diff --git a/.claude/skills/store-screenshots/SKILL.md b/.claude/skills/store-screenshots/SKILL.md
new file mode 100644
index 0000000000..f0c319dd05
--- /dev/null
+++ b/.claude/skills/store-screenshots/SKILL.md
@@ -0,0 +1,19 @@
+---
+name: store-screenshots
+description: Refresh the App Store and Google Play screenshots for phones and tablets. Use when the user says "store screenshots", "app store screenshots", "play store screenshots", "iPad screenshots", "recapture the screenshots", or wants the store panels changed.
+user-invocable: true
+---
+
+# Store screenshots
+
+Follow `assets/store-screenshots/README.md`. It owns the panels, the creative direction, the render command and the recapture steps. Change copy, crops and layout in `assets/store-screenshots/render.mjs`, not in the exports.
+
+Working rules:
+
+- Capture at native density: `--pixel-density 3` on the iPhone 16 Pro Max, `--pixel-density 2` on the iPad Pro 13-inch. The default is 1x, which is too soft for the store.
+- Every headline wraps to two lines and every subline fits on one. The renderer enforces this; rewrite the copy rather than shrink the type.
+- Use SF Pro. Never substitute another font.
+- Open `output/preview.png` and a full-size panel from each store before you report a render. Show the user the preview.
+- Do not upload screenshots to a store, a PR, or anywhere public, and do not commit, unless the user asks.
+- Stage the demo host on its own port and pick a free Metro port. Do not restart the main daemons.
+- When you learn something the next capture needs, fix the README rather than this skill.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e632cb4b96..285ff8e072 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -3,7 +3,7 @@ name: CI
 on:
   push:
     branches: [main]
-  # Every base branch, so stacked PRs and PRs into `next` get the same checks.
+  # Every base branch, so stacked PRs and PRs into any base get the same checks.
   pull_request:
   merge_group:
   workflow_dispatch:
@@ -133,11 +133,12 @@ jobs:
         if: ${{ !cancelled() && steps.install.outcome == 'success' && (needs.changes.outputs.full != 'false' || needs.changes.outputs.sdk != 'false') }}
         run: npm run typecheck:examples --workspace=@getpaseo/client
 
+  # The locked Playwright installers do not support ubuntu-latest's Ubuntu 26.04.
   typecheck:
     name: typecheck
     needs: changes
     if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.quality != 'false') }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
 
@@ -280,10 +281,10 @@ jobs:
   # otherwise has no server-test coverage. Scoped to the observer/watcher suites to
   # bound runtime.
   server-tests-macos:
-    name: server-tests (macos-14, file observation)
+    name: server-tests (macos-latest, file observation)
     needs: changes
     if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.server != 'false') }}
-    runs-on: macos-14
+    runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4
 
@@ -395,7 +396,7 @@ jobs:
     name: app-tests
     needs: changes
     if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.app != 'false') }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
 
@@ -417,19 +418,11 @@ jobs:
       - name: Run app unit tests
         run: npm run test --workspace=@getpaseo/app
 
-      - uses: actions/setup-java@v4
-        with:
-          distribution: temurin
-          java-version: "21"
-
-      - name: Run Android module tests
-        run: npm run test:android --workspace=@getpaseo/app
-
   playwright-1:
     name: playwright (shard 1/8)
     needs: changes
     if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     env:
       PLAYWRIGHT_SHARD: "1/8"
       PLAYWRIGHT_ARTIFACT: "1"
@@ -485,7 +478,7 @@ jobs:
     name: playwright (shard 2/8)
     needs: changes
     if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     env:
       PLAYWRIGHT_SHARD: "2/8"
       PLAYWRIGHT_ARTIFACT: "2"
@@ -495,7 +488,7 @@ jobs:
     name: playwright (shard 3/8)
     needs: changes
     if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     env:
       PLAYWRIGHT_SHARD: "3/8"
       PLAYWRIGHT_ARTIFACT: "3"
@@ -505,7 +498,7 @@ jobs:
     name: playwright (shard 4/8)
     needs: changes
     if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     env:
       PLAYWRIGHT_SHARD: "4/8"
       PLAYWRIGHT_ARTIFACT: "4"
@@ -515,7 +508,7 @@ jobs:
     name: playwright (shard 5/8)
     needs: changes
     if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     env:
       PLAYWRIGHT_SHARD: "5/8"
       PLAYWRIGHT_ARTIFACT: "5"
@@ -525,7 +518,7 @@ jobs:
     name: playwright (shard 6/8)
     needs: changes
     if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     env:
       PLAYWRIGHT_SHARD: "6/8"
       PLAYWRIGHT_ARTIFACT: "6"
@@ -535,7 +528,7 @@ jobs:
     name: playwright (shard 7/8)
     needs: changes
     if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     env:
       PLAYWRIGHT_SHARD: "7/8"
       PLAYWRIGHT_ARTIFACT: "7"
@@ -545,7 +538,7 @@ jobs:
     name: playwright (shard 8/8)
     needs: changes
     if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     env:
       PLAYWRIGHT_SHARD: "8/8"
       PLAYWRIGHT_ARTIFACT: "8"
diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml
index d81c036e62..26be12291b 100644
--- a/.github/workflows/desktop-release.yml
+++ b/.github/workflows/desktop-release.yml
@@ -100,10 +100,10 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - runner: macos-14
+          - runner: macos-latest
             electron_arch: arm64
             node_heap_mb: 4096
-          - runner: macos-15-intel
+          - runner: macos-26-intel
             electron_arch: x64
             node_heap_mb: 8192
     permissions:
diff --git a/.github/workflows/nix.yml b/.github/workflows/nix.yml
index f37a8b0cdf..b653564793 100644
--- a/.github/workflows/nix.yml
+++ b/.github/workflows/nix.yml
@@ -101,7 +101,7 @@ jobs:
         run: nix build .#desktop -o result-desktop
 
   build-desktop-darwin:
-    runs-on: macos-14
+    runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4
 
diff --git a/.oxlintrc.json b/.oxlintrc.json
index f5078649c9..ae335c0e48 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -85,6 +85,176 @@
     "max-nested-callbacks": ["error", { "max": 3 }]
   },
   "overrides": [
+    // Exceptions name individual APIs in individual modules; new APIs still fail in these files.
+    // TODO entries are runtime debt, not startup exemptions. Do not add directory-wide exceptions.
+    {
+      "files": ["packages/server/src/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
+      "rules": {
+        "paseo/no-sync-io": [
+          "error",
+          {
+            "allow": {
+              // TODO: literal executableExists is a synchronous public capability; move its callers and Windows existence predicates to async together.
+              "executable-resolution/executable-resolution.ts": ["existsSync"],
+              // TODO: winget enumeration shares synchronous existence predicates with literal lookup; convert the executable-resolution boundary together.
+              "executable-resolution/windows.ts": ["readdirSync"],
+              // TODO: live file-change classification is a synchronous event mapper; move the probe to async event ingestion.
+              "server/agent/providers/claude/agent.ts": ["existsSync"],
+              // TODO: new-session construction still resolves its project directory synchronously; move preparation before construction.
+              "server/agent/providers/claude/project-dir.ts": ["realpathSync"],
+              // TODO: live subagent output is read by a synchronous event mapper; add bounded async loading at ingestion.
+              "server/agent/providers/claude/subagents/workflow-output.ts": [
+                "closeSync",
+                "openSync",
+                "readSync"
+              ],
+              // TODO: diagnostics probes provider-owned auth/session storage; convert alongside provider discovery and readiness.
+              "server/agent/providers/omp/agent.ts": ["existsSync"],
+              // TODO: synchronous provider configuration discovery; move discovery into async launch preparation.
+              "server/agent/providers/omp/provider-config.ts": ["existsSync"],
+              // TODO: synchronous session-root selection is shared by descriptor builders; migrate callers with explicit readiness.
+              "server/agent/providers/omp/session-descriptor.ts": ["existsSync"],
+              // TODO: launch directory creation shares the server generation/start state machine; audit concurrent rotation before adding an await.
+              "server/agent/providers/opencode/server-manager.ts": ["mkdirSync"],
+              // TODO: launch preparation owns MCP config merge, extension generation and synchronous cleanup; migrate lifecycle and diagnostics together.
+              "server/agent/providers/pi/agent.ts": [
+                "existsSync",
+                "mkdtempSync",
+                "readFileSync",
+                "rmSync",
+                "writeFileSync"
+              ],
+              // Provider child process: Pi loads this extension outside the daemon; it reads child-agent status there.
+              "server/agent/providers/pi/extensions/pi-subagents/index.ts": ["readFileSync"],
+              // Startup/shutdown only: remove stale Unix listening sockets before bind and during disposal.
+              "server/bootstrap.ts": ["existsSync", "unlinkSync"],
+              // Startup configuration resolution: detect the bundled app distribution before the daemon listens.
+              "server/config.ts": ["existsSync"],
+              // Startup identity: load or create the daemon keypair before accepting connections.
+              "server/daemon-keypair.ts": ["existsSync", "readFileSync"],
+              // Fatal exit diagnostics: synchronously flush the exit reason when the worker is about to terminate.
+              "server/daemon-worker.ts": ["appendFileSync", "mkdirSync"],
+              // Startup host identity: memoized scutil lookup is warmed before listening; later callers use the cache.
+              "server/host-name.ts": ["execFileSync"],
+              // TODO: relationship persistence is atomic with enrollment/revocation state transitions; serialize those transitions before async writes.
+              "server/hub/relationship-controller.ts": [
+                "existsSync",
+                "readFileSync",
+                "renameSync",
+                "rmSync"
+              ],
+              // Local client bootstrap: reads the local credential and pid lock to select/authenticate a daemon connection.
+              "server/local-credential.ts": ["readFileSync"],
+              // Startup logger construction: create the log directory before opening the logging destination.
+              "server/logger.ts": ["mkdirSync"],
+              // TODO: runtime skill commands resolve their bundled source through a synchronous targets capability; migrate the capability and controller together.
+              "server/orchestration-skills/internal/paths.ts": ["existsSync"],
+              // Module initialization: the package version is resolved once and cached at import.
+              "server/package-version.ts": ["existsSync", "readFileSync"],
+              // Startup config and exported synchronous configuration API; runtime DaemonConfigStore uses the async load/save capabilities.
+              "server/persisted-config.ts": ["existsSync", "readFileSync"],
+              // Startup pid identity: read and memoize the Linux boot id for the daemon lock.
+              "server/pid-lock.ts": ["readFileSync"],
+              // Startup builtin loader construction: select the bundled plugin root before loading plugins.
+              "server/plugins/builtin/index.ts": ["existsSync"],
+              // Build child process: plugin graph traversal and esbuild preparation run in the isolated compiler process.
+              "server/plugins/compiler-build.ts": ["existsSync", "readFileSync", "realpathSync"],
+              // Build child process: select the esbuild binary for the isolated plugin compiler.
+              "server/plugins/compiler-esbuild.ts": ["existsSync"],
+              // Build child process: TypeScript resolution and source reads run in the isolated plugin compiler.
+              "server/plugins/compiler-imports.ts": ["readFileSync", "realpathSync"],
+              // TODO: plugin install/update/remove commits sources.json synchronously; preserve record/write ordering with an async mutation queue.
+              "server/plugins/managed-source.ts": ["existsSync", "readFileSync"],
+              // TODO: shared synchronous persistence supports startup identity plus Hub/plugin/push runtime writers; migrate those owners before removing these exports.
+              "server/private-files.ts": [
+                "chmodSync",
+                "mkdirSync",
+                "realpathSync",
+                "renameSync",
+                "rmSync",
+                "writeFileSync"
+              ],
+              // TODO: constructor load plus runtime renew/revoke/prune use synchronous persistence; introduce ordered async mutations and readiness.
+              "server/push/token-store.ts": ["existsSync", "readFileSync"],
+              // Startup identity: load or create the server id before accepting connections.
+              "server/server-id.ts": ["existsSync", "readFileSync"],
+              // Listener lifecycle only: unlink the Unix socket before binding or after stopping the proxy.
+              "server/service-proxy.ts": ["existsSync", "unlinkSync"],
+              // TODO: self-update origin validation exposes synchronous package-root and realpath checks; migrate validation and its runtime interface together.
+              "server/session/daemon/install-origin.ts": ["existsSync", "readFileSync"],
+              // TODO: npm self-update inspection probes the reported install path; move the probe into bounded async installation inspection.
+              "server/session/daemon/npm-global-cli.ts": ["lstatSync"],
+              // Speech child process: model-file validation runs in the worker-backed local speech provider.
+              "server/speech/providers/local/sherpa/sherpa-offline-recognizer.ts": ["existsSync"],
+              // Speech child process: native addon discovery and patchelf run outside the daemon.
+              "server/speech/providers/local/sherpa/sherpa-onnx-node-loader.ts": [
+                "existsSync",
+                "spawnSync"
+              ],
+              // Speech child process: model-file validation runs in the worker-backed local speech provider.
+              "server/speech/providers/local/sherpa/sherpa-tts.ts": ["existsSync"],
+              // TODO: static request selection and index injection need bounded async serving with response/error ownership; keep this as a separate request-path conversion.
+              "server/web-ui.ts": ["readFileSync", "statSync"],
+              // Startup registry hydration: check persisted workspace directories before the runtime reconciliation service starts.
+              "server/workspace-registry-bootstrap.ts": ["statSync"],
+              // Terminal child process: hook config installation/removal is owned by terminal creation and teardown in the worker.
+              "terminal/agent-hooks/agent-hook-installer.ts": [
+                "existsSync",
+                "readFileSync",
+                "rmSync"
+              ],
+              // Terminal child process: launcher readiness and PTY record ownership run outside the daemon.
+              "terminal/terminal-worker-process.ts": [
+                "chmodSync",
+                "closeSync",
+                "existsSync",
+                "openSync",
+                "rmSync",
+                "writeSync"
+              ],
+              // Worker startup only: choose and secure the local listening socket before accepting a controller.
+              "terminal/terminal-worker-socket-path.ts": ["lstatSync", "mkdirSync"],
+              // Startup only: build an independent worker installation before launching; Electron ASAR sources require plain fs reads.
+              "terminal/terminal-worker-runtime.ts": [
+                "chmodSync",
+                "existsSync",
+                "mkdirSync",
+                "readdirSync",
+                "readFileSync",
+                "renameSync",
+                "rmSync",
+                "statSync",
+                "writeFileSync"
+              ],
+              // TODO: CLI shim lookup moved out of terminal.ts; migrate the executable-resolution boundary together.
+              "terminal/paseo-cli-path.ts": ["existsSync"],
+              // Node loader thread: TypeScript terminal-worker resolution runs in the loader, outside the daemon event loop.
+              "terminal/terminal-ts-loader.mjs": ["existsSync"],
+              // Terminal child process: executable preparation and shell integration run in the worker-backed terminal manager.
+              "terminal/terminal.ts": [
+                "accessSync",
+                "chmodSync",
+                "existsSync",
+                "mkdirSync",
+                "readFileSync",
+                "statSync"
+              ],
+              // TODO: legacy realpath helpers still serve install-origin validation and other synchronous consumers; migrate remaining callers before removing them.
+              "utils/path.ts": ["realpathSync"]
+            }
+          }
+        ]
+      }
+    },
+    {
+      "files": [
+        "packages/server/src/**/*.{test,spec,fixture}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
+        "packages/server/src/**/test-utils/**",
+        "packages/server/src/server/daemon-e2e/**",
+        "packages/server/src/server/agent/providers/pi/extensions/*-test.ts"
+      ],
+      "rules": { "paseo/no-sync-io": "off" }
+    },
     {
       "files": [
         "plugins/*-provider/server/**/*.ts",
@@ -236,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",
@@ -258,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",
@@ -373,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 98d1c76900..fee6f2395e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,175 @@
 # Changelog
 
+## 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
+
+Plugins can now add tools to individual agents and configure their MCP servers when sessions open.
+
+Completed conversation turns can be collapsed into summaries and expanded to read the full exchange.
+
+Voice settings now let you configure speech providers and download local models with one tap, including SenseVoice and Whisper for Chinese dictation. Voice mode is now opt-in.
+
+### Added
+
+- Let plugins give tools to specific agents ([#7938](https://github.com/getpaseo/paseo/pull/7938))
+- Added Chat display settings that group tool calls or collapse completed conversation turns ([#7785](https://github.com/getpaseo/paseo/pull/7785), [#7990](https://github.com/getpaseo/paseo/pull/7990), [#8026](https://github.com/getpaseo/paseo/pull/8026), [#8042](https://github.com/getpaseo/paseo/pull/8042), [#8109](https://github.com/getpaseo/paseo/pull/8109) by [@akaready](https://github.com/akaready), [@Dey11](https://github.com/Dey11), [@Sebeb](https://github.com/Sebeb), [@Waishnav](https://github.com/Waishnav))
+- Let plugins add MCP servers whenever an agent session opens ([#7983](https://github.com/getpaseo/paseo/pull/7983))
+- Added downloadable local speech models in Voice settings, including SenseVoice and Whisper for Chinese dictation ([#7295](https://github.com/getpaseo/paseo/pull/7295))
+- Added a choice of Enter or ⌘/Ctrl+Enter to send messages ([#5503](https://github.com/getpaseo/paseo/pull/5503) by [@lukelabonte](https://github.com/lukelabonte))
+- Added sent-message recall with Up and Down in an empty web or desktop Composer ([#7710](https://github.com/getpaseo/paseo/pull/7710))
+- Added long-press Send to queue a message or send it immediately ([#7897](https://github.com/getpaseo/paseo/pull/7897) by [@bjspi](https://github.com/bjspi))
+- Added project-specific editor choices, including Xcode on macOS ([#7898](https://github.com/getpaseo/paseo/pull/7898) by [@kinoroy](https://github.com/kinoroy))
+
+### Improved
+
+- Release eligible agent runtimes after one idle hour, resuming the saved session on the next prompt ([#7782](https://github.com/getpaseo/paseo/pull/7782))
+- Added a link back to the parent in subagent panes ([#7784](https://github.com/getpaseo/paseo/pull/7784))
+- Opened subagents in place of the subagent list on phones, with Back returning to the list ([#8093](https://github.com/getpaseo/paseo/pull/8093))
+- Added clickable links and selectable descriptions to question cards ([#7419](https://github.com/getpaseo/paseo/pull/7419) by [@NoSync](https://github.com/NoSync))
+- Kept large Import session lists responsive on web ([#7872](https://github.com/getpaseo/paseo/pull/7872) by [@royenheart](https://github.com/royenheart))
+- Enlarged project and workspace menu buttons on phones ([#7928](https://github.com/getpaseo/paseo/pull/7928))
+- Stopped hidden chats from rendering incoming text updates ([#7901](https://github.com/getpaseo/paseo/pull/7901))
+- Reduced stalls when highlighting and wrapping large diffs ([#8006](https://github.com/getpaseo/paseo/pull/8006), [#7945](https://github.com/getpaseo/paseo/pull/7945))
+- Reduced daemon stalls when opening and paging large Claude and OMP histories ([#7789](https://github.com/getpaseo/paseo/pull/7789), [#7940](https://github.com/getpaseo/paseo/pull/7940), [#7948](https://github.com/getpaseo/paseo/pull/7948), [#7958](https://github.com/getpaseo/paseo/pull/7958) by [@ragokan](https://github.com/ragokan))
+- Reduced daemon stalls during plugin builds, image processing and config reloads ([#7967](https://github.com/getpaseo/paseo/pull/7967), [#7954](https://github.com/getpaseo/paseo/pull/7954), [#7959](https://github.com/getpaseo/paseo/pull/7959))
+- Reduced blocking filesystem work during workspace and project refreshes ([#7941](https://github.com/getpaseo/paseo/pull/7941), [#7943](https://github.com/getpaseo/paseo/pull/7943), [#7944](https://github.com/getpaseo/paseo/pull/7944))
+
+### Fixed
+
+- Fixed terminal glyph corruption when shared WebGL texture atlases change ([#8013](https://github.com/getpaseo/paseo/pull/8013) by [@donghyeonan](https://github.com/donghyeonan))
+- Fixed restored workspaces with no open chat staying on Loading workspace at launch on phones ([#7918](https://github.com/getpaseo/paseo/pull/7918))
+- Fixed restored agent tabs appearing in unrelated workspaces ([#7956](https://github.com/getpaseo/paseo/pull/7956) by [@odoo-mvds](https://github.com/odoo-mvds))
+- Fixed background Git fetches opening credential prompts ([#8019](https://github.com/getpaseo/paseo/pull/8019))
+- Fixed failed SSH tunnels crashing callers with an unhandled EPIPE ([#7876](https://github.com/getpaseo/paseo/pull/7876))
+- Fixed brief Windows file locks preventing atomic saves ([#7955](https://github.com/getpaseo/paseo/pull/7955))
+- Fixed large ACP terminal output blocking daemon requests ([#7953](https://github.com/getpaseo/paseo/pull/7953) by [@bbtfr](https://github.com/bbtfr))
+- Fixed messages sent during Pi manual compaction failing instead of waiting ([#7848](https://github.com/getpaseo/paseo/pull/7848) by [@itssimon](https://github.com/itssimon))
+- Fixed late tool updates creating duplicate rows during overlapping turns ([#8010](https://github.com/getpaseo/paseo/pull/8010) by [@luoph](https://github.com/luoph))
+- Fixed plugin ACP reasoning appearing inside assistant replies when message IDs match ([#7272](https://github.com/getpaseo/paseo/pull/7272) by [@cncolder](https://github.com/cncolder))
+- Fixed outside-folder links replacing Files with an access error ([#7726](https://github.com/getpaseo/paseo/pull/7726) by [@jtomaszewski](https://github.com/jtomaszewski))
+- Fixed command suggestions overlapping a growing Composer on phones ([#7910](https://github.com/getpaseo/paseo/pull/7910))
+- Fixed bare Markdown URLs losing ports or stopping at colons in paths ([#7859](https://github.com/getpaseo/paseo/pull/7859) by [@mariotaku](https://github.com/mariotaku))
+- Fixed inline code sizing inside emphasis, links and headings ([#7889](https://github.com/getpaseo/paseo/pull/7889), [#8088](https://github.com/getpaseo/paseo/pull/8088))
+- Fixed compact navigation sizes and a cramped Settings detail pane in docked windows 600–719 wide ([#8052](https://github.com/getpaseo/paseo/pull/8052) by [@zeyugao](https://github.com/zeyugao))
+- Fixed Settings losing the selected host or sidebar scroll position between sections ([#7893](https://github.com/getpaseo/paseo/pull/7893), [#7899](https://github.com/getpaseo/paseo/pull/7899) by [@bingqilinweimaotai](https://github.com/bingqilinweimaotai), [@wangnan0916](https://github.com/wangnan0916))
+- Fixed OpenCode v2 subagent rows missing model and token details ([#7799](https://github.com/getpaseo/paseo/pull/7799) by [@Davnn1](https://github.com/Davnn1))
+- Fixed file-link tooltips staying over the preview after leaving a chat ([#7842](https://github.com/getpaseo/paseo/pull/7842))
+- Fixed model discovery errors touching the model picker edges ([#8039](https://github.com/getpaseo/paseo/pull/8039) by [@ilteoood](https://github.com/ilteoood))
+- Fixed model selectors staying open over Settings ([#7783](https://github.com/getpaseo/paseo/pull/7783) by [@ragokan](https://github.com/ragokan))
+
+### Notes
+
+- Voice mode now defaults to off; enable it in Voice settings
+- If environment variables select OpenAI speech, move keys and endpoints stored only in legacy `providers.openai` into Voice settings
+- Before downgrading to 0.13.2, restore a backed-up `config.json` or convert speech credentials and idle-cleanup settings saved by 0.14.0
+- Install the optional [Claude Code entrypoint plugin](https://paseo.sh/plugins/getpaseo/claude-code-entrypoint-env) to launch Claude sessions with `CLAUDE_CODE_ENTRYPOINT=Paseo`, a community workaround for subscription limits draining faster ([#7976](https://github.com/getpaseo/paseo/pull/7976), [#8164](https://github.com/getpaseo/paseo/pull/8164) by [@david828019-oss](https://github.com/david828019-oss))
+
 ## 0.13.2 - 2026-10-26
 
 ### Fixed
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index 421da176dd..5a0265ae15 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -1,4 +1,174 @@
-# 更新日志
+# Changelog
+
+## 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
+
+插件现在可以为单个 Agent 添加工具，并在会话打开时配置其 MCP 服务器。
+
+已完成的对话轮次可以折叠为摘要，也可以展开查看完整对话。
+
+语音设置现在支持配置语音服务商并一键下载本地模型，包括可用于中文听写的 SenseVoice 和 Whisper。语音模式现在需要主动开启。
+
+### 新增
+
+- 插件现在可以为特定 Agent 提供工具 ([#7938](https://github.com/getpaseo/paseo/pull/7938))
+- 新增“聊天显示”设置，可将工具调用分组或折叠已完成的对话轮次 ([#7785](https://github.com/getpaseo/paseo/pull/7785), [#7990](https://github.com/getpaseo/paseo/pull/7990), [#8026](https://github.com/getpaseo/paseo/pull/8026), [#8042](https://github.com/getpaseo/paseo/pull/8042), [#8109](https://github.com/getpaseo/paseo/pull/8109) by [@akaready](https://github.com/akaready), [@Dey11](https://github.com/Dey11), [@Sebeb](https://github.com/Sebeb), [@Waishnav](https://github.com/Waishnav))
+- 插件现在可以在每次打开 Agent 会话时添加 MCP 服务器 ([#7983](https://github.com/getpaseo/paseo/pull/7983))
+- 语音设置新增可下载的本地语音模型，支持使用 SenseVoice 和 Whisper 进行中文听写 ([#7295](https://github.com/getpaseo/paseo/pull/7295))
+- 新增 Enter 或 ⌘/Ctrl+Enter 发送消息的快捷键选项 ([#5503](https://github.com/getpaseo/paseo/pull/5503) by [@lukelabonte](https://github.com/lukelabonte))
+- 新增在网页和桌面端的空 Composer 中按上下键回顾已发送消息 ([#7710](https://github.com/getpaseo/paseo/pull/7710))
+- 新增长按发送按钮排队发送或立即发送消息 ([#7897](https://github.com/getpaseo/paseo/pull/7897) by [@bjspi](https://github.com/bjspi))
+- 新增按项目记忆编辑器的功能，macOS 支持 Xcode ([#7898](https://github.com/getpaseo/paseo/pull/7898) by [@kinoroy](https://github.com/kinoroy))
+
+### 改进
+
+- 符合条件的 Agent 运行时空闲一小时后释放，下次发送提示词时恢复已保存的会话 ([#7782](https://github.com/getpaseo/paseo/pull/7782))
+- 在子 Agent 窗格中新增返回父 Agent 的链接 ([#7784](https://github.com/getpaseo/paseo/pull/7784))
+- 在手机上从子 Agent 列表打开子 Agent 时直接替换列表，点按“返回”可回到列表 ([#8093](https://github.com/getpaseo/paseo/pull/8093))
+- 问题卡片新增可点击链接和可选中的描述文本 ([#7419](https://github.com/getpaseo/paseo/pull/7419) by [@NoSync](https://github.com/NoSync))
+- 减少网页端长会话导入列表的操作卡顿 ([#7872](https://github.com/getpaseo/paseo/pull/7872) by [@royenheart](https://github.com/royenheart))
+- 增大手机上项目和工作区菜单按钮的点击区域 ([#7928](https://github.com/getpaseo/paseo/pull/7928))
+- 隐藏的聊天不再渲染收到的文本更新 ([#7901](https://github.com/getpaseo/paseo/pull/7901))
+- 减少大型 diff 高亮和自动换行时的卡顿 ([#8006](https://github.com/getpaseo/paseo/pull/8006), [#7945](https://github.com/getpaseo/paseo/pull/7945))
+- 减少打开和分页加载大型 Claude 和 OMP 历史时的 daemon 卡顿 ([#7789](https://github.com/getpaseo/paseo/pull/7789), [#7940](https://github.com/getpaseo/paseo/pull/7940), [#7948](https://github.com/getpaseo/paseo/pull/7948), [#7958](https://github.com/getpaseo/paseo/pull/7958) by [@ragokan](https://github.com/ragokan))
+- 减少插件构建、图片处理和重新加载配置时的 daemon 卡顿 ([#7967](https://github.com/getpaseo/paseo/pull/7967), [#7954](https://github.com/getpaseo/paseo/pull/7954), [#7959](https://github.com/getpaseo/paseo/pull/7959))
+- 减少刷新工作区和项目时由文件系统操作造成的阻塞 ([#7941](https://github.com/getpaseo/paseo/pull/7941), [#7943](https://github.com/getpaseo/paseo/pull/7943), [#7944](https://github.com/getpaseo/paseo/pull/7944))
+
+### 修复
+
+- 修复共享 WebGL 纹理图集变化时终端字符显示错误的问题 ([#8013](https://github.com/getpaseo/paseo/pull/8013) by [@donghyeonan](https://github.com/donghyeonan))
+- 修复手机启动时没有打开聊天的已恢复工作区停留在加载状态的问题 ([#7918](https://github.com/getpaseo/paseo/pull/7918))
+- 修复已恢复的 Agent 标签出现在无关工作区中的问题 ([#7956](https://github.com/getpaseo/paseo/pull/7956) by [@odoo-mvds](https://github.com/odoo-mvds))
+- 修复后台 Git 拉取弹出凭据提示的问题 ([#8019](https://github.com/getpaseo/paseo/pull/8019))
+- 修复 SSH 隧道失败时未处理的 EPIPE 导致调用方崩溃的问题 ([#7876](https://github.com/getpaseo/paseo/pull/7876))
+- 修复 Windows 短暂文件锁导致原子保存失败的问题 ([#7955](https://github.com/getpaseo/paseo/pull/7955))
+- 修复 ACP 终端产生大量输出时阻塞 daemon 的问题 ([#7953](https://github.com/getpaseo/paseo/pull/7953) by [@bbtfr](https://github.com/bbtfr))
+- 修复 Pi 手动压缩上下文期间发送消息直接失败而不等待的问题 ([#7848](https://github.com/getpaseo/paseo/pull/7848) by [@itssimon](https://github.com/itssimon))
+- 修复轮次重叠时较晚的工具更新产生重复行的问题 ([#8010](https://github.com/getpaseo/paseo/pull/8010) by [@luoph](https://github.com/luoph))
+- 修复插件 ACP 推理和回复的消息 ID 相同时，推理内容混入回复的问题 ([#7272](https://github.com/getpaseo/paseo/pull/7272) by [@cncolder](https://github.com/cncolder))
+- 修复工作区外的文件夹链接使 Files 显示访问错误的问题 ([#7726](https://github.com/getpaseo/paseo/pull/7726) by [@jtomaszewski](https://github.com/jtomaszewski))
+- 修复手机上命令建议与不断增高的 Composer 重叠的问题 ([#7910](https://github.com/getpaseo/paseo/pull/7910))
+- 修复 Markdown 裸链接丢失端口或在路径冒号处截断的问题 ([#7859](https://github.com/getpaseo/paseo/pull/7859) by [@mariotaku](https://github.com/mariotaku))
+- 修复强调、链接和标题中行内代码的字号问题 ([#7889](https://github.com/getpaseo/paseo/pull/7889), [#8088](https://github.com/getpaseo/paseo/pull/8088))
+- 修复宽度 600–719 的停靠布局使用紧凑导航尺寸、设置详情面板过窄的问题 ([#8052](https://github.com/getpaseo/paseo/pull/8052) by [@zeyugao](https://github.com/zeyugao))
+- 修复切换设置页面时丢失已选主机或侧栏滚动位置的问题 ([#7893](https://github.com/getpaseo/paseo/pull/7893), [#7899](https://github.com/getpaseo/paseo/pull/7899) by [@bingqilinweimaotai](https://github.com/bingqilinweimaotai), [@wangnan0916](https://github.com/wangnan0916))
+- 修复 OpenCode v2 子 Agent 行缺少模型和 token 详情的问题 ([#7799](https://github.com/getpaseo/paseo/pull/7799) by [@Davnn1](https://github.com/Davnn1))
+- 修复离开聊天后文件链接提示仍遮挡预览的问题 ([#7842](https://github.com/getpaseo/paseo/pull/7842))
+- 修复模型发现错误信息紧贴模型选择器边缘的问题 ([#8039](https://github.com/getpaseo/paseo/pull/8039) by [@ilteoood](https://github.com/ilteoood))
+- 修复模型选择器在打开设置后仍然显示的问题 ([#7783](https://github.com/getpaseo/paseo/pull/7783) by [@ragokan](https://github.com/ragokan))
+
+### 说明
+
+- 语音模式默认关闭，可在语音设置中启用
+- 如果通过环境变量选择 OpenAI 语音，请将仅保存在旧版 `providers.openai` 中的密钥和服务地址移至语音设置
+- 降级至 0.13.2 前，请恢复备份的 `config.json` 或转换 0.14.0 保存的语音凭据和空闲清理设置
+- 安装可选的 [Claude Code entrypoint 插件](https://paseo.sh/plugins/getpaseo/claude-code-entrypoint-env)，即可使用 `CLAUDE_CODE_ENTRYPOINT=Paseo` 启动 Claude 会话；这是针对订阅额度消耗过快问题的社区变通方案 ([#7976](https://github.com/getpaseo/paseo/pull/7976), [#8164](https://github.com/getpaseo/paseo/pull/8164) by [@david828019-oss](https://github.com/david828019-oss))
 
 ## 0.13.2 - 2026-10-26
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 3f1731597c..1496bd407b 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                                 |
@@ -52,7 +53,9 @@ At the start of non-trivial work, list `docs/` and skim anything relevant to the
 | [docs/connected-hosts.md](docs/connected-hosts.md)                   | Daemon-owned host registrations, routed SDK scopes, identity and authority boundaries                                          |
 | [docs/permissions.md](docs/permissions.md)                           | Semantic daemon permissions, principals, credentials, pairing invitations, and Hub authority                                   |
 | [docs/terminal-performance.md](docs/terminal-performance.md)         | Terminal latency pipeline, coalescing/backpressure invariants, benchmark + perf spec usage                                     |
+| [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/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                                     |
@@ -66,6 +69,7 @@ At the start of non-trivial work, list `docs/` and skim anything relevant to the
 | [docs/android.md](docs/android.md)                                   | App variants, local/cloud builds, EAS workflows, version codes, F-Droid source builds and store metadata                       |
 | [docs/docker.md](docs/docker.md)                                     | Running the daemon and bundled web UI in Docker, volumes, agent images, security                                               |
 | [docs/release.md](docs/release.md)                                   | Release playbook, draft releases, completion checklist                                                                         |
+| [docs/terminal-worker.md](docs/terminal-worker.md)                   | Terminal worker process model, socket/record/secret, protocol-bump rule and draining, the worker's file copy, Windows desktop  |
 | [docs/terminal-activity.md](docs/terminal-activity.md)               | Terminal activity indicators — source-agnostic tracker, agent hook reporting, adding a new hook provider                       |
 | [SECURITY.md](SECURITY.md)                                           | Relay threat model, E2E encryption, DNS rebinding, agent auth                                                                  |
 | [public-docs/hub/security.md](public-docs/hub/security.md)           | Public Hub guide — trust boundaries, untrusted triggers, provider controls, and output authority                               |
@@ -116,10 +120,9 @@ See [docs/development.md](docs/development.md) for full setup, build sync requir
 
 ## Release branches
 
-When the user says "this goes to next", create or
-retarget the PR to `next` and preserve that destination through delivery. Follow
-[release branch discipline](docs/release.md#release-branch-discipline) for creating
-and updating `next`, integrating it after a release, and releasing a hotfix from a tag.
+Merge normal PRs into `main`, including while a beta soaks or a release is being finalized. Each
+release builds in a short-lived release workspace from `origin/main` or a release tag; see
+[release base and source](docs/release.md#release-base-and-source).
 
 ## Critical rules
 
diff --git a/assets/store-screenshots/.gitignore b/assets/store-screenshots/.gitignore
new file mode 100644
index 0000000000..22908c2c7d
--- /dev/null
+++ b/assets/store-screenshots/.gitignore
@@ -0,0 +1 @@
+output/preview.png
diff --git a/assets/store-screenshots/README.md b/assets/store-screenshots/README.md
new file mode 100644
index 0000000000..fc37d98bd8
--- /dev/null
+++ b/assets/store-screenshots/README.md
@@ -0,0 +1,102 @@
+# Store screenshots
+
+Five panels for the App Store and Google Play, in phone and tablet sets, made from native captures of the real app. Both sets tell the same story with the same copy; only the capture, the device frame and the callouts change.
+
+| #   | Headline                                | Capture                                                                | Phone callout                                | Tablet callout                        |
+| --- | --------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------- |
+| 1   | Run many coding agents at once          | Sidebar grouped by status: Needs input, Ready to review, Working, Done | — (agent marks in the background)            | — (agent marks in the background)     |
+| 2   | Your full dev environment on your phone | Agent chat: reasoning, tool calls, final summary                       | —                                            | — (Changes pane open beside the chat) |
+| 3   | Ask an agent to change the app itself   | A chat asking for a plugin, the turn collapsed, the new Deploys pill   | The plugin's Preview deploys sheet           | The plugin's Deploys popover          |
+| 4   | Review the diff before you merge        | `daemon-client.ts` diff with removed and added lines                   | Jump to file: four changed files with counts | — (the full-width diff reads as is)   |
+| 5   | A real terminal in every workspace      | `git status` and a vitest run in the same worktree                     | The passing test tree                        | The passing test tree                 |
+
+On tablets, panel 2 says "on your tablet" and panel 3 calls the popover a panel. A scene overrides its copy per device in `render.mjs`.
+
+## Creative direction
+
+The panels follow paseo.sh:
+
+- **Canvas:** the site's `#101615` background.
+- **Type:** centred SF Pro headlines in sentence case, with no closing period. Every headline wraps to exactly two lines.
+- **Sublines:** one plain grey sentence on one line that says what you can do. The renderer fails if a headline or subline wraps differently, because the device is placed from that fixed text height.
+- **Agent marks:** panel 1 scatters faded, rotated, monochrome marks of the agents featured on the homepage behind the device. They are rendered from `packages/website/src/components/agent-icons.tsx`, so they follow the site.
+- **Device:** dark-mode captures in a plain black frame; the iPhone frame has a Dynamic Island. The device starts a fixed gap below the text and runs just off the bottom edge, so a taller canvas gets a larger device instead of a larger gap. A canvas too narrow for that, like a 3:4 iPad on Google's 9:16 tablet canvas, shows the whole device at full width with the text and device centred.
+- **Callouts:** a callout lifts one region of a capture out of the device, larger than the device around it, so the detail reads at store thumbnail size. On tablets, place callouts over empty screen so they do not hide the context they explain.
+
+Everything on screen is real app UI showing one story. The hero agent adds jitter to the reconnect backoff in this repository. Its diff, test run and terminal come from a real worktree. The other workspaces fill the sidebar's status groups.
+
+Panel 3 shows a real plugin. `demo/preview-deploys/` is a trusted local plugin that adds a Deploys composer pill; its popover opens as a sheet on phones and as a popover on tablets. The deploys it lists are sample data. The demo host installs it, and a scripted agent in the "Build a preview deploys plugin" workspace plays the turn that writes it.
+
+## Files
+
+- `raw/iphone/`: native 1320 × 2868 captures from an iPhone 16 Pro Max simulator. `files.png` and `plugin-sheet.png` are the sources for the Jump to file and Preview deploys callouts.
+- `raw/ipad/`: native 2064 × 2752 captures from an iPad Pro 13-inch (M4) simulator. `plugin-sheet.png` is the source for the Deploys popover callout.
+- `render.mjs`: the layout, copy and callout crops. Edit `SCENES`, `DEVICES` and `STORES` there.
+- `demo/`: the staged demo host the captures come from.
+- `output/apple/`: 1320 × 2868 for the iPhone 6.9-inch slot.
+- `output/google/`: 1440 × 2560 (9:16) phone screenshots, reusing the iPhone captures.
+- `output/apple-ipad/`: 2064 × 2752 for the iPad 13-inch slot.
+- `output/google-tablet/`: 1800 × 3200 (9:16) tablet screenshots, reusing the iPad captures.
+- `output/preview.png`: contact sheet with one row per store, for review only. It is ignored by Git; do not upload it to a store.
+
+All exports are opaque RGB PNGs.
+
+## Render
+
+```sh
+SF_FONT_DIR=/path/to/fonts node assets/store-screenshots/render.mjs
+```
+
+`SF_FONT_DIR` must hold `SFNS.ttf` copied from a Mac's `/System/Library/Fonts`. On macOS the renderer finds it without the variable. SF Pro is not redistributable, so it is not in the repository. The renderer fails rather than fall back to another font.
+
+Each capture and callout is resized with Lanczos to the exact pixels it fills, and the page renders at device scale 1. Do not render at a higher scale and downsample: Chrome's image downscaling is what made earlier exports look soft and aliased.
+
+Open `output/preview.png` and at least one full-size panel per store before you call a render done. The line guard catches wrapping, not a callout that covers the wrong thing.
+
+Callout crops are in native capture pixels. To find them, overlay a 100 px grid on the capture with sharp and read the coordinates off it.
+
+## Recapture
+
+1. Stage the demo host. It runs an in-process daemon on port 7791 with scripted Claude Code and Codex clients, a local clone of this repository as the `paseo` project, real worktrees, and a terminal in the hero worktree:
+
+   ```sh
+   npx tsx assets/store-screenshots/demo/stage.mts
+   ```
+
+   Each run re-clones the repository into the demo home, so stale worktrees from an earlier run do not block it. The hero agent is paced so it reports a realistic "Worked for" time. Wait for `READY` in its output.
+
+2. Start Metro against it on a free port. When the simulator runs on another Mac, forward Metro and the daemon to it. Other agents may already hold a Metro port; pick another one rather than stopping theirs.
+
+   ```sh
+   EXPO_PUBLIC_LOCAL_DAEMON=127.0.0.1:7791 npm run start:expo --workspace=@getpaseo/app -- --port <port>
+   ssh -o ExitOnForwardFailure=yes -R <port>:127.0.0.1:<port> -R 7791:127.0.0.1:7791 <mac-host>
+   ```
+
+3. On the simulator, install and open the dev client (`sh.paseo.debug`) at `http://127.0.0.1:<port>`. Use an iPhone 16 Pro Max for the phone set and an iPad Pro 13-inch (M4) in portrait for the tablet set.
+   - Set dark appearance and override the status bar to 9:41 with full battery and signal (`xcrun simctl status_bar <device> override`).
+   - On first launch, accept the open-in-app dialog, decline notifications, turn off the dev client's Tools button, and close any error toast. `agent-device react-native dismiss-overlay` clears overlays.
+   - Name the host "MacBook Pro" and set the sidebar badge to Hidden.
+   - Group the sidebar by status.
+   - If you reset the simulator, reinstall the dev client.
+
+4. Capture the sidebar first. Opening a "Ready to review" workspace marks it done. Select a Working row before you capture.
+
+5. Capture every screen at native density. `agent-device screenshot` defaults to 1x, which is too soft for the store:
+
+   ```sh
+   agent-device screenshot /tmp/sidebar.png --pixel-density 3 --session store   # iPhone: 1320 × 2868
+   agent-device screenshot /tmp/sidebar.png --pixel-density 2 --session store   # iPad: 2064 × 2752
+   ```
+
+   - **Chat:** expand the tool-call group and scroll to the bottom. On iPad, open Explorer → Changes beside the chat.
+   - **Diff:** on iPhone, Explorer → Changes, then use Jump to file to reach `daemon-client.ts`. On iPad, collapse the sidebar, open a Diff tab from the main area's **+** menu and scroll to the `daemon-client.ts` hunks.
+   - **Terminal:** the second workspace tab. Type the commands with `npm run cli -- terminal send-keys --host 127.0.0.1:7791 <terminal-id> "<text>" Enter` instead of the simulator keyboard, then dismiss the software keyboard.
+   - **Plugin:** the "Build a preview deploys plugin" workspace with the turn collapsed, then tap **Deploys** for `plugin-sheet.png`. After editing the plugin, reload it with `npm run cli -- plugin reload --host 127.0.0.1:7791 preview-deploys`.
+
+6. Copy the captures into `raw/iphone/` or `raw/ipad/` under the names `render.mjs` uses, render, and check the preview.
+
+## Publish
+
+The stable release uploads these exports to the App Store and Google Play, and F-Droid reads the Google ones from the repo. See [Store screenshots](../../docs/release.md#store-screenshots). The Android metadata holds links to the Google exports, and every render rewrites them, so commit the links with the exports.
+
+Dimensions are checked against [Apple's screenshot specifications](https://developer.apple.com/help/app-store-connect/reference/app-information/screenshot-specifications/) and [Google Play's preview asset requirements](https://support.google.com/googleplay/android-developer/answer/9866151?hl=en).
diff --git a/assets/store-screenshots/demo/change/apply.mjs b/assets/store-screenshots/demo/change/apply.mjs
new file mode 100644
index 0000000000..ae5efe295b
--- /dev/null
+++ b/assets/store-screenshots/demo/change/apply.mjs
@@ -0,0 +1,84 @@
+// Applies the demo change to a checkout of the Paseo repository.
+import { copyFileSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repo = process.argv[2];
+const client = path.join(repo, "packages/client/src");
+
+copyFileSync(
+  path.join(here, "reconnect-delay.ts"),
+  path.join(client, "connection/reconnect-delay.ts"),
+);
+copyFileSync(
+  path.join(here, "reconnect-delay.test.ts"),
+  path.join(client, "connection/reconnect-delay.test.ts"),
+);
+
+function edit(file, pairs) {
+  let text = readFileSync(file, "utf8");
+  for (const [from, to] of pairs) {
+    if (!text.includes(from)) throw new Error(`Missing anchor in ${file}: ${from.slice(0, 60)}`);
+    text = text.replace(from, to);
+  }
+  writeFileSync(file, text);
+}
+
+edit(path.join(client, "daemon-client.ts"), [
+  [
+    `import { CreationClient } from "./creation/index.js";\n`,
+    `import { CreationClient } from "./creation/index.js";\nimport { getReconnectDelayMs } from "./connection/reconnect-delay.js";\n`,
+  ],
+  [
+    `  private reconnectAttempt = 0;\n`,
+    `  private reconnectAttempt = 0;\n  private nextReconnectDelay: { attempt: number; delayMs: number } | null = null;\n`,
+  ],
+  [
+    `              nextRetryAt: new Date(
+                Date.now() +
+                  Math.min(
+                    (this.config.reconnect?.baseDelayMs ?? DEFAULT_RECONNECT_BASE_DELAY_MS) *
+                      2 ** this.reconnectAttempt,
+                    this.config.reconnect?.maxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS,
+                  ),
+              ).toISOString(),
+`,
+    `              nextRetryAt: new Date(Date.now() + this.getNextReconnectDelayMs()).toISOString(),
+`,
+  ],
+  [
+    `  private armReconnectTimer(): void {
+    const attempt = this.reconnectAttempt;
+    const baseDelay = this.config.reconnect?.baseDelayMs ?? DEFAULT_RECONNECT_BASE_DELAY_MS;
+    const maxDelay = this.config.reconnect?.maxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS;
+    const delay = Math.min(baseDelay * 2 ** attempt, maxDelay);
+`,
+    `  // The countdown and the timer must agree, so each attempt draws its jitter once.
+  private getNextReconnectDelayMs(): number {
+    const attempt = this.reconnectAttempt;
+    if (this.nextReconnectDelay?.attempt !== attempt) {
+      this.nextReconnectDelay = {
+        attempt,
+        delayMs: getReconnectDelayMs(attempt, {
+          baseDelayMs: this.config.reconnect?.baseDelayMs ?? DEFAULT_RECONNECT_BASE_DELAY_MS,
+          maxDelayMs: this.config.reconnect?.maxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS,
+        }),
+      };
+    }
+    return this.nextReconnectDelay.delayMs;
+  }
+
+  private armReconnectTimer(): void {
+    const attempt = this.reconnectAttempt;
+    const delay = this.getNextReconnectDelayMs();
+`,
+  ],
+]);
+
+edit(path.join(repo, "CHANGELOG.md"), [
+  [
+    `# Changelog\n\n`,
+    `# Changelog\n\n## Unreleased\n\n### Fixed\n\n- Spread reconnect attempts after a relay restart instead of retrying every client at once\n\n`,
+  ],
+]);
diff --git a/assets/store-screenshots/demo/change/reconnect-delay.test.ts b/assets/store-screenshots/demo/change/reconnect-delay.test.ts
new file mode 100644
index 0000000000..3b5367784c
--- /dev/null
+++ b/assets/store-screenshots/demo/change/reconnect-delay.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { getReconnectDelayMs } from "./reconnect-delay";
+
+const options = { baseDelayMs: 1500, maxDelayMs: 30_000 };
+
+describe("getReconnectDelayMs", () => {
+  it("doubles the ceiling on each attempt", () => {
+    const top = () => 1;
+    expect(getReconnectDelayMs(0, options, top)).toBe(1500);
+    expect(getReconnectDelayMs(1, options, top)).toBe(3000);
+    expect(getReconnectDelayMs(2, options, top)).toBe(6000);
+  });
+
+  it("never waits longer than the max delay", () => {
+    expect(getReconnectDelayMs(12, options, () => 1)).toBe(30_000);
+  });
+
+  it("spreads retries between half and the full ceiling", () => {
+    expect(getReconnectDelayMs(3, options, () => 0)).toBe(6000);
+    expect(getReconnectDelayMs(3, options, () => 0.5)).toBe(9000);
+    expect(getReconnectDelayMs(3, options, () => 1)).toBe(12_000);
+  });
+
+  it("keeps the first retry under two seconds", () => {
+    for (let i = 0; i < 100; i += 1) {
+      expect(getReconnectDelayMs(0, options)).toBeLessThanOrEqual(1500);
+    }
+  });
+});
diff --git a/assets/store-screenshots/demo/change/reconnect-delay.ts b/assets/store-screenshots/demo/change/reconnect-delay.ts
new file mode 100644
index 0000000000..88de867aa6
--- /dev/null
+++ b/assets/store-screenshots/demo/change/reconnect-delay.ts
@@ -0,0 +1,18 @@
+export interface ReconnectDelayOptions {
+  baseDelayMs: number;
+  maxDelayMs: number;
+}
+
+/**
+ * Exponential backoff with equal jitter. Half of each delay is fixed and half
+ * is random, so a relay restart spreads reconnects out instead of every client
+ * retrying on the same tick.
+ */
+export function getReconnectDelayMs(
+  attempt: number,
+  options: ReconnectDelayOptions,
+  random: () => number = Math.random,
+): number {
+  const ceiling = Math.min(options.baseDelayMs * 2 ** attempt, options.maxDelayMs);
+  return Math.round(ceiling / 2 + random() * (ceiling / 2));
+}
diff --git a/assets/store-screenshots/demo/preview-deploys/index.client.tsx b/assets/store-screenshots/demo/preview-deploys/index.client.tsx
new file mode 100644
index 0000000000..72ab9a709a
--- /dev/null
+++ b/assets/store-screenshots/demo/preview-deploys/index.client.tsx
@@ -0,0 +1,204 @@
+// The plugin the demo agent "builds" in the store screenshots: a Deploys pill on
+// every composer that opens the latest preview deploy for each branch. The
+// deploys are fixed sample data; the UI is a real plugin surface.
+import type {
+  PluginButtonContentProps,
+  PluginButtonRegistration,
+  PluginClientContext,
+} from "@getpaseo/plugin/client";
+import { useMemo } from "react";
+import { Text, View } from "react-native";
+
+type DeployStatus = "ready" | "building" | "failed";
+
+interface Deploy {
+  branch: string;
+  status: DeployStatus;
+  detail: string;
+  age: string;
+  progress?: number;
+}
+
+const DEPLOYS: Deploy[] = [
+  { branch: "fix/reconnect-jitter", status: "ready", detail: "Built in 48s", age: "2m" },
+  {
+    branch: "perf/provider-snapshot-cache",
+    status: "building",
+    detail: "Bundling app",
+    age: "now",
+    progress: 0.64,
+  },
+  { branch: "feat/remember-terminal", status: "ready", detail: "Built in 51s", age: "18m" },
+  {
+    branch: "i18n/ko-settings",
+    status: "failed",
+    detail: "Missing key settings.notifications",
+    age: "26m",
+  },
+];
+
+function DeploysSheet({ theme, layout }: PluginButtonContentProps) {
+  const mono = layout.platform === "ios" ? "Menlo" : "monospace";
+  const styles = useMemo(
+    () => ({
+      // Popovers on tablets and desktop are narrow by default; give the
+      // branch names room. Phones show the sheet at full width.
+      body: { gap: 14, width: layout.compact ? undefined : 400 },
+      production: {
+        padding: 14,
+        gap: 6,
+        borderRadius: 12,
+        backgroundColor: theme.colors.surface2,
+      },
+      productionTop: { flexDirection: "row" as const, alignItems: "center" as const, gap: 8 },
+      label: { color: theme.colors.foregroundMuted, fontSize: 13 },
+      version: { color: theme.colors.foreground, fontSize: 22, fontWeight: "600" as const },
+      live: { color: theme.colors.statusSuccess, fontSize: 13, fontWeight: "600" as const },
+      heading: { color: theme.colors.foregroundMuted, fontSize: 13, marginTop: 4 },
+      list: {
+        borderRadius: 12,
+        borderWidth: 1,
+        borderColor: theme.colors.border,
+        overflow: "hidden" as const,
+      },
+      row: {
+        flexDirection: "row" as const,
+        alignItems: "center" as const,
+        gap: 12,
+        paddingVertical: 12,
+        paddingHorizontal: 14,
+      },
+      divider: { height: 1, backgroundColor: theme.colors.border },
+      text: { flex: 1, gap: 4 },
+      branch: { color: theme.colors.foreground, fontSize: 14, fontFamily: mono },
+      detail: { color: theme.colors.foregroundMuted, fontSize: 13 },
+      failed: { color: theme.colors.statusDanger, fontSize: 13 },
+      age: { color: theme.colors.foregroundMuted, fontSize: 13 },
+      track: {
+        height: 4,
+        marginTop: 4,
+        borderRadius: 2,
+        backgroundColor: theme.colors.surface2,
+        overflow: "hidden" as const,
+      },
+    }),
+    [theme, mono, layout.compact],
+  );
+  const dotColor: Record<DeployStatus, string> = {
+    ready: theme.colors.statusSuccess,
+    building: theme.colors.statusWarning,
+    failed: theme.colors.statusDanger,
+  };
+
+  return (
+    <View style={styles.body}>
+      <View style={styles.production}>
+        <View style={styles.productionTop}>
+          <Dot color={theme.colors.statusSuccess} />
+          <Text style={styles.live}>Live</Text>
+          <Text style={styles.label}>Production · main</Text>
+        </View>
+        <Text style={styles.version}>v0.14.0-beta.1</Text>
+        <Text style={styles.label}>Deployed 3h ago</Text>
+      </View>
+      <Text style={styles.heading}>Previews</Text>
+      <View style={styles.list}>
+        {DEPLOYS.map((deploy, index) => (
+          <View key={deploy.branch}>
+            {index > 0 ? <View style={styles.divider} /> : null}
+            <View style={styles.row}>
+              <Dot color={dotColor[deploy.status]} />
+              <View style={styles.text}>
+                <Text style={styles.branch} numberOfLines={1}>
+                  {deploy.branch}
+                </Text>
+                <Text style={deploy.status === "failed" ? styles.failed : styles.detail}>
+                  {deploy.detail}
+                </Text>
+                {deploy.progress !== undefined ? (
+                  <Progress
+                    value={deploy.progress}
+                    track={styles.track}
+                    color={theme.colors.statusWarning}
+                  />
+                ) : null}
+              </View>
+              <Text style={styles.age}>{deploy.age}</Text>
+            </View>
+          </View>
+        ))}
+      </View>
+    </View>
+  );
+}
+
+function Progress({ value, track, color }: { value: number; track: object; color: string }) {
+  const fill = useMemo(
+    () => ({ width: `${value * 100}%` as const, height: 4, backgroundColor: color }),
+    [value, color],
+  );
+  return (
+    <View style={track}>
+      <View style={fill} />
+    </View>
+  );
+}
+
+function Dot({ color }: { color: string }) {
+  const style = useMemo(
+    () => ({ width: 8, height: 8, borderRadius: 4, backgroundColor: color }),
+    [color],
+  );
+  return <View style={style} />;
+}
+
+export default function contribute(client: PluginClientContext) {
+  const pills = new Map<string, PluginButtonRegistration>();
+  const lifetime = new AbortController();
+  const register = (agent: { id: string; workspaceId?: string | null }) => {
+    if (lifetime.signal.aborted || !agent.workspaceId) return;
+    pills.get(agent.id)?.remove();
+    pills.set(
+      agent.id,
+      client.addComposerPill({
+        id: "deploys",
+        workspaceId: agent.workspaceId,
+        agentId: agent.id,
+        button: {
+          title: "Preview deploys",
+          icon: "Rocket",
+          label: "Deploys",
+          behavior: { kind: "popover", Content: DeploysSheet },
+        },
+      }),
+    );
+  };
+  void client.paseo.agents
+    .list({ subscribe: {}, signal: lifetime.signal })
+    .then(({ subscription }) => {
+      subscription.subscribe({
+        snapshot: ({ entries }) => {
+          for (const pill of pills.values()) pill.remove();
+          pills.clear();
+          for (const { agent } of entries) register(agent);
+        },
+        update: (message) => {
+          if (message.type !== "agent_update") return;
+          const update = message.payload;
+          if (update.kind === "remove") {
+            pills.get(update.agentId)?.remove();
+            pills.delete(update.agentId);
+          } else register(update.agent);
+        },
+      });
+      return undefined;
+    })
+    .catch((error) => {
+      if (!lifetime.signal.aborted) console.error("Agent observation failed", error);
+    });
+  return () => {
+    lifetime.abort();
+    for (const pill of pills.values()) pill.remove();
+    pills.clear();
+  };
+}
diff --git a/assets/store-screenshots/demo/preview-deploys/paseo-plugin.json b/assets/store-screenshots/demo/preview-deploys/paseo-plugin.json
new file mode 100644
index 0000000000..0da849e8f7
--- /dev/null
+++ b/assets/store-screenshots/demo/preview-deploys/paseo-plugin.json
@@ -0,0 +1,4 @@
+{
+  "id": "preview-deploys",
+  "requirements": { "paseo": ">=0.8.0" }
+}
diff --git a/assets/store-screenshots/demo/scripted-agents.mts b/assets/store-screenshots/demo/scripted-agents.mts
new file mode 100644
index 0000000000..603017f323
--- /dev/null
+++ b/assets/store-screenshots/demo/scripted-agents.mts
@@ -0,0 +1,281 @@
+// Scripted Claude Code and Codex clients for staging store screenshots.
+// Each agent replays a fixed conversation through the real daemon, so the app
+// renders real timeline rows, permission prompts, and running states.
+import { randomUUID } from "node:crypto";
+import type {
+  AgentCapabilityFlags,
+  AgentClient,
+  AgentMode,
+  AgentModelDefinition,
+  AgentPermissionRequest,
+  AgentPermissionResponse,
+  AgentPersistenceHandle,
+  AgentPromptInput,
+  AgentRunResult,
+  AgentSession,
+  AgentSessionConfig,
+  AgentStreamEvent,
+  AgentTimelineItem,
+  ToolCallDetail,
+} from "../../../packages/server/src/server/agent/agent-sdk-types.js";
+import { getAgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
+
+export type ScriptStep =
+  | { kind: "say"; text: string }
+  | { kind: "think"; text: string }
+  | { kind: "tool"; name: string; detail: ToolCallDetail }
+  | { kind: "todo"; items: { text: string; completed: boolean }[] }
+  | { kind: "wait"; ms: number }
+  | { kind: "running-tool"; name: string; detail: ToolCallDetail }
+  | { kind: "ask"; name: string; title: string; detail: ToolCallDetail };
+
+export interface AgentScript {
+  /** Matched against the start of the prompt that opens the turn. */
+  prompt: string;
+  steps: ScriptStep[];
+  /** Leave the turn open after the last step. */
+  keepRunning?: boolean;
+  /** Pause between steps, so "Worked for" reflects a believable duration. */
+  stepDelayMs?: number;
+}
+
+const CAPABILITIES: AgentCapabilityFlags = {
+  supportsStreaming: true,
+  supportsSessionPersistence: true,
+  supportsDynamicModes: false,
+  supportsMcpServers: false,
+  supportsReasoningStream: true,
+  supportsToolInvocations: true,
+  supportsRewindConversation: false,
+  supportsRewindFiles: false,
+  supportsRewindBoth: false,
+};
+
+const MODELS: Record<string, AgentModelDefinition[]> = {
+  claude: [
+    {
+      provider: "claude",
+      id: "claude-opus-5-5",
+      label: "Opus 5.5",
+      isDefault: true,
+      thinkingOptions: [
+        { id: "medium", label: "Medium", isDefault: true },
+        { id: "high", label: "High" },
+      ],
+      defaultThinkingOptionId: "medium",
+    },
+    { provider: "claude", id: "claude-sonnet-5-5", label: "Sonnet 5.5" },
+  ],
+  codex: [
+    {
+      provider: "codex",
+      id: "gpt-5.6-sol",
+      label: "GPT-5.6-Sol",
+      isDefault: true,
+      thinkingOptions: [
+        { id: "medium", label: "Medium", isDefault: true },
+        { id: "high", label: "High" },
+      ],
+      defaultThinkingOptionId: "medium",
+    },
+  ],
+};
+
+function promptText(prompt: AgentPromptInput): string {
+  if (typeof prompt === "string") return prompt;
+  return prompt
+    .map((block) => ("text" in block && typeof block.text === "string" ? block.text : ""))
+    .join("");
+}
+
+class ScriptedSession implements AgentSession {
+  readonly capabilities = CAPABILITIES;
+  readonly id = randomUUID();
+  private readonly listeners = new Set<(event: AgentStreamEvent) => void>();
+  private readonly history: AgentStreamEvent[] = [];
+  private pending: AgentPermissionRequest[] = [];
+  private activeTurnId: string | null = null;
+
+  constructor(
+    readonly provider: string,
+    private readonly config: AgentSessionConfig,
+    private readonly scripts: AgentScript[],
+  ) {}
+
+  private emit(event: AgentStreamEvent): void {
+    const tagged = this.activeTurnId ? { ...event, turnId: this.activeTurnId } : event;
+    this.history.push(tagged);
+    for (const listener of this.listeners) listener(tagged);
+  }
+
+  private timeline(item: AgentTimelineItem): void {
+    this.emit({ type: "timeline", provider: this.provider, item });
+  }
+
+  async run(): Promise<AgentRunResult> {
+    return { sessionId: this.id, finalText: "", timeline: [] };
+  }
+
+  async startTurn(prompt: AgentPromptInput): Promise<{ turnId: string }> {
+    const turnId = randomUUID();
+    this.activeTurnId = turnId;
+    const text = promptText(prompt);
+    const script = this.scripts.find((candidate) => text.startsWith(candidate.prompt));
+    setTimeout(() => void this.play(text, script), 50);
+    return { turnId };
+  }
+
+  private async play(text: string, script: AgentScript | undefined): Promise<void> {
+    this.emit({ type: "turn_started", provider: this.provider });
+    this.timeline({ type: "user_message", text, messageId: randomUUID() });
+    const delay = script?.stepDelayMs ?? 400;
+    for (const step of script?.steps ?? [{ kind: "say", text: "Done." } as const]) {
+      await new Promise((resolve) => setTimeout(resolve, step.kind === "wait" ? step.ms : delay));
+      this.playStep(step);
+      if (step.kind === "ask") return;
+    }
+    if (script?.keepRunning) return;
+    this.emit({
+      type: "turn_completed",
+      provider: this.provider,
+      usage: { inputTokens: 48_210, outputTokens: 3_904 },
+    });
+    this.activeTurnId = null;
+  }
+
+  private playStep(step: ScriptStep): void {
+    switch (step.kind) {
+      case "say":
+        this.timeline({ type: "assistant_message", text: step.text, messageId: randomUUID() });
+        return;
+      case "think":
+        this.timeline({ type: "reasoning", text: step.text });
+        return;
+      case "todo":
+        this.timeline({ type: "todo", items: step.items });
+        return;
+      case "wait":
+        return;
+      case "tool":
+      case "running-tool": {
+        const callId = randomUUID();
+        this.timeline({
+          type: "tool_call",
+          callId,
+          name: step.name,
+          status: "running",
+          error: null,
+          detail: step.detail,
+        });
+        if (step.kind === "tool") {
+          this.timeline({
+            type: "tool_call",
+            callId,
+            name: step.name,
+            status: "completed",
+            error: null,
+            detail: step.detail,
+          });
+        }
+        return;
+      }
+      case "ask": {
+        const request: AgentPermissionRequest = {
+          id: randomUUID(),
+          provider: this.provider,
+          name: step.name,
+          kind: "tool",
+          title: step.title,
+          detail: step.detail,
+        };
+        this.pending = [request];
+        this.emit({ type: "permission_requested", provider: this.provider, request });
+      }
+    }
+  }
+
+  subscribe(callback: (event: AgentStreamEvent) => void): () => void {
+    this.listeners.add(callback);
+    return () => this.listeners.delete(callback);
+  }
+
+  async *streamHistory(): AsyncGenerator<AgentStreamEvent> {
+    yield* this.history;
+  }
+
+  async getRuntimeInfo() {
+    return {
+      provider: this.provider,
+      sessionId: this.id,
+      model: this.config.model ?? MODELS[this.provider]?.[0]?.id ?? null,
+      thinkingOptionId: this.config.thinkingOptionId ?? "medium",
+      modeId: this.config.modeId ?? null,
+    };
+  }
+
+  async getAvailableModes(): Promise<AgentMode[]> {
+    return getAgentProviderDefinition(this.provider).modes;
+  }
+
+  async getCurrentMode(): Promise<string | null> {
+    return this.config.modeId ?? null;
+  }
+
+  async setMode(): Promise<void> {}
+
+  getPendingPermissions(): AgentPermissionRequest[] {
+    return this.pending;
+  }
+
+  async respondToPermission(requestId: string, resolution: AgentPermissionResponse) {
+    this.pending = [];
+    this.emit({ type: "permission_resolved", provider: this.provider, requestId, resolution });
+  }
+
+  describePersistence(): AgentPersistenceHandle {
+    return { provider: this.provider, sessionId: this.id };
+  }
+
+  async interrupt(): Promise<void> {
+    if (!this.activeTurnId) return;
+    this.emit({ type: "turn_canceled", provider: this.provider, reason: "Interrupted" });
+    this.activeTurnId = null;
+  }
+
+  async close(): Promise<void> {}
+}
+
+export class ScriptedAgentClient implements AgentClient {
+  readonly capabilities = CAPABILITIES;
+
+  constructor(
+    readonly provider: string,
+    private readonly scripts: AgentScript[],
+  ) {}
+
+  async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+    return new ScriptedSession(this.provider, config, this.scripts);
+  }
+
+  async resumeSession(
+    _handle: AgentPersistenceHandle,
+    overrides?: Partial<AgentSessionConfig>,
+  ): Promise<AgentSession> {
+    return new ScriptedSession(
+      this.provider,
+      { provider: this.provider, cwd: overrides?.cwd ?? process.cwd(), ...overrides },
+      this.scripts,
+    );
+  }
+
+  async fetchCatalog() {
+    return {
+      models: MODELS[this.provider] ?? [],
+      modes: getAgentProviderDefinition(this.provider).modes,
+    };
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return true;
+  }
+}
diff --git a/assets/store-screenshots/demo/stage.mts b/assets/store-screenshots/demo/stage.mts
new file mode 100644
index 0000000000..3c6a3cadf0
--- /dev/null
+++ b/assets/store-screenshots/demo/stage.mts
@@ -0,0 +1,556 @@
+// Stages the demo host used for store screenshots.
+//
+//   npx tsx assets/store-screenshots/demo/stage.mts
+//
+// Starts an in-process daemon on DEMO_PORT (default 7791) with scripted Claude
+// Code and Codex clients, adds a local clone of this repository as the `paseo`
+// project, cuts real worktrees, applies a real change to the hero worktree, and
+// opens a terminal there. Leave it running while you capture.
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createTestPaseoDaemon } from "../../../packages/server/src/server/test-utils/paseo-daemon.js";
+import { DaemonClient } from "../../../packages/server/src/server/test-utils/daemon-client.js";
+import { type AgentScript, ScriptedAgentClient } from "./scripted-agents.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, "../../..");
+const demoRoot = path.join(repoRoot, ".dev/store-capture/demo");
+const codeRoot = path.join(demoRoot, "code");
+const pluginDir = path.join(here, "preview-deploys");
+const port = Number(process.env.DEMO_PORT ?? 7791);
+const minute = 60_000;
+
+const claudeScripts: AgentScript[] = [];
+const codexScripts: AgentScript[] = [];
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", ["-c", "user.name=Mo", "-c", "user.email=mo@paseo.sh", ...args], {
+    cwd,
+    encoding: "utf8",
+  });
+}
+
+function run(cwd: string, command: string): string {
+  return execSync(command, { cwd, encoding: "utf8", env: { ...process.env, FORCE_COLOR: "0" } });
+}
+
+async function prepareRepos(): Promise<void> {
+  // A fresh clone each run: worktrees from an earlier run stay registered in it.
+  // Worktree setup (npm ci, builds) is dropped so new worktrees open instantly.
+  const paseo = path.join(codeRoot, "paseo");
+  await rm(paseo, { recursive: true, force: true });
+  await mkdir(codeRoot, { recursive: true });
+  execFileSync("git", ["clone", "-q", "--local", repoRoot, paseo]);
+  git(paseo, "checkout", "-q", "-B", "main");
+  git(paseo, "remote", "remove", "origin");
+  const config = JSON.parse(await readFile(path.join(paseo, "paseo.json"), "utf8"));
+  delete config.worktree;
+  await writeFile(path.join(paseo, "paseo.json"), `${JSON.stringify(config, null, 2)}\n`);
+  git(paseo, "commit", "-qam", "chore: skip worktree setup in demo");
+  const dotfiles = path.join(codeRoot, "dotfiles");
+  if (!existsSync(dotfiles)) {
+    await mkdir(dotfiles, { recursive: true });
+    await writeFile(path.join(dotfiles, "tmux.conf"), "set -g mouse on\nset -g base-index 1\n");
+    await writeFile(path.join(dotfiles, "zshrc"), "export EDITOR=nvim\nalias g=git\n");
+    git(dotfiles, "init", "-q", "-b", "main");
+    git(dotfiles, "add", ".");
+    git(dotfiles, "commit", "-qm", "Initial dotfiles");
+  }
+}
+
+async function main(): Promise<void> {
+  await prepareRepos();
+  const home = path.join(demoRoot, "home");
+  await rm(home, { recursive: true, force: true });
+  await mkdir(home, { recursive: true });
+
+  const daemon = await createTestPaseoDaemon({
+    agentClients: {
+      claude: new ScriptedAgentClient("claude", claudeScripts),
+      codex: new ScriptedAgentClient("codex", codexScripts),
+    },
+    listen: "127.0.0.1",
+    listenPort: port,
+    paseoHomeRoot: home,
+    mcpEnabled: false,
+    cleanup: false,
+    pluginsEnabled: true,
+    plugins: {
+      "preview-deploys": { source: "directory", path: pluginDir, enabled: true },
+    },
+  });
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    appVersion: "0.14.0",
+  });
+  await client.connect();
+  await client.fetchAgents({ subscribe: {} });
+
+  const paseo = await client.addProject(path.join(codeRoot, "paseo"));
+  const dotfiles = await client.addProject(path.join(codeRoot, "dotfiles"));
+  const paseoProjectId = paseo.project!.projectId;
+
+  async function worktree(title: string, branchName: string) {
+    const result = await client.createWorkspace({
+      title,
+      source: {
+        kind: "worktree",
+        projectId: paseoProjectId,
+        action: "branch-off",
+        baseBranch: "main",
+        branchName,
+      },
+    });
+    if (!result.workspace) throw new Error(`No workspace for ${title}: ${JSON.stringify(result)}`);
+    return result.workspace;
+  }
+
+  async function agent(input: {
+    provider: "claude" | "codex";
+    workspace: { id: string; workspaceDirectory?: string | null };
+    cwd: string;
+    title: string;
+    script: AgentScript;
+  }) {
+    (input.provider === "claude" ? claudeScripts : codexScripts).push(input.script);
+    return client.createAgent({
+      provider: input.provider,
+      cwd: input.cwd,
+      workspaceId: input.workspace.id,
+      title: input.title,
+      initialPrompt: input.script.prompt,
+    });
+  }
+
+  const pause = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+  // Done: finished earlier and already read.
+  const release = await worktree("Release v0.14.0-beta.1", "release/0.14.0-beta.1");
+  const releaseAgent = await agent({
+    provider: "codex",
+    workspace: release,
+    cwd: release.workspaceDirectory!,
+    title: "Release v0.14.0-beta.1",
+    script: {
+      prompt: "Cut 0.14.0-beta.1 from main and draft the release notes.",
+      steps: [
+        {
+          kind: "tool",
+          name: "shell",
+          detail: {
+            type: "shell",
+            command: "npm run release:beta",
+            output: "Tagged v0.14.0-beta.1\n",
+            exitCode: 0,
+          },
+        },
+        {
+          kind: "say",
+          text: "Tagged `v0.14.0-beta.1` and drafted the release notes. CI is building the desktop and mobile artifacts.",
+        },
+      ],
+    },
+  });
+  const dotfilesWorkspace = (
+    await client.createWorkspace({
+      title: "Add a tmux status line",
+      source: {
+        kind: "directory",
+        path: path.join(codeRoot, "dotfiles"),
+        projectId: dotfiles.project!.projectId,
+      },
+    })
+  ).workspace!;
+  const tmuxAgent = await agent({
+    provider: "claude",
+    workspace: dotfilesWorkspace,
+    cwd: path.join(codeRoot, "dotfiles"),
+    title: "Add a tmux status line",
+    script: {
+      prompt: "Add a minimal tmux status line with the session name and battery.",
+      steps: [
+        {
+          kind: "tool",
+          name: "Edit",
+          detail: {
+            type: "edit",
+            filePath: "tmux.conf",
+            oldString: "",
+            newString: "set -g status-right '#S · #{battery_percentage}'",
+          },
+        },
+        {
+          kind: "say",
+          text: "Added a status line with the session name on the left and battery on the right.",
+        },
+      ],
+    },
+  });
+  await pause(3000);
+  await client.clearAgentAttention([releaseAgent.id, tmuxAgent.id]);
+
+  // Working: turns that stay open while you capture.
+  const ipad = await worktree(
+    "Keep the composer above the iPad keyboard",
+    "fix/ipad-keyboard-inset",
+  );
+  await agent({
+    provider: "codex",
+    workspace: ipad,
+    cwd: ipad.workspaceDirectory!,
+    title: "Keep the composer above the iPad keyboard",
+    script: {
+      prompt:
+        "On iPad with a hardware keyboard attached, the composer jumps up as if the software keyboard were open. Find out why and fix it.",
+      keepRunning: true,
+      steps: [
+        {
+          kind: "tool",
+          name: "shell",
+          detail: {
+            type: "shell",
+            command: 'rg -n "keyboardHeight" packages/app/src',
+            output:
+              "packages/app/src/keyboard/shift/internal/provider.ts:41:  const keyboardHeight = useSharedValue(0);\n",
+            exitCode: 0,
+          },
+        },
+        {
+          kind: "tool",
+          name: "read",
+          detail: {
+            type: "read",
+            filePath: "packages/app/src/keyboard/shift/internal/provider.ts",
+          },
+        },
+        {
+          kind: "say",
+          text: "The shift provider trusts the keyboard frame event. With a hardware keyboard, iPadOS still reports the shortcuts bar as a keyboard frame, so we lift the composer by its full height. Checking the frame against the screen bottom next.",
+        },
+        {
+          kind: "running-tool",
+          name: "shell",
+          detail: { type: "shell", command: "npx vitest run packages/app/src/keyboard" },
+        },
+      ],
+    },
+  });
+  const snapshots = await worktree(
+    "Cache provider snapshots on disk",
+    "perf/provider-snapshot-cache",
+  );
+  await agent({
+    provider: "claude",
+    workspace: snapshots,
+    cwd: snapshots.workspaceDirectory!,
+    title: "Cache provider snapshots on disk",
+    script: {
+      prompt:
+        "Cold start spends about two seconds probing providers. Cache the last provider snapshot on disk and refresh it in the background.",
+      keepRunning: true,
+      steps: [
+        {
+          kind: "todo",
+          items: [
+            { text: "Find where snapshots are built", completed: true },
+            { text: "Persist the last snapshot per host", completed: false },
+            { text: "Refresh in the background after boot", completed: false },
+          ],
+        },
+        {
+          kind: "tool",
+          name: "Read",
+          detail: {
+            type: "read",
+            filePath: "packages/server/src/server/agent/provider-snapshot-manager.ts",
+          },
+        },
+        {
+          kind: "running-tool",
+          name: "Edit",
+          detail: {
+            type: "edit",
+            filePath: "packages/server/src/server/agent/provider-snapshot-manager.ts",
+          },
+        },
+      ],
+    },
+  });
+
+  // Needs input: waiting on a permission.
+  const korean = await worktree("Korean translations for Settings", "i18n/ko-settings");
+  await agent({
+    provider: "claude",
+    workspace: korean,
+    cwd: korean.workspaceDirectory!,
+    title: "Korean translations for Settings",
+    script: {
+      prompt: "Translate the new Settings strings into Korean and open a PR.",
+      steps: [
+        {
+          kind: "tool",
+          name: "Read",
+          detail: { type: "read", filePath: "packages/app/src/i18n/resources/en.ts" },
+        },
+        {
+          kind: "tool",
+          name: "Edit",
+          detail: { type: "edit", filePath: "packages/app/src/i18n/resources/ko.ts" },
+        },
+        {
+          kind: "tool",
+          name: "Bash",
+          detail: {
+            type: "shell",
+            command: "npm run test --workspace=@getpaseo/app -- i18n",
+            output: "Test Files  3 passed (3)\n     Tests  41 passed (41)\n",
+            exitCode: 0,
+          },
+        },
+        { kind: "say", text: "Translated 18 strings. I'll push the branch so I can open the PR." },
+        {
+          kind: "ask",
+          name: "Bash",
+          title: "Bash",
+          detail: { type: "shell", command: "git push -u origin i18n/ko-settings" },
+        },
+      ],
+    },
+  });
+
+  // Ready to review: a second finished agent.
+  const terminals = await worktree(
+    "Remember the last terminal per workspace",
+    "feat/remember-terminal",
+  );
+  await agent({
+    provider: "codex",
+    workspace: terminals,
+    cwd: terminals.workspaceDirectory!,
+    title: "Remember the last terminal per workspace",
+    script: {
+      prompt:
+        "When I switch back to a workspace, open the terminal I was using last instead of the first one.",
+      steps: [
+        {
+          kind: "tool",
+          name: "shell",
+          detail: {
+            type: "shell",
+            command: 'rg -n "activeTerminalId" packages/app/src',
+            output: "",
+            exitCode: 0,
+          },
+        },
+        {
+          kind: "say",
+          text: "Workspaces now remember their last focused terminal and reopen it when you switch back. The choice is stored per host, so it survives restarts.",
+        },
+      ],
+    },
+  });
+
+  // Plugin: the agent "built" the preview-deploys plugin this daemon runs.
+  const plugin = await worktree("Build a preview deploys plugin", "plugins/preview-deploys");
+  const pluginSource = (file: string) => run(pluginDir, `cat ${file}`);
+  await agent({
+    provider: "claude",
+    workspace: plugin,
+    cwd: plugin.workspaceDirectory!,
+    title: "Build a preview deploys plugin",
+    script: {
+      prompt: "Build me a plugin that shows our preview deploys right next to the composer.",
+      stepDelayMs: 6_000,
+      steps: [
+        { kind: "tool", name: "Read", detail: { type: "read", filePath: "docs/plugins.md" } },
+        {
+          kind: "tool",
+          name: "Write",
+          detail: {
+            type: "write",
+            filePath: "plugins/preview-deploys/paseo-plugin.json",
+            content: pluginSource("paseo-plugin.json"),
+          },
+        },
+        {
+          kind: "tool",
+          name: "Write",
+          detail: {
+            type: "write",
+            filePath: "plugins/preview-deploys/index.client.tsx",
+            content: pluginSource("index.client.tsx"),
+          },
+        },
+        {
+          kind: "tool",
+          name: "Bash",
+          detail: {
+            type: "shell",
+            command: "paseo plugin install ./plugins/preview-deploys",
+            output: "Installed preview-deploys\n",
+            exitCode: 0,
+          },
+        },
+        {
+          kind: "say",
+          text: "Done. **Deploys** now sits above the composer in every workspace. Tap it to see production and the latest preview for each branch, with build progress and failures.",
+        },
+      ],
+    },
+  });
+
+  // Hero: Claude finished a real change in a real worktree.
+  const jitter = await worktree("Add jitter to reconnect backoff", "fix/reconnect-jitter");
+  const cwd = jitter.workspaceDirectory!;
+  await symlink(path.join(repoRoot, "node_modules"), path.join(cwd, "node_modules"));
+  execFileSync("node", [path.join(here, "change/apply.mjs"), cwd]);
+  const clientDiff = git(cwd, "diff", "--", "packages/client/src/daemon-client.ts");
+  const vitest = run(
+    cwd,
+    "npx vitest run packages/client/src/connection/reconnect-delay.test.ts",
+  ).replace(/^ RUN .*\n/m, "");
+  const readExcerpt = run(cwd, "sed -n '7067,7086p' packages/client/src/daemon-client.ts");
+  await agent({
+    provider: "claude",
+    workspace: jitter,
+    cwd,
+    title: "Add jitter to reconnect backoff",
+    script: {
+      prompt:
+        'When the relay restarts, every phone reconnects at the same moment and we get a spike. Add jitter to the reconnect backoff, keep the 30s cap, and make sure the "Retrying in" countdown still matches the real delay.',
+      stepDelayMs: 7_000,
+      steps: [
+        {
+          kind: "tool",
+          name: "Grep",
+          detail: {
+            type: "search",
+            toolName: "grep",
+            query: "reconnectAttempt",
+            filePaths: ["packages/client/src/daemon-client.ts"],
+            numFiles: 1,
+            numMatches: 9,
+            mode: "files_with_matches",
+          },
+        },
+        {
+          kind: "tool",
+          name: "Read",
+          detail: {
+            type: "read",
+            filePath: "packages/client/src/daemon-client.ts",
+            offset: 7040,
+            limit: 60,
+            content: readExcerpt,
+          },
+        },
+        {
+          kind: "say",
+          text: "The delay is calculated twice: once for `nextRetryAt`, which drives the countdown, and again when the timer is armed. Both use plain doubling, so every client retries on the same schedule. If I add randomness in both places the countdown will be wrong, so I'll draw the jitter once per attempt and share it.",
+        },
+        {
+          kind: "tool",
+          name: "Write",
+          detail: {
+            type: "write",
+            filePath: "packages/client/src/connection/reconnect-delay.ts",
+            content: run(cwd, "cat packages/client/src/connection/reconnect-delay.ts"),
+          },
+        },
+        {
+          kind: "tool",
+          name: "Edit",
+          detail: {
+            type: "edit",
+            filePath: "packages/client/src/daemon-client.ts",
+            unifiedDiff: clientDiff,
+          },
+        },
+        {
+          kind: "tool",
+          name: "Write",
+          detail: {
+            type: "write",
+            filePath: "packages/client/src/connection/reconnect-delay.test.ts",
+            content: run(cwd, "cat packages/client/src/connection/reconnect-delay.test.ts"),
+          },
+        },
+        {
+          kind: "tool",
+          name: "Bash",
+          detail: {
+            type: "shell",
+            command: "npx vitest run packages/client/src/connection/reconnect-delay.test.ts",
+            output: vitest,
+            exitCode: 0,
+          },
+        },
+        {
+          kind: "tool",
+          name: "Edit",
+          detail: {
+            type: "edit",
+            filePath: "CHANGELOG.md",
+            unifiedDiff: git(cwd, "diff", "--", "CHANGELOG.md"),
+          },
+        },
+        {
+          kind: "say",
+          text: [
+            "Reconnects now back off with jitter.",
+            "",
+            "- `getReconnectDelayMs` picks a delay between half and the full backoff, still capped at 30s.",
+            '- `DaemonClient` draws the delay once per attempt, so the "Retrying in" countdown matches the actual retry.',
+            "- Four new tests cover the doubling, the cap, the jitter range, and a quick first retry.",
+            "",
+            "Tests pass. After a relay restart, clients now spread their reconnects across the backoff window instead of arriving together.",
+          ].join("\n"),
+        },
+      ],
+    },
+  });
+
+  const terminal = await client.createTerminal(cwd, "zsh", undefined, {
+    workspaceId: jitter.id,
+    command: "bash",
+    args: ["--rcfile", path.join(here, "terminal-rc.sh"), "-i"],
+  });
+  const terminalId = terminal.terminal?.id;
+  if (terminalId) {
+    await pause(1500);
+    for (const line of [
+      "git status --short",
+      "cd packages/client",
+      "npx vitest run reconnect --reporter=tree",
+    ]) {
+      client.sendTerminalInput(terminalId, { type: "input", data: `${line}\r` });
+      await pause(4000);
+    }
+  }
+
+  console.log(`READY port=${daemon.port} home=${daemon.paseoHome}`);
+  await writeFile(
+    path.join(demoRoot, "state.json"),
+    JSON.stringify(
+      { port: daemon.port, home: daemon.paseoHome, hero: { workspaceId: jitter.id, cwd } },
+      null,
+      2,
+    ),
+  );
+  const stop = async () => {
+    await client.close();
+    await daemon.close();
+    process.exit(0);
+  };
+  process.on("SIGTERM", stop);
+  process.on("SIGINT", stop);
+  void minute;
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
diff --git a/assets/store-screenshots/demo/terminal-rc.sh b/assets/store-screenshots/demo/terminal-rc.sh
new file mode 100644
index 0000000000..ab33d79466
--- /dev/null
+++ b/assets/store-screenshots/demo/terminal-rc.sh
@@ -0,0 +1,19 @@
+# Shell profile for the demo terminal: a Pure-style two-line prompt that fits a
+# phone-width terminal, and vitest output without the absolute checkout path
+# or the long timing breakdown. Vitest drops its colors when piped, so the
+# wrapper puts its usual green checks and grey timings back.
+export FORCE_COLOR=1
+__where() { local top; top=$(git rev-parse --show-toplevel 2>/dev/null); printf '~/paseo%s' "${PWD#"$top"}"; }
+__branch() { git branch --show-current 2>/dev/null; }
+__dirty() { [ -n "$(git status --porcelain 2>/dev/null)" ] && printf '*'; }
+PROMPT_COMMAND='printf "\e]0;zsh\a"'
+PS1='\n\[\e[34m\]$(__where)\[\e[0m\] \[\e[90m\]$(__branch)$(__dirty)\[\e[0m\]\n\[\e[35m\]❯\[\e[0m\] '
+npx() {
+  command npx "$@" 2>&1 | sed -E \
+    -e '1{/^$/d}' -e '/ RUN /d' -e '/Start at/d' -e 's/ \(transform.*\)//' \
+    -e $'s/✓/\e[32m✓\e[0m/' \
+    -e $'s/ ([0-9]+ms)$/ \e[90m\\1\e[0m/' \
+    -e $'s/ (\\([0-9]+( tests)?\\))/ \e[90m\\1\e[0m/' \
+    -e $'s/([0-9]+ passed)/\e[1;32m\\1\e[0m/'
+}
+clear
diff --git a/assets/store-screenshots/output/apple-ipad/01-sidebar.png b/assets/store-screenshots/output/apple-ipad/01-sidebar.png
new file mode 100644
index 0000000000..03f1d8ed61
Binary files /dev/null and b/assets/store-screenshots/output/apple-ipad/01-sidebar.png differ
diff --git a/assets/store-screenshots/output/apple-ipad/02-chat.png b/assets/store-screenshots/output/apple-ipad/02-chat.png
new file mode 100644
index 0000000000..1c56073112
Binary files /dev/null and b/assets/store-screenshots/output/apple-ipad/02-chat.png differ
diff --git a/assets/store-screenshots/output/apple-ipad/03-plugins.png b/assets/store-screenshots/output/apple-ipad/03-plugins.png
new file mode 100644
index 0000000000..87063634d3
Binary files /dev/null and b/assets/store-screenshots/output/apple-ipad/03-plugins.png differ
diff --git a/assets/store-screenshots/output/apple-ipad/04-review.png b/assets/store-screenshots/output/apple-ipad/04-review.png
new file mode 100644
index 0000000000..80e8cf8a52
Binary files /dev/null and b/assets/store-screenshots/output/apple-ipad/04-review.png differ
diff --git a/assets/store-screenshots/output/apple-ipad/05-terminal.png b/assets/store-screenshots/output/apple-ipad/05-terminal.png
new file mode 100644
index 0000000000..01b8d93c2a
Binary files /dev/null and b/assets/store-screenshots/output/apple-ipad/05-terminal.png differ
diff --git a/assets/store-screenshots/output/apple/01-sidebar.png b/assets/store-screenshots/output/apple/01-sidebar.png
new file mode 100644
index 0000000000..f2a7ab849c
Binary files /dev/null and b/assets/store-screenshots/output/apple/01-sidebar.png differ
diff --git a/assets/store-screenshots/output/apple/02-chat.png b/assets/store-screenshots/output/apple/02-chat.png
new file mode 100644
index 0000000000..b9afa6607d
Binary files /dev/null and b/assets/store-screenshots/output/apple/02-chat.png differ
diff --git a/assets/store-screenshots/output/apple/03-plugins.png b/assets/store-screenshots/output/apple/03-plugins.png
new file mode 100644
index 0000000000..6f74f4ce53
Binary files /dev/null and b/assets/store-screenshots/output/apple/03-plugins.png differ
diff --git a/assets/store-screenshots/output/apple/04-review.png b/assets/store-screenshots/output/apple/04-review.png
new file mode 100644
index 0000000000..9b34d6cce0
Binary files /dev/null and b/assets/store-screenshots/output/apple/04-review.png differ
diff --git a/assets/store-screenshots/output/apple/05-terminal.png b/assets/store-screenshots/output/apple/05-terminal.png
new file mode 100644
index 0000000000..fae3170671
Binary files /dev/null and b/assets/store-screenshots/output/apple/05-terminal.png differ
diff --git a/assets/store-screenshots/output/google-tablet/01-sidebar.png b/assets/store-screenshots/output/google-tablet/01-sidebar.png
new file mode 100644
index 0000000000..8560682610
Binary files /dev/null and b/assets/store-screenshots/output/google-tablet/01-sidebar.png differ
diff --git a/assets/store-screenshots/output/google-tablet/02-chat.png b/assets/store-screenshots/output/google-tablet/02-chat.png
new file mode 100644
index 0000000000..a8f2342ab3
Binary files /dev/null and b/assets/store-screenshots/output/google-tablet/02-chat.png differ
diff --git a/assets/store-screenshots/output/google-tablet/03-plugins.png b/assets/store-screenshots/output/google-tablet/03-plugins.png
new file mode 100644
index 0000000000..3fe70263ca
Binary files /dev/null and b/assets/store-screenshots/output/google-tablet/03-plugins.png differ
diff --git a/assets/store-screenshots/output/google-tablet/04-review.png b/assets/store-screenshots/output/google-tablet/04-review.png
new file mode 100644
index 0000000000..ae54bfa798
Binary files /dev/null and b/assets/store-screenshots/output/google-tablet/04-review.png differ
diff --git a/assets/store-screenshots/output/google-tablet/05-terminal.png b/assets/store-screenshots/output/google-tablet/05-terminal.png
new file mode 100644
index 0000000000..9921c839dd
Binary files /dev/null and b/assets/store-screenshots/output/google-tablet/05-terminal.png differ
diff --git a/assets/store-screenshots/output/google/01-sidebar.png b/assets/store-screenshots/output/google/01-sidebar.png
new file mode 100644
index 0000000000..abed766b66
Binary files /dev/null and b/assets/store-screenshots/output/google/01-sidebar.png differ
diff --git a/assets/store-screenshots/output/google/02-chat.png b/assets/store-screenshots/output/google/02-chat.png
new file mode 100644
index 0000000000..bd42e5df49
Binary files /dev/null and b/assets/store-screenshots/output/google/02-chat.png differ
diff --git a/assets/store-screenshots/output/google/03-plugins.png b/assets/store-screenshots/output/google/03-plugins.png
new file mode 100644
index 0000000000..e26ecb407e
Binary files /dev/null and b/assets/store-screenshots/output/google/03-plugins.png differ
diff --git a/assets/store-screenshots/output/google/04-review.png b/assets/store-screenshots/output/google/04-review.png
new file mode 100644
index 0000000000..38e9287c6a
Binary files /dev/null and b/assets/store-screenshots/output/google/04-review.png differ
diff --git a/assets/store-screenshots/output/google/05-terminal.png b/assets/store-screenshots/output/google/05-terminal.png
new file mode 100644
index 0000000000..1445744fcb
Binary files /dev/null and b/assets/store-screenshots/output/google/05-terminal.png differ
diff --git a/assets/store-screenshots/raw/ipad/chat.png b/assets/store-screenshots/raw/ipad/chat.png
new file mode 100644
index 0000000000..f8abc88b6c
Binary files /dev/null and b/assets/store-screenshots/raw/ipad/chat.png differ
diff --git a/assets/store-screenshots/raw/ipad/diff.png b/assets/store-screenshots/raw/ipad/diff.png
new file mode 100644
index 0000000000..030946b7ae
Binary files /dev/null and b/assets/store-screenshots/raw/ipad/diff.png differ
diff --git a/assets/store-screenshots/raw/ipad/plugin-sheet.png b/assets/store-screenshots/raw/ipad/plugin-sheet.png
new file mode 100644
index 0000000000..2550f0eecd
Binary files /dev/null and b/assets/store-screenshots/raw/ipad/plugin-sheet.png differ
diff --git a/assets/store-screenshots/raw/ipad/plugin.png b/assets/store-screenshots/raw/ipad/plugin.png
new file mode 100644
index 0000000000..1fd3fbe2d8
Binary files /dev/null and b/assets/store-screenshots/raw/ipad/plugin.png differ
diff --git a/assets/store-screenshots/raw/ipad/sidebar.png b/assets/store-screenshots/raw/ipad/sidebar.png
new file mode 100644
index 0000000000..f348372425
Binary files /dev/null and b/assets/store-screenshots/raw/ipad/sidebar.png differ
diff --git a/assets/store-screenshots/raw/ipad/terminal.png b/assets/store-screenshots/raw/ipad/terminal.png
new file mode 100644
index 0000000000..3c65d7aabf
Binary files /dev/null and b/assets/store-screenshots/raw/ipad/terminal.png differ
diff --git a/assets/store-screenshots/raw/iphone/chat.png b/assets/store-screenshots/raw/iphone/chat.png
new file mode 100644
index 0000000000..5ba23b3282
Binary files /dev/null and b/assets/store-screenshots/raw/iphone/chat.png differ
diff --git a/assets/store-screenshots/raw/iphone/diff.png b/assets/store-screenshots/raw/iphone/diff.png
new file mode 100644
index 0000000000..eab57a68d5
Binary files /dev/null and b/assets/store-screenshots/raw/iphone/diff.png differ
diff --git a/assets/store-screenshots/raw/iphone/files.png b/assets/store-screenshots/raw/iphone/files.png
new file mode 100644
index 0000000000..d2ebaf96b2
Binary files /dev/null and b/assets/store-screenshots/raw/iphone/files.png differ
diff --git a/assets/store-screenshots/raw/iphone/plugin-sheet.png b/assets/store-screenshots/raw/iphone/plugin-sheet.png
new file mode 100644
index 0000000000..012e3877ea
Binary files /dev/null and b/assets/store-screenshots/raw/iphone/plugin-sheet.png differ
diff --git a/assets/store-screenshots/raw/iphone/plugin.png b/assets/store-screenshots/raw/iphone/plugin.png
new file mode 100644
index 0000000000..95beb12d67
Binary files /dev/null and b/assets/store-screenshots/raw/iphone/plugin.png differ
diff --git a/assets/store-screenshots/raw/iphone/sidebar.png b/assets/store-screenshots/raw/iphone/sidebar.png
new file mode 100644
index 0000000000..d0601f3f2f
Binary files /dev/null and b/assets/store-screenshots/raw/iphone/sidebar.png differ
diff --git a/assets/store-screenshots/raw/iphone/terminal.png b/assets/store-screenshots/raw/iphone/terminal.png
new file mode 100644
index 0000000000..b96b192e17
Binary files /dev/null and b/assets/store-screenshots/raw/iphone/terminal.png differ
diff --git a/assets/store-screenshots/render.mjs b/assets/store-screenshots/render.mjs
new file mode 100644
index 0000000000..6695eac559
--- /dev/null
+++ b/assets/store-screenshots/render.mjs
@@ -0,0 +1,413 @@
+// Renders the App Store and Google Play screenshots from the native captures in
+// raw/. Every image is resized with Lanczos to the exact pixel size it occupies
+// on the canvas, and the page renders at device scale 1, so the browser never
+// resamples a capture.
+//
+//   node assets/store-screenshots/render.mjs
+//
+// SF Pro is not redistributable. On macOS it comes from /System/Library/Fonts;
+// elsewhere point SF_FONT_DIR at a folder holding SFNS.ttf copied from a Mac.
+
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { build } from "esbuild";
+import { chromium } from "playwright";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import sharp from "sharp";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const repo = path.resolve(root, "../..");
+const raw = (device, name) => path.join(root, "raw", device, `${name}.png`);
+const output = path.join(root, "output");
+const androidImages = path.join(repo, "fastlane/metadata/android/en-US/images");
+
+// Native captures per device: iPhone 16 Pro Max at 3x and iPad Pro 13-inch at
+// 2x. The frame's screen radius and Dynamic Island are in capture pixels.
+const DEVICES = {
+  iphone: {
+    capture: { width: 1320, height: 2868 },
+    radius: 186,
+    bezel: 22,
+    island: { width: 378, height: 112, top: 33 },
+  },
+  ipad: { capture: { width: 2064, height: 2752 }, radius: 44, bezel: 30, island: null },
+};
+
+// Every title wraps to two lines and every subline fits on one; the renderer
+// fails otherwise, because the device is placed from that fixed text height.
+//
+// Each scene names its capture per device, and a device entry may override the
+// title or subline where the copy depends on the form factor.
+//
+// A callout lifts a region of a capture out of the device. `crop` is in native
+// capture pixels, `zoom` is its size relative to the device screen (capped to
+// the canvas width), and the callout is centred on the spot the crop comes
+// from, moved by `shift` native pixels down the screen.
+const SCENES = [
+  {
+    id: "sidebar",
+    backdrop: "agents",
+    title: "Run many coding agents at once",
+    body: "See which agents are working and which need you.",
+    iphone: { capture: "sidebar" },
+    ipad: { capture: "sidebar" },
+  },
+  {
+    id: "chat",
+    title: "Your full dev environment on your phone",
+    body: "Start agents and follow every edit and command.",
+    iphone: { capture: "chat" },
+    ipad: { capture: "chat", title: "Your full dev environment on your tablet" },
+  },
+  {
+    id: "plugins",
+    title: "Ask an agent to change the app itself",
+    body: "This Deploys sheet is a plugin an agent wrote.",
+    iphone: {
+      capture: "plugin",
+      callout: { from: "plugin-sheet", crop: [0, 1340, 1320, 1400], zoom: 1.04, shift: -1400 },
+    },
+    ipad: {
+      capture: "plugin",
+      body: "This Deploys panel is a plugin an agent wrote.",
+      callout: { from: "plugin-sheet", crop: [670, 1486, 844, 970], zoom: 1.3, shift: -900 },
+    },
+  },
+  {
+    id: "review",
+    title: "Review the diff before you merge",
+    body: "Every file the agent changed, on its own branch.",
+    iphone: {
+      capture: "diff",
+      callout: { from: "files", crop: [0, 1060, 1320, 870], zoom: 1.26, shift: 110 },
+    },
+    ipad: { capture: "diff" },
+  },
+  {
+    id: "terminal",
+    title: "A real terminal in every workspace",
+    body: "Run the tests yourself, on your own machine.",
+    iphone: {
+      capture: "terminal",
+      callout: { from: "terminal", crop: [0, 950, 1320, 460], zoom: 1.35, shift: 110 },
+    },
+    ipad: {
+      capture: "terminal",
+      callout: { from: "terminal", crop: [596, 640, 1010, 412], zoom: 1.35, shift: 650 },
+    },
+  },
+];
+
+// `textTop` is where the text starts when the device is sized by the canvas
+// height. A canvas too narrow for that, like a tablet on 9:16, sizes the device
+// by its width and centres the text and device instead.
+const STORES = {
+  apple: {
+    device: "iphone",
+    width: 1320,
+    height: 2868,
+    textTop: 230,
+    titleSize: 100,
+    bodySize: 46,
+    textWidth: 1120,
+  },
+  google: {
+    device: "iphone",
+    androidScreenshots: "phoneScreenshots",
+    width: 1440,
+    height: 2560,
+    textTop: 150,
+    titleSize: 96,
+    bodySize: 44,
+    textWidth: 1200,
+  },
+  "apple-ipad": {
+    device: "ipad",
+    width: 2064,
+    height: 2752,
+    textTop: 200,
+    titleSize: 124,
+    bodySize: 56,
+    textWidth: 1400,
+  },
+  "google-tablet": {
+    device: "ipad",
+    androidScreenshots: "tenInchScreenshots",
+    width: 1800,
+    height: 3200,
+    textTop: 200,
+    titleSize: 136,
+    bodySize: 60,
+    textWidth: 1560,
+  },
+};
+
+const TITLE_LINE = 1.06;
+const BODY_LINE = 1.3;
+const BODY_GAP = 30;
+// The device starts this far below the text and runs BLEED off the bottom.
+const GAP = 140;
+const BLEED = 40;
+const MARGIN = 56;
+const COLORS = { canvas: "#101615", title: "#ffffff", body: "rgba(255, 255, 255, 0.58)" };
+
+function findFont() {
+  const dirs = [process.env.SF_FONT_DIR, "/System/Library/Fonts", "/Library/Fonts"].filter(Boolean);
+  for (const dir of dirs) {
+    const file = path.join(dir, "SFNS.ttf");
+    if (existsSync(file)) return file;
+  }
+  throw new Error("SF Pro not found. Set SF_FONT_DIR to a folder containing SFNS.ttf from macOS.");
+}
+
+// The device fills the canvas from GAP below the text to just past the bottom
+// edge, so a taller canvas gets a larger device rather than a larger gap. When
+// that would be wider than the canvas, the device takes the full width and the
+// text and the whole device sit centred, still GAP apart.
+function deviceLayout(store, device) {
+  const { capture, bezel } = device;
+  const textHeight = 2 * store.titleSize * TITLE_LINE + BODY_GAP + store.bodySize * BODY_LINE;
+  const tallest = store.height + BLEED - (store.textTop + textHeight + GAP) - 2 * bezel;
+  const widest = store.width - 2 * MARGIN - 2 * bezel;
+  const screenWidth = Math.min(Math.round((tallest * capture.width) / capture.height), widest);
+  const screenHeight = Math.round((screenWidth * capture.height) / capture.width);
+  const scale = screenWidth / capture.width;
+  const width = screenWidth + 2 * bezel;
+  const height = screenHeight + 2 * bezel;
+  const textTop =
+    screenWidth < widest
+      ? store.height + BLEED - height - GAP - textHeight
+      : (store.height - height - GAP - textHeight) / 2;
+  const island = device.island && {
+    width: Math.round(device.island.width * scale),
+    height: Math.round(device.island.height * scale),
+    top: Math.round(device.island.top * scale),
+  };
+  return {
+    textTop: Math.round(textTop),
+    left: Math.round((store.width - width) / 2),
+    top: Math.round(textTop + textHeight + GAP),
+    width,
+    height,
+    bezel,
+    screenWidth,
+    screenHeight,
+    scale,
+    radius: Math.round(device.radius * scale),
+    island,
+  };
+}
+
+function calloutLayout(callout, frame, store) {
+  const [cropX, cropY, cropWidth, cropHeight] = callout.crop;
+  const scale = Math.min(frame.scale * callout.zoom, (store.width - 2 * MARGIN) / cropWidth);
+  const width = Math.round(cropWidth * scale);
+  const height = Math.round(cropHeight * scale);
+  const centreX = frame.left + frame.bezel + (cropX + cropWidth / 2) * frame.scale;
+  const centreY = frame.top + frame.bezel + (cropY + cropHeight / 2 + callout.shift) * frame.scale;
+  const clamp = (value, max) => Math.round(Math.min(Math.max(value, MARGIN), max - MARGIN));
+  return {
+    width,
+    height,
+    left: clamp(centreX - width / 2, store.width - width),
+    top: clamp(centreY - height / 2, store.height - height),
+  };
+}
+
+async function resize(source, crop, width, height, file) {
+  let image = sharp(source);
+  if (crop) image = image.extract({ left: crop[0], top: crop[1], width: crop[2], height: crop[3] });
+  await image.resize(width, height, { kernel: "lanczos3" }).png().toFile(file);
+  return pathToFileURL(file).href;
+}
+
+// Agent marks scattered behind the first panel, from the homepage's featured
+// agents. Each entry is [mark, centre x, centre y, size, rotation], with the
+// centre as a fraction of the canvas and the size as a fraction of its width.
+const AGENT_MARKS = [
+  ["ClaudeCodeIcon", 0.11, 0.075, 0.12, -14],
+  ["CodexIcon", 0.89, 0.1, 0.13, 12],
+  ["PiIcon", 0.07, 0.34, 0.1, 10],
+  ["OmpIcon", 0.93, 0.37, 0.11, -10],
+  ["OpenCodeIcon", 0.08, 0.6, 0.11, -8],
+  ["CursorIcon", 0.92, 0.63, 0.1, 16],
+  ["MuseCodeIcon", 0.07, 0.85, 0.11, 14],
+  ["AntigravityIcon", 0.92, 0.88, 0.12, -12],
+];
+
+async function loadAgentMarks(work) {
+  const bundle = path.join(work, "agent-icons.mjs");
+  await build({
+    entryPoints: [path.join(repo, "packages/website/src/components/agent-icons.tsx")],
+    outfile: bundle,
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    jsx: "automatic",
+  });
+  const icons = await import(pathToFileURL(bundle).href);
+  return Object.fromEntries(
+    AGENT_MARKS.map(([name]) => [name, renderToStaticMarkup(createElement(icons[name]))]),
+  );
+}
+
+function backdrop(store, marks) {
+  return AGENT_MARKS.map(([name, x, y, size, rotation]) => {
+    const side = Math.round(size * store.width);
+    const left = Math.round(x * store.width - side / 2);
+    const top = Math.round(y * store.height - side / 2);
+    return `<div class="mark" style="left:${left}px;top:${top}px;width:${side}px;height:${side}px;transform:rotate(${rotation}deg)">${marks[name]}</div>`;
+  }).join("");
+}
+
+function page({ store, shot, frame, screen, callout, calloutImage, font, marks }) {
+  const behind = shot.backdrop === "agents" ? backdrop(store, marks) : "";
+  const { island } = frame;
+  const notch = island
+    ? `<div class="island" style="top:${island.top}px;width:${island.width}px;height:${island.height}px;margin-left:-${island.width / 2}px;border-radius:${island.height / 2}px"></div>`
+    : "";
+  const lifted = callout
+    ? `<img class="callout" src="${calloutImage}" style="left:${callout.left}px;top:${callout.top}px;width:${callout.width}px;height:${callout.height}px">`
+    : "";
+  return `<!doctype html>
+<meta charset="utf-8">
+<style>
+  @font-face { font-family: "SF Pro"; src: url("${pathToFileURL(font).href}"); font-weight: 1 1000; }
+  * { margin: 0; box-sizing: border-box; }
+  html, body { width: ${store.width}px; height: ${store.height}px; overflow: hidden; background: ${COLORS.canvas}; }
+  body { position: relative; font-family: "SF Pro"; -webkit-font-smoothing: antialiased; }
+  .text { position: absolute; top: ${frame.textTop}px; left: 0; right: 0; margin: 0 auto; width: ${store.textWidth}px; text-align: center; }
+  .mark { position: absolute; color: #fff; opacity: 0.09; filter: grayscale(1) brightness(0) invert(1); }
+  .mark svg { display: block; width: 100%; height: 100%; }
+  h1 { color: ${COLORS.title}; font-size: ${store.titleSize}px; font-weight: 600; line-height: ${TITLE_LINE}; letter-spacing: -0.022em; text-wrap: balance; }
+  p { margin-top: ${BODY_GAP}px; color: ${COLORS.body}; font-size: ${store.bodySize}px; font-weight: 400; line-height: ${BODY_LINE}; letter-spacing: -0.005em; text-wrap: balance; }
+  .device { position: absolute; left: ${frame.left}px; top: ${frame.top}px; width: ${frame.width}px; height: ${frame.height}px; padding: ${frame.bezel}px; border-radius: ${frame.radius + frame.bezel}px; background: #040505; box-shadow: 0 0 0 3px #343b39, 0 0 0 5px #161b1a, 0 60px 140px rgba(0, 0, 0, 0.55); }
+  .screen { position: relative; width: ${frame.screenWidth}px; height: ${frame.screenHeight}px; border-radius: ${frame.radius}px; overflow: hidden; }
+  .screen img { display: block; width: ${frame.screenWidth}px; height: ${frame.screenHeight}px; }
+  .island { position: absolute; left: 50%; background: #000; }
+  .callout { position: absolute; display: block; border-radius: 36px; box-shadow: 0 0 0 2px rgba(255, 255, 255, 0.14), 0 40px 100px rgba(0, 0, 0, 0.6); }
+</style>
+${behind}
+<div class="text"><h1>${shot.title}</h1><p>${shot.body}</p></div>
+<div class="device"><div class="screen"><img src="${screen}">${notch}</div></div>
+${lifted}`;
+}
+
+async function renderStore(browser, name, store, font, marks, work) {
+  const dir = path.join(output, name);
+  await mkdir(dir, { recursive: true });
+  const view = await browser.newPage({
+    viewport: { width: store.width, height: store.height },
+    deviceScaleFactor: 1,
+  });
+  const device = DEVICES[store.device];
+  const frame = deviceLayout(store, device);
+  const files = [];
+  for (const [index, scene] of SCENES.entries()) {
+    const stem = `${name}-${scene.id}`;
+    const shot = { ...scene, ...scene[store.device] };
+    const screen = await resize(
+      raw(store.device, shot.capture),
+      null,
+      frame.screenWidth,
+      frame.screenHeight,
+      path.join(work, `${stem}-screen.png`),
+    );
+    const callout = shot.callout ? calloutLayout(shot.callout, frame, store) : null;
+    const calloutImage = callout
+      ? await resize(
+          raw(store.device, shot.callout.from),
+          shot.callout.crop,
+          callout.width,
+          callout.height,
+          path.join(work, `${stem}-callout.png`),
+        )
+      : null;
+    const html = path.join(work, `${stem}.html`);
+    await writeFile(html, page({ store, shot, frame, screen, callout, calloutImage, font, marks }));
+    await view.goto(pathToFileURL(html).href);
+    await view.evaluate(async () => {
+      await document.fonts.ready;
+      await Promise.all(Array.from(document.images, (image) => image.decode()));
+    });
+    await expectLines(view, "h1", 2, `${stem} title`);
+    await expectLines(view, "p", 1, `${stem} subline`);
+    const file = path.join(dir, `${String(index + 1).padStart(2, "0")}-${scene.id}.png`);
+    await sharp(await view.screenshot())
+      .removeAlpha()
+      .png()
+      .toFile(file);
+    files.push(file);
+    console.log(path.relative(repo, file));
+  }
+  await view.close();
+  return files;
+}
+
+async function expectLines(view, selector, expected, label) {
+  const lines = await view.$eval(selector, (element) =>
+    Math.round(element.clientHeight / parseFloat(getComputedStyle(element).lineHeight)),
+  );
+  if (lines !== expected) throw new Error(`${label} wraps to ${lines} lines, expected ${expected}`);
+}
+
+// Google Play and F-Droid read their screenshots from the Android metadata,
+// which holds links to these renders. Rewriting the links on every render keeps
+// added, removed and renamed panels in step with the App Store.
+async function linkAndroidScreenshots(folder, files) {
+  const dir = path.join(androidImages, folder);
+  await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true });
+  for (const [index, file] of files.entries()) {
+    await symlink(path.relative(dir, file), path.join(dir, `${index + 1}.png`));
+  }
+}
+
+async function renderPreview(rows) {
+  const tile = 440;
+  const gap = 40;
+  const resized = [];
+  let top = gap;
+  let width = 0;
+  for (const files of rows) {
+    let left = gap;
+    let rowHeight = 0;
+    for (const file of files) {
+      const meta = await sharp(file).metadata();
+      const height = Math.round((meta.height * tile) / meta.width);
+      const input = await sharp(file).resize(tile, height, { kernel: "lanczos3" }).toBuffer();
+      resized.push({ input, left, top });
+      left += tile + gap;
+      rowHeight = Math.max(rowHeight, height);
+    }
+    width = Math.max(width, left);
+    top += rowHeight + gap;
+  }
+  const file = path.join(output, "preview.png");
+  await sharp({ create: { width, height: top, channels: 3, background: "#070a09" } })
+    .composite(resized)
+    .png()
+    .toFile(file);
+  console.log(path.relative(repo, file));
+}
+
+const font = findFont();
+const work = await mkdtemp(path.join(os.tmpdir(), "paseo-store-"));
+const browser = await chromium.launch({ headless: true });
+try {
+  const marks = await loadAgentMarks(work);
+  const rows = [];
+  for (const [name, store] of Object.entries(STORES)) {
+    const files = await renderStore(browser, name, store, font, marks, work);
+    if (store.androidScreenshots) await linkAndroidScreenshots(store.androidScreenshots, files);
+    rows.push(files);
+  }
+  await renderPreview(rows);
+} finally {
+  await browser.close();
+  await rm(work, { recursive: true, force: true });
+}
diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md
index 719b0b5468..26c9df8823 100644
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -12,6 +12,27 @@ initializing → idle → running → idle (or error → closed)
 
 Each live agent in `AgentManager` carries a `lastStatus` of `initializing`, `idle`, `running`, or `error`. `closed` is the persisted, resumable state for an agent record that has no live provider runtime. State transitions persist to disk and stream to subscribed clients via WebSocket.
 
+## Daemon restart recovery
+
+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
+agents or workspaces, private helpers and Hub-owned executions retain their own lifecycle.
+Explicit creation environment overrides are saved with the agent and reapplied when reopening.
+
+Startup chooses candidates before anything else reads or repairs persisted running state, then
+opens connections and resumes every candidate in the background. A provider that is slow to reopen
+holds back only its own agent; a failed reopen is logged. Graceful shutdown records intent before
+closing runtimes.
+
+This is best-effort continuation. A crash between saving intent and dispatching a prompt can lose
+or repeat a continuation. Provider resume owns conversation restoration; there is no recovery retry
+loop or exactly-once turn guarantee.
+
 ## Runtime residency
 
 An unarchived agent may be `closed` without being deleted or archived. Closing releases its provider
@@ -115,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.
@@ -139,8 +166,10 @@ caller, child, and host into one watch.
 
 Bootstrap restores these watches after repairing stale running records to `closed` and before opening
 ingress. Reading a closed child's result does not load its provider. A finish notification reports that
-the child's run has settled; the parent decides whether its task is complete. Recovery never resumes
-child work. Archived or deleted parents suppress delivery; parent-owned creation watches also stop
+the child's run has settled; the parent decides whether its task is complete. A child chosen for restart
+recovery is observed only after its resume was sent, so the parent never hears that it was closed
+in between. Archived or deleted parents suppress delivery;
+parent-owned creation watches also stop
 reporting after detachment.
 
 Intent remains stored until the parent's notification dispatch is acknowledged. Dispatch failure
@@ -160,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
 
@@ -211,6 +259,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
@@ -263,17 +332,27 @@ Workspace status is an aggregate activity signal computed **per `workspaceId`**.
 
 Running provider-native subagents contribute `running` to the workspace owned by their parent agent. Their completed, failed, and canceled states stay in the parent's subagents track.
 
-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`.
@@ -288,7 +367,7 @@ parentAgentId === thisAgent.id  AND  !archivedAt
 
 - **Provider subagents** are child executions owned by Claude, Codex, or OpenCode. They are not inserted into `AgentManager` as managed agents. Providers emit a separate descriptor and timeline stream through `agent.provider_subagents.*`; the client keeps that state outside the normal agent store and merges only the presentation rows into the track. A descriptor's optional `parentSubagentId` identifies its direct provider-subagent parent; an absent value identifies a direct child of the managed agent.
 
-Clicking either kind opens a workspace tab. On compact layouts it opens in a [sheet](explorer-sidebar.md#sheets) over the subagents list instead; the sheet hides the composer and shows the agent's model and thinking as one line in its place (`PaneSubtitle`, the row provider subagents already use), and a Paseo subagent's sheet offers **Open as tab** (the full-screen glyph in the header) to get the composer back. A Paseo subagent tab is a normal interactive agent pane. A provider subagent tab is a read-only timeline pane with no composer, archive, detach, rewind, or fork actions. It shows its own direct children in a subagents track. Every subagent pane links back to its parent (`packages/app/src/subagents/parent/`): a pill above the composer when there is one, a parent box in the composer's place when there is not. Both panes use `AgentStreamView`, so message, reasoning, tool-call, and layout rendering stay identical.
+Clicking either kind opens a workspace tab. On compact layouts it opens in a [sheet](explorer-sidebar.md#sheets) instead, replacing the subagents list in place (Back returns to the list); the sheet hides the composer and shows the agent's model and thinking as one line in its place (`PaneSubtitle`, the row provider subagents already use), and a Paseo subagent's sheet offers **Open as tab** (the full-screen glyph in the header) to get the composer back. A Paseo subagent tab is a normal interactive agent pane. A provider subagent tab is a read-only timeline pane with no composer, archive, detach, rewind, or fork actions. It shows its own direct children in a subagents track. Every subagent pane links back to its parent (`packages/app/src/subagents/parent/`): a pill above the composer when there is one, a parent box in the composer's place when there is not. Both panes use `AgentStreamView`, so message, reasoning, tool-call, and layout rendering stay identical.
 
 Provider timelines use the same structural timeline item format but deliberately have a separate lifecycle and transport. A provider thread/session identifier is not a Paseo agent identifier, and closing its tab is always layout-only.
 
diff --git a/docs/agent-stream-disclosure.md b/docs/agent-stream-disclosure.md
new file mode 100644
index 0000000000..9cde8a44ff
--- /dev/null
+++ b/docs/agent-stream-disclosure.md
@@ -0,0 +1,163 @@
+# 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) 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)` (`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.
+
+Following output:
+
+- A hold always detaches the bottom anchor controller (`holdForDisclosure`).
+- 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 in the reading anchor and runs `apply`; the next reading reconcile restores
+the row's top after layout, before paint (`strategy-web.tsx`).
+
+## Native
+
+On compact layouts, tool calls and tool-call groups open a sheet instead of expanding, so they do
+not hold. Summary lines and todo cards 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`).                                                       |
+| Disclosure hold        | LegendList's `maintainVisibleContentPosition`, restoring only the held row.               |
+| 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)` runs in the toggle's event:
+
+1. Mark the row held and detach the controller (`holdForDisclosure`). The pin goes away and
+   LegendList's `maintainVisibleContentPosition` takes over, restoring only the held row
+   (`shouldRestorePosition`). Upstream LegendList anchors only rows from the first fully visible
+   one down, 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, moving the trigger by the row's size change. The LegendList patch counts rows cut off
+   at the top as in view and applies `shouldRestorePosition` to size changes too.
+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 ten 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 5a59eedaa4..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
@@ -98,7 +110,7 @@ The older `android`, `android:development`, and `ios` commands remain aliases fo
 `android:production` still builds and installs a release through Expo; use `build:apk` when you
 need an artifact. `android:clear` removes the generated Android project.
 
-Run `npm run test:android --workspace=@getpaseo/app` to prebuild Android and run native module unit tests. The app CI job runs this command with the Android toolchain.
+Run `npm run test:android --workspace=@getpaseo/app` explicitly with a local Android toolchain to prebuild Android and run native module unit tests. Ordinary CI does not prebuild Android or run these tests.
 
 ### Diagnostic logs without ADB
 
@@ -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
@@ -215,7 +231,8 @@ fastlane/metadata/android/
 │   ├── images/
 │   │   ├── icon.png            (512x512)
 │   │   ├── featureGraphic.png  (1024x500)
-│   │   └── phoneScreenshots/   (1.png, 2.png, ...)
+│   │   ├── phoneScreenshots/   (1.png, 2.png, ... linked to the store renders)
+│   │   └── tenInchScreenshots/ (1.png, 2.png, ... linked to the store renders)
 │   └── changelogs/             (generated — see below)
 ├── ja/
 └── zh-CN/
@@ -223,6 +240,8 @@ fastlane/metadata/android/
 
 Locale directories generally match `packages/app/src/i18n/locales.ts`, but note that `en` becomes `en-US`.
 
+Google Play reads its screenshots from the same folders; see [Store screenshots](release.md#store-screenshots).
+
 F-Droid changelogs are generated from `CHANGELOG.md`. Run `npm run fdroid:changelogs`; `npm run fdroid:changelogs:check` verifies without writing. It is wired into the npm `version` lifecycle, so a release picks it up automatically and `git add -A` stages the result.
 
 One changelog must be generated per-ABI-split, so each version will create **four** identical version-coded entries. F-Droid caps changelogs at 500 characters, so the generator strips some content and adds a link to the full notes.
diff --git a/docs/architecture.md b/docs/architecture.md
index 29f9c7f817..a7ad69c14d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -66,6 +66,9 @@ WebSocket message schemas. Shared configuration schemas belong in protocol leaf
 retaining the daemon's runtime and wire-schema allocations. The server export tests guard
 these dependency trees with tree-shaking disabled to match unbundled production imports.
 
+Terminals do not live in the daemon process: their PTYs run in a detached terminal worker that
+survives daemon restarts, crashes and upgrades. See [terminal-worker.md](terminal-worker.md).
+
 Project identity is daemon-global rather than session-owned. After registry bootstrap, the daemon's
 project Git observer keeps one non-recursive watch on each lexically equivalent active project root
 and listens only for the root `.git` entry, with a slow rescan as a missed-event fallback. It runs
@@ -490,6 +493,16 @@ The supervisor alone publishes its ready worker's endpoint in `paseo.pid`, clear
 
 Worker restart retains supervisor arguments/environment and rereads the configuration file. Updating a package and observing its new worker version do not refresh the running supervisor code; the launcher owns full-process replacement. See [CLI lifecycle contracts](../public-docs/cli.md#daemon-management).
 
+## Outbound networking
+
+The daemon and its plugin processes honor `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY`
+(including lowercase forms, which take precedence). Fetch and relay, Hub, and connected-host WebSockets
+share this policy. Loopback (`localhost`, `127.0.0.1`, `::1`) always goes direct.
+A proxy without a scheme uses HTTP. Invalid values and unsupported proxy schemes
+are treated as unset, with one warning naming the variable in `daemon.log`.
+Agent and terminal environments are unchanged. System proxy settings and SOCKS-only
+`ALL_PROXY` configurations are not supported.
+
 ## Deployment models
 
 1. **Local daemon** (default): `paseo daemon start` on `127.0.0.1:6767`
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 a6c6cefbdc..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.
@@ -232,7 +262,7 @@ For pay-as-you-go, use `ANTHROPIC_API_KEY` with a standard Model Studio key (`sk
 
 Codex talks to OpenAI's Responses API by default. Custom providers that extend `"codex"` can point Codex at any OpenAI-compatible endpoint (OpenRouter, LiteLLM, vLLM, llama.cpp server, an internal gateway, etc.) by setting `OPENAI_BASE_URL` and `OPENAI_API_KEY` in the provider `env`.
 
-Paseo passes those variables through to the Codex app-server process **and** maps them into Codex's thread config under `model_provider` / `model_providers`, because Codex reads provider routing from config rather than from `OPENAI_BASE_URL` alone.
+Paseo passes those variables through to the Codex app-server process **and** maps them into Codex's thread config under `model_provider` / `model_providers`, because Codex reads provider routing from config rather than from `OPENAI_BASE_URL` alone. The generated Codex provider key is `paseo:<provider-id>`, so a Paseo provider such as `ollama` does not override a Codex built-in. Existing custom sessions created with a non-built-in provider key remain available in Import session. Native Codex conversations using a built-in key stay separate from a custom provider of the same name.
 
 ### Setup
 
@@ -260,9 +290,9 @@ Paseo passes those variables through to the Codex app-server process **and** map
 Under the hood, for each custom Codex provider Paseo injects this into Codex's config:
 
 ```toml
-model_provider = "my-codex"
+model_provider = "paseo:my-codex"
 
-[model_providers.my-codex]
+[model_providers."paseo:my-codex"]
 name = "My Codex"
 base_url = "https://custom-relay.example.com/v1"
 wire_api = "responses"
@@ -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 dc65096b66..38c13b63df 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`.
@@ -470,7 +474,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)                                          |                                                                                                                                                                                               |
diff --git a/docs/design.md b/docs/design.md
index fe60cdc53b..2d769e4f2d 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 the width of what it paints (`toolbarSlot`, `toolbarContentSlot`) and its circle reaches into the gaps, so `TOOLBAR_CONTROL_GAP`, 20pt, is the visible space between glyphs. 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`).
+
+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 the 44pt touch slots 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,21 +156,25 @@ 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.
 
-The list+detail pattern is canonical and reused across surfaces. The settings shell (`packages/app/src/screens/settings-screen.tsx`) and the projects screen (`packages/app/src/screens/projects-screen.tsx`) implement it identically:
+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:
 
 - On compact: full-screen list with `<BackHeader>` at the top. Tapping a row pushes a full-screen detail with its own `<BackHeader>` that returns to the list.
-- On desktop: a 320px sidebar on the left holds the list with `surfaceSidebar` background. The content pane on the right holds the selected detail with `<ScreenHeader>`, `<HeaderIconBadge>`, and `<ScreenTitle>`.
+- On wide layouts: a sidebar on the left holds the list with `surfaceSidebar` background. The content pane on the right holds the selected detail with `<ScreenHeader>`, `<HeaderIconBadge>`, and `<ScreenTitle>`.
 
 The branching is one `useIsCompactFormFactor()` check at the top of the screen component. The list and the detail are the same components in both layouts; only the framing changes.
 
 The workspace screen (`packages/app/src/screens/workspace/workspace-screen.tsx`) follows a different but parallel rule: tabs collapse on compact, panes split on desktop. The sidebar (`packages/app/src/components/left-sidebar.tsx`) is overlaid on compact and pinned on desktop.
 
-On a narrow desktop route, app navigation yields to the rendered content topology when the remaining width cannot preserve its center target: Settings keeps its 320px list + 400px detail split, and a workspace Explorer keeps its current visible width plus a 400px center pane. That is a topology decision at the app container, not a second compact breakpoint. Temporary width clamps are render-only; widening restores the user's saved sidebar widths.
+On a narrow window using the wide layout, app navigation yields when the remaining width cannot accommodate the content topology. Settings prefers a 720px split (320px list + 400px detail); its list shrinks first to keep forms readable without reducing the detail below 400px. Explorer reserves at least 240px plus a 360px workspace. These are local space budgets, not compact breakpoints. The app sidebar shrinks from its preferred 320px toward a 200px minimum to leave a 400px center target; its preferred width fits at 720px. Temporary width clamps are render-only; widening restores the user's saved sidebar widths.
 
-Electron window controls are top-corner obstructions, not a compact-layout condition. Rendered surfaces declare which top corners they physically occupy; only those corners receive clearance. Full-window overlays redeclare both corners. A focused split pane owns both corners; if focus restoration temporarily exposes the full split tree, the split boundary reserves one top strip instead of assigning a control rectangle to an arbitrarily narrow leaf. The 720px desktop breakpoint preserves the default 320px sidebar and target 400px center width when the Explorer is closed; it is product policy, not an obstruction gate.
+Electron window controls are top-corner obstructions, not a compact-layout condition. Rendered surfaces declare which top corners they physically occupy; only those corners receive clearance. Full-window overlays redeclare both corners. A focused split pane owns both corners; if focus restoration temporarily exposes the full split tree, the split boundary reserves one top strip instead of assigning a control rectangle to an arbitrarily narrow leaf.
 
 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.
 
 ---
@@ -195,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.
 
@@ -249,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.
@@ -276,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 7eb92375ab..ddebf3ffff 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -273,6 +273,26 @@ Playwright dispatch lateness. Set `PASEO_PROFILE_TYPING_KEYS`, `PASEO_PROFILE_TY
 `PASEO_PROFILE_CPU_PATH` and `PASEO_PROFILE_TRACE_PATH` captures run separately after the latency
 measurements so profiling overhead does not contaminate them.
 
+For diff layout, two benchmarks share one corpus
+(`packages/app/src/git/diff-document/benchmark-corpus.ts`: a real source file, a changelog with
+600-character lines, generated code with ligature punctuation, and JSON). The node bench runs the
+shared document model with the web and native measurers replaced by counters, so it reports how
+many strings each backend would have to shape, which is the cost that survives the move to canvas
+or Skia:
+
+```bash
+cd packages/app && npx vitest bench --project unit src/git/diff-document/model.bench.ts
+```
+
+The browser benchmark opens the same corpus as a working diff, toggles line wrap from the toolbar,
+and reports pointer-down to painted latency, the longest main-thread task, and the `DiffDocument`
+React commit time for cold and warm toggles, then scroll frame times in both modes:
+
+```bash
+cd packages/app && PASEO_DIFF_PERF_E2E=1 npx playwright test --project=browser \
+  e2e/browser/diff-performance.spec.ts -g "toggling line wrap"
+```
+
 Set `PASEO_PROFILE_TYPING_SCENARIO=height-growth` to alternate `Shift+Enter` and printable input.
 That report includes input and composer height changes plus React work grouped into composer,
 stream, and ancestor/root scopes. Ancestor/root timings include descendant work because the Profiler
@@ -542,6 +562,49 @@ patch every build the consumers use: Metro resolves the `react-native` field of
 (`src/*.ts` for `react-native-svg`), while Node and Vitest resolve `main`/`module`
 (`lib/commonjs`, `lib/module`). Patching only `lib/` leaves the app bundle unfixed.
 
+## Dependency overrides and workspace tooling
+
+Root `package.json` `overrides` pin one Expo SDK across the tree (`expo`, `expo-router`,
+`react-native`, …). npm does not apply those overrides to packages it places under a
+workspace's own `node_modules`. When `expo-module-scripts` was declared in
+`packages/expo-two-way-audio`, npm nested it there and its `jest-expo` peer `expo@*` resolved to
+a second, newer Expo SDK and React Native: 200+ duplicate packages nothing imported (#7730).
+Declare tooling that peer-depends on `expo` or `react-native` in the root `devDependencies`,
+where the overrides apply; workspace scripts still find the binary through the root
+`node_modules/.bin`.
+
+## Dependency signature audit
+
+The `quality` CI job runs `npm audit signatures`. It verifies every lockfile package's registry
+signature and, for packages published with provenance, fetches
+`/-/npm/v1/attestations/<name>@<version>` from the registry. Cloudflare caches that document
+for a year. An edge that cached it in the seconds before the registry attached the publish
+attestation keeps serving a document with only the provenance bundle, and npm fails with:
+
+```
+npm error code EMISSINGSIGNATUREKEY
+npm error <name>@<version> has attestations but no corresponding public key(s) can be found
+```
+
+The same package's registry signature verified a moment earlier with the same keys, so the
+key list is intact. The failure names one package, repeats only for that package, and depends
+on the Azure region the runner landed in, because each region maps to one Cloudflare colo. A
+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. 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
 
 The in-app ACP provider catalog pins package-runner entries (`npx`, `npm exec`,
diff --git a/docs/explorer-sidebar.md b/docs/explorer-sidebar.md
index a1778b47b8..b63095e7a0 100644
--- a/docs/explorer-sidebar.md
+++ b/docs/explorer-sidebar.md
@@ -33,25 +33,36 @@ keeps only agents and terminals. A panel kind opts in with `compactSheet` in its
 (`packages/app/src/panels/panel-manifest.ts`), and the layout store's `openTab` decides between
 sheet and tab, so callers open targets the same way on every layout. Each such sheet holds one
 ordinary `WorkspaceTab` (`SheetTab` in the store) and is an `IsolatedBottomSheetModal` like every
-other sheet in the app, so it sits on the one app-wide stack: a sheet opened from any sheet, a
-subagent chosen from the subagents list included, lands on top of it, and closing the top sheet
-(drag, Close, backdrop, or Android Back) uncovers the one below. The list stays open under the
-sheet it opened; see [menus.md](menus.md#selecting-an-item-on-ios) for the row contract.
+other sheet in the app, so it sits on the one app-wide stack: a sheet opened from any sheet lands on
+top of it, and closing the top sheet (drag, Close, backdrop, or Android Back) uncovers the one below.
+
+A subagent chosen from the subagents list is the exception. It opens as a page of the list's own
+sheet and replaces the list in place: Back returns to the list, Close ends both, and Open parent
+closes the list, landing on the pane the list was opened from. The store's `selectSheetTab` describes
+the `SheetTab` a reveal would show without opening it, so the page never enters `sheetsByWorkspace`.
+See [menus.md](menus.md#a-page-that-fills-the-sheet) for the page contract.
 
 The store keeps `sheetsByWorkspace` in opening order and never reorders it, because moving a sheet
 remounts its panel. Revealing a target that already has a sheet uncovers that sheet by closing the
 ones above it, except ones holding unsaved work, which stay where they are. Opening a sheet as a tab
 dismisses the sheets above it, since the tab would sit under them. The stack is not persisted.
 
-Sheets are modal and cover both compact sidebars as well as the workspace. A sheet's header is its drag
-handle, because the panel scrolls on its own and content panning would fight it. Its trailing rail
-holds icon buttons only (`SheetHeaderIconButton`): Open as tab is the full-screen glyph beside
-Close, so the title keeps its width. Compact sheets use the app overlay host: a workspace-local
-host sits behind the app-level left sidebar. The workspace environment bridge preserves existing
-editing sessions, caches, file-link resolution and supported navigation context without moving
-their providers. Keep this capability at the workspace boundary; new sheet callers must not
-assemble provider internals. Wide layouts retain local hosting and pane geometry. Both hosts
-forward the same Gorhom modal queue; neither creates another stack. See
+Both kinds render the same `SheetPane` (`packages/app/src/screens/workspace/sheet-pane/`): the
+header (icon, title, Back when there is a list to return to, Open as tab, Close), the pane, its
+bottom inset, and its focus. Only the container differs, a workspace sheet in `sheet-tabs.tsx` or a
+menu page in `sheet-pane/page.tsx`, so a fix to what a sheet shows lands in one place. The
+container owns Android Back; the pane never subscribes to it.
+
+Sheets are modal and cover both compact sidebars as well as the workspace. The header drags the
+sheet through `SheetDragArea`, because the panel scrolls on its own and content panning would fight
+it. Its trailing rail holds icon buttons only (`SheetHeaderIconButton`): Open as tab is the
+full-screen glyph beside Close, so the title keeps its width. Compact sheets use the app overlay
+host: a workspace-local host sits behind the app-level left sidebar. The sheet pane bridge
+(`useSheetPaneBridge`) preserves existing editing sessions, caches, file-link resolution and
+supported navigation context without moving their providers. Keep this capability at the workspace
+boundary; new sheet callers must not assemble provider internals. Wide layouts retain local hosting
+and pane geometry. Both hosts forward the same Gorhom modal queue; neither creates another stack.
+See
 [floating-panels.md Gotcha 7](floating-panels.md#gotcha-7--a-sheet-cannot-read-context-from-its-call-site).
 
 A sheet holding unsaved work is never implicitly displaced; only its guarded close removes it.
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/floating-panels.md b/docs/floating-panels.md
index f17c59c7c2..4a770f897b 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
@@ -410,6 +413,19 @@ bridges the menu's two contexts; the rest pass `null`.
 
 Wrapping providers _around_ the modal does nothing. They land on the wrong side.
 
+## Gotcha 8 — Read safe-area insets where the overlay draws
+
+A compact sheet tab's body (`SheetBottomInset` in `adaptive-modal-sheet.tsx`) pads the bottom
+inset and gives its content a bottom inset of 0, so the composer dock sits the same in a sheet as
+in a tab. An overlay opened from that content and calling `useSafeAreaInsets()` at its call site
+gets that 0 and draws over the navigation bar.
+
+- A Gorhom sheet reads the inset inside its children, which render in the app's sheet host. See
+  `CompactSheetBody`, `MenuSheetScrollView` and `ComboboxSheetFrame`.
+- An RN `Modal` passes the call site's context straight through, so put a `SafeAreaProvider`
+  inside it and read the inset below that. The modal is its own window, and the provider measures
+  it. See `attachment-lightbox.tsx`.
+
 ## Recipe for a new anchored panel
 
 Before you write a new one, ask:
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 d2c871f74b..a6ff393c6a 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -22,21 +22,24 @@ Authoritative terminology. UI label wins. Don't invent synonyms; use what's here
 - **Sidebar items** — The configurable entries of the app sidebar, in two sections. Header: the rows at the head of the sidebar — New workspace, History, Search, Schedules, and plugin header items. Footer: the full-width rows between Add project and the footer icon row — Usage and plugin footer items. Add project and the icon row (Hosts, Help and support, Settings) are fixed and are not sidebar items. A plugin item may render several rows, such as one per bot; it is still one item that moves and hides as a block. Each section's order and visibility is one per-device preference (`AppSettings.sidebarNavItems`, `AppSettings.sidebarFooterItems`); every item may be off. UI: the Header and Footer cards on the Sidebar settings page. Code: `packages/app/src/sidebar-nav/model.ts` resolves a section, and the sidebar (`components/sidebar/sidebar-nav-rows.tsx`, the footer in `components/left-sidebar.tsx`) and the settings page (`screens/settings/sidebar/sidebar-nav-section.tsx`) read it through `useSidebarNavItems(section)`. Never hardcode one of these entries or add a second place that decides which ones show. Don't confuse with **Explorer sidebar**.
 - **Explorer sidebar** — The dedicated navigation dock containing the Files and Changes trees. UI: "Explorer sidebar". Code: `packages/app/src/workspace-tabs/explorer-sidebar.ts`; persisted pane identifiers retain the `explorer` spelling. See [explorer-sidebar.md](explorer-sidebar.md).
 - **Sheet** — Any bottom sheet; there is one kind and one app-wide stack, so a sheet opened from a sheet lands on top of it and closing it uncovers the one below. Code: `IsolatedBottomSheetModal` (`packages/app/src/components/ui/isolated-bottom-sheet-modal`). Forbidden: "Workspace sheet", "modal sheet" as a distinct kind. See [floating-panels.md](floating-panels.md).
-- **Sheet tab** — A compact-layout sheet holding one file or subagent tab over the workspace without adding it to the tab switcher. UI action: "Open as tab". Code: `SheetTab` and `sheetsByWorkspace` in `packages/app/src/stores/workspace-layout-store.ts`, `SheetTabs` (`packages/app/src/screens/workspace/sheet-tabs.tsx`). See [explorer-sidebar.md](explorer-sidebar.md#sheets).
+- **Sheet tab** — A compact-layout sheet holding one file or subagent tab over the workspace without adding it to the tab switcher. A subagent chosen from the subagents list shows as a page of the list's sheet instead of a sheet of its own. UI action: "Open as tab". Code: `SheetTab` and `sheetsByWorkspace` in `packages/app/src/stores/workspace-layout-store.ts`, `SheetPane` (`packages/app/src/screens/workspace/sheet-pane/`). See [explorer-sidebar.md](explorer-sidebar.md#sheets).
 - **Side pane** — An ordinary right-side workspace pane used for content opened beside the user's work. It closes and participates in workspace splits like every other main-host pane. See [explorer-sidebar.md](explorer-sidebar.md#side-pane). Forbidden: "Side panel".
 - **Directory-backed surface** — A right-sidebar surface whose content is determined by the workspace's `cwd`, so two workspaces on the same directory see identical content: git diff/status, forge change-request info, file preview/explorer contents. Keyed by `(serverId, cwd)`, never `workspaceId`. See [architecture.md](architecture.md#right-sidebar-boundary-directory-backed-vs-workspace-owned).
 - **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.
 - **Agent profile** — A named launch bundle: provider, model, mode, thinking option, feature values, and free-text notes. Applying one writes those values into the **Agent controls** and is then forgotten — there is no selected profile, no default profile, and no drift tracking. The notes are written for orchestrating agents and are what the `list_profiles` MCP tool surfaces. Stored host-wide in daemon config as `agentProfiles`. UI: "Agent profiles". Code: `AgentProfile` (`packages/protocol/src/messages.ts:161`). Carries no system prompt, because a per-agent system prompt can only be set at creation. Forbidden: "Favourite", which this replaced.
 - **Terminal profile** — A named shell command a terminal can launch. Stored host-wide in daemon config as `terminalProfiles`. UI: "Terminal profiles". Code: `TerminalProfile` (`packages/protocol/src/messages.ts:135`), `resolveTerminalProfiles` (`packages/protocol/src/terminal-profiles.ts`). Also selectable as a New Workspace launch target, where the alternative is the chat agent.
 - **Provider** — Agent backend (Claude Code, Codex, Copilot, OpenCode, Pi, Oh My Pi). UI: "Provider". Code: `ProviderSnapshotEntry` (`packages/protocol/src/messages.ts:198`).
+- **Hook** — A plugin lifecycle handler registered with `server.addHook`, named `subject.operation.position` with `before` or `after`; each hook declares whether Paseo waits. See [hooks](../public-docs/plugins/hooks.md).
 - **Usage source** — Plugin registration that discovers accounts and fetches plan usage. Code: `UsageSourceRegistration` (`packages/plugin/src/server/usage.ts`).
 - **Report ID** — Stable daemon-composed identity for one source account: `<sourceId>:<accountKey>`. The source owns the account key; clients treat the whole ID as opaque. Code: `UsageReportEntry.id` (`packages/protocol/src/messages.ts`).
 - **Usage report** — A source's normalized usage for one account, including status and optional windows, balances, and details. Its entry carries the Report ID, account label, and fetch time. Each report renders as one card in the Usage modal, in host Settings, and in an agent's context window details (a hover card on desktop web, a tooltip on native wide screens, a sheet on compact ones), which show only the account that agent runs under, without pins. The hover card and the sheet have Refresh; the native tooltip takes no presses. Code: `UsageReport` (`packages/plugin/src/server/usage.ts`), `UsageCard` (`packages/app/src/usage/card.tsx`), `AgentUsage` (`packages/app/src/usage/agent-usage.tsx`).
+- **Check usage** — Host-wide switch in Usage Settings, on by default. Turning it off stops login discovery and vendor requests on that host for every device. Usage shows an off state with **Turn on**; the sidebar summary and agent usage sections disappear.
 - **Usage (sidebar item)** — The sidebar footer item showing each pinned window's source icon and percent, hidden while no pinned window has data (the footer's Usage icon remains available); both entry points open the Usage modal over the current screen: a dialog on wide layouts, a bottom sheet on compact ones. Usage has no route of its own. Off until the user turns on **Summary in sidebar** (Usage Settings) or the Usage row in Settings > Sidebar; window rows pin only while it is on, and saved pins come back when it is turned on again. A pin is `{ sourceId, windowId }` and shows once per account of that source. Pins and the used/remaining choice are one per-device preference (`AppSettings.usage`) that every usage surface follows. It reads the active workspace's host, else the first connected host with usage sources. Code: `packages/app/src/usage/sidebar-item.tsx`, `usage/usage-modal.tsx`, `usage/pinned.ts`, `usage/preferences.ts`.
 - **Model** — A specific LLM offered by a provider. UI: "Model" / "Select model". Code: `AgentModelDefinition` (`packages/protocol/src/messages.ts:187`).
 - **Tab** — UI surface representing one session inside a workspace. Not a conceptual unit; use **Agent session** when talking about the model. Code: `WorkspaceTabDescriptor` (`packages/app/src/screens/workspace/workspace-tabs-types.ts`).
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 9dc3e26cae..3e29e13ac3 100644
--- a/docs/menus.md
+++ b/docs/menus.md
@@ -52,10 +52,12 @@ is another, with its own icons and hover-revealed actions — but both hand the
 and take `closeOnSelect` to say whether choosing them ends the surface. A row that owns its press
 outright leaves the surface open behind whatever it opened, and skips the iOS wait.
 
-A row whose result opens a sheet passes `closeOnSelect={false}`: the sheet stacks over the menu
-sheet and uncovers it on close, so the menu is where the user lands next. A row that opens a tab
+A row whose result opens a sheet opens it as a page of the menu's own sheet, never as a second
+sheet over it: the row names a [fill page](#a-page-that-fills-the-sheet) with `opensPage`, the page
+replaces the list in place, Back returns to the list, and Close ends both. A row that opens a tab
 closes, because the tab replaces the pane the menu belongs to. The subagents track asks the layout
-store which one a row is (`useSubagentOpensInSheet`), since the answer changes with the layout.
+store which sheet tab a row would show (`useSubagentSheetTab`), since the answer changes with the
+layout; a row with none opens its tab.
 
 ## Pages
 
@@ -101,6 +103,23 @@ The sheet keeps `keyboardBehavior="interactive"`. `extend` grows a sheet to its
 point, and with `enableDynamicSizing` that point is the content's own height — a short page does
 not grow, and the keyboard comes up over the field you are typing into.
 
+## A page that fills the sheet
+
+A page can carry its own content instead of rows: `{ id, fill: true, content }`. Only the sheet
+renders one. It takes the full-sheet snap point (`FULL_SHEET_SNAP_POINTS`) instead of sizing to
+content, and the sheet stops panning on content drags, because the page scrolls on its own and a
+drag would fight that scroll. The page's header drags the sheet instead, through `SheetDragArea`.
+
+The content renders on the far side of the sheet's portal, so it brings its own context bridge,
+built where the page is defined. Sheet tabs are the one user: `useSheetPanePage` turns a `SheetTab`
+into a fill page around the same `SheetPane` the workspace's own sheets render. See
+[explorer-sidebar.md](explorer-sidebar.md#sheets).
+
+Back pops one page. The header's Back and Android Back both call `goBack`, which answers `false` at
+the root so the sheet closes instead. A page whose definition disappears while it is open, such as
+a subagent archived from elsewhere, is pruned from the path, and the sheet falls back to the page
+that opened it.
+
 ## Hover intent
 
 A flyout **overlaps its parent by 5pt** rather than sitting beside it. With a gap there is a strip
@@ -181,15 +200,17 @@ its own.
 
 ## Gotchas
 
-- **Released height.** Reanimated's web entering animation leaves an inline height snapshot on
-  the surface. `AnchoredSurface` clears it, and a `revision` prop re-clears it when content
-  identity changes — a pushed page taller than the one it replaced is clipped without that.
-- **Animate only once placed.** The same snapshot carries top/left, and Reanimated writes it back
-  750ms after mount. `AnchoredSurface` remounts the surface when its position resolves so the
-  entering animation never ends at the off-screen measuring position; on a slow machine that
-  write moved the open menu back off-screen.
+- **Web enters without Reanimated.** For a custom keyframe, Reanimated's web path snapshots the
+  surface's rect when the animation ends and writes it back as inline top/left/width/height 750ms
+  after the start. Whatever moved or resized the surface in between was undone: content that
+  grew once its data arrived left the menu clipped, or hanging over its anchor, until it moved
+  again. `AnchoredSurface` plays the same keyframes through the Web Animations API on web, which
+  leaves no inline style; native keeps the Reanimated `Keyframe`.
+- **Animate only once placed.** `AnchoredSurface` remounts the surface when its position resolves,
+  so the entering animation runs at the final position rather than ending unseen at the
+  off-screen measuring position.
 - **Sheets size to content.** `enableDynamicSizing`, not fixed snap points. A pushed page is
-  rarely the height of the page before it.
+  rarely the height of the page before it. A fill page is the one exception.
 - **The sheet's content is teleported out of the menu's subtree**, so `MenuSheetSurface` rebuilds
   both menu contexts through the sheet's `contextBridge`. Providing them around the modal puts
   them on the wrong side of the portal and every item inside throws. Gotcha 7 in
@@ -205,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 169803c0eb..3dbea66676 100644
--- a/docs/mobile-testing.md
+++ b/docs/mobile-testing.md
@@ -35,6 +35,20 @@ PASEO_MOBILE_E2E_METRO_PORT=62093 npm run test:e2e:mobile
 
 [native-terminal-basic.ios.ad](../packages/app/e2e/mobile/agent-device/native-terminal-basic.ios.ad) and [native-terminal-basic.android.ad](../packages/app/e2e/mobile/agent-device/native-terminal-basic.android.ad) are the smallest examples. Each opens a fresh terminal, types a command at zero delay, submits it, and asserts its distinct output. The app must be connected to a daemon with an active workspace.
 
+For Android background fold recovery, install the release APK on a foldable AVD, open a
+connected workspace, close the keyboard, and run:
+
+```bash
+ANDROID_SERIAL=emulator-5574 node packages/app/e2e/mobile/fold/android.mjs
+```
+
+The AVD must expose `CLOSED` and `OPENED` device states. The test backgrounds the app,
+changes posture, resumes immediately, and asserts compact/wide workspace controls without
+restarting the process. It writes snapshots and native failure state under
+`.dev/agent-device-artifacts/android-fold`. Set `PASEO_MOBILE_APP_ID=sh.paseo` for a
+production package. This needs a native rebuild when the Unistyles patch changes; a Metro
+reload cannot update it.
+
 For Android keyboard continuity, run the current checkout in the app, open an idle terminal
 with an empty prompt, hide its keyboard, and run:
 
@@ -438,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 21a924c4e8..db6151f9de 100644
--- a/docs/plugins.md
+++ b/docs/plugins.md
@@ -99,6 +99,10 @@ Built-in plugins ship from `plugins/<id>/`, with `paseo-plugin.json`, `index.ser
 `packages/server/src/server/plugins/builtin/index.ts`; the workspace, build copy, and CI
 checks cover that registry. Unlisted directories do not load.
 
+The `worktree-include` built-in copies gitignored files selected by
+[`.worktreeinclude`](../public-docs/worktrees.md#copy-local-files-with-worktreeinclude)
+before setup and agents, through `worktree.create.after`.
+
 Desktop packaging ships the entire built-in plugin directory as an external resource,
 including declarations. The external esbuild compiler cannot read Electron's `app.asar`
 filesystem, and packaging dependencies excludes `.d.ts` files needed for import validation.
@@ -333,11 +337,10 @@ export default function contribute(client: PluginClientContext) {
 }
 ```
 
-The contribution function must return cleanup. Server cleanup may be async; Paseo waits for it when
-the plugin is reloaded, disabled, removed, disconnected, or shut down. Cleanup is for resources
-created by plugin code. Paseo removes registered contributions, unmounts surfaces, clears query
-state, rejects pending RPCs, closes the plugin's daemon session, and stops the subprocess. Cleanup
-errors are logged and do not interrupt host teardown.
+The contribution function must return cleanup for resources created by plugin code. Server cleanup
+may be async; Paseo waits for it when stopping the server plugin. Cleanup errors are logged and do
+not interrupt host teardown. Client installation retention and disposal follow the public
+[hosts and lifecycle contract](../public-docs/plugins/reference.md#hosts-and-lifecycle).
 
 Paseo owns the route, screen header, icon validation, close action, theme DTO, layout facts,
 and render error boundary. The contributed component owns the complete body below the header.
@@ -354,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.
@@ -382,6 +403,15 @@ grace. During daemon startup, plugin sessions may connect while application WebS
 paused; the daemon accepts clients only after configured plugins have settled and the initial
 catalog is complete.
 
+The app retains client bundles per host in its file cache (IndexedDB on web), keyed by plugin ID
+and the daemon's SHA-256. A cold client verifies stored contents before advertising their hashes;
+missing or corrupt files request full bundles. Only the latest catalog's bundles remain. Hashing
+uses Expo's native async digest on mobile, avoiding a JavaScript hash loop on Hermes; reading and
+passing the bundle string still costs memory and time once per client lifetime.
+Persistence runs after catalog reconstruction without delaying installation. One write runs at a
+time; while storage is busy, only the newest pending catalog is kept. A failed write leaves the
+in-memory bundles usable, and a later catalog retries persistence.
+
 When the same plugin contribution exists on multiple hosts, Paseo shows it once in the sidebar and
 adds a host picker to the screen header. The selected host supplies the bundle, RPC transport, and
 query cache. Explicit SDK targets follow the [host API contract](../public-docs/plugins/reference.md#discover-hosts-and-target-another-host).
@@ -428,14 +458,22 @@ The [public reference](../public-docs/plugins/reference.md#icons) owns the autho
 
 ## Lifecycle hooks
 
-Server entries register lifecycle observers with `server.on()` and request transforms with
-`server.before()`. The [public reference](../public-docs/plugins/reference.md#lifecycle-hooks)
-owns callback shapes, ordering, and failure behavior. `plugin-examples/lifecycle-logger` registers all
-eleven hooks; `plugin-examples/lifecycle-actions` demonstrates common automation callbacks.
+Server entries register async handlers with `server.addHook(name, handler)`, returning a cleanup
+function. Names follow `subject.operation.position`, ending in `before` or `after`. Waiting is a per-hook
+registry property, independent of position. The [hooks reference](../public-docs/plugins/hooks.md)
+owns payloads, ordering, failure behavior, and examples. `agent.create.before` edits saved
+configuration; `agent.open.before` contributes launch-only `env`, `tools`, and `mcpServers` on
+every open. Executable tool definitions stay in the plugin process; only metadata crosses the boundary.
+
+Worktree placement is resolved before Git source planning, so a hook can change the branch and base
+without undoing fetched refs. Restores use the recorded destination and bypass creation hooks.
+Workspace records decide ownership, including explicit non-ownership after recovery. Without a record,
+ownership checks prefer the marker-verified worktree root over the legacy
+path shape: a plugin can place a worktree several directories below the default worktrees root.
 
 Emit from the operation owner, not a client subscription. Provider history replay must not trigger
-live hooks. Observers must not be awaited inside agent mutations: a callback can send a prompt or
-answer a permission through its own daemon session. Awaiting it there deadlocks that command.
+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.
 
 ## Contribute a provider
 
@@ -530,7 +568,7 @@ string is never inline SVG or a URL.
 
 Register a usage source from `index.server.ts` with `server.registerUsageSource()`. Import `UsageSourceRegistration` and normalization helpers from `@getpaseo/plugin/server/usage`. The plugin owns account discovery, harness labels, and credential-store reads; the daemon owns account grouping and the fetch cache. Agent popovers use only the agent's own login. The host-wide Usage modal falls back across an account's logins; any success shows usage only, and all failures show every login's labeled error and remedy. Follow the [usage source discovery contract](../public-docs/plugins/reference.md#usage-sources). The resolved launch environment crosses into the trusted, unsandboxed plugin subprocess for session discovery. Usage queries never run lifecycle hooks. Inputs are validated in the plugin process and remain daemon-side. `icon` uses the same SVG file rules as provider icons.
 
-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.
+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.
 
 ## Contribute sidebar items
 
@@ -606,7 +644,10 @@ Request observation with `client.paseo.agents.list({ subscribe: {} })` and consu
 demand. Provider and project `subscribe()` calls establish their own demand. On capable daemons, each
 list-and-subscribe call has its own server ID, even for the same query. Older daemons retain
 [shared delivery behavior](protocol-compatibility.md#owned-observations). Handle snapshots
-also run after reconnect; replace your view before applying its subsequent updates. The installation
+also run after reconnect; replace your view before applying its subsequent updates. An installation
+stays loaded during a dropped connection while the app retains its `DaemonClient` object. An
+unchanged installation does not rerun setup on reconnect, so refresh state from those snapshots
+rather than from setup. Switching connections replaces the client object and reinstalls plugins. The installation
 owns every observation created through its API and releases them on unload, including setup failure.
 Mounted surfaces and command invocations have shorter API lifetimes.
 
diff --git a/docs/protocol-compatibility.md b/docs/protocol-compatibility.md
index e5ba1db2a3..0fa4fed63d 100644
--- a/docs/protocol-compatibility.md
+++ b/docs/protocol-compatibility.md
@@ -2,7 +2,7 @@
 
 The app and the daemon are separate products that ship separately. A user updates the app from an app store or a desktop auto-update; they update the daemon when they feel like it. Every combination happens in the wild: new app against an old daemon, old app against a new daemon, and both sides months apart.
 
-In development both sides are always the same version, which is why this is the constraint contributors miss most often.
+Development can have the same version drift: an app reload picks up new code while a long-running daemon keeps its loaded version. Check the connected daemon version when diagnosing behavior that crosses this boundary.
 
 Two contracts follow from it.
 
@@ -38,7 +38,7 @@ The app checks for the capability and either runs the feature or tells the user
 - **No defensive branches spread through the feature.** Detection happens in one place, and everything downstream reads a clean shape.
 - Capability flags live in `features` on the `server_info` message (`packages/protocol/src/messages.ts`, the `server_info` schema).
 
-Existing functionality keeps working across versions because of the protocol contract. Gating a new feature never substitutes for that.
+Existing functionality keeps working across versions. Never gate an established request on a new enhancement: negotiate the optional enhancement at the client boundary and preserve the existing request for older hosts. Whole-turn pagination can require a capability; reading conversation history cannot.
 
 ## Client capability ownership
 
@@ -52,6 +52,47 @@ On capable daemons, connecting creates no timeline or event demand. Client subsc
 release it on unsubscribe, and restore it after reconnect. Raw message observers inspect traffic
 without requesting streams. Application caches and which agents are visible remain caller-owned.
 
+## Terminal ANSI replay
+
+Terminal replay intentionally drops JSON-era apps, an exception to the general cross-version policy:
+use app v0.1.81 or newer. Earlier apps omit `restore` and reject ANSI Restore (`0x05`), so they show
+only subsequent live output, without the existing screen or history.
+
+`terminal_chunked_replay` is SDK-owned delivery behavior. The daemon sends new binary opcodes only to a source
+advertising the capability. The SDK keeps the established subscribe request against older
+ANSI hosts and normalizes their single Restore frame into begin/data/end. `observeTerminal` defaults
+to an explicit full snapshot: omitting restore on an ANSI-era host selects its discarded JSON path.
+Explicit caller restore modes and history counts pass through unchanged. JSON snapshot
+wire declarations remain accepted, but JSON snapshot frames have no rendering runtime.
+Terminals require `terminal-restore-modes`; older hosts show an update message without attaching.
+
+## Binary chunking
+
+`binary_chunking_v1` in hello and optional `server_info.features.binaryChunkingV1`
+negotiate connection-scoped framing. Application serializers and routed envelopes use
+the same boundary. Small messages and handshakes keep their existing representation.
+Older peers retain existing frame limits.
+
+The reserved binary opcode `0x31` is followed by version `1`, original kind
+(`0` text, `1` binary), and START/END flag bits `0`/`1`. Remaining bytes are an
+unchanged slice. There is no total length or chunk count; a future receiver can
+consume slices incrementally. Today the receiver buffers up to the existing
+100 MiB logical limit and decodes UTF-8 only after END. Transfers cannot interleave.
+Disconnect clears partial state and negotiation.
+
+The lower transport supplies its plaintext frame budget, including encryption
+overhead. The sender waits for drain between chunks while ordinary messages keep
+the existing delivery path. Slow-client protections count messages queued behind
+an active transfer as well as bytes already in the socket.
+The framing module never selects an encryption construction.
+
+Native uploads retain the platform's existing queue limits. React Native's
+WebSocket does not report its queued bytes, so the client cannot wait for native
+drain. Android's installed OkHttp transport closes when a send would put more
+than 16 MiB in its queue. The native transport disables outbound chunking, including
+on routed channels, and retains its existing single-frame admission errors.
+Inbound chunking remains enabled; daemon-to-native responses use the daemon's paced writes.
+
 ## Owned observations
 
 `owned_subscriptions` and `server_info.features.ownedSubscriptions` negotiate the source-owned
diff --git a/docs/providers.md b/docs/providers.md
index 1a43558ae3..60fb75a785 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -89,7 +89,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.
 
@@ -507,6 +507,8 @@ interface AgentSession {
 }
 ```
 
+`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 83a419b8ce..4ddeb04c28 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -6,10 +6,10 @@ All workspaces share one version and release together.
 
 A release has exactly two steps. The agent does the first, the user authorizes the second.
 
-**Preparation** (local, reversible — agent does this):
+**Preparation** (reversible — agent does this):
 
 - format, lint, typecheck all green
-- resolve the release source to one commit and confirm that commit's existing CI is green
+- resolve the [release base](#release-base-and-source), get the [release inventory](#release-inventory) approved when one applies, and confirm CI for the resulting release source is green
 - classify the diff from the previous stable to the release source as patch or minor, then show the
   target version and rationale to the user
 - draft the changelog, show it to the user, wait for review
@@ -17,9 +17,10 @@ A release has exactly two steps. The agent does the first, the user authorizes t
 
 **Go-ahead** (user says "go ahead"):
 
-- commit the approved release inputs locally
-- run the release, which publishes npm and pushes the prepared branch and tag
+- commit the approved release inputs locally on the release branch
+- run the release, which publishes npm and pushes the release branch and tag
 - create the release heartbeat immediately and babysit it to completion
+- [reconcile `main`](#reconcile-main) with what shipped
 
 Rules that apply to both steps:
 
@@ -27,56 +28,128 @@ Rules that apply to both steps:
 - No code changes bundled into the changelog commit or the release commit. Code shims live in their own commit, reviewed on their own merits.
 - A sanity-check finding is information, not a directive. The agent surfaces it; the user decides.
 - Invoking a release skill is intent to start the flow, not blanket authorization to publish.
+- An approval the user already gave covers what it names, such as an explicit PR selection or authorization to release autonomously. Do not ask for it again.
 - If the user asks for a release preview, show the prospective changelog/release contents and answer questions, but do not commit, tag, publish, or run release commands until they explicitly authorize the release.
 
-## Release source and CI
+## Main stays open
 
-The default release source is `origin/main`. Fetch `origin`, then record the
-resolved commit. The default release checkout is a clean local `main` whose
-`HEAD` equals `origin/main`.
+Merge normal PRs into `main` at any time, including while a beta soaks or a release is being
+finalized. Each release builds in a short-lived release workspace, and its published tag records
+the shipped source.
 
-An explicit user instruction can select another ref, such as a hotfix commit or
-tag. Resolve that ref once and apply every source, diff, and CI check to that
-commit instead of `origin/main`.
+## Choosing a path
 
-Before making release-preparation commits, confirm the existing CI run for the
-resolved commit is green. Pending CI is watched to completion. Release
-preparation then stays local through the changelog, any explicitly requested ACP
-catalog update, lockfile preparation, and the version commit. After approval,
-commit the prepared inputs locally and run the release command. Its branch and
-tag push is the one remote release batch and starts CI for the complete release
-commit.
+The user decides when the changes on `main` warrant a release and how much risk it takes:
 
-## Release branch discipline
+1. **Direct stable release** for a low-risk batch of polish and bug fixes. Stable desktop updates
+   already ramp over 36 hours (see [Staged rollout](#staged-rollout-stable-channel)), and store
+   review often takes about a day, with no guaranteed timing.
+2. **Beta flow**, the default for changes that need testing. Release candidates on the `beta`
+   channel. Each beta folds into the series' single changelog entry, publishes npm only on the
+   explicit `beta` dist-tag, and stays behind the Stable/Beta switch on `/download`.
 
-While you finalize a release on `main`, use a temporary `next` branch for work intended for the following
-release. This applies to both beta and stable releases.
+A beta follows these defaults, which the user can explicitly override:
 
-- Create each new `next` from freshly fetched `origin/main`. Reuse it while active.
-- "This goes to next" means create the PR against `next` or retarget an existing
-  PR, and keep that destination through delivery.
-- Keep `next` current by merging `origin/main` into it as release fixes land.
-  Avoid rebasing this shared branch because agents and open PRs depend on its history.
-- After the release ships, bring `next` up to date and open a `next` → `main` PR.
-  Pass CI and merge without squashing away the individual PR commits needed for
-  the changelog. Retarget remaining PRs based on `next` to `main` and delete the integrated
-  `next`. Create it fresh when needed again.
+- Soak a beta at least 24 hours before promotion. Soak longer for risky or breaking changes, or
+  while feedback is open. Changes added in a later beta get their own soak; earlier soak time does
+  not count for them.
+- A follow-up beta carries regressions, fixes, and polish for what that beta delivers. Unrelated
+  work on `main` and pre-existing bugs wait for a later release unless the user explicitly selects
+  them.
+- Promotion ships the tested beta's product content unchanged and does not pull from `main`.
+  Adding a product change needs the user's explicit selection and a new beta, which soaks again.
+- During a soak, ship urgent stable regressions and compatibility or provider model updates as a
+  [stable hotfix](#release-base-and-source) from the latest stable tag. The beta keeps its own
+  pace.
 
-**Setup still needed:** PR checks run for every base branch, but CI, Docker, and Nix
-push runs target only `main`, and GitHub permits only squash merges. Enable
-required-check protection for `next`, CI on its pushes, and merge commits for the
-integration PR. Handle PR
-base changes (`edited` events) so retargeting runs checks against the new base;
-GitHub's default PR events do not cover this. Deployment triggers stay unchanged.
+npm dist-tags are independent pointers:
 
-### Hotfix from a release tag
+- A beta release publishes with `--tag beta` and moves only `beta`; `latest` remains on the
+  newest stable.
+- A stable release publishes to `latest`. Move `beta` to it as well when the stable version is
+  newer than the version `beta` points to, which covers promotions and direct stable releases, so
+  `@getpaseo/cli@beta` users never sit behind stable. A stable hotfix on an older line leaves
+  `beta` on the active newer beta.
 
-If `main` contains changes you do not want to release, branch from the affected
-release tag and cherry-pick only the required fixes. Run CI on that branch, then
-use the normal release flow with it as the explicit source, choosing a new patch
-or beta version. Ensure the fixes and changelog also reach `main` and any active
-`next`, preserving newer development and version changes there. This is a
-short-lived hotfix branch, not another maintained release track.
+## Release base and source
+
+The release base is the tag or commit a release workspace starts from. The release source is the
+base plus any approved cherry-picks, and every source, diff, and CI check uses it.
+
+| Release                                                  | Base                                                         | Changes on top               |
+| -------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------- |
+| Starting release: first beta of a line, or direct stable | `origin/main`, captured once                                 | None                         |
+| Follow-up beta                                           | The selected published beta tag, normally the series' latest | Approved commits from `main` |
+| Promotion                                                | The beta tag being promoted                                  | None by default              |
+| Stable hotfix                                            | The latest appropriate stable tag                            | Approved commits from `main` |
+
+An explicit user instruction can select another base.
+
+1. Fetch `origin` with tags and resolve the base to one commit.
+2. Create the release workspace through Paseo MCP on a new branch from the base, named
+   `release/vX.Y.Z` or `release/vX.Y.Z-beta.N` for the version being cut. Run the release from
+   this workspace: `release:push` pushes `HEAD` to the current branch.
+3. Cherry-pick the approved commits in their `main` order with `git cherry-pick -x`, so each
+   commit records the `main` commit it came from. Include the prerequisites the inventory listed.
+   Resolve conflicts within the approved changes and report how. A resolution that needs new
+   behavior is a scope addition: surface it for selection.
+4. Confirm CI for the release source. When the source is a commit whose CI already passed (the
+   captured `origin/main`, or the beta tag being promoted), use that run and watch pending CI to
+   completion. Otherwise push the release branch and run `gh workflow run ci.yml --ref <branch>`,
+   because CI push runs target only `main`.
+5. Keep the changelog, any explicitly requested ACP catalog update, lockfile preparation, and the
+   version commit local until the go-ahead. The release command pushes the release branch and tag
+   as one batch, and the tag push starts the release workflows. Then run
+   `gh workflow run ci.yml --ref <branch>` so CI covers the complete release commit.
+6. [Reconcile `main`](#reconcile-main).
+
+A stable hotfix can take the version a patch beta line would promote to, such as `0.13.3`
+shipping while `0.13.3-beta.2` soaks. Never republish or reuse a shipped version. Continue the line
+as the next unused patch beta, `0.13.4-beta.1`, from the tested beta tag. No `version:all:*` mode
+computes that from a prerelease, so follow the [manual steps](#manual-step-by-step) with
+`npm version 0.13.4-beta.1 --include-workspace-root --message "chore(release): cut %s"` and
+`npm run release:publish:beta`. Record the tested beta tag as its source so its soak still counts
+for the unchanged content.
+
+## Release inventory
+
+When the user asks for a follow-up beta or a promotion, list what `main` has that the base does
+not, then get the batch approved. There is no release label or queue.
+
+1. Find the commits on `origin/main` whose patches are not in the base tag:
+
+   ```bash
+   git log --cherry-pick --right-only --no-merges --format='%h %s' <base-tag>...origin/main
+   ```
+
+   Patch equivalence recognizes commits already cherry-picked into the tag, so trust the tag
+   content over PR state or branch names.
+
+2. Present a short include/defer list. Link each PR and give one plain reason. List separately the
+   prerequisites an included PR depends on and anything that adds scope beyond what the beta
+   delivers. For each fix that shipped in a stable hotfix after the beta's base, confirm the beta
+   preserves its behavior, directly or through a superseding change. List the missing ones for
+   explicit selection; adding one to a promotion needs a new beta.
+3. Wait for the user to approve the batch, unless an explicit selection or autonomous
+   authorization they already gave covers it.
+
+For a promotion, every item defaults to defer.
+
+## Reconcile main
+
+After the release push, open a PR into `main` that brings in what shipped and keeps newer
+development on `main`:
+
+- The shipped `CHANGELOG.md` and `CHANGELOG.zh-CN.md` entries, exactly as tagged. A beta or
+  promotion entry replaces the series entry on `main`. A stable hotfix on an older line goes
+  below any newer entries.
+- The shipped version in every `package.json` and `package-lock.json`, unless `main` already
+  carries a newer version, plus the F-Droid changelog files a stable release generates.
+- No claims about unshipped work: a shipped entry describes only the tagged content, and notes
+  `main` holds for changes that have not shipped stay out of it.
+
+Delete the release branch once the PR merges. The tag is the record of shipped source; Paseo
+maintains no release track besides `main`.
 
 ## ACP catalog updates
 
@@ -91,21 +164,6 @@ ACP catalog work enters a release through an explicit user request:
 The release authorization covers the requested ACP commit. It ships in the same
 release push as the changelog and version commit.
 
-## Two paths
-
-There are two supported release paths:
-
-1. **Direct stable release**: you are ready to ship the resolved release source to everyone immediately (default `origin/main`).
-2. **Beta flow**: release candidates on the `beta` channel. Each beta folds into the series' single changelog entry, publishes npm only on the explicit `beta` dist-tag, and stays behind the Stable/Beta switch on `/download`.
-
-Paseo has one linear release track even though npm dist-tags are independent
-pointers. The npm invariant is:
-
-- A beta release moves only `beta`; `latest` remains on the newest stable.
-- A stable release moves both `latest` and `beta` to that stable version. This
-  keeps users who install `@getpaseo/cli@beta` on the newest Paseo release after
-  a beta is promoted or superseded by a direct stable release.
-
 ## Release version decision
 
 Every fresh release starts by classifying the full diff from the previous
@@ -133,7 +191,7 @@ as described in **Fixing a failed release build**.
 
 Before running any stable release command:
 
-- Make sure the resolved release source passed CI, the approved release inputs are committed locally on the intended branch, and the working tree is clean.
+- Make sure the release source passed CI, the approved release inputs are committed locally on the release branch, and the working tree is clean.
 - **Run `npm run format`, `npm run lint`, and `npm run typecheck` and commit any resulting changes BEFORE you start any `release:*` command.** `release:check` runs `npm install --workspaces --include-workspace-root` as part of `release:prepare`, which can mutate `package-lock.json` (e.g. churning `"dev": true` markers on optional deps). The next step, `version:all:*`, runs `npm version` which aborts when the working tree is dirty. If this happens mid-flight you have to commit the lockfile churn before retrying — and the pre-commit format hook will reject a lockfile-only commit because oxfmt internally skips `package-lock.json` while lefthook's glob still matches it. Avoid the whole mess by running format/lint/typecheck first, then `release:prepare` once on its own to absorb any lockfile churn into a normal commit, then start the release.
 - Do not use a release command as a substitute for checking whether the current commit is actually ready.
 
@@ -145,9 +203,9 @@ npm run release:minor
 
 This bumps the version across all workspaces, runs checks, publishes to npm, and pushes the branch + tag. The tag push triggers `Desktop Release`, `Android APK Release`, `Docker`, and `Release Notes Sync` on GitHub Actions. The workflows create the GitHub Release as a draft while builds and release-note sync run. EAS picks up the same tag via the EAS GitHub app and starts the iOS + Android store builds in parallel (see "Mobile builds (EAS)" below) — there is no mobile-release workflow under `.github/workflows`.
 
-After the stable release succeeds, move npm's `beta` pointer to the new stable
-version for every published package. This changes dist-tags only; do not
-republish the packages:
+After the stable release succeeds, check `npm view @getpaseo/cli dist-tags`. When the new stable
+is newer than `beta`, move `beta` to it for every published package. This changes dist-tags only;
+do not republish the packages:
 
 ```bash
 PASEO_VERSION=$(node -p "require('./package.json').version")
@@ -156,8 +214,8 @@ for package in highlight relay protocol client plugin server cli; do
 done
 ```
 
-Verify both npm tags now resolve to `PASEO_VERSION` before considering the
-stable release complete.
+Verify `latest` resolves to `PASEO_VERSION`, and `beta` resolves to `PASEO_VERSION` or the
+active newer beta, before considering the stable release complete.
 
 The Docker workflow builds images from the checked-out source tree on pull requests and on `main` as non-publishing checks. Stable `vX.Y.Z` tag pushes publish `ghcr.io/getpaseo/paseo:X.Y.Z` and `ghcr.io/getpaseo/paseo:latest`; beta `vX.Y.Z-beta.N` tag pushes publish only `ghcr.io/getpaseo/paseo:X.Y.Z-beta.N` and never move `latest`.
 
@@ -175,7 +233,7 @@ npm run version:all:patch
 npm run version:all:minor
 npm run release:publish      # Publish to npm
 npm run release:push         # Push HEAD + tag (triggers CI workflows)
-# Then move npm's beta dist-tag to this stable version using the command above.
+# Then move npm's beta dist-tag to this stable version when it is newer than beta (see above).
 ```
 
 ## Beta flow
@@ -223,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
 
@@ -305,8 +366,8 @@ macOS 13 maps to Darwin 22. The two values use different version domains; do not
 
 iOS and Android store builds are not in `.github/workflows`. They are triggered by the EAS GitHub app the moment the `v*` tag is pushed:
 
-- **Android (Play Store)** — EAS builds with profile `production` and auto-submits to the Play Store via `eas submit` (EAS-managed credentials, no Fastlane).
-- **iOS (TestFlight + App Store)** — EAS builds with profile `production`, uploads once through a `testflight` job, distributes the build to the `Paseo Beta` external group with Beta App Review submission, and a Fastlane lane submits that same build for App Store review.
+- **Android (Play Store)** — EAS builds with profile `production` and auto-submits to the Play Store via `eas submit` (EAS-managed credentials). A Fastlane lane then replaces the store screenshots.
+- **iOS (TestFlight + App Store)** — EAS builds with profile `production`, uploads once through a `testflight` job, distributes the build to the `Paseo Beta` external group with Beta App Review submission, and a Fastlane lane uploads the store screenshots and submits that same build for App Store review.
 - **Android APK (GitHub Release asset)** — separate, via `.github/workflows/android-apk-release.yml`. This is the only Android-related workflow that lives in this repo.
 
 EAS uses the local app version source. `packages/app/app.config.js` derives the native version from the package version. Android `versionCode` is `major * 1_000_000 + minor * 1_000 + patch`. iOS reserves 1,000 build slots per app version: beta `N` uses slot `N`, and stable uses slot `999`. For example, `0.2.6-beta.2` appears in App Store Connect as version `0.2.6` build `2006002`; stable uses build `2006999`. Rebuilding the same tag produces the same native build number; if a store has already accepted a binary and you need a different binary, cut the next beta or patch instead of relying on EAS remote auto-increment.
@@ -317,6 +378,17 @@ Stable iOS releases use one binary for two Apple review paths: Beta App Review f
 
 There is no mobile-release workflow under `.github/workflows`. The EAS GitHub app reads the workflows under `packages/app/.eas/workflows` and handles tag triggering directly.
 
+### Store screenshots
+
+Each stable release publishes the screenshots committed under `assets/store-screenshots/output/` (see [its README](../assets/store-screenshots/README.md) for how they are made). To change the store screenshots, re-render and commit them before you tag.
+
+- **App Store:** `submit_review` uploads `output/apple/` and `output/apple-ipad/` to the version it submits, replacing that version's `en-US` screenshots. Apple ties screenshots to an app version, so a version that is already live keeps the ones it shipped with. `Resubmit iOS for App Store review` uploads them again.
+  - When `submit_review` fails with `appStoreVersions … is not in valid state`, the reason is in the API error's `meta.associatedErrors`, which fastlane does not print. Read it with a `POST /v1/reviewSubmissionItems` against the version. A required age-rating question that Apple added, such as `socialMedia`, fails this way; answer it under App Information > Age Rating in App Store Connect, then resubmit.
+- **Google Play:** `upload_android_screenshots` runs `fastlane android upload_screenshots` after `submit_android`. It replaces only the `en-US` phone and 10-inch tablet screenshots, never the listing text or changelogs, and skips images whose checksum already matches. The lane stages only `en-US`: supply uploads every locale folder in one edit, and Play rejects F-Droid locales such as `ja`, which fails the whole edit. `Upload Google Play screenshots` reruns the step for the current release without a rebuild.
+- **F-Droid:** reads the same files as Google Play. `fastlane/metadata/android/en-US/images/phoneScreenshots/` and `tenInchScreenshots/` hold symlinks to the Google renders. `render.mjs` rewrites them on every render, so added or renamed panels reach Google Play and F-Droid as well.
+
+Fastlane cannot use the Play key Expo stores for `eas submit`. The Play lane reads its own copy of the same service-account key from the `GOOGLE_PLAY_JSON_KEY` file secret in the EAS `production` environment, and that service account needs the Play Console permission **Manage store presence**.
+
 ### Watching mobile builds from the terminal
 
 Use the EAS CLI from `packages/app/`:
@@ -359,6 +431,7 @@ For the `Release Mobile` EAS workflow, these jobs must pass:
 - `submit_ios_for_review` — iOS build submitted for App Store review via Fastlane
 - `build_android` — Android store binary built
 - `submit_android` — Android binary submitted to the Play Store
+- `upload_android_screenshots` — Google Play screenshots replaced from the repo
 
 Do not treat `build_ios: SUCCESS` or `distribute_ios: SUCCESS` as a completed iOS release. `submit_ios_for_review: FAILURE` means the iOS release is blocked even if the build is visible in TestFlight.
 
@@ -477,7 +550,7 @@ git tag -f android-v0.1.28 HEAD && git push origin android-v0.1.28 --force
 git tag -f v0.1.29-beta.2 HEAD && git push origin v0.1.29-beta.2 --force
 ```
 
-This ensures the checkout ref matches the actual code on `main` with the fix included.
+This ensures the checkout ref matches the code you want built, with the fix included.
 
 - `vX.Y.Z` or `vX.Y.Z-beta.N` rebuilds the full tagged release
 - `desktop-vX.Y.Z` rebuilds desktop for all desktop platforms only
@@ -620,7 +693,7 @@ Rules:
 
   This returns every distinct GitHub login that authored or co-authored a commit in the PR. Use those logins for attribution. Fall back to `gh pr view N --json author` only if the commits command returns nothing (which should not happen for merged PRs).
 
-  When listing PR numbers, `git log --format='%H %s' v<previous>..<release-source-sha> | grep -E '\(#[0-9]+\)$'` pulls the PR number out of squash commit subjects.
+  When listing PR numbers, `git log --cherry-pick --right-only --no-merges --format='%H %s' v<previous>...<release-source-sha> | grep -E '\(#[0-9]+\)$'` pulls the PR number out of squash commit subjects and skips commits the previous stable already shipped as cherry-picks.
 
 ## Changelog ordering
 
@@ -652,11 +725,11 @@ Every entry covers `previous stable release → release source`: first beta, lat
 
 ### Beta release
 
-- [ ] The resolved release source is the intended commit (default `origin/main`) and its existing CI is green
+- [ ] The release base and changes match the [release base table](#release-base-and-source) and any approved [inventory](#release-inventory), and CI for the release source is green
 - [ ] Every PR in the release range has been opened, and its full description and every linked issue have been read before drafting the changelog
 - [ ] Fold this beta into the series' single `CHANGELOG.md` entry (heading `## X.Y.Z-beta.N - YYYY-MM-DD`, previous stable → release source), review it against the changelog policy, get approval, and commit it with its [`CHANGELOG.zh-CN.md` translation](#changelog-translations) before cutting the release
 - [ ] The diff from the previous stable to the resolved release source is classified as patch or minor, with the target version and rationale approved
-- [ ] Release preparation stayed local until the approved release command pushed the complete branch and tag
+- [ ] The changelog, ACP, lockfile, and version commits stayed local until the approved release command pushed the release branch and tag
 - [ ] `npm run release:beta:patch`, `npm run release:beta:minor`, or `npm run release:beta:next` completes successfully
 - [ ] Every GitHub Actions run for the complete release commit and tag is green
 - [ ] npm shows the version under the `beta` dist-tag, not `latest`
@@ -667,22 +740,24 @@ Every entry covers `previous stable release → release source`: first beta, lat
 - [ ] GitHub `Docker` workflow is green and the versioned beta image is published without moving `latest`
 - [ ] GitHub `Release Notes Sync` mirrored the beta entry into the prerelease body
 - [ ] EAS `Release iOS Beta` completed its build, TestFlight distribution, external beta group, and Beta App Review path
+- [ ] The [reconcile PR](#reconcile-main) brought the shipped changelog entries and version into `main`
 - [ ] The release heartbeat was created after the tag push and deleted only after every item above passed
 
 ### Stable release (or promotion)
 
 - [ ] Run the pre-release sanity check (see above) and address any findings
 - [ ] The diff from the previous stable to the resolved release source is classified as patch or minor, with the target version and rationale approved
-- [ ] The resolved release source is the intended commit (default `origin/main`) and its existing CI is green
+- [ ] The release base and changes match the [release base table](#release-base-and-source) and any approved [inventory](#release-inventory), and CI for the release source is green
+- [ ] A promotion ships the tested beta's product content after its soak, unless the user explicitly overrode either default
 - [ ] Every PR in the release range has been opened, and its full description and every linked issue have been read before drafting the changelog
 - [ ] Ensure the approved release inputs are committed locally and the git worktree is clean before running any release command
 - [ ] Ensure local `npm run typecheck` passes on that exact commit before running any release command
 - [ ] Update `CHANGELOG.md` with user-facing release notes (features, fixes — not refactors). Promotion renames the series' `## X.Y.Z-beta.N` entry to `## X.Y.Z - YYYY-MM-DD` and re-checks it covers the full release. Commit the matching [`CHANGELOG.zh-CN.md` entry](#changelog-translations) with it
 - [ ] Verify the changelog heading follows strict `## X.Y.Z - YYYY-MM-DD` format
-- [ ] Release preparation stayed local until the approved release command pushed the complete branch and tag
+- [ ] The changelog, ACP, lockfile, and version commits stayed local until the approved release command pushed the release branch and tag
 - [ ] `npm run release:patch`, `npm run release:minor`, or `npm run release:promote` completes successfully
 - [ ] Every GitHub Actions run for the complete release commit and tag is green
-- [ ] Move npm's `beta` dist-tag to the new stable version for every published package and verify both `latest` and `beta` resolve to it
+- [ ] `latest` resolves to the new stable, and `beta` resolves to it too unless an active newer beta holds `beta`
 - [ ] The GitHub Release was published only after the three stable manifests were uploaded, and it has the changelog body and every expected macOS, Linux, Windows, and Android APK asset
 - [ ] GitHub `Desktop Release` workflow for the `v*` tag is green
 - [ ] The GitHub Release contains `latest-mac.yml`, `latest-linux.yml`, and `latest.yml`
@@ -696,4 +771,5 @@ Every entry covers `previous stable release → release source`: first beta, lat
 - [ ] EAS iOS `submit_ios_for_review` succeeds, putting the build into App Store review
 - [ ] EAS Android `build_android` completes for the same tag
 - [ ] EAS Android `submit_android` succeeds, putting the build on its Play Store track
+- [ ] The [reconcile PR](#reconcile-main) brought the shipped changelog entries and version into `main`
 - [ ] The release heartbeat was created after the tag push and deleted only after every item above passed
diff --git a/docs/terminal-performance.md b/docs/terminal-performance.md
index 3bb7c4d71c..c757d004ec 100644
--- a/docs/terminal-performance.md
+++ b/docs/terminal-performance.md
@@ -6,9 +6,9 @@ How terminal output stays low-latency, what the invariants are, and how to measu
 
 ```
 pty (node-pty, forked worker process)
-  → headless xterm parse (worker, snapshot fidelity)
-  → TerminalOutputCoalescer (worker, ≤1 IPC message per 5ms per terminal)
-  → process.send IPC → daemon main process
+  → headless xterm parse (worker, ANSI replay fidelity)
+  → TerminalOutputCoalescer (worker, ≤1 socket frame per 5ms per terminal)
+  → framed local socket → daemon main process
   → TerminalOutputCoalescer (per client stream, terminal-session-controller.ts)
   → binary ws frame (2-byte header + raw bytes)
   → client decode (daemon-client.ts) → stream router → emulator runtime
@@ -19,11 +19,15 @@ Terminal frames share the daemon main event loop with all agent traffic. The `ev
 
 ## Invariants (the easy-to-break ones)
 
+- **Replay is incremental across the daemon and SDK.** Capable clients request their configured history, bounded by [worker retention](terminal-worker.md#process-model). Older apps retain their own 200-row request. Explicit SDK history demand is unchanged against older ANSI hosts, which apply their existing 500-row ceiling. Begin resets once, chunks keep a streaming UTF-8 decoder/parser, and each renderer suppresses generated replies while parsing replay. Never concatenate capable replay chunks to feed the renderer.
+- **Replay serialization reads xterm directly.** The [worker](terminal-worker.md#process-model) uses its existing buffer; text capture translates only the requested rows, and readiness scans row strings. Do not rebuild a full cell-object grid. Serialization still allocates a whole ANSI string and UTF-8 bytes before bounded delivery; chunking does not bound those allocations.
 - **Coalescers are leading+trailing throttles.** The first chunk after an idle window flushes immediately (synchronously); only sustained bursts wait for the trailing timer. Reverting to trailing-only adds a full window (~5ms) to every keystroke echo.
-- **Output coalescing happens in the worker, before IPC.** One `process.send` per pty chunk was a main-loop flood under build output. Non-output messages (snapshot/snapshotReady/titleChange/exit) must flush the coalescer first so ordering is preserved.
+- **Output coalescing happens in the worker, before IPC.** One socket frame per pty chunk was a main-loop flood under build output. Non-output messages (snapshotReady/titleChange/exit) must flush the coalescer first so ordering is preserved.
+- **Replay delivery is isolated per viewer.** Live worker output never waits for app delivery. Each daemon stream owns its bounded live tail and revision deduplication; a slow or failed replay cannot pause another viewer of the same terminal.
+- **Replay geometry belongs to the parser queue.** Native measurements and web fits must leave the captured dimensions intact through every chunk's commit. Apply the latest measured size after replay, before live bytes; clear, replacement and disposal must release that geometry ownership. A layout effect must not resize the renderer directly during replay.
 - **Coalesced output carries the LAST chunk's revision.** Snapshot replay dedup (`replayTerminalOutputAfterSnapshot`) skips buffered output with `revision <= replayRevision`; a merged batch with a lower revision would be wrongly skipped (lost output).
-- **The input-mode tracker runs once per process boundary, not per hop.** The worker owns the authoritative tracker; the daemon caches the replay preamble from `getTerminalState` responses and `snapshotReady` messages. Do not reintroduce a per-chunk `feed()` on the daemon main loop.
-- **Snapshot catch-up is backpressure-gated.** A stream falls back to a full snapshot only when `outputBytesSinceSnapshot > MAX_TERMINAL_OUTPUT_FRAME_BYTES` (256KB) **and** the client transport reports `bufferedAmount > MAX_CLIENT_BUFFERED_BYTES` (4MB). A client that keeps draining streams continuously, no matter how much output is produced. Before this gate existed, every 256KB of build output dropped a frame and forced a full JSON cell-grid snapshot (~200k objects across IPC) — the historical source of spiky lag and GC hitches.
+- **The input-mode tracker runs once per process boundary, not per hop.** The worker commits its authoritative tracker with xterm parsing before publishing the corresponding revision; the daemon caches current modes from ordered worker events and adoption. A replay response carries capture-time modes for its viewer; it must not overwrite the shared cache after newer live output. Apply that viewer's preamble before its buffered live bytes. Do not reintroduce a per-chunk `feed()` on the daemon main loop.
+- **Snapshot catch-up is backpressure-gated.** After more than 256 KiB of output, a stream catches up only when its transport reports more than 4 MiB queued, or exposes no backpressure reading. A draining client streams continuously. Pressure recovery sends at most 500 recent history rows plus the screen, preserving smaller explicit demands including zero; even a live-only subscription needs this resynchronization. It does not change the subscription's configured demand: later attach/reconnect restores still request the full configured history. The recent window avoids repeatedly serializing all retained history for a slow viewer.
 - **Plugin daemon sessions report IPC queue bytes.** Their virtual socket increments `bufferedAmount` before `process.send` and decrements it only in the send callback. Text and binary frames share that ordered queue, so the normal snapshot catch-up and physical high-water gates remain valid for server-side plugin SDK traffic.
 - **Client output writes are not serialized per frame.** The emulator runtime drains contiguous plain writes straight into xterm (which buffers internally). Only barrier ops (`clear`, `snapshot`, `suppressInput` writes) wait — behind a zero-length sentinel write — so resets can't interleave with in-flight output.
 - **Find preserves the inspected xterm viewport, including at the live bottom.** Keep its output anchor inside the existing batched write path. Serializing output to preserve a search result would add terminal latency.
diff --git a/docs/terminal-rendering.md b/docs/terminal-rendering.md
new file mode 100644
index 0000000000..4c418595fc
--- /dev/null
+++ b/docs/terminal-rendering.md
@@ -0,0 +1,75 @@
+# Terminal rendering
+
+Web and Electron draw terminals with xterm.js. iOS and Android keep an `@xterm/headless` buffer in JS and draw it with the `PaseoTerminal` native view in `packages/app/modules/paseo-terminal`: CoreText on iOS, `Canvas.drawTextRun` on Android. `src/terminal/native-renderer/terminal-frame.ts` turns the visible buffer into frames, and both native views take the same props.
+
+## xterm owns the grid
+
+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. 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 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.
+
+## 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
+
+Marks stacked above or below a letter, Arabic letter tails and some fallback glyphs ink into the rows next to theirs. Neither view clips a row to its own bounds, because a row clip also cuts marks and Arabic dots. Rows draw top to bottom, so a later row's cell backgrounds cover the ink that reaches into it.
+
+Android redraws every row on each frame, so overhanging ink cannot go stale. Its row `RenderNode`s are created with `setClipToBounds(false)`. The default would clip only unselected rows, because selected rows are drawn straight onto the view's canvas.
+
+iOS repaints only the rows that changed. Each `TerminalRowLayout` records how far its glyphs ink above and below the row. A changed row invalidates its old and new ink extent, and `draw(_:)` redraws every row whose ink extent meets the dirty rect. Invalidating only the row's own rect left an erased row's marks in the row next to it, erased a neighbour's marks when a row was rewritten, and showed or hid overhang depending on which rows changed together.
+
+## Mixed-direction text
+
+Rows draw left to right in logical order on both platforms. Terminal bidi escape modes are not implemented. On iOS the row needs both the `kCTWritingDirection` override and an LTR paragraph base direction. Without the base direction, bidi rule L1 moves trailing spaces ahead of a row that starts with Arabic or Hebrew, and the whole row shifts.
+
+Arabic still gets the contextual form its logical neighbours select, but in left-to-right order, so letters join on the wrong side. Correct visual Arabic needs implicit bidi per row: reorder RTL runs for display and map cursor, selection and hit-testing through the visual-to-logical index. That changes which column a character appears in, so it has to be decided as product behaviour first. Shaping alone cannot fix it.
+
+## Render regression
+
+The scripts live in `packages/app/e2e/mobile/terminal-rendering`. Run them from `packages/app` on the daemon's host, starting from an idle, focused terminal with an empty prompt.
+
+`render.mjs` prints a mixed-script fixture, screenshots it with agent-device, and checks the geometry with `check.mjs`. The check rebuilds the expected buffer with `@xterm/headless` and measures the grid from a ruler row. It checks that:
+
+- every grapheme cluster has ink inside its own columns, and blank cells stay blank;
+- on the accent rows, every cell is drawn in its own colour, including cells inside one cluster;
+- the cursor is drawn after the text;
+- every row is exposed as `terminal-row-<n>`;
+- selecting one cell of a conjunct highlights only that cell.
+
+On iOS the screenshot is taken at 3 pixels per point (`PASEO_TERMINAL_RENDERING_PIXEL_DENSITY`), because the simulator's default is one pixel per point and a glyph is then about 12 pixels. Focus the terminal before a run: with the simulator's hardware keyboard connected the key bar shows without a focused input, and `type` fails. In a debug build, the dev client's floating gear button covers the right end of the first row, so ruler cells there fail.
+
+```bash
+PLATFORM=android ANDROID_SERIAL=emulator-5554 node e2e/mobile/terminal-rendering/render.mjs
+PLATFORM=ios IOS_DEVICE="iPhone 17" node e2e/mobile/terminal-rendering/render.mjs
+```
+
+Geometry passes when a cell holds the wrong glyph. `identity.mjs` judges each cluster of a `render.mjs` run against pango's rendering of the same characters in the device's fonts. The reference is cut at the edges of the cluster's columns, placed as the renderer places it, because glyphs such as Devanagari letters ink past their advance and the device cuts them there too. A shape passes when its coverage correlates with its own reference at 0.6 or more, and no other cluster of the corpus matches it better. Box and block characters are judged against their Unicode definition. Shades are judged by even density over a 4×4 grid, because the device and pango fall back to different shade fonts. Clusters that pango draws without ink are reported as unjudged instead: flags on both platforms and Apple Color Emoji. The `rect` and `swap` controls fill every cluster with white, or judge each one against another cluster. Both must fail every cluster, which shows the oracle refuses ink that is present but wrong. An Arabic letter is compared with all four of its positional forms, so the oracle shows the right letter is drawn, not that it has the right form. Ink that a neighbouring row draws into a cluster's cells counts as that cluster's ink. On iOS the tail of `م` in the Arabic row reaches one pixel into the `न` below it, so `न` fails although both rows are drawn correctly.
+
+```bash
+FONTCONFIG_FILE=fonts.conf node e2e/mobile/terminal-rendering/identity.mjs <run dir> [none|rect|swap]
+```
+
+`fonts.conf` points fontconfig at the device's font files and lists, for `monospace`, the terminal font followed by the device's fallbacks for Hangul, Arabic, Devanagari, CJK, emoji and symbols:
+
+- **Android:** pull the fonts from `/system/fonts` with `adb pull`. The terminal font is Droid Sans Mono.
+- **iOS:** copy the simulator runtime's fonts from `RuntimeRoot/System/Library/Fonts`. The terminal font is Menlo. PingFang stores its outlines in Apple's `hvgl` table, which FreeType cannot draw, so the CJK references come from Apple SD Gothic Neo instead. `語` then scores below the threshold although the device draws it correctly.
+
+`overhang.mjs` prints rows whose marks reach the rows next to them. In one update it writes into two rows that hold a neighbour's marks and erases two rows whose marks reach a blank row. The marks must be drawn before the update, stay drawn in the written rows, and leave no ink behind the erased rows. Run it like `render.mjs`.
+
+`reattach.mjs` checks the restore size. It changes the PTY size by opening the keyboard (`RESIZE=keyboard`) or folding an Android foldable (`RESIZE=fold`), relaunches the app, and compares the client's rows with `paseo terminal capture`. A trial where no terminal rows appear, for example after a launch crash, counts as never attached and fails the run.
diff --git a/docs/terminal-worker.md b/docs/terminal-worker.md
new file mode 100644
index 0000000000..77aa9325b7
--- /dev/null
+++ b/docs/terminal-worker.md
@@ -0,0 +1,86 @@
+# Terminal worker
+
+Every terminal's PTY lives in the terminal worker, a process separate from the daemon. The worker outlives the daemon, so restarts, crashes and upgrades keep terminals running. This doc covers what the code can't tell you: why the process model is shaped this way, the rules nothing enforces, and the known limits.
+
+## Process model
+
+```
+supervisor (paseo.pid) ──► daemon worker ──► launcher ──► terminal worker ──► PTY programs
+                                                exits      (re-parented to init)
+```
+
+- The daemon starts the worker through a launcher (`terminal-worker-process.ts --launch`). The launcher spawns the worker `detached`, waits for `ready` on fd 3, prints the pid and exits, so the worker is re-parented and leaves the daemon's process tree. The supervisor's forced kill uses `tree-kill`, which walks parent pids: a worker that stayed a child, even detached, would die with a hung daemon.
+- The worker talks to one daemon at a time over a local socket (named pipe on Windows). Losing the daemon means "no controller", not exit: PTYs keep running, events are dropped, and the headless terminal keeps the screen for the next daemon's `listTerminals`.
+- A socket disconnect triggers reconnection to the same worker and a screen replay. Only confirmed process death retires its sessions; the next terminal creation shares one replacement launch. Dead-worker cleanup stays scoped to that worker, so a healthy draining peer keeps running. Shutdown and detach suppress recovery.
+- 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.
+
+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 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 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.
+
+## Protocol versions
+
+`TERMINAL_WORKER_PROTOCOL_VERSION` (`terminal-worker-protocol.ts`) is bumped whenever a request, response or event changes shape. A daemon classifies each live worker at start:
+
+| Worker reports                     | Daemon does                                                                                                                                                 |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| its own version                    | adopts it                                                                                                                                                   |
+| one version older                  | adopts it to drain: it keeps its terminals, takes no new ones, and is let go after its last terminal exits                                                  |
+| 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 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.
+
+Tests stand up other versions with `PASEO_TERMINAL_WORKER_PROTOCOL_OVERRIDE`, read by the worker. It is test-only.
+
+## Display replay
+
+The worker keeps the headless xterm model and generates ANSI. A replay request emits begin metadata (dimensions, retained history, revision and input modes), at most 64 KiB per data chunk, and end. Live output keeps flowing independently during replay. Capture is synchronous with PTY callbacks; flush the output coalescer before the cut so a later batch never includes bytes already in replay. Retained-history metadata counts the worker history before the request limit.
+
+ConPTY renders a console rather than forwarding every program escape sequence unchanged. A program write callback does not establish that its hidden cursor move or input modes reached the worker. Test exact ANSI fidelity at the serializer boundary; PTY integration compares the initial replay plus committed observed output at the capture cut, including startup modes.
+
+The worker paces replay writes on its local socket; the daemon synchronously queues each event into the application's bounded transport. App network delivery does not extend the worker's request deadline. There is no per-chunk acknowledgement or second replay delivery queue in the daemon. The physical application transport owns its 64 MiB high-water close, so a backed-up app cannot hold worker capture open. Each daemon viewer still holds at most 4 MiB of live output during capture, then drops revisions already present in the worker replay. Capture failure and tail overflow affect only that viewer; PTYs and healthy viewers keep running.
+
+Live traffic that fills the shared worker socket beyond 4 MiB disconnects the stalled controller. Reconnection adopts the surviving sessions and requests fresh replay for existing streams. Readiness does not require a revision: adoption announces readiness without one, while the replay capture supplies the revision used for deduplication.
+
+The SDK advertises `terminal_chunked_replay` only because it decodes begin/data/end. Capable clients receive these events directly; the daemon collects one Restore frame only for older ANSI clients. The SDK normalizes an older host's single Restore into the same lifecycle. Capture stays a worker request; bootstrap readiness uses `hasOutput`, not a transported grid.
+
+## Running from its own copy
+
+A worker outlives the installation that started it. An npm or desktop update replaces that installation's files, and the next terminal the old worker creates would load node-pty's `spawn-helper` and the zsh integration from paths that no longer exist. So a built daemon does not launch the worker from its install:
+
+- `npm run build` bundles the worker with esbuild (`packages/server/scripts/build-terminal-worker.mjs`) into `dist/server/terminal-worker/` with its `shell-integration/` beside it. Only node-pty stays external. A package loaded through a module-local `createRequire` is invisible to esbuild and would be missing at run time; `terminal-worker-runtime.test.ts` fails if the bundle loads anything but built-ins and node-pty.
+- Before launching, the daemon copies the bundle, the shell integration and node-pty (this platform's native build only) into `$PASEO_HOME/terminal-worker/<paseoVersion>-<hash>/` and launches from there. The hash covers the bundle and node-pty, so a local rebuild of the same version gets its own copy.
+- A copy is deleted once no record names it: after a draining worker exits, after a kill cleanup, and at daemon start. The daemon and the reaper delete copies, never the worker itself, so a worker exiting cannot remove a copy a new worker is about to launch from.
+- Dev (`.ts` source) launches from source and copies nothing.
+
+Each create carries the controlling daemon's environment and Paseo CLI path (`baseEnv`, `paseoCliPath`), so a terminal opened after an upgrade gets the new installation's `PASEO_CLI` while older terminals keep theirs.
+
+## Desktop
+
+Desktop app updates and version-mismatch restarts stop the daemon with "keep terminals" on macOS and Linux, through `daemon stop --keep-terminals` (the shutdown RPC; SIGTERM always means "stop and close"). A daemon that predates the feature cannot keep terminals: the CLI refuses before sending anything, and desktop logs that and stops it with its terminals closed.
+
+On Windows every desktop stop closes terminals. In the desktop app the worker runs as `Paseo.exe` with `ELECTRON_RUN_AS_NODE`, and a surviving one would lock the install folder the NSIS update replaces. Restarts, crashes and npm self-updates keep terminals on Windows too.
+
+## Known limits
+
+- On macOS `ps` has no session id, so a HUP-ignoring child of a shell that had already exited before cleanup started (re-parented to launchd) is not found. Linux reaches it through the session; a program that `exec`s keeps its entry on every OS.
+- On Linux, a member of a gone shell's session is signaled only if its environment carries that terminal's `PASEO_TERMINAL_ID`. A job that scrubbed its environment (`env -i`) is reported as unconfirmed, with its pid, and never signaled.
+- The agent-hook activity URL is baked into each shell when it starts. If the daemon's listen address changes across a restart, older shells report to the old address.
+- Restoring terminals after a reboot is out of scope: records from an earlier boot are retired without signaling anything.
diff --git a/docs/timeline-sync.md b/docs/timeline-sync.md
index 118ad628ce..e12b4a495a 100644
--- a/docs/timeline-sync.md
+++ b/docs/timeline-sync.md
@@ -10,16 +10,27 @@ then replaces the previous tool state or merges into the current text item. Inte
 are never retained for history or catch-up. Provider history is the durable transcript authority
 and rebuilds the projection when an agent resumes.
 
+Pagination bounds each read, not total resident history. Active and idle agents retain their
+projected transcript; archive releases it and later history reads rebuild it from the provider.
+Streaming overhead must remain proportional to the retained transcript. Cumulative text snapshots
+must be released after their deltas have been consumed.
+
 The invariants are:
 
 > A continuously subscribed client applies every committed row in order. Opening or resuming an
-> agent establishes the daemon's current tail in one bounded request, with older history reachable
+> agent establishes the daemon's current tail in one complete-turn request, with older history reachable
 > through backward pagination.
 
-Tool output is bounded before it enters either delivery path. Canonical shell tool output is sliced
-to 64 KiB, and the same bounded item is used for runtime timeline rows and live stream events.
-Provider history hydration applies the same rule so reopening an agent cannot restore an oversized
-tool payload.
+Every item is bounded before it enters either delivery path, because a timeline page is one
+WebSocket message and the daemon closes a socket whose outbound buffer passes 64 MiB. Tool calls get
+64 KiB and other items 256 KiB. Over budget, the largest strings are cut to a shared length with a
+`…[truncated 12.3 MB]` marker, and an oversized `data:` URL is replaced by the marker. Strings up
+to 1 KiB stay whole, so ids and paths survive. Arrays drop their trailing elements without a marker
+element, so typed arrays still match the wire schema. Limiting an item twice gives the same item. The
+budget does not bound wide objects or multi-byte text. The same
+bounded item is used for runtime timeline rows and live stream events. Provider history hydration
+applies the same rule so reopening an agent cannot restore an oversized payload. Fetches apply it
+again to assistant and reasoning rows the projection merges from many chunks.
 
 ## Presence is not delivery
 
@@ -44,7 +55,21 @@ recovery is complete only when `hasNewer: false`.
 
 Initialization timeouts guard lack of catch-up progress, not the full multi-page sync. A successful page that queues the next `after` page refreshes the watchdog.
 
-Opening or resuming an agent fetches one bounded latest tail page. Older history remains
+Opening or resuming an agent fetches the latest available turns with a soft target of 40
+projected items. Backward pages and prompt-jump windows also include whole turns, including
+all currently available rows of an active run. There is no per-turn cap: a large run can
+exceed the target. Local history mounting uses the same boundaries so revealing older rows
+does not change the collapse state of a turn already displayed.
+
+`wholeTurns` is a preference negotiated once at the client fetch boundary. Hosts advertising
+`features.wholeTurnTimeline` receive it; other hosts receive the existing item-based request.
+Reading history remains available on older hosts, whose pages can still split turns. Forward
+catch-up stays incremental, but its reset snapshot honors a supported whole-turn request.
+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.
 
 A failed catch-up or subscription reconcile retries on its own, doubling from 1s to a 30s ceiling.
@@ -70,9 +95,10 @@ 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
 
@@ -149,12 +175,13 @@ range describes those exact items: `startSeq` drives older pagination and `endSe
 catch-up. The owner requests `after endSeq`, and requests `before startSeq` when the user loads older
 history. Code outside the owner does not distinguish cached and network timelines.
 
-The first resume request is bounded. If it reports more newer history, fetch one latest bounded tail
+The first resume request is bounded. If it reports more newer history, fetch one latest complete-turn tail
 instead of replaying every missed page. Live gap recovery still pages forward until current.
 
-If the canonical window exceeds the cache item limit, contains a discontiguous retained range, has a
+If the canonical window exceeds the cache item target, contains a discontiguous retained range, has a
 live head, or includes presentation data the cache cannot encode losslessly, persistence drops the
-range and keeps a display-only tail. Never slice items while retaining the pre-slice range; that
+range and keeps a display-only tail of complete available turns. The item target is soft;
+the byte budget still evicts entire cache rows. Never slice items while retaining the pre-slice range; that
 falsely certifies discarded source rows. A display-only row paints without granting synchronization
 authority, so the owner uses the ordinary bounded `tail` bootstrap.
 
@@ -238,11 +265,11 @@ foreground control ownership remains a separate daemon concern. Cancellation req
 with that record rather than in a React component, so an old request cannot clear a newer one. Submissions
 remain a separate pre-turn registry and retire on canonical acknowledgement.
 
-Canonical turns and visible responses are different boundaries. Agent-originated prompts and lifecycle
-notifications project into tool rows, so they do not create a human-message boundary. Legacy system
-prompts, including schedule injections, remain hidden. One visible response can span several canonical
-turns; layout and copy group that response together while lifecycle, timing, tool sequences, and exact
-fork positions retain the canonical `turnId` boundaries.
+Every canonical run owns a visible turn, including heartbeats and agent notifications.
+Notifications delivered during a run stay inside it; batched notifications share the run
+that starts or accepts them. Received messages retain sender attribution, while lifecycle
+notifications remain visible events. Collapse, timing and locally mounted history share
+these boundaries.
 
 Agent-message XML belongs to the daemon's `agent/agent-messages` boundary. Prompt delivery encodes
 provenance; acceptance, provider echoes, import, and replay share its projection. The delivery ID is
diff --git a/docs/unistyles.md b/docs/unistyles.md
index 3daae333df..6be82f70b0 100644
--- a/docs/unistyles.md
+++ b/docs/unistyles.md
@@ -358,6 +358,14 @@ export to `src`, but browser and Electron Metro resolve its `browser` export to
 `lib/module`; CommonJS consumers use `lib/commonjs`. A source-only patch leaves
 Electron running the old code.
 
+The adaptive-theme patch keeps `colorScheme` reads off the media-query lists
+owned by Unistyles' change listeners. Chromium defers their events while a window
+is hidden; reading `matches` on those same lists can consume the pending change.
+CSS variables then follow the OS theme while `withUnistyles` props retain the old
+colors. Keep this patch until upstream reads the scheme through separate lists.
+The desktop browser E2E checks both transition directions in an isolated Electron
+process, because Playwright's focus emulation prevents real hidden-page behavior.
+
 Register every dependency patch in `scripts/postinstall-patches.mjs`. A file in
 `patches/` is inert unless that script knows which installed package activates
 it.
diff --git a/fastlane/metadata/android/en-US/changelogs/140001.txt b/fastlane/metadata/android/en-US/changelogs/140001.txt
new file mode 100644
index 0000000000..32cf0aa48b
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/140001.txt
@@ -0,0 +1,10 @@
+Plugins can now add tools to individual agents and configure their MCP servers when sessions open.
+
+Completed conversation turns can be collapsed into summaries and expanded to read the full exchange.
+
+Voice settings now let you configure speech providers and download local models with one tap, including SenseVoice and Whisper for Chinese dictation. Voice mode is now opt-in.
+
+Added
+- Let plugins give tools to specific agents
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/140002.txt b/fastlane/metadata/android/en-US/changelogs/140002.txt
new file mode 100644
index 0000000000..32cf0aa48b
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/140002.txt
@@ -0,0 +1,10 @@
+Plugins can now add tools to individual agents and configure their MCP servers when sessions open.
+
+Completed conversation turns can be collapsed into summaries and expanded to read the full exchange.
+
+Voice settings now let you configure speech providers and download local models with one tap, including SenseVoice and Whisper for Chinese dictation. Voice mode is now opt-in.
+
+Added
+- Let plugins give tools to specific agents
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/140003.txt b/fastlane/metadata/android/en-US/changelogs/140003.txt
new file mode 100644
index 0000000000..32cf0aa48b
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/140003.txt
@@ -0,0 +1,10 @@
+Plugins can now add tools to individual agents and configure their MCP servers when sessions open.
+
+Completed conversation turns can be collapsed into summaries and expanded to read the full exchange.
+
+Voice settings now let you configure speech providers and download local models with one tap, including SenseVoice and Whisper for Chinese dictation. Voice mode is now opt-in.
+
+Added
+- Let plugins give tools to specific agents
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/140004.txt b/fastlane/metadata/android/en-US/changelogs/140004.txt
new file mode 100644
index 0000000000..32cf0aa48b
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/140004.txt
@@ -0,0 +1,10 @@
+Plugins can now add tools to individual agents and configure their MCP servers when sessions open.
+
+Completed conversation turns can be collapsed into summaries and expanded to read the full exchange.
+
+Voice settings now let you configure speech providers and download local models with one tap, including SenseVoice and Whisper for Chinese dictation. Voice mode is now opt-in.
+
+Added
+- Let plugins give tools to specific agents
+
+Full notes: https://paseo.sh/changelog
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/images/phoneScreenshots/1.png b/fastlane/metadata/android/en-US/images/phoneScreenshots/1.png
index 9f633ca58f..ca3a9fa2a8 120000
--- a/fastlane/metadata/android/en-US/images/phoneScreenshots/1.png
+++ b/fastlane/metadata/android/en-US/images/phoneScreenshots/1.png
@@ -1 +1 @@
-../../../../../../packages/website/public/phone-1.png
\ No newline at end of file
+../../../../../../assets/store-screenshots/output/google/01-sidebar.png
\ No newline at end of file
diff --git a/fastlane/metadata/android/en-US/images/phoneScreenshots/2.png b/fastlane/metadata/android/en-US/images/phoneScreenshots/2.png
index 6d2fbd14d7..a0748cf426 120000
--- a/fastlane/metadata/android/en-US/images/phoneScreenshots/2.png
+++ b/fastlane/metadata/android/en-US/images/phoneScreenshots/2.png
@@ -1 +1 @@
-../../../../../../packages/website/public/phone-2.png
\ No newline at end of file
+../../../../../../assets/store-screenshots/output/google/02-chat.png
\ No newline at end of file
diff --git a/fastlane/metadata/android/en-US/images/phoneScreenshots/3.png b/fastlane/metadata/android/en-US/images/phoneScreenshots/3.png
index e23c27ced5..0e7dba6b41 120000
--- a/fastlane/metadata/android/en-US/images/phoneScreenshots/3.png
+++ b/fastlane/metadata/android/en-US/images/phoneScreenshots/3.png
@@ -1 +1 @@
-../../../../../../packages/website/public/phone-3.png
\ No newline at end of file
+../../../../../../assets/store-screenshots/output/google/03-plugins.png
\ No newline at end of file
diff --git a/fastlane/metadata/android/en-US/images/phoneScreenshots/4.png b/fastlane/metadata/android/en-US/images/phoneScreenshots/4.png
new file mode 120000
index 0000000000..e89becb9bc
--- /dev/null
+++ b/fastlane/metadata/android/en-US/images/phoneScreenshots/4.png
@@ -0,0 +1 @@
+../../../../../../assets/store-screenshots/output/google/04-review.png
\ No newline at end of file
diff --git a/fastlane/metadata/android/en-US/images/phoneScreenshots/5.png b/fastlane/metadata/android/en-US/images/phoneScreenshots/5.png
new file mode 120000
index 0000000000..c067990032
--- /dev/null
+++ b/fastlane/metadata/android/en-US/images/phoneScreenshots/5.png
@@ -0,0 +1 @@
+../../../../../../assets/store-screenshots/output/google/05-terminal.png
\ No newline at end of file
diff --git a/fastlane/metadata/android/en-US/images/tenInchScreenshots/1.png b/fastlane/metadata/android/en-US/images/tenInchScreenshots/1.png
new file mode 120000
index 0000000000..401053965e
--- /dev/null
+++ b/fastlane/metadata/android/en-US/images/tenInchScreenshots/1.png
@@ -0,0 +1 @@
+../../../../../../assets/store-screenshots/output/google-tablet/01-sidebar.png
\ No newline at end of file
diff --git a/fastlane/metadata/android/en-US/images/tenInchScreenshots/2.png b/fastlane/metadata/android/en-US/images/tenInchScreenshots/2.png
new file mode 120000
index 0000000000..2454381850
--- /dev/null
+++ b/fastlane/metadata/android/en-US/images/tenInchScreenshots/2.png
@@ -0,0 +1 @@
+../../../../../../assets/store-screenshots/output/google-tablet/02-chat.png
\ No newline at end of file
diff --git a/fastlane/metadata/android/en-US/images/tenInchScreenshots/3.png b/fastlane/metadata/android/en-US/images/tenInchScreenshots/3.png
new file mode 120000
index 0000000000..1b31012051
--- /dev/null
+++ b/fastlane/metadata/android/en-US/images/tenInchScreenshots/3.png
@@ -0,0 +1 @@
+../../../../../../assets/store-screenshots/output/google-tablet/03-plugins.png
\ No newline at end of file
diff --git a/fastlane/metadata/android/en-US/images/tenInchScreenshots/4.png b/fastlane/metadata/android/en-US/images/tenInchScreenshots/4.png
new file mode 120000
index 0000000000..13d8545d92
--- /dev/null
+++ b/fastlane/metadata/android/en-US/images/tenInchScreenshots/4.png
@@ -0,0 +1 @@
+../../../../../../assets/store-screenshots/output/google-tablet/04-review.png
\ No newline at end of file
diff --git a/fastlane/metadata/android/en-US/images/tenInchScreenshots/5.png b/fastlane/metadata/android/en-US/images/tenInchScreenshots/5.png
new file mode 120000
index 0000000000..b0905beafc
--- /dev/null
+++ b/fastlane/metadata/android/en-US/images/tenInchScreenshots/5.png
@@ -0,0 +1 @@
+../../../../../../assets/store-screenshots/output/google-tablet/05-terminal.png
\ No newline at end of file
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 3e19f893c2..7e8367c9c0 100644
--- a/nix/npm-deps.hash
+++ b/nix/npm-deps.hash
@@ -1 +1 @@
-sha256-eNiKmiZ3XXZMRZRSoGxUbMn2RtY6AX079vUatBYM+qE=
+sha256-vwivjBU5VFpM9VD7Wx4IKHN6xEVlg/KBMJCCMuA1JEw=
diff --git a/package-lock.json b/package-lock.json
index 847bd24eb7..38a46b7319 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "paseo",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "paseo",
-      "version": "0.13.2",
+      "version": "0.15.3",
       "hasInstallScript": true,
       "license": "Apache-2.0",
       "workspaces": [
@@ -30,6 +30,8 @@
         "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",
         "knip": "^5.82.1",
@@ -980,7 +982,7 @@
       "version": "7.8.4",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-async-generators/-/plugin-syntax-async-generators-7.8.4.tgz",
       "integrity": "sha512-tycmZxkGfZaxhMRbXlPXuVFpdWlXpir2W4AMhSJgRKzk/eDlIXOhb2LHWoLpDF7TEHylV5zNhykX6KAgHJmTNw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.8.0"
@@ -993,7 +995,7 @@
       "version": "7.8.3",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-bigint/-/plugin-syntax-bigint-7.8.3.tgz",
       "integrity": "sha512-wnTnFlG+YxQm3vDxpGE57Pj0srRU4sHE/mDkt1qv2YJJSeUAec2ma4WLUnUPeKjyrfntVwe/N6dCXpU+zL3Npg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.8.0"
@@ -1006,7 +1008,7 @@
       "version": "7.12.13",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-class-properties/-/plugin-syntax-class-properties-7.12.13.tgz",
       "integrity": "sha512-fm4idjKla0YahUNgFNLCB0qySdsoPiZP3iQE3rky0mBUtMZ23yDJ9SJdg6dXTSDnulOVqiF3Hgr9nbXvXTQZYA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.12.13"
@@ -1019,7 +1021,7 @@
       "version": "7.14.5",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-class-static-block/-/plugin-syntax-class-static-block-7.14.5.tgz",
       "integrity": "sha512-b+YyPmr6ldyNnM6sqYeMWE+bgJcJpO6yS4QD7ymxgH34GBPNDM/THBh8iunyvKIZztiwLH4CJZ0RxTk9emgpjw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.14.5"
@@ -1108,7 +1110,7 @@
       "version": "7.28.6",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-import-attributes/-/plugin-syntax-import-attributes-7.28.6.tgz",
       "integrity": "sha512-jiLC0ma9XkQT3TKJ9uYvlakm66Pamywo+qwL+oL8HJOvc6TWdZXVfhqJr8CCzbSGUAbDOzlGHJC1U+vRfLQDvw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.28.6"
@@ -1124,7 +1126,7 @@
       "version": "7.10.4",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-import-meta/-/plugin-syntax-import-meta-7.10.4.tgz",
       "integrity": "sha512-Yqfm+XDx0+Prh3VSeEQCPU81yC+JWZ2pDPFSS4ZdpfZhp4MkFMaDC1UqseovEKwSUpnIL7+vK+Clp7bfh0iD7g==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.10.4"
@@ -1137,7 +1139,7 @@
       "version": "7.8.3",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-json-strings/-/plugin-syntax-json-strings-7.8.3.tgz",
       "integrity": "sha512-lY6kdGpWHvjoe2vk4WrAapEuBR69EMxZl+RoGRhrFGNYVK8mOPAW8VfbT/ZgrFbXlDNiiaxQnAtgVCZ6jv30EA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.8.0"
@@ -1165,7 +1167,7 @@
       "version": "7.10.4",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-logical-assignment-operators/-/plugin-syntax-logical-assignment-operators-7.10.4.tgz",
       "integrity": "sha512-d8waShlpFDinQ5MtvGU9xDAOzKH47+FFoney2baFIoMr952hKOLp1HR7VszoZvOsV/4+RRszNY7D17ba0te0ig==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.10.4"
@@ -1190,7 +1192,7 @@
       "version": "7.10.4",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-numeric-separator/-/plugin-syntax-numeric-separator-7.10.4.tgz",
       "integrity": "sha512-9H6YdfkcK/uOnY/K7/aA2xpzaAgkQn37yzWUMRK7OaPOqOpGS1+n0H5hxT9AUw9EsSjPW8SVyMJwYRtWs3X3ug==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.10.4"
@@ -1203,7 +1205,7 @@
       "version": "7.8.3",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-object-rest-spread/-/plugin-syntax-object-rest-spread-7.8.3.tgz",
       "integrity": "sha512-XoqMijGZb9y3y2XskN+P1wUGiVwWZ5JmoDRwx5+3GmEplNyVM2s2Dg8ILFQm8rWM48orGy5YpI5Bl8U1y7ydlA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.8.0"
@@ -1216,7 +1218,7 @@
       "version": "7.8.3",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-optional-catch-binding/-/plugin-syntax-optional-catch-binding-7.8.3.tgz",
       "integrity": "sha512-6VPD0Pc1lpTqw0aKoeRTMiB+kWhAoT24PA+ksWSBrFtl5SIRVpZlwN3NNPQjehA2E/91FV3RjLWoVTglWcSV3Q==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.8.0"
@@ -1241,7 +1243,7 @@
       "version": "7.14.5",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-private-property-in-object/-/plugin-syntax-private-property-in-object-7.14.5.tgz",
       "integrity": "sha512-0wVnp9dxJ72ZUJDV27ZfbSj6iHLoytYZmh3rFcxNnvsJF3ktkzLDZPy/mA17HGsaQT3/DQsWYX1f1QGWkCoVUg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.14.5"
@@ -1257,7 +1259,7 @@
       "version": "7.14.5",
       "resolved": "https://registry.npmjs.org/@babel/plugin-syntax-top-level-await/-/plugin-syntax-top-level-await-7.14.5.tgz",
       "integrity": "sha512-hx++upLv5U1rgYfwe1xBQUhRmU41NEvpUvrp8jkrSCdvGSnM5/qdRMtylJ6PG5OFkBaHkbTAKTnd3/YyESRHFw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.14.5"
@@ -2510,6 +2512,14 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@bcoe/v8-coverage": {
+      "version": "0.2.3",
+      "resolved": "https://registry.npmjs.org/@bcoe/v8-coverage/-/v8-coverage-0.2.3.tgz",
+      "integrity": "sha512-0hYQ8SB4Db5zvZB4axdMHGwEaQjkZzFjQiN9LVYvIFB2nSUHW9tYpxWriPrWDASIxiaXax83REcLxuSdnGPZtw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true
+    },
     "node_modules/@blazediff/core": {
       "version": "1.9.1",
       "resolved": "https://registry.npmjs.org/@blazediff/core/-/core-1.9.1.tgz",
@@ -2779,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",
@@ -2884,6 +2842,17 @@
         "react": ">=16.8.0"
       }
     },
+    "node_modules/@dual-bundle/import-meta-resolve": {
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/@dual-bundle/import-meta-resolve/-/import-meta-resolve-4.2.1.tgz",
+      "integrity": "sha512-id+7YRUgoUX6CgV0DtuhirQWodeeA7Lf4i2x71JS/vtA5pRb/hIGWlw+G6MeXvsM+MXrz0VAydTGElX1rAfgPg==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/JounQin"
+      }
+    },
     "node_modules/@egjs/hammerjs": {
       "version": "2.0.17",
       "resolved": "https://registry.npmjs.org/@egjs/hammerjs/-/hammerjs-2.0.17.tgz",
@@ -3112,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"
@@ -3139,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",
@@ -3209,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": {
@@ -3239,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",
@@ -5537,14 +5488,6 @@
         "react-native": "*"
       }
     },
-    "node_modules/@expo/log-box-utils": {
-      "version": "58.0.2",
-      "resolved": "https://registry.npmjs.org/@expo/log-box-utils/-/log-box-utils-58.0.2.tgz",
-      "integrity": "sha512-My8Lwe9FU/yDwwzqwi5LN2rzzDcJqIAZKrD9f0XHZEKz/FQnWJYdt1rsV7+RwqMGeGq2XsxTCVT1ggTCOvumxw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
     "node_modules/@expo/logger": {
       "version": "1.0.221",
       "resolved": "https://registry.npmjs.org/@expo/logger/-/logger-1.0.221.tgz",
@@ -5899,36 +5842,6 @@
         "node": "^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0"
       }
     },
-    "node_modules/@expo/modules-macros-win32-arm64": {
-      "version": "0.20.0",
-      "resolved": "https://registry.npmjs.org/@expo/modules-macros-win32-arm64/-/modules-macros-win32-arm64-0.20.0.tgz",
-      "integrity": "sha512-7B57gc7+TeygPcK8fLYlEhJbbvaPh+JBzex11YIYZrSzbFhz7Q+Z37fSdAfp4EsfCswJNcX0S6wpkgSlVNefVw==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "peer": true
-    },
-    "node_modules/@expo/modules-macros-win32-x64": {
-      "version": "0.20.0",
-      "resolved": "https://registry.npmjs.org/@expo/modules-macros-win32-x64/-/modules-macros-win32-x64-0.20.0.tgz",
-      "integrity": "sha512-BM5a2U2tCyHzmtiSEY70KPsts82Mfy1bHSZ7AUbg6z9LcnxuThxJlcH85/SV5eFbhrPfgDBAG/WAncyZCvKvyA==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "peer": true
-    },
     "node_modules/@expo/multipart-body-parser": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/@expo/multipart-body-parser/-/multipart-body-parser-2.0.0.tgz",
@@ -6216,14 +6129,6 @@
         "node-forge": "^1.2.1"
       }
     },
-    "node_modules/@expo/platforms": {
-      "version": "58.0.1",
-      "resolved": "https://registry.npmjs.org/@expo/platforms/-/platforms-58.0.1.tgz",
-      "integrity": "sha512-KtLrtAvpShq16l9lTxd2fZSjULxcGxXrJTHA31iUVqrc+Af7aTAJW4ZB3yQBgi/w+kSb6BB/CG9RXI0ohbMm6g==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
     "node_modules/@expo/plist": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/@expo/plist/-/plist-0.2.0.tgz",
@@ -7569,7 +7474,7 @@
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/@istanbuljs/load-nyc-config/-/load-nyc-config-1.1.0.tgz",
       "integrity": "sha512-VjeHSlIzpv/NyD3N0YuHfXOPDIixcA1q2ZV98wsMqcYlPmv2n3Yb2lYP9XMElnaFVXg5A7YLTeLu6V84uQDjmQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "ISC",
       "dependencies": {
         "camelcase": "^5.3.1",
@@ -7586,7 +7491,7 @@
       "version": "5.3.1",
       "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz",
       "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=6"
@@ -7596,7 +7501,7 @@
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz",
       "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "locate-path": "^5.0.0",
@@ -7610,7 +7515,7 @@
       "version": "3.14.2",
       "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.2.tgz",
       "integrity": "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "argparse": "^1.0.7",
@@ -7624,7 +7529,7 @@
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz",
       "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "p-locate": "^4.1.0"
@@ -7637,7 +7542,7 @@
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz",
       "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "p-try": "^2.0.0"
@@ -7653,7 +7558,7 @@
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz",
       "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "p-limit": "^2.2.0"
@@ -7666,7 +7571,7 @@
       "version": "0.1.3",
       "resolved": "https://registry.npmjs.org/@istanbuljs/schema/-/schema-0.1.3.tgz",
       "integrity": "sha512-ZXRY4jNvVgSVQ8DL3LTcakaAtXwTVUxE81hslsyD2AtoXW/wVob10HkOJ1X/pAlcI7D+2YoZKg5do8G/w6RYgA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -7676,7 +7581,7 @@
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/@jest/console/-/console-29.7.0.tgz",
       "integrity": "sha512-5Ni4CU7XHQi32IJ398EEP4RrB8eV09sXP2ROqD4bksHrnTree52PsxvX8tpL8LvTZ3pFzXyPbNQReSN41CAhOg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@jest/types": "^29.6.3",
@@ -7694,12 +7599,72 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
       "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
       }
     },
+    "node_modules/@jest/core": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/@jest/core/-/core-29.7.0.tgz",
+      "integrity": "sha512-n7aeXWKMnGtDA48y8TLWJPJmLmmZ642Ceo78cYWEpiD7FzDgmNDV/GCVRorPABdXLJZ/9wzzgZAlHjXjxDHGsg==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@jest/console": "^29.7.0",
+        "@jest/reporters": "^29.7.0",
+        "@jest/test-result": "^29.7.0",
+        "@jest/transform": "^29.7.0",
+        "@jest/types": "^29.6.3",
+        "@types/node": "*",
+        "ansi-escapes": "^4.2.1",
+        "chalk": "^4.0.0",
+        "ci-info": "^3.2.0",
+        "exit": "^0.1.2",
+        "graceful-fs": "^4.2.9",
+        "jest-changed-files": "^29.7.0",
+        "jest-config": "^29.7.0",
+        "jest-haste-map": "^29.7.0",
+        "jest-message-util": "^29.7.0",
+        "jest-regex-util": "^29.6.3",
+        "jest-resolve": "^29.7.0",
+        "jest-resolve-dependencies": "^29.7.0",
+        "jest-runner": "^29.7.0",
+        "jest-runtime": "^29.7.0",
+        "jest-snapshot": "^29.7.0",
+        "jest-util": "^29.7.0",
+        "jest-validate": "^29.7.0",
+        "jest-watcher": "^29.7.0",
+        "micromatch": "^4.0.4",
+        "pretty-format": "^29.7.0",
+        "slash": "^3.0.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      },
+      "peerDependencies": {
+        "node-notifier": "^8.0.1 || ^9.0.0 || ^10.0.0"
+      },
+      "peerDependenciesMeta": {
+        "node-notifier": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@jest/core/node_modules/slash": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
+      "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/@jest/create-cache-key-function": {
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/@jest/create-cache-key-function/-/create-cache-key-function-29.7.0.tgz",
@@ -7714,10 +7679,10 @@
       }
     },
     "node_modules/@jest/diff-sequences": {
-      "version": "30.4.0",
-      "resolved": "https://registry.npmjs.org/@jest/diff-sequences/-/diff-sequences-30.4.0.tgz",
-      "integrity": "sha512-zOpzlfUs45l6u7jm39qr87JCHUDsaeCtvL+kQe/Vn9jSnRB4/5IPXISm0h9I1vZW/o00Kn4UTJ2MOlhnUGwv3g==",
-      "dev": true,
+      "version": "30.5.0",
+      "resolved": "https://registry.npmjs.org/@jest/diff-sequences/-/diff-sequences-30.5.0.tgz",
+      "integrity": "sha512-OsqBjHXCn8cadasoAZBP6nWYvMsRhpMzGXTpxJ5aO04NlbdhIz+FVe3q49l0AwVhsz/cEmIpBes6gAFl1/dWQg==",
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
@@ -7727,7 +7692,7 @@
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/@jest/environment/-/environment-29.7.0.tgz",
       "integrity": "sha512-aQIfHDq33ExsN4jP1NWGXhxgQ/wixs60gDiKO+XVMd8Mn0NWPWgc34ZQDTb2jKaUWQ7MuwoitXAsN2XVXNMpAw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@jest/fake-timers": "^29.7.0",
@@ -7743,7 +7708,7 @@
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/@jest/expect/-/expect-29.7.0.tgz",
       "integrity": "sha512-8uMeAMycttpva3P1lBHB8VciS9V0XAr3GymPpipdyQXbBcuhkLQOSe8E/p92RyAdToS6ZD1tFkX+CkhoECE0dQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "expect": "^29.7.0",
@@ -7757,7 +7722,7 @@
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/@jest/expect-utils/-/expect-utils-29.7.0.tgz",
       "integrity": "sha512-GlsNBWiFQFCVi9QVSx7f5AgMeLxe9YCCs5PuP2O2LdjDAA8Jh9eX7lA1Jq/xdXw3Wb3hyvlFNfZIfcRetSzYcA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "jest-get-type": "^29.6.3"
@@ -7770,7 +7735,7 @@
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/@jest/fake-timers/-/fake-timers-29.7.0.tgz",
       "integrity": "sha512-q4DH1Ha4TTFPdxLsqDXK1d3+ioSL7yL5oCMJZgDYm6i+6CygW5E5xVr/D1HdsGxjt1ZWSfUAs9OxSB/BNelWrQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@jest/types": "^29.6.3",
@@ -7785,10 +7750,10 @@
       }
     },
     "node_modules/@jest/get-type": {
-      "version": "30.1.0",
-      "resolved": "https://registry.npmjs.org/@jest/get-type/-/get-type-30.1.0.tgz",
-      "integrity": "sha512-eMbZE2hUnx1WV0pmURZY9XoXPkUYjpc55mb0CrhtdWLtzMQPFvu/rZkTLZFTsdaVQa+Tr4eWAteqcUzoawq/uA==",
-      "dev": true,
+      "version": "30.5.0",
+      "resolved": "https://registry.npmjs.org/@jest/get-type/-/get-type-30.5.0.tgz",
+      "integrity": "sha512-9/2VUPitAjmBzbvDvqrxmvB7BzWsBW0WmkkojX1ODuxX1NLGxx9gfaZpHB0z8DtJ9uhGNmZG/VXBhf8uO0OV8Q==",
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
@@ -7798,7 +7763,7 @@
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/@jest/globals/-/globals-29.7.0.tgz",
       "integrity": "sha512-mpiz3dutLbkW2MNFubUGUEVLkTGiqW6yLVTA+JbP6fI6J5iL9Y0Nlg8k95pcF8ctKwCS7WVxteBs29hhfAotzQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@jest/environment": "^29.7.0",
@@ -7810,6 +7775,171 @@
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
+    "node_modules/@jest/react-is-18": {
+      "name": "react-is",
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz",
+      "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==",
+      "devOptional": true,
+      "license": "MIT"
+    },
+    "node_modules/@jest/react-is-19": {
+      "name": "react-is",
+      "version": "19.3.1",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-19.3.1.tgz",
+      "integrity": "sha512-RRieF6IyxQBkcK6pP8xOHprLTPW6QjRkbGdImtqNme+/hYVwCZkLQLdlZGOhUqXwkS9IEynaGvPJtv6XB/cz0Q==",
+      "devOptional": true,
+      "license": "MIT"
+    },
+    "node_modules/@jest/reporters": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/@jest/reporters/-/reporters-29.7.0.tgz",
+      "integrity": "sha512-DApq0KJbJOEzAFYjHADNNxAE3KbhxQB1y5Kplb5Waqw6zVbuWatSnMjE5gs8FUgEPmNsnZA3NCWl9NG0ia04Pg==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@bcoe/v8-coverage": "^0.2.3",
+        "@jest/console": "^29.7.0",
+        "@jest/test-result": "^29.7.0",
+        "@jest/transform": "^29.7.0",
+        "@jest/types": "^29.6.3",
+        "@jridgewell/trace-mapping": "^0.3.18",
+        "@types/node": "*",
+        "chalk": "^4.0.0",
+        "collect-v8-coverage": "^1.0.0",
+        "exit": "^0.1.2",
+        "glob": "^7.1.3",
+        "graceful-fs": "^4.2.9",
+        "istanbul-lib-coverage": "^3.0.0",
+        "istanbul-lib-instrument": "^6.0.0",
+        "istanbul-lib-report": "^3.0.0",
+        "istanbul-lib-source-maps": "^4.0.0",
+        "istanbul-reports": "^3.1.3",
+        "jest-message-util": "^29.7.0",
+        "jest-util": "^29.7.0",
+        "jest-worker": "^29.7.0",
+        "slash": "^3.0.0",
+        "string-length": "^4.0.1",
+        "strip-ansi": "^6.0.0",
+        "v8-to-istanbul": "^9.0.1"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      },
+      "peerDependencies": {
+        "node-notifier": "^8.0.1 || ^9.0.0 || ^10.0.0"
+      },
+      "peerDependenciesMeta": {
+        "node-notifier": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@jest/reporters/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==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "node_modules/@jest/reporters/node_modules/char-regex": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/char-regex/-/char-regex-1.0.2.tgz",
+      "integrity": "sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/@jest/reporters/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",
+      "devOptional": 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/@jest/reporters/node_modules/istanbul-lib-instrument": {
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/istanbul-lib-instrument/-/istanbul-lib-instrument-6.0.3.tgz",
+      "integrity": "sha512-Vtgk7L/R2JHyyGW07spoFlB8/lpjiOLTjMdms6AFMraYt3BaJauod/NGrfnVG/y4Ix1JEuMRPDPEj2ua+zz1/Q==",
+      "devOptional": true,
+      "license": "BSD-3-Clause",
+      "peer": true,
+      "dependencies": {
+        "@babel/core": "^7.23.9",
+        "@babel/parser": "^7.23.9",
+        "@istanbuljs/schema": "^0.1.3",
+        "istanbul-lib-coverage": "^3.2.0",
+        "semver": "^7.5.4"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/@jest/reporters/node_modules/minimatch": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "devOptional": true,
+      "license": "ISC",
+      "peer": true,
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/@jest/reporters/node_modules/slash": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
+      "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@jest/reporters/node_modules/string-length": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/string-length/-/string-length-4.0.2.tgz",
+      "integrity": "sha512-+l6rNN5fYHNhZZy41RXsYptCjA2Igmq4EG7kZAYFQI1E1VTXarr6ZPXBg6eq7Y6eK4FEhY6AJlyuFIb/v/S0VQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "char-regex": "^1.0.2",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/@jest/schemas": {
       "version": "29.6.3",
       "resolved": "https://registry.npmjs.org/@jest/schemas/-/schemas-29.6.3.tgz",
@@ -7822,11 +7952,27 @@
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
+    "node_modules/@jest/source-map": {
+      "version": "29.6.3",
+      "resolved": "https://registry.npmjs.org/@jest/source-map/-/source-map-29.6.3.tgz",
+      "integrity": "sha512-MHjT95QuipcPrpLM+8JMSzFx6eHp5Bm+4XeFDJlwsvVBjmKNiIAvasGK2fxz2WbGRlnvqehFbh07MMa7n3YJnw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@jridgewell/trace-mapping": "^0.3.18",
+        "callsites": "^3.0.0",
+        "graceful-fs": "^4.2.9"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
     "node_modules/@jest/test-result": {
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/@jest/test-result/-/test-result-29.7.0.tgz",
       "integrity": "sha512-Fdx+tv6x1zlkJPcWXmMDAG2HBnaR9XPSd5aDWQVsfrZmLVT3lU1cwyxLgRmXR9yrq4NBoEm9BMsfgFzTQAbJYA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@jest/console": "^29.7.0",
@@ -7838,11 +7984,39 @@
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
+    "node_modules/@jest/test-sequencer": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/@jest/test-sequencer/-/test-sequencer-29.7.0.tgz",
+      "integrity": "sha512-GQwJ5WZVrKnOJuiYiAF52UNUJXgTZx1NHjFSEB0qEMmSZKAkdMoIzw/Cj6x6NF4AvV23AUqDpFzQkN/eYCYTxw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@jest/test-result": "^29.7.0",
+        "graceful-fs": "^4.2.9",
+        "jest-haste-map": "^29.7.0",
+        "slash": "^3.0.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/@jest/test-sequencer/node_modules/slash": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
+      "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/@jest/transform": {
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/@jest/transform/-/transform-29.7.0.tgz",
       "integrity": "sha512-ok/BTPFzFKVMwO5eOHRrvnBVHdRy9IrsrW1GpMaQ9MCnilNLXQKmAX8s1YXDFaai9xJpac2ySzV0YeRRECr2Vw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/core": "^7.11.6",
@@ -7869,14 +8043,14 @@
       "version": "3.0.7",
       "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
       "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "ISC"
     },
     "node_modules/@jest/transform/node_modules/slash": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
       "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -7886,7 +8060,7 @@
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/write-file-atomic/-/write-file-atomic-4.0.2.tgz",
       "integrity": "sha512-7KxauUdBmSdWnmpaGFg+ppNjKF8uNLry8LyzjauQDOVONfFLNKrKvQOxZ/VuTIcS/gge/YNahf5RIIQWTSarlg==",
-      "dev": true,
+      "devOptional": true,
       "license": "ISC",
       "dependencies": {
         "imurmurhash": "^0.1.4",
@@ -7968,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",
@@ -8892,225 +9086,6 @@
         "node": ">=12.4.0"
       }
     },
-    "node_modules/@noxcturnal/noxcturnal-darwin-arm64": {
-      "version": "0.1.5",
-      "resolved": "https://registry.npmjs.org/@noxcturnal/noxcturnal-darwin-arm64/-/noxcturnal-darwin-arm64-0.1.5.tgz",
-      "integrity": "sha512-hQgDaWxKYln83Uk1Hh4Liju9AvGoYh4aLd4A1ou3lGn5hxzhW2uO+z3mERtWk6BMGVazvi/yUXtp9x3IlaWyhA==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@noxcturnal/noxcturnal-darwin-x64": {
-      "version": "0.1.5",
-      "resolved": "https://registry.npmjs.org/@noxcturnal/noxcturnal-darwin-x64/-/noxcturnal-darwin-x64-0.1.5.tgz",
-      "integrity": "sha512-I57zR8QF7Xam+4nGD5UoIODsw0VjkVyn51iDBL3CMaDR5Lh1OxXwKZMYKtv3CtQl+RSDsMfmXBEqGYLE8lIPHg==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@noxcturnal/noxcturnal-linux-arm64-gnu": {
-      "version": "0.1.5",
-      "resolved": "https://registry.npmjs.org/@noxcturnal/noxcturnal-linux-arm64-gnu/-/noxcturnal-linux-arm64-gnu-0.1.5.tgz",
-      "integrity": "sha512-gVH4XJPh8RdrdjjlU0dKeielQt/FXfvqhr8IEWEf3VeNtQs8l2rPzFPdqS0uwLWQYHLBGgB0LkuOil1KKYx1gQ==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@noxcturnal/noxcturnal-linux-arm64-musl": {
-      "version": "0.1.5",
-      "resolved": "https://registry.npmjs.org/@noxcturnal/noxcturnal-linux-arm64-musl/-/noxcturnal-linux-arm64-musl-0.1.5.tgz",
-      "integrity": "sha512-rzQ075fcHZ+ebsELussRjnW8WBMy1RuLdS8wSqBGhdVlPR7/NaSyoWkNxnVDT8sEO26xjqGoW/o/08ghBzr/zA==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@noxcturnal/noxcturnal-linux-x64-gnu": {
-      "version": "0.1.5",
-      "resolved": "https://registry.npmjs.org/@noxcturnal/noxcturnal-linux-x64-gnu/-/noxcturnal-linux-x64-gnu-0.1.5.tgz",
-      "integrity": "sha512-X5O0lXMrv8HGOGoXDB1PG0Hjt7Rl+MJA+seR2NecQvUAAw2gzDvF/unCV5sqTAVeHfXhBHEFGkLenHZSD44efg==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@noxcturnal/noxcturnal-linux-x64-musl": {
-      "version": "0.1.5",
-      "resolved": "https://registry.npmjs.org/@noxcturnal/noxcturnal-linux-x64-musl/-/noxcturnal-linux-x64-musl-0.1.5.tgz",
-      "integrity": "sha512-fkQIQHRxqldNXVmjxfeCvGOiLhLU9SLBw1As02pMA2xjyiZfiXcUn4SUrZ92ciGnyCS8/XMbx+nZSxgEc3qDPw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@noxcturnal/noxcturnal-win32-arm64-msvc": {
-      "version": "0.1.5",
-      "resolved": "https://registry.npmjs.org/@noxcturnal/noxcturnal-win32-arm64-msvc/-/noxcturnal-win32-arm64-msvc-0.1.5.tgz",
-      "integrity": "sha512-baeH5m/vM1nf0J2UkW8cfgiVogpM0gRO9b4PZWknXQPbv5+k+0N5sGOYl/UAO2q72qYb3Xbiu7eD8c4A2kR2SA==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@noxcturnal/noxcturnal-win32-x64-msvc": {
-      "version": "0.1.5",
-      "resolved": "https://registry.npmjs.org/@noxcturnal/noxcturnal-win32-x64-msvc/-/noxcturnal-win32-x64-msvc-0.1.5.tgz",
-      "integrity": "sha512-2faDMzom8pCG/s/uR4Czh1atz4KohI85AaSmA2vtAuVnCq+nLL4Viys3A5vUlNz9MNBmTNFxzXyF2Z5HtfxXLg==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "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",
@@ -9387,17 +9362,6 @@
         "node": ">=8.0.0"
       }
     },
-    "node_modules/@oxc-project/types": {
-      "version": "0.154.0",
-      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.154.0.tgz",
-      "integrity": "sha512-KYOUGQFlLWR+s4QMV2Q9ko38TZm7EdO87Qm7rvZLqk/webse/cDjtyxKhg/47l0byCbs/k46LT8qc4PKjAikzA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "funding": {
-        "url": "https://github.com/sponsors/oxc-project"
-      }
-    },
     "node_modules/@oxc-resolver/binding-android-arm-eabi": {
       "version": "11.19.1",
       "resolved": "https://registry.npmjs.org/@oxc-resolver/binding-android-arm-eabi/-/binding-android-arm-eabi-11.19.1.tgz",
@@ -10411,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",
@@ -10429,13 +10448,13 @@
       }
     },
     "node_modules/@pkgr/core": {
-      "version": "0.2.9",
-      "resolved": "https://registry.npmjs.org/@pkgr/core/-/core-0.2.9.tgz",
-      "integrity": "sha512-QNqXyfVS2wm9hweSYD2O7F0G06uurj9kZ96TRQE5Y9hU7+tgdZwIkbAKc5Ocy1HxEY2kuDQa6cQ1WRs/O5LFKA==",
+      "version": "0.3.6",
+      "resolved": "https://registry.npmjs.org/@pkgr/core/-/core-0.3.6.tgz",
+      "integrity": "sha512-SEeaJLb3qBNF/OaXnaR1NmmBbFYk1zC0ZH/52fATcRPLFg/p791YrcyFFy44Bo9sLaGuSuLp5Q6axbb/O+v/RA==",
       "dev": true,
       "license": "MIT",
       "engines": {
-        "node": "^12.20.0 || ^14.18.0 || >=16.0.0"
+        "node": "^14.18.0 || >=16.0.0"
       },
       "funding": {
         "url": "https://opencollective.com/pkgr"
@@ -11020,17 +11039,6 @@
         "react-native": ">=0.57"
       }
     },
-    "node_modules/@react-native/asset-utils": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/asset-utils/-/asset-utils-0.88.0.tgz",
-      "integrity": "sha512-Bj1DxQt5f4OrjdlgSVkZT37Z3hx5hUIN5AUDSqL/e99vgtTcqj5vnm067epZL1EF/QiqsniZO8Q1GSkItOakDg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
     "node_modules/@react-native/assets-registry": {
       "version": "0.86.3",
       "resolved": "https://registry.npmjs.org/@react-native/assets-registry/-/assets-registry-0.86.3.tgz",
@@ -12073,7 +12081,7 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/@sinonjs/commons/-/commons-3.0.1.tgz",
       "integrity": "sha512-K3mCHKQ9sVh8o1C9cxkwxaOmXoAMlDxC1mYyHrjqOWEcBjYr76t96zL2zlj5dUGZ3HSw240X1qgH3Mjf1yJWpQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "BSD-3-Clause",
       "dependencies": {
         "type-detect": "4.0.8"
@@ -12083,7 +12091,7 @@
       "version": "10.3.0",
       "resolved": "https://registry.npmjs.org/@sinonjs/fake-timers/-/fake-timers-10.3.0.tgz",
       "integrity": "sha512-V4BG07kuYSUkTCSBHG8G8TNhM+F19jXFWnQtzj+we8DrkpSBCee9Z3Ms8yiGer/dlmhe35/Xdgyo3/0rQKg7YA==",
-      "dev": true,
+      "devOptional": true,
       "license": "BSD-3-Clause",
       "dependencies": {
         "@sinonjs/commons": "^3.0.0"
@@ -12556,6 +12564,151 @@
         }
       }
     },
+    "node_modules/@testing-library/react-native": {
+      "version": "13.3.3",
+      "resolved": "https://registry.npmjs.org/@testing-library/react-native/-/react-native-13.3.3.tgz",
+      "integrity": "sha512-k6Mjsd9dbZgvY4Bl7P1NIpePQNi+dfYtlJ5voi9KQlynxSyQkfOgJmYGCYmw/aSgH/rUcFvG8u5gd4npzgRDyg==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "jest-matcher-utils": "^30.0.5",
+        "picocolors": "^1.1.1",
+        "pretty-format": "^30.0.5",
+        "redent": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "jest": ">=29.0.0",
+        "react": ">=18.2.0",
+        "react-native": ">=0.71",
+        "react-test-renderer": ">=18.2.0"
+      },
+      "peerDependenciesMeta": {
+        "jest": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@testing-library/react-native/node_modules/@jest/schemas": {
+      "version": "30.5.0",
+      "resolved": "https://registry.npmjs.org/@jest/schemas/-/schemas-30.5.0.tgz",
+      "integrity": "sha512-/hunigyNpc4RCjC0VaW3f5RCUZVM2+WQ65qP7z083Gmvac7or2LI50XVNOtE4YPgBpV0yxYiAgorAPGniCoJmg==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "@sinclair/typebox": "^0.34.0"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@testing-library/react-native/node_modules/@sinclair/typebox": {
+      "version": "0.34.52",
+      "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.34.52.tgz",
+      "integrity": "sha512-XiMQh7qqVlxZzcVD+kkGMNGMzcTrDMLWI7S4x7z1MkCkbDPrekpZXEUK0eZqZFMuHQg2a2DZOcDIh9o5v3Gonw==",
+      "devOptional": true,
+      "license": "MIT"
+    },
+    "node_modules/@testing-library/react-native/node_modules/ansi-styles": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz",
+      "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
+      "devOptional": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/@testing-library/react-native/node_modules/indent-string": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/indent-string/-/indent-string-4.0.0.tgz",
+      "integrity": "sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==",
+      "devOptional": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@testing-library/react-native/node_modules/jest-diff": {
+      "version": "30.5.2",
+      "resolved": "https://registry.npmjs.org/jest-diff/-/jest-diff-30.5.2.tgz",
+      "integrity": "sha512-rBtHnI6BWTiWj3lM7fOLVfChx7R9B0u9VV3PRHawKs79x6ZjW1QoSrKenaigNGWlvhtoi2BqvDbABDie+Os3xQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/diff-sequences": "30.5.0",
+        "@jest/get-type": "30.5.0",
+        "chalk": "^4.1.2",
+        "pretty-format": "30.5.1"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@testing-library/react-native/node_modules/jest-matcher-utils": {
+      "version": "30.5.2",
+      "resolved": "https://registry.npmjs.org/jest-matcher-utils/-/jest-matcher-utils-30.5.2.tgz",
+      "integrity": "sha512-lFkB365PTIHOhPzwrb9T6gvlDnPpOZ7/c3ewOKKB7bzztqjVrtlyRL2MkyfJXpyY2u2SKw001JKrTx14fBUFcQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/get-type": "30.5.0",
+        "chalk": "^4.1.2",
+        "jest-diff": "30.5.2",
+        "pretty-format": "30.5.1"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@testing-library/react-native/node_modules/pretty-format": {
+      "version": "30.5.1",
+      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-30.5.1.tgz",
+      "integrity": "sha512-byhRAPguVKMQIj4kjJwJ5lAskVhfuiSdiYl/aLTWpgkGEmic2jYhJh1yE9ih8Ox44Xg9ccCT11/S6QrzSJuNrg==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/react-is-18": "npm:react-is@^18.3.1",
+        "@jest/react-is-19": "npm:react-is@^19.2.5",
+        "@jest/schemas": "30.5.0",
+        "ansi-styles": "^5.2.0"
+      },
+      "engines": {
+        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@testing-library/react-native/node_modules/redent": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/redent/-/redent-3.0.0.tgz",
+      "integrity": "sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "indent-string": "^4.0.0",
+        "strip-indent": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@testing-library/react-native/node_modules/strip-indent": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-3.0.0.tgz",
+      "integrity": "sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "min-indent": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/@tootallnate/once": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/@tootallnate/once/-/once-2.0.0.tgz",
@@ -12623,7 +12776,7 @@
       "version": "7.20.5",
       "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz",
       "integrity": "sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/parser": "^7.20.7",
@@ -12637,7 +12790,7 @@
       "version": "7.27.0",
       "resolved": "https://registry.npmjs.org/@types/babel__generator/-/babel__generator-7.27.0.tgz",
       "integrity": "sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/types": "^7.0.0"
@@ -12647,7 +12800,7 @@
       "version": "7.4.4",
       "resolved": "https://registry.npmjs.org/@types/babel__template/-/babel__template-7.4.4.tgz",
       "integrity": "sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/parser": "^7.1.0",
@@ -12658,7 +12811,7 @@
       "version": "7.28.0",
       "resolved": "https://registry.npmjs.org/@types/babel__traverse/-/babel__traverse-7.28.0.tgz",
       "integrity": "sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/types": "^7.28.2"
@@ -13065,7 +13218,7 @@
       "version": "4.1.9",
       "resolved": "https://registry.npmjs.org/@types/graceful-fs/-/graceful-fs-4.1.9.tgz",
       "integrity": "sha512-olP3sd1qOEe5dXTSaFvQG+02VdRXcdytWLAZsAq1PecU8uqQAhkrnbli7DagjtXKW/Bl7YJbUsa8MPcuc8LHEQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@types/node": "*"
@@ -13248,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",
@@ -13373,7 +13514,7 @@
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/@types/stack-utils/-/stack-utils-2.0.3.tgz",
       "integrity": "sha512-9aEbYZ3TbYMznPdcdr3SmIrLXwC/AKZXQeCf9Pgao5CKb8CyHuEX5jzWPTkvregvhRJHcpRO6BFoGW9ycaOkYw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/@types/tough-cookie": {
@@ -13410,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",
@@ -13443,6 +13576,288 @@
       "integrity": "sha512-I4q9QU9MQv4oEOz4tAHJtNz1cwuLxn2F3xcc2iV5WdqLPpUnj30aUuxt1mAxYTG+oe8CZMV/+6rU4S4gRDzqtQ==",
       "license": "MIT"
     },
+    "node_modules/@typescript-eslint/eslint-plugin": {
+      "version": "8.72.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.72.1.tgz",
+      "integrity": "sha512-5CokTWXpmbylfFabsbvHC0CAw3XLaGnoa+nFJX5FR592h/LoZsENUE6p/rg5xvkKrFEXz6pYmgI29AgXc2N3BQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@eslint-community/regexpp": "^4.12.2",
+        "@typescript-eslint/scope-manager": "8.72.1",
+        "@typescript-eslint/type-utils": "8.72.1",
+        "@typescript-eslint/utils": "8.72.1",
+        "@typescript-eslint/visitor-keys": "8.72.1",
+        "ignore": "^7.0.5",
+        "natural-compare": "^1.4.0",
+        "ts-api-utils": "^2.5.0"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      },
+      "peerDependencies": {
+        "@typescript-eslint/parser": "^8.72.1",
+        "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
+        "typescript": ">=4.8.4 <6.1.0"
+      }
+    },
+    "node_modules/@typescript-eslint/eslint-plugin/node_modules/ignore": {
+      "version": "7.0.14",
+      "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.14.tgz",
+      "integrity": "sha512-wCBiZ77u1tuWde6G/nfOtLaCTYcFDU5yCzARzK10y+rLhzYoL7a7yEemcopcc2Mzow7gZOIjnV2ym1NYmdiJOQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 4"
+      }
+    },
+    "node_modules/@typescript-eslint/parser": {
+      "version": "8.72.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.72.1.tgz",
+      "integrity": "sha512-ZGwZP4OCfyA0AQTpEAMWz+rtX01DRhQWW5hB0ucKDEIX5U7jdmPSaMx94rQfaPAQzIYz2BimOgKOJtjfpRFQ9g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@typescript-eslint/scope-manager": "8.72.1",
+        "@typescript-eslint/types": "8.72.1",
+        "@typescript-eslint/typescript-estree": "8.72.1",
+        "@typescript-eslint/visitor-keys": "8.72.1",
+        "debug": "^4.4.3"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      },
+      "peerDependencies": {
+        "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
+        "typescript": ">=4.8.4 <6.1.0"
+      }
+    },
+    "node_modules/@typescript-eslint/project-service": {
+      "version": "8.72.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.72.1.tgz",
+      "integrity": "sha512-fAuVMkwdO/huI8nyo/WKnNKf6Gag93S56Rh3Ts5mGcavwSdaN8tRg1gCeIGX8PF+nzp1BjGfO4gHhGzW1J6jTg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@typescript-eslint/tsconfig-utils": "^8.72.1",
+        "@typescript-eslint/types": "^8.72.1",
+        "debug": "^4.4.3"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      },
+      "peerDependencies": {
+        "typescript": ">=4.8.4 <6.1.0"
+      }
+    },
+    "node_modules/@typescript-eslint/scope-manager": {
+      "version": "8.72.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.72.1.tgz",
+      "integrity": "sha512-lC/t6eMCZZQAAKZEYGL6RDVSuFehpdmMT6h+nJIjIa6oylN/PwDgDVtEIbB7O9xFfZYtZAYLoLlDNWKJhtF+uQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@typescript-eslint/types": "8.72.1",
+        "@typescript-eslint/visitor-keys": "8.72.1"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      }
+    },
+    "node_modules/@typescript-eslint/tsconfig-utils": {
+      "version": "8.72.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.72.1.tgz",
+      "integrity": "sha512-e4D5R5vpeAEPBxT2BAzsFQL3sbwyeeeo5+aczgNSRK1V734jE7pTqaGFU+fXapWEQwnZbpFaTn32+Z8DwS6OTg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      },
+      "peerDependencies": {
+        "typescript": ">=4.8.4 <6.1.0"
+      }
+    },
+    "node_modules/@typescript-eslint/type-utils": {
+      "version": "8.72.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-8.72.1.tgz",
+      "integrity": "sha512-iY2wlmyrXJmx4yxUGP3aYCFF3cA/6ShddOKmLU2dx7LnEykbAM8WThlxZEfd1NddqceF6eJmZUayxx9oKIYNlg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@typescript-eslint/types": "8.72.1",
+        "@typescript-eslint/typescript-estree": "8.72.1",
+        "@typescript-eslint/utils": "8.72.1",
+        "debug": "^4.4.3",
+        "ts-api-utils": "^2.5.0"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      },
+      "peerDependencies": {
+        "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
+        "typescript": ">=4.8.4 <6.1.0"
+      }
+    },
+    "node_modules/@typescript-eslint/types": {
+      "version": "8.72.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.72.1.tgz",
+      "integrity": "sha512-LmE5IhQet1BWOWEXqBrVtBPsMAOQ6Nzk35d+WLh3mk4EUF33sqlfxjio1MdYeSvKSG5skactKKuixBIKXhL4Rw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      }
+    },
+    "node_modules/@typescript-eslint/typescript-estree": {
+      "version": "8.72.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.72.1.tgz",
+      "integrity": "sha512-DAlUoUV93hIvrtIQLwCbmZQYVZwOMhiHJrOVUUIWicFZaIYjTRqlY3I/NZevfkLmSqkNHRu2qYDcq9lrn16oOQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@typescript-eslint/project-service": "8.72.1",
+        "@typescript-eslint/tsconfig-utils": "8.72.1",
+        "@typescript-eslint/types": "8.72.1",
+        "@typescript-eslint/visitor-keys": "8.72.1",
+        "debug": "^4.4.3",
+        "minimatch": "^10.2.2",
+        "semver": "^7.7.3",
+        "tinyglobby": "^0.2.15",
+        "ts-api-utils": "^2.5.0"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      },
+      "peerDependencies": {
+        "typescript": ">=4.8.4 <6.1.0"
+      }
+    },
+    "node_modules/@typescript-eslint/typescript-estree/node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "node_modules/@typescript-eslint/typescript-estree/node_modules/brace-expansion": {
+      "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": "20 || >=22"
+      }
+    },
+    "node_modules/@typescript-eslint/typescript-estree/node_modules/minimatch": {
+      "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.8"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/@typescript-eslint/utils": {
+      "version": "8.72.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-8.72.1.tgz",
+      "integrity": "sha512-5v5liypurJBFHCBNqh/RjsymAD+VWcE0djuGY/BUqp5fC3Qn+luWDEksjuTtWjPn6i5zQlUtkZCRG/CYG0yCkA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@eslint-community/eslint-utils": "^4.9.1",
+        "@typescript-eslint/scope-manager": "8.72.1",
+        "@typescript-eslint/types": "8.72.1",
+        "@typescript-eslint/typescript-estree": "8.72.1"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      },
+      "peerDependencies": {
+        "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
+        "typescript": ">=4.8.4 <6.1.0"
+      }
+    },
+    "node_modules/@typescript-eslint/visitor-keys": {
+      "version": "8.72.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.72.1.tgz",
+      "integrity": "sha512-SB8xqipSzZHUePCCLNeYxqnxq83X61/qzNhjQGbTfjxGZIeOEP7tBgWYX05Tcd6CgE02WdTJnh5b8kMZJ/+bnQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@typescript-eslint/types": "8.72.1",
+        "eslint-visitor-keys": "^5.0.0"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      }
+    },
+    "node_modules/@typescript-eslint/visitor-keys/node_modules/eslint-visitor-keys": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-5.0.1.tgz",
+      "integrity": "sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": "^20.19.0 || ^22.13.0 || >=24"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
     "node_modules/@typescript/native-preview": {
       "version": "7.0.0-dev.20260423.1",
       "resolved": "https://registry.npmjs.org/@typescript/native-preview/-/native-preview-7.0.0-dev.20260423.1.tgz",
@@ -14236,10 +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/*"
@@ -14252,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",
@@ -14520,7 +14970,7 @@
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz",
       "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==",
-      "dev": true,
+      "devOptional": true,
       "license": "ISC",
       "dependencies": {
         "normalize-path": "^3.0.0",
@@ -14534,7 +14984,7 @@
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz",
       "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=8.6"
@@ -14543,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",
@@ -14584,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",
@@ -14592,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": {
@@ -14649,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",
@@ -14660,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": {
@@ -14732,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"
@@ -14761,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": {
@@ -15052,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": {
@@ -15165,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",
@@ -15208,7 +15711,7 @@
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/babel-jest/-/babel-jest-29.7.0.tgz",
       "integrity": "sha512-BrvGY3xZSwEcCzKvKsCi2GgHqDqsYkOP4/by5xCgIwGXQxIEh+8ew3gmrE1y7XRR6LHZIj6yLYnUi/mm2KXKBg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@jest/transform": "^29.7.0",
@@ -15230,7 +15733,7 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
       "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -15250,7 +15753,7 @@
       "version": "6.1.1",
       "resolved": "https://registry.npmjs.org/babel-plugin-istanbul/-/babel-plugin-istanbul-6.1.1.tgz",
       "integrity": "sha512-Y1IQok9821cC9onCx5otgFfRm7Lm+I+wwxOx738M/WLPZ9Q42m4IG5W0FNX8WLL2gYMZo3JkuXIH2DOpWM+qwA==",
-      "dev": true,
+      "devOptional": true,
       "license": "BSD-3-Clause",
       "dependencies": {
         "@babel/helper-plugin-utils": "^7.0.0",
@@ -15267,7 +15770,7 @@
       "version": "29.6.3",
       "resolved": "https://registry.npmjs.org/babel-plugin-jest-hoist/-/babel-plugin-jest-hoist-29.6.3.tgz",
       "integrity": "sha512-ESAc/RJvGTFEzRwOTT4+lNDk/GNHMkKbNzsvT0qKRfDyyYTskxB5rnU2njIDYVxXCBHHEI1c0YwHob3WaYujOg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/template": "^7.3.3",
@@ -15365,7 +15868,7 @@
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/babel-preset-current-node-syntax/-/babel-preset-current-node-syntax-1.2.0.tgz",
       "integrity": "sha512-E/VlAEzRrsLEb2+dv8yp3bo4scof3l9nR4lrld+Iy5NyVqgVYUJnDAmunkhPMisRI32Qc4iRiz425d8vM++2fg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/plugin-syntax-async-generators": "^7.8.4",
@@ -15436,7 +15939,7 @@
       "version": "29.6.3",
       "resolved": "https://registry.npmjs.org/babel-preset-jest/-/babel-preset-jest-29.6.3.tgz",
       "integrity": "sha512-0B3bhxR6snWXJZtR/RliHTDPRgn1sNHOR0yVtq/IiQFyuOVjFS+wuio/R4gSNkyYmKmJB4wGZv2NZanmKmTnNA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "babel-plugin-jest-hoist": "^29.6.3",
@@ -15469,7 +15972,7 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
       "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/barcode-detector": {
@@ -15607,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",
@@ -15809,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",
@@ -15831,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": {
@@ -15856,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",
@@ -15912,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": {
@@ -16103,7 +16544,7 @@
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz",
       "integrity": "sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=6"
@@ -16378,6 +16819,14 @@
         "node": ">=8"
       }
     },
+    "node_modules/cjs-module-lexer": {
+      "version": "1.4.3",
+      "resolved": "https://registry.npmjs.org/cjs-module-lexer/-/cjs-module-lexer-1.4.3.tgz",
+      "integrity": "sha512-9z8TZaGM1pfswYeXrUpzPrkx8UnWYdhJclsiYMm6x/w5+nN+8Tf/LnAgfLGQCm59qAOxU8WwHEq2vNwF6i4j+Q==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true
+    },
     "node_modules/clean-stack": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/clean-stack/-/clean-stack-3.0.1.tgz",
@@ -16432,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",
@@ -16508,11 +16923,23 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/co": {
+      "version": "4.6.0",
+      "resolved": "https://registry.npmjs.org/co/-/co-4.6.0.tgz",
+      "integrity": "sha512-QVb0dM5HvG+uaxitm8wONl7jltx8dqhfU33DcqtOZcLSVIKSDDLDi7+0LbAKiyI8hD9u42m2YxXSkMGWThaecQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "iojs": ">= 1.0.0",
+        "node": ">= 0.12.0"
+      }
+    },
     "node_modules/collect-v8-coverage": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/collect-v8-coverage/-/collect-v8-coverage-1.0.3.tgz",
       "integrity": "sha512-1L5aqIkwPfiodaMgQunkF1zRhNqifHBmtbbbxcr6yVxxBnliw4TDOW6NxpO8DJLgJ16OT+Y4ztZqP6p/FtXnAw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/color": {
@@ -16677,7 +17104,7 @@
       "version": "0.0.1",
       "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
       "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/concurrently": {
@@ -16839,41 +17266,27 @@
         "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,
+    "node_modules/create-jest": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/create-jest/-/create-jest-29.7.0.tgz",
+      "integrity": "sha512-Adz2bdH0Vq3F53KEMJOoftQFutWCukm6J24wbPWRO4k1kMY7gS7ds/uoJkNuV8wDCtWWnuwGcJwpWcih+zEW1Q==",
+      "devOptional": true,
       "license": "MIT",
-      "optional": true,
+      "peer": 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"
+        "@jest/types": "^29.6.3",
+        "chalk": "^4.0.0",
+        "exit": "^0.1.2",
+        "graceful-fs": "^4.2.9",
+        "jest-config": "^29.7.0",
+        "jest-util": "^29.7.0",
+        "prompts": "^2.0.1"
+      },
+      "bin": {
+        "create-jest": "bin/create-jest.js"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
     "node_modules/create-require": {
@@ -16889,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",
@@ -17797,6 +18219,22 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/dedent": {
+      "version": "1.7.2",
+      "resolved": "https://registry.npmjs.org/dedent/-/dedent-1.7.2.tgz",
+      "integrity": "sha512-WzMx3mW98SN+zn3hgemf4OzdmyNhhhKz5Ay0pUfQiMQ3e1g+xmTJWp/pKdwKVXhdSkAEGIIzqeuWrL3mV/AXbA==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "babel-plugin-macros": "^3.1.0"
+      },
+      "peerDependenciesMeta": {
+        "babel-plugin-macros": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/deep-is": {
       "version": "0.1.4",
       "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz",
@@ -17964,6 +18402,17 @@
         "node": ">=8"
       }
     },
+    "node_modules/detect-newline": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/detect-newline/-/detect-newline-3.1.0.tgz",
+      "integrity": "sha512-TLz+x/vEXm/Y7P7wn1EJFNLxYpUD4TgMosxY6fAVJUnJMbupHBOncxyWUG9OpTaH9EBD7uFI5LfEgmMOc54DsA==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/detect-node": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/detect-node/-/detect-node-2.1.0.tgz",
@@ -18004,7 +18453,7 @@
       "version": "29.6.3",
       "resolved": "https://registry.npmjs.org/diff-sequences/-/diff-sequences-29.6.3.tgz",
       "integrity": "sha512-EjePK1srD3P08o2j4f0ExnylqRs5B9tJjcp9t1krH2qRi8CCdsYfwe9JgSLurFBWwq4uOlipzfk5fHNvwFKr8Q==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
@@ -18028,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": {
@@ -18065,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",
@@ -18325,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",
@@ -18646,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",
@@ -18671,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",
@@ -18697,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",
@@ -18713,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",
@@ -18748,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",
@@ -18769,7 +19273,7 @@
       "version": "0.13.1",
       "resolved": "https://registry.npmjs.org/emittery/-/emittery-0.13.1.tgz",
       "integrity": "sha512-DeWwawk6r5yR9jFgnDKYt4sLS0LmHJJi3ZOnb5/JdbYwj3nW+FxQnHIjhBKz8YLC7oRNPVM9NQ47I3CVx34eqQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=12"
@@ -18869,7 +19373,7 @@
       "version": "1.3.4",
       "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.4.tgz",
       "integrity": "sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "is-arrayish": "^0.2.1"
@@ -19189,7 +19693,6 @@
       "dev": true,
       "license": "BSD-3-Clause",
       "optional": true,
-      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -19270,6 +19773,60 @@
         "eslint": ">=6.0.0"
       }
     },
+    "node_modules/eslint-config-prettier": {
+      "version": "9.1.2",
+      "resolved": "https://registry.npmjs.org/eslint-config-prettier/-/eslint-config-prettier-9.1.2.tgz",
+      "integrity": "sha512-iI1f+D2ViGn+uvv5HuHVUamg8ll4tN+JRHGc6IJi4TP9Kl976C57fzPXgseXNs8v0iA8aSJpHsTWjDb9QJamGQ==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "eslint-config-prettier": "bin/cli.js"
+      },
+      "peerDependencies": {
+        "eslint": ">=7.0.0"
+      }
+    },
+    "node_modules/eslint-config-universe": {
+      "version": "15.2.0",
+      "resolved": "https://registry.npmjs.org/eslint-config-universe/-/eslint-config-universe-15.2.0.tgz",
+      "integrity": "sha512-n2662q/mM+2pTFVz7ELosqhN+/nbR75Ut/4vLme40kKSHHe0oPbPMxgPqyYrASlANuSDP4aAJ71rRviDMCZTxg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@typescript-eslint/eslint-plugin": "^8.59.0",
+        "@typescript-eslint/parser": "^8.59.0",
+        "eslint-config-prettier": "^9.1.0",
+        "eslint-plugin-import": "^2.31.0",
+        "eslint-plugin-n": "^17.17.0",
+        "eslint-plugin-node": "^11.1.0",
+        "eslint-plugin-prettier": "^5.2.6",
+        "eslint-plugin-react": "^7.37.5",
+        "eslint-plugin-react-hooks": "^7.0.0",
+        "globals": "^16.0.0"
+      },
+      "peerDependencies": {
+        "eslint": ">=8.10",
+        "prettier": ">=3"
+      },
+      "peerDependenciesMeta": {
+        "prettier": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/eslint-config-universe/node_modules/globals": {
+      "version": "16.5.0",
+      "resolved": "https://registry.npmjs.org/globals/-/globals-16.5.0.tgz",
+      "integrity": "sha512-c/c15i26VrJ4IRt5Z89DnIzCGDn9EcebibhAOjw5ibqEHsE1wLUgkPn9RDmNcUKyU87GeaL633nyJ+pplFR2ZQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/eslint-import-resolver-node": {
       "version": "0.3.9",
       "resolved": "https://registry.npmjs.org/eslint-import-resolver-node/-/eslint-import-resolver-node-0.3.9.tgz",
@@ -19547,9 +20104,9 @@
       }
     },
     "node_modules/eslint-plugin-node/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": {
@@ -19581,14 +20138,14 @@
       }
     },
     "node_modules/eslint-plugin-prettier": {
-      "version": "5.5.5",
-      "resolved": "https://registry.npmjs.org/eslint-plugin-prettier/-/eslint-plugin-prettier-5.5.5.tgz",
-      "integrity": "sha512-hscXkbqUZ2sPithAuLm5MXL+Wph+U7wHngPBv9OMWwlP8iaflyxpjTYZkmdgB4/vPIhemRlBEoLrH7UC1n7aUw==",
+      "version": "5.5.7",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-prettier/-/eslint-plugin-prettier-5.5.7.tgz",
+      "integrity": "sha512-WjHyn3GrFd+ZR0rzsLiM4zJZ35PZMOE0SUIxzGmnWNG0126yNfJKJzObmmkYDwHJfGlkz3PSlzyG9ez/LJntwg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "prettier-linter-helpers": "^1.0.1",
-        "synckit": "^0.11.12"
+        "synckit": "^0.12.3"
       },
       "engines": {
         "node": "^14.18.0 || >=16.0.0"
@@ -19644,6 +20201,43 @@
         "eslint": "^3 || ^4 || ^5 || ^6 || ^7 || ^8 || ^9.7"
       }
     },
+    "node_modules/eslint-plugin-react-hooks": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-react-hooks/-/eslint-plugin-react-hooks-7.1.1.tgz",
+      "integrity": "sha512-f2I7Gw6JbvCexzIInuSbZpfdQ44D7iqdWX01FKLvrPgqxoE7oMj8clOfto8U6vYiz4yd5oKu39rRSVOe1zRu0g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/core": "^7.24.4",
+        "@babel/parser": "^7.24.4",
+        "hermes-parser": "^0.25.1",
+        "zod": "^3.25.0 || ^4.0.0",
+        "zod-validation-error": "^3.5.0 || ^4.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "eslint": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0 || ^10.0.0"
+      }
+    },
+    "node_modules/eslint-plugin-react-hooks/node_modules/hermes-estree": {
+      "version": "0.25.1",
+      "resolved": "https://registry.npmjs.org/hermes-estree/-/hermes-estree-0.25.1.tgz",
+      "integrity": "sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/eslint-plugin-react-hooks/node_modules/hermes-parser": {
+      "version": "0.25.1",
+      "resolved": "https://registry.npmjs.org/hermes-parser/-/hermes-parser-0.25.1.tgz",
+      "integrity": "sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "hermes-estree": "0.25.1"
+      }
+    },
     "node_modules/eslint-plugin-react/node_modules/brace-expansion": {
       "version": "1.1.12",
       "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
@@ -19841,7 +20435,7 @@
       "version": "4.0.1",
       "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
       "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
-      "dev": true,
+      "devOptional": true,
       "license": "BSD-2-Clause",
       "bin": {
         "esparse": "bin/esparse.js",
@@ -19990,11 +20584,54 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/execa": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/execa/-/execa-5.1.1.tgz",
+      "integrity": "sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "cross-spawn": "^7.0.3",
+        "get-stream": "^6.0.0",
+        "human-signals": "^2.1.0",
+        "is-stream": "^2.0.0",
+        "merge-stream": "^2.0.0",
+        "npm-run-path": "^4.0.1",
+        "onetime": "^5.1.2",
+        "signal-exit": "^3.0.3",
+        "strip-final-newline": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sindresorhus/execa?sponsor=1"
+      }
+    },
+    "node_modules/execa/node_modules/signal-exit": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
+      "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
+      "devOptional": true,
+      "license": "ISC",
+      "peer": true
+    },
+    "node_modules/exit": {
+      "version": "0.1.2",
+      "resolved": "https://registry.npmjs.org/exit/-/exit-0.1.2.tgz",
+      "integrity": "sha512-Zk/eNKV2zbjpKzrsQ+n1G6poVbErQxJ0LBOJXaKZ1EViLzH+hrLu9cdXI4zw9dBQJslwBEpbQ2P1oS7nDxs6jQ==",
+      "devOptional": true,
+      "peer": true,
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
     "node_modules/expect": {
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/expect/-/expect-29.7.0.tgz",
       "integrity": "sha512-2Zks0hf1VLFYI1kbh0I5jP3KHHyCHpkfyHBzsSXRFgl/Bg9mWYfMW8oD+PdMPlEwy5HNsR9JutYy6pMeOh61nw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@jest/expect-utils": "^29.7.0",
@@ -20246,6 +20883,131 @@
         "react-native": "*"
       }
     },
+    "node_modules/expo-module-scripts": {
+      "version": "5.0.8",
+      "resolved": "https://registry.npmjs.org/expo-module-scripts/-/expo-module-scripts-5.0.8.tgz",
+      "integrity": "sha512-3YkAic3E6QGQuNEIchq6/0GGSBwR2C70AhDUF7VI7/N3THwUpeqZrX20FxHKN95/wclHs1ljrGvRX+2YTgXxiw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/cli": "^7.23.4",
+        "@babel/plugin-transform-export-namespace-from": "^7.23.4",
+        "@babel/preset-env": "^7.23.8",
+        "@babel/preset-typescript": "^7.23.3",
+        "@expo/npm-proofread": "^1.0.1",
+        "@testing-library/react-native": "^13.2.0",
+        "@tsconfig/node18": "^18.2.2",
+        "@types/jest": "^29.2.1",
+        "babel-plugin-dynamic-import-node": "^2.3.3",
+        "babel-preset-expo": "~54.0.7",
+        "commander": "^12.1.0",
+        "eslint-config-universe": "^15.0.3",
+        "glob": "^13.0.0",
+        "jest-expo": "~54.0.13",
+        "jest-snapshot-prettier": "npm:prettier@^2",
+        "jest-watch-typeahead": "2.2.1",
+        "resolve-workspace-root": "^2.0.0",
+        "ts-jest": "~29.0.4",
+        "typescript": "^5.9.2"
+      },
+      "bin": {
+        "expo-module": "bin/expo-module.js"
+      }
+    },
+    "node_modules/expo-module-scripts/node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "node_modules/expo-module-scripts/node_modules/brace-expansion": {
+      "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": "20 || >=22"
+      }
+    },
+    "node_modules/expo-module-scripts/node_modules/commander": {
+      "version": "12.1.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
+      "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/expo-module-scripts/node_modules/glob": {
+      "version": "13.0.6",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz",
+      "integrity": "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "minimatch": "^10.2.2",
+        "minipass": "^7.1.3",
+        "path-scurry": "^2.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/expo-module-scripts/node_modules/lru-cache": {
+      "version": "11.5.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.3.tgz",
+      "integrity": "sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
+    "node_modules/expo-module-scripts/node_modules/minimatch": {
+      "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.8"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/expo-module-scripts/node_modules/path-scurry": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz",
+      "integrity": "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "lru-cache": "^11.0.0",
+        "minipass": "^7.1.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/expo-modules-autolinking": {
       "version": "57.0.16",
       "resolved": "https://registry.npmjs.org/expo-modules-autolinking/-/expo-modules-autolinking-57.0.16.tgz",
@@ -20303,18 +21065,6 @@
         "react-native": "*"
       }
     },
-    "node_modules/expo-modules-macros": {
-      "version": "0.20.0",
-      "resolved": "https://registry.npmjs.org/expo-modules-macros/-/expo-modules-macros-0.20.0.tgz",
-      "integrity": "sha512-Ekgb5c9LQPM9CPnmDZdeWcOa1eBbCDUGrgdN5lIFNH2GWDUf9doeAOK7IqQOOVviamy37eIp5FW+N1zyrIwzoA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "optionalDependencies": {
-        "@expo/modules-macros-win32-arm64": "0.20.0",
-        "@expo/modules-macros-win32-x64": "0.20.0"
-      }
-    },
     "node_modules/expo-router": {
       "version": "57.0.28",
       "resolved": "https://registry.npmjs.org/expo-router/-/expo-router-57.0.28.tgz",
@@ -20857,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",
@@ -20947,7 +21686,7 @@
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz",
       "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/fast-levenshtein": {
@@ -21293,31 +22032,6 @@
       "integrity": "sha512-3PYnM29RFXwvAN6Pc/scUfkI7RwhQ/xqyLUyPNlXUp9S40zI8nup9tUSrTLSVnWGBN38FNiGWbwZOB6uR4OGdw==",
       "license": "MIT"
     },
-    "node_modules/flow-estree": {
-      "version": "0.331.0",
-      "resolved": "https://registry.npmjs.org/flow-estree/-/flow-estree-0.331.0.tgz",
-      "integrity": "sha512-FVLYkSL/ITb/QXBEQvNWPjPooRGswuUtGOwrH+puSlMDneNkxy640+FZsk/TfKL+b7Wbw/Fg9FTUv2bMQDpj2w==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/flow-parser": {
-      "version": "0.331.0",
-      "resolved": "https://registry.npmjs.org/flow-parser/-/flow-parser-0.331.0.tgz",
-      "integrity": "sha512-vEZcHIlnKeN8JSVtYFczj8sWJfHIJOkz+YG00O/oul/Bete+t1ZhTi+O6JRRLFYvGW+yJkZ0YgL16iStnbkUqQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "flow-estree": "0.331.0"
-      },
-      "engines": {
-        "node": ">=0.4.0"
-      }
-    },
     "node_modules/follow-redirects": {
       "version": "1.15.11",
       "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.11.tgz",
@@ -21507,7 +22221,7 @@
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
       "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==",
-      "dev": true,
+      "devOptional": true,
       "license": "ISC"
     },
     "node_modules/fsevents": {
@@ -21629,7 +22343,7 @@
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/get-package-type/-/get-package-type-0.1.0.tgz",
       "integrity": "sha512-pjzuKtY64GYfWizNAJ0fr9VqttZkNiK2iS430LtIHzjBEr6bX8Am2zm4sW4Ro5wjWW5cAlRL1qAMTcXbjNAO2Q==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=8.0.0"
@@ -21681,6 +22395,20 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/get-stream": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-6.0.1.tgz",
+      "integrity": "sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/get-symbol-description": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/get-symbol-description/-/get-symbol-description-1.1.0.tgz",
@@ -22394,6 +23122,14 @@
         "node": ">=12"
       }
     },
+    "node_modules/html-escaper": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
+      "integrity": "sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true
+    },
     "node_modules/html-parse-stringify": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/html-parse-stringify/-/html-parse-stringify-3.0.1.tgz",
@@ -22424,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"
     },
@@ -22525,6 +23261,17 @@
         "node": ">= 6"
       }
     },
+    "node_modules/human-signals": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-2.1.0.tgz",
+      "integrity": "sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw==",
+      "devOptional": true,
+      "license": "Apache-2.0",
+      "peer": true,
+      "engines": {
+        "node": ">=10.17.0"
+      }
+    },
     "node_modules/hyperlinker": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/hyperlinker/-/hyperlinker-1.0.0.tgz",
@@ -22569,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",
@@ -22671,6 +23392,27 @@
         "node": ">=4"
       }
     },
+    "node_modules/import-local": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/import-local/-/import-local-3.2.0.tgz",
+      "integrity": "sha512-2SPlun1JUPWoM6t3F0dw0FkCF/jWY8kttcY4f599GLTSjh2OCuuhdTkJQsEcZzBqbXZGKMK2OqW1oZsjtf/gQA==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "pkg-dir": "^4.2.0",
+        "resolve-cwd": "^3.0.0"
+      },
+      "bin": {
+        "import-local-fixture": "fixtures/cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/import-meta-resolve": {
       "version": "4.2.0",
       "resolved": "https://registry.npmjs.org/import-meta-resolve/-/import-meta-resolve-4.2.0.tgz",
@@ -22685,7 +23427,7 @@
       "version": "0.1.4",
       "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz",
       "integrity": "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=0.8.19"
@@ -22709,7 +23451,7 @@
       "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
       "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==",
       "deprecated": "This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.",
-      "dev": true,
+      "devOptional": true,
       "license": "ISC",
       "dependencies": {
         "once": "^1.3.0",
@@ -22847,7 +23589,7 @@
       "version": "0.2.1",
       "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz",
       "integrity": "sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/is-async-function": {
@@ -23057,6 +23799,17 @@
         "node": ">=8"
       }
     },
+    "node_modules/is-generator-fn": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/is-generator-fn/-/is-generator-fn-2.1.0.tgz",
+      "integrity": "sha512-cTIB4yPYL/Grw0EaSzASzg6bBy9gqCofvWN8okThAYIxKJZC+udlRAmGbM0XLeniEJSs8uEgHPGuHSe1XsOLSQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/is-generator-function": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/is-generator-function/-/is-generator-function-1.1.2.tgz",
@@ -23247,7 +24000,7 @@
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-2.0.1.tgz",
       "integrity": "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -23417,7 +24170,7 @@
       "version": "3.2.2",
       "resolved": "https://registry.npmjs.org/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz",
       "integrity": "sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==",
-      "dev": true,
+      "devOptional": true,
       "license": "BSD-3-Clause",
       "engines": {
         "node": ">=8"
@@ -23427,7 +24180,7 @@
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/istanbul-lib-instrument/-/istanbul-lib-instrument-5.2.1.tgz",
       "integrity": "sha512-pzqtp31nLv/XFOzXGuvhCb8qhjmTVo5vjVk19XE4CRlSWz0KoeJ3bw9XsA7nOp9YBf4qHjwBxkDzKcME/J29Yg==",
-      "dev": true,
+      "devOptional": true,
       "license": "BSD-3-Clause",
       "dependencies": {
         "@babel/core": "^7.12.3",
@@ -23444,12 +24197,101 @@
       "version": "6.3.1",
       "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
       "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
-      "dev": true,
+      "devOptional": true,
       "license": "ISC",
       "bin": {
         "semver": "bin/semver.js"
       }
     },
+    "node_modules/istanbul-lib-report": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz",
+      "integrity": "sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==",
+      "devOptional": true,
+      "license": "BSD-3-Clause",
+      "peer": true,
+      "dependencies": {
+        "istanbul-lib-coverage": "^3.0.0",
+        "make-dir": "^4.0.0",
+        "supports-color": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/istanbul-lib-report/node_modules/make-dir": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-4.0.0.tgz",
+      "integrity": "sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "semver": "^7.5.3"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/istanbul-lib-report/node_modules/supports-color": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
+      "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "has-flag": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/istanbul-lib-source-maps": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/istanbul-lib-source-maps/-/istanbul-lib-source-maps-4.0.1.tgz",
+      "integrity": "sha512-n3s8EwkdFIJCG3BPKBYvskgXGoy88ARzvegkitk60NxRdwltLOTaH7CUiMRXvwYorl0Q712iEjcWB+fK/MrWVw==",
+      "devOptional": true,
+      "license": "BSD-3-Clause",
+      "peer": true,
+      "dependencies": {
+        "debug": "^4.1.1",
+        "istanbul-lib-coverage": "^3.0.0",
+        "source-map": "^0.6.1"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/istanbul-lib-source-maps/node_modules/source-map": {
+      "version": "0.6.1",
+      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
+      "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
+      "devOptional": true,
+      "license": "BSD-3-Clause",
+      "peer": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/istanbul-reports": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/istanbul-reports/-/istanbul-reports-3.2.0.tgz",
+      "integrity": "sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==",
+      "devOptional": true,
+      "license": "BSD-3-Clause",
+      "peer": true,
+      "dependencies": {
+        "html-escaper": "^2.0.0",
+        "istanbul-lib-report": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/iterator.prototype": {
       "version": "1.1.5",
       "resolved": "https://registry.npmjs.org/iterator.prototype/-/iterator.prototype-1.1.5.tgz",
@@ -23502,11 +24344,273 @@
         "node": ">=10"
       }
     },
+    "node_modules/jest": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest/-/jest-29.7.0.tgz",
+      "integrity": "sha512-NIy3oAFp9shda19hy4HK0HRTWKtPJmGdnvywu01nOqNC2vZg+Z+fvJDxpMQA88eb2I9EcafcdjYgsDthnYTvGw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@jest/core": "^29.7.0",
+        "@jest/types": "^29.6.3",
+        "import-local": "^3.0.2",
+        "jest-cli": "^29.7.0"
+      },
+      "bin": {
+        "jest": "bin/jest.js"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      },
+      "peerDependencies": {
+        "node-notifier": "^8.0.1 || ^9.0.0 || ^10.0.0"
+      },
+      "peerDependenciesMeta": {
+        "node-notifier": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/jest-changed-files": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-changed-files/-/jest-changed-files-29.7.0.tgz",
+      "integrity": "sha512-fEArFiwf1BpQ+4bXSprcDc3/x4HSzL4al2tozwVpDFpsxALjLYdyiIK4e5Vz66GQJIbXJ82+35PtysofptNX2w==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "execa": "^5.0.0",
+        "jest-util": "^29.7.0",
+        "p-limit": "^3.1.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/jest-circus": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-circus/-/jest-circus-29.7.0.tgz",
+      "integrity": "sha512-3E1nCMgipcTkCocFwM90XXQab9bS+GMsjdpmPrlelaxwD93Ad8iVEjX/vvHPdLPnFf+L40u+5+iutRdA1N9myw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@jest/environment": "^29.7.0",
+        "@jest/expect": "^29.7.0",
+        "@jest/test-result": "^29.7.0",
+        "@jest/types": "^29.6.3",
+        "@types/node": "*",
+        "chalk": "^4.0.0",
+        "co": "^4.6.0",
+        "dedent": "^1.0.0",
+        "is-generator-fn": "^2.0.0",
+        "jest-each": "^29.7.0",
+        "jest-matcher-utils": "^29.7.0",
+        "jest-message-util": "^29.7.0",
+        "jest-runtime": "^29.7.0",
+        "jest-snapshot": "^29.7.0",
+        "jest-util": "^29.7.0",
+        "p-limit": "^3.1.0",
+        "pretty-format": "^29.7.0",
+        "pure-rand": "^6.0.0",
+        "slash": "^3.0.0",
+        "stack-utils": "^2.0.3"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/jest-circus/node_modules/pure-rand": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-6.1.0.tgz",
+      "integrity": "sha512-bVWawvoZoBYpp6yIoQtQXHZjmz35RSVHnUOTefl8Vcjr8snTPY1wnpSPMWekcFwbxI6gtmT7rSYPFvz71ldiOA==",
+      "devOptional": true,
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://github.com/sponsors/dubzzz"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fast-check"
+        }
+      ],
+      "license": "MIT",
+      "peer": true
+    },
+    "node_modules/jest-circus/node_modules/slash": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
+      "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/jest-cli": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-cli/-/jest-cli-29.7.0.tgz",
+      "integrity": "sha512-OVVobw2IubN/GSYsxETi+gOe7Ka59EFMR/twOU3Jb2GnKKeMGJB5SGUUrEz3SFVmJASUdZUzy83sLNNQ2gZslg==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@jest/core": "^29.7.0",
+        "@jest/test-result": "^29.7.0",
+        "@jest/types": "^29.6.3",
+        "chalk": "^4.0.0",
+        "create-jest": "^29.7.0",
+        "exit": "^0.1.2",
+        "import-local": "^3.0.2",
+        "jest-config": "^29.7.0",
+        "jest-util": "^29.7.0",
+        "jest-validate": "^29.7.0",
+        "yargs": "^17.3.1"
+      },
+      "bin": {
+        "jest": "bin/jest.js"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      },
+      "peerDependencies": {
+        "node-notifier": "^8.0.1 || ^9.0.0 || ^10.0.0"
+      },
+      "peerDependenciesMeta": {
+        "node-notifier": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/jest-config": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-config/-/jest-config-29.7.0.tgz",
+      "integrity": "sha512-uXbpfeQ7R6TZBqI3/TxCU4q4ttk3u0PJeC+E0zbfSoSjq6bJ7buBPxzQPL0ifrkY4DNu4JUdk0ImlBUYi840eQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@babel/core": "^7.11.6",
+        "@jest/test-sequencer": "^29.7.0",
+        "@jest/types": "^29.6.3",
+        "babel-jest": "^29.7.0",
+        "chalk": "^4.0.0",
+        "ci-info": "^3.2.0",
+        "deepmerge": "^4.2.2",
+        "glob": "^7.1.3",
+        "graceful-fs": "^4.2.9",
+        "jest-circus": "^29.7.0",
+        "jest-environment-node": "^29.7.0",
+        "jest-get-type": "^29.6.3",
+        "jest-regex-util": "^29.6.3",
+        "jest-resolve": "^29.7.0",
+        "jest-runner": "^29.7.0",
+        "jest-util": "^29.7.0",
+        "jest-validate": "^29.7.0",
+        "micromatch": "^4.0.4",
+        "parse-json": "^5.2.0",
+        "pretty-format": "^29.7.0",
+        "slash": "^3.0.0",
+        "strip-json-comments": "^3.1.1"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      },
+      "peerDependencies": {
+        "@types/node": "*",
+        "ts-node": ">=9.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "ts-node": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/jest-config/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==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "node_modules/jest-config/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",
+      "devOptional": 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/jest-config/node_modules/minimatch": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "devOptional": true,
+      "license": "ISC",
+      "peer": true,
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/jest-config/node_modules/slash": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
+      "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/jest-config/node_modules/strip-json-comments": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz",
+      "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/jest-diff": {
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/jest-diff/-/jest-diff-29.7.0.tgz",
       "integrity": "sha512-LMIgiIrhigmPrs03JHpxUh2yISK3vLFPkAodPeo0+BuF7wA2FoQbkEg1u8gBYBThncu7e1oEDUfIXVuTqLRUjw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "chalk": "^4.0.0",
@@ -23518,6 +24622,38 @@
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
+    "node_modules/jest-docblock": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-docblock/-/jest-docblock-29.7.0.tgz",
+      "integrity": "sha512-q617Auw3A612guyaFgsbFeYpNP5t2aoUNLwBUbc/0kD1R4t9ixDbyFTHd1nok4epoVFpr7PmeWHrhvuV3XaJ4g==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "detect-newline": "^3.0.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/jest-each": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-each/-/jest-each-29.7.0.tgz",
+      "integrity": "sha512-gns+Er14+ZrEoC5fhOfYCY1LOHHr0TI+rQUHZS8Ttw2l7gl+80eHc/gFf2Ktkw0+SIACDTeWvpFcv3B04VembQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@jest/types": "^29.6.3",
+        "chalk": "^4.0.0",
+        "jest-get-type": "^29.6.3",
+        "jest-util": "^29.7.0",
+        "pretty-format": "^29.7.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
     "node_modules/jest-environment-jsdom": {
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/jest-environment-jsdom/-/jest-environment-jsdom-29.7.0.tgz",
@@ -23546,6 +24682,358 @@
         }
       }
     },
+    "node_modules/jest-environment-node": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-environment-node/-/jest-environment-node-29.7.0.tgz",
+      "integrity": "sha512-DOSwCRqXirTOyheM+4d5YZOrWcdu0LNZ87ewUoywbcb2XR4wKgqiG8vNeYwhjFMbEkfju7wx2GYH0P2gevGvFw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@jest/environment": "^29.7.0",
+        "@jest/fake-timers": "^29.7.0",
+        "@jest/types": "^29.6.3",
+        "@types/node": "*",
+        "jest-mock": "^29.7.0",
+        "jest-util": "^29.7.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/jest-expo": {
+      "version": "54.0.18",
+      "resolved": "https://registry.npmjs.org/jest-expo/-/jest-expo-54.0.18.tgz",
+      "integrity": "sha512-couPPatkifK3v0WZW7zu1HZW5HyxY+1cY69LKHPawwbZTuIvf5wk4SYHtoUrGa/nAM2jW/YiXDLWfociEHJPvw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@expo/config": "~12.0.14",
+        "@expo/json-file": "^10.0.16",
+        "@jest/create-cache-key-function": "^29.2.1",
+        "@jest/globals": "^29.2.1",
+        "babel-jest": "^29.2.1",
+        "jest-environment-jsdom": "^29.2.1",
+        "jest-snapshot": "^29.2.1",
+        "jest-watch-select-projects": "^2.0.0",
+        "jest-watch-typeahead": "2.2.1",
+        "json5": "^2.2.3",
+        "lodash": "^4.17.19",
+        "react-test-renderer": "19.1.0",
+        "server-only": "^0.0.1",
+        "stacktrace-js": "^2.0.2"
+      },
+      "bin": {
+        "jest": "bin/jest.js"
+      },
+      "peerDependencies": {
+        "expo": "*",
+        "react-native": "*",
+        "react-server-dom-webpack": "~19.0.4 || ~19.1.5 || ~19.2.4"
+      },
+      "peerDependenciesMeta": {
+        "react-server-dom-webpack": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/jest-expo/node_modules/@expo/config": {
+      "version": "12.0.14",
+      "resolved": "https://registry.npmjs.org/@expo/config/-/config-12.0.14.tgz",
+      "integrity": "sha512-3dfbBd9LnPDgyylhCgkOsaG8Adg52uOVOTQYH5lf23a/t8M5eQpXKCvzUarrf62B78057n2NnkiofK9TfPgvzw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "~7.10.4",
+        "@expo/config-plugins": "~54.0.5",
+        "@expo/config-types": "^54.0.10",
+        "@expo/json-file": "^10.0.16",
+        "deepmerge": "^4.3.1",
+        "getenv": "^2.0.0",
+        "glob": "^13.0.0",
+        "require-from-string": "^2.0.2",
+        "resolve-from": "^5.0.0",
+        "resolve-workspace-root": "^2.0.0",
+        "semver": "^7.6.0",
+        "slugify": "^1.3.4",
+        "sucrase": "~3.35.1"
+      }
+    },
+    "node_modules/jest-expo/node_modules/@expo/config-plugins": {
+      "version": "54.0.6",
+      "resolved": "https://registry.npmjs.org/@expo/config-plugins/-/config-plugins-54.0.6.tgz",
+      "integrity": "sha512-RKKhe3HSCTEmU2PBl4lu0BtV68TOz7qjPRXQBkBOUeYe83vIno1N63viDOiHIf7wxZ1ALxvsyEu3QWlCICnfWw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@expo/config-types": "^54.0.10",
+        "@expo/json-file": "~10.0.16",
+        "@expo/plist": "^0.4.9",
+        "@expo/sdk-runtime-versions": "^1.0.0",
+        "chalk": "^4.1.2",
+        "debug": "^4.3.5",
+        "getenv": "^2.0.0",
+        "glob": "^13.0.0",
+        "resolve-from": "^5.0.0",
+        "semver": "^7.5.4",
+        "slash": "^3.0.0",
+        "slugify": "^1.6.6",
+        "xcode": "^4.0.0",
+        "xml2js": "0.6.0"
+      }
+    },
+    "node_modules/jest-expo/node_modules/@expo/config-plugins/node_modules/@babel/code-frame": {
+      "version": "7.10.4",
+      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.10.4.tgz",
+      "integrity": "sha512-vG6SvB6oYEhvgisZNFRmRCUkLz11c7rp+tbNTynGqc6mS1d5ATd/sGyV6W0KZZnXRKMTzZDRgQT3Ou9jhpAfUg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/highlight": "^7.10.4"
+      }
+    },
+    "node_modules/jest-expo/node_modules/@expo/config-plugins/node_modules/@expo/json-file": {
+      "version": "10.0.16",
+      "resolved": "https://registry.npmjs.org/@expo/json-file/-/json-file-10.0.16.tgz",
+      "integrity": "sha512-fcVkWEj+hLuP2yt5W0aw6LmDRqSPWDLUSxOMcmFeV+algmIF59sQVKCwB9btjQLd4V6x9N0pISkQEkBubUHrCw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "~7.10.4",
+        "json5": "^2.2.3"
+      }
+    },
+    "node_modules/jest-expo/node_modules/@expo/config-types": {
+      "version": "54.0.10",
+      "resolved": "https://registry.npmjs.org/@expo/config-types/-/config-types-54.0.10.tgz",
+      "integrity": "sha512-/J16SC2an1LdtCZ67xhSkGXpALYUVUNyZws7v+PVsFZxClYehDSoKLqyRaGkpHlYrCc08bS0RF5E0JV6g50psA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/jest-expo/node_modules/@expo/config/node_modules/@babel/code-frame": {
+      "version": "7.10.4",
+      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.10.4.tgz",
+      "integrity": "sha512-vG6SvB6oYEhvgisZNFRmRCUkLz11c7rp+tbNTynGqc6mS1d5ATd/sGyV6W0KZZnXRKMTzZDRgQT3Ou9jhpAfUg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/highlight": "^7.10.4"
+      }
+    },
+    "node_modules/jest-expo/node_modules/@expo/json-file": {
+      "version": "10.2.0",
+      "resolved": "https://registry.npmjs.org/@expo/json-file/-/json-file-10.2.0.tgz",
+      "integrity": "sha512-S6XzKe3R9GQeHiUPXc3xJjOv2VJhOEwFYf7xdC2z2cUqt3kZJ9mSO877sNQloVdnW/SUCtPY3bexlM7nwq+CAQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.20.0",
+        "json5": "^2.2.3"
+      }
+    },
+    "node_modules/jest-expo/node_modules/@expo/plist": {
+      "version": "0.4.9",
+      "resolved": "https://registry.npmjs.org/@expo/plist/-/plist-0.4.9.tgz",
+      "integrity": "sha512-MPVpmKGfnQEnrCzgxuXcmPP/y/t6AVm+DcSb2Myp21LKWv1N3l8uFxMggesfF4ixAxkRlGmMMx9GyDC9M+XklQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@xmldom/xmldom": "^0.8.8",
+        "base64-js": "^1.2.3",
+        "xmlbuilder": "^15.1.1"
+      }
+    },
+    "node_modules/jest-expo/node_modules/@xmldom/xmldom": {
+      "version": "0.8.15",
+      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.8.15.tgz",
+      "integrity": "sha512-/5NV/vDALVFDXgLmfsy9TRCBlKwO2LNBFzpzvb9iIj+jR+eSc6DLYYvVOdivT/jm7MtU6TebYuRmzEOI7w40UA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
+    "node_modules/jest-expo/node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "node_modules/jest-expo/node_modules/brace-expansion": {
+      "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": "20 || >=22"
+      }
+    },
+    "node_modules/jest-expo/node_modules/commander": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-4.1.1.tgz",
+      "integrity": "sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/jest-expo/node_modules/getenv": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/getenv/-/getenv-2.0.0.tgz",
+      "integrity": "sha512-VilgtJj/ALgGY77fiLam5iD336eSWi96Q15JSAG1zi8NRBysm3LXKdGnHb4m5cuyxvOLQQKWpBZAT6ni4FI2iQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/jest-expo/node_modules/glob": {
+      "version": "13.0.6",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz",
+      "integrity": "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "minimatch": "^10.2.2",
+        "minipass": "^7.1.3",
+        "path-scurry": "^2.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/jest-expo/node_modules/lru-cache": {
+      "version": "11.5.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.3.tgz",
+      "integrity": "sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
+    "node_modules/jest-expo/node_modules/minimatch": {
+      "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.8"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/jest-expo/node_modules/path-scurry": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz",
+      "integrity": "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "lru-cache": "^11.0.0",
+        "minipass": "^7.1.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/jest-expo/node_modules/react-test-renderer": {
+      "version": "19.1.0",
+      "resolved": "https://registry.npmjs.org/react-test-renderer/-/react-test-renderer-19.1.0.tgz",
+      "integrity": "sha512-jXkSl3CpvPYEF+p/eGDLB4sPoDX8pKkYvRl9+rR8HxLY0X04vW7hCm1/0zHoUSjPZ3bDa+wXWNTDVIw/R8aDVw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "react-is": "^19.1.0",
+        "scheduler": "^0.26.0"
+      },
+      "peerDependencies": {
+        "react": "^19.1.0"
+      }
+    },
+    "node_modules/jest-expo/node_modules/scheduler": {
+      "version": "0.26.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.26.0.tgz",
+      "integrity": "sha512-NlHwttCI/l5gCPR3D1nNXtWABUmBwvZpEQiD4IXSbIDq8BzLIK/7Ir5gTFSGZDUu37K5cMNp0hFtzO38sC7gWA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/jest-expo/node_modules/slash": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
+      "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/jest-expo/node_modules/sucrase": {
+      "version": "3.35.1",
+      "resolved": "https://registry.npmjs.org/sucrase/-/sucrase-3.35.1.tgz",
+      "integrity": "sha512-DhuTmvZWux4H1UOnWMB3sk0sbaCVOoQZjv8u1rDoTV0HTdGem9hkAZtl4JZy8P2z4Bg0nT+YMeOFyVr4zcG5Tw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/gen-mapping": "^0.3.2",
+        "commander": "^4.0.0",
+        "lines-and-columns": "^1.1.6",
+        "mz": "^2.7.0",
+        "pirates": "^4.0.1",
+        "tinyglobby": "^0.2.11",
+        "ts-interface-checker": "^0.1.9"
+      },
+      "bin": {
+        "sucrase": "bin/sucrase",
+        "sucrase-node": "bin/sucrase-node"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      }
+    },
+    "node_modules/jest-expo/node_modules/xcode": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/xcode/-/xcode-4.0.0.tgz",
+      "integrity": "sha512-dDaoWzc9EP2fp9FS9PVZUkyvFxY4y1TOV9pcKaKLk++Ei/qb97XDFEVP7GnW7Osii/TzVABJ0jq2F+9/lq0TVA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "simple-plist": "^1.3.1"
+      },
+      "engines": {
+        "node": ">=14.17.0"
+      }
+    },
+    "node_modules/jest-expo/node_modules/xmlbuilder": {
+      "version": "15.1.1",
+      "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-15.1.1.tgz",
+      "integrity": "sha512-yMqGBqtXyeN1e3TGYvgNgDVZ3j84W4cwkOXQswghol6APgZWaff9lnbvN7MHYJOiXsvGPXtjTYJEiC9J2wv9Eg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.0"
+      }
+    },
     "node_modules/jest-get-type": {
       "version": "29.6.3",
       "resolved": "https://registry.npmjs.org/jest-get-type/-/jest-get-type-29.6.3.tgz",
@@ -23559,7 +25047,7 @@
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/jest-haste-map/-/jest-haste-map-29.7.0.tgz",
       "integrity": "sha512-fP8u2pyfqx0K1rGn1R9pyE0/KTn+G7PxktWidOBTqFPLYX0b9ksaMFkhK5vrS3DVun09pckLdlx90QthlW7AmA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@jest/types": "^29.6.3",
@@ -23581,11 +25069,26 @@
         "fsevents": "^2.3.2"
       }
     },
+    "node_modules/jest-leak-detector": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-leak-detector/-/jest-leak-detector-29.7.0.tgz",
+      "integrity": "sha512-kYA8IJcSYtST2BY9I+SMC32nDpBT3J2NvWJx8+JCuCdl/CR1I4EKUJROiP8XtCcxqgTTBGJNdbB1A8XRKbTetw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "jest-get-type": "^29.6.3",
+        "pretty-format": "^29.7.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
     "node_modules/jest-matcher-utils": {
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/jest-matcher-utils/-/jest-matcher-utils-29.7.0.tgz",
       "integrity": "sha512-sBkD+Xi9DtcChsI3L3u0+N0opgPYnCRPtGcQYrgXmR+hmt/fYfWAL0xRXYU8eWOdfuLgBe0YCW3AFtnRLagq/g==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "chalk": "^4.0.0",
@@ -23601,7 +25104,7 @@
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/jest-message-util/-/jest-message-util-29.7.0.tgz",
       "integrity": "sha512-GBEV4GRADeP+qtB2+6u61stea8mGcOT4mCtrYISZwfu9/ISHFJ/5zOMXYbpBE9RsS5+Gb63DW4FgmnKJ79Kf6w==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/code-frame": "^7.12.13",
@@ -23622,7 +25125,7 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
       "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -23632,7 +25135,7 @@
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/jest-mock/-/jest-mock-29.7.0.tgz",
       "integrity": "sha512-ITOMZn+UkYS4ZFh83xYAOzWStloNzJFO2s8DWrE4lhtGD+AorgnbkiKERe4wQVBydIGPx059g6riW5Btp6Llnw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@jest/types": "^29.6.3",
@@ -23643,21 +25146,251 @@
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
+    "node_modules/jest-pnp-resolver": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/jest-pnp-resolver/-/jest-pnp-resolver-1.2.3.tgz",
+      "integrity": "sha512-+3NpwQEnRoIBtx4fyhblQDPgJI0H1IEIkX7ShLUjPGA7TtUTvI1oiKi3SR4oBR0hQhQR80l4WAe5RrXBwWMA8w==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=6"
+      },
+      "peerDependencies": {
+        "jest-resolve": "*"
+      },
+      "peerDependenciesMeta": {
+        "jest-resolve": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/jest-regex-util": {
       "version": "29.6.3",
       "resolved": "https://registry.npmjs.org/jest-regex-util/-/jest-regex-util-29.6.3.tgz",
       "integrity": "sha512-KJJBsRCyyLNWCNBOvZyRDnAIfUiRJ8v+hOBQYGn8gDyF3UegwiP4gwRR3/SDa42g1YbVycTidUF3rKjyLFDWbg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
+    "node_modules/jest-resolve": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-resolve/-/jest-resolve-29.7.0.tgz",
+      "integrity": "sha512-IOVhZSrg+UvVAshDSDtHyFCCBUl/Q3AAJv8iZ6ZjnZ74xzvwuzLXid9IIIPgTnY62SJjfuupMKZsZQRsCvxEgA==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "chalk": "^4.0.0",
+        "graceful-fs": "^4.2.9",
+        "jest-haste-map": "^29.7.0",
+        "jest-pnp-resolver": "^1.2.2",
+        "jest-util": "^29.7.0",
+        "jest-validate": "^29.7.0",
+        "resolve": "^1.20.0",
+        "resolve.exports": "^2.0.0",
+        "slash": "^3.0.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/jest-resolve-dependencies": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-resolve-dependencies/-/jest-resolve-dependencies-29.7.0.tgz",
+      "integrity": "sha512-un0zD/6qxJ+S0et7WxeI3H5XSe9lTBBR7bOHCHXkKR6luG5mwDDlIzVQ0V5cZCuoTgEdcdwzTghYkTWfubi+nA==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "jest-regex-util": "^29.6.3",
+        "jest-snapshot": "^29.7.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/jest-resolve/node_modules/slash": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
+      "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/jest-runner": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-runner/-/jest-runner-29.7.0.tgz",
+      "integrity": "sha512-fsc4N6cPCAahybGBfTRcq5wFR6fpLznMg47sY5aDpsoejOcVYFb07AHuSnR0liMcPTgBsA3ZJL6kFOjPdoNipQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@jest/console": "^29.7.0",
+        "@jest/environment": "^29.7.0",
+        "@jest/test-result": "^29.7.0",
+        "@jest/transform": "^29.7.0",
+        "@jest/types": "^29.6.3",
+        "@types/node": "*",
+        "chalk": "^4.0.0",
+        "emittery": "^0.13.1",
+        "graceful-fs": "^4.2.9",
+        "jest-docblock": "^29.7.0",
+        "jest-environment-node": "^29.7.0",
+        "jest-haste-map": "^29.7.0",
+        "jest-leak-detector": "^29.7.0",
+        "jest-message-util": "^29.7.0",
+        "jest-resolve": "^29.7.0",
+        "jest-runtime": "^29.7.0",
+        "jest-util": "^29.7.0",
+        "jest-watcher": "^29.7.0",
+        "jest-worker": "^29.7.0",
+        "p-limit": "^3.1.0",
+        "source-map-support": "0.5.13"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/jest-runner/node_modules/source-map": {
+      "version": "0.6.1",
+      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
+      "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
+      "devOptional": true,
+      "license": "BSD-3-Clause",
+      "peer": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/jest-runner/node_modules/source-map-support": {
+      "version": "0.5.13",
+      "resolved": "https://registry.npmjs.org/source-map-support/-/source-map-support-0.5.13.tgz",
+      "integrity": "sha512-SHSKFHadjVA5oR4PPqhtAVdcBWwRYVd6g6cAXnIbRiIwc2EhPrTuKUBdSLvlEKyIP3GCf89fltvcZiP9MMFA1w==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "buffer-from": "^1.0.0",
+        "source-map": "^0.6.0"
+      }
+    },
+    "node_modules/jest-runtime": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/jest-runtime/-/jest-runtime-29.7.0.tgz",
+      "integrity": "sha512-gUnLjgwdGqW7B4LvOIkbKs9WGbn+QLqRQQ9juC6HndeDiezIwhDP+mhMwHWCEcfQ5RUXa6OPnFF8BJh5xegwwQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@jest/environment": "^29.7.0",
+        "@jest/fake-timers": "^29.7.0",
+        "@jest/globals": "^29.7.0",
+        "@jest/source-map": "^29.6.3",
+        "@jest/test-result": "^29.7.0",
+        "@jest/transform": "^29.7.0",
+        "@jest/types": "^29.6.3",
+        "@types/node": "*",
+        "chalk": "^4.0.0",
+        "cjs-module-lexer": "^1.0.0",
+        "collect-v8-coverage": "^1.0.0",
+        "glob": "^7.1.3",
+        "graceful-fs": "^4.2.9",
+        "jest-haste-map": "^29.7.0",
+        "jest-message-util": "^29.7.0",
+        "jest-mock": "^29.7.0",
+        "jest-regex-util": "^29.6.3",
+        "jest-resolve": "^29.7.0",
+        "jest-snapshot": "^29.7.0",
+        "jest-util": "^29.7.0",
+        "slash": "^3.0.0",
+        "strip-bom": "^4.0.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/jest-runtime/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==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "node_modules/jest-runtime/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",
+      "devOptional": 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/jest-runtime/node_modules/minimatch": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "devOptional": true,
+      "license": "ISC",
+      "peer": true,
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/jest-runtime/node_modules/slash": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
+      "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/jest-runtime/node_modules/strip-bom": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/strip-bom/-/strip-bom-4.0.0.tgz",
+      "integrity": "sha512-3xurFv5tEgii33Zi8Jtp55wEIILR9eh34FAW00PZf+JnSsTmV/ioewSgQl97JHvgjoRGwPShsWm+IdrxB35d0w==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/jest-snapshot": {
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/jest-snapshot/-/jest-snapshot-29.7.0.tgz",
       "integrity": "sha512-Rm0BMWtxBcioHr1/OX5YCP8Uov4riHvKPknOGs804Zg9JGZgmIBkbtlxJC/7Z4msKYVbIJtfU+tKb8xlYNfdkw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/core": "^7.11.6",
@@ -23868,7 +25601,7 @@
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/jest-watcher/-/jest-watcher-29.7.0.tgz",
       "integrity": "sha512-49Fg7WXkU3Vl2h6LbLtMQ/HyB6rXSIX7SqvBLQmssRBGN9I0PNvPmAmCWSOY6SOvrjhI/F7/bGAv9RtnsPA03g==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@jest/test-result": "^29.7.0",
@@ -23888,7 +25621,7 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/char-regex/-/char-regex-1.0.2.tgz",
       "integrity": "sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=10"
@@ -23898,7 +25631,7 @@
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/string-length/-/string-length-4.0.2.tgz",
       "integrity": "sha512-+l6rNN5fYHNhZZy41RXsYptCjA2Igmq4EG7kZAYFQI1E1VTXarr6ZPXBg6eq7Y6eK4FEhY6AJlyuFIb/v/S0VQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "char-regex": "^1.0.2",
@@ -24172,7 +25905,7 @@
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz",
       "integrity": "sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/json-schema": {
@@ -24967,7 +26700,7 @@
       "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz",
       "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/linkify-it": {
@@ -25182,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",
@@ -27300,7 +28990,7 @@
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-2.1.0.tgz",
       "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=6"
@@ -27332,7 +29022,7 @@
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/min-indent/-/min-indent-1.0.1.tgz",
       "integrity": "sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=4"
@@ -27425,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",
@@ -27823,7 +29404,7 @@
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/natural-compare/-/natural-compare-1.4.0.tgz",
       "integrity": "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/natural-orderby": {
@@ -27857,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": {
@@ -27945,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": {
@@ -27996,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",
@@ -28007,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": {
@@ -28029,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": {
@@ -28056,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": {
@@ -28154,7 +29771,7 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz",
       "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=0.10.0"
@@ -28173,31 +29790,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/noxcturnal": {
-      "version": "0.1.5",
-      "resolved": "https://registry.npmjs.org/noxcturnal/-/noxcturnal-0.1.5.tgz",
-      "integrity": "sha512-X/HQXJP/xn7LVQ4z1E4La0NHSl5UHdtJPG6ky4r2/Xgb7k79nGDJgBXk7I5f1V2vInWjlSCM14oSB0cUxwZS/Q==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "@oxc-project/types": "0.154.0"
-      },
-      "engines": {
-        "node": ">=18"
-      },
-      "optionalDependencies": {
-        "@noxcturnal/noxcturnal-darwin-arm64": "0.1.5",
-        "@noxcturnal/noxcturnal-darwin-x64": "0.1.5",
-        "@noxcturnal/noxcturnal-linux-arm64-gnu": "0.1.5",
-        "@noxcturnal/noxcturnal-linux-arm64-musl": "0.1.5",
-        "@noxcturnal/noxcturnal-linux-x64-gnu": "0.1.5",
-        "@noxcturnal/noxcturnal-linux-x64-musl": "0.1.5",
-        "@noxcturnal/noxcturnal-win32-arm64-msvc": "0.1.5",
-        "@noxcturnal/noxcturnal-win32-x64-msvc": "0.1.5"
-      }
-    },
     "node_modules/npm-package-arg": {
       "version": "11.0.3",
       "resolved": "https://registry.npmjs.org/npm-package-arg/-/npm-package-arg-11.0.3.tgz",
@@ -28231,6 +29823,20 @@
       "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
       "license": "ISC"
     },
+    "node_modules/npm-run-path": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-4.0.1.tgz",
+      "integrity": "sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "path-key": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/nth-check": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz",
@@ -28453,7 +30059,7 @@
       "version": "5.1.2",
       "resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz",
       "integrity": "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "mimic-fn": "^2.1.0"
@@ -28728,7 +30334,7 @@
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz",
       "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "yocto-queue": "^0.1.0"
@@ -28756,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",
@@ -28880,7 +30473,7 @@
       "version": "5.2.0",
       "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-5.2.0.tgz",
       "integrity": "sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@babel/code-frame": "^7.0.0",
@@ -29015,7 +30608,7 @@
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
       "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=0.10.0"
@@ -29190,7 +30783,7 @@
       "version": "4.0.7",
       "resolved": "https://registry.npmjs.org/pirates/-/pirates-4.0.7.tgz",
       "integrity": "sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">= 6"
@@ -29209,7 +30802,7 @@
       "version": "4.2.0",
       "resolved": "https://registry.npmjs.org/pkg-dir/-/pkg-dir-4.2.0.tgz",
       "integrity": "sha512-HRDzbaKjC+AOWVXxAU/x54COGeIv9eb+6CkDSQoNTt4XyWoIJvuPsXizxu/Fr23EiekbtZwmh1IcIG/l/a10GQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "find-up": "^4.0.0"
@@ -29222,7 +30815,7 @@
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz",
       "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "locate-path": "^5.0.0",
@@ -29236,7 +30829,7 @@
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz",
       "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "p-locate": "^4.1.0"
@@ -29249,7 +30842,7 @@
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz",
       "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "p-try": "^2.0.0"
@@ -29265,7 +30858,7 @@
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz",
       "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "p-limit": "^2.2.0"
@@ -29274,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",
@@ -29423,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",
@@ -29694,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",
@@ -30085,25 +31762,9 @@
       }
     },
     "node_modules/react-is": {
-      "version": "19.2.4",
-      "resolved": "https://registry.npmjs.org/react-is/-/react-is-19.2.4.tgz",
-      "integrity": "sha512-W+EWGn2v0ApPKgKKCy/7s7WHXkboGcsrXE+2joLyVxkbyVQfO3MUEaUQDHoSmb8TFFrSKYa9mw64WZHNHSDzYA==",
-      "license": "MIT"
-    },
-    "node_modules/react-is-18": {
-      "name": "react-is",
-      "version": "18.3.1",
-      "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz",
-      "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==",
-      "dev": true,
-      "license": "MIT"
-    },
-    "node_modules/react-is-19": {
-      "name": "react-is",
-      "version": "19.2.7",
-      "resolved": "https://registry.npmjs.org/react-is/-/react-is-19.2.7.tgz",
-      "integrity": "sha512-kZFnouyVv7eP/Phmrlo9FK+zcAdriZJvzxXHF1Sl1P377WSGe2G/JxVolhTrB/jeV47lKImhNUsijjHAAbcl/A==",
-      "dev": true,
+      "version": "19.3.1",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-19.3.1.tgz",
+      "integrity": "sha512-RRieF6IyxQBkcK6pP8xOHprLTPW6QjRkbGdImtqNme+/hYVwCZkLQLdlZGOhUqXwkS9IEynaGvPJtv6XB/cz0Q==",
       "license": "MIT"
     },
     "node_modules/react-markdown": {
@@ -30651,6 +32312,21 @@
         }
       }
     },
+    "node_modules/react-test-renderer": {
+      "version": "19.3.1",
+      "resolved": "https://registry.npmjs.org/react-test-renderer/-/react-test-renderer-19.3.1.tgz",
+      "integrity": "sha512-YcNewwmnZMd0wTb2nkb4hQ58NmX/u1hW2OJsNpen8CnV+jNkmEjYd1R6wJrOMSgb8bIF5HAJv4iL+S3PwNptOA==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "react-is": "^19.3.1",
+        "scheduler": "^0.28.0"
+      },
+      "peerDependencies": {
+        "react": "^19.3.1"
+      }
+    },
     "node_modules/read-binary-file-arch": {
       "version": "1.0.6",
       "resolved": "https://registry.npmjs.org/read-binary-file-arch/-/read-binary-file-arch-1.0.6.tgz",
@@ -31181,6 +32857,20 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/resolve-cwd": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/resolve-cwd/-/resolve-cwd-3.0.0.tgz",
+      "integrity": "sha512-OrZaX2Mb+rJCpH/6CpSqt9xFVpN++x01XnN2ie9g6P5/3xelLAkXWVADpdz1IHD/KFfEXyE6V0U01OQ3UO2rEg==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "resolve-from": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/resolve-from": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz",
@@ -31206,6 +32896,17 @@
       "integrity": "sha512-nR23LHAvaI6aHtMg6RWoaHpdR4D881Nydkzi2CixINyg9T00KgaJdJI6Vwty+Ps8WLxZHuxsS0BseWjxSA4C+w==",
       "license": "MIT"
     },
+    "node_modules/resolve.exports": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/resolve.exports/-/resolve.exports-2.0.4.tgz",
+      "integrity": "sha512-zepuGL0ulf+nt+XaFrlKeaiTJeyPFPLLY62+ncq1/VTHBdt3HsfXOH60priZ6tnXQozdGcDeIF5JVTanvIcYWQ==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/responselike": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/responselike/-/responselike-2.0.1.tgz",
@@ -31261,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",
@@ -31551,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": {
@@ -31583,11 +33348,12 @@
       }
     },
     "node_modules/scheduler": {
-      "version": "0.26.0",
-      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.26.0.tgz",
-      "integrity": "sha512-NlHwttCI/l5gCPR3D1nNXtWABUmBwvZpEQiD4IXSbIDq8BzLIK/7Ir5gTFSGZDUu37K5cMNp0hFtzO38sC7gWA==",
-      "dev": true,
-      "license": "MIT"
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.28.0.tgz",
+      "integrity": "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/secure-json-parse": {
       "version": "4.1.0",
@@ -32224,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",
@@ -32248,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",
@@ -32416,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",
@@ -32450,7 +34152,7 @@
       "version": "2.0.6",
       "resolved": "https://registry.npmjs.org/stack-utils/-/stack-utils-2.0.6.tgz",
       "integrity": "sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "escape-string-regexp": "^2.0.0"
@@ -32463,7 +34165,7 @@
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz",
       "integrity": "sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -32863,6 +34565,17 @@
         "node": ">=4"
       }
     },
+    "node_modules/strip-final-newline": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-2.0.0.tgz",
+      "integrity": "sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==",
+      "devOptional": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/strip-indent": {
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-4.1.1.tgz",
@@ -33047,13 +34760,14 @@
       "license": "MIT"
     },
     "node_modules/synckit": {
-      "version": "0.11.12",
-      "resolved": "https://registry.npmjs.org/synckit/-/synckit-0.11.12.tgz",
-      "integrity": "sha512-Bh7QjT8/SuKUIfObSXNHNSK6WHo6J1tHCqJsuaFDP7gP0fkzSfTxI8y85JrppZ0h8l0maIgc2tfuZQ6/t3GtnQ==",
+      "version": "0.12.3",
+      "resolved": "https://registry.npmjs.org/synckit/-/synckit-0.12.3.tgz",
+      "integrity": "sha512-U+/AXT6LWsxnj2vz9HeUuPWBNgdWxjyIEjEPdbJARC9txmgPzo2VEdqnFo4hHaNyMPtycyVJrSaQYeQv/PoyyA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@pkgr/core": "^0.2.9"
+        "@dual-bundle/import-meta-resolve": "^4.2.1",
+        "@pkgr/core": "^0.3.6"
       },
       "engines": {
         "node": "^14.18.0 || >=16.0.0"
@@ -33163,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",
@@ -33184,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",
@@ -33228,7 +34971,7 @@
       "version": "6.0.0",
       "resolved": "https://registry.npmjs.org/test-exclude/-/test-exclude-6.0.0.tgz",
       "integrity": "sha512-cAGWPIyOHU6zlmg88jwm7VRyXnMN7iV68OGAbYDk/Mh/xC/pzVPlQtY6ngoIH/5/tciuhGfvESU8GrHrcxD56w==",
-      "dev": true,
+      "devOptional": true,
       "license": "ISC",
       "dependencies": {
         "@istanbuljs/schema": "^0.1.2",
@@ -33243,7 +34986,7 @@
       "version": "1.1.12",
       "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
       "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^1.0.0",
@@ -33255,7 +34998,7 @@
       "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,
+      "devOptional": true,
       "license": "ISC",
       "dependencies": {
         "fs.realpath": "^1.0.0",
@@ -33276,7 +35019,7 @@
       "version": "3.1.5",
       "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
       "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
-      "dev": true,
+      "devOptional": true,
       "license": "ISC",
       "dependencies": {
         "brace-expansion": "^1.1.7"
@@ -33579,6 +35322,19 @@
       "integrity": "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==",
       "license": "MIT"
     },
+    "node_modules/ts-api-utils": {
+      "version": "2.5.0",
+      "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.5.0.tgz",
+      "integrity": "sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.12"
+      },
+      "peerDependencies": {
+        "typescript": ">=4.8.4"
+      }
+    },
     "node_modules/ts-declaration-location": {
       "version": "1.0.7",
       "resolved": "https://registry.npmjs.org/ts-declaration-location/-/ts-declaration-location-1.0.7.tgz",
@@ -33868,7 +35624,7 @@
       "version": "4.0.8",
       "resolved": "https://registry.npmjs.org/type-detect/-/type-detect-4.0.8.tgz",
       "integrity": "sha512-0fr/mIH1dlO+x7TlcMy+bIDqKPsw/70tVyeHW787goQjhmqaZe10uwLujubK9q9Lg6Fiho1KUKDYz0Z7k7g5/g==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=4"
@@ -34153,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",
@@ -34362,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",
@@ -34517,6 +36276,22 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/v8-to-istanbul": {
+      "version": "9.3.0",
+      "resolved": "https://registry.npmjs.org/v8-to-istanbul/-/v8-to-istanbul-9.3.0.tgz",
+      "integrity": "sha512-kiGUalWN+rgBJ/1OHZsBtU4rXZOfj/7rKQxULKlIzwzQSvMJUUNgPwJEEh7gU6xEVxC0ahoOBvN2YI8GH6FNgA==",
+      "devOptional": true,
+      "license": "ISC",
+      "peer": true,
+      "dependencies": {
+        "@jridgewell/trace-mapping": "^0.3.12",
+        "@types/istanbul-lib-coverage": "^2.0.1",
+        "convert-source-map": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10.12.0"
+      }
+    },
     "node_modules/validate-npm-package-license": {
       "version": "3.0.4",
       "resolved": "https://registry.npmjs.org/validate-npm-package-license/-/validate-npm-package-license-3.0.4.tgz",
@@ -34559,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",
@@ -34982,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",
@@ -35517,7 +37290,7 @@
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
       "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=10"
@@ -35695,7 +37468,7 @@
     },
     "packages/app": {
       "name": "@getpaseo/app",
-      "version": "0.13.2",
+      "version": "0.15.3",
       "dependencies": {
         "@codemirror/commands": "6.10.4",
         "@codemirror/language": "6.12.4",
@@ -35713,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",
@@ -35725,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.212",
-        "@xterm/xterm": "^6.1.0-beta.213",
+        "@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",
@@ -35808,7 +37583,8 @@
         "@types/ws": "^8.18.1",
         "@vitest/browser": "^4.1.7",
         "@vitest/browser-playwright": "^4.1.7",
-        "@xterm/headless": "^6.1.0-beta.213",
+        "@xterm/addon-serialize": "0.14.0",
+        "@xterm/headless": "6.1.0-beta.334",
         "babel-preset-expo": "~57.0.16",
         "dotenv": "^17.2.3",
         "eas-cli": "^16.24.1",
@@ -36587,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",
@@ -36639,34 +38406,6 @@
         "@xterm/xterm": "^6.1.0-beta.213"
       }
     },
-    "packages/app/node_modules/@xterm/addon-webgl": {
-      "version": "0.20.0-beta.212",
-      "resolved": "https://registry.npmjs.org/@xterm/addon-webgl/-/addon-webgl-0.20.0-beta.212.tgz",
-      "integrity": "sha512-RzaTYeukTXTJth+Sl7FzCmb8AqiyDrNWNnqG+/300qJbfHYfCMmBlBVZ0yCTSZIWMdgFbgkhmnmBN7Yzs6xoBA==",
-      "license": "MIT",
-      "peerDependencies": {
-        "@xterm/xterm": "^6.1.0-beta.213"
-      }
-    },
-    "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.213",
-      "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-6.1.0-beta.213.tgz",
-      "integrity": "sha512-bq5nJkgoZDSg6Ma4zgiQ7jlooGNo7U+HDa6vnhx43yXsVEK2laIF7R08bMYAuU0B+C9xX0gwSrcsW18GxjUoJQ==",
-      "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",
@@ -37103,43 +38842,6 @@
         "typescript": ">=4.8.4 <6.1.0"
       }
     },
-    "packages/app/node_modules/eslint-config-expo/node_modules/eslint-plugin-react-hooks": {
-      "version": "7.1.1",
-      "resolved": "https://registry.npmjs.org/eslint-plugin-react-hooks/-/eslint-plugin-react-hooks-7.1.1.tgz",
-      "integrity": "sha512-f2I7Gw6JbvCexzIInuSbZpfdQ44D7iqdWX01FKLvrPgqxoE7oMj8clOfto8U6vYiz4yd5oKu39rRSVOe1zRu0g==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@babel/core": "^7.24.4",
-        "@babel/parser": "^7.24.4",
-        "hermes-parser": "^0.25.1",
-        "zod": "^3.25.0 || ^4.0.0",
-        "zod-validation-error": "^3.5.0 || ^4.0.0"
-      },
-      "engines": {
-        "node": ">=18"
-      },
-      "peerDependencies": {
-        "eslint": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0 || ^10.0.0"
-      }
-    },
-    "packages/app/node_modules/eslint-config-expo/node_modules/hermes-estree": {
-      "version": "0.25.1",
-      "resolved": "https://registry.npmjs.org/hermes-estree/-/hermes-estree-0.25.1.tgz",
-      "integrity": "sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==",
-      "dev": true,
-      "license": "MIT"
-    },
-    "packages/app/node_modules/eslint-config-expo/node_modules/hermes-parser": {
-      "version": "0.25.1",
-      "resolved": "https://registry.npmjs.org/hermes-parser/-/hermes-parser-0.25.1.tgz",
-      "integrity": "sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "hermes-estree": "0.25.1"
-      }
-    },
     "packages/app/node_modules/eslint-config-expo/node_modules/ignore": {
       "version": "7.0.12",
       "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.12.tgz",
@@ -37150,19 +38852,6 @@
         "node": ">= 4"
       }
     },
-    "packages/app/node_modules/eslint-config-expo/node_modules/ts-api-utils": {
-      "version": "2.5.0",
-      "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.5.0.tgz",
-      "integrity": "sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=18.12"
-      },
-      "peerDependencies": {
-        "typescript": ">=4.8.4"
-      }
-    },
     "packages/app/node_modules/eslint-plugin-expo": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/eslint-plugin-expo/-/eslint-plugin-expo-1.2.1.tgz",
@@ -37272,19 +38961,6 @@
         "typescript": ">=4.8.4 <6.1.0"
       }
     },
-    "packages/app/node_modules/eslint-plugin-expo/node_modules/ts-api-utils": {
-      "version": "2.5.0",
-      "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.5.0.tgz",
-      "integrity": "sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=18.12"
-      },
-      "peerDependencies": {
-        "typescript": ">=4.8.4"
-      }
-    },
     "packages/app/node_modules/eslint-visitor-keys": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-5.0.1.tgz",
@@ -37961,12 +39637,13 @@
     },
     "packages/cli": {
       "name": "@getpaseo/cli",
-      "version": "0.13.2",
+      "version": "0.15.3",
+      "license": "Apache-2.0",
       "dependencies": {
         "@clack/prompts": "^1.0.0",
-        "@getpaseo/client": "0.13.2",
-        "@getpaseo/protocol": "0.13.2",
-        "@getpaseo/server": "0.13.2",
+        "@getpaseo/client": "0.15.3",
+        "@getpaseo/protocol": "0.15.3",
+        "@getpaseo/server": "0.15.3",
         "chalk": "^5.3.0",
         "commander": "^12.0.0",
         "mime-types": "^2.1.35",
@@ -38213,10 +39890,11 @@
     },
     "packages/client": {
       "name": "@getpaseo/client",
-      "version": "0.13.2",
+      "version": "0.15.3",
+      "license": "Apache-2.0",
       "dependencies": {
-        "@getpaseo/protocol": "0.13.2",
-        "@getpaseo/relay": "0.13.2",
+        "@getpaseo/protocol": "0.15.3",
+        "@getpaseo/relay": "0.15.3",
         "ws": "^8.20.0",
         "zod": "^4.4.3"
       },
@@ -38228,7 +39906,7 @@
     },
     "packages/desktop": {
       "name": "@getpaseo/desktop",
-      "version": "0.13.2",
+      "version": "0.15.3",
       "license": "Apache-2.0",
       "dependencies": {
         "@getpaseo/cli": "*",
@@ -38243,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",
@@ -38472,12 +40149,11 @@
     },
     "packages/expo-two-way-audio": {
       "name": "@getpaseo/expo-two-way-audio",
-      "version": "0.13.2",
+      "version": "0.15.3",
       "license": "MIT",
       "devDependencies": {
         "@types/jest": "^29.5.14",
         "@types/react": "^18.0.25",
-        "expo-module-scripts": "^5.0.8",
         "expo-modules-core": "^2.0.4"
       },
       "peerDependencies": {
@@ -38486,1234 +40162,6 @@
         "react-native": "*"
       }
     },
-    "packages/expo-two-way-audio/node_modules/@expo/code-signing-certificates": {
-      "version": "0.0.7",
-      "resolved": "https://registry.npmjs.org/@expo/code-signing-certificates/-/code-signing-certificates-0.0.7.tgz",
-      "integrity": "sha512-zP0tnfqrFFRL8INtOaQ6XwEYfdIpIH9vrEo7y0bHQGQa50z4/QWXE5CI4nRUHxqFW4MVWOwXFg1hom1aAZHNkQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "node-forge": "^1.4.0"
-      },
-      "engines": {
-        "node": ">=22.13.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/config": {
-      "version": "12.0.13",
-      "resolved": "https://registry.npmjs.org/@expo/config/-/config-12.0.13.tgz",
-      "integrity": "sha512-Cu52arBa4vSaupIWsF0h7F/Cg//N374nYb7HAxV0I4KceKA7x2UXpYaHOL7EEYYvp7tZdThBjvGpVmr8ScIvaQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@babel/code-frame": "~7.10.4",
-        "@expo/config-plugins": "~54.0.4",
-        "@expo/config-types": "^54.0.10",
-        "@expo/json-file": "^10.0.8",
-        "deepmerge": "^4.3.1",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "require-from-string": "^2.0.2",
-        "resolve-from": "^5.0.0",
-        "resolve-workspace-root": "^2.0.0",
-        "semver": "^7.6.0",
-        "slugify": "^1.3.4",
-        "sucrase": "~3.35.1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/config-plugins": {
-      "version": "54.0.4",
-      "resolved": "https://registry.npmjs.org/@expo/config-plugins/-/config-plugins-54.0.4.tgz",
-      "integrity": "sha512-g2yXGICdoOw5i3LkQSDxl2Q5AlQCrG7oniu0pCPPO+UxGb7He4AFqSvPSy8HpRUj55io17hT62FTjYRD+d6j3Q==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@expo/config-types": "^54.0.10",
-        "@expo/json-file": "~10.0.8",
-        "@expo/plist": "^0.4.8",
-        "@expo/sdk-runtime-versions": "^1.0.0",
-        "chalk": "^4.1.2",
-        "debug": "^4.3.5",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "resolve-from": "^5.0.0",
-        "semver": "^7.5.4",
-        "slash": "^3.0.0",
-        "slugify": "^1.6.6",
-        "xcode": "^3.0.1",
-        "xml2js": "0.6.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/config-plugins/node_modules/@babel/code-frame": {
-      "version": "7.10.4",
-      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.10.4.tgz",
-      "integrity": "sha512-vG6SvB6oYEhvgisZNFRmRCUkLz11c7rp+tbNTynGqc6mS1d5ATd/sGyV6W0KZZnXRKMTzZDRgQT3Ou9jhpAfUg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@babel/highlight": "^7.10.4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/config-plugins/node_modules/@expo/json-file": {
-      "version": "10.0.16",
-      "resolved": "https://registry.npmjs.org/@expo/json-file/-/json-file-10.0.16.tgz",
-      "integrity": "sha512-fcVkWEj+hLuP2yt5W0aw6LmDRqSPWDLUSxOMcmFeV+algmIF59sQVKCwB9btjQLd4V6x9N0pISkQEkBubUHrCw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@babel/code-frame": "~7.10.4",
-        "json5": "^2.2.3"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/config-types": {
-      "version": "54.0.10",
-      "resolved": "https://registry.npmjs.org/@expo/config-types/-/config-types-54.0.10.tgz",
-      "integrity": "sha512-/J16SC2an1LdtCZ67xhSkGXpALYUVUNyZws7v+PVsFZxClYehDSoKLqyRaGkpHlYrCc08bS0RF5E0JV6g50psA==",
-      "dev": true,
-      "license": "MIT"
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/config/node_modules/@babel/code-frame": {
-      "version": "7.10.4",
-      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.10.4.tgz",
-      "integrity": "sha512-vG6SvB6oYEhvgisZNFRmRCUkLz11c7rp+tbNTynGqc6mS1d5ATd/sGyV6W0KZZnXRKMTzZDRgQT3Ou9jhpAfUg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@babel/highlight": "^7.10.4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/devtools": {
-      "version": "58.0.2",
-      "resolved": "https://registry.npmjs.org/@expo/devtools/-/devtools-58.0.2.tgz",
-      "integrity": "sha512-WBj/K+vv8JPSmY70ennL04YYOHkpEsGGkfuVY9lfv4XO7Qhbt5qz4q6W7maME194I5oGcimRMigUFfWNkBe90w==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "chalk": "^4.1.2"
-      },
-      "peerDependencies": {
-        "expo": "*",
-        "react": "*",
-        "react-native": "*"
-      },
-      "peerDependenciesMeta": {
-        "expo": {
-          "optional": true
-        },
-        "react": {
-          "optional": true
-        },
-        "react-native": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/dom-webview": {
-      "version": "58.0.2",
-      "resolved": "https://registry.npmjs.org/@expo/dom-webview/-/dom-webview-58.0.2.tgz",
-      "integrity": "sha512-bLkREoP7qL3rEuzxP60xG+TjdPoGjbnZfxkvYo5imJxGWfKMOf7x962W06Pu+WWAr4gcDRk16iA+Clg8D0zjCg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "peerDependencies": {
-        "expo": "*",
-        "react": "*",
-        "react-native": "*"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/env": {
-      "version": "2.5.2",
-      "resolved": "https://registry.npmjs.org/@expo/env/-/env-2.5.2.tgz",
-      "integrity": "sha512-z8kCvBVJpd2S20a+Ab1otQgz8sJLeR7CXDTsuAMcNbYFsK10Fdhfb7rx9Ys1vvlbijnY55eZhQvJACajc1IjBQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "chalk": "^4.0.0",
-        "debug": "^4.3.4",
-        "getenv": "^2.0.0"
-      },
-      "engines": {
-        "node": ">=20.12.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/fingerprint": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@expo/fingerprint/-/fingerprint-0.21.5.tgz",
-      "integrity": "sha512-4ngc+aPgMK56sYc47tfabmoaNdP7OvPBOH7QPgN3riSYM0Ev+KwsGRDius5jBBwjCI9ADp7IpjJEK9xlRYjjvA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/env": "^2.5.2",
-        "@expo/spawn-async": "^1.8.0",
-        "arg": "^5.0.2",
-        "chalk": "^4.1.2",
-        "debug": "^4.3.4",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "ignore": "^5.3.1",
-        "minimatch": "^10.2.2",
-        "resolve-from": "^5.0.0",
-        "semver": "^7.7.4"
-      },
-      "bin": {
-        "fingerprint": "bin/cli.js"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/fingerprint/node_modules/ignore": {
-      "version": "5.3.2",
-      "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz",
-      "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">= 4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/image-utils": {
-      "version": "0.12.5",
-      "resolved": "https://registry.npmjs.org/@expo/image-utils/-/image-utils-0.12.5.tgz",
-      "integrity": "sha512-nsFYd7GfDdwZa+S+p+EkVCkh7UKKNf0kfUXDQ53HbyMmNFD3psb5JYwU/2N+uZG5wOEfKGfQ5u7pk/wn2gMlBA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/require-utils": "^58.0.4",
-        "@expo/spawn-async": "^1.8.0",
-        "chalk": "^4.0.0",
-        "getenv": "^2.0.0",
-        "jimp-compact": "0.16.1",
-        "parse-png": "^2.1.0",
-        "semver": "^7.7.4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/image-utils/node_modules/@expo/require-utils": {
-      "version": "58.0.4",
-      "resolved": "https://registry.npmjs.org/@expo/require-utils/-/require-utils-58.0.4.tgz",
-      "integrity": "sha512-DvjS5NCitXYcad2Woe1EMHJKcbhTbE77HX0BgOQGL2LFHE3q2H0n8kCWDPBOCVJ63Drap3c35nwoJwF5TQL7Tw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "@babel/core": "^7.25.2",
-        "@babel/plugin-transform-modules-commonjs": "^7.24.8"
-      },
-      "peerDependencies": {
-        "typescript": "^5.0.0 || ^5.0.0-0 || ^6.0.0 || ^7.0.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/inline-modules": {
-      "version": "0.2.6",
-      "resolved": "https://registry.npmjs.org/@expo/inline-modules/-/inline-modules-0.2.6.tgz",
-      "integrity": "sha512-S8PK3wx6ogwunoQ7pqdPbklQGtXloeWTAOzWJ9yIL7xHFxvnI/Ryj0phA3KEGCMlaKZjaCP1h/3s7n/ueErRgQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config-plugins": "~58.0.9"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/inline-modules/node_modules/@expo/config-plugins": {
-      "version": "58.0.9",
-      "resolved": "https://registry.npmjs.org/@expo/config-plugins/-/config-plugins-58.0.9.tgz",
-      "integrity": "sha512-HyP7V1QgDxeHcOEh4qQH7cfK7cI7wNp0y9lszAu98SRYCshhDbwB9gWpFfnpX1GQUtgiqG4Hvgh1z3ntcGwAjw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config-types": "^58.0.3",
-        "@expo/json-file": "~11.2.1",
-        "@expo/plist": "^0.10.1",
-        "@expo/require-utils": "^58.0.4",
-        "@expo/sdk-runtime-versions": "^1.0.1",
-        "chalk": "^4.1.2",
-        "debug": "^4.3.5",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "semver": "^7.7.4",
-        "slugify": "^1.6.6",
-        "xcode": "^3.0.1",
-        "xml2js": "0.6.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/inline-modules/node_modules/@expo/config-types": {
-      "version": "58.0.3",
-      "resolved": "https://registry.npmjs.org/@expo/config-types/-/config-types-58.0.3.tgz",
-      "integrity": "sha512-wyfrwkTT/hQHzwyqkXkngKxoOa8L6ovsTP4h/UukS1mTmssee5et6HOPoN5RtawdJPnm5JO28f//C/wXlpka8Q==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/inline-modules/node_modules/@expo/json-file": {
-      "version": "11.2.1",
-      "resolved": "https://registry.npmjs.org/@expo/json-file/-/json-file-11.2.1.tgz",
-      "integrity": "sha512-UPhKoFCj8BcwgLB1rKQ1CuR/REITnZLiqxHEHOeH1tPsdXcHGtUDh0P5bLbr7oU0nKVdtJ5rzyKx8jniMQdESQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "json5": "^2.2.3"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/inline-modules/node_modules/@expo/plist": {
-      "version": "0.10.1",
-      "resolved": "https://registry.npmjs.org/@expo/plist/-/plist-0.10.1.tgz",
-      "integrity": "sha512-nuNOqj+r/hGJbZ1Ax3jUpZaOB8UAMHUrISALJEUKaCieTflYj7224EqFWmMpriCGk9wXS1gH+9GGVnSj0tWzuQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@xmldom/xmldom": "^0.8.8",
-        "base64-js": "^1.5.1",
-        "xmlbuilder": "^15.1.1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/inline-modules/node_modules/@expo/require-utils": {
-      "version": "58.0.4",
-      "resolved": "https://registry.npmjs.org/@expo/require-utils/-/require-utils-58.0.4.tgz",
-      "integrity": "sha512-DvjS5NCitXYcad2Woe1EMHJKcbhTbE77HX0BgOQGL2LFHE3q2H0n8kCWDPBOCVJ63Drap3c35nwoJwF5TQL7Tw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "@babel/core": "^7.25.2",
-        "@babel/plugin-transform-modules-commonjs": "^7.24.8"
-      },
-      "peerDependencies": {
-        "typescript": "^5.0.0 || ^5.0.0-0 || ^6.0.0 || ^7.0.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/json-file": {
-      "version": "10.2.0",
-      "resolved": "https://registry.npmjs.org/@expo/json-file/-/json-file-10.2.0.tgz",
-      "integrity": "sha512-S6XzKe3R9GQeHiUPXc3xJjOv2VJhOEwFYf7xdC2z2cUqt3kZJ9mSO877sNQloVdnW/SUCtPY3bexlM7nwq+CAQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "json5": "^2.2.3"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/local-build-cache-provider": {
-      "version": "58.0.6",
-      "resolved": "https://registry.npmjs.org/@expo/local-build-cache-provider/-/local-build-cache-provider-58.0.6.tgz",
-      "integrity": "sha512-AJk3pslFNlwRMbUbfvxhu6CPA9U7A+JPb88VS/uWkG/S/QMJL90Iw4sPVfG4BOKfRUNkB8ipl432Dr4txjSMKw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config": "~58.0.6",
-        "chalk": "^4.1.2"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/local-build-cache-provider/node_modules/@expo/config": {
-      "version": "58.0.6",
-      "resolved": "https://registry.npmjs.org/@expo/config/-/config-58.0.6.tgz",
-      "integrity": "sha512-PT1qv4s/R5A/NxXb4efGlFsYF5Consi7F8xSsJBAN090EGDr6U1EDQGOijFqzDc3JA2epD8zjKLJLOVB9YOewg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config-plugins": "~58.0.9",
-        "@expo/config-types": "^58.0.3",
-        "@expo/json-file": "^11.2.1",
-        "@expo/platforms": "^58.0.1",
-        "@expo/require-utils": "^58.0.4",
-        "deepmerge": "^4.3.1",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "resolve-workspace-root": "^2.0.0",
-        "semver": "^7.7.4",
-        "slugify": "^1.3.4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/local-build-cache-provider/node_modules/@expo/config-plugins": {
-      "version": "58.0.9",
-      "resolved": "https://registry.npmjs.org/@expo/config-plugins/-/config-plugins-58.0.9.tgz",
-      "integrity": "sha512-HyP7V1QgDxeHcOEh4qQH7cfK7cI7wNp0y9lszAu98SRYCshhDbwB9gWpFfnpX1GQUtgiqG4Hvgh1z3ntcGwAjw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config-types": "^58.0.3",
-        "@expo/json-file": "~11.2.1",
-        "@expo/plist": "^0.10.1",
-        "@expo/require-utils": "^58.0.4",
-        "@expo/sdk-runtime-versions": "^1.0.1",
-        "chalk": "^4.1.2",
-        "debug": "^4.3.5",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "semver": "^7.7.4",
-        "slugify": "^1.6.6",
-        "xcode": "^3.0.1",
-        "xml2js": "0.6.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/local-build-cache-provider/node_modules/@expo/config-types": {
-      "version": "58.0.3",
-      "resolved": "https://registry.npmjs.org/@expo/config-types/-/config-types-58.0.3.tgz",
-      "integrity": "sha512-wyfrwkTT/hQHzwyqkXkngKxoOa8L6ovsTP4h/UukS1mTmssee5et6HOPoN5RtawdJPnm5JO28f//C/wXlpka8Q==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/local-build-cache-provider/node_modules/@expo/json-file": {
-      "version": "11.2.1",
-      "resolved": "https://registry.npmjs.org/@expo/json-file/-/json-file-11.2.1.tgz",
-      "integrity": "sha512-UPhKoFCj8BcwgLB1rKQ1CuR/REITnZLiqxHEHOeH1tPsdXcHGtUDh0P5bLbr7oU0nKVdtJ5rzyKx8jniMQdESQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "json5": "^2.2.3"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/local-build-cache-provider/node_modules/@expo/plist": {
-      "version": "0.10.1",
-      "resolved": "https://registry.npmjs.org/@expo/plist/-/plist-0.10.1.tgz",
-      "integrity": "sha512-nuNOqj+r/hGJbZ1Ax3jUpZaOB8UAMHUrISALJEUKaCieTflYj7224EqFWmMpriCGk9wXS1gH+9GGVnSj0tWzuQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@xmldom/xmldom": "^0.8.8",
-        "base64-js": "^1.5.1",
-        "xmlbuilder": "^15.1.1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/local-build-cache-provider/node_modules/@expo/require-utils": {
-      "version": "58.0.4",
-      "resolved": "https://registry.npmjs.org/@expo/require-utils/-/require-utils-58.0.4.tgz",
-      "integrity": "sha512-DvjS5NCitXYcad2Woe1EMHJKcbhTbE77HX0BgOQGL2LFHE3q2H0n8kCWDPBOCVJ63Drap3c35nwoJwF5TQL7Tw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "@babel/core": "^7.25.2",
-        "@babel/plugin-transform-modules-commonjs": "^7.24.8"
-      },
-      "peerDependencies": {
-        "typescript": "^5.0.0 || ^5.0.0-0 || ^6.0.0 || ^7.0.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/log-box": {
-      "version": "58.0.12",
-      "resolved": "https://registry.npmjs.org/@expo/log-box/-/log-box-58.0.12.tgz",
-      "integrity": "sha512-IzDYoFY2iUsmSDvl1V7YUM7UkCPDyMVS4e4a38c2LnFc1A3WGMUiQh+vsHLYTPKjIelu4r7/u4V7Gxtfa0oJgA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/dom-webview": "^58.0.2",
-        "@expo/log-box-utils": "^58.0.2",
-        "anser": "^1.4.9",
-        "stacktrace-parser": "^0.1.10"
-      },
-      "peerDependencies": {
-        "@expo/dom-webview": "^58.0.2",
-        "expo": "*",
-        "react": "*",
-        "react-native": "*"
-      },
-      "peerDependenciesMeta": {
-        "expo": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro": {
-      "version": "58.0.0",
-      "resolved": "https://registry.npmjs.org/@expo/metro/-/metro-58.0.0.tgz",
-      "integrity": "sha512-PMD640ihB0C3Oqm0AnDVJ/8qF2cKbRUEqGuSOr4tM/OTb9ktxsQqsiSSSeaOEgdCZBq20AxRS0d6WHNhhH2P+g==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "metro": "0.87.1",
-        "metro-babel-transformer": "0.87.1",
-        "metro-cache": "0.87.1",
-        "metro-cache-key": "0.87.1",
-        "metro-config": "0.87.1",
-        "metro-core": "0.87.1",
-        "metro-file-map": "0.87.1",
-        "metro-minify-terser": "0.87.1",
-        "metro-resolver": "0.87.1",
-        "metro-runtime": "0.87.1",
-        "metro-source-map": "0.87.1",
-        "metro-symbolicate": "0.87.1",
-        "metro-transform-plugins": "0.87.1",
-        "metro-transform-worker": "0.87.1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-config": {
-      "version": "58.0.14",
-      "resolved": "https://registry.npmjs.org/@expo/metro-config/-/metro-config-58.0.14.tgz",
-      "integrity": "sha512-UDUMAJwYGEzaB26ejMLG/IOVzwKDbHzoODBf3FZeRS94kk9jDf1dWE1VMX6bLBLoiflxXwqrMWiH0Fvz3gZ9YQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "@babel/core": "^7.20.0",
-        "@babel/generator": "^7.20.5",
-        "@expo/config": "~58.0.6",
-        "@expo/env": "~2.5.2",
-        "@expo/json-file": "~11.2.1",
-        "@expo/metro": "~58.0.0",
-        "@expo/platforms": "^58.0.1",
-        "@expo/require-utils": "^58.0.4",
-        "@expo/spawn-async": "^1.8.0",
-        "@jridgewell/gen-mapping": "^0.3.13",
-        "@jridgewell/remapping": "^2.3.5",
-        "@jridgewell/sourcemap-codec": "^1.5.5",
-        "@jridgewell/trace-mapping": "^0.3.31",
-        "@react-native/js-polyfills": "0.88.0",
-        "2g": "^1.0.1",
-        "browserslist": "^4.25.0",
-        "chalk": "^4.1.0",
-        "debug": "^4.3.2",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "hermes-parser": "^0.36.0",
-        "jsc-safe-url": "^0.2.4",
-        "lightningcss": "^1.30.1",
-        "noxcturnal": "^0.1.0",
-        "picomatch": "^4.0.4",
-        "postcss": "^8.5.23",
-        "resolve-from": "^5.0.0"
-      },
-      "peerDependencies": {
-        "expo": "*"
-      },
-      "peerDependenciesMeta": {
-        "expo": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-config/node_modules/@expo/config": {
-      "version": "58.0.6",
-      "resolved": "https://registry.npmjs.org/@expo/config/-/config-58.0.6.tgz",
-      "integrity": "sha512-PT1qv4s/R5A/NxXb4efGlFsYF5Consi7F8xSsJBAN090EGDr6U1EDQGOijFqzDc3JA2epD8zjKLJLOVB9YOewg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config-plugins": "~58.0.9",
-        "@expo/config-types": "^58.0.3",
-        "@expo/json-file": "^11.2.1",
-        "@expo/platforms": "^58.0.1",
-        "@expo/require-utils": "^58.0.4",
-        "deepmerge": "^4.3.1",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "resolve-workspace-root": "^2.0.0",
-        "semver": "^7.7.4",
-        "slugify": "^1.3.4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-config/node_modules/@expo/config-plugins": {
-      "version": "58.0.9",
-      "resolved": "https://registry.npmjs.org/@expo/config-plugins/-/config-plugins-58.0.9.tgz",
-      "integrity": "sha512-HyP7V1QgDxeHcOEh4qQH7cfK7cI7wNp0y9lszAu98SRYCshhDbwB9gWpFfnpX1GQUtgiqG4Hvgh1z3ntcGwAjw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config-types": "^58.0.3",
-        "@expo/json-file": "~11.2.1",
-        "@expo/plist": "^0.10.1",
-        "@expo/require-utils": "^58.0.4",
-        "@expo/sdk-runtime-versions": "^1.0.1",
-        "chalk": "^4.1.2",
-        "debug": "^4.3.5",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "semver": "^7.7.4",
-        "slugify": "^1.6.6",
-        "xcode": "^3.0.1",
-        "xml2js": "0.6.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-config/node_modules/@expo/config-types": {
-      "version": "58.0.3",
-      "resolved": "https://registry.npmjs.org/@expo/config-types/-/config-types-58.0.3.tgz",
-      "integrity": "sha512-wyfrwkTT/hQHzwyqkXkngKxoOa8L6ovsTP4h/UukS1mTmssee5et6HOPoN5RtawdJPnm5JO28f//C/wXlpka8Q==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-config/node_modules/@expo/json-file": {
-      "version": "11.2.1",
-      "resolved": "https://registry.npmjs.org/@expo/json-file/-/json-file-11.2.1.tgz",
-      "integrity": "sha512-UPhKoFCj8BcwgLB1rKQ1CuR/REITnZLiqxHEHOeH1tPsdXcHGtUDh0P5bLbr7oU0nKVdtJ5rzyKx8jniMQdESQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "json5": "^2.2.3"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-config/node_modules/@expo/plist": {
-      "version": "0.10.1",
-      "resolved": "https://registry.npmjs.org/@expo/plist/-/plist-0.10.1.tgz",
-      "integrity": "sha512-nuNOqj+r/hGJbZ1Ax3jUpZaOB8UAMHUrISALJEUKaCieTflYj7224EqFWmMpriCGk9wXS1gH+9GGVnSj0tWzuQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@xmldom/xmldom": "^0.8.8",
-        "base64-js": "^1.5.1",
-        "xmlbuilder": "^15.1.1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-config/node_modules/@expo/require-utils": {
-      "version": "58.0.4",
-      "resolved": "https://registry.npmjs.org/@expo/require-utils/-/require-utils-58.0.4.tgz",
-      "integrity": "sha512-DvjS5NCitXYcad2Woe1EMHJKcbhTbE77HX0BgOQGL2LFHE3q2H0n8kCWDPBOCVJ63Drap3c35nwoJwF5TQL7Tw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "@babel/core": "^7.25.2",
-        "@babel/plugin-transform-modules-commonjs": "^7.24.8"
-      },
-      "peerDependencies": {
-        "typescript": "^5.0.0 || ^5.0.0-0 || ^6.0.0 || ^7.0.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-config/node_modules/2g": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/2g/-/2g-1.0.1.tgz",
-      "integrity": "sha512-+uViadKOS/wwR4pFu5g8TPn3QHpKqoX19JHCnp8k/3cLpImdcXozwvZA6Q/5PeW3AcU8neL8faaMidBcv7o8CA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "bin": {
-        "2g": "bin/cli.js"
-      },
-      "peerDependencies": {
-        "typescript": ">=5.8.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-config/node_modules/hermes-estree": {
-      "version": "0.36.1",
-      "resolved": "https://registry.npmjs.org/hermes-estree/-/hermes-estree-0.36.1.tgz",
-      "integrity": "sha512-guv1nQ6IJ7S83NRFPWc3SA7IBZrdNC9kapwOq6uXvF4wP+sDCgjzQbKPCoyYmoyZRzztF/n/c36l/rccCZSiCw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-config/node_modules/hermes-parser": {
-      "version": "0.36.1",
-      "resolved": "https://registry.npmjs.org/hermes-parser/-/hermes-parser-0.36.1.tgz",
-      "integrity": "sha512-GApNk4zLHi2UWoWZZkx7LNCOSzLSc5lB55pZ/PhK7ycFeg7u5LcF88p/WbpIi1XUDtE0MpHE3uRR3u3KB7TjSQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "hermes-estree": "0.36.1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-file-map": {
-      "version": "58.0.5",
-      "resolved": "https://registry.npmjs.org/@expo/metro-file-map/-/metro-file-map-58.0.5.tgz",
-      "integrity": "sha512-Y2w8qKklLffZie28In4WF6f6e8nIJOhU0mZ5UaQdCiITVQm2a5teNdIDudEPkBsh8ItlvyHZt9n42PN2onRbkQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "2g": "^1.0.1",
-        "debug": "^4.3.4",
-        "fb-watchman": "^2.0.2",
-        "invariant": "^2.2.4",
-        "jest-worker": "^29.7.0",
-        "walker": "^1.0.8"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/metro-file-map/node_modules/2g": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/2g/-/2g-1.0.1.tgz",
-      "integrity": "sha512-+uViadKOS/wwR4pFu5g8TPn3QHpKqoX19JHCnp8k/3cLpImdcXozwvZA6Q/5PeW3AcU8neL8faaMidBcv7o8CA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "bin": {
-        "2g": "bin/cli.js"
-      },
-      "peerDependencies": {
-        "typescript": ">=5.8.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/osascript": {
-      "version": "2.8.1",
-      "resolved": "https://registry.npmjs.org/@expo/osascript/-/osascript-2.8.1.tgz",
-      "integrity": "sha512-SCi+6q6uOkGhiAn6AIP/OPFgaIq/iKD2oYpnAOg2rShHStJ8ey7wyT127RbOaZXmlcY/62rHOX1WiiMnD8u/BA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/spawn-async": "^1.8.0"
-      },
-      "engines": {
-        "node": ">=12"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/package-manager": {
-      "version": "1.14.2",
-      "resolved": "https://registry.npmjs.org/@expo/package-manager/-/package-manager-1.14.2.tgz",
-      "integrity": "sha512-sftl0eRVVCarI6grMdjAB3jX2pX1Mt3cdSnajlXS4QyeDkaKRM/ntBy6dcagj1VL0+cEfEqctlyvinmlZdNubg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/json-file": "^11.2.1",
-        "@expo/spawn-async": "^1.8.0",
-        "chalk": "^4.0.0",
-        "npm-package-arg": "^11.0.0",
-        "ora": "^3.4.0",
-        "resolve-workspace-root": "^2.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/package-manager/node_modules/@expo/json-file": {
-      "version": "11.2.1",
-      "resolved": "https://registry.npmjs.org/@expo/json-file/-/json-file-11.2.1.tgz",
-      "integrity": "sha512-UPhKoFCj8BcwgLB1rKQ1CuR/REITnZLiqxHEHOeH1tPsdXcHGtUDh0P5bLbr7oU0nKVdtJ5rzyKx8jniMQdESQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "json5": "^2.2.3"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/plist": {
-      "version": "0.4.9",
-      "resolved": "https://registry.npmjs.org/@expo/plist/-/plist-0.4.9.tgz",
-      "integrity": "sha512-MPVpmKGfnQEnrCzgxuXcmPP/y/t6AVm+DcSb2Myp21LKWv1N3l8uFxMggesfF4ixAxkRlGmMMx9GyDC9M+XklQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@xmldom/xmldom": "^0.8.8",
-        "base64-js": "^1.2.3",
-        "xmlbuilder": "^15.1.1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/prebuild-config": {
-      "version": "58.0.14",
-      "resolved": "https://registry.npmjs.org/@expo/prebuild-config/-/prebuild-config-58.0.14.tgz",
-      "integrity": "sha512-2wVzVDfXjRB3LzUbW5shOM/A+6eUUCfR+2bpZiWRBBZBtZP2HA5Zq1YgCio1tDqMGAHf2NQQDhvy/Rz1U6aC3A==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config": "~58.0.6",
-        "@expo/config-plugins": "~58.0.9",
-        "@expo/config-types": "^58.0.3",
-        "@expo/image-utils": "^0.12.5",
-        "@expo/json-file": "^11.2.1",
-        "@react-native/normalize-colors": "0.88.0",
-        "debug": "^4.3.1",
-        "expo-modules-autolinking": "~58.0.13",
-        "resolve-from": "^5.0.0",
-        "semver": "^7.7.4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/prebuild-config/node_modules/@expo/config": {
-      "version": "58.0.6",
-      "resolved": "https://registry.npmjs.org/@expo/config/-/config-58.0.6.tgz",
-      "integrity": "sha512-PT1qv4s/R5A/NxXb4efGlFsYF5Consi7F8xSsJBAN090EGDr6U1EDQGOijFqzDc3JA2epD8zjKLJLOVB9YOewg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config-plugins": "~58.0.9",
-        "@expo/config-types": "^58.0.3",
-        "@expo/json-file": "^11.2.1",
-        "@expo/platforms": "^58.0.1",
-        "@expo/require-utils": "^58.0.4",
-        "deepmerge": "^4.3.1",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "resolve-workspace-root": "^2.0.0",
-        "semver": "^7.7.4",
-        "slugify": "^1.3.4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/prebuild-config/node_modules/@expo/config-plugins": {
-      "version": "58.0.9",
-      "resolved": "https://registry.npmjs.org/@expo/config-plugins/-/config-plugins-58.0.9.tgz",
-      "integrity": "sha512-HyP7V1QgDxeHcOEh4qQH7cfK7cI7wNp0y9lszAu98SRYCshhDbwB9gWpFfnpX1GQUtgiqG4Hvgh1z3ntcGwAjw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config-types": "^58.0.3",
-        "@expo/json-file": "~11.2.1",
-        "@expo/plist": "^0.10.1",
-        "@expo/require-utils": "^58.0.4",
-        "@expo/sdk-runtime-versions": "^1.0.1",
-        "chalk": "^4.1.2",
-        "debug": "^4.3.5",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "semver": "^7.7.4",
-        "slugify": "^1.6.6",
-        "xcode": "^3.0.1",
-        "xml2js": "0.6.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/prebuild-config/node_modules/@expo/config-types": {
-      "version": "58.0.3",
-      "resolved": "https://registry.npmjs.org/@expo/config-types/-/config-types-58.0.3.tgz",
-      "integrity": "sha512-wyfrwkTT/hQHzwyqkXkngKxoOa8L6ovsTP4h/UukS1mTmssee5et6HOPoN5RtawdJPnm5JO28f//C/wXlpka8Q==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/prebuild-config/node_modules/@expo/json-file": {
-      "version": "11.2.1",
-      "resolved": "https://registry.npmjs.org/@expo/json-file/-/json-file-11.2.1.tgz",
-      "integrity": "sha512-UPhKoFCj8BcwgLB1rKQ1CuR/REITnZLiqxHEHOeH1tPsdXcHGtUDh0P5bLbr7oU0nKVdtJ5rzyKx8jniMQdESQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "json5": "^2.2.3"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/prebuild-config/node_modules/@expo/plist": {
-      "version": "0.10.1",
-      "resolved": "https://registry.npmjs.org/@expo/plist/-/plist-0.10.1.tgz",
-      "integrity": "sha512-nuNOqj+r/hGJbZ1Ax3jUpZaOB8UAMHUrISALJEUKaCieTflYj7224EqFWmMpriCGk9wXS1gH+9GGVnSj0tWzuQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@xmldom/xmldom": "^0.8.8",
-        "base64-js": "^1.5.1",
-        "xmlbuilder": "^15.1.1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/prebuild-config/node_modules/@expo/require-utils": {
-      "version": "58.0.4",
-      "resolved": "https://registry.npmjs.org/@expo/require-utils/-/require-utils-58.0.4.tgz",
-      "integrity": "sha512-DvjS5NCitXYcad2Woe1EMHJKcbhTbE77HX0BgOQGL2LFHE3q2H0n8kCWDPBOCVJ63Drap3c35nwoJwF5TQL7Tw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "@babel/core": "^7.25.2",
-        "@babel/plugin-transform-modules-commonjs": "^7.24.8"
-      },
-      "peerDependencies": {
-        "typescript": "^5.0.0 || ^5.0.0-0 || ^6.0.0 || ^7.0.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/schema-utils": {
-      "version": "58.0.2",
-      "resolved": "https://registry.npmjs.org/@expo/schema-utils/-/schema-utils-58.0.2.tgz",
-      "integrity": "sha512-w28y8SG+5ZTdDdmH2ZnCQk9wHVwGzI9NqX5V4urJUFEnxbm7I129fJRkb8RIAJmMA1WKU5h3ONmranV473uaXQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/sdk-runtime-versions": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/@expo/sdk-runtime-versions/-/sdk-runtime-versions-1.0.1.tgz",
-      "integrity": "sha512-kvisefkhxu8Fm/4M8G6DEqUaigrXfrSOm2lFw7hsk/nq0zchcp6B4wSk8rlheHY8FRi5iHxKtoVMGY/3M6h04A==",
-      "dev": true,
-      "license": "MIT"
-    },
-    "packages/expo-two-way-audio/node_modules/@expo/spawn-async": {
-      "version": "1.8.0",
-      "resolved": "https://registry.npmjs.org/@expo/spawn-async/-/spawn-async-1.8.0.tgz",
-      "integrity": "sha512-eb9xxd/LbuEGSdua4NumCu/McVB9EM+F/JxB9pWgnERw4HQ9XyTNH1KapG6oqLWR8TuRK2LQfzJlmNi94CVobw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "cross-spawn": "^7.0.6"
-      },
-      "engines": {
-        "node": ">=12"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@jest/schemas": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/@jest/schemas/-/schemas-30.4.1.tgz",
-      "integrity": "sha512-i6b4qw5qnP8c5FEeBJg/uZQ4ddrkN6Ca8qISJh0pr7a5hfn3h3v5x60BEbOC7OYAGZNMs1LfFLwnW2CuK8F57Q==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@sinclair/typebox": "^0.34.0"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/babel-plugin-codegen": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/babel-plugin-codegen/-/babel-plugin-codegen-0.88.0.tgz",
-      "integrity": "sha512-leGEnCcS7Q0hTxvzvhNtr8zGQpI1gfWqXjzC4UedsFmNMv6kIo4s70o0XbtM30ZXbpfWe4BcSC8NKWuak5sI4A==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/traverse": "^7.29.0",
-        "@react-native/codegen": "0.88.0"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/babel-preset": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/babel-preset/-/babel-preset-0.88.0.tgz",
-      "integrity": "sha512-iMfAHhFGNegnReSY6CYaWHncvyDwHq8olRs0zp9nRRApMAoCiLyfo1dwL/f39qt/MreD6xIqUs9SrTPYWobY6g==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "@babel/core": "^7.25.2",
-        "@babel/plugin-proposal-export-default-from": "^7.24.7",
-        "@babel/plugin-syntax-dynamic-import": "^7.8.3",
-        "@babel/plugin-syntax-export-default-from": "^7.24.7",
-        "@babel/plugin-syntax-nullish-coalescing-operator": "^7.8.3",
-        "@babel/plugin-syntax-optional-chaining": "^7.8.3",
-        "@babel/plugin-transform-async-generator-functions": "^7.25.4",
-        "@babel/plugin-transform-async-to-generator": "^7.24.7",
-        "@babel/plugin-transform-block-scoping": "^7.25.0",
-        "@babel/plugin-transform-class-properties": "^7.25.4",
-        "@babel/plugin-transform-classes": "^7.25.4",
-        "@babel/plugin-transform-destructuring": "^7.24.8",
-        "@babel/plugin-transform-flow-strip-types": "^7.25.2",
-        "@babel/plugin-transform-for-of": "^7.24.7",
-        "@babel/plugin-transform-modules-commonjs": "^7.24.8",
-        "@babel/plugin-transform-named-capturing-groups-regex": "^7.24.7",
-        "@babel/plugin-transform-nullish-coalescing-operator": "^7.24.7",
-        "@babel/plugin-transform-optional-catch-binding": "^7.24.7",
-        "@babel/plugin-transform-optional-chaining": "^7.24.8",
-        "@babel/plugin-transform-private-methods": "^7.24.7",
-        "@babel/plugin-transform-private-property-in-object": "^7.24.7",
-        "@babel/plugin-transform-react-display-name": "^7.24.7",
-        "@babel/plugin-transform-react-jsx": "^7.25.2",
-        "@babel/plugin-transform-react-jsx-self": "^7.24.7",
-        "@babel/plugin-transform-react-jsx-source": "^7.24.7",
-        "@babel/plugin-transform-regenerator": "^7.24.7",
-        "@babel/plugin-transform-runtime": "^7.24.7",
-        "@babel/plugin-transform-typescript": "^7.25.2",
-        "@babel/plugin-transform-unicode-regex": "^7.24.7",
-        "@react-native/babel-plugin-codegen": "0.88.0",
-        "babel-plugin-transform-flow-enums": "^0.0.2",
-        "flow-parser": "0.327.0",
-        "react-refresh": "^0.14.0"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      },
-      "peerDependencies": {
-        "@babel/core": "*"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/babel-preset/node_modules/flow-parser": {
-      "version": "0.327.0",
-      "resolved": "https://registry.npmjs.org/flow-parser/-/flow-parser-0.327.0.tgz",
-      "integrity": "sha512-/MYZ5hXWf5ozpbdfUDmazMgQXviLxWEiRLH3MppEGDdW0itRVqmB5UaU7QX+SBCDNiq+gEesSVn8nlxmPDyDkw==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "flow-estree": "0.327.0"
-      },
-      "engines": {
-        "node": ">=0.4.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/codegen": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/codegen/-/codegen-0.88.0.tgz",
-      "integrity": "sha512-SAGg+XfzsrPiYTscbKa9bo2/H2ei2TjyxW8RTMq2Ps661kRK3AnmpMGVfrEFshEMr3FGEbuQIvj86X98kaXlRA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/core": "^7.25.2",
-        "@babel/parser": "^7.29.0",
-        "flow-parser": "0.327.0",
-        "invariant": "^2.2.4",
-        "nullthrows": "^1.1.1",
-        "tinyglobby": "^0.2.15",
-        "yargs": "^17.6.2"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      },
-      "peerDependencies": {
-        "@babel/core": "*"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/codegen/node_modules/flow-parser": {
-      "version": "0.327.0",
-      "resolved": "https://registry.npmjs.org/flow-parser/-/flow-parser-0.327.0.tgz",
-      "integrity": "sha512-/MYZ5hXWf5ozpbdfUDmazMgQXviLxWEiRLH3MppEGDdW0itRVqmB5UaU7QX+SBCDNiq+gEesSVn8nlxmPDyDkw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "flow-estree": "0.327.0"
-      },
-      "engines": {
-        "node": ">=0.4.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/community-cli-plugin": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/community-cli-plugin/-/community-cli-plugin-0.88.0.tgz",
-      "integrity": "sha512-WrQdXbjVt1gwAay8ZzYtpOi9ly99ksJ0VMYFdVcMe6nq3vtiRgqKRpHgCdN6ySIbtr5o+aJ+Vr7OTDY98ec/Ow==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@react-native/asset-utils": "0.88.0",
-        "@react-native/dev-middleware": "0.88.0",
-        "commander": "^12.0.0",
-        "debug": "^4.4.0",
-        "invariant": "^2.2.4",
-        "metro": "^0.87.1",
-        "semver": "^7.1.3"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      },
-      "peerDependencies": {
-        "@react-native-community/cli": "*",
-        "@react-native/metro-config": "0.88.0"
-      },
-      "peerDependenciesMeta": {
-        "@react-native-community/cli": {
-          "optional": true
-        },
-        "@react-native/metro-config": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/debugger-frontend": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/debugger-frontend/-/debugger-frontend-0.88.0.tgz",
-      "integrity": "sha512-v5cnBaaWhDRPcQv8EC20zj53jOAKH7u2wnzzXS4JTNu+diPC+cA2+kC7rq3eKI5vGhlAcG2kDPoViRuC0AY0oA==",
-      "dev": true,
-      "license": "BSD-3-Clause",
-      "peer": true,
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/debugger-shell": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/debugger-shell/-/debugger-shell-0.88.0.tgz",
-      "integrity": "sha512-p82zT8ZKNx7nIm/8zf8pi55sxm5KQBm8td47kzoJysTdqHLyPsRMUvDXtvCJIWadHSv7RJ6t/yiCc+IoImLBtw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "cross-spawn": "^7.0.6",
-        "debug": "^4.4.0",
-        "fb-dotslash": "0.5.8"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/dev-middleware": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/dev-middleware/-/dev-middleware-0.88.0.tgz",
-      "integrity": "sha512-sHLxVHOwfkF672ZzMepNh4d3IKbrZy3qXDKWSwN5LC5VJkzzZ5FdmSPP4N/CCn2pcKJ4oSqvojXwN4De3Xk92A==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@isaacs/ttlcache": "^1.4.1",
-        "@react-native/debugger-frontend": "0.88.0",
-        "@react-native/debugger-shell": "0.88.0",
-        "connect": "^3.6.5",
-        "debug": "^4.4.0",
-        "invariant": "^2.2.4",
-        "nullthrows": "^1.1.1",
-        "open": "^8.4.2",
-        "serve-static": "^1.16.2",
-        "ws": "^7.5.10"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/dev-middleware/node_modules/ws": {
-      "version": "7.5.13",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.13.tgz",
-      "integrity": "sha512-rsKI6xDBFVf4r/x8XyChGK04QR/XHroxs/jUcoWvtEZM8TPU/X/uIY9B1CsSzYws9ZJb/6bbBu7dPhFW00CAoA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=8.3.0"
-      },
-      "peerDependencies": {
-        "bufferutil": "^4.0.1",
-        "utf-8-validate": "^5.0.2"
-      },
-      "peerDependenciesMeta": {
-        "bufferutil": {
-          "optional": true
-        },
-        "utf-8-validate": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/gradle-plugin": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/gradle-plugin/-/gradle-plugin-0.88.0.tgz",
-      "integrity": "sha512-4jPSKslOfJj8NKY/jv9qmWkxZYmqPyamoS3Vs0JOFxw9t4PM6L/ea0fUsjNV0LxC9zJlvWilPJOCTOf7h8wlyw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/js-polyfills": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/js-polyfills/-/js-polyfills-0.88.0.tgz",
-      "integrity": "sha512-Iq6v4+EWdOLv0M1+BpADQJBVfInl6FkABXCIBSi0FbvHahEYT+Y4UJ7Cm96p18gbEN1VKzqz3nbBbwLA6bx0rQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/metro-babel-transformer": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/metro-babel-transformer/-/metro-babel-transformer-0.88.0.tgz",
-      "integrity": "sha512-xsUfzXrqKXeD7sBja7hkyBG32AGIwWJ3IEZ+UcNMRTR/sucnXXZ6Do40qXoeY52YC8b9//J+p51JIp2CC0DZKA==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "@babel/core": "^7.25.2",
-        "@react-native/babel-preset": "0.88.0",
-        "flow-parser": "0.327.0",
-        "nullthrows": "^1.1.1"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      },
-      "peerDependencies": {
-        "@babel/core": "*"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/metro-babel-transformer/node_modules/flow-parser": {
-      "version": "0.327.0",
-      "resolved": "https://registry.npmjs.org/flow-parser/-/flow-parser-0.327.0.tgz",
-      "integrity": "sha512-/MYZ5hXWf5ozpbdfUDmazMgQXviLxWEiRLH3MppEGDdW0itRVqmB5UaU7QX+SBCDNiq+gEesSVn8nlxmPDyDkw==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "flow-estree": "0.327.0"
-      },
-      "engines": {
-        "node": ">=0.4.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/metro-config": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/metro-config/-/metro-config-0.88.0.tgz",
-      "integrity": "sha512-iPV2HNXlPs7xQDBJJGIjkH0x2psZwJeRIEpfSqxgqLaO5eEfE2Ccicfz2OBHBcIC5jKGGa4IoI/e26zMNDuTMQ==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "@react-native/js-polyfills": "0.88.0",
-        "@react-native/metro-babel-transformer": "0.88.0",
-        "metro-config": "^0.87.1",
-        "metro-runtime": "^0.87.1"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@react-native/normalize-colors": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/normalize-colors/-/normalize-colors-0.88.0.tgz",
-      "integrity": "sha512-eZCu3tGAQCfvMCPQJVY4dmoMX8ZZYBvqIGHX7lwOYyzNK+Dl8e5ky7ZoXub1Rq75oSrQXNNmSP2CDjNNXXZpFQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/@sinclair/typebox": {
-      "version": "0.34.49",
-      "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.34.49.tgz",
-      "integrity": "sha512-brySQQs7Jtn0joV8Xh9ZV/hZb9Ozb0pmazDIASBkYKCjXrXU3mpcFahmK/z4YDhGkQvP9mWJbVyahdtU5wQA+A==",
-      "dev": true,
-      "license": "MIT"
-    },
     "packages/expo-two-way-audio/node_modules/@types/react": {
       "version": "18.3.28",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.28.tgz",
@@ -39725,1390 +40173,6 @@
         "csstype": "^3.2.2"
       }
     },
-    "packages/expo-two-way-audio/node_modules/@typescript-eslint/scope-manager": {
-      "version": "8.61.1",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.61.1.tgz",
-      "integrity": "sha512-L2bdIeoQS8FlKAvONAr20w6OcLXeB+qiDKbAooS9A0Ben+iSIkBef0FxqwKWYqt5sa0i4KJtxVyVmhMylKzF5w==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@typescript-eslint/types": "8.61.1",
-        "@typescript-eslint/visitor-keys": "8.61.1"
-      },
-      "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/typescript-eslint"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@typescript-eslint/types": {
-      "version": "8.61.1",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.61.1.tgz",
-      "integrity": "sha512-G+CRlPqLv7Bz1IZVs03x5K59F1veqL0EJUROAdGhKsEq8qOiRiZbI+HUojPq5l0fEGOKModD9br6lObhB8zkoA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/typescript-eslint"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@typescript-eslint/visitor-keys": {
-      "version": "8.61.1",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.61.1.tgz",
-      "integrity": "sha512-6fJ9MHWtK14C1DSkiMlHUSOmrVebL7150xZJBlJiL62jjhIA4JmOq6flwBgDxIdBKKdoiZRel+dfPD5MLfny3w==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@typescript-eslint/types": "8.61.1",
-        "eslint-visitor-keys": "^5.0.0"
-      },
-      "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/typescript-eslint"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/@xmldom/xmldom": {
-      "version": "0.8.13",
-      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.8.13.tgz",
-      "integrity": "sha512-KRYzxepc14G/CEpEGc3Yn+JKaAeT63smlDr+vjB8jRfgTBBI9wRj/nkQEO+ucV8p8I9bfKLWp37uHgFrbntPvw==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=10.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/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",
-      "peer": true,
-      "engines": {
-        "node": ">= 14"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/ansi-styles": {
-      "version": "5.2.0",
-      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz",
-      "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/babel-plugin-react-native-web": {
-      "version": "0.21.4",
-      "resolved": "https://registry.npmjs.org/babel-plugin-react-native-web/-/babel-plugin-react-native-web-0.21.4.tgz",
-      "integrity": "sha512-FSclsDTGi5EcvpbW3TM7s8GLWwQqo5wI9zQqJr2m0IoJRenSkp1+bVvdeZXTNznI5Ms9Bry7DLBR+C5Shb9gtw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/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",
-      "integrity": "sha512-ycduwJbvdvIMmVvlAZqGggS+pm5Eu4Bk9pcV9Sm2Z4PJNRVsKkv0g7vHj+LeuC1gHTeF67sJXFOq61IlqCa2hA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "hermes-parser": "0.36.1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/babel-plugin-syntax-hermes-parser/node_modules/hermes-estree": {
-      "version": "0.36.1",
-      "resolved": "https://registry.npmjs.org/hermes-estree/-/hermes-estree-0.36.1.tgz",
-      "integrity": "sha512-guv1nQ6IJ7S83NRFPWc3SA7IBZrdNC9kapwOq6uXvF4wP+sDCgjzQbKPCoyYmoyZRzztF/n/c36l/rccCZSiCw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/babel-plugin-syntax-hermes-parser/node_modules/hermes-parser": {
-      "version": "0.36.1",
-      "resolved": "https://registry.npmjs.org/hermes-parser/-/hermes-parser-0.36.1.tgz",
-      "integrity": "sha512-GApNk4zLHi2UWoWZZkx7LNCOSzLSc5lB55pZ/PhK7ycFeg7u5LcF88p/WbpIi1XUDtE0MpHE3uRR3u3KB7TjSQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "hermes-estree": "0.36.1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/balanced-match": {
-      "version": "4.0.4",
-      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
-      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": "18 || 20 || >=22"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/brace-expansion": {
-      "version": "5.0.6",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.6.tgz",
-      "integrity": "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "balanced-match": "^4.0.2"
-      },
-      "engines": {
-        "node": "18 || 20 || >=22"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/cli-cursor": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-2.1.0.tgz",
-      "integrity": "sha512-8lgKz8LmCRYZZQDpRyT2m5rKJ08TnU4tR9FFFW2rxpxR1FzWi4PQ/NfyODchAatHaUgnSPVcx/R5w6NuTBzFiw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "restore-cursor": "^2.0.0"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/color-convert": {
-      "version": "1.9.3",
-      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz",
-      "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "color-name": "1.1.3"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/color-name": {
-      "version": "1.1.3",
-      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz",
-      "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/commander": {
-      "version": "12.1.0",
-      "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
-      "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/content-type": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz",
-      "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/express"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/escape-string-regexp": {
-      "version": "1.0.5",
-      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz",
-      "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=0.8.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-config-prettier": {
-      "version": "9.1.2",
-      "resolved": "https://registry.npmjs.org/eslint-config-prettier/-/eslint-config-prettier-9.1.2.tgz",
-      "integrity": "sha512-iI1f+D2ViGn+uvv5HuHVUamg8ll4tN+JRHGc6IJi4TP9Kl976C57fzPXgseXNs8v0iA8aSJpHsTWjDb9QJamGQ==",
-      "dev": true,
-      "license": "MIT",
-      "bin": {
-        "eslint-config-prettier": "bin/cli.js"
-      },
-      "peerDependencies": {
-        "eslint": ">=7.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-config-universe": {
-      "version": "15.2.0",
-      "resolved": "https://registry.npmjs.org/eslint-config-universe/-/eslint-config-universe-15.2.0.tgz",
-      "integrity": "sha512-n2662q/mM+2pTFVz7ELosqhN+/nbR75Ut/4vLme40kKSHHe0oPbPMxgPqyYrASlANuSDP4aAJ71rRviDMCZTxg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@typescript-eslint/eslint-plugin": "^8.59.0",
-        "@typescript-eslint/parser": "^8.59.0",
-        "eslint-config-prettier": "^9.1.0",
-        "eslint-plugin-import": "^2.31.0",
-        "eslint-plugin-n": "^17.17.0",
-        "eslint-plugin-node": "^11.1.0",
-        "eslint-plugin-prettier": "^5.2.6",
-        "eslint-plugin-react": "^7.37.5",
-        "eslint-plugin-react-hooks": "^7.0.0",
-        "globals": "^16.0.0"
-      },
-      "peerDependencies": {
-        "eslint": ">=8.10",
-        "prettier": ">=3"
-      },
-      "peerDependenciesMeta": {
-        "prettier": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-config-universe/node_modules/@typescript-eslint/eslint-plugin": {
-      "version": "8.61.1",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.61.1.tgz",
-      "integrity": "sha512-ZPlVl3PB3et/59Ne0fv/sci6ZXz4T4Hp4nTJ56i/Y0gR89ARb+KphojTq6j+56E5PIezmOIOOWyY+aWQFd+IkQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@eslint-community/regexpp": "^4.12.2",
-        "@typescript-eslint/scope-manager": "8.61.1",
-        "@typescript-eslint/type-utils": "8.61.1",
-        "@typescript-eslint/utils": "8.61.1",
-        "@typescript-eslint/visitor-keys": "8.61.1",
-        "ignore": "^7.0.5",
-        "natural-compare": "^1.4.0",
-        "ts-api-utils": "^2.5.0"
-      },
-      "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/typescript-eslint"
-      },
-      "peerDependencies": {
-        "@typescript-eslint/parser": "^8.61.1",
-        "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
-        "typescript": ">=4.8.4 <6.1.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-config-universe/node_modules/@typescript-eslint/parser": {
-      "version": "8.61.1",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.61.1.tgz",
-      "integrity": "sha512-PJ5vePq5/ognBbrIcoC5+SHO5dfpeLPzP9FpLkzWrguoYQEeeSjlJpVwOpo1JRSTEi7dRcwNy4h4dzV70PqHcg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@typescript-eslint/scope-manager": "8.61.1",
-        "@typescript-eslint/types": "8.61.1",
-        "@typescript-eslint/typescript-estree": "8.61.1",
-        "@typescript-eslint/visitor-keys": "8.61.1",
-        "debug": "^4.4.3"
-      },
-      "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/typescript-eslint"
-      },
-      "peerDependencies": {
-        "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
-        "typescript": ">=4.8.4 <6.1.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-config-universe/node_modules/@typescript-eslint/project-service": {
-      "version": "8.61.1",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.61.1.tgz",
-      "integrity": "sha512-PrC4JYGmR241lYnfhmKGTXkFqv8+ymbTFgSAY0fVXpY82/QkMw5TZPl+vGzuDDU2QYJk9fIDOBTntF+yDv9LEA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@typescript-eslint/tsconfig-utils": "^8.61.1",
-        "@typescript-eslint/types": "^8.61.1",
-        "debug": "^4.4.3"
-      },
-      "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/typescript-eslint"
-      },
-      "peerDependencies": {
-        "typescript": ">=4.8.4 <6.1.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-config-universe/node_modules/@typescript-eslint/tsconfig-utils": {
-      "version": "8.61.1",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.61.1.tgz",
-      "integrity": "sha512-UN/H4di+OO7EWx2ovME+8t31YO+KVnK0RRKEHR3kOt21/Ay8BOq3M1OMvWs5vNiqcFCYGYoxK3MXPZzmMUE+yg==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/typescript-eslint"
-      },
-      "peerDependencies": {
-        "typescript": ">=4.8.4 <6.1.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-config-universe/node_modules/@typescript-eslint/type-utils": {
-      "version": "8.61.1",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-8.61.1.tgz",
-      "integrity": "sha512-GYRicKmVK0C4fsKgaACaknOUAq9Oa2kwsjnpFhFcS/5p4Ht5IP9OVLbgIgcK4SRk92nVHFluurg1lumD9dBcLw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@typescript-eslint/types": "8.61.1",
-        "@typescript-eslint/typescript-estree": "8.61.1",
-        "@typescript-eslint/utils": "8.61.1",
-        "debug": "^4.4.3",
-        "ts-api-utils": "^2.5.0"
-      },
-      "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/typescript-eslint"
-      },
-      "peerDependencies": {
-        "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
-        "typescript": ">=4.8.4 <6.1.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-config-universe/node_modules/@typescript-eslint/typescript-estree": {
-      "version": "8.61.1",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.61.1.tgz",
-      "integrity": "sha512-u+oQD3BqYWPc8YV9Zab4vaJElJuwOLPRc10Jm1o/qS+6Qwen14HCWwx0Seo4LnSn2wxea2Ik8DxPt2/FHmuhrg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@typescript-eslint/project-service": "8.61.1",
-        "@typescript-eslint/tsconfig-utils": "8.61.1",
-        "@typescript-eslint/types": "8.61.1",
-        "@typescript-eslint/visitor-keys": "8.61.1",
-        "debug": "^4.4.3",
-        "minimatch": "^10.2.2",
-        "semver": "^7.7.3",
-        "tinyglobby": "^0.2.15",
-        "ts-api-utils": "^2.5.0"
-      },
-      "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/typescript-eslint"
-      },
-      "peerDependencies": {
-        "typescript": ">=4.8.4 <6.1.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-config-universe/node_modules/@typescript-eslint/utils": {
-      "version": "8.61.1",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-8.61.1.tgz",
-      "integrity": "sha512-1+P/3Dj6jvtybE1q0HQ6yBt/gq+oKJyLdEv4HdnqasaEXRSYCAsD59mXEVQnM/ULNdQxbX77tdG4jPRjIS6knA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@eslint-community/eslint-utils": "^4.9.1",
-        "@typescript-eslint/scope-manager": "8.61.1",
-        "@typescript-eslint/types": "8.61.1",
-        "@typescript-eslint/typescript-estree": "8.61.1"
-      },
-      "engines": {
-        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/typescript-eslint"
-      },
-      "peerDependencies": {
-        "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
-        "typescript": ">=4.8.4 <6.1.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-config-universe/node_modules/ts-api-utils": {
-      "version": "2.5.0",
-      "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.5.0.tgz",
-      "integrity": "sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=18.12"
-      },
-      "peerDependencies": {
-        "typescript": ">=4.8.4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-plugin-react-hooks": {
-      "version": "7.1.1",
-      "resolved": "https://registry.npmjs.org/eslint-plugin-react-hooks/-/eslint-plugin-react-hooks-7.1.1.tgz",
-      "integrity": "sha512-f2I7Gw6JbvCexzIInuSbZpfdQ44D7iqdWX01FKLvrPgqxoE7oMj8clOfto8U6vYiz4yd5oKu39rRSVOe1zRu0g==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@babel/core": "^7.24.4",
-        "@babel/parser": "^7.24.4",
-        "hermes-parser": "^0.25.1",
-        "zod": "^3.25.0 || ^4.0.0",
-        "zod-validation-error": "^3.5.0 || ^4.0.0"
-      },
-      "engines": {
-        "node": ">=18"
-      },
-      "peerDependencies": {
-        "eslint": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0 || ^10.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/eslint-visitor-keys": {
-      "version": "5.0.1",
-      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-5.0.1.tgz",
-      "integrity": "sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==",
-      "dev": true,
-      "license": "Apache-2.0",
-      "engines": {
-        "node": "^20.19.0 || ^22.13.0 || >=24"
-      },
-      "funding": {
-        "url": "https://opencollective.com/eslint"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-asset": {
-      "version": "58.0.16",
-      "resolved": "https://registry.npmjs.org/expo-asset/-/expo-asset-58.0.16.tgz",
-      "integrity": "sha512-beR3uusLA+rFo+6Ug0L7FPR4b6y/37VwtYW2Jig/i+3Co+oyYCTnvVuFPWhb05W9TOZRxdHUEI569fVKIgtYAA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/image-utils": "^0.12.5",
-        "expo-constants": "~58.0.12"
-      },
-      "peerDependencies": {
-        "expo": "*",
-        "react": "*",
-        "react-native": "*"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-constants": {
-      "version": "58.0.12",
-      "resolved": "https://registry.npmjs.org/expo-constants/-/expo-constants-58.0.12.tgz",
-      "integrity": "sha512-d3/dsps32nU4m6YJQbXQ1dIfn58GxfmJjTnZ0WtnhdSHTdG/oVsOakLqYRlX/FaLUKkQOSHXMf7hyCx+2a/HSQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/env": "~2.5.2",
-        "@expo/require-utils": "^58.0.4"
-      },
-      "peerDependencies": {
-        "expo": "*",
-        "react-native": "*"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-constants/node_modules/@expo/require-utils": {
-      "version": "58.0.4",
-      "resolved": "https://registry.npmjs.org/@expo/require-utils/-/require-utils-58.0.4.tgz",
-      "integrity": "sha512-DvjS5NCitXYcad2Woe1EMHJKcbhTbE77HX0BgOQGL2LFHE3q2H0n8kCWDPBOCVJ63Drap3c35nwoJwF5TQL7Tw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "@babel/core": "^7.25.2",
-        "@babel/plugin-transform-modules-commonjs": "^7.24.8"
-      },
-      "peerDependencies": {
-        "typescript": "^5.0.0 || ^5.0.0-0 || ^6.0.0 || ^7.0.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-file-system": {
-      "version": "58.0.9",
-      "resolved": "https://registry.npmjs.org/expo-file-system/-/expo-file-system-58.0.9.tgz",
-      "integrity": "sha512-JT0km3Wa+wDz/7Rli8ifreoMnmk68ulf/uaWzRA26xm/4K+jGTY+cDhnboRmpmXUCBkED6uqxWmNoXjaVU9VUw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "peerDependencies": {
-        "expo": "*",
-        "react-native": "*"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-font": {
-      "version": "58.0.8",
-      "resolved": "https://registry.npmjs.org/expo-font/-/expo-font-58.0.8.tgz",
-      "integrity": "sha512-i9HKj/ljdmmjLamYQEkI4wXJB9+ap7AG5CpCqK/bgwwy45y5T8+1lpNbYgRXE7aQgmDjPpzd09wX6dOZkHfrxg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "peerDependencies": {
-        "expo": "*",
-        "react": "*",
-        "react-native": "*"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-keep-awake": {
-      "version": "58.0.3",
-      "resolved": "https://registry.npmjs.org/expo-keep-awake/-/expo-keep-awake-58.0.3.tgz",
-      "integrity": "sha512-wLRF+XeVsD/Rt/ZyX+A0mk1brdf8vefWizNAPzqV5eOCgkj23LCRZdN8gUi5X8UwyR8UJ7Y7Dzdz4YDGB/4c9Q==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "peerDependencies": {
-        "expo": "*",
-        "react": "*"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts": {
-      "version": "5.0.8",
-      "resolved": "https://registry.npmjs.org/expo-module-scripts/-/expo-module-scripts-5.0.8.tgz",
-      "integrity": "sha512-3YkAic3E6QGQuNEIchq6/0GGSBwR2C70AhDUF7VI7/N3THwUpeqZrX20FxHKN95/wclHs1ljrGvRX+2YTgXxiw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@babel/cli": "^7.23.4",
-        "@babel/plugin-transform-export-namespace-from": "^7.23.4",
-        "@babel/preset-env": "^7.23.8",
-        "@babel/preset-typescript": "^7.23.3",
-        "@expo/npm-proofread": "^1.0.1",
-        "@testing-library/react-native": "^13.2.0",
-        "@tsconfig/node18": "^18.2.2",
-        "@types/jest": "^29.2.1",
-        "babel-plugin-dynamic-import-node": "^2.3.3",
-        "babel-preset-expo": "~54.0.7",
-        "commander": "^12.1.0",
-        "eslint-config-universe": "^15.0.3",
-        "glob": "^13.0.0",
-        "jest-expo": "~54.0.13",
-        "jest-snapshot-prettier": "npm:prettier@^2",
-        "jest-watch-typeahead": "2.2.1",
-        "resolve-workspace-root": "^2.0.0",
-        "ts-jest": "~29.0.4",
-        "typescript": "^5.9.2"
-      },
-      "bin": {
-        "expo-module": "bin/expo-module.js"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@expo/config-plugins": {
-      "version": "58.0.9",
-      "resolved": "https://registry.npmjs.org/@expo/config-plugins/-/config-plugins-58.0.9.tgz",
-      "integrity": "sha512-HyP7V1QgDxeHcOEh4qQH7cfK7cI7wNp0y9lszAu98SRYCshhDbwB9gWpFfnpX1GQUtgiqG4Hvgh1z3ntcGwAjw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config-types": "^58.0.3",
-        "@expo/json-file": "~11.2.1",
-        "@expo/plist": "^0.10.1",
-        "@expo/require-utils": "^58.0.4",
-        "@expo/sdk-runtime-versions": "^1.0.1",
-        "chalk": "^4.1.2",
-        "debug": "^4.3.5",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "semver": "^7.7.4",
-        "slugify": "^1.6.6",
-        "xcode": "^3.0.1",
-        "xml2js": "0.6.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@expo/config-plugins/node_modules/@expo/json-file": {
-      "version": "11.2.1",
-      "resolved": "https://registry.npmjs.org/@expo/json-file/-/json-file-11.2.1.tgz",
-      "integrity": "sha512-UPhKoFCj8BcwgLB1rKQ1CuR/REITnZLiqxHEHOeH1tPsdXcHGtUDh0P5bLbr7oU0nKVdtJ5rzyKx8jniMQdESQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "json5": "^2.2.3"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@expo/config-plugins/node_modules/@expo/require-utils": {
-      "version": "58.0.4",
-      "resolved": "https://registry.npmjs.org/@expo/require-utils/-/require-utils-58.0.4.tgz",
-      "integrity": "sha512-DvjS5NCitXYcad2Woe1EMHJKcbhTbE77HX0BgOQGL2LFHE3q2H0n8kCWDPBOCVJ63Drap3c35nwoJwF5TQL7Tw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "@babel/core": "^7.25.2",
-        "@babel/plugin-transform-modules-commonjs": "^7.24.8"
-      },
-      "peerDependencies": {
-        "typescript": "^5.0.0 || ^5.0.0-0 || ^6.0.0 || ^7.0.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@expo/config-types": {
-      "version": "58.0.3",
-      "resolved": "https://registry.npmjs.org/@expo/config-types/-/config-types-58.0.3.tgz",
-      "integrity": "sha512-wyfrwkTT/hQHzwyqkXkngKxoOa8L6ovsTP4h/UukS1mTmssee5et6HOPoN5RtawdJPnm5JO28f//C/wXlpka8Q==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@expo/metro-runtime": {
-      "version": "58.0.14",
-      "resolved": "https://registry.npmjs.org/@expo/metro-runtime/-/metro-runtime-58.0.14.tgz",
-      "integrity": "sha512-IIvTo+RpN5jZVuYspQdECsxQ03VGWjZnGS6wtr9U7DERBpykUe+ZSHDZ1hsrvQ7HAucsVoKr9np0xAscGEuXtg==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "@expo/log-box": "^58.0.12",
-        "anser": "^1.4.9",
-        "pretty-format": "^29.7.0",
-        "stacktrace-parser": "^0.1.10",
-        "whatwg-fetch": "^3.0.0"
-      },
-      "peerDependencies": {
-        "@expo/log-box": "^58.0.12",
-        "expo": "*",
-        "react": "*",
-        "react-dom": "*",
-        "react-native": "*"
-      },
-      "peerDependenciesMeta": {
-        "react-dom": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@expo/metro-runtime/node_modules/pretty-format": {
-      "version": "29.7.0",
-      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-29.7.0.tgz",
-      "integrity": "sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "@jest/schemas": "^29.6.3",
-        "ansi-styles": "^5.0.0",
-        "react-is": "^18.0.0"
-      },
-      "engines": {
-        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@expo/plist": {
-      "version": "0.10.1",
-      "resolved": "https://registry.npmjs.org/@expo/plist/-/plist-0.10.1.tgz",
-      "integrity": "sha512-nuNOqj+r/hGJbZ1Ax3jUpZaOB8UAMHUrISALJEUKaCieTflYj7224EqFWmMpriCGk9wXS1gH+9GGVnSj0tWzuQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@xmldom/xmldom": "^0.8.8",
-        "base64-js": "^1.5.1",
-        "xmlbuilder": "^15.1.1"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@jest/schemas": {
-      "version": "29.6.3",
-      "resolved": "https://registry.npmjs.org/@jest/schemas/-/schemas-29.6.3.tgz",
-      "integrity": "sha512-mo5j5X+jIZmJQveBKeS/clAueipV7KgiX1vMgCxam1RNYiqE1w62n0/tJJnHtjW8ZHcQco5gY85jA3mi0L+nSA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@sinclair/typebox": "^0.27.8"
-      },
-      "engines": {
-        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@react-native/virtualized-lists": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/@react-native/virtualized-lists/-/virtualized-lists-0.88.0.tgz",
-      "integrity": "sha512-zpZIOAbobdS93edwHkNUdGDzvElNeQJqukRERRPns3/ucPvuMd2G4fYpmVJSVjhxtGCcLLB1PFndLYYfwaYoBQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "invariant": "^2.2.4",
-        "nullthrows": "^1.1.1"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      },
-      "peerDependencies": {
-        "@types/react": "^19.2.0",
-        "react": "*",
-        "react-native": "0.88.0"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@sinclair/typebox": {
-      "version": "0.27.12",
-      "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.27.12.tgz",
-      "integrity": "sha512-hhyNJ+nbR6ZR7pToHvllEFun9TL0sbL+tk/ON75lo+Xas054uez98qRbsuNt7MBCyZKK4+8Yli/OAGZhmfBZ/g==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@testing-library/react-native": {
-      "version": "13.3.3",
-      "resolved": "https://registry.npmjs.org/@testing-library/react-native/-/react-native-13.3.3.tgz",
-      "integrity": "sha512-k6Mjsd9dbZgvY4Bl7P1NIpePQNi+dfYtlJ5voi9KQlynxSyQkfOgJmYGCYmw/aSgH/rUcFvG8u5gd4npzgRDyg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "jest-matcher-utils": "^30.0.5",
-        "picocolors": "^1.1.1",
-        "pretty-format": "^30.0.5",
-        "redent": "^3.0.0"
-      },
-      "engines": {
-        "node": ">=18"
-      },
-      "peerDependencies": {
-        "jest": ">=29.0.0",
-        "react": ">=18.2.0",
-        "react-native": ">=0.71",
-        "react-test-renderer": ">=18.2.0"
-      },
-      "peerDependenciesMeta": {
-        "jest": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/@types/react": {
-      "version": "19.3.0",
-      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.3.0.tgz",
-      "integrity": "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "csstype": "^3.2.2"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/expo": {
-      "version": "58.0.14",
-      "resolved": "https://registry.npmjs.org/expo/-/expo-58.0.14.tgz",
-      "integrity": "sha512-M05O++KRgG4NA6kQ9AP60kbN8xqHJ6S8uTXdtkeiwcGVIYzdu2kaUXJyraVturvePO/Mf4PWa0C9+JggrHITwA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/runtime": "^7.20.0",
-        "@expo/cli": "^58.1.11",
-        "@expo/config": "~58.0.6",
-        "@expo/config-plugins": "~58.0.9",
-        "@expo/devtools": "~58.0.2",
-        "@expo/dom-webview": "~58.0.2",
-        "@expo/fingerprint": "^0.21.5",
-        "@expo/local-build-cache-provider": "^58.0.6",
-        "@expo/log-box": "^58.0.12",
-        "@expo/log-box-utils": "^58.0.2",
-        "@expo/metro": "~58.0.0",
-        "@expo/metro-config": "~58.0.14",
-        "@ungap/structured-clone": "^1.3.0",
-        "babel-preset-expo": "~58.0.17",
-        "expo-asset": "~58.0.16",
-        "expo-constants": "~58.0.12",
-        "expo-file-system": "~58.0.9",
-        "expo-font": "~58.0.8",
-        "expo-keep-awake": "~58.0.3",
-        "expo-modules-autolinking": "~58.0.13",
-        "expo-modules-core": "~58.0.22",
-        "pretty-format": "^29.7.0",
-        "react-refresh": "^0.14.2",
-        "whatwg-url-minimum": "^0.2.0"
-      },
-      "bin": {
-        "expo": "bin/cli",
-        "expo-modules-autolinking": "bin/autolinking",
-        "fingerprint": "bin/fingerprint"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || ^26.0.0 || >=27.0.0"
-      },
-      "peerDependencies": {
-        "@expo/dom-webview": "*",
-        "@expo/metro-runtime": "*",
-        "react": "*",
-        "react-dom": "*",
-        "react-native": "*",
-        "react-native-web": "*",
-        "react-native-webview": "*"
-      },
-      "peerDependenciesMeta": {
-        "@expo/dom-webview": {
-          "optional": true
-        },
-        "@expo/metro-runtime": {
-          "optional": true
-        },
-        "react-dom": {
-          "optional": true
-        },
-        "react-native-web": {
-          "optional": true
-        },
-        "react-native-webview": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/expo-modules-core": {
-      "version": "58.0.22",
-      "resolved": "https://registry.npmjs.org/expo-modules-core/-/expo-modules-core-58.0.22.tgz",
-      "integrity": "sha512-T3YJYziFkF4JlGDpX4zCl91oIxz1Skq5sp1LFVO+GL/BARSIXk013QWGdRZrvt+wMxoVaql5dpOdPdP5q2+0jQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "expo-modules-jsi": "~58.0.15",
-        "expo-modules-macros": "0.20.0",
-        "invariant": "^2.2.4"
-      },
-      "peerDependencies": {
-        "react": "*",
-        "react-native": "*",
-        "react-native-worklets": ">=0.13.0"
-      },
-      "peerDependenciesMeta": {
-        "react-native-worklets": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/expo/node_modules/@expo/cli": {
-      "version": "58.1.11",
-      "resolved": "https://registry.npmjs.org/@expo/cli/-/cli-58.1.11.tgz",
-      "integrity": "sha512-wkFTSLXXYqLkRT5oy4DnLuTOtbFIu3qTiXHSHkFSqUBTHiE92y3bOIwM3UN7Y1ys18qVJge8lXjezaEfsHmijQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/code-signing-certificates": "^0.0.7",
-        "@expo/config": "~58.0.6",
-        "@expo/config-plugins": "~58.0.9",
-        "@expo/devcert": "^1.2.2",
-        "@expo/env": "~2.5.2",
-        "@expo/image-utils": "^0.12.5",
-        "@expo/inline-modules": "^0.2.6",
-        "@expo/json-file": "^11.2.1",
-        "@expo/log-box": "^58.0.12",
-        "@expo/log-box-utils": "^58.0.2",
-        "@expo/metro": "~58.0.0",
-        "@expo/metro-config": "58.0.14",
-        "@expo/metro-file-map": "^58.0.5",
-        "@expo/osascript": "^2.8.1",
-        "@expo/package-manager": "^1.14.2",
-        "@expo/platforms": "^58.0.1",
-        "@expo/plist": "^0.10.1",
-        "@expo/prebuild-config": "^58.0.14",
-        "@expo/require-utils": "^58.0.4",
-        "@expo/router-server": "^58.0.14",
-        "@expo/schema-utils": "^58.0.2",
-        "@expo/spawn-async": "^1.8.0",
-        "@expo/ws-tunnel": "^2.0.1",
-        "@expo/xcpretty": "^4.4.6",
-        "@react-native/asset-utils": "0.88.0",
-        "@react-native/dev-middleware": "0.88.0",
-        "@react-native/js-polyfills": "0.88.0",
-        "2g": "^1.0.1",
-        "accepts": "^1.3.8",
-        "agent-cli-detector": "0.1.7",
-        "arg": "^5.0.2",
-        "bplist-creator": "0.1.0",
-        "bplist-parser": "^0.3.1",
-        "chalk": "^4.0.0",
-        "ci-info": "^3.3.0",
-        "compression": "^1.7.4",
-        "connect": "^3.7.0",
-        "dnssd-advertise": "^1.1.6",
-        "expo-server": "^58.0.5",
-        "fetch-nodeshim": "^0.4.10",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "lan-network": "^0.2.1",
-        "multitars": "^1.0.2",
-        "node-forge": "^1.4.0",
-        "npm-package-arg": "^11.0.0",
-        "ora": "^3.4.0",
-        "picomatch": "^4.0.4",
-        "pretty-format": "^29.7.0",
-        "progress": "^2.0.3",
-        "prompts": "^2.3.2",
-        "resolve-from": "^5.0.0",
-        "sandbox-cli-detector": "^0.2.0",
-        "semver": "^7.7.4",
-        "send": "^0.19.0",
-        "slugify": "^1.3.4",
-        "stacktrace-parser": "^0.1.10",
-        "structured-headers": "^0.4.1",
-        "terminal-link": "^2.1.1",
-        "toqr": "^0.1.1",
-        "wrap-ansi": "^7.0.0",
-        "ws": "^8.12.1",
-        "zod": "^3.25.76"
-      },
-      "bin": {
-        "expo-internal": "bin/cli.js"
-      },
-      "peerDependencies": {
-        "expo": "*",
-        "expo-router": "*",
-        "react-native": "*"
-      },
-      "peerDependenciesMeta": {
-        "expo-router": {
-          "optional": true
-        },
-        "react-native": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/expo/node_modules/@expo/cli/node_modules/@expo/router-server": {
-      "version": "58.0.14",
-      "resolved": "https://registry.npmjs.org/@expo/router-server/-/router-server-58.0.14.tgz",
-      "integrity": "sha512-RSzQYMA+Tv2eTemhjhzpx8+hL+pMC30JTVqAWrk5AZwht+OgaKZar/gHmj4iJf7n3rq+GG6KujrkKF9xAXLz2w==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "debug": "^4.3.4"
-      },
-      "peerDependencies": {
-        "@expo/metro-runtime": "^58.0.14",
-        "expo": "*",
-        "expo-constants": "^58.0.12",
-        "expo-font": "^58.0.8",
-        "expo-router": "*",
-        "expo-server": "^58.0.5",
-        "react": "*",
-        "react-dom": "*",
-        "react-server-dom-webpack": "~19.0.1 || ~19.1.2 || ~19.2.1 || ~19.3.0"
-      },
-      "peerDependenciesMeta": {
-        "@expo/metro-runtime": {
-          "optional": true
-        },
-        "expo-router": {
-          "optional": true
-        },
-        "react-dom": {
-          "optional": true
-        },
-        "react-server-dom-webpack": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/expo/node_modules/@expo/config": {
-      "version": "58.0.6",
-      "resolved": "https://registry.npmjs.org/@expo/config/-/config-58.0.6.tgz",
-      "integrity": "sha512-PT1qv4s/R5A/NxXb4efGlFsYF5Consi7F8xSsJBAN090EGDr6U1EDQGOijFqzDc3JA2epD8zjKLJLOVB9YOewg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/config-plugins": "~58.0.9",
-        "@expo/config-types": "^58.0.3",
-        "@expo/json-file": "^11.2.1",
-        "@expo/platforms": "^58.0.1",
-        "@expo/require-utils": "^58.0.4",
-        "deepmerge": "^4.3.1",
-        "getenv": "^2.0.0",
-        "glob": "^13.0.0",
-        "resolve-workspace-root": "^2.0.0",
-        "semver": "^7.7.4",
-        "slugify": "^1.3.4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/expo/node_modules/@expo/json-file": {
-      "version": "11.2.1",
-      "resolved": "https://registry.npmjs.org/@expo/json-file/-/json-file-11.2.1.tgz",
-      "integrity": "sha512-UPhKoFCj8BcwgLB1rKQ1CuR/REITnZLiqxHEHOeH1tPsdXcHGtUDh0P5bLbr7oU0nKVdtJ5rzyKx8jniMQdESQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "json5": "^2.2.3"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/expo/node_modules/@expo/require-utils": {
-      "version": "58.0.4",
-      "resolved": "https://registry.npmjs.org/@expo/require-utils/-/require-utils-58.0.4.tgz",
-      "integrity": "sha512-DvjS5NCitXYcad2Woe1EMHJKcbhTbE77HX0BgOQGL2LFHE3q2H0n8kCWDPBOCVJ63Drap3c35nwoJwF5TQL7Tw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "@babel/core": "^7.25.2",
-        "@babel/plugin-transform-modules-commonjs": "^7.24.8"
-      },
-      "peerDependencies": {
-        "typescript": "^5.0.0 || ^5.0.0-0 || ^6.0.0 || ^7.0.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/expo/node_modules/2g": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/2g/-/2g-1.0.1.tgz",
-      "integrity": "sha512-+uViadKOS/wwR4pFu5g8TPn3QHpKqoX19JHCnp8k/3cLpImdcXozwvZA6Q/5PeW3AcU8neL8faaMidBcv7o8CA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "bin": {
-        "2g": "bin/cli.js"
-      },
-      "peerDependencies": {
-        "typescript": ">=5.8.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/expo/node_modules/babel-preset-expo": {
-      "version": "58.0.17",
-      "resolved": "https://registry.npmjs.org/babel-preset-expo/-/babel-preset-expo-58.0.17.tgz",
-      "integrity": "sha512-Rrqc/Z5Idc4bG2/PrEh725t3kvuAc7jUKCJ+wZVU9KXk2bKSdqAniXxQa8aph9aHdv4h5sGKLpMXMaMNz/4+Og==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/generator": "^7.20.5",
-        "@babel/helper-module-imports": "^7.25.9",
-        "@babel/plugin-proposal-decorators": "^7.12.9",
-        "@babel/plugin-proposal-export-default-from": "^7.24.7",
-        "@babel/plugin-syntax-dynamic-import": "^7.8.3",
-        "@babel/plugin-syntax-export-default-from": "^7.24.7",
-        "@babel/plugin-syntax-nullish-coalescing-operator": "^7.8.3",
-        "@babel/plugin-syntax-optional-chaining": "^7.8.3",
-        "@babel/plugin-transform-async-generator-functions": "^7.25.4",
-        "@babel/plugin-transform-async-to-generator": "^7.24.7",
-        "@babel/plugin-transform-block-scoping": "^7.25.0",
-        "@babel/plugin-transform-class-properties": "^7.25.4",
-        "@babel/plugin-transform-class-static-block": "^7.27.1",
-        "@babel/plugin-transform-classes": "^7.25.4",
-        "@babel/plugin-transform-destructuring": "^7.24.8",
-        "@babel/plugin-transform-export-namespace-from": "^7.25.9",
-        "@babel/plugin-transform-flow-strip-types": "^7.25.2",
-        "@babel/plugin-transform-for-of": "^7.24.7",
-        "@babel/plugin-transform-logical-assignment-operators": "^7.24.7",
-        "@babel/plugin-transform-modules-commonjs": "^7.24.8",
-        "@babel/plugin-transform-named-capturing-groups-regex": "^7.24.7",
-        "@babel/plugin-transform-nullish-coalescing-operator": "^7.24.7",
-        "@babel/plugin-transform-object-rest-spread": "^7.24.7",
-        "@babel/plugin-transform-optional-catch-binding": "^7.24.7",
-        "@babel/plugin-transform-optional-chaining": "^7.24.8",
-        "@babel/plugin-transform-parameters": "^7.24.7",
-        "@babel/plugin-transform-private-methods": "^7.24.7",
-        "@babel/plugin-transform-private-property-in-object": "^7.24.7",
-        "@babel/plugin-transform-react-display-name": "^7.24.7",
-        "@babel/plugin-transform-react-jsx": "^7.28.6",
-        "@babel/plugin-transform-react-jsx-development": "^7.27.1",
-        "@babel/plugin-transform-react-pure-annotations": "^7.27.1",
-        "@babel/plugin-transform-runtime": "^7.24.7",
-        "@babel/plugin-transform-typescript": "^7.25.2",
-        "@babel/plugin-transform-unicode-regex": "^7.24.7",
-        "@babel/preset-typescript": "^7.23.0",
-        "@react-native/babel-plugin-codegen": "0.88.0",
-        "babel-plugin-react-compiler": "^1.0.0",
-        "babel-plugin-react-native-web": "~0.21.4",
-        "babel-plugin-syntax-hermes-parser": "^0.36.0",
-        "babel-plugin-transform-flow-enums": "^0.0.2",
-        "debug": "^4.3.4"
-      },
-      "peerDependencies": {
-        "@babel/runtime": "^7.20.0",
-        "expo": "*",
-        "expo-widgets": "^58.0.20",
-        "react-refresh": ">=0.14.0 <1.0.0"
-      },
-      "peerDependenciesMeta": {
-        "@babel/runtime": {
-          "optional": true
-        },
-        "expo": {
-          "optional": true
-        },
-        "expo-widgets": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/expo/node_modules/pretty-format": {
-      "version": "29.7.0",
-      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-29.7.0.tgz",
-      "integrity": "sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@jest/schemas": "^29.6.3",
-        "ansi-styles": "^5.0.0",
-        "react-is": "^18.0.0"
-      },
-      "engines": {
-        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/flow-parser": {
-      "version": "0.327.0",
-      "resolved": "https://registry.npmjs.org/flow-parser/-/flow-parser-0.327.0.tgz",
-      "integrity": "sha512-/MYZ5hXWf5ozpbdfUDmazMgQXviLxWEiRLH3MppEGDdW0itRVqmB5UaU7QX+SBCDNiq+gEesSVn8nlxmPDyDkw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "flow-estree": "0.327.0"
-      },
-      "engines": {
-        "node": ">=0.4.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/jest-expo": {
-      "version": "54.0.17",
-      "resolved": "https://registry.npmjs.org/jest-expo/-/jest-expo-54.0.17.tgz",
-      "integrity": "sha512-LyIhrsP4xvHEEcR1R024u/LBj3uPpAgB+UljgV+YXWkEHjprnr0KpE4tROsMNYCVTM1pPlAnPuoBmn5gnAN9KA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@expo/config": "~12.0.13",
-        "@expo/json-file": "^10.0.8",
-        "@jest/create-cache-key-function": "^29.2.1",
-        "@jest/globals": "^29.2.1",
-        "babel-jest": "^29.2.1",
-        "jest-environment-jsdom": "^29.2.1",
-        "jest-snapshot": "^29.2.1",
-        "jest-watch-select-projects": "^2.0.0",
-        "jest-watch-typeahead": "2.2.1",
-        "json5": "^2.2.3",
-        "lodash": "^4.17.19",
-        "react-test-renderer": "19.1.0",
-        "server-only": "^0.0.1",
-        "stacktrace-js": "^2.0.2"
-      },
-      "bin": {
-        "jest": "bin/jest.js"
-      },
-      "peerDependencies": {
-        "expo": "*",
-        "react-native": "*",
-        "react-server-dom-webpack": "~19.0.4 || ~19.1.5 || ~19.2.4"
-      },
-      "peerDependenciesMeta": {
-        "react-server-dom-webpack": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/react-is": {
-      "version": "18.3.1",
-      "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz",
-      "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/react-native": {
-      "version": "0.88.0",
-      "resolved": "https://registry.npmjs.org/react-native/-/react-native-0.88.0.tgz",
-      "integrity": "sha512-v/wee0nYWcammMYBnSat/e3WY/5iaf9YQOMcBrfKT/wPApPPlHp94hgZovBtwhMuthR01yc/8cGn0FpFTE/C4A==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@react-native/asset-utils": "0.88.0",
-        "@react-native/codegen": "0.88.0",
-        "@react-native/community-cli-plugin": "0.88.0",
-        "@react-native/gradle-plugin": "0.88.0",
-        "@react-native/normalize-colors": "0.88.0",
-        "@react-native/virtualized-lists": "0.88.0",
-        "anser": "^1.4.9",
-        "ansi-regex": "^5.0.0",
-        "base64-js": "^1.5.1",
-        "flow-enums-runtime": "^0.0.6",
-        "flow-parser": "0.327.0",
-        "hermes-compiler": "260318099.0.4",
-        "invariant": "^2.2.4",
-        "memoize-one": "^5.0.0",
-        "metro-runtime": "^0.87.1",
-        "metro-source-map": "^0.87.1",
-        "nullthrows": "^1.1.1",
-        "pretty-format": "^29.7.0",
-        "promise": "^8.3.0",
-        "react-devtools-core": "^6.1.5",
-        "react-refresh": "^0.14.0",
-        "regenerator-runtime": "^0.13.2",
-        "scheduler": "0.28.0",
-        "semver": "^7.1.3",
-        "stacktrace-parser": "^0.1.10",
-        "tinyglobby": "^0.2.15",
-        "whatwg-fetch": "^3.0.0",
-        "ws": "^7.5.10",
-        "yargs": "^17.6.2"
-      },
-      "bin": {
-        "react-native": "cli.js"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      },
-      "peerDependencies": {
-        "@types/react": "^19.1.1",
-        "react": "^19.3.0"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/react-native/node_modules/pretty-format": {
-      "version": "29.7.0",
-      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-29.7.0.tgz",
-      "integrity": "sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@jest/schemas": "^29.6.3",
-        "ansi-styles": "^5.0.0",
-        "react-is": "^18.0.0"
-      },
-      "engines": {
-        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/react-native/node_modules/ws": {
-      "version": "7.5.13",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.13.tgz",
-      "integrity": "sha512-rsKI6xDBFVf4r/x8XyChGK04QR/XHroxs/jUcoWvtEZM8TPU/X/uIY9B1CsSzYws9ZJb/6bbBu7dPhFW00CAoA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=8.3.0"
-      },
-      "peerDependencies": {
-        "bufferutil": "^4.0.1",
-        "utf-8-validate": "^5.0.2"
-      },
-      "peerDependenciesMeta": {
-        "bufferutil": {
-          "optional": true
-        },
-        "utf-8-validate": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-module-scripts/node_modules/scheduler": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.28.0.tgz",
-      "integrity": "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/expo-modules-autolinking": {
-      "version": "58.0.13",
-      "resolved": "https://registry.npmjs.org/expo-modules-autolinking/-/expo-modules-autolinking-58.0.13.tgz",
-      "integrity": "sha512-uzLFoTnAKabUdITvzRqWTvFkZsOdRPEXj7AEMAuBEhA2kGhqaBDa2EOWqPXVay0QJVoZuIQaEEgPGAXN1dPuYg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@expo/platforms": "^58.0.1",
-        "@expo/require-utils": "^58.0.4",
-        "@expo/spawn-async": "^1.8.0",
-        "chalk": "^4.1.0",
-        "commander": "^7.2.0"
-      },
-      "bin": {
-        "expo-modules-autolinking": "bin/expo-modules-autolinking.js"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-modules-autolinking/node_modules/@expo/require-utils": {
-      "version": "58.0.4",
-      "resolved": "https://registry.npmjs.org/@expo/require-utils/-/require-utils-58.0.4.tgz",
-      "integrity": "sha512-DvjS5NCitXYcad2Woe1EMHJKcbhTbE77HX0BgOQGL2LFHE3q2H0n8kCWDPBOCVJ63Drap3c35nwoJwF5TQL7Tw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.20.0",
-        "@babel/core": "^7.25.2",
-        "@babel/plugin-transform-modules-commonjs": "^7.24.8"
-      },
-      "peerDependencies": {
-        "typescript": "^5.0.0 || ^5.0.0-0 || ^6.0.0 || ^7.0.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-modules-autolinking/node_modules/commander": {
-      "version": "7.2.0",
-      "resolved": "https://registry.npmjs.org/commander/-/commander-7.2.0.tgz",
-      "integrity": "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">= 10"
-      }
-    },
     "packages/expo-two-way-audio/node_modules/expo-modules-core": {
       "version": "2.5.0",
       "resolved": "https://registry.npmjs.org/expo-modules-core/-/expo-modules-core-2.5.0.tgz",
@@ -41119,770 +40183,6 @@
         "invariant": "^2.2.4"
       }
     },
-    "packages/expo-two-way-audio/node_modules/expo-modules-jsi": {
-      "version": "58.0.15",
-      "resolved": "https://registry.npmjs.org/expo-modules-jsi/-/expo-modules-jsi-58.0.15.tgz",
-      "integrity": "sha512-PsjYgL4KWtvBqWH242r0wbP99VjgHkHCpkPCekO7nzb+ulkDNyrNnhysxa0TcNpfRTNLetmCUaLs9t4CcoquZQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "peerDependencies": {
-        "react-native": "*"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/expo-server": {
-      "version": "58.0.5",
-      "resolved": "https://registry.npmjs.org/expo-server/-/expo-server-58.0.5.tgz",
-      "integrity": "sha512-FHYecxfGOuAhacHcanR6qCN8Cln9S+FFulcYetLu3ddDg55ohuCsMZ9U4Egzwdm+A2o6N+MdSoJKquBC5F9NIg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || ^26.0.0 || >=27.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/flow-estree": {
-      "version": "0.327.0",
-      "resolved": "https://registry.npmjs.org/flow-estree/-/flow-estree-0.327.0.tgz",
-      "integrity": "sha512-f9vK751YUzD0qaHSpKc5/qQM6gqOlgGS+4ZRqTNcZOpVqn3mC55yEQ6dUG2K1eaVm5FbKkz9CFWe6XNvrkQFQg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/getenv": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/getenv/-/getenv-2.0.0.tgz",
-      "integrity": "sha512-VilgtJj/ALgGY77fiLam5iD336eSWi96Q15JSAG1zi8NRBysm3LXKdGnHb4m5cuyxvOLQQKWpBZAT6ni4FI2iQ==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=6"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/glob": {
-      "version": "13.0.6",
-      "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz",
-      "integrity": "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "minimatch": "^10.2.2",
-        "minipass": "^7.1.3",
-        "path-scurry": "^2.0.2"
-      },
-      "engines": {
-        "node": "18 || 20 || >=22"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/globals": {
-      "version": "16.5.0",
-      "resolved": "https://registry.npmjs.org/globals/-/globals-16.5.0.tgz",
-      "integrity": "sha512-c/c15i26VrJ4IRt5Z89DnIzCGDn9EcebibhAOjw5ibqEHsE1wLUgkPn9RDmNcUKyU87GeaL633nyJ+pplFR2ZQ==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/has-flag": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz",
-      "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/hermes-compiler": {
-      "version": "260318099.0.4",
-      "resolved": "https://registry.npmjs.org/hermes-compiler/-/hermes-compiler-260318099.0.4.tgz",
-      "integrity": "sha512-8odcPFkPC82HlqCl0C5QI9mBN4rEAT+IAo55sJhzwKw//K3qZloiv3ex6J2O8CuBbhdmkJozfidNsset2KH25w==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/hermes-estree": {
-      "version": "0.25.1",
-      "resolved": "https://registry.npmjs.org/hermes-estree/-/hermes-estree-0.25.1.tgz",
-      "integrity": "sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==",
-      "dev": true,
-      "license": "MIT"
-    },
-    "packages/expo-two-way-audio/node_modules/hermes-parser": {
-      "version": "0.25.1",
-      "resolved": "https://registry.npmjs.org/hermes-parser/-/hermes-parser-0.25.1.tgz",
-      "integrity": "sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "hermes-estree": "0.25.1"
-      }
-    },
-    "packages/expo-two-way-audio/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",
-      "peer": true,
-      "dependencies": {
-        "agent-base": "^7.1.2",
-        "debug": "4"
-      },
-      "engines": {
-        "node": ">= 14"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/ignore": {
-      "version": "7.0.5",
-      "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.5.tgz",
-      "integrity": "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">= 4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/indent-string": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/indent-string/-/indent-string-4.0.0.tgz",
-      "integrity": "sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/jest-diff": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/jest-diff/-/jest-diff-30.4.1.tgz",
-      "integrity": "sha512-CRpFK0RtLriVDGcPPAnR6HMVI8bSR2jnUIgralhauzYQZIb4RH9AtEInTuQr65LmmGggGcRT6HIASxwqsVsmlA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jest/diff-sequences": "30.4.0",
-        "@jest/get-type": "30.1.0",
-        "chalk": "^4.1.2",
-        "pretty-format": "30.4.1"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/jest-matcher-utils": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/jest-matcher-utils/-/jest-matcher-utils-30.4.1.tgz",
-      "integrity": "sha512-zvYfX5CaeEkFrrLS9suWe9rvJrm9J1Iv3ua8kIBv9GEPzcnsfBf0bob37la7s67fs0nlBC3EuvkOLnXQKxtx4A==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jest/get-type": "30.1.0",
-        "chalk": "^4.1.2",
-        "jest-diff": "30.4.1",
-        "pretty-format": "30.4.1"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/log-symbols": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-2.2.0.tgz",
-      "integrity": "sha512-VeIAFslyIerEJLXHziedo2basKbMKtTw3vfn5IzG0XTjhAVEJyNHnL2p7vc+wBDSdQuUpNw3M2u6xb9QsAY5Eg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "chalk": "^2.0.1"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/log-symbols/node_modules/ansi-styles": {
-      "version": "3.2.1",
-      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz",
-      "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "color-convert": "^1.9.0"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/log-symbols/node_modules/chalk": {
-      "version": "2.4.2",
-      "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz",
-      "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "ansi-styles": "^3.2.1",
-        "escape-string-regexp": "^1.0.5",
-        "supports-color": "^5.3.0"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/lru-cache": {
-      "version": "11.5.1",
-      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.1.tgz",
-      "integrity": "sha512-RPimw/7aMdv2oqRrxKwvZXcPfwBrn/JZ2xYcY9Hus/6LaS3VOAKVWKWgNLCFSiOm1ESXinjsDlidVU7JlnCN2A==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "engines": {
-        "node": "20 || >=22"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro/-/metro-0.87.1.tgz",
-      "integrity": "sha512-1oyLU9elM7hPAsKIqKooEekwxiuWr27+MZBhUROPhzcbXhMDxK64GPF/hCXwBZVp1F89ODavCrBmJtLx9WtBoQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/code-frame": "^7.29.0",
-        "@babel/core": "^7.25.2",
-        "@babel/generator": "^7.29.1",
-        "@babel/parser": "^7.29.0",
-        "@babel/template": "^7.28.6",
-        "@babel/traverse": "^7.29.0",
-        "@babel/types": "^7.29.0",
-        "accepts": "^2.0.0",
-        "connect": "^3.6.5",
-        "debug": "^4.4.0",
-        "error-stack-parser": "^2.0.6",
-        "flow-enums-runtime": "^0.0.6",
-        "flow-parser": "0.331.0",
-        "graceful-fs": "^4.2.4",
-        "invariant": "^2.2.4",
-        "jest-worker": "^29.7.0",
-        "jsc-safe-url": "^0.2.2",
-        "lodash.throttle": "^4.1.1",
-        "metro-babel-transformer": "0.87.1",
-        "metro-cache": "0.87.1",
-        "metro-cache-key": "0.87.1",
-        "metro-config": "0.87.1",
-        "metro-core": "0.87.1",
-        "metro-file-map": "0.87.1",
-        "metro-resolver": "0.87.1",
-        "metro-runtime": "0.87.1",
-        "metro-source-map": "0.87.1",
-        "metro-symbolicate": "0.87.1",
-        "metro-transform-plugins": "0.87.1",
-        "metro-transform-worker": "0.87.1",
-        "mime-types": "^3.0.1",
-        "nullthrows": "^1.1.1",
-        "serialize-error": "^2.1.0",
-        "source-map": "^0.5.6",
-        "throat": "^5.0.0",
-        "ws": "^7.5.10",
-        "yargs": "^17.6.2"
-      },
-      "bin": {
-        "metro": "src/cli.js"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-babel-transformer": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-babel-transformer/-/metro-babel-transformer-0.87.1.tgz",
-      "integrity": "sha512-orvRIGpb0yK1yMbk5YP3dhVKjmoxUkRB9fdltGJxNppEqus/1tFpNuf9KnGFR3Qjg0izoUrJ4z6WgoBvdkXPrA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/core": "^7.25.2",
-        "flow-enums-runtime": "^0.0.6",
-        "flow-parser": "0.331.0",
-        "metro-cache-key": "0.87.1",
-        "nullthrows": "^1.1.1"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-cache": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-cache/-/metro-cache-0.87.1.tgz",
-      "integrity": "sha512-juNPaj0Xi5tkLp8imXqvbSnEIijwKG36m7OiFFVJMqEkiURwAjkMFVek3/xpix1+LVQqO7kjVp3PvuvIM61mKQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "exponential-backoff": "^3.1.1",
-        "flow-enums-runtime": "^0.0.6",
-        "https-proxy-agent": "^7.0.5",
-        "metro-core": "0.87.1"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-cache-key": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-cache-key/-/metro-cache-key-0.87.1.tgz",
-      "integrity": "sha512-scqVVPMA2c+RVO12I3wyMDp5xCkRPLsyrcG4Qc3xfU5JR0EW/0sz2tjty+5UjMUtG09uiM1KYQ8HjWg7OQXHtw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "flow-enums-runtime": "^0.0.6"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-config": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-config/-/metro-config-0.87.1.tgz",
-      "integrity": "sha512-NmkDlc/qZAdo5gTkVTuO2AKE/khemRKRH5IA+SKfqUBJigI5GqZ5TOXhmEokhlkAqzjt8dyzKhzI6FHvXoXaTQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "connect": "^3.6.5",
-        "flow-enums-runtime": "^0.0.6",
-        "jest-validate": "^29.7.0",
-        "metro": "0.87.1",
-        "metro-cache": "0.87.1",
-        "metro-core": "0.87.1",
-        "metro-runtime": "0.87.1"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-core": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-core/-/metro-core-0.87.1.tgz",
-      "integrity": "sha512-xizzky/4+c/Mkznege8OW05j7bSdM39VPoEps61Se4+hf32UQujmbvLvIE9+UnP6kNEPVomk0Fw8NsBK9iRQmw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "flow-enums-runtime": "^0.0.6",
-        "lodash.throttle": "^4.1.1",
-        "metro-resolver": "0.87.1"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-file-map": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-file-map/-/metro-file-map-0.87.1.tgz",
-      "integrity": "sha512-9sPuNCojC3pS4vj+ZPY7FXmHGpdJeckXuKXQrDAfJvZc60AF8owRFTkI8XdwlwrmPIB2w++KraK9FMEXvC4wJw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "debug": "^4.4.0",
-        "fb-watchman": "^2.0.0",
-        "flow-enums-runtime": "^0.0.6",
-        "graceful-fs": "^4.2.4",
-        "invariant": "^2.2.4",
-        "jest-worker": "^29.7.0",
-        "micromatch": "^4.0.4",
-        "nullthrows": "^1.1.1"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-minify-terser": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-minify-terser/-/metro-minify-terser-0.87.1.tgz",
-      "integrity": "sha512-YK4k1oO1wV48hfE+Nbw2rJCnAgeabzrgT/xH5ha5n9gbK4p3HYFC898cERUiyTl9vRh58CNTiXRc88f7y6PfKg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "flow-enums-runtime": "^0.0.6",
-        "terser": "^5.15.0"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-resolver": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-resolver/-/metro-resolver-0.87.1.tgz",
-      "integrity": "sha512-FXH/brY69wT6sPxaSW8BhMmDGD/6irmBr/cL4rUi+VWwqR3pbvdcfUOfyjcHucgQ7pe5IW3xJY21eHKLVKNumQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "flow-enums-runtime": "^0.0.6"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-runtime": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-runtime/-/metro-runtime-0.87.1.tgz",
-      "integrity": "sha512-kjeuSvInsM6OzBjkCQsWxnkrKZFMKtnkCl38oXWRI9lDGs2L9hGs9Tak9sQYJ9h3gtDujneB7wZio+irgqJKDw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/runtime": "^7.25.0",
-        "flow-enums-runtime": "^0.0.6"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-source-map": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-source-map/-/metro-source-map-0.87.1.tgz",
-      "integrity": "sha512-Bqpm0PBGdy53pigIJb4HRF7QxD2pUOdgSmVh/4AWbP635kSCv+Y6ltVxUZgSnzS/QbSmzyCGijmRPlXMj2/qHw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/traverse": "^7.29.0",
-        "@babel/types": "^7.29.0",
-        "flow-enums-runtime": "^0.0.6",
-        "invariant": "^2.2.4",
-        "metro-symbolicate": "0.87.1",
-        "nullthrows": "^1.1.1",
-        "ob1": "0.87.1",
-        "source-map": "^0.5.6",
-        "vlq": "^1.0.0"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-symbolicate": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-symbolicate/-/metro-symbolicate-0.87.1.tgz",
-      "integrity": "sha512-rcGvwabrg0lbXGRGRKl14PY3My3+dkno2jZYhdJEuH2DmjTtTkV5bYwgto4JtV/Lbe+sXE6GO1UGg654430uow==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "flow-enums-runtime": "^0.0.6",
-        "invariant": "^2.2.4",
-        "metro-source-map": "0.87.1",
-        "nullthrows": "^1.1.1",
-        "source-map": "^0.5.6",
-        "vlq": "^1.0.0"
-      },
-      "bin": {
-        "metro-symbolicate": "src/index.js"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-transform-plugins": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-transform-plugins/-/metro-transform-plugins-0.87.1.tgz",
-      "integrity": "sha512-qMiJ/x+VfqumFJJSefKS6nj8uojzC29b2/aK8vlMuFABIqGjDucICEOXd2Yt6k/XMFAgAcaJvShUOT0HLyYaPw==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/core": "^7.25.2",
-        "@babel/generator": "^7.29.1",
-        "@babel/template": "^7.28.6",
-        "@babel/traverse": "^7.29.0",
-        "flow-enums-runtime": "^0.0.6",
-        "nullthrows": "^1.1.1"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro-transform-worker": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/metro-transform-worker/-/metro-transform-worker-0.87.1.tgz",
-      "integrity": "sha512-VOzs3OV405FuOLYdAhqA2wsn1F9lvueDVxMDLvCKaQ44U+yknIqphJ9eMjjsGwLDZiJq9sW3DMLhjD27JxQgqQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "@babel/core": "^7.25.2",
-        "@babel/generator": "^7.29.1",
-        "@babel/parser": "^7.29.0",
-        "@babel/types": "^7.29.0",
-        "flow-enums-runtime": "^0.0.6",
-        "metro": "0.87.1",
-        "metro-babel-transformer": "0.87.1",
-        "metro-cache": "0.87.1",
-        "metro-cache-key": "0.87.1",
-        "metro-minify-terser": "0.87.1",
-        "metro-source-map": "0.87.1",
-        "metro-transform-plugins": "0.87.1",
-        "nullthrows": "^1.1.1"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro/node_modules/accepts": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
-      "integrity": "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "mime-types": "^3.0.0",
-        "negotiator": "^1.0.0"
-      },
-      "engines": {
-        "node": ">= 0.6"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/metro/node_modules/ws": {
-      "version": "7.5.13",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.13.tgz",
-      "integrity": "sha512-rsKI6xDBFVf4r/x8XyChGK04QR/XHroxs/jUcoWvtEZM8TPU/X/uIY9B1CsSzYws9ZJb/6bbBu7dPhFW00CAoA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=8.3.0"
-      },
-      "peerDependencies": {
-        "bufferutil": "^4.0.1",
-        "utf-8-validate": "^5.0.2"
-      },
-      "peerDependenciesMeta": {
-        "bufferutil": {
-          "optional": true
-        },
-        "utf-8-validate": {
-          "optional": true
-        }
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/mime-types": {
-      "version": "3.0.2",
-      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz",
-      "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "mime-db": "^1.54.0"
-      },
-      "engines": {
-        "node": ">=18"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/express"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/mimic-fn": {
-      "version": "1.2.0",
-      "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-1.2.0.tgz",
-      "integrity": "sha512-jf84uxzwiuiIVKiOLpfYk7N46TSy8ubTonmneY9vrpHNAnp0QBt2BxWV9dO3/j+BoVAb+a5G6YDPW3M5HOdMWQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/minimatch": {
-      "version": "10.2.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz",
-      "integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "brace-expansion": "^5.0.5"
-      },
-      "engines": {
-        "node": "18 || 20 || >=22"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/negotiator": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.1.0.tgz",
-      "integrity": "sha512-NMPBRMJgiQHjbd8phG3Vebdx4kZ1H121rbl5IkMqeOsahptB9BKo/d7oJ3zTXqTgagn2bWlNSXkh0QUGM31RYg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "content-type": "^2.1.0"
-      },
-      "engines": {
-        "node": ">=18"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/express"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/node-forge": {
-      "version": "1.4.0",
-      "resolved": "https://registry.npmjs.org/node-forge/-/node-forge-1.4.0.tgz",
-      "integrity": "sha512-LarFH0+6VfriEhqMMcLX2F7SwSXeWwnEAJEsYm5QKWchiVYVvJyV9v7UDvUv+w5HO23ZpQTXDv/GxdDdMyOuoQ==",
-      "dev": true,
-      "license": "(BSD-3-Clause OR GPL-2.0)",
-      "peer": true,
-      "engines": {
-        "node": ">= 6.13.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/ob1": {
-      "version": "0.87.1",
-      "resolved": "https://registry.npmjs.org/ob1/-/ob1-0.87.1.tgz",
-      "integrity": "sha512-i8iA8uij0g1YQzS8uOJPSRCgwDjO9warIHUAu1Fqj877Wc3wlfxDYBioYWgKTBF2+URVJttyDWSEpmd99nlvtQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "flow-enums-runtime": "^0.0.6"
-      },
-      "engines": {
-        "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/onetime": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/onetime/-/onetime-2.0.1.tgz",
-      "integrity": "sha512-oyyPpiMaKARvvcgip+JV+7zci5L8D1W9RZIz2l1o08AM3pfspitVWnPt3mzHcBPp12oYMTy0pqrFs/C+m3EwsQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "mimic-fn": "^1.0.0"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/open": {
-      "version": "8.4.2",
-      "resolved": "https://registry.npmjs.org/open/-/open-8.4.2.tgz",
-      "integrity": "sha512-7x81NCL719oNbsq/3mh+hVrAWmFuEYUqrq/Iw3kUzH8ReypT9QQ0BLoJS7/G9k6N81XjW4qHWtjWwe/9eLy1EQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "define-lazy-prop": "^2.0.0",
-        "is-docker": "^2.1.1",
-        "is-wsl": "^2.2.0"
-      },
-      "engines": {
-        "node": ">=12"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/ora": {
-      "version": "3.4.0",
-      "resolved": "https://registry.npmjs.org/ora/-/ora-3.4.0.tgz",
-      "integrity": "sha512-eNwHudNbO1folBP3JsZ19v9azXWtQZjICdr3Q0TDPIaeBQ3mXLrh54wM+er0+hSp+dWKf+Z8KM58CYzEyIYxYg==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "chalk": "^2.4.2",
-        "cli-cursor": "^2.1.0",
-        "cli-spinners": "^2.0.0",
-        "log-symbols": "^2.2.0",
-        "strip-ansi": "^5.2.0",
-        "wcwidth": "^1.0.1"
-      },
-      "engines": {
-        "node": ">=6"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/ora/node_modules/ansi-styles": {
-      "version": "3.2.1",
-      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz",
-      "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "color-convert": "^1.9.0"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/ora/node_modules/chalk": {
-      "version": "2.4.2",
-      "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz",
-      "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "ansi-styles": "^3.2.1",
-        "escape-string-regexp": "^1.0.5",
-        "supports-color": "^5.3.0"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/path-scurry": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz",
-      "integrity": "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "lru-cache": "^11.0.0",
-        "minipass": "^7.1.2"
-      },
-      "engines": {
-        "node": "18 || 20 || >=22"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/pretty-format": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-30.4.1.tgz",
-      "integrity": "sha512-K6KiKMHTL4jjX4u3Kir2EW07nRfcqVTXIImx50wbjHQTcZPgg+gjVeNTIT3l3L1Rd4UefxfogquC9J37SoFyyw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jest/schemas": "30.4.1",
-        "ansi-styles": "^5.2.0",
-        "react-is-18": "npm:react-is@^18.3.1",
-        "react-is-19": "npm:react-is@^19.2.5"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
     "packages/expo-two-way-audio/node_modules/react": {
       "version": "19.3.1",
       "resolved": "https://registry.npmjs.org/react/-/react-19.3.1.tgz",
@@ -41893,205 +40193,10 @@
         "node": ">=0.10.0"
       }
     },
-    "packages/expo-two-way-audio/node_modules/react-refresh": {
-      "version": "0.14.2",
-      "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.14.2.tgz",
-      "integrity": "sha512-jCvmsr+1IUSMUyzOkRcvnVbX3ZYC6g9TDrDbFuFmRDq7PD4yaGbLKNQL6k2jnArV8hjYxh7hVhAZB6s9HDGpZA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/react-test-renderer": {
-      "version": "19.1.0",
-      "resolved": "https://registry.npmjs.org/react-test-renderer/-/react-test-renderer-19.1.0.tgz",
-      "integrity": "sha512-jXkSl3CpvPYEF+p/eGDLB4sPoDX8pKkYvRl9+rR8HxLY0X04vW7hCm1/0zHoUSjPZ3bDa+wXWNTDVIw/R8aDVw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "react-is": "^19.1.0",
-        "scheduler": "^0.26.0"
-      },
-      "peerDependencies": {
-        "react": "^19.1.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/redent": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/redent/-/redent-3.0.0.tgz",
-      "integrity": "sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "indent-string": "^4.0.0",
-        "strip-indent": "^3.0.0"
-      },
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/restore-cursor": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/restore-cursor/-/restore-cursor-2.0.0.tgz",
-      "integrity": "sha512-6IzJLuGi4+R14vwagDHX+JrXmPVtPpn4mffDJ1UdR7/Edm87fl6yi8mMBIVvFtJaNTUvjughmW4hwLhRG7gC1Q==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "onetime": "^2.0.0",
-        "signal-exit": "^3.0.2"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/signal-exit": {
-      "version": "3.0.7",
-      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
-      "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
-      "dev": true,
-      "license": "ISC",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/slash": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
-      "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/source-map": {
-      "version": "0.5.7",
-      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.5.7.tgz",
-      "integrity": "sha512-LbrmJOMUSdEVxIKvdcJzQC+nQhe8FUZQTXQy6+I75skNgn3OoQ0DZA8YnFa7gp8tqtL3KPf1kmo0R5DoApeSGQ==",
-      "dev": true,
-      "license": "BSD-3-Clause",
-      "peer": true,
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/strip-ansi": {
-      "version": "5.2.0",
-      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-5.2.0.tgz",
-      "integrity": "sha512-DuRs1gKbBqsMKIZlrffwlug8MHkcnpjs5VPmL1PAh+mA30U0DTotfDZ0d2UUsXpPmPmMMJ6W773MaA3J+lbiWA==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "ansi-regex": "^4.1.0"
-      },
-      "engines": {
-        "node": ">=6"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/strip-ansi/node_modules/ansi-regex": {
-      "version": "4.1.1",
-      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.1.tgz",
-      "integrity": "sha512-ILlv4k/3f6vfQ4OoP2AGvirOktlQ98ZEL1k9FaQjxa3L1abBgbuTDAdPOpvbGncC0BTVQrl+OM8xZGK6tWXt7g==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "engines": {
-        "node": ">=6"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/strip-indent": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-3.0.0.tgz",
-      "integrity": "sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "min-indent": "^1.0.0"
-      },
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/sucrase": {
-      "version": "3.35.1",
-      "resolved": "https://registry.npmjs.org/sucrase/-/sucrase-3.35.1.tgz",
-      "integrity": "sha512-DhuTmvZWux4H1UOnWMB3sk0sbaCVOoQZjv8u1rDoTV0HTdGem9hkAZtl4JZy8P2z4Bg0nT+YMeOFyVr4zcG5Tw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jridgewell/gen-mapping": "^0.3.2",
-        "commander": "^4.0.0",
-        "lines-and-columns": "^1.1.6",
-        "mz": "^2.7.0",
-        "pirates": "^4.0.1",
-        "tinyglobby": "^0.2.11",
-        "ts-interface-checker": "^0.1.9"
-      },
-      "bin": {
-        "sucrase": "bin/sucrase",
-        "sucrase-node": "bin/sucrase-node"
-      },
-      "engines": {
-        "node": ">=16 || 14 >=14.17"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/sucrase/node_modules/commander": {
-      "version": "4.1.1",
-      "resolved": "https://registry.npmjs.org/commander/-/commander-4.1.1.tgz",
-      "integrity": "sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">= 6"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/supports-color": {
-      "version": "5.5.0",
-      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz",
-      "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "has-flag": "^3.0.0"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/whatwg-url-minimum": {
-      "version": "0.2.0",
-      "resolved": "https://registry.npmjs.org/whatwg-url-minimum/-/whatwg-url-minimum-0.2.0.tgz",
-      "integrity": "sha512-BtjXU1caNcCFfETP2DhqSeVPfRDl2MTUitI107RE34rJXjR/izfUtR5IoTFOK1WqjNLXbbeqaCH/mQAOLjpc8g==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
-    "packages/expo-two-way-audio/node_modules/xmlbuilder": {
-      "version": "15.1.1",
-      "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-15.1.1.tgz",
-      "integrity": "sha512-yMqGBqtXyeN1e3TGYvgNgDVZ3j84W4cwkOXQswghol6APgZWaff9lnbvN7MHYJOiXsvGPXtjTYJEiC9J2wv9Eg==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=8.0"
-      }
-    },
-    "packages/expo-two-way-audio/node_modules/zod": {
-      "version": "3.25.76",
-      "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
-      "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
-      "dev": true,
-      "license": "MIT",
-      "funding": {
-        "url": "https://github.com/sponsors/colinhacks"
-      }
-    },
     "packages/highlight": {
       "name": "@getpaseo/highlight",
-      "version": "0.13.2",
+      "version": "0.15.3",
+      "license": "Apache-2.0",
       "dependencies": {
         "@codemirror/language": "6.12.4",
         "@codemirror/legacy-modes": "^6.5.3",
@@ -42120,15 +40225,16 @@
     },
     "packages/plugin": {
       "name": "@getpaseo/plugin",
-      "version": "0.13.2",
+      "version": "0.15.3",
+      "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.13.2",
-        "@getpaseo/protocol": "0.13.2",
+        "@getpaseo/client": "0.15.3",
+        "@getpaseo/protocol": "0.15.3",
         "@types/node": "^20.9.0",
         "@types/react": "~19.2.0",
         "react": "19.2.3",
@@ -42138,8 +40244,8 @@
         "zod": "^4.4.3"
       },
       "peerDependencies": {
-        "@getpaseo/client": "0.13.2",
-        "@getpaseo/protocol": "0.13.2",
+        "@getpaseo/client": "0.15.3",
+        "@getpaseo/protocol": "0.15.3",
         "react": ">=19.1.0 <20",
         "react-native": ">=0.81.5",
         "zod": "^4.4.3"
@@ -42161,7 +40267,8 @@
     },
     "packages/protocol": {
       "name": "@getpaseo/protocol",
-      "version": "0.13.2",
+      "version": "0.15.3",
+      "license": "Apache-2.0",
       "dependencies": {
         "semver": "^7.8.5",
         "zod": "^4.4.3"
@@ -42188,7 +40295,8 @@
     },
     "packages/relay": {
       "name": "@getpaseo/relay",
-      "version": "0.13.2",
+      "version": "0.15.3",
+      "license": "Apache-2.0",
       "dependencies": {
         "@noble/ciphers": "^2.4.0",
         "@noble/curves": "^2.4.0",
@@ -42409,21 +40517,24 @@
     },
     "packages/server": {
       "name": "@getpaseo/server",
-      "version": "0.13.2",
+      "version": "0.15.3",
+      "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.13.2",
-        "@getpaseo/highlight": "0.13.2",
-        "@getpaseo/plugin": "0.13.2",
-        "@getpaseo/protocol": "0.13.2",
-        "@getpaseo/relay": "0.13.2",
+        "@getpaseo/client": "0.15.3",
+        "@getpaseo/highlight": "0.15.3",
+        "@getpaseo/plugin": "0.15.3",
+        "@getpaseo/protocol": "0.15.3",
+        "@getpaseo/relay": "0.15.3",
         "@isaacs/ttlcache": "^2.1.4",
         "@modelcontextprotocol/sdk": "1.29.0",
         "@opencode-ai/sdk": "1.14.46",
         "@opencode/client": "2.0.10",
-        "@xterm/headless": "^6.0.0",
+        "@xterm/addon-serialize": "0.14.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",
@@ -42431,6 +40542,7 @@
         "esbuild": "^0.25.12",
         "express": "^4.18.2",
         "fast-deep-equal": "^3.1.3",
+        "https-proxy-agent": "^7.0.6",
         "lru-cache": "^11.5.1",
         "markdown-it": "^10.0.0",
         "mnemonic-id": "^3.2.7",
@@ -42448,6 +40560,7 @@
         "strip-ansi": "^7.1.2",
         "tree-kill": "^1.2.2",
         "typescript": "^5.9.3",
+        "undici": "^7.24.8",
         "uuid": "^9.0.1",
         "which": "^5.0.0",
         "ws": "^8.14.2",
@@ -43021,6 +41134,15 @@
         "url": "https://opencollective.com/vitest"
       }
     },
+    "packages/server/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==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14"
+      }
+    },
     "packages/server/node_modules/ajv": {
       "version": "8.20.0",
       "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
@@ -43090,6 +41212,19 @@
         "@esbuild/win32-x64": "0.25.12"
       }
     },
+    "packages/server/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==",
+      "license": "MIT",
+      "dependencies": {
+        "agent-base": "^7.1.2",
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
     "packages/server/node_modules/isexe": {
       "version": "3.1.5",
       "resolved": "https://registry.npmjs.org/isexe/-/isexe-3.1.5.tgz",
@@ -43339,7 +41474,7 @@
     },
     "packages/website": {
       "name": "@getpaseo/website",
-      "version": "0.13.2",
+      "version": "0.15.3",
       "dependencies": {
         "@cloudflare/vite-plugin": "^1.29.1",
         "@cloudflare/workers-types": "^4.20260317.1",
@@ -44949,7 +43084,7 @@
     },
     "plugins": {
       "name": "@getpaseo/builtin-plugins",
-      "version": "0.13.2",
+      "version": "0.15.3",
       "dependencies": {
         "@getpaseo/plugin": "*",
         "zod": "^4.4.3"
diff --git a/package.json b/package.json
index beeff7c613..a0883ec25d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "paseo",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "private": true,
   "description": "Paseo: voice-controlled development environment for local AI coding agents",
   "keywords": [
@@ -131,6 +131,8 @@
     "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",
     "knip": "^5.82.1",
@@ -147,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/.eas/workflows/release-mobile.yml b/packages/app/.eas/workflows/release-mobile.yml
index 26790ef22f..e57260898c 100644
--- a/packages/app/.eas/workflows/release-mobile.yml
+++ b/packages/app/.eas/workflows/release-mobile.yml
@@ -42,6 +42,20 @@ jobs:
       build_id: ${{ needs.build_android.outputs.build_id }}
       profile: production
 
+  upload_android_screenshots:
+    name: Upload Google Play screenshots
+    needs: [build_android, submit_android]
+    environment: production
+    runs_on: macos-medium
+    steps:
+      - uses: eas/checkout
+      - name: Install fastlane
+        run: bundle install
+      - name: Upload screenshots
+        run: |
+          export ANDROID_VERSION_CODE="${{ needs.build_android.outputs.app_build_version }}"
+          bundle exec fastlane android upload_screenshots
+
   submit_ios_for_review:
     name: Submit iOS for App Store review
     needs: [build_ios, distribute_ios]
diff --git a/packages/app/.eas/workflows/upload-android-screenshots.yml b/packages/app/.eas/workflows/upload-android-screenshots.yml
new file mode 100644
index 0000000000..dbd2fdddca
--- /dev/null
+++ b/packages/app/.eas/workflows/upload-android-screenshots.yml
@@ -0,0 +1,27 @@
+name: Upload Google Play screenshots
+
+# Standalone re-trigger for the release workflow's Google Play screenshot step.
+# Replaces the en-US phone and tablet screenshots with the committed renders,
+# without rebuilding or resubmitting the app.
+
+on:
+  workflow_dispatch:
+    inputs:
+      android_version_code:
+        type: string
+        required: false
+        description: "versionCode of the production release to attach the change to, e.g. 14000. Leave empty when the production track has a single release."
+
+jobs:
+  upload_android_screenshots:
+    name: Upload Google Play screenshots
+    environment: production
+    runs_on: macos-medium
+    steps:
+      - uses: eas/checkout
+      - name: Install fastlane
+        run: bundle install
+      - name: Upload screenshots
+        run: |
+          export ANDROID_VERSION_CODE="${{ inputs.android_version_code }}"
+          bundle exec fastlane android upload_screenshots
diff --git a/packages/app/app.config.js b/packages/app/app.config.js
index 7ddfc95029..fecdcce31a 100644
--- a/packages/app/app.config.js
+++ b/packages/app/app.config.js
@@ -102,7 +102,7 @@ export default {
     name: variant.name,
     slug: "voice-mobile",
     version: nativeReleaseVersion.appVersion,
-    orientation: "portrait",
+    orientation: "default",
     icon: "./assets/images/icon.png",
     scheme: "paseo",
     userInterfaceStyle: "automatic",
@@ -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 b98258ff9a..dde61f4560 100644
--- a/packages/app/app.config.test.ts
+++ b/packages/app/app.config.test.ts
@@ -59,3 +59,56 @@ describe("Android app config", () => {
     30_000,
   );
 });
+
+it("follows system rotation on Android", async () => {
+  const manifest = await resolveAndroidManifest();
+  const activity = manifest.application[0].activity.find(
+    (entry: ManifestEntry) => entry.$["android:name"] === ".MainActivity",
+  );
+  expect(activity.$["android:screenOrientation"]).toBe("unspecified");
+}, 30_000);
+
+it("allows all orientations on iPhone and iPad", async () => {
+  const { mkdtemp, rm } = await import("node:fs/promises");
+  const { tmpdir } = await import("node:os");
+  const { join } = await import("node:path");
+  const root = await mkdtemp(join(tmpdir(), "paseo-ios-config-"));
+  try {
+    const { exp } = await getPrebuildConfigAsync(__dirname, { platforms: ["ios"] });
+    await compileModsAsync(exp, {
+      projectRoot: root,
+      introspect: true,
+      platforms: ["ios"],
+      assertMissingModProviders: false,
+    });
+    const plist = exp._internal.modResults.ios.infoPlist;
+    const orientations = [
+      "UIInterfaceOrientationPortrait",
+      "UIInterfaceOrientationPortraitUpsideDown",
+      "UIInterfaceOrientationLandscapeLeft",
+      "UIInterfaceOrientationLandscapeRight",
+    ];
+    expect(plist.UISupportedInterfaceOrientations).toEqual(orientations);
+    expect(plist["UISupportedInterfaceOrientations~ipad"]).toEqual(orientations);
+  } finally {
+    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/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 0009188b34..24f26f1c44 100644
--- a/packages/app/e2e/browser/agent-message-submission.spec.ts
+++ b/packages/app/e2e/browser/agent-message-submission.spec.ts
@@ -53,6 +53,7 @@ import {
 import { expectInFlightForkAvailable } from "../support/helpers/assistant-fork";
 import {
   scrollTimelineToNewestLoadedEdge,
+  userScrollsTimelineToHistoryStart,
   scrollTimelineUntilOlderHistoryIsReachable,
 } from "../support/helpers/timeline-pagination";
 import {
@@ -234,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;
@@ -244,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;
@@ -256,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);
   };
 }
@@ -986,7 +1001,7 @@ test.describe("Agent message submission", () => {
     }
   });
 
-  test("keeps one prompt when its provider echo crosses the bounded tail", async ({
+  test("keeps one prompt when a delayed provider echo belongs to a large whole turn", async ({
     page,
   }, testInfo) => {
     const workspace = await seedWorkspace({
@@ -1003,8 +1018,10 @@ test.describe("Agent message submission", () => {
       await expectVisibleAgentSurfacesIdle(page);
       await page.reload();
 
-      await expect(submittedPrompt).toHaveCount(0);
-      await scrollTimelineUntilOlderHistoryIsReachable(page, prompt);
+      // The complete turn arrives on reload; scrolling mounts its oldest rows
+      // without requiring another page or an increase in total content height.
+      await userScrollsTimelineToHistoryStart(page);
+      await expect(submittedPrompt).toBeVisible();
       await expect(submittedPrompt).toHaveCount(1);
       await expect(submittedPrompt).toHaveAttribute("aria-busy", "false");
     } finally {
@@ -1175,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-timeline-pagination.spec.ts b/packages/app/e2e/browser/agent-timeline-pagination.spec.ts
index f2772b0b1b..57ee050fa4 100644
--- a/packages/app/e2e/browser/agent-timeline-pagination.spec.ts
+++ b/packages/app/e2e/browser/agent-timeline-pagination.spec.ts
@@ -27,6 +27,10 @@ import {
   seedRealisticOlderTimeline,
   sendLiveTurnBeforeHydration,
   expectTimelineViewportAnchoredAfterPrepend,
+  expectToolCallGroupPositionPreserved,
+  rememberToolCallGroupPosition,
+  seedItemPagedToolGroupTimeline,
+  useChatDisplay,
   userNavigatesTimelineToHistoryStartWithKeyboard,
   userScrollsTimelineToHistoryStart,
 } from "../support/helpers/timeline-pagination";
@@ -100,6 +104,32 @@ test.describe("Agent timeline pagination", () => {
     }
   });
 
+  // Hosts paged by items can end a page inside a tool run. The older page extends the group
+  // the reader is on, which changes the row hosting it; the reader must stay with that group
+  // rather than land at history start and drain every older page.
+  test("keeps the reading position when an older item page extends the tool-call group being read", async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+    await useChatDisplay(page, "collapseToolCalls");
+    const agent = await seedItemPagedToolGroupTimeline();
+    try {
+      const history = await holdOlderHistoryPages(page, agent, { itemPagedHost: true });
+      await openAgentTimeline(page, agent);
+      await expectTimelinePromptVisible(page, agent.newestPrompt);
+
+      await userScrollsTimelineToHistoryStart(page);
+      await history.expectRequestedPages(1);
+      const reading = await rememberToolCallGroupPosition(page, agent.loadedCommands);
+
+      history.releasePage(1);
+      await expectToolCallGroupPositionPreserved(page, agent.totalCommands, reading);
+      await history.expectSettledWithRequestedPages(1);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
   test("loads older history when the user navigates to history start with the keyboard", async ({
     page,
   }) => {
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..f68efffd02 100644
--- a/packages/app/e2e/browser/agent-timeline-sync-retry.spec.ts
+++ b/packages/app/e2e/browser/agent-timeline-sync-retry.spec.ts
@@ -18,8 +18,10 @@ 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);
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..523297729c
--- /dev/null
+++ b/packages/app/e2e/browser/agent-turn-end.spec.ts
@@ -0,0 +1,200 @@
+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;
+  footer: Box | 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 footers = Array.from(viewport?.querySelectorAll('[data-testid="turn-footer"]') ?? [])
+        .map(boxOf)
+        .filter((box): box is Box => box !== null)
+        .sort((left, right) => left.top - right.top);
+      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),
+            );
+      state.frames.push({
+        at: performance.now(),
+        running: Boolean(viewport?.querySelector('[data-testid="turn-working-indicator"]')),
+        footer: footers.at(-1) ?? null,
+        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"
+        } 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);
+}
+
+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);
+  });
+});
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/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/branch-switcher.spec.ts b/packages/app/e2e/browser/branch-switcher.spec.ts
index c413b6413e..9799242390 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,88 @@ 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) => {
+      const envelope = JSON.parse(message.toString());
+      if (envelope.type === "session" && envelope.message?.type === "branch_suggestions_request")
+        requestCount++;
+      server.send(message);
+    });
+    server.onMessage(async (message) => {
+      const envelope = JSON.parse(message.toString());
+      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 +144,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 +168,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..7137c903ff 100644
--- a/packages/app/e2e/browser/changes-pane.spec.ts
+++ b/packages/app/e2e/browser/changes-pane.spec.ts
@@ -323,6 +323,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);
@@ -928,11 +1041,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);
@@ -1657,6 +1770,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" }],
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 77d995eda7..5b68663862 100644
--- a/packages/app/e2e/browser/compact-workspace-sheet.spec.ts
+++ b/packages/app/e2e/browser/compact-workspace-sheet.spec.ts
@@ -5,12 +5,16 @@ import { expectComposerVisible } from "../support/helpers/composer";
 import { installDaemonWebSocketGate } from "../support/helpers/daemon-websocket-gate";
 import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
 import {
+  expectSubagentRowGone,
   expectSubagentRowVisible,
   openSubagentFromCompactTrack,
   seedSubagent,
 } from "../support/helpers/subagents";
 import {
+  backToList,
   closeSheet,
+  expectNoSheetOpen,
+  expectOneSheetOpen,
   expectOpenTabCount,
   openSheetAsTab,
   expectDeclinedDiscardPrompt,
@@ -52,6 +56,10 @@ test("compact opens files and subagents in a sheet, leaving the tabs for agents"
       { client: workspace.client, repoPath: workspace.cwd, workspaceId: workspace.workspaceId },
       { parentId: workspace.agentId, title: "Sheet child" },
     );
+    const grandchild = await seedSubagent(
+      { client: workspace.client, repoPath: workspace.cwd, workspaceId: workspace.workspaceId },
+      { parentId: child.id, title: "Sheet grandchild" },
+    );
     await openAgentRoute(page, { workspaceId: workspace.workspaceId, agentId: workspace.agentId });
     await expectOpenTabCount(page, 1);
 
@@ -79,12 +87,14 @@ test("compact opens files and subagents in a sheet, leaving the tabs for agents"
       await tapSheetBackdrop(page);
     });
 
-    await test.step("a subagent opens in a sheet over the subagents list", async () => {
+    await test.step("a subagent opens in place of the subagents list", async () => {
       await openSubagentFromCompactTrack(page, child.id);
 
       const childSheet = sheet(page, child.title);
       await expect(childSheet).toBeVisible();
       await expectSheetAtSnap(page, child.title);
+      await expectSubagentRowGone(page, child.id);
+      await expectOneSheetOpen(page);
       await expect(childSheet.getByRole("textbox", { name: "Message agent..." })).toHaveCount(0);
       // The composer's model, thinking, and mode stand in for it, resolved the same way. An idle
       // seeded agent has no context usage yet.
@@ -94,23 +104,51 @@ test("compact opens files and subagents in a sheet, leaving the tabs for agents"
       await expectOpenTabCount(page, 1);
     });
 
-    await test.step("closing the subagent's sheet uncovers the list", async () => {
-      await closeSheet(page, child.title);
+    await test.step("Back returns the sheet to the list", async () => {
+      await backToList(page, child.title);
       await expectSubagentRowVisible(page, child.id);
+      await expectOneSheetOpen(page);
+    });
+
+    await test.step("Close closes the list with the subagent", async () => {
+      await page.getByTestId(`subagents-track-row-${child.id}`).click();
+      await closeSheet(page, child.title);
+      await expectSubagentRowGone(page, child.id);
+      await expectNoSheetOpen(page);
     });
 
     await test.step("the parent box in a subagent's sheet closes it onto the parent", async () => {
-      await page.getByTestId(`subagents-track-row-${child.id}`).click();
+      await openSubagentFromCompactTrack(page, child.id);
       const childSheet = sheet(page, child.title);
       await expectSheetAtSnap(page, child.title);
       await expect(childSheet.getByTestId("composer-parent-agent-pill")).toHaveCount(0);
       await childSheet.getByTestId("parent-agent-callout-open").click();
       await expect(childSheet).toHaveCount(0);
+      await expectNoSheetOpen(page);
+      await expectOpenTabCount(page, 1);
+    });
+
+    await test.step("a nested subagent's parent box lands on its parent's sheet", async () => {
+      await openSubagentFromCompactTrack(page, child.id);
+      const childSheet = sheet(page, child.title);
+      await openSubagentFromCompactTrack(page, grandchild.id, childSheet);
+      const grandchildSheet = sheet(page, grandchild.title);
+      await expectSheetAtSnap(page, grandchild.title);
+      await expect(grandchildSheet.getByTestId("parent-agent-callout")).toContainText(child.title);
+
+      await grandchildSheet.getByTestId("parent-agent-callout-open").click();
+      await expect(grandchildSheet).toHaveCount(0);
+      await expect(childSheet).toBeVisible();
+      await expectOneSheetOpen(page);
+
+      await childSheet.getByTestId("parent-agent-callout-open").click();
+      await expect(childSheet).toHaveCount(0);
+      await expectNoSheetOpen(page);
       await expectOpenTabCount(page, 1);
     });
 
     await test.step("Open as tab promotes the subagent to a full tab and ends the list", async () => {
-      await page.getByTestId(`subagents-track-row-${child.id}`).click();
+      await openSubagentFromCompactTrack(page, child.id);
       await expectSheetAtSnap(page, child.title);
       await openSheetAsTab(page, child.title);
       await expect(page.getByTestId(`subagents-track-row-${child.id}`)).toHaveCount(0);
@@ -123,7 +161,7 @@ test("compact opens files and subagents in a sheet, leaving the tabs for agents"
       await expect(page.getByTestId(`subagents-track-row-${child.id}`)).toHaveCount(0);
     });
 
-    await test.step("once its tab closes, the subagent reopens in a sheet that keeps the list", async () => {
+    await test.step("once its tab closes, the subagent reopens in place of the list", async () => {
       await page
         .getByRole("button", { name: /Switch tabs/ })
         .filter({ visible: true })
@@ -141,7 +179,7 @@ test("compact opens files and subagents in a sheet, leaving the tabs for agents"
 
       await openSubagentFromCompactTrack(page, child.id);
       await expectSheetAtSnap(page, child.title);
-      await closeSheet(page, child.title);
+      await backToList(page, child.title);
       await expectSubagentRowVisible(page, child.id);
       await tapSheetBackdrop(page);
       await expect(page.getByRole("button", { name: "Bottom sheet backdrop" })).toHaveCount(0);
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..aad17cd1ae 100644
--- a/packages/app/e2e/browser/composer-control-density.spec.ts
+++ b/packages/app/e2e/browser/composer-control-density.spec.ts
@@ -1,10 +1,17 @@
 import { test, expect } from "../support/fixtures";
 import { openWorkspaceWithAgents } from "../support/helpers/archive-tab";
+import { fillComposerDraft } from "../support/helpers/composer";
 import {
+  expectComposerToolbarOnTextRails,
   expectNoCollapsedComposerToolbarFrame,
+  expectNoFrameTruncatesModelBesideThinking,
+  readSettledModelTriggerLabels,
   recordComposerToolbarFrames,
+  recordModelTriggerFramesFromLoad,
+  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;
@@ -92,3 +99,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 9b80222432..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 {
@@ -18,7 +20,7 @@ function visibleMainPane(page: Page) {
 }
 
 function composerChangesPill(page: Page) {
-  return page.getByTestId("composer-diff-stat-pill");
+  return page.getByRole("button", { name: "Open Changes tab", exact: true });
 }
 
 async function revealComposerChangesInExplorer(page: Page) {
@@ -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,
@@ -498,6 +501,7 @@ test.describe("send review feedback", () => {
   test("only open tabs in this workspace appear in compact and wide recipient menus", async ({
     page,
   }) => {
+    test.setTimeout(120000);
     const workspace = await seedChangedAgent("review-feedback-multiple-");
     const other = await seedChangedAgent("review-feedback-other-");
     try {
@@ -858,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..11fe0bf50f 100644
--- a/packages/app/e2e/browser/composer-focus.spec.ts
+++ b/packages/app/e2e/browser/composer-focus.spec.ts
@@ -25,7 +25,7 @@ import {
   expectMobileAgentSidebarVisible,
   expectMobileExplorerHidden,
   expectMobileExplorerVisible,
-  swipeOpenMobileAgentSidebar,
+  openMobileAgentSidebarWithKeyboard,
   swipeOpenMobileExplorer,
 } from "../support/helpers/sidebar";
 import { readScrollMetrics } from "../support/helpers/agent-bottom-anchor";
@@ -249,7 +249,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..f79b7fd760 100644
--- a/packages/app/e2e/browser/context-window-meter.spec.ts
+++ b/packages/app/e2e/browser/context-window-meter.spec.ts
@@ -429,6 +429,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/daemon-lifecycle.spec.ts b/packages/app/e2e/browser/daemon-lifecycle.spec.ts
index bded30cb81..23f6f5b2ff 100644
--- a/packages/app/e2e/browser/daemon-lifecycle.spec.ts
+++ b/packages/app/e2e/browser/daemon-lifecycle.spec.ts
@@ -1,14 +1,23 @@
 import { randomUUID } from "node:crypto";
-import { mkdtemp, writeFile } from "node:fs/promises";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { expect, test } from "../support/fixtures";
+import { expect, test, daemonTest as cleanupTest } from "../support/fixtures";
 import { startIsolatedHostDaemon } from "../support/helpers/isolated-host-daemon";
 import {
   openDaemonOverview,
   restartDaemonInSettings,
   expectDaemonRestartComplete,
+  expectDaemonRestartFailed,
+  plantUnclosableTerminalProgram,
   readWorkerPid,
+  openLongLivedTerminal,
+  listTerminalIds,
+  suspendDaemonProcess,
+  resumeDaemonProcess,
+  daemonProcessCanWrite,
+  readTerminalProcessIds,
 } from "../support/helpers/daemon-lifecycle";
 
 test("settings restart waits for a replacement worker while retaining the supervisor", async ({
@@ -29,6 +38,57 @@ test("settings restart waits for a replacement worker while retaining the superv
   }
 });
 
+test("settings restart keeps a terminal", async ({ page }) => {
+  const daemon = await startIsolatedHostDaemon(randomUUID());
+  try {
+    const terminalId = await openLongLivedTerminal(daemon);
+    const previousWorker = await readWorkerPid(daemon);
+    await openDaemonOverview(page, daemon);
+    await restartDaemonInSettings(page);
+    await expectDaemonRestartComplete(page);
+    expect(await readWorkerPid(daemon)).not.toBe(previousWorker);
+    expect(await listTerminalIds(daemon)).toContain(terminalId);
+  } finally {
+    await daemon.close();
+  }
+});
+
+test("settings restart and close terminals closes the terminal", async ({ page }) => {
+  const daemon = await startIsolatedHostDaemon(randomUUID());
+  try {
+    await openLongLivedTerminal(daemon);
+    const previousWorker = await readWorkerPid(daemon);
+    await openDaemonOverview(page, daemon);
+    await restartDaemonInSettings(page, { closeTerminals: true });
+    await expectDaemonRestartComplete(page);
+    expect(await readWorkerPid(daemon)).not.toBe(previousWorker);
+    expect(await listTerminalIds(daemon)).toEqual([]);
+  } finally {
+    await daemon.close();
+  }
+});
+
+test("settings restart and close terminals shows the processes it could not close", async ({
+  page,
+}, testInfo) => {
+  test.skip(process.platform === "win32", "The unclosable program is a POSIX zombie");
+  const daemon = await startIsolatedHostDaemon(randomUUID());
+  let program: Awaited<ReturnType<typeof plantUnclosableTerminalProgram>> | null = null;
+  try {
+    program = await plantUnclosableTerminalProgram(daemon);
+    await openDaemonOverview(page, daemon);
+    await restartDaemonInSettings(page, { closeTerminals: true });
+    await expectDaemonRestartFailed(page, `pid ${program.pid}`);
+    await page.screenshot({
+      path: testInfo.outputPath("restart-cleanup-failed.png"),
+      fullPage: true,
+    });
+  } finally {
+    program?.release();
+    await daemon.close();
+  }
+});
+
 test("settings restart replaces the worker when a provider CLI answers --version slowly", async ({
   page,
 }) => {
@@ -64,3 +124,51 @@ async function createHomeWithSlowProvider(versionDelayMs: number): Promise<strin
   );
   return paseoHome;
 }
+
+// Cleanup has no renderer demand: drive the same isolated daemon owner directly.
+// A stopped worker deterministically outlives the old helper's five-second
+// supervisor-only kill and logs into its deleted home when resumed.
+cleanupTest(
+  "isolated cleanup prevents a stopped worker from recreating its deleted home",
+  async () => {
+    cleanupTest.skip(process.platform === "win32", "POSIX stopped-process failure injection");
+    const daemon = await startIsolatedHostDaemon(randomUUID());
+    const workerPid = await readWorkerPid(daemon);
+    try {
+      suspendDaemonProcess(workerPid);
+      await daemon.close();
+      resumeDaemonProcess(workerPid);
+      await expect.poll(() => daemonProcessCanWrite(workerPid)).toBe(false);
+      expect(existsSync(daemon.paseoHome)).toBe(false);
+    } finally {
+      resumeDaemonProcess(workerPid);
+      await daemon.close();
+      await rm(daemon.paseoHome, { recursive: true, force: true });
+    }
+  },
+);
+
+cleanupTest(
+  "isolated cleanup force-stops a frozen supervisor and its detached terminal writers",
+  async () => {
+    cleanupTest.skip(process.platform === "win32", "POSIX stopped-process failure injection");
+    const daemon = await startIsolatedHostDaemon(randomUUID());
+    const supervisorPid = daemon.getPid()!;
+    const workerPid = await readWorkerPid(daemon);
+    try {
+      await openLongLivedTerminal(daemon);
+      const terminalProcesses = await readTerminalProcessIds(daemon);
+      expect(terminalProcesses.length).toBeGreaterThanOrEqual(2);
+      suspendDaemonProcess(supervisorPid);
+      await daemon.close();
+      const writerStates = await Promise.all(
+        [supervisorPid, workerPid, ...terminalProcesses].map(daemonProcessCanWrite),
+      );
+      expect(writerStates).toEqual(Array(terminalProcesses.length + 2).fill(false));
+      expect(existsSync(daemon.paseoHome)).toBe(false);
+    } finally {
+      resumeDaemonProcess(supervisorPid);
+      await daemon.close();
+    }
+  },
+);
diff --git a/packages/app/e2e/browser/diff-performance.spec.ts b/packages/app/e2e/browser/diff-performance.spec.ts
index c11c82f279..0358b6359e 100644
--- a/packages/app/e2e/browser/diff-performance.spec.ts
+++ b/packages/app/e2e/browser/diff-performance.spec.ts
@@ -1,6 +1,7 @@
 import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { CDPSession, Locator, Page, TestInfo } from "@playwright/test";
+import { pullRequestCorpus } from "../../src/git/diff-document/benchmark-corpus";
 import { buildHostWorkspaceRoute } from "../../src/utils/host-routes";
 import { test, expect } from "../support/fixtures";
 import { getServerId } from "../support/helpers/server-id";
@@ -296,8 +297,187 @@ diffPerfDescribe("Diff canvas performance", () => {
       await repo.cleanup().catch(() => undefined);
     }
   });
+  test("toggling line wrap on a pull-request-sized diff", async ({ page }, testInfo) => {
+    test.setTimeout(300_000);
+    const corpus = await createPullRequestCorpusRepository();
+    const client = await connectSeedClient();
+
+    try {
+      const created = await client.createWorkspace({
+        source: { kind: "directory", path: corpus.repo.path },
+      });
+      if (!created.workspace) {
+        throw new Error(created.error ?? "Failed to create wrap performance workspace");
+      }
+
+      await configureUnwrappedUnifiedDiff(page);
+      await instrumentDiffLatency(page);
+      await page.setViewportSize({ width: 1400, height: 900 });
+      await page.goto(buildHostWorkspaceRoute(getServerId(), created.workspace.id));
+      await waitForWorkspaceTabsVisible(page);
+      const openStartedAt = performance.now();
+      await openChangesPanel(page, 90_000);
+      await expect(page.getByTestId("git-diff-canvas")).toBeVisible({ timeout: 30_000 });
+      const open = {
+        readyMs: Math.round(performance.now() - openStartedAt),
+        ...(await readDiffDocumentRenders(page)),
+      };
+
+      const toggles: WrapToggleMeasurement[] = [];
+      for (const name of [
+        "wrap on (cold)",
+        "wrap off (cold)",
+        "wrap on (warm)",
+        "wrap off (warm)",
+      ]) {
+        toggles.push(await measureWrapToggle(page, name));
+      }
+      const unwrappedScroll = await continuouslyScrollCanvas(page);
+      toggles.push(await measureWrapToggle(page, "wrap on (warm, scrolled)"));
+      const wrappedScroll = await continuouslyScrollCanvas(page);
+
+      const report = {
+        scenario: "wrap-toggle",
+        sourceFiles: corpus.fileCount,
+        sourceLines: corpus.lineCount,
+        open,
+        toggles,
+        scroll: {
+          unwrapped: summarizeScroll(unwrappedScroll),
+          wrapped: summarizeScroll(wrappedScroll),
+        },
+      };
+      await attachPerformanceReport(testInfo, report);
+      console.log(`[perf] Wrap toggle: ${JSON.stringify(report)}`);
+
+      const [wrapOn, wrapOff] = toggles;
+      expect(wrapOn!.scrollHeightAfter).toBeGreaterThan(wrapOn!.scrollHeightBefore);
+      expect(wrapOff!.scrollHeightAfter).toBe(wrapOn!.scrollHeightBefore);
+    } finally {
+      await client.close().catch(() => undefined);
+      await corpus.repo.cleanup().catch(() => undefined);
+    }
+  });
 });
 
+interface WrapToggleMeasurement {
+  name: string;
+  /** Pointer down on the toolbar button to two painted frames after the document resized. */
+  latencyMs: number;
+  scrollHeightBefore: number;
+  scrollHeightAfter: number;
+  longestTaskMs: number;
+  longTaskTotalMs: number;
+  diffDocumentCommits: number;
+  diffDocumentRenderMs: number;
+}
+
+interface LongTask {
+  startTime: number;
+  duration: number;
+}
+
+interface DiffLatencyScope {
+  __PASEO_RENDER_PROFILE_ENABLED__?: boolean;
+  __PASEO_RENDER_PROFILE__?: Array<{ id: string; actualDuration: number }>;
+  __PASEO_RESET_RENDER_PROFILE__?: () => void;
+  __PASEO_LONG_TASKS__?: LongTask[];
+  __PASEO_WRAP_TOGGLE_AT__?: number;
+}
+
+async function createPullRequestCorpusRepository() {
+  const files = pullRequestCorpus();
+  const repo = await createTempGitRepo("diff-wrap-perf-", {
+    files: files.map((file) => ({ path: file.path, content: "baseline\n" })),
+  });
+  for (const file of files) {
+    await writeFile(path.join(repo.path, file.path), `${file.lines.join("\n")}\n`);
+  }
+  return {
+    repo,
+    fileCount: files.length,
+    lineCount: files.reduce((count, file) => count + file.lines.length, 0),
+  };
+}
+
+async function instrumentDiffLatency(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    const scope = globalThis as typeof globalThis & DiffLatencyScope;
+    scope.__PASEO_RENDER_PROFILE_ENABLED__ = true;
+    scope.__PASEO_LONG_TASKS__ = [];
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        scope.__PASEO_LONG_TASKS__?.push({ startTime: entry.startTime, duration: entry.duration });
+      }
+    }).observe({ type: "longtask", buffered: true });
+  });
+}
+
+async function readDiffDocumentRenders(
+  page: Page,
+): Promise<{ diffDocumentCommits: number; diffDocumentRenderMs: number }> {
+  return page.evaluate(() => {
+    const scope = globalThis as typeof globalThis & DiffLatencyScope;
+    const samples = (scope.__PASEO_RENDER_PROFILE__ ?? []).filter(
+      (sample) => sample.id === "DiffDocument",
+    );
+    return {
+      diffDocumentCommits: samples.length,
+      diffDocumentRenderMs: Math.round(
+        samples.reduce((total, sample) => total + sample.actualDuration, 0),
+      ),
+    };
+  });
+}
+
+async function measureWrapToggle(page: Page, name: string): Promise<WrapToggleMeasurement> {
+  const scroll = page.getByTestId("git-diff-scroll");
+  const scrollHeightBefore = await scroll.evaluate((element) => element.scrollHeight);
+  await page.evaluate(() => {
+    const scope = globalThis as typeof globalThis & DiffLatencyScope;
+    scope.__PASEO_RESET_RENDER_PROFILE__?.();
+    scope.__PASEO_LONG_TASKS__ = [];
+    scope.__PASEO_WRAP_TOGGLE_AT__ = undefined;
+    document.addEventListener(
+      "pointerdown",
+      () => {
+        scope.__PASEO_WRAP_TOGGLE_AT__ = performance.now();
+      },
+      { capture: true, once: true },
+    );
+  });
+  await page.getByTestId("changes-toggle-wrap-lines").click();
+  const measured = await scroll.evaluate(async (element, before) => {
+    const scope = globalThis as typeof globalThis & DiffLatencyScope;
+    const deadline = performance.now() + 240_000;
+    while (element.scrollHeight === before && performance.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    await new Promise<void>((resolve) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+    );
+    const doneAt = performance.now();
+    // Long task entries are delivered after the task ends; give the observer a turn.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    const startedAt = scope.__PASEO_WRAP_TOGGLE_AT__ ?? doneAt;
+    const longTasks = (scope.__PASEO_LONG_TASKS__ ?? []).filter(
+      (task) => task.startTime + task.duration >= startedAt && task.startTime <= doneAt,
+    );
+    return {
+      latencyMs: Math.round(doneAt - startedAt),
+      scrollHeightAfter: element.scrollHeight,
+      longestTaskMs: Math.round(Math.max(0, ...longTasks.map((task) => task.duration))),
+      longTaskTotalMs: Math.round(longTasks.reduce((total, task) => total + task.duration, 0)),
+    };
+  }, scrollHeightBefore);
+  return { name, scrollHeightBefore, ...measured, ...(await readDiffDocumentRenders(page)) };
+}
+
+function summarizeScroll(report: Awaited<ReturnType<typeof continuouslyScrollCanvas>>) {
+  const { frameSignatures: _frameSignatures, ...summary } = report;
+  return summary;
+}
+
 async function measureAdditionalPerformanceScenario(
   page: Page,
   cdp: CDPSession,
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..373459ef4c 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,88 @@ test.describe("Direct terminal shortcut pane placement", () => {
     }
   });
 });
+
+async function prepareUnfocusedCompactPane(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 launchTerminalFromCompactPane(page: Page, pane: Locator) {
+  await pane.getByTestId("workspace-tab-switcher-trigger").click();
+  await page.getByTestId("workspace-tab-switcher-new-terminal").click();
+  await expect(pane.getByTestId("terminal-surface")).toBeVisible({ timeout: 30_000 });
+}
+
+async function maximizeAndRestoreCompactPane(page: Page, pane: Locator) {
+  await pane.getByTestId("workspace-header-menu-trigger").click();
+  await expect(page.getByRole("menuitem", { name: "Split pane right", exact: true })).toBeVisible();
+  await page.getByRole("menuitem", { name: "Maximize pane", exact: true }).click();
+  await pane.getByTestId("workspace-header-menu-trigger").click();
+  await page.getByRole("menuitem", { name: "Restore pane", exact: true }).click();
+}
+
+test("compact pane launch stays in its owning pane and pane controls remain reachable", async ({
+  page,
+}) => {
+  const workspace = await seedWorkspace({ repoPrefix: "compact-pane-launch-" });
+  try {
+    const { originalPane, otherPane } = await prepareUnfocusedCompactPane(
+      page,
+      workspace.workspaceId,
+    );
+    await launchTerminalFromCompactPane(page, originalPane);
+    await expect(otherPane.getByTestId("workspace-new-tab-panel")).toBeVisible();
+    await maximizeAndRestoreCompactPane(page, originalPane);
+    await expect(otherPane).toBeVisible();
+  } 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("compact desktop panes retain window dragging with both sidebars closed", async ({ page }) => {
+  const workspace = await seedWorkspace({ repoPrefix: "compact-pane-window-drag-" });
+  try {
+    await installLocalDesktopHost(page, workspace.repoPath);
+    const { originalPane, otherPane } = await prepareUnfocusedCompactPane(
+      page,
+      workspace.workspaceId,
+    );
+    await runWorkspaceActionFromCommandCenter(page, "Toggle left sidebar");
+    await expect(originalPane.getByTestId("workspace-tab-switcher-trigger")).toBeVisible();
+    await expect(otherPane.getByTestId("workspace-tab-switcher-trigger")).toBeVisible();
+    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/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/new-workspace-composer-draft.spec.ts b/packages/app/e2e/browser/new-workspace-composer-draft.spec.ts
index 906efcfb42..01fd4638eb 100644
--- a/packages/app/e2e/browser/new-workspace-composer-draft.spec.ts
+++ b/packages/app/e2e/browser/new-workspace-composer-draft.spec.ts
@@ -1,3 +1,4 @@
+import { chooseModel, startWithoutRememberedModel } from "../support/helpers/model-memory";
 import {
   composerLocator,
   enterComposerFullscreen,
@@ -97,6 +98,7 @@ test.describe("New workspace composer draft", () => {
     const project = await seedWorkspace({ repoPrefix: "new-workspace-submitted-draft-" });
 
     try {
+      await startWithoutRememberedModel(page);
       await gotoAppShell(page);
       await waitForSidebarHydration(page);
       await openNewWorkspaceComposer(page, {
@@ -104,6 +106,7 @@ test.describe("New workspace composer draft", () => {
         projectDisplayName: project.projectDisplayName,
       });
 
+      await chooseModel(page, "mock", "Ten second stream");
       const composer = page.getByRole("textbox", { name: "Message agent..." });
       const createButton = page.getByTestId("workspace-create-submit");
       await expect(composer).toBeEditable({ timeout: 30_000 });
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/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/owned-subscriptions-old-daemon.spec.ts b/packages/app/e2e/browser/owned-subscriptions-old-daemon.spec.ts
index 17f4db2e85..5f1f36e409 100644
--- a/packages/app/e2e/browser/owned-subscriptions-old-daemon.spec.ts
+++ b/packages/app/e2e/browser/owned-subscriptions-old-daemon.spec.ts
@@ -1,29 +1,90 @@
 import { randomUUID } from "node:crypto";
-import { submitMessage, expectComposerEditable } from "../support/helpers/composer";
 import {
   focusTerminalSurface,
   typeInTerminal,
   getTerminalBufferText,
 } from "../support/helpers/terminal-perf";
 import { buildHostWorkspaceRoute } from "../../src/utils/host-routes";
-import { metroTest as test, expect } from "../support/fixtures";
+import { metroTest as test, expect, type Page } from "../support/fixtures";
 import { buildCreateAgentPreferences, buildSeededHost } from "../support/helpers/daemon-registry";
 import { startIsolatedHostDaemon } from "../support/helpers/isolated-host-daemon";
 import type { MockAgentWorkspace } from "../support/helpers/mock-agent";
 import { seedWorkspace } from "../support/helpers/seed-client";
 import {
-  expectTimelinePromptVisible,
+  expectFoldedTurnAtReadingPosition,
+  expectOldestLoadedTurnPartial,
   holdOlderHistoryPages,
   openAgentTimeline,
-  scrollThroughOlderHistoryPages,
+  expectTimelinePromptVisible,
+  userScrollsTimelineToHistoryStart,
 } from "../support/helpers/timeline-pagination";
 
-test("does not repeat an assistant block when the current app paginates a published 0.2.5 daemon", async ({
+interface PublishedDaemonAgent {
+  serverId: string;
+  daemon: Awaited<ReturnType<typeof startIsolatedHostDaemon>>;
+  agent: MockAgentWorkspace;
+  /** Register the host in the browser and apply app settings before the first load. */
+  seedBrowser(page: Page, appSettings?: Record<string, unknown>): Promise<void>;
+  close(): Promise<void>;
+}
+
+async function startPublishedDaemonAgent(options: {
+  publishedVersion: string;
+  serverIdPrefix: string;
+  repoPrefix: string;
+  title: string;
+}): Promise<PublishedDaemonAgent> {
+  const serverId = `${options.serverIdPrefix}${randomUUID().replaceAll("-", "").slice(0, 12)}`;
+  const daemon = await startIsolatedHostDaemon(serverId, {
+    publishedVersion: options.publishedVersion,
+  });
+  const workspace = await seedWorkspace({ repoPrefix: options.repoPrefix, port: daemon.port });
+  const createdAgent = await workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title: options.title,
+    modeId: "load-test",
+    model: "ten-second-stream",
+  });
+  const agent: MockAgentWorkspace = {
+    agentId: createdAgent.id,
+    workspaceId: workspace.workspaceId,
+    cwd: workspace.repoPath,
+    client: workspace.client,
+    cleanup: workspace.cleanup,
+  };
+  return {
+    serverId,
+    daemon,
+    agent,
+    async seedBrowser(page, appSettings) {
+      const host = buildSeededHost({
+        serverId,
+        endpoint: `127.0.0.1:${daemon.port}`,
+        nowIso: new Date().toISOString(),
+      });
+      await page.addInitScript(
+        ({ seededHost, preferences, settings }) => {
+          localStorage.setItem("@paseo:e2e", "1");
+          localStorage.setItem("@paseo:daemon-registry", JSON.stringify([seededHost]));
+          localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(preferences));
+          if (settings) localStorage.setItem("@paseo:app-settings", JSON.stringify(settings));
+        },
+        { seededHost: host, preferences: buildCreateAgentPreferences(), settings: appSettings },
+      );
+    },
+    async close() {
+      await agent.cleanup();
+      await daemon.close();
+    },
+  };
+}
+
+test("loads history across browser reconnection while retaining old-daemon connections and terminals", async ({
   page,
 }) => {
   test.setTimeout(120_000);
-  const serverId = `srv_old_pagination_${randomUUID().replaceAll("-", "").slice(0, 12)}`;
-  const daemon = await startIsolatedHostDaemon(serverId, { publishedVersion: "0.2.5" });
   const observationSockets = new Set<unknown>();
   page.on("websocket", (socket) => {
     socket.on("framesent", ({ payload }) => {
@@ -37,104 +98,84 @@ test("does not repeat an assistant block when the current app paginates a publis
         observationSockets.add(socket);
     });
   });
-  const workspace = await seedWorkspace({
+  const published = await startPublishedDaemonAgent({
+    publishedVersion: "0.2.5",
+    serverIdPrefix: "srv_old_pagination_",
     repoPrefix: "timeline-old-daemon-pagination-",
-    port: daemon.port,
-  });
-  const createdAgent = await workspace.client.createAgent({
-    provider: "mock",
-    cwd: workspace.repoPath,
-    workspaceId: workspace.workspaceId,
     title: "Published daemon pagination regression",
-    modeId: "load-test",
-    model: "ten-second-stream",
   });
-  const agent: MockAgentWorkspace = {
-    agentId: createdAgent.id,
-    workspaceId: workspace.workspaceId,
-    cwd: workspace.repoPath,
-    client: workspace.client,
-    cleanup: workspace.cleanup,
-  };
+  const { agent, serverId } = published;
 
   try {
-    for (let index = 0; index < 40; index += 1) {
-      await agent.client.sendAgentMessage(
-        agent.agentId,
-        `timeline-pagination-older-turn-${index}: emit 1 coalesced agent stream updates`,
-      );
-      await agent.client.waitForFinish(agent.agentId, 15_000);
-    }
-    await agent.client.sendAgentMessage(agent.agentId, "build a realistic long mock timeline");
-    await agent.client.waitForFinish(agent.agentId, 20_000);
-    for (let index = 0; index < 20; index += 1) {
-      await agent.client.sendAgentMessage(
-        agent.agentId,
-        `timeline-pagination-turn-${index}: emit 1 coalesced agent stream updates`,
-      );
-      await agent.client.waitForFinish(agent.agentId, 15_000);
-    }
+    await agent.client.sendAgentMessage(agent.agentId, "emit 1 coalesced agent stream updates");
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+    await published.seedBrowser(page);
 
-    const host = buildSeededHost({
-      serverId,
-      endpoint: `127.0.0.1:${daemon.port}`,
-      nowIso: new Date().toISOString(),
-    });
-    await page.addInitScript(
-      ({ seededHost, preferences }) => {
-        localStorage.setItem("@paseo:e2e", "1");
-        localStorage.setItem("@paseo:daemon-registry", JSON.stringify([seededHost]));
-        localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(preferences));
-      },
-      { seededHost: host, preferences: buildCreateAgentPreferences() },
-    );
-
-    const history = await holdOlderHistoryPages(page, agent, daemon.port);
     await openAgentTimeline(page, agent, serverId);
-    await expectTimelinePromptVisible(
-      page,
-      "timeline-pagination-turn-19: emit 1 coalesced agent stream updates",
-    );
-    await scrollThroughOlderHistoryPages(page, 3, history);
-
-    history.expectRepeatedEntries();
-    await history.expectOwnedTextRendered("Now I have a clearer picture.");
+    await expectTimelinePromptVisible(page, "emit 1 coalesced agent stream updates");
     expect(observationSockets.size).toBe(1);
 
-    await test.step("send a live turn after reconnecting the old daemon", async () => {
-      await daemon.restart();
-      await expect.poll(() => observationSockets.size, { timeout: 30_000 }).toBe(2);
-      await expectComposerEditable(page);
-      await submitMessage(
-        page,
-        "compatibility-after-reconnect: emit 1 coalesced agent stream updates",
-      );
-      await expectTimelinePromptVisible(
-        page,
-        "compatibility-after-reconnect: emit 1 coalesced agent stream updates",
-      );
-      // The browser and the seed client reconnect independently after the restart.
-      await agent.client.connect();
-      await agent.client.waitForFinish(agent.agentId, 20_000);
-      await page.screenshot({ path: test.info().outputPath("old-daemon-live-reconnect.png") });
+    await test.step("reconnect the browser and reload the old daemon history", async () => {
+      observationSockets.clear();
+      await page.reload();
+      await expectTimelinePromptVisible(page, "emit 1 coalesced agent stream updates");
+      await expect.poll(() => observationSockets.size).toBe(1);
     });
 
     await test.step("open a terminal and receive its output", async () => {
       const terminal = await agent.client.createTerminal(agent.cwd, "Compatibility terminal");
       expect(terminal.error).toBeNull();
       const terminalId = terminal.terminal!.id;
-      const route = buildHostWorkspaceRoute(serverId, workspace.workspaceId);
+      const route = buildHostWorkspaceRoute(serverId, agent.workspaceId);
       await page.goto(`${route}?open=${encodeURIComponent(`terminal:${terminalId}`)}`);
       await focusTerminalSurface(page);
       await typeInTerminal(page, "printf 'compatibility-%s\\n' terminal-output\n");
       await expect
         .poll(() => getTerminalBufferText(page), { timeout: 15_000 })
         .toContain("compatibility-terminal-output");
-      await page.screenshot({ path: test.info().outputPath("old-daemon-terminal.png") });
       await agent.client.killTerminal(terminalId);
     });
   } finally {
-    await agent.cleanup();
-    await daemon.close();
+    await published.close();
+  }
+});
+
+// Hosts without whole-turn pages split turns across item pages. The oldest loaded turn
+// starts mid-turn and only folds once the next page completes it; the reader must stay
+// with that turn instead of landing at history start and draining every older page.
+test("keeps the reader on the turn that folds when an older item page completes it", async ({
+  page,
+}) => {
+  test.setTimeout(240_000);
+  const published = await startPublishedDaemonAgent({
+    publishedVersion: "0.13.0-beta.2",
+    serverIdPrefix: "srv_old_fold_",
+    repoPrefix: "timeline-old-daemon-fold-",
+    title: "Published daemon folded turn pagination",
+  });
+  const { agent, serverId } = published;
+  const prompts = Array.from({ length: 5 }, (_, index) => `Realistic turn ${index}: inspect it`);
+
+  try {
+    for (const prompt of prompts) {
+      await agent.client.sendAgentMessage(agent.agentId, prompt);
+      await agent.client.waitForFinish(agent.agentId, 30_000);
+    }
+    await published.seedBrowser(page, { chatDisplay: "collapseTurns" });
+    const history = await holdOlderHistoryPages(page, agent, {
+      daemonPort: published.daemon.port,
+    });
+    await openAgentTimeline(page, agent, serverId);
+    await expectTimelinePromptVisible(page, prompts.at(-1)!);
+
+    await userScrollsTimelineToHistoryStart(page);
+    await history.expectRequestedPages(1);
+    const partialTurnPrompt = await expectOldestLoadedTurnPartial(page, prompts);
+
+    history.releasePage(1);
+    await expectFoldedTurnAtReadingPosition(page, partialTurnPrompt);
+    await history.expectSettledWithRequestedPages(1);
+  } finally {
+    await published.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-host-ui.spec.ts b/packages/app/e2e/browser/plugin-host-ui.spec.ts
index a195f30aa2..b63728ff73 100644
--- a/packages/app/e2e/browser/plugin-host-ui.spec.ts
+++ b/packages/app/e2e/browser/plugin-host-ui.spec.ts
@@ -1,3 +1,13 @@
+import {
+  withRetainedPlugin,
+  editRetainedDraft,
+  expectRetainedDraft,
+  expectStoredPluginTitle,
+  hideRetainedPreferences,
+  showRetainedPreferences,
+  expectChangedPlugin,
+  expectRemovedPlugin,
+} from "../support/helpers/plugin-reconnect";
 import { verifyPluginTranslations } from "../support/helpers/plugin-translations";
 import { pluginRequirements } from "../support/helpers/plugin-fixture";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
@@ -188,3 +198,51 @@ test("plugin content and host labels follow app language without losing an open
   test.setTimeout(180_000);
   await verifyPluginTranslations(page, info);
 });
+
+test("retains plugin state offline and reconciles settings, changed code and removal", async ({
+  page,
+}) => {
+  test.setTimeout(180_000);
+  await withRetainedPlugin(page, async (probe) => {
+    await probe.open();
+    await editRetainedDraft(page, "Connected draft", 0);
+
+    await test.step("local plugin UI remains mounted and usable while disconnected", async () => {
+      await probe.disconnect();
+      await expectRetainedDraft(page, "Connected draft", 1);
+      await editRetainedDraft(page, "Offline draft", 1);
+      await probe.changeStoredTitle("Saved by another client");
+      await expectStoredPluginTitle(page, "Agent monitor");
+      await probe.reconnect();
+      await expectStoredPluginTitle(page, "Saved by another client");
+      await expectRetainedDraft(page, "Offline draft", 2);
+    });
+
+    await test.step("inactive settings refresh without replacing the installation", async () => {
+      await hideRetainedPreferences(page);
+      await probe.disconnect();
+      await probe.changeStoredTitle("Saved while preferences hidden");
+      await probe.reconnect();
+      await showRetainedPreferences(page);
+      await expectStoredPluginTitle(page, "Saved while preferences hidden");
+      await expectRetainedDraft(page, "Offline draft", 2);
+    });
+
+    await test.step("changed code replaces the retained installation after reconnect", async () => {
+      await probe.disconnect();
+      await probe.changeCode();
+      await expectRetainedDraft(page, "Offline draft", 2);
+      await probe.reconnect();
+      await expectChangedPlugin(page);
+      await editRetainedDraft(page, "New code draft", 0);
+    });
+
+    await test.step("removal is reconciled after reconnect", async () => {
+      await probe.disconnect();
+      await probe.remove();
+      await expectRetainedDraft(page, "New code draft", 1);
+      await probe.reconnect();
+      await expectRemovedPlugin(page);
+    });
+  });
+});
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 166e6b9881..d75653298e 100644
--- a/packages/app/e2e/browser/plugin-timeline.spec.ts
+++ b/packages/app/e2e/browser/plugin-timeline.spec.ts
@@ -1,4 +1,5 @@
 import { test } from "../support/fixtures";
+import { installDaemonWebSocketGate } from "../support/helpers/daemon-websocket-gate";
 import {
   withTimelinePlugin,
   viewInlineThinkingExample,
@@ -6,6 +7,8 @@ import {
   interactWithStreamingCard,
   expectWholeCompletedCard,
   expectBothConsecutiveTools,
+  trackPluginChatRecovery,
+  reconnectPluginChat,
 } from "../support/helpers/plugin-timeline";
 
 for (const width of [1100, 390]) {
@@ -13,13 +16,24 @@ for (const width of [1100, 390]) {
     page,
   }, info) => {
     await page.setViewportSize({ width, height: 900 });
+    const gate = await installDaemonWebSocketGate(page);
     await withTimelinePlugin(page, info, "assistant", async (agent) => {
       await requestPluginTimeline(agent);
       await interactWithStreamingCard(page);
       await agent.client.waitForFinish(agent.agentId, 30_000);
       await expectWholeCompletedCard(page);
       // Local state is checked during growth; the viewport remounts on the history handoff.
+      const recovery = trackPluginChatRecovery(page);
+      gate.holdTimelineResponses(agent.agentId);
       await page.reload({ waitUntil: "domcontentloaded" });
+      await gate.waitForHeldTimelineResponse();
+      await recovery.expectCatalogWithoutRetransmission();
+      gate.releaseHeldTimelineResponses();
+      await expectWholeCompletedCard(page);
+      await recovery.expectRecoveredWithoutRetransmission();
+      recovery.reset();
+      await reconnectPluginChat(page, gate);
+      await recovery.expectRecoveredWithoutRetransmission();
       await expectWholeCompletedCard(page);
     });
   });
diff --git a/packages/app/e2e/browser/projects-settings.spec.ts b/packages/app/e2e/browser/projects-settings.spec.ts
index 0612d5ce07..0732ec6732 100644
--- a/packages/app/e2e/browser/projects-settings.spec.ts
+++ b/packages/app/e2e/browser/projects-settings.spec.ts
@@ -204,19 +204,26 @@ test.describe("Projects settings", () => {
   }) => {
     const repo = await createTempGitRepo("projects-settings-empty-");
     const client = await connectSeedClient();
-    let projectId: string | null = null;
+    let projectViewKey: string | null = null;
 
     try {
       await gotoAppShell(page);
 
-      projectId = await addProjectFromSidebar(page, repo.path);
-      await openProjectSettingsFromSidebar(page, projectId);
+      projectViewKey = await addProjectFromSidebar(page, repo.path);
+      await openProjectSettingsFromSidebar(page, projectViewKey);
 
       await expectProjectSettingsFormVisible(page);
       await expect(page.getByTestId("project-settings-back-button")).not.toBeVisible();
     } finally {
-      if (projectId) {
-        await client.removeProject(projectId).catch(() => undefined);
+      if (projectViewKey) {
+        const project = (await client.listProjects()).projects.find(
+          (entry) => entry.projectKey === projectViewKey,
+        );
+        expect(project).toBeDefined();
+        await client.removeProject(project!.projectId);
+        expect(
+          (await client.listProjects()).projects.map((entry) => entry.projectKey),
+        ).not.toContain(projectViewKey);
       }
       await client.close().catch(() => undefined);
       await repo.cleanup().catch(() => undefined);
diff --git a/packages/app/e2e/browser/provider-settings-refresh.spec.ts b/packages/app/e2e/browser/provider-settings-refresh.spec.ts
index 961b518435..6c9739e894 100644
--- a/packages/app/e2e/browser/provider-settings-refresh.spec.ts
+++ b/packages/app/e2e/browser/provider-settings-refresh.spec.ts
@@ -1,5 +1,7 @@
+import path from "node:path";
 import type { Locator } from "@playwright/test";
 import { expect, test, type Page } from "../support/fixtures";
+import { clickNewChat, gotoWorkspace } from "../support/helpers/launcher";
 import { expectComposerVisible } from "../support/helpers/composer";
 import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
 
@@ -214,3 +216,66 @@ test.describe("provider settings overlay stack", () => {
     }
   });
 });
+
+async function openTimedOutProvider(page: Page, workspaceId: string, width: number) {
+  await gotoWorkspace(page, workspaceId);
+  await clickNewChat(page);
+  await expectComposerVisible(page);
+  await page.setViewportSize({ width, height: 900 });
+  await page.getByRole("button", { name: /Select model/ }).click();
+  if (width < 600) {
+    await page.getByTestId("agent-controls-model").click();
+  } else {
+    await page.getByRole("button", { name: "Back", exact: true }).click();
+  }
+  await page.getByTestId("model-provider-picker-timeout").click();
+  await expect(page.getByText(/Timed out refreshing Pi timeout/)).toBeVisible();
+}
+
+async function expectErrorHasSideGutters(page: Page) {
+  const error = page.getByText(/Timed out refreshing Pi timeout/);
+  const bounds = await error.evaluate((element) => {
+    const text = element.getBoundingClientRect();
+    const state = element.parentElement!.getBoundingClientRect();
+    return { left: text.left - state.left, right: state.right - text.right };
+  });
+  expect(bounds.left, "error text stays inside the empty state's left edge").toBeGreaterThan(0);
+  expect(bounds.right, "error text stays inside the empty state's right edge").toBeGreaterThan(0);
+  await expect(page.getByRole("button", { name: "Retry", exact: true })).toBeVisible();
+}
+
+test.use({
+  e2eDaemonConfig: {
+    version: 1,
+    agents: {
+      catalogRefreshTimeoutMs: 2000,
+      providers: {
+        "picker-timeout": {
+          extends: "pi",
+          label: "Pi timeout",
+          enabled: true,
+          command: [
+            process.execPath,
+            path.resolve("e2e/fixtures/fake-pi-rpc.mjs"),
+            "--stall-model-discovery",
+          ],
+        },
+      },
+    },
+  },
+});
+
+test.describe("model discovery timeout", () => {
+  for (const width of [1200, 390]) {
+    test(`keeps a wrapped discovery error away from both picker edges at ${width}px`, async ({
+      page,
+      withWorkspace,
+    }, testInfo) => {
+      await page.setViewportSize({ width: 1200, height: 900 });
+      const workspace = await withWorkspace({ prefix: "model-error-spacing-" });
+      await openTimedOutProvider(page, workspace.workspaceId, width);
+      await page.screenshot({ path: testInfo.outputPath("model-error.png") });
+      await expectErrorHasSideGutters(page);
+    });
+  }
+});
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/settings-host-page.spec.ts b/packages/app/e2e/browser/settings-host-page.spec.ts
index 76e5b331e6..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";
@@ -30,6 +35,10 @@ import {
   addDirectHostFromSettings,
   expectHostOnlineWithoutError,
   expectIdleAgentRelease,
+  editRestartRecoveryPrompt,
+  expectRestartRecoveryEnabled,
+  expectRestartRecoveryPrompt,
+  setRestartRecoveryEnabled,
   setIdleAgentRelease,
 } from "../support/helpers/settings";
 
@@ -252,3 +261,91 @@ test.describe("Settings host page", () => {
     await expectHostActionCards(page, serverId);
   });
 });
+
+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.");
+  await setRestartRecoveryEnabled(page, false);
+  await page.reload();
+  await expectRestartRecoveryEnabled(page, false);
+  await setRestartRecoveryEnabled(page, true);
+  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 4d7afbd4b9..4d77fde7d8 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,
@@ -284,6 +287,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 +326,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(\/|$)/);
     });
 
@@ -479,3 +492,76 @@ test.describe("Settings — compact master-detail", () => {
     await expect(page.getByTestId("welcome-direct-connection")).toBeVisible();
   });
 });
+
+async function measureDockedNavigation(page: import("@playwright/test").Page, width: number) {
+  await page.setViewportSize({ width, height: 951 });
+  const history = page.getByRole("button", { name: /^History/ }).filter({ visible: true });
+  const settings = page
+    .getByRole("button", { name: "Settings", exact: true })
+    .filter({ visible: true });
+  await expect(history).toBeVisible();
+  await expect(settings).toBeVisible();
+  return {
+    width,
+    history: await history.evaluate((el) => el.getBoundingClientRect().height),
+    settings: await settings.evaluate((el) => el.getBoundingClientRect().height),
+  };
+}
+
+async function measureSettingsSplit(page: import("@playwright/test").Page, width: number) {
+  await page.setViewportSize({ width, height: 951 });
+  const sidebar = page.getByTestId("settings-sidebar");
+  const detail = page.getByTestId("settings-detail-pane");
+  await expect(sidebar).toBeVisible();
+  await expect(detail).toBeVisible();
+  return {
+    width,
+    sidebar: await sidebar.evaluate((el) => el.getBoundingClientRect().width),
+    detail: await detail.evaluate((el) => el.getBoundingClientRect().width),
+  };
+}
+
+async function expectConsistentDockedNavigation(page: import("@playwright/test").Page) {
+  const wide = await measureDockedNavigation(page, 951);
+  for (const width of [600, 669, 719, 720]) {
+    const narrow = await measureDockedNavigation(page, width);
+    expect
+      .soft(narrow.history, `History keeps its wide-layout density at ${width}`)
+      .toBeCloseTo(wide.history, 0);
+    expect
+      .soft(narrow.settings, `Settings keeps its wide-layout density at ${width}`)
+      .toBeCloseTo(wide.settings, 0);
+  }
+}
+
+async function expectSettingsDetailKeepsReadingWidth(page: import("@playwright/test").Page) {
+  const reference = await measureSettingsSplit(page, 720);
+  for (const width of [600, 669, 719]) {
+    const narrow = await measureSettingsSplit(page, width);
+    expect
+      .soft(narrow.detail, `Settings preserves its detail budget at ${width}`)
+      .toBeGreaterThanOrEqual(reference.detail);
+    expect
+      .soft(narrow.sidebar, `Settings navigation yields width at ${width}`)
+      .toBeLessThan(reference.sidebar);
+  }
+  const wide = await measureSettingsSplit(page, 951);
+  expect(wide.sidebar).toBeCloseTo(reference.sidebar, 0);
+  expect(wide.detail).toBeGreaterThan(reference.detail);
+}
+
+test("docked navigation keeps its density and Settings preserves reading width", async ({
+  page,
+  withWorkspace,
+}) => {
+  const workspace = await withWorkspace({ prefix: "narrow-wide-layout-" });
+  await gotoWorkspace(page, workspace.workspaceId);
+  await expectConsistentDockedNavigation(page);
+  await openSettings(page);
+  await openSettingsSection(page, "appearance");
+  await expectAppearanceContent(page);
+  await expectSettingsDetailKeepsReadingWidth(page);
+  await page.setViewportSize({ width: 599, height: 951 });
+  await expectSettingsSidebarHidden(page);
+  await expectAppearanceContent(page);
+});
diff --git a/packages/app/e2e/browser/settings-toggle-tab-regression.spec.ts b/packages/app/e2e/browser/settings-toggle-tab-regression.spec.ts
index 41da8ac3fa..35ec6f78bb 100644
--- a/packages/app/e2e/browser/settings-toggle-tab-regression.spec.ts
+++ b/packages/app/e2e/browser/settings-toggle-tab-regression.spec.ts
@@ -1,3 +1,4 @@
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
 import { buildHostAgentDetailRoute, buildHostWorkspaceRoute } from "@/utils/host-routes";
 import { expect, test } from "../support/fixtures";
 import { createMockIdleAgent, openWorkspaceWithAgents } from "../support/helpers/archive-tab";
@@ -274,3 +275,123 @@ test.describe("Settings toggle tab regression", () => {
     }
   });
 });
+
+async function selectSendingOption(
+  page: import("@playwright/test").Page,
+  setting: string,
+  option: string,
+) {
+  await page.getByRole("button", { name: new RegExp(`^${setting}:`) }).click();
+  await page.getByRole("menuitem", { name: option, exact: true }).click();
+  await expect(
+    page.getByRole("button", { name: `${setting}: ${option}`, exact: true }),
+  ).toBeVisible();
+}
+
+async function sendDraftWithShortcut(
+  page: import("@playwright/test").Page,
+  draft: string,
+  shortcut: string,
+) {
+  const composer = page.getByRole("textbox", { name: "Message agent..." });
+  await composer.fill(draft);
+  await composer.press(shortcut);
+  await expect(composer).toHaveValue("");
+  await expect(page.getByText(draft, { exact: true })).toBeVisible();
+}
+
+test("send shortcut selection persists and controls the composer", async ({ page }, testInfo) => {
+  test.setTimeout(180_000);
+  const workspace = await seedWorkspace({ repoPrefix: "send-shortcut-" });
+  const modifierLabel = process.platform === "darwin" ? "⌘" : "Ctrl";
+  try {
+    const agent = await createMockIdleAgent(workspace.client, {
+      cwd: workspace.repoPath,
+      workspaceId: workspace.workspaceId,
+      title: "Send shortcut",
+    });
+    await openAgentRouteAndExpectFocused({
+      page,
+      serverId: getServerId(),
+      workspaceId: workspace.workspaceId,
+      agentId: agent.id,
+    });
+    await openComposerTab(page, agent.id);
+    const composer = page.getByRole("textbox", { name: "Message agent..." });
+
+    await test.step("Enter sends by default", async () => {
+      await sendDraftWithShortcut(page, "Default Enter submission", "Enter");
+    });
+    await test.step("choose the explicit modifier shortcut and retain it after reload", async () => {
+      await pressSettingsToggleShortcut(page);
+      await expect(
+        page.getByRole("button", { name: "Send shortcut: Enter", exact: true }),
+      ).toBeVisible();
+      await page.getByRole("button", { name: "Send shortcut: Enter", exact: true }).click();
+      await expect(page.getByRole("menuitem")).toHaveText(["Enter", `${modifierLabel}+Enter`]);
+      // Let the menu opening animation settle for visual QA.
+      await page.waitForTimeout(300);
+      await page.screenshot({ path: testInfo.outputPath("send-shortcut-selector.png") });
+      await page.getByRole("menuitem", { name: `${modifierLabel}+Enter`, exact: true }).click();
+      await page.reload();
+      await expect(
+        page.getByRole("button", { name: `Send shortcut: ${modifierLabel}+Enter`, exact: true }),
+      ).toBeVisible();
+      await pressSettingsToggleShortcut(page);
+      await expect(composer).toBeVisible();
+    });
+    await test.step("Enter and Shift+Enter keep editing; modifier Enter sends", async () => {
+      await composer.fill("First line");
+      await composer.press("Enter");
+      await expect(composer).toHaveValue("First line\n");
+      await composer.press("Shift+Enter");
+      await expect(composer).toHaveValue("First line\n\n");
+      await sendDraftWithShortcut(page, "Sent with Control", "Control+Enter");
+      await sendDraftWithShortcut(page, "Sent with Command", "Meta+Enter");
+    });
+    await test.step("switch back to Enter without changing the default send behavior", async () => {
+      await pressSettingsToggleShortcut(page);
+      await selectSendingOption(page, "Send shortcut", "Enter");
+      await pressSettingsToggleShortcut(page);
+      await composer.fill("Shift still edits");
+      await composer.press("Shift+Enter");
+      await expect(composer).toHaveValue("Shift still edits\n");
+      await sendDraftWithShortcut(page, "Restored Enter submission", "Enter");
+    });
+  } finally {
+    await workspace.cleanup();
+  }
+});
+
+for (const behavior of ["Steer", "Interrupt", "Queue"] as const) {
+  test(`modifier send shortcut follows ${behavior} while an agent runs`, async ({ page }) => {
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: "running-send-shortcut-",
+      title: "Running send shortcut",
+      model: "one-minute-stream",
+    });
+    const modifierLabel = process.platform === "darwin" ? "⌘" : "Ctrl";
+    try {
+      await openAgentRoute(page, agent);
+      await expect(page.getByRole("textbox", { name: "Message agent..." })).toBeVisible();
+      await pressSettingsToggleShortcut(page);
+      await selectSendingOption(page, "Send shortcut", `${modifierLabel}+Enter`);
+      await selectSendingOption(page, "Default send", behavior);
+      await pressSettingsToggleShortcut(page);
+      await sendDraftWithShortcut(page, "Stay running while I write a follow-up", "Control+Enter");
+      await expect(page.getByRole("button", { name: "Stop agent", exact: true })).toBeVisible();
+      const composer = page.getByRole("textbox", { name: "Message agent..." });
+      await composer.fill("Follow-up");
+      await composer.press("Enter");
+      await expect(composer).toHaveValue("Follow-up\n");
+      await composer.press("Control+Enter");
+      await expect(composer).toHaveValue("");
+      await expect(page.getByText("Follow-up", { exact: true })).toBeVisible();
+      await expect(page.getByRole("button", { name: "Send queued message" })).toHaveCount(
+        behavior === "Queue" ? 1 : 0,
+      );
+    } finally {
+      await agent.cleanup();
+    }
+  });
+}
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-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 03ffe9f7db..cf885a1d14 100644
--- a/packages/app/e2e/browser/sidebar-reorder.spec.ts
+++ b/packages/app/e2e/browser/sidebar-reorder.spec.ts
@@ -53,11 +53,18 @@ async function quickDragFirstRowAfterSecond(
   await page.mouse.move(source.x, source.y + 7);
   await expect(trailingScrim).toHaveCount(0);
   await page.mouse.move(target.x, target.y, { steps: 4 });
-  await page.mouse.up();
+  await finishSidebarDrag(page);
 
   await expect.poll(() => rowTestIds(rows)).toEqual([before[1], before[0]]);
 }
 
+async function finishSidebarDrag(page: Page): Promise<void> {
+  await page.mouse.up();
+  // dnd-kit's pointer sensor keeps its document click blocker for 50 ms after drop.
+  // Row order updates before that blocker is removed; wait before the next user action.
+  await page.waitForTimeout(60);
+}
+
 async function dragWithoutReordering(rows: Locator): Promise<void> {
   const before = await rowTestIds(rows);
   const source = await visibleBoundingBox(rows.nth(0));
@@ -66,7 +73,7 @@ async function dragWithoutReordering(rows: Locator): Promise<void> {
   await page.mouse.move(source.x + source.width / 2, source.y + source.height / 2);
   await page.mouse.down();
   await page.mouse.move(target.x + target.width / 2, target.y + target.height / 2, { steps: 5 });
-  await page.mouse.up();
+  await finishSidebarDrag(page);
   await expect.poll(() => rowTestIds(rows)).toEqual(before);
 }
 
@@ -419,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-workspace-mark-unread.spec.ts b/packages/app/e2e/browser/sidebar-workspace-mark-unread.spec.ts
index ccf29179b8..a2a695af5f 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,72 @@ 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>>,
+  agentId: string,
+) {
+  await gate.drop();
+  await gate.waitForBlockedConnection();
+  gate.holdTimelineResponses(agentId);
+  gate.restore();
+  await gate.waitForHeldTimelineResponse();
+  await expectReconnectingToastGone(page);
+  gate.releaseHeldTimelineResponses();
+  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, workspaces.subject.agentId);
+  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..a7a7b4320a 100644
--- a/packages/app/e2e/browser/sidebar-workspace.spec.ts
+++ b/packages/app/e2e/browser/sidebar-workspace.spec.ts
@@ -13,6 +13,7 @@ import {
   movePointerAwayFromWorkspaceHoverCard,
   openMobileAgentSidebar,
   pinWorkspaceFromSidebar,
+  scrollWorkspaceList,
 } from "../support/helpers/sidebar";
 import { seedWorkspace } from "../support/helpers/seed-client";
 import { expectWorkspaceHeader } from "../support/helpers/workspace-ui";
@@ -582,6 +583,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 +652,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/split-pane-drag-tracking.spec.ts b/packages/app/e2e/browser/split-pane-drag-tracking.spec.ts
new file mode 100644
index 0000000000..90420c6fd9
--- /dev/null
+++ b/packages/app/e2e/browser/split-pane-drag-tracking.spec.ts
@@ -0,0 +1,134 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+import { test } from "../support/fixtures";
+import { runWorkspaceActionFromCommandCenter } from "../support/helpers/command-center-workspace-actions";
+import { createCreationScenario } from "../support/helpers/creation";
+import { clickNewChat, gotoWorkspace } from "../support/helpers/launcher";
+import { seedWorkspace } from "../support/helpers/seed-client";
+import { waitForWorkspaceTabsVisible } from "../support/helpers/workspace-tabs";
+
+const DRAG_DISTANCE = -40;
+const TOLERANCE_PX = 2;
+
+function splitDividers(page: Page): Locator {
+  return page.getByTestId("workspace-split-resize-handle").filter({ visible: true });
+}
+
+async function dividerX(divider: Locator): Promise<number> {
+  const box = await divider.boundingBox();
+  if (!box) throw new Error("Divider has no bounding box");
+  return box.x;
+}
+
+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();
+}
+
+async function dragDividerWithTouch(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;
+  const input = await page.context().newCDPSession(page);
+  try {
+    await input.send("Input.dispatchTouchEvent", { type: "touchStart", touchPoints: [{ x, y }] });
+    for (let step = 1; step <= 8; step++) {
+      await input.send("Input.dispatchTouchEvent", {
+        type: "touchMove",
+        touchPoints: [{ x: x + (deltaX * step) / 8, y }],
+      });
+    }
+    await input.send("Input.dispatchTouchEvent", { type: "touchEnd", touchPoints: [] });
+  } finally {
+    await input.detach();
+  }
+}
+
+async function splitIntoFourPanes(page: Page): Promise<void> {
+  for (const expectedDividers of [1, 2, 3]) {
+    await runWorkspaceActionFromCommandCenter(page, "Split pane right");
+    await expect(splitDividers(page)).toHaveCount(expectedDividers);
+  }
+}
+
+async function expectDividersTrackPointer(
+  page: Page,
+  distance = DRAG_DISTANCE,
+  drag = dragDivider,
+): Promise<void> {
+  for (const index of [0, 1, 2]) {
+    const divider = splitDividers(page).nth(index);
+    const before = await dividerX(divider);
+    await drag(divider, distance);
+    await expect
+      .poll(async () => Math.abs((await dividerX(divider)) - before - distance), {
+        message: `divider ${index + 1} should stay under the pointer`,
+      })
+      .toBeLessThanOrEqual(TOLERANCE_PX);
+  }
+}
+
+for (const hasTouch of [false, true]) {
+  test.describe(`Split pane drag tracking (${hasTouch ? "coarse" : "fine"} pointer)`, () => {
+    test.use({ hasTouch });
+
+    test("a divider moves as far as the pointer in the main row", async ({ page }) => {
+      await page.setViewportSize({ width: 1600, height: 900 });
+      const workspace = await seedWorkspace({ repoPrefix: "split-drag-tracking-" });
+      try {
+        await gotoWorkspace(page, workspace.workspaceId);
+        await waitForWorkspaceTabsVisible(page);
+        await clickNewChat(page);
+        await splitIntoFourPanes(page);
+        await expectDividersTrackPointer(
+          page,
+          DRAG_DISTANCE,
+          hasTouch ? dragDividerWithTouch : dragDivider,
+        );
+      } finally {
+        await workspace.cleanup();
+      }
+    });
+
+    test("dividers track the pointer after app creation, Explorer changes and reload", async ({
+      page,
+    }) => {
+      await page.setViewportSize({ width: 1600, height: 900 });
+      const creation = await createCreationScenario(page);
+      try {
+        await creation.openWorkspaceForm("local");
+        await creation.submitPrompt("Reply briefly.", "Create");
+        await creation.expectAssistantReply();
+        await waitForWorkspaceTabsVisible(page);
+        await splitIntoFourPanes(page);
+        await expectDividersTrackPointer(page);
+        await page
+          .getByTestId("workspace-explorer-toggle")
+          .filter({ visible: true })
+          .first()
+          .click();
+        await expect(page.getByTestId("workspace-explorer-sidebar")).toBeVisible();
+        await expectDividersTrackPointer(page, -DRAG_DISTANCE);
+        await page
+          .getByTestId("workspace-explorer-toggle")
+          .filter({ visible: true })
+          .first()
+          .click();
+        await expect(page.getByTestId("workspace-explorer-sidebar")).not.toBeVisible();
+        await page.reload();
+        await expect(splitDividers(page)).toHaveCount(3);
+        await expectDividersTrackPointer(page);
+      } finally {
+        await creation.cleanup();
+      }
+    });
+  });
+}
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-retained-tab-stream.spec.ts b/packages/app/e2e/browser/terminal-retained-tab-stream.spec.ts
index c3481110f7..d0dbe9be23 100644
--- a/packages/app/e2e/browser/terminal-retained-tab-stream.spec.ts
+++ b/packages/app/e2e/browser/terminal-retained-tab-stream.spec.ts
@@ -1,5 +1,10 @@
 import type { Page } from "@playwright/test";
 import { expect, test } from "../support/fixtures";
+import {
+  expectTerminalCursor,
+  getTerminalBufferText,
+  waitForTerminalContent,
+} from "../support/helpers/terminal-perf";
 import { TerminalE2EHarness } from "../support/helpers/terminal-dsl";
 
 interface AttachOverlayProbeWindow extends Window {
@@ -59,4 +64,65 @@ test.describe("retained terminal tab streams", () => {
 
     expect(await terminalAttachOverlayWasSeen(page)).toBe(false);
   });
+
+  for (const { count, retainedMarker } of [
+    { count: 3000, retainedMarker: "history-0001界🙂" },
+    { count: 12050, retainedMarker: "history-3000界🙂" },
+  ]) {
+    test(`reattach restores retained styled Unicode history from ${count} lines`, async ({
+      page,
+    }) => {
+      await page.addInitScript(() => {
+        const key = "@paseo:app-settings";
+        const settings = JSON.parse(localStorage.getItem(key) ?? "{}");
+        localStorage.setItem(key, JSON.stringify({ ...settings, terminalScrollbackLines: 10000 }));
+      });
+      const terminal = await harness.createTerminal({
+        name: `history-${count}`,
+        command: "/bin/sh",
+        args: [
+          "-lc",
+          `i=1; while [ $i -le ${count} ]; do printf '\\033[31mhistory-%04d界🙂 payload-abcdefghijklmnopqrstuvwxyz0123456789\\033[0m\\n' $i; i=$((i+1)); done; sleep 120`,
+        ],
+      });
+      const last = `history-${String(count).padStart(4, "0")}界🙂`;
+      await harness.openTerminal(page, { terminalId: terminal.id });
+      await waitForTerminalContent(page, (text) => text.includes(last), 10000);
+      expect(await getTerminalBufferText(page)).toContain(retainedMarker);
+      await page.reload();
+      await waitForTerminalContent(page, (text) => text.includes(last), 10000);
+      const restored = await getTerminalBufferText(page);
+      expect(restored).toContain(retainedMarker);
+      expect(restored.match(/history-\d{4,5}/g)?.length).toBeGreaterThanOrEqual(
+        Math.min(count, 10000),
+      );
+      if (count > 10000) expect(restored).not.toContain("history-0001界🙂");
+    });
+  }
+  for (const input of [
+    { name: "client blinking bar", presentation: "", shape: "bar" as const, blinking: true },
+    {
+      name: "program blinking underline",
+      presentation: "\x1b[3 q",
+      shape: "underline" as const,
+      blinking: true,
+    },
+  ]) {
+    test(`reattach preserves the ${input.name} cursor`, async ({ page }) => {
+      const terminal = await harness.createTerminal({
+        name: "cursor-presentation",
+        command: process.execPath,
+        args: [
+          "-e",
+          `process.stdout.write(${JSON.stringify(input.presentation + "CURSOR-READY\r\n")});setInterval(()=>{},1000)`,
+        ],
+      });
+      await harness.openTerminal(page, { terminalId: terminal.id });
+      await waitForTerminalContent(page, (text) => text.includes("CURSOR-READY"), 10000);
+      await expectTerminalCursor(page, input);
+      await page.reload();
+      await waitForTerminalContent(page, (text) => text.includes("CURSOR-READY"), 10000);
+      await expectTerminalCursor(page, input);
+    });
+  }
 });
diff --git a/packages/app/e2e/browser/tool-call-overview-sheet.spec.ts b/packages/app/e2e/browser/tool-call-overview-sheet.spec.ts
index 42831fad8a..0b3a068e63 100644
--- a/packages/app/e2e/browser/tool-call-overview-sheet.spec.ts
+++ b/packages/app/e2e/browser/tool-call-overview-sheet.spec.ts
@@ -1,8 +1,15 @@
-import type { Page } from "@playwright/test";
+import type { Locator, Page } from "@playwright/test";
 import { test, expect } from "../support/fixtures";
+import { scrollChatAwayFromBottom } from "../support/helpers/agent-bottom-anchor";
+import { gateSecondToolCall } from "../support/helpers/tool-call-gate";
 import { expectComposerVisible } from "../support/helpers/composer";
 import { daemonWsRoutePattern } from "../support/helpers/daemon-port";
 import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+import {
+  readReactRenders,
+  recordReactRenders,
+  resetReactRenders,
+} from "../support/helpers/react-renders";
 
 type WebSocketMessage = string | Buffer;
 
@@ -115,23 +122,27 @@ async function holdStreamAfterFirstCompletedToolCall(page: Page, agentId: string
     });
   });
 
+  function appendCompletedCalls(extraCompletedCalls: number) {
+    if (extraCompletedCalls > 0 && (!firstCallId || !firstCompletedMessage)) {
+      throw new Error("Expected the first completed tool call before release");
+    }
+    for (let index = 0; index < extraCompletedCalls; index += 1) {
+      sendToPage?.(
+        cloneToolCallWithId(
+          firstCompletedMessage as WebSocketMessage,
+          `${firstCallId}:${sequenceOffset + index}`,
+          sequenceOffset + index + 1,
+        ),
+      );
+    }
+    sequenceOffset += extraCompletedCalls;
+  }
   return {
     waitForFirstCompleted: () => firstCompleted,
+    appendCompletedCalls,
     release(extraCompletedCalls = 0) {
       isHolding = false;
-      if (extraCompletedCalls > 0 && (!firstCallId || !firstCompletedMessage)) {
-        throw new Error("Expected the first completed tool call before release");
-      }
-      for (let index = 0; index < extraCompletedCalls; index += 1) {
-        sendToPage?.(
-          cloneToolCallWithId(
-            firstCompletedMessage as WebSocketMessage,
-            `${firstCallId}:${index}`,
-            index + 1,
-          ),
-        );
-      }
-      sequenceOffset = extraCompletedCalls;
+      appendCompletedCalls(extraCompletedCalls);
       for (const message of heldMessages.splice(0)) {
         sendToPage?.(shiftTimelineSequence(message, sequenceOffset));
       }
@@ -139,17 +150,24 @@ async function holdStreamAfterFirstCompletedToolCall(page: Page, agentId: string
   };
 }
 
-async function configureOverviewToolCalls(page: Page): Promise<void> {
-  await page.addInitScript(() => {
+type OverviewChatDisplay = "collapseToolCalls" | "collapseTurns";
+
+// Expand thinking keeps reasoning out of tool call runs, so the first tool call starts alone.
+async function configureOverviewToolCalls(page: Page, chatDisplay: OverviewChatDisplay) {
+  await page.addInitScript((display) => {
     localStorage.setItem(
       "@paseo:app-settings",
-      JSON.stringify({ chatDisplay: "collapseToolCalls" }),
+      JSON.stringify({ chatDisplay: display, autoExpandReasoning: true }),
     );
-  });
+  }, chatDisplay);
 }
 
-async function createOverviewAgent(page: Page, title: string) {
-  await configureOverviewToolCalls(page);
+async function createOverviewAgent(
+  page: Page,
+  title: string,
+  chatDisplay: OverviewChatDisplay = "collapseToolCalls",
+) {
+  await configureOverviewToolCalls(page, chatDisplay);
   return seedMockAgentWorkspace({
     repoPrefix: "tool-call-overview-sheet-",
     title,
@@ -204,6 +222,36 @@ function readScrollMetrics(root: HTMLElement) {
   };
 }
 
+const FIRST_CALL_DETAILS = "export function ConversationList()";
+
+function firstToolCall(page: Page): Locator {
+  return page.getByTestId("tool-call-badge").filter({ hasText: "conversation-list.tsx" }).first();
+}
+
+async function openToolDetails(badge: Locator): Promise<void> {
+  await badge.getByRole("button").first().click();
+}
+
+async function timelineRowOf(locator: Locator) {
+  const row = await locator.locator("xpath=ancestor::*[@data-history-row-id][1]").elementHandle();
+  if (!row) throw new Error("Expected the locator inside a timeline row");
+  return row;
+}
+
+/** Whether the locator renders inside this exact row node, i.e. the row was not remounted. */
+async function isInsideRow(
+  locator: Locator,
+  row: Awaited<ReturnType<typeof timelineRowOf>>,
+): Promise<boolean> {
+  return locator.evaluate((node, previousRow) => previousRow.contains(node), row);
+}
+
+async function topOf(row: Locator): Promise<number> {
+  const box = await row.boundingBox();
+  if (!box) throw new Error("Expected a visible timeline row");
+  return box.y;
+}
+
 test.describe("compact overview tool calls", () => {
   test.use({ viewport: COMPACT_VIEWPORT, hasTouch: true });
 
@@ -219,8 +267,16 @@ test.describe("compact overview tool calls", () => {
       await agent.client.sendAgentMessage(agent.agentId, "Exercise the overview tool-call sheet.");
       await gate.waitForFirstCompleted();
 
+      const single = firstToolCall(page);
+      await expect(single).toBeVisible();
+      await expect(page.getByTestId("tool-call-group")).toHaveCount(0);
+      await openToolDetails(single);
+      await expect(page.getByTestId("tool-call-sheet-close")).toBeVisible();
+      await page.getByTestId("tool-call-sheet-close").click();
+      gate.appendCompletedCalls(1);
       const group = page.getByTestId("tool-call-group").first();
       await expect(group).toBeVisible();
+      await expect(page.getByTestId("tool-call-group-sheet")).toBeHidden();
       await group.click();
 
       const sheet = page.getByTestId("tool-call-group-sheet");
@@ -261,27 +317,86 @@ test.describe("compact overview tool calls", () => {
   });
 });
 
-test("keeps overview tool calls inline on desktop", async ({ page }) => {
+for (const display of ["collapseToolCalls", "collapseTurns"] as const) {
+  test(`keeps an opened lone tool call open when it becomes a group (${display})`, async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+    const agent = await createOverviewAgent(page, "Desktop overview tool calls", display);
+    await recordReactRenders(page);
+    try {
+      const gate = await gateSecondToolCall(page, agent.agentId);
+      await openOverviewAgent(page, agent);
+      await agent.client.sendAgentMessage(agent.agentId, "Exercise desktop overview tool calls.");
+      await gate.waitForFirstCompleted();
+      const lone = firstToolCall(page);
+      const group = page.getByTestId("tool-call-group").first();
+      const details = page.getByText(FIRST_CALL_DETAILS);
+
+      await test.step("a lone tool call shows as itself", async () => {
+        await expect(lone).toBeVisible();
+        await expect(group).toHaveCount(0);
+      });
+
+      await gate.waitForSecondRunning();
+      await test.step("opening it re-renders that tool call and nothing else", async () => {
+        await resetReactRenders(page);
+        await openToolDetails(lone);
+        await expect(details).toBeVisible();
+        const renders = await readReactRenders(page);
+        expect(renders.AgentStreamView ?? 0).toBe(0);
+        expect(renders.StreamRowContent ?? 0).toBe(0);
+        expect(renders.ToolCall).toBe(1);
+      });
+
+      await test.step("the second call forms an open group around the opened call", async () => {
+        // Reading above the tail, the row holds still; at the tail the new rows push it up.
+        await scrollChatAwayFromBottom(page, { deltaY: -160, minDistanceFromBottom: 72 });
+        const loneTop = await topOf(lone);
+        const loneRow = await timelineRowOf(lone);
+        await resetReactRenders(page);
+        gate.releaseSecondRunning();
+        await expect(group.getByTestId("tool-call-badge")).toHaveCount(2);
+        await expect(group.getByText(FIRST_CALL_DETAILS)).toBeVisible();
+        expect(await isInsideRow(group, loneRow)).toBe(true);
+        expect(Math.abs((await topOf(group)) - loneTop)).toBeLessThanOrEqual(2);
+        expect((await readReactRenders(page)).AgentStreamView).toBeGreaterThan(0);
+        await expect(page.getByTestId("tool-call-group-sheet")).toHaveCount(0);
+      });
+
+      await test.step("closing and reopening the group keeps the call open", async () => {
+        await openToolDetails(group);
+        await expect(group.getByTestId("tool-call-badge")).toHaveCount(0);
+        await expect(details).toHaveCount(0);
+        await openToolDetails(group);
+        await expect(group.getByTestId("tool-call-badge")).toHaveCount(2);
+        await expect(group.getByText(FIRST_CALL_DETAILS)).toBeVisible();
+      });
+    } finally {
+      await agent.cleanup();
+    }
+  });
+}
+
+test("forms a closed group when the lone tool call was left closed", async ({ page }) => {
   test.setTimeout(120_000);
-  const agent = await createOverviewAgent(page, "Desktop overview tool calls");
-
+  const agent = await createOverviewAgent(page, "Closed desktop overview tool calls");
   try {
-    const gate = await holdStreamAfterFirstCompletedToolCall(page, agent.agentId);
+    const gate = await gateSecondToolCall(page, agent.agentId);
     await openOverviewAgent(page, agent);
-    await agent.client.sendAgentMessage(agent.agentId, "Exercise desktop overview tool calls.");
+    await agent.client.sendAgentMessage(agent.agentId, "Leave the first tool call closed.");
     await gate.waitForFirstCompleted();
+    const lone = firstToolCall(page);
     const group = page.getByTestId("tool-call-group").first();
+    await expect(lone).toBeVisible();
+    await expect(group).toHaveCount(0);
+
+    await gate.waitForSecondRunning();
+    const loneTop = await topOf(lone);
+    gate.releaseSecondRunning();
     await expect(group).toBeVisible();
-
-    // Keep streaming layout changes out of the pointer-down/pointer-up interval.
-    const header = group.getByRole("button").first();
-    await header.click();
-    await expect(group.getByTestId("tool-call-badge").first()).toBeVisible();
-    await expect(page.getByTestId("tool-call-group-sheet")).toHaveCount(0);
-
-    gate.release(1);
-    await expect.poll(() => group.getByTestId("tool-call-badge").count()).toBeGreaterThanOrEqual(2);
-    await expect(page.getByTestId("tool-call-group-sheet")).toHaveCount(0);
+    await expect(group.getByTestId("tool-call-badge")).toHaveCount(0);
+    expect(Math.abs((await topOf(group)) - loneTop)).toBeLessThanOrEqual(2);
   } finally {
     await agent.cleanup();
   }
diff --git a/packages/app/e2e/browser/tool-call-shimmer.spec.ts b/packages/app/e2e/browser/tool-call-shimmer.spec.ts
index 40dde0aa99..c37255d35e 100644
--- a/packages/app/e2e/browser/tool-call-shimmer.spec.ts
+++ b/packages/app/e2e/browser/tool-call-shimmer.spec.ts
@@ -1,11 +1,9 @@
-import type { Locator, Page } from "@playwright/test";
+import type { Locator } from "@playwright/test";
 import { test, expect } from "../support/fixtures";
-import { daemonWsRoutePattern } from "../support/helpers/daemon-port";
+import { gateSecondToolCall } from "../support/helpers/tool-call-gate";
 import { expectComposerVisible } from "../support/helpers/composer";
 import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
 
-type WebSocketMessage = string | Buffer;
-
 interface ShimmerEvidence {
   animationDuration: string;
   endPx: number;
@@ -14,127 +12,6 @@ interface ShimmerEvidence {
   startPx: number;
 }
 
-function parseSessionMessage(message: WebSocketMessage): Record<string, unknown> | null {
-  const raw = typeof message === "string" ? message : message.toString("utf8");
-  try {
-    const envelope = JSON.parse(raw) as { type?: unknown; message?: unknown };
-    return envelope.type === "session" && envelope.message && typeof envelope.message === "object"
-      ? (envelope.message as Record<string, unknown>)
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function getToolCallStatus(
-  message: WebSocketMessage,
-  agentId: string,
-): { callId: string; status: string } | null {
-  const sessionMessage = parseSessionMessage(message);
-  if (sessionMessage?.type !== "agent_stream") {
-    return null;
-  }
-  const payload = sessionMessage.payload as Record<string, unknown> | undefined;
-  if (payload?.agentId !== agentId) {
-    return null;
-  }
-  const event = payload.event as Record<string, unknown> | undefined;
-  const item = event?.item as Record<string, unknown> | undefined;
-  return event?.type === "timeline" &&
-    item?.type === "tool_call" &&
-    typeof item.callId === "string" &&
-    typeof item.status === "string"
-    ? { callId: item.callId, status: item.status }
-    : null;
-}
-
-function replaceToolCallStatus(message: WebSocketMessage, status: string): string {
-  const raw = typeof message === "string" ? message : message.toString("utf8");
-  const envelope = JSON.parse(raw) as {
-    message?: { payload?: { event?: { item?: { status?: string } } } };
-  };
-  const item = envelope.message?.payload?.event?.item;
-  if (!item) {
-    throw new Error("Expected a tool-call session message");
-  }
-  item.status = status;
-  return JSON.stringify(envelope);
-}
-
-async function gateSecondToolCall(page: Page, agentId: string) {
-  let firstCallId: string | null = null;
-  let secondCallId: string | null = null;
-  let secondRunningMessage: WebSocketMessage | null = null;
-  let pauseAfterSecondRunning = false;
-  let releaseSecondRequested = false;
-  let forwardSecondRunning: (() => void) | null = null;
-  let resolveFirstCompleted!: () => void;
-  let resolveSecondRunning!: () => void;
-  const firstCompleted = new Promise<void>((resolve) => {
-    resolveFirstCompleted = resolve;
-  });
-  const secondRunning = new Promise<void>((resolve) => {
-    resolveSecondRunning = resolve;
-  });
-
-  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
-    const server = ws.connectToServer();
-    forwardSecondRunning = () => {
-      if (secondRunningMessage) {
-        ws.send(secondRunningMessage);
-        secondRunningMessage = null;
-      }
-    };
-    ws.onMessage((message) => server.send(message));
-    server.onMessage((message) => {
-      if (pauseAfterSecondRunning) {
-        return;
-      }
-
-      const toolCall = getToolCallStatus(message, agentId);
-      if (!toolCall) {
-        ws.send(message);
-        return;
-      }
-
-      if (!firstCallId) {
-        firstCallId = toolCall.callId;
-      }
-      if (toolCall.callId === firstCallId) {
-        ws.send(message);
-        if (toolCall.status === "completed") {
-          resolveFirstCompleted();
-        }
-        return;
-      }
-
-      secondCallId ??= toolCall.callId;
-      if (toolCall.callId === secondCallId) {
-        const transformedMessage =
-          toolCall.status === "completed" ? replaceToolCallStatus(message, "running") : message;
-        secondRunningMessage = transformedMessage;
-        pauseAfterSecondRunning = true;
-        resolveSecondRunning();
-        if (releaseSecondRequested) {
-          forwardSecondRunning?.();
-        }
-        return;
-      }
-
-      ws.send(message);
-    });
-  });
-
-  return {
-    waitForFirstCompleted: () => firstCompleted,
-    waitForSecondRunning: () => secondRunning,
-    releaseSecondRunning() {
-      releaseSecondRequested = true;
-      forwardSecondRunning?.();
-    },
-  };
-}
-
 async function readShimmerEvidence(locator: Locator): Promise<ShimmerEvidence> {
   return locator.evaluate((root) => {
     const shimmer = Array.from(root.querySelectorAll<HTMLElement>("*")).find((element) =>
diff --git a/packages/app/e2e/browser/turn-collapse.spec.ts b/packages/app/e2e/browser/turn-collapse.spec.ts
index 1deb050fa8..bcfca2f763 100644
--- a/packages/app/e2e/browser/turn-collapse.spec.ts
+++ b/packages/app/e2e/browser/turn-collapse.spec.ts
@@ -1,8 +1,31 @@
-import type { Page } from "@playwright/test";
+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({
+  e2eDaemonConfig: {
+    version: 1,
+    agents: {
+      providers: {
+        codex: {
+          enabled: true,
+          command: [process.execPath, path.resolve("e2e/fixtures/catalog-codex.mjs")],
+        },
+      },
+    },
+  },
+});
+
 type ChatDisplay = "full" | "collapseToolCalls" | "collapseTurns";
 
 async function useChatDisplay(page: Page, chatDisplay: ChatDisplay): Promise<void> {
@@ -19,34 +42,166 @@ async function seedAnsweredAgent(title: string) {
     initialPrompt: "Why does the chat stop following new output?",
   });
   await agent.client.waitForFinish(agent.agentId, 30_000);
-  await agent.client.sendAgentMessage(agent.agentId, "Make the fix and run the burst script.");
+  await agent.client.sendAgentMessage(
+    agent.agentId,
+    "Make the fix and run the burst script.\n" + "Keep the previous response visible.\n".repeat(40),
+  );
   await agent.client.waitForFinish(agent.agentId, 30_000);
   return agent;
 }
 
 /** 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);
+}
+
+async function groupedToolsInsideLatestTurn(page: Page): Promise<string[]> {
+  return page.evaluate(() => {
+    const rows = [...document.querySelectorAll("[data-message-id]")];
+    const start = rows.findLastIndex((row) => row.querySelector("[data-testid=turn-summary]"));
+    const end = rows.findLastIndex((row) => row.querySelector("[data-testid=assistant-message]"));
+    return rows
+      .slice(start + 1, end)
+      .flatMap((row) =>
+        [...row.querySelectorAll("[data-testid=tool-call-group]")].map(
+          (group) => group.textContent ?? "",
+        ),
+      );
+  });
+}
+
+async function expectCompactMessageToggle(prompt: Locator, label: string) {
+  const button = prompt.getByRole("button", { name: label, exact: true });
+  const text = prompt.getByText(label, { exact: true });
+  await expect
+    .poll(
+      async () => {
+        const control = (await button.boundingBox())!;
+        const glyphs = (await text.boundingBox())!;
+        return control.height - glyphs.height;
+      },
+      { message: "The inline toggle adds no vertical space beyond its text" },
+    )
+    .toBe(0);
+}
+
+async function expandAndCollapseLongPrompt(page: Page) {
+  const prompt = page.getByTestId("user-message").last();
+  const before = await prompt.boundingBox();
+  const text = prompt.locator('[data-message-text="true"]');
+  const messageLeft = (await text.boundingBox())!.x;
+  await expect
+    .poll(async () => (await prompt.getByText("Show more", { exact: true }).boundingBox())!.x)
+    .toBe(messageLeft);
+  await expectCompactMessageToggle(prompt, "Show more");
+  await prompt.getByRole("button", { name: "Show more", exact: true }).click();
+  await expect(prompt.getByRole("button", { name: "Show less", exact: true })).toBeVisible();
+  await expect
+    .poll(async () => (await prompt.getByText("Show less", { exact: true }).boundingBox())!.x)
+    .toBe(messageLeft);
+  await expect
+    .poll(async () => (await prompt.boundingBox())?.height ?? 0)
+    .toBeGreaterThan(before!.height);
+  await expectCompactMessageToggle(prompt, "Show less");
+  await prompt.getByRole("button", { name: "Show less", exact: true }).click();
+  await expect.poll(async () => (await prompt.boundingBox())?.height ?? 0).toBe(before!.height);
+  await prompt.scrollIntoViewIfNeeded();
+  const bounds = (await prompt.boundingBox())!;
+  const body = (await text.boundingBox())!;
+  await page.screenshot({
+    path: "/tmp/message-toggle-aligned.png",
+    clip: {
+      x: body.x - 16,
+      y: bounds.y,
+      width: bounds.x + bounds.width - body.x + 16,
+      height: bounds.height,
+    },
   });
 }
 
 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 });
     await useChatDisplay(page, "collapseTurns");
     const agent = await seedAnsweredAgent("Turn collapse");
     try {
       await openAgentRoute(page, agent);
       await expectComposerVisible(page);
 
+      await expandAndCollapseLongPrompt(page);
+
       const summary = page.getByTestId("turn-summary").last().getByRole("button");
-      await expect(summary).toHaveText(/^Wrote \d+ messages?, edited 1 file/);
+      await expect(summary).toHaveText(/^Edited 1 file/);
       // Text chunks that stream back to back merge into one message, so the reply holds
       // at least the stream's last chunk.
       await expect(page.getByTestId("assistant-message").last()).toHaveText(
@@ -57,6 +212,9 @@ test.describe("Turn collapse", () => {
       await summary.click();
       await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBeGreaterThan(0);
       await expect(summary).toBeInViewport();
+      await summary.evaluate((element) => element.scrollIntoView({ block: "start" }));
+      await page.screenshot({ path: "/tmp/turn-rail-aligned.png" });
+      await expect.poll(() => groupedToolsInsideLatestTurn(page)).toEqual([]);
 
       await summary.click();
       await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBe(0);
@@ -65,3 +223,455 @@ test.describe("Turn collapse", () => {
     }
   });
 });
+
+test("received messages show their sender and open that agent", async ({ page }) => {
+  await page.addInitScript(() =>
+    localStorage.setItem("@paseo:app-settings", JSON.stringify({ theme: "dark" })),
+  );
+  const recipient = await seedMockAgentWorkspace({
+    repoPrefix: "sender-attribution-",
+    title: "Implementation",
+  });
+  try {
+    const sender = await recipient.client.createAgent({
+      provider: "codex",
+      cwd: recipient.cwd,
+      workspaceId: recipient.workspaceId,
+      title: "Reviewer",
+      model: "gpt-6.1-sol",
+      modeId: "full-access",
+    });
+    await recipient.client.sendAgentMessage(
+      recipient.agentId,
+      "I reviewed the turn-grouping changes. Heartbeats now keep their own timing footer, and the previous response stays visible.",
+      { sourceAgentId: sender.id },
+    );
+    await openAgentRoute(page, recipient);
+    await expectComposerVisible(page);
+    const attribution = page.getByRole("button", { name: "Sent by Reviewer", exact: true });
+    await expect(attribution).toBeVisible();
+    await expect(page.getByTestId("user-message").filter({ has: attribution })).toContainText(
+      "I reviewed the turn-grouping changes.",
+    );
+    const labelColor = await attribution
+      .getByText("Sent by Reviewer", { exact: true })
+      .evaluate((element) => getComputedStyle(element).color);
+    await expect(attribution.locator("svg")).toHaveCSS("fill", labelColor);
+    await expectSenderAlignedWithBubble(attribution);
+    await attribution.scrollIntoViewIfNeeded();
+    await page.screenshot({ path: "/tmp/sender-attribution.png" });
+    await attribution.click();
+    await expect.poll(() => getActiveTabTestId(page)).toContain(sender.id);
+  } finally {
+    await recipient.cleanup();
+  }
+});
+
+test("long sender attribution stays on one line in compact chat", async ({ page }, testInfo) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.addInitScript(() =>
+    localStorage.setItem("@paseo:app-settings", JSON.stringify({ theme: "dark" })),
+  );
+  const recipient = await seedMockAgentWorkspace({
+    repoPrefix: "compact-attribution-",
+    title: "Implementation",
+  });
+  try {
+    const title = "Reviewer checking the compact chat timeline and sender attribution";
+    const sender = await recipient.client.createAgent({
+      provider: "codex",
+      cwd: recipient.cwd,
+      workspaceId: recipient.workspaceId,
+      title,
+      model: "gpt-6.1-sol",
+      modeId: "full-access",
+    });
+    await recipient.client.sendAgentMessage(
+      recipient.agentId,
+      "The sender label stays on one line, even when the agent has a long name.",
+      { sourceAgentId: sender.id },
+    );
+    await openAgentRoute(page, recipient);
+    await expectComposerVisible(page);
+    const attribution = page.getByRole("button", { name: `Sent by ${title}`, exact: true });
+    await expect(attribution).toBeVisible();
+    await expectSenderTruncatedWithinMessage(attribution, title);
+    await expectSenderAlignedWithBubble(attribution);
+    await attribution.scrollIntoViewIfNeeded();
+    await page.screenshot({ path: testInfo.outputPath("sender-compact-390.png") });
+    await page.setViewportSize({ width: 320, height: 740 });
+    await expectSenderTruncatedWithinMessage(attribution, title);
+    await expectSenderAlignedWithBubble(attribution);
+    await page.screenshot({ path: testInfo.outputPath("sender-compact-320.png") });
+  } finally {
+    await recipient.cleanup();
+  }
+});
+
+interface MessagePreviewWatch {
+  /** Frames after the watch started on which the fade or "Show more" control was missing. */
+  framesWithoutClip: number[];
+  /** Frames on which the fade was a different DOM node than when the watch started. */
+  framesRemounted: number[];
+}
+
+declare global {
+  interface Window {
+    __paseoMessagePreviewWatch?: { stop(): MessagePreviewWatch };
+  }
+}
+
+async function seedReceivedReviewWithToolTurn() {
+  const recipient = await seedMockAgentWorkspace({
+    repoPrefix: "preview-clip-",
+    title: "Implementation",
+  });
+  const sender = await recipient.client.createAgent({
+    provider: "mock",
+    cwd: recipient.cwd,
+    workspaceId: recipient.workspaceId,
+    title: "Reviewer",
+    modeId: "load-test",
+    model: "e2e-fast-stream",
+  });
+  // Long enough to clip behind the preview fade; the instruction makes the recipient run tools.
+  await recipient.client.sendAgentMessage(
+    recipient.agentId,
+    "Review complete: the regression is red on the baseline and green with the fix.\n" +
+      "Keep the previous response visible while the reader scrolls.\n".repeat(30) +
+      "Now emit 7 tool agent stream updates",
+    { sourceAgentId: sender.id },
+  );
+  return recipient;
+}
+
+/** Samples the received message's bubble on every animation frame until stopped. */
+async function watchReceivedMessagePreview(page: Page, senderLabel: string): Promise<void> {
+  await page.evaluate((label) => {
+    const findBubble = () =>
+      [...document.querySelectorAll("[data-testid=user-message]")].find((row) =>
+        row.textContent?.includes(label),
+      ) ?? null;
+    const initialFade = findBubble()?.querySelector("svg") ?? null;
+    if (!initialFade) throw new Error(`No faded bubble for ${label}`);
+    const framesWithoutClip: number[] = [];
+    const framesRemounted: number[] = [];
+    let frame = 0;
+    let running = true;
+    const sample = () => {
+      if (!running) return;
+      const bubble = findBubble();
+      const fade = bubble?.querySelector("svg") ?? null;
+      if (!fade || !bubble?.textContent?.includes("Show more")) framesWithoutClip.push(frame);
+      else if (fade !== initialFade) framesRemounted.push(frame);
+      frame += 1;
+      requestAnimationFrame(sample);
+    };
+    requestAnimationFrame(sample);
+    window.__paseoMessagePreviewWatch = {
+      stop() {
+        running = false;
+        return { framesWithoutClip, framesRemounted };
+      },
+    };
+  }, senderLabel);
+}
+
+async function expectReceivedMessagePreviewUndisturbed(page: Page): Promise<void> {
+  // Give the opened turn's layout a few frames to settle before judging.
+  await page.evaluate(
+    () => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))),
+  );
+  const watch = await page.evaluate(() => window.__paseoMessagePreviewWatch!.stop());
+  expect(
+    watch.framesWithoutClip,
+    "the preview fade and Show more control stay on every frame",
+  ).toEqual([]);
+  expect(watch.framesRemounted, "the preview keeps its DOM node (no remount)").toEqual([]);
+}
+
+// Opening a turn must not rebuild its host row: the preview above the summary loses its
+// measured height when remounted, which drops the fade and "Show more" for a frame.
+test("opening a turn keeps the received message above it clipped on every frame", async ({
+  page,
+}) => {
+  await useChatDisplay(page, "collapseTurns");
+  const recipient = await seedReceivedReviewWithToolTurn();
+  try {
+    await openAgentRoute(page, recipient);
+    await expectComposerVisible(page);
+    await expect(page.getByText("Completed 7 commands", { exact: true })).toBeVisible({
+      timeout: 30_000,
+    });
+    const bubble = page
+      .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 watchReceivedMessagePreview(page, "Sent by Reviewer");
+    await page
+      .getByTestId("turn-summary")
+      .getByRole("button", { name: "Ran 7 commands", exact: true })
+      .click();
+    await expect(page.getByText("echo stress-6", { exact: true })).toBeVisible();
+    await expectReceivedMessagePreviewUndisturbed(page);
+  } finally {
+    await recipient.cleanup();
+  }
+});
+
+async function expectSenderTruncatedWithinMessage(attribution: Locator, title: string) {
+  const label = attribution.getByText(`Sent by ${title}`, { exact: true });
+  await expect(label).toHaveCSS("white-space", "nowrap");
+  await expect(label).toHaveCSS("text-overflow", "ellipsis");
+  const bounds = await label.evaluate((element) => ({
+    textWidth: element.scrollWidth,
+    visibleWidth: element.clientWidth,
+    right: element.getBoundingClientRect().right,
+    viewportWidth: document.documentElement.clientWidth,
+  }));
+  expect(bounds.textWidth).toBeGreaterThan(bounds.visibleWidth);
+  expect(bounds.right).toBeLessThanOrEqual(bounds.viewportWidth);
+}
+
+async function expectSenderAlignedWithBubble(attribution: Locator) {
+  const edges = await attribution.evaluate((button) => {
+    const bubble = button.nextElementSibling;
+    const label = button.querySelector('[dir="auto"]');
+    if (!bubble || !label) throw new Error("Sender label or message bubble missing");
+    return {
+      labelRight: label.getBoundingClientRect().right,
+      bubbleRight: bubble.getBoundingClientRect().right,
+    };
+  });
+  expect(
+    Math.abs(edges.labelRight - edges.bubbleRight),
+    "sender and bubble share the right edge",
+  ).toBeLessThanOrEqual(1);
+}
+
+async function seedWholeTurnHistory() {
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "whole-turn-history-",
+    title: "Whole turns",
+    model: "e2e-fast-stream",
+  });
+  for (const prompt of [
+    ...Array.from(
+      { length: 25 },
+      (_, index) => `Short ${index}: emit 1 coalesced agent stream updates`,
+    ),
+    "Older long turn: emit 60 tool agent stream updates",
+    "Latest long turn: emit 120 tool agent stream updates",
+  ]) {
+    await agent.client.sendAgentMessage(agent.agentId, prompt);
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+  }
+  return agent;
+}
+
+test("loads complete long turns and preserves expansion while revealing older history", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  await useChatDisplay(page, "collapseTurns");
+  const agent = await seedWholeTurnHistory();
+  try {
+    const history = await holdOlderHistoryPages(page, agent);
+    await openAgentRoute(page, agent);
+    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(120);
+    history.expectNoRepeatedEntries();
+    await latest.scrollIntoViewIfNeeded();
+    await latest.click();
+    await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBe(0);
+  } finally {
+    await agent.cleanup();
+  }
+});
+
+async function useThinkingDisplay(
+  page: Page,
+  autoExpandReasoning: boolean,
+  chatDisplay: ChatDisplay,
+) {
+  await page.addInitScript(
+    (settings) => {
+      localStorage.setItem(
+        "@paseo:app-settings",
+        JSON.stringify({
+          ...settings,
+          chatDisplay: sessionStorage.getItem("e2e-chat-display") ?? settings.chatDisplay,
+        }),
+      );
+    },
+    { autoExpandReasoning, chatDisplay },
+  );
+}
+
+for (const autoExpandReasoning of [false, true]) {
+  test(`reasoning follows Expand thinking (${autoExpandReasoning}) when opening its turn`, async ({
+    page,
+  }) => {
+    await page.setViewportSize({ width: 1280, height: 1000 });
+    await useThinkingDisplay(page, autoExpandReasoning, "collapseToolCalls");
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: "thinking-group-",
+      title: "Thinking with tools",
+      model: "ten-second-stream",
+      initialPrompt: "Inspect the scroll container",
+    });
+    try {
+      await agent.client.waitForFinish(agent.agentId, 30_000);
+      await openAgentRoute(page, agent);
+      await expectComposerVisible(page);
+      const reasoning = page
+        .getByText(/Need to find the scroll container, the layout effect/)
+        .filter({ visible: true })
+        .first();
+      await expectThinkingPresentation(page, autoExpandReasoning);
+      await switchToCollapsedTurns(page);
+      await expectComposerVisible(page);
+      const summary = page.getByTestId("turn-summary").last().getByRole("button");
+      await expect(summary).toBeVisible();
+      await expect(summary).not.toContainText(/thought/i);
+      await expect(reasoning).toHaveCount(0);
+      await summary.click();
+      await expect(reasoning).toHaveCount(autoExpandReasoning ? 1 : 0);
+      await expect.poll(() => groupedToolsInsideLatestTurn(page)).toEqual([]);
+      await openOneToolOutput(page);
+      await summary.click();
+      await expect(reasoning).toHaveCount(0);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+}
+
+async function openOneToolOutput(page: Page) {
+  const output = page.getByText(/\[burst\] tick 1 userIsAtBottom=true/).filter({ visible: true });
+  await expect(output).toHaveCount(0);
+  const command = page
+    .getByTestId("tool-call-badge")
+    .filter({ hasText: "node scripts/simulate-stream-burst.mjs" })
+    .first();
+  await command.getByRole("button").first().click();
+  await expect(output.first()).toBeVisible();
+  await command.getByRole("button").first().click();
+  await expect(output).toHaveCount(0);
+}
+
+async function expectThinkingPresentation(page: Page, autoExpandReasoning: boolean) {
+  const reasoning = page
+    .getByText(/Need to find the scroll container, the layout effect/)
+    .filter({ visible: true })
+    .first();
+  if (autoExpandReasoning) {
+    await expect(reasoning).toBeVisible();
+    await expect(page.getByTestId("tool-call-group").filter({ hasText: /thought/ })).toHaveCount(0);
+  } else {
+    await expect(reasoning).toHaveCount(0);
+    const group = page
+      .getByTestId("tool-call-group")
+      .filter({ hasText: /read 1 file/i, visible: true })
+      .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.
+    const thought = group
+      .getByTestId("tool-call-badge")
+      .filter({ hasText: /^Thinking/ })
+      .first();
+    await expect(thought).toBeVisible();
+    await expect(reasoning).toHaveCount(0);
+    // A press right after the group opens occasionally does not register; retry until the
+    // thought row opens.
+    await expect(async () => {
+      await thought.getByRole("button").first().click();
+      await expect(reasoning).toBeVisible({ timeout: 2_000 });
+    }).toPass();
+  }
+}
+
+async function switchToCollapsedTurns(page: Page) {
+  await page.evaluate(() => {
+    sessionStorage.setItem("e2e-chat-display", "collapseTurns");
+  });
+  await page.reload();
+}
+
+test("a scheduled heartbeat opens a separate turn without reopening the previous response", async ({
+  page,
+}) => {
+  test.setTimeout(90_000);
+  await useChatDisplay(page, "collapseTurns");
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "heartbeat-turn-",
+    title: "Heartbeat turns",
+    model: "ten-second-stream",
+    initialPrompt: "Inspect the scroll container",
+  });
+  const schedules = agent.client as unknown as Pick<
+    DaemonClient,
+    "scheduleCreate" | "scheduleRunOnce" | "scheduleDelete"
+  >;
+  let scheduleId: string | undefined;
+  try {
+    await agent.client.waitForFinish(agent.agentId, 30_000);
+    await openAgentRoute(page, agent);
+    await expectComposerVisible(page);
+    const summaries = page.getByTestId("turn-summary");
+    await expect(summaries).toHaveCount(1);
+    const previousSummary = await summaries.first().innerText();
+    const previousReplyId = await page
+      .getByTestId("assistant-message")
+      .last()
+      .evaluate((element) => element.closest("[data-message-id]")!.getAttribute("data-message-id"));
+    const created = await schedules.scheduleCreate({
+      name: "Check the completed work",
+      prompt: "Inspect the scroll container again",
+      cadence: { type: "cron", expression: "0 0 1 1 *" },
+      target: { type: "self", agentId: agent.agentId },
+      runOnCreate: false,
+    });
+    expect(created.error).toBeNull();
+    scheduleId = created.schedule!.id;
+    const fired = await schedules.scheduleRunOnce({ id: scheduleId });
+    expect(fired.error).toBeNull();
+    await expect(
+      page.getByTestId("tool-call-badge").filter({ hasText: /^Heartbeat/ }),
+    ).toBeVisible();
+    await expect(summaries.first()).toHaveText(previousSummary);
+    const previousReply = page
+      .locator(`[data-message-id="${previousReplyId}"]`)
+      .getByTestId("assistant-message");
+    await expect(previousReply).toBeVisible();
+    await expect(previousReply).toContainText("(end of synthetic stream)");
+    await agent.client.waitForFinish(agent.agentId, 30_000);
+    await expect(summaries).toHaveCount(2);
+    await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBe(0);
+    await expect(page.getByRole("button", { name: /^Worked for/ })).toHaveCount(2);
+    await page.screenshot({ path: "/tmp/heartbeat-turn-footer.png" });
+  } finally {
+    if (scheduleId) await schedules.scheduleDelete({ id: scheduleId });
+    await agent.cleanup();
+  }
+});
diff --git a/packages/app/e2e/browser/usage-modal.spec.ts b/packages/app/e2e/browser/usage-modal.spec.ts
index 1d98f6c591..6835e01bcb 100644
--- a/packages/app/e2e/browser/usage-modal.spec.ts
+++ b/packages/app/e2e/browser/usage-modal.spec.ts
@@ -717,15 +717,15 @@ test("open usage clocks advance without refreshing or reopening", async ({ page
     await openCompactUsageWithClock(page, now);
     const card = page.getByTestId("usage-report-login-journey:account");
     await expect(card.getByTestId("usage-freshness")).toHaveText("Updated just now");
-    await expect(card.getByText("resets 30m", { exact: false }).first()).toBeVisible();
+    await expect(card.getByText("resets in 30m", { exact: false }).first()).toBeVisible();
     // The shared minute clock is wall-aligned, and the daemon timestamps use real time.
     // After two browser minutes the latest displayed tick is one or two minutes old.
     await advanceUsageClock(page, 120_000);
     await expect(card.getByTestId("usage-freshness")).toHaveText(/^Updated [12]m ago$/);
-    await expect(card.getByText(/resets (28|29)m/).first()).toBeVisible();
-    await expect(card.getByText(/runs out (28|29)m/)).toBeVisible();
+    await expect(card.getByText(/resets in (28|29)m/).first()).toBeVisible();
+    await expect(card.getByText(/runs out in (28|29)m/)).toBeVisible();
     await expect(card.getByTestId("provider-usage-balance-credits-reset")).toHaveText(
-      /^resets (28|29)m$/,
+      /^resets in (28|29)m\s·\s/,
     );
   } finally {
     await login.cleanup();
diff --git a/packages/app/e2e/browser/usage-off.spec.ts b/packages/app/e2e/browser/usage-off.spec.ts
new file mode 100644
index 0000000000..a0114c8e33
--- /dev/null
+++ b/packages/app/e2e/browser/usage-off.spec.ts
@@ -0,0 +1,69 @@
+import { expect, test } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import { seedSidebarFooterPreferences } from "../support/helpers/sidebar-nav-settings";
+import { installUsageReportsFixture } from "../support/helpers/usage-reports";
+import {
+  claudeAndCodexReports,
+  openUsageFromIcon,
+  openUsageOptions,
+  closeUsageOptions,
+  closeUsage,
+  expectNoUsageItem,
+  expectPinnedUsage,
+} from "../support/helpers/usage-sidebar-item";
+
+test("Check usage applies to the host and Turn on restores cards", async ({
+  page,
+  e2eWorkerClient,
+}) => {
+  test.setTimeout(180_000);
+  const previous = (await e2eWorkerClient.getDaemonConfig()).config.usage ?? { enabled: true };
+  try {
+    const usage = await installUsageReportsFixture(page, {
+      lists: [() => claudeAndCodexReports()],
+    });
+    await page.setViewportSize({ width: 1440, height: 1000 });
+    await seedSidebarFooterPreferences(page, [{ key: "usage", visible: true }]);
+    await gotoAppShell(page);
+    await expectPinnedUsage(page, ["31% 5h", "54% wk", "7% 5h", "12% wk"]);
+    await openUsageFromIcon(page);
+    await usage.waitForListRequests(1);
+    await openUsageOptions(page);
+    await page.getByRole("switch", { name: "Check usage", exact: true }).click();
+    await closeUsageOptions(page);
+    await expect(page.getByRole("button", { name: "Turn on", exact: true })).toBeVisible();
+    await expect(page.getByRole("button", { name: "Refresh all", exact: true })).toHaveCount(0);
+    expect((await e2eWorkerClient.getDaemonConfig()).config.usage).toEqual({ enabled: false });
+    await expectNoUsageItem(page);
+    const before = usage.listRequests().length;
+    await closeUsage(page);
+    await page.reload();
+    await openUsageFromIcon(page);
+    await expect(page.getByRole("button", { name: "Turn on", exact: true })).toBeVisible();
+    expect(usage.listRequests()).toHaveLength(before);
+    await page.getByRole("button", { name: "Turn on", exact: true }).click();
+    await expect(page.getByText("Claude", { exact: true })).toBeVisible();
+    expect((await e2eWorkerClient.getDaemonConfig()).config.usage).toEqual({ enabled: true });
+    // A separate client changes the policy, as another device would.
+    await e2eWorkerClient.patchDaemonConfig({ usage: { enabled: false } });
+    await expect(page.getByRole("button", { name: "Turn on", exact: true })).toBeVisible();
+    await e2eWorkerClient.patchDaemonConfig({ usage: { enabled: true } });
+    await expect(page.getByText("Claude", { exact: true })).toBeVisible();
+  } finally {
+    await e2eWorkerClient.patchDaemonConfig({ usage: previous });
+  }
+});
+
+test("older hosts keep usage without a Check usage switch", async ({ page }) => {
+  test.setTimeout(180_000);
+  await installUsageReportsFixture(page, {
+    usageSettingSupported: false,
+    lists: [() => claudeAndCodexReports()],
+  });
+  await page.setViewportSize({ width: 1440, height: 1000 });
+  await gotoAppShell(page);
+  await openUsageFromIcon(page);
+  await expect(page.getByText("Claude", { exact: true })).toBeVisible();
+  await openUsageOptions(page);
+  await expect(page.getByRole("switch", { name: "Check usage", exact: true })).toHaveCount(0);
+});
diff --git a/packages/app/e2e/browser/usage-sidebar-item.spec.ts b/packages/app/e2e/browser/usage-sidebar-item.spec.ts
index 27fac6691c..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()] });
@@ -441,3 +547,31 @@ test("released hosts supply source logos through the client conversion", async (
   ).toHaveAttribute("d", codexPath);
   await qaScreenshot(page, "released-host-usage-modal");
 });
+
+test("hidden usage sends no requests until opened", async ({ page }) => {
+  test.setTimeout(180_000);
+  const usage = await installUsageReportsFixture(page, { lists: [() => claudeAndCodexReports()] });
+  await page.setViewportSize(WIDE);
+  await gotoAppShell(page);
+  await expectNoUsageItem(page);
+  await expect(page.getByRole("button", { name: "Usage", exact: true })).toBeVisible({
+    timeout: 90_000,
+  });
+  await openSidebarNavSettings(page);
+  await expectFooterItemSetting(page, "usage", false);
+  await leaveSettings(page);
+  expect(usage.listRequests()).toHaveLength(0);
+  await openUsageFromIcon(page);
+  await usage.waitForListRequests(1);
+  expect(usage.listRequests()).toHaveLength(1);
+});
+
+test("visible usage summary requests reports on load", async ({ page }) => {
+  test.setTimeout(180_000);
+  const usage = await installUsageReportsFixture(page, { lists: [() => claudeAndCodexReports()] });
+  await seedSidebarFooterPreferences(page, [{ key: "usage", visible: true }]);
+  await page.setViewportSize(WIDE);
+  await gotoAppShell(page);
+  await expectPinnedUsage(page, ["31% 5h", "54% wk", "7% 5h", "12% wk"]);
+  expect(usage.listRequests()).toHaveLength(1);
+});
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..90e47aab3c
--- /dev/null
+++ b/packages/app/e2e/browser/workspace-archive-undo.spec.ts
@@ -0,0 +1,186 @@
+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,
+  outlastUndoWindow,
+  pressUndoShortcut,
+  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(),
+    ]);
+    expect(buttonBox && kebabBox && buttonBox.x + buttonBox.width <= kebabBox.x).toBe(true);
+  });
+
+  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);
+  });
+
+  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/fixtures/fake-pi-rpc.mjs b/packages/app/e2e/fixtures/fake-pi-rpc.mjs
index b6d156ddfc..372e29c44b 100644
--- a/packages/app/e2e/fixtures/fake-pi-rpc.mjs
+++ b/packages/app/e2e/fixtures/fake-pi-rpc.mjs
@@ -6,6 +6,7 @@ for await (const line of lines) {
   const command = JSON.parse(line);
   let data = {};
   if (command.type === "get_available_models") {
+    if (process.argv.includes("--stall-model-discovery")) continue;
     data = {
       models: [
         {
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/agent-device/native-user-message-preview-preconditions.md b/packages/app/e2e/mobile/agent-device/native-user-message-preview-preconditions.md
new file mode 100644
index 0000000000..9985a3f544
--- /dev/null
+++ b/packages/app/e2e/mobile/agent-device/native-user-message-preview-preconditions.md
@@ -0,0 +1,14 @@
+# Native user message preview
+
+Open a chat with a user message containing 16 newline-separated lines of
+`Preview line N`, with N from 1 to 16. Scroll the message into view on a
+phone-sized Android emulator or iOS simulator. Its text must exceed the 240-point preview cap,
+while its expanded bubble and toggle fit in the chat viewport. Close any other
+expanded messages so the toggle labels identify this message.
+
+Replay `native-user-message-preview.android.ad` or
+`native-user-message-preview.ios.ad` through the existing mobile runner or
+agent-device. It checks that a clipped message offers Show more and
+that two expand/collapse round trips keep both controls reachable. Before the
+fix, the first Show more assertion fails because native layout reports the
+capped height as the full content height.
diff --git a/packages/app/e2e/mobile/agent-device/native-user-message-preview.android.ad b/packages/app/e2e/mobile/agent-device/native-user-message-preview.android.ad
new file mode 100644
index 0000000000..45630217bb
--- /dev/null
+++ b/packages/app/e2e/mobile/agent-device/native-user-message-preview.android.ad
@@ -0,0 +1,14 @@
+context platform=android timeout=60000 retries=0
+env APP_ID=sh.paseo.debug
+
+open "${APP_ID}"
+wait "role=\"button\" label=\"Show more\"" 10000
+press "role=\"button\" label=\"Show more\""
+wait "role=\"button\" label=\"Show less\"" 10000
+press "role=\"button\" label=\"Show less\""
+wait "role=\"button\" label=\"Show more\"" 10000
+press "role=\"button\" label=\"Show more\""
+wait "role=\"button\" label=\"Show less\"" 10000
+press "role=\"button\" label=\"Show less\""
+wait "role=\"button\" label=\"Show more\"" 10000
+close
diff --git a/packages/app/e2e/mobile/agent-device/native-user-message-preview.ios.ad b/packages/app/e2e/mobile/agent-device/native-user-message-preview.ios.ad
new file mode 100644
index 0000000000..d19d7dd8aa
--- /dev/null
+++ b/packages/app/e2e/mobile/agent-device/native-user-message-preview.ios.ad
@@ -0,0 +1,14 @@
+context platform=ios timeout=60000 retries=0
+env APP_ID=sh.paseo.debug
+
+open "${APP_ID}"
+wait "role=\"button\" label=\"Show more\"" 10000
+press "role=\"button\" label=\"Show more\""
+wait "role=\"button\" label=\"Show less\"" 10000
+press "role=\"button\" label=\"Show less\""
+wait "role=\"button\" label=\"Show more\"" 10000
+press "role=\"button\" label=\"Show more\""
+wait "role=\"button\" label=\"Show less\"" 10000
+press "role=\"button\" label=\"Show less\""
+wait "role=\"button\" label=\"Show more\"" 10000
+close
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/fold/android.mjs b/packages/app/e2e/mobile/fold/android.mjs
new file mode 100644
index 0000000000..93f23dc111
--- /dev/null
+++ b/packages/app/e2e/mobile/fold/android.mjs
@@ -0,0 +1,104 @@
+// Run a release build with a connected workspace open and the keyboard hidden.
+// ANDROID_SERIAL=emulator-5574 node packages/app/e2e/mobile/fold/android.mjs
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+const serial = process.env.ANDROID_SERIAL;
+assert(serial, "Set ANDROID_SERIAL to a booted Android foldable emulator");
+const appId = process.env.PASEO_MOBILE_APP_ID ?? "sh.paseo.debug";
+const session = "android-fold";
+const artifacts = resolve(".dev/agent-device-artifacts/android-fold");
+const env = {
+  ...process.env,
+  AGENT_DEVICE_STATE_DIR: resolve(".dev/agent-device-android-fold"),
+};
+mkdirSync(artifacts, { recursive: true });
+
+function run(binary, args) {
+  return execFileSync(binary, args, { env, encoding: "utf8", timeout: 60_000 });
+}
+function adb(...args) {
+  return run("adb", ["-s", serial, ...args]);
+}
+function ad(...args) {
+  return run("agent-device", [...args, "--session", session]);
+}
+function pid() {
+  return adb("shell", "pidof", appId).trim();
+}
+function open() {
+  ad("open", appId, "--platform", "android", "--serial", serial, "--no-test-ime");
+}
+function stateId(name) {
+  const states = adb("shell", "cmd", "device_state", "print-states");
+  const match = states.match(new RegExp(`identifier=(\\d+), name='${name}'`));
+  assert(match, `Emulator must expose the ${name} posture: ${states}`);
+  return match[1];
+}
+
+async function expectLayout(posture) {
+  const compact = posture === "CLOSED";
+  const expectedId = compact ? "workspace-tab-switcher-trigger" : "workspace-tabs-scroll";
+  const unexpectedId = compact ? "workspace-tabs-scroll" : "workspace-tab-switcher-trigger";
+  const deadline = Date.now() + 15_000;
+  let nodes = [];
+  do {
+    let data;
+    try {
+      ({ data } = JSON.parse(ad("snapshot", "-i", "--json")));
+    } catch (error) {
+      // During display handoff Android briefly has no capturable app window.
+      if (!error.stdout?.includes("insufficient foreground app content")) throw error;
+      await delay(200);
+      continue;
+    }
+    assert.equal(data.appBundleId, appId, "Snapshot must belong to Paseo");
+    nodes = data.nodes;
+    if (
+      nodes.some((node) => node.identifier === expectedId) &&
+      !nodes.some((node) => node.identifier === unexpectedId)
+    ) {
+      writeFileSync(resolve(artifacts, `${posture}.json`), JSON.stringify(data, null, 2));
+      console.log(`PASS: ${posture} uses ${compact ? "compact" : "wide"} workspace controls`);
+      return;
+    }
+    await delay(200);
+  } while (Date.now() < deadline);
+  writeFileSync(resolve(artifacts, `${posture}-failure.json`), JSON.stringify(nodes, null, 2));
+  writeFileSync(
+    resolve(artifacts, "native-failure.txt"),
+    adb("shell", "dumpsys", "activity", "top"),
+  );
+  assert.fail(`${posture}: expected ${expectedId}, without ${unexpectedId}`);
+}
+
+const closed = stateId("CLOSED");
+const opened = stateId("OPENED");
+const initialState = adb("shell", "cmd", "device_state", "state").match(
+  /Committed state: DeviceState\{identifier=(\d+)/,
+)?.[1];
+assert(initialState, "Could not read the initial fold state");
+
+try {
+  adb("shell", "cmd", "device_state", "state", opened);
+  open();
+  await expectLayout("OPENED");
+  const initialPid = pid();
+  for (const [posture, id] of [
+    ["CLOSED", closed],
+    ["OPENED", opened],
+  ]) {
+    adb("shell", "input", "keyevent", "KEYCODE_HOME");
+    adb("shell", "cmd", "device_state", "state", id);
+    // Resume immediately: waiting for configuration delivery hides the regression.
+    open();
+    await expectLayout(posture);
+    assert.equal(pid(), initialPid, "Fold/resume must preserve the app process");
+  }
+} finally {
+  adb("shell", "cmd", "device_state", "state", initialState);
+  ad("close");
+}
diff --git a/packages/app/e2e/mobile/markdown-formatting/README.md b/packages/app/e2e/mobile/markdown-formatting/README.md
index c2ab0ddc65..28cdb87c6b 100644
--- a/packages/app/e2e/mobile/markdown-formatting/README.md
+++ b/packages/app/e2e/mobile/markdown-formatting/README.md
@@ -12,6 +12,22 @@ point and Metro workflow in [status-ring](../status-ring/README.md), importing
 `MarkdownFormattingRegression` from `./e2e/mobile/markdown-formatting/native`.
 Open the same Metro URL in a browser to compare web. Restore `index.ts` afterward.
 
+With this fixture open in an Android Agent Device session, run:
+
+```sh
+node packages/app/e2e/mobile/markdown-formatting/android.mjs <session>
+```
+
+The runner switches to paragraphs with long inline code at a fixed 300 dp width.
+It compares the native Markdown host’s bottom with its last TextView’s bottom,
+then repeats in compact mode and after restoring regular text. More than one
+pixel of surplus fails. Keep the whole fixture visible: clipped accessibility
+bounds cannot establish measurement parity.
+
+`scripts/postinstall-patches.test.mjs` regenerates both platforms’ props and
+compares them with the shipped headers. This catches missing C++ fields in the
+measurement path, which the Kotlin tests cannot exercise.
+
 The package patch contains `InlineCodeFormattingTest`, which exercises actual
 Android spans in Robolectric native graphics mode, covering draw and measurement,
 span order, code inside paragraph/heading sizes, bold/italic composition, and
diff --git a/packages/app/e2e/mobile/markdown-formatting/android.mjs b/packages/app/e2e/mobile/markdown-formatting/android.mjs
new file mode 100644
index 0000000000..c015edcb3a
--- /dev/null
+++ b/packages/app/e2e/mobile/markdown-formatting/android.mjs
@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+
+const session = process.argv[2];
+assert(session, "Pass an Android agent-device session serving native.tsx");
+function ad(...args) {
+  return execFileSync("agent-device", ["--session", session, ...args], {
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+}
+
+function assertMeasurementParity(mode) {
+  const snapshot = JSON.parse(ad("snapshot", "--raw", "--json"));
+  assert.equal(snapshot.success, true);
+  const nodes = snapshot.data.nodes;
+  let last = nodes.find((node) => node.label?.endsWith("End of measurement fixture."));
+  assert(last?.rect, "The last paragraph must be visible, including its bottom");
+  // EnrichedMarkdownText exposes paragraph accessibility nodes inside its TextView;
+  // EnrichedMarkdown exposes the TextViews themselves. Measure the native child.
+  let host = nodes.find((node) => node.index === last.parentIndex);
+  if (host?.type === "android.widget.TextView") {
+    last = host;
+    host = nodes.find((node) => node.index === last.parentIndex);
+  }
+  assert.equal(host?.type, "android.widget.FrameLayout");
+  const viewport = nodes.find((node) => node.type === "android.widget.ScrollView");
+  const footer = nodes.find((node) => node.label === "End of Markdown host");
+  assert(viewport?.rect && footer?.rect, "The fixture and footer must be visible");
+  assert(
+    host.rect.y >= viewport.rect.y &&
+      footer.rect.y + footer.rect.height <= viewport.rect.y + viewport.rect.height,
+    "The whole fixture must fit in the viewport; clipped bounds cannot prove parity",
+  );
+  const hostBottom = host.rect.y + host.rect.height;
+  const childBottom = last.rect.y + last.rect.height;
+  console.log(
+    JSON.stringify({
+      mode,
+      host: host.rect,
+      lastChild: last.rect,
+      surplus: hostBottom - childBottom,
+    }),
+  );
+  assert(
+    Math.abs(hostBottom - childBottom) <= 1,
+    `Markdown reserves blank space in ${mode}: host bottom ${hostBottom}, last child bottom ${childBottom}`,
+  );
+}
+
+ad("press", 'label="Show wrapping fixture"');
+ad("wait", "text", "End of Markdown host", "10000");
+assertMeasurementParity("regular");
+ad("press", 'label="Use compact text"');
+ad("wait", "text", "Use regular text", "10000");
+assertMeasurementParity("compact");
+ad("press", 'label="Use regular text"');
+ad("wait", "text", "Use compact text", "10000");
+assertMeasurementParity("regular restored");
+console.log("PASS Android Markdown host measurement matches its last child");
diff --git a/packages/app/e2e/mobile/markdown-formatting/native.tsx b/packages/app/e2e/mobile/markdown-formatting/native.tsx
index d5d9a64aa0..e28f8a9900 100644
--- a/packages/app/e2e/mobile/markdown-formatting/native.tsx
+++ b/packages/app/e2e/mobile/markdown-formatting/native.tsx
@@ -1,6 +1,6 @@
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { useCallback, useState } from "react";
-import { Button, ScrollView, Text } from "react-native";
+import { Button, ScrollView, Text, View } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
 import { MarkdownRenderer } from "@/components/markdown/renderer";
@@ -10,6 +10,7 @@ const styles = StyleSheet.create((theme) => ({
   scroll: { backgroundColor: theme.colors.surface0 },
   content: { padding: 32, paddingTop: 60 },
   title: { color: theme.colors.foreground },
+  wrapping: { width: 300 },
 }));
 
 const queryClient = new QueryClient();
@@ -32,7 +33,15 @@ const source = [
   "Normal **bold** and *italic* prose.",
 ].join("\n\n");
 
+const wrappingSource = [
+  "Measurement parity. Take a repo with a gitignored `.env` in the main checkout and a `.worktreeinclude` containing `.env`.",
+  "Every creation path goes through `createPaseoWorktreeWorkflow` in `worktree-session.ts:341`, before `createAgent` in `creation/index.ts:160-174` starts.",
+  "The built-in plugin lives in `plugins/worktree-include/index.server.ts` and copies `paseo.json` beside `.worktreeinclude`. End of measurement fixture.",
+].join("\n\n");
+
 export default function MarkdownFormattingRegression() {
+  const [wrapping, setWrapping] = useState(false);
+  const toggleWrapping = useCallback(() => setWrapping((value) => !value), []);
   const [compact, setCompact] = useState(false);
   const toggleCompact = useCallback(() => setCompact((value) => !value), []);
   return (
@@ -44,7 +53,14 @@ export default function MarkdownFormattingRegression() {
             title={compact ? "Use regular text" : "Use compact text"}
             onPress={toggleCompact}
           />
-          <MarkdownRenderer text={source} compact={compact} />
+          <Button
+            title={wrapping ? "Show formatting fixture" : "Show wrapping fixture"}
+            onPress={toggleWrapping}
+          />
+          <View style={wrapping ? styles.wrapping : undefined}>
+            <MarkdownRenderer text={wrapping ? wrappingSource : source} compact={compact} />
+          </View>
+          <Text style={styles.title}>End of Markdown host</Text>
         </ScrollView>
       </GestureHandlerRootView>
     </QueryClientProvider>
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
new file mode 100644
index 0000000000..92287e0586
--- /dev/null
+++ b/packages/app/e2e/mobile/terminal-rendering/check.mjs
@@ -0,0 +1,314 @@
+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";
+
+/** A pixel is ink when one channel differs from the terminal background by more than this. */
+const INK_THRESHOLD = 70;
+/** Ink pixels a printed grapheme cluster needs inside its own columns. */
+const MIN_CLUSTER_INK = 3;
+/** How far a pixel may sit from the background-to-color blend line and still count as that color. */
+const BLEND_TOLERANCE = 40;
+/** Pixels of another cell's color tolerated in a cell, for antialiasing at the cell edge. */
+const MAX_FOREIGN_INK = 2;
+
+const graphemes = new Intl.Segmenter("und", { granularity: "grapheme" });
+
+/**
+ * Checks a screenshot of the fixture against the cells xterm assigns: every printed grapheme
+ * cluster has ink inside its own columns, blank cells stay blank, and the cursor sits right after
+ * the text. A cluster that spans cells, such as a Devanagari conjunct, is shaped as one unit, so
+ * it is judged across all its columns. On rows that use the fixture's accent color, every cell
+ * must be drawn in its own color, including cells that share a shaped cluster.
+ *
+ * These are geometry and color checks: they cannot tell a correct glyph from a wrong one.
+ *
+ * `rows` maps a terminal row index to its rect in screenshot pixels.
+ */
+export async function checkTerminalScreenshot({ png, size, rows }) {
+  const terminal = await fixtureTerminal(size);
+  assert.ok(rows.get(0), "The ruler row is not exposed as terminal-row-0");
+  const grid = measureGrid(png, rows.get(0));
+  const { failures, slots } = checkRows({ png, terminal, rows, grid });
+  terminal.dispose();
+  return { grid, failures, slots };
+}
+
+/** Where the harness selects: the first cell of the conjunct that starts the `select` line. */
+export async function selectionTarget({ size }) {
+  const terminal = await fixtureTerminal(size);
+  const row = lineNames(terminal.buffer.active, terminal.buffer.active.cursorY + 1).indexOf(
+    SELECT_LINE,
+  );
+  terminal.dispose();
+  return { row, col: 0, clusterColumns: 2 };
+}
+
+/**
+ * Checks a screenshot taken with only the first cell of the `select` conjunct selected: that cell
+ * has the selection background and the conjunct's second, unselected cell keeps its accent color.
+ */
+export function checkPartialSelection({ png, rows, grid, target }) {
+  const rect = rows.get(target.row);
+  if (!rect) return [{ row: target.row, kind: "missing-row" }];
+  const cell = (col) => ({
+    left: grid.left + col * grid.cellWidth + 1,
+    right: grid.left + (col + 1) * grid.cellWidth - 1,
+    top: rect.y,
+    bottom: rect.y + rect.height,
+  });
+  const selected = cell(target.col);
+  const unselected = cell(target.col + 1);
+  const selectionBackground = pixelAt(png, selected.left + 1, selected.top + 1);
+  const unselectedBackground = pixelAt(png, unselected.left + 1, unselected.top + 1);
+  if (
+    !differs(selectionBackground, grid.background) ||
+    differs(unselectedBackground, grid.background)
+  ) {
+    return [{ row: target.row, col: target.col, kind: "selection-not-set-up" }];
+  }
+  const failures = [];
+  const ownInk = countColor(png, unselected, grid.background, ACCENT);
+  if (ownInk < MIN_CLUSTER_INK) {
+    failures.push({ row: target.row, col: target.col + 1, kind: "unselected-cell-lost-color" });
+  }
+  return failures;
+}
+
+async function fixtureTerminal(size) {
+  const terminal = new xterm.Terminal({
+    cols: size.columns,
+    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),
+  );
+  return terminal;
+}
+
+export function writeOverlay(png, slots, path) {
+  const out = new PNG({ width: png.width, height: png.height });
+  png.data.copy(out.data);
+  for (const slot of slots) {
+    const color = slot.ok ? [0, 200, 0] : [255, 0, 0];
+    const { left, right, top, bottom } = slot.box;
+    for (let x = Math.ceil(left); x < right; x += 1) {
+      for (const y of [Math.ceil(top), Math.floor(bottom) - 1]) {
+        const offset = (out.width * y + x) * 4;
+        out.data.set(color, offset);
+      }
+    }
+    if (!slot.ok) {
+      for (let y = Math.ceil(top); y < bottom; y += 1) {
+        for (const x of [Math.ceil(left), Math.floor(right) - 1]) {
+          out.data.set(color, (out.width * y + x) * 4);
+        }
+      }
+    }
+  }
+  writeFileSync(path, PNG.sync.write(out));
+}
+
+function inkAt(png, x, y, background) {
+  const offset = (png.width * Math.round(y) + Math.round(x)) * 4;
+  return (
+    Math.abs(png.data[offset] - background[0]) > INK_THRESHOLD ||
+    Math.abs(png.data[offset + 1] - background[1]) > INK_THRESHOLD ||
+    Math.abs(png.data[offset + 2] - background[2]) > INK_THRESHOLD
+  );
+}
+
+/** Pixels in `box` that differ from `background` in some channel by more than the ink threshold. */
+export function countInk(png, box, background) {
+  let count = 0;
+  for (let y = Math.ceil(box.top); y < Math.floor(box.bottom); y += 1) {
+    for (let x = Math.ceil(box.left); x < Math.floor(box.right); x += 1) {
+      if (inkAt(png, x, y, background)) count += 1;
+    }
+  }
+  return count;
+}
+
+function differs(a, b) {
+  return a.some((channel, index) => Math.abs(channel - b[index]) > INK_THRESHOLD);
+}
+
+/** Distance from `pixel` to the nearest blend of `background` toward `color`. */
+function blendDistance(pixel, background, color) {
+  const direction = color.map((channel, index) => channel - background[index]);
+  const length = direction.reduce((sum, value) => sum + value * value, 0);
+  const offset = pixel.map((channel, index) => channel - background[index]);
+  const along = offset.reduce((sum, value, index) => sum + value * direction[index], 0);
+  const alpha = length === 0 ? 0 : Math.min(1, Math.max(0, along / length));
+  return Math.hypot(...offset.map((value, index) => value - alpha * direction[index]));
+}
+
+/** Ink pixels in `box` that are a blend of the background toward `color`. */
+function countColor(png, box, background, color, other) {
+  let count = 0;
+  for (let y = Math.ceil(box.top); y < Math.floor(box.bottom); y += 1) {
+    for (let x = Math.ceil(box.left); x < Math.floor(box.right); x += 1) {
+      if (!inkAt(png, x, y, background)) continue;
+      const pixel = pixelAt(png, x, y);
+      const distance = blendDistance(pixel, background, color);
+      if (distance > BLEND_TOLERANCE) continue;
+      if (other && blendDistance(pixel, background, other) <= distance) continue;
+      count += 1;
+    }
+  }
+  return count;
+}
+
+function pixelAt(png, x, y) {
+  const offset = (png.width * Math.round(y) + Math.round(x)) * 4;
+  return [png.data[offset], png.data[offset + 1], png.data[offset + 2]];
+}
+
+/** Reads the grid origin and cell width from a ruler row of `RULER_CELLS` full blocks. */
+export function measureGrid(png, rulerRect) {
+  const y = rulerRect.y + rulerRect.height / 2;
+  const background = pixelAt(png, rulerRect.x + rulerRect.width - 2, y);
+  let left = -1;
+  let right = -1;
+  for (let x = Math.ceil(rulerRect.x); x < rulerRect.x + rulerRect.width; x += 1) {
+    if (!inkAt(png, x, y, background)) continue;
+    if (left < 0) left = x;
+    right = x + 1;
+  }
+  assert.ok(left >= 0, "The ruler row has no ink");
+  const foreground = pixelAt(png, Math.round((left + right) / 2), y);
+  return { left, cellWidth: (right - left) / RULER_CELLS, background, foreground };
+}
+
+function lineNames(buffer, count) {
+  const names = fixtureLines(0).map((line) => line.name);
+  const result = [];
+  let index = -1;
+  for (let row = 0; row < count; row += 1) {
+    if (!buffer.getLine(row).isWrapped) index += 1;
+    result.push(names[index] ?? `line-${index}`);
+  }
+  return result;
+}
+
+/** The row's printed cells, consecutive cells of one grapheme cluster grouped together. */
+function rowClusters(line, columns, cell) {
+  const cells = [];
+  let text = "";
+  for (let col = 0; col < columns; col += 1) {
+    line.getCell(col, cell);
+    const width = cell.getWidth();
+    if (width === 0) continue;
+    const chars = cell.getChars() || " ";
+    cells.push({
+      col,
+      width,
+      chars,
+      offset: text.length,
+      painted: cell.isInverse() || !cell.isBgDefault(),
+      accent: cell.isFgRGB() && cell.getFgColor() === rgbValue(ACCENT),
+    });
+    text += chars;
+  }
+  const clusterEnds = [...graphemes.segment(text)].map(
+    (segment) => segment.index + segment.segment.length,
+  );
+  const clusters = [];
+  let end = 0;
+  for (const entry of cells) {
+    while (entry.offset >= clusterEnds[end]) end += 1;
+    const last = clusters.at(-1);
+    if (last && last.end === end) last.cells.push(entry);
+    else clusters.push({ end, cells: [entry] });
+  }
+  return clusters.map((cluster) => cluster.cells);
+}
+
+function rgbValue([red, green, blue]) {
+  return (red << 16) | (green << 8) | blue;
+}
+
+/** Each cell of a cluster that uses the accent color holds ink of its own color only. */
+function checkClusterColors({ png, cluster, rect, grid }) {
+  const kinds = [];
+  for (const entry of cluster) {
+    const box = {
+      left: grid.left + entry.col * grid.cellWidth + 1,
+      right: grid.left + (entry.col + entry.width) * grid.cellWidth - 1,
+      top: rect.y,
+      bottom: rect.y + rect.height,
+    };
+    const [color, other] = entry.accent ? [ACCENT, grid.foreground] : [grid.foreground, ACCENT];
+    const own = countColor(png, box, grid.background, color, other);
+    const foreign = countColor(png, box, grid.background, other, color);
+    if (own < MIN_CLUSTER_INK || foreign > MAX_FOREIGN_INK) {
+      kinds.push({ col: entry.col, kind: entry.accent ? "accent-color-lost" : "color-leaked" });
+    }
+  }
+  return kinds;
+}
+
+function checkRows({ png, terminal, rows, grid }) {
+  const buffer = terminal.buffer.active;
+  const lastRow = buffer.cursorY;
+  const names = lineNames(buffer, lastRow + 1);
+  const failures = [];
+  const slots = [];
+  const cell = buffer.getNullCell();
+  for (let row = 0; row <= lastRow; row += 1) {
+    const rect = rows.get(row);
+    if (!rect) {
+      failures.push({ row, line: names[row], kind: "missing-row" });
+      continue;
+    }
+    const clusters = rowClusters(buffer.getLine(row), terminal.cols, cell);
+    // Color is judged on whole rows that use the accent, so a color leaking into a neighbouring
+    // default-colored cell fails too.
+    const checksColor = clusters.some((cluster) => cluster.some((entry) => entry.accent));
+    for (const cluster of clusters) {
+      const first = cluster[0];
+      const columns = cluster.reduce((sum, entry) => sum + entry.width, 0);
+      const left = grid.left + first.col * grid.cellWidth;
+      const right = left + columns * grid.cellWidth;
+      const box = { left: left + 1, right: right - 1, top: rect.y, bottom: rect.y + rect.height };
+      const chars = cluster.map((entry) => entry.chars).join("");
+      const isCursor = row === lastRow && first.col === buffer.cursorX;
+      let kind = null;
+      if (isCursor) {
+        const covered = countInk(png, box, grid.background);
+        const area = (box.right - box.left) * (box.bottom - box.top);
+        if (covered < area * 0.25) kind = "cursor-not-drawn";
+      } else if (chars.trim() !== "") {
+        if (countInk(png, box, grid.background) < MIN_CLUSTER_INK) kind = "missing-ink";
+      } else if (!cluster.some((entry) => entry.painted)) {
+        const quarter = (right - left) / 4;
+        const center = { ...box, left: left + quarter, right: right - quarter };
+        if (countInk(png, center, grid.background) > 0) kind = "ink-in-blank";
+      }
+      const colorFailures =
+        kind === null && checksColor && chars.trim() !== ""
+          ? checkClusterColors({ png, cluster, rect, grid })
+          : [];
+      slots.push({
+        row,
+        line: names[row],
+        col: first.col,
+        width: columns,
+        chars,
+        isCursor,
+        box,
+        ok: kind === null && colorFailures.length === 0,
+      });
+      if (kind) failures.push({ row, line: names[row], col: first.col, char: chars, kind });
+      for (const failure of colorFailures) {
+        failures.push({ row, line: names[row], char: chars, ...failure });
+      }
+    }
+  }
+  return { failures, slots };
+}
diff --git a/packages/app/e2e/mobile/terminal-rendering/fixture.mjs b/packages/app/e2e/mobile/terminal-rendering/fixture.mjs
new file mode 100644
index 0000000000..e4ff5c2bb4
--- /dev/null
+++ b/packages/app/e2e/mobile/terminal-rendering/fixture.mjs
@@ -0,0 +1,59 @@
+// Terminal output covering the scripts and styles the native renderer must place on the grid.
+// Each entry is one line of output; `ruler` is drawn with full blocks so the harness can read
+// the grid origin and cell width from pixels, independent of the renderer under test.
+
+const ESC = "\u001b";
+const sgr = (codes, text) => `${ESC}[${codes}m${text}${ESC}[0m`;
+
+export const RULER_CELLS = 20;
+/** A foreground no theme uses, so its pixels can be told apart from default text. */
+export const ACCENT = [255, 64, 160];
+const accent = (text) => sgr(`38;2;${ACCENT.join(";")}`, text);
+/**
+ * The `select` line starts with a conjunct whose first cell the harness selects on its own. Its
+ * second cell uses the accent, which no theme's selection foreground matches.
+ */
+export const SELECT_LINE = "select";
+
+export function fixtureLines(columns) {
+  const wrapSyllables = Math.ceil(columns / 2) + 6;
+  return [
+    { name: "ruler", text: "█".repeat(RULER_CELLS) },
+    { name: "ascii", text: "ASCII abcdefghij 0123456789 end" },
+    { name: "hangul-mixed", text: "한글 문장 Hello end" },
+    { name: "hangul-color-boundary", text: `안녕하세요${sgr(31, "NEXT")} end` },
+    { name: "hangul-bold-boundary", text: `${sgr(1, "안녕하세요")}NEXT end` },
+    { name: "hangul-decomposed", text: "한글 end" },
+    { name: "cjk", text: "日本語テキスト 中文字符 end" },
+    { name: "combining", text: "é ä ñ x̣̂ end" },
+    { name: "arabic", text: "مرحبا لا 123 abc end" },
+    { name: "devanagari", text: "नमस्ते क्षत्रिय end" },
+    { name: "emoji", text: "👍 ❤️ 👋🏽 👩‍💻 🇰🇷 end" },
+    // One shaped cluster over two cells, colored per cell: the color must follow the cell.
+    { name: "split-color", text: `क्${accent("ष")} ${accent("क्")}ष ल${accent("ا")} end` },
+    { name: SELECT_LINE, text: `क्${accent("ष")} end` },
+    { name: "box", text: "╭──┬──╮ │ab│cd│ ╰──┴──╯ ▀▄▌▐░▒▓ end" },
+    {
+      name: "styles",
+      text: [
+        sgr(1, "bold"),
+        sgr(3, "italic"),
+        sgr(4, "under"),
+        sgr(7, "inverse"),
+        sgr(42, "bg"),
+        sgr(9, "strike"),
+        "end",
+      ].join(" "),
+    },
+    { name: "hangul-wrap", text: "가".repeat(wrapSyllables) },
+    // The last line has no newline: the shell sleeps with the cursor right after it.
+    { name: "cursor", text: "> 안녕하세요" },
+  ];
+}
+
+/** The bytes `cat` writes; the tty turns each newline into CR LF. */
+export function fixtureOutput(columns) {
+  return fixtureLines(columns)
+    .map((line) => line.text)
+    .join("\n");
+}
diff --git a/packages/app/e2e/mobile/terminal-rendering/identity.mjs b/packages/app/e2e/mobile/terminal-rendering/identity.mjs
new file mode 100644
index 0000000000..a0a6246a3d
--- /dev/null
+++ b/packages/app/e2e/mobile/terminal-rendering/identity.mjs
@@ -0,0 +1,423 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { PNG } from "pngjs";
+import { checkTerminalScreenshot } from "./check.mjs";
+
+// Checks that every printed cluster of a `render.mjs` run is the right glyph. `check.mjs` proves
+// where ink lands and what color it has; this compares each cluster's ink with pango's (HarfBuzz)
+// rendering of the same characters in the device's own fonts, so a wrong glyph, tofu, a solid
+// block, a split conjunct or a cluster from elsewhere fails.
+//
+//   FONTCONFIG_FILE=<fonts.conf> node e2e/mobile/terminal-rendering/identity.mjs <run dir> [control]
+//
+// The fonts.conf lists the device's font files and prefers, for `monospace`, the terminal font
+// followed by the device's fallbacks; `docs/terminal-rendering.md` says how to build one. Needs
+// `pango-view` on the PATH.
+//
+// control:
+//   none  judge the screenshot (default); exits 1 when a cluster fails.
+//   rect  first fill every judged cluster's box with white; exits 1 unless every cluster fails.
+//   swap  judge each cluster against a different cluster of the corpus; exits 1 unless every
+//         cluster fails.
+// The two controls prove the oracle refuses ink that is present but wrong.
+
+/** Coverage grid side used to compare shapes. */
+const GRID = 16;
+/** A pixel at or above this ink strength (0..1) is part of a glyph's bounding box. */
+const INK = 0.25;
+/** Lowest shape correlation a cluster may have with its own reference. */
+const THRESHOLD = 0.6;
+/** How much better another cluster may match before the cluster's own match stops counting. */
+const MARGIN = 0.02;
+/** Lines whose cells carry decorations or a custom-drawn ruler; they stay geometry-only. */
+const SKIPPED_LINES = new Set(["ruler", "styles"]);
+const ZWJ = "‍";
+
+/**
+ * The renderer draws box and block characters to fill the cell, so they are judged against their
+ * Unicode definition. Shades come from the font, whose fallback differs between the device and
+ * pango, so a shade is judged by how evenly and densely it inks its own bounding box. Fonts dither
+ * differently: ░ ▒ ▓ measure 0.16, 0.31, 0.75 in Droid Sans Mono and 0.19, 0.50, 0.81 in Menlo. The
+ * bands split between those, and do not overlap, so one shade never passes as another.
+ */
+const CELL_GLYPHS = {
+  "─": { arms: "LR" },
+  "│": { arms: "UD" },
+  "┬": { arms: "LRD" },
+  "┴": { arms: "LRU" },
+  "╭": { arms: "DR" },
+  "╮": { arms: "DL" },
+  "╰": { arms: "UR" },
+  "╯": { arms: "UL" },
+  "▀": { fill: "top" },
+  "▄": { fill: "bottom" },
+  "▌": { fill: "left" },
+  "▐": { fill: "right" },
+  "░": { shade: [0.08, 0.25] },
+  "▒": { shade: [0.25, 0.625] },
+  "▓": { shade: [0.625, 0.9] },
+};
+/** A shade must ink each region of this grid over its bounding box within its band. */
+const SHADE_GRID = 4;
+/** Regions of the cell, as fractions [left, top, right, bottom], that a line to each edge crosses. */
+const ARM_REGIONS = {
+  U: [0.3, 0, 0.7, 0.2],
+  D: [0.3, 0.8, 0.7, 1],
+  L: [0, 0.3, 0.2, 0.7],
+  R: [0.8, 0.3, 1, 0.7],
+};
+/** [filled, empty] halves of each half block. */
+const HALVES = {
+  top: [
+    [0, 0, 1, 0.5],
+    [0, 0.5, 1, 1],
+  ],
+  bottom: [
+    [0, 0.5, 1, 1],
+    [0, 0, 1, 0.5],
+  ],
+  left: [
+    [0, 0, 0.5, 1],
+    [0.5, 0, 1, 1],
+  ],
+  right: [
+    [0.5, 0, 1, 1],
+    [0, 0, 0.5, 1],
+  ],
+};
+
+const [dirArg, control = "none"] = process.argv.slice(2);
+if (!dirArg || !["none", "rect", "swap"].includes(control)) {
+  throw new Error("Usage: identity.mjs <run dir> [none|rect|swap]");
+}
+const dir = resolve(dirArg);
+const report = JSON.parse(readFileSync(resolve(dir, "report.json"), "utf8"));
+const png = PNG.sync.read(readFileSync(resolve(dir, "terminal.png")));
+const rows = new Map(report.rows.map((row) => [row.index, row.rect]));
+const { grid, slots } = await checkTerminalScreenshot({ png, size: report.size, rows });
+
+const printed = slots.filter(
+  (slot) => !SKIPPED_LINES.has(slot.line) && !slot.isCursor && slot.chars.trim() !== "",
+);
+/** The columns xterm gives each printed cluster. */
+const columnsOf = new Map(printed.map((slot) => [slot.chars, slot.width]));
+
+if (control === "rect") {
+  for (const { box } of printed) {
+    for (let y = Math.ceil(box.top); y < Math.floor(box.bottom); y += 1) {
+      for (let x = Math.ceil(box.left); x < Math.floor(box.right); x += 1) {
+        png.data.set([255, 255, 255, 255], (png.width * y + x) * 4);
+      }
+    }
+  }
+}
+
+/** Ink strength 0..1 of each pixel in a box: the largest channel distance from the background. */
+function screenshotInk(box) {
+  const left = Math.ceil(box.left);
+  const top = Math.ceil(box.top);
+  const width = Math.floor(box.right) - left;
+  const height = Math.floor(box.bottom) - top;
+  const ink = new Float32Array(width * height);
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const offset = (png.width * (top + y) + left + x) * 4;
+      let distance = 0;
+      for (let channel = 0; channel < 3; channel += 1) {
+        distance = Math.max(
+          distance,
+          Math.abs(png.data[offset + channel] - grid.background[channel]),
+        );
+      }
+      ink[y * width + x] = distance / 255;
+    }
+  }
+  return { ink, width, height };
+}
+
+/** Ink of the slot's whole cells, scaled so the foreground color is 1. */
+function cellInk(slot) {
+  const left = Math.round(grid.left + slot.col * grid.cellWidth);
+  const right = Math.round(grid.left + (slot.col + slot.width) * grid.cellWidth);
+  const cells = screenshotInk({ left, right, top: slot.box.top, bottom: slot.box.bottom });
+  const full =
+    Math.max(...[0, 1, 2].map((c) => Math.abs(grid.foreground[c] - grid.background[c]))) / 255;
+  for (let i = 0; i < cells.ink.length; i += 1) cells.ink[i] = Math.min(1, cells.ink[i] / full);
+  return cells;
+}
+
+const scratch = mkdtempSync(resolve(tmpdir(), "terminal-identity-"));
+/** pango-view sizes its image to the text's advance plus this margin on each side. */
+const REFERENCE_MARGIN = 48;
+function pangoInk(text) {
+  const out = resolve(scratch, "reference.png");
+  execFileSync("pango-view", [
+    "--no-display",
+    "--dpi=72",
+    "--font=monospace 96px",
+    `--text=${text}`,
+    "--background=black",
+    "--foreground=white",
+    `--margin=${REFERENCE_MARGIN}`,
+    "-o",
+    out,
+  ]);
+  const image = PNG.sync.read(readFileSync(out));
+  const ink = new Float32Array(image.width * image.height);
+  for (let i = 0; i < ink.length; i += 1) {
+    const o = i * 4;
+    ink[i] = Math.max(image.data[o], image.data[o + 1], image.data[o + 2]) / 255;
+  }
+  return {
+    ink,
+    width: image.width,
+    height: image.height,
+    advance: image.width - 2 * REFERENCE_MARGIN,
+  };
+}
+
+/** The terminal font's cell advance at the reference size. */
+const referenceCell = pangoInk("M").advance;
+
+/**
+ * The text as the renderer places it in `columns` cells: centred, scaled down when its advance is
+ * wider, and cut at the cells' edges. Glyphs whose ink overhangs their advance, such as Devanagari
+ * headlines, are cut on the device too.
+ */
+function referenceInk(text, columns) {
+  const image = pangoInk(text);
+  const box = Math.max(image.advance, columns * referenceCell);
+  const left = Math.round(REFERENCE_MARGIN + (image.advance - box) / 2);
+  const right = Math.round(REFERENCE_MARGIN + (image.advance + box) / 2);
+  for (let y = 0; y < image.height; y += 1) {
+    for (let x = 0; x < image.width; x += 1) {
+      if (x < left || x >= right) image.ink[y * image.width + x] = 0;
+    }
+  }
+  return image;
+}
+
+function regionInk({ ink, width, height }, [x0, y0, x1, y1]) {
+  let [sum, max, count] = [0, 0, 0];
+  for (let y = Math.floor(y0 * height); y < Math.ceil(y1 * height); y += 1) {
+    for (let x = Math.floor(x0 * width); x < Math.ceil(x1 * width); x += 1) {
+      const value = ink[y * width + x] ?? 0;
+      sum += value;
+      max = Math.max(max, value);
+      count += 1;
+    }
+  }
+  return { mean: sum / count, max };
+}
+
+function inkBox({ ink, width, height }) {
+  let [minX, minY, maxX, maxY] = [width, height, -1, -1];
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      if (ink[y * width + x] < INK) continue;
+      minX = Math.min(minX, x);
+      maxX = Math.max(maxX, x);
+      minY = Math.min(minY, y);
+      maxY = Math.max(maxY, y);
+    }
+  }
+  return maxX < 0 ? null : { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 };
+}
+
+/** Whether an unbroken line crosses the region to the cell edge: a row for L/R, a column for U/D. */
+function lineCrosses({ ink, width, height }, arm) {
+  const [x0, y0, x1, y1] = ARM_REGIONS[arm];
+  const [left, top, right, bottom] = [
+    Math.floor(x0 * width),
+    Math.floor(y0 * height),
+    Math.ceil(x1 * width),
+    Math.ceil(y1 * height),
+  ];
+  const horizontal = arm === "L" || arm === "R";
+  const [outerFrom, outerTo, innerFrom, innerTo] = horizontal
+    ? [top, bottom, left, right]
+    : [left, right, top, bottom];
+  for (let outer = outerFrom; outer < outerTo; outer += 1) {
+    let unbroken = true;
+    for (let inner = innerFrom; inner < innerTo && unbroken; inner += 1) {
+      const [x, y] = horizontal ? [inner, outer] : [outer, inner];
+      unbroken = (ink[y * width + x] ?? 0) >= 0.5;
+    }
+    if (unbroken) return true;
+  }
+  return false;
+}
+
+/** 1 when the cell matches the character's definition, 0 otherwise. */
+function cellGlyphScore(slot, spec) {
+  const ink = cellInk(slot);
+  if (spec.arms) {
+    const matches = Object.keys(ARM_REGIONS).every((arm) =>
+      spec.arms.includes(arm) ? lineCrosses(ink, arm) : regionInk(ink, ARM_REGIONS[arm]).max < 0.3,
+    );
+    return matches ? 1 : 0;
+  }
+  if (spec.fill) {
+    const [filled, empty] = HALVES[spec.fill].map((region) => regionInk(ink, region).mean);
+    return filled >= 0.8 && empty <= 0.2 ? 1 : 0;
+  }
+  const box = inkBox(ink);
+  if (!box || box.width < 0.7 * ink.width || box.height < 0.5 * ink.height) return 0;
+  const [x0, y0] = [box.x / ink.width, box.y / ink.height];
+  const [x1, y1] = [(box.x + box.width) / ink.width, (box.y + box.height) / ink.height];
+  const [w, h] = [(x1 - x0) / SHADE_GRID, (y1 - y0) / SHADE_GRID];
+  const regions = Array.from({ length: SHADE_GRID * SHADE_GRID }, (_, index) => {
+    const [gx, gy] = [index % SHADE_GRID, Math.floor(index / SHADE_GRID)];
+    return [x0 + gx * w, y0 + gy * h, x0 + (gx + 1) * w, y0 + (gy + 1) * h];
+  });
+  const means = regions.map((region) => regionInk(ink, region).mean);
+  return means.every((mean) => mean >= spec.shade[0] && mean < spec.shade[1]) ? 1 : 0;
+}
+
+/** Coverage of the ink's bounding box, centered in a square that keeps its aspect, at GRID². */
+function coverage(image) {
+  const box = inkBox(image);
+  if (!box) return null;
+  const side = Math.max(box.width, box.height);
+  const originX = box.x - (side - box.width) / 2;
+  const originY = box.y - (side - box.height) / 2;
+  const vector = new Float32Array(GRID * GRID);
+  const step = side / GRID;
+  const samples = 4;
+  for (let gy = 0; gy < GRID; gy += 1) {
+    for (let gx = 0; gx < GRID; gx += 1) {
+      let sum = 0;
+      for (let sample = 0; sample < samples * samples; sample += 1) {
+        const x = Math.floor(originX + (gx + ((sample % samples) + 0.5) / samples) * step);
+        const y = Math.floor(
+          originY + (gy + (Math.floor(sample / samples) + 0.5) / samples) * step,
+        );
+        sum +=
+          x >= 0 && y >= 0 && x < image.width && y < image.height
+            ? image.ink[y * image.width + x]
+            : 0;
+      }
+      vector[gy * GRID + gx] = sum / (samples * samples);
+    }
+  }
+  return vector;
+}
+
+/** Pearson correlation of two coverage vectors; -1 when either has no ink or no contrast. */
+function correlation(a, b) {
+  if (!a || !b) return -1;
+  const n = a.length;
+  let [ma, mb] = [0, 0];
+  for (let i = 0; i < n; i += 1) {
+    ma += a[i];
+    mb += b[i];
+  }
+  ma /= n;
+  mb /= n;
+  let [num, da, db] = [0, 0, 0];
+  for (let i = 0; i < n; i += 1) {
+    num += (a[i] - ma) * (b[i] - mb);
+    da += (a[i] - ma) ** 2;
+    db += (b[i] - mb) ** 2;
+  }
+  return da === 0 || db === 0 ? -1 : num / Math.sqrt(da * db);
+}
+
+const references = new Map();
+/**
+ * The cluster alone and with a zero-width joiner before, after and on both sides, so any Arabic
+ * positional form of the right letter matches.
+ */
+function referenceVectors(chars) {
+  if (!references.has(chars)) {
+    const forms = [chars, ZWJ + chars, chars + ZWJ, ZWJ + chars + ZWJ];
+    references.set(
+      chars,
+      forms.map((text) => coverage(referenceInk(text, columnsOf.get(chars)))),
+    );
+  }
+  return references.get(chars);
+}
+
+function shapeScore(vector, chars) {
+  return Math.max(...referenceVectors(chars).map((reference) => correlation(vector, reference)));
+}
+
+/**
+ * pango draws no ink for Apple Color Emoji, and draws flags on neither device. Those clusters have
+ * no reference and are reported instead of judged.
+ */
+const hasReference = (chars) =>
+  CELL_GLYPHS[chars] ||
+  (!/^\p{Regional_Indicator}{2}$/u.test(chars) && referenceVectors(chars).some(Boolean));
+const judged = printed.filter((slot) => hasReference(slot.chars));
+const unjudged = printed
+  .filter((slot) => !hasReference(slot.chars))
+  .map((slot) => ({
+    line: slot.line,
+    col: slot.col,
+    chars: slot.chars,
+    reason: "no reference ink",
+  }));
+
+const distinct = [...new Set(judged.map((slot) => slot.chars))];
+const shapes = distinct.filter((chars) => !CELL_GLYPHS[chars]);
+
+/** The cluster a slot is judged against: its own, or under `swap` a different one. */
+function expectedChars(slot, index) {
+  if (control !== "swap") return slot.chars;
+  const own = distinct.indexOf(slot.chars);
+  const other = distinct[(own + 1 + (index % (distinct.length - 1))) % distinct.length];
+  return other === slot.chars ? distinct[(own + 1) % distinct.length] : other;
+}
+
+function judge(slot, index) {
+  const expected = expectedChars(slot, index);
+  const result = { line: slot.line, row: slot.row, col: slot.col, chars: slot.chars, expected };
+  const spec = CELL_GLYPHS[expected];
+  if (spec) {
+    result.score = cellGlyphScore(slot, spec);
+    return result;
+  }
+  // The shape must also resemble its own cluster at least as much as any other cluster in the
+  // corpus, within MARGIN, so a near-lookalike such as g judged as 8 fails.
+  const vector = coverage(screenshotInk(slot.box));
+  const score = shapeScore(vector, expected);
+  let nearest = { chars: expected, score };
+  for (const other of shapes) {
+    if (other === expected) continue;
+    const otherScore = shapeScore(vector, other);
+    if (otherScore > nearest.score) nearest = { chars: other, score: otherScore };
+  }
+  const distinctive = nearest.chars === expected || nearest.score - score <= MARGIN;
+  result.score = distinctive ? score : Math.min(score, 0);
+  result.nearest = nearest;
+  return result;
+}
+
+const results = judged.map(judge);
+rmSync(scratch, { recursive: true, force: true });
+
+const passed = results.filter((result) => result.score >= THRESHOLD);
+const failed = results.filter((result) => result.score < THRESHOLD);
+const outDir = resolve(dir, "identity");
+mkdirSync(outDir, { recursive: true });
+writeFileSync(
+  resolve(outDir, `${control}.json`),
+  `${JSON.stringify({ control, threshold: THRESHOLD, unjudged, results }, null, 2)}\n`,
+);
+
+const format = (result) =>
+  `${result.line}@${result.col}(${result.chars}${result.expected === result.chars ? "" : `→${result.expected}`})=${result.score.toFixed(2)}${result.nearest && result.nearest.chars !== result.expected ? ` nearest ${result.nearest.chars}` : ""}`;
+console.log(
+  `${report.label} ${control}: ${results.length} clusters judged, ${passed.length} pass, ${failed.length} fail, ${unjudged.length} unjudged (${outDir})`,
+);
+if (control === "none") {
+  for (const result of failed) console.log(`  fail ${format(result)}`);
+  process.exitCode = failed.length === 0 ? 0 : 1;
+} else {
+  for (const result of passed) console.log(`  accepted ${format(result)}`);
+  process.exitCode = passed.length === 0 ? 0 : 1;
+}
diff --git a/packages/app/e2e/mobile/terminal-rendering/overhang.mjs b/packages/app/e2e/mobile/terminal-rendering/overhang.mjs
new file mode 100644
index 0000000000..da977d78d3
--- /dev/null
+++ b/packages/app/e2e/mobile/terminal-rendering/overhang.mjs
@@ -0,0 +1,236 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { setTimeout } from "node:timers/promises";
+import { PNG } from "pngjs";
+import { countInk, measureGrid } from "./check.mjs";
+import { RULER_CELLS } from "./fixture.mjs";
+
+// Checks ink that leaves its row: stacked marks above and below a row reach into the rows next to
+// it. The script prints such rows, then in one update writes into two rows that hold another row's
+// overhang and erases two rows whose overhang reaches a blank row. The overhang must be drawn
+// before the update, stay drawn in the written rows, and leave no ink behind the erased rows.
+//
+// Preconditions are the same as `render.mjs`: the app runs the build being verified against a
+// daemon on the same host as this script, and shows an idle, focused terminal with an empty prompt.
+//
+//   PLATFORM=android ANDROID_SERIAL=emulator-5554 node e2e/mobile/terminal-rendering/overhang.mjs
+//   PLATFORM=ios IOS_DEVICE="iPhone 17" node e2e/mobile/terminal-rendering/overhang.mjs
+const platform = process.env.PLATFORM ?? "android";
+const appId = process.env.PASEO_TERMINAL_RENDERING_APP_ID ?? "sh.paseo.debug";
+const label = process.env.PASEO_TERMINAL_RENDERING_LABEL ?? "overhang";
+const session = process.env.AGENT_DEVICE_SESSION ?? `terminal-rendering-${platform}`;
+const artifacts = resolve(
+  process.env.PASEO_TERMINAL_RENDERING_ARTIFACTS ??
+    resolve(homedir(), ".paseo/artifacts/terminal-rendering", platform),
+  label,
+);
+const fixtureDir = process.env.PASEO_TERMINAL_RENDERING_FIXTURE_DIR ?? tmpdir();
+const screenshotArgs =
+  platform === "ios"
+    ? ["--pixel-density", process.env.PASEO_TERMINAL_RENDERING_PIXEL_DENSITY ?? "3"]
+    : [];
+const env = {
+  ...process.env,
+  AGENT_DEVICE_STATE_DIR:
+    process.env.AGENT_DEVICE_STATE_DIR ??
+    resolve(homedir(), ".paseo/artifacts/terminal-rendering/device-state"),
+};
+mkdirSync(artifacts, { recursive: true });
+
+/** Marks stacked below the row: Arabic dots, rings below `g`, a vowel sign below a consonant. */
+const BELOW = "پپپ ييي ججج g̥̥̥̥ कृ";
+/** Marks stacked above the row: accents over `e` and `s`, candrabindu, om. */
+const ABOVE = "é́́́ ŝ̂̂ कँ ॐ";
+/** The marks rows stay left of this column; the update writes at it, outside the checked boxes. */
+const CHECKED_COLUMNS = 26;
+const WRITE_COLUMN = 30;
+/** 0-based rows. Each source row's overhang reaches the row next to it. */
+const SOURCES = [
+  { row: 2, text: BELOW, overhangRow: 3, update: "write" },
+  { row: 6, text: ABOVE, overhangRow: 5, update: "erase" },
+  { row: 9, text: BELOW, overhangRow: 10, update: "erase" },
+  { row: 13, text: ABOVE, overhangRow: 12, update: "write" },
+];
+const PARK_ROW = 16;
+
+function ad(...args) {
+  return execFileSync("agent-device", [...args, "--session", session], {
+    env,
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+}
+
+function deviceArgs() {
+  if (platform === "android") {
+    return [
+      "--platform",
+      "android",
+      ...(process.env.ANDROID_SERIAL ? ["--serial", process.env.ANDROID_SERIAL] : []),
+    ];
+  }
+  return [
+    "--platform",
+    "ios",
+    ...(process.env.IOS_DEVICE ? ["--device", process.env.IOS_DEVICE] : []),
+  ];
+}
+
+function snapshotNodes() {
+  return JSON.parse(ad("snapshot", "--json")).data.nodes;
+}
+
+function pressControl(id) {
+  const node = JSON.parse(ad("snapshot", "-i", "--json")).data.nodes.find(
+    (candidate) => candidate.identifier === id,
+  );
+  assert.ok(node?.rect, `No ${id} control on screen`);
+  const { x, y, width, height } = node.rect;
+  ad("press", String(Math.round(x + width / 2)), String(Math.round(y + height / 2)));
+}
+
+async function pressEnter() {
+  pressControl("terminal-key-enter");
+  await setTimeout(2_000);
+}
+
+async function runCommand(command) {
+  ad("type", command, "--delay-ms", "0");
+  await pressEnter();
+}
+
+async function terminalSize() {
+  await runCommand("clear; stty size");
+  for (const node of snapshotNodes()) {
+    const match = /^(\d+) (\d+)$/.exec((node.label ?? "").trim());
+    if (match && (node.identifier ?? "").startsWith("terminal-row-")) {
+      return { rows: Number(match[1]), columns: Number(match[2]) };
+    }
+  }
+  throw new Error("No terminal row showed the `stty size` output");
+}
+
+function shellQuote(text) {
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
+/** Prints the source rows, waits for Enter, applies the update, and waits for Enter again. */
+function fixtureScript() {
+  const at = (row, col) => `\\033[${row + 1};${col + 1}H`;
+  const print = (row, text) => `printf '${at(row, 0)}%s' ${shellQuote(text)}`;
+  const update = SOURCES.map((source) =>
+    source.update === "write"
+      ? `${at(source.overhangRow, WRITE_COLUMN)}x`
+      : `${at(source.row, 0)}\\033[2K`,
+  ).join("");
+  return [
+    "stty -echo",
+    "printf '\\033[2J\\033[3J'",
+    print(0, "█".repeat(RULER_CELLS)),
+    ...SOURCES.map((source) => print(source.row, source.text)),
+    `printf '${at(PARK_ROW, 0)}'`,
+    "read -r _",
+    `printf '${update}${at(PARK_ROW, 0)}'`,
+    "read -r _",
+    "stty echo",
+    "",
+  ].join("\n");
+}
+
+function screenshot(name) {
+  const path = resolve(artifacts, name);
+  ad("screenshot", path, ...screenshotArgs);
+  return PNG.sync.read(readFileSync(path));
+}
+
+/** Pixels in `box` where the two screenshots differ by more than the ink threshold. */
+function changedPixels(before, after, box) {
+  const difference = new PNG({ width: before.width, height: before.height });
+  for (let index = 0; index < before.data.length; index += 1) {
+    difference.data[index] = Math.abs(before.data[index] - after.data[index]);
+  }
+  return countInk(difference, box, [0, 0, 0]);
+}
+
+ad("open", appId, ...deviceArgs());
+const controls = JSON.parse(ad("snapshot", "-i", "--json")).data.nodes;
+const hasControl = (id) => controls.some((node) => node.identifier === id);
+assert.ok(hasControl("terminal-keyboard-toggle"), "Open a terminal first");
+if (!hasControl("terminal-key-enter")) pressControl("terminal-keyboard-toggle");
+
+const size = await terminalSize();
+assert.ok(
+  size.rows > PARK_ROW && size.columns > WRITE_COLUMN,
+  `Terminal too small: ${JSON.stringify(size)}`,
+);
+const scriptPath = resolve(fixtureDir, "paseo-terminal-overhang.sh");
+writeFileSync(scriptPath, fixtureScript());
+await runCommand(`sh ${scriptPath}`);
+
+const nodes = snapshotNodes();
+const before = screenshot("before.png");
+await pressEnter();
+const after = screenshot("after.png");
+await pressEnter();
+
+// Snapshot rects are in points on iOS and pixels on Android; the checks work in screenshot pixels.
+const scale = before.width / Math.max(...nodes.map((node) => node.rect?.width ?? 0));
+const ruler = nodes.find((node) => node.identifier === "terminal-row-0")?.rect;
+assert.ok(ruler, "The ruler row is not exposed as terminal-row-0");
+const rulerRect = {
+  x: ruler.x * scale,
+  y: ruler.y * scale,
+  width: ruler.width * scale,
+  height: ruler.height * scale,
+};
+const grid = measureGrid(before, rulerRect);
+const rowBox = (row) => ({
+  left: grid.left,
+  right: grid.left + CHECKED_COLUMNS * grid.cellWidth,
+  top: rulerRect.y + row * rulerRect.height,
+  bottom: rulerRect.y + (row + 1) * rulerRect.height,
+});
+
+/** Measures one source row's overhang before and after the update. */
+function measure(source) {
+  const box = rowBox(source.overhangRow);
+  const overhangBefore = countInk(before, box, grid.background);
+  if (source.update === "write") {
+    const changedAfterWrite = changedPixels(before, after, box);
+    const failures = [
+      ...(overhangBefore === 0 ? ["overhang-not-drawn"] : []),
+      ...(changedAfterWrite > 0 ? ["overhang-lost-after-write"] : []),
+    ];
+    return { ...source, overhangBefore, changedAfterWrite, failures };
+  }
+  const inkAfterErase = countInk(after, box, grid.background);
+  const sourceInkAfterErase = countInk(after, rowBox(source.row), grid.background);
+  const failures = [
+    ...(overhangBefore === 0 ? ["overhang-not-drawn"] : []),
+    ...(inkAfterErase > 0 ? ["overhang-left-after-erase"] : []),
+    ...(sourceInkAfterErase > 0 ? ["source-left-after-erase"] : []),
+  ];
+  return { ...source, overhangBefore, inkAfterErase, sourceInkAfterErase, failures };
+}
+
+const results = SOURCES.map(measure);
+
+const report = { platform, label, size, grid, rulerRect, results };
+writeFileSync(resolve(artifacts, "report.json"), `${JSON.stringify(report, null, 2)}\n`);
+const failures = results.flatMap((result) =>
+  result.failures.map((failure) => `row ${result.overhangRow}: ${failure}`),
+);
+console.log(`${label}: ${failures.length} failures (${artifacts})`);
+for (const result of results) {
+  console.log(
+    `  row ${result.row} -> ${result.overhangRow} (${result.update}): overhang ${result.overhangBefore}` +
+      (result.update === "write"
+        ? `, changed after write ${result.changedAfterWrite}`
+        : `, left after erase ${result.inkAfterErase}, source left ${result.sourceInkAfterErase}`),
+  );
+}
+for (const failure of failures) console.log(`  ${failure}`);
+process.exitCode = failures.length === 0 ? 0 : 1;
diff --git a/packages/app/e2e/mobile/terminal-rendering/reattach.mjs b/packages/app/e2e/mobile/terminal-rendering/reattach.mjs
new file mode 100644
index 0000000000..c5cb7734e9
--- /dev/null
+++ b/packages/app/e2e/mobile/terminal-rendering/reattach.mjs
@@ -0,0 +1,149 @@
+import { homedir } from "node:os";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { setTimeout } from "node:timers/promises";
+
+// Reattaches to a terminal whose PTY has a different size than the app will measure, and checks
+// that the client rows equal the daemon's rows. RESIZE=keyboard opens the keyboard, and the
+// relaunched app starts with it closed. RESIZE=fold folds an Android foldable emulator and
+// relaunches the app unfolded. Either way the shell redraws its prompt on attach.
+//
+// Preconditions: the app shows terminal TERMINAL_ID, idle at an empty shell prompt, against the
+// daemon at PASEO_HOST.
+//
+//   PLATFORM=android TERMINAL_ID=511fd9f0 PASEO_HOST=localhost:6870 \
+//     node e2e/mobile/terminal-rendering/reattach.mjs
+//
+// The client used to be sized after the replay arrived, so the shell's redraw landed on the
+// wrong rows in most trials. TRIALS sets how many reattaches to check.
+const platform = process.env.PLATFORM ?? "android";
+const appId = process.env.PASEO_TERMINAL_RENDERING_APP_ID ?? "sh.paseo.debug";
+const appUrl = process.env.PASEO_TERMINAL_RENDERING_APP_URL;
+const terminalId = process.env.TERMINAL_ID;
+const host = process.env.PASEO_HOST;
+const trials = Number(process.env.TRIALS ?? 5);
+const resize = process.env.RESIZE ?? "keyboard";
+const label = process.env.PASEO_TERMINAL_RENDERING_LABEL ?? "reattach";
+const session = process.env.AGENT_DEVICE_SESSION ?? `terminal-rendering-${platform}`;
+const artifacts = resolve(
+  process.env.PASEO_TERMINAL_RENDERING_ARTIFACTS ??
+    resolve(homedir(), ".paseo/artifacts/terminal-rendering", platform),
+  label,
+);
+const env = {
+  ...process.env,
+  AGENT_DEVICE_STATE_DIR:
+    process.env.AGENT_DEVICE_STATE_DIR ??
+    resolve(homedir(), ".paseo/artifacts/terminal-rendering/device-state"),
+};
+if (!terminalId || !host) throw new Error("Set TERMINAL_ID and PASEO_HOST");
+mkdirSync(artifacts, { recursive: true });
+
+function ad(...args) {
+  return execFileSync("agent-device", [...args, "--session", session], {
+    env,
+    encoding: "utf8",
+    timeout: 120_000,
+  });
+}
+
+function paseo(...args) {
+  return execFileSync("npm", ["run", "-s", "cli", "--", ...args, "--host", host], {
+    cwd: resolve(import.meta.dirname, "../../../../.."),
+    encoding: "utf8",
+  });
+}
+
+function pressControl(id) {
+  const node = JSON.parse(ad("snapshot", "-i", "--json")).data.nodes.find(
+    (candidate) => candidate.identifier === id,
+  );
+  if (!node?.rect) throw new Error(`No ${id} control on screen`);
+  const { x, y, width, height } = node.rect;
+  ad("press", String(Math.round(x + width / 2)), String(Math.round(y + height / 2)));
+}
+
+async function resizePty() {
+  if (resize === "keyboard") {
+    pressControl("terminal-keyboard-toggle");
+    await setTimeout(2_000);
+    return;
+  }
+  const adb = (...args) =>
+    execFileSync("adb", [
+      ...(process.env.ANDROID_SERIAL ? ["-s", process.env.ANDROID_SERIAL] : []),
+      ...args,
+    ]);
+  adb("emu", "fold");
+  await setTimeout(5_000);
+  adb("shell", "am", "force-stop", appId);
+  adb("emu", "unfold");
+  await setTimeout(3_000);
+}
+
+function clientRows() {
+  const nodes = JSON.parse(ad("snapshot", "--json")).data.nodes;
+  const byIndex = new Map(nodes.map((node) => [node.index, node]));
+  const rows = [];
+  for (const node of nodes) {
+    const match = /^terminal-row-(\d+)$/.exec(node.identifier ?? "");
+    if (!match) continue;
+    // agent-device leaves the label on the parent when the row inherits it.
+    const text = node.label ?? (node.inheritsLabel ? byIndex.get(node.parentIndex)?.label : "");
+    rows[Number(match[1])] = (text ?? "").trim();
+  }
+  return rows;
+}
+
+/**
+ * Waits for the relaunched app to show terminal rows, then for the shell's redraw to land.
+ * Returns null when no row appears, for example when the app crashed on launch.
+ */
+async function attachedClientRows() {
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    await setTimeout(2_000);
+    if (clientRows().some((text) => text !== "")) {
+      await setTimeout(3_000);
+      return clientRows();
+    }
+  }
+  return null;
+}
+
+function mismatches(client, server) {
+  const rows = [];
+  for (let row = 0; row < Math.max(client.length, server.length); row += 1) {
+    const expected = (server[row] ?? "").trim();
+    const actual = client[row] ?? "";
+    if (expected !== actual) rows.push({ row, server: expected, client: actual });
+  }
+  return rows;
+}
+
+const results = [];
+for (let trial = 1; trial <= trials; trial += 1) {
+  paseo("terminal", "send-keys", terminalId, "clear", "Enter");
+  await setTimeout(1_500);
+  await resizePty();
+  ad("open", appId, ...(appUrl ? [appUrl] : []), "--relaunch");
+  const client = await attachedClientRows();
+  ad("screenshot", resolve(artifacts, `trial-${trial}.png`));
+  if (!client) {
+    results.push({ trial, attached: false });
+    console.log(`${label} trial ${trial}: no terminal rows appeared`);
+    continue;
+  }
+  const server = paseo("terminal", "capture", terminalId).split("\n");
+  const rows = mismatches(client, server);
+  results.push({ trial, attached: true, mismatchedRows: rows });
+  console.log(`${label} trial ${trial}: ${rows.length} mismatched rows`);
+}
+
+writeFileSync(resolve(artifacts, "report.json"), `${JSON.stringify(results, null, 2)}\n`);
+const attached = results.filter((result) => result.attached);
+const failed = attached.filter((result) => result.mismatchedRows.length > 0).length;
+console.log(
+  `${label}: ${failed} of ${attached.length} reattaches differ from the daemon, ${trials - attached.length} never attached (${artifacts})`,
+);
+process.exitCode = failed === 0 && attached.length === trials ? 0 : 1;
diff --git a/packages/app/e2e/mobile/terminal-rendering/render.mjs b/packages/app/e2e/mobile/terminal-rendering/render.mjs
new file mode 100644
index 0000000000..7aacfcaa8e
--- /dev/null
+++ b/packages/app/e2e/mobile/terminal-rendering/render.mjs
@@ -0,0 +1,197 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { setTimeout } from "node:timers/promises";
+import { PNG } from "pngjs";
+import {
+  checkPartialSelection,
+  checkTerminalScreenshot,
+  selectionTarget,
+  writeOverlay,
+} from "./check.mjs";
+import { fixtureOutput } from "./fixture.mjs";
+
+// Renders the fixture in a real Paseo terminal and checks the screenshot with `check.mjs`, then
+// selects one cell of a conjunct and checks a second screenshot.
+//
+// Preconditions: the app runs the build being verified against a daemon on the same host as
+// this script, and shows an idle, focused terminal with an empty shell prompt.
+//
+//   PLATFORM=android ANDROID_SERIAL=emulator-5554 node e2e/mobile/terminal-rendering/render.mjs
+//   PLATFORM=ios IOS_DEVICE="iPhone 17" node e2e/mobile/terminal-rendering/render.mjs
+const platform = process.env.PLATFORM ?? "android";
+const appId = process.env.PASEO_TERMINAL_RENDERING_APP_ID ?? "sh.paseo.debug";
+const label = process.env.PASEO_TERMINAL_RENDERING_LABEL ?? "run";
+const session = process.env.AGENT_DEVICE_SESSION ?? `terminal-rendering-${platform}`;
+const artifacts = resolve(
+  process.env.PASEO_TERMINAL_RENDERING_ARTIFACTS ??
+    resolve(homedir(), ".paseo/artifacts/terminal-rendering", platform),
+  label,
+);
+const fixtureDir = process.env.PASEO_TERMINAL_RENDERING_FIXTURE_DIR ?? tmpdir();
+// iOS simulators screenshot at one pixel per point unless asked; glyph identity needs the
+// device's real density. Android screenshots are always in device pixels.
+const screenshotArgs =
+  platform === "ios"
+    ? ["--pixel-density", process.env.PASEO_TERMINAL_RENDERING_PIXEL_DENSITY ?? "3"]
+    : [];
+const env = {
+  ...process.env,
+  AGENT_DEVICE_STATE_DIR:
+    process.env.AGENT_DEVICE_STATE_DIR ??
+    resolve(homedir(), ".paseo/artifacts/terminal-rendering/device-state"),
+};
+mkdirSync(artifacts, { recursive: true });
+
+function ad(...args) {
+  return execFileSync("agent-device", [...args, "--session", session], {
+    env,
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+}
+
+function deviceArgs() {
+  if (platform === "android") {
+    return [
+      "--platform",
+      "android",
+      ...(process.env.ANDROID_SERIAL ? ["--serial", process.env.ANDROID_SERIAL] : []),
+    ];
+  }
+  return [
+    "--platform",
+    "ios",
+    ...(process.env.IOS_DEVICE ? ["--device", process.env.IOS_DEVICE] : []),
+  ];
+}
+
+function snapshotNodes() {
+  return JSON.parse(ad("snapshot", "--json")).data.nodes;
+}
+
+function rowNodes(nodes) {
+  const rows = new Map();
+  for (const node of nodes) {
+    const match = /^terminal-row-(\d+)$/.exec(node.identifier ?? "");
+    if (match && node.rect) rows.set(Number(match[1]), node);
+  }
+  return rows;
+}
+
+/**
+ * Taps a control at its center. On iOS the keyboard toolbar is a full-screen accessibility node
+ * listed after the key bar, so pressing by selector reports the keys as covered.
+ */
+function pressControl(id) {
+  const node = JSON.parse(ad("snapshot", "-i", "--json")).data.nodes.find(
+    (candidate) => candidate.identifier === id,
+  );
+  assert.ok(node?.rect, `No ${id} control on screen`);
+  const { x, y, width, height } = node.rect;
+  ad("press", String(Math.round(x + width / 2)), String(Math.round(y + height / 2)));
+}
+
+async function runCommand(command) {
+  ad("type", command, "--delay-ms", "0");
+  pressControl("terminal-key-enter");
+  await setTimeout(2_000);
+}
+
+async function terminalSize() {
+  await runCommand("clear; stty size");
+  for (const node of snapshotNodes()) {
+    const match = /^(\d+) (\d+)$/.exec((node.label ?? "").trim());
+    if (match && (node.identifier ?? "").startsWith("terminal-row-")) {
+      return { rows: Number(match[1]), columns: Number(match[2]) };
+    }
+  }
+  throw new Error("No terminal row showed the `stty size` output");
+}
+
+ad("open", appId, ...deviceArgs());
+const controls = JSON.parse(ad("snapshot", "-i", "--json")).data.nodes;
+const hasControl = (id) => controls.some((node) => node.identifier === id);
+assert.ok(hasControl("terminal-keyboard-toggle"), "Open a terminal first");
+if (!hasControl("terminal-key-enter")) pressControl("terminal-keyboard-toggle");
+
+const size = await terminalSize();
+const fixturePath = resolve(fixtureDir, "paseo-terminal-rendering.txt");
+const scriptPath = resolve(fixtureDir, "paseo-terminal-rendering.sh");
+writeFileSync(fixturePath, fixtureOutput(size.columns));
+writeFileSync(scriptPath, `printf '\\033[2J\\033[3J\\033[H'; cat '${fixturePath}'; sleep 120\n`);
+await runCommand(`sh ${scriptPath}`);
+
+const nodes = snapshotNodes();
+const screenshotPath = resolve(artifacts, "terminal.png");
+ad("screenshot", screenshotPath, ...screenshotArgs);
+const png = PNG.sync.read(readFileSync(screenshotPath));
+// Snapshot rects are in points on iOS and pixels on Android; the checks work in screenshot pixels.
+const scale = png.width / Math.max(...nodes.map((node) => node.rect?.width ?? 0));
+const toPixels = ({ x, y, width, height }) => ({
+  x: x * scale,
+  y: y * scale,
+  width: width * scale,
+  height: height * scale,
+});
+const rows = rowNodes(nodes);
+const rects = new Map([...rows].map(([index, node]) => [index, toPixels(node.rect)]));
+const { grid, failures, slots } = await checkTerminalScreenshot({ png, size, rows: rects });
+
+// Long-press selects the conjunct as a word; dragging back from its second cell leaves the first.
+const target = await selectionTarget({ size });
+const targetRect = rects.get(target.row);
+assert.ok(targetRect, "The select line is not on screen");
+const y = Math.round((targetRect.y + targetRect.height / 2) / scale);
+const cellX = (offset) => Math.round((grid.left + (target.col + offset) * grid.cellWidth) / scale);
+ad("longpress", String(cellX(0.5)), String(y), "800");
+ad("gesture", "pan", String(cellX(1.75)), String(y), String(cellX(0.5) - cellX(1.75)), "0", "600");
+const selectionPath = resolve(artifacts, "selection.png");
+ad("screenshot", selectionPath, ...screenshotArgs);
+const selectionFailures = checkPartialSelection({
+  png: PNG.sync.read(readFileSync(selectionPath)),
+  rows: rects,
+  grid,
+  target,
+});
+for (const failure of selectionFailures) failures.push({ line: "select", ...failure });
+// A tap clears the selection; it would otherwise survive into the next run's screenshot.
+const lastRect = rects.get(size.rows - 1);
+if (lastRect) {
+  ad("press", String(cellX(4)), String(Math.round((lastRect.y + lastRect.height / 2) / scale)));
+}
+try {
+  pressControl("terminal-key-ctrl");
+  ad("type", "c", "--delay-ms", "0");
+} catch (error) {
+  console.warn(`Could not interrupt the fixture: ${error.message}`);
+}
+
+writeOverlay(png, slots, resolve(artifacts, "overlay.png"));
+const report = {
+  platform,
+  label,
+  size,
+  grid,
+  checkedClusters: slots.length,
+  failures,
+  rows: [...rows.keys()].map((index) => ({
+    index,
+    label: rows.get(index).label,
+    rect: rects.get(index),
+  })),
+};
+writeFileSync(resolve(artifacts, "report.json"), `${JSON.stringify(report, null, 2)}\n`);
+
+const byLine = Map.groupBy(failures, (failure) => failure.line);
+console.log(
+  `${label}: ${slots.length} clusters checked, ${failures.length} failures (${artifacts})`,
+);
+for (const [line, list] of byLine) {
+  console.log(
+    `  ${line}: ${list.map((failure) => `${failure.kind}@${failure.col ?? "-"}${failure.char ? `(${failure.char})` : ""}`).join(" ")}`,
+  );
+}
+process.exitCode = failures.length === 0 ? 0 : 1;
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/agent-timeline-gate.ts b/packages/app/e2e/support/helpers/agent-timeline-gate.ts
index 408bd8af24..89a1d8c364 100644
--- a/packages/app/e2e/support/helpers/agent-timeline-gate.ts
+++ b/packages/app/e2e/support/helpers/agent-timeline-gate.ts
@@ -338,11 +338,32 @@ export async function delayAgentOlderTimelineResponse(
   return delayAgentTimelineResponse(page, agentId, "before");
 }
 
+export interface OlderTimelinePagesOptions {
+  daemonPort?: number;
+  /**
+   * Hide whole-turn paging from the app so it reads this host with item pages, as it reads
+   * daemons released before whole-turn pages. An item page can end inside a turn or a tool run.
+   */
+  itemPagedHost?: boolean;
+}
+
+function withoutWholeTurnPages(message: WebSocketMessage): WebSocketMessage {
+  const sessionMessage = getSessionMessage(message);
+  const payload = sessionMessage ? getPayload(sessionMessage) : null;
+  if (sessionMessage?.type !== "status" || payload?.status !== "server_info") return message;
+  const envelope = parseWebSocketJson(message) as {
+    message: { payload: { features?: Record<string, unknown> } };
+  };
+  delete envelope.message.payload.features?.wholeTurnTimeline;
+  return JSON.stringify(envelope);
+}
+
 export async function holdAgentOlderTimelinePages(
   page: Page,
   agentId: string,
-  daemonPort?: number,
+  options: OlderTimelinePagesOptions = {},
 ): Promise<OlderTimelinePagesGate> {
+  const { daemonPort } = options;
   let requestCount = 0;
   let responseCount = 0;
   let repeatedEntryCount = 0;
@@ -376,7 +397,8 @@ export async function holdAgentOlderTimelinePages(
       }
       server.send(message);
     });
-    server.onMessage((message) => {
+    server.onMessage((received) => {
+      const message = options.itemPagedHost ? withoutWholeTurnPages(received) : received;
       const sessionMessage = getSessionMessage(message);
       const payload = sessionMessage ? getPayload(sessionMessage) : null;
       if (
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/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..b8ebc22ab6 100644
--- a/packages/app/e2e/support/helpers/composer-control-density.ts
+++ b/packages/app/e2e/support/helpers/composer-control-density.ts
@@ -53,3 +53,192 @@ 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([]);
 }
+
+/** 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/context-window.ts b/packages/app/e2e/support/helpers/context-window.ts
index afc91f859c..5320b73b32 100644
--- a/packages/app/e2e/support/helpers/context-window.ts
+++ b/packages/app/e2e/support/helpers/context-window.ts
@@ -54,12 +54,15 @@ export async function leaveContextWindowMeter(page: Page): Promise<void> {
   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> {
diff --git a/packages/app/e2e/support/helpers/custom-models.ts b/packages/app/e2e/support/helpers/custom-models.ts
index 11933a0dfa..aff79965ea 100644
--- a/packages/app/e2e/support/helpers/custom-models.ts
+++ b/packages/app/e2e/support/helpers/custom-models.ts
@@ -19,6 +19,9 @@ export async function addCustomModel(page: Page, id: string): Promise<void> {
     .getByRole("button", { name: "Add", exact: true })
     .click();
   await expect(page.getByRole("button", { name: `Remove ${id}`, exact: true })).toHaveCount(1);
+  // Config updates before provider refresh finishes and dismisses the add sheet.
+  // Resizing or interacting with the model list must wait for that save to finish.
+  await expect(page.getByTestId("add-custom-model-sheet")).toBeHidden();
 }
 
 export async function removeCustomModel(page: Page, id: string): Promise<void> {
diff --git a/packages/app/e2e/support/helpers/daemon-lifecycle.ts b/packages/app/e2e/support/helpers/daemon-lifecycle.ts
index 6779039f1f..c38c0f5f78 100644
--- a/packages/app/e2e/support/helpers/daemon-lifecycle.ts
+++ b/packages/app/e2e/support/helpers/daemon-lifecycle.ts
@@ -1,3 +1,7 @@
+import { execFile, spawn } from "node:child_process";
+import { writeFile, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
 import { expect, type Page } from "@playwright/test";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import { connectDaemonClient } from "./daemon-client-loader";
@@ -15,14 +19,27 @@ export async function openDaemonOverview(page: Page, daemon: IsolatedHostDaemon)
   await openHostSection(page, daemon.serverId, "host");
 }
 
-export async function restartDaemonInSettings(page: Page) {
-  const button = page.getByRole("button", { name: "Restart", exact: true });
+export async function restartDaemonInSettings(
+  page: Page,
+  options: { closeTerminals?: boolean } = {},
+) {
+  const button = page.getByRole("button", {
+    name: options.closeTerminals ? "Restart and close terminals" : "Restart",
+    exact: true,
+  });
   await expect(button).toBeEnabled();
   page.once("dialog", (dialog) => dialog.accept());
   await button.click();
   await expect(page.getByRole("button", { name: "Restarting...", exact: true })).toBeDisabled();
 }
 
+export async function expectDaemonRestartFailed(page: Page, text: string) {
+  const error = page.getByTestId("host-page-restart-error");
+  await expect(error).toBeVisible({ timeout: 30_000 });
+  await expect(error).toContainText(text);
+  await expect(page.getByRole("button", { name: "Restart", exact: true })).toBeEnabled();
+}
+
 export async function expectDaemonRestartComplete(page: Page) {
   await expect(page.getByRole("button", { name: "Restart", exact: true })).toBeEnabled({
     timeout: 30_000,
@@ -40,3 +57,139 @@ export async function readWorkerPid(daemon: IsolatedHostDaemon): Promise<number>
     await client.close();
   }
 }
+
+/** Opens a terminal on the isolated daemon that runs a long-lived program. */
+export async function openLongLivedTerminal(daemon: IsolatedHostDaemon): Promise<string> {
+  const client = await connectDaemonClient<DaemonClient>({
+    port: daemon.port,
+    clientIdPrefix: "lifecycle-terminal",
+  });
+  try {
+    const workspace = await client.createWorkspace({
+      source: { kind: "directory", path: daemon.paseoHome },
+      title: "lifecycle",
+    });
+    if (!workspace.workspace) throw new Error(workspace.error ?? "Workspace creation failed");
+    const created = await client.createTerminal(daemon.paseoHome, "lifecycle", undefined, {
+      workspaceId: workspace.workspace.id,
+      command: process.execPath,
+      args: ["-e", "setInterval(() => {}, 1e9)"],
+    });
+    if (!created.terminal) throw new Error(created.error ?? "Terminal creation failed");
+    return created.terminal.id;
+  } finally {
+    await client.close();
+  }
+}
+
+export async function listTerminalIds(daemon: IsolatedHostDaemon): Promise<string[]> {
+  const client = await connectDaemonClient<DaemonClient>({
+    port: daemon.port,
+    clientIdPrefix: "lifecycle-terminals",
+  });
+  try {
+    return (await client.listTerminals()).terminals.map((terminal) => terminal.id);
+  } finally {
+    await client.close();
+  }
+}
+
+const execFileAsync = promisify(execFile);
+
+async function psField(pid: number, field: "stat" | "lstart"): Promise<string> {
+  const { stdout } = await execFileAsync("ps", ["-o", `${field}=`, "-p", String(pid)], {
+    env: { ...process.env, LC_ALL: "C" },
+  });
+  return stdout.trim();
+}
+
+export interface UnclosableTerminalProgram {
+  pid: number;
+  /** Ends the program's parent, which lets the system reap the program. */
+  release(): void;
+}
+
+/**
+ * Leaves in the daemon's home the record a dead terminal worker leaves, naming one terminal
+ * program that SIGKILL cannot remove: a zombie whose parent (an exec'd `sleep`) never waits for
+ * it. A kill cleanup can only report it as still running. POSIX only.
+ */
+export async function plantUnclosableTerminalProgram(
+  daemon: IsolatedHostDaemon,
+): Promise<UnclosableTerminalProgram> {
+  const parent = spawn("/bin/sh", ["-c", "sleep 0 & echo $!; exec sleep 600"], {
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  parent.unref();
+  const release = () => {
+    if (parent.exitCode === null && parent.signalCode === null) parent.kill("SIGKILL");
+  };
+  try {
+    const pid = await new Promise<number>((resolve) => {
+      parent.stdout!.once("data", (chunk: Buffer) => resolve(Number(chunk.toString().trim())));
+    });
+    await expect.poll(async () => (await psField(pid, "stat")).startsWith("Z")).toBe(true);
+    const gone = spawn(process.execPath, ["-e", ""], { stdio: "ignore" });
+    await new Promise((resolve) => gone.once("exit", resolve));
+    const record = {
+      recordId: "planted-record",
+      pid: gone.pid,
+      bootId: null,
+      createdAt: new Date().toISOString(),
+      identity: { startedAt: "Thu Jan  1 00:00:00 1970", commandLine: "planted-worker" },
+      protocolVersion: 1,
+      paseoVersion: "0.0.0-test",
+      socketPath: path.join(daemon.paseoHome, "planted-worker.sock"),
+      secret: "planted-secret",
+      terminals: [{ id: "planted-terminal", pid, startedAt: await psField(pid, "lstart") }],
+    };
+    await writeFile(
+      path.join(daemon.paseoHome, "terminal-worker", `${gone.pid}.json`),
+      `${JSON.stringify(record, null, 2)}\n`,
+      { mode: 0o600 },
+    );
+    return { pid, release };
+  } catch (error) {
+    release();
+    throw error;
+  }
+}
+
+/** Fault injection and liveness checks for the isolated daemon cleanup journey. */
+export function suspendDaemonProcess(pid: number): void {
+  process.kill(pid, "SIGSTOP");
+}
+
+export function resumeDaemonProcess(pid: number): void {
+  try {
+    process.kill(pid, "SIGCONT");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+  }
+}
+
+export async function daemonProcessCanWrite(pid: number): Promise<boolean> {
+  try {
+    const state = await psField(pid, "stat");
+    return state.length > 0 && !state.startsWith("Z");
+  } catch (error) {
+    if ((error as { code?: unknown }).code === 1) return false;
+    throw error;
+  }
+}
+
+export async function readTerminalProcessIds(daemon: IsolatedHostDaemon): Promise<number[]> {
+  const directory = path.join(daemon.paseoHome, "terminal-worker");
+  const records = await Promise.all(
+    (await readdir(directory))
+      .filter((name) => name.endsWith(".json"))
+      .map(async (name) => {
+        const record = JSON.parse(await readFile(path.join(directory, name), "utf8")) as {
+          pid: number;
+          terminals: Array<{ pid: number }>;
+        };
+        return [record.pid].concat(record.terminals.map((terminal) => terminal.pid));
+      }),
+  );
+  return records.flat();
+}
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/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/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 01fe3a70c1..dea61c3a37 100644
--- a/packages/app/e2e/support/helpers/isolated-host-daemon.ts
+++ b/packages/app/e2e/support/helpers/isolated-host-daemon.ts
@@ -1,4 +1,11 @@
-import { spawn, execFileSync, type ChildProcess, type SpawnOptions } from "node:child_process";
+import { promisify } from "node:util";
+import {
+  spawn,
+  execFile,
+  execFileSync,
+  type ChildProcess,
+  type SpawnOptions,
+} from "node:child_process";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import net from "node:net";
 import { tmpdir } from "node:os";
@@ -6,6 +13,8 @@ import path from "node:path";
 import { withDisabledE2ESpeechEnv } from "./speech-env";
 import { killProcessTree, spawnTsx } from "./spawn-node";
 
+const execFileAsync = promisify(execFile);
+
 export interface IsolatedHostDaemon {
   serverId: string;
   port: number;
@@ -16,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;
@@ -84,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 = {},
@@ -129,29 +162,36 @@ 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
     ? path.join(publishedPackageRoot, "node_modules", "@getpaseo", "server")
     : path.resolve(__dirname, "../../../../server");
+  let child: ChildProcess | null = null;
+  const stopDaemon = async (): Promise<void> => {
+    // The CLI owns graceful shutdown, forced cleanup and detached terminal
+    // reaping. Keep its ESM graph out of Playwright's transforming loader.
+    await execFileAsync(
+      process.execPath,
+      [
+        path.resolve(__dirname, "../../../../cli/dist/index.js"),
+        "daemon",
+        "stop",
+        "--home",
+        paseoHome,
+        "--force",
+      ],
+      { timeout: 30_000 },
+    );
+    await killProcessTree(child);
+  };
   const spawnDaemon = async (): Promise<ChildProcess> => {
     const spawnOptions: SpawnOptions = {
       cwd: serverDir,
@@ -169,21 +209,21 @@ export async function startIsolatedHostDaemon(
       stdio: ["ignore", "ignore", "pipe"],
       detached: false,
     };
-    const child = publishedPackageRoot
+    const spawned = publishedPackageRoot
       ? spawn(process.execPath, ["dist/scripts/supervisor-entrypoint.js"], spawnOptions)
       : spawnTsx("scripts/supervisor-entrypoint.ts", ["--dev"], spawnOptions);
 
+    child = spawned;
     let stderr = "";
-    child.stderr?.on("data", (chunk: Buffer) => {
+    spawned.stderr?.on("data", (chunk: Buffer) => {
       stderr += chunk.toString("utf8");
       stderr = stderr.split("\n").slice(-40).join("\n");
     });
 
     try {
-      await waitForServer(port, child);
-      return child;
+      await waitForServer(port, spawned);
+      return spawned;
     } catch (error) {
-      await killProcessTree(child);
       throw new Error(
         `${error instanceof Error ? error.message : String(error)}\nDaemon stderr:\n${stderr}`,
         { cause: error },
@@ -191,10 +231,10 @@ export async function startIsolatedHostDaemon(
     }
   };
 
-  let child: ChildProcess;
   try {
-    child = await spawnDaemon();
+    await spawnDaemon();
   } catch (error) {
+    await stopDaemon();
     if (!options.preserveHome) {
       await rm(paseoHome, { recursive: true, force: true });
     }
@@ -209,22 +249,22 @@ export async function startIsolatedHostDaemon(
     serverId,
     port,
     paseoHome,
-    getPid: () => child.pid,
+    getPid: () => child?.pid,
     restart: async () => {
       if (closed) throw new Error(`Cannot restart closed isolated daemon ${serverId}`);
-      await killProcessTree(child);
-      child = await spawnDaemon();
+      await stopDaemon();
+      await spawnDaemon();
     },
     close: async () => {
       if (closed) return;
-      closed = true;
-      await killProcessTree(child);
+      await stopDaemon();
       if (!options.preserveHome) {
         await rm(paseoHome, { recursive: true, force: true });
       }
       if (publishedPackageRoot) {
         await rm(publishedPackageRoot, { recursive: true, force: true });
       }
+      closed = true;
     },
   };
 }
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-reconnect.ts b/packages/app/e2e/support/helpers/plugin-reconnect.ts
new file mode 100644
index 0000000000..739399b9e7
--- /dev/null
+++ b/packages/app/e2e/support/helpers/plugin-reconnect.ts
@@ -0,0 +1,159 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { settingsRpc } from "@getpaseo/plugin";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { z } from "zod";
+import { expect, type Page } from "../fixtures";
+import { gotoAppShell } from "./app";
+import { installDaemonWebSocketGate } from "./daemon-websocket-gate";
+import { connectDaemonClient } from "./daemon-client-loader";
+import { copyPluginExample, pluginRequirements } from "./plugin-fixture";
+
+const PLUGIN_ID = "retained-plugin-e2e";
+
+export function retainedPluginSource(version: string) {
+  return `import { useState } from "react";
+import { Text, View, TextInput, Pressable } from "react-native";
+import { useSettings } from "@getpaseo/plugin/client";
+import { preferences } from "./shared/preferences";
+function Preferences({ color }) {
+  const settings = useSettings(preferences);
+  return <Text style={{ color }}>{settings.status === "ready" ? "Stored title: " + settings.values.title : "Preferences " + settings.status}</Text>;
+}
+function Surface({ theme }) {
+  const [draft, setDraft] = useState("");
+  const [clicks, setClicks] = useState(0);
+  const [showPreferences, setShowPreferences] = useState(true);
+  const color = theme.colors.foreground;
+  return <View>
+    <Text style={{ color }}>Plugin version ${version}</Text>
+    <TextInput accessibilityLabel="Plugin draft" value={draft} onChangeText={setDraft} style={{ color }} />
+    <Pressable accessibilityRole="button" onPress={() => setClicks(value => value + 1)}><Text style={{ color }}>{"Local clicks " + clicks}</Text></Pressable>
+    <Pressable accessibilityRole="button" onPress={() => setShowPreferences(value => !value)}><Text style={{ color }}>{showPreferences ? "Hide preferences" : "Show preferences"}</Text></Pressable>
+    {showPreferences ? <Preferences color={color} /> : null}
+  </View>;
+}
+export default function contribute(plugin) {
+  plugin.addSurface("main", Surface);
+  plugin.addSidebarItem({ id: "main", title: "Reconnect probe", icon: "PanelsTopLeft", surface: "main" });
+  return () => {};
+}`;
+}
+
+export async function withRetainedPlugin(
+  page: Page,
+  run: (probe: Awaited<ReturnType<typeof createProbe>>) => Promise<void>,
+) {
+  const probe = await createProbe(page);
+  try {
+    await run(probe);
+  } finally {
+    await probe.close();
+  }
+}
+
+async function createProbe(page: Page) {
+  const example = await copyPluginExample("settings");
+  const peer = await connectDaemonClient<DaemonClient>({ clientIdPrefix: "plugin-reconnect" });
+  const previous = await peer.getDaemonConfig();
+  const gate = await installDaemonWebSocketGate(page);
+  const clientEntry = path.join(example.directory, "index.client.tsx");
+  let catalogCount = 0;
+  try {
+    await writeFile(
+      path.join(example.directory, "paseo-plugin.json"),
+      JSON.stringify({ id: PLUGIN_ID, requirements: pluginRequirements }),
+    );
+    await writeFile(clientEntry, retainedPluginSource("one"));
+    await peer.patchDaemonConfig({ pluginsEnabled: true });
+    await peer.installDirectoryPlugin(example.directory);
+  } catch (error) {
+    await peer.close();
+    await example.cleanup();
+    throw error;
+  }
+  return {
+    async open() {
+      await page.setViewportSize({ width: 1100, height: 800 });
+      await gotoAppShell(page);
+      await page.getByRole("button", { name: "Reconnect probe", exact: true }).click();
+      await expect(page.getByText("Stored title: Agent monitor", { exact: true })).toBeVisible();
+    },
+    async disconnect() {
+      catalogCount = gate.getClientRequestCount("plugin.catalog.get.request");
+      await gate.drop();
+      await gate.waitForBlockedConnection();
+    },
+    async reconnect() {
+      gate.restore();
+      await gate.waitForServerMessage("plugin.catalog.get.response", catalogCount + 1);
+    },
+    async changeStoredTitle(title: string) {
+      const rpc = settingsRpc("display");
+      const current = rpc.read.output.parse(
+        await peer.invokePluginRpc(PLUGIN_ID, rpc.read.name, {}),
+      );
+      if (current.status !== "ready") throw new Error("Expected ready settings");
+      const values = z
+        .object({ groupBy: z.string(), showMetadata: z.boolean(), title: z.string() })
+        .parse(current.values);
+      const result = await peer.invokePluginRpc(PLUGIN_ID, rpc.write.name, {
+        revision: current.revision,
+        values: { ...values, title },
+      });
+      expect(result).toMatchObject({ status: "saved", values: { title } });
+    },
+    async changeCode() {
+      await writeFile(clientEntry, retainedPluginSource("two"));
+      await peer.reloadPlugin(PLUGIN_ID);
+    },
+    async remove() {
+      await peer.removePlugin(PLUGIN_ID);
+    },
+    async close() {
+      gate.restore();
+      await peer.removePlugin(PLUGIN_ID).catch(() => undefined);
+      await peer.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled ?? false });
+      await peer.close();
+      await example.cleanup();
+    },
+  };
+}
+
+export async function editRetainedDraft(page: Page, draft: string, clicks: number) {
+  await page.getByRole("textbox", { name: "Plugin draft", exact: true }).fill(draft);
+  await page.getByRole("button", { name: `Local clicks ${clicks}`, exact: true }).click();
+  await expectRetainedDraft(page, draft, clicks + 1);
+}
+
+export async function expectRetainedDraft(page: Page, draft: string, clicks: number) {
+  await expect(page.getByRole("textbox", { name: "Plugin draft", exact: true })).toHaveValue(draft);
+  await expect(
+    page.getByRole("button", { name: `Local clicks ${clicks}`, exact: true }),
+  ).toBeVisible();
+}
+
+export async function expectStoredPluginTitle(page: Page, title: string) {
+  await expect(page.getByText(`Stored title: ${title}`, { exact: true })).toBeVisible();
+}
+
+export async function hideRetainedPreferences(page: Page) {
+  await page.getByRole("button", { name: "Hide preferences", exact: true }).click();
+  await expect(page.getByText(/^Stored title:/)).toHaveCount(0);
+}
+
+export async function showRetainedPreferences(page: Page) {
+  await page.getByRole("button", { name: "Show preferences", exact: true }).click();
+}
+
+export async function expectChangedPlugin(page: Page) {
+  await expect(page.getByText("Plugin version two", { exact: true })).toBeVisible();
+  await expectRetainedDraft(page, "", 0);
+}
+
+export async function expectRemovedPlugin(page: Page) {
+  await expect(
+    page.getByText("This plugin surface is unavailable.", { exact: true }),
+  ).toBeVisible();
+  await expect(page.getByRole("button", { name: "Reconnect probe", exact: true })).toHaveCount(0);
+}
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 533b546022..d321aaa236 100644
--- a/packages/app/e2e/support/helpers/plugin-timeline.ts
+++ b/packages/app/e2e/support/helpers/plugin-timeline.ts
@@ -5,8 +5,64 @@ import { expect, type Page, type TestInfo } from "@playwright/test";
 import { copyPluginExample, pluginRequirements } from "./plugin-fixture";
 import { connectNewWorkspaceDaemonClient } from "./new-workspace";
 import { openAgentRoute, seedMockAgentWorkspace, type MockAgentWorkspace } from "./mock-agent";
+import { installDaemonWebSocketGate } from "./daemon-websocket-gate";
+import { expectReconnectingToastVisible } from "./workspace-ui";
 
 const PLUGIN_ID = "timeline-transform-e2e";
+
+/** Observe the app's real socket, including fresh sockets after a reload. */
+export function trackPluginChatRecovery(page: Page) {
+  const messages: {
+    type: string;
+    payload?: { plugins?: { id: string; clientBundle?: string }[] };
+  }[] = [];
+  page.on("websocket", (socket) => {
+    const collect = ({ payload }: { payload: string | Buffer }) => {
+      if (typeof payload !== "string") return;
+      const frame = JSON.parse(payload);
+      if (frame.type === "session") messages.push(frame.message);
+    };
+    socket.on("framesent", collect);
+    socket.on("framereceived", collect);
+  });
+  return {
+    reset() {
+      messages.length = 0;
+    },
+    async expectCatalogWithoutRetransmission() {
+      await expect
+        .poll(() =>
+          messages.some(
+            (message) =>
+              message.type === "plugin.catalog.get.response" &&
+              message.payload?.plugins?.some((plugin) => plugin.id === PLUGIN_ID),
+          ),
+        )
+        .toBe(true);
+      const entry = messages
+        .find((message) => message.type === "plugin.catalog.get.response")
+        ?.payload?.plugins?.find((plugin) => plugin.id === PLUGIN_ID);
+      expect(entry).toBeDefined();
+      expect(entry).not.toHaveProperty("clientBundle");
+    },
+    async expectRecoveredWithoutRetransmission() {
+      await this.expectCatalogWithoutRetransmission();
+      await expect
+        .poll(() => messages.some((message) => message.type === "fetch_agent_timeline_response"))
+        .toBe(true);
+    },
+  };
+}
+
+export async function reconnectPluginChat(
+  page: Page,
+  gate: Awaited<ReturnType<typeof installDaemonWebSocketGate>>,
+) {
+  await gate.drop();
+  await gate.waitForBlockedConnection();
+  await expectReconnectingToastVisible(page);
+  gate.restore();
+}
 export const ASSISTANT_TEXT =
   "Skill header\n\n# Instructions\n\nRead every paragraph and preserve the full message while this response is still streaming.";
 
@@ -78,7 +134,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/react-renders.ts b/packages/app/e2e/support/helpers/react-renders.ts
new file mode 100644
index 0000000000..5e9752cbfa
--- /dev/null
+++ b/packages/app/e2e/support/helpers/react-renders.ts
@@ -0,0 +1,78 @@
+import type { Page } from "@playwright/test";
+
+declare global {
+  var __PASEO_E2E_REACT_RENDERS__: Record<string, number> | undefined;
+}
+
+/**
+ * Counts which components render in each React commit, by name, the way React DevTools
+ * highlights updates: a fiber rendered when React performed work on it in that commit.
+ * Install before the app loads; React registers with the DevTools hook at startup.
+ */
+export async function recordReactRenders(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    const PERFORMED_WORK = 1;
+    interface Fiber {
+      type: unknown;
+      flags: number;
+      child: Fiber | null;
+      sibling: Fiber | null;
+      alternate: Fiber | null;
+    }
+    const nameOf = (type: unknown): string | null => {
+      if (typeof type === "function") {
+        return (type as { displayName?: string }).displayName || type.name || null;
+      }
+      if (!type || typeof type !== "object") return null;
+      const component = type as { displayName?: string; render?: unknown; type?: unknown };
+      return component.displayName || nameOf(component.render) || nameOf(component.type);
+    };
+    const record = (root: Fiber) => {
+      const renders = (globalThis.__PASEO_E2E_REACT_RENDERS__ ??= {});
+      const pending: Fiber[] = [root];
+      while (pending.length > 0) {
+        const fiber = pending.pop()!;
+        const name = typeof fiber.type === "string" ? null : nameOf(fiber.type);
+        if (name && (fiber.flags & PERFORMED_WORK) !== 0) renders[name] = (renders[name] ?? 0) + 1;
+        // A subtree React bailed out of is shared with the previous commit; skip it.
+        if (fiber.alternate && fiber.child === fiber.alternate.child) continue;
+        for (let child = fiber.child; child; child = child.sibling) pending.push(child);
+      }
+    };
+    let rendererCount = 0;
+    Object.defineProperty(globalThis, "__REACT_DEVTOOLS_GLOBAL_HOOK__", {
+      configurable: true,
+      value: {
+        supportsFiber: true,
+        isDisabled: false,
+        renderers: new Map(),
+        inject(renderer: unknown) {
+          rendererCount += 1;
+          this.renderers.set(rendererCount, renderer);
+          return rendererCount;
+        },
+        checkDCE() {},
+        onScheduleFiberRoot() {},
+        onCommitFiberRoot(_rendererId: number, root: { current: Fiber }) {
+          record(root.current);
+        },
+        onPostCommitFiberRoot() {},
+        onCommitFiberUnmount() {},
+      },
+    });
+  });
+}
+
+export async function resetReactRenders(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    globalThis.__PASEO_E2E_REACT_RENDERS__ = {};
+  });
+}
+
+/** Render counts per component name since the last reset, read after the next painted frame. */
+export async function readReactRenders(page: Page): Promise<Record<string, number>> {
+  return page.evaluate(async () => {
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+    return { ...globalThis.__PASEO_E2E_REACT_RENDERS__ };
+  });
+}
diff --git a/packages/app/e2e/support/helpers/seed-client.ts b/packages/app/e2e/support/helpers/seed-client.ts
index 4419e5193f..41e676473f 100644
--- a/packages/app/e2e/support/helpers/seed-client.ts
+++ b/packages/app/e2e/support/helpers/seed-client.ts
@@ -28,6 +28,10 @@ interface SeedProjectDescriptor {
  * prefer those wrappers over reaching for this client directly.
  */
 export interface SeedDaemonClient {
+  patchDaemonConfig(
+    config: import("@getpaseo/protocol/messages").MutableDaemonConfigPatch,
+  ): Promise<{ config: import("@getpaseo/protocol/messages").MutableDaemonConfig }>;
+  getDaemonConfig(): Promise<{ config: import("@getpaseo/protocol/messages").MutableDaemonConfig }>;
   connect(): Promise<void>;
   close(): Promise<void>;
   addProject(cwd: string): Promise<{
@@ -114,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<{
@@ -149,7 +154,14 @@ export interface SeedDaemonClient {
     timeout?: number,
   ): Promise<{ status: string }>;
   cancelAgent(agentId: string): Promise<void>;
-  sendAgentMessage(agentId: string, text: string): Promise<void>;
+  sendAgentMessage(
+    agentId: string,
+    text: 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 07bd716105..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);
 }
@@ -560,3 +575,41 @@ export async function expectHostOnlineWithoutError(page: Page): Promise<void> {
   await expect(page.getByTestId("host-page-identity")).toContainText("Online");
   await expect(page.getByTestId("host-connection-error")).toHaveCount(0);
 }
+
+function restartRecoverySwitch(page: Page) {
+  return page.getByRole("switch", { name: "Resume agents after restart", exact: true });
+}
+
+function restartRecoveryEditButton(page: Page) {
+  return page.getByRole("button", { name: "Edit prompt", exact: true });
+}
+
+export async function setRestartRecoveryEnabled(page: Page, enabled: boolean) {
+  const toggle = restartRecoverySwitch(page);
+  await toggle.click();
+  await expectRestartRecoveryEnabled(page, enabled);
+}
+
+// The prompt is only editable while restart recovery is on.
+export async function expectRestartRecoveryEnabled(page: Page, enabled: boolean) {
+  await expect(restartRecoverySwitch(page)).toBeChecked({ checked: enabled });
+  await expect(restartRecoveryEditButton(page)).toBeEnabled({ enabled });
+}
+
+export async function editRestartRecoveryPrompt(page: Page, prompt: string) {
+  await restartRecoveryEditButton(page).click();
+  const sheet = page.getByTestId("host-page-restart-recovery-sheet");
+  await sheet.getByRole("textbox", { name: "Resume prompt", exact: true }).fill(prompt);
+  await sheet.getByRole("button", { name: "Save", exact: true }).click();
+  await expect(sheet).toHaveCount(0);
+}
+
+export async function expectRestartRecoveryPrompt(page: Page, prompt: string) {
+  await restartRecoveryEditButton(page).click();
+  const sheet = page.getByTestId("host-page-restart-recovery-sheet");
+  await expect(sheet.getByRole("textbox", { name: "Resume prompt", exact: true })).toHaveValue(
+    prompt,
+  );
+  await sheet.getByRole("button", { name: "Cancel", exact: true }).click();
+  await expect(sheet).toHaveCount(0);
+}
diff --git a/packages/app/e2e/support/helpers/sheet.ts b/packages/app/e2e/support/helpers/sheet.ts
index 6288c6f9c1..94c33747d0 100644
--- a/packages/app/e2e/support/helpers/sheet.ts
+++ b/packages/app/e2e/support/helpers/sheet.ts
@@ -5,7 +5,7 @@ export function sheet(page: Page, label: string): Locator {
   return page.getByRole("dialog", { name: label });
 }
 
-/** A sheet tab's header, which carries its title, Close, and the Open as tab glyph. */
+/** A sheet tab's header, which carries its title, Back, Close, and the Open as tab glyph. */
 export function sheetHeader(page: Page, label: string): Locator {
   return page.getByTestId("sheet-tab-header").filter({ hasText: label });
 }
@@ -48,6 +48,12 @@ export async function closeSheet(page: Page, label: string): Promise<void> {
   await expect(sheet(page, label)).toHaveCount(0);
 }
 
+/** Steps a sheet opened from a list back to that list, in the same sheet. */
+export async function backToList(page: Page, label: string): Promise<void> {
+  await sheetHeader(page, label).getByRole("button", { name: "Back" }).click();
+  await expect(sheet(page, label)).toHaveCount(0);
+}
+
 export async function openSheetAsTab(page: Page, label: string): Promise<void> {
   await sheetHeader(page, label).getByRole("button", { name: "Open as tab" }).click();
   await expect(sheet(page, label)).toHaveCount(0);
@@ -76,6 +82,15 @@ export async function selectTabFromSwitcher(page: Page, label: string): Promise<
   await expect(page.getByRole("button", { name: "Bottom sheet backdrop" })).toHaveCount(0);
 }
 
+/** Each open sheet renders its own backdrop, so counting them counts the sheets. */
+export async function expectOneSheetOpen(page: Page): Promise<void> {
+  await expect(page.getByRole("button", { name: "Bottom sheet backdrop" })).toHaveCount(1);
+}
+
+export async function expectNoSheetOpen(page: Page): Promise<void> {
+  await expect(page.getByRole("button", { name: "Bottom sheet backdrop" })).toHaveCount(0);
+}
+
 /** Taps the top sheet's backdrop; each stacked sheet renders its own, top last. */
 export async function tapSheetBackdrop(page: Page): Promise<void> {
   await page
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.ts b/packages/app/e2e/support/helpers/sidebar.ts
index 66a913e7b3..6e0a4abedc 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> {
@@ -252,16 +267,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/subagents.ts b/packages/app/e2e/support/helpers/subagents.ts
index a6fc5bcf21..ed10a69905 100644
--- a/packages/app/e2e/support/helpers/subagents.ts
+++ b/packages/app/e2e/support/helpers/subagents.ts
@@ -3,7 +3,7 @@ import { startIsolatedHostDaemon } from "./isolated-host-daemon";
 import { seedWorkspace } from "./seed-client";
 import { getE2EDaemonPort } from "./daemon-port";
 import { PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
-import { expect, type Page } from "@playwright/test";
+import { expect, type Locator, type Page } from "@playwright/test";
 import { daemonWsRoutePattern } from "./daemon-port";
 import type { SeededWorkspace } from "./seed-client";
 
@@ -151,10 +151,21 @@ export async function openSubagentsTrack(page: Page): Promise<void> {
   await expect(panel).toBeVisible({ timeout: 30_000 });
 }
 
-/** On compact the track opens as a sheet, which closes once a row is chosen. */
-export async function openSubagentFromCompactTrack(page: Page, childId: string): Promise<void> {
-  await page.getByTestId("subagents-track-header").click();
-  await page.getByTestId(`subagents-track-row-${childId}`).click();
+/**
+ * On compact the track opens as a sheet, and the chosen row opens in its place. `track` is the
+ * pane whose track to open, for when a subagent's sheet shows a track of its own.
+ */
+export async function openSubagentFromCompactTrack(
+  page: Page,
+  childId: string,
+  track: Page | Locator = page,
+): Promise<void> {
+  await track.getByTestId("subagents-track-header").click();
+  const row = page.getByTestId(`subagents-track-row-${childId}`);
+  // Tap the row once the sheet has brought it on screen, as a finger would. Clicking it while it is
+  // still below the fold makes Playwright scroll the sheet host, and every sheet then docks short.
+  await expect(row).toBeInViewport();
+  await row.click();
 }
 
 export async function expectSubagentRowVisible(page: Page, childId: string): Promise<void> {
diff --git a/packages/app/e2e/support/helpers/terminal-perf.ts b/packages/app/e2e/support/helpers/terminal-perf.ts
index 5c00bed485..67a114b30f 100644
--- a/packages/app/e2e/support/helpers/terminal-perf.ts
+++ b/packages/app/e2e/support/helpers/terminal-perf.ts
@@ -1,4 +1,5 @@
 import { expect, type Page } from "@playwright/test";
+import type { Terminal } from "@xterm/xterm";
 import { buildHostWorkspaceRoute } from "../../../src/utils/host-routes";
 import { getServerId } from "./server-id";
 
@@ -206,3 +207,100 @@ export function computePercentile(samples: number[], p: number): number {
 export function round2(value: number): number {
   return Math.round(value * 100) / 100;
 }
+
+/** Observe actual cursor pixels and blink phases through xterm's public render event. */
+export async function expectTerminalCursor(
+  page: Page,
+  expected: { shape: "bar" | "underline"; blinking: boolean },
+): Promise<void> {
+  const observed = await page.evaluate(async () => {
+    const terminal = (window as Window & { __paseoTerminal?: Terminal }).__paseoTerminal;
+    if (!terminal) throw new Error("Terminal did not mount");
+    const source = Array.from(document.querySelectorAll(".xterm-screen canvas")).find(
+      (canvas): canvas is HTMLCanvasElement =>
+        canvas instanceof HTMLCanvasElement && canvas.getContext("webgl2") !== null,
+    );
+    if (!source) throw new Error("Cursor verification requires the actual WebGL renderer");
+    const copy = document.createElement("canvas");
+    const context = copy.getContext("2d");
+    if (!context) throw new Error("Cursor pixel capture is unavailable");
+    terminal.focus();
+    await new Promise<void>((resolve) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+    );
+    if (!terminal.element?.contains(document.activeElement))
+      throw new Error("Terminal did not focus");
+    const started = performance.now();
+    const frames: Array<{ time: number; width: number; height: number }> = [];
+    const rendered = terminal.onRender(() => {
+      copy.width = source.width;
+      copy.height = source.height;
+      // WebGL's default drawing buffer must be copied before this render returns.
+      context.drawImage(source, 0, 0);
+      const cellWidth = source.width / terminal.cols;
+      const cellHeight = source.height / terminal.rows;
+      const x = Math.round(terminal.buffer.active.cursorX * cellWidth);
+      const y = Math.round(terminal.buffer.active.cursorY * cellHeight);
+      const width = Math.ceil(cellWidth);
+      const height = Math.ceil(cellHeight);
+      const background = context.getImageData(x + width + 2, y, 1, 1).data;
+      const pixels = context.getImageData(x, y, width, height).data;
+      let minX = width;
+      let maxX = -1;
+      let minY = height;
+      let maxY = -1;
+      for (let row = 0; row < height; row++) {
+        for (let col = 0; col < width; col++) {
+          const offset = (row * width + col) * 4;
+          if (
+            ![0, 1, 2, 3].some(
+              (channel) => Math.abs(pixels[offset + channel]! - background[channel]!) > 20,
+            )
+          )
+            continue;
+          minX = Math.min(minX, col);
+          maxX = Math.max(maxX, col);
+          minY = Math.min(minY, row);
+          maxY = Math.max(maxY, row);
+        }
+      }
+      frames.push({
+        time: performance.now() - started,
+        width: maxX < 0 ? 0 : (maxX - minX + 1) / cellWidth,
+        height: maxY < 0 ? 0 : (maxY - minY + 1) / cellHeight,
+      });
+    });
+    try {
+      const refresh = setInterval(() => terminal.refresh(0, terminal.rows - 1), 40);
+      try {
+        await new Promise((resolve) => setTimeout(resolve, 1800));
+      } finally {
+        clearInterval(refresh);
+      }
+    } finally {
+      rendered.dispose();
+    }
+    return {
+      frames,
+      focused: terminal.element?.contains(document.activeElement),
+      samples: frames.length,
+      width: Math.max(...frames.map((frame) => frame.width)),
+      height: Math.max(...frames.map((frame) => frame.height)),
+      blinking:
+        frames.filter(
+          (frame, index) => index > 0 && (frame.width === 0) !== (frames[index - 1]!.width === 0),
+        ).length >= 2,
+    };
+  });
+  expect(observed.samples).toBeGreaterThan(5);
+  expect(observed.blinking, JSON.stringify(observed)).toBe(expected.blinking);
+  if (expected.shape === "bar") {
+    expect(observed.width).toBeGreaterThan(0);
+    expect(observed.width).toBeLessThan(0.4);
+    expect(observed.height).toBeGreaterThan(0.6);
+  } else {
+    expect(observed.width).toBeGreaterThan(0.6);
+    expect(observed.height).toBeGreaterThan(0);
+    expect(observed.height).toBeLessThan(0.4);
+  }
+}
diff --git a/packages/app/e2e/support/helpers/timeline-pagination.ts b/packages/app/e2e/support/helpers/timeline-pagination.ts
index 52027df956..f54fd86812 100644
--- a/packages/app/e2e/support/helpers/timeline-pagination.ts
+++ b/packages/app/e2e/support/helpers/timeline-pagination.ts
@@ -1,4 +1,4 @@
-import { expect, type TestInfo, type Page } from "@playwright/test";
+import { expect, type Locator, type TestInfo, type Page } from "@playwright/test";
 import { buildAgentRoute, seedMockAgentWorkspace, type MockAgentWorkspace } from "./mock-agent";
 import { readReplicaCache } from "./replica-cache-storage";
 import {
@@ -9,6 +9,7 @@ import {
   type AgentTimelineResponseGate,
   type BootstrapTimelineGate,
   type OlderTimelinePagesGate,
+  type OlderTimelinePagesOptions,
 } from "./agent-timeline-gate";
 
 export { holdDaemonHydration };
@@ -35,6 +36,19 @@ interface RealisticOlderTimelineAgent extends MockAgentWorkspace {
   newestPrompt: string;
 }
 
+export interface ItemPagedToolGroupAgent extends MockAgentWorkspace {
+  newestPrompt: string;
+  /** Commands in one run, more than an item page holds. */
+  totalCommands: number;
+  /** Commands of that run the initial tail loads, so the size of the group as first shown. */
+  loadedCommands: number;
+}
+
+interface ToolCallGroupPositionSnapshot {
+  top: number;
+}
+
+const ITEM_PAGE_SIZE = 40;
 const PROMPT_PREFIX = "timeline-pagination-turn";
 const LIVE_BEFORE_HYDRATION_PROMPT = "timeline live before authoritative hydration";
 const HISTORY_START_THRESHOLD_PX = 96;
@@ -126,6 +140,93 @@ export async function seedRealisticOlderTimeline(): Promise<RealisticOlderTimeli
   };
 }
 
+/**
+ * A run of commands longer than an item page, followed by enough short turns that the
+ * initial tail ends inside the run. Read with item pages, the tail loads the newest
+ * commands as one group; the older page carries the rest of that run and the turns before
+ * it, with a further page behind it.
+ */
+export async function seedItemPagedToolGroupTimeline(): Promise<ItemPagedToolGroupAgent> {
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "timeline-item-page-tool-group-",
+    title: "Item page tool group regression",
+  });
+  const olderTurns = 10;
+  const newerTurns = 12;
+  const totalCommands = 50;
+  // A short turn is its prompt and one reply; the run's turn ends with one reply.
+  const loadedCommands = ITEM_PAGE_SIZE - newerTurns * 2 - 1;
+  const shortTurnPrompt = (label: string, index: number) =>
+    `item-page-${label}-turn-${index}: emit 1 coalesced agent stream updates`;
+  const sendTurn = async (prompt: string) => {
+    await agent.client.sendAgentMessage(agent.agentId, prompt);
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+  };
+
+  for (let index = 0; index < olderTurns; index += 1) {
+    await sendTurn(shortTurnPrompt("older", index));
+  }
+  await sendTurn(`emit ${totalCommands} tool agent stream updates`);
+  for (let index = 0; index < newerTurns; index += 1) {
+    await sendTurn(shortTurnPrompt("newer", index));
+  }
+
+  return {
+    ...agent,
+    newestPrompt: shortTurnPrompt("newer", newerTurns - 1),
+    totalCommands,
+    loadedCommands,
+  };
+}
+
+export async function useChatDisplay(
+  page: Page,
+  chatDisplay: "full" | "collapseToolCalls" | "collapseTurns",
+): Promise<void> {
+  await page.addInitScript((value) => {
+    localStorage.setItem("@paseo:app-settings", JSON.stringify({ chatDisplay: value }));
+  }, chatDisplay);
+}
+
+function toolCallGroup(page: Page, commandCount: number): Locator {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  return timeline
+    .getByTestId("tool-call-group")
+    .getByRole("button", { name: `Ran ${commandCount} commands`, exact: true });
+}
+
+export async function rememberToolCallGroupPosition(
+  page: Page,
+  commandCount: number,
+): Promise<ToolCallGroupPositionSnapshot> {
+  const group = toolCallGroup(page, commandCount);
+  await expect(group).toBeVisible();
+  const box = await group.boundingBox();
+  if (!box) {
+    throw new Error(`Expected a rendered tool-call group of ${commandCount} commands`);
+  }
+  return { top: box.y };
+}
+
+/** The group the reader was on keeps its place on screen, now counting the older page's calls. */
+export async function expectToolCallGroupPositionPreserved(
+  page: Page,
+  commandCount: number,
+  before: ToolCallGroupPositionSnapshot,
+): Promise<void> {
+  const group = toolCallGroup(page, commandCount);
+  await expect(group).toBeVisible();
+  await expect
+    .poll(
+      async () => {
+        const box = await group.boundingBox();
+        return box ? Math.abs(box.y - before.top) : Number.POSITIVE_INFINITY;
+      },
+      { message: `the group of ${commandCount} commands keeps its viewport position` },
+    )
+    .toBeLessThanOrEqual(2);
+}
+
 export async function scrollThroughOlderHistoryPages(
   page: Page,
   pageCount: number,
@@ -316,13 +417,14 @@ export async function holdNextOlderTimelinePage(
 export async function holdOlderHistoryPages(
   page: Page,
   agent: MockAgentWorkspace,
-  daemonPort?: number,
+  options?: OlderTimelinePagesOptions,
 ): Promise<OlderHistoryPages> {
   const gate: OlderTimelinePagesGate = await holdAgentOlderTimelinePages(
     page,
     agent.agentId,
-    daemonPort,
+    options,
   );
+  const loader = page.getByTestId("load-older-history-spinner");
   return {
     async expectRequestedPages(count) {
       await gate.waitForRequestCount(count);
@@ -330,7 +432,17 @@ export async function holdOlderHistoryPages(
     },
     async expectSettledWithRequestedPages(count) {
       await waitForTimelineGeometryToSettle(page);
-      expect(gate.getRequestCount()).toBe(count);
+      // The loader stays until the prepend settles and the viewport decides whether to
+      // keep loading. Once it hides, no further page loads without new user intent.
+      await expect
+        .poll(
+          async () => ({
+            requestedPages: gate.getRequestCount(),
+            loading: await loader.isVisible(),
+          }),
+          { message: `older history settles after ${count} requested page(s)` },
+        )
+        .toEqual({ requestedPages: count, loading: false });
     },
     expectNoRepeatedEntries() {
       expect(gate.getRepeatedEntryCount()).toBe(0);
@@ -365,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);
@@ -423,6 +546,53 @@ export async function expectTimelineViewportAnchoredAfterPrepend(
   expect(Math.abs(contentGrowth - scrollAdjustment)).toBeLessThanOrEqual(2);
 }
 
+/**
+ * Item-based pages from older hosts split turns, so the oldest loaded turn starts
+ * mid-turn: its prompt is above loaded history. Returns that prompt.
+ */
+export async function expectOldestLoadedTurnPartial(
+  page: Page,
+  prompts: readonly string[],
+): Promise<string> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  const oldestLoadedPrompt = await timeline
+    .getByTestId("user-message")
+    .first()
+    .evaluate((element) => element.textContent ?? "");
+  const loadedIndex = prompts.findIndex((prompt) => oldestLoadedPrompt.includes(prompt));
+  expect(loadedIndex, "oldest loaded prompt is a seeded turn").toBeGreaterThan(0);
+  const oldestRow = timeline.locator("[data-history-row-id]").first();
+  await expect(oldestRow.getByTestId("user-message"), "rows above the oldest prompt").toHaveCount(
+    0,
+  );
+  const partialPrompt = prompts[loadedIndex - 1]!;
+  await expectTimelinePromptNotMounted(page, partialPrompt);
+  return partialPrompt;
+}
+
+/** The reader stays with the turn they were reading once it folds behind its summary. */
+export async function expectFoldedTurnAtReadingPosition(page: Page, prompt: string): Promise<void> {
+  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();
+  await expect
+    .poll(
+      async () => {
+        const [timelineBox, promptBox] = await Promise.all([
+          timeline.boundingBox(),
+          promptRow.boundingBox(),
+        ]);
+        if (!timelineBox || !promptBox) return false;
+        const offset = promptBox.y - timelineBox.y;
+        return offset >= 0 && offset <= timelineBox.height / 2;
+      },
+      { message: "folded turn sits in the upper half of the viewport" },
+    )
+    .toBe(true);
+}
+
 export async function expectTimelineAtHistoryStart(page: Page): Promise<void> {
   await expect
     .poll(async () => (await readTimelineViewport(page)).scrollTop)
diff --git a/packages/app/e2e/support/helpers/tool-call-gate.ts b/packages/app/e2e/support/helpers/tool-call-gate.ts
new file mode 100644
index 0000000000..5fd823eb27
--- /dev/null
+++ b/packages/app/e2e/support/helpers/tool-call-gate.ts
@@ -0,0 +1,125 @@
+import type { Page } from "@playwright/test";
+import { daemonWsRoutePattern } from "./daemon-port";
+
+type WebSocketMessage = string | Buffer;
+
+function parseSessionMessage(message: WebSocketMessage): Record<string, unknown> | null {
+  const raw = typeof message === "string" ? message : message.toString("utf8");
+  try {
+    const envelope = JSON.parse(raw) as { type?: unknown; message?: unknown };
+    return envelope.type === "session" && envelope.message && typeof envelope.message === "object"
+      ? (envelope.message as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function getToolCallStatus(
+  message: WebSocketMessage,
+  agentId: string,
+): { callId: string; status: string } | null {
+  const sessionMessage = parseSessionMessage(message);
+  if (sessionMessage?.type !== "agent_stream") {
+    return null;
+  }
+  const payload = sessionMessage.payload as Record<string, unknown> | undefined;
+  if (payload?.agentId !== agentId) {
+    return null;
+  }
+  const event = payload.event as Record<string, unknown> | undefined;
+  const item = event?.item as Record<string, unknown> | undefined;
+  return event?.type === "timeline" &&
+    item?.type === "tool_call" &&
+    typeof item.callId === "string" &&
+    typeof item.status === "string"
+    ? { callId: item.callId, status: item.status }
+    : null;
+}
+
+function replaceToolCallStatus(message: WebSocketMessage, status: string): string {
+  const raw = typeof message === "string" ? message : message.toString("utf8");
+  const envelope = JSON.parse(raw) as {
+    message?: { payload?: { event?: { item?: { status?: string } } } };
+  };
+  const item = envelope.message?.payload?.event?.item;
+  if (!item) {
+    throw new Error("Expected a tool-call session message");
+  }
+  item.status = status;
+  return JSON.stringify(envelope);
+}
+
+export async function gateSecondToolCall(page: Page, agentId: string) {
+  let firstCallId: string | null = null;
+  let secondCallId: string | null = null;
+  let secondRunningMessage: WebSocketMessage | null = null;
+  let pauseAfterSecondRunning = false;
+  let releaseSecondRequested = false;
+  let forwardSecondRunning: (() => void) | null = null;
+  let resolveFirstCompleted!: () => void;
+  let resolveSecondRunning!: () => void;
+  const firstCompleted = new Promise<void>((resolve) => {
+    resolveFirstCompleted = resolve;
+  });
+  const secondRunning = new Promise<void>((resolve) => {
+    resolveSecondRunning = resolve;
+  });
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+    forwardSecondRunning = () => {
+      if (secondRunningMessage) {
+        ws.send(secondRunningMessage);
+        secondRunningMessage = null;
+      }
+    };
+    ws.onMessage((message) => server.send(message));
+    server.onMessage((message) => {
+      if (pauseAfterSecondRunning) {
+        return;
+      }
+
+      const toolCall = getToolCallStatus(message, agentId);
+      if (!toolCall) {
+        ws.send(message);
+        return;
+      }
+
+      if (!firstCallId) {
+        firstCallId = toolCall.callId;
+      }
+      if (toolCall.callId === firstCallId) {
+        ws.send(message);
+        if (toolCall.status === "completed") {
+          resolveFirstCompleted();
+        }
+        return;
+      }
+
+      secondCallId ??= toolCall.callId;
+      if (toolCall.callId === secondCallId) {
+        const transformedMessage =
+          toolCall.status === "completed" ? replaceToolCallStatus(message, "running") : message;
+        secondRunningMessage = transformedMessage;
+        pauseAfterSecondRunning = true;
+        resolveSecondRunning();
+        if (releaseSecondRequested) {
+          forwardSecondRunning?.();
+        }
+        return;
+      }
+
+      ws.send(message);
+    });
+  });
+
+  return {
+    waitForFirstCompleted: () => firstCompleted,
+    waitForSecondRunning: () => secondRunning,
+    releaseSecondRunning() {
+      releaseSecondRequested = true;
+      forwardSecondRunning?.();
+    },
+  };
+}
diff --git a/packages/app/e2e/support/helpers/usage-reports.ts b/packages/app/e2e/support/helpers/usage-reports.ts
index 86b74c6ea3..bb46e52f95 100644
--- a/packages/app/e2e/support/helpers/usage-reports.ts
+++ b/packages/app/e2e/support/helpers/usage-reports.ts
@@ -25,6 +25,7 @@ interface UsageReportsFixtureOptions {
    * app connects, so a reload can switch it.
    */
   usageSupported?: boolean | (() => boolean);
+  usageSettingSupported?: boolean;
   /** Released hosts expose provider.usage.list with no source icons. */
   providerUsageListOnly?: boolean;
   /** The host daemon's port; defaults to the E2E daemon. */
@@ -63,6 +64,7 @@ function withUsageSupportFeature(
   message: WebSocketMessage,
   enabled: boolean,
   providerUsageListOnly: boolean,
+  usageSettingSupported: boolean,
 ): string | null {
   const envelope = parseJson(message) as {
     type?: unknown;
@@ -86,6 +88,7 @@ function withUsageSupportFeature(
         ...payload,
         features: {
           ...features,
+          usageSetting: usageSettingSupported ? true : undefined,
           usageSources: enabled && !providerUsageListOnly,
           providerUsageList: enabled,
         },
@@ -229,7 +232,12 @@ export async function installUsageReportsFixture(
     server.onMessage((message) => {
       const serverInfo =
         typeof message === "string"
-          ? withUsageSupportFeature(message, isUsageSupported(), providerUsageListOnly)
+          ? withUsageSupportFeature(
+              message,
+              isUsageSupported(),
+              providerUsageListOnly,
+              options.usageSettingSupported ?? true,
+            )
           : null;
       ws.send(serverInfo ?? message);
     });
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..0eadc58644
--- /dev/null
+++ b/packages/app/e2e/support/helpers/workspace-archive-undo.ts
@@ -0,0 +1,97 @@
+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 { getServerId } from "./server-id";
+import { expectWorkspaceAbsentFromSidebar } from "./sidebar";
+
+type DaemonClient = Awaited<ReturnType<typeof connectNewWorkspaceDaemonClient>>;
+
+const UNDO_SHORTCUT = process.platform === "darwin" ? "Meta+Z" : "Control+Z";
+/** 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();
+}
+
+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 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/fastlane/Fastfile b/packages/app/fastlane/Fastfile
index dc7508b456..f9f11a0e9a 100644
--- a/packages/app/fastlane/Fastfile
+++ b/packages/app/fastlane/Fastfile
@@ -1,7 +1,47 @@
+require "fileutils"
+require "tmpdir"
+
 default_platform(:ios)
 
 APP_IDENTIFIER = "sh.paseo"
 
+# Store screenshots are rendered into assets/store-screenshots/output; see the
+# README there. Google Play and F-Droid both read fastlane/metadata/android at
+# the repo root, whose screenshot files link to those renders.
+REPO_ROOT = File.expand_path("../../..", __dir__)
+STORE_SCREENSHOTS = File.join(REPO_ROOT, "assets/store-screenshots/output")
+ANDROID_METADATA = File.join(REPO_ROOT, "fastlane/metadata/android")
+
+# deliver reads screenshots from one folder per language and picks the device
+# slot from each image's size, so both Apple sets go into en-US together.
+def stage_app_store_screenshots
+  root = Dir.mktmpdir("app-store-screenshots")
+  locale = File.join(root, "en-US")
+  FileUtils.mkdir_p(locale)
+  { "apple" => "iphone", "apple-ipad" => "ipad" }.each do |set, device|
+    Dir.glob(File.join(STORE_SCREENSHOTS, set, "*.png")).sort.each do |file|
+      FileUtils.cp(file, File.join(locale, "#{device}-#{File.basename(file)}"))
+    end
+  end
+  root
+end
+
+# Google Play only has en-US screenshots, and some F-Droid locales in
+# ANDROID_METADATA are not Play languages (Play rejects "ja"). supply uploads
+# every locale folder in one edit, so give it only the en-US images.
+def stage_google_play_screenshots
+  root = Dir.mktmpdir("google-play-screenshots")
+  images = File.join(ANDROID_METADATA, "en-US/images")
+  %w[phoneScreenshots tenInchScreenshots].each do |kind|
+    target = File.join(root, "en-US/images", kind)
+    FileUtils.mkdir_p(target)
+    Dir.glob(File.join(images, kind, "*.png")).sort.each do |file|
+      FileUtils.cp(File.realpath(file), File.join(target, File.basename(file)))
+    end
+  end
+  root
+end
+
 platform :ios do
   desc "Submit the latest TestFlight build to App Store Review"
   lane :submit_review do
@@ -87,7 +127,8 @@ platform :ios do
       },
       force: true,
       skip_binary_upload: true,
-      skip_screenshots: true,
+      screenshots_path: stage_app_store_screenshots,
+      overwrite_screenshots: true,
       precheck_include_in_app_purchases: false,
       submission_information: {
         add_id_info_uses_idfa: false,
@@ -96,3 +137,25 @@ platform :ios do
     )
   end
 end
+
+platform :android do
+  desc "Replace the Google Play store screenshots with the ones in the repo"
+  lane :upload_screenshots do
+    # supply attaches listing changes to a release on the production track.
+    # The release workflow passes the version code it just submitted; without
+    # it, supply uses the track's only release.
+    version_code = ENV["ANDROID_VERSION_CODE"].to_s.strip
+    supply(
+      package_name: APP_IDENTIFIER,
+      json_key: ENV.fetch("GOOGLE_PLAY_JSON_KEY"),
+      metadata_path: stage_google_play_screenshots,
+      version_code: version_code.empty? ? nil : version_code.to_i,
+      skip_upload_apk: true,
+      skip_upload_aab: true,
+      skip_upload_metadata: true,
+      skip_upload_changelogs: true,
+      skip_upload_images: true,
+      sync_image_upload: true,
+    )
+  end
+end
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/build.gradle b/packages/app/modules/paseo-terminal/android/build.gradle
new file mode 100644
index 0000000000..3be89253be
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/android/build.gradle
@@ -0,0 +1,25 @@
+apply plugin: 'com.android.library'
+
+group = 'sh.paseo.terminal'
+version = '0.1.0'
+
+def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+apply from: expoModulesCorePlugin
+applyKotlinExpoModulesCorePlugin()
+useCoreDependencies()
+useExpoPublishing()
+useDefaultAndroidSdkVersions()
+
+android {
+  namespace "sh.paseo.terminal"
+  defaultConfig {
+    testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+  }
+}
+
+dependencies {
+  implementation "androidx.customview:customview:1.1.0"
+  testImplementation "junit:junit:4.13.2"
+  androidTestImplementation "androidx.test:runner:1.6.2"
+  androidTestImplementation "androidx.test.ext:junit:1.2.1"
+}
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
new file mode 100644
index 0000000000..351ed32e73
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/android/src/androidTest/assets/grapheme-rows.json
@@ -0,0 +1,38 @@
+[
+  {
+    "output": "स्ते",
+    "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": "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,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": "क्अ",
+    "row": "2,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, 1, 2, 3, 4, 5, 6, 7],
+    "contrastStarts": [0, 2, 3, 4, 5, 6, 7]
+  },
+  {
+    "output": "अ्क",
+    "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
new file mode 100644
index 0000000000..632065eab0
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/android/src/androidTest/java/sh/paseo/terminal/TerminalRowLayoutTest.kt
@@ -0,0 +1,132 @@
+package sh.paseo.terminal
+
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Paint
+import android.util.Log
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import org.json.JSONArray
+import org.json.JSONObject
+import org.junit.Assert.assertTrue
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.junit.runner.RunWith
+
+private const val COLUMNS = 8
+
+/** Rasters that draw the same clusters match exactly; a wrong clustering differs by 0.12 or more. */
+private const val MATCH_TOLERANCE = 0.01f
+
+@RunWith(AndroidJUnit4::class)
+class TerminalRowLayoutTest {
+  private val font = TerminalFont("monospace", 40f, 1f)
+  private val paints = TerminalPaints()
+
+  /**
+   * Draws each row of `grapheme-rows.json` and compares it with its grapheme clusters drawn one at a
+   * time, each centred in its own columns. `terminal-frame.test.ts` checks that the rows are what
+   * xterm produces and that the clusters are UAX #29 grapheme clusters.
+   */
+  @Test
+  fun drawsEachGraphemeClusterInItsOwnColumns() {
+    val assets = InstrumentationRegistry.getInstrumentation().context.assets
+    val rows = JSONArray(assets.open("grapheme-rows.json").bufferedReader().readText())
+    for (index in 0 until rows.length()) {
+      val row = rows.getJSONObject(index)
+      val source = TerminalRowSource.decode(row.getString("row"))
+      val layout = TerminalRowLayout(source, font, TerminalCustomGlyphs.EMPTY)
+      // Selection covers row 0 only, so drawing as row 1 draws nothing selected.
+      val drawn = raster { layout.drawSelected(it, 1, TerminalSelection(TerminalSelectionRecord()), paints) }
+      val expected = raster { drawClusters(it, source, starts(row, "clusterStarts")) }
+      val contrast = raster { drawClusters(it, source, starts(row, "contrastStarts")) }
+      val output = row.getString("output")
+      val (toExpected, toContrast) = difference(drawn, expected) to difference(drawn, contrast)
+      Log.i("TerminalRowLayoutTest", "$output expected=$toExpected contrast=$toContrast")
+      assertTrue("$output differs from its grapheme clusters by $toExpected", toExpected <= MATCH_TOLERANCE)
+      assertTrue("$output also matches the wrong clusters", toContrast > MATCH_TOLERANCE)
+    }
+  }
+
+  @Test
+  fun selectionCompositesOverCellAndTerminalBackgroundsWithoutChangingForeground() {
+    val red = 0xffff0000.toInt()
+    val green = 0xff00aa00.toInt()
+    val overlay = 0x472684ff
+    val source = TerminalRowSource.decode("1,1;1,4294901760,4278233600,0;M")
+    val layout = TerminalRowLayout(source, font, TerminalCustomGlyphs.EMPTY)
+    paints.selectionBackground = overlay
+    for (terminalBackground in listOf(0xffffffff.toInt(), 0xff000000.toInt())) {
+      val actual = raster { canvas ->
+        canvas.drawColor(terminalBackground)
+        layout.drawSelected(canvas, 0, TerminalSelection(TerminalSelectionRecord()), paints)
+      }
+      val expected = raster { canvas ->
+        canvas.drawColor(terminalBackground)
+        canvas.drawColor(green)
+        canvas.drawColor(overlay)
+      }
+      assertEquals(expected.getPixel(0, 0), actual.getPixel(0, 0))
+      assertTrue("selected glyph retains its red foreground", (0 until font.cellHeightPx).any { y ->
+        (0 until font.cellWidthPx).any { x -> actual.getPixel(x, y) == red }
+      })
+    }
+    val defaultBackground = TerminalRowLayout(TerminalRowSource.decode("1,1;1,4294901760,0,0;M"), font, TerminalCustomGlyphs.EMPTY)
+    for (terminalBackground in listOf(0xffffffff.toInt(), 0xff000000.toInt())) {
+      val actual = raster { canvas ->
+        canvas.drawColor(terminalBackground)
+        defaultBackground.drawSelected(canvas, 0, TerminalSelection(TerminalSelectionRecord()), paints)
+      }
+      val expected = raster { canvas -> canvas.drawColor(terminalBackground); canvas.drawColor(overlay) }
+      assertEquals(expected.getPixel(0, 0), actual.getPixel(0, 0))
+    }
+  }
+
+  private fun starts(row: JSONObject, key: String): List<Int> =
+    row.getJSONArray(key).let { starts -> List(starts.length()) { starts.getInt(it) } }
+
+  private fun raster(draw: (Canvas) -> Unit): Bitmap {
+    val bitmap = Bitmap.createBitmap(COLUMNS * font.cellWidthPx, font.cellHeightPx, Bitmap.Config.ARGB_8888)
+    draw(Canvas(bitmap))
+    return bitmap
+  }
+
+  /** Draws each cluster as its own text, centred in its columns and scaled down when wider. */
+  private fun drawClusters(canvas: Canvas, source: TerminalRowSource, starts: List<Int>) {
+    val cellCount = source.cells.size / 2
+    val paint = Paint(font.paint(0)).apply { color = source.styles[1].toLong().toInt() }
+    val offsets = IntArray(cellCount + 1)
+    val cols = IntArray(cellCount + 1)
+    for (cell in 0 until cellCount) {
+      offsets[cell + 1] = offsets[cell] + source.cells[cell * 2]
+      cols[cell + 1] = cols[cell] + source.cells[cell * 2 + 1]
+    }
+    for ((index, first) in starts.withIndex()) {
+      val end = starts.getOrElse(index + 1) { cellCount }
+      val text = source.text.substring(offsets[first], offsets[end])
+      if (text.isBlank()) continue
+      val slot = (cols[end] - cols[first]) * font.cellWidthPx.toFloat()
+      val advance = paint.measureText(text)
+      val x = cols[first] * font.cellWidthPx + if (advance > slot + 1f) 0f else (slot - advance) / 2f
+      canvas.save()
+      if (advance > slot + 1f) canvas.scale(slot / advance, slot / advance, x, font.cellHeightPx / 2f)
+      canvas.drawText(text, x, font.baselinePx.toFloat(), paint)
+      canvas.restore()
+    }
+  }
+
+  /** Share of inked pixels, in either image, whose coverage differs by more than a quarter. */
+  private fun difference(a: Bitmap, b: Bitmap): Float {
+    var inked = 0
+    var differing = 0
+    for (y in 0 until a.height) {
+      for (x in 0 until a.width) {
+        val (left, right) = (a.getPixel(x, y) ushr 24) to (b.getPixel(x, y) ushr 24)
+        if (left < 64 && right < 64) continue
+        inked += 1
+        if (kotlin.math.abs(left - right) > 64) differing += 1
+      }
+    }
+    return if (inked == 0) 0f else differing.toFloat() / inked
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/android/src/main/AndroidManifest.xml b/packages/app/modules/paseo-terminal/android/src/main/AndroidManifest.xml
new file mode 100644
index 0000000000..94cbbcfc39
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/android/src/main/AndroidManifest.xml
@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />
diff --git a/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/PaseoTerminalModule.kt b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/PaseoTerminalModule.kt
new file mode 100644
index 0000000000..e6250ec280
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/PaseoTerminalModule.kt
@@ -0,0 +1,24 @@
+package sh.paseo.terminal
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class PaseoTerminalModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("PaseoTerminal")
+
+    View(PaseoTerminalView::class) {
+      Events("onCellMetrics")
+
+      Prop("frame") { view: PaseoTerminalView, frame: TerminalFrameRecord -> view.setFrame(frame) }
+      Prop("theme") { view: PaseoTerminalView, theme: TerminalThemeRecord -> view.setTheme(theme) }
+      Prop("fontFamily") { view: PaseoTerminalView, family: String -> view.setFontFamily(family) }
+      Prop("fontSize") { view: PaseoTerminalView, size: Double -> view.setFontSize(size) }
+      Prop("customGlyphs") { view: PaseoTerminalView, glyphs: List<TerminalCustomGlyphRecord> ->
+        view.setCustomGlyphs(glyphs)
+      }
+
+      OnViewDidUpdateProps { view: PaseoTerminalView -> view.commit() }
+    }
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/PaseoTerminalView.kt b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/PaseoTerminalView.kt
new file mode 100644
index 0000000000..03f76cf91b
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/PaseoTerminalView.kt
@@ -0,0 +1,195 @@
+package sh.paseo.terminal
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.Rect
+import android.os.Bundle
+import android.view.MotionEvent
+import android.widget.TextView
+import androidx.core.view.ViewCompat
+import androidx.core.view.accessibility.AccessibilityNodeInfoCompat
+import androidx.customview.widget.ExploreByTouchHelper
+import expo.modules.kotlin.AppContext
+import expo.modules.kotlin.viewevent.EventDispatcher
+import expo.modules.kotlin.views.ExpoView
+
+private const val MIN_CACHED_ROWS = 256
+private const val CURSOR_ALPHA = 0.45f
+
+/**
+ * Paints terminal frames on the cell grid. Row shaping is cached by row content, so cursor and
+ * selection changes repaint without reshaping, and unchanged rows replay their display lists.
+ */
+@SuppressLint("ViewConstructor")
+class PaseoTerminalView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
+  private val onCellMetrics by EventDispatcher<Map<String, Float>>()
+
+  private var fontFamily = "monospace"
+  private var fontSize = 12.0
+  private var font: TerminalFont? = null
+  private var customGlyphs = TerminalCustomGlyphs.EMPTY
+  private var frame: TerminalFrameRecord? = null
+  private var frameChanged = false
+
+  private var rows: List<TerminalRowLayout> = emptyList()
+  private var columns = 0
+  private var cursor: TerminalCursorRecord? = null
+  private var selection: TerminalSelection? = null
+  private var backgroundColor = Color.BLACK
+  private var cursorColor = Color.WHITE
+  private val paints = TerminalPaints()
+  private val rowCache = object : LinkedHashMap<String, TerminalRowLayout>(64, 0.75f, true) {
+    override fun removeEldestEntry(eldest: MutableMap.MutableEntry<String, TerminalRowLayout>): Boolean {
+      if (size <= maxOf(MIN_CACHED_ROWS, rows.size * 2)) return false
+      eldest.value.release()
+      return true
+    }
+  }
+  private val accessibility = RowAccessibility()
+
+  init {
+    setWillNotDraw(false)
+    ViewCompat.setAccessibilityDelegate(this, accessibility)
+  }
+
+  fun setFrame(value: TerminalFrameRecord) {
+    frame = value
+    frameChanged = true
+  }
+
+  fun setTheme(value: TerminalThemeRecord) {
+    backgroundColor = argb(value.background)
+    cursorColor = argb(value.cursor)
+    paints.selectionBackground = argb(value.selectionBackground)
+    invalidate()
+  }
+
+  fun setFontFamily(value: String) {
+    fontFamily = value
+  }
+
+  fun setFontSize(value: Double) {
+    fontSize = value
+  }
+
+  fun setCustomGlyphs(value: List<TerminalCustomGlyphRecord>) {
+    customGlyphs = TerminalCustomGlyphs(value)
+    clearRowCache()
+    frameChanged = true
+  }
+
+  /** Applies a batch of prop updates: font first, then the frame laid out with it. */
+  fun commit() {
+    val density = resources.displayMetrics.density
+    val sizePx = (fontSize * density).toFloat()
+    val current = font
+    if (current == null || !current.sameAs(fontFamily, sizePx, density)) {
+      val next = TerminalFont(fontFamily, sizePx, density)
+      font = next
+      clearRowCache()
+      frameChanged = true
+      onCellMetrics(
+        mapOf(
+          "cellWidth" to next.cellWidthPx / density,
+          "cellHeight" to next.cellHeightPx / density,
+        ),
+      )
+    }
+    if (frameChanged) {
+      frameChanged = false
+      layoutFrame()
+    }
+    invalidate()
+  }
+
+  private fun layoutFrame() {
+    val currentFont = font ?: return
+    val record = frame ?: return
+    columns = record.columns
+    cursor = record.cursor
+    selection = record.selection?.let(::TerminalSelection)
+    rows = record.rows.map { encoded ->
+      rowCache.getOrPut(encoded) {
+        TerminalRowLayout(TerminalRowSource.decode(encoded), currentFont, customGlyphs)
+      }
+    }
+    accessibility.invalidateRoot()
+  }
+
+  private fun clearRowCache() {
+    for (layout in rowCache.values) layout.release()
+    rowCache.clear()
+    rows = emptyList()
+  }
+
+  override fun onDraw(canvas: Canvas) {
+    super.onDraw(canvas)
+    canvas.drawColor(backgroundColor)
+    val currentFont = font ?: return
+    val cellWidth = currentFont.cellWidthPx
+    val cellHeight = currentFont.cellHeightPx
+    val gridWidth = columns * cellWidth
+    canvas.save()
+    canvas.clipRect(0, 0, minOf(width, gridWidth), height)
+    val activeSelection = selection
+    for ((index, row) in rows.withIndex()) {
+      canvas.save()
+      canvas.translate(0f, (index * cellHeight).toFloat())
+      if (activeSelection != null && activeSelection.intersectsRow(index)) {
+        row.drawSelected(canvas, index, activeSelection, paints)
+      } else {
+        row.draw(canvas, gridWidth, paints)
+      }
+      canvas.restore()
+    }
+    cursor?.let { position ->
+      paints.fill.color = withAlpha(cursorColor, CURSOR_ALPHA)
+      val left = (position.col * cellWidth).toFloat()
+      val top = (position.row * cellHeight).toFloat()
+      canvas.drawRect(left, top, left + cellWidth, top + cellHeight, paints.fill)
+    }
+    canvas.restore()
+  }
+
+  override fun dispatchHoverEvent(event: MotionEvent): Boolean =
+    accessibility.dispatchHoverEvent(event) || super.dispatchHoverEvent(event)
+
+  override fun onDetachedFromWindow() {
+    super.onDetachedFromWindow()
+    for (layout in rowCache.values) layout.release()
+  }
+
+  private fun withAlpha(color: Int, alpha: Float): Int =
+    Color.argb((Color.alpha(color) * alpha).toInt(), Color.red(color), Color.green(color), Color.blue(color))
+
+  /** Exposes each non-blank row as a virtual text node, `terminal-row-<index>`. */
+  private inner class RowAccessibility : ExploreByTouchHelper(this@PaseoTerminalView) {
+    override fun getVirtualViewAt(x: Float, y: Float): Int {
+      val cellHeight = font?.cellHeightPx ?: return INVALID_ID
+      val row = (y / cellHeight).toInt()
+      return if (row in rows.indices && rows[row].describe().isNotEmpty()) row else INVALID_ID
+    }
+
+    override fun getVisibleVirtualViews(virtualViewIds: MutableList<Int>) {
+      for ((index, row) in rows.withIndex()) {
+        if (row.describe().isNotEmpty()) virtualViewIds.add(index)
+      }
+    }
+
+    @Suppress("DEPRECATION")
+    override fun onPopulateNodeForVirtualView(virtualViewId: Int, node: AccessibilityNodeInfoCompat) {
+      val cellHeight = font?.cellHeightPx ?: 1
+      val label = rows.getOrNull(virtualViewId)?.describe().orEmpty()
+      node.className = TextView::class.java.name
+      node.text = label
+      node.contentDescription = label
+      node.viewIdResourceName = "terminal-row-$virtualViewId"
+      val top = virtualViewId * cellHeight
+      node.setBoundsInParent(Rect(0, top, minOf(width, columns * (font?.cellWidthPx ?: 1)), top + cellHeight))
+    }
+
+    override fun onPerformActionForVirtualView(virtualViewId: Int, action: Int, arguments: Bundle?): Boolean = false
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalCustomGlyphs.kt b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalCustomGlyphs.kt
new file mode 100644
index 0000000000..ce1e8d5229
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalCustomGlyphs.kt
@@ -0,0 +1,76 @@
+package sh.paseo.terminal
+
+import android.graphics.Canvas
+import android.graphics.Paint
+import android.graphics.Path
+
+/**
+ * Box drawing and block elements painted as cell geometry instead of font glyphs, so frames and
+ * blocks join across cells regardless of the font's own metrics.
+ */
+internal class TerminalCustomGlyph(record: TerminalCustomGlyphRecord) {
+  private val rects: FloatArray = FloatArray(record.rects.size) { record.rects[it].toFloat() }
+  private val commands: DoubleArray = record.path
+  private val strokeWidth: Float = record.strokeWidth.toFloat()
+  private var scaledPath: Path? = null
+  private var scaledWidth = 0f
+  private var scaledHeight = 0f
+
+  fun draw(canvas: Canvas, x: Float, width: Float, height: Float, density: Float, paint: Paint) {
+    paint.style = Paint.Style.FILL
+    var index = 0
+    while (index + 3 < rects.size) {
+      canvas.drawRect(
+        x + rects[index] * width,
+        rects[index + 1] * height,
+        x + (rects[index] + rects[index + 2]) * width,
+        (rects[index + 1] + rects[index + 3]) * height,
+        paint,
+      )
+      index += 4
+    }
+    if (commands.isEmpty()) return
+    val path = pathFor(width, height)
+    paint.style = Paint.Style.STROKE
+    paint.strokeWidth = strokeWidth * density
+    paint.strokeCap = Paint.Cap.BUTT
+    paint.strokeJoin = Paint.Join.MITER
+    canvas.save()
+    canvas.translate(x, 0f)
+    canvas.drawPath(path, paint)
+    canvas.restore()
+    paint.style = Paint.Style.FILL
+  }
+
+  private fun pathFor(width: Float, height: Float): Path {
+    val cached = scaledPath
+    if (cached != null && scaledWidth == width && scaledHeight == height) return cached
+    val path = Path()
+    var index = 0
+    while (index < commands.size) {
+      val x = { offset: Int -> commands[index + offset].toFloat() * width }
+      val y = { offset: Int -> commands[index + offset].toFloat() * height }
+      when (commands[index].toInt()) {
+        0 -> { path.moveTo(x(1), y(2)); index += 3 }
+        1 -> { path.lineTo(x(1), y(2)); index += 3 }
+        2 -> { path.quadTo(x(1), y(2), x(3), y(4)); index += 5 }
+        else -> index = commands.size
+      }
+    }
+    scaledPath = path
+    scaledWidth = width
+    scaledHeight = height
+    return path
+  }
+}
+
+internal class TerminalCustomGlyphs(records: List<TerminalCustomGlyphRecord>) {
+  private val glyphs: Map<String, TerminalCustomGlyph> =
+    records.associate { it.char to TerminalCustomGlyph(it) }
+
+  operator fun get(text: String): TerminalCustomGlyph? = glyphs[text]
+
+  companion object {
+    val EMPTY = TerminalCustomGlyphs(emptyList())
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalFont.kt b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalFont.kt
new file mode 100644
index 0000000000..046efd1e18
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalFont.kt
@@ -0,0 +1,61 @@
+package sh.paseo.terminal
+
+import android.graphics.Paint
+import android.graphics.Typeface
+import kotlin.math.max
+import kotlin.math.roundToInt
+
+private const val MEASURE_TEXT = "mmmmmmmmmm"
+
+/**
+ * The terminal font at one pixel size: a paint per face (regular, bold, italic, bold italic) and
+ * the cell those faces are laid out on. Cells are whole device pixels so every column origin is
+ * exact. Platform fallback fonts cover characters the family lacks.
+ */
+internal class TerminalFont(val family: String, val sizePx: Float, val density: Float) {
+  private val faces: Array<Paint> = Array(4) { face ->
+    Paint(Paint.ANTI_ALIAS_FLAG or Paint.SUBPIXEL_TEXT_FLAG).apply {
+      typeface = Typeface.create(family, typefaceStyle(face))
+      textSize = sizePx
+    }
+  }
+
+  val cellWidthPx: Int
+  val cellHeightPx: Int
+  val baselinePx: Int
+  val underlineOffsetPx: Float
+  val underlineThicknessPx: Float
+  val strikeOffsetPx: Float
+  val strikeThicknessPx: Float
+
+  init {
+    val regular = faces[0]
+    cellWidthPx = max(1, (regular.measureText(MEASURE_TEXT) / MEASURE_TEXT.length).roundToInt())
+    val metrics = regular.fontMetricsInt
+    cellHeightPx = max(1, metrics.descent - metrics.ascent)
+    baselinePx = -metrics.ascent
+    underlineOffsetPx = regular.underlinePosition
+    underlineThicknessPx = max(1f, regular.underlineThickness)
+    strikeOffsetPx = regular.strikeThruPosition
+    strikeThicknessPx = max(1f, regular.strikeThruThickness)
+  }
+
+  /** Paint for a style's face; callers only change its color. */
+  fun paint(flags: Int): Paint = faces[face(flags)]
+
+  fun sameAs(family: String, sizePx: Float, density: Float): Boolean =
+    this.family == family && this.sizePx == sizePx && this.density == density
+
+  companion object {
+    fun face(flags: Int): Int =
+      (if (flags and TerminalStyleFlags.BOLD != 0) 1 else 0) +
+        (if (flags and TerminalStyleFlags.ITALIC != 0) 2 else 0)
+
+    private fun typefaceStyle(face: Int): Int = when (face) {
+      1 -> Typeface.BOLD
+      2 -> Typeface.ITALIC
+      3 -> Typeface.BOLD_ITALIC
+      else -> Typeface.NORMAL
+    }
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalFrame.kt b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalFrame.kt
new file mode 100644
index 0000000000..a33eca76e6
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalFrame.kt
@@ -0,0 +1,99 @@
+package sh.paseo.terminal
+
+import expo.modules.kotlin.records.Field
+import expo.modules.kotlin.records.Record
+
+class TerminalCursorRecord : Record {
+  @Field val row: Int = 0
+  @Field val col: Int = 0
+}
+
+class TerminalSelectionRecord : Record {
+  @Field val startRow: Int = 0
+  @Field val startCol: Int = 0
+  @Field val endRow: Int = 0
+  @Field val endCol: Int = 0
+}
+
+class TerminalFrameRecord : Record {
+  @Field val columns: Int = 0
+  /** Encoded rows, `cells;styles;text`; see `frame-encoding.ts`. */
+  @Field val rows: List<String> = emptyList()
+  @Field val cursor: TerminalCursorRecord? = null
+  @Field val selection: TerminalSelectionRecord? = null
+}
+
+class TerminalThemeRecord : Record {
+  @Field val background: Double = 0.0
+  @Field val cursor: Double = 0.0
+  @Field val selectionBackground: Double = 0.0
+}
+
+class TerminalCustomGlyphRecord : Record {
+  @Field val char: String = ""
+  @Field val rects: DoubleArray = DoubleArray(0)
+  @Field val path: DoubleArray = DoubleArray(0)
+  @Field val strokeWidth: Double = 0.0
+}
+
+internal object TerminalStyleFlags {
+  const val BOLD = 1
+  const val ITALIC = 2
+  const val UNDERLINE = 4
+  const val STRIKETHROUGH = 8
+}
+
+/** JS sends colors as unsigned ARGB numbers; Android paints signed ARGB ints. */
+internal fun argb(value: Double): Int = value.toLong().toInt()
+
+/** One row as the caller described it: cell text, column spans and style spans. */
+internal class TerminalRowSource private constructor(
+  val text: String,
+  val cells: IntArray,
+  val styles: DoubleArray,
+) {
+  companion object {
+    /** Decodes `cells;styles;text`, where both number lists are comma separated. */
+    fun decode(encoded: String): TerminalRowSource {
+      val cellsEnd = encoded.indexOf(';')
+      val stylesEnd = encoded.indexOf(';', cellsEnd + 1)
+      val cells = parseNumbers(encoded, 0, cellsEnd)
+      val styles = parseNumbers(encoded, cellsEnd + 1, stylesEnd)
+      return TerminalRowSource(
+        encoded.substring(stylesEnd + 1),
+        IntArray(cells.size) { cells[it].toInt() },
+        DoubleArray(styles.size) { styles[it].toDouble() },
+      )
+    }
+
+    private fun parseNumbers(encoded: String, start: Int, end: Int): LongArray {
+      if (end <= start) return LongArray(0)
+      var count = 1
+      for (index in start until end) if (encoded[index] == ',') count += 1
+      val numbers = LongArray(count)
+      var slot = 0
+      for (index in start until end) {
+        val char = encoded[index]
+        if (char == ',') slot += 1 else numbers[slot] = numbers[slot] * 10 + (char - '0')
+      }
+      return numbers
+    }
+  }
+}
+
+internal class TerminalSelection(record: TerminalSelectionRecord) {
+  private val startRow = record.startRow
+  private val startCol = record.startCol
+  private val endRow = record.endRow
+  private val endCol = record.endCol
+
+  fun intersectsRow(row: Int): Boolean = row in startRow..endRow
+
+  /** A cell is selected when any column it covers is inside the inclusive range. */
+  fun contains(row: Int, col: Int, span: Int): Boolean {
+    if (!intersectsRow(row)) return false
+    val firstCol = if (row == startRow) startCol else 0
+    val lastCol = if (row == endRow) endCol else Int.MAX_VALUE
+    return col + span - 1 >= firstCol && col <= lastCol
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalRowLayout.kt b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalRowLayout.kt
new file mode 100644
index 0000000000..6680f15ed9
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/android/src/main/java/sh/paseo/terminal/TerminalRowLayout.kt
@@ -0,0 +1,302 @@
+package sh.paseo.terminal
+
+import android.graphics.Canvas
+import android.graphics.Paint
+import android.graphics.RenderNode
+import android.graphics.text.MeasuredText
+import android.icu.text.BreakIterator
+
+/** Shaped glyphs may exceed their slot by this many pixels before they are scaled down. */
+private const val OVERFLOW_TOLERANCE_PX = 1f
+/** Stands in for an open edge when a group is clipped on one side only. */
+private const val CLIP_UNBOUNDED_PX = 100_000f
+
+/**
+ * One row shaped once and placed on the terminal grid.
+ *
+ * Each run of cells with the same font face is shaped as a whole, so contextual forms, ligatures,
+ * marks and fallback fonts see their neighbours. The shaper reports a cluster's advance on its
+ * first UTF-16 unit and zero on the units it absorbed. A cell whose first unit has zero advance
+ * therefore belongs to the cluster of the cell before it: a ligature, conjunct, emoji sequence or
+ * reordered mark that spans columns. A cell that does not start a grapheme cluster also stays with
+ * the cell before it: a half-form conjunct such as स्त keeps both consonants' advances, and drawing
+ * either half alone would show an explicit virama. Each resulting group is drawn from the shaped
+ * run (in context) at its first cell's column, centred in the columns it owns, and scaled down only when
+ * its glyphs are wider than those columns. Colors never split groups or reshape the row: a group
+ * whose cells differ in color is drawn once per color, clipped to those cells' columns.
+ */
+internal class TerminalRowLayout(
+  val source: TerminalRowSource,
+  private val font: TerminalFont,
+  private val customGlyphs: TerminalCustomGlyphs,
+) {
+  private val chars: CharArray = source.text.toCharArray()
+  private val cellCount = source.cells.size / 2
+  private val cellCol = IntArray(cellCount)
+  private val cellSpan = IntArray(cellCount)
+  private val cellStart = IntArray(cellCount)
+  private val cellEnd = IntArray(cellCount)
+  private val cellForeground = IntArray(cellCount)
+  private val cellBackground = IntArray(cellCount)
+  private val cellFlags = IntArray(cellCount)
+  private val cellGlyph = arrayOfNulls<TerminalCustomGlyph>(cellCount)
+  private val groups = ArrayList<Group>()
+  private val measured: MeasuredText?
+  val text: String get() = source.text
+
+  private var node: RenderNode? = null
+
+  private class Group(
+    val firstCell: Int,
+    val lastCell: Int,
+    val col: Int,
+    val start: Int,
+    val end: Int,
+    val contextStart: Int,
+    val contextEnd: Int,
+    val offsetPx: Float,
+    val scale: Float,
+    val blank: Boolean,
+  )
+
+  init {
+    readCells()
+    measured = measure()
+    if (measured != null) buildGroups(measured)
+  }
+
+  private fun readCells() {
+    var offset = 0
+    var col = 0
+    var styleIndex = 0
+    var styleEndCol = 0
+    for (cell in 0 until cellCount) {
+      val length = source.cells[cell * 2]
+      val span = maxOf(1, source.cells[cell * 2 + 1])
+      while (col >= styleEndCol && styleIndex + 3 < source.styles.size) {
+        styleEndCol += source.styles[styleIndex].toInt()
+        styleIndex += 4
+      }
+      val style = styleIndex - 4
+      if (style >= 0) {
+        cellForeground[cell] = argb(source.styles[style + 1])
+        cellBackground[cell] = argb(source.styles[style + 2])
+        cellFlags[cell] = source.styles[style + 3].toInt()
+      }
+      cellCol[cell] = col
+      cellSpan[cell] = span
+      cellStart[cell] = offset
+      cellEnd[cell] = minOf(chars.size, offset + length)
+      cellGlyph[cell] = customGlyphs[source.text.substring(cellStart[cell], cellEnd[cell])]
+      offset = cellEnd[cell]
+      col += span
+    }
+  }
+
+  /** Same face, not custom glyph: cells shaped together. */
+  private fun shapesWith(cell: Int, other: Int): Boolean =
+    cellGlyph[cell] == null && cellGlyph[other] == null &&
+      TerminalFont.face(cellFlags[cell]) == TerminalFont.face(cellFlags[other])
+
+  private fun measure(): MeasuredText? {
+    if (chars.isEmpty()) return null
+    val builder = MeasuredText.Builder(chars)
+    var cell = 0
+    while (cell < cellCount) {
+      var last = cell
+      while (last + 1 < cellCount && shapesWith(cell, last + 1)) last += 1
+      val length = cellEnd[last] - cellStart[cell]
+      if (length > 0) {
+        if (cellGlyph[cell] != null) {
+          builder.appendReplacementRun(font.paint(cellFlags[cell]), length, 0f)
+        } else {
+          builder.appendStyleRun(font.paint(cellFlags[cell]), length, false)
+        }
+      }
+      cell = last + 1
+    }
+    val trailing = chars.size - (if (cellCount > 0) cellEnd[cellCount - 1] else 0)
+    if (trailing > 0) builder.appendReplacementRun(font.paint(0), trailing, 0f)
+    return builder.build()
+  }
+
+  private fun buildGroups(measured: MeasuredText) {
+    // Keep platform graphemes together even when Minikin reports separate advances/cursors.
+    // Rules follow the OS ICU version: Android 10 splits Indic conjuncts such as स्ते.
+    val graphemes = BreakIterator.getCharacterInstance()
+    graphemes.setText(source.text)
+    var cell = 0
+    while (cell < cellCount) {
+      if (cellGlyph[cell] != null) {
+        cell += 1
+        continue
+      }
+      var last = cell
+      while (last + 1 < cellCount && shapesWith(cell, last + 1)) last += 1
+      val contextStart = cellStart[cell]
+      val contextEnd = cellEnd[last]
+      var first = cell
+      for (next in cell + 1..last) {
+        val startsCluster =
+          cellEnd[next] > cellStart[next] &&
+            measured.getCharWidthAt(cellStart[next]) != 0f &&
+            graphemes.isBoundary(cellStart[next])
+        if (startsCluster) {
+          addGroup(measured, first, next - 1, contextStart, contextEnd)
+          first = next
+        }
+      }
+      addGroup(measured, first, last, contextStart, contextEnd)
+      cell = last + 1
+    }
+  }
+
+  private fun addGroup(measured: MeasuredText, first: Int, last: Int, contextStart: Int, contextEnd: Int) {
+    val start = cellStart[first]
+    val end = cellEnd[last]
+    if (end <= start) return
+    var columns = 0
+    for (cell in first..last) columns += cellSpan[cell]
+    val slot = (columns * font.cellWidthPx).toFloat()
+    val advance = measured.getWidth(start, end)
+    val scale = if (advance > slot + OVERFLOW_TOLERANCE_PX) slot / advance else 1f
+    val offset = if (scale < 1f) 0f else (slot - advance) / 2f
+    var blank = true
+    for (index in start until end) {
+      if (chars[index] != ' ') {
+        blank = false
+        break
+      }
+    }
+    groups.add(Group(first, last, cellCol[first], start, end, contextStart, contextEnd, offset, scale, blank))
+  }
+
+  /** Draws the row with its own colors, replaying a recorded display list when possible. */
+  fun draw(canvas: Canvas, width: Int, paints: TerminalPaints) {
+    if (!canvas.isHardwareAccelerated) {
+      drawContent(canvas, -1, null, paints)
+      return
+    }
+    // Marks stacked above or below a letter ink outside the row. The node must not clip them: the
+    // view redraws every row on each frame, so ink outside the row is never left stale.
+    val recorded = node ?: RenderNode("terminal-row").also {
+      it.setClipToBounds(false)
+      node = it
+    }
+    if (!recorded.hasDisplayList() || recorded.width != width) {
+      recorded.setPosition(0, 0, width, font.cellHeightPx)
+      val recording = recorded.beginRecording()
+      try {
+        drawContent(recording, -1, null, paints)
+      } finally {
+        recorded.endRecording()
+      }
+    }
+    canvas.drawRenderNode(recorded)
+  }
+
+  /** Draws backgrounds, the selection overlay, then text with its original colors. */
+  fun drawSelected(canvas: Canvas, row: Int, selection: TerminalSelection, paints: TerminalPaints) {
+    drawContent(canvas, row, selection, paints)
+  }
+
+  fun release() {
+    node?.discardDisplayList()
+    node = null
+  }
+
+  private fun selected(row: Int, selection: TerminalSelection?, cell: Int): Boolean =
+    selection?.contains(row, cellCol[cell], cellSpan[cell]) == true
+
+  private fun drawContent(canvas: Canvas, row: Int, selection: TerminalSelection?, paints: TerminalPaints) {
+    val cellWidth = font.cellWidthPx.toFloat()
+    val cellHeight = font.cellHeightPx.toFloat()
+    val fill = paints.fill
+    for (cell in 0 until cellCount) {
+      val left = cellCol[cell] * cellWidth
+      val right = (cellCol[cell] + cellSpan[cell]) * cellWidth
+      val background = cellBackground[cell]
+      if (background ushr 24 != 0) {
+        fill.color = background
+        canvas.drawRect(left, 0f, right, cellHeight, fill)
+      }
+      if (selected(row, selection, cell)) {
+        fill.color = paints.selectionBackground
+        canvas.drawRect(left, 0f, right, cellHeight, fill)
+      }
+    }
+
+    val baseline = font.baselinePx.toFloat()
+    val text = measured
+    if (text != null) {
+      for (group in groups) {
+        if (group.blank) continue
+        val paint = font.paint(cellFlags[group.firstCell])
+        var first = group.firstCell
+        while (first <= group.lastCell) {
+          val color = cellForeground[first]
+          var last = first
+          while (last < group.lastCell && cellForeground[last + 1] == color) last += 1
+          // Only edges between differently colored cells clip; the group's outer edges may overhang.
+          val clipped = first > group.firstCell || last < group.lastCell
+          canvas.save()
+          if (clipped) {
+            val left = if (first > group.firstCell) cellCol[first] * cellWidth else -CLIP_UNBOUNDED_PX
+            val right =
+              if (last < group.lastCell) (cellCol[last] + cellSpan[last]) * cellWidth else CLIP_UNBOUNDED_PX
+            canvas.clipRect(left, -CLIP_UNBOUNDED_PX, right, CLIP_UNBOUNDED_PX)
+          }
+          paint.color = color
+          drawGroupText(canvas, text, group, paint, cellWidth, cellHeight, baseline)
+          canvas.restore()
+          first = last + 1
+        }
+      }
+    }
+
+    for (cell in 0 until cellCount) {
+      val glyph = cellGlyph[cell]
+      val flags = cellFlags[cell]
+      val foreground = cellForeground[cell]
+      if (glyph != null) {
+        fill.color = foreground
+        glyph.draw(canvas, cellCol[cell] * cellWidth, cellSpan[cell] * cellWidth, cellHeight, font.density, fill)
+      }
+      if (flags and (TerminalStyleFlags.UNDERLINE or TerminalStyleFlags.STRIKETHROUGH) == 0) continue
+      fill.color = foreground
+      val left = cellCol[cell] * cellWidth
+      val right = left + cellSpan[cell] * cellWidth
+      if (flags and TerminalStyleFlags.UNDERLINE != 0) {
+        val top = baseline + font.underlineOffsetPx
+        canvas.drawRect(left, top, right, top + font.underlineThicknessPx, fill)
+      }
+      if (flags and TerminalStyleFlags.STRIKETHROUGH != 0) {
+        val top = baseline + font.strikeOffsetPx
+        canvas.drawRect(left, top, right, top + font.strikeThicknessPx, fill)
+      }
+    }
+  }
+
+  private fun drawGroupText(
+    canvas: Canvas,
+    text: MeasuredText,
+    group: Group,
+    paint: Paint,
+    cellWidth: Float,
+    cellHeight: Float,
+    baseline: Float,
+  ) {
+    val x = group.col * cellWidth + group.offsetPx
+    if (group.scale < 1f) canvas.scale(group.scale, group.scale, x, cellHeight / 2f)
+    canvas.drawTextRun(text, group.start, group.end, group.contextStart, group.contextEnd, x, baseline, false, paint)
+  }
+
+  /** The row's text as accessibility reads it. */
+  fun describe(): String = source.text.trimEnd()
+}
+
+/** Paint state shared by every row of one view. */
+internal class TerminalPaints {
+  val fill = Paint(Paint.ANTI_ALIAS_FLAG)
+  var selectionBackground: Int = 0x472684FF
+}
diff --git a/packages/app/modules/paseo-terminal/contract.ts b/packages/app/modules/paseo-terminal/contract.ts
new file mode 100644
index 0000000000..6fd6c0906b
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/contract.ts
@@ -0,0 +1,59 @@
+/**
+ * Native terminal renderer. The caller owns terminal state (xterm), input and gestures; this view
+ * shapes and paints one frame of terminal cells on the authoritative cell grid and reports the
+ * cell size its font produces.
+ *
+ * Colors are unsigned 32-bit ARGB numbers (`0xAARRGGBB`). Alpha 0 means "not painted".
+ */
+export interface PaseoTerminalFrame {
+  /** Columns the frame paints. Cells beyond it are clipped. */
+  columns: number;
+  rows: PaseoTerminalRow[];
+  cursor: PaseoTerminalCursor | null;
+  selection: PaseoTerminalSelection | null;
+}
+
+/**
+ * One terminal row. Cells start at column 0 and are consecutive. `text` is every cell's text in
+ * order, so cell `i` owns the next `cells[2i]` UTF-16 code units of `text` and covers the next
+ * `cells[2i + 1]` columns. Style spans are consecutive from column 0 and cover all columns.
+ */
+export interface PaseoTerminalRow {
+  text: string;
+  /** Flattened `[utf16Length, columnSpan]` per cell. */
+  cells: number[];
+  /** Flattened `[columnCount, foreground, background, flags]` per style span. */
+  styles: number[];
+}
+
+export interface PaseoTerminalCursor {
+  row: number;
+  col: number;
+}
+
+/** Inclusive cell range in frame rows. A cell is selected when any of its columns is. */
+export interface PaseoTerminalSelection {
+  startRow: number;
+  startCol: number;
+  endRow: number;
+  endCol: number;
+}
+
+export interface PaseoTerminalTheme {
+  background: number;
+  cursor: number;
+  selectionBackground: number;
+}
+
+export interface PaseoTerminalCellMetrics {
+  cellWidth: number;
+  cellHeight: number;
+}
+
+export const PASEO_TERMINAL_STYLE_FLAGS = {
+  bold: 1,
+  italic: 2,
+  underline: 4,
+  strikethrough: 8,
+  dim: 16,
+} as const;
diff --git a/packages/app/src/terminal/native-renderer/terminal-custom-glyph.test.ts b/packages/app/modules/paseo-terminal/custom-glyphs.test.ts
similarity index 81%
rename from packages/app/src/terminal/native-renderer/terminal-custom-glyph.test.ts
rename to packages/app/modules/paseo-terminal/custom-glyphs.test.ts
index 95de6c8c54..f3892110c0 100644
--- a/packages/app/src/terminal/native-renderer/terminal-custom-glyph.test.ts
+++ b/packages/app/modules/paseo-terminal/custom-glyphs.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { resolveTerminalCustomGlyph } from "./terminal-custom-glyph";
+import { encodeTerminalCustomGlyphs, resolveTerminalCustomGlyph } from "./custom-glyphs";
 
 describe("native terminal custom glyphs", () => {
   it("fills the complete cell for the full block used by the Claude mascot", () => {
@@ -85,4 +85,22 @@ describe("native terminal custom glyphs", () => {
       expect(resolveTerminalCustomGlyph(char), `missing custom glyph ${char}`).not.toBeNull();
     }
   });
+
+  it("encodes every glyph for the native renderer in cell fractions", () => {
+    const encoded = new Map(encodeTerminalCustomGlyphs().map((glyph) => [glyph.char, glyph]));
+
+    expect(encoded.get("▛")).toEqual({
+      char: "▛",
+      rects: [0, 0, 0.5, 0.5, 0.5, 0, 0.5, 0.5, 0, 0.5, 0.5, 0.5],
+      path: [],
+      strokeWidth: 0,
+    });
+    expect(encoded.get("╭")).toEqual({
+      char: "╭",
+      rects: [],
+      path: [0, 0.5, 1, 1, 0.5, 0.75, 2, 0.5, 0.5, 0.75, 0.5, 1, 1, 0.5],
+      strokeWidth: 1,
+    });
+    expect(encoded.get("┣")?.strokeWidth).toBe(3);
+  });
 });
diff --git a/packages/app/src/terminal/native-renderer/terminal-custom-glyph.ts b/packages/app/modules/paseo-terminal/custom-glyphs.ts
similarity index 66%
rename from packages/app/src/terminal/native-renderer/terminal-custom-glyph.ts
rename to packages/app/modules/paseo-terminal/custom-glyphs.ts
index f63de40e24..fd55193f74 100644
--- a/packages/app/src/terminal/native-renderer/terminal-custom-glyph.ts
+++ b/packages/app/modules/paseo-terminal/custom-glyphs.ts
@@ -82,12 +82,60 @@ const BLOCK_GLYPHS: Readonly<Record<string, TerminalRectGlyph>> = {
   "▟": rects(upperRight(), lowerLeft(), lowerRight()),
 };
 
+/**
+ * One custom glyph as the native view consumes it. Coordinates are fractions of one cell.
+ * `rects` is flattened `[x, y, width, height]`. `path` is flattened commands:
+ * `0 x y` moves, `1 x y` draws a line, `2 cx cy x y` draws a quadratic curve. Paths are
+ * stroked with `strokeWidth` points regardless of cell size.
+ */
+export interface PaseoTerminalCustomGlyph {
+  char: string;
+  rects: number[];
+  path: number[];
+  strokeWidth: number;
+}
+
+const PATH_COMMAND_CODES: Readonly<Record<string, { code: number; coordinates: number }>> = {
+  M: { code: 0, coordinates: 2 },
+  L: { code: 1, coordinates: 2 },
+  Q: { code: 2, coordinates: 4 },
+};
+
 export function resolveTerminalCustomGlyph(char: string): TerminalCustomGlyph | null {
   return LIGHT_BOX_GLYPHS[char] ?? HEAVY_BOX_GLYPHS[char] ?? BLOCK_GLYPHS[char] ?? null;
 }
 
-export function isTerminalCustomGlyph(char: string): boolean {
-  return resolveTerminalCustomGlyph(char) !== null;
+export function encodeTerminalCustomGlyphs(): PaseoTerminalCustomGlyph[] {
+  const table = { ...LIGHT_BOX_GLYPHS, ...HEAVY_BOX_GLYPHS, ...BLOCK_GLYPHS };
+  return Object.entries(table).map(([char, glyph]) =>
+    glyph.kind === "rects"
+      ? {
+          char,
+          rects: glyph.rects.flatMap((value) => [value.x, value.y, value.width, value.height]),
+          path: [],
+          strokeWidth: 0,
+        }
+      : { char, rects: [], path: encodePath(glyph.path), strokeWidth: glyph.strokeWidth },
+  );
+}
+
+function encodePath(pathData: string): number[] {
+  const tokens = pathData.match(/[MLQ]|-?\d*\.?\d+/g) ?? [];
+  const encoded: number[] = [];
+  let index = 0;
+  while (index < tokens.length) {
+    const command = PATH_COMMAND_CODES[tokens[index]];
+    if (!command) {
+      throw new Error(`Unsupported terminal glyph path command in ${pathData}`);
+    }
+    const coordinates = tokens.slice(index + 1, index + 1 + command.coordinates).map(Number);
+    if (coordinates.length !== command.coordinates || coordinates.some(Number.isNaN)) {
+      throw new Error(`Malformed terminal glyph path ${pathData}`);
+    }
+    encoded.push(command.code, ...coordinates);
+    index += 1 + command.coordinates;
+  }
+  return encoded;
 }
 
 function path(pathData: string, strokeWidth = 1): TerminalPathGlyph {
diff --git a/packages/app/modules/paseo-terminal/expo-module.config.json b/packages/app/modules/paseo-terminal/expo-module.config.json
new file mode 100644
index 0000000000..6291f992c1
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/expo-module.config.json
@@ -0,0 +1,9 @@
+{
+  "platforms": ["android", "ios"],
+  "android": {
+    "modules": ["sh.paseo.terminal.PaseoTerminalModule"]
+  },
+  "ios": {
+    "modules": ["PaseoTerminalModule"]
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/frame-encoding.test.ts b/packages/app/modules/paseo-terminal/frame-encoding.test.ts
new file mode 100644
index 0000000000..a40d4302c2
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/frame-encoding.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, test } from "vitest";
+
+import { encodeTerminalFrame } from "./frame-encoding";
+
+describe("encodeTerminalFrame", () => {
+  test("puts cells and styles before text, so text may contain separators", () => {
+    const native = encodeTerminalFrame({
+      columns: 10,
+      rows: [
+        {
+          text: "안a;b,",
+          cells: [1, 2, 1, 1, 1, 1, 1, 1, 1, 1],
+          styles: [3, 0xffe5e5e5, 0, 0, 3, 0xffff0000, 0, 1],
+        },
+        { text: "", cells: [], styles: [] },
+      ],
+      cursor: { row: 1, col: 0 },
+      selection: { startRow: 0, startCol: 0, endRow: 0, endCol: 1 },
+    });
+
+    expect(native).toEqual({
+      columns: 10,
+      rows: ["1,2,1,1,1,1,1,1,1,1;3,4293256677,0,0,3,4294901760,0,1;안a;b,", ";;"],
+      cursor: { row: 1, col: 0 },
+      selection: { startRow: 0, startCol: 0, endRow: 0, endCol: 1 },
+    });
+  });
+
+  test("leaves out a missing cursor and selection instead of sending null", () => {
+    const native = encodeTerminalFrame({ columns: 1, rows: [], cursor: null, selection: null });
+
+    expect(Object.keys(native)).toEqual(["columns", "rows"]);
+  });
+});
diff --git a/packages/app/modules/paseo-terminal/frame-encoding.ts b/packages/app/modules/paseo-terminal/frame-encoding.ts
new file mode 100644
index 0000000000..fc4d113bd2
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/frame-encoding.ts
@@ -0,0 +1,27 @@
+import type { PaseoTerminalCursor, PaseoTerminalFrame, PaseoTerminalSelection } from "./contract";
+
+/** A frame as it crosses to native. */
+export interface NativePaseoTerminalFrame {
+  columns: number;
+  rows: string[];
+  cursor?: PaseoTerminalCursor;
+  selection?: PaseoTerminalSelection;
+}
+
+/**
+ * Rows cross as `cells;styles;text`, with the numbers comma separated. One string per row keeps
+ * prop conversion to a single copy instead of one call per number, and the string is also the
+ * native shaping cache key, so an unchanged row costs one lookup.
+ *
+ * A missing cursor or selection is left out rather than sent as `null`: Expo on iOS fails to
+ * convert `null` into an optional record field and then drops the whole frame.
+ */
+export function encodeTerminalFrame(frame: PaseoTerminalFrame): NativePaseoTerminalFrame {
+  const native: NativePaseoTerminalFrame = {
+    columns: frame.columns,
+    rows: frame.rows.map((row) => `${row.cells.join(",")};${row.styles.join(",")};${row.text}`),
+  };
+  if (frame.cursor) native.cursor = frame.cursor;
+  if (frame.selection) native.selection = frame.selection;
+  return native;
+}
diff --git a/packages/app/modules/paseo-terminal/index.tsx b/packages/app/modules/paseo-terminal/index.tsx
new file mode 100644
index 0000000000..321cf7c30c
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/index.tsx
@@ -0,0 +1,47 @@
+import { requireNativeView } from "expo";
+import { useCallback, useMemo } from "react";
+import type { StyleProp, ViewStyle } from "react-native";
+
+import type { PaseoTerminalCellMetrics, PaseoTerminalFrame, PaseoTerminalTheme } from "./contract";
+import { encodeTerminalCustomGlyphs, type PaseoTerminalCustomGlyph } from "./custom-glyphs";
+import { encodeTerminalFrame, type NativePaseoTerminalFrame } from "./frame-encoding";
+
+export * from "./contract";
+
+export interface PaseoTerminalViewProps {
+  frame: PaseoTerminalFrame;
+  theme: PaseoTerminalTheme;
+  fontFamily: string;
+  /** Font size in points after the system font scale is applied. */
+  fontSize: number;
+  onCellMetrics?: (metrics: PaseoTerminalCellMetrics) => void;
+  style?: StyleProp<ViewStyle>;
+}
+
+interface NativePaseoTerminalViewProps extends Omit<
+  PaseoTerminalViewProps,
+  "frame" | "onCellMetrics"
+> {
+  frame: NativePaseoTerminalFrame;
+  customGlyphs: PaseoTerminalCustomGlyph[];
+  onCellMetrics?: (event: { nativeEvent: PaseoTerminalCellMetrics }) => void;
+}
+
+const NativePaseoTerminalView = requireNativeView<NativePaseoTerminalViewProps>("PaseoTerminal");
+const CUSTOM_GLYPHS = encodeTerminalCustomGlyphs();
+
+export function PaseoTerminalView({ frame, onCellMetrics, ...props }: PaseoTerminalViewProps) {
+  const nativeFrame = useMemo(() => encodeTerminalFrame(frame), [frame]);
+  const handleCellMetrics = useCallback(
+    (event: { nativeEvent: PaseoTerminalCellMetrics }) => onCellMetrics?.(event.nativeEvent),
+    [onCellMetrics],
+  );
+  return (
+    <NativePaseoTerminalView
+      {...props}
+      frame={nativeFrame}
+      customGlyphs={CUSTOM_GLYPHS}
+      onCellMetrics={handleCellMetrics}
+    />
+  );
+}
diff --git a/packages/app/modules/paseo-terminal/ios/PaseoTerminal.podspec b/packages/app/modules/paseo-terminal/ios/PaseoTerminal.podspec
new file mode 100644
index 0000000000..f15570465f
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/ios/PaseoTerminal.podspec
@@ -0,0 +1,22 @@
+Pod::Spec.new do |s|
+  s.name           = 'PaseoTerminal'
+  s.version        = '0.1.0'
+  s.summary        = 'Native terminal renderer for Paseo'
+  s.description    = 'Shapes and paints terminal frames on the terminal cell grid'
+  s.license        = 'Apache-2.0'
+  s.author         = 'Paseo'
+  s.homepage       = 'https://paseo.sh'
+  s.platforms      = { :ios => '15.1' }
+  s.swift_version  = '5.4'
+  s.source         = { :path => '.' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule'
+  }
+
+  s.source_files = "**/*.{h,m,swift}"
+end
diff --git a/packages/app/modules/paseo-terminal/ios/PaseoTerminalModule.swift b/packages/app/modules/paseo-terminal/ios/PaseoTerminalModule.swift
new file mode 100644
index 0000000000..ec6d7edb0c
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/ios/PaseoTerminalModule.swift
@@ -0,0 +1,21 @@
+import ExpoModulesCore
+
+public class PaseoTerminalModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("PaseoTerminal")
+
+    View(PaseoTerminalView.self) {
+      Events("onCellMetrics")
+
+      Prop("frame") { (view: PaseoTerminalView, frame: TerminalFrameRecord) in view.setFrame(frame) }
+      Prop("theme") { (view: PaseoTerminalView, theme: TerminalThemeRecord) in view.setTheme(theme) }
+      Prop("fontFamily") { (view: PaseoTerminalView, family: String) in view.setFontFamily(family) }
+      Prop("fontSize") { (view: PaseoTerminalView, size: Double) in view.setFontSize(size) }
+      Prop("customGlyphs") { (view: PaseoTerminalView, glyphs: [TerminalCustomGlyphRecord]) in
+        view.setCustomGlyphs(glyphs)
+      }
+
+      OnViewDidUpdateProps { (view: PaseoTerminalView) in view.commit() }
+    }
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/ios/PaseoTerminalView.swift b/packages/app/modules/paseo-terminal/ios/PaseoTerminalView.swift
new file mode 100644
index 0000000000..9739202cad
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/ios/PaseoTerminalView.swift
@@ -0,0 +1,177 @@
+import ExpoModulesCore
+import UIKit
+
+private let minCachedRows = 256
+private let cursorAlpha: CGFloat = 0.45
+
+/// Paints terminal frames on the cell grid. Row shaping is cached by row content, and a frame
+/// repaints only the rows whose layout, selection or cursor changed. A row's glyphs may ink outside
+/// the row, so a repaint covers the old and new row's ink and redraws every row whose ink it meets.
+final class PaseoTerminalView: ExpoView {
+  let onCellMetrics = EventDispatcher()
+
+  private var fontFamily = "Menlo"
+  private var fontSize: CGFloat = 12
+  private var font: TerminalFont?
+  private var customGlyphs = TerminalCustomGlyphs.empty
+  private var frameRecord: TerminalFrameRecord?
+  private var frameChanged = false
+
+  private var rows: [TerminalRowLayout] = []
+  private var columns = 0
+  private var cursor: (row: Int, col: Int)?
+  private var selection: TerminalSelection?
+  private var background = TerminalColor(Double(0xff00_0000))
+  private var cursorColor = TerminalColor(Double(0xffff_ffff))
+  private var rowPaint = TerminalRowPaint(
+    selectionBackground: TerminalColor(Double(0x4726_84ff)))
+  private var rowCache: [String: TerminalRowLayout] = [:]
+
+  required init(appContext: AppContext? = nil) {
+    super.init(appContext: appContext)
+    isOpaque = true
+    contentMode = .redraw
+    isAccessibilityElement = false
+  }
+
+  func setFrame(_ record: TerminalFrameRecord) {
+    frameRecord = record
+    frameChanged = true
+  }
+
+  func setTheme(_ record: TerminalThemeRecord) {
+    background = TerminalColor(record.background)
+    cursorColor = TerminalColor(record.cursor)
+    rowPaint = TerminalRowPaint(
+      selectionBackground: TerminalColor(record.selectionBackground))
+    backgroundColor = UIColor(cgColor: background.cgColor())
+    setNeedsDisplay()
+  }
+
+  func setFontFamily(_ value: String) { fontFamily = value }
+
+  func setFontSize(_ value: Double) { fontSize = CGFloat(value) }
+
+  func setCustomGlyphs(_ records: [TerminalCustomGlyphRecord]) {
+    customGlyphs = TerminalCustomGlyphs(records)
+    rowCache.removeAll()
+    rows = []
+    frameChanged = true
+  }
+
+  /// Applies a batch of prop updates: font first, then the frame laid out with it.
+  func commit() {
+    let displayScale = traitCollection.displayScale > 0 ? traitCollection.displayScale : UIScreen.main.scale
+    if font?.sameAs(family: fontFamily, size: fontSize, displayScale: displayScale) != true {
+      let next = TerminalFont(family: fontFamily, size: fontSize, displayScale: displayScale)
+      font = next
+      rowCache.removeAll()
+      rows = []
+      frameChanged = true
+      onCellMetrics(["cellWidth": next.cellWidth, "cellHeight": next.cellHeight])
+      setNeedsDisplay()
+    }
+    if frameChanged {
+      frameChanged = false
+      layoutFrame()
+    }
+  }
+
+  override func traitCollectionDidChange(_ previous: UITraitCollection?) {
+    super.traitCollectionDidChange(previous)
+    if previous?.displayScale != traitCollection.displayScale { commit() }
+  }
+
+  override func layoutSubviews() {
+    super.layoutSubviews()
+    setNeedsDisplay()
+  }
+
+  private func layoutFrame() {
+    guard let font, let record = frameRecord else { return }
+    let previousRows = rows
+    let previousSelection = selection
+    let previousCursor = cursor
+    let previousColumns = columns
+
+    columns = record.columns
+    cursor = record.cursor.map { ($0.row, $0.col) }
+    selection = record.selection.map(TerminalSelection.init)
+    rows = record.rows.map { encoded in
+      if let cached = rowCache[encoded] { return cached }
+      let layout = TerminalRowLayout(
+        source: TerminalRowSource(encoded: encoded), font: font, customGlyphs: customGlyphs)
+      rowCache[encoded] = layout
+      return layout
+    }
+    trimRowCache(keeping: record.rows)
+    updateAccessibility()
+
+    if previousColumns != columns || previousRows.count != rows.count {
+      setNeedsDisplay()
+      return
+    }
+    for index in rows.indices {
+      let layoutChanged = previousRows[index] !== rows[index]
+      let selectionChanged = previousSelection?.columns(onRow: index) != selection?.columns(onRow: index)
+      let cursorChanged =
+        (previousCursor?.row == index || cursor?.row == index)
+        && (previousCursor?.row != cursor?.row || previousCursor?.col != cursor?.col)
+      if layoutChanged || selectionChanged || cursorChanged {
+        let previous = paintedRect(previousRows[index], at: index, font: font)
+        setNeedsDisplay(previous.union(paintedRect(rows[index], at: index, font: font)))
+      }
+    }
+  }
+
+  /// The area row `index` paints, including glyph ink outside the row.
+  private func paintedRect(_ row: TerminalRowLayout, at index: Int, font: TerminalFont) -> CGRect {
+    let top = CGFloat(index) * font.cellHeight
+    return CGRect(x: 0, y: top + row.inkTop, width: bounds.width, height: row.inkBottom - row.inkTop)
+  }
+
+  private func trimRowCache(keeping currentRows: [String]) {
+    guard rowCache.count > max(minCachedRows, rows.count * 2) else { return }
+    let current = Set(currentRows)
+    rowCache = rowCache.filter { current.contains($0.key) }
+  }
+
+  override func draw(_ rect: CGRect) {
+    guard let context = UIGraphicsGetCurrentContext() else { return }
+    context.setFillColor(background.cgColor())
+    context.fill(rect)
+    guard let font else { return }
+    let gridWidth = CGFloat(columns) * font.cellWidth
+    context.saveGState()
+    context.clip(to: CGRect(x: 0, y: 0, width: min(bounds.width, gridWidth), height: bounds.height))
+    for (index, row) in rows.enumerated() where paintedRect(row, at: index, font: font).intersects(rect) {
+      row.draw(in: context, row: index, top: CGFloat(index) * font.cellHeight, selection: selection, paint: rowPaint)
+    }
+    if let cursor {
+      context.setFillColor(cursorColor.cgColor(alphaScale: cursorAlpha))
+      context.fill(CGRect(
+        x: CGFloat(cursor.col) * font.cellWidth, y: CGFloat(cursor.row) * font.cellHeight,
+        width: font.cellWidth, height: font.cellHeight))
+    }
+    context.restoreGState()
+  }
+
+  /// Exposes each non-blank row as a static text element, `terminal-row-<index>`.
+  private func updateAccessibility() {
+    guard let font else { return }
+    var elements: [UIAccessibilityElement] = []
+    for (index, row) in rows.enumerated() {
+      let label = row.accessibilityText
+      guard !label.isEmpty else { continue }
+      let element = UIAccessibilityElement(accessibilityContainer: self)
+      element.accessibilityIdentifier = "terminal-row-\(index)"
+      element.accessibilityLabel = label
+      element.accessibilityTraits = .staticText
+      element.accessibilityFrameInContainerSpace = CGRect(
+        x: 0, y: CGFloat(index) * font.cellHeight,
+        width: min(bounds.width, CGFloat(columns) * font.cellWidth), height: font.cellHeight)
+      elements.append(element)
+    }
+    accessibilityElements = elements
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/ios/TerminalCustomGlyphs.swift b/packages/app/modules/paseo-terminal/ios/TerminalCustomGlyphs.swift
new file mode 100644
index 0000000000..2442131916
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/ios/TerminalCustomGlyphs.swift
@@ -0,0 +1,73 @@
+import CoreGraphics
+
+/// Box drawing and block elements painted as cell geometry instead of font glyphs, so frames and
+/// blocks join across cells regardless of the font's own metrics.
+final class TerminalCustomGlyph {
+  private let rects: [Double]
+  private let commands: [Double]
+  private let strokeWidth: CGFloat
+
+  init(_ record: TerminalCustomGlyphRecord) {
+    rects = record.rects
+    commands = record.path
+    strokeWidth = CGFloat(record.strokeWidth)
+  }
+
+  func draw(in context: CGContext, rect cell: CGRect, color: CGColor) {
+    context.saveGState()
+    context.setFillColor(color)
+    var index = 0
+    while index + 3 < rects.count {
+      context.fill(CGRect(
+        x: cell.minX + CGFloat(rects[index]) * cell.width,
+        y: cell.minY + CGFloat(rects[index + 1]) * cell.height,
+        width: CGFloat(rects[index + 2]) * cell.width,
+        height: CGFloat(rects[index + 3]) * cell.height))
+      index += 4
+    }
+    if !commands.isEmpty {
+      let point = { (offset: Int) in
+        CGPoint(
+          x: cell.minX + CGFloat(self.commands[offset]) * cell.width,
+          y: cell.minY + CGFloat(self.commands[offset + 1]) * cell.height)
+      }
+      let path = CGMutablePath()
+      index = 0
+      while index < commands.count {
+        switch Int(commands[index]) {
+        case 0:
+          path.move(to: point(index + 1))
+          index += 3
+        case 1:
+          path.addLine(to: point(index + 1))
+          index += 3
+        case 2:
+          path.addQuadCurve(to: point(index + 3), control: point(index + 1))
+          index += 5
+        default:
+          index = commands.count
+        }
+      }
+      context.setStrokeColor(color)
+      context.setLineWidth(strokeWidth)
+      context.setLineCap(.butt)
+      context.setLineJoin(.miter)
+      context.addPath(path)
+      context.strokePath()
+    }
+    context.restoreGState()
+  }
+}
+
+final class TerminalCustomGlyphs {
+  static let empty = TerminalCustomGlyphs([])
+  private let glyphs: [String: TerminalCustomGlyph]
+
+  init(_ records: [TerminalCustomGlyphRecord]) {
+    var glyphs: [String: TerminalCustomGlyph] = [:]
+    for record in records { glyphs[record.char] = TerminalCustomGlyph(record) }
+    self.glyphs = glyphs
+  }
+
+  subscript(text: String) -> TerminalCustomGlyph? { glyphs[text] }
+}
diff --git a/packages/app/modules/paseo-terminal/ios/TerminalFont.swift b/packages/app/modules/paseo-terminal/ios/TerminalFont.swift
new file mode 100644
index 0000000000..d2f52a78da
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/ios/TerminalFont.swift
@@ -0,0 +1,67 @@
+import CoreText
+import UIKit
+
+private let measureText = "mmmmmmmmmm"
+
+/// The terminal font at one size: a CTFont per face (regular, bold, italic, bold italic) and the
+/// cell those faces are laid out on. Cells are whole device pixels so every column origin is
+/// exact. CoreText's cascade list covers characters the family lacks.
+final class TerminalFont {
+  let family: String
+  let size: CGFloat
+  let displayScale: CGFloat
+  private let faces: [CTFont]
+
+  /// Cell size and baseline in points, each a whole number of device pixels.
+  let cellWidth: CGFloat
+  let cellHeight: CGFloat
+  let baseline: CGFloat
+  let underlineOffset: CGFloat
+  let underlineThickness: CGFloat
+  let strikeOffset: CGFloat
+  let strikeThickness: CGFloat
+
+  init(family: String, size: CGFloat, displayScale: CGFloat) {
+    self.family = family
+    self.size = size
+    self.displayScale = displayScale
+    let regular = TerminalFont.makeFont(family: family, size: size, traits: [])
+    faces = [
+      regular,
+      TerminalFont.makeFont(family: family, size: size, traits: .traitBold),
+      TerminalFont.makeFont(family: family, size: size, traits: .traitItalic),
+      TerminalFont.makeFont(family: family, size: size, traits: [.traitBold, .traitItalic]),
+    ]
+
+    let pixel = { (value: CGFloat) in max(1, (value * displayScale).rounded()) / displayScale }
+    let line = CTLineCreateWithAttributedString(
+      NSAttributedString(string: measureText, attributes: [.font: regular]))
+    let width = CGFloat(CTLineGetTypographicBounds(line, nil, nil, nil))
+    cellWidth = pixel(width / CGFloat(measureText.count))
+    let ascent = CTFontGetAscent(regular)
+    let descent = CTFontGetDescent(regular)
+    let leading = CTFontGetLeading(regular)
+    cellHeight = pixel(ascent + descent + leading)
+    baseline = pixel(ascent)
+    underlineOffset = -CTFontGetUnderlinePosition(regular)
+    underlineThickness = max(1 / displayScale, CTFontGetUnderlineThickness(regular))
+    strikeOffset = -CTFontGetXHeight(regular) / 2
+    strikeThickness = underlineThickness
+  }
+
+  func font(flags: Int) -> CTFont { faces[TerminalFont.face(flags: flags)] }
+
+  func sameAs(family: String, size: CGFloat, displayScale: CGFloat) -> Bool {
+    self.family == family && self.size == size && self.displayScale == displayScale
+  }
+
+  static func face(flags: Int) -> Int {
+    (flags & TerminalStyleFlags.bold != 0 ? 1 : 0) + (flags & TerminalStyleFlags.italic != 0 ? 2 : 0)
+  }
+
+  private static func makeFont(family: String, size: CGFloat, traits: UIFontDescriptor.SymbolicTraits) -> CTFont {
+    let base = UIFontDescriptor(fontAttributes: [.family: family])
+    let descriptor = traits.isEmpty ? base : (base.withSymbolicTraits(traits) ?? base)
+    return UIFont(descriptor: descriptor, size: size) as CTFont
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/ios/TerminalFrame.swift b/packages/app/modules/paseo-terminal/ios/TerminalFrame.swift
new file mode 100644
index 0000000000..2cba97fd61
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/ios/TerminalFrame.swift
@@ -0,0 +1,121 @@
+import CoreGraphics
+import ExpoModulesCore
+
+struct TerminalCursorRecord: Record {
+  @Field var row: Int = 0
+  @Field var col: Int = 0
+}
+
+struct TerminalSelectionRecord: Record {
+  @Field var startRow: Int = 0
+  @Field var startCol: Int = 0
+  @Field var endRow: Int = 0
+  @Field var endCol: Int = 0
+}
+
+struct TerminalFrameRecord: Record {
+  @Field var columns: Int = 0
+  /// Encoded rows, `cells;styles;text`; see `frame-encoding.ts`.
+  @Field var rows: [String] = []
+  @Field var cursor: TerminalCursorRecord? = nil
+  @Field var selection: TerminalSelectionRecord? = nil
+}
+
+struct TerminalThemeRecord: Record {
+  @Field var background: Double = 0
+  @Field var cursor: Double = 0
+  @Field var selectionBackground: Double = 0
+}
+
+struct TerminalCustomGlyphRecord: Record {
+  @Field var char: String = ""
+  @Field var rects: [Double] = []
+  @Field var path: [Double] = []
+  @Field var strokeWidth: Double = 0
+}
+
+enum TerminalStyleFlags {
+  static let bold = 1
+  static let italic = 2
+  static let underline = 4
+  static let strikethrough = 8
+}
+
+/// JS sends colors as unsigned ARGB numbers.
+struct TerminalColor: Equatable {
+  let argb: UInt32
+
+  init(_ value: Double) {
+    argb = UInt32(truncatingIfNeeded: Int64(value))
+  }
+
+  var isPainted: Bool { argb >> 24 != 0 }
+
+  func cgColor(alphaScale: CGFloat = 1) -> CGColor {
+    let channel = { (shift: UInt32) in CGFloat((argb >> shift) & 0xff) / 255 }
+    return CGColor(srgbRed: channel(16), green: channel(8), blue: channel(0), alpha: channel(24) * alphaScale)
+  }
+}
+
+/// One row as the caller described it: cell text, column spans and style spans.
+struct TerminalRowSource {
+  let text: String
+  let cells: [Int]
+  let styles: [Double]
+
+  /// Decodes `cells;styles;text`, where both number lists are comma separated.
+  init(encoded: String) {
+    let utf8 = encoded.utf8
+    let separator = UInt8(ascii: ";")
+    let cellsEnd = utf8.firstIndex(of: separator) ?? utf8.endIndex
+    let stylesStart = cellsEnd == utf8.endIndex ? cellsEnd : utf8.index(after: cellsEnd)
+    let stylesEnd = utf8[stylesStart...].firstIndex(of: separator) ?? utf8.endIndex
+    let textStart = stylesEnd == utf8.endIndex ? stylesEnd : utf8.index(after: stylesEnd)
+    cells = TerminalRowSource.parseNumbers(utf8[utf8.startIndex..<cellsEnd]).map { Int($0) }
+    styles = TerminalRowSource.parseNumbers(utf8[stylesStart..<stylesEnd]).map { Double($0) }
+    text = String(encoded[textStart...])
+  }
+
+  private static func parseNumbers(_ bytes: Substring.UTF8View) -> [Int64] {
+    guard !bytes.isEmpty else { return [] }
+    var numbers: [Int64] = [0]
+    for byte in bytes {
+      if byte == UInt8(ascii: ",") {
+        numbers.append(0)
+      } else {
+        numbers[numbers.count - 1] = numbers[numbers.count - 1] * 10 + Int64(byte - UInt8(ascii: "0"))
+      }
+    }
+    return numbers
+  }
+}
+
+struct TerminalSelection: Equatable {
+  let startRow: Int
+  let startCol: Int
+  let endRow: Int
+  let endCol: Int
+
+  init(_ record: TerminalSelectionRecord) {
+    startRow = record.startRow
+    startCol = record.startCol
+    endRow = record.endRow
+    endCol = record.endCol
+  }
+
+  func intersects(row: Int) -> Bool { row >= startRow && row <= endRow }
+
+  /// A cell is selected when any column it covers is inside the inclusive range.
+  func contains(row: Int, col: Int, span: Int) -> Bool {
+    guard intersects(row: row) else { return false }
+    let firstCol = row == startRow ? startCol : 0
+    let lastCol = row == endRow ? endCol : Int.max
+    return col + span - 1 >= firstCol && col <= lastCol
+  }
+
+  /// The part of the selection on one row, so a row only repaints when its own part changes.
+  func columns(onRow row: Int) -> ClosedRange<Int>? {
+    guard intersects(row: row) else { return nil }
+    return (row == startRow ? startCol : 0)...(row == endRow ? endCol : Int.max)
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/ios/TerminalRowLayout.swift b/packages/app/modules/paseo-terminal/ios/TerminalRowLayout.swift
new file mode 100644
index 0000000000..83d731f1e3
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/ios/TerminalRowLayout.swift
@@ -0,0 +1,336 @@
+import CoreText
+import UIKit
+
+/// Shaped glyphs may exceed their slot by this many points before they are scaled down.
+private let overflowTolerance: CGFloat = 0.5
+/// Stands in for an open edge when a group is clipped on one side only.
+private let clipUnbounded: CGFloat = 100_000
+
+/// Lays text out left to right in logical order. The override fixes every character's direction;
+/// the base direction also covers trailing spaces, which bidi rule L1 otherwise moves to the
+/// direction detected from the first strong character, ahead of an Arabic or Hebrew row.
+private let leftToRightAttributes: [NSAttributedString.Key: Any] = {
+  var base = CTWritingDirection.leftToRight
+  let paragraph = withUnsafeBytes(of: &base) { bytes in
+    CTParagraphStyleCreate(
+      [CTParagraphStyleSetting(
+        spec: .baseWritingDirection, valueSize: MemoryLayout<CTWritingDirection>.size, value: bytes.baseAddress!)],
+      1)
+  }
+  let overrideLeftToRight = CTWritingDirection.leftToRight.rawValue | 2  // kCTWritingDirectionOverride
+  return [
+    NSAttributedString.Key(kCTWritingDirectionAttributeName as String): [NSNumber(value: overrideLeftToRight)],
+    NSAttributedString.Key(kCTParagraphStyleAttributeName as String): paragraph,
+  ]
+}()
+
+/// Colors a row is painted with besides its own styles.
+struct TerminalRowPaint {
+  let selectionBackground: TerminalColor
+}
+
+/// One row shaped once and placed on the terminal grid.
+///
+/// Each run of cells with the same font face is shaped as a whole line, in logical order and left
+/// to right like the terminal grid, so contextual forms, ligatures, marks and fallback fonts see
+/// their neighbours. CoreText reports which UTF-16 offset produced each glyph. Cells whose units
+/// produced no advancing glyph, and cells a reordered glyph crosses, join the cluster of the cell
+/// before them: a ligature, conjunct, emoji sequence or reordered mark that spans columns. Each
+/// group is drawn at its first cell's column with the glyph offsets CoreText produced, centred in
+/// the columns it owns and scaled down only when wider than them. Colors never split groups.
+final class TerminalRowLayout {
+  let source: TerminalRowSource
+  private let font: TerminalFont
+  private let units: [UInt16]
+  private let cellCount: Int
+  private var cellCol: [Int]
+  private var cellSpan: [Int]
+  private var cellStart: [Int]
+  private var cellEnd: [Int]
+  private var cellForeground: [TerminalColor]
+  private var cellBackground: [TerminalColor]
+  private var cellFlags: [Int]
+  private var cellGlyph: [TerminalCustomGlyph?]
+  private var groups: [Group] = []
+  /// The row's painted extent, relative to its top edge. Marks stacked above or below a
+  /// letter and some fallback glyphs ink outside the row; the view repaints that area with it.
+  private(set) var inkTop: CGFloat = 0
+  private(set) var inkBottom: CGFloat
+
+  private struct GlyphRun {
+    let font: CTFont
+    var glyphs: [CGGlyph]
+    /// Relative to the group's pen origin, y up from the baseline.
+    var positions: [CGPoint]
+  }
+
+  private struct Group {
+    let firstCell: Int
+    let lastCell: Int
+    let col: Int
+    let offset: CGFloat
+    let scale: CGFloat
+    let runs: [GlyphRun]
+  }
+
+  private struct ShapedGlyph {
+    let font: CTFont
+    let glyph: CGGlyph
+    let position: CGPoint
+    let advance: CGFloat
+    let cell: Int
+  }
+
+  init(source: TerminalRowSource, font: TerminalFont, customGlyphs: TerminalCustomGlyphs) {
+    self.source = source
+    self.font = font
+    units = Array(source.text.utf16)
+    cellCount = source.cells.count / 2
+    cellCol = Array(repeating: 0, count: cellCount)
+    cellSpan = Array(repeating: 1, count: cellCount)
+    cellStart = Array(repeating: 0, count: cellCount)
+    cellEnd = Array(repeating: 0, count: cellCount)
+    cellForeground = Array(repeating: TerminalColor(0), count: cellCount)
+    cellBackground = Array(repeating: TerminalColor(0), count: cellCount)
+    cellFlags = Array(repeating: 0, count: cellCount)
+    cellGlyph = Array(repeating: nil, count: cellCount)
+    inkBottom = font.cellHeight
+    readCells(customGlyphs: customGlyphs)
+    shapeRuns()
+  }
+
+  var accessibilityText: String {
+    var text = source.text
+    while text.last == " " { text.removeLast() }
+    return text
+  }
+
+  private func readCells(customGlyphs: TerminalCustomGlyphs) {
+    var offset = 0
+    var col = 0
+    var styleIndex = 0
+    var styleEndCol = 0
+    for cell in 0..<cellCount {
+      let length = source.cells[cell * 2]
+      let span = max(1, source.cells[cell * 2 + 1])
+      while col >= styleEndCol && styleIndex + 3 < source.styles.count {
+        styleEndCol += Int(source.styles[styleIndex])
+        styleIndex += 4
+      }
+      let style = styleIndex - 4
+      if style >= 0 {
+        cellForeground[cell] = TerminalColor(source.styles[style + 1])
+        cellBackground[cell] = TerminalColor(source.styles[style + 2])
+        cellFlags[cell] = Int(source.styles[style + 3])
+      }
+      cellCol[cell] = col
+      cellSpan[cell] = span
+      cellStart[cell] = offset
+      cellEnd[cell] = min(units.count, offset + length)
+      cellGlyph[cell] = customGlyphs[text(from: cellStart[cell], to: cellEnd[cell])]
+      offset = cellEnd[cell]
+      col += span
+    }
+  }
+
+  private func text(from start: Int, to end: Int) -> String {
+    String(utf16CodeUnits: Array(units[start..<end]), count: end - start)
+  }
+
+  private func shapesWith(_ cell: Int, _ other: Int) -> Bool {
+    cellGlyph[cell] == nil && cellGlyph[other] == nil
+      && TerminalFont.face(flags: cellFlags[cell]) == TerminalFont.face(flags: cellFlags[other])
+  }
+
+  private func shapeRuns() {
+    var cell = 0
+    while cell < cellCount {
+      if cellGlyph[cell] != nil {
+        cell += 1
+        continue
+      }
+      var last = cell
+      while last + 1 < cellCount && shapesWith(cell, last + 1) { last += 1 }
+      shapeRun(first: cell, last: last)
+      cell = last + 1
+    }
+  }
+
+  private func shapeRun(first: Int, last: Int) {
+    let start = cellStart[first]
+    let end = cellEnd[last]
+    guard end > start else { return }
+    var cellOfUnit = Array(repeating: first, count: end - start)
+    for cell in first...last where cellEnd[cell] > cellStart[cell] {
+      for unit in cellStart[cell]..<cellEnd[cell] { cellOfUnit[unit - start] = cell }
+    }
+
+    var attributes = leftToRightAttributes
+    attributes[NSAttributedString.Key(kCTFontAttributeName as String)] = font.font(flags: cellFlags[first])
+    let line = CTLineCreateWithAttributedString(
+      NSAttributedString(string: text(from: start, to: end), attributes: attributes))
+
+    var shaped: [ShapedGlyph] = []
+    for run in CTLineGetGlyphRuns(line) as? [CTRun] ?? [] {
+      let count = CTRunGetGlyphCount(run)
+      guard count > 0 else { continue }
+      let runAttributes = CTRunGetAttributes(run) as NSDictionary
+      let runFont = runAttributes[kCTFontAttributeName as String].map { $0 as! CTFont }
+        ?? font.font(flags: cellFlags[first])
+      var glyphs = Array(repeating: CGGlyph(0), count: count)
+      var positions = Array(repeating: CGPoint.zero, count: count)
+      var advances = Array(repeating: CGSize.zero, count: count)
+      var indices = Array(repeating: CFIndex(0), count: count)
+      let all = CFRange(location: 0, length: 0)
+      CTRunGetGlyphs(run, all, &glyphs)
+      CTRunGetPositions(run, all, &positions)
+      CTRunGetAdvances(run, all, &advances)
+      CTRunGetStringIndices(run, all, &indices)
+      for index in 0..<count {
+        let unit = min(max(0, indices[index]), cellOfUnit.count - 1)
+        shaped.append(ShapedGlyph(
+          font: runFont, glyph: glyphs[index], position: positions[index],
+          advance: advances[index].width, cell: cellOfUnit[unit]))
+      }
+    }
+
+    // A cell starts a cluster unless a reordered glyph crosses into it or it has no advance.
+    var startsCluster = Array(repeating: true, count: last - first + 1)
+    var advance = Array(repeating: CGFloat(0), count: last - first + 1)
+    var furthestCell = first
+    for glyph in shaped {
+      advance[glyph.cell - first] += glyph.advance
+      if glyph.cell < furthestCell {
+        for cell in (glyph.cell + 1)...furthestCell { startsCluster[cell - first] = false }
+      } else {
+        furthestCell = glyph.cell
+      }
+    }
+    if last > first {
+      for cell in (first + 1)...last where advance[cell - first] == 0 {
+        startsCluster[cell - first] = false
+      }
+    }
+
+    var groupFirst = first
+    for cell in first...last {
+      let closesGroup = cell == last || startsCluster[cell + 1 - first]
+      guard closesGroup else { continue }
+      addGroup(first: groupFirst, last: cell, glyphs: shaped.filter { $0.cell >= groupFirst && $0.cell <= cell })
+      groupFirst = cell + 1
+    }
+  }
+
+  private func addGroup(first: Int, last: Int, glyphs: [ShapedGlyph]) {
+    let isBlank = (cellStart[first]..<cellEnd[last]).allSatisfy { units[$0] == 0x20 }
+    guard let origin = glyphs.first?.position.x, !isBlank else { return }
+    let columns = (first...last).reduce(0) { $0 + cellSpan[$1] }
+    let slot = CGFloat(columns) * font.cellWidth
+    let advance = glyphs.reduce(CGFloat(0)) { $0 + $1.advance }
+    let scale = advance > slot + overflowTolerance ? slot / advance : 1
+    let offset = scale < 1 ? 0 : (slot - advance) / 2
+    var runs: [GlyphRun] = []
+    for glyph in glyphs {
+      let position = CGPoint(x: glyph.position.x - origin, y: glyph.position.y)
+      if let lastRun = runs.last, CFEqual(lastRun.font, glyph.font) {
+        runs[runs.count - 1].glyphs.append(glyph.glyph)
+        runs[runs.count - 1].positions.append(position)
+      } else {
+        runs.append(GlyphRun(font: glyph.font, glyphs: [glyph.glyph], positions: [position]))
+      }
+    }
+    groups.append(Group(
+      firstCell: first, lastCell: last, col: cellCol[first], offset: offset, scale: scale, runs: runs))
+    extendInk(runs: runs, scale: scale)
+  }
+
+  /// Grows the row's ink extent to cover the glyphs as `draw` places them, padded by a device pixel
+  /// for antialiasing.
+  private func extendInk(runs: [GlyphRun], scale: CGFloat) {
+    let centerY = font.cellHeight / 2
+    let baselineInTextSpace = font.cellHeight / 2 - font.baseline
+    let pixel = 1 / font.displayScale
+    for run in runs {
+      var bounds = Array(repeating: CGRect.zero, count: run.glyphs.count)
+      CTFontGetBoundingRectsForGlyphs(run.font, .horizontal, run.glyphs, &bounds, run.glyphs.count)
+      for (glyph, position) in zip(bounds, run.positions) where !glyph.isEmpty {
+        let top = centerY - (position.y + baselineInTextSpace + glyph.maxY) * scale - pixel
+        let bottom = centerY - (position.y + baselineInTextSpace + glyph.minY) * scale + pixel
+        inkTop = min(inkTop, (top * font.displayScale).rounded(.down) / font.displayScale)
+        inkBottom = max(inkBottom, (bottom * font.displayScale).rounded(.up) / font.displayScale)
+      }
+    }
+  }
+
+  private func isSelected(_ cell: Int, row: Int, selection: TerminalSelection?) -> Bool {
+    selection?.contains(row: row, col: cellCol[cell], span: cellSpan[cell]) ?? false
+  }
+
+  /// Draws cell backgrounds, the selection overlay, then text with its original colors.
+  func draw(in context: CGContext, row: Int, top: CGFloat, selection: TerminalSelection?, paint: TerminalRowPaint) {
+    let cellWidth = font.cellWidth
+    let cellHeight = font.cellHeight
+    for cell in 0..<cellCount {
+      let rect = CGRect(x: CGFloat(cellCol[cell]) * cellWidth, y: top, width: CGFloat(cellSpan[cell]) * cellWidth, height: cellHeight)
+      let background = cellBackground[cell]
+      if background.isPainted {
+        context.setFillColor(background.cgColor())
+        context.fill(rect)
+      }
+      if isSelected(cell, row: row, selection: selection) {
+        context.setFillColor(paint.selectionBackground.cgColor())
+        context.fill(rect)
+      }
+    }
+
+    let centerY = top + cellHeight / 2
+    let baselineInTextSpace = cellHeight / 2 - font.baseline
+    // A group whose cells differ in color is drawn once per color, clipped to those
+    // cells' columns. Only edges between differently colored cells clip; outer edges may overhang.
+    for group in groups {
+      var first = group.firstCell
+      while first <= group.lastCell {
+        let color = cellForeground[first]
+        var last = first
+        while last < group.lastCell && cellForeground[last + 1] == color {
+          last += 1
+        }
+        context.saveGState()
+        if first > group.firstCell || last < group.lastCell {
+          let left = first > group.firstCell ? CGFloat(cellCol[first]) * cellWidth : -clipUnbounded
+          let right = last < group.lastCell ? CGFloat(cellCol[last] + cellSpan[last]) * cellWidth : clipUnbounded
+          context.clip(to: CGRect(x: left, y: -clipUnbounded, width: right - left, height: 2 * clipUnbounded))
+        }
+        context.setFillColor(color.cgColor())
+        context.translateBy(x: CGFloat(group.col) * cellWidth + group.offset, y: centerY)
+        context.scaleBy(x: group.scale, y: -group.scale)
+        context.textMatrix = .identity
+        for run in group.runs {
+          let positions = run.positions.map { CGPoint(x: $0.x, y: $0.y + baselineInTextSpace) }
+          CTFontDrawGlyphs(run.font, run.glyphs, positions, run.glyphs.count, context)
+        }
+        context.restoreGState()
+        first = last + 1
+      }
+    }
+
+    let baseline = top + font.baseline
+    for cell in 0..<cellCount {
+      let color = cellForeground[cell]
+      let left = CGFloat(cellCol[cell]) * cellWidth
+      let width = CGFloat(cellSpan[cell]) * cellWidth
+      if let glyph = cellGlyph[cell] {
+        glyph.draw(in: context, rect: CGRect(x: left, y: top, width: width, height: cellHeight), color: color.cgColor())
+      }
+      let flags = cellFlags[cell]
+      if flags & (TerminalStyleFlags.underline | TerminalStyleFlags.strikethrough) == 0 { continue }
+      context.setFillColor(color.cgColor())
+      if flags & TerminalStyleFlags.underline != 0 {
+        context.fill(CGRect(x: left, y: baseline + font.underlineOffset, width: width, height: font.underlineThickness))
+      }
+      if flags & TerminalStyleFlags.strikethrough != 0 {
+        context.fill(CGRect(x: left, y: baseline + font.strikeOffset, width: width, height: font.strikeThickness))
+      }
+    }
+  }
+}
diff --git a/packages/app/modules/paseo-terminal/package.json b/packages/app/modules/paseo-terminal/package.json
new file mode 100644
index 0000000000..9cfb922d65
--- /dev/null
+++ b/packages/app/modules/paseo-terminal/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "paseo-terminal",
+  "version": "0.1.0",
+  "private": true
+}
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..3ac90cf2b5
--- /dev/null
+++ b/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift
@@ -0,0 +1,124 @@
+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 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
+    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 }
+      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 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)
+    }
+    let payload: [String: Any] = [
+      "bounds": rect(bounds),
+      "verticalBarEdge": barEdge,
+      "verticalBar": barPayload,
+      "bottomClearance": bottomClearance,
+      "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 3eddd9b53f..9c2698885b 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/app",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "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.212",
-    "@xterm/xterm": "^6.1.0-beta.213",
+    "@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",
@@ -154,7 +156,8 @@
     "@types/ws": "^8.18.1",
     "@vitest/browser": "^4.1.7",
     "@vitest/browser-playwright": "^4.1.7",
-    "@xterm/headless": "^6.1.0-beta.213",
+    "@xterm/addon-serialize": "0.14.0",
+    "@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 54%
rename from packages/app/src/hooks/agent-commands-query.ts
rename to packages/app/src/agent-commands/cache/index.ts
index 276c0fd9ba..474491f297 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;
@@ -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;
 }
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/icons.ts b/packages/app/src/agent-controls/icons.ts
index 06b2759071..8effc9831d 100644
--- a/packages/app/src/agent-controls/icons.ts
+++ b/packages/app/src/agent-controls/icons.ts
@@ -18,6 +18,7 @@ import { getModeVisuals, type AgentProviderDefinition } from "@getpaseo/protocol
 export interface AgentControlIconProps {
   size: number;
   color: string;
+  strokeWidth?: number;
 }
 
 export type AgentControlIcon = ComponentType<AgentControlIconProps>;
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/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..53e1dede80 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
@@ -6,7 +6,7 @@ import type { AgentFeature } from "@getpaseo/protocol/agent-types";
 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 +14,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 {
@@ -133,7 +132,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],
@@ -410,7 +409,7 @@ function AgentProfileFeatureRow({
   feature: AgentFeature;
   isFirst: boolean;
   disabled: boolean;
-  size: FieldControlSize;
+  size: ControlSize;
   model: AgentProfileFormModel;
 }): ReactElement {
   const rowStyle = useMemo(
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 890f6eaae7..1ca917f0b3 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.tsx b/packages/app/src/agent-stream/disclosure.tsx
new file mode 100644
index 0000000000..b35e67e567
--- /dev/null
+++ b/packages/app/src/agent-stream/disclosure.tsx
@@ -0,0 +1,40 @@
+import { createContext, useContext, useMemo, type ReactNode, type RefObject } from "react";
+import type { StreamViewportHandle } from "./strategy";
+
+/**
+ * Runs a disclosure's state change. Inside a timeline row, the row that owns the
+ * trigger keeps its screen position through the change; elsewhere `apply` runs as is.
+ */
+export type DisclosureHold = (apply: () => void) => 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) => {
+      const viewport = viewportRef.current;
+      if (viewport) {
+        viewport.holdRow(rowId, apply);
+      } 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 5fa3535bce..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" }> {
@@ -71,7 +52,7 @@ function layoutFor(input: { platform: "web" | "native"; isTurnActive: boolean })
       isTurnActive: input.isTurnActive,
       history: strategy.orderTail([userMessage("user"), assistant]),
       liveHead: [],
-      timingByAssistantId: timingFor(assistant.id),
+      timingByItemId: timingFor(assistant.id),
     }),
   };
 }
diff --git a/packages/app/src/agent-stream/history-window.ts b/packages/app/src/agent-stream/history-window.ts
index 347f780023..43cca2bbbf 100644
--- a/packages/app/src/agent-stream/history-window.ts
+++ b/packages/app/src/agent-stream/history-window.ts
@@ -1,4 +1,5 @@
 import type { StreamItem } from "@/types/stream";
+import { continuesTurn } from "./turn-membership";
 
 export const DEFAULT_MOUNTED_RECENT_STREAM_ITEMS = 20;
 
@@ -32,7 +33,7 @@ export function findMountedWindowStart(input: {
   }
 
   let startIndex = Math.max(items.length - minMountedCount, 0);
-  while (startIndex > 0 && items[startIndex]?.kind !== "user_message") {
+  while (startIndex > 0 && continuesTurn(items[startIndex - 1], items[startIndex])) {
     startIndex -= 1;
   }
   return startIndex;
diff --git a/packages/app/src/agent-stream/layout.test.ts b/packages/app/src/agent-stream/layout.test.ts
index f10fde2cb1..fde9a3a342 100644
--- a/packages/app/src/agent-stream/layout.test.ts
+++ b/packages/app/src/agent-stream/layout.test.ts
@@ -104,7 +104,7 @@ function layoutFor(input: {
       strategy,
       streamHead: input.head ?? [],
     }),
-    timingByAssistantId: timingFor(...(input.timingIds ?? [])),
+    timingByItemId: timingFor(...(input.timingIds ?? [])),
   });
 }
 
@@ -148,7 +148,7 @@ function findLayoutItem(layout: StreamLayout, id: string): StreamLayoutItem {
 }
 
 describe("layoutStream", () => {
-  it("places one response footer after an adjacent tagged tool-only turn", () => {
+  it("keeps separate footers for an assistant turn and an adjacent tool-only turn", () => {
     const priorAssistant = assistantMessage("prior", 1, undefined, "turn-1");
     const nextTool = toolCall("next-tool", 2, "turn-2");
     const layout = layoutFor({
@@ -157,8 +157,8 @@ describe("layoutStream", () => {
       timingIds: [priorAssistant.id],
     });
 
-    expect(layout.auxiliaryTurnFooter?.itemId).toBe(priorAssistant.id);
-    expect(footerOwners(layout)).toEqual([priorAssistant.id]);
+    expect(layout.auxiliaryTurnFooter?.itemId).toBe(nextTool.id);
+    expect(footerOwners(layout)).toEqual([priorAssistant.id, nextTool.id]);
   });
 
   it("recomputes cached history layout when only the live boundary turn changes", () => {
@@ -171,7 +171,7 @@ describe("layoutStream", () => {
       isTurnActive: true,
       history,
       liveHead,
-      timingByAssistantId: timingFor(priorAssistant.id),
+      timingByItemId: timingFor(priorAssistant.id),
     });
 
     liveHead[0] = { ...liveHead[0]!, turnId: "turn-2" };
@@ -180,7 +180,7 @@ describe("layoutStream", () => {
       isTurnActive: true,
       history,
       liveHead,
-      timingByAssistantId: timingFor(priorAssistant.id),
+      timingByItemId: timingFor(priorAssistant.id),
     });
 
     expect(footerOwners(first)).toEqual([]);
@@ -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/layout.ts b/packages/app/src/agent-stream/layout.ts
index 82ef98db54..924d9d75ec 100644
--- a/packages/app/src/agent-stream/layout.ts
+++ b/packages/app/src/agent-stream/layout.ts
@@ -39,13 +39,13 @@ export interface StreamLayoutInput {
   isTurnActive: boolean;
   history: StreamItem[];
   liveHead: StreamItem[];
-  timingByAssistantId: Map<string, TurnTiming>;
+  timingByItemId: Map<string, TurnTiming>;
 }
 
 interface LayoutSegmentInput {
   strategy: StreamStrategy;
   items: StreamItem[];
-  timingByAssistantId: Map<string, TurnTiming>;
+  timingByItemId: Map<string, TurnTiming>;
   auxiliaryTurnFooter: TurnFooterHost | null;
   hasAuxiliaryFooter: boolean;
   frameOrder: StreamFrameChildOrder;
@@ -57,8 +57,8 @@ interface LayoutSegmentInput {
   phase: "streaming" | "complete";
 }
 
-interface AssistantFooterSource {
-  item: Extract<StreamItem, { kind: "assistant_message" }>;
+interface TurnFooterSource {
+  item: StreamItem;
   items: StreamItem[];
   index: number;
 }
@@ -67,23 +67,26 @@ function createTurnFooterHost(input: {
   item: StreamItem;
   items: StreamItem[];
   index: number;
-  timingByAssistantId: Map<string, TurnTiming>;
+  timingByItemId: Map<string, TurnTiming>;
 }): TurnFooterHost {
   return {
     itemId: input.item.id,
     items: input.items,
-    timing: input.timingByAssistantId.get(input.item.id),
+    timing: input.timingByItemId.get(input.item.id),
     startIndex: input.index,
   };
 }
 
-function findLatestAssistantInResponse(input: {
+function findTurnFooterSource(input: {
   strategy: StreamStrategy;
   items: StreamItem[];
   startIndex: number;
   boundaryAboveItems?: StreamItem[] | null;
   boundaryAboveIndex?: number | null;
-}): AssistantFooterSource | null {
+}): TurnFooterSource | null {
+  const last = input.items[input.startIndex];
+  const toolFallback: TurnFooterSource | null =
+    last?.kind === "tool_call" ? { item: last, items: input.items, index: input.startIndex } : null;
   let items = input.items;
   let index = input.startIndex;
   let canCrossBoundary = true;
@@ -97,7 +100,7 @@ function findLatestAssistantInResponse(input: {
     ) {
       const item = items[index];
       if (!item || (laterItem && !continuesResponse(item, laterItem))) {
-        return null;
+        return toolFallback;
       }
       if (item.kind === "assistant_message") {
         return { item, items, index };
@@ -111,7 +114,7 @@ function findLatestAssistantInResponse(input: {
       input.boundaryAboveIndex === null ||
       input.boundaryAboveIndex === undefined
     ) {
-      return null;
+      return toolFallback;
     }
 
     items = input.boundaryAboveItems;
@@ -131,20 +134,20 @@ function resolveAuxiliaryTurnFooter(input: StreamLayoutInput): TurnFooterHost |
     return null;
   }
 
-  const assistant = findLatestAssistantInResponse({
+  const source = findTurnFooterSource({
     strategy: input.strategy,
     items: footerItems,
     startIndex: latestIndex,
   });
-  if (!assistant) {
+  if (!source) {
     return null;
   }
 
   return createTurnFooterHost({
-    item: assistant.item,
-    items: assistant.items,
-    index: assistant.index,
-    timingByAssistantId: input.timingByAssistantId,
+    item: source.item,
+    items: source.items,
+    index: source.index,
+    timingByItemId: input.timingByItemId,
   });
 }
 
@@ -154,7 +157,7 @@ function resolveCompletedFooter(input: {
   index: number;
   item: StreamItem;
   belowItem: StreamItem | null;
-  timingByAssistantId: Map<string, TurnTiming>;
+  timingByItemId: Map<string, TurnTiming>;
   auxiliaryTurnFooter: TurnFooterHost | null;
   boundaryAboveItems: StreamItem[] | null;
   boundaryAboveIndex: number | null;
@@ -163,21 +166,21 @@ function resolveCompletedFooter(input: {
     return null;
   }
 
-  const assistant = findLatestAssistantInResponse({
+  const source = findTurnFooterSource({
     strategy: input.strategy,
     items: input.items,
     startIndex: input.index,
     boundaryAboveItems: input.boundaryAboveItems,
     boundaryAboveIndex: input.boundaryAboveIndex,
   });
-  if (!assistant || input.auxiliaryTurnFooter?.itemId === assistant.item.id) {
+  if (!source || input.auxiliaryTurnFooter?.itemId === source.item.id) {
     return null;
   }
   return createTurnFooterHost({
-    item: assistant.item,
-    items: assistant.items,
-    index: assistant.index,
-    timingByAssistantId: input.timingByAssistantId,
+    item: source.item,
+    items: source.items,
+    index: source.index,
+    timingByItemId: input.timingByItemId,
   });
 }
 
@@ -306,7 +309,7 @@ function layoutSegmentItem(
     index,
     item,
     belowItem,
-    timingByAssistantId: input.timingByAssistantId,
+    timingByItemId: input.timingByItemId,
     auxiliaryTurnFooter: input.auxiliaryTurnFooter,
     boundaryAboveItems: input.boundaryAboveItems,
     boundaryAboveIndex: input.boundaryAboveIndex,
@@ -375,7 +378,7 @@ export function layoutStream(input: StreamLayoutInput): StreamLayout {
       history = layoutSegment({
         strategy: input.strategy,
         items: input.history,
-        timingByAssistantId: input.timingByAssistantId,
+        timingByItemId: input.timingByItemId,
         auxiliaryTurnFooter,
         hasAuxiliaryFooter,
         frameOrder,
@@ -395,7 +398,7 @@ export function layoutStream(input: StreamLayoutInput): StreamLayout {
   const liveHead = layoutSegment({
     strategy: input.strategy,
     items: input.liveHead,
-    timingByAssistantId: input.timingByAssistantId,
+    timingByItemId: input.timingByItemId,
     auxiliaryTurnFooter,
     hasAuxiliaryFooter,
     frameOrder,
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..a16763f467
--- /dev/null
+++ b/packages/app/src/agent-stream/legend-list-held-row.browser.test.tsx
@@ -0,0 +1,190 @@
+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";
+
+// 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);
+  return { render, scrollTo, heldRowTop, rowSize };
+}
+
+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);
+});
+
+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 dec4c489b9..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);
   });
 
@@ -69,8 +69,8 @@ describe("buildAgentStreamRenderModel", () => {
       historyStart: 2,
     });
 
-    expect(model.turnTiming.byAssistantId.has("hidden-a")).toBe(false);
-    expect(model.turnTiming.byAssistantId.get("visible-a")).toEqual({
+    expect(model.turnTiming.byItemId.has("hidden-a")).toBe(false);
+    expect(model.turnTiming.byItemId.get("visible-a")).toEqual({
       completedAt: tail[3]?.timestamp,
       durationMs: 1000,
     });
@@ -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", () => {
@@ -184,7 +184,7 @@ describe("buildAgentStreamRenderModel", () => {
     });
 
     expect(model.turnTiming.runningStartedAt).toBe(tail[0]?.timestamp);
-    expect(model.turnTiming.byAssistantId.has("live-a")).toBe(false);
+    expect(model.turnTiming.byItemId.has("live-a")).toBe(false);
   });
 
   it("maps completed turn timing to assistant ids across committed history and live head", () => {
@@ -201,13 +201,13 @@ describe("buildAgentStreamRenderModel", () => {
     });
 
     expect(model.turnTiming.runningStartedAt).toBe(null);
-    expect(model.turnTiming.byAssistantId.get("live-a")).toEqual({
+    expect(model.turnTiming.byItemId.get("live-a")).toEqual({
       completedAt: head[0]?.timestamp,
       durationMs: 3000,
     });
   });
 
-  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,8 +219,8 @@ describe("buildAgentStreamRenderModel", () => {
       isMobileBreakpoint: false,
     });
 
-    expect(model.segments.historyMounted.map((item) => item.id)).toEqual(["a1", "u1"]);
-    expect(model.turnTiming.byAssistantId.get("a1")).toEqual({
+    expect(model.segments.historyMounted.map((item) => item.id)).toEqual(["u1", "a1"]);
+    expect(model.turnTiming.byItemId.get("a1")).toEqual({
       completedAt: tail[1]?.timestamp,
       durationMs: 3000,
     });
@@ -238,7 +238,7 @@ describe("buildAgentStreamRenderModel", () => {
       isMobileBreakpoint: false,
     });
 
-    expect(model.turnTiming.byAssistantId.size).toBe(0);
+    expect(model.turnTiming.byItemId.size).toBe(0);
   });
 
   it.each(["web", "native"] as const)(
@@ -274,10 +274,10 @@ describe("buildAgentStreamRenderModel", () => {
 
       expect(second.history).toBe(first.history);
       expect(second.segments.historyMounted).toBe(first.segments.historyMounted);
-      expect(second.turnTiming.byAssistantId).toBe(first.turnTiming.byAssistantId);
+      expect(second.turnTiming.byItemId).toBe(first.turnTiming.byItemId);
       expect(first.history).toHaveLength(20);
-      expect(first.turnTiming.byAssistantId.has("a29")).toBe(false);
-      expect(first.turnTiming.byAssistantId.get("a38")).toEqual({
+      expect(first.turnTiming.byItemId.has("a29")).toBe(false);
+      expect(first.turnTiming.byItemId.get("a38")).toEqual({
         completedAt: tail[77]?.timestamp,
         durationMs: 1000,
       });
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..b732edbb01
--- /dev/null
+++ b/packages/app/src/agent-stream/native-disclosure-hold.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import { createNativeDisclosureHold } 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("turn-1");
+    frames.runFrame();
+
+    expect(hold.heldRowId()).toBe("turn-1");
+    expect(releases).toEqual([]);
+
+    frames.runFrame();
+
+    expect(hold.heldRowId()).toBeNull();
+    expect(releases).toEqual(["released"]);
+  });
+
+  it("restarts the quiet frames on every item size change", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.hold("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("turn-1");
+    frames.runFrame();
+    hold.hold("turn-2");
+
+    expect(hold.heldRowId()).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("turn-1");
+    hold.cancel();
+    frames.runFrame();
+    frames.runFrame();
+
+    expect(hold.heldRowId()).toBeNull();
+    expect(releases).toEqual([]);
+  });
+});
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..96b5087b98
--- /dev/null
+++ b/packages/app/src/agent-stream/native-disclosure-hold.ts
@@ -0,0 +1,64 @@
+/**
+ * The native viewport's disclosure hold. While a row is held, it is the only row the list may
+ * anchor on. 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 {
+  heldRowId(): string | null;
+  hold(rowId: string): void;
+  noteItemSizeChanged(): void;
+  cancel(): void;
+}
+
+export function createNativeDisclosureHold(input: {
+  quietFrames: number;
+  requestFrame: (callback: () => void) => number;
+  cancelFrame: (id: number) => void;
+  onRelease: () => void;
+}): NativeDisclosureHold {
+  let heldRowId: string | null = null;
+  let frameId: number | null = null;
+  let remainingFrames = 0;
+
+  const stopCountdown = () => {
+    if (frameId !== null) {
+      input.cancelFrame(frameId);
+      frameId = null;
+    }
+  };
+
+  const tick = () => {
+    remainingFrames -= 1;
+    if (remainingFrames > 0) {
+      frameId = input.requestFrame(tick);
+      return;
+    }
+    frameId = null;
+    heldRowId = null;
+    input.onRelease();
+  };
+
+  const restartCountdown = () => {
+    stopCountdown();
+    remainingFrames = input.quietFrames;
+    frameId = input.requestFrame(tick);
+  };
+
+  return {
+    heldRowId: () => heldRowId,
+    hold(rowId) {
+      heldRowId = rowId;
+      restartCountdown();
+    },
+    noteItemSizeChanged() {
+      if (heldRowId !== null) {
+        restartCountdown();
+      }
+    },
+    cancel() {
+      stopCountdown();
+      heldRowId = null;
+    },
+  };
+}
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-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 357b6c079b..9f8213d716 100644
--- a/packages/app/src/agent-stream/presentation.test.ts
+++ b/packages/app/src/agent-stream/presentation.test.ts
@@ -15,6 +15,7 @@ import { QueryClient } from "@tanstack/react-query";
 import { describe, expect, it } from "vitest";
 import { buildAgentStreamRenderModel } from "./model";
 import { createStreamPresentation } from "./presentation";
+import { createReadingAnchor } from "./reading-anchor";
 
 const runtime = {
   paseo: {},
@@ -68,6 +69,9 @@ function installProbe(
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
   };
 }
 
@@ -588,3 +592,283 @@ describe("timeline presentation", () => {
     expect(projectTimelineItems([source], () => [])).toEqual([]);
   });
 });
+
+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", "probe-plugin/reply/0"]);
+  expect([...result.turns.turnsByHostId.keys()]).toEqual(["prompt"]);
+  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",
+    "probe-plugin/reply/0",
+  ]);
+  const expandedTurnHostIds = new Set(["prompt"]);
+  const opened = present({ ...completed, expandedTurnHostIds });
+  expect(opened.tail.map((item) => item.id)).toEqual([
+    "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",
+    "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.turnsByHostId.size).toBe(0);
+  },
+);
+
+it("opening a turn reveals individual calls rather than another tool group", () => {
+  const present = createStreamPresentation();
+  const timestamp = new Date();
+  const tail: StreamItem[] = [
+    { kind: "user_message", id: "prompt", text: "Work", timestamp },
+    toolCall("one", "Bash"),
+    toolCall("two", "Bash"),
+    { kind: "assistant_message", id: "reply", text: "Done", timestamp },
+  ];
+  const result = present({
+    ...presentationOptions,
+    transform: undefined,
+    tail,
+    head: [],
+    display: "collapseTurns",
+    isTurnActive: false,
+    expandedTurnHostIds: new Set(["prompt"]),
+  });
+  expect(result.tail.map((item) => item.id)).toEqual(tail.map((item) => item.id));
+  expect(result.groupsByHostId.size).toBe(0);
+  expect(result.readingRowReplacements.get("tool-two")).toBeUndefined();
+});
+
+it.each(["collapseToolCalls", "collapseTurns"] as const)(
+  "preserves the reader when a prepend extends a group in %s",
+  (display) => {
+    const present = createStreamPresentation();
+    const anchor = createReadingAnchor();
+    const calls = [toolCall("one", "Bash"), toolCall("two", "Bash")];
+    const input = {
+      ...presentationOptions,
+      transform: undefined,
+      display,
+      head: [],
+      isTurnActive: false,
+    };
+    const partial = present({ ...input, tail: calls.slice(1) });
+    anchor.reconcile(0, [{ id: partial.tail[0]!.id, top: 48, height: 200 }]);
+    const completed = present({ ...input, tail: calls });
+    const groupId = completed.tail[0]!.id;
+    expect(anchor.getRowId(completed.readingRowReplacements)).toBe(groupId);
+    expect(
+      anchor.reconcile(
+        0,
+        [{ id: groupId, top: 448, height: 200 }],
+        false,
+        completed.readingRowReplacements,
+      ),
+    ).toBe(400);
+    expect(anchor.getRowId()).toBe(groupId);
+    const timestamp = new Date();
+    const folded = present({
+      ...input,
+      display: "collapseTurns",
+      tail: [
+        { kind: "user_message", id: "prompt", text: "Work", timestamp },
+        ...calls,
+        { kind: "assistant_message", id: "reply", text: "Done", timestamp },
+      ],
+    });
+    // Both the original partial group and its replacement resolve directly to the turn.
+    expect(folded.readingRowReplacements.get(calls[1]!.id)).toBe("prompt");
+    expect(anchor.getRowId(folded.readingRowReplacements)).toBe("prompt");
+    const opened = present({ ...input, tail: calls, display: "full" });
+    expect(opened.readingRowReplacements.get(calls[1]!.id)).toBeUndefined();
+  },
+);
+
+it("presents received agent messages as attributed bubbles with the original turn identity", () => {
+  const call = toolCall("received", "agent_message");
+  if (call.payload.source !== "agent") throw new Error("Expected agent tool");
+  call.turnId = "turn";
+  call.payload.data.agentMessage = {
+    event: "message",
+    sender: { id: "sender", title: "Reviewer" },
+    text: "Ready",
+  };
+  const result = createStreamPresentation()({
+    ...presentationOptions,
+    transform: undefined,
+    tail: [call],
+    head: [],
+  });
+  expect(result.tail[0]).toMatchObject({
+    kind: "user_message",
+    id: call.id,
+    turnId: "turn",
+    text: "Ready",
+    sender: { id: "sender", title: "Reviewer" },
+  });
+});
+
+it("does not reopen the previous turn while a new run waits for its first row", () => {
+  const timestamp = new Date();
+  const tail: StreamItem[] = [
+    { kind: "user_message", id: "prompt", text: "Work", timestamp },
+    toolCall("one", "Bash"),
+    { kind: "assistant_message", id: "reply", text: "Done", timestamp },
+  ];
+  for (const item of tail) item.turnId = "completed";
+  const result = createStreamPresentation()({
+    ...presentationOptions,
+    transform: undefined,
+    tail,
+    head: [],
+    display: "collapseTurns",
+    isTurnActive: true,
+    activeTurnId: "new",
+  });
+  expect(result.tail.map((item) => item.id)).toEqual(["prompt", "reply"]);
+});
+
+// A sent prompt counts as activity before the daemon opens its turn, so the only known turn is
+// the completed one; it must stay folded until the new turn's rows arrive.
+it("keeps the previous turn folded while a sent prompt waits for its turn to open", () => {
+  const timestamp = new Date();
+  const tail: StreamItem[] = [
+    { kind: "user_message", id: "prompt", text: "Work", timestamp },
+    toolCall("one", "Bash"),
+    { kind: "assistant_message", id: "reply", text: "Done", timestamp },
+  ];
+  for (const item of tail) item.turnId = "completed";
+  const result = createStreamPresentation()({
+    ...presentationOptions,
+    transform: undefined,
+    tail,
+    head: [],
+    display: "collapseTurns",
+    isTurnActive: true,
+    activeTurnId: null,
+  });
+  expect(result.tail.map((item) => item.id)).toEqual(["prompt", "reply"]);
+});
+
+it("groups reasoning with tools unless Expand thinking is enabled, including setting changes", () => {
+  const present = createStreamPresentation();
+  const timestamp = new Date();
+  const thought: StreamItem = {
+    kind: "thought",
+    id: "thought",
+    text: "Consider this",
+    status: "ready",
+    timestamp,
+  };
+  const tail: StreamItem[] = [toolCall("one", "Bash"), thought, toolCall("two", "Bash")];
+  for (const item of tail) item.turnId = "run";
+  const input = {
+    ...presentationOptions,
+    transform: undefined,
+    tail,
+    head: [],
+    display: "collapseToolCalls" as const,
+    isTurnActive: false,
+  };
+  const grouped = present({ ...input, autoExpandReasoning: false });
+  expect(grouped.tail).toHaveLength(1);
+  expect(grouped.groupsByHostId.get("tool-one")?.run.calls).toEqual(tail);
+  const separate = present({ ...input, autoExpandReasoning: true });
+  expect(separate.tail.map((item) => item.id)).toEqual(["tool-one", "thought", "tool-two"]);
+  expect(separate.groupsByHostId.has("thought")).toBe(false);
+  const next = { ...thought, id: "next", turnId: "next-run" };
+  const bounded = present({ ...input, tail: [...tail, next], autoExpandReasoning: false });
+  expect(bounded.tail.map((item) => item.id)).toEqual(["tool-one", "next"]);
+});
+
+it.each([false, true])(
+  "reveals raw reasoning when opening a turn (Expand thinking %s)",
+  (autoExpandReasoning) => {
+    const timestamp = new Date();
+    const tail: StreamItem[] = [
+      { kind: "user_message", id: "prompt", text: "Work", timestamp },
+      { kind: "thought", id: "thought", text: "Consider this", status: "ready", timestamp },
+      toolCall("one", "Bash"),
+      { kind: "assistant_message", id: "reply", text: "Done", timestamp },
+    ];
+    const input = {
+      ...presentationOptions,
+      transform: undefined,
+      tail,
+      head: [],
+      display: "collapseTurns" as const,
+      isTurnActive: false,
+      autoExpandReasoning,
+    };
+    const present = createStreamPresentation();
+    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.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 9e8e5b430e..9a5ff6469e 100644
--- a/packages/app/src/agent-stream/presentation.ts
+++ b/packages/app/src/agent-stream/presentation.ts
@@ -1,3 +1,4 @@
+import { isTurnBoundary } from "./turn-membership";
 import type { ChatDisplay } from "@/hooks/use-settings";
 import type { TimelineItemTransform } from "@/plugins/timeline/model";
 import { projectPluginTimelineItems } from "@/plugins/timeline/projection";
@@ -10,19 +11,38 @@ import {
 } from "@/tool-calls/detail-level/projection";
 import type { StreamItem, UserMessageItem } from "@/types/stream";
 import { collapseTurns, type TurnCollapse } from "./turn-collapse/model";
+import type { ReadingRowReplacements } from "./reading-anchor";
 
 interface PresentationInput {
   tail: StreamItem[];
   head: StreamItem[];
   transform: TimelineItemTransform | undefined;
   display: ChatDisplay;
+  autoExpandReasoning?: boolean;
   /** User messages whose collapsed turn the reader opened. */
   expandedTurnHostIds: ReadonlySet<string>;
   isTurnActive: boolean;
+  activeTurnId?: string | null;
 }
 
 export interface StreamPresentation extends ToolCallDetailProjection {
   turns: Omit<TurnCollapse, "tail">;
+  readingRowReplacements: ReadingRowReplacements;
+}
+
+function groupedRowHosts(
+  rows: readonly StreamItem[],
+  groups: ToolCallDetailProjection["groupsByHostId"],
+): ReadonlyMap<string, string> {
+  const hosts = new Map<string, string>();
+  for (const row of rows) {
+    const group = groups.get(row.id);
+    if (!group) continue;
+    for (const call of group.run.calls) {
+      if (call.id !== row.id) hosts.set(call.id, row.id);
+    }
+  }
+  return hosts;
 }
 
 const NO_COLLAPSED_TURNS: StreamPresentation["turns"] = collapseTurns({
@@ -30,6 +50,7 @@ const NO_COLLAPSED_TURNS: StreamPresentation["turns"] = collapseTurns({
   isLatestTurnOpen: false,
   expandedHostIds: new Set(),
   getGroupedCalls: () => undefined,
+  previousTurnsByHostId: new Map(),
 });
 
 /** Source messages reach plugins before display projection. */
@@ -55,27 +76,54 @@ export function createStreamPresentation() {
   let historyTransform: TimelineItemTransform | undefined;
   let historyRows: StreamItem[] = [];
   let preparedTail: StreamItem[] | undefined;
+  let preparedAutoExpandReasoning: boolean | undefined;
   let preparedLevel: ToolCallDetailLevel | undefined;
   let preparedHistory: PreparedToolCallHistory | null = null;
+  let historyGroupHosts: ReadonlyMap<string, string> = new Map();
   let collapsedSource: StreamItem[] | undefined;
   let collapsedIsLatestTurnOpen = false;
   let collapsedExpandedHostIds: ReadonlySet<string> | undefined;
   let collapsed: TurnCollapse | undefined;
 
   function presentRows(item: StreamItem): StreamItem[] {
+    if (item.kind === "tool_call" && item.payload.source === "agent") {
+      const message = item.payload.data.agentMessage;
+      if (message?.event === "message") {
+        return [
+          {
+            kind: "user_message",
+            id: item.id,
+            turnId: item.turnId,
+            timelineCursor: item.timelineCursor,
+            timestamp: item.timestamp,
+            text: message.text,
+            sender: message.sender,
+          },
+        ];
+      }
+    }
     return [item.kind === "user_message" ? presentUserMessage(item) : item];
   }
 
   function collapse(
     projection: ToolCallDetailProjection,
     input: PresentationInput,
-  ): StreamPresentation {
+  ): Omit<StreamPresentation, "readingRowReplacements"> {
     if (input.display !== "collapseTurns") {
       return { ...projection, turns: NO_COLLAPSED_TURNS };
     }
     // Live text updates reach the head only, so the folded history is reused until the
     // retained rows, the latest turn's liveness, or the reader's expanded turns change.
-    const isLatestTurnOpen = input.isTurnActive || projection.head.length > 0;
+    const last = projection.tail.at(-1) ?? null;
+    const first = projection.head[0] ?? null;
+    const activeTurnIsAnother = Boolean(
+      input.activeTurnId && last?.turnId && input.activeTurnId !== last.turnId,
+    );
+    // Without head rows, the latest retained turn is live only while the active run is that
+    // turn. A run that has not opened yet carries no id and belongs to the next turn.
+    const isLatestTurnOpen = first
+      ? !isTurnBoundary(last, first) && !activeTurnIsAnother
+      : input.isTurnActive && (last?.turnId === undefined || input.activeTurnId === last.turnId);
     if (
       !collapsed ||
       collapsedSource !== projection.tail ||
@@ -87,13 +135,27 @@ export function createStreamPresentation() {
         isLatestTurnOpen,
         expandedHostIds: input.expandedTurnHostIds,
         getGroupedCalls: (itemId) => projection.groupsByHostId.get(itemId)?.run.calls,
+        previousTurnsByHostId: collapsed?.turnsByHostId ?? NO_COLLAPSED_TURNS.turnsByHostId,
       });
       collapsedSource = projection.tail;
       collapsedIsLatestTurnOpen = isLatestTurnOpen;
       collapsedExpandedHostIds = input.expandedTurnHostIds;
     }
     const { tail, ...turns } = collapsed;
-    return { ...projection, tail, turns };
+    if (turns.nestedItemIds.size === 0) return { ...projection, tail, turns };
+    // Opening a turn reveals its raw calls; those rows must not become group hosts again.
+    const withoutExpandedRows = (groups: StreamPresentation["groupsByHostId"]) => ({
+      size: groups.size - [...turns.nestedItemIds].filter((id) => groups.has(id)).length,
+      get: (id: string) => (turns.nestedItemIds.has(id) ? undefined : groups.get(id)),
+      has: (id: string) => !turns.nestedItemIds.has(id) && groups.has(id),
+    });
+    return {
+      ...projection,
+      tail,
+      turns,
+      groupsByHostId: withoutExpandedRows(projection.groupsByHostId),
+      historyGroupUpdatesByHostId: withoutExpandedRows(projection.historyGroupUpdatesByHostId),
+    };
   }
 
   return (input: PresentationInput): StreamPresentation => {
@@ -111,20 +173,48 @@ export function createStreamPresentation() {
       const blocks = presentRows(item);
       head.push(...blocks);
     }
-    if (preparedTail !== historyRows || preparedLevel !== level) {
-      preparedHistory = prepareToolCallHistory(level, historyRows);
+    if (
+      preparedTail !== historyRows ||
+      preparedLevel !== level ||
+      preparedAutoExpandReasoning !== input.autoExpandReasoning
+    ) {
+      preparedHistory = prepareToolCallHistory(level, historyRows, input.autoExpandReasoning);
+      historyGroupHosts = preparedHistory
+        ? groupedRowHosts(preparedHistory.grouped.tail, preparedHistory.grouped.groupsByHostId)
+        : new Map();
       preparedTail = historyRows;
       preparedLevel = level;
+      preparedAutoExpandReasoning = input.autoExpandReasoning;
     }
-    return collapse(
-      projectToolCallDetailLevel({
-        level,
-        tail: historyRows,
-        head,
-        preparedHistory,
-        isTurnActive: input.isTurnActive,
-      }),
-      input,
+    const projection = projectToolCallDetailLevel({
+      level,
+      tail: historyRows,
+      head,
+      preparedHistory,
+      isTurnActive: input.isTurnActive,
+    });
+    const result = collapse(projection, input);
+    // Only the trailing retained group can absorb head rows. Reuse the retained
+    // index across streaming updates rather than walking the full history again.
+    const last = projection.tail.at(-1);
+    const liveGroupHosts = groupedRowHosts(
+      last ? [last, ...projection.head] : projection.head,
+      projection.groupsByHostId,
     );
+    const retainedGroupHosts = historyGroupHosts;
+    return {
+      ...result,
+      readingRowReplacements: {
+        get(id) {
+          if (result.turns.nestedItemIds.has(id)) return undefined;
+          const groupHost = liveGroupHosts.get(id) ?? retainedGroupHosts.get(id) ?? id;
+          return (
+            result.turns.hostIdByHiddenRowId.get(id) ??
+            result.turns.hostIdByHiddenRowId.get(groupHost) ??
+            (groupHost === id ? undefined : groupHost)
+          );
+        },
+      },
+    };
   };
 }
diff --git a/packages/app/src/agent-stream/reading-anchor.test.ts b/packages/app/src/agent-stream/reading-anchor.test.ts
index 74b2bd5bcd..30d30ab1a0 100644
--- a/packages/app/src/agent-stream/reading-anchor.test.ts
+++ b/packages/app/src/agent-stream/reading-anchor.test.ts
@@ -2,6 +2,24 @@ import { describe, expect, it } from "vitest";
 import { createReadingAnchor } from "./reading-anchor";
 
 describe("reading anchor", () => {
+  it("pins the folded turn host when a prepend replaces the row being read", () => {
+    const anchor = createReadingAnchor();
+    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);
+    // 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");
+    expect(
+      anchor.reconcile(0, [{ id: "prompt", top: 1048, height: 100 }], false, replacements),
+    ).toBe(1000);
+    expect(anchor.getRowId()).toBe("prompt");
+    expect(
+      anchor.reconcile(1000, [{ id: "prompt", top: 1048, height: 100 }], false, replacements),
+    ).toBe(1000);
+  });
+
   const rows = [
     { id: "above", top: 0, height: 500 },
     { id: "reading", top: 500, height: 500 },
@@ -38,6 +56,16 @@ 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]!);
+    // 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("leaves expansion of the row being read in place", () => {
     const anchor = createReadingAnchor();
     anchor.reconcile(600, rows);
diff --git a/packages/app/src/agent-stream/reading-anchor.ts b/packages/app/src/agent-stream/reading-anchor.ts
index 4299f1d9c8..ed2baa552a 100644
--- a/packages/app/src/agent-stream/reading-anchor.ts
+++ b/packages/app/src/agent-stream/reading-anchor.ts
@@ -6,6 +6,10 @@ interface RowGeometry {
 
 // A row must clear the reading line before the next row takes ownership.
 const READING_POSITION_OFFSET_PX = 8;
+export interface ReadingRowReplacements {
+  get(id: string): string | undefined;
+}
+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.
@@ -14,27 +18,42 @@ export function createReadingAnchor() {
   let geometry: readonly RowGeometry[] = [];
   const readingRow = (scrollTop: number) =>
     geometry.find((row) => row.top + row.height > scrollTop + READING_POSITION_OFFSET_PX);
-  const project = (scrollTop: number, row: Pick<RowGeometry, "id" | "top"> | undefined) =>
-    scrollTop + (anchor && row?.id === anchor.id ? row.top - anchor.top : 0);
+  const getRowId = (replacements = NO_REPLACEMENTS) =>
+    anchor ? (replacements.get(anchor.id) ?? anchor.id) : null;
+  const project = (
+    scrollTop: number,
+    row: Pick<RowGeometry, "id" | "top"> | undefined,
+    replacements = NO_REPLACEMENTS,
+  ) => scrollTop + (anchor && row && row.id === getRowId(replacements) ? row.top - anchor.top : 0);
   return {
-    getRowId: () => anchor?.id ?? null,
+    getRowId,
     getReadingRowId: (scrollTop: number) =>
       readingRow(scrollTop)?.id ?? geometry.at(-1)?.id ?? null,
     project,
     reset() {
       anchor = null;
     },
+    // A disclosure names the row that owns its trigger. That row keeps its top
+    // through the toggle, even when another row sits under the reading line.
+    pin(row: Pick<RowGeometry, "id" | "top">) {
+      anchor = { id: row.id, top: row.top };
+    },
     scroll(scrollTop: number) {
       const next = readingRow(scrollTop);
       anchor = next ? { id: next.id, top: next.top } : null;
     },
-    reconcile(scrollTop: number, rows: readonly RowGeometry[], userScrolled = false): number {
+    reconcile(
+      scrollTop: number,
+      rows: readonly RowGeometry[],
+      userScrolled = false,
+      replacements = NO_REPLACEMENTS,
+    ): number {
       geometry = rows;
-      const previous = anchor && rows.find((row) => row.id === anchor?.id);
+      const previous = anchor && rows.find((row) => row.id === getRowId(replacements));
       // The first virtualized commit can precede its mounted range. Keep the
       // pinned reader until it mounts, rather than adopting an unrelated row.
       if (anchor && !previous && !userScrolled) return scrollTop;
-      const correctedTop = project(scrollTop, previous ?? undefined);
+      const correctedTop = project(scrollTop, previous ?? undefined, replacements);
       // 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);
diff --git a/packages/app/src/agent-stream/render-strategy.test.ts b/packages/app/src/agent-stream/render-strategy.test.ts
index 22d7c5f2f1..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,84 +107,42 @@ 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");
   });
 
-  it("collects copy content across adjacent turns without a visible prompt", () => {
+  it("keeps copied content within the canonical turn without a visible prompt", () => {
     const chronological: StreamItem[] = [
       { ...assistantMessage("a1", "first turn", 1), turnId: "turn-1" },
       { ...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({
@@ -228,41 +150,21 @@ describe("neighbor and traversal semantics", () => {
         items: chronological,
         startIndex: 2,
       }),
-    ).toBe("first turn\n\nsecond turn");
+    ).toBe("second turn");
   });
 
   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/strategy-native.tsx b/packages/app/src/agent-stream/strategy-native.tsx
index 7dc6e8d521..3288e2be25 100644
--- a/packages/app/src/agent-stream/strategy-native.tsx
+++ b/packages/app/src/agent-stream/strategy-native.tsx
@@ -1,38 +1,42 @@
 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 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 { createNativeDisclosureHold } from "./native-disclosure-hold";
+import { EndPinnedScrollView } from "./native-end-pin";
+import { createNewRowEstimates } from "./new-row-estimates";
 import type { StreamRenderInput, StreamStrategy, StreamViewportHandle } from "./strategy";
-import {
-  createStreamStrategy,
-  isNearBottomForStreamRenderStrategy,
-  resolveBottomAnchorTransportBehavior,
-} from "./strategy";
+import { createStreamStrategy, isNearBottomForStreamRenderStrategy } from "./strategy";
 import {
   abandonHistoryStartPaginationRequest,
   createHistoryStartPaginationState,
@@ -49,11 +53,6 @@ import {
   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 +64,50 @@ 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);
+}
 
 function keyExtractor(item: { id: string }): string {
   return item.id;
@@ -94,7 +136,11 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     strategy,
   } = props;
   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,11 +153,9 @@ 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,
@@ -126,13 +170,28 @@ 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,
+      distanceFromHistoryStart: metrics.offsetY,
       hasOlderHistory,
       isLoadingOlderHistory,
       isReady: historyStartReadyRef.current && hasMeasuredViewport,
@@ -196,13 +255,6 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     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 +262,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 +295,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 +310,79 @@ 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],
+  const releaseDisclosure = useStableEvent(() => {
+    bottomAnchorController.releaseDisclosure({ isAtEnd: isAtEnd() });
+  });
+  const [disclosureHold] = useState(() =>
+    createNativeDisclosureHold({
+      quietFrames: DISCLOSURE_QUIET_FRAMES,
+      requestFrame: requestAnimationFrame,
+      cancelFrame: cancelAnimationFrame,
+      onRelease: releaseDisclosure,
+    }),
+  );
+  useEffect(() => () => disclosureHold.cancel(), [disclosureHold]);
+  // 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. The row's measurement trigger
+  // makes that same commit carry the row's new height.
+  const holdRow = useStableEvent((rowId: string, apply: () => void) => {
+    disclosureHold.hold(rowId);
+    bottomAnchorController.holdForDisclosure();
+    apply();
+    rowLayoutSyncRegistry.get(rowId)?.();
+  });
+  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 heldRowId = disclosureHold.heldRowId();
+    return heldRowId === null || item.id === heldRowId;
+  });
+  // 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.
+  // - 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";
+  const pinsEnd = isFollowingEnd && isListPlaced;
+  const maintainVisibleContentPosition = useMemo(
+    () => (isFollowingEnd ? false : { data: true, size: true, shouldRestorePosition }),
+    [isFollowingEnd, 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();
@@ -341,13 +393,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       historyStartSettleSchedulerRef.current?.cancel();
       historyStartSettleSchedulerRef.current = null;
     };
-  }, [agentId, clearNativeViewportSettling, clearPendingUserScrollEnd, evaluateHistoryStart]);
-
-  useEffect(() => () => clearNativeViewportSettling(), [clearNativeViewportSettling]);
-
-  useEffect(() => {
-    bottomAnchorController.prepareForStickyContentChange();
-  }, [bottomAnchorController, historyRows, segments.liveHead]);
+  }, [clearPendingUserScrollEnd, evaluateHistoryStart]);
 
   useEffect(() => {
     const handle: StreamViewportHandle = {
@@ -359,9 +405,8 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       },
       prepareForViewportChange: () => {
         bottomAnchorController.prepareForStickyViewportChange();
-        markNativeViewportSettling();
       },
-      holdReadingPosition: () => bottomAnchorController.detachByUser(),
+      holdRow,
     };
     viewportRef.current = handle;
     return () => {
@@ -369,7 +414,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 +454,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 +482,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 {
@@ -424,6 +509,10 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     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.
+    disclosureHold.cancel();
     bottomAnchorController.beginUserScroll();
     const rearmed = rearmHistoryStartPagination(historyStartPaginationStateRef.current);
     if (rearmed !== historyStartPaginationStateRef.current) {
@@ -433,17 +522,22 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     }
   });
 
-  // Defer drag end so momentum can take ownership, but capture the terminal
-  // gesture position now because layout may move the viewport in the meantime.
+  // 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 +552,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 +565,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 +572,6 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       viewportHeight,
       viewportMeasuredForKey: "native-virtualized",
     };
-    if (viewportChanged) {
-      markNativeViewportSettling();
-    }
     bottomAnchorController.handleViewportMetricsChange({
       previousViewportWidth,
       viewportWidth,
@@ -493,24 +582,37 @@ 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,
-    });
+    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") {
       scheduleHistoryStartSettle();
     }
   });
 
+  const handleListPlaced = useStableEvent(() => {
+    isListPlacedRef.current = true;
+    setIsListPlaced(true);
+    streamViewportMetricsRef.current = {
+      ...streamViewportMetricsRef.current,
+      contentMeasuredForKey: "native-virtualized",
+    };
+    bottomAnchorController.handleContentSizeChange();
+  });
+
   useEffect(() => {
     evaluateHistoryStart();
     if (historyStartPaginationStateRef.current.status === "settling") {
@@ -524,45 +626,35 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     scheduleHistoryStartSettle,
   ]);
 
+  // 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">
@@ -575,21 +667,21 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     );
   }, [historyStartPaginationState]);
 
-  // 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}
+    <LegendList<StreamItem>
+      ref={listRef}
+      data={rows}
       renderItem={renderItem}
+      extraData={renderHistoryMountedRow}
       keyExtractor={keyExtractor}
-      strictMode
       testID="agent-chat-scroll"
       nativeID="agent-chat-scroll-native-virtualized"
-      ListHeaderComponent={liveHeaderContent ?? undefined}
-      ListFooterComponent={historyFooterContent ?? undefined}
+      ListHeaderComponent={historyStartContent}
+      ListFooterComponent={liveAuxiliaryContent ?? undefined}
       contentContainerStyle={listContentContainerStyle}
+      automaticallyAdjustContentInsets={false}
+      automaticallyAdjustsScrollIndicatorInsets={false}
+      contentInsetAdjustmentBehavior="never"
       style={listStyle}
       onLayout={handleListLayout}
       onScroll={handleScroll}
@@ -599,16 +691,17 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       onMomentumScrollEnd={handleMomentumScrollEnd}
       scrollEventThrottle={16}
       onContentSizeChange={handleContentSizeChange}
+      onItemSizeChanged={handleItemSizeChanged}
+      onReady={handleListPlaced}
       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}
+      renderScrollComponent={renderScrollComponent}
+      recycleItems={false}
+      alignItemsAtEnd
+      initialScrollAtEnd
+      drawDistance={NATIVE_STREAM_DRAW_DISTANCE}
+      getEstimatedItemSize={getEstimatedItemSize}
       scrollEnabled={scrollEnabled}
       showsVerticalScrollIndicator
-      inverted
     />
   );
 }
@@ -616,26 +709,20 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
 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..28fbd1e2a2
--- /dev/null
+++ b/packages/app/src/agent-stream/strategy-web.browser.test.tsx
@@ -0,0 +1,158 @@
+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 { 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: () => 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) =>
+      act(() => viewportRef.current!.holdRow(rowId, apply)),
+    rowTop: (id: string) =>
+      rowElement(id).getBoundingClientRect().top - scrollContainer.getBoundingClientRect().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);
+  });
+
+  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 1f61d0a14c..5ad0be03c2 100644
--- a/packages/app/src/agent-stream/strategy-web.test.tsx
+++ b/packages/app/src/agent-stream/strategy-web.test.tsx
@@ -7,7 +7,7 @@ import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { RetainedPanelActivity } from "@/components/retained-panel";
-import type { StreamItem } from "@/types/stream";
+import { reduceStreamUpdate, type StreamItem } from "@/types/stream";
 import type { StreamRenderInput, StreamSegmentRenderers, StreamViewportHandle } from "./strategy";
 import { createWebStreamStrategy } from "./strategy-web";
 
@@ -131,6 +131,79 @@ describe("createWebStreamStrategy", () => {
     vi.restoreAllMocks();
   });
 
+  it.each(["liveHead", "historyMounted"] as const)(
+    "keeps one rendered tool row after late prior-turn updates in %s",
+    (lane) => {
+      const strategy = createWebStreamStrategy({ isMobileBreakpoint: true });
+      container = document.createElement("div");
+      document.body.appendChild(container);
+      root = createRoot(container);
+      const input: StreamRenderInput = {
+        agentId: "agent",
+        segments: { historyVirtualized: [], historyMounted: [], liveHead: [] },
+        boundary: {
+          hasVirtualizedHistory: false,
+          hasMountedHistory: lane === "historyMounted",
+          hasLiveHead: lane === "liveHead",
+        },
+        renderers: createRenderers(() => {}),
+        listEmptyComponent: null,
+        viewportRef: React.createRef<StreamViewportHandle>(),
+        routeBottomAnchorRequest: null,
+        isAuthoritativeHistoryReady: true,
+        onNearBottomChange: () => {},
+        onNearHistoryStart: () => true,
+        isLoadingOlderHistory: false,
+        hasOlderHistory: false,
+        olderHistoryProgressKey: null,
+        scrollEnabled: true,
+        listStyle: null,
+        baseListContentContainerStyle: null,
+        forwardListContentContainerStyle: null,
+        contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
+      };
+      let items: StreamItem[] = [];
+      const updates = [
+        { callId: "background", turnId: "old", status: "running" },
+        { callId: "exec", turnId: "current", status: "running" },
+        { callId: "background", turnId: "old", status: "completed" },
+        { callId: "exec", turnId: "current", status: "completed" },
+      ] as const;
+      for (const [index, update] of updates.entries()) {
+        items = reduceStreamUpdate(
+          items,
+          {
+            type: "timeline",
+            provider: "codex",
+            turnId: update.turnId,
+            item: {
+              type: "tool_call",
+              callId: update.callId,
+              name: "exec_command",
+              status: update.status,
+              error: null,
+              detail: { type: "shell", command: update.callId },
+            },
+          },
+          new Date(index),
+        );
+        act(() =>
+          root?.render(
+            strategy.render({
+              ...input,
+              segments: { ...input.segments, [lane]: items },
+            }),
+          ),
+        );
+      }
+      const rows = [...container.querySelectorAll("[data-history-row-id]")];
+      expect(rows.map((row) => row.getAttribute("data-history-row-id"))).toEqual([
+        "agent_tool_turn:old/background",
+        "agent_tool_turn:current/exec",
+      ]);
+    },
+  );
+
   it("mounts virtualized history without recursive row measurement updates", () => {
     const rowRenderCount = vi.fn();
     const strategy = createWebStreamStrategy({ isMobileBreakpoint: true });
diff --git a/packages/app/src/agent-stream/strategy-web.tsx b/packages/app/src/agent-stream/strategy-web.tsx
index 8e8bdf7680..b511ac72dd 100644
--- a/packages/app/src/agent-stream/strategy-web.tsx
+++ b/packages/app/src/agent-stream/strategy-web.tsx
@@ -363,6 +363,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,
@@ -394,7 +396,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   const rangeExtractor = useCallback(
     (range: VirtualRange): number[] => {
       const anchorIndex = segments.historyVirtualized.findIndex(
-        (row) => row.id === readingAnchor.getRowId(),
+        (row) => row.id === readingAnchor.getRowId(props.readingRowReplacements),
       );
       const container = scrollContainerRef.current;
       // TanStack has computed the new measurements before calling the extractor.
@@ -404,10 +406,14 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       const measurement = virtualizer.measurementsCache[anchorIndex];
       const correctedOffset =
         container && measurement
-          ? readingAnchor.project(container.scrollTop, {
-              id: String(measurement.key),
-              top: measurement.start,
-            })
+          ? readingAnchor.project(
+              container.scrollTop,
+              {
+                id: String(measurement.key),
+                top: measurement.start,
+              },
+              props.readingRowReplacements,
+            )
           : container?.scrollTop;
       let visibleRange = range;
       if (
@@ -428,7 +434,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
         ]),
       ].sort((left, right) => left - right);
     },
-    [chatFindRowIndexes, readingAnchor, segments.historyVirtualized],
+    [chatFindRowIndexes, readingAnchor, segments.historyVirtualized, props.readingRowReplacements],
   );
   const virtualOffsetListener = useRef<((offset: number, scrolling: boolean) => void) | null>(null);
   const observeVirtualOffset = useCallback<typeof observeElementOffset>((instance, onOffset) => {
@@ -724,25 +730,35 @@ 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(container.scrollTop, rows);
+    const correctedTop = readingAnchor.reconcile(
+      container.scrollTop,
+      rows,
+      false,
+      props.readingRowReplacements,
+    );
     if (!shouldAnchor) {
       readingAnchor.reset();
       return;
@@ -754,6 +770,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
@@ -818,10 +839,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();
@@ -832,7 +849,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       historyStartSettleSchedulerRef.current?.cancel();
       historyStartSettleSchedulerRef.current = null;
     };
-  }, [evaluateHistoryStart, props.agentId, readingAnchor]);
+  }, [evaluateHistoryStart]);
 
   useLayoutEffect(() => {
     if (!isActiveRef.current || !isActivationReady) {
@@ -1173,10 +1190,13 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
         }
         scheduleStickToBottom();
       },
-      holdReadingPosition: () => {
+      holdRow: (rowId, apply) => {
         cancelPendingStickToBottom();
         setFollowOutput(false);
-        readingAnchor.scroll(scrollContainerRef.current?.scrollTop ?? 0);
+        const row = measureRows()?.find((candidate) => candidate.id === rowId);
+        if (row) readingAnchor.pin(row);
+        disclosurePendingRef.current = true;
+        apply();
       },
       scrollToMessage,
     };
@@ -1190,6 +1210,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   }, [
     cancelPendingStickToBottom,
     forceStickToBottom,
+    measureRows,
     readingAnchor,
     scheduleStickToBottom,
     scrollToMessage,
@@ -1370,11 +1391,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,
@@ -1383,9 +1400,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 3d9df4d201..d1d40d351f 100644
--- a/packages/app/src/agent-stream/strategy.ts
+++ b/packages/app/src/agent-stream/strategy.ts
@@ -1,6 +1,7 @@
 import type { ComponentType, ReactElement, ReactNode, RefObject } from "react";
 import type { StyleProp, ViewStyle } from "react-native";
 import type { StreamItem } from "@/types/stream";
+import type { ReadingRowReplacements } from "./reading-anchor";
 import { continuesResponse } from "./turn-membership";
 import type { StreamHistoryBoundary, StreamRenderSegments } from "./model";
 import type {
@@ -13,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";
@@ -55,8 +51,11 @@ export interface StreamViewportHandle {
   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 its visual top.
+   * Following output stops; it resumes if the change leaves the list at its end.
+   */
+  holdRow: (rowId: string, apply: () => void) => void;
   scrollToMessage?: (messageId: string, occurrence?: ScrollToMessageOccurrence) => void;
 }
 
@@ -78,6 +77,8 @@ export interface StreamRenderInput {
   segments: StreamRenderSegments;
   historyRowRevision?: StreamHistoryRowRevision;
   liveHeadRowRevision?: unknown;
+  /** Presentation rows replaced by another row after history is folded. */
+  readingRowReplacements?: ReadingRowReplacements;
   boundary: StreamHistoryBoundary;
   renderers: StreamSegmentRenderers;
   listEmptyComponent: ReactNode;
@@ -122,14 +123,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;
@@ -145,9 +143,6 @@ interface StreamStrategyConfig {
   historyLiveBoundaryEdge: "first" | "last";
   liveHeadHistoryBoundaryEdge: "first" | "last";
   frameChildOrder: StreamFrameChildOrder;
-  flatListInverted: boolean;
-  overlayScrollbarInverted: boolean;
-  maintainVisibleContentPosition?: MaintainVisibleContentPositionConfig;
   bottomAnchorTransportBehavior: BottomAnchorTransportBehavior;
   disableParentScrollOnInlineDetailsExpansion: boolean;
   anchorBottomOnContentSizeChange: boolean;
@@ -157,8 +152,6 @@ interface StreamStrategyConfig {
   getBottomOffset: (metrics: StreamViewportMetrics) => number;
 }
 
-const NATIVE_SETTLING_VERIFICATION_DELAY_FRAMES = 4;
-
 export function createStreamStrategy(config: StreamStrategyConfig): StreamStrategy {
   return {
     render: config.render,
@@ -213,7 +206,6 @@ export function createStreamStrategy(config: StreamStrategyConfig): StreamStrate
         ListFooterComponentStyle: { marginTop: gapSize },
       };
     },
-    getMaintainVisibleContentPosition: () => config.maintainVisibleContentPosition,
     getBottomAnchorTransportBehavior: () => config.bottomAnchorTransportBehavior,
     getHistoryLiveBoundaryIndex: (history) => {
       if (history.length === 0) {
@@ -234,8 +226,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,
@@ -244,23 +234,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/stream-tick.bench.ts b/packages/app/src/agent-stream/stream-tick.bench.ts
index dc1fecb881..b765c441e8 100644
--- a/packages/app/src/agent-stream/stream-tick.bench.ts
+++ b/packages/app/src/agent-stream/stream-tick.bench.ts
@@ -110,7 +110,7 @@ function runTicks(input: { tail: StreamItem[]; historyStart: number; heads: Stre
       isTurnActive: true,
       history: model.history,
       liveHead: model.segments.liveHead,
-      timingByAssistantId: model.turnTiming.byAssistantId,
+      timingByItemId: model.turnTiming.byItemId,
     });
   }
 }
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 4535b14d9e..4fab619628 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,
+    previousTurnsByHostId: new Map(),
     ...options,
   });
 }
@@ -48,6 +64,118 @@ function collapse(tail: StreamItem[], options: Partial<CollapseTurnsInput> = {})
 const ids = (items: StreamItem[]) => items.map((item) => item.id);
 
 describe("collapseTurns", () => {
+  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", "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(expanded.tail).toEqual(items);
+    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", "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).turnsByHostId.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 history row renders again only when its item changes, so a prompt that is already retained
+  // when its turn closes needs its row revised to show the summary line.
+  it("reports the hosts whose summary line appeared, changed or went away", () => {
+    const open = collapse([user("u1"), shell("c1"), reply("r1"), user("u2"), shell("c2")], {
+      isLatestTurnOpen: true,
+    });
+    expect([...open.updatedHostIds]).toEqual(["u1"]);
+    const closed = collapse(
+      [user("u1"), shell("c1"), reply("r1"), user("u2"), shell("c2"), reply("r2")],
+      {
+        previousTurnsByHostId: open.turnsByHostId,
+      },
+    );
+    expect([...closed.updatedHostIds]).toEqual(["u2"]);
+    const unchanged = collapse(
+      [user("u1"), shell("c1"), reply("r1"), user("u2"), shell("c2"), reply("r2")],
+      {
+        previousTurnsByHostId: closed.turnsByHostId,
+      },
+    );
+    expect(unchanged.updatedHostIds.size).toBe(0);
+    const moreWork = collapse(
+      [user("u1"), shell("c1"), reply("r1"), user("u2"), shell("c2"), shell("c3"), reply("r2")],
+      { previousTurnsByHostId: unchanged.turnsByHostId },
+    );
+    expect([...moreWork.updatedHostIds]).toEqual(["u2"]);
+    const rewound = collapse([user("u1"), shell("c1"), reply("r1")], {
+      previousTurnsByHostId: moreWork.turnsByHostId,
+    });
+    expect([...rewound.updatedHostIds]).toEqual(["u2"]);
+  });
+  it("maps hidden rows only while their 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")], {
+      expandedHostIds: new Set(["u1"]),
+    });
+    expect(expanded.hostIdByHiddenRowId.size).toBe(0);
+  });
+  it("keeps lifecycle events and compaction recognizable beside a semantic action summary", () => {
+    const create = shell("create");
+    if (create.payload.source !== "agent") throw new Error("Expected agent tool");
+    create.payload.data.name = "mcp__paseo__create_agent";
+    create.payload.data.detail = { type: "unknown", input: { title: "Side fix" }, output: null };
+    const finished = shell("finished");
+    if (finished.payload.source !== "agent") throw new Error("Expected agent tool");
+    finished.payload.data.name = "agent_notification";
+    finished.payload.data.agentMessage = {
+      event: "finished",
+      sender: { id: "worker", title: "PR helper" },
+      text: "Finished",
+    };
+    const items: StreamItem[] = [
+      user("u1"),
+      create,
+      finished,
+      {
+        kind: "compaction",
+        id: "compaction",
+        timestamp: at,
+        status: "completed",
+      } satisfies StreamItem,
+      shell("bash"),
+      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({
+      commandCount: 1,
+      otherToolCount: 0,
+      paseoActions: { "Created agent": 1 },
+    });
+  });
+
   it("folds a finished turn's work into its user message and keeps the reply", () => {
     const result = collapse([
       user("u1"),
@@ -63,7 +191,6 @@ describe("collapseTurns", () => {
       hostId: "u1",
       expanded: false,
       summary: {
-        messageCount: 1,
         tools: expect.objectContaining({ commandCount: 2 }),
       },
     });
@@ -121,6 +248,34 @@ describe("collapseTurns", () => {
     expect(result.turnsByHostId.size).toBe(0);
   });
 
+  it("keeps a completed response folded when a promptless canonical turn starts", () => {
+    const first = [user("u1"), shell("c1"), reply("r1")].map((item) =>
+      Object.assign(item, { turnId: "first" }),
+    );
+    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);
+  });
+
+  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(result.hostIdByFoldedMessageId.has("steer")).toBe(false);
+  });
+
+  it("reveals every raw call inside an expanded turn", () => {
+    const calls = [shell("one"), shell("two")];
+    const result = collapse([user("prompt"), calls[0]!, reply("done")], {
+      expandedHostIds: new Set(["prompt"]),
+      getGroupedCalls: (id) => (id === "one" ? calls : undefined),
+    });
+    expect(ids(result.tail)).toEqual(["prompt", "one", "two", "done"]);
+    expect([...result.nestedItemIds]).toEqual(["one", "two"]);
+  });
+
   it("counts every call a tool-call group row stands for", () => {
     const group = [shell("c1"), shell("c2"), shell("c3")];
     const result = collapse([user("u1"), group[0]!, reply("final")], {
diff --git a/packages/app/src/agent-stream/turn-collapse/model.ts b/packages/app/src/agent-stream/turn-collapse/model.ts
index d9f532ad73..0821c74401 100644
--- a/packages/app/src/agent-stream/turn-collapse/model.ts
+++ b/packages/app/src/agent-stream/turn-collapse/model.ts
@@ -1,13 +1,18 @@
-import { getStreamItemMessageId, type StreamItem, type ToolCallItem } from "@/types/stream";
+import { isTurnBoundary, isTurnTrigger } from "../turn-membership";
+import {
+  getStreamItemMessageId,
+  type StreamItem,
+  type ThoughtItem,
+  type ToolCallItem,
+} from "@/types/stream";
 import { summarizeToolCalls, type OverviewSummary } from "@/tool-calls/detail-level/overview/model";
 
 export interface TurnSummary {
-  messageCount: number;
   tools: OverviewSummary;
 }
 
 export interface CollapsedTurn {
-  /** The user message the turn answers. Its row carries the turn's summary line. */
+  /** The input or first loaded row that carries the turn's summary line. */
   hostId: string;
   expanded: boolean;
   summary: TurnSummary;
@@ -20,6 +25,13 @@ export interface TurnCollapse {
   nestedItemIds: ReadonlySet<string>;
   /** 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>;
+  /**
+   * Hosts whose summary line appeared, changed or went away since `previousTurnsByHostId`. A
+   * history row renders again only when its item changes, so these rows are revised.
+   */
+  updatedHostIds: ReadonlySet<string>;
 }
 
 export interface CollapseTurnsInput {
@@ -28,7 +40,9 @@ export interface CollapseTurnsInput {
   isLatestTurnOpen: boolean;
   expandedHostIds: ReadonlySet<string>;
   /** The calls a tool-call group row stands for; undefined for a single call. */
-  getGroupedCalls: (itemId: string) => readonly ToolCallItem[] | undefined;
+  getGroupedCalls: (itemId: string) => readonly (ToolCallItem | ThoughtItem)[] | undefined;
+  /** The previous fold of the same history, the baseline for `updatedHostIds`. */
+  previousTurnsByHostId: ReadonlyMap<string, CollapsedTurn>;
 }
 
 const EMPTY_TURNS: ReadonlyMap<string, CollapsedTurn> = new Map();
@@ -39,22 +53,72 @@ function summarizeTurn(
   items: readonly StreamItem[],
   getGroupedCalls: CollapseTurnsInput["getGroupedCalls"],
 ): TurnSummary {
-  const calls: ToolCallItem[] = [];
-  let messageCount = 0;
+  const calls: (ToolCallItem | ThoughtItem)[] = [];
   for (const item of items) {
-    if (item.kind === "assistant_message") messageCount += 1;
-    else if (item.kind === "tool_call") calls.push(...(getGroupedCalls(item.id) ?? [item]));
+    if ((item.kind === "tool_call" || item.kind === "thought") && !isTurnTrigger(item))
+      calls.push(...(getGroupedCalls(item.id) ?? [item]));
   }
-  return { messageCount, tools: summarizeToolCalls(calls) };
+  return { tools: summarizeToolCalls(calls) };
 }
 
 function hasWork(summary: TurnSummary): boolean {
-  return summary.messageCount > 0 || Object.values(summary.tools).some((count) => count > 0);
+  const { paseoActions, thoughtCount: _thoughtCount, ...counts } = summary.tools;
+  return Object.keys(paseoActions).length > 0 || Object.values(counts).some((count) => count > 0);
 }
 
-function findLastAssistantIndex(tail: StreamItem[], start: number, end: number): number {
+function isSameTurn(a: CollapsedTurn, b: CollapsedTurn): boolean {
+  const { paseoActions: actionsA, ...countsA } = a.summary.tools;
+  const { paseoActions: actionsB, ...countsB } = b.summary.tools;
+  return (
+    a.expanded === b.expanded &&
+    hasSameCounts(countsA, countsB) &&
+    hasSameCounts(actionsA, actionsB)
+  );
+}
+
+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 findUpdatedHosts(
+  previous: ReadonlyMap<string, CollapsedTurn>,
+  next: ReadonlyMap<string, CollapsedTurn>,
+): ReadonlySet<string> {
+  const updated = new Set<string>();
+  for (const [hostId, turn] of next) {
+    const before = previous.get(hostId);
+    if (!before || !isSameTurn(before, turn)) updated.add(hostId);
+  }
+  for (const hostId of previous.keys()) {
+    if (!next.has(hostId)) updated.add(hostId);
+  }
+  return updated.size === 0 ? EMPTY_IDS : updated;
+}
+
+function staysVisibleWhenCollapsed(item: StreamItem): boolean {
+  return isTurnTrigger(item) || item.kind === "compaction";
+}
+
+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;
 }
@@ -63,7 +127,7 @@ function findLastAssistantIndex(tail: StreamItem[], start: number, end: number):
  * 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. Thoughts fold with the turn but are not counted.
+ * before its reply. Reasoning is revealed only when the turn opens.
  */
 export function collapseTurns(input: CollapseTurnsInput): TurnCollapse {
   const { tail } = input;
@@ -71,52 +135,81 @@ export function collapseTurns(input: CollapseTurnsInput): TurnCollapse {
   const turnsByHostId = new Map<string, CollapsedTurn>();
   const nestedItemIds = new Set<string>();
   const hostIdByFoldedMessageId = new Map<string, string>();
+  const hostIdByHiddenRowId = new Map<string, string>();
 
   let runStart = 0;
   const flushRun = (runEnd: number) => {
     const host = tail[runStart - 1];
     const isClosed = runEnd < tail.length || !input.isLatestTurnOpen;
-    const replyIndex = findLastAssistantIndex(tail, runStart, runEnd);
-    if (host?.kind !== "user_message" || !isClosed || replyIndex <= runStart) {
+    const replyIndex = findLastReplyIndex(tail, runStart, runEnd);
+    if (
+      !host ||
+      (host.kind !== "user_message" && host.kind !== "tool_call") ||
+      !isClosed ||
+      replyIndex <= runStart
+    ) {
       output.push(...tail.slice(runStart, runEnd));
       return;
     }
     const folded = tail.slice(runStart, replyIndex);
     const summary = summarizeTurn(folded, input.getGroupedCalls);
-    if (!hasWork(summary)) {
+    if (!hasWork(summary) && !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 });
-    for (const item of folded) {
+    const revealed = expanded
+      ? folded.flatMap<StreamItem>((item) =>
+          item.kind === "tool_call" || item.kind === "thought"
+            ? [...(input.getGroupedCalls(item.id) ?? [item])]
+            : [item],
+        )
+      : folded;
+    for (const item of revealed) {
+      if (staysVisibleWhenCollapsed(item)) continue;
       hostIdByFoldedMessageId.set(getStreamItemMessageId(item), host.id);
       if (expanded) nestedItemIds.add(item.id);
+      else hostIdByHiddenRowId.set(item.id, host.id);
     }
-    if (expanded) output.push(...folded);
+    output.push(
+      ...(expanded ? revealed : folded.filter((item) => staysVisibleWhenCollapsed(item))),
+    );
     output.push(...tail.slice(replyIndex, runEnd));
   };
 
   for (let index = 0; index < tail.length; index += 1) {
-    if (tail[index]?.kind !== "user_message") continue;
+    if (
+      !(index === 0 && isTurnTrigger(tail[index]!)) &&
+      !isTurnBoundary(tail[index - 1] ?? null, tail[index] ?? null)
+    )
+      continue;
     flushRun(index);
     output.push(tail[index]!);
     runStart = index + 1;
   }
   flushRun(tail.length);
 
+  const updatedHostIds = findUpdatedHosts(input.previousTurnsByHostId, turnsByHostId);
   if (turnsByHostId.size === 0) {
     return {
       tail,
       turnsByHostId: EMPTY_TURNS,
       nestedItemIds: EMPTY_IDS,
       hostIdByFoldedMessageId: EMPTY_HOSTS,
+      hostIdByHiddenRowId: EMPTY_HOSTS,
+      updatedHostIds,
     };
   }
   return {
-    tail: output.length === tail.length ? tail : output,
+    tail:
+      output.length === tail.length && output.every((item, index) => item === tail[index])
+        ? tail
+        : output,
     turnsByHostId,
     nestedItemIds,
     hostIdByFoldedMessageId,
+    hostIdByHiddenRowId,
+    updatedHostIds,
   };
 }
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 9f73f1ac22..22660b4606 100644
--- a/packages/app/src/agent-stream/turn-collapse/summary-line.tsx
+++ b/packages/app/src/agent-stream/turn-collapse/summary-line.tsx
@@ -1,6 +1,7 @@
-import { memo, useCallback, useMemo } from "react";
+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";
@@ -17,22 +18,11 @@ export const TurnSummaryLine = memo(function TurnSummaryLine({
   onExpandedChange: (hostId: string, expanded: boolean) => void;
 }) {
   const { t } = useTranslation();
-  const { messageCount, tools } = turn.summary;
-  const messageParts = useMemo(
-    () =>
-      messageCount > 0
-        ? [
-            t(`turnSummary.messages.${messageCount === 1 ? "one" : "other"}`, {
-              count: messageCount,
-            }),
-          ]
-        : [],
-    [messageCount, t],
-  );
-  const label = useOverviewSummaryLabel(tools, messageParts);
+  const label = useOverviewSummaryLabel(turn.summary.tools) || t("turnSummary.details");
+  const hold = useDisclosureHold();
   const toggle = useCallback(
-    () => onExpandedChange(turn.hostId, !turn.expanded),
-    [onExpandedChange, turn.expanded, turn.hostId],
+    () => hold(() => onExpandedChange(turn.hostId, !turn.expanded)),
+    [hold, onExpandedChange, turn.expanded, turn.hostId],
   );
 
   return (
diff --git a/packages/app/src/agent-stream/turn-footer.tsx b/packages/app/src/agent-stream/turn-footer.tsx
index acbd920b81..08fceb4005 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: {
@@ -197,7 +201,7 @@ function CompletedTurnFooter({
   return (
     <View style={stylesheet.turnFooterSlot}>
       <AssistantTurnFooter
-        getContent={getContent}
+        getContent={items[startIndex]?.kind === "assistant_message" ? getContent : undefined}
         completedAt={timing?.completedAt}
         durationMs={timing?.durationMs}
         onFork={boundary && onForkAssistantTurn ? handleFork : undefined}
@@ -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,
+    height: 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/turn-membership.test.ts b/packages/app/src/agent-stream/turn-membership.test.ts
index 4483e4e1a7..029ebd83f8 100644
--- a/packages/app/src/agent-stream/turn-membership.test.ts
+++ b/packages/app/src/agent-stream/turn-membership.test.ts
@@ -53,7 +53,7 @@ function layoutFor(items: StreamItem[], isTurnActive: boolean) {
       isTurnActive,
       history: model.segments.historyMounted,
       liveHead: model.segments.liveHead,
-      timingByAssistantId: model.turnTiming.byAssistantId,
+      timingByItemId: model.turnTiming.byItemId,
     }),
   };
 }
@@ -67,6 +67,24 @@ function completedFooterIds(layout: ReturnType<typeof layoutFor>["layout"]): str
 }
 
 describe("canonical turn membership", () => {
+  it("uses trigger fallback for missing IDs without pretending to recover batching", () => {
+    const previous = assistant("reply", 1, "first");
+    const trigger = runningTool("heartbeat", 2, "first");
+    if (trigger.kind !== "tool_call" || trigger.payload.source !== "agent")
+      throw new Error("Expected agent tool");
+    trigger.payload.data.name = "heartbeat";
+    expect(continuesTurn(previous, trigger)).toBe(true);
+    delete trigger.turnId;
+    expect(continuesTurn(previous, trigger)).toBe(false);
+    trigger.payload.data.name = "agent_message";
+    trigger.payload.data.agentMessage = {
+      event: "finished",
+      sender: { id: "worker" },
+      text: "Done",
+    };
+    expect(continuesTurn(previous, trigger)).toBe(false);
+  });
+
   it("stops tagged traversal at every mismatching turn ID", () => {
     expect(continuesTurn(assistant("first", 1, "turn-1"), runningTool("next", 2, "turn-2"))).toBe(
       false,
@@ -76,7 +94,7 @@ describe("canonical turn membership", () => {
     );
   });
 
-  it("renders adjacent turns without visible prompts as one response", () => {
+  it("renders a separate footer for each canonical turn without visible prompts", () => {
     const items = [
       user("prompt", 1, "turn-1"),
       assistant("first reply", 2, "turn-1"),
@@ -88,7 +106,11 @@ describe("canonical turn membership", () => {
 
     const completed = layoutFor(items, false);
 
-    expect(completedFooterIds(completed.layout)).toEqual(["heartbeat-2-reply"]);
+    expect(completedFooterIds(completed.layout)).toEqual([
+      "first reply",
+      "heartbeat-1-reply",
+      "heartbeat-2-reply",
+    ]);
     expect(completed.layout.auxiliaryTurnFooter?.timing).toEqual({
       completedAt: at(6),
       durationMs: null,
@@ -123,7 +145,7 @@ describe("canonical turn membership", () => {
     const completedItems = [...build(turnId), assistant("done", 9, turnId)];
     const completed = layoutFor(completedItems, false);
     expect(completedFooterIds(completed.layout)).toEqual(["done"]);
-    expect(completed.model.turnTiming.byAssistantId.get("done")).toMatchObject({
+    expect(completed.model.turnTiming.byItemId.get("done")).toMatchObject({
       completedAt: at(9),
       durationMs: 8000,
     });
diff --git a/packages/app/src/agent-stream/turn-membership.ts b/packages/app/src/agent-stream/turn-membership.ts
index 414d583305..9650c12ff1 100644
--- a/packages/app/src/agent-stream/turn-membership.ts
+++ b/packages/app/src/agent-stream/turn-membership.ts
@@ -1,24 +1,21 @@
+import { continuesTimelineTurn, isTimelineTurnTrigger } from "@getpaseo/protocol/timeline-turn";
 import type { StreamItem } from "@/types/stream";
 
 /**
  * Canonical turn IDs take precedence. Timelines without them retain the legacy
- * user-message boundary rule so old daemons and persisted rows need no rewrite.
+ * trigger boundary rule; missing IDs cannot reconstruct historical batching.
  */
 export function continuesTurn(previous: StreamItem | null, next: StreamItem | null): boolean {
   if (!previous || !next) return false;
-  if (previous.turnId !== undefined && next.turnId !== undefined) {
-    return previous.turnId === next.turnId;
-  }
-  return next.kind !== "user_message";
+  return continuesTimelineTurn(previous.turnId, next.turnId, isTurnTrigger(next));
 }
 
 /**
- * A visible response can span multiple canonical turns when their prompts are
- * system-injected and therefore absent from the Paseo timeline.
+ * Every canonical turn owns its response, including system-triggered runs.
  */
 export function continuesResponse(previous: StreamItem | null, next: StreamItem | null): boolean {
   if (!previous || !next) return false;
-  return continuesTurn(previous, next) || next.kind !== "user_message";
+  return continuesTurn(previous, next);
 }
 
 export function isTurnBoundary(previous: StreamItem | null, next: StreamItem | null): boolean {
@@ -37,3 +34,12 @@ export function startsNewTurn(item: StreamItem, previous: StreamItem | null): bo
 export function belongsToTurn(item: StreamItem, turnId: string | null): boolean {
   return turnId !== null && item.turnId === turnId;
 }
+
+/** Inputs that start a turn when older history has no canonical turn IDs. */
+export function isTurnTrigger(item: StreamItem): boolean {
+  return isTimelineTurnTrigger(
+    item.kind === "tool_call" && item.payload.source === "agent"
+      ? { type: item.kind, ...item.payload.data }
+      : { type: item.kind },
+  );
+}
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 67e08a6f82..ab9d3b8258 100644
--- a/packages/app/src/agent-stream/view.tsx
+++ b/packages/app/src/agent-stream/view.tsx
@@ -61,6 +61,11 @@ import { returnToTimelineTail } from "./timeline-tail-navigation";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import { ToolCallDetailsContent } from "@/components/tool-call-details";
 import { QuestionFormCard } from "@/components/question-form-card";
+import {
+  ToolCallExpansionContext,
+  useAgentToolCallExpansion,
+  useExpandedToolCallGroups,
+} from "@/tool-calls/expansion-context";
 import { ToolCallSheetProvider } from "@/components/tool-call-sheet";
 import { createStreamPresentation } from "./presentation";
 import { OverviewToolCallGroupView } from "@/tool-calls/detail-level/overview/view";
@@ -69,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";
@@ -90,6 +97,7 @@ import {
 import { createAssistantImageOccurrenceKey } from "@/assistant-image/acquisition-cache";
 import { AssistantSelectionCopySurface } from "@/assistant-selection-copy/surface";
 import { AssistantFileLinkResolverProvider, createInlinePathOpener } from "@/assistant-file-links";
+import { useOpenOutsideWorkspaceFolder } from "@/workspace/open-in-file-manager/outside-folder";
 import {
   createWorkspaceFileTabTarget,
   type WorkspaceFileLocation,
@@ -224,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;
@@ -318,6 +291,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(
     {
@@ -359,13 +373,12 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
         }),
       [isMobile],
     );
-    const [isNearBottom, setIsNearBottom] = useState(true);
+    const nearBottom = useNearBottom(agentId);
     const [expandedInlineToolCallIds, setExpandedInlineToolCallIds] = useState<Set<string>>(
       new Set(),
     );
-    const [expandedToolCallGroupIds, setExpandedToolCallGroupIds] = useState<Set<string>>(
-      new Set(),
-    );
+    const toolCallExpansion = useAgentToolCallExpansion(agentId);
+    const expandedToolCallGroups = useExpandedToolCallGroups(toolCallExpansion);
     const [expandedTurnHostIds, setExpandedTurnHostIds] = useState<ReadonlySet<string>>(new Set());
 
     // Get serverId (fallback to agent's serverId if not provided)
@@ -417,22 +430,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());
-      setExpandedToolCallGroupIds(new Set());
-      setExpandedTurnHostIds(new Set());
-    }, [agentId]);
 
     const isActive = useRetainedPanelActive();
     const openInlineFile = useStableEvent(
@@ -459,20 +456,23 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
         view: "files",
       });
     });
+    const openInlineOutsideDirectory = useOpenOutsideWorkspaceFolder(resolvedServerId);
     const inlinePathOpener = useMemo(
       () =>
         createInlinePathOpener({
           workspaceRoot,
+          resolveRelativeFiles: true,
           client,
           openFile: openInlineFile,
           openDirectory: openInlineDirectory,
+          openOutsideDirectory: openInlineOutsideDirectory,
         }),
-      [workspaceRoot, client, openInlineFile, openInlineDirectory],
+      [workspaceRoot, client, openInlineFile, openInlineDirectory, openInlineOutsideDirectory],
     );
     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);
@@ -524,8 +524,10 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           head: effectiveStreamHead ?? EMPTY_STREAM_HEAD,
           transform: transformTimelineItem,
           display: chatDisplay,
+          autoExpandReasoning,
           expandedTurnHostIds,
           isTurnActive,
+          activeTurnId: effectiveTurnPresentation.turnId,
         }),
       [
         presentStream,
@@ -533,8 +535,10 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
         effectiveStreamHead,
         transformTimelineItem,
         chatDisplay,
+        autoExpandReasoning,
         expandedTurnHostIds,
         isTurnActive,
+        effectiveTurnPresentation.turnId,
       ],
     );
     const {
@@ -543,7 +547,6 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       revealLoadedHistory,
       loadOlder,
     } = useStreamHistoryWindow({
-      agentId,
       items: presentation.tail,
       loadRemoteOlder,
     });
@@ -576,12 +579,12 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           isTurnActive,
           history: baseRenderModel.history,
           liveHead: baseRenderModel.segments.liveHead,
-          timingByAssistantId: baseRenderModel.turnTiming.byAssistantId,
+          timingByItemId: baseRenderModel.turnTiming.byItemId,
         }),
       [
         baseRenderModel.history,
         baseRenderModel.segments.liveHead,
-        baseRenderModel.turnTiming.byAssistantId,
+        baseRenderModel.turnTiming.byItemId,
         isTurnActive,
         streamRenderStrategy,
       ],
@@ -664,9 +667,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);
@@ -701,17 +703,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       return getCollapsedTurn(layoutItem.item.id)?.expanded ? "openedHost" : "none";
     });
 
-    const setToolCallGroupExpanded = useCallback((groupId: string, expanded: boolean) => {
-      setExpandedToolCallGroupIds((previous) => {
-        const next = new Set(previous);
-        if (expanded) {
-          next.add(groupId);
-        } else {
-          next.delete(groupId);
-        }
-        return next;
-      });
-    }, []);
+    const setToolCallGroupExpanded = toolCallExpansion.setGroupExpanded;
 
     const renderUserMessageItem = useCallback(
       (layoutItem: StreamLayoutItem, item: Extract<StreamItem, { kind: "user_message" }>) => {
@@ -722,6 +714,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
             agentId={agentId}
             messageId={item.messageId}
             message={item.text}
+            sender={item.sender}
             images={item.images}
             attachments={item.attachments}
             timestamp={item.timestamp.getTime()}
@@ -807,7 +800,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       (
         item: Extract<StreamItem, { kind: "tool_call" }>,
         isLastInSequence: boolean,
-        maxDetailHeight?: number,
+        options: { maxDetailHeight?: number; standalone?: boolean } = {},
       ) => {
         const { payload } = item;
 
@@ -839,7 +832,8 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
               agentMessage={data.agentMessage}
               isLastInSequence={isLastInSequence}
               onOpenFilePath={handleToolCallOpenFile}
-              maxDetailHeight={maxDetailHeight}
+              standalone={options.standalone}
+              maxDetailHeight={options.maxDetailHeight}
             />
           );
         }
@@ -855,7 +849,8 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
             status={data.status}
             isLastInSequence={isLastInSequence}
             onOpenFilePath={handleToolCallOpenFile}
-            maxDetailHeight={maxDetailHeight}
+            standalone={options.standalone}
+            maxDetailHeight={options.maxDetailHeight}
           />
         );
       },
@@ -868,12 +863,17 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       presentation.groupsByHostId.get(hostId),
     );
     const renderToolCallItem = useCallback(
-      (layoutItem: StreamLayoutItem, item: Extract<StreamItem, { kind: "tool_call" }>) => {
+      (
+        layoutItem: StreamLayoutItem,
+        item: Extract<StreamItem, { kind: "tool_call" | "thought" }>,
+      ) => {
         const group = getToolCallGroup(item.id);
         if (!group) {
-          return renderSingleToolCallItem(item, layoutItem.isLastInToolSequence);
+          return item.kind === "thought"
+            ? renderThoughtItem(layoutItem, item)
+            : renderSingleToolCallItem(item, layoutItem.isLastInToolSequence);
         }
-        const expanded = expandedToolCallGroupIds.has(group.run.id);
+        const expanded = expandedToolCallGroups.has(group.run.id);
         return (
           <OverviewToolCallGroupView
             group={group}
@@ -884,10 +884,23 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
             {expanded
               ? group.run.calls.map((call, index) => (
                   <React.Fragment key={call.id}>
-                    {renderSingleToolCallItem(
-                      call,
-                      index === group.run.calls.length - 1,
-                      GROUPED_TOOL_CALL_DETAIL_MAX_HEIGHT,
+                    {call.kind === "thought" ? (
+                      // Reasoning is grouped only while Expand thinking is off, so an opened
+                      // group shows each thought as a closed row like any other call.
+                      <ThoughtSlot
+                        itemId={call.id}
+                        text={call.text}
+                        status={call.status}
+                        isLastInSequence={index === group.run.calls.length - 1}
+                        defaultExpanded={false}
+                        standalone={false}
+                        onInlineDetailsExpandedChangeByItemId={setInlineDetailsExpanded}
+                      />
+                    ) : (
+                      renderSingleToolCallItem(call, index === group.run.calls.length - 1, {
+                        maxDetailHeight: GROUPED_TOOL_CALL_DETAIL_MAX_HEIGHT,
+                        standalone: false,
+                      })
                     )}
                   </React.Fragment>
                 ))
@@ -896,7 +909,9 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
         );
       },
       [
-        expandedToolCallGroupIds,
+        expandedToolCallGroups,
+        renderThoughtItem,
+        setInlineDetailsExpanded,
         getToolCallGroup,
         renderSingleToolCallItem,
         setToolCallGroupExpanded,
@@ -904,8 +919,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);
@@ -914,10 +928,20 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
             return renderAssistantMessageItem(layoutItem, item);
 
           case "thought":
-            return renderThoughtItem(layoutItem, item);
+            return renderToolCallItem(layoutItem, item);
 
           case "tool_call":
-            return renderToolCallItem(layoutItem, item);
+            return (
+              <>
+                {renderToolCallItem(layoutItem, item)}
+                {getCollapsedTurn(item.id) ? (
+                  <TurnSummaryLine
+                    turn={getCollapsedTurn(item.id)!}
+                    onExpandedChange={setTurnExpanded}
+                  />
+                ) : null}
+              </>
+            );
 
           case "notification":
             return <Notification level={item.level} message={item.message} />;
@@ -947,17 +971,18 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
         agentId,
         renderUserMessageItem,
         renderAssistantMessageItem,
-        renderThoughtItem,
         renderToolCallItem,
+        getCollapsedTurn,
+        setTurnExpanded,
         resolvedServerId,
       ],
     );
 
     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,
@@ -1026,13 +1051,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({
@@ -1075,6 +1094,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           item,
           layoutItemById: layoutHistoryItemById,
           renderStreamItem,
+          viewportRef,
         }),
       [layoutHistoryItemById, renderStreamItem],
     );
@@ -1096,6 +1116,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           item,
           layoutItemById: layoutLiveHeadItemById,
           renderStreamItem,
+          viewportRef,
         }),
     );
     const renderLiveAuxiliary = useCallback<StreamSegmentRenderers["renderLiveAuxiliary"]>(() => {
@@ -1130,24 +1151,31 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
     const streamScrollEnabled =
       !streamRenderStrategy.shouldDisableParentScrollOnInlineDetailsExpansion() ||
       expandedInlineToolCallIds.size === 0;
-    const { nestedItemIds } = presentation.turns;
+    const { nestedItemIds, updatedHostIds: updatedTurnHostIds } = presentation.turns;
     const historyRowRevision = useMemo(
       () => ({
-        contentById: presentation.historyGroupUpdatesByHostId,
-        displayStateById: {
+        contentById: {
           has: (id: string) =>
-            expandedToolCallGroupIds.has(id) ||
+            presentation.historyGroupUpdatesByHostId.has(id) || updatedTurnHostIds.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,
       }),
       [
-        expandedToolCallGroupIds,
+        expandedToolCallGroups,
+        getToolCallGroup,
         expandedTurnHostIds,
         isMobile,
         nestedItemIds,
         presentation.historyGroupUpdatesByHostId,
+        updatedTurnHostIds,
       ],
     );
 
@@ -1168,50 +1196,44 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
         <ToolCallSheetProvider>
           <AssistantSelectionCopySurface style={stylesheet.container}>
             <MessageOuterSpacingProvider disableOuterSpacing>
-              {streamRenderStrategy.render({
-                agentId,
-                segments: renderModel.segments,
-                historyRowRevision,
-                liveHeadRowRevision: expandedToolCallGroupIds,
-                boundary,
-                renderers,
-                listEmptyComponent,
-                viewportRef,
-                routeBottomAnchorRequest,
-                isAuthoritativeHistoryReady,
-                onNearBottomChange: setIsNearBottom,
-                onReadingPositionChange: handleReadingPositionChange,
-                onNearHistoryStart: loadOlder,
-                isLoadingOlderHistory: isLoadingOlder,
-                hasOlderHistory: hasOlder,
-                olderHistoryProgressKey: progressKey,
-                scrollEnabled: streamScrollEnabled,
-                listStyle: stylesheet.list,
-                baseListContentContainerStyle: stylesheet.listContentContainer,
-                forwardListContentContainerStyle: stylesheet.forwardListContentContainer,
-                contentMaxWidth,
-              })}
+              <ToolCallExpansionContext.Provider value={toolCallExpansion}>
+                {streamRenderStrategy.render({
+                  readingRowReplacements: presentation.readingRowReplacements,
+                  agentId,
+                  segments: renderModel.segments,
+                  historyRowRevision,
+                  liveHeadRowRevision: expandedToolCallGroups,
+                  boundary,
+                  renderers,
+                  listEmptyComponent,
+                  viewportRef,
+                  routeBottomAnchorRequest,
+                  isAuthoritativeHistoryReady,
+                  onNearBottomChange: nearBottom.set,
+                  onReadingPositionChange: handleReadingPositionChange,
+                  onNearHistoryStart: loadOlder,
+                  isLoadingOlderHistory: isLoadingOlder,
+                  hasOlderHistory: hasOlder,
+                  olderHistoryProgressKey: progressKey,
+                  scrollEnabled: streamScrollEnabled,
+                  listStyle: stylesheet.list,
+                  baseListContentContainerStyle: stylesheet.listContentContainer,
+                  forwardListContentContainerStyle: stylesheet.forwardListContentContainer,
+                  contentMaxWidth,
+                })}
+              </ToolCallExpansionContext.Provider>
             </MessageOuterSpacingProvider>
             <ChatOutlineRail
               prompts={chatOutline.prompts}
               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>
@@ -1363,6 +1385,7 @@ interface ThoughtSlotProps {
   status: Extract<StreamItem, { kind: "thought" }>["status"];
   isLastInSequence: boolean;
   defaultExpanded: boolean;
+  standalone?: boolean;
 }
 
 // Reasoning text is paced the same way assistant text is; see @/hooks/use-revealed-text.
@@ -1373,6 +1396,7 @@ function ThoughtSlot({
   status,
   isLastInSequence,
   defaultExpanded,
+  standalone,
 }: ThoughtSlotProps) {
   const revealedText = useRevealedText(text, status === "ready" ? "complete" : "streaming");
   return (
@@ -1384,6 +1408,7 @@ function ThoughtSlot({
       status={status === "ready" ? "completed" : "executing"}
       isLastInSequence={isLastInSequence}
       defaultExpanded={defaultExpanded}
+      standalone={standalone}
       forceInline={defaultExpanded}
     />
   );
@@ -1398,7 +1423,9 @@ function ToolCallSlot({
     (expanded: boolean) => onInlineDetailsExpandedChangeByItemId(itemId, expanded),
     [onInlineDetailsExpandedChangeByItemId, itemId],
   );
-  return <ToolCall {...rest} onInlineDetailsExpandedChange={handleExpandedChange} />;
+  return (
+    <ToolCall {...rest} itemId={itemId} onInlineDetailsExpandedChange={handleExpandedChange} />
+  );
 }
 
 const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
@@ -1743,10 +1770,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,
@@ -1861,12 +1884,11 @@ function StreamItemWrapper({ gapBelow, turnIndent, children }: StreamItemWrapper
   const gapStyle = useMemo(() => ({ paddingBottom: gapBelow }), [gapBelow]);
   switch (turnIndent) {
     case "none":
-      return <View style={wrapperStyle}>{children}</View>;
     case "openedHost":
       return (
         <View style={wrapperStyle}>
           {children}
-          <IndentRail style={gapStyle} />
+          {turnIndent === "openedHost" ? <IndentRail style={gapStyle} /> : null}
         </View>
       );
     case "nested":
diff --git a/packages/app/src/agent-stream/web-virtualization.test.ts b/packages/app/src/agent-stream/web-virtualization.test.ts
index 31107789e2..2d1f1b5b75 100644
--- a/packages/app/src/agent-stream/web-virtualization.test.ts
+++ b/packages/app/src/agent-stream/web-virtualization.test.ts
@@ -70,6 +70,17 @@ function indexEntries(items: StreamItem[]): IndexedStreamItem[] {
 }
 
 describe("findMountedWindowStart", () => {
+  it("mounts complete autonomous runs and keeps same-run steers together", () => {
+    const items = [
+      { ...userMessage("human", 1), turnId: "first" },
+      { ...assistantMessage("reply", 2), turnId: "first" },
+      { ...toolCall("wake", 3), turnId: "autonomous" },
+      { ...userMessage("steer", 4), turnId: "autonomous" },
+      { ...assistantMessage("done", 5), turnId: "autonomous" },
+    ];
+    expect(findMountedWindowStart({ items, minMountedCount: 1 })).toBe(2);
+  });
+
   it("keeps all items mounted when the chat is below the threshold", () => {
     const items = [userMessage("u1", 1), assistantMessage("a1", 2)];
 
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/assistant-file-links/path-open.test.ts b/packages/app/src/assistant-file-links/path-open.test.ts
index a046a598f6..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,13 +64,19 @@ 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);
     },
     openDirectory: (directory) => {
       opened.push(directory);
     },
+    openOutsideDirectory: (directory) => {
+      opened.push(directory);
+    },
   });
   const first = opener.open({ raw: "./first.md", path: "/repo/first.md" }, "preferred");
   await opener.open({ raw: "./second.md:2", path: "/repo/second.md", lineStart: 2 }, "preferred");
@@ -88,13 +94,19 @@ 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);
     },
     openDirectory: (directory) => {
       opened.push(directory);
     },
+    openOutsideDirectory: (directory) => {
+      opened.push(directory);
+    },
   });
   const pending = opener.open({ raw: "./docs", path: "/repo/docs" }, "preferred");
   opener.cancel();
@@ -102,3 +114,67 @@ it("ignores a pending probe when its view is left", async () => {
   await pending;
   expect(opened).toEqual([]);
 });
+
+it("sends folders outside the workspace away from the workspace Files panel", async () => {
+  const { createInlinePathOpener } = await import("./path-open");
+  const workspaceFolders: string[] = [];
+  const outsideFolders: string[] = [];
+  const opener = createInlinePathOpener({
+    workspaceRoot: "/Users/me/repo",
+    client: null,
+    openFile: () => {},
+    openDirectory: (directory) => {
+      workspaceFolders.push(directory);
+    },
+    openOutsideDirectory: (directory) => {
+      outsideFolders.push(directory);
+    },
+  });
+  for (const raw of ["~/Downloads/contracts/", "/tmp/reports/", "/Users/me/repo/docs/"]) {
+    await opener.open({ raw, path: raw }, "preferred");
+  }
+  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 b3d2178165..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;
@@ -14,12 +15,23 @@ interface PathOpenInput {
   client: { listDirectory(root: string, path: string): Promise<unknown> } | null;
 }
 
-type PathOpenTarget = { kind: "file" } | { kind: "directory"; directoryPath: string };
+type PathOpenTarget =
+  | { kind: "file" }
+  | { kind: "directory"; directoryPath: string }
+  | { kind: "outsideDirectory"; directoryPath: string };
+
+// Workspace paths arrive relative to the root; anything still absolute or
+// home-relative lives outside it, where the Files panel cannot list it.
+function isOutsideWorkspacePath(pathValue: string): boolean {
+  return isAbsolutePath(pathValue) || pathValue === "~" || pathValue.startsWith("~/");
+}
 
 /** Resolve workspace folders from filesystem facts, including names that contain dots. */
 export async function resolveInlinePathOpen(input: PathOpenInput): Promise<PathOpenTarget> {
   if (!input.file) {
-    return { kind: "directory", directoryPath: input.directory };
+    return isOutsideWorkspacePath(input.directory)
+      ? { kind: "outsideDirectory", directoryPath: input.directory }
+      : { kind: "directory", directoryPath: input.directory };
   }
   if (
     input.lineStart !== undefined ||
@@ -39,9 +51,14 @@ 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;
 }) {
   let generation = 0;
   return {
@@ -58,11 +75,24 @@ export function createInlinePathOpener(input: {
       if (ownGeneration !== generation) return;
       if (destination.kind === "directory") {
         input.openDirectory(destination.directoryPath);
+      } 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..7447b96225 100644
--- a/packages/app/src/changelog/internal/changelog-sheet.tsx
+++ b/packages/app/src/changelog/internal/changelog-sheet.tsx
@@ -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>
diff --git a/packages/app/src/command-center/command-center.tsx b/packages/app/src/command-center/command-center.tsx
index 7a44f8ccd9..1c20f0725d 100644
--- a/packages/app/src/command-center/command-center.tsx
+++ b/packages/app/src/command-center/command-center.tsx
@@ -1,8 +1,9 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
+import { Modal } from "@/components/ui/modal";
 import equal from "fast-deep-equal";
 import { recordRenderProfileReasons } from "@/utils/render-profiler";
 import {
   FlatList,
-  Modal,
   Pressable,
   Text,
   View,
@@ -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.test.tsx b/packages/app/src/components/adaptive-modal-sheet.test.tsx
new file mode 100644
index 0000000000..96e8fba9d5
--- /dev/null
+++ b/packages/app/src/components/adaptive-modal-sheet.test.tsx
@@ -0,0 +1,33 @@
+/**
+ * @vitest-environment jsdom
+ */
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { Text } from "react-native";
+import { SafeAreaInsetsContext, useSafeAreaInsets } from "react-native-safe-area-context";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { SheetBottomInset } from "./adaptive-modal-sheet";
+
+beforeEach(() => vi.stubGlobal("React", React));
+
+const SCREEN_INSETS = { top: 24, right: 0, bottom: 34, left: 0 };
+
+function BottomInsetProbe() {
+  return <Text testID="content-bottom-inset">{String(useSafeAreaInsets().bottom)}</Text>;
+}
+
+describe("SheetBottomInset", () => {
+  it("pads the bottom inset once and leaves none for its content", () => {
+    render(
+      <SafeAreaInsetsContext.Provider value={SCREEN_INSETS}>
+        <SheetBottomInset testID="sheet-body">
+          <BottomInsetProbe />
+        </SheetBottomInset>
+      </SafeAreaInsetsContext.Provider>,
+    );
+
+    expect(screen.getByTestId("sheet-body").style.paddingBottom).toBe("34px");
+    // Content that pads the inset itself, like the composer dock, must not pad it again.
+    expect(screen.getByTestId("content-bottom-inset").textContent).toBe("0");
+  });
+});
diff --git a/packages/app/src/components/adaptive-modal-sheet.tsx b/packages/app/src/components/adaptive-modal-sheet.tsx
index f487f07f07..7e28f3d81a 100644
--- a/packages/app/src/components/adaptive-modal-sheet.tsx
+++ b/packages/app/src/components/adaptive-modal-sheet.tsx
@@ -1,18 +1,19 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import type { ComponentProps, ReactNode } from "react";
 import { createPortal } from "react-dom";
 import { useTranslation } from "react-i18next";
 import { Keyboard, Pressable, Text, View } from "react-native";
-import type { DimensionValue, StyleProp, ViewStyle } 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, useGlobalOverlayLayer } from "../lib/overlay-root";
 import {
-  getOverlayRoot,
-  OverlayLayerProvider,
-  useGlobalWebOverlayLayer,
-  useWebOverlayRegistration,
-} from "../lib/overlay-root";
-import { BottomSheetHandle, type BottomSheetBackgroundProps } from "@gorhom/bottom-sheet";
+  BottomSheetHandle,
+  useBottomSheetGestureHandlers,
+  type BottomSheetBackgroundProps,
+} from "@gorhom/bottom-sheet";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
 import Animated from "react-native-reanimated";
 import { ArrowLeft, Search, X, type LucideIcon } from "lucide-react-native";
 import {
@@ -25,7 +26,7 @@ import { getCompactSheetSafeAreaPadding } from "@/components/adaptive-modal-shee
 import { ScrollView } from "@/components/ui/scroll-view";
 import { isWeb } from "@/constants/platform";
 import { useKeyboardVisibility } from "@/hooks/use-keyboard-visibility";
-import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { SafeAreaInsetsContext, useSafeAreaInsets } from "react-native-safe-area-context";
 import { AdaptiveTextInput } from "@/components/adaptive-text-input";
 export { AdaptiveTextInput, type AdaptiveTextInputProps } from "@/components/adaptive-text-input";
 
@@ -40,6 +41,9 @@ export const SHEET_HORIZONTAL_PADDING_SCALE = 6;
 // glyph should line up with the X must reach the same rail.
 export const SHEET_HEADER_CLOSE_PADDING_SCALE = 2;
 
+/** The one height a sheet takes when it shows a whole pane rather than sizing to its content. */
+export const FULL_SHEET_SNAP_POINTS = ["92%"];
+
 export interface SheetHeaderSearch {
   onChange: (value: string) => void;
   onFocus?: () => void;
@@ -91,7 +95,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,
@@ -132,6 +136,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",
@@ -222,6 +232,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) {
@@ -244,32 +276,55 @@ const ThemedBottomSheetHandle = withUnistyles(BottomSheetHandle, (theme) => ({
   indicatorStyle: { backgroundColor: theme.colors.palette.zinc[600] },
 }));
 
-const HANDLE_WITH_CONTENT_STYLE = { paddingHorizontal: 0, paddingBottom: 0 };
-
-/**
- * The compact sheet's drag handle: Gorhom's `handleComponent` for every bottom sheet. Children
- * join the handle, so a header passed here drags the sheet like the indicator does. That is how a
- * sheet whose content scrolls on its own keeps its header draggable without content panning.
- */
+/** The compact sheet's drag handle: Gorhom's `handleComponent` for every bottom sheet. */
 export function SheetHandle({
-  children,
   // Gorhom passes `indicatorStyle={undefined}`, which would override the themed indicator.
   indicatorStyle: _indicatorStyle,
   ...props
 }: ComponentProps<typeof BottomSheetHandle>) {
-  if (!children) return <ThemedBottomSheetHandle {...props} />;
-  // The children carry their own semantics; the handle's slider role would swallow them on web.
+  return <ThemedBottomSheetHandle {...props} />;
+}
+
+/**
+ * Content that drags the sheet the way its handle does. A sheet whose body scrolls on its own
+ * turns content panning off and wraps its header in this, so the header still pulls it down.
+ * Render it inside the sheet's content.
+ */
+export function SheetDragArea({ children }: { children: ReactNode }) {
+  const { handlePanGestureHandler } = useBottomSheetGestureHandlers();
+  const gesture = useMemo(
+    () =>
+      Gesture.Pan()
+        .shouldCancelWhenOutside(false)
+        .runOnJS(false)
+        .onStart(handlePanGestureHandler.handleOnStart)
+        .onChange(handlePanGestureHandler.handleOnChange)
+        .onEnd(handlePanGestureHandler.handleOnEnd)
+        .onFinalize(handlePanGestureHandler.handleOnFinalize),
+    [handlePanGestureHandler],
+  );
   return (
-    <ThemedBottomSheetHandle
-      {...props}
-      style={HANDLE_WITH_CONTENT_STYLE}
-      accessible={false}
-      accessibilityRole={null}
-      accessibilityLabel={null}
-      accessibilityHint={null}
-    >
-      {children}
-    </ThemedBottomSheetHandle>
+    <GestureDetector gesture={gesture}>
+      <View>{children}</View>
+    </GestureDetector>
+  );
+}
+
+/**
+ * A compact sheet's content area that reaches the bottom of the screen. It owns the system
+ * navigation inset: it pads it once and tells its content none is left, so content that pads the
+ * inset itself, like the composer dock, sits the same in a sheet as in a tab.
+ */
+export function SheetBottomInset({ style, children, ...props }: ViewProps) {
+  const insets = useSafeAreaInsets();
+  const contentInsets = useMemo(() => ({ ...insets, bottom: 0 }), [insets]);
+  const insetStyle = useMemo(() => [style, { paddingBottom: insets.bottom }], [style, insets]);
+  return (
+    <View {...props} style={insetStyle}>
+      <SafeAreaInsetsContext.Provider value={contentInsets}>
+        {children}
+      </SafeAreaInsetsContext.Provider>
+    </View>
   );
 }
 
@@ -462,8 +517,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;
@@ -488,6 +562,76 @@ export interface AdaptiveModalSheetProps {
   contextBridge?: ContextBridge | null;
 }
 
+/**
+ * The compact sheet's body. It renders on the far side of the sheet's portal so it reads the
+ * screen's bottom inset, not the one left where the sheet was opened: inside a sheet tab, none is.
+ */
+function CompactSheetBody({
+  header,
+  onClose,
+  testID,
+  footer,
+  isKeyboardVisible,
+  scrollable,
+  bodyStyle,
+  contentStyle,
+  children,
+}: {
+  header?: SheetHeader;
+  onClose: () => void;
+  testID?: string;
+  footer: ReactNode;
+  isKeyboardVisible: boolean;
+  scrollable: boolean;
+  bodyStyle?: StyleProp<ViewStyle>;
+  contentStyle?: StyleProp<ViewStyle>;
+  children: ReactNode;
+}) {
+  const insets = useSafeAreaInsets();
+  const { contentPaddingBottom = 0, footerPaddingBottom = 0 } = getCompactSheetSafeAreaPadding({
+    isCompact: true,
+    isKeyboardVisible,
+    hasFooter: Boolean(footer),
+    safeAreaBottom: insets.bottom,
+  });
+  // Safe-area clearance is a separate layer: it must not replace the caller's
+  // padding (including an explicit zero), and the footer owns it when present.
+  const bodyClearanceStyle = { paddingBottom: contentPaddingBottom };
+  const footerClearanceStyle = useMemo(
+    () => ({ paddingBottom: footerPaddingBottom }),
+    [footerPaddingBottom],
+  );
+  const footerView = useMemo(
+    () => (footer ? <View style={footerClearanceStyle}>{footer}</View> : null),
+    [footer, footerClearanceStyle],
+  );
+  return (
+    <SheetVisibleFrame footer={footerView}>
+      {header ? <SheetHeaderView header={header} onClose={onClose} testID={testID} /> : null}
+      <View style={[styles.compactStaticContent, bodyStyle]}>
+        {scrollable ? (
+          <ScrollView
+            style={styles.bottomSheetVisibleScroll}
+            contentContainerStyle={SCROLL_CONTENT_GROW}
+            keyboardShouldPersistTaps="handled"
+            showsVerticalScrollIndicator={false}
+          >
+            <View style={[styles.contentGrow, bodyClearanceStyle]}>
+              <SheetContent style={[styles.contentGrow, contentStyle]}>{children}</SheetContent>
+            </View>
+          </ScrollView>
+        ) : (
+          <View style={[styles.compactStaticContent, bodyClearanceStyle]}>
+            <SheetContent style={[styles.compactStaticContent, contentStyle]}>
+              {children}
+            </SheetContent>
+          </View>
+        )}
+      </View>
+    </SheetVisibleFrame>
+  );
+}
+
 export function AdaptiveModalSheet({
   header,
   visible,
@@ -508,34 +652,11 @@ export function AdaptiveModalSheet({
 }: AdaptiveModalSheetProps) {
   const { t } = useTranslation();
   const isMobile = useIsCompactFormFactor();
-  const insets = useSafeAreaInsets();
   const isKeyboardVisible = useKeyboardVisibility(visible);
   const resolvedSnapPoints = useMemo(() => snapPoints ?? ["65%", "90%"], [snapPoints]);
-  const compactSafeAreaPadding = useMemo(
-    () =>
-      getCompactSheetSafeAreaPadding({
-        isCompact: isMobile,
-        isKeyboardVisible,
-        hasFooter: Boolean(footer),
-        safeAreaBottom: insets.bottom,
-      }),
-    [footer, insets.bottom, isKeyboardVisible, isMobile],
-  );
-  // Safe-area clearance is a separate layer: it must not replace the caller's
-  // padding (including an explicit zero), and the footer owns it when present.
-  const bodyClearanceStyle = { paddingBottom: compactSafeAreaPadding.contentPaddingBottom ?? 0 };
-  const footerClearanceStyle = useMemo(
-    () => ({ paddingBottom: compactSafeAreaPadding.footerPaddingBottom ?? 0 }),
-    [compactSafeAreaPadding.footerPaddingBottom],
-  );
   const footerView = useMemo(
-    () =>
-      footer ? (
-        <View style={footerClearanceStyle}>
-          <View style={[styles.footer, footerContainerStyle]}>{footer}</View>
-        </View>
-      ) : null,
-    [footer, footerClearanceStyle, footerContainerStyle],
+    () => (footer ? <SheetFooter style={footerContainerStyle}>{footer}</SheetFooter> : null),
+    [footer, footerContainerStyle],
   );
   useEffect(() => {
     if (!isWeb && visible) {
@@ -552,7 +673,7 @@ export function AdaptiveModalSheet({
   });
   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?.();
@@ -563,6 +684,7 @@ export function AdaptiveModalSheet({
       styles.desktopCard,
       desktopHeight != null && { height: desktopHeight },
       desktopMaxWidth != null && { maxWidth: desktopMaxWidth },
+      isWeb && WEB_ENTER_STYLE,
     ],
     [desktopMaxWidth, desktopHeight],
   );
@@ -580,8 +702,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();
@@ -590,10 +712,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(() => {
@@ -614,32 +737,6 @@ export function AdaptiveModalSheet({
   }, [visible, isMobile, onDismiss, shouldRenderWeb]);
 
   if (isMobile) {
-    const sheetContent = (
-      <>
-        <SheetHeaderView header={header} onClose={onClose} testID={testID} />
-        <View style={[styles.compactStaticContent, bodyStyle]}>
-          {scrollable ? (
-            <ScrollView
-              style={styles.bottomSheetVisibleScroll}
-              contentContainerStyle={SCROLL_CONTENT_GROW}
-              keyboardShouldPersistTaps="handled"
-              showsVerticalScrollIndicator={false}
-            >
-              <View style={[styles.contentGrow, bodyClearanceStyle]}>
-                <SheetContent style={[styles.contentGrow, contentStyle]}>{children}</SheetContent>
-              </View>
-            </ScrollView>
-          ) : (
-            <View style={[styles.compactStaticContent, bodyClearanceStyle]}>
-              <SheetContent style={[styles.compactStaticContent, contentStyle]}>
-                {children}
-              </SheetContent>
-            </View>
-          )}
-        </View>
-      </>
-    );
-
     return (
       <IsolatedBottomSheetModal
         ref={sheetRef}
@@ -658,7 +755,20 @@ export function AdaptiveModalSheet({
         accessible={false}
         presentation={presentation}
       >
-        <SheetVisibleFrame footer={footerView}>{sheetContent}</SheetVisibleFrame>
+        <OverlayLayerProvider layer={modalLayer}>
+          <CompactSheetBody
+            header={header}
+            onClose={onClose}
+            testID={testID}
+            footer={footerView}
+            isKeyboardVisible={isKeyboardVisible}
+            scrollable={scrollable}
+            bodyStyle={bodyStyle}
+            contentStyle={contentStyle}
+          >
+            {children}
+          </CompactSheetBody>
+        </OverlayLayerProvider>
       </IsolatedBottomSheetModal>
     );
   }
@@ -667,7 +777,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
@@ -683,6 +793,15 @@ export function AdaptiveModalSheet({
         )}
       </View>
       {footerView}
+      {header ? null : (
+        <View style={styles.floatingClose}>
+          <SheetHeaderIconButton
+            icon={X}
+            accessibilityLabel={t("common.actions.close")}
+            onPress={onClose}
+          />
+        </View>
+      )}
     </OverlayLayerProvider>
   );
 
@@ -693,13 +812,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 a1cb5cf779..038e026c76 100644
--- a/packages/app/src/components/add-project-flow.tsx
+++ b/packages/app/src/components/add-project-flow.tsx
@@ -1,3 +1,6 @@
+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";
 import { router } from "expo-router";
@@ -22,14 +25,7 @@ import {
   type ComponentType,
   type RefObject,
 } from "react";
-import {
-  Modal,
-  Pressable,
-  ScrollView,
-  Text,
-  View,
-  type PressableStateCallbackType,
-} from "react-native";
+import { Pressable, ScrollView, Text, View, type PressableStateCallbackType } from "react-native";
 import {
   EditingTextInput as TextInput,
   type EditingTextInputHandle,
@@ -74,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,
@@ -98,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;
@@ -307,7 +299,7 @@ function FlowRow({
 }
 
 function FlowHint({ keys, action }: { keys: string[]; action: string }) {
-  const shortcutsAvailable = useKeyboardShortcutsAvailable();
+  const shortcutsAvailable = useHardwareKeyboardPresent();
   if (!shortcutsAvailable) return null;
 
   return (
@@ -331,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);
@@ -464,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) => {
@@ -622,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();
           },
         });
       }
@@ -723,6 +713,7 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
     directoryPaths,
     githubQuery.data,
     host,
+    addHost,
     onClose,
     openAddedProject,
     page,
@@ -818,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"
@@ -876,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}`}
@@ -895,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}
@@ -999,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) => ({
@@ -1073,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/agent-list.tsx b/packages/app/src/components/agent-list.tsx
index b487e53660..8921102f26 100644
--- a/packages/app/src/components/agent-list.tsx
+++ b/packages/app/src/components/agent-list.tsx
@@ -1,8 +1,8 @@
+import { Modal } from "@/components/ui/modal";
 import {
   View,
   Text,
   Pressable,
-  Modal,
   RefreshControl,
   FlatList,
   type ListRenderItem,
diff --git a/packages/app/src/components/archived-agent-callout.tsx b/packages/app/src/components/archived-agent-callout.tsx
index b5f6a3ea54..8930bf44c3 100644
--- a/packages/app/src/components/archived-agent-callout.tsx
+++ b/packages/app/src/components/archived-agent-callout.tsx
@@ -41,7 +41,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 ef5aa1833a..82fe6b139f 100644
--- a/packages/app/src/components/attachment-lightbox.test.tsx
+++ b/packages/app/src/components/attachment-lightbox.test.tsx
@@ -72,6 +72,7 @@ vi.mock("react-i18next", () => ({
 }));
 
 vi.mock("react-native-safe-area-context", () => ({
+  SafeAreaProvider: ({ children }: { children?: React.ReactNode }) => children,
   useSafeAreaInsets: () => ({ top: 0, right: 0, bottom: 0, left: 0 }),
 }));
 
diff --git a/packages/app/src/components/attachment-lightbox.tsx b/packages/app/src/components/attachment-lightbox.tsx
index 3cf2c5203f..29ad351976 100644
--- a/packages/app/src/components/attachment-lightbox.tsx
+++ b/packages/app/src/components/attachment-lightbox.tsx
@@ -1,18 +1,20 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
-import { Modal, Pressable, Text, View } from "react-native";
+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";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
 import { StyleSheet } from "react-native-unistyles";
-import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { SafeAreaProvider, useSafeAreaInsets } from "react-native-safe-area-context";
 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 }
@@ -28,20 +30,19 @@ const LIGHTBOX_FIT = { padding: SPACING[4], maxWidth: 960, maxHeight: 640 };
 
 export function AttachmentLightbox({ source, onClose }: AttachmentLightboxProps) {
   const { t } = useTranslation();
-  const insets = useSafeAreaInsets();
   const metadata = source?.type === "attachment" ? source.metadata : null;
   const attachmentUrl = useAttachmentPreviewUrl(metadata);
   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,24 +51,13 @@ 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 contentLayerStyle = useMemo(
-    () => [
-      styles.contentLayer,
-      {
-        paddingTop: insets.top,
-        paddingRight: insets.right,
-        paddingBottom: insets.bottom,
-        paddingLeft: insets.left,
-      },
-    ],
-    [insets.bottom, insets.left, insets.right, insets.top],
-  );
   const actions = useMemo(
     () => [
       {
@@ -91,17 +81,19 @@ export function AttachmentLightbox({ source, onClose }: AttachmentLightboxProps)
   return (
     <Modal transparent animationType="fade" statusBarTranslucent visible onRequestClose={onClose}>
       <ModalRoot style={styles.root}>
-        <WindowChromeRootRegion corners="both">
-          <View ref={setWebOverlayScope} style={styles.root}>
-            <Pressable
-              testID="attachment-lightbox-backdrop"
-              accessibilityRole="button"
-              accessibilityLabel={t("message.attachments.dismissImage")}
-              onPress={onClose}
-              style={styles.backdrop}
-            />
-            <View pointerEvents="box-none" style={contentLayerStyle}>
-              <View pointerEvents="box-none" style={styles.imageArea}>
+        {/* The modal is its own window: its insets are the window's, not the ones left where the
+            image was opened (inside a sheet tab, the bottom one is already spent). */}
+        <SafeAreaProvider>
+          <WindowChromeRootRegion corners="both">
+            <View ref={setOverlayScope} style={styles.root}>
+              <Pressable
+                testID="attachment-lightbox-backdrop"
+                accessibilityRole="button"
+                accessibilityLabel={t("message.attachments.dismissImage")}
+                onPress={onClose}
+                style={styles.backdrop}
+              />
+              <LightboxImageArea>
                 {hasError ? (
                   <Text style={styles.errorText}>{t("message.attachments.imageLoadFailed")}</Text>
                 ) : (
@@ -117,15 +109,38 @@ export function AttachmentLightbox({ source, onClose }: AttachmentLightboxProps)
                     uri={url}
                   />
                 )}
-              </View>
+              </LightboxImageArea>
             </View>
-          </View>
-        </WindowChromeRootRegion>
+          </WindowChromeRootRegion>
+        </SafeAreaProvider>
       </ModalRoot>
     </Modal>
   );
 }
 
+function LightboxImageArea({ children }: { children: ReactNode }) {
+  const insets = useSafeAreaInsets();
+  const style = useMemo(
+    () => [
+      styles.contentLayer,
+      {
+        paddingTop: insets.top,
+        paddingRight: insets.right,
+        paddingBottom: insets.bottom,
+        paddingLeft: insets.left,
+      },
+    ],
+    [insets.bottom, insets.left, insets.right, insets.top],
+  );
+  return (
+    <View pointerEvents="box-none" style={style}>
+      <View pointerEvents="box-none" style={styles.imageArea}>
+        {children}
+      </View>
+    </View>
+  );
+}
+
 const styles = StyleSheet.create((theme) => ({
   root: {
     flex: 1,
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..cfd33227a2 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(theme.spacing[2]),
+    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,9 +334,11 @@ 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,
+    marginHorizontal: 0,
     height: "auto",
   },
   triggerFill: {
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/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/indent-rail.tsx b/packages/app/src/components/indent-rail.tsx
index b54ac1ca9b..36fd84a0a9 100644
--- a/packages/app/src/components/indent-rail.tsx
+++ b/packages/app/src/components/indent-rail.tsx
@@ -3,11 +3,10 @@ import { View, type StyleProp, type ViewStyle } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
 
 /**
- * Collapsed chat rows badge their summary with an icon whose center sits 7px into the content
- * column (`ExpandableBadge` bleeds 13px left, then 1px border, 8px padding, 22px icon). The rail
- * hangs from that center so opened rows read as children of the line that opened them.
+ * Align the rail with the expanded caret's left edge. Keep the content offset fixed so
+ * expanded tool cards stay in place, with a gap between their border and the rail.
  */
-const RAIL_LEFT = 7;
+const RAIL_LEFT = 1;
 const RAIL_WIDTH = 1;
 export const INDENT_RAIL_CONTENT_OFFSET = 21;
 
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 dbc501b5c7..1b2df08302 100644
--- a/packages/app/src/components/left-sidebar.tsx
+++ b/packages/app/src/components/left-sidebar.tsx
@@ -1,3 +1,4 @@
+import { useAddHost } from "@/hosts/add-host";
 import { router } from "expo-router";
 import {
   CircleGauge,
@@ -11,19 +12,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 { useWindowLayout, resolveDesktopDivisionLayout } from "@/window-layout";
 import {
   SIDEBAR_RESIZE_ACTIVATION_OFFSET,
   SIDEBAR_RESIZE_FAIL_OFFSET,
@@ -34,12 +41,24 @@ import { SidebarSeparator } from "@/components/sidebar/sidebar-separator";
 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 +67,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,21 +81,20 @@ 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,
-  useHasUsageSummary,
-  useOpenSidebarUsage,
-} from "@/usage";
+import { UsageSidebarItem, UsageSidebarRoot, useUsageSummary, useOpenSidebarUsage } from "@/usage";
 import { SidebarAgentListSkeleton } from "./sidebar-agent-list-skeleton";
 import { SidebarCalloutSlot } from "./sidebar-callout-slot";
 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 {
@@ -122,9 +141,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();
@@ -165,33 +191,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);
@@ -199,14 +212,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"),
@@ -239,41 +244,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}
     </>
@@ -427,35 +426,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>
@@ -480,10 +516,10 @@ function SidebarUsageIcon({ label }: { label: string }) {
  */
 function SidebarFooterRows({ onBeforeNavigate }: { onBeforeNavigate?: () => void }) {
   const { items } = useSidebarNavItems("footer");
-  const hasUsageSummary = useHasUsageSummary();
+  const usageSummary = useUsageSummary();
   const rowsRef = useRef<View | null>(null);
   const visibleItems = items.filter(
-    (item) => item.visible && (item.kind === "plugin" || hasUsageSummary),
+    (item) => item.visible && (item.kind === "plugin" || usageSummary.length > 0),
   );
   if (visibleItems.length === 0) return null;
   return (
@@ -499,7 +535,7 @@ function SidebarFooterRows({ onBeforeNavigate }: { onBeforeNavigate?: () => void
               onBeforeNavigate={onBeforeNavigate}
             />
           ) : (
-            <UsageSidebarItem key={item.key} />
+            <UsageSidebarItem key={item.key} sources={usageSummary} />
           ),
         )}
       </View>
@@ -536,6 +572,7 @@ function MobileSidebar({
   insetsBottom,
   closeSidebar,
 }: MobileSidebarProps) {
+  const insets = useSafeAreaInsets();
   const hasActiveHostFilter = useSidebarViewStore((state) => state.hostFilters.length > 0);
   const { gesture: closeGesture, gestureRef: closeGestureRef } = useCloseAgentListGesture();
 
@@ -550,10 +587,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(
@@ -565,6 +602,14 @@ function MobileSidebar({
     [insetsTop, insetsBottom, theme.colors.surfaceSidebar],
   );
 
+  const navRows = (
+    <SidebarNavRows
+      style={styles.mobileNavRowsGroup}
+      onBeforeNavigate={closeSidebar}
+      firstRowTrailing={closeButton}
+    />
+  );
+
   return (
     <MobilePanelOverlay
       panel="agent-list"
@@ -573,11 +618,29 @@ function MobileSidebar({
     >
       <View style={styles.sidebarContent} pointerEvents="auto">
         <WindowChromeSafeArea placement="below" />
-        <SidebarNavRows
-          style={styles.sidebarHeaderGroup}
-          onBeforeNavigate={closeSidebar}
-          firstRowTrailing={closeButton}
-        />
+        {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>
+        ) : (
+          <ScrollView
+            style={styles.mobileNavScroll}
+            showsVerticalScrollIndicator={false}
+            alwaysBounceVertical={false}
+            testID="sidebar-nav-scroll"
+          >
+            {navRows}
+          </ScrollView>
+        )}
+        <SidebarSeparator />
 
         {isInitialLoad && !hasActiveHostFilter ? (
           <SidebarAgentListSkeleton />
@@ -643,20 +706,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), []);
@@ -669,6 +739,7 @@ function DesktopSidebar({
   const resizeGesture = useMemo(
     () =>
       Gesture.Pan()
+        .enabled(divisionLayout === null)
         .hitSlop({ left: 8, right: 8, top: 0, bottom: 0 })
         .onBegin(() => {
           scheduleOnRN(showResizeGrip);
@@ -679,129 +750,142 @@ 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],
   );
   const sidebarHeaderGroupStyle = useMemo(
     () => [styles.sidebarHeaderGroup, ownsTopLeft && styles.sidebarHeaderGroupBelowChrome],
     [ownsTopLeft],
   );
   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>
+            )}
+            <SidebarNavRows style={sidebarHeaderGroupStyle} onBeforeNavigate={closeSidebar} />
+          </View>
+
+          {isInitialLoad && !hasActiveHostFilter ? (
+            <SidebarAgentListSkeleton />
           ) : (
-            <TitlebarDragRegion />
+            <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}
+            />
           )}
-          <SidebarNavRows style={sidebarHeaderGroupStyle} />
-        </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}
+          <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>
   );
 }
 
@@ -832,9 +916,7 @@ const workspacesSectionHeaderElement = <WorkspacesSectionHeader />;
 const staticStyles = RNStyleSheet.create({
   desktopSidebar: {
     position: "relative" as const,
-  },
-  desktopSidebarHidden: {
-    display: "none",
+    flex: 1,
   },
 });
 
@@ -849,18 +931,30 @@ const styles = StyleSheet.create((theme) => ({
   sidebarHeaderGroupBelowChrome: {
     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",
   },
@@ -896,10 +990,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/fullscreen-viewer.web.tsx b/packages/app/src/components/markdown/fence/mermaid/fullscreen-viewer.web.tsx
index 8b68ae61cb..02ca7108d8 100644
--- a/packages/app/src/components/markdown/fence/mermaid/fullscreen-viewer.web.tsx
+++ b/packages/app/src/components/markdown/fence/mermaid/fullscreen-viewer.web.tsx
@@ -1,5 +1,6 @@
+import { Modal } from "@/components/ui/modal";
 import { useCallback, useEffect, useMemo, useRef } from "react";
-import { Modal, View } from "react-native";
+import { View } from "react-native";
 import { X } from "lucide-react-native";
 import { useTranslation } from "react-i18next";
 import { StyleSheet } from "react-native-unistyles";
diff --git a/packages/app/src/components/markdown/fence/mermaid/host.native.tsx b/packages/app/src/components/markdown/fence/mermaid/host.native.tsx
index 001ec5cf1c..5f86efe05c 100644
--- a/packages/app/src/components/markdown/fence/mermaid/host.native.tsx
+++ b/packages/app/src/components/markdown/fence/mermaid/host.native.tsx
@@ -1,6 +1,6 @@
+import { Modal } from "@/components/ui/modal";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
-  Modal,
   Pressable,
   StyleSheet as RNStyleSheet,
   ScrollView,
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 9430aa3a12..e73dd4171f 100644
--- a/packages/app/src/components/message.tsx
+++ b/packages/app/src/components/message.tsx
@@ -1,3 +1,5 @@
+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";
 import { AssistantForkMenu, type AssistantForkTarget } from "@/components/assistant-fork-menu";
@@ -26,6 +28,7 @@ import { writeMarkdownToRichClipboard } from "@/utils/rich-clipboard";
 import { getDefaultMarkdownClipboardEnvironment } from "@/utils/rich-clipboard-default-environment";
 import { formatDuration, formatMessageTimestamp } from "@/utils/time";
 import { resolveToolCallIcon } from "@/utils/tool-call-icon";
+import { useToolCallExpanded } from "@/tool-calls/expansion-context";
 import { useTargetAgentTitle } from "@/tool-calls/use-target-agent-title";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import type { AgentMessage } from "@getpaseo/protocol/agent-message";
@@ -89,6 +92,7 @@ export type { InlinePathTarget } from "@/assistant-file-links";
 export type { AssistantForkTarget };
 
 interface UserMessageProps {
+  sender?: AgentMessage["sender"];
   serverId?: string;
   agentId?: string;
   messageId?: string;
@@ -387,6 +391,7 @@ function UserMessageImagePill({ image, onOpen, accessibilityLabel }: UserMessage
 const MESSAGE_TEXT_DATASET = { messageText: "true" };
 
 export const UserMessage = memo(function UserMessage({
+  sender,
   serverId,
   agentId,
   messageId,
@@ -473,42 +478,45 @@ export const UserMessage = memo(function UserMessage({
         onPointerEnter={handlePointerEnter}
         onPointerLeave={handlePointerLeave}
       >
+        {sender ? <MessageSender sender={sender} serverId={serverId} /> : null}
         <View style={userMessageStylesheet.bubble}>
-          {hasImages ? (
-            <View style={imagePreviewContainerStyle}>
-              {images.map((image) => (
-                <UserMessageImagePill
-                  key={image.id}
-                  image={image}
-                  onOpen={setLightboxMetadata}
-                  accessibilityLabel={t("composer.attachments.openImage")}
-                />
-              ))}
-            </View>
-          ) : null}
-          {hasAttachments ? (
-            <View style={attachmentPreviewContainerStyle}>
-              {attachments.map((attachment, index) => {
-                const content = getAgentAttachmentPillContent(attachment, t);
-                return (
-                  <AttachmentFrame
-                    key={`${attachment.type}:${"number" in attachment ? attachment.number : index}`}
-                  >
-                    <AttachmentLabel
-                      icon={content.icon}
-                      title={content.title}
-                      subtitle={content.subtitle}
-                    />
-                  </AttachmentFrame>
-                );
-              })}
-            </View>
-          ) : null}
-          {hasText ? (
-            <Text selectable style={userMessageStylesheet.text} dataSet={MESSAGE_TEXT_DATASET}>
-              {message}
-            </Text>
-          ) : null}
+          <MessagePreview>
+            {hasImages ? (
+              <View style={imagePreviewContainerStyle}>
+                {images.map((image) => (
+                  <UserMessageImagePill
+                    key={image.id}
+                    image={image}
+                    onOpen={setLightboxMetadata}
+                    accessibilityLabel={t("composer.attachments.openImage")}
+                  />
+                ))}
+              </View>
+            ) : null}
+            {hasAttachments ? (
+              <View style={attachmentPreviewContainerStyle}>
+                {attachments.map((attachment, index) => {
+                  const content = getAgentAttachmentPillContent(attachment, t);
+                  return (
+                    <AttachmentFrame
+                      key={`${attachment.type}:${"number" in attachment ? attachment.number : index}`}
+                    >
+                      <AttachmentLabel
+                        icon={content.icon}
+                        title={content.title}
+                        subtitle={content.subtitle}
+                      />
+                    </AttachmentFrame>
+                  );
+                })}
+              </View>
+            ) : null}
+            {hasText ? (
+              <Text selectable style={userMessageStylesheet.text} dataSet={MESSAGE_TEXT_DATASET}>
+                {message}
+              </Text>
+            ) : null}
+          </MessagePreview>
         </View>
         {hasText ? (
           <View
@@ -541,7 +549,7 @@ export const UserMessage = memo(function UserMessage({
 });
 
 interface AssistantTurnFooterProps {
-  getContent: () => string;
+  getContent?: () => string;
   completedAt?: Date;
   durationMs?: number | null;
   onFork?: (target: AssistantForkTarget) => Promise<void> | void;
@@ -641,10 +649,12 @@ export const AssistantTurnFooter = memo(function AssistantTurnFooter({
 
   return (
     <View style={assistantTurnFooterStylesheet.container}>
-      <TurnCopyButton
-        getContent={getContent}
-        containerStyle={assistantTurnFooterStylesheet.copyButton}
-      />
+      {getContent ? (
+        <TurnCopyButton
+          getContent={getContent}
+          containerStyle={assistantTurnFooterStylesheet.copyButton}
+        />
+      ) : null}
       {canFork ? <AssistantForkMenu onFork={handleFork} /> : null}
       {primaryLabel ? (
         <Pressable
@@ -1190,6 +1200,7 @@ export const AssistantMessage = memo(function AssistantMessage({
     >
       <MarkdownRenderer
         text={revealedMessage}
+        agentCommands
         streaming={phase !== "complete" || revealedMessage.length < renderedMessage.text.length}
         client={client}
         workspaceRoot={workspaceRoot}
@@ -1473,9 +1484,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 (
@@ -2233,6 +2244,9 @@ interface ToolCallProps {
   defaultExpanded?: boolean;
   forceInline?: boolean;
   maxDetailHeight?: number;
+  itemId: string;
+  /** Shown as its own row rather than inside a tool call group. */
+  standalone?: boolean;
 }
 
 export const ToolCall = memo(function ToolCall({
@@ -2254,12 +2268,19 @@ export const ToolCall = memo(function ToolCall({
   defaultExpanded,
   forceInline = false,
   maxDetailHeight = 400,
+  itemId,
+  standalone = true,
 }: ToolCallProps) {
   const { openToolCall } = useToolCallSheet();
-  const [isExpanded, setIsExpanded] = useState(defaultExpanded ?? false);
+  const { expanded: isExpanded, toggle: toggleExpanded } = useToolCallExpanded({
+    callId: itemId,
+    defaultExpanded: defaultExpanded ?? false,
+    standalone,
+  });
 
   const isMobile = useIsCompactFormFactor();
   const shouldRenderInline = !isMobile || forceInline;
+  const hold = useDisclosureHold();
 
   const effectiveDetail = useMemo<ToolCallDetail | undefined>(() => {
     if (detail) {
@@ -2311,10 +2332,12 @@ export const ToolCall = memo(function ToolCall({
         showLoadingSkeleton: presentation.isLoadingDetails,
       });
     } else {
-      setIsExpanded((prev) => !prev);
+      hold(toggleExpanded);
     }
   }, [
+    hold,
     shouldRenderInline,
+    toggleExpanded,
     openToolCall,
     toolName,
     presentation.detail,
@@ -2420,5 +2443,7 @@ function areToolCallPropsEqual(previous: ToolCallProps, next: ToolCallProps) {
   if (previous.defaultExpanded !== next.defaultExpanded) return false;
   if (previous.forceInline !== next.forceInline) return false;
   if (previous.maxDetailHeight !== next.maxDetailHeight) return false;
+  if (previous.itemId !== next.itemId) return false;
+  if (previous.standalone !== next.standalone) return false;
   return true;
 }
diff --git a/packages/app/src/components/model-browser.tsx b/packages/app/src/components/model-browser.tsx
index 17924b233d..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}
@@ -1692,7 +1694,7 @@ const styles = StyleSheet.create((theme) => ({
     opacity: 0,
   },
   emptyState: {
-    paddingVertical: theme.spacing[4],
+    padding: theme.spacing[4],
     alignItems: "center",
     gap: theme.spacing[2],
   },
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 6576728384..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,9 +47,9 @@ export function ResizeHandle({
   onResizeSplit,
 }: ResizeHandleProps) {
   const { theme } = useUnistyles();
-  const finePointer = useHasFinePointer();
+  const { finePointer } = usePointerCapabilities();
   const pointerStatesRef = useRef(new Map<number, PointerState>());
-  const touchDragRef = useRef<ResizeHandleDrag | null>(null);
+  const touchStateRef = useRef<PointerState | null>(null);
   const cursorBeforeDragRef = useRef<string | null>(null);
   const hoverTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const [active, setActive] = useState(false);
@@ -151,23 +151,30 @@ export function ResizeHandle({
   const touchGesture = useMemo(() => {
     const gesture = Gesture.Pan()
       .runOnJS(true)
-      .onBegin(() => setDragging(true))
-      .onStart(() => {
-        touchDragRef.current = startResizeHandleDrag({
-          sizes,
-          index,
-          preview: (nextSizes) => onPreviewResizeSplit(groupId, nextSizes),
-          commit: (nextSizes) => onResizeSplit(groupId, nextSizes),
-        });
+      .onBegin((event) => {
+        setDragging(true);
+        touchStateRef.current = {
+          containerSize,
+          pointerStart: direction === "horizontal" ? event.absoluteX : event.absoluteY,
+          drag: startResizeHandleDrag({
+            sizes,
+            index,
+            preview: (nextSizes) => onPreviewResizeSplit(groupId, nextSizes),
+            commit: (nextSizes) => onResizeSplit(groupId, nextSizes),
+          }),
+        };
       })
       .onUpdate((event) => {
-        if (containerSize <= 0) return;
-        const translation = direction === "horizontal" ? event.translationX : event.translationY;
-        touchDragRef.current?.move(translation / containerSize);
+        const state = touchStateRef.current;
+        if (!state || state.containerSize <= 0) return;
+        // Gesture Handler resets web translation when the pan activates. Measure from
+        // the initial press so the activation distance is included on every platform.
+        const pointerCurrent = direction === "horizontal" ? event.absoluteX : event.absoluteY;
+        state.drag.move((pointerCurrent - state.pointerStart) / state.containerSize);
       })
-      .onEnd(() => touchDragRef.current?.finish())
+      .onEnd(() => touchStateRef.current?.drag.finish())
       .onFinalize(() => {
-        touchDragRef.current = null;
+        touchStateRef.current = null;
         setDragging(false);
       });
 
diff --git a/packages/app/src/components/rewind/use-rewind-agent-mutation.ts b/packages/app/src/components/rewind/use-rewind-agent-mutation.ts
index d482bb2d42..f6d3d0325c 100644
--- a/packages/app/src/components/rewind/use-rewind-agent-mutation.ts
+++ b/packages/app/src/components/rewind/use-rewind-agent-mutation.ts
@@ -1,3 +1,4 @@
+import { planTimelineTailFetch } from "@/timeline/timeline-sync-plan";
 import { useCallback } from "react";
 import { useTranslation } from "react-i18next";
 import { useMutation } from "@tanstack/react-query";
@@ -42,8 +43,7 @@ export function useRewindAgentMutation(input: UseRewindAgentMutationInput): {
           : undefined;
         if (!input.serverId) throw new Error(t("common.errors.daemonClientUnavailable"));
         await getHostRuntimeStore().fetchAgentTimeline(input.serverId, input.agentId, {
-          direction: "tail",
-          projection: "projected",
+          ...planTimelineTailFetch(),
           ...(cursor ? { cursor: { epoch: cursor.epoch, seq: cursor.endSeq } } : {}),
         });
       }
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-workspace-menu.tsx b/packages/app/src/components/sidebar/sidebar-workspace-menu.tsx
index f74c43c980..f1c2fabcd1 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,9 @@ 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. */
+export const ARCHIVE_BUTTON_SIZE = 18;
+
 const triggerIconProps = densityIconProps("sm", foregroundMutedColorMapping);
 const triggerIconHoveredProps = densityIconProps("sm", foregroundColorMapping);
 
@@ -78,6 +83,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 +468,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. The kebab's marginLeft is the gap between them.
+  archiveButton: {
+    width: ARCHIVE_BUTTON_SIZE,
+    height: ARCHIVE_BUTTON_SIZE,
+    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..aef846c4a3 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_SIZE,
+  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.
@@ -432,23 +446,46 @@ export function SidebarWorkspaceTrailingActionBase({
   );
 }
 
+// The archive button plus the kebab's marginLeft, which is the gap between them.
+const ARCHIVE_BUTTON_SCRIM_WIDTH = ARCHIVE_BUTTON_SIZE + 2;
+
 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_SCRIM_WIDTH : 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 660b5f4e6b..63a3144dda 100644
--- a/packages/app/src/components/split-container.tsx
+++ b/packages/app/src/components/split-container.tsx
@@ -1,3 +1,7 @@
+import {
+  AdaptiveWorkspaceChrome,
+  type WorkspaceCompactHeaderActions,
+} 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,12 +47,14 @@ 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";
 import {
   collectAllPanes,
   createDefaultLayout,
+  selectExplorerSidebarPaneId,
   useWorkspaceLayoutStore,
   type SplitNode,
   type SplitPane,
@@ -60,6 +67,11 @@ import { isNative } from "@/constants/platform";
 interface SplitContainerProps {
   layout: WorkspaceLayout;
   renderMainHeader?: () => ReactNode;
+  renderCompactHeader: (
+    tabs: WorkspaceTabDescriptor[],
+    activeTabKey: string,
+    actions: WorkspaceCompactHeaderActions,
+  ) => ReactNode;
   workspaceKey: string;
   normalizedServerId: string;
   normalizedWorkspaceId: string;
@@ -144,7 +156,6 @@ const EMPTY_SPLIT_SIZES: number[] = [];
 
 export function SplitContainer({
   layout,
-  renderMainHeader,
   workspaceKey,
   normalizedServerId,
   normalizedWorkspaceId,
@@ -173,9 +184,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;
@@ -183,8 +196,8 @@ export function SplitContainer({
   } | null>(null);
   const maximizedPaneId =
     maximizedPane?.workspaceKey === workspaceKey ? maximizedPane.paneId : null;
-  const explorerSidebarPaneId = useWorkspaceLayoutStore(
-    (state) => state.explorerSidebarPaneIdByWorkspace[workspaceKey] ?? null,
+  const explorerSidebarPaneId = useWorkspaceLayoutStore((state) =>
+    selectExplorerSidebarPaneId(state, workspaceKey),
   );
 
   const mainRoot = useMemo(
@@ -236,7 +249,6 @@ export function SplitContainer({
       <View style={styles.workspaceShell}>
         <WindowChromeRegion corners={mainColumnWindowChromeCorners}>
           <View style={mainColumnStyle}>
-            {renderMainHeader?.()}
             {splitRoot.usesFallbackStrip && <WindowChromeSafeArea placement="below" />}
             {renderRoot ? (
               <SplitNodeView
@@ -278,6 +290,8 @@ export function SplitContainer({
                 onTogglePaneMaximized={handleTogglePaneMaximized}
                 focusModeEnabled={focusModeEnabled}
                 onExitFocusMode={onExitFocusMode}
+                renderMainHeader={renderMainHeader}
+                renderCompactHeader={renderCompactHeader}
               />
             ) : null}
           </View>
@@ -409,6 +423,8 @@ function SplitNodeView({
   onTogglePaneMaximized,
   focusModeEnabled,
   onExitFocusMode,
+  renderMainHeader,
+  renderCompactHeader,
 }: SplitNodeViewProps) {
   const [groupContainerSize, setGroupContainerSize] = useState(0);
   const groupId = node.kind === "group" ? node.group.id : null;
@@ -495,6 +511,8 @@ function SplitNodeView({
             onTogglePaneMaximized={onTogglePaneMaximized}
             focusModeEnabled={focusModeEnabled}
             onExitFocusMode={onExitFocusMode}
+            renderMainHeader={renderMainHeader}
+            renderCompactHeader={renderCompactHeader}
           />
         </WindowChromeRegion>
       </RetainedPanel>
@@ -543,12 +561,25 @@ 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}
+              renderMainHeader={renderMainHeader}
+              renderCompactHeader={renderCompactHeader}
             />
           </SplitGroupChild>
           {index < node.group.children.length - 1 &&
@@ -607,6 +638,8 @@ const SplitPaneView = memo(function SplitPaneView({
   onTogglePaneMaximized,
   focusModeEnabled,
   onExitFocusMode,
+  renderMainHeader,
+  renderCompactHeader,
 }: SplitPaneViewProps) {
   recordRenderProfileReasons(`SplitPaneView:${pane.id}`, ["render"]);
   const paneRef = useRef<View | null>(null);
@@ -700,6 +733,51 @@ 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(
+    () => (
+      <WindowChromeSafeArea placement="inline">
+        <TitlebarDragRegion />
+        {renderCompactHeader(paneTabs, activeTabDescriptor?.key ?? "", compactHeaderActions)}
+      </WindowChromeSafeArea>
+    ),
+    [renderCompactHeader, paneTabs, activeTabDescriptor?.key, compactHeaderActions],
+  );
   return (
     <RenderProfile id={`SplitPaneView:${pane.id}`}>
       <View
@@ -708,43 +786,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}>
+          {renderMainHeader?.()}
+          <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 c4c7080b83..b4e3dd93e1 100644
--- a/packages/app/src/components/terminal-emulator-contract.ts
+++ b/packages/app/src/components/terminal-emulator-contract.ts
@@ -4,7 +4,6 @@ import type {
 } from "../terminal/runtime/terminal-emulator-runtime";
 import type { Ref } from "react";
 import type { ITheme } from "@xterm/xterm";
-import type { TerminalState } from "@getpaseo/protocol/messages";
 import type { TerminalInputModeState } from "@getpaseo/protocol/terminal-input-mode";
 import type { TerminalOutputData } from "../terminal/runtime/terminal-emulator-runtime";
 import type {
@@ -13,14 +12,14 @@ 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";
 
 export interface TerminalEmulatorHandle {
   find?: TerminalFindHandle;
   writeOutput: (data: TerminalOutputData) => void;
-  restoreOutput: (data: TerminalOutputData) => void;
-  renderSnapshot: (state: TerminalState | null) => void;
+  replay: (event: import("@getpaseo/client").TerminalReplayEvent) => void;
   paste: (text: string) => void;
   copySelection: (clipboard: TerminalClipboardWriter) => Promise<string>;
   clear: () => void;
@@ -34,6 +33,7 @@ export interface TerminalEmulatorProps {
   ref: Ref<TerminalEmulatorHandle>;
   streamKey: string;
   supportsTerminalInputModeReplay: boolean;
+  characterWidths: TerminalCharacterWidths;
   testId?: string;
   xtermTheme?: ITheme;
   scrollbackLines: number;
@@ -44,7 +44,6 @@ export interface TerminalEmulatorProps {
   swipeGesturesEnabled?: boolean;
   onSwipeLeft?: () => void;
   onSwipeRight?: () => void;
-  initialSnapshot?: TerminalState | null;
   onFindRequest?: () => void;
   onFindResult?: (result: TerminalFindResult) => void;
   onInput?: (data: string) => Promise<void> | void;
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 dcda257116..ad71316f3c 100644
--- a/packages/app/src/components/terminal-emulator-native-grid.native.tsx
+++ b/packages/app/src/components/terminal-emulator-native-grid.native.tsx
@@ -1,19 +1,17 @@
+import Svg, { Path } from "react-native-svg";
 import { useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
 import {
   Keyboard,
   type LayoutChangeEvent,
   PanResponder,
-  type PanResponderGestureState,
   Pressable,
   StyleSheet,
   Text,
   View,
-  type GestureResponderEvent,
   type StyleProp,
   type ViewStyle,
 } from "react-native";
 import type { ITheme } from "@xterm/xterm";
-import type { TerminalState } from "@getpaseo/protocol/messages";
 import {
   TerminalInputModeTracker,
   terminalInputModeStatesEqual,
@@ -48,13 +46,10 @@ import {
   type TerminalSelectionViewport,
 } from "../terminal/native-renderer/terminal-selection";
 import {
-  TERMINAL_GESTURE_LONG_PRESS_MS,
-  TERMINAL_GESTURE_TAP_TOLERANCE_PX,
-  advanceTerminalScrollGesture,
-  classifyTerminalGestureIntent,
-  resolveTerminalGestureReleaseAction,
-  type TerminalGestureIntent,
-} from "../terminal/native-renderer/terminal-selection-gesture";
+  createTerminalSelectionController,
+  terminalSelectionHandles,
+  TERMINAL_SELECTION_GRIP_SIZE,
+} from "../terminal/native-renderer/terminal-selection-controller";
 import { resolveNativeTerminalMountAction } from "../terminal/native-renderer/terminal-mount-policy";
 import {
   forwardNativeTerminalKey,
@@ -88,75 +83,8 @@ const DEFAULT_XTERM_THEME: ITheme = {
   foreground: "#e6e6e6",
   cursor: "#e6e6e6",
 };
-interface NativeTerminalPanState {
-  lastDy: number;
-  rowRemainder: number;
-  didScroll: boolean;
-  didNavigate: boolean;
-  movedBeyondTapTolerance: boolean;
-  intent: TerminalGestureIntent | null;
-}
-
-interface NativeTerminalSelectionPress {
-  startX: number;
-  startY: number;
-  startedAt: number;
-  startedWithSelection: boolean;
-  status: "pressing" | "selecting";
-}
-
-function resolvePanResponderPoint(
-  press: NativeTerminalSelectionPress,
-  event: GestureResponderEvent,
-  gesture: PanResponderGestureState,
-): { x: number; y: number } {
-  const eventDx = event.nativeEvent.locationX - press.startX;
-  const eventDy = event.nativeEvent.locationY - press.startY;
-  const dx = Math.abs(eventDx) > Math.abs(gesture.dx) ? eventDx : gesture.dx;
-  const dy = Math.abs(eventDy) > Math.abs(gesture.dy) ? eventDy : gesture.dy;
-  return {
-    x: press.startX + dx,
-    y: press.startY + dy,
-  };
-}
-
-function initialNativeTerminalSize(snapshot: TerminalState | null): TerminalMeasuredSize {
-  return {
-    rows: snapshot?.rows ?? MIN_NATIVE_TERMINAL_ROWS,
-    cols: snapshot?.cols ?? MIN_NATIVE_TERMINAL_COLS,
-  };
-}
-
-function screenStateFromViewport(viewport: TerminalViewportState): TerminalScreenState {
-  const visibleRows = viewport.grid.length;
-  const currentViewport = {
-    firstRow: viewport.firstRow,
-    lastRow: Math.min(viewport.newestRow, viewport.firstRow + Math.max(1, visibleRows) - 1),
-  };
-  return {
-    viewport,
-    scroll: {
-      mode: "following",
-      firstRow: viewport.firstRow,
-      visibleRows,
-      oldestRow: viewport.oldestRow,
-      newestRow: viewport.newestRow,
-      currentViewport,
-      bottomViewport: currentViewport,
-    },
-  };
-}
-
-function viewportStateFromSnapshot(state: TerminalState): TerminalViewportState {
-  return {
-    rows: state.grid.length,
-    cols: state.cols,
-    firstRow: 0,
-    oldestRow: 0,
-    newestRow: Math.max(0, state.grid.length - 1),
-    grid: state.grid,
-    cursor: state.cursor,
-  };
+function initialNativeTerminalSize(): TerminalMeasuredSize {
+  return { rows: MIN_NATIVE_TERMINAL_ROWS, cols: MIN_NATIVE_TERMINAL_COLS };
 }
 
 function NativeTerminalEmulator({
@@ -165,11 +93,11 @@ function NativeTerminalEmulator({
   testId = "terminal-surface",
   xtermTheme = DEFAULT_XTERM_THEME,
   scrollbackLines,
+  characterWidths,
   fontFamily,
   fontSize,
   keyboardInset = 0,
   isKeyboardVisible = false,
-  initialSnapshot = null,
   onInput,
   onTerminalKey,
   onResize,
@@ -181,20 +109,18 @@ function NativeTerminalEmulator({
   resizeRequestToken = 0,
 }: TerminalEmulatorProps) {
   const terminalRef = useRef<NativeHeadlessTerminal | null>(null);
-  const mountInputRef = useRef({ streamKey, initialSnapshot });
+  const mountInputRef = useRef({ streamKey });
   if (
     resolveNativeTerminalMountAction({
       mountedStreamKey: mountInputRef.current.streamKey,
       nextStreamKey: streamKey,
     }) === "mount"
   ) {
-    mountInputRef.current = { streamKey, initialSnapshot };
+    mountInputRef.current = { streamKey };
   }
   const inputRef = useRef<TerminalInputHandle>(null);
-  const terminalSizeRef = useRef<TerminalMeasuredSize>(initialNativeTerminalSize(initialSnapshot));
-  const resizePolicyRef = useRef(
-    createTerminalResizePolicy(initialNativeTerminalSize(initialSnapshot)),
-  );
+  const terminalSizeRef = useRef<TerminalMeasuredSize>(initialNativeTerminalSize());
+  const resizePolicyRef = useRef(createTerminalResizePolicy(initialNativeTerminalSize()));
   const activeResizeClaimTokenRef = useRef(0);
   const layoutRef = useRef<TerminalMeasuredLayout | null>(null);
   const metricsRef = useRef<TerminalGridCellMetrics | null>(null);
@@ -202,29 +128,20 @@ function NativeTerminalEmulator({
   const outputDrainRef = useRef<NativeTerminalOutputDrain | null>(null);
   const screenModelRef = useRef<TerminalScreenModel | null>(null);
   const selectionModelRef = useRef<TerminalSelectionModel>(createTerminalSelectionModel());
-  const selectionLongPressTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const selectionPressRef = useRef<NativeTerminalSelectionPress | null>(null);
+  const selectionControllerRef = useRef<ReturnType<
+    typeof createTerminalSelectionController
+  > | null>(null);
+  const gestureStartRef = useRef({ x: 0, y: 0 });
+  const [cellMetrics, setCellMetrics] = useState<TerminalGridCellMetrics | null>(null);
   const latestResolvedScreenRef = useRef<TerminalScreenState | null>(null);
   const paintFrameRef = useRef<number | null>(null);
   const outputDecoderRef = useRef(new TextDecoder());
-  const panStateRef = useRef<NativeTerminalPanState>({
-    lastDy: 0,
-    rowRemainder: 0,
-    didScroll: false,
-    didNavigate: false,
-    movedBeyondTapTolerance: false,
-    intent: null,
-  });
   const inputModeTrackerRef = useRef(new TerminalInputModeTracker());
   const lastInputModeStateRef = useRef<TerminalInputModeState>({
     ...inputModeTrackerRef.current.getState(),
     applicationCursorKeys: false,
   });
-  const [terminalScreen, setTerminalScreen] = useState<TerminalScreenState | null>(() => {
-    return initialSnapshot
-      ? screenStateFromViewport(viewportStateFromSnapshot(initialSnapshot))
-      : null;
-  });
+  const [terminalScreen, setTerminalScreen] = useState<TerminalScreenState | null>(null);
   const [selectionRange, setSelectionRange] = useState<TerminalSelectionRange | null>(null);
   const selectionRangeRef = useRef<TerminalSelectionRange | null>(null);
   const hasNotifiedSelectionRef = useRef(false);
@@ -288,6 +205,7 @@ function NativeTerminalEmulator({
   }, []);
 
   const clearSelection = useCallback(() => {
+    selectionControllerRef.current?.cancel();
     const snapshot = selectionModelRef.current.clear();
     commitSelectionRange(snapshot.range);
   }, [commitSelectionRange]);
@@ -298,20 +216,14 @@ function NativeTerminalEmulator({
 
   const syncSelectionWithTerminal = useCallback(
     (terminal: NativeHeadlessTerminal) => {
+      const previous = selectionModelRef.current.getSnapshot().range;
       const snapshot = selectionModelRef.current.sync({ bounds: terminal.getBufferBounds() });
+      if (previous && !snapshot.range) selectionControllerRef.current?.cancel();
       commitSelectionRange(snapshot.range);
     },
     [commitSelectionRange],
   );
 
-  const clearSelectionLongPressTimeout = useCallback(() => {
-    if (selectionLongPressTimeoutRef.current === null) {
-      return;
-    }
-    clearTimeout(selectionLongPressTimeoutRef.current);
-    selectionLongPressTimeoutRef.current = null;
-  }, []);
-
   const resolveVisibleRows = useCallback((terminal: NativeHeadlessTerminal): number => {
     return (
       resolveMeasuredNativeTerminalSize({
@@ -361,10 +273,14 @@ function NativeTerminalEmulator({
     (terminal: NativeHeadlessTerminal): NativeTerminalOutputDrain =>
       createNativeTerminalOutputDrain({
         write: async (chunk) => {
+          inputModeTrackerRef.current.feed(chunk);
           await terminal.write(chunk);
           emitInputModeChange();
         },
-        reset: () => {
+        restoreSize: () => terminal.resize(terminalSizeRef.current),
+        reset: (size) => {
+          inputModeTrackerRef.current.reset();
+          if (size) terminal.resize(size);
           terminal.reset();
           emitInputModeChange();
         },
@@ -415,11 +331,11 @@ function NativeTerminalEmulator({
         return;
       }
 
+      const isFirstMeasuredSize = !hasNotifiedMeasuredSizeRef.current;
       hasNotifiedMeasuredSizeRef.current = true;
       terminalSizeRef.current = policyResult.measuredSize;
       if (policyResult.measuredSizeChanged) {
-        terminalRef.current?.resize(policyResult.measuredSize);
-        schedulePaint();
+        outputDrainRef.current?.resize();
       }
       callbacksRef.current.onResize?.({
         rows: policyResult.measuredSize.rows,
@@ -427,69 +343,62 @@ function NativeTerminalEmulator({
         shouldClaim: policyResult.resizeClaim !== null,
         forceClaim: policyResult.resizeClaim?.force,
       });
-    },
-    [schedulePaint],
-  );
-
-  const resetTerminal = useCallback(
-    (snapshot: TerminalState | null) => {
-      outputDrainRef.current?.dispose();
-      outputDrainRef.current = null;
-      terminalRef.current?.dispose();
-      screenModelRef.current = null;
-      latestResolvedScreenRef.current = null;
-      clearSelection();
-      const measuredSize = resolveMeasuredNativeTerminalSize({
-        layout: layoutRef.current,
-        metrics: metricsRef.current,
-      });
-      const size =
-        measuredSize ??
-        (snapshot ? { rows: snapshot.rows, cols: snapshot.cols } : terminalSizeRef.current);
-      terminalSizeRef.current = size;
-      resizePolicyRef.current = createTerminalResizePolicy(size);
-      outputDecoderRef.current.decode();
-      const terminal = createNativeHeadlessTerminal({
-        rows: size.rows,
-        cols: size.cols,
-        scrollbackLines,
-      });
-      terminalRef.current = terminal;
-      screenModelRef.current = createNativeTerminalScreenModel({ terminal });
-      const outputDrain = createOutputDrain(terminal);
-      outputDrainRef.current = outputDrain;
-      const screen = snapshot
-        ? screenStateFromViewport(viewportStateFromSnapshot(snapshot))
-        : resolveTerminalScreen(terminal);
-      commitTerminalScreen(screen);
-      resetInputModeTracker();
-      if (snapshot) {
-        outputDrain.restoreSnapshot(snapshot);
+      // Ready waits for the grid size, so the pane attaches with it and the daemon replays the
+      // terminal at that size instead of the PTY's.
+      if (isFirstMeasuredSize) {
+        callbacksRef.current.onRendererReadyChange?.({
+          streamKey: mountInputRef.current.streamKey,
+          isReady: true,
+        });
       }
     },
-    [
-      commitTerminalScreen,
-      createOutputDrain,
-      resetInputModeTracker,
-      resolveTerminalScreen,
+    [],
+  );
+
+  const resetTerminal = useCallback(() => {
+    outputDrainRef.current?.dispose();
+    outputDrainRef.current = null;
+    terminalRef.current?.dispose();
+    screenModelRef.current = null;
+    latestResolvedScreenRef.current = null;
+    clearSelection();
+    const measuredSize = resolveMeasuredNativeTerminalSize({
+      layout: layoutRef.current,
+      metrics: metricsRef.current,
+    });
+    const size = measuredSize ?? terminalSizeRef.current;
+    terminalSizeRef.current = size;
+    resizePolicyRef.current = createTerminalResizePolicy(size);
+    outputDecoderRef.current.decode();
+    const terminal = createNativeHeadlessTerminal({
+      rows: size.rows,
+      cols: size.cols,
       scrollbackLines,
-      clearSelection,
-    ],
-  );
+      characterWidths,
+    });
+    terminalRef.current = terminal;
+    screenModelRef.current = createNativeTerminalScreenModel({ terminal });
+    const outputDrain = createOutputDrain(terminal);
+    outputDrainRef.current = outputDrain;
+    const screen = resolveTerminalScreen(terminal);
+    commitTerminalScreen(screen);
+    resetInputModeTracker();
+  }, [
+    commitTerminalScreen,
+    createOutputDrain,
+    resetInputModeTracker,
+    resolveTerminalScreen,
+    scrollbackLines,
+    characterWidths,
+    clearSelection,
+  ]);
 
-  const enqueueOutputText = useCallback(
-    (text: string) => {
-      if (text.length === 0) {
-        return;
-      }
-      const inputModeUpdate = inputModeTrackerRef.current.feed(text);
-      if (inputModeUpdate.changed) {
-        emitInputModeChange();
-      }
-      outputDrainRef.current?.enqueueText(text);
-    },
-    [emitInputModeChange],
-  );
+  const enqueueOutputText = useCallback((text: string) => {
+    if (text.length === 0) {
+      return;
+    }
+    outputDrainRef.current?.enqueueText(text);
+  }, []);
 
   const claimActiveTerminalSize = useCallback(() => {
     activeResizeClaimTokenRef.current += 1;
@@ -512,27 +421,7 @@ function NativeTerminalEmulator({
         const text = outputDecoderRef.current.decode(data, { stream: true });
         enqueueOutputText(text);
       },
-      restoreOutput: (data: TerminalOutputData) => {
-        outputDecoderRef.current.decode();
-        resetInputModeTracker();
-        const text = outputDecoderRef.current.decode(data, { stream: false });
-        outputDrainRef.current?.restoreText(text);
-      },
-      renderSnapshot: (state: TerminalState | null) => {
-        outputDecoderRef.current.decode();
-        resetInputModeTracker();
-        if (!state) {
-          resetTerminal(null);
-          return;
-        }
-        clearSelection();
-        const outputDrain = outputDrainRef.current;
-        if (!outputDrain) {
-          resetTerminal(state);
-          return;
-        }
-        outputDrain.restoreSnapshot(state);
-      },
+      replay: (event) => outputDrainRef.current?.replay(event),
       paste: (text: string) => {
         if (text.length === 0) {
           return;
@@ -563,7 +452,6 @@ function NativeTerminalEmulator({
         screenModelRef.current?.reset();
         clearSelection();
         resetInputModeTracker();
-        terminalRef.current?.reset();
         schedulePaint();
       },
       claimSize: claimActiveTerminalSize,
@@ -582,19 +470,17 @@ function NativeTerminalEmulator({
       claimActiveTerminalSizeForAction,
       clearSelection,
       resetInputModeTracker,
-      resetTerminal,
       schedulePaint,
     ],
   );
 
   useEffect(() => {
     hasNotifiedMeasuredSizeRef.current = false;
-    resetTerminal(mountInputRef.current.initialSnapshot);
-    callbacksRef.current.onRendererReadyChange?.({ streamKey, isReady: true });
+    resetTerminal();
+    emitMeasuredSize({ source: "measure" });
     return () => {
       callbacksRef.current.onRendererReadyChange?.({ streamKey, isReady: false });
-      clearSelectionLongPressTimeout();
-      selectionPressRef.current = null;
+      selectionControllerRef.current?.cancel();
       if (paintFrameRef.current !== null) {
         cancelAnimationFrame(paintFrameRef.current);
         paintFrameRef.current = null;
@@ -604,7 +490,7 @@ function NativeTerminalEmulator({
       terminalRef.current?.dispose();
       terminalRef.current = null;
     };
-  }, [clearSelectionLongPressTimeout, resetTerminal, streamKey]);
+  }, [emitMeasuredSize, resetTerminal, streamKey]);
 
   useEffect(() => {
     if (focusRequestToken <= 0) return;
@@ -661,6 +547,7 @@ function NativeTerminalEmulator({
   const handleCellMetricsChange = useCallback(
     (metrics: TerminalGridCellMetrics) => {
       metricsRef.current = metrics;
+      setCellMetrics(metrics);
       emitMeasuredSize({ source: "measure" });
     },
     [emitMeasuredSize],
@@ -733,14 +620,6 @@ function NativeTerminalEmulator({
       if (!coordinate) {
         return;
       }
-      const existingPress = selectionPressRef.current;
-      selectionPressRef.current = {
-        startX: point.x,
-        startY: point.y,
-        startedAt: existingPress?.startedAt ?? Date.now(),
-        startedWithSelection: existingPress?.startedWithSelection ?? false,
-        status: "selecting",
-      };
       const bounds = terminal.getBufferBounds();
       const wordSelection = resolveTerminalWordSelection({ terminal, coordinate });
       let snapshot = selectionModelRef.current.begin({
@@ -755,222 +634,61 @@ function NativeTerminalEmulator({
     [commitSelectionRange, resolveSelectionCoordinate],
   );
 
-  const updateSelectionAtPoint = useCallback(
-    (point: { x: number; y: number }) => {
-      const terminal = terminalRef.current;
-      if (!terminal || selectionPressRef.current?.status !== "selecting") {
-        return;
-      }
-      const coordinate = resolveSelectionCoordinate(point);
-      if (!coordinate) {
-        return;
-      }
-      const snapshot = selectionModelRef.current.update({
-        coordinate,
-        bounds: terminal.getBufferBounds(),
-      });
-      commitSelectionRange(snapshot.range);
-    },
-    [commitSelectionRange, resolveSelectionCoordinate],
-  );
-
-  const handlePanResponderScroll = useCallback(
-    (currentDy: number) => {
-      const cellHeight = metricsRef.current?.cellHeight;
-      if (!cellHeight || cellHeight <= 0) {
-        return;
-      }
-      const panState = panStateRef.current;
-      const update = advanceTerminalScrollGesture({
-        state: panState,
-        currentDy,
-        cellHeight,
-      });
-      panState.lastDy = update.state.lastDy;
-      panState.rowRemainder = update.state.rowRemainder;
-      panState.didScroll = update.state.didScroll;
-      const { rowDelta } = update;
-      if (rowDelta === 0) {
-        return;
-      }
-      if (rowDelta > 0) {
-        applyScroll("up", rowDelta);
-        return;
-      }
-      applyScroll("down", Math.abs(rowDelta));
-    },
-    [applyScroll],
+  const selectionController = useMemo(
+    () =>
+      createTerminalSelectionController({
+        getGeometry: () => {
+          const viewport = resolveSelectionViewport();
+          const metrics = metricsRef.current;
+          return viewport && metrics
+            ? { range: selectionRangeRef.current, viewport, metrics }
+            : null;
+        },
+        onBeginHandle: (endpoint, cols) =>
+          selectionModelRef.current.beginEndpointDrag(endpoint, cols),
+        onMoveHandle: (coordinate) => {
+          const terminal = terminalRef.current;
+          if (!terminal) return;
+          commitSelectionRange(
+            selectionModelRef.current.update({ coordinate, bounds: terminal.getBufferBounds() })
+              .range,
+          );
+        },
+        onLongPress: beginSelectionAtPoint,
+        onTap: focusTerminalFromTap,
+        onScroll: applyScroll,
+        schedule: (callback, delay) => setTimeout(callback, delay) as unknown as number,
+        cancel: (timer) => clearTimeout(timer),
+      }),
+    [
+      applyScroll,
+      beginSelectionAtPoint,
+      commitSelectionRange,
+      focusTerminalFromTap,
+      resolveSelectionViewport,
+    ],
   );
+  selectionControllerRef.current = selectionController;
 
   const panResponder = useMemo(
     () =>
       PanResponder.create({
         onStartShouldSetPanResponder: () => true,
         onStartShouldSetPanResponderCapture: () => true,
-        onMoveShouldSetPanResponder: (_event, gesture) => {
-          const intent = classifyTerminalGestureIntent({
-            status: selectionRangeRef.current ? "selecting" : "pressing",
-            dx: gesture.dx,
-            dy: gesture.dy,
-            vx: gesture.vx,
-            vy: gesture.vy,
-          });
-          return intent === "scroll" || intent === "select";
-        },
-        onMoveShouldSetPanResponderCapture: (_event, gesture) => {
-          const intent = classifyTerminalGestureIntent({
-            status: selectionRangeRef.current ? "selecting" : "pressing",
-            dx: gesture.dx,
-            dy: gesture.dy,
-            vx: gesture.vx,
-            vy: gesture.vy,
-          });
-          return intent === "scroll" || intent === "select";
-        },
         onPanResponderGrant: (event) => {
-          panStateRef.current = {
-            lastDy: 0,
-            rowRemainder: 0,
-            didScroll: false,
-            didNavigate: false,
-            movedBeyondTapTolerance: false,
-            intent: null,
-          };
-          const point = {
-            x: event.nativeEvent.locationX,
-            y: event.nativeEvent.locationY,
-          };
-          const pressStatus = selectionRangeRef.current ? "selecting" : "pressing";
-          selectionPressRef.current = {
-            startX: point.x,
-            startY: point.y,
-            startedAt: Date.now(),
-            startedWithSelection: pressStatus === "selecting",
-            status: pressStatus,
-          };
-          clearSelectionLongPressTimeout();
-          if (pressStatus === "selecting") {
-            return;
-          }
-          selectionLongPressTimeoutRef.current = setTimeout(() => {
-            selectionLongPressTimeoutRef.current = null;
-            const press = selectionPressRef.current;
-            if (press?.status !== "pressing") {
-              return;
-            }
-            beginSelectionAtPoint({ x: press.startX, y: press.startY });
-          }, TERMINAL_GESTURE_LONG_PRESS_MS);
-        },
-        onPanResponderMove: (event, gesture) => {
-          const selectionPress = selectionPressRef.current;
-          const panState = panStateRef.current;
-          if (Math.hypot(gesture.dx, gesture.dy) > TERMINAL_GESTURE_TAP_TOLERANCE_PX) {
-            panState.movedBeyondTapTolerance = true;
-          }
-          if (selectionPress?.status === "selecting") {
-            if (panState.movedBeyondTapTolerance) {
-              updateSelectionAtPoint(resolvePanResponderPoint(selectionPress, event, gesture));
-            }
-            return;
-          }
-
-          if (panState.intent === "scroll") {
-            handlePanResponderScroll(gesture.dy);
-            return;
-          }
-          if (panState.didNavigate) {
-            return;
-          }
-
-          if (selectionPress?.status === "pressing") {
-            const point = resolvePanResponderPoint(selectionPress, event, gesture);
-            const dx = point.x - selectionPress.startX;
-            const dy = point.y - selectionPress.startY;
-            const intent = classifyTerminalGestureIntent({
-              status: "pressing",
-              dx,
-              dy,
-              vx: gesture.vx,
-              vy: gesture.vy,
-              elapsedMs: Date.now() - selectionPress.startedAt,
-            });
-            if (intent === "tap" || intent === "pending") {
-              return;
-            }
-
-            clearSelectionLongPressTimeout();
-            panState.intent = intent;
-
-            if (intent === "scroll") {
-              selectionPressRef.current = null;
-              handlePanResponderScroll(gesture.dy);
-              return;
-            }
-
-            if (intent === "select") {
-              beginSelectionAtPoint({ x: selectionPress.startX, y: selectionPress.startY });
-              updateSelectionAtPoint(point);
-              return;
-            }
-          }
-        },
-        onPanResponderRelease: (event, gesture) => {
-          clearSelectionLongPressTimeout();
-          const selectionPress = selectionPressRef.current;
-          if (
-            selectionPress?.status === "selecting" &&
-            panStateRef.current.movedBeyondTapTolerance
-          ) {
-            updateSelectionAtPoint(resolvePanResponderPoint(selectionPress, event, gesture));
-          }
-          selectionPressRef.current = null;
-          const { didScroll, didNavigate, movedBeyondTapTolerance } = panStateRef.current;
-          panStateRef.current = {
-            lastDy: 0,
-            rowRemainder: 0,
-            didScroll: false,
-            didNavigate: false,
-            movedBeyondTapTolerance: false,
-            intent: null,
-          };
-          const releaseAction = resolveTerminalGestureReleaseAction({
-            status: selectionPress?.status ?? "idle",
-            startedWithSelection: selectionPress?.startedWithSelection,
-            didScroll,
-            didNavigate,
-            movedBeyondTapTolerance,
-            pressDurationMs: selectionPress ? Date.now() - selectionPress.startedAt : 0,
-            longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-            scrollMode: terminalScreenRef.current?.scroll.mode ?? "following",
-          });
-          if (releaseAction === "select" && selectionPress) {
-            beginSelectionAtPoint({ x: selectionPress.startX, y: selectionPress.startY });
-            return;
-          }
-          if (releaseAction === "focus" || releaseAction === "clear") {
-            focusTerminalFromTap();
-          }
-        },
-        onPanResponderTerminate: () => {
-          clearSelectionLongPressTimeout();
-          selectionPressRef.current = null;
-          panStateRef.current = {
-            lastDy: 0,
-            rowRemainder: 0,
-            didScroll: false,
-            didNavigate: false,
-            movedBeyondTapTolerance: false,
-            intent: null,
-          };
+          const point = { x: event.nativeEvent.locationX, y: event.nativeEvent.locationY };
+          gestureStartRef.current = point;
+          selectionController.press(point);
         },
+        onPanResponderMove: (_event, gesture) =>
+          selectionController.move({
+            x: gestureStartRef.current.x + gesture.dx,
+            y: gestureStartRef.current.y + gesture.dy,
+          }),
+        onPanResponderRelease: () => selectionController.release(),
+        onPanResponderTerminate: () => selectionController.cancel(),
       }),
-    [
-      beginSelectionAtPoint,
-      clearSelectionLongPressTimeout,
-      focusTerminalFromTap,
-      handlePanResponderScroll,
-      updateSelectionAtPoint,
-    ],
+    [selectionController],
   );
 
   const backgroundColor = xtermTheme.background ?? "#0b0b0b";
@@ -981,6 +699,11 @@ function NativeTerminalEmulator({
 
   const terminalState = terminalScreen?.viewport ?? null;
   const isScrolled = terminalScreen?.scroll.mode === "scrolled";
+  const viewport = resolveSelectionViewport();
+  const handles =
+    viewport && cellMetrics
+      ? terminalSelectionHandles({ range: selectionRange, viewport, metrics: cellMetrics })
+      : [];
   const terminalGrid = terminalState ? (
     <TerminalGridView
       state={terminalState}
@@ -997,6 +720,41 @@ function NativeTerminalEmulator({
     <View onLayout={handleLayout} style={rootStyle} testID={testId}>
       <View {...panResponder.panHandlers} accessible={false} style={styles.nativeSurface}>
         {terminalGrid}
+        <View pointerEvents="none" style={StyleSheet.absoluteFill}>
+          {handles.map((handle) => (
+            <View key={handle.endpoint}>
+              <View
+                style={[
+                  styles.selectionStem,
+                  {
+                    left: Math.max(
+                      0,
+                      Math.min(handle.x - 1, viewport!.cols * cellMetrics!.cellWidth - 2),
+                    ),
+                    top: handle.stemTop,
+                    height: handle.stemHeight,
+                  },
+                ]}
+              />
+              <Svg
+                width={TERMINAL_SELECTION_GRIP_SIZE}
+                height={TERMINAL_SELECTION_GRIP_SIZE}
+                viewBox="0 0 18 18"
+                style={[styles.selectionGrip, { left: handle.gripX - 9, top: handle.gripY - 9 }]}
+              >
+                <Path
+                  fill="#2684ff"
+                  d={
+                    handle.gripDirection === "left"
+                      ? "M18 0H9C4 0 0 4 0 9S4 18 9 18 18 14 18 9Z"
+                      : "M0 0H9C14 0 18 4 18 9S14 18 9 18 0 14 0 9Z"
+                  }
+                  transform={handle.gripAbove ? "translate(0 18) scale(1 -1)" : undefined}
+                />
+              </Svg>
+            </View>
+          ))}
+        </View>
         <TerminalInput
           ref={inputRef}
           isKeyboardVisible={isKeyboardVisible}
@@ -1039,6 +797,8 @@ const styles = StyleSheet.create({
   nativeGrid: {
     flex: 1,
   },
+  selectionGrip: { position: "absolute" },
+  selectionStem: { position: "absolute", width: 2, backgroundColor: "#2684ff" },
   followButton: {
     position: "absolute",
     right: 12,
diff --git a/packages/app/src/components/terminal-emulator.tsx b/packages/app/src/components/terminal-emulator.tsx
index 3d272fb75e..7504843c54 100644
--- a/packages/app/src/components/terminal-emulator.tsx
+++ b/packages/app/src/components/terminal-emulator.tsx
@@ -19,7 +19,6 @@ import type { DOMProps } from "expo/dom";
 import { useDOMImperativeHandle, type DOMImperativeFactory } from "expo/dom";
 import "@xterm/xterm/css/xterm.css";
 import type { ITheme } from "@xterm/xterm";
-import type { TerminalState } from "@getpaseo/protocol/messages";
 import type { TerminalInputModeState } from "@getpaseo/protocol/terminal-input-mode";
 import type { PendingTerminalModifiers } from "../utils/terminal-keys";
 import {
@@ -28,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,
@@ -40,8 +40,7 @@ import { focusWithRetries } from "../utils/web-focus";
 export interface TerminalEmulatorHandle {
   find?: TerminalFindHandle;
   writeOutput: (data: TerminalOutputData) => void;
-  restoreOutput: (data: TerminalOutputData) => void;
-  renderSnapshot: (state: TerminalState | null) => void;
+  replay: (event: import("@getpaseo/client").TerminalReplayEvent) => void;
   paste: (text: string) => void;
   copySelection: (clipboard: TerminalClipboardWriter) => Promise<string>;
   clear: () => void;
@@ -98,6 +97,7 @@ interface TerminalEmulatorProps {
   ref: Ref<TerminalEmulatorHandle>;
   streamKey: string;
   supportsTerminalInputModeReplay: boolean;
+  characterWidths: TerminalCharacterWidths;
   testId?: string;
   xtermTheme?: ITheme;
   scrollbackLines: number;
@@ -108,7 +108,6 @@ interface TerminalEmulatorProps {
   swipeGesturesEnabled?: boolean;
   onSwipeLeft?: () => void;
   onSwipeRight?: () => void;
-  initialSnapshot?: TerminalState | null;
   onFindRequest?: () => void;
   onFindResult?: (result: TerminalFindResult) => void;
   onInput?: (data: string) => Promise<void> | void;
@@ -147,16 +146,6 @@ declare global {
   interface Window {}
 }
 
-function isTerminalState(value: unknown): value is TerminalState {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    "rows" in value &&
-    "cols" in value &&
-    "grid" in value
-  );
-}
-
 export default function TerminalEmulator({
   ref,
   streamKey,
@@ -167,12 +156,12 @@ export default function TerminalEmulator({
     cursor: "#e6e6e6",
   },
   scrollbackLines,
+  characterWidths,
   fontFamily,
   fontSize,
   swipeGesturesEnabled = false,
   onSwipeLeft,
   onSwipeRight,
-  initialSnapshot = null,
   onFindRequest,
   onFindResult,
   onInput,
@@ -197,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]);
@@ -228,8 +219,6 @@ export default function TerminalEmulator({
     onOpenLocalFileLink,
     onFilePaste,
   };
-  const initialSnapshotRef = useRef(initialSnapshot);
-  initialSnapshotRef.current = initialSnapshot;
   const pendingModifiersRef = useRef(pendingModifiers);
   pendingModifiersRef.current = pendingModifiers;
 
@@ -253,17 +242,17 @@ export default function TerminalEmulator({
         const data = args[0];
         if (data instanceof Uint8Array) runtimeRef.current?.write({ data });
       },
-      restoreOutput: (...args) => {
-        const data = args[0];
-        if (data instanceof Uint8Array) runtimeRef.current?.restoreOutput({ data });
-      },
-      renderSnapshot: (...args) => {
-        const state = args[0];
-        if (state === null) {
-          runtimeRef.current?.renderSnapshot({ state: null });
-        } else if (isTerminalState(state)) {
-          runtimeRef.current?.renderSnapshot({ state });
-        }
+      replay: (event) => {
+        if (!event || typeof event !== "object" || Array.isArray(event)) return;
+        if (event.type === "end") runtimeRef.current?.replay({ type: "end" });
+        if (event.type === "data" && event.data instanceof Uint8Array)
+          runtimeRef.current?.replay({ type: "data", data: event.data });
+        if (event.type === "begin")
+          runtimeRef.current?.replay({
+            type: "begin",
+            rows: typeof event.rows === "number" ? event.rows : undefined,
+            cols: typeof event.cols === "number" ? event.cols : undefined,
+          });
       },
       paste: (...args) => {
         const text = args[0];
@@ -299,12 +288,7 @@ export default function TerminalEmulator({
       writeOutput: (data: TerminalOutputData) => {
         runtimeRef.current?.write({ data });
       },
-      restoreOutput: (data: TerminalOutputData) => {
-        runtimeRef.current?.restoreOutput({ data });
-      },
-      renderSnapshot: (state: TerminalState | null) => {
-        runtimeRef.current?.renderSnapshot({ state });
-      },
+      replay: (event) => runtimeRef.current?.replay(event),
       paste: (text: string) => {
         pasteText(text);
       },
@@ -336,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) {
@@ -468,10 +456,10 @@ export default function TerminalEmulator({
       },
     });
     runtime.setPendingModifiers({ pendingModifiers: pendingModifiersRef.current });
+    runtime.setCharacterWidths({ widths: characterWidthsRef.current });
     runtime.mount({
       root,
       host,
-      initialSnapshot: initialSnapshotRef.current,
       scrollback: scrollbackLinesRef.current,
       theme: mountedThemeRef.current,
       fontFamily: fontFamilyRef.current,
diff --git a/packages/app/src/components/terminal-pane.tsx b/packages/app/src/components/terminal-pane.tsx
index 6c1561bc5b..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";
@@ -15,7 +16,6 @@ import Animated, { runOnJS, useAnimatedReaction } from "react-native-reanimated"
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { Keyboard as KeyboardIcon, KeyboardOff as KeyboardOffIcon } from "lucide-react-native";
 import type { TerminalKeyInput } from "@getpaseo/protocol/terminal-key-input";
-import type { TerminalState } from "@getpaseo/protocol/messages";
 import {
   DEFAULT_TERMINAL_INPUT_MODE_STATE,
   type TerminalInputModeState,
@@ -60,7 +60,6 @@ import { getDesktopHost } from "@/desktop/host";
 import { routeTerminalDrop } from "@/terminal/drop/terminal-file-drop";
 import { prepareDroppedPathsForTerminal } from "@/terminal/drop/terminal-path";
 import { toErrorMessage } from "@/utils/error-messages";
-import { getWorkspaceTerminalSession } from "@/terminal/runtime/workspace-terminal-session";
 import {
   EMPTY_FOCUS_CLAIM_STATE,
   canRequestFocusClaim,
@@ -85,10 +84,10 @@ import {
 } from "./terminal-resize-debouncer";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative } from "@/constants/platform";
+import { useKeyboardFocusSurface } from "@/keyboard";
 import {
   applyTerminalRendererReadyChange,
   resolveTerminalStreamTarget,
-  shouldReplayTerminalSnapshotForRenderer,
   shouldShowTerminalLoadingOverlay,
   type TerminalRendererReadyChange,
 } from "@/utils/terminal-renderer-readiness";
@@ -307,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]);
@@ -316,10 +320,6 @@ export function TerminalPane({
   const measuredTerminalSizeRef = useRef<{ rows: number; cols: number } | null>(null);
   const lastSentTerminalSizeRef = useRef<{ rows: number; cols: number } | null>(null);
   const streamControllerRef = useRef<TerminalStreamController | null>(null);
-  const workspaceTerminalSession = useMemo(
-    () => getWorkspaceTerminalSession({ scopeKey }),
-    [scopeKey],
-  );
   const [isAttaching, setIsAttaching] = useState(false);
   const [streamError, setStreamError] = useState<string | null>(null);
   const [rendererReadyStreamKey, setRendererReadyStreamKey] = useState<string | null>(null);
@@ -383,7 +383,6 @@ export function TerminalPane({
   const keyboardRefitTimeoutsRef = useRef<Array<ReturnType<typeof setTimeout>>>([]);
   const lastAutoFocusKeyRef = useRef<string | null>(null);
   const paneFocusResizeClaimRef = useRef(EMPTY_FOCUS_CLAIM_STATE);
-  const initialSnapshot = workspaceTerminalSession.snapshots.get({ terminalId });
 
   useEffect(() => {
     terminalIdRef.current = terminalId;
@@ -441,16 +440,8 @@ export function TerminalPane({
     (change: TerminalRendererReadyChange) => {
       if (!change.isReady && change.streamKey === terminalStreamKey) findRef.current?.reset();
       setRendererReadyStreamKey((current) => applyTerminalRendererReadyChange(current, change));
-      if (!shouldReplayTerminalSnapshotForRenderer({ change, terminalStreamKey })) {
-        return;
-      }
-
-      const snapshot = workspaceTerminalSession.snapshots.get({ terminalId });
-      if (snapshot) {
-        emulatorRef.current?.renderSnapshot(snapshot);
-      }
     },
-    [terminalId, terminalStreamKey, workspaceTerminalSession.snapshots],
+    [terminalStreamKey],
   );
 
   useEffect(() => {
@@ -468,6 +459,8 @@ export function TerminalPane({
     }
   }, [isMobile, isPaneFocused, isWorkspaceFocused, requestTerminalFocus, scopeKey, terminalId]);
 
+  useKeyboardFocusSurface("terminal", isTerminalPresented && isPaneFocused && terminalId != null);
+
   useEffect(() => {
     const canRequest = canRequestFocusClaim({
       isWorkspaceFocused: isTerminalPresented,
@@ -564,7 +557,6 @@ export function TerminalPane({
   );
 
   const handleStreamExit = useStableEvent((exitedTerminalId: string) => {
-    workspaceTerminalSession.snapshots.clear({ terminalId: exitedTerminalId });
     if (terminalIdRef.current === exitedTerminalId) emulatorRef.current?.clear();
     setModifiers({ ...EMPTY_MODIFIERS });
   });
@@ -604,29 +596,10 @@ export function TerminalPane({
     },
   );
 
-  const handleStreamRestore = useStableEvent(
-    ({ terminalId: restoreTerminalId, data }: { terminalId: string; data: Uint8Array }) => {
-      workspaceTerminalSession.snapshots.clear({ terminalId: restoreTerminalId });
-      if (terminalIdRef.current !== restoreTerminalId) {
-        return;
-      }
-      emulatorRef.current?.restoreOutput(data);
-    },
-  );
-
-  const handleStreamSnapshot = useStableEvent(
-    ({ terminalId: snapshotTerminalId, state }: { terminalId: string; state: TerminalState }) => {
-      workspaceTerminalSession.snapshots.set({ terminalId: snapshotTerminalId, state });
-      if (terminalIdRef.current !== snapshotTerminalId) {
-        return;
-      }
-      emulatorRef.current?.renderSnapshot(state);
-    },
-  );
-
   const getStreamRestoreOptions = useStableEvent(() =>
     resolveTerminalRestoreOptions({
       supportsTerminalRestoreModes,
+      scrollbackLines: settings.terminalScrollbackLines,
       canClaimSize: canRequestFocusClaim({
         isWorkspaceFocused: terminalPresentedRef.current,
         isPaneFocused,
@@ -653,8 +626,9 @@ export function TerminalPane({
       client,
       getPreferredSize: getPreferredStreamSize,
       onOutput: handleStreamOutput,
-      onRestore: handleStreamRestore,
-      onSnapshot: handleStreamSnapshot,
+      onReplay: ({ terminalId: id, replay }) => {
+        if (terminalIdRef.current === id) emulatorRef.current?.replay(replay);
+      },
       onExit: handleStreamExit,
       getRestoreOptions: getStreamRestoreOptions,
       onStatusChange: handleStreamControllerStatus,
@@ -674,8 +648,6 @@ export function TerminalPane({
     getStreamRestoreOptions,
     handleStreamControllerStatus,
     handleStreamOutput,
-    handleStreamRestore,
-    handleStreamSnapshot,
     handleStreamExit,
     isConnected,
   ]);
@@ -1208,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}
@@ -1216,7 +1189,6 @@ export function TerminalPane({
             keyboardInset={keyboardInset}
             isKeyboardVisible={isKeyboardVisible}
             swipeGesturesEnabled={swipeGesturesEnabled}
-            initialSnapshot={initialSnapshot}
             onRendererReadyChange={handleRendererReadyChange}
             onSwipeRight={handleSwipeRight}
             onSwipeLeft={handleSwipeLeft}
diff --git a/packages/app/src/components/toast-host.tsx b/packages/app/src/components/toast-host.tsx
index d9c8001f50..81020210d9 100644
--- a/packages/app/src/components/toast-host.tsx
+++ b/packages/app/src/components/toast-host.tsx
@@ -1,3 +1,7 @@
+import {
+  FloatingHeaderOverlay,
+  useFloatingHeaderOverlayClearance,
+} from "@/components/floating-header";
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { createPortal } from "react-dom";
 import {
@@ -31,6 +35,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 +47,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. */
@@ -74,40 +81,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 +146,7 @@ export function useToastHost(): {
 
   const dismiss = useCallback(() => {
     setToast(null);
-  }, []);
+  }, [setToast]);
 
   return { api, toast, dismiss };
 }
@@ -190,9 +213,11 @@ 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
@@ -220,7 +245,7 @@ export function ToastViewport({
     return createPortal(content, getOverlayRoot());
   }
 
-  return content;
+  return placement === "panel" ? <FloatingHeaderOverlay>{content}</FloatingHeaderOverlay> : content;
 }
 
 function ToastCard({
diff --git a/packages/app/src/components/tool-call-details.tsx b/packages/app/src/components/tool-call-details.tsx
index a10bd7b0c6..5e08f944df 100644
--- a/packages/app/src/components/tool-call-details.tsx
+++ b/packages/app/src/components/tool-call-details.tsx
@@ -64,7 +64,7 @@ function resolveShouldFill(
 ): boolean {
   if (!fillAvailableHeight) return false;
   const t = detail?.type;
-  return t === "shell" || t === "edit" || t === "write" || t === "read" || t === "sub_agent";
+  return t === "shell" || t === "edit" || t === "write" || t === "read";
 }
 
 function useDetailStyles(
@@ -186,184 +186,6 @@ function ShellDetailSection({ command, output, ds }: ShellDetailProps) {
   );
 }
 
-function resolveSubAgentFallbackHeader(
-  subAgentType: string | null | undefined,
-  description: string | null | undefined,
-  fallbackText: string,
-): string {
-  if (subAgentType && description) {
-    return `${subAgentType}: ${description}`;
-  }
-  return subAgentType ?? description ?? fallbackText;
-}
-
-interface SubAgentDetailProps {
-  log: string;
-  childSessionId: string | null | undefined;
-  subAgentType: string | null | undefined;
-  description: string | null | undefined;
-  ds: DetailStyles;
-}
-
-interface SubAgentActivityRow {
-  index: number;
-  toolName: string;
-  summary?: string;
-}
-
-interface ParsedSubAgentLog {
-  actions: SubAgentActivityRow[];
-  remainingLog: string;
-}
-
-function parseBracketedSubAgentLine(line: string, index: number): SubAgentActivityRow | null {
-  const match = line.match(/^\[([^\]]+)\](?:\s+(.*))?$/);
-  if (!match) {
-    return null;
-  }
-  const toolName = match[1]?.trim();
-  if (!toolName) {
-    return null;
-  }
-  const summary = match[2]?.trim();
-  return {
-    index,
-    toolName,
-    ...(summary ? { summary } : {}),
-  };
-}
-
-function parseSubAgentLog(log: string): ParsedSubAgentLog {
-  const actions: SubAgentActivityRow[] = [];
-  const remainingLines: string[] = [];
-  for (const line of log.replace(/^\n+/, "").split("\n")) {
-    const normalizedLine = line.trim();
-    if (!normalizedLine) {
-      continue;
-    }
-    const parsedAction = parseBracketedSubAgentLine(normalizedLine, actions.length + 1);
-    if (parsedAction) {
-      actions.push(parsedAction);
-    } else {
-      remainingLines.push(line);
-    }
-  }
-  return {
-    actions,
-    remainingLog: remainingLines.join("\n").replace(/^\n+/, ""),
-  };
-}
-
-function SubAgentActionRow({ action }: { action: SubAgentActivityRow }) {
-  return (
-    <View style={styles.subAgentActionRow}>
-      <Text selectable style={styles.subAgentActionTool}>
-        {formatSubAgentToolName(action.toolName)}
-      </Text>
-      {action.summary ? (
-        <Text selectable style={styles.subAgentActionSummary}>
-          {action.summary}
-        </Text>
-      ) : null}
-    </View>
-  );
-}
-
-function formatSubAgentToolName(toolName: string): string {
-  const trimmed = toolName.trim();
-  if (!trimmed) {
-    return toolName;
-  }
-  return trimmed
-    .replace(/[._-]+/g, " ")
-    .split(" ")
-    .filter((segment) => segment.length > 0)
-    .map((segment) => `${segment[0]?.toUpperCase() ?? ""}${segment.slice(1)}`)
-    .join(" ");
-}
-
-function SubAgentLogText({
-  activityLog,
-  fallbackHeader,
-  hasActions,
-}: {
-  activityLog: string;
-  fallbackHeader: string;
-  hasActions: boolean;
-}) {
-  if (activityLog.length > 0) {
-    return (
-      <Text selectable style={styles.scrollText}>
-        {activityLog}
-      </Text>
-    );
-  }
-  if (!hasActions) {
-    return (
-      <Text selectable style={styles.scrollText}>
-        {fallbackHeader}
-      </Text>
-    );
-  }
-  return null;
-}
-
-function SubAgentDetailSection({
-  log,
-  childSessionId,
-  subAgentType,
-  description,
-  ds,
-}: SubAgentDetailProps) {
-  const { t } = useTranslation();
-  const { actions, remainingLog } = useMemo(() => parseSubAgentLog(log), [log]);
-  const fallbackHeader = resolveSubAgentFallbackHeader(
-    subAgentType,
-    description,
-    t("toolCallDetails.subAgentActivity"),
-  );
-  const hasActions = actions.length > 0;
-  return (
-    <View style={ds.sectionFillStyle}>
-      <View style={ds.codeBlockFillStyle}>
-        <ScrollView
-          style={ds.codeVerticalScrollStyle}
-          contentContainerStyle={styles.codeVerticalContent}
-          nestedScrollEnabled
-          showsVerticalScrollIndicator
-        >
-          <ScrollView
-            horizontal
-            nestedScrollEnabled
-            showsHorizontalScrollIndicator
-            contentContainerStyle={styles.codeHorizontalContent}
-          >
-            <View style={styles.codeLine} dataSet={CODE_SURFACE_DATASET}>
-              {childSessionId ? (
-                <Text selectable style={styles.subAgentSessionText}>
-                  session {childSessionId}
-                </Text>
-              ) : null}
-              {hasActions ? (
-                <View style={styles.subAgentActions}>
-                  {actions.map((action) => (
-                    <SubAgentActionRow key={action.index} action={action} />
-                  ))}
-                </View>
-              ) : null}
-              <SubAgentLogText
-                activityLog={remainingLog}
-                fallbackHeader={fallbackHeader}
-                hasActions={hasActions}
-              />
-            </View>
-          </ScrollView>
-        </ScrollView>
-      </View>
-    </View>
-  );
-}
-
 interface EditDetailProps {
   diffLines: DiffLine[] | undefined;
   ds: DetailStyles;
@@ -636,19 +458,7 @@ function buildDetailSections(
       <ShellDetailSection key="shell" command={detail.command} output={detail.output} ds={ds} />,
     ];
   }
-  if (detail.type === "worktree_setup") return [];
-  if (detail.type === "sub_agent") {
-    return [
-      <SubAgentDetailSection
-        key="sub-agent"
-        log={detail.log}
-        childSessionId={detail.childSessionId}
-        subAgentType={detail.subAgentType}
-        description={detail.description}
-        ds={ds}
-      />,
-    ];
-  }
+  if (detail.type === "worktree_setup" || detail.type === "sub_agent") return [];
   if (detail.type === "edit") {
     return [<EditDetailSection key="edit" diffLines={diffLines} ds={ds} />];
   }
@@ -900,34 +710,6 @@ const styles = StyleSheet.create((theme) => {
     shellPrompt: {
       color: theme.colors.foregroundMuted,
     },
-    subAgentSessionText: {
-      fontFamily: theme.fontFamily.mono,
-      fontSize: theme.fontSize.code,
-      color: theme.colors.foregroundMuted,
-      lineHeight: 18,
-      marginBottom: theme.spacing[2],
-    },
-    subAgentActions: {
-      gap: theme.spacing[1],
-      marginBottom: theme.spacing[2],
-    },
-    subAgentActionRow: {
-      flexDirection: "row",
-      alignItems: "center",
-      gap: theme.spacing[2],
-    },
-    subAgentActionTool: {
-      fontFamily: theme.fontFamily.mono,
-      fontSize: theme.fontSize.code,
-      color: theme.colors.foregroundMuted,
-      lineHeight: 18,
-    },
-    subAgentActionSummary: {
-      fontFamily: theme.fontFamily.mono,
-      fontSize: theme.fontSize.code,
-      color: theme.colors.foreground,
-      lineHeight: 18,
-    },
     jsonScroll: {
       borderWidth: theme.borderWidth[1],
       borderColor: theme.colors.border,
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..2e1cd6f68f 100644
--- a/packages/app/src/components/ui/anchor.test.ts
+++ b/packages/app/src/components/ui/anchor.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { computePosition, getTransformOrigin, type Rect } from "./anchor";
+import { computePosition, fitSurfaceWidth, getTransformOrigin, 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 };
@@ -97,3 +97,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..96a7518cba 100644
--- a/packages/app/src/components/ui/anchor.ts
+++ b/packages/app/src/components/ui/anchor.ts
@@ -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,
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 abcaf240d6..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,
@@ -168,6 +163,7 @@ export function Button({
   trailing,
   style,
   textStyle,
+  numberOfLines,
   disabled,
   loading = false,
   accessibilityRole,
@@ -177,11 +173,12 @@ export function Button({
   Omit<PressableProps, "style"> & {
     ref?: React.Ref<View>;
     variant?: ButtonVariant;
-    size?: ButtonSize;
+    size?: ControlSize;
     leftIcon?: LeftIcon;
     trailing?: ReactNode;
     style?: StyleProp<ViewStyle>;
     textStyle?: StyleProp<TextStyle>;
+    numberOfLines?: number;
     loading?: boolean;
   }
 >) {
@@ -203,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), []);
@@ -222,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,
@@ -274,10 +265,14 @@ export function Button({
       <ThemedButtonIcon
         loading={loading}
         leftIcon={leftIcon}
-        iconSize={buttonIconSize[size]}
+        iconSize={controlIconSize[size]}
         uniProps={resolveIconMapping()}
       />
-      {children != null ? <Text style={resolvedTextStyle}>{children}</Text> : null}
+      {children != null ? (
+        <Text numberOfLines={numberOfLines} style={resolvedTextStyle}>
+          {children}
+        </Text>
+      ) : null}
       {trailing}
     </Pressable>
   );
diff --git a/packages/app/src/components/ui/combobox.tsx b/packages/app/src/components/ui/combobox.tsx
index 84d76c1083..cee4fc2dea 100644
--- a/packages/app/src/components/ui/combobox.tsx
+++ b/packages/app/src/components/ui/combobox.tsx
@@ -1,3 +1,5 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
+import { Modal } from "@/components/ui/modal";
 import {
   useCallback,
   useEffect,
@@ -12,7 +14,6 @@ import {
   View,
   Text,
   Pressable,
-  Modal,
   ScrollView,
   Platform,
   StatusBar,
@@ -62,12 +63,9 @@ 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 { 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";
@@ -207,7 +205,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 +252,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 +308,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 +522,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 +866,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 +908,7 @@ function resolveInitialActiveIndex(
 }
 
 interface MobileBodyProps {
+  overlayLayer: number;
   isOpen: boolean;
   snapPoints: string[];
   handleIndicatorStyle: { backgroundColor: string };
@@ -938,7 +935,6 @@ interface MobileBodyProps {
   handleSelect: (id: string) => void;
   renderOption: RenderOptionFn | undefined;
   children: ReactNode;
-  safeAreaBottom: number;
 }
 
 function MobileComboboxBody(props: MobileBodyProps): ReactElement | null {
@@ -961,21 +957,6 @@ function MobileComboboxSheet(props: MobileBodyProps): ReactElement {
     () => [styles.comboboxTitle, { color: props.titleColor }],
     [props.titleColor],
   );
-  const { footer, safeAreaBottom } = props;
-  const frameStyle = useMemo(
-    () => [styles.mobileSheetFrame, { paddingBottom: footer ? 0 : safeAreaBottom }],
-    [footer, safeAreaBottom],
-  );
-  const footerStyle = useMemo(
-    () => [styles.footer, { paddingBottom: safeAreaBottom }],
-    [safeAreaBottom],
-  );
-
-  const footerView = useMemo(
-    () => (footer ? <View style={footerStyle}>{footer}</View> : undefined),
-    [footer, footerStyle],
-  );
-
   const body = props.hasChildren ? (
     props.children
   ) : (
@@ -1006,8 +987,8 @@ function MobileComboboxSheet(props: MobileBodyProps): ReactElement {
       keyboardBlurBehavior="none"
       presentation={props.presentation}
     >
-      <SheetVisibleFrame footer={footerView}>
-        <View style={frameStyle}>
+      <OverlayLayerProvider layer={props.overlayLayer}>
+        <ComboboxSheetFrame footer={props.footer}>
           {props.header ? (
             <SheetHeaderView header={props.header} onClose={props.onClose} />
           ) : (
@@ -1045,17 +1026,43 @@ function MobileComboboxSheet(props: MobileBodyProps): ReactElement {
               {body}
             </BottomSheetScrollView>
           )}
-        </View>
-      </SheetVisibleFrame>
+        </ComboboxSheetFrame>
+      </OverlayLayerProvider>
     </IsolatedBottomSheetModal>
   );
 }
 
+/**
+ * Rendered on the far side of the sheet's portal so it clears the screen's bottom inset, not the
+ * one left where the combobox was opened: inside a sheet tab, none is.
+ */
+function ComboboxSheetFrame({ footer, children }: { footer?: ReactNode; children: ReactNode }) {
+  const { bottom: safeAreaBottom } = useSafeAreaInsets();
+  const frameStyle = useMemo(
+    () => [styles.mobileSheetFrame, { paddingBottom: footer ? 0 : safeAreaBottom }],
+    [footer, safeAreaBottom],
+  );
+  const footerStyle = useMemo(
+    () => [styles.footer, { paddingBottom: safeAreaBottom }],
+    [safeAreaBottom],
+  );
+  const footerView = useMemo(
+    () => (footer ? <View style={footerStyle}>{footer}</View> : undefined),
+    [footer, footerStyle],
+  );
+  return (
+    <SheetVisibleFrame footer={footerView}>
+      <View style={frameStyle}>{children}</View>
+    </SheetVisibleFrame>
+  );
+}
+
 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>;
@@ -1182,25 +1189,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.
@@ -1327,7 +1322,6 @@ export function Combobox({
   const isMobile = useIsCompactFormFactor();
   const active = useRetainedPanelActive();
   const floatingLayer = useOverlayLayer("floating");
-  const safeAreaInsets = useSafeAreaInsets();
   const titleColor = theme.colors.foreground;
   const effectiveOptionsPosition = resolveEffectiveOptionsPosition(isMobile, optionsPosition);
   const isDesktopAboveSearch = resolveIsDesktopAboveSearch(isMobile, effectiveOptionsPosition);
@@ -1525,11 +1519,10 @@ export function Combobox({
   );
 
   const handleDesktopKey = useCallback(
-    (key: DesktopKey, event?: KeyboardEvent) => {
+    (key: DesktopKey, event?: KeyboardInputEvent) => {
       return dispatchDesktopKey(
         {
           isOpen,
-          isMobile,
           orderedVisibleOptions,
           activeIndex,
           setActiveIndex,
@@ -1540,7 +1533,7 @@ export function Combobox({
         event,
       );
     },
-    [activeIndex, handleClose, handleSelect, isMobile, isOpen, orderedVisibleOptions],
+    [activeIndex, handleClose, handleSelect, isOpen, orderedVisibleOptions],
   );
 
   useDismissKeyboardOnOpen(isOpen, isMobile);
@@ -1577,12 +1570,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}
@@ -1608,7 +1609,6 @@ export function Combobox({
         emptyText={resolvedEmptyText}
         handleSelect={handleSelect}
         renderOption={renderOption}
-        safeAreaBottom={safeAreaInsets.bottom}
       >
         {children}
       </MobileComboboxBody>
@@ -1623,6 +1623,7 @@ export function Combobox({
       isOpen={isOpen}
       handleClose={handleClose}
       handleDesktopKey={handleDesktopKey}
+      setOverlayScope={setOverlayScope}
       refs={refs}
       shouldUseDesktopFade={shouldUseDesktopFade}
       desktopFrameStyle={desktopFrameStyle}
@@ -1681,7 +1682,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],
@@ -1712,7 +1713,7 @@ const styles = StyleSheet.create((theme) => ({
     opacity: 0.55,
   },
   comboboxItemTrailingSlot: {
-    width: 16,
+    width: densityIconBox("md"),
     alignItems: "center",
     justifyContent: "center",
   },
@@ -1732,7 +1733,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..431bb0434b 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,121 @@ 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("spaces touch toolbar controls by what they paint and keeps the pointer's 4px gap", () => {
+    expect(TOOLBAR_CONTROL_GAPS).toEqual({ touch: 20, pointer: 4 });
+    expect(TOOLBAR_CONTROL_GAP).toEqual({ xs: 20, md: 4 });
+    // A 20pt glyph's disc-sized frame reaches 8 into the gap on each side.
+    expect(toolbarSlot(20)).toEqual({
+      width: TOOLBAR_DISC_SIZE,
+      height: TOOLBAR_DISC_SIZE,
+      marginHorizontal: { xs: -8, md: 0 },
+    });
+  });
+
+  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 +213,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 +331,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..0ec75ad6ab 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,238 @@ 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 it is the visible space between what
+ * the controls paint, because each control lays out at its painted width (`toolbarSlot`).
+ */
+export const TOOLBAR_CONTROL_GAPS = { touch: 20, pointer: 4 } satisfies SizingValue;
+export const TOOLBAR_CONTROL_GAP = bySizing(TOOLBAR_CONTROL_GAPS);
+
+/**
+ * A toolbar control's frame: a disc-sized circle, which is also its fully rounded highlight.
+ * Touch-sized it lays out at the width of the glyph it paints, `shapeWidth`, and the circle reaches
+ * into the gaps on either side, so the row spaces what you see. Pointer-sized it is the square
+ * control.
+ */
+export function toolbarSlot(shapeWidth: number): {
+  width: LayoutValue;
+  height: LayoutValue;
+  marginHorizontal: LayoutValue;
+} {
+  return {
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
+    marginHorizontal: bySizing({
+      touch: (shapeWidth - TOOLBAR_DISC_SIZES.touch) / 2,
+      pointer: 0,
+    }),
+  };
+}
+
+/**
+ * A toolbar control as wide as its content, such as a labelled picker: a disc-tall pill. Touch-sized
+ * its padding reaches into the gaps, so its content is what the row spaces.
+ */
+export function toolbarContentSlot(padding: number): {
+  height: LayoutValue;
+  paddingHorizontal: number;
+  marginHorizontal: LayoutValue;
+} {
+  return {
+    height: TOOLBAR_DISC_SIZE,
+    paddingHorizontal: padding,
+    marginHorizontal: bySizing({ touch: -padding, pointer: 0 }),
+  };
+}
+
+/**
+ * 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 +281,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 +303,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 +355,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 +388,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 +415,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 +445,8 @@ export function createControlGeometry(theme: Theme) {
       ...fieldControlMd,
       ...fieldTextMd,
     },
-    formTextInput: {
-      ...fieldControlMd,
-      ...fieldTextMd,
-    },
-    fieldControlXs,
     fieldControlSm,
     fieldControlMd,
-    fieldTextXs,
     fieldTextSm,
     fieldTextMd,
     controlRest: {
@@ -311,39 +471,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/edge-fade.tsx b/packages/app/src/components/ui/edge-fade.tsx
index de404aeed8..f5a36ce30b 100644
--- a/packages/app/src/components/ui/edge-fade.tsx
+++ b/packages/app/src/components/ui/edge-fade.tsx
@@ -4,9 +4,10 @@ import Svg, { Defs, LinearGradient as SvgLinearGradient, Rect, Stop } from "reac
 import { withUnistyles } from "react-native-unistyles";
 import type { Theme } from "@/styles/theme";
 
-type EdgeFadeBackdrop = "surface0" | "surfaceWorkspace";
+type EdgeFadeBackdrop = "surface0" | "surfaceWorkspace" | "surface3";
 
 const backdropColorMappings: Record<EdgeFadeBackdrop, (theme: Theme) => { color: string }> = {
+  surface3: (theme) => ({ color: theme.colors.surface3 }),
   surface0: (theme) => ({ color: theme.colors.surface0 }),
   surfaceWorkspace: (theme) => ({ color: theme.colors.surfaceWorkspace }),
 };
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/hover-card.tsx b/packages/app/src/components/ui/hover-card.tsx
index fd81294f80..164120c491 100644
--- a/packages/app/src/components/ui/hover-card.tsx
+++ b/packages/app/src/components/ui/hover-card.tsx
@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import {
   createContext,
   useCallback,
@@ -14,11 +15,7 @@ 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,
@@ -127,7 +124,7 @@ function WebHoverCard({
   }, [clearGraceTimer, disabled]);
 
   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 +136,7 @@ function WebHoverCard({
         return true;
       } else if (
         focusInside() &&
-        event.target === trigger &&
+        document.activeElement === trigger &&
         ["ArrowDown", "Enter", " "].includes(event.key)
       ) {
         event.preventDefault();
@@ -158,7 +155,8 @@ function WebHoverCard({
     [clearGraceTimer, focusInside, open, openNow],
   );
 
-  const setOverlayScope = useWebOverlayRegistration({
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape"],
     active: !disabled && open,
     layer,
     onKeyDown: keyPressed,
@@ -210,9 +208,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);
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 457181c53f..639804bd53 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
@@ -123,19 +123,25 @@ export function useIsolatedBottomSheetVisibility({
   visible,
   isEnabled,
   onClose,
+  onBack,
 }: {
   visible: boolean;
   isEnabled?: boolean;
   onClose: () => void;
+  /** Offered Android Back before it closes the sheet; returns true when it handled the press. */
+  onBack?: () => boolean;
 }) {
   const onCloseRef = useRef(onClose);
   onCloseRef.current = onClose;
+  const onBackRef = useRef(onBack);
+  onBackRef.current = onBack;
 
   const tracker = useMemo(
     () =>
       createBottomSheetVisibilityTracker({
         onClose: () => onCloseRef.current(),
         backPress: systemBackPress,
+        onBack: () => onBackRef.current?.() ?? false,
       }),
     [],
   );
diff --git a/packages/app/src/components/ui/isolated-bottom-sheet-modal/visibility-tracker.test.ts b/packages/app/src/components/ui/isolated-bottom-sheet-modal/visibility-tracker.test.ts
index 60b386bd45..5205fb2486 100644
--- a/packages/app/src/components/ui/isolated-bottom-sheet-modal/visibility-tracker.test.ts
+++ b/packages/app/src/components/ui/isolated-bottom-sheet-modal/visibility-tracker.test.ts
@@ -204,6 +204,31 @@ describe("bottom sheet visibility tracker", () => {
     expect(context.sheet.events).toEqual([{ type: "present" }, { type: "dismiss" }]);
   });
 
+  it("lets the sheet step back through its own pages before Back dismisses it", () => {
+    const sheet = new FakeBottomSheet();
+    const backPress = new FakeBackPress();
+    let openPages = 1;
+    const tracker = createBottomSheetVisibilityTracker({
+      onClose: () => {},
+      onBack: () => {
+        if (openPages === 0) return false;
+        openPages -= 1;
+        return true;
+      },
+      backPress,
+    });
+    tracker.attachController(sheet);
+    tracker.syncDesired({ visible: true });
+    tracker.handleSheetIndexChange(0);
+
+    expect(backPress.press()).toBe(true);
+    expect(openPages).toBe(0);
+    expect(sheet.events).toEqual([{ type: "present" }]);
+
+    expect(backPress.press()).toBe(true);
+    expect(sheet.events).toEqual([{ type: "present" }, { type: "dismiss" }]);
+  });
+
   it("leaves Back to the navigator before the sheet is on screen and after it closes", () => {
     const context = setup();
     context.tracker.attachController(context.sheet);
diff --git a/packages/app/src/components/ui/isolated-bottom-sheet-modal/visibility-tracker.ts b/packages/app/src/components/ui/isolated-bottom-sheet-modal/visibility-tracker.ts
index dec2dd535c..167ed2ebe6 100644
--- a/packages/app/src/components/ui/isolated-bottom-sheet-modal/visibility-tracker.ts
+++ b/packages/app/src/components/ui/isolated-bottom-sheet-modal/visibility-tracker.ts
@@ -36,6 +36,11 @@ type BottomSheetPhase = "closed" | "presenting" | "presented" | "dismissing";
 export function createBottomSheetVisibilityTracker(opts: {
   onClose: () => void;
   backPress?: BackPressSource;
+  /**
+   * Offered the Back press before the sheet takes it as a close. Returns true when it handled
+   * the press itself, such as stepping back a page inside the sheet.
+   */
+  onBack?: () => boolean;
 }): BottomSheetVisibilityTracker {
   let controller: BottomSheetController | null = null;
   let visible = false;
@@ -60,6 +65,7 @@ export function createBottomSheetVisibilityTracker(opts: {
     }
     releaseBackPress =
       opts.backPress?.subscribe(() => {
+        if (opts.onBack?.()) return true;
         dismiss();
         return true;
       }) ?? null;
diff --git a/packages/app/src/components/ui/menu/index.ts b/packages/app/src/components/ui/menu/index.ts
index 5668556899..437090d146 100644
--- a/packages/app/src/components/ui/menu/index.ts
+++ b/packages/app/src/components/ui/menu/index.ts
@@ -12,6 +12,8 @@ export { MenuRoot, MenuTrigger, type MenuTriggerProps, type MenuTriggerState } f
 export {
   MenuSurface,
   useMenuSurface,
+  type MenuFillPageDefinition,
+  type MenuListPageDefinition,
   type MenuPageDefinition,
   type MenuSurfaceProps,
 } from "./menu-surface";
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.test.tsx b/packages/app/src/components/ui/menu/menu-context.test.tsx
index 40b45b9343..5640b7ef82 100644
--- a/packages/app/src/components/ui/menu/menu-context.test.tsx
+++ b/packages/app/src/components/ui/menu/menu-context.test.tsx
@@ -61,3 +61,38 @@ describe("useMenuState selectItem elsewhere", () => {
     expect(onSelect).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("useMenuState pages", () => {
+  it("pops the open page on Back and leaves Back at the root to the surface", () => {
+    const { result } = renderHook(() => useMenuState({ defaultOpen: true }));
+    act(() => result.current.openSub({ id: "row", depth: 0 }));
+
+    let handled = false;
+    act(() => {
+      handled = result.current.goBack();
+    });
+    expect(handled).toBe(true);
+    expect(result.current.path).toEqual([]);
+
+    act(() => {
+      handled = result.current.goBack();
+    });
+    expect(handled).toBe(false);
+    expect(result.current.open).toBe(true);
+  });
+
+  it("falls back to the list when the open page's definition goes away", () => {
+    const { result } = renderHook(() => useMenuState({ defaultOpen: true }));
+    act(() => result.current.openSub({ id: "row", depth: 0 }));
+
+    const keepNoPage = () => false;
+    act(() => result.current.prunePages(keepNoPage));
+
+    expect(result.current.path).toEqual([]);
+    let handled = true;
+    act(() => {
+      handled = result.current.goBack();
+    });
+    expect(handled).toBe(false);
+  });
+});
diff --git a/packages/app/src/components/ui/menu/menu-context.ts b/packages/app/src/components/ui/menu/menu-context.ts
index 9635f09c9f..502580c308 100644
--- a/packages/app/src/components/ui/menu/menu-context.ts
+++ b/packages/app/src/components/ui/menu/menu-context.ts
@@ -7,6 +7,7 @@ import {
   goBack as goBackPath,
   MENU_ROOT_PATH,
   openSubPage,
+  pruneMissingPages,
   type MenuPath,
 } from "./menu-navigation";
 import type { Rect } from "../anchor";
@@ -40,7 +41,10 @@ export interface MenuContextValue {
   path: MenuPath;
   openSub: (sub: { id: string; depth: number }) => void;
   closeSub: (depth: number) => void;
-  goBack: () => void;
+  /** Pops the open page. False at the root, where Back is the surface's to answer. */
+  goBack: () => boolean;
+  /** Closes any open page that no longer has a definition, falling back to its parent. */
+  prunePages: (hasPage: (id: string) => boolean) => void;
 }
 
 const MenuContext = createContext<MenuContextValue | null>(null);
@@ -160,7 +164,13 @@ export function useMenuState({
   }, []);
 
   const goBack = useCallback(() => {
+    if (path.length === 0) return false;
     setPath((current) => goBackPath(current));
+    return true;
+  }, [path.length]);
+
+  const prunePages = useCallback((hasPage: (id: string) => boolean) => {
+    setPath((current) => pruneMissingPages(current, hasPage));
   }, []);
 
   return useMemo(
@@ -176,7 +186,19 @@ export function useMenuState({
       openSub,
       closeSub,
       goBack,
+      prunePages,
     }),
-    [isOpen, setOpen, selectItem, anchorRect, presentation, path, openSub, closeSub, goBack],
+    [
+      isOpen,
+      setOpen,
+      selectItem,
+      anchorRect,
+      presentation,
+      path,
+      openSub,
+      closeSub,
+      goBack,
+      prunePages,
+    ],
   );
 }
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-navigation.test.ts b/packages/app/src/components/ui/menu/menu-navigation.test.ts
index 4b447ef3f2..9740f3df52 100644
--- a/packages/app/src/components/ui/menu/menu-navigation.test.ts
+++ b/packages/app/src/components/ui/menu/menu-navigation.test.ts
@@ -6,6 +6,7 @@ import {
   isSubPageOpen,
   MENU_ROOT_PATH,
   openSubPage,
+  pruneMissingPages,
 } from "./menu-navigation";
 
 describe("openSubPage", () => {
@@ -73,3 +74,15 @@ describe("isSubPageOpen", () => {
     expect(isSubPageOpen(path, { id: "grouping", depth: 0 })).toBe(false);
   });
 });
+
+describe("pruneMissingPages", () => {
+  it("falls back to the deepest page that still exists", () => {
+    expect(pruneMissingPages(["list", "row"], (id) => id === "list")).toEqual(["list"]);
+    expect(pruneMissingPages(["list", "row"], (id) => id === "row")).toEqual([]);
+  });
+
+  it("returns the same path when every page exists", () => {
+    const path = ["list", "row"];
+    expect(pruneMissingPages(path, () => true)).toBe(path);
+  });
+});
diff --git a/packages/app/src/components/ui/menu/menu-navigation.ts b/packages/app/src/components/ui/menu/menu-navigation.ts
index 2cccca9ed1..b38f9acf13 100644
--- a/packages/app/src/components/ui/menu/menu-navigation.ts
+++ b/packages/app/src/components/ui/menu/menu-navigation.ts
@@ -33,6 +33,16 @@ export function closeSubPage(path: MenuPath, depth: number): MenuPath {
   return path.slice(0, depth);
 }
 
+/**
+ * Cuts the path back to the deepest page that still has a definition. A page can lose its
+ * definition while it is open (a subagent's page goes with its row when the subagent is
+ * archived), and the pages it opened go with it.
+ */
+export function pruneMissingPages(path: MenuPath, hasPage: (id: string) => boolean): MenuPath {
+  const missing = path.findIndex((id) => !hasPage(id));
+  return missing === -1 ? path : path.slice(0, missing);
+}
+
 export function goBack(path: MenuPath): MenuPath {
   if (path.length === 0) return path;
   return path.slice(0, -1);
diff --git a/packages/app/src/components/ui/menu/menu-overlay.browser.test.tsx b/packages/app/src/components/ui/menu/menu-overlay.browser.test.tsx
new file mode 100644
index 0000000000..9d60353a52
--- /dev/null
+++ b/packages/app/src/components/ui/menu/menu-overlay.browser.test.tsx
@@ -0,0 +1,124 @@
+import React, { act, useEffect, useState, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { Text, View } from "react-native";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { page } from "vitest/browser";
+import { MenuRoot, MenuSurface, MenuTrigger, type Size } from "./index";
+
+// App sources compile against the classic JSX runtime, which expects React on the global.
+beforeEach(() => vi.stubGlobal("React", React));
+
+/**
+ * A real browser, because the regression lives in Reanimated's web entering path: it snapshots
+ * the surface's rect when a custom keyframe ends and writes that rect back as inline
+ * top/left/width/height when it cleans the keyframe up, 750ms after the animation starts.
+ * Anything that moved or resized the surface in between is undone by that write.
+ */
+
+interface Mounted {
+  root: Root;
+  container: HTMLDivElement;
+}
+
+const mounted: Mounted[] = [];
+
+function mount(node: ReactNode): void {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  act(() => root.render(node));
+  mounted.push({ root, container });
+}
+
+afterEach(() => {
+  for (const entry of mounted.splice(0)) {
+    act(() => entry.root.unmount());
+    entry.container.remove();
+  }
+});
+
+const OFFSET = 12;
+const PILL_POSITION = { position: "absolute", top: 700, left: 40 } as const;
+const SHORT: Size = { width: 200, height: 40 };
+const TALL: Size = { width: 200, height: 240 };
+const WIDE: Size = { width: 480, height: 40 };
+/** Inside the window between the entering animation ending and Reanimated's cleanup. */
+const GROWS_BEFORE_CLEANUP_MS = 400;
+/** Past Reanimated's cleanup, where the surface used to keep a fixed height. */
+const GROWS_AFTER_CLEANUP_MS = 1_000;
+/** Long enough after the content grew for anything that would write to the surface to land. */
+const SETTLE_MS = 1_200;
+
+/** Plain timers, not `act`: an async `act` holds every update until it resolves. */
+function wait(ms: number): Promise<void> {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms));
+}
+
+function element(testID: string): HTMLElement {
+  const found = document.querySelector(`[data-testid="${testID}"]`);
+  if (!(found instanceof HTMLElement)) throw new Error(`${testID} did not render`);
+  return found;
+}
+
+/** Stands in for a popover whose data lands after it opened, like a plugin's first RPC. */
+function GrowsAfterOpen({ afterMs, from, to }: { afterMs: number; from: Size; to: Size }) {
+  const [grown, setGrown] = useState(false);
+  useEffect(() => {
+    const timer = setTimeout(() => setGrown(true), afterMs);
+    return () => clearTimeout(timer);
+  }, [afterMs]);
+  return <View testID="body" style={grown ? to : from} />;
+}
+
+function mountMenuAbovePill(body: ReactNode): void {
+  mount(
+    <View style={PILL_POSITION}>
+      <MenuRoot>
+        <MenuTrigger testID="pill" accessibilityLabel="Open panel">
+          <Text>Open panel</Text>
+        </MenuTrigger>
+        <MenuSurface
+          side="top"
+          align="start"
+          offset={OFFSET}
+          minWidth={280}
+          maxWidth={620}
+          testID="panel"
+        >
+          {body}
+        </MenuSurface>
+      </MenuRoot>
+    </View>,
+  );
+  act(() => element("pill").click());
+}
+
+describe("anchored menu surface on web", () => {
+  beforeEach(async () => {
+    await page.viewport(1280, 900);
+  });
+
+  it.each([GROWS_BEFORE_CLEANUP_MS, GROWS_AFTER_CLEANUP_MS])(
+    "stays on its anchor when its content grows %ims after opening",
+    async (afterMs) => {
+      mountMenuAbovePill(<GrowsAfterOpen afterMs={afterMs} from={SHORT} to={TALL} />);
+
+      await wait(afterMs + SETTLE_MS);
+
+      const pill = element("pill").getBoundingClientRect();
+      const panel = element("panel").getBoundingClientRect();
+      expect(panel.height).toBeGreaterThan(240);
+      expect(panel.bottom).toBeLessThanOrEqual(pill.top);
+    },
+  );
+
+  it("widens when its content widens after the entering animation", async () => {
+    mountMenuAbovePill(<GrowsAfterOpen afterMs={GROWS_BEFORE_CLEANUP_MS} from={SHORT} to={WIDE} />);
+
+    await wait(GROWS_BEFORE_CLEANUP_MS + SETTLE_MS);
+
+    const body = element("body").getBoundingClientRect();
+    const panel = element("panel").getBoundingClientRect();
+    expect(panel.width).toBeGreaterThanOrEqual(body.width);
+  });
+});
diff --git a/packages/app/src/components/ui/menu/menu-overlay.tsx b/packages/app/src/components/ui/menu/menu-overlay.tsx
index 9631dbbe9a..c48fda7156 100644
--- a/packages/app/src/components/ui/menu/menu-overlay.tsx
+++ b/packages/app/src/components/ui/menu/menu-overlay.tsx
@@ -1,7 +1,11 @@
+import { navigateMenuKeyboard } from "./keyboard-navigation";
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
+import { Modal } from "@/components/ui/modal";
 import {
   useCallback,
   useEffect,
   useId,
+  useLayoutEffect,
   useMemo,
   useState,
   type ReactElement,
@@ -11,7 +15,6 @@ import { createPortal } from "react-dom";
 import { useTranslation } from "react-i18next";
 import {
   Dimensions,
-  Modal,
   Platform,
   Pressable,
   View,
@@ -23,14 +26,10 @@ 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,
   measureElement,
   type Alignment,
@@ -47,56 +46,41 @@ const contentEntering = new Keyframe({
   100: { opacity: 1, transform: [{ scale: 1 }] },
 }).duration(CONTENT_ENTERING_DURATION_MS);
 
+/** `contentEntering` for the browser's own animation engine. Both default to linear easing. */
+const WEB_CONTENT_ENTERING_KEYFRAMES: PropertyIndexedKeyframes = {
+  opacity: [0, 1],
+  transform: ["scale(0.97)", "scale(1)"],
+};
+
+/** Web plays the same keyframes itself; see `useWebContentEntering`. */
+const nativeContentEntering = isWeb ? undefined : contentEntering;
+
 const contentExiting = new Keyframe({
   0: { opacity: 1, transform: [{ scale: 1 }] },
   100: { opacity: 0, transform: [{ scale: 0.97 }] },
 }).duration(100);
 
-function releaseFixedMenuHeight(surfaceNativeID: string): void {
-  if (!isWeb) return;
-  document.getElementById(surfaceNativeID)?.style.removeProperty("height");
-}
-
 /**
- * Reanimated's web entering animation leaves an inline height snapshot on the measured surface.
- * Once the menu is open, height must return to content-sized so rows can grow in place — and so
- * a submenu page taller than the page it replaced is not clipped to the old height.
- *
- * `revision` is what makes that second case work: bump it whenever the rendered content changes
- * identity (a page push, for instance) and the snapshot is released again.
+ * On web the surface enters through the Web Animations API rather than Reanimated. Reanimated's
+ * web path snapshots an element's rect when a custom keyframe ends and, when it cleans the keyframe
+ * up 750ms after the start, writes that rect back as inline top/left/width/height. A surface that
+ * moved or resized in between — content that grew once its data arrived — snapped back to the old
+ * rect and stayed there, clipped or hanging past its anchor. A Web Animation leaves no inline style.
  */
-function useReleaseFixedMenuHeight({
-  contentSize,
-  enabled,
+function useWebContentEntering({
+  placed,
   surfaceNativeID,
-  revision,
 }: {
-  contentSize: Size | null;
-  enabled: boolean;
+  placed: boolean;
   surfaceNativeID: string;
-  revision?: string | number;
 }): void {
-  useEffect(() => {
-    if (!enabled) return undefined;
-
-    const release = () => {
-      releaseFixedMenuHeight(surfaceNativeID);
-      if (typeof requestAnimationFrame === "function") {
-        requestAnimationFrame(() => releaseFixedMenuHeight(surfaceNativeID));
-      }
-    };
-    const timers: ReturnType<typeof setTimeout>[] = [
-      setTimeout(release, CONTENT_ENTERING_DURATION_MS),
-    ];
-
-    if (contentSize) {
-      timers.push(setTimeout(release, 0));
-    }
-
-    return () => {
-      for (const timer of timers) clearTimeout(timer);
-    };
-  }, [contentSize, enabled, surfaceNativeID, revision]);
+  useLayoutEffect(() => {
+    if (!isWeb || !placed || typeof document === "undefined") return undefined;
+    const animation = document
+      .getElementById(surfaceNativeID)
+      ?.animate(WEB_CONTENT_ENTERING_KEYFRAMES, CONTENT_ENTERING_DURATION_MS);
+    return () => animation?.cancel();
+  }, [placed, surfaceNativeID]);
 }
 
 /**
@@ -224,8 +208,6 @@ export interface AnchoredSurfaceProps {
   fullWidth?: boolean;
   horizontalPadding?: number;
   scrollable?: boolean;
-  /** Bump when the rendered content changes identity, so the height snapshot is released. */
-  revision?: string | number;
   /** A submenu sits inside its parent's overlay and must not paint a second backdrop. */
   backdrop?: boolean;
   /**
@@ -259,7 +241,6 @@ export function AnchoredSurface({
   fullWidth = false,
   horizontalPadding = 16,
   scrollable = false,
-  revision,
   backdrop = true,
   onPointerEnter,
   onPointerLeave,
@@ -269,33 +250,25 @@ export function AnchoredSurface({
 }: AnchoredSurfaceProps): ReactElement | null {
   const { t } = useTranslation();
   const surfaceNativeID = useId();
-  const { position, actualPlacement, contentSize, visibleContentSize, onContentLayout } =
-    useAnchoredPosition({
-      open,
-      anchorRect,
-      anchorRef,
-      side,
-      align,
-      offset,
-      scrollable,
-      maxHeight,
-    });
-
-  useReleaseFixedMenuHeight({
-    contentSize,
-    enabled: open,
-    surfaceNativeID,
-    revision,
+  const { position, actualPlacement, visibleContentSize, onContentLayout } = useAnchoredPosition({
+    open,
+    anchorRect,
+    anchorRef,
+    side,
+    align,
+    offset,
+    scrollable,
+    maxHeight,
   });
 
   // The surface is placed once both measurements land. Until then it sits off-screen so it can
-  // be measured, and it must not animate: Reanimated's web entering path snapshots the element's
-  // rect when the animation ends and writes that rect back as inline top/left when it cleans the
-  // keyframe up 750ms later. If the animation ends before placement, the snapshot is the
-  // off-screen rect and the menu jumps back off-screen. Remounting on placement starts the
-  // animation from the final position.
+  // be measured, and it must not animate: an entering animation that ran there would be over
+  // before anyone saw the menu. Remounting on placement starts the native animation from the
+  // final position; web starts its own animation on placement.
   const placed = position !== null;
 
+  useWebContentEntering({ placed, surfaceNativeID });
+
   useEffect(() => {
     if (!isWeb || !open || !placed || typeof document === "undefined") return undefined;
     const frame = requestAnimationFrame(() => {
@@ -311,11 +284,7 @@ export function AnchoredSurface({
     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,
       {
@@ -383,7 +352,7 @@ export function AnchoredSurface({
         dataSet={surfaceDataSet}
         style={styles.content}
         frameStyle={frameStyle}
-        entering={placed ? contentEntering : undefined}
+        entering={placed ? nativeContentEntering : undefined}
         exiting={
           !placed || isWeb || !onExited
             ? undefined
@@ -430,8 +399,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();
@@ -439,44 +408,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,
   });
 
@@ -488,7 +428,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/menu/menu-surface.tsx b/packages/app/src/components/ui/menu/menu-surface.tsx
index 2f73149244..581b620499 100644
--- a/packages/app/src/components/ui/menu/menu-surface.tsx
+++ b/packages/app/src/components/ui/menu/menu-surface.tsx
@@ -19,6 +19,11 @@ import {
   useIsolatedBottomSheetVisibility,
   type ContextBridge,
 } from "@/components/ui/isolated-bottom-sheet-modal";
+import {
+  FULL_SHEET_SNAP_POINTS,
+  SheetBackground,
+  SheetHandle,
+} from "@/components/adaptive-modal-sheet";
 import { SPACING, type Theme } from "@/styles/theme";
 import { useRetainedPanelActive } from "@/components/retained-panel";
 import { useMenuContext, MenuContextProvider } from "./menu-context";
@@ -32,24 +37,6 @@ import type { KeyboardFocusScope } from "@/keyboard/actions";
 const ThemedChevronLeft = withUnistyles(ChevronLeft);
 const mutedIconMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
 
-// `backgroundStyle` and `handleIndicatorStyle` are style-shaped props the Babel plugin does not
-// track, so the sheet is wrapped rather than reading the theme through a hook.
-// See docs/unistyles.md.
-const ThemedBottomSheetModal = withUnistyles(IsolatedBottomSheetModal, (theme) => ({
-  backgroundStyle: {
-    borderTopLeftRadius: theme.borderRadius.xl,
-    borderTopRightRadius: theme.borderRadius.xl,
-    borderWidth: 1,
-    backgroundColor: theme.colors.surface0,
-    borderColor: theme.colors.border,
-  },
-  handleIndicatorStyle: {
-    width: 36,
-    height: 4,
-    backgroundColor: theme.colors.surface2,
-  },
-}));
-
 /** How long the pointer must rest on a submenu row before its flyout opens. */
 const HOVER_OPEN_DELAY_MS = 90;
 /**
@@ -65,7 +52,7 @@ const HOVER_CLOSE_GRACE_MS = 260;
  */
 const SUBMENU_OVERLAP = 5;
 
-export interface MenuPageDefinition {
+export interface MenuListPageDefinition {
   id: string;
   title: string;
   content: ReactNode;
@@ -78,6 +65,24 @@ export interface MenuPageDefinition {
    * surface stops closing on hover, since its parent leads back to the same dismissal.
    */
   hoverIntent?: boolean;
+  fill?: false;
+}
+
+/**
+ * A sheet page that takes the sheet's full height and draws everything itself, header included:
+ * no back header, no scroller, no content panning. Only the sheet presentation opens one; a
+ * popover never has a trigger for it.
+ */
+export interface MenuFillPageDefinition {
+  id: string;
+  fill: true;
+  content: ReactNode;
+}
+
+export type MenuPageDefinition = MenuListPageDefinition | MenuFillPageDefinition;
+
+function pageHoverIntent(page: MenuPageDefinition | undefined): boolean {
+  return !page || page.fill === true || page.hoverIntent !== false;
 }
 
 interface MenuSurfaceContextValue {
@@ -126,8 +131,15 @@ export interface MenuSurfaceProps {
  * popover (plus one flyout per open submenu) or a bottom sheet showing one page at a time.
  */
 export function MenuSurface(props: MenuSurfaceProps): ReactElement | null {
-  const { presentation, open, setOpen } = useMenuContext("MenuSurface");
+  const { presentation, open, setOpen, path, prunePages } = useMenuContext("MenuSurface");
   const active = useRetainedPanelActive();
+  // An open page whose definition went away (its row was removed) falls back to its parent, so
+  // neither a render nor a later Back walks a path to a page that no longer exists.
+  const { pages } = props;
+  useEffect(() => {
+    if (path.length === 0) return;
+    prunePages((id) => pages?.some((page) => page.id === id) ?? false);
+  }, [pages, path, prunePages]);
   // A menu belongs to the panel that opened it. When that panel leaves the screen the menu closes
   // for good, rather than waiting hidden to reappear with the panel: a row that opened a sheet
   // and promoted it to a tab, say, would otherwise bring the list back on the next tab switch.
@@ -234,11 +246,11 @@ function MenuPopoverSurface({
   // `hoverIntent: false` takes a page off the pointer entirely — it is not opened by resting on
   // its trigger, and while it is open nothing on this surface closes on a pointer leaving it.
   const hoverValue = useMemo<MenuSurfaceContextValue>(() => {
-    const locked = openPages.some(({ page }) => page.hoverIntent === false);
+    const locked = openPages.some(({ page }) => !pageHoverIntent(page));
     return {
       ...surfaceValue,
       hoverOpen: (sub) => {
-        if (pages.find((page) => page.id === sub.id)?.hoverIntent === false) return;
+        if (!pageHoverIntent(pages.find((page) => page.id === sub.id))) return;
         surfaceValue.hoverOpen(sub);
       },
       hoverClose: (depth) => {
@@ -332,7 +344,6 @@ function MenuFlyout({
       maxHeight={maxHeight}
       scrollable={scrollable}
       backdrop={false}
-      revision={page.id}
       onPointerEnter={cancelHoverClose}
       onPointerLeave={handleHoverOut}
       testID={testID}
@@ -353,17 +364,6 @@ function MenuSheetSurface({
   const { height: windowHeight } = useWindowDimensions();
   const menu = useMenuContext("MenuSurface");
   const { value: surfaceValue } = useSubAnchors();
-  const safeAreaInsets = useSafeAreaInsets();
-
-  const sheetScrollContentStyle = useMemo(
-    () => ({
-      paddingBottom: getMenuSheetBottomPadding({
-        safeAreaBottom: safeAreaInsets.bottom,
-        breathingRoom: SPACING[1],
-      }),
-    }),
-    [safeAreaInsets.bottom],
-  );
   const sheetDataSet = useMemo(
     () => (keyboardFocusScope ? { keyboardScope: keyboardFocusScope } : undefined),
     [keyboardFocusScope],
@@ -374,11 +374,15 @@ function MenuSheetSurface({
     visible: menu.open,
     isEnabled: true,
     onClose: handleClose,
+    // Android Back steps back through the pages before it closes the sheet.
+    onBack: menu.goBack,
   });
 
   const openPageId = currentPageId(menu.path);
   const openPage = openPageId ? pages.find((page) => page.id === openPageId) : null;
   const depth = menu.path.length;
+  const fillPage = openPage?.fill === true ? openPage : null;
+  const listPage = openPage?.fill === true ? null : openPage;
 
   // The sheet's content is teleported out of this subtree, so both menu contexts have to be
   // rebuilt on the other side. Providing them around the modal instead would put them on the
@@ -393,12 +397,18 @@ function MenuSheetSurface({
   );
 
   return (
-    <ThemedBottomSheetModal
+    <IsolatedBottomSheetModal
       ref={sheetRef}
       contextBridge={contextBridge}
+      backgroundComponent={SheetBackground}
+      handleComponent={SheetHandle}
       // Content-sized rather than fixed snap points: a pushed page is rarely the same height
       // as the page it replaced, and a fixed sheet would either clip it or leave dead space.
-      enableDynamicSizing
+      // A fill page is the exception: it takes the height every full sheet has, and its own
+      // content scrolls, so dragging it would fight that scroll.
+      enableDynamicSizing={!fillPage}
+      snapPoints={fillPage ? FULL_SHEET_SNAP_POINTS : undefined}
+      enableContentPanningGesture={!fillPage}
       maxDynamicContentSize={windowHeight * 0.8}
       onChange={handleSheetChange}
       onDismiss={handleSheetDismiss}
@@ -412,28 +422,64 @@ function MenuSheetSurface({
       keyboardBehavior="interactive"
       keyboardBlurBehavior="restore"
     >
-      <BottomSheetScrollView
-        dataSet={sheetDataSet}
-        contentContainerStyle={sheetScrollContentStyle}
-        keyboardShouldPersistTaps="handled"
-        showsVerticalScrollIndicator={false}
-        testID={testID ? `${testID}-content` : undefined}
-      >
-        {openPage ? (
-          <>
-            <MenuSheetHeader title={openPage.title} onBack={menu.goBack} />
-            <MenuPage depth={depth}>{openPage.content}</MenuPage>
-          </>
-        ) : (
-          <>
-            {sheetTitle ? (
-              <MenuSheetHeader title={sheetTitle} onBack={null} trailing={sheetTrailing} />
-            ) : null}
-            <MenuPage depth={0}>{children}</MenuPage>
-          </>
-        )}
-      </BottomSheetScrollView>
-    </ThemedBottomSheetModal>
+      {fillPage ? (
+        <View style={styles.fillPage} testID={testID ? `${testID}-${fillPage.id}` : undefined}>
+          {fillPage.content}
+        </View>
+      ) : (
+        <MenuSheetScrollView dataSet={sheetDataSet} testID={testID}>
+          {listPage ? (
+            <>
+              <MenuSheetHeader title={listPage.title} onBack={menu.goBack} />
+              <MenuPage depth={depth}>{listPage.content}</MenuPage>
+            </>
+          ) : (
+            <>
+              {sheetTitle ? (
+                <MenuSheetHeader title={sheetTitle} onBack={null} trailing={sheetTrailing} />
+              ) : null}
+              <MenuPage depth={0}>{children}</MenuPage>
+            </>
+          )}
+        </MenuSheetScrollView>
+      )}
+    </IsolatedBottomSheetModal>
+  );
+}
+
+/**
+ * Rendered on the far side of the sheet's portal so it clears the screen's bottom inset, not the
+ * one left where the menu was opened: inside a sheet tab, none is.
+ */
+function MenuSheetScrollView({
+  dataSet,
+  testID,
+  children,
+}: {
+  dataSet: { keyboardScope: KeyboardFocusScope } | undefined;
+  testID?: string;
+  children: ReactNode;
+}) {
+  const safeAreaInsets = useSafeAreaInsets();
+  const contentStyle = useMemo(
+    () => ({
+      paddingBottom: getMenuSheetBottomPadding({
+        safeAreaBottom: safeAreaInsets.bottom,
+        breathingRoom: SPACING[1],
+      }),
+    }),
+    [safeAreaInsets.bottom],
+  );
+  return (
+    <BottomSheetScrollView
+      dataSet={dataSet}
+      contentContainerStyle={contentStyle}
+      keyboardShouldPersistTaps="handled"
+      showsVerticalScrollIndicator={false}
+      testID={testID ? `${testID}-content` : undefined}
+    >
+      {children}
+    </BottomSheetScrollView>
   );
 }
 
@@ -470,6 +516,10 @@ function MenuSheetHeader({
 }
 
 const styles = StyleSheet.create((theme) => ({
+  fillPage: {
+    flex: 1,
+    minHeight: 0,
+  },
   sheetHeader: {
     flexDirection: "row",
     alignItems: "center",
diff --git a/packages/app/src/components/ui/modal.tsx b/packages/app/src/components/ui/modal.tsx
new file mode 100644
index 0000000000..884377fd8c
--- /dev/null
+++ b/packages/app/src/components/ui/modal.tsx
@@ -0,0 +1,13 @@
+import { Modal as NativeModal, type ModalProps } from "react-native";
+
+// React Native defaults iPhone modals to portrait even when the app supports rotation.
+const orientations: NonNullable<ModalProps["supportedOrientations"]> = [
+  "portrait",
+  "portrait-upside-down",
+  "landscape-left",
+  "landscape-right",
+];
+
+export function Modal(props: ModalProps) {
+  return <NativeModal supportedOrientations={orientations} {...props} />;
+}
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 697a80fdcf..99f446001f 100644
--- a/packages/app/src/components/ui/tooltip.tsx
+++ b/packages/app/src/components/ui/tooltip.tsx
@@ -1,3 +1,4 @@
+import { Modal } from "@/components/ui/modal";
 import {
   Children,
   cloneElement,
@@ -16,7 +17,6 @@ import { createPortal } from "react-dom";
 import {
   Dimensions,
   Platform,
-  Modal,
   Pressable,
   View,
   type PressableProps,
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
new file mode 100644
index 0000000000..e7bef2d177
--- /dev/null
+++ b/packages/app/src/components/user-message/index.tsx
@@ -0,0 +1,100 @@
+import { useState, useCallback, useMemo, type ReactNode } from "react";
+import { View, type LayoutChangeEvent, type ViewStyle } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { useTranslation } from "react-i18next";
+import type { AgentMessage } from "@getpaseo/protocol/agent-message";
+import { Button } from "@/components/ui/button";
+import { EdgeFade } from "@/components/ui/edge-fade";
+import { useProviderIcon } from "@/components/provider-icons";
+import { useSessionStore } from "@/stores/session-store";
+import { navigateToAgent } from "@/utils/navigate-to-agent";
+import { isNative } from "@/constants/platform";
+
+const PREVIEW_HEIGHT = 240;
+// 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 = {
+  maxHeight: PREVIEW_HEIGHT,
+  overflow: isNative ? "scroll" : "hidden",
+};
+
+export function MessagePreview({ children }: { children: ReactNode }) {
+  const { t } = useTranslation();
+  const [expanded, setExpanded] = useState(false);
+  const [overflowing, setOverflowing] = useState(false);
+  const measure = useCallback(
+    (event: LayoutChangeEvent) => setOverflowing(event.nativeEvent.layout.height > PREVIEW_HEIGHT),
+    [],
+  );
+  const toggle = useCallback(() => setExpanded((value) => !value), []);
+  const accessibilityState = useMemo(() => ({ expanded }), [expanded]);
+  return (
+    <>
+      <View style={!expanded && previewStyle}>
+        <View style={styles.body} onLayout={measure}>
+          {children}
+        </View>
+        {overflowing && !expanded ? (
+          <EdgeFade edge="bottom" solidFraction={0} backdrop="surface3" style={styles.fade} />
+        ) : null}
+      </View>
+      {overflowing ? (
+        <Button
+          variant="ghost"
+          size="sm"
+          style={[styles.toggle, expanded && styles.expandedToggle]}
+          accessibilityState={accessibilityState}
+          onPress={toggle}
+        >
+          {t(expanded ? "turnSummary.showLess" : "turnSummary.showMore")}
+        </Button>
+      ) : null}
+    </>
+  );
+}
+
+export function MessageSender({
+  sender,
+  serverId,
+}: {
+  sender: AgentMessage["sender"];
+  serverId?: string;
+}) {
+  const { t } = useTranslation();
+  const host = sender.serverId ?? serverId;
+  const agent = useSessionStore((state) => {
+    const session = host ? state.sessions[host] : undefined;
+    return session?.agents.get(sender.id) ?? session?.agentDetails.get(sender.id);
+  });
+  const ProviderIcon = useProviderIcon(agent?.provider ?? "", host);
+  const renderProviderIcon = useCallback(
+    (color: string) => <ProviderIcon size={16} color={color} />,
+    [ProviderIcon],
+  );
+  const openSender = useCallback(() => {
+    if (host) navigateToAgent({ serverId: host, agentId: sender.id });
+  }, [host, sender.id]);
+  return (
+    <Button
+      variant="ghost"
+      size="sm"
+      leftIcon={renderProviderIcon}
+      style={styles.sender}
+      textStyle={styles.senderText}
+      numberOfLines={1}
+      disabled={!host}
+      onPress={openSender}
+    >
+      {t("turnSummary.sentBy", { name: agent?.title ?? sender.title ?? sender.id })}
+    </Button>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  body: { flexShrink: 0 },
+  sender: { paddingRight: 0, borderRightWidth: 0, maxWidth: "100%" },
+  senderText: { flexShrink: 1 },
+  toggle: { alignSelf: "flex-start", paddingHorizontal: 0, minHeight: 0, borderWidth: 0 },
+  expandedToggle: { marginTop: theme.spacing[2] },
+  fade: { position: "absolute", bottom: 0, left: 0, right: 0, height: theme.spacing[12] },
+}));
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-controls/control.tsx b/packages/app/src/composer/agent-controls/control.tsx
index 64b8b39100..c93640206a 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 { TOUCH_ICON_SIZE, 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) => [
@@ -72,11 +76,11 @@ export const AgentControlTrigger = forwardRef<View, AgentControlTriggerProps>(
       >
         {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 +100,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(theme.spacing[2]),
+    borderRadius: theme.borderRadius.full,
     backgroundColor: "transparent",
   },
   toolbarIconOnly: {
-    width: 28,
+    ...toolbarSlot(TOUCH_ICON_SIZE.md),
     flexShrink: 0,
     paddingHorizontal: 0,
     justifyContent: "center",
@@ -159,7 +162,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 +170,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..f86721fb98 100644
--- a/packages/app/src/composer/agent-controls/index.tsx
+++ b/packages/app/src/composer/agent-controls/index.tsx
@@ -61,6 +61,17 @@ import {
   resolveAgentModelSelection,
 } from "@/composer/agent-controls/utils";
 import { useIsCompactFormFactor } from "@/constants/layout";
+import {
+  controlSizingForLayout,
+  TOOLBAR_CONTROL_GAP,
+  bySizing,
+  toolbarGlyphColor,
+  type ToolbarGlyphs,
+  TOUCH_ICON_SIZE,
+  toolbarContentSlot,
+  toolbarSlot,
+} from "@/components/ui/control-geometry";
+import { DensityIcon } from "@/components/ui/density-icon";
 import { readMeasuredWidth } from "@/hooks/use-container-width";
 import { useToast } from "@/contexts/toast-context";
 import { toErrorMessage } from "@/utils/error-messages";
@@ -70,15 +81,17 @@ 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 {
+  ComposerControlLayoutProvider,
+  useComposerControlLayout,
+} from "@/composer/agent-controls/layout-context";
 import { ComposerToolbarGlyph } from "@/composer/agent-controls/glyph";
 import { AgentControlTrigger } from "@/composer/agent-controls/control";
 import { CompactModelSheet } from "@/composer/agent-controls/model-sheet";
@@ -218,10 +231,10 @@ function getFeatureIconColor(
     green: { 400: string };
     yellow: { 400: string };
   },
-  foregroundMuted: string,
+  restColor: string,
 ): string {
   if (!isFeatureActive(feature)) {
-    return foregroundMuted;
+    return restColor;
   }
 
   switch (getFeatureHighlightColor(feature.id)) {
@@ -232,7 +245,7 @@ function getFeatureIconColor(
     case "yellow":
       return palette.yellow[400];
     default:
-      return foregroundMuted;
+      return restColor;
   }
 }
 
@@ -460,6 +473,10 @@ function buildAgentProviderModels(
   return map;
 }
 
+function densityFolds(density: ComposerControlDensity): boolean {
+  return resolveComposerControlPresentation(density).foldControls;
+}
+
 function buildOpenChangeHandler(
   selector: AgentControlSelector,
   setOpenSelector: (next: AgentControlSelector | null) => void,
@@ -503,14 +520,20 @@ 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";
+  // 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);
@@ -574,10 +597,10 @@ function ControlledAgentControls({
   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 +609,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(
@@ -633,10 +664,9 @@ function ControlledAgentControls({
         selected={args.selected}
         active={args.active}
         onPress={args.onPress}
-        iconColor={theme.colors.foreground}
       />
     ),
-    [theme.colors.foreground],
+    [],
   );
 
   const handleOpenChange = useCallback(
@@ -702,8 +732,8 @@ function ControlledAgentControls({
 
   const handleCloseSheet = useCallback(() => {
     setActiveSheet(null);
-    if (!isCompact) onDropdownClose?.();
-  }, [isCompact, onDropdownClose]);
+    if (!presentation.foldControls) onDropdownClose?.();
+  }, [onDropdownClose, presentation.foldControls]);
 
   const handleSelectThinkingAndClose = useCallback(
     (thinkingOptionId: string) => {
@@ -734,7 +764,7 @@ function ControlledAgentControls({
   return (
     <ComposerControlLayoutProvider value={layoutContextValue}>
       <View style={styles.container} onLayout={handleLayout}>
-        {!isCompact ? (
+        {!presentation.foldControls ? (
           <DesktopAgentControlsContent
             provider={provider}
             providerOptions={providerOptions}
@@ -781,7 +811,7 @@ function ControlledAgentControls({
             renderThinkingOption={renderThinkingOption}
             modeControl={modeControl}
             presentation={presentation}
-            glyphSize={layoutContextValue.glyphSize}
+            glyphs={layoutContextValue.glyphs}
             activeSheet={activeSheet}
             handleOpenSheet={handleOpenSheet}
             handleCloseSheet={handleCloseSheet}
@@ -820,7 +850,8 @@ function ControlledAgentControls({
             handleOpenChange={handleSheetOpenChange}
             renderThinkingOption={renderThinkingOption}
             modeControl={modeControl}
-            glyphSize={layoutContextValue.glyphSize}
+            glyphs={layoutContextValue.glyphs}
+            showLabels={presentation.showModelLabel}
             modelSelectorServerId={modelSelectorServerId}
             canSwitchProvider={Boolean(onSelectProviderAndModel)}
           />
@@ -881,7 +912,7 @@ interface DesktopAgentControlsContentProps {
   }) => ReactElement;
   modeControl?: AgentModeControlValue | null;
   presentation: ComposerControlPresentation;
-  glyphSize: number;
+  glyphs: ToolbarGlyphs;
   activeSheet: ActiveSheet;
   handleOpenSheet: (sheet: Exclude<ActiveSheet, null>) => void;
   handleCloseSheet: () => void;
@@ -938,15 +969,15 @@ function DesktopAgentControlsContent(props: DesktopAgentControlsContentProps) {
     renderThinkingOption,
     modeControl,
     presentation,
-    glyphSize,
+    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") }),
@@ -1067,8 +1098,12 @@ 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
@@ -1143,7 +1178,8 @@ interface SheetAgentControlsContentProps {
     onPress: () => void;
   }) => ReactElement;
   modeControl?: AgentModeControlValue | null;
-  glyphSize: number;
+  glyphs: ToolbarGlyphs;
+  showLabels: boolean;
   modelSelectorServerId: string | null;
   canSwitchProvider: boolean;
 }
@@ -1182,7 +1218,8 @@ function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
     handleOpenChange,
     renderThinkingOption,
     modeControl,
-    glyphSize,
+    glyphs,
+    showLabels,
     modelSelectorServerId,
     canSwitchProvider,
   } = props;
@@ -1270,7 +1307,8 @@ function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
       onRetryProvider={onRetryModelProvider}
       isRetryingProvider={isRetryingModelProvider}
       serverId={modelSelectorServerId}
-      glyphSize={glyphSize}
+      glyphs={glyphs}
+      showLabels={showLabels}
       canSwitchProvider={canSwitchProvider}
     >
       {sheetControls}
@@ -1294,6 +1332,8 @@ function DesktopFeatureItem({
   onActionComplete?: () => void;
 }) {
   const { theme } = useUnistyles();
+  const { glyphs } = useComposerControlLayout();
+  const restColor = toolbarGlyphColor(theme, glyphs.icon.tone);
   const featureSelector: AgentControlSelector = `feature-${feature.id}`;
   const featureAnchorRef = useRef<View>(null);
 
@@ -1334,11 +1374,7 @@ function DesktopFeatureItem({
         <TooltipTrigger asChild triggerRefProp="ref">
           <AgentControlTrigger
             icon={FeatureIcon}
-            iconColor={getFeatureIconColor(
-              feature,
-              theme.colors.palette,
-              theme.colors.foregroundMuted,
-            )}
+            iconColor={getFeatureIconColor(feature, theme.colors.palette, restColor)}
             surface="toolbar"
             label={feature.label}
             showToolbarLabel={false}
@@ -1369,11 +1405,7 @@ function DesktopFeatureItem({
             <AgentControlTrigger
               ref={featureAnchorRef}
               icon={FeatureIcon}
-              iconColor={getFeatureIconColor(
-                feature,
-                theme.colors.palette,
-                theme.colors.foregroundMuted,
-              )}
+              iconColor={getFeatureIconColor(feature, theme.colors.palette, restColor)}
               surface="toolbar"
               label={feature.label}
               value={selectedOption?.label ?? feature.label}
@@ -1529,15 +1561,16 @@ function ThinkingComboboxOption({
   selected,
   active,
   onPress,
-  iconColor,
 }: {
   option: ComboboxOption;
   selected: boolean;
   active: boolean;
   onPress: () => void;
-  iconColor: string;
 }) {
-  const leadingSlot = useMemo(() => <ThinkingIcon size={16} color={iconColor} />, [iconColor]);
+  const leadingSlot = useMemo(
+    () => <DensityIcon icon={ThinkingIcon} size="md" color="foreground" />,
+    [],
+  );
   return (
     <ComboboxItem
       label={option.label}
@@ -1949,17 +1982,20 @@ 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. Touch-sized the pickers' pills and circles reach 8 past
+    // what the row spaces, so the clip reaches as far.
     overflow: "hidden",
+    paddingHorizontal: bySizing({ touch: theme.spacing[2], pointer: 0 }),
+    marginHorizontal: bySizing({ touch: -theme.spacing[2], pointer: 0 }),
   },
   modeBadge: {
-    height: 28,
     flexDirection: "row",
     alignItems: "center",
     backgroundColor: "transparent",
     gap: theme.spacing[1],
-    paddingHorizontal: theme.spacing[2],
-    borderRadius: theme.borderRadius["2xl"],
+    ...toolbarContentSlot(theme.spacing[2]),
+    borderRadius: theme.borderRadius.full,
   },
   modelControl: {
     minWidth: 0,
@@ -1971,8 +2007,7 @@ const styles = StyleSheet.create((theme) => ({
     flexShrink: 0,
   },
   modeIconBadge: {
-    width: 28,
-    height: 28,
+    ...toolbarSlot(TOUCH_ICON_SIZE.md),
     alignItems: "center",
     justifyContent: "center",
     paddingHorizontal: 0,
@@ -1984,7 +2019,7 @@ const styles = StyleSheet.create((theme) => ({
     backgroundColor: theme.colors.surface2,
   },
   modeBadgePressed: {
-    backgroundColor: theme.colors.surface0,
+    backgroundColor: theme.colors.surface2,
   },
   disabledBadge: {
     opacity: 0.5,
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..906bc0c48f 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,
     });
   });
 
@@ -41,6 +54,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 420,
         currentDensity: "full",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("full");
@@ -48,6 +62,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 380,
         currentDensity: "full",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("condensed");
@@ -55,6 +70,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 290,
         currentDensity: "condensed",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("condensed");
@@ -62,6 +78,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 280,
         currentDensity: "condensed",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("tight");
@@ -69,6 +86,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 300,
         currentDensity: "tight",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("tight");
@@ -76,6 +94,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 312,
         currentDensity: "tight",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("condensed");
@@ -85,6 +104,7 @@ describe("composer control layout", () => {
     const base = {
       availableWidth: 430,
       currentDensity: "condensed" as const,
+      geometry: POINTER,
     };
 
     expect(
@@ -129,6 +149,7 @@ describe("composer control layout", () => {
     const base = {
       availableWidth: 430,
       currentDensity: "full" as const,
+      geometry: POINTER,
       controls: {
         hasModel: true,
         hasThinking: true,
@@ -154,15 +175,166 @@ describe("composer control layout", () => {
     ).toBe("condensed");
   });
 
-  it("gives every toolbar control one shell and one platform glyph envelope", () => {
-    expect(COMPOSER_TOOLBAR_GEOMETRY).toEqual({
+  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: 20,
+      glyphs: {
+        icon: { size: 20, strokeWidth: 1.5, tone: "foreground" },
+        label: { size: 20, strokeWidth: 1.5, tone: "foreground" },
+      },
+      controlGap: 20,
+    });
+  });
+
+  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,
+      },
+    };
+
+    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 what they
+    // paint, 20pt apart, so icon-only thinking, mode and features need 200.
+    const controls = {
+      hasModel: true,
+      hasThinking: true,
+      hasMode: true,
+      features: [{ type: "toggle" as const }, { type: "toggle" as const }],
+      fontScale: 1,
+    };
+
+    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,
+      },
+    };
+
+    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..ec6a5b8f26 100644
--- a/packages/app/src/composer/agent-controls/layout.ts
+++ b/packages/app/src/composer/agent-controls/layout.ts
@@ -1,4 +1,25 @@
-export type ComposerControlDensity = "full" | "condensed" | "tight";
+import {
+  TOOLBAR_CONTROL_GAPS,
+  TOOLBAR_CONTROL_SIZES,
+  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;
@@ -15,27 +36,53 @@ export interface ComposerControlPresentation {
   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, as far as it takes room in the row. */
+  labelPadding: number;
+  caretSize: number;
+}
+
+/**
+ * The toolbar's measurements under a control sizing; see `resolveControlSizing`. Touch-sized a
+ * control lays out at the width of what it paints (`toolbarSlot`, `toolbarContentSlot`), so an
+ * icon-only control takes its glyph's width and a picker's padding takes no room.
+ */
+export function composerToolbarGeometry(sizing: ControlSizing): ComposerToolbarGeometry {
+  const glyphs = toolbarGlyphsFor(sizing);
+  const isTouch = sizing === "touch";
+  return {
+    controlSize: isTouch ? glyphs.icon.size : TOOLBAR_CONTROL_SIZES.pointer,
+    glyphs,
+    controlGap: TOOLBAR_CONTROL_GAPS[sizing],
+    iconLabelGap: 4,
+    labelPadding: isTouch ? 0 : 8,
+    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,203 @@ 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") 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);
+  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) widths.push(geometry.controlSize);
+  return sumControlWidths(widths, geometry);
 }
 
-function resolveFullFloor(controls: ComposerControlPresence): number {
+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(50 + 70 * fontScale);
-  if (controls.hasThinking) widths.push(54 + 48 * fontScale);
-  if (controls.hasMode) widths.push(54 + 96 * fontScale);
+  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));
+    widths.push(resolveFeatureControlWidth(feature, fontScale, geometry));
   }
-  return sumControlWidths(widths);
+  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) 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/model-sheet.tsx b/packages/app/src/composer/agent-controls/model-sheet.tsx
index 6929b447ea..68c7f9f834 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 { 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 {
+  TOUCH_ICON_SIZE,
+  toolbarContentSlot,
+  toolbarSlot,
+  type ToolbarGlyphs,
+} from "@/components/ui/control-geometry";
 
 const SNAP_POINTS = ["80%", "90%"];
 const MODEL_LIST_TOP_INSET = 4;
@@ -41,7 +57,9 @@ 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;
   children: ReactNode;
 }
@@ -75,6 +93,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,7 +148,8 @@ export function CompactModelSheet({
   isRetryingProvider = false,
   disabled = false,
   serverId = null,
-  glyphSize,
+  glyphs,
+  showLabels,
   canSwitchProvider,
   children,
 }: CompactModelSheetProps) {
@@ -229,15 +285,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 +310,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}
@@ -372,23 +404,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(theme.spacing[2]),
+    borderRadius: theme.borderRadius.full,
     backgroundColor: "transparent",
   },
+  triggerIconOnly: {
+    ...toolbarSlot(TOUCH_ICON_SIZE.md),
+    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 +562,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 +593,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/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/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.live.test.tsx b/packages/app/src/composer/draft/input-draft.live.test.tsx
index 8bc31bb176..82de9d3d73 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(() => {
diff --git a/packages/app/src/composer/draft/input-draft.ts b/packages/app/src/composer/draft/input-draft.ts
index c14db9a119..2eb606a7f7 100644
--- a/packages/app/src/composer/draft/input-draft.ts
+++ b/packages/app/src/composer/draft/input-draft.ts
@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 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,
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 d00b6f7790..2b99ac8c09 100644
--- a/packages/app/src/composer/draft/workspace-tab.tsx
+++ b/packages/app/src/composer/draft/workspace-tab.tsx
@@ -1,21 +1,17 @@
 import { useCallback, useEffect, useMemo, useRef } from "react";
-import { Keyboard, ScrollView, StyleSheet as RNStyleSheet, Text, View } from "react-native";
+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 +21,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";
@@ -41,7 +37,7 @@ import {
   useWorkspaceAttachmentsStore,
 } from "@/attachments/workspace-attachments-store";
 import type { UserMessageImageAttachment } from "@/types/stream";
-import { COMPACT_FORM_FACTOR_WIDTH, useIsCompactFormFactor } from "@/constants/layout";
+import { COMPACT_CONTENT_WIDTH, useIsCompactFormFactor } from "@/constants/layout";
 import { isWeb } from "@/constants/platform";
 import {
   buildWorkspaceTabPersistenceKey,
@@ -50,16 +46,6 @@ 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;
@@ -260,25 +246,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 +268,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);
@@ -387,10 +367,9 @@ 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_FORM_FACTOR_WIDTH,
+    COMPACT_CONTENT_WIDTH,
     { initialIsBelow: isCompactFormFactor },
   );
   const workspaceAttachmentScopeKey = useWorkspaceAttachmentScopeKey({
@@ -421,82 +400,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,
@@ -600,75 +568,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 +623,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 +646,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/index.tsx b/packages/app/src/composer/index.tsx
index d000c269af..60b05be23e 100644
--- a/packages/app/src/composer/index.tsx
+++ b/packages/app/src/composer/index.tsx
@@ -31,8 +31,20 @@ import {
 import { useTranslation } from "react-i18next";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
+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 { COMPOSER_TOOLBAR_SHAPES } from "@/composer/input/toolbar-rails";
 import { usePanelStore } from "@/stores/panel-store";
-import { useHasFinePointer } from "@/hooks/use-fine-pointer";
+import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
 import { useShallow } from "zustand/shallow";
 import {
   ArrowUp,
@@ -71,7 +83,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 {
@@ -193,10 +205,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 +266,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 +1058,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 +1087,8 @@ function ComposerForgeBinding({
 }
 
 interface ComposerCancelButtonProps {
-  buttonIconSize: number;
-  cancelButtonStyle: (object | undefined)[];
+  discGlyphSize: number;
+  cancelButtonStyle: (state: PressableStateCallbackType) => object[];
   handleCancelAgent: () => void;
   isConnected: boolean;
   isCancellingAgent: boolean;
@@ -1090,7 +1097,7 @@ interface ComposerCancelButtonProps {
 }
 
 function ComposerCancelButton({
-  buttonIconSize,
+  discGlyphSize,
   cancelButtonStyle,
   handleCancelAgent,
   isConnected,
@@ -1104,7 +1111,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 +1123,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 +1136,7 @@ function ComposerCancelButton({
 }
 
 interface ComposerVoiceModeButtonProps {
-  buttonIconSize: number;
+  glyph: ToolbarGlyph;
   handleToggleRealtimeVoice: () => void;
   isConnected: boolean;
   isVoiceSwitching: boolean;
@@ -1140,37 +1147,25 @@ interface ComposerVoiceModeButtonProps {
   t: TFunction;
 }
 
-interface ComposerRightControlsSlotProps extends ComposerVoiceModeButtonProps {
+function showsVoiceModeButton(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;
+}): boolean {
+  // Voice mode holds the trailing disc until there is something to send, then Send takes it.
   return (
-    <View style={styles.rightControls}>
-      <ComposerVoiceModeButton {...voiceProps} />
-    </View>
+    input.showVoice &&
+    !input.isVoiceModeForAgent &&
+    input.hasAgent &&
+    !input.isAgentRunning &&
+    !input.hasSendableContent
   );
 }
 
 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}>
@@ -1281,7 +1288,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,8 +1316,11 @@ 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(
@@ -2010,8 +2019,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 +2029,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 +2047,7 @@ function ComposerContentImpl({
     ),
     [
       agentInterruptKeys,
-      buttonIconSize,
+      discGlyphSize,
       cancelButtonStyle,
       handleCancelAgent,
       isCancellingAgent,
@@ -2046,32 +2056,34 @@ 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(
+    () =>
+      showsVoiceModeButton({
+        isVoiceModeForAgent,
+        hasAgent,
+        isAgentRunning,
+        hasSendableContent,
+        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 +2093,6 @@ function ComposerContentImpl({
     ],
   );
 
-  const contextWindowMeterGlyphSize = isCompactLayout ? ICON_SIZE.md : buttonIconSize;
   const beforeVoiceContent = useMemo(
     () =>
       hasAgent ? (
@@ -2092,7 +2103,7 @@ function ComposerContentImpl({
             maxTokens={agentState.contextWindowMaxTokens}
             usedTokens={agentState.contextWindowUsedTokens}
             totalCostUsd={agentState.totalCostUsd}
-            glyphSize={contextWindowMeterGlyphSize}
+            toolbarRing={TOOLBAR_RINGS[controlSizing]}
           />
         </View>
       ) : null,
@@ -2103,7 +2114,7 @@ function ComposerContentImpl({
       agentState.contextWindowMaxTokens,
       agentState.contextWindowUsedTokens,
       agentState.totalCostUsd,
-      contextWindowMeterGlyphSize,
+      controlSizing,
     ],
   );
 
@@ -2489,12 +2500,13 @@ function ComposerContentImpl({
                   disabled={isSubmitLoading}
                   leftContent={leftContent}
                   beforeVoiceContent={beforeVoiceContent}
-                  rightContent={rightContent}
+                  voiceModeContent={voiceModeContent}
                   activeActionContent={activeActionContent}
                   voiceServerId={serverId}
                   voiceAgentId={agentId}
                   isAgentRunning={isAgentRunning}
                   defaultSendBehavior={activeSendBehavior}
+                  sendShortcut={appSettings.sendShortcut}
                   onQueue={handleQueue}
                   onSubmitLoadingPress={submitLoadingPressHandler}
                   onKeyPress={handleCommandKeyPress}
@@ -2567,7 +2579,6 @@ const styles = StyleSheet.create((theme: Theme) => ({
     width: "100%",
     overflow: "visible",
     paddingHorizontal: theme.spacing[4],
-    paddingBottom: theme.spacing[4],
   },
   inputAreaLocked: {
     opacity: 0.6,
@@ -2577,7 +2588,6 @@ const styles = StyleSheet.create((theme: Theme) => ({
     minHeight: 0,
     alignItems: "stretch",
     paddingHorizontal: 0,
-    paddingBottom: 0,
   },
   fullscreenFill: {
     flex: 1,
@@ -2597,42 +2607,49 @@ const styles = StyleSheet.create((theme: Theme) => ({
     gap: theme.spacing[3],
   },
   cancelButton: {
-    width: 28,
-    height: 28,
+    ...toolbarSlot(COMPOSER_TOOLBAR_SHAPES.disc),
+    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(COMPOSER_TOOLBAR_SHAPES.ring),
     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(COMPOSER_TOOLBAR_SHAPES.disc),
+    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 73c54331d1..3c4541181f 100644
--- a/packages/app/src/composer/input/input.tsx
+++ b/packages/app/src/composer/input/input.tsx
@@ -1,3 +1,5 @@
+import { useKeyboardFocusSurface } from "@/keyboard";
+import type { SendShortcut } from "@/hooks/use-settings";
 import {
   useComposerEditingSession,
   useComposerFullscreen,
@@ -6,6 +8,7 @@ import {
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import {
   View,
+  Platform,
   Text,
   useWindowDimensions,
   NativeSyntheticEvent,
@@ -25,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 {
+  COMPOSER_PADDING_BOTTOM,
+  COMPOSER_PADDING_HORIZONTAL,
+  COMPOSER_CORNER_RADIUS,
+  COMPOSER_PADDING_TOP,
+  COMPOSER_TOOLBAR_SHAPES,
+  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";
@@ -88,6 +111,7 @@ import {
   resolveAlternateSendAction,
   resolveComposerSurfacePresentation,
   resolveComposerSurfaceText,
+  resolveMessageInputEnterAction,
   resolveRetainedSelection,
   runAlternateSendAction,
   runDefaultSendAction,
@@ -96,6 +120,11 @@ import {
 } from "./state";
 
 const DEFAULT_SEND_KEYS: ShortcutKey[][] = [["Enter"]];
+const MOD_ENTER_SEND_KEYS: ShortcutKey[][] = [["mod", "Enter"]];
+
+function resolveSendKeys(sendShortcut: SendShortcut): ShortcutKey[][] {
+  return sendShortcut === "mod-enter" ? MOD_ENTER_SEND_KEYS : DEFAULT_SEND_KEYS;
+}
 const COMPOSER_INPUT_DATASET = { composerInput: "" } as const;
 
 export interface AttachmentMenuItem {
@@ -155,8 +184,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 after the dictation button, or null when the row hides it. */
+  voiceModeContent?: React.ReactNode;
   /** Primary action to render when the agent is active and the composer has no sendable content. */
   activeActionContent?: React.ReactNode;
   voiceServerId?: string;
@@ -167,6 +196,7 @@ export interface MessageInputProps {
    *  running. "interrupt" and "steer" send immediately, "queue" queues. Required so the default
    *  lives only in DEFAULT_CLIENT_SETTINGS. */
   defaultSendBehavior: "interrupt" | "steer" | "queue";
+  sendShortcut: SendShortcut;
   /** Callback for queue button when agent is running */
   onQueue?: (payload: MessagePayload) => void;
   /** Optional handler used when submit button is in loading state. */
@@ -236,19 +266,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>
   );
 }
@@ -326,21 +365,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"]>;
@@ -379,12 +422,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} />;
@@ -393,15 +436,30 @@ 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 {
   onKeyPressCallback: ((event: ComposerKeyPressEvent) => boolean) | undefined;
   input: ComposerKeyPressEvent["input"];
   submitOnEnter: boolean;
+  sendShortcut: SendShortcut;
+  isAgentRunning: boolean;
+  onQueue: ((payload: MessagePayload) => void) | undefined;
   isSubmitDisabled: boolean;
   isSubmitLoading: boolean;
   disabled: boolean;
@@ -428,12 +486,21 @@ function handleDesktopKeyPressImpl(
   }
 
   if (event.nativeEvent.key !== "Enter") return;
-  if (!ctx.submitOnEnter) return;
-  if (shiftKey) return;
+
+  const action = resolveMessageInputEnterAction({
+    submitOnEnter: ctx.submitOnEnter,
+    sendShortcut: ctx.sendShortcut,
+    shiftKey: shiftKey ?? false,
+    metaKey: metaKey ?? false,
+    ctrlKey: ctrlKey ?? false,
+    isAgentRunning: ctx.isAgentRunning,
+    onQueue: ctx.onQueue,
+  });
+  if (action === null) return;
 
   if (ctx.isSubmitDisabled || ctx.isSubmitLoading || ctx.disabled) return;
   event.preventDefault();
-  if (metaKey || ctrlKey) {
+  if (action === "alternate-send") {
     ctx.handleAlternateSendAction();
     return;
   }
@@ -776,7 +843,7 @@ function SendButtonTooltip({
   submitIcon,
   submitLabel,
   submitButtonTestID,
-  buttonIconSize,
+  glyph,
   sendKeys,
   sendTooltipLabel,
 }: {
@@ -793,7 +860,7 @@ function SendButtonTooltip({
   submitIcon: "arrow" | "return";
   submitLabel: string | undefined;
   submitButtonTestID: string | undefined;
-  buttonIconSize: number;
+  glyph: ToolbarGlyph;
   sendKeys: ShortcutChord | null | undefined;
   sendTooltipLabel: string;
 }) {
@@ -810,12 +877,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} />
@@ -1106,12 +1175,13 @@ 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;
   isAgentRunning: boolean;
   defaultSendBehavior: "interrupt" | "steer" | "queue";
+  sendShortcut: SendShortcut;
   onQueue: ((payload: MessagePayload) => void) | undefined;
   onSubmitLoadingPress: (() => void) | undefined;
   onKeyPressCallback: ((event: ComposerKeyPressEvent) => boolean) | undefined;
@@ -1153,12 +1223,13 @@ 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,
     isAgentRunning: props.isAgentRunning ?? false,
     defaultSendBehavior: props.defaultSendBehavior,
+    sendShortcut: props.sendShortcut,
     onQueue: props.onQueue,
     onSubmitLoadingPress: props.onSubmitLoadingPress,
     onKeyPressCallback: props.onKeyPress,
@@ -1180,8 +1251,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[];
@@ -1189,7 +1264,7 @@ function resolvePresentationSendDisabled(input: {
   allowEmpty: boolean;
 }): boolean {
   return (
-    input.disabled || (input.fullscreen && !input.allowEmpty && !hasSendableComposerContent(input))
+    input.disabled || (input.standsIn && !input.allowEmpty && !hasSendableComposerContent(input))
   );
 }
 
@@ -1230,12 +1305,13 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
       disabled,
       leftContent,
       beforeVoiceContent,
-      rightContent,
+      voiceModeContent,
       activeActionContent,
       voiceServerId,
       voiceAgentId,
       isAgentRunning,
       defaultSendBehavior,
+      sendShortcut,
       onQueue,
       onSubmitLoadingPress,
       onKeyPressCallback,
@@ -1258,13 +1334,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;
@@ -1384,6 +1463,16 @@ 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();
@@ -1755,6 +1844,9 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
             selectionRef.current,
           ),
           submitOnEnter: shouldSubmitOnEnter,
+          sendShortcut,
+          isAgentRunning,
+          onQueue,
           isSubmitDisabled,
           isSubmitLoading,
           disabled,
@@ -1766,6 +1858,9 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         shouldHandleWebKeyPress,
         onKeyPressCallback,
         shouldSubmitOnEnter,
+        sendShortcut,
+        isAgentRunning,
+        onQueue,
         isSubmitDisabled,
         isSubmitLoading,
         disabled,
@@ -1864,20 +1959,21 @@ 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,
-        !isDictationStartEnabled && styles.buttonDisabled,
         isDictating && styles.voiceButtonRecording,
+        Boolean(hovered || pressed) && !isDictating && styles.iconButtonHovered,
+        Boolean(pressed) && isDictating && styles.discPressed,
+        !isDictationStartEnabled && styles.buttonDisabled,
       ],
       [isDictating, isDictationStartEnabled],
     );
@@ -1889,7 +1985,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 },
@@ -1917,21 +2013,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" && voiceModeContent == null);
+    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 }],
@@ -1943,10 +2043,10 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         <AttachButtonIcon
           hovered={Boolean(hovered)}
           onAttachButtonRef={onAttachButtonRef}
-          buttonIconSize={buttonIconSize}
+          glyph={toolbarGlyph}
         />
       ),
-      [onAttachButtonRef, buttonIconSize],
+      [onAttachButtonRef, toolbarGlyph],
     );
 
     const renderVoiceButtonIcon = useCallback(
@@ -1955,16 +2055,17 @@ 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}
           shouldShow
           canPressLoadingButton={canPressLoadingButton}
@@ -1979,14 +2080,13 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
           submitIcon={submitIcon}
           submitLabel={submitLabel}
           submitButtonTestID={submitButtonTestID}
-          buttonIconSize={buttonIconSize}
-          sendKeys={DEFAULT_SEND_KEYS}
+          glyph={toolbarGlyph}
+          sendKeys={resolveSendKeys(sendShortcut)}
           sendTooltipLabel={sendTooltipLabel}
         />
       ),
       [
-        isFullscreen,
-        primaryActionKind,
+        presentedActionKind,
         activeActionContent,
         canPressLoadingButton,
         onSubmitLoadingPress,
@@ -2000,7 +2100,8 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         submitIcon,
         submitLabel,
         submitButtonTestID,
-        buttonIconSize,
+        toolbarGlyph,
+        sendShortcut,
         sendTooltipLabel,
       ],
     );
@@ -2073,9 +2174,25 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         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
@@ -2105,12 +2222,13 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
               voiceMuteToggleKeys={voiceMuteToggleKeys}
               dictationToggleKeys={dictationToggleKeys}
             />
-            {rightContent}
+            {voiceModeContent}
             {sendButton}
           </View>
         </View>
       ),
       [
+        buttonRowStyle,
         mode.showAttachments,
         isConnected,
         disabled,
@@ -2130,7 +2248,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         isRealtimeVoiceForCurrentAgent,
         voiceMuteToggleKeys,
         dictationToggleKeys,
-        rightContent,
+        voiceModeContent,
         sendButton,
       ],
     );
@@ -2182,7 +2300,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}
       >
@@ -2193,7 +2315,8 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         />
         <ComposerInputPresentation
           fullscreen={isFullscreen}
-          sendIconSize={buttonIconSize}
+          controlSizing={controlSizing}
+          sendIconSize={toolbarGlyph.size}
           surface={textSurface}
           toolbar={toolbar}
           send={sendButton}
@@ -2227,26 +2350,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",
@@ -2320,64 +2434,80 @@ 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,
   },
   attachButton: {
-    width: 28,
-    height: 28,
+    ...toolbarSlot(COMPOSER_TOOLBAR_SHAPES.attach),
     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(COMPOSER_TOOLBAR_SHAPES.dictation),
     borderRadius: theme.borderRadius.full,
     alignItems: "center",
     justifyContent: "center",
   },
   voiceButtonRecording: {
+    marginHorizontal: toolbarSlot(COMPOSER_TOOLBAR_SHAPES.disc).marginHorizontal,
+  },
+  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,
+    marginHorizontal: toolbarSlot(COMPOSER_TOOLBAR_SHAPES.disc).marginHorizontal,
+    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,
@@ -2387,6 +2517,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/state.test.ts b/packages/app/src/composer/input/state.test.ts
index 82f30da364..ad492976b3 100644
--- a/packages/app/src/composer/input/state.test.ts
+++ b/packages/app/src/composer/input/state.test.ts
@@ -2,10 +2,12 @@ import { describe, expect, it, vi } from "vitest";
 import {
   applyDictationTranscript,
   computeCanStartDictation,
+  type MessageInputEnterContext,
   resolveActiveSendBehavior,
   resolveComposerSurfacePresentation,
   resolveComposerSurfaceText,
   resolveGlyphRailOffset,
+  resolveMessageInputEnterAction,
   resolveRetainedSelection,
   resolveAlternateSendAction,
   runAlternateSendAction,
@@ -320,6 +322,212 @@ describe("composer send behavior", () => {
   });
 });
 
+describe("resolveMessageInputEnterAction", () => {
+  function enterContext(
+    overrides: Partial<MessageInputEnterContext> = {},
+  ): MessageInputEnterContext {
+    return {
+      submitOnEnter: true,
+      sendShortcut: "enter",
+      shiftKey: false,
+      metaKey: false,
+      ctrlKey: false,
+      isAgentRunning: false,
+      onQueue: () => undefined,
+      ...overrides,
+    };
+  }
+
+  it("returns null for plain, Shift, and modifier Enter when submit on enter is disabled", () => {
+    expect(resolveMessageInputEnterAction(enterContext({ submitOnEnter: false }))).toBeNull();
+    expect(
+      resolveMessageInputEnterAction(enterContext({ submitOnEnter: false, shiftKey: true })),
+    ).toBeNull();
+    expect(
+      resolveMessageInputEnterAction(enterContext({ submitOnEnter: false, metaKey: true })),
+    ).toBeNull();
+    expect(
+      resolveMessageInputEnterAction(enterContext({ submitOnEnter: false, ctrlKey: true })),
+    ).toBeNull();
+  });
+
+  it("still returns null when modifier Enter sends and submit on enter is disabled", () => {
+    expect(
+      resolveMessageInputEnterAction(
+        enterContext({ sendShortcut: "mod-enter", submitOnEnter: false, metaKey: true }),
+      ),
+    ).toBeNull();
+    expect(
+      resolveMessageInputEnterAction(
+        enterContext({ sendShortcut: "mod-enter", submitOnEnter: false }),
+      ),
+    ).toBeNull();
+  });
+
+  it("sends on plain Enter when Enter sends", () => {
+    expect(resolveMessageInputEnterAction(enterContext())).toBe("default-send");
+  });
+
+  it("returns null for Shift+Enter when Enter sends", () => {
+    expect(resolveMessageInputEnterAction(enterContext({ shiftKey: true }))).toBeNull();
+  });
+
+  it("returns null for Shift+Cmd+Enter and Shift+Ctrl+Enter so Shift keeps its newline", () => {
+    expect(
+      resolveMessageInputEnterAction(
+        enterContext({ shiftKey: true, metaKey: true, isAgentRunning: true }),
+      ),
+    ).toBeNull();
+    expect(
+      resolveMessageInputEnterAction(
+        enterContext({ shiftKey: true, ctrlKey: true, isAgentRunning: true }),
+      ),
+    ).toBeNull();
+  });
+
+  it("sends on Cmd+Enter and Ctrl+Enter while idle even with a queue handler", () => {
+    expect(resolveMessageInputEnterAction(enterContext({ metaKey: true }))).toBe("default-send");
+    expect(resolveMessageInputEnterAction(enterContext({ ctrlKey: true }))).toBe("default-send");
+  });
+
+  it("queues on Cmd+Enter and Ctrl+Enter while the agent is running with a queue handler", () => {
+    expect(
+      resolveMessageInputEnterAction(enterContext({ metaKey: true, isAgentRunning: true })),
+    ).toBe("alternate-send");
+    expect(
+      resolveMessageInputEnterAction(enterContext({ ctrlKey: true, isAgentRunning: true })),
+    ).toBe("alternate-send");
+  });
+
+  it("sends on Cmd+Enter and Ctrl+Enter while running when no queue handler exists", () => {
+    expect(
+      resolveMessageInputEnterAction(
+        enterContext({ metaKey: true, isAgentRunning: true, onQueue: undefined }),
+      ),
+    ).toBe("default-send");
+    expect(
+      resolveMessageInputEnterAction(
+        enterContext({ ctrlKey: true, isAgentRunning: true, onQueue: undefined }),
+      ),
+    ).toBe("default-send");
+  });
+
+  it("returns null for plain and Shift+Enter when modifier Enter sends", () => {
+    expect(resolveMessageInputEnterAction(enterContext({ sendShortcut: "mod-enter" }))).toBeNull();
+    expect(
+      resolveMessageInputEnterAction(enterContext({ sendShortcut: "mod-enter", shiftKey: true })),
+    ).toBeNull();
+  });
+
+  it("returns null for Shift+Cmd+Enter and Shift+Ctrl+Enter when modifier Enter sends", () => {
+    expect(
+      resolveMessageInputEnterAction(
+        enterContext({ sendShortcut: "mod-enter", shiftKey: true, metaKey: true }),
+      ),
+    ).toBeNull();
+    expect(
+      resolveMessageInputEnterAction(
+        enterContext({ sendShortcut: "mod-enter", shiftKey: true, ctrlKey: true }),
+      ),
+    ).toBeNull();
+  });
+
+  it("sends on Cmd+Enter and Ctrl+Enter while idle when modifier Enter sends", () => {
+    expect(
+      resolveMessageInputEnterAction(enterContext({ sendShortcut: "mod-enter", metaKey: true })),
+    ).toBe("default-send");
+    expect(
+      resolveMessageInputEnterAction(enterContext({ sendShortcut: "mod-enter", ctrlKey: true })),
+    ).toBe("default-send");
+  });
+
+  it("uses the default action on modifier Enter while running when modifier Enter sends", () => {
+    expect(
+      resolveMessageInputEnterAction(
+        enterContext({ sendShortcut: "mod-enter", metaKey: true, isAgentRunning: true }),
+      ),
+    ).toBe("default-send");
+    expect(
+      resolveMessageInputEnterAction(
+        enterContext({ sendShortcut: "mod-enter", ctrlKey: true, isAgentRunning: true }),
+      ),
+    ).toBe("default-send");
+  });
+
+  describe("composed with the send actions", () => {
+    function actions() {
+      const calls: string[] = [];
+      return {
+        calls,
+        handleSendMessage: () => calls.push("send"),
+        handleQueueMessage: () => calls.push("queue"),
+        onQueue: () => undefined,
+      };
+    }
+
+    function resolveCommandEnterToSendModifierEnter() {
+      return resolveMessageInputEnterAction(
+        enterContext({ sendShortcut: "mod-enter", metaKey: true, isAgentRunning: true }),
+      );
+    }
+
+    it("queues through the default send action when queue behavior is selected and the agent is running", () => {
+      const sendAction = actions();
+
+      expect(resolveCommandEnterToSendModifierEnter()).toBe("default-send");
+
+      runDefaultSendAction({
+        defaultSendBehavior: "queue",
+        isAgentRunning: true,
+        onQueue: sendAction.onQueue,
+        handleSendMessage: sendAction.handleSendMessage,
+        handleQueueMessage: sendAction.handleQueueMessage,
+      });
+
+      expect(sendAction.calls).toEqual(["queue"]);
+    });
+
+    it("sends through the default send action when queue behavior is selected and the agent is idle", () => {
+      const sendAction = actions();
+
+      expect(
+        resolveMessageInputEnterAction(
+          enterContext({ sendShortcut: "mod-enter", metaKey: true, isAgentRunning: false }),
+        ),
+      ).toBe("default-send");
+
+      runDefaultSendAction({
+        defaultSendBehavior: "queue",
+        isAgentRunning: false,
+        onQueue: sendAction.onQueue,
+        handleSendMessage: sendAction.handleSendMessage,
+        handleQueueMessage: sendAction.handleQueueMessage,
+      });
+
+      expect(sendAction.calls).toEqual(["send"]);
+    });
+
+    it.each([{ defaultSendBehavior: "steer" }, { defaultSendBehavior: "interrupt" }] as const)(
+      "sends through the default send action when $defaultSendBehavior behavior is selected and the agent is running",
+      ({ defaultSendBehavior }) => {
+        const sendAction = actions();
+
+        expect(resolveCommandEnterToSendModifierEnter()).toBe("default-send");
+
+        runDefaultSendAction({
+          defaultSendBehavior,
+          isAgentRunning: true,
+          onQueue: sendAction.onQueue,
+          handleSendMessage: sendAction.handleSendMessage,
+          handleQueueMessage: sendAction.handleQueueMessage,
+        });
+
+        expect(sendAction.calls).toEqual(["send"]);
+      },
+    );
+  });
+});
+
 describe("stopRealtimeVoice", () => {
   it("keeps voice mode active when the running agent refuses cancellation", async () => {
     const cancellationError = new Error("active run cancellation was not acknowledged");
diff --git a/packages/app/src/composer/input/state.ts b/packages/app/src/composer/input/state.ts
index 9cf6279482..67c8030745 100644
--- a/packages/app/src/composer/input/state.ts
+++ b/packages/app/src/composer/input/state.ts
@@ -1,3 +1,4 @@
+import type { SendShortcut } from "@/hooks/use-settings";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import type { ActiveTurnBehavior } from "@getpaseo/protocol/messages";
 import type { MessagePayload, TextReplacement } from "@/composer/types";
@@ -151,6 +152,29 @@ export function runAlternateSendAction(ctx: SendActionContext): void {
   runDefaultSendAction(ctx);
 }
 
+export type MessageInputEnterAction = "alternate-send" | "default-send";
+
+export interface MessageInputEnterContext {
+  submitOnEnter: boolean;
+  sendShortcut: SendShortcut;
+  shiftKey: boolean;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  isAgentRunning: boolean;
+  onQueue: ((payload: MessagePayload) => void) | undefined;
+}
+
+export function resolveMessageInputEnterAction(
+  ctx: MessageInputEnterContext,
+): MessageInputEnterAction | null {
+  if (!ctx.submitOnEnter) return null;
+  if (ctx.shiftKey) return null;
+  const hasModifier = ctx.metaKey || ctx.ctrlKey;
+  if (ctx.sendShortcut === "mod-enter") return hasModifier ? "default-send" : null;
+  if (hasModifier && ctx.isAgentRunning && ctx.onQueue) return "alternate-send";
+  return "default-send";
+}
+
 export function runMessageInputKeyboardAction(
   action: MessageInputKeyboardActionKind,
   actions: MessageInputKeyboardActions,
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..1b4caadd2d
--- /dev/null
+++ b/packages/app/src/composer/input/toolbar-rails.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { composerToolbarOverhang, resolveComposerLeadingEdge } from "./toolbar-rails";
+
+describe("composer toolbar rails", () => {
+  it("keeps touch glyphs and labels on the text rails and nests a trailing disc into the corner", () => {
+    for (const edge of ["attach", "dictation", "voiceMode", "label", "none"] as const) {
+      expect(composerToolbarOverhang(edge, "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", "dictation", "voiceMode", "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..1cbca21224
--- /dev/null
+++ b/packages/app/src/composer/input/toolbar-rails.ts
@@ -0,0 +1,85 @@
+import {
+  TOOLBAR_CONTROL_SIZES,
+  TOOLBAR_DISC_SIZES,
+  TOOLBAR_RINGS,
+  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" | "dictation" | "voiceMode" | "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,
+});
+
+/** How much of Lucide's 24-unit grid each toolbar glyph's ink spans, centred in its box. */
+const GLYPH_INK_SPANS = { plus: 14, mic: 14, audioLines: 20 } as const;
+
+function touchGlyphInkWidth(span: number): number {
+  const glyph = toolbarGlyphsFor("touch").icon;
+  return (span * glyph.size) / 24 + glyph.strokeWidth;
+}
+
+/** The width each toolbar control paints when touch-sized; the row spaces these. */
+export const COMPOSER_TOOLBAR_SHAPES = {
+  attach: touchGlyphInkWidth(GLYPH_INK_SPANS.plus),
+  dictation: touchGlyphInkWidth(GLYPH_INK_SPANS.mic),
+  voiceMode: touchGlyphInkWidth(GLYPH_INK_SPANS.audioLines),
+  ring: TOOLBAR_RINGS.touch.size,
+  disc: TOOLBAR_DISC_SIZES.touch,
+} as const;
+
+/** 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,
+});
+
+/** How far the composer toolbar hangs past the text column at one end. */
+export function composerToolbarOverhang(edge: ComposerToolbarEdge, sizing: ControlSizing): number {
+  if (sizing === "pointer") return POINTER_OVERHANG;
+  return edge === "disc" ? DISC_CORNER_NEST : 0;
+}
+
+/** 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/tracks.tsx b/packages/app/src/composer/tracks.tsx
index 4e06266058..74a0b7f434 100644
--- a/packages/app/src/composer/tracks.tsx
+++ b/packages/app/src/composer/tracks.tsx
@@ -1,5 +1,6 @@
 import { useCallback, useMemo, useState, type ReactElement, type ReactNode } from "react";
-import { Pressable, Text, View } from "react-native";
+import { Pressable, ScrollView, Text, View } from "react-native";
+import { GestureDetector } from "react-native-gesture-handler";
 import { StyleSheet } from "react-native-unistyles";
 import {
   MENU_ITEM_HEIGHT,
@@ -8,11 +9,15 @@ import {
   MenuSurface,
   MenuTrigger,
   useMenuContext,
+  useMenuDepth,
+  type MenuPageDefinition,
   type MenuTriggerState,
 } from "@/components/ui/menu";
 import { StatusRing } from "@/components/status-ring";
+import { bySizing } from "@/components/ui/control-geometry";
 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";
@@ -27,14 +32,28 @@ 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();
   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}>
+          <ScrollView
+            testID="composer-track-scroll"
+            horizontal
+            keyboardShouldPersistTaps="handled"
+            showsHorizontalScrollIndicator={false}
+            pointerEvents="box-none"
+          >
+            <View style={styles.track} pointerEvents="box-none">
+              {children}
+            </View>
+          </ScrollView>
+        </GestureDetector>
       </View>
     </View>
   );
@@ -61,6 +80,8 @@ export interface ComposerTrackPillProps {
   accessibilityLabel?: string;
   /** Panel body. Rendered into a popover on wide screens and a sheet on compact ones. */
   children: ReactNode;
+  /** Pages a row can open in place of the list (`ComposerTrackRow` `opensPage`). */
+  pages?: readonly MenuPageDefinition[];
 }
 
 /**
@@ -85,6 +106,7 @@ export function ComposerTrackPill({
   testID,
   accessibilityLabel,
   children,
+  pages,
 }: ComposerTrackPillProps): ReactElement {
   return (
     <MenuRoot compactMode="sheet">
@@ -98,6 +120,7 @@ export function ComposerTrackPill({
         align="start"
         offset={PANEL_OFFSET}
         sheetTitle={panelTitle}
+        pages={pages}
         minWidth={PANEL_MIN_WIDTH}
         maxWidth={PANEL_MAX_WIDTH}
         maxHeight={PANEL_MAX_HEIGHT}
@@ -199,6 +222,11 @@ export interface ComposerTrackRowProps {
    * lands inside the panel is not.
    */
   closeOnSelect?: boolean;
+  /**
+   * A page of the panel this row opens in place of the list, instead of running `onPress`. The
+   * panel stays open: Back returns to the list.
+   */
+  opensPage?: string;
   disabled?: boolean;
   accessibilityLabel?: string;
   testID?: string;
@@ -220,18 +248,23 @@ export function ComposerTrackRow({
   children,
   onPress,
   closeOnSelect = true,
+  opensPage,
   disabled = false,
   accessibilityLabel,
   testID,
 }: ComposerTrackRowProps): ReactElement {
-  const { selectItem } = useMenuContext("ComposerTrackRow");
+  const { selectItem, openSub } = useMenuContext("ComposerTrackRow");
+  const depth = useMenuDepth();
   const [hovered, setHovered] = useState(false);
   const handlePointerEnter = useCallback(() => setHovered(true), []);
   const handlePointerLeave = useCallback(() => setHovered(false), []);
-  const handleSelect = useCallback(
-    () => selectItem(onPress, closeOnSelect),
-    [closeOnSelect, onPress, selectItem],
-  );
+  const handleSelect = useCallback(() => {
+    if (opensPage) {
+      selectItem(() => openSub({ id: opensPage, depth }), false);
+      return;
+    }
+    selectItem(onPress, closeOnSelect);
+  }, [closeOnSelect, depth, onPress, openSub, opensPage, selectItem]);
 
   const itemDataSet = useMemo(
     () => ({ menuItem: "true", menuDisabled: disabled ? "true" : "false" }),
@@ -251,7 +284,7 @@ export function ComposerTrackRow({
     [hovered, renderRow],
   );
 
-  if (!onPress) {
+  if (!onPress && !opensPage) {
     return <View accessibilityLabel={accessibilityLabel}>{renderRow(false)}</View>;
   }
 
@@ -326,16 +359,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;
 
@@ -352,9 +386,14 @@ const styles = StyleSheet.create((theme) => {
         md: COMPOSER_PILL_CLEARANCE.wide,
       },
     },
-    track: {
+    trackViewport: {
       width: "100%",
       maxWidth: theme.contentMaxWidth,
+      minWidth: 0,
+      flexGrow: 0,
+      flexShrink: 1,
+    },
+    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 96aee0e828..ee30a611ff 100644
--- a/packages/app/src/constants/layout.ts
+++ b/packages/app/src/constants/layout.ts
@@ -1,20 +1,26 @@
 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;
 
-export const COMPACT_FORM_FACTOR_WIDTH = 500;
+// Measured composer width; independent of the window's compact/wide breakpoint.
+export const COMPACT_CONTENT_WIDTH = 500;
 
-// Settings uses the canonical desktop list + detail layout. Its sidebar and
-// detail target must fit together before it can share width with app navigation.
+// Settings navigation can shrink below its preferred width to preserve the detail
+// minimum. Both targets must fit before Settings shares width with app navigation.
 export const SETTINGS_DESKTOP_SIDEBAR_WIDTH = 320;
 export const SETTINGS_DESKTOP_DETAIL_MIN_WIDTH = 400;
 export const SETTINGS_DESKTOP_SPLIT_MIN_WIDTH =
@@ -33,7 +39,7 @@ export {
   getIsElectronMac as getIsElectronRuntimeMac,
 } from "./platform";
 
-/** Below 600 points, sidebars overlay the workspace. Medium and wider layouts dock them. */
+/** Below md (600 points), sidebars overlay the workspace; wider layouts can dock them. */
 export function isCompactBreakpoint(breakpoint: string | undefined): boolean {
   return breakpoint === "xs" || breakpoint === "sm";
 }
diff --git a/packages/app/src/contexts/session-context.tsx b/packages/app/src/contexts/session-context.tsx
index bccd4d3ee0..0b46f5f2de 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
@@ -455,10 +441,6 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
       reportError: (error) => {
         console.warn("[Session] viewed timeline synchronization failed", { serverId, error });
       },
-      schedule: (task, delayMs) => {
-        const timeout = setTimeout(task, delayMs);
-        return () => clearTimeout(timeout);
-      },
     });
     viewedTimelineSyncRef.current = sync;
     setViewedTimelineSync(serverId, sync);
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/data/acp-provider-catalog.ts b/packages/app/src/data/acp-provider-catalog.ts
index f0210f1402..46b7d81a2d 100644
--- a/packages/app/src/data/acp-provider-catalog.ts
+++ b/packages/app/src/data/acp-provider-catalog.ts
@@ -292,7 +292,10 @@ const CATALOG_DATA = [
     version: "0.6.13",
     iconId: "minimax-code",
     installLink: "https://agent.minimax.io",
-    command: ["npx", "-y", "@minimax-ai/code@0.6.13", "acp"],
+    // `-p <pkg>` names the package and `mcode` names its binary. Without the
+    // explicit binary, npx resolves the executable from the unscoped package
+    // name (`code`), which this package does not publish.
+    command: ["npx", "-y", "-p", "@minimax-ai/code@0.6.13", "mcode", "acp"],
   },
   {
     id: "minion-code",
diff --git a/packages/app/src/data/providers-snapshot.ts b/packages/app/src/data/providers-snapshot.ts
index 68b389fe15..87c62f81ca 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";
 
diff --git a/packages/app/src/data/push-router.ts b/packages/app/src/data/push-router.ts
index 75ac313169..cc32f8f8e3 100644
--- a/packages/app/src/data/push-router.ts
+++ b/packages/app/src/data/push-router.ts
@@ -1,11 +1,12 @@
 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";
@@ -186,10 +187,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 +206,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 {
diff --git a/packages/app/src/data/query.ts b/packages/app/src/data/query.ts
index 2a645f8666..e2b25d7b29 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>;
@@ -113,7 +113,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/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/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-document/benchmark-corpus.ts b/packages/app/src/git/diff-document/benchmark-corpus.ts
new file mode 100644
index 0000000000..469d437e8d
--- /dev/null
+++ b/packages/app/src/git/diff-document/benchmark-corpus.ts
@@ -0,0 +1,65 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * The diff shapes the layout benchmarks measure, shared by the node bench
+ * (`model.bench.ts`) and the browser benchmark (`e2e/browser/diff-performance.spec.ts`)
+ * so both report against the same text.
+ */
+export interface BenchmarkCorpusFile {
+  path: string;
+  lines: string[];
+}
+
+function repeatToLength(unit: string, length: number): string {
+  return unit.repeat(Math.ceil(length / unit.length)).slice(0, length);
+}
+
+/** A real source file: short lines, a few with ligature punctuation. */
+export function realCodeCorpusFile(): BenchmarkCorpusFile {
+  const source = readFileSync(path.resolve(__dirname, "../diff-pane.tsx"), "utf8");
+  return { path: "packages/app/src/git/diff-pane.tsx", lines: source.split("\n") };
+}
+
+/** The CHANGELOG shape that once froze the renderer: 42 lines, longest ~600 characters. */
+export function changelogCorpusFile(): BenchmarkCorpusFile {
+  const sentence =
+    "- Fixed an issue where the diff viewer re-measured every line -> on toggle, which made wrapping painfully slow. ";
+  return {
+    path: "CHANGELOG.md",
+    lines: Array.from({ length: 42 }, (_, index) =>
+      repeatToLength(sentence, 200 + ((index * 97) % 398)),
+    ),
+  };
+}
+
+/** Generated TypeScript: ligature punctuation on every line, every tenth line long. */
+export function generatedCodeCorpusFile(lineCount: number): BenchmarkCorpusFile {
+  return {
+    path: "src/generated.ts",
+    lines: Array.from({ length: lineCount }, (_, index) => {
+      const base = `const handler${index} = async (event) => items.filter((item) => item.id !== ${index} && item.kind === "selected");`;
+      return index % 10 === 9 ? repeatToLength(`${base} // `, 320) : base;
+    }),
+  };
+}
+
+/** Serialized data: no ligatures, every line wraps several times. */
+export function jsonCorpusFile(lineCount: number): BenchmarkCorpusFile {
+  return {
+    path: "fixtures/data.json",
+    lines: Array.from({ length: lineCount }, (_, index) =>
+      repeatToLength(`{"id": ${index}, "label": "row ${index}", "tags": ["alpha", "beta"]}, `, 300),
+    ),
+  };
+}
+
+/** A pull-request-sized working diff: one of each shape above. */
+export function pullRequestCorpus(): BenchmarkCorpusFile[] {
+  return [
+    realCodeCorpusFile(),
+    changelogCorpusFile(),
+    generatedCodeCorpusFile(1200),
+    jsonCorpusFile(300),
+  ];
+}
diff --git a/packages/app/src/git/diff-document/model.bench.ts b/packages/app/src/git/diff-document/model.bench.ts
new file mode 100644
index 0000000000..2fb25d502a
--- /dev/null
+++ b/packages/app/src/git/diff-document/model.bench.ts
@@ -0,0 +1,317 @@
+import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
+import { bench, describe } from "vitest";
+import {
+  changelogCorpusFile,
+  generatedCodeCorpusFile,
+  jsonCorpusFile,
+  pullRequestCorpus,
+  realCodeCorpusFile,
+  type BenchmarkCorpusFile,
+} from "./benchmark-corpus";
+import { buildDiffDocumentModel } from "./model";
+import {
+  createAdditiveAdvances,
+  createChunkedAdvanceMeasurer,
+  createChunkedWidthMeasurer,
+  createMeasuredAdvances,
+  requiresShaping,
+} from "./text-measurement";
+import type { BuildDiffDocumentModelInput, TextMeasurer } from "./types";
+
+// The pure layout work the diff surface does when a diff opens or line wrap is
+// toggled, without a browser or Skia. Counts are the backend-independent cost
+// owners (how many strings a shaper has to see), timings are the JS overhead
+// around them:
+//   npx vitest bench --project unit src/git/diff-document/model.bench.ts
+
+const DESKTOP_VIEWPORT = { width: 1400, height: 900 };
+const PHONE_VIEWPORT = { width: 390, height: 800 };
+const CELL_WIDTH = 7.8;
+
+interface MeasurementStats {
+  /** Whole strings handed to the backend. */
+  calls: number;
+  /** Characters inside those strings; canvas and Skia cost scales with this. */
+  characters: number;
+}
+
+interface Backend {
+  measurer: TextMeasurer;
+  stats: MeasurementStats;
+}
+
+function monospaceWidth(text: string): number {
+  let width = 0;
+  for (const character of text) width += character.charCodeAt(0) > 0x2e7f ? 2 : 1;
+  return width * CELL_WIDTH;
+}
+
+function countingMeasure(stats: MeasurementStats): (text: string) => number {
+  return (text) => {
+    stats.calls += 1;
+    stats.characters += text.length;
+    return monospaceWidth(text);
+  };
+}
+
+/** Previous web backend, retained to isolate the cost of width-only probes. */
+function webBackendWithoutWidthProbe(): Backend {
+  const stats: MeasurementStats = { calls: 0, characters: 0 };
+  const measure = countingMeasure(stats);
+  return { stats, measurer: { measure, measureAdvances: createMeasuredAdvances(measure) } };
+}
+
+/**
+ * `createWebTextMeasurer` in surface.web.tsx, with canvas replaced by a counter.
+ * Width-only probes shape one string per chunk, like the native measurer; the
+ * widths are the same sums, in the same order, as the last cumulative advance.
+ */
+function webBackend(): Backend {
+  const stats: MeasurementStats = { calls: 0, characters: 0 };
+  const measure = countingMeasure(stats);
+  const additive = createAdditiveAdvances(measure);
+  return {
+    stats,
+    measurer: {
+      measure,
+      measureAdvances: createMeasuredAdvances(measure),
+      measureWidth: createChunkedWidthMeasurer((graphemes) => {
+        const text = graphemes.join("");
+        return requiresShaping(text) ? measure(text) : (additive(graphemes).at(-1) ?? 0);
+      }),
+    },
+  };
+}
+
+/** `createNativeTextMeasurer` in text.native.ts, with Skia replaced by a counter. */
+function nativeBackend(): Backend {
+  const stats: MeasurementStats = { calls: 0, characters: 0 };
+  const widths = new Map<string, number>();
+  const additive = (graphemes: readonly string[]) => {
+    let advance = 0;
+    return graphemes.map((grapheme) => {
+      let width = widths.get(grapheme);
+      if (width === undefined) {
+        stats.calls += 1;
+        stats.characters += grapheme.length;
+        width = monospaceWidth(grapheme);
+        widths.set(grapheme, width);
+      }
+      return (advance += width);
+    });
+  };
+  const shape = countingMeasure(stats);
+  return {
+    stats,
+    measurer: {
+      measure(text) {
+        return requiresShaping(text) ? shape(text) : (additive([...text]).at(-1) ?? 0);
+      },
+      measureWidth: createChunkedWidthMeasurer((graphemes) => {
+        const text = graphemes.join("");
+        return requiresShaping(text) ? shape(text) : (additive(graphemes).at(-1) ?? 0);
+      }),
+      measureAdvances: createChunkedAdvanceMeasurer({
+        requiresShaping,
+        measureAdditive: additive,
+        measureShaped(graphemes) {
+          shape(graphemes.join(""));
+          let advance = 0;
+          return graphemes.map((grapheme) => (advance += monospaceWidth(grapheme)));
+        },
+      }),
+    },
+  };
+}
+
+function addedFile(file: BenchmarkCorpusFile): ParsedDiffFile {
+  return {
+    path: file.path,
+    isNew: true,
+    isDeleted: false,
+    additions: file.lines.length,
+    deletions: 0,
+    hunks: [
+      {
+        oldStart: 0,
+        oldCount: 0,
+        newStart: 1,
+        newCount: file.lines.length,
+        lines: file.lines.map((content) => ({
+          type: "add" as const,
+          content,
+          tokens: [{ text: content, style: null }],
+        })),
+      },
+    ],
+  };
+}
+
+interface Scenario {
+  name: string;
+  files: ParsedDiffFile[];
+}
+
+const SCENARIOS: Scenario[] = [
+  { name: "real code (diff-pane.tsx)", files: [addedFile(realCodeCorpusFile())] },
+  { name: "changelog (42 long prose lines)", files: [addedFile(changelogCorpusFile())] },
+  { name: "generated code (1200 lines)", files: [addedFile(generatedCodeCorpusFile(1200))] },
+  { name: "json (300 lines x 300 chars)", files: [addedFile(jsonCorpusFile(300))] },
+  { name: "pull request (all of the above)", files: pullRequestCorpus().map(addedFile) },
+];
+
+function input(
+  scenario: Scenario,
+  options: {
+    wrapLines: boolean;
+    viewport: { width: number; height: number };
+    measureText: TextMeasurer;
+  },
+): BuildDiffDocumentModelInput {
+  return {
+    files: scenario.files,
+    collapsedFilePaths: new Set(),
+    layout: "unified",
+    wrapLines: options.wrapLines,
+    viewportWidth: options.viewport.width,
+    typography: { family: "monospace", size: 13, lineHeight: 20 },
+    measureText: options.measureText,
+    palette: {
+      surface: "#000",
+      headerSurface: "#111",
+      border: "#222",
+      foreground: "#fff",
+      foregroundMuted: "#aaa",
+      addition: "green",
+      deletion: "red",
+      additionBackground: "#010",
+      deletionBackground: "#100",
+      emptyBackground: "#111",
+      selection: "blue",
+      headerActiveSurface: "#222",
+      headerBorder: "#333",
+      statusSuccess: "green",
+      statusDanger: "red",
+      statusWarning: "orange",
+      syntax: {},
+    },
+    labels: { binary: "Binary", tooLarge: "Too large" },
+    // What the surfaces pass at scrollTop 0: five viewports tall.
+    materializationWindow: { top: 0, height: options.viewport.height * 5 },
+  };
+}
+
+interface Variant {
+  name: string;
+  wrapLines: boolean;
+  viewport: { width: number; height: number };
+  backend: () => Backend;
+}
+
+const VARIANTS: Variant[] = [
+  {
+    name: "unwrapped desktop | web",
+    wrapLines: false,
+    viewport: DESKTOP_VIEWPORT,
+    backend: webBackend,
+  },
+  {
+    name: "wrapped desktop | web",
+    wrapLines: true,
+    viewport: DESKTOP_VIEWPORT,
+    backend: webBackend,
+  },
+  {
+    name: "wrapped desktop | web without width probe",
+    wrapLines: true,
+    viewport: DESKTOP_VIEWPORT,
+    backend: webBackendWithoutWidthProbe,
+  },
+  {
+    name: "wrapped phone | web",
+    wrapLines: true,
+    viewport: PHONE_VIEWPORT,
+    backend: webBackend,
+  },
+  {
+    name: "unwrapped desktop | native",
+    wrapLines: false,
+    viewport: DESKTOP_VIEWPORT,
+    backend: nativeBackend,
+  },
+  {
+    name: "wrapped desktop | native",
+    wrapLines: true,
+    viewport: DESKTOP_VIEWPORT,
+    backend: nativeBackend,
+  },
+  {
+    name: "wrapped phone | native",
+    wrapLines: true,
+    viewport: PHONE_VIEWPORT,
+    backend: nativeBackend,
+  },
+];
+
+function countModel(scenario: Scenario, variant: Variant) {
+  const { measurer, stats } = variant.backend();
+  const started = performance.now();
+  const model = buildDiffDocumentModel(
+    input(scenario, {
+      wrapLines: variant.wrapLines,
+      viewport: variant.viewport,
+      measureText: measurer,
+    }),
+  );
+  const elapsedMs = performance.now() - started;
+  let materializedCells = 0;
+  let fragments = 0;
+  let graphemes = 0;
+  for (const row of model.rows) {
+    if (row.kind !== "line") continue;
+    for (const cell of row.cells) {
+      if (!cell || cell.fragments.length === 0) continue;
+      materializedCells += 1;
+      fragments += cell.fragments.length;
+      for (const fragment of cell.fragments) graphemes += fragment.graphemes.length;
+    }
+  }
+  const sourceLines = scenario.files.reduce(
+    (count, file) => count + file.hunks.reduce((total, hunk) => total + hunk.lines.length, 0),
+    0,
+  );
+  return {
+    sourceLines,
+    materializedCells,
+    fragments,
+    graphemeObjects: graphemes,
+    measureCalls: stats.calls,
+    measuredCharacters: stats.characters,
+    coldMs: Number(elapsedMs.toFixed(1)),
+  };
+}
+
+const report: Record<string, ReturnType<typeof countModel>> = {};
+for (const scenario of SCENARIOS) {
+  for (const variant of VARIANTS) {
+    report[`${scenario.name} | ${variant.name}`] = countModel(scenario, variant);
+  }
+}
+console.table(report);
+
+for (const scenario of SCENARIOS) {
+  describe(scenario.name, () => {
+    for (const variant of VARIANTS) {
+      if (variant.backend === nativeBackend) continue;
+      bench(variant.name, () => {
+        buildDiffDocumentModel(
+          input(scenario, {
+            wrapLines: variant.wrapLines,
+            viewport: variant.viewport,
+            measureText: variant.backend().measurer,
+          }),
+        );
+      });
+    }
+  });
+}
diff --git a/packages/app/src/git/diff-document/model.test.ts b/packages/app/src/git/diff-document/model.test.ts
index ace965c1ce..9b55a242db 100644
--- a/packages/app/src/git/diff-document/model.test.ts
+++ b/packages/app/src/git/diff-document/model.test.ts
@@ -10,7 +10,7 @@ import {
   resolveRelayoutScrollTop,
   shouldApplyRelayoutScroll,
 } from "./model";
-import type { BuildDiffDocumentModelInput, TextMeasurer } from "./types";
+import type { BuildDiffDocumentModelInput, DiffCell, TextMeasurer } from "./types";
 
 const measurer: TextMeasurer = { measure: (text) => Array.from(text).length * 10 };
 
@@ -639,17 +639,119 @@ describe("diff document model", () => {
     expect(firstLineCells(last, "b.ts")).toBe(firstLineCells(first, "b.ts"));
   });
 
-  it("keeps wrapped geometry fully measured", () => {
+  it("replaces estimated wrapped heights through reuse and preserves the scroll anchor", () => {
+    const changed = fileWithChangedLine("x".repeat(100));
+    const files = [changed, file("later.ts")];
+    // Deliberately inaccurate M width makes the estimate differ from exact layout.
+    const measureText = {
+      measure: (text: string) => (text === "M" ? 5 : Array.from(text).length * 10),
+    };
+    const options = input({ files, measureText });
+    const first = buildDiffDocumentModel({
+      ...options,
+      materializationWindow: { top: 30, height: 1 },
+    });
+    const eager = buildDiffDocumentModel(options);
+    const exact = buildDiffDocumentModel({ ...options, reuseFrom: [first] });
+    expect(first.height).not.toBe(eager.height);
+    expect(exact.rows).toEqual(eager.rows);
+    expect(exact.height).toBe(eager.height);
+    expect(firstLineCells(exact, changed.path)).toBe(firstLineCells(first, changed.path));
+    const scrollTop = first.files[1]!.bodyTop + 3;
+    const nextScrollTop = resolveRelayoutScrollTop(first, exact, scrollTop);
+    expect(nextScrollTop).toBe(exact.files[1]!.bodyTop + 3);
+    expect(captureScrollAnchor(exact, nextScrollTop)).toEqual(
+      captureScrollAnchor(first, scrollTop),
+    );
+  });
+
+  it("preserves the wrapped source offset when resize leaves the anchor outside the window", () => {
+    const source = file();
+    source.hunks[0]!.lines = Array.from({ length: 200 }, () => ({
+      type: "add" as const,
+      content: "x".repeat(200),
+    }));
+    const options = input({ files: [source], viewportWidth: 500 });
+    const before = buildDiffDocumentModel(options);
+    const scrollTop = before.rows[100]!.top + 36;
+    const anchor = captureScrollAnchor(before, scrollTop)!;
+    expect(anchor).toMatchObject({ kind: "text", cellOffset: 90 });
+    const resizedOptions = { ...options, viewportWidth: 180 };
+    const estimated = buildDiffDocumentModel({
+      ...resizedOptions,
+      materializationWindow: {
+        top: Math.floor(scrollTop / 800) * 800 - 800,
+        height: 2000,
+      },
+    });
+    const estimatedRow = estimated.rows[100]!;
+    expect(estimatedRow.kind === "line" && estimatedRow.cells[0]?.fragments).toEqual([]);
+    const restored = resolveRelayoutScrollTop(before, estimated, scrollTop);
+    const recaptured = captureScrollAnchor(estimated, restored)!;
+    expect(recaptured).toMatchObject({ kind: "text", cellOffset: 78 });
+
+    const materialized = buildDiffDocumentModel({
+      ...resizedOptions,
+      materializationWindow: { top: restored - 800, height: 2000 },
+      reuseFrom: [estimated],
+    });
+    const eager = buildDiffDocumentModel(resizedOptions);
+    const expected = resolveRelayoutScrollTop(before, eager, scrollTop);
+    expect(expected).toBe(28_938);
+    expect(Math.abs(restored - expected)).toBeLessThan(before.lineHeight);
+    expect(resolveRelayoutScrollTop(estimated, materialized, restored)).toBe(expected);
+  });
+
+  it("materializes the relayout anchor even when off-screen height estimates are inaccurate", () => {
+    const source = file();
+    source.hunks[0]!.lines = Array.from({ length: 200 }, () => ({
+      type: "add" as const,
+      content: "x".repeat(200),
+    }));
+    const options = input({ files: [source], viewportWidth: 500 });
+    const before = buildDiffDocumentModel(options);
+    const scrollTop = before.rows[100]!.top + 38;
+    const anchor = captureScrollAnchor(before, scrollTop)!;
+    const resizedOptions = {
+      ...options,
+      viewportWidth: 180,
+      measureText: { measure: (text: string) => (text === "M" ? 5 : text.length * 10) },
+    };
+    const resized = buildDiffDocumentModel({
+      ...resizedOptions,
+      materializationWindow: { top: scrollTop - 800, height: 2000 },
+      materializationAnchor: anchor,
+    });
+    const row = resized.rows[100]!;
+    expect(row.kind === "line" && row.cells[0]!.fragments.length).toBeGreaterThan(0);
+    const restored = resolveRelayoutScrollTop(before, resized, scrollTop);
+    const materialized = buildDiffDocumentModel({
+      ...resizedOptions,
+      materializationWindow: { top: restored - 800, height: 2000 },
+      materializationAnchor: captureScrollAnchor(resized, restored),
+      reuseFrom: [resized],
+    });
+    const nextScrollTop = resolveRelayoutScrollTop(resized, materialized, restored);
+    const nextAnchor = captureScrollAnchor(materialized, nextScrollTop);
+    // Offset 90 belongs to the fragment beginning at 78 after narrowing.
+    expect(nextAnchor).toMatchObject({ kind: "text", cellOffset: 78, viewportDelta: -2 });
+    expect(nextScrollTop).toBe(resolveScrollAnchor(materialized, anchor));
+  });
+
+  it("materializes wrapped text only inside the window", () => {
     const model = buildDiffDocumentModel(
       input({
         files: [file("a.ts"), file("b.ts")],
         wrapLines: true,
-        materializationWindow: { top: 0, height: FILE_HEADER_HEIGHT },
+        materializationWindow: { top: FILE_HEADER_HEIGHT, height: 1 },
       }),
     );
 
     expect(measuredFragments(model, "a.ts")).toBeGreaterThan(0);
-    expect(measuredFragments(model, "b.ts")).toBeGreaterThan(0);
+    expect(measuredFragments(model, "b.ts")).toBe(0);
+    expect(
+      model.rows.filter((row) => row.kind === "line" && row.cells.some(hasFragments)),
+    ).toHaveLength(1);
   });
 });
 
@@ -798,3 +900,7 @@ function reviewActionsWithEditor(
     onDeleteComment() {},
   };
 }
+
+function hasFragments(cell: DiffCell | null): boolean {
+  return cell !== null && cell.fragments.length > 0;
+}
diff --git a/packages/app/src/git/diff-document/model.ts b/packages/app/src/git/diff-document/model.ts
index fb2b9a04f0..67efe06c2b 100644
--- a/packages/app/src/git/diff-document/model.ts
+++ b/packages/app/src/git/diff-document/model.ts
@@ -154,27 +154,38 @@ function appendReusableFileRows(candidate: {
 }): FileRowsResult {
   const reusedRows = candidate.model.rows.slice(candidate.file.rowStart, candidate.file.rowEnd);
   const retainsRowGeometry =
-    !candidate.input.wrapLines &&
     candidate.model.reviewGeometryKey === candidate.reviewGeometryKey &&
     candidate.file.top === candidate.fileTop &&
     candidate.file.fileIndex === candidate.fileIndex &&
     candidate.file.rowStart === candidate.rows.length;
   let top = candidate.bodyTop;
   for (const reusedRow of reusedRows) {
-    let nextRow = retainsRowGeometry ? reusedRow : repositionReusedRow(reusedRow, candidate, top);
+    let nextRow =
+      retainsRowGeometry && reusedRow.top === top
+        ? reusedRow
+        : repositionReusedRow(reusedRow, candidate, top);
     if (
       nextRow.kind === "line" &&
-      intersectsMaterializationWindow(candidate.input, top, top + nextRow.height) &&
+      (intersectsMaterializationWindow(candidate.input, top, top + nextRow.height) ||
+        containsMaterializationAnchor(candidate.input, candidate.file.path, nextRow.cells)) &&
       nextRow.cells.some((cell) => cell && cell.fragments.length === 0)
     ) {
+      const cells = materializeCells(
+        nextRow.cells,
+        candidate.file.file,
+        candidate.file.gutterWidth,
+        candidate.input,
+      );
       nextRow = {
         ...nextRow,
-        cells: materializeCells(
-          nextRow.cells,
-          candidate.file.file,
-          candidate.file.gutterWidth,
-          candidate.input,
-        ),
+        cells,
+        height:
+          Math.max(
+            candidate.input.typography.lineHeight,
+            ...cells.map(
+              (cell) => (cell?.fragments.length ?? 1) * candidate.input.typography.lineHeight,
+            ),
+          ) + nextRow.reviewHeight,
       };
     }
     candidate.rows.push(nextRow);
@@ -240,6 +251,7 @@ function appendNewFileRows(candidate: {
   const lines = geometryLines(
     lineSources(candidate.file, candidate.input.layout, false),
     candidate.input,
+    candidate.gutterWidth,
   );
   const fileBottom =
     candidate.bodyTop +
@@ -252,8 +264,8 @@ function appendNewFileRows(candidate: {
   let maximumHorizontalOverflow = 0;
   for (const line of lines) {
     const shouldMaterialize =
-      candidate.input.wrapLines ||
-      intersectsMaterializationWindow(candidate.input, top, top + line.height);
+      intersectsMaterializationWindow(candidate.input, top, top + line.height) ||
+      containsMaterializationAnchor(candidate.input, candidate.file.path, line.cells);
     const cells = shouldMaterialize
       ? materializeCells(line.cells, candidate.file, candidate.gutterWidth, candidate.input)
       : line.cells;
@@ -275,7 +287,7 @@ function appendNewFileRows(candidate: {
       candidate.input.typography.lineHeight,
       ...cells.map((cell) => (cell?.fragments.length ?? 1) * candidate.input.typography.lineHeight),
     );
-    const height = textHeight + line.reviewHeight;
+    const height = shouldMaterialize ? textHeight + line.reviewHeight : line.height;
     candidate.rows.push({
       kind: "line",
       index: candidate.rows.length,
@@ -412,13 +424,14 @@ function cellSource(line: SplitDiffDisplayLine | null, includeTokens: boolean):
   };
 }
 
-function geometryCell(source: CellSource): DiffCell {
+function geometryCell(source: CellSource, estimatedWrapColumns: number): DiffCell {
   return {
     type: source.type,
     content: source.content,
     lineNumber: source.lineNumber,
     tokens: [],
     fragments: [],
+    estimatedWrapColumns,
     reviewTarget: source.reviewTarget,
     sourceIdentity: source.sourceIdentity,
   };
@@ -427,20 +440,87 @@ function geometryCell(source: CellSource): DiffCell {
 function geometryLines(
   sources: Array<[CellSource] | [CellSource | null, CellSource | null]>,
   input: BuildDiffDocumentModelInput,
+  gutterWidth: number,
 ): GeometryLine[] {
+  const characterWidth = input.wrapLines ? input.measureText.measure("M") : 0;
   return sources.map((sourceCells) => {
+    const columns = input.wrapLines
+      ? Math.max(
+          1,
+          Math.floor(
+            (input.viewportWidth / sourceCells.length - gutterWidth - CODE_HORIZONTAL_PADDING) /
+              characterWidth,
+          ),
+        )
+      : Infinity;
     const cells = sourceCells.map((source) =>
-      source ? geometryCell(source) : null,
+      source ? geometryCell(source, columns) : null,
     ) as DiffLineRow["cells"];
     const reviewHeight = reviewHeightForCells(cells, input);
     return {
       cells,
       reviewHeight,
-      height: input.typography.lineHeight + reviewHeight,
+      // Unseen wrapped rows use a monospace estimate; materialization replaces
+      // it with the exact fragment count without changing source identity.
+      height:
+        input.typography.lineHeight *
+          Math.max(
+            1,
+            ...cells.map((cell) => {
+              return cell && input.wrapLines
+                ? Math.ceil(estimatedDisplayOffset(cell.content) / columns)
+                : 1;
+            }),
+          ) +
+        reviewHeight,
     };
   });
 }
 
+// Use the same tab expansion and column count for estimated heights and anchors.
+function estimatedDisplayOffset(text: string): number {
+  return text.length + (text.match(/\t/g)?.length ?? 0) * 3;
+}
+
+function estimatedVisualLine(cell: DiffCell, sourceOffset: number): number {
+  return Math.floor(
+    estimatedDisplayOffset(cell.content.slice(0, sourceOffset)) /
+      (cell.estimatedWrapColumns ?? Infinity),
+  );
+}
+
+function estimatedFragment(cell: DiffCell, visualIndex: number, lineHeight: number) {
+  const columns = cell.estimatedWrapColumns ?? Infinity;
+  const lastIndex = Math.max(0, Math.ceil(estimatedDisplayOffset(cell.content) / columns) - 1);
+  const index = Math.min(visualIndex, lastIndex);
+  const displayOffset = index === 0 ? 0 : index * columns;
+  let start = Math.min(displayOffset, cell.content.length);
+  if (cell.content.includes("\t")) {
+    let offset = 0;
+    start = 0;
+    while (start < cell.content.length && offset < displayOffset) {
+      offset += cell.content[start] === "\t" ? 4 : 1;
+      start += 1;
+    }
+  }
+  return { start, top: index * lineHeight };
+}
+
+// A resize can move the anchor outside the old window. Measure that row in the
+// same pass: estimated columns cannot identify exact shaped-text fragments.
+function containsMaterializationAnchor(
+  input: BuildDiffDocumentModelInput,
+  path: string,
+  cells: DiffLineRow["cells"],
+): boolean {
+  const anchor = input.materializationAnchor;
+  return (
+    anchor?.kind === "text" &&
+    anchor.path === path &&
+    cells.some((cell) => cell && sameSourceIdentity(cell.sourceIdentity, anchor.sourceIdentity))
+  );
+}
+
 function intersectsMaterializationWindow(
   input: BuildDiffDocumentModelInput,
   fileTop: number,
@@ -795,17 +875,27 @@ export function captureScrollAnchor(
   }
   const textY = Math.max(0, Math.min(scrollTop - row.top, row.height - row.reviewHeight));
   const visualIndex = Math.max(0, Math.floor(textY / model.lineHeight));
-  let cellIndex = row.cells.findIndex((cell) => Boolean(cell?.fragments[visualIndex]));
+  let cellIndex = row.cells.findIndex(
+    (cell) =>
+      cell &&
+      (cell.fragments.length > 0
+        ? Boolean(cell.fragments[visualIndex])
+        : estimatedFragment(cell, visualIndex, model.lineHeight).top ===
+          visualIndex * model.lineHeight),
+  );
   if (cellIndex < 0) cellIndex = row.cells.findIndex((cell) => cell !== null);
   const cell = row.cells[cellIndex];
   if (!cell) return { kind: "header", path: file.path, viewportDelta: row.top - scrollTop };
-  const fragment = cell.fragments[Math.min(cell.fragments.length - 1, visualIndex)];
-  const anchorY = row.top + (fragment?.top ?? 0);
+  const fragment =
+    cell.fragments.length > 0
+      ? cell.fragments[Math.min(cell.fragments.length - 1, visualIndex)]!
+      : estimatedFragment(cell, visualIndex, model.lineHeight);
+  const anchorY = row.top + fragment.top;
   return {
     kind: "text",
     path: file.path,
     sourceIdentity: cell.sourceIdentity,
-    cellOffset: fragment?.start ?? 0,
+    cellOffset: fragment.start,
     viewportDelta: anchorY - scrollTop,
   };
 }
@@ -831,8 +921,10 @@ export function resolveScrollAnchor(model: DiffDocumentModel, anchor: DiffScroll
   const fragment =
     cell.fragments.find(
       (candidate) => candidate.start <= anchor.cellOffset && anchor.cellOffset < candidate.end,
-    ) ?? cell.fragments.at(-1);
-  return Math.max(0, row.top + (fragment?.top ?? 0) - anchor.viewportDelta);
+    ) ??
+    cell.fragments.at(-1) ??
+    estimatedFragment(cell, estimatedVisualLine(cell, anchor.cellOffset), model.lineHeight);
+  return Math.max(0, row.top + fragment.top - anchor.viewportDelta);
 }
 
 export function resolveRelayoutScrollTop(
diff --git a/packages/app/src/git/diff-document/surface.native.tsx b/packages/app/src/git/diff-document/surface.native.tsx
index 2063198712..00a47437cd 100644
--- a/packages/app/src/git/diff-document/surface.native.tsx
+++ b/packages/app/src/git/diff-document/surface.native.tsx
@@ -38,6 +38,7 @@ import {
 } from "./horizontal-offsets";
 import {
   buildDiffDocumentModel,
+  captureScrollAnchor,
   resolveRelayoutScrollTop,
   retainReusableModels,
   shouldApplyRelayoutScroll,
@@ -138,6 +139,9 @@ export function DiffSurface(props: DiffSurfaceProps) {
         tooLarge: t("workspace.git.diff.tooLarge"),
       },
       materializationWindow: diffMaterializationWindow(fileWindowTop, viewport.height),
+      materializationAnchor: previousModelRef.current
+        ? captureScrollAnchor(previousModelRef.current, scrollTop.get())
+        : null,
       reuseFrom,
     });
     reusableModelRef.current = {
@@ -148,6 +152,7 @@ export function DiffSurface(props: DiffSurfaceProps) {
   }, [
     measurement,
     fileWindowTop,
+    scrollTop,
     props.collapsedFilePaths,
     props.displayPreferences.layout,
     props.displayPreferences.wrapLines,
diff --git a/packages/app/src/git/diff-document/surface.web.tsx b/packages/app/src/git/diff-document/surface.web.tsx
index 97801b708f..393f6dfcd7 100644
--- a/packages/app/src/git/diff-document/surface.web.tsx
+++ b/packages/app/src/git/diff-document/surface.web.tsx
@@ -28,10 +28,20 @@ import {
 } from "./hit-testing";
 import { retainHorizontalOffsetMapForPaths } from "./horizontal-offsets";
 import { HorizontalScroll } from "./horizontal-scroll.web";
-import { buildDiffDocumentModel, FILE_HEADER_HEIGHT, resolveRelayoutScrollTop } from "./model";
+import {
+  buildDiffDocumentModel,
+  captureScrollAnchor,
+  FILE_HEADER_HEIGHT,
+  resolveRelayoutScrollTop,
+} from "./model";
 import { paintWebFileHeader, paintWebViewport } from "./paint.web";
 import { hasPointerDragStarted } from "./pointer-gesture";
-import { createMeasuredAdvances } from "./text-measurement";
+import {
+  createMeasuredAdvances,
+  createAdditiveAdvances,
+  createChunkedWidthMeasurer,
+  requiresShaping,
+} from "./text-measurement";
 import { retainDiffViewport } from "./viewport";
 import type {
   DiffHit,
@@ -183,6 +193,9 @@ export function DiffSurface(props: DiffSurfaceProps) {
         tooLarge: t("workspace.git.diff.tooLarge"),
       },
       materializationWindow: diffMaterializationWindow(fileWindowTop, viewport.height),
+      materializationAnchor: previousModelRef.current
+        ? captureScrollAnchor(previousModelRef.current, scrollTopRef.current)
+        : null,
     });
     return next;
   }, [
@@ -1166,5 +1179,13 @@ function createWebTextMeasurer(typography: DiffTypography): TextMeasurer {
   };
   // Canvas exposes no glyph coverage, so `requiresShaping` alone decides which
   // runs a shaper has to see -- there is no `glyphIds` to fall back on.
-  return { measure, measureAdvances: createMeasuredAdvances((text) => measure(text)) };
+  const additive = createAdditiveAdvances(measure);
+  return {
+    measure,
+    measureAdvances: createMeasuredAdvances(measure),
+    measureWidth: createChunkedWidthMeasurer((graphemes) => {
+      const text = graphemes.join("");
+      return requiresShaping(text) ? measure(text) : (additive(graphemes).at(-1) ?? 0);
+    }),
+  };
 }
diff --git a/packages/app/src/git/diff-document/types.ts b/packages/app/src/git/diff-document/types.ts
index 4ac8125445..d98880eb8c 100644
--- a/packages/app/src/git/diff-document/types.ts
+++ b/packages/app/src/git/diff-document/types.ts
@@ -112,6 +112,8 @@ export interface DiffCell {
   lineNumber: number | null;
   tokens: DiffTokenRun[];
   fragments: DiffFragment[];
+  /** Monospace columns per visual line until this cell is measured. */
+  estimatedWrapColumns?: number;
   reviewTarget: ReviewableDiffTarget | null;
   sourceIdentity: DiffSourceIdentity;
 }
@@ -185,6 +187,8 @@ export interface BuildDiffDocumentModelInput {
   reviewActions?: InlineReviewActions;
   labels: { binary: string; tooLarge: string };
   materializationWindow?: { top: number; height: number };
+  /** Also measure the anchored row so relayout can restore its exact fragment. */
+  materializationAnchor?: DiffScrollAnchor | null;
   /** A geometry-compatible model whose unchanged file measurements may be reused. */
   reuseFrom?: readonly DiffDocumentModel[];
 }
diff --git a/packages/app/src/git/diff-document/workspace-cache.test.ts b/packages/app/src/git/diff-document/workspace-cache.test.ts
index ddf9972a46..a264d417ca 100644
--- a/packages/app/src/git/diff-document/workspace-cache.test.ts
+++ b/packages/app/src/git/diff-document/workspace-cache.test.ts
@@ -95,6 +95,37 @@ describe("diff document workspace cache", () => {
     expect(stats.calls).toBe(0);
   });
 
+  it("materializes a new anchor when the viewport window is unchanged", () => {
+    const cache = createDiffDocumentWorkspaceCache();
+    const source = diffFile();
+    source.hunks[0]!.lines = Array.from({ length: 100 }, () => ({
+      type: "add" as const,
+      content: "x".repeat(200),
+    }));
+    const { measureText } = countingMeasurer();
+    const input = modelInput([source], measureText, {
+      wrapLines: true,
+      materializationWindow: { top: 30, height: 54 },
+    });
+    const first = cache.buildModel(input);
+    const anchored = cache.buildModel({
+      ...input,
+      materializationAnchor: {
+        kind: "text",
+        path: source.path,
+        sourceIdentity: { hunkIndex: 0, lineIndex: 50, side: "new" },
+        cellOffset: 90,
+        viewportDelta: -2,
+      },
+    });
+    const firstRow = first.rows[50]!;
+    const anchoredRow = anchored.rows[50]!;
+    expect(firstRow.kind === "line" && firstRow.cells[0]!.fragments.length).toBe(0);
+    expect(anchoredRow.kind === "line" && anchoredRow.cells[0]!.fragments.length).toBeGreaterThan(
+      0,
+    );
+  });
+
   it("retains text cells for unchanged files when another file changes", () => {
     const cache = createDiffDocumentWorkspaceCache();
     const { measureText } = countingMeasurer();
diff --git a/packages/app/src/git/diff-document/workspace-cache.tsx b/packages/app/src/git/diff-document/workspace-cache.tsx
index 5b9921e31d..dac4d96c2e 100644
--- a/packages/app/src/git/diff-document/workspace-cache.tsx
+++ b/packages/app/src/git/diff-document/workspace-cache.tsx
@@ -128,7 +128,9 @@ function exactModelKey(input: Omit<BuildDiffDocumentModelInput, "reuseFrom">): s
   const materializationWindow = input.materializationWindow
     ? [input.materializationWindow.top, input.materializationWindow.height]
     : null;
-  return JSON.stringify([collapsedFilePaths, reviewGeometry, materializationWindow]);
+  const anchor = input.materializationAnchor;
+  const anchoredRow = anchor?.kind === "text" ? [anchor.path, anchor.sourceIdentity] : null;
+  return JSON.stringify([collapsedFilePaths, reviewGeometry, materializationWindow, anchoredRow]);
 }
 
 function typographyKey(typography: DiffTypography): string {
diff --git a/packages/app/src/git/diff-pane.tsx b/packages/app/src/git/diff-pane.tsx
index 3dd84f256a..59d3b49797 100644
--- a/packages/app/src/git/diff-pane.tsx
+++ b/packages/app/src/git/diff-pane.tsx
@@ -19,6 +19,7 @@ import type { Theme } from "@/styles/theme";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import {
   AlignJustify,
+  ArrowRight,
   ChevronDown,
   Columns2,
   ExternalLink,
@@ -61,6 +62,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 +203,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 +473,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 +501,8 @@ interface ChangesHeaderProps {
 }
 
 interface BuildChangesHeaderModelInput {
+  baseRef: string | null;
+  isWorktree: boolean;
   branchName: string | null;
   committedDescription?: string;
   compact: boolean;
@@ -519,6 +526,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 +638,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 +667,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 ? (
@@ -1134,7 +1158,7 @@ function DiffBodyContent({
         {emptyAction ? (
           <Button
             variant="ghost"
-            size="xs"
+            size="sm"
             testID="changes-empty-switch-mode"
             onPress={emptyAction.onPress}
           >
@@ -1904,6 +1928,8 @@ export function ChangesSurface({
   const changesHeaderModel = useMemo(
     () =>
       buildChangesHeaderModel({
+        baseRef: baseRef ?? null,
+        isWorktree: isManagedWorktree(status),
         branchName: currentBranchName,
         committedDescription: committedDiffDescription,
         compact: isMobile,
@@ -1921,6 +1947,8 @@ export function ChangesSurface({
         workspaceId,
       }),
     [
+      baseRef,
+      status,
       committedDiffDescription,
       currentBranchName,
       cwd,
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/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/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 a30b27ce8f..41806de307 100644
--- a/packages/app/src/hooks/use-acp-provider-catalog.test.ts
+++ b/packages/app/src/hooks/use-acp-provider-catalog.test.ts
@@ -62,7 +62,9 @@ describe("ACP provider catalog", () => {
     expect(findProvider("minimax-code")).toMatchObject({
       title: "MiniMax Code",
       version: "0.6.13",
-      command: ["npx", "-y", "@minimax-ai/code@0.6.13", "acp"],
+      // The package publishes `mcode`, not `code`, so npx needs the package and
+      // the binary named separately.
+      command: ["npx", "-y", "-p", "@minimax-ai/code@0.6.13", "mcode", "acp"],
     });
     expect(findProvider("minimax-code").iconSvg).toContain("<svg");
   });
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..a400cf6862 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;
 }
@@ -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-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-initialization.test.ts b/packages/app/src/hooks/use-agent-initialization.test.ts
index f2726fba02..e517021b6b 100644
--- a/packages/app/src/hooks/use-agent-initialization.test.ts
+++ b/packages/app/src/hooks/use-agent-initialization.test.ts
@@ -78,6 +78,7 @@ describe("ensureAgentIsInitialized", () => {
           cursor: { epoch: "epoch-1", seq: 42 },
           limit: TIMELINE_FETCH_PAGE_SIZE,
           projection: "projected",
+          wholeTurns: true,
         },
       },
     ]);
@@ -105,6 +106,7 @@ describe("ensureAgentIsInitialized", () => {
           direction: "tail",
           limit: TIMELINE_FETCH_PAGE_SIZE,
           projection: "projected",
+          wholeTurns: true,
         },
       },
     ]);
@@ -148,6 +150,7 @@ describe("ensureAgentIsInitialized", () => {
           direction: "tail",
           limit: TIMELINE_FETCH_PAGE_SIZE,
           projection: "projected",
+          wholeTurns: true,
         },
       },
     ]);
@@ -192,6 +195,7 @@ describe("ensureAgentIsInitialized", () => {
           cursor: { epoch: "epoch-1", seq: 12 },
           limit: TIMELINE_FETCH_PAGE_SIZE,
           projection: "projected",
+          wholeTurns: true,
         },
       },
     ]);
@@ -283,6 +287,7 @@ describe("refreshAgent", () => {
           direction: "tail",
           limit: TIMELINE_FETCH_PAGE_SIZE,
           projection: "projected",
+          wholeTurns: true,
         },
       },
     ]);
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 19caef4f8b..68102ed131 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
@@ -422,6 +422,23 @@ describe("deriveAgentScreenViewState", () => {
     expect(result.memory.lastReadyAgent).toBeNull();
   });
 
+  it.each(["error", "retrying"] as const)("shows archived history sync %s", (status) => {
+    const result = deriveAgentScreenViewState({
+      input: {
+        ...createBaseInput(),
+        agent: createAgent("agent-1"),
+        isArchived: true,
+        hasHydratedHistoryBefore: true,
+        visibilityCatchUpStatus: status,
+      },
+      memory: createBaseMemory(),
+    });
+    expect(expectReadyState(result.state).sync).toEqual({
+      status: "sync_error",
+      isRetrying: status === "retrying",
+    });
+  });
+
   it("renders an archived agent before provider history is initialized", () => {
     const result = deriveAgentScreenViewState({
       input: {
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 591fd1abb1..e0cc75ee06 100644
--- a/packages/app/src/hooks/use-agent-screen-state-machine.ts
+++ b/packages/app/src/hooks/use-agent-screen-state-machine.ts
@@ -175,10 +175,14 @@ function resolveAgentScreenSync(args: {
   hadInitialSyncFailure: boolean;
 }): AgentScreenReadySyncState {
   const { input, hadInitialSyncFailure } = args;
-  if (input.isArchived) {
+  if (
+    input.isArchived &&
+    input.visibilityCatchUpStatus !== "error" &&
+    input.visibilityCatchUpStatus !== "retrying"
+  ) {
     return { status: "idle" };
   }
-  if (!input.isConnected) {
+  if (!input.isConnected && !input.isArchived) {
     return { status: "reconnecting" };
   }
   if (input.missingAgentState.kind === "error") {
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-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-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 1da68b4edf..3259631992 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
@@ -152,6 +152,7 @@ describe("loadOlderAgentHistory", () => {
           cursor: { epoch: "epoch-1", seq: 10 },
           limit: TIMELINE_FETCH_PAGE_SIZE,
           projection: "projected",
+          wholeTurns: true,
         },
       },
     ]);
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-settings/index.ts b/packages/app/src/hooks/use-settings/index.ts
index 9f6f22fb23..382ab350fc 100644
--- a/packages/app/src/hooks/use-settings/index.ts
+++ b/packages/app/src/hooks/use-settings/index.ts
@@ -49,6 +49,7 @@ import {
   type KeyValueStorage,
   type ReleaseChannel,
   type SendBehavior,
+  type SendShortcut,
   type ServiceUrlBehavior,
   type Settings,
   type SidebarWorkspaceTrailing,
@@ -93,6 +94,7 @@ export type {
   KeyValueStorage,
   ReleaseChannel,
   SendBehavior,
+  SendShortcut,
   ServiceUrlBehavior,
   Settings,
   SettingsDeps,
diff --git a/packages/app/src/hooks/use-settings/storage.test.ts b/packages/app/src/hooks/use-settings/storage.test.ts
index fe2ffdd2a0..0b169b5214 100644
--- a/packages/app/src/hooks/use-settings/storage.test.ts
+++ b/packages/app/src/hooks/use-settings/storage.test.ts
@@ -227,6 +227,39 @@ describe("loadAppSettingsFromStorage", () => {
     expect(result.chatOutlineEnabled).toBe(false);
   });
 
+  it("uses Enter to send by default", async () => {
+    const deps = makeDeps();
+
+    const result = await loadAppSettingsFromStorage(deps);
+
+    expect(result.sendShortcut).toBe("enter");
+    expect(DEFAULT_CLIENT_SETTINGS.sendShortcut).toBe("enter");
+  });
+
+  it("loads the modifier Enter send preference", async () => {
+    const deps = makeDeps({
+      storage: createInMemoryKeyValueStorage({
+        [APP_SETTINGS_KEY]: JSON.stringify({ sendShortcut: "mod-enter" }),
+      }),
+    });
+
+    const result = await loadAppSettingsFromStorage(deps);
+
+    expect(result.sendShortcut).toBe("mod-enter");
+  });
+
+  it("falls back to Enter when the stored send shortcut is invalid", async () => {
+    const deps = makeDeps({
+      storage: createInMemoryKeyValueStorage({
+        [APP_SETTINGS_KEY]: JSON.stringify({ sendShortcut: "yes" }),
+      }),
+    });
+
+    const result = await loadAppSettingsFromStorage(deps);
+
+    expect(result.sendShortcut).toBe("enter");
+  });
+
   it("defaults sidebar navigation items to an empty preference list", async () => {
     const deps = makeDeps();
 
diff --git a/packages/app/src/hooks/use-settings/storage.ts b/packages/app/src/hooks/use-settings/storage.ts
index 3a5be63441..424536ac69 100644
--- a/packages/app/src/hooks/use-settings/storage.ts
+++ b/packages/app/src/hooks/use-settings/storage.ts
@@ -33,6 +33,8 @@ import { migrateAppSettings } from "./migrations";
 export { APP_SETTINGS_KEY } from "./keys";
 export const APP_SETTINGS_QUERY_KEY = ["app-settings"];
 
+export type SendShortcut = "enter" | "mod-enter";
+
 export type SendBehavior = ActiveTurnBehavior | "queue";
 export type ReleaseChannel = "stable" | "beta";
 export type ServiceUrlBehavior = "ask" | "in-app" | "external";
@@ -104,6 +106,7 @@ export interface AppSettings {
   chatDisplay: ChatDisplay;
   chatOutlineEnabled: boolean;
   vimKeybindings: boolean;
+  sendShortcut: SendShortcut;
   filePanelAssociations: Record<string, string>;
   /** Desktop-only preferences for implicit opens into the ordinary side pane. */
   openInSidePane: OpenInSidePanePreferences;
@@ -160,6 +163,7 @@ export const DEFAULT_CLIENT_SETTINGS: AppSettings = {
   chatDisplay: "collapseTurns",
   chatOutlineEnabled: true,
   vimKeybindings: false,
+  sendShortcut: "enter",
   filePanelAssociations: {},
   openInSidePane: DEFAULT_OPEN_IN_SIDE_PANE_PREFERENCES,
   pullRequestOpenLocation: "explorer",
@@ -264,6 +268,7 @@ const StoredAppSettingsSchema = z
     compactToolCalls: z.boolean().optional().catch(undefined),
     chatOutlineEnabled: z.boolean().catch(true),
     vimKeybindings: z.boolean().catch(false),
+    sendShortcut: z.enum(["enter", "mod-enter"]).catch("enter"),
     filePanelAssociations: z.record(z.string(), z.string()).catch({}),
     openInSidePane: z
       .object({
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 5e4d7f053c..eb6fdea5a0 100644
--- a/packages/app/src/hosts/host-chooser.tsx
+++ b/packages/app/src/hosts/host-chooser.tsx
@@ -1,32 +1,21 @@
-import { usePanelStore } from "@/stores/panel-store";
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
+import { useAddHost } from "@/hosts/add-host";
+import { Modal } from "@/components/ui/modal";
 import { createElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
-import {
-  Modal,
-  Pressable,
-  ScrollView,
-  Text,
-  View,
-  type PressableStateCallbackType,
-} from "react-native";
+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>;
@@ -71,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);
@@ -82,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;
       }
 
@@ -104,7 +88,7 @@ export function useHostChooser() {
       });
       return true;
     },
-    [hosts, localServerId, open],
+    [hosts, localServerId, open, addHost],
   );
 }
 
@@ -158,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 [];
@@ -199,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" &&
@@ -240,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 18ba3f041e..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");
@@ -832,7 +832,6 @@ describe("translation resources", () => {
     expect(en.common.placeholders.search).toBe("Search...");
     expect(en.common.empty.noResults).toBe("No results found");
     expect(en.common.empty.noOptionsMatchSearch).toBe("No options match your search.");
-    expect(en.toolCallDetails.subAgentActivity).toBe("Sub-agent activity");
     expect(en.panels.file.failedToLoadPreview).toBe("Failed to load file preview");
   });
 
diff --git a/packages/app/src/i18n/resources/ar.ts b/packages/app/src/i18n/resources/ar.ts
index 108fad41d4..9b3c41f663 100644
--- a/packages/app/src/i18n/resources/ar.ts
+++ b/packages/app/src/i18n/resources/ar.ts
@@ -67,6 +67,7 @@ export const ar: TranslationResources = {
       daemonClientUnavailable: "عميل Daemon غير متوفر",
       daemonClientDisconnected: "تم قطع اتصال عميل Daemon",
       noFileFound: "لم يتم العثور على ملف لـ{{token}}",
+      folderOutsideWorkspace: "{{path}} خارج مساحة العمل هذه",
       unexpectedDictationError: "حدث خطأ غير متوقع أثناء معالجة الإملاء.",
     },
     connectionStatus: {
@@ -378,6 +379,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: "لا توجد مهام حتى الآن.",
@@ -616,6 +635,7 @@ export const ar: TranslationResources = {
     terminal: {
       hostDisconnected: "Host غير متصل",
       updateHost: "حدّث المضيف لاستخدام عارض الطرفية الأصلي.",
+      restoreRequiresUpdate: "حدّث المضيف لعرض الطرفيات.",
       unableToSubscribe: "غير قادر على الاشتراك في المحطة",
       fileUploaded: "تم رفع الملف",
       pasteFileFailed: "تعذر لصق الملف: {{reason}}",
@@ -928,6 +948,9 @@ export const ar: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "الفرع الأساسي",
+        },
         openChangesTab: "فتح علامة تبويب التغييرات",
         openDiffTab: "فتح علامة تبويب الفرق",
         closeChangesTab: "إغلاق علامة تبويب التغييرات",
@@ -1231,6 +1254,7 @@ export const ar: TranslationResources = {
       hosts: "المضيفون",
       settings: "إعدادات",
       closeSidebar: "إغلاق الشريط الجانبي",
+      moreActions: "المزيد من الإجراءات",
     },
     footer: {
       usage: "الاستخدام",
@@ -1335,6 +1359,9 @@ export const ar: TranslationResources = {
         hostDisconnected: "Host غير متصل",
         hideFailed: "فشل في إخفاء مساحة العمل",
         archiveFailed: "فشل في أرشفة مساحة العمل",
+        archived: "تمت أرشفة مساحة العمل",
+        undoArchive: "تراجع",
+        undoArchiveFailed: "تعذّر التراجع عن الأرشفة",
       },
     },
   },
@@ -1539,6 +1566,8 @@ export const ar: TranslationResources = {
       cli: {
         statusFailed: "غير قادر على التحقق من حالة تثبيت CLI.",
         installFailed: "غير قادر على تثبيت PaseoCLI.",
+        uninstallFailed: "تعذر إلغاء تثبيت Paseo CLI.",
+        keptForeign: "تم الإبقاء على أمر paseo لم يثبته Paseo. احذفه بنفسك لإلغاء تثبيته.",
       },
     },
   },
@@ -1590,6 +1619,7 @@ export const ar: TranslationResources = {
     openPath: "فتح المسار",
   },
   branchSwitcher: {
+    failedToLoad: "تعذّر تحميل الفروع. أعد فتح قائمة الفروع للمحاولة مرة أخرى.",
     triggerTooltip: "تبديل فرع مساحة العمل",
     currentBranch: "الفرع الحالي:{{branchName}}. اضغط لتبديل الفرع.",
     placeholder: "تبديل الفرع...",
@@ -1612,7 +1642,11 @@ export const ar: TranslationResources = {
     loadingCommands: "جارٍ تحميل الأوامر...",
     noFiles: "لم يتم العثور على ملفات أو أدلة",
     noCommands: "لم يتم العثور على أي أوامر",
-    failedToLoad: "فشل التحميل",
+    loadingProviderCommands: "جارٍ تحميل أوامر {{provider}}...",
+    commandsFailed: "تعذر تحميل الأوامر",
+    providerCommandsFailed: "تعذر تحميل أوامر {{provider}}",
+    filesFailed: "تعذر البحث في الملفات",
+    skillTag: "مهارة",
     chooseProjectForCommands: "اختر مشروعًا لعرض الأوامر",
     chooseModelForCommands: "اختر نموذجًا لعرض الأوامر",
   },
@@ -1639,6 +1673,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: {
@@ -1857,6 +1945,8 @@ export const ar: TranslationResources = {
       notNow: "ليس الآن",
       directConnectionHint:
         "بدون التتابع، اتصل مباشرة عبر TCP أو Tailscale أو شبكة VPN أخرى. لن يتم إنشاء رمز QR.",
+      tailscaleDocs: "إعداد Tailscale",
+      tailscaleDocsAccessibility: "اقرأ كيفية الاتصال عبر Tailscale",
       updateRequired: "حدّث المضيف لتمكين التتابع من Paseo Desktop.",
       unavailable: "عرض الاقتران غير متاح.",
       hint: "قم بمسح رمز QR هذا باستخدام Paseo على هاتفك، أو انسخ الرابط أدناه.",
@@ -1913,7 +2003,6 @@ export const ar: TranslationResources = {
     parent: {
       backToParent: "العودة إلى الوكيل الأصلي",
       backTo: "العودة إلى {{label}}",
-      parent: "الأصل",
       parentAgent: "الوكيل الأصلي",
       openParent: "فتح الوكيل الأصلي",
     },
@@ -2013,17 +2102,17 @@ export const ar: TranslationResources = {
   toolCallDetails: {
     error: "خطأ",
     empty: "لا توجد تفاصيل إضافية متاحة",
-    subAgentActivity: "نشاط الوكيل الفرعي",
     input: "مدخل",
     output: "الإخراج",
   },
   turnSummary: {
-    messages: {
-      one: "كتب {{count}} رسالة",
-      other: "كتب {{count}} رسائل",
-    },
+    details: "عرض تفاصيل الجولة",
+    sentBy: "أرسلها {{name}}",
+    showMore: "عرض المزيد",
+    showLess: "عرض أقل",
   },
   toolCallGroup: {
+    thought: "فكّر",
     editedFiles: {
       one: "حرّر {{count}} ملفًا",
       other: "حرّر {{count}} ملفات",
@@ -2091,6 +2180,11 @@ export const ar: TranslationResources = {
     },
   },
   providerUsage: {
+    checkUsage: "التحقق من الاستخدام",
+    checkUsageHint: "ينطبق على {{host}} على جميع الأجهزة",
+    off: "التحقق من الاستخدام متوقف على {{host}}.",
+    turnOn: "تشغيل",
+
     options: "الإعدادات",
     refreshFailed: "تعذّر تحديث الاستخدام",
     noHosts: "لا توجد مضيفات متصلة",
@@ -2156,6 +2250,7 @@ export const ar: TranslationResources = {
       minutes_few: "{{value}} دقائق",
       minutes_many: "{{value}} دقيقة",
       minutes_other: "{{value}} دقيقة",
+      pair: "{{first}} و{{second}}",
     },
     timing: {
       lastUpdated: "آخر تحديث {{relativeTime}}",
@@ -2163,6 +2258,8 @@ export const ar: TranslationResources = {
       resetTimePassed: "مضى وقت إعادة التعيين",
       resettingNow: "تتم إعادة التعيين الآن",
       resetsIn: "تتم إعادة التعيين خلال {{duration}}",
+      resetsAtWeekday: "{{weekday}} {{time}}",
+      resetsAtDate: "{{date}}، {{time}}",
       runsOutNow: "ينفد الآن",
       runsOutIn: "ينفد خلال {{duration}}",
       justNow: "الآن",
@@ -2349,6 +2446,11 @@ export const ar: TranslationResources = {
     general: {
       title: "عام",
       sending: "الإرسال",
+      setup: {
+        label: "الإعداد الأولي",
+        description: "أعد المرور على المظهر والمزوّدين والمشاريع وإقران الهاتف",
+        action: "إظهار الإعداد مجددًا",
+      },
       browserData: {
         title: "بيانات المتصفح",
         siteData: "ملفات تعريف الارتباط وبيانات المواقع",
@@ -2369,12 +2471,25 @@ export const ar: TranslationResources = {
             "عند تشغيل الوكيل، يوجّه Enter الجولة النشطة. يضيف Command/Ctrl+Enter إلى قائمة الانتظار.",
           queue: "عند تشغيل الوكيل، يضيف Enter إلى قائمة الانتظار. Command/Ctrl+Enter يرسل.",
         },
+        commandEnterDescriptions: {
+          interrupt: "عند تشغيل الوكيل، يوقف {{modifier}}+Enter التشغيل. يُدرج Enter سطرًا جديدًا.",
+          steer: "عند تشغيل الوكيل، يوجّه {{modifier}}+Enter الجولة النشطة. يُدرج Enter سطرًا جديدًا.",
+          queue:
+            "عند تشغيل الوكيل، يضيف {{modifier}}+Enter إلى قائمة الانتظار. يُدرج Enter سطرًا جديدًا.",
+        },
         options: {
           interrupt: "مقاطعة",
           steer: "توجيه",
           queue: "طابور",
         },
       },
+      sendShortcut: {
+        label: "اختصار الإرسال",
+        options: {
+          enter: "Enter",
+          "mod-enter": "{{modifier}}+Enter",
+        },
+      },
       serviceUrls: {
         options: {
           ask: "بسأل",
@@ -2623,11 +2738,7 @@ export const ar: TranslationResources = {
       commandLine: {
         title: "سطر الأوامر",
         description: "وكلاء التحكم والبرنامج النصي من المحطة الطرفية الخاصة بك",
-      },
-      actions: {
-        install: "ثَبَّتَ",
-        installing: "جارٍ التثبيت...",
-        installed: "تم التثبيت",
+        accessibilityLabel: "تثبيت Paseo CLI",
       },
     },
     permissions: {
@@ -2705,10 +2816,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: "اختيار المهارات",
@@ -2725,9 +2835,6 @@ export const ar: TranslationResources = {
         uninstallFailed: "غير قادر على إلغاء تثبيت مهارات التنسيق.",
         saveSelectionFailed: "غير قادر على حفظ اختيار مهارات التنسيق.",
         actions: {
-          install: "ثَبَّتَ",
-          installing: "جارٍ التثبيت...",
-          installed: "تم التثبيت",
           update: "تحديث",
           working: "عمل...",
           remove: "إزالة",
@@ -2749,6 +2856,7 @@ export const ar: TranslationResources = {
           title: "تمكين أدوات Paseo",
           hint: "سيتمكن الوكلاء من إدارة أشجار العمل والوكلاء والجداول الزمنية",
           accessibilityLabel: "حقن أدوات Paseo",
+          updateFailed: "تعذر تحديث أدوات Paseo.",
         },
         systemPrompt: {
           title: "موجه النظام",
@@ -2764,6 +2872,14 @@ export const ar: TranslationResources = {
       },
       agents: {
         unavailable: "Connect to this host to manage agents",
+        resumeOnStartup: {
+          title: "استئناف الوكلاء بعد إعادة التشغيل",
+          info: "إعادة فتح الوكلاء الذين كانوا يعملون عند توقف المضيف وإرسال طلب الاستئناف. ينطبق ذلك بعد إعادة التشغيل العادية والتعطّل.",
+          hint: "متابعة العمل المنقطع تلقائيًا.",
+          prompt: "طلب الاستئناف",
+          edit: "تحرير",
+          editAccessibilityLabel: "تعديل الطلب",
+        },
         idleRuntimeCleanup: {
           title: "تحرير الوكلاء الخاملين",
           hint: "تحرير الذاكرة بعد ساعة من الخمول.",
@@ -2859,6 +2975,10 @@ export const ar: TranslationResources = {
           requestFailedTitle: "خطأ",
           requestFailedMessage:
             "فشل في إرسال طلب إعادة التشغيل.  يقوم Paseo بإعادة الاتصال تلقائيًا - حاول مرة أخرى بمجرد ظهور المضيف على أنه متصل بالإنترنت.",
+          closeTerminals: "إعادة التشغيل وإغلاق الطرفيات",
+          closeTerminalsHint: "يعيد التشغيل ويغلق أيضًا كل الطرفيات المفتوحة على هذا المضيف.",
+          closeTerminalsConfirmMessage:
+            "سيُعاد تشغيل الخدمة وتُغلق كل طرفياتها، مما ينهي البرامج التي تعمل فيها. سيعيد التطبيق الاتصال تلقائيًا.",
           dialogFailedMessage: "غير قادر على فتح مربع حوار تأكيد إعادة التشغيل.",
         },
         update: {
diff --git a/packages/app/src/i18n/resources/en.ts b/packages/app/src/i18n/resources/en.ts
index 16bddd9cf9..ecb2890c93 100644
--- a/packages/app/src/i18n/resources/en.ts
+++ b/packages/app/src/i18n/resources/en.ts
@@ -63,6 +63,7 @@ export const en = {
       daemonClientUnavailable: "Daemon client unavailable",
       daemonClientDisconnected: "Daemon client is disconnected",
       noFileFound: "No file found for {{token}}",
+      folderOutsideWorkspace: "{{path}} is outside this workspace",
       unexpectedDictationError: "An unexpected error occurred while handling dictation.",
     },
     connectionStatus: {
@@ -375,6 +376,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.",
@@ -613,6 +632,7 @@ export const en = {
     terminal: {
       hostDisconnected: "Host is not connected",
       updateHost: "Update the host to use the native terminal renderer.",
+      restoreRequiresUpdate: "Update the host to view terminals.",
       unableToSubscribe: "Unable to subscribe to terminal",
       fileUploaded: "File uploaded",
       pasteFileFailed: "Failed to paste file: {{reason}}",
@@ -936,6 +956,9 @@ export const en = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Change base",
+        },
         openChangesTab: "Open Changes tab",
         openDiffTab: "Open Diff tab",
         closeChangesTab: "Close Changes tab",
@@ -1239,6 +1262,7 @@ export const en = {
       hosts: "Hosts",
       settings: "Settings",
       closeSidebar: "Close sidebar",
+      moreActions: "More actions",
     },
     footer: {
       usage: "Usage",
@@ -1343,6 +1367,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",
       },
     },
   },
@@ -1563,6 +1590,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.",
       },
     },
   },
@@ -1619,6 +1649,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?",
@@ -1637,7 +1668,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",
   },
@@ -1664,6 +1699,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: {
@@ -1882,6 +1971,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.",
@@ -1938,7 +2029,6 @@ export const en = {
     parent: {
       backToParent: "Back to parent",
       backTo: "Back to {{label}}",
-      parent: "Parent",
       parentAgent: "Parent agent",
       openParent: "Open parent",
     },
@@ -2038,17 +2128,17 @@ export const en = {
   toolCallDetails: {
     error: "Error",
     empty: "No additional details available",
-    subAgentActivity: "Sub-agent activity",
     input: "Input",
     output: "Output",
   },
   turnSummary: {
-    messages: {
-      one: "wrote {{count}} message",
-      other: "wrote {{count}} messages",
-    },
+    details: "View turn details",
+    sentBy: "Sent by {{name}}",
+    showMore: "Show more",
+    showLess: "Show less",
   },
   toolCallGroup: {
+    thought: "Thought",
     editedFiles: {
       one: "edited {{count}} file",
       other: "edited {{count}} files",
@@ -2116,6 +2206,11 @@ export const en = {
     },
   },
   providerUsage: {
+    checkUsage: "Check usage",
+    checkUsageHint: "Applies to {{host}} on every device",
+    off: "Usage is off on {{host}}.",
+    turnOn: "Turn on",
+
     options: "Settings",
     refreshFailed: "Unable to refresh usage",
     noHosts: "No connected hosts",
@@ -2163,15 +2258,18 @@ export const en = {
       days: "{{value}}d",
       hours: "{{value}}h",
       minutes: "{{value}}m",
+      pair: "{{first}} {{second}}",
     },
     timing: {
       lastUpdated: "Last updated {{relativeTime}}",
       noSuccessfulUpdate: "No successful update",
       resetTimePassed: "Reset time passed",
       resettingNow: "resetting now",
-      resetsIn: "resets {{duration}}",
+      resetsIn: "resets in {{duration}}",
+      resetsAtWeekday: "{{weekday}} {{time}}",
+      resetsAtDate: "{{date}}, {{time}}",
       runsOutNow: "runs out now",
-      runsOutIn: "runs out {{duration}}",
+      runsOutIn: "runs out in {{duration}}",
       justNow: "just now",
       daysAgo: "{{value}}d ago",
       hoursAgo: "{{value}}h ago",
@@ -2316,7 +2414,7 @@ export const en = {
       installing: "Installing…",
       logs: {
         action: "Logs",
-        title: "Logs: {{id}}",
+        title: "Logs: {{name}}",
         loading: "Loading logs…",
         refresh: "Refresh",
         refreshing: "Refreshing…",
@@ -2325,7 +2423,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",
@@ -2336,16 +2435,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",
@@ -2438,6 +2537,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",
@@ -2457,12 +2561,26 @@ export const en = {
             "When the agent is running, Enter steers the active turn. Command/Ctrl+Enter queues.",
           queue: "When the agent is running, Enter queues. Command/Ctrl+Enter submits.",
         },
+        commandEnterDescriptions: {
+          interrupt:
+            "When the agent is running, {{modifier}}+Enter interrupts. Enter inserts a new line.",
+          steer:
+            "When the agent is running, {{modifier}}+Enter steers the active turn. Enter inserts a new line.",
+          queue: "When the agent is running, {{modifier}}+Enter queues. Enter inserts a new line.",
+        },
         options: {
           interrupt: "Interrupt",
           steer: "Steer",
           queue: "Queue",
         },
       },
+      sendShortcut: {
+        label: "Send shortcut",
+        options: {
+          enter: "Enter",
+          "mod-enter": "{{modifier}}+Enter",
+        },
+      },
       serviceUrls: {
         options: {
           ask: "Ask",
@@ -2710,11 +2828,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: {
@@ -2791,7 +2905,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",
@@ -2802,7 +2916,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.",
@@ -2816,9 +2929,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",
@@ -2840,6 +2950,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",
@@ -2855,6 +2966,14 @@ export const en = {
       },
       agents: {
         unavailable: "Connect to this host to manage agents",
+        resumeOnStartup: {
+          title: "Resume agents after restart",
+          info: "Reopen agents that were working when the host stopped and send the resume prompt. Applies after graceful restarts and crashes.",
+          hint: "Continue interrupted work automatically.",
+          prompt: "Resume prompt",
+          edit: "Edit",
+          editAccessibilityLabel: "Edit prompt",
+        },
         idleRuntimeCleanup: {
           title: "Release idle agents",
           hint: "Free up memory after an hour of inactivity.",
@@ -2951,6 +3070,10 @@ export const en = {
           requestFailedTitle: "Error",
           requestFailedMessage:
             "Failed to send the restart request. Paseo reconnects automatically-try again once the host shows as online.",
+          closeTerminals: "Restart and close terminals",
+          closeTerminalsHint: "Restart and also close every terminal running on this host.",
+          closeTerminalsConfirmMessage:
+            "This will restart the daemon and close every terminal on it, ending the programs running in them. The app will reconnect automatically.",
           dialogFailedMessage: "Unable to open the restart confirmation dialog.",
         },
         update: {
diff --git a/packages/app/src/i18n/resources/es.ts b/packages/app/src/i18n/resources/es.ts
index 2226583781..11968541d4 100644
--- a/packages/app/src/i18n/resources/es.ts
+++ b/packages/app/src/i18n/resources/es.ts
@@ -68,6 +68,7 @@ export const es: TranslationResources = {
       daemonClientUnavailable: "ClienteDaemonno disponible",
       daemonClientDisconnected: "El clienteDaemonestá desconectado",
       noFileFound: "No se encontró ningún archivo para{{token}}",
+      folderOutsideWorkspace: "{{path}} está fuera de este espacio de trabajo",
       unexpectedDictationError: "Se produjo un error inesperado al manejar el dictado.",
     },
     connectionStatus: {
@@ -383,6 +384,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.",
@@ -622,6 +641,7 @@ export const es: TranslationResources = {
     terminal: {
       hostDisconnected: "Hostno está conectado",
       updateHost: "Actualiza el host para usar el renderizador de terminal nativo.",
+      restoreRequiresUpdate: "Actualiza el host para ver las terminales.",
       unableToSubscribe: "No se puede suscribir al terminal",
       fileUploaded: "Archivo subido",
       pasteFileFailed: "No se pudo pegar el archivo: {{reason}}",
@@ -961,6 +981,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",
@@ -1267,6 +1290,7 @@ export const es: TranslationResources = {
       hosts: "Hosts",
       settings: "Ajustes",
       closeSidebar: "Cerrar barra lateral",
+      moreActions: "Más acciones",
     },
     footer: {
       usage: "Uso",
@@ -1371,6 +1395,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",
       },
     },
   },
@@ -1584,6 +1611,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.",
       },
     },
   },
@@ -1635,6 +1665,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...",
@@ -1658,7 +1689,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",
   },
@@ -1685,6 +1720,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: {
@@ -1905,6 +1994,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.",
@@ -1961,7 +2052,6 @@ export const es: TranslationResources = {
     parent: {
       backToParent: "Volver al padre",
       backTo: "Volver a {{label}}",
-      parent: "Padre",
       parentAgent: "Agente padre",
       openParent: "Abrir padre",
     },
@@ -2061,17 +2151,17 @@ export const es: TranslationResources = {
   toolCallDetails: {
     error: "Error",
     empty: "No hay detalles adicionales disponibles",
-    subAgentActivity: "Actividad de subagente",
     input: "Aporte",
     output: "Producción",
   },
   turnSummary: {
-    messages: {
-      one: "escribió {{count}} mensaje",
-      other: "escribió {{count}} mensajes",
-    },
+    details: "Ver detalles del turno",
+    sentBy: "Enviado por {{name}}",
+    showMore: "Mostrar más",
+    showLess: "Mostrar menos",
   },
   toolCallGroup: {
+    thought: "Razonó",
     editedFiles: {
       one: "editó {{count}} archivo",
       other: "editó {{count}} archivos",
@@ -2139,6 +2229,11 @@ export const es: TranslationResources = {
     },
   },
   providerUsage: {
+    checkUsage: "Consultar uso",
+    checkUsageHint: "Se aplica a {{host}} en todos los dispositivos",
+    off: "El uso está desactivado en {{host}}.",
+    turnOn: "Activar",
+
     options: "Configuración",
     refreshFailed: "No se pudo actualizar el uso",
     noHosts: "No hay hosts conectados",
@@ -2186,6 +2281,7 @@ export const es: TranslationResources = {
       days: "{{value}} d",
       hours: "{{value}} h",
       minutes: "{{value}} min",
+      pair: "{{first}} {{second}}",
     },
     timing: {
       lastUpdated: "Última actualización {{relativeTime}}",
@@ -2193,6 +2289,8 @@ export const es: TranslationResources = {
       resetTimePassed: "Pasó la hora de restablecimiento",
       resettingNow: "se restablece ahora",
       resetsIn: "se restablece en {{duration}}",
+      resetsAtWeekday: "{{weekday}} {{time}}",
+      resetsAtDate: "{{date}}, {{time}}",
       runsOutNow: "se agota ahora",
       runsOutIn: "se agota en {{duration}}",
       justNow: "ahora mismo",
@@ -2361,6 +2459,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",
@@ -2384,12 +2488,27 @@ export const es: TranslationResources = {
           queue:
             "Cuando el agente se está ejecutando, Enter pone en cola. Command/Ctrl+Enter envía.",
         },
+        commandEnterDescriptions: {
+          interrupt:
+            "Cuando el agente se está ejecutando, {{modifier}}+Enter interrumpe. Enter inserta una línea nueva.",
+          steer:
+            "Cuando el agente se está ejecutando, {{modifier}}+Enter dirige el turno activo. Enter inserta una línea nueva.",
+          queue:
+            "Cuando el agente se está ejecutando, {{modifier}}+Enter pone en cola. Enter inserta una línea nueva.",
+        },
         options: {
           interrupt: "Interrumpir",
           steer: "Dirigir",
           queue: "Cola",
         },
       },
+      sendShortcut: {
+        label: "Atajo de envío",
+        options: {
+          enter: "Enter",
+          "mod-enter": "{{modifier}}+Enter",
+        },
+      },
       serviceUrls: {
         options: {
           ask: "Preguntar",
@@ -2641,11 +2760,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: {
@@ -2723,10 +2838,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.",
@@ -2745,9 +2859,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",
@@ -2769,6 +2880,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",
@@ -2784,6 +2896,14 @@ export const es: TranslationResources = {
       },
       agents: {
         unavailable: "Connect to this host to manage agents",
+        resumeOnStartup: {
+          title: "Reanudar agentes tras reiniciar",
+          info: "Vuelve a abrir los agentes que estaban trabajando cuando se detuvo el host y envía el mensaje de reanudación. Se aplica tras reinicios normales y fallos.",
+          hint: "Continuar automáticamente el trabajo interrumpido.",
+          prompt: "Mensaje de reanudación",
+          edit: "Editar",
+          editAccessibilityLabel: "Editar mensaje",
+        },
         idleRuntimeCleanup: {
           title: "Liberar agentes inactivos",
           hint: "Libera memoria tras una hora de inactividad.",
@@ -2881,6 +3001,11 @@ export const es: TranslationResources = {
           requestFailedTitle: "Error",
           requestFailedMessage:
             "No se pudo enviar la solicitud de reinicio.Paseose vuelve a conectar automáticamente; inténtelo nuevamente una vez que el host se muestre en línea.",
+          closeTerminals: "Reiniciar y cerrar terminales",
+          closeTerminalsHint:
+            "Reinicia y además cierra todas las terminales abiertas en este host.",
+          closeTerminalsConfirmMessage:
+            "Esto reiniciará el daemon y cerrará todas sus terminales, terminando los programas que se ejecutan en ellas. La app se reconectará automáticamente.",
           dialogFailedMessage:
             "No se puede abrir el cuadro de diálogo de confirmación de reinicio.",
         },
diff --git a/packages/app/src/i18n/resources/fr.ts b/packages/app/src/i18n/resources/fr.ts
index 65d72d405b..4f31acf15a 100644
--- a/packages/app/src/i18n/resources/fr.ts
+++ b/packages/app/src/i18n/resources/fr.ts
@@ -68,6 +68,7 @@ export const fr: TranslationResources = {
       daemonClientUnavailable: "Client du daemon indisponible",
       daemonClientDisconnected: "Le client du daemon est déconnecté",
       noFileFound: "Aucun fichier trouvé pour {{token}}",
+      folderOutsideWorkspace: "{{path}} se trouve en dehors de cet espace de travail",
       unexpectedDictationError: "Une erreur inattendue s’est produite pendant la dictée.",
     },
     connectionStatus: {
@@ -383,6 +384,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.",
@@ -622,6 +641,7 @@ export const fr: TranslationResources = {
     terminal: {
       hostDisconnected: "L’hôte n’est pas connecté",
       updateHost: "Mettez à jour l’hôte pour utiliser le rendu natif du terminal.",
+      restoreRequiresUpdate: "Mettez à jour l’hôte pour afficher les terminaux.",
       unableToSubscribe: "Impossible de s’abonner au terminal",
       fileUploaded: "Fichier envoyé",
       pasteFileFailed: "Impossible de coller le fichier : {{reason}}",
@@ -954,6 +974,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",
@@ -1261,6 +1284,7 @@ export const fr: TranslationResources = {
       hosts: "Hôtes",
       settings: "Paramètres",
       closeSidebar: "Fermer la barre latérale",
+      moreActions: "Plus d’actions",
     },
     footer: {
       usage: "Utilisation",
@@ -1365,6 +1389,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",
       },
     },
   },
@@ -1580,6 +1607,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.",
       },
     },
   },
@@ -1631,6 +1661,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…",
@@ -1655,7 +1686,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",
   },
@@ -1683,6 +1718,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: {
@@ -1903,6 +1993,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.",
@@ -1959,7 +2051,6 @@ export const fr: TranslationResources = {
     parent: {
       backToParent: "Retour au parent",
       backTo: "Retour à {{label}}",
-      parent: "Parent",
       parentAgent: "Agent parent",
       openParent: "Ouvrir le parent",
     },
@@ -2060,17 +2151,17 @@ export const fr: TranslationResources = {
   toolCallDetails: {
     error: "Erreur",
     empty: "Aucun détail supplémentaire disponible",
-    subAgentActivity: "Activité du sous-agent",
     input: "Entrée",
     output: "Sortie",
   },
   turnSummary: {
-    messages: {
-      one: "{{count}} message écrit",
-      other: "{{count}} messages écrits",
-    },
+    details: "Voir les détails du tour",
+    sentBy: "Envoyé par {{name}}",
+    showMore: "Afficher plus",
+    showLess: "Afficher moins",
   },
   toolCallGroup: {
+    thought: "Réfléchi",
     editedFiles: {
       one: "{{count}} fichier modifié",
       other: "{{count}} fichiers modifiés",
@@ -2139,6 +2230,11 @@ export const fr: TranslationResources = {
     },
   },
   providerUsage: {
+    checkUsage: "Vérifier l’utilisation",
+    checkUsageHint: "S’applique à {{host}} sur tous les appareils",
+    off: "L’utilisation est désactivée sur {{host}}.",
+    turnOn: "Activer",
+
     options: "Paramètres",
     refreshFailed: "Impossible d’actualiser l’utilisation",
     noHosts: "Aucun hôte connecté",
@@ -2186,6 +2282,7 @@ export const fr: TranslationResources = {
       days: "{{value}} j",
       hours: "{{value}} h",
       minutes: "{{value}} min",
+      pair: "{{first}} {{second}}",
     },
     timing: {
       lastUpdated: "Dernière mise à jour {{relativeTime}}",
@@ -2193,6 +2290,8 @@ export const fr: TranslationResources = {
       resetTimePassed: "Heure de réinitialisation dépassée",
       resettingNow: "réinitialisation en cours",
       resetsIn: "se réinitialise dans {{duration}}",
+      resetsAtWeekday: "{{weekday}} {{time}}",
+      resetsAtDate: "{{date}}, {{time}}",
       runsOutNow: "s’épuise maintenant",
       runsOutIn: "s’épuise dans {{duration}}",
       justNow: "à l’instant",
@@ -2361,6 +2460,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",
@@ -2383,12 +2488,27 @@ export const fr: TranslationResources = {
           queue:
             "Quand l’agent est en cours d’exécution, Entrée met en file d’attente. Cmd/Ctrl+Entrée envoie.",
         },
+        commandEnterDescriptions: {
+          interrupt:
+            "Lorsque l'agent est en cours d'exécution, {{modifier}}+Entrée interrompt. Entrée insère une nouvelle ligne.",
+          steer:
+            "Lorsque l'agent est en cours d'exécution, {{modifier}}+Entrée oriente le tour actif. Entrée insère une nouvelle ligne.",
+          queue:
+            "Lorsque l'agent est en cours d'exécution, {{modifier}}+Entrée met en file d'attente. Entrée insère une nouvelle ligne.",
+        },
         options: {
           interrupt: "Interrompre",
           steer: "Réorienter",
           queue: "File d’attente",
         },
       },
+      sendShortcut: {
+        label: "Raccourci d’envoi",
+        options: {
+          enter: "Enter",
+          "mod-enter": "{{modifier}}+Enter",
+        },
+      },
       serviceUrls: {
         options: {
           ask: "Demander",
@@ -2643,11 +2763,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: {
@@ -2726,10 +2842,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.",
@@ -2748,9 +2863,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",
@@ -2772,6 +2884,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",
@@ -2787,6 +2900,14 @@ export const fr: TranslationResources = {
       },
       agents: {
         unavailable: "Connectez-vous à cet hôte pour gérer les agents",
+        resumeOnStartup: {
+          title: "Reprendre les agents après un redémarrage",
+          info: "Rouvre les agents qui travaillaient lorsque l’hôte s’est arrêté et envoie le message de reprise. S’applique après un redémarrage normal ou un plantage.",
+          hint: "Continuer automatiquement le travail interrompu.",
+          prompt: "Message de reprise",
+          edit: "Modifier",
+          editAccessibilityLabel: "Modifier le message",
+        },
         idleRuntimeCleanup: {
           title: "Libérer les agents inactifs",
           hint: "Libère de la mémoire après une heure d’inactivité.",
@@ -2886,6 +3007,10 @@ export const fr: TranslationResources = {
           requestFailedTitle: "Erreur",
           requestFailedMessage:
             "Impossible d’envoyer la demande de redémarrage. Paseo se reconnecte automatiquement : réessayez quand l’hôte apparaît en ligne.",
+          closeTerminals: "Redémarrer et fermer les terminaux",
+          closeTerminalsHint: "Redémarre et ferme aussi tous les terminaux ouverts sur cet hôte.",
+          closeTerminalsConfirmMessage:
+            "Le daemon va redémarrer et fermer tous ses terminaux, ce qui arrêtera les programmes qui y tournent. L'app se reconnectera automatiquement.",
           dialogFailedMessage:
             "Impossible d’ouvrir la boîte de dialogue de confirmation du redémarrage.",
         },
diff --git a/packages/app/src/i18n/resources/ja.ts b/packages/app/src/i18n/resources/ja.ts
index 5829bf4fa3..4913934cfd 100644
--- a/packages/app/src/i18n/resources/ja.ts
+++ b/packages/app/src/i18n/resources/ja.ts
@@ -68,6 +68,7 @@ export const ja: TranslationResources = {
       daemonClientUnavailable: "デーモンクライアントが利用できません",
       daemonClientDisconnected: "デーモンクライアントが切断されています",
       noFileFound: "{{token}}のファイルが見つかりません",
+      folderOutsideWorkspace: "{{path}} はこのワークスペースの外にあります",
       unexpectedDictationError: "音声入力処理中に予期しないエラーが発生しました。",
     },
     connectionStatus: {
@@ -383,6 +384,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: "タスクがまだありません。",
@@ -622,6 +641,7 @@ export const ja: TranslationResources = {
     terminal: {
       hostDisconnected: "ホストが接続されていません",
       updateHost: "ネイティブターミナルを使用するにはホストを更新してください。",
+      restoreRequiresUpdate: "ターミナルを表示するにはホストを更新してください。",
       unableToSubscribe: "ターミナルに接続できません",
       fileUploaded: "ファイルをアップロードしました",
       pasteFileFailed: "ファイルを貼り付けられませんでした: {{reason}}",
@@ -941,6 +961,9 @@ export const ja: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "ベースブランチ",
+        },
         openChangesTab: "変更タブを開く",
         openDiffTab: "差分タブを開く",
         closeChangesTab: "変更タブを閉じる",
@@ -1245,6 +1268,7 @@ export const ja: TranslationResources = {
       hosts: "ホスト",
       settings: "設定",
       closeSidebar: "サイドバーを閉じる",
+      moreActions: "その他のアクション",
     },
     footer: {
       usage: "使用状況",
@@ -1349,6 +1373,9 @@ export const ja: TranslationResources = {
         hostDisconnected: "ホストが接続されていません",
         hideFailed: "ワークスペースの非表示に失敗しました",
         archiveFailed: "ワークスペースのアーカイブに失敗しました",
+        archived: "ワークスペースをアーカイブしました",
+        undoArchive: "元に戻す",
+        undoArchiveFailed: "アーカイブを元に戻せませんでした",
       },
     },
   },
@@ -1555,6 +1582,9 @@ export const ja: TranslationResources = {
       cli: {
         statusFailed: "CLIのインストール状態を確認できません。",
         installFailed: "Paseo CLIをインストールできません。",
+        uninstallFailed: "Paseo CLI をアンインストールできません。",
+        keptForeign:
+          "Paseoがインストールしていないpaseoコマンドは残しました。アンインストールするには手動で削除してください。",
       },
     },
   },
@@ -1606,6 +1636,7 @@ export const ja: TranslationResources = {
     openPath: "パスを開く",
   },
   branchSwitcher: {
+    failedToLoad: "ブランチを読み込めませんでした。選択画面を開き直してお試しください。",
     triggerTooltip: "ワークスペースのブランチを切り替え",
     currentBranch: "現在のブランチ: {{branchName}}。押してブランチを切り替えてください。",
     placeholder: "ブランチを切り替え...",
@@ -1629,7 +1660,11 @@ export const ja: TranslationResources = {
     loadingCommands: "コマンドを読み込み中...",
     noFiles: "ファイルまたはディレクトリが見つかりません",
     noCommands: "コマンドが見つかりません",
-    failedToLoad: "読み込みに失敗しました",
+    loadingProviderCommands: "{{provider}} のコマンドを読み込み中...",
+    commandsFailed: "コマンドを読み込めませんでした",
+    providerCommandsFailed: "{{provider}} のコマンドを読み込めませんでした",
+    filesFailed: "ファイルを検索できませんでした",
+    skillTag: "スキル",
     chooseProjectForCommands: "コマンドを表示するにはプロジェクトを選択してください",
     chooseModelForCommands: "コマンドを表示するにはモデルを選択してください",
   },
@@ -1656,6 +1691,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: {
@@ -1876,6 +1966,8 @@ export const ja: TranslationResources = {
       notNow: "今はしない",
       directConnectionHint:
         "リレーを使わない場合は、TCP、Tailscale、または別の VPN で直接接続してください。QR コードは作成されません。",
+      tailscaleDocs: "Tailscale を設定",
+      tailscaleDocsAccessibility: "Tailscale で接続する方法を読む",
       updateRequired: "Paseo Desktop からリレーを有効にするにはホストを更新してください。",
       unavailable: "ペアリングオファーが利用できません。",
       hint: "スマートフォンのPaseoでこのQRコードをスキャンするか、以下のリンクをコピーしてください。",
@@ -1932,7 +2024,6 @@ export const ja: TranslationResources = {
     parent: {
       backToParent: "親に戻る",
       backTo: "{{label}} に戻る",
-      parent: "親",
       parentAgent: "親エージェント",
       openParent: "親を開く",
     },
@@ -2033,17 +2124,17 @@ export const ja: TranslationResources = {
   toolCallDetails: {
     error: "エラー",
     empty: "追加の詳細はありません",
-    subAgentActivity: "サブエージェントアクティビティ",
     input: "入力",
     output: "出力",
   },
   turnSummary: {
-    messages: {
-      one: "{{count}}件のメッセージを送信",
-      other: "{{count}}件のメッセージを送信",
-    },
+    details: "ターンの詳細を表示",
+    sentBy: "{{name}} から送信",
+    showMore: "もっと見る",
+    showLess: "折りたたむ",
   },
   toolCallGroup: {
+    thought: "思考",
     editedFiles: {
       one: "{{count}}個のファイルを編集",
       other: "{{count}}個のファイルを編集",
@@ -2112,6 +2203,11 @@ export const ja: TranslationResources = {
     },
   },
   providerUsage: {
+    checkUsage: "使用状況を確認",
+    checkUsageHint: "すべてのデバイスで {{host}} に適用",
+    off: "{{host}} の使用状況確認はオフです。",
+    turnOn: "オンにする",
+
     options: "設定",
     refreshFailed: "使用状況を更新できません",
     noHosts: "接続中のホストがありません",
@@ -2159,6 +2255,7 @@ export const ja: TranslationResources = {
       days: "{{value}}日",
       hours: "{{value}}時間",
       minutes: "{{value}}分",
+      pair: "{{first}}{{second}}",
     },
     timing: {
       lastUpdated: "最終更新: {{relativeTime}}",
@@ -2166,6 +2263,8 @@ export const ja: TranslationResources = {
       resetTimePassed: "リセット時刻を過ぎています",
       resettingNow: "まもなくリセット",
       resetsIn: "{{duration}}後にリセット",
+      resetsAtWeekday: "{{weekday}} {{time}}",
+      resetsAtDate: "{{date}} {{time}}",
       runsOutNow: "まもなく上限に到達",
       runsOutIn: "{{duration}}後に上限に到達",
       justNow: "たった今",
@@ -2334,6 +2433,12 @@ export const ja: TranslationResources = {
     general: {
       title: "一般",
       sending: "送信",
+      setup: {
+        label: "初回セットアップ",
+        description:
+          "外観、プロバイダー、プロジェクト、スマートフォンのペアリングをもう一度設定します",
+        action: "セットアップを再表示",
+      },
       browserData: {
         title: "ブラウザーデータ",
         siteData: "Cookie とサイトデータ",
@@ -2353,12 +2458,25 @@ export const ja: TranslationResources = {
             "エージェント実行中、Enterで現在のターンに指示を送ります。Command/Ctrl+Enterでキューに追加。",
           queue: "エージェント実行中、Enterでキューに追加します。Command/Ctrl+Enterで送信。",
         },
+        commandEnterDescriptions: {
+          interrupt: "エージェント実行中、{{modifier}}+Enterで中断します。Enterで改行します。",
+          steer:
+            "エージェント実行中、{{modifier}}+Enterで現在のターンに指示を送ります。Enterで改行します。",
+          queue: "エージェント実行中、{{modifier}}+Enterでキューに追加します。Enterで改行します。",
+        },
         options: {
           interrupt: "中断",
           steer: "指示",
           queue: "キュー",
         },
       },
+      sendShortcut: {
+        label: "送信ショートカット",
+        options: {
+          enter: "Enter",
+          "mod-enter": "{{modifier}}+Enter",
+        },
+      },
       serviceUrls: {
         options: {
           ask: "確認する",
@@ -2609,11 +2727,7 @@ export const ja: TranslationResources = {
       commandLine: {
         title: "コマンドライン",
         description: "ターミナルからエージェントを制御し、スクリプトで操作",
-      },
-      actions: {
-        install: "インストール",
-        installing: "インストール中...",
-        installed: "インストール済み",
+        accessibilityLabel: "Paseo CLI をインストール",
       },
     },
     permissions: {
@@ -2692,10 +2806,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オーケストレーションスキルを削除します。",
@@ -2714,9 +2827,6 @@ export const ja: TranslationResources = {
         uninstallFailed: "オーケストレーションスキルをアンインストールできません。",
         saveSelectionFailed: "オーケストレーションスキルの選択を保存できません。",
         actions: {
-          install: "インストール",
-          installing: "インストール中...",
-          installed: "インストール済み",
           update: "更新",
           working: "処理中...",
           remove: "削除",
@@ -2738,6 +2848,7 @@ export const ja: TranslationResources = {
           title: "Paseoツールを有効にする",
           hint: "エージェントがワークツリー、エージェント、スケジュールを管理できるようになります",
           accessibilityLabel: "Paseoツールを有効にする",
+          updateFailed: "Paseoツールを更新できませんでした。",
         },
         systemPrompt: {
           title: "システムプロンプト",
@@ -2753,6 +2864,14 @@ export const ja: TranslationResources = {
       },
       agents: {
         unavailable: "エージェントを管理するにはこのホストに接続してください",
+        resumeOnStartup: {
+          title: "再起動後にエージェントを再開",
+          info: "ホストの停止時に作業中だったエージェントを開き直し、再開メッセージを送信します。通常の再起動とクラッシュの両方に適用されます。",
+          hint: "中断された作業を自動的に続行します。",
+          prompt: "再開メッセージ",
+          edit: "編集",
+          editAccessibilityLabel: "メッセージを編集",
+        },
         idleRuntimeCleanup: {
           title: "アイドル状態のエージェントを解放",
           hint: "1 時間のアイドル状態の後にメモリを解放します。",
@@ -2851,6 +2970,10 @@ export const ja: TranslationResources = {
           requestFailedTitle: "エラー",
           requestFailedMessage:
             "再起動リクエストの送信に失敗しました。Paseoは自動的に再接続します。ホストがオンラインになったら再試行してください。",
+          closeTerminals: "再起動してターミナルを閉じる",
+          closeTerminalsHint: "再起動し、このホストのすべてのターミナルも閉じます。",
+          closeTerminalsConfirmMessage:
+            "デーモンを再起動し、すべてのターミナルを閉じます。ターミナルで実行中のプログラムは終了します。アプリは自動的に再接続します。",
           dialogFailedMessage: "再起動確認ダイアログを開けませんでした。",
         },
         update: {
diff --git a/packages/app/src/i18n/resources/ko.ts b/packages/app/src/i18n/resources/ko.ts
index 36a27fc84e..76c101c1d1 100644
--- a/packages/app/src/i18n/resources/ko.ts
+++ b/packages/app/src/i18n/resources/ko.ts
@@ -67,6 +67,7 @@ export const ko: TranslationResources = {
       daemonClientUnavailable: "데몬 클라이언트를 사용할 수 없습니다",
       daemonClientDisconnected: "데몬 클라이언트 연결이 끊어졌습니다",
       noFileFound: "{{token}}에 해당하는 파일을 찾을 수 없습니다",
+      folderOutsideWorkspace: "{{path}}은(는) 이 워크스페이스 밖에 있습니다",
       unexpectedDictationError: "받아쓰기를 처리하는 중 예기치 않은 오류가 발생했습니다.",
     },
     connectionStatus: {
@@ -379,6 +380,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: "아직 작업이 없습니다.",
@@ -617,6 +636,7 @@ export const ko: TranslationResources = {
     terminal: {
       hostDisconnected: "호스트가 연결되어 있지 않습니다",
       updateHost: "기본 터미널 렌더러를 사용하도록 호스트를 업데이트합니다.",
+      restoreRequiresUpdate: "터미널을 보려면 호스트를 업데이트하세요.",
       unableToSubscribe: "터미널을 구독할 수 없습니다",
       fileUploaded: "파일을 업로드했습니다",
       pasteFileFailed: "파일을 붙여넣지 못했습니다: {{reason}}",
@@ -935,6 +955,9 @@ export const ko: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "기준 브랜치",
+        },
         openChangesTab: "변경사항 탭 열기",
         openDiffTab: "Diff 탭 열기",
         closeChangesTab: "변경사항 탭 닫기",
@@ -1238,6 +1261,7 @@ export const ko: TranslationResources = {
       hosts: "호스트",
       settings: "설정",
       closeSidebar: "사이드바 닫기",
+      moreActions: "추가 작업",
     },
     footer: {
       usage: "사용량",
@@ -1342,6 +1366,9 @@ export const ko: TranslationResources = {
         hostDisconnected: "호스트가 연결되어 있지 않습니다",
         hideFailed: "워크스페이스를 숨기지 못했습니다",
         archiveFailed: "워크스페이스를 보관하지 못했습니다.",
+        archived: "워크스페이스를 보관했습니다",
+        undoArchive: "실행 취소",
+        undoArchiveFailed: "보관을 취소하지 못했습니다",
       },
     },
   },
@@ -1548,6 +1575,9 @@ export const ko: TranslationResources = {
       cli: {
         statusFailed: "CLI 설치 상태를 확인할 수 없습니다.",
         installFailed: "Paseo CLI를 설치할 수 없습니다.",
+        uninstallFailed: "Paseo CLI를 제거할 수 없습니다.",
+        keptForeign:
+          "Paseo가 설치하지 않은 paseo 명령은 그대로 두었습니다. 제거하려면 직접 삭제하세요.",
       },
     },
   },
@@ -1599,6 +1629,7 @@ export const ko: TranslationResources = {
     openPath: "경로 열기",
   },
   branchSwitcher: {
+    failedToLoad: "브랜치를 불러오지 못했습니다. 선택기를 다시 열어 재시도하세요.",
     triggerTooltip: "워크스페이스 브랜치 전환",
     currentBranch: "현재 브랜치: {{branchName}}. 브랜치를 전환하려면 누르세요.",
     placeholder: "브랜치 전환...",
@@ -1622,7 +1653,11 @@ export const ko: TranslationResources = {
     loadingCommands: "명령 불러오는 중...",
     noFiles: "파일 또는 디렉터리를 찾을 수 없습니다",
     noCommands: "명령을 찾을 수 없습니다",
-    failedToLoad: "불러오지 못했습니다",
+    loadingProviderCommands: "{{provider}} 명령 불러오는 중...",
+    commandsFailed: "명령을 불러오지 못했습니다",
+    providerCommandsFailed: "{{provider}} 명령을 불러오지 못했습니다",
+    filesFailed: "파일을 검색하지 못했습니다",
+    skillTag: "스킬",
     chooseProjectForCommands: "명령을 보려면 프로젝트를 선택하세요",
     chooseModelForCommands: "명령을 보려면 모델을 선택하세요",
   },
@@ -1649,6 +1684,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: {
@@ -1867,6 +1956,8 @@ export const ko: TranslationResources = {
       notNow: "지금은 아님",
       directConnectionHint:
         "릴레이 없이 TCP, Tailscale 또는 다른 VPN을 통해 직접 연결하세요. QR 코드가 생성되지 않습니다.",
+      tailscaleDocs: "Tailscale 설정",
+      tailscaleDocsAccessibility: "Tailscale로 연결하는 방법 읽기",
       updateRequired: "Paseo 데스크톱에서 릴레이를 활성화하려면 호스트를 업데이트하세요.",
       unavailable: "페어링 정보를 사용할 수 없습니다.",
       hint: "휴대폰의 Paseo로 이 QR 코드를 스캔하거나 아래 링크를 복사하세요.",
@@ -1923,7 +2014,6 @@ export const ko: TranslationResources = {
     parent: {
       backToParent: "상위 에이전트로 돌아가기",
       backTo: "{{label}}(으)로 돌아가기",
-      parent: "상위",
       parentAgent: "상위 에이전트",
       openParent: "상위 에이전트 열기",
     },
@@ -2023,17 +2113,17 @@ export const ko: TranslationResources = {
   toolCallDetails: {
     error: "오류",
     empty: "추가 세부 정보가 없습니다",
-    subAgentActivity: "서브에이전트 활동",
     input: "입력",
     output: "출력",
   },
   turnSummary: {
-    messages: {
-      one: "{{count}} 메시지를 작성했습니다.",
-      other: "{{count}} 메시지를 작성했습니다.",
-    },
+    details: "턴 세부 정보 보기",
+    sentBy: "{{name}}이(가) 보냄",
+    showMore: "더 보기",
+    showLess: "접기",
   },
   toolCallGroup: {
+    thought: "생각함",
     editedFiles: {
       one: "{{count}} 파일을 편집했습니다.",
       other: "{{count}} 파일을 편집했습니다.",
@@ -2101,6 +2191,11 @@ export const ko: TranslationResources = {
     },
   },
   providerUsage: {
+    checkUsage: "사용량 확인",
+    checkUsageHint: "모든 기기에서 {{host}}에 적용",
+    off: "{{host}}의 사용량 확인이 꺼져 있습니다.",
+    turnOn: "켜기",
+
     options: "설정",
     refreshFailed: "사용량을 새로 고칠 수 없습니다",
     noHosts: "연결된 호스트가 없습니다",
@@ -2148,6 +2243,7 @@ export const ko: TranslationResources = {
       days: "{{value}}일",
       hours: "{{value}}시간",
       minutes: "{{value}}분",
+      pair: "{{first}} {{second}}",
     },
     timing: {
       lastUpdated: "마지막 업데이트: {{relativeTime}}",
@@ -2155,6 +2251,8 @@ export const ko: TranslationResources = {
       resetTimePassed: "초기화 시간이 지났습니다",
       resettingNow: "지금 재설정 중",
       resetsIn: "{{duration}} 후 재설정",
+      resetsAtWeekday: "{{weekday}} {{time}}",
+      resetsAtDate: "{{date}} {{time}}",
       runsOutNow: "지금 한도에 도달",
       runsOutIn: "{{duration}} 후 한도에 도달",
       justNow: "방금",
@@ -2323,6 +2421,11 @@ export const ko: TranslationResources = {
     general: {
       title: "일반",
       sending: "전송",
+      setup: {
+        label: "초기 설정",
+        description: "모양, 제공자, 프로젝트, 휴대폰 페어링을 다시 진행합니다",
+        action: "설정 다시 보기",
+      },
       browserData: {
         title: "브라우저 데이터",
         siteData: "쿠키 및 사이트 데이터",
@@ -2344,12 +2447,27 @@ export const ko: TranslationResources = {
           queue:
             "에이전트가 실행 중일 때 Enter는 대기열에 추가합니다. Command/Ctrl+Enter는 제출합니다.",
         },
+        commandEnterDescriptions: {
+          interrupt:
+            "에이전트가 실행 중일 때 {{modifier}}+Enter는 중단합니다. Enter는 줄바꿈합니다.",
+          steer:
+            "에이전트가 실행 중일 때 {{modifier}}+Enter는 현재 턴에 지시합니다. Enter는 줄바꿈합니다.",
+          queue:
+            "에이전트가 실행 중일 때 {{modifier}}+Enter는 대기열에 추가합니다. Enter는 줄바꿈합니다.",
+        },
         options: {
           interrupt: "중단",
           steer: "지시",
           queue: "대기열",
         },
       },
+      sendShortcut: {
+        label: "전송 단축키",
+        options: {
+          enter: "Enter",
+          "mod-enter": "{{modifier}}+Enter",
+        },
+      },
       serviceUrls: {
         options: {
           ask: "물어보기",
@@ -2597,11 +2715,7 @@ export const ko: TranslationResources = {
       commandLine: {
         title: "명령줄",
         description: "터미널에서 에이전트를 제어하고 스크립팅합니다",
-      },
-      actions: {
-        install: "설치",
-        installing: "설치 중...",
-        installed: "설치됨",
+        accessibilityLabel: "Paseo CLI 설치",
       },
     },
     permissions: {
@@ -2679,10 +2793,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 오케스트레이션 스킬을 제거합니다.",
@@ -2700,9 +2813,6 @@ export const ko: TranslationResources = {
         uninstallFailed: "오케스트레이션 스킬을 제거할 수 없습니다.",
         saveSelectionFailed: "오케스트레이션 스킬 선택을 저장하지 못했습니다.",
         actions: {
-          install: "설치",
-          installing: "설치 중...",
-          installed: "설치됨",
           update: "업데이트",
           working: "작업 중...",
           remove: "제거",
@@ -2724,6 +2834,7 @@ export const ko: TranslationResources = {
           title: "Paseo 도구 활성화",
           hint: "에이전트가 워크트리, 에이전트, 일정을 관리할 수 있습니다",
           accessibilityLabel: "Paseo 도구 주입",
+          updateFailed: "Paseo 도구를 업데이트할 수 없습니다.",
         },
         systemPrompt: {
           title: "시스템 프롬프트",
@@ -2739,6 +2850,14 @@ export const ko: TranslationResources = {
       },
       agents: {
         unavailable: "에이전트를 관리하려면 이 호스트에 연결하세요",
+        resumeOnStartup: {
+          title: "재시작 후 에이전트 재개",
+          info: "호스트가 중지될 때 작업 중이던 에이전트를 다시 열고 재개 메시지를 보냅니다. 정상 재시작과 비정상 종료 후 모두 적용됩니다.",
+          hint: "중단된 작업을 자동으로 계속합니다.",
+          prompt: "재개 메시지",
+          edit: "편집",
+          editAccessibilityLabel: "메시지 편집",
+        },
         idleRuntimeCleanup: {
           title: "유휴 에이전트 해제",
           hint: "1시간 동안 활동이 없으면 메모리를 확보합니다.",
@@ -2836,6 +2955,10 @@ export const ko: TranslationResources = {
           requestFailedTitle: "오류",
           requestFailedMessage:
             "재시작 요청을 보내지 못했습니다. Paseo가 자동으로 다시 연결하므로 호스트가 온라인으로 표시되면 다시 시도하세요.",
+          closeTerminals: "재시작하고 터미널 닫기",
+          closeTerminalsHint: "재시작하면서 이 호스트의 모든 터미널도 닫습니다.",
+          closeTerminalsConfirmMessage:
+            "데몬을 재시작하고 모든 터미널을 닫습니다. 터미널에서 실행 중인 프로그램은 종료됩니다. 앱은 자동으로 다시 연결됩니다.",
           dialogFailedMessage: "재시작 확인 대화 상자를 열 수 없습니다.",
         },
         update: {
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 5a83b4345c..cbd13dfd60 100644
--- a/packages/app/src/i18n/resources/pt-BR.ts
+++ b/packages/app/src/i18n/resources/pt-BR.ts
@@ -68,6 +68,7 @@ export const ptBR: TranslationResources = {
       daemonClientUnavailable: "Cliente do daemon indisponível",
       daemonClientDisconnected: "O cliente do daemon está desconectado",
       noFileFound: "Nenhum arquivo encontrado para {{token}}",
+      folderOutsideWorkspace: "{{path}} está fora deste workspace",
       unexpectedDictationError: "Ocorreu um erro inesperado ao processar o ditado.",
     },
     connectionStatus: {
@@ -382,6 +383,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.",
@@ -621,6 +640,7 @@ export const ptBR: TranslationResources = {
     terminal: {
       hostDisconnected: "Host não está conectado",
       updateHost: "Atualize o host para usar o renderizador de terminal nativo.",
+      restoreRequiresUpdate: "Atualize o host para visualizar os terminais.",
       unableToSubscribe: "Não foi possível assinar o terminal",
       fileUploaded: "Arquivo enviado",
       pasteFileFailed: "Falha ao colar o arquivo: {{reason}}",
@@ -951,6 +971,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",
@@ -1257,6 +1280,7 @@ export const ptBR: TranslationResources = {
       hosts: "Hosts",
       settings: "Configurações",
       closeSidebar: "Fechar barra lateral",
+      moreActions: "Mais ações",
     },
     footer: {
       usage: "Uso",
@@ -1361,6 +1385,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",
       },
     },
   },
@@ -1569,6 +1596,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.",
       },
     },
   },
@@ -1620,6 +1650,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...",
@@ -1643,7 +1674,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",
   },
@@ -1670,6 +1705,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: {
@@ -1890,6 +1979,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.",
@@ -1946,7 +2037,6 @@ export const ptBR: TranslationResources = {
     parent: {
       backToParent: "Voltar ao pai",
       backTo: "Voltar para {{label}}",
-      parent: "Pai",
       parentAgent: "Agente pai",
       openParent: "Abrir pai",
     },
@@ -2046,17 +2136,17 @@ export const ptBR: TranslationResources = {
   toolCallDetails: {
     error: "Erro",
     empty: "Nenhum detalhe adicional disponível",
-    subAgentActivity: "Atividade do subagente",
     input: "Entrada",
     output: "Saída",
   },
   turnSummary: {
-    messages: {
-      one: "escreveu {{count}} mensagem",
-      other: "escreveu {{count}} mensagens",
-    },
+    details: "Ver detalhes do turno",
+    sentBy: "Enviado por {{name}}",
+    showMore: "Mostrar mais",
+    showLess: "Mostrar menos",
   },
   toolCallGroup: {
+    thought: "Pensou",
     editedFiles: {
       one: "editou {{count}} arquivo",
       other: "editou {{count}} arquivos",
@@ -2124,6 +2214,11 @@ export const ptBR: TranslationResources = {
     },
   },
   providerUsage: {
+    checkUsage: "Consultar uso",
+    checkUsageHint: "Aplica-se a {{host}} em todos os dispositivos",
+    off: "O uso está desativado em {{host}}.",
+    turnOn: "Ativar",
+
     options: "Configurações",
     refreshFailed: "Não foi possível atualizar o uso",
     noHosts: "Nenhum host conectado",
@@ -2171,6 +2266,7 @@ export const ptBR: TranslationResources = {
       days: "{{value}} d",
       hours: "{{value}} h",
       minutes: "{{value}} min",
+      pair: "{{first}} {{second}}",
     },
     timing: {
       lastUpdated: "Última atualização {{relativeTime}}",
@@ -2178,6 +2274,8 @@ export const ptBR: TranslationResources = {
       resetTimePassed: "O horário de redefinição passou",
       resettingNow: "redefinindo agora",
       resetsIn: "redefine em {{duration}}",
+      resetsAtWeekday: "{{weekday}} {{time}}",
+      resetsAtDate: "{{date}}, {{time}}",
       runsOutNow: "esgota agora",
       runsOutIn: "esgota em {{duration}}",
       justNow: "agora mesmo",
@@ -2346,6 +2444,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",
@@ -2367,12 +2470,27 @@ export const ptBR: TranslationResources = {
             "Quando o agente está em execução, Enter orienta o turno ativo. Command/Ctrl+Enter enfileira.",
           queue: "Quando o agente está em execução, Enter enfileira. Command/Ctrl+Enter envia.",
         },
+        commandEnterDescriptions: {
+          interrupt:
+            "Quando o agente está em execução, {{modifier}}+Enter interrompe. Enter insere uma nova linha.",
+          steer:
+            "Quando o agente está em execução, {{modifier}}+Enter orienta o turno ativo. Enter insere uma nova linha.",
+          queue:
+            "Quando o agente está em execução, {{modifier}}+Enter enfileira. Enter insere uma nova linha.",
+        },
         options: {
           interrupt: "Interromper",
           steer: "Orientar",
           queue: "Fila",
         },
       },
+      sendShortcut: {
+        label: "Atalho de envio",
+        options: {
+          enter: "Enter",
+          "mod-enter": "{{modifier}}+Enter",
+        },
+      },
       serviceUrls: {
         options: {
           ask: "Perguntar",
@@ -2623,11 +2741,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: {
@@ -2705,10 +2819,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.",
@@ -2727,9 +2840,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",
@@ -2751,6 +2861,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",
@@ -2766,6 +2877,14 @@ export const ptBR: TranslationResources = {
       },
       agents: {
         unavailable: "Conecte-se a este host para gerenciar agentes",
+        resumeOnStartup: {
+          title: "Retomar agentes após reiniciar",
+          info: "Reabre os agentes que estavam trabalhando quando o host parou e envia a mensagem de retomada. Aplica-se após reinicializações normais e falhas.",
+          hint: "Continuar automaticamente o trabalho interrompido.",
+          prompt: "Mensagem de retomada",
+          edit: "Editar",
+          editAccessibilityLabel: "Editar mensagem",
+        },
         idleRuntimeCleanup: {
           title: "Liberar agentes ociosos",
           hint: "Libera memória após uma hora de inatividade.",
@@ -2864,6 +2983,10 @@ export const ptBR: TranslationResources = {
           requestFailedTitle: "Erro",
           requestFailedMessage:
             "Falha ao enviar a solicitação de reinício. O Paseo reconecta automaticamente. Tente novamente quando o host aparecer como online.",
+          closeTerminals: "Reiniciar e fechar terminais",
+          closeTerminalsHint: "Reinicia e também fecha todos os terminais abertos neste host.",
+          closeTerminalsConfirmMessage:
+            "Isso reiniciará o daemon e fechará todos os terminais dele, encerrando os programas que rodam neles. O app vai se reconectar automaticamente.",
           dialogFailedMessage: "Não foi possível abrir o diálogo de confirmação de reinício.",
         },
         update: {
diff --git a/packages/app/src/i18n/resources/ru.ts b/packages/app/src/i18n/resources/ru.ts
index 135d5fe2f9..ee788167f5 100644
--- a/packages/app/src/i18n/resources/ru.ts
+++ b/packages/app/src/i18n/resources/ru.ts
@@ -68,6 +68,7 @@ export const ru: TranslationResources = {
       daemonClientUnavailable: "Daemon клиента недоступен",
       daemonClientDisconnected: "Daemon клиента отключен",
       noFileFound: "Файл для {{token}} не найден",
+      folderOutsideWorkspace: "{{path}} находится вне этого рабочего пространства",
       unexpectedDictationError: "При обработке диктовки произошла непредвиденная ошибка.",
     },
     connectionStatus: {
@@ -382,6 +383,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: "Задач пока нет.",
@@ -623,6 +642,7 @@ export const ru: TranslationResources = {
     terminal: {
       hostDisconnected: "Хост не подключён",
       updateHost: "Обновите хост, чтобы использовать нативный рендерер терминала.",
+      restoreRequiresUpdate: "Обновите хост, чтобы просматривать терминалы.",
       unableToSubscribe: "Не удалось подключиться к терминалу",
       fileUploaded: "Файл загружен",
       pasteFileFailed: "Не удалось вставить файл: {{reason}}",
@@ -945,6 +965,9 @@ export const ru: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Базовая ветка",
+        },
         openChangesTab: "Открыть вкладку «Изменения»",
         openDiffTab: "Открыть вкладку «Дифф»",
         closeChangesTab: "Закрыть вкладку «Изменения»",
@@ -1249,6 +1272,7 @@ export const ru: TranslationResources = {
       hosts: "Хосты",
       settings: "Настройки",
       closeSidebar: "Закрыть боковую панель",
+      moreActions: "Дополнительные действия",
     },
     footer: {
       usage: "Использование",
@@ -1353,6 +1377,9 @@ export const ru: TranslationResources = {
         hostDisconnected: "Хост не подключён",
         hideFailed: "Не удалось скрыть рабочее пространство",
         archiveFailed: "Не удалось архивировать рабочее пространство",
+        archived: "Рабочее пространство архивировано",
+        undoArchive: "Отменить",
+        undoArchiveFailed: "Не удалось отменить архивацию",
       },
     },
   },
@@ -1566,6 +1593,9 @@ export const ru: TranslationResources = {
       cli: {
         statusFailed: "Не удалось проверить состояние установки CLI.",
         installFailed: "Не удалось установить Paseo CLI.",
+        uninstallFailed: "Не удалось удалить Paseo CLI.",
+        keptForeign:
+          "Команда paseo, установленная не Paseo, оставлена. Чтобы удалить её, сделайте это вручную.",
       },
     },
   },
@@ -1617,6 +1647,7 @@ export const ru: TranslationResources = {
     openPath: "Открыть путь",
   },
   branchSwitcher: {
+    failedToLoad: "Не удалось загрузить ветки. Откройте список заново, чтобы повторить попытку.",
     triggerTooltip: "Переключить ветку рабочего пространства",
     currentBranch: "Текущая ветка: {{branchName}}. Нажмите, чтобы переключить ветку.",
     placeholder: "Сменить ветку...",
@@ -1641,7 +1672,11 @@ export const ru: TranslationResources = {
     loadingCommands: "Загрузка команд...",
     noFiles: "Файлы и каталоги не найдены",
     noCommands: "Команды не найдены",
-    failedToLoad: "Не удалось загрузить",
+    loadingProviderCommands: "Загрузка команд {{provider}}...",
+    commandsFailed: "Не удалось загрузить команды",
+    providerCommandsFailed: "Не удалось загрузить команды {{provider}}",
+    filesFailed: "Не удалось найти файлы",
+    skillTag: "Навык",
     chooseProjectForCommands: "Выберите проект, чтобы увидеть команды",
     chooseModelForCommands: "Выберите модель, чтобы увидеть команды",
   },
@@ -1668,6 +1703,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: {
@@ -1889,6 +1979,8 @@ export const ru: TranslationResources = {
       notNow: "Не сейчас",
       directConnectionHint:
         "Без ретранслятора подключайтесь напрямую через TCP, Tailscale или другую VPN. QR-код создаваться не будет.",
+      tailscaleDocs: "Настроить Tailscale",
+      tailscaleDocsAccessibility: "Узнать, как подключиться через Tailscale",
       updateRequired: "Обновите хост, чтобы включить ретранслятор из Paseo Desktop.",
       unavailable: "Данные для сопряжения недоступны.",
       hint: "Отсканируйте этот QR-код с помощью Paseo на телефоне или скопируйте ссылку ниже.",
@@ -1945,7 +2037,6 @@ export const ru: TranslationResources = {
     parent: {
       backToParent: "Назад к родителю",
       backTo: "Назад к {{label}}",
-      parent: "Родитель",
       parentAgent: "Родительский агент",
       openParent: "Открыть родителя",
     },
@@ -2046,17 +2137,17 @@ export const ru: TranslationResources = {
   toolCallDetails: {
     error: "Ошибка",
     empty: "Дополнительные сведения отсутствуют",
-    subAgentActivity: "Активность субагента",
     input: "Входные данные",
     output: "Выходные данные",
   },
   turnSummary: {
-    messages: {
-      one: "написано {{count}} сообщение",
-      other: "написаны сообщения ({{count}})",
-    },
+    details: "Показать подробности хода",
+    sentBy: "Отправлено агентом {{name}}",
+    showMore: "Показать больше",
+    showLess: "Свернуть",
   },
   toolCallGroup: {
+    thought: "Обдумал",
     editedFiles: {
       one: "изменён {{count}} файл",
       other: "изменены файлы ({{count}})",
@@ -2124,6 +2215,11 @@ export const ru: TranslationResources = {
     },
   },
   providerUsage: {
+    checkUsage: "Проверять использование",
+    checkUsageHint: "Применяется к {{host}} на всех устройствах",
+    off: "Проверка использования отключена на {{host}}.",
+    turnOn: "Включить",
+
     options: "Настройки",
     refreshFailed: "Не удалось обновить использование",
     noHosts: "Нет подключённых хостов",
@@ -2171,6 +2267,7 @@ export const ru: TranslationResources = {
       days: "{{value}} дн.",
       hours: "{{value}} ч",
       minutes: "{{value}} мин",
+      pair: "{{first}} {{second}}",
     },
     timing: {
       lastUpdated: "Последнее обновление {{relativeTime}}",
@@ -2178,6 +2275,8 @@ export const ru: TranslationResources = {
       resetTimePassed: "Время сброса прошло",
       resettingNow: "сброс сейчас",
       resetsIn: "сброс через {{duration}}",
+      resetsAtWeekday: "{{weekday}} {{time}}",
+      resetsAtDate: "{{date}}, {{time}}",
       runsOutNow: "закончится сейчас",
       runsOutIn: "закончится через {{duration}}",
       justNow: "только что",
@@ -2348,6 +2447,11 @@ export const ru: TranslationResources = {
     general: {
       title: "Основные",
       sending: "Отправка",
+      setup: {
+        label: "Первоначальная настройка",
+        description: "Снова пройти оформление, провайдеры, проекты и привязку телефона",
+        action: "Показать настройку снова",
+      },
       browserData: {
         title: "Данные браузера",
         siteData: "Файлы cookie и данные сайтов",
@@ -2370,12 +2474,27 @@ export const ru: TranslationResources = {
           queue:
             "Когда агент работает, Enter ставит сообщение в очередь, а Command/Ctrl+Enter отправляет его.",
         },
+        commandEnterDescriptions: {
+          interrupt:
+            "Когда агент работает, {{modifier}}+Enter прерывает его работу, а Enter вставляет новую строку.",
+          steer:
+            "Когда агент работает, {{modifier}}+Enter дополняет текущий ответ новым указанием, а Enter вставляет новую строку.",
+          queue:
+            "Когда агент работает, {{modifier}}+Enter ставит сообщение в очередь, а Enter вставляет новую строку.",
+        },
         options: {
           interrupt: "Прерывать",
           steer: "Направить",
           queue: "Поставить в очередь",
         },
       },
+      sendShortcut: {
+        label: "Сочетание клавиш для отправки",
+        options: {
+          enter: "Enter",
+          "mod-enter": "{{modifier}}+Enter",
+        },
+      },
       serviceUrls: {
         options: {
           ask: "Спрашивать",
@@ -2629,11 +2748,7 @@ export const ru: TranslationResources = {
       commandLine: {
         title: "Командная строка",
         description: "Управляйте агентами и автоматизируйте их работу из терминала",
-      },
-      actions: {
-        install: "Установить",
-        installing: "Установка...",
-        installed: "Установлено",
+        accessibilityLabel: "Установить Paseo CLI",
       },
     },
     permissions: {
@@ -2712,14 +2827,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 на этом хосте.",
@@ -2737,9 +2851,6 @@ export const ru: TranslationResources = {
         uninstallFailed: "Не удалось удалить навыки оркестрации.",
         saveSelectionFailed: "Не удалось сохранить выбор навыков оркестрации.",
         actions: {
-          install: "Установить",
-          installing: "Установка...",
-          installed: "Установлено",
           update: "Обновить",
           working: "Выполняется...",
           remove: "Удалить",
@@ -2761,6 +2872,7 @@ export const ru: TranslationResources = {
           title: "Включить инструменты Paseo",
           hint: "Агенты смогут управлять worktree, агентами и расписаниями.",
           accessibilityLabel: "Добавить инструменты Paseo",
+          updateFailed: "Не удалось обновить инструменты Paseo.",
         },
         systemPrompt: {
           title: "Системный промпт",
@@ -2776,6 +2888,14 @@ export const ru: TranslationResources = {
       },
       agents: {
         unavailable: "Подключитесь к этому хосту, чтобы управлять агентами",
+        resumeOnStartup: {
+          title: "Возобновлять агентов после перезапуска",
+          info: "Открывает агентов, которые работали при остановке хоста, и отправляет сообщение для продолжения. Применяется после обычного перезапуска и сбоя.",
+          hint: "Автоматически продолжать прерванную работу.",
+          prompt: "Сообщение для продолжения",
+          edit: "Редактировать",
+          editAccessibilityLabel: "Изменить сообщение",
+        },
         idleRuntimeCleanup: {
           title: "Освобождать неактивных агентов",
           hint: "Освобождает память после часа бездействия.",
@@ -2874,6 +2994,10 @@ export const ru: TranslationResources = {
           requestFailedTitle: "Ошибка",
           requestFailedMessage:
             "Не удалось отправить запрос на перезапуск. Paseo переподключается автоматически. Повторите попытку, когда хост появится в сети.",
+          closeTerminals: "Перезапустить и закрыть терминалы",
+          closeTerminalsHint: "Перезапускает демон и закрывает все терминалы на этом хосте.",
+          closeTerminalsConfirmMessage:
+            "Демон будет перезапущен, а все его терминалы закрыты вместе с запущенными в них программами. Приложение переподключится автоматически.",
           dialogFailedMessage: "Не удалось открыть диалог подтверждения перезапуска.",
         },
         update: {
diff --git a/packages/app/src/i18n/resources/zh-CN.ts b/packages/app/src/i18n/resources/zh-CN.ts
index 78b0f06442..ea9d34fd4f 100644
--- a/packages/app/src/i18n/resources/zh-CN.ts
+++ b/packages/app/src/i18n/resources/zh-CN.ts
@@ -67,6 +67,7 @@ export const zhCN: TranslationResources = {
       daemonClientUnavailable: "Daemon client 不可用",
       daemonClientDisconnected: "Daemon client 已断开连接",
       noFileFound: "未找到 {{token}} 对应的文件",
+      folderOutsideWorkspace: "{{path}} 不在此工作区内",
       unexpectedDictationError: "处理听写时发生意外错误。",
     },
     connectionStatus: {
@@ -378,6 +379,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: "还没有任务。",
@@ -616,6 +635,7 @@ export const zhCN: TranslationResources = {
     terminal: {
       hostDisconnected: "Host 未连接",
       updateHost: "请更新主机以使用原生终端渲染器。",
+      restoreRequiresUpdate: "更新主机以查看终端。",
       unableToSubscribe: "无法订阅 Terminal",
       fileUploaded: "文件已上传",
       pasteFileFailed: "无法粘贴文件：{{reason}}",
@@ -920,6 +940,9 @@ export const zhCN: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "基准分支",
+        },
         openChangesTab: "打开“更改”标签页",
         openDiffTab: "打开 Diff 标签页",
         closeChangesTab: "关闭“更改”标签页",
@@ -1223,6 +1246,7 @@ export const zhCN: TranslationResources = {
       hosts: "Hosts",
       settings: "设置",
       closeSidebar: "关闭侧边栏",
+      moreActions: "更多操作",
     },
     footer: {
       usage: "使用情况",
@@ -1324,6 +1348,9 @@ export const zhCN: TranslationResources = {
         hostDisconnected: "Host 未连接",
         hideFailed: "隐藏 workspace 失败",
         archiveFailed: "归档工作区失败",
+        archived: "工作区已归档",
+        undoArchive: "撤销",
+        undoArchiveFailed: "无法撤销归档",
       },
     },
   },
@@ -1523,6 +1550,8 @@ export const zhCN: TranslationResources = {
       cli: {
         statusFailed: "无法检查 CLI 安装状态。",
         installFailed: "无法安装 Paseo CLI。",
+        uninstallFailed: "无法卸载 Paseo CLI。",
+        keptForeign: "已保留一个不是由 Paseo 安装的 paseo 命令。如需卸载，请手动删除。",
       },
     },
   },
@@ -1573,6 +1602,7 @@ export const zhCN: TranslationResources = {
     openPath: "打开路径",
   },
   branchSwitcher: {
+    failedToLoad: "无法加载分支，请重新打开选择器以重试。",
     triggerTooltip: "切换工作区分支",
     currentBranch: "当前分支：{{branchName}}。按下以切换分支。",
     placeholder: "切换分支...",
@@ -1595,7 +1625,11 @@ export const zhCN: TranslationResources = {
     loadingCommands: "正在加载 commands...",
     noFiles: "没有找到文件或目录",
     noCommands: "没有找到 commands",
-    failedToLoad: "加载失败",
+    loadingProviderCommands: "正在加载 {{provider}} commands...",
+    commandsFailed: "无法加载 commands",
+    providerCommandsFailed: "无法加载 {{provider}} commands",
+    filesFailed: "无法搜索文件",
+    skillTag: "Skill",
     chooseProjectForCommands: "选择项目以查看命令",
     chooseModelForCommands: "选择模型以查看命令",
   },
@@ -1622,6 +1656,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: {
@@ -1836,6 +1923,8 @@ export const zhCN: TranslationResources = {
       notNow: "暂不",
       directConnectionHint:
         "不使用中继时，请通过 TCP、Tailscale 或其他 VPN 直接连接。不会生成二维码。",
+      tailscaleDocs: "设置 Tailscale",
+      tailscaleDocsAccessibility: "了解如何通过 Tailscale 连接",
       updateRequired: "请更新主机，以便从 Paseo Desktop 启用中继。",
       unavailable: "配对 offer 不可用。",
       hint: "用手机上的 Paseo 扫描此二维码，或复制下方链接。",
@@ -1891,7 +1980,6 @@ export const zhCN: TranslationResources = {
     parent: {
       backToParent: "返回父代理",
       backTo: "返回 {{label}}",
-      parent: "父代理",
       parentAgent: "父代理",
       openParent: "打开父代理",
     },
@@ -1991,17 +2079,17 @@ export const zhCN: TranslationResources = {
   toolCallDetails: {
     error: "错误",
     empty: "没有可用的更多详情",
-    subAgentActivity: "Sub-agent 活动",
     input: "输入",
     output: "输出",
   },
   turnSummary: {
-    messages: {
-      one: "写了 {{count}} 条消息",
-      other: "写了 {{count}} 条消息",
-    },
+    details: "查看轮次详情",
+    sentBy: "由 {{name}} 发送",
+    showMore: "展开",
+    showLess: "收起",
   },
   toolCallGroup: {
+    thought: "已思考",
     editedFiles: {
       one: "编辑了 {{count}} 个文件",
       other: "编辑了 {{count}} 个文件",
@@ -2069,6 +2157,11 @@ export const zhCN: TranslationResources = {
     },
   },
   providerUsage: {
+    checkUsage: "检查用量",
+    checkUsageHint: "在所有设备上应用于 {{host}}",
+    off: "{{host}} 的用量检查已关闭。",
+    turnOn: "开启",
+
     options: "设置",
     refreshFailed: "无法刷新用量",
     noHosts: "没有已连接的主机",
@@ -2116,6 +2209,7 @@ export const zhCN: TranslationResources = {
       days: "{{value}}天",
       hours: "{{value}}小时",
       minutes: "{{value}}分钟",
+      pair: "{{first}}{{second}}",
     },
     timing: {
       lastUpdated: "上次更新于 {{relativeTime}}",
@@ -2123,6 +2217,8 @@ export const zhCN: TranslationResources = {
       resetTimePassed: "重置时间已过",
       resettingNow: "正在重置",
       resetsIn: "将在 {{duration}}后重置",
+      resetsAtWeekday: "{{weekday}} {{time}}",
+      resetsAtDate: "{{date}} {{time}}",
       runsOutNow: "即将用尽",
       runsOutIn: "将在 {{duration}}后用尽",
       justNow: "刚刚",
@@ -2290,6 +2386,11 @@ export const zhCN: TranslationResources = {
     general: {
       title: "通用",
       sending: "发送",
+      setup: {
+        label: "首次设置",
+        description: "重新设置外观、提供方、项目和手机配对",
+        action: "再次显示设置",
+      },
       browserData: {
         title: "浏览器数据",
         siteData: "Cookie 和网站数据",
@@ -2308,12 +2409,24 @@ export const zhCN: TranslationResources = {
           steer: "Agent 运行时，Enter 会引导当前回合。Command/Ctrl+Enter 会排队。",
           queue: "Agent 运行时，Enter 会排队。Command/Ctrl+Enter 会提交。",
         },
+        commandEnterDescriptions: {
+          interrupt: "Agent 运行时，{{modifier}}+Enter 会中断。Enter 会插入换行。",
+          steer: "Agent 运行时，{{modifier}}+Enter 会引导当前回合。Enter 会插入换行。",
+          queue: "Agent 运行时，{{modifier}}+Enter 会排队。Enter 会插入换行。",
+        },
         options: {
           interrupt: "中断",
           steer: "引导",
           queue: "排队",
         },
       },
+      sendShortcut: {
+        label: "发送快捷键",
+        options: {
+          enter: "Enter",
+          "mod-enter": "{{modifier}}+Enter",
+        },
+      },
       serviceUrls: {
         options: {
           ask: "询问",
@@ -2559,11 +2672,7 @@ export const zhCN: TranslationResources = {
       commandLine: {
         title: "命令行",
         description: "从终端控制 Agent 并运行脚本",
-      },
-      actions: {
-        install: "安装",
-        installing: "正在安装...",
-        installed: "已安装",
+        accessibilityLabel: "安装 Paseo CLI",
       },
     },
     permissions: {
@@ -2641,10 +2750,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",
@@ -2661,9 +2769,6 @@ export const zhCN: TranslationResources = {
         uninstallFailed: "无法卸载编排 skills。",
         saveSelectionFailed: "无法保存编排 skills 的选择。",
         actions: {
-          install: "安装",
-          installing: "正在安装...",
-          installed: "已安装",
           update: "更新",
           working: "处理中...",
           remove: "移除",
@@ -2685,6 +2790,7 @@ export const zhCN: TranslationResources = {
           title: "启用 Paseo tools",
           hint: "Agent 将能够管理 worktree、Agent 和计划",
           accessibilityLabel: "注入 Paseo tools",
+          updateFailed: "无法更新 Paseo 工具。",
         },
         systemPrompt: {
           title: "System prompt",
@@ -2700,6 +2806,14 @@ export const zhCN: TranslationResources = {
       },
       agents: {
         unavailable: "连接到这个 Host 以管理 Agent",
+        resumeOnStartup: {
+          title: "重启后恢复智能体",
+          info: "重新打开主机停止时正在工作的智能体，并发送恢复提示。适用于正常重启和崩溃后的恢复。",
+          hint: "自动继续被中断的工作。",
+          prompt: "恢复提示",
+          edit: "编辑",
+          editAccessibilityLabel: "编辑提示",
+        },
         idleRuntimeCleanup: {
           title: "释放空闲 Agent",
           hint: "空闲一小时后释放内存。",
@@ -2791,6 +2905,10 @@ export const zhCN: TranslationResources = {
           offlineMessage: "这个 Host 已离线。Paseo 会自动重连，请等它恢复在线后再重启。",
           requestFailedTitle: "错误",
           requestFailedMessage: "发送重启请求失败。Paseo 会自动重连，请在 Host 显示在线后重试。",
+          closeTerminals: "重启并关闭终端",
+          closeTerminalsHint: "重启的同时关闭此主机上的所有终端。",
+          closeTerminalsConfirmMessage:
+            "这将重启守护进程并关闭其所有终端，终端中运行的程序会被结束。应用会自动重新连接。",
           dialogFailedMessage: "无法打开重启确认对话框。",
         },
         update: {
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 8139459b2b..c610ec2410 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,
@@ -44,7 +44,7 @@ import { useAgentDescriptor } from "@/agent-presentation";
 import { useToastHost, type ToastApi, type ToastState } from "@/components/toast-host";
 import type { WorkspaceComposerAttachment } from "@/attachments/types";
 import { useWorkspaceAttachmentScopeKey } from "@/attachments/workspace-attachments-store";
-import { COMPACT_FORM_FACTOR_WIDTH, useIsCompactFormFactor } from "@/constants/layout";
+import { COMPACT_CONTENT_WIDTH, useIsCompactFormFactor } from "@/constants/layout";
 import { isNative, isWeb } from "@/constants/platform";
 import { useAgentAttentionClear } from "@/hooks/use-agent-attention-clear";
 import { useAgentInputDraft, type AgentInputDraft } from "@/composer/draft/input-draft";
@@ -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,8 +78,9 @@ 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 { ParentAgentCallout, useParentAgentId } from "@/subagents/parent";
 import { useCreateFlowStore } from "@/stores/create-flow-store";
 import { buildDraftStoreKey, generateDraftId } from "@/stores/draft-keys";
@@ -91,14 +91,13 @@ import {
   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";
@@ -217,7 +216,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 +225,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 +326,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 +358,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 +432,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 +472,7 @@ function AgentPanelContent({
       : runtimeConnectionStatus;
   const lastConnectionError = runtimeLastError;
 
-  if (!resolvedServerId || (!runtimeClient && !hasCachedAgent)) {
+  if (target.kind === "agent" && (!resolvedServerId || (!runtimeClient && !hasCachedAgent))) {
     return (
       <AgentSessionUnavailableState
         serverLabel={serverLabel}
@@ -499,9 +486,9 @@ function AgentPanelContent({
 
   return (
     <AgentPanelBody
-      serverId={resolvedServerId}
+      serverId={resolvedServerId ?? serverId}
       workspaceId={workspaceId}
-      agentId={resolvedAgentId}
+      target={target}
       isPaneFocused={isPaneFocused}
       client={runtimeClient}
       isConnected={runtimeIsConnected}
@@ -513,7 +500,7 @@ function AgentPanelContent({
 function AgentPanelBody({
   serverId,
   workspaceId,
-  agentId,
+  target,
   isPaneFocused,
   client,
   isConnected,
@@ -521,13 +508,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(
@@ -642,7 +630,7 @@ function AgentPanelBody({
         }
       : null;
 
-  if (!agent) {
+  if (target.kind === "agent" && !agent) {
     return (
       <View style={styles.container} testID="agent-loading">
         <View style={styles.errorContainer}>
@@ -656,7 +644,7 @@ function AgentPanelBody({
     <ChatAgentContent
       serverId={serverId}
       workspaceId={workspaceId}
-      agentId={agentId}
+      target={target}
       isPaneFocused={isPaneFocused}
       client={client}
       isConnected={isConnected}
@@ -668,7 +656,7 @@ function AgentPanelBody({
 function ChatAgentContent({
   serverId,
   workspaceId,
-  agentId,
+  target,
   isPaneFocused,
   client,
   isConnected,
@@ -676,19 +664,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;
@@ -763,35 +751,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 +973,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,7 +1004,8 @@ function ChatAgentContent({
     <ChatAgentReadyContent
       serverId={serverId}
       workspaceId={workspaceId}
-      agentId={agentId}
+      agentId={agentId ?? tabId}
+      draft={draft}
       isPaneFocused={isPaneFocused}
       isArchivingCurrentAgent={isArchivingCurrentAgent}
       agentState={agentState}
@@ -1032,7 +1023,7 @@ function ChatAgentContent({
       showHistorySyncOverlay={showHistorySyncOverlay}
       showHistorySyncError={showHistorySyncError}
       isRetryingHistorySync={isRetryingHistorySync}
-      cwd={agentCwd}
+      cwd={agentState.cwd ?? ""}
       retryTimelineSync={retryTimelineSync}
       onAttentionInputFocus={attentionController.clearOnInputFocus}
       onAttentionPromptSend={attentionController.clearOnPromptSend}
@@ -1045,6 +1036,7 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
   serverId,
   workspaceId,
   agentId,
+  draft,
   isPaneFocused,
   isArchivingCurrentAgent,
   agentState,
@@ -1070,11 +1062,13 @@ 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;
   toastApi: ToastApi;
@@ -1096,31 +1090,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 +1148,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 +1169,46 @@ 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}
           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 +1244,7 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
     </ChatSurface>
   );
 
-  return (
+  const content = (
     <RewindComposerRestoreProvider
       textSource={agentInputDraft.textSource}
       setText={agentInputDraft.replaceText}
@@ -1274,8 +1263,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,
@@ -1308,7 +1329,6 @@ function TimelineSyncErrorCallout({
             {t("agentPanel.states.timelineSyncFailed")}
           </Text>
           <Button
-            size="sm"
             variant="secondary"
             onPress={onRetry}
             disabled={isRetrying}
@@ -1334,36 +1354,33 @@ function SheetAgentFacts({ serverId, agentId }: { serverId: string; agentId: str
 const AgentStreamSection = memo(function AgentStreamSection({
   streamViewRef,
   serverId,
-  workspaceId,
   agentId,
   agent,
+  draft,
   routeBottomAnchorRequest,
   hasAppliedAuthoritativeHistory,
   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;
   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);
@@ -1408,7 +1425,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}
@@ -1429,6 +1470,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,
@@ -1512,7 +1591,7 @@ function ActiveAgentComposer({
 }) {
   const isCompactFormFactor = useIsCompactFormFactor();
   const { onLayout: onInputAreaLayout, isBelow: isCompactComposerLayout } = useContainerWidthBelow(
-    COMPACT_FORM_FACTOR_WIDTH,
+    COMPACT_CONTENT_WIDTH,
     { initialIsBelow: isCompactFormFactor },
   );
   const paneContext = usePaneContext();
diff --git a/packages/app/src/panels/agent-tracks.tsx b/packages/app/src/panels/agent-tracks.tsx
index f7c724133a..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,
-  useSubagentOpensInSheet,
-  type SubagentRow,
+  useSubagentSheetTab,
+  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 });
@@ -100,7 +107,7 @@ export const AgentTracks = memo(function AgentTracks({
     },
     [openSubagentTarget],
   );
-  const opensInSheet = useSubagentOpensInSheet(workspaceKey);
+  const sheetTabFor = useSubagentSheetTab(workspaceKey, tabId);
   const handleOpenChanges = useCallback(() => {
     if (!workspaceKey) {
       return;
@@ -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
@@ -134,10 +129,10 @@ export const AgentTracks = memo(function AgentTracks({
         rows={subagentRows}
         onOpenSubagent={handleOpenSubagent}
         onOpenProviderSubagent={handleOpenProviderSubagent}
-        opensInSheet={opensInSheet}
+        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/provider-subagent-panel.tsx b/packages/app/src/panels/provider-subagent-panel.tsx
index e36f7880ca..377d5331c8 100644
--- a/packages/app/src/panels/provider-subagent-panel.tsx
+++ b/packages/app/src/panels/provider-subagent-panel.tsx
@@ -16,9 +16,10 @@ import { usePaneContext } from "@/panels/pane-context";
 import { PaneSubtitle } from "@/panels/pane-subtitle";
 import { definePanel, type PanelDescriptor } from "@/panels/panel-registry";
 import { useSessionStore } from "@/stores/session-store";
+import type { SheetTab } from "@/stores/workspace-layout-store";
 import { ParentAgentCallout } from "@/subagents/parent";
 import { type SubagentRow, useSubagentsForParent } from "@/subagents/select";
-import { useSubagentOpensInSheet } from "@/subagents/opens-in-sheet";
+import { useSubagentSheetTab } from "@/subagents/sheet-tab";
 import { SubagentsTrack } from "@/subagents/track";
 import {
   providerSubagentKey,
@@ -30,7 +31,7 @@ import {
 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";
@@ -51,12 +52,12 @@ function ProviderSubagentChildTrack({
   serverId,
   rows,
   onOpenProviderSubagent,
-  opensInSheet,
+  sheetTabFor,
 }: {
   serverId: string;
   rows: ReturnType<typeof useSubagentsForParent>;
   onOpenProviderSubagent: (parentAgentId: string, subagentId: string) => void;
-  opensInSheet: (row: SubagentRow) => boolean;
+  sheetTabFor: (row: SubagentRow) => SheetTab | null;
 }) {
   if (rows.length === 0) return null;
   return (
@@ -66,7 +67,7 @@ function ProviderSubagentChildTrack({
         rows={rows}
         onOpenSubagent={NOOP_SUBAGENT}
         onOpenProviderSubagent={onOpenProviderSubagent}
-        opensInSheet={opensInSheet}
+        sheetTabFor={sheetTabFor}
         onArchiveSubagent={NOOP_SUBAGENT}
       />
     </ComposerTrackBar>
@@ -106,17 +107,14 @@ 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,
   };
 }
 
 function ProviderSubagentPanel() {
   const { t } = useTranslation();
-  const { serverId, workspaceId, target, openFileInWorkspace, openTab } = usePaneContext();
+  const { serverId, workspaceId, tabId, target, openFileInWorkspace, openTab } = usePaneContext();
   invariant(target.kind === "provider_subagent", "ProviderSubagentPanel requires provider target");
   const key = providerSubagentKey(serverId, target.parentAgentId, target.subagentId);
   const streamId = `provider:${encodeURIComponent(target.parentAgentId)}:${encodeURIComponent(target.subagentId)}`;
@@ -144,8 +142,9 @@ function ProviderSubagentPanel() {
     providerParentSubagentId: target.subagentId,
   });
   const childTrackClearance = resolveChildTrackClearance(childRows.length, isCompact);
-  const opensInSheet = useSubagentOpensInSheet(
+  const sheetTabFor = useSubagentSheetTab(
     buildWorkspaceTabPersistenceKey({ serverId, workspaceId }),
+    tabId,
   );
   const openProviderChild = useCallback(
     (parentAgentId: string, subagentId: string) => {
@@ -274,7 +273,7 @@ function ProviderSubagentPanel() {
           serverId={serverId}
           rows={childRows}
           onOpenProviderSubagent={openProviderChild}
-          opensInSheet={opensInSheet}
+          sheetTabFor={sheetTabFor}
         />
       </View>
       <ParentAgentCallout serverId={serverId} parentAgentId={target.parentAgentId} />
diff --git a/packages/app/src/panels/retained-chat-content.browser.test.tsx b/packages/app/src/panels/retained-chat-content.browser.test.tsx
index 57977dd462..3ffeb1bfef 100644
--- a/packages/app/src/panels/retained-chat-content.browser.test.tsx
+++ b/packages/app/src/panels/retained-chat-content.browser.test.tsx
@@ -34,11 +34,24 @@ import {
 import type { ContextBridge } from "@/components/ui/isolated-bottom-sheet-modal";
 
 import { render as renderEnvironment } from "@testing-library/react";
-import { useWorkspaceSheetEnvironment } from "@/screens/workspace/workspace-sheet-environment";
+import {
+  SheetPaneHostProvider,
+  useSheetPaneBridge,
+  type SheetPaneHost,
+} from "@/screens/workspace/sheet-pane";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { useAssistantFileLinkActions, type InlinePathTarget } from "@/assistant-file-links";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+const SHEET_PANE_HOST: SheetPaneHost = {
+  workspaceKey: "host:workspace",
+  serverId: "host",
+  workspaceId: "workspace",
+  isWorkspaceFocused: true,
+  buildContent: () => {
+    throw new Error("The environment probe builds no pane content");
+  },
+};
 let root: Root;
 let container: HTMLDivElement;
 beforeEach(() => {
@@ -155,14 +168,21 @@ describe("workspace sheet environment", () => {
       }, [name]);
       return null;
     }
-    function Capture() {
-      bridge = useWorkspaceSheetEnvironment();
+    function CaptureBridge() {
+      bridge = useSheetPaneBridge();
       return (
         <ComposerEditingScope tabId="file" targetKey="file:a">
           <Probe name="pane" />
         </ComposerEditingScope>
       );
     }
+    function Capture() {
+      return (
+        <SheetPaneHostProvider value={SHEET_PANE_HOST}>
+          <CaptureBridge />
+        </SheetPaneHostProvider>
+      );
+    }
     function Source({ workspaceRoot, active }: { workspaceRoot: string; active: boolean }) {
       const onOpenFile = useCallback(
         (target: InlinePathTarget) => {
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/buttons/model.test.ts b/packages/app/src/plugins/buttons/model.test.ts
index 8c07a8615e..e8f604bb50 100644
--- a/packages/app/src/plugins/buttons/model.test.ts
+++ b/packages/app/src/plugins/buttons/model.test.ts
@@ -17,6 +17,9 @@ 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: [],
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
new file mode 100644
index 0000000000..55cae64e5d
--- /dev/null
+++ b/packages/app/src/plugins/catalog-sync-model.test.ts
@@ -0,0 +1,504 @@
+import appPackage from "../../package.json";
+import { afterEach, expect, it } from "vitest";
+import { QueryObserver } from "@tanstack/react-query";
+import { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { SessionOutboundMessage } from "@getpaseo/protocol/messages";
+import { settingsRpc } from "@getpaseo/plugin";
+import { syncPluginCatalog } from "./catalog-sync-model";
+import { createPluginHosts } from "./hosts";
+import { PluginRegistry } from "./registry";
+import { pluginSettingsKey } from "./settings/query";
+import type { InstalledPlugin } from "./types";
+
+const audio = { play: async () => 0 };
+const rpc = settingsRpc("preferences");
+type Catalog = Awaited<ReturnType<DaemonClient["getPluginCatalog"]>>;
+type Observation = ReturnType<DaemonClient["observeEvents"]>;
+type Observer = Parameters<Observation["subscribe"]>[0];
+
+class SettingsStore {
+  private revision = 1;
+  private values = { label: "original" };
+  reads = 0;
+
+  read() {
+    this.reads++;
+    return { status: "ready", revision: String(this.revision), values: this.values } as const;
+  }
+
+  write(input: unknown) {
+    const write = rpc.write.input.parse(input);
+    if (write.revision !== String(this.revision)) {
+      return { status: "conflict", error: "Settings changed" } as const;
+    }
+    const values = write.values;
+    if (typeof values !== "object" || values === null || !("label" in values)) {
+      throw new Error("Expected settings values");
+    }
+    if (typeof values.label !== "string") throw new Error("Expected label");
+    this.values = { label: values.label };
+    this.revision++;
+    return { status: "saved", revision: String(this.revision), values: this.values } as const;
+  }
+}
+
+/** In-memory daemon port; it delivers owned snapshots and stops updates on release. */
+class CatalogClient extends DaemonClient {
+  catalog = catalog("one");
+  fetches = 0;
+  releases = 0;
+  events: Parameters<DaemonClient["observeEvents"]>[0] = [];
+  private readonly observers = new Set<Observer>();
+
+  constructor(readonly settings = new SettingsStore()) {
+    super({ url: "ws://unused.test", clientId: "catalog-sync-test" });
+  }
+
+  override async getPluginCatalog(): Promise<Catalog> {
+    this.fetches++;
+    return this.catalog;
+  }
+
+  override observeEvents(events: Parameters<DaemonClient["observeEvents"]>[0]): Observation {
+    this.events = events;
+    const snapshot = { requestId: "events", subscriptionId: "catalog" };
+    const subscribers = new Set<Observer>();
+    return {
+      subscriptionId: snapshot.subscriptionId,
+      ready: Promise.resolve(snapshot),
+      subscribe: (observer) => {
+        subscribers.add(observer);
+        this.observers.add(observer);
+        observer.snapshot(snapshot);
+        return () => {
+          subscribers.delete(observer);
+          this.observers.delete(observer);
+        };
+      },
+      release: async () => {
+        this.releases++;
+        for (const observer of subscribers) this.observers.delete(observer);
+        subscribers.clear();
+      },
+    };
+  }
+
+  override async invokePluginRpc(_pluginId: string, method: string, input: unknown) {
+    if (method === rpc.read.name) return this.settings.read();
+    if (method === rpc.write.name) return this.settings.write(input);
+    throw new Error(`Unexpected RPC: ${method}`);
+  }
+
+  update(message: SessionOutboundMessage) {
+    for (const observer of this.observers) observer.update(message);
+  }
+
+  snapshot() {
+    for (const observer of this.observers) {
+      observer.snapshot({ requestId: "reconnect", subscriptionId: "catalog" });
+    }
+  }
+}
+
+function catalog(marker: string): Catalog {
+  return [
+    {
+      id: "reports",
+      requirements: { paseo: `>=${appPackage.version}` },
+      clientBundle: `(function() { return { default: function(plugin) {
+      plugin.addTimelineTransformer({
+        id: "report", query: { itemType: "tool_call" },
+        transform() { return ${JSON.stringify(marker)} ? { items: [] } : undefined; }
+      });
+      return function() { plugin.openSettings("cleanup"); };
+    } }; })`,
+    },
+  ];
+}
+
+const cleanups: Array<() => void> = [];
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0).toReversed()) cleanup();
+});
+
+function harness() {
+  let evaluations = 0;
+  let disposals = 0;
+  const registry = new PluginRegistry({
+    localeSource: { getLocale: () => "en", subscribe: () => () => {} },
+    version: appPackage.version,
+    createRuntime(installation) {
+      evaluations++;
+      return {
+        hosts: createPluginHosts(
+          {
+            getHosts: () => [],
+            getSnapshot: () => null,
+            subscribeAll: () => () => {},
+            subscribeHostList: () => () => {},
+          },
+          installation.lifetime.signal,
+        ),
+        paseo: installation.paseo,
+        i18n: installation.i18n,
+        rpc: async () => {
+          throw new Error("Unexpected runtime RPC");
+        },
+        openSettings: () => {
+          disposals++;
+        },
+        openScreen() {},
+        openSurface() {},
+        async playAudio() {},
+        openPanel() {},
+        addComposerPill: () => ({ update() {}, remove() {} }),
+        addHeaderButton: () => ({ update() {}, remove() {} }),
+        subscribe: () => {
+          throw new Error("Subscriptions are not used here");
+        },
+      };
+    },
+  });
+  const client = new CatalogClient();
+  cleanups.push(() => {
+    registry.removeHost("host");
+    registry.removeHost("other");
+  });
+  function sync(options: Partial<Parameters<typeof syncPluginCatalog>[0]> = {}) {
+    const stop = syncPluginCatalog({
+      serverId: "host",
+      client,
+      audio,
+      connected: true,
+      supported: true,
+      registry,
+      ...options,
+    });
+    cleanups.push(stop);
+    return stop;
+  }
+  function installed(serverId = "host") {
+    const plugin = registry.getSnapshot().find((entry) => entry.serverId === serverId);
+    if (!plugin) throw new Error(`Missing installation: ${serverId}`);
+    return plugin;
+  }
+  return {
+    registry,
+    client,
+    sync,
+    installed,
+    evaluations: () => evaluations,
+    disposals: () => disposals,
+  };
+}
+
+async function connected() {
+  const h = harness();
+  const stop = h.sync();
+  await expect.poll(() => h.registry.getSnapshot().length).toBe(1);
+  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"),
+    queryFn: async () => rpc.read.output.parse(await plugin.invoke(rpc.read.name, {})),
+    // The replica policy used by useSettings deliberately disables automatic refetches.
+    gcTime: Infinity,
+    staleTime: Infinity,
+    refetchOnMount: false,
+    refetchOnReconnect: false,
+    refetchOnWindowFocus: false,
+    retry: false,
+  } as const;
+}
+
+it("retains installations and timeline transforms while disconnected", async () => {
+  const h = await connected();
+  const plugin = h.installed();
+  const snapshot = h.registry.getSnapshot();
+  const transformers = plugin.timelineTransformers;
+  h.stop();
+  h.sync({ connected: false });
+  h.client.update({
+    type: "status",
+    payload: { status: "plugin_catalog_changed", pluginId: "reports" },
+  });
+  expect(h.registry.getSnapshot()).toBe(snapshot);
+  expect(h.installed().timelineTransformers).toBe(transformers);
+  expect(plugin.lifetime.signal.aborted).toBe(false);
+  expect(h.disposals()).toBe(0);
+  expect(h.client.fetches).toBe(1);
+  expect(h.client.events).toEqual([
+    "status.plugin_catalog_changed",
+    "status.plugin_settings_changed",
+  ]);
+});
+
+it.each(["mounted", "unmounted"])(
+  "refreshes %s settings and revisions after another client saves offline",
+  async (surface) => {
+    const h = await connected();
+    const plugin = h.installed();
+    const snapshot = h.registry.getSnapshot();
+    const options = settingsQuery(plugin);
+    const original = await plugin.queryClient.fetchQuery(options);
+    const observer = new QueryObserver(plugin.queryClient, options);
+    const unsubscribe = observer.subscribe(() => {});
+    cleanups.push(unsubscribe);
+    if (surface === "unmounted") unsubscribe();
+    plugin.queryClient.setQueryData(["attachment-search"], "retained");
+    const otherClient = new CatalogClient();
+    h.registry.installCatalog("other", otherClient.catalog, { client: otherClient, audio });
+    const otherPlugin = h.installed("other");
+    await otherPlugin.queryClient.fetchQuery(settingsQuery(otherPlugin));
+    // Another host publishes new presentation snapshots without replacing the owning lifetime.
+    const beforeReconnect = h.registry.getSnapshot();
+    const retainedInstallation = h.installed();
+
+    h.stop();
+    h.sync({ connected: false });
+    const clientB = new CatalogClient(h.client.settings);
+    expect(
+      await clientB.invokePluginRpc("reports", rpc.write.name, {
+        revision: original.revision,
+        values: { label: "client B" },
+      }),
+    ).toEqual({ status: "saved", revision: "2", values: { label: "client B" } });
+    expect(plugin.queryClient.getQueryData(options.queryKey)).toEqual(original);
+    h.sync();
+
+    await expect
+      .poll(() => plugin.queryClient.getQueryData(options.queryKey))
+      .toEqual({
+        status: "ready",
+        revision: "2",
+        values: { label: "client B" },
+      });
+    const refreshed = await plugin.queryClient.fetchQuery(options);
+    expect(
+      await plugin.invoke(rpc.write.name, {
+        revision: refreshed.revision,
+        values: { label: "client A" },
+      }),
+    ).toEqual({ status: "saved", revision: "3", values: { label: "client A" } });
+    expect(h.registry.getSnapshot()).toBe(beforeReconnect);
+    expect(h.installed()).toBe(retainedInstallation);
+    expect(h.installed().lifetime).toBe(plugin.lifetime);
+    expect(h.installed().queryClient).toBe(plugin.queryClient);
+    expect(h.installed().timelineTransformers).toBe(snapshot[0].timelineTransformers);
+    expect(plugin.queryClient.getQueryData(["attachment-search"])).toBe("retained");
+    expect(otherClient.settings.reads).toBe(1);
+    expect(otherPlugin.queryClient.getQueryState(options.queryKey)?.isInvalidated).toBe(false);
+    expect(otherPlugin.queryClient.getQueryData(options.queryKey)).toEqual(original);
+    expect(h.evaluations()).toBe(2);
+    expect(h.disposals()).toBe(0);
+  },
+);
+
+it("replaces changed bundles on reconnect and disposes the old installation", async () => {
+  const h = await connected();
+  const plugin = h.installed();
+  plugin.queryClient.setQueryData(["attachment-search"], "old");
+  h.stop();
+  h.client.catalog = catalog("two");
+  h.sync();
+  await expect.poll(() => h.installed() === plugin).toBe(false);
+  expect(plugin.lifetime.signal.aborted).toBe(true);
+  expect(plugin.queryClient.getQueryCache().getAll()).toEqual([]);
+  expect(h.installed().timelineTransformers.map((entry) => entry.id)).toEqual(["report"]);
+  expect(h.evaluations()).toBe(2);
+  expect(h.disposals()).toBe(1);
+});
+
+it("replaces an explicitly reloaded bundle even when its source is unchanged", async () => {
+  const h = await connected();
+  const plugin = h.installed();
+  h.client.update({
+    type: "status",
+    payload: { status: "plugin_catalog_changed", pluginId: "reports" },
+  });
+  await expect.poll(() => h.installed() === plugin).toBe(false);
+  expect(h.disposals()).toBe(1);
+  expect(h.evaluations()).toBe(2);
+});
+
+it.each(["unsupported", "no audio"])("disposes plugins when %s", async (reason) => {
+  const h = await connected();
+  const plugin = h.installed();
+  h.stop();
+  h.sync({ supported: reason !== "unsupported", audio: reason === "no audio" ? null : audio });
+  expect(h.registry.getSnapshot()).toEqual([]);
+  expect(plugin.lifetime.signal.aborted).toBe(true);
+  expect(h.disposals()).toBe(1);
+});
+
+it("refreshes settings on a replayed subscription snapshot without reinstalling", async () => {
+  const h = await connected();
+  const plugin = h.installed();
+  const options = settingsQuery(plugin);
+  await plugin.queryClient.fetchQuery(options);
+  h.client.settings.write({ revision: "1", values: { label: "replayed" } });
+  h.client.snapshot();
+  await expect
+    .poll(() => plugin.queryClient.getQueryData(options.queryKey))
+    .toEqual({
+      status: "ready",
+      revision: "2",
+      values: { label: "replayed" },
+    });
+  expect(h.installed()).toBe(plugin);
+  expect(h.evaluations()).toBe(1);
+});
+
+it("invalidates only the named settings on its host for a live notification", async () => {
+  const h = await connected();
+  const plugin = h.installed();
+  const options = settingsQuery(plugin);
+  await plugin.queryClient.fetchQuery(options);
+  const observer = new QueryObserver(plugin.queryClient, options);
+  cleanups.push(observer.subscribe(() => {}));
+  plugin.queryClient.setQueryData(pluginSettingsKey("other-settings"), "unchanged");
+  const other = new CatalogClient();
+  h.registry.installCatalog("other", other.catalog, { client: other, audio });
+  await h.installed("other").queryClient.fetchQuery(settingsQuery(h.installed("other")));
+
+  const beforeNotification = h.registry.getSnapshot();
+  const retainedInstallation = h.installed();
+  h.client.settings.write({ revision: "1", values: { label: "live" } });
+  h.client.update({
+    type: "status",
+    payload: {
+      status: "plugin_settings_changed",
+      pluginId: "reports",
+      settingsId: "preferences",
+    },
+  });
+
+  await expect
+    .poll(() => plugin.queryClient.getQueryData(options.queryKey))
+    .toEqual({
+      status: "ready",
+      revision: "2",
+      values: { label: "live" },
+    });
+  expect(plugin.queryClient.getQueryState(pluginSettingsKey("other-settings"))?.isInvalidated).toBe(
+    false,
+  );
+  expect(other.settings.reads).toBe(1);
+  expect(h.registry.getSnapshot()).toBe(beforeNotification);
+  expect(h.installed()).toBe(retainedInstallation);
+  expect(h.installed().lifetime).toBe(plugin.lifetime);
+  expect(h.installed().queryClient).toBe(plugin.queryClient);
+  expect(h.evaluations()).toBe(2);
+  expect(h.client.fetches).toBe(1);
+});
+
+it("ignores an in-flight catalog snapshot after disconnect", async () => {
+  const h = await connected();
+  const plugin = h.installed();
+  await plugin.queryClient.fetchQuery(settingsQuery(plugin));
+  const snapshot = h.registry.getSnapshot();
+  h.stop();
+  let resolveCatalog: (value: Catalog) => void = () => {};
+  const pending = new Promise<Catalog>((resolve) => {
+    resolveCatalog = resolve;
+  });
+  let fetching: () => void = () => {};
+  const started = new Promise<void>((resolve) => {
+    fetching = resolve;
+  });
+  class PendingClient extends CatalogClient {
+    override getPluginCatalog() {
+      fetching();
+      return pending;
+    }
+  }
+  const stop = h.sync({ client: new PendingClient(h.client.settings) });
+  await started;
+  stop();
+  resolveCatalog(catalog("late"));
+  await pending;
+  // Drain the catalog continuation through a subsequently queued task.
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  expect(h.registry.getSnapshot()).toBe(snapshot);
+  expect(h.client.settings.reads).toBe(1);
+  expect(h.evaluations()).toBe(1);
+});
diff --git a/packages/app/src/plugins/catalog-sync-model.ts b/packages/app/src/plugins/catalog-sync-model.ts
new file mode 100644
index 0000000000..3c11aef63b
--- /dev/null
+++ b/packages/app/src/plugins/catalog-sync-model.ts
@@ -0,0 +1,102 @@
+import type { AudioEngine } from "@/audio";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { PluginRegistry } from "./registry";
+import { pluginSettingsKey, pluginSettingsPrefix } from "./settings/query";
+
+interface CatalogSyncInput {
+  serverId: string;
+  client: DaemonClient;
+  audio: Pick<AudioEngine, "play"> | null;
+  connected: boolean;
+  supported: boolean;
+  registry: Pick<
+    PluginRegistry,
+    "installCatalog" | "getSnapshot" | "removeHost" | "setCatalogStatus"
+  >;
+}
+
+export function syncPluginCatalog({
+  serverId,
+  client,
+  audio,
+  connected,
+  supported,
+  registry,
+}: 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(() => {
+      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([
+    "status.plugin_catalog_changed",
+    "status.plugin_settings_changed",
+  ]);
+  observation.subscribe({
+    snapshot: () => {
+      void refresh().then(() => {
+        if (cancelled) return undefined;
+        // Retained replicas miss offline writes and do not refetch when a screen mounts.
+        for (const plugin of registry.getSnapshot()) {
+          if (plugin.serverId !== serverId) continue;
+          void plugin.queryClient.invalidateQueries({
+            queryKey: pluginSettingsPrefix,
+            refetchType: "all",
+          });
+        }
+        return undefined;
+      });
+    },
+    update: (message) => {
+      if (message.type !== "status") return;
+      if (message.payload.status === "plugin_settings_changed") {
+        const { pluginId, settingsId } = message.payload;
+        if (typeof settingsId === "string") {
+          const plugin = registry
+            .getSnapshot()
+            .find((item) => item.serverId === serverId && item.id === pluginId);
+          void plugin?.queryClient.invalidateQueries({ queryKey: pluginSettingsKey(settingsId) });
+        }
+      }
+      if (message.payload.status === "plugin_catalog_changed") {
+        const pluginId = message.payload.pluginId;
+        if (typeof pluginId === "string") void refresh(pluginId);
+      }
+    },
+  });
+  return () => {
+    cancelled = true;
+    void observation
+      .release()
+      .catch((error) => console.warn("[Plugins] Failed to release catalog", error));
+  };
+}
diff --git a/packages/app/src/plugins/catalog-sync.tsx b/packages/app/src/plugins/catalog-sync.tsx
index 0eedfde3ab..6dc11b72b8 100644
--- a/packages/app/src/plugins/catalog-sync.tsx
+++ b/packages/app/src/plugins/catalog-sync.tsx
@@ -1,10 +1,10 @@
 import { useVoiceAudioEngineOptional } from "@/contexts/voice-context";
-import { pluginSettingsKey } from "./settings/use-settings";
 import { useEffect } from "react";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import { useHostFeature } from "@/runtime/host-features";
 import { useHostRuntimeIsConnected } from "@/runtime/host-runtime";
 import { pluginRegistry } from "./registry";
+import { syncPluginCatalog } from "./catalog-sync-model";
 
 export function PluginCatalogSync({
   serverId,
@@ -17,72 +17,18 @@ export function PluginCatalogSync({
   const connected = useHostRuntimeIsConnected(serverId);
   const supported = useHostFeature(serverId, "plugins");
 
-  useEffect(() => {
-    let cancelled = false;
-    let refreshQueue = Promise.resolve();
-    if (!supported || !audio) {
-      pluginRegistry.removeHost(serverId);
-      return;
-    }
-    if (!connected) {
-      pluginRegistry.removeHost(serverId);
-      return;
-    }
-    const refresh = (replacePluginId?: string) => {
-      refreshQueue = refreshQueue.then(() =>
-        client
-          .getPluginCatalog()
-          .then((catalog) => {
-            if (!cancelled) {
-              pluginRegistry.installCatalog(serverId, catalog, {
-                replacePluginId,
-                client,
-                audio,
-              });
-            }
-            return undefined;
-          })
-          .catch((error) => {
-            if (!cancelled) {
-              console.warn(`[Plugins] Failed to load catalog for ${serverId}`, error);
-            }
-            return undefined;
-          }),
-      );
-      return refreshQueue;
-    };
-    const observation = client.observeEvents([
-      "status.plugin_catalog_changed",
-      "status.plugin_settings_changed",
-    ]);
-    observation.subscribe({
-      snapshot: () => {
-        void refresh();
-      },
-      update: (message) => {
-        if (message.type !== "status") return;
-        if (message.payload.status === "plugin_settings_changed") {
-          const { pluginId, settingsId } = message.payload;
-          if (typeof settingsId === "string") {
-            const plugin = pluginRegistry
-              .getSnapshot()
-              .find((item) => item.serverId === serverId && item.id === pluginId);
-            void plugin?.queryClient.invalidateQueries({ queryKey: pluginSettingsKey(settingsId) });
-          }
-        }
-        if (message.payload.status === "plugin_catalog_changed") {
-          const pluginId = message.payload.pluginId;
-          if (typeof pluginId === "string") void refresh(pluginId);
-        }
-      },
-    });
-    return () => {
-      cancelled = true;
-      void observation
-        .release()
-        .catch((error) => console.warn("[Plugins] Failed to release catalog", error));
-    };
-  }, [audio, client, connected, serverId, supported]);
+  useEffect(
+    () =>
+      syncPluginCatalog({
+        serverId,
+        client,
+        audio,
+        connected,
+        supported,
+        registry: pluginRegistry,
+      }),
+    [audio, client, connected, serverId, supported],
+  );
 
   useEffect(() => () => pluginRegistry.removeHost(serverId), [serverId]);
   return null;
diff --git a/packages/app/src/plugins/client-bundles/index.ts b/packages/app/src/plugins/client-bundles/index.ts
new file mode 100644
index 0000000000..06580dd222
--- /dev/null
+++ b/packages/app/src/plugins/client-bundles/index.ts
@@ -0,0 +1,32 @@
+import * as FileSystem from "expo-file-system/legacy";
+import { CryptoDigestAlgorithm, digestStringAsync, randomUUID } from "expo-crypto";
+import { createPluginClientBundleStore } from "./store";
+
+export function createHostPluginClientBundleStore(serverId: string) {
+  const directory = `${FileSystem.cacheDirectory}plugin-client-bundles/${encodeURIComponent(serverId)}/`;
+  const ensureDirectory = async () => {
+    if (!FileSystem.cacheDirectory) throw new Error("Plugin bundle cache directory unavailable");
+    await FileSystem.makeDirectoryAsync(directory, { intermediates: true });
+  };
+  return createPluginClientBundleStore(
+    {
+      async list() {
+        await ensureDirectory();
+        return FileSystem.readDirectoryAsync(directory);
+      },
+      read: (name) => FileSystem.readAsStringAsync(`${directory}${name}`),
+      async writeAtomic(name, contents) {
+        await ensureDirectory();
+        const temporary = `${directory}${randomUUID()}.tmp`;
+        try {
+          await FileSystem.writeAsStringAsync(temporary, contents);
+          await FileSystem.moveAsync({ from: temporary, to: `${directory}${name}` });
+        } finally {
+          await FileSystem.deleteAsync(temporary, { idempotent: true });
+        }
+      },
+      remove: (name) => FileSystem.deleteAsync(`${directory}${name}`, { idempotent: true }),
+    },
+    (contents) => digestStringAsync(CryptoDigestAlgorithm.SHA256, contents),
+  );
+}
diff --git a/packages/app/src/plugins/client-bundles/index.web.ts b/packages/app/src/plugins/client-bundles/index.web.ts
new file mode 100644
index 0000000000..6e67778089
--- /dev/null
+++ b/packages/app/src/plugins/client-bundles/index.web.ts
@@ -0,0 +1,62 @@
+import { createPluginClientBundleStore } from "./store";
+
+const DATABASE_NAME = "paseo-plugin-client-bundles";
+const STORE_NAME = "bundles";
+let opening: Promise<IDBDatabase> | undefined;
+
+function openDatabase(): Promise<IDBDatabase> {
+  opening ??= new Promise<IDBDatabase>((resolve, reject) => {
+    const request = indexedDB.open(DATABASE_NAME, 1);
+    request.addEventListener("upgradeneeded", () => request.result.createObjectStore(STORE_NAME));
+    request.addEventListener("success", () => resolve(request.result));
+    request.addEventListener("error", () => reject(request.error));
+  }).catch((error) => {
+    opening = undefined;
+    throw error;
+  });
+  return opening;
+}
+
+export function createHostPluginClientBundleStore(serverId: string) {
+  const prefix = `${encodeURIComponent(serverId)}/`;
+  const range = () => IDBKeyRange.bound(prefix, `${prefix}\uffff`);
+  async function run<T>(
+    mode: IDBTransactionMode,
+    operation: (store: IDBObjectStore) => IDBRequest<T>,
+  ): Promise<T> {
+    const database = await openDatabase();
+    return new Promise((resolve, reject) => {
+      const transaction = database.transaction(STORE_NAME, mode);
+      const request = operation(transaction.objectStore(STORE_NAME));
+      transaction.addEventListener("complete", () => resolve(request.result));
+      transaction.addEventListener("abort", () => reject(transaction.error));
+      transaction.addEventListener("error", () => reject(transaction.error));
+    });
+  }
+  return createPluginClientBundleStore(
+    {
+      async list() {
+        return (await run("readonly", (store) => store.getAllKeys(range())))
+          .filter((key): key is string => typeof key === "string")
+          .map((key) => key.slice(prefix.length));
+      },
+      async read(name) {
+        const result: unknown = await run("readonly", (store) => store.get(`${prefix}${name}`));
+        if (typeof result !== "string") throw new Error("Missing plugin client bundle");
+        return result;
+      },
+      async writeAtomic(name, contents) {
+        await run("readwrite", (store) => store.put(contents, `${prefix}${name}`));
+      },
+      async remove(name) {
+        await run("readwrite", (store) => store.delete(`${prefix}${name}`));
+      },
+    },
+    async (contents) => {
+      const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(contents));
+      return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join(
+        "",
+      );
+    },
+  );
+}
diff --git a/packages/app/src/plugins/client-bundles/storage.browser.test.ts b/packages/app/src/plugins/client-bundles/storage.browser.test.ts
new file mode 100644
index 0000000000..9acd7e0c52
--- /dev/null
+++ b/packages/app/src/plugins/client-bundles/storage.browser.test.ts
@@ -0,0 +1,36 @@
+import { expect, test } from "vitest";
+import { createHostPluginClientBundleStore } from "./index.web";
+
+async function sha256(contents: string) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(contents));
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+test("browser bundles survive a fresh store and remain isolated by host", async () => {
+  const first = createHostPluginClientBundleStore("bundle-test-host-a");
+  const second = createHostPluginClientBundleStore("bundle-test-host-b");
+  const clientBundle = "bundle".repeat(250_000);
+  const entry = {
+    id: "same-plugin",
+    clientBundle,
+    clientBundleHash: await sha256(clientBundle),
+  };
+  const otherCode = "other host code";
+  const other = {
+    id: entry.id,
+    clientBundle: otherCode,
+    clientBundleHash: await sha256(otherCode),
+  };
+  try {
+    await first.replace([entry]);
+    await second.replace([other]);
+    expect(await createHostPluginClientBundleStore("bundle-test-host-a").load()).toEqual([entry]);
+    expect(await createHostPluginClientBundleStore("bundle-test-host-b").load()).toEqual([other]);
+    await first.replace([]);
+    expect(await createHostPluginClientBundleStore("bundle-test-host-a").load()).toEqual([]);
+    expect(await second.load()).toEqual([other]);
+  } finally {
+    await first.replace([]);
+    await second.replace([]);
+  }
+});
diff --git a/packages/app/src/plugins/client-bundles/store.test.ts b/packages/app/src/plugins/client-bundles/store.test.ts
new file mode 100644
index 0000000000..c3332c6b0e
--- /dev/null
+++ b/packages/app/src/plugins/client-bundles/store.test.ts
@@ -0,0 +1,179 @@
+import { createHash } from "node:crypto";
+import { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { expect, test } from "vitest";
+import { createPluginClientBundleStore, type PluginBundleFiles } from "./store";
+
+const sha256 = async (contents: string) => createHash("sha256").update(contents).digest("hex");
+
+class BundleFiles implements PluginBundleFiles {
+  readonly contents = new Map<string, string>();
+  readonly writes: string[] = [];
+  async list() {
+    return [...this.contents.keys()];
+  }
+  async read(name: string) {
+    const contents = this.contents.get(name);
+    if (contents === undefined) throw new Error("File disappeared");
+    return contents;
+  }
+  async writeAtomic(name: string, contents: string) {
+    this.writes.push(name);
+    this.contents.set(name, contents);
+  }
+  async remove(name: string) {
+    this.contents.delete(name);
+  }
+}
+
+async function bundle(id: string, clientBundle: string) {
+  return { id, clientBundle, clientBundleHash: await sha256(clientBundle) };
+}
+
+test("a cold store loads verified bundles and prunes versions missing from the latest catalog", async () => {
+  const files = new BundleFiles();
+  const old = await bundle("changed", "old");
+  const kept = await bundle("kept", "Unicode: 折叠屏 🐚");
+  await createPluginClientBundleStore(files, sha256).replace([old, kept]);
+  const cold = createPluginClientBundleStore(files, sha256);
+  expect(await cold.load()).toEqual([old, kept]);
+  const changed = await bundle("changed", "new");
+  await cold.replace([kept, changed]);
+  expect(files.contents.size).toBe(2);
+  expect(await createPluginClientBundleStore(files, sha256).load()).toEqual([kept, changed]);
+  expect(files.writes).toHaveLength(3);
+  await cold.replace([]);
+  expect(files.contents.size).toBe(0);
+});
+
+test("same-length corruption, truncated files and unreadable files are not advertised", async () => {
+  const files = new BundleFiles();
+  const entries = await Promise.all([
+    bundle("same-length", "good"),
+    bundle("truncated", "long"),
+    bundle("missing", "lost"),
+  ]);
+  await createPluginClientBundleStore(files, sha256).replace(entries);
+  const names = [...files.contents.keys()];
+  files.contents.set(names[0]!, "evil");
+  files.contents.set(names[1]!, "lo");
+  // The directory entry still exists while reading the file fails.
+  const unreadable: PluginBundleFiles = {
+    list: () => files.list(),
+    read: (name) =>
+      name === names[2] ? Promise.reject(new Error("Unreadable")) : files.read(name),
+    writeAtomic: (name, contents) => files.writeAtomic(name, contents),
+    remove: (name) => files.remove(name),
+  };
+  const cold = createPluginClientBundleStore(unreadable, sha256);
+  expect(await cold.load()).toEqual([]);
+  await cold.replace(entries);
+  expect(await createPluginClientBundleStore(files, sha256).load()).toEqual(entries);
+});
+
+test("an interrupted atomic write leaves the prior catalog available for a cold reader", async () => {
+  const files = new BundleFiles();
+  const previous = await bundle("plugin", "previous");
+  await createPluginClientBundleStore(files, sha256).replace([previous]);
+  const failing: PluginBundleFiles = {
+    list: () => files.list(),
+    read: (name) => files.read(name),
+    remove: (name) => files.remove(name),
+    writeAtomic: async () => {
+      throw new Error("Disk full");
+    },
+  };
+  await expect(
+    createPluginClientBundleStore(failing, sha256).replace([await bundle("plugin", "next")]),
+  ).rejects.toThrow("Disk full");
+  expect(await createPluginClientBundleStore(files, sha256).load()).toEqual([previous]);
+});
+
+// Exercise the app store through a fresh platform-agnostic client, using its transport port.
+test.each(["valid", "corrupt", "missing"])(
+  "cold catalog uses a %s persisted bundle correctly",
+  async (state) => {
+    const files = new BundleFiles();
+    const entry = await bundle("plugin", "good code");
+    await createPluginClientBundleStore(files, sha256).replace([entry]);
+    if (state === "corrupt") files.contents.set([...files.contents.keys()][0]!, "evil code");
+    if (state === "missing") files.contents.clear();
+    let open = () => {};
+    let receive: (data: unknown, binary: boolean) => void = () => {};
+    const requests: Record<string, unknown>[] = [];
+    const client = new DaemonClient({
+      url: "ws://test",
+      clientId: "plugin-cache-test",
+      reconnect: { enabled: false },
+      createPluginClientBundleStore: () => createPluginClientBundleStore(files, sha256),
+      transportFactory: () => ({
+        send(data) {
+          if (typeof data !== "string") return;
+          const frame = JSON.parse(data);
+          if (frame.type !== "session") return;
+          const request = frame.message;
+          if (request.type !== "plugin.catalog.get.request") return;
+          requests.push(request);
+          const { clientBundle: _code, ...reference } = entry;
+          receive(
+            JSON.stringify({
+              type: "session",
+              message: {
+                type: "plugin.catalog.get.response",
+                payload: {
+                  requestId: request.requestId,
+                  plugins: [request.cachedClientBundles ? reference : entry],
+                },
+              },
+            }),
+            false,
+          );
+        },
+        close() {},
+        onOpen(handler) {
+          open = handler;
+          return () => {};
+        },
+        onMessage(handler) {
+          receive = handler;
+          return () => {};
+        },
+        onClose() {
+          return () => {};
+        },
+        onError() {
+          return () => {};
+        },
+      }),
+    });
+    try {
+      const connecting = client.connect();
+      open();
+      receive(
+        JSON.stringify({
+          type: "session",
+          message: {
+            type: "status",
+            payload: {
+              status: "server_info",
+              serverId: "cache-host",
+              hostname: null,
+              version: null,
+              features: { plugins: true },
+            },
+          },
+        }),
+        false,
+      );
+      await connecting;
+      expect(await client.getPluginCatalog()).toEqual([entry]);
+      if (state === "valid")
+        expect(requests[0]?.cachedClientBundles).toEqual([
+          { id: entry.id, clientBundleHash: entry.clientBundleHash },
+        ]);
+      else expect(requests[0]).not.toHaveProperty("cachedClientBundles");
+      await expect.poll(() => createPluginClientBundleStore(files, sha256).load()).toEqual([entry]);
+    } finally {
+      await client.close();
+    }
+  },
+);
diff --git a/packages/app/src/plugins/client-bundles/store.ts b/packages/app/src/plugins/client-bundles/store.ts
new file mode 100644
index 0000000000..4a120c2c2a
--- /dev/null
+++ b/packages/app/src/plugins/client-bundles/store.ts
@@ -0,0 +1,56 @@
+import type {
+  PluginClientBundle,
+  PluginClientBundleStore,
+} from "@getpaseo/client/internal/daemon-client";
+
+/** Each adapter is scoped to one host. Writes publish a complete file/record atomically. */
+export interface PluginBundleFiles {
+  list(): Promise<string[]>;
+  read(name: string): Promise<string>;
+  writeAtomic(name: string, contents: string): Promise<void>;
+  remove(name: string): Promise<void>;
+}
+
+export function createPluginClientBundleStore(
+  files: PluginBundleFiles,
+  sha256: (contents: string) => Promise<string>,
+): PluginClientBundleStore {
+  const verified = new Set<string>();
+  const filename = (bundle: PluginClientBundle) =>
+    `${encodeURIComponent(bundle.id)}.${bundle.clientBundleHash}.js`;
+  return {
+    async load() {
+      const bundles: PluginClientBundle[] = [];
+      for (const name of await files.list()) {
+        try {
+          const match = /^(.*)\.([a-f0-9]{64})\.js$/.exec(name);
+          if (!match) continue;
+          const id = decodeURIComponent(match[1]!);
+          const clientBundleHash = match[2]!;
+          const clientBundle = await files.read(name);
+          if ((await sha256(clientBundle)) !== clientBundleHash) continue;
+          verified.add(name);
+          bundles.push({ id, clientBundleHash, clientBundle });
+        } catch {
+          // Missing, unreadable or corrupt files are cache misses, never executable code.
+        }
+      }
+      return bundles;
+    },
+    async replace(bundles) {
+      const retained = new Set<string>();
+      for (const bundle of bundles) {
+        const name = filename(bundle);
+        retained.add(name);
+        if (verified.has(name)) continue;
+        await files.writeAtomic(name, bundle.clientBundle);
+        verified.add(name);
+      }
+      for (const name of await files.list()) {
+        if (retained.has(name)) continue;
+        await files.remove(name);
+        verified.delete(name);
+      }
+    },
+  };
+}
diff --git a/packages/app/src/plugins/client-runtime.ts b/packages/app/src/plugins/client-runtime.ts
index 61e921bd0f..d9439ff8ad 100644
--- a/packages/app/src/plugins/client-runtime.ts
+++ b/packages/app/src/plugins/client-runtime.ts
@@ -2,6 +2,7 @@ import { createPlayAudio, type AudioEngine } from "@/audio";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
 import { createPluginHosts } from "./hosts";
 import type { PluginClientOpenPanelOptions } from "@getpaseo/plugin/client";
+import { subscribePluginRpc } from "@getpaseo/plugin/client/host";
 import {
   createPluginAgentActionContext,
   createPluginCapabilities,
@@ -36,6 +37,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/command-center/contributions.test.ts b/packages/app/src/plugins/command-center/contributions.test.ts
index e70304b883..e8aea62ede 100644
--- a/packages/app/src/plugins/command-center/contributions.test.ts
+++ b/packages/app/src/plugins/command-center/contributions.test.ts
@@ -71,6 +71,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 };
diff --git a/packages/app/src/plugins/evaluate.ts b/packages/app/src/plugins/evaluate.ts
index ea37209f57..56e296efd6 100644
--- a/packages/app/src/plugins/evaluate.ts
+++ b/packages/app/src/plugins/evaluate.ts
@@ -111,6 +111,7 @@ export type PluginClientRuntime = Pick<
   | "openScreen"
   | "openSurface"
   | "openPanel"
+  | "subscribe"
   | "addComposerPill"
   | "addHeaderButton"
 > & { hosts: ReturnType<typeof createPluginHosts> };
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..b15a68d5e0 100644
--- a/packages/app/src/plugins/installation-provider.test.tsx
+++ b/packages/app/src/plugins/installation-provider.test.tsx
@@ -29,6 +29,9 @@ function installation(invoked: string[]): InstalledPlugin {
       invoked.push(method);
       return { state: "green" };
     },
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     queryClient: new QueryClient(),
     cleanup: () => undefined,
     settingsScreens: [],
diff --git a/packages/app/src/plugins/installation-provider.tsx b/packages/app/src/plugins/installation-provider.tsx
index 552f8080b8..ba3b159f99 100644
--- a/packages/app/src/plugins/installation-provider.tsx
+++ b/packages/app/src/plugins/installation-provider.tsx
@@ -18,7 +18,7 @@ export function PluginInstallationProvider({
   return (
     <QueryClientProvider client={plugin.queryClient}>
       <PaseoApiProvider paseo={plugin.paseo}>
-        <PluginRpcProvider invoke={plugin.invoke}>
+        <PluginRpcProvider invoke={plugin.invoke} subscribe={plugin.subscribe}>
           <PluginTranslationProvider runtime={plugin.i18n}>{children}</PluginTranslationProvider>
         </PluginRpcProvider>
       </PaseoApiProvider>
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/registry-lifecycle.test.ts b/packages/app/src/plugins/registry-lifecycle.test.ts
index 18330dc949..a1a766e5c8 100644
--- a/packages/app/src/plugins/registry-lifecycle.test.ts
+++ b/packages/app/src/plugins/registry-lifecycle.test.ts
@@ -62,6 +62,9 @@ function registry(
         openPanel: () => {},
         addComposerPill: () => ({ update() {}, remove() {} }),
         addHeaderButton: () => ({ update() {}, remove() {} }),
+        subscribe: () => {
+          throw new Error("Subscriptions are not used here");
+        },
       };
     },
   });
@@ -219,7 +222,10 @@ test("locale snapshots preserve installation state and observations, then releas
   expect(after.paseo).toBe(before.paseo);
   expect(after.surfaces[0].Component).toBe(before.surfaces[0].Component);
   expect(h.open).toEqual(new Set(["notes"]));
+  const translatedSnapshot = h.plugins.getSnapshot();
   h.plugins.installCatalog("host", [translated], { client: h.client, audio });
+  expect(h.plugins.getSnapshot()).toBe(translatedSnapshot);
+  expect(h.plugins.getSnapshot()[0].locale).toBe("zh-CN");
   expect(h.plugins.getSnapshot()[0].i18n).toBe(before.i18n);
   h.plugins.removeHost("host");
   expect(listeners.size).toBe(0);
diff --git a/packages/app/src/plugins/registry-requirements.test.ts b/packages/app/src/plugins/registry-requirements.test.ts
index dedefe0b0d..8628c0ebfb 100644
--- a/packages/app/src/plugins/registry-requirements.test.ts
+++ b/packages/app/src/plugins/registry-requirements.test.ts
@@ -39,6 +39,9 @@ function registry(version: string) {
         openPanel() {},
         addComposerPill: () => ({ update() {}, remove() {} }),
         addHeaderButton: () => ({ update() {}, remove() {} }),
+        subscribe: () => {
+          throw new Error("Subscriptions are not used here");
+        },
       };
     },
   });
diff --git a/packages/app/src/plugins/registry.test.ts b/packages/app/src/plugins/registry.test.ts
index 9e8d246a95..4d3877161f 100644
--- a/packages/app/src/plugins/registry.test.ts
+++ b/packages/app/src/plugins/registry.test.ts
@@ -27,12 +27,12 @@ const pluginRegistry = {
   installCatalog(
     serverId: string,
     catalog: Parameters<typeof registry.installCatalog>[1],
-    options: { replacePluginId?: string } = {},
+    options: { replacePluginId?: string; client?: DaemonClient } = {},
   ) {
     return registry.installCatalog(
       serverId,
       catalog.map((entry) => ({ ...entry, requirements: { paseo: `>=${appPackage.version}` } })),
-      { ...options, client: daemonClient, audio },
+      { client: daemonClient, ...options, audio },
     );
   },
 };
@@ -118,6 +118,37 @@ describe("PluginRegistry", () => {
     expect(second?.queryClient.getQueryData(["counter"])).toBe(3);
   });
 
+  it("keeps the snapshot when the same catalog is installed again", () => {
+    const clientBundle = timelineBundle("one");
+    pluginRegistry.installCatalog("host-a", [{ id: "reports", clientBundle }]);
+    const snapshot = pluginRegistry.getSnapshot();
+    const transformers = snapshot[0]?.timelineTransformers;
+    const listener = vi.fn();
+    const unsubscribe = pluginRegistry.subscribe(listener);
+
+    pluginRegistry.installCatalog("host-a", [{ id: "reports", clientBundle }]);
+    unsubscribe();
+
+    expect(pluginRegistry.getSnapshot()).toBe(snapshot);
+    expect(pluginRegistry.getSnapshot()[0]?.timelineTransformers).toBe(transformers);
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it("reinstalls an unchanged bundle for a new host client", () => {
+    const clientBundle = bundle("one");
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle }]);
+    const first = pluginRegistry.getSnapshot()[0];
+
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle }], {
+      client: {} as DaemonClient,
+    });
+
+    const second = pluginRegistry.getSnapshot()[0];
+    expect(second).not.toBe(first);
+    expect(first?.lifetime.signal.aborted).toBe(true);
+    expect(Reflect.get(globalThis, "__pluginCleanups")).toBe(1);
+  });
+
   it("replaces the query cache when the plugin bundle changes", () => {
     pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle: bundle("one") }]);
     const first = pluginRegistry.getSnapshot()[0];
diff --git a/packages/app/src/plugins/registry.ts b/packages/app/src/plugins/registry.ts
index adbdabc93c..fe21dc785f 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,9 @@ 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>();
 
   constructor(
     private readonly dependencies: {
@@ -39,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[],
@@ -49,10 +64,15 @@ export class PluginRegistry {
     },
   ): boolean {
     const previous = this.byHost.get(serverId) ?? [];
+    const previousErrors = this.hostEvaluationErrors(serverId);
+    // Installations call the client they were created with, so a new client replaces them all.
+    const sameClient = this.clientByHost.get(serverId) === options.client;
+    this.clientByHost.set(serverId, options.client);
     const previousTimelineBundles = previous
       .filter((plugin) => plugin.timelineTransformers.length > 0)
       .map((plugin) => `${plugin.id}\0${plugin.clientBundle}`);
     const preserved = catalog.flatMap((entry) => {
+      if (!sameClient) return [];
       const existing = previous.find(
         (plugin) =>
           plugin.id !== options.replacePluginId &&
@@ -82,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,
@@ -146,13 +172,13 @@ export class PluginRegistry {
       }
     }
     this.byHost.set(serverId, installed);
-    if (
-      installed.length !== catalog.length ||
-      installed.length !== previous.length ||
-      installed.some((plugin, index) => plugin !== previous[index])
-    ) {
-      this.publish();
-    }
+    // An unchanged catalog keeps the snapshot, so timeline projections cached against the
+    // installed transformers stay valid across a reconnect.
+    const unchanged =
+      installed.length === previous.length &&
+      installed.every((plugin, index) => plugin === previous[index]) &&
+      this.hostEvaluationErrors(serverId) === previousErrors;
+    if (!unchanged) this.publish();
     const installedTimelineBundles = installed
       .filter((plugin) => plugin.timelineTransformers.length > 0)
       .map((plugin) => `${plugin.id}\0${plugin.clientBundle}`);
@@ -163,16 +189,30 @@ 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);
     }
     this.byHost.delete(serverId);
+    this.clientByHost.delete(serverId);
     this.publish();
   }
 
+  private hostEvaluationErrors(serverId: string): string {
+    const prefix = `${serverId}/`;
+    return JSON.stringify(
+      [...this.evaluationErrors].filter(([key]) => key.startsWith(prefix)).sort(),
+    );
+  }
+
   private dispose(plugin: InstalledPlugin): void {
     if (this.disposed.has(plugin)) return;
     this.disposed.add(plugin);
@@ -231,6 +271,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/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/query.ts b/packages/app/src/plugins/settings/query.ts
new file mode 100644
index 0000000000..db06d58320
--- /dev/null
+++ b/packages/app/src/plugins/settings/query.ts
@@ -0,0 +1,2 @@
+export const pluginSettingsPrefix = ["plugin-settings"] as const;
+export const pluginSettingsKey = (id: string) => [...pluginSettingsPrefix, id] as const;
diff --git a/packages/app/src/plugins/settings/use-settings.ts b/packages/app/src/plugins/settings/use-settings.ts
index 0cefc1878f..decf4bfe05 100644
--- a/packages/app/src/plugins/settings/use-settings.ts
+++ b/packages/app/src/plugins/settings/use-settings.ts
@@ -6,8 +6,8 @@ import { type SettingsDefinition } from "@getpaseo/plugin";
 import { settingsRpc } from "@getpaseo/plugin";
 import { useReplicaQuery } from "@/data/query";
 import { z, type ZodType } from "zod";
+import { pluginSettingsKey } from "./query";
 
-export const pluginSettingsKey = (id: string) => ["plugin-settings", id] as const;
 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);
diff --git a/packages/app/src/plugins/sidebar-groups.test.ts b/packages/app/src/plugins/sidebar-groups.test.ts
index e204c28d9d..bc9517d4b4 100644
--- a/packages/app/src/plugins/sidebar-groups.test.ts
+++ b/packages/app/src/plugins/sidebar-groups.test.ts
@@ -26,6 +26,9 @@ 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 }],
     sidebarItems: {
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..4973b34f5b 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,6 +43,9 @@ 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 })),
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..c75d6b5b01 100644
--- a/packages/app/src/plugins/theme.test.ts
+++ b/packages/app/src/plugins/theme.test.ts
@@ -56,6 +56,9 @@ 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: [],
     sidebarItems: { header: [], footer: [] },
diff --git a/packages/app/src/plugins/timeline/model.test.ts b/packages/app/src/plugins/timeline/model.test.ts
index ffd33ef0ff..2a07c1cf47 100644
--- a/packages/app/src/plugins/timeline/model.test.ts
+++ b/packages/app/src/plugins/timeline/model.test.ts
@@ -18,6 +18,9 @@ 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: [],
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..f7bea7e192 100644
--- a/packages/app/src/plugins/timeline/projection.ts
+++ b/packages/app/src/plugins/timeline/projection.ts
@@ -22,13 +22,14 @@ function cloneAndFreeze<T>(value: T): T {
 }
 
 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":
@@ -105,6 +106,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/types.ts b/packages/app/src/plugins/types.ts
index 9c2a88a210..29c0470e5d 100644
--- a/packages/app/src/plugins/types.ts
+++ b/packages/app/src/plugins/types.ts
@@ -71,6 +71,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;
diff --git a/packages/app/src/plugins/workspace-panels/resolution.test.ts b/packages/app/src/plugins/workspace-panels/resolution.test.ts
index 1208106721..15282266b7 100644
--- a/packages/app/src/plugins/workspace-panels/resolution.test.ts
+++ b/packages/app/src/plugins/workspace-panels/resolution.test.ts
@@ -15,6 +15,9 @@ 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: [],
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/provider-selection.ts b/packages/app/src/provider-selection/provider-selection.ts
index e0313c6623..54d75f1da2 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";
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 648c66c590..03fc0632a9 100644
--- a/packages/app/src/runtime/directory-sync/agent-replica.test.ts
+++ b/packages/app/src/runtime/directory-sync/agent-replica.test.ts
@@ -390,4 +390,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..1ffb4fae5f 100644
--- a/packages/app/src/runtime/directory-sync/index.ts
+++ b/packages/app/src/runtime/directory-sync/index.ts
@@ -160,6 +160,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 +263,7 @@ export class DirectorySync {
   }
 
   private releaseSubscriptions(): void {
+    this.subscriptionGeneration += 1;
     for (const subscription of [
       this.agentSubscription,
       this.workspaceSubscription,
@@ -362,6 +364,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 +381,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);
         }
       });
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..6be4b5e9a5 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 });
       }
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-runtime.test.ts b/packages/app/src/runtime/host-runtime.test.ts
index 33e4f1a316..ca8e417fc3 100644
--- a/packages/app/src/runtime/host-runtime.test.ts
+++ b/packages/app/src/runtime/host-runtime.test.ts
@@ -1189,6 +1189,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",
diff --git a/packages/app/src/runtime/host-runtime.ts b/packages/app/src/runtime/host-runtime.ts
index bb953220cb..b6d10dc8c7 100644
--- a/packages/app/src/runtime/host-runtime.ts
+++ b/packages/app/src/runtime/host-runtime.ts
@@ -1,3 +1,4 @@
+import { createHostPluginClientBundleStore } from "@/plugins/client-bundles";
 import { watchdog } from "@/watchdog";
 import { createHostChannelTransport } from "@getpaseo/client/internal/hosts";
 import type { OwnedSubscription } from "@getpaseo/client";
@@ -589,6 +590,7 @@ function createDefaultDeps(
         capabilities: appCapabilities,
         trace: createPerformanceTrace({ host: host.serverId, connection: connection.id }),
         providerSnapshots: "wire",
+        createPluginClientBundleStore: createHostPluginClientBundleStore,
         ...(host.password ? { password: host.password } : {}),
         localCredential: () => readDesktopManagedLocalCredential(connection),
       } satisfies Omit<DaemonClientConfig, "url">;
@@ -668,6 +670,7 @@ function createDefaultDeps(
           ),
           reconnect: { enabled: false },
           appVersion: resolveAppVersion() ?? undefined,
+          createPluginClientBundleStore: createHostPluginClientBundleStore,
         });
         try {
           await client.connect();
@@ -684,6 +687,7 @@ function createDefaultDeps(
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         capabilities: appCapabilities,
         trace: createPerformanceTrace({ host: host.serverId, connection: connection.id }),
+        createPluginClientBundleStore: createHostPluginClientBundleStore,
       });
     },
     getClientId: () => getOrCreateClientId(),
@@ -1017,6 +1021,9 @@ export class HostRuntimeController {
       }
 
       const currentActiveConnectionId = this.snapshot.activeConnectionId;
+      if (currentActiveConnectionId) {
+        this.reconcileActiveProbeWithClient(currentActiveConnectionId, probeByConnectionId);
+      }
       const activeProbe = currentActiveConnectionId
         ? probeByConnectionId.get(currentActiveConnectionId)
         : null;
@@ -1207,6 +1214,27 @@ export class HostRuntimeController {
     });
   }
 
+  // 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,
@@ -2824,6 +2852,8 @@ export class HostRuntimeStore {
       replica,
       replaceDemandedAgentIds: (agentIds) => directory.setAgentRouteDemand(agentIds),
       drainQueuedAgentMessage: (agentId) => this.drainQueuedAgentMessage(serverId, agentId),
+      applyTurnLiveness: (agentId, transitions) =>
+        directory.applyAgentTurnLiveness(agentId, transitions),
       ports,
     });
   }
diff --git a/packages/app/src/runtime/replica-cache/index.test.ts b/packages/app/src/runtime/replica-cache/index.test.ts
index eaad715a52..5c90ffa5e1 100644
--- a/packages/app/src/runtime/replica-cache/index.test.ts
+++ b/packages/app/src/runtime/replica-cache/index.test.ts
@@ -306,6 +306,41 @@ async function expectLegacyWorkspaceRefresh({
 }
 
 describe("ReplicaCache", () => {
+  it("persists the complete newest turn beyond the cache item target", async () => {
+    const storage = new MemoryStorage();
+    const writer = createCache(storage);
+    const items = Array.from({ length: 60 }, (_, index) => ({
+      ...timelineItem(`item-${index}`),
+      id: `item-${index}`,
+      turnId: "long-run",
+    }));
+    writer.commitTimeline(SERVER_ID, "agent-1", { ...timeline(), items });
+    await writer.flush();
+    const restored = await createCache(storage).readTimeline(SERVER_ID, "agent-1");
+    expect(restored?.items.map((item) => item.id)).toEqual(items.map((item) => item.id));
+    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);
@@ -498,6 +533,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 59578e65d7..044bed232a 100644
--- a/packages/app/src/runtime/replica-cache/index.ts
+++ b/packages/app/src/runtime/replica-cache/index.ts
@@ -1,3 +1,4 @@
+import { findMountedWindowStart } from "@/agent-stream/history-window";
 import { z } from "zod";
 import {
   AgentStatusSchema,
@@ -231,6 +232,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(),
@@ -246,6 +248,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(),
@@ -296,6 +300,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(),
@@ -611,6 +616,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,
@@ -631,26 +661,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: [],
@@ -658,7 +669,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,
@@ -697,6 +710,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,
@@ -766,7 +780,14 @@ function serializeTimeline(timeline: CachedTimeline): StoredTimeline | null {
   const canonicalItems = timeline.items.filter(
     (item) => item.kind !== "user_message" || !isUnreconciledLocalUserMessage(item),
   );
-  const items = canonicalItems.map(serializeTimelineItem).filter((item) => item !== null);
+  const start = findMountedWindowStart({
+    items: canonicalItems,
+    minMountedCount: MAX_TIMELINE_ITEMS,
+  });
+  const items = canonicalItems
+    .slice(start)
+    .map(serializeTimelineItem)
+    .filter((item) => item !== null);
   const range = timeline.range;
   const canPersistCoverage =
     range !== null &&
@@ -783,7 +804,7 @@ function serializeTimeline(timeline: CachedTimeline): StoredTimeline | null {
     canonicalItems.some((item) => item.timelineCursor?.seq === range.endSeq);
   return {
     agentId: timeline.agentId,
-    items: items.slice(-MAX_TIMELINE_ITEMS),
+    items,
     range: canPersistCoverage
       ? { epoch: range.epoch, startSeq: range.startSeq, endSeq: range.endSeq }
       : null,
diff --git a/packages/app/src/screens/new-workspace-screen.tsx b/packages/app/src/screens/new-workspace-screen.tsx
index 3cb01ae9df..18173545a7 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,
@@ -8,7 +9,6 @@ import { getHostRuntimeStore } from "@/runtime/host-runtime";
 import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
 import type { ReactNode } from "react";
 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 +62,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,
@@ -1166,9 +1165,7 @@ export function NewWorkspaceScreen({
     openAddProjectPicker(selectedServerId);
   }, [openAddProjectPicker, selectedServerId]);
 
-  const handleAddHost = useCallback(() => {
-    router.push(buildSettingsAddHostRoute(Date.now()));
-  }, []);
+  const handleAddHost = useAddHost();
 
   const openPicker = useCallback(() => {
     setPickerOpen(true);
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/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/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 b45b745212..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,14 +114,18 @@ 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";
 import ProjectsScreen from "@/screens/projects-screen";
 import ProjectSettingsScreen from "@/screens/project-settings-screen";
-import { SETTINGS_DESKTOP_SIDEBAR_WIDTH, useIsCompactFormFactor } from "@/constants/layout";
-import { densityIconBox, densityIconSize } from "@/styles/density";
+import {
+  SETTINGS_DESKTOP_DETAIL_MIN_WIDTH,
+  SETTINGS_DESKTOP_SIDEBAR_WIDTH,
+  useIsCompactFormFactor,
+} from "@/constants/layout";
+import { density, densityIconBox, densityIconSize } from "@/styles/density";
 import { useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
 import {
   type EnableBuiltInDaemonOption,
@@ -141,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
@@ -153,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;
 }
@@ -197,7 +201,7 @@ const SIDEBAR_SECTION_ITEMS: SidebarSectionItem[] = [
     id: "shortcuts",
     labelKey: "settings.sections.shortcuts",
     icon: Keyboard,
-    desktopOnly: true,
+    hardwareKeyboardOnly: true,
     Content: KeyboardShortcutsSection,
   },
   {
@@ -225,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);
 }
 
@@ -385,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;
@@ -416,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>
@@ -429,7 +455,6 @@ function DiagnosticsSection({
           </View>
           <Button
             variant="secondary"
-            size="sm"
             onPress={handlePlayPress}
             disabled={!voiceAudioEngine || isPlaybackTestRunning}
           >
@@ -686,7 +711,6 @@ function DesktopAppUpdateRow() {
           </Text>
         </View>
         <SegmentedControl
-          size="sm"
           value={settings.releaseChannel}
           onValueChange={handleReleaseChannelChange}
           options={releaseChannelOptions}
@@ -708,7 +732,6 @@ function DesktopAppUpdateRow() {
         <View style={styles.aboutUpdateActions}>
           <Button
             variant="outline"
-            size="sm"
             onPress={handleCheckForUpdates}
             disabled={isChecking || isInstalling}
           >
@@ -716,7 +739,6 @@ function DesktopAppUpdateRow() {
           </Button>
           <Button
             variant="default"
-            size="sm"
             onPress={handleInstallUpdate}
             disabled={isChecking || isInstalling || !isUpdateReady}
           >
@@ -951,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);
@@ -1085,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();
@@ -1160,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 {
@@ -1213,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);
@@ -1268,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) {
@@ -1293,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;
@@ -1342,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 (
@@ -1384,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 (
@@ -1432,7 +1370,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
             layout="mobile"
           />
         </ScrollView>
-        {addHostModals}
       </View>
     );
   }
@@ -1443,7 +1380,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
         <PageLayout title={detailTitle} onBack={handleBackFromDetail}>
           {content}
         </PageLayout>
-        {addHostModals}
       </View>
     );
   }
@@ -1478,7 +1414,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
           </View>
         </WindowChromeRegion>
       </View>
-      {addHostModals}
     </View>
   );
 }
@@ -1544,12 +1479,14 @@ const desktopStyles = StyleSheet.create({
   },
   contentPane: {
     flex: 1,
+    minWidth: SETTINGS_DESKTOP_DETAIL_MIN_WIDTH,
   },
 });
 
 const sidebarStyles = StyleSheet.create((theme) => ({
   desktopContainer: {
     width: SETTINGS_DESKTOP_SIDEBAR_WIDTH,
+    flexShrink: 1,
     borderRightWidth: 1,
     borderRightColor: theme.colors.border,
     backgroundColor: theme.colors.surfaceSidebar,
@@ -1586,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 },
@@ -1612,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/daemon-lifecycle.test.ts b/packages/app/src/screens/settings/daemon-lifecycle.test.ts
index c50006534a..d73222d9b9 100644
--- a/packages/app/src/screens/settings/daemon-lifecycle.test.ts
+++ b/packages/app/src/screens/settings/daemon-lifecycle.test.ts
@@ -12,6 +12,69 @@ test("settings restart completes when a replacement worker is observed without a
   expect(pid).toBe(11);
 });
 
+test("settings restart keeps terminals by default and closes them only when asked", async () => {
+  let pid = 10;
+  const requests: Array<{ killTerminals: boolean }> = [];
+  const deps = {
+    getStatus: async () => ({ pid, version: "1.0.0", serverId: "daemon" }),
+    restartServer: async (_reason: string, options: { killTerminals: boolean }) => {
+      requests.push(options);
+      pid += 1;
+    },
+  };
+  await restartDaemonFromSettings("daemon", "settings", deps);
+  await restartDaemonFromSettings("daemon", "settings", deps, { killTerminals: true });
+  expect(requests).toEqual([{ killTerminals: false }, { killTerminals: true }]);
+});
+
+test("a close-terminals restart completes when the replacement reports every terminal closed", async () => {
+  let pid = 10;
+  await restartDaemonFromSettings(
+    "daemon",
+    "settings",
+    {
+      getStatus: async () => ({
+        pid,
+        version: "1.0.0",
+        serverId: "daemon",
+        terminalCleanupUnconfirmed: [],
+      }),
+      restartServer: async () => {
+        pid = 11;
+      },
+    },
+    { killTerminals: true },
+  );
+  expect(pid).toBe(11);
+});
+
+test("a close-terminals restart fails with the processes the replacement could not confirm closed", async () => {
+  let pid = 10;
+  const leftover = {
+    pid: 4242,
+    role: "terminal program",
+    reason: "still alive",
+    detail: "survived SIGKILL",
+  };
+  const deps = {
+    getStatus: async () => ({
+      pid,
+      version: "1.0.0",
+      serverId: "daemon",
+      terminalCleanupUnconfirmed: pid === 10 ? [] : [leftover],
+    }),
+    restartServer: async () => {
+      pid += 1;
+    },
+  };
+
+  await expect(
+    restartDaemonFromSettings("daemon", "settings", deps, { killTerminals: true }),
+  ).rejects.toThrow("pid 4242 (terminal program): still alive (survived SIGKILL)");
+  // Keeping terminals asks nothing of the cleanup, so a leftover does not fail it.
+  await restartDaemonFromSettings("daemon", "settings", deps);
+});
+
 test("a status permission failure prevents the restart request", async () => {
   let restarted = false;
   await expect(
diff --git a/packages/app/src/screens/settings/daemon-lifecycle.ts b/packages/app/src/screens/settings/daemon-lifecycle.ts
index c4e9d83f5a..e848d26af8 100644
--- a/packages/app/src/screens/settings/daemon-lifecycle.ts
+++ b/packages/app/src/screens/settings/daemon-lifecycle.ts
@@ -1,35 +1,61 @@
+interface UnconfirmedTerminalProcess {
+  pid: number;
+  role: string;
+  reason: string;
+  detail: string;
+}
 interface WorkerStatus {
   pid: number;
   serverId: string;
   version: string | null;
+  // Absent on daemons without terminalsSurviveRestart, which have no terminal cleanup to report.
+  terminalCleanupUnconfirmed?: UnconfirmedTerminalProcess[];
 }
 interface StatusReader {
   getStatus: () => Promise<WorkerStatus>;
 }
 
 export interface SettingsDaemonRestartDeps extends StatusReader {
-  restartServer: (reason: string) => Promise<unknown>;
+  restartServer: (reason: string, options: { killTerminals: boolean }) => Promise<unknown>;
 }
 
-/** Acknowledgment starts the wait; only a different ready worker completes it. */
+/**
+ * Acknowledgment starts the wait; only a different ready worker completes it. Terminals survive
+ * the restart unless `killTerminals` is set (daemons advertising terminalsSurviveRestart); then
+ * the replacement must also report every terminal process gone.
+ */
 export async function restartDaemonFromSettings(
   hostServerId: string,
   reason: string,
   deps: SettingsDaemonRestartDeps,
+  options: { killTerminals: boolean } = { killTerminals: false },
 ): Promise<void> {
   const previous = await readSelectedWorker(hostServerId, deps);
   let acknowledged = false;
   try {
-    await deps.restartServer(reason);
+    await deps.restartServer(reason, options);
     acknowledged = true;
   } catch (error) {
     if (!isReconnectFailure(error)) throw error;
   }
+  let replacement: WorkerStatus;
   try {
-    await observeReplacement(previous, deps);
+    replacement = await observeReplacement(previous, deps);
   } catch (error) {
     throw new Error(`Restart acknowledged: ${acknowledged}. ${String(error)}`, { cause: error });
   }
+  const unconfirmed = replacement.terminalCleanupUnconfirmed ?? [];
+  if (options.killTerminals && unconfirmed.length > 0) {
+    throw new Error(
+      [
+        "The daemon restarted, but closing its terminals was not confirmed; these processes may still be running:",
+        ...unconfirmed.map(
+          (entry) => `pid ${entry.pid} (${entry.role}): ${entry.reason} (${entry.detail})`,
+        ),
+        "Stopping the daemon retries the cleanup.",
+      ].join("\n"),
+    );
+  }
 }
 
 export async function updateDaemonFromSettings(
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 85da0fdf4e..bc1712f4a1 100644
--- a/packages/app/src/screens/settings/general/sending-section.tsx
+++ b/packages/app/src/screens/settings/general/sending-section.tsx
@@ -1,13 +1,17 @@
 import { useCallback, useMemo } from "react";
 import { useTranslation } from "react-i18next";
 import { SettingsCard, SettingsSection, SettingsSelect } from "@/components/settings";
-import { useAppSettings, type SendBehavior } from "@/hooks/use-settings";
+import { useAppSettings, type SendShortcut, type SendBehavior } from "@/hooks/use-settings";
+import { useHardwareKeyboardPresent, supportsConfigurableComposerSendKeys } from "@/keyboard";
+import { getShortcutOs } from "@/utils/shortcut-platform";
 
 const SEND_BEHAVIORS: readonly SendBehavior[] = ["interrupt", "steer", "queue"];
 
 export function SendingSection() {
   const { t } = useTranslation();
   const { settings, updateSettings } = useAppSettings();
+  const shortcutsAvailable = useHardwareKeyboardPresent() && supportsConfigurableComposerSendKeys;
+  const modifier = getShortcutOs() === "mac" ? "⌘" : "Ctrl";
   const options = useMemo(
     () =>
       SEND_BEHAVIORS.map((value) => ({
@@ -20,12 +24,37 @@ export function SendingSection() {
     (sendBehavior: SendBehavior) => void updateSettings({ sendBehavior }),
     [updateSettings],
   );
+  const shortcutOptions = useMemo(
+    () =>
+      (["enter", "mod-enter"] as const).map((value) => ({
+        value,
+        label: t(`settings.general.sendShortcut.options.${value}`, { modifier }),
+      })),
+    [t, modifier],
+  );
+  const changeSendShortcut = useCallback(
+    (sendShortcut: SendShortcut) => void updateSettings({ sendShortcut }),
+    [updateSettings],
+  );
   return (
     <SettingsSection title={t("settings.general.sending")}>
       <SettingsCard>
+        {shortcutsAvailable ? (
+          <SettingsSelect
+            label={t("settings.general.sendShortcut.label")}
+            value={settings.sendShortcut}
+            options={shortcutOptions}
+            onValueChange={changeSendShortcut}
+          />
+        ) : null}
         <SettingsSelect
           label={t("settings.general.defaultSend.label")}
-          hint={t(`settings.general.defaultSend.descriptions.${settings.sendBehavior}`)}
+          hint={t(
+            shortcutsAvailable && settings.sendShortcut === "mod-enter"
+              ? `settings.general.defaultSend.commandEnterDescriptions.${settings.sendBehavior}`
+              : `settings.general.defaultSend.descriptions.${settings.sendBehavior}`,
+            { modifier },
+          )}
           value={settings.sendBehavior}
           options={options}
           onValueChange={change}
diff --git a/packages/app/src/screens/settings/host-page.tsx b/packages/app/src/screens/settings/host-page.tsx
index 0fb6fb5aa9..9c0c952488 100644
--- a/packages/app/src/screens/settings/host-page.tsx
+++ b/packages/app/src/screens/settings/host-page.tsx
@@ -65,6 +65,8 @@ 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";
 
@@ -289,9 +291,10 @@ 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} />
           <IdleRuntimeCleanupCard serverId={serverId} />
         </SettingsSection>
       ) : (
@@ -471,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}
@@ -480,7 +482,6 @@ function ConnectionsSection({ host }: { host: HostProfile }) {
             </Button>
             <Button
               variant="destructive"
-              size="sm"
               style={FLEX_1_STYLE}
               onPress={handleConfirmRemove}
               disabled={isRemovingConnection}
@@ -547,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>
@@ -565,7 +561,15 @@ function RestartDaemonCard({ host }: { host: HostProfile }) {
   const isConnected = useHostRuntimeIsConnected(host.serverId);
   const runtime = getHostRuntimeStore();
   const [isRestarting, setIsRestarting] = useState(false);
+  // Rendered in the card, not an Alert.alert: react-native-web's Alert is a no-op, and a failed
+  // close-terminals restart must name the processes left running until the user retries.
+  const [restartError, setRestartError] = useState<string | null>(null);
   const isMountedRef = useRef(true);
+  // COMPAT(terminalsSurviveRestart): added in v0.12.0, remove gate after 2027-04-21.
+  const terminalsSurviveRestart = useSessionStore(
+    (state) =>
+      state.sessions[host.serverId]?.serverInfo?.features?.terminalsSurviveRestart === true,
+  );
 
   useEffect(() => {
     return () => {
@@ -578,71 +582,80 @@ function RestartDaemonCard({ host }: { host: HostProfile }) {
     [host.serverId, runtime],
   );
 
-  const waitForDaemonRestart = useCallback(
-    async (request: Promise<void>) => {
-      try {
-        await request;
-      } catch (error) {
-        Alert.alert(
-          t("settings.host.daemon.restart.requestFailedTitle"),
-          error instanceof Error ? error.message : String(error),
-        );
-      } finally {
-        if (isMountedRef.current) setIsRestarting(false);
+  const waitForDaemonRestart = useCallback(async (request: Promise<void>) => {
+    try {
+      await request;
+    } catch (error) {
+      console.error("[HostPage] Daemon restart failed", error);
+      if (isMountedRef.current) {
+        setRestartError(error instanceof Error ? error.message : String(error));
       }
+    } finally {
+      if (isMountedRef.current) setIsRestarting(false);
+    }
+  }, []);
+
+  const startRestart = useCallback(
+    (killTerminals: boolean) => {
+      if (!daemonClient) {
+        Alert.alert(
+          t("settings.host.daemon.restart.unavailableTitle"),
+          t("settings.host.daemon.restart.unavailableMessage"),
+        );
+        return;
+      }
+      if (!isHostConnected()) {
+        Alert.alert(
+          t("settings.host.daemon.restart.offlineTitle"),
+          t("settings.host.daemon.restart.offlineMessage"),
+        );
+        return;
+      }
+
+      void confirmDialog({
+        title: t("settings.host.daemon.restart.confirmTitle", { name: host.label }),
+        message: killTerminals
+          ? t("settings.host.daemon.restart.closeTerminalsConfirmMessage")
+          : t("settings.host.daemon.restart.confirmMessage"),
+        confirmLabel: killTerminals
+          ? t("settings.host.daemon.restart.closeTerminals")
+          : t("settings.host.daemon.restart.confirm"),
+        cancelLabel: t("common.actions.cancel"),
+        destructive: true,
+      })
+        .then((confirmed) => {
+          if (!confirmed) return;
+          setRestartError(null);
+          setIsRestarting(true);
+          const restartRequest = restartDaemonFromSettings(
+            host.serverId,
+            `settings_daemon_restart_${host.serverId}`,
+            {
+              restartServer: (reason, options) =>
+                daemonClient.restartServer(reason, undefined, options),
+              getStatus: async () => ({
+                ...(await daemonClient.getDaemonStatus()),
+                serverId: daemonClient.getLastServerInfoMessage()?.serverId ?? "",
+                version: daemonClient.getLastServerInfoMessage()?.version ?? null,
+              }),
+            },
+            { killTerminals },
+          );
+          void waitForDaemonRestart(restartRequest);
+          return;
+        })
+        .catch((error) => {
+          console.error(`[HostPage] Failed to open restart confirmation for ${host.label}`, error);
+          if (isMountedRef.current) {
+            setRestartError(t("settings.host.daemon.restart.dialogFailedMessage"));
+          }
+        });
     },
-    [t],
+    [daemonClient, host.label, host.serverId, isHostConnected, t, waitForDaemonRestart],
   );
 
-  const handleRestart = useCallback(() => {
-    if (!daemonClient) {
-      Alert.alert(
-        t("settings.host.daemon.restart.unavailableTitle"),
-        t("settings.host.daemon.restart.unavailableMessage"),
-      );
-      return;
-    }
-    if (!isHostConnected()) {
-      Alert.alert(
-        t("settings.host.daemon.restart.offlineTitle"),
-        t("settings.host.daemon.restart.offlineMessage"),
-      );
-      return;
-    }
-
-    void confirmDialog({
-      title: t("settings.host.daemon.restart.confirmTitle", { name: host.label }),
-      message: t("settings.host.daemon.restart.confirmMessage"),
-      confirmLabel: t("settings.host.daemon.restart.confirm"),
-      cancelLabel: t("common.actions.cancel"),
-      destructive: true,
-    })
-      .then((confirmed) => {
-        if (!confirmed) return;
-        setIsRestarting(true);
-        const restartRequest = restartDaemonFromSettings(
-          host.serverId,
-          `settings_daemon_restart_${host.serverId}`,
-          {
-            restartServer: (reason) => daemonClient.restartServer(reason),
-            getStatus: async () => ({
-              ...(await daemonClient.getDaemonStatus()),
-              serverId: daemonClient.getLastServerInfoMessage()?.serverId ?? "",
-              version: daemonClient.getLastServerInfoMessage()?.version ?? null,
-            }),
-          },
-        );
-        void waitForDaemonRestart(restartRequest);
-        return;
-      })
-      .catch((error) => {
-        console.error(`[HostPage] Failed to open restart confirmation for ${host.label}`, error);
-        Alert.alert(
-          t("settings.host.daemon.restart.requestFailedTitle"),
-          t("settings.host.daemon.restart.dialogFailedMessage"),
-        );
-      });
-  }, [daemonClient, host.label, host.serverId, isHostConnected, t, waitForDaemonRestart]);
+  const handleRestart = useCallback(() => startRestart(false), [startRestart]);
+  const handleRestartAndCloseTerminals = useCallback(() => startRestart(true), [startRestart]);
 
   return (
     <View style={settingsStyles.card} testID="host-page-restart-card">
@@ -653,7 +666,6 @@ function RestartDaemonCard({ host }: { host: HostProfile }) {
         </View>
         <Button
           variant="outline"
-          size="sm"
           leftIcon={restartIcon}
           onPress={handleRestart}
           disabled={isRestarting || !daemonClient || !isConnected}
@@ -664,6 +676,34 @@ function RestartDaemonCard({ host }: { host: HostProfile }) {
             : t("settings.host.daemon.restart.confirm")}
         </Button>
       </View>
+      {terminalsSurviveRestart ? (
+        <View style={settingsStyles.row}>
+          <View style={settingsStyles.rowContent}>
+            <Text style={settingsStyles.rowHint}>
+              {t("settings.host.daemon.restart.closeTerminalsHint")}
+            </Text>
+          </View>
+          <Button
+            variant="outline"
+            onPress={handleRestartAndCloseTerminals}
+            disabled={isRestarting || !daemonClient || !isConnected}
+            testID="host-page-restart-close-terminals-button"
+          >
+            {t("settings.host.daemon.restart.closeTerminals")}
+          </Button>
+        </View>
+      ) : null}
+      {restartError ? (
+        <View style={styles.cardAlert}>
+          <InlineAlert
+            size="sm"
+            variant="error"
+            title={t("settings.host.daemon.restart.requestFailedTitle")}
+            description={restartError}
+            testID="host-page-restart-error"
+          />
+        </View>
+      ) : null}
     </View>
   );
 }
@@ -828,7 +868,6 @@ function UpdateDaemonCard({ host }: { host: HostProfile }) {
         </View>
         <Button
           variant="outline"
-          size="sm"
           leftIcon={updateIcon}
           onPress={handleUpdate}
           disabled={desktopManaged || isUpdating || !daemonClient || !isConnected}
@@ -848,7 +887,7 @@ function UpdateDaemonCard({ host }: { host: HostProfile }) {
         />
       ) : null}
       {updateState.status === "failed" ? (
-        <View style={styles.updateFailure}>
+        <View style={styles.cardAlert}>
           <InlineAlert
             size="sm"
             variant="error"
@@ -862,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);
@@ -1043,7 +1043,6 @@ function AppendSystemPromptCard({ serverId }: { serverId: string }) {
           </View>
           <Button
             variant="outline"
-            size="sm"
             onPress={handleOpen}
             testID="host-page-append-system-prompt-edit"
           >
@@ -1070,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"
@@ -1079,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"
@@ -1260,7 +1257,6 @@ function RemoveHostSection({
           </View>
           <Button
             variant="outline"
-            size="sm"
             leftIcon={removeIcon}
             textStyle={destructiveTextStyle}
             onPress={handleOpenConfirm}
@@ -1286,7 +1282,6 @@ function RemoveHostSection({
           <View style={styles.confirmActions}>
             <Button
               variant="secondary"
-              size="sm"
               style={FLEX_1_STYLE}
               onPress={handleCancel}
               disabled={isRemoving}
@@ -1295,7 +1290,6 @@ function RemoveHostSection({
             </Button>
             <Button
               variant="destructive"
-              size="sm"
               style={FLEX_1_STYLE}
               onPress={handleConfirmRemove}
               disabled={isRemoving}
@@ -1391,7 +1385,6 @@ function TerminalProfileRow({
       <View style={terminalProfileStyles.rowActions}>
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={moveUpIcon}
           onPress={handleMoveUp}
           disabled={isFirst}
@@ -1400,7 +1393,6 @@ function TerminalProfileRow({
         />
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={moveDownIcon}
           onPress={handleMoveDown}
           disabled={isLast}
@@ -1409,7 +1401,6 @@ function TerminalProfileRow({
         />
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={editProfileIcon}
           onPress={handleEdit}
           accessibilityLabel={t("settings.host.terminalProfiles.editProfile")}
@@ -1417,7 +1408,6 @@ function TerminalProfileRow({
         />
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={removeProfileIcon}
           onPress={handleRemove}
           accessibilityLabel={t("settings.host.terminalProfiles.remove")}
@@ -1583,7 +1573,6 @@ function TerminalProfilesSection({ serverId }: { serverId: string }) {
     () => (
       <Button
         variant="ghost"
-        size="sm"
         leftIcon={addProfileIcon}
         onPress={handleAddOpen}
         disabled={!isConnected || !profiles}
@@ -1702,7 +1691,7 @@ const terminalProfileStyles = StyleSheet.create((theme) => ({
 }));
 
 const styles = StyleSheet.create((theme) => ({
-  updateFailure: {
+  cardAlert: {
     marginHorizontal: theme.spacing[4],
     marginBottom: theme.spacing[4],
   },
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.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..09b09586d3 100644
--- a/packages/app/src/screens/settings/providers-section.tsx
+++ b/packages/app/src/screens/settings/providers-section.tsx
@@ -26,6 +26,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 +170,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 +274,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>
         </>
       )}
@@ -439,11 +467,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 +537,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 +609,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
new file mode 100644
index 0000000000..9c6d7a6d7a
--- /dev/null
+++ b/packages/app/src/screens/settings/restart-recovery-card.tsx
@@ -0,0 +1,197 @@
+import { useCallback, useMemo, useState } from "react";
+import { Text, View } from "react-native";
+import { useMutation } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+import { StyleSheet } from "react-native-unistyles";
+import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
+import { SettingsTextAreaCard } from "@/components/settings-textarea";
+import { SettingsInfoTip } from "@/components/settings/headings/settings-info-tip";
+import { Button } from "@/components/ui/button";
+import { Switch } from "@/components/ui/switch";
+import { useDaemonConfig } from "@/hooks/use-daemon-config";
+import { useHostFeature } from "@/runtime/host-features";
+import { useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import { settingsStyles } from "@/styles/settings";
+
+const DEFAULT_RESUME_PROMPT = "Resume working.";
+
+// COMPAT(restartRecovery): added in v0.14.0, remove gate after 2027-04-28.
+export function RestartRecoveryCard({ serverId }: { serverId: string }) {
+  const { t } = useTranslation();
+  const isConnected = useHostRuntimeIsConnected(serverId);
+  const isSupported = useHostFeature(serverId, "resumeOnStartupSetting");
+  const { config, patchConfig } = useDaemonConfig(serverId);
+  const [isEditing, setIsEditing] = useState(false);
+  const mutation = useMutation({
+    mutationFn: async (next: { resumeOnStartup?: boolean; resumePrompt?: string }) => {
+      const result = await patchConfig(next);
+      if (!result) {
+        throw new Error(t("workspace.terminal.hostDisconnected"));
+      }
+      return result;
+    },
+  });
+
+  const handleValueChange = useCallback(
+    (next: boolean) => {
+      mutation.mutate({ resumeOnStartup: next });
+    },
+    [mutation],
+  );
+
+  const handleOpen = useCallback(() => {
+    mutation.reset();
+    setIsEditing(true);
+  }, [mutation]);
+
+  const handleClose = useCallback(() => {
+    if (mutation.isPending) return;
+    mutation.reset();
+    setIsEditing(false);
+  }, [mutation]);
+
+  const handleSave = useCallback(
+    (prompt: string) => {
+      mutation.mutate({ resumePrompt: prompt }, { onSuccess: () => setIsEditing(false) });
+    },
+    [mutation],
+  );
+
+  if (!isConnected || !isSupported || !config) return null;
+
+  const isEnabled = config.resumeOnStartup === true;
+
+  return (
+    <>
+      <View style={settingsStyles.card} testID="host-page-restart-recovery-card">
+        <View style={settingsStyles.row}>
+          <View style={settingsStyles.rowContent}>
+            <View style={styles.titleRow}>
+              <Text style={settingsStyles.rowTitle}>
+                {t("settings.host.agents.resumeOnStartup.title")}
+              </Text>
+              <SettingsInfoTip
+                title={t("settings.host.agents.resumeOnStartup.title")}
+                info={t("settings.host.agents.resumeOnStartup.info")}
+              />
+            </View>
+            <Text style={settingsStyles.rowHint}>
+              {t("settings.host.agents.resumeOnStartup.hint")}
+            </Text>
+            {mutation.error && !isEditing ? (
+              <Text style={settingsStyles.rowError} testID="host-page-restart-recovery-error">
+                {mutation.error.message}
+              </Text>
+            ) : null}
+          </View>
+          <View style={styles.trailing}>
+            <Button
+              variant="outline"
+              onPress={handleOpen}
+              disabled={!isEnabled || mutation.isPending}
+              accessibilityLabel={t("settings.host.agents.resumeOnStartup.editAccessibilityLabel")}
+              testID="host-page-restart-recovery-edit"
+            >
+              {t("settings.host.agents.resumeOnStartup.edit")}
+            </Button>
+            <Switch
+              value={isEnabled}
+              onValueChange={handleValueChange}
+              disabled={mutation.isPending}
+              accessibilityLabel={t("settings.host.agents.resumeOnStartup.title")}
+              testID="host-page-restart-recovery-switch"
+            />
+          </View>
+        </View>
+      </View>
+
+      {isEditing ? (
+        <ResumePromptSheet
+          initialPrompt={config.resumePrompt ?? DEFAULT_RESUME_PROMPT}
+          isSaving={mutation.isPending}
+          error={mutation.error?.message ?? null}
+          onSave={handleSave}
+          onClose={handleClose}
+        />
+      ) : null}
+    </>
+  );
+}
+
+function ResumePromptSheet({
+  initialPrompt,
+  isSaving,
+  error,
+  onSave,
+  onClose,
+}: {
+  initialPrompt: string;
+  isSaving: boolean;
+  error: string | null;
+  onSave: (prompt: string) => void;
+  onClose: () => void;
+}) {
+  const { t } = useTranslation();
+  const [draft, setDraft] = useState(initialPrompt);
+  const header = useMemo<SheetHeader>(
+    () => ({ title: t("settings.host.agents.resumeOnStartup.prompt") }),
+    [t],
+  );
+  const canSave = draft !== initialPrompt && draft.trim().length > 0 && !isSaving;
+
+  const handleSave = useCallback(() => onSave(draft), [draft, onSave]);
+
+  return (
+    <AdaptiveModalSheet
+      header={header}
+      visible
+      onClose={onClose}
+      testID="host-page-restart-recovery-sheet"
+      desktopMaxWidth={560}
+    >
+      <SettingsTextAreaCard
+        testID="host-page-restart-recovery-prompt-input"
+        accessibilityLabel={t("settings.host.agents.resumeOnStartup.prompt")}
+        value={draft}
+        onChangeText={setDraft}
+        placeholder={DEFAULT_RESUME_PROMPT}
+      />
+      {error ? (
+        <Text style={settingsStyles.rowError} testID="host-page-restart-recovery-error">
+          {error}
+        </Text>
+      ) : null}
+      <View style={styles.sheetActions}>
+        <Button variant="ghost" onPress={onClose} disabled={isSaving}>
+          {t("common.actions.cancel")}
+        </Button>
+        <Button
+          variant="default"
+          onPress={handleSave}
+          disabled={!canSave}
+          testID="host-page-restart-recovery-save"
+        >
+          {t("common.actions.save")}
+        </Button>
+      </View>
+    </AdaptiveModalSheet>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  titleRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[2],
+  },
+  trailing: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[3],
+  },
+  sheetActions: {
+    flexDirection: "row",
+    justifyContent: "flex-end",
+    gap: theme.spacing[2],
+  },
+}));
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..c7fbcd7d06 100644
--- a/packages/app/src/screens/settings/sidebar/sidebar-nav-section.tsx
+++ b/packages/app/src/screens/settings/sidebar/sidebar-nav-section.tsx
@@ -117,7 +117,6 @@ function SidebarNavRow({
       <View style={styles.rowActions}>
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={moveUpIcon}
           onPress={handleMoveUp}
           disabled={isFirst}
@@ -126,7 +125,6 @@ function SidebarNavRow({
         />
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={moveDownIcon}
           onPress={handleMoveDown}
           disabled={isLast}
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..668f6345a8
--- /dev/null
+++ b/packages/app/src/screens/workspace/adaptive-workspace-chrome.tsx
@@ -0,0 +1,38 @@
+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";
+
+export function AdaptiveWorkspaceChrome({
+  compactHeader,
+  children,
+}: {
+  compactHeader: ReactNode;
+  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}>
+        {selectWorkspaceChrome({ width, compact: compactHeader, full: children })}
+      </View>
+    </WorkspaceTabMeasurementScope>
+  );
+}
+
+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/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
new file mode 100644
index 0000000000..74f5079fba
--- /dev/null
+++ b/packages/app/src/screens/workspace/sheet-pane/host.tsx
@@ -0,0 +1,86 @@
+import React, { createContext, useCallback, useContext, type ReactNode } from "react";
+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";
+import { useDiffDocumentWorkspaceCacheBridge } from "@/git/diff-document/workspace-cache";
+import { HostRouteProvider, useHostRouteServerId } from "@/navigation/host-route-context";
+import type { WorkspacePaneContentModel } from "@/screens/workspace/workspace-pane-content";
+import type { WorkspaceTabDescriptor } from "@/screens/workspace/workspace-tabs-types";
+
+/** What a sheet pane needs from the workspace it shows a tab of. */
+export interface SheetPaneHost {
+  workspaceKey: string;
+  serverId: string;
+  workspaceId: string;
+  isWorkspaceFocused: boolean;
+  /** The pane content for a sheet's tab. Closing the tab from inside it runs `closeCurrentTab`. */
+  buildContent: (
+    tab: WorkspaceTabDescriptor,
+    closeCurrentTab: () => void,
+  ) => WorkspacePaneContentModel;
+}
+
+const SheetPaneHostContext = createContext<SheetPaneHost | null>(null);
+
+/** `null` while there is no workspace to show sheets for. */
+export function SheetPaneHostProvider({
+  value,
+  children,
+}: {
+  value: SheetPaneHost | null;
+  children: ReactNode;
+}) {
+  return <SheetPaneHostContext.Provider value={value}>{children}</SheetPaneHostContext.Provider>;
+}
+
+/** The host of the workspace the caller is in, or null while there is none. */
+export function useSheetPaneHostIfAny(): SheetPaneHost | null {
+  return useContext(SheetPaneHostContext);
+}
+
+export function useSheetPaneHost(): SheetPaneHost {
+  const host = useSheetPaneHostIfAny();
+  invariant(host, "SheetPaneHostProvider is required");
+  return host;
+}
+
+/**
+ * Carries a sheet pane's environment across the portal into the app overlay host: the workspace
+ * host, and the environment of the built-in panels. Pane identity is supplied by the pane itself.
+ */
+export function useSheetPaneBridge(): ContextBridge {
+  const host = useSheetPaneHost();
+  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(forgeShorthand(children))));
+      return (
+        <SheetPaneHostContext.Provider value={host}>
+          <NavigationContext.Provider value={navigation}>
+            <NavigationRouteContext.Provider value={route}>
+              <RetainedPanelActivity active={active}>
+                {serverId ? (
+                  <HostRouteProvider serverId={serverId}>{content}</HostRouteProvider>
+                ) : (
+                  content
+                )}
+              </RetainedPanelActivity>
+            </NavigationRouteContext.Provider>
+          </NavigationContext.Provider>
+        </SheetPaneHostContext.Provider>
+      );
+    },
+    [host, editing, cache, files, forgeShorthand, active, serverId, navigation, route],
+  );
+}
diff --git a/packages/app/src/screens/workspace/sheet-pane/index.ts b/packages/app/src/screens/workspace/sheet-pane/index.ts
new file mode 100644
index 0000000000..1e6f6d1c40
--- /dev/null
+++ b/packages/app/src/screens/workspace/sheet-pane/index.ts
@@ -0,0 +1,16 @@
+/**
+ * A workspace tab shown in a sheet. One pane — header, body, bottom inset, focus — behind every
+ * sheet container: the workspace's sheet tabs, and pages of a menu that shows a sheet in place.
+ *
+ * See docs/explorer-sidebar.md.
+ */
+
+export {
+  SheetPaneHostProvider,
+  useSheetPaneBridge,
+  useSheetPaneHost,
+  useSheetPaneHostIfAny,
+  type SheetPaneHost,
+} from "./host";
+export { SheetPane, useLeaveSheet, type SheetPaneProps } from "./sheet-pane";
+export { useSheetPanePage } from "./page";
diff --git a/packages/app/src/screens/workspace/sheet-pane/page.tsx b/packages/app/src/screens/workspace/sheet-pane/page.tsx
new file mode 100644
index 0000000000..1b076510b9
--- /dev/null
+++ b/packages/app/src/screens/workspace/sheet-pane/page.tsx
@@ -0,0 +1,38 @@
+import { useCallback } from "react";
+import { useMenuContext, type MenuFillPageDefinition } from "@/components/ui/menu";
+import { usePaneContext } from "@/panels/pane-context";
+import type { SheetTab } from "@/stores/workspace-layout-store";
+import type { WorkspaceTabTarget } from "@/workspace-tabs/model";
+import { useSheetPaneBridge } from "./host";
+import { SheetPane } from "./sheet-pane";
+
+/**
+ * Shows sheet tabs as pages of a menu opened from a pane, so a row's sheet replaces the list it
+ * was chosen from instead of stacking a second sheet over it. Back returns to the list; Close
+ * closes the menu, which uncovers the pane the menu was opened from.
+ */
+export function useSheetPanePage(): (sheet: SheetTab) => MenuFillPageDefinition {
+  const bridge = useSheetPaneBridge();
+  const { target: opener } = usePaneContext();
+  return useCallback(
+    (sheet) => ({
+      id: sheet.tab.tabId,
+      fill: true,
+      content: bridge(
+        // Keyed like the detached container, so the panel's descriptor hook stays fixed per page.
+        <MenuSheetPane
+          key={`${sheet.tab.tabId}:${sheet.tab.target.kind}`}
+          sheet={sheet}
+          opener={opener}
+        />,
+      ),
+    }),
+    [bridge, opener],
+  );
+}
+
+function MenuSheetPane({ sheet, opener }: { sheet: SheetTab; opener: WorkspaceTabTarget }) {
+  const { setOpen, goBack } = useMenuContext("MenuSheetPane");
+  const close = useCallback(() => setOpen(false), [setOpen]);
+  return <SheetPane sheet={sheet} onClose={close} onBack={goBack} opener={opener} isTop />;
+}
diff --git a/packages/app/src/screens/workspace/sheet-pane/sheet-pane.tsx b/packages/app/src/screens/workspace/sheet-pane/sheet-pane.tsx
new file mode 100644
index 0000000000..7b93f84746
--- /dev/null
+++ b/packages/app/src/screens/workspace/sheet-pane/sheet-pane.tsx
@@ -0,0 +1,207 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  type ComponentType,
+} from "react";
+import { View } from "react-native";
+import { useTranslation } from "react-i18next";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
+import { Maximize2 } from "lucide-react-native";
+import {
+  SheetBottomInset,
+  SheetDragArea,
+  SheetHeaderIconButton,
+  SheetHeaderView,
+  type SheetHeader,
+} from "@/components/adaptive-modal-sheet";
+import type { PanelIconProps } from "@/panels/panel-registry";
+import { getPanelRegistration } from "@/panels/panel-registry";
+import { getHostRuntimeStore } from "@/runtime/host-runtime";
+import { useSessionStore } from "@/stores/session-store";
+import type { WorkspaceTabDescriptor } from "@/screens/workspace/workspace-tabs-types";
+import { WorkspacePaneContent } from "@/screens/workspace/workspace-pane-content";
+import { useWorkspaceLayoutStore, type SheetTab } from "@/stores/workspace-layout-store";
+import { workspaceTabTargetsEqual } from "@/workspace-tabs/identity";
+import type { WorkspaceTabTarget } from "@/workspace-tabs/model";
+import { useSheetPaneHost } from "./host";
+
+function PanelIcon({
+  icon: Icon,
+  size,
+  color,
+}: { icon: ComponentType<PanelIconProps> } & PanelIconProps) {
+  return <Icon size={size} color={color} />;
+}
+
+const ThemedPanelIcon = withUnistyles(PanelIcon, (theme) => ({
+  color: theme.colors.foregroundMuted,
+}));
+
+export interface SheetPaneProps {
+  sheet: SheetTab;
+  /** Closes the sheet, everything it was chosen from included. */
+  onClose: () => void;
+  /** Steps back to the list the sheet was chosen from, when there is one. */
+  onBack?: () => void;
+  /** The pane closing the sheet uncovers, when the container knows it. */
+  opener?: WorkspaceTabTarget | null;
+  /** Only the top sheet's pane is focused; a covered one stays as live as the pane under it. */
+  isTop: boolean;
+}
+
+interface SheetPaneExit {
+  close: () => void;
+  opener: WorkspaceTabTarget | null;
+}
+
+const SheetPaneExitContext = createContext<SheetPaneExit | null>(null);
+
+/**
+ * A tab shown in a sheet: its header (icon, title, Back, Open as tab, Close), which drags the
+ * sheet, over its pane. Every sheet container renders this; only the container differs.
+ */
+export function SheetPane({ sheet, onClose, onBack, opener = null, isTop }: SheetPaneProps) {
+  const { t } = useTranslation();
+  const host = useSheetPaneHost();
+  const { tab } = sheet;
+  const registration = getPanelRegistration(tab.target.kind);
+  if (!registration) {
+    throw new Error(`No panel registration for kind: ${tab.target.kind}`);
+  }
+  const descriptor = registration.useDescriptor(tab.target as never, {
+    serverId: host.serverId,
+    workspaceId: host.workspaceId,
+    tabId: tab.tabId,
+  });
+
+  const openTabInFront = useWorkspaceLayoutStore((state) => state.openTabInFront);
+  const { workspaceKey } = host;
+  const handleOpenAsTab = useCallback(
+    () => openTabInFront(workspaceKey, sheet),
+    [openTabInFront, sheet, workspaceKey],
+  );
+  const header = useMemo<SheetHeader>(
+    () => ({
+      title: descriptor.label,
+      leading: <ThemedPanelIcon icon={descriptor.icon} size={16} />,
+      back: onBack ? { onPress: onBack } : undefined,
+      // The sheet is for looking; the full-screen glyph takes the tab out of the sheet and into
+      // the switcher, where it gets its composer back.
+      actions: sheet.policy.openAsTab ? (
+        <SheetHeaderIconButton
+          icon={Maximize2}
+          accessibilityLabel={t("workspace.sheet.openAsTab")}
+          onPress={handleOpenAsTab}
+          testID="sheet-tab-open-as-tab"
+        />
+      ) : undefined,
+    }),
+    [descriptor.icon, descriptor.label, handleOpenAsTab, onBack, sheet.policy.openAsTab, t],
+  );
+
+  const tabDescriptor = useMemo<WorkspaceTabDescriptor>(
+    () => ({
+      key: tab.tabId,
+      tabId: tab.tabId,
+      kind: tab.target.kind,
+      target: tab.target,
+      state: tab.state,
+    }),
+    [tab],
+  );
+  const { buildContent } = host;
+  const content = useMemo(
+    () => buildContent(tabDescriptor, onClose),
+    [buildContent, onClose, tabDescriptor],
+  );
+  const exit = useMemo<SheetPaneExit>(() => ({ close: onClose, opener }), [onClose, opener]);
+  const isPaneFocused = isTop && host.isWorkspaceFocused;
+  useViewedSheetAgent({
+    sourceId: `${workspaceKey}:sheet:${tab.tabId}`,
+    serverId: host.serverId,
+    agentId: isPaneFocused && tab.target.kind === "agent" ? tab.target.agentId : null,
+  });
+
+  return (
+    <SheetPaneExitContext.Provider value={exit}>
+      <View style={styles.pane}>
+        {/* The body scrolls on its own, so the header is where the sheet drags from. */}
+        <SheetDragArea>
+          <SheetHeaderView header={header} onClose={onClose} testID="sheet-tab-header" />
+        </SheetDragArea>
+        <SheetBottomInset
+          style={styles.body}
+          role="dialog"
+          aria-label={descriptor.label}
+          testID="sheet-tab-body"
+        >
+          <WorkspacePaneContent
+            content={content}
+            isWorkspaceFocused={host.isWorkspaceFocused}
+            isPaneFocused={isPaneFocused}
+          />
+        </SheetBottomInset>
+      </View>
+    </SheetPaneExitContext.Provider>
+  );
+}
+
+/**
+ * The agent of the sheet on top is viewed, alongside the pane under it: its timeline catches up
+ * and stays live. The workspace only publishes the agents of its panes.
+ */
+function useViewedSheetAgent({
+  sourceId,
+  serverId,
+  agentId,
+}: {
+  sourceId: string;
+  serverId: string;
+  agentId: string | null;
+}) {
+  const viewedTimelineSync = useSessionStore(
+    (state) => state.sessions[serverId]?.viewedTimelineSync ?? null,
+  );
+  useEffect(() => {
+    if (!agentId) return;
+    void getHostRuntimeStore()
+      .prepareAgentTimeline(serverId, agentId)
+      .catch(() => undefined);
+  }, [agentId, serverId]);
+  useLayoutEffect(() => {
+    if (!agentId || !viewedTimelineSync) return;
+    viewedTimelineSync.replaceVisibleAgentIds(sourceId, [agentId]);
+    return () => viewedTimelineSync.replaceVisibleAgentIds(sourceId, []);
+  }, [agentId, sourceId, viewedTimelineSync]);
+}
+
+/**
+ * Leaves the sheet the calling pane is shown in, if any, on the way to `destination`. Answers
+ * whether closing the sheet already lands there, so the caller navigates only when it does not.
+ */
+export function useLeaveSheet(): (destination: WorkspaceTabTarget) => boolean {
+  const exit = useContext(SheetPaneExitContext);
+  return useCallback(
+    (destination) => {
+      if (!exit) return false;
+      exit.close();
+      return exit.opener !== null && workspaceTabTargetsEqual(exit.opener, destination);
+    },
+    [exit],
+  );
+}
+
+const styles = StyleSheet.create({
+  pane: {
+    flex: 1,
+    minHeight: 0,
+  },
+  body: {
+    flex: 1,
+    minHeight: 0,
+  },
+});
diff --git a/packages/app/src/screens/workspace/sheet-tabs.tsx b/packages/app/src/screens/workspace/sheet-tabs.tsx
index e7c8005233..30bebaac66 100644
--- a/packages/app/src/screens/workspace/sheet-tabs.tsx
+++ b/packages/app/src/screens/workspace/sheet-tabs.tsx
@@ -1,131 +1,62 @@
-import type { BottomSheetHandleProps } from "@gorhom/bottom-sheet";
 import { useIsFocused } from "expo-router/react-navigation";
+import { useCallback, useEffect, useRef } from "react";
 import {
-  type ComponentType,
-  type FC,
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
-import { View } from "react-native";
-import { useTranslation } from "react-i18next";
-import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { StyleSheet, withUnistyles } from "react-native-unistyles";
-import { useStore } from "zustand";
-import { createStore } from "zustand/vanilla";
-import { Maximize2 } from "lucide-react-native";
-import {
+  FULL_SHEET_SNAP_POINTS,
   SheetBackground,
   SheetHandle,
-  SheetHeaderIconButton,
-  SheetHeaderView,
-  type SheetHeader,
 } from "@/components/adaptive-modal-sheet";
 import {
   IsolatedBottomSheetModal,
   type IsolatedBottomSheetModalRef,
   systemBackPress,
 } from "@/components/ui/isolated-bottom-sheet-modal";
-import type { PanelIconProps } from "@/panels/panel-registry";
-import { getPanelRegistration } from "@/panels/panel-registry";
-import { ensurePanelsRegistered } from "@/panels/register-panels";
-import type { WorkspaceTabDescriptor } from "@/screens/workspace/workspace-tabs-types";
 import {
-  WorkspacePaneContent,
-  type WorkspacePaneContentModel,
-} from "@/screens/workspace/workspace-pane-content";
+  SheetPane,
+  useSheetPaneBridge,
+  useSheetPaneHost,
+  useSheetPaneHostIfAny,
+} from "@/screens/workspace/sheet-pane";
 import { useWorkspaceLayoutStore, type SheetTab } from "@/stores/workspace-layout-store";
-import { useWorkspaceSheetEnvironment } from "./workspace-sheet-environment";
 
-const SNAP_POINTS = ["92%"];
 const NO_SHEETS: readonly SheetTab[] = [];
 
-function PanelIcon({
-  icon: Icon,
-  size,
-  color,
-}: { icon: ComponentType<PanelIconProps> } & PanelIconProps) {
-  return <Icon size={size} color={color} />;
-}
-
-const ThemedPanelIcon = withUnistyles(PanelIcon, (theme) => ({
-  color: theme.colors.foregroundMuted,
-}));
-
-interface SheetTabHandleValue {
-  header: SheetHeader;
-  onClose: () => void;
-}
-
-/**
- * The sheet's handle, showing its header. Gorhom takes `handleComponent` as a component type and
- * renders it on the far side of the portal: a new function per render would remount the header on
- * every change, and no context from here reaches it. So each sheet gets one handle component for
- * its lifetime, which reads the header through a store the sheet keeps current.
- */
-function useSheetTabHandle(value: SheetTabHandleValue): FC<BottomSheetHandleProps> {
-  const [store] = useState(() => createStore<SheetTabHandleValue>(() => value));
-  useEffect(() => store.setState(value, true), [store, value]);
-  const [Handle] = useState(
-    () =>
-      function SheetTabHandle(props: BottomSheetHandleProps) {
-        const { header, onClose } = useStore(store);
-        return (
-          <SheetHandle {...props}>
-            <SheetHeaderView header={header} onClose={onClose} testID="sheet-tab-header" />
-          </SheetHandle>
-        );
-      },
-  );
-  return Handle;
-}
-
 export interface SheetTabsProps {
-  workspaceKey: string | null;
-  serverId: string;
-  workspaceId: string;
-  isWorkspaceFocused: boolean;
-  buildContent: (tab: WorkspaceTabDescriptor) => WorkspacePaneContentModel;
   /** The workspace's ordinary tab close, including its unsaved-changes guard. */
   onCloseTab: (tabId: string) => Promise<void>;
 }
 
-interface SheetTabSheetProps extends Omit<SheetTabsProps, "workspaceKey" | "onCloseTab"> {
+interface SheetTabSheetProps {
   sheet: SheetTab;
-  /** Only the top sheet's pane is focused and answers Android Back; the ones below wait their turn. */
+  /** Only the top sheet answers Android Back; the ones below wait their turn. */
   isTop: boolean;
   /** Runs the guarded close and resolves to whether the tab is still open. */
   onClose: (tabId: string) => Promise<boolean>;
-  onOpenAsTab: (tabId: string) => void;
 }
 
 /**
  * The workspace's sheet tabs, one sheet each, on the app-wide sheet stack. Their environment
- * crosses into the app overlay host so compact sheets cover both sidebars, and a
- * sheet opened from any other sheet (a subagent chosen from the subagents list, say) lands on top of
- * it and uncovers it on close. The shared sheet parts (`SheetBackground`, `SheetHandle`,
- * `SheetHeaderView`) keep them looking and dragging like every other sheet.
+ * crosses into the app overlay host so compact sheets cover both sidebars, and a sheet opened
+ * from another one lands on top of it and uncovers it on close.
  */
-export function SheetTabs({ workspaceKey, onCloseTab, ...rest }: SheetTabsProps) {
-  const sheets = useWorkspaceLayoutStore((state) =>
-    workspaceKey ? (state.sheetsByWorkspace[workspaceKey] ?? NO_SHEETS) : NO_SHEETS,
-  );
-  const openSheetAsTab = useWorkspaceLayoutStore((state) => state.openSheetAsTab);
-  const handleOpenAsTab = useCallback(
-    (tabId: string) => {
-      if (workspaceKey) openSheetAsTab(workspaceKey, tabId);
-    },
-    [openSheetAsTab, workspaceKey],
+export function SheetTabs({ onCloseTab }: SheetTabsProps) {
+  const host = useSheetPaneHostIfAny();
+  return host ? (
+    <WorkspaceSheetTabs workspaceKey={host.workspaceKey} onCloseTab={onCloseTab} />
+  ) : null;
+}
+
+function WorkspaceSheetTabs({
+  workspaceKey,
+  onCloseTab,
+}: SheetTabsProps & { workspaceKey: string }) {
+  const sheets = useWorkspaceLayoutStore(
+    (state) => state.sheetsByWorkspace[workspaceKey] ?? NO_SHEETS,
   );
   const handleClose = useCallback(
     async (tabId: string) => {
       await onCloseTab(tabId);
       // A declined unsaved-changes prompt leaves the tab in its sheet.
-      const open = workspaceKey
-        ? useWorkspaceLayoutStore.getState().sheetsByWorkspace[workspaceKey]
-        : undefined;
+      const open = useWorkspaceLayoutStore.getState().sheetsByWorkspace[workspaceKey];
       return open?.some((sheet) => sheet.tab.tabId === tabId) ?? false;
     },
     [onCloseTab, workspaceKey],
@@ -136,42 +67,21 @@ export function SheetTabs({ workspaceKey, onCloseTab, ...rest }: SheetTabsProps)
         <SheetTabSheet
           // Keyed by tab id and kind, so the registration and its descriptor hook stay fixed.
           key={`${sheet.tab.tabId}:${sheet.tab.target.kind}`}
-          {...rest}
           sheet={sheet}
           isTop={index === sheets.length - 1}
           onClose={handleClose}
-          onOpenAsTab={handleOpenAsTab}
         />
       ))}
     </>
   );
 }
 
-function SheetTabSheet({
-  sheet,
-  isTop,
-  serverId,
-  workspaceId,
-  isWorkspaceFocused,
-  buildContent,
-  onClose,
-  onOpenAsTab,
-}: SheetTabSheetProps) {
-  const { t } = useTranslation();
+function SheetTabSheet({ sheet, isTop, onClose }: SheetTabSheetProps) {
   const { tab } = sheet;
   const sheetRef = useRef<IsolatedBottomSheetModalRef>(null);
   const isScreenFocused = useIsFocused();
-  const contextBridge = useWorkspaceSheetEnvironment();
-  ensurePanelsRegistered();
-  const registration = getPanelRegistration(tab.target.kind);
-  if (!registration) {
-    throw new Error(`No panel registration for kind: ${tab.target.kind}`);
-  }
-  const descriptor = registration.useDescriptor(tab.target as never, {
-    serverId,
-    workspaceId,
-    tabId: tab.tabId,
-  });
+  const { isWorkspaceFocused } = useSheetPaneHost();
+  const contextBridge = useSheetPaneBridge();
 
   // The sheet lives as long as its store entry: it presents on mount, and unmounting takes it off
   // the stack, which uncovers the sheet below. Gorhom slides an unmounting sheet down and still
@@ -209,105 +119,23 @@ function SheetTabSheet({
     });
   }, [close, ownsBackPress]);
 
-  const handleOpenAsTab = useCallback(() => onOpenAsTab(tab.tabId), [onOpenAsTab, tab.tabId]);
-  const header = useMemo<SheetHeader>(
-    () => ({
-      title: descriptor.label,
-      leading: <ThemedPanelIcon icon={descriptor.icon} size={16} />,
-      // The sheet is for looking; the full-screen glyph takes the tab out of the sheet and into
-      // the switcher, where it gets its composer back.
-      actions: sheet.policy.openAsTab ? (
-        <SheetHeaderIconButton
-          icon={Maximize2}
-          accessibilityLabel={t("workspace.sheet.openAsTab")}
-          onPress={handleOpenAsTab}
-          testID="sheet-tab-open-as-tab"
-        />
-      ) : undefined,
-    }),
-    [descriptor.icon, descriptor.label, handleOpenAsTab, sheet.policy.openAsTab, t],
-  );
-  const handleValue = useMemo<SheetTabHandleValue>(
-    () => ({ header, onClose: close }),
-    [close, header],
-  );
-  // The header is the sheet's handle: the panel scrolls on its own, so dragging the content would
-  // fight it, and the header is where people reach to pull the sheet down.
-  const SheetTabHandle = useSheetTabHandle(handleValue);
-
   return (
     <IsolatedBottomSheetModal
       ref={sheetRef}
       contextBridge={contextBridge}
-      snapPoints={SNAP_POINTS}
+      snapPoints={FULL_SHEET_SNAP_POINTS}
       enableDynamicSizing={false}
       enablePanDownToClose
+      // The pane scrolls on its own; the sheet drags from its handle and header.
       enableContentPanningGesture={false}
       enableDismissOnClose={false}
       backgroundComponent={SheetBackground}
-      handleComponent={SheetTabHandle}
+      handleComponent={SheetHandle}
       backdropOpacity={0.45}
       onChange={handleChange}
       accessible={false}
     >
-      {/* A covered sheet stays as live as the pane under it; only focus follows the top sheet. */}
-      <SheetTabBody
-        tab={tab}
-        label={descriptor.label}
-        isPaneFocused={isTop && isWorkspaceFocused}
-        isWorkspaceFocused={isWorkspaceFocused}
-        buildContent={buildContent}
-      />
+      <SheetPane sheet={sheet} onClose={close} isTop={isTop} />
     </IsolatedBottomSheetModal>
   );
 }
-
-function SheetTabBody({
-  tab,
-  label,
-  isPaneFocused,
-  isWorkspaceFocused,
-  buildContent,
-}: {
-  tab: SheetTab["tab"];
-  label: string;
-  /** Only the top sheet's pane is focused; the ones below are covered. */
-  isPaneFocused: boolean;
-  isWorkspaceFocused: boolean;
-  buildContent: (tab: WorkspaceTabDescriptor) => WorkspacePaneContentModel;
-}) {
-  const tabDescriptor = useMemo<WorkspaceTabDescriptor>(
-    () => ({
-      key: tab.tabId,
-      tabId: tab.tabId,
-      kind: tab.target.kind,
-      target: tab.target,
-      state: tab.state,
-    }),
-    [tab],
-  );
-  const content = useMemo(() => buildContent(tabDescriptor), [buildContent, tabDescriptor]);
-  // The sheet reaches the bottom of the screen, so it owns the system navigation inset.
-  const { bottom: bottomInset } = useSafeAreaInsets();
-  const contentStyle = useMemo(
-    () => [styles.content, { paddingBottom: bottomInset }],
-    [bottomInset],
-  );
-
-  return (
-    <View style={contentStyle} role="dialog" aria-label={label} testID="sheet-tab-body">
-      <WorkspacePaneContent
-        content={content}
-        isWorkspaceFocused={isWorkspaceFocused}
-        isPaneFocused={isPaneFocused}
-      />
-    </View>
-  );
-}
-
-const styles = StyleSheet.create({
-  content: {
-    flex: 1,
-    minHeight: 0,
-  },
-});
diff --git a/packages/app/src/screens/workspace/visible-agent-ids.test.ts b/packages/app/src/screens/workspace/visible-agent-ids.test.ts
index 1378d6cc20..37f470bb3f 100644
--- a/packages/app/src/screens/workspace/visible-agent-ids.test.ts
+++ b/packages/app/src/screens/workspace/visible-agent-ids.test.ts
@@ -111,28 +111,6 @@ test("pane retargeting replaces the viewed agent and duplicate panes collapse to
   }).toEqual({ duplicate: ["agent-a"], retargeted: ["agent-a", "agent-b"] });
 });
 
-test("the agent shown in the workspace sheet is viewed alongside the pane under it", () => {
-  const layout: WorkspaceLayout = {
-    focusedPaneId: "main",
-    root: { kind: "pane", pane: { id: "main", tabIds: ["a"], focusedTabId: "a" } },
-  };
-  const tabs: WorkspaceTab[] = [
-    { tabId: "a", target: { kind: "agent", agentId: "agent-a" }, createdAt: 1 },
-  ];
-  const sheetTab: WorkspaceTab = {
-    tabId: "sheet",
-    target: { kind: "agent", agentId: "agent-child" },
-    createdAt: 2,
-  };
-
-  expect(
-    selectVisibleAgentIds({ layout, tabs, sheetTab, routeFocused: true, focusedPaneOnly: true }),
-  ).toEqual(["agent-a", "agent-child"]);
-  expect(
-    selectVisibleAgentIds({ layout, tabs, sheetTab, routeFocused: false, focusedPaneOnly: true }),
-  ).toEqual([]);
-});
-
 test("single-pane tablet includes its visible Explorer agent without including other splits", () => {
   const layout: WorkspaceLayout = {
     focusedPaneId: "main",
diff --git a/packages/app/src/screens/workspace/visible-agent-ids.ts b/packages/app/src/screens/workspace/visible-agent-ids.ts
index 8643e84940..95a5ec84f8 100644
--- a/packages/app/src/screens/workspace/visible-agent-ids.ts
+++ b/packages/app/src/screens/workspace/visible-agent-ids.ts
@@ -6,8 +6,6 @@ import { deriveWorkspacePaneState } from "./workspace-pane-state";
 export function selectVisibleAgentIds(input: {
   layout: WorkspaceLayout | null;
   tabs: WorkspaceTab[];
-  /** The workspace sheet's tab, shown over the panes. */
-  sheetTab?: WorkspaceTab | null;
   routeFocused: boolean;
   focusedPaneOnly: boolean;
   explorerPaneId?: string | null;
@@ -29,7 +27,6 @@ export function selectVisibleAgentIds(input: {
       .target;
     return target ? [target] : [];
   });
-  if (input.sheetTab) targets.push(input.sheetTab.target);
   return [
     ...new Set(targets.flatMap((target) => (target.kind === "agent" ? [target.agentId] : []))),
   ].sort();
@@ -38,7 +35,6 @@ export function selectVisibleAgentIds(input: {
 export function useVisibleAgentIds(input: {
   layout: WorkspaceLayout | null;
   tabs: WorkspaceTab[];
-  sheetTab: WorkspaceTab | null;
   routeFocused: boolean;
   focusedPaneOnly: boolean;
   explorerPaneId?: string | null;
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-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-pane-content.test.tsx b/packages/app/src/screens/workspace/workspace-pane-content.test.tsx
index 84ec2634b9..6726c4d686 100644
--- a/packages/app/src/screens/workspace/workspace-pane-content.test.tsx
+++ b/packages/app/src/screens/workspace/workspace-pane-content.test.tsx
@@ -11,18 +11,7 @@ import {
 } from "@/screens/workspace/workspace-pane-content";
 import type { WorkspaceTabDescriptor } from "@/screens/workspace/workspace-tabs-types";
 import { usePaneContext, usePaneFocus, type PaneContextValue } from "@/panels/pane-context";
-
-vi.mock("@/panels/register-panels", () => ({
-  ensurePanelsRegistered: vi.fn(),
-}));
-
-vi.mock("@/panels/panel-registry", () => ({
-  getPanelRegistration: () => ({
-    kind: "agent",
-    component: ProbePanel,
-    useDescriptor: vi.fn(),
-  }),
-}));
+import { definePanel, registerPanel } from "@/panels/panel-registry";
 
 interface ProbeSnapshot {
   paneContextValue: PaneContextValue;
@@ -48,6 +37,18 @@ function ProbePanel() {
   return null;
 }
 
+// The workspace screen registers the real panels; this probe stands in for each kind the tests open.
+for (const kind of ["agent", "draft"] as const) {
+  registerPanel(
+    definePanel(kind, {
+      component: ProbePanel,
+      useDescriptor: () => {
+        throw new Error("The probe panel has no descriptor");
+      },
+    }),
+  );
+}
+
 const agentTab: WorkspaceTabDescriptor = {
   key: "agent_agent-a",
   tabId: "agent_agent-a",
diff --git a/packages/app/src/screens/workspace/workspace-pane-content.tsx b/packages/app/src/screens/workspace/workspace-pane-content.tsx
index 21476a85a4..95368240e9 100644
--- a/packages/app/src/screens/workspace/workspace-pane-content.tsx
+++ b/packages/app/src/screens/workspace/workspace-pane-content.tsx
@@ -9,7 +9,6 @@ import {
 } from "@/panels/pane-context";
 import { useStableEvent } from "@/hooks/use-stable-event";
 import { getPanelRegistration } from "@/panels/panel-registry";
-import { ensurePanelsRegistered } from "@/panels/register-panels";
 import type { WorkspaceTabDescriptor } from "@/screens/workspace/workspace-tabs-types";
 import { RenderProfile } from "@/utils/render-profiler";
 import type { WorkspaceFileOpenRequest } from "@/workspace/file-open";
@@ -56,7 +55,6 @@ export function buildWorkspacePaneContentModel({
   onOpenWorkspaceFile,
   onOpenImportSheet,
 }: BuildWorkspacePaneContentModelInput): WorkspacePaneContentModel {
-  ensurePanelsRegistered();
   const registration = getPanelRegistration(tab.kind);
   invariant(registration, `No panel registration for kind: ${tab.kind}`);
   return {
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 3617c074e2..6ba87ac884 100644
--- a/packages/app/src/screens/workspace/workspace-screen.tsx
+++ b/packages/app/src/screens/workspace/workspace-screen.tsx
@@ -1,13 +1,21 @@
+import {
+  AdaptiveWorkspaceChrome,
+  type WorkspaceCompactHeaderActions,
+} 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 {
@@ -59,10 +67,11 @@ 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";
+import { useOpenOutsideWorkspaceFolder } from "@/workspace/open-in-file-manager/outside-folder";
 import { getOrCreateClientId } from "@/utils/client-id";
 import { selectIsAgentListOpen, usePanelStore } from "@/stores/panel-store";
 import { toggleDesktopSidebarsWithCheckoutIntent } from "@/utils/desktop-sidebar-toggle";
@@ -125,10 +134,10 @@ import {
   useWorkspaceSetupStore,
 } from "@/stores/workspace-setup-store";
 import { useWorkspace } from "@/stores/session-store-hooks";
-import { useWorkspaceTerminalSessionRetention } from "@/terminal/hooks/use-workspace-terminal-session-retention";
 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";
@@ -144,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";
@@ -178,6 +188,8 @@ import {
   type WorkspacePaneContentModel,
 } from "@/screens/workspace/workspace-pane-content";
 import { useMountedTabSet } from "@/screens/workspace/use-mounted-tab-set";
+import { ensurePanelsRegistered } from "@/panels/register-panels";
+import { SheetPaneHostProvider, type SheetPaneHost } from "@/screens/workspace/sheet-pane";
 import { SheetTabs } from "@/screens/workspace/sheet-tabs";
 import type { PaneHost } from "@/panels/panel-manifest";
 import { WorkspaceFocusProvider } from "@/workspace/focus";
@@ -368,9 +380,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}`}>
@@ -419,6 +431,10 @@ export const WorkspaceScreen = memo(function WorkspaceScreen({
   workspaceId,
   isRouteFocused,
 }: WorkspaceScreenProps) {
+  // Every reader of the panel registry renders inside the workspace screen, so it registers the
+  // panels before any of them renders. A reader importing the registration instead would import
+  // every panel, and the panels render readers.
+  ensurePanelsRegistered();
   const navigationFocused = useIsFocused();
   useEffect(() => {
     traceInstant("paseo.workspace.mount", { serverId, workspaceId });
@@ -493,6 +509,7 @@ function WorkspaceHeaderTitleBar({
   onCopyBranchName,
   onOpenSetupTab,
 }: WorkspaceHeaderTitleBarProps) {
+  const actionsInBar = resolveWorkspaceActionPlacement(useWindowLayout()) === "vertical-bar";
   return (
     <View style={styles.headerTitleContainer}>
       {isLoading ? (
@@ -509,18 +526,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>
   );
 }
@@ -762,13 +781,17 @@ function WorkspaceScreenGateFrame({ children }: { children: ReactNode }) {
 function WorkspaceContentProviders({
   children,
   workspaceKey,
+  sheetPaneHost,
 }: {
   children: ReactNode;
   workspaceKey: string | null;
+  sheetPaneHost: SheetPaneHost | null;
 }) {
   return (
     <WorkspaceFocusProvider workspaceKey={workspaceKey}>
-      <DiffDocumentWorkspaceCacheProvider>{children}</DiffDocumentWorkspaceCacheProvider>
+      <DiffDocumentWorkspaceCacheProvider>
+        <SheetPaneHostProvider value={sheetPaneHost}>{children}</SheetPaneHostProvider>
+      </DiffDocumentWorkspaceCacheProvider>
     </WorkspaceFocusProvider>
   );
 }
@@ -848,8 +871,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. */
@@ -869,13 +896,6 @@ function shouldShowWorkspaceScreenHeader(input: {
   return !input.isFocusModeEnabled || input.isMobile;
 }
 
-function buildWorkspaceTerminalScopeKey(serverId: string, workspaceId: string): string | null {
-  if (!serverId || !workspaceId) {
-    return null;
-  }
-  return `${serverId}:${workspaceId}`;
-}
-
 /**
  * A pane the user acted inside owns the tab: it opens there, and an existing tab
  * moves there. No pane means the open has no opinion beyond the focused pane.
@@ -1016,8 +1036,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");
@@ -1054,14 +1077,6 @@ function WorkspaceScreenContent({
   const { handleRetryHost, handleManageHost, handleDismissMissingWorkspace } =
     useWorkspaceRouteActions(normalizedServerId);
 
-  const workspaceTerminalScopeKey = useMemo(
-    () => buildWorkspaceTerminalScopeKey(normalizedServerId, normalizedWorkspaceId),
-    [normalizedServerId, normalizedWorkspaceId],
-  );
-  useWorkspaceTerminalSessionRetention({
-    scopeKey: workspaceTerminalScopeKey,
-  });
-
   const client = useHostRuntimeClient(normalizedServerId);
   const isConnected = useHostRuntimeIsConnected(normalizedServerId);
   const supportsProvidersSnapshot = useSessionStore(
@@ -1215,6 +1230,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({
@@ -1228,6 +1250,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,
@@ -1340,10 +1367,6 @@ function WorkspaceScreenContent({
   const sheets = useWorkspaceLayoutStore((state) =>
     persistenceKey ? (state.sheetsByWorkspace[persistenceKey] ?? NO_SHEETS) : NO_SHEETS,
   );
-  // Only the top sheet is on screen.
-  const sheetTab = useWorkspaceLayoutStore((state) =>
-    persistenceKey ? (state.sheetsByWorkspace[persistenceKey]?.at(-1)?.tab ?? null) : null,
-  );
   const unpinWorkspaceAgent = useWorkspaceLayoutStore((state) => state.unpinAgent);
   const hideWorkspaceAgent = useWorkspaceLayoutStore((state) => state.hideAgent);
   const setWorkspaceTabState = useWorkspaceLayoutStore((state) => state.setTabState);
@@ -1415,7 +1438,6 @@ function WorkspaceScreenContent({
   const visibleAgentIds = useVisibleAgentIds({
     layout: workspaceLayout,
     tabs: uiTabs,
-    sheetTab,
     routeFocused: isRouteFocused,
     focusedPaneOnly: syncFocusedPaneOnly,
     explorerPaneId: explorerSidebarPaneId,
@@ -1533,7 +1555,7 @@ function WorkspaceScreenContent({
       persistenceKey,
       buildWorkspaceTabSnapshot({
         agentVisibility: workspaceAgentVisibility,
-        agentsHydrated: hasHydratedAgents,
+        agentsHydrated: hasHydratedAgents && !isArchiveUndoRunning,
         terminalsHydrated: terminalsQuery.isSuccess,
         knownTerminalIds,
         standaloneTerminalIds,
@@ -1544,6 +1566,7 @@ function WorkspaceScreenContent({
     );
   }, [
     hasHydratedAgents,
+    isArchiveUndoRunning,
     hasHydratedWorkspaceLayoutStore,
     pendingTerminalCreateInput,
     createTerminalMutation.isPending,
@@ -1801,8 +1824,8 @@ function WorkspaceScreenContent({
   });
 
   const handleCreateTerminalWithProfile = useCallback(
-    (profile: TerminalProfile) => {
-      createTerminal({ profile, destination: { kind: "open" } });
+    (profile: TerminalProfile, paneId?: string) => {
+      createTerminal({ profile, destination: { kind: "open", paneId } });
     },
     [createTerminal],
   );
@@ -2179,8 +2202,7 @@ function WorkspaceScreenContent({
         const sessionState = useSessionStore.getState().sessions[normalizedServerId];
         const currentCursor = sessionState?.agentTimelineCursor.get(agentId);
         await getHostRuntimeStore().fetchAgentTimeline(normalizedServerId, agentId, {
-          direction: "tail",
-          projection: "projected",
+          ...planTimelineTailFetch(),
           ...(currentCursor
             ? { cursor: { epoch: currentCursor.epoch, seq: currentCursor.endSeq } }
             : {}),
@@ -2915,6 +2937,8 @@ function WorkspaceScreenContent({
       paneId?: string | null;
       focusPaneBeforeOpen?: boolean;
       host?: PaneHost;
+      /** Overrides the guarded tab close, for a host that closes the tab its own way. */
+      onCloseCurrentTab?: () => void;
     }) =>
       buildWorkspacePaneContentModel({
         tab: input.tab,
@@ -2964,9 +2988,11 @@ function WorkspaceScreenContent({
                 });
               }
             : undefined,
-        onCloseCurrentTab: () => {
-          void handleCloseTabById(input.tab.tabId);
-        },
+        onCloseCurrentTab:
+          input.onCloseCurrentTab ??
+          (() => {
+            void handleCloseTabById(input.tab.tabId);
+          }),
         onRetargetCurrentTab: (target) => {
           if (!persistenceKey) {
             return;
@@ -3041,16 +3067,36 @@ function WorkspaceScreenContent({
     [buildPaneContentModel],
   );
   const buildSheetPaneContentModel = useCallback(
-    function buildSheetPaneContentModel(tab: WorkspaceTabDescriptor) {
+    function buildSheetPaneContentModel(tab: WorkspaceTabDescriptor, closeCurrentTab: () => void) {
       return buildPaneContentModel({
         tab,
         paneId: null,
         focusPaneBeforeOpen: false,
         host: "sheet",
+        onCloseCurrentTab: closeCurrentTab,
       });
     },
     [buildPaneContentModel],
   );
+  const sheetPaneHost = useMemo<SheetPaneHost | null>(
+    () =>
+      persistenceKey
+        ? {
+            workspaceKey: persistenceKey,
+            serverId: normalizedServerId,
+            workspaceId: normalizedWorkspaceId,
+            isWorkspaceFocused: isRouteFocused,
+            buildContent: buildSheetPaneContentModel,
+          }
+        : null,
+    [
+      buildSheetPaneContentModel,
+      isRouteFocused,
+      normalizedServerId,
+      normalizedWorkspaceId,
+      persistenceKey,
+    ],
+  );
   const handleFocusPane = useStableEvent(function handleFocusPane(paneId: string) {
     if (!persistenceKey || paneFocusSuppressedRef.current) {
       return;
@@ -3173,11 +3219,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
@@ -3195,15 +3239,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>
@@ -3215,13 +3261,14 @@ function WorkspaceScreenContent({
       workspaceDirectory,
       activeFileLocation,
       liveTerminalIds,
-      handleScriptTerminalStarted,
+      scriptActions,
       handleViewScriptTerminal,
       handleOpenUrlInBrowserTab,
       handleToggleExplorerSidebar,
       explorerSidebarToggleLabel,
       explorerSidebarToggleAccessibilityState,
       explorerToggleOwner,
+      workspaceActionsInBar,
       t,
     ],
   );
@@ -3327,28 +3374,79 @@ 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(
+    (
+      headerTabs: WorkspaceTabDescriptor[],
+      headerActiveTabKey: string,
+      actions: WorkspaceCompactHeaderActions,
+    ) => {
+      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,
+    ],
+  );
+  const renderCompactWorkspaceHeader = useCallback(
+    (
+      headerTabs: WorkspaceTabDescriptor[],
+      headerActiveTabKey: string,
+      actions: WorkspaceCompactHeaderActions,
+      actionsOnly = false,
+    ) => {
+      const tabSwitcher = renderWorkspaceTabSwitcher(headerTabs, headerActiveTabKey, actions);
+      return (
         <CompactWorkspaceHeader
+          headerVariant={actionsOnly ? "full" : "compact"}
+          actionsActive={isRouteFocused && (!isMobile || workspacePanelActive)}
+          tabSwitcher={tabSwitcher}
           isLoading={isWorkspaceHeaderLoading}
           title={workspaceHeaderTitle}
           subtitle={workspaceHeaderSubtitle}
@@ -3358,27 +3456,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={actions.pane}
+            onExitFocusMode={isFocusModeEnabled ? toggleFocusMode : undefined}
             normalizedServerId={normalizedServerId}
             normalizedWorkspaceId={normalizedWorkspaceId}
             scripts={compactHeaderScripts}
@@ -3396,35 +3476,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,
@@ -3432,12 +3503,27 @@ function WorkspaceScreenContent({
       openImportSheet,
       showCreateBrowserTab,
       showWorkspaceSetup,
-      tabs,
       workspaceDirectory,
       workspaceHeaderSubtitle,
       workspaceHeaderTitle,
+      workspacePanelActive,
     ],
   );
+  const compactWorkspaceHeader = renderCompactWorkspaceHeader(tabs, activeTabKey, {
+    closeAbove: handleCloseTabsToLeft,
+    closeBelow: handleCloseTabsToRight,
+    closeOthers: handleCloseOtherTabs,
+  });
+  const fullWorkspaceActions = renderCompactWorkspaceHeader(
+    tabs,
+    activeTabKey,
+    {
+      closeAbove: handleCloseTabsToLeft,
+      closeBelow: handleCloseTabsToRight,
+      closeOthers: handleCloseOtherTabs,
+    },
+    true,
+  );
   const desktopSplitContent = useMemo(() => {
     if (!canRenderDesktopPaneSplits || !workspaceLayout || !persistenceKey) {
       return null;
@@ -3446,6 +3532,7 @@ function WorkspaceScreenContent({
       <SplitContainer
         layout={workspaceLayout}
         renderMainHeader={renderWorkspaceScreenHeader}
+        renderCompactHeader={renderCompactWorkspaceHeader}
         focusModeEnabled={desktopFocusModeEnabled}
         onExitFocusMode={toggleFocusMode}
         workspaceKey={persistenceKey}
@@ -3482,6 +3569,7 @@ function WorkspaceScreenContent({
     canRenderDesktopPaneSplits,
     workspaceLayout,
     renderWorkspaceScreenHeader,
+    renderCompactWorkspaceHeader,
     persistenceKey,
     desktopFocusModeEnabled,
     toggleFocusMode,
@@ -3520,6 +3608,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,
@@ -3539,47 +3643,45 @@ function WorkspaceScreenContent({
           </StreamTopOverlayProvider>
         )}
       </FloatingHeaderLayout>
-      <SheetTabs
-        workspaceKey={persistenceKey}
-        serverId={normalizedServerId}
-        workspaceId={normalizedWorkspaceId}
-        isWorkspaceFocused={isRouteFocused}
-        buildContent={buildSheetPaneContentModel}
-        onCloseTab={handleCloseTabById}
-      />
+      <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}
+      {rendersDesktopSplitContent ? null : (
+        <AdaptiveWorkspaceChrome compactHeader={compactWorkspaceHeader}>
+          {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>
@@ -3682,6 +3784,7 @@ function WorkspaceScreenContent({
       view: "files",
     });
   });
+  const openMarkdownOutsideDirectory = useOpenOutsideWorkspaceFolder(normalizedServerId);
   const markdownPathOpener = useMemo(
     () =>
       createInlinePathOpener({
@@ -3689,8 +3792,15 @@ function WorkspaceScreenContent({
         client,
         openFile: openMarkdownFile,
         openDirectory: openMarkdownDirectory,
+        openOutsideDirectory: openMarkdownOutsideDirectory,
       }),
-    [workspaceDirectory, client, openMarkdownFile, openMarkdownDirectory],
+    [
+      workspaceDirectory,
+      client,
+      openMarkdownFile,
+      openMarkdownDirectory,
+      openMarkdownOutsideDirectory,
+    ],
   );
   useEffect(() => {
     if (!isRouteFocused) markdownPathOpener.cancel();
@@ -3758,8 +3868,13 @@ function WorkspaceScreenContent({
     return gatedWorkspaceScreen;
   }
   return (
-    <WorkspaceContentProviders key={persistenceKey} workspaceKey={persistenceKey}>
-      <AssistantFileLinkResolverProvider
+    <WorkspaceContentProviders
+      key={persistenceKey}
+      workspaceKey={persistenceKey}
+      sheetPaneHost={sheetPaneHost}
+    >
+      <WorkspaceMarkdownLinks
+        workspace={workspaceDescriptor}
         client={client}
         serverId={normalizedServerId}
         workspaceRoot={workspaceDirectory ?? undefined}
@@ -3767,11 +3882,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-sheet-environment.tsx b/packages/app/src/screens/workspace/workspace-sheet-environment.tsx
deleted file mode 100644
index 1f9fc72d8d..0000000000
--- a/packages/app/src/screens/workspace/workspace-sheet-environment.tsx
+++ /dev/null
@@ -1,38 +0,0 @@
-import React, { useCallback, useContext } from "react";
-import { NavigationContext, NavigationRouteContext } from "expo-router/react-navigation";
-import { useAssistantFileLinkEnvironmentBridge } from "@/assistant-file-links";
-import { useComposerEditingEnvironmentBridge } from "@/composer/editing-session";
-import { RetainedPanelActivity, useRetainedPanelActive } from "@/components/retained-panel";
-import type { ContextBridge } from "@/components/ui/isolated-bottom-sheet-modal";
-import { useDiffDocumentWorkspaceCacheBridge } from "@/git/diff-document/workspace-cache";
-import { HostRouteProvider, useHostRouteServerId } from "@/navigation/host-route-context";
-
-/** The environment of the built-in compact panels; pane identity is supplied by their body. */
-export function useWorkspaceSheetEnvironment(): ContextBridge {
-  const editing = useComposerEditingEnvironmentBridge();
-  const cache = useDiffDocumentWorkspaceCacheBridge();
-  const files = useAssistantFileLinkEnvironmentBridge();
-  const active = useRetainedPanelActive();
-  const serverId = useHostRouteServerId();
-  const navigation = useContext(NavigationContext);
-  const route = useContext(NavigationRouteContext);
-  return useCallback(
-    (children) => {
-      const content = editing(cache(files(children)));
-      return (
-        <NavigationContext.Provider value={navigation}>
-          <NavigationRouteContext.Provider value={route}>
-            <RetainedPanelActivity active={active}>
-              {serverId ? (
-                <HostRouteProvider serverId={serverId}>{content}</HostRouteProvider>
-              ) : (
-                content
-              )}
-            </RetainedPanelActivity>
-          </NavigationRouteContext.Provider>
-        </NavigationContext.Provider>
-      );
-    },
-    [editing, cache, files, active, serverId, navigation, route],
-  );
-}
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/screens/workspace/workspace-tab-presentation.tsx b/packages/app/src/screens/workspace/workspace-tab-presentation.tsx
index fb73376b8b..03f0254099 100644
--- a/packages/app/src/screens/workspace/workspace-tab-presentation.tsx
+++ b/packages/app/src/screens/workspace/workspace-tab-presentation.tsx
@@ -6,7 +6,6 @@ import { Check } from "lucide-react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useTranslation } from "react-i18next";
 import invariant from "tiny-invariant";
-import { ensurePanelsRegistered } from "@/panels/register-panels";
 import { getPanelRegistration, type PanelIconProps } from "@/panels/panel-registry";
 import type { WorkspaceTabDescriptor } from "@/screens/workspace/workspace-tabs-types";
 import type { SidebarStateBucket } from "@/utils/sidebar-agent-state";
@@ -43,7 +42,6 @@ export function WorkspaceTabPresentationResolver({
   workspaceId,
   children,
 }: WorkspaceTabPresentationResolverProps): ReactElement {
-  ensurePanelsRegistered();
   const registration = getPanelRegistration(tab.kind);
   invariant(registration, `No panel registration for kind: ${tab.kind}`);
 
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..c3cf58a3bd 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(
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..6d94ed81a3 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";
@@ -33,13 +29,12 @@ export interface NavigateToWorkspaceInput {
 
 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 +99,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..7c52269e07 100644
--- a/packages/app/src/stores/session-store.ts
+++ b/packages/app/src/stores/session-store.ts
@@ -74,6 +74,7 @@ export interface Agent {
   id: string;
   provider: AgentProvider;
   status: AgentLifecycleStatus;
+  backgroundWork?: { count: number };
   turn: TurnLiveness;
   createdAt: Date;
   updatedAt: Date;
@@ -97,12 +98,15 @@ export interface Agent {
   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>;
   projectPlacement?: ProjectPlacementPayload | null;
 }
 
 export interface WorkspaceDescriptor {
+  parentWorkspaceId?: string;
   createdAt: Date | null;
   lastUserMessageAt: Date | null;
   id: string;
@@ -160,6 +164,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 +265,7 @@ interface ExplorerRequestState {
 }
 
 export interface AgentFileExplorerState {
+  listingGeneration: number;
   directories: Map<string, ExplorerDirectory>;
   isLoading: boolean;
   lastError: string | null;
diff --git a/packages/app/src/stores/workspace-layout-store.test.ts b/packages/app/src/stores/workspace-layout-store.test.ts
index 431d550823..2c3e6f15a4 100644
--- a/packages/app/src/stores/workspace-layout-store.test.ts
+++ b/packages/app/src/stores/workspace-layout-store.test.ts
@@ -41,6 +41,7 @@ import {
   normalizeLayout,
   removePaneFromTree,
   removeTabFromTree,
+  selectSheetTab,
   stripEphemeralTabsFromLayout,
   type SplitNode,
   type SplitPane,
@@ -173,7 +174,6 @@ it("feeds restored layout to timeline sync as a release signal, not a subscripti
     fetchLatestTail: async () => ({ hasNewer: false, endCursor: null }),
     onCatchUpEnded: () => undefined,
     reportError: () => undefined,
-    schedule: () => () => undefined,
   });
   // The edge session-context.tsx owns. Pointing it at subscription instead would resume every
   // agent behind a restored tab on the daemon.
@@ -4496,6 +4496,12 @@ describe("compact workspace sheet", () => {
     return store.getState().sheetsByWorkspace[workspaceKey]?.at(-1);
   }
 
+  function requireTopSheet(store: ReturnType<typeof createCompactStore>) {
+    const sheet = topSheet(store);
+    if (!sheet) throw new Error("Expected a sheet");
+    return sheet;
+  }
+
   function sheetTargets(store: ReturnType<typeof createCompactStore>) {
     return (store.getState().sheetsByWorkspace[workspaceKey] ?? []).map(
       (sheet) => sheet.tab.target,
@@ -4647,7 +4653,7 @@ describe("compact workspace sheet", () => {
       .getState()
       .openTab({ workspaceKey, target: { kind: "file", path: "src/other.ts" }, intent: "reveal" });
 
-    store.getState().openSheetAsTab(workspaceKey, nextTabId ?? "");
+    store.getState().openTabInFront(workspaceKey, requireTopSheet(store));
 
     expect(sheetTargets(store)).toEqual([]);
     expect(tabKinds(store)).toEqual(["terminal", "file"]);
@@ -4683,7 +4689,7 @@ describe("compact workspace sheet", () => {
     if (!sheetTabId) throw new Error("Expected a sheet tab");
     store.getState().setTabState(workspaceKey, sheetTabId, { scrollTop: 120 });
 
-    const tabId = store.getState().openSheetAsTab(workspaceKey, sheetTabId);
+    const tabId = store.getState().openTabInFront(workspaceKey, requireTopSheet(store));
 
     expect(tabId).toBe(sheetTabId);
     expect(topSheet(store)).toBeUndefined();
@@ -4787,6 +4793,40 @@ describe("compact workspace sheet", () => {
     expect(tabKinds(store)).toEqual(["terminal", "agent", "agent"]);
   });
 
+  it("describes the sheet a reveal would show without opening it, and opens it as a tab", () => {
+    seedAgents([
+      { id: "root", parentAgentId: null, workspaceId: "sheet-ws" },
+      { id: "child", parentAgentId: "root", workspaceId: "sheet-ws" },
+    ]);
+    const store = createCompactStore();
+    const rootTabId = store
+      .getState()
+      .openTab({ workspaceKey, target: { kind: "agent", agentId: "root" }, intent: "reveal" });
+
+    const sheet = selectSheetTab(store.getState(), {
+      workspaceKey,
+      target: { kind: "agent", agentId: "child" },
+      parentTabId: rootTabId ?? undefined,
+    });
+    expect(sheet?.parentTabId).toBe(rootTabId);
+    expect(
+      selectSheetTab(store.getState(), {
+        workspaceKey,
+        target: { kind: "agent", agentId: "root" },
+      }),
+    ).toBeNull();
+    expect(topSheet(store)).toBeUndefined();
+    if (!sheet) throw new Error("Expected a sheet tab");
+
+    const tabId = store.getState().openTabInFront(workspaceKey, sheet);
+
+    expect(tabId).toBe(sheet.tab.tabId);
+    expect(topSheet(store)).toBeUndefined();
+    const layout = store.getState().layoutByWorkspace[workspaceKey];
+    expect(findPaneById(layout.root, "main")?.focusedTabId).toBe(tabId);
+    expect(layout.parentTabIdByTabId?.[tabId ?? ""]).toBe(rootTabId);
+  });
+
   it("gives a sheet target opened from inside the sheet the sheet's own parent", () => {
     seedAgents([
       { id: "root", parentAgentId: null, workspaceId: "sheet-ws" },
@@ -4811,7 +4851,7 @@ describe("compact workspace sheet", () => {
     });
     expect(topSheet(store)?.parentTabId).toBe(rootTabId);
 
-    store.getState().openSheetAsTab(workspaceKey, fileSheetTabId ?? "");
+    store.getState().openTabInFront(workspaceKey, requireTopSheet(store));
     const layout = store.getState().layoutByWorkspace[workspaceKey];
     expect(layout.parentTabIdByTabId?.[fileSheetTabId ?? ""]).toBe(rootTabId);
   });
@@ -5204,3 +5244,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 1c0b7a5037..f66650c7ca 100644
--- a/packages/app/src/stores/workspace-layout-store.ts
+++ b/packages/app/src/stores/workspace-layout-store.ts
@@ -128,6 +128,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;
@@ -156,13 +158,12 @@ interface WorkspaceLayoutStore {
    * `compactSheet` opens in a sheet; the returned tab id is the sheet tab's id.
    */
   openTab: (input: OpenWorkspaceTabInput) => string | null;
-  /** Whether `openTab` with this input would show the target in a sheet. */
-  opensInSheet: (
-    input: Pick<OpenWorkspaceTabInput, "workspaceKey" | "target" | "intent">,
-  ) => boolean;
   setLayoutMode: (mode: WorkspaceLayoutMode) => void;
-  /** Moves a sheet's tab, keeping its tab id, into the focused pane. */
-  openSheetAsTab: (workspaceKey: string, tabId: string) => string | null;
+  /**
+   * Moves a sheet's tab, keeping its tab id, into the focused pane and dismisses the sheets that
+   * would cover it. The sheet need not be one of the workspace's sheet tabs.
+   */
+  openTabInFront: (workspaceKey: string, sheet: SheetTab) => string | null;
   /** Placement resolves lazily so an already acknowledged workspace never creates a side pane. */
   autoOpenPullRequestTab: (
     workspaceKey: string,
@@ -211,6 +212,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;
@@ -521,6 +523,29 @@ export function selectExplorerSidebarPaneId(
   return resolveExplorerSidebarPaneId(layout, state.explorerSidebarPaneIdByWorkspace[workspaceKey]);
 }
 
+/**
+ * The sheet tab a reveal of this target would show, or null when it opens as a tab. A caller
+ * that hosts the sheet itself (a list showing it in place) renders this without opening it.
+ */
+export function selectSheetTab(
+  state: Pick<WorkspaceLayoutStore, "layoutMode" | "layoutByWorkspace" | "sheetsByWorkspace">,
+  input: Pick<OpenWorkspaceTabInput, "workspaceKey" | "target" | "parentTabId">,
+): SheetTab | null {
+  const workspaceKey = trimNonEmpty(input.workspaceKey);
+  const target = normalizeWorkspaceTabTarget(input.target);
+  if (!workspaceKey || !target) return null;
+  const policy = resolveSheetPolicy(state, workspaceKey, target, "reveal");
+  if (!policy) return null;
+  return placeTargetInSheet({
+    kept: undefined,
+    target,
+    intent: "reveal",
+    policy,
+    parentTabId: resolveOpenParentTabId(state, workspaceKey, input.parentTabId),
+    state: undefined,
+  });
+}
+
 /** A workspace's panes give up keyboard focus while focus is parked or the sheet covers them. */
 export function selectPaneFocusSuspended(
   state: Pick<WorkspaceLayoutStore, "focusRestorationByWorkspace" | "sheetsByWorkspace">,
@@ -822,10 +847,8 @@ function placeTargetInSheet(input: {
 function promoteSheetToTab(
   state: WorkspaceLayoutStore,
   workspaceKey: string,
-  tabId: string,
+  sheet: SheetTab,
 ): { tabId: string; patch: Partial<WorkspaceLayoutStore> } | null {
-  const sheet = findSheet(state, workspaceKey, tabId);
-  if (!sheet) return null;
   const { tab } = sheet;
   const placement = getOpenTabPlacement(state, workspaceKey, tab.target, FOCUSED_PANE_PLACEMENT);
   const input = {
@@ -910,9 +933,9 @@ function dismissSheets(
 function openSheetTabInFront(
   state: WorkspaceLayoutStore,
   workspaceKey: string,
-  tabId: string,
+  sheet: SheetTab,
 ): { tabId: string; patch: Partial<WorkspaceLayoutStore> } | null {
-  const promoted = promoteSheetToTab(state, workspaceKey, tabId);
+  const promoted = promoteSheetToTab(state, workspaceKey, sheet);
   if (!promoted) return null;
   const next = { ...state, ...promoted.patch };
   return {
@@ -1063,6 +1086,7 @@ export function createWorkspaceLayoutStore(
         },
         layoutMode: "split-panes",
         sheetsByWorkspace: {},
+        focusRequest: null,
         layoutByWorkspace: {},
         splitSizesByWorkspace: {},
         explorerSidebarWidthByWorkspace: {},
@@ -1115,6 +1139,7 @@ export function createWorkspaceLayoutStore(
                   });
             set((state) => ({
               ...withSheets(state, normalizedWorkspaceKey, next),
+              focusRequest: { workspaceKey: normalizedWorkspaceKey, tabId: sheet.tab.tabId },
               ...advancePanelRevision(
                 state,
                 normalizedWorkspaceKey,
@@ -1178,6 +1203,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:
@@ -1208,15 +1236,6 @@ export function createWorkspaceLayoutStore(
           }));
           return result.tabId;
         },
-        opensInSheet: (input) => {
-          const normalizedWorkspaceKey = trimNonEmpty(input.workspaceKey);
-          const normalizedTarget = normalizeWorkspaceTabTarget(input.target);
-          if (!normalizedWorkspaceKey || !normalizedTarget) return false;
-          return (
-            resolveSheetPlacement(get(), normalizedWorkspaceKey, normalizedTarget, input.intent) !==
-            null
-          );
-        },
         setLayoutMode: (mode) => {
           set((state) => {
             if (state.layoutMode === mode) return state;
@@ -1225,7 +1244,7 @@ export function createWorkspaceLayoutStore(
             const next: WorkspaceLayoutStore = { ...state, layoutMode: mode };
             for (const [workspaceKey, sheets] of Object.entries(state.sheetsByWorkspace)) {
               for (const sheet of sheets) {
-                const promoted = promoteSheetToTab(next, workspaceKey, sheet.tab.tabId);
+                const promoted = promoteSheetToTab(next, workspaceKey, sheet);
                 Object.assign(
                   next,
                   promoted?.patch ?? withoutSheet(next, workspaceKey, sheet.tab.tabId),
@@ -1235,11 +1254,10 @@ export function createWorkspaceLayoutStore(
             return next;
           });
         },
-        openSheetAsTab: (workspaceKey, tabId) => {
+        openTabInFront: (workspaceKey, sheet) => {
           const normalizedWorkspaceKey = trimNonEmpty(workspaceKey);
-          const normalizedTabId = trimNonEmpty(tabId);
-          if (!normalizedWorkspaceKey || !normalizedTabId) return null;
-          const promoted = openSheetTabInFront(get(), normalizedWorkspaceKey, normalizedTabId);
+          if (!normalizedWorkspaceKey) return null;
+          const promoted = openSheetTabInFront(get(), normalizedWorkspaceKey, sheet);
           if (!promoted) return null;
           set(promoted.patch);
           return promoted.tabId;
@@ -1496,18 +1514,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,
             };
           });
         },
@@ -1525,13 +1541,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;
@@ -1569,7 +1587,10 @@ export function createWorkspaceLayoutStore(
               return normalizedTabId;
             }
             // A target sheets do not host becomes the tab it would have opened as.
-            const promoted = openSheetTabInFront(next, normalizedWorkspaceKey, normalizedTabId);
+            const retargeted = findSheet(next, normalizedWorkspaceKey, normalizedTabId);
+            const promoted = retargeted
+              ? openSheetTabInFront(next, normalizedWorkspaceKey, retargeted)
+              : null;
             set(promoted?.patch ?? withoutSheet(next, normalizedWorkspaceKey, normalizedTabId));
             return promoted?.tabId ?? null;
           }
@@ -1958,6 +1979,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);
@@ -1978,16 +2006,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/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/styles/unistyles.ts b/packages/app/src/styles/unistyles.ts
index 407faafdf6..96510c59f2 100644
--- a/packages/app/src/styles/unistyles.ts
+++ b/packages/app/src/styles/unistyles.ts
@@ -6,8 +6,7 @@ StyleSheet.configure({
   breakpoints: {
     xs: 0,
     sm: 576,
-    medium: 600,
-    md: 720,
+    md: 600,
     lg: 992,
     xl: 1200,
   },
@@ -22,7 +21,6 @@ type AppThemes = typeof REGISTERED_THEMES;
 interface AppBreakpoints {
   xs: number;
   sm: number;
-  medium: number;
   md: number;
   lg: number;
   xl: number;
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 6c539931e1..cd8ee753fb 100644
--- a/packages/app/src/subagents/index.ts
+++ b/packages/app/src/subagents/index.ts
@@ -9,4 +9,5 @@ export {
   type ArchiveFinishedStatus,
   type UseArchiveFinishedSubagentsInput,
 } from "./use-archive-finished";
-export { useSubagentOpensInSheet } from "./opens-in-sheet";
+export { useSubagentSheetTab } from "./sheet-tab";
+export { deriveSubagentStatusBucket } from "./track-presentation";
diff --git a/packages/app/src/subagents/opens-in-sheet.ts b/packages/app/src/subagents/opens-in-sheet.ts
deleted file mode 100644
index 26432ea039..0000000000
--- a/packages/app/src/subagents/opens-in-sheet.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import { useWorkspaceLayoutStore } from "@/stores/workspace-layout-store";
-import type { WorkspaceTabTarget } from "@/workspace-tabs/model";
-import type { SubagentRow } from "./select";
-
-/** The workspace target a subagent row opens. */
-export function subagentRowTarget(row: SubagentRow): WorkspaceTabTarget {
-  return row.kind === "provider"
-    ? { kind: "provider_subagent", parentAgentId: row.parentAgentId, subagentId: row.id }
-    : { kind: "agent", agentId: row.id };
-}
-
-/** Answers, per subagent row, whether opening it in this workspace shows a sheet rather than a tab. */
-export function useSubagentOpensInSheet(
-  workspaceKey: string | null,
-): (row: SubagentRow) => boolean {
-  // The rows render the answer, so this subscribes to what the answer reads: the layout mode and
-  // the workspace's tabs. A subagent already open as a tab reveals that tab instead of a sheet,
-  // and a row rendered while that tab existed must re-render once it closes, or choosing the row
-  // would still close the list it sits in.
-  useWorkspaceLayoutStore((state) => state.layoutMode);
-  useWorkspaceLayoutStore((state) =>
-    workspaceKey ? state.layoutByWorkspace[workspaceKey] : undefined,
-  );
-  return (row) =>
-    workspaceKey !== null &&
-    useWorkspaceLayoutStore
-      .getState()
-      .opensInSheet({ workspaceKey, target: subagentRowTarget(row), intent: "reveal" });
-}
diff --git a/packages/app/src/subagents/parent/callout.tsx b/packages/app/src/subagents/parent/callout.tsx
index f76e1267e3..d1bb31204a 100644
--- a/packages/app/src/subagents/parent/callout.tsx
+++ b/packages/app/src/subagents/parent/callout.tsx
@@ -3,8 +3,8 @@ import { Text, View } from "react-native";
 import { useTranslation } from "react-i18next";
 import { CornerUpLeft } from "lucide-react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
+import { StatusIcon } from "@/components/status-icon";
 import { Button } from "@/components/ui/button";
-import { ComposerTrackMark } from "@/composer/tracks";
 import { FOOTER_HEIGHT } from "@/constants/layout";
 import type { Theme } from "@/styles/theme";
 import { useParentAgent, type ParentAgent } from "./use-parent-agent";
@@ -22,6 +22,7 @@ function ParentIcon({
 }
 
 const ThemedParentIcon = withUnistyles(ParentIcon);
+const ICON_SIZE = 16;
 const foregroundColorMapping = (theme: Theme) => ({ color: theme.colors.foreground });
 
 /** Stands in the composer's place on a subagent shown without one: who the parent is, and the way back. */
@@ -38,20 +39,13 @@ export function ParentAgentCallout({
   return (
     <View style={styles.rail}>
       <View style={styles.callout} testID="parent-agent-callout">
-        <View style={styles.avatar}>
-          <ThemedParentIcon icon={parent.icon} size={18} uniProps={foregroundColorMapping} />
-        </View>
-        <View style={styles.body}>
-          <Text style={styles.eyebrow}>{t("subagents.parent.parent")}</Text>
-          <View style={styles.titleRow}>
-            <Text style={styles.title} numberOfLines={1}>
-              {parent.label ?? t("subagents.parent.parentAgent")}
-            </Text>
-            <ComposerTrackMark bucket={parent.statusBucket} />
-          </View>
-        </View>
+        <StatusIcon statusBucket={parent.statusBucket} size={ICON_SIZE} backdrop="surface1">
+          <ThemedParentIcon icon={parent.icon} size={ICON_SIZE} uniProps={foregroundColorMapping} />
+        </StatusIcon>
+        <Text style={styles.title} numberOfLines={1}>
+          {parent.label ?? t("subagents.parent.parentAgent")}
+        </Text>
         <Button
-          size="sm"
           variant="secondary"
           leftIcon={CornerUpLeft}
           onPress={parent.open}
@@ -65,11 +59,13 @@ export function ParentAgentCallout({
 }
 
 const styles = StyleSheet.create((theme) => ({
+  // The composer's rail, so the callout sits where the composer would.
   rail: {
     minHeight: FOOTER_HEIGHT,
     alignItems: "center",
     width: "100%",
-    padding: theme.spacing[4],
+    paddingHorizontal: theme.spacing[4],
+    paddingBottom: theme.spacing[4],
   },
   callout: {
     width: "100%",
@@ -84,31 +80,10 @@ const styles = StyleSheet.create((theme) => ({
     padding: theme.spacing[3],
     paddingRight: { xs: theme.spacing[3], md: theme.spacing[4] },
   },
-  avatar: {
-    width: 36,
-    height: 36,
-    borderRadius: theme.borderRadius.lg,
-    backgroundColor: theme.colors.surface2,
-    alignItems: "center",
-    justifyContent: "center",
-  },
-  body: {
+  // Shrinks before the button does, so Open parent never wraps or leaves the row.
+  title: {
     flex: 1,
     minWidth: 0,
-    gap: theme.spacing[0.5],
-  },
-  eyebrow: {
-    fontSize: theme.fontSize.sm,
-    color: theme.colors.foregroundMuted,
-  },
-  titleRow: {
-    flexDirection: "row",
-    alignItems: "center",
-    gap: theme.spacing[2],
-    minWidth: 0,
-  },
-  title: {
-    flexShrink: 1,
     fontSize: theme.fontSize.base,
     fontWeight: theme.fontWeight.medium,
     color: theme.colors.foreground,
diff --git a/packages/app/src/subagents/parent/use-parent-agent.ts b/packages/app/src/subagents/parent/use-parent-agent.ts
index e3916e6bbe..86f9db06cb 100644
--- a/packages/app/src/subagents/parent/use-parent-agent.ts
+++ b/packages/app/src/subagents/parent/use-parent-agent.ts
@@ -1,6 +1,7 @@
 import { useCallback } from "react";
 import { useAgentDescriptor } from "@/agent-presentation";
 import type { PanelDescriptor } from "@/panels/panel-registry";
+import { useLeaveSheet } from "@/screens/workspace/sheet-pane";
 import { useSessionStore } from "@/stores/session-store";
 import type { SidebarStateBucket } from "@/utils/sidebar-agent-state";
 import { navigateToAgent } from "@/utils/navigate-to-agent";
@@ -25,10 +26,14 @@ export function useParentAgentId(serverId: string, agentId: string): string | nu
 /** The parent as its own tab presents it, and the way back to it. */
 export function useParentAgent(serverId: string, parentAgentId: string): ParentAgent {
   const descriptor = useAgentDescriptor({ kind: "agent", agentId: parentAgentId }, { serverId });
-  // The parent may live in another workspace; navigateToAgent opens it wherever it is.
+  const leaveSheet = useLeaveSheet();
+  // Going back to the parent leaves the sheet the child is shown in. When the child was chosen
+  // from the parent's list, closing the sheet already uncovers the parent; otherwise the parent
+  // may live anywhere, even another workspace, and navigateToAgent opens it wherever it is.
   const open = useCallback(() => {
+    if (leaveSheet({ kind: "agent", agentId: parentAgentId })) return;
     navigateToAgent({ serverId, agentId: parentAgentId });
-  }, [parentAgentId, serverId]);
+  }, [leaveSheet, parentAgentId, serverId]);
   return {
     label: descriptor.label || null,
     icon: descriptor.icon,
diff --git a/packages/app/src/subagents/select.test.ts b/packages/app/src/subagents/select.test.ts
index c9d7ca4096..a9d8ce4152 100644
--- a/packages/app/src/subagents/select.test.ts
+++ b/packages/app/src/subagents/select.test.ts
@@ -246,6 +246,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 +354,7 @@ describe("selectSubagentsForParent", () => {
         provider: "claude",
         title: "Review child",
         status: "running",
+        backgroundWork: { count: 1 },
         requiresAttention: true,
         createdAt,
         model: "should-not-leak",
@@ -364,6 +381,7 @@ describe("selectSubagentsForParent", () => {
         description: null,
         subtitle: null,
         status: "running",
+        backgroundWork: { count: 1 },
         turn: { phase: "idle", cancellationRequestId: null },
         requiresAttention: true,
         createdAt,
@@ -371,6 +389,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/opens-in-sheet.test.tsx b/packages/app/src/subagents/sheet-tab.test.tsx
similarity index 80%
rename from packages/app/src/subagents/opens-in-sheet.test.tsx
rename to packages/app/src/subagents/sheet-tab.test.tsx
index c9b915f787..e295f7b7c7 100644
--- a/packages/app/src/subagents/opens-in-sheet.test.tsx
+++ b/packages/app/src/subagents/sheet-tab.test.tsx
@@ -9,7 +9,7 @@ import { useSessionStore, type Agent } from "@/stores/session-store";
 import { normalizeAgentSnapshot, projectAgentSnapshot } from "@/utils/agent-snapshots";
 import { useWorkspaceLayoutStore } from "@/stores/workspace-layout-store";
 import { buildWorkspaceTabPersistenceKey } from "@/workspace-tabs/model";
-import { useSubagentOpensInSheet } from "./opens-in-sheet";
+import { useSubagentSheetTab } from "./sheet-tab";
 import { selectSubagentsForParent, type SubagentRow } from "./select";
 
 vi.mock("@react-native-async-storage/async-storage", () => {
@@ -116,28 +116,40 @@ afterEach(() => {
   });
 });
 
-describe("useSubagentOpensInSheet", () => {
-  it("re-renders the row's answer as the child's tab opens and closes", () => {
+describe("useSubagentSheetTab", () => {
+  it("re-renders the row's sheet as the child's tab opens and closes", () => {
     const row = seedParentWithChild();
     const store = useWorkspaceLayoutStore.getState();
     store.setLayoutMode("compact");
-    const target = { kind: "agent", agentId: "child" } as const;
 
     // The row renders its answer, as the track does, so a stale render is a stale answer.
-    const { result } = renderHook(() => useSubagentOpensInSheet(workspaceKey)(row));
-    expect(result.current).toBe(true);
+    const { result } = renderHook(() => useSubagentSheetTab(workspaceKey, "parent-tab")(row));
+    expect(result.current?.tab.target).toEqual({ kind: "agent", agentId: "child" });
 
     let tabId: string | null = null;
     act(() => {
-      const sheetTabId = store.openTab({ workspaceKey, target, intent: "reveal" });
-      tabId = sheetTabId ? store.openSheetAsTab(workspaceKey, sheetTabId) : null;
+      tabId = result.current ? store.openTabInFront(workspaceKey, result.current) : null;
     });
     expect(tabId).not.toBeNull();
-    expect(result.current).toBe(false);
+    expect(result.current).toBeNull();
 
     act(() => {
       store.closeTab(workspaceKey, tabId ?? "");
     });
-    expect(result.current).toBe(true);
+    expect(result.current?.tab.tabId).toBe(tabId);
+  });
+
+  it("hands a re-rendered row the same sheet", () => {
+    const row = seedParentWithChild();
+    useWorkspaceLayoutStore.getState().setLayoutMode("compact");
+
+    const { result, rerender } = renderHook(() =>
+      useSubagentSheetTab(workspaceKey, "parent-tab")(row),
+    );
+    const first = result.current;
+    rerender();
+
+    expect(first).not.toBeNull();
+    expect(result.current).toBe(first);
   });
 });
diff --git a/packages/app/src/subagents/sheet-tab.ts b/packages/app/src/subagents/sheet-tab.ts
new file mode 100644
index 0000000000..c81be94ced
--- /dev/null
+++ b/packages/app/src/subagents/sheet-tab.ts
@@ -0,0 +1,58 @@
+import { useMemo } from "react";
+import {
+  selectSheetTab,
+  useWorkspaceLayoutStore,
+  type SheetTab,
+} from "@/stores/workspace-layout-store";
+import type { WorkspaceTabTarget } from "@/workspace-tabs/model";
+import type { SubagentRow } from "./select";
+
+/** The workspace target a subagent row opens. */
+export function subagentRowTarget(row: SubagentRow): WorkspaceTabTarget {
+  return row.kind === "provider"
+    ? { kind: "provider_subagent", parentAgentId: row.parentAgentId, subagentId: row.id }
+    : { kind: "agent", agentId: row.id };
+}
+
+/**
+ * Answers, per subagent row, the sheet that shows it in place of the list, or null when choosing
+ * it reveals a tab instead. `parentTabId` is the tab of the pane the list belongs to.
+ */
+export function useSubagentSheetTab(
+  workspaceKey: string | null,
+  parentTabId: string,
+): (row: SubagentRow) => SheetTab | null {
+  // The rows render the answer, so this subscribes to everything the answer reads. A subagent
+  // already open as a tab reveals that tab instead, and a row rendered while that tab existed
+  // must re-render once it closes.
+  const layoutMode = useWorkspaceLayoutStore((state) => state.layoutMode);
+  const layout = useWorkspaceLayoutStore((state) =>
+    workspaceKey ? state.layoutByWorkspace[workspaceKey] : undefined,
+  );
+  const sheets = useWorkspaceLayoutStore((state) =>
+    workspaceKey ? state.sheetsByWorkspace[workspaceKey] : undefined,
+  );
+  return useMemo(() => {
+    // One answer per row until the state it reads changes, so a re-render of the list hands an
+    // open sheet the same tab rather than a fresh one.
+    const answers = new Map<string, SheetTab | null>();
+    return (row) => {
+      if (!workspaceKey) return null;
+      const state = {
+        layoutMode,
+        layoutByWorkspace: layout ? { [workspaceKey]: layout } : {},
+        sheetsByWorkspace: sheets ? { [workspaceKey]: sheets } : {},
+      };
+      const key = `${row.kind}:${row.id}`;
+      const known = answers.get(key);
+      if (known !== undefined) return known;
+      const sheet = selectSheetTab(state, {
+        workspaceKey,
+        target: subagentRowTarget(row),
+        parentTabId,
+      });
+      answers.set(key, sheet);
+      return sheet;
+    };
+  }, [layout, layoutMode, parentTabId, sheets, workspaceKey]);
+}
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/subagents/track.tsx b/packages/app/src/subagents/track.tsx
index d759da431e..dd8c088e63 100644
--- a/packages/app/src/subagents/track.tsx
+++ b/packages/app/src/subagents/track.tsx
@@ -18,6 +18,8 @@ import {
 import type { Theme } from "@/styles/theme";
 import { useAgentFactsLine } from "@/panels/agent-facts-line";
 import { getPanelManifest } from "@/panels/panel-manifest";
+import { useSheetPanePage } from "@/screens/workspace/sheet-pane";
+import type { SheetTab } from "@/stores/workspace-layout-store";
 import type { SubagentRow } from "./select";
 import type { ArchiveFinishedStatus } from "./use-archive-finished";
 import {
@@ -40,10 +42,10 @@ export interface SubagentsTrackProps {
   onOpenSubagent: (address: AgentAddress) => void;
   onOpenProviderSubagent: (parentAgentId: string, subagentId: string) => void;
   /**
-   * Whether opening this row shows it in a sheet. A sheet stacks over the list and uncovers it on
-   * close, so the list stays open; a tab replaces the list's pane, so choosing it ends the list.
+   * The sheet a row opens, or null when it opens as a tab. A sheet replaces the list in place and
+   * Back returns to it; a tab replaces the list's pane, so choosing it ends the list.
    */
-  opensInSheet: (row: SubagentRow) => boolean;
+  sheetTabFor: (row: SubagentRow) => SheetTab | null;
   onArchiveSubagent: (address: AgentAddress) => void;
   onArchiveFinished?: () => void;
   archiveFinishedStatus?: ArchiveFinishedStatus;
@@ -71,13 +73,14 @@ export function SubagentsTrack({
   rows,
   onOpenSubagent,
   onOpenProviderSubagent,
-  opensInSheet,
+  sheetTabFor,
   onArchiveSubagent,
   onArchiveFinished,
   archiveFinishedStatus = IDLE_ARCHIVE_FINISHED_STATUS,
   onDetachSubagent,
 }: SubagentsTrackProps): ReactElement | null {
   const { t } = useTranslation();
+  const sheetPanePage = useSheetPanePage();
 
   const isArchivingFinished = archiveFinishedStatus.kind === "archiving";
   const isArchiveFinishedFailed = archiveFinishedStatus.kind === "failed";
@@ -88,9 +91,12 @@ export function SubagentsTrack({
   const pill = buildSubagentPillPresentation(t, rows);
   const finishedCount = countFinishedSubagents(rows);
   const showArchiveFinished = finishedCount > 0 || isArchivingFinished || isArchiveFinishedFailed;
+  const sheets = rows.map(sheetTabFor);
+  const pages = sheets.flatMap((sheet) => (sheet ? [sheetPanePage(sheet)] : []));
 
   return (
     <ComposerTrackPill
+      pages={pages}
       testID="subagents-track-header"
       segments={pill.segments}
       accessibilityLabel={pill.accessibilityLabel}
@@ -105,14 +111,14 @@ export function SubagentsTrack({
           />
         </ComposerTrackActions>
       ) : null}
-      {rows.map((row) => (
+      {rows.map((row, index) => (
         <SubagentsTrackRow
           key={row.kind === "paseo" ? `${row.address.serverId}:${row.id}` : row.id}
           row={row}
           serverId={serverId}
           onOpenSubagent={onOpenSubagent}
           onOpenProviderSubagent={onOpenProviderSubagent}
-          opensInSheet={opensInSheet(row)}
+          sheetTabId={sheets[index]?.tab.tabId ?? null}
           onArchiveSubagent={onArchiveSubagent}
           onDetachSubagent={onDetachSubagent}
         />
@@ -184,7 +190,8 @@ interface SubagentsTrackRowProps {
   row: SubagentRow;
   onOpenSubagent: (address: AgentAddress) => void;
   onOpenProviderSubagent: (parentAgentId: string, subagentId: string) => void;
-  opensInSheet: boolean;
+  /** The sheet page the row opens in place of the list, when it opens in a sheet. */
+  sheetTabId: string | null;
   onArchiveSubagent: (address: AgentAddress) => void;
   onDetachSubagent?: (address: AgentAddress) => void;
 }
@@ -194,7 +201,7 @@ function SubagentsTrackRow({
   row,
   onOpenSubagent,
   onOpenProviderSubagent,
-  opensInSheet,
+  sheetTabId,
   onArchiveSubagent,
   onDetachSubagent,
 }: SubagentsTrackRowProps): ReactElement {
@@ -269,7 +276,7 @@ function SubagentsTrackRow({
     <ComposerTrackRow
       accessibilityLabel={displayLabel}
       testID={`subagents-track-row-${row.id}`}
-      closeOnSelect={!opensInSheet}
+      opensPage={sheetTabId ?? undefined}
       onPress={handlePress}
     >
       {renderRow}
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/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/hooks/use-workspace-terminal-session-retention.ts b/packages/app/src/terminal/hooks/use-workspace-terminal-session-retention.ts
deleted file mode 100644
index 506a5baab3..0000000000
--- a/packages/app/src/terminal/hooks/use-workspace-terminal-session-retention.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { useEffect } from "react";
-import {
-  releaseWorkspaceTerminalSession,
-  retainWorkspaceTerminalSession,
-} from "@/terminal/runtime/workspace-terminal-session";
-
-export function useWorkspaceTerminalSessionRetention(input: { scopeKey: string | null }): void {
-  useEffect(() => {
-    if (!input.scopeKey) {
-      return;
-    }
-
-    retainWorkspaceTerminalSession({ scopeKey: input.scopeKey });
-    return () => {
-      releaseWorkspaceTerminalSession({ scopeKey: input.scopeKey! });
-    };
-  }, [input.scopeKey]);
-}
diff --git a/packages/app/src/terminal/native-renderer/colors.ts b/packages/app/src/terminal/native-renderer/colors.ts
index dfebe4eb4d..3804660b56 100644
--- a/packages/app/src/terminal/native-renderer/colors.ts
+++ b/packages/app/src/terminal/native-renderer/colors.ts
@@ -1,6 +1,6 @@
 import type { ITheme } from "@xterm/xterm";
-import type { TextStyle } from "react-native";
 import type { TerminalCell } from "@getpaseo/protocol/messages";
+import { PASEO_TERMINAL_STYLE_FLAGS } from "../../../modules/paseo-terminal/contract";
 
 import { darkTheme } from "@/styles/theme";
 import { toXtermTheme } from "@/utils/to-xterm-theme";
@@ -29,77 +29,114 @@ const DEFAULT_COLOR_MODE = 0;
 const ANSI_COLOR_MODE = 1;
 const INDEXED_COLOR_MODE = 2;
 const RGB_COLOR_MODE = 3;
-const FLAG_BOLD = 1 << 0;
-const FLAG_ITALIC = 1 << 1;
-const FLAG_UNDERLINE = 1 << 2;
-const FLAG_DIM = 1 << 3;
-const FLAG_INVERSE = 1 << 4;
-const FLAG_STRIKETHROUGH = 1 << 5;
+const OPAQUE_BLACK = 0xff000000;
+const DIM_ALPHA = 0.65;
 
-interface ResolvedCellStyle {
-  key: string;
-  style: TextStyle;
-  foregroundColor: string;
-}
-
-interface ResolvedCellColors {
-  foreground: string;
-  background: string;
-  paintsBackground: boolean;
+/** Colors are unsigned ARGB. A background of 0 is the terminal background. */
+export interface ResolvedCellStyle {
+  foreground: number;
+  background: number;
+  flags: number;
 }
 
 export interface TerminalCellStyleResolver {
-  readonly themeKey: string;
-  readonly backgroundColor: string;
-  readonly cursorColor: string;
+  readonly backgroundColor: number;
+  readonly cursorColor: number;
   resolve(cell: TerminalCell): ResolvedCellStyle;
 }
 
 export const DEFAULT_TERMINAL_THEME = toXtermTheme(darkTheme.colors.terminal);
 
 export const NATIVE_TERMINAL_SELECTION_COLORS = {
-  background: "#ffff00",
-  foreground: "#000000",
+  background: 0x472684ff,
 } as const;
 
-function build256Palette(theme: ITheme): string[] {
-  const palette = Array.from({ length: 256 }, () => "");
+function build256Palette(theme: ITheme): number[] {
+  const palette = Array.from({ length: 256 }, () => OPAQUE_BLACK);
 
   for (let index = 0; index < ANSI_THEME_KEYS.length; index += 1) {
     const key = ANSI_THEME_KEYS[index];
-    palette[index] = theme[key] ?? DEFAULT_TERMINAL_THEME[key] ?? "#000000";
+    palette[index] = parseTerminalColor(theme[key] ?? DEFAULT_TERMINAL_THEME[key], OPAQUE_BLACK);
   }
 
   for (let red = 0; red < CUBE_LEVELS.length; red += 1) {
     for (let green = 0; green < CUBE_LEVELS.length; green += 1) {
       for (let blue = 0; blue < CUBE_LEVELS.length; blue += 1) {
         const index = 16 + red * 36 + green * 6 + blue;
-        palette[index] = `rgb(${CUBE_LEVELS[red]}, ${CUBE_LEVELS[green]}, ${CUBE_LEVELS[blue]})`;
+        palette[index] = rgbColor(
+          (CUBE_LEVELS[red] << 16) | (CUBE_LEVELS[green] << 8) | CUBE_LEVELS[blue],
+        );
       }
     }
   }
 
   for (let index = 0; index < 24; index += 1) {
     const value = 8 + index * 10;
-    palette[232 + index] = `rgb(${value}, ${value}, ${value})`;
+    palette[232 + index] = rgbColor((value << 16) | (value << 8) | value);
   }
 
   return palette;
 }
 
-function rgbColor(value: number): string {
-  const red = (value >> 16) & 0xff;
-  const green = (value >> 8) & 0xff;
-  const blue = value & 0xff;
-  return `rgb(${red}, ${green}, ${blue})`;
+function rgbColor(value: number): number {
+  return (OPAQUE_BLACK | (value & 0xffffff)) >>> 0;
+}
+
+function argb(input: { alpha: number; red: number; green: number; blue: number }): number {
+  const channel = (value: number) => Math.max(0, Math.min(255, Math.round(value)));
+  return (
+    ((channel(input.alpha) << 24) |
+      (channel(input.red) << 16) |
+      (channel(input.green) << 8) |
+      channel(input.blue)) >>>
+    0
+  );
+}
+
+/** Parses the CSS color forms terminal themes use: `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()`. */
+export function parseTerminalColor(value: string | undefined, fallback: number): number {
+  if (!value) return fallback;
+  const color = value.trim().toLowerCase();
+  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/.exec(color)?.[1];
+  if (hex) {
+    const digits = hex.length === 3 ? [...hex].map((digit) => digit + digit).join("") : hex;
+    const channel = (offset: number) => Number.parseInt(digits.slice(offset, offset + 2), 16);
+    return argb({
+      alpha: digits.length === 8 ? channel(6) : 255,
+      red: channel(0),
+      green: channel(2),
+      blue: channel(4),
+    });
+  }
+  const functional = /^rgba?\(([^)]*)\)$/.exec(color)?.[1];
+  if (functional) {
+    const parts = functional
+      .split(/[\s,/]+/)
+      .filter(Boolean)
+      .map(Number);
+    if (parts.length >= 3 && parts.every((part) => Number.isFinite(part))) {
+      return argb({
+        alpha: parts.length >= 4 ? parts[3] * 255 : 255,
+        red: parts[0],
+        green: parts[1],
+        blue: parts[2],
+      });
+    }
+  }
+  return fallback;
+}
+
+function withDimAlpha(color: number): number {
+  const alpha = (color >>> 24) & 0xff;
+  return (((Math.round(alpha * DIM_ALPHA) & 0xff) << 24) | (color & 0xffffff)) >>> 0;
 }
 
 function resolveColor(input: {
   value: number | undefined;
   mode: number | undefined;
-  fallback: string;
-  palette: string[];
-}): string {
+  fallback: number;
+  palette: number[];
+}): number {
   const mode = input.mode ?? DEFAULT_COLOR_MODE;
   const value = input.value ?? 0;
 
@@ -114,131 +151,50 @@ function resolveColor(input: {
 
 function cellFlags(cell: TerminalCell): number {
   let flags = 0;
-  if (cell.bold) flags |= FLAG_BOLD;
-  if (cell.italic) flags |= FLAG_ITALIC;
-  if (cell.underline) flags |= FLAG_UNDERLINE;
-  if (cell.dim) flags |= FLAG_DIM;
-  if (cell.inverse) flags |= FLAG_INVERSE;
-  if (cell.strikethrough) flags |= FLAG_STRIKETHROUGH;
+  if (cell.bold) flags |= PASEO_TERMINAL_STYLE_FLAGS.bold;
+  if (cell.italic) flags |= PASEO_TERMINAL_STYLE_FLAGS.italic;
+  if (cell.underline) flags |= PASEO_TERMINAL_STYLE_FLAGS.underline;
+  if (cell.strikethrough) flags |= PASEO_TERMINAL_STYLE_FLAGS.strikethrough;
+  if (cell.dim) flags |= PASEO_TERMINAL_STYLE_FLAGS.dim;
   return flags;
 }
 
-function resolveCellColors(input: {
-  cell: TerminalCell;
-  palette: string[];
-  foregroundColor: string;
-  backgroundColor: string;
-}): ResolvedCellColors {
-  const foreground = resolveColor({
-    value: input.cell.fg,
-    mode: input.cell.fgMode,
-    fallback: input.foregroundColor,
-    palette: input.palette,
-  });
-  const background = resolveColor({
-    value: input.cell.bg,
-    mode: input.cell.bgMode,
-    fallback: input.backgroundColor,
-    palette: input.palette,
-  });
-
-  const resolvedForeground = input.cell.inverse ? background : foreground;
-  const resolvedBackground = input.cell.inverse ? foreground : background;
-  return {
-    foreground: resolvedForeground,
-    background: resolvedBackground,
-    paintsBackground: resolvedBackground !== input.backgroundColor,
-  };
-}
-
-function textDecorationLine(flags: number): TextStyle["textDecorationLine"] | undefined {
-  const underline = (flags & FLAG_UNDERLINE) !== 0;
-  const strikethrough = (flags & FLAG_STRIKETHROUGH) !== 0;
-  if (underline && strikethrough) return "underline line-through";
-  if (underline) return "underline";
-  if (strikethrough) return "line-through";
-  return undefined;
-}
-
-function createTextStyle(input: {
-  foreground: string;
-  background: string;
-  paintsBackground: boolean;
-  flags: number;
-}): TextStyle {
-  const style: TextStyle = {
-    color: input.foreground,
-  };
-
-  if (input.paintsBackground) {
-    style.backgroundColor = input.background;
-  }
-  if ((input.flags & FLAG_BOLD) !== 0) {
-    style.fontWeight = "700";
-  }
-  if ((input.flags & FLAG_ITALIC) !== 0) {
-    style.fontStyle = "italic";
-  }
-  if ((input.flags & FLAG_DIM) !== 0) {
-    style.opacity = 0.65;
-  }
-
-  const decorationLine = textDecorationLine(input.flags);
-  if (decorationLine) {
-    style.textDecorationLine = decorationLine;
-    style.textDecorationColor = input.foreground;
-  }
-
-  return style;
-}
-
-function buildStyleKey(input: {
-  foreground: string;
-  background: string;
-  paintsBackground: boolean;
-  flags: number;
-}): string {
-  const background = input.paintsBackground ? input.background : "default";
-  return `${input.foreground}|${background}|${input.flags}`;
-}
-
-function buildThemeKey(theme: ITheme): string {
-  return JSON.stringify(theme);
-}
-
 export function createTerminalCellStyleResolver(theme: ITheme): TerminalCellStyleResolver {
   const palette = build256Palette(theme);
-  const foregroundColor = theme.foreground ?? DEFAULT_TERMINAL_THEME.foreground ?? "#fafafa";
-  const backgroundColor = theme.background ?? DEFAULT_TERMINAL_THEME.background ?? "#181B1A";
-  const cursorColor = theme.cursor ?? foregroundColor;
-  const styleCache = new Map<string, TextStyle>();
+  const foregroundColor = parseTerminalColor(
+    theme.foreground ?? DEFAULT_TERMINAL_THEME.foreground,
+    0xfffafafa,
+  );
+  const backgroundColor = parseTerminalColor(
+    theme.background ?? DEFAULT_TERMINAL_THEME.background,
+    0xff181b1a,
+  );
+  const cursorColor = parseTerminalColor(theme.cursor, foregroundColor);
 
   return {
-    themeKey: buildThemeKey(theme),
     backgroundColor,
     cursorColor,
     resolve(cell: TerminalCell): ResolvedCellStyle {
+      const foreground = resolveColor({
+        value: cell.fg,
+        mode: cell.fgMode,
+        fallback: foregroundColor,
+        palette,
+      });
+      const background = resolveColor({
+        value: cell.bg,
+        mode: cell.bgMode,
+        fallback: backgroundColor,
+        palette,
+      });
+      const resolvedForeground = cell.inverse ? background : foreground;
+      const resolvedBackground = cell.inverse ? foreground : background;
       const flags = cellFlags(cell);
-      const colors = resolveCellColors({ cell, palette, foregroundColor, backgroundColor });
-      const key = buildStyleKey({
-        foreground: colors.foreground,
-        background: colors.background,
-        paintsBackground: colors.paintsBackground,
+      return {
+        foreground: cell.dim ? withDimAlpha(resolvedForeground) : resolvedForeground,
+        background: resolvedBackground === backgroundColor ? 0 : resolvedBackground,
         flags,
-      });
-      const cachedStyle = styleCache.get(key);
-      if (cachedStyle) {
-        return { key, style: cachedStyle, foregroundColor: colors.foreground };
-      }
-
-      const style = createTextStyle({
-        foreground: colors.foreground,
-        background: colors.background,
-        paintsBackground: colors.paintsBackground,
-        flags,
-      });
-      styleCache.set(key, style);
-      return { key, style, foregroundColor: colors.foreground };
+      };
     },
   };
 }
diff --git a/packages/app/src/terminal/native-renderer/headless-terminal-output-drain.test.ts b/packages/app/src/terminal/native-renderer/headless-terminal-output-drain.test.ts
index fb94588a01..4d238b98c6 100644
--- a/packages/app/src/terminal/native-renderer/headless-terminal-output-drain.test.ts
+++ b/packages/app/src/terminal/native-renderer/headless-terminal-output-drain.test.ts
@@ -1,8 +1,8 @@
+import { createTerminalResizePolicy, updateTerminalResizePolicy } from "./terminal-resize-policy";
 import { describe, expect, test } from "vitest";
 
 import {
   createNativeHeadlessTerminal,
-  type TerminalCellRow,
   type TerminalViewportState,
 } from "./headless-terminal-state";
 import { createNativeTerminalBenchmarkPayload } from "./native-terminal-benchmark-payload";
@@ -11,7 +11,8 @@ import {
   NATIVE_TERMINAL_PARSE_CHUNK_CHARS,
 } from "./headless-terminal-output-drain";
 import { createNativeTerminalScreenModel, type TerminalScreenState } from "./terminal-screen-model";
-import { renderTerminalSnapshotToAnsi } from "../runtime/terminal-snapshot";
+import { Terminal as ReplaySource } from "@xterm/headless";
+import { SerializeAddon } from "@xterm/addon-serialize";
 
 const ROWS = 12;
 const COLS = 80;
@@ -41,33 +42,6 @@ function createFrameRecorder() {
   };
 }
 
-function lineCells(line: string, cols: number): TerminalCellRow {
-  const cells: TerminalCellRow = [];
-  for (let index = 0; index < cols; index += 1) {
-    cells.push({ char: line[index] ?? " ", width: 1 });
-  }
-  return cells;
-}
-
-function terminalStateFromLines(input: {
-  lines: string[];
-  rows: number;
-  cols: number;
-  cursor: TerminalViewportState["cursor"];
-}) {
-  const grid: TerminalCellRow[] = [];
-  for (let row = 0; row < input.rows; row += 1) {
-    grid.push(lineCells(input.lines[row] ?? "", input.cols));
-  }
-  return {
-    rows: input.rows,
-    cols: input.cols,
-    grid,
-    scrollback: [],
-    cursor: input.cursor,
-  };
-}
-
 async function runScheduledWork(input: {
   callbacks: Array<() => void>;
   flush: Promise<void>;
@@ -80,11 +54,13 @@ async function runScheduledWork(input: {
 }
 
 async function benchmarkSnapshot(lineCount: number) {
-  const terminal = createNativeHeadlessTerminal({ rows: ROWS, cols: COLS, scrollbackLines: 100 });
-  await terminal.write(
-    createNativeTerminalBenchmarkPayload({ startLine: 0, lineCount, cols: COLS }),
-  );
-  return terminal.getState();
+  return {
+    rows: ROWS,
+    cols: COLS,
+    data: new TextEncoder().encode(
+      createNativeTerminalBenchmarkPayload({ startLine: 0, lineCount, cols: COLS }),
+    ),
+  };
 }
 
 function createScreenRestorer(
@@ -94,6 +70,7 @@ function createScreenRestorer(
   const frameRecorder = createFrameRecorder();
   let screen: TerminalScreenState | null = null;
   const drain = createNativeTerminalOutputDrain({
+    restoreSize: () => {},
     write: (chunk) => terminal.write(chunk),
     reset: () => terminal.reset(),
     getViewportState: () => {
@@ -107,7 +84,12 @@ function createScreenRestorer(
 
   return {
     async restore(snapshot: Awaited<ReturnType<typeof benchmarkSnapshot>>) {
-      drain.restoreSnapshot(snapshot);
+      drain.replay({ type: "begin", rows: snapshot.rows, cols: snapshot.cols });
+      drain.replay({
+        type: "data",
+        data: snapshot.data,
+      });
+      drain.replay({ type: "end" });
       await drain.flush();
       frameRecorder.frames[0]?.();
       return screen;
@@ -122,6 +104,7 @@ describe("native terminal output drain", () => {
     const frameRecorder = createFrameRecorder();
     const payload = "x".repeat(NATIVE_TERMINAL_PARSE_CHUNK_CHARS * 2);
     const drain = createNativeTerminalOutputDrain({
+      restoreSize: () => {},
       write: async (chunk) => {
         writes.push(chunk);
       },
@@ -170,6 +153,7 @@ describe("native terminal output drain", () => {
     const paintedStates: TerminalViewportState[] = [];
     const frameRecorder = createFrameRecorder();
     const drain = createNativeTerminalOutputDrain({
+      restoreSize: () => {},
       write: (chunk) => terminal.write(chunk),
       reset: () => terminal.reset(),
       getViewportState: () => terminal.getViewportState(),
@@ -202,6 +186,7 @@ describe("native terminal output drain", () => {
     const scheduledWork: Array<() => void> = [];
     const frameRecorder = createFrameRecorder();
     const drain = createNativeTerminalOutputDrain({
+      restoreSize: () => {},
       write: (chunk) => terminal.write(chunk),
       reset: () => terminal.reset(),
       getViewportState: () => terminal.getViewportState(),
@@ -210,21 +195,22 @@ describe("native terminal output drain", () => {
       scheduleFrame: frameRecorder.scheduleFrame,
       cancelFrame: frameRecorder.cancelFrame,
     });
-    const restoredSnapshot = terminalStateFromLines({
-      rows: 4,
-      cols: 32,
-      lines: ["restored-one", "restored-two"],
-      cursor: { row: 1, col: "restored-two".length },
-    });
+    const restoredCursor = { row: 1, col: "restored-two".length };
+    const replay = new TextEncoder().encode("restored-one\r\nrestored-two");
 
     await terminal.write("old-one\r\nold-two\r\nold-three\r\n");
     drain.enqueueText("stale-queued\r\n");
-    drain.restoreText(renderTerminalSnapshotToAnsi(restoredSnapshot));
+    drain.replay({ type: "begin" });
+    drain.replay({
+      type: "data",
+      data: replay,
+    });
+    drain.replay({ type: "end" });
     await runScheduledWork({ callbacks: scheduledWork, flush: drain.flush() });
 
     const state = terminal.getViewportState();
     expect(state.grid.map(rowText)).toEqual(["restored-one", "restored-two", "", ""]);
-    expect(state.cursor).toEqual(restoredSnapshot.cursor);
+    expect(state.cursor).toEqual(restoredCursor);
   });
 
   test("snapshot restore preserves a scrolled viewport anchor while replacing terminal state", async () => {
@@ -242,7 +228,7 @@ describe("native terminal output drain", () => {
       paintedMode: screen?.scroll.mode,
       paintedTopRow: rowText(screen?.viewport.grid[0] ?? []),
       beforeTopRow,
-      restoredBottomRows: terminal.getState().grid.slice(-2).map(rowText),
+      restoredBottomRows: terminal.getViewportState().grid.slice(-2).map(rowText),
     }).toEqual({
       paintedMode: "scrolled",
       paintedTopRow: beforeTopRow,
@@ -268,3 +254,255 @@ describe("native terminal output drain", () => {
     });
   });
 });
+
+test("replays split Unicode and ANSI with one reset then live output", async () => {
+  const terminal = createNativeHeadlessTerminal({ rows: 4, cols: 40, scrollbackLines: 1000 });
+  let resets = 0;
+  const drain = createNativeTerminalOutputDrain({
+    restoreSize: () => {},
+    write: (text) => terminal.write(text),
+    reset: (size) => {
+      resets++;
+      if (size) terminal.resize(size);
+      terminal.reset();
+    },
+    getViewportState: () => terminal.getViewportState(),
+    onPaint: () => {},
+  });
+  try {
+    drain.replay({ type: "begin", rows: 4, cols: 40, retainedHistoryLines: 400 });
+    const bytes = new TextEncoder().encode("\x1b[31m界🙂 replay\x1b[0m\r\n");
+    for (let i = 0; i < bytes.length; i++)
+      drain.replay({ type: "data", data: bytes.subarray(i, i + 1) });
+    drain.replay({ type: "end" });
+    drain.enqueueText("live");
+    await drain.flush();
+    expect(resets).toBe(1);
+    expect(
+      terminal
+        .getBufferWindow({ startRow: 0, rowCount: 4 })
+        .rows.map((row) =>
+          row
+            .filter((cell) => cell.width !== 0)
+            .map((cell) => cell.char)
+            .join(""),
+        )
+        .join("\n"),
+    ).toContain("界🙂 replay");
+    expect(
+      terminal
+        .getBufferWindow({ startRow: 0, rowCount: 4 })
+        .rows.map((row) =>
+          row
+            .filter((cell) => cell.width !== 0)
+            .map((cell) => cell.char)
+            .join(""),
+        )
+        .join("\n"),
+    ).toContain("live");
+  } finally {
+    drain.dispose();
+    terminal.dispose();
+  }
+});
+
+test("an empty replacement replay resets after an in-flight write finishes", async () => {
+  let finish!: () => void;
+  let started!: () => void;
+  const writing = new Promise<void>((resolve) => {
+    started = resolve;
+  });
+  const blocked = new Promise<void>((resolve) => {
+    finish = resolve;
+  });
+  let resets = 0;
+  const drain = createNativeTerminalOutputDrain({
+    restoreSize: () => {},
+    write: async () => {
+      started();
+      await blocked;
+    },
+    reset: () => {
+      resets++;
+    },
+    getViewportState: () => null,
+    onPaint: () => {},
+  });
+  try {
+    drain.enqueueText("old terminal");
+    await writing;
+    drain.replay({ type: "begin" });
+    drain.replay({ type: "end" });
+    finish();
+    await drain.flush();
+    expect(resets).toBe(1);
+    expect(drain.getQueuedChars()).toBe(0);
+  } finally {
+    finish();
+    drain.dispose();
+  }
+});
+
+test("replay geometry returns to measured layout before live writes and unchanged-layout focus", async () => {
+  const measured = { rows: 24, cols: 40 };
+  const terminal = createNativeHeadlessTerminal({ ...measured, scrollbackLines: 1000 });
+  const policy = createTerminalResizePolicy(measured);
+  const sizes: number[] = [];
+  const drain = createNativeTerminalOutputDrain({
+    write: async (text) => {
+      sizes.push(terminal.getViewportState().cols);
+      await terminal.write(text);
+    },
+    reset: (size) => {
+      if (size) terminal.resize(size);
+      terminal.reset();
+    },
+    restoreSize: () => terminal.resize(measured),
+    getViewportState: () => terminal.getViewportState(),
+    onPaint: () => {},
+  });
+  try {
+    drain.replay({ type: "begin", rows: 30, cols: 120 });
+    drain.replay({ type: "data", data: new TextEncoder().encode("x".repeat(100) + "\r\n") });
+    drain.replay({ type: "end" });
+    drain.enqueueText("LIVE-" + "y".repeat(60));
+    await drain.flush();
+    expect(sizes).toEqual([120, 40]);
+    const focus = updateTerminalResizePolicy(policy, {
+      source: "claim",
+      size: measured,
+      claimToken: 1,
+    });
+    expect(focus.measuredSizeChanged).toBe(false);
+    expect(focus.resizeClaim).toMatchObject(measured);
+    expect(terminal.getViewportState()).toMatchObject(measured);
+    expect(terminal.getBufferBounds().cols).toBe(40);
+    const lines = terminal
+      .getViewportState()
+      .grid.map((row) =>
+        row
+          .map((cell) => cell.char)
+          .join("")
+          .trimEnd(),
+      )
+      .join("\n");
+    expect(lines).toContain("LIVE-" + "y".repeat(35) + "\n" + "y".repeat(25));
+  } finally {
+    drain.dispose();
+    terminal.dispose();
+  }
+});
+
+test.each(["clear", "replacement", "dispose"] as const)(
+  "cancels queued replay geometry on %s",
+  async (action) => {
+    const local = { rows: 24, cols: 40 };
+    const terminal = createNativeHeadlessTerminal({ ...local, scrollbackLines: 1000 });
+    let finish!: () => void;
+    const block = new Promise<void>((resolve) => {
+      finish = resolve;
+    });
+    let started!: () => void;
+    const writing = new Promise<void>((resolve) => {
+      started = resolve;
+    });
+    let first = true;
+    let restores = 0;
+    const drain = createNativeTerminalOutputDrain({
+      restoreSize: () => {
+        restores++;
+        terminal.resize(local);
+      },
+      reset: (size) => {
+        if (size) terminal.resize(size);
+        terminal.reset();
+      },
+      write: async (text) => {
+        await terminal.write(text);
+        if (first) {
+          first = false;
+          started();
+          await block;
+        }
+      },
+      getViewportState: () => terminal.getViewportState(),
+      onPaint: () => {},
+    });
+    try {
+      drain.replay({ type: "begin", rows: 30, cols: 120 });
+      drain.replay({ type: "data", data: new TextEncoder().encode("old") });
+      await writing;
+      local.cols = 60;
+      drain.resize();
+      expect(terminal.getViewportState().cols).toBe(120);
+      drain.replay({ type: "end" });
+      if (action === "clear") drain.clear();
+      else if (action === "dispose") {
+        drain.dispose();
+        drain.clear();
+      } else {
+        drain.replay({ type: "begin", rows: 20, cols: 80 });
+        drain.replay({ type: "data", data: new TextEncoder().encode("new") });
+        drain.replay({ type: "end" });
+      }
+      finish();
+      await drain.flush();
+      expect(restores).toBe(action === "dispose" ? 0 : 1);
+      if (action !== "dispose") expect(terminal.getViewportState()).toMatchObject(local);
+    } finally {
+      finish();
+      drain.dispose();
+      terminal.dispose();
+    }
+  },
+);
+
+test("holds captured geometry across mid-replay measurement changes", async () => {
+  const source = new ReplaySource({ rows: 4, cols: 8, scrollback: 100, allowProposedApi: true });
+  const serializer = new SerializeAddon();
+  source.loadAddon(serializer);
+  await new Promise<void>((resolve) =>
+    source.write("ABCDEFGH\r\n12345678\r\nabcdefgh\r\nxyz\x1b[2;8H", resolve),
+  );
+  const ansi = new TextEncoder().encode(serializer.serialize());
+  const terminal = createNativeHeadlessTerminal({ rows: 4, cols: 8, scrollbackLines: 100 });
+  const expected = createNativeHeadlessTerminal({ rows: 4, cols: 8, scrollbackLines: 100 });
+  await expected.write(new TextDecoder().decode(ansi));
+  expected.resize({ rows: 4, cols: 4 });
+  let measured = { rows: 4, cols: 8 };
+  const drain = createNativeTerminalOutputDrain({
+    write: (chunk) => terminal.write(chunk),
+    reset: (size) => {
+      if (size) terminal.resize(size);
+      terminal.reset();
+    },
+    restoreSize: () => terminal.resize(measured),
+    getViewportState: () => terminal.getViewportState(),
+    onPaint: () => {},
+  });
+  try {
+    drain.replay({ type: "begin", rows: 4, cols: 8 });
+    await drain.flush();
+    measured = { rows: 4, cols: 4 };
+    drain.resize();
+    drain.replay({ type: "data", data: ansi });
+    drain.replay({ type: "end" });
+    await drain.flush();
+    expect(terminal.getViewportState()).toEqual(expected.getViewportState());
+    const actualBounds = terminal.getBufferBounds();
+    const expectedBounds = expected.getBufferBounds();
+    expect(
+      terminal.getBufferWindow({
+        startRow: actualBounds.oldestRow,
+        rowCount: actualBounds.newestRow - actualBounds.oldestRow + 1,
+      }),
+    ).toEqual(
+      expected.getBufferWindow({
+        startRow: expectedBounds.oldestRow,
+        rowCount: expectedBounds.newestRow - expectedBounds.oldestRow + 1,
+      }),
+    );
+  } finally {
+    drain.dispose();
+  }
+});
diff --git a/packages/app/src/terminal/native-renderer/headless-terminal-output-drain.ts b/packages/app/src/terminal/native-renderer/headless-terminal-output-drain.ts
index d853165371..00b9865be9 100644
--- a/packages/app/src/terminal/native-renderer/headless-terminal-output-drain.ts
+++ b/packages/app/src/terminal/native-renderer/headless-terminal-output-drain.ts
@@ -1,5 +1,3 @@
-import type { TerminalState } from "@getpaseo/protocol/messages";
-import { renderTerminalSnapshotToAnsi } from "../runtime/terminal-snapshot";
 import type { TerminalViewportState } from "./headless-terminal-state";
 import { nativeTerminalPerformanceNow } from "./terminal-performance";
 
@@ -14,9 +12,9 @@ export interface NativeTerminalParseSample {
 }
 
 export interface NativeTerminalOutputDrain {
+  replay(event: import("@getpaseo/client").TerminalReplayEvent): void;
   enqueueText(text: string): void;
-  restoreText(text: string): void;
-  restoreSnapshot(snapshot: TerminalState): void;
+  resize(): void;
   clear(): void;
   flush(): Promise<void>;
   dispose(): void;
@@ -25,7 +23,8 @@ export interface NativeTerminalOutputDrain {
 
 export interface NativeTerminalOutputDrainOptions {
   write: (chunk: string) => Promise<void>;
-  reset: () => void;
+  restoreSize: () => void;
+  reset: (size?: { rows: number; cols: number }) => void;
   getViewportState: () => TerminalViewportState | null;
   onPaint: (state: TerminalViewportState) => void;
   onParse?: (sample: NativeTerminalParseSample) => void;
@@ -68,16 +67,22 @@ export function createNativeTerminalOutputDrain(
   const chunkChars = options.chunkChars ?? NATIVE_TERMINAL_PARSE_CHUNK_CHARS;
   const chunksPerTurn = options.chunksPerTurn ?? NATIVE_TERMINAL_PARSE_CHUNKS_PER_TURN;
   const idleWaiters: Array<() => void> = [];
-  let pendingText = "";
+  type Operation =
+    | { type: "write"; text: string }
+    | { type: "reset"; size?: { rows: number; cols: number } }
+    | { type: "restore-size" };
+  let operations: Operation[] = [];
+  let queuedChars = 0;
   let drainScheduled = false;
   let draining = false;
   let disposed = false;
+  let replaying = false;
   let paintFrame: number | null = null;
   let generation = 0;
-  let resetBeforeNextWrite = false;
+  const replayDecoder = new TextDecoder();
 
   function resolveIdleIfReady(): void {
-    if (drainScheduled || draining || pendingText.length > 0) {
+    if (drainScheduled || draining || operations.length > 0) {
       return;
     }
     while (idleWaiters.length > 0) {
@@ -119,15 +124,6 @@ export function createNativeTerminalOutputDrain(
     });
   }
 
-  function replacePendingText(text: string): void {
-    generation += 1;
-    pendingText = text;
-    resetBeforeNextWrite = true;
-    cancelPendingPaint();
-    scheduleDrain();
-    resolveIdleIfReady();
-  }
-
   async function drainPending(): Promise<void> {
     if (disposed || draining) {
       return;
@@ -138,16 +134,23 @@ export function createNativeTerminalOutputDrain(
     let parsedChunks = 0;
 
     try {
-      while (pendingText.length > 0 && parsedChunks < chunksPerTurn) {
-        if (disposed || activeGeneration !== generation) {
-          return;
+      while (operations.length > 0 && parsedChunks < chunksPerTurn) {
+        if (disposed || activeGeneration !== generation) return;
+        const operation = operations[0]!;
+        if (operation.type !== "write") {
+          operations.shift();
+          if (operation.type === "reset") options.reset(operation.size);
+          else {
+            options.restoreSize();
+            replaying = false;
+          }
+          requestPaint();
+          continue;
         }
-        if (resetBeforeNextWrite) {
-          options.reset();
-          resetBeforeNextWrite = false;
-        }
-        const chunk = pendingText.slice(0, chunkChars);
-        pendingText = pendingText.slice(chunk.length);
+        const chunk = operation.text.slice(0, chunkChars);
+        operation.text = operation.text.slice(chunk.length);
+        queuedChars -= chunk.length;
+        if (!operation.text) operations.shift();
         const parseStart = nativeTerminalPerformanceNow();
         await options.write(chunk);
         if (disposed || activeGeneration !== generation) {
@@ -156,14 +159,14 @@ export function createNativeTerminalOutputDrain(
         options.onParse?.({
           durationMs: nativeTerminalPerformanceNow() - parseStart,
           parsedChars: chunk.length,
-          queuedChars: pendingText.length,
+          queuedChars,
         });
         requestPaint();
         parsedChunks += 1;
       }
     } finally {
       draining = false;
-      if (!disposed && pendingText.length > 0) {
+      if (!disposed && operations.length > 0) {
         scheduleDrain();
       }
       resolveIdleIfReady();
@@ -171,38 +174,56 @@ export function createNativeTerminalOutputDrain(
   }
 
   return {
-    enqueueText(text: string): void {
-      if (disposed || text.length === 0) {
-        return;
+    replay(event): void {
+      if (disposed) return;
+      if (event.type === "begin") {
+        replaying = true;
+        generation++;
+        replayDecoder.decode();
+        operations = [
+          {
+            type: "reset",
+            size: event.rows && event.cols ? { rows: event.rows, cols: event.cols } : undefined,
+          },
+        ];
+        queuedChars = 0;
+        cancelPendingPaint();
+      } else if (event.type === "data") {
+        this.enqueueText(replayDecoder.decode(event.data, { stream: true }));
+      } else {
+        this.enqueueText(replayDecoder.decode());
+        operations.push({ type: "restore-size" });
       }
-      pendingText += text;
+      scheduleDrain();
+    },
+    enqueueText(text: string): void {
+      if (disposed || !text) return;
+      const last = operations.at(-1);
+      if (last?.type === "write") last.text += text;
+      else operations.push({ type: "write", text });
+      queuedChars += text.length;
       scheduleDrain();
     },
 
-    restoreText(text: string): void {
-      if (disposed) {
-        return;
-      }
-      replacePendingText(text);
-    },
-
-    restoreSnapshot(snapshot: TerminalState): void {
-      if (disposed) {
-        return;
-      }
-      replacePendingText(renderTerminalSnapshotToAnsi(snapshot));
+    resize(): void {
+      if (disposed || replaying) return;
+      operations.push({ type: "restore-size" });
+      scheduleDrain();
     },
 
     clear(): void {
+      if (disposed) return;
       generation += 1;
-      pendingText = "";
-      resetBeforeNextWrite = false;
+      operations = [{ type: "restore-size" }, { type: "reset" }];
+      queuedChars = 0;
+      replayDecoder.decode();
       cancelPendingPaint();
+      scheduleDrain();
       resolveIdleIfReady();
     },
 
     flush(): Promise<void> {
-      if (!drainScheduled && !draining && pendingText.length === 0) {
+      if (!drainScheduled && !draining && operations.length === 0) {
         return Promise.resolve();
       }
       scheduleDrain();
@@ -214,8 +235,8 @@ export function createNativeTerminalOutputDrain(
     dispose(): void {
       disposed = true;
       generation += 1;
-      pendingText = "";
-      resetBeforeNextWrite = false;
+      operations = [];
+      queuedChars = 0;
       cancelPendingPaint();
       while (idleWaiters.length > 0) {
         idleWaiters.shift()?.();
@@ -223,7 +244,7 @@ export function createNativeTerminalOutputDrain(
     },
 
     getQueuedChars(): number {
-      return pendingText.length;
+      return queuedChars;
     },
   };
 }
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 c25399c9b2..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,11 +19,12 @@ export interface NativeHeadlessTerminalOptions {
   rows: number;
   cols: number;
   scrollbackLines?: number;
+  /** Defaults to `graphemes`, the table current daemons use. */
+  characterWidths?: TerminalCharacterWidths;
 }
 
 export interface NativeHeadlessTerminal {
   write(data: NativeTerminalWriteData): Promise<void>;
-  getState(): TerminalState;
   getViewportState(input?: TerminalViewportStateInput): TerminalViewportState;
   getInputModeState(): NativeHeadlessTerminalInputModeState;
   getBufferBounds(): TerminalBufferBounds;
@@ -165,35 +168,6 @@ function extractRow(
   return rowCells;
 }
 
-function extractGrid(terminal: HeadlessTerminalInstance): TerminalCellRow[] {
-  const grid: TerminalCellRow[] = [];
-  const baseY = terminal.buffer.active.baseY;
-  const reusableCell = terminal.buffer.active.getNullCell();
-  for (let row = 0; row < terminal.rows; row += 1) {
-    grid.push(extractRow(terminal, baseY + row, reusableCell));
-  }
-  return grid;
-}
-
-function extractScrollback(
-  terminal: HeadlessTerminalInstance,
-  options: { scrollbackLines?: number },
-): TerminalCellRow[] {
-  const scrollback: TerminalCellRow[] = [];
-  const scrollbackLines = terminal.buffer.active.baseY;
-  const startRow =
-    typeof options.scrollbackLines === "number"
-      ? Math.max(0, scrollbackLines - options.scrollbackLines)
-      : 0;
-  const reusableCell = terminal.buffer.active.getNullCell();
-
-  for (let row = startRow; row < scrollbackLines; row += 1) {
-    scrollback.push(extractRow(terminal, row, reusableCell));
-  }
-
-  return scrollback;
-}
-
 function extractBufferWindow(
   terminal: HeadlessTerminalInstance,
   oldestRow: number,
@@ -290,19 +264,6 @@ function extractInputModeState(
   };
 }
 
-function extractState(
-  terminal: HeadlessTerminalInstance,
-  options: { scrollbackLines?: number },
-): TerminalState {
-  return {
-    rows: terminal.rows,
-    cols: terminal.cols,
-    grid: extractGrid(terminal),
-    scrollback: extractScrollback(terminal, options),
-    cursor: extractCursorState(terminal),
-  };
-}
-
 function extractViewportState(
   terminal: HeadlessTerminalInstance,
   coordinateEpoch: number,
@@ -340,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>();
@@ -380,9 +347,6 @@ export function createNativeHeadlessTerminal(
         });
       });
     },
-    getState(): TerminalState {
-      return extractState(terminal, { scrollbackLines: options.scrollbackLines });
-    },
     getViewportState(input?: TerminalViewportStateInput): TerminalViewportState {
       return extractViewportState(
         terminal,
diff --git a/packages/app/src/terminal/native-renderer/terminal-frame.test.ts b/packages/app/src/terminal/native-renderer/terminal-frame.test.ts
new file mode 100644
index 0000000000..850fd4d183
--- /dev/null
+++ b/packages/app/src/terminal/native-renderer/terminal-frame.test.ts
@@ -0,0 +1,244 @@
+import { describe, expect, test } from "vitest";
+
+import graphemeRows from "../../../modules/paseo-terminal/android/src/androidTest/assets/grapheme-rows.json";
+import { PASEO_TERMINAL_STYLE_FLAGS } from "../../../modules/paseo-terminal/contract";
+import { encodeTerminalFrame } from "../../../modules/paseo-terminal/frame-encoding";
+import {
+  createTerminalCellStyleResolver,
+  DEFAULT_TERMINAL_THEME,
+  parseTerminalColor,
+} from "./colors";
+import { createNativeHeadlessTerminal } from "./headless-terminal-state";
+import { buildTerminalFrame } from "./terminal-frame";
+import { createNativeTerminalOutputDrain } from "./headless-terminal-output-drain";
+import { resolveMeasuredNativeTerminalSize } from "./terminal-size-measurement";
+
+const resolver = createTerminalCellStyleResolver(DEFAULT_TERMINAL_THEME);
+const RED = parseTerminalColor(DEFAULT_TERMINAL_THEME.red, 0);
+const FOREGROUND = parseTerminalColor(DEFAULT_TERMINAL_THEME.foreground, 0);
+
+async function frameFor(output: string, options: { cols?: number; rows?: number } = {}) {
+  const terminal = createNativeHeadlessTerminal({
+    cols: options.cols ?? 20,
+    rows: options.rows ?? 4,
+  });
+  await terminal.write(output);
+  const state = terminal.getViewportState({ firstRow: 0, rowCount: options.rows ?? 4 });
+  terminal.dispose();
+  return {
+    state,
+    frame: buildTerminalFrame({ state, columns: state.cols, resolver, selection: null }),
+  };
+}
+
+function cellLayout(row: { text: string; cells: number[] }) {
+  const layout: Array<{ text: string; col: number; span: number }> = [];
+  let offset = 0;
+  let col = 0;
+  for (let index = 0; index < row.cells.length; index += 2) {
+    const [length, span] = [row.cells[index], row.cells[index + 1]];
+    layout.push({ text: row.text.slice(offset, offset + length), col, span });
+    offset += length;
+    col += span;
+  }
+  return layout;
+}
+
+/** Indexes of the cells that start a grapheme cluster. */
+function clusterStartCells(row: { text: string; cells: number[] }, segmenter: Intl.Segmenter) {
+  const boundaries = new Set(Array.from(segmenter.segment(row.text), (segment) => segment.index));
+  const starts: number[] = [];
+  let offset = 0;
+  for (let cell = 0; cell < row.cells.length / 2; cell += 1) {
+    if (boundaries.has(offset)) starts.push(cell);
+    offset += row.cells[cell * 2];
+  }
+  return starts;
+}
+
+describe("native terminal frame", () => {
+  test("keeps each Hangul syllable on xterm's two-column allocation", async () => {
+    const { frame } = await frameFor("> 안녕하세요");
+
+    expect(cellLayout(frame.rows[0]).slice(0, 7)).toEqual([
+      { text: ">", col: 0, span: 1 },
+      { text: " ", col: 1, span: 1 },
+      { text: "안", col: 2, span: 2 },
+      { text: "녕", col: 4, span: 2 },
+      { text: "하", col: 6, span: 2 },
+      { text: "세", col: 8, span: 2 },
+      { text: "요", col: 10, span: 2 },
+    ]);
+    expect(frame.cursor).toEqual({ row: 0, col: 12 });
+  });
+
+  test("covers every column once, including trailing blanks", async () => {
+    const corpus = ["안녕하세요NEXT", "日本語 中文", "áé é x̸", "क्ष कि ❤️ 👩‍💻 🇰🇷"];
+    const { frame } = await frameFor(corpus.join("\r\n"), { rows: 4, cols: 24 });
+
+    for (const row of frame.rows) {
+      const spans = row.cells.filter((_, index) => index % 2 === 1);
+      const styleColumns = row.styles.filter((_, index) => index % 4 === 0);
+      expect(spans.reduce((total, span) => total + span, 0)).toBe(24);
+      expect(styleColumns.reduce((total, span) => total + span, 0)).toBe(24);
+      expect(row.cells.filter((_, index) => index % 2 === 0).reduce((a, b) => a + b, 0)).toBe(
+        row.text.length,
+      );
+    }
+  });
+
+  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, 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: 2 },
+      { text: " ", col: 10, span: 1 },
+    ]);
+  });
+
+  test("splits style spans at SGR changes without moving cells", async () => {
+    const { frame } = await frameFor("안녕\x1b[31mNEXT\x1b[0m\x1b[1;4m!\x1b[0m");
+    const row = frame.rows[0];
+
+    expect(
+      cellLayout(row)
+        .slice(0, 7)
+        .map((cell) => cell.col),
+    ).toEqual([0, 2, 4, 5, 6, 7, 8]);
+    expect(row.styles.slice(0, 12)).toEqual([
+      4,
+      FOREGROUND,
+      0,
+      0,
+      4,
+      RED,
+      0,
+      0,
+      1,
+      FOREGROUND,
+      0,
+      PASEO_TERMINAL_STYLE_FLAGS.bold | PASEO_TERMINAL_STYLE_FLAGS.underline,
+    ]);
+  });
+
+  test("resolves inverse and dim into paint colors", async () => {
+    const { frame } = await frameFor("\x1b[7mI\x1b[0m\x1b[2mD\x1b[0m");
+    const background = parseTerminalColor(DEFAULT_TERMINAL_THEME.background, 0);
+
+    expect(frame.rows[0].styles.slice(0, 8)).toEqual([
+      1,
+      background,
+      FOREGROUND,
+      0,
+      1,
+      (((Math.round(255 * 0.65) & 0xff) << 24) | (FOREGROUND & 0xffffff)) >>> 0,
+      0,
+      PASEO_TERMINAL_STYLE_FLAGS.dim,
+    ]);
+  });
+
+  test("rows follow content and style but not cursor or selection", async () => {
+    const plain = await frameFor("same\r\nrow");
+    const moved = await frameFor("same\r\nrow\x1b[1;1H");
+    const recolored = await frameFor("\x1b[31msame\x1b[0m\r\nrow");
+
+    expect(moved.frame.rows[0]).toEqual(plain.frame.rows[0]);
+    expect(moved.frame.cursor).not.toEqual(plain.frame.cursor);
+    expect(recolored.frame.rows[0]).not.toEqual(plain.frame.rows[0]);
+
+    const selected = buildTerminalFrame({
+      state: plain.state,
+      columns: plain.state.cols,
+      resolver,
+      selection: {
+        start: { row: 0, col: 1 },
+        end: { row: 1, col: 0 },
+        coordinateEpoch: 0,
+      },
+    });
+    expect(selected.rows).toEqual(plain.frame.rows);
+    expect(selected.selection).toEqual({ startRow: 0, startCol: 1, endRow: 1, endCol: 0 });
+  });
+
+  test("clips the frame to the visible columns", async () => {
+    const { state } = await frameFor("0123456789abcdefghij");
+    const frame = buildTerminalFrame({ state, columns: 8, resolver, selection: null });
+
+    expect(frame.columns).toBe(8);
+    expect(frame.rows[0].text).toBe("01234567");
+  });
+
+  // The Android instrumented test draws these rows and compares them with each cluster drawn on its
+  // own. This keeps its input equal to what xterm produces, and its clusters equal to UAX #29
+  // grapheme clusters. `contrastStarts` is a wrong clustering the comparison must reject.
+  test("Android cluster fixture matches xterm cells and grapheme clusters", async () => {
+    const segmenter = new Intl.Segmenter("und", { granularity: "grapheme" });
+    const actual = await Promise.all(
+      graphemeRows.map(async ({ output, contrastStarts }) => {
+        const { frame } = await frameFor(output, { cols: 8, rows: 1 });
+        const row = frame.rows[0];
+        const [encoded] = encodeTerminalFrame({ ...frame, rows: [row] }).rows;
+        return {
+          output,
+          row: encoded,
+          clusterStarts: clusterStartCells(row, segmenter),
+          contrastStarts,
+        };
+      }),
+    );
+
+    expect(actual).toEqual(graphemeRows);
+  });
+});
+
+test("builds native frames after replay commits at captured geometry and the latest measurement precedes live text", async () => {
+  let measured = resolveMeasuredNativeTerminalSize({
+    layout: { width: 400, height: 240 },
+    metrics: { cellWidth: 10, cellHeight: 10 },
+  })!;
+  const terminal = createNativeHeadlessTerminal({ ...measured, scrollbackLines: 10000 });
+  const parsedColumns: number[] = [];
+  const drain = createNativeTerminalOutputDrain({
+    write: async (text) => {
+      parsedColumns.push(terminal.getViewportState().cols);
+      await terminal.write(text);
+    },
+    reset: (size) => {
+      if (size) terminal.resize(size);
+      terminal.reset();
+    },
+    restoreSize: () => terminal.resize(measured),
+    getViewportState: () => terminal.getViewportState(),
+    onPaint: () => {},
+  });
+  try {
+    drain.replay({ type: "begin", rows: 30, cols: 120 });
+    drain.replay({ type: "data", data: new TextEncoder().encode("x".repeat(100) + "\r\n") });
+    measured = resolveMeasuredNativeTerminalSize({
+      layout: { width: 500, height: 100 },
+      metrics: { cellWidth: 10, cellHeight: 10 },
+    })!;
+    drain.resize();
+    drain.replay({ type: "end" });
+    drain.enqueueText("\x1b[H\x1b[2K\x1b[31mLIVE-界🙂\x1b[0m");
+    await drain.flush();
+    expect(parsedColumns).toEqual([120, 50]);
+    const state = terminal.getViewportState();
+    const frame = buildTerminalFrame({ state, columns: state.cols, resolver, selection: null });
+    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([9, RED, 0, 0]);
+    expect(encodeTerminalFrame(frame).rows[0]).toContain("LIVE-界🙂");
+  } finally {
+    drain.dispose();
+    terminal.dispose();
+  }
+});
diff --git a/packages/app/src/terminal/native-renderer/terminal-frame.ts b/packages/app/src/terminal/native-renderer/terminal-frame.ts
new file mode 100644
index 0000000000..584e09a274
--- /dev/null
+++ b/packages/app/src/terminal/native-renderer/terminal-frame.ts
@@ -0,0 +1,84 @@
+import type {
+  PaseoTerminalFrame,
+  PaseoTerminalRow,
+  PaseoTerminalSelection,
+} from "../../../modules/paseo-terminal/contract";
+import type { TerminalCellStyleResolver } from "./colors";
+import type { NativeTerminalCell, TerminalViewportState } from "./headless-terminal-state";
+import type { TerminalSelectionRange } from "./terminal-selection";
+
+/**
+ * Converts the xterm viewport into the native renderer's frame. Every cell keeps its own text and
+ * xterm's column span; continuation cells of wide characters (width 0) belong to the cell before
+ * them. Nothing here measures or joins text: the renderer shapes rows and places the result on
+ * these columns.
+ */
+export function buildTerminalFrame(input: {
+  state: TerminalViewportState;
+  columns: number;
+  resolver: TerminalCellStyleResolver;
+  selection: TerminalSelectionRange | null;
+}): PaseoTerminalFrame {
+  const grid = input.state.grid as NativeTerminalCell[][];
+  return {
+    columns: input.columns,
+    rows: grid.map((cells) =>
+      buildRow({ cells, columns: input.columns, resolver: input.resolver }),
+    ),
+    cursor: input.state.cursor.hidden
+      ? null
+      : { row: input.state.cursor.row, col: input.state.cursor.col },
+    selection: input.selection
+      ? toFrameSelection({ range: input.selection, firstRow: input.state.firstRow })
+      : null,
+  };
+}
+
+function buildRow(input: {
+  cells: NativeTerminalCell[];
+  columns: number;
+  resolver: TerminalCellStyleResolver;
+}): PaseoTerminalRow {
+  let text = "";
+  const cells: number[] = [];
+  const styles: number[] = [];
+  const lastColumn = Math.min(input.columns, input.cells.length);
+
+  for (let col = 0; col < lastColumn; col += 1) {
+    const cell = input.cells[col];
+    const span = cell.width ?? 1;
+    if (span <= 0) {
+      continue;
+    }
+    const cellText = cell.char || " ";
+    text += cellText;
+    cells.push(cellText.length, span);
+
+    const style = input.resolver.resolve(cell);
+    const previous = styles.length - 4;
+    if (
+      previous >= 0 &&
+      styles[previous + 1] === style.foreground &&
+      styles[previous + 2] === style.background &&
+      styles[previous + 3] === style.flags
+    ) {
+      styles[previous] += span;
+    } else {
+      styles.push(span, style.foreground, style.background, style.flags);
+    }
+  }
+
+  return { text, cells, styles };
+}
+
+function toFrameSelection(input: {
+  range: TerminalSelectionRange;
+  firstRow: number;
+}): PaseoTerminalSelection {
+  return {
+    startRow: input.range.start.row - input.firstRow,
+    startCol: input.range.start.col,
+    endRow: input.range.end.row - input.firstRow,
+    endCol: input.range.end.col,
+  };
+}
diff --git a/packages/app/src/terminal/native-renderer/terminal-grid-metrics.test.ts b/packages/app/src/terminal/native-renderer/terminal-grid-metrics.test.ts
index 0c4d7bc25f..c0fef99104 100644
--- a/packages/app/src/terminal/native-renderer/terminal-grid-metrics.test.ts
+++ b/packages/app/src/terminal/native-renderer/terminal-grid-metrics.test.ts
@@ -1,68 +1,8 @@
 import { describe, expect, it } from "vitest";
 
-import {
-  resolveTerminalCustomGlyphCellTransform,
-  resolveTerminalGridMetricsMeasurement,
-  resolveMeasuredTerminalCellMetrics,
-  resolveTerminalCursorOffset,
-} from "./terminal-grid-metrics";
+import { resolveTerminalGridMetricsMeasurement } from "./terminal-grid-metrics";
 
 describe("native terminal grid metrics", () => {
-  it("places each normalized custom glyph in run viewport coordinates", () => {
-    expect(
-      resolveTerminalCustomGlyphCellTransform({
-        cellOffset: 57,
-        cellWidth: 7.4,
-        cellHeight: 16.2,
-      }),
-    ).toBe("matrix(7.4 0 0 16.2 421.8 0)");
-  });
-
-  it("preserves fractional measured cell width for horizontal layout", () => {
-    expect(
-      resolveMeasuredTerminalCellMetrics({
-        measuredTextWidth: 72.246,
-        measuredTextHeight: 16.2,
-        measureTextLength: 10,
-        roundToNearestPixel: (value) => value,
-      }),
-    ).toEqual({
-      cellWidth: 7.2246,
-      cellHeight: 16.2,
-    });
-  });
-
-  it.each([1, 2, 2.75, 3, 3.5])(
-    "aligns cells to the physical pixel grid at density %s",
-    (density) => {
-      const metrics = resolveMeasuredTerminalCellMetrics({
-        measuredTextWidth: 72.246,
-        measuredTextHeight: 16.2,
-        measureTextLength: 10,
-        roundToNearestPixel: (value) => Math.round(value * density) / density,
-      });
-
-      expect(metrics.cellWidth * density).toBeCloseTo(Math.round(metrics.cellWidth * density), 10);
-      expect(metrics.cellHeight * density).toBeCloseTo(
-        Math.round(metrics.cellHeight * density),
-        10,
-      );
-    },
-  );
-
-  it("positions the cursor with the measured fractional cell width", () => {
-    expect(
-      resolveTerminalCursorOffset({
-        cursorCol: 80,
-        cursorRow: 3,
-        metrics: { cellWidth: 7.2246, cellHeight: 16 },
-      }),
-    ).toEqual({
-      x: 577.968,
-      y: 48,
-    });
-  });
-
   it("emits measured metrics once until the measurement changes", () => {
     const measured = { cellWidth: 7.2, cellHeight: 16 };
 
diff --git a/packages/app/src/terminal/native-renderer/terminal-grid-metrics.ts b/packages/app/src/terminal/native-renderer/terminal-grid-metrics.ts
index cb14111bf2..806c149c60 100644
--- a/packages/app/src/terminal/native-renderer/terminal-grid-metrics.ts
+++ b/packages/app/src/terminal/native-renderer/terminal-grid-metrics.ts
@@ -3,47 +3,6 @@ export interface TerminalGridCellMetrics {
   cellHeight: number;
 }
 
-export interface TerminalGridCellMetricsInput {
-  measuredTextWidth: number;
-  measuredTextHeight: number;
-  measureTextLength: number;
-  roundToNearestPixel: (value: number) => number;
-}
-
-export interface TerminalCursorOffsetInput {
-  cursorCol: number;
-  cursorRow: number;
-  metrics: TerminalGridCellMetrics;
-}
-
-export interface TerminalCursorOffset {
-  x: number;
-  y: number;
-}
-
-export interface TerminalCustomGlyphCellTransformInput {
-  cellOffset: number;
-  cellWidth: number;
-  cellHeight: number;
-}
-
-export function resolveTerminalCustomGlyphCellTransform(
-  input: TerminalCustomGlyphCellTransformInput,
-): string {
-  const translateX = input.cellOffset * input.cellWidth;
-  return `matrix(${input.cellWidth} 0 0 ${input.cellHeight} ${translateX} 0)`;
-}
-
-export function resolveMeasuredTerminalCellMetrics(
-  input: TerminalGridCellMetricsInput,
-): TerminalGridCellMetrics {
-  const textLength = Math.max(1, input.measureTextLength);
-  return {
-    cellWidth: snapCellMetric(input.measuredTextWidth / textLength, input.roundToNearestPixel),
-    cellHeight: snapCellMetric(input.measuredTextHeight, input.roundToNearestPixel),
-  };
-}
-
 export function resolveTerminalGridMetricsMeasurement(
   previous: TerminalGridCellMetrics | null,
   next: TerminalGridCellMetrics,
@@ -53,16 +12,3 @@ export function resolveTerminalGridMetricsMeasurement(
   }
   return next;
 }
-
-export function resolveTerminalCursorOffset(
-  input: TerminalCursorOffsetInput,
-): TerminalCursorOffset {
-  return {
-    x: input.cursorCol * input.metrics.cellWidth,
-    y: input.cursorRow * input.metrics.cellHeight,
-  };
-}
-
-function snapCellMetric(value: number, roundToNearestPixel: (value: number) => number): number {
-  return Math.max(1, roundToNearestPixel(value));
-}
diff --git a/packages/app/src/terminal/native-renderer/terminal-grid-view.native.tsx b/packages/app/src/terminal/native-renderer/terminal-grid-view.native.tsx
index 04f82c1011..167a33e0ab 100644
--- a/packages/app/src/terminal/native-renderer/terminal-grid-view.native.tsx
+++ b/packages/app/src/terminal/native-renderer/terminal-grid-view.native.tsx
@@ -1,71 +1,34 @@
-import { memo, useCallback, useMemo, useRef, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import {
-  PixelRatio,
-  Text,
+  useWindowDimensions,
   View,
   type LayoutChangeEvent,
   type StyleProp,
-  type TextStyle,
   type ViewStyle,
 } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
-import Svg, { G, Path } from "react-native-svg";
 import type { ITheme } from "@xterm/xterm";
 
+import {
+  PaseoTerminalView,
+  type PaseoTerminalCellMetrics,
+  type PaseoTerminalTheme,
+} from "../../../modules/paseo-terminal";
 import {
   createTerminalCellStyleResolver,
   DEFAULT_TERMINAL_THEME,
   NATIVE_TERMINAL_SELECTION_COLORS,
 } from "./colors";
-import type { TerminalGlyphRect } from "./terminal-custom-glyph";
 import { resolveNativeTerminalFontFamily } from "./font.native";
 import type { TerminalViewportState } from "./headless-terminal-state";
 import {
-  resolveMeasuredTerminalCellMetrics,
-  resolveTerminalCustomGlyphCellTransform,
   resolveTerminalGridMetricsMeasurement,
-  resolveTerminalCursorOffset,
   type TerminalGridCellMetrics,
 } from "./terminal-grid-metrics";
-import {
-  buildRows,
-  type TerminalCustomGlyphCell,
-  type TerminalCustomGlyphRun,
-  type TerminalRowModel,
-  type TerminalRun,
-} from "./terminal-row-model";
+import { buildTerminalFrame } from "./terminal-frame";
 import type { TerminalSelectionRange } from "./terminal-selection";
 
-const MEASURE_TEXT = "mmmmmmmmmm";
 const DEFAULT_FONT_SIZE = 12;
-const INITIAL_CELL_WIDTH_RATIO = 0.62;
-const INITIAL_CELL_HEIGHT_RATIO = 1.35;
-
-interface CellMetrics {
-  cellWidth: number;
-  cellHeight: number;
-}
-
-interface TerminalGridViewport {
-  width: number;
-  height: number;
-}
-
-interface TerminalGridRowProps {
-  row: TerminalRowModel;
-  cellWidth: number;
-  cellHeight: number;
-  fontFamily?: string;
-  fontSize: number;
-  styleEpoch: string;
-}
-
-interface TerminalGridRunProps {
-  run: TerminalRun;
-  cellWidth: number;
-  cellHeight: number;
-  textStyle: StyleProp<TextStyle>;
-}
 
 export interface TerminalGridViewProps {
   state: TerminalViewportState;
@@ -77,221 +40,20 @@ export interface TerminalGridViewProps {
   onCellMetricsChange?: (metrics: TerminalGridCellMetrics) => void;
 }
 
-function estimateCellMetrics(fontSize: number): CellMetrics {
-  return {
-    cellWidth: snapPixel(fontSize * INITIAL_CELL_WIDTH_RATIO),
-    cellHeight: snapPixel(fontSize * INITIAL_CELL_HEIGHT_RATIO),
-  };
-}
-
-function snapPixel(value: number): number {
-  return Math.max(1, PixelRatio.roundToNearestPixel(value));
-}
-
 function resolveVisibleCols(input: {
-  viewportWidth: number;
-  cellWidth: number;
+  viewportWidth: number | null;
+  cellWidth: number | null;
   gridCols: number;
 }): number {
+  if (input.viewportWidth === null || input.cellWidth === null) {
+    return input.gridCols;
+  }
   if (input.viewportWidth <= 0 || input.cellWidth <= 0 || input.gridCols <= 0) {
     return 0;
   }
   return Math.min(input.gridCols, Math.max(1, Math.floor(input.viewportWidth / input.cellWidth)));
 }
 
-function TerminalGridRun({ run, cellWidth, cellHeight, textStyle }: TerminalGridRunProps) {
-  const runStyle = useMemo<StyleProp<ViewStyle>>(
-    () => [
-      styles.run,
-      {
-        backgroundColor: run.style.backgroundColor,
-        height: cellHeight,
-        width: run.cellCount * cellWidth,
-      },
-    ],
-    [cellHeight, cellWidth, run.cellCount, run.style.backgroundColor],
-  );
-  const runTextStyle = useMemo<StyleProp<TextStyle>>(
-    () => [textStyle, run.style],
-    [run.style, textStyle],
-  );
-
-  return (
-    <View style={runStyle}>
-      {run.renderKind === "custom-glyph" ? (
-        <TerminalGridCustomGlyphRun run={run} cellWidth={cellWidth} cellHeight={cellHeight} />
-      ) : (
-        <Text numberOfLines={1} style={runTextStyle}>
-          {run.text}
-        </Text>
-      )}
-    </View>
-  );
-}
-
-interface TerminalGridCustomGlyphRunProps {
-  run: TerminalCustomGlyphRun;
-  cellWidth: number;
-  cellHeight: number;
-}
-
-interface TerminalGridCustomGlyphRectProps {
-  cell: TerminalCustomGlyphCell;
-  rect: TerminalGlyphRect;
-  cellWidth: number;
-  cellHeight: number;
-  foregroundColor: string;
-}
-
-function TerminalGridCustomGlyphRect({
-  cell,
-  rect,
-  cellWidth,
-  cellHeight,
-  foregroundColor,
-}: TerminalGridCustomGlyphRectProps) {
-  const style = useMemo<ViewStyle>(
-    () => ({
-      position: "absolute",
-      backgroundColor: foregroundColor,
-      left: (cell.offset + rect.x) * cellWidth,
-      top: rect.y * cellHeight,
-      width: rect.width * cellWidth,
-      height: rect.height * cellHeight,
-    }),
-    [cell.offset, cellHeight, cellWidth, foregroundColor, rect],
-  );
-
-  return <View style={style} />;
-}
-
-function TerminalGridCustomGlyphRun({
-  run,
-  cellWidth,
-  cellHeight,
-}: TerminalGridCustomGlyphRunProps) {
-  const opacity = typeof run.style.opacity === "number" ? run.style.opacity : 1;
-
-  return (
-    <View style={[styles.customGlyphRun, { opacity }]}>
-      {run.glyphs.map((cell) =>
-        cell.glyph.kind === "rects"
-          ? cell.glyph.rects.map((rect) => (
-              <TerminalGridCustomGlyphRect
-                key={`${cell.key}:${rect.x}:${rect.y}:${rect.width}:${rect.height}`}
-                cell={cell}
-                rect={rect}
-                cellWidth={cellWidth}
-                cellHeight={cellHeight}
-                foregroundColor={run.foregroundColor}
-              />
-            ))
-          : null,
-      )}
-      <Svg
-        height={cellHeight}
-        pointerEvents="none"
-        preserveAspectRatio="none"
-        style={styles.customGlyphSvg}
-        viewBox={`0 0 ${run.cellCount * cellWidth} ${cellHeight}`}
-        width={run.cellCount * cellWidth}
-      >
-        <G fill="none" stroke={run.foregroundColor}>
-          {run.glyphs.map((cell) =>
-            cell.glyph.kind === "path" ? (
-              <Path
-                d={cell.glyph.path}
-                key={cell.key}
-                strokeLinecap="butt"
-                strokeLinejoin="miter"
-                strokeWidth={cell.glyph.strokeWidth}
-                transform={resolveTerminalCustomGlyphCellTransform({
-                  cellOffset: cell.offset,
-                  cellWidth,
-                  cellHeight,
-                })}
-                vectorEffect="non-scaling-stroke"
-              />
-            ) : null,
-          )}
-        </G>
-      </Svg>
-    </View>
-  );
-}
-
-const MemoTerminalGridRun = memo(TerminalGridRun, (previous, next) => {
-  return (
-    previous.run === next.run &&
-    previous.cellWidth === next.cellWidth &&
-    previous.cellHeight === next.cellHeight &&
-    previous.textStyle === next.textStyle
-  );
-});
-
-function TerminalGridRow({
-  row,
-  cellWidth,
-  cellHeight,
-  fontFamily,
-  fontSize,
-}: TerminalGridRowProps) {
-  const rowStyle = useMemo<StyleProp<ViewStyle>>(
-    () => [styles.row, { height: cellHeight }],
-    [cellHeight],
-  );
-  const textStyle = useMemo<StyleProp<TextStyle>>(
-    () => [
-      styles.rowText,
-      {
-        height: cellHeight,
-        lineHeight: cellHeight,
-        fontFamily,
-        fontSize,
-      },
-    ],
-    [cellHeight, fontFamily, fontSize],
-  );
-  const accessibilityLabel = useMemo(
-    () =>
-      row.runs
-        .map((run) => run.text)
-        .join("")
-        .trimEnd(),
-    [row.runs],
-  );
-
-  return (
-    <View
-      accessibilityLabel={accessibilityLabel}
-      accessible={accessibilityLabel.length > 0}
-      style={rowStyle}
-      testID={`terminal-row-${row.index}`}
-    >
-      {row.runs.map((run) => (
-        <MemoTerminalGridRun
-          key={run.key}
-          run={run}
-          cellWidth={cellWidth}
-          cellHeight={cellHeight}
-          textStyle={textStyle}
-        />
-      ))}
-    </View>
-  );
-}
-
-const MemoTerminalGridRow = memo(TerminalGridRow, (previous, next) => {
-  return (
-    previous.row.hash === next.row.hash &&
-    previous.cellWidth === next.cellWidth &&
-    previous.cellHeight === next.cellHeight &&
-    previous.fontFamily === next.fontFamily &&
-    previous.fontSize === next.fontSize &&
-    previous.styleEpoch === next.styleEpoch
-  );
-});
-
 export function TerminalGridView({
   state,
   xtermTheme = DEFAULT_TERMINAL_THEME,
@@ -301,129 +63,60 @@ export function TerminalGridView({
   selection = null,
   onCellMetricsChange,
 }: TerminalGridViewProps) {
-  const [metrics, setMetrics] = useState<CellMetrics>(() => estimateCellMetrics(fontSize));
+  const { fontScale } = useWindowDimensions();
+  const [cellWidth, setCellWidth] = useState<number | null>(null);
+  const [viewportWidth, setViewportWidth] = useState<number | null>(null);
   const measuredMetricsRef = useRef<TerminalGridCellMetrics | null>(null);
-  const [viewport, setViewport] = useState<TerminalGridViewport | null>(null);
   const resolvedFontFamily = useMemo(
     () => resolveNativeTerminalFontFamily(fontFamily),
     [fontFamily],
   );
   const resolver = useMemo(() => createTerminalCellStyleResolver(xtermTheme), [xtermTheme]);
-  const visibleCols = useMemo(() => {
-    const viewportWidth = viewport?.width ?? state.cols * metrics.cellWidth;
-    return resolveVisibleCols({
-      viewportWidth,
-      cellWidth: metrics.cellWidth,
-      gridCols: state.cols,
-    });
-  }, [metrics.cellWidth, state.cols, viewport?.width]);
-  const projectedGrid = useMemo(
-    () => state.grid.map((row) => row.slice(0, visibleCols)),
-    [state.grid, visibleCols],
+  const theme = useMemo<PaseoTerminalTheme>(
+    () => ({
+      background: resolver.backgroundColor,
+      cursor: resolver.cursorColor,
+      selectionBackground: NATIVE_TERMINAL_SELECTION_COLORS.background,
+    }),
+    [resolver],
   );
-  const rows = useMemo(
-    () =>
-      buildRows({
-        grid: projectedGrid,
-        resolver,
-        selection: selection
-          ? {
-              range: selection,
-              firstRow: state.firstRow,
-              backgroundColor: NATIVE_TERMINAL_SELECTION_COLORS.background,
-              foregroundColor: NATIVE_TERMINAL_SELECTION_COLORS.foreground,
-            }
-          : undefined,
-      }),
-    [projectedGrid, resolver, selection, state.firstRow],
+  const columns = resolveVisibleCols({ viewportWidth, cellWidth, gridCols: state.cols });
+  const frame = useMemo(
+    () => buildTerminalFrame({ state, columns, resolver, selection }),
+    [columns, resolver, selection, state],
   );
 
-  const containerStyle = useMemo<StyleProp<ViewStyle>>(
-    () => [styles.root, { backgroundColor: resolver.backgroundColor }, style],
-    [resolver.backgroundColor, style],
-  );
-  const gridStyle = useMemo<StyleProp<ViewStyle>>(
-    () => [
-      styles.grid,
-      {
-        width: visibleCols * metrics.cellWidth,
-        height: state.grid.length * metrics.cellHeight,
-      },
-    ],
-    [metrics.cellHeight, metrics.cellWidth, state.grid.length, visibleCols],
-  );
-  const measureStyle = useMemo<StyleProp<TextStyle>>(
-    () => [styles.measureText, { fontFamily: resolvedFontFamily, fontSize }],
-    [resolvedFontFamily, fontSize],
-  );
-  const cursorStyle = useMemo<StyleProp<ViewStyle>>(() => {
-    const cursorOffset = resolveTerminalCursorOffset({
-      cursorCol: state.cursor.col,
-      cursorRow: state.cursor.row,
-      metrics,
-    });
-    return [
-      styles.cursor,
-      {
-        backgroundColor: resolver.cursorColor,
-        width: metrics.cellWidth,
-        height: metrics.cellHeight,
-        transform: [{ translateX: cursorOffset.x }, { translateY: cursorOffset.y }],
-      },
-    ];
-  }, [metrics, state.cursor.col, state.cursor.row, resolver.cursorColor]);
-
-  const handleMeasure = useCallback(
-    (event: LayoutChangeEvent) => {
-      const nextMetrics = resolveMeasuredTerminalCellMetrics({
-        measuredTextWidth: event.nativeEvent.layout.width,
-        measuredTextHeight: event.nativeEvent.layout.height,
-        measureTextLength: MEASURE_TEXT.length,
-        roundToNearestPixel: (value) => PixelRatio.roundToNearestPixel(value),
-      });
+  const handleCellMetrics = useCallback(
+    (metrics: PaseoTerminalCellMetrics) => {
       const changedMetrics = resolveTerminalGridMetricsMeasurement(
         measuredMetricsRef.current,
-        nextMetrics,
+        metrics,
       );
       if (!changedMetrics) {
         return;
       }
       measuredMetricsRef.current = changedMetrics;
-      setMetrics(changedMetrics);
+      setCellWidth(changedMetrics.cellWidth);
       onCellMetricsChange?.(changedMetrics);
     },
     [onCellMetricsChange],
   );
 
   const handleContainerLayout = useCallback((event: LayoutChangeEvent) => {
-    const { width, height } = event.nativeEvent.layout;
-    setViewport((current) => {
-      if (current?.width === width && current.height === height) {
-        return current;
-      }
-      return { width, height };
-    });
+    const { width } = event.nativeEvent.layout;
+    setViewportWidth((current) => (current === width ? current : width));
   }, []);
 
   return (
-    <View onLayout={handleContainerLayout} pointerEvents="none" style={containerStyle}>
-      <View style={gridStyle}>
-        <Text onLayout={handleMeasure} pointerEvents="none" style={measureStyle}>
-          {MEASURE_TEXT}
-        </Text>
-        {rows.map((row) => (
-          <MemoTerminalGridRow
-            key={row.index}
-            row={row}
-            cellWidth={metrics.cellWidth}
-            cellHeight={metrics.cellHeight}
-            fontFamily={resolvedFontFamily}
-            fontSize={fontSize}
-            styleEpoch={resolver.themeKey}
-          />
-        ))}
-        {!state.cursor.hidden && <View pointerEvents="none" style={cursorStyle} />}
-      </View>
+    <View onLayout={handleContainerLayout} pointerEvents="none" style={[styles.root, style]}>
+      <PaseoTerminalView
+        frame={frame}
+        theme={theme}
+        fontFamily={resolvedFontFamily}
+        fontSize={fontSize * fontScale}
+        onCellMetrics={handleCellMetrics}
+        style={styles.surface}
+      />
     </View>
   );
 }
@@ -432,38 +125,7 @@ const styles = StyleSheet.create({
   root: {
     overflow: "hidden",
   },
-  grid: {
-    position: "relative",
-  },
-  row: {
-    flexDirection: "row",
-  },
-  run: {
-    overflow: "hidden",
-  },
-  customGlyphRun: {
+  surface: {
     flex: 1,
-    position: "relative",
-  },
-  customGlyphSvg: {
-    left: 0,
-    position: "absolute",
-    top: 0,
-  },
-  rowText: {
-    includeFontPadding: false,
-    margin: 0,
-    padding: 0,
-  },
-  measureText: {
-    includeFontPadding: false,
-    opacity: 0,
-    position: "absolute",
-  },
-  cursor: {
-    left: 0,
-    opacity: 0.45,
-    position: "absolute",
-    top: 0,
   },
 });
diff --git a/packages/app/src/terminal/native-renderer/terminal-row-model.test.ts b/packages/app/src/terminal/native-renderer/terminal-row-model.test.ts
deleted file mode 100644
index b19922b7a9..0000000000
--- a/packages/app/src/terminal/native-renderer/terminal-row-model.test.ts
+++ /dev/null
@@ -1,120 +0,0 @@
-import type { TerminalCell } from "@getpaseo/protocol/messages";
-import { describe, expect, test } from "vitest";
-
-import { createTerminalCellStyleResolver, DEFAULT_TERMINAL_THEME } from "./colors";
-import { buildRows } from "./terminal-row-model";
-
-function cell(
-  char: string,
-  overrides: Partial<TerminalCell> & { width?: number } = {},
-): TerminalCell & { width?: number } {
-  return { char, ...overrides };
-}
-
-describe("terminal row model", () => {
-  test("preserves terminal cell width for styled runs and trailing spaces", () => {
-    const resolver = createTerminalCellStyleResolver(DEFAULT_TERMINAL_THEME);
-
-    const rows = buildRows({
-      grid: [
-        [cell("n", { bg: 2, bgMode: 1 }), cell("v", { bg: 2, bgMode: 1 }), cell(" "), cell(" ")],
-      ],
-      resolver,
-    });
-
-    expect(rows[0].runs.map((run) => ({ text: run.text, cellCount: run.cellCount }))).toEqual([
-      { text: "nv", cellCount: 2 },
-      { text: "  ", cellCount: 2 },
-    ]);
-  });
-
-  test("uses xterm's authoritative width instead of guessing from the code point", () => {
-    const resolver = createTerminalCellStyleResolver(DEFAULT_TERMINAL_THEME);
-
-    const rows = buildRows({
-      grid: [[cell("A", { width: 2 }), cell(" ", { width: 0 }), cell("界", { width: 1 })]],
-      resolver,
-    });
-
-    expect(rows[0].runs.map((run) => ({ text: run.text, cellCount: run.cellCount }))).toEqual([
-      { text: "A界", cellCount: 3 },
-    ]);
-  });
-
-  test("redraws selected cells with the terminal selection colors", () => {
-    const resolver = createTerminalCellStyleResolver(DEFAULT_TERMINAL_THEME);
-    const grid = [[cell("a", { fg: 1, fgMode: 1 }), cell("b", { dim: true }), cell("c")]];
-
-    const rows = buildRows({
-      grid,
-      resolver,
-      selection: {
-        range: {
-          start: { row: 7, col: 1 },
-          end: { row: 7, col: 2 },
-          coordinateEpoch: 1,
-        },
-        firstRow: 7,
-        backgroundColor: "#ffff00",
-        foregroundColor: "#000000",
-      },
-    });
-
-    expect(
-      rows[0].runs.map((run) => ({
-        text: run.text,
-        color: run.style.color,
-        backgroundColor: run.style.backgroundColor,
-        opacity: run.style.opacity,
-      })),
-    ).toEqual([
-      {
-        text: "a",
-        color: DEFAULT_TERMINAL_THEME.red,
-        backgroundColor: undefined,
-        opacity: undefined,
-      },
-      { text: "b", color: "#000000", backgroundColor: "#ffff00", opacity: 1 },
-      { text: "c", color: "#000000", backgroundColor: "#ffff00", opacity: 1 },
-    ]);
-    expect(rows[0].hash).not.toBe(buildRows({ grid, resolver })[0].hash);
-  });
-
-  test("splits Claude box drawing from font text at exact terminal columns", () => {
-    const resolver = createTerminalCellStyleResolver(DEFAULT_TERMINAL_THEME);
-    const frame = "╭─ Claude Code ───╮";
-
-    const [row] = buildRows({
-      grid: [frame.split("").map((char) => cell(char, { fg: 1, fgMode: 1 }))],
-      resolver,
-    });
-
-    expect(
-      row.runs.map((run) => ({
-        text: run.text,
-        cellCount: run.cellCount,
-        renderKind: run.renderKind,
-      })),
-    ).toEqual([
-      { text: "╭─", cellCount: 2, renderKind: "custom-glyph" },
-      { text: " Claude Code ", cellCount: 13, renderKind: "text" },
-      { text: "───╮", cellCount: 4, renderKind: "custom-glyph" },
-    ]);
-  });
-
-  test("keeps Claude mascot glyphs custom while preserving copied row text", () => {
-    const resolver = createTerminalCellStyleResolver(DEFAULT_TERMINAL_THEME);
-    const mascot = "▐▛███▜▌   Claude Code";
-
-    const [row] = buildRows({
-      grid: [mascot.split("").map((char) => cell(char, { fg: 1, fgMode: 1 }))],
-      resolver,
-    });
-
-    expect(row.runs.map((run) => [run.text, run.renderKind])).toEqual([
-      ["▐▛███▜▌", "custom-glyph"],
-      ["   Claude Code", "text"],
-    ]);
-    expect(row.runs.map((run) => run.text).join("")).toBe(mascot);
-  });
-});
diff --git a/packages/app/src/terminal/native-renderer/terminal-row-model.ts b/packages/app/src/terminal/native-renderer/terminal-row-model.ts
deleted file mode 100644
index a65f39fd44..0000000000
--- a/packages/app/src/terminal/native-renderer/terminal-row-model.ts
+++ /dev/null
@@ -1,253 +0,0 @@
-import type { TextStyle } from "react-native";
-import type { TerminalCell } from "@getpaseo/protocol/messages";
-
-import type { TerminalCellStyleResolver } from "./colors";
-import { resolveTerminalCustomGlyph, type TerminalCustomGlyph } from "./terminal-custom-glyph";
-import type { TerminalSelectionRange } from "./terminal-selection";
-
-const WIDE_CHAR_RANGES: ReadonlyArray<readonly [number, number]> = [
-  [0x1100, 0x115f],
-  [0x2329, 0x232a],
-  [0x2e80, 0xa4cf],
-  [0xac00, 0xd7a3],
-  [0xf900, 0xfaff],
-  [0xfe10, 0xfe19],
-  [0xfe30, 0xfe6f],
-  [0xff00, 0xff60],
-  [0xffe0, 0xffe6],
-  [0x1f300, 0x1faff],
-];
-
-interface TerminalRunBase {
-  key: string;
-  text: string;
-  cellCount: number;
-  styleKey: string;
-  style: TextStyle;
-  foregroundColor: string;
-}
-
-export interface TerminalTextRun extends TerminalRunBase {
-  renderKind: "text";
-}
-
-export interface TerminalCustomGlyphRun extends TerminalRunBase {
-  renderKind: "custom-glyph";
-  glyphs: TerminalCustomGlyphCell[];
-}
-
-export type TerminalRun = TerminalCustomGlyphRun | TerminalTextRun;
-
-export interface TerminalCustomGlyphCell {
-  key: string;
-  offset: number;
-  glyph: TerminalCustomGlyph;
-}
-
-export interface TerminalRowModel {
-  index: number;
-  hash: string;
-  runs: TerminalRun[];
-}
-
-type TerminalRenderableCell = TerminalCell & { width?: number };
-
-interface TerminalRowSelectionStyle {
-  range: TerminalSelectionRange;
-  firstRow: number;
-  backgroundColor: string;
-  foregroundColor: string;
-}
-
-function hashStringPart(hash: number, value: string): number {
-  let nextHash = hash;
-  for (let index = 0; index < value.length; index += 1) {
-    nextHash = Math.imul(nextHash ^ value.charCodeAt(index), 16777619);
-  }
-  return nextHash;
-}
-
-function finishHash(hash: number): string {
-  return (hash >>> 0).toString(36);
-}
-
-function terminalCharWidth(char: string): number {
-  const codePoint = char.codePointAt(0);
-  if (codePoint === undefined) return 1;
-  const isWide = WIDE_CHAR_RANGES.some(([start, end]) => codePoint >= start && codePoint <= end);
-  return isWide ? 2 : 1;
-}
-
-function shouldSkipSpacerCell(cells: TerminalRenderableCell[], col: number, char: string): boolean {
-  if (terminalCharWidth(char) < 2) {
-    return false;
-  }
-  return cells[col + 1]?.char === " ";
-}
-
-function terminalCellCount(cells: TerminalRenderableCell[], col: number, char: string): number {
-  const authoritativeWidth = cells[col]?.width;
-  if (authoritativeWidth !== undefined) {
-    return Math.max(1, authoritativeWidth);
-  }
-  if (shouldSkipSpacerCell(cells, col, char)) {
-    return 2;
-  }
-  return 1;
-}
-
-function appendRun(input: {
-  runs: TerminalRun[];
-  text: string;
-  cellCount: number;
-  styleKey: string;
-  style: TextStyle;
-  foregroundColor: string;
-  customGlyph: TerminalCustomGlyph | null;
-  col: number;
-}): void {
-  const renderKind = input.customGlyph ? "custom-glyph" : "text";
-  const previousRun = input.runs[input.runs.length - 1];
-  if (
-    previousRun &&
-    previousRun.styleKey === input.styleKey &&
-    previousRun.renderKind === renderKind
-  ) {
-    const offset = previousRun.cellCount;
-    previousRun.text += input.text;
-    previousRun.cellCount += input.cellCount;
-    if (previousRun.renderKind === "custom-glyph" && input.customGlyph) {
-      previousRun.glyphs.push({
-        key: `${input.col}:${input.text}`,
-        offset,
-        glyph: input.customGlyph,
-      });
-    }
-    return;
-  }
-
-  const baseRun: TerminalRunBase = {
-    key: `${input.col}:${input.styleKey}`,
-    text: input.text,
-    cellCount: input.cellCount,
-    styleKey: input.styleKey,
-    style: input.style,
-    foregroundColor: input.foregroundColor,
-  };
-  if (input.customGlyph) {
-    input.runs.push({
-      ...baseRun,
-      renderKind: "custom-glyph",
-      glyphs: [{ key: `${input.col}:${input.text}`, offset: 0, glyph: input.customGlyph }],
-    });
-    return;
-  }
-  input.runs.push({ ...baseRun, renderKind: "text" });
-}
-
-function cellIntersectsSelection(input: {
-  selection: TerminalRowSelectionStyle;
-  row: number;
-  col: number;
-  cellCount: number;
-}): boolean {
-  const absoluteRow = input.selection.firstRow + input.row;
-  const { start, end } = input.selection.range;
-  if (absoluteRow < start.row || absoluteRow > end.row) {
-    return false;
-  }
-
-  const selectedStartCol = absoluteRow === start.row ? start.col : 0;
-  const selectedEndCol = absoluteRow === end.row ? end.col : Number.POSITIVE_INFINITY;
-  const cellEndCol = input.col + input.cellCount - 1;
-  return cellEndCol >= selectedStartCol && input.col <= selectedEndCol;
-}
-
-function selectedCellStyle(input: {
-  style: TextStyle;
-  foregroundColor: string;
-  backgroundColor: string;
-}): TextStyle {
-  return {
-    ...input.style,
-    backgroundColor: input.backgroundColor,
-    color: input.foregroundColor,
-    opacity: 1,
-    ...(input.style.textDecorationLine
-      ? { textDecorationColor: input.foregroundColor }
-      : undefined),
-  };
-}
-
-function buildRowModel(input: {
-  cells: TerminalRenderableCell[];
-  index: number;
-  resolver: TerminalCellStyleResolver;
-  selection?: TerminalRowSelectionStyle;
-}): TerminalRowModel {
-  const runs: TerminalRun[] = [];
-  let hash = 2166136261;
-
-  for (let col = 0; col < input.cells.length; col += 1) {
-    const cell = input.cells[col];
-    const text = cell.char || " ";
-    const resolvedStyle = input.resolver.resolve(cell);
-    const cellCount = terminalCellCount(input.cells, col, text);
-    const customGlyph = resolveTerminalCustomGlyph(text);
-    const selection = input.selection;
-    let styleKey = resolvedStyle.key;
-    let style = resolvedStyle.style;
-    let foregroundColor = resolvedStyle.foregroundColor;
-    if (
-      selection &&
-      cellIntersectsSelection({
-        selection,
-        row: input.index,
-        col,
-        cellCount,
-      })
-    ) {
-      styleKey = `${resolvedStyle.key}|selection:${selection.foregroundColor}:${selection.backgroundColor}`;
-      style = selectedCellStyle({
-        style: resolvedStyle.style,
-        foregroundColor: selection.foregroundColor,
-        backgroundColor: selection.backgroundColor,
-      });
-      foregroundColor = selection.foregroundColor;
-    }
-    appendRun({
-      runs,
-      text,
-      cellCount,
-      styleKey,
-      style,
-      foregroundColor,
-      customGlyph,
-      col,
-    });
-    hash = hashStringPart(hash, text);
-    hash = hashStringPart(hash, String(cellCount));
-    hash = hashStringPart(hash, styleKey);
-    hash = hashStringPart(hash, customGlyph ? "custom-glyph" : "text");
-
-    if (cellCount > 1) {
-      col += 1;
-    }
-  }
-
-  return {
-    index: input.index,
-    hash: finishHash(hash),
-    runs,
-  };
-}
-
-export function buildRows(input: {
-  grid: TerminalRenderableCell[][];
-  resolver: TerminalCellStyleResolver;
-  selection?: TerminalRowSelectionStyle;
-}): TerminalRowModel[] {
-  return input.grid.map((cells, index) =>
-    buildRowModel({ cells, index, resolver: input.resolver, selection: input.selection }),
-  );
-}
diff --git a/packages/app/src/terminal/native-renderer/terminal-scrollback.test.ts b/packages/app/src/terminal/native-renderer/terminal-scrollback.test.ts
index 3464bcd973..6bacdc0472 100644
--- a/packages/app/src/terminal/native-renderer/terminal-scrollback.test.ts
+++ b/packages/app/src/terminal/native-renderer/terminal-scrollback.test.ts
@@ -54,16 +54,19 @@ describe("native terminal scrollback retention", () => {
       scrollbackLines: SCROLLBACK,
       lineCount: SCROLLBACK + ROWS + 10,
     });
-    const state = terminal.getState();
     const bounds = terminal.getBufferBounds();
 
-    expect(state.scrollback.length).toBeGreaterThan(0);
-    expect(state.scrollback.length).toBeLessThanOrEqual(SCROLLBACK);
+    const historyRows = bounds.bottomViewport.firstRow - bounds.oldestRow;
+    expect(historyRows).toBeGreaterThan(0);
+    expect(historyRows).toBeLessThanOrEqual(SCROLLBACK);
     expect(bounds.newestRow).toBeGreaterThan(ROWS);
     expect(bounds.oldestRow).toBeGreaterThan(0);
-    expect(bounds.newestRow - bounds.oldestRow + 1).toBe(
-      state.scrollback.length + state.grid.length,
-    );
+    const retained = terminal.getBufferWindow({
+      startRow: bounds.oldestRow,
+      rowCount: SCROLLBACK + ROWS + 1,
+    });
+    expect(retained.rows).toHaveLength(SCROLLBACK + ROWS);
+    expect(rowText(retained.rows[0]!)).toBe(expectedBenchmarkLine(bounds.oldestRow));
   });
 
   test("observable scrollback count is bounded by configured lines", async () => {
@@ -73,9 +76,9 @@ describe("native terminal scrollback retention", () => {
       scrollbackLines: SCROLLBACK,
       lineCount: SCROLLBACK * 3,
     });
-    const state = terminal.getState();
 
-    expect(state.scrollback.length).toBe(SCROLLBACK);
+    const bounds = terminal.getBufferBounds();
+    expect(bounds.bottomViewport.firstRow - bounds.oldestRow).toBe(SCROLLBACK);
   });
 
   test("scroll up moves viewport into retained history", async () => {
diff --git a/packages/app/src/terminal/native-renderer/terminal-selection-controller.test.ts b/packages/app/src/terminal/native-renderer/terminal-selection-controller.test.ts
new file mode 100644
index 0000000000..b71c264434
--- /dev/null
+++ b/packages/app/src/terminal/native-renderer/terminal-selection-controller.test.ts
@@ -0,0 +1,411 @@
+import { describe, expect, it } from "vitest";
+import { createNativeHeadlessTerminal } from "./headless-terminal-state";
+import {
+  createTerminalSelectionModel,
+  extractTerminalSelectedText,
+  resolveTerminalSelectionRects,
+} from "./terminal-selection";
+import {
+  createTerminalSelectionController,
+  terminalSelectionHandles,
+} from "./terminal-selection-controller";
+
+describe("selection handle controller", () => {
+  it("preserves the grab offset while moving a handle", () => {
+    const range = { start: { row: 1, col: 2 }, end: { row: 1, col: 5 }, coordinateEpoch: 0 };
+    const moves: Array<{ row: number; col: number }> = [];
+    const controller = createTerminalSelectionController({
+      getGeometry: () => ({
+        range,
+        viewport: { firstRow: 0, rows: 10, cols: 10 },
+        metrics: { cellWidth: 10, cellHeight: 10 },
+      }),
+      onBeginHandle: () => {},
+      onMoveHandle: (coordinate) => moves.push(coordinate),
+      onLongPress: () => {},
+      onTap: () => {},
+      onScroll: () => {},
+      schedule: () => 1,
+      cancel: () => {},
+    });
+    controller.press({ x: 23, y: 15 });
+    controller.move({ x: 63, y: 15 });
+    controller.release();
+    expect(moves).toEqual([{ row: 1, col: 5 }]);
+  });
+});
+
+it("selects on hold, preserves a handle tap, and cancels an active drag", () => {
+  const actions: string[] = [];
+  let timer: (() => void) | null = null;
+  const controller = createTerminalSelectionController({
+    getGeometry: () => ({
+      range: { start: { row: 2, col: 2 }, end: { row: 2, col: 5 }, coordinateEpoch: 0 },
+      viewport: { firstRow: 0, rows: 10, cols: 10 },
+      metrics: { cellWidth: 10, cellHeight: 10 },
+    }),
+    onBeginHandle: (endpoint) => actions.push(endpoint),
+    onMoveHandle: () => actions.push("move"),
+    onLongPress: () => actions.push("long"),
+    onTap: () => actions.push("tap"),
+    onScroll: () => actions.push("scroll"),
+    schedule: (callback) => {
+      timer = callback;
+      return 1;
+    },
+    cancel: () => {
+      timer = null;
+    },
+  });
+  controller.press({ x: 90, y: 80 });
+  (timer as (() => void) | null)?.();
+  controller.release();
+  controller.press({ x: 20, y: 25 });
+  controller.release();
+  controller.press({ x: 20, y: 25 });
+  controller.cancel();
+  controller.move({ x: 50, y: 25 });
+  expect(actions).toEqual(["long", "start", "start"]);
+});
+
+it("scrolls selection into history while holding a handle at the edge", () => {
+  let firstRow = 10;
+  let timer: (() => void) | null = null;
+  const coordinates: Array<{ row: number; col: number }> = [];
+  const controller = createTerminalSelectionController({
+    getGeometry: () => ({
+      range: { start: { row: 12, col: 2 }, end: { row: 13, col: 5 }, coordinateEpoch: 0 },
+      viewport: { firstRow, rows: 10, cols: 10 },
+      metrics: { cellWidth: 10, cellHeight: 10 },
+    }),
+    onBeginHandle: () => {},
+    onMoveHandle: (point) => coordinates.push(point),
+    onLongPress: () => {},
+    onTap: () => {},
+    onScroll: (direction) => {
+      if (direction === "up") firstRow--;
+    },
+    schedule: (callback) => {
+      timer = callback;
+      return 1;
+    },
+    cancel: () => {
+      timer = null;
+    },
+  });
+  controller.press({ x: 20, y: 25 });
+  controller.move({ x: 20, y: 1 });
+  (timer as (() => void) | null)?.();
+  (timer as (() => void) | null)?.();
+  controller.release();
+  expect(coordinates).toEqual([
+    { row: 10, col: 2 },
+    { row: 9, col: 2 },
+    { row: 8, col: 2 },
+  ]);
+  expect(timer).toBeNull();
+});
+
+it("scrolls outside handles without clearing selection and clears on an outside tap", () => {
+  const actions: string[] = [];
+  const controller = createTerminalSelectionController({
+    getGeometry: () => ({
+      range: { start: { row: 2, col: 2 }, end: { row: 2, col: 5 }, coordinateEpoch: 0 },
+      viewport: { firstRow: 0, rows: 10, cols: 10 },
+      metrics: { cellWidth: 10, cellHeight: 10 },
+    }),
+    onBeginHandle: () => actions.push("handle"),
+    onMoveHandle: () => actions.push("move"),
+    onLongPress: () => actions.push("long"),
+    onTap: () => actions.push("tap"),
+    onScroll: (direction, rows) => actions.push(`${direction}:${rows}`),
+    schedule: () => 1,
+    cancel: () => {},
+  });
+  controller.press({ x: 95, y: 70 });
+  controller.move({ x: 95, y: 90 });
+  controller.release();
+  controller.press({ x: 95, y: 70 });
+  controller.release();
+  expect(actions).toEqual(["up:2", "tap"]);
+});
+
+it("extends the selection after a long press and drag", () => {
+  let timer: (() => void) | null = null;
+  const moves: Array<{ row: number; col: number }> = [];
+  const controller = createTerminalSelectionController({
+    getGeometry: () => ({
+      range: null,
+      viewport: { firstRow: 0, rows: 10, cols: 10 },
+      metrics: { cellWidth: 10, cellHeight: 10 },
+    }),
+    onBeginHandle: () => {},
+    onMoveHandle: (coordinate) => moves.push(coordinate),
+    onLongPress: () => {},
+    onTap: () => {},
+    onScroll: () => {},
+    schedule: (callback) => {
+      timer = callback;
+      return 1;
+    },
+    cancel: () => {
+      timer = null;
+    },
+  });
+  controller.press({ x: 25, y: 25 });
+  (timer as (() => void) | null)?.();
+  controller.move({ x: 65, y: 35 });
+  controller.release();
+  expect(moves).toEqual([{ row: 3, col: 6 }]);
+});
+
+it.each([
+  {
+    endpoint: "start" as const,
+    startX: 20,
+    crossedX: 80,
+    crossedText: "gh",
+    crossedStart: 6,
+    crossedEnd: 7,
+    backX: 10,
+    backText: "bcdef",
+    backStart: 1,
+    backEnd: 5,
+  },
+  {
+    endpoint: "end" as const,
+    startX: 60,
+    crossedX: 10,
+    crossedText: "b",
+    crossedStart: 1,
+    crossedEnd: 1,
+    backX: 80,
+    backText: "cdefgh",
+    backStart: 2,
+    backEnd: 7,
+  },
+])("tracks the $endpoint handle through crossing and back", async (scenario) => {
+  const terminal = createNativeHeadlessTerminal({ rows: 4, cols: 10 });
+  try {
+    await terminal.write("abcdefghij");
+    const bounds = terminal.getBufferBounds();
+    const model = createTerminalSelectionModel();
+    model.begin({ coordinate: { row: 0, col: 2 }, bounds });
+    model.update({ coordinate: { row: 0, col: 5 }, bounds });
+    const viewport = { firstRow: 0, rows: 4, cols: 10 };
+    const metrics = { cellWidth: 10, cellHeight: 10 };
+    const geometry = () => ({ range: model.getSnapshot().range, viewport, metrics });
+    const controller = createTerminalSelectionController({
+      getGeometry: geometry,
+      onBeginHandle: (endpoint, cols) => model.beginEndpointDrag(endpoint, cols),
+      onMoveHandle: (coordinate) => {
+        model.update({ coordinate, bounds });
+      },
+      onLongPress: () => {},
+      onTap: () => {},
+      onScroll: () => {},
+      schedule: () => 1,
+      cancel: () => {},
+    });
+    const check = (start: number, end: number, text: string) => {
+      const range = model.getSnapshot().range;
+      expect(range).toEqual({
+        start: { row: 0, col: start },
+        end: { row: 0, col: end },
+        coordinateEpoch: bounds.coordinateEpoch,
+      });
+      expect(terminalSelectionHandles(geometry())).toMatchObject([
+        { endpoint: "start", x: start * 10, y: 5 },
+        { endpoint: "end", x: (end + 1) * 10, y: 5 },
+      ]);
+      expect(resolveTerminalSelectionRects({ selection: range, viewport, metrics })).toEqual([
+        {
+          key: `0:${start}:${end}`,
+          x: start * 10,
+          y: 0,
+          width: (end - start + 1) * 10,
+          height: 10,
+        },
+      ]);
+      expect(extractTerminalSelectedText({ terminal, selection: range })).toBe(text);
+    };
+    controller.press({ x: scenario.startX, y: 5 });
+    controller.move({ x: scenario.crossedX, y: 5 });
+    check(scenario.crossedStart, scenario.crossedEnd, scenario.crossedText);
+    controller.move({ x: scenario.backX, y: 5 });
+    check(scenario.backStart, scenario.backEnd, scenario.backText);
+    controller.release();
+  } finally {
+    terminal.dispose();
+  }
+});
+
+it.each([
+  {
+    endpoint: "end" as const,
+    initialRow: 0,
+    targetRow: 1,
+    targetX: 0,
+    expectedRow: 0,
+    expectedCol: 9,
+    text: "cdefghij",
+  },
+  {
+    endpoint: "start" as const,
+    initialRow: 1,
+    targetRow: 0,
+    targetX: 100,
+    expectedRow: 1,
+    expectedCol: 0,
+    text: "KLMNOP",
+  },
+])("preserves a $endpoint boundary at a row edge", async (scenario) => {
+  const terminal = createNativeHeadlessTerminal({ rows: 4, cols: 10 });
+  try {
+    await terminal.write("abcdefghij\r\nKLMNOPQRST");
+    const bounds = terminal.getBufferBounds();
+    const model = createTerminalSelectionModel();
+    model.begin({ coordinate: { row: scenario.initialRow, col: 2 }, bounds });
+    model.update({ coordinate: { row: scenario.initialRow, col: 5 }, bounds });
+    const viewport = { firstRow: 0, rows: 4, cols: 10 };
+    const metrics = { cellWidth: 10, cellHeight: 10 };
+    const geometry = () => ({ range: model.getSnapshot().range, viewport, metrics });
+    const controller = createTerminalSelectionController({
+      getGeometry: geometry,
+      onBeginHandle: (endpoint, cols) => model.beginEndpointDrag(endpoint, cols),
+      onMoveHandle: (coordinate) => {
+        model.update({ coordinate, bounds });
+      },
+      onLongPress: () => {},
+      onTap: () => {},
+      onScroll: () => {},
+      schedule: () => 1,
+      cancel: () => {},
+    });
+    controller.press({ x: scenario.endpoint === "end" ? 60 : 20, y: scenario.initialRow * 10 + 5 });
+    controller.move({ x: scenario.targetX, y: scenario.targetRow * 10 + 5 });
+    const range = model.getSnapshot().range;
+    expect(range?.[scenario.endpoint]).toEqual({
+      row: scenario.expectedRow,
+      col: scenario.expectedCol,
+    });
+    expect(extractTerminalSelectedText({ terminal, selection: range })).toBe(scenario.text);
+    expect(
+      terminalSelectionHandles(geometry()).find((handle) => handle.endpoint === scenario.endpoint),
+    ).toMatchObject({
+      x: scenario.endpoint === "end" ? 100 : 0,
+      y: scenario.expectedRow * 10 + 5,
+    });
+    controller.release();
+  } finally {
+    terminal.dispose();
+  }
+});
+
+it("cancels a drag when buffer coordinates are invalidated", () => {
+  const model = createTerminalSelectionModel();
+  const bounds = { oldestRow: 0, newestRow: 9, coordinateEpoch: 0 };
+  model.begin({ coordinate: { row: 2, col: 2 }, bounds });
+  model.update({ coordinate: { row: 2, col: 5 }, bounds });
+  const viewport = { firstRow: 0, rows: 10, cols: 10 };
+  const metrics = { cellWidth: 10, cellHeight: 10 };
+  const controller = createTerminalSelectionController({
+    getGeometry: () => ({ range: model.getSnapshot().range, viewport, metrics }),
+    onBeginHandle: (endpoint, cols) => model.beginEndpointDrag(endpoint, cols),
+    onMoveHandle: (coordinate) => {
+      model.update({ coordinate, bounds });
+    },
+    onLongPress: () => {},
+    onTap: () => {},
+    onScroll: () => {},
+    schedule: () => 1,
+    cancel: () => {},
+  });
+  controller.press({ x: 20, y: 25 });
+  const previous = model.getSnapshot().range;
+  const snapshot = model.sync({ bounds: { ...bounds, coordinateEpoch: 1 } });
+  if (previous && !snapshot.range) controller.cancel();
+  controller.move({ x: 80, y: 25 });
+  controller.release();
+  expect(model.getSnapshot().range).toBeNull();
+});
+
+it("preserves a newly selected word through small movement at the viewport edge", () => {
+  const model = createTerminalSelectionModel();
+  const bounds = { oldestRow: 0, newestRow: 9, coordinateEpoch: 0 };
+  let timer: (() => void) | null = null;
+  const controller = createTerminalSelectionController({
+    getGeometry: () => ({
+      range: model.getSnapshot().range,
+      viewport: { firstRow: 0, rows: 10, cols: 20 },
+      metrics: { cellWidth: 10, cellHeight: 10 },
+    }),
+    onBeginHandle: (endpoint, cols) => model.beginEndpointDrag(endpoint, cols),
+    onMoveHandle: (coordinate) => {
+      model.update({ coordinate, bounds });
+    },
+    onLongPress: () => {
+      model.begin({ coordinate: { row: 0, col: 2 }, bounds });
+      model.update({ coordinate: { row: 0, col: 6 }, bounds });
+    },
+    onTap: () => {},
+    onScroll: () => {},
+    schedule: (callback) => {
+      timer = callback;
+      return 1;
+    },
+    cancel: () => {
+      timer = null;
+    },
+  });
+  controller.press({ x: 45, y: 5 });
+  const fire = timer as (() => void) | null;
+  timer = null;
+  fire?.();
+  controller.move({ x: 44, y: 4 });
+  controller.release();
+  expect(model.getSnapshot().range).toEqual({
+    start: { row: 0, col: 2 },
+    end: { row: 0, col: 6 },
+    coordinateEpoch: 0,
+  });
+  expect(timer).toBeNull();
+});
+
+it("places mirrored teardrop grips below the selected row", () => {
+  const handles = terminalSelectionHandles({
+    range: { start: { row: 2, col: 2 }, end: { row: 2, col: 5 }, coordinateEpoch: 0 },
+    viewport: { firstRow: 0, rows: 10, cols: 10 },
+    metrics: { cellWidth: 10, cellHeight: 10 },
+  });
+  expect(handles).toMatchObject([
+    { endpoint: "start", x: 20, y: 25, gripX: 11, gripY: 39, gripDirection: "left" },
+    { endpoint: "end", x: 60, y: 25, gripX: 69, gripY: 39, gripDirection: "right" },
+  ]);
+});
+
+it("keeps edge grips reachable and preserves the offset from the cell when dragging a grip", () => {
+  const range = { start: { row: 0, col: 0 }, end: { row: 9, col: 9 }, coordinateEpoch: 0 };
+  const viewport = { firstRow: 0, rows: 10, cols: 10 };
+  const metrics = { cellWidth: 10, cellHeight: 10 };
+  const handles = terminalSelectionHandles({ range, viewport, metrics });
+  expect(handles.map(({ gripX, gripY }) => ({ gripX, gripY }))).toEqual([
+    { gripX: 9, gripY: 19 },
+    { gripX: 91, gripY: 81 },
+  ]);
+  const moves: Array<{ row: number; col: number }> = [];
+  const controller = createTerminalSelectionController({
+    getGeometry: () => ({ range, viewport, metrics }),
+    onBeginHandle: () => {},
+    onMoveHandle: (coordinate) => moves.push(coordinate),
+    onLongPress: () => {},
+    onTap: () => {},
+    onScroll: () => {},
+    schedule: () => 1,
+    cancel: () => {},
+  });
+  controller.press({ x: 9, y: 19 });
+  controller.move({ x: 19, y: 29 });
+  controller.release();
+  expect(moves).toEqual([{ row: 1, col: 1 }]);
+});
diff --git a/packages/app/src/terminal/native-renderer/terminal-selection-controller.ts b/packages/app/src/terminal/native-renderer/terminal-selection-controller.ts
new file mode 100644
index 0000000000..721fd501d7
--- /dev/null
+++ b/packages/app/src/terminal/native-renderer/terminal-selection-controller.ts
@@ -0,0 +1,208 @@
+import type { TerminalGridCellMetrics } from "./terminal-grid-metrics";
+import type {
+  TerminalBufferCoordinate,
+  TerminalSelectionPoint,
+  TerminalSelectionRange,
+  TerminalSelectionViewport,
+} from "./terminal-selection";
+export const TERMINAL_SELECTION_GRIP_SIZE = 18;
+const TERMINAL_GESTURE_LONG_PRESS_MS = 450;
+const TERMINAL_GESTURE_TAP_TOLERANCE_PX = 8;
+
+type Endpoint = "start" | "end";
+interface Geometry {
+  range: TerminalSelectionRange | null;
+  viewport: TerminalSelectionViewport;
+  metrics: TerminalGridCellMetrics;
+}
+interface Ports {
+  getGeometry(): Geometry | null;
+  onBeginHandle(endpoint: Endpoint, cols: number): void;
+  onMoveHandle(coordinate: TerminalBufferCoordinate): void;
+  onLongPress(point: TerminalSelectionPoint): void;
+  onTap(): void;
+  onScroll(direction: "up" | "down", rows: number): void;
+  schedule(callback: () => void, delay: number): number;
+  cancel(timer: number): void;
+}
+
+export function terminalSelectionHandles(geometry: Geometry): Array<{
+  endpoint: Endpoint;
+  x: number;
+  y: number;
+  gripX: number;
+  gripY: number;
+  gripDirection: "left" | "right";
+  gripAbove: boolean;
+  stemTop: number;
+  stemHeight: number;
+}> {
+  const { range, viewport, metrics } = geometry;
+  if (!range) return [];
+  return (["start", "end"] as const).flatMap((endpoint) => {
+    const cell = range[endpoint];
+    if (cell.row < viewport.firstRow || cell.row >= viewport.firstRow + viewport.rows) return [];
+    const x = (cell.col + (endpoint === "end" ? 1 : 0)) * metrics.cellWidth;
+    const stemTop = (cell.row - viewport.firstRow) * metrics.cellHeight;
+    const size = TERMINAL_SELECTION_GRIP_SIZE;
+    const width = viewport.cols * metrics.cellWidth;
+    const height = viewport.rows * metrics.cellHeight;
+    const wantsLeft = endpoint === "start";
+    const gripDirection =
+      (wantsLeft && x >= size) || (!wantsLeft && x > width - size) ? "left" : "right";
+    const gripAbove = stemTop + metrics.cellHeight + size > height;
+    const gripTop = gripAbove ? Math.max(0, stemTop - size) : stemTop + metrics.cellHeight;
+    return [
+      {
+        endpoint,
+        x,
+        y: stemTop + metrics.cellHeight / 2,
+        gripX: x + (gripDirection === "left" ? -size / 2 : size / 2),
+        gripY: gripTop + size / 2,
+        gripDirection,
+        gripAbove,
+        stemTop,
+        stemHeight: metrics.cellHeight,
+      },
+    ];
+  });
+}
+
+export function createTerminalSelectionController(ports: Ports) {
+  let press: {
+    start: TerminalSelectionPoint;
+    point: TerminalSelectionPoint;
+    endpoint: Endpoint | null;
+    offset: TerminalSelectionPoint;
+    fixed: TerminalBufferCoordinate | null;
+    moved: boolean;
+    long: boolean;
+    scrolling: boolean;
+    remainder: number;
+  } | null = null;
+  let timer: number | null = null;
+  function stopTimer() {
+    if (timer !== null) ports.cancel(timer);
+    timer = null;
+  }
+  function updateHandle() {
+    const geometry = ports.getGeometry();
+    if (!press || (!press.endpoint && !press.long) || !geometry) return;
+    const { viewport, metrics } = geometry;
+    const x = press.point.x - press.offset.x;
+    const y = press.point.y - press.offset.y;
+    let row =
+      viewport.firstRow +
+      Math.max(0, Math.min(viewport.rows - 1, Math.floor(y / metrics.cellHeight)));
+    let col = Math.floor(x / metrics.cellWidth);
+    if (press.endpoint && press.fixed) {
+      const boundary = Math.round(x / metrics.cellWidth);
+      const isEnd =
+        row > press.fixed.row || (row === press.fixed.row && boundary > press.fixed.col);
+      col = boundary - (isEnd ? 1 : 0);
+      if (col < 0 && isEnd) {
+        row -= 1;
+        col = viewport.cols - 1;
+      } else if (col >= viewport.cols && !isEnd) {
+        row += 1;
+        col = 0;
+      }
+    }
+    col = Math.max(0, Math.min(viewport.cols - 1, col));
+    ports.onMoveHandle({ row, col });
+  }
+  function edgeTick() {
+    timer = null;
+    const geometry = ports.getGeometry();
+    if (!press || (!press.endpoint && !press.long) || !geometry) return;
+    const y = press.point.y - press.offset.y;
+    const height = geometry.viewport.rows * geometry.metrics.cellHeight;
+    let direction: "up" | "down" | null = null;
+    if (y < geometry.metrics.cellHeight) direction = "up";
+    else if (y > height - geometry.metrics.cellHeight) direction = "down";
+    if (!direction) return;
+    ports.onScroll(direction, 1);
+    if (!press) return;
+    updateHandle();
+    if (press) timer = ports.schedule(edgeTick, 100);
+  }
+  return {
+    press(point: TerminalSelectionPoint) {
+      stopTimer();
+      const geometry = ports.getGeometry();
+      const handles = geometry ? terminalSelectionHandles(geometry) : [];
+      const handle = handles
+        .map((item) => ({
+          endpoint: item.endpoint,
+          x: item.x,
+          y: item.y,
+          distance: Math.hypot(point.x - item.gripX, point.y - item.gripY),
+        }))
+        .filter((item) => item.distance <= 28)
+        .sort((a, b) => a.distance - b.distance)[0];
+      press = {
+        start: point,
+        point,
+        endpoint: handle?.endpoint ?? null,
+        offset: handle ? { x: point.x - handle.x, y: point.y - handle.y } : { x: 0, y: 0 },
+        fixed:
+          handle && geometry?.range
+            ? geometry.range[handle.endpoint === "start" ? "end" : "start"]
+            : null,
+        moved: false,
+        long: false,
+        scrolling: false,
+        remainder: 0,
+      };
+      if (handle && geometry) {
+        ports.onBeginHandle(handle.endpoint, geometry.viewport.cols);
+        return;
+      }
+      timer = ports.schedule(() => {
+        timer = null;
+        if (press && !press.moved) {
+          press.long = true;
+          ports.onLongPress(press.start);
+        }
+      }, TERMINAL_GESTURE_LONG_PRESS_MS);
+    },
+    move(point: TerminalSelectionPoint) {
+      if (!press) return;
+      const previous = press.point;
+      press.point = point;
+      const dx = point.x - press.start.x,
+        dy = point.y - press.start.y;
+      if (Math.hypot(dx, dy) > TERMINAL_GESTURE_TAP_TOLERANCE_PX) {
+        press.moved = true;
+        if (!press.endpoint) stopTimer();
+      }
+      if (press.endpoint || press.long) {
+        if (press.endpoint || press.moved) {
+          updateHandle();
+          stopTimer();
+          if (press) timer = ports.schedule(edgeTick, 100);
+        }
+      } else if (!press.long) {
+        if (!press.scrolling && Math.abs(dy) > 12 && Math.abs(dy) > Math.abs(dx)) {
+          press.scrolling = true;
+          press.remainder = dy;
+        } else if (press.scrolling) press.remainder += point.y - previous.y;
+        const height = ports.getGeometry()?.metrics.cellHeight ?? 0;
+        if (press.scrolling && height > 0) {
+          const rows = Math.trunc(press.remainder / height);
+          press.remainder -= rows * height;
+          if (rows) ports.onScroll(rows > 0 ? "up" : "down", Math.abs(rows));
+        }
+      }
+    },
+    release() {
+      stopTimer();
+      if (press && !press.endpoint && !press.long && !press.moved) ports.onTap();
+      press = null;
+    },
+    cancel() {
+      stopTimer();
+      press = null;
+    },
+  };
+}
diff --git a/packages/app/src/terminal/native-renderer/terminal-selection-gesture.test.ts b/packages/app/src/terminal/native-renderer/terminal-selection-gesture.test.ts
deleted file mode 100644
index aed6857d5c..0000000000
--- a/packages/app/src/terminal/native-renderer/terminal-selection-gesture.test.ts
+++ /dev/null
@@ -1,354 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
-  TERMINAL_GESTURE_LONG_PRESS_MS,
-  TERMINAL_GESTURE_TAP_TOLERANCE_PX,
-  TERMINAL_GESTURE_VERTICAL_SCROLL_THRESHOLD_PX,
-  advanceTerminalScrollGesture,
-  classifyTerminalGestureIntent,
-  resolveTerminalGestureReleaseAction,
-} from "./terminal-selection-gesture";
-
-describe("native terminal gesture policy", () => {
-  describe("advanceTerminalScrollGesture", () => {
-    it("keeps consuming a slow drag after scroll intent arms below one row", () => {
-      let state = { lastDy: 0, rowRemainder: 0, didScroll: false };
-      const rowDeltas: number[] = [];
-
-      for (const currentDy of [13, 15, 18, 22, 28]) {
-        const update = advanceTerminalScrollGesture({
-          state,
-          currentDy,
-          cellHeight: 14,
-        });
-        state = update.state;
-        rowDeltas.push(update.rowDelta);
-      }
-
-      expect({ rowDeltas, state }).toEqual({
-        rowDeltas: [0, 1, 0, 0, 1],
-        state: { lastDy: 28, rowRemainder: 0, didScroll: true },
-      });
-    });
-  });
-
-  describe("classifyTerminalGestureIntent", () => {
-    it("treats a motionless press as a tap", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "pressing",
-          dx: 0,
-          dy: 0,
-          vx: 0,
-          vy: 0,
-        }),
-      ).toEqual("tap");
-    });
-
-    it("treats a tiny jitter within tap tolerance as a tap", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "pressing",
-          dx: TERMINAL_GESTURE_TAP_TOLERANCE_PX - 4,
-          dy: TERMINAL_GESTURE_TAP_TOLERANCE_PX - 4,
-          vx: 0,
-          vy: 0,
-        }),
-      ).toEqual("tap");
-    });
-
-    it("leaves horizontal movement available to terminal selection", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "pressing",
-          dx: TERMINAL_GESTURE_TAP_TOLERANCE_PX + 20,
-          dy: 4,
-          vx: 0,
-          vy: 0,
-        }),
-      ).toEqual("pending");
-    });
-
-    it("does not infer selection from slow horizontal drag dwell", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "pressing",
-          dx: TERMINAL_GESTURE_TAP_TOLERANCE_PX + 40,
-          dy: 3,
-          vx: 0,
-          vy: 0,
-          elapsedMs: TERMINAL_GESTURE_LONG_PRESS_MS + 50,
-        }),
-      ).toEqual("pending");
-    });
-
-    it("keeps tiny horizontal jitter inside tap tolerance as a tap", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "pressing",
-          dx: TERMINAL_GESTURE_TAP_TOLERANCE_PX - 1,
-          dy: 1,
-          vx: 2,
-          vy: 0,
-          elapsedMs: 20,
-        }),
-      ).toEqual("tap");
-    });
-
-    it("keeps horizontal movement below navigation distance pending", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "pressing",
-          dx: TERMINAL_GESTURE_TAP_TOLERANCE_PX + 10,
-          dy: 2,
-          vx: 0,
-          vy: 0,
-        }),
-      ).toEqual("pending");
-    });
-
-    it("treats a clearly vertical drag as scroll", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "pressing",
-          dx: 4,
-          dy: TERMINAL_GESTURE_VERTICAL_SCROLL_THRESHOLD_PX + 5,
-          vx: 0,
-          vy: 0.2,
-        }),
-      ).toEqual("scroll");
-    });
-
-    it("does not navigate on a fast rightward swipe", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "pressing",
-          dx: TERMINAL_GESTURE_TAP_TOLERANCE_PX + 40,
-          dy: 4,
-          vx: 2,
-          vy: 0,
-        }),
-      ).toEqual("pending");
-    });
-
-    it("does not navigate on a slow rightward swipe", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "pressing",
-          dx: TERMINAL_GESTURE_TAP_TOLERANCE_PX + 40,
-          dy: 4,
-          vx: 0,
-          vy: 0,
-        }),
-      ).toEqual("pending");
-    });
-
-    it("does not navigate on a fast leftward swipe", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "pressing",
-          dx: -(TERMINAL_GESTURE_TAP_TOLERANCE_PX + 40),
-          dy: -4,
-          vx: -2,
-          vy: 0,
-        }),
-      ).toEqual("pending");
-    });
-
-    it("does not navigate while movement stays inside tap tolerance", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "pressing",
-          dx: TERMINAL_GESTURE_TAP_TOLERANCE_PX - 1,
-          dy: 2,
-          vx: 2,
-          vy: 0,
-        }),
-      ).toEqual("tap");
-    });
-
-    it("keeps selection intent once selection is active", () => {
-      expect(
-        classifyTerminalGestureIntent({
-          status: "selecting",
-          dx: 100,
-          dy: 50,
-          vx: 2,
-          vy: 1,
-        }),
-      ).toEqual("select");
-    });
-  });
-
-  describe("resolveTerminalGestureReleaseAction", () => {
-    it("focuses the terminal after a normal tap", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "pressing",
-          didScroll: false,
-          didNavigate: false,
-          movedBeyondTapTolerance: false,
-          pressDurationMs: 80,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "following",
-        }),
-      ).toEqual("focus");
-    });
-
-    it("focuses the terminal after a normal tap while scrolled", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "pressing",
-          didScroll: false,
-          didNavigate: false,
-          movedBeyondTapTolerance: false,
-          pressDurationMs: 80,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "scrolled",
-        }),
-      ).toEqual("focus");
-    });
-
-    it("starts selection after a long press", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "pressing",
-          didScroll: false,
-          didNavigate: false,
-          movedBeyondTapTolerance: false,
-          pressDurationMs: TERMINAL_GESTURE_LONG_PRESS_MS + 50,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "following",
-        }),
-      ).toEqual("select");
-    });
-
-    it("starts selection after a 500ms hold", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "pressing",
-          didScroll: false,
-          didNavigate: false,
-          movedBeyondTapTolerance: false,
-          pressDurationMs: 500,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "following",
-        }),
-      ).toEqual("select");
-    });
-
-    it("keeps a 400ms press as a tap", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "pressing",
-          didScroll: false,
-          didNavigate: false,
-          movedBeyondTapTolerance: false,
-          pressDurationMs: 400,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "following",
-        }),
-      ).toEqual("focus");
-    });
-
-    it("does nothing after a scroll gesture", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "pressing",
-          didScroll: true,
-          didNavigate: false,
-          movedBeyondTapTolerance: true,
-          pressDurationMs: 80,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "scrolled",
-        }),
-      ).toEqual("none");
-    });
-
-    it("does nothing after a navigation swipe", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "pressing",
-          didScroll: false,
-          didNavigate: true,
-          movedBeyondTapTolerance: true,
-          pressDurationMs: 80,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "following",
-        }),
-      ).toEqual("none");
-    });
-
-    it("does nothing while actively selecting", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "selecting",
-          didScroll: false,
-          didNavigate: false,
-          movedBeyondTapTolerance: true,
-          pressDurationMs: 80,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "following",
-        }),
-      ).toEqual("none");
-    });
-
-    it("clears an existing selection after a short tap", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "selecting",
-          startedWithSelection: true,
-          didScroll: false,
-          didNavigate: false,
-          movedBeyondTapTolerance: false,
-          pressDurationMs: 80,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "following",
-        }),
-      ).toEqual("clear");
-    });
-
-    it("preserves a word selection created by the current long press", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "selecting",
-          startedWithSelection: false,
-          didScroll: false,
-          didNavigate: false,
-          movedBeyondTapTolerance: false,
-          pressDurationMs: TERMINAL_GESTURE_LONG_PRESS_MS + 50,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "following",
-        }),
-      ).toEqual("none");
-    });
-
-    it("does not focus after an undecided fast drag", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "pressing",
-          didScroll: false,
-          didNavigate: false,
-          movedBeyondTapTolerance: true,
-          pressDurationMs: 80,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "following",
-        }),
-      ).toEqual("none");
-    });
-
-    it("does nothing from idle", () => {
-      expect(
-        resolveTerminalGestureReleaseAction({
-          status: "idle",
-          didScroll: false,
-          didNavigate: false,
-          movedBeyondTapTolerance: false,
-          pressDurationMs: 80,
-          longPressMs: TERMINAL_GESTURE_LONG_PRESS_MS,
-          scrollMode: "following",
-        }),
-      ).toEqual("none");
-    });
-  });
-});
diff --git a/packages/app/src/terminal/native-renderer/terminal-selection-gesture.ts b/packages/app/src/terminal/native-renderer/terminal-selection-gesture.ts
deleted file mode 100644
index 07b5267e87..0000000000
--- a/packages/app/src/terminal/native-renderer/terminal-selection-gesture.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-export type TerminalGestureStatus = "idle" | "pressing" | "selecting";
-export type TerminalGestureIntent = "tap" | "pending" | "select" | "scroll";
-export type TerminalGestureScrollMode = "following" | "scrolled";
-
-export interface TerminalGestureMoveInput {
-  status: TerminalGestureStatus;
-  dx: number;
-  dy: number;
-  vx: number;
-  vy: number;
-  elapsedMs?: number;
-}
-
-export interface TerminalGestureReleaseInput {
-  status: TerminalGestureStatus;
-  startedWithSelection?: boolean;
-  didScroll: boolean;
-  didNavigate: boolean;
-  movedBeyondTapTolerance: boolean;
-  pressDurationMs: number;
-  longPressMs: number;
-  scrollMode: TerminalGestureScrollMode;
-}
-
-export interface TerminalScrollGestureState {
-  lastDy: number;
-  rowRemainder: number;
-  didScroll: boolean;
-}
-
-export interface TerminalScrollGestureUpdate {
-  state: TerminalScrollGestureState;
-  rowDelta: number;
-}
-
-export type TerminalGestureAction = "none" | "focus" | "select" | "clear";
-
-export const TERMINAL_GESTURE_TAP_TOLERANCE_PX = 8;
-export const TERMINAL_GESTURE_LONG_PRESS_MS = 450;
-export const TERMINAL_GESTURE_VERTICAL_SCROLL_THRESHOLD_PX = 12;
-
-export function classifyTerminalGestureIntent(
-  input: TerminalGestureMoveInput,
-): TerminalGestureIntent {
-  if (input.status === "selecting") {
-    return "select";
-  }
-
-  const absDx = Math.abs(input.dx);
-  const absDy = Math.abs(input.dy);
-
-  if (absDy > TERMINAL_GESTURE_VERTICAL_SCROLL_THRESHOLD_PX && absDy > absDx) {
-    return "scroll";
-  }
-
-  if (Math.hypot(input.dx, input.dy) > TERMINAL_GESTURE_TAP_TOLERANCE_PX) {
-    return "pending";
-  }
-
-  return "tap";
-}
-
-export function advanceTerminalScrollGesture(input: {
-  state: TerminalScrollGestureState;
-  currentDy: number;
-  cellHeight: number;
-}): TerminalScrollGestureUpdate {
-  const deltaY = input.currentDy - input.state.lastDy;
-  const accumulatedRows = input.state.rowRemainder + deltaY;
-  const rowDelta = Math.trunc(accumulatedRows / input.cellHeight);
-  return {
-    state: {
-      lastDy: input.currentDy,
-      rowRemainder: accumulatedRows - rowDelta * input.cellHeight,
-      didScroll: input.state.didScroll || rowDelta !== 0,
-    },
-    rowDelta,
-  };
-}
-
-export function resolveTerminalGestureReleaseAction(
-  input: TerminalGestureReleaseInput,
-): TerminalGestureAction {
-  if (input.didScroll || input.didNavigate) {
-    return "none";
-  }
-
-  if (input.status === "selecting") {
-    if (!input.startedWithSelection) {
-      return "none";
-    }
-    return input.movedBeyondTapTolerance ? "none" : "clear";
-  }
-
-  if (input.status !== "pressing") {
-    return "none";
-  }
-
-  if (input.pressDurationMs >= input.longPressMs) {
-    return "select";
-  }
-
-  if (input.movedBeyondTapTolerance) {
-    return "none";
-  }
-
-  return "focus";
-}
diff --git a/packages/app/src/terminal/native-renderer/terminal-selection.test.ts b/packages/app/src/terminal/native-renderer/terminal-selection.test.ts
index c188671ffe..6141bf1efd 100644
--- a/packages/app/src/terminal/native-renderer/terminal-selection.test.ts
+++ b/packages/app/src/terminal/native-renderer/terminal-selection.test.ts
@@ -483,3 +483,51 @@ describe("native terminal selection", () => {
     expect(copied).toEqual([]);
   });
 });
+
+describe("endpoint dragging", () => {
+  it.each([
+    {
+      endpoint: "start" as const,
+      fixed: { row: 2, col: 9 },
+      target: { row: 3, col: 2 },
+      expected: { row: 3, col: 0 },
+    },
+    {
+      endpoint: "end" as const,
+      fixed: { row: 2, col: 0 },
+      target: { row: 1, col: 7 },
+      expected: { row: 1, col: 9 },
+    },
+  ])(
+    "preserves the fixed boundary across a row edge for $endpoint",
+    ({ endpoint, fixed, target, expected }) => {
+      const selection = createTerminalSelectionModel();
+      const bounds = { oldestRow: 0, newestRow: 10, coordinateEpoch: 1 };
+      selection.begin({ coordinate: fixed, bounds });
+      selection.update({ coordinate: fixed, bounds });
+      selection.beginEndpointDrag(endpoint, 10);
+      selection.update({ coordinate: target, bounds });
+      expect(selection.getSnapshot().range?.[endpoint === "start" ? "start" : "end"]).toEqual(
+        expected,
+      );
+    },
+  );
+
+  it.each(["start", "end"] as const)(
+    "keeps the opposite endpoint fixed as %s crosses it",
+    (endpoint) => {
+      const selection = createTerminalSelectionModel();
+      const bounds = { oldestRow: 0, newestRow: 10, coordinateEpoch: 1 };
+      selection.begin({ coordinate: { row: 2, col: 2 }, bounds });
+      selection.update({ coordinate: { row: 3, col: 4 }, bounds });
+      selection.beginEndpointDrag(endpoint, 10);
+      const coordinate = endpoint === "start" ? { row: 4, col: 5 } : { row: 1, col: 1 };
+      selection.update({ coordinate, bounds });
+      expect(selection.getSnapshot().range).toEqual(
+        endpoint === "start"
+          ? { start: { row: 3, col: 5 }, end: coordinate, coordinateEpoch: 1 }
+          : { start: coordinate, end: { row: 2, col: 1 }, coordinateEpoch: 1 },
+      );
+    },
+  );
+});
diff --git a/packages/app/src/terminal/native-renderer/terminal-selection.ts b/packages/app/src/terminal/native-renderer/terminal-selection.ts
index 450a3813ac..0f7391e669 100644
--- a/packages/app/src/terminal/native-renderer/terminal-selection.ts
+++ b/packages/app/src/terminal/native-renderer/terminal-selection.ts
@@ -25,6 +25,7 @@ export interface TerminalSelectionBounds {
 export interface TerminalSelectionModel {
   begin(input: TerminalSelectionUpdateInput): TerminalSelectionSnapshot;
   update(input: TerminalSelectionUpdateInput): TerminalSelectionSnapshot;
+  beginEndpointDrag(endpoint: "start" | "end", cols: number): void;
   clear(): TerminalSelectionSnapshot;
   sync(input: TerminalSelectionSyncInput): TerminalSelectionSnapshot;
   getSnapshot(): TerminalSelectionSnapshot;
@@ -252,6 +253,7 @@ export function resolveTerminalSelectionRects(
 
 export function createTerminalSelectionModel(): TerminalSelectionModel {
   let state: TerminalSelectionState = { anchor: null, range: null };
+  let drag: { endpoint: "start" | "end"; cols: number } | null = null;
 
   function snapshot(): TerminalSelectionSnapshot {
     return { range: state.range };
@@ -259,18 +261,31 @@ export function createTerminalSelectionModel(): TerminalSelectionModel {
 
   function setSelection(input: TerminalSelectionUpdateInput): TerminalSelectionSnapshot {
     const coordinate = clampCoordinate(input.coordinate, input.bounds);
-    const anchor = state.anchor ?? coordinate;
+    const fixed = state.anchor ?? coordinate;
+    let anchor = fixed;
+    if (drag?.endpoint === "start" && compareCoordinates(coordinate, fixed) > 0) {
+      anchor =
+        fixed.col + 1 < drag.cols
+          ? { row: fixed.row, col: fixed.col + 1 }
+          : { row: fixed.row + 1, col: 0 };
+    } else if (drag?.endpoint === "end" && compareCoordinates(coordinate, fixed) < 0) {
+      anchor =
+        fixed.col > 0
+          ? { row: fixed.row, col: fixed.col - 1 }
+          : { row: fixed.row - 1, col: drag.cols - 1 };
+    }
     const range = normalizeTerminalSelection({
       anchor,
       focus: coordinate,
       coordinateEpoch: input.bounds.coordinateEpoch,
     });
-    state = { anchor, range };
+    state = { anchor: fixed, range };
     return snapshot();
   }
 
   return {
     begin(input: TerminalSelectionUpdateInput): TerminalSelectionSnapshot {
+      drag = null;
       const coordinate = clampCoordinate(input.coordinate, input.bounds);
       state = {
         anchor: coordinate,
@@ -285,7 +300,14 @@ export function createTerminalSelectionModel(): TerminalSelectionModel {
     update(input: TerminalSelectionUpdateInput): TerminalSelectionSnapshot {
       return setSelection(input);
     },
+    beginEndpointDrag(endpoint, cols) {
+      if (state.range) {
+        drag = { endpoint, cols };
+        state = { ...state, anchor: state.range[endpoint === "start" ? "end" : "start"] };
+      }
+    },
     clear(): TerminalSelectionSnapshot {
+      drag = null;
       state = { anchor: null, range: null };
       return snapshot();
     },
@@ -293,6 +315,7 @@ export function createTerminalSelectionModel(): TerminalSelectionModel {
       if (!state.range || rangeIsSafe(state.range, input.bounds)) {
         return snapshot();
       }
+      drag = null;
       state = { anchor: null, range: null };
       return snapshot();
     },
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 5dcefb8ebf..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
@@ -166,7 +166,6 @@ function createTerminalHost(input: CreateTerminalHostInput): MountedTerminal {
   runtime.mount({
     root,
     host,
-    initialSnapshot: null,
     scrollback: input.scrollback ?? 10_000,
     theme: {
       background: "#0b0b0b",
@@ -718,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" },
@@ -750,30 +751,11 @@ describe("terminal emulator runtime in a real browser", () => {
     const reset = vi.fn(originalReset);
     terminal.reset = reset;
 
-    mounted.runtime.renderSnapshot({
-      state: {
-        rows: terminal.rows,
-        cols: terminal.cols,
-        scrollback: [],
-        grid: [
-          [
-            { char: "p" },
-            { char: "r" },
-            { char: "o" },
-            { char: "m" },
-            { char: "p" },
-            { char: "t" },
-          ],
-        ],
-        cursor: {
-          row: 0,
-          col: 6,
-        },
-      },
-    });
-    await nextFrame();
-
+    mounted.runtime.replay({ type: "begin", rows: terminal.rows, cols: terminal.cols });
+    mounted.runtime.replay({ type: "data", data: terminalOutput("prompt") });
+    mounted.runtime.replay({ type: "end" });
     expect(reset).not.toHaveBeenCalled();
+    await nextFrame();
   });
 
   it("opens OSC 8 hyperlinks the same way as plain-text URLs", async () => {
@@ -795,3 +777,156 @@ describe("terminal emulator runtime in a real browser", () => {
     expect(confirm).not.toHaveBeenCalled();
   });
 });
+
+describe("incremental replay lifecycle", () => {
+  it.each(["clear", "remount"] as const)(
+    "recovers live input after interrupted replay and %s",
+    async (cleanup) => {
+      const mounted = createTerminalHost({ width: 720, height: 360 });
+      mounted.runtime.replay({ type: "begin", rows: 30, cols: 120 });
+      mounted.root.style.width = "360px";
+      mounted.runtime.resize({ shouldClaim: false });
+      mounted.runtime.replay({ type: "data", data: terminalOutput("interrupted") });
+      if (cleanup === "clear")
+        await new Promise<void>((resolve) => mounted.runtime.clear({ onCommitted: resolve }));
+      else {
+        mounted.runtime.unmount();
+        mounted.runtime.mount({
+          root: mounted.root,
+          host: mounted.host,
+          scrollback: 1000,
+          theme: {},
+        });
+      }
+      await new Promise<void>((resolve) =>
+        mounted.runtime.write({ data: terminalOutput("live"), onCommitted: resolve }),
+      );
+      getBrowserTerminal().input("user-input", true);
+      expect(mounted.inputs).toContain("user-input");
+      expect(getBrowserTerminal().cols).toBeLessThan(60);
+    },
+  );
+
+  it("suppresses generated replies until queued replay chunks commit after end", async () => {
+    const mounted = createTerminalHost({ width: 720, height: 360 });
+    mounted.runtime.replay({ type: "begin" });
+    mounted.runtime.replay({ type: "data", data: terminalOutput("\x1b]4;1;?\x07") });
+    mounted.runtime.replay({ type: "data", data: terminalOutput("\x1b]4;1;?\x07") });
+    mounted.runtime.replay({ type: "end" });
+    await new Promise<void>((resolve) =>
+      mounted.runtime.write({ data: terminalOutput("committed"), onCommitted: resolve }),
+    );
+    expect(mounted.inputs).toEqual([]);
+    await new Promise<void>((resolve) =>
+      mounted.runtime.write({ data: terminalOutput("\x1b]4;1;?\x07"), onCommitted: resolve }),
+    );
+    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 () => {
+  const mounted = createTerminalHost({ width: 720, height: 360 });
+  await settleMountRefits();
+  const local = latestSize(mounted.sizes);
+  mounted.runtime.replay({ type: "begin", rows: 30, cols: 120 });
+  mounted.runtime.replay({ type: "data", data: terminalOutput("x".repeat(100)) });
+  mounted.runtime.replay({ type: "end" });
+  await new Promise<void>((resolve) =>
+    mounted.runtime.write({ data: terminalOutput("LIVE"), onCommitted: resolve }),
+  );
+  expect(getBrowserTerminal().cols).toBe(latestSize(mounted.sizes).cols);
+  expect(getBrowserTerminal().cols).toBeLessThan(120);
+  expect(getBrowserTerminal().rows).toBe(local.rows);
+  mounted.runtime.resize({ forceClaim: true, shouldClaim: true });
+  expect(getBrowserTerminal().cols).toBe(latestSize(mounted.sizes).cols);
+});
+
+it("defers layout fit until all replay chunks commit", async () => {
+  const mounted = createTerminalHost({ width: 720, height: 360 });
+  await settleMountRefits();
+  mounted.runtime.replay({ type: "begin", rows: 30, cols: 120 });
+  await new Promise<void>((resolve) =>
+    mounted.runtime.write({
+      data: terminalOutput("first"),
+      suppressInput: true,
+      onCommitted: resolve,
+    }),
+  );
+  expect(getBrowserTerminal().cols).toBe(120);
+  mounted.root.style.width = "360px";
+  mounted.runtime.resize({ shouldClaim: true, forceClaim: true, forceRefresh: true });
+  await nextFrame();
+  expect(getBrowserTerminal().cols).toBe(120);
+  mounted.runtime.replay({ type: "data", data: terminalOutput("\x1b[2;110Hsecond") });
+  mounted.runtime.replay({ type: "end" });
+  await new Promise<void>((resolve) =>
+    mounted.runtime.write({ data: terminalOutput("LIVE"), onCommitted: resolve }),
+  );
+  expect(getBrowserTerminal().cols).toBe(latestSize(mounted.sizes).cols);
+  expect(getBrowserTerminal().cols).toBeLessThan(60);
+  expect(latestSize(mounted.sizes)).toMatchObject({ shouldClaim: true, forceClaim: true });
+  mounted.runtime.resize({ shouldClaim: true, forceClaim: true });
+  expect(getBrowserTerminal().cols).toBe(latestSize(mounted.sizes).cols);
+});
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 a11cedbfe2..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 {
@@ -302,25 +309,14 @@ describe("terminal-emulator-runtime", () => {
     expect(committed).toEqual(["first", "second", "clear", "third"]);
   });
 
-  it("falls back to timeout commit for a barrier op when the gate sentinel never fires", () => {
+  it("unblocks queued replay writes if a begin barrier never commits", () => {
     vi.useFakeTimers();
-    const { runtime, terminal } = createRuntimeWithTerminal();
-    const onCommitted = vi.fn();
-
-    // restoreOutput is a barrier; if xterm never commits the gate sentinel, the barrier still
-    // applies (and commits) after the 5s safety timeout instead of stalling forever.
-    runtime.restoreOutput({
-      data: terminalOutput("stuck"),
-      onCommitted,
-    });
-
-    expect(onCommitted).not.toHaveBeenCalled();
-    expect(terminal.resetCalls).toBe(0);
-    vi.advanceTimersByTime(5_000);
-    // The barrier now runs (write submitted) but its own commit still waits on xterm; advance
-    // again to fire the barrier's own write timeout.
-    vi.advanceTimersByTime(5_000);
-    expect(onCommitted).toHaveBeenCalledTimes(1);
+    const { runtime, writeTexts } = createRuntimeWithTerminal();
+    runtime.replay({ type: "begin" });
+    runtime.replay({ type: "data", data: terminalOutput("stuck") });
+    expect(writeTexts).toEqual(["\x1bc"]);
+    vi.advanceTimersByTime(5000);
+    expect(writeTexts).toEqual(["\x1bc", "stuck"]);
   });
 
   it("reports input mode changes from terminal output and resets them on snapshots", () => {
@@ -343,18 +339,7 @@ describe("terminal-emulator-runtime", () => {
     });
 
     runtime.write({ data: terminalOutput("\x1b[>7u") });
-    runtime.renderSnapshot({
-      state: {
-        rows: 2,
-        cols: 8,
-        scrollback: [],
-        grid: [[{ char: "$" }, { char: " " }]],
-        cursor: {
-          row: 0,
-          col: 2,
-        },
-      },
-    });
+    runtime.replay({ type: "begin", rows: 2, cols: 8 });
     // The plain write reports kitty flags synchronously during drain; the snapshot resets
     // them only after its barrier gate (the sentinel write callback) resolves.
     expect(inputModeChanges).toEqual([
@@ -410,40 +395,18 @@ describe("terminal-emulator-runtime", () => {
     expect(committed).toEqual(["second", "first"]);
   });
 
-  it("applies a snapshot after the writes ahead of it, never interleaving the reset", () => {
+  it("keeps replay reset and data after preceding writes, without interleaving", () => {
     const { runtime, terminal, writeTexts, writeCallbacks } = createRuntimeWithTerminal();
-    const committed: string[] = [];
-
-    runtime.write({
-      data: terminalOutput("before-a"),
-      onCommitted: () => {
-        committed.push("before-a");
-      },
-    });
-    runtime.write({
-      data: terminalOutput("before-b"),
-      onCommitted: () => {
-        committed.push("before-b");
-      },
-    });
-    runtime.restoreOutput({
-      data: terminalOutput("snap"),
-      onCommitted: () => {
-        committed.push("snap");
-      },
-    });
-
-    // Plain writes are submitted up front; the snapshot's reset+write has not run yet.
+    runtime.write({ data: terminalOutput("before-a") });
+    runtime.write({ data: terminalOutput("before-b") });
+    runtime.replay({ type: "begin" });
+    runtime.replay({ type: "data", data: terminalOutput("snap") });
+    runtime.replay({ type: "end" });
     expect(writeTexts).toEqual(["before-a", "before-b"]);
-
-    // writeCallbacks: [0]=before-a, [1]=before-b, [2]=barrier gate sentinel.
-    // The snapshot is gated behind the prior writes; resolving the gate runs it after them.
     writeCallbacks[2]?.();
-    expect(writeTexts).toEqual(["before-a", "before-b", "csnap"]);
-
-    // Snapshot commit fires only after its own write callback, strictly after the writes.
+    expect(writeTexts).toEqual(["before-a", "before-b", "\x1bc"]);
     writeCallbacks[3]?.();
-    expect(committed).toEqual(["snap"]);
+    expect(writeTexts).toEqual(["before-a", "before-b", "\x1bc", "snap"]);
     expect(terminal.resetCalls).toBe(0);
   });
 
@@ -456,7 +419,7 @@ describe("terminal-emulator-runtime", () => {
 
     // No plain writes precede this barrier (mount), so there is nothing to gate: it starts
     // at once with no sentinel, flipping suppressInput synchronously.
-    runtime.restoreOutput({ data: terminalOutput("snapshot") });
+    runtime.replay({ type: "begin" });
     expect(readSuppressInput()).toBe(true);
 
     // writeCallbacks[0] is the barrier's own snapshot write; committing it restores input.
@@ -471,7 +434,7 @@ describe("terminal-emulator-runtime", () => {
 
     // A plain write is now ungated, so the following barrier must wait on the sentinel.
     runtime.write({ data: terminalOutput("output") });
-    runtime.restoreOutput({ data: terminalOutput("snapshot") });
+    runtime.replay({ type: "begin" });
 
     // The plain write commits first. Only the following sentinel opens the barrier.
     expect(readSuppressInput()).toBe(false);
@@ -505,57 +468,40 @@ describe("terminal-emulator-runtime", () => {
     expect(onCommittedB).toHaveBeenCalledTimes(1);
   });
 
-  it("clears ungated writes on unmount so remount barriers apply immediately", () => {
+  it("clears ungated writes on unmount so remount replay begins immediately", () => {
     const { runtime } = createRuntimeWithTerminal();
-
     runtime.write({ data: terminalOutput("before unmount") });
     runtime.unmount();
-
     const remounted = attachStubTerminal(runtime);
-    runtime.restoreOutput({ data: terminalOutput("restored screen") });
-
-    expect(remounted.writeTexts).toEqual(["\u001bcrestored screen"]);
-    expect(remounted.writeCallbacks).toHaveLength(1);
+    runtime.replay({ type: "begin" });
+    runtime.replay({ type: "data", data: terminalOutput("restored screen") });
+    expect(remounted.writeTexts).toEqual(["\x1bc"]);
+    remounted.writeCallbacks[0]?.();
+    expect(remounted.writeTexts).toEqual(["\x1bc", "restored screen"]);
   });
 
-  it("replays snapshots through a single write without first painting a reset terminal", () => {
+  it("parses replay chunks serially without synchronously resetting the terminal", () => {
     const { runtime, terminal, writeTexts, writeCallbacks } = createRuntimeWithTerminal();
-
-    runtime.renderSnapshot({
-      state: {
-        rows: 2,
-        cols: 8,
-        scrollback: [],
-        grid: [
-          [{ char: "h" }, { char: "i" }],
-          [{ char: "$" }, { char: " " }],
-        ],
-        cursor: {
-          row: 1,
-          col: 2,
-        },
-      },
-    });
-
-    // The snapshot is a barrier; its write applies after the gate sentinel (writeCallbacks[0]).
-    writeCallbacks[0]?.();
-
+    runtime.replay({ type: "begin", rows: 2, cols: 8 });
+    runtime.replay({ type: "data", data: terminalOutput("hi") });
+    runtime.replay({ type: "data", data: terminalOutput("\r\n$") });
+    runtime.replay({ type: "end" });
     expect(terminal.resetCalls).toBe(0);
-    expect(writeTexts).toHaveLength(1);
-    expect(writeTexts[0]?.startsWith("\u001bc")).toBe(true);
-    expect(writeTexts[0]).toContain("hi");
+    expect(writeTexts).toEqual(["\x1bc"]);
+    writeCallbacks[0]?.();
+    expect(writeTexts).toEqual(["\x1bc", "hi"]);
+    writeCallbacks[1]?.();
+    expect(writeTexts).toEqual(["\x1bc", "hi", "\r\n$"]);
   });
 
-  it("restores server-rendered ANSI snapshots through the snapshot write path", () => {
+  it("restores worker-rendered ANSI through the replay lifecycle", () => {
     const { runtime, terminal, writeTexts, writeCallbacks } = createRuntimeWithTerminal();
-
-    runtime.restoreOutput({ data: terminalOutput("restored screen") });
-
-    // restoreOutput is a barrier (suppressInput); it applies after the gate sentinel.
+    runtime.replay({ type: "begin" });
+    runtime.replay({ type: "data", data: terminalOutput("restored screen") });
+    runtime.replay({ type: "end" });
     writeCallbacks[0]?.();
-
     expect(terminal.resetCalls).toBe(0);
-    expect(writeTexts).toEqual(["\u001bcrestored screen"]);
+    expect(writeTexts).toEqual(["\x1bc", "restored screen"]);
   });
 
   it("forces a refit when resize is requested", () => {
@@ -699,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 0a55cd7126..ae74a4945f 100644
--- a/packages/app/src/terminal/runtime/terminal-emulator-runtime.ts
+++ b/packages/app/src/terminal/runtime/terminal-emulator-runtime.ts
@@ -3,11 +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 { TerminalState } from "@getpaseo/protocol/messages";
+import type { TerminalCharacterWidths } from "../character-widths";
 import {
   type TerminalInputModeState,
   TerminalInputModeTracker,
@@ -24,7 +25,6 @@ import {
   resolveMacTerminalEditingShortcut,
   shouldInterceptDomTerminalKey,
 } from "@/utils/terminal-keys";
-import { renderTerminalSnapshotToAnsi } from "./terminal-snapshot";
 import {
   createTerminalLocalFileLinkProvider,
   type TerminalLocalFileLinkSource,
@@ -55,7 +55,6 @@ const FIND_HIGHLIGHT_LIMIT = 20_000;
 export interface TerminalEmulatorRuntimeMountInput {
   root: HTMLDivElement;
   host: HTMLDivElement;
-  initialSnapshot: TerminalState | null;
   scrollback: number;
   theme: ITheme;
   fontFamily?: string;
@@ -124,7 +123,6 @@ interface TerminalEmulatorRuntimeDisposables {
   removeVisualViewportResize: () => void;
   clearFitTimeouts: () => void;
   removeFontListeners: () => void;
-  removeTouchListeners: () => void;
   removeFilePasteListener: () => void;
   restoreDocumentStyles: () => void;
   restoreViewportStyles: () => void;
@@ -134,7 +132,7 @@ interface TerminalEmulatorRuntimeDisposables {
 }
 
 interface TerminalOutputOperation {
-  type: "write" | "clear" | "snapshot";
+  type: "write" | "clear" | "snapshot" | "fit";
   data: TerminalOutputData;
   rows?: number;
   cols?: number;
@@ -156,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);
@@ -185,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> {
@@ -224,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() },
@@ -236,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;
@@ -280,6 +295,7 @@ export class TerminalEmulatorRuntime {
     },
   };
 
+  private replayResize: TerminalResizeRequest | null = null;
   private fitAndEmitResize: ((input?: TerminalResizeRequest) => void) | null = null;
   private lastSize: { rows: number; cols: number } | null = null;
   private cleanup: (() => void) | null = null;
@@ -322,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);
@@ -370,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)) {
@@ -434,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();
@@ -531,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, {
@@ -570,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 {
@@ -608,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);
@@ -616,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() === "?");
       }
@@ -652,6 +691,7 @@ export class TerminalEmulatorRuntime {
     window.__paseoTerminal = terminal;
 
     const fitAndEmitResize = (resizeInput?: TerminalResizeRequest): void => {
+      if (this.deferReplayResize(resizeInput)) return;
       const forceRefresh = resizeInput?.forceRefresh ?? false;
       const shouldClaim = resizeInput?.shouldClaim ?? true;
       const forceClaim = resizeInput?.forceClaim ?? false;
@@ -722,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 });
     });
@@ -777,10 +812,6 @@ export class TerminalEmulatorRuntime {
       fitAndEmitResize({ forceRefresh: true, shouldClaim: false });
     }, 0);
 
-    if (input.initialSnapshot) {
-      this.renderSnapshot({ state: input.initialSnapshot });
-    }
-
     this.processOutputQueue();
 
     const disposables: TerminalEmulatorRuntimeDisposables = {
@@ -810,7 +841,6 @@ export class TerminalEmulatorRuntime {
       removeFontListeners: () => {
         fontSet?.removeEventListener?.("loadingdone", fontReadyHandler);
       },
-      removeTouchListeners,
       removeFilePasteListener: () => {
         input.host.removeEventListener("paste", filePasteHandler, true);
       },
@@ -842,7 +872,6 @@ export class TerminalEmulatorRuntime {
       disposables.removeVisualViewportResize();
       disposables.clearFitTimeouts();
       disposables.removeFontListeners();
-      disposables.removeTouchListeners();
       disposables.removeFilePasteListener();
       disposables.disposeFitAddon();
       disposables.disposeWebglAddon();
@@ -898,20 +927,19 @@ export class TerminalEmulatorRuntime {
     onFilePaste?.(file);
   }
 
-  renderSnapshot(input: { state: TerminalState | null; onCommitted?: () => void }): void {
-    if (!input.state) {
-      this.clear(input);
-      return;
+  replay(event: import("@getpaseo/client").TerminalReplayEvent): void {
+    if (event.type === "begin") {
+      this.replayResize ??= { shouldClaim: false };
+      this.restoreOutput({ data: EMPTY_TERMINAL_OUTPUT, rows: event.rows, cols: event.cols });
+    } else if (event.type === "data") {
+      this.write({ data: event.data, suppressInput: true });
+    } else {
+      this.outputOperations.push({ type: "fit", data: EMPTY_TERMINAL_OUTPUT });
+      this.processOutputQueue();
     }
-    this.restoreOutput({
-      data: encodeTerminalOutput(renderTerminalSnapshotToAnsi(input.state)),
-      rows: input.state.rows,
-      cols: input.state.cols,
-      ...(input.onCommitted ? { onCommitted: input.onCommitted } : {}),
-    });
   }
 
-  restoreOutput(input: {
+  private restoreOutput(input: {
     data: TerminalOutputData;
     rows?: number;
     cols?: number;
@@ -928,6 +956,16 @@ export class TerminalEmulatorRuntime {
     this.processOutputQueue();
   }
 
+  private deferReplayResize(input?: TerminalResizeRequest): boolean {
+    if (!this.replayResize) return false;
+    this.replayResize = {
+      forceRefresh: this.replayResize.forceRefresh || input?.forceRefresh,
+      shouldClaim: this.replayResize.shouldClaim || (input?.shouldClaim ?? true),
+      forceClaim: this.replayResize.forceClaim || input?.forceClaim,
+    };
+    return true;
+  }
+
   resize(input?: TerminalResizeRequest): void {
     this.fitAndEmitResize?.(input);
   }
@@ -1047,6 +1085,7 @@ export class TerminalEmulatorRuntime {
       commit();
     }
     this.hasUngatedWrites = false;
+    this.replayResize = null;
 
     this.cleanup?.();
     this.cleanup = null;
@@ -1176,16 +1215,40 @@ export class TerminalEmulatorRuntime {
       this.processOutputQueue();
     };
 
+    if (operation.type === "fit") {
+      // xterm resize flushes its write buffer synchronously. Leave the parser's
+      // commit callback before fitting, or that flush consumes the next write.
+      queueMicrotask(() => {
+        if (this.inFlightOutputOperation !== operation || this.terminal !== terminal) return;
+        const resize = this.replayResize ?? { shouldClaim: false };
+        this.replayResize = null;
+        this.fitAndEmitResize?.(resize);
+        finalizeOperation(operation);
+      });
+      return;
+    }
+
     if (operation.type === "clear") {
       this.inputModeDecoder.decode();
       this.inputModeTracker.reset();
       this.emitInputModeChange();
       terminal.reset();
-      finalizeOperation(operation);
+      if (!this.replayResize) {
+        finalizeOperation(operation);
+        return;
+      }
+      queueMicrotask(() => {
+        if (this.inFlightOutputOperation !== operation || this.terminal !== terminal) return;
+        const resize = this.replayResize ?? { shouldClaim: false };
+        this.replayResize = null;
+        this.fitAndEmitResize?.(resize);
+        finalizeOperation(operation);
+      });
       return;
     }
 
     if (operation.type === "snapshot") {
+      this.replayResize ??= { shouldClaim: false };
       this.inputModeDecoder.decode();
       this.inputModeTracker.reset();
       this.emitInputModeChange();
@@ -1348,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-find.browser.test.ts b/packages/app/src/terminal/runtime/terminal-find.browser.test.ts
index 8336925338..84b941a340 100644
--- a/packages/app/src/terminal/runtime/terminal-find.browser.test.ts
+++ b/packages/app/src/terminal/runtime/terminal-find.browser.test.ts
@@ -31,7 +31,6 @@ function mount(options?: { isMac: boolean }) {
   runtime.mount({
     root,
     host,
-    initialSnapshot: null,
     scrollback: 1000,
     theme: { background: "#ffffff", foreground: "#111111" },
   });
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
new file mode 100644
index 0000000000..5b1e875b44
--- /dev/null
+++ b/packages/app/src/terminal/runtime/terminal-glyph-rendering.browser.test.ts
@@ -0,0 +1,204 @@
+import "@xterm/xterm/css/xterm.css";
+import { page } from "vitest/browser";
+import { afterEach, expect, it } from "vitest";
+import type { Terminal } from "@xterm/xterm";
+import { encodeTerminalOutput, TerminalEmulatorRuntime } from "./terminal-emulator-runtime";
+
+interface TerminalView {
+  root: HTMLDivElement;
+  host: HTMLDivElement;
+  runtime: TerminalEmulatorRuntime;
+  terminal: Terminal;
+}
+
+interface RowImage {
+  width: number;
+  height: number;
+  pixels: Uint8ClampedArray;
+}
+
+const views: TerminalView[] = [];
+const header = "HEADER_0123456789 한글 日本語";
+
+function mountTerminal(left: number): TerminalView {
+  const root = document.createElement("div");
+  Object.assign(root.style, {
+    position: "fixed",
+    left: `${left}px`,
+    top: "0",
+    width: "440px",
+    height: "360px",
+    overflow: "hidden",
+  });
+  const host = document.createElement("div");
+  Object.assign(host.style, { width: "100%", height: "100%" });
+  root.appendChild(host);
+  document.body.appendChild(root);
+  const runtime = new TerminalEmulatorRuntime();
+  runtime.mount({
+    root,
+    host,
+    scrollback: 1000,
+    fontFamily: "monospace",
+    fontSize: 16,
+    theme: { background: "#101010", foreground: "#eeeeee", cursor: "#eeeeee" },
+  });
+  const terminal = window.__paseoTerminal;
+  if (!terminal) throw new Error("Terminal did not mount");
+  const view = { root, host, runtime, terminal };
+  views.push(view);
+  return view;
+}
+
+function write(view: TerminalView, text: string): Promise<void> {
+  return new Promise((resolve) => {
+    view.runtime.write({ data: encodeTerminalOutput(text), onCommitted: resolve });
+  });
+}
+
+function webglCanvas(view: TerminalView): HTMLCanvasElement {
+  for (const canvas of view.host.querySelectorAll(".xterm-screen canvas")) {
+    if (canvas instanceof HTMLCanvasElement && canvas.getContext("webgl2")) return canvas;
+  }
+  throw new Error("Real WebGL is required; DOM fallback cannot test glyph corruption");
+}
+
+async function mountPair() {
+  await page.viewport(1000, 600);
+  const active = mountTerminal(0);
+  const sibling = mountTerminal(460);
+  await document.fonts.ready;
+  await expect
+    .poll(() => active.host.querySelectorAll(".xterm-screen canvas").length)
+    .toBeGreaterThan(0);
+  await expect
+    .poll(() => sibling.host.querySelectorAll(".xterm-screen canvas").length)
+    .toBeGreaterThan(0);
+  webglCanvas(active);
+  webglCanvas(sibling);
+  await write(active, "\x1b[?25l");
+  await write(sibling, "\x1b[?25l");
+  return { active, sibling };
+}
+
+function captureHeader(input: { view: TerminalView; output?: string }): Promise<RowImage> {
+  const { view, output } = input;
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      rendered.dispose();
+      reject(new Error("Terminal did not render within 2 seconds"));
+    }, 2000);
+    const rendered = view.terminal.onRender(() => {
+      rendered.dispose();
+      clearTimeout(timeout);
+      try {
+        // Copy during onRender, before WebGL discards its default drawing buffer.
+        const source = webglCanvas(view);
+        const canvas = document.createElement("canvas");
+        canvas.width = source.width;
+        canvas.height = Math.round(source.height / view.terminal.rows);
+        const context = canvas.getContext("2d");
+        if (!context) throw new Error("Canvas 2D pixel capture is unavailable");
+        context.drawImage(source, 0, 0);
+        const pixels = context.getImageData(0, 0, canvas.width, canvas.height).data;
+        resolve({ width: canvas.width, height: canvas.height, pixels });
+      } catch (error) {
+        reject(error);
+      }
+    });
+    if (output === undefined) view.terminal.refresh(0, view.terminal.rows - 1);
+    else view.runtime.write({ data: encodeTerminalOutput(output) });
+  });
+}
+
+function expectSamePixels(input: { expected: RowImage; actual: RowImage; label: string }): void {
+  const { expected, actual, label } = input;
+  expect(actual.width, label).toBe(expected.width);
+  expect(actual.height, label).toBe(expected.height);
+  let changed = 0;
+  for (let index = 0; index < expected.pixels.length; index += 1) {
+    if (expected.pixels[index] !== actual.pixels[index]) changed += 1;
+  }
+  expect(changed, label).toBe(0);
+}
+
+function coloredOutput(input: { cells: number; offset: number }): string {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let output = "";
+  for (let index = 0; index < input.cells; index += 1) {
+    const value = index + input.offset;
+    const foreground = `${value % 256};${(value >> 8) % 256};${(value * 13) % 256}`;
+    const background = (value * 7) % 256;
+    output += `\x1b[38;2;${foreground}m\x1b[48;5;${background}m${alphabet[value % alphabet.length]}`;
+  }
+  return `${output}\x1b[0m`;
+}
+
+afterEach(() => {
+  for (const view of views.splice(0)) {
+    view.runtime.unmount();
+    view.root.remove();
+  }
+});
+
+it("preserves another terminal's glyph pixels when a shared atlas is cleared", async () => {
+  const { active, sibling } = await mountPair();
+  await write(sibling, header);
+  const before = await captureHeader({ view: sibling });
+  const visibleChannels = before.pixels.filter(
+    (channel, index) => index % 4 !== 3 && channel > 100,
+  );
+  expect(visibleChannels.length).toBeGreaterThan(100);
+
+  active.terminal.clearTextureAtlas();
+  await captureHeader({ view: active, output: coloredOutput({ cells: 2000, offset: 0 }) });
+  const after = await captureHeader({
+    view: sibling,
+    output: `\x1b[${sibling.terminal.rows};1Hx`,
+  });
+  expect(sibling.terminal.buffer.active.getLine(0)?.translateToString(true)).toBe(header);
+  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);
+  // Startup glyphs can stay on an unmerged page and hide this bug. Allocate the
+  // reference after some output, as a real long-running TUI does.
+  for (let batch = 0; batch < 16; batch += 1) {
+    await captureHeader({
+      view: active,
+      output: `\x1b[H${coloredOutput({ cells, offset: batch * cells })}`,
+    });
+  }
+  const lateHeader = `\x1b[H\x1b[0m\x1b[2K\x1b[38;2;253;251;247m${header}\x1b[0m`;
+  await write(active, lateHeader);
+  await write(sibling, lateHeader);
+  const activeBefore = await captureHeader({ view: active });
+  const siblingBefore = await captureHeader({ view: sibling });
+
+  for (let batch = 0; batch < 256; batch += 1) {
+    const activeFrame = await captureHeader({
+      view: active,
+      output: `\x1b[2;1H${coloredOutput({ cells, offset: (batch + 16) * cells })}`,
+    });
+    const siblingFrame = await captureHeader({
+      view: sibling,
+      output: `\x1b[${sibling.terminal.rows};1H${batch % 10}`,
+    });
+    expect(active.terminal.buffer.active.getLine(0)?.translateToString(true)).toBe(header);
+    expect(sibling.terminal.buffer.active.getLine(0)?.translateToString(true)).toBe(header);
+    expectSamePixels({
+      expected: activeBefore,
+      actual: activeFrame,
+      label: `active frame ${batch}`,
+    });
+    expectSamePixels({
+      expected: siblingBefore,
+      actual: siblingFrame,
+      label: `sibling frame ${batch}`,
+    });
+  }
+}, 60_000);
diff --git a/packages/app/src/terminal/runtime/terminal-resize-repro.browser.test.ts b/packages/app/src/terminal/runtime/terminal-resize-repro.browser.test.ts
index 35b3492b71..d72a935f49 100644
--- a/packages/app/src/terminal/runtime/terminal-resize-repro.browser.test.ts
+++ b/packages/app/src/terminal/runtime/terminal-resize-repro.browser.test.ts
@@ -1,15 +1,14 @@
+import { Terminal as ReplaySource } from "@xterm/xterm";
+import { SerializeAddon } from "@xterm/addon-serialize";
 import { page } from "@vitest/browser/context";
 import { afterEach, describe, expect, it } from "vitest";
-import type { TerminalState } from "@getpaseo/protocol/messages";
 import { encodeTerminalOutput, TerminalEmulatorRuntime } from "./terminal-emulator-runtime";
 
 // Regression: "streaming pino log, resized the Paseo terminal, old logs stayed
 // narrow and new logs drew on top of the old ones."
 //
-// A heavy stream overflows MAX_TERMINAL_OUTPUT_FRAME_BYTES, so the server sends a
-// SNAPSHOT mid-stream. The client restores it via renderTerminalSnapshotToAnsi.
-// When the snapshot carries per-row soft-wrap flags, restored long lines must
-// reflow on resize just like live output — not freeze at the snapshot width.
+// Backpressure triggers an ANSI replay serialized directly from xterm. Replayed
+// soft-wrapped lines must reflow on resize like live output.
 
 interface Mounted {
   host: HTMLDivElement;
@@ -57,7 +56,6 @@ function mount(width: number, height: number): Mounted {
   runtime.mount({
     root,
     host,
-    initialSnapshot: null,
     scrollback: 10_000,
     theme: { background: "#0b0b0b", foreground: "#e6e6e6", cursor: "#e6e6e6" },
   });
@@ -90,9 +88,18 @@ function someRowContains(term: InspectableTerminal, text: string): boolean {
   return dumpRows(term).some((r) => r.text.includes(text));
 }
 
-function renderSnapshotCommitted(runtime: TerminalEmulatorRuntime, state: TerminalState) {
+function replayCommitted(
+  runtime: TerminalEmulatorRuntime,
+  state: { rows: number; cols: number; data: Uint8Array },
+) {
   return new Promise<void>((resolve) => {
-    runtime.renderSnapshot({ state, onCommitted: resolve });
+    runtime.replay({ type: "begin", rows: state.rows, cols: state.cols });
+    runtime.replay({
+      type: "data",
+      data: state.data,
+    });
+    runtime.replay({ type: "end" });
+    runtime.write({ data: new Uint8Array([0]), onCommitted: resolve });
   });
 }
 
@@ -102,31 +109,18 @@ function writeCommitted(runtime: TerminalEmulatorRuntime, data: Uint8Array) {
   });
 }
 
-// Build a server-style snapshot of one long pino line that the SERVER soft-wrapped
-// at `cols`, represented as multiple grid rows (exactly what the daemon stores in
-// its headless xterm and ships in a snapshot).
-function buildWrappedSnapshot(cols: number): TerminalState {
-  const longLine = `[server] [15:30:00.123] TRACE: provider.claude.raw_event {"module":"agent","seq":1,"sessionId":"ed8972f4-d3be-45d0-992c-631f8f1ed04e","turnId":"foreground-turn-1","payload":"${"A".repeat(40)}"}`;
-  const grid: TerminalState["grid"] = [];
-  for (let i = 0; i < longLine.length; i += cols) {
-    const chunk = longLine.slice(i, i + cols);
-    grid.push([...chunk].map((char) => ({ char })));
+// Serialize one long pino line from a real server-width xterm buffer.
+// The replay must retain its soft-wrap boundaries for later client reflow.
+async function buildWrappedSnapshot(cols: number) {
+  const source = new ReplaySource({ rows: 24, cols, allowProposedApi: true });
+  const serializer = new SerializeAddon();
+  source.loadAddon(serializer);
+  try {
+    await new Promise<void>((resolve) => source.write(pinoLine(0), resolve));
+    return { rows: 24, cols, data: new TextEncoder().encode(serializer.serialize()) };
+  } finally {
+    source.dispose();
   }
-  // The fixed daemon ships per-row soft-wrap flags: every row of the logical line
-  // continues onto the next except the last.
-  const gridWrapped = grid.map((_, index) => index < grid.length - 1);
-  // Cursor sits just below the restored content, exactly where the daemon's
-  // headless terminal leaves it after a line break, so streamed output appends
-  // cleanly below instead of overwriting the restored rows.
-  return {
-    rows: 24,
-    cols,
-    scrollback: [],
-    scrollbackWrapped: [],
-    grid,
-    gridWrapped,
-    cursor: { row: grid.length, col: 0 },
-  };
 }
 
 function pinoLine(seq: number): string {
@@ -141,15 +135,14 @@ afterEach(() => {
 });
 
 describe("terminal resize reflow repro (Paseo terminal)", () => {
-  it("snapshot-restored rows stay frozen at the snapshot width after the terminal grows", async () => {
+  it("replayed soft-wrapped rows reflow after the terminal grows", async () => {
     await page.viewport(1600, 700);
     const m = mount(560, 360); // ~70 cols
     await waitFor(() => m.terminal.cols > 40);
     const narrowCols = m.terminal.cols;
 
-    // 1) Mid-stream snapshot arrives (server overflowed 256KB). It carries the
-    //    long line wrapped at the server width as separate grid rows.
-    await renderSnapshotCommitted(m.runtime, buildWrappedSnapshot(narrowCols));
+    // 1) A mid-stream ANSI replay arrives, preserving wraps at the captured width.
+    await replayCommitted(m.runtime, await buildWrappedSnapshot(narrowCols));
     await waitFor(() => someRowContains(m.terminal, "[15:30:00.123]"));
 
     // 2) Normal post-snapshot streaming resumes (autowrap on -> soft-wrapped).
diff --git a/packages/app/src/terminal/runtime/terminal-restore-options.test.ts b/packages/app/src/terminal/runtime/terminal-restore-options.test.ts
index 14f2ce4d8f..7e5294b347 100644
--- a/packages/app/src/terminal/runtime/terminal-restore-options.test.ts
+++ b/packages/app/src/terminal/runtime/terminal-restore-options.test.ts
@@ -4,25 +4,27 @@ import { resolveTerminalRestoreOptions } from "./terminal-restore-options";
 
 describe("terminal restore options", () => {
   it("omits restore options for daemons without terminal restore modes", () => {
-    expect(
+    expect(() =>
       resolveTerminalRestoreOptions({
+        scrollbackLines: 10000,
         supportsTerminalRestoreModes: false,
         canClaimSize: true,
         size: { rows: 24, cols: 80 },
       }),
-    ).toBeUndefined();
+    ).toThrow("Update the host to view terminals.");
   });
 
-  it("requests visible snapshot restore with bounded scrollback for capable daemons", () => {
+  it("requests visible snapshot restore with configured scrollback for capable daemons", () => {
     expect(
       resolveTerminalRestoreOptions({
+        scrollbackLines: 10000,
         supportsTerminalRestoreModes: true,
         canClaimSize: true,
         size: { rows: 24, cols: 80 },
       }),
     ).toEqual({
       mode: "visible-snapshot",
-      scrollbackLines: 200,
+      scrollbackLines: 10000,
       size: { rows: 24, cols: 80 },
     });
   });
@@ -30,26 +32,39 @@ describe("terminal restore options", () => {
   it("omits size until the terminal has been measured", () => {
     expect(
       resolveTerminalRestoreOptions({
+        scrollbackLines: 10000,
         supportsTerminalRestoreModes: true,
         canClaimSize: true,
         size: null,
       }),
     ).toEqual({
       mode: "visible-snapshot",
-      scrollbackLines: 200,
+      scrollbackLines: 10000,
     });
   });
 
   it("does not let a background attach resize the PTY", () => {
     expect(
       resolveTerminalRestoreOptions({
+        scrollbackLines: 10000,
         supportsTerminalRestoreModes: true,
         canClaimSize: false,
         size: { rows: 24, cols: 80 },
       }),
     ).toEqual({
       mode: "visible-snapshot",
-      scrollbackLines: 200,
+      scrollbackLines: 10000,
     });
   });
 });
+
+it.each([0, 5, 400, 10000])("requests exactly %s configured history rows", (scrollbackLines) => {
+  expect(
+    resolveTerminalRestoreOptions({
+      supportsTerminalRestoreModes: true,
+      scrollbackLines,
+      canClaimSize: false,
+      size: null,
+    }),
+  ).toEqual({ mode: "visible-snapshot", scrollbackLines });
+});
diff --git a/packages/app/src/terminal/runtime/terminal-restore-options.ts b/packages/app/src/terminal/runtime/terminal-restore-options.ts
index d1e304cec7..3fcd894eac 100644
--- a/packages/app/src/terminal/runtime/terminal-restore-options.ts
+++ b/packages/app/src/terminal/runtime/terminal-restore-options.ts
@@ -1,23 +1,23 @@
+import { i18n } from "@/i18n/i18next";
 import type { SubscribeTerminalRequest } from "@getpaseo/protocol/messages";
 
-export const TERMINAL_VISIBLE_RESTORE_SCROLLBACK_LINES = 200;
-
 export interface ResolveTerminalRestoreOptionsInput {
   supportsTerminalRestoreModes: boolean;
+  scrollbackLines: number;
   canClaimSize: boolean;
   size: { rows: number; cols: number } | null;
 }
 
 export function resolveTerminalRestoreOptions(
   input: ResolveTerminalRestoreOptionsInput,
-): SubscribeTerminalRequest["restore"] | undefined {
+): NonNullable<SubscribeTerminalRequest["restore"]> {
   if (!input.supportsTerminalRestoreModes) {
-    return undefined;
+    throw new Error(i18n.t("workspace.terminal.restoreRequiresUpdate"));
   }
 
   return {
     mode: "visible-snapshot",
-    scrollbackLines: TERMINAL_VISIBLE_RESTORE_SCROLLBACK_LINES,
+    scrollbackLines: input.scrollbackLines,
     ...(input.canClaimSize && input.size ? { size: input.size } : {}),
   };
 }
diff --git a/packages/app/src/terminal/runtime/terminal-snapshot.test.ts b/packages/app/src/terminal/runtime/terminal-snapshot.test.ts
index c5fdbbd9fd..6232d9a8c0 100644
--- a/packages/app/src/terminal/runtime/terminal-snapshot.test.ts
+++ b/packages/app/src/terminal/runtime/terminal-snapshot.test.ts
@@ -2,7 +2,7 @@ import { Terminal as HeadlessTerminal } from "@xterm/headless";
 import { Terminal as ClientTerminal } from "@xterm/xterm";
 import { describe, expect, it } from "vitest";
 
-import { renderTerminalSnapshotToAnsi } from "./terminal-snapshot";
+import { SerializeAddon } from "@xterm/addon-serialize";
 
 interface SnapshotCell {
   char: string;
@@ -122,7 +122,7 @@ function extractRow(terminal: ClientTerminal | HeadlessTerminal, row: number): S
 }
 
 describe("terminal-snapshot", () => {
-  it("replays extracted terminal state into a client xterm with matching grid, scrollback, and cursor presentation", async () => {
+  it("replays upstream serialized ANSI into a client xterm with matching grid, scrollback, and cursor presentation", async () => {
     const source = new HeadlessTerminal({
       rows: 4,
       cols: 12,
@@ -138,6 +138,8 @@ describe("terminal-snapshot", () => {
     await writeToTerminal(source, "\u001b[2 q");
     await writeToTerminal(source, "\u001b[?25l");
 
+    const serializer = new SerializeAddon();
+    source.loadAddon(serializer);
     const snapshot = extractState(source);
 
     const client = new ClientTerminal({
@@ -147,7 +149,7 @@ describe("terminal-snapshot", () => {
       scrollback: 100,
     });
 
-    await writeToTerminal(client, renderTerminalSnapshotToAnsi(snapshot));
+    await writeToTerminal(client, serializer.serialize() + "\x1b[2 q\x1b[?25l");
 
     expect(extractState(client)).toEqual(snapshot);
   });
diff --git a/packages/app/src/terminal/runtime/terminal-snapshot.ts b/packages/app/src/terminal/runtime/terminal-snapshot.ts
deleted file mode 100644
index 4b7a8e0b9b..0000000000
--- a/packages/app/src/terminal/runtime/terminal-snapshot.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { renderTerminalSnapshotToAnsi } from "@getpaseo/protocol/terminal-snapshot";
diff --git a/packages/app/src/terminal/runtime/terminal-stream-controller.test.ts b/packages/app/src/terminal/runtime/terminal-stream-controller.test.ts
index 388484d79d..ecd49c6fd5 100644
--- a/packages/app/src/terminal/runtime/terminal-stream-controller.test.ts
+++ b/packages/app/src/terminal/runtime/terminal-stream-controller.test.ts
@@ -1,3 +1,4 @@
+import { resolveTerminalRestoreOptions } from "./terminal-restore-options";
 import type { SessionOutboundMessage } from "@getpaseo/protocol/messages";
 import { describe, expect, it } from "vitest";
 
@@ -7,34 +8,16 @@ import {
   type TerminalStreamControllerStatus,
 } from "./terminal-stream-controller";
 
-interface TerminalSnapshot {
-  rows: number;
-  cols: number;
-  grid: Array<Array<{ char: string }>>;
-  scrollback: Array<Array<{ char: string }>>;
-  cursor: { row: number; col: number };
-}
-
-function terminalCellText(cell: { char: string }): string {
-  return cell.char;
-}
-
-function terminalRowText(row: Array<{ char: string }>): string {
-  return row.map(terminalCellText).join("");
-}
-
-function terminalSnapshotText(state: TerminalSnapshot): string {
-  return state.grid.map(terminalRowText).join("\n");
-}
-
 function terminalOutput(text: string): Uint8Array {
   return new TextEncoder().encode(text);
 }
 
-type TerminalStreamEvent =
-  | { terminalId: string; type: "output"; data: Uint8Array }
-  | { terminalId: string; type: "snapshot"; state: TerminalSnapshot }
-  | { terminalId: string; type: "restore"; data: Uint8Array };
+type StreamEvent = import("@getpaseo/client").TerminalStreamEvent;
+type TerminalStreamEvent = StreamEvent extends infer Event
+  ? Event extends StreamEvent
+    ? Omit<Event, "subscriptionId">
+    : never
+  : never;
 
 class FakeTerminalStreamClient implements TerminalStreamControllerClient {
   private readonly updates = new Set<(message: SessionOutboundMessage) => void>();
@@ -115,32 +98,23 @@ class FakeTerminalStreamClient implements TerminalStreamControllerClient {
 function createHarness(input?: { client?: FakeTerminalStreamClient }) {
   const client = input?.client ?? new FakeTerminalStreamClient();
   const outputs: Array<{ terminalId: string; data: Uint8Array }> = [];
-  const restores: Array<{ terminalId: string; data: Uint8Array }> = [];
-  const snapshots: Array<{ terminalId: string; text: string }> = [];
+  const replays: import("@getpaseo/client").TerminalReplayEvent[] = [];
   const statuses: TerminalStreamControllerStatus[] = [];
   const exits: string[] = [];
   const controller = new TerminalStreamController({
     client,
+    onReplay: ({ replay }) => replays.push(replay),
     onExit: (terminalId) => exits.push(terminalId),
     getPreferredSize: () => ({ rows: 24, cols: 80 }),
     onOutput: (output) => {
       outputs.push(output);
     },
-    onRestore: (restore) => {
-      restores.push(restore);
-    },
-    onSnapshot: ({ terminalId, state }) => {
-      snapshots.push({
-        terminalId,
-        text: terminalSnapshotText(state),
-      });
-    },
     onStatusChange: (status) => {
       statuses.push(status);
     },
   });
 
-  return { client, controller, outputs, restores, snapshots, statuses, exits };
+  return { client, controller, outputs, replays, statuses, exits };
 }
 
 async function flushAsyncWork(): Promise<void> {
@@ -149,24 +123,20 @@ async function flushAsyncWork(): Promise<void> {
 }
 
 describe("terminal-stream-controller", () => {
-  it("subscribes, resizes, and forwards snapshot/output events", async () => {
+  it("subscribes, resizes, and forwards replay/output events", async () => {
     const harness = createHarness();
     harness.client.nextSubscribeResults.push({ terminalId: "term-1", error: null });
 
     harness.controller.setTerminal({ terminalId: "term-1" });
     await flushAsyncWork();
 
-    harness.client.emit({
-      terminalId: "term-1",
-      type: "snapshot",
-      state: {
-        rows: 1,
-        cols: 5,
-        grid: [[{ char: "h" }, { char: "e" }, { char: "l" }, { char: "l" }, { char: "o" }]],
-        scrollback: [],
-        cursor: { row: 0, col: 5 },
-      },
-    });
+    const replay: import("@getpaseo/client").TerminalReplayEvent[] = [
+      { type: "begin", rows: 24, cols: 80, retainedHistoryLines: 400 },
+      { type: "data", data: terminalOutput("hello") },
+      { type: "end" },
+    ];
+    for (const event of replay)
+      harness.client.emit({ terminalId: "term-1", type: "replay", replay: event });
     const outputData = terminalOutput(" world");
     harness.client.emit({
       terminalId: "term-1",
@@ -178,7 +148,7 @@ describe("terminal-stream-controller", () => {
     expect(harness.client.resizeCalls).toEqual([
       { terminalId: "term-1", rows: 24, cols: 80, intent: "claim" },
     ]);
-    expect(harness.snapshots).toEqual([{ terminalId: "term-1", text: "hello" }]);
+    expect(harness.replays).toEqual(replay);
     expect(harness.outputs[0]?.data).toBe(outputData);
     expect(harness.outputs).toEqual([{ terminalId: "term-1", data: terminalOutput(" world") }]);
     expect(harness.statuses.at(-1)).toEqual({
@@ -236,23 +206,19 @@ describe("terminal-stream-controller", () => {
         size: { rows: 24, cols: 80 },
       }),
       onOutput: (output) => harness.outputs.push(output),
-      onRestore: (restore) => harness.restores.push(restore),
-      onSnapshot: ({ terminalId, state }) => {
-        harness.snapshots.push({
-          terminalId,
-          text: terminalSnapshotText(state),
-        });
-      },
+      onReplay: ({ replay }) => harness.replays.push(replay),
     });
 
     controller.setTerminal({ terminalId: "term-1" });
     await flushAsyncWork();
     const restoreData = terminalOutput("restored");
-    client.emit({
-      terminalId: "term-1",
-      type: "restore",
-      data: restoreData,
-    });
+    const replay: import("@getpaseo/client").TerminalReplayEvent[] = [
+      { type: "begin" },
+      { type: "data", data: restoreData },
+      { type: "end" },
+    ];
+    for (const event of replay)
+      client.emit({ terminalId: "term-1", type: "replay", replay: event });
     controller.dispose();
 
     expect(client.subscribeCalls).toEqual([
@@ -270,8 +236,7 @@ describe("terminal-stream-controller", () => {
     expect(client.resizeCalls).toEqual([
       { terminalId: "term-1", rows: 24, cols: 80, intent: "claim" },
     ]);
-    expect(harness.restores[0]?.data).toBe(restoreData);
-    expect(harness.restores).toEqual([{ terminalId: "term-1", data: terminalOutput("restored") }]);
+    expect(harness.replays).toEqual(replay);
     expect(harness.outputs).toEqual([]);
   });
 
@@ -319,3 +284,28 @@ it("reports observation failure without declaring the PTY exited, then allows re
   expect(h.statuses.at(-1)?.error).toBe(null);
   h.controller.dispose();
 });
+
+it("does not resize or attach on a JSON-era host and reports the required update", () => {
+  const client = new FakeTerminalStreamClient();
+  const statuses: TerminalStreamControllerStatus[] = [];
+  const controller = new TerminalStreamController({
+    client,
+    getPreferredSize: () => ({ rows: 24, cols: 40 }),
+    onOutput: () => {},
+    getRestoreOptions: () =>
+      resolveTerminalRestoreOptions({
+        supportsTerminalRestoreModes: false,
+        scrollbackLines: 10000,
+        canClaimSize: true,
+        size: { rows: 24, cols: 40 },
+      }),
+    onStatusChange: (status) => statuses.push(status),
+  });
+  controller.setTerminal({ terminalId: "old-host-terminal" });
+  expect(client.subscribeCalls).toEqual([]);
+  expect(client.resizeCalls).toEqual([]);
+  expect(statuses.at(-1)).toMatchObject({
+    isAttaching: false,
+    error: "Update the host to view terminals.",
+  });
+});
diff --git a/packages/app/src/terminal/runtime/terminal-stream-controller.ts b/packages/app/src/terminal/runtime/terminal-stream-controller.ts
index 90d54be4d4..b4b166cadf 100644
--- a/packages/app/src/terminal/runtime/terminal-stream-controller.ts
+++ b/packages/app/src/terminal/runtime/terminal-stream-controller.ts
@@ -1,5 +1,5 @@
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
-import type { SubscribeTerminalRequest, TerminalState } from "@getpaseo/protocol/messages";
+import type { SubscribeTerminalRequest } from "@getpaseo/protocol/messages";
 import type { TerminalOutputData } from "./terminal-emulator-runtime";
 import { i18n } from "@/i18n/i18next";
 
@@ -23,9 +23,11 @@ export interface TerminalStreamControllerOptions {
   client: TerminalStreamControllerClient;
   getPreferredSize: () => TerminalStreamControllerSize | null;
   onOutput: (input: { terminalId: string; data: TerminalOutputData }) => void;
-  onSnapshot: (input: { terminalId: string; state: TerminalState }) => void;
   onExit?: (terminalId: string) => void;
-  onRestore?: (input: { terminalId: string; data: TerminalOutputData }) => void;
+  onReplay?: (input: {
+    terminalId: string;
+    replay: import("@getpaseo/client").TerminalReplayEvent;
+  }) => void;
   getRestoreOptions?: () => SubscribeTerminalRequest["restore"] | undefined;
   onStatusChange?: (status: TerminalStreamControllerStatus) => void;
 }
@@ -43,17 +45,11 @@ export class TerminalStreamController {
     if (this.disposed || event.terminalId !== this.terminalId) {
       return;
     }
-    if (event.type === "snapshot") {
-      this.options.onSnapshot({ terminalId: event.terminalId, state: event.state });
+    if (event.type === "replay") {
+      this.options.onReplay?.({ terminalId: event.terminalId, replay: event.replay });
       return;
     }
-    if (event.type === "restore") {
-      if (event.data.length > 0) {
-        this.options.onRestore?.({ terminalId: event.terminalId, data: event.data });
-      }
-      return;
-    }
-    if (event.data.length > 0) {
+    if (event.type === "output" && event.data.length > 0) {
       this.options.onOutput({ terminalId: event.terminalId, data: event.data });
     }
   };
@@ -70,10 +66,10 @@ export class TerminalStreamController {
       this.options.onStatusChange?.({ terminalId: null, isAttaching: false, error: null });
       return;
     }
-    const restore = this.options.getRestoreOptions?.();
     this.options.onStatusChange?.({ terminalId: nextTerminalId, isAttaching: true, error: null });
     let subscription: ReturnType<DaemonClient["observeTerminal"]>;
     try {
+      const restore = this.options.getRestoreOptions?.();
       const preferredSize = restore?.size ?? this.options.getPreferredSize();
       if (preferredSize)
         this.options.client.sendTerminalInput(nextTerminalId, {
diff --git a/packages/app/src/terminal/runtime/workspace-terminal-session.test.ts b/packages/app/src/terminal/runtime/workspace-terminal-session.test.ts
deleted file mode 100644
index 97063539d6..0000000000
--- a/packages/app/src/terminal/runtime/workspace-terminal-session.test.ts
+++ /dev/null
@@ -1,75 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
-  getWorkspaceTerminalSession,
-  releaseWorkspaceTerminalSession,
-  retainWorkspaceTerminalSession,
-} from "./workspace-terminal-session";
-
-describe("workspace-terminal-session", () => {
-  it("returns the same workspace session instance for the same scope", () => {
-    const first = getWorkspaceTerminalSession({
-      scopeKey: "workspace-a",
-    });
-    const second = getWorkspaceTerminalSession({
-      scopeKey: "workspace-a",
-    });
-
-    expect(second).toBe(first);
-  });
-
-  it("preserves snapshots across repeated lookups", () => {
-    const first = getWorkspaceTerminalSession({
-      scopeKey: "workspace-snapshots",
-    });
-    first.snapshots.set({
-      terminalId: "term-1",
-      state: {
-        rows: 1,
-        cols: 1,
-        grid: [[{ char: "A" }]],
-        scrollback: [],
-        cursor: { row: 0, col: 0 },
-      },
-    });
-
-    const second = getWorkspaceTerminalSession({
-      scopeKey: "workspace-snapshots",
-    });
-
-    expect(second.snapshots.get({ terminalId: "term-1" })).toEqual({
-      rows: 1,
-      cols: 1,
-      grid: [[{ char: "A" }]],
-      scrollback: [],
-      cursor: { row: 0, col: 0 },
-    });
-  });
-
-  it("evicts workspace terminal session state when the retain count returns to zero", () => {
-    const scopeKey = "workspace-release";
-    const first = getWorkspaceTerminalSession({
-      scopeKey,
-    });
-    first.snapshots.set({
-      terminalId: "term-1",
-      state: {
-        rows: 1,
-        cols: 1,
-        grid: [[{ char: "A" }]],
-        scrollback: [],
-        cursor: { row: 0, col: 0 },
-      },
-    });
-
-    retainWorkspaceTerminalSession({ scopeKey });
-    releaseWorkspaceTerminalSession({ scopeKey });
-
-    const second = getWorkspaceTerminalSession({
-      scopeKey,
-    });
-
-    expect(second).not.toBe(first);
-    expect(second.snapshots.get({ terminalId: "term-1" })).toBeNull();
-  });
-});
diff --git a/packages/app/src/terminal/runtime/workspace-terminal-session.ts b/packages/app/src/terminal/runtime/workspace-terminal-session.ts
deleted file mode 100644
index 277f956b97..0000000000
--- a/packages/app/src/terminal/runtime/workspace-terminal-session.ts
+++ /dev/null
@@ -1,79 +0,0 @@
-import type { TerminalState } from "@getpaseo/protocol/messages";
-
-export interface WorkspaceTerminalSnapshots {
-  get: (input: { terminalId: string }) => TerminalState | null;
-  set: (input: { terminalId: string; state: TerminalState }) => void;
-  clear: (input: { terminalId: string }) => void;
-  prune: (input: { terminalIds: string[] }) => void;
-}
-
-export interface WorkspaceTerminalSession {
-  scopeKey: string;
-  snapshots: WorkspaceTerminalSnapshots;
-}
-
-interface WorkspaceTerminalSessionRecord {
-  snapshotByTerminalId: Map<string, TerminalState>;
-  session: WorkspaceTerminalSession;
-}
-
-const sessionsByScopeKey = new Map<string, WorkspaceTerminalSessionRecord>();
-const refCountByScopeKey = new Map<string, number>();
-
-function createSnapshots(input: {
-  snapshotByTerminalId: Map<string, TerminalState>;
-}): WorkspaceTerminalSnapshots {
-  return {
-    get: ({ terminalId }) => input.snapshotByTerminalId.get(terminalId) ?? null,
-    set: ({ terminalId, state }) => {
-      input.snapshotByTerminalId.set(terminalId, state);
-    },
-    clear: ({ terminalId }) => {
-      input.snapshotByTerminalId.delete(terminalId);
-    },
-    prune: ({ terminalIds }) => {
-      const terminalIdSet = new Set(terminalIds);
-      for (const terminalId of Array.from(input.snapshotByTerminalId.keys())) {
-        if (!terminalIdSet.has(terminalId)) {
-          input.snapshotByTerminalId.delete(terminalId);
-        }
-      }
-    },
-  };
-}
-
-export function getWorkspaceTerminalSession(input: { scopeKey: string }): WorkspaceTerminalSession {
-  const existing = sessionsByScopeKey.get(input.scopeKey);
-  if (existing) {
-    return existing.session;
-  }
-
-  const snapshotByTerminalId = new Map<string, TerminalState>();
-  const session: WorkspaceTerminalSession = {
-    scopeKey: input.scopeKey,
-    snapshots: createSnapshots({
-      snapshotByTerminalId,
-    }),
-  };
-
-  sessionsByScopeKey.set(input.scopeKey, {
-    snapshotByTerminalId,
-    session,
-  });
-  return session;
-}
-
-export function retainWorkspaceTerminalSession(input: { scopeKey: string }): void {
-  const current = refCountByScopeKey.get(input.scopeKey) ?? 0;
-  refCountByScopeKey.set(input.scopeKey, current + 1);
-}
-
-export function releaseWorkspaceTerminalSession(input: { scopeKey: string }): void {
-  const current = refCountByScopeKey.get(input.scopeKey) ?? 0;
-  if (current > 1) {
-    refCountByScopeKey.set(input.scopeKey, current - 1);
-    return;
-  }
-  refCountByScopeKey.delete(input.scopeKey);
-  sessionsByScopeKey.delete(input.scopeKey);
-}
diff --git a/packages/app/src/timeline/replica.test.ts b/packages/app/src/timeline/replica.test.ts
index 47bd36596a..0ce9b8ca2b 100644
--- a/packages/app/src/timeline/replica.test.ts
+++ b/packages/app/src/timeline/replica.test.ts
@@ -11,6 +11,7 @@ import type { CachedTimeline } from "@/runtime/replica-cache";
 import { selectAgentTimelineState, useSessionStore } from "@/stores/session-store";
 import { useCreateFlowStore, type PendingCreateAttempt } from "@/stores/create-flow-store";
 import type { StreamItem } from "@/types/stream";
+import type { TurnLivenessTransition } from "./turn-liveness";
 import {
   createTimelineReplica,
   createViewedTimelineOwner,
@@ -40,7 +41,13 @@ function cachedTimeline(): CachedTimeline {
   };
 }
 
-function createOwner(storage: TimelineReplicaStorage): ViewedTimelineOwner {
+function createOwner(
+  storage: TimelineReplicaStorage,
+  applyTurnLiveness: (
+    agentId: string,
+    transitions: readonly TurnLivenessTransition[],
+  ) => void = () => undefined,
+): ViewedTimelineOwner {
   const replica = createTimelineReplica({
     serverId: SERVER_ID,
     storage,
@@ -51,13 +58,13 @@ 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 }),
       fetchLatestTail: async () => ({ hasNewer: false, endCursor: null }),
       reportError: () => undefined,
-      schedule: () => () => undefined,
     },
   });
 }
@@ -99,7 +106,7 @@ describe("viewed timeline persistence", () => {
               .status,
         )
         .toBe("painted");
-      owner.enqueueStreamEvent(AGENT_ID, {
+      owner.applyStreamEvent(AGENT_ID, {
         event: {
           type: "timeline",
           provider: "codex",
@@ -148,7 +155,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",
@@ -282,7 +289,7 @@ describe("viewed timeline persistence", () => {
       )
       .toMatchObject({ status: "painted" });
 
-    first.enqueueStreamEvent(AGENT_ID, {
+    first.applyStreamEvent(AGENT_ID, {
       event: {
         type: "timeline",
         provider: "codex",
@@ -371,6 +378,22 @@ describe("viewed timeline persistence", () => {
     ]);
   });
 
+  it("preparing an already painted cache again keeps history out of the live head", async () => {
+    useSessionStore.getState().initializeSession(SERVER_ID, null);
+    const replica = createTimelineReplica({
+      serverId: SERVER_ID,
+      storage: { readTimeline: async () => cachedTimeline(), commitTimeline: () => undefined },
+      prepareAgent: async () => undefined,
+    });
+    await replica.prepare(AGENT_ID);
+    const painted = useSessionStore.getState().sessions[SERVER_ID]!.agentStreamTail.get(AGENT_ID);
+    expect(painted).toEqual(cachedTimeline().items);
+    await replica.prepare(AGENT_ID);
+    const session = useSessionStore.getState().sessions[SERVER_ID]!;
+    expect(session.agentStreamHead.get(AGENT_ID) ?? []).toEqual([]);
+    expect(session.agentStreamTail.get(AGENT_ID)).toBe(painted);
+  });
+
   it("reconciles a live head that overlaps the cached canonical timeline", async () => {
     useSessionStore.getState().initializeSession(SERVER_ID, null);
     let release!: (value: CachedTimeline) => void;
@@ -445,7 +468,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",
@@ -510,7 +533,7 @@ describe("viewed timeline persistence", () => {
       [AGENT_ID, 9],
       ["agent-2", 4],
     ] as const) {
-      owner.enqueueStreamEvent(agentId, {
+      owner.applyStreamEvent(agentId, {
         event: {
           type: "timeline",
           provider: "codex",
@@ -528,6 +551,81 @@ describe("viewed timeline persistence", () => {
   });
 });
 
+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("create handoff lifetime", () => {
   const DRAFT_ID = "draft-1";
 
@@ -591,6 +689,7 @@ describe("create handoff lifetime", () => {
       replica,
       replaceDemandedAgentIds: () => undefined,
       drainQueuedAgentMessage: () => undefined,
+      applyTurnLiveness: () => undefined,
       ports: {
         observe: () => ({ ready: Promise.resolve(), release: async () => undefined }),
         readCursor: () => undefined,
@@ -601,7 +700,6 @@ describe("create handoff lifetime", () => {
         },
         fetchLatestTail: async () => ({ hasNewer: false, endCursor: null }),
         reportError: () => undefined,
-        schedule: () => () => undefined,
       },
     });
 
diff --git a/packages/app/src/timeline/session-stream-reducers.test.ts b/packages/app/src/timeline/session-stream-reducers.test.ts
index 9e57142846..0e401ad7a0 100644
--- a/packages/app/src/timeline/session-stream-reducers.test.ts
+++ b/packages/app/src/timeline/session-stream-reducers.test.ts
@@ -19,6 +19,66 @@ import {
   type TimelineCursor,
 } from "./session-stream-reducers";
 
+it("keeps streamed reasoning together while the initial history is loading", () => {
+  let head: StreamItem[] = [];
+  const chunks = ["Checking a long oper", "ation before", " the re", "sult arrives."];
+  for (const [index, text] of chunks.entries()) {
+    const result = processAgentStreamEvent({
+      event: {
+        type: "timeline",
+        provider: "codex",
+        turnId: "turn-18",
+        item: { type: "reasoning", text },
+      },
+      seq: index + 1,
+      epoch: "epoch-1",
+      currentTail: [],
+      currentHead: head,
+      currentCursor: undefined,
+      timestamp: new Date(1000 + index),
+      hasAuthoritativeBaseline: false,
+    });
+    head = result.head;
+    expect(head).toHaveLength(1);
+    expect(head[0]).toMatchObject({
+      kind: "thought",
+      text: chunks.slice(0, index + 1).join(""),
+      turnId: "turn-18",
+    });
+  }
+});
+
+it.each([false, true])(
+  "keeps adjacent reasoning from different turns separate (history loaded: %s)",
+  (hasAuthoritativeBaseline) => {
+    let head: StreamItem[] = [];
+    let tail: StreamItem[] = [];
+    for (const [index, turnId] of ["turn-1", "turn-2"].entries()) {
+      const result = processAgentStreamEvent({
+        event: {
+          type: "timeline",
+          provider: "codex",
+          turnId,
+          item: { type: "reasoning", text: turnId },
+        },
+        seq: index + 1,
+        epoch: "epoch-1",
+        currentTail: tail,
+        currentHead: head,
+        currentCursor: undefined,
+        timestamp: new Date(1000),
+        hasAuthoritativeBaseline,
+      });
+      head = result.head;
+      tail = result.tail;
+    }
+    expect([...tail, ...head]).toMatchObject([
+      { kind: "thought", text: "turn-1", turnId: "turn-1" },
+      { kind: "thought", text: "turn-2", turnId: "turn-2" },
+    ]);
+  },
+);
+
 // ---------------------------------------------------------------------------
 // Test helpers
 // ---------------------------------------------------------------------------
diff --git a/packages/app/src/timeline/session-stream-reducers.ts b/packages/app/src/timeline/session-stream-reducers.ts
index 34a461d893..a46ec8188f 100644
--- a/packages/app/src/timeline/session-stream-reducers.ts
+++ b/packages/app/src/timeline/session-stream-reducers.ts
@@ -1615,19 +1615,17 @@ export function processAgentStreamEvent(
         unmatchedUserMessageInsert: "head",
       });
     } else {
-      const overlay = applyStreamEvent({
-        tail: currentHead,
-        head: [],
-        event,
-        timestamp,
+      // Before history arrives, the overlay is one ordered stream. Reducing it
+      // directly keeps consecutive reasoning chunks in the same row.
+      const overlay = reduceStreamUpdate(currentHead, event, timestamp, {
         source: "live",
         timelineCursor,
       });
       streamResult = {
         tail: currentTail,
-        head: [...overlay.tail, ...overlay.head],
+        head: overlay,
         changedTail: false,
-        changedHead: overlay.changedTail || overlay.changedHead,
+        changedHead: overlay !== currentHead,
       };
     }
   } else {
diff --git a/packages/app/src/timeline/timeline-replacement.test.ts b/packages/app/src/timeline/timeline-replacement.test.ts
index f457ea7daa..cea2dc909d 100644
--- a/packages/app/src/timeline/timeline-replacement.test.ts
+++ b/packages/app/src/timeline/timeline-replacement.test.ts
@@ -15,7 +15,7 @@ describe("requestTimelineReplacement", () => {
     await expect(requestTimelineReplacement(client, "agent-1")).rejects.toThrow("fetch complete");
 
     expect(requests).toEqual([
-      ["agent-1", { direction: "tail", projection: "projected", limit: 40 }],
+      ["agent-1", { direction: "tail", projection: "projected", wholeTurns: true, limit: 40 }],
     ]);
   });
 });
diff --git a/packages/app/src/timeline/timeline-sync-plan.test.ts b/packages/app/src/timeline/timeline-sync-plan.test.ts
index 9135b5fb85..093941fb77 100644
--- a/packages/app/src/timeline/timeline-sync-plan.test.ts
+++ b/packages/app/src/timeline/timeline-sync-plan.test.ts
@@ -17,6 +17,7 @@ describe("timeline sync planning", () => {
       direction: "tail",
       limit: TIMELINE_FETCH_PAGE_SIZE,
       projection: "projected",
+      wholeTurns: true,
     });
   });
 
@@ -26,6 +27,7 @@ describe("timeline sync planning", () => {
       cursor: { epoch: "epoch-1", seq: 49 },
       limit: TIMELINE_FETCH_PAGE_SIZE,
       projection: "projected",
+      wholeTurns: true,
     });
   });
 
@@ -37,6 +39,7 @@ describe("timeline sync planning", () => {
       cursor: { epoch: "epoch-1", seq: 25 },
       limit: TIMELINE_FETCH_PAGE_SIZE,
       projection: "projected",
+      wholeTurns: true,
     });
   });
 
@@ -49,6 +52,7 @@ describe("timeline sync planning", () => {
       },
       limit: TIMELINE_FETCH_PAGE_SIZE,
       projection: "projected",
+      wholeTurns: true,
       mergeWindow: true,
     });
   });
diff --git a/packages/app/src/timeline/timeline-sync-plan.ts b/packages/app/src/timeline/timeline-sync-plan.ts
index e5e8b2fb95..b66de16941 100644
--- a/packages/app/src/timeline/timeline-sync-plan.ts
+++ b/packages/app/src/timeline/timeline-sync-plan.ts
@@ -9,6 +9,7 @@ export interface ProjectedTimelineTailFetchPlan {
   direction: "tail";
   limit: number;
   projection: "projected";
+  wholeTurns: true;
 }
 
 export interface ProjectedTimelineAfterFetchPlan {
@@ -16,6 +17,7 @@ export interface ProjectedTimelineAfterFetchPlan {
   cursor: TimelineSyncCursor;
   limit: number;
   projection: "projected";
+  wholeTurns: true;
 }
 
 export interface ProjectedTimelineBeforeFetchPlan {
@@ -23,6 +25,7 @@ export interface ProjectedTimelineBeforeFetchPlan {
   cursor: TimelineSyncCursor;
   limit: number;
   projection: "projected";
+  wholeTurns: true;
 }
 
 export type ProjectedTimelineFetchPlan =
@@ -40,6 +43,7 @@ export function planTimelineCatchUpAfter(cursor: TimelineSyncCursor) {
     cursor,
     limit: TIMELINE_FETCH_PAGE_SIZE,
     projection: "projected",
+    wholeTurns: true,
   } as const;
 }
 
@@ -48,6 +52,7 @@ export function planTimelineTailFetch() {
     direction: "tail",
     limit: TIMELINE_FETCH_PAGE_SIZE,
     projection: "projected",
+    wholeTurns: true,
   } as const;
 }
 
@@ -65,6 +70,7 @@ export function planTimelineOlderFetch(cursor: TimelineSyncCursor) {
     cursor,
     limit: TIMELINE_FETCH_PAGE_SIZE,
     projection: "projected",
+    wholeTurns: true,
   } as const;
 }
 
@@ -75,6 +81,7 @@ export function planTimelinePromptJump(target: TimelineSyncCursor) {
     cursor: { epoch: target.epoch, seq: target.seq + newerRows + 1 },
     limit: TIMELINE_FETCH_PAGE_SIZE,
     projection: "projected",
+    wholeTurns: true,
     mergeWindow: true,
   } as const;
 }
diff --git a/packages/app/src/timeline/turn-time.test.ts b/packages/app/src/timeline/turn-time.test.ts
index 3ce6942301..f3e97b2e49 100644
--- a/packages/app/src/timeline/turn-time.test.ts
+++ b/packages/app/src/timeline/turn-time.test.ts
@@ -51,7 +51,7 @@ describe("deriveStreamTurnTiming", () => {
     });
 
     assert.equal(timing.runningStartedAt, secondUserAt);
-    assert.equal(timing.byAssistantId.has("a2"), false);
+    assert.equal(timing.byItemId.has("a2"), false);
   });
 
   it("derives completed turn timing from user and assistant item timestamps", () => {
@@ -69,7 +69,7 @@ describe("deriveStreamTurnTiming", () => {
       head: [],
     });
 
-    assert.deepEqual(timing.byAssistantId.get("a1"), {
+    assert.deepEqual(timing.byItemId.get("a1"), {
       completedAt: assistantAt,
       durationMs: 7000,
     });
@@ -95,8 +95,8 @@ describe("deriveStreamTurnTiming", () => {
       completedAt: lastAssistantAt,
       durationMs: 7000,
     };
-    assert.deepEqual(timing.byAssistantId.get("a1"), expected);
-    assert.deepEqual(timing.byAssistantId.get("a2"), expected);
+    assert.deepEqual(timing.byItemId.get("a1"), expected);
+    assert.deepEqual(timing.byItemId.get("a2"), expected);
   });
 
   it("preserves the completion timestamp when a canonical turn has no visible prompt", () => {
@@ -120,7 +120,7 @@ describe("deriveStreamTurnTiming", () => {
       head: [],
     });
 
-    assert.deepEqual(timing.byAssistantId.get("hidden-prompt-a2"), {
+    assert.deepEqual(timing.byItemId.get("hidden-prompt-a2"), {
       completedAt: hiddenPromptTurnAt,
       durationMs: null,
     });
@@ -143,12 +143,12 @@ describe("deriveStreamTurnTiming", () => {
     const first = derive("one", "2026-05-15T00:01:04.000Z");
     const second = derive("one two", "2026-05-15T00:01:05.000Z");
 
-    assert.equal(second.byAssistantId, first.byAssistantId);
-    assert.deepEqual(first.byAssistantId.get("a1"), {
+    assert.equal(second.byItemId, first.byItemId);
+    assert.deepEqual(first.byItemId.get("a1"), {
       completedAt: tail[1]?.timestamp,
       durationMs: 7000,
     });
-    assert.equal(first.byAssistantId.has("a2"), false);
+    assert.equal(first.byItemId.has("a2"), false);
   });
 
   it("keeps the timing map identity when the head closed the tail's open turn", () => {
@@ -168,8 +168,8 @@ describe("deriveStreamTurnTiming", () => {
     const first = derive("one", "2026-05-15T00:01:04.000Z");
     const second = derive("one two", "2026-05-15T00:01:05.000Z");
 
-    assert.equal(second.byAssistantId, first.byAssistantId);
-    assert.deepEqual(first.byAssistantId.get("a1"), {
+    assert.equal(second.byItemId, first.byItemId);
+    assert.deepEqual(first.byItemId.get("a1"), {
       completedAt: lastTailAt,
       durationMs: 7000,
     });
@@ -193,9 +193,9 @@ describe("deriveStreamTurnTiming", () => {
       head,
     });
 
-    assert.notEqual(completed.byAssistantId, active.byAssistantId);
-    assert.equal(active.byAssistantId.has("a1"), false);
-    assert.deepEqual(completed.byAssistantId.get("a1"), { completedAt, durationMs: 9000 });
+    assert.notEqual(completed.byItemId, active.byItemId);
+    assert.equal(active.byItemId.has("a1"), false);
+    assert.deepEqual(completed.byItemId.get("a1"), { completedAt, durationMs: 9000 });
   });
 
   it("derives fresh timing when the tail itself changes", () => {
@@ -211,11 +211,39 @@ describe("deriveStreamTurnTiming", () => {
     const first = derive(firstTail);
     const second = derive(secondTail);
 
-    assert.notEqual(second.byAssistantId, first.byAssistantId);
-    assert.equal(first.byAssistantId.has("a2"), false);
-    assert.deepEqual(second.byAssistantId.get("a2"), {
+    assert.notEqual(second.byItemId, first.byItemId);
+    assert.equal(first.byItemId.has("a2"), false);
+    assert.deepEqual(second.byItemId.get("a2"), {
       completedAt: secondTail[3]?.timestamp,
       durationMs: 3000,
     });
   });
 });
+
+it("times a heartbeat that ends with tools and no assistant text", () => {
+  const trigger: StreamItem = {
+    kind: "tool_call",
+    id: "trigger",
+    timestamp: new Date("2026-05-15T00:00:00Z"),
+    turnId: "heartbeat",
+    payload: {
+      source: "agent",
+      data: {
+        provider: "claude",
+        callId: "trigger",
+        name: "heartbeat",
+        status: "completed",
+        error: null,
+        detail: { type: "plain_text", text: "Check progress" },
+      },
+    },
+  };
+  const tool: StreamItem = { ...trigger, id: "last", timestamp: new Date("2026-05-15T00:00:05Z") };
+  const timing = deriveStreamTurnTiming({
+    tail: [trigger, tool],
+    head: [],
+    isTurnActive: false,
+    activeTurnStartedAt: null,
+  });
+  assert.equal(timing.byItemId.get("last")?.durationMs, 5000);
+});
diff --git a/packages/app/src/timeline/turn-time.ts b/packages/app/src/timeline/turn-time.ts
index c47a6983cd..8d1aa00648 100644
--- a/packages/app/src/timeline/turn-time.ts
+++ b/packages/app/src/timeline/turn-time.ts
@@ -1,5 +1,5 @@
 import type { StreamItem } from "@/types/stream";
-import { startsNewTurn } from "@/agent-stream/turn-membership";
+import { startsNewTurn, isTurnTrigger } from "@/agent-stream/turn-membership";
 
 export interface TurnTiming {
   completedAt: Date;
@@ -7,7 +7,7 @@ export interface TurnTiming {
 }
 
 export interface StreamTurnTiming {
-  byAssistantId: Map<string, TurnTiming>;
+  byItemId: Map<string, TurnTiming>;
   runningStartedAt: Date | null;
 }
 
@@ -20,7 +20,7 @@ interface OpenTurn {
 
 interface HeadTurnTiming {
   additions: Map<string, TurnTiming>;
-  byAssistantId: Map<string, TurnTiming>;
+  byItemId: Map<string, TurnTiming>;
 }
 
 interface TailTurnTiming {
@@ -37,14 +37,18 @@ const EMPTY_OPEN_TURN: OpenTurn = {
 };
 
 function closeTurn(turn: OpenTurn, into: Map<string, TurnTiming>): void {
-  if (!turn.lastItemAt || turn.assistantIds.length === 0) {
+  if (!turn.lastItemAt) {
     return;
   }
   const timing: TurnTiming = {
     completedAt: turn.lastItemAt,
     durationMs: turn.userAt ? Math.max(0, turn.lastItemAt.getTime() - turn.userAt.getTime()) : null,
   };
-  for (const id of turn.assistantIds) {
+  let footerIds = turn.assistantIds;
+  if (footerIds.length === 0 && turn.previousItem?.kind === "tool_call") {
+    footerIds = [turn.previousItem.id];
+  }
+  for (const id of footerIds) {
     into.set(id, timing);
   }
 }
@@ -61,7 +65,7 @@ function walkTurns(
   for (const item of items) {
     if (startsNewTurn(item, previousItem)) {
       closeTurn({ userAt, lastItemAt, assistantIds, previousItem }, into);
-      userAt = item.kind === "user_message" ? item.timestamp : null;
+      userAt = isTurnTrigger(item) ? item.timestamp : null;
       lastItemAt = null;
       assistantIds = [];
     }
@@ -108,7 +112,7 @@ function getTailTurnTiming(tail: StreamItem[]): TailTurnTiming {
   return timing;
 }
 
-function resolveByAssistantId(
+function resolveByItemId(
   tail: TailTurnTiming,
   additions: Map<string, TurnTiming>,
 ): Map<string, TurnTiming> {
@@ -116,14 +120,14 @@ function resolveByAssistantId(
     return tail.completed;
   }
   if (tail.lastHead && areTimingsEqual(tail.lastHead.additions, additions)) {
-    return tail.lastHead.byAssistantId;
+    return tail.lastHead.byItemId;
   }
-  const byAssistantId = new Map(tail.completed);
+  const byItemId = new Map(tail.completed);
   for (const [id, timing] of additions) {
-    byAssistantId.set(id, timing);
+    byItemId.set(id, timing);
   }
-  tail.lastHead = { additions, byAssistantId };
-  return byAssistantId;
+  tail.lastHead = { additions, byItemId };
+  return byItemId;
 }
 
 export function deriveStreamTurnTiming(params: {
@@ -139,7 +143,7 @@ export function deriveStreamTurnTiming(params: {
     closeTurn(openTurn, additions);
   }
   return {
-    byAssistantId: resolveByAssistantId(tail, additions),
+    byItemId: resolveByItemId(tail, additions),
     runningStartedAt: params.isTurnActive ? params.activeTurnStartedAt : null,
   };
 }
diff --git a/packages/app/src/timeline/viewed-timeline-sync.test.ts b/packages/app/src/timeline/viewed-timeline-sync.test.ts
index 9bf6897bd9..e556da612f 100644
--- a/packages/app/src/timeline/viewed-timeline-sync.test.ts
+++ b/packages/app/src/timeline/viewed-timeline-sync.test.ts
@@ -90,7 +90,7 @@ test("visible catch-up settles before hidden open chats start fetching", async (
   world.sync.dispose();
 });
 
-test("a failed visible catch-up releases hidden chats without bypassing its retry delay", async () => {
+test("a failed visible catch-up releases hidden chats without bypassing its error", async () => {
   const world = new TimelineWorld();
   world.openedEarlier(["a-hidden"]);
   world.sync.replaceVisibleAgentIds("pane", ["z-visible"]);
@@ -103,7 +103,7 @@ test("a failed visible catch-up releases hidden chats without bypassing its retr
   hidden.respond({ hasNewer: false });
   await world.nextError();
   world.expectNoPendingFetch();
-  (await world.nextRetry())();
+  world.sync.retryVisibleAgentTimeline("z-visible");
   (await world.nextFetch("z-visible")).respond({ hasNewer: false });
   world.sync.dispose();
 });
@@ -189,6 +189,7 @@ class TimelineWorld {
           direction: "tail",
           limit: 40,
           projection: "projected",
+          wholeTurns: true,
         });
       } finally {
         this.forcedTimelineTailReplacements.delete(agentId);
@@ -199,20 +200,6 @@ class TimelineWorld {
       const waiter = this.errorWaiters.shift();
       if (waiter) waiter(this.errors.at(-1) ?? "");
     },
-    schedule: (task, delayMs) => {
-      const scheduled = { task, delayMs };
-      this.scheduled.push(scheduled);
-      const waiterIndex = this.retryWaiters.findIndex((waiter) => waiter.delayMs === delayMs);
-      if (waiterIndex >= 0) {
-        const [waiter] = this.retryWaiters.splice(waiterIndex, 1);
-        this.scheduled.splice(this.scheduled.indexOf(scheduled), 1);
-        waiter.resolve(task);
-      }
-      return () => {
-        const index = this.scheduled.indexOf(scheduled);
-        if (index >= 0) this.scheduled.splice(index, 1);
-      };
-    },
   });
 
   show(sourceId: string, agentIds: string[]): void {
@@ -234,12 +221,6 @@ class TimelineWorld {
   }> = [];
   private readonly errorWaiters: Array<(message: string) => void> = [];
   private readonly cacheRequestWaiters: Array<(agentId: string) => void> = [];
-  private readonly scheduled: Array<{ task: () => void; delayMs: number }> = [];
-  private readonly retryWaiters: Array<{
-    delayMs: number;
-    resolve(retry: () => void): void;
-  }> = [];
-
   get pendingFetchCount(): number {
     return this.fetches.length;
   }
@@ -299,22 +280,6 @@ class TimelineWorld {
     return new Promise((resolve) => this.errorWaiters.push(resolve));
   }
 
-  nextRetry(delayMs = 1_000): Promise<() => void> {
-    const index = this.scheduled.findIndex((entry) => entry.delayMs === delayMs);
-    if (index >= 0) return Promise.resolve(this.scheduled.splice(index, 1)[0].task);
-    return new Promise((resolve) => this.retryWaiters.push({ delayMs, resolve }));
-  }
-
-  elapse(elapsedMs: number): void {
-    const due = this.scheduled.filter((entry) => entry.delayMs <= elapsedMs);
-    this.scheduled.splice(
-      0,
-      this.scheduled.length,
-      ...this.scheduled.filter((entry) => entry.delayMs > elapsedMs),
-    );
-    for (const entry of due) entry.task();
-  }
-
   private releaseMembershipWaiter(): void {
     const waiter = this.membershipWaiters.shift();
     if (!waiter) return;
@@ -341,7 +306,12 @@ test("uses a tail fetch when an agent becomes visible", async () => {
   membership.succeed();
 
   const fetch = await world.nextFetch("agent-a");
-  expect(fetch.request).toEqual({ direction: "tail", limit: 40, projection: "projected" });
+  expect(fetch.request).toEqual({
+    direction: "tail",
+    limit: 40,
+    projection: "projected",
+    wholeTurns: true,
+  });
   fetch.respond({ hasNewer: false });
 });
 
@@ -366,6 +336,7 @@ test("loads the cache before choosing the authoritative network request", async
     cursor: { epoch: "cached-epoch", seq: 17 },
     limit: 40,
     projection: "projected",
+    wholeTurns: true,
   });
   fetch.respond({ hasNewer: false });
 });
@@ -384,6 +355,7 @@ test("catches up after the restored cursor when an agent becomes visible", async
     cursor: { epoch: "epoch-agent-a", seq: 42 },
     limit: 40,
     projection: "projected",
+    wholeTurns: true,
   });
   fetch.respond({ hasNewer: false });
 });
@@ -401,7 +373,12 @@ test("falls back to the latest tail when a restored cursor has more than one cat
   probe.respond({ hasNewer: true, seq: 82 });
 
   const fallback = await world.nextFetch("agent-a");
-  expect(fallback.request).toEqual({ direction: "tail", limit: 40, projection: "projected" });
+  expect(fallback.request).toEqual({
+    direction: "tail",
+    limit: 40,
+    projection: "projected",
+    wholeTurns: true,
+  });
   expect(
     world.applyTimelineResponse({
       requestId: "fallback-tail",
@@ -444,6 +421,7 @@ test("a gap absorbed by a running tail is recovered after the tail completes", a
     cursor: { epoch: "epoch-agent-a", seq: 9 },
     limit: 40,
     projection: "projected",
+    wholeTurns: true,
   });
   recovery.respond({ hasNewer: false });
   await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
@@ -469,6 +447,28 @@ test("reports a chat current only once its parked follow-up page completes", asy
   world.sync.dispose();
 });
 
+test("a gap during manual retry is recovered before reporting ready", async () => {
+  const world = new TimelineWorld();
+  world.sync.setConnected(true);
+  world.show("workspace", ["agent-a"]);
+  (await world.nextMembership()).succeed();
+  (await world.nextFetch("agent-a")).fail("unavailable");
+  await world.nextError();
+  world.sync.retryVisibleAgentTimeline("agent-a");
+  const retry = await world.nextFetch("agent-a");
+  world.sync.recoverGap("agent-a", { epoch: "epoch-agent-a", endSeq: 9 });
+  retry.respond({ hasNewer: false });
+  await vi.waitFor(() => expect(world.pendingFetchCount).toBe(1));
+  const recovery = await world.nextFetch("agent-a");
+  expect(recovery.request).toMatchObject({
+    direction: "after",
+    cursor: { epoch: "epoch-agent-a", seq: 9 },
+  });
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("retrying");
+  recovery.respond({ hasNewer: false });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+});
+
 test("reports a chat current once the latest-tail fallback replaces an overflowing catch-up", async () => {
   const world = new TimelineWorld();
   world.cursors.set("agent-a", { epoch: "epoch-agent-a", endSeq: 42 });
@@ -527,6 +527,7 @@ test("unchanged visible-set publication does not cancel paged catch-up", async (
     cursor: { epoch: "epoch-agent-a", seq: 5 },
     limit: 40,
     projection: "projected",
+    wholeTurns: true,
   });
   world.expectNoPendingMembership();
 });
@@ -765,6 +766,21 @@ test("overlapping sources deduplicate membership and retain open hidden chats",
   world.expectNoPendingFetch();
 });
 
+test("failed timeline fetch does not schedule a retry", async () => {
+  vi.useFakeTimers();
+  const world = new TimelineWorld();
+  world.sync.setConnected(true);
+  world.show("workspace", ["agent-a"]);
+  (await world.nextMembership()).succeed();
+  (await world.nextFetch("agent-a")).fail("unavailable");
+  await world.nextError();
+  expect(vi.getTimerCount()).toBe(0);
+  await vi.advanceTimersByTimeAsync(120_000);
+  world.expectNoPendingFetch();
+  world.expectNoPendingMembership();
+  vi.useRealTimers();
+});
+
 test("a failed catch-up reports once and retries through the explicit retry policy", async () => {
   const world = new TimelineWorld();
   world.sync.setConnected(true);
@@ -773,12 +789,12 @@ test("a failed catch-up reports once and retries through the explicit retry poli
   membership.succeed();
   const failed = await world.nextFetch("agent-a");
   failed.fail("timeline unavailable");
-  const [error, retryCatchUp] = await Promise.all([world.nextError(), world.nextRetry()]);
+  const error = await world.nextError();
   expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("error");
 
-  retryCatchUp();
+  world.sync.retryVisibleAgentTimeline("agent-a");
   const retry = await world.nextFetch("agent-a");
-  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("error");
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("retrying");
   retry.respond({ hasNewer: false });
   await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
 
@@ -789,35 +805,6 @@ test("a failed catch-up reports once and retries through the explicit retry poli
   world.expectNoPendingMembership();
 });
 
-test("a failed catch-up retries with exponential backoff", async () => {
-  const world = new TimelineWorld();
-  world.sync.setConnected(true);
-  world.sync.replaceVisibleAgentIds("workspace", ["agent-a"]);
-  const membership = await world.nextMembership();
-  membership.succeed();
-
-  const first = await world.nextFetch("agent-a");
-  first.fail("timeline unavailable");
-  const [firstError, retryAfterFirstFailure] = await Promise.all([
-    world.nextError(),
-    world.nextRetry(),
-  ]);
-  expect(firstError).toBe("timeline unavailable");
-  retryAfterFirstFailure();
-
-  const second = await world.nextFetch("agent-a");
-  second.fail("timeline unavailable");
-  await world.nextError();
-
-  const retryAfterSecondFailure = await world.nextRetry(2_000);
-  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("error");
-
-  retryAfterSecondFailure();
-  const third = await world.nextFetch("agent-a");
-  third.respond({ hasNewer: false });
-  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
-});
-
 test("manual retries can immediately re-attempt a failed catch-up", async () => {
   const world = new TimelineWorld();
   world.sync.setConnected(true);
@@ -827,7 +814,7 @@ test("manual retries can immediately re-attempt a failed catch-up", async () =>
 
   const failed = await world.nextFetch("agent-a");
   failed.fail("timeline unavailable");
-  await world.nextRetry();
+  await world.nextError();
   expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("error");
 
   world.sync.retryVisibleAgentTimeline("agent-a");
@@ -838,7 +825,7 @@ test("manual retries can immediately re-attempt a failed catch-up", async () =>
   await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
 });
 
-test("redeclaring unchanged visibility does not bypass catch-up backoff", async () => {
+test("redeclaring unchanged visibility does not bypass catch-up error", async () => {
   const world = new TimelineWorld();
   world.sync.setConnected(true);
   world.sync.replaceVisibleAgentIds("workspace", ["agent-a"]);
@@ -847,9 +834,11 @@ test("redeclaring unchanged visibility does not bypass catch-up backoff", async
 
   const failed = await world.nextFetch("agent-a");
   failed.fail("timeline unavailable");
-  await world.nextRetry();
+  await world.nextError();
 
   world.sync.replaceVisibleAgentIds("workspace", ["agent-a"]);
+  world.sync.setActive(false);
+  world.sync.setActive(true);
 
   world.expectNoPendingMembership();
   world.expectNoPendingFetch();
@@ -865,7 +854,7 @@ test("a manual retry that fails returns to the error state", async () => {
 
   const failed = await world.nextFetch("agent-a");
   failed.fail("timeline unavailable");
-  await world.nextRetry();
+  await world.nextError();
 
   world.sync.retryVisibleAgentTimeline("agent-a");
   expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("retrying");
@@ -897,12 +886,14 @@ test("gap recovery supersedes completed catch-up and pages through the current t
       cursor: { epoch: "epoch-agent-a", seq: 10 },
       limit: 40,
       projection: "projected",
+      wholeTurns: true,
     },
     {
       direction: "after",
       cursor: { epoch: "epoch-agent-a", seq: 15 },
       limit: 40,
       projection: "projected",
+      wholeTurns: true,
     },
   ]);
 });
@@ -926,20 +917,34 @@ test("repeated recovery for the same running gap reuses the in-flight fetch", as
   gapPage.respond({ hasNewer: false });
 });
 
-test("membership failure autonomously retries without another visibility declaration", async () => {
+test("failed membership does not schedule a retry", async () => {
+  vi.useFakeTimers();
+  const world = new TimelineWorld();
+  world.sync.setConnected(true);
+  world.show("workspace", ["agent-a"]);
+  (await world.nextMembership()).fail("unavailable");
+  await world.nextError();
+  expect(vi.getTimerCount()).toBe(0);
+  await vi.advanceTimersByTimeAsync(120_000);
+  world.expectNoPendingFetch();
+  world.expectNoPendingMembership();
+  vi.useRealTimers();
+});
+
+test("membership failure waits for manual retry", async () => {
   const world = new TimelineWorld();
   world.sync.setConnected(true);
   world.sync.replaceVisibleAgentIds("workspace", ["agent-a"]);
   const failed = await world.nextMembership();
   failed.fail("subscription unavailable");
-  const [error, retryMembership] = await Promise.all([world.nextError(), world.nextRetry()]);
+  const error = await world.nextError();
   expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("error");
 
-  retryMembership();
+  world.sync.retryVisibleAgentTimeline("agent-a");
   const retry = await world.nextMembership();
   retry.succeed();
   const catchUp = await world.nextFetch("agent-a");
-  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("error");
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("retrying");
   catchUp.respond({ hasNewer: false });
   await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
 
@@ -950,44 +955,68 @@ test("membership failure autonomously retries without another visibility declara
   });
 });
 
-test("membership failures retry with exponential backoff", async () => {
+test("retrying membership restores a previously loaded chat", async () => {
   const world = new TimelineWorld();
   world.sync.setConnected(true);
-  world.sync.replaceVisibleAgentIds("workspace", ["agent-a"]);
-
-  const first = await world.nextMembership();
-  first.fail("subscription unavailable");
-  const [firstError, retryAfterFirstFailure] = await Promise.all([
-    world.nextError(),
-    world.nextRetry(),
-  ]);
-  expect(firstError).toBe("subscription unavailable");
-
-  retryAfterFirstFailure();
-  const second = await world.nextMembership();
-  second.fail("subscription unavailable again");
-
-  const retryAfterSecondFailure = await world.nextRetry(2_000);
-  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("error");
-
-  retryAfterSecondFailure();
-  const retry = await world.nextMembership();
-  retry.succeed();
-  const catchUp = await world.nextFetch("agent-a");
-  catchUp.respond({ hasNewer: false });
+  world.show("workspace", ["agent-a"]);
+  (await world.nextMembership()).succeed();
+  (await world.nextFetch("agent-a")).respond({ hasNewer: false });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+  world.cursors.set("agent-a", { epoch: "epoch-agent-a", endSeq: 10 });
+  world.show("workspace", ["agent-b"]);
+  (await world.nextMembership()).fail("subscription unavailable");
+  await world.nextError();
+  world.sync.retryVisibleAgentTimeline("agent-a");
+  (await world.nextMembership()).succeed();
+  (await world.nextFetch("agent-b")).respond({ hasNewer: false });
+  const resumed = await world.nextFetch("agent-a");
+  expect(resumed.request).toMatchObject({
+    direction: "after",
+    cursor: { epoch: "epoch-agent-a", seq: 10 },
+  });
+  resumed.respond({ hasNewer: false });
   await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
 });
 
-test("redeclaring unchanged visibility does not bypass membership backoff", async () => {
+test("a fetch that finishes after membership failure cannot clear the error", async () => {
+  const world = new TimelineWorld();
+  world.sync.setConnected(true);
+  world.show("workspace", ["agent-a"]);
+  (await world.nextMembership()).succeed();
+  const inFlight = await world.nextFetch("agent-a");
+  world.show("workspace", ["agent-b"]);
+  (await world.nextMembership()).fail("subscription unavailable");
+  await world.nextError();
+  inFlight.respond({ hasNewer: false });
+  await Promise.resolve();
+  await Promise.resolve();
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("error");
+});
+
+test("a failed membership retry returns to error", async () => {
+  const world = new TimelineWorld();
+  world.sync.setConnected(true);
+  world.show("workspace", ["agent-a"]);
+  (await world.nextMembership()).fail("unavailable");
+  await world.nextError();
+  world.sync.retryVisibleAgentTimeline("agent-a");
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("retrying");
+  (await world.nextMembership()).fail("still unavailable");
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("error"));
+});
+
+test("redeclaring unchanged visibility does not bypass membership error", async () => {
   const world = new TimelineWorld();
   world.sync.setConnected(true);
   world.sync.replaceVisibleAgentIds("workspace", ["agent-a"]);
 
   const failed = await world.nextMembership();
   failed.fail("subscription unavailable");
-  await world.nextRetry();
+  await world.nextError();
 
   world.sync.replaceVisibleAgentIds("workspace", ["agent-a"]);
+  world.sync.setActive(false);
+  world.sync.setActive(true);
 
   world.expectNoPendingMembership();
   world.expectNoPendingFetch();
@@ -1033,7 +1062,6 @@ test("backgrounding preserves subscriptions and returning verifies the visible c
 
   world.sync.setActive(false);
   world.expectNoPendingMembership();
-  world.elapse(60_000);
   world.sync.setActive(true);
 
   world.expectNoPendingMembership();
@@ -1050,11 +1078,10 @@ test("stale membership retry cannot overwrite a newer effective set", async () =
   world.show("workspace", ["agent-a"]);
   const failed = await world.nextMembership();
   failed.fail("subscription unavailable");
-  const staleRetry = await world.nextRetry();
+  await world.nextError();
 
   world.show("workspace", ["agent-b"]);
   const current = await world.nextMembership();
-  staleRetry();
   current.succeed();
   const agentB = await world.nextFetch("agent-b");
   agentB.respond({ hasNewer: false });
@@ -1071,10 +1098,9 @@ test("membership retry cannot run while disconnected", async () => {
   world.sync.replaceVisibleAgentIds("workspace", ["agent-a"]);
   const failed = await world.nextMembership();
   failed.fail("subscription unavailable");
-  const disconnectedRetry = await world.nextRetry();
+  await world.nextError();
 
   world.sync.setConnected(false);
-  disconnectedRetry();
   world.expectNoPendingMembership();
   world.sync.setConnected(true);
   const restored = await world.nextMembership();
@@ -1101,7 +1127,6 @@ test("returning to an open hidden agent stays live after inactivity", async () =
   agentBCatchUp.respond({ hasNewer: false });
   await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-b")).toBe("ready"));
 
-  world.elapse(60_000);
   world.show("workspace", ["agent-a"]);
 
   world.expectNoPendingMembership();
diff --git a/packages/app/src/timeline/viewed-timeline-sync.ts b/packages/app/src/timeline/viewed-timeline-sync.ts
index 5939feabce..0f5369c1c4 100644
--- a/packages/app/src/timeline/viewed-timeline-sync.ts
+++ b/packages/app/src/timeline/viewed-timeline-sync.ts
@@ -21,12 +21,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>;
@@ -109,6 +111,15 @@ class TimelineReplicaOwner implements TimelineReplica {
   async prepare(agentId: string): Promise<void> {
     const existing = this.preparations.get(agentId);
     if (existing) return existing;
+    const timeline = selectAgentTimelineState(
+      useSessionStore.getState().sessions[this.serverId],
+      agentId,
+    );
+    // A route and the visible-chat owner can both prepare before catch-up finishes.
+    // Repainting that same cache would treat its history as a live head.
+    if (timeline.status !== "cold" && this.cachedRanges.has(agentId)) {
+      return;
+    }
     const preparation = this.load(agentId).finally(() => {
       if (this.preparations.get(agentId) === preparation) {
         this.preparations.delete(agentId);
@@ -320,7 +331,6 @@ export interface ViewedTimelineSyncPorts {
    */
   onCatchUpEnded(agentId: string): void;
   reportError(error: unknown): void;
-  schedule(task: () => void, delayMs: number): () => void;
 }
 
 export type ViewedTimelineStatus = "ready" | "pending" | "error" | "retrying";
@@ -353,7 +363,12 @@ export type ViewedTimelineOwnerPorts = Omit<
 
 export interface ViewedTimelineOwner extends ViewedTimelineSync {
   applyTimelineResponse(payload: TimelineResponsePayload): void;
-  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;
 }
 
@@ -362,6 +377,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>();
@@ -401,8 +417,12 @@ export function createViewedTimelineOwner(input: {
       });
       if (accepted) input.replica.timelineUpdated(payload.agentId);
     },
-    enqueueStreamEvent(agentId, event) {
+    applyStreamEvent(agentId, event) {
       streamQueue.enqueue(agentId, event);
+      const turnLiveness = deriveAgentStreamTurnLiveness([event]);
+      if (turnLiveness.length === 0) return;
+      streamQueue.flushAgent(agentId);
+      input.applyTurnLiveness(agentId, turnLiveness);
     },
     flushStreamAgent(agentId) {
       streamQueue.flushAgent(agentId);
@@ -414,26 +434,14 @@ export function createViewedTimelineOwner(input: {
   };
 }
 
-const RETRY_DELAY_MS = 1_000;
-const MAX_RETRY_DELAY_MS = 30_000;
-
 type CatchUpStatus = "running" | "complete" | "error";
 
 interface CatchUpState {
   generation: number;
   status: CatchUpStatus;
   request?: ProjectedTimelineForwardFetchPlan;
-  cancelRetry?: () => void;
-  retryDelayMs?: number;
 }
 
-const getNextRetryDelayMs = (previousDelayMs: number | undefined): number => {
-  if (previousDelayMs == null) {
-    return RETRY_DELAY_MS;
-  }
-  return Math.min(previousDelayMs * 2, MAX_RETRY_DELAY_MS);
-};
-
 function isSameCatchUpRequest(
   left: ProjectedTimelineForwardFetchPlan | undefined,
   right: ProjectedTimelineForwardFetchPlan | undefined,
@@ -463,9 +471,7 @@ function decideCatchUp(input: {
     }
     return "replace";
   }
-  return input.current.status === "running" || input.current.status === "complete"
-    ? "keep"
-    : "replace";
+  return "keep";
 }
 
 function normalizeAgentIds(agentIds: string[]): string[] {
@@ -485,8 +491,7 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
   const pendingCatchUps = new Map<string, ProjectedTimelineForwardFetchPlan>();
   const visibilityCatchUpPending = new Set<string>();
   const visibilityCatchUpErrors = new Map<string, string>();
-  // User-initiated retries only. Background retries stay silent; a retry the user asked for
-  // owes them a pending state until it settles.
+  // A user-initiated retry owes a pending state until it settles.
   const manualRetries = new Set<string>();
   const loadedCache = new Set<string>();
   const cacheLoads = new Map<string, Promise<void>>();
@@ -502,8 +507,6 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
   let acknowledged: string[] = [];
   let membershipGeneration = 0;
   let membershipNeedsRetry = false;
-  let membershipRetryDelayMs: number | undefined;
-  let cancelMembershipRetry: (() => void) | null = null;
   // 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;
@@ -554,7 +557,6 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
 
   const cancelCatchUp = (agentId: string) => {
     catchUpGenerations.set(agentId, (catchUpGenerations.get(agentId) ?? 0) + 1);
-    catchUps.get(agentId)?.cancelRetry?.();
     catchUps.delete(agentId);
     pendingCatchUps.delete(agentId);
   };
@@ -598,19 +600,7 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
       setVisibilityCatchUpReady(agentId);
     } catch (error) {
       if (catchUps.get(agentId)?.generation === generation) {
-        const nextRetryDelayMs = getNextRetryDelayMs(catchUps.get(agentId)?.retryDelayMs);
-        const cancelRetry = ports.schedule(() => {
-          const current = catchUps.get(agentId);
-          if (current?.generation !== generation || current.status !== "error") return;
-          startCatchUp(agentId);
-        }, nextRetryDelayMs);
-        catchUps.set(agentId, {
-          generation,
-          status: "error",
-          request,
-          cancelRetry,
-          retryDelayMs: nextRetryDelayMs,
-        });
+        catchUps.set(agentId, { generation, status: "error", request });
         setVisibilityCatchUpError([agentId], error);
         ports.reportError(error);
       }
@@ -677,17 +667,9 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     if (decision === "keep") {
       return;
     }
-    current?.cancelRetry?.();
     const generation = (catchUpGenerations.get(agentId) ?? 0) + 1;
     catchUpGenerations.set(agentId, generation);
-    const retryDelayMs =
-      supersede || current?.status !== "error" ? undefined : current.retryDelayMs;
-    catchUps.set(agentId, {
-      generation,
-      status: "running",
-      request: nextRequest,
-      retryDelayMs,
-    });
+    catchUps.set(agentId, { generation, status: "running", request: nextRequest });
     pendingCatchUps.delete(agentId);
     void fetchUntilCurrent(
       agentId,
@@ -706,7 +688,7 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     for (const agentId of ordered) {
       const pendingCatchUp = pendingCatchUps.get(agentId);
       const current = catchUps.get(agentId);
-      // Completion of a different chat must not bypass a failed chat's backoff or
+      // Completion of a different chat must not bypass a failed chat's error or
       // supersede an in-flight tail that owns its parked gap recovery.
       if (current && !(current.status === "complete" && pendingCatchUp)) continue;
       startCatchUp(agentId, {
@@ -732,42 +714,31 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     } catch (error) {
       if (disposed || !connected || generation !== membershipGeneration) return;
       membershipNeedsRetry = true;
+      acknowledged = [];
+      for (const agentId of requested) cancelCatchUp(agentId);
       setVisibilityCatchUpError(requested, error);
-      cancelMembershipRetry?.();
-      const nextRetryDelayMs = getNextRetryDelayMs(membershipRetryDelayMs);
-      cancelMembershipRetry = ports.schedule(() => {
-        cancelMembershipRetry = null;
-        if (disposed || !connected || membershipGeneration !== generation) return;
-        void reconcileMembership();
-      }, nextRetryDelayMs);
-      membershipRetryDelayMs = nextRetryDelayMs;
       ports.reportError(error);
       return;
     }
     if (disposed || !connected || generation !== membershipGeneration) return;
-    cancelMembershipRetry?.();
-    cancelMembershipRetry = null;
-    membershipRetryDelayMs = undefined;
     acknowledged = requested;
     startAcknowledgedCatchUps();
   };
 
   const retryVisibleAgentTimeline = (agentId: string) => {
-    if (!isDesired(agentId) || manualRetries.has(agentId)) return;
+    if (!connected || !isDesired(agentId) || manualRetries.has(agentId)) return;
     const catchUp = catchUps.get(agentId);
     const membershipRetryable = membershipNeedsRetry && connected;
     if (catchUp?.status !== "error" && !membershipRetryable) return;
     manualRetries.add(agentId);
     notifyListeners();
-    if (catchUp?.status === "error") {
-      catchUp.cancelRetry?.();
-      startCatchUp(agentId, { request: catchUp.request, supersede: true });
+    if (membershipRetryable) {
+      void reconcileMembership();
       return;
     }
-    cancelMembershipRetry?.();
-    cancelMembershipRetry = null;
-    membershipRetryDelayMs = undefined;
-    void reconcileMembership();
+    if (catchUp?.status === "error") {
+      startCatchUp(agentId, { request: catchUp.request, supersede: true });
+    }
   };
 
   const commitDesiredMembership = (
@@ -808,8 +779,6 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
         ensureCacheLoaded(agentId);
       }
     }
-    cancelMembershipRetry?.();
-    cancelMembershipRetry = null;
     desired = nextDesired;
     ports.replaceDemandedAgentIds(desired);
     membershipGeneration += 1;
@@ -860,6 +829,7 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
         return;
       }
       for (const agentId of visibleAgentIds()) {
+        if (visibilityCatchUpErrors.has(agentId)) continue;
         visibilityCatchUpPending.add(agentId);
         visibilityCatchUpErrors.delete(agentId);
         startCatchUp(agentId, { supersede: true });
@@ -871,9 +841,6 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
       connected = nextConnected;
       if (!connected) {
         commitDesiredMembership(desired, { resetCatchUpStatus: true });
-        cancelMembershipRetry?.();
-        cancelMembershipRetry = null;
-        membershipRetryDelayMs = undefined;
         void observation?.handle.release().catch(ports.reportError);
         observation = null;
         acknowledged = [];
@@ -885,7 +852,7 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
       void reconcileMembership();
     },
     recoverGap(agentId, cursor) {
-      if (!isDesired(agentId)) return;
+      if (!isDesired(agentId) || catchUps.get(agentId)?.status === "error") return;
       startCatchUp(agentId, {
         request: planTimelineCatchUpAfter({ epoch: cursor.epoch, seq: cursor.endSeq }),
         supersede: true,
@@ -895,10 +862,7 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
       disposed = true;
       void observation?.handle.release().catch(ports.reportError);
       observation = null;
-      cancelMembershipRetry?.();
-      cancelMembershipRetry = null;
       membershipNeedsRetry = false;
-      membershipRetryDelayMs = undefined;
       sources.clear();
       membershipGeneration += 1;
       for (const agentId of desired) cancelCatchUp(agentId);
diff --git a/packages/app/src/tool-calls/detail-level/grouping.ts b/packages/app/src/tool-calls/detail-level/grouping.ts
index 079158b2d9..aeb0d2ed32 100644
--- a/packages/app/src/tool-calls/detail-level/grouping.ts
+++ b/packages/app/src/tool-calls/detail-level/grouping.ts
@@ -1,5 +1,6 @@
+import { isTurnTrigger, isTurnBoundary } from "@/agent-stream/turn-membership";
 import type { ToolCallDetail } from "@getpaseo/protocol/agent-types";
-import type { StreamItem, ToolCallItem } from "@/types/stream";
+import type { StreamItem, ToolCallItem, ThoughtItem } from "@/types/stream";
 
 export interface ToolCallDescriptor {
   detail: ToolCallDetail;
@@ -9,17 +10,19 @@ export interface ToolCallDescriptor {
   metadata?: Record<string, unknown>;
 }
 
+export type GroupableItem = ToolCallItem | ThoughtItem;
+
 export interface ToolCallRun {
   id: string;
-  calls: readonly ToolCallItem[];
-  latest: ToolCallItem;
+  calls: readonly GroupableItem[];
+  latest: GroupableItem;
   isSealed: boolean;
 }
 
 export interface GroupedHistory<TGroup> {
   tail: StreamItem[];
   groupsByHostId: Map<string, TGroup>;
-  pendingCalls: readonly ToolCallItem[];
+  pendingCalls: readonly GroupableItem[];
 }
 
 export interface GroupedToolCalls<TGroup> {
@@ -62,15 +65,19 @@ export function describeToolCall(item: ToolCallItem): ToolCallDescriptor {
   };
 }
 
-export function isGroupableToolCall(item: StreamItem): item is ToolCallItem {
-  if (item.kind !== "tool_call") {
+export function isGroupableToolCall(
+  item: StreamItem,
+  autoExpandReasoning = false,
+): item is GroupableItem {
+  if (item.kind === "thought") return !autoExpandReasoning;
+  if (item.kind !== "tool_call" || isTurnTrigger(item)) {
     return false;
   }
   const descriptor = describeToolCall(item);
   return descriptor.detail.type !== "plan" && descriptor.name.trim().toLowerCase() !== "speak";
 }
 
-function createRun(calls: readonly ToolCallItem[], isSealed: boolean): ToolCallRun {
+function createRun(calls: readonly GroupableItem[], isSealed: boolean): ToolCallRun {
   const first = calls[0];
   const latest = calls.at(-1);
   if (!first || !latest) {
@@ -79,20 +86,21 @@ function createRun(calls: readonly ToolCallItem[], isSealed: boolean): ToolCallR
   return { id: first.id, calls, latest, isSealed };
 }
 
-function createHost(run: ToolCallRun): ToolCallItem {
+function createHost(run: ToolCallRun): GroupableItem {
   if (run.calls.length === 1) {
     return run.latest;
   }
   return { ...run.latest, id: run.id };
 }
 
-function isRunning(call: ToolCallItem): boolean {
+function isRunning(call: GroupableItem): boolean {
+  if (call.kind === "thought") return call.status !== "ready";
   const status = describeToolCall(call).status;
   return status === "running" || status === "executing";
 }
 
 function appendRun<TGroup>(input: {
-  calls: readonly ToolCallItem[];
+  calls: readonly GroupableItem[];
   isSealed: boolean;
   output: StreamItem[];
   groups: Map<string, TGroup>;
@@ -104,19 +112,23 @@ function appendRun<TGroup>(input: {
   const run = createRun(input.calls, input.isSealed);
   const host = createHost(run);
   input.output.push(host);
-  input.groups.set(host.id, input.buildGroup(run));
+  if (run.calls.length > 1) input.groups.set(host.id, input.buildGroup(run));
 }
 
 export function prepareGroupedHistory<TGroup>(input: {
   tail: StreamItem[];
   buildGroup: (run: ToolCallRun) => TGroup;
+  autoExpandReasoning?: boolean;
 }): GroupedHistory<TGroup> {
   const output: StreamItem[] = [];
   const groups = new Map<string, TGroup>();
-  let pending: ToolCallItem[] = [];
+  let pending: GroupableItem[] = [];
 
   for (const item of input.tail) {
-    if (isGroupableToolCall(item)) {
+    if (
+      isGroupableToolCall(item, input.autoExpandReasoning) &&
+      !isTurnBoundary(pending.at(-1) ?? null, item)
+    ) {
       pending.push(item);
       continue;
     }
@@ -128,7 +140,8 @@ export function prepareGroupedHistory<TGroup>(input: {
       buildGroup: input.buildGroup,
     });
     pending = [];
-    output.push(item);
+    if (isGroupableToolCall(item, input.autoExpandReasoning)) pending.push(item);
+    else output.push(item);
   }
 
   appendRun({
@@ -151,6 +164,7 @@ export function groupLiveToolCalls<TGroup>(input: {
   head: StreamItem[];
   isTurnActive: boolean;
   buildGroup: (run: ToolCallRun) => TGroup;
+  autoExpandReasoning?: boolean;
 }): GroupedToolCalls<TGroup> {
   const head: StreamItem[] = [];
   const liveGroups = new Map<string, TGroup>();
@@ -166,7 +180,8 @@ export function groupLiveToolCalls<TGroup>(input: {
     if (hostPlacement === "head") {
       head.push(createHost(run));
     }
-    if (hostPlacement === "head" || pendingIncludesHead || !isSealed) {
+    const needsLiveGroup = hostPlacement === "head" || pendingIncludesHead || !isSealed;
+    if (run.calls.length > 1 && needsLiveGroup) {
       liveGroups.set(run.id, input.buildGroup(run));
     }
     pending = [];
@@ -175,7 +190,8 @@ export function groupLiveToolCalls<TGroup>(input: {
   };
 
   for (const item of input.head) {
-    if (isGroupableToolCall(item)) {
+    if (isTurnBoundary(pending.at(-1) ?? null, item)) flush(true);
+    if (isGroupableToolCall(item, input.autoExpandReasoning)) {
       if (pending.length === 0) {
         hostPlacement = "head";
       }
@@ -202,19 +218,13 @@ export function groupLiveToolCalls<TGroup>(input: {
       historyGroupUpdatesByHostId: EMPTY_GROUPS,
     };
   }
-  if (input.history.groupsByHostId.size === 0) {
-    return {
-      tail: input.history.tail,
-      head,
-      groupsByHostId: liveGroups,
-      historyGroupUpdatesByHostId: EMPTY_GROUPS,
-    };
-  }
   const groupsByHostId = new Map(input.history.groupsByHostId);
   let historyGroupUpdatesByHostId: Map<string, TGroup> | null = null;
   for (const [id, group] of liveGroups) {
     groupsByHostId.set(id, group);
-    if (input.history.groupsByHostId.has(id)) {
+    const isHistoryHost =
+      input.history.groupsByHostId.has(id) || input.history.pendingCalls[0]?.id === id;
+    if (isHistoryHost) {
       historyGroupUpdatesByHostId ??= new Map();
       historyGroupUpdatesByHostId.set(id, group);
     }
diff --git a/packages/app/src/tool-calls/detail-level/overview/label.ts b/packages/app/src/tool-calls/detail-level/overview/label.ts
index 762e530172..605e9ce211 100644
--- a/packages/app/src/tool-calls/detail-level/overview/label.ts
+++ b/packages/app/src/tool-calls/detail-level/overview/label.ts
@@ -33,13 +33,20 @@ export function useOverviewSummaryLabel(
       [summary.readFileCount, "toolCallGroup.readFiles"],
       [summary.searchCount, "toolCallGroup.searches"],
       [summary.otherToolCount, "toolCallGroup.otherTools"],
-      [summary.paseoCallCount, "toolCallGroup.paseoCalls"],
     ] as const;
     for (const [count, key] of entries) {
       if (count > 0) {
         parts.push(t(`${key}.${count === 1 ? "one" : "other"}`, { count }));
       }
     }
+    for (const [action, count] of Object.entries(summary.paseoActions)) {
+      parts.push(
+        count === 1 ? action.toLocaleLowerCase() : `${action.toLocaleLowerCase()} ×${count}`,
+      );
+    }
+    // Reasoning stays in the details; it is not an action in a work summary.
+    // Keep a label for a group containing only reasoning.
+    if (parts.length === 0 && summary.thoughtCount > 0) return t("toolCallGroup.thought");
     return joinSummaryParts(parts, t("toolCallGroup.and"));
   }, [leadingParts, summary, t]);
 }
diff --git a/packages/app/src/tool-calls/detail-level/overview/model.ts b/packages/app/src/tool-calls/detail-level/overview/model.ts
index 0fb638c012..e4717c43bf 100644
--- a/packages/app/src/tool-calls/detail-level/overview/model.ts
+++ b/packages/app/src/tool-calls/detail-level/overview/model.ts
@@ -1,17 +1,18 @@
-import { isPaseoToolName } from "@getpaseo/protocol/tool-name-normalization";
-import type { ToolCallItem } from "@/types/stream";
-import { describeToolCall, type ToolCallRun } from "../grouping";
+import { getPaseoToolActionLabel } from "@getpaseo/protocol/paseo-tool-presentation/index";
+import { isTurnTrigger } from "@/agent-stream/turn-membership";
+
+import { describeToolCall, type GroupableItem, type ToolCallRun } from "../grouping";
 
-const DIRECT_PASEO_TOOL_PREFIX = "paseo_";
 const DIRECT_SEARCH_TOOL_SUFFIX_PATTERN = /(?:^|[_.:/])(?:web_search|llm_context)$/;
 
 export interface OverviewSummary {
+  thoughtCount: number;
   editedFileCount: number;
   commandCount: number;
   readFileCount: number;
   searchCount: number;
   otherToolCount: number;
-  paseoCallCount: number;
+  paseoActions: Record<string, number>;
 }
 
 export interface OverviewToolCallGroup {
@@ -21,28 +22,31 @@ export interface OverviewToolCallGroup {
   isLoading: boolean;
 }
 
-function isPaseoCall(name: string, normalizedName: string): boolean {
-  return isPaseoToolName(name) || normalizedName.startsWith(DIRECT_PASEO_TOOL_PREFIX);
-}
-
 function isSearchCall(name: string): boolean {
   return DIRECT_SEARCH_TOOL_SUFFIX_PATTERN.test(name);
 }
 
 /** Counts tool calls by what they did, for any summary of a stretch of agent work. */
-export function summarizeToolCalls(calls: readonly ToolCallItem[]): OverviewSummary {
+export function summarizeToolCalls(calls: readonly GroupableItem[]): OverviewSummary {
   const editedFiles = new Set<string>();
   const readFiles = new Set<string>();
+  let thoughtCount = 0;
   let commandCount = 0;
   let searchCount = 0;
   let otherToolCount = 0;
-  let paseoCallCount = 0;
+  const paseoActions: Record<string, number> = {};
 
   for (const call of calls) {
+    if (call.kind === "thought") {
+      thoughtCount += 1;
+      continue;
+    }
+    if (isTurnTrigger(call)) continue;
     const descriptor = describeToolCall(call);
     const normalizedName = descriptor.name.trim().toLowerCase();
-    if (isPaseoCall(descriptor.name, normalizedName)) {
-      paseoCallCount += 1;
+    const action = getPaseoToolActionLabel(descriptor.name);
+    if (action) {
+      paseoActions[action] = (paseoActions[action] ?? 0) + 1;
     } else if (descriptor.detail.type === "edit" || descriptor.detail.type === "write") {
       editedFiles.add(descriptor.detail.filePath);
     } else if (descriptor.detail.type === "shell") {
@@ -57,17 +61,19 @@ export function summarizeToolCalls(calls: readonly ToolCallItem[]): OverviewSumm
   }
 
   return {
+    thoughtCount,
     editedFileCount: editedFiles.size,
     commandCount,
     readFileCount: readFiles.size,
     searchCount,
     otherToolCount,
-    paseoCallCount,
+    paseoActions,
   };
 }
 
 export function buildOverviewGroup(run: ToolCallRun): OverviewToolCallGroup {
   const isLoading = run.calls.some((call) => {
+    if (call.kind === "thought") return call.status !== "ready";
     const status = describeToolCall(call).status;
     return status === "running" || status === "executing";
   });
diff --git a/packages/app/src/tool-calls/detail-level/overview/sheet.tsx b/packages/app/src/tool-calls/detail-level/overview/sheet.tsx
index b3b5bf39eb..2888f1f424 100644
--- a/packages/app/src/tool-calls/detail-level/overview/sheet.tsx
+++ b/packages/app/src/tool-calls/detail-level/overview/sheet.tsx
@@ -4,8 +4,12 @@ import { BottomSheetScrollView, type BottomSheetScrollViewMethods } from "@gorho
 import { Wrench, X } from "lucide-react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useTranslation } from "react-i18next";
-import { useIsolatedBottomSheetVisibility } from "@/components/ui/isolated-bottom-sheet-modal";
+import {
+  type ContextBridge,
+  useIsolatedBottomSheetVisibility,
+} from "@/components/ui/isolated-bottom-sheet-modal";
 import { ToolCallSheetModal, useToolCallSheetContextBridge } from "@/components/tool-call-sheet";
+import { useToolCallExpansionContextBridge } from "@/tool-calls/expansion-context";
 import type { Theme } from "@/styles/theme";
 
 interface OverviewToolCallGroupSheetProps {
@@ -29,7 +33,12 @@ export function OverviewToolCallGroupSheet({
 }: OverviewToolCallGroupSheetProps) {
   const { t } = useTranslation();
   const scrollRef = useRef<BottomSheetScrollViewMethods>(null);
-  const contextBridge = useToolCallSheetContextBridge();
+  const sheetContextBridge = useToolCallSheetContextBridge();
+  const expansionContextBridge = useToolCallExpansionContextBridge();
+  const contextBridge = useCallback<ContextBridge>(
+    (content) => sheetContextBridge(expansionContextBridge(content)),
+    [expansionContextBridge, sheetContextBridge],
+  );
   const { sheetRef, handleSheetChange, handleSheetDismiss } = useIsolatedBottomSheetVisibility({
     visible,
     onClose,
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/detail-level/projection.test.ts b/packages/app/src/tool-calls/detail-level/projection.test.ts
index dabf87b73d..5c4b4a900b 100644
--- a/packages/app/src/tool-calls/detail-level/projection.test.ts
+++ b/packages/app/src/tool-calls/detail-level/projection.test.ts
@@ -110,11 +110,7 @@ describe("tool call detail-level projection", () => {
       preparedHistory: prepared,
     });
     expect(single.head).toEqual([firstCall]);
-    expect(single.groupsByHostId.get(firstCall.id)?.run).toMatchObject({
-      calls: [firstCall],
-      latest: firstCall,
-      isSealed: false,
-    });
+    expect(single.groupsByHostId.size).toBe(0);
 
     const grouped = project({
       level: "overview",
@@ -142,18 +138,11 @@ describe("tool call detail-level projection", () => {
     expect(result.groupsByHostId.get("1")?.isLoading).toBe(true);
   });
 
-  it("builds a loading aggregate for a one-call run", () => {
+  it("leaves a running lone call visible without an aggregate", () => {
     const call = toolCall("1", { type: "shell", command: "one" }, { status: "running" });
     const result = project({ level: "overview", head: [call], isTurnActive: true });
-    const group = result.groupsByHostId.get(call.id);
-    if (!group) {
-      throw new Error("Expected an overview group");
-    }
-
-    expect(group).toMatchObject({
-      isLoading: true,
-      summary: { commandCount: 1 },
-    });
+    expect(result.head).toEqual([call]);
+    expect(result.groupsByHostId.size).toBe(0);
   });
 
   it("keeps an active overview group on its latest call until a visible boundary arrives", () => {
@@ -255,12 +244,13 @@ describe("tool call detail-level projection", () => {
       run: expect.any(Object),
       isLoading: false,
       summary: {
+        thoughtCount: 0,
         editedFileCount: 1,
         commandCount: 1,
         readFileCount: 2,
         searchCount: 0,
         otherToolCount: 0,
-        paseoCallCount: 0,
+        paseoActions: {},
       },
     });
   });
@@ -328,7 +318,7 @@ describe("tool call detail-level projection", () => {
     const result = project({ level: "overview", head: calls });
 
     expect(result.groupsByHostId.get("1")).toMatchObject({
-      summary: { otherToolCount: 2, paseoCallCount: 2 },
+      summary: { otherToolCount: 2, paseoActions: { "Listed agents": 1, "List worktrees": 1 } },
     });
   });
 
@@ -346,7 +336,11 @@ describe("tool call detail-level projection", () => {
     const result = project({ level: "overview", head: calls });
 
     expect(result.groupsByHostId.get("1")).toMatchObject({
-      summary: { searchCount: 3, otherToolCount: 0, paseoCallCount: 3 },
+      summary: {
+        searchCount: 3,
+        otherToolCount: 0,
+        paseoActions: { "Listed providers": 1, "List worktrees": 2 },
+      },
     });
   });
 
@@ -476,7 +470,105 @@ describe("tool call detail-level projection", () => {
     const result = project({ level: "overview", head: [singleCall, plan, speak] });
 
     expect(result.head).toEqual([singleCall, plan, speak]);
-    expect(result.groupsByHostId.get(singleCall.id)?.run.calls).toEqual([singleCall]);
-    expect(result.groupsByHostId.size).toBe(1);
+    expect(result.groupsByHostId.size).toBe(0);
   });
 });
+
+it("keeps a heartbeat trigger visible outside grouped work", () => {
+  const trigger = toolCall(
+    "1",
+    { type: "plain_text", text: "Check progress" },
+    { name: "heartbeat" },
+  );
+  const work = toolCall("2", { type: "shell", command: "pwd" });
+  const result = project({ level: "overview", tail: [trigger, work] });
+  expect(result.tail.map((item) => item.id)).toEqual(["1", "2"]);
+  expect(result.groupsByHostId.has("1")).toBe(false);
+});
+
+it("does not merge tools from different canonical turns", () => {
+  const first = toolCall("1", { type: "shell", command: "pwd" });
+  first.turnId = "first";
+  const second = toolCall("2", { type: "shell", command: "ls" });
+  second.turnId = "second";
+  const result = project({ level: "overview", tail: [first, second] });
+  expect(result.tail.map((item) => item.id)).toEqual(["1", "2"]);
+});
+
+it.each([false, true])(
+  "handles streaming reasoning across retained history (Expand thinking %s)",
+  (autoExpandReasoning) => {
+    const call = { ...toolCall("1", { type: "shell", command: "echo ok" }), turnId: "run" };
+    const thought: StreamItem = {
+      kind: "thought",
+      id: "reasoning",
+      text: "Checking",
+      status: "loading",
+      timestamp: new Date(),
+      turnId: "run",
+    };
+    const tail = [call];
+    const result = project({
+      level: "overview",
+      tail,
+      head: [thought],
+      isTurnActive: true,
+      preparedHistory: prepareToolCallHistory("overview", tail, autoExpandReasoning),
+    });
+    expect(result.head).toEqual(autoExpandReasoning ? [thought] : []);
+    expect(result.groupsByHostId.get(call.id)?.run.calls).toEqual(
+      autoExpandReasoning ? undefined : [call, thought],
+    );
+    expect(result.groupsByHostId.get(call.id)?.summary).toEqual(
+      autoExpandReasoning
+        ? undefined
+        : expect.objectContaining({
+            commandCount: 1,
+            otherToolCount: 0,
+            thoughtCount: 1,
+          }),
+    );
+  },
+);
+
+it("turns a retained lone call into a group without replacing its row key", () => {
+  const first = toolCall("1", { type: "shell", command: "one" });
+  const second = toolCall("2", { type: "shell", command: "two" });
+  const tail = [assistant("before"), first];
+  const preparedHistory = prepareToolCallHistory("overview", tail);
+  const single = project({ level: "overview", tail, preparedHistory, isTurnActive: true });
+  const grouped = project({
+    level: "overview",
+    tail,
+    head: [second],
+    preparedHistory,
+    isTurnActive: true,
+  });
+  expect(single.groupsByHostId.size).toBe(0);
+  expect(single.tail).toBe(tail);
+  expect(grouped.tail).toBe(single.tail);
+  expect(grouped.head).toEqual([]);
+  expect(grouped.groupsByHostId.get(first.id)?.run.calls).toEqual([first, second]);
+  expect(grouped.historyGroupUpdatesByHostId.get(first.id)).toBe(
+    grouped.groupsByHostId.get(first.id),
+  );
+});
+
+it("shows one thought as itself until another groupable item arrives", () => {
+  const thought: StreamItem = {
+    kind: "thought",
+    id: "thought",
+    text: "Checking",
+    status: "ready",
+    timestamp: new Date(0),
+  };
+  const single = project({ level: "overview", tail: [thought] });
+  expect(single.tail).toEqual([thought]);
+  expect(single.groupsByHostId.size).toBe(0);
+  const grouped = project({
+    level: "overview",
+    tail: [thought, toolCall("1", { type: "shell", command: "one" })],
+  });
+  expect(grouped.tail.map((item) => item.id)).toEqual([thought.id]);
+  expect(grouped.groupsByHostId.get(thought.id)?.run.calls).toHaveLength(2);
+});
diff --git a/packages/app/src/tool-calls/detail-level/projection.ts b/packages/app/src/tool-calls/detail-level/projection.ts
index 9d57391b2e..3f10855ce5 100644
--- a/packages/app/src/tool-calls/detail-level/projection.ts
+++ b/packages/app/src/tool-calls/detail-level/projection.ts
@@ -13,6 +13,7 @@ export type ToolCallDetailGroup = OverviewToolCallGroup;
 
 export interface PreparedToolCallHistory {
   mode: "overview";
+  autoExpandReasoning: boolean;
   grouped: GroupedHistory<ToolCallDetailGroup>;
 }
 
@@ -41,15 +42,18 @@ function visibleToolCallItems(items: StreamItem[]): StreamItem[] {
 export function prepareToolCallHistory(
   level: ToolCallDetailLevel,
   tail: StreamItem[],
+  autoExpandReasoning = false,
 ): PreparedToolCallHistory | null {
   if (level === "detailed") {
     return null;
   }
   return {
     mode: "overview",
+    autoExpandReasoning,
     grouped: prepareGroupedHistory({
       tail: visibleToolCallItems(tail),
       buildGroup: buildOverviewGroup,
+      autoExpandReasoning,
     }),
   };
 }
@@ -74,6 +78,7 @@ export function projectToolCallDetailLevel(input: {
   }
   return groupLiveToolCalls({
     history: input.preparedHistory.grouped,
+    autoExpandReasoning: input.preparedHistory.autoExpandReasoning,
     head: visibleToolCallItems(input.head),
     isTurnActive: input.isTurnActive,
     buildGroup: buildOverviewGroup,
diff --git a/packages/app/src/tool-calls/expansion-context.tsx b/packages/app/src/tool-calls/expansion-context.tsx
new file mode 100644
index 0000000000..4ac2477247
--- /dev/null
+++ b/packages/app/src/tool-calls/expansion-context.tsx
@@ -0,0 +1,69 @@
+import { createContext, useCallback, useContext, useState, useSyncExternalStore } from "react";
+import type { ContextBridge } from "@/components/ui/isolated-bottom-sheet-modal";
+import {
+  createToolCallExpansion,
+  type ExpandedToolCallGroups,
+  type ToolCallExpansion,
+} from "./expansion";
+
+export const ToolCallExpansionContext = createContext<ToolCallExpansion | null>(null);
+
+/** One store per viewed agent; switching agents starts with every tool call closed. */
+export function useAgentToolCallExpansion(agentId: string): ToolCallExpansion {
+  const [owner, setOwner] = useState(() => ({ agentId, expansion: createToolCallExpansion() }));
+  if (owner.agentId === agentId) return owner.expansion;
+  const next = { agentId, expansion: createToolCallExpansion() };
+  setOwner(next);
+  return next.expansion;
+}
+
+/** Subscribes the timeline to group toggles only; call toggles never reach it. */
+export function useExpandedToolCallGroups(expansion: ToolCallExpansion): ExpandedToolCallGroups {
+  return useSyncExternalStore(
+    expansion.subscribeGroups,
+    expansion.getExpandedGroups,
+    expansion.getExpandedGroups,
+  );
+}
+
+function useToolCallExpansion(): ToolCallExpansion {
+  const expansion = useContext(ToolCallExpansionContext);
+  if (!expansion) throw new Error("ToolCall requires a ToolCallExpansionContext");
+  return expansion;
+}
+
+/** Carries tool call open state into sheets that render their content in a portal. */
+export function useToolCallExpansionContextBridge(): ContextBridge {
+  const expansion = useToolCallExpansion();
+  return useCallback(
+    (children) => (
+      <ToolCallExpansionContext.Provider value={expansion}>
+        {children}
+      </ToolCallExpansionContext.Provider>
+    ),
+    [expansion],
+  );
+}
+
+/** Subscribes one tool call to its own open state. */
+export function useToolCallExpanded(input: {
+  callId: string;
+  defaultExpanded: boolean;
+  standalone: boolean;
+}) {
+  const expansion = useToolCallExpansion();
+  const { callId, defaultExpanded, standalone } = input;
+  const subscribe = useCallback(
+    (listener: () => void) => expansion.subscribeCall(callId, listener),
+    [expansion, callId],
+  );
+  const getSnapshot = useCallback(
+    () => expansion.isCallExpanded(callId, defaultExpanded),
+    [expansion, callId, defaultExpanded],
+  );
+  const expanded = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const toggle = useCallback(() => {
+    expansion.setCallExpanded({ callId, expanded: !expanded, standalone });
+  }, [expansion, callId, expanded, standalone]);
+  return { expanded, toggle };
+}
diff --git a/packages/app/src/tool-calls/expansion.test.ts b/packages/app/src/tool-calls/expansion.test.ts
new file mode 100644
index 0000000000..875d3c6078
--- /dev/null
+++ b/packages/app/src/tool-calls/expansion.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { createToolCallExpansion } from "./expansion";
+
+function observe(expansion: ReturnType<typeof createToolCallExpansion>) {
+  const notified: string[] = [];
+  expansion.subscribeCall("first", () => notified.push("first"));
+  expansion.subscribeCall("second", () => notified.push("second"));
+  expansion.subscribeGroups(() => notified.push("timeline"));
+  return notified;
+}
+
+describe("tool call expansion", () => {
+  it("opens a lone call and its future group without notifying the timeline", () => {
+    const expansion = createToolCallExpansion();
+    const notified = observe(expansion);
+    const groupsBefore = expansion.getExpandedGroups();
+
+    expansion.setCallExpanded({ callId: "first", expanded: true, standalone: true });
+
+    expect(notified).toEqual(["first"]);
+    expect(expansion.getExpandedGroups()).toBe(groupsBefore);
+    expect(expansion.isCallExpanded("first", false)).toBe(true);
+    expect(expansion.getExpandedGroups().has("first")).toBe(true);
+  });
+
+  it("closes the lone call and its future group together", () => {
+    const expansion = createToolCallExpansion();
+    const notified = observe(expansion);
+    const groupsBefore = expansion.getExpandedGroups();
+
+    expansion.setCallExpanded({ callId: "first", expanded: true, standalone: true });
+    expansion.setCallExpanded({ callId: "first", expanded: false, standalone: true });
+
+    expect(notified).toEqual(["first", "first"]);
+    expect(expansion.getExpandedGroups()).toBe(groupsBefore);
+    expect(expansion.isCallExpanded("first", false)).toBe(false);
+    expect(expansion.getExpandedGroups().has("first")).toBe(false);
+  });
+
+  it("keeps a call open when its group closes and reopens", () => {
+    const expansion = createToolCallExpansion();
+    const notified = observe(expansion);
+    expansion.setCallExpanded({ callId: "first", expanded: true, standalone: true });
+    const groupsWhenFormed = expansion.getExpandedGroups();
+
+    expansion.setGroupExpanded("first", false);
+    const closedGroups = expansion.getExpandedGroups();
+    expect(closedGroups).not.toBe(groupsWhenFormed);
+    expect(closedGroups.has("first")).toBe(false);
+    expect(expansion.isCallExpanded("first", false)).toBe(true);
+
+    expansion.setGroupExpanded("first", true);
+    expect(expansion.getExpandedGroups()).not.toBe(closedGroups);
+    expect(expansion.getExpandedGroups().has("first")).toBe(true);
+    expect(expansion.isCallExpanded("first", false)).toBe(true);
+    expect(notified).toEqual(["first", "timeline", "timeline"]);
+  });
+
+  it("toggles a call inside a group without touching the group", () => {
+    const expansion = createToolCallExpansion();
+    const notified = observe(expansion);
+    expansion.setGroupExpanded("first", true);
+    const groups = expansion.getExpandedGroups();
+
+    expansion.setCallExpanded({ callId: "first", expanded: true, standalone: false });
+    expansion.setCallExpanded({ callId: "first", expanded: false, standalone: false });
+
+    expect(notified).toEqual(["timeline", "first", "first"]);
+    expect(expansion.getExpandedGroups()).toBe(groups);
+    expect(groups.has("first")).toBe(true);
+  });
+
+  it("uses the call's default until the user toggles it", () => {
+    const expansion = createToolCallExpansion();
+    expect(expansion.isCallExpanded("first", true)).toBe(true);
+    expansion.setCallExpanded({ callId: "first", expanded: false, standalone: true });
+    expect(expansion.isCallExpanded("first", true)).toBe(false);
+  });
+});
diff --git a/packages/app/src/tool-calls/expansion.ts b/packages/app/src/tool-calls/expansion.ts
new file mode 100644
index 0000000000..d11a824ae2
--- /dev/null
+++ b/packages/app/src/tool-calls/expansion.ts
@@ -0,0 +1,67 @@
+type Listener = () => void;
+
+/** Which tool call groups are open. A new value is published only when a group is toggled. */
+export interface ExpandedToolCallGroups {
+  has(groupId: string): boolean;
+}
+
+/**
+ * Open state of one agent's tool calls and tool call groups.
+ *
+ * A group takes its first call's id. Opening a lone call (`standalone`) also opens the group it
+ * will host once a second call arrives, without publishing a group change: the timeline renders
+ * that row again when the group forms and reads the open state then. A call toggle notifies only
+ * that call's subscribers.
+ */
+export function createToolCallExpansion() {
+  const calls = new Map<string, boolean>();
+  const callListeners = new Map<string, Set<Listener>>();
+  const groups = new Set<string>();
+  const groupListeners = new Set<Listener>();
+  let expandedGroups = createExpandedGroups();
+
+  function createExpandedGroups(): ExpandedToolCallGroups {
+    return { has: (groupId) => groups.has(groupId) };
+  }
+
+  function writeGroup(groupId: string, expanded: boolean) {
+    if (expanded) groups.add(groupId);
+    else groups.delete(groupId);
+  }
+
+  return {
+    isCallExpanded: (callId: string, defaultExpanded: boolean) =>
+      calls.get(callId) ?? defaultExpanded,
+    subscribeCall(callId: string, listener: Listener) {
+      let listeners = callListeners.get(callId);
+      if (!listeners) {
+        listeners = new Set();
+        callListeners.set(callId, listeners);
+      }
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) callListeners.delete(callId);
+      };
+    },
+    setCallExpanded(input: { callId: string; expanded: boolean; standalone: boolean }) {
+      calls.set(input.callId, input.expanded);
+      if (input.standalone) writeGroup(input.callId, input.expanded);
+      for (const listener of callListeners.get(input.callId) ?? []) listener();
+    },
+    getExpandedGroups: () => expandedGroups,
+    subscribeGroups(listener: Listener) {
+      groupListeners.add(listener);
+      return () => {
+        groupListeners.delete(listener);
+      };
+    },
+    setGroupExpanded(groupId: string, expanded: boolean) {
+      writeGroup(groupId, expanded);
+      expandedGroups = createExpandedGroups();
+      for (const listener of groupListeners) listener();
+    },
+  };
+}
+
+export type ToolCallExpansion = ReturnType<typeof createToolCallExpansion>;
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.test.ts b/packages/app/src/types/stream.test.ts
index 62e26698db..376d04ea67 100644
--- a/packages/app/src/types/stream.test.ts
+++ b/packages/app/src/types/stream.test.ts
@@ -661,6 +661,82 @@ describe("stream reducer canonical tool calls", () => {
     expect(new Set(tools.map((tool) => tool.id)).size).toBe(2);
   });
 
+  it.each(["live", "canonical"] as const)(
+    "keeps current tool identity during %s updates when an older turn reports late",
+    (source) => {
+      let state: StreamItem[] = [];
+      const events = [
+        { callId: "background", turnId: "codex-turn-17", status: "running" as const },
+        { callId: "exec-current", turnId: "codex-turn-18", status: "running" as const },
+        { callId: "background", turnId: "codex-turn-17", status: "completed" as const },
+        { callId: "exec-current", turnId: "codex-turn-18", status: "completed" as const },
+      ];
+      for (const [index, item] of events.entries()) {
+        state = reduceStreamUpdate(
+          state,
+          canonicalToolTimeline({
+            provider: "codex",
+            name: "exec_command",
+            ...item,
+          }),
+          new Date(index * 1000),
+          { source },
+        );
+      }
+      expect(
+        state.filter(isAgentToolCallItem).map((item) => ({
+          id: item.id,
+          turnId: item.turnId,
+          status: item.payload.data.status,
+        })),
+      ).toEqual([
+        {
+          id: "agent_tool_turn:codex-turn-17/background",
+          turnId: "codex-turn-17",
+          status: "completed",
+        },
+        {
+          id: "agent_tool_turn:codex-turn-18/exec-current",
+          turnId: "codex-turn-18",
+          status: "completed",
+        },
+      ]);
+    },
+  );
+
+  it("does not move reasoning into an older turn when a late tool update finalizes it", () => {
+    const background = canonicalToolTimeline({
+      provider: "codex",
+      name: "exec_command",
+      callId: "background",
+      turnId: "old",
+      status: "running",
+    });
+    let state = reduceStreamUpdate([], background, new Date(0));
+    state = reduceStreamUpdate(
+      state,
+      {
+        type: "timeline",
+        provider: "codex",
+        turnId: "current",
+        item: { type: "reasoning", text: "Working on the current request" },
+      },
+      new Date(1),
+    );
+    state = reduceStreamUpdate(
+      state,
+      canonicalToolTimeline({
+        provider: "codex",
+        name: "exec_command",
+        callId: "background",
+        turnId: "old",
+        status: "completed",
+      }),
+      new Date(2),
+    );
+    expect(state.at(-1)).toMatchObject({ kind: "thought", turnId: "current", status: "ready" });
+  });
+
   it("merges lifecycle updates for the same call occurrence", () => {
     const callId = "tool-updated-within-turn";
     const turnId = "autonomous-turn-1";
diff --git a/packages/app/src/types/stream.ts b/packages/app/src/types/stream.ts
index 657d218b35..623deb0ac5 100644
--- a/packages/app/src/types/stream.ts
+++ b/packages/app/src/types/stream.ts
@@ -91,6 +91,8 @@ export type StreamItem =
 export type UserMessageImageAttachment = AttachmentMetadata;
 
 export interface UserMessageItem {
+  /** Attribution added by presentation for received agent messages. */
+  sender?: AgentMessage["sender"];
   kind: "user_message";
   id: string;
   clientMessageId?: string;
@@ -810,6 +812,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;
@@ -986,6 +990,7 @@ function appendThought(
   text: string,
   timestamp: Date,
   timelineCursor?: TimelinePosition,
+  turnId?: string,
 ): StreamItem[] {
   const { chunk, hasContent } = normalizeChunk(text);
   if (!chunk) {
@@ -993,7 +998,7 @@ function appendThought(
   }
 
   const last = state[state.length - 1];
-  if (last && last.kind === "thought") {
+  if (last && last.kind === "thought" && last.turnId === turnId) {
     const updated: ThoughtItem = {
       ...last,
       ...(timelineCursor ? { timelineCursor } : {}),
@@ -1511,36 +1516,30 @@ function reduceTimelineEvent(
   const item = event.item;
   switch (item.type) {
     case "user_message":
-      return finalizeActiveThoughts(
-        appendUserMessage(
-          state,
-          item.text,
-          timestamp,
-          source,
-          item.messageId,
-          item.clientMessageId,
-          timelineCursor,
-          event.turnId,
-        ),
+      return appendUserMessage(
+        state,
+        item.text,
+        timestamp,
+        source,
+        item.messageId,
+        item.clientMessageId,
+        timelineCursor,
+        event.turnId,
       );
     case "assistant_message":
-      return finalizeActiveThoughts(
-        appendAssistantMessage(
-          state,
-          item.text,
-          timestamp,
-          source,
-          item.messageId,
-          reservedItemIds,
-          timelineCursor,
-        ),
+      return appendAssistantMessage(
+        state,
+        item.text,
+        timestamp,
+        source,
+        item.messageId,
+        reservedItemIds,
+        timelineCursor,
       );
     case "reasoning":
-      return appendThought(state, item.text, timestamp, timelineCursor);
+      return appendThought(state, item.text, timestamp, timelineCursor, event.turnId);
     case "tool_call":
-      return finalizeActiveThoughts(
-        reduceTimelineToolCall(state, event, item, timestamp, timelineCursor),
-      );
+      return reduceTimelineToolCall(state, event, item, timestamp, timelineCursor);
     case "todo": {
       const items: TodoEntry[] = (item.items ?? []).map((todo) => ({
         text: todo.text,
@@ -1549,9 +1548,7 @@ function reduceTimelineEvent(
         status: todo.status,
         activeForm: todo.activeForm,
       }));
-      return finalizeActiveThoughts(
-        appendTodoList(state, event.provider, items, timestamp, timelineCursor),
-      );
+      return appendTodoList(state, event.provider, items, timestamp, timelineCursor);
     }
     case "error": {
       const notification: NotificationItem = {
@@ -1563,7 +1560,7 @@ function reduceTimelineEvent(
         level: "error",
         message: item.message ?? "Unknown error",
       };
-      return finalizeActiveThoughts(appendNotification(state, notification));
+      return appendNotification(state, notification);
     }
     case "notification": {
       const notification: NotificationItem = {
@@ -1575,16 +1572,12 @@ function reduceTimelineEvent(
         level: item.level,
         message: item.message,
       };
-      return finalizeActiveThoughts(appendNotification(state, notification));
+      return appendNotification(state, notification);
     }
     case "compaction":
-      return finalizeActiveThoughts(
-        reduceTimelineCompaction(state, item, timestamp, timelineCursor),
-      );
+      return reduceTimelineCompaction(state, item, timestamp, timelineCursor);
     case "plugin":
-      return finalizeActiveThoughts(
-        appendPluginTimelineItem(state, item, timestamp, timelineCursor),
-      );
+      return appendPluginTimelineItem(state, item, timestamp, timelineCursor);
     default:
       return state;
   }
@@ -1601,8 +1594,9 @@ export function reduceStreamUpdate(
 ): StreamItem[] {
   const source = options?.source ?? "live";
   switch (event.type) {
-    case "timeline":
-      return applyTimelineTurnId(
+    case "timeline": {
+      const updated = applyTimelineTurnId(
+        state,
         reduceTimelineEvent(
           state,
           event,
@@ -1613,6 +1607,8 @@ export function reduceStreamUpdate(
         ),
         event,
       );
+      return event.item.type === "reasoning" ? updated : finalizeActiveThoughts(updated);
+    }
     case "thread_started":
     case "turn_started":
     case "turn_completed":
@@ -1628,6 +1624,7 @@ export function reduceStreamUpdate(
 }
 
 function applyTimelineTurnId(
+  previous: StreamItem[],
   items: StreamItem[],
   event: Extract<AgentStreamEventPayload, { type: "timeline" }>,
 ): StreamItem[] {
@@ -1637,15 +1634,14 @@ function applyTimelineTurnId(
     return reconcileCanonicalUserTurnMembership(items, clientMessageId, event.turnId);
   }
 
-  if (!event.turnId || items.length === 0) return items;
-  const index = items.length - 1;
-  const last = items[index];
-  if (!last || last.turnId === event.turnId) return items;
-  return [
-    ...items.slice(0, index),
-    { ...last, turnId: event.turnId } as StreamItem,
-    ...items.slice(index + 1),
-  ];
+  if (!event.turnId || items === previous) return items;
+  // Assign membership only to rows written by this event, before finalizing
+  // unrelated reasoning rows. Late lifecycle updates can replace an earlier row.
+  return items.map((item, index) =>
+    item === previous[index] || item.turnId === event.turnId
+      ? item
+      : ({ ...item, turnId: event.turnId } as StreamItem),
+  );
 }
 
 function reconcileCanonicalUserTurnMembership(
diff --git a/packages/app/src/usage/balance-bar.tsx b/packages/app/src/usage/balance-bar.tsx
index def723c554..bcd33873cc 100644
--- a/packages/app/src/usage/balance-bar.tsx
+++ b/packages/app/src/usage/balance-bar.tsx
@@ -1,10 +1,16 @@
-import { useMemo } from "react";
 import type { TFunction } from "i18next";
 import { useTranslation } from "react-i18next";
-import { Text, View, type StyleProp, type ViewStyle } from "react-native";
+import { Text, View } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
-import { clampPct, formatAmount, formatProviderUsageLabel, formatResetLabel } from "./format";
-import type { UsageBalance, UsageTone } from "./types";
+import {
+  formatAmount,
+  formatProviderUsageLabel,
+  formatResetLabel,
+  formatResetTime,
+} from "./format";
+import { UsageMeter } from "./meter";
+import { UsageResetLine } from "./reset-line";
+import type { UsageBalance } from "./types";
 import { useRelativeTimeTick } from "./use-relative-time-tick";
 
 interface ResolvedBalance {
@@ -41,19 +47,6 @@ function resolveBalance({
   return { amountText: "—", usedPct: null };
 }
 
-function fillToneStyle(tone: UsageTone) {
-  switch (tone) {
-    case "ok":
-      return styles.fillOk;
-    case "warning":
-      return styles.fillWarning;
-    case "danger":
-      return styles.fillDanger;
-    default:
-      return styles.fillDefault;
-  }
-}
-
 export function UsageBalanceBar({
   balance,
   retained = false,
@@ -66,11 +59,7 @@ export function UsageBalanceBar({
   const { amountText, usedPct } = resolveBalance({ balance, t, locale: i18n.resolvedLanguage });
   const tone = balance.tone ?? "default";
   const resetLabel = formatResetLabel(balance.resetsAt, retained, now, t);
-
-  const fillStyle = useMemo<StyleProp<ViewStyle>>(
-    () => [styles.fill, fillToneStyle(tone), { width: `${clampPct(usedPct ?? 0)}%` }],
-    [usedPct, tone],
-  );
+  const resetTime = formatResetTime(balance.resetsAt, now, t);
 
   return (
     <View style={styles.container}>
@@ -78,22 +67,21 @@ export function UsageBalanceBar({
         <Text style={styles.label} numberOfLines={1}>
           {formatProviderUsageLabel(balance.id, balance.label, t)}
         </Text>
-        <View style={styles.value} testID={`provider-usage-balance-${balance.id}-value`}>
-          <Text style={styles.amount} numberOfLines={1} ellipsizeMode="tail">
-            {amountText}
-          </Text>
-          {resetLabel ? (
-            <Text style={styles.reset} testID={`provider-usage-balance-${balance.id}-reset`}>
-              {resetLabel}
-            </Text>
-          ) : null}
-        </View>
+        <Text
+          style={styles.amount}
+          numberOfLines={1}
+          ellipsizeMode="tail"
+          testID={`provider-usage-balance-${balance.id}-value`}
+        >
+          {amountText}
+        </Text>
       </View>
-      {usedPct != null ? (
-        <View style={styles.track}>
-          <View style={fillStyle} />
-        </View>
-      ) : null}
+      {usedPct != null ? <UsageMeter percent={usedPct} tone={tone} /> : null}
+      <UsageResetLine
+        countdown={resetLabel}
+        exactTime={resetTime}
+        testID={`provider-usage-balance-${balance.id}-reset`}
+      />
     </View>
   );
 }
@@ -110,44 +98,13 @@ const styles = StyleSheet.create((theme) => ({
   },
   label: {
     flexShrink: 1,
-    color: theme.colors.foregroundMuted,
-    fontSize: theme.fontSize.sm,
-  },
-  value: {
-    flexShrink: 1,
-    alignItems: "flex-end",
-  },
-  amount: {
     color: theme.colors.foreground,
     fontSize: theme.fontSize.sm,
     fontWeight: theme.fontWeight.medium,
   },
-  reset: {
-    color: theme.colors.foregroundMuted,
+  amount: {
+    flexShrink: 1,
+    color: theme.colors.foreground,
     fontSize: theme.fontSize.sm,
-    fontWeight: theme.fontWeight.normal,
-    textAlign: "right",
-  },
-  track: {
-    height: 4,
-    borderRadius: 2,
-    backgroundColor: theme.colors.surface3,
-    overflow: "hidden",
-  },
-  fill: {
-    height: 4,
-    borderRadius: 2,
-  },
-  fillDefault: {
-    backgroundColor: theme.colors.foregroundMuted,
-  },
-  fillOk: {
-    backgroundColor: theme.colors.statusSuccess,
-  },
-  fillWarning: {
-    backgroundColor: theme.colors.statusWarning,
-  },
-  fillDanger: {
-    backgroundColor: theme.colors.statusDanger,
   },
 }));
diff --git a/packages/app/src/usage/controls.tsx b/packages/app/src/usage/controls.tsx
index 20297c9df0..f0a8c73f5e 100644
--- a/packages/app/src/usage/controls.tsx
+++ b/packages/app/src/usage/controls.tsx
@@ -21,10 +21,12 @@ export interface UsageHostSelection {
  */
 export function UsageControls({
   view,
+  serverId,
   onRefresh,
   hostSelection,
 }: {
   view: UsageView;
+  serverId: string;
   onRefresh: () => void;
   hostSelection?: UsageHostSelection;
 }) {
@@ -43,8 +45,8 @@ export function UsageControls({
       ) : null}
       {view.kind === "unavailable" ? null : (
         <>
-          <UsageRefreshButton busy={busy} onRefresh={onRefresh} />
-          <UsageOptions />
+          {view.kind === "off" ? null : <UsageRefreshButton busy={busy} onRefresh={onRefresh} />}
+          <UsageOptions serverId={serverId} />
         </>
       )}
     </View>
@@ -84,7 +86,12 @@ export function useHostUsageWithControls(hostSelection: UsageHostSelection): {
   const controls = useMemo(
     () =>
       hasControls ? (
-        <UsageControls view={view} onRefresh={refresh} hostSelection={hostSelection} />
+        <UsageControls
+          serverId={hostSelection.serverId}
+          view={view}
+          onRefresh={refresh}
+          hostSelection={hostSelection}
+        />
       ) : null,
     [hasControls, hostSelection, refresh, view],
   );
diff --git a/packages/app/src/usage/display.ts b/packages/app/src/usage/display.ts
index 5b4e534693..c62ed78fd7 100644
--- a/packages/app/src/usage/display.ts
+++ b/packages/app/src/usage/display.ts
@@ -1,7 +1,5 @@
 import { useCallback, useMemo } from "react";
 import { useAppSettings } from "@/hooks/use-settings";
-import { useUsageHostId } from "./hosts";
-import { useUsageHostReports } from "./queries";
 import {
   isUsagePinned,
   setUsageDisplayAs,
@@ -25,12 +23,6 @@ interface UsagePreferencesState {
   display: UsageDisplay;
 }
 
-/** The device's usage preferences, with pins resolved against a host's reports. */
-export function useUsagePreferences(serverId?: string): UsagePreferencesState {
-  const defaultServerId = useUsageHostId();
-  return useUsageDisplay(useUsageHostReports(serverId ?? defaultServerId));
-}
-
 /** The device's usage preferences, with pins resolved against the given reports. */
 export function useUsageDisplay(reports: readonly UsageReportEntry[]): UsagePreferencesState {
   const { settings, updateSettings } = useAppSettings();
diff --git a/packages/app/src/usage/format.test.ts b/packages/app/src/usage/format.test.ts
index b7b81f0e5a..89fb9a7ed6 100644
--- a/packages/app/src/usage/format.test.ts
+++ b/packages/app/src/usage/format.test.ts
@@ -7,6 +7,7 @@ import {
   formatPct,
   formatProviderUsageLabel,
   formatResetLabel,
+  formatResetTime,
   formatRunsOutLabel,
 } from "./format";
 
@@ -36,8 +37,8 @@ describe("formatAmount", () => {
     const threeDaysAgo = new Date(NOW - 3 * 24 * 60 * 60 * 1000).toISOString();
 
     expect(formatPct(7, "en")).toBe("7%");
-    expect(formatResetLabel(twoHoursFromNow, false, NOW)).toBe("resets 2h");
-    expect(formatRunsOutLabel(twoHoursFromNow, NOW)).toBe("runs out 2h");
+    expect(formatResetLabel(twoHoursFromNow, false, NOW)).toBe("resets in 2h");
+    expect(formatRunsOutLabel(twoHoursFromNow, NOW)).toBe("runs out in 2h");
 
     await i18n.changeLanguage("ja");
     expect(formatResetLabel(twoHoursFromNow, false, NOW)).toBe("2時間後にリセット");
@@ -94,6 +95,70 @@ describe("formatAmount", () => {
   });
 });
 
+describe("reset countdown", () => {
+  const MINUTE = 60_000;
+  const HOUR = 60 * MINUTE;
+  const DAY = 24 * HOUR;
+  const countdown = (ms: number) => formatResetLabel(new Date(NOW + ms).toISOString(), false, NOW);
+
+  beforeEach(async () => {
+    await i18n.changeLanguage("en");
+  });
+
+  it("keeps counting down inside a day instead of sitting on the rounded-down day", () => {
+    expect(countdown(2 * DAY + 23 * HOUR + 10 * MINUTE)).toBe("resets in 2d 23h");
+    expect(countdown(2 * DAY + 22 * HOUR + 10 * MINUTE)).toBe("resets in 2d 22h");
+  });
+
+  it("says two units, dropping a unit that is zero", () => {
+    expect(countdown(DAY + 30 * MINUTE)).toBe("resets in 1d");
+    expect(countdown(4 * HOUR + 59 * MINUTE)).toBe("resets in 4h 59m");
+    expect(countdown(HOUR)).toBe("resets in 1h");
+    expect(countdown(37 * MINUTE)).toBe("resets in 37m");
+    expect(countdown(59 * 1000)).toBe("resets in 0m");
+  });
+
+  it("joins the at-risk countdown the same way", () => {
+    const iso = new Date(NOW + 3 * HOUR + 5 * MINUTE).toISOString();
+    expect(formatRunsOutLabel(iso, NOW)).toBe("runs out in 3h 5m");
+  });
+});
+
+describe("exact reset time", () => {
+  // Local-time dates, so the thresholds hold in any timezone the tests run in.
+  const now = new Date(2026, 9, 29, 12, 0).getTime();
+  const at = (...args: [number, number, number, number, number]) =>
+    formatResetTime(new Date(...args).toISOString(), now)?.replace(/\s/g, " ");
+
+  beforeEach(async () => {
+    await i18n.changeLanguage("en");
+  });
+
+  it("shows only the time within 24 hours", () => {
+    expect(at(2026, 9, 29, 15, 0)).toMatch(/^(3:00 PM|15:00)$/);
+    expect(at(2026, 9, 30, 11, 59)).toMatch(/^(11:59 AM|11:59)$/);
+  });
+
+  it("adds the weekday within 7 days", () => {
+    expect(at(2026, 9, 30, 12, 0)).toMatch(/^Fri (12:00 PM|12:00)$/);
+    expect(at(2026, 10, 5, 11, 59)).toMatch(/^Thu (11:59 AM|11:59)$/);
+  });
+
+  it("adds the date after 7 days", () => {
+    expect(at(2026, 10, 5, 12, 0)).toMatch(/^Nov 5, (12:00 PM|12:00)$/);
+  });
+
+  it("names the weekday in the app language", async () => {
+    await i18n.changeLanguage("fr");
+    expect(at(2026, 9, 31, 15, 0)).toMatch(/^sam\.? /);
+  });
+
+  it("says nothing for a time that has passed", () => {
+    expect(formatResetTime(new Date(now - 1).toISOString(), now)).toBeNull();
+    expect(formatResetTime(null, now)).toBeNull();
+  });
+});
+
 it("retained reset times that have passed do not claim the quota is resetting", () => {
   const past = "2000-01-01T00:00:00.000Z";
   expect(formatResetLabel(past, true)).toBe("Reset time passed");
diff --git a/packages/app/src/usage/format.ts b/packages/app/src/usage/format.ts
index e7a6ba6f7b..867976a586 100644
--- a/packages/app/src/usage/format.ts
+++ b/packages/app/src/usage/format.ts
@@ -1,5 +1,6 @@
 import type { TFunction } from "i18next";
 import { i18n } from "@/i18n/i18next";
+import { formatTimeOfDay } from "@/utils/time";
 import type { UsageDisplayAs } from "./preferences";
 import type { UsageBalanceUnit } from "./types";
 
@@ -50,7 +51,17 @@ export function formatDisplayPct(
     : t("providerUsage.values.remaining", { amount: percentage });
 }
 
-type RelativeDuration = { unit: "now" } | { unit: "minutes" | "hours" | "days"; count: number };
+type DurationUnit = "minutes" | "hours" | "days";
+interface DurationPart {
+  unit: DurationUnit;
+  count: number;
+}
+/** Two units, floored, so a countdown keeps moving: "2d 23h", "4h 59m", "37m". */
+type RelativeDuration = { kind: "now" } | { kind: "remaining"; parts: DurationPart[] };
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
 
 function formatCount(value: number): string {
   return new Intl.NumberFormat(i18n.resolvedLanguage).format(value);
@@ -59,35 +70,34 @@ function formatCount(value: number): string {
 function relativeDuration(iso: string, now: number): RelativeDuration | null {
   const diffMs = new Date(iso).getTime() - now;
   if (!Number.isFinite(diffMs)) return null;
-  if (diffMs <= 0) return { unit: "now" };
-  const diffMinutes = Math.floor(diffMs / 60_000);
-  const diffHours = Math.floor(diffMinutes / 60);
-  const diffDays = Math.floor(diffHours / 24);
-  if (diffDays > 0) return { unit: "days", count: diffDays };
-  if (diffHours > 0) return { unit: "hours", count: diffHours };
-  return { unit: "minutes", count: diffMinutes };
+  if (diffMs <= 0) return { kind: "now" };
+  const days = Math.floor(diffMs / DAY_MS);
+  const hours = Math.floor((diffMs % DAY_MS) / HOUR_MS);
+  const minutes = Math.floor((diffMs % HOUR_MS) / MINUTE_MS);
+  if (days > 0) return remaining({ unit: "days", count: days }, { unit: "hours", count: hours });
+  if (hours > 0)
+    return remaining({ unit: "hours", count: hours }, { unit: "minutes", count: minutes });
+  return remaining({ unit: "minutes", count: minutes });
 }
 
-function formatRelativeDuration(duration: RelativeDuration, t: TFunction): string | null {
-  switch (duration.unit) {
-    case "now":
-      return null;
-    case "days":
-      return t("providerUsage.duration.days", {
-        count: duration.count,
-        value: formatCount(duration.count),
-      });
-    case "hours":
-      return t("providerUsage.duration.hours", {
-        count: duration.count,
-        value: formatCount(duration.count),
-      });
-    case "minutes":
-      return t("providerUsage.duration.minutes", {
-        count: duration.count,
-        value: formatCount(duration.count),
-      });
-  }
+/** The major unit, plus the minor one unless it is zero. */
+function remaining(major: DurationPart, minor?: DurationPart): RelativeDuration {
+  return { kind: "remaining", parts: minor && minor.count > 0 ? [major, minor] : [major] };
+}
+
+function formatDurationPart(part: DurationPart, t: TFunction): string {
+  return t(`providerUsage.duration.${part.unit}`, {
+    count: part.count,
+    value: formatCount(part.count),
+  });
+}
+
+function formatRelativeDuration(
+  duration: Extract<RelativeDuration, { kind: "remaining" }>,
+  t: TFunction,
+): string {
+  const [first, second] = duration.parts.map((part) => formatDurationPart(part, t));
+  return second ? t("providerUsage.duration.pair", { first, second }) : first;
 }
 
 export function formatResetLabel(
@@ -99,10 +109,34 @@ export function formatResetLabel(
   if (!iso) return null;
   const rel = relativeDuration(iso, now);
   if (!rel) return null;
-  if (rel.unit === "now" && retained) return t("providerUsage.timing.resetTimePassed");
-  if (rel.unit === "now") return t("providerUsage.timing.resettingNow");
-  const duration = formatRelativeDuration(rel, t);
-  return duration ? t("providerUsage.timing.resetsIn", { duration }) : null;
+  if (rel.kind === "now" && retained) return t("providerUsage.timing.resetTimePassed");
+  if (rel.kind === "now") return t("providerUsage.timing.resettingNow");
+  return t("providerUsage.timing.resetsIn", { duration: formatRelativeDuration(rel, t) });
+}
+
+/**
+ * When a window resets on the clock: "3:00 PM" within a day, "Fri 3:00 PM" within a week,
+ * "Oct 31, 3:00 PM" after that. Names follow the app language; 12/24h follows the device.
+ * Nothing for a time that has passed, where the countdown already says so.
+ */
+export function formatResetTime(
+  iso: string | null | undefined,
+  now = Date.now(),
+  t: TFunction = i18n.t,
+): string | null {
+  if (!iso) return null;
+  const at = new Date(iso);
+  const diffMs = at.getTime() - now;
+  if (!Number.isFinite(diffMs) || diffMs <= 0) return null;
+  const time = formatTimeOfDay(at);
+  const locale = i18n.resolvedLanguage;
+  if (diffMs < DAY_MS) return time;
+  if (diffMs < 7 * DAY_MS) {
+    const weekday = at.toLocaleDateString(locale, { weekday: "short" });
+    return t("providerUsage.timing.resetsAtWeekday", { weekday, time });
+  }
+  const date = at.toLocaleDateString(locale, { month: "short", day: "numeric" });
+  return t("providerUsage.timing.resetsAtDate", { date, time });
 }
 
 export function formatRunsOutLabel(
@@ -113,9 +147,8 @@ export function formatRunsOutLabel(
   if (!iso) return null;
   const rel = relativeDuration(iso, now);
   if (!rel) return null;
-  if (rel.unit === "now") return t("providerUsage.timing.runsOutNow");
-  const duration = formatRelativeDuration(rel, t);
-  return duration ? t("providerUsage.timing.runsOutIn", { duration }) : null;
+  if (rel.kind === "now") return t("providerUsage.timing.runsOutNow");
+  return t("providerUsage.timing.runsOutIn", { duration: formatRelativeDuration(rel, t) });
 }
 
 export function formatAgo(
diff --git a/packages/app/src/usage/host-usage-section.tsx b/packages/app/src/usage/host-usage-section.tsx
index e80e839680..4921c7f954 100644
--- a/packages/app/src/usage/host-usage-section.tsx
+++ b/packages/app/src/usage/host-usage-section.tsx
@@ -1,5 +1,5 @@
 import { useTranslation } from "react-i18next";
-import { useUsagePreferences } from "./display";
+import { useUsageDisplay } from "./display";
 import { useHostUsage } from "./queries";
 import { UsageSection } from "./usage-section";
 
@@ -7,7 +7,7 @@ import { UsageSection } from "./usage-section";
 export function HostUsageSection({ serverId }: { serverId: string }) {
   const { t } = useTranslation();
   const { view, refresh } = useHostUsage(serverId);
-  const { display } = useUsagePreferences(serverId);
+  const { display } = useUsageDisplay(view.kind === "ready" ? view.reports : []);
   return (
     <UsageSection
       serverId={serverId}
diff --git a/packages/app/src/usage/index.ts b/packages/app/src/usage/index.ts
index 45599aba2d..64353b8c9d 100644
--- a/packages/app/src/usage/index.ts
+++ b/packages/app/src/usage/index.ts
@@ -4,6 +4,6 @@ export { useHostReportsUsage } from "./queries";
 export {
   UsageSidebarItem,
   UsageSidebarRoot,
-  useHasUsageSummary,
+  useUsageSummary,
   useOpenSidebarUsage,
 } from "./sidebar-item";
diff --git a/packages/app/src/usage/meter.tsx b/packages/app/src/usage/meter.tsx
index 37842cafb5..4150477801 100644
--- a/packages/app/src/usage/meter.tsx
+++ b/packages/app/src/usage/meter.tsx
@@ -46,8 +46,8 @@ export function UsageMeter({
 
 const styles = StyleSheet.create((theme) => ({
   track: {
-    height: 4,
-    borderRadius: 2,
+    height: 6,
+    borderRadius: 3,
     backgroundColor: theme.colors.surface3,
     overflow: "hidden",
   },
diff --git a/packages/app/src/usage/model.test.ts b/packages/app/src/usage/model.test.ts
index a278d66984..3090ac79e4 100644
--- a/packages/app/src/usage/model.test.ts
+++ b/packages/app/src/usage/model.test.ts
@@ -405,3 +405,15 @@ it("available and retained usage show the same successful completion time", () =
   );
   expect(upsertReport([failure], success)).toEqual([failure]);
 });
+
+it("disabled host shows off even with cached reports", () => {
+  expect(
+    resolveUsageView({
+      hostLabel: "Laptop",
+      isConnected: true,
+      supportsUsage: true,
+      enabled: false,
+      query: { data: [], error: null, isFetching: false },
+    }),
+  ).toMatchObject({ kind: "off" });
+});
diff --git a/packages/app/src/usage/model.ts b/packages/app/src/usage/model.ts
index 48143ad23f..bbe183dcd0 100644
--- a/packages/app/src/usage/model.ts
+++ b/packages/app/src/usage/model.ts
@@ -106,6 +106,7 @@ export interface UsageQueryState {
 
 export function resolveUsageView(
   input: {
+    enabled?: boolean;
     hostLabel: string;
     isConnected: boolean;
     supportsUsage: boolean;
@@ -125,6 +126,8 @@ export function resolveUsageView(
       message: t("providerUsage.hostUpgradeRequired", { host: hostLabel }),
     };
   }
+  if (input.enabled === false)
+    return { kind: "off", message: t("providerUsage.off", { host: hostLabel }) };
   if (query?.data) {
     return { kind: "ready", reports: query.data, isRefreshing: query.isFetching };
   }
diff --git a/packages/app/src/usage/options.tsx b/packages/app/src/usage/options.tsx
index b735b612aa..cc674cb90f 100644
--- a/packages/app/src/usage/options.tsx
+++ b/packages/app/src/usage/options.tsx
@@ -8,15 +8,20 @@ import { ToolbarButton, paneContentToolbarIconSize } from "@/components/ui/pane-
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { SettingsRow, SettingsSwitch } from "@/components/settings";
 import { SegmentedControl, type SegmentedControlOption } from "@/components/ui/segmented-control";
+import { Alert } from "@/components/ui/alert";
+import { useHosts } from "@/runtime/host-runtime";
 import { settingsStyles } from "@/styles/settings";
-import { useUsagePreferences } from "./display";
+import { useUsageSetting } from "./setting";
+import { useUsageDisplay } from "./display";
 import { useUsageInSidebar } from "./in-sidebar";
 import type { UsageDisplayAs } from "./preferences";
 
 const ThemedSettings = withUnistyles(Settings);
 
 /** The shared usage preferences, opened from a cog as a popover or compact sheet. */
-export function UsageOptions() {
+export function UsageOptions({ serverId }: { serverId: string | null }) {
+  const setting = useUsageSetting(serverId);
+  const hostLabel = useHosts().find((host) => host.serverId === serverId)?.label ?? serverId;
   const { t } = useTranslation();
   const displayAsOptions: SegmentedControlOption<UsageDisplayAs>[] = [
     { value: "used", label: t("providerUsage.displayUsed"), testID: "usage-display-used" },
@@ -27,7 +32,7 @@ export function UsageOptions() {
     },
   ];
   const compact = useIsCompactFormFactor();
-  const { display } = useUsagePreferences();
+  const { display } = useUsageDisplay([]);
   const { inSidebar, setInSidebar } = useUsageInSidebar();
   return (
     <DropdownMenu compactMode="sheet">
@@ -49,20 +54,31 @@ export function UsageOptions() {
         testID="usage-options-surface"
       >
         <View testID="usage-options-fields">
-          <SettingsSwitch
-            label={t("providerUsage.showInSidebar")}
-            hint={t("providerUsage.showInSidebarHint")}
-            value={inSidebar}
-            onValueChange={setInSidebar}
-            testID="usage-show-in-sidebar"
-          />
+          {setting.error ? <Alert variant="error" description={setting.error.message} /> : null}
+          {setting.supported ? (
+            <SettingsSwitch
+              label={t("providerUsage.checkUsage")}
+              hint={t("providerUsage.checkUsageHint", { host: hostLabel })}
+              disabled={!setting.ready}
+              value={setting.enabled}
+              onValueChange={setting.setEnabled}
+            />
+          ) : null}
+          <View style={setting.supported ? settingsStyles.rowBorder : undefined}>
+            <SettingsSwitch
+              label={t("providerUsage.showInSidebar")}
+              hint={t("providerUsage.showInSidebarHint")}
+              value={inSidebar}
+              onValueChange={setInSidebar}
+              testID="usage-show-in-sidebar"
+            />
+          </View>
           <View style={settingsStyles.rowBorder}>
             <SettingsRow label={t("providerUsage.displayAs")}>
               <SegmentedControl
                 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 c5ec32bd2d..bac8bd7ffa 100644
--- a/packages/app/src/usage/queries.ts
+++ b/packages/app/src/usage/queries.ts
@@ -17,6 +17,7 @@ import {
   useHosts,
 } from "@/runtime/host-runtime";
 import { useSessionStore, type SessionState } from "@/stores/session-store";
+import { useUsageSetting } from "./setting";
 import { usageCopy } from "./copy";
 import {
   replaceReport,
@@ -32,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) {
@@ -132,13 +134,14 @@ function toQueryState(query: {
 
 /** Usage reports for one host, as shown on its settings page. */
 export function useHostUsage(serverId: string): { view: UsageView; refresh: () => void } {
+  const setting = useUsageSetting(serverId);
   const queryClient = useQueryClient();
   const isConnected = useHostRuntimeIsConnected(serverId);
   const isSupported = useSessionStore((state) => supportsUsage(state.sessions[serverId]));
   const query = useFetchQuery({
     queryKey: usageReportsQueryKey(serverId),
     queryFn: () => listReports(queryClient, serverId),
-    enabled: isConnected && isSupported,
+    enabled: isConnected && isSupported && setting.enabled,
     dataShape: "list",
     staleTimeMs: REPORTS_STALE_TIME_MS,
   });
@@ -150,6 +153,7 @@ export function useHostUsage(serverId: string): { view: UsageView; refresh: () =
   const view = resolveUsageView(
     {
       hostLabel,
+      enabled: setting.ready ? setting.enabled : undefined,
       isConnected,
       supportsUsage: isSupported,
       query: toQueryState(query),
@@ -161,19 +165,27 @@ 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({
+    enabled: setting.enabled,
     queryKey: usageReportsQueryKey(serverId ?? ""),
     queryFn: serverId ? () => listReports(queryClient, serverId) : skipToken,
     dataShape: "list",
     staleTimeMs: REPORTS_STALE_TIME_MS,
+    refetchInterval: shouldPoll ? REPORTS_REFETCH_INTERVAL_MS : false,
   });
-  return query.data ?? NO_REPORTS;
+  return setting.enabled ? (query.data ?? NO_REPORTS) : NO_REPORTS;
 }
 
 /**
@@ -209,7 +221,8 @@ export function useAgentUsage(serverId: string, agentId: string): AgentUsageView
 export function useHostReportsUsage(serverId: string): boolean {
   const isConnected = useHostRuntimeIsConnected(serverId);
   const isSupported = useSessionStore((state) => supportsUsage(state.sessions[serverId]));
-  return isConnected && isSupported;
+  const setting = useUsageSetting(serverId);
+  return isConnected && isSupported && setting.enabled;
 }
 
 /** Every host with whether it is connected and reports usage, in host order. */
diff --git a/packages/app/src/usage/reset-line.tsx b/packages/app/src/usage/reset-line.tsx
new file mode 100644
index 0000000000..8016df2926
--- /dev/null
+++ b/packages/app/src/usage/reset-line.tsx
@@ -0,0 +1,48 @@
+import { Text, View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+
+/**
+ * The reset data of a window or balance: the countdown first, then the exact time. When the line
+ * is too narrow the exact time gives way (truncates) and the countdown stays whole.
+ */
+export function UsageResetLine({
+  countdown,
+  exactTime,
+  atRisk = false,
+  testID,
+}: {
+  countdown: string | null;
+  exactTime: string | null;
+  /** The countdown is a runs-out warning rather than a reset. */
+  atRisk?: boolean;
+  testID?: string;
+}) {
+  if (!countdown) return null;
+  return (
+    <View style={styles.line} testID={testID}>
+      <Text style={atRisk ? styles.atRisk : styles.text}>{countdown}</Text>
+      {exactTime ? (
+        <Text style={[styles.text, styles.exactTime]} numberOfLines={1} ellipsizeMode="tail">
+          {`\u00a0·\u00a0${exactTime}`}
+        </Text>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  line: { flexDirection: "row", alignItems: "center" },
+  text: {
+    flexShrink: 0,
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.sm,
+    fontWeight: theme.fontWeight.normal,
+  },
+  atRisk: {
+    flexShrink: 0,
+    color: theme.colors.statusDanger,
+    fontSize: theme.fontSize.sm,
+    fontWeight: theme.fontWeight.normal,
+  },
+  exactTime: { flexShrink: 1 },
+}));
diff --git a/packages/app/src/usage/setting.ts b/packages/app/src/usage/setting.ts
new file mode 100644
index 0000000000..e6916cf8c8
--- /dev/null
+++ b/packages/app/src/usage/setting.ts
@@ -0,0 +1,26 @@
+import { useMutation } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { useDaemonConfig } from "@/hooks/use-daemon-config";
+import { useSessionStore } from "@/stores/session-store";
+
+/** Host policy comes from the live daemon config replica. */
+export function useUsageSetting(serverId: string | null) {
+  const supported = useSessionStore((state) =>
+    Boolean(serverId && state.sessions[serverId]?.serverInfo?.features?.usageSetting),
+  );
+  const { config, patchConfig } = useDaemonConfig(supported ? serverId : null);
+  const mutation = useMutation({
+    mutationFn: (enabled: boolean) => patchConfig({ usage: { enabled } }),
+  });
+  const setEnabled = mutation.mutate;
+  const turnOn = useCallback(() => setEnabled(true), [setEnabled]);
+  return {
+    supported,
+    error: mutation.error,
+    // COMPAT(usageSetting): added in v0.14, remove after 2027-05-01.
+    enabled: !supported || (config !== null && config.usage?.enabled !== false),
+    ready: !supported || config !== null,
+    setEnabled,
+    turnOn,
+  };
+}
diff --git a/packages/app/src/usage/sidebar-item.tsx b/packages/app/src/usage/sidebar-item.tsx
index 45a8a8b293..bd4dfeb65e 100644
--- a/packages/app/src/usage/sidebar-item.tsx
+++ b/packages/app/src/usage/sidebar-item.tsx
@@ -16,8 +16,11 @@ 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 { useUsagePreferences } from "./display";
+import { useUsageDisplay } from "./display";
+import { useUsageInSidebar } from "./in-sidebar";
 import { useUsageHostId } from "./hosts";
 import { useUsageHostReports } from "./queries";
 import { UsageSourceIcon } from "./source-icon";
@@ -33,28 +36,29 @@ import {
 import { UsageModal } from "./usage-modal";
 
 /** Each summary window with data on the usage host, under its source; empty while none has. */
-function useUsageSummary(): readonly PinnedUsageSource[] {
+export function useUsageSummary(): readonly PinnedUsageSource[] {
   const { t } = useTranslation();
-  const { preferences } = useUsagePreferences();
-  const reports = useUsageHostReports(useUsageHostId());
+  const active = useRetainedPanelActive();
+  const isAppVisible = useAppVisible();
+  const { inSidebar } = useUsageInSidebar();
+  const serverId = useUsageHostId();
+  const reports = useUsageHostReports({
+    serverId: inSidebar ? serverId : null,
+    shouldPoll: active && inSidebar && isAppVisible,
+  });
+  const { preferences } = useUsageDisplay(reports);
   return useMemo(() => resolvePinnedUsage(reports, preferences, t), [preferences, reports, t]);
 }
 
-/** Whether the sidebar Usage item has anything to show. */
-export function useHasUsageSummary(): boolean {
-  return useUsageSummary().length > 0;
-}
-
 /**
  * The sidebar footer's usage entry: each summary window's source icon and percent, and nothing
  * while no summary window has data, since the footer's Usage icon already opens Usage.
  * Pressing it opens the Usage modal.
  */
-export function UsageSidebarItem() {
+export function UsageSidebarItem({ sources }: { sources: readonly PinnedUsageSource[] }) {
   const { t } = useTranslation();
   const label = t(builtinSidebarNavLabelKey("usage"));
   const openUsage = useOpenSidebarUsage();
-  const sources = useUsageSummary();
   if (sources.length === 0) return null;
   return <PinnedUsageTrigger label={label} sources={sources} onPress={openUsage} />;
 }
@@ -192,12 +196,7 @@ function PinnedUsageLine({
           <Fragment key={window.key}>
             {layout === "meters" ? (
               <View style={[styles.meterSlot, leadStyle]}>
-                <UsageMeter
-                  percent={window.percent}
-                  tone={window.tone}
-                  quiet
-                  style={styles.meter}
-                />
+                <UsageMeter percent={window.percent} tone={window.tone} quiet />
               </View>
             ) : null}
             <Text
@@ -269,10 +268,6 @@ const styles = StyleSheet.create((theme) => ({
     minWidth: MIN_METER_WIDTH,
     marginRight: METER_GAP,
   },
-  meter: {
-    height: 6,
-    borderRadius: 3,
-  },
   percent: {
     flexShrink: 0,
     color: theme.colors.foreground,
diff --git a/packages/app/src/usage/types.ts b/packages/app/src/usage/types.ts
index 58b8e31c98..9e36f58c84 100644
--- a/packages/app/src/usage/types.ts
+++ b/packages/app/src/usage/types.ts
@@ -10,6 +10,7 @@ export type UsageBalanceUnit = UsageBalance["unit"];
 
 /** What a host's usage surface shows. `unavailable` is a host state, not a failed request. */
 export type UsageView =
+  | { kind: "off"; message: string }
   | { kind: "unavailable"; message: string }
   | { kind: "loading" }
   | { kind: "error"; message: string }
diff --git a/packages/app/src/usage/usage-modal.tsx b/packages/app/src/usage/usage-modal.tsx
index bf92eaa60f..4e049c0b58 100644
--- a/packages/app/src/usage/usage-modal.tsx
+++ b/packages/app/src/usage/usage-modal.tsx
@@ -4,7 +4,7 @@ import { View } from "react-native";
 import { AdaptiveModalSheet } from "@/components/adaptive-modal-sheet";
 import { builtinSidebarNavLabelKey } from "@/sidebar-nav/model";
 import { useHostUsageWithControls } from "./controls";
-import { useUsagePreferences } from "./display";
+import { useUsageDisplay } from "./display";
 import { useUsageHostSelection } from "./hosts";
 import type { UsageHost } from "./model";
 import { UsageBody, UsageMessage } from "./usage-section";
@@ -52,12 +52,12 @@ function HostUsageModal({
   hosts: UsageHost[];
   onSelectHost: (serverId: string) => void;
 }) {
-  const { display } = useUsagePreferences();
   const hostSelection = useMemo(
     () => ({ hosts, serverId, onSelect: onSelectHost }),
     [hosts, onSelectHost, serverId],
   );
   const { view, refresh, controls } = useHostUsageWithControls(hostSelection);
+  const { display } = useUsageDisplay(view.kind === "ready" ? view.reports : []);
   return (
     <UsageModalFrame {...props} actions={controls}>
       <View testID={`usage-host-${serverId}`}>
diff --git a/packages/app/src/usage/usage-section.tsx b/packages/app/src/usage/usage-section.tsx
index 26699fd447..1eae545f39 100644
--- a/packages/app/src/usage/usage-section.tsx
+++ b/packages/app/src/usage/usage-section.tsx
@@ -7,6 +7,7 @@ import { Button } from "@/components/ui/button";
 import { settingsStyles } from "@/styles/settings";
 import { SettingsSection } from "@/components/settings/headings/settings-section";
 import type { UsageDisplay } from "./display";
+import { useUsageSetting } from "./setting";
 import { UsageControls } from "./controls";
 import { UsageList } from "./list";
 import type { UsageView } from "./types";
@@ -27,8 +28,8 @@ export function UsageSection({
   testID?: string;
 }) {
   const trailing = useMemo(
-    () => <UsageControls view={view} onRefresh={onRefresh} />,
-    [onRefresh, view],
+    () => <UsageControls serverId={serverId} view={view} onRefresh={onRefresh} />,
+    [onRefresh, view, serverId],
   );
 
   return (
@@ -51,6 +52,15 @@ export function UsageBody({
   onRefresh: () => void;
 }) {
   const { t } = useTranslation();
+  const setting = useUsageSetting(serverId);
+  if (view.kind === "off")
+    return (
+      <View>
+        <UsageMessage text={view.message} />
+        {setting.error ? <Alert variant="error" description={setting.error.message} /> : null}
+        <Button onPress={setting.turnOn}>{t("providerUsage.turnOn")}</Button>
+      </View>
+    );
   if (view.kind === "unavailable") {
     return <UsageMessage text={view.message} />;
   }
@@ -67,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/usage/window-bar.tsx b/packages/app/src/usage/window-bar.tsx
index 99c1eb9f21..b837872e01 100644
--- a/packages/app/src/usage/window-bar.tsx
+++ b/packages/app/src/usage/window-bar.tsx
@@ -1,29 +1,24 @@
 import { Pin } from "lucide-react-native";
 import { useMemo } from "react";
 import { useTranslation } from "react-i18next";
-import { Pressable, Text, View, type StyleProp, type ViewStyle } from "react-native";
+import { Pressable, Text, View } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import {
   formatDisplayPct,
   formatProviderUsageLabel,
   formatResetLabel,
+  formatResetTime,
   formatRunsOutLabel,
 } from "./format";
 import { UsageMeter } from "./meter";
 import { displayPercent, usageWindowRowLabel } from "./model";
+import { UsageResetLine } from "./reset-line";
 import type { UsageDisplayAs } from "./preferences";
 import { windowTone } from "./tone";
 import type { UsageTone, UsageWindow } from "./types";
 import { useRelativeTimeTick } from "./use-relative-time-tick";
 
-// Pinned rows carry the pinned surface; hovering an unpinned row previews it at half strength,
-// so a hover never reads as the selection. Pinned rows do not react to hover.
-function highlightStyle(pinned: boolean, hovered: boolean) {
-  if (pinned) return styles.highlightPinned;
-  return hovered ? styles.highlightHovered : styles.highlightNone;
-}
-
 export function UsageWindowBar({
   window,
   displayAs,
@@ -54,9 +49,12 @@ export function UsageWindowBar({
     window.runsOutAt != null &&
     window.shortfallPct != null &&
     (!retained || Date.parse(window.runsOutAt) > now);
-  const trailing = isAtRisk
+  const countdown = isAtRisk
     ? formatRunsOutLabel(window.runsOutAt, now, t)
     : formatResetLabel(window.resetsAt, retained, now, t);
+  // The exact time belongs to the reset; beside a runs-out warning it would read as the moment
+  // the quota runs out.
+  const exactTime = isAtRisk ? null : formatResetTime(window.resetsAt, now, t);
 
   const value =
     shownPct != null ? formatDisplayPct(shownPct, displayAs, i18n.resolvedLanguage, t) : "—";
@@ -64,60 +62,57 @@ export function UsageWindowBar({
   const content = {
     label: formatProviderUsageLabel(window.id, window.label, t),
     value,
-    trailing,
+    countdown,
+    exactTime,
     isAtRisk,
     percent: shownPct ?? 0,
     tone,
     pinned,
   };
 
-  // Same padding as the pinnable row, so bars line up in both modes.
   if (!pinnable) {
     return (
       <View style={styles.row}>
-        <WindowRowContent {...content} highlight={styles.highlightNone} pinnable={false} />
+        <WindowRowContent {...content} pinnable={false} />
       </View>
     );
   }
 
-  // The whole row pins the window to the sidebar Usage item. Pinned or not, it keeps the same
-  // padding so toggling only changes the background.
+  // The whole row pins the window to the sidebar Usage item; the pin glyph is the only sign of it.
   return (
     <Pressable
       onPress={onTogglePin}
       accessibilityRole="checkbox"
-      accessibilityLabel={usageWindowRowLabel({ pinLabel, value, trailing })}
+      accessibilityLabel={usageWindowRowLabel({
+        pinLabel,
+        value,
+        trailing: [countdown, exactTime].filter(Boolean).join(" · "),
+      })}
       accessibilityState={accessibilityState}
       aria-checked={pinned}
       style={styles.row}
       testID={pinTestID}
     >
-      {({ hovered }: { hovered?: boolean }) => (
-        <WindowRowContent
-          {...content}
-          highlight={highlightStyle(pinned, Boolean(hovered))}
-          pinnable
-        />
-      )}
+      <WindowRowContent {...content} pinnable />
     </Pressable>
   );
 }
 
 function WindowRowContent({
-  highlight,
   label,
   value,
-  trailing,
+  countdown,
+  exactTime,
   isAtRisk,
   percent,
   tone,
   pinnable,
   pinned,
 }: {
-  highlight: StyleProp<ViewStyle>;
   label: string;
   value: string;
-  trailing: string | null | undefined;
+  countdown: string | null;
+  exactTime: string | null;
   isAtRisk: boolean;
   percent: number;
   tone: UsageTone;
@@ -126,24 +121,17 @@ function WindowRowContent({
 }) {
   return (
     <>
-      <View style={highlight} pointerEvents="none" />
-      <View style={styles.contentRow}>
-        <View style={styles.windowContent}>
-          <View style={styles.labelRow}>
-            <Text style={styles.label} numberOfLines={1}>
-              {label}
-            </Text>
-            <Text style={styles.value} numberOfLines={1} ellipsizeMode="tail">
-              {value}
-              {trailing ? (
-                <Text style={isAtRisk ? styles.atRisk : styles.reset}>{` · ${trailing}`}</Text>
-              ) : null}
-            </Text>
-          </View>
-          <UsageMeter percent={percent} tone={tone} />
-        </View>
+      <View style={styles.labelRow}>
+        <Text style={styles.label} numberOfLines={1}>
+          {label}
+        </Text>
+        <Text style={styles.value} numberOfLines={1}>
+          {value}
+        </Text>
         {pinnable ? <UsagePinGlyph pinned={pinned} /> : null}
       </View>
+      <UsageMeter percent={percent} tone={tone} />
+      <UsageResetLine countdown={countdown} exactTime={exactTime} atRisk={isAtRisk} />
     </>
   );
 }
@@ -153,9 +141,9 @@ const ThemedPin = withUnistyles(Pin);
 function UsagePinGlyph({ pinned }: { pinned: boolean }) {
   const { t } = useTranslation();
   const iconMapping = useMemo(
-    () => (theme: { colors: { foregroundMuted: string } }) => ({
-      color: theme.colors.foregroundMuted,
-      fill: pinned ? theme.colors.foregroundMuted : "none",
+    () => (theme: { colors: { foreground: string; foregroundMuted: string } }) => ({
+      color: pinned ? theme.colors.foreground : theme.colors.foregroundMuted,
+      fill: pinned ? theme.colors.foreground : "none",
     }),
     [pinned],
   );
@@ -179,59 +167,23 @@ function UsagePinGlyph({ pinned }: { pinned: boolean }) {
 }
 
 const styles = StyleSheet.create((theme) => ({
-  contentRow: { flexDirection: "row", alignItems: "center", gap: theme.spacing[2] },
-  windowContent: { flex: 1, gap: 3 },
+  row: { gap: 3, paddingVertical: theme.spacing[1.5] },
   pin: { width: 12, alignItems: "center" },
   tooltipText: { color: theme.colors.popoverForeground, fontSize: theme.fontSize.sm },
-  row: {
-    gap: 3,
-    // The highlight bleeds into the card padding so the label and bar stay on the card's rail.
-    marginHorizontal: -theme.spacing[2],
-    paddingHorizontal: theme.spacing[2],
-    paddingVertical: theme.spacing[1.5],
-    // Its own stacking context, so the highlight layer paints above the card and below the text.
-    zIndex: 0,
-  },
-  highlightNone: {
-    display: "none",
-  },
-  highlightPinned: {
-    ...StyleSheet.absoluteFill,
-    zIndex: -1,
-    borderRadius: theme.borderRadius.md,
-    backgroundColor: theme.colors.surface2,
-  },
-  // The pinned surface at half strength: a separate layer, so the text keeps full opacity.
-  highlightHovered: {
-    ...StyleSheet.absoluteFill,
-    zIndex: -1,
-    borderRadius: theme.borderRadius.md,
-    backgroundColor: theme.colors.surface2,
-    opacity: theme.opacity[50],
-  },
   labelRow: {
     flexDirection: "row",
-    justifyContent: "space-between",
     alignItems: "center",
     gap: theme.spacing[2],
   },
   label: {
     flex: 1,
-    color: theme.colors.foregroundMuted,
-    fontSize: theme.fontSize.sm,
-  },
-  value: {
-    flexShrink: 1,
     color: theme.colors.foreground,
     fontSize: theme.fontSize.sm,
     fontWeight: theme.fontWeight.medium,
   },
-  reset: {
-    color: theme.colors.foregroundMuted,
-    fontWeight: theme.fontWeight.normal,
-  },
-  atRisk: {
-    color: theme.colors.statusDanger,
-    fontWeight: theme.fontWeight.normal,
+  value: {
+    flexShrink: 0,
+    color: theme.colors.foreground,
+    fontSize: theme.fontSize.sm,
   },
 }));
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.ts b/packages/app/src/utils/agent-snapshots.ts
index 13a7bcd14b..11640d800b 100644
--- a/packages/app/src/utils/agent-snapshots.ts
+++ b/packages/app/src/utils/agent-snapshots.ts
@@ -70,6 +70,7 @@ export function projectAgentSnapshot(agent: Agent): AgentSnapshotPayload {
     updatedAt: agent.updatedAt.toISOString(),
     lastUserMessageAt: agent.lastUserMessageAt?.toISOString() ?? null,
     status: agent.status,
+    backgroundWork: agent.backgroundWork,
     ...projectActiveTurn(agent),
     capabilities: agent.capabilities,
     currentModeId: agent.currentModeId,
@@ -85,6 +86,7 @@ export function projectAgentSnapshot(agent: Agent): AgentSnapshotPayload {
     attentionReason: agent.attentionReason ?? null,
     attentionTimestamp: agent.attentionTimestamp?.toISOString() ?? null,
     archivedAt: agent.archivedAt?.toISOString() ?? null,
+    ...(agent.background ? { background: true } : {}),
   };
 }
 
@@ -110,6 +112,7 @@ export function normalizeAgentSnapshot(snapshot: AgentSnapshotPayload, serverId:
     id: snapshot.id,
     provider: snapshot.provider,
     status: snapshot.status,
+    backgroundWork: snapshot.backgroundWork,
     turn,
     createdAt,
     updatedAt,
@@ -133,6 +136,7 @@ export function normalizeAgentSnapshot(snapshot: AgentSnapshotPayload, serverId:
     attentionReason: snapshot.attentionReason ?? null,
     attentionTimestamp,
     archivedAt,
+    background: snapshot.background === true,
     parentAgentId,
     labels: snapshot.labels,
   };
diff --git a/packages/app/src/utils/desktop-window.test.ts b/packages/app/src/utils/desktop-window.test.ts
index aa95a90dbf..21f35537dc 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,
@@ -87,3 +88,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..fa1f397e1c 100644
--- a/packages/app/src/utils/desktop-window.tsx
+++ b/packages/app/src/utils/desktop-window.tsx
@@ -83,6 +83,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,
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/terminal-renderer-readiness.test.ts b/packages/app/src/utils/terminal-renderer-readiness.test.ts
index 45866f8df6..d7e5f71833 100644
--- a/packages/app/src/utils/terminal-renderer-readiness.test.ts
+++ b/packages/app/src/utils/terminal-renderer-readiness.test.ts
@@ -3,7 +3,6 @@ import { describe, expect, it } from "vitest";
 import {
   applyTerminalRendererReadyChange,
   resolveTerminalStreamTarget,
-  shouldReplayTerminalSnapshotForRenderer,
   shouldShowTerminalLoadingOverlay,
 } from "./terminal-renderer-readiness";
 
@@ -74,27 +73,6 @@ describe("terminal-renderer-readiness", () => {
     expect(current).toBeNull();
   });
 
-  it("replays snapshots only for ready events from the current renderer", () => {
-    expect(
-      shouldReplayTerminalSnapshotForRenderer({
-        change: { streamKey: "scope:terminal-1", isReady: true },
-        terminalStreamKey: "scope:terminal-1",
-      }),
-    ).toBe(true);
-    expect(
-      shouldReplayTerminalSnapshotForRenderer({
-        change: { streamKey: "scope:terminal-1", isReady: false },
-        terminalStreamKey: "scope:terminal-1",
-      }),
-    ).toBe(false);
-    expect(
-      shouldReplayTerminalSnapshotForRenderer({
-        change: { streamKey: "scope:terminal-1", isReady: true },
-        terminalStreamKey: "scope:terminal-2",
-      }),
-    ).toBe(false);
-  });
-
   it("does not attach the stream before the matching renderer is ready", () => {
     expect(
       resolveTerminalStreamTarget({
diff --git a/packages/app/src/utils/terminal-renderer-readiness.ts b/packages/app/src/utils/terminal-renderer-readiness.ts
index 7d4f855aba..197a8811f9 100644
--- a/packages/app/src/utils/terminal-renderer-readiness.ts
+++ b/packages/app/src/utils/terminal-renderer-readiness.ts
@@ -14,13 +14,6 @@ export function applyTerminalRendererReadyChange(
   return currentReadyStreamKey === change.streamKey ? null : currentReadyStreamKey;
 }
 
-export function shouldReplayTerminalSnapshotForRenderer(input: {
-  change: TerminalRendererReadyChange;
-  terminalStreamKey: string;
-}): boolean {
-  return input.change.isReady && input.change.streamKey === input.terminalStreamKey;
-}
-
 export function resolveTerminalStreamTarget(input: {
   terminalId: string;
   terminalStreamKey: string;
diff --git a/packages/app/src/utils/test-daemon-connection.test.ts b/packages/app/src/utils/test-daemon-connection.test.ts
index 4dc82dda29..29382b5c89 100644
--- a/packages/app/src/utils/test-daemon-connection.test.ts
+++ b/packages/app/src/utils/test-daemon-connection.test.ts
@@ -76,6 +76,25 @@ describe("test-daemon-connection connectToDaemon", () => {
     probe = new FakeDaemonProbe();
   });
 
+  it.each([
+    { id: "direct:lan:6767", type: "directTcp" as const, endpoint: "lan:6767" },
+    {
+      id: "relay:test",
+      type: "relay" as const,
+      relayEndpoint: "relay.paseo.sh:443",
+      daemonPublicKeyB64: "pubkey",
+    },
+  ])("adoptable $type probe clients use the app WebSocket factory", async (connection) => {
+    const { connectToDaemon } = await import("./test-daemon-connection");
+    const { createAppWebSocketFactory } = await import("@/runtime/websocket-factory");
+    const result = await connectToDaemon(connection, { serverId: "srv_probe_test" }, probe.deps);
+    try {
+      expect(result.client.config.webSocketFactory).toBe(createAppWebSocketFactory());
+    } finally {
+      await result.client.close();
+    }
+  });
+
   it("reuses the app clientId for direct connections", async () => {
     const { connectToDaemon } = await import("./test-daemon-connection");
     const first = await connectToDaemon(
@@ -129,6 +148,23 @@ describe("test-daemon-connection connectToDaemon", () => {
     expect(probe.createdConfigs()[0]?.transportFactory).toBeUndefined();
   });
 
+  it("keeps the bundle cache factory on a probe client that the host runtime can adopt", async () => {
+    const { connectToDaemon } = await import("./test-daemon-connection");
+    const createPluginClientBundleStore = () => ({
+      async load() {
+        return [];
+      },
+      async replace() {},
+    });
+    const { client } = await connectToDaemon(
+      { id: "direct:lan:6767", type: "directTcp", endpoint: "lan:6767" },
+      { createPluginClientBundleStore },
+      probe.deps,
+    );
+    expect(client.config.createPluginClientBundleStore).toBe(createPluginClientBundleStore);
+    await client.close();
+  });
+
   it("encodes the local socket target into the client config", async () => {
     const { connectToDaemon } = await import("./test-daemon-connection");
     const result = await connectToDaemon(
diff --git a/packages/app/src/utils/test-daemon-connection.ts b/packages/app/src/utils/test-daemon-connection.ts
index 18ffa62dc4..1d1605af62 100644
--- a/packages/app/src/utils/test-daemon-connection.ts
+++ b/packages/app/src/utils/test-daemon-connection.ts
@@ -6,6 +6,7 @@ import {
 } from "@getpaseo/client/internal/daemon-client";
 import type { DaemonClientConfig } from "@getpaseo/client/internal/daemon-client";
 import type { HostConnection } from "@/types/host-connection";
+import { createAppWebSocketFactory } from "@/runtime/websocket-factory";
 import { getOrCreateClientId } from "./client-id";
 import { resolveAppVersion } from "./app-version";
 import {
@@ -132,12 +133,13 @@ function resolveConnectionCredentials(
 export async function buildClientConfig(
   connection: HostConnection,
   serverId?: string,
-  options?: {
+  options: {
     capabilities?: DaemonClientConfig["capabilities"];
     trace?: DaemonClientConfig["trace"];
+    createPluginClientBundleStore?: DaemonClientConfig["createPluginClientBundleStore"];
     password?: string;
     localCredential?: DaemonClientConfig["localCredential"];
-  },
+  } = {},
   deps: Pick<
     DaemonConnectionDependencies<DaemonProbeClient>,
     | "getClientId"
@@ -155,10 +157,12 @@ export async function buildClientConfig(
     clientType: "mobile" as const,
     appVersion: deps.resolveAppVersion() ?? undefined,
     suppressSendErrors: true,
+    webSocketFactory: createAppWebSocketFactory(),
     reconnect: { enabled: false },
     ...resolveConnectionCredentials(connection, options),
-    ...(options?.capabilities ? { capabilities: options.capabilities } : {}),
-    ...(options?.trace ? { trace: options.trace } : {}),
+    ...(options.capabilities ? { capabilities: options.capabilities } : {}),
+    ...(options.trace ? { trace: options.trace } : {}),
+    createPluginClientBundleStore: options.createPluginClientBundleStore,
     ...((connection.type === "directSocket" || connection.type === "directPipe") &&
     desktopTransportFactory
       ? { transportFactory: desktopTransportFactory }
@@ -288,6 +292,7 @@ interface ProbeOptions {
   localCredential?: DaemonClientConfig["localCredential"];
   capabilities?: DaemonClientConfig["capabilities"];
   trace?: DaemonClientConfig["trace"];
+  createPluginClientBundleStore?: DaemonClientConfig["createPluginClientBundleStore"];
 }
 
 function resolveTimeout(connection: HostConnection, options?: ProbeOptions): number {
diff --git a/packages/app/src/utils/time.ts b/packages/app/src/utils/time.ts
index 948ee8eeb3..1c063d1a27 100644
--- a/packages/app/src/utils/time.ts
+++ b/packages/app/src/utils/time.ts
@@ -125,6 +125,11 @@ function getTimeFormatter(): Intl.DateTimeFormat {
   return cachedTimeFormatter;
 }
 
+/** A clock time in the device's 12h/24h preference: "3:00 PM" or "15:00". */
+export function formatTimeOfDay(date: Date): string {
+  return getTimeFormatter().format(date);
+}
+
 /**
  * Format a chat-message timestamp for hover-revealed UI.
  * - Same day: "10:11 PM" or "22:11" depending on user preference
@@ -132,7 +137,7 @@ function getTimeFormatter(): Intl.DateTimeFormat {
  * - Older, including today's weekday last week: "14 May 2026, 10:11 PM"
  */
 export function formatMessageTimestamp(date: Date, now: Date = new Date()): string {
-  const time = getTimeFormatter().format(date);
+  const time = formatTimeOfDay(date);
   const daysAgo = localCalendarDaysBetween(date, now);
 
   if (daysAgo === 0) {
diff --git a/packages/app/src/utils/tool-call-detail-state.ts b/packages/app/src/utils/tool-call-detail-state.ts
index e2d983d8cb..b28848af8e 100644
--- a/packages/app/src/utils/tool-call-detail-state.ts
+++ b/packages/app/src/utils/tool-call-detail-state.ts
@@ -40,12 +40,6 @@ function hasMeaningfulFetchDetail(detail: Extract<ToolCallDetail, { type: "fetch
   return Boolean(detail.url || detail.result || detail.codeText);
 }
 
-function hasMeaningfulSubAgentDetail(
-  detail: Extract<ToolCallDetail, { type: "sub_agent" }>,
-): boolean {
-  return Boolean(detail.subAgentType || detail.description || detail.log);
-}
-
 function hasMeaningfulPlainTextDetail(
   detail: Extract<ToolCallDetail, { type: "plain_text" }>,
 ): boolean {
@@ -75,9 +69,9 @@ export function hasMeaningfulToolCallDetail(detail: ToolCallDetail | undefined):
     case "fetch":
       return hasMeaningfulFetchDetail(detail);
     case "worktree_setup":
-      return false;
+    // A sub-agent card is a launch marker; the child's activity lives in the sub-agent panel.
     case "sub_agent":
-      return hasMeaningfulSubAgentDetail(detail);
+      return false;
     case "plain_text":
       return hasMeaningfulPlainTextDetail(detail);
     case "plan":
@@ -92,7 +86,7 @@ export function isPendingToolCallDetail(params: {
   status: "executing" | "running" | "completed" | "failed" | "canceled";
   error: unknown;
 }): boolean {
-  if (params.detail?.type === "worktree_setup") return false;
+  if (params.detail?.type === "worktree_setup" || params.detail?.type === "sub_agent") return false;
   const isRunning = params.status === "running" || params.status === "executing";
   return isRunning && params.error == null && !hasMeaningfulToolCallDetail(params.detail);
 }
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..e2d0246a92
--- /dev/null
+++ b/packages/app/src/window-layout/context.ts
@@ -0,0 +1,15 @@
+import { createContext, useContext } from "react";
+import { useWindowDimensions } from "react-native";
+import type { WindowLayout } from "./model";
+
+export const WindowLayoutContext = createContext<WindowLayout | 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;
+}
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..507133528e
--- /dev/null
+++ b/packages/app/src/window-layout/index.ios.tsx
@@ -0,0 +1,52 @@
+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 { WindowLayoutContext, useWindowLayout } from "./context";
+import { resolveSafeAreaInsets, type WindowLayout } from "./model";
+
+export { useWindowLayout } from "./context";
+export { WindowLayoutActions, WindowLayoutActionsHost } from "./actions";
+export { WindowLayoutSurface, WindowLayoutDivisionGap } from "./surface";
+export {
+  resolveDesktopDivisionLayout,
+  resolveWorkspaceActionPlacement,
+  resolveWorkspaceBarActions,
+} from "./model";
+export type { DesktopDivisionLayout, 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 bottom inset every descendant reads through `useSafeAreaInsets()`. */
+function WindowSafeAreaInsets({ children }: { children: ReactNode }) {
+  const systemInsets = useSafeAreaInsets();
+  const layout = useWindowLayout();
+  const insets = useMemo(() => resolveSafeAreaInsets(systemInsets, layout), [systemInsets, layout]);
+  return <SafeAreaInsetsContext.Provider value={insets}>{children}</SafeAreaInsetsContext.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..c884d3e987
--- /dev/null
+++ b/packages/app/src/window-layout/index.tsx
@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+
+export { useWindowLayout } from "./context";
+export { WindowLayoutActions, WindowLayoutActionsHost } from "./actions";
+export { WindowLayoutSurface, WindowLayoutDivisionGap } from "./surface";
+export {
+  resolveDesktopDivisionLayout,
+  resolveWorkspaceActionPlacement,
+  resolveWorkspaceBarActions,
+} from "./model";
+export type { DesktopDivisionLayout, 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..e363d4313a
--- /dev/null
+++ b/packages/app/src/window-layout/model.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { resolveSafeAreaInsets, type WindowLayout } from "./model";
+
+const systemInsets = { top: 59, right: 0, bottom: 34, left: 0 };
+
+function layout(bottomClearance: number | null | undefined): WindowLayout {
+  return {
+    bounds: { x: 0, y: 0, width: 402, height: 874 },
+    verticalBarEdge: "none",
+    verticalBar: null,
+    bottomClearance,
+    divisions: [],
+  };
+}
+
+describe("resolveSafeAreaInsets", () => {
+  it("replaces only the bottom with the measured bar clearance", () => {
+    expect(resolveSafeAreaInsets(systemInsets, layout(24))).toEqual({
+      ...systemInsets,
+      bottom: 24,
+    });
+  });
+
+  it("keeps a measured zero instead of falling back to the system inset", () => {
+    expect(resolveSafeAreaInsets(systemInsets, layout(0)).bottom).toBe(0);
+  });
+
+  it.each([null, undefined])("leaves system insets alone without a clearance (%s)", (value) => {
+    expect(resolveSafeAreaInsets(systemInsets, layout(value))).toBe(systemInsets);
+  });
+
+  it("leaves system insets alone before the native layout arrives", () => {
+    expect(resolveSafeAreaInsets(systemInsets, null)).toBe(systemInsets);
+  });
+});
diff --git a/packages/app/src/window-layout/model.ts b/packages/app/src/window-layout/model.ts
new file mode 100644
index 0000000000..d2ba0de709
--- /dev/null
+++ b/packages/app/src/window-layout/model.ts
@@ -0,0 +1,81 @@
+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;
+  divisions: WindowLayoutRect[];
+}
+
+/** The window's measured bottom clearance replaces the rectangular safe-area bottom. */
+export function resolveSafeAreaInsets<Insets extends { bottom: number }>(
+  systemInsets: Insets,
+  layout: WindowLayout | null,
+): Insets {
+  const clearance = layout?.bottomClearance;
+  return typeof clearance === "number" && clearance !== systemInsets.bottom
+    ? { ...systemInsets, bottom: clearance }
+    : systemInsets;
+}
+
+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/launcher/index.tsx b/packages/app/src/workspace-tabs/launcher/index.tsx
index 2029808f31..c55208fc95 100644
--- a/packages/app/src/workspace-tabs/launcher/index.tsx
+++ b/packages/app/src/workspace-tabs/launcher/index.tsx
@@ -25,7 +25,6 @@ import {
   type PanelIconProps,
   type PanelPresentation,
 } from "@/panels/panel-registry";
-import { ensurePanelsRegistered } from "@/panels/register-panels";
 import {
   getTerminalProfileIcon,
   resolveTerminalProfiles,
@@ -109,7 +108,6 @@ export function useWorkspaceTabLaunchCatalog(input: {
   const { config } = useDaemonConfig(serverId);
   const plugins = useInstalledPlugins();
   const isCompact = useIsCompactFormFactor();
-  ensurePanelsRegistered();
 
   const launchSelection = useCallback(
     (selection: NewTabSelection) => (destination: WorkspaceTabLaunchDestination) => {
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-tabs/open-beside.ts b/packages/app/src/workspace-tabs/open-beside.ts
index abf6eba2ec..845c2c7f78 100644
--- a/packages/app/src/workspace-tabs/open-beside.ts
+++ b/packages/app/src/workspace-tabs/open-beside.ts
@@ -6,6 +6,7 @@ import {
   DEFAULT_PANE_ID,
   findPaneById,
   findPaneContainingTab,
+  selectSheetTab,
   useWorkspaceLayoutStore,
   type WorkspaceTabPlacement,
 } from "@/stores/workspace-layout-store";
@@ -144,7 +145,7 @@ export function openPreferredWorkspacePreview(
   // The sheet is already a single replaceable slot, so it needs no preview tab.
   if (
     existing ||
-    store.opensInSheet({ workspaceKey: input.workspaceKey, target: input.target, intent: "reveal" })
+    selectSheetTab(store, { workspaceKey: input.workspaceKey, target: input.target }) !== null
   ) {
     return openPreferredWorkspaceTarget(input);
   }
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..584b71dec9
--- /dev/null
+++ b/packages/app/src/workspace/archive-undo/internal/workspace-archived-toast.tsx
@@ -0,0 +1,41 @@
+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} /> : 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",
+    alignItems: "center",
+    gap: theme.spacing[2],
+  },
+  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/open-in-file-manager/outside-folder.ts b/packages/app/src/workspace/open-in-file-manager/outside-folder.ts
new file mode 100644
index 0000000000..e7d41d72d9
--- /dev/null
+++ b/packages/app/src/workspace/open-in-file-manager/outside-folder.ts
@@ -0,0 +1,36 @@
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+import { useToast } from "@/contexts/toast-context";
+import { useIsLocalDaemon } from "@/hooks/use-is-local-daemon";
+import { openDesktopTarget, useDesktopOpenTargets } from "@/workspace/desktop-open-targets";
+
+/**
+ * Opens a folder outside the workspace in the system file manager. The Files
+ * panel only lists the workspace, so hosts without a local file manager get a
+ * toast instead.
+ */
+export function useOpenOutsideWorkspaceFolder(serverId: string): (folderPath: string) => void {
+  const { t } = useTranslation();
+  const toast = useToast();
+  const isLocalExecution = useIsLocalDaemon(serverId);
+  const { targets } = useDesktopOpenTargets({ isLocalExecution });
+  const fileManagerTarget = targets.find((target) => target.kind === "file-manager");
+
+  return useCallback(
+    (folderPath: string) => {
+      const showOutsideWorkspace = () =>
+        toast.show(t("common.errors.folderOutsideWorkspace", { path: folderPath }));
+      if (!fileManagerTarget) {
+        showOutsideWorkspace();
+        return;
+      }
+      void openDesktopTarget({ editorId: fileManagerTarget.id, workspacePath: folderPath }).catch(
+        (error: unknown) => {
+          console.warn("[open-outside-workspace-folder] open failed", error);
+          showOutsideWorkspace();
+        },
+      );
+    },
+    [fileManagerTarget, t, toast],
+  );
+}
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/gorhom-bottom-sheet.ts b/packages/app/test-stubs/gorhom-bottom-sheet.ts
index ee27421efd..7fc1d4bc4f 100644
--- a/packages/app/test-stubs/gorhom-bottom-sheet.ts
+++ b/packages/app/test-stubs/gorhom-bottom-sheet.ts
@@ -22,6 +22,10 @@ export function useBottomSheetModal(): never {
 export function useBottomSheet(): never {
   throw new Error("useBottomSheet is unavailable in tests");
 }
+// A drag area only hands its gesture to a sheet; with no sheet drawn there is nothing to drag.
+export function useBottomSheetGestureHandlers(): never {
+  throw new Error("useBottomSheetGestureHandlers is unavailable in tests");
+}
 export const BottomSheetModalInternalProvider = PassThrough;
 export const INITIAL_CONTAINER_LAYOUT = {
   height: 0,
diff --git a/packages/app/test-stubs/lucide-react-native.ts b/packages/app/test-stubs/lucide-react-native.ts
index a85976e1bf..e07f0b05e7 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;
diff --git a/packages/app/test-stubs/react-native-safe-area-context.ts b/packages/app/test-stubs/react-native-safe-area-context.ts
index ae793cd921..40c064f943 100644
--- a/packages/app/test-stubs/react-native-safe-area-context.ts
+++ b/packages/app/test-stubs/react-native-safe-area-context.ts
@@ -1,8 +1,18 @@
-// The package ships untranspiled Flow, which the unit project cannot parse. Insets are a device
-// fact no test asserts on, so they are zero.
+import { createContext, useContext } from "react";
+
+// The package ships untranspiled Flow, which the unit project cannot parse. Like the real package,
+// the hook reads the insets context; outside a provider the insets are zero.
 const ZERO_INSETS = { top: 0, right: 0, bottom: 0, left: 0 } as const;
 
-export const useSafeAreaInsets = () => ZERO_INSETS;
+export interface EdgeInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export const SafeAreaInsetsContext = createContext<EdgeInsets | null>(ZERO_INSETS);
+export const useSafeAreaInsets = () => useContext(SafeAreaInsetsContext) ?? ZERO_INSETS;
 export const useSafeAreaFrame = () => ({ x: 0, y: 0, width: 0, height: 0 });
 export const SafeAreaProvider = ({ children }: { children?: unknown }) => children;
 export const SafeAreaView = ({ children }: { children?: unknown }) => children;
diff --git a/packages/app/test-stubs/react-native-unistyles.ts b/packages/app/test-stubs/react-native-unistyles.ts
index adc8af93bf..38a86c7567 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,6 +27,7 @@ const testTheme = {
     surface1: "#fafafa",
     surface2: "#f4f4f5",
     surface3: "#e4e4e7",
+    surfaceSidebar: lightTheme.colors.surfaceSidebar,
     border: "#e4e4e7",
     borderAccent: "#a1a1aa",
     palette: {
@@ -88,9 +90,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/vitest.config.ts b/packages/app/vitest.config.ts
index 3254fc5e0c..69360fa7ee 100644
--- a/packages/app/vitest.config.ts
+++ b/packages/app/vitest.config.ts
@@ -24,7 +24,9 @@ export default defineConfig({
       transform(source, id) {
         // The ESM package contains a CommonJS WASM factory. Metro handles the
         // interop; Vite needs an ESM export instead of the CommonJS trailer.
-        if (!id.endsWith("/lib/module/web/wasm/md4c.js")) return;
+        // Vite can request the file with a version query (`md4c.js?v=<hash>`), so match the
+        // path without it.
+        if (!id.split("?")[0].endsWith("/lib/module/web/wasm/md4c.js")) return;
         const trailer = source.lastIndexOf("\nif (typeof exports === 'object'");
         if (trailer < 0) throw new Error("Markdown WASM CommonJS trailer was not found");
         return {
@@ -34,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,
@@ -80,6 +86,7 @@ export default defineConfig({
           environment: "node",
           include: [
             "src/**/*.{test,spec}.{ts,tsx}",
+            "modules/**/*.{test,spec}.{ts,tsx}",
             "native-release-version.test.ts",
             "app.config.test.ts",
             "vitest-environment.test.ts",
@@ -90,13 +97,27 @@ 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,
           include: ["src/**/*.browser.{test,spec}.{ts,tsx}"],
           browser: {
             enabled: true,
-            provider: playwright(),
+            provider: playwright({
+              // Exercise real WebGL glyph rendering on GPU-less CI runners.
+              launchOptions: { args: ["--enable-unsafe-swiftshader"] },
+            }),
             headless: true,
             connectTimeout: 180_000,
             instances: [{ browser: "chromium" }],
@@ -157,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",
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 be8188fff3..a23676a0fc 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/cli",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "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.13.2",
-    "@getpaseo/protocol": "0.13.2",
-    "@getpaseo/server": "0.13.2",
+    "@getpaseo/client": "0.15.3",
+    "@getpaseo/protocol": "0.15.3",
+    "@getpaseo/server": "0.15.3",
     "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 ed77d4be62..6b40a92536 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,78 +380,104 @@ 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);
-    }
-  }
-
-  // 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;
+    // 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);
     }
 
-    if (message.type === "agent.timeline.error") {
-      writer.end();
-      console.error(`Timeline observation stopped: ${message.payload.error}`);
-      return;
+    // Apply filter to existing items
+    if (options.filter) {
+      existingItems = existingItems.filter((item) => matchesFilter(item, options.filter));
     }
-    if (message.type === "agent.timeline.subscription_restored") {
-      writer.end();
-      console.log("\n[Reconnected; live output resumed. Events may have been missed.]");
-      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.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;
       }
-      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/commands/daemon/restart.ts b/packages/cli/src/commands/daemon/restart.ts
index ef88e39a23..97e2fbf604 100644
--- a/packages/cli/src/commands/daemon/restart.ts
+++ b/packages/cli/src/commands/daemon/restart.ts
@@ -3,8 +3,11 @@ import {
   readDaemonInstance,
   isSameDaemonInstance,
   DaemonInstanceError,
+  retryUnconfirmedTerminalCleanup,
+  TerminalCleanupNotConfirmedError,
 } from "@getpaseo/server/daemon-control";
 import { setTimeout as delay } from "node:timers/promises";
+import type { DaemonGetStatusResponse } from "@getpaseo/protocol/messages";
 import { connectToDaemon } from "../../utils/client.js";
 import { withOutput, type CommandOptions } from "../../output/index.js";
 import { addJsonAndDaemonHostOptions } from "../../utils/command-options.js";
@@ -20,13 +23,30 @@ export function daemonRestartCommand(): Command {
     ),
   )
     .option("--timeout <seconds>", "Replacement readiness deadline (default: 600)")
+    .option("--kill-terminals", "Close every terminal instead of keeping them across the restart")
     .action(withOutput(runRestartCommand));
 }
 
+type DaemonStatus = DaemonGetStatusResponse["payload"];
+
 export async function runRestartCommand(options: CommandOptions, _command: Command) {
   const target = options.daemonTarget;
   const deadline = Date.now() + parseTimeoutMs(options.timeout);
   const remaining = () => Math.max(1, deadline - Date.now());
+  const killTerminals = options.killTerminals === true;
+  // The supervisor reaps before the respawn and the replacement retries what that left;
+  // anything still named by a closing record survived both. A local caller retries once more
+  // itself; a remote one has only what the replacement reports.
+  const confirmTerminalsClosed = async (status: DaemonStatus) => {
+    if (!killTerminals) return;
+    if (target.kind === "instance") {
+      await retryUnconfirmedTerminalCleanup(target.home);
+      return;
+    }
+    // Absent on daemons without terminalsSurviveRestart, which have no terminal cleanup.
+    const unconfirmed = status.terminalCleanupUnconfirmed ?? [];
+    if (unconfirmed.length > 0) throw new TerminalCleanupNotConfirmedError(unconfirmed);
+  };
   const instance = target.kind === "instance" ? await readDaemonInstance(target.home) : null;
   async function checkSupervisor() {
     if (target.kind !== "instance") return;
@@ -54,7 +74,10 @@ export async function runRestartCommand(options: CommandOptions, _command: Comma
     workerPid = (await client.getDaemonStatus({ timeout: remaining() })).pid;
     await checkSupervisor();
     try {
-      await client.restartServer("cli_restart", undefined, { timeout: remaining() });
+      await client.restartServer("cli_restart", undefined, {
+        timeout: remaining(),
+        killTerminals,
+      });
       acknowledged = true;
     } catch (error) {
       if (!isReconnectFailure(error)) throw error;
@@ -77,6 +100,7 @@ export async function runRestartCommand(options: CommandOptions, _command: Comma
         const status = await replacement.getDaemonStatus({ timeout: remaining() });
         if (status.pid !== workerPid) {
           await checkSupervisor();
+          await confirmTerminalsClosed(status);
           return {
             type: "single" as const,
             data: {
diff --git a/packages/cli/src/commands/daemon/status.ts b/packages/cli/src/commands/daemon/status.ts
index 14c20534e6..cd499ea6cb 100644
--- a/packages/cli/src/commands/daemon/status.ts
+++ b/packages/cli/src/commands/daemon/status.ts
@@ -103,6 +103,7 @@ async function probeDaemonStatus(
         daemonNode: status.nodePath,
         providers: status.providers,
         relay: status.relay,
+        ...(status.terminalsUnavailable ? { terminals: status.terminalsUnavailable } : {}),
       };
     }
   } finally {
diff --git a/packages/cli/src/commands/daemon/stop.test.ts b/packages/cli/src/commands/daemon/stop.test.ts
new file mode 100644
index 0000000000..7ee5f930f9
--- /dev/null
+++ b/packages/cli/src/commands/daemon/stop.test.ts
@@ -0,0 +1,110 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { hostname, tmpdir } from "node:os";
+import path from "node:path";
+import { Command } from "commander";
+import { afterEach, describe, expect, test } from "vitest";
+import { createStopCommandRunner, type StopCommandDeps } from "./stop.js";
+
+// The daemon the gate is checked against: a connection whose server_info may or may not
+// advertise terminalsSurviveRestart, and that records any shutdown it is asked for.
+function createFakeDaemon(features: { terminalsSurviveRestart?: boolean } = {}) {
+  const shutdownRequests: Array<{ keepTerminals?: boolean }> = [];
+  const deps: StopCommandDeps = {
+    connectToDaemon: async () => ({
+      getLastServerInfoMessage: () => ({
+        status: "server_info",
+        serverId: "fake-daemon",
+        version: "0.11.0",
+        features,
+      }),
+      shutdownServer: async (options) => {
+        shutdownRequests.push({ keepTerminals: options?.keepTerminals });
+        return { status: "shutdown_requested", clientId: "fake-client", requestId: "fake-request" };
+      },
+      close: async () => undefined,
+    }),
+  };
+  return { deps, shutdownRequests };
+}
+
+const cleanups: Array<() => void> = [];
+
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0)) cleanup();
+});
+
+function stop(options: Record<string, unknown>, deps: StopCommandDeps) {
+  return createStopCommandRunner(deps)(options as never, new Command("stop"));
+}
+
+// A home whose lock names a live stand-in supervisor, so the local stop path runs for real.
+function homeWithRunningSupervisor(): { home: string; supervisor: ChildProcess } {
+  const home = mkdtempSync(path.join(tmpdir(), "paseo-stop-keep-"));
+  const supervisor = spawn(process.execPath, ["-e", "setInterval(() => {}, 1e9)"], {
+    stdio: "ignore",
+  });
+  writeFileSync(
+    path.join(home, "paseo.pid"),
+    JSON.stringify({
+      pid: supervisor.pid,
+      startedAt: new Date().toISOString(),
+      hostname: hostname(),
+      uid: process.getuid?.() ?? 0,
+      listen: "127.0.0.1:1",
+    }),
+  );
+  cleanups.push(() => {
+    supervisor.kill("SIGKILL");
+    rmSync(home, { recursive: true, force: true });
+  });
+  return { home, supervisor };
+}
+
+describe("daemon stop --keep-terminals", () => {
+  test("refuses an endpoint daemon that does not advertise terminalsSurviveRestart", async () => {
+    const daemon = createFakeDaemon();
+    await expect(
+      stop(
+        { daemonTarget: { kind: "endpoint", host: "127.0.0.1:7777" }, keepTerminals: true },
+        daemon.deps,
+      ),
+    ).rejects.toMatchObject({ code: "TERMINALS_KEEP_UNSUPPORTED" });
+    expect(daemon.shutdownRequests).toEqual([]);
+  });
+
+  test.skipIf(process.platform === "win32")(
+    "refuses a local daemon without the capability and never signals its supervisor",
+    async () => {
+      const daemon = createFakeDaemon();
+      const { home, supervisor } = homeWithRunningSupervisor();
+      await expect(
+        stop({ daemonTarget: { kind: "instance", home }, keepTerminals: true }, daemon.deps),
+      ).rejects.toMatchObject({ code: "TERMINALS_KEEP_UNSUPPORTED" });
+      expect(daemon.shutdownRequests).toEqual([]);
+      expect(supervisor.exitCode).toBeNull();
+      expect(supervisor.signalCode).toBeNull();
+    },
+  );
+
+  test("asks a capable daemon to keep its terminals", async () => {
+    const daemon = createFakeDaemon({ terminalsSurviveRestart: true });
+    await stop(
+      { daemonTarget: { kind: "endpoint", host: "127.0.0.1:7777" }, keepTerminals: true },
+      daemon.deps,
+    );
+    expect(daemon.shutdownRequests).toEqual([{ keepTerminals: true }]);
+  });
+
+  test("rejects --force with --keep-terminals before contacting the daemon", async () => {
+    const daemon = createFakeDaemon({ terminalsSurviveRestart: true });
+    const { home } = homeWithRunningSupervisor();
+    await expect(
+      stop(
+        { daemonTarget: { kind: "instance", home }, keepTerminals: true, force: true },
+        daemon.deps,
+      ),
+    ).rejects.toMatchObject({ code: "INVALID_OPTIONS" });
+    expect(daemon.shutdownRequests).toEqual([]);
+  });
+});
diff --git a/packages/cli/src/commands/daemon/stop.ts b/packages/cli/src/commands/daemon/stop.ts
index f2bf8b1255..141d50965e 100644
--- a/packages/cli/src/commands/daemon/stop.ts
+++ b/packages/cli/src/commands/daemon/stop.ts
@@ -1,6 +1,10 @@
 import { Command } from "commander";
+import {
+  requireTerminalKeepCapability,
+  type DaemonClient,
+} from "@getpaseo/client/internal/daemon-client";
 import { stopDaemonInstance, type DaemonInstance } from "@getpaseo/server/daemon-control";
-import { connectToDaemon } from "../../utils/client.js";
+import { connectToDaemon, type ConnectOptions } from "../../utils/client.js";
 import { withOutput, type CommandOptions } from "../../output/index.js";
 import { addJsonAndDaemonHostOptions } from "../../utils/command-options.js";
 import { describeDaemonTarget } from "../../utils/daemon-target.js";
@@ -10,19 +14,43 @@ export function daemonStopCommand(): Command {
   return addJsonAndDaemonHostOptions(new Command("stop").description("Stop the selected daemon"))
     .option("--timeout <seconds>", "Graceful exit deadline (default: 15)")
     .option("--force", "Permit forced local process cleanup")
+    .option(
+      "--keep-terminals",
+      "Leave terminals running; the next daemon started for this home takes them back",
+    )
     .option("--kill-timeout <seconds>", "Forced exit deadline (default: 3)")
     .action(withOutput(runStopCommand));
 }
 
-export async function runStopCommand(options: CommandOptions, _command: Command) {
+// The daemon connection stop needs; stop.test.ts passes an in-memory adapter.
+export type StopDaemonConnection = Pick<
+  DaemonClient,
+  "getLastServerInfoMessage" | "shutdownServer" | "close"
+>;
+
+export interface StopCommandDeps {
+  connectToDaemon(options: ConnectOptions): Promise<StopDaemonConnection>;
+}
+
+export const runStopCommand = createStopCommandRunner({ connectToDaemon });
+
+export function createStopCommandRunner(deps: StopCommandDeps) {
+  return (options: CommandOptions, _command: Command) => runStop(options, deps);
+}
+
+async function runStop(options: CommandOptions, deps: StopCommandDeps) {
   const target = options.daemonTarget;
   const timeoutMs = parseTimeoutMs(options.timeout, 15_000);
   const deadline = Date.now() + timeoutMs;
   const remaining = () => Math.max(1, deadline - Date.now());
+  const keepTerminals = options.keepTerminals === true;
   const requestShutdown = async (instance?: DaemonInstance) => {
-    const client = await connectToDaemon({ target, timeout: remaining(), instance });
+    const client = await deps.connectToDaemon({ target, timeout: remaining(), instance });
     try {
-      await client.shutdownServer({ timeout: remaining() });
+      // Checked on the connection that carries the shutdown: a daemon without the capability
+      // would close the terminals it was asked to keep.
+      if (keepTerminals) requireTerminalKeepCapability(client, describeDaemonTarget(target));
+      await client.shutdownServer({ timeout: remaining(), keepTerminals });
     } finally {
       await client.close();
     }
@@ -32,6 +60,11 @@ export async function runStopCommand(options: CommandOptions, _command: Command)
       code: "INVALID_OPTIONS",
       message: "--force requires a local --home; an endpoint gives no remote process authority.",
     };
+  if (options.force && keepTerminals)
+    throw {
+      code: "INVALID_OPTIONS",
+      message: "--force kills terminals; it cannot be combined with --keep-terminals.",
+    };
   const result: {
     action: string;
     home?: string;
@@ -44,6 +77,7 @@ export async function runStopCommand(options: CommandOptions, _command: Command)
       ? {
           ...(await stopDaemonInstance(target.home, {
             force: options.force === true,
+            keepTerminals,
             timeoutMs,
             killTimeoutMs: parseTimeoutMs(options.killTimeout, 3_000),
             requestShutdown,
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/42-test-daemon-ephemeral-port.test.ts b/packages/cli/tests/42-test-daemon-ephemeral-port.test.ts
new file mode 100644
index 0000000000..f559c275bc
--- /dev/null
+++ b/packages/cli/tests/42-test-daemon-ephemeral-port.test.ts
@@ -0,0 +1,16 @@
+#!/usr/bin/env npx tsx
+
+import assert from "node:assert/strict";
+import { startTestDaemon, runPaseoCli } from "./helpers/test-daemon.ts";
+
+// Port zero leaves allocation to the listening daemon, with no reserve/release gap.
+const daemon = await startTestDaemon({ port: 0 });
+try {
+  assert(daemon.port > 0, "the helper returns the port the daemon actually bound");
+  assert.equal(daemon.wsUrl, `ws://127.0.0.1:${daemon.port}`);
+  const result = await runPaseoCli(daemon, ["agent", "ls", "--host", daemon.wsUrl, "--json"]);
+  assert.equal(result.exitCode, 0, result.stderr);
+  assert.deepEqual(JSON.parse(result.stdout), []);
+} finally {
+  await daemon.stop();
+}
diff --git a/packages/cli/tests/45-daemon-terminals-survive.test.ts b/packages/cli/tests/45-daemon-terminals-survive.test.ts
new file mode 100644
index 0000000000..7804ea6917
--- /dev/null
+++ b/packages/cli/tests/45-daemon-terminals-survive.test.ts
@@ -0,0 +1,324 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * Terminals survive `paseo daemon restart` and `stop --keep-terminals`; `restart
+ * --kill-terminals`, `stop` and `stop --force` close them. Runs the built CLI and daemon in a
+ * throwaway home; every process it starts is stopped in `finally`.
+ */
+
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtemp, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readDaemonInstance } from "@getpaseo/server/daemon-control";
+import { runLocalPaseo } from "./helpers/local-cli.ts";
+import { getAvailablePort } from "./helpers/network.ts";
+
+if (process.platform === "win32") {
+  console.log("Skipping terminal survival CLI test on Windows (POSIX shell terminals).");
+  process.exit(0);
+}
+
+console.log("=== Daemon terminals survive restart ===\n");
+
+const paseoHome = await mkdtemp(join(tmpdir(), "paseo-terminals-survive-"));
+const workDir = join(paseoHome, "work");
+await mkdir(workDir, { recursive: true });
+const port = await getAvailablePort();
+const env = {
+  PASEO_HOME: paseoHome,
+  PASEO_LOCAL_SPEECH_AUTO_DOWNLOAD: "0",
+  PASEO_DICTATION_ENABLED: "0",
+  PASEO_VOICE_MODE_ENABLED: "0",
+  // The daemon inherits this; terminals then run a plain POSIX shell with no startup files.
+  SHELL: "/bin/sh",
+};
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitFor<T>(
+  probe: () => Promise<T | null | false> | T | null | false,
+  message: string,
+  timeoutMs = 30_000,
+): Promise<T> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const value = await probe();
+    if (value) return value;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(message);
+}
+
+async function paseo(args: string[], expectSuccess = true) {
+  const result = await runLocalPaseo(args, env);
+  if (expectSuccess) {
+    assert.equal(
+      result.exitCode,
+      0,
+      `paseo ${args.join(" ")} failed:\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+  return result;
+}
+
+async function json<T>(args: string[]): Promise<T> {
+  return JSON.parse((await paseo([...args, "--json"])).stdout) as T;
+}
+
+async function capture(terminalId: string): Promise<string> {
+  const { lines } = await json<{ lines: string[] }>(["terminal", "capture", terminalId]);
+  return lines.join("\n");
+}
+
+async function waitForScreen(terminalId: string, text: string): Promise<void> {
+  await waitFor(
+    async () => (await capture(terminalId)).includes(text),
+    `terminal ${terminalId} never showed ${text}:\n${await capture(terminalId)}`,
+  );
+}
+
+async function terminalIds(): Promise<string[]> {
+  return (await json<Array<{ id: string }>>(["terminal", "ls", "--all"])).map((t) => t.id);
+}
+
+// Worker records and the cleanup records a kill that could not finish leaves beside them.
+function workerRecordCount(): number {
+  const dir = join(paseoHome, "terminal-worker");
+  return existsSync(dir)
+    ? readdirSync(dir).filter((name) => /^(\d+|closing-.+)\.json$/.test(name)).length
+    : 0;
+}
+
+// A shell terminal that reports its pid and prints a marker.
+async function openTerminal(name: string): Promise<{ id: string; pid: number }> {
+  const terminal = await json<{ id: string }>([
+    "terminal",
+    "create",
+    "--cwd",
+    workDir,
+    "--name",
+    name,
+  ]);
+  const pidFile = join(workDir, `${name}.pid`);
+  await paseo([
+    "terminal",
+    "send-keys",
+    terminal.id,
+    "-l",
+    `echo $$ > '${pidFile}'; echo MARKER-${name}`,
+  ]);
+  await paseo(["terminal", "send-keys", terminal.id, "Enter"]);
+  const pid = await waitFor(
+    () =>
+      existsSync(pidFile) && readFileSync(pidFile, "utf8").trim()
+        ? Number(readFileSync(pidFile, "utf8"))
+        : null,
+    `terminal ${name} never wrote its pid`,
+  );
+  await waitForScreen(terminal.id, `MARKER-${name}`);
+  return { id: terminal.id, pid };
+}
+
+async function expectKept(terminal: { id: string; pid: number }, name: string, trigger: string) {
+  assert((await terminalIds()).includes(terminal.id), `${trigger}: terminal is still listed`);
+  assert(isAlive(terminal.pid), `${trigger}: terminal program is still alive`);
+  assert((await capture(terminal.id)).includes(`MARKER-${name}`), `${trigger}: marker is kept`);
+  await paseo(["terminal", "send-keys", terminal.id, "-l", `echo after-${trigger}`]);
+  await paseo(["terminal", "send-keys", terminal.id, "Enter"]);
+  await waitForScreen(terminal.id, `\nafter-${trigger}`);
+}
+
+async function expectClosed(pid: number, trigger: string) {
+  await waitFor(() => !isAlive(pid), `${trigger}: terminal program ${pid} is still alive`, 15_000);
+}
+
+// A zombie: a real process with a birth time that SIGKILL cannot remove while its parent (an
+// exec'd `sleep` that never waits) lives. Cleanup can only report it as still alive.
+async function startZombie(): Promise<{ zombiePid: number; parentPid: number }> {
+  const parent = spawn("/bin/sh", ["-c", "sleep 0 & echo $!; exec sleep 600"], {
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const zombiePid = await new Promise<number>((resolve) => {
+    parent.stdout!.once("data", (chunk: Buffer) => resolve(Number(chunk.toString().trim())));
+  });
+  parent.unref();
+  await waitFor(
+    async () => (await psField(zombiePid, "stat")).startsWith("Z"),
+    `process ${zombiePid} never became a zombie`,
+  );
+  return { zombiePid, parentPid: parent.pid! };
+}
+
+async function psField(pid: number, field: "stat" | "lstart"): Promise<string> {
+  const child = spawn("ps", ["-o", `${field}=`, "-p", String(pid)], {
+    env: { ...process.env, LC_ALL: "C" },
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  let out = "";
+  child.stdout.on("data", (chunk: Buffer) => (out += chunk.toString()));
+  await new Promise((resolve) => child.once("close", resolve));
+  return out.trim();
+}
+
+async function goneProcessPid(): Promise<number> {
+  const child = spawn(process.execPath, ["-e", ""], { stdio: "ignore" });
+  await new Promise((resolve) => child.once("exit", resolve));
+  return child.pid!;
+}
+
+// A record as a dead terminal worker leaves it, naming one terminal program that is a zombie.
+async function plantRecordNaming(programPid: number): Promise<void> {
+  const workerPid = await goneProcessPid();
+  const record = {
+    recordId: "planted-record",
+    pid: workerPid,
+    bootId: null,
+    createdAt: new Date().toISOString(),
+    identity: { startedAt: "Thu Jan  1 00:00:00 1970", commandLine: "planted-worker" },
+    protocolVersion: 1,
+    paseoVersion: "0.0.0-test",
+    socketPath: join(paseoHome, "planted-worker.sock"),
+    secret: "planted-secret",
+    terminals: [
+      { id: "planted-terminal", pid: programPid, startedAt: await psField(programPid, "lstart") },
+    ],
+  };
+  writeFileSync(
+    join(paseoHome, "terminal-worker", `${workerPid}.json`),
+    `${JSON.stringify(record, null, 2)}\n`,
+    { mode: 0o600 },
+  );
+}
+
+const trackedPids: number[] = [];
+
+try {
+  for (const [field, value] of [
+    ["daemon.listen", `127.0.0.1:${port}`],
+    ["daemon.relay.enabled", "false"],
+    ["features.dictation.enabled", "false"],
+    ["features.voiceMode.enabled", "false"],
+  ] as const) {
+    await paseo(["daemon", "config", "set", field, value]);
+  }
+  await paseo(["daemon", "start"]);
+
+  console.log("Test 1: daemon restart keeps the terminal");
+  const kept = await openTerminal("kept");
+  trackedPids.push(kept.pid);
+  await paseo(["daemon", "restart", "--home", paseoHome]);
+  await expectKept(kept, "kept", "restart");
+  console.log("✓ same id, same program, marker and input after restart\n");
+
+  console.log("Test 2: stop --keep-terminals, then start, gives the terminal back");
+  const forceAndKeep = await paseo(
+    ["daemon", "stop", "--home", paseoHome, "--force", "--keep-terminals"],
+    false,
+  );
+  assert.notEqual(forceAndKeep.exitCode, 0, "--force with --keep-terminals is refused");
+  await paseo(["daemon", "stop", "--home", paseoHome, "--keep-terminals"]);
+  assert.equal(await readDaemonInstance(paseoHome), null, "the supervisor stopped");
+  assert(isAlive(kept.pid), "the program outlives the stopped daemon");
+  await paseo(["daemon", "start"]);
+  await expectKept(kept, "kept", "keep-stop");
+  console.log("✓ adopted with the same id and still usable\n");
+
+  console.log("Test 3: a plain stop with no daemon running closes kept terminals");
+  await paseo(["daemon", "stop", "--home", paseoHome, "--keep-terminals"]);
+  assert(isAlive(kept.pid), "kept again");
+  await paseo(["daemon", "stop", "--home", paseoHome]);
+  await expectClosed(kept.pid, "stop without a supervisor");
+  assert.equal(workerRecordCount(), 0, "no worker record is left");
+  console.log("✓ closed\n");
+
+  console.log("Test 4: restart --kill-terminals closes the terminal");
+  await paseo(["daemon", "start"]);
+  const killedByRestart = await openTerminal("restart-kill");
+  trackedPids.push(killedByRestart.pid);
+  await paseo(["daemon", "restart", "--home", paseoHome, "--kill-terminals"]);
+  await expectClosed(killedByRestart.pid, "restart --kill-terminals");
+  assert.deepEqual(await terminalIds(), [], "no terminal is listed after the kill restart");
+  console.log("✓ closed\n");
+
+  console.log("Test 5: daemon stop closes the terminal and its worker");
+  const killedByStop = await openTerminal("stop-kill");
+  trackedPids.push(killedByStop.pid);
+  await paseo(["daemon", "stop", "--home", paseoHome]);
+  await expectClosed(killedByStop.pid, "stop");
+  assert.equal(workerRecordCount(), 0, "no worker record is left");
+  console.log("✓ closed\n");
+
+  console.log("Test 6: daemon stop --force closes the terminal");
+  await paseo(["daemon", "start"]);
+  const killedByForce = await openTerminal("force-kill");
+  trackedPids.push(killedByForce.pid);
+  await paseo(["daemon", "stop", "--home", paseoHome, "--force"]);
+  await expectClosed(killedByForce.pid, "stop --force");
+  assert.equal(workerRecordCount(), 0, "no worker record is left");
+  console.log("✓ closed\n");
+
+  const endpoint = `127.0.0.1:${port}`;
+  console.log("Test 7: restart --host --kill-terminals closes the terminal");
+  await paseo(["daemon", "start"]);
+  const killedByEndpointRestart = await openTerminal("endpoint-restart-kill");
+  trackedPids.push(killedByEndpointRestart.pid);
+  await paseo(["daemon", "restart", "--host", endpoint, "--kill-terminals"]);
+  await expectClosed(killedByEndpointRestart.pid, "restart --host --kill-terminals");
+  assert.deepEqual(await terminalIds(), [], "no terminal is listed after the kill restart");
+  console.log("✓ closed and confirmed by the replacement\n");
+
+  console.log("Test 8: restart --host --kill-terminals reports a process cleanup could not end");
+  const zombie = await startZombie();
+  trackedPids.push(zombie.parentPid);
+  await plantRecordNaming(zombie.zombiePid);
+  const unconfirmed = await paseo(
+    ["daemon", "restart", "--host", endpoint, "--kill-terminals"],
+    false,
+  );
+  assert.notEqual(unconfirmed.exitCode, 0, "the kill restart fails");
+  const output = unconfirmed.stdout + unconfirmed.stderr;
+  assert(output.includes("Terminal cleanup was not confirmed"), `names the failure:\n${output}`);
+  assert(output.includes(`pid ${zombie.zombiePid}`), `names the surviving pid:\n${output}`);
+  process.kill(zombie.parentPid, "SIGKILL");
+  await expectClosed(zombie.zombiePid, "zombie reaped once its parent exits");
+  await paseo(["daemon", "stop", "--home", paseoHome]);
+  assert.equal(workerRecordCount(), 0, "the next stop retries the cleanup and retires the record");
+  console.log("✓ reported, then retried by stop\n");
+
+  console.log("Test 9: restart --host --kill-terminals reports a worker record it cannot read");
+  await paseo(["daemon", "start"]);
+  // A kill cleanup cannot check what an unreadable record names, and leaves nothing else
+  // behind, so the replacement daemon must still report it.
+  const unreadablePath = join(paseoHome, "terminal-worker", `${await goneProcessPid()}.json`);
+  writeFileSync(unreadablePath, "{ not json", { mode: 0o600 });
+  const unreadable = await paseo(
+    ["daemon", "restart", "--host", endpoint, "--kill-terminals"],
+    false,
+  );
+  assert.notEqual(unreadable.exitCode, 0, "the kill restart fails");
+  const unreadableOutput = unreadable.stdout + unreadable.stderr;
+  assert(unreadableOutput.includes(unreadablePath), `names the record:\n${unreadableOutput}`);
+  assert(existsSync(unreadablePath), "the unreadable record is kept");
+  rmSync(unreadablePath);
+  await paseo(["daemon", "stop", "--home", paseoHome]);
+  assert.equal(workerRecordCount(), 0, "no worker record is left");
+  console.log("✓ reported with the record's path\n");
+} finally {
+  await runLocalPaseo(["daemon", "stop", "--home", paseoHome, "--force"], env);
+  for (const pid of trackedPids) {
+    if (isAlive(pid)) process.kill(pid, "SIGKILL");
+  }
+  await rm(paseoHome, { recursive: true, force: true });
+}
+
+console.log("=== Daemon terminals survive restart passed ===");
diff --git a/packages/cli/tests/46-daemon-terminal-worker-upgrade.test.ts b/packages/cli/tests/46-daemon-terminal-worker-upgrade.test.ts
new file mode 100644
index 0000000000..9090456406
--- /dev/null
+++ b/packages/cli/tests/46-daemon-terminal-worker-upgrade.test.ts
@@ -0,0 +1,561 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * A terminal worker survives an upgrade of the installation that started it. Two disposable
+ * installations A and B (built dist, real copies of @getpaseo/server, @getpaseo/cli and
+ * node-pty, every other dependency a symlink into this repo) each get their own CLI shim, so
+ * each daemon's PASEO_CLI is a distinct path:
+ *
+ * 1. A daemon from A runs its worker from a copy in $PASEO_HOME/terminal-worker/. After
+ *    `stop --keep-terminals` and moving A's node-pty, worker bundle and shell integration away,
+ *    a daemon from B adopts the same worker and opens a new, working terminal in it with B's
+ *    environment and CLI, while the first terminal keeps A's.
+ * 2. Worker protocol versions (PASEO_TERMINAL_WORKER_PROTOCOL_OVERRIDE): protocols 0–4
+ *    are obsolete unreleased wires, so their programs/workers/copies are closed and a current
+ *    worker serves new terminals. A truly newer protocol is left running, reported as
+ *    terminal_worker_incompatible, and closed by `daemon stop`.
+ *
+ * Every process it starts is stopped in `finally`.
+ */
+
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createServer } from "node:net";
+
+if (process.platform === "win32") {
+  console.log("Skipping terminal worker upgrade CLI test on Windows (POSIX shell terminals).");
+  process.exit(0);
+}
+
+console.log("=== Terminal worker survives an upgrade ===\n");
+
+const repoRoot = join(import.meta.dirname, "..", "..", "..");
+const root = await mkdtemp(join(tmpdir(), "paseo-worker-upgrade-"));
+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 zsh = ["/bin/zsh", "/usr/bin/zsh"].find((candidate) => existsSync(candidate)) ?? null;
+
+interface Installation {
+  name: string;
+  dir: string;
+  version: string;
+  shim: string;
+  serverDir: string;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Installation fixtures
+// ---------------------------------------------------------------------------------------------
+
+function linkEntries(source: string, target: string, taken: Set<string>): void {
+  if (!existsSync(source)) return;
+  for (const name of readdirSync(source)) {
+    if (name.startsWith(".")) continue;
+    if (name.startsWith("@")) {
+      mkdirSync(join(target, name), { recursive: true });
+      for (const scoped of readdirSync(join(source, name))) {
+        const key = `${name}/${scoped}`;
+        if (taken.has(key)) continue;
+        taken.add(key);
+        symlinkSync(join(source, name, scoped), join(target, name, scoped));
+      }
+      continue;
+    }
+    if (taken.has(name)) continue;
+    taken.add(name);
+    symlinkSync(join(source, name), join(target, name));
+  }
+}
+
+function createInstallation(name: string, version: string): Installation {
+  const dir = join(root, `install-${name}`);
+  const modules = join(dir, "node_modules");
+  mkdirSync(join(modules, "@getpaseo"), { recursive: true });
+
+  // Real copies: the server (its version marks the installation), the CLI (so it resolves this
+  // installation's server), and node-pty (so moving it away breaks only this installation).
+  const serverDir = join(modules, "@getpaseo", "server");
+  const serverPackage = JSON.parse(
+    readFileSync(join(repoRoot, "packages/server/package.json"), "utf8"),
+  ) as Record<string, unknown>;
+  mkdirSync(join(serverDir, "dist"), { recursive: true });
+  writeFileSync(
+    join(serverDir, "package.json"),
+    `${JSON.stringify({ ...serverPackage, version }, null, 2)}\n`,
+  );
+  for (const part of ["server", "src", "scripts"]) {
+    cpSync(join(repoRoot, "packages/server/dist", part), join(serverDir, "dist", part), {
+      recursive: true,
+    });
+  }
+  const cliDir = join(modules, "@getpaseo", "cli");
+  mkdirSync(cliDir, { recursive: true });
+  cpSync(join(repoRoot, "packages/cli/package.json"), join(cliDir, "package.json"));
+  cpSync(join(repoRoot, "packages/cli/dist"), join(cliDir, "dist"), { recursive: true });
+  cpSync(join(repoRoot, "packages/server/node_modules/node-pty"), join(modules, "node-pty"), {
+    recursive: true,
+  });
+
+  const taken = new Set(["@getpaseo/server", "@getpaseo/cli", "node-pty"]);
+  for (const source of [
+    "packages/server/node_modules",
+    "packages/cli/node_modules",
+    "node_modules",
+  ]) {
+    linkEntries(join(repoRoot, source), modules, taken);
+  }
+
+  const shim = join(dir, "bin", "paseo");
+  mkdirSync(join(dir, "bin"));
+  writeFileSync(
+    shim,
+    `#!/bin/sh\nexec "${process.execPath}" "${join(cliDir, "dist", "index.js")}" "$@"\n`,
+  );
+  chmodSync(shim, 0o755);
+  return { name, dir, version, shim, serverDir };
+}
+
+// The runtime files an upgrade replaces: node-pty, the worker bundle, the shell integration.
+function moveRuntimeAway(installation: Installation): () => void {
+  const away = join(installation.dir, "moved-away");
+  const moves = [
+    join(installation.dir, "node_modules", "node-pty"),
+    join(installation.serverDir, "dist", "server", "terminal-worker"),
+    join(installation.serverDir, "dist", "server", "terminal", "shell-integration"),
+  ].map((from, index) => ({ from, to: join(away, String(index)) }));
+  mkdirSync(away, { recursive: true });
+  for (const move of moves) renameSync(move.from, move.to);
+  return () => {
+    for (const move of moves) renameSync(move.to, move.from);
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------------------------
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitFor<T>(
+  probe: () => Promise<T | null | false> | T | null | false,
+  message: () => string | Promise<string>,
+  timeoutMs = 30_000,
+): Promise<T> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const value = await probe();
+    if (value) return value;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(await message());
+}
+
+interface RunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+function run(
+  installation: Installation,
+  args: string[],
+  extraEnv: Record<string, string> = {},
+): Promise<RunResult> {
+  const env = {
+    ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("PASEO_"))),
+    HOME: cliHome,
+    USERPROFILE: cliHome,
+    PASEO_HOME: paseoHome,
+    PASEO_LOCAL_SPEECH_AUTO_DOWNLOAD: "0",
+    PASEO_DICTATION_ENABLED: "0",
+    PASEO_VOICE_MODE_ENABLED: "0",
+    // Each daemon hands its terminals its own installation's CLI.
+    PASEO_CLI: installation.shim,
+    PASEO_TEST_INSTALL: installation.name,
+    SHELL: "/bin/sh",
+    ...extraEnv,
+  };
+  return new Promise((resolve) => {
+    execFile(installation.shim, args, { env, timeout: 120_000 }, (error, stdout, stderr) => {
+      let exitCode = 0;
+      if (error) exitCode = typeof error.code === "number" ? error.code : 1;
+      resolve({ exitCode, stdout, stderr });
+    });
+  });
+}
+
+async function paseo(
+  installation: Installation,
+  args: string[],
+  extraEnv: Record<string, string> = {},
+): Promise<RunResult> {
+  const result = await run(installation, args, extraEnv);
+  assert.equal(
+    result.exitCode,
+    0,
+    `paseo ${args.join(" ")} (${installation.name}) failed:\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+  );
+  return result;
+}
+
+async function json<T>(installation: Installation, args: string[]): Promise<T> {
+  return JSON.parse((await paseo(installation, [...args, "--json"])).stdout) as T;
+}
+
+async function capture(installation: Installation, terminalId: string): Promise<string> {
+  const { lines } = await json<{ lines: string[] }>(installation, [
+    "terminal",
+    "capture",
+    terminalId,
+  ]);
+  return lines.join("\n");
+}
+
+async function type(installation: Installation, terminalId: string, line: string) {
+  await paseo(installation, ["terminal", "send-keys", terminalId, "-l", line]);
+  await paseo(installation, ["terminal", "send-keys", terminalId, "Enter"]);
+}
+
+async function waitForScreen(installation: Installation, terminalId: string, text: string) {
+  await waitFor(
+    async () => (await capture(installation, terminalId)).includes(text),
+    async () =>
+      `terminal ${terminalId} never showed ${text}:\n${await capture(installation, terminalId)}`,
+  );
+}
+
+// Opens a terminal, records its shell's pid, and prints a marker.
+async function openTerminal(
+  installation: Installation,
+  name: string,
+): Promise<{ id: string; pid: number }> {
+  const terminal = await json<{ id: string }>(installation, [
+    "terminal",
+    "create",
+    "--cwd",
+    workDir,
+    "--name",
+    name,
+  ]);
+  const pidFile = join(workDir, `${name}.pid`);
+  await type(installation, terminal.id, `echo $$ > '${pidFile}'; echo MARKER-${name}`);
+  const pid = await waitFor(
+    () =>
+      existsSync(pidFile) && readFileSync(pidFile, "utf8").trim()
+        ? Number(readFileSync(pidFile, "utf8"))
+        : null,
+    () => `terminal ${name} never wrote its pid`,
+  );
+  await waitForScreen(installation, terminal.id, `MARKER-${name}`);
+  trackedPids.push(pid);
+  return { id: terminal.id, pid };
+}
+
+// The value of `$variable` in the terminal's shell, written to a file (a long path would wrap
+// on screen).
+async function echoVariable(
+  installation: Installation,
+  terminalId: string,
+  label: string,
+  variable: string,
+): Promise<string> {
+  const valueFile = join(workDir, `${label}.value`);
+  await type(
+    installation,
+    terminalId,
+    `printf '%s' "$${variable}" > '${valueFile}.tmp' && mv '${valueFile}.tmp' '${valueFile}'`,
+  );
+  await waitFor(
+    () => existsSync(valueFile),
+    async () =>
+      `terminal ${terminalId} never wrote ${label}:\n${await capture(installation, terminalId)}`,
+  );
+  return readFileSync(valueFile, "utf8");
+}
+
+interface WorkerRecordFile {
+  pid: number;
+  protocolVersion: unknown;
+  runtime?: string | null;
+  terminals: Array<{ id: string; pid: number }>;
+}
+
+function workerRecords(): WorkerRecordFile[] {
+  const dir = join(paseoHome, "terminal-worker");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => /^\d+\.json$/.test(name))
+    .map((name) => JSON.parse(readFileSync(join(dir, name), "utf8")) as WorkerRecordFile);
+}
+
+function runtimeCopies(): string[] {
+  const dir = join(paseoHome, "terminal-worker");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((name) =>
+    existsSync(join(dir, name, "paseo-terminal-worker-runtime.json")),
+  );
+}
+
+function commandLineOf(pid: number): Promise<string> {
+  return new Promise((resolve) => {
+    execFile("ps", ["-ww", "-o", "command=", "-p", String(pid)], (_error, stdout) =>
+      resolve(stdout.trim()),
+    );
+  });
+}
+
+async function terminalIds(installation: Installation): Promise<string[]> {
+  return (await json<Array<{ id: string }>>(installation, ["terminal", "ls", "--all"])).map(
+    (terminal) => terminal.id,
+  );
+}
+
+async function startDaemon(installation: Installation, extraEnv: Record<string, string> = {}) {
+  const result = await paseo(installation, ["daemon", "start", "--json"], extraEnv);
+  lastListen = (JSON.parse(result.stdout) as { listen: string }).listen;
+  assert.match(lastListen, /^127\.0\.0\.1:[1-9]\d*$/, "start publishes the actual bound port");
+  if (competingListener.listening) {
+    const competitor = competingListener.address();
+    assert(competitor && typeof competitor !== "string");
+    assert.notEqual(
+      Number(lastListen.split(":").at(-1)),
+      competitor.port,
+      "each daemon binds its own endpoint while the released port belongs to a peer",
+    );
+  }
+}
+
+async function stopDaemon(installation: Installation, keepTerminals = false) {
+  await paseo(installation, [
+    "daemon",
+    "stop",
+    "--home",
+    paseoHome,
+    ...(keepTerminals ? ["--keep-terminals"] : []),
+  ]);
+}
+
+// A terminal in a worker reporting `protocolVersion`, left running by `stop --keep-terminals`.
+async function leaveWorkerWithProtocol(
+  installation: Installation,
+  protocolVersion: number,
+  name: string,
+): Promise<{ terminal: { id: string; pid: number }; workerPid: number; runtime: string }> {
+  await startDaemon(installation, {
+    PASEO_TERMINAL_WORKER_PROTOCOL_OVERRIDE: String(protocolVersion),
+  });
+  const terminal = await openTerminal(installation, name);
+  const [worker] = workerRecords();
+  assert(worker, "the daemon started a worker");
+  assert.equal(worker.protocolVersion, protocolVersion, "the worker reports the override");
+  await stopDaemon(installation, true);
+  return { terminal, workerPid: worker.pid, runtime: worker.runtime! };
+}
+
+const trackedPids: number[] = [];
+const a = createInstallation("A", "0.98.0");
+const b = createInstallation("B", "0.99.0");
+let restoreA: (() => void) | null = null;
+let passed = false;
+let lastListen = "";
+const competingListener = createServer();
+
+try {
+  for (const [field, value] of [
+    // Let the listening daemon reserve its port atomically. Clients discover the
+    // actual endpoint from this home's PID record after every start.
+    ["daemon.listen", "127.0.0.1:0"],
+    ["daemon.relay.enabled", "false"],
+    ["features.dictation.enabled", "false"],
+    ["features.voiceMode.enabled", "false"],
+  ] as const) {
+    await paseo(a, ["daemon", "config", "set", field, value]);
+  }
+
+  console.log("Test 1: a daemon from A runs its worker from a copy in the home");
+  await startDaemon(a);
+  const t1 = await openTerminal(a, "t1");
+  const [firstWorker] = workerRecords();
+  assert(firstWorker, "one worker runs");
+  assert.equal(firstWorker.protocolVersion, currentProtocolVersion, "the current wire is adopted");
+  assert.match(firstWorker.runtime ?? "", /^0\.98\.0-[0-9a-f]{12}$/);
+  const copyA = join(paseoHome, "terminal-worker", firstWorker.runtime!);
+  assert(
+    (await commandLineOf(firstWorker.pid)).includes(join(copyA, "terminal-worker.mjs")),
+    "the worker runs the copy's bundle",
+  );
+  assert.equal(await echoVariable(a, t1.id, "CLI1", "PASEO_CLI"), a.shim, "T1 has A's CLI");
+  console.log("✓ worker runs from", copyA, "\n");
+
+  console.log("Test 2: B adopts the worker after A's runtime files are gone");
+  await stopDaemon(a, true);
+  restoreA = moveRuntimeAway(a);
+  await startDaemon(b, zsh ? { SHELL: zsh } : {});
+  assert.deepEqual(
+    workerRecords().map((record) => record.pid),
+    [firstWorker.pid],
+    "B adopted the same worker instead of starting one",
+  );
+  assert((await terminalIds(b)).includes(t1.id), "T1 is listed by B");
+  const t2 = await openTerminal(b, "t2");
+  assert.equal(await echoVariable(b, t2.id, "INSTALL2", "PASEO_TEST_INSTALL"), "B");
+  assert.equal(await echoVariable(b, t2.id, "CLI2", "PASEO_CLI"), b.shim, "T2 has B's CLI");
+  if (zsh) {
+    // Creating a zsh terminal reads Paseo's integration from the worker's copy (A's is gone);
+    // a missing file would have failed the create.
+    const zshVersion = await echoVariable(b, t2.id, "ZSH", "ZSH_VERSION");
+    assert(zshVersion.length > 0, "T2 runs zsh with Paseo's shell integration");
+  } else {
+    console.log("  (zsh is not installed: the shell-integration check is skipped)");
+  }
+  assert.equal(await echoVariable(b, t1.id, "CLI1AGAIN", "PASEO_CLI"), a.shim, "T1 keeps A's CLI");
+  console.log("✓ same worker, T2 uses B's environment, T1 still works\n");
+
+  console.log("Test 3: daemon stop closes both terminals and deletes the copy");
+  await stopDaemon(b);
+  await waitFor(
+    () => !isAlive(t1.pid) && !isAlive(t2.pid) && !isAlive(firstWorker.pid),
+    () => "terminals or worker outlived daemon stop",
+  );
+  assert.deepEqual(workerRecords(), [], "no worker record is left");
+  assert.deepEqual(runtimeCopies(), [], "no copy is left");
+  restoreA();
+  restoreA = null;
+  console.log("✓ closed and cleaned up\n");
+
+  // A released endpoint belongs to nobody. Reproduce another process taking it
+  // between starts; worker adoption is keyed by the home, not by a stable TCP port.
+  const releasedPort = Number(lastListen.split(":").at(-1));
+  await new Promise<void>((resolve, reject) => {
+    competingListener.once("error", reject);
+    competingListener.listen(releasedPort, "127.0.0.1", resolve);
+  });
+  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.
+  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(
+      a,
+      protocolVersion,
+      `obsolete-${protocolVersion}`,
+    );
+    await startDaemon(b);
+    await waitFor(
+      () => !isAlive(obsolete.workerPid) && !isAlive(obsolete.terminal.pid),
+      () => "the obsolete worker or its terminal survived",
+    );
+    assert(!(await terminalIds(b)).includes(obsolete.terminal.id), "its terminal is gone");
+    const [current] = workerRecords();
+    assert.equal(workerRecords().length, 1, "one current worker runs");
+    assert(current);
+    assert.equal(current.protocolVersion, currentProtocolVersion);
+    assert.match(current.runtime ?? "", /^0\.99\.0-/);
+    await waitFor(
+      () => !runtimeCopies().includes(obsolete.runtime),
+      () => `the obsolete worker's copy ${obsolete.runtime} was not deleted`,
+    );
+    assert.deepEqual(runtimeCopies(), [current.runtime], "the current copy stays");
+    const replacement = await openTerminal(b, `replacement-${protocolVersion}`);
+    assert.deepEqual(
+      workerRecords()
+        .find((record) => record.pid === current.pid)!
+        .terminals.map((terminal) => terminal.id),
+      [replacement.id],
+      "new terminals open in the current worker",
+    );
+    await type(b, replacement.id, `echo after-protocol-cut-${protocolVersion}`);
+    await waitForScreen(b, replacement.id, `\nafter-protocol-cut-${protocolVersion}`);
+    await stopDaemon(b);
+    await waitFor(
+      () => !isAlive(replacement.pid) && !isAlive(current.pid),
+      () => "the replacement worker or program outlived daemon stop",
+    );
+    assert.deepEqual(workerRecords(), [], "no worker record is left");
+    assert.deepEqual(runtimeCopies(), [], "no copy is left");
+    console.log("✓ obsolete closed, current usable, copies cleaned up\n");
+  }
+
+  console.log("Test 5: a worker from a newer Paseo is left running and reported");
+  const newer = await leaveWorkerWithProtocol(a, currentProtocolVersion + 1, "newer");
+  await startDaemon(b);
+  const listed = await run(b, ["terminal", "ls", "--all", "--json"]);
+  assert.notEqual(listed.exitCode, 0, "terminal ls fails");
+  assert.match(listed.stdout + listed.stderr, /held by a newer Paseo \(v0\.98\.0/);
+  const created = await run(b, ["terminal", "create", "--cwd", workDir, "--json"]);
+  assert.notEqual(created.exitCode, 0, "terminal create fails");
+  assert.match(created.stdout + created.stderr, /held by a newer Paseo/);
+  const status = await paseo(b, ["daemon", "status", "--home", paseoHome]);
+  assert.match(status.stdout, /terminals: Terminals are held by a newer Paseo/);
+  assert(isAlive(newer.terminal.pid), "its program keeps running");
+  assert.deepEqual(
+    workerRecords().map((record) => record.pid),
+    [newer.workerPid],
+    "no second worker starts",
+  );
+  await stopDaemon(b);
+  await waitFor(
+    () => !isAlive(newer.workerPid) && !isAlive(newer.terminal.pid),
+    () => "daemon stop left the newer worker or its terminal running",
+  );
+  assert.deepEqual(workerRecords(), [], "no worker record is left");
+  assert.deepEqual(runtimeCopies(), [], "no copy is left");
+  console.log("✓ reported, untouched, closed by stop\n");
+  passed = true;
+} finally {
+  if (!passed) {
+    for (const log of ["daemon.log", "terminal-worker.log"]) {
+      const logPath = join(paseoHome, log);
+      if (existsSync(logPath)) {
+        console.error(`--- ${log} (last 60 lines) ---`);
+        console.error(readFileSync(logPath, "utf8").split("\n").slice(-60).join("\n"));
+      }
+    }
+  }
+  if (competingListener.listening) {
+    await new Promise<void>((resolve, reject) =>
+      competingListener.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      }),
+    );
+  }
+  restoreA?.();
+  for (const installation of [b, a]) {
+    await run(installation, ["daemon", "stop", "--home", paseoHome, "--force"]);
+  }
+  for (const pid of trackedPids) {
+    if (isAlive(pid)) process.kill(pid, "SIGKILL");
+  }
+  await rm(root, { recursive: true, force: true });
+}
+
+console.log("=== Terminal worker survives an upgrade passed ===");
diff --git a/packages/cli/tests/helpers/test-daemon.ts b/packages/cli/tests/helpers/test-daemon.ts
index 5b5513d1a7..cfc9a87fb1 100644
--- a/packages/cli/tests/helpers/test-daemon.ts
+++ b/packages/cli/tests/helpers/test-daemon.ts
@@ -18,7 +18,7 @@ import { tmpdir } from "os";
 import { join } from "path";
 import { fileURLToPath } from "url";
 import { ChildProcess, spawn } from "child_process";
-import { getAvailablePort } from "./network.ts";
+import { readDaemonInstance } from "@getpaseo/server/daemon-control";
 
 export interface TestDaemonContext {
   /** Available local port for test daemon (never 6767) */
@@ -195,17 +195,20 @@ async function probeDaemonReady(
 }
 
 async function waitForDaemonReady(
-  port: number,
   paseoHome: string,
   timeout = 30000,
   env?: NodeJS.ProcessEnv,
-): Promise<void> {
+): Promise<number> {
   const deadline = Date.now() + timeout;
 
-  async function poll(): Promise<void> {
-    if (await probeDaemonReady(port, paseoHome, env)) return;
+  async function poll(): Promise<number> {
+    const instance = await readDaemonInstance(paseoHome);
+    if (instance?.listen) {
+      const port = Number(new URL(`http://${instance.listen}`).port);
+      if (await probeDaemonReady(port, paseoHome, env)) return port;
+    }
     if (Date.now() >= deadline) {
-      throw new Error(`Daemon failed to become ready on port ${port} within ${timeout}ms`);
+      throw new Error(`Daemon failed to publish a ready endpoint within ${timeout}ms`);
     }
     await sleep(100);
     return poll();
@@ -231,15 +234,14 @@ export async function startTestDaemon(options?: {
   timeout?: number;
   env?: NodeJS.ProcessEnv;
 }): Promise<TestDaemonContext> {
-  const port = options?.port ?? (await getAvailablePort());
+  // Let the listening process allocate its port, without a reserve/release race.
+  const requestedPort = options?.port ?? 0;
   const { paseoHome, workDir } =
     options?.paseoHome && options?.workDir
       ? { paseoHome: options.paseoHome, workDir: options.workDir }
       : await createTempDirs();
   const timeout = options?.timeout ?? 30000;
 
-  const wsUrl = `ws://${TEST_DAEMON_HOST}:${port}`;
-
   // Find the CLI entry point - use the source file directly with tsx
   const cliDir = join(import.meta.dirname, "..", "..");
   const cliSrcPath = join(cliDir, "src", "index.ts");
@@ -252,7 +254,7 @@ export async function startTestDaemon(options?: {
       ),
       ...TEST_DAEMON_ENV_DEFAULTS,
       PASEO_HOME: paseoHome,
-      PASEO_LISTEN: `${TEST_DAEMON_HOST}:${port}`,
+      PASEO_LISTEN: `${TEST_DAEMON_HOST}:${requestedPort}`,
       // Force no TTY to prevent QR code output
       CI: "true",
       ...options?.env,
@@ -312,20 +314,18 @@ export async function startTestDaemon(options?: {
     }
   });
 
-  const ctx: TestDaemonContext = {
-    port,
-    wsUrl,
-    paseoHome,
-    workDir,
-    process: daemonProcess,
-    isReady: false,
-    stop: cleanup,
-  };
-
   // Wait for daemon to be ready
   try {
-    await waitForDaemonReady(port, paseoHome, timeout, options?.env);
-    ctx.isReady = true;
+    const port = await waitForDaemonReady(paseoHome, timeout, options?.env);
+    return {
+      port,
+      wsUrl: `ws://${TEST_DAEMON_HOST}:${port}`,
+      paseoHome,
+      workDir,
+      process: daemonProcess,
+      isReady: true,
+      stop: cleanup,
+    };
   } catch (err) {
     // Daemon failed to start - clean up and rethrow
     await cleanup();
@@ -335,8 +335,6 @@ export async function startTestDaemon(options?: {
       { cause: err },
     );
   }
-
-  return ctx;
 }
 
 /**
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 df80ba532c..810cb8b0c9 100644
--- a/packages/client/package.json
+++ b/packages/client/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/client",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "description": "Paseo client SDK package",
+  "license": "Apache-2.0",
   "files": [
     "dist",
     "!dist/**/*.map",
@@ -47,8 +48,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@getpaseo/protocol": "0.13.2",
-    "@getpaseo/relay": "0.13.2",
+    "@getpaseo/protocol": "0.15.3",
+    "@getpaseo/relay": "0.15.3",
     "ws": "^8.20.0",
     "zod": "^4.4.3"
   },
diff --git a/packages/client/src/connection/index.ts b/packages/client/src/connection/index.ts
index eda2fec26b..bf2388e663 100644
--- a/packages/client/src/connection/index.ts
+++ b/packages/client/src/connection/index.ts
@@ -125,6 +125,8 @@ export class ConnectionSubscriptions extends OwnedSubscriptions {
 // Protocol support belongs to the installed client. Only browser hosting needs
 // a resource supplied by the caller. Keep this exhaustive as the protocol evolves.
 export const DEFAULT_CLIENT_CAPABILITIES = {
+  [CLIENT_CAPS.terminalChunkedReplay]: true,
+  [CLIENT_CAPS.binaryChunkingV1]: true,
   [CLIENT_CAPS.helloRejection]: true,
   [CLIENT_CAPS.ownedSubscriptions]: true,
   [CLIENT_CAPS.allProviders]: true,
@@ -142,6 +144,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-relay-e2ee-transport.ts b/packages/client/src/daemon-client-relay-e2ee-transport.ts
index 258c0aa9b5..0faecdcb5e 100644
--- a/packages/client/src/daemon-client-relay-e2ee-transport.ts
+++ b/packages/client/src/daemon-client-relay-e2ee-transport.ts
@@ -1,3 +1,4 @@
+import { maxSecuredPlaintextByteLength } from "@getpaseo/relay";
 import { MAX_RELAY_WEBSOCKET_MESSAGE_BYTES } from "@getpaseo/protocol/websocket-message-limit";
 import {
   openClientSecureChannel,
@@ -155,18 +156,15 @@ export function createEncryptedTransport(
   const relayTransport: RelayTransport = {
     send: (data) => {
       if (typeof data === "string") {
-        base.send(data);
-        return;
+        return base.send(data);
       }
       if (ArrayBuffer.isView(data)) {
-        base.send(normalizeTransportPayload(data));
-        return;
+        return base.send(normalizeTransportPayload(data));
       }
       if (data instanceof ArrayBuffer) {
-        base.send(data);
-        return;
+        return base.send(data);
       }
-      base.send(String(data));
+      return base.send(String(data));
     },
     // The channel decides the close code. Report it now: a socket close event
     // arrives asynchronously, and the consumer must not act on an earlier
@@ -226,6 +224,8 @@ export function createEncryptedTransport(
   });
 
   return {
+    supportsDrain: base.supportsDrain,
+    maxFrameBytes: maxSecuredPlaintextByteLength(MAX_RELAY_WEBSOCKET_MESSAGE_BYTES),
     send: (data) => {
       if (!channel) {
         throw new Error("Encrypted channel not ready");
@@ -239,8 +239,9 @@ export function createEncryptedTransport(
       // Encryption and its transport handoff are synchronous up to send's first await.
       // Reject capacity failures here so a routed sender loses only its own channel.
       assertOutboundCapacity(wireBytes);
-      void channel.send(payload).catch((error) => {
+      return channel.send(payload).catch((error) => {
         emitError(error);
+        throw error;
       });
     },
     close: (code?: number, reason?: string) => {
diff --git a/packages/client/src/daemon-client-transport-types.ts b/packages/client/src/daemon-client-transport-types.ts
index ddcb57246b..64f84cf8c1 100644
--- a/packages/client/src/daemon-client-transport-types.ts
+++ b/packages/client/src/daemon-client-transport-types.ts
@@ -1,5 +1,8 @@
 export interface DaemonTransport {
-  send: (data: string | Uint8Array | ArrayBuffer) => void;
+  /** False when the underlying socket cannot report write drain. */
+  supportsDrain?: boolean;
+  maxFrameBytes?: number;
+  send: (data: string | Uint8Array | ArrayBuffer) => void | Promise<void>;
   close: (code?: number, reason?: string) => void;
   onMessage: (handler: (data: unknown, isBinary: boolean) => void) => () => void;
   onOpen: (handler: () => void) => () => void;
@@ -13,12 +16,16 @@ export type DaemonTransportFactory = (options: {
   protocols?: string[];
 }) => DaemonTransport;
 
-export type WebSocketFactory = (
-  url: string,
-  options?: { headers?: Record<string, string>; protocols?: string[] },
-) => WebSocketLike;
+export interface WebSocketFactory {
+  (
+    url: string,
+    options?: { headers?: Record<string, string>; protocols?: string[] },
+  ): WebSocketLike;
+  supportsDrain?: boolean;
+}
 
 export interface WebSocketLike {
+  bufferedAmount?: number;
   readyState: number;
   send: (data: string | Uint8Array | ArrayBuffer) => void;
   close: (code?: number, reason?: string) => void;
diff --git a/packages/client/src/daemon-client-transport.test.ts b/packages/client/src/daemon-client-transport.test.ts
index 963a8b541c..c95c534129 100644
--- a/packages/client/src/daemon-client-transport.test.ts
+++ b/packages/client/src/daemon-client-transport.test.ts
@@ -175,3 +175,18 @@ describe("daemon-client transport helpers", () => {
     expect(decodeMessageData(bytes)).toBe("hello");
   });
 });
+
+test("native drain capability survives WebSocket and encryption wrappers", async () => {
+  const { nativeWebSocketFactory } = await import("./daemon-client-websocket-transport.js");
+  expect(nativeWebSocketFactory.supportsDrain).toBe(false);
+  const factory = Object.assign(() => ({ readyState: 1, send() {}, close() {} }), {
+    supportsDrain: false,
+  });
+  const base = createWebSocketTransportFactory(factory)({ url: "ws://test" });
+  expect(base.supportsDrain).toBe(false);
+  const encrypted = createEncryptedTransport(base, {
+    daemonPublicKeyB64: "unused-key",
+    logger: { warn() {} },
+  });
+  expect(encrypted.supportsDrain).toBe(false);
+});
diff --git a/packages/client/src/daemon-client-websocket-transport.ts b/packages/client/src/daemon-client-websocket-transport.ts
index f5734b4b51..c7ec87555d 100644
--- a/packages/client/src/daemon-client-websocket-transport.ts
+++ b/packages/client/src/daemon-client-websocket-transport.ts
@@ -39,6 +39,9 @@ export function nativeWebSocketFactory(
   return new (getGlobalWebSocket())(url, options?.protocols, { headers: options?.headers });
 }
 
+// React Native leaves bufferedAmount at zero, including while native output is queued.
+nativeWebSocketFactory.supportsDrain = false;
+
 export function createWebSocketTransportFactory(factory: WebSocketFactory): DaemonTransportFactory {
   return ({ url, headers, protocols }) => {
     const ws = factory(url, { headers, protocols });
@@ -50,11 +53,28 @@ export function createWebSocketTransportFactory(factory: WebSocketFactory): Daem
       }
     }
     return {
+      supportsDrain: factory.supportsDrain !== false,
       send: (data) => {
         if (typeof ws.readyState === "number" && ws.readyState !== 1) {
           throw new Error(`WebSocket not open (readyState=${ws.readyState})`);
         }
         ws.send(data);
+        if ((ws.bufferedAmount ?? 0) > 1024 * 1024) {
+          return new Promise<void>((resolve, reject) => {
+            const drain = () => {
+              if (ws.readyState !== 1) {
+                reject(new Error("WebSocket closed while draining"));
+                return;
+              }
+              if ((ws.bufferedAmount ?? 0) <= 1024 * 1024) {
+                resolve();
+                return;
+              }
+              setTimeout(drain, 10);
+            };
+            drain();
+          });
+        }
       },
       close: (code?: number, reason?: string) => {
         // Node's `ws` may emit an `error` when a connecting socket is closed before the
diff --git a/packages/client/src/daemon-client.test.ts b/packages/client/src/daemon-client.test.ts
index f663aeb8be..87719a0a56 100644
--- a/packages/client/src/daemon-client.test.ts
+++ b/packages/client/src/daemon-client.test.ts
@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { afterEach, expect, expectTypeOf, test, vi } from "vitest";
+import { afterEach, describe, expect, expectTypeOf, test, vi } from "vitest";
 import { z } from "zod";
 import {
   DaemonClient,
@@ -9,8 +9,11 @@ import {
   type CreateAgentRequestOptions,
   type DaemonTransport,
   type Logger,
+  type PluginClientBundle,
+  type PluginClientBundleStore,
 } from "./daemon-client";
 import { CLIENT_CAPS } from "@getpaseo/protocol/client-capabilities";
+import { ChunkedTransport } from "@getpaseo/protocol/chunked-transport";
 import { BROWSER_AUTOMATION_COMMAND_NAMES } from "@getpaseo/protocol/browser-automation/rpc-schemas";
 import {
   decodeFileTransferFrame,
@@ -654,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(
@@ -664,6 +699,7 @@ class FakeDaemon {
           payload: {
             status: "server_info",
             serverId: "srv_heartbeat_test",
+            features: { binaryChunkingV1: true },
             hostname: null,
             version: null,
           },
@@ -1092,6 +1128,7 @@ test("advertises client capabilities in hello", async () => {
       provider_snapshot_references: true,
       explicit_event_subscriptions: true,
       owned_subscriptions: true,
+      binary_chunking_v1: true,
       compact_provider_snapshots: true,
       custom_mode_icons: true,
       project_updates: true,
@@ -1099,11 +1136,14 @@ test("advertises client capabilities in hello", async () => {
       projected_subagent_timeline: true,
       reasoning_merge_enum: true,
       terminal_reflowable_snapshot: true,
+      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",
@@ -1640,6 +1680,77 @@ test("preserves legacy fetchAgent id overload", async () => {
   await expect(responsePromise).rejects.toThrow("legacy fetch sentinel");
 });
 
+test.each([undefined, false, true])(
+  "loads history with whole-turn support advertised as %s",
+  async (wholeTurnTimeline) => {
+    const transport = createMockTransport();
+    const client = new DaemonClient({
+      url: "ws://test",
+      clientId: "history-compatibility",
+      reconnect: { enabled: false },
+      transportFactory: () => transport.transport,
+    });
+    clients.push(client);
+    const connected = client.connect();
+    transport.triggerOpen({
+      features: wholeTurnTimeline === undefined ? {} : { wholeTurnTimeline },
+    });
+    await connected;
+
+    const requests = [
+      { direction: "tail" as const },
+      { direction: "before" as const, cursor: { epoch: "epoch-1", seq: 50 } },
+      { direction: "after" as const, cursor: { epoch: "epoch-1", seq: 50 } },
+      { direction: "before" as const, cursor: { epoch: "epoch-1", seq: 80 }, mergeWindow: true },
+    ];
+    for (const [index, request] of requests.entries()) {
+      const requestId = `history-${index}`;
+      const result = client.fetchAgentTimeline("agent-1", {
+        ...request,
+        requestId,
+        wholeTurns: true,
+        limit: 40,
+        projection: "projected",
+      });
+      // Attach immediately so the old rejection is captured by the regression.
+      const completed = expect(result).resolves.toMatchObject({ requestId, entries: [] });
+      expect(parseSentFrame(transport.sent.at(-1))).toEqual({
+        type: "fetch_agent_timeline_request",
+        agentId: "agent-1",
+        requestId,
+        ...request,
+        limit: 40,
+        projection: "projected",
+        ...(wholeTurnTimeline === true ? { wholeTurns: true } : {}),
+      });
+      transport.triggerMessage(
+        wrapSessionMessage({
+          type: "fetch_agent_timeline_response",
+          payload: {
+            requestId,
+            agentId: "agent-1",
+            agent: null,
+            direction: request.direction,
+            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,
+          },
+        }),
+      );
+      await completed;
+    }
+  },
+);
+
 test("honors explicit fetchAgentTimeline timeout below the session RPC default", async () => {
   useHeartbeatClock();
   const logger = createMockLogger();
@@ -2028,6 +2139,188 @@ test("gets a structured plugin log snapshot", async () => {
   ]);
 });
 
+describe("plugin catalog", () => {
+  async function connectedClient(createStore?: (serverId: string) => PluginClientBundleStore) {
+    const mock = createMockTransport();
+    const client = new DaemonClient({
+      url: "ws://test",
+      clientId: "clsk_unit_test",
+      logger: createMockLogger(),
+      createPluginClientBundleStore: createStore,
+      reconnect: { enabled: false },
+      transportFactory: () => mock.transport,
+    });
+    clients.push(client);
+    const connectPromise = client.connect();
+    mock.triggerOpen({ features: { plugins: true } });
+    await connectPromise;
+    return { client, mock };
+  }
+
+  async function fetchCatalog(
+    harness: Awaited<ReturnType<typeof connectedClient>>,
+    respond: (request: Record<string, unknown>) => Array<Record<string, unknown>>,
+  ) {
+    const before = harness.mock.sent.length;
+    const response = harness.client.getPluginCatalog();
+    await vi.waitFor(() => expect(harness.mock.sent.length).toBeGreaterThan(before));
+    const request = parseSentFrame(harness.mock.sent.at(-1));
+    harness.mock.triggerMessage(
+      wrapSessionMessage({
+        type: "plugin.catalog.get.response",
+        payload: { requestId: request.requestId, plugins: respond(request) },
+      }),
+    );
+    return { request, plugins: await response };
+  }
+
+  test("reuses retained client bundles the daemon leaves out", async () => {
+    const harness = await connectedClient();
+    const first = await fetchCatalog(harness, () => [
+      { id: "kept", clientBundle: "kept bundle", clientBundleHash: "hash-kept" },
+      { id: "changed", clientBundle: "old bundle", clientBundleHash: "hash-old" },
+    ]);
+    expect(first.request).not.toHaveProperty("cachedClientBundles");
+
+    const second = await fetchCatalog(harness, () => [
+      { id: "kept", clientBundleHash: "hash-kept" },
+      { id: "changed", clientBundle: "new bundle", clientBundleHash: "hash-new" },
+    ]);
+
+    expect(second.request.cachedClientBundles).toEqual([
+      { id: "kept", clientBundleHash: "hash-kept" },
+      { id: "changed", clientBundleHash: "hash-old" },
+    ]);
+    expect(second.plugins).toEqual([
+      { id: "kept", clientBundle: "kept bundle", clientBundleHash: "hash-kept" },
+      { id: "changed", clientBundle: "new bundle", clientBundleHash: "hash-new" },
+    ]);
+    const third = await fetchCatalog(harness, () => []);
+    expect(third.request.cachedClientBundles).toEqual([
+      { id: "kept", clientBundleHash: "hash-kept" },
+      { id: "changed", clientBundleHash: "hash-new" },
+    ]);
+    const fourth = await fetchCatalog(harness, () => []);
+    expect(fourth.request).not.toHaveProperty("cachedClientBundles");
+  });
+
+  test("keeps fetching every bundle from a daemon that sends no bundle hashes", async () => {
+    const harness = await connectedClient();
+    const legacyCatalog = () => [{ id: "legacy", clientBundle: "legacy bundle" }];
+    await fetchCatalog(harness, legacyCatalog);
+
+    const second = await fetchCatalog(harness, legacyCatalog);
+
+    expect(second.request).not.toHaveProperty("cachedClientBundles");
+    expect(second.plugins).toEqual([{ id: "legacy", clientBundle: "legacy bundle" }]);
+  });
+
+  test("a fresh client advertises persisted bundles on its first fetch and expands omitted code", async () => {
+    let persisted: PluginClientBundle[] = [];
+    let loads = 0;
+    const store: PluginClientBundleStore = {
+      async load() {
+        loads++;
+        return persisted;
+      },
+      async replace(bundles) {
+        persisted = bundles;
+      },
+    };
+    const createdFor: string[] = [];
+    const createStore = (serverId: string) => {
+      createdFor.push(serverId);
+      return store;
+    };
+    const bundle = { id: "kept", clientBundleHash: "hash-kept", clientBundle: "stored code" };
+    const warm = await connectedClient(createStore);
+    await fetchCatalog(warm, () => [bundle]);
+    const cold = await connectedClient(createStore);
+    const first = await fetchCatalog(cold, () => [{ id: "kept", clientBundleHash: "hash-kept" }]);
+    expect(first.request.cachedClientBundles).toEqual([
+      { id: "kept", clientBundleHash: "hash-kept" },
+    ]);
+    expect(first.plugins).toEqual([bundle]);
+    expect(loads).toBe(2);
+    await fetchCatalog(cold, () => []);
+    expect(loads).toBe(2);
+    expect(createdFor).toEqual([
+      warm.client.getLastServerInfoMessage()!.serverId,
+      cold.client.getLastServerInfoMessage()!.serverId,
+    ]);
+    expect(persisted).toEqual([]);
+  });
+
+  test.each(["missing", "unreadable"])(
+    "a %s persistent cache requests full bundles",
+    async (state) => {
+      const store: PluginClientBundleStore = {
+        async load() {
+          if (state === "unreadable") throw new Error("Storage unavailable");
+          return [];
+        },
+        async replace() {},
+      };
+      const bundle = { id: "full", clientBundleHash: "hash-full", clientBundle: "full code" };
+      const result = await fetchCatalog(await connectedClient(() => store), () => [bundle]);
+      expect(result.request).not.toHaveProperty("cachedClientBundles");
+      expect(result.plugins).toEqual([bundle]);
+    },
+  );
+
+  test("failed cache writes never fail plugin loading", async () => {
+    const store: PluginClientBundleStore = {
+      async load() {
+        return [];
+      },
+      async replace() {
+        throw new Error("Disk full");
+      },
+    };
+    const bundle = { id: "full", clientBundleHash: "hash-full", clientBundle: "full code" };
+    expect(
+      (await fetchCatalog(await connectedClient(() => store), () => [bundle])).plugins,
+    ).toEqual([bundle]);
+  });
+
+  test.each([false, true])(
+    "usable catalogs do not wait for storage; latest write survives a failed first write: %s",
+    async (failFirstWrite) => {
+      const writes: PluginClientBundle[][] = [];
+      let finishWrite = () => {};
+      const blockedWrite = new Promise<void>((resolve) => {
+        finishWrite = resolve;
+      });
+      const store: PluginClientBundleStore = {
+        async load() {
+          return [];
+        },
+        async replace(bundles) {
+          writes.push(bundles);
+          if (writes.length === 1) {
+            await blockedWrite;
+            if (failFirstWrite) throw new Error("Disk full");
+          }
+        },
+      };
+      const harness = await connectedClient(() => store);
+      const first = { id: "plugin", clientBundle: "old", clientBundleHash: "hash-old" };
+      const changed = { id: "plugin", clientBundle: "new", clientBundleHash: "hash-new" };
+      try {
+        expect((await fetchCatalog(harness, () => [first])).plugins).toEqual([first]);
+        await vi.waitFor(() => expect(writes).toEqual([[first]]));
+        expect((await fetchCatalog(harness, () => [changed])).plugins).toEqual([changed]);
+        expect((await fetchCatalog(harness, () => [])).plugins).toEqual([]);
+        expect(writes).toEqual([[first]]);
+        finishWrite();
+        await vi.waitFor(() => expect(writes).toEqual([[first], []]));
+      } finally {
+        finishWrite();
+      }
+    },
+  );
+});
+
 test("keeps a plugin reload pending past the session RPC deadline", async () => {
   useHeartbeatClock();
   try {
@@ -2312,7 +2605,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 checks a silently broken socket through two normal heartbeat misses", async () => {
   useHeartbeatClock();
   const first = new FakeDaemon();
   const second = new FakeDaemon();
@@ -2330,7 +2623,11 @@ test("foreground verification replaces a silently broken socket without waiting
   await connection;
 
   client.ensureConnected({ verify: true });
-  await vi.advanceTimersByTimeAsync(3_000);
+  await vi.advanceTimersByTimeAsync(15_000);
+  expect(first.closesFromClient()).toEqual([]);
+  await vi.advanceTimersByTimeAsync(25_000);
+  expect(first.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+  client.ensureConnected();
   expect(attempts).toBe(2);
   second.openConnection();
   expect(client.getConnectionState()).toEqual({ status: "connected" });
@@ -2358,7 +2655,110 @@ 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;
+  });
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(measurementError).toEqual(
+    expect.objectContaining({
+      message: "Latency measurement timed out (5000ms)",
+    }),
+  );
+  for (let index = 0; index < 4; index++) {
+    await vi.advanceTimersByTimeAsync(index === 0 ? 5_000 : 10_000);
+    daemon.receiveChunk(index === 0);
+    expect(daemon.closesFromClient()).toEqual([]);
+  }
+  // No complete message or pong has arrived, but progress prevents misses.
+  expect(daemon.pingTimestamps()).toEqual(["0s", "25s"]);
+  await vi.advanceTimersByTimeAsync(25_000);
+  expect(daemon.closesFromClient()).toEqual([]);
+  await vi.advanceTimersByTimeAsync(25_000);
+  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 < 4; index++) {
+    await vi.advanceTimersByTimeAsync(10_000);
+    daemon.receiveChunk(index === 0);
+    expect(daemon.closesFromClient()).toEqual([]);
+  }
+  // No complete message or pong has arrived, but progress prevents misses.
+  expect(daemon.pingTimestamps()).toEqual(["0s", "25s"]);
+  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(5_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 expected = ["0s"];
+    if (index >= 4) expected.push("25s");
+    if (index >= 9) expected.push("50s");
+    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([]);
+});
+
+test("an obsolete heartbeat cannot close a replacement connection", async () => {
   useHeartbeatClock();
   const first = new FakeDaemon();
   const second = new FakeDaemon();
@@ -2475,6 +2875,18 @@ 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("reports the round-trip time of the last successful heartbeat", async () => {
   useHeartbeatClock();
   const session = new DaemonClientSession();
@@ -6132,66 +6544,80 @@ test("emits output events for the active terminal stream", async () => {
   unsubscribe();
 });
 
-test("emits snapshot events for the subscribed terminal stream", async () => {
-  const logger = createMockLogger();
-  const mock = createMockTransport();
+test.each([5, 500, 10000])(
+  "preserves explicit %s history demand on an old ANSI host and normalizes restore",
+  async (history) => {
+    const logger = createMockLogger();
+    const mock = createMockTransport();
 
-  const client = new DaemonClient({
-    url: "ws://test",
-    clientId: "clsk_unit_test",
-    logger,
-    reconnect: { enabled: false },
-    transportFactory: () => mock.transport,
-  });
-  clients.push(client);
+    const client = new DaemonClient({
+      url: "ws://test",
+      clientId: "clsk_unit_test",
+      logger,
+      reconnect: { enabled: false },
+      transportFactory: () => mock.transport,
+    });
+    clients.push(client);
 
-  const connectPromise = client.connect();
-  mock.triggerOpen();
-  await connectPromise;
+    const connectPromise = client.connect();
+    mock.triggerOpen();
+    await connectPromise;
 
-  const snapshots: unknown[] = [];
-  client.onTerminalStreamEvent((event) => {
-    if (event.type !== "snapshot") {
-      return;
-    }
-    snapshots.push(event.state);
-  });
+    const events: unknown[] = [];
+    const replayEvents: unknown[] = [];
+    client.onTerminalStreamEvent((event) => {
+      if (event.type === "replay") replayEvents.push(event.replay);
+      events.push(event);
+    });
 
-  const subscribePromise = client.subscribeTerminal("term-1", { requestId: "sub-2" });
-  await vi.waitFor(() =>
-    expect(parseSentFrame(mock.sent.at(-1)).type).toBe("subscribe_terminal_request"),
-  );
-  mock.triggerMessage(
-    wrapSessionMessage({
-      type: "subscribe_terminal_response",
-      payload: {
-        subscriptionId: "server-" + String(parseSentFrame(mock.sent.at(-1)).requestId),
-        terminalId: "term-1",
+    const subscribePromise = client.subscribeTerminal("term-1", {
+      requestId: "sub-2",
+      restore: { mode: "visible-snapshot", scrollbackLines: history },
+    });
+    await vi.waitFor(() =>
+      expect(parseSentFrame(mock.sent.at(-1)).type).toBe("subscribe_terminal_request"),
+    );
+    expect(parseSentFrame(mock.sent.at(-1)).restore).toEqual({
+      mode: "visible-snapshot",
+      scrollbackLines: history,
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "subscribe_terminal_response",
+        payload: {
+          subscriptionId: "server-" + String(parseSentFrame(mock.sent.at(-1)).requestId),
+          terminalId: "term-1",
+          slot: 12,
+          error: null,
+          requestId: "sub-2",
+        },
+      }),
+    );
+    await subscribePromise;
+
+    const state = {
+      rows: 1,
+      cols: 5,
+      grid: [[{ char: "h" }, { char: "e" }, { char: "l" }, { char: "l" }, { char: "o" }]],
+      scrollback: [],
+      cursor: { row: 0, col: 5 },
+    };
+    mock.triggerMessage(
+      encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.Snapshot,
         slot: 12,
-        error: null,
-        requestId: "sub-2",
-      },
-    }),
-  );
-  await subscribePromise;
+        payload: encodeTerminalSnapshotPayload(state),
+      }),
+    );
 
-  const state = {
-    rows: 1,
-    cols: 5,
-    grid: [[{ char: "h" }, { char: "e" }, { char: "l" }, { char: "l" }, { char: "o" }]],
-    scrollback: [],
-    cursor: { row: 0, col: 5 },
-  };
-  mock.triggerMessage(
-    encodeTerminalStreamFrame({
-      opcode: TerminalStreamOpcode.Snapshot,
-      slot: 12,
-      payload: encodeTerminalSnapshotPayload(state),
-    }),
-  );
-
-  expect(snapshots).toEqual([state]);
-});
+    expect(events).toEqual([]);
+    const data = new TextEncoder().encode("\x1b[31mold ANSI host界🙂");
+    mock.triggerMessage(
+      encodeTerminalStreamFrame({ opcode: TerminalStreamOpcode.Restore, slot: 12, payload: data }),
+    );
+    expect(replayEvents).toEqual([{ type: "begin" }, { type: "data", data }, { type: "end" }]);
+  },
+);
 
 test("sends explicit terminal input and resize commands", async () => {
   const logger = createMockLogger();
@@ -6562,91 +6988,101 @@ test("drops legacy agent_stream tool_call payloads and logs validation warning",
   expect(logger.warn).toHaveBeenCalled();
 });
 
-test("parses canonical fetch_agent_timeline_response payloads without crashing", async () => {
-  const logger = createMockLogger();
-  const mock = createMockTransport();
+test.each([false, true])(
+  "parses canonical timeline responses with chunking=%s",
+  async (chunked) => {
+    const logger = createMockLogger();
+    const mock = createMockTransport();
 
-  const client = new DaemonClient({
-    url: "ws://test",
-    clientId: "clsk_unit_test",
-    logger,
-    reconnect: { enabled: false },
-    transportFactory: () => mock.transport,
-  });
-  clients.push(client);
+    const client = new DaemonClient({
+      url: "ws://test",
+      clientId: "clsk_unit_test",
+      logger,
+      reconnect: { enabled: false },
+      transportFactory: () => mock.transport,
+    });
+    clients.push(client);
 
-  const connectPromise = client.connect();
-  mock.triggerOpen();
-  await connectPromise;
+    const connectPromise = client.connect();
+    mock.triggerOpen({ features: { ownedSubscriptions: true, binaryChunkingV1: chunked } });
+    await connectPromise;
 
-  const received: unknown[] = [];
-  const unsubscribe = client.on("fetch_agent_timeline_response", (msg) => {
-    received.push(msg);
-  });
+    const received: unknown[] = [];
+    const unsubscribe = client.on("fetch_agent_timeline_response", (msg) => {
+      received.push(msg);
+    });
 
-  mock.triggerMessage(
-    wrapSessionMessage({
-      type: "fetch_agent_timeline_response",
+    const command = chunked ? "x".repeat(50 * 1024 * 1024) : "pwd";
+    const sender = new ChunkedTransport({
+      frameBytes: 24 * 1024 * 1024,
+      send: (frame) => mock.triggerMessage(frame),
+      deliver: () => {},
+    });
+    sender.enabled = chunked;
+    await sender.send(
+      wrapSessionMessage({
+        type: "fetch_agent_timeline_response",
+        payload: {
+          requestId: "req-1",
+          agentId: "agent_cli",
+          agent: null,
+          direction: "tail",
+          projection: "projected",
+          epoch: "epoch-1",
+          reset: false,
+          staleCursor: false,
+          gap: false,
+          window: { minSeq: 1, maxSeq: 1, nextSeq: 2 },
+          startCursor: { epoch: "epoch-1", seq: 1 },
+          endCursor: { epoch: "epoch-1", seq: 1 },
+          hasOlder: false,
+          hasNewer: false,
+          entries: [
+            {
+              timestamp: "2026-02-08T20:20:00.000Z",
+              provider: "codex",
+              seqStart: 1,
+              seqEnd: 1,
+              sourceSeqRanges: [{ startSeq: 1, endSeq: 1 }],
+              collapsed: [],
+              item: {
+                type: "tool_call",
+                callId: "call_cli_snapshot",
+                name: "shell",
+                status: "running",
+                detail: {
+                  type: "shell",
+                  command,
+                },
+                error: null,
+              },
+            },
+          ],
+          error: null,
+        },
+      }),
+    );
+
+    unsubscribe();
+
+    expect(received).toHaveLength(1);
+    expect(received[0]).toMatchObject({
       payload: {
-        requestId: "req-1",
-        agentId: "agent_cli",
-        agent: null,
-        direction: "tail",
-        projection: "projected",
-        epoch: "epoch-1",
-        reset: false,
-        staleCursor: false,
-        gap: false,
-        window: { minSeq: 1, maxSeq: 1, nextSeq: 2 },
-        startCursor: { epoch: "epoch-1", seq: 1 },
-        endCursor: { epoch: "epoch-1", seq: 1 },
-        hasOlder: false,
-        hasNewer: false,
         entries: [
           {
-            timestamp: "2026-02-08T20:20:00.000Z",
-            provider: "codex",
-            seqStart: 1,
-            seqEnd: 1,
-            sourceSeqRanges: [{ startSeq: 1, endSeq: 1 }],
-            collapsed: [],
             item: {
               type: "tool_call",
-              callId: "call_cli_snapshot",
-              name: "shell",
               status: "running",
-              detail: {
-                type: "shell",
-                command: "pwd",
-              },
               error: null,
+              detail: { type: "shell", command },
             },
           },
         ],
-        error: null,
       },
-    }),
-  );
-
-  unsubscribe();
-
-  expect(received).toHaveLength(1);
-  expect(received[0]).toMatchObject({
-    payload: {
-      entries: [
-        {
-          item: {
-            type: "tool_call",
-            status: "running",
-            error: null,
-            detail: { type: "shell" },
-          },
-        },
-      ],
-    },
-  });
-  expect(logger.warn).not.toHaveBeenCalled();
-});
+    });
+    expect(logger.warn).not.toHaveBeenCalled();
+  },
+);
 
 test("rejects and logs a correlated response that violates the protocol schema", async () => {
   const mock = createMockTransport();
@@ -8216,3 +8652,429 @@ test("closes before admission when a protected-capable daemon is reached in lega
   expect(daemonReceived).toHaveLength(1);
   expect(JSON.parse(daemonReceived[0] as string)).toMatchObject({ type: "hello" });
 });
+
+test.each([
+  { chunked: false, transportChunked: false },
+  { chunked: true, transportChunked: false },
+  { chunked: false, transportChunked: true },
+  { chunked: true, transportChunked: true },
+])(
+  "default terminal observation requests ANSI replay (replay=$chunked, transport=$transportChunked)",
+  async ({ chunked, transportChunked }) => {
+    const transport = createMockTransport();
+    const client = new DaemonClient({
+      url: "ws://test",
+      clientId: "clsk_unit_test",
+      logger: createMockLogger(),
+      reconnect: { enabled: false },
+      transportFactory: () => transport.transport,
+    });
+    clients.push(client);
+    const connecting = client.connect();
+    transport.triggerOpen({
+      preserveSent: true,
+      features: {
+        ownedSubscriptions: true,
+        "terminal-restore-modes": true,
+        binaryChunkingV1: transportChunked,
+      },
+    });
+    await connecting;
+    const hello = JSON.parse(transport.sent[0] as string);
+    expect(hello.capabilities[CLIENT_CAPS.terminalChunkedReplay]).toBe(true);
+    expect(hello.capabilities[CLIENT_CAPS.binaryChunkingV1]).toBe(true);
+    const wire: Uint8Array[] = [];
+    const sender = new ChunkedTransport({
+      frameBytes: 17,
+      send: (frame) => {
+        if (typeof frame === "string") throw new Error("Expected binary terminal frame");
+        wire.push(frame);
+        transport.triggerMessage(frame);
+      },
+      deliver: () => {},
+    });
+    sender.enabled = transportChunked;
+    const events: import("./terminal-stream-router").TerminalStreamEvent[] = [];
+    const observation = client.observeTerminal("default-terminal", (event) => events.push(event));
+    await vi.waitFor(() =>
+      expect(parseSentFrame(transport.sent.at(-1)).type).toBe("subscribe_terminal_request"),
+    );
+    const request = parseSentFrame(transport.sent.at(-1));
+    expect(request.restore).toEqual({ mode: "full-snapshot" });
+    transport.triggerMessage(
+      wrapSessionMessage({
+        type: "subscribe_terminal_response",
+        payload: {
+          terminalId: "default-terminal",
+          requestId: request.requestId,
+          subscriptionId: "default-subscription",
+          slot: 2,
+          error: null,
+        },
+      }),
+    );
+    await observation.ready;
+    const data = new TextEncoder().encode("\x1b[31mretained 界🙂\x1b[0m");
+    const metadata = { rows: 24, cols: 80, retainedHistoryLines: 1000 };
+    if (chunked) {
+      await sender.send(
+        encodeTerminalStreamFrame({
+          opcode: TerminalStreamOpcode.ReplayBegin,
+          slot: 2,
+          payload: JSON.stringify(metadata),
+        }),
+      );
+      await sender.send(
+        encodeTerminalStreamFrame({
+          opcode: TerminalStreamOpcode.ReplayData,
+          slot: 2,
+          payload: data,
+        }),
+      );
+      await sender.send(
+        encodeTerminalStreamFrame({ opcode: TerminalStreamOpcode.ReplayEnd, slot: 2 }),
+      );
+    } else {
+      // An ANSI-era host selects its existing Restore path for this explicit request.
+      await sender.send(
+        encodeTerminalStreamFrame({ opcode: TerminalStreamOpcode.Restore, slot: 2, payload: data }),
+      );
+    }
+    if (transportChunked) {
+      expect(wire.length).toBeGreaterThan(chunked ? 3 : 1);
+      expect(wire.some((frame) => frame[0] === 0x31)).toBe(true);
+      expect(wire.every((frame) => frame.length <= 17)).toBe(true);
+    } else {
+      expect(wire.map((frame) => frame[0])).toEqual(chunked ? [6, 7, 8] : [5]);
+    }
+    expect(events).toEqual([
+      {
+        terminalId: "default-terminal",
+        subscriptionId: "default-subscription",
+        type: "replay",
+        replay: chunked ? { type: "begin", ...metadata } : { type: "begin" },
+      },
+      {
+        terminalId: "default-terminal",
+        subscriptionId: "default-subscription",
+        type: "replay",
+        replay: { type: "data", data },
+      },
+      {
+        terminalId: "default-terminal",
+        subscriptionId: "default-subscription",
+        type: "replay",
+        replay: { type: "end" },
+      },
+    ]);
+    const live = new TextEncoder().encode("live after replay 界🙂");
+    await sender.send(
+      encodeTerminalStreamFrame({ opcode: TerminalStreamOpcode.Output, slot: 2, payload: live }),
+    );
+    expect(events.at(-1)).toEqual({
+      terminalId: "default-terminal",
+      subscriptionId: "default-subscription",
+      type: "output",
+      data: live,
+    });
+  },
+);
+
+test("uses the frame budget selected by an asynchronously opened transport", async () => {
+  const mock = createMockTransport();
+  mock.transport.maxFrameBytes = 1024;
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "dynamic-budget",
+    transportFactory: () => mock.transport,
+    reconnect: { enabled: false },
+  });
+  clients.push(client);
+  const connecting = client.connect();
+  mock.transport.maxFrameBytes = 16;
+  mock.triggerOpen({ features: { binaryChunkingV1: true } });
+  await connecting;
+  client.sendHostFrame("route", new Uint8Array(100));
+  await vi.waitFor(() => expect(mock.sent.length).toBeGreaterThan(1));
+  expect(mock.sent.every((frame) => typeof frame !== "string" && frame.byteLength <= 16)).toBe(
+    true,
+  );
+});
+
+test.each([false, true])("routed sends wait for origin drain (binary=%s)", async (binary) => {
+  const mock = createMockTransport();
+  let drain!: () => void;
+  let blocked = false;
+  const send = mock.transport.send;
+  mock.transport.send = (frame) => {
+    send(frame);
+    if (blocked)
+      return new Promise<void>((resolve) => {
+        drain = resolve;
+      });
+  };
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "routed-drain",
+    transportFactory: () => mock.transport,
+    reconnect: { enabled: false },
+  });
+  clients.push(client);
+  const connecting = client.connect();
+  mock.triggerOpen({ features: { binaryChunkingV1: true } });
+  await connecting;
+  blocked = true;
+  let finished = false;
+  const write = Promise.resolve(
+    client.sendHostFrame("route", binary ? new Uint8Array([1]) : "hello"),
+  ).then(() => {
+    finished = true;
+    return undefined;
+  });
+  await Promise.resolve();
+  expect(finished).toBe(false);
+  drain();
+  await write;
+  expect(finished).toBe(true);
+});
+
+test("a queued admission failure rejects its RPC without closing the client", async () => {
+  const mock = createMockTransport();
+  const send = mock.transport.send;
+  let block = false;
+  let drain!: () => void;
+  mock.transport.send = (frame) => {
+    if (!block) return send(frame);
+    if (typeof frame !== "string")
+      return new Promise<void>((resolve) => {
+        drain = resolve;
+      });
+    throw new Error("capacity");
+  };
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "queued-admission",
+    transportFactory: () => mock.transport,
+    reconnect: { enabled: false },
+  });
+  clients.push(client);
+  const connecting = client.connect();
+  mock.triggerOpen();
+  await connecting;
+  block = true;
+  const first = client.sendHostFrame("route", new Uint8Array([1]));
+  const ping = client.ping({ timeoutMs: 1000 });
+  void ping.catch(() => {});
+  drain();
+  await first;
+  await expect(ping).rejects.toThrow("capacity");
+  expect(client.isConnected).toBe(true);
+});
+
+test("RPC deadlines remain active while a preceding frame waits for drain", async () => {
+  const mock = createMockTransport();
+  const send = mock.transport.send;
+  let blocked = false;
+  let drain!: () => void;
+  mock.transport.send = (frame) => {
+    if (!blocked) return send(frame);
+    if (typeof frame !== "string")
+      return new Promise<void>((resolve) => {
+        drain = resolve;
+      });
+  };
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "drain-deadline",
+    transportFactory: () => mock.transport,
+    reconnect: { enabled: false },
+  });
+  clients.push(client);
+  const connecting = client.connect();
+  mock.triggerOpen();
+  await connecting;
+  blocked = true;
+  const first = client.sendHostFrame("route", new Uint8Array([1]));
+  try {
+    await expect(client.ping({ timeoutMs: 20 })).rejects.toThrow("Timeout waiting for message");
+    expect(client.isConnected).toBe(true);
+  } finally {
+    drain();
+    await first;
+  }
+});
+
+test.each([false, true])(
+  "event listener errors do not close the transport (chunked=%s)",
+  async (chunked) => {
+    const mock = createMockTransport();
+    const closed = vi.fn();
+    mock.transport.close = closed;
+    const client = new DaemonClient({
+      url: "ws://test",
+      clientId: "listener-error",
+      transportFactory: () => mock.transport,
+      reconnect: { enabled: false },
+    });
+    clients.push(client);
+    const connecting = client.connect();
+    mock.triggerOpen({ features: { binaryChunkingV1: chunked } });
+    await connecting;
+    const unsubscribe = client.subscribe(() => {
+      throw new Error("listener failed");
+    });
+    const text = wrapSessionMessage({
+      type: "agent_deleted",
+      payload: { agentId: "agent-test", requestId: "listener-test" },
+    });
+    const payload = new TextEncoder().encode(text);
+    const frame = chunked ? new Uint8Array([0x31, 1, 0, 3, ...payload]) : text;
+    expect(() => mock.triggerMessage(frame)).toThrow("listener failed");
+    expect(closed).not.toHaveBeenCalled();
+    unsubscribe();
+    const events: string[] = [];
+    client.subscribe((event) => {
+      events.push(event.type);
+    });
+    mock.triggerMessage(frame);
+    expect(events).toEqual(["agent_deleted"]);
+    await client.sendHostFrame("route", "still connected");
+    expect(client.isConnected).toBe(true);
+  },
+);
+
+test("malformed chunk metadata still closes the client transport", async () => {
+  const mock = createMockTransport();
+  const closed = vi.fn();
+  mock.transport.close = closed;
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "malformed-chunk",
+    transportFactory: () => mock.transport,
+    reconnect: { enabled: false },
+  });
+  clients.push(client);
+  const connecting = client.connect();
+  mock.triggerOpen({ features: { binaryChunkingV1: true } });
+  await connecting;
+  mock.triggerMessage(new Uint8Array([0x31, 2, 0, 3, 65]));
+  expect(closed).toHaveBeenCalledWith(4003, "Invalid chunked transport");
+});
+
+test.each([FileTransferOpcode.FileBegin, FileTransferOpcode.FileChunk, FileTransferOpcode.FileEnd])(
+  "upload stops at a queued pre-write rejection (opcode=%s)",
+  async (opcode) => {
+    const mock = createMockTransport();
+    const send = mock.transport.send;
+    let drain!: () => void;
+    let blocked = false;
+    const attempts: number[] = [];
+    mock.transport.send = (frame) => {
+      if (typeof frame !== "string") {
+        const decoded = decodeFileTransferFrame(assertUint8Array(frame));
+        if (decoded) {
+          attempts.push(decoded.opcode);
+          if (decoded.opcode === opcode) throw new Error("upload capacity");
+        } else if (blocked)
+          return new Promise<void>((resolve) => {
+            drain = resolve;
+          });
+      }
+      return send(frame);
+    };
+    const client = new DaemonClient({
+      url: "ws://test",
+      clientId: "upload-admission",
+      transportFactory: () => mock.transport,
+      reconnect: { enabled: false },
+    });
+    clients.push(client);
+    const connecting = client.connect();
+    mock.triggerOpen();
+    await connecting;
+    blocked = true;
+    const first = client.sendHostFrame("route", new Uint8Array([1]));
+    const upload = client.uploadFile({
+      fileName: "file.bin",
+      mimeType: "application/octet-stream",
+      bytes: new Uint8Array([1, 2]),
+      chunkSize: 1,
+    });
+    let rejected: unknown;
+    void upload.catch((error) => {
+      rejected = error;
+    });
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    drain();
+    await first;
+    await vi.waitFor(() => expect(rejected).toMatchObject({ message: "upload capacity" }), {
+      timeout: 500,
+    });
+    expect(attempts.at(-1)).toBe(opcode);
+    expect(client.isConnected).toBe(true);
+  },
+);
+
+test.each(["latency", "dictation start", "dictation finish"])(
+  "queued control send rejection reaches its caller (%s)",
+  async (operation) => {
+    const mock = createMockTransport();
+    const send = mock.transport.send;
+    let blocked = false;
+    let drain!: () => void;
+    mock.transport.send = (frame) => {
+      if (!blocked) return send(frame);
+      if (typeof frame !== "string")
+        return new Promise<void>((resolve) => {
+          drain = resolve;
+        });
+      throw new Error("control capacity");
+    };
+    const client = new DaemonClient({
+      url: "ws://test",
+      clientId: "control-admission",
+      transportFactory: () => mock.transport,
+      reconnect: { enabled: false },
+    });
+    clients.push(client);
+    const connecting = client.connect();
+    mock.triggerOpen();
+    await connecting;
+    blocked = true;
+    const first = client.sendHostFrame("route", new Uint8Array([1]));
+    let result: Promise<unknown>;
+    if (operation === "latency") result = client.measureLatency({ timeoutMs: 1000 });
+    else if (operation === "dictation start")
+      result = client.startDictationStream("dictation", "pcm");
+    else result = client.finishDictationStream("dictation", 0);
+    const rejected = expect(result).rejects.toThrow("control capacity");
+    drain();
+    await first;
+    await rejected;
+    expect(client.isConnected).toBe(true);
+  },
+);
+
+test("routed channels inherit an origin without drain support", async () => {
+  const { createHostChannelTransport } = await import("./hosts/index.js");
+  const mock = createMockTransport();
+  mock.transport.supportsDrain = false;
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "unpaced-route",
+    transportFactory: () => mock.transport,
+    reconnect: { enabled: false },
+  });
+  clients.push(client);
+  const connecting = client.connect();
+  mock.triggerOpen();
+  await connecting;
+  const route = createHostChannelTransport(
+    client,
+    "srv_destination",
+    "scope",
+    "route",
+  )({ url: "ws://route" });
+  expect(route.supportsDrain).toBe(false);
+  route.close();
+});
diff --git a/packages/client/src/daemon-client.ts b/packages/client/src/daemon-client.ts
index 59d928283f..017c302f7d 100644
--- a/packages/client/src/daemon-client.ts
+++ b/packages/client/src/daemon-client.ts
@@ -1,3 +1,7 @@
+import {
+  ChunkedTransport,
+  ChunkedTransportProtocolError,
+} from "@getpaseo/protocol/chunked-transport";
 import {
   HOST_ROUTE_OPCODE,
   encodeHostRouteFrame,
@@ -160,6 +164,11 @@ import {
   FileTransferOpcode,
   TerminalStreamOpcode,
   type FileTransferFrame,
+  assertPluginWireValue,
+  decodePluginFrame,
+  encodePluginInputFrame,
+  isPluginFrameOpcode,
+  PluginFrameOpcode,
 } from "@getpaseo/protocol/binary-frames/index";
 import {
   createRelayE2eeTransportFactory,
@@ -396,6 +405,17 @@ export type DaemonEventHandler = (event: DaemonEvent) => void;
 export type BrowserAutomationExecuteRequestMessage = BrowserAutomationExecuteRequest;
 export type BrowserAutomationExecuteResponseMessage = BrowserAutomationExecuteResponse;
 
+export interface PluginClientBundle {
+  id: string;
+  clientBundleHash: string;
+  clientBundle: string;
+}
+
+/** Host-scoped storage. load must return only bundles whose contents have been verified. */
+export interface PluginClientBundleStore {
+  load(): Promise<PluginClientBundle[]>;
+  replace(bundles: PluginClientBundle[]): Promise<void>;
+}
 /** Endpoint security negotiated on a relay connection. See docs/relay-endpoint-security.md. */
 export type RelaySecurityMode = "legacy" | "protected";
 
@@ -406,6 +426,8 @@ export interface DaemonClientConfig {
   sessionPermissions?: import("@getpaseo/protocol/messages").DaemonPermission[];
   url: string;
   clientId: string;
+  /** Create one cache for the confirmed daemon identity, retained for this client lifetime. */
+  createPluginClientBundleStore?: (serverId: string) => PluginClientBundleStore;
   clientType?: "mobile" | "browser" | "cli" | "mcp" | "hub";
   appVersion?: string;
   runtimeGeneration?: number | null;
@@ -482,6 +504,7 @@ 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;
@@ -686,6 +709,8 @@ export interface FetchAgentOptions {
 }
 type LegacyFetchAgentOptions = Omit<FetchAgentOptions, "agentId">;
 export interface FetchAgentTimelineOptions {
+  /** Prefer whole-turn pages when supported; older hosts retain item-based paging. */
+  wholeTurns?: boolean;
   direction?: FetchAgentTimelineDirection;
   cursor?: FetchAgentTimelineCursor;
   limit?: number;
@@ -766,6 +791,9 @@ type ShutdownRequestedStatusPayload = z.infer<typeof ShutdownRequestedStatusPayl
 export interface ShutdownServerOptions {
   requestId?: string;
   timeout?: number;
+  // Leave terminals running for the next daemon. Only daemons advertising
+  // `features.terminalsSurviveRestart` honor it; check before sending.
+  keepTerminals?: boolean;
 }
 export interface DaemonStatusOptions {
   requestId?: string;
@@ -847,6 +875,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" }
@@ -1013,6 +1049,15 @@ 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];
+export type PluginCatalogEntry = Omit<PluginCatalogResponseEntry, "clientBundle"> & {
+  clientBundle: string;
+};
 
 export class DaemonConnectionError extends Error {
   readonly serverId?: string;
@@ -1242,7 +1287,7 @@ function toReasonCode(reason: string | null | undefined): string | null {
 }
 
 interface PendingSend {
-  send: () => void;
+  send: () => void | Promise<void>;
   resolve: () => void;
   reject: (error: Error) => void;
   timeoutHandle: ReturnType<typeof setTimeout>;
@@ -1254,6 +1299,7 @@ interface PingProbe {
   reject: (error: Error) => void;
   timeoutHandle: ReturnType<typeof setTimeout>;
   startedAt: number;
+  receivedActivity: boolean;
   // 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.
@@ -1265,6 +1311,36 @@ export function supportsUsageReports(features: ServerInfoStatusPayload["features
   return features?.usageSources === true || features?.providerUsageList === true;
 }
 
+export class TerminalKeepUnsupportedError extends Error {
+  readonly code = "TERMINALS_KEEP_UNSUPPORTED";
+  // Own fields reach the CLI's JSON error output, which desktop reads.
+  readonly version: string | null;
+
+  constructor(target: string, version: string | null) {
+    super(
+      `The daemon at ${target}${version ? ` (v${version})` : ""} closes terminals when it stops. Update it first, or run \`paseo daemon stop\` to stop it and close them.`,
+    );
+    this.name = "TerminalKeepUnsupportedError";
+    this.version = version;
+  }
+}
+
+/**
+ * Gate for an explicit "keep terminals" stop. Older daemons drop `keepTerminals` and close the
+ * terminals anyway, so read the capability on the connection that will carry the shutdown and
+ * refuse before sending it.
+ */
+// COMPAT(terminalsSurviveRestart): added in v0.12.0, remove gate after 2027-04-21.
+export function requireTerminalKeepCapability(
+  client: Pick<DaemonClient, "getLastServerInfoMessage">,
+  target: string,
+): void {
+  const serverInfo = client.getLastServerInfoMessage();
+  if (serverInfo?.features?.terminalsSurviveRestart !== true) {
+    throw new TerminalKeepUnsupportedError(target, serverInfo?.version ?? null);
+  }
+}
+
 function buildFetchAgentsRequest(
   options: FetchAgentsOptions | undefined,
   requestId: string,
@@ -1312,6 +1388,7 @@ export class DaemonClient {
     failed: (error) => this.logger.error({ err: error }, "Subscription failed"),
   });
   private transport: DaemonTransport | null = null;
+  private chunkedTransport: ChunkedTransport | null = null;
   private helloAuth: HelloAuth;
   private transportCleanup: Array<() => void> = [];
   private rawMessageListeners: Set<(message: SessionOutboundMessage) => void> = new Set();
@@ -1341,6 +1418,15 @@ export class DaemonClient {
   private pendingBinaryFileReads = new Map<string, PendingBinaryFileRead>();
   private activeBinaryFileTransfers = new Map<string, BinaryFileTransferState>();
   private completedBinaryFileReads = new Map<string, FileReadResult>();
+  /** The last catalog's client bundles by plugin id, so later catalogs can leave them out. */
+  private pluginClientBundles = new Map<
+    string,
+    { clientBundleHash: string; clientBundle: string }
+  >();
+  private pluginClientBundleStore: PluginClientBundleStore | undefined;
+  private pluginClientBundlesLoaded: Promise<void> | undefined;
+  private pluginClientBundlesWrite: PluginClientBundle[] | undefined;
+  private pluginClientBundlesWriting = false;
   private logger: Logger;
   private pendingSendQueue: PendingSend[] = [];
   /**
@@ -1357,7 +1443,6 @@ 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 livenessHeartbeatTimer: ReturnType<typeof setTimeout> | null = null;
   private lastLivenessRttMs: number | null = null;
   private consecutiveLivenessFailures = 0;
@@ -1497,6 +1582,18 @@ export class DaemonClient {
       });
       this.traceConnectionAttempt += 1;
       this.transport = transport;
+      this.chunkedTransport = new ChunkedTransport({
+        get supportsDrain() {
+          return transport.supportsDrain;
+        },
+        get frameBytes() {
+          return transport.maxFrameBytes ?? 32 * 1024 * 1024;
+        },
+        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;
 
@@ -1603,7 +1700,16 @@ export class DaemonClient {
           });
         }),
         transport.onMessage((data) => {
-          if (this.transport === transport) this.handleTransportMessage(data);
+          if (this.transport !== transport) return;
+          const bytes = asUint8Array(data);
+          try {
+            if (typeof data === "string" || bytes)
+              this.chunkedTransport!.receive(typeof data === "string" ? data : bytes!);
+            else this.handleTransportMessage(data);
+          } catch (error) {
+            if (!(error instanceof ChunkedTransportProtocolError)) throw error;
+            transport.close(4003, "Invalid chunked transport");
+          }
         }),
       ];
     } catch (error) {
@@ -1683,7 +1789,7 @@ export class DaemonClient {
       this.shouldReconnect = true;
     }
     if (this.connectionState.status === "connected") {
-      if (options?.verify) this.verifyConnection();
+      if (options?.verify) this.tickLivenessHeartbeat();
       return;
     }
     if (this.connectionState.status === "connecting") return;
@@ -1696,26 +1802,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 {
@@ -1804,9 +1893,9 @@ export class DaemonClient {
       })
     ).routeId;
   }
-  sendHostFrame(routeId: string, data: string | Uint8Array): void {
+  sendHostFrame(routeId: string, data: string | Uint8Array): Promise<void> {
     if (typeof data === "string") {
-      this.sendSessionMessageStrict({
+      return this.sendSessionMessageStrict({
         type: "hosts.route.frame.request",
         routeId,
         data,
@@ -1814,7 +1903,7 @@ export class DaemonClient {
       });
     } else {
       if (!this.isConnected || !this.transport) throw this.unavailableError();
-      this.sendTransportFrame(encodeHostRouteFrame(routeId, data));
+      return this.sendTransportFrame(encodeHostRouteFrame(routeId, data));
     }
   }
   private readonly hostFrameListeners = new Set<(frame: HostRouteFrame) => void>();
@@ -1872,6 +1961,11 @@ export class DaemonClient {
   // Message Subscription
   // ============================================================================
 
+  /** Drain capability inherited by transports routed through this connection. */
+  get supportsDrain(): boolean {
+    return this.transport?.supportsDrain !== false;
+  }
+
   subscribe(handler: DaemonEventHandler): () => void {
     this.eventListeners.add(handler);
     return () => {
@@ -1980,7 +2074,7 @@ export class DaemonClient {
     messageType: string,
     message: unknown,
     submitted?: () => void,
-  ): void {
+  ): Promise<void> {
     const isOpen =
       this.config.trace?.isEnabled() === true &&
       this.beginTraceSection("paseo.ws.message.outbound", {
@@ -1989,25 +2083,30 @@ export class DaemonClient {
         ...describeRequestIdentity(message),
       });
     try {
-      this.sendTransportFrame(JSON.stringify(message), submitted);
+      return this.sendTransportFrame(JSON.stringify(message), submitted);
     } finally {
       this.endTraceSection(isOpen);
     }
   }
 
-  private sendSessionPayload(payload: SessionInboundMessage): void {
-    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;
-      }
-    });
+  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;
+        }
+      },
+    );
   }
 
   private sendTransportFrame(
     frame: string | Uint8Array | ArrayBuffer,
     submitted?: () => void,
-  ): void {
+  ): Promise<void> {
     if (!this.transport) {
       throw this.unavailableError();
     }
@@ -2020,7 +2119,8 @@ export class DaemonClient {
     });
     try {
       submitted?.();
-      this.transport.send(frame);
+      const payload = typeof frame === "string" ? frame : asUint8Array(frame)!;
+      return this.chunkedTransport!.send(payload);
     } finally {
       this.endTraceSection(isOpen);
     }
@@ -2049,10 +2149,10 @@ export class DaemonClient {
     }
   }
 
-  private sendBinaryFrame(frame: Uint8Array): void {
+  private sendBinaryFrame(frame: Uint8Array): Promise<void> {
     if (!this.transport || this.connectionState.status !== "connected") {
       if (this.config.suppressSendErrors) {
-        return;
+        return Promise.resolve();
       }
       throw new Error(`Transport not connected (status: ${this.connectionState.status})`);
     }
@@ -2061,10 +2161,10 @@ export class DaemonClient {
         envelopeType: "binary",
         messageType: "binary",
       });
-      this.sendTransportFrame(frame);
+      return this.sendTransportFrame(frame);
     } catch (error) {
       if (this.config.suppressSendErrors) {
-        return;
+        return Promise.resolve();
       }
       throw error instanceof Error ? error : new Error(String(error));
     }
@@ -2079,7 +2179,7 @@ export class DaemonClient {
   private sendSessionMessageOrThrow(message: SessionInboundMessage): Promise<void> {
     return this.sendWhenConnected(() => {
       const payload = SessionInboundMessageSchema.parse(message);
-      this.sendSessionPayload(payload);
+      return this.sendSessionPayload(payload);
     });
   }
 
@@ -2088,13 +2188,12 @@ export class DaemonClient {
     return this.sendWhenConnected(() => undefined);
   }
 
-  private sendWhenConnected(send: () => void): Promise<void> {
+  private sendWhenConnected(send: () => void | Promise<void>): Promise<void> {
     const status = this.connectionState.status;
 
     // If connected, send immediately
     if (this.transport && status === "connected") {
-      send();
-      return Promise.resolve();
+      return Promise.resolve(send());
     }
 
     // If connecting, queue the message to be sent once connected
@@ -2133,8 +2232,7 @@ export class DaemonClient {
       clearTimeout(pending.timeoutHandle);
       try {
         if (this.transport && this.connectionState.status === "connected") {
-          pending.send();
-          pending.resolve();
+          void Promise.resolve(pending.send()).then(pending.resolve, pending.reject);
         } else {
           pending.reject(new DaemonConnectionError("Connection lost before message could be sent"));
         }
@@ -2163,6 +2261,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;
@@ -2190,19 +2290,19 @@ export class DaemonClient {
       { ...params.options, requestId: params.requestId },
     );
 
+    // The response deadline still applies while the transport waits for drain.
+    void promise.catch(() => undefined);
     try {
-      await 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;
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
       cancel(err);
-      void promise.catch(() => undefined);
       throw err;
-    }
-
-    try {
-      const result = await promise;
-      if (result.kind === "error") throw result.error;
-      return result.value;
     } finally {
       await wire.finish();
     }
@@ -2218,12 +2318,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) {
@@ -2292,13 +2394,13 @@ export class DaemonClient {
     });
   }
 
-  private sendSessionMessageStrict(message: SessionInboundMessage): void {
+  private sendSessionMessageStrict(message: SessionInboundMessage): Promise<void> {
     if (!this.transport || this.connectionState.status !== "connected") {
       throw this.unavailableError();
     }
     const payload = SessionInboundMessageSchema.parse(message);
     try {
-      this.sendSessionPayload(payload);
+      return this.sendSessionPayload(payload);
     } catch (error) {
       throw error instanceof Error ? error : new Error(String(error));
     }
@@ -2438,9 +2540,18 @@ 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);
+    let deadline: ReturnType<typeof setTimeout>;
+    const timeout = new Promise<never>((_resolve, reject) => {
+      deadline = setTimeout(() => reject(new PingTimeoutError(timeoutMs)), timeoutMs);
     });
+    return Promise.race([
+      this.sendPingAwaitRtt({ timeoutMs, drivesLivenessFailure: false }),
+      timeout,
+    ])
+      .catch((error) => {
+        throw toTimeoutError(error, "Latency measurement", timeoutMs);
+      })
+      .finally(() => clearTimeout(deadline));
   }
 
   private async livenessPing(params?: { timeoutMs?: number }): Promise<number> {
@@ -2476,35 +2587,38 @@ 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);
+      // 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.drivesLivenessFailure && !probe.receivedActivity) {
+        this.recordLivenessFailure(toTimeoutError(error, "Liveness check", timeoutMs));
+      }
+    };
     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,
     };
     this.pingProbe = probe;
 
-    try {
-      this.sendJsonMessage("ping", "ping", { type: "ping" });
-    } catch (error) {
-      this.clearPingProbe();
+    const rejectSend = (error: unknown) => {
+      if (this.pingProbe !== probe) return;
       const sendError = error instanceof Error ? error : new Error(String(error));
-      if (probe.drivesLivenessFailure) {
-        this.recordLivenessFailure(sendError);
-      }
-      return Promise.reject(sendError);
+      this.rejectPingProbe(sendError);
+      if (probe.drivesLivenessFailure) this.recordLivenessFailure(sendError);
+    };
+    try {
+      void this.sendJsonMessage("ping", "ping", { type: "ping" }).catch(rejectSend);
+    } catch (error) {
+      rejectSend(error);
     }
 
     return promise;
@@ -2530,14 +2644,21 @@ 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);
   }
 
+  private tickLivenessHeartbeat(): void {
+    this.stopLivenessHeartbeat();
+    const transport = this.transport;
+    const tick = this.livenessPing({ timeoutMs: LIVENESS_HEARTBEAT_TIMEOUT_MS });
+    void tick
+      .catch(() => {})
+      .finally(() => {
+        if (this.transport === transport) this.scheduleNextLivenessHeartbeat();
+      });
+  }
+
   // ============================================================================
   // Agent RPCs (requestId-correlated)
   // ============================================================================
@@ -2554,6 +2675,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 {
@@ -2775,6 +2897,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 };
@@ -2880,6 +3024,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,
@@ -3164,13 +3321,24 @@ 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);
     const result = await this.creations.createAgent({
       ...options,
       config: resolveAgentConfig(options),
@@ -3417,6 +3585,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,
@@ -3447,6 +3631,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>,
@@ -3548,9 +3749,15 @@ export class DaemonClient {
     agentId: string,
     options: FetchAgentTimelineOptions = {},
   ): Promise<FetchAgentTimelinePayload> {
+    // COMPAT(wholeTurnTimeline): added after v0.13.2 (#8010); remove after 2027-04-27 once the daemon floor supports whole-turn pages.
+    // Reading history predates this capability and must keep working on older hosts.
+    const supportsWholeTurns = this.lastServerInfoMessage?.features?.wholeTurnTimeline === true;
     const resolvedRequestId = this.createRequestId(options.requestId);
     const message = SessionInboundMessageSchema.parse({
       type: "fetch_agent_timeline_request",
+      ...(supportsWholeTurns && options.wholeTurns !== undefined
+        ? { wholeTurns: options.wholeTurns }
+        : {}),
       agentId,
       requestId: resolvedRequestId,
       ...(options.direction ? { direction: options.direction } : {}),
@@ -3665,6 +3872,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,
@@ -4035,13 +4294,14 @@ export class DaemonClient {
   async restartServer(
     reason?: string,
     requestId?: string,
-    options?: { timeout?: number },
+    options?: { timeout?: number; killTerminals?: boolean },
   ): Promise<RestartRequestedStatusPayload> {
     const resolvedRequestId = this.createRequestId(requestId);
     const message = SessionInboundMessageSchema.parse({
       type: "restart_server_request",
       ...(reason && reason.trim().length > 0 ? { reason } : {}),
       requestId: resolvedRequestId,
+      ...(options?.killTerminals ? { killTerminals: true } : {}),
     });
     return this.sendRequest({
       requestId: resolvedRequestId,
@@ -4069,6 +4329,7 @@ export class DaemonClient {
     const message = SessionInboundMessageSchema.parse({
       type: "shutdown_server_request",
       requestId: resolvedRequestId,
+      ...(options?.keepTerminals ? { keepTerminals: true } : {}),
     });
     return this.sendRequest({
       requestId: resolvedRequestId,
@@ -4151,7 +4412,7 @@ export class DaemonClient {
   }
 
   async sendVoiceAudioChunk(audio: string, format: string, isLast = false): Promise<void> {
-    this.sendSessionMessage({ type: "voice_audio_chunk", audio, format, isLast });
+    return this.sendSessionMessageStrict({ type: "voice_audio_chunk", audio, format, isLast });
   }
 
   async startDictationStream(dictationId: string, format: string): Promise<void> {
@@ -4192,8 +4453,13 @@ export class DaemonClient {
 
     const cleanupError = new Error("Cancelled dictation start waiter");
     try {
-      this.sendSessionMessageStrict({ type: "dictation_stream_start", dictationId, format });
-      await Promise.race([ackPromise, errorPromise]);
+      const sent = this.sendSessionMessageStrict({
+        type: "dictation_stream_start",
+        dictationId,
+        format,
+      });
+      const response = Promise.race([ackPromise, errorPromise]);
+      await Promise.race([response, sent.then(() => response)]);
     } finally {
       ack.cancel(cleanupError);
       streamError.cancel(cleanupError);
@@ -4328,12 +4594,17 @@ export class DaemonClient {
 
     const cleanupError = new Error("Cancelled dictation finish waiter");
     try {
-      this.sendSessionMessageStrict({ type: "dictation_stream_finish", dictationId, finalSeq });
-      const firstOutcome = await Promise.race([
+      const sent = this.sendSessionMessageStrict({
+        type: "dictation_stream_finish",
+        dictationId,
+        finalSeq,
+      });
+      const response = Promise.race([
         finalOutcomePromise,
         errorOutcomePromise,
         finishAcceptedOutcomePromise,
       ]);
+      const firstOutcome = await Promise.race([response, sent.then(() => response)]);
 
       if (firstOutcome.kind === "final") {
         return firstOutcome.payload;
@@ -4951,7 +5222,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({
@@ -4961,6 +5232,7 @@ export class DaemonClient {
         cwd: options.cwd,
         query: options.query,
         limit: options.limit,
+        refMode: options.refMode,
       },
       responseType: "branch_suggestions_response",
     });
@@ -5249,8 +5521,10 @@ export class DaemonClient {
         return undefined;
       },
     );
+    const sendFrame = (frame: Uint8Array) =>
+      Promise.race([this.sendBinaryFrame(frame), responsePromise]);
     try {
-      this.sendBinaryFrame(
+      await sendFrame(
         encodeFileTransferFrame({
           opcode: FileTransferOpcode.FileBegin,
           requestId: resolvedRequestId,
@@ -5264,6 +5538,7 @@ export class DaemonClient {
         }),
       );
 
+      if (settled) return await responsePromise;
       const chunkSize = input.chunkSize ?? 128 * 1024;
       for (let offset = 0; offset < bytes.byteLength; offset += chunkSize) {
         // Native WebSocket.send encodes binary synchronously. Let rendering and
@@ -5273,7 +5548,7 @@ export class DaemonClient {
         if (this.transport !== uploadTransport || this.connectionState.status !== "connected") {
           throw new DaemonConnectionError("Connection changed during file upload");
         }
-        this.sendBinaryFrame(
+        await sendFrame(
           encodeFileTransferFrame({
             opcode: FileTransferOpcode.FileChunk,
             requestId: resolvedRequestId,
@@ -5282,7 +5557,7 @@ export class DaemonClient {
         );
       }
 
-      this.sendBinaryFrame(
+      await sendFrame(
         encodeFileTransferFrame({
           opcode: FileTransferOpcode.FileEnd,
           requestId: resolvedRequestId,
@@ -5785,14 +6060,82 @@ export class DaemonClient {
     });
   }
 
-  async getPluginCatalog() {
+  async getPluginCatalog(): Promise<PluginCatalogEntry[]> {
+    if (this.config.createPluginClientBundleStore && !this.pluginClientBundleStore) {
+      const serverInfo = this.getLastServerInfoMessage();
+      if (!serverInfo) throw new Error("Plugin catalog requires a connected host");
+      this.pluginClientBundleStore = this.config.createPluginClientBundleStore(serverInfo.serverId);
+    }
+    const store = this.pluginClientBundleStore;
+    if (store) {
+      this.pluginClientBundlesLoaded ??= store.load().then(
+        (bundles) => {
+          for (const { id, ...bundle } of bundles) this.pluginClientBundles.set(id, bundle);
+          return undefined;
+        },
+        (error) => this.logger.warn({ err: error }, "Failed to load plugin client bundles"),
+      );
+      await this.pluginClientBundlesLoaded;
+    }
     const requestId = this.createRequestId();
+    const cached = this.pluginClientBundles;
+    const cachedClientBundles = [...cached].map(([id, { clientBundleHash }]) => ({
+      id,
+      clientBundleHash,
+    }));
     const payload = await this.sendCorrelatedSessionRequest({
       requestId,
-      message: { type: "plugin.catalog.get.request", requestId },
+      message: {
+        type: "plugin.catalog.get.request",
+        requestId,
+        ...(cachedClientBundles.length > 0 ? { cachedClientBundles } : {}),
+      },
       responseType: "plugin.catalog.get.response",
     });
-    return payload.plugins;
+    const retained = new Map<string, { clientBundleHash: string; clientBundle: string }>();
+    const plugins = payload.plugins.map(({ clientBundle: sent, ...plugin }): PluginCatalogEntry => {
+      const previous = cached.get(plugin.id);
+      const clientBundle =
+        sent ??
+        (previous?.clientBundleHash === plugin.clientBundleHash
+          ? previous?.clientBundle
+          : undefined);
+      if (clientBundle === undefined) {
+        throw new Error(`Plugin catalog left out the client bundle for ${plugin.id}`);
+      }
+      // COMPAT(pluginCatalogBundleHash): introduced by PR #6732 (unreleased); remove after
+      // 2027-04-27 once the daemon floor includes bundle hashes. Older bundles are not retained.
+      if (plugin.clientBundleHash !== undefined) {
+        retained.set(plugin.id, { clientBundleHash: plugin.clientBundleHash, clientBundle });
+      }
+      return Object.assign(plugin, { clientBundle });
+    });
+    this.pluginClientBundles = retained;
+    if (store) {
+      this.pluginClientBundlesWrite = [...retained].map(([id, bundle]) =>
+        Object.assign({ id }, bundle),
+      );
+      void this.persistPluginClientBundles(store);
+    }
+    return plugins;
+  }
+
+  private async persistPluginClientBundles(store: PluginClientBundleStore): Promise<void> {
+    if (this.pluginClientBundlesWriting) return;
+    this.pluginClientBundlesWriting = true;
+    try {
+      while (this.pluginClientBundlesWrite) {
+        const bundles = this.pluginClientBundlesWrite;
+        this.pluginClientBundlesWrite = undefined;
+        try {
+          await store.replace(bundles);
+        } catch (error) {
+          this.logger.warn({ err: error }, "Failed to persist plugin client bundles");
+        }
+      }
+    } finally {
+      this.pluginClientBundlesWriting = false;
+    }
   }
 
   async listPlugins(): Promise<PluginListItem[]> {
@@ -6012,22 +6355,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,
@@ -6275,7 +6655,8 @@ export class DaemonClient {
   }
 
   /**
-   * Snapshot/restore and output arrive in receive. Subscribe to the returned handle
+   * Defaults to a full ANSI replay. Replay begin/data/end and live output arrive in receive.
+   * Subscribe to the returned handle
    * for terminal_stream_exit: payload.error means observation failure, not PTY exit.
    * Either outcome detaches this slot and releases the handle automatically.
    */
@@ -6294,7 +6675,7 @@ export class DaemonClient {
       {
         type: "subscribe_terminal_request",
         terminalId,
-        ...(options?.restore ? { restore: options.restore } : {}),
+        restore: options?.restore ?? { mode: "full-snapshot" },
       },
       options,
     );
@@ -6624,6 +7005,8 @@ export class DaemonClient {
   }
 
   private disposeTransport(code = 1001, reason = "Reconnecting"): void {
+    this.chunkedTransport?.close();
+    this.chunkedTransport = null;
     this.owned.disconnected();
     this.providerSnapshotUpdates.clear();
     this.stopLivenessHeartbeat();
@@ -6787,6 +7170,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) {
@@ -6798,6 +7198,10 @@ export class DaemonClient {
       for (const handler of this.hostFrameListeners) handler(hostFrame);
       return true;
     }
+    if (isPluginFrameOpcode(rawBytes[0])) {
+      this.handlePluginFrame(rawBytes);
+      return true;
+    }
     const fileFrame = decodeFileTransferFrame(rawBytes);
     if (fileFrame) {
       this.traceInstant("paseo.ws.message.inbound", {
@@ -7093,15 +7497,6 @@ export class DaemonClient {
     probe.resolve(perfNow() - probe.startedAt);
   }
 
-  private clearPingProbe(): void {
-    const probe = this.pingProbe;
-    if (!probe) {
-      return;
-    }
-    this.pingProbe = null;
-    clearTimeout(probe.timeoutHandle);
-  }
-
   private rejectPingProbe(error: Error): void {
     const probe = this.pingProbe;
     if (!probe) {
@@ -7150,6 +7545,10 @@ export class DaemonClient {
     if (consumerMessage.type === "status") {
       const serverInfo = parseServerInfoStatusPayload(consumerMessage.payload);
       if (serverInfo) {
+        if (this.chunkedTransport)
+          this.chunkedTransport.enabled =
+            serverInfo.features?.binaryChunkingV1 === true &&
+            this.config.capabilities?.[CLIENT_CAPS.binaryChunkingV1] !== false;
         this.lastServerInfoMessage = serverInfo;
         this.destinationServerId = serverInfo.serverId;
         this.connectionFailure = undefined;
diff --git a/packages/client/src/hosts/index.ts b/packages/client/src/hosts/index.ts
index 1baa9ebe43..aa5c910158 100644
--- a/packages/client/src/hosts/index.ts
+++ b/packages/client/src/hosts/index.ts
@@ -1,3 +1,4 @@
+import { MAX_HOST_CHANNEL_FRAME_BYTES } from "@getpaseo/protocol/binary-frames/index";
 import { safeRandomId } from "../daemon-client-transport-utils.js";
 import { DaemonClient } from "../daemon-client.js";
 import type { DaemonTransportFactory } from "../daemon-client-transport-types.js";
@@ -84,13 +85,17 @@ export function createHostChannelTransport(
       })
       .catch(close);
     return {
+      get supportsDrain() {
+        return origin.supportsDrain;
+      },
+      maxFrameBytes: MAX_HOST_CHANNEL_FRAME_BYTES,
       send(data) {
         if (closed || !routeId)
           throw Object.assign(new Error(`Host ${serverId} is offline`), {
             code: "host_offline",
             serverId,
           });
-        origin.sendHostFrame(
+        return origin.sendHostFrame(
           routeId,
           typeof data === "string" || data instanceof Uint8Array ? data : new Uint8Array(data),
         );
diff --git a/packages/client/src/index.test.ts b/packages/client/src/index.test.ts
index a7bb17121c..63f523dc11 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();
@@ -1770,3 +1875,319 @@ test("qualified parents preserve foreign identity without resolving an equal loc
   await client.close();
   expect(localParent.address).toEqual({ serverId: "srv_sdk_test", agentId: "same-parent" });
 });
+
+test("agent reload reopens through the daemon RPC then returns the observed snapshot; refresh remains a read", async () => {
+  const { client, ws } = await connectClient();
+  try {
+    const agent = client.agents.ref("agent_sdk");
+    const snapshot = createAgent();
+    const reloaded = agent.reload({ requestId: "reload-sdk" });
+    expect(parseSentSessionMessage(ws.sent.at(-1))).toMatchObject({
+      type: "refresh_agent_request",
+      agentId: "agent_sdk",
+      requestId: "reload-sdk",
+    });
+    ws.message(
+      sessionMessage({
+        type: "status",
+        payload: {
+          status: "agent_refreshed",
+          requestId: "reload-sdk",
+          agentId: "agent_sdk",
+          timelineSize: 0,
+        },
+      }),
+    );
+    await expect
+      .poll(() => parseSentSessionMessage(ws.sent.at(-1)).type)
+      .toBe("fetch_agent_request");
+    const fetched = parseSentSessionMessage(ws.sent.at(-1));
+    ws.message(
+      sessionMessage({
+        type: "fetch_agent_response",
+        payload: {
+          requestId: fetched.requestId,
+          agentId: "agent_sdk",
+          agent: snapshot,
+          project: null,
+          error: null,
+        },
+      }),
+    );
+    expect(await reloaded).toEqual({ agent: snapshot, project: null });
+    expect(agent.current()).toEqual(snapshot);
+    const read = agent.refresh("snapshot-read");
+    expect(parseSentSessionMessage(ws.sent.at(-1))).toMatchObject({
+      type: "fetch_agent_request",
+      requestId: "snapshot-read",
+    });
+    ws.message(
+      sessionMessage({
+        type: "fetch_agent_response",
+        payload: {
+          requestId: "snapshot-read",
+          agentId: "agent_sdk",
+          agent: snapshot,
+          project: null,
+          error: null,
+        },
+      }),
+    );
+    expect(await read).toEqual({ agent: snapshot, project: null });
+  } finally {
+    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 455d377634..79a2de50a1 100644
--- a/packages/client/src/index.ts
+++ b/packages/client/src/index.ts
@@ -1,3 +1,4 @@
+export type { TerminalReplayEvent, TerminalStreamEvent } from "./terminal-stream-router.js";
 import type { AgentAddress } from "@getpaseo/protocol/addresses";
 import { parentAddressLabels } from "@getpaseo/protocol/agent-labels";
 export type { AgentAddress } from "@getpaseo/protocol/addresses";
@@ -53,6 +54,7 @@ export type {
 } from "./terminals/index.js";
 import type { PluginTimelineItem } from "@getpaseo/protocol/agent-types";
 import type {
+  AgentBackgroundWorkItem,
   FetchAgentsEntry,
   FetchAgentsOptions,
   FetchAgentsPageInfo,
@@ -188,6 +190,10 @@ export interface PaseoWorkspaceHandle {
   current(): PaseoWorkspace | null;
   refresh(options?: { requestId?: string }): Promise<PaseoWorkspace | null>;
   setTitle(title: string | null, requestId?: string): Promise<{ title: string | null }>;
+  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.
@@ -263,7 +269,11 @@ 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>;
@@ -344,6 +354,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;
@@ -367,8 +407,14 @@ export interface PaseoAgentHandle {
   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>;
+  /**
+   * Reopens the provider session with current configuration, rerunning session-open hooks.
+   * Interrupts a running turn and returns the refreshed snapshot.
+   */
+  reload(options?: { requestId?: string }): Promise<PaseoAgentRefetchResult | null>;
   send(text: string, options?: PaseoAgentSendOptions): Promise<void>;
   respondToPermission(options: PaseoAgentRespondToPermissionOptions): Promise<void>;
   /** Sends a prompt and resolves when that turn finishes or needs attention. */
@@ -598,17 +644,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);
   };
@@ -813,25 +862,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;
     };
 
@@ -868,6 +899,8 @@ function createWorkspaceHandleFactory(
       current: () => current,
       refresh,
       setTitle: (title, requestId) => daemonClient.setWorkspaceTitle(id, title, requestId),
+      setBaseBranch: (options) =>
+        daemonClient.setWorkspaceBaseBranch({ ...options, workspaceId: id }),
       archive: async (requestId) => {
         const result = await daemonClient.archiveWorkspace(id, requestId);
         if (current) {
@@ -893,6 +926,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;
@@ -939,6 +973,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;
       },
@@ -981,6 +1057,12 @@ function createAgentHandleFactory(
         current = result?.agent ?? null;
         return result;
       },
+      reload: async (options) => {
+        await daemonClient.refreshAgent(id, options?.requestId);
+        const result = await daemonClient.fetchAgent({ agentId: id });
+        current = result?.agent ?? null;
+        return result;
+      },
       send: async (text, options) => {
         await daemonClient.sendAgentMessage(id, text, options);
       },
@@ -1054,6 +1136,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,
diff --git a/packages/client/src/node/connector.test.ts b/packages/client/src/node/connector.test.ts
index 6e916d4bec..882a2f5706 100644
--- a/packages/client/src/node/connector.test.ts
+++ b/packages/client/src/node/connector.test.ts
@@ -44,12 +44,14 @@ test("a slow consumer cannot exceed the shared byte budget and close releases re
   socket.pause();
   await ready;
   const frame = new Uint8Array(1024 * 1024);
-  for (let index = 0; index < 4; index++) transport.send(frame);
+  const writes = Array.from({ length: 4 }, () => transport.send(frame));
+  const drained = Promise.allSettled(writes);
   expect(budget.bufferedBytes).toBe(4 * 1024 * 1024);
   expect(() => transport.send(frame)).toThrow("Connected host buffer limit reached");
   expect(budget.bufferedBytes).toBeLessThanOrEqual(budget.limit);
   transport.close();
   await expect.poll(() => budget.bufferedBytes).toBe(0);
+  await drained;
 });
 test("direct connector preserves 25 MiB binary frames in both directions", async () => {
   const server = await endpoint();
@@ -65,12 +67,13 @@ test("direct connector preserves 25 MiB binary frames in both directions", async
   await ready;
   const bytes = new Uint8Array(25 * 1024 * 1024).fill(173);
   const echoed = once(socket, "message");
-  transport.send(bytes);
+  const sending = transport.send(bytes);
   const [sent, binary] = await echoed;
   expect(binary).toBe(true);
   expect(Buffer.from(sent as Uint8Array).equals(bytes)).toBe(true);
   socket.send(bytes);
   expect(Buffer.from(await received).equals(bytes)).toBe(true);
+  await sending;
 });
 
 import {
@@ -124,24 +127,29 @@ test("encrypted connector rejects overload synchronously and preserves the physi
   });
   await new Promise<void>((resolve) => transport.onOpen(resolve));
   await ready;
+  expect(transport.maxFrameBytes).toBeLessThan(32 * 1024 * 1024);
   peer.pause();
   const frame = new Uint8Array(1024 * 1024).fill(173);
   let rejected: unknown;
+  const writes: (void | Promise<void>)[] = [];
   for (let index = 0; index < 8; index++) {
     try {
-      transport.send(frame);
+      writes.push(transport.send(frame));
     } catch (error) {
       rejected = error;
       break;
     }
   }
+  const drained = Promise.allSettled(writes);
   expect(rejected).toMatchObject({ code: "resource_limit" });
   expect(budget.bufferedBytes).toBeLessThanOrEqual(budget.limit);
   await new Promise<void>((resolve) => setImmediate(resolve));
   expect(errors).toEqual([]);
   expect(closed).toBe(false);
-  transport.send("sibling control");
+  const sibling = transport.send("sibling control");
   peer.resume();
+  await drained;
+  await sibling;
   await expect.poll(() => received.includes("sibling control")).toBe(true);
   expect(received.filter((data) => data instanceof ArrayBuffer).length).toBeGreaterThan(0);
   expect(
diff --git a/packages/client/src/node/index.ts b/packages/client/src/node/index.ts
index 7132d09f10..464d16332d 100644
--- a/packages/client/src/node/index.ts
+++ b/packages/client/src/node/index.ts
@@ -2,6 +2,7 @@ export { createHostChannelTransport } from "../hosts/index.js";
 import { HostTransportBudget } from "./buffering.js";
 export { HostTransportBudget } from "./buffering.js";
 import { homedir } from "node:os";
+import type { Agent } from "node:http";
 import { WebSocket } from "ws";
 import { parseHostTarget, type HostTarget } from "@getpaseo/protocol/host-target";
 import { createSshTunnel, type SshTunnel } from "./ssh-tunnel.js";
@@ -19,10 +20,15 @@ export { parseHostTarget };
 export type { SshTunnel } from "./ssh-tunnel.js";
 export { createSshTunnel, resolveSshFailureDetail } from "./ssh-tunnel.js";
 
+export interface HostTransportOptions {
+  webSocketAgent?: (url: string) => Agent | undefined;
+}
+
 /** A factory owns one attempt, including a fresh SSH process and its teardown. */
 export function createHostTransportFactory(
   connection: string,
   budget = new HostTransportBudget(),
+  options: HostTransportOptions = {},
 ): DaemonTransportFactory {
   const target = parseHostTarget(connection);
   // Rises to "protected" once the daemon negotiates it, so a later attempt
@@ -68,12 +74,13 @@ export function createHostTransportFactory(
         return;
       }
       const socketPath = socketTarget.socketPath?.replace(/^~(?=\/)/, homedir());
-      let factory = createWebSocketTransportFactory((url, options) => {
+      let factory = createWebSocketTransportFactory((url, socketOptions) => {
         const socket = new WebSocket(
           socketPath && url.startsWith("ws+unix:") ? `ws+unix://${socketPath}:/ws` : url,
-          options?.protocols,
+          socketOptions?.protocols,
           {
-            headers: options?.headers,
+            headers: socketOptions?.headers,
+            agent: socketPath ? undefined : options.webSocketAgent?.(url),
             ...(socketPath ? { socketPath } : {}),
             maxPayload: 100 * 1024 * 1024,
           },
@@ -165,9 +172,15 @@ export function createHostTransportFactory(
       close();
     });
     return {
+      get supportsDrain() {
+        return transport?.supportsDrain;
+      },
+      get maxFrameBytes() {
+        return transport?.maxFrameBytes;
+      },
       send(data) {
         if (closed || !transport) throw new Error("Host transport is unavailable");
-        transport.send(data);
+        return transport.send(data);
       },
       close,
       onOpen(handler) {
@@ -191,14 +204,16 @@ export function createHostTransportFactory(
 }
 export function createHostClient(
   connection: string,
-  config: Omit<DaemonClientConfig, "url" | "transportFactory">,
+  config: Omit<DaemonClientConfig, "url"> & HostTransportOptions,
   budget?: HostTransportBudget,
 ): DaemonClient {
   const target = parseHostTarget(connection);
+  const { webSocketAgent, transportFactory, ...clientConfig } = config;
   return new DaemonClient({
-    ...config,
+    ...clientConfig,
     url: "ws://host-connector/ws",
     ...(target.password ? { password: target.password } : {}),
-    transportFactory: createHostTransportFactory(connection, budget),
+    transportFactory:
+      transportFactory ?? createHostTransportFactory(connection, budget, { webSocketAgent }),
   });
 }
diff --git a/packages/client/src/terminal-stream-router.test.ts b/packages/client/src/terminal-stream-router.test.ts
index 7b9e598410..b8ed727117 100644
--- a/packages/client/src/terminal-stream-router.test.ts
+++ b/packages/client/src/terminal-stream-router.test.ts
@@ -4,7 +4,7 @@ import { describe, expect, test } from "vitest";
 import { TerminalStreamRouter, type TerminalStreamEvent } from "./terminal-stream-router.js";
 
 describe("terminal-stream-router", () => {
-  test("routes restore frames as restore events", () => {
+  test("normalizes old ANSI restore into the replay lifecycle", () => {
     const router = new TerminalStreamRouter();
     const events: TerminalStreamEvent[] = [];
     const payload = new TextEncoder().encode("restored screen");
@@ -16,14 +16,14 @@ describe("terminal-stream-router", () => {
       payload,
     });
 
-    expect(events).toEqual([
-      {
+    expect(events).toEqual(
+      ["begin", "data", "end"].map((type) => ({
         terminalId: "term-1",
         subscriptionId: "subscription-1",
-        type: "restore",
-        data: payload,
-      },
-    ]);
+        type: "replay",
+        replay: type === "data" ? { type, data: payload } : { type },
+      })),
+    );
   });
 });
 
@@ -61,3 +61,45 @@ test("legacy listeners share a terminal slot without releasing each other", () =
   router.handleFrame(frame);
   expect(received).toEqual(["first", "second", "second"]);
 });
+
+test("streams chunks without joining and ignores released slots during replay", () => {
+  const router = new TerminalStreamRouter();
+  const events: TerminalStreamEvent[] = [];
+  const release = router.attach("old", "terminal", 4, (event) => events.push(event));
+  const payload = new TextEncoder().encode(
+    JSON.stringify({ rows: 24, cols: 80, retainedHistoryLines: 1000 }),
+  );
+  router.handleFrame({ opcode: TerminalStreamOpcode.ReplayBegin, slot: 4, payload });
+  const data = new TextEncoder().encode("\x1b[31m界🙂");
+  router.handleFrame({
+    opcode: TerminalStreamOpcode.ReplayData,
+    slot: 4,
+    payload: data.subarray(0, 7),
+  });
+  release();
+  router.attach("new", "terminal", 5, (event) => events.push(event));
+  router.handleFrame({
+    opcode: TerminalStreamOpcode.ReplayData,
+    slot: 4,
+    payload: data.subarray(7),
+  });
+  router.handleFrame({
+    opcode: TerminalStreamOpcode.ReplayEnd,
+    slot: 4,
+    payload: new Uint8Array(),
+  });
+  expect(events).toHaveLength(2);
+  expect(events[1]).toMatchObject({
+    subscriptionId: "old",
+    type: "replay",
+    replay: { type: "data", data: data.subarray(0, 7) },
+  });
+  router.handleFrame({ opcode: TerminalStreamOpcode.ReplayBegin, slot: 5, payload });
+  router.handleFrame({ opcode: TerminalStreamOpcode.ReplayData, slot: 5, payload: data });
+  router.handleFrame({
+    opcode: TerminalStreamOpcode.ReplayEnd,
+    slot: 5,
+    payload: new Uint8Array(),
+  });
+  expect(events.slice(2).map((event) => event.subscriptionId)).toEqual(["new", "new", "new"]);
+});
diff --git a/packages/client/src/terminal-stream-router.ts b/packages/client/src/terminal-stream-router.ts
index a2c9575450..bca9fb3ea1 100644
--- a/packages/client/src/terminal-stream-router.ts
+++ b/packages/client/src/terminal-stream-router.ts
@@ -1,14 +1,17 @@
 import {
-  decodeTerminalSnapshotPayload,
   TerminalStreamOpcode,
+  TerminalReplayMetadataSchema,
   type TerminalStreamFrame,
 } from "@getpaseo/protocol/binary-frames/index";
-import type { TerminalState } from "@getpaseo/protocol/messages";
+
+export type TerminalReplayEvent =
+  | { type: "begin"; rows?: number; cols?: number; retainedHistoryLines?: number }
+  | { type: "data"; data: Uint8Array }
+  | { type: "end" };
 
 export type TerminalStreamEvent = { terminalId: string; subscriptionId: string } & (
   | { type: "output"; data: Uint8Array }
-  | { type: "snapshot"; state: TerminalState }
-  | { type: "restore"; data: Uint8Array }
+  | { type: "replay"; replay: TerminalReplayEvent }
 );
 
 export class TerminalStreamRouter {
@@ -61,20 +64,42 @@ export class TerminalStreamRouter {
       let event: TerminalStreamEvent;
       if (frame.opcode === TerminalStreamOpcode.Output)
         event = { ...identity, type: "output", data: frame.payload };
-      else if (frame.opcode === TerminalStreamOpcode.Restore)
-        event = { ...identity, type: "restore", data: frame.payload };
-      else if (frame.opcode === TerminalStreamOpcode.Snapshot) {
-        const state = decodeTerminalSnapshotPayload(frame.payload);
-        if (!state) return;
-        event = { ...identity, type: "snapshot", state };
-      } else return;
-      registration.receive(event);
-      for (const listener of this.listeners) {
+      else if (frame.opcode === TerminalStreamOpcode.Restore) {
+        // COMPAT(terminalSingleRestore): added after v0.14.0; remove when ANSI host floor supports chunked replay after 2027-04-30.
+        for (const replay of [
+          { type: "begin" },
+          { type: "data", data: frame.payload },
+          { type: "end" },
+        ] as TerminalReplayEvent[])
+          this.deliver(registration.receive, { ...identity, type: "replay", replay });
+        continue;
+      } else if (frame.opcode === TerminalStreamOpcode.ReplayBegin) {
+        let raw: unknown;
         try {
-          listener(event);
+          raw = JSON.parse(new TextDecoder().decode(frame.payload));
         } catch {
-          /* Passive diagnostics cannot interrupt delivery. */
+          return;
         }
+        const parsed = TerminalReplayMetadataSchema.safeParse(raw);
+        if (!parsed.success) return;
+        const metadata = parsed.data;
+        event = { ...identity, type: "replay", replay: { type: "begin", ...metadata } };
+      } else if (frame.opcode === TerminalStreamOpcode.ReplayData)
+        event = { ...identity, type: "replay", replay: { type: "data", data: frame.payload } };
+      else if (frame.opcode === TerminalStreamOpcode.ReplayEnd)
+        event = { ...identity, type: "replay", replay: { type: "end" } };
+      else return;
+      this.deliver(registration.receive, event);
+    }
+  }
+
+  private deliver(receive: (event: TerminalStreamEvent) => void, event: TerminalStreamEvent): void {
+    receive(event);
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        /* Passive diagnostics cannot interrupt delivery. */
       }
     }
   }
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/appearance-theme.electron.mjs b/packages/desktop/e2e/appearance-theme.electron.mjs
new file mode 100644
index 0000000000..426c50f355
--- /dev/null
+++ b/packages/desktop/e2e/appearance-theme.electron.mjs
@@ -0,0 +1,158 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import electronPath from "electron";
+import { build } from "esbuild";
+
+export async function runAdaptiveThemeRegression(artifactDir) {
+  const { outputFiles } = await build({
+    stdin: {
+      resolveDir: fileURLToPath(new URL("../../app", import.meta.url)),
+      contents: `
+        import { createElement } from "react";
+        import { createRoot } from "react-dom/client";
+        import { StyleSheet, UnistylesRuntime, withUnistyles } from "react-native-unistyles";
+        StyleSheet.configure({
+          themes: {
+            dark: { foreground: "#fafafa", background: "#181b1a" },
+            light: { foreground: "#1a1a1e", background: "#ffffff" },
+          },
+          settings: { adaptiveThemes: true },
+        });
+        const Message = withUnistyles(({ color }) =>
+          createElement("p", { style: { color } }, "Theme-reactive message"));
+        createRoot(document.getElementById("root")).render(createElement(Message, {
+          style: { margin: 0 },
+          uniProps: theme => ({ color: theme.foreground }),
+        }));
+        window.readThemeForTest = () => UnistylesRuntime.themeName;
+      `,
+    },
+    bundle: true,
+    write: false,
+    format: "iife",
+    platform: "browser",
+    alias: { "react-native": "react-native-web" },
+    define: { __DEV__: "false" },
+    resolveExtensions: [".web.js", ".js", ".json"],
+  });
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "paseo-adaptive-theme-"));
+  try {
+    await fs.writeFile(path.join(directory, "renderer.js"), outputFiles[0].text);
+    await fs.writeFile(path.join(directory, "main.cjs"), `(${electronRegression.toString()})()`);
+    // A separate process avoids Playwright's focus emulation, which keeps hidden pages visible.
+    const env = { ...process.env };
+    delete env.ELECTRON_RUN_AS_NODE;
+    const args = [
+      ...(process.platform === "linux" ? ["--no-sandbox"] : []),
+      path.join(directory, "main.cjs"),
+      artifactDir,
+    ];
+    const command = process.platform === "linux" ? "xvfb-run" : electronPath;
+    const commandArgs =
+      process.platform === "linux"
+        ? ["-a", "--server-args=-screen 0 1280x800x24", electronPath, ...args]
+        : args;
+    await promisify(execFile)(command, commandArgs, {
+      env,
+      timeout: 30_000,
+    });
+    return JSON.parse(await fs.readFile(path.join(artifactDir, "adaptive-theme.json"), "utf8"));
+  } finally {
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+}
+
+async function electronRegression() {
+  const { app, BrowserWindow, nativeTheme } = require("electron");
+  const assert = require("node:assert/strict");
+  const files = require("node:fs");
+  const paths = require("node:path");
+  const { setTimeout: delay } = require("node:timers/promises");
+  app.setPath("userData", paths.join(__dirname, "profile"));
+  app.on("window-all-closed", () => {});
+  // Electron keeps Linux's --no-sandbox in argv; the artifact directory is always last.
+  const artifactDir = process.argv.at(-1);
+  let window;
+  const observations = [];
+  const colors = {
+    dark: { foreground: "rgb(250, 250, 250)", background: "rgb(24, 27, 26)" },
+    light: { foreground: "rgb(26, 26, 30)", background: "rgb(255, 255, 255)" },
+  };
+  async function read(expression) {
+    return window.webContents.executeJavaScript(expression);
+  }
+  async function expectValue(expression, expected) {
+    let actual;
+    for (let attempt = 0; attempt < 50; attempt++) {
+      actual = await read(expression);
+      if (actual === expected) return;
+      await delay(50);
+    }
+    assert.equal(actual, expected, expression);
+  }
+  try {
+    await app.whenReady();
+    if (process.platform === "darwin") {
+      app.setActivationPolicy("accessory");
+      app.dock.hide();
+    }
+    for (const [from, to] of [
+      ["dark", "light"],
+      ["light", "dark"],
+    ]) {
+      nativeTheme.themeSource = from;
+      window = new BrowserWindow({ width: 600, height: 200, show: false, skipTaskbar: true });
+      await window.loadURL(
+        "data:text/html," +
+          encodeURIComponent(`<!doctype html>
+        <style>body { background: var(--background); } p { font: 20px system-ui; }</style>
+        <div id="root"></div>`),
+      );
+      await read(files.readFileSync(paths.join(__dirname, "renderer.js"), "utf8"));
+      window.showInactive();
+      const foreground =
+        "document.querySelector('p') && getComputedStyle(document.querySelector('p')).color";
+      const background = "getComputedStyle(document.body).backgroundColor";
+      await expectValue(foreground, colors[from].foreground);
+      await expectValue(background, colors[from].background);
+      window.hide();
+      await expectValue("document.visibilityState", "hidden");
+      nativeTheme.themeSource = to;
+      await expectValue(`matchMedia('(prefers-color-scheme: ${to})').matches`, true);
+      // Reading the public runtime while hidden must not consume the pending theme notification.
+      assert.equal(await read("window.readThemeForTest()"), to);
+      window.showInactive();
+      await expectValue("document.visibilityState", "visible");
+      await expectValue(background, colors[to].background);
+      try {
+        await expectValue(foreground, colors[to].foreground);
+      } finally {
+        files.writeFileSync(
+          paths.join(artifactDir, `theme-${from}-to-${to}.png`),
+          (await window.webContents.capturePage()).toPNG(),
+        );
+      }
+      observations.push({
+        from,
+        to,
+        foreground: await read(foreground),
+        background: await read(background),
+      });
+      window.destroy();
+      window = undefined;
+    }
+    files.writeFileSync(
+      paths.join(artifactDir, "adaptive-theme.json"),
+      JSON.stringify(observations, null, 2),
+    );
+    app.exit(0);
+  } catch (error) {
+    console.error(error);
+    window?.destroy();
+    app.exit(1);
+  }
+}
diff --git a/packages/desktop/e2e/browser-tabs.e2e.mjs b/packages/desktop/e2e/browser-tabs.e2e.mjs
index 78d2fa978e..f06860d862 100644
--- a/packages/desktop/e2e/browser-tabs.e2e.mjs
+++ b/packages/desktop/e2e/browser-tabs.e2e.mjs
@@ -12,8 +12,10 @@ 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 { runSettingsMemoryRegression } from "./settings-memory.electron.mjs";
 
@@ -197,6 +199,20 @@ 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();
+  }
+}
+
 async function startTargetPage() {
   const server = createServer((_request, response) => {
     response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
@@ -1040,6 +1056,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");
@@ -1207,6 +1227,7 @@ async function main() {
     const page = await waitForAppPage(browser, expoPort);
     await hideDeveloperToasts(page);
     const status = await waitForDesktopStatus(page);
+    await settleDesktopStartup(page);
 
     const checkPluginLinks = () =>
       runPluginLinksRegression({
@@ -1241,6 +1262,7 @@ async function main() {
       return;
     }
 
+    const adaptiveTheme = await runAdaptiveThemeRegression(artifactDir);
     await runAppearanceFontSizeRegression(page);
 
     const callerAgentId = await createCallerAgent(daemonPort);
@@ -1265,7 +1287,12 @@ async function main() {
       artifactDir,
     });
     const pluginLinks = await checkPluginLinks();
-    writeJson(path.join(artifactDir, "result.json"), { ...report, settingsMemory, pluginLinks });
+    writeJson(path.join(artifactDir, "result.json"), {
+      ...report,
+      settingsMemory,
+      pluginLinks,
+      adaptiveTheme,
+    });
     console.log(
       `Browser desktop browser E2E passed: WebContents ${report.originalWebContentsId} remained ${report.finalWebContentsId}; viewport, inactive capture, focus continuity, list, snapshot, click, local-page selectors passed.`,
     );
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 4735fb5192..a675c51dc1 100644
--- a/packages/desktop/package.json
+++ b/packages/desktop/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/desktop",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "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/cli/external.ts b/packages/desktop/src/daemon/cli/external.ts
index 6c9deeccb1..4a55adff1c 100644
--- a/packages/desktop/src/daemon/cli/external.ts
+++ b/packages/desktop/src/daemon/cli/external.ts
@@ -4,6 +4,31 @@ import type { NodeEntrypointInvocation } from "../node-entrypoint-launcher.js";
 import { createNodeEntrypointInvocation } from "../runtime-paths.js";
 import { resolveExternalCliEntrypoint } from "./entrypoints.js";
 
+/** A CLI command that exited non-zero, with the `--json` error it printed when there was one. */
+export class ExternalCliCommandError extends Error {
+  readonly code: string | null;
+  readonly error: Record<string, unknown> | null;
+
+  constructor(message: string, error: Record<string, unknown> | null) {
+    super(message);
+    this.name = "ExternalCliCommandError";
+    this.error = error;
+    this.code = typeof error?.code === "string" ? error.code : null;
+  }
+}
+
+// `--json` commands print `{ "error": { code, message, ... } }` on stderr when they fail.
+function parseJsonCliError(stderr: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(stderr) as { error?: unknown };
+    return typeof parsed.error === "object" && parsed.error !== null
+      ? (parsed.error as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 function createExternalCliInvocation(args: string[]): NodeEntrypointInvocation {
   return createNodeEntrypointInvocation({
     entrypoint: resolveExternalCliEntrypoint(),
@@ -85,7 +110,10 @@ export async function runExternalCliJsonCommand(args: string[]): Promise<unknown
       stderr: stderr.slice(0, 500),
       command: invocation.command,
     });
-    throw new Error(externalCliFailureMessage(result.exitCode, stdout, stderr));
+    throw new ExternalCliCommandError(
+      externalCliFailureMessage(result.exitCode, stdout, stderr),
+      parseJsonCliError(stderr),
+    );
   }
 
   const stdout = result.stdout.trim();
diff --git a/packages/desktop/src/daemon/daemon-manager.test.ts b/packages/desktop/src/daemon/daemon-manager.test.ts
index d18a8cd48c..ff830666ad 100644
--- a/packages/desktop/src/daemon/daemon-manager.test.ts
+++ b/packages/desktop/src/daemon/daemon-manager.test.ts
@@ -4,7 +4,13 @@ import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { DEFAULT_DESKTOP_SETTINGS } from "../settings/desktop-settings";
-import { createDaemonCommandHandlers } from "./daemon-manager";
+import { ExternalCliCommandError } from "./cli/external";
+import {
+  createDaemonCommandHandlers,
+  keepsTerminalsOnStop,
+  stopCapturedDaemon,
+  type DesktopDaemonStopReason,
+} from "./daemon-manager";
 
 const mocks = vi.hoisted(() => ({
   paseoHome: "",
@@ -73,7 +79,8 @@ vi.mock("./runtime-paths.js", () => ({
   })),
 }));
 
-vi.mock("./cli/external.js", () => ({
+vi.mock("./cli/external.js", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
   runExternalCliJsonCommand: mocks.runExternalCliJsonCommand,
   runExternalCliTextCommand: mocks.runExternalCliTextCommand,
 }));
@@ -176,3 +183,107 @@ describe("daemon-manager commands", () => {
     expect(await handler({ listen: "localhost:6799" })).toBeNull();
   });
 });
+
+describe("desktop stops and terminals", () => {
+  const reasons: DesktopDaemonStopReason[] = [
+    "manual_ipc",
+    "settings",
+    "host_remove",
+    "quit",
+    "app_update",
+    "version_mismatch",
+    "restart",
+  ];
+
+  it("keeps terminals only for an app update or version-mismatch restart, never on Windows", () => {
+    for (const platform of ["darwin", "linux"] as const) {
+      expect(reasons.filter((reason) => keepsTerminalsOnStop(reason, platform))).toEqual([
+        "app_update",
+        "version_mismatch",
+      ]);
+    }
+    expect(reasons.filter((reason) => keepsTerminalsOnStop(reason, "win32"))).toEqual([]);
+  });
+
+  function stopHarness(runCliJson: (args: string[]) => Promise<unknown>) {
+    const stops: Array<{ keepTerminals: boolean | undefined }> = [];
+    const logged: string[] = [];
+    const instance = {
+      pid: 4242,
+      startedAt: "2026-10-21T00:00:00.000Z",
+      hostname: "host",
+      uid: 501,
+      listen: "127.0.0.1:6799",
+    };
+    const stopInstance = (async (
+      _home: string,
+      options: {
+        keepTerminals?: boolean;
+        requestShutdown?: (ready: { listen: string }) => Promise<void>;
+      },
+    ) => {
+      stops.push({ keepTerminals: options.keepTerminals });
+      await options.requestShutdown?.({ listen: instance.listen });
+      return { action: "stopped", pid: instance.pid, forced: false, usedLifecycleRpc: true };
+    }) as unknown as NonNullable<Parameters<typeof stopCapturedDaemon>[0]["stopInstance"]>;
+    return {
+      stops,
+      logged,
+      input: {
+        home: "/tmp/paseo-home",
+        instance,
+        stopInstance,
+        runCliJson,
+        log: (message: string) => logged.push(message),
+      } as Omit<Parameters<typeof stopCapturedDaemon>[0], "reason" | "keepTerminals">,
+    };
+  }
+
+  it("asks the daemon to keep its terminals on an app update", async () => {
+    const calls: string[][] = [];
+    const harness = stopHarness(async (args) => {
+      calls.push(args);
+      return { action: "shutdown_requested" };
+    });
+
+    await stopCapturedDaemon({ ...harness.input, reason: "app_update", keepTerminals: true });
+
+    expect(harness.stops).toEqual([{ keepTerminals: true }]);
+    expect(calls).toEqual([
+      ["daemon", "stop", "--host", "127.0.0.1:6799", "--keep-terminals", "--json"],
+    ]);
+  });
+
+  it("stops a daemon without the capability with its terminals closed, and says so", async () => {
+    const calls: string[][] = [];
+    const harness = stopHarness(async (args) => {
+      calls.push(args);
+      if (args.includes("--keep-terminals")) {
+        throw new ExternalCliCommandError("refused", {
+          code: "TERMINALS_KEEP_UNSUPPORTED",
+          version: "0.11.0",
+        });
+      }
+      return { action: "shutdown_requested" };
+    });
+
+    await stopCapturedDaemon({ ...harness.input, reason: "app_update", keepTerminals: true });
+
+    expect(harness.stops).toEqual([{ keepTerminals: true }, { keepTerminals: false }]);
+    expect(calls[1]).toEqual(["daemon", "stop", "--host", "127.0.0.1:6799", "--json"]);
+    expect(harness.logged).toContain(
+      "daemon v0.11.0 cannot keep terminals; stopping it and closing them",
+    );
+  });
+
+  it("does not retry a keep stop that failed for another reason", async () => {
+    const harness = stopHarness(async () => {
+      throw new ExternalCliCommandError("unreachable", { code: "DAEMON_UNREACHABLE" });
+    });
+
+    await expect(
+      stopCapturedDaemon({ ...harness.input, reason: "app_update", keepTerminals: true }),
+    ).rejects.toThrow("unreachable");
+    expect(harness.stops).toEqual([{ keepTerminals: true }]);
+  });
+});
diff --git a/packages/desktop/src/daemon/daemon-manager.ts b/packages/desktop/src/daemon/daemon-manager.ts
index 5f3f5394c6..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,
@@ -37,7 +38,11 @@ import {
   closeLocalTransportSession,
 } from "./local-transport.js";
 import { createNodeEntrypointInvocation, resolveDaemonRunnerEntrypoint } from "./runtime-paths.js";
-import { runExternalCliJsonCommand, runExternalCliTextCommand } from "./cli/external.js";
+import {
+  ExternalCliCommandError,
+  runExternalCliJsonCommand,
+  runExternalCliTextCommand,
+} from "./cli/external.js";
 import {
   createDesktopSettingsCommandHandlers,
   type DesktopCommandHandler,
@@ -348,18 +353,84 @@ export async function stopDesktopDaemon(
       "Daemon changed since confirmation; inspect its current home and PID before stopping it.",
     );
   if (!instance || (!owned && !explicit)) return resolveDesktopDaemonStatus();
-  logDesktopDaemonLifecycle("stopping captured supervisor", { reason, pid: instance.pid, owned });
-  await stopDaemonInstance(home, {
-    instance,
-    timeoutMs: 15_000,
-    requestShutdown: async (ready) => {
-      await runExternalCliJsonCommand(["daemon", "stop", "--host", ready.listen, "--json"]);
-    },
+  const keepTerminals = keepsTerminalsOnStop(reason, process.platform);
+  logDesktopDaemonLifecycle("stopping captured supervisor", {
+    reason,
+    pid: instance.pid,
+    owned,
+    keepTerminals,
   });
+  await stopCapturedDaemon({ home, instance, reason, keepTerminals });
   if (owned) ownedLaunch = null;
   return resolveDesktopDaemonStatus();
 }
 
+export interface StopCapturedDaemonInput {
+  home: string;
+  instance: DaemonInstance;
+  reason: DesktopDaemonStopReason;
+  keepTerminals: boolean;
+  stopInstance?: typeof stopDaemonInstance;
+  runCliJson?: typeof runExternalCliJsonCommand;
+  log?: typeof logDesktopDaemonLifecycle;
+}
+
+/** Stops the supervisor desktop captured, keeping its terminals when asked and supported. */
+export async function stopCapturedDaemon(input: StopCapturedDaemonInput): Promise<void> {
+  const stopInstance = input.stopInstance ?? stopDaemonInstance;
+  const runCliJson = input.runCliJson ?? runExternalCliJsonCommand;
+  const logLifecycle = input.log ?? logDesktopDaemonLifecycle;
+  const stop = (keep: boolean) =>
+    stopInstance(input.home, {
+      instance: input.instance,
+      timeoutMs: 15_000,
+      keepTerminals: keep,
+      requestShutdown: async (ready) => {
+        await runCliJson([
+          "daemon",
+          "stop",
+          "--host",
+          ready.listen,
+          ...(keep ? ["--keep-terminals"] : []),
+          "--json",
+        ]);
+      },
+    });
+  try {
+    await stop(input.keepTerminals);
+  } catch (error) {
+    // The CLI refuses a keep stop before sending anything when the daemon predates the feature;
+    // that daemon closes terminals on every stop, as every upgrade did before.
+    if (
+      !input.keepTerminals ||
+      !(error instanceof ExternalCliCommandError) ||
+      error.code !== "TERMINALS_KEEP_UNSUPPORTED"
+    ) {
+      throw error;
+    }
+    const version = typeof error.error?.version === "string" ? error.error.version : "unknown";
+    logLifecycle(`daemon v${version} cannot keep terminals; stopping it and closing them`, {
+      reason: input.reason,
+      pid: input.instance.pid,
+    });
+    await stop(false);
+  }
+}
+
+/**
+ * Whether a desktop stop keeps the daemon's terminals running for the daemon that replaces it.
+ * Only when one comes straight back (an app update, a version-mismatch restart), and never on
+ * Windows: a surviving terminal worker runs Paseo.exe and would lock the install folder the
+ * update replaces. Quit, Settings, host removal and manual stops close terminals.
+ */
+export function keepsTerminalsOnStop(
+  reason: DesktopDaemonStopReason,
+  platform: NodeJS.Platform,
+): boolean {
+  if (platform === "win32") return false;
+  return reason === "app_update" || reason === "version_mismatch";
+}
+
 async function restartDaemon(): Promise<DesktopDaemonStatus> {
   await runExternalCliJsonCommand(["daemon", "restart", "--home", getPaseoHome(), "--json"]);
   return resolveDesktopDaemonStatus();
@@ -468,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/editor-targets/registry.test.ts b/packages/desktop/src/features/editor-targets/registry.test.ts
index 4d8c4d80c7..0a6ae12328 100644
--- a/packages/desktop/src/features/editor-targets/registry.test.ts
+++ b/packages/desktop/src/features/editor-targets/registry.test.ts
@@ -86,6 +86,10 @@ class FakeEditorTargets implements EditorTargetRuntime {
     return this.paths.has(targetPath);
   }
 
+  expandHomePath(targetPath: string): string {
+    return targetPath.startsWith("~/") ? `/home/me/${targetPath.slice(2)}` : targetPath;
+  }
+
   isAbsolutePath(targetPath: string): boolean {
     return targetPath.startsWith("/") || /^[A-Z]:\//u.test(targetPath);
   }
@@ -513,6 +517,19 @@ describe("editor target registry", () => {
     expect(runtime.revealedPaths).toEqual(["C:/repo/src/app.ts"]);
   });
 
+  it("opens a home-relative folder in the file manager", async () => {
+    const runtime = new FakeEditorTargets();
+    runtime.addPath("/home/me/Downloads/contracts");
+
+    await openEditorTarget(
+      { editorId: "file-manager", workspacePath: "~/Downloads/contracts" },
+      runtime,
+      [fileManagerTarget],
+    );
+
+    expect(runtime.openedPaths).toEqual(["/home/me/Downloads/contracts"]);
+  });
+
   it("keeps the platform file-manager ids used by stored preferences", async () => {
     const macTargets = await listAvailableEditorTargets(new FakeEditorTargets("darwin"), [
       finderTarget,
diff --git a/packages/desktop/src/features/editor-targets/registry.ts b/packages/desktop/src/features/editor-targets/registry.ts
index 1e589f7a64..99a8e8d461 100644
--- a/packages/desktop/src/features/editor-targets/registry.ts
+++ b/packages/desktop/src/features/editor-targets/registry.ts
@@ -97,10 +97,16 @@ export function getEditorTarget(
 }
 
 export async function openEditorTarget(
-  input: EditorTargetLaunchInput & { editorId: string },
+  request: EditorTargetLaunchInput & { editorId: string },
   runtime: EditorTargetRuntime,
   targets: readonly EditorTarget[] = EDITOR_TARGETS,
 ): Promise<void> {
+  // Assistant replies name folders like `~/Downloads/x`; expand them before the absolute-path guard.
+  const input = {
+    ...request,
+    workspacePath: runtime.expandHomePath(request.workspacePath),
+    filePath: request.filePath === undefined ? undefined : runtime.expandHomePath(request.filePath),
+  };
   if (!runtime.isAbsolutePath(input.workspacePath)) {
     throw new Error("Editor target workspace path must be an absolute local path");
   }
diff --git a/packages/desktop/src/features/editor-targets/runtime.ts b/packages/desktop/src/features/editor-targets/runtime.ts
index 9562b27977..36bfac0e65 100644
--- a/packages/desktop/src/features/editor-targets/runtime.ts
+++ b/packages/desktop/src/features/editor-targets/runtime.ts
@@ -61,6 +61,14 @@ function isAbsolutePath(value: string, platform: NodeJS.Platform): boolean {
   return platform === "win32" ? win32.isAbsolute(value) : posix.isAbsolute(value);
 }
 
+function expandHomePath(value: string, homeDirectory: string): string {
+  if (value === "~") return homeDirectory;
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path.join(homeDirectory, value.slice(2));
+  }
+  return value;
+}
+
 function resolveExecutable(
   commands: readonly string[],
   input: {
@@ -166,6 +174,7 @@ export function createEditorTargetRuntime(
     pathExists,
     isAbsolutePath: (targetPath) => isAbsolutePath(targetPath, platform),
     listDirectory,
+    expandHomePath: (targetPath) => expandHomePath(targetPath, homeDirectory),
     resolveCommand: (commands) => resolveExecutable(commands, { env, pathExists, platform }),
     async spawnDetached({ command, args }) {
       const commandScript = isWindowsCommandScript(command, platform);
diff --git a/packages/desktop/src/features/editor-targets/target.ts b/packages/desktop/src/features/editor-targets/target.ts
index f7111662c5..b6a9f93668 100644
--- a/packages/desktop/src/features/editor-targets/target.ts
+++ b/packages/desktop/src/features/editor-targets/target.ts
@@ -30,6 +30,8 @@ export interface EditorTargetRuntime {
   pathExists(path: string): boolean;
   isAbsolutePath(path: string): boolean;
   listDirectory(path: string): EditorTargetDirectoryEntry[];
+  /** Resolves a leading `~` to the user's home directory. */
+  expandHomePath(path: string): string;
   resolveCommand(commands: readonly string[]): string | null;
   spawnDetached(input: { command: string; args: readonly string[] }): Promise<void>;
   openPath(path: string): Promise<void>;
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 1a38528c25..e7a72c97f1 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.13.2",
+  "version": "0.15.3",
   "description": "Native module for two way audio streaming",
   "keywords": [
     "ExpoTwoWayAudio",
@@ -33,7 +33,6 @@
   "devDependencies": {
     "@types/jest": "^29.5.14",
     "@types/react": "^18.0.25",
-    "expo-module-scripts": "^5.0.8",
     "expo-modules-core": "^2.0.4"
   },
   "peerDependencies": {
diff --git a/packages/expo-two-way-audio/tsconfig.json b/packages/expo-two-way-audio/tsconfig.json
index 102525ffa9..24e443895c 100644
--- a/packages/expo-two-way-audio/tsconfig.json
+++ b/packages/expo-two-way-audio/tsconfig.json
@@ -6,7 +6,7 @@
     "module": "esnext",
     "moduleResolution": "bundler",
     "typeRoots": [
-      "./node_modules/expo-module-scripts/ts-declarations",
+      "../../node_modules/expo-module-scripts/ts-declarations",
       "./node_modules/@types",
       "../../node_modules/@types"
     ]
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 d7708e5925..009e1677d5 100644
--- a/packages/highlight/package.json
+++ b/packages/highlight/package.json
@@ -1,6 +1,7 @@
 {
   "name": "@getpaseo/highlight",
-  "version": "0.13.2",
+  "version": "0.15.3",
+  "license": "Apache-2.0",
   "files": [
     "dist",
     "!dist/**/*.map",
diff --git a/packages/highlight/src/__tests__/highlighter.test.ts b/packages/highlight/src/__tests__/highlighter.test.ts
index fde3f9d740..095f9689a8 100644
--- a/packages/highlight/src/__tests__/highlighter.test.ts
+++ b/packages/highlight/src/__tests__/highlighter.test.ts
@@ -1,4 +1,6 @@
 import { describe, it, expect } from "vitest";
+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";
 
@@ -420,3 +422,55 @@ describe("highlightLine", () => {
     expect(tokens).toEqual([{ text: "hello", style: null }]);
   });
 });
+
+describe("highlightCodeWithBudget", () => {
+  it("yields to IO while producing byte-identical output below the source budget", async () => {
+    const code = "const value = Math.max(42, 7);\n".repeat(3_000);
+    const expected = JSON.stringify(highlightCode(code, "file.ts"));
+    let ticks = 0;
+    let longestGap = 0;
+    let lastTick = performance.now();
+    const timer = setInterval(() => {
+      const now = performance.now();
+      longestGap = Math.max(longestGap, now - lastTick);
+      lastTick = now;
+      ticks++;
+    }, 1);
+    try {
+      const actual = await highlightCodeWithBudget(code, "file.ts", {
+        yieldToEventLoop: setImmediate,
+      });
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      expect(ticks).toBeGreaterThan(1);
+      expect(longestGap).toBeLessThan(50);
+      expect(JSON.stringify(actual)).toBe(expected);
+    } finally {
+      clearInterval(timer);
+    }
+  });
+
+  it("budgets UTF-8 bytes before parsing, including multibyte text", async () => {
+    expect(
+      await highlightCodeWithBudget("é".repeat(HIGHLIGHT_MAX_SOURCE_BYTES / 2 + 1), "file.ts", {
+        yieldToEventLoop: setImmediate,
+      }),
+    ).toBeNull();
+    expect(
+      await highlightCodeWithBudget("a".repeat(HIGHLIGHT_MAX_SOURCE_BYTES + 1), "file.ts", {
+        yieldToEventLoop: setImmediate,
+      }),
+    ).toBeNull();
+  });
+
+  it("stops a parser that is cancelled between real event-loop turns", async () => {
+    const controller = new AbortController();
+    const pending = highlightCodeWithBudget(
+      "const value = Math.max(42, 7);\n".repeat(3_000),
+      "file.ts",
+      { yieldToEventLoop: setImmediate, signal: controller.signal },
+    );
+    await setImmediate();
+    controller.abort();
+    expect(await pending).toBeNull();
+  });
+});
diff --git a/packages/highlight/src/budgeted-highlighter.ts b/packages/highlight/src/budgeted-highlighter.ts
new file mode 100644
index 0000000000..e949a619ff
--- /dev/null
+++ b/packages/highlight/src/budgeted-highlighter.ts
@@ -0,0 +1,49 @@
+import { highlightCodeInSteps } from "./highlighter.js";
+import type { HighlightToken } from "./types.js";
+
+// Full source, rather than patch size, bounds parser and token allocation work.
+// Each token consumes a source code unit or an empty line: at most the byte cap + 1 records.
+export const HIGHLIGHT_MAX_SOURCE_BYTES = 768 * 1024;
+const SLICE_MS = 4;
+
+/**
+ * Returns null when source exceeds the budget or the request is cancelled.
+ * The host supplies a real event-loop yield (setImmediate on the daemon).
+ * Existing synchronous highlighting remains available for its existing consumers.
+ */
+export async function highlightCodeWithBudget(
+  code: string,
+  filename: string,
+  options: { yieldToEventLoop: () => Promise<void>; signal?: { readonly aborted: boolean } },
+): Promise<HighlightToken[][] | null> {
+  if (options.signal?.aborted || exceedsSourceBudget(code)) return null;
+  const steps = highlightCodeInSteps(code, filename);
+  let sliceStarted = Date.now();
+  try {
+    for (;;) {
+      if (options.signal?.aborted) return null;
+      const step = steps.next();
+      if (step.done) return step.value;
+      if (Date.now() - sliceStarted >= SLICE_MS) {
+        await options.yieldToEventLoop();
+        sliceStarted = Date.now();
+      }
+    }
+  } finally {
+    steps.return([]);
+  }
+}
+
+function exceedsSourceBudget(code: string): boolean {
+  if (code.length > HIGHLIGHT_MAX_SOURCE_BYTES) return true;
+  let bytes = 0;
+  for (const char of code) {
+    const point = char.codePointAt(0)!;
+    if (point < 0x80) bytes++;
+    else if (point < 0x800) bytes += 2;
+    else if (point < 0x10000) bytes += 3;
+    else bytes += 4;
+    if (bytes > HIGHLIGHT_MAX_SOURCE_BYTES) return true;
+  }
+  return false;
+}
diff --git a/packages/highlight/src/index.ts b/packages/highlight/src/index.ts
index a69820ee28..da468e2f87 100644
--- a/packages/highlight/src/index.ts
+++ b/packages/highlight/src/index.ts
@@ -15,3 +15,4 @@ export {
   isSyntaxThemeId,
   resolveSyntaxColors,
 } from "./themes.js";
+export { highlightCodeWithBudget, HIGHLIGHT_MAX_SOURCE_BYTES } from "./budgeted-highlighter.js";
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 18421b41e1..deb9319a48 100644
--- a/packages/plugin/package.json
+++ b/packages/plugin/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/plugin",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "description": "Paseo plugin SDK package",
+  "license": "Apache-2.0",
   "files": [
     "dist",
     "!dist/**/*.map"
@@ -52,6 +53,11 @@
       "types": "./dist/client/index.d.ts",
       "source": "./src/client/index.ts",
       "default": "./dist/client/index.js"
+    },
+    "./internal/lifecycle": {
+      "types": "./dist/server/lifecycle.d.ts",
+      "source": "./src/server/lifecycle.ts",
+      "default": "./dist/server/lifecycle.js"
     }
   },
   "publishConfig": {
@@ -72,8 +78,8 @@
     "use-sync-external-store": "^1.6.0"
   },
   "devDependencies": {
-    "@getpaseo/client": "0.13.2",
-    "@getpaseo/protocol": "0.13.2",
+    "@getpaseo/client": "0.15.3",
+    "@getpaseo/protocol": "0.15.3",
     "@types/node": "^20.9.0",
     "@types/react": "~19.2.0",
     "react": "19.2.3",
@@ -83,8 +89,8 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@getpaseo/client": "0.13.2",
-    "@getpaseo/protocol": "0.13.2",
+    "@getpaseo/client": "0.15.3",
+    "@getpaseo/protocol": "0.15.3",
     "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 c9b54ecdb7..c28bbc8d68 100644
--- a/packages/plugin/src/boundaries.test.ts
+++ b/packages/plugin/src/boundaries.test.ts
@@ -13,6 +13,7 @@ const entries = {
   "./server/provider": "server",
   "./server/usage": "server",
   "./server/acp": "server",
+  "./internal/lifecycle": "server",
   "./client": "client",
   "./client/host": "client",
   "./client/ui": "client",
@@ -92,7 +93,12 @@ function typeErrors(code: string): string[] {
 }
 describe("plugin SDK import boundaries", () => {
   it("publishes process capabilities without their Windows implementation helpers", () => {
-    expect(Object.keys(server).sort()).toEqual(["execCommand", "spawnProcess", "terminateProcess"]);
+    expect(Object.keys(server).sort()).toEqual([
+      "defineAgentTool",
+      "execCommand",
+      "spawnProcess",
+      "terminateProcess",
+    ]);
   });
 
   it("classifies every published entry", () => {
@@ -129,12 +135,8 @@ describe("plugin SDK import boundaries", () => {
   it.each(Object.entries(entries))(
     "%s respects its %s boundary, including type dependencies",
     (specifier, runtime) => {
-      const name =
-        specifier === "."
-          ? "index"
-          : specifier.slice(2) +
-            (specifier === "./client" || specifier === "./server" ? "/index" : "");
-      expect(boundaryViolations(path.join(sourceDirectory, `${name}.ts`), runtime)).toEqual([]);
+      const file = path.resolve(sourceDirectory, "..", manifest.exports[specifier].source);
+      expect(boundaryViolations(file, runtime)).toEqual([]);
     },
   );
 });
@@ -165,6 +167,7 @@ describe("plugin example import boundaries", () => {
         const entry = specifier.replace("@getpaseo/plugin", ".") as keyof typeof entries;
         if (
           entry === "./client/host" ||
+          entry.startsWith("./internal/") ||
           !(entry in entries) ||
           (entries[entry] !== "shared" && entries[entry] !== runtime)
         )
@@ -209,3 +212,179 @@ describe("plugin panel SDK boundary", () => {
     ).toEqual([]);
   });
 });
+
+describe("plugin agent tools SDK boundary", () => {
+  it("lets a session hook attach typed tools without exposing their transport", () => {
+    expect(
+      typeErrors(`
+      import { z } from "zod";
+      import { defineAgentTool, type PluginServerContext, type AgentToolResult, type AgentToolContext, type AgentToolDefinition } from "@getpaseo/plugin/server";
+      const tool: AgentToolDefinition = defineAgentTool({
+        name: "create_issue",
+        description: "Create an issue",
+        input: z.object({ title: z.string(), count: z.string().transform(Number) }),
+        async execute(input, { agent, paseo, signal }) {
+          const count: number = input.count;
+          // @ts-expect-error input is inferred from the schema
+          input.missing;
+          return { text: agent.id + input.title, structuredContent: { count } };
+        },
+      });
+      export default function contribute(server: PluginServerContext) {
+        server.addHook("agent.open.before", async ({ request }) => {
+          const title: string | null = request.title;
+          // @ts-expect-error labels are read-only
+          request.labels.x = "changed";
+          if (request.labels.x !== "y") return;
+          // @ts-expect-error MCP servers use the same typed transport config as saved servers
+          request.mcpServers.invalid = { type: "http", url: 42 };
+          return { ...request, tools: [...request.tools, tool], mcpServers: {
+            ...request.mcpServers, company: { type: "http", url: "https://tools.example.com/mcp" },
+          } };
+        });
+        return () => {};
+      }
+    `),
+    ).toEqual([]);
+  });
+});
+
+describe("lifecycle hook SDK types", () => {
+  it("infers payloads and replacement requests and requires async handlers and new names", () => {
+    expect(
+      typeErrors(`
+      import type { PluginServerContext, PluginHooks, PluginHookPayload, PluginHookResult } from "@getpaseo/plugin/server";
+      export default function contribute(server: PluginServerContext) {
+        server.addHook("worktree.create.before", async ({ request }) => {
+          if (request.kind === "checkout-branch") {
+            // @ts-expect-error Branch checkout has no branch-off base.
+            request.baseRef;
+          } else {
+            const base: string = request.baseRef;
+          }
+          const branch: string = request.branch;
+          // @ts-expect-error Repository identity is read-only.
+          request.repoRoot = "/other";
+          // @ts-expect-error Source checkout identity is read-only.
+          request.sourceCheckout = "/other";
+          if (request.kind === "checkout-change-request") {
+            const number: number = request.changeRequestNumber;
+          }
+          return { ...request, branch: "feature", baseRef: "main", slug: "feature", path: "/work/feature" };
+        });
+        server.addHook("worktree.create.before", async () => {});
+        server.addHook("worktree.create.after", async ({ worktree }) => {
+          const path: string = worktree.path;
+          const branch: string = worktree.branch;
+          const source: string = worktree.sourceCheckout;
+          // @ts-expect-error Worktree facts have no workspace identity.
+          worktree.workspaceId;
+        });
+        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.turn.after", async ({ agent, outcome, timeline }, { paseo, signal }) => {
+          const kind: "completed" | "failed" | "canceled" = outcome.kind;
+          // @ts-expect-error Notification payloads have no creation request.
+          outcome.request;
+        });
+        // @ts-expect-error Async handlers are required even for notifications.
+        server.addHook("agent.turn.before", () => {});
+        // @ts-expect-error Legacy names are only accepted by deprecated registration methods.
+        server.addHook("agent.session_open", async () => {});
+        // @ts-expect-error Unknown names fail typechecking.
+        server.addHook("nonsense", async () => {});
+        // @ts-expect-error A prepare handler must return the whole request or undefined.
+        server.addHook("agent.create.before", async () => ({ invalid: true }));
+        server.before("agent.session_open", ({ request }) => request);
+        server.on("agent.turn_ended", () => {});
+        return () => {};
+      }
+    `),
+    ).toEqual([]);
+  });
+});
+
+describe("agent session reload SDK boundary", () => {
+  it("exposes reload separately from snapshot refresh", () => {
+    expect(
+      typeErrors(`
+      import { type PluginServerContext } from "@getpaseo/plugin/server";
+      import { type PaseoAgentRefetchResult } from "@getpaseo/client";
+      async function reload(server: PluginServerContext, paseo: import("@getpaseo/client").PaseoApi) {
+        const agent = paseo.agents.ref("chosen-agent");
+        const read: PaseoAgentRefetchResult | null = await agent.refresh("read-snapshot");
+        const reopened: PaseoAgentRefetchResult | null = await agent.reload({ requestId: "reload-session" });
+        await agent.reload();
+        // @ts-expect-error reload options can grow without a positional signature change
+        await agent.reload("reload-session");
+      }
+    `),
+    ).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([]);
+  });
+});
diff --git a/packages/plugin/src/client/contracts.ts b/packages/plugin/src/client/contracts.ts
index 7675a655ff..76c163af53 100644
--- a/packages/plugin/src/client/contracts.ts
+++ b/packages/plugin/src/client/contracts.ts
@@ -4,7 +4,13 @@ import type { PaseoApi } from "@getpaseo/client";
 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 {
+  PluginRpcContract,
+  PluginSubscribeOptions,
+  PluginSubscriptionContract,
+  PluginSubscriptionHandle,
+  PluginWireInput,
+} from "../rpc.js";
 import type {
   PluginButtonRegistration,
   PluginHeaderButtonContribution,
@@ -203,6 +209,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;
@@ -295,7 +311,7 @@ export interface PluginCommandCapabilities {
   paseo: PaseoApi;
   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;
   /** @deprecated Use `openScreen`. */
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..2ec1f57b2e 100644
--- a/packages/plugin/src/client/host.ts
+++ b/packages/plugin/src/client/host.ts
@@ -8,7 +8,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 +19,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,
diff --git a/packages/plugin/src/client/index.ts b/packages/plugin/src/client/index.ts
index 62cf7e2dc3..ffaf0782d5 100644
--- a/packages/plugin/src/client/index.ts
+++ b/packages/plugin/src/client/index.ts
@@ -71,7 +71,12 @@ export {
 } from "./file.js";
 export { usePaseo } from "./paseo-context.js";
 export { useAgent, useWorkspace } from "./client-state.js";
-export { useRpc } from "./rpc-context.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";
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..653d71e663 100644
--- a/packages/plugin/src/client/runtime-context-bridge.tsx
+++ b/packages/plugin/src/client/runtime-context-bridge.tsx
@@ -26,7 +26,7 @@ export function usePluginRuntimeContextBridge(): PluginRuntimeContextBridge {
       );
       return (
         <PaseoApiProvider paseo={paseo}>
-          <PluginRpcProvider invoke={rpc.invoke}>
+          <PluginRpcProvider invoke={rpc.invoke} subscribe={rpc.subscribe}>
             <PluginTranslationProvider runtime={translations}>{content}</PluginTranslationProvider>
           </PluginRpcProvider>
         </PaseoApiProvider>
diff --git a/packages/plugin/src/index.ts b/packages/plugin/src/index.ts
index 2bc20fa9ac..839b5003df 100644
--- a/packages/plugin/src/index.ts
+++ b/packages/plugin/src/index.ts
@@ -19,7 +19,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/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 b2fbee8e2c..86e22b2afe 100644
--- a/packages/plugin/src/server/acp-internal/connection.ts
+++ b/packages/plugin/src/server/acp-internal/connection.ts
@@ -997,7 +997,9 @@ class AcpRuntime {
   ): string {
     if (messageId) {
       this.fallbackChunkIds.delete(kind);
-      return messageId;
+      // Native IDs identify a message within its chunk kind. Timeline IDs must
+      // also distinguish reasoning from replies and from generated fallback IDs.
+      return JSON.stringify([kind, messageId]);
     }
     let id = this.fallbackChunkIds.get(kind);
     if (!id) {
diff --git a/packages/plugin/src/server/acp.test.ts b/packages/plugin/src/server/acp.test.ts
index f4b429578f..1d99c73a75 100644
--- a/packages/plugin/src/server/acp.test.ts
+++ b/packages/plugin/src/server/acp.test.ts
@@ -1307,7 +1307,15 @@ describe("runAcpProvider streamed chunks without messageId (#4699)", () => {
     const items = events.flatMap((event) =>
       event.type === "timeline.item" &&
       (event.item.type === "assistant_message" || event.item.type === "reasoning")
-        ? [{ id: event.item.id, text: event.item.text }]
+        ? [
+            {
+              id: event.item.id,
+              text: event.item.text,
+              ...(event.item.type === "assistant_message" && event.item.messageId
+                ? { messageId: event.item.messageId }
+                : {}),
+            },
+          ]
         : [],
     );
     expect(items).toEqual([
@@ -1315,7 +1323,11 @@ describe("runAcpProvider streamed chunks without messageId (#4699)", () => {
       { id: "agent_message_chunk:1", text: "- **Current temperature**: 25°C" },
       { id: "agent_message_chunk:2", text: "next turn" },
       { id: "agent_thought_chunk:3", text: "think A" },
-      { id: "m-explicit", text: "say" },
+      {
+        id: JSON.stringify(["agent_message_chunk", "m-explicit"]),
+        messageId: "m-explicit",
+        text: "say",
+      },
       { id: "agent_thought_chunk:4", text: "think B" },
     ]);
     await connection.close();
@@ -1402,6 +1414,21 @@ async function streamChunkTurns(
 }
 
 describe("ACP streamed message boundaries", () => {
+  it("keeps reasoning separate from a reply sharing its native message ID", async () => {
+    expect(
+      await streamChunkTurns([
+        textChunk("private ", "agent_thought_chunk", "shared-id"),
+        textChunk("reasoning", "agent_thought_chunk", "shared-id"),
+        textChunk("public ", "agent_message_chunk", "shared-id"),
+        textChunk("reply", "agent_message_chunk", "shared-id"),
+      ]),
+    ).toEqual([
+      { type: "reasoning", text: "private reasoning" },
+      { type: "assistant_message", text: "public reply" },
+      { type: "assistant_message", text: "Next turn" },
+    ]);
+  });
+
   it.each([
     {
       name: "tool call",
@@ -1584,8 +1611,12 @@ describe("ACP session history replay", () => {
     );
     try {
       expect(timelineProjection(events)).toEqual([
-        { type: "user_message", id: "user-1", text: "What is the " },
-        { type: "user_message", id: "user-1", text: "What is the temperature?" },
+        { type: "user_message", id: '["user_message_chunk","user-1"]', text: "What is the " },
+        {
+          type: "user_message",
+          id: '["user_message_chunk","user-1"]',
+          text: "What is the temperature?",
+        },
         { type: "reasoning", id: "agent_thought_chunk:1", text: "Checking the sensor" },
         { type: "tool_call", id: "tool-1", status: "running" },
         { type: "tool_call", id: "tool-1", status: "completed" },
@@ -1599,6 +1630,48 @@ describe("ACP session history replay", () => {
     }
   });
 
+  it("keeps replayed user, reasoning and reply chunks separate when their native IDs match", async () => {
+    const { connection, events } = await openReplaySession(
+      [
+        userChunk("What is the ", "shared-id"),
+        userChunk("temperature?", "shared-id"),
+        textChunk("Checking ", "agent_thought_chunk", "shared-id"),
+        textChunk("the sensor", "agent_thought_chunk", "shared-id"),
+        textChunk("It is ", "agent_message_chunk", "shared-id"),
+        textChunk("25°C", "agent_message_chunk", "shared-id"),
+      ],
+      "replay",
+    );
+    try {
+      const items = new Map(
+        events.flatMap((event) =>
+          event.type === "timeline.item" ? [[event.item.id, event.item] as const] : [],
+        ),
+      );
+      expect([...items.values()]).toEqual([
+        {
+          type: "user_message",
+          id: '["user_message_chunk","shared-id"]',
+          messageId: "shared-id",
+          text: "What is the temperature?",
+        },
+        {
+          type: "reasoning",
+          id: '["agent_thought_chunk","shared-id"]',
+          text: "Checking the sensor",
+        },
+        {
+          type: "assistant_message",
+          id: '["agent_message_chunk","shared-id"]',
+          messageId: "shared-id",
+          text: "It is 25°C",
+        },
+      ]);
+    } finally {
+      await connection.close();
+    }
+  });
+
   it("continues anonymous user chunks into one message and starts a new one after an agent reply", async () => {
     const { connection, events } = await openReplaySession(
       [
diff --git a/packages/plugin/src/server/agent-tools.ts b/packages/plugin/src/server/agent-tools.ts
new file mode 100644
index 0000000000..202040cefb
--- /dev/null
+++ b/packages/plugin/src/server/agent-tools.ts
@@ -0,0 +1,39 @@
+import type { PaseoApi } from "@getpaseo/client";
+import type { z } from "zod";
+import type { PluginHookAgent } from "./lifecycle.js";
+
+export interface AgentToolContext {
+  agent: PluginHookAgent;
+  paseo: PaseoApi;
+  signal: AbortSignal;
+}
+
+export interface AgentToolResult {
+  text?: string;
+  structuredContent?: unknown;
+  isError?: boolean;
+}
+
+export interface AgentToolDefinition {
+  name: string;
+  title?: string;
+  description: string;
+  input: z.ZodType;
+  execute(input: unknown, context: AgentToolContext): AgentToolResult | Promise<AgentToolResult>;
+}
+
+export function defineAgentTool<Input extends z.ZodType>(tool: {
+  name: string;
+  title?: string;
+  description: string;
+  input: Input;
+  execute(
+    input: z.output<Input>,
+    context: AgentToolContext,
+  ): AgentToolResult | Promise<AgentToolResult>;
+}): AgentToolDefinition {
+  if (!/^[a-z][a-z0-9_]*$/.test(tool.name) || tool.name.length > 64) {
+    throw new Error(`Invalid agent tool name: ${tool.name}`);
+  }
+  return tool;
+}
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 9180023d19..4ff70ae74d 100644
--- a/packages/plugin/src/server/index.ts
+++ b/packages/plugin/src/server/index.ts
@@ -11,10 +11,18 @@ export type {
   PluginServerContribution,
   PluginSettings,
   PluginSettingsState,
+  PluginSubscriptionContext,
 } from "./contracts.js";
 export type {
+  PluginHooks,
+  PluginHookEvents,
+  PluginHookRequests,
+  PluginHookPayload,
+  PluginHookResult,
   PluginHookContext,
   PluginHookWorkspace,
+  PluginHookWorktree,
+  PluginWorktreeCreateRequest,
   PluginHookAgent,
   PluginSessionOpenRequest,
   PluginTurnOutcome,
@@ -24,3 +32,6 @@ export type {
 } from "./lifecycle.js";
 
 export { spawnProcess, execCommand, terminateProcess } from "./process.js";
+
+export { defineAgentTool } from "./agent-tools.js";
+export type { AgentToolDefinition, AgentToolResult, AgentToolContext } from "./agent-tools.js";
diff --git a/packages/plugin/src/server/lifecycle.ts b/packages/plugin/src/server/lifecycle.ts
index 350039face..20df9c2dcb 100644
--- a/packages/plugin/src/server/lifecycle.ts
+++ b/packages/plugin/src/server/lifecycle.ts
@@ -1,3 +1,4 @@
+import type { AgentToolDefinition } from "./agent-tools.js";
 import type {
   AgentPermissionRequest,
   AgentPermissionResponse,
@@ -20,6 +21,46 @@ export interface PluginHookWorkspace {
   archivedAt: string | null;
 }
 
+export interface PluginHookWorktree {
+  path: string;
+  branch: string;
+  sourceCheckout: string;
+}
+
+/** Resolved creation options before Git fetches refs or chooses a unique branch name. */
+export type PluginWorktreeCreateRequest = {
+  readonly repoRoot: string;
+  readonly sourceCheckout: string;
+  branch: string;
+  slug: string;
+  path: string;
+} & (
+  | { kind: "branch-off"; baseRef: string }
+  | { kind: "checkout-branch" }
+  | {
+      kind: "checkout-change-request";
+      baseRef: string;
+      forge: string;
+      changeRequestNumber: number;
+      headRef: string;
+      headRepositoryOwner?: string;
+      headRepository?: string;
+      checkoutRefs?: { remoteName?: string; remoteRef: string }[];
+      pushRemoteUrl?: string;
+      trackOriginHead?: boolean;
+    }
+  | {
+      kind: "checkout-github-pr";
+      baseRef: string;
+      githubPrNumber: number;
+      headRef: string;
+      headRepositoryOwner?: string;
+      checkoutRefs?: { remoteName?: string; remoteRef: string }[];
+      pushRemoteUrl?: string;
+      trackOriginHead?: boolean;
+    }
+);
+
 export interface PluginHookAgent {
   id: string;
   workspaceId: string | null;
@@ -36,7 +77,11 @@ export interface PluginSessionOpenRequest {
   cwd: string;
   reason: "create" | "resume" | "refresh" | "import";
   purpose: "interactive" | "history";
+  readonly title: string | null;
+  readonly labels: Readonly<Record<string, string>>;
+  tools: AgentToolDefinition[];
   env: Record<string, string>;
+  mcpServers: NonNullable<AgentSessionConfig["mcpServers"]>;
 }
 
 export type PluginTurnOutcome =
@@ -44,9 +89,9 @@ export type PluginTurnOutcome =
   | { kind: "failed"; error: { message: string; code?: string } }
   | { kind: "canceled"; reason: string };
 
-export interface PluginLifecycleEvents {
-  "agent.turn_started": { agent: PluginHookAgent; turnId: string | null };
-  "agent.turn_ended": {
+export interface PluginHookEvents {
+  "agent.turn.before": { agent: PluginHookAgent; turnId: string | null };
+  "agent.turn.after": {
     agent: PluginHookAgent;
     turnId: string | null;
     outcome: PluginTurnOutcome;
@@ -56,26 +101,58 @@ export interface PluginLifecycleEvents {
      */
     timeline: readonly AgentTimelineItem[];
   };
-  "agent.permission_requested": { agent: PluginHookAgent; request: AgentPermissionRequest };
-  "agent.permission_resolved": {
+  "agent.permission.before": { agent: PluginHookAgent; request: AgentPermissionRequest };
+  "agent.permission.after": {
     agent: PluginHookAgent;
     requestId: string;
     resolution: AgentPermissionResponse;
   };
-  "agent.archived": { agent: PluginHookAgent; archivedAt: string };
-  "agent.created": { agent: PluginHookAgent };
-  "agent.closed": { agent: PluginHookAgent };
-  "workspace.created": { workspace: PluginHookWorkspace };
-  "workspace.archived": { workspace: PluginHookWorkspace };
+  "agent.archive.after": { agent: PluginHookAgent; archivedAt: string };
+  "agent.create.after": { agent: PluginHookAgent };
+  "agent.close.after": { agent: PluginHookAgent };
+  "workspace.create.after": { workspace: PluginHookWorkspace };
+  "workspace.archive.after": { workspace: PluginHookWorkspace };
 }
 
-export interface PluginBeforeRequests {
-  "agent.create": { config: AgentSessionConfig; env?: Record<string, string> };
-  "agent.session_open": PluginSessionOpenRequest;
-  "workspace.create": Omit<WorkspaceCreateRequest, "type" | "requestId">;
+export interface PluginHookRequests {
+  "worktree.create.before": PluginWorktreeCreateRequest;
+  "agent.create.before": { config: AgentSessionConfig; env?: Record<string, string> };
+  "agent.open.before": PluginSessionOpenRequest;
+  "workspace.create.before": Omit<WorkspaceCreateRequest, "type" | "requestId">;
 }
 
+export type PluginHooks = {
+  [Name in keyof PluginHookRequests]: {
+    request: PluginHookRequests[Name];
+    result: PluginHookRequests[Name];
+  };
+} & { [Name in keyof PluginHookEvents]: { payload: PluginHookEvents[Name] } } & {
+  "worktree.create.after": { payload: { worktree: PluginHookWorktree } };
+};
+
+export type PluginHookPayload<Name extends keyof PluginHooks> = {
+  [Key in keyof PluginHooks]: PluginHooks[Key] extends { request: infer Request }
+    ? { request: Request }
+    : PluginHooks[Key] extends { payload: infer Payload }
+      ? Payload
+      : never;
+}[Name];
+export type PluginHookResult<Name extends keyof PluginHooks> = {
+  [Key in keyof PluginHooks]: PluginHooks[Key] extends { result: infer Result }
+    ? Result | void
+    : void;
+}[Name];
+
+type HookHandlers = {
+  [Name in keyof PluginHooks]: (
+    payload: PluginHookPayload<Name>,
+    context: PluginHookContext,
+  ) => Promise<PluginHookResult<Name>>;
+};
+
 export interface PluginLifecycleRegistration {
+  addHook<Name extends keyof PluginHooks>(name: Name, handler: HookHandlers[Name]): () => void;
+  /** @deprecated Use addHook with the renamed hook. Removed after 2027-04-30. */
   on<Name extends keyof PluginLifecycleEvents>(
     name: Name,
     handler: (
@@ -83,6 +160,7 @@ export interface PluginLifecycleRegistration {
       context: PluginHookContext,
     ) => void | Promise<void>,
   ): () => void;
+  /** @deprecated Use addHook with the renamed hook. Removed after 2027-04-30. */
   before<Name extends keyof PluginBeforeRequests>(
     name: Name,
     handler: (
@@ -91,3 +169,69 @@ export interface PluginLifecycleRegistration {
     ) => PluginBeforeRequests[Name] | void | Promise<PluginBeforeRequests[Name] | void>,
   ): () => void;
 }
+
+/** @internal Lifecycle policy shared by the daemon and plugin process. */
+export const pluginHookRegistry = {
+  "workspace.create.before": { waits: true },
+  "workspace.create.after": { waits: false },
+  "workspace.archive.after": { waits: false },
+  "worktree.create.before": { waits: true },
+  "worktree.create.after": { waits: true },
+  "agent.create.before": { waits: true },
+  "agent.create.after": { waits: false },
+  "agent.open.before": { waits: true },
+  "agent.close.after": { waits: false },
+  "agent.archive.after": { waits: false },
+  "agent.turn.before": { waits: false },
+  "agent.turn.after": { waits: false },
+  "agent.permission.before": { waits: false },
+  "agent.permission.after": { waits: false },
+} as const satisfies Record<keyof PluginHooks, { waits: boolean }>;
+
+// COMPAT(pluginHookNames): added in v0.14, remove after 2027-04-30
+const legacyEvents = {
+  "workspace.created": "workspace.create.after",
+  "workspace.archived": "workspace.archive.after",
+  "agent.created": "agent.create.after",
+  "agent.closed": "agent.close.after",
+  "agent.archived": "agent.archive.after",
+  "agent.turn_started": "agent.turn.before",
+  "agent.turn_ended": "agent.turn.after",
+  "agent.permission_requested": "agent.permission.before",
+  "agent.permission_resolved": "agent.permission.after",
+} as const;
+const legacyRequests = {
+  "workspace.create": "workspace.create.before",
+  "agent.create": "agent.create.before",
+  "agent.session_open": "agent.open.before",
+} as const;
+export type PluginLifecycleEvents = {
+  [Name in keyof typeof legacyEvents]: PluginHookEvents[(typeof legacyEvents)[Name]];
+};
+export type PluginBeforeRequests = {
+  [Name in keyof typeof legacyRequests]: PluginHookRequests[(typeof legacyRequests)[Name]];
+};
+
+/** @internal SDK adapter for the daemon's hook registry. */
+export function createLifecycleRegistration(
+  register: (
+    name: keyof PluginHooks,
+    handler: (input: never, context: PluginHookContext) => unknown,
+  ) => () => void,
+): PluginLifecycleRegistration {
+  const names = new Set<string>(Object.keys(pluginHookRegistry));
+  return {
+    addHook(name, handler) {
+      if (!names.has(name)) throw new Error(`Unknown lifecycle hook: ${name}`);
+      return register(name, handler);
+    },
+    on(name, handler) {
+      if (!Object.hasOwn(legacyEvents, name)) throw new Error(`Unknown lifecycle event: ${name}`);
+      return register(legacyEvents[name], handler);
+    },
+    before(name, handler) {
+      if (!Object.hasOwn(legacyRequests, name)) throw new Error(`Unknown before hook: ${name}`);
+      return register(legacyRequests[name], handler);
+    },
+  };
+}
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 e463e681e7..be5d266cc2 100644
--- a/packages/protocol/package.json
+++ b/packages/protocol/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/protocol",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "description": "Paseo shared protocol schemas and wire types",
+  "license": "Apache-2.0",
   "files": [
     "dist",
     "!dist/**/*.map",
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 c7fffe8ce9..ca04655430 100644
--- a/packages/protocol/src/agent-types.ts
+++ b/packages/protocol/src/agent-types.ts
@@ -288,7 +288,7 @@ export type ToolCallDetail =
       subAgentType?: string;
       description?: string;
       childSessionId?: string;
-      log: string;
+      log?: string;
       actions?: Array<{
         index: number;
         toolName: string;
diff --git a/packages/protocol/src/binary-frames/demux.test.ts b/packages/protocol/src/binary-frames/demux.test.ts
index c56e417528..a350cfaf03 100644
--- a/packages/protocol/src/binary-frames/demux.test.ts
+++ b/packages/protocol/src/binary-frames/demux.test.ts
@@ -89,3 +89,18 @@ describe("host route binary framing", () => {
     ).toThrow("Invalid host route ID");
   });
 });
+
+it.each([
+  TerminalStreamOpcode.ReplayBegin,
+  TerminalStreamOpcode.ReplayData,
+  TerminalStreamOpcode.ReplayEnd,
+])("decodes replay opcode %s directly and inside a host route", (opcode) => {
+  const payload = new TextEncoder().encode("界 replay");
+  const bytes = encodeTerminalStreamFrame({ opcode, slot: 12, payload });
+  const expected = { kind: "terminal", frame: { opcode, slot: 12, payload } };
+  expect(decodeBinaryFrame(bytes)).toEqual(expected);
+  const routed = decodeBinaryFrame(encodeHostRouteFrame("host", bytes));
+  expect(routed?.kind).toBe("host_route");
+  if (routed?.kind !== "host_route") throw new Error("Missing host route");
+  expect(decodeBinaryFrame(routed.frame.payload)).toEqual(expected);
+});
diff --git a/packages/protocol/src/binary-frames/demux.ts b/packages/protocol/src/binary-frames/demux.ts
index a8503b898f..1a7617e35b 100644
--- a/packages/protocol/src/binary-frames/demux.ts
+++ b/packages/protocol/src/binary-frames/demux.ts
@@ -4,6 +4,7 @@ import {
   FileTransferOpcode,
   type FileTransferFrame,
 } from "./file-transfer.js";
+import { decodePluginFrame, PluginFrameOpcode, type PluginFrame } from "./plugin.js";
 import {
   decodeTerminalStreamFrame,
   TerminalStreamOpcode,
@@ -13,7 +14,8 @@ import {
 export type BinaryFrame =
   | { 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 {
   switch (bytes[0]) {
@@ -25,6 +27,9 @@ export function decodeBinaryFrame(bytes: Uint8Array): BinaryFrame | null {
     case TerminalStreamOpcode.Input:
     case TerminalStreamOpcode.Resize:
     case TerminalStreamOpcode.Snapshot:
+    case TerminalStreamOpcode.ReplayBegin:
+    case TerminalStreamOpcode.ReplayData:
+    case TerminalStreamOpcode.ReplayEnd:
     case TerminalStreamOpcode.Restore: {
       const frame = decodeTerminalStreamFrame(bytes);
       return frame ? { kind: "terminal", frame } : null;
@@ -35,6 +40,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/host-route.ts b/packages/protocol/src/binary-frames/host-route.ts
index f45cd714f9..643dcb4e98 100644
--- a/packages/protocol/src/binary-frames/host-route.ts
+++ b/packages/protocol/src/binary-frames/host-route.ts
@@ -3,6 +3,11 @@ import { MAX_WEBSOCKET_MESSAGE_BYTES } from "../websocket-message-limit.js";
 export const HOST_ROUTE_OPCODE = 0x30;
 export const MAX_HOST_ROUTE_ID_BYTES = 256;
 export const MAX_HOST_ROUTE_HEADER_BYTES = 3 + MAX_HOST_ROUTE_ID_BYTES;
+// A logical host channel crosses the 32 MiB route admission boundary. Text can
+// expand sixfold when enclosed in JSON; binary adds the bounded route header.
+export const MAX_HOST_CHANNEL_FRAME_BYTES = Math.floor(
+  (32 * 1024 * 1024 - MAX_HOST_ROUTE_HEADER_BYTES) / 6,
+);
 export const MAX_ROUTED_PAYLOAD_BYTES = MAX_WEBSOCKET_MESSAGE_BYTES - MAX_HOST_ROUTE_HEADER_BYTES;
 export interface HostRouteFrame {
   routeId: string;
diff --git a/packages/protocol/src/binary-frames/index.ts b/packages/protocol/src/binary-frames/index.ts
index cb24172960..bb2e7e002d 100644
--- a/packages/protocol/src/binary-frames/index.ts
+++ b/packages/protocol/src/binary-frames/index.ts
@@ -2,3 +2,4 @@ export * from "./demux.js";
 export * from "./file-transfer.js";
 export * from "./terminal.js";
 export * from "./host-route.js";
+export * from "./plugin.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/binary-frames/terminal.ts b/packages/protocol/src/binary-frames/terminal.ts
index 3936502c89..b74ea7a8de 100644
--- a/packages/protocol/src/binary-frames/terminal.ts
+++ b/packages/protocol/src/binary-frames/terminal.ts
@@ -1,6 +1,12 @@
 import { z } from "zod";
 import { TerminalStateSchema } from "../messages.js";
 
+export const TerminalReplayMetadataSchema = z.object({
+  rows: z.number().int().positive(),
+  cols: z.number().int().positive(),
+  retainedHistoryLines: z.number().int().nonnegative(),
+});
+
 export const TerminalStreamResizeSchema = z.object({
   rows: z.number().int().positive(),
   cols: z.number().int().positive(),
@@ -13,6 +19,9 @@ export const TerminalStreamOpcode = {
   Resize: 0x03,
   Snapshot: 0x04,
   Restore: 0x05,
+  ReplayBegin: 0x06,
+  ReplayData: 0x07,
+  ReplayEnd: 0x08,
 } as const;
 
 export type TerminalStreamOpcode = (typeof TerminalStreamOpcode)[keyof typeof TerminalStreamOpcode];
@@ -58,6 +67,9 @@ function isTerminalStreamOpcode(value: number): value is TerminalStreamOpcode {
     value === TerminalStreamOpcode.Input ||
     value === TerminalStreamOpcode.Resize ||
     value === TerminalStreamOpcode.Snapshot ||
+    value === TerminalStreamOpcode.ReplayBegin ||
+    value === TerminalStreamOpcode.ReplayData ||
+    value === TerminalStreamOpcode.ReplayEnd ||
     value === TerminalStreamOpcode.Restore
   );
 }
diff --git a/packages/protocol/src/chunked-transport.test.ts b/packages/protocol/src/chunked-transport.test.ts
new file mode 100644
index 0000000000..3979b48885
--- /dev/null
+++ b/packages/protocol/src/chunked-transport.test.ts
@@ -0,0 +1,392 @@
+import { describe, expect, it } from "vitest";
+import { ChunkedTransport } from "./chunked-transport.js";
+
+describe("chunked transport", () => {
+  it("delivers a large UTF-8 logical message once, preserving order", async () => {
+    const delivered: (string | Uint8Array)[] = [];
+    const receiver = new ChunkedTransport({
+      frameBytes: 17,
+      send: () => {},
+      deliver: (v) => delivered.push(v),
+    });
+    receiver.enabled = true;
+    const frames: (string | Uint8Array)[] = [];
+    const sender = new ChunkedTransport({
+      frameBytes: 17,
+      send: (v) => {
+        frames.push(v);
+        receiver.receive(v);
+      },
+      deliver: () => {},
+    });
+    sender.enabled = true;
+    const text = "🌍".repeat(100);
+    await sender.send(text);
+    expect(delivered).toEqual([text]);
+    expect(frames.length).toBeGreaterThan(1);
+    expect(frames.every((v) => v instanceof Uint8Array && v.byteLength <= 17)).toBe(true);
+  });
+});
+
+it("preserves binary kind and leaves legacy frames unchanged", async () => {
+  const delivered: (string | Uint8Array)[] = [];
+  const receiver = new ChunkedTransport({
+    frameBytes: 8,
+    send: () => {},
+    deliver: (v) => delivered.push(v),
+  });
+  const frames: (string | Uint8Array)[] = [];
+  const sender = new ChunkedTransport({
+    frameBytes: 8,
+    send: (v) => {
+      frames.push(v);
+      receiver.receive(v);
+    },
+    deliver: () => {},
+  });
+  const data = new Uint8Array(40).fill(5);
+  await sender.send(data);
+  expect(frames).toEqual([data]);
+  frames.length = 0;
+  sender.enabled = receiver.enabled = true;
+  await sender.send(data);
+  expect(frames).toHaveLength(10);
+  expect(delivered).toEqual([data, data]);
+});
+
+it("rejects malformed sequences and drops incomplete transfers on close", () => {
+  const delivered: unknown[] = [];
+  const receiver = new ChunkedTransport({
+    frameBytes: 8,
+    send: () => {},
+    deliver: (v) => delivered.push(v),
+  });
+  receiver.enabled = true;
+  receiver.receive(new Uint8Array([0x31, 1, 0, 1, 65]));
+  expect(() => receiver.receive("interrupted")).toThrow("Interrupted");
+  receiver.receive(new Uint8Array([0x31, 1, 0, 2, 66]));
+  expect(delivered).toEqual([]);
+});
+
+it("waits for drain before the next chunk and preserves logical ordering", async () => {
+  const frames: (string | Uint8Array)[] = [];
+  let drain!: () => void;
+  const sender = new ChunkedTransport({
+    frameBytes: 8,
+    send: (v) => {
+      frames.push(v);
+      if (frames.length === 1)
+        return new Promise<void>((resolve) => {
+          drain = resolve;
+        });
+    },
+    deliver: () => {},
+  });
+  sender.enabled = true;
+  const first = sender.send("abcdefghij");
+  const next = new Uint8Array([1, 2, 3, 4]);
+  const second = sender.send(next);
+  await Promise.resolve();
+  expect(frames).toHaveLength(1);
+  expect(sender.queuedByteLength).toBe(4);
+  drain();
+  await Promise.all([first, second]);
+  expect(frames).toHaveLength(4);
+  expect(frames[3]).toEqual(next);
+  expect(sender.queuedByteLength).toBe(0);
+});
+
+it.each([
+  [0x31, 2, 0, 3, 65],
+  [0x31, 1, 2, 3, 65],
+  [0x31, 1, 0, 4, 65],
+  [0x31, 1, 0, 2, 65],
+  [0x31, 1, 0, 1],
+])("rejects malformed chunk metadata %j", (...bytes) => {
+  const receiver = new ChunkedTransport({
+    frameBytes: 8,
+    send: () => {},
+    deliver: () => {
+      throw new Error("Unexpected delivery");
+    },
+  });
+  receiver.enabled = true;
+  expect(() => receiver.receive(new Uint8Array(bytes))).toThrow();
+});
+
+it("reconnect discards partial state and requires negotiation again", () => {
+  const delivered: unknown[] = [];
+  const create = () =>
+    new ChunkedTransport({ frameBytes: 8, send: () => {}, deliver: (v) => delivered.push(v) });
+  const old = create();
+  old.enabled = true;
+  old.receive(new Uint8Array([0x31, 1, 0, 1, 65]));
+  old.close();
+  old.receive(new Uint8Array([0x31, 1, 0, 2, 66]));
+  const fresh = create();
+  expect(fresh.enabled).toBe(false);
+  fresh.enabled = true;
+  fresh.receive(new Uint8Array([0x31, 1, 0, 3, 67]));
+  expect(delivered).toEqual(["C"]);
+});
+
+it("bounds logical messages waiting behind a blocked writer", async () => {
+  let drain!: () => void;
+  const transport = new ChunkedTransport({
+    frameBytes: 32 * 1024 * 1024,
+    send: () =>
+      new Promise<void>((resolve) => {
+        drain = resolve;
+      }),
+    deliver: () => {},
+  });
+  const first = transport.send(new Uint8Array(100 * 1024 * 1024));
+  const overflow = transport.send("one more byte");
+  try {
+    await expect(overflow).rejects.toThrow("queue");
+  } finally {
+    drain();
+    await first;
+  }
+});
+
+it("requests drain for chunks while ordinary frames keep the immediate write path", async () => {
+  const waits: boolean[] = [];
+  const transport = new ChunkedTransport({
+    frameBytes: 8,
+    send: (_frame, wait) => {
+      waits.push(wait);
+    },
+    deliver: () => {},
+  });
+  transport.enabled = true;
+  await transport.send("small");
+  await transport.send("abcdefghij");
+  expect(waits).toEqual([false, true, true, true]);
+});
+
+it("charges queued ASCII messages by their UTF-8 bytes", async () => {
+  let drain!: () => void;
+  let blocked = true;
+  const transport = new ChunkedTransport({
+    frameBytes: 32 * 1024 * 1024,
+    send: () => {
+      if (blocked) {
+        blocked = false;
+        return new Promise<void>((resolve) => {
+          drain = resolve;
+        });
+      }
+    },
+    deliver: () => {},
+  });
+  transport.enabled = true;
+  const first = transport.send(new Uint8Array([1]));
+  const text = "x".repeat(10 * 1024 * 1024);
+  const queued = Array.from({ length: 4 }, () => transport.send(text));
+  const settled = Promise.allSettled(queued);
+  expect(transport.queuedByteLength).toBe(40 * 1024 * 1024);
+  drain();
+  await first;
+  expect((await settled).map((result) => result.status)).toEqual([
+    "fulfilled",
+    "fulfilled",
+    "fulfilled",
+    "fulfilled",
+  ]);
+});
+
+it("notifies the socket owner when an awaited send overflows the queue", async () => {
+  let drain!: () => void;
+  const failures: unknown[] = [];
+  const transport = new ChunkedTransport({
+    frameBytes: 32 * 1024 * 1024,
+    send: () =>
+      new Promise<void>((resolve) => {
+        drain = resolve;
+      }),
+    deliver: () => {},
+    onFailure: (error) => {
+      failures.push(error);
+    },
+  });
+  const first = transport.send(new Uint8Array(100 * 1024 * 1024));
+  const overflow = transport.send("extra");
+  await expect(overflow).rejects.toThrow("queue");
+  drain();
+  await first;
+  expect(failures).toHaveLength(1);
+});
+
+it("bounds retained reassembly memory for many one-byte chunks", async () => {
+  const { spawnSync } = await import("node:child_process");
+  // Exercise the built package as a Node consumer; CI builds it before protocol tests.
+  const entry = new URL("../dist/chunked-transport.js", import.meta.url).href;
+  const result = spawnSync(
+    process.execPath,
+    [
+      "--expose-gc",
+      "--input-type=module",
+      "-e",
+      `
+    import { ChunkedTransport } from ${JSON.stringify(entry)};
+    let delivered = 0;
+    const receiver = new ChunkedTransport({ frameBytes: 8, send() {}, deliver(frame) { delivered = frame.byteLength; } });
+    receiver.enabled = true;
+    global.gc();
+    const before = process.memoryUsage().heapUsed;
+    receiver.receive(new Uint8Array([0x31, 1, 1, 1, 65]));
+    for (let index = 0; index < 300000; index++) receiver.receive(new Uint8Array([0x31, 1, 1, 0, 65]));
+    global.gc();
+    const growth = process.memoryUsage().heapUsed - before;
+    receiver.receive(new Uint8Array([0x31, 1, 1, 2, 66]));
+    console.log(JSON.stringify({ growth, delivered }));
+  `,
+    ],
+    { encoding: "utf8", timeout: 15000 },
+  );
+  expect(result.status, result.stderr).toBe(0);
+  const observed = JSON.parse(result.stdout);
+  expect(observed.delivered).toBe(300002);
+  expect(observed.growth).toBeLessThan(8 * 1024 * 1024);
+}, 20000);
+
+it.each(["ASCII", "中", "🌍", "\ud800", "\udc00", "\ud800x"])(
+  "accounts for queued UTF-8 text %j exactly",
+  async (text) => {
+    let drain!: () => void;
+    let blocked = true;
+    const transport = new ChunkedTransport({
+      frameBytes: 1024,
+      send: () => {
+        if (blocked) {
+          blocked = false;
+          return new Promise<void>((resolve) => {
+            drain = resolve;
+          });
+        }
+      },
+      deliver: () => {},
+    });
+    const first = transport.send(new Uint8Array([1]));
+    const second = transport.send(text);
+    expect(transport.queuedByteLength).toBe(new TextEncoder().encode(text).byteLength);
+    drain();
+    await Promise.all([first, second]);
+  },
+);
+
+it("notifies the owner once when an accepted writer fails", async () => {
+  const failures: unknown[] = [];
+  const error = new Error("write failed");
+  const transport = new ChunkedTransport({
+    frameBytes: 1024,
+    deliver: () => {},
+    onFailure: (failure) => {
+      failures.push(failure);
+    },
+    send: () => Promise.reject(error),
+  });
+  await expect(transport.send("hello", { waitForDrain: true })).rejects.toThrow("write failed");
+  expect(failures).toEqual([error]);
+  expect(() => transport.send("again")).toThrow("Transport closed");
+  expect(failures).toEqual([error]);
+});
+
+it.each([false, true])(
+  "a pre-write rejection preserves the sender (chunked=%s)",
+  async (chunked) => {
+    const failures: unknown[] = [];
+    let reject = true;
+    const transport = new ChunkedTransport({
+      frameBytes: 8,
+      deliver: () => {},
+      onFailure: (error) => {
+        failures.push(error);
+      },
+      send: () => {
+        if (reject) throw new Error("capacity");
+      },
+    });
+    transport.enabled = chunked;
+    expect(() => transport.send("abcdefghij")).toThrow("capacity");
+    expect(failures).toEqual([]);
+    reject = false;
+    await transport.send("sibling");
+  },
+);
+
+it("a queued pre-write rejection does not poison the next logical send", async () => {
+  let drain!: () => void;
+  const failures: unknown[] = [];
+  const delivered: string[] = [];
+  const transport = new ChunkedTransport({
+    frameBytes: 1024,
+    deliver: () => {},
+    onFailure: (error) => {
+      failures.push(error);
+    },
+    send: (frame) => {
+      if (frame === "blocked")
+        return new Promise<void>((resolve) => {
+          drain = resolve;
+        });
+      if (frame === "reject") throw new Error("capacity");
+      delivered.push(frame as string);
+    },
+  });
+  const first = transport.send("blocked");
+  const rejected = transport.send("reject");
+  const sibling = transport.send("sibling");
+  const results = Promise.allSettled([first, rejected, sibling]);
+  drain();
+  expect((await results).map((result) => result.status)).toEqual([
+    "fulfilled",
+    "rejected",
+    "fulfilled",
+  ]);
+  expect(delivered).toEqual(["sibling"]);
+  expect(failures).toEqual([]);
+});
+
+it.each([false, true])("delivery errors leave framing usable (chunked=%s)", async (chunked) => {
+  let fail = true;
+  const delivered: (string | Uint8Array)[] = [];
+  const transport = new ChunkedTransport({
+    frameBytes: 64,
+    send: () => {},
+    deliver: (frame) => {
+      if (fail) throw new Error("listener failed");
+      delivered.push(frame);
+    },
+  });
+  transport.enabled = chunked;
+  const frame = chunked ? new Uint8Array([0x31, 1, 0, 3, 65]) : "A";
+  expect(() => transport.receive(frame)).toThrow("listener failed");
+  fail = false;
+  transport.receive(frame);
+  expect(delivered).toEqual(["A"]);
+  await transport.send("still connected");
+});
+
+it("unpaced transports retain ordinary outbound admission and accept inbound chunks", async () => {
+  const frames: unknown[] = [];
+  const delivered: unknown[] = [];
+  const transport = new ChunkedTransport({
+    frameBytes: 8,
+    supportsDrain: false,
+    send: (frame) => {
+      frames.push(frame);
+      if (typeof frame === "string" && frame.length > 8) throw new Error("single frame limit");
+    },
+    deliver: (frame) => {
+      delivered.push(frame);
+    },
+  });
+  transport.enabled = true;
+  expect(() => transport.send("too large for one frame")).toThrow("single frame limit");
+  expect(frames).toEqual(["too large for one frame"]);
+  transport.receive(new Uint8Array([0x31, 1, 0, 3, 65]));
+  expect(delivered).toEqual(["A"]);
+  await transport.send("small");
+});
diff --git a/packages/protocol/src/chunked-transport.ts b/packages/protocol/src/chunked-transport.ts
new file mode 100644
index 0000000000..8faa22cd96
--- /dev/null
+++ b/packages/protocol/src/chunked-transport.ts
@@ -0,0 +1,216 @@
+import { MAX_WEBSOCKET_MESSAGE_BYTES } from "./websocket-message-limit.js";
+
+type Frame = string | Uint8Array;
+
+/** A malformed wire frame, distinct from a consumer delivery failure. */
+export class ChunkedTransportProtocolError extends Error {}
+// Reserved outside the application binary opcode space. Version, kind, flags follow.
+const OPCODE = 0x31;
+const HEADER = 4;
+
+/** Connection-scoped ordered framing, below serialization and routing, above encryption. */
+export class ChunkedTransport {
+  enabled = false;
+  private assembly: Uint8Array | undefined;
+  private size = 0;
+  private kind = 0;
+  private closed = false;
+  private pending: Promise<void> | undefined;
+  private queuedBytes = 0;
+  private activeBytes = 0;
+
+  constructor(
+    private readonly io: {
+      frameBytes: number;
+      supportsDrain?: boolean;
+      send: (frame: Frame, waitForDrain: boolean) => void | Promise<void>;
+      deliver: (frame: Frame) => void;
+      onActivity?: () => void;
+      onFailure?: (error: unknown) => void;
+    },
+  ) {
+    if (io.frameBytes <= HEADER) throw new Error("Invalid transport frame budget");
+  }
+
+  /** Bytes waiting behind the active write; physical buffering owns the active frame. */
+  get queuedByteLength(): number {
+    return this.queuedBytes - this.activeBytes;
+  }
+  get isWriting(): boolean {
+    return this.pending !== undefined;
+  }
+
+  send(frame: Frame, options: { waitForDrain?: boolean; byteLength?: number } = {}): Promise<void> {
+    const byteLength = options.byteLength ?? frameByteLength(frame);
+    if (byteLength > MAX_WEBSOCKET_MESSAGE_BYTES) throw new Error("Logical message too large");
+    const chunk =
+      this.enabled && this.io.supportsDrain !== false && byteLength > this.io.frameBytes;
+    if (this.closed) throw new Error("Transport closed");
+    const write = () => {
+      if (this.closed) throw new Error("Transport closed");
+      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
+        ? this.sendChunks(
+            typeof frame === "string" ? new TextEncoder().encode(frame) : frame,
+            typeof frame === "string",
+          )
+        : this.io.send(frame, options.waitForDrain === true);
+      if (!result) return;
+      return result.catch((error) => {
+        this.fail(error);
+        throw error;
+      });
+    };
+    if (this.queuedBytes + byteLength > MAX_WEBSOCKET_MESSAGE_BYTES) {
+      const error = new Error("Logical output queue exceeded its byte limit");
+      this.fail(error);
+      const rejected = Promise.reject<void>(error);
+      void rejected.catch(() => {});
+      return rejected;
+    }
+    this.queuedBytes += byteLength;
+    let result: void | Promise<void>;
+    try {
+      result = this.pending ? this.pending.then(write) : write();
+    } catch (error) {
+      this.queuedBytes -= byteLength;
+      this.activeBytes = 0;
+      throw error;
+    }
+    if (!result) {
+      this.queuedBytes -= byteLength;
+      this.activeBytes = 0;
+      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;
+    });
+    return completion;
+  }
+
+  private sendChunks(bytes: Uint8Array, text: boolean): Promise<void> {
+    const capacity = this.io.frameBytes - HEADER;
+    const writeChunk = (offset: number) => {
+      if (this.closed) throw new Error("Transport closed");
+      const end = Math.min(bytes.byteLength, offset + capacity);
+      const wire = new Uint8Array(HEADER + end - offset);
+      wire.set([
+        OPCODE,
+        1,
+        text ? 0 : 1,
+        (offset === 0 ? 1 : 0) | (end === bytes.byteLength ? 2 : 0),
+      ]);
+      wire.set(bytes.subarray(offset, end), HEADER);
+      return this.io.send(wire, true);
+    };
+    const first = writeChunk(0);
+    return (async () => {
+      await first;
+      for (let offset = capacity; offset < bytes.byteLength; offset += capacity)
+        await writeChunk(offset);
+    })();
+  }
+
+  receive(frame: Frame): void {
+    if (this.closed) return;
+    let message: Frame | undefined;
+    try {
+      message = this.assemble(frame);
+    } catch (error) {
+      this.close();
+      throw new ChunkedTransportProtocolError(
+        error instanceof Error ? error.message : String(error),
+        { cause: error },
+      );
+    }
+    this.io.onActivity?.();
+    if (message !== undefined) this.io.deliver(message);
+  }
+
+  private assemble(frame: Frame): Frame | undefined {
+    if (typeof frame === "string" || frame[0] !== OPCODE) {
+      if (this.assembly) throw new Error("Interrupted chunked message");
+      return frame;
+    }
+    if (
+      !this.enabled ||
+      frame.length <= HEADER ||
+      frame[1] !== 1 ||
+      frame[2]! > 1 ||
+      (frame[3]! & ~3) !== 0
+    )
+      throw new Error("Invalid chunk header");
+    const start = (frame[3]! & 1) !== 0;
+    const end = (frame[3]! & 2) !== 0;
+    if (start === !!this.assembly) throw new Error("Invalid chunk sequence");
+    if (start) {
+      this.assembly = new Uint8Array(0);
+      this.kind = frame[2]!;
+      this.size = 0;
+    }
+    if (frame[2] !== this.kind) throw new Error("Chunk kind changed");
+    this.size += frame.length - HEADER;
+    if (this.size > MAX_WEBSOCKET_MESSAGE_BYTES) throw new Error("Logical message too large");
+    const payload = frame.subarray(HEADER);
+    if (this.assembly!.byteLength < this.size) {
+      const capacity = Math.min(
+        MAX_WEBSOCKET_MESSAGE_BYTES,
+        Math.max(this.size, this.assembly!.byteLength * 2, 16384),
+      );
+      const grown = new Uint8Array(capacity);
+      grown.set(this.assembly!.subarray(0, this.size - payload.byteLength));
+      this.assembly = grown;
+    }
+    this.assembly!.set(payload, this.size - payload.byteLength);
+    if (!end) return;
+    const data = this.assembly!.subarray(0, this.size);
+    this.assembly = undefined;
+    this.size = 0;
+    return this.kind === 0 ? new TextDecoder("utf-8", { fatal: true }).decode(data) : data.slice();
+  }
+
+  private fail(error: unknown): void {
+    if (this.closed) return;
+    this.close();
+    this.io.onFailure?.(error);
+  }
+
+  close(): void {
+    this.closed = true;
+    this.enabled = false;
+    this.assembly = undefined;
+    this.size = 0;
+  }
+}
+
+function frameByteLength(frame: Frame): number {
+  if (typeof frame !== "string") return frame.byteLength;
+  let bytes = 0;
+  for (let index = 0; index < frame.length; index++) {
+    const code = frame.charCodeAt(index);
+    if (code <= 0x7f) bytes++;
+    else if (code <= 0x7ff) bytes += 2;
+    else if (
+      code >= 0xd800 &&
+      code <= 0xdbff &&
+      frame.charCodeAt(index + 1) >= 0xdc00 &&
+      frame.charCodeAt(index + 1) <= 0xdfff
+    ) {
+      bytes += 4;
+      index++;
+    } else bytes += 3;
+  }
+  return bytes;
+}
diff --git a/packages/protocol/src/client-capabilities.ts b/packages/protocol/src/client-capabilities.ts
index a35852cc06..bb03d72b89 100644
--- a/packages/protocol/src/client-capabilities.ts
+++ b/packages/protocol/src/client-capabilities.ts
@@ -1,4 +1,6 @@
 export const CLIENT_CAPS = {
+  terminalChunkedReplay: "terminal_chunked_replay",
+  binaryChunkingV1: "binary_chunking_v1",
   helloRejection: "hello_rejection",
   // COMPAT(ownedSubscriptions): added in v0.8.0, remove legacy ownership after 2027-03-09.
   ownedSubscriptions: "owned_subscriptions",
@@ -44,8 +46,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/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.plugins.test.ts b/packages/protocol/src/messages.plugins.test.ts
index f266b65988..dce5a11bca 100644
--- a/packages/protocol/src/messages.plugins.test.ts
+++ b/packages/protocol/src/messages.plugins.test.ts
@@ -23,6 +23,29 @@ describe("plugin protocol compatibility", () => {
       expect(SessionOutboundMessageSchema.parse(message)).toEqual(message);
     },
   );
+  it.each([
+    { type: "plugin.catalog.get.request", requestId: "catalog" },
+    {
+      type: "plugin.catalog.get.request",
+      requestId: "catalog",
+      cachedClientBundles: [{ id: "example", clientBundleHash: "a".repeat(64) }],
+    },
+  ])("parses plugin catalog requests %j", (request) => {
+    expect(SessionInboundMessageSchema.parse(request)).toEqual(request);
+  });
+  it("parses plugin catalogs that leave out a client bundle the client already holds", () => {
+    const message = {
+      type: "plugin.catalog.get.response",
+      payload: {
+        requestId: "catalog",
+        plugins: [
+          { id: "cached", clientBundleHash: "a".repeat(64) },
+          { id: "changed", clientBundle: "bundle", clientBundleHash: "b".repeat(64) },
+        ],
+      },
+    };
+    expect(SessionOutboundMessageSchema.parse(message)).toEqual(message);
+  });
   it("preserves manifest metadata in plugin list responses", () => {
     const message = {
       type: "plugin.list.response",
@@ -349,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.ts b/packages/protocol/src/messages.ts
index 3034598f1e..2899bf56cb 100644
--- a/packages/protocol/src/messages.ts
+++ b/packages/protocol/src/messages.ts
@@ -229,6 +229,8 @@ export const MutableDaemonConfigSchema = z
       .optional(),
     app: z.object({ baseUrl: z.string() }).optional(),
     catalogRefreshTimeoutMs: z.number().int().positive().optional(),
+    // COMPAT(usageSetting): added in v0.14, remove after 2027-05-01.
+    usage: z.object({ enabled: z.boolean() }).optional(),
     browserTools: MutableBrowserToolsConfigSchema.default({ enabled: false }),
     providers: z.record(z.string(), MutableDaemonProviderConfigSchema).default({}),
     metadataGeneration: MutableMetadataGenerationConfigSchema.default({ providers: [] }),
@@ -237,6 +239,9 @@ export const MutableDaemonConfigSchema = z
     // COMPAT(idleRuntimeCleanupSetting): added in v0.13.0, keep optional while old daemons are supported.
     // Persisted host-wide value, applied live by the daemon.
     idleRuntimeCleanup: z.boolean().optional(),
+    // COMPAT(restartRecovery): added in v0.14.0, keep optional for older hosts.
+    resumeOnStartup: z.boolean().optional(),
+    resumePrompt: z.string().optional(),
     appendSystemPrompt: z.string().default(""),
     terminalProfiles: z.array(TerminalProfileSchema).optional(),
     agentProfiles: z.array(AgentProfileSchema).optional(),
@@ -253,6 +258,7 @@ export const MutableDaemonConfigPatchSchema = z
   .object({
     relay: MutableRelayConfigSchema.partial().optional(),
     mcp: z.object({ injectIntoAgents: z.boolean().optional() }).passthrough().optional(),
+    usage: z.object({ enabled: z.boolean() }).optional(),
     browserTools: MutableBrowserToolsConfigSchema.partial().optional(),
     providers: z
       .record(z.string(), MutableDaemonProviderConfigSchema.partial().passthrough())
@@ -262,6 +268,8 @@ export const MutableDaemonConfigPatchSchema = z
     autoArchiveAfterMerge: z.boolean().optional(),
     enableTerminalAgentHooks: z.boolean().optional(),
     idleRuntimeCleanup: z.boolean().optional(),
+    resumeOnStartup: z.boolean().optional(),
+    resumePrompt: z.string().optional(),
     appendSystemPrompt: z.string().optional(),
     terminalProfiles: z.array(TerminalProfileSchema).optional(),
     agentProfiles: z.array(AgentProfileSchema).optional(),
@@ -633,7 +641,9 @@ const ToolCallDetailPayloadSchema: z.ZodType<ToolCallDetail, unknown> = z.discri
       subAgentType: z.string().optional(),
       description: z.string().optional(),
       childSessionId: z.string().optional(),
-      log: z.string(),
+      // COMPAT(subagent-log): added in v0.14.1, remove after 2027-04-30. A sub-agent card is a
+      // launch marker; apps before v0.14.1 required `log`, so daemons still send it empty.
+      log: z.string().optional(),
       // Compat cruft for clients <= 0.1.65-beta.3 that required this field. Producers still
       // emit `[]`; nothing reads it. Drop the field (and the `[]` emissions) once those
       // clients are no longer in the field.
@@ -863,6 +873,7 @@ export const AgentSnapshotPayloadSchema = z.object({
   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(),
@@ -881,6 +892,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>;
@@ -894,6 +908,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(),
@@ -1027,6 +1042,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(),
@@ -1085,6 +1107,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(),
@@ -1360,6 +1390,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(),
@@ -1470,6 +1509,10 @@ export const DiagnosticsRequestSchema = z.object({
 export const PluginCatalogGetRequestSchema = z.object({
   type: z.literal("plugin.catalog.get.request"),
   requestId: z.string(),
+  /** Client bundles the client already holds; the daemon leaves out each one whose hash matches. */
+  cachedClientBundles: z
+    .array(z.object({ id: PluginIdSchema, clientBundleHash: z.string() }))
+    .optional(),
 });
 
 export const PluginListRequestSchema = z.object({
@@ -1589,6 +1632,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(),
 });
 
@@ -1771,7 +1822,8 @@ 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({}),
   requestId: z.string(),
@@ -1892,11 +1944,17 @@ export const RestartServerRequestMessageSchema = z.object({
   type: z.literal("restart_server_request"),
   reason: z.string().optional(),
   requestId: z.string(),
+  // Restart keeps terminals unless this is true. Daemons that predate
+  // `features.terminalsSurviveRestart` ignore it and close terminals anyway.
+  killTerminals: z.boolean().optional(),
 });
 
 export const ShutdownServerRequestMessageSchema = z.object({
   type: z.literal("shutdown_server_request"),
   requestId: z.string(),
+  // Shutdown closes terminals unless this is true. Gate on
+  // `features.terminalsSurviveRestart`: older daemons drop the field.
+  keepTerminals: z.boolean().optional(),
 });
 
 export const DaemonUpdateRequestMessageSchema = z.object({
@@ -1910,6 +1968,8 @@ export const AgentTimelineCursorSchema = z.object({
 });
 
 export const FetchAgentTimelineRequestMessageSchema = z.object({
+  // Keep available turns whole for tail/before pages; after catch-up stays incremental.
+  wholeTurns: z.boolean().optional(),
   type: z.literal("fetch_agent_timeline_request"),
   agentId: z.string(),
   requestId: z.string(),
@@ -1943,6 +2003,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(),
@@ -2154,6 +2228,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"),
@@ -2188,6 +2273,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({
@@ -2471,6 +2566,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(),
 });
 
@@ -3207,6 +3303,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",
@@ -3274,6 +3371,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   FetchRecentProviderSessionsRequestMessageSchema,
   FetchWorkspacesRequestMessageSchema,
   ProjectListRequestMessageSchema,
+  ProjectSuggestionsRequestSchema,
   FetchAgentRequestMessageSchema,
   DeleteAgentRequestMessageSchema,
   ArchiveAgentRequestMessageSchema,
@@ -3284,6 +3382,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   ProjectRemoveRequestSchema,
   WorkspaceTitleSetRequestSchema,
   WorkspacePinSetRequestSchema,
+  WorkspaceBaseBranchSetRequestSchema,
   WorkspaceLabelListRequestSchema,
   WorkspaceLabelAssignmentSetRequestSchema,
   WorkspaceLabelUpdateRequestSchema,
@@ -3291,6 +3390,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   WorkspaceLabelDeleteInspectRequestSchema,
   WorkspaceRecoveryInspectRequestSchema,
   WorkspaceRecoveryRestoreRequestSchema,
+  WorkspaceArchiveUndoRequestSchema,
   SetVoiceModeMessageSchema,
   SendAgentMessageRequestSchema,
   WaitForFinishRequestSchema,
@@ -3317,6 +3417,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   PluginDisableRequestSchema,
   PluginRemoveRequestSchema,
   PluginRpcInvokeRequestSchema,
+  PluginRpcSubscribeRequestSchema,
   AgentTimelineAppendRequestSchema,
   AgentSkillsGetStatusRequestSchema,
   AgentSkillsReconcileRequestSchema,
@@ -3352,6 +3453,8 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   AgentTimelineSearchRequestMessageSchema,
   AgentTimelineListPromptsRequestMessageSchema,
   ProviderSubagentListRequestMessageSchema,
+  AgentBackgroundWorkListRequestMessageSchema,
+  AgentBackgroundWorkStopRequestMessageSchema,
   ProviderSubagentTimelineRequestMessageSchema,
   SetAgentTimelineSubscriptionRequestMessageSchema,
   AgentForkContextRequestMessageSchema,
@@ -3653,9 +3756,13 @@ 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(),
+        // COMPAT(usageSetting): added in v0.14, remove after 2027-05-01.
+        usageSetting: z.boolean().optional(),
         usageSources: z.boolean().optional(),
         // COMPAT(providersSnapshotCwd): added in v0.3.2, remove gate after 2027-02-10.
         providersSnapshotCwd: z.boolean().optional(),
@@ -3663,6 +3770,8 @@ export const ServerInfoStatusPayloadSchema = z
         directorySync: z.boolean().optional(),
         // COMPAT(workspaceLabels): added in v0.5.0, remove after 2027-08-14.
         workspaceLabels: 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.
@@ -3715,16 +3824,22 @@ 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.
         idleRuntimeCleanupSetting: z.boolean().optional(),
+        // COMPAT(restartRecovery): added in v0.14.0, remove gate after 2027-04-28.
+        resumeOnStartupSetting: z.boolean().optional(),
         // COMPAT(terminalRestoreModes): added in v0.1.81, remove gate after 2026-11-23.
         "terminal-restore-modes": z.boolean().optional(),
         // COMPAT(terminalInputModeReplay): added in v0.2.6, remove gate after 2027-02-02.
         "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(agentTimelinePromptIndex): added in v0.2.X, drop the gate when floor >= v0.2.X.
@@ -3743,6 +3858,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.
@@ -3757,14 +3874,21 @@ export const ServerInfoStatusPayloadSchema = z
         daemonDiagnostics: z.boolean().optional(),
         // COMPAT(daemonSelfUpdate): added in v0.1.93, remove gate after 2026-12-13.
         daemonSelfUpdate: z.boolean().optional(),
+        // COMPAT(terminalsSurviveRestart): added in v0.12.0, remove gate after 2027-04-21.
+        terminalsSurviveRestart: z.boolean().optional(),
         // COMPAT(agentForkContext): added in v0.1.102, remove gate after 2026-12-28.
         agentForkContext: z.boolean().optional(),
         // COMPAT(agentForkContextCursor): added in v0.1.108, remove gate after 2027-01-14.
         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(),
         // COMPAT(providerSubagentNesting): added in v0.7, remove gate after 2027-03-04.
         providerSubagentNesting: z.boolean().optional(),
         // COMPAT(workspacePinning): added in v0.1.107, remove gate after 2027-01-12.
@@ -3784,6 +3908,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.
@@ -3805,6 +3931,7 @@ export const ServerInfoStatusPayloadSchema = z
         selectiveAgentTimeline: z.boolean().optional(),
         explicitEventSubscriptions: z.boolean().optional(),
         ownedSubscriptions: z.boolean().optional(),
+        binaryChunkingV1: z.boolean().optional(),
         workspaceSetupObservation: z.boolean().optional(),
         workspaceSortTimes: z.boolean().optional(),
         // COMPAT(canonicalSubmittedPrompts): added in v0.2.6, remove gate after 2027-01-30.
@@ -4106,6 +4233,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(),
@@ -4468,6 +4597,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({
@@ -4693,6 +4840,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(),
   }),
 });
 
@@ -4827,6 +4976,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({
@@ -5118,6 +5312,22 @@ export const DaemonGetStatusResponseSchema = z.object({
           error: z.string().nullable().optional(),
         }),
       ),
+      // Processes a terminal cleanup on this host (a kill restart or stop) could not confirm
+      // gone; empty when every cleanup finished. Daemons without terminalsSurviveRestart have
+      // no such cleanup and omit it.
+      terminalCleanupUnconfirmed: z
+        .array(
+          z.object({
+            pid: z.number(),
+            role: z.string(),
+            reason: z.string(),
+            detail: z.string(),
+          }),
+        )
+        .optional(),
+      // Set when this host's terminals are held by a terminal worker from a newer Paseo, which
+      // this daemon leaves running but cannot drive: why, and what the user can do.
+      terminalsUnavailable: z.string().optional(),
     })
     .passthrough(),
 });
@@ -5310,6 +5520,7 @@ const CheckoutStatusCommonSchema = z.object({
   cwd: z.string(),
   error: CheckoutErrorSchema.nullable(),
   requestId: z.string(),
+  baseRefExact: 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
@@ -6754,7 +6965,10 @@ export const PluginCatalogGetResponseSchema = z.object({
     plugins: z.array(
       z.object({
         id: PluginIdSchema,
-        clientBundle: z.string(),
+        /** Left out only when the request listed this plugin with the same `clientBundleHash`. */
+        clientBundle: z.string().optional(),
+        /** SHA-256 of `clientBundle`, hex encoded. */
+        clientBundleHash: z.string().optional(),
         requirements: PluginRequirementsSchema.optional(),
       }),
     ),
@@ -6907,10 +7121,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({
@@ -6984,6 +7214,9 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   PluginDisableResponseSchema,
   PluginRemoveResponseSchema,
   PluginRpcInvokeResponseSchema,
+  PluginRpcSubscribeResponseSchema,
+  PluginRpcEventSchema,
+  PluginRpcClosedSchema,
   AgentTimelineAppendResponseSchema,
   AgentSkillsGetStatusResponseSchema,
   AgentSkillsReconcileResponseSchema,
@@ -7015,6 +7248,7 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   WorkspaceLabelDeleteInspectResponseSchema,
   ProjectUpdateMessageSchema,
   ProjectListResponseMessageSchema,
+  ProjectSuggestionsResponseSchema,
   ScriptStatusUpdateMessageSchema,
   WorkspaceSetupProgressMessageSchema,
   WorkspaceSetupStatusResponseMessageSchema,
@@ -7046,6 +7280,9 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   ProviderSubagentListResponseMessageSchema,
   ProviderSubagentTimelineResponseMessageSchema,
   ProviderSubagentUpdateMessageSchema,
+  AgentBackgroundWorkListResponseMessageSchema,
+  AgentBackgroundWorkStopResponseMessageSchema,
+  AgentBackgroundWorkUpdateMessageSchema,
   SetAgentTimelineSubscriptionResponseMessageSchema,
   AgentAttentionRequiredMessageSchema,
   AgentForkContextResponseMessageSchema,
@@ -7085,8 +7322,10 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   ProjectRemoveResponseSchema,
   WorkspaceTitleSetResponseSchema,
   WorkspacePinSetResponseSchema,
+  WorkspaceBaseBranchSetResponseSchema,
   WorkspaceRecoveryInspectResponseSchema,
   WorkspaceRecoveryRestoreResponseSchema,
+  WorkspaceArchiveUndoResponseSchema,
   WaitForFinishResponseMessageSchema,
   AgentPermissionRequestMessageSchema,
   AgentPermissionResolvedMessageSchema,
@@ -7300,6 +7539,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>;
@@ -7379,6 +7619,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>;
@@ -7443,8 +7686,10 @@ 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 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>;
@@ -7687,6 +7932,7 @@ export const WSHelloMessageSchema = z.object({
       [CLIENT_CAPS.providerSnapshotReferences]: z.boolean().optional(),
       [CLIENT_CAPS.timelineReplacementInvalidation]: 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 d6b2bc02ff..a15c1ae1be 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",
@@ -200,8 +257,8 @@ describe("wire schema compatibility", () => {
     });
   });
 
-  test("sub_agent tool-call payload still parses against the v0.1.65-beta.3 schema", () => {
-    const parsed = LegacySubAgentToolCallSchema.parse({
+  test("a sub-agent launch marker still parses against the v0.1.65-beta.3 schema", () => {
+    const card = {
       type: "tool_call",
       callId: "call-sub-agent-1",
       name: "Task",
@@ -212,12 +269,26 @@ describe("wire schema compatibility", () => {
         subAgentType: "Explore",
         description: "Inspect repository structure",
         childSessionId: "child-session-1",
-        log: "[Read] README.md",
+        log: "",
         actions: [],
       },
-    });
+    } as const;
 
-    expect(parsed.detail.actions).toEqual([]);
+    const parsed = LegacySubAgentToolCallSchema.parse(JSON.parse(JSON.stringify(card)));
+    expect(parsed.detail).toMatchObject({ log: "", actions: [] });
+    const { log: _log, ...withoutLog } = card.detail;
+    expect(LegacySubAgentToolCallSchema.safeParse({ ...card, detail: withoutLog }).success).toBe(
+      false,
+    );
+    expect(AgentTimelineItemPayloadSchema.parse({ ...card, detail: withoutLog })).toMatchObject({
+      detail: { type: "sub_agent", description: "Inspect repository structure" },
+    });
+    expect(
+      AgentTimelineItemPayloadSchema.parse({
+        ...card,
+        detail: { ...card.detail, log: "[Read] README.md" },
+      }),
+    ).toMatchObject({ detail: { log: "[Read] README.md" } });
   });
 
   test("old clients parse agent snapshots with rewind capabilities", () => {
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/paseo-tool-presentation/catalog.ts b/packages/protocol/src/paseo-tool-presentation/catalog.ts
index 0c35b128b7..4844b7ceb7 100644
--- a/packages/protocol/src/paseo-tool-presentation/catalog.ts
+++ b/packages/protocol/src/paseo-tool-presentation/catalog.ts
@@ -19,6 +19,7 @@ export interface PaseoToolDetailSpec {
 
 export interface PaseoToolEntry {
   label: string;
+  completedLabel: string;
   context?: PaseoToolContext;
   detail?: PaseoToolDetailSpec;
 }
@@ -123,14 +124,24 @@ function baseName(value: unknown): string | undefined {
   return value.split(/[\\/]/).findLast((segment) => segment.length > 0);
 }
 
-function browser(label: string, context?: PaseoToolContext): PaseoToolEntry {
-  return { label, ...(context ? { context } : {}), detail: { inputOrder: BROWSER_FIELDS } };
+function browser(
+  label: string,
+  completedLabel: string,
+  context?: PaseoToolContext,
+): PaseoToolEntry {
+  return {
+    label,
+    completedLabel,
+    ...(context ? { context } : {}),
+    detail: { inputOrder: BROWSER_FIELDS },
+  };
 }
 
 export const PASEO_TOOL_CATALOG = {
   // Agents
   create_agent: {
     label: "Create agent",
+    completedLabel: "Created agent",
     context: field("title", "initialPrompt"),
     detail: {
       promptField: "initialPrompt",
@@ -140,6 +151,7 @@ export const PASEO_TOOL_CATALOG = {
   },
   send_agent_prompt: {
     label: "Send message",
+    completedLabel: "Sent message",
     context: field("prompt"),
     detail: {
       promptField: "prompt",
@@ -149,42 +161,55 @@ export const PASEO_TOOL_CATALOG = {
   },
   get_agent_status: {
     label: "Check agent",
+    completedLabel: "Checked agent",
     context: targetAgent(),
     detail: { inputOrder: ["agentId"] },
   },
   get_agent_activity: {
     label: "Read agent activity",
+    completedLabel: "Read agent activity",
     context: targetAgent(),
     detail: { inputOrder: ["agentId", "limit"] },
   },
   list_agents: {
     label: "List agents",
+    completedLabel: "Listed agents",
     detail: { inputOrder: ["cwd", "statuses", "sinceHours", "limit", "includeArchived"] },
   },
   update_agent: {
     label: "Update agent",
+    completedLabel: "Updated agent",
     context: fieldOrTargetAgent("name"),
     detail: { inputOrder: AGENT_FIELDS },
   },
   set_agent_mode: {
     label: "Set agent mode",
+    completedLabel: "Set agent mode",
     context: field("modeId"),
     detail: { inputOrder: ["agentId", "modeId"] },
   },
   cancel_agent: {
     label: "Cancel agent",
+    completedLabel: "Canceled agent",
     context: targetAgent(),
     detail: { inputOrder: ["agentId"] },
   },
   archive_agent: {
     label: "Archive agent",
+    completedLabel: "Archived agent",
     context: targetAgent(),
     detail: { inputOrder: ["agentId"] },
   },
-  kill_agent: { label: "Kill agent", context: targetAgent(), detail: { inputOrder: ["agentId"] } },
-  list_pending_permissions: { label: "List permissions" },
+  kill_agent: {
+    label: "Kill agent",
+    completedLabel: "Killed agent",
+    context: targetAgent(),
+    detail: { inputOrder: ["agentId"] },
+  },
+  list_pending_permissions: { label: "List permissions", completedLabel: "Listed permissions" },
   respond_to_permission: {
     label: "Respond to permission",
+    completedLabel: "Responded to permission",
     context: targetAgent(),
     detail: { inputOrder: ["agentId", "requestId", "response"] },
   },
@@ -192,32 +217,41 @@ export const PASEO_TOOL_CATALOG = {
   // Workspaces and scripts
   create_workspace: {
     label: "Create workspace",
+    completedLabel: "Created workspace",
     context: workspaceContext(),
     detail: { inputOrder: WORKSPACE_FIELDS, outputFields: ["workspaceId", "projectId"] },
   },
-  list_hosts: { label: "List hosts" },
-  list_workspaces: { label: "List workspaces" },
+  list_hosts: { label: "List hosts", completedLabel: "Listed hosts" },
+  list_workspaces: { label: "List workspaces", completedLabel: "Listed workspaces" },
   rename_workspace: {
     label: "Rename workspace",
+    completedLabel: "Renamed workspace",
     context: field("title"),
     detail: { inputOrder: ["title", "workspaceId"] },
   },
   archive_workspace: {
     label: "Archive workspace",
+    completedLabel: "Archived workspace",
     context: field("workspaceId"),
     detail: {
       inputOrder: ["workspaceId"],
       outputFields: ["workspaceId", "archivedAgentIds", "removedDirectory"],
     },
   },
-  list_workspace_scripts: { label: "List scripts", detail: { inputOrder: ["workspaceId"] } },
+  list_workspace_scripts: {
+    label: "List scripts",
+    completedLabel: "Listed scripts",
+    detail: { inputOrder: ["workspaceId"] },
+  },
   start_workspace_script: {
     label: "Start script",
+    completedLabel: "Started script",
     context: field("scriptName"),
     detail: { inputOrder: ["workspaceId", "scriptName"] },
   },
   stop_workspace_script: {
     label: "Stop script",
+    completedLabel: "Stopped script",
     context: field("scriptName"),
     detail: { inputOrder: ["workspaceId", "scriptName"] },
   },
@@ -225,22 +259,30 @@ export const PASEO_TOOL_CATALOG = {
   // Terminals
   create_terminal: {
     label: "Create terminal",
+    completedLabel: "Created terminal",
     context: field("name", "command"),
     detail: { inputOrder: ["cwd", "workspaceId", "name", "command"] },
   },
-  list_terminals: { label: "List terminals", detail: { inputOrder: ["cwd", "all"] } },
+  list_terminals: {
+    label: "List terminals",
+    completedLabel: "Listed terminals",
+    detail: { inputOrder: ["cwd", "all"] },
+  },
   capture_terminal: {
     label: "Read terminal",
+    completedLabel: "Read terminal",
     context: field("terminalId"),
     detail: { inputOrder: ["terminalId", "lines"] },
   },
   send_terminal_keys: {
     label: "Send keys",
+    completedLabel: "Sent keys",
     context: field("keys"),
     detail: { inputOrder: ["terminalId", "keys", "literal"] },
   },
   kill_terminal: {
     label: "Kill terminal",
+    completedLabel: "Killed terminal",
     context: field("terminalId"),
     detail: { inputOrder: ["terminalId"] },
   },
@@ -248,6 +290,7 @@ export const PASEO_TOOL_CATALOG = {
   // Schedules and heartbeats
   create_schedule: {
     label: "Create schedule",
+    completedLabel: "Created schedule",
     context: field("name", "cron"),
     detail: {
       promptField: "prompt",
@@ -257,6 +300,7 @@ export const PASEO_TOOL_CATALOG = {
   },
   create_heartbeat: {
     label: "Create heartbeat",
+    completedLabel: "Created heartbeat",
     context: field("name", "cron"),
     detail: {
       promptField: "prompt",
@@ -266,79 +310,93 @@ export const PASEO_TOOL_CATALOG = {
   },
   update_schedule: {
     label: "Update schedule",
+    completedLabel: "Updated schedule",
     context: field("name", "id"),
     detail: { promptField: "prompt", inputOrder: AUTOMATION_FIELDS },
   },
-  list_schedules: { label: "List schedules" },
+  list_schedules: { label: "List schedules", completedLabel: "Listed schedules" },
   inspect_schedule: {
     label: "Inspect schedule",
+    completedLabel: "Inspected schedule",
     context: field("id"),
     detail: { inputOrder: ["id"] },
   },
   schedule_logs: {
     label: "Read schedule logs",
+    completedLabel: "Read schedule logs",
     context: field("id"),
     detail: { inputOrder: ["id"] },
   },
   run_schedule_once: {
     label: "Run schedule",
+    completedLabel: "Ran schedule",
+    context: field("id"),
+    detail: { inputOrder: ["id"] },
+  },
+  pause_schedule: {
+    label: "Pause schedule",
+    completedLabel: "Paused schedule",
     context: field("id"),
     detail: { inputOrder: ["id"] },
   },
-  pause_schedule: { label: "Pause schedule", context: field("id"), detail: { inputOrder: ["id"] } },
   resume_schedule: {
     label: "Resume schedule",
+    completedLabel: "Resumed schedule",
     context: field("id"),
     detail: { inputOrder: ["id"] },
   },
   delete_schedule: {
     label: "Delete schedule",
+    completedLabel: "Deleted schedule",
     context: field("id"),
     detail: { inputOrder: ["id"] },
   },
   delete_heartbeat: {
     label: "Delete heartbeat",
+    completedLabel: "Deleted heartbeat",
     context: field("id"),
     detail: { inputOrder: ["id"] },
   },
 
   // Providers
-  list_providers: { label: "List providers" },
+  list_providers: { label: "List providers", completedLabel: "Listed providers" },
   list_models: {
     label: "List models",
+    completedLabel: "Listed models",
     context: field("provider"),
     detail: { inputOrder: ["provider"] },
   },
-  list_profiles: { label: "List profiles" },
+  list_profiles: { label: "List profiles", completedLabel: "Listed profiles" },
   inspect_provider: {
     label: "Inspect provider",
+    completedLabel: "Inspected provider",
     context: field("provider"),
     detail: { inputOrder: ["provider", "cwd", "settings"] },
   },
 
   // Browser
-  browser_list_tabs: browser("List browser tabs"),
-  browser_new_tab: browser("Open browser tab", field("url")),
-  browser_close_tab: browser("Close browser tab", field("browserId")),
-  browser_navigate: browser("Navigate", field("url")),
-  browser_back: browser("Go back"),
-  browser_forward: browser("Go forward"),
-  browser_reload: browser("Reload page"),
-  browser_snapshot: browser("Snapshot page"),
-  browser_screenshot: browser("Take screenshot"),
-  browser_click: browser("Click element", field("ref")),
-  browser_hover: browser("Hover element", field("ref")),
-  browser_drag: browser("Drag element", field("sourceRef")),
-  browser_fill: browser("Fill field", field("ref")),
-  browser_select: browser("Select option", field("value", "ref")),
-  browser_type: browser("Type text", field("text")),
-  browser_keypress: browser("Press key", field("key")),
-  browser_upload: browser("Upload files", field("filePaths")),
-  browser_wait: browser("Wait for page", field("text", "url")),
-  browser_scroll: browser("Scroll page"),
-  browser_resize: browser("Resize browser", viewportContext()),
-  browser_logs: browser("Read browser logs"),
-  browser_evaluate: browser("Run JavaScript", field("function")),
+  browser_list_tabs: browser("List browser tabs", "Listed browser tabs"),
+  browser_new_tab: browser("Open browser tab", "Opened browser tab", field("url")),
+  browser_close_tab: browser("Close browser tab", "Closed browser tab", field("browserId")),
+  browser_navigate: browser("Navigate", "Navigated", field("url")),
+  browser_back: browser("Go back", "Went back"),
+  browser_forward: browser("Go forward", "Went forward"),
+  browser_reload: browser("Reload page", "Reloaded page"),
+  browser_snapshot: browser("Snapshot page", "Snapshotted page"),
+  browser_screenshot: browser("Take screenshot", "Took screenshot"),
+  browser_click: browser("Click element", "Clicked element", field("ref")),
+  browser_hover: browser("Hover element", "Hovered element", field("ref")),
+  browser_drag: browser("Drag element", "Dragged element", field("sourceRef")),
+  browser_fill: browser("Fill field", "Filled field", field("ref")),
+  browser_select: browser("Select option", "Selected option", field("value", "ref")),
+  browser_type: browser("Type text", "Typed text", field("text")),
+  browser_keypress: browser("Press key", "Pressed key", field("key")),
+  browser_upload: browser("Upload files", "Uploaded files", field("filePaths")),
+  browser_wait: browser("Wait for page", "Waited for page", field("text", "url")),
+  browser_scroll: browser("Scroll page", "Scrolled page"),
+  browser_resize: browser("Resize browser", "Resized browser", viewportContext()),
+  browser_logs: browser("Read browser logs", "Read browser logs"),
+  browser_evaluate: browser("Run JavaScript", "Ran JavaScript", field("function")),
 } satisfies Record<string, PaseoToolEntry>;
 
 export type PaseoToolName = keyof typeof PASEO_TOOL_CATALOG;
diff --git a/packages/protocol/src/paseo-tool-presentation/index.ts b/packages/protocol/src/paseo-tool-presentation/index.ts
index c04606a231..e5395a9e62 100644
--- a/packages/protocol/src/paseo-tool-presentation/index.ts
+++ b/packages/protocol/src/paseo-tool-presentation/index.ts
@@ -28,6 +28,8 @@ export const PASEO_TOOL_NAMES = Object.keys(PASEO_TOOL_CATALOG) as readonly Pase
 
 /** Returns null for tools outside the Paseo namespace. */
 export function buildPaseoToolDisplay(input: PaseoToolDisplayInput): PaseoToolDisplay | null {
+  // Canonical details own internal lifecycle rows such as worktree setup.
+  if (input.detail.type !== "unknown") return null;
   const leafName = paseoLeafName(input.toolName);
   if (!leafName) return null;
   const entry = getPaseoToolEntry(leafName);
@@ -39,6 +41,13 @@ export function buildPaseoToolDisplay(input: PaseoToolDisplayInput): PaseoToolDi
   return { displayName: entry.label, ...(summary ? { summary } : {}) };
 }
 
+/** A semantic action label for summaries, sharing the tool presentation catalog. */
+export function getPaseoToolActionLabel(toolName: string): string | null {
+  const leafName = paseoLeafName(toolName);
+  if (!leafName) return null;
+  return getPaseoToolEntry(leafName)?.completedLabel ?? humanizeLeafName(leafName);
+}
+
 /** The agent a Paseo call acts on, so callers can resolve its title. */
 export function getPaseoToolTargetAgentId(
   toolName: string,
@@ -49,7 +58,11 @@ export function getPaseoToolTargetAgentId(
 }
 
 function paseoLeafName(toolName: string): string | null {
-  return isPaseoToolName(toolName) ? getPaseoToolLeafName(toolName) : null;
+  if (isPaseoToolName(toolName)) return getPaseoToolLeafName(toolName);
+  const normalized = toolName.trim().toLowerCase();
+  return normalized.startsWith("paseo_") && !normalized.startsWith("paseo__")
+    ? normalized.slice("paseo_".length)
+    : null;
 }
 
 function readToolInput(detail: ToolCallDetail): Readonly<Record<string, unknown>> {
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/terminal-snapshot.test.ts b/packages/protocol/src/terminal-snapshot.test.ts
deleted file mode 100644
index 96d82a9205..0000000000
--- a/packages/protocol/src/terminal-snapshot.test.ts
+++ /dev/null
@@ -1,79 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { renderTerminalSnapshotToAnsi } from "./terminal-snapshot";
-import type { TerminalState } from "./messages";
-
-function cells(text: string): TerminalState["grid"][number] {
-  return [...text].map((char) => ({ char }));
-}
-
-describe("renderTerminalSnapshotToAnsi", () => {
-  it("renders soft-wrapped rows as one contiguous logical line when wrap flags are present", () => {
-    // The server soft-wrapped one logical line "ABCDEFGHIJKLMNOP" at 10 cols into
-    // two grid rows. gridWrapped[0] = true marks row 0 as continuing into row 1.
-    const state: TerminalState = {
-      rows: 2,
-      cols: 10,
-      scrollback: [],
-      scrollbackWrapped: [],
-      grid: [cells("ABCDEFGHIJ"), cells("KLMNOP")],
-      gridWrapped: [true, false],
-      cursor: { row: 1, col: 6 },
-    };
-
-    const ansi = renderTerminalSnapshotToAnsi(state);
-
-    // The rows must arrive unbroken so xterm re-wraps them itself (and can later
-    // reflow them) — no hard newline injected between "...IJ" and "KL...".
-    expect(ansi).toContain("ABCDEFGHIJKLMNOP");
-    // Auto-wrap must stay enabled; disabling it (ESC[?7l) is what makes xterm mark
-    // the rows non-wrapped and refuse to reflow them on resize.
-    expect(ansi).not.toContain("[?7l");
-  });
-
-  it("falls back to verbatim per-row replay when wrap flags are absent (old daemon)", () => {
-    // No gridWrapped/scrollbackWrapped: the client cannot tell soft-wraps from hard
-    // newlines, so it must keep today's exact behaviour rather than guess.
-    const state: TerminalState = {
-      rows: 2,
-      cols: 10,
-      scrollback: [],
-      grid: [cells("ABCDEFGHIJ"), cells("KLMNOP")],
-      cursor: { row: 1, col: 6 },
-    };
-
-    const ansi = renderTerminalSnapshotToAnsi(state);
-
-    expect(ansi).toContain("[?7l");
-    expect(ansi).toContain("ABCDEFGHIJ\r\nKLMNOP");
-  });
-});
-
-describe("renderTerminalSnapshotToAnsi wide chars", () => {
-  it("skips wide-char continuation cells so the glyph keeps its two columns", () => {
-    // The daemon captures "통" as the glyph followed by an empty continuation
-    // cell. Emitting anything for that cell pushes the rest of the row right.
-    const state: TerminalState = {
-      rows: 1,
-      cols: 10,
-      scrollback: [],
-      grid: [[{ char: "통" }, { char: "" }, { char: "합" }, { char: "" }, { char: "!" }]],
-      cursor: { row: 0, col: 5 },
-    };
-
-    expect(renderTerminalSnapshotToAnsi(state)).toContain("통합!");
-  });
-
-  it("replays snapshots from an old daemon verbatim, including its continuation spaces", () => {
-    // Old daemons already collapsed the continuation to " ". The serializer
-    // cannot tell that apart from a real space, so it must not guess.
-    const state: TerminalState = {
-      rows: 1,
-      cols: 10,
-      scrollback: [],
-      grid: [cells("통 합 !")],
-      cursor: { row: 0, col: 6 },
-    };
-
-    expect(renderTerminalSnapshotToAnsi(state)).toContain("통 합 !");
-  });
-});
diff --git a/packages/protocol/src/terminal-snapshot.ts b/packages/protocol/src/terminal-snapshot.ts
deleted file mode 100644
index 1860067573..0000000000
--- a/packages/protocol/src/terminal-snapshot.ts
+++ /dev/null
@@ -1,224 +0,0 @@
-import type { TerminalCell, TerminalState } from "./messages.js";
-
-interface TerminalStyle {
-  fg: number | undefined;
-  bg: number | undefined;
-  fgMode: number | undefined;
-  bgMode: number | undefined;
-  bold: boolean;
-  italic: boolean;
-  underline: boolean;
-  dim: boolean;
-  inverse: boolean;
-  strikethrough: boolean;
-}
-
-const DEFAULT_STYLE: TerminalStyle = {
-  fg: undefined,
-  bg: undefined,
-  fgMode: undefined,
-  bgMode: undefined,
-  bold: false,
-  italic: false,
-  underline: false,
-  dim: false,
-  inverse: false,
-  strikethrough: false,
-};
-
-export function renderTerminalSnapshotToAnsi(state: TerminalState): string {
-  const rows = [...state.scrollback, ...state.grid];
-  const wrapFlags = [...(state.scrollbackWrapped ?? []), ...(state.gridWrapped ?? [])];
-  // Soft-wrapped lines can only be re-wrapped on resize when we know which rows
-  // were continuations. With that per-row flag we replay each logical line as one
-  // unbroken run (autowrap on) so xterm marks the continuations wrapped and reflows
-  // them. Without it (old daemon) we keep the verbatim per-row replay: autowrap off
-  // plus a hard newline per row.
-  const hasWrapInfo = wrapFlags.length === rows.length;
-  const lines: string[] = hasWrapInfo ? [] : ["\u001b[?7l"];
-
-  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
-    const row = rows[rowIndex] ?? [];
-    const continuesToNextRow = hasWrapInfo && wrapFlags[rowIndex] === true;
-    // A continuation row must fill the full width so the next row first cell
-    // triggers xterm auto-wrap, which is what marks the row wrapped/reflowable.
-    lines.push(renderTerminalRow(row, continuesToNextRow ? state.cols : undefined));
-    if (rowIndex < rows.length - 1 && !continuesToNextRow) {
-      lines.push("\r\n");
-    }
-  }
-
-  lines.push("\u001b[0m");
-  const cursorPresentationAnsi = renderCursorPresentationToAnsi(state.cursor);
-  if (cursorPresentationAnsi) {
-    lines.push(cursorPresentationAnsi);
-  }
-  lines.push(`\u001b[${state.cursor.row + 1};${state.cursor.col + 1}H`);
-  lines.push(state.cursor.hidden ? "\u001b[?25l" : "\u001b[?25h");
-  if (!hasWrapInfo) {
-    lines.push("\u001b[?7h");
-  }
-  return lines.join("");
-}
-
-function renderCursorPresentationToAnsi(cursor: TerminalState["cursor"]): string | null {
-  if (!cursor.style) {
-    return null;
-  }
-
-  const cursorStyleCode = (() => {
-    if (cursor.style === "block") {
-      return cursor.blink === false ? 2 : 1;
-    }
-    if (cursor.style === "underline") {
-      return cursor.blink === false ? 4 : 3;
-    }
-    return cursor.blink === false ? 6 : 5;
-  })();
-
-  return `\u001b[${cursorStyleCode} q`;
-}
-
-function renderTerminalRow(row: TerminalCell[], padToCols?: number): string {
-  const output: string[] = [];
-  const contentLength = getTerminalRowLength(row);
-  const length = padToCols !== undefined ? Math.max(contentLength, padToCols) : contentLength;
-  let previousStyle = DEFAULT_STYLE;
-
-  for (let index = 0; index < length; index += 1) {
-    const cell = row[index] ?? { char: " " };
-    // An empty char marks a wide-char continuation cell. The glyph in the
-    // previous cell already advances the cursor two columns, so emitting
-    // anything here would shift the rest of the row one column right.
-    if (cell.char === "") {
-      continue;
-    }
-    const nextStyle = getTerminalStyle(cell);
-    if (!terminalStylesEqual(previousStyle, nextStyle)) {
-      output.push(styleToAnsi(nextStyle));
-      previousStyle = nextStyle;
-    }
-    output.push(cell.char || " ");
-  }
-
-  if (!terminalStylesEqual(previousStyle, DEFAULT_STYLE)) {
-    output.push("\u001b[0m");
-  }
-
-  return output.join("");
-}
-
-function getTerminalRowLength(row: TerminalCell[]): number {
-  for (let index = row.length - 1; index >= 0; index -= 1) {
-    const cell = row[index];
-    if (!cell) {
-      continue;
-    }
-    if (cell.char !== " ") {
-      return index + 1;
-    }
-    if (
-      cell.fg !== undefined ||
-      cell.bg !== undefined ||
-      cell.fgMode !== undefined ||
-      cell.bgMode !== undefined ||
-      cell.bold ||
-      cell.italic ||
-      cell.underline ||
-      cell.dim ||
-      cell.inverse ||
-      cell.strikethrough
-    ) {
-      return index + 1;
-    }
-  }
-  return 0;
-}
-
-function getTerminalStyle(cell: TerminalCell): TerminalStyle {
-  return {
-    fg: cell.fg,
-    bg: cell.bg,
-    fgMode: cell.fgMode,
-    bgMode: cell.bgMode,
-    bold: Boolean(cell.bold),
-    italic: Boolean(cell.italic),
-    underline: Boolean(cell.underline),
-    dim: Boolean(cell.dim),
-    inverse: Boolean(cell.inverse),
-    strikethrough: Boolean(cell.strikethrough),
-  };
-}
-
-function terminalStylesEqual(left: TerminalStyle, right: TerminalStyle): boolean {
-  return (
-    left.fg === right.fg &&
-    left.bg === right.bg &&
-    left.fgMode === right.fgMode &&
-    left.bgMode === right.bgMode &&
-    left.bold === right.bold &&
-    left.italic === right.italic &&
-    left.underline === right.underline &&
-    left.dim === right.dim &&
-    left.inverse === right.inverse &&
-    left.strikethrough === right.strikethrough
-  );
-}
-
-function styleToAnsi(style: TerminalStyle): string {
-  const codes = ["0"];
-
-  if (style.bold) {
-    codes.push("1");
-  }
-  if (style.dim) {
-    codes.push("2");
-  }
-  if (style.italic) {
-    codes.push("3");
-  }
-  if (style.underline) {
-    codes.push("4");
-  }
-  if (style.inverse) {
-    codes.push("7");
-  }
-  if (style.strikethrough) {
-    codes.push("9");
-  }
-
-  if (style.fg !== undefined && style.fgMode !== undefined) {
-    codes.push(...colorToSgr(style.fgMode, style.fg, false));
-  }
-
-  if (style.bg !== undefined && style.bgMode !== undefined) {
-    codes.push(...colorToSgr(style.bgMode, style.bg, true));
-  }
-
-  return `\u001b[${codes.join(";")}m`;
-}
-
-function colorToSgr(mode: number, value: number, background: boolean): string[] {
-  if (mode === 1) {
-    if (value >= 8) {
-      return [String((background ? 100 : 90) + (value - 8))];
-    }
-    return [String((background ? 40 : 30) + value)];
-  }
-
-  if (mode === 2) {
-    return [background ? "48" : "38", "5", String(value)];
-  }
-
-  if (mode === 3) {
-    return [
-      background ? "48" : "38",
-      "2",
-      String((value >> 16) & 0xff),
-      String((value >> 8) & 0xff),
-      String(value & 0xff),
-    ];
-  }
-
-  return [];
-}
diff --git a/packages/protocol/src/timeline-turn.ts b/packages/protocol/src/timeline-turn.ts
new file mode 100644
index 0000000000..f509787317
--- /dev/null
+++ b/packages/protocol/src/timeline-turn.ts
@@ -0,0 +1,24 @@
+/** Canonical run identity wins over trigger-shaped rows steered into that run. */
+export function continuesTimelineTurn(
+  previousTurnId: string | undefined,
+  nextTurnId: string | undefined,
+  nextIsTrigger: boolean,
+): boolean {
+  if (previousTurnId !== undefined && nextTurnId !== undefined) {
+    return previousTurnId === nextTurnId;
+  }
+  // Missing IDs cannot recover historical batching or steering. Each visible
+  // trigger deterministically starts a turn in both paging and presentation.
+  return !nextIsTrigger;
+}
+
+export function isTimelineTurnTrigger(item: {
+  type: string;
+  name?: string;
+  agentMessage?: unknown;
+}): boolean {
+  return (
+    item.type === "user_message" ||
+    (item.type === "tool_call" && (item.agentMessage !== undefined || item.name === "heartbeat"))
+  );
+}
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 b2e0c5187f..9f951df9dc 100644
--- a/packages/relay/package.json
+++ b/packages/relay/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/relay",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "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/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 4aeb01dc3f..0733102d65 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/server",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "description": "Paseo backend server",
+  "license": "Apache-2.0",
   "files": [
     "dist/server",
     "dist/src",
@@ -73,7 +74,7 @@
     "clean": "node ../../scripts/clean-package-dist.mjs",
     "build": "npm run build:lib && npm run build:scripts",
     "build:clean": "npm run clean && npm run build",
-    "build:lib": "tsc -p tsconfig.server.json --incremental false && node scripts/build-opencode-bridge-plugin.mjs && node -e \"const fs=require('node:fs'); fs.mkdirSync('dist/server/server/speech/providers/local/sherpa/assets',{recursive:true}); fs.copyFileSync('src/server/speech/providers/local/sherpa/assets/silero_vad.onnx','dist/server/server/speech/providers/local/sherpa/assets/silero_vad.onnx'); fs.cpSync('src/terminal/shell-integration','dist/server/terminal/shell-integration',{recursive:true}); fs.cpSync('src/terminal/shell-integration','dist/src/terminal/shell-integration',{recursive:true}); fs.copyFileSync('src/terminal/terminal-ts-loader.mjs','dist/server/terminal/terminal-ts-loader.mjs'); fs.rmSync('dist/server/skills',{recursive:true,force:true}); fs.cpSync('../../skills','dist/server/skills',{recursive:true}); fs.rmSync('dist/server/builtin-plugins',{recursive:true,force:true}); fs.cpSync('../../plugins','dist/server/builtin-plugins',{recursive:true,filter:(source)=>!source.split(require('node:path').sep).some((segment)=>segment==='node_modules'||segment==='test')&&!/\\.(test|spec)\\.[cm]?[jt]sx?$/.test(source)&&!source.endsWith('.tsbuildinfo')});\"",
+    "build:lib": "tsc -p tsconfig.server.json --incremental false && node scripts/build-opencode-bridge-plugin.mjs && node scripts/build-terminal-worker.mjs && node -e \"const fs=require('node:fs'); fs.mkdirSync('dist/server/server/speech/providers/local/sherpa/assets',{recursive:true}); fs.copyFileSync('src/server/speech/providers/local/sherpa/assets/silero_vad.onnx','dist/server/server/speech/providers/local/sherpa/assets/silero_vad.onnx'); fs.cpSync('src/terminal/shell-integration','dist/server/terminal/shell-integration',{recursive:true}); fs.cpSync('src/terminal/shell-integration','dist/src/terminal/shell-integration',{recursive:true}); fs.copyFileSync('src/terminal/terminal-ts-loader.mjs','dist/server/terminal/terminal-ts-loader.mjs'); fs.rmSync('dist/server/skills',{recursive:true,force:true}); fs.cpSync('../../skills','dist/server/skills',{recursive:true}); fs.rmSync('dist/server/builtin-plugins',{recursive:true,force:true}); fs.cpSync('../../plugins','dist/server/builtin-plugins',{recursive:true,filter:(source)=>!source.split(require('node:path').sep).some((segment)=>segment==='node_modules'||segment==='test')&&!/\\.(test|spec)\\.[cm]?[jt]sx?$/.test(source)&&!source.endsWith('.tsbuildinfo')});\"",
     "build:scripts": "tsc -p tsconfig.scripts.json --incremental false && node -e \"const fs=require('node:fs'); fs.mkdirSync('dist/scripts',{recursive:true}); fs.copyFileSync('scripts/mcp-stdio-socket-bridge-cli.mjs','dist/scripts/mcp-stdio-socket-bridge-cli.mjs');\"",
     "prepack": "npm run build:clean && npm --prefix ../.. run build:daemon-web-ui",
     "start": "node dist/scripts/supervisor-entrypoint.js",
@@ -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/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/connected-hosts/hosts.e2e.test.ts && vitest run --maxWorkers=1 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\"",
+    "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",
@@ -107,16 +108,18 @@
     "@agentclientprotocol/sdk": "^0.17.1",
     "@anthropic-ai/claude-agent-sdk": "0.3.246",
     "@anthropic-ai/sdk": "^0.104.2",
-    "@getpaseo/client": "0.13.2",
-    "@getpaseo/highlight": "0.13.2",
-    "@getpaseo/plugin": "0.13.2",
-    "@getpaseo/protocol": "0.13.2",
-    "@getpaseo/relay": "0.13.2",
+    "@getpaseo/client": "0.15.3",
+    "@getpaseo/highlight": "0.15.3",
+    "@getpaseo/plugin": "0.15.3",
+    "@getpaseo/protocol": "0.15.3",
+    "@getpaseo/relay": "0.15.3",
     "@isaacs/ttlcache": "^2.1.4",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@opencode-ai/sdk": "1.14.46",
     "@opencode/client": "2.0.10",
-    "@xterm/headless": "^6.0.0",
+    "@xterm/addon-serialize": "0.14.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",
@@ -124,6 +127,7 @@
     "esbuild": "^0.25.12",
     "express": "^4.18.2",
     "fast-deep-equal": "^3.1.3",
+    "https-proxy-agent": "^7.0.6",
     "lru-cache": "^11.5.1",
     "markdown-it": "^10.0.0",
     "mnemonic-id": "^3.2.7",
@@ -141,6 +145,7 @@
     "strip-ansi": "^7.1.2",
     "tree-kill": "^1.2.2",
     "typescript": "^5.9.3",
+    "undici": "^7.24.8",
     "uuid": "^9.0.1",
     "which": "^5.0.0",
     "ws": "^8.14.2",
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/build-terminal-worker.mjs b/packages/server/scripts/build-terminal-worker.mjs
new file mode 100644
index 0000000000..3a5b290fc3
--- /dev/null
+++ b/packages/server/scripts/build-terminal-worker.mjs
@@ -0,0 +1,55 @@
+// Bundles the terminal worker into one file with its shell integration beside it. The daemon
+// copies this directory (plus node-pty) into $PASEO_HOME/terminal-worker/ and launches the worker
+// from the copy, so a worker that outlives an upgrade never loads files from the installation
+// that replaced the one it came from. See docs/terminal-worker.md.
+//
+// Usage: node scripts/build-terminal-worker.mjs [--outdir <dir>]
+// Default output: dist/server/terminal-worker/
+
+import { cp, mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { build } from "esbuild";
+
+const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+
+export const TERMINAL_WORKER_BUNDLE_NAME = "terminal-worker.mjs";
+
+export async function buildTerminalWorkerBundle({ outDir }) {
+  await rm(outDir, { recursive: true, force: true });
+  await mkdir(outDir, { recursive: true });
+  await build({
+    entryPoints: [path.join(packageRoot, "src/terminal/terminal-worker-process.ts")],
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    target: "node20",
+    // Loaded from the copy's own node_modules/ at run time.
+    external: ["node-pty"],
+    // Bundled CommonJS dependencies call require() for Node built-ins.
+    banner: {
+      js: 'import { createRequire as __terminalWorkerCreateRequire } from "node:module"; const require = __terminalWorkerCreateRequire(import.meta.url);',
+    },
+    outfile: path.join(outDir, TERMINAL_WORKER_BUNDLE_NAME),
+    logLevel: "warning",
+  });
+  // terminal.ts resolves the zsh integration relative to its own module, which is the bundle.
+  await cp(
+    path.join(packageRoot, "src/terminal/shell-integration"),
+    path.join(outDir, "shell-integration"),
+    { recursive: true },
+  );
+}
+
+function readOutDir(argv) {
+  const index = argv.indexOf("--outdir");
+  if (index === -1) return path.join(packageRoot, "dist/server/terminal-worker");
+  const value = argv[index + 1];
+  if (!value) throw new Error("--outdir requires a directory");
+  return path.resolve(value);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  await buildTerminalWorkerBundle({ outDir: readOutDir(process.argv.slice(2)) });
+}
diff --git a/packages/server/scripts/reproduce-codex-history-string-limit.mts b/packages/server/scripts/reproduce-codex-history-string-limit.mts
new file mode 100644
index 0000000000..b0f49e4faf
--- /dev/null
+++ b/packages/server/scripts/reproduce-codex-history-string-limit.mts
@@ -0,0 +1,108 @@
+// Opt-in diagnostic for #3905. Run from the repository root:
+// node --import tsx packages/server/scripts/reproduce-codex-history-string-limit.mts 520 [legacy|paginated]
+// Requires Codex 0.148+ on PATH and approximately 2 GiB of available memory.
+// `paginated` migrates the synthetic rollout with `codex migrate-rollouts` first.
+import { execFileSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdtemp, mkdir, open, rm } from "node:fs/promises";
+import path from "node:path";
+import pino from "pino";
+import { CodexAppServerAgentSession } from "../src/server/agent/providers/codex-app-server-agent.js";
+
+const megabytes = Number(process.argv[2] ?? "520");
+if (!Number.isSafeInteger(megabytes) || megabytes < 1 || megabytes > 600) {
+  throw new Error("Expected an integer size between 1 and 600 MiB");
+}
+const historyMode = process.argv[3] ?? "legacy";
+if (historyMode !== "legacy" && historyMode !== "paginated") {
+  throw new Error("Expected history mode legacy or paginated");
+}
+const root = await mkdtemp(path.join(process.cwd(), ".codex-history-repro-"));
+const home = path.join(root, "codex-home");
+const now = new Date();
+const timestamp = now.toISOString();
+const threadId = randomUUID();
+const turnId = randomUUID();
+const sessions = path.join(home, "sessions", ...timestamp.slice(0, 10).split("-"));
+await mkdir(sessions, { recursive: true });
+const rollout = await open(
+  path.join(sessions, `rollout-${timestamp.slice(0, 19).replaceAll(":", "-")}-${threadId}.jsonl`),
+  "w",
+);
+async function write(type: string, payload: unknown) {
+  await rollout.write(`${JSON.stringify({ timestamp, type, payload })}\n`);
+}
+await write("session_meta", {
+  id: threadId,
+  timestamp,
+  cwd: root,
+  originator: "codex_cli_rs",
+  cli_version: "0.159.0",
+  source: "cli",
+  model_provider: "openai",
+  history_mode: "legacy",
+});
+await write("event_msg", { type: "task_started", turn_id: turnId, model_context_window: 200000 });
+await write("event_msg", {
+  type: "user_message",
+  message: "Synthetic oversized history",
+  images: [],
+  local_images: [],
+  text_elements: [],
+});
+for (let index = 0; index < megabytes; index++) {
+  await write("event_msg", {
+    type: "agent_message",
+    message: "x".repeat(1024 * 1024),
+    phase: "commentary",
+  });
+}
+await write("event_msg", { type: "task_complete", turn_id: turnId, last_agent_message: "done" });
+await rollout.close();
+if (historyMode === "paginated") {
+  execFileSync("codex", ["migrate-rollouts", "--apply", "--thread", threadId], {
+    env: { ...process.env, CODEX_HOME: home },
+    stdio: "ignore",
+  });
+}
+console.log(
+  `Opening synthetic ${megabytes} MiB ${historyMode} history through the real Codex app-server`,
+);
+const session = new CodexAppServerAgentSession(
+  { provider: "codex", cwd: root },
+  { sessionId: threadId },
+  pino({ level: "silent" }),
+  async () =>
+    spawn(
+      "codex",
+      ["app-server", "--disable", "plugins", "--disable", "apps", "--disable", "remote_plugin"],
+      {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...process.env, CODEX_HOME: home },
+      },
+    ),
+  { codexHome: home },
+  false,
+  false,
+  false,
+  undefined,
+  "history",
+);
+try {
+  await session.connect();
+  let count = 0;
+  for await (const event of session.streamHistory()) {
+    if (event.type !== "timeline") continue;
+    count++;
+    if (event.item.type === "notification") console.log(event.item.message);
+  }
+  console.log(`History loaded: ${count} timeline rows`);
+} catch (error) {
+  // A recoverable session error is acceptable for the crash-isolation assertion.
+  console.log(
+    `History rejected without crashing: ${error instanceof Error ? error.message : String(error)}`,
+  );
+} finally {
+  await session.close();
+  await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+}
diff --git a/packages/server/scripts/supervisor-entrypoint.ts b/packages/server/scripts/supervisor-entrypoint.ts
index ee3746accf..7d0e7f50aa 100644
--- a/packages/server/scripts/supervisor-entrypoint.ts
+++ b/packages/server/scripts/supervisor-entrypoint.ts
@@ -12,6 +12,7 @@ import { resolvePaseoHome } from "../src/server/paseo-home.js";
 import { daemonLogPath } from "../src/server/daemon-instance.js";
 import { PRIVATE_FILE_MODE } from "../src/server/private-files.js";
 import { loadPersistedConfig } from "../src/server/persisted-config.js";
+import { reapTerminalWorkers } from "../src/terminal/terminal-worker-reaper.js";
 import { runSupervisor } from "./supervisor.js";
 import { resolveSupervisorLogFile } from "./supervisor-log-config.js";
 
@@ -175,6 +176,10 @@ async function main(): Promise<void> {
     onWorkerExit: () =>
       updatePidLock(paseoHome, { listen: null, serverId: null }, { ownerPid: process.pid }),
     onSupervisorExit: releaseLock,
+    cleanupTerminals: async (log) => {
+      const result = await reapTerminalWorkers({ paseoHome, log });
+      log("Terminal worker cleanup result", { ...result });
+    },
   });
   requestSupervisorShutdown = supervisor.requestShutdown;
 }
diff --git a/packages/server/scripts/supervisor.terminal-cleanup.test.ts b/packages/server/scripts/supervisor.terminal-cleanup.test.ts
new file mode 100644
index 0000000000..224a0788d3
--- /dev/null
+++ b/packages/server/scripts/supervisor.terminal-cleanup.test.ts
@@ -0,0 +1,180 @@
+import { spawn } from "node:child_process";
+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 { describe, expect, test } from "vitest";
+
+// A real supervisor with scripted workers. Each worker generation logs what it sees to an
+// events file; `cleanupTerminals` logs "cleanup". The order of events is the contract: a kill
+// intent cleans up before the next worker starts, a keep intent or a crash never cleans up.
+
+async function runSupervisorWith(workerScript: string, timeoutMs = 8_000) {
+  const home = await mkdtemp(path.join(tmpdir(), "paseo-terminal-cleanup-"));
+  const workerPath = path.join(home, "worker.mjs");
+  const runnerPath = path.join(home, "runner.mjs");
+  const eventsPath = path.join(home, "events.jsonl");
+  const supervisor = new URL("./supervisor.ts", import.meta.url).href;
+  await writeFile(
+    workerPath,
+    `
+    import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+    const counter = ${JSON.stringify(path.join(home, "generation"))};
+    const generation = existsSync(counter) ? Number(readFileSync(counter, "utf8")) + 1 : 1;
+    writeFileSync(counter, String(generation));
+    const record = (event) =>
+      appendFileSync(${JSON.stringify(eventsPath)}, JSON.stringify(event) + "\\n");
+    record({ started: generation });
+    ${workerScript}
+  `,
+  );
+  await writeFile(
+    runnerPath,
+    `
+    import { appendFileSync } from "node:fs";
+    import { runSupervisor } from ${JSON.stringify(supervisor)};
+    runSupervisor({
+      name: "TerminalCleanupTest", startupMessage: "starting", restartOnCrash: true,
+      resolveWorkerEntry: () => ${JSON.stringify(workerPath)}, workerArgs: [], workerExecArgv: [],
+      cleanupTerminals: async () => {
+        appendFileSync(${JSON.stringify(eventsPath)}, JSON.stringify("cleanup") + "\\n");
+      },
+    });
+  `,
+  );
+  const env = Object.fromEntries(
+    Object.entries(process.env).filter(([key]) => !key.startsWith("PASEO_")),
+  );
+  const child = spawn(process.execPath, ["--import", "tsx", runnerPath], {
+    cwd: fileURLToPath(new URL("../../../", import.meta.url)),
+    env: { ...env, HOME: home, PASEO_HOME: home },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  let output = "";
+  child.stdout.on("data", (chunk) => (output += chunk));
+  child.stderr.on("data", (chunk) => (output += chunk));
+  try {
+    const code = await new Promise<number | null>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        reject(new Error(output));
+      }, timeoutMs);
+      child.once("error", reject);
+      child.once("close", (exitCode) => {
+        clearTimeout(timer);
+        resolve(exitCode);
+      });
+    });
+    const events = (await readFile(eventsPath, "utf8").catch(() => ""))
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as unknown);
+    return { code, output, events };
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+}
+
+// Generation 1 asks for `firstIntent`; generation 2 (if any) stops with `secondIntent`.
+function scriptedWorker(firstIntent: string, secondIntent = "") {
+  return `
+    process.on("message", (message) => {
+      if (message.type !== "paseo:graceful-shutdown") return;
+      record({ graceful: generation, keepTerminals: message.keepTerminals });
+      process.exit(0);
+    });
+    process.send({ type: "paseo:ready", listen: "endpoint-" + generation, serverId: "srv" });
+    if (generation === 1) { ${firstIntent} }
+    else { ${secondIntent} }
+  `;
+}
+
+const stopKeeping = `process.send({ type: "paseo:shutdown", reason: "test", keepTerminals: true });`;
+
+describe("supervisor terminal cleanup", () => {
+  test("a keep restart passes keepTerminals and never cleans up", async () => {
+    const result = await runSupervisorWith(
+      scriptedWorker(
+        `process.send({ type: "paseo:restart", reason: "test", keepTerminals: true });`,
+        stopKeeping,
+      ),
+    );
+    expect(result.code, result.output).toBe(0);
+    expect(result.events).toEqual([
+      { started: 1 },
+      { graceful: 1, keepTerminals: true },
+      { started: 2 },
+      { graceful: 2, keepTerminals: true },
+    ]);
+  });
+
+  test("a kill restart cleans up after the worker exits and before the respawn", async () => {
+    const result = await runSupervisorWith(
+      scriptedWorker(
+        `process.send({ type: "paseo:restart", reason: "test", keepTerminals: false });`,
+        stopKeeping,
+      ),
+    );
+    expect(result.code, result.output).toBe(0);
+    expect(result.events).toEqual([
+      { started: 1 },
+      { graceful: 1, keepTerminals: false },
+      "cleanup",
+      { started: 2 },
+      { graceful: 2, keepTerminals: true },
+    ]);
+  });
+
+  test("a kill restart whose worker hangs cleans up after the forced kill, before the respawn", async () => {
+    const result = await runSupervisorWith(
+      `
+      process.on("message", (message) => {
+        if (message.type !== "paseo:graceful-shutdown") return;
+        record({ graceful: generation, keepTerminals: message.keepTerminals });
+        if (generation === 2) process.exit(0);
+      });
+      process.send({ type: "paseo:ready", listen: "endpoint-" + generation, serverId: "srv" });
+      if (generation === 1) {
+        process.send({ type: "paseo:restart", reason: "test", keepTerminals: false });
+        setInterval(() => {}, 1000);
+      } else {
+        ${stopKeeping}
+      }
+    `,
+      20_000,
+    );
+    expect(result.code, result.output).toBe(0);
+    expect(result.events).toEqual([
+      { started: 1 },
+      { graceful: 1, keepTerminals: false },
+      "cleanup",
+      { started: 2 },
+      { graceful: 2, keepTerminals: true },
+    ]);
+  }, 30_000);
+
+  test("a crash restart keeps terminals", async () => {
+    const result = await runSupervisorWith(scriptedWorker(`process.exit(1);`, stopKeeping));
+    expect(result.code, result.output).toBe(0);
+    expect(result.events).toEqual([
+      { started: 1 },
+      { started: 2 },
+      { graceful: 2, keepTerminals: true },
+    ]);
+  });
+
+  test("a kill stop cleans up when the supervisor exits", async () => {
+    const result = await runSupervisorWith(
+      scriptedWorker(
+        `process.send({ type: "paseo:shutdown", reason: "test", keepTerminals: false });`,
+      ),
+    );
+    expect(result.code, result.output).toBe(0);
+    expect(result.events).toEqual([
+      { started: 1 },
+      { graceful: 1, keepTerminals: false },
+      "cleanup",
+    ]);
+  });
+});
diff --git a/packages/server/scripts/supervisor.ts b/packages/server/scripts/supervisor.ts
index ec56822619..fac28946d5 100644
--- a/packages/server/scripts/supervisor.ts
+++ b/packages/server/scripts/supervisor.ts
@@ -21,6 +21,7 @@ type WorkerLifecycleMessage =
   | {
       type: "paseo:shutdown";
       reason?: string;
+      keepTerminals: boolean;
     }
   | {
       type: "paseo:ready";
@@ -30,6 +31,7 @@ type WorkerLifecycleMessage =
   | {
       type: "paseo:restart";
       reason?: string;
+      keepTerminals: boolean;
     };
 
 interface SupervisorHeartbeatMessage {
@@ -39,8 +41,11 @@ interface SupervisorHeartbeatMessage {
 interface SupervisorGracefulShutdownMessage {
   type: "paseo:graceful-shutdown";
   reason: string;
+  keepTerminals: boolean;
 }
 
+export type SupervisorLifecycleLog = (message: string, fields?: Record<string, unknown>) => void;
+
 interface SupervisorOptions {
   name: string;
   startupMessage: string;
@@ -57,11 +62,15 @@ interface SupervisorOptions {
   onWorkerExit?: () => Promise<void> | void;
   restartOnCrash?: boolean;
   onSupervisorExit?: () => Promise<void> | void;
+  // Closes every terminal the worker left. Runs after a kill-intent restart or stop once the
+  // worker has exited (also after a forced kill), before a respawn, and on any supervisor
+  // exit except a keep-terminals stop. A crash restart keeps terminals and skips it.
+  cleanupTerminals?: (log: SupervisorLifecycleLog) => Promise<void>;
   logFile?: SupervisorLogFileOptions;
 }
 
 export interface SupervisorController {
-  requestShutdown(reason: string): void;
+  requestShutdown(reason: string, options?: { keepTerminals?: boolean }): void;
 }
 
 function describeExit(code: number | null, signal: NodeJS.Signals | null): string {
@@ -74,10 +83,11 @@ function parseLifecycleMessage(msg: unknown): WorkerLifecycleMessage | null {
   }
   const type = (msg as { type?: unknown }).type;
   if (type === "paseo:shutdown") {
-    const reason = (msg as { reason?: unknown }).reason;
+    const { reason, keepTerminals } = msg as { reason?: unknown; keepTerminals?: unknown };
     return {
       type: "paseo:shutdown",
       ...(typeof reason === "string" && reason.trim().length > 0 ? { reason } : {}),
+      keepTerminals: keepTerminals === true,
     };
   }
   if (type === "paseo:ready") {
@@ -91,10 +101,11 @@ function parseLifecycleMessage(msg: unknown): WorkerLifecycleMessage | null {
     return { type: "paseo:ready", listen, serverId };
   }
   if (type === "paseo:restart") {
-    const reason = (msg as { reason?: unknown }).reason;
+    const { reason, keepTerminals } = msg as { reason?: unknown; keepTerminals?: unknown };
     return {
       type: "paseo:restart",
       ...(typeof reason === "string" && reason.trim().length > 0 ? { reason } : {}),
+      keepTerminals: keepTerminals === true,
     };
   }
   return null;
@@ -185,6 +196,9 @@ export function runSupervisor(options: SupervisorOptions): SupervisorController
   let child: ChildProcess | null = null;
   let restarting = false;
   let shuttingDown = false;
+  // The resolved terminal decision of the pending restart or stop. It survives the force-kill
+  // path, so a hung kill restart still closes terminals before the respawn.
+  let pendingKeepTerminals = false;
   let exiting = false;
   let lifecycleFailed = false;
   let publication = Promise.resolve();
@@ -217,12 +231,31 @@ export function runSupervisor(options: SupervisorOptions): SupervisorController
 
   const closeLogStream = (): Promise<void> => durableLog.close();
 
-  const exitSupervisor = (code: number): void => {
+  const runTerminalCleanup = async (when: string): Promise<void> => {
+    if (!options.cleanupTerminals) {
+      return;
+    }
+    writeLifecycleLog("Closing terminals", { when });
+    try {
+      await options.cleanupTerminals(writeLifecycleLog);
+      writeLifecycleLog("Terminal cleanup finished", { when });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      log(`Terminal cleanup not confirmed (${when}): ${message}`);
+    }
+  };
+
+  const exitSupervisor = (code: number, exitOptions: { keepTerminals?: boolean } = {}): void => {
     if (exiting) {
       return;
     }
     exiting = true;
-    Promise.resolve(options.onSupervisorExit?.())
+    const cleanup =
+      exitOptions.keepTerminals === true
+        ? Promise.resolve()
+        : runTerminalCleanup("supervisor_exit");
+    cleanup
+      .then(() => options.onSupervisorExit?.())
       .catch((error) => {
         const message = error instanceof Error ? error.message : String(error);
         log(`Supervisor exit cleanup failed: ${message}`);
@@ -357,14 +390,20 @@ export function runSupervisor(options: SupervisorOptions): SupervisorController
 
       if (lifecycleMessage.type === "paseo:shutdown") {
         const reason = lifecycleMessage.reason ?? "worker_requested_shutdown";
-        writeLifecycleLog("Worker requested shutdown", { reason });
-        requestShutdown(reason);
+        writeLifecycleLog("Worker requested shutdown", {
+          reason,
+          keepTerminals: lifecycleMessage.keepTerminals,
+        });
+        requestShutdown(reason, { keepTerminals: lifecycleMessage.keepTerminals });
         return;
       }
 
       const reason = lifecycleMessage.reason ?? "worker_requested_restart";
-      writeLifecycleLog("Worker requested restart", { reason });
-      requestRestart(reason);
+      writeLifecycleLog("Worker requested restart", {
+        reason,
+        keepTerminals: lifecycleMessage.keepTerminals,
+      });
+      requestRestart(reason, lifecycleMessage.keepTerminals);
     });
 
     child.on("error", (error) => {
@@ -395,7 +434,7 @@ export function runSupervisor(options: SupervisorOptions): SupervisorController
 
         if (shuttingDown) {
           log(`Worker exited (${exitDescriptor}). Supervisor shutting down.`);
-          exitSupervisor(0);
+          exitSupervisor(0, { keepTerminals: pendingKeepTerminals });
           return;
         }
 
@@ -404,13 +443,25 @@ export function runSupervisor(options: SupervisorOptions): SupervisorController
           ((code !== 0 && code !== null) || (signal !== null && signal !== "SIGTERM"));
 
         if (restarting || crashed) {
+          const closeTerminals = restarting && !pendingKeepTerminals;
           restarting = false;
+          pendingKeepTerminals = false;
           log(
-            crashed
+            crashed && !closeTerminals
               ? `Worker crashed (${exitDescriptor}). Restarting worker...`
               : `Worker exited (${exitDescriptor}). Restarting worker...`,
           );
-          spawnWorker();
+          if (!closeTerminals) {
+            spawnWorker();
+            return;
+          }
+          // The replacement daemon must never adopt terminals the user asked to close.
+          void runTerminalCleanup("before_respawn").then(() => {
+            if (!shuttingDown) {
+              spawnWorker();
+            }
+            return;
+          });
           return;
         }
 
@@ -429,9 +480,11 @@ export function runSupervisor(options: SupervisorOptions): SupervisorController
     const message: SupervisorGracefulShutdownMessage = {
       type: "paseo:graceful-shutdown",
       reason,
+      keepTerminals: pendingKeepTerminals,
     };
     writeLifecycleLog("Supervisor requesting graceful worker shutdown", {
       reason,
+      keepTerminals: pendingKeepTerminals,
       supervisorPid: process.pid,
       workerPid: currentChild.pid ?? null,
     });
@@ -455,28 +508,33 @@ export function runSupervisor(options: SupervisorOptions): SupervisorController
     });
   };
 
-  const requestRestart = (reason: string) => {
+  const requestRestart = (reason: string, keepTerminals: boolean) => {
     if (!child || restarting || shuttingDown) {
       return;
     }
     restarting = true;
-    writeLifecycleLog("Restart requested", { reason });
+    pendingKeepTerminals = keepTerminals;
+    writeLifecycleLog("Restart requested", { reason, keepTerminals });
     log(`${reason}. Stopping worker for restart...`);
     requestWorkerShutdown(reason);
     scheduleForceKill(reason);
   };
 
-  const requestShutdown = (reason: string) => {
+  const requestShutdown = (reason: string, shutdownOptions: { keepTerminals?: boolean } = {}) => {
     if (shuttingDown) {
       return;
     }
     shuttingDown = true;
     restarting = false;
-    writeLifecycleLog("Supervisor shutdown requested", { reason });
+    pendingKeepTerminals = shutdownOptions.keepTerminals === true;
+    writeLifecycleLog("Supervisor shutdown requested", {
+      reason,
+      keepTerminals: pendingKeepTerminals,
+    });
     log(`${reason}. Stopping worker...`);
     if (!child) {
       void publication.then(() => {
-        exitSupervisor(lifecycleFailed ? 1 : 0);
+        exitSupervisor(lifecycleFailed ? 1 : 0, { keepTerminals: pendingKeepTerminals });
         return;
       });
       return;
diff --git a/packages/server/src/executable-resolution/executable-resolution.ts b/packages/server/src/executable-resolution/executable-resolution.ts
index 97bb8af3a3..064dcec64e 100644
--- a/packages/server/src/executable-resolution/executable-resolution.ts
+++ b/packages/server/src/executable-resolution/executable-resolution.ts
@@ -1,17 +1,10 @@
-import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import { delimiter, resolve } from "node:path";
 import type { ProcessEnvRecord } from "../server/paseo-env.js";
 import { execCommand } from "../utils/spawn.js";
+import which from "which";
 import { windowsExecutableResolution } from "./windows.js";
 
-type Which = (
-  command: string,
-  options: { all: true; path?: string; pathExt?: string },
-) => Promise<string[]>;
-
-const require = createRequire(import.meta.url);
-const which = require("which") as Which;
 const PROBE_TIMEOUT_MS = 2000;
 
 function hasPathSeparator(value: string): boolean {
diff --git a/packages/server/src/executable-resolution/which.d.ts b/packages/server/src/executable-resolution/which.d.ts
new file mode 100644
index 0000000000..e7fd869f25
--- /dev/null
+++ b/packages/server/src/executable-resolution/which.d.ts
@@ -0,0 +1,10 @@
+// `which` ships no types. Imported statically (not through createRequire) so the terminal
+// worker bundle includes it: the worker runs from a copy that has only node-pty beside it.
+// Listed in the tsconfig includes, since nothing imports a declaration file.
+declare module "which" {
+  function which(
+    command: string,
+    options: { all: true; path?: string; pathExt?: string },
+  ): Promise<string[]>;
+  export default which;
+}
diff --git a/packages/server/src/server/agent/activity-curator.test.ts b/packages/server/src/server/agent/activity-curator.test.ts
index c98bbae54d..6a1d85bcf0 100644
--- a/packages/server/src/server/agent/activity-curator.test.ts
+++ b/packages/server/src/server/agent/activity-curator.test.ts
@@ -247,7 +247,7 @@ second line'`,
     ]);
   });
 
-  it("keeps nested sub-agent logs beside the sub-agent that produced them", () => {
+  it("lists each sub-agent as its launch marker", () => {
     const timeline: AgentTimelineItem[] = [
       { type: "assistant_message", text: "Before first child." },
       toolCallItem({
@@ -257,7 +257,7 @@ second line'`,
           type: "sub_agent",
           subAgentType: "Child one",
           description: "First investigation",
-          log: "[Assistant] First child result.",
+          log: "",
         },
       }),
       { type: "assistant_message", text: "Between children." },
@@ -268,7 +268,7 @@ second line'`,
           type: "sub_agent",
           subAgentType: "Child two",
           description: "Second investigation",
-          log: "[Assistant] Second child result.",
+          log: "",
         },
       }),
       { type: "assistant_message", text: "After second child." },
@@ -279,10 +279,8 @@ second line'`,
     expect(result.split("\n")).toEqual([
       "[Assistant] Before first child.",
       "[Child one] First investigation",
-      "[Assistant] First child result.",
       "[Assistant] Between children.",
       "[Child two] Second investigation",
-      "[Assistant] Second child result.",
       "[Assistant] After second child.",
     ]);
   });
@@ -456,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 488867c657..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;
@@ -164,9 +170,6 @@ function curateProjectedActivityEntries(
           break;
         }
         entries.push(formatToolCallEntry(item, options));
-        if (item.detail.type === "sub_agent" && item.detail.log.trim()) {
-          entries.push(activityEntry(item.detail.log.trim()));
-        }
         break;
       }
       case "todo":
@@ -272,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.",
     );
@@ -352,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 d75fa8739a..3f56f136c1 100644
--- a/packages/server/src/server/agent/agent-loading.test.ts
+++ b/packages/server/src/server/agent/agent-loading.test.ts
@@ -1,4 +1,4 @@
-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";
@@ -17,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-"));
@@ -142,60 +143,247 @@ 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 });
-  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");
-    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,
+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,
     });
 
-    expect(loaded.id).toBe(agentId);
-    // The transcript is replayed from the provider's persisted history, so the reply the
-    // agent gave before the worktree went away is still readable.
-    const replies = 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,
+    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 transcript is replayed from the provider's persisted history, so the reply the
+      // agent gave before the worktree went away is still readable.
+      const replies = 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 manager.closeAgent(agentId).catch(() => undefined);
-    await manager.flush().catch(() => undefined);
-    await storage.flush().catch(() => undefined);
-    await rm(root, { recursive: true, force: true });
+    await ctx.cleanup();
+    await rm(cwd, { recursive: true, force: true });
   }
-});
+}, 30000);
+
+test("timeline reads keep runnable unarchived agents interactive for the next prompt", 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);
+    expect(purposes).toEqual([{ purpose: "interactive" }]);
+    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"),
+    ]);
+    expect(purposes).toEqual([
+      { purpose: "interactive" },
+      { purpose: "history" },
+      undefined, // Reload uses the provider's interactive default.
+    ]);
+  } 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");
+      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 761f1008bd..c683a4ec77 100644
--- a/packages/server/src/server/agent/agent-loading.ts
+++ b/packages/server/src/server/agent/agent-loading.ts
@@ -41,6 +41,7 @@ export interface EnsureAgentLoadedDeps {
   agentStorage: AgentStorage;
   validProviders?: Iterable<AgentProvider>;
   broadcastTimeline?: boolean;
+  purpose?: "history" | "interactive";
   logger: Logger;
 }
 
@@ -118,7 +119,7 @@ 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 {
@@ -135,6 +136,8 @@ export async function ensureAgentLoaded(
         labels: record.labels,
         workspaceId: record.workspaceId,
         owner: record.owner,
+        background: record.background,
+        env: record.launchEnv,
       });
       deps.logger.info({ agentId, provider: record.provider }, "Agent created from stored config");
     }
diff --git a/packages/server/src/server/agent/agent-manager-stream-coalescing.test.ts b/packages/server/src/server/agent/agent-manager-stream-coalescing.test.ts
index 9dc194fa11..c423264869 100644
--- a/packages/server/src/server/agent/agent-manager-stream-coalescing.test.ts
+++ b/packages/server/src/server/agent/agent-manager-stream-coalescing.test.ts
@@ -6,6 +6,7 @@ import { afterEach, describe, expect, test, vi } from "vitest";
 import { createTestLogger } from "../../test-utils/test-logger.js";
 import { AgentManager, type AgentManagerEvent } from "./agent-manager.js";
 import { AGENT_STREAM_COALESCE_DEFAULT_WINDOW_MS } from "./agent-stream-coalescer.js";
+import { limitAgentTimelineItemContent } from "./agent-timeline-content.js";
 import type { AgentTimelineRow } from "./agent-timeline-store-types.js";
 import { projectTimelineRows } from "./timeline-projection.js";
 import type {
@@ -31,7 +32,6 @@ import type {
 
 const COALESCE_WINDOW_MS = AGENT_STREAM_COALESCE_DEFAULT_WINDOW_MS;
 const BEFORE_COALESCE_WINDOW_MS = Math.max(COALESCE_WINDOW_MS - 1, 0);
-const TOOL_CALL_CONTENT_MAX_LENGTH = 64 * 1024;
 
 const TEST_CAPABILITIES: AgentCapabilityFlags = {
   supportsStreaming: false,
@@ -400,10 +400,7 @@ describe("target coalesced behavior", () => {
     try {
       const { agentId, session } = await createManagedSession(harness);
       const output = `${"a".repeat(512 * 1024)}${"z".repeat(512 * 1024)}`;
-      const expectedItem = toolCall({
-        status: "completed",
-        output: "a".repeat(TOOL_CALL_CONTENT_MAX_LENGTH),
-      });
+      const expectedItem = limitAgentTimelineItemContent(toolCall({ status: "completed", output }));
 
       session.pushEvent(timelineEvent(toolCall({ status: "completed", output })));
       await waitForSessionEventQueue();
@@ -425,10 +422,7 @@ describe("target coalesced behavior", () => {
     try {
       const { agentId } = await createManagedSession(harness);
       const output = `${"a".repeat(512 * 1024)}${"z".repeat(512 * 1024)}`;
-      const expectedItem = toolCall({
-        status: "completed",
-        output: "a".repeat(TOOL_CALL_CONTENT_MAX_LENGTH),
-      });
+      const expectedItem = limitAgentTimelineItemContent(toolCall({ status: "completed", output }));
 
       await harness.manager.appendTimelineItem(agentId, toolCall({ status: "completed", output }));
 
@@ -449,10 +443,7 @@ describe("target coalesced behavior", () => {
     try {
       const { agentId, session } = await createManagedSession(harness);
       const output = `${"a".repeat(512 * 1024)}${"z".repeat(512 * 1024)}`;
-      const expectedItem = toolCall({
-        status: "completed",
-        output: "a".repeat(TOOL_CALL_CONTENT_MAX_LENGTH),
-      });
+      const expectedItem = limitAgentTimelineItemContent(toolCall({ status: "completed", output }));
       session.setHistory([timelineEvent(toolCall({ status: "completed", output }))]);
 
       await harness.manager.hydrateTimelineFromProvider(agentId, { force: true });
@@ -470,10 +461,7 @@ describe("target coalesced behavior", () => {
     try {
       const { agentId } = await createManagedSession(harness);
       const output = `${"a".repeat(512 * 1024)}${"z".repeat(512 * 1024)}`;
-      const expectedItem = toolCall({
-        status: "completed",
-        output: "a".repeat(TOOL_CALL_CONTENT_MAX_LENGTH),
-      });
+      const expectedItem = limitAgentTimelineItemContent(toolCall({ status: "completed", output }));
 
       await harness.manager.emitLiveTimelineItem(
         agentId,
@@ -495,10 +483,9 @@ describe("target coalesced behavior", () => {
     try {
       const { agentId, session } = await createManagedSession(harness);
       const content = `${"a".repeat(512 * 1024)}${"z".repeat(512 * 1024)}`;
-      const expectedItem = toolCall({
-        status: "failed",
-        error: { content: "a".repeat(TOOL_CALL_CONTENT_MAX_LENGTH) },
-      });
+      const expectedItem = limitAgentTimelineItemContent(
+        toolCall({ status: "failed", error: { content } }),
+      );
 
       session.pushEvent(timelineEvent(toolCall({ status: "failed", error: { content } })));
       await waitForSessionEventQueue();
diff --git a/packages/server/src/server/agent/agent-manager.test.ts b/packages/server/src/server/agent/agent-manager.test.ts
index ae8989c003..5b77522473 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";
@@ -21,6 +21,7 @@ import {
 } from "./agent-manager.js";
 import { AgentStorage } from "./agent-storage.js";
 import { InMemoryAgentTimelineStore } from "./agent-timeline-store.js";
+import { limitAgentTimelineItemContent } from "./agent-timeline-content.js";
 import { toAgentPayload } from "./agent-projections.js";
 import { projectTimelineRows } from "./timeline-projection.js";
 import { getOpenAgentTabLabel, PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
@@ -57,6 +58,9 @@ import type {
 import type { PaseoToolCatalog } from "./tools/types.js";
 import type { ProviderDefinition } from "./provider-registry.js";
 
+import { OpenCodeV2AgentClient } from "./providers/opencode/v2/agent.js";
+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");
 
@@ -669,6 +673,33 @@ 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("uses an injected timeline store without making it a production requirement", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-timeline-store-"));
   const store = new RecordingTimelineStore();
@@ -880,6 +911,66 @@ test("retries provider history hydration after a stream failure", async () => {
   }
 });
 
+test("notification batches share the run they start or join", async () => {
+  const session = new SteeringTestSession({ provider: "codex", cwd: process.cwd() });
+  const workdir = mkdtempSync(join(tmpdir(), "agent-notification-turns-"));
+  const manager = new AgentManager({
+    clients: {
+      codex: new (class extends TestAgentClient {
+        override async createSession(): Promise<AgentSession> {
+          return session;
+        }
+      })(),
+    },
+    logger,
+  });
+  const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+    workspaceId: undefined,
+  });
+  const batch = (prefix: string) =>
+    ["one", "two"]
+      .map((id) =>
+        formatAgentMessage({
+          id: `${prefix}-${id}`,
+          source: { kind: "agent-notification", agentId: "worker", event: "finished" },
+          text: "Worker finished",
+        }),
+      )
+      .join("\n\n");
+  const consume = async (prompt: string, clientMessageId: string) => {
+    for await (const _event of manager.streamAgent(agent.id, prompt, { clientMessageId })) {
+    }
+  };
+  try {
+    const first = consume("human", "human");
+    await manager.waitForAgentRunStart(agent.id);
+    await expect(
+      manager.steerAgentRun(agent.id, batch("joined"), { clientMessageId: "joined-one" }),
+    ).resolves.toEqual({ status: "accepted" });
+    session.pushEvent({ type: "turn_completed", provider: "codex", turnId: "active-turn-1" });
+    await first;
+    const second = consume(batch("idle"), "idle-one");
+    await manager.waitForAgentRunStart(agent.id);
+    session.pushEvent({ type: "turn_completed", provider: "codex", turnId: "active-turn-2" });
+    await second;
+    expect(
+      manager.fetchTimeline(agent.id, { limit: 0 }).rows.map((row) => ({
+        turnId: row.turnId,
+        id: row.item.type === "tool_call" ? row.item.callId : row.item.type,
+      })),
+    ).toEqual([
+      { turnId: "active-turn-1", id: "user_message" },
+      { turnId: "active-turn-1", id: "paseo-agent-message:joined-one" },
+      { turnId: "active-turn-1", id: "paseo-agent-message:joined-two" },
+      { turnId: "active-turn-2", id: "paseo-agent-message:idle-one" },
+      { turnId: "active-turn-2", id: "paseo-agent-message:idle-two" },
+    ]);
+  } finally {
+    await manager.closeAgent(agent.id);
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
 test("unavailable steer interrupts once and starts one replacement turn", async () => {
   const session = new SteeringTestSession({ provider: "codex", cwd: process.cwd() });
   session.steerResult = "unavailable";
@@ -896,6 +987,131 @@ test("unavailable steer interrupts once and starts one replacement turn", async
   }
 });
 
+test("steers a send that arrives while the previous turn is still starting", async () => {
+  const startHeld = deferred<void>();
+  class SlowStartSteeringSession extends SteeringTestSession {
+    override async startTurn(prompt: AgentPromptInput): Promise<{ turnId: string }> {
+      await startHeld.promise;
+      return await super.startTurn(prompt);
+    }
+  }
+  const session = new SlowStartSteeringSession({
+    provider: "codex",
+    cwd: process.cwd(),
+  });
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-steer-starting-"));
+  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 steerOptions = (clientMessageId: string) => ({
+      replaceRunning: true,
+      activeTurnBehavior: "steer" as const,
+      runOptions: { clientMessageId },
+    });
+    await startAgentRun(manager, agent.id, "FIRST", logger, steerOptions("first-client"));
+    const second = startAgentRun(
+      manager,
+      agent.id,
+      "SECOND",
+      logger,
+      steerOptions("second-client"),
+    );
+
+    startHeld.resolve();
+    await expect(second).resolves.toEqual({ disposition: "steered" });
+
+    expect(session.startPrompts).toEqual(["FIRST"]);
+    expect(session.interruptCount).toBe(0);
+    expect(
+      manager
+        .fetchTimeline(agent.id, { limit: 0 })
+        .rows.filter((row) => row.item.type === "user_message")
+        .map((row) => ({
+          text: row.item.type === "user_message" ? row.item.text : null,
+          turnId: row.turnId,
+        })),
+    ).toEqual([
+      { text: "FIRST", turnId: "active-turn-1" },
+      { text: "SECOND", turnId: "active-turn-1" },
+    ]);
+  } finally {
+    startHeld.resolve();
+    if (agentId) await manager.closeAgent(agentId).catch(() => undefined);
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
+test("starts its own turn when the previous turn fails to start under a steer send", async () => {
+  const startHeld = deferred<void>();
+  class FailingFirstStartSession extends SteeringTestSession {
+    override async startTurn(prompt: AgentPromptInput): Promise<{ turnId: string }> {
+      if (prompt === "FIRST") {
+        this.startPrompts.push(prompt);
+        await startHeld.promise;
+        throw new Error("first start failed");
+      }
+      return await super.startTurn(prompt);
+    }
+  }
+  const session = new FailingFirstStartSession({
+    provider: "codex",
+    cwd: process.cwd(),
+  });
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-steer-failed-start-"));
+  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 steerOptions = (clientMessageId: string) => ({
+      replaceRunning: true,
+      activeTurnBehavior: "steer" as const,
+      runOptions: { clientMessageId },
+    });
+    await startAgentRun(manager, agent.id, "FIRST", logger, steerOptions("first-client"));
+    const second = startAgentRun(
+      manager,
+      agent.id,
+      "SECOND",
+      logger,
+      steerOptions("second-client"),
+    );
+
+    startHeld.resolve();
+    await expect(second).resolves.toEqual({ disposition: "turn_started" });
+    await vi.waitFor(() => expect(session.startPrompts).toEqual(["FIRST", "SECOND"]));
+    expect(session.interruptCount).toBe(0);
+  } finally {
+    startHeld.resolve();
+    if (agentId) await manager.closeAgent(agentId).catch(() => undefined);
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
 test("orders an accepted steer before output emitted while acknowledgement is pending", async () => {
   const entered = deferred<void>();
   const release = deferred<void>();
@@ -1034,6 +1250,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 = 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>();
@@ -2517,6 +2801,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);
@@ -2869,6 +3200,92 @@ test("createAgent passes daemon launch env through the provider launch context",
   });
 });
 
+test.each([
+  { provider: "codex", hasHandle: true },
+  { provider: "opencode", hasHandle: true },
+  { provider: "codex", hasHandle: false },
+  { provider: "opencode", hasHandle: false },
+])(
+  "$provider preserves explicit launch env across reloads and storage-backed resumes (handle: $hasHandle)",
+  async ({ provider, hasHandle }) => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-launch-env-"));
+    const storagePath = join(workdir, "agents");
+    class LaunchEnvClient extends TestAgentClient {
+      lastLaunchContext: AgentLaunchContext | undefined;
+
+      override async createSession(
+        config: AgentSessionConfig,
+        context?: AgentLaunchContext,
+      ): Promise<AgentSession> {
+        this.lastLaunchContext = context;
+        const session = await super.createSession(config);
+        session.describePersistence = () => ({ provider, sessionId: session.id });
+        return session;
+      }
+
+      override async resumeSession(
+        handle: AgentPersistenceHandle,
+        config?: Partial<AgentSessionConfig>,
+        context?: AgentLaunchContext,
+      ): Promise<AgentSession> {
+        this.lastLaunchContext = context;
+        const session = await super.resumeSession(handle, config, context);
+        session.describePersistence = () => ({ provider, sessionId: handle.sessionId });
+        return session;
+      }
+    }
+
+    const client = new LaunchEnvClient(provider);
+    let storage = new AgentStorage(storagePath, logger);
+    let manager = new AgentManager({ clients: { [provider]: client }, registry: storage, logger });
+    const env = { XDG_DATA_HOME: join(workdir, "agent-data"), CUSTOM_EMPTY: "" };
+    const expectedEnv = { ...env };
+    const agent = await manager.createAgent({ provider, cwd: workdir }, undefined, {
+      workspaceId: undefined,
+      env,
+    });
+    onTestFinished(async () => {
+      await manager.closeAgent(agent.id);
+      await manager.flush();
+      rmSync(workdir, { recursive: true, force: true });
+    });
+    env.XDG_DATA_HOME = "caller-mutated";
+
+    await manager.closeAgent(agent.id);
+    await manager.flush();
+
+    if (!hasHandle) {
+      const record = await storage.get(agent.id);
+      if (!record) throw new Error("Created agent was not persisted");
+      await storage.upsert({ ...record, persistence: null });
+    }
+
+    // Fresh storage and manager instances must read the environment from disk.
+    for (let restart = 0; restart < 2; restart += 1) {
+      storage = new AgentStorage(storagePath, logger);
+      manager = new AgentManager({ clients: { [provider]: client }, registry: storage, logger });
+      const resumed = await ensureAgentLoaded(agent.id, {
+        agentManager: manager,
+        agentStorage: storage,
+        logger,
+      });
+      expect(client.lastLaunchContext).toEqual({
+        agentId: agent.id,
+        env: { ...expectedEnv, PASEO_AGENT_ID: agent.id, PASEO_AGENT_CWD: workdir },
+      });
+      await manager.reloadAgentSession(agent.id);
+      expect(client.lastLaunchContext).toEqual({
+        agentId: agent.id,
+        env: { ...expectedEnv, PASEO_AGENT_ID: agent.id, PASEO_AGENT_CWD: workdir },
+      });
+      expect(toAgentPayload(resumed)).not.toHaveProperty("launchEnv");
+      expect(toAgentPayload(resumed).persistence?.metadata).not.toHaveProperty("launchEnv");
+      await manager.closeAgent(agent.id);
+      await manager.flush();
+    }
+  },
+);
+
 test("createAgent passes persistSession to provider create options", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-test-"));
   const storagePath = join(workdir, "agents");
@@ -3722,7 +4139,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 () => {
@@ -4321,7 +4738,7 @@ test("importProviderSession imports the selected session without listing and pub
   expect(manager.getTimeline(imported.id)).toEqual([
     { type: "user_message", text: "Trace provider imports" },
     { type: "assistant_message", text: "Done" },
-    {
+    limitAgentTimelineItemContent({
       type: "tool_call",
       callId: "large-shell-result",
       name: "shell",
@@ -4330,10 +4747,10 @@ test("importProviderSession imports the selected session without listing and pub
       detail: {
         type: "shell",
         command: "print output",
-        output: "x".repeat(64 * 1024),
+        output: "x".repeat(1024 * 1024),
         exitCode: 0,
       },
-    },
+    }),
   ]);
   expect(manager.listProviderSubagents(imported.id)).toEqual([
     expect.objectContaining({ id: "thread-child", title: "Imported child", status: "completed" }),
@@ -5437,6 +5854,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);
@@ -6977,6 +7440,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)!;
@@ -7019,7 +7483,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(manager.getTimeline(snapshot.id)).toEqual(timelineBeforeStaleTerminals);
@@ -7747,7 +8211,7 @@ test("workspace ownership does not turn an ordinary agent into a disposable help
   expect(manager.listAgents().map((agent) => agent.id)).toEqual([agentId]);
   expect(await storage.get(agentId)).not.toBeNull();
   // Workspace ownership preserves ordinary agent lifecycle hooks.
-  expect(beforeHookCalls).toContain("agent.create");
+  expect(beforeHookCalls).toContain("agent.create.before");
 });
 
 test("global subscribers receive internal agent events only when they opt in", async () => {
@@ -7788,6 +8252,60 @@ test("global subscribers receive internal agent events only when they opt in", a
   unsubscribeOptedIn();
 });
 
+test("agent removal notifications respect scoped subscriptions and internal visibility", () => {
+  const manager = new AgentManager({ clients: {}, logger });
+  const removedId = "00000000-0000-4000-8000-000000000901";
+  const internalId = "00000000-0000-4000-8000-000000000902";
+  const otherId = "00000000-0000-4000-8000-000000000903";
+  const publicEvents: AgentManagerEvent[] = [];
+  const allEvents: AgentManagerEvent[] = [];
+  const scopedEvents: AgentManagerEvent[] = [];
+  const internalEvents: AgentManagerEvent[] = [];
+  const unrelatedEvents: AgentManagerEvent[] = [];
+  const releases = [
+    manager.subscribe((event) => publicEvents.push(event), { replayState: false }),
+    manager.subscribe((event) => allEvents.push(event), {
+      replayState: false,
+      includeInternal: true,
+    }),
+    manager.subscribe((event) => scopedEvents.push(event), {
+      replayState: false,
+      agentId: removedId,
+    }),
+    manager.subscribe((event) => internalEvents.push(event), {
+      replayState: false,
+      agentId: internalId,
+    }),
+    manager.subscribe((event) => unrelatedEvents.push(event), {
+      replayState: false,
+      agentId: otherId,
+    }),
+  ];
+  try {
+    manager.notifyAgentRemoved({ id: removedId, workspaceId: "workspace" });
+    manager.notifyAgentRemoved({ id: internalId, workspaceId: "workspace", internal: true });
+    const publicRemoval = {
+      type: "agent_removed",
+      agentId: removedId,
+      workspaceId: "workspace",
+      internal: false,
+    };
+    const internalRemoval = {
+      type: "agent_removed",
+      agentId: internalId,
+      workspaceId: "workspace",
+      internal: true,
+    };
+    expect(publicEvents).toEqual([publicRemoval]);
+    expect(allEvents).toEqual([publicRemoval, internalRemoval]);
+    expect(scopedEvents).toEqual([publicRemoval]);
+    expect(internalEvents).toEqual([internalRemoval]);
+    expect(unrelatedEvents).toEqual([]);
+  } finally {
+    for (const release of releases) release();
+  }
+});
+
 test("getAgent returns internal agents by ID", async () => {
   const internalAgentId = "00000000-0000-4000-8000-000000000107";
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-test-"));
@@ -7848,7 +8366,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,
@@ -8289,6 +8807,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");
@@ -8836,14 +9466,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),
       );
@@ -10484,6 +11176,88 @@ 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);
+  const timeline = new InMemoryAgentTimelineStore();
+  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,
+    timelineStore: timeline,
+    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();
+    expect(
+      timeline
+        .getItems(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);
@@ -11341,7 +12115,7 @@ test("listImportableSessions searches every provider result before global rankin
   ]);
 });
 
-test("user_message events wrapping a paseo-system envelope are not added to the timeline", async () => {
+test("system-injected prompts appear as trigger tools in the live timeline", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-envelope-live-"));
   const storagePath = join(workdir, "agents");
   const storage = new AgentStorage(storagePath, logger);
@@ -11370,13 +12144,16 @@ test("user_message events wrapping a paseo-system envelope are not added to the
   await manager.runAgent(snapshot.id, { text: "do something" });
 
   const timeline = manager.getTimeline(snapshot.id);
+  expect(timeline).toContainEqual(
+    expect.objectContaining({ type: "tool_call", name: "heartbeat", status: "completed" }),
+  );
   const userMessages = timeline.filter((item) => item.type === "user_message");
 
   expect(userMessages).toHaveLength(1);
   expect(userMessages[0].text).toBe("plain user message");
 });
 
-test("user_message events wrapping a paseo-system envelope are not restored during history replay", async () => {
+test("system-injected prompts appear as trigger tools during history replay", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-envelope-history-"));
   const storagePath = join(workdir, "agents");
   const storage = new AgentStorage(storagePath, logger);
@@ -11411,6 +12188,9 @@ test("user_message events wrapping a paseo-system envelope are not restored duri
   await manager.hydrateTimelineFromProvider(snapshot.id, { force: true });
 
   const timeline = manager.getTimeline(snapshot.id);
+  expect(timeline).toContainEqual(
+    expect.objectContaining({ type: "tool_call", name: "heartbeat", status: "completed" }),
+  );
   const userMessages = timeline.filter((item) => item.type === "user_message");
 
   expect(userMessages).toHaveLength(1);
@@ -11626,10 +12406,7 @@ test("commits startup notices once on create and after restored history", async
       exitCode: 0,
     },
   };
-  const limitedToolOutput: AgentTimelineItem = {
-    ...toolOutput,
-    detail: { type: "shell", command: "print output", output: "x".repeat(64 * 1024), exitCode: 0 },
-  };
+  const limitedToolOutput = limitAgentTimelineItemContent(toolOutput);
   class NotifyingSession extends TestAgentSession {
     readonly initialTimeline = [{ item: notice, timestamp: "2026-09-22T00:00:00.000Z" }];
     override async *streamHistory(): AsyncGenerator<AgentStreamEvent> {
@@ -12006,15 +12783,15 @@ test.each([
     const session = client.sessions[0]!;
     session.pushEvent({ type: "turn_started", provider: "codex", turnId: "hook-turn" });
     await expect
-      .poll(() => events.filter(({ name }) => name === "agent.turn_started").length)
+      .poll(() => events.filter(({ name }) => name === "agent.turn.before").length)
       .toBe(1);
     expect(timelineStore.itemReads).toBe(readsBeforeDispatch);
     session.pushEvent(terminalEvent);
     await expect
-      .poll(() => events.filter(({ name }) => name === "agent.turn_ended"))
+      .poll(() => events.filter(({ name }) => name === "agent.turn.after"))
       .toEqual([
         {
-          name: "agent.turn_ended",
+          name: "agent.turn.after",
           event: {
             agent: {
               id: agent.id,
@@ -12298,3 +13075,172 @@ test("an out-of-band command racing idle cleanup waits for the resumed runtime",
   expect(h.commands).toEqual(["/maintenance"]);
   expect(h.prompts).toEqual([]);
 });
+
+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);
+});
diff --git a/packages/server/src/server/agent/agent-manager.ts b/packages/server/src/server/agent/agent-manager.ts
index de823660da..fdecc4ad1c 100644
--- a/packages/server/src/server/agent/agent-manager.ts
+++ b/packages/server/src/server/agent/agent-manager.ts
@@ -1,3 +1,5 @@
+import type { AttachedAgentTool, PluginAgentToolsRuntime } from "../plugins/agent-tools.js";
+import type { AgentToolResult } from "@getpaseo/plugin/server";
 import type { RuntimeCleanupCandidate } from "./idle-runtime-cleanup/index.js";
 import { ensureAgentLoaded } from "./agent-loading.js";
 import { projectTimelineRows } from "./timeline-projection.js";
@@ -83,7 +85,11 @@ import {
 import { invokeRewindCapability, type RewindMode } from "./rewind/rewind.js";
 import { parseAgentMessage, projectAgentMessages } from "./agent-messages/index.js";
 import { isStaleProviderSessionError } from "./stale-provider-session-error.js";
-import { stripInternalPaseoMcpServer, withRuntimePaseoMcpServer } from "./runtime-mcp-config.js";
+import {
+  PASEO_MCP_SERVER_NAME,
+  stripInternalPaseoMcpServer,
+  withRuntimePaseoMcpServer,
+} from "./runtime-mcp-config.js";
 import { resolveCreateAgentTitles } from "./create-agent-title.js";
 import type { PaseoToolCatalogFactory } from "./tools/types.js";
 import { isPaseoToolPolicyEnabled } from "./paseo-tool-policy.js";
@@ -92,6 +98,7 @@ 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";
 
@@ -165,6 +172,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;
@@ -230,7 +260,9 @@ export type {
 
 export type AgentManagerEvent =
   | { type: "agent_state"; agent: ManagedAgent }
+  | { type: "agent_removed"; agentId: string; workspaceId?: string; internal: boolean }
   | { type: "provider_subagent"; event: ProviderSubagentStoreEvent }
+  | { type: "background_work"; agentId: string; items: AgentBackgroundWorkItem[] }
   | { type: "timeline_replacement"; agentId: string; epoch: string }
   | {
       type: "agent_stream";
@@ -317,6 +349,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 {
@@ -333,6 +367,7 @@ export interface AgentManagerOptions {
   terminalManager?: TerminalManager | null;
   mcpBaseUrl?: string;
   mcpAuthToken?: string;
+  pluginAgentTools?: PluginAgentToolsRuntime;
   paseoToolsEnabled?: boolean;
   paseoToolCatalogFactory?: PaseoToolCatalogFactory;
   resolvePaseoToolPolicy?: (provider: AgentProvider) => ProviderPaseoToolsPolicy | undefined;
@@ -379,6 +414,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 };
@@ -414,6 +461,8 @@ interface ManagedAgentBase {
   owner?: AgentOwner;
   capabilities: AgentCapabilityFlags;
   config: AgentSessionConfig;
+  /** Explicit launch overrides, before per-opening hooks and daemon-owned variables. */
+  launchEnv?: Record<string, string>;
   runtimeInfo?: AgentRuntimeInfo;
   createdAt: Date;
   updatedAt: Date;
@@ -442,6 +491,11 @@ 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" }).
    */
@@ -556,18 +610,20 @@ interface AgentMetadataPatch {
 
 const SYSTEM_ERROR_PREFIX = "[System Error]";
 
-function attachPersistenceCwd(
+function normalizePersistenceForConfig(
   handle: AgentPersistenceHandle | null,
-  cwd: string,
+  config: AgentSessionConfig,
 ): AgentPersistenceHandle | null {
   if (!handle) {
     return null;
   }
+  const { mcpServers: _launchMcpServers, ...metadata } = handle.metadata ?? {};
   return {
     ...handle,
     metadata: {
-      ...handle.metadata,
-      cwd,
+      ...metadata,
+      cwd: config.cwd,
+      ...(config.mcpServers ? { mcpServers: config.mcpServers } : {}),
     },
   };
 }
@@ -746,6 +802,7 @@ export class AgentManager {
   private readonly agents = new Map<string, LiveManagedAgent>();
   private readonly timelineStore: InMemoryAgentTimelineStore;
   private readonly providerSubagents = new ProviderSubagentStore();
+  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>();
@@ -759,6 +816,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>();
@@ -766,6 +824,10 @@ export class AgentManager {
   private readonly agentStreamCoalescer: AgentStreamCoalescer;
   private mcpBaseUrl: string | null;
   private readonly mcpAuthToken: string | null;
+  private sessionOpenGeneration = 0;
+  private readonly sessionOpenGenerations = new Map<string, number>();
+  private readonly attachedPluginTools = new Map<string, AttachedAgentTool[]>();
+  private readonly pluginAgentTools: PluginAgentToolsRuntime | undefined;
   private paseoToolsEnabled = true;
   private paseoToolCatalogFactory: PaseoToolCatalogFactory | null = null;
   private readonly paseoToolPolicies = new Map<string, ProviderPaseoToolsPolicy | undefined>();
@@ -783,6 +845,7 @@ export class AgentManager {
 
   constructor(options: AgentManagerOptions) {
     this.pluginLifecycle = options.pluginLifecycle;
+    this.pluginAgentTools = options.pluginAgentTools;
     this.timelineStore = options.timelineStore ?? new InMemoryAgentTimelineStore();
     this.idFactory = options.idFactory ?? (() => randomUUID());
     this.registry = options?.registry;
@@ -887,6 +950,62 @@ export class AgentManager {
     this.paseoToolCatalogFactory = factory;
   }
 
+  invalidatePluginSessions(): void {
+    this.sessionOpenGeneration++;
+  }
+
+  async reloadStalePluginSession(agentId: string): Promise<void> {
+    if (!this.needsPluginSessionReload(agentId)) return;
+    await this.trackAgentRegistrationOperation(
+      this.runLifecycleMutation(agentId, async () => {
+        if (!this.needsPluginSessionReload(agentId)) return;
+        await this.reloadAgentSessionInternal(agentId);
+      }),
+    );
+  }
+
+  private needsPluginSessionReload(agentId: string): boolean {
+    const agent = this.getAgent(agentId);
+    return (
+      agent !== null &&
+      agent.lifecycle !== "closed" &&
+      this.sessionOpenGenerations.get(agentId) !== this.sessionOpenGeneration &&
+      !this.hasInFlightRun(agentId)
+    );
+  }
+
+  getPluginTools(agentId: string): readonly AttachedAgentTool[] {
+    return (this.attachedPluginTools.get(agentId) ?? []).filter((tool) =>
+      this.pluginAgentTools?.isToolPluginAvailable(tool.pluginId, tool.pluginInstanceId),
+    );
+  }
+
+  async executePluginTool(
+    tool: AttachedAgentTool,
+    agentId: string,
+    input: unknown,
+    signal?: AbortSignal,
+  ): Promise<AgentToolResult> {
+    const agent = this.getAgent(agentId);
+    if (!agent || agent.lifecycle === "closed") throw new Error(`Agent is not live: ${agentId}`);
+    if (!this.pluginAgentTools) throw new Error("Plugin tools are unavailable");
+    const record = await this.registry?.get(agentId);
+    return this.pluginAgentTools.callTool(
+      tool.pluginId,
+      tool.pluginInstanceId,
+      describeHookAgent({ ...agent, title: record?.title ?? agent.config.title }),
+      tool.name,
+      input,
+      signal,
+    );
+  }
+
+  private detachPluginTools(agentId: string): void {
+    this.attachedPluginTools.delete(agentId);
+    this.sessionOpenGenerations.delete(agentId);
+    this.pluginAgentTools?.detachTools(agentId);
+  }
+
   getPaseoToolPolicy(agentId: string): ProviderPaseoToolsPolicy | undefined {
     return this.paseoToolPolicies.get(agentId);
   }
@@ -1244,6 +1363,38 @@ export class AgentManager {
     return 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 });
+  }
+
   listProviderSubagentActivity(): ProviderSubagentDescriptor[] {
     const publicParentIds = new Set(
       Array.from(this.agents.values())
@@ -1288,7 +1439,7 @@ export class AgentManager {
     this.assertAcceptingAgentRegistrations();
     const resolvedAgentId = validateAgentId(agentId ?? this.idFactory(), "createAgent");
     if (this.pluginLifecycle && !config.internal) {
-      const request = await this.pluginLifecycle.before("agent.create", {
+      const request = await this.pluginLifecycle.before("agent.create.before", {
         config,
         env: options.env,
       });
@@ -1312,21 +1463,29 @@ export class AgentManager {
       storedConfig.cwd,
       paseoToolPolicy,
       options?.env,
-      { reason: "create", purpose: "interactive", workspaceId: options.workspaceId ?? null },
+      {
+        reason: "create",
+        purpose: "interactive",
+        workspaceId: options.workspaceId ?? null,
+        title: options.initialTitle ?? storedConfig.title ?? null,
+        labels: options.labels ?? {},
+      },
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
     const createOptions = this.buildCreateSessionOptions(options);
     const session = await client.createSession(providerLaunchConfig, launchContext, createOptions);
-    await this.requireExternalMcpSupport(session, storedConfig);
+    await this.requireExternalMcpSupport(session, providerLaunchConfig, launchContext);
     const agent = await this.registerSession(session, storedConfig, resolvedAgentId, {
       labels: options.labels,
       initialTitle: options.initialTitle,
       workspaceId: options.workspaceId,
       owner: options.owner,
+      background: options.background,
+      launchEnv: options.env ? { ...options.env } : undefined,
       historyPrimed: true,
     });
     if (!agent.internal) {
-      this.pluginLifecycle?.emit("agent.created", {
+      this.pluginLifecycle?.emit("agent.create.after", {
         agent: describeHookAgent({ ...agent, title: agent.config.title }),
       });
     }
@@ -1354,6 +1513,7 @@ export class AgentManager {
       labels?: Record<string, string>;
       workspaceId?: string;
       owner?: AgentOwner;
+      background?: boolean;
       attention?: AttentionState;
     },
     resumeOptions?: AgentResumeSessionOptions,
@@ -1386,6 +1546,7 @@ export class AgentManager {
       labels?: Record<string, string>;
       workspaceId?: string;
       owner?: AgentOwner;
+      background?: boolean;
       attention?: AttentionState;
     },
     resumeOptions?: AgentResumeSessionOptions,
@@ -1406,15 +1567,14 @@ 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 { storedConfig, launchConfig, paseoToolPolicy } = await this.prepareSessionConfig(
       mergedConfig,
       resolvedAgentId,
-      { purpose },
+      { purpose, env: launchEnv },
     );
     const client = this.requireClient(handle.provider);
     const available = await client.isAvailable();
@@ -1429,11 +1589,13 @@ export class AgentManager {
       client,
       storedConfig.cwd,
       paseoToolPolicy,
-      undefined,
+      launchEnv,
       {
         reason: "resume",
         purpose,
         workspaceId: options?.workspaceId ?? null,
+        title: record?.title ?? mergedConfig.title ?? null,
+        labels: record?.labels ?? options?.labels ?? {},
       },
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
@@ -1443,9 +1605,11 @@ export class AgentManager {
       launchContext,
       currentResumeOptions,
     );
-    await this.requireExternalMcpSupport(session, storedConfig);
+    if (purpose === "history") this.historySessions.add(session);
+    await this.requireExternalMcpSupport(session, providerLaunchConfig, launchContext);
     return this.registerSession(session, storedConfig, resolvedAgentId, {
       ...options,
+      launchEnv,
       persistence: handle,
       restoring: true,
     });
@@ -1491,7 +1655,12 @@ export class AgentManager {
       storedConfig.cwd,
       paseoToolPolicy,
       undefined,
-      { reason: "import", purpose: "interactive", workspaceId: input.workspaceId },
+      {
+        reason: "import",
+        purpose: "interactive",
+        workspaceId: input.workspaceId,
+        labels: input.labels ?? {},
+      },
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
     const imported = await client.importSession(
@@ -1501,6 +1670,7 @@ export class AgentManager {
       },
       { config: providerLaunchConfig, storedConfig, launchContext },
     );
+    await this.requireExternalMcpSupport(imported.session, providerLaunchConfig, launchContext);
     let handedToRegistration = false;
     try {
       const importedConfig = await this.normalizeConfig(
@@ -1577,6 +1747,7 @@ export class AgentManager {
     const { storedConfig, launchConfig, paseoToolPolicy } = await this.prepareSessionConfig(
       refreshConfig,
       agentId,
+      { env: existing.launchEnv },
     );
     const hadPreviousPaseoToolPolicy = this.paseoToolPolicies.has(agentId);
     const previousPaseoToolPolicy = this.paseoToolPolicies.get(agentId);
@@ -1585,15 +1756,21 @@ export class AgentManager {
       client,
       storedConfig.cwd,
       paseoToolPolicy,
-      undefined,
-      { reason: "refresh", purpose: "interactive", workspaceId: existing.workspaceId },
+      existing.launchEnv,
+      {
+        reason: "refresh",
+        purpose: "interactive",
+        workspaceId: existing.workspaceId,
+        title: await this.resolveInitialPersistedTitle(agentId, existing.config, null),
+        labels: existing.labels,
+      },
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
     if (
-      Object.keys(storedConfig.mcpServers ?? {}).length > 0 &&
+      Object.keys(stripInternalPaseoMcpServer(providerLaunchConfig).mcpServers ?? {}).length > 0 &&
       existing.session.capabilities.supportsMcpServers !== true
     ) {
-      throw new Error(`Provider '${provider}' does not support MCP servers`);
+      throw this.unsupportedMcpError(providerLaunchConfig, launchContext);
     }
 
     let session: AgentSession | undefined;
@@ -1604,6 +1781,7 @@ export class AgentManager {
       await this.closeReloadedSession(existing.session, agentId);
       await this.drainSessionEvents(agentId);
       this.cancelRunningProviderSubagents(agentId);
+      this.clearBackgroundWork(agentId);
       closedExisting = this.prepareAgentForClosure(existing, "agent reloaded");
       await this.persistSnapshot(closedExisting);
       this.assertAcceptingAgentRegistrations();
@@ -1612,7 +1790,7 @@ export class AgentManager {
       session = handle
         ? await client.resumeSession(handle, providerLaunchConfig, launchContext)
         : await client.createSession(providerLaunchConfig, launchContext);
-      await this.requireExternalMcpSupport(session, storedConfig);
+      await this.requireExternalMcpSupport(session, providerLaunchConfig, launchContext);
       this.assertAcceptingAgentRegistrations();
 
       if (rehydrateFromDisk) {
@@ -1630,6 +1808,8 @@ export class AgentManager {
         labels: existing.labels,
         workspaceId: existing.workspaceId,
         owner: existing.owner,
+        background: existing.background,
+        launchEnv: existing.launchEnv,
         createdAt: existing.createdAt,
         updatedAt: existing.updatedAt,
         lastUserMessageAt: existing.lastUserMessageAt,
@@ -1645,11 +1825,13 @@ 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;
     } finally {
       if (!handedToRegistration) {
+        this.detachPluginTools(agentId);
         if (hadPreviousPaseoToolPolicy) {
           this.paseoToolPolicies.set(agentId, previousPaseoToolPolicy);
         } else {
@@ -1848,7 +2030,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);
     this.cancelRunningProviderSubagents(agentId);
+    // close() drops the session's subscribers before the provider could report an empty list.
+    this.clearBackgroundWork(agentId);
     const closedAgent = this.prepareAgentForClosure(agent, "agent closed");
 
     let persistError: unknown;
@@ -1857,6 +2042,7 @@ export class AgentManager {
     } catch (error) {
       persistError = error;
     }
+    this.detachPluginTools(agentId);
     this.emitClosedAgent(closedAgent, { persist: false });
     this.logger.trace(
       {
@@ -1948,7 +2134,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;
@@ -1970,7 +2156,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 {
@@ -2022,7 +2211,7 @@ export class AgentManager {
     const archivedRecord = buildArchivedAgentRecord(record, options);
     await this.requireRegistry().upsert(archivedRecord);
     if (!record.archivedAt && !record.internal) {
-      this.pluginLifecycle?.emit("agent.archived", {
+      this.pluginLifecycle?.emit("agent.archive.after", {
         agent: describeHookAgent(archivedRecord),
         archivedAt: archivedRecord.archivedAt,
       });
@@ -2056,7 +2245,7 @@ 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,
@@ -2080,13 +2269,14 @@ export class AgentManager {
         lastError: record.lastError ?? undefined,
         attention,
         internal: record.internal,
+        background: record.background,
         labels: record.labels,
       },
     });
   }
 
   async setAgentMode(agentId: string, modeId: string): Promise<AgentProviderNotice | null> {
-    const agent = this.requireSessionAgent(agentId);
+    const agent = await this.ensureInteractiveSession(agentId);
     const notice = (await agent.session.setMode(modeId)) ?? null;
     await this.drainSessionEvents(agentId);
     const currentMode = (await agent.session.getCurrentMode()) ?? modeId;
@@ -2102,7 +2292,7 @@ export class AgentManager {
   }
 
   async setAgentModel(agentId: string, modelId: string | null): Promise<void> {
-    const agent = this.requireSessionAgent(agentId);
+    const agent = await this.ensureInteractiveSession(agentId);
     const normalizedModelId =
       typeof modelId === "string" && modelId.trim().length > 0 ? modelId : null;
 
@@ -2124,7 +2314,7 @@ export class AgentManager {
     agentId: string,
     thinkingOptionId: string | null,
   ): Promise<AgentProviderNotice | null> {
-    const agent = this.requireSessionAgent(agentId);
+    const agent = await this.ensureInteractiveSession(agentId);
     const normalizedThinkingOptionId =
       typeof thinkingOptionId === "string" && thinkingOptionId.trim().length > 0
         ? thinkingOptionId
@@ -2155,7 +2345,7 @@ export class AgentManager {
   }
 
   async setAgentFeature(agentId: string, featureId: string, value: unknown): Promise<void> {
-    const agent = this.requireAgent(agentId);
+    const agent = await this.ensureInteractiveSession(agentId);
 
     if (!agent.session.setFeature) {
       throw new Error("Agent session does not support setting features");
@@ -2298,16 +2488,16 @@ export class AgentManager {
   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);
@@ -2317,18 +2507,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);
@@ -2397,23 +2587,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) } : {}),
       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 &&
@@ -2536,7 +2731,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;
@@ -2635,7 +2830,7 @@ export class AgentManager {
         throw error;
       }
       if (isStaleProviderSessionError(error)) {
-        pendingRun.start = { status: "failed", error: error.message };
+        this.runs.settleForegroundStart(pendingRun, { status: "failed", error: error.message });
         agent.pendingReplacement = false;
         if (!agent.activeForegroundTurnId) agent.lifecycle = "idle";
         this.runs.settleForegroundRun(agentId, pendingRun.token);
@@ -2643,24 +2838,56 @@ export class AgentManager {
       }
       agent.pendingReplacement = false;
       const errorMsg = error instanceof Error ? error.message : "Failed to start turn";
-      pendingRun.start = { status: "failed", error: errorMsg };
-      // A terminal rejection belongs after the submitted prompt even though no provider turn exists.
-      if (options?.clientMessageId) {
-        this.recordSubmittedPrompt(agent, prompt, options.clientMessageId, "rejected", {
-          messageId: options.clientMessageId,
+      this.runs.settleForegroundStart(pendingRun, { status: "failed", error: errorMsg });
+      try {
+        // A terminal rejection belongs after the submitted prompt even though no provider turn exists.
+        if (options?.clientMessageId) {
+          this.recordSubmittedPrompt(agent, prompt, options.clientMessageId, "rejected", {
+            messageId: options.clientMessageId,
+          });
+        }
+        await this.handleStreamEvent(agent, {
+          type: "turn_failed",
+          provider: agent.provider,
+          error: errorMsg,
         });
+        this.finalizeForegroundTurn(agent);
+      } finally {
+        // A steer waiting on this start is released only once the run is cleared.
+        this.runs.settleForegroundRun(agentId, pendingRun.token);
       }
-      await this.handleStreamEvent(agent, {
-        type: "turn_failed",
-        provider: agent.provider,
-        error: errorMsg,
-      });
-      this.finalizeForegroundTurn(agent);
-      this.runs.settleForegroundRun(agentId, pendingRun.token);
       throw error;
     }
   }
 
+  private async ensureInteractiveSession(agentId: string): Promise<ActiveManagedAgent> {
+    const agent = this.requireSessionAgent(agentId);
+    if (this.historySessions.has(agent.session)) {
+      await this.trackAgentRegistrationOperation(
+        this.runLifecycleMutation(agentId, async () => {
+          const record = await this.registry?.get(agentId);
+          if (record?.archivedAt) throw new Error(`Agent is archived: ${agentId}`);
+          const current = this.requireSessionAgent(agentId);
+          if (this.historySessions.has(current.session)) {
+            // Recheck inside the lane: another prompt may already have upgraded it.
+            // Reload validates the directory before releasing readable history.
+            await this.reloadAgentSessionInternal(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,
@@ -2683,6 +2910,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,
@@ -2733,9 +2962,10 @@ export class AgentManager {
         agent.pendingReplacement = false;
       }
       const turnStartedAt = new Date();
-      pendingRun.start = { status: "started", turnId };
+      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
@@ -2836,7 +3066,10 @@ export class AgentManager {
         ? { provider: mutableAgent.provider, sessionId: mutableAgent.runtimeInfo.sessionId }
         : null);
     if (persistenceHandle) {
-      mutableAgent.persistence = attachPersistenceCwd(persistenceHandle, mutableAgent.cwd);
+      mutableAgent.persistence = normalizePersistenceForConfig(
+        persistenceHandle,
+        mutableAgent.config,
+      );
     }
     this.logger.trace(
       {
@@ -2922,7 +3155,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;
     });
@@ -2939,6 +3178,9 @@ export class AgentManager {
     prompt: AgentPromptInput,
     options?: AgentSteerOptions,
   ): Promise<ActiveTurnSteerDispatchResult> {
+    // A turn that is still starting has no id to steer yet. Replacing it would drop its
+    // prompt, so wait until it is accepted (or fails) and steer the turn it became.
+    await this.runs.waitForForegroundStart(agentId);
     const agent = this.requireSessionAgent(agentId);
     const expectedTurnId = agent.activeForegroundTurnId ?? agent.activeTurnId;
     if (!expectedTurnId) {
@@ -2952,7 +3194,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;
         })
@@ -3057,6 +3305,7 @@ export class AgentManager {
     prompt: AgentPromptInput,
     clientMessageId: string | undefined,
     expectedTurnId: string,
+    providerMessageId: string | undefined,
   ): Promise<void> {
     if (!clientMessageId) {
       return;
@@ -3064,6 +3313,7 @@ export class AgentManager {
     this.recordSubmittedPrompt(agent, prompt, clientMessageId, "accepted", {
       messageId: clientMessageId,
       turnId: expectedTurnId,
+      ...(providerMessageId ? { providerMessageId } : {}),
     });
     this.emitState(agent);
   }
@@ -3348,7 +3598,12 @@ export class AgentManager {
   }
 
   async rewind(agentId: string, messageId: string, mode: RewindMode): Promise<void> {
-    const agent = this.requireSessionAgent(agentId);
+    let agent = this.requireSessionAgent(agentId);
+    if (this.historySessions.has(agent.session)) {
+      agent = await this.ensureInteractiveSession(agentId);
+    }
+    // An interactive session must acquire its rewind lock without yielding.
+
     const submittedRow = this.timelineStore
       .getRows(agentId)
       .find(
@@ -3395,6 +3650,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",
@@ -3410,6 +3669,15 @@ export class AgentManager {
     await this.deleteCommittedTimeline(agentId);
   }
 
+  notifyAgentRemoved(agent: Pick<StoredAgentRecord, "id" | "workspaceId" | "internal">): void {
+    this.dispatch({
+      type: "agent_removed",
+      agentId: agent.id,
+      workspaceId: agent.workspaceId,
+      internal: agent.internal === true,
+    });
+  }
+
   async deleteCommittedTimeline(agentId: string): Promise<void> {
     await this.durableTimelineStore?.deleteAgent(agentId);
   }
@@ -3668,6 +3936,8 @@ export class AgentManager {
       publishWhenReady?: boolean;
       workspaceId?: string;
       owner?: AgentOwner;
+      background?: boolean;
+      launchEnv?: Record<string, string>;
     },
   ): Promise<ManagedAgent> {
     let registered = false;
@@ -3696,6 +3966,7 @@ export class AgentManager {
         config,
         now,
         durableTimelineHasRows,
+        background: options?.background === true,
         options,
       });
 
@@ -3780,16 +4051,23 @@ export class AgentManager {
 
   private async requireExternalMcpSupport(
     session: AgentSession,
-    storedConfig: AgentSessionConfig,
+    launchConfig: AgentSessionConfig,
+    launchContext: AgentLaunchContext,
   ): Promise<void> {
     if (
-      Object.keys(storedConfig.mcpServers ?? {}).length === 0 ||
+      Object.keys(stripInternalPaseoMcpServer(launchConfig).mcpServers ?? {}).length === 0 ||
       session.capabilities.supportsMcpServers === true
     ) {
       return;
     }
     await this.closeUnregisteredSession(session);
-    throw new Error(`Provider '${storedConfig.provider}' does not support MCP servers`);
+    throw this.unsupportedMcpError(launchConfig, launchContext);
+  }
+
+  private unsupportedMcpError(config: AgentSessionConfig, context: AgentLaunchContext): Error {
+    const owners = [...new Set(Object.values(context.mcpServerOwners ?? {}))];
+    const source = owners.length ? ` (plugin ${owners.join(", ")})` : "";
+    return new Error(`Provider '${config.provider}' does not support MCP servers${source}`);
   }
 
   private async initializeAgentTimelineForRegister(params: {
@@ -3833,6 +4111,7 @@ export class AgentManager {
     config: AgentSessionConfig;
     now: Date;
     durableTimelineHasRows: boolean;
+    background: boolean;
     options:
       | {
           createdAt?: Date;
@@ -3846,6 +4125,7 @@ export class AgentManager {
           persistence?: AgentPersistenceHandle;
           workspaceId?: string;
           owner?: AgentOwner;
+          launchEnv?: Record<string, string>;
         }
       | undefined;
   }): ActiveManagedAgent {
@@ -3856,6 +4136,7 @@ export class AgentManager {
       cwd: config.cwd,
       workspaceId: options?.workspaceId,
       owner: options?.owner,
+      launchEnv: options?.launchEnv,
       session,
       capabilities: session.capabilities,
       config,
@@ -3875,9 +4156,9 @@ export class AgentManager {
       foregroundTurnWaiters: new Set<ForegroundTurnWaiter>(),
       finalizedForegroundTurnIds: new Set<string>(),
       unsubscribeSession: null,
-      persistence: attachPersistenceCwd(
+      persistence: normalizePersistenceForConfig(
         options?.persistence ?? session.describePersistence(),
-        config.cwd,
+        config,
       ),
       historyPrimed: options?.historyPrimed ?? durableTimelineHasRows,
       lastUserMessageAt: options?.lastUserMessageAt ?? null,
@@ -3885,6 +4166,7 @@ export class AgentManager {
       lastError: options?.lastError,
       attention: resolveInitialAttention(options?.attention),
       internal: config.internal ?? false,
+      background: params.background,
       labels: options?.labels ?? {},
     } as ActiveManagedAgent;
   }
@@ -3940,15 +4222,17 @@ export class AgentManager {
   private discardRetainedAgentState(agentId: string): void {
     this.timelineStore.delete(agentId);
     this.paseoToolPolicies.delete(agentId);
+    this.detachPluginTools(agentId);
     for (const event of this.providerSubagents.deleteParent(agentId)) {
       this.dispatch({ type: "provider_subagent", event });
     }
+    this.clearBackgroundWork(agentId);
   }
 
   private emitClosedAgent(agent: ManagedAgentClosed, options?: { persist?: boolean }): void {
     this.emitState(agent, options);
     if (!agent.internal) {
-      this.pluginLifecycle?.emit("agent.closed", {
+      this.pluginLifecycle?.emit("agent.close.after", {
         agent: describeHookAgent({ ...agent, title: agent.config.title }),
       });
     }
@@ -4052,6 +4336,14 @@ export class AgentManager {
       this.dispatch({ type: "provider_subagent", event: 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(
@@ -4180,9 +4472,9 @@ export class AgentManager {
         newInfo.modeId !== agent.runtimeInfo?.modeId;
       agent.runtimeInfo = newInfo;
       if (!agent.persistence && newInfo.sessionId) {
-        agent.persistence = attachPersistenceCwd(
+        agent.persistence = normalizePersistenceForConfig(
           { provider: agent.provider, sessionId: newInfo.sessionId },
-          agent.cwd,
+          agent.config,
         );
       }
       // Emit state if runtimeInfo changed so clients get the updated model
@@ -4540,9 +4832,9 @@ export class AgentManager {
       case "model_changed":
         agent.runtimeInfo = event.runtimeInfo;
         if (!agent.persistence && event.runtimeInfo.sessionId) {
-          agent.persistence = attachPersistenceCwd(
+          agent.persistence = normalizePersistenceForConfig(
             { provider: agent.provider, sessionId: event.runtimeInfo.sessionId },
-            agent.cwd,
+            agent.config,
           );
         }
         this.applyObservedMode(agent, event.runtimeInfo.modeId ?? agent.currentModeId);
@@ -4616,7 +4908,7 @@ export class AgentManager {
   private refreshSessionPersistence(agent: ActiveManagedAgent): void {
     const handle = agent.session.describePersistence();
     if (handle) {
-      agent.persistence = attachPersistenceCwd(handle, agent.cwd);
+      agent.persistence = normalizePersistenceForConfig(handle, agent.config);
     }
   }
 
@@ -4804,6 +5096,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);
   }
@@ -4815,7 +5109,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);
@@ -5070,17 +5364,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,
@@ -5088,19 +5384,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 {
@@ -5256,7 +5558,14 @@ export class AgentManager {
     for (const subscriber of this.subscribers) {
       if (
         subscriber.agentId &&
-        event.type === "agent_stream" &&
+        (event.type === "agent_stream" || event.type === "agent_removed") &&
+        subscriber.agentId !== event.agentId
+      ) {
+        continue;
+      }
+      if (
+        subscriber.agentId &&
+        event.type === "background_work" &&
         subscriber.agentId !== event.agentId
       ) {
         continue;
@@ -5292,7 +5601,9 @@ export class AgentManager {
 
   private eventBelongsToInternalAgent(event: AgentManagerEvent): boolean {
     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"
@@ -5426,10 +5737,17 @@ export class AgentManager {
       reason: PluginSessionOpenRequest["reason"];
       purpose: PluginSessionOpenRequest["purpose"];
       workspaceId?: string | null;
+      title?: string | null;
+      labels?: Record<string, string>;
     },
   ): Promise<AgentLaunchContext> {
+    // A plugin changing during this open must still make the resulting session stale.
+    const generation = this.sessionOpenGeneration;
+    this.detachPluginTools(agentId);
+    let mcpServers: AgentSessionConfig["mcpServers"];
+    let mcpServerOwners: Record<string, string> | undefined;
     if (this.pluginLifecycle) {
-      const request: PluginSessionOpenRequest = {
+      const request = {
         agentId,
         provider: client.provider,
         cwd,
@@ -5437,29 +5755,49 @@ export class AgentManager {
         reason: opening?.reason ?? "resume",
         purpose: opening?.purpose ?? "interactive",
         env: { ...env },
+        title: opening?.title ?? null,
+        labels: opening?.labels ?? {},
+        tools: [],
+        mcpServers: {},
       };
-      const transformed = await this.pluginLifecycle.before("agent.session_open", request);
+      const transformed = await this.pluginLifecycle.before("agent.open.before", request);
       env = transformed.env;
+      if (request.purpose === "interactive") {
+        this.attachedPluginTools.set(agentId, transformed.tools as AttachedAgentTool[]);
+        mcpServers = transformed.mcpServers;
+        mcpServerOwners = transformed.mcpServerOwners;
+      }
     }
     const context: AgentLaunchContext = {
       agentId,
+      mcpServers,
+      mcpServerOwners,
       env: {
         ...env,
         PASEO_AGENT_ID: agentId,
         PASEO_AGENT_CWD: cwd,
       },
     };
-    if (
+    const useNativeTools =
       this.paseoToolsEnabled &&
       isPaseoToolPolicyEnabled(paseoToolPolicy) &&
-      client.capabilities.supportsNativePaseoTools &&
-      this.paseoToolCatalogFactory
+      client.capabilities.supportsNativePaseoTools;
+    if (
+      this.paseoToolCatalogFactory &&
+      (useNativeTools || this.getPluginTools(agentId).length > 0)
     ) {
-      context.paseoTools = await this.paseoToolCatalogFactory({
-        callerAgentId: agentId,
-        paseoToolPolicy,
-      });
+      try {
+        const catalog = await this.paseoToolCatalogFactory({
+          callerAgentId: agentId,
+          paseoToolPolicy,
+        });
+        if (useNativeTools) context.paseoTools = catalog;
+      } catch (error) {
+        this.detachPluginTools(agentId);
+        throw error;
+      }
     }
+    this.sessionOpenGenerations.set(agentId, generation);
     return context;
   }
 
@@ -5467,7 +5805,26 @@ export class AgentManager {
     launchConfig: AgentSessionConfig,
     launchContext: AgentLaunchContext,
   ): AgentSessionConfig {
-    return launchContext.paseoTools ? stripInternalPaseoMcpServer(launchConfig) : launchConfig;
+    const savedServerNames = new Set(
+      Object.keys(stripInternalPaseoMcpServer(launchConfig).mcpServers ?? {}),
+    );
+    for (const name of Object.keys(launchContext.mcpServers ?? {})) {
+      const owner = launchContext.mcpServerOwners?.[name];
+      if (name === PASEO_MCP_SERVER_NAME || savedServerNames.has(name)) {
+        const existingOwner = savedServerNames.has(name)
+          ? "agent saved configuration"
+          : "Paseo internal MCP server";
+        throw new Error(`MCP server '${name}' from plugin ${owner} collides with ${existingOwner}`);
+      }
+    }
+    const merged =
+      Object.keys(launchContext.mcpServers ?? {}).length > 0
+        ? {
+            ...launchConfig,
+            mcpServers: { ...launchConfig.mcpServers, ...launchContext.mcpServers },
+          }
+        : launchConfig;
+    return launchContext.paseoTools ? stripInternalPaseoMcpServer(merged) : merged;
   }
 
   private async requireAvailableClient(options: { provider: AgentProvider }): Promise<AgentClient> {
diff --git a/packages/server/src/server/agent/agent-messages/envelope.ts b/packages/server/src/server/agent/agent-messages/envelope.ts
index 2144d6ae02..a0aa880fce 100644
--- a/packages/server/src/server/agent/agent-messages/envelope.ts
+++ b/packages/server/src/server/agent/agent-messages/envelope.ts
@@ -1,5 +1,5 @@
 import { renderPromptAttachmentAsText } from "../prompt-attachments.js";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
 import type {
   AgentPromptContentBlock,
@@ -175,9 +175,18 @@ function projectAgentMessage(item: AgentTimelineItem): AgentTimelineItem | null
   if (item.type !== "user_message") return item;
   const message = parseAgentMessage(item.text);
   if (!message) {
-    // COMPAT(legacySystemEnvelope): added in v0.11.1; remove after 2027-04-08 once
-    // legacy notification history is retired. Schedules still use this envelope.
-    return isSystemInjectedEnvelope(item.text) ? null : item;
+    // Schedule bodies include their run ID, keeping identity stable across acceptance
+    // and provider replay even when the provider assigns its own message ID.
+    if (!isSystemInjectedEnvelope(item.text)) return item;
+    const text = item.text.slice("<paseo-system>\n".length, -"\n</paseo-system>".length);
+    return {
+      type: "tool_call",
+      callId: `paseo-system:${createHash("sha256").update(item.text).digest("hex")}`,
+      name: "heartbeat",
+      status: "completed",
+      error: null,
+      detail: { type: "plain_text", text, icon: "sparkles" },
+    };
   }
   const { source } = message;
   if (!source) {
diff --git a/packages/server/src/server/agent/agent-projections.test.ts b/packages/server/src/server/agent/agent-projections.test.ts
index ec4186b022..e9c6289db5 100644
--- a/packages/server/src/server/agent/agent-projections.test.ts
+++ b/packages/server/src/server/agent/agent-projections.test.ts
@@ -4,6 +4,7 @@ import { AGENT_LIFECYCLE_STATUSES } from "./agent-manager.js";
 import {
   buildStoredAgentPayload,
   toAgentPayload,
+  toAgentListItemPayload,
   toRecentProviderSessionDescriptorPayload,
   toStoredAgentRecord,
   type ManagedAgent,
@@ -539,3 +540,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 7d154e9c14..b11021a99c 100644
--- a/packages/server/src/server/agent/agent-projections.ts
+++ b/packages/server/src/server/agent/agent-projections.ts
@@ -95,6 +95,7 @@ export function toStoredAgentRecord(
     lastStatus: agent.lifecycle,
     lastModeId: agent.currentModeId ?? config?.modeId ?? null,
     config: config ?? null,
+    launchEnv: agent.launchEnv ? { ...agent.launchEnv } : undefined,
     runtimeInfo,
     features: normalizeFeatures(agent.features),
     persistence,
@@ -105,6 +106,7 @@ export function toStoredAgentRecord(
       ? agent.attention.attentionTimestamp.toISOString()
       : null,
     internal: options?.internal,
+    ...(agent.background ? { background: true } : {}),
     owner: agent.owner,
   } satisfies StoredAgentRecord;
 }
@@ -148,7 +150,7 @@ export function toAgentPayload(
     title: options?.title ?? null,
     labels: agent.labels,
     archivedAt: options?.archivedAt ?? null,
-    ...(agent.internal ? { internal: true } : {}),
+    ...visibilityFlags(agent),
   };
 
   const usage = sanitizeUsage(agent.lastUsage);
@@ -205,6 +207,17 @@ 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 } : {}),
+  };
+}
+
 export function buildStoredAgentPayload(
   record: StoredAgentRecord,
   validProviders: Iterable<AgentProvider>,
@@ -257,7 +270,7 @@ 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),
     ...(typeof record.lastError === "string" ? { lastError: record.lastError } : {}),
     ...(providerAvailable ? {} : { providerUnavailable: true }),
@@ -274,6 +287,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,
diff --git a/packages/server/src/server/agent/agent-prompt.test.ts b/packages/server/src/server/agent/agent-prompt.test.ts
index 00e70756de..2c150bd2e1 100644
--- a/packages/server/src/server/agent/agent-prompt.test.ts
+++ b/packages/server/src/server/agent/agent-prompt.test.ts
@@ -357,3 +357,21 @@ test("a human pasting an agent envelope stays a human message through provider r
     clientMessageId: "human-submission",
   });
 });
+
+test("schedule prompts remain visible as completed tool calls on replay", () => {
+  const text = formatSystemNotificationPrompt("Heartbeat: check progress");
+  expect(projectAgentMessages({ type: "user_message", messageId: "fire-1", text })).toEqual([
+    expect.objectContaining({
+      type: "tool_call",
+      status: "completed",
+      detail: { type: "plain_text", text: "Heartbeat: check progress", icon: "sparkles" },
+    }),
+  ]);
+});
+
+test("schedule trigger identity survives the provider assigning a message ID", () => {
+  const text = formatSystemNotificationPrompt("Schedule fired (id=heartbeat, run=run-1).");
+  expect(projectAgentMessages({ type: "user_message", text })).toEqual(
+    projectAgentMessages({ type: "user_message", text, messageId: "provider-message" }),
+  );
+});
diff --git a/packages/server/src/server/agent/agent-prompt.ts b/packages/server/src/server/agent/agent-prompt.ts
index 08aca8e626..dde5c02bbd 100644
--- a/packages/server/src/server/agent/agent-prompt.ts
+++ b/packages/server/src/server/agent/agent-prompt.ts
@@ -15,6 +15,7 @@ export type AgentRunController = Pick<
   | "getAgent"
   | "tryRunOutOfBand"
   | "hasInFlightRun"
+  | "reloadStalePluginSession"
   | "replaceAgentRun"
   | "steerOrReplaceActiveTurn"
   | "streamAgent"
@@ -115,6 +116,7 @@ export async function startAgentRun(
     return { disposition: "out_of_band" };
   }
   try {
+    await agentManager.reloadStalePluginSession(agentId);
     return await startAgentRunInner(agentManager, agentId, prompt, logger, options);
   } catch (error) {
     if (!isStaleProviderSessionError(error)) throw error;
diff --git a/packages/server/src/server/agent/agent-run-state.test.ts b/packages/server/src/server/agent/agent-run-state.test.ts
new file mode 100644
index 0000000000..29e09a5f94
--- /dev/null
+++ b/packages/server/src/server/agent/agent-run-state.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, test } from "vitest";
+
+import { AgentRunState } from "./agent-run-state.js";
+
+function track(promise: Promise<void>): { readonly resolved: boolean } {
+  const state = { resolved: false };
+  void (async () => {
+    await promise;
+    state.resolved = true;
+  })();
+  return state;
+}
+
+async function flushMicrotasks(): Promise<void> {
+  await new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+describe("waitForForegroundStart", () => {
+  test("resolves once the starting turn has an id", async () => {
+    const runs = new AgentRunState();
+    const run = runs.createPendingRun("agent");
+    const wait = track(runs.waitForForegroundStart("agent"));
+
+    await flushMicrotasks();
+    expect(wait.resolved).toBe(false);
+
+    runs.settleForegroundStart(run, { status: "started", turnId: "turn-1" });
+    await flushMicrotasks();
+    expect(wait.resolved).toBe(true);
+  });
+
+  test("waits for a failed start's run to be cleared", async () => {
+    const runs = new AgentRunState();
+    const run = runs.createPendingRun("agent");
+    const wait = track(runs.waitForForegroundStart("agent"));
+
+    runs.settleForegroundStart(run, { status: "failed", error: "start failed" });
+    await flushMicrotasks();
+    expect(wait.resolved).toBe(false);
+    expect(runs.hasPendingRun("agent")).toBe(true);
+
+    runs.settleForegroundRun("agent", run.token);
+    await flushMicrotasks();
+    expect(wait.resolved).toBe(true);
+  });
+
+  test("resolves at once when no turn is starting", async () => {
+    const runs = new AgentRunState();
+    await expect(runs.waitForForegroundStart("agent")).resolves.toBeUndefined();
+  });
+});
diff --git a/packages/server/src/server/agent/agent-run-state.ts b/packages/server/src/server/agent/agent-run-state.ts
index ad1eb0af34..0ea85f6d81 100644
--- a/packages/server/src/server/agent/agent-run-state.ts
+++ b/packages/server/src/server/agent/agent-run-state.ts
@@ -10,14 +10,18 @@ export interface ForegroundTurnWaiter {
   resolveSettled: () => void;
 }
 
+type ForegroundRunStart =
+  | { status: "pending" }
+  | { status: "started"; turnId: string }
+  | { status: "failed"; error: string };
+
 export interface PendingForegroundRun {
   token: string;
   kind: "foreground";
   stagedEvents: AgentStreamEvent[];
-  start:
-    | { status: "pending" }
-    | { status: "started"; turnId: string }
-    | { status: "failed"; error: string };
+  start: ForegroundRunStart;
+  turnStartedPromise: Promise<void>;
+  resolveTurnStarted: () => void;
   settled: boolean;
   settledPromise: Promise<void>;
   resolveSettled: () => void;
@@ -54,6 +58,28 @@ export class AgentRunState {
     return run?.kind === "foreground" ? run : null;
   }
 
+  settleForegroundStart(
+    run: PendingForegroundRun,
+    start: Exclude<ForegroundRunStart, { status: "pending" }>,
+  ): void {
+    run.start = start;
+    if (start.status === "started") {
+      run.resolveTurnStarted();
+    }
+  }
+
+  /**
+   * Resolves once the agent's foreground run has a turn id or has ended. A failed start
+   * resolves only once its run is cleared, so callers never see a failed run still tracked.
+   */
+  async waitForForegroundStart(agentId: string): Promise<void> {
+    const run = this.getPendingRun(agentId);
+    if (run?.start.status !== "pending") {
+      return;
+    }
+    await Promise.race([run.turnStartedPromise, run.settledPromise]);
+  }
+
   hasPendingRun(agentId: string): boolean {
     return this.getPendingRun(agentId) !== null;
   }
@@ -277,10 +303,16 @@ export class ForegroundTurnStream {
 }
 
 function createPendingForegroundRun(): PendingForegroundRun {
+  let resolveTurnStarted!: () => void;
+  const turnStartedPromise = new Promise<void>((resolvePromise) => {
+    resolveTurnStarted = resolvePromise;
+  });
   return {
     ...createTrackedRunState(),
     kind: "foreground",
     start: { status: "pending" },
+    turnStartedPromise,
+    resolveTurnStarted,
     stagedEvents: [],
   };
 }
diff --git a/packages/server/src/server/agent/agent-sdk-types.ts b/packages/server/src/server/agent/agent-sdk-types.ts
index 6818e65445..7604f1db76 100644
--- a/packages/server/src/server/agent/agent-sdk-types.ts
+++ b/packages/server/src/server/agent/agent-sdk-types.ts
@@ -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;
@@ -313,7 +317,10 @@ export type ToolCallDetail =
       subAgentType?: string;
       description?: string;
       childSessionId?: string;
-      log: string;
+      // COMPAT(subagent-log): added in v0.14.1, remove after 2027-04-30. Apps before v0.14.1
+      // require `log`; every producer sends it empty and carries the same tag. Optional here because
+      // protocol timeline items, where `log` is optional, flow into this type.
+      log?: string;
       actions?: Array<{
         index: number;
         toolName: string;
@@ -461,6 +468,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 {
@@ -616,6 +629,9 @@ export interface AgentSessionConfig {
 }
 
 export interface AgentLaunchContext {
+  /** Launch-only plugin MCP servers and their owners; never persisted. */
+  mcpServers?: Record<string, McpServerConfig>;
+  mcpServerOwners?: Record<string, string>;
   agentId?: string;
   env?: Record<string, string>;
   /**
@@ -687,6 +703,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.
@@ -694,6 +711,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. */
diff --git a/packages/server/src/server/agent/agent-storage.test.ts b/packages/server/src/server/agent/agent-storage.test.ts
index 723f612085..c87b812761 100644
--- a/packages/server/src/server/agent/agent-storage.test.ts
+++ b/packages/server/src/server/agent/agent-storage.test.ts
@@ -3,6 +3,8 @@ import os from "node:os";
 import path from "node:path";
 import { 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";
@@ -148,6 +150,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({
@@ -172,7 +269,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");
@@ -189,8 +286,8 @@ 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"] });
   });
@@ -210,7 +307,7 @@ describe("AgentStorage", () => {
     const record = await storage.get("agent-feature-values");
     expect(record?.config?.featureValues).toEqual({ fast_mode: true });
 
-    const reloaded = new AgentStorage(storagePath, logger);
+    const reloaded = new AgentStorage(storagePath, createTestLogger());
     const persisted = await reloaded.get("agent-feature-values");
     expect(persisted?.config?.featureValues).toEqual({ fast_mode: true });
     expect(buildSessionConfig(persisted!).featureValues).toEqual({ fast_mode: true });
@@ -223,7 +320,7 @@ describe("AgentStorage", () => {
       }),
     );
 
-    const reloaded = new AgentStorage(storagePath, logger);
+    const reloaded = new AgentStorage(storagePath, createTestLogger());
     const persisted = await reloaded.get("agent-no-feature-values");
     expect(persisted?.config?.featureValues).toBeUndefined();
     expect(buildSessionConfig(persisted!).featureValues).toBeUndefined();
@@ -312,7 +409,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");
   });
@@ -415,7 +512,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);
   });
 
@@ -486,12 +583,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);
   });
@@ -543,8 +640,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);
@@ -571,8 +668,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 be94a31d49..41ad500969 100644
--- a/packages/server/src/server/agent/agent-storage.ts
+++ b/packages/server/src/server/agent/agent-storage.ts
@@ -54,8 +54,10 @@ const STORED_AGENT_SCHEMA = z.object({
   title: z.string().nullable().optional(),
   labels: z.record(z.string(), z.string()).default({}),
   lastStatus: AgentStatusSchema.default("closed"),
+  resumeOnStartup: z.boolean().optional(),
   lastModeId: z.string().nullable().optional(),
   config: SERIALIZABLE_CONFIG_SCHEMA,
+  launchEnv: z.record(z.string(), z.string()).optional(),
   runtimeInfo: z
     .object({
       provider: z.string(),
@@ -73,6 +75,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(),
 });
@@ -102,9 +105,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) {
@@ -116,11 +124,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;
@@ -140,8 +256,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> {
@@ -231,6 +346,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);
@@ -259,6 +382,10 @@ 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;
     });
   }
@@ -279,9 +406,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) {
@@ -291,7 +418,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();
@@ -299,28 +426,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;
     }
@@ -357,14 +481,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> {
@@ -401,6 +522,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/agent-timeline-content.test.ts b/packages/server/src/server/agent/agent-timeline-content.test.ts
index 1ccb78c67a..1461d0aeef 100644
--- a/packages/server/src/server/agent/agent-timeline-content.test.ts
+++ b/packages/server/src/server/agent/agent-timeline-content.test.ts
@@ -1,12 +1,30 @@
+import { AgentTimelineItemPayloadSchema } from "@getpaseo/protocol/messages";
 import { describe, expect, test } from "vitest";
 
+import type { AgentTimelineItem } from "./agent-sdk-types.js";
 import { limitAgentTimelineItemContent } from "./agent-timeline-content.js";
 
+function serializedBytes(item: AgentTimelineItem): number {
+  return Buffer.byteLength(JSON.stringify(item), "utf8");
+}
+
 describe("agent timeline content", () => {
+  test("returns an item within budget unchanged", () => {
+    const item: AgentTimelineItem = {
+      type: "tool_call",
+      callId: "small",
+      name: "Bash",
+      status: "completed",
+      error: null,
+      detail: { type: "shell", command: "ls", output: "x".repeat(60 * 1024) },
+    };
+    expect(limitAgentTimelineItemContent(item)).toBe(item);
+  });
+
   test.each([false, true])(
-    "preserves the exact UTF-16 prefix for oversized shell output (failed=%s)",
+    "cuts oversized shell output and keeps short fields whole (failed=%s)",
     (failed) => {
-      const text = "x".repeat(64 * 1024 - 1) + "🙂";
+      const text = "x".repeat(1024 * 1024) + "🙂";
       const item = limitAgentTimelineItemContent({
         type: "tool_call",
         callId: "large-shell",
@@ -15,45 +33,116 @@ describe("agent timeline content", () => {
         detail: { type: "shell", command: "echo large", output: text },
         error: failed ? { content: text } : null,
       });
-      expect(item).toEqual({
-        type: "tool_call",
+      expect(item).toMatchObject({
         callId: "large-shell",
         name: "Bash",
-        status: failed ? "failed" : "completed",
-        detail: { type: "shell", command: "echo large", output: text.slice(0, 64 * 1024) },
-        error: failed ? { content: text.slice(0, 64 * 1024) } : null,
+        detail: { type: "shell", command: "echo large" },
       });
+      if (item.type !== "tool_call" || item.detail.type !== "shell") throw new Error("shape");
+      expect(item.detail.output).toMatch(/^x+…\[truncated \d{3}\.\d KB\]$/);
+      expect(serializedBytes(item)).toBeLessThanOrEqual(64 * 1024);
     },
   );
 
-  test("marks truncated plain-text tool content within the content budget", () => {
-    const oversizedInput = "x".repeat(64 * 1024 + 1);
-
+  test("replaces an oversized data URL in an unknown tool result with a marker", () => {
+    const url = `data:image/jpeg;base64,${"A".repeat(14 * 1024 * 1024)}`;
     const item = limitAgentTimelineItemContent({
       type: "tool_call",
-      callId: "terminal-session-4242",
-      name: "terminal",
+      callId: "screenshot",
+      name: "node_repl.js",
       status: "completed",
       error: null,
       detail: {
-        type: "plain_text",
-        text: oversizedInput,
-        icon: "square_terminal",
+        type: "unknown",
+        input: { index: 1 },
+        output: { content: [{ type: "image", url }], note: "captured" },
       },
     });
-
-    expect(limitAgentTimelineItemContent(item)).toEqual(item);
     expect(item).toEqual({
       type: "tool_call",
-      callId: "terminal-session-4242",
-      name: "terminal",
+      callId: "screenshot",
+      name: "node_repl.js",
       status: "completed",
       error: null,
       detail: {
-        type: "plain_text",
-        text: "x".repeat(64 * 1024 - "\n\n[Content truncated]".length) + "\n\n[Content truncated]",
-        icon: "square_terminal",
+        type: "unknown",
+        input: { index: 1 },
+        output: { content: [{ type: "image", url: "…[truncated 14.0 MB]" }], note: "captured" },
       },
     });
   });
+
+  test("gives non-tool items a 256 KiB budget", () => {
+    const text = "a".repeat(10 * 1024 * 1024);
+    const item = limitAgentTimelineItemContent({ type: "assistant_message", text });
+    if (item.type !== "assistant_message") throw new Error("shape");
+    expect(item.text).toMatch(/^a+…\[truncated 9\.\d MB\]$/);
+    expect(item.text.length).toBeGreaterThan(200 * 1024);
+    expect(serializedBytes(item)).toBeLessThanOrEqual(256 * 1024);
+  });
+
+  test("bounds an item whose structure alone exceeds the budget", () => {
+    const item = limitAgentTimelineItemContent({
+      type: "tool_call",
+      callId: "many",
+      name: "query",
+      status: "completed",
+      error: null,
+      detail: { type: "unknown", input: null, output: Array.from({ length: 1_000_000 }, () => 1) },
+    });
+    if (item.type !== "tool_call" || item.detail.type !== "unknown") throw new Error("shape");
+    const output = item.detail.output as unknown[];
+    expect(output.length).toBeLessThan(1_000_000);
+    expect(output.every((value) => value === 1)).toBe(true);
+    expect(serializedBytes(item)).toBeLessThanOrEqual(64 * 1024);
+  });
+
+  test("keeps short strings whole and limits idempotently when an item has many strings", () => {
+    const callId = "3f2b8c1e-9a4d-4e6f-8b2a-1c3d5e7f9a0b";
+    const item = limitAgentTimelineItemContent({
+      type: "tool_call",
+      callId,
+      name: "mcp__search__files",
+      status: "completed",
+      error: null,
+      detail: {
+        type: "unknown",
+        input: { query: "useWorkspaceSomethingVeryDescriptive" },
+        output: Array.from(
+          { length: 10_000 },
+          (_, index) => `${String(index).padStart(5, "0")}${"p".repeat(28)}`,
+        ),
+      },
+    });
+    if (item.type !== "tool_call" || item.detail.type !== "unknown") throw new Error("shape");
+    expect(item.callId).toBe(callId);
+    expect(item.detail.input).toEqual({ query: "useWorkspaceSomethingVeryDescriptive" });
+    const output = item.detail.output as string[];
+    expect(output.length).toBeLessThan(10_000);
+    expect(output.every((path) => path.length === 33)).toBe(true);
+    expect(serializedBytes(item)).toBeLessThanOrEqual(64 * 1024);
+    expect(limitAgentTimelineItemContent(item)).toBe(item);
+  });
+
+  test("keeps a long typed array valid against the wire schema", () => {
+    const item = limitAgentTimelineItemContent({
+      type: "todo",
+      items: Array.from({ length: 20_000 }, (_, index) => ({
+        text: `Task ${index}`,
+        completed: false,
+      })),
+    });
+    if (item.type !== "todo") throw new Error("shape");
+    expect(item.items.length).toBeLessThan(20_000);
+    expect(AgentTimelineItemPayloadSchema.safeParse(item).success).toBe(true);
+    expect(serializedBytes(item)).toBeLessThanOrEqual(256 * 1024);
+  });
+
+  test("is stable on an already-limited item", () => {
+    const item = limitAgentTimelineItemContent({
+      type: "reasoning",
+      text: "r".repeat(1024 * 1024),
+    });
+    expect(limitAgentTimelineItemContent(item)).toBe(item);
+  });
 });
diff --git a/packages/server/src/server/agent/agent-timeline-content.ts b/packages/server/src/server/agent/agent-timeline-content.ts
index 003239b283..5117073e14 100644
--- a/packages/server/src/server/agent/agent-timeline-content.ts
+++ b/packages/server/src/server/agent/agent-timeline-content.ts
@@ -1,9 +1,19 @@
 import type { AgentTimelineItem } from "./agent-sdk-types.js";
 import type { JsonValue } from "@getpaseo/protocol/agent-types";
 
-const TOOL_CALL_CONTENT_MAX_LENGTH = 64 * 1024;
 export const PLUGIN_TIMELINE_DATA_MAX_BYTES = 64 * 1024;
 
+// One timeline fetch sends its entries in one WebSocket message, so every item must stay small.
+// Budgets count UTF-16 units plus a fixed cost per node; neither is exact JSON bytes. They bound
+// long strings and long arrays, not wide objects (every entry is kept) or multi-byte text.
+const TOOL_CALL_BUDGET = 64 * 1024;
+const ITEM_BUDGET = 256 * 1024;
+const NODE_COST = 8;
+const MARKER_COST = 32;
+// Ids, names, paths and queries stay whole, so an item keeps its identity across passes.
+const SHORT_STRING = 1024;
+const MAX_DEPTH = 64;
+
 export function assertPluginTimelineDataSize(data: JsonValue): void {
   const serializedBytes = Buffer.byteLength(JSON.stringify(data), "utf8");
   if (serializedBytes > PLUGIN_TIMELINE_DATA_MAX_BYTES) {
@@ -17,66 +27,119 @@ function retainTextPrefix(text: string, length: number): string {
   return Buffer.from(text.slice(0, length), "utf16le").toString("utf16le");
 }
 
-function limitFailedShellError(item: AgentTimelineItem): AgentTimelineItem {
-  if (
-    item.type !== "tool_call" ||
-    item.detail.type !== "shell" ||
-    item.status !== "failed" ||
-    typeof item.error !== "object" ||
-    item.error === null ||
-    !("content" in item.error) ||
-    typeof item.error.content !== "string" ||
-    item.error.content.length <= TOOL_CALL_CONTENT_MAX_LENGTH
-  ) {
-    return item;
-  }
-  return {
-    ...item,
-    error: {
-      ...item.error,
-      content: retainTextPrefix(item.error.content, TOOL_CALL_CONTENT_MAX_LENGTH),
-    },
-  };
+function formatSize(units: number): string {
+  if (units < 1024) return `${units} B`;
+  if (units < 1024 * 1024) return `${(units / 1024).toFixed(1)} KB`;
+  return `${(units / (1024 * 1024)).toFixed(1)} MB`;
 }
 
-function limitPlainText(item: AgentTimelineItem): AgentTimelineItem {
-  if (
-    item.type !== "tool_call" ||
-    item.detail.type !== "plain_text" ||
-    typeof item.detail.text !== "string" ||
-    item.detail.text.length <= TOOL_CALL_CONTENT_MAX_LENGTH
-  ) {
-    return item;
-  }
-  const notice = "\n\n[Content truncated]";
-  return {
-    ...item,
-    detail: {
-      ...item.detail,
-      text:
-        retainTextPrefix(item.detail.text, TOOL_CALL_CONTENT_MAX_LENGTH - notice.length) + notice,
-    },
-  };
+function truncatedMarker(units: number): string {
+  return `…[truncated ${formatSize(units)}]`;
 }
 
+interface ItemSize {
+  nodeCost: number;
+  stringLengths: number[];
+  tooDeep: boolean;
+}
+
+function measure(value: unknown, depth: number, size: ItemSize): void {
+  size.nodeCost += NODE_COST;
+  if (depth > MAX_DEPTH) {
+    size.tooDeep = true;
+  } else if (typeof value === "string") {
+    size.stringLengths.push(value.length);
+  } else if (Array.isArray(value)) {
+    for (const element of value) measure(element, depth + 1, size);
+  } else if (typeof value === "object" && value !== null) {
+    for (const [key, child] of Object.entries(value)) {
+      size.nodeCost += key.length;
+      measure(child, depth + 1, size);
+    }
+  }
+}
+
+/** The largest per-string length that keeps all strings, once cut, within `available`. */
+function findStringCap(lengths: readonly number[], available: number): number {
+  let low = 0;
+  let high = 0;
+  for (const length of lengths) high = Math.max(high, length);
+  while (low < high) {
+    const cap = Math.ceil((low + high) / 2);
+    let total = 0;
+    for (const length of lengths) total += Math.min(length, cap);
+    if (total <= available) low = cap;
+    else high = cap - 1;
+  }
+  return low;
+}
+
+interface CutState {
+  stringCap: number;
+  remaining: number;
+}
+
+function cutString(text: string, cap: number): string {
+  if (text.length <= cap) return text;
+  // A partial data URL is useless to every reader, so drop it whole.
+  if (text.startsWith("data:")) return truncatedMarker(text.length);
+  return retainTextPrefix(text, cap) + truncatedMarker(text.length - cap);
+}
+
+function cut(value: unknown, depth: number, state: CutState): unknown {
+  state.remaining -= NODE_COST;
+  if (depth > MAX_DEPTH) return "…[truncated]";
+  if (typeof value === "string") {
+    const text = cutString(value, state.stringCap);
+    state.remaining -= text.length;
+    return text;
+  }
+  if (Array.isArray(value)) {
+    let changed = false;
+    const output: unknown[] = [];
+    for (const element of value) {
+      const remainingBefore = state.remaining;
+      const next = cut(element, depth + 1, state);
+      if (state.remaining < 0) {
+        // Drop this and later elements. A marker element would break typed arrays.
+        state.remaining = remainingBefore;
+        changed = true;
+        break;
+      }
+      changed ||= next !== element;
+      output.push(next);
+    }
+    return changed ? output : value;
+  }
+  if (typeof value === "object" && value !== null) {
+    let changed = false;
+    const output: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(value)) {
+      state.remaining -= key.length;
+      const next = cut(child, depth + 1, state);
+      changed ||= next !== child;
+      output[key] = next;
+    }
+    return changed ? output : value;
+  }
+  return value;
+}
+
+/** Returns the item itself when it fits its budget; otherwise a copy with its largest strings cut. */
 export function limitAgentTimelineItemContent(item: AgentTimelineItem): AgentTimelineItem {
-  item = limitFailedShellError(item);
-  item = limitPlainText(item);
-  if (
-    item.type !== "tool_call" ||
-    item.detail.type !== "shell" ||
-    typeof item.detail.output !== "string"
-  ) {
-    return item;
-  }
-  if (item.detail.output.length <= TOOL_CALL_CONTENT_MAX_LENGTH) {
-    return item;
-  }
-  return {
-    ...item,
-    detail: {
-      ...item.detail,
-      output: retainTextPrefix(item.detail.output, TOOL_CALL_CONTENT_MAX_LENGTH),
-    },
-  };
+  const budget = item.type === "tool_call" ? TOOL_CALL_BUDGET : ITEM_BUDGET;
+  const size: ItemSize = { nodeCost: 0, stringLengths: [], tooDeep: false };
+  measure(item, 0, size);
+  let stringTotal = 0;
+  for (const length of size.stringLengths) stringTotal += length;
+  if (!size.tooDeep && size.nodeCost + stringTotal <= budget) return item;
+
+  // Strings get what structure leaves, but at least half the budget, less a margin for JSON
+  // escaping. Arrays drop the elements that do not fit, which bounds items whose short strings
+  // or structure alone are too big.
+  const markerCost =
+    MARKER_COST * size.stringLengths.filter((length) => length > SHORT_STRING).length;
+  const available = (budget * 15) / 16 - Math.min(size.nodeCost, budget / 2) - markerCost;
+  const stringCap = Math.max(SHORT_STRING, findStringCap(size.stringLengths, available));
+  return cut(item, 0, { stringCap, remaining: budget }) as AgentTimelineItem;
 }
diff --git a/packages/server/src/server/agent/agent-timeline-store-types.ts b/packages/server/src/server/agent/agent-timeline-store-types.ts
index 639b24a904..9ca1ab37b9 100644
--- a/packages/server/src/server/agent/agent-timeline-store-types.ts
+++ b/packages/server/src/server/agent/agent-timeline-store-types.ts
@@ -17,6 +17,7 @@ export interface AgentTimelineCursor {
 export type AgentTimelineFetchDirection = "tail" | "before" | "after";
 
 export interface AgentTimelineFetchOptions {
+  wholeTurns?: boolean;
   direction?: AgentTimelineFetchDirection;
   cursor?: AgentTimelineCursor;
   /**
diff --git a/packages/server/src/server/agent/agent-timeline-store.test.ts b/packages/server/src/server/agent/agent-timeline-store.test.ts
index 895aec2684..9ec4df4d55 100644
--- a/packages/server/src/server/agent/agent-timeline-store.test.ts
+++ b/packages/server/src/server/agent/agent-timeline-store.test.ts
@@ -1,7 +1,45 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
+import { selectReferenceProjectedTimelinePage } from "./test-utils/timeline-page-reference.js";
+import type { AgentTimelineItem } from "./agent-sdk-types.js";
 import { InMemoryAgentTimelineStore } from "./agent-timeline-store.js";
 
 describe("InMemoryAgentTimelineStore", () => {
+  it("resets stale forward cursors to complete available turns", () => {
+    const store = new InMemoryAgentTimelineStore();
+    store.initialize("agent", { epoch: "current" });
+    for (let index = 0; index < 60; index++)
+      store.append(
+        "agent",
+        {
+          type: "tool_call",
+          callId: `call-${index}`,
+          name: "shell",
+          status: "completed",
+          error: null,
+          detail: { type: "unknown", input: null, output: null },
+        },
+        { turnId: "run" },
+      );
+    const page = store.fetch("agent", {
+      direction: "after",
+      cursor: { epoch: "old", seq: 10 },
+      limit: 40,
+      wholeTurns: true,
+    });
+    expect(page.rows).toHaveLength(60);
+    expect(page).toMatchObject({
+      reset: true,
+      staleCursor: true,
+      startSeq: 1,
+      endSeq: 60,
+      hasOlder: false,
+      hasNewer: false,
+    });
+  });
+
   it("clamps an overshooting before cursor into the bounded tail window", () => {
     const store = new InMemoryAgentTimelineStore();
     store.initialize("agent-1", {
@@ -143,6 +181,20 @@ describe("projected timeline retention", () => {
       },
     ]);
   });
+
+  it("serves a merged assistant message within the item budget", () => {
+    const store = new InMemoryAgentTimelineStore();
+    store.initialize("agent", { epoch: "e" });
+    const chunk = "a".repeat(200 * 1024);
+    for (let index = 0; index < 10; index++) {
+      store.append("agent", { type: "assistant_message", messageId: "m", text: chunk });
+    }
+    const [row] = store.fetch("agent", { limit: 1 }).rows;
+    expect(row).toMatchObject({ seqStart: 1, seqEnd: 10 });
+    expect(row.item).toMatchObject({ type: "assistant_message", messageId: "m" });
+    expect(Buffer.byteLength(JSON.stringify(row.item))).toBeLessThanOrEqual(256 * 1024);
+    expect(store.getLastAssistantMessage("agent")).toHaveLength(10 * chunk.length);
+  });
 });
 
 describe("projected sequence ownership", () => {
@@ -177,7 +229,10 @@ describe("projected sequence ownership", () => {
     store.append("a", { type: "assistant_message", text: "Answer" });
     store.append("a", { ...tool, status: "completed" });
     store.initialize("b", { rows: store.getRows("a") });
+    expect(store.getLastItem("b")).toMatchObject({ type: "tool_call", status: "completed" });
+    expect(store.getLastAssistantMessage("b")).toBe("Answer");
     expect(store.append("b", { type: "user_message", text: "next" }).seq).toBe(4);
+    expect(store.getLastItem("b")).toEqual({ type: "user_message", text: "next" });
     expect(store.fetch("b").rows.map((row) => row.seqStart)).toEqual([1, 2, 4]);
   });
   it("returns the last projected assistant message without joining different messages", () => {
@@ -211,3 +266,178 @@ it("includes transitive tool updates in a contiguous projected tail", () => {
   expect(tail.rows.map((row) => row.seqStart)).toEqual([1, 2, 3, 5]);
   expect(tail).toMatchObject({ startSeq: 1, endSeq: 6, hasOlder: false });
 });
+
+async function measureTimelineTail(wholeTurns: boolean) {
+  const fixture = fileURLToPath(
+    new URL("./test-utils/timeline-responsiveness.ts", import.meta.url),
+  );
+  const { stdout, stderr } = await promisify(execFile)(
+    process.execPath,
+    ["--expose-gc", "--import", "tsx", fixture, String(wholeTurns)],
+    { timeout: 15_000 },
+  );
+  process.stderr.write(stderr);
+  return JSON.parse(stdout) as {
+    result: ReturnType<InMemoryAgentTimelineStore["fetch"]>;
+    blockingMs: number;
+  };
+}
+
+it("excludes unrelated test-runner CPU from the timeline fetch budget", async () => {
+  let unrelatedWork: ReturnType<typeof setImmediate>;
+  const burnCpu = () => {
+    const threadCpuUsage: (previous?: NodeJS.CpuUsage) => NodeJS.CpuUsage = Reflect.get(
+      process,
+      "threadCpuUsage",
+    );
+    const start = threadCpuUsage();
+    let elapsed: NodeJS.CpuUsage;
+    do {
+      elapsed = threadCpuUsage(start);
+    } while (elapsed.user + elapsed.system < 80_000);
+    unrelatedWork = setImmediate(burnCpu);
+  };
+  unrelatedWork = setImmediate(burnCpu);
+  try {
+    const { result: tail, blockingMs } = await measureTimelineTail(false);
+    expect(tail.rows).toHaveLength(200);
+    expect(tail.startSeq).toBe(99_801);
+    expect(tail.endSeq).toBe(100_000);
+    expect(blockingMs).toBeLessThan(50);
+  } finally {
+    clearImmediate(unrelatedWork);
+  }
+});
+
+it.each([false, true])(
+  "serves tail 200 from 100,000 retained rows without stalling the loop (wholeTurns=%s)",
+  async (wholeTurns) => {
+    const { result: tail, blockingMs } = await measureTimelineTail(wholeTurns);
+    expect(tail.rows).toHaveLength(200);
+    expect(tail.startSeq).toBe(99_801);
+    expect(tail.endSeq).toBe(100_000);
+    expect(blockingMs).toBeLessThan(50);
+  },
+);
+
+it("matches the previous reprojecting selector on seeded randomized timelines", () => {
+  let seed = 0x76aabbcc;
+  const random = (bound: number) => {
+    seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0;
+    return Math.floor((seed / 0x1_0000_0000) * bound);
+  };
+  for (let scenario = 0; scenario < 100; scenario++) {
+    const store = new InMemoryAgentTimelineStore();
+    store.initialize("a", { epoch: "e" });
+    for (let seq = 1; seq <= 100; seq++) {
+      const identity = String(random(8));
+      const text = String(seq);
+      const items: AgentTimelineItem[] = [
+        { type: "user_message", text },
+        { type: "assistant_message", text },
+        { type: "assistant_message", text, messageId: identity },
+        { type: "reasoning", text },
+        {
+          type: "tool_call",
+          callId: identity,
+          name: "shell",
+          status: "running",
+          error: null,
+          detail: { type: "plain_text", label: text },
+        },
+        {
+          type: "plugin",
+          id: identity,
+          pluginId: "test",
+          kind: "state",
+          version: 1,
+          data: { text },
+        },
+      ];
+      store.append("a", items[random(items.length)], { turnId: String(random(3)) });
+    }
+    // Include rehydration of already-projected rows, with non-monotonic seqEnd.
+    store.initialize("b", { rows: store.getRows("a"), epoch: "e" });
+    for (const agentId of ["a", "b"]) {
+      assertSelectionMatchesReference(store, agentId);
+      store.append(agentId, { type: "assistant_message", text: "later" });
+      assertSelectionMatchesReference(store, agentId);
+    }
+  }
+});
+
+function assertSelectionMatchesReference(store: InMemoryAgentTimelineStore, agentId: string): void {
+  for (const direction of ["tail", "before", "after"] as const) {
+    for (const limit of [0, 1, 7, 200]) {
+      for (const cursorSeq of [0, 1, 25, 50, 99, 100, 150]) {
+        const actual = store.fetch(agentId, {
+          direction,
+          limit,
+          cursor: { epoch: "e", seq: cursorSeq },
+        });
+        const expected = selectReferenceProjectedTimelinePage({
+          rows: store.getRows(agentId),
+          bounds: actual.window,
+          direction,
+          limit,
+          cursorSeq,
+        });
+        expect({
+          ...expected,
+          entries: undefined,
+          rows: expected.entries.map((entry) => Object.assign({ seq: entry.seqEnd }, entry)),
+        }).toEqual({
+          entries: undefined,
+          rows: actual.rows,
+          startSeq: actual.startSeq,
+          endSeq: actual.endSeq,
+          hasOlder: actual.hasOlder,
+          hasNewer: actual.hasNewer,
+        });
+      }
+    }
+  }
+}
+
+it("continues a scroll across appends and lifecycle collapse without losing source coverage", () => {
+  const store = new InMemoryAgentTimelineStore();
+  store.initialize("a", { epoch: "e" });
+  const tool: AgentTimelineItem = {
+    type: "tool_call",
+    callId: "t",
+    name: "shell",
+    status: "running",
+    error: null,
+    detail: { type: "plain_text", label: "work" },
+  };
+  store.append("a", tool);
+  for (let seq = 2; seq <= 5; seq++) store.append("a", { type: "user_message", text: String(seq) });
+  const first = store.fetch("a", { direction: "after", cursor: { epoch: "e", seq: 0 }, limit: 2 });
+  expect(first.endSeq).toBe(2);
+  store.append("a", { ...tool, status: "completed" });
+  store.append("a", { type: "assistant_message", text: "Done" });
+  expect(first.rows[0].item).toMatchObject({ status: "running" });
+  const second = store.fetch("a", {
+    direction: "after",
+    cursor: { epoch: "e", seq: first.endSeq! },
+    limit: 2,
+  });
+  expect(second.rows.map((row) => row.seqStart)).toEqual([3, 4]);
+  expect(second.endSeq).toBe(4);
+  const third = store.fetch("a", {
+    direction: "after",
+    cursor: { epoch: "e", seq: second.endSeq! },
+    limit: 2,
+  });
+  expect(third.rows.map((row) => row.seqStart)).toEqual([1, 5]);
+  expect(third.rows[0].item).toMatchObject({ status: "completed" });
+  expect(third.endSeq).toBe(6);
+  const last = store.fetch("a", {
+    direction: "after",
+    cursor: { epoch: "e", seq: third.endSeq! },
+    limit: 2,
+  });
+  expect(last.rows.map((row) => row.item)).toEqual([{ type: "assistant_message", text: "Done" }]);
+  expect(last.endSeq).toBe(7);
+  expect(last.hasNewer).toBe(false);
+});
diff --git a/packages/server/src/server/agent/agent-timeline-store.ts b/packages/server/src/server/agent/agent-timeline-store.ts
index 6a37e11ef0..4c3b9c5c3a 100644
--- a/packages/server/src/server/agent/agent-timeline-store.ts
+++ b/packages/server/src/server/agent/agent-timeline-store.ts
@@ -1,9 +1,6 @@
 import { randomUUID } from "node:crypto";
-import {
-  TimelineProjection,
-  selectProjectedTimelinePage,
-  type ProjectedTimelineRow,
-} from "./timeline-projection.js";
+import { TimelineProjection, type ProjectedTimelineRow } from "./timeline-projection.js";
+import { limitAgentTimelineItemContent } from "./agent-timeline-content.js";
 import type { AgentTimelineItem } from "./agent-sdk-types.js";
 import type {
   AgentTimelineFetchOptions,
@@ -43,8 +40,7 @@ export class InMemoryAgentTimelineStore {
       ? options.rows.map(cloneRow)
       : this.buildRowsFromItems(options?.items ?? [], options?.nextSeq ?? 1, timestamp);
     const nextSeq = rows.reduce((next, row) => Math.max(next, row.seq + 1), options?.nextSeq ?? 1);
-    const projection = new TimelineProjection();
-    for (const row of rows) projection.append(row);
+    const projection = new TimelineProjection(rows);
     this.states.set(agentId, {
       epoch: options?.epoch ?? randomUUID(),
       projection,
@@ -97,22 +93,22 @@ export class InMemoryAgentTimelineStore {
     const state = this.requireState(agentId);
     const direction = options?.direction ?? "tail";
     const cursor = options?.cursor;
-    const rows = state.projection.getRows();
+    const hasRows = state.minSeq !== 0;
     const window = { minSeq: state.minSeq, maxSeq: state.nextSeq - 1, nextSeq: state.nextSeq };
     const staleCursor = cursor !== undefined && cursor.epoch !== state.epoch;
     const gap =
       !staleCursor &&
       direction === "after" &&
       cursor !== undefined &&
-      rows.length > 0 &&
+      hasRows &&
       cursor.seq < state.minSeq - 1;
     const reset = staleCursor || gap;
-    const page = selectProjectedTimelinePage({
-      rows,
+    const page = state.projection.selectPage({
       bounds: window,
       direction: reset ? "tail" : direction,
       cursorSeq: cursor?.seq,
       limit: options?.limit ?? DEFAULT_TIMELINE_FETCH_LIMIT,
+      wholeTurns: options?.wholeTurns,
     });
     return {
       epoch: state.epoch,
@@ -125,7 +121,12 @@ export class InMemoryAgentTimelineStore {
       hasNewer: page.hasNewer,
       startSeq: page.startSeq,
       endSeq: page.endSeq,
-      rows: page.entries.map((entry) => Object.assign({ seq: entry.seqEnd }, entry)),
+      // Stored rows are already within budget; this bounds assistant and reasoning merges.
+      rows: page.entries.map((entry) =>
+        Object.assign({ seq: entry.seqEnd }, entry, {
+          item: limitAgentTimelineItemContent(entry.item),
+        }),
+      ),
     };
   }
 
@@ -150,14 +151,11 @@ export class InMemoryAgentTimelineStore {
 
   getLastItem(agentId: string): AgentTimelineItem | null {
     const state = this.requireState(agentId);
-    return state.projection.getRows().find((row) => row.seqEnd === state.nextSeq - 1)?.item ?? null;
+    return state.projection.getLastItem(state.nextSeq - 1);
   }
 
   getLastAssistantMessage(agentId: string): string | null {
-    const row = this.requireState(agentId)
-      .projection.getRows()
-      .findLast((candidate) => candidate.item.type === "assistant_message");
-    return row?.item.type === "assistant_message" ? row.item.text : null;
+    return this.requireState(agentId).projection.getLastAssistantMessage();
   }
 
   private requireState(agentId: string): AgentTimelineState {
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..048da2814d 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)}`,
   );
 }
 
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 5d2c9fddc1..daa5ba9ec1 100644
--- a/packages/server/src/server/agent/create-agent/create.test.ts
+++ b/packages/server/src/server/agent/create-agent/create.test.ts
@@ -69,6 +69,7 @@ test("session create forwards clientMessageId to the initial prompt run options"
       getAgent: vi.fn(() => snapshot),
       tryRunOutOfBand: vi.fn(() => false),
       hasInFlightRun: vi.fn(() => false),
+      reloadStalePluginSession: async () => {},
       streamAgent,
       waitForAgentRunStart: vi.fn(async () => undefined),
     } as unknown as Parameters<typeof createAgentCommand>[0]["agentManager"],
diff --git a/packages/server/src/server/agent/create-agent/create.ts b/packages/server/src/server/agent/create-agent/create.ts
index 77cdde673b..a46fcb4312 100644
--- a/packages/server/src/server/agent/create-agent/create.ts
+++ b/packages/server/src/server/agent/create-agent/create.ts
@@ -21,7 +21,17 @@ 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";
+
+/** How a workspace this creation makes inherits its creator's visibility. */
+interface McpWorkspaceIntent {
+  background?: boolean;
+  callerWorkspaceId?: string;
+}
 
 export interface CreateAgentCommandDependencies {
   finishSubscriptions?: FinishSubscriptions;
@@ -40,7 +50,7 @@ export interface CreateAgentCommandDependencies {
 export type EnsureWorkspaceForCreate = (
   cwd: string,
   firstAgentContext?: FirstAgentContext,
-  context?: { callerWorkspaceId?: string },
+  context?: { background?: boolean; callerWorkspaceId?: string },
 ) => Promise<string>;
 
 export interface CreateAgentFromSessionInput {
@@ -49,6 +59,7 @@ export interface CreateAgentFromSessionInput {
   agentId?: string;
   config: AgentSessionConfig;
   workspaceId: string;
+  background: boolean;
   initialPrompt?: string;
   source?: AgentPromptSource;
   clientMessageId?: string;
@@ -77,6 +88,8 @@ export interface CreateAgentFromMcpInput {
   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>;
@@ -255,6 +268,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 +291,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 +318,7 @@ async function resolveMcpCreateAgent(
           dependencies,
           resolvedCwd,
           input.initialPrompt ?? "",
-          parentAgent?.workspaceId,
+          workspaceIntent,
         ),
       ),
       cwd: resolvedCwd,
@@ -329,6 +347,7 @@ async function resolveMcpCreateAgent(
       ...(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,
@@ -410,16 +429,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 +527,7 @@ async function resolveMcpCwd(params: {
   dependencies: CreateAgentCommandDependencies;
   cwd: string;
   initialPrompt: string;
-  callerWorkspaceId?: string;
+  workspaceIntent: McpWorkspaceIntent;
   worktree: CreateAgentFromMcpInput["worktree"];
 }): Promise<{
   resolvedCwd: string;
@@ -542,7 +557,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..e5767de4f7
--- /dev/null
+++ b/packages/server/src/server/agent/directory.test.ts
@@ -0,0 +1,139 @@
+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"]),
+    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/internal/observation.ts b/packages/server/src/server/agent/finish-subscriptions/internal/observation.ts
index 887a4ba075..7abe483cf4 100644
--- a/packages/server/src/server/agent/finish-subscriptions/internal/observation.ts
+++ b/packages/server/src/server/agent/finish-subscriptions/internal/observation.ts
@@ -13,6 +13,8 @@ import type { FinishObservation } from "../index.js";
 export function createFinishObservation(input: {
   agentManager: AgentManager;
   agentStorage: AgentStorage;
+  /** A child chosen for restart recovery reports its state only after its resume was sent. */
+  waitForResume(agentId: string, signal: AbortSignal): Promise<void>;
   messages(): AgentMessageDelivery;
   hosts(): ToolHosts;
   serverId: string;
@@ -24,6 +26,7 @@ export function createFinishObservation(input: {
     hosts: input.hosts,
     local: {
       async wait(agentId, signal) {
+        await input.waitForResume(agentId, signal);
         await input.messages().waitForDispatch(agentId, signal);
         signal.throwIfAborted();
         const live = agentManager.getAgent(agentId);
@@ -52,6 +55,7 @@ export function createFinishObservation(input: {
         };
       },
       async observe(agentId, handler, signal, onError) {
+        await input.waitForResume(agentId, signal);
         const stored = await agentStorage.get(agentId);
         let updates = Promise.resolve();
         const publish = (snapshot: AgentSnapshotPayload | null, event?: AgentStreamEvent) => {
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 9190e6942b..d2d97b12b6 100644
--- a/packages/server/src/server/agent/import-sessions.test.ts
+++ b/packages/server/src/server/agent/import-sessions.test.ts
@@ -221,7 +221,7 @@ test("listImportableProviderSessions filters, sorts, limits, and projects import
     listImportableSessions,
   } satisfies Pick<AgentManager, "listAgents" | "listImportableSessions">;
   const agentStorage = {
-    list: async () => [
+    listAll: async () => [
       {
         provider: "codex",
         persistence: {
@@ -231,7 +231,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({
@@ -303,7 +303,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" },
@@ -360,7 +360,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 },
   });
 
@@ -397,7 +397,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",
@@ -441,7 +441,7 @@ test("listImportableProviderSessions includes an archived provider session still
       listImportableSessions: async () => makeImportableSessionsResult([archivedSession]),
     },
     agentStorage: {
-      list: async () => [
+      listAll: async () => [
         {
           id: agentId,
           provider: "claude",
@@ -489,8 +489,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" },
   });
 
@@ -525,8 +525,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" },
   });
 
@@ -542,8 +542,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(
diff --git a/packages/server/src/server/agent/import-sessions.ts b/packages/server/src/server/agent/import-sessions.ts
index 492667ab88..dec3c88188 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 efb14e6d31..d4b1b76af1 100644
--- a/packages/server/src/server/agent/mcp-parity.e2e.test.ts
+++ b/packages/server/src/server/agent/mcp-parity.e2e.test.ts
@@ -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 b8a0d820ec..6c463da2c1 100644
--- a/packages/server/src/server/agent/mcp-server.test.ts
+++ b/packages/server/src/server/agent/mcp-server.test.ts
@@ -76,7 +76,7 @@ import type { GeneratedWorkspaceName } from "../worktree-branch-name-generator.j
 import type { ForgeService } from "../../services/forge-service.js";
 import { areEquivalentPaths } from "../../utils/path.js";
 import { createTerminalManager, type TerminalManager } from "../../terminal/terminal-manager.js";
-import { createWorkerTerminalManager } from "../../terminal/worker-terminal-manager.js";
+import { startWorkerTerminalManager } from "../../terminal/worker-terminal-manager.js";
 import { PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
 import { PASEO_TOOL_NAMES } from "@getpaseo/protocol/paseo-tool-presentation/index";
 import { MutableDaemonConfigSchema, type AgentProfile } from "@getpaseo/protocol/messages";
@@ -270,6 +270,8 @@ function buildAgentManagerSpies() {
     hydrateTimelineFromProvider: vi.fn().mockResolvedValue(undefined),
     appendTimelineItem: vi.fn().mockResolvedValue(undefined),
     emitLiveTimelineItem: vi.fn().mockResolvedValue(undefined),
+    getPluginTools: () => [],
+    reloadStalePluginSession: async () => {},
     hasInFlightRun: vi.fn().mockReturnValue(false),
     steerOrReplaceActiveTurn: async () => ({ status: "inactive" as const }),
     tryRunOutOfBand: vi.fn().mockReturnValue(false),
@@ -290,7 +292,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(),
   };
 }
@@ -617,6 +621,10 @@ class FakeBrowserToolsBroker {
 }
 
 class BoundaryAgentManagerFake {
+  public getPluginTools(): [] {
+    return [];
+  }
+
   private readonly agent = createManagedAgent({
     id: "agent-1",
     cwd: REPO_CWD,
@@ -633,7 +641,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 [];
   }
 }
@@ -766,7 +783,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;
@@ -875,6 +893,7 @@ async function createAgentMcpServer(
     logger: options.logger,
     ...createFinishObservation({
       ...options,
+      waitForResume: async () => {},
       messages: () => messages,
       serverId: options.serverId ?? "self",
       hosts: () => {
@@ -887,7 +906,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);
@@ -1378,13 +1401,24 @@ describe("terminal MCP tools", () => {
   );
 
   it.each([
-    ["in-process", createTerminalManager],
-    ["worker", createWorkerTerminalManager],
+    ["in-process", async () => ({ manager: createTerminalManager(), home: null })],
+    [
+      "worker",
+      async () => {
+        const home = await mkdtemp(join(tmpdir(), "mcp-terminal-keys-home-"));
+        const manager = await startWorkerTerminalManager({
+          paseoHome: home,
+          paseoVersion: "0.0.0-test",
+          logger,
+        });
+        return { manager, home };
+      },
+    ],
   ] as const)(
     "delivers MCP key tokens through %s after terminal input modes change",
     async (_name, createManager) => {
       const { agentManager, agentStorage } = createTestDeps();
-      const terminalManager = createManager();
+      const { manager: terminalManager, home } = await createManager();
       const terminal = await terminalManager.createTerminal({
         cwd: process.cwd(),
         workspaceId: "ws-terminal-keys",
@@ -1414,15 +1448,15 @@ describe("terminal MCP tools", () => {
         logger,
       });
 
+      // Every step is a round trip through a real PTY. A loaded Windows runner (ConPTY) has
+      // taken over 3 s to reach READY, so each step gets the same window rather than 1 s.
+      const roundTrip = { timeout: 5000 };
       let output = "";
       const unsubscribe = terminal.subscribe((message) => {
         if (message.type === "output") {
           output += message.data;
         }
       });
-      // Every key travels through the PTY and back; on loaded Windows runners one round
-      // trip can take seconds, so each wait gets the same budget as the first.
-      const roundTrip = { timeout: 5000 };
       try {
         await vi.waitFor(async () => {
           const capture = await terminalManager.captureTerminal(terminal.id);
@@ -1459,6 +1493,7 @@ describe("terminal MCP tools", () => {
         await server.close();
         await terminalManager.killTerminalAndWait(terminal.id);
         terminalManager.killAll();
+        if (home) await rm(home, { recursive: true, force: true });
       }
     },
   );
@@ -1474,7 +1509,6 @@ describe("terminal MCP tools", () => {
         id: "term-1",
         name: "daemon",
         cwd: process.cwd(),
-        getState: vi.fn().mockReturnValue({ scrollback: [], grid: [[]] }),
       }),
       captureTerminal,
     });
@@ -1629,11 +1663,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({
@@ -1651,9 +1685,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);
     }
@@ -1775,7 +1806,7 @@ describe("create_agent MCP tool", () => {
         cwd: existingCwd,
       }),
       undefined,
-      { workspaceId: "wks_existing" },
+      { workspaceId: "wks_existing", background: false },
     );
   });
 
@@ -1819,7 +1850,7 @@ describe("create_agent MCP tool", () => {
         featureValues: { fast_mode: true },
       }),
       undefined,
-      { workspaceId: "workspace-created" },
+      { workspaceId: "workspace-created", background: false },
     );
   });
 
@@ -2015,7 +2046,7 @@ describe("create_agent MCP tool", () => {
         title: "Fix auth bug",
       }),
       undefined,
-      { workspaceId: "workspace-created" },
+      { workspaceId: "workspace-created", background: false },
     );
   });
 
@@ -2050,7 +2081,7 @@ describe("create_agent MCP tool", () => {
         title: "Fix auth",
       }),
       undefined,
-      { workspaceId: "workspace-created" },
+      { workspaceId: "workspace-created", background: false },
     );
   });
 
@@ -2094,6 +2125,7 @@ describe("create_agent MCP tool", () => {
       {
         labels: { source: "mcp" },
         workspaceId: "workspace-created",
+        background: false,
       },
     );
   });
@@ -2196,7 +2228,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",
@@ -2681,7 +2713,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,
@@ -2714,7 +2746,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) => {
@@ -2810,12 +2842,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",
@@ -2835,16 +2868,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",
@@ -3001,6 +3024,7 @@ describe("create_agent MCP tool", () => {
           source: "handoff",
         },
         workspaceId: "wks_parent",
+        background: false,
       },
     );
   });
@@ -3062,6 +3086,7 @@ describe("create_agent MCP tool", () => {
           [PARENT_AGENT_ID_LABEL]: "parent-agent",
         },
         workspaceId: "wks_parent",
+        background: false,
       },
     );
   });
@@ -3200,6 +3225,7 @@ describe("create_agent MCP tool", () => {
     expect(agentIdArg).toBeUndefined();
     expect(optionsArg).toEqual({
       workspaceId: "workspace-created",
+      background: false,
     });
   });
 
@@ -3277,7 +3303,7 @@ describe("create_agent MCP tool", () => {
     expect(spies.agentManager.createAgent).toHaveBeenCalledWith(
       expect.objectContaining({ modeId: "dynamic" }),
       undefined,
-      { workspaceId: "workspace-created" },
+      { workspaceId: "workspace-created", background: false },
     );
   });
 
@@ -3316,7 +3342,7 @@ describe("create_agent MCP tool", () => {
     expect(spies.agentManager.createAgent).toHaveBeenCalledWith(
       expect.objectContaining({ modeId: "build", featureValues: { auto_accept: true } }),
       undefined,
-      { workspaceId: "workspace-created" },
+      { workspaceId: "workspace-created", background: false },
     );
   });
 
@@ -6316,7 +6342,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",
@@ -6375,7 +6401,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({
@@ -6416,7 +6442,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",
@@ -6447,7 +6473,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,
@@ -6566,7 +6592,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/mutable-provider-config-owner.test.ts b/packages/server/src/server/agent/mutable-provider-config-owner.test.ts
index 53270c1a78..0307eabda6 100644
--- a/packages/server/src/server/agent/mutable-provider-config-owner.test.ts
+++ b/packages/server/src/server/agent/mutable-provider-config-owner.test.ts
@@ -99,16 +99,17 @@ afterEach(() => {
 });
 
 describe("mutable provider config owner", () => {
-  test("publishes provider changes after commit and emits nothing on rollback", () => {
+  test("publishes provider changes after commit and emits nothing on rollback", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-provider-config-owner-"));
     tempDirs.push(paseoHome);
     const store = new DaemonConfigStore(paseoHome, mutableConfig({ version: 1 }));
     const manager = new ProviderSnapshotManager({
       logger: createTestLogger(),
-      providerOverrides: { codex: { enabled: true } },
+      providerOverrides: CONTROLLED_PROVIDERS,
+      extraClients: { codex: controlledCodexClient(async () => catalog("initial")) },
     });
     const cwd = path.resolve("/tmp/provider-config-owner");
-    manager.getSnapshot(cwd);
+    await manager.refreshSnapshotForCwd({ cwd });
     const events: string[] = [];
     manager.on("change", ({ current }) => events.push(current.cwd));
     let agentManagerState = manager.getAgentManagerProviderState();
@@ -125,7 +126,7 @@ describe("mutable provider config owner", () => {
     });
 
     try {
-      store.patch({ providers: { codex: { enabled: false } } });
+      await store.patch({ providers: { codex: { enabled: false } } });
       expect(events).toEqual([cwd]);
       expect(agentManagerState.providerDefinitions.codex).toMatchObject({ enabled: false });
 
@@ -133,7 +134,7 @@ describe("mutable provider config owner", () => {
       const unsubscribeFailure = store.onApply(() => {
         throw new Error("later owner failed");
       });
-      expect(() => store.patch({ providers: { codex: { enabled: true } } })).toThrow(
+      await expect(store.patch({ providers: { codex: { enabled: true } } })).rejects.toThrow(
         "later owner failed",
       );
       unsubscribeFailure();
@@ -150,7 +151,7 @@ describe("mutable provider config owner", () => {
     }
   });
 
-  test("does no provider work for unrelated CORS, Git, and app URL reloads", () => {
+  test("does no provider work for unrelated CORS, Git, and app URL reloads", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-provider-config-owner-"));
     tempDirs.push(paseoHome);
     const initial: PersistedConfig = {
@@ -174,9 +175,10 @@ describe("mutable provider config owner", () => {
     });
     const manager = new ProviderSnapshotManager({
       logger: createTestLogger(),
-      providerOverrides: { codex: { enabled: true } },
+      providerOverrides: CONTROLLED_PROVIDERS,
+      extraClients: { codex: controlledCodexClient(async () => catalog("initial")) },
     });
-    manager.getSnapshot("/tmp/provider-config-owner");
+    await manager.refreshSnapshotForCwd({ cwd: "/tmp/provider-config-owner" });
     const events: string[] = [];
     manager.on("change", ({ current }) => events.push(current.cwd));
     let registryUpdates = 0;
@@ -200,7 +202,7 @@ describe("mutable provider config owner", () => {
       };
       writeFileSync(configPath, `${JSON.stringify(reloaded, null, 2)}\n`, "utf-8");
 
-      expect(store.reload().appliedPaths).toEqual([
+      expect((await store.reload()).appliedPaths).toEqual([
         "app.baseUrl",
         "daemon.cors.allowedOrigins",
         "daemon.git.maxProcessConcurrency",
@@ -245,7 +247,7 @@ describe("mutable provider config owner", () => {
       await vi.waitFor(() => expect(catalogResolvers).toHaveLength(1));
       expect(events).toEqual([]);
 
-      store.patch({ providers: { codex: { enabled: true, label: "Reloaded Codex" } } });
+      await store.patch({ providers: { codex: { enabled: true, label: "Reloaded Codex" } } });
       expect(events).toEqual(["loading:none"]);
       await vi.waitFor(() => expect(catalogResolvers).toHaveLength(2));
 
@@ -311,9 +313,9 @@ describe("mutable provider config owner", () => {
       expect(events).toEqual([]);
 
       const before = manager.getSnapshot(cwd);
-      expect(() =>
+      await expect(
         store.patch({ providers: { codex: { enabled: true, label: "Rejected Codex" } } }),
-      ).toThrow("later owner failed");
+      ).rejects.toThrow("later owner failed");
       expect(events).toEqual([]);
       expect(observedDuringApply).toEqual([{ label: "Codex", snapshot: before }]);
       expect(observedDuringApply[0]!.snapshot).toBe(before);
diff --git a/packages/server/src/server/agent/permission-response.test.ts b/packages/server/src/server/agent/permission-response.test.ts
index 5ac7374e88..710599c588 100644
--- a/packages/server/src/server/agent/permission-response.test.ts
+++ b/packages/server/src/server/agent/permission-response.test.ts
@@ -40,6 +40,8 @@ class FakePermissionAgentManager {
     return undefined;
   }
 
+  async reloadStalePluginSession(): Promise<void> {}
+
   hasInFlightRun(): boolean {
     return this.hasRunInFlight;
   }
diff --git a/packages/server/src/server/agent/plugin-provider.test.ts b/packages/server/src/server/agent/plugin-provider.test.ts
index 3131447098..a9cf3b0ed5 100644
--- a/packages/server/src/server/agent/plugin-provider.test.ts
+++ b/packages/server/src/server/agent/plugin-provider.test.ts
@@ -4,6 +4,8 @@ import { join } from "node:path";
 import { AgentStorage } from "./agent-storage.js";
 import { createIdleRuntimeCleanup } from "./idle-runtime-cleanup/index.js";
 import { relative } from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import type {
   ProviderConnection,
   ProviderLaunch,
@@ -25,6 +27,21 @@ import {
   StaleProviderSessionError,
 } from "./stale-provider-session-error.js";
 
+test("long concurrent plugin and child streams retain text-sized history and release it on archive", () => {
+  const fixture = fileURLToPath(new URL("./test-utils/plugin-stream-memory.ts", import.meta.url));
+  const output = execFileSync(
+    process.execPath,
+    ["--expose-gc", "--max-old-space-size=512", "--import", "tsx", fixture],
+    {
+      encoding: "utf8",
+      timeout: 20_000,
+    },
+  );
+  const memory = JSON.parse(output) as { retained: number; closed: number };
+  expect(memory.retained).toBeLessThan(24 * 1024 * 1024);
+  expect(memory.closed).toBeLessThan(6 * 1024 * 1024);
+});
+
 const CAPABILITIES = [
   "prompt.message",
   "session.configure",
@@ -36,6 +53,7 @@ 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>;
 }
@@ -191,6 +209,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 });
@@ -229,6 +248,572 @@ 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: () => 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 = () =>
+    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(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, "user-B", "conversation");
+    const afterRewind = messages();
+    expect(nativeMessages).toEqual(["A"]);
+    await manager.runAgent(agentId, "D", { clientMessageId: "client-D" });
+    const afterReplacement = 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, "user-B", "files");
+    expect(nativeMessages).toEqual(["A", "B", "C"]);
+    expect(messages()).toEqual(["A", "Reply A", "B", "Reply B", "C", "Reply C"]);
+    await manager.runAgent(agentId, "D", { clientMessageId: "client-D" });
+    expect(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("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("retrying a failed plugin rewind replay replaces the manager timeline before prompting", async () => {
+  let failReplay = true;
+  await withRewindAgent(
+    async ({ manager, agentId, messages }) => {
+      await expect(manager.rewind(agentId, "user-B", "conversation")).rejects.toThrow(
+        "replay failed",
+      );
+      await expect(manager.runAgent(agentId, "D")).rejects.toThrow("Retry the rewind or reload");
+      await manager.rewind(agentId, "user-B", "conversation");
+      expect(messages()).toEqual(["A", "Reply A"]);
+      await manager.runAgent(agentId, "D");
+      expect(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, "user-B", "conversation")).rejects.toThrow(
+        "replay failed",
+      );
+      await manager.reloadAgentSession(agentId, undefined, { rehydrateFromDisk: true });
+      await manager.hydrateTimelineFromProvider(agentId, { force: true });
+      expect(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],
@@ -292,6 +877,99 @@ function expectNestedChildren(events: AgentStreamEvent[]) {
 }
 
 describe("PluginAgentClientRegistry", () => {
+  test("history keeps the tool's first position when completion follows later text", async () => {
+    const harness = createProviderHarness();
+    const registry = new PluginAgentClientRegistry(createTestLogger());
+    registry.replace([harness.registration]);
+    const client = registry.clients()[harness.registration.id]!;
+    const session = await client.createSession({ provider: client.provider, cwd: "/tmp" });
+    const opened = harness.inputs.find((input) => input.type === "session.open");
+    if (opened?.type !== "session.open") throw new Error("missing session open");
+    const tool = {
+      type: "tool_call" as const,
+      id: "tool-position",
+      callId: "call-position",
+      name: "read",
+      detail: { type: "unknown" as const, input: null, output: null },
+      error: null,
+    };
+    try {
+      harness.emit({
+        type: "timeline.item",
+        sessionId: opened.sessionId,
+        item: { ...tool, status: "running" },
+      });
+      harness.emit({
+        type: "timeline.item",
+        sessionId: opened.sessionId,
+        item: { type: "assistant_message", id: "later-text", text: "Working" },
+      });
+      harness.emit({
+        type: "timeline.item",
+        sessionId: opened.sessionId,
+        item: { ...tool, status: "completed" },
+      });
+      const items = [];
+      for await (const event of session.streamHistory())
+        if (event.type === "timeline") items.push(event.item);
+      expect(items).toEqual([
+        {
+          type: "tool_call",
+          callId: "call-position",
+          name: "read",
+          detail: tool.detail,
+          error: null,
+          status: "completed",
+        },
+        { type: "assistant_message", messageId: "later-text", text: "Working" },
+      ]);
+    } finally {
+      await session.close();
+      await registry.shutdown();
+    }
+  });
+
+  test("detached text deltas preserve split surrogates and history replays one complete message", async () => {
+    const harness = createProviderHarness();
+    const registry = new PluginAgentClientRegistry(createTestLogger());
+    registry.replace([harness.registration]);
+    const client = registry.clients()[harness.registration.id]!;
+    const session = await client.createSession({ provider: client.provider, cwd: "/tmp" });
+    const opened = harness.inputs.find((input) => input.type === "session.open");
+    if (opened?.type !== "session.open") throw new Error("missing session open");
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+    const prefix = "long prefix ".repeat(10);
+    const first = prefix + "a\uD83D";
+    const complete = first + "\uDE00b";
+    try {
+      for (const text of [first, complete, complete]) {
+        harness.emit({
+          type: "timeline.item",
+          sessionId: opened.sessionId,
+          item: { type: "assistant_message", id: "split-message", text },
+        });
+      }
+      const deltas = events.flatMap((event) =>
+        event.type === "timeline" && event.item.type === "assistant_message"
+          ? [event.item.text]
+          : [],
+      );
+      expect(deltas).toEqual([first, "\uDE00b"]);
+      expect(deltas.join("")).toBe(prefix + "a😀b");
+      const history: AgentStreamEvent[] = [];
+      for await (const event of session.streamHistory()) history.push(event);
+      expect(
+        history.flatMap((event) =>
+          event.type === "timeline" && event.item.type === "assistant_message" ? [event.item] : [],
+        ),
+      ).toEqual([{ type: "assistant_message", messageId: "split-message", text: complete }]);
+    } finally {
+      await session.close();
+      await registry.shutdown();
+    }
+  });
+
   test("stores only agent options while the plugin receives merged defaults", async () => {
     const logger = createTestLogger();
     const harness = createProviderHarness();
@@ -310,7 +988,7 @@ describe("PluginAgentClientRegistry", () => {
     });
     const own = { nested: { replace: "agent" } };
     const agent = await manager.createAgent(
-      { provider: "plugin-direct", cwd: "/tmp", providerOptions: own },
+      { provider: "plugin-direct", cwd: tmpdir(), providerOptions: own },
       undefined,
       { workspaceId: undefined },
     );
@@ -486,6 +1164,137 @@ describe("PluginAgentClientRegistry", () => {
     }
   });
 
+  test.each(["completed", "canceled", "failed"] as const)(
+    "reports a reused plugin child as running until its next turn is %s",
+    async (outcome) => {
+      const logger = createTestLogger();
+      const harness = createProviderHarness();
+      const plugins = new PluginAgentClientRegistry(logger);
+      plugins.replace([harness.registration]);
+      const registry = buildProviderRegistry(logger, { pluginProviders: plugins.definitions() });
+      const manager = new AgentManager({
+        logger,
+        clients: { "plugin-direct": registry["plugin-direct"].createClient(logger) },
+        providerDefinitions: { "plugin-direct": registry["plugin-direct"] },
+      });
+      try {
+        const agent = await manager.createAgent(
+          { provider: "plugin-direct", cwd: tmpdir() },
+          undefined,
+          { workspaceId: undefined },
+        );
+        const open = harness.inputs.find((input) => input.type === "session.open")!;
+        harness.emit({
+          type: "session.opened",
+          sessionId: "reusable-child",
+          parentSessionId: open.sessionId,
+          capabilities: [],
+          restoration: "parent",
+          title: "Plugin child",
+          cwd: tmpdir(),
+        });
+        harness.emit({
+          type: "session.turn",
+          sessionId: "reusable-child",
+          turnId: "first-turn",
+          state: "started",
+        });
+        harness.emit({
+          type: "session.turn",
+          sessionId: "reusable-child",
+          turnId: "first-turn",
+          state: "completed",
+        });
+        await nextTurn();
+        const [child] = manager.listProviderSubagents(agent.id);
+        expect(child).toMatchObject({
+          id: "reusable-child",
+          title: "Plugin child",
+          status: "completed",
+        });
+
+        harness.emit({
+          type: "session.turn",
+          sessionId: "reusable-child",
+          turnId: "second-turn",
+          state: "started",
+        });
+        await nextTurn();
+        expect(manager.listProviderSubagents(agent.id)).toMatchObject([
+          { id: child.id, title: child.title, status: "running" },
+        ]);
+
+        harness.emit({
+          type: "session.turn",
+          sessionId: "reusable-child",
+          turnId: "second-turn",
+          state: outcome,
+        });
+        await nextTurn();
+        expect(manager.listProviderSubagents(agent.id)).toMatchObject([
+          { id: child.id, title: child.title, status: outcome },
+        ]);
+      } finally {
+        await Promise.all(manager.listAgents().map((agent) => manager.closeAgent(agent.id)));
+        await plugins.shutdown();
+      }
+    },
+  );
+
+  test.each(["started", "completed", "canceled", "failed"] as const)(
+    "replays a reused plugin child's latest turn state: %s",
+    async (state) => {
+      const harness = createProviderHarness({
+        openChildren(rootSessionId, emit) {
+          emit({
+            type: "session.opened",
+            sessionId: "reusable-child",
+            parentSessionId: rootSessionId,
+            capabilities: [],
+            restoration: "parent",
+            cwd: "/workspace",
+          });
+          for (const [turnId, turnState] of [
+            ["first-turn", "started"],
+            ["first-turn", "completed"],
+            ["second-turn", "started"],
+          ] as const) {
+            emit({ type: "session.turn", sessionId: "reusable-child", turnId, state: turnState });
+          }
+          if (state !== "started") {
+            emit({
+              type: "session.turn",
+              sessionId: "reusable-child",
+              turnId: "second-turn",
+              state,
+            });
+          }
+        },
+      });
+      const registry = new PluginAgentClientRegistry(createTestLogger());
+      registry.replace([harness.registration]);
+      try {
+        const session = await registry.clients()[harness.registration.id]!.createSession({
+          provider: harness.registration.id,
+          cwd: "/workspace",
+        });
+        const statuses = [];
+        for await (const event of session.streamHistory()) {
+          if (
+            event.type === "provider_subagent" &&
+            event.event.type === "upsert" &&
+            event.event.id === "reusable-child"
+          ) {
+            statuses.push(event.event.status);
+          }
+        }
+        expect(statuses.at(-1)).toBe(state === "started" ? "running" : state);
+      } finally {
+        await registry.shutdown();
+      }
+    },
+  );
+
   test("gates persistence operations on negotiated provider capabilities", async () => {
     const harness = createProviderHarness({ capabilities: ["session.persistence"] });
     const registry = new PluginAgentClientRegistry(createTestLogger());
@@ -1321,3 +2130,28 @@ test("plugin without a runtime safety capability uses baseline collection withou
     await rm(home, { recursive: true, force: true });
   }
 });
+
+test("plugin provider import launches with runtime MCP servers and returns only saved configuration", async () => {
+  const harness = createProviderHarness();
+  const registry = new PluginAgentClientRegistry(createTestLogger());
+  registry.replace([harness.registration]);
+  const client = registry.clients()[harness.registration.id]!;
+  const storedConfig = { provider: harness.registration.id, cwd: "/project" };
+  const company = { type: "http", url: "https://tools.example.com/mcp" } as const;
+  try {
+    const imported = await client.importSession!(
+      { providerHandleId: 'plugin:{"version":1,"data":{"token":"root"}}', cwd: "/project" },
+      { config: { ...storedConfig, mcpServers: { company } }, storedConfig },
+    );
+    expect(harness.inputs).toContainEqual(
+      expect.objectContaining({
+        type: "session.open",
+        config: expect.objectContaining({ mcpServers: { company } }),
+      }),
+    );
+    expect(imported.config).toEqual(storedConfig);
+    await imported.session.close();
+  } finally {
+    await registry.shutdown();
+  }
+});
diff --git a/packages/server/src/server/agent/plugin-provider.ts b/packages/server/src/server/agent/plugin-provider.ts
index 68e9778e43..2d20056930 100644
--- a/packages/server/src/server/agent/plugin-provider.ts
+++ b/packages/server/src/server/agent/plugin-provider.ts
@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+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";
@@ -592,6 +593,7 @@ class ProviderRuntime {
 
 class ProviderRuntimeSession {
   readonly history: ProviderEvent[] = [];
+  private historyClaimed = false;
   private readonly listeners = new Set<(event: ProviderEvent) => void>();
   private capabilities: readonly string[] = [];
   private openRequest: { requestId: string; deferred: Deferred<void> } | null = null;
@@ -601,6 +603,7 @@ class ProviderRuntimeSession {
   >();
   private readonly activeTurnIds = new Set<string>();
   private terminal = false;
+  private closePromise: Promise<void> | null = null;
   config: ProviderConfigState = { models: [], modes: [], thinkingOptions: [], settings: [] };
   commands: Array<{ name: string; description: string; argumentHint?: string }> = [];
   persistence: ProviderPersistence | null = null;
@@ -622,6 +625,10 @@ class ProviderRuntimeSession {
   }
 
   onEvent(listener: (event: ProviderEvent) => void): () => void {
+    // This buffer bridges session.open and adapter attachment. Once replayed,
+    // the adapter owns history; retaining live cumulative snapshots is quadratic.
+    this.historyClaimed = true;
+    this.history.length = 0;
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
   }
@@ -713,10 +720,19 @@ class ProviderRuntimeSession {
   }
 
   async close(): Promise<void> {
+    this.history.length = 0;
     if (this.restoration === "parent") {
       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",
@@ -725,9 +741,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> {
@@ -826,7 +842,7 @@ class ProviderRuntimeSession {
     if (event.type === "session.persistence" && this.restoration === "core") {
       this.persistence = event.persistence;
     }
-    this.history.push(event);
+    if (!this.historyClaimed) this.history.push(event);
     for (const listener of this.listeners) listener(event);
   }
 }
@@ -1052,7 +1068,7 @@ class PluginAgentClient implements AgentClient {
     if (!persistence) throw new Error(`Plugin provider '${this.provider}' did not persist import`);
     return {
       session,
-      config: { ...context.config, provider: this.provider, cwd: input.cwd },
+      config: { ...context.storedConfig, provider: this.provider, cwd: input.cwd },
       persistence,
       timeline: session.timelineHistory(),
       providerSubagentEvents: session.subagentHistory(),
@@ -1085,11 +1101,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) => {
+        forget();
+        return await this.runtime.openSession({
+          sessionId: randomUUID(),
+          config: {
+            ...config,
+            model: state.model,
+            mode: state.mode,
+            thinkingOption: state.thinkingOption,
+            settings: Object.fromEntries(
+              state.settings.map((setting) => [setting.id, setting.value]),
+            ),
+          },
+          persistence,
+          history: "replay",
+        });
+      },
+      bind,
+    );
+    bind(bridge);
     return session;
   }
 
@@ -1128,25 +1173,54 @@ class PluginAgentClient implements AgentClient {
   }
 }
 
+interface TimelineTextSnapshot {
+  type: "assistant_message" | "reasoning" | "user_message";
+  text: string;
+}
+
+function isTextSnapshotItem(
+  item: ProviderTimelineItem,
+): item is Extract<ProviderTimelineItem, { type: TimelineTextSnapshot["type"] }> {
+  return (
+    item.type === "assistant_message" || item.type === "reasoning" || item.type === "user_message"
+  );
+}
+
 class PluginAgentSession implements AgentSession {
   readonly initialTimeline: ImportedProviderSession["timeline"];
   private readonly listeners = new Set<(event: AgentStreamEvent) => void>();
-  private readonly history: AgentStreamEvent[] = [];
+  private readonly history = new PluginSessionHistory();
   private readonly pendingPermissions = new Map<string, AgentPermissionRequest>();
   private readonly permissionResponses = new Map<string, AgentPermissionResponse>();
   private readonly revertTokens = new Map<string, ProviderTimelineItem["revertToken"]>();
-  private readonly timelineSnapshots = new Map<string, ProviderTimelineItem>();
+  private readonly timelineSnapshots = new Map<string, TimelineTextSnapshot>();
   private readonly subagentIdsBySession = new Map<string, string | null>();
-  private readonly childUnsubscribes = new Map<string, () => void>();
-  private readonly childSnapshots = new Map<string, Map<string, ProviderTimelineItem>>();
+  private readonly children = new Map<
+    string,
+    { session: ProviderRuntimeSession; unsubscribe: () => void }
+  >();
+  private readonly childSnapshots = new Map<string, Map<string, TimelineTextSnapshot>>();
   private unsubscribe: (() => void) | null = null;
   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,
+    ) => Promise<ProviderRuntimeSession>,
+    private readonly onBind: (bridge: ProviderRuntimeSession) => void,
   ) {
     this.subagentIdsBySession.set(bridge.id, null);
     for (const event of bridge.history) this.accept(event, false);
@@ -1163,7 +1237,13 @@ 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[] {
@@ -1191,6 +1271,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,
@@ -1213,6 +1294,7 @@ class PluginAgentSession implements AgentSession {
     prompt: AgentPromptInput,
     options: SteerActiveTurnOptions,
   ): Promise<SteerResult> {
+    this.assertReplayComplete();
     if (!this.bridge.negotiatedCapabilities.includes("prompt.steer")) {
       return { status: "unavailable" };
     }
@@ -1236,7 +1318,8 @@ class PluginAgentSession implements AgentSession {
   }
 
   async *streamHistory(): AsyncGenerator<AgentStreamEvent> {
-    for (const event of this.history) yield event;
+    await this.ensureReplay();
+    for (const event of this.history.read(this.provider)) yield event;
   }
 
   get canStopRuntime(): (() => Promise<boolean>) | undefined {
@@ -1263,6 +1346,7 @@ class PluginAgentSession implements AgentSession {
   }
 
   async setMode(modeId: string): Promise<void> {
+    this.assertReplayComplete();
     await this.bridge.configure({ mode: modeId });
   }
 
@@ -1299,11 +1383,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.listeners.clear();
+    await this.replaying?.catch(() => undefined);
+    await this.clearBinding();
+    this.replay = null;
     this.listeners.clear();
     this.onClose();
     await this.bridge.close();
@@ -1318,14 +1401,17 @@ class PluginAgentSession implements AgentSession {
   }
 
   async setModel(modelId: string | null): Promise<void> {
+    this.assertReplayComplete();
     await this.bridge.configure({ model: modelId });
   }
 
   async setThinkingOption(thinkingOptionId: string | null): Promise<void> {
+    this.assertReplayComplete();
     await this.bridge.configure({ thinkingOption: thinkingOptionId });
   }
 
   async setFeature(featureId: string, value: unknown): Promise<void> {
+    this.assertReplayComplete();
     await this.bridge.configure({
       settings: { [featureId]: toJsonValue(value, `setting '${featureId}'`) },
     });
@@ -1344,16 +1430,20 @@ class PluginAgentSession implements AgentSession {
   }
 
   timelineHistory(): ImportedProviderSession["timeline"] {
-    return this.history.flatMap((event) =>
-      event.type === "timeline" ? [{ item: event.item, timestamp: event.timestamp }] : [],
-    );
+    return this.history
+      .read(this.provider)
+      .flatMap((event) =>
+        event.type === "timeline" ? [{ item: event.item, timestamp: event.timestamp }] : [],
+      );
   }
 
   subagentHistory(): NonNullable<ImportedProviderSession["providerSubagentEvents"]> {
-    return this.history.filter(
-      (event): event is Extract<AgentStreamEvent, { type: "provider_subagent" }> =>
-        event.type === "provider_subagent",
-    );
+    return this.history
+      .read(this.provider)
+      .filter(
+        (event): event is Extract<AgentStreamEvent, { type: "provider_subagent" }> =>
+          event.type === "provider_subagent",
+      );
   }
 
   attachChild(
@@ -1382,13 +1472,13 @@ class PluginAgentSession implements AgentSession {
         cwd: opened.cwd,
       },
     });
-    const snapshots = new Map<string, ProviderTimelineItem>();
+    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 {
@@ -1568,7 +1658,7 @@ class PluginAgentSession implements AgentSession {
   private acceptChildEvent(
     childId: string,
     event: ProviderEvent,
-    snapshots: Map<string, ProviderTimelineItem>,
+    snapshots: Map<string, TimelineTextSnapshot>,
   ): void {
     if (event.type === "timeline.item") {
       const item = mapTimelineItem(event.item, snapshots);
@@ -1581,11 +1671,15 @@ class PluginAgentSession implements AgentSession {
       }
       return;
     }
-    if (event.type === "session.turn" && event.state !== "started") {
+    if (event.type === "session.turn") {
       this.publish({
         type: "provider_subagent",
         provider: this.provider,
-        event: { type: "upsert", id: childId, status: event.state },
+        event: {
+          type: "upsert",
+          id: childId,
+          status: event.state === "started" ? "running" : event.state,
+        },
       });
       return;
     }
@@ -1602,7 +1696,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.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 Error(`No provider revert token for message ${messageId}`);
     await this.bridge.revert({
@@ -1612,6 +1783,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 {
@@ -1717,24 +1894,24 @@ function mapPromptContent(prompt: AgentPromptInput): ProviderContent[] {
 
 function mapTimelineItem(
   item: ProviderTimelineItem,
-  snapshots: Map<string, ProviderTimelineItem>,
+  snapshots: Map<string, TimelineTextSnapshot>,
   revertTokens?: Map<string, ProviderTimelineItem["revertToken"]>,
 ): AgentTimelineItem | null {
   const previous = snapshots.get(item.id);
-  snapshots.set(item.id, item);
-  const { id, revertToken, ...withoutIdentity } = item;
-  if (revertToken !== undefined && revertTokens) {
-    revertTokens.set(id, revertToken);
-    if (item.type === "user_message" || item.type === "assistant_message") {
-      revertTokens.set(item.messageId ?? id, revertToken);
-    }
+  if (isTextSnapshotItem(item)) {
+    snapshots.set(item.id, { type: item.type, text: item.text });
   }
+  const { id, revertToken: _revertToken, ...withoutIdentity } = item;
+  rememberRevertToken(item, revertTokens);
 
   if (item.type === "assistant_message" || item.type === "reasoning") {
     const previousText = previous?.type === item.type ? previous.text : "";
-    const text = item.text.startsWith(previousText)
+    const suffix = item.text.startsWith(previousText)
       ? item.text.slice(previousText.length)
       : item.text;
+    // Match OpenCode's detachedSuffix: a sliced delta otherwise keeps its entire
+    // cumulative IPC snapshot alive in the projected timeline. Preserve split surrogates.
+    const text = Buffer.from(suffix, "utf16le").toString("utf16le");
     if (text.length === 0) return null;
     return item.type === "assistant_message"
       ? { type: "assistant_message", text, messageId: item.messageId ?? id }
@@ -1762,6 +1939,17 @@ function mapTimelineItem(
   return withoutIdentity as AgentTimelineItem;
 }
 
+function rememberRevertToken(
+  item: ProviderTimelineItem,
+  tokens?: Map<string, ProviderTimelineItem["revertToken"]>,
+): void {
+  if (item.revertToken === undefined || !tokens) return;
+  tokens.set(item.id, item.revertToken);
+  if (item.type === "user_message" || item.type === "assistant_message") {
+    tokens.set(item.messageId ?? item.id, item.revertToken);
+  }
+}
+
 function persistenceHandle(
   provider: string,
   persistence: ProviderPersistence,
diff --git a/packages/server/src/server/agent/plugin-session-history.ts b/packages/server/src/server/agent/plugin-session-history.ts
new file mode 100644
index 0000000000..f5efd446d7
--- /dev/null
+++ b/packages/server/src/server/agent/plugin-session-history.ts
@@ -0,0 +1,66 @@
+import { TimelineProjection } from "./timeline-projection.js";
+import type { AgentStreamEvent } from "./agent-sdk-types.js";
+
+// Replay canonical items, rather than retaining every streamed delta or tool state.
+// Sequence numbers here only preserve adapter replay order, not wire cursors.
+export class PluginSessionHistory {
+  private readonly timelines = new Map<
+    string,
+    { projection: TimelineProjection; seq: number; positions: Map<number, number> }
+  >();
+  private readonly events: Array<{ seq: number; event: AgentStreamEvent }> = [];
+  private seq = 0;
+
+  push(event: AgentStreamEvent): void {
+    const seq = ++this.seq;
+    const child =
+      event.type === "provider_subagent" && event.event.type === "timeline" ? event.event : null;
+    if (event.type !== "timeline" && !child) {
+      this.events.push({ seq, event });
+      return;
+    }
+    const key = child?.id ?? "";
+    let projection = this.timelines.get(key);
+    if (!projection) {
+      projection = { projection: new TimelineProjection(), seq: 0, positions: new Map() };
+      this.timelines.set(key, projection);
+    }
+    const timeline = event.type === "timeline" ? event : child!;
+    const row = projection.projection.append({
+      seq: ++projection.seq,
+      item: timeline.item,
+      timestamp: timeline.timestamp ?? "",
+      ...(event.type === "timeline" && event.turnId ? { turnId: event.turnId } : {}),
+    });
+    if (!projection.positions.has(row.seqStart)) projection.positions.set(row.seqStart, seq);
+  }
+
+  read(provider: string): AgentStreamEvent[] {
+    const events = [...this.events];
+    for (const [id, projection] of this.timelines) {
+      for (const row of projection.projection.getRows()) {
+        const timestamp = row.timestamp ? { timestamp: row.timestamp } : {};
+        const event: AgentStreamEvent = id
+          ? {
+              type: "provider_subagent",
+              provider,
+              event: { type: "timeline", id, item: row.item, ...timestamp },
+            }
+          : {
+              type: "timeline",
+              provider,
+              item: row.item,
+              ...timestamp,
+              ...(row.turnId ? { turnId: row.turnId } : {}),
+            };
+        events.push({ seq: projection.positions.get(row.seqStart)!, event });
+      }
+    }
+    return events.sort((a, b) => a.seq - b.seq).map(({ event }) => event);
+  }
+
+  clear(): void {
+    this.timelines.clear();
+    this.events.length = 0;
+  }
+}
diff --git a/packages/server/src/server/agent/provider-registry.ts b/packages/server/src/server/agent/provider-registry.ts
index 0f3c39868a..8616c5ea52 100644
--- a/packages/server/src/server/agent/provider-registry.ts
+++ b/packages/server/src/server/agent/provider-registry.ts
@@ -468,6 +468,7 @@ 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),
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-subagents/store.test.ts b/packages/server/src/server/agent/provider-subagents/store.test.ts
index dc71c0f5c6..5c2ca55174 100644
--- a/packages/server/src/server/agent/provider-subagents/store.test.ts
+++ b/packages/server/src/server/agent/provider-subagents/store.test.ts
@@ -80,7 +80,7 @@ describe("ProviderSubagentStore", () => {
     const [row] = subagents.fetchTimeline("parent-a", "child-1").rows;
     expect(row?.item).toMatchObject({
       type: "tool_call",
-      detail: { type: "shell", output: "x".repeat(64 * 1024) },
+      detail: { type: "shell", output: expect.stringMatching(/^x+…\[truncated \d+\.\d KB\]$/) },
     });
   });
 
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..ae80dc74f7 100644
--- a/packages/server/src/server/agent/providers/acp-agent.test.ts
+++ b/packages/server/src/server/agent/providers/acp-agent.test.ts
@@ -1,6 +1,6 @@
 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";
@@ -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>;
@@ -423,6 +445,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,
@@ -2634,6 +2674,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 +3093,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 +3131,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 +3180,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 +3207,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 +3251,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 +3312,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 +3351,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 +3404,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 +3453,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 +3486,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 +3591,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 {
@@ -4424,6 +4672,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..4b67d827dd 100644
--- a/packages/server/src/server/agent/providers/acp-agent.ts
+++ b/packages/server/src/server/agent/providers/acp-agent.ts
@@ -1,10 +1,12 @@
 import { ACPProviderOptionsSchema } from "./acp-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";
@@ -120,6 +122,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 +145,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 +335,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 +564,7 @@ interface ACPProcessTransport {
   connection: ClientSideConnection;
   stderrChunks: string[];
   spawnReady: Promise<void>;
-  spawnError: Promise<never>;
+  processError: Promise<never>;
 }
 
 interface ACPImportPromptPreviews {
@@ -634,6 +656,7 @@ interface PendingPermission {
   resolve: (response: RequestPermissionResponse) => void;
   reject: (error: Error) => void;
   turnId: string | null;
+  toolCallId: string;
 }
 
 interface PendingUserMessage {
@@ -1380,6 +1403,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 +1415,7 @@ export class ACPAgentClient implements AgentClient {
       const initialize = await this.initializeTransport(
         transport,
         options?.initializeTimeoutMs,
-        options?.providerOptions,
+        configuredOptions.clientCapabilities,
       );
       const initializedProbe: SpawnedACPProcess = {
         ...probe,
@@ -1425,7 +1449,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 +1468,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 +1493,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 +1578,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,6 +1769,7 @@ 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;
@@ -1753,7 +1777,8 @@ export class ACPAgentSession implements AgentSession, ACPClient {
   private lastActivityAt: string | null = null;
   private configOptions: SessionConfigOption[] = [];
   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 +1992,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 +2009,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 +2033,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) {
@@ -2051,58 +2107,39 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     ];
   }
 
-  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 +2149,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 +2175,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,
@@ -2221,7 +2254,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       requestedValue: modeId,
       label: "mode",
     });
-    this.availableModes = deriveModesFromACP(this.defaultModes, null, this.configOptions).modes;
+    this.availableModes = this.modesFromConfig().modes;
     this.pushEvent({
       type: "mode_changed",
       provider: this.provider,
@@ -2653,6 +2686,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
         resolve,
         reject,
         turnId: this.activeForegroundTurnId,
+        toolCallId: params.toolCall.toolCallId,
       });
     });
 
@@ -2733,14 +2767,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 +2786,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 +2915,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 +2945,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 +2982,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
           ),
           clientInfo: { name: "Paseo", version: "dev" },
         }),
-        spawnError,
+        processError,
       ]),
     );
 
@@ -2972,6 +3007,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;
@@ -2997,11 +3033,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
   private async applyConfiguredOverrides(): 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;
@@ -3138,13 +3170,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 +3247,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 +3290,37 @@ 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[] {
     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");
@@ -3416,11 +3485,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 +3498,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-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 8530e76844..5c70f0a1fe 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
@@ -466,13 +466,13 @@ describe("background Claude subagents", () => {
         type: "sub_agent",
         subAgentType: "general-purpose",
         description: "Count files here",
-        log: "[Bash] ls -1",
+        log: "",
       },
     });
   });
 
   test.each(["before", "after"])(
-    "keeps one logged Task card when child tools start %s the parent finishes",
+    "keeps one Task card when child tools start %s the parent finishes",
     async (timing) => {
       // A child can stream across the main session's turn boundary. Claude opens the next
       // main-session turn with system/init; bare child frames do not open a turn.
@@ -605,7 +605,7 @@ describe("background Claude subagents", () => {
           type: "sub_agent",
           subAgentType: "general-purpose",
           description: "Count files here",
-          log: "[Bash] ls -1",
+          log: "",
         },
       });
     },
@@ -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,57 @@ 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 session runtime safety observes pumped background work and autonomous replies", async () => {
diff --git a/packages/server/src/server/agent/providers/claude/agent.env.test.ts b/packages/server/src/server/agent/providers/claude/agent.env.test.ts
index 0d2748fd62..6d268e932c 100644
--- a/packages/server/src/server/agent/providers/claude/agent.env.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.env.test.ts
@@ -1,10 +1,11 @@
+import { once } from "node:events";
 import type { Query } from "@anthropic-ai/claude-agent-sdk";
 import { describe, expect, test, vi } from "vitest";
 
 import { createTestLogger } from "../../../../test-utils/test-logger.js";
 import type { AgentLaunchContext } from "../../agent-sdk-types.js";
 import { ClaudeAgentClient } from "./agent.js";
-import type { ClaudeQueryInput } from "./query.js";
+import { claudeQuery, type ClaudeQueryInput } from "./query.js";
 
 function createQueryMock(events: unknown[]): Query {
   let index = 0;
@@ -29,6 +30,55 @@ function createQueryMock(events: unknown[]): Query {
 }
 
 describe("Claude SDK env", () => {
+  test.each(
+    ["node", "bun", process.execPath].flatMap((command) =>
+      [undefined, "Paseo", "custom-client"].map((entrypoint) => ({ command, entrypoint })),
+    ),
+  )(
+    "preserves explicit launch identity $entrypoint in $command while clearing inherited session env",
+    async ({ command, entrypoint }) => {
+      let output = "";
+      let exited = Promise.resolve<unknown[]>([]);
+      const query = claudeQuery(
+        { prompt: "", options: {} },
+        {
+          runtimeSettings: { env: { CLAUDE_CODE_ENTRYPOINT: "sdk-ts" } },
+          launchEnv: entrypoint === undefined ? {} : { CLAUDE_CODE_ENTRYPOINT: entrypoint },
+          queryFactory: ({ options }) => {
+            if (!options.spawnClaudeCodeProcess) {
+              throw new Error("Missing Claude process launcher");
+            }
+            const child = options.spawnClaudeCodeProcess({
+              command,
+              args: [
+                "-e",
+                "process.stdout.write(JSON.stringify({ entrypoint: process.env.CLAUDE_CODE_ENTRYPOINT, parentSession: process.env.CLAUDECODE ?? null }))",
+              ],
+              cwd: process.cwd(),
+              env: { ...process.env, CLAUDE_CODE_ENTRYPOINT: "sdk-ts", CLAUDECODE: "1" },
+              signal: new AbortController().signal,
+            });
+            child.stdout.on("data", (chunk: Buffer) => {
+              output += chunk.toString();
+            });
+            exited = once(child, "close");
+            return createQueryMock([]);
+          },
+        },
+      );
+
+      try {
+        expect(await exited).toEqual([0, null]);
+        expect(JSON.parse(output)).toEqual({
+          ...(entrypoint === undefined ? {} : { entrypoint }),
+          parentSession: null,
+        });
+      } finally {
+        query.close();
+      }
+    },
+  );
+
   test("forwards launch-context env through Claude process env", async () => {
     let capturedEnv: Record<string, string | undefined> | undefined;
     let capturedPerTaskStopAffordance: boolean | undefined;
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 b355f367b3..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
@@ -1,9 +1,14 @@
+import { measureMainThreadWork } from "../../../../test-utils/main-thread-work.js";
 import fs, { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { open } from "node:fs/promises";
+import { performance } from "node:perf_hooks";
 import * as os from "node:os";
 import * as path from "node:path";
 import pino from "pino";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
+import { createTestPaseoDaemon } from "../../../test-utils/paseo-daemon.js";
+import type { ClaudeRewindSdk } from "./rewind.js";
 import { ClaudeAgentClient } from "./agent.js";
 import { claudeProjectDirSync } from "./project-dir.js";
 import { withClaudeReplayHistory } from "./transcript-history.js";
@@ -32,7 +37,10 @@ describe("ClaudeAgentSession persisted history load", () => {
   let configDir: string;
   let records: LogRecord[];
 
-  async function resume(queryFactory?: ClaudeQueryFactory): Promise<AgentSession> {
+  async function resume(
+    queryFactory?: ClaudeQueryFactory,
+    rewindSdk?: ClaudeRewindSdk,
+  ): Promise<AgentSession> {
     const client = new ClaudeAgentClient({
       logger: pino({ level: "info" }, { write: (line: string) => records.push(JSON.parse(line)) }),
       queryFactory:
@@ -42,10 +50,36 @@ describe("ClaudeAgentSession persisted history load", () => {
         }),
       resolveBinary: async () => process.execPath,
       resolveVersion: async () => "2.1.220",
+      rewindSdk,
     });
     return client.resumeSession({ provider: "claude", sessionId: SESSION_ID }, { cwd });
   }
 
+  function replyFactory(text: string, messageId = "live-reply"): ClaudeQueryFactory {
+    return (() => {
+      const messages = [
+        { type: "assistant", uuid: messageId, message: { content: text } },
+        { type: "result", subtype: "success", total_cost_usd: 0 },
+      ];
+      return {
+        async next() {
+          const value = messages.shift();
+          return value ? { done: false, value } : { done: true, value: undefined };
+        },
+        close() {},
+        async return() {
+          return { done: true, value: undefined };
+        },
+        async supportedCommands() {
+          return [];
+        },
+        [Symbol.asyncIterator]() {
+          return this;
+        },
+      };
+    }) as ClaudeQueryFactory;
+  }
+
   function transcriptPath(): string {
     return path.join(claudeProjectDirSync(cwd, { configDir }), `${SESSION_ID}.jsonl`);
   }
@@ -65,6 +99,286 @@ describe("ClaudeAgentSession persisted history load", () => {
     rmSync(tempRoot, { recursive: true, force: true });
   });
 
+  test("serves unrelated health requests while resuming 32 MiB of ordered history", async () => {
+    const startedAt = performance.now();
+    mkdirSync(path.dirname(transcriptPath()), { recursive: true });
+    const file = await open(transcriptPath(), "w");
+    const text = "x".repeat(16 * 1024);
+    let bytes = 0;
+    let count = 0;
+    try {
+      while (bytes < 32 * 1024 * 1024) {
+        const line =
+          JSON.stringify({ type: "assistant", message: { content: `${count}:${text}` } }) + "\n";
+        bytes += Buffer.byteLength(line);
+        await file.write(line);
+        count++;
+      }
+    } finally {
+      await file.close();
+    }
+    const daemon = await createTestPaseoDaemon();
+    let loading = true;
+    let answeredDuringLoad = false;
+    const health = fetch(`http://127.0.0.1:${daemon.port}/api/health`).then(async (response) => {
+      expect(response.status).toBe(200);
+      await response.text();
+      answeredDuringLoad = loading;
+      return undefined;
+    });
+    let session: AgentSession | undefined;
+    try {
+      const {
+        result: { resumed: loadedSession, historyCount },
+        blockingMs,
+      } = await measureMainThreadWork("Claude history main-thread work", async () => {
+        const resumed = await resume(replyFactory("live after large resume"));
+        session = resumed;
+        let index = 0;
+        for await (const event of resumed.streamHistory()) {
+          expect(event).toEqual({
+            type: "timeline",
+            provider: "claude",
+            timestamp: undefined,
+            item: { type: "assistant_message", text: `${index}:${text}` },
+          });
+          index++;
+        }
+        loading = false;
+        await health;
+        return { resumed, historyCount: index };
+      });
+      console.info(
+        JSON.stringify({
+          bytes,
+          count,
+          blockingMs,
+          answeredDuringLoad,
+          elapsedMs: performance.now() - startedAt,
+        }),
+      );
+      expect(historyCount).toBe(count);
+      expect(blockingMs).toBeLessThan(50);
+      expect(answeredDuringLoad).toBe(true);
+      const live = await collectSessionTurnEvents(loadedSession, "follow up");
+      expect(
+        live
+          .filter((event) => event.type === "timeline" && event.item.type === "assistant_message")
+          .map((event) => (event.type === "timeline" ? event.item : null)),
+      ).toEqual([
+        { type: "assistant_message", messageId: "live-reply", text: "live after large resume" },
+      ]);
+    } finally {
+      await session?.close();
+      await daemon.close();
+    }
+  }, 60_000);
+
+  test("rebinds ordered history before returning from rewind and accepts a live turn", async () => {
+    const entries = [
+      { type: "user", uuid: "u1", message: { content: "first" } },
+      { type: "assistant", uuid: "a1", message: { content: "first reply" } },
+      { type: "user", uuid: "u2", message: { content: "second" } },
+      { type: "assistant", uuid: "a2", message: { content: "second reply" } },
+    ];
+    mkdirSync(path.dirname(transcriptPath()), { recursive: true });
+    writeFileSync(transcriptPath(), entries.map((entry) => JSON.stringify(entry)).join("\n"));
+    const forkId = "rebound-history";
+    const forkFile = path.join(path.dirname(transcriptPath()), `${forkId}.jsonl`);
+    writeFileSync(
+      forkFile,
+      entries
+        .slice(0, 2)
+        .map((entry) => JSON.stringify(entry))
+        .join("\n"),
+    );
+    const forks: unknown[] = [];
+    const late = {
+      type: "assistant",
+      uuid: "retired-reply",
+      message: { content: "retired query" },
+    };
+    let pendingRead: ((value: unknown) => void) | undefined;
+    let releaseRetirement!: () => void;
+    const retirementGate = new Promise<void>((resolve) => {
+      releaseRetirement = resolve;
+    });
+    let retirementStarted!: () => void;
+    const retiring = new Promise<void>((resolve) => {
+      retirementStarted = resolve;
+    });
+    let firstQuery = true;
+    let retired = false;
+    const queryFactory = (() => {
+      if (!firstQuery) return replyFactory("live after rebind")({} as never);
+      firstQuery = false;
+      const messages = [
+        { type: "assistant", uuid: "before-rebind", message: { content: "before rebind" } },
+        { type: "result", subtype: "success", total_cost_usd: 0 },
+      ];
+      return {
+        async next() {
+          const value = messages.shift();
+          if (value) return { done: false, value };
+          if (retired) return { done: true, value: undefined };
+          return new Promise((resolve) => {
+            pendingRead = resolve;
+          });
+        },
+        close() {
+          retired = true;
+          pendingRead?.({ done: false, value: late });
+        },
+        async return() {
+          retirementStarted();
+          await retirementGate;
+          return { done: true, value: undefined };
+        },
+        async supportedCommands() {
+          return [];
+        },
+        [Symbol.asyncIterator]() {
+          return this;
+        },
+      };
+    }) as ClaudeQueryFactory;
+    const session = await resume(queryFactory, {
+      async forkSession(sessionId, options) {
+        forks.push({ sessionId, ...options });
+        return { sessionId: forkId };
+      },
+    });
+    try {
+      const original = await Array.fromAsync(session.streamHistory());
+      expect(original).toHaveLength(4);
+      await collectSessionTurnEvents(session, "before rewind");
+      const emitted: AgentStreamEvent[] = [];
+      const subscription = session.subscribe((event) => emitted.push(event));
+      let rewindDone = false;
+      const rewind = (async () => {
+        await session.revertConversation!({ messageId: "u2" });
+        rewindDone = true;
+      })();
+      await retiring;
+      let historyDone = false;
+      const reading = (async () => {
+        const history = await Array.fromAsync(session.streamHistory());
+        historyDone = true;
+        return history;
+      })();
+      const readingAgain = Array.fromAsync(session.streamHistory());
+      await Promise.resolve();
+      expect(rewindDone).toBe(false);
+      expect(historyDone).toBe(false);
+      releaseRetirement();
+      await rewind;
+      subscription();
+      expect(retired).toBe(true);
+      expect(
+        emitted.filter(
+          (event) => event.type === "timeline" && event.item.type === "assistant_message",
+        ),
+      ).toEqual([
+        {
+          type: "timeline",
+          provider: "claude",
+          item: {
+            type: "assistant_message",
+            text: `Claude switched to a new session: ${SESSION_ID} -> ${forkId}`,
+          },
+        },
+      ]);
+      expect(forks).toEqual([
+        { sessionId: SESSION_ID, upToMessageId: "a1", transcriptPath: transcriptPath() },
+      ]);
+      expect(session.id).toBe(forkId);
+      const [history, secondRead] = await Promise.all([reading, readingAgain]);
+      expect(history).toEqual(original.slice(0, 2));
+      expect(secondRead).toEqual([]);
+      const live = await collectSessionTurnEvents(session, "continue the fork");
+      expect(
+        live
+          .filter((event) => event.type === "timeline" && event.item.type === "assistant_message")
+          .map((event) => (event.type === "timeline" ? event.item : null)),
+      ).toEqual([
+        { type: "assistant_message", messageId: "live-reply", text: "live after rebind" },
+      ]);
+    } finally {
+      releaseRetirement();
+      await session.close();
+    }
+  });
+
+  test("reports a failed rewind without poisoning readiness when query retirement throws", async () => {
+    mkdirSync(path.dirname(transcriptPath()), { recursive: true });
+    writeFileSync(
+      transcriptPath(),
+      [
+        { type: "user", uuid: "u1", message: { content: "first" } },
+        { type: "assistant", uuid: "a1", message: { content: "reply" } },
+        { type: "user", uuid: "u2", message: { content: "second" } },
+      ]
+        .map((entry) => JSON.stringify(entry))
+        .join("\n"),
+    );
+    let firstQuery = true;
+    let finishRead: ((value: unknown) => void) | undefined;
+    const queryFactory = ((input) => {
+      const query = replyFactory(
+        firstQuery ? "before retirement" : "still available",
+        firstQuery ? "before-retirement" : "live-reply",
+      )(input);
+      if (!firstQuery) return query;
+      firstQuery = false;
+      let reads = 0;
+      return {
+        ...query,
+        async next() {
+          if (++reads <= 2) return query.next();
+          return new Promise((resolve) => {
+            finishRead = resolve;
+          });
+        },
+        close() {
+          finishRead?.({ done: true, value: undefined });
+          throw new Error("retirement failed");
+        },
+        [Symbol.asyncIterator]() {
+          return this;
+        },
+      };
+    }) as ClaudeQueryFactory;
+    const session = await resume(queryFactory, {
+      async forkSession() {
+        return { sessionId: "failed-rebind" };
+      },
+    });
+    try {
+      await Array.fromAsync(session.streamHistory());
+      await collectSessionTurnEvents(session, "before rewind");
+      await expect(session.revertConversation!({ messageId: "u2" })).rejects.toThrow(
+        "retirement failed",
+      );
+      expect(records).toContainEqual(
+        expect.objectContaining({
+          level: pino.levels.values.warn,
+          msg: "Failed to rebind Claude session",
+          sessionId: "failed-rebind",
+          err: expect.objectContaining({ message: "retirement failed" }),
+        }),
+      );
+      expect(session.id).toBe(SESSION_ID);
+      const live = await collectSessionTurnEvents(session, "after failed rebind");
+      expect(
+        live
+          .filter((event) => event.type === "timeline" && event.item.type === "assistant_message")
+          .map((event) => (event.type === "timeline" ? event.item : null)),
+      ).toEqual([{ type: "assistant_message", messageId: "live-reply", text: "still available" }]);
+    } finally {
+      await session.close();
+    }
+  });
+
   test.each(["file_path", "files"])(
     "replays %s without probing targets and preserves live existence checks",
     async (field) => {
@@ -300,21 +614,58 @@ describe("ClaudeAgentSession persisted history load", () => {
     );
   });
 
-  test("loads readable history when the temporary directory is unavailable", () => {
+  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" }] } };
     mkdirSync(path.dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(entry));
     const unavailable = path.join(tempRoot, "unavailable-tmp");
     for (const variable of ["TMPDIR", "TEMP", "TMP"]) vi.stubEnv(variable, unavailable);
-    withClaudeReplayHistory(file, (history) => {
-      expect([...history.parentEntries]).toEqual([entry]);
+    await withClaudeReplayHistory(file, async (history) => {
+      expect(await Array.fromAsync(history.parentEntries)).toEqual([entry]);
     });
   });
 
   test.each(["parent", "child", "workflow"])(
     "preserves indexed %s history when its transcript disappears between passes",
-    (target) => {
+    async (target) => {
       const parent = transcriptPath();
       const sessionDirectory = parent.slice(0, -".jsonl".length);
       const child = path.join(sessionDirectory, "subagents", "agent-child.jsonl");
@@ -334,14 +685,16 @@ describe("ClaudeAgentSession persisted history load", () => {
       writeFileSync(parent, JSON.stringify(parentEntry));
       writeFileSync(child, JSON.stringify(childEntry));
       writeFileSync(workflow, JSON.stringify(childEntry));
-      withClaudeReplayHistory(parent, (history) => {
+      await withClaudeReplayHistory(parent, async (history) => {
         rmSync({ parent, child, workflow }[target]);
         // Ownership facts and visible payloads are separate passes over the same source.
         for (let pass = 0; pass < 2; pass++) {
-          expect([...history.parentEntries]).toEqual([parentEntry]);
+          expect(await Array.fromAsync(history.parentEntries)).toEqual([parentEntry]);
           expect(history.subagents).toHaveLength(1);
-          expect([...history.subagents[0]!.entries]).toEqual([childEntry]);
-          expect([...history.workflowEntriesByRunId.get("wf_test")!]).toEqual([childEntry]);
+          expect(await Array.fromAsync(history.subagents[0]!.entries)).toEqual([childEntry]);
+          expect(await Array.fromAsync(history.workflowEntriesByRunId.get("wf_test")!)).toEqual([
+            childEntry,
+          ]);
         }
       });
     },
diff --git a/packages/server/src/server/agent/providers/claude/agent.image-rendering.test.ts b/packages/server/src/server/agent/providers/claude/agent.image-rendering.test.ts
index 5a06fea7fd..a772e544d1 100644
--- a/packages/server/src/server/agent/providers/claude/agent.image-rendering.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.image-rendering.test.ts
@@ -13,8 +13,8 @@ const MATERIALIZED_PNG_PATH_PATTERN =
   /paseo-attachments(?:-[^\\/]+)?[\\/](?:[^\\/]+[\\/])?[0-9a-f]{64}\.png$/;
 
 interface ClaudeImageTestSession {
-  translateMessageToEvents(message: SDKMessage): AgentStreamEvent[];
-  convertHistoryEntry(entry: unknown): AgentTimelineItem[];
+  translateMessageToEvents(message: SDKMessage): Promise<AgentStreamEvent[]>;
+  convertHistoryEntry(entry: unknown): Promise<AgentTimelineItem[]>;
 }
 
 async function createSession(): Promise<ClaudeImageTestSession> {
@@ -157,7 +157,7 @@ describe("Claude tool_result image rendering", () => {
   test("emits the image as assistant markdown and keeps base64 out of the live tool output", async () => {
     const session = await createSession();
 
-    const events = session.translateMessageToEvents(imageToolResultUserMessage());
+    const events = await session.translateMessageToEvents(imageToolResultUserMessage());
 
     const timelineItems = events
       .filter((event) => event.type === "timeline")
@@ -181,7 +181,7 @@ describe("Claude tool_result image rendering", () => {
   test("replays the image as assistant markdown through history conversion", async () => {
     const session = await createSession();
 
-    const items = session.convertHistoryEntry(imageToolResultHistoryEntry());
+    const items = await session.convertHistoryEntry(imageToolResultHistoryEntry());
 
     const [imageMessage, ...extraImages] = imageMessages(items);
     expect(extraImages).toEqual([]);
@@ -202,7 +202,7 @@ describe("Claude tool_result image rendering", () => {
   test("keeps base64 out of an errored tool_result that carries an image", async () => {
     const session = await createSession();
 
-    const events = session.translateMessageToEvents(erroredImageToolResultUserMessage());
+    const events = await session.translateMessageToEvents(erroredImageToolResultUserMessage());
 
     const timelineItems = events
       .filter((event) => event.type === "timeline")
@@ -226,7 +226,7 @@ describe("Claude tool_result image rendering", () => {
   test("emits one image message per image block in a multi-image tool_result", async () => {
     const session = await createSession();
 
-    const events = session.translateMessageToEvents(multiImageToolResultUserMessage());
+    const events = await session.translateMessageToEvents(multiImageToolResultUserMessage());
 
     const timelineItems = events
       .filter((event) => event.type === "timeline")
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.rewind-anchors.test.ts b/packages/server/src/server/agent/providers/claude/agent.rewind-anchors.test.ts
index 1b1932e9cd..ed9b324ff4 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 type { AgentSession } from "../../agent-sdk-types.js";
@@ -267,3 +271,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 666e701649..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(() => {
@@ -422,6 +446,237 @@ describe("ClaudeAgentSession persisted subagent replay", () => {
     });
   });
 
+  describe("a background subagent", () => {
+    // Shapes recorded from Claude Code 2.1.x: the launch returns at once with an async result,
+    // and a child stopped by an interrupt ends on the interrupt placeholder, not an end_turn.
+    function backgroundLaunch(): string[] {
+      return [
+        parentEntry([
+          {
+            type: "tool_use",
+            id: TOOL_USE_ID,
+            name: "Agent",
+            input: {
+              subagent_type: "general-purpose",
+              description: "probe sleeper",
+              run_in_background: true,
+            },
+          },
+        ]),
+        JSON.stringify({
+          type: "user",
+          sessionId: "replay-session",
+          timestamp: "2026-07-26T06:27:48.000Z",
+          message: {
+            role: "user",
+            content: [
+              {
+                type: "tool_result",
+                tool_use_id: TOOL_USE_ID,
+                content: [
+                  {
+                    type: "text",
+                    text: `Async agent launched successfully.\nagentId: ${AGENT_ID}`,
+                  },
+                ],
+              },
+            ],
+          },
+          toolUseResult: { isAsync: true, status: "async_launched", agentId: AGENT_ID },
+        }),
+      ];
+    }
+
+    function readStatus(event: { status?: string }): string | undefined {
+      return event.status;
+    }
+
+    function interruptedChild(): string[] {
+      return [
+        JSON.stringify({
+          type: "assistant",
+          isSidechain: true,
+          agentId: AGENT_ID,
+          timestamp: "2026-07-26T06:27:50.000Z",
+          message: {
+            role: "assistant",
+            content: [{ type: "tool_use", id: "toolu_child_bash", name: "Bash", input: {} }],
+            stop_reason: "tool_use",
+          },
+        }),
+        JSON.stringify({
+          type: "user",
+          isSidechain: true,
+          agentId: AGENT_ID,
+          timestamp: "2026-07-26T06:28:05.000Z",
+          message: {
+            role: "user",
+            content: [
+              {
+                type: "tool_result",
+                tool_use_id: "toolu_child_bash",
+                content: "The user doesn't want to proceed with this tool use.",
+                is_error: true,
+              },
+            ],
+          },
+        }),
+        JSON.stringify({
+          type: "user",
+          isSidechain: true,
+          agentId: AGENT_ID,
+          timestamp: "2026-07-26T06:28:05.001Z",
+          message: {
+            role: "user",
+            content: [{ type: "text", text: "[Request interrupted by user for tool use]" }],
+          },
+        }),
+      ];
+    }
+
+    test.each([
+      ["the meta sidecar", JSON.stringify({ toolUseId: TOOL_USE_ID })],
+      ["the legacy scrape", null],
+    ])("is canceled when an interrupt stopped it, linked through %s", async (_link, meta) => {
+      writeSession({ parentLines: backgroundLaunch(), meta, sidechainLines: interruptedChild() });
+
+      expect(upserts(await replayDescriptors()).at(-1)).toMatchObject({
+        id: TOOL_USE_ID,
+        status: "canceled",
+      });
+    });
+
+    test("stays running when the child was given a new prompt after the interrupt", async () => {
+      writeSession({
+        parentLines: backgroundLaunch(),
+        meta: JSON.stringify({ toolUseId: TOOL_USE_ID }),
+        sidechainLines: [
+          ...interruptedChild(),
+          JSON.stringify({
+            type: "user",
+            isSidechain: true,
+            agentId: AGENT_ID,
+            timestamp: "2026-07-26T06:29:00.000Z",
+            message: { role: "user", content: [{ type: "text", text: "Carry on with the task." }] },
+          }),
+        ],
+      });
+
+      const statuses = upserts(await replayDescriptors()).map(readStatus);
+      expect(statuses).not.toContain("canceled");
+      expect(statuses).toContain("running");
+    });
+
+    test.each(["interrupted", "running"])(
+      "ignores an API request copy of a %s child's launch result",
+      async (state) => {
+        const launch = backgroundLaunch();
+        const result = JSON.parse(launch[1]!);
+        writeSession({
+          parentLines: [
+            ...launch,
+            JSON.stringify({
+              type: "api-request-blob",
+              sessionId: "replay-session",
+              hash: "request-copy",
+              message: result.message,
+            }),
+          ],
+          meta: JSON.stringify({ toolUseId: TOOL_USE_ID }),
+          sidechainLines:
+            state === "interrupted"
+              ? interruptedChild()
+              : [sidechainEntry({ stopReason: "tool_use" })],
+        });
+        expect(upserts(await replayDescriptors()).at(-1)).toMatchObject({
+          id: TOOL_USE_ID,
+          status: state === "interrupted" ? "canceled" : "running",
+        });
+      },
+    );
+
+    test("stays running while the child has not finished", async () => {
+      writeSession({
+        parentLines: backgroundLaunch(),
+        meta: JSON.stringify({ toolUseId: TOOL_USE_ID }),
+        sidechainLines: [sidechainEntry({ stopReason: "tool_use" })],
+      });
+
+      const statuses = upserts(await replayDescriptors()).map(readStatus);
+      expect(statuses).not.toContain("completed");
+      expect(statuses).toContain("running");
+    });
+
+    function taskNotification(status: string, form = "user"): string {
+      const text = `<task-notification>\n<task-id>${AGENT_ID}</task-id>\n<tool-use-id>${TOOL_USE_ID}</tool-use-id>\n<status>${status}</status>\n<summary>Background task ended</summary>\n</task-notification>`;
+      const records = {
+        user: { message: { role: "user", content: [{ type: "text", text }] } },
+        system: {
+          subtype: "task_notification",
+          task_id: AGENT_ID,
+          tool_use_id: TOOL_USE_ID,
+          status,
+        },
+        "queue-operation": { operation: "enqueue", content: text },
+      };
+      return JSON.stringify({
+        type: form,
+        timestamp: "2026-07-26T06:29:00.000Z",
+        ...records[form as keyof typeof records],
+      });
+    }
+
+    for (const form of ["user", "system", "queue-operation"]) {
+      test.each([
+        ["completed", "completed"],
+        ["failed", "failed"],
+        ["killed", "canceled"],
+        ["stopped", "canceled"],
+      ])(
+        `restores a %s task notification from ${form} when the child stop_reason is null`,
+        async (status, expected) => {
+          writeSession({
+            parentLines: [...backgroundLaunch(), taskNotification(status, form)],
+            meta: JSON.stringify({ toolUseId: TOOL_USE_ID }),
+            sidechainLines: [sidechainEntry({ stopReason: null })],
+          });
+          expect(upserts(await replayDescriptors()).at(-1)).toMatchObject({
+            id: TOOL_USE_ID,
+            status: expected,
+          });
+        },
+      );
+    }
+
+    test("prefers a stopped notification over the child's end_turn", async () => {
+      writeSession({
+        parentLines: [...backgroundLaunch(), taskNotification("stopped")],
+        meta: JSON.stringify({ toolUseId: TOOL_USE_ID }),
+        sidechainLines: [sidechainEntry({ stopReason: "end_turn" })],
+      });
+      expect(upserts(await replayDescriptors()).at(-1)).toMatchObject({ status: "canceled" });
+    });
+
+    test("does not invent an outcome for an unknown notification status", async () => {
+      writeSession({
+        parentLines: [...backgroundLaunch(), taskNotification("unknown")],
+        meta: JSON.stringify({ toolUseId: TOOL_USE_ID }),
+        sidechainLines: [sidechainEntry({ stopReason: null })],
+      });
+      expect(upserts(await replayDescriptors()).at(-1)).toMatchObject({ status: "running" });
+    });
+
+    test("completes from the child's own end_turn", async () => {
+      writeSession({
+        parentLines: backgroundLaunch(),
+        meta: JSON.stringify({ toolUseId: TOOL_USE_ID }),
+        sidechainLines: [sidechainEntry({ stopReason: "end_turn" })],
+      });
+
+      expect(upserts(await replayDescriptors()).at(-1)).toMatchObject({ status: "completed" });
+    });
+  });
+
   test("does not replay a skill-spawned subagent the parent never named", async () => {
     // The reported bug. A /code-review subagent has no Task tool_use, so its sidecar carries only
     // agentType and its id appears nowhere in the parent — it used to replay as running forever,
@@ -506,7 +761,7 @@ describe("ClaudeAgentSession persisted subagent replay", () => {
     );
   }, 120_000);
 
-  test("limits retained child shell output to the timeline's existing content limit", async () => {
+  test("limits retained child shell output to the timeline item budget", async () => {
     const output = "x".repeat(128 * 1024);
     writeSession({
       parentLines: [taskToolUse(), taskToolResult()],
@@ -551,7 +806,10 @@ describe("ClaudeAgentSession persisted subagent replay", () => {
         type: "timeline",
         id: TOOL_USE_ID,
         item: expect.objectContaining({
-          detail: expect.objectContaining({ type: "shell", output: output.slice(0, 64 * 1024) }),
+          detail: expect.objectContaining({
+            type: "shell",
+            output: expect.stringMatching(/^x+…\[truncated \d+\.\d KB\]$/),
+          }),
         }),
       }),
     ]);
@@ -1028,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.sub-agent-sidechain.test.ts b/packages/server/src/server/agent/providers/claude/agent.sub-agent-sidechain.test.ts
index 84293afa6a..f219baa1b1 100644
--- a/packages/server/src/server/agent/providers/claude/agent.sub-agent-sidechain.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.sub-agent-sidechain.test.ts
@@ -273,7 +273,7 @@ describe("ClaudeAgentSession sub-agent sidechain updates", () => {
     queryFactory.mockReset();
   });
 
-  test("accumulates lightweight sub_agent detail and preserves callId lifecycle collapse", async () => {
+  test("labels the Task card from its input and preserves callId lifecycle collapse", async () => {
     const session = await new ClaudeAgentClient({
       logger,
       queryFactory,
@@ -307,9 +307,7 @@ describe("ClaudeAgentSession sub-agent sidechain updates", () => {
 
     expect(latest.detail.subAgentType).toBe("Explore");
     expect(latest.detail.description).toBe("Inspect repository structure");
-    expect(latest.detail.log).toContain("[Read] README.md");
-    expect(latest.detail.log).toContain("[Edit] src/index.ts");
-    expect(latest.detail.log).not.toContain("VERY_LARGE_OLD_STRING");
+    expect(latest.detail.log).toBe("");
 
     const rows: AgentTimelineRow[] = timelineToolCalls.map((item, index) => ({
       seq: index + 1,
@@ -396,10 +394,7 @@ describe("ClaudeAgentSession sub-agent sidechain updates", () => {
       .map((event) => event.item)
       .at(-1);
 
-    expect(latestSubAgentUpdate?.detail).toMatchObject({
-      type: "sub_agent",
-      log: expect.stringContaining("[Read] README.md"),
-    });
+    expect(latestSubAgentUpdate?.detail).toMatchObject({ type: "sub_agent", log: "" });
   });
 
   test("routes a resumed SendMessage sidechain to the original child without a second Task card", async () => {
@@ -553,7 +548,7 @@ describe("ClaudeAgentSession sub-agent sidechain updates", () => {
     ).toMatchObject({ type: "upsert", id: "task-tail-1", status: "failed" });
   });
 
-  test("tails sub-agent actions instead of dropping latest entries at cap", async () => {
+  test("keeps the Task card the same size while the child runs", async () => {
     queryFactory.mockImplementation(() => buildQueryMock(buildTailScenarioEvents(205)));
 
     const session = await new ClaudeAgentClient({
@@ -568,24 +563,27 @@ describe("ClaudeAgentSession sub-agent sidechain updates", () => {
     const events = await collectUntilTerminal(streamSession(session, "delegate work"));
     await session.close();
 
-    const timelineToolCalls = events
-      .filter(
-        (event): event is Extract<AgentStreamEvent, { type: "timeline" }> =>
-          event.type === "timeline" && event.item.type === "tool_call",
+    const runningCards = events
+      .flatMap((event) =>
+        event.type === "timeline" &&
+        event.item.type === "tool_call" &&
+        event.item.callId === "task-tail-1" &&
+        event.item.status === "running" &&
+        event.item.detail.type === "sub_agent"
+          ? [event.item]
+          : [],
       )
-      .map((event) => event.item)
-      .filter((item) => item.callId === "task-tail-1");
-    const subAgentUpdates = timelineToolCalls.filter((item) => item.detail.type === "sub_agent");
-    const latest = subAgentUpdates[subAgentUpdates.length - 1];
-    expect(latest).toBeDefined();
-    if (!latest || latest.detail.type !== "sub_agent") {
-      throw new Error("expected sub_agent detail");
-    }
+      .map((item) => JSON.stringify(item));
+    expect(runningCards).toHaveLength(1);
 
-    expect(latest.detail.log).not.toContain("[Read] file-1.md");
-    expect(latest.detail.log).not.toContain("[Read] file-5.md");
-    expect(latest.detail.log).toContain("[Read] file-6.md");
-    expect(latest.detail.log).toContain("[Read] file-205.md");
+    const childToolCalls = events.filter(
+      (event) =>
+        event.type === "provider_subagent" &&
+        event.event.type === "timeline" &&
+        event.event.id === "task-tail-1" &&
+        event.event.item.type === "tool_call",
+    );
+    expect(childToolCalls).toHaveLength(205);
   });
 
   test("keeps a long main-thread tool call out of the subagents track", async () => {
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 2b2c725269..07b46c6b7b 100644
--- a/packages/server/src/server/agent/providers/claude/agent.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.test.ts
@@ -32,7 +32,7 @@ import type { AgentAttachment } from "@getpaseo/protocol/messages";
 import { buildAgentPrompt, renderPromptAttachmentAsText } from "../../prompt-attachments.js";
 
 interface TestClaudeSession {
-  translateMessageToEvents(message: SDKMessage): AgentStreamEvent[];
+  translateMessageToEvents(message: SDKMessage): Promise<AgentStreamEvent[]>;
   close(): Promise<void>;
 }
 
@@ -53,7 +53,7 @@ afterEach(() => {
 });
 
 describe("convertClaudeHistoryEntry", () => {
-  test("maps user tool results to timeline items", () => {
+  test("maps user tool results to timeline items", async () => {
     const toolUseId = "toolu_test";
     const entry = {
       type: "user",
@@ -79,14 +79,14 @@ describe("convertClaudeHistoryEntry", () => {
     ];
 
     const mapBlocks = vi.fn().mockReturnValue(stubTimeline);
-    const result = convertClaudeHistoryEntry(entry, mapBlocks);
+    const result = await convertClaudeHistoryEntry(entry, mapBlocks);
 
     expect(result).toEqual(stubTimeline);
     expect(mapBlocks).toHaveBeenCalledTimes(1);
     expect(Array.isArray(mapBlocks.mock.calls[0][0])).toBe(true);
   });
 
-  test("replays persisted Claude tool results as completed tool calls", () => {
+  test("replays persisted Claude tool results as completed tool calls", async () => {
     const entry = {
       type: "user",
       message: {
@@ -124,12 +124,12 @@ describe("convertClaudeHistoryEntry", () => {
 
     const mapPersistedToolResultBlocks = (): AgentTimelineItem[] => completedToolCall;
 
-    expect(convertClaudeHistoryEntry(entry, mapPersistedToolResultBlocks)).toEqual(
+    expect(await convertClaudeHistoryEntry(entry, mapPersistedToolResultBlocks)).toEqual(
       completedToolCall,
     );
   });
 
-  test("returns user messages when no tool blocks exist", () => {
+  test("returns user messages when no tool blocks exist", async () => {
     const entry = {
       type: "user",
       message: {
@@ -138,7 +138,7 @@ describe("convertClaudeHistoryEntry", () => {
       },
     };
 
-    expect(convertClaudeHistoryEntry(entry, () => [])).toEqual([
+    expect(await convertClaudeHistoryEntry(entry, () => [])).toEqual([
       {
         type: "user_message",
         text: "Run npm test",
@@ -146,7 +146,7 @@ describe("convertClaudeHistoryEntry", () => {
     ]);
   });
 
-  test("converts compact boundary metadata variants", () => {
+  test("converts compact boundary metadata variants", async () => {
     const fixtures = [
       {
         entry: {
@@ -175,7 +175,7 @@ describe("convertClaudeHistoryEntry", () => {
     ] as const;
 
     for (const fixture of fixtures) {
-      expect(convertClaudeHistoryEntry(fixture.entry, () => [])).toEqual([
+      expect(await convertClaudeHistoryEntry(fixture.entry, () => [])).toEqual([
         {
           type: "compaction",
           status: "completed",
@@ -186,7 +186,7 @@ describe("convertClaudeHistoryEntry", () => {
     }
   });
 
-  test("skips synthetic user entries", () => {
+  test("skips synthetic user entries", async () => {
     const entry = {
       type: "user",
       isSynthetic: true,
@@ -197,13 +197,13 @@ describe("convertClaudeHistoryEntry", () => {
     };
 
     const mapBlocks = vi.fn().mockReturnValue([]);
-    const result = convertClaudeHistoryEntry(entry, mapBlocks);
+    const result = await convertClaudeHistoryEntry(entry, mapBlocks);
 
     expect(result).toEqual([]);
     expect(mapBlocks).not.toHaveBeenCalled();
   });
 
-  test("skips meta user entries from Claude skill loading", () => {
+  test("skips meta user entries from Claude skill loading", async () => {
     const entry = {
       type: "user",
       isMeta: true,
@@ -219,13 +219,13 @@ describe("convertClaudeHistoryEntry", () => {
     };
 
     const mapBlocks = vi.fn().mockReturnValue([]);
-    const result = convertClaudeHistoryEntry(entry, mapBlocks);
+    const result = await convertClaudeHistoryEntry(entry, mapBlocks);
 
     expect(result).toEqual([]);
     expect(mapBlocks).not.toHaveBeenCalled();
   });
 
-  test("skips interrupt placeholder transcript noise", () => {
+  test("skips interrupt placeholder transcript noise", async () => {
     const interruptEntry = {
       type: "user",
       message: {
@@ -246,11 +246,11 @@ describe("convertClaudeHistoryEntry", () => {
       .fn()
       .mockReturnValue([{ type: "assistant_message", text: "No response requested." }]);
 
-    expect(convertClaudeHistoryEntry(interruptEntry, mapBlocks)).toEqual([]);
-    expect(convertClaudeHistoryEntry(assistantNoiseEntry, mapBlocks)).toEqual([]);
+    expect(await convertClaudeHistoryEntry(interruptEntry, mapBlocks)).toEqual([]);
+    expect(await convertClaudeHistoryEntry(assistantNoiseEntry, mapBlocks)).toEqual([]);
   });
 
-  test("skips <local-command-stdout> messages (model switch, /context, etc.)", () => {
+  test("skips <local-command-stdout> messages (model switch, /context, etc.)", async () => {
     // Real entries from Claude Code JSONL history files
     const modelSwitch = {
       type: "user",
@@ -305,24 +305,24 @@ describe("convertClaudeHistoryEntry", () => {
 
     const mapBlocks = vi.fn().mockReturnValue([]);
 
-    expect(convertClaudeHistoryEntry(modelSwitch, mapBlocks)).toEqual([]);
-    expect(convertClaudeHistoryEntry(modelSwitchWithAnsi, mapBlocks)).toEqual([]);
-    expect(convertClaudeHistoryEntry(contextDump, mapBlocks)).toEqual([]);
-    expect(convertClaudeHistoryEntry(planMode, mapBlocks)).toEqual([]);
-    expect(convertClaudeHistoryEntry(goodbye, mapBlocks)).toEqual([]);
-    expect(convertClaudeHistoryEntry(empty, mapBlocks)).toEqual([]);
+    expect(await convertClaudeHistoryEntry(modelSwitch, mapBlocks)).toEqual([]);
+    expect(await convertClaudeHistoryEntry(modelSwitchWithAnsi, mapBlocks)).toEqual([]);
+    expect(await convertClaudeHistoryEntry(contextDump, mapBlocks)).toEqual([]);
+    expect(await convertClaudeHistoryEntry(planMode, mapBlocks)).toEqual([]);
+    expect(await convertClaudeHistoryEntry(goodbye, mapBlocks)).toEqual([]);
+    expect(await convertClaudeHistoryEntry(empty, mapBlocks)).toEqual([]);
 
     // Real user messages must NOT be filtered
     const realMessage = {
       type: "user",
       message: { role: "user", content: "fix the bug in auth.ts" },
     };
-    expect(convertClaudeHistoryEntry(realMessage, mapBlocks)).toEqual([
+    expect(await convertClaudeHistoryEntry(realMessage, mapBlocks)).toEqual([
       { type: "user_message", text: "fix the bug in auth.ts" },
     ]);
   });
 
-  test("maps task notifications to synthetic tool calls", () => {
+  test("maps task notifications to synthetic tool calls", async () => {
     const entry = {
       type: "system",
       subtype: "task_notification",
@@ -333,7 +333,7 @@ describe("convertClaudeHistoryEntry", () => {
       output_file: "/tmp/bg-fail-1.txt",
     };
 
-    expect(convertClaudeHistoryEntry(entry, () => [])).toEqual([
+    expect(await convertClaudeHistoryEntry(entry, () => [])).toEqual([
       {
         type: "tool_call",
         callId: "task_notification_task-note-system-1",
@@ -357,7 +357,7 @@ describe("convertClaudeHistoryEntry", () => {
     ]);
   });
 
-  test("maps queue-operation task notifications to synthetic tool calls", () => {
+  test("maps queue-operation task notifications to synthetic tool calls", async () => {
     const entry = {
       type: "queue-operation",
       operation: "enqueue",
@@ -372,7 +372,7 @@ describe("convertClaudeHistoryEntry", () => {
       ].join("\n"),
     };
 
-    expect(convertClaudeHistoryEntry(entry, () => [])).toEqual([
+    expect(await convertClaudeHistoryEntry(entry, () => [])).toEqual([
       {
         type: "tool_call",
         callId: "task_notification_task-note-queue-1",
@@ -396,7 +396,7 @@ describe("convertClaudeHistoryEntry", () => {
     ]);
   });
 
-  test("passes assistant content blocks through to the mapper", () => {
+  test("passes assistant content blocks through to the mapper", async () => {
     const entry = {
       type: "assistant",
       message: {
@@ -414,7 +414,7 @@ describe("convertClaudeHistoryEntry", () => {
     ];
     const mapBlocks = vi.fn().mockReturnValue(mappedTimeline);
 
-    expect(convertClaudeHistoryEntry(entry, mapBlocks)).toEqual(mappedTimeline);
+    expect(await convertClaudeHistoryEntry(entry, mapBlocks)).toEqual(mappedTimeline);
     expect(mapBlocks).toHaveBeenCalledWith(entry.message.content);
   });
 });
@@ -729,6 +729,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({
@@ -887,6 +1077,68 @@ describe("ClaudeAgentSession features", () => {
     await session.close();
   });
 
+  test("keeps an extraArgs settings file when Paseo sets Claude flag settings", async () => {
+    const settingsDir = await fs.mkdtemp(path.join(os.tmpdir(), "paseo-claude-settings-"));
+    const settingsPath = path.join(settingsDir, "settings.json");
+    await fs.writeFile(
+      settingsPath,
+      JSON.stringify({ env: { ENABLE_TOOL_SEARCH: "false" }, permissions: { deny: ["Monitor"] } }),
+    );
+    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-5-5",
+      providerOptions: {
+        extraArgs: { chrome: null, settings: settingsPath },
+      },
+    });
+
+    await session.startTurn("hello");
+
+    const options = queryFactory.mock.calls[0]?.[0].options;
+    expect(options?.extraArgs).toEqual({ chrome: null });
+    expect(options?.settings).toEqual({
+      env: { ENABLE_TOOL_SEARCH: "false" },
+      permissions: { deny: ["Monitor"] },
+      fastMode: false,
+    });
+    await session.close();
+    await fs.rm(settingsDir, { recursive: true, force: true });
+  });
+
+  test("keeps inline extraArgs settings JSON for internal agents", 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(),
+      internal: true,
+      providerOptions: {
+        extraArgs: { settings: '{"env":{"ENABLE_TOOL_SEARCH":"false"}}' },
+      },
+    });
+
+    await session.startTurn("hello");
+
+    const options = queryFactory.mock.calls[0]?.[0].options;
+    expect(options?.extraArgs).toEqual({});
+    expect(options?.settings).toEqual({
+      env: { ENABLE_TOOL_SEARCH: "false" },
+      disableAllHooks: true,
+    });
+    await session.close();
+  });
+
   test("lists fast mode only for supported Opus models", async () => {
     const client = new ClaudeAgentClient({ logger, resolveBinary: async () => "/test/claude/bin" });
 
@@ -1162,16 +1414,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" }] },
         },
       });
@@ -1208,7 +1461,7 @@ describe("ClaudeAgentSession features", () => {
         input: Record<string, unknown>,
         options: Record<string, unknown>,
       ): Promise<PermissionResult>;
-      translateMessageToEvents(message: SDKMessage): AgentStreamEvent[];
+      translateMessageToEvents(message: SDKMessage): Promise<AgentStreamEvent[]>;
     };
 
     try {
@@ -1229,7 +1482,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,
@@ -1248,7 +1501,7 @@ describe("ClaudeAgentSession features", () => {
         ),
       ).resolves.toMatchObject({ behavior: "deny", interrupt: undefined });
 
-      internal.translateMessageToEvents({
+      await internal.translateMessageToEvents({
         type: "command_lifecycle",
         command_uuid: steerUuid,
         state: "started",
@@ -1288,7 +1541,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" });
@@ -2395,7 +2648,7 @@ describe("ClaudeAgentSession context window usage", () => {
   test("emits canonical task snapshots from Claude TaskCreate results", async () => {
     const session = await createSessionForTest();
     try {
-      session.translateMessageToEvents({
+      await session.translateMessageToEvents({
         type: "assistant",
         message: {
           content: [
@@ -2409,7 +2662,7 @@ describe("ClaudeAgentSession context window usage", () => {
         },
       } as unknown as SDKMessage);
 
-      const events = session.translateMessageToEvents({
+      const events = await session.translateMessageToEvents({
         type: "user",
         message: {
           content: [{ type: "tool_result", tool_use_id: "task-create-1", content: "created" }],
@@ -2655,8 +2908,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" },
     });
@@ -2727,7 +2985,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 {
@@ -2760,6 +3018,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]() {
@@ -3611,9 +3874,9 @@ describe("ClaudeAgentSession context window usage", () => {
     ]);
 
     try {
-      const compactEvents = (session as unknown as TestClaudeSession).translateMessageToEvents(
-        createCompactBoundary(),
-      );
+      const compactEvents = await (
+        session as unknown as TestClaudeSession
+      ).translateMessageToEvents(createCompactBoundary());
       expect(compactEvents).toContainEqual(
         expect.objectContaining({
           type: "usage_updated",
@@ -3799,7 +4062,7 @@ describe("ClaudeAgentSession context window usage", () => {
   test("result.result is surfaced as an assistant message when no model output was produced", async () => {
     const session = await createSessionForTest();
 
-    const events = session.translateMessageToEvents({
+    const events = await session.translateMessageToEvents({
       type: "result",
       subtype: "success",
       result: "Unknown command: /foo-doesnt-exist",
@@ -3834,7 +4097,7 @@ describe("ClaudeAgentSession context window usage", () => {
   test("result.result is not duplicated when the model produced output during the turn", async () => {
     const session = await createSessionForTest();
 
-    const events = session.translateMessageToEvents({
+    const events = await session.translateMessageToEvents({
       type: "result",
       subtype: "success",
       result: "Here is the answer.",
diff --git a/packages/server/src/server/agent/providers/claude/agent.ts b/packages/server/src/server/agent/providers/claude/agent.ts
index 201fa349eb..06b0c36e1f 100644
--- a/packages/server/src/server/agent/providers/claude/agent.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.ts
@@ -1,3 +1,4 @@
+import { setImmediate } from "node:timers/promises";
 import { ClaudeRuntimeSafety } from "./runtime-safety.js";
 import { validateProviderOptions } from "../../provider-options.js";
 import type { ChildProcess } from "node:child_process";
@@ -32,7 +33,9 @@ import {
   mapTaskNotificationSystemRecordToToolCall,
   mapTaskNotificationUserContentToToolCall,
   readTaskNotificationToolUseIdFromHistoryRecord,
+  readTaskNotificationFromHistoryRecord,
 } from "./task-notification-tool-call.js";
+import { isClaudeInterruptPlaceholderText } from "./interrupt-placeholder.js";
 import {
   getClaudeContextWindowMaxTokens,
   getClaudeModelsWithSettings,
@@ -45,6 +48,7 @@ import {
   parseClaudeCodeVersion,
   resolveClaudeDisabledThinkingForModel,
 } from "./model-manifest.js";
+import { expandTilde } from "../../../../utils/path.js";
 import { parsePartialJsonObject } from "./partial-json.js";
 import { withClaudeReplayHistory, type ClaudeReplayHistory } from "./transcript-history.js";
 import { ClaudeSidechainTracker } from "./sidechain-tracker.js";
@@ -55,6 +59,8 @@ import {
   type ClaudeHookObservationInput,
 } from "./subagents/live-source.js";
 import { observeReplaySubagents, type ClaudeReplayParentFacts } from "./subagents/replay-source.js";
+import { mapTaskStatus } from "./subagents/task-status.js";
+import type { ProviderSubagentStatus } from "../../provider-subagents/store.js";
 import { foldSubagentObservations, type SubagentObservation } from "./subagents/observation.js";
 import { observeReplayWorkflows } from "./subagents/workflow-replay-source.js";
 import { limitAgentTimelineItemContent } from "../../agent-timeline-content.js";
@@ -76,13 +82,14 @@ 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,
   type ClaudeRewindSdk,
 } from "./rewind.js";
 import { normalizeProviderReplayTimestamp } from "../../provider-history-timestamps.js";
-import { claudeConfigDir, claudeProjectDirSync, claudeTranscriptPathSync } from "./project-dir.js";
+import { claudeConfigDir, claudeProjectDirSync, claudeTranscriptPath } from "./project-dir.js";
 import { THINKING_APPLIES_NEXT_TURN_NOTICE } from "../../provider-notices.js";
 import {
   isProviderImageMarkdown,
@@ -424,7 +431,6 @@ const CLAUDE_ROOT_ONLY_COMMANDS = new Set([
   "usage",
 ]);
 const INTERRUPT_TOOL_USE_PLACEHOLDER = "[Request interrupted by user for tool use]";
-const INTERRUPT_PLACEHOLDER_PATTERN = /^\[Request interrupted by user(?:[^\]]*)\]$/;
 const NO_RESPONSE_REQUESTED_PLACEHOLDER = "No response requested.";
 const STEER_SUPERSEDED_PERMISSION_MESSAGE =
   "The user answered with a message instead of approving. Their message follows.";
@@ -436,6 +442,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
@@ -644,6 +656,40 @@ function readClaudeFastModeSetting(settings: ClaudeOptions["settings"]): boolean
   return typeof settings.fastMode === "boolean" ? settings.fastMode : null;
 }
 
+type ClaudeSettingsObject = NonNullable<Exclude<ClaudeOptions["settings"], string>>;
+
+// Mirrors `claude --settings`: the value is inline JSON or a path to a JSON file,
+// resolved against the session cwd like the Claude process would.
+async function readClaudeCliSettings(value: string, cwd: string): Promise<ClaudeSettingsObject> {
+  const trimmed = value.trim();
+  const isInlineJson = trimmed.startsWith("{");
+  const source = isInlineJson ? "--settings JSON" : path.resolve(cwd, expandTilde(trimmed));
+  let raw = trimmed;
+  if (!isInlineJson) {
+    try {
+      raw = await fsPromises.readFile(source, "utf8");
+    } catch (error) {
+      throw new Error(
+        `Failed to read Claude settings file ${source}: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `Claude ${source} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Claude ${source} must contain a JSON object`);
+  }
+  return parsed as ClaudeSettingsObject;
+}
+
 function mergeClaudeSettings(
   settings: ClaudeOptions["settings"],
   updates: NonNullable<Exclude<ClaudeOptions["settings"], string>>,
@@ -788,11 +834,6 @@ function normalizeClaudeTranscriptText(value: unknown): string | null {
   return normalized.length > 0 ? normalized : null;
 }
 
-function isClaudeInterruptPlaceholderText(value: unknown): boolean {
-  const normalized = normalizeClaudeTranscriptText(value);
-  return normalized !== null && INTERRUPT_PLACEHOLDER_PATTERN.test(normalized);
-}
-
 function isClaudeNoResponsePlaceholderText(value: unknown): boolean {
   return normalizeClaudeTranscriptText(value) === NO_RESPONSE_REQUESTED_PLACEHOLDER;
 }
@@ -1634,7 +1675,7 @@ export class ClaudeAgentClient implements AgentClient {
       cwd: merged.cwd,
     };
     const claudeConfig = this.assertConfig(mergedConfig);
-    return new ClaudeAgentSession(claudeConfig, {
+    const session = new ClaudeAgentSession(claudeConfig, {
       defaults: this.defaults,
       runtimeSettings: this.runtimeSettings,
       handle,
@@ -1645,6 +1686,8 @@ export class ClaudeAgentClient implements AgentClient {
       resolveBinary: this.resolveBinary,
       rewindSdk: this.rewindSdk,
     });
+    await session.ensureHistoryReady();
+    return session;
   }
 
   async getCatalogCacheKey(_options: FetchCatalogOptions): Promise<string> {
@@ -2257,6 +2300,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();
@@ -2329,6 +2373,9 @@ class ClaudeAgentSession implements AgentSession {
     { type: "provider_subagent" }
   >[] = [];
   private historyPending = false;
+  // Readiness never rejects; history/rebind failures are logged at their owning boundary.
+  private historyReady: Promise<void> | null = null;
+  private historySessionId: string | null = null;
   private replayingHistory = false;
   private turnState: TurnState = "idle";
   private nextTurnOrdinal = 1;
@@ -2349,6 +2396,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>();
@@ -2382,7 +2435,7 @@ class ClaudeAgentSession implements AgentSession {
       }
       this.claudeSessionId = handle.sessionId;
       this.persistence = handle;
-      this.loadPersistedHistory(handle.sessionId);
+      this.historySessionId = handle.sessionId;
     } else {
       this.claudeSessionId = null;
       this.persistence = null;
@@ -2420,7 +2473,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
         ? {
@@ -2462,6 +2515,7 @@ class ClaudeAgentSession implements AgentSession {
     prompt: AgentPromptInput,
     options?: AgentRunOptions,
   ): Promise<{ turnId: string }> {
+    await this.ensureHistoryReady();
     if (this.closed) {
       throw new Error("Claude session is closed");
     }
@@ -2490,6 +2544,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();
@@ -2539,7 +2594,11 @@ class ClaudeAgentSession implements AgentSession {
       this.input.push(sdkMessage);
       setTimeout(() => {
         if (this.activeForegroundTurnId === turnId) {
-          this.emitSubmittedUserMessage(sdkMessage, turnId, options?.clientMessageId);
+          void this.emitSubmittedUserMessage(sdkMessage, turnId, options?.clientMessageId).catch(
+            (error: unknown) => {
+              this.logger.warn({ err: error }, "Failed to emit submitted Claude message");
+            },
+          );
         }
       }, 0);
     } catch (error) {
@@ -2583,7 +2642,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(
@@ -2617,6 +2676,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();
@@ -2632,6 +2718,7 @@ class ClaudeAgentSession implements AgentSession {
   }
 
   async *streamHistory(): AsyncGenerator<AgentStreamEvent> {
+    await this.ensureHistoryReady();
     if (
       !this.historyPending ||
       (this.persistedHistory.length === 0 && this.persistedProviderSubagentEvents.length === 0)
@@ -2643,7 +2730,9 @@ class ClaudeAgentSession implements AgentSession {
     this.persistedHistory = [];
     this.persistedProviderSubagentEvents = [];
     this.historyPending = false;
+    let replayed = 0;
     for (const entry of history) {
+      if (++replayed % 32 === 0) await setImmediate();
       yield {
         type: "timeline",
         item: entry.item,
@@ -2961,8 +3050,11 @@ class ClaudeAgentSession implements AgentSession {
       "provider.claude.session_close.start",
     );
     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;
@@ -3001,7 +3093,7 @@ class ClaudeAgentSession implements AgentSession {
       // (see `claude --help`), so the SDK's persistSession=false is silently dropped
       // in stream-json mode. Sweep the transcript ourselves so ephemeral runs
       // (metadata generator, branch-name generator) don't show up as resumable.
-      const historyPath = this.resolveHistoryPath(this.claudeSessionId);
+      const historyPath = await this.resolveHistoryPath(this.claudeSessionId);
       if (historyPath) {
         try {
           await promises.rm(historyPath, { force: true });
@@ -3029,6 +3121,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,
@@ -3045,7 +3138,8 @@ class ClaudeAgentSession implements AgentSession {
   }
 
   async revertConversation(input: { messageId: string }): Promise<void> {
-    const target = this.resolveConversationRewindTarget(input.messageId);
+    await this.ensureHistoryReady();
+    const target = await this.resolveConversationRewindTarget(input.messageId);
     if (target.kind === "fresh-session") {
       this.startFreshConversationSession();
       return;
@@ -3054,16 +3148,15 @@ class ClaudeAgentSession implements AgentSession {
     await revertClaudeConversation({
       sdk: this.rewindSdk,
       sessionId: currentSessionId,
-      transcriptPath: currentSessionId ? this.resolveHistoryPath(currentSessionId) : null,
+      transcriptPath: currentSessionId ? await this.resolveHistoryPath(currentSessionId) : null,
       messageId: target.messageId,
       resolveMessageId: (messageId) => this.resolveClaudeMessageId(messageId),
-      setSessionId: (sessionId) => {
-        this.rebindConversationSession(sessionId);
-      },
+      setSessionId: (sessionId) => this.rebindConversationSession(sessionId),
     });
   }
 
   async revertFiles(input: { messageId: string }): Promise<void> {
+    await this.ensureHistoryReady();
     const messageId = await this.resolveClaudeMessageId(input.messageId);
     await revertClaudeFiles({
       query: await this.ensureQuery(),
@@ -3238,38 +3331,52 @@ class ClaudeAgentSession implements AgentSession {
     return candidates;
   }
 
-  private rebindConversationSession(sessionId: string): void {
-    const oldSessionId = this.claudeSessionId;
-    this.claudeSessionId = sessionId;
-    this.pendingFreshSessionId = null;
-    this.persistence = null;
-    this.cachedRuntimeInfo = null;
-    this.queryRestartNeeded = true;
-    this.persistedHistory = [];
-    this.persistedProviderSubagentEvents = [];
-    this.historyPending = false;
-    this.userMessageIds = [];
-    this.emittedUserMessageIds.clear();
-    this.rewindTurnAnchors.length = 0;
-    this.taskState.reset();
-    this.loadPersistedHistory(sessionId);
-    if (oldSessionId && oldSessionId !== sessionId) {
-      this.dispatchEvents([
-        {
-          type: "timeline",
-          provider: "claude",
-          item: this.createClaudeSessionChangedNotice(oldSessionId, sessionId),
-        },
-        {
-          type: "thread_started",
-          provider: "claude",
-          sessionId,
-        },
-      ]);
-    }
+  private rebindConversationSession(sessionId: string): Promise<void> {
+    const previousReady = this.ensureHistoryReady();
+    const rebind = (async () => {
+      await previousReady;
+      await this.retireQuery();
+      if (this.closed) return;
+      const oldSessionId = this.claudeSessionId;
+      this.claudeSessionId = sessionId;
+      this.pendingFreshSessionId = null;
+      this.persistence = null;
+      this.cachedRuntimeInfo = null;
+      this.queryRestartNeeded = true;
+      this.persistedHistory = [];
+      this.persistedProviderSubagentEvents = [];
+      this.historyPending = false;
+      this.userMessageIds = [];
+      this.emittedUserMessageIds.clear();
+      this.rewindTurnAnchors.length = 0;
+      this.taskState.reset();
+      this.historySessionId = sessionId;
+      await this.loadPersistedHistory(sessionId);
+      if (this.closed) return;
+      if (oldSessionId && oldSessionId !== sessionId) {
+        this.dispatchEvents([
+          {
+            type: "timeline",
+            provider: "claude",
+            item: this.createClaudeSessionChangedNotice(oldSessionId, sessionId),
+          },
+          {
+            type: "thread_started",
+            provider: "claude",
+            sessionId,
+          },
+        ]);
+      }
+    })();
+    this.historyReady = rebind.catch((error) => {
+      this.logger.warn({ err: error, sessionId }, "Failed to rebind Claude session");
+    });
+    return rebind;
   }
 
   private startFreshConversationSession(): void {
+    this.historySessionId = null;
+    this.historyReady = Promise.resolve();
     const sessionId = randomUUID();
     this.claudeSessionId = sessionId;
     this.pendingFreshSessionId = sessionId;
@@ -3367,12 +3474,24 @@ 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) {
+        return { kind: "fork", messageId: steerParent };
+      }
       throw new Error(`Claude rewind target ${messageId} is not in the tracked conversation`);
     }
 
@@ -3390,7 +3509,44 @@ class ClaudeAgentSession implements AgentSession {
     return { kind: "fresh-session" };
   }
 
+  private async retireQuery(): Promise<void> {
+    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;
+    this.input = null;
+    this.queryPumpPromise = null;
+    this.queryRestartNeeded = false;
+    // Ending the input retires the process on purpose. Detach first so its
+    // exit is not reported as a crash.
+    const retiredChild = this.childProcess;
+    this.childProcess = null;
+    if (retiredChild) this.failRunningRuntimeTasks();
+    oldInput?.end();
+    oldQuery.close?.();
+    try {
+      await oldQuery.return?.();
+    } catch {
+      /* ignore */
+    }
+    // Tree-kill the old process tree now that the SDK has cleaned up.
+    // If we skip this, MCP children of the previous claude process can
+    // survive as orphans when the session spawns a replacement query.
+    if (retiredChild) {
+      await terminateWithTreeKill(retiredChild, {
+        gracefulTimeoutMs: 2_000,
+        forceTimeoutMs: 2_000,
+      }).catch(() => {
+        /* process may already be dead */
+      });
+    }
+  }
+
   private async ensureQuery(launchMode: PermissionMode = this.currentMode): Promise<Query> {
+    await this.ensureHistoryReady();
     // Controls use the running turn's query. Pending launch settings take effect
     // after that turn finishes, when its active query handle has been cleared.
     if (this.query && (!this.queryRestartNeeded || this.activeForegroundQuery === this.query)) {
@@ -3398,37 +3554,7 @@ class ClaudeAgentSession implements AgentSession {
     }
 
     if (this.queryRestartNeeded && this.query) {
-      const oldQuery = this.query;
-      const oldInput = this.input;
-      // 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;
-      this.input = null;
-      this.queryPumpPromise = null;
-      this.queryRestartNeeded = false;
-      // Ending the input retires the process on purpose. Detach first so its
-      // exit is not reported as a crash.
-      const retiredChild = this.childProcess;
-      this.childProcess = null;
-      if (retiredChild) this.failRunningRuntimeTasks();
-      oldInput?.end();
-      oldQuery.close?.();
-      try {
-        await oldQuery.return?.();
-      } catch {
-        /* ignore */
-      }
-      // Tree-kill the old process tree now that the SDK has cleaned up.
-      // If we skip this, MCP children of the previous claude process can
-      // survive as orphans when the session spawns a replacement query.
-      if (retiredChild) {
-        await terminateWithTreeKill(retiredChild, {
-          gracefulTimeoutMs: 2_000,
-          forceTimeoutMs: 2_000,
-        }).catch(() => {
-          /* process may already be dead */
-        });
-      }
+      await this.retireQuery();
     }
 
     // Preserve claudeSessionId across query recreation so buildOptions() passes
@@ -3437,9 +3563,12 @@ class ClaudeAgentSession implements AgentSession {
 
     const input = createAsyncMessageInput<SDKUserMessage>();
     const options = await this.buildOptions(launchMode);
+    // Closure can finish while launch options are being prepared.
+    if (this.closed) throw new Error("Claude session is closed");
     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(
@@ -3577,7 +3706,7 @@ class ClaudeAgentSession implements AgentSession {
       this.config.providerOptions,
       this.config.toolPolicy,
     );
-    const settingsOptions = this.buildSettingsOptions(providerOptions, { ultracode });
+    const settingsOptions = await this.buildSettingsOptions(providerOptions, { ultracode });
     const sdkEnv = this.harnessEnvironment;
     assertClaudeModeCanRun(permissionMode, sdkEnv);
 
@@ -3662,10 +3791,10 @@ class ClaudeAgentSession implements AgentSession {
     return base;
   }
 
-  private buildSettingsOptions(
+  private async buildSettingsOptions(
     providerOptions: ClaudeProviderOptions,
     input: { ultracode: boolean },
-  ): Pick<ClaudeOptions, "settings"> | Record<string, never> {
+  ): Promise<Pick<ClaudeOptions, "settings" | "extraArgs"> | Record<string, never>> {
     const fastMode = this.resolveFastModeSetting();
     // Internal agents do daemon work such as naming a branch, so the user's and
     // project's hooks must not run for them.
@@ -3673,12 +3802,21 @@ class ClaudeAgentSession implements AgentSession {
     if (fastMode === null && !input.ultracode && !disableAllHooks) {
       return {};
     }
+    const updates = {
+      ...(fastMode === null ? {} : { fastMode }),
+      ...(input.ultracode ? { ultracode: true } : {}),
+      ...(disableAllHooks ? { disableAllHooks: true } : {}),
+    };
+    // The SDK replaces extraArgs.settings with Options.settings, so a user's
+    // `--settings` would be dropped whenever Paseo sets flag settings. Fold it in.
+    const { settings: extraArgsSettings, ...extraArgs } = providerOptions.extraArgs ?? {};
+    if (typeof extraArgsSettings !== "string") {
+      return { settings: mergeClaudeSettings(providerOptions.settings, updates) };
+    }
+    const cliSettings = await readClaudeCliSettings(extraArgsSettings, this.config.cwd);
     return {
-      settings: mergeClaudeSettings(providerOptions.settings, {
-        ...(fastMode === null ? {} : { fastMode }),
-        ...(input.ultracode ? { ultracode: true } : {}),
-        ...(disableAllHooks ? { disableAllHooks: true } : {}),
-      }),
+      extraArgs,
+      settings: { ...cliSettings, ...providerOptions.settings, ...updates },
     };
   }
 
@@ -4026,11 +4164,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 {
@@ -4095,13 +4237,22 @@ class ClaudeAgentSession implements AgentSession {
       );
     };
     const handlePumpedMessage = async (message: SDKMessage): Promise<boolean> => {
+      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--;
@@ -4221,6 +4372,10 @@ class ClaudeAgentSession implements AgentSession {
     return isClaudeTurnInit(message) && !this.activeForegroundTurnId;
   }
 
+  private ownsQuery(query: Query): boolean {
+    return !this.closed && this.query === query;
+  }
+
   private async routeSdkMessageFromPump(message: SDKMessage): Promise<void> {
     if (this.consumeSessionStateChange(message)) {
       return;
@@ -4295,10 +4450,17 @@ class ClaudeAgentSession implements AgentSession {
     messageIdHint: string | null,
     turnId: string | null,
   ): Promise<AgentStreamEvent[]> {
-    const messageEvents = this.translateMessageToEvents(message, {
+    const query = this.query;
+    const messageEvents = await this.translateMessageToEvents(message, {
       suppressAssistantText: true,
       suppressReasoning: true,
     });
+    if (
+      this.closed ||
+      this.query !== query ||
+      (this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? null) !== turnId
+    )
+      return [];
     const assistantTimelineEvents = readClaudeParentToolUseId(message)
       ? []
       : this.timelineAssembler
@@ -4316,6 +4478,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];
   }
 
@@ -4443,13 +4620,13 @@ class ClaudeAgentSession implements AgentSession {
     return withdrewAll;
   }
 
-  private translateMessageToEvents(
+  private async translateMessageToEvents(
     message: SDKMessage,
     options?: {
       suppressAssistantText?: boolean;
       suppressReasoning?: boolean;
     },
-  ): AgentStreamEvent[] {
+  ): Promise<AgentStreamEvent[]> {
     const parentToolUseId = readClaudeParentToolUseId(message);
     if (parentToolUseId) {
       return this.translateSidechainFrameToEvents(message, parentToolUseId);
@@ -4497,11 +4674,11 @@ class ClaudeAgentSession implements AgentSession {
         this.appendSystemMessageEvents(message, events);
         break;
       case "user":
-        this.appendUserMessageEvents(message, events);
+        await this.appendUserMessageEvents(message, events);
         this.appendSidechainResultEvents(message, events);
         break;
       case "assistant": {
-        const timelineItems = this.mapBlocksToTimeline(message.message.content, {
+        const timelineItems = await this.mapBlocksToTimeline(message.message.content, {
           suppressAssistantText: options?.suppressAssistantText ?? false,
           suppressReasoning: options?.suppressReasoning ?? false,
         });
@@ -4512,7 +4689,7 @@ class ClaudeAgentSession implements AgentSession {
         break;
       }
       case "stream_event":
-        this.appendStreamEventEvents(message, events, options);
+        await this.appendStreamEventEvents(message, events, options);
         break;
       case "result":
         this.appendResultEvents(message, events);
@@ -4577,7 +4754,7 @@ class ClaudeAgentSession implements AgentSession {
   /**
    * The Task card in the parent transcript, built from the declaration.
    *
-   * The sidechain tracker also emits this card, enriched with the child's action log, and the two
+   * The sidechain tracker also emits this card when it first sees the child, and the two
    * collapse on the shared tool-call id. Emitting it at declaration matters because a
    * backgrounded subagent produces no sidechain frames at all — verified on the wire — so the
    * tracker never runs for one and its card would otherwise stay an unlabeled "Task".
@@ -4614,13 +4791,14 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
-  private emitSubmittedUserMessage(
+  private async emitSubmittedUserMessage(
     message: Extract<SDKMessage, { type: "user" }>,
     turnId: string,
     clientMessageId?: string,
-  ): void {
+  ): Promise<void> {
     const events: AgentStreamEvent[] = [];
-    this.appendUserMessageEvents(message, events);
+    await this.appendUserMessageEvents(message, events);
+    if (this.activeForegroundTurnId !== turnId) return;
     if (events.length === 0) {
       return;
     }
@@ -4711,6 +4889,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;
     }
@@ -4750,10 +4935,10 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
-  private appendUserMessageEvents(
+  private async appendUserMessageEvents(
     message: Extract<SDKMessage, { type: "user" }>,
     events: AgentStreamEvent[],
-  ): void {
+  ): Promise<void> {
     if (isSyntheticUserEntry(message)) {
       return;
     }
@@ -4792,7 +4977,7 @@ class ClaudeAgentSession implements AgentSession {
       return;
     }
     if (Array.isArray(content)) {
-      this.appendUserContentArrayEvents(content, messageId, events);
+      await this.appendUserContentArrayEvents(content, messageId, events);
     }
   }
 
@@ -4818,12 +5003,12 @@ class ClaudeAgentSession implements AgentSession {
     events.push({ type: "timeline", item, provider: "claude" });
   }
 
-  private appendUserContentArrayEvents(
+  private async appendUserContentArrayEvents(
     content: ReadonlyArray<unknown>,
     messageId: string | undefined,
     events: AgentStreamEvent[],
-  ): void {
-    const timelineItems = this.mapBlocksToTimeline(content, {
+  ): Promise<void> {
+    const timelineItems = await this.mapBlocksToTimeline(content, {
       textMessageType: "user_message",
     });
     for (const item of timelineItems) {
@@ -4839,16 +5024,16 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
-  private appendStreamEventEvents(
+  private async appendStreamEventEvents(
     message: Extract<SDKMessage, { type: "stream_event" }>,
     events: AgentStreamEvent[],
     options: { suppressAssistantText?: boolean; suppressReasoning?: boolean } | undefined,
-  ): void {
+  ): Promise<void> {
     const usageUpdatedEvent = this.contextUsage.buildStreamUsageEvent(message.event);
     if (usageUpdatedEvent) {
       events.push(usageUpdatedEvent);
     }
-    const timelineItems = this.mapPartialEvent(message.event, {
+    const timelineItems = await this.mapPartialEvent(message.event, {
       suppressAssistantText: options?.suppressAssistantText ?? false,
       suppressReasoning: options?.suppressReasoning ?? false,
     });
@@ -4862,6 +5047,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: …")
@@ -4871,7 +5073,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",
@@ -4889,10 +5096,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,
@@ -5272,22 +5488,31 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
-  private loadPersistedHistory(sessionId: string): void {
+  ensureHistoryReady(): Promise<void> {
+    if (!this.historyReady) {
+      this.historyReady = this.historySessionId
+        ? this.loadPersistedHistory(this.historySessionId)
+        : Promise.resolve();
+    }
+    return this.historyReady;
+  }
+
+  private async loadPersistedHistory(sessionId: string): Promise<void> {
     let historyPath: string | null = null;
     this.replayingHistory = true;
     try {
       this.taskState.reset();
-      historyPath = this.resolveHistoryPath(sessionId);
-      if (!historyPath || !fs.existsSync(historyPath)) {
+      historyPath = await this.resolveHistoryPath(sessionId);
+      if (!historyPath || !(await transcriptExists(historyPath))) {
         this.logger.info(
           { sessionId, cwd: this.config.cwd, historyPath },
           "No Claude transcript to load history from",
         );
         return;
       }
-      withClaudeReplayHistory(historyPath, (history) => {
-        const replay = this.ingestPersistedSidechains(history);
-        this.ingestPersistedHistory(history.parentEntries, replay);
+      await withClaudeReplayHistory(historyPath, async (history) => {
+        const replay = await this.ingestPersistedSidechains(history);
+        await this.ingestPersistedHistory(history.parentEntries, replay);
       });
     } catch (error) {
       this.logger.warn(
@@ -5299,13 +5524,13 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
-  private ingestPersistedHistory(
-    entries: Iterable<ClaudeHistoryEntry>,
+  private async ingestPersistedHistory(
+    entries: Iterable<ClaudeHistoryEntry> | AsyncIterable<ClaudeHistoryEntry>,
     replay: ClaudeReplayOwnership,
-  ): void {
+  ): Promise<void> {
     const timeline: PersistedTimelineEntry[] = [];
-    for (const entry of entries) {
-      this.ingestPersistedHistoryEntry(entry, timeline, replay);
+    for await (const entry of entries) {
+      await this.ingestPersistedHistoryEntry(entry, timeline, replay);
     }
 
     if (timeline.length > 0) {
@@ -5314,28 +5539,35 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
-  private ingestPersistedSidechains(history: ClaudeReplayHistory): ClaudeReplayOwnership {
-    const parentFacts = readClaudeReplayParentFacts(history.parentEntries);
+  private async ingestPersistedSidechains(
+    history: ClaudeReplayHistory,
+  ): Promise<ClaudeReplayOwnership> {
+    const parentFacts = await readClaudeReplayParentFacts(history.parentEntries);
 
     // Replay produces the same observations the live task protocol produces, then folds them
     // with the same function, so identity and status are derived once for both paths.
-    const subagentReplay = observeReplaySubagents({
-      subagents: history.subagents.map((subagent) => ({
+    const subagents = [];
+    for (const subagent of history.subagents) {
+      subagents.push({
         ...subagent,
-        parentFacts: readClaudeReplayParentFacts(subagent.entries),
-      })),
+        parentFacts: await readClaudeReplayParentFacts(subagent.entries),
+      });
+    }
+    const subagentReplay = await observeReplaySubagents({
+      subagents,
       parent: parentFacts,
       convertEntry: (entry) => this.convertHistoryEntry(entry),
     });
     const observations = [
       ...subagentReplay.observations,
-      ...observeReplayWorkflows({
+      ...(await observeReplayWorkflows({
         workflows: history.workflows,
         parentEntries: history.parentEntries,
         entriesByRunId: history.workflowEntriesByRunId,
         convertEntry: (entry) => this.convertHistoryEntry(entry),
-      }),
+      })),
     ];
+    this.taskProtocolSource.restore(subagentReplay.restored);
     const restoredProviderSubagentIds = new Set(
       observations
         .filter((observation) => observation.kind === "declared")
@@ -5359,11 +5591,11 @@ class ClaudeAgentSession implements AgentSession {
     return replay;
   }
 
-  private ingestPersistedHistoryEntry(
+  private async ingestPersistedHistoryEntry(
     entry: ClaudeHistoryEntry,
     timeline: PersistedTimelineEntry[],
     replay: ClaudeReplayOwnership,
-  ): void {
+  ): Promise<void> {
     if (entry.isSidechain) {
       return;
     }
@@ -5377,7 +5609,7 @@ class ClaudeAgentSession implements AgentSession {
       ? replay.toolOwners.get(notificationToolUseId)
       : undefined;
     if (notificationOwner) {
-      for (const item of this.convertHistoryEntry(entry)) {
+      for (const item of await this.convertHistoryEntry(entry)) {
         this.persistedProviderSubagentEvents.push({
           type: "provider_subagent",
           provider: "claude",
@@ -5394,7 +5626,7 @@ class ClaudeAgentSession implements AgentSession {
     const taskSnapshot = this.taskState.observe(entry);
     const items = [
       ...(taskSnapshot ? [taskSnapshot] : []),
-      ...this.convertHistoryEntry(entry).map((item) =>
+      ...(await this.convertHistoryEntry(entry)).map((item) =>
         labelReplayedSubagentCard(item, replay.subagentToolCalls),
       ),
     ];
@@ -5421,20 +5653,20 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
-  private resolveHistoryPath(sessionId: string): string | null {
+  private async resolveHistoryPath(sessionId: string): Promise<string | null> {
     const cwd = this.config.cwd;
     if (!cwd) return null;
-    return claudeTranscriptPathSync({
+    return claudeTranscriptPath({
       cwd,
       sessionId,
       configDir: claudeConfigDir(this.harnessEnvironment),
     });
   }
 
-  private convertHistoryEntry(entry: ClaudeHistoryEntry): AgentTimelineItem[] {
-    return convertClaudeHistoryEntry(entry, (content) => this.mapBlocksToTimeline(content)).map(
-      limitAgentTimelineItemContent,
-    );
+  private async convertHistoryEntry(entry: ClaudeHistoryEntry): Promise<AgentTimelineItem[]> {
+    return (
+      await convertClaudeHistoryEntry(entry, (content) => this.mapBlocksToTimeline(content))
+    ).map(limitAgentTimelineItemContent);
   }
 
   // Maps Claude content blocks into AgentTimelineItems.
@@ -5449,14 +5681,14 @@ class ClaudeAgentSession implements AgentSession {
   //
   // NOTE: convertClaudeHistoryEntry uses extractUserMessageText directly instead of this function
   // for user entries. Both paths must produce equivalent user_message items.
-  private mapBlocksToTimeline(
+  private async mapBlocksToTimeline(
     content: string | ReadonlyArray<unknown>,
     options?: {
       textMessageType?: "assistant_message" | "user_message";
       suppressAssistantText?: boolean;
       suppressReasoning?: boolean;
     },
-  ): AgentTimelineItem[] {
+  ): Promise<AgentTimelineItem[]> {
     const textMessageType = options?.textMessageType ?? "assistant_message";
     const suppressText =
       textMessageType === "assistant_message" && (options?.suppressAssistantText ?? false);
@@ -5483,7 +5715,7 @@ class ClaudeAgentSession implements AgentSession {
       if (!isClaudeContentChunk(block) || this.mapSubagentHandbackBlock(block, items)) {
         continue;
       }
-      this.mapBlockToTimeline(block, {
+      await this.mapBlockToTimeline(block, {
         items,
         userTextParts,
         textMessageType,
@@ -5528,7 +5760,7 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
-  private mapBlockToTimeline(
+  private async mapBlockToTimeline(
     block: ClaudeContentChunk,
     context: {
       items: AgentTimelineItem[];
@@ -5537,7 +5769,7 @@ class ClaudeAgentSession implements AgentSession {
       suppressText: boolean;
       suppressReasoning: boolean;
     },
-  ): void {
+  ): Promise<void> {
     switch (block.type) {
       case "text":
       case "text_delta":
@@ -5561,7 +5793,7 @@ class ClaudeAgentSession implements AgentSession {
       case "code_execution_tool_result":
       case "bash_code_execution_tool_result":
       case "text_editor_code_execution_tool_result":
-        this.handleToolResult(block, context.items);
+        await this.handleToolResult(block, context.items);
         break;
       default:
         break;
@@ -5607,7 +5839,10 @@ class ClaudeAgentSession implements AgentSession {
     );
   }
 
-  private handleToolResult(block: ClaudeContentChunk, items: AgentTimelineItem[]): void {
+  private async handleToolResult(
+    block: ClaudeContentChunk,
+    items: AgentTimelineItem[],
+  ): Promise<void> {
     const entry =
       typeof block.tool_use_id === "string" ? this.toolUseCache.get(block.tool_use_id) : undefined;
     const blockToolName = typeof block.tool_name === "string" ? block.tool_name : undefined;
@@ -5640,7 +5875,7 @@ class ClaudeAgentSession implements AgentSession {
     this.rememberSettledSubagentToolCall(settledToolCall, entry);
 
     for (const image of images) {
-      const imageItem = renderProviderImageOutputAsAssistantMarkdown(image, {
+      const imageItem = await renderProviderImageOutputAsAssistantMarkdown(image, {
         materialize: materializeProviderImage,
       });
       if (imageItem) {
@@ -5864,13 +6099,13 @@ class ClaudeAgentSession implements AgentSession {
     return false;
   }
 
-  private mapPartialEvent(
+  private async mapPartialEvent(
     event: SDKPartialAssistantMessage["event"],
     options?: {
       suppressAssistantText?: boolean;
       suppressReasoning?: boolean;
     },
-  ): AgentTimelineItem[] {
+  ): Promise<AgentTimelineItem[]> {
     if (this.updatePartialEventToolState(event)) {
       return [];
     }
@@ -5878,14 +6113,14 @@ class ClaudeAgentSession implements AgentSession {
     switch (event.type) {
       case "content_block_start":
         return isClaudeContentChunk(event.content_block)
-          ? this.mapBlocksToTimeline([event.content_block], {
+          ? await this.mapBlocksToTimeline([event.content_block], {
               suppressAssistantText: options?.suppressAssistantText,
               suppressReasoning: options?.suppressReasoning,
             })
           : [];
       case "content_block_delta":
         return isClaudeContentChunk(event.delta)
-          ? this.mapBlocksToTimeline([event.delta], {
+          ? await this.mapBlocksToTimeline([event.delta], {
               suppressAssistantText: options?.suppressAssistantText,
               suppressReasoning: options?.suppressReasoning,
             })
@@ -6167,6 +6402,7 @@ function buildClaudeSubagentCardDetail(
     type: "sub_agent",
     ...(facts.title ? { subAgentType: facts.title } : {}),
     ...(facts.description ? { description: facts.description } : {}),
+    // COMPAT(subagent-log): remove after 2027-04-30.
     log: "",
     actions: [],
   };
@@ -6191,37 +6427,38 @@ function labelReplayedSubagentCard(
  * source consumes. The agentId scrape is kept only as a fallback for sessions recorded before
  * Claude Code wrote the meta sidecar.
  */
-function readClaudeReplayParentFacts(
-  entries: Iterable<ClaudeHistoryEntry>,
-): ClaudeReplayParentFacts {
+async function readClaudeReplayParentFacts(
+  entries: Iterable<ClaudeHistoryEntry> | AsyncIterable<ClaudeHistoryEntry>,
+): Promise<ClaudeReplayParentFacts> {
   const toolCalls = new Map<string, { title?: string; description?: string }>();
-  const linksByAgentId = new Map<string, { toolCallId: string; failed: boolean }>();
-  const outcomes = new Map<string, { failed: boolean }>();
-  for (const entry of entries) {
+  const linksByAgentId = new Map<string, { toolCallId: string }>();
+  const outcomes: Map<string, { status: ProviderSubagentStatus }> = new Map();
+  for await (const entry of entries) {
+    const notification = readTaskNotificationFromHistoryRecord(entry);
+    const status = mapTaskStatus(notification?.status ?? undefined);
+    if (notification?.toolUseId && status) {
+      outcomes.set(notification.toolUseId, { status });
+    }
     const content = toObjectRecord(entry.message)?.content;
     if (!Array.isArray(content)) continue;
     for (const value of content) {
       const block = toObjectRecord(value);
+      const declaration = readClaudeReplayTaskDeclaration(entry.type, block);
+      if (declaration) toolCalls.set(declaration.id, declaration.identity);
       if (
-        block?.type === "tool_use" &&
-        (block.name === "Task" || block.name === "Agent") &&
-        typeof block.id === "string"
-      ) {
-        const input = toObjectRecord(block.input);
-        const title = readNonEmptyString(input?.name) ?? readNonEmptyString(input?.subagent_type);
-        const description = readNonEmptyString(input?.description);
-        toolCalls.set(block.id, {
-          ...(title ? { title } : {}),
-          ...(description ? { description } : {}),
+        entry.type !== "user" ||
+        block?.type !== "tool_result" ||
+        typeof block.tool_use_id !== "string"
+      )
+        continue;
+      if (toObjectRecord(entry.toolUseResult)?.status !== "async_launched")
+        outcomes.set(block.tool_use_id, {
+          status: block.is_error === true ? "failed" : "completed",
         });
-      }
-      if (block?.type !== "tool_result" || typeof block.tool_use_id !== "string") continue;
-      outcomes.set(block.tool_use_id, { failed: block.is_error === true });
       const agentId = readLegacyClaudeSubagentId(block.content);
       if (agentId)
         linksByAgentId.set(agentId, {
           toolCallId: block.tool_use_id,
-          failed: block.is_error === true,
         });
     }
   }
@@ -6232,6 +6469,29 @@ function readClaudeReplayParentFacts(
   };
 }
 
+function readClaudeReplayTaskDeclaration(
+  entryType: unknown,
+  block: Record<string, unknown> | undefined,
+): {
+  id: string;
+  identity: { title?: string; description?: string };
+} | null {
+  if (
+    entryType !== "assistant" ||
+    block?.type !== "tool_use" ||
+    (block.name !== "Task" && block.name !== "Agent") ||
+    typeof block.id !== "string"
+  )
+    return null;
+  const input = toObjectRecord(block.input);
+  const title = readNonEmptyString(input?.name) ?? readNonEmptyString(input?.subagent_type);
+  const description = readNonEmptyString(input?.description);
+  return {
+    id: block.id,
+    identity: { ...(title ? { title } : {}), ...(description ? { description } : {}) },
+  };
+}
+
 function readLegacyClaudeSubagentId(content: unknown): string | undefined {
   return /agentId:\s*([\w-]+)/.exec(JSON.stringify(content))?.[1];
 }
@@ -6248,12 +6508,14 @@ interface ClaudeHistoryEntry {
   [key: string]: unknown;
 }
 
-function mapAssistantHistoryBlocksWithMessageId(
+async function mapAssistantHistoryBlocksWithMessageId(
   entry: ClaudeHistoryEntry,
   content: string | ClaudeContentChunk[],
-  mapBlocks: (content: string | ClaudeContentChunk[]) => AgentTimelineItem[],
-): AgentTimelineItem[] {
-  const items = mapBlocks(content);
+  mapBlocks: (
+    content: string | ClaudeContentChunk[],
+  ) => AgentTimelineItem[] | Promise<AgentTimelineItem[]>,
+): Promise<AgentTimelineItem[]> {
+  const items = await mapBlocks(content);
   const assistantMessageId =
     typeof entry.uuid === "string" && entry.uuid.length > 0 ? entry.uuid : null;
   if (!assistantMessageId) {
@@ -6295,6 +6557,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") {
@@ -6321,10 +6587,27 @@ function isProviderImageMessage(item: AgentTimelineItem): boolean {
   return item.type === "assistant_message" && isProviderImageMarkdown(item.text);
 }
 
-export function convertClaudeHistoryEntry(
+/**
+ * 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: (content: string | ClaudeContentChunk[]) => AgentTimelineItem[],
-): AgentTimelineItem[] {
+  mapBlocks: (
+    content: string | ClaudeContentChunk[],
+  ) => AgentTimelineItem[] | Promise<AgentTimelineItem[]>,
+): Promise<AgentTimelineItem[]> {
   const preamble = convertClaudeHistoryEntryPreamble(entry);
   if ("shortCircuit" in preamble) {
     return preamble.shortCircuit;
@@ -6363,7 +6646,7 @@ export function convertClaudeHistoryEntry(
   }
 
   if (hasToolBlock && normalizedBlocks) {
-    const mapped = mapBlocks(normalizedBlocks);
+    const mapped = await mapBlocks(normalizedBlocks);
     if (entry.type === "user") {
       // tool_result handling (handleToolResult) emits image markdown as an assistant_message
       // alongside the tool_call. User-entry text blocks also map to assistant_message in this path
@@ -6377,7 +6660,7 @@ export function convertClaudeHistoryEntry(
   }
 
   if (entry.type === "assistant" && contentValue) {
-    return mapAssistantHistoryBlocksWithMessageId(entry, contentValue, mapBlocks);
+    return await mapAssistantHistoryBlocksWithMessageId(entry, contentValue, mapBlocks);
   }
 
   return timeline;
@@ -6682,40 +6965,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 {
@@ -6727,9 +7049,8 @@ async function readClaudeRenamedSessionTitle(input: {
   sessionId: string;
   configDir: string;
 }): Promise<string | null> {
-  let content: string;
   try {
-    content = await fsPromises.readFile(claudeTranscriptPathSync(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.
@@ -6738,7 +7059,6 @@ async function readClaudeRenamedSessionTitle(input: {
     }
     throw error;
   }
-  return readLastClaudeCustomTitle(content);
 }
 
 function normalizeImportablePromptPreview(text: string): string | null {
@@ -6829,3 +7149,13 @@ function readClaudeCommandLifecycle(message: unknown): ClaudeCommandLifecycle |
     state: record.state as ClaudeCommandLifecycle["state"],
   };
 }
+
+async function transcriptExists(file: string): Promise<boolean> {
+  try {
+    await fs.promises.access(file);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
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/interrupt-placeholder.ts b/packages/server/src/server/agent/providers/claude/interrupt-placeholder.ts
new file mode 100644
index 0000000000..f74c899234
--- /dev/null
+++ b/packages/server/src/server/agent/providers/claude/interrupt-placeholder.ts
@@ -0,0 +1,6 @@
+const INTERRUPT_PLACEHOLDER_PATTERN = /^\[Request interrupted by user(?:[^\]]*)\]$/;
+
+/** The text Claude Code records in place of a turn that an interrupt stopped. */
+export function isClaudeInterruptPlaceholderText(value: unknown): boolean {
+  return typeof value === "string" && INTERRUPT_PLACEHOLDER_PATTERN.test(value.trim());
+}
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..464964cf3a 100644
--- a/packages/server/src/server/agent/providers/claude/models.test.ts
+++ b/packages/server/src/server/agent/providers/claude/models.test.ts
@@ -365,7 +365,21 @@ describe("ClaudeAgentClient.fetchCatalog", () => {
     );
   });
 
-  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 +407,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);
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/project-dir.ts b/packages/server/src/server/agent/providers/claude/project-dir.ts
index 030a54c813..c9fa690101 100644
--- a/packages/server/src/server/agent/providers/claude/project-dir.ts
+++ b/packages/server/src/server/agent/providers/claude/project-dir.ts
@@ -1,5 +1,5 @@
-import { existsSync, readdirSync, realpathSync } from "node:fs";
-import { realpath } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { realpath, access, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -35,21 +35,21 @@ export function claudeProjectDirSync(cwd: string, options?: ClaudeProjectDirOpti
 // one `cwd` encodes to when the project moved, the daemon migrated, or Claude Code sees the
 // cwd under another name (a Windows binary under WSL). Returns the expected path when no
 // transcript exists anywhere.
-export function claudeTranscriptPathSync(input: {
+export async function claudeTranscriptPath(input: {
   cwd: string;
   sessionId: string;
   configDir?: string;
-}): string {
+}): Promise<string> {
   const options = { configDir: input.configDir };
   const fileName = `${input.sessionId}.jsonl`;
-  const expected = join(claudeProjectDirSync(input.cwd, options), fileName);
-  if (existsSync(expected)) {
+  const expected = join(await claudeProjectDir(input.cwd, options), fileName);
+  if (await exists(expected)) {
     return expected;
   }
   const projectsRoot = join(resolveConfigDir(options), "projects");
   let projectDirs: string[];
   try {
-    projectDirs = readdirSync(projectsRoot);
+    projectDirs = await readdir(projectsRoot);
   } catch (error) {
     if (isMissingDirectoryError(error)) {
       return expected;
@@ -58,13 +58,23 @@ export function claudeTranscriptPathSync(input: {
   }
   for (const projectDir of projectDirs) {
     const candidate = join(projectsRoot, projectDir, fileName);
-    if (existsSync(candidate)) {
+    if (await exists(candidate)) {
       return candidate;
     }
   }
   return expected;
 }
 
+async function exists(file: string): Promise<boolean> {
+  try {
+    await access(file);
+    return true;
+  } catch (error) {
+    if (isMissingDirectoryError(error)) return false;
+    throw error;
+  }
+}
+
 function isMissingDirectoryError(error: unknown): boolean {
   const code = (error as NodeJS.ErrnoException | null)?.code;
   return code === "ENOENT" || code === "ENOTDIR";
diff --git a/packages/server/src/server/agent/providers/claude/query.ts b/packages/server/src/server/agent/providers/claude/query.ts
index ccd511816a..0f9525d5b1 100644
--- a/packages/server/src/server/agent/providers/claude/query.ts
+++ b/packages/server/src/server/agent/providers/claude/query.ts
@@ -2,11 +2,10 @@ import { type ChildProcess, type ChildProcessWithoutNullStreams } from "node:chi
 import { query, type Options, type Query, type SpawnOptions } from "@anthropic-ai/claude-agent-sdk";
 
 import {
-  createProviderEnv,
   createProviderEnvSpec,
   type ProviderRuntimeSettings,
 } from "../../provider-launch-config.js";
-import { buildSelfNodeCommand } from "../../../paseo-env.js";
+import { buildSelfNodeCommand, createExternalProcessEnv } from "../../../paseo-env.js";
 import { spawnProcess } from "../../../../utils/spawn.js";
 
 // Keep the raw SDK query import in this module only. Claude process launch behavior
@@ -74,11 +73,10 @@ function applyRuntimeSettingsToClaudeOptions(
         runtimeSettings,
         overlays: [launchEnv],
       });
-      const providerEnv = createProviderEnv({
-        baseEnv: spawnOptions.env,
-        runtimeSettings,
-        overlays: [launchEnv],
-      });
+      // Session-open hooks may explicitly supply a client identity. Keep inherited
+      // SDK/parent identities cleared while honoring this launch-only contribution.
+      providerEnvSpec.envOverlay.CLAUDE_CODE_ENTRYPOINT = launchEnv?.CLAUDE_CODE_ENTRYPOINT;
+      const providerEnv = createExternalProcessEnv(spawnOptions.env, providerEnvSpec.envOverlay);
       const selfNodeCommand = isDefaultRuntime
         ? buildSelfNodeCommand(resolved.args, providerEnv)
         : null;
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 3b228aacc6..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,13 +72,61 @@ 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;
   transcriptPath: string | null;
   messageId: string;
   resolveMessageId?: (messageId: string) => string | Promise<string>;
-  setSessionId: (sessionId: string) => void;
+  setSessionId: (sessionId: string) => void | Promise<void>;
 }): Promise<void> {
   if (!input.sessionId || !input.transcriptPath) {
     throw new Error("Claude session is not ready for rewind");
@@ -86,7 +136,7 @@ export async function revertClaudeConversation(input: {
     upToMessageId: messageId,
     transcriptPath: input.transcriptPath,
   });
-  input.setSessionId(fork.sessionId);
+  await input.setSessionId(fork.sessionId);
 }
 
 export async function revertClaudeFiles(input: {
@@ -108,7 +158,7 @@ export async function revertClaudeConversationAndFiles(input: {
   transcriptPath: string | null;
   messageId: string;
   resolveMessageId?: (messageId: string) => string | Promise<string>;
-  setSessionId: (sessionId: string) => void;
+  setSessionId: (sessionId: string) => void | Promise<void>;
 }): Promise<void> {
   await revertClaudeFiles({
     query: input.query,
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..a21bf908ea 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,160 @@
 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";
+  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.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";
+  }
+
+  /** 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.
       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;
+    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/settings-argv.test.ts b/packages/server/src/server/agent/providers/claude/settings-argv.test.ts
new file mode 100644
index 0000000000..36d1b9d794
--- /dev/null
+++ b/packages/server/src/server/agent/providers/claude/settings-argv.test.ts
@@ -0,0 +1,46 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import pino from "pino";
+import { expect, test } from "vitest";
+import { ClaudeAgentClient } from "./agent.js";
+
+test("the real SDK passes the user's settings file contents alongside Paseo flags", async () => {
+  const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "paseo-claude-settings-argv-"));
+  const capturePath = path.join(cwd, "argv.json");
+  const binaryPath = path.join(cwd, "capture.mjs");
+  const settingsPath = path.join(cwd, "settings.json");
+  const userSettings = {
+    env: { ENABLE_TOOL_SEARCH: "false" },
+    permissions: { deny: ["Monitor"] },
+  };
+  try {
+    // A CLI fixture records the real SDK's arguments without making a model request.
+    await fs.writeFile(
+      binaryPath,
+      `import fs from "node:fs"; fs.writeFileSync(${JSON.stringify(capturePath)}, JSON.stringify(process.argv.slice(2)));`,
+    );
+    await fs.writeFile(settingsPath, JSON.stringify(userSettings));
+    const client = new ClaudeAgentClient({
+      logger: pino({ level: "silent" }),
+      resolveBinary: async () => binaryPath,
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd,
+      model: "claude-opus-5-5",
+      providerOptions: { extraArgs: { settings: settingsPath } },
+    });
+    try {
+      await session.startTurn("hello");
+    } finally {
+      await session.close();
+    }
+    const argv: string[] = JSON.parse(await fs.readFile(capturePath, "utf8"));
+    const settingsIndex = argv.indexOf("--settings");
+    expect(settingsIndex).toBeGreaterThanOrEqual(0);
+    expect(JSON.parse(argv[settingsIndex + 1]!)).toEqual({ ...userSettings, fastMode: false });
+  } finally {
+    await fs.rm(cwd, { recursive: true, force: true });
+  }
+});
diff --git a/packages/server/src/server/agent/providers/claude/sidechain-tracker.test.ts b/packages/server/src/server/agent/providers/claude/sidechain-tracker.test.ts
index a17c1cd58c..427f279bea 100644
--- a/packages/server/src/server/agent/providers/claude/sidechain-tracker.test.ts
+++ b/packages/server/src/server/agent/providers/claude/sidechain-tracker.test.ts
@@ -4,7 +4,7 @@ import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
 import { ClaudeSidechainTracker } from "./sidechain-tracker.js";
 
 describe("ClaudeSidechainTracker", () => {
-  it("retains a background child's actions across the parent finishing", () => {
+  it("keeps a background child's card across the parent finishing", () => {
     const tracker = new ClaudeSidechainTracker({
       getToolInput: () => ({ subagent_type: "general-purpose", description: "List files" }),
       isDescriptorOwnedElsewhere: () => true,
@@ -15,27 +15,67 @@ describe("ClaudeSidechainTracker", () => {
         parent_tool_use_id: "task-1",
         message: { content: [{ type: "tool_use", id, name: "Bash", input: { command } }] },
       }) as unknown as SDKMessage;
-    tracker.handleMessage(action("ls", "ls -1"), "task-1");
+    const parentCards = (events: ReturnType<typeof tracker.handleMessage>) =>
+      events.filter((event) => event.type === "timeline");
+    const childCallIds = (events: ReturnType<typeof tracker.handleMessage>) =>
+      events.flatMap((event) =>
+        event.type === "provider_subagent" &&
+        event.event.type === "timeline" &&
+        event.event.item.type === "tool_call"
+          ? [event.event.item.callId]
+          : [],
+      );
+
+    expect(parentCards(tracker.handleMessage(action("ls", "ls -1"), "task-1"))).toHaveLength(1);
     expect(tracker.finishAll("completed")).toEqual([]);
-    const events = tracker.handleMessage(action("pwd", "pwd"), "task-1");
-    expect(events).toContainEqual(
-      expect.objectContaining({
-        type: "timeline",
-        item: expect.objectContaining({
-          detail: expect.objectContaining({ log: "[Bash] ls -1\n[Bash] pwd" }),
-        }),
-      }),
-    );
+    const afterFinish = tracker.handleMessage(action("pwd", "pwd"), "task-1");
+    expect(parentCards(afterFinish)).toEqual([]);
+    expect(childCallIds(afterFinish)).toEqual(["pwd"]);
+
     tracker.delete("task-1");
     const next = tracker.handleMessage(action("next", "ls"), "task-1");
-    expect(next).toContainEqual(
-      expect.objectContaining({
-        type: "timeline",
-        item: expect.objectContaining({
-          detail: expect.objectContaining({ log: "[Bash] ls" }),
-        }),
-      }),
-    );
+    expect(parentCards(next)).toHaveLength(1);
+    expect(childCallIds(next)).toEqual(["next"]);
+  });
+
+  it("shows a streamed child tool call's input once the assistant message brings it", () => {
+    const tracker = new ClaudeSidechainTracker({ getToolInput: () => null });
+    const frames = [
+      {
+        type: "stream_event",
+        parent_tool_use_id: "task-1",
+        event: {
+          type: "content_block_start",
+          index: 0,
+          content_block: { type: "tool_use", id: "bash-1", name: "Bash", input: {} },
+        },
+      },
+      {
+        type: "assistant",
+        parent_tool_use_id: "task-1",
+        message: {
+          content: [
+            { type: "tool_use", id: "bash-1", name: "Bash", input: { command: "echo child" } },
+          ],
+        },
+      },
+    ] as unknown as SDKMessage[];
+
+    const childCards = frames
+      .flatMap((frame) => tracker.handleMessage(frame, "task-1"))
+      .flatMap((event) =>
+        event.type === "provider_subagent" &&
+        event.event.type === "timeline" &&
+        event.event.item.type === "tool_call"
+          ? [event.event.item]
+          : [],
+      );
+
+    expect(childCards.at(-1)).toMatchObject({
+      callId: "bash-1",
+      status: "running",
+      detail: { type: "shell", command: "echo child" },
+    });
   });
 
   it("uses Claude's native agent name for the provider subagent title", () => {
diff --git a/packages/server/src/server/agent/providers/claude/sidechain-tracker.ts b/packages/server/src/server/agent/providers/claude/sidechain-tracker.ts
index 083b82cea6..5ca79641f9 100644
--- a/packages/server/src/server/agent/providers/claude/sidechain-tracker.ts
+++ b/packages/server/src/server/agent/providers/claude/sidechain-tracker.ts
@@ -5,7 +5,6 @@ import {
   mapClaudeFailedToolCall,
   mapClaudeRunningToolCall,
 } from "./tool-call-mapper.js";
-import { buildToolCallDisplayModel } from "@getpaseo/protocol/tool-call-display";
 import {
   isClaudeSubagentHandbackToolName,
   readClaudeSubagentHandback,
@@ -20,21 +19,17 @@ interface ClaudeContentChunk {
 
 type ClaudeToolCallItem = Extract<AgentTimelineItem, { type: "tool_call" }>;
 
-interface SubAgentActionEntry {
-  index: number;
+interface SubAgentChildCall {
   toolName: string;
   input: unknown;
-  summary?: string;
 }
 
 interface SubAgentActivityState {
   name?: string;
   subAgentType?: string;
   description?: string;
-  actions: SubAgentActionEntry[];
-  actionKeys: string[];
-  nextActionIndex: number;
-  actionIndexByKey: Map<string, number>;
+  /** The child's tool calls awaiting results, which carry no input of their own. */
+  runningCalls: Map<string, SubAgentChildCall>;
   completedActionKeys: Set<string>;
 }
 
@@ -44,7 +39,6 @@ interface SubAgentActionCandidate {
   input: unknown;
 }
 
-const MAX_SUB_AGENT_LOG_ENTRIES = 200;
 const MAX_SUB_AGENT_SUMMARY_CHARS = 160;
 
 function readTrimmedString(value: unknown): string | undefined {
@@ -79,8 +73,7 @@ export class ClaudeSidechainTracker {
     needsSyntheticParentToolCard?: (toolUseId: string) => boolean;
     /**
      * The parent's tool call once Claude has answered it. A background child streams its frames
-     * after that answer, so its card keeps the settled status and output and gains the child's
-     * action log.
+     * after that answer, so its card keeps the settled status and output.
      */
     getSettledParentToolCall?: (toolUseId: string) => ClaudeToolCallItem | undefined;
   }) {
@@ -91,28 +84,27 @@ export class ClaudeSidechainTracker {
   }
 
   handleMessage(message: SDKMessage, parentToolUseId: string): AgentStreamEvent[] {
+    const existingState = this.activeSidechains.get(parentToolUseId);
     const state =
-      this.activeSidechains.get(parentToolUseId) ??
+      existingState ??
       ({
-        actions: [],
-        actionKeys: [],
-        nextActionIndex: 1,
-        actionIndexByKey: new Map<string, number>(),
+        runningCalls: new Map<string, SubAgentChildCall>(),
         completedActionKeys: new Set<string>(),
       } satisfies SubAgentActivityState);
     this.activeSidechains.set(parentToolUseId, state);
 
-    const contextUpdated = this.updateSubAgentContextFromTaskInput(state, parentToolUseId);
+    // The parent card is a launch marker: it changes only when the child is first seen or the
+    // task input names it differently, never with the child's activity.
+    const cardUpdated =
+      this.updateSubAgentContextFromTaskInput(state, parentToolUseId) || !existingState;
     const actionCandidates = this.extractSubAgentActionCandidates(message);
     const childTimelineItems = [
       ...this.extractSubAgentTimelineItems(message, state),
       ...this.extractSubAgentToolResults(message, state),
     ];
-    let actionUpdated = false;
     for (const action of actionCandidates) {
       if (state.completedActionKeys.has(action.key)) continue;
-      if (this.appendSubAgentAction(state, action)) {
-        actionUpdated = true;
+      if (this.trackChildCall(state, action)) {
         const toolCall = mapClaudeRunningToolCall({
           name: action.toolName,
           callId: action.key,
@@ -125,7 +117,7 @@ export class ClaudeSidechainTracker {
       }
     }
 
-    if (!contextUpdated && !actionUpdated && childTimelineItems.length === 0) {
+    if (!cardUpdated && childTimelineItems.length === 0) {
       return [];
     }
 
@@ -145,11 +137,8 @@ export class ClaudeSidechainTracker {
       type: "sub_agent",
       ...(state.subAgentType ? { subAgentType: state.subAgentType } : {}),
       ...(state.description ? { description: state.description } : {}),
-      log: state.actions
-        .map((action) =>
-          action.summary ? `[${action.toolName}] ${action.summary}` : `[${action.toolName}]`,
-        )
-        .join("\n"),
+      // COMPAT(subagent-log): remove after 2027-04-30.
+      log: "",
       actions: [],
     };
 
@@ -170,18 +159,19 @@ export class ClaudeSidechainTracker {
           },
         ];
 
-    const parentCard: AgentStreamEvent[] = this.needsSyntheticParentToolCard(parentToolUseId)
-      ? [
-          {
-            type: "timeline",
-            item: {
-              ...toolCall,
-              detail,
+    const parentCard: AgentStreamEvent[] =
+      cardUpdated && this.needsSyntheticParentToolCard(parentToolUseId)
+        ? [
+            {
+              type: "timeline",
+              item: {
+                ...toolCall,
+                detail,
+              },
+              provider: "claude",
             },
-            provider: "claude",
-          },
-        ]
-      : [];
+          ]
+        : [];
 
     return [
       ...descriptorEvents,
@@ -303,8 +293,7 @@ export class ClaudeSidechainTracker {
       if (!isClaudeContentChunk(block) || !block.type.endsWith("tool_result")) continue;
       const callId = readTrimmedString(block.tool_use_id);
       if (!callId || state.completedActionKeys.has(callId)) continue;
-      const actionIndex = state.actionIndexByKey.get(callId);
-      const action = actionIndex === undefined ? undefined : state.actions[actionIndex];
+      const action = state.runningCalls.get(callId);
       const toolName = action?.toolName ?? readTrimmedString(block.tool_name);
       if (!toolName) continue;
       const params = {
@@ -317,6 +306,7 @@ export class ClaudeSidechainTracker {
         ? mapClaudeFailedToolCall({ ...params, error: block })
         : mapClaudeCompletedToolCall(params);
       if (toolCall) {
+        state.runningCalls.delete(callId);
         state.completedActionKeys.add(callId);
         items.push(toolCall);
       }
@@ -412,13 +402,12 @@ export class ClaudeSidechainTracker {
     const key =
       readTrimmedString(block.id) ??
       `stream:${block.name}:${typeof event.index === "number" ? event.index : 0}`;
-    return [
-      {
-        key,
-        toolName: block.name,
-        input: block.input ?? null,
-      },
-    ];
+    // A streamed call starts with `{}` until its input arrives, so an empty input is not final.
+    const input =
+      block.input && typeof block.input === "object" && Object.keys(block.input).length > 0
+        ? block.input
+        : null;
+    return [{ key, toolName: block.name, input }];
   }
 
   private extractSubAgentActionCandidates(message: SDKMessage): SubAgentActionCandidate[] {
@@ -448,84 +437,20 @@ export class ClaudeSidechainTracker {
     return [];
   }
 
-  private appendSubAgentAction(
+  /** Returns whether the call is new or has gained its input, so its running card changes. */
+  private trackChildCall(
     state: SubAgentActivityState,
     candidate: SubAgentActionCandidate,
   ): boolean {
-    const normalizedToolName = readTrimmedString(candidate.toolName);
-    if (!normalizedToolName) {
+    const toolName = readTrimmedString(candidate.toolName);
+    if (!toolName) {
       return false;
     }
-
-    const summary = this.deriveSubAgentActionSummary(normalizedToolName, candidate.input);
-    const existingIndex = state.actionIndexByKey.get(candidate.key);
-
-    if (existingIndex !== undefined) {
-      const existing = state.actions[existingIndex];
-      if (!existing) {
-        return false;
-      }
-      const nextSummary = existing.summary ?? summary;
-      if (existing.toolName === normalizedToolName && existing.summary === nextSummary) {
-        return false;
-      }
-      state.actions[existingIndex] = {
-        ...existing,
-        toolName: normalizedToolName,
-        input: existing.input ?? candidate.input,
-        ...(nextSummary ? { summary: nextSummary } : {}),
-      };
-      return true;
+    const existing = state.runningCalls.get(candidate.key);
+    if (existing && (existing.input !== null || candidate.input === null)) {
+      return false;
     }
-
-    state.actions.push({
-      index: state.nextActionIndex,
-      toolName: normalizedToolName,
-      input: candidate.input,
-      ...(summary ? { summary } : {}),
-    });
-    state.nextActionIndex += 1;
-    state.actionKeys.push(candidate.key);
-    this.trimSubAgentTail(state);
-    this.rebuildSubAgentActionIndex(state);
+    state.runningCalls.set(candidate.key, { toolName, input: candidate.input });
     return true;
   }
-
-  private trimSubAgentTail(state: SubAgentActivityState): void {
-    while (state.actions.length > MAX_SUB_AGENT_LOG_ENTRIES) {
-      state.actions.shift();
-      const removedKey = state.actionKeys.shift();
-      if (removedKey) state.completedActionKeys.delete(removedKey);
-    }
-  }
-
-  private rebuildSubAgentActionIndex(state: SubAgentActivityState): void {
-    state.actionIndexByKey.clear();
-    for (let index = 0; index < state.actionKeys.length; index += 1) {
-      const key = state.actionKeys[index];
-      if (key) {
-        state.actionIndexByKey.set(key, index);
-      }
-    }
-  }
-
-  private deriveSubAgentActionSummary(toolName: string, input: unknown): string | undefined {
-    const runningToolCall = mapClaudeRunningToolCall({
-      name: toolName,
-      callId: `sub-agent-summary-${toolName}`,
-      input,
-      output: null,
-    });
-    if (!runningToolCall) {
-      return undefined;
-    }
-    const display = buildToolCallDisplayModel({
-      name: runningToolCall.name,
-      status: runningToolCall.status,
-      error: runningToolCall.error,
-      detail: runningToolCall.detail,
-      metadata: runningToolCall.metadata,
-    });
-    return this.normalizeSubAgentText(display.summary);
-  }
 }
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 2149fae139..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
@@ -1,7 +1,8 @@
+import type { ProviderSubagentStatus } from "../../../provider-subagents/store.js";
+import { mapTaskStatus } from "./task-status.js";
 import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
 
 import type { AgentMetadata } from "../../../agent-sdk-types.js";
-import type { ProviderSubagentStatus } from "../../../provider-subagents/store.js";
 import { resolveObservedClaudeModelId } from "../models.js";
 import type { SubagentObservation } from "./observation.js";
 import {
@@ -48,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,25 +122,13 @@ function readString(value: unknown): string | undefined {
 }
 
 /**
- * The descriptor has no paused or pending state, and neither is terminal, so both read as
- * running. `killed` is a cancellation, not a failure — the child was stopped, it did not error.
+ * 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.
  */
-function mapTaskStatus(status: string | undefined): ProviderSubagentStatus | undefined {
-  switch (status) {
-    case "pending":
-    case "running":
-    case "paused":
-      return "running";
-    case "completed":
-      return "completed";
-    case "failed":
-      return "failed";
-    case "killed":
-    case "stopped":
-      return "canceled";
-    default:
-      return undefined;
-  }
+export interface ClaudeRestoredSubagent {
+  taskId: string;
+  id: string;
+  presentation: ClaudeSubagentPresentationFacts;
 }
 
 export interface ClaudeTaskProtocolSourceInput {
@@ -183,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>();
@@ -267,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.
    *
@@ -280,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();
@@ -336,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);
@@ -345,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 e28d15b8c1..fc48e9db3a 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
@@ -1,3 +1,9 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import {
+  materializeProviderImage,
+  renderProviderImageOutputAsAssistantMarkdown,
+} from "../../provider-image-output.js";
 import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
 import { describe, expect, it } from "vitest";
 
@@ -30,7 +36,7 @@ function parentWithTaskCall(failed = false): ClaudeReplayParentFacts {
       ],
     ]),
     linksByAgentId: new Map(),
-    outcomesByToolCallId: new Map([[TOOL_USE_ID, { failed }]]),
+    outcomesByToolCallId: new Map([[TOOL_USE_ID, { status: failed ? "failed" : "completed" }]]),
   };
 }
 
@@ -45,7 +51,7 @@ function applyToStore(observations: SubagentObservation[]): ProviderSubagentDesc
 }
 
 describe("parseClaudeSubagentMeta", () => {
-  it("reads the real sidecar shape", () => {
+  it("reads the real sidecar shape", async () => {
     expect(
       parseClaudeSubagentMeta(
         '{"agentType":"general-purpose","description":"Reply banana","toolUseId":"toolu_013i","spawnDepth":1}',
@@ -68,7 +74,7 @@ describe("parseClaudeSubagentMeta", () => {
     expect(parseClaudeSubagentMeta(contents)).toBeNull();
   });
 
-  it("keeps the good fields when one field has the wrong type", () => {
+  it("keeps the good fields when one field has the wrong type", async () => {
     expect(parseClaudeSubagentMeta('{"agentType":"Explore","toolUseId":42}')).toEqual({
       agentType: "Explore",
       description: undefined,
@@ -79,12 +85,58 @@ describe("parseClaudeSubagentMeta", () => {
 });
 
 describe("observeReplaySubagents", () => {
-  it("links a subagent to its Task call through meta.toolUseId", () => {
-    const observations = observeReplaySubagents({
-      subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries: [] }],
+  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: () => [],
-    }).observations;
+      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({
+        subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries: [] }],
+        parent: parentWithTaskCall(),
+        convertEntry: () => [],
+      })
+    ).observations;
 
     expect(observations[0]).toMatchObject({
       kind: "declared",
@@ -95,31 +147,33 @@ describe("observeReplaySubagents", () => {
     });
   });
 
-  it("replays descendants beneath the sidechain that declared their Task", () => {
+  it("replays descendants beneath the sidechain that declared their Task", async () => {
     const nestedToolUseId = "toolu_012rzYnFZA";
-    const observations = observeReplaySubagents({
-      subagents: [
-        {
-          agentId: AGENT_ID,
-          meta: { toolUseId: TOOL_USE_ID, spawnDepth: 1 },
-          entries: [],
-          parentFacts: {
-            toolCalls: new Map([
-              [nestedToolUseId, { title: "Explore", description: "Nested audit" }],
-            ]),
-            linksByAgentId: new Map(),
-            outcomesByToolCallId: new Map([[nestedToolUseId, { failed: false }]]),
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [
+          {
+            agentId: AGENT_ID,
+            meta: { toolUseId: TOOL_USE_ID, spawnDepth: 1 },
+            entries: [],
+            parentFacts: {
+              toolCalls: new Map([
+                [nestedToolUseId, { title: "Explore", description: "Nested audit" }],
+              ]),
+              linksByAgentId: new Map(),
+              outcomesByToolCallId: new Map([[nestedToolUseId, { status: "completed" }]]),
+            },
           },
-        },
-        {
-          agentId: "a6acb4b898",
-          meta: { toolUseId: nestedToolUseId, agentType: "Explore", spawnDepth: 2 },
-          entries: [],
-        },
-      ],
-      parent: parentWithTaskCall(),
-      convertEntry: () => [],
-    }).observations;
+          {
+            agentId: "a6acb4b898",
+            meta: { toolUseId: nestedToolUseId, agentType: "Explore", spawnDepth: 2 },
+            entries: [],
+          },
+        ],
+        parent: parentWithTaskCall(),
+        convertEntry: () => [],
+      })
+    ).observations;
 
     expect(observations).toContainEqual(
       expect.objectContaining({
@@ -130,89 +184,143 @@ describe("observeReplaySubagents", () => {
     );
   });
 
-  it("keeps a subagent recorded before spawnDepth existed", () => {
-    const observations = observeReplaySubagents({
-      subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries: [] }],
-      parent: parentWithTaskCall(),
-      convertEntry: () => [],
-    }).observations;
+  it("keeps a subagent recorded before spawnDepth existed", async () => {
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries: [] }],
+        parent: parentWithTaskCall(),
+        convertEntry: () => [],
+      })
+    ).observations;
 
     expect(observations[0]).toMatchObject({ kind: "declared", id: TOOL_USE_ID });
   });
 
-  it("drops a meta-linked subagent when the parent never declared its Task", () => {
-    const observations = observeReplaySubagents({
-      subagents: [
-        {
-          agentId: AGENT_ID,
-          meta: { toolUseId: TOOL_USE_ID, agentType: "Explore", description: "Find the code" },
-          entries: [],
-        },
-      ],
-      parent: emptyParent(),
-      convertEntry: () => [],
-    }).observations;
+  it("drops a meta-linked subagent when the parent never declared its Task", async () => {
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [
+          {
+            agentId: AGENT_ID,
+            meta: { toolUseId: TOOL_USE_ID, agentType: "Explore", description: "Find the code" },
+            entries: [],
+          },
+        ],
+        parent: emptyParent(),
+        convertEntry: () => [],
+      })
+    ).observations;
 
     expect(observations).toEqual([]);
   });
 
-  it("falls back to the scraped link when there is no meta file", () => {
+  it("falls back to the scraped link when there is no meta file", async () => {
     const parent: ClaudeReplayParentFacts = {
       toolCalls: new Map([[TOOL_USE_ID, { title: "Explore" }]]),
-      linksByAgentId: new Map([[AGENT_ID, { toolCallId: TOOL_USE_ID, failed: false }]]),
-      outcomesByToolCallId: new Map(),
+      linksByAgentId: new Map([[AGENT_ID, { toolCallId: TOOL_USE_ID }]]),
+      outcomesByToolCallId: new Map([[TOOL_USE_ID, { status: "completed" }]]),
     };
 
-    const [declared, ...rest] = observeReplaySubagents({
-      subagents: [{ agentId: AGENT_ID, meta: null, entries: [] }],
-      parent,
-      convertEntry: () => [],
-    }).observations;
+    const [declared, ...rest] = (
+      await observeReplaySubagents({
+        subagents: [{ agentId: AGENT_ID, meta: null, entries: [] }],
+        parent,
+        convertEntry: () => [],
+      })
+    ).observations;
 
     expect(declared).toMatchObject({ id: TOOL_USE_ID, toolCallId: TOOL_USE_ID, title: "Explore" });
     expect(rest.at(-1)).toMatchObject({ kind: "status", status: "completed" });
   });
 
-  it("drops an unlinkable subagent", () => {
-    const observations = observeReplaySubagents({
-      subagents: [{ agentId: AGENT_ID, meta: null, entries: [] }],
-      parent: emptyParent(),
-      convertEntry: () => [],
-    }).observations;
+  it("drops an unlinkable subagent", async () => {
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [{ agentId: AGENT_ID, meta: null, entries: [] }],
+        parent: emptyParent(),
+        convertEntry: () => [],
+      })
+    ).observations;
     expect(observations).toEqual([]);
   });
 
-  it("drops a terminal subagent the parent has no Task call for", () => {
+  it("drops a terminal subagent the parent has no Task call for", async () => {
     // A legacy grandchild: its toolUseId names a Task call made inside a sibling's transcript, so
     // no tool_result for it can ever reach the parent. Left running, it never stops.
     const descriptor = applyToStore(
-      observeReplaySubagents({
-        subagents: [
-          {
-            agentId: AGENT_ID,
-            meta: { toolUseId: TOOL_USE_ID },
-            entries: [
-              {
-                type: "assistant",
-                timestamp: "2026-07-31T03:41:00.000Z",
-                message: { stop_reason: "end_turn" },
-              },
-            ],
-          },
-        ],
-        parent: emptyParent(),
-        convertEntry: () => [],
-      }).observations,
+      (
+        await observeReplaySubagents({
+          subagents: [
+            {
+              agentId: AGENT_ID,
+              meta: { toolUseId: TOOL_USE_ID },
+              entries: [
+                {
+                  type: "assistant",
+                  timestamp: "2026-07-31T03:41:00.000Z",
+                  message: { stop_reason: "end_turn" },
+                },
+              ],
+            },
+          ],
+          parent: emptyParent(),
+          convertEntry: () => [],
+        })
+      ).observations,
     );
 
     expect(descriptor).toBeNull();
   });
 
-  it("drops a terminal skill-spawned subagent that has no link at all", () => {
+  it("drops a terminal skill-spawned subagent that has no link at all", async () => {
     // A /code-review run: no Task tool_use exists to name it, so its sidecar carries only
     // agentType and its id appears nowhere in the parent transcript.
     const descriptor = applyToStore(
-      observeReplaySubagents({
+      (
+        await observeReplaySubagents({
+          subagents: [
+            {
+              agentId: AGENT_ID,
+              meta: { agentType: "general-purpose" },
+              entries: [
+                {
+                  type: "assistant",
+                  timestamp: "2026-07-31T03:41:00.000Z",
+                  message: { stop_reason: "end_turn" },
+                },
+              ],
+            },
+          ],
+          parent: emptyParent(),
+          convertEntry: () => [],
+        })
+      ).observations,
+    );
+
+    expect(descriptor).toBeNull();
+  });
+
+  it("reports a scraped link's failure as failed", async () => {
+    const descriptor = applyToStore(
+      (
+        await observeReplaySubagents({
+          subagents: [{ agentId: AGENT_ID, meta: null, entries: [] }],
+          parent: {
+            toolCalls: new Map([[TOOL_USE_ID, { title: "Explore" }]]),
+            linksByAgentId: new Map([[AGENT_ID, { toolCallId: TOOL_USE_ID }]]),
+            outcomesByToolCallId: new Map([[TOOL_USE_ID, { status: "failed" }]]),
+          },
+          convertEntry: () => [],
+        })
+      ).observations,
+    );
+
+    expect(descriptor).toMatchObject({ id: TOOL_USE_ID, status: "failed" });
+  });
+
+  it("drops a non-terminal linkless subagent", async () => {
+    const observations = (
+      await observeReplaySubagents({
         subagents: [
           {
             agentId: AGENT_ID,
@@ -221,111 +329,81 @@ describe("observeReplaySubagents", () => {
               {
                 type: "assistant",
                 timestamp: "2026-07-31T03:41:00.000Z",
-                message: { stop_reason: "end_turn" },
+                message: { stop_reason: null },
               },
             ],
           },
         ],
         parent: emptyParent(),
         convertEntry: () => [],
-      }).observations,
-    );
-
-    expect(descriptor).toBeNull();
-  });
-
-  it("reports a scraped link's failure as failed", () => {
-    const descriptor = applyToStore(
-      observeReplaySubagents({
-        subagents: [{ agentId: AGENT_ID, meta: null, entries: [] }],
-        parent: {
-          toolCalls: new Map([[TOOL_USE_ID, { title: "Explore" }]]),
-          linksByAgentId: new Map([[AGENT_ID, { toolCallId: TOOL_USE_ID, failed: true }]]),
-          outcomesByToolCallId: new Map(),
-        },
-        convertEntry: () => [],
-      }).observations,
-    );
-
-    expect(descriptor).toMatchObject({ id: TOOL_USE_ID, status: "failed" });
-  });
-
-  it("drops a non-terminal linkless subagent", () => {
-    const observations = observeReplaySubagents({
-      subagents: [
-        {
-          agentId: AGENT_ID,
-          meta: { agentType: "general-purpose" },
-          entries: [
-            {
-              type: "assistant",
-              timestamp: "2026-07-31T03:41:00.000Z",
-              message: { stop_reason: null },
-            },
-          ],
-        },
-      ],
-      parent: emptyParent(),
-      convertEntry: () => [],
-    }).observations;
+      })
+    ).observations;
 
     expect(observations).toEqual([]);
   });
 
-  it("finishes a terminal Task child when the parent has not recorded its outcome", () => {
+  it("finishes a terminal Task child when the parent has not recorded its outcome", async () => {
     const descriptor = applyToStore(
-      observeReplaySubagents({
-        subagents: [
-          {
-            agentId: AGENT_ID,
-            meta: { toolUseId: TOOL_USE_ID },
-            entries: [
-              {
-                type: "assistant",
-                timestamp: "2026-07-31T03:41:00.000Z",
-                message: { stop_reason: "end_turn" },
-              },
-            ],
-          },
-        ],
-        parent: { ...parentWithTaskCall(), outcomesByToolCallId: new Map() },
-        convertEntry: () => [],
-      }).observations,
+      (
+        await observeReplaySubagents({
+          subagents: [
+            {
+              agentId: AGENT_ID,
+              meta: { toolUseId: TOOL_USE_ID },
+              entries: [
+                {
+                  type: "assistant",
+                  timestamp: "2026-07-31T03:41:00.000Z",
+                  message: { stop_reason: "end_turn" },
+                },
+              ],
+            },
+          ],
+          parent: { ...parentWithTaskCall(), outcomesByToolCallId: new Map() },
+          convertEntry: () => [],
+        })
+      ).observations,
     );
 
     expect(descriptor).toMatchObject({ status: "completed" });
   });
 
-  it("leaves a subagent with no recorded outcome running", () => {
-    const observations = observeReplaySubagents({
-      subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries: [] }],
-      parent: { ...parentWithTaskCall(), outcomesByToolCallId: new Map() },
-      convertEntry: () => [],
-    }).observations;
+  it("leaves a subagent with no recorded outcome running", async () => {
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries: [] }],
+        parent: { ...parentWithTaskCall(), outcomesByToolCallId: new Map() },
+        convertEntry: () => [],
+      })
+    ).observations;
     expect(observations.some((o) => o.kind === "status")).toBe(false);
   });
 
-  it("reports a failed outcome as failed", () => {
-    const observations = observeReplaySubagents({
-      subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries: [] }],
-      parent: parentWithTaskCall(true),
-      convertEntry: () => [],
-    }).observations;
+  it("reports a failed outcome as failed", async () => {
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries: [] }],
+        parent: parentWithTaskCall(true),
+        convertEntry: () => [],
+      })
+    ).observations;
     expect(observations.at(-1)).toMatchObject({ kind: "status", status: "failed" });
   });
 
-  it("carries entry timestamps onto timeline observations", () => {
-    const observations = observeReplaySubagents({
-      subagents: [
-        {
-          agentId: AGENT_ID,
-          meta: { toolUseId: TOOL_USE_ID },
-          entries: [{ type: "assistant", timestamp: "2026-07-26T06:27:47.034Z" }],
-        },
-      ],
-      parent: parentWithTaskCall(),
-      convertEntry: () => [{ type: "reasoning", text: "thinking" }],
-    }).observations;
+  it("carries entry timestamps onto timeline observations", async () => {
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [
+          {
+            agentId: AGENT_ID,
+            meta: { toolUseId: TOOL_USE_ID },
+            entries: [{ type: "assistant", timestamp: "2026-07-26T06:27:47.034Z" }],
+          },
+        ],
+        parent: parentWithTaskCall(),
+        convertEntry: () => [{ type: "reasoning", text: "thinking" }],
+      })
+    ).observations;
 
     expect(observations.find((observation) => observation.kind === "timeline")).toMatchObject({
       kind: "timeline",
@@ -336,18 +414,20 @@ describe("observeReplaySubagents", () => {
 });
 
 describe("replay runtime", () => {
-  it("reads the model and effort off the subagent's own transcript", () => {
-    const observations = observeReplaySubagents({
-      subagents: [
-        {
-          agentId: AGENT_ID,
-          meta: { toolUseId: TOOL_USE_ID },
-          entries: [{ type: "assistant", effort: "high", message: { model: "claude-opus-5" } }],
-        },
-      ],
-      parent: parentWithTaskCall(),
-      convertEntry: () => [],
-    }).observations;
+  it("reads the model and effort off the subagent's own transcript", async () => {
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [
+          {
+            agentId: AGENT_ID,
+            meta: { toolUseId: TOOL_USE_ID },
+            entries: [{ type: "assistant", effort: "high", message: { model: "claude-opus-5" } }],
+          },
+        ],
+        parent: parentWithTaskCall(),
+        convertEntry: () => [],
+      })
+    ).observations;
 
     expect(observations.find((o) => o.kind === "subtitle")).toEqual({
       kind: "subtitle",
@@ -356,49 +436,55 @@ describe("replay runtime", () => {
     });
   });
 
-  it("takes the last observed values when the model changes mid-transcript", () => {
-    const observations = observeReplaySubagents({
-      subagents: [
-        {
-          agentId: AGENT_ID,
-          meta: { toolUseId: TOOL_USE_ID },
-          entries: [
-            { type: "assistant", effort: "high", message: { model: "claude-opus-5" } },
-            { type: "assistant", effort: "low", message: { model: "claude-sonnet-5" } },
-          ],
-        },
-      ],
-      parent: parentWithTaskCall(),
-      convertEntry: () => [],
-    }).observations;
+  it("takes the last observed values when the model changes mid-transcript", async () => {
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [
+          {
+            agentId: AGENT_ID,
+            meta: { toolUseId: TOOL_USE_ID },
+            entries: [
+              { type: "assistant", effort: "high", message: { model: "claude-opus-5" } },
+              { type: "assistant", effort: "low", message: { model: "claude-sonnet-5" } },
+            ],
+          },
+        ],
+        parent: parentWithTaskCall(),
+        convertEntry: () => [],
+      })
+    ).observations;
 
     expect(observations.find((o) => o.kind === "subtitle")).toMatchObject({
       subtitle: "general-purpose · Sonnet 5 · Low",
     });
   });
 
-  it("reports nothing when the transcript never names a model or effort", () => {
-    const observations = observeReplaySubagents({
-      subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries: [] }],
-      parent: parentWithTaskCall(),
-      convertEntry: () => [],
-    }).observations;
+  it("reports nothing when the transcript never names a model or effort", async () => {
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries: [] }],
+        parent: parentWithTaskCall(),
+        convertEntry: () => [],
+      })
+    ).observations;
     expect(observations.some((o) => o.kind === "subtitle")).toBe(false);
   });
 
-  it("passes through a model the manifest does not know", () => {
+  it("passes through a model the manifest does not know", async () => {
     // Claude Code is an Anthropic-compatible client; subagents legitimately report other models.
-    const observations = observeReplaySubagents({
-      subagents: [
-        {
-          agentId: AGENT_ID,
-          meta: { toolUseId: TOOL_USE_ID },
-          entries: [{ type: "assistant", message: { model: "glm-5.1" } }],
-        },
-      ],
-      parent: parentWithTaskCall(),
-      convertEntry: () => [],
-    }).observations;
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [
+          {
+            agentId: AGENT_ID,
+            meta: { toolUseId: TOOL_USE_ID },
+            entries: [{ type: "assistant", message: { model: "glm-5.1" } }],
+          },
+        ],
+        parent: parentWithTaskCall(),
+        convertEntry: () => [],
+      })
+    ).observations;
     expect(observations.find((o) => o.kind === "subtitle")).toMatchObject({
       subtitle: "general-purpose · glm-5.1",
     });
@@ -406,20 +492,24 @@ describe("replay runtime", () => {
 });
 
 describe("replay usage", () => {
-  function subtitleOf(entries: ClaudeReplayEntry[]): SubagentObservation | undefined {
-    return observeReplaySubagents({
-      subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries }],
-      parent: parentWithTaskCall(),
-      convertEntry: () => [],
-    }).observations.find((observation) => observation.kind === "subtitle");
+  async function subtitleOf(
+    entries: ClaudeReplayEntry[],
+  ): Promise<SubagentObservation | undefined> {
+    return (
+      await observeReplaySubagents({
+        subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries }],
+        parent: parentWithTaskCall(),
+        convertEntry: () => [],
+      })
+    ).observations.find((observation) => observation.kind === "subtitle");
   }
 
-  it("derives the counters Claude Code itself reports, from a real transcript's shape", () => {
+  it("derives the counters Claude Code itself reports, from a real transcript's shape", async () => {
     // Shape and numbers taken from an on-disk subagent transcript. Claude Code finalizes a
     // subagent from the LAST assistant entry's usage, so the earlier, smaller turn must not win
     // and must not be added in.
     expect(
-      subtitleOf([
+      await subtitleOf([
         {
           type: "assistant",
           timestamp: "2026-07-23T23:18:43.023Z",
@@ -462,9 +552,9 @@ describe("replay usage", () => {
     });
   });
 
-  it("formats tokens for a child that only answered", () => {
+  it("formats tokens for a child that only answered", async () => {
     expect(
-      subtitleOf([
+      await subtitleOf([
         {
           type: "assistant",
           timestamp: "2026-07-27T16:42:14.698Z",
@@ -479,12 +569,12 @@ describe("replay usage", () => {
     ).toMatchObject({ subtitle: "general-purpose · 16.4k tokens" });
   });
 
-  it("emits nothing for a transcript with no entries", () => {
-    expect(subtitleOf([])).toBeUndefined();
+  it("emits nothing for a transcript with no entries", async () => {
+    expect(await subtitleOf([])).toBeUndefined();
   });
 
-  it("keeps duration out of the compact subtitle", () => {
-    const observation = subtitleOf([
+  it("keeps duration out of the compact subtitle", async () => {
+    const observation = await subtitleOf([
       {
         type: "assistant",
         timestamp: "2026-07-27T16:42:14.698Z",
@@ -494,8 +584,8 @@ describe("replay usage", () => {
     expect(observation).toMatchObject({ subtitle: "general-purpose · 10 tokens" });
   });
 
-  it("omits totalTokens when no entry carries a usage block", () => {
-    const observation = subtitleOf([
+  it("omits totalTokens when no entry carries a usage block", async () => {
+    const observation = await subtitleOf([
       { type: "assistant", timestamp: "2026-07-27T16:42:14.698Z", message: { content: [] } },
       {
         type: "assistant",
@@ -506,9 +596,9 @@ describe("replay usage", () => {
     expect(observation).toBeUndefined();
   });
 
-  it("keeps the last usage-bearing entry when the final assistant entry has none", () => {
+  it("keeps the last usage-bearing entry when the final assistant entry has none", async () => {
     expect(
-      subtitleOf([
+      await subtitleOf([
         {
           type: "assistant",
           timestamp: "2026-07-27T16:42:14.698Z",
@@ -519,34 +609,36 @@ describe("replay usage", () => {
     ).toMatchObject({ subtitle: "general-purpose · 1k tokens" });
   });
 
-  it("only reports counters the transcript actually shows", () => {
+  it("only reports counters the transcript actually shows", async () => {
     // A user-only transcript says nothing about cost: no assistant turn, so no tool count either.
-    const observation = subtitleOf([
+    const observation = await subtitleOf([
       { type: "user", timestamp: "2026-07-27T16:42:14.698Z", message: { content: "prompt" } },
       { type: "user", timestamp: "2026-07-27T16:42:20.000Z", message: { content: "more" } },
     ]);
     expect(observation).toBeUndefined();
   });
 
-  it("lands the complete provider-owned subtitle on the descriptor", () => {
+  it("lands the complete provider-owned subtitle on the descriptor", async () => {
     const store = new ProviderSubagentStore();
-    const observations = observeReplaySubagents({
-      subagents: [
-        {
-          agentId: AGENT_ID,
-          meta: { toolUseId: TOOL_USE_ID },
-          entries: [
-            {
-              type: "assistant",
-              timestamp: "2026-07-27T16:42:14.698Z",
-              message: { content: [], usage: { input_tokens: 7 } },
-            },
-          ],
-        },
-      ],
-      parent: parentWithTaskCall(),
-      convertEntry: () => [],
-    }).observations;
+    const observations = (
+      await observeReplaySubagents({
+        subagents: [
+          {
+            agentId: AGENT_ID,
+            meta: { toolUseId: TOOL_USE_ID },
+            entries: [
+              {
+                type: "assistant",
+                timestamp: "2026-07-27T16:42:14.698Z",
+                message: { content: [], usage: { input_tokens: 7 } },
+              },
+            ],
+          },
+        ],
+        parent: parentWithTaskCall(),
+        convertEntry: () => [],
+      })
+    ).observations;
     for (const event of foldSubagentObservations(observations)) {
       store.apply("parent", "claude", event);
     }
@@ -559,7 +651,7 @@ describe("live and replay agree", () => {
   // The property the design exists to guarantee: one session, two sources, one descriptor.
   // This is inexpressible against the inference implementation, where the paths share no
   // vocabulary and each derives identity and status its own way.
-  it("produces identical descriptor state from the wire and from disk", () => {
+  it("produces identical descriptor state from the wire and from disk", async () => {
     const live = new ClaudeTaskProtocolSource();
     const liveObservations = [
       ...live.observe({
@@ -579,21 +671,23 @@ describe("live and replay agree", () => {
       } as unknown as SDKMessage),
     ];
 
-    const replayObservations = observeReplaySubagents({
-      subagents: [
-        {
-          agentId: AGENT_ID,
-          meta: {
-            toolUseId: TOOL_USE_ID,
-            agentType: "general-purpose",
-            description: "Summarize hover and unistyles docs",
+    const replayObservations = (
+      await observeReplaySubagents({
+        subagents: [
+          {
+            agentId: AGENT_ID,
+            meta: {
+              toolUseId: TOOL_USE_ID,
+              agentType: "general-purpose",
+              description: "Summarize hover and unistyles docs",
+            },
+            entries: [],
           },
-          entries: [],
-        },
-      ],
-      parent: parentWithTaskCall(),
-      convertEntry: () => [],
-    }).observations;
+        ],
+        parent: parentWithTaskCall(),
+        convertEntry: () => [],
+      })
+    ).observations;
 
     const fromWire = applyToStore(liveObservations);
     const fromDisk = applyToStore(replayObservations);
@@ -616,3 +710,34 @@ describe("live and replay agree", () => {
     });
   });
 });
+
+it("awaits image materialization before publishing replay observations", async () => {
+  const bytes = Buffer.from("async replay image fixture");
+  const convertEntry = async () => {
+    const item = await renderProviderImageOutputAsAssistantMarkdown(
+      { data: bytes.toString("base64"), mimeType: "image/png" },
+      { materialize: materializeProviderImage },
+    );
+    return item ? [item] : [];
+  };
+  const { observations } = await observeReplaySubagents({
+    parent: parentWithTaskCall(),
+    subagents: [
+      {
+        agentId: AGENT_ID,
+        meta: { toolUseId: TOOL_USE_ID },
+        entries: [{ type: "assistant", message: { content: [] } }],
+      },
+    ],
+    convertEntry,
+  });
+  const image = observations.find(
+    (observation) =>
+      observation.kind === "timeline" && observation.item.type === "assistant_message",
+  );
+  if (!image || image.kind !== "timeline" || image.item.type !== "assistant_message")
+    throw new Error("Expected replay image");
+  const source = image.item.text.match(/!\[Image\]\(([^)]+)\)/)?.[1];
+  expect(source).toBeTruthy();
+  expect(await readFile(fileURLToPath(source!))).toEqual(bytes);
+});
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 23ba35c0fe..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
@@ -3,7 +3,9 @@ import { z } from "zod";
 import type { AgentTimelineItem } from "../../../agent-sdk-types.js";
 import { normalizeProviderReplayTimestamp } from "../../../provider-history-timestamps.js";
 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";
 
@@ -130,7 +132,7 @@ function readUsage(entry: ClaudeReplayEntry): ClaudeSubagentUsage | null {
 export interface ClaudeReplaySubagentInput {
   agentId: string;
   meta: ClaudeSubagentMeta | null;
-  entries: Iterable<ClaudeReplayEntry>;
+  entries: Iterable<ClaudeReplayEntry> | AsyncIterable<ClaudeReplayEntry>;
   /** Task declarations made by this subagent, used to attach its direct children. */
   parentFacts?: ClaudeReplayParentFacts;
 }
@@ -139,9 +141,12 @@ export interface ClaudeReplayParentFacts {
   /** Task `tool_use` id -> identity declared in the parent's tool input. */
   toolCalls: ReadonlyMap<string, { title?: string; description?: string }>;
   /** agentId -> tool call, recovered by scraping tool-result text. Legacy fallback only. */
-  linksByAgentId: ReadonlyMap<string, { toolCallId: string; failed: boolean }>;
-  /** Task `tool_use` id -> outcome. Usable once meta.json supplies the link directly. */
-  outcomesByToolCallId: ReadonlyMap<string, { failed: boolean }>;
+  linksByAgentId: ReadonlyMap<string, { toolCallId: string }>;
+  /**
+   * Task `tool_use` id -> outcome, whichever way the child was linked. A background launch has
+   * none: its immediate result only says the child started.
+   */
+  outcomesByToolCallId: ReadonlyMap<string, { status: ProviderSubagentStatus }>;
 }
 
 interface ParentLink {
@@ -177,27 +182,14 @@ function resolveParentLink(
   parent: ClaudeReplayParentFacts,
 ): ParentLink | null {
   const metaToolUseId = subagent.meta?.toolUseId?.trim();
-  if (metaToolUseId && parent.toolCalls.has(metaToolUseId)) {
-    const outcome = parent.outcomesByToolCallId.get(metaToolUseId);
-    let status: ProviderSubagentStatus | null = null;
-    if (outcome) status = outcome.failed ? "failed" : "completed";
-    return {
-      id: metaToolUseId,
-      toolCallId: metaToolUseId,
-      status,
-    };
-  }
+  const toolCallId =
+    metaToolUseId && parent.toolCalls.has(metaToolUseId)
+      ? metaToolUseId
+      : parent.linksByAgentId.get(subagent.agentId)?.toolCallId;
+  if (!toolCallId || !parent.toolCalls.has(toolCallId)) return null;
 
-  const scraped = parent.linksByAgentId.get(subagent.agentId);
-  if (scraped && parent.toolCalls.has(scraped.toolCallId)) {
-    return {
-      id: scraped.toolCallId,
-      toolCallId: scraped.toolCallId,
-      status: scraped.failed ? "failed" : "completed",
-    };
-  }
-
-  return null;
+  const status = parent.outcomesByToolCallId.get(toolCallId)?.status ?? null;
+  return { id: toolCallId, toolCallId, status };
 }
 
 /**
@@ -250,13 +242,14 @@ function observeSubtitle(
   };
 }
 
-function observeSubagent(
+async function observeSubagent(
   subagent: ClaudeReplaySubagentInput,
   parent: ClaudeReplayParentFacts,
-  convertEntry: (entry: ClaudeReplayEntry) => AgentTimelineItem[],
+  convertEntry: (entry: ClaudeReplayEntry) => AgentTimelineItem[] | Promise<AgentTimelineItem[]>,
   toolOwners: Map<string, string>,
+  restored: ClaudeRestoredSubagent[],
   parentSubagentId?: string,
-): SubagentObservation[] {
+): Promise<SubagentObservation[]> {
   const link = resolveParentLink(subagent, parent);
   if (!link) return [];
   const toolCall = parent.toolCalls.get(link.toolCallId);
@@ -269,31 +262,30 @@ function observeSubagent(
   let childTerminalStatus: ProviderSubagentStatus | null = null;
 
   // Consume each source once for presentation and timeline; keep no raw transcript records.
-  for (const entry of subagent.entries) {
+  for await (const entry of subagent.entries) {
     const timestamp = normalizeProviderReplayTimestamp(entry.timestamp);
     if (!seenEntry) firstTimestamp = timestamp;
     seenEntry = true;
     lastTimestamp = timestamp;
     Object.assign(runtime, readRuntime(entry));
     usage = readUsage(entry) ?? usage;
-    if (entry.type === "assistant") {
-      childTerminalStatus = entry.message?.stop_reason === "end_turn" ? "completed" : null;
-    }
+    childTerminalStatus = readChildTerminalStatus(entry, childTerminalStatus);
     recordReplayToolOwners(toolOwners, entry, link.id);
-    for (const item of convertEntry(entry)) {
+    for (const item of await convertEntry(entry)) {
       timeline.push({ kind: "timeline", id: link.id, item, ...(timestamp ? { timestamp } : {}) });
     }
   }
   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;
@@ -308,6 +300,30 @@ function observeSubagent(
   return observations;
 }
 
+/** Advance the child's fallback outcome without retaining transcript entries. */
+function readChildTerminalStatus(
+  entry: ClaudeReplayEntry,
+  previous: ProviderSubagentStatus | null,
+): ProviderSubagentStatus | null {
+  if (entry.type === "assistant") {
+    return entry.message?.stop_reason === "end_turn" ? "completed" : null;
+  }
+  if (entry.type !== "user") return previous;
+  const texts = readUserTexts(entry);
+  if (texts.length === 0) return previous;
+  return texts.some(isClaudeInterruptPlaceholderText) ? "canceled" : null;
+}
+
+/** Tool results carry no user text and do not change the child's terminal status. */
+function readUserTexts(entry: ClaudeReplayEntry): string[] {
+  const content = entry.message?.content;
+  if (typeof content === "string") return [content];
+  if (!Array.isArray(content)) return [];
+  return content.flatMap((block: { type?: unknown; text?: unknown } | null) =>
+    block?.type === "text" && typeof block.text === "string" ? [block.text] : [],
+  );
+}
+
 function recordReplayToolOwners(
   owners: Map<string, string>,
   entry: ClaudeReplayEntry,
@@ -320,13 +336,18 @@ function recordReplayToolOwners(
   }
 }
 
-export function observeReplaySubagents(input: {
+export async function observeReplaySubagents(input: {
   subagents: readonly ClaudeReplaySubagentInput[];
   parent: ClaudeReplayParentFacts;
-  convertEntry: (entry: ClaudeReplayEntry) => AgentTimelineItem[];
-}): { observations: SubagentObservation[]; toolOwners: ReadonlyMap<string, string> } {
+  convertEntry: (entry: ClaudeReplayEntry) => AgentTimelineItem[] | Promise<AgentTimelineItem[]>;
+}): 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),
   );
@@ -346,11 +367,12 @@ export function observeReplaySubagents(input: {
       const { ownerId, parent, link } = resolved;
 
       // Only proven descendants may own notifications; ambient sidecars cannot claim them.
-      for (const observation of observeSubagent(
+      for (const observation of await observeSubagent(
         subagent,
         parent,
         input.convertEntry,
         toolOwners,
+        restored,
         ownerId,
       )) {
         observations.push(observation);
@@ -360,7 +382,7 @@ export function observeReplaySubagents(input: {
       madeProgress = true;
     }
   }
-  return { observations, toolOwners };
+  return { observations, toolOwners, restored };
 }
 
 function resolveReplayOwner(
diff --git a/packages/server/src/server/agent/providers/claude/subagents/task-status.ts b/packages/server/src/server/agent/providers/claude/subagents/task-status.ts
new file mode 100644
index 0000000000..a488ce12d7
--- /dev/null
+++ b/packages/server/src/server/agent/providers/claude/subagents/task-status.ts
@@ -0,0 +1,23 @@
+import type { ProviderSubagentStatus } from "../../../provider-subagents/store.js";
+
+/**
+ * The descriptor has no paused or pending state, and neither is terminal, so both read as
+ * running. `killed` is a cancellation, not a failure — the child was stopped, it did not error.
+ */
+export function mapTaskStatus(status: string | undefined): ProviderSubagentStatus | undefined {
+  switch (status) {
+    case "pending":
+    case "running":
+    case "paused":
+      return "running";
+    case "completed":
+      return "completed";
+    case "failed":
+      return "failed";
+    case "killed":
+    case "stopped":
+      return "canceled";
+    default:
+      return undefined;
+  }
+}
diff --git a/packages/server/src/server/agent/providers/claude/subagents/workflow-replay-source.test.ts b/packages/server/src/server/agent/providers/claude/subagents/workflow-replay-source.test.ts
index 59e1f23557..edb673c664 100644
--- a/packages/server/src/server/agent/providers/claude/subagents/workflow-replay-source.test.ts
+++ b/packages/server/src/server/agent/providers/claude/subagents/workflow-replay-source.test.ts
@@ -1,3 +1,9 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import {
+  materializeProviderImage,
+  renderProviderImageOutputAsAssistantMarkdown,
+} from "../../provider-image-output.js";
 import { describe, expect, it } from "vitest";
 
 import { ProviderSubagentStore } from "../../../provider-subagents/store.js";
@@ -35,7 +41,7 @@ function parentEntries(
 }
 
 describe("Claude workflow replay", () => {
-  it("parses the persisted run summary observed from Claude Code 2.1.220", () => {
+  it("parses the persisted run summary observed from Claude Code 2.1.220", async () => {
     expect(
       parseClaudeWorkflowRun(
         JSON.stringify({
@@ -62,8 +68,8 @@ describe("Claude workflow replay", () => {
     });
   });
 
-  it("rebuilds the same generic completed descriptor through the parent Workflow call", () => {
-    const observations = observeReplayWorkflows({
+  it("rebuilds the same generic completed descriptor through the parent Workflow call", async () => {
+    const observations = await observeReplayWorkflows({
       workflows: [
         {
           runId: RUN_ID,
@@ -91,8 +97,8 @@ describe("Claude workflow replay", () => {
     });
   });
 
-  it("rebuilds a workflow when Claude persists its result as structured text blocks", () => {
-    const observations = observeReplayWorkflows({
+  it("rebuilds a workflow when Claude persists its result as structured text blocks", async () => {
+    const observations = await observeReplayWorkflows({
       workflows: [{ runId: RUN_ID, summary: "Structured result workflow", status: "completed" }],
       parentEntries: parentEntries([
         {
@@ -114,7 +120,7 @@ describe("Claude workflow replay", () => {
     });
   });
 
-  it("replays the workflow result without exposing its script or child prompt", () => {
+  it("replays the workflow result without exposing its script or child prompt", async () => {
     const workflow = parseClaudeWorkflowRun(
       JSON.stringify({
         runId: RUN_ID,
@@ -128,7 +134,7 @@ describe("Claude workflow replay", () => {
     expect(workflow).not.toBeNull();
     if (!workflow) throw new Error("expected workflow");
 
-    const observations = observeReplayWorkflows({
+    const observations = await observeReplayWorkflows({
       workflows: [workflow],
       parentEntries: parentEntries(),
     });
@@ -145,9 +151,9 @@ describe("Claude workflow replay", () => {
     expect(JSON.stringify(observations)).not.toContain("SECRET CHILD PROMPT");
   });
 
-  it("does not duplicate a result already present in the child transcript", () => {
+  it("does not duplicate a result already present in the child transcript", async () => {
     const report = "What Paseo is\nA local-first coding-agent environment.";
-    const observations = observeReplayWorkflows({
+    const observations = await observeReplayWorkflows({
       workflows: [
         { runId: RUN_ID, summary: "Inspect Paseo", status: "completed", result: { report } },
       ],
@@ -166,8 +172,8 @@ describe("Claude workflow replay", () => {
     ).toHaveLength(1);
   });
 
-  it("fails a nonterminal persisted run because its former runtime cannot update it", () => {
-    const observations = observeReplayWorkflows({
+  it("fails a nonterminal persisted run because its former runtime cannot update it", async () => {
+    const observations = await observeReplayWorkflows({
       workflows: [{ runId: RUN_ID, summary: "Interrupted workflow", status: "running" }],
       parentEntries: parentEntries(),
     });
@@ -179,9 +185,9 @@ describe("Claude workflow replay", () => {
     });
   });
 
-  it("drops a run that no parent Workflow tool call declared", () => {
+  it("drops a run that no parent Workflow tool call declared", async () => {
     expect(
-      observeReplayWorkflows({
+      await observeReplayWorkflows({
         workflows: [{ runId: RUN_ID, status: "completed" }],
         parentEntries: [],
       }),
@@ -195,3 +201,29 @@ describe("Claude workflow replay", () => {
     },
   );
 });
+
+it("awaits image materialization before publishing replay observations", async () => {
+  const bytes = Buffer.from("async replay image fixture");
+  const convertEntry = async () => {
+    const item = await renderProviderImageOutputAsAssistantMarkdown(
+      { data: bytes.toString("base64"), mimeType: "image/png" },
+      { materialize: materializeProviderImage },
+    );
+    return item ? [item] : [];
+  };
+  const observations = await observeReplayWorkflows({
+    workflows: [{ runId: RUN_ID, status: "completed" }],
+    parentEntries: parentEntries(),
+    entriesByRunId: new Map([[RUN_ID, [{ type: "assistant", message: { content: [] } }]]]),
+    convertEntry,
+  });
+  const image = observations.find(
+    (observation) =>
+      observation.kind === "timeline" && observation.item.type === "assistant_message",
+  );
+  if (!image || image.kind !== "timeline" || image.item.type !== "assistant_message")
+    throw new Error("Expected replay image");
+  const source = image.item.text.match(/!\[Image\]\(([^)]+)\)/)?.[1];
+  expect(source).toBeTruthy();
+  expect(await readFile(fileURLToPath(source!))).toEqual(bytes);
+});
diff --git a/packages/server/src/server/agent/providers/claude/subagents/workflow-replay-source.ts b/packages/server/src/server/agent/providers/claude/subagents/workflow-replay-source.ts
index 1d7ff2b1a8..17a278d00f 100644
--- a/packages/server/src/server/agent/providers/claude/subagents/workflow-replay-source.ts
+++ b/packages/server/src/server/agent/providers/claude/subagents/workflow-replay-source.ts
@@ -45,14 +45,17 @@ export function parseClaudeWorkflowRun(contents: string): ClaudeWorkflowRun | nu
  * provider runtime was recreated, so replay terminalizes it as failed instead of resurrecting a
  * row that can never receive another update.
  */
-export function observeReplayWorkflows(input: {
+export async function observeReplayWorkflows(input: {
   workflows: readonly ClaudeWorkflowRun[];
-  parentEntries: Iterable<ClaudeWorkflowParentEntry>;
+  parentEntries: Iterable<ClaudeWorkflowParentEntry> | AsyncIterable<ClaudeWorkflowParentEntry>;
   /** Repeatable entries in chronological order, supplied by the transcript reader. */
-  entriesByRunId?: ReadonlyMap<string, Iterable<ClaudeReplayEntry>>;
-  convertEntry?: (entry: ClaudeReplayEntry) => AgentTimelineItem[];
-}): SubagentObservation[] {
-  const toolCallIdByRunId = readWorkflowLinks(input.parentEntries);
+  entriesByRunId?: ReadonlyMap<
+    string,
+    Iterable<ClaudeReplayEntry> | AsyncIterable<ClaudeReplayEntry>
+  >;
+  convertEntry?: (entry: ClaudeReplayEntry) => AgentTimelineItem[] | Promise<AgentTimelineItem[]>;
+}): Promise<SubagentObservation[]> {
+  const toolCallIdByRunId = await readWorkflowLinks(input.parentEntries);
   const observations: SubagentObservation[] = [];
 
   for (const workflow of input.workflows) {
@@ -79,7 +82,7 @@ export function observeReplayWorkflows(input: {
       });
     }
 
-    for (const observation of observeWorkflowTimeline({
+    for (const observation of await observeWorkflowTimeline({
       id,
       result: workflow.result,
       entries: input.entriesByRunId?.get(workflow.runId) ?? [],
@@ -115,19 +118,19 @@ export function observeReplayWorkflows(input: {
   return observations;
 }
 
-function observeWorkflowTimeline(input: {
+async function observeWorkflowTimeline(input: {
   id: string;
   result: unknown;
-  entries: Iterable<ClaudeReplayEntry>;
-  convertEntry?: (entry: ClaudeReplayEntry) => AgentTimelineItem[];
+  entries: Iterable<ClaudeReplayEntry> | AsyncIterable<ClaudeReplayEntry>;
+  convertEntry?: (entry: ClaudeReplayEntry) => AgentTimelineItem[] | Promise<AgentTimelineItem[]>;
   finishedAt?: string;
-}): SubagentObservation[] {
+}): Promise<SubagentObservation[]> {
   const observations: SubagentObservation[] = [];
   const replayedAssistantText = new Set<string>();
 
-  for (const entry of input.entries) {
+  for await (const entry of input.entries) {
     const timestamp = normalizeProviderReplayTimestamp(entry.timestamp);
-    const items = input.convertEntry?.(entry) ?? [];
+    const items = (await input.convertEntry?.(entry)) ?? [];
     for (const item of items) {
       if (item.type === "assistant_message") replayedAssistantText.add(item.text.trim());
       observations.push({
@@ -150,11 +153,13 @@ function observeWorkflowTimeline(input: {
   return observations;
 }
 
-function readWorkflowLinks(entries: Iterable<ClaudeWorkflowParentEntry>): Map<string, string> {
+async function readWorkflowLinks(
+  entries: Iterable<ClaudeWorkflowParentEntry> | AsyncIterable<ClaudeWorkflowParentEntry>,
+): Promise<Map<string, string>> {
   const workflowToolCallIds = new Set<string>();
   const toolCallIdByRunId = new Map<string, string>();
 
-  for (const entry of entries) {
+  for await (const entry of entries) {
     const content = entry.message?.content;
     if (!Array.isArray(content)) continue;
     for (const value of content) {
@@ -165,7 +170,7 @@ function readWorkflowLinks(entries: Iterable<ClaudeWorkflowParentEntry>): Map<st
     }
   }
 
-  for (const entry of entries) {
+  for await (const entry of entries) {
     const content = entry.message?.content;
     if (!Array.isArray(content)) continue;
     for (const value of content) {
diff --git a/packages/server/src/server/agent/providers/claude/task-notification-tool-call.ts b/packages/server/src/server/agent/providers/claude/task-notification-tool-call.ts
index b269be70eb..76ad89d8ef 100644
--- a/packages/server/src/server/agent/providers/claude/task-notification-tool-call.ts
+++ b/packages/server/src/server/agent/providers/claude/task-notification-tool-call.ts
@@ -221,9 +221,11 @@ function parseTaskNotificationFromSystemRecord(record: unknown): TaskNotificatio
 /** Normalize notification identity for one transcript traversal. Queue bookkeeping and delivery
  * are separate records of the same occurrence; each source counts repeated identical bodies
  * independently so the second event is not merged with the first. */
-export function* assignTaskNotificationReplayIds<T>(entries: Iterable<T>): Generator<T> {
+export async function* assignTaskNotificationReplayIds<T>(
+  entries: AsyncIterable<T>,
+): AsyncGenerator<T> {
   const occurrences = new Map<string, Map<string, number>>();
-  for (const entry of entries) {
+  for await (const entry of entries) {
     const record = TaskNotificationHistoryRecordSchema.safeParse(entry);
     if (!record.success) {
       yield entry;
@@ -405,19 +407,21 @@ export function mapTaskNotificationSystemRecordToToolCall(
 }
 
 export function readTaskNotificationToolUseIdFromHistoryRecord(record: unknown): string | null {
+  return readTaskNotificationFromHistoryRecord(record)?.toolUseId ?? null;
+}
+
+export function readTaskNotificationFromHistoryRecord(
+  record: unknown,
+): TaskNotificationEnvelope | null {
   const parsedRecord = TaskNotificationHistoryRecordSchema.safeParse(record);
-  if (!parsedRecord.success) {
-    return null;
-  }
+  if (!parsedRecord.success) return null;
   if (parsedRecord.data.type === "user" && parsedRecord.data.message) {
-    return (
-      parseTaskNotificationFromUserContent({
-        content: parsedRecord.data.message.content,
-        messageId: parsedRecord.data.uuid ?? parsedRecord.data.message_id,
-      })?.toolUseId ?? null
-    );
+    return parseTaskNotificationFromUserContent({
+      content: parsedRecord.data.message.content,
+      messageId: parsedRecord.data.uuid ?? parsedRecord.data.message_id,
+    });
   }
-  return parseTaskNotificationFromSystemRecord(record)?.toolUseId ?? null;
+  return parseTaskNotificationFromSystemRecord(record);
 }
 
 export function coerceTaskNotificationHistoryRecordToSystemMessage(
diff --git a/packages/server/src/server/agent/providers/claude/transcript-history.ts b/packages/server/src/server/agent/providers/claude/transcript-history.ts
index f8663f83d0..09882b76dd 100644
--- a/packages/server/src/server/agent/providers/claude/transcript-history.ts
+++ b/packages/server/src/server/agent/providers/claude/transcript-history.ts
@@ -1,5 +1,6 @@
 import { assignTaskNotificationReplayIds } from "./task-notification-tool-call.js";
-import fs from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+import { setImmediate } from "node:timers/promises";
 import path from "node:path";
 import { normalizeProviderReplayTimestamp } from "../../provider-history-timestamps.js";
 import {
@@ -24,11 +25,11 @@ interface RecordLocation {
 }
 
 /** Chunk in bytes so UTF-8 and multi-chunk records are decoded once, at a line boundary. */
-function* locatedRecords(
+async function* locatedRecords(
   file: string,
-  fd: number,
-): Generator<{ entry: TranscriptEntry; location: RecordLocation }> {
-  const stat = fs.fstatSync(fd);
+  fd: FileHandle,
+): AsyncGenerator<{ entry: TranscriptEntry; location: RecordLocation }> {
+  const stat = await fd.stat();
   // Opening a directory succeeds on some platforms; it must never look like empty history.
   if (stat.isDirectory()) {
     throw Object.assign(new Error(`EISDIR: illegal operation on a directory, read '${file}'`), {
@@ -43,7 +44,7 @@ function* locatedRecords(
   let length = 0;
   while (remaining > 0) {
     const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, remaining));
-    const count = fs.readSync(fd, buffer, 0, buffer.length, null);
+    const { bytesRead: count } = await fd.read(buffer, 0, buffer.length, null);
     if (count === 0) break;
     remaining -= count;
     let start = 0;
@@ -64,6 +65,8 @@ function* locatedRecords(
       if (entry) yield { entry, location };
       start = end + 1;
     }
+    // Bound parsing work as well as IO; microtasks alone do not service timers or sockets.
+    await setImmediate();
     if (start < count) {
       pieces.push(buffer.subarray(start, count));
       length += count - start;
@@ -85,20 +88,25 @@ function* locatedRecords(
 /** Indexed sources parse only their own records using descriptors owned by this replay. */
 function indexedRecords(
   locations: readonly RecordLocation[],
-  descriptors: ReadonlyMap<string, number>,
-): Iterable<TranscriptEntry> {
+  descriptors: ReadonlyMap<string, FileHandle>,
+): AsyncIterable<TranscriptEntry> {
   return {
-    *[Symbol.iterator]() {
+    async *[Symbol.asyncIterator]() {
       yield* assignTaskNotificationReplayIds(readEntries());
     },
   };
-  function* readEntries(): Generator<TranscriptEntry> {
+  async function* readEntries(): AsyncGenerator<TranscriptEntry> {
     for (const location of locations) {
       const fd = descriptors.get(location.file)!;
       const buffer = Buffer.allocUnsafe(location.length);
       let read = 0;
       while (read < buffer.length) {
-        const count = fs.readSync(fd, buffer, read, buffer.length - read, location.offset + read);
+        const { bytesRead: count } = await fd.read(
+          buffer,
+          read,
+          buffer.length - read,
+          location.offset + read,
+        );
         if (count === 0)
           throw new Error(`Claude transcript was truncated during replay: ${location.file}`);
         read += count;
@@ -127,9 +135,9 @@ function parseRecord(line: string): TranscriptEntry | null {
   }
 }
 
-function readOptionalFile(file: string): string | null {
+async function readOptionalFile(file: string): Promise<string | null> {
   try {
-    return fs.readFileSync(file, "utf8");
+    return await fs.readFile(file, "utf8");
   } catch {
     return null;
   }
@@ -138,31 +146,40 @@ function readOptionalFile(file: string): string | null {
 /** Discover sources without retaining transcript contents. Unrelated sidechains stay excluded
  * by the replay ownership resolver; workflow children retain their separate run ownership. */
 export interface ClaudeReplayHistory {
-  parentEntries: Iterable<TranscriptEntry>;
+  parentEntries: AsyncIterable<TranscriptEntry>;
   subagents: {
     agentId: string;
     meta: ClaudeSubagentMeta | null;
-    entries: Iterable<TranscriptEntry>;
+    entries: AsyncIterable<TranscriptEntry>;
   }[];
   workflows: ClaudeWorkflowRun[];
-  workflowEntriesByRunId: Map<string, Iterable<TranscriptEntry>>;
+  workflowEntriesByRunId: Map<string, AsyncIterable<TranscriptEntry>>;
 }
 
 /** Own descriptors through every pass so unlink or rename cannot invalidate discovered history.
  * Sources must be consumed before the callback returns. No transcript copies are needed. */
-export function withClaudeReplayHistory<T>(
+export async function withClaudeReplayHistory<T>(
   historyPath: string,
-  consume: (history: ClaudeReplayHistory) => T,
-): T {
-  const descriptors = new Map<string, number>();
+  consume: (history: ClaudeReplayHistory) => Promise<T>,
+): Promise<T> {
+  const descriptors = new Map<string, FileHandle>();
   try {
-    return consume(indexHistory(historyPath, descriptors));
+    return await consume(await indexHistory(historyPath, descriptors));
   } finally {
-    for (const fd of descriptors.values()) fs.closeSync(fd);
+    await closeReplaySources(descriptors.values());
   }
 }
 
-function indexHistory(historyPath: string, descriptors: Map<string, number>): ClaudeReplayHistory {
+async function closeReplaySources(descriptors: Iterable<FileHandle>): Promise<void> {
+  const results = await Promise.allSettled([...descriptors].map((fd) => fd.close()));
+  const failure = results.find((result) => result.status === "rejected");
+  if (failure) throw failure.reason;
+}
+
+async function indexHistory(
+  historyPath: string,
+  descriptors: Map<string, FileHandle>,
+): Promise<ClaudeReplayHistory> {
   const sessionDirectory = path.join(
     path.dirname(historyPath),
     path.basename(historyPath, ".jsonl"),
@@ -174,8 +191,7 @@ function indexHistory(historyPath: string, descriptors: Map<string, number>): Cl
   const directories = [sidechainDirectory];
   while (directories.length) {
     const directory = directories.pop()!;
-    if (!fs.existsSync(directory)) continue;
-    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    for (const entry of await optionalDirectory(directory)) {
       const file = path.join(directory, entry.name);
       if (entry.isDirectory()) {
         directories.push(file);
@@ -194,23 +210,23 @@ function indexHistory(historyPath: string, descriptors: Map<string, number>): Cl
       }
       const agentId = /^agent-(.+)\.meta\.json$/.exec(entry.name)?.[1];
       if (!agentId) continue;
-      const contents = readOptionalFile(file);
+      const contents = await readOptionalFile(file);
       const meta = contents === null ? null : parseClaudeSubagentMeta(contents);
       if (meta) metaByAgentId.set(agentId, meta);
     }
   }
   const parentLocations: RecordLocation[] = [];
   const locationsByAgentId = new Map<string, RecordLocation[]>();
-  function scan(
+  async function scan(
     file: string,
     visit: (entry: TranscriptEntry, location: RecordLocation) => void,
-  ): void {
-    const fd = fs.openSync(file, "r");
+  ): Promise<void> {
+    const fd = await fs.open(file, "r");
     descriptors.set(file, fd);
-    for (const { entry, location } of locatedRecords(file, fd)) visit(entry, location);
+    for await (const { entry, location } of locatedRecords(file, fd)) visit(entry, location);
   }
   for (const file of sidechainFiles) {
-    scan(file, (entry, location) => {
+    await scan(file, (entry, location) => {
       if (file === historyPath && entry.isSidechain !== true) parentLocations.push(location);
       if (entry.isSidechain !== true || typeof entry.agentId !== "string") return;
       const locations = locationsByAgentId.get(entry.agentId) ?? [];
@@ -218,11 +234,11 @@ function indexHistory(historyPath: string, descriptors: Map<string, number>): Cl
       locationsByAgentId.set(entry.agentId, locations);
     });
   }
-  const workflowEntriesByRunId = new Map<string, Iterable<TranscriptEntry>>();
+  const workflowEntriesByRunId = new Map<string, AsyncIterable<TranscriptEntry>>();
   for (const [runId, files] of workflowFiles) {
     const locations: RecordLocation[] = [];
     for (const file of files)
-      scan(file, (entry, location) => {
+      await scan(file, (entry, location) => {
         if (entry.type !== "user" || isToolResult(entry)) locations.push(location);
       });
     locations.sort((a, b) => {
@@ -240,21 +256,28 @@ function indexHistory(historyPath: string, descriptors: Map<string, number>): Cl
       meta: metaByAgentId.get(agentId) ?? null,
       entries: indexedRecords(locations, descriptors),
     })),
-    workflows: readWorkflows(sessionDirectory),
+    workflows: await readWorkflows(sessionDirectory),
     workflowEntriesByRunId,
   };
 }
 
-function readWorkflows(sessionDirectory: string): ClaudeWorkflowRun[] {
+async function readWorkflows(sessionDirectory: string): Promise<ClaudeWorkflowRun[]> {
   const workflows: ClaudeWorkflowRun[] = [];
   const workflowDirectory = path.join(sessionDirectory, "workflows");
-  if (fs.existsSync(workflowDirectory)) {
-    for (const entry of fs.readdirSync(workflowDirectory, { withFileTypes: true })) {
-      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
-      const contents = readOptionalFile(path.join(workflowDirectory, entry.name));
-      const workflow = contents === null ? null : parseClaudeWorkflowRun(contents);
-      if (workflow) workflows.push(workflow);
-    }
+  for (const entry of await optionalDirectory(workflowDirectory)) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    const contents = await readOptionalFile(path.join(workflowDirectory, entry.name));
+    const workflow = contents === null ? null : parseClaudeWorkflowRun(contents);
+    if (workflow) workflows.push(workflow);
   }
   return workflows;
 }
+
+async function optionalDirectory(directory: string) {
+  try {
+    return await fs.readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
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 0469d9fbe1..dc7f920993 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
@@ -264,6 +264,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 () => {
diff --git a/packages/server/src/server/agent/providers/codex-app-server-agent.real.e2e.test.ts b/packages/server/src/server/agent/providers/codex-app-server-agent.real.e2e.test.ts
index 5a6592862c..f564b7bf94 100644
--- a/packages/server/src/server/agent/providers/codex-app-server-agent.real.e2e.test.ts
+++ b/packages/server/src/server/agent/providers/codex-app-server-agent.real.e2e.test.ts
@@ -77,12 +77,19 @@ CHILD_SENTINEL in your own response.
 
         const completedChildIndex = events.findIndex(
           (event) =>
-            event.type === "timeline" &&
-            event.item.type === "tool_call" &&
-            event.item.status === "completed" &&
-            event.item.detail.type === "sub_agent" &&
-            event.item.detail.log.includes("CHILD_SENTINEL"),
+            event.type === "provider_subagent" &&
+            event.event.type === "upsert" &&
+            event.event.status === "completed",
         );
+        const childAssistantText = events
+          .flatMap((event) =>
+            event.type === "provider_subagent" &&
+            event.event.type === "timeline" &&
+            event.event.item.type === "assistant_message"
+              ? [event.event.item.text]
+              : [],
+          )
+          .join("");
         const rootMessageIndexes = events.flatMap((event, index) =>
           event.type === "timeline" && event.item.type === "assistant_message" ? [index] : [],
         );
@@ -105,6 +112,7 @@ CHILD_SENTINEL in your own response.
           .map((item) => item.text)
           .join("");
         expect(topLevelAssistantText).not.toContain("CHILD_SENTINEL");
+        expect(childAssistantText).toContain("CHILD_SENTINEL");
         expect(completedChildIndex).toBeGreaterThanOrEqual(0);
         expect(rootMessageIndexes[0]).toBeGreaterThan(completedChildIndex);
         expect(terminalIndexes).toHaveLength(1);
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 8c61635d6f..78df159fc0 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
@@ -16,6 +16,7 @@ import type {
   AgentSessionConfig,
   AgentSlashCommand,
   AgentStreamEvent,
+  AgentTimelineItem,
 } from "../agent-sdk-types.js";
 import {
   buildCodexAppServerEnv,
@@ -87,7 +88,9 @@ describe("Codex executable discovery", () => {
 import { CodexAppServerClient } from "./codex/app-server-transport.js";
 import {
   createFakeCodexAppServer,
+  fakeCodexThreadHistory,
   type FakeCodexAppServer,
+  waitForNextEvent,
   waitForNextPermission,
   waitForNextTimelineItem,
   waitForProviderSubagent,
@@ -113,8 +116,7 @@ interface CodexSessionTestAccess {
   };
   ensureThreadLoaded(): Promise<void>;
   handleToolApprovalRequest(params: unknown): Promise<unknown>;
-  handleNotification(method: string, params: unknown): void;
-  loadPersistedHistory(client: CodexClientLike | null): Promise<void>;
+  handleNotification(method: string, params: unknown): Promise<void>;
   refreshResolvedCollaborationMode(): void;
   serviceTier: "fast" | null;
   planModeEnabled: boolean;
@@ -212,6 +214,7 @@ async function startPublicSteeringSession(
   const started = await session.startTurn("first");
   await appServer.waitForTurnStart();
   appServer.startsTurn({ threadId: "thread-1", turnId: "native-A" });
+  await new Promise<void>((resolve) => setImmediate(resolve));
   await new Promise((resolve) => setTimeout(resolve, 0));
   return { session, paseoTurnId: started.turnId };
 }
@@ -224,7 +227,116 @@ 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({
+      "turn/steer": () => ({ turn: { id: "native-A" } }),
+    });
+    const session = new CodexAppServerAgentSession(
+      createConfig({ cwd: "/workspace/project" }),
+      null,
+      createTestLogger(),
+      async () => appServer.child,
+    );
+    try {
+      const { turnId } = await session.startTurn("FIRST");
+      const steer = session.steerActiveTurn("SECOND", { expectedTurnId: turnId });
+      appServer.startsTurn({ threadId: "thread-1", turnId: "native-A" });
+
+      await expect(steer).resolves.toEqual({ status: "accepted" });
+      expect(
+        appServer.requests().filter((request) => request.method === "turn/start"),
+      ).toHaveLength(1);
+      expect(appServer.requests().filter((request) => request.method === "turn/interrupt")).toEqual(
+        [],
+      );
+      expect(appServer.requests().find((request) => request.method === "turn/steer")).toMatchObject(
+        {
+          params: {
+            threadId: "thread-1",
+            expectedTurnId: "native-A",
+            input: [{ type: "text", text: "SECOND" }],
+          },
+        },
+      );
+      appServer.assertNoErrors();
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("releases a waiting steer when the accepted turn ends before identification", async () => {
+    const appServer = createFakeCodexAppServer();
+    const session = new CodexAppServerAgentSession(
+      createConfig({ cwd: "/workspace/project" }),
+      null,
+      createTestLogger(),
+      async () => appServer.child,
+    );
+    try {
+      const { turnId } = await session.startTurn("FIRST");
+      const steer = session.steerActiveTurn("SECOND", { expectedTurnId: turnId });
+      appServer.completeTurn();
+
+      await expect(steer).resolves.toEqual({ status: "unavailable" });
+      expect(appServer.requests().filter((request) => request.method === "turn/steer")).toEqual([]);
+      appServer.assertNoErrors();
+    } finally {
+      await session.close();
+    }
+  });
+
   test("a steer without the clearing contract leaves permissions open", async () => {
     const appServer = createFakeCodexAppServer({
       "turn/steer": () => ({ turn: { id: "native-A" } }),
@@ -354,9 +466,11 @@ describe("Codex active-turn steering admission", () => {
     });
     await resolverEntered.promise;
     appServer.completeTurn({ threadId: "thread-1" });
+    await new Promise<void>((resolve) => setImmediate(resolve));
     await new Promise((resolve) => setTimeout(resolve, 0));
     const startedB = await session.startTurn("second");
     appServer.startsTurn({ threadId: "thread-1", turnId: "native-B" });
+    await new Promise<void>((resolve) => setImmediate(resolve));
     await new Promise((resolve) => setTimeout(resolve, 0));
     commandResolution.resolve(null);
 
@@ -478,6 +592,7 @@ async function startCompactionTurnTest(): Promise<{
 
   await session.startTurn("exercise compaction lifecycle");
   appServer.startsTurn({ threadId: "thread-1", turnId: "codex-turn-1" });
+  await new Promise<void>((resolve) => setImmediate(resolve));
   return { appServer, session, events, terminalEvent };
 }
 
@@ -499,6 +614,81 @@ function archivedThreadErrorMessage(threadId: string): string {
   );
 }
 
+function codexUserItem(id: string, text: string) {
+  return { type: "userMessage", id, content: [{ type: "text", text }] };
+}
+
+function codexAgentItem(text: string) {
+  return { type: "agentMessage", id: `agent-${text}`, text };
+}
+
+// An AgentManager over a real Codex provider whose every spawn gets a fresh fake
+// app-server serving `threads` from thread/read.
+function createReopenableCodexAgent(threads: Record<string, unknown[]>) {
+  const appServers: FakeCodexAppServer[] = [];
+  const provider = new CodexAppServerAgentClient(createTestLogger());
+  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",
+    capabilities: provider.capabilities,
+    isAvailable: async () => true,
+    fetchCatalog: async () => ({ models: [], modes: [] }),
+    createSession: async () => {
+      throw new Error("Unexpected create");
+    },
+    resumeSession: (...args) => provider.resumeSession(...args),
+  };
+  const manager = new AgentManager({ clients: { codex: client }, logger: createTestLogger() });
+  const agentId = "00000000-0000-4000-8000-000000000001";
+  const handle = { provider: "codex", sessionId: "saved-thread" };
+  const config = createConfig({ cwd: process.cwd() });
+
+  async function open(): Promise<void> {
+    await manager.resumeAgentFromPersistence(handle, config, agentId);
+    await manager.hydrateTimelineFromProvider(agentId);
+  }
+
+  return {
+    manager,
+    agentId,
+    latestAppServer: () => appServers[appServers.length - 1],
+    threadMethods: (index: number) =>
+      appServers[index]
+        .requests()
+        .map((request) => request.method)
+        .filter((method) => typeof method === "string" && method.startsWith("thread/")),
+    // Cold-loads the agent, closes its runtime, and reopens it while Paseo keeps its timeline.
+    async loadCloseAndReopen(): Promise<AgentTimelineItem[]> {
+      await open();
+      const projected = manager.getTimeline(agentId);
+      await manager.closeAgent(agentId);
+      await open();
+      return projected;
+    },
+    async close(): Promise<void> {
+      await manager.closeAgent(agentId);
+      for (const appServer of appServers) appServer.assertNoErrors();
+    },
+  };
+}
+
 function asInternals(session: CodexTestSession): CodexSessionTestAccess {
   return castInternals<CodexSessionTestAccess>(session);
 }
@@ -512,6 +702,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 },
@@ -1149,6 +1353,9 @@ describe("Codex app-server provider", () => {
     );
     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();
 
@@ -1181,6 +1388,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();
@@ -1189,6 +1399,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,
@@ -1460,7 +1719,9 @@ describe("Codex app-server provider", () => {
         command: "gh pr merge 2030 --squash",
         cwd: "/workspace/project",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.says({ threadId: "thread-1", text: "Merged." });
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       await expect(nextTimelineItem).resolves.toEqual({
         type: "timeline",
@@ -1504,6 +1765,7 @@ describe("Codex app-server provider", () => {
         command: "gh pr merge 2030 --squash",
         cwd: "/workspace/project",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       await expect(nextTimelineItem).resolves.toEqual({
         type: "timeline",
@@ -1548,6 +1810,7 @@ describe("Codex app-server provider", () => {
         processId: "4242",
         text: "gh pr merge 2030 --squash\n",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       await expect(nextTimelineItem).resolves.toEqual({
         type: "timeline",
@@ -1576,6 +1839,7 @@ describe("Codex app-server provider", () => {
         command: "sleep 30",
         output: "Process running with session id 4242",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       await expect(relabeledTerminal).resolves.toEqual({
         type: "timeline",
@@ -1623,6 +1887,7 @@ describe("Codex app-server provider", () => {
           processId: "73",
           command,
         });
+        await new Promise<void>((resolve) => setImmediate(resolve));
 
         const terminalWrite = waitForTimelineToolCall(session, "terminal-session-73-1");
         appServer.typesIntoTerminal({
@@ -1632,6 +1897,7 @@ describe("Codex app-server provider", () => {
           processId: "73",
           text: "print(1)\n",
         });
+        await new Promise<void>((resolve) => setImmediate(resolve));
 
         await expect(terminalWrite).resolves.toMatchObject({
           item: {
@@ -1668,7 +1934,9 @@ describe("Codex app-server provider", () => {
         processId: "4242",
         text: "git status\n",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
+      await firstTimelineItem;
       const secondTimelineItem = waitForNextTimelineItem(session);
       appServer.typesIntoTerminal({
         threadId: "thread-1",
@@ -1677,6 +1945,7 @@ describe("Codex app-server provider", () => {
         processId: "4242",
         text: "git push\n",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       const [first, second] = await Promise.all([firstTimelineItem, secondTimelineItem]);
       expect(first.item).toMatchObject({
@@ -1844,7 +2113,7 @@ describe("Codex app-server provider", () => {
       purpose: "history",
     });
 
-    expect(threadRequests).toEqual(["thread/read"]);
+    expect(threadRequests).toEqual(["thread/read", "thread/read"]);
     await session.close();
     appServer.assertNoErrors();
   });
@@ -1883,12 +2152,151 @@ describe("Codex app-server provider", () => {
       "thread/resume",
       "thread/unarchive",
       "thread/resume",
-      "thread/read",
     ]);
     await session.close();
     appServer.assertNoErrors();
   });
 
+  test("resumes a Codex thread without asking for its turns", async () => {
+    const appServer = createFakeCodexAppServer();
+    const provider = createProviderWithFakeAppServer(appServer);
+
+    const session = await provider.resumeSession({ sessionId: "saved-thread" });
+
+    expect(
+      appServer
+        .requests()
+        .filter((request) => request.method === "thread/resume")
+        .map((request) => request.params),
+    ).toEqual([expect.objectContaining({ threadId: "saved-thread", excludeTurns: true })]);
+    await session.close();
+    appServer.assertNoErrors();
+  });
+
+  test("reopening an agent whose timeline Paseo still holds does not read Codex history", async () => {
+    const codex = createReopenableCodexAgent({
+      "saved-thread": [
+        { id: "turn-1", items: [codexUserItem("user-1", "Hello"), codexAgentItem("Hi there.")] },
+      ],
+    });
+    try {
+      const projected = await codex.loadCloseAndReopen();
+
+      expect(projected).toEqual([
+        expect.objectContaining({ type: "user_message", messageId: "user-1", text: "Hello" }),
+        expect.objectContaining({ type: "assistant_message", text: "Hi there." }),
+      ]);
+      // 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(historyMethods(1)).toEqual(["thread/loaded/list", "thread/resume"]);
+      expect(codex.manager.getTimeline(codex.agentId)).toEqual(projected);
+    } finally {
+      await codex.close();
+    }
+  });
+
+  test("rewinds an agent reopened without reading its Codex history", async () => {
+    const firstTurn = {
+      id: "turn-1",
+      items: [codexUserItem("user-1", "First"), codexAgentItem("First answer.")],
+    };
+    const codex = createReopenableCodexAgent({
+      "saved-thread": [
+        firstTurn,
+        { id: "turn-2", items: [codexUserItem("user-2", "Second"), codexAgentItem("Second.")] },
+      ],
+      "forked-thread": [firstTurn],
+    });
+    try {
+      await codex.loadCloseAndReopen();
+
+      await codex.manager.rewind(codex.agentId, "user-2", "conversation");
+
+      expect(codex.latestAppServer().recordedRollbacks).toEqual([
+        { threadId: "forked-thread", numTurns: 1 },
+      ]);
+      expect(codex.manager.getTimeline(codex.agentId)).toEqual([
+        expect.objectContaining({ type: "user_message", messageId: "user-1", text: "First" }),
+        expect.objectContaining({ type: "assistant_message", text: "First answer." }),
+      ]);
+    } finally {
+      await codex.close();
+    }
+  });
+
+  test("keeps a reopened agent's interaction with an earlier sub-agent on its original card", async () => {
+    const codex = createReopenableCodexAgent({
+      "saved-thread": [
+        {
+          id: "turn-1",
+          items: [
+            codexUserItem("user-1", "Delegate"),
+            {
+              type: "subAgentActivity",
+              id: "spawn-child",
+              kind: "started",
+              agentThreadId: "child-thread",
+              agentPath: "/root/child",
+            },
+          ],
+        },
+      ],
+      "child-thread": [{ id: "child-turn-1", items: [codexAgentItem("Child started.")] }],
+    });
+    try {
+      await codex.loadCloseAndReopen();
+      const appServer = codex.latestAppServer();
+
+      const run = codex.manager.runAgent(codex.agentId, "Ask the child again");
+      await appServer.waitForTurnStart();
+      appServer.startsTurn({ threadId: "saved-thread", turnId: "turn-2" });
+      appServer.beginsSubAgentActivity({
+        callId: "interact-child",
+        threadId: "child-thread",
+        parentThreadId: "saved-thread",
+        kind: "interacted",
+        agentPath: "/root/child",
+      });
+      appServer.says({ threadId: "child-thread", itemId: "child-reply", text: "Child replied." });
+      appServer.completesSubAgentActivity({
+        callId: "interact-child",
+        threadId: "child-thread",
+        parentThreadId: "saved-thread",
+        kind: "interacted",
+        agentPath: "/root/child",
+      });
+      appServer.completeTurn({ threadId: "saved-thread" });
+      await run;
+
+      const toolCalls = codex.manager
+        .getTimeline(codex.agentId)
+        .filter((item) => item.type === "tool_call");
+      expect(new Set(toolCalls.map((item) => item.callId))).toEqual(new Set(["spawn-child"]));
+      expect(toolCalls.at(-1)).toMatchObject({ callId: "spawn-child", status: "completed" });
+      expect(codex.manager.getProviderSubagent(codex.agentId, "child-thread")).toMatchObject({
+        toolCallId: "spawn-child",
+        status: "completed",
+      });
+      expect(
+        codex.manager
+          .fetchProviderSubagentTimeline(codex.agentId, "child-thread")
+          .rows.map((row) => row.item),
+      ).toEqual([
+        expect.objectContaining({ type: "assistant_message", text: "Child started." }),
+        expect.objectContaining({ type: "assistant_message", text: "Child replied." }),
+      ]);
+    } finally {
+      await codex.close();
+    }
+  });
+
   test("closes Codex app-server when an interactive resume fails", async () => {
     const appServer = createFakeCodexAppServer({
       "thread/resume": () => Promise.reject(new Error("thread resume failed")),
@@ -2075,9 +2483,13 @@ describe("Codex app-server provider", () => {
     await session.startTurn("remember first");
     emitCodexUserMessage(appServer, { id: "codex-first", text: "remember first" });
     appServer.completeTurn();
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    await new Promise<void>((resolve) => setImmediate(resolve));
     await session.startTurn("remember second");
     emitCodexUserMessage(appServer, { id: "codex-second", text: "remember second" });
     appServer.completeTurn();
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    await new Promise<void>((resolve) => setImmediate(resolve));
 
     await session.revertConversation({ messageId: "codex-first" });
 
@@ -2116,6 +2528,8 @@ describe("Codex app-server provider", () => {
       turnId: "turn-first",
     });
     appServer.completeTurn();
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    await new Promise<void>((resolve) => setImmediate(resolve));
     await session.startTurn("remember second");
     emitCodexUserMessage(appServer, {
       id: "codex-second",
@@ -2123,6 +2537,8 @@ describe("Codex app-server provider", () => {
       turnId: "turn-second",
     });
     appServer.completeTurn();
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    await new Promise<void>((resolve) => setImmediate(resolve));
 
     await session.revertConversation({ messageId: "codex-second" });
 
@@ -2137,7 +2553,7 @@ describe("Codex app-server provider", () => {
         cwd: "/workspace/project",
         model: "gpt-5.4",
         serviceTier: null,
-        excludeTurns: false,
+        excludeTurns: true,
         persistExtendedHistory: true,
       },
     ]);
@@ -2149,10 +2565,82 @@ 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({
-      "thread/read": () => ({
-        thread: { id: "thread-1", historyMode: "paginated", turns: [] },
+      ...fakeCodexThreadHistory({
+        "thread-1": { historyMode: "paginated", turns: [] },
+        "forked-thread": { historyMode: "paginated", turns: [] },
       }),
       "thread/rollback": () => {
         throw new Error("paginated threads do not support thread/rollback");
@@ -2172,6 +2660,8 @@ describe("Codex app-server provider", () => {
       turnId: "turn-first",
     });
     appServer.completeTurn();
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    await new Promise<void>((resolve) => setImmediate(resolve));
     await session.startTurn("remember second");
     emitCodexUserMessage(appServer, {
       id: "codex-second",
@@ -2179,6 +2669,8 @@ describe("Codex app-server provider", () => {
       turnId: "turn-second",
     });
     appServer.completeTurn();
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    await new Promise<void>((resolve) => setImmediate(resolve));
 
     await session.revertConversation({ messageId: "codex-first" });
 
@@ -2193,7 +2685,7 @@ describe("Codex app-server provider", () => {
         cwd: "/workspace/project",
         model: "gpt-5.4",
         serviceTier: null,
-        excludeTurns: false,
+        excludeTurns: true,
         persistExtendedHistory: true,
       },
     ]);
@@ -2210,11 +2702,10 @@ describe("Codex app-server provider", () => {
     async (historyMode) => {
       const appServer = createFakeCodexAppServer(
         historyMode === "paginated"
-          ? {
-              "thread/read": () => ({
-                thread: { id: "thread-1", historyMode: "paginated", turns: [] },
-              }),
-            }
+          ? fakeCodexThreadHistory({
+              "thread-1": { historyMode: "paginated", turns: [] },
+              "forked-thread": { historyMode: "paginated", turns: [] },
+            })
           : undefined,
       );
       const customCodexConfig = {
@@ -2249,6 +2740,8 @@ describe("Codex app-server provider", () => {
         turnId: "turn-first",
       });
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await session.startTurn("remember second");
       emitCodexUserMessage(appServer, {
         id: "codex-second",
@@ -2256,6 +2749,8 @@ describe("Codex app-server provider", () => {
         turnId: "turn-second",
       });
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       await session.revertConversation({ messageId: "codex-first" });
 
@@ -2290,7 +2785,7 @@ describe("Codex app-server provider", () => {
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
     await session.startTurn("remember this", { clientMessageId: "client-message" });
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       threadId: "thread-1",
       turn: { id: "turn-1" },
     });
@@ -2304,8 +2799,15 @@ 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));
     await session.close();
   });
 
@@ -2321,9 +2823,9 @@ describe("Codex app-server provider", () => {
       OPENAI_BASE_URL: "https://custom-relay.example.com",
     });
     expect(capturedThreadStartConfig(capturedRequests)).toEqual({
-      model_provider: "codex-iisb",
+      model_provider: "paseo:codex-iisb",
       model_providers: {
-        "codex-iisb": {
+        "paseo:codex-iisb": {
           name: "Custom Codex",
           base_url: "https://custom-relay.example.com/v1",
           env_key: "OPENAI_API_KEY",
@@ -2341,15 +2843,30 @@ describe("Codex app-server provider", () => {
     );
 
     expect(capturedThreadStartConfig(capturedRequests)).toEqual({
-      model_provider: "codex-custom",
+      model_provider: "paseo:codex-custom",
       model_providers: {
-        "codex-custom": expect.objectContaining({
+        "paseo:codex-custom": expect.objectContaining({
           base_url: "https://custom-relay.example.com/v1",
         }),
       },
     });
   });
 
+  test("namespaces provider ids that collide with Codex built-ins", async () => {
+    // `ollama` is a reserved Codex provider id: without namespacing, Codex rejects
+    // the generated config outright and the agent never starts.
+    const capturedRequests = await runCustomCodexProviderTurn("ollama", "https://ollama.com");
+
+    expect(capturedThreadStartConfig(capturedRequests)).toEqual({
+      model_provider: "paseo:ollama",
+      model_providers: {
+        "paseo:ollama": expect.objectContaining({
+          base_url: "https://ollama.com/v1",
+        }),
+      },
+    });
+  });
+
   test("resumeSession does not replace a persisted Codex thread when app-server resume fails", async () => {
     const threadRequests: string[] = [];
     const appServer = createFakeCodexAppServer({
@@ -3007,6 +3524,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",
@@ -3181,12 +3779,12 @@ describe("Codex app-server provider", () => {
     ]);
   });
 
-  test("converts Codex collab agent notifications through the normal timeline path", () => {
+  test("converts Codex collab agent notifications through the normal timeline path", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/started", {
+    await asInternals(session).handleNotification("item/started", {
       threadId: "test-thread",
       item: {
         type: "collabAgentToolCall",
@@ -3222,12 +3820,12 @@ describe("Codex app-server provider", () => {
     ]);
   });
 
-  test("folds child-thread Codex activity into the parent sub-agent tool call", () => {
+  test("keeps child-thread Codex activity out of the parent sub-agent card", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "collabAgentToolCall",
@@ -3241,12 +3839,12 @@ describe("Codex app-server provider", () => {
         },
       },
     });
-    asInternals(session).handleNotification("item/agentMessage/delta", {
+    await asInternals(session).handleNotification("item/agentMessage/delta", {
       threadId: "child-thread-1",
       itemId: "child-message-1",
       delta: "Found",
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "child-thread-1",
       item: {
         type: "agentMessage",
@@ -3254,13 +3852,12 @@ describe("Codex app-server provider", () => {
         text: "Found the path.",
       },
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       threadId: "child-thread-1",
       turn: { status: "completed" },
     });
 
     const timelineEvents = events.filter((event) => event.type === "timeline");
-    expect(timelineEvents).toHaveLength(4);
     expect(timelineEvents.every((event) => event.item.type === "tool_call")).toBe(true);
     const finalItem = timelineEvents.at(-1)?.item;
     expect(finalItem).toMatchObject({
@@ -3272,7 +3869,7 @@ describe("Codex app-server provider", () => {
         type: "sub_agent",
         subAgentType: "Sub-agent",
         description: "Report findings.",
-        log: "[Assistant] Found the path.",
+        log: "",
         actions: [],
       },
     });
@@ -3332,12 +3929,15 @@ describe("Codex app-server provider", () => {
         threadId: "settled-child-thread",
         agentPath: "/root/settled-child",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn({ threadId: "settled-child-thread" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.says({
         threadId: "settled-child-thread",
         itemId: "late-child-message",
         text: "Late trailing output.",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       const providerUpserts = events.flatMap((event) =>
         event.type === "provider_subagent" && event.event.type === "upsert" ? [event.event] : [],
@@ -3346,13 +3946,9 @@ describe("Codex app-server provider", () => {
         id: "settled-child-thread",
         status: "completed",
       });
-      expect(events.at(-1)).toMatchObject({
+      expect(events.findLast((event) => event.type === "timeline")).toMatchObject({
         type: "timeline",
-        item: {
-          callId: "call-settled-child",
-          status: "completed",
-          detail: { type: "sub_agent", log: "[Assistant] Late trailing output." },
-        },
+        item: { callId: "call-settled-child", status: "completed" },
       });
 
       appServer.completesSubAgentActivity({
@@ -3361,6 +3957,7 @@ describe("Codex app-server provider", () => {
         agentPath: "/root/settled-child",
         kind: "interacted",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       expect(
         events.findLast(
           (event) => event.type === "provider_subagent" && event.event.type === "upsert",
@@ -3371,6 +3968,7 @@ describe("Codex app-server provider", () => {
         threadId: "settled-child-thread",
         turnId: "next-child-turn",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       expect(
         events.findLast(
           (event) => event.type === "provider_subagent" && event.event.type === "upsert",
@@ -3378,7 +3976,9 @@ describe("Codex app-server provider", () => {
       ).toMatchObject({ event: { id: "settled-child-thread", status: "running" } });
 
       appServer.completeTurn({ threadId: "settled-child-thread" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await resultPromise;
       appServer.assertNoErrors();
     } finally {
@@ -3386,12 +3986,12 @@ describe("Codex app-server provider", () => {
     }
   });
 
-  test("updates a registered child with its later native activity name", () => {
+  test("updates a registered child with its later native activity name", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "collabAgentToolCall",
@@ -3405,7 +4005,7 @@ describe("Codex app-server provider", () => {
         },
       },
     });
-    asInternals(session).handleNotification("item/started", {
+    await asInternals(session).handleNotification("item/started", {
       threadId: "test-thread",
       item: {
         type: "subAgentActivity",
@@ -3440,11 +4040,11 @@ describe("Codex app-server provider", () => {
     });
   });
 
-  test("renders child MCP image results in the provider subagent timeline", () => {
+  test("renders child MCP image results in the provider subagent timeline", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "subAgentActivity",
@@ -3455,7 +4055,7 @@ describe("Codex app-server provider", () => {
       },
     });
 
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "image-child-thread",
       item: {
         id: "child-mcp-image",
@@ -3488,11 +4088,11 @@ describe("Codex app-server provider", () => {
     rmSync(source, { force: true });
   });
 
-  test("renders a child user message once across lifecycle notifications", () => {
+  test("renders a child user message once across lifecycle notifications", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "subAgentActivity",
@@ -3508,11 +4108,11 @@ describe("Codex app-server provider", () => {
       content: [{ type: "text", text: "Inspect this path." }],
     };
 
-    asInternals(session).handleNotification("item/started", {
+    await asInternals(session).handleNotification("item/started", {
       threadId: "user-child-thread",
       item: childUserMessage,
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "user-child-thread",
       item: childUserMessage,
     });
@@ -3546,19 +4146,24 @@ describe("Codex app-server provider", () => {
         threadId: "child-thread-1",
         agentPath: "/root/child",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.says({
         threadId: "child-thread-1",
         itemId: "child-message-1",
         text: "Child findings.",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn({ threadId: "child-thread-1" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.says({
         threadId: "thread-1",
         itemId: "parent-message-1",
         text: "Parent report.",
         chunks: ["Parent ", "report."],
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       const result = await resultPromise;
       expect(result.finalText).toBe("Parent report.");
@@ -3592,13 +4197,16 @@ describe("Codex app-server provider", () => {
         itemId: "first-parent-message",
         text: "First report.",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.says({
         threadId: "thread-1",
         itemId: "second-parent-message",
         text: "Second report.",
         chunks: ["", "Second report."],
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       const result = await resultPromise;
       expect(result.finalText).toBe("Second report.");
@@ -3623,8 +4231,11 @@ describe("Codex app-server provider", () => {
       await appServer.waitForTurnStart();
 
       appServer.says({ threadId: "thread-1", text: "First report." });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.says({ threadId: "thread-1", text: "Second report." });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       const result = await resultPromise;
       expect(result.finalText).toBe("Second report.");
@@ -3642,29 +4253,37 @@ describe("Codex app-server provider", () => {
       createTestLogger(),
       async () => appServer.child,
     );
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
 
     try {
       const resultPromise = session.run("Delegate the investigation, then report the result.");
       await appServer.waitForTurnStart();
 
       appServer.startsTurn({ threadId: "child-thread-early" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.says({
         threadId: "child-thread-early",
         itemId: "child-message-early",
         text: "Early child findings.",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn({ threadId: "child-thread-early" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.startsSubAgent({
         callId: "spawn-child-early",
         threadId: "child-thread-early",
         agentPath: "/root/early-child",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.says({
         threadId: "thread-1",
         itemId: "parent-message-after-early-child",
         text: "Parent report after replay.",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       const result = await resultPromise;
       expect(result.finalText).toBe("Parent report after replay.");
@@ -3679,11 +4298,18 @@ describe("Codex app-server provider", () => {
         type: "tool_call",
         callId: "spawn-child-early",
         status: "completed",
-        detail: {
-          type: "sub_agent",
-          log: "[Assistant] Early child findings.",
-        },
+        detail: { type: "sub_agent", log: "" },
       });
+      expect(events).toContainEqual(
+        expect.objectContaining({
+          type: "provider_subagent",
+          event: expect.objectContaining({
+            type: "timeline",
+            id: "child-thread-early",
+            item: expect.objectContaining({ type: "assistant_message" }),
+          }),
+        }),
+      );
       appServer.assertNoErrors();
     } finally {
       await session.close();
@@ -3708,36 +4334,43 @@ describe("Codex app-server provider", () => {
         threadId: "child-thread-stable",
         agentPath: "/root/stable-child",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.beginsSubAgentActivity({
         callId: "message-child-stable",
         threadId: "child-thread-stable",
         agentPath: "/root/stable-child",
         kind: "interacted",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completesSubAgentActivity({
         callId: "message-child-stable",
         threadId: "child-thread-stable",
         agentPath: "/root/stable-child",
         kind: "interacted",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.says({
         threadId: "child-thread-stable",
         itemId: "stable-child-message",
         text: "Still on the same card.",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.beginsSubAgentActivity({
         callId: "interrupt-child-stable",
         threadId: "child-thread-stable",
         agentPath: "/root/stable-child",
         kind: "interrupted",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completesSubAgentActivity({
         callId: "interrupt-child-stable",
         threadId: "child-thread-stable",
         agentPath: "/root/stable-child",
         kind: "interrupted",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       const result = await resultPromise;
       const toolCalls = result.timeline.filter((item) => item.type === "tool_call");
@@ -3747,10 +4380,7 @@ describe("Codex app-server provider", () => {
       expect(toolCalls.at(-1)).toMatchObject({
         callId: "spawn-child-stable",
         status: "canceled",
-        detail: {
-          type: "sub_agent",
-          log: "[Assistant] Still on the same card.",
-        },
+        detail: { type: "sub_agent", log: "" },
       });
       appServer.assertNoErrors();
     } finally {
@@ -3772,6 +4402,7 @@ describe("Codex app-server provider", () => {
       await appServer.waitForTurnStart();
 
       appServer.completeTurn({ threadId: "child-thread-fast" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       const activity = {
         callId: "spawn-child-fast",
         threadId: "child-thread-fast",
@@ -3779,8 +4410,11 @@ describe("Codex app-server provider", () => {
         kind: "started" as const,
       };
       appServer.beginsSubAgentActivity(activity);
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completesSubAgentActivity(activity);
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       const result = await resultPromise;
       const toolCalls = result.timeline.filter((item) => item.type === "tool_call");
@@ -3809,24 +4443,27 @@ describe("Codex app-server provider", () => {
       await appServer.waitForTurnStart();
 
       appServer.completeTurn({ threadId: "child-late-compaction" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completesCompaction({
         threadId: "child-late-compaction",
         itemId: "late-child-compaction",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.startsSubAgent({
         callId: "spawn-child-late-compaction",
         threadId: "child-late-compaction",
         agentPath: "/root/late-compaction",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       const result = await resultPromise;
       const toolCalls = result.timeline.filter((item) => item.type === "tool_call");
-      expect(toolCalls.map((item) => item.status)).toEqual(["running", "completed", "completed"]);
+      expect(toolCalls.map((item) => item.status)).toEqual(["running", "completed"]);
       expect(toolCalls.at(-1)).toMatchObject({
         callId: "spawn-child-late-compaction",
         status: "completed",
-        detail: { type: "sub_agent", log: "[Compacted]" },
       });
       appServer.assertNoErrors();
     } finally {
@@ -3834,7 +4471,7 @@ describe("Codex app-server provider", () => {
     }
   });
 
-  test("projects legacy child tools into one stable sub-agent log", async () => {
+  test("routes legacy child tools to the child timeline", async () => {
     const appServer = createFakeCodexAppServer();
     const session = new CodexAppServerAgentSession(
       createConfig({ cwd: "/workspace/project" }),
@@ -3842,6 +4479,8 @@ describe("Codex app-server provider", () => {
       createTestLogger(),
       async () => appServer.child,
     );
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
 
     try {
       const resultPromise = session.run("Delegate the implementation.");
@@ -3852,6 +4491,7 @@ describe("Codex app-server provider", () => {
         threadId: "legacy-tool-child",
         agentPath: "/root/legacy-tool-child",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       const command = {
         threadId: "legacy-tool-child",
         callId: "legacy-child-command",
@@ -3859,15 +4499,20 @@ describe("Codex app-server provider", () => {
         output: "child output",
       };
       appServer.runsLegacyCommand(command);
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completesCommand(command);
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.appliesLegacyPatch({
         threadId: "legacy-tool-child",
         callId: "legacy-child-patch",
         path: "/workspace/project/src/child.ts",
         diff: "@@\n-old\n+new\n",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn({ threadId: "legacy-tool-child" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       const result = await resultPromise;
       const toolCalls = result.timeline.filter((item) => item.type === "tool_call");
@@ -3878,24 +4523,31 @@ describe("Codex app-server provider", () => {
       expect(finalToolCall).toMatchObject({
         callId: "spawn-legacy-tool-child",
         status: "completed",
-        detail: { type: "sub_agent" },
+        detail: { type: "sub_agent", log: "" },
       });
-      if (finalToolCall?.detail.type === "sub_agent") {
-        expect(finalToolCall.detail.log.match(/\[Shell\]/g)).toHaveLength(1);
-        expect(finalToolCall.detail.log).toContain("[Edit]");
-      }
+      const childToolCalls = events.flatMap((event) =>
+        event.type === "provider_subagent" &&
+        event.event.type === "timeline" &&
+        event.event.id === "legacy-tool-child" &&
+        event.event.item.type === "tool_call"
+          ? [event.event.item]
+          : [],
+      );
+      expect(new Set(childToolCalls.map((item) => item.detail.type))).toEqual(
+        new Set(["shell", "edit"]),
+      );
       appServer.assertNoErrors();
     } finally {
       await session.close();
     }
   });
 
-  test("keeps nested MultiAgentV2 output inside the root sub-agent card", () => {
+  test("keeps nested MultiAgentV2 output out of the root sub-agent card", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "subAgentActivity",
@@ -3905,7 +4557,7 @@ describe("Codex app-server provider", () => {
         agentPath: "/root/child",
       },
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "child-thread-root",
       item: {
         type: "subAgentActivity",
@@ -3915,12 +4567,12 @@ describe("Codex app-server provider", () => {
         agentPath: "/root/child/grandchild",
       },
     });
-    asInternals(session).handleNotification("item/agentMessage/delta", {
+    await asInternals(session).handleNotification("item/agentMessage/delta", {
       threadId: "grandchild-thread",
       itemId: "grandchild-message",
       delta: "Grandchild findings.",
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       threadId: "grandchild-thread",
       turn: { status: "completed" },
     });
@@ -3950,10 +4602,24 @@ describe("Codex app-server provider", () => {
     expect(beforeParentCompletes.at(-1)).toMatchObject({
       callId: "spawn-child-root",
       status: "running",
-      detail: { type: "sub_agent", log: expect.stringContaining("Grandchild findings.") },
+      detail: { type: "sub_agent", log: "" },
     });
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: "provider_subagent",
+        event: {
+          type: "timeline",
+          id: "grandchild-thread",
+          item: {
+            type: "assistant_message",
+            messageId: "grandchild-message",
+            text: "Grandchild findings.",
+          },
+        },
+      }),
+    );
 
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       threadId: "child-thread-root",
       turn: { status: "completed" },
     });
@@ -3963,12 +4629,12 @@ describe("Codex app-server provider", () => {
     });
   });
 
-  test("keeps a nested child under its spawning parent after a root interaction", () => {
+  test("keeps a nested child under its spawning parent after a root interaction", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "subAgentActivity",
@@ -3978,7 +4644,7 @@ describe("Codex app-server provider", () => {
         agentPath: "/root/child",
       },
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "child-thread-root",
       item: {
         type: "subAgentActivity",
@@ -3988,7 +4654,7 @@ describe("Codex app-server provider", () => {
         agentPath: "/root/child/grandchild",
       },
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "collabAgentToolCall",
@@ -4001,7 +4667,7 @@ describe("Codex app-server provider", () => {
         },
       },
     });
-    asInternals(session).handleNotification("item/agentMessage/delta", {
+    await asInternals(session).handleNotification("item/agentMessage/delta", {
       threadId: "grandchild-thread",
       itemId: "grandchild-after-wait",
       delta: "Still nested.",
@@ -4018,37 +4684,44 @@ describe("Codex app-server provider", () => {
       "child-thread-root",
       "child-thread-root",
     ]);
-    expect(events.at(-1)).toMatchObject({
-      type: "timeline",
-      item: {
-        callId: "spawn-child-root",
-        detail: { type: "sub_agent", log: expect.stringContaining("Still nested.") },
-      },
-    });
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: "provider_subagent",
+        event: {
+          type: "timeline",
+          id: "grandchild-thread",
+          item: {
+            type: "assistant_message",
+            messageId: "grandchild-after-wait",
+            text: "Still nested.",
+          },
+        },
+      }),
+    );
   });
 
-  test("never treats an unmapped foreign terminal as the root terminal", () => {
+  test("never treats an unmapped foreign terminal as the root terminal", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       threadId: "unmapped-child-thread",
       turn: { status: "completed" },
     });
     expect(events).toEqual([]);
 
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       threadId: "test-thread",
       turn: { status: "completed" },
     });
     expect(events.filter((event) => event.type === "turn_completed")).toHaveLength(1);
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       threadId: "test-thread",
       turn: { id: "next-root-turn" },
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "subAgentActivity",
@@ -4064,12 +4737,12 @@ describe("Codex app-server provider", () => {
     });
   });
 
-  test("routes msg-scoped legacy Codex events to their child thread", () => {
+  test("routes msg-scoped legacy Codex events to their child thread", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "subAgentActivity",
@@ -4079,7 +4752,7 @@ describe("Codex app-server provider", () => {
         agentPath: "/root/legacy-envelope-child",
       },
     });
-    asInternals(session).handleNotification("codex/event/exec_command_begin", {
+    await asInternals(session).handleNotification("codex/event/exec_command_begin", {
       msg: {
         type: "exec_command_begin",
         threadId: "legacy-envelope-child",
@@ -4087,7 +4760,7 @@ describe("Codex app-server provider", () => {
         command: "pwd",
       },
     });
-    asInternals(session).handleNotification("codex/event/task_complete", {
+    await asInternals(session).handleNotification("codex/event/task_complete", {
       msg: {
         type: "task_complete",
         thread_id: "legacy-envelope-child",
@@ -4125,7 +4798,7 @@ describe("Codex app-server provider", () => {
       },
     });
 
-    asInternals(session).handleNotification("codex/event/task_complete", {
+    await asInternals(session).handleNotification("codex/event/task_complete", {
       msg: { type: "task_complete" },
     });
     expect(events.filter((event) => event.type === "turn_completed")).toHaveLength(1);
@@ -4147,11 +4820,13 @@ describe("Codex app-server provider", () => {
       const spawn = waitForTimelineToolCall(session, "spawn-legacy-only-child");
 
       appServer.startsTurn({ threadId: "thread-1", turnId: "turn-with-legacy-only-child" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.startsLegacyOnlySubAgent({
         callId: "spawn-legacy-only-child",
         threadId: "legacy-only-child-thread",
         agentPath: "/root/legacy-only-child",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       await expect(child).resolves.toMatchObject({
         type: "provider_subagent",
@@ -4179,6 +4854,7 @@ describe("Codex app-server provider", () => {
       });
 
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await resultPromise;
       appServer.assertNoErrors();
     } finally {
@@ -4203,10 +4879,12 @@ describe("Codex app-server provider", () => {
       const resultPromise = session.run("Wait for the child.");
       await appServer.waitForTurnStart();
       appServer.startsTurn({ threadId: "thread-1", turnId: "turn-waiting-for-child" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       await expect(session.interrupt()).rejects.toThrow("A foreground turn is already active");
 
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await resultPromise;
       appServer.assertNoErrors();
     } finally {
@@ -4231,10 +4909,12 @@ describe("Codex app-server provider", () => {
       const resultPromise = session.run("Wait for the child.");
       await appServer.waitForTurnStart();
       appServer.startsTurn({ threadId: "thread-1", turnId: "turn-already-idle" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       await expect(session.interrupt()).resolves.toBeUndefined();
 
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await resultPromise;
       appServer.assertNoErrors();
     } finally {
@@ -4263,10 +4943,12 @@ describe("Codex app-server provider", () => {
 
       const interruptPromise = session.interrupt();
       appServer.startsTurn({ threadId: "thread-1", turnId: "turn-identified-late" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await interruptPromise;
 
       expect(interruptedTurns).toEqual([{ threadId: "thread-1", turnId: "turn-identified-late" }]);
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await resultPromise;
       appServer.assertNoErrors();
     } finally {
@@ -4294,6 +4976,7 @@ describe("Codex app-server provider", () => {
       await appServer.waitForTurnStart();
       const interruptPromise = session.interrupt();
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       await expect(interruptPromise).resolves.toBeUndefined();
       await resultPromise;
@@ -4353,7 +5036,9 @@ describe("Codex app-server provider", () => {
       const nativeStart = await appServer.waitForTurnStart().catch(() => null);
       if (nativeStart) {
         appServer.startsTurn({ threadId: "thread-1", turnId: "cleanup-turn" });
+        await new Promise<void>((resolve) => setImmediate(resolve));
         appServer.completeTurn();
+        await new Promise<void>((resolve) => setImmediate(resolve));
       }
       await resultPromise.catch(() => undefined);
       await session.close();
@@ -4371,7 +5056,7 @@ describe("Codex app-server provider", () => {
       },
     };
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       threadId: "test-thread",
       turn: { id: "autonomous-turn" },
     });
@@ -4387,13 +5072,13 @@ describe("Codex app-server provider", () => {
     });
   });
 
-  test("never replaces the root identity with an early child thread start", () => {
+  test("never replaces the root identity with an early child thread start", async () => {
     const session = createSession();
 
-    asInternals(session).handleNotification("thread/started", {
+    await asInternals(session).handleNotification("thread/started", {
       thread: { id: "child-thread-started-early" },
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "subAgentActivity",
@@ -4407,12 +5092,12 @@ describe("Codex app-server provider", () => {
     expect(session.currentThreadId).toBe("test-thread");
   });
 
-  test("does not leak aggregate child telemetry into the root timeline", () => {
+  test("does not leak aggregate child telemetry into the root timeline", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "subAgentActivity",
@@ -4424,7 +5109,7 @@ describe("Codex app-server provider", () => {
     });
     const eventCountAfterSpawn = events.length;
 
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       threadId: "child-thread-telemetry",
       plan: [{ step: "Child-only plan", status: "inProgress" }],
     });
@@ -4432,12 +5117,12 @@ describe("Codex app-server provider", () => {
     expect(events).toHaveLength(eventCountAfterSpawn);
   });
 
-  test("keeps child context compaction inside the child card", () => {
+  test("keeps child context compaction on the child timeline", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "subAgentActivity",
@@ -4447,11 +5132,11 @@ describe("Codex app-server provider", () => {
         agentPath: "/root/compacting-child",
       },
     });
-    asInternals(session).handleNotification("item/started", {
+    await asInternals(session).handleNotification("item/started", {
       threadId: "child-thread-compaction",
       item: { type: "contextCompaction", id: "child-compaction" },
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "child-thread-compaction",
       item: { type: "contextCompaction", id: "child-compaction" },
     });
@@ -4465,18 +5150,78 @@ describe("Codex app-server provider", () => {
         (item) => item.type === "tool_call" && item.callId === "spawn-child-compaction",
       ),
     ).toBe(true);
-    expect(timelineItems.at(-1)).toMatchObject({
-      type: "tool_call",
-      detail: { type: "sub_agent", log: "[Compacted]" },
-    });
+    expect(
+      events.flatMap((event) =>
+        event.type === "provider_subagent" && event.event.type === "timeline" ? [event.event] : [],
+      ),
+    ).toEqual([
+      {
+        type: "timeline",
+        id: "child-thread-compaction",
+        item: { type: "compaction", status: "loading" },
+      },
+      {
+        type: "timeline",
+        id: "child-thread-compaction",
+        item: { type: "compaction", status: "completed" },
+      },
+    ]);
   });
 
-  test("keeps the parent sub-agent running when a child command fails during the child turn", () => {
+  test("settles a child compaction once when the item completion is missing or duplicated", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/completed", {
+    for (const child of ["compacted-child", "turn-ended-child"]) {
+      await asInternals(session).handleNotification("item/completed", {
+        threadId: "test-thread",
+        item: {
+          type: "subAgentActivity",
+          id: `spawn-${child}`,
+          kind: "started",
+          agentThreadId: child,
+          agentPath: `/root/${child}`,
+        },
+      });
+      await asInternals(session).handleNotification("item/started", {
+        threadId: child,
+        item: { type: "contextCompaction", id: `${child}-compaction` },
+      });
+    }
+    await asInternals(session).handleNotification("thread/compacted", {
+      threadId: "compacted-child",
+    });
+    await asInternals(session).handleNotification("item/completed", {
+      threadId: "compacted-child",
+      item: { type: "contextCompaction", id: "compacted-child-compaction" },
+    });
+    await asInternals(session).handleNotification("turn/completed", {
+      threadId: "turn-ended-child",
+      turn: { status: "completed" },
+    });
+
+    const compactions = events.flatMap((event) =>
+      event.type === "provider_subagent" && event.event.type === "timeline"
+        ? [
+            `${event.event.id} ${event.event.item.type === "compaction" ? event.event.item.status : ""}`,
+          ]
+        : [],
+    );
+    expect(compactions).toEqual([
+      "compacted-child loading",
+      "turn-ended-child loading",
+      "compacted-child completed",
+      "turn-ended-child completed",
+    ]);
+  });
+
+  test("keeps the parent sub-agent running when a child command fails during the child turn", async () => {
+    const session = createSession();
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "collabAgentToolCall",
@@ -4490,7 +5235,7 @@ describe("Codex app-server provider", () => {
         },
       },
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "child-thread-1",
       item: {
         type: "commandExecution",
@@ -4503,7 +5248,7 @@ describe("Codex app-server provider", () => {
       },
     });
 
-    expect(events.at(-1)?.item).toMatchObject({
+    expect(events.findLast((event) => event.type === "timeline")?.item).toMatchObject({
       type: "tool_call",
       callId: "call-sub-agent-child-command-failure",
       name: "Sub-agent",
@@ -4517,12 +5262,12 @@ describe("Codex app-server provider", () => {
     });
   });
 
-  test("does not synthesize a parent sub-agent failure from child error state alone", () => {
+  test("does not synthesize a parent sub-agent failure from child error state alone", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "collabAgentToolCall",
@@ -4584,14 +5329,13 @@ describe("Codex app-server provider", () => {
       }),
     };
 
-    await asInternals(session).loadPersistedHistory(session.client);
-
     const history: AgentStreamEvent[] = [];
     for await (const event of session.streamHistory()) {
       history.push(event);
     }
 
     expect(requests.map((request) => [request.method, request.params])).toEqual([
+      ["thread/read", { threadId: "test-thread", includeTurns: false }],
       ["thread/read", { threadId: "test-thread", includeTurns: true }],
     ]);
     expect(history).toEqual([
@@ -4638,7 +5382,7 @@ describe("Codex app-server provider", () => {
       })),
     };
 
-    await asInternals(session).loadPersistedHistory(session.client);
+    await Array.fromAsync(session.streamHistory());
 
     expect(asInternals(session).codexUserMessageTurns().resolve("message-history")).toEqual({
       index: 0,
@@ -4707,8 +5451,6 @@ describe("Codex app-server provider", () => {
       }),
     };
 
-    await asInternals(session).loadPersistedHistory(session.client);
-
     const history: AgentStreamEvent[] = [];
     for await (const event of session.streamHistory()) {
       history.push(event);
@@ -4773,11 +5515,11 @@ describe("Codex app-server provider", () => {
 
     const liveEvents: AgentStreamEvent[] = [];
     session.subscribe((event) => liveEvents.push(event));
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       threadId: "v2-child-thread",
       turn: { id: "v2-child-turn-after-resume" },
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "subAgentActivity",
@@ -4787,7 +5529,7 @@ describe("Codex app-server provider", () => {
         agentPath: "/root/v2-child",
       },
     });
-    asInternals(session).handleNotification("item/agentMessage/delta", {
+    await asInternals(session).handleNotification("item/agentMessage/delta", {
       threadId: "v2-child-thread",
       itemId: "v2-child-message-after-resume",
       delta: "More findings after resume.",
@@ -4801,25 +5543,25 @@ describe("Codex app-server provider", () => {
     );
     expect(liveToolCalls.at(-1)).toMatchObject({
       status: "running",
-      detail: { type: "sub_agent", log: "[Assistant] More findings after resume." },
+      detail: { type: "sub_agent", log: "" },
     });
 
     liveEvents.length = 0;
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       threadId: "legacy-child-thread",
       turn: { id: "legacy-child-turn-after-resume" },
     });
-    asInternals(session).handleNotification("item/agentMessage/delta", {
+    await asInternals(session).handleNotification("item/agentMessage/delta", {
       threadId: "legacy-child-thread",
       itemId: "legacy-child-message-after-resume",
       delta: "Legacy findings after resume.",
     });
-    expect(liveEvents.at(-1)).toMatchObject({
+    expect(liveEvents.findLast((event) => event.type === "timeline")).toMatchObject({
       type: "timeline",
       item: {
         callId: "legacy-spawn-history",
         status: "running",
-        detail: { type: "sub_agent", log: "[Assistant] Legacy findings after resume." },
+        detail: { type: "sub_agent", log: "" },
       },
     });
   });
@@ -4869,8 +5611,6 @@ describe("Codex app-server provider", () => {
       }),
     };
 
-    await asInternals(session).loadPersistedHistory(session.client);
-
     const history: AgentStreamEvent[] = [];
     for await (const event of session.streamHistory()) {
       history.push(event);
@@ -4934,8 +5674,6 @@ describe("Codex app-server provider", () => {
       }),
     };
 
-    await asInternals(session).loadPersistedHistory(session.client);
-
     const history: AgentStreamEvent[] = [];
     for await (const event of session.streamHistory()) {
       history.push(event);
@@ -5058,6 +5796,7 @@ describe("Codex app-server provider", () => {
         threadId: "child-thread",
         agentPath: "/root/child",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await child;
       appServer.beginsSubAgentActivity({
         callId: "parent-interacted",
@@ -5066,7 +5805,9 @@ describe("Codex app-server provider", () => {
         kind: "interacted",
         agentPath: "/root",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await resultPromise;
 
       expect(providerSubagentIds).toEqual(new Set(["child-thread"]));
@@ -5108,8 +5849,6 @@ describe("Codex app-server provider", () => {
       }),
     };
 
-    await asInternals(session).loadPersistedHistory(session.client);
-
     const history: AgentStreamEvent[] = [];
     for await (const event of session.streamHistory()) {
       history.push(event);
@@ -5169,8 +5908,6 @@ describe("Codex app-server provider", () => {
       }),
     };
 
-    await asInternals(session).loadPersistedHistory(session.client);
-
     const history: AgentStreamEvent[] = [];
     for await (const event of session.streamHistory()) {
       history.push(event);
@@ -5198,7 +5935,7 @@ describe("Codex app-server provider", () => {
     ]);
   });
 
-  test("captures live Codex user message ids from item events", () => {
+  test("captures live Codex user message ids from item events", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
@@ -5209,11 +5946,11 @@ describe("Codex app-server provider", () => {
       content: [{ type: "text", text: "Use the native Codex id." }],
     };
 
-    asInternals(session).handleNotification("item/started", {
+    await asInternals(session).handleNotification("item/started", {
       threadId: "test-thread",
       item: userMessageItem,
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: userMessageItem,
     });
@@ -5232,19 +5969,19 @@ describe("Codex app-server provider", () => {
     ]);
   });
 
-  test("emits Codex context compaction markers from live thread items", () => {
+  test("emits Codex context compaction markers from live thread items", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/started", {
+    await asInternals(session).handleNotification("item/started", {
       threadId: "test-thread",
       item: {
         type: "contextCompaction",
         id: "compact-live",
       },
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "contextCompaction",
@@ -5282,7 +6019,9 @@ describe("Codex app-server provider", () => {
         threadId: "thread-1",
         itemId: "compact-without-completion",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await terminalEvent;
 
       expect(
@@ -5304,11 +6043,14 @@ describe("Codex app-server provider", () => {
         threadId: "thread-1",
         itemId: "compact-completed-normally",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completesCompaction({
         threadId: "thread-1",
         itemId: "compact-completed-normally",
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await terminalEvent;
 
       expect(
@@ -5327,8 +6069,11 @@ describe("Codex app-server provider", () => {
 
     try {
       appServer.startsCompaction({ threadId: "thread-1", itemId: "current-compaction" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completesCompaction({ threadId: "thread-1", itemId: "older-compaction" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await terminalEvent;
 
       expect(
@@ -5350,10 +6095,12 @@ describe("Codex app-server provider", () => {
 
     try {
       appServer.startsCompaction({ threadId: "thread-1", itemId: `compact-${status}` });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       appServer.completeTurn({
         status,
         error: status === "failed" ? { message: "Compaction failed" } : null,
       });
+      await new Promise<void>((resolve) => setImmediate(resolve));
       await terminalEvent;
 
       expect(
@@ -5367,17 +6114,17 @@ describe("Codex app-server provider", () => {
     }
   });
 
-  test("emits and dedupes Codex thread/compacted notifications", () => {
+  test("emits and dedupes Codex thread/compacted notifications", async () => {
     const session = createSession();
     session.activeForegroundTurnId = null;
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("thread/compacted", {
+    await asInternals(session).handleNotification("thread/compacted", {
       threadId: "test-thread",
       turnId: "legacy-compact-turn",
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "contextCompaction",
@@ -5398,17 +6145,17 @@ describe("Codex app-server provider", () => {
     ]);
   });
 
-  test("emits consecutive Codex thread/compacted notifications", () => {
+  test("emits consecutive Codex thread/compacted notifications", async () => {
     const session = createSession();
     session.activeForegroundTurnId = null;
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("thread/compacted", {
+    await asInternals(session).handleNotification("thread/compacted", {
       threadId: "test-thread",
       turnId: "legacy-compact-turn-1",
     });
-    asInternals(session).handleNotification("thread/compacted", {
+    await asInternals(session).handleNotification("thread/compacted", {
       threadId: "test-thread",
       turnId: "legacy-compact-turn-2",
     });
@@ -5462,7 +6209,10 @@ describe("Codex app-server provider", () => {
     expect(session.currentThreadId).toBe("archived-thread-id");
     expect(requests).toEqual([
       { method: "thread/loaded/list", params: {} },
-      { method: "thread/resume", params: { threadId: "archived-thread-id" } },
+      {
+        method: "thread/resume",
+        params: { threadId: "archived-thread-id", excludeTurns: true },
+      },
     ]);
   });
 
@@ -5534,14 +6284,14 @@ describe("Codex app-server provider", () => {
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
     await handler?.run({ emit: (event) => events.push(event) });
-    asInternals(session).handleNotification("item/started", {
+    await asInternals(session).handleNotification("item/started", {
       threadId: "test-thread",
       item: {
         type: "contextCompaction",
         id: "manual-compact",
       },
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       threadId: "test-thread",
       item: {
         type: "contextCompaction",
@@ -5656,23 +6406,23 @@ describe("Codex app-server provider", () => {
     });
   });
 
-  test("emits a synthetic plan approval permission after a successful Codex plan turn", () => {
+  test("emits a synthetic plan approval permission after a successful Codex plan turn", async () => {
     const session = createSession({
       featureValues: { plan_mode: true, fast_mode: true },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       turn: { id: "turn-plan-1" },
     });
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       plan: [
         { step: "Inspect the existing auth flow", status: "completed" },
         { step: "Implement the button behavior", status: "pending" },
       ],
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
 
@@ -5726,24 +6476,24 @@ describe("Codex app-server provider", () => {
     });
   });
 
-  test("does not complete Codex plan timeline cards while plan approval is pending", () => {
+  test("does not complete Codex plan timeline cards while plan approval is pending", async () => {
     const session = createSession({
       featureValues: { plan_mode: true, fast_mode: true },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       turn: { id: "turn-plan-thread-item" },
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       item: {
         id: "plan-item-1",
         type: "plan",
         text: "- Inspect README\n- Add a short note",
       },
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
 
@@ -5772,28 +6522,28 @@ describe("Codex app-server provider", () => {
     });
   });
 
-  test("replaces a pending synthetic plan approval when a later plan completes", () => {
+  test("replaces a pending synthetic plan approval when a later plan completes", async () => {
     const session = createSession({
       featureValues: { plan_mode: true },
     });
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       turn: { id: "turn-plan-first" },
     });
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       plan: [{ step: "Implement the first plan", status: "pending" }],
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       turn: { id: "turn-plan-second" },
     });
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       plan: [{ step: "Implement the revised plan", status: "pending" }],
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
 
@@ -5812,13 +6562,13 @@ describe("Codex app-server provider", () => {
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       turn: { id: "turn-plan-pending" },
     });
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       plan: [{ step: "Implement the original plan", status: "pending" }],
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
     const pendingPlan = session.getPendingPermissions()[0];
@@ -5852,13 +6602,13 @@ describe("Codex app-server provider", () => {
       featureValues: { plan_mode: true },
     });
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       turn: { id: "turn-plan-pending" },
     });
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       plan: [{ step: "Implement the original plan", status: "pending" }],
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
     const pendingPlan = session.getPendingPermissions()[0];
@@ -5906,13 +6656,13 @@ describe("Codex app-server provider", () => {
       featureValues: { plan_mode: true },
     });
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       turn: { id: "turn-plan-pending" },
     });
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       plan: [{ step: "Implement the original plan", status: "pending" }],
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
 
@@ -5937,10 +6687,10 @@ describe("Codex app-server provider", () => {
 
     const startTurn = session.startTurn("Revise the plan");
     await promptRequested;
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       plan: [{ step: "Implement the newer plan", status: "pending" }],
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
     acceptPrompt?.();
@@ -5956,13 +6706,13 @@ describe("Codex app-server provider", () => {
       featureValues: { plan_mode: true },
     });
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       turn: { id: "turn-plan-pending" },
     });
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       plan: [{ step: "Implement the original plan", status: "pending" }],
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
     const pendingPlan = session.getPendingPermissions()[0];
@@ -5982,12 +6732,12 @@ describe("Codex app-server provider", () => {
     expect(session.getPendingPermissions()).toEqual([]);
   });
 
-  test("emits imageView paths with spaces as valid assistant markdown images", () => {
+  test("emits imageView paths with spaces as valid assistant markdown images", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       item: {
         id: "image-view-1",
         type: "imageView",
@@ -6013,12 +6763,12 @@ describe("Codex app-server provider", () => {
     ["saved_path", { saved_path: "/tmp/generated-snake.png" }, "file:///tmp/generated-snake.png"],
   ])(
     "emits imageGeneration thread items with %s as assistant markdown images",
-    (_fieldName, imageFields, expectedPath) => {
+    async (_fieldName, imageFields, expectedPath) => {
       const session = createSession();
       const events: AgentStreamEvent[] = [];
       session.subscribe((event) => events.push(event));
 
-      asInternals(session).handleNotification("item/completed", {
+      await asInternals(session).handleNotification("item/completed", {
         item: {
           id: `image-generation-${_fieldName}`,
           type: "imageGeneration",
@@ -6041,12 +6791,12 @@ describe("Codex app-server provider", () => {
     },
   );
 
-  test("materializes imageGeneration base64 results before rendering markdown", () => {
+  test("materializes imageGeneration base64 results before rendering markdown", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       item: {
         id: "image-generation-base64",
         type: "imageGeneration",
@@ -6194,21 +6944,22 @@ describe("Codex app-server provider", () => {
     }
   });
 
-  test("ignores incomplete imageGeneration thread items without failing the turn", () => {
+  test("ignores incomplete imageGeneration thread items without failing the turn", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    expect(() =>
-      asInternals(session).handleNotification("item/completed", {
-        item: {
-          id: "image-generation-incomplete",
-          type: "imageGeneration",
-          status: "in_progress",
-        },
-      }),
+    expect(
+      async () =>
+        await asInternals(session).handleNotification("item/completed", {
+          item: {
+            id: "image-generation-incomplete",
+            type: "imageGeneration",
+            status: "in_progress",
+          },
+        }),
     ).not.toThrow();
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
 
@@ -6231,12 +6982,12 @@ describe("Codex app-server provider", () => {
     ["no failure details", null, { message: "Image generation failed" }],
   ])(
     "emits failed imageGeneration items with %s as failed tool calls",
-    (_label, failure, expectedError) => {
+    async (_label, failure, expectedError) => {
       const session = createSession();
       const events: AgentStreamEvent[] = [];
       session.subscribe((event) => events.push(event));
 
-      asInternals(session).handleNotification("item/completed", {
+      await asInternals(session).handleNotification("item/completed", {
         item: {
           id: "image-generation-failed",
           type: "imageGeneration",
@@ -6296,8 +7047,6 @@ describe("Codex app-server provider", () => {
       })),
     };
 
-    await asInternals(session).loadPersistedHistory(session.client);
-
     const history: AgentStreamEvent[] = [];
     for await (const event of session.streamHistory()) {
       history.push(event);
@@ -6323,12 +7072,12 @@ describe("Codex app-server provider", () => {
     ]);
   });
 
-  test("emits usage_updated on token usage updates and keeps usage on turn completion", () => {
+  test("emits usage_updated on token usage updates and keeps usage on turn completion", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("thread/tokenUsage/updated", {
+    await asInternals(session).handleNotification("thread/tokenUsage/updated", {
       tokenUsage: {
         model_context_window: 200000,
         last: {
@@ -6339,7 +7088,7 @@ describe("Codex app-server provider", () => {
         },
       },
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
 
@@ -6369,20 +7118,20 @@ describe("Codex app-server provider", () => {
     });
   });
 
-  test("streams Codex assistant message deltas and does not replay completed text", () => {
+  test("streams Codex assistant message deltas and does not replay completed text", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/agentMessage/delta", {
+    await asInternals(session).handleNotification("item/agentMessage/delta", {
       itemId: "assistant-item-1",
       delta: "Hel",
     });
-    asInternals(session).handleNotification("item/agentMessage/delta", {
+    await asInternals(session).handleNotification("item/agentMessage/delta", {
       itemId: "assistant-item-1",
       delta: "lo",
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       item: {
         id: "assistant-item-1",
         type: "agentMessage",
@@ -6406,20 +7155,20 @@ describe("Codex app-server provider", () => {
     ]);
   });
 
-  test("emits only the missing assistant suffix when completed text extends streamed deltas", () => {
+  test("emits only the missing assistant suffix when completed text extends streamed deltas", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/agentMessage/delta", {
+    await asInternals(session).handleNotification("item/agentMessage/delta", {
       itemId: "assistant-item-2",
       delta: "Hel",
     });
-    asInternals(session).handleNotification("item/agentMessage/delta", {
+    await asInternals(session).handleNotification("item/agentMessage/delta", {
       itemId: "assistant-item-2",
       delta: "lo",
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       item: {
         id: "assistant-item-2",
         type: "agentMessage",
@@ -6449,24 +7198,24 @@ describe("Codex app-server provider", () => {
     ]);
   });
 
-  test("emits a markdown divider when a new Codex assistant item starts after the previous one completed", () => {
+  test("emits a markdown divider when a new Codex assistant item starts after the previous one completed", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/agentMessage/delta", {
+    await asInternals(session).handleNotification("item/agentMessage/delta", {
       itemId: "assistant-item-3",
       delta:
         "I’m in the waiting phase now. The next read is intentionally delayed so we get meaningful CI state instead of churn.",
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       item: {
         id: "assistant-item-3",
         type: "agentMessage",
         text: "I’m in the waiting phase now. The next read is intentionally delayed so we get meaningful CI state instead of churn.",
       },
     });
-    asInternals(session).handleNotification("item/agentMessage/delta", {
+    await asInternals(session).handleNotification("item/agentMessage/delta", {
       itemId: "assistant-item-4",
       delta:
         "CI is still cooking. I’m staying on the current run rather than jumping around, because the first red job will tell us exactly whether anything else needs work.",
@@ -6496,20 +7245,20 @@ describe("Codex app-server provider", () => {
     ]);
   });
 
-  test("streams Codex reasoning deltas and does not replay completed reasoning", () => {
+  test("streams Codex reasoning deltas and does not replay completed reasoning", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/reasoning/summaryTextDelta", {
+    await asInternals(session).handleNotification("item/reasoning/summaryTextDelta", {
       itemId: "reasoning-item-1",
       delta: "Think",
     });
-    asInternals(session).handleNotification("item/reasoning/summaryTextDelta", {
+    await asInternals(session).handleNotification("item/reasoning/summaryTextDelta", {
       itemId: "reasoning-item-1",
       delta: "ing",
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       item: {
         id: "reasoning-item-1",
         type: "reasoning",
@@ -6533,20 +7282,20 @@ describe("Codex app-server provider", () => {
     ]);
   });
 
-  test("emits only the missing reasoning suffix when completed reasoning extends streamed deltas", () => {
+  test("emits only the missing reasoning suffix when completed reasoning extends streamed deltas", async () => {
     const session = createSession();
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("item/reasoning/summaryTextDelta", {
+    await asInternals(session).handleNotification("item/reasoning/summaryTextDelta", {
       itemId: "reasoning-item-2",
       delta: "Think",
     });
-    asInternals(session).handleNotification("item/reasoning/summaryTextDelta", {
+    await asInternals(session).handleNotification("item/reasoning/summaryTextDelta", {
       itemId: "reasoning-item-2",
       delta: "ing",
     });
-    asInternals(session).handleNotification("item/completed", {
+    await asInternals(session).handleNotification("item/completed", {
       item: {
         id: "reasoning-item-2",
         type: "reasoning",
@@ -6583,13 +7332,13 @@ describe("Codex app-server provider", () => {
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       turn: { id: "turn-plan-2" },
     });
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       plan: [{ step: "Implement the new flow", status: "pending" }],
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
 
@@ -6637,13 +7386,13 @@ describe("Codex app-server provider", () => {
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       turn: { id: "turn-plan-3" },
     });
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       plan: [{ step: "Implement the safe flow", status: "pending" }],
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
 
@@ -6705,13 +7454,13 @@ describe("Codex app-server provider", () => {
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
 
-    asInternals(session).handleNotification("turn/started", {
+    await asInternals(session).handleNotification("turn/started", {
       turn: { id: "turn-plan-4" },
     });
-    asInternals(session).handleNotification("turn/plan/updated", {
+    await asInternals(session).handleNotification("turn/plan/updated", {
       plan: [{ step: "Implement the fast flow", status: "pending" }],
     });
-    asInternals(session).handleNotification("turn/completed", {
+    await asInternals(session).handleNotification("turn/completed", {
       turn: { status: "completed", error: null },
     });
 
@@ -6895,9 +7644,21 @@ describe("Codex importable sessions", () => {
   const threadsByModelProvider = [
     { id: "stock-thread", cwd: "/workspace/project-a", modelProvider: "openai", updatedAt: 2 },
     { id: "custom-thread", cwd: "/workspace/project-a", modelProvider: "my-codex", updatedAt: 1 },
+    {
+      id: "new-custom-thread",
+      cwd: "/workspace/project-a",
+      modelProvider: "paseo:my-codex",
+      updatedAt: 3,
+    },
+    {
+      id: "other-custom-thread",
+      cwd: "/workspace/project-a",
+      modelProvider: "paseo-my-codex",
+      updatedAt: 4,
+    },
   ];
 
-  test("a custom Codex provider lists the threads it created", async () => {
+  test("a custom Codex provider lists its old and namespaced threads without other providers", async () => {
     const appServer = createFakeCodexAppServer({
       "thread/list": providerFilteringThreadListHandler(threadsByModelProvider),
     });
@@ -6910,10 +7671,40 @@ describe("Codex importable sessions", () => {
 
     const sessions = await provider.listImportableSessions({ cwd: "/workspace/project-a" });
 
-    expect(sessions.map((session) => session.providerHandleId)).toEqual(["custom-thread"]);
+    expect(sessions.map((session) => session.providerHandleId)).toEqual([
+      "custom-thread",
+      "new-custom-thread",
+    ]);
     appServer.assertNoErrors();
   });
 
+  test.each(["openai", "ollama", "lmstudio", "amazon-bedrock", "amazon-bedrock-runtime", "gcp"])(
+    "a custom provider named %s excludes native built-in sessions",
+    async (providerId) => {
+      const appServer = createFakeCodexAppServer({
+        "thread/list": providerFilteringThreadListHandler([
+          { id: "native-thread", cwd: "/workspace/project-a", modelProvider: providerId },
+          {
+            id: "custom-thread",
+            cwd: "/workspace/project-a",
+            modelProvider: `paseo:${providerId}`,
+          },
+        ]),
+      });
+      const provider = createProviderWithFakeAppServer(appServer, {
+        runtimeSettings: {
+          env: { OPENAI_BASE_URL: "https://llm.example.test/v1", OPENAI_API_KEY: "test-key" },
+        },
+        customProvider: { id: providerId, label: "Custom Codex", extends: "codex" },
+      });
+
+      const sessions = await provider.listImportableSessions({ cwd: "/workspace/project-a" });
+
+      expect(sessions.map((session) => session.providerHandleId)).toEqual(["custom-thread"]);
+      appServer.assertNoErrors();
+    },
+  );
+
   test("stock Codex keeps listing only its own threads", async () => {
     const appServer = createFakeCodexAppServer({
       "thread/list": providerFilteringThreadListHandler(threadsByModelProvider),
@@ -7113,7 +7904,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();
@@ -7182,6 +7973,7 @@ test("Codex runtime safety queries live terminals and retains unsupported app se
     await appServer.waitForTurnStart();
     expect(await session.canStopRuntime()).toBe(false);
     appServer.completeTurn({ threadId: "thread-1" });
+    await new Promise<void>((resolve) => setImmediate(resolve));
     await expect.poll(() => session.canStopRuntime()).toBe(true);
     response = { data: [{ processId: "shell-1" }], nextCursor: null };
     expect(await session.canStopRuntime()).toBe(false);
@@ -7199,3 +7991,150 @@ test("Codex runtime safety queries live terminals and retains unsupported app se
     await session.close();
   }
 });
+
+test("publishes a materialized image before dispatching the following turn completion", async () => {
+  const appServer = createFakeCodexAppServer();
+  const session = new CodexAppServerAgentSession(
+    createConfig(),
+    null,
+    createTestLogger(),
+    async () => appServer.child,
+  );
+  const events: AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  try {
+    await session.startTurn("generate an image");
+    const data = Buffer.alloc(1024 * 1024, 47).toString("base64");
+    const imageFrame =
+      JSON.stringify({
+        method: "item/completed",
+        params: {
+          item: {
+            id: "ordered-image",
+            type: "imageGeneration",
+            status: "completed",
+            result: { data, mimeType: "image/png" },
+          },
+        },
+      }) + "\n";
+    const completed = new Promise<void>((resolve) =>
+      session.subscribe((event) => {
+        if (event.type === "turn_completed") resolve();
+      }),
+    );
+    appServer.child.stdout.write(imageFrame);
+    appServer.child.stdout.write(
+      JSON.stringify({
+        method: "turn/completed",
+        params: { turn: { status: "completed", error: null } },
+      }) + "\n",
+    );
+    await completed;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    const imageIndex = events.findIndex(
+      (event) =>
+        event.type === "timeline" &&
+        event.item.type === "assistant_message" &&
+        event.item.text.includes("![Image]"),
+    );
+    const completedIndex = events.findIndex((event) => event.type === "turn_completed");
+    expect(imageIndex).toBeGreaterThanOrEqual(0);
+    expect(imageIndex).toBeLessThan(completedIndex);
+    const imageEvent = events[imageIndex];
+    if (imageEvent.type !== "timeline" || imageEvent.item.type !== "assistant_message")
+      throw new Error("Expected image");
+    expect(existsSync(markdownImageSource(imageEvent.item.text))).toBe(true);
+  } finally {
+    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 f438c98ec4..b031ae410e 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,3 +1,4 @@
+import { CodexBackgroundInventory } from "./codex/background-inventory.js";
 import { validateProviderOptions } from "../provider-options.js";
 import {
   getAgentStreamEventTurnId,
@@ -49,17 +50,19 @@ import { Dirent } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { z } from "zod";
 import { renderPromptAttachmentAsText } from "../prompt-attachments.js";
 import { composeSystemPromptParts } from "../system-prompt.js";
-import { curateAgentActivity } from "../activity-curator.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,
@@ -92,12 +95,18 @@ import {
   type CodexAppServerTraceContext,
 } from "./codex/app-server-transport.js";
 import { type CodexUserMessageTurnIndex, revertCodexConversation } from "./codex/rewind.js";
+import {
+  type CodexHistoryRow,
+  CodexThreadHistoryTooLargeError,
+  readCodexThreadHistory,
+} from "./codex/thread-history.js";
 import {
   materializeProviderImage,
   renderProviderImageOutputAsAssistantMarkdown,
   type ProviderImageOutput,
 } from "./provider-image-output.js";
 import { normalizeProviderReplayTimestamp } from "../provider-history-timestamps.js";
+import { limitAgentTimelineItemContent } from "../agent-timeline-content.js";
 import {
   formatProviderDiagnostic,
   formatProviderDiagnosticError,
@@ -144,7 +153,26 @@ 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.
+const CODEX_BUILTIN_MODEL_PROVIDER_IDS = new Set([
+  "openai",
+  "ollama",
+  "lmstudio",
+  "amazon-bedrock",
+  "amazon-bedrock-runtime",
+  "gcp",
+]);
 // Codex treats most app-server client names as the model-request originator.
 // This reserved Codex name is non-originating, so requests keep Codex's default
 // CLI identity instead of showing up as Paseo in provider usage logs.
@@ -496,6 +524,11 @@ interface PersistedTimelineEntry {
   providerTurnId?: string;
 }
 
+interface CodexThreadHistory {
+  timeline: PersistedTimelineEntry[];
+  providerSubagentEvents: AgentStreamEvent[];
+}
+
 interface PersistedSubAgentRoute {
   childThreadId: string;
   toolCall: ToolCallTimelineItem;
@@ -1372,6 +1405,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 {
@@ -1504,6 +1546,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);
@@ -1523,6 +1566,7 @@ function parseCodexPatchChanges(changes: unknown): CodexPatchFileChange[] {
           (typeof recordChanges.type === "string" && recordChanges.type) ||
           undefined,
         content: extractPatchLikeText(recordChanges),
+        movePath: codexPatchMovePath(recordChanges),
       },
     ];
   }
@@ -1542,6 +1586,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);
@@ -1650,6 +1695,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;
@@ -1660,11 +1730,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,
@@ -1799,22 +1865,13 @@ function readCodexHistoryTimestamp(item: unknown): string | null {
   );
 }
 
-function readCodexTurnHistoryTimestamp(
-  turn: unknown,
+/** Falls back to the row's start time for a user message and its end time otherwise. */
+function readCodexHistoryRowTimestamp(
+  row: CodexHistoryRow,
   timelineItem: AgentTimelineItem,
 ): string | null {
-  const record = toObjectRecord(turn);
-  if (!record) {
-    return null;
-  }
-
-  const startedAt =
-    normalizeProviderReplayTimestamp(record.startedAt) ??
-    normalizeProviderReplayTimestamp(record.started_at);
-  const completedAt =
-    normalizeProviderReplayTimestamp(record.completedAt) ??
-    normalizeProviderReplayTimestamp(record.completed_at);
-
+  const startedAt = normalizeProviderReplayTimestamp(row.startedAt);
+  const completedAt = normalizeProviderReplayTimestamp(row.completedAt);
   if (timelineItem.type === "user_message") {
     return startedAt ?? completedAt;
   }
@@ -1939,12 +1996,12 @@ function codexImageOutputFromResult(result: unknown): ProviderImageOutput | null
   };
 }
 
-function mapCodexThreadImageItem(
+async function mapCodexThreadImageItem(
   normalizedType: string,
   normalizedItem: Record<string, unknown>,
-): AgentTimelineItem | null {
+): Promise<AgentTimelineItem | null> {
   if (normalizedType === "imageView") {
-    return renderProviderImageOutputAsAssistantMarkdown({
+    return await renderProviderImageOutputAsAssistantMarkdown({
       path: firstStringField(normalizedItem, ["path"]),
     });
   }
@@ -1960,7 +2017,7 @@ function mapCodexThreadImageItem(
 
   const savedPath = firstStringField(normalizedItem, ["savedPath", "saved_path"]);
   const result = codexImageOutputFromResult(normalizedItem.result);
-  return renderProviderImageOutputAsAssistantMarkdown(
+  return await renderProviderImageOutputAsAssistantMarkdown(
     {
       path: savedPath ?? result?.path ?? null,
       url: result?.url ?? null,
@@ -1982,10 +2039,10 @@ function mapCodexAgentMessage(item: Record<string, unknown>): AgentTimelineItem
   };
 }
 
-export function threadItemToTimeline(
+export async function threadItemToTimeline(
   item: unknown,
   options?: { includeUserMessage?: boolean; cwd?: string | null },
-): AgentTimelineItem | null {
+): Promise<AgentTimelineItem | null> {
   const itemRecord = toObjectRecord(item);
   if (!itemRecord) return null;
   const includeUserMessage = options?.includeUserMessage ?? true;
@@ -1999,7 +2056,7 @@ export function threadItemToTimeline(
       : itemRecord;
 
   if (normalizedType === "imageView" || normalizedType === "imageGeneration") {
-    return mapCodexThreadImageItem(normalizedType, normalizedItem);
+    return await mapCodexThreadImageItem(normalizedType, normalizedItem);
   }
   if (normalizedType && CODEX_TOOL_THREAD_ITEM_TYPES.has(normalizedType)) {
     return mapCodexToolCallFromThreadItem(normalizedItem, { cwd });
@@ -2024,7 +2081,7 @@ export function threadItemToTimeline(
   }
 }
 
-function mcpToolResultImagesToTimeline(item: unknown): AgentTimelineItem[] {
+async function mcpToolResultImagesToTimeline(item: unknown): Promise<AgentTimelineItem[]> {
   const itemRecord = toObjectRecord(item);
   if (!itemRecord) {
     return [];
@@ -2037,104 +2094,40 @@ function mcpToolResultImagesToTimeline(item: unknown): AgentTimelineItem[] {
   }
 
   const { images } = splitCodexMcpToolResultImages(itemRecord.result);
-  return images
-    .map((image) =>
-      renderProviderImageOutputAsAssistantMarkdown(image, {
-        materialize: materializeProviderImage,
-      }),
-    )
-    .filter((timelineItem): timelineItem is AgentTimelineItem => timelineItem !== null);
+  const items: AgentTimelineItem[] = [];
+  for (const image of images) {
+    const imageItem = await renderProviderImageOutputAsAssistantMarkdown(image, {
+      materialize: materializeProviderImage,
+    });
+    if (imageItem) items.push(imageItem);
+  }
+  return items;
 }
 
-function threadItemToTimelineEntries(
+async function threadItemToTimelineEntries(
   item: unknown,
   options?: { includeUserMessage?: boolean; cwd?: string | null },
-): AgentTimelineItem[] {
-  const timelineItem = threadItemToTimeline(item, options);
+): Promise<AgentTimelineItem[]> {
+  const timelineItem = await threadItemToTimeline(item, options);
   if (!timelineItem) {
     return [];
   }
-  return [timelineItem, ...mcpToolResultImagesToTimeline(item)];
-}
-
-const CodexThreadReadResponseSchema = z
-  .object({
-    thread: z
-      .object({
-        turns: z
-          .array(
-            z
-              .object({
-                items: z.array(z.unknown()).default([]),
-              })
-              .passthrough(),
-          )
-          .default([]),
-      })
-      .passthrough()
-      .default({ turns: [] }),
-  })
-  .passthrough();
-
-type CodexThreadReadResponse = z.infer<typeof CodexThreadReadResponseSchema>;
-type CodexThreadReadRequest = (threadId: string) => Promise<unknown>;
-
-async function requestCodexThreadHistory(
-  requestThread: CodexThreadReadRequest,
-  threadId: string,
-): Promise<CodexThreadReadResponse> {
-  const response = await requestThread(threadId);
-  return CodexThreadReadResponseSchema.parse(response);
+  return [timelineItem, ...(await mcpToolResultImagesToTimeline(item))];
 }
 
 async function loadCodexThreadHistoryTimeline(params: {
+  client: CodexAppServerClientLike;
   threadId: string;
   cwd: string | null;
-  requestThread: CodexThreadReadRequest;
 }): Promise<CodexThreadHistoryProjection> {
-  const response = await requestCodexThreadHistory(params.requestThread, params.threadId);
   const timeline: PersistedTimelineEntry[] = [];
   const subAgentTimelineIndexByThreadId = new Map<string, number>();
-  for (const turn of response.thread.turns) {
-    for (const item of turn.items) {
-      const historicalSubAgentActivity = readCodexSubAgentActivity(item);
-      if (historicalSubAgentActivity) {
-        const existingIndex = subAgentTimelineIndexByThreadId.get(
-          historicalSubAgentActivity.agentThreadId,
-        );
-        if (existingIndex !== undefined) {
-          const activityTimelineItem = threadItemToTimeline(item, { cwd: params.cwd });
-          updateHistoricalSubAgentActivity(
-            timeline,
-            existingIndex,
-            historicalSubAgentActivity.kind,
-            activityTimelineItem?.type === "tool_call" &&
-              activityTimelineItem.detail.type === "sub_agent"
-              ? activityTimelineItem.detail.subAgentType
-              : undefined,
-          );
-          continue;
-        }
-      }
-      for (const timelineItem of threadItemToTimelineEntries(item, { cwd: params.cwd })) {
-        const timestamp =
-          readCodexHistoryTimestamp(item) ?? readCodexTurnHistoryTimestamp(turn, timelineItem);
-        const settledTimelineItem =
-          historicalSubAgentActivity && timelineItem.type === "tool_call"
-            ? settleHistoricalSubAgentActivity(timelineItem, historicalSubAgentActivity.kind)
-            : timelineItem;
-        timeline.push({
-          item: settledTimelineItem,
-          timestamp: timestamp ?? undefined,
-          ...(timelineItem.type === "user_message" && typeof turn.id === "string"
-            ? { providerTurnId: turn.id }
-            : {}),
-        });
-        for (const childThreadId of readCodexHistoricalSubAgentThreadIds(item)) {
-          subAgentTimelineIndexByThreadId.set(childThreadId, timeline.length - 1);
-        }
-      }
-    }
+  try {
+    await projectCodexThreadHistory(params, { timeline, subAgentTimelineIndexByThreadId });
+  } catch (error) {
+    if (!(error instanceof CodexThreadHistoryTooLargeError)) throw error;
+    // The session stays usable; the row says why the history stops here.
+    timeline.push({ item: { type: "notification", level: "warning", message: error.message } });
   }
   const subAgentRoutes = Array.from(subAgentTimelineIndexByThreadId.entries()).flatMap(
     ([childThreadId, timelineIndex]): PersistedSubAgentRoute[] => {
@@ -2147,11 +2140,55 @@ async function loadCodexThreadHistoryTimeline(params: {
   return { timeline, subAgentRoutes };
 }
 
-function readCodexThread(client: CodexAppServerClientLike, threadId: string): Promise<unknown> {
-  return client.request("thread/read", {
-    threadId,
-    includeTurns: true,
-  });
+async function projectCodexThreadHistory(
+  params: { client: CodexAppServerClientLike; threadId: string; cwd: string | null },
+  projection: {
+    timeline: PersistedTimelineEntry[];
+    subAgentTimelineIndexByThreadId: Map<string, number>;
+  },
+): Promise<void> {
+  const { timeline, subAgentTimelineIndexByThreadId } = projection;
+  for await (const row of readCodexThreadHistory(params.client, params.threadId)) {
+    const { item } = row;
+    const historicalSubAgentActivity = readCodexSubAgentActivity(item);
+    if (historicalSubAgentActivity) {
+      const existingIndex = subAgentTimelineIndexByThreadId.get(
+        historicalSubAgentActivity.agentThreadId,
+      );
+      if (existingIndex !== undefined) {
+        const activityTimelineItem = await threadItemToTimeline(item, { cwd: params.cwd });
+        updateHistoricalSubAgentActivity(
+          timeline,
+          existingIndex,
+          historicalSubAgentActivity.kind,
+          activityTimelineItem?.type === "tool_call" &&
+            activityTimelineItem.detail.type === "sub_agent"
+            ? activityTimelineItem.detail.subAgentType
+            : undefined,
+        );
+        continue;
+      }
+    }
+    for (const timelineItem of await threadItemToTimelineEntries(item, { cwd: params.cwd })) {
+      const timestamp =
+        readCodexHistoryTimestamp(item) ?? readCodexHistoryRowTimestamp(row, timelineItem);
+      const settledTimelineItem =
+        historicalSubAgentActivity && timelineItem.type === "tool_call"
+          ? settleHistoricalSubAgentActivity(timelineItem, historicalSubAgentActivity.kind)
+          : timelineItem;
+      timeline.push({
+        // Cap each item as it is projected so a large history is never held uncapped.
+        item: limitAgentTimelineItemContent(settledTimelineItem),
+        timestamp: timestamp ?? undefined,
+        ...(timelineItem.type === "user_message" && row.turnId !== undefined
+          ? { providerTurnId: row.turnId }
+          : {}),
+      });
+      for (const childThreadId of readCodexHistoricalSubAgentThreadIds(item)) {
+        subAgentTimelineIndexByThreadId.set(childThreadId, timeline.length - 1);
+      }
+    }
+  }
 }
 
 export async function forkCodexThread(
@@ -3290,10 +3327,12 @@ export async function codexAppServerTurnInputFromPrompt(
     }
     if (block.type === "image") {
       try {
-        const filePath = materializeProviderImage({
-          data: block.data,
-          mimeType: block.mimeType,
-        }).path;
+        const filePath = (
+          await materializeProviderImage({
+            data: block.data,
+            mimeType: block.mimeType,
+          })
+        ).path;
         output.push({ type: "localImage", path: filePath });
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -3384,10 +3423,14 @@ function buildCodexCustomProviderConfig(
     providerConfig.env_key = "OPENAI_API_KEY";
     providerConfig.requires_openai_auth = false;
   }
+  // Namespace Paseo ids so they cannot override Codex's built-ins. A colon is
+  // forbidden in Paseo ids, keeping these keys distinct from every legacy id
+  // when both generations are listed together.
+  const providerKey = `paseo:${customProvider.id}`;
   return {
-    model_provider: customProvider.id,
+    model_provider: providerKey,
     model_providers: {
-      [customProvider.id]: providerConfig,
+      [providerKey]: providerConfig,
     },
   };
 }
@@ -3400,8 +3443,6 @@ interface CodexSubAgentCallState {
   activityItemIds: Set<string>;
   pendingCommandOutputDeltas: Map<string, string[]>;
   pendingFileChangeOutputDeltas: Map<string, string[]>;
-  childItemOrder: string[];
-  childItems: Map<string, AgentTimelineItem>;
   childThreadIds: Set<string>;
 }
 
@@ -3439,6 +3480,9 @@ export class CodexAppServerAgentSession implements AgentSession {
   > | 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;
@@ -3451,6 +3495,7 @@ 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;
@@ -3461,10 +3506,12 @@ export class CodexAppServerAgentSession implements AgentSession {
   private serviceTier: string | null = null;
   private speedModels: CodexModel[] = [];
   private planModeEnabled = false;
-  private historyPending = false;
-  private persistedHistory: PersistedTimelineEntry[] = [];
-  private loadingPersistedHistory = false;
-  private persistedProviderSubagentEvents: AgentStreamEvent[] = [];
+  // History read by rewind or an archived resume, held until streamHistory consumes it.
+  private stagedHistory: CodexThreadHistory | null = null;
+  // Collects provider subagent events emitted while a thread history read rebuilds routes.
+  private historySubagentEvents: AgentStreamEvent[] | null = null;
+  // A resumed thread's earlier turns and sub-agents are known only after reading its history.
+  private historyIndexed = true;
   private pendingPermissions = new Map<string, AgentPermissionRequest>();
   private mcpElicitationPermissionIds = new Map<number, string>();
   private pendingPermissionHandlers = new Map<string, CodexPendingPermissionHandler>();
@@ -3473,8 +3520,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 }>
@@ -3501,6 +3557,9 @@ export class CodexAppServerAgentSession implements AgentSession {
   private compactionTriggerByItemId = new Map<string, "auto" | "manual">();
   private pendingRootCompactionItemIds = new Set<string>();
   private pendingAnonymousRootCompactions = 0;
+  // Child threads with a compaction shown as loading. Some Codex builds settle it only through
+  // `thread/compacted` or the end of the child's turn.
+  private pendingChildCompactionThreadIds = new Set<string>();
   // Codex can report one completed compaction through both channels:
   // `thread/compacted` and a completed `contextCompaction` item.
   private unpairedCompactionNotificationCompletions = 0;
@@ -3571,7 +3630,8 @@ export class CodexAppServerAgentSession implements AgentSession {
 
     if (this.resumeHandle?.sessionId) {
       this.currentThreadId = this.resumeHandle.sessionId;
-      this.historyPending = true;
+      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 = [];
     }
@@ -3619,7 +3679,7 @@ export class CodexAppServerAgentSession implements AgentSession {
 
   private async establishConnection(): Promise<void> {
     if (this.initialResumePurpose === "history") {
-      await this.readArchivedHistory();
+      this.stagedHistory = await this.readArchivedHistory();
       this.connectionState = "history-ready";
       return;
     }
@@ -3652,7 +3712,6 @@ export class CodexAppServerAgentSession implements AgentSession {
 
       if (this.currentThreadId) {
         await this.ensureThreadLoaded();
-        await this.loadPersistedHistory(this.client);
         await this.applyDefaultModelAndThinking();
       }
 
@@ -3660,6 +3719,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) {
@@ -3711,6 +3771,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) {
@@ -3967,39 +4028,40 @@ export class CodexAppServerAgentSession implements AgentSession {
     );
   }
 
-  private async readArchivedHistory(): Promise<void> {
+  private async readArchivedHistory(): Promise<CodexThreadHistory> {
     const child = await this.spawnAppServer();
     const client = new CodexAppServerClient(child, this.logger, () => this.traceContext());
     try {
       await client.request("initialize", buildCodexAppServerInitializeParams());
       client.notify("initialized", {});
-      await this.loadPersistedHistory(client);
+      return await this.readThreadHistory(client);
     } finally {
       await client.dispose();
     }
   }
 
-  private async loadPersistedHistory(client: CodexAppServerClientLike | null): Promise<void> {
-    if (!client || !this.currentThreadId) return;
-    const threadId = this.currentThreadId;
-
-    const history = await loadCodexThreadHistoryTimeline({
-      threadId,
+  // Reads the thread and its sub-agent threads, rebuilding the turn index and
+  // sub-agent routes. The caller owns the returned history; nothing retains it.
+  private async readThreadHistory(
+    client: CodexAppServerClientLike | null,
+  ): Promise<CodexThreadHistory> {
+    if (!client || !this.currentThreadId) {
+      return { timeline: [], providerSubagentEvents: [] };
+    }
+    const { timeline, subAgentRoutes } = await loadCodexThreadHistoryTimeline({
+      client,
+      threadId: this.currentThreadId,
       cwd: this.config.cwd ?? null,
-      requestThread: (threadIdToRead) => {
-        return readCodexThread(client, threadIdToRead);
-      },
     });
-    const { timeline, subAgentRoutes } = history;
     this.subAgentCallsByCallId.clear();
     this.subAgentCallIdByChildThreadId.clear();
     this.pendingSubAgentNotificationsByThreadId.clear();
-    this.persistedProviderSubagentEvents = [];
-    this.loadingPersistedHistory = true;
+    const providerSubagentEvents: AgentStreamEvent[] = [];
+    this.historySubagentEvents = providerSubagentEvents;
     try {
       await this.loadPersistedSubAgentHistories(client, subAgentRoutes);
     } finally {
-      this.loadingPersistedHistory = false;
+      this.historySubagentEvents = null;
     }
     this.resetCodexUserMessageTurns();
     for (const entry of timeline) {
@@ -4010,8 +4072,15 @@ export class CodexAppServerAgentSession implements AgentSession {
         this.rememberCodexUserMessageTurn(entry.item.messageId, entry.providerTurnId);
       }
     }
-    this.persistedHistory = timeline;
-    this.historyPending = timeline.length > 0;
+    this.historyIndexed = true;
+    return { timeline, providerSubagentEvents };
+  }
+
+  // Turns and rewind route by the thread's earlier turns and sub-agents. A resumed
+  // session whose projection Paseo already holds reads them here and drops the rest.
+  private async ensureHistoryIndexed(): Promise<void> {
+    if (this.historyIndexed) return;
+    await this.readThreadHistory(this.client);
   }
 
   private async loadPersistedSubAgentHistories(
@@ -4038,9 +4107,9 @@ export class CodexAppServerAgentSession implements AgentSession {
       });
       try {
         const childHistory = await loadCodexThreadHistoryTimeline({
+          client,
           threadId: next.route.childThreadId,
           cwd: this.config.cwd ?? null,
-          requestThread: (childThreadId) => readCodexThread(client, childThreadId),
         });
         for (const entry of childHistory.timeline) {
           this.emitProviderSubagentTimeline(next.route.childThreadId, entry.item, entry.timestamp);
@@ -4063,7 +4132,13 @@ export class CodexAppServerAgentSession implements AgentSession {
 
   private async ensureThreadLoaded(): Promise<void> {
     if (!this.client || !this.currentThreadId) return;
-    const params: Record<string, unknown> = { threadId: this.currentThreadId };
+    // Paseo reads history only when it replays it; the resume response needs no turns.
+    const params: Record<string, unknown> = { threadId: this.currentThreadId, excludeTurns: true };
+    if (this.deps.customCodexConfig) {
+      // Resume otherwise prefers the provider stored on the thread, including
+      // the unnamespaced key emitted by earlier Paseo versions.
+      params.modelProvider = this.deps.customCodexConfig.model_provider;
+    }
     const developerInstructions = composeSystemPromptParts(
       this.config.systemPrompt,
       this.config.daemonAppendSystemPrompt,
@@ -4370,6 +4445,7 @@ export class CodexAppServerAgentSession implements AgentSession {
     this.dismissPendingPlanApprovals("Dismissed by a new prompt");
 
     try {
+      await this.pendingNotifications;
       await this.connect();
       if (!this.client) {
         throw new Error("Codex client not initialized");
@@ -4382,6 +4458,7 @@ export class CodexAppServerAgentSession implements AgentSession {
 
       if (this.currentThreadId) {
         await this.ensureThreadLoaded();
+        await this.ensureHistoryIndexed();
       } else {
         await this.ensureThread();
       }
@@ -4411,6 +4488,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");
       }
@@ -4436,9 +4516,18 @@ export class CodexAppServerAgentSession implements AgentSession {
   ): Promise<SteerResult> {
     const client = this.client;
     const threadId = this.currentThreadId;
-    const nativeTurnId = this.currentTurnId;
+    let nativeTurnId = this.currentTurnId;
     const foregroundTurnId = this.activeForegroundTurnId;
-    if (!client || !threadId || !nativeTurnId || foregroundTurnId !== options.expectedTurnId) {
+    if (!client || !threadId || foregroundTurnId !== options.expectedTurnId) {
+      return { status: "unavailable" };
+    }
+    const pendingIdentification = this.pendingForegroundTurnIdentification;
+    // The start acknowledgement precedes the notification that identifies the native
+    // turn. Keep this steer attached to the accepted foreground turn while it arrives.
+    if (!nativeTurnId && pendingIdentification?.foregroundTurnId === foregroundTurnId) {
+      nativeTurnId = await pendingIdentification.promise;
+    }
+    if (!nativeTurnId) {
       return { status: "unavailable" };
     }
     if (await this.resolveSlashCommandInvocation(prompt)) return { status: "unavailable" };
@@ -4549,27 +4638,20 @@ 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);
     };
   }
 
   async *streamHistory(): AsyncGenerator<AgentStreamEvent> {
-    if (
-      (!this.historyPending || this.persistedHistory.length === 0) &&
-      this.persistedProviderSubagentEvents.length === 0
-    ) {
-      return;
-    }
-    const history = this.persistedHistory;
-    const providerSubagents = this.persistedProviderSubagentEvents;
-    this.persistedHistory = [];
-    this.persistedProviderSubagentEvents = [];
-    this.historyPending = false;
-    for (const event of providerSubagents) {
+    const history = this.stagedHistory ?? (await this.readThreadHistory(this.client));
+    this.stagedHistory = null;
+    for (const event of history.providerSubagentEvents) {
       yield event;
     }
-    for (const entry of history) {
+    for (const entry of history.timeline) {
       yield {
         type: "timeline",
         provider: CODEX_PROVIDER,
@@ -4589,7 +4671,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,
@@ -4920,17 +5002,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,
@@ -4942,6 +5025,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<void> {
     await this.connect();
     if (!this.client) {
@@ -4952,6 +5041,7 @@ export class CodexAppServerAgentSession implements AgentSession {
     } else {
       await this.ensureThread();
     }
+    await this.ensureHistoryIndexed();
 
     await revertCodexConversation({
       client: this.client,
@@ -4965,11 +5055,11 @@ 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.persistedHistory = [];
-        this.historyPending = false;
-        await this.loadPersistedHistory(this.client);
-        this.reconcileAsyncQuestionsAfterRewind();
+        this.stagedHistory = await this.readThreadHistory(this.client);
+        this.reconcileAsyncQuestionsAfterRewind(this.stagedHistory.timeline);
       },
     });
   }
@@ -5008,15 +5098,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;
@@ -5029,6 +5131,10 @@ export class CodexAppServerAgentSession implements AgentSession {
     }
   }
 
+  stopBackgroundWork(id: string): Promise<void> {
+    return this.background.stopItem(id);
+  }
+
   async canStopRuntime(): Promise<boolean> {
     if (
       !this.client ||
@@ -5057,9 +5163,142 @@ 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.background.stop();
     this.clearPendingPermissions();
+    this.pendingToolCallDetails.clear();
     this.pendingSubAgentNotificationsByThreadId.clear();
     this.subscribers.clear();
     this.startupEvents = null;
@@ -5088,6 +5327,7 @@ export class CodexAppServerAgentSession implements AgentSession {
   }
 
   private async disposeClient(): Promise<void> {
+    this.background.stop();
     const client = this.client;
     this.connectionState = "disconnected";
     this.currentTurnId = null;
@@ -5207,6 +5447,8 @@ export class CodexAppServerAgentSession implements AgentSession {
       await this.connect();
       if (this.currentThreadId) {
         await this.ensureThreadLoaded();
+        // A goal runs turns of its own.
+        await this.ensureHistoryIndexed();
       } else {
         await this.ensureThread();
       }
@@ -5400,8 +5642,8 @@ export class CodexAppServerAgentSession implements AgentSession {
   }
 
   private emitEvent(event: AgentStreamEvent): void {
-    if (this.loadingPersistedHistory && event.type === "provider_subagent") {
-      this.persistedProviderSubagentEvents.push(event);
+    if (this.historySubagentEvents && event.type === "provider_subagent") {
+      this.historySubagentEvents.push(event);
       return;
     }
     this.notifySubscribers(event);
@@ -5437,7 +5679,21 @@ export class CodexAppServerAgentSession implements AgentSession {
     return `codex-turn-${this.nextTurnOrdinal++}`;
   }
 
-  private handleNotification(method: string, params: unknown): void {
+  private pendingNotifications: Promise<void> = Promise.resolve();
+
+  private handleNotification(method: string, params: unknown): Promise<void> {
+    // An image must exist before its event, and completion must follow that event.
+    // Transport callbacks cannot await: the session owns their ordered drain.
+    const next = this.pendingNotifications.then(() => {
+      return this.closed ? undefined : this.processNotification(method, params);
+    });
+    this.pendingNotifications = next.catch((error: unknown) => {
+      this.handleUnexpectedTermination(error instanceof Error ? error : new Error(String(error)));
+    });
+    return this.pendingNotifications;
+  }
+
+  private async processNotification(method: string, params: unknown): Promise<void> {
     const notificationParams = toObjectRecord(params);
     if (method === "serverRequest/resolved" && typeof notificationParams?.requestId === "number") {
       const requestId = this.mcpElicitationPermissionIds.get(notificationParams.requestId);
@@ -5467,13 +5723,24 @@ export class CodexAppServerAgentSession implements AgentSession {
       return;
     }
     if (route.kind === "sub_agent") {
-      this.dispatchSubAgentNotification(parsed, route.callId);
+      await this.dispatchSubAgentNotification(parsed, route.callId);
       return;
     }
-    this.dispatchParsedNotification(parsed);
+    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);
   }
 
-  private dispatchSubAgentNotification(parsed: ParsedCodexNotification, callId: string): void {
+  private async dispatchSubAgentNotification(
+    parsed: ParsedCodexNotification,
+    callId: string,
+  ): Promise<void> {
     switch (parsed.kind) {
       case "thread_started":
         this.emitSubAgentActivityUpdate(callId, "running", { reopen: true });
@@ -5484,7 +5751,7 @@ export class CodexAppServerAgentSession implements AgentSession {
       case "reasoning_delta":
       case "item_started":
       case "item_completed":
-        this.dispatchParsedNotification(parsed);
+        await this.dispatchParsedNotification(parsed);
         return;
       case "exec_command_output_delta":
       case "file_change_output_delta":
@@ -5502,6 +5769,9 @@ export class CodexAppServerAgentSession implements AgentSession {
       case "patch_apply_completed":
         this.handlePatchApplyCompletedNotification(parsed, callId);
         return;
+      case "context_compacted":
+        this.settleChildCompaction(parsed.threadId);
+        return;
       default:
         // Aggregate child telemetry is redundant and must not leak into the
         // root timeline. Concrete legacy tools are projected above for Codex
@@ -5510,7 +5780,7 @@ export class CodexAppServerAgentSession implements AgentSession {
     }
   }
 
-  private dispatchParsedNotification(parsed: ParsedCodexNotification): void {
+  private async dispatchParsedNotification(parsed: ParsedCodexNotification): Promise<void> {
     if (isCodexDeltaNotification(parsed)) {
       this.handleCodexDeltaNotification(parsed);
       return;
@@ -5555,10 +5825,10 @@ export class CodexAppServerAgentSession implements AgentSession {
         this.handlePatchApplyCompletedNotification(parsed);
         return;
       case "item_completed":
-        this.handleItemCompletedNotification(parsed);
+        await this.handleItemCompletedNotification(parsed);
         return;
       case "item_started":
-        this.handleItemStartedNotification(parsed);
+        await this.handleItemStartedNotification(parsed);
         return;
       case "invalid_payload":
         this.warnInvalidNotificationPayload(parsed.method, parsed.params);
@@ -5600,7 +5870,7 @@ export class CodexAppServerAgentSession implements AgentSession {
     pending.push(parsed);
   }
 
-  private replayPendingSubAgentNotifications(threadIds: readonly string[]): void {
+  private async replayPendingSubAgentNotifications(threadIds: readonly string[]): Promise<void> {
     for (const threadId of threadIds) {
       const pending = this.pendingSubAgentNotificationsByThreadId.get(threadId);
       if (!pending) {
@@ -5612,7 +5882,7 @@ export class CodexAppServerAgentSession implements AgentSession {
         continue;
       }
       for (const parsed of pending) {
-        this.dispatchSubAgentNotification(parsed, callId);
+        await this.dispatchSubAgentNotification(parsed, callId);
       }
     }
   }
@@ -5678,20 +5948,10 @@ export class CodexAppServerAgentSession implements AgentSession {
         activityItemIds: new Set<string>(),
         pendingCommandOutputDeltas: new Map<string, string[]>(),
         pendingFileChangeOutputDeltas: new Map<string, string[]>(),
-        childItemOrder: [],
-        childItems: new Map<string, AgentTimelineItem>(),
         childThreadIds: new Set<string>(),
       } satisfies CodexSubAgentCallState);
 
-    state.toolCall = {
-      ...timelineItem,
-      detail: {
-        ...timelineItem.detail,
-        log:
-          timelineItem.detail.log ||
-          (state.toolCall.detail.type === "sub_agent" ? state.toolCall.detail.log : ""),
-      },
-    };
+    state.toolCall = timelineItem;
     state.parentCallId ??= parentCallId;
     state.parentSubagentId ??= parentSubagentId;
     const activity = readCodexSubAgentActivity(rawItem);
@@ -5744,25 +6004,17 @@ export class CodexAppServerAgentSession implements AgentSession {
     const activityToolCall = mapCodexToolCallFromThreadItem(rawItem, {
       cwd: this.config.cwd ?? null,
     });
-    if (
-      activityToolCall?.detail.type === "sub_agent" &&
-      state.toolCall.detail.type === "sub_agent"
-    ) {
-      state.toolCall = {
-        ...state.toolCall,
-        detail: {
-          ...state.toolCall.detail,
-          subAgentType: activityToolCall.detail.subAgentType,
-        },
-      };
-    }
+    const subAgentType =
+      activityToolCall?.detail.type === "sub_agent"
+        ? activityToolCall.detail.subAgentType
+        : undefined;
     let nextStatus: ToolCallTimelineItem["status"] | undefined = "running";
     if (activity.kind === "interrupted") {
       nextStatus = "canceled";
     } else if (isTerminalSubAgentStatus(state.toolCall.status)) {
       nextStatus = undefined;
     }
-    this.emitSubAgentActivityUpdate(callId, nextStatus);
+    this.emitSubAgentActivityUpdate(callId, nextStatus, { subAgentType });
     return true;
   }
 
@@ -5803,7 +6055,13 @@ export class CodexAppServerAgentSession implements AgentSession {
   ): boolean {
     if (
       childSubAgentCallId &&
-      this.handleSubAgentContextCompactionItem(childSubAgentCallId, parsed.item, "completed")
+      parsed.threadId &&
+      this.handleSubAgentContextCompactionItem(
+        childSubAgentCallId,
+        parsed.threadId,
+        parsed.item,
+        "completed",
+      )
     ) {
       return true;
     }
@@ -5813,17 +6071,6 @@ export class CodexAppServerAgentSession implements AgentSession {
     );
   }
 
-  private upsertSubAgentChildItem(callId: string, itemId: string, item: AgentTimelineItem): void {
-    const state = this.subAgentCallsByCallId.get(callId);
-    if (!state) {
-      return;
-    }
-    if (!state.childItems.has(itemId)) {
-      state.childItemOrder.push(itemId);
-    }
-    state.childItems.set(itemId, item);
-  }
-
   private emitCodexToolTimelineItem(
     timelineItem: ToolCallTimelineItem,
     subAgentCallId: string | null,
@@ -5833,7 +6080,6 @@ export class CodexAppServerAgentSession implements AgentSession {
       this.emitEvent({ type: "timeline", provider: CODEX_PROVIDER, item: timelineItem });
       return;
     }
-    this.upsertSubAgentChildItem(subAgentCallId, timelineItem.callId, timelineItem);
     const state = this.subAgentCallsByCallId.get(subAgentCallId);
     if (state) {
       const targetThreadIds = childThreadId ? [childThreadId] : state.childThreadIds;
@@ -5847,26 +6093,15 @@ export class CodexAppServerAgentSession implements AgentSession {
     );
   }
 
-  private getSubAgentChildTimeline(state: CodexSubAgentCallState): AgentTimelineItem[] {
-    return state.childItemOrder
-      .map((itemId) => state.childItems.get(itemId))
-      .filter((item): item is AgentTimelineItem => Boolean(item));
-  }
-
   private emitSubAgentActivityUpdate(
     callId: string,
     status?: ToolCallTimelineItem["status"],
-    options?: { reopen?: boolean },
+    options?: { reopen?: boolean; subAgentType?: string },
   ): void {
     const state = this.subAgentCallsByCallId.get(callId);
     if (!state || state.toolCall.detail.type !== "sub_agent") {
       return;
     }
-    const childTimeline = this.getSubAgentChildTimeline(state);
-    const log =
-      childTimeline.length > 0
-        ? curateAgentActivity(childTimeline, { labelAssistantMessages: true })
-        : "";
     let resolvedStatus = status ?? state.toolCall.status;
     if (
       status === "running" &&
@@ -5875,16 +6110,12 @@ export class CodexAppServerAgentSession implements AgentSession {
     ) {
       resolvedStatus = state.toolCall.status;
     }
-    for (const childThreadId of state.childThreadIds) {
-      this.emitProviderSubagentUpsert(childThreadId, state, resolvedStatus);
-    }
-    const baseToolCall = {
-      ...state.toolCall,
-      detail: {
-        ...state.toolCall.detail,
-        log,
-      },
-    };
+    const baseToolCall = options?.subAgentType
+      ? {
+          ...state.toolCall,
+          detail: { ...state.toolCall.detail, subAgentType: options.subAgentType },
+        }
+      : state.toolCall;
     const nextToolCall: ToolCallTimelineItem =
       resolvedStatus === "failed"
         ? {
@@ -5897,10 +6128,14 @@ export class CodexAppServerAgentSession implements AgentSession {
             status: resolvedStatus,
             error: null,
           };
+    // The card is a launch marker: the child's activity streams to its own timeline, so the card
+    // is re-sent only when its status or label changes.
+    const cardChanged = !isDeepStrictEqual(nextToolCall, state.toolCall);
     state.toolCall = nextToolCall;
-    if (state.parentCallId && state.parentCallId !== callId) {
-      this.upsertSubAgentChildItem(state.parentCallId, state.callId, nextToolCall);
-      this.emitSubAgentActivityUpdate(state.parentCallId);
+    for (const childThreadId of state.childThreadIds) {
+      this.emitProviderSubagentUpsert(childThreadId, state, resolvedStatus);
+    }
+    if (!cardChanged || (state.parentCallId && state.parentCallId !== callId)) {
       return;
     }
     this.emitEvent({ type: "timeline", provider: CODEX_PROVIDER, item: nextToolCall });
@@ -6008,7 +6243,6 @@ export class CodexAppServerAgentSession implements AgentSession {
   ): void {
     this.applyBufferedDeltaTextToTimelineItem(timelineItem, itemId);
     if (itemId) {
-      this.upsertSubAgentChildItem(callId, itemId, timelineItem);
       this.pendingAgentMessages.delete(itemId);
       this.pendingReasoning.delete(itemId);
       this.pendingCommandOutputDeltas.delete(itemId);
@@ -6019,19 +6253,29 @@ export class CodexAppServerAgentSession implements AgentSession {
 
   private handleSubAgentContextCompactionItem(
     callId: string,
+    childThreadId: string,
     item: { id?: string; type?: string; [key: string]: unknown },
     status: "loading" | "completed",
   ): boolean {
     if (!this.isContextCompactionItem(item)) {
       return false;
     }
-    if (item.id) {
-      this.upsertSubAgentChildItem(callId, item.id, { type: "compaction", status });
+    if (status === "loading") {
+      this.pendingChildCompactionThreadIds.add(childThreadId);
+      this.emitProviderSubagentTimeline(childThreadId, { type: "compaction", status });
+    } else {
+      this.settleChildCompaction(childThreadId);
     }
     this.emitSubAgentActivityUpdate(callId);
     return true;
   }
 
+  private settleChildCompaction(childThreadId: string): void {
+    if (this.pendingChildCompactionThreadIds.delete(childThreadId)) {
+      this.emitProviderSubagentTimeline(childThreadId, { type: "compaction", status: "completed" });
+    }
+  }
+
   private shouldSkipCompletedThreadItem(
     timelineItem: AgentTimelineItem,
     normalizedItemType: string | undefined,
@@ -6062,11 +6306,6 @@ export class CodexAppServerAgentSession implements AgentSession {
             text: parsed.delta,
           });
         }
-        this.upsertSubAgentChildItem(subAgentCallId, parsed.itemId, {
-          type: "assistant_message",
-          messageId: parsed.itemId,
-          text,
-        });
         this.emitSubAgentActivityUpdate(subAgentCallId, "running");
         return;
       }
@@ -6100,10 +6339,6 @@ export class CodexAppServerAgentSession implements AgentSession {
             text: parsed.delta,
           });
         }
-        this.upsertSubAgentChildItem(subAgentCallId, parsed.itemId, {
-          type: "reasoning",
-          text: prev.join(""),
-        });
         this.emitSubAgentActivityUpdate(subAgentCallId, "running");
         return;
       }
@@ -6138,6 +6373,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,
@@ -6153,6 +6389,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 (
@@ -6166,11 +6403,23 @@ 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 {
     const subAgentCallId = this.getSubAgentCallIdForThread(parsed.threadId);
     if (subAgentCallId) {
+      if (parsed.threadId) this.settleChildCompaction(parsed.threadId);
       let status: ToolCallTimelineItem["status"] = "completed";
       if (parsed.status === "failed") {
         status = "failed";
@@ -6181,6 +6430,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",
@@ -6220,6 +6474,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();
@@ -6562,9 +6817,9 @@ export class CodexAppServerAgentSession implements AgentSession {
     }
   }
 
-  private reconcileAsyncQuestionsAfterRewind(): void {
+  private reconcileAsyncQuestionsAfterRewind(timeline: readonly PersistedTimelineEntry[]): void {
     const retainedIds = new Set(
-      this.persistedHistory.flatMap(({ item }) =>
+      timeline.flatMap(({ item }) =>
         item.type === "tool_call" && item.name === "request_user_input_async" ? [item.callId] : [],
       ),
     );
@@ -6578,9 +6833,14 @@ export class CodexAppServerAgentSession implements AgentSession {
     }
   }
 
-  private handleItemCompletedNotification(
+  private ownsNotificationTurn(turnId: string | null): boolean {
+    return !this.closed && this.activeForegroundTurnId === turnId;
+  }
+
+  private async handleItemCompletedNotification(
     parsed: Extract<ParsedCodexNotification, { kind: "item_completed" }>,
-  ): void {
+  ): 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
@@ -6588,22 +6848,28 @@ 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)) {
-      this.handleUserMessageItem(parsed);
+      await this.handleUserMessageItem(parsed);
       return;
     }
     const childSubAgentCallId = this.getSubAgentCallIdForThread(parsed.threadId);
     if (this.handleCompletedSpecialItem(parsed, childSubAgentCallId)) {
       return;
     }
-    const timelineItem = threadItemToTimeline(parsed.item, {
+    const foregroundTurnId = this.activeForegroundTurnId;
+    const timelineItem = await threadItemToTimeline(parsed.item, {
       includeUserMessage: false,
       cwd: this.config.cwd ?? null,
     });
     if (!timelineItem) {
       return;
     }
+    const imageItems = await mcpToolResultImagesToTimeline(parsed.item);
+    if (!this.ownsNotificationTurn(foregroundTurnId)) return;
     const registeredChildThreadIds =
       timelineItem.type === "tool_call"
         ? this.registerSubAgentToolCall({
@@ -6613,12 +6879,11 @@ export class CodexAppServerAgentSession implements AgentSession {
             parentSubagentId: resolveCodexParentSubagentId(childSubAgentCallId, parsed.threadId),
           })
         : [];
-    const imageItems = mcpToolResultImagesToTimeline(parsed.item);
     if (childSubAgentCallId) {
       this.emitCompletedProviderSubagentItem(parsed, timelineItem);
       this.handleSubAgentChildItemCompleted(childSubAgentCallId, parsed.item.id, timelineItem);
       this.emitProviderSubagentTimelineItems(parsed.threadId, imageItems);
-      this.replayPendingSubAgentNotifications(registeredChildThreadIds);
+      await this.replayPendingSubAgentNotifications(registeredChildThreadIds);
       return;
     }
     const normalizedItemType = normalizeCodexThreadItemType(
@@ -6626,18 +6891,16 @@ export class CodexAppServerAgentSession implements AgentSession {
     );
     const itemId = parsed.item.id;
     if (this.shouldSkipCompletedThreadItem(timelineItem, normalizedItemType, itemId)) {
-      this.replayPendingSubAgentNotifications(registeredChildThreadIds);
+      await this.replayPendingSubAgentNotifications(registeredChildThreadIds);
       return;
     }
     if (this.consumeStreamedTextCompletion(timelineItem, itemId)) {
       if (timelineItem.type === "assistant_message") {
         this.pendingAssistantMessageBoundary = true;
       }
-      if (itemId) {
-        this.emittedItemCompletedIds.add(itemId);
-        this.emittedItemStartedIds.delete(itemId);
-      }
-      this.replayPendingSubAgentNotifications(registeredChildThreadIds);
+      this.emittedItemCompletedIds.add(itemId);
+      this.emittedItemStartedIds.delete(itemId);
+      await this.replayPendingSubAgentNotifications(registeredChildThreadIds);
       return;
     }
     this.applyBufferedDeltaTextToTimelineItem(timelineItem, itemId);
@@ -6666,13 +6929,13 @@ export class CodexAppServerAgentSession implements AgentSession {
       this.pendingCommandOutputDeltas.delete(itemId);
       this.pendingFileChangeOutputDeltas.delete(itemId);
     }
-    this.replayPendingSubAgentNotifications(registeredChildThreadIds);
+    await this.replayPendingSubAgentNotifications(registeredChildThreadIds);
   }
 
   private consumeStreamedTextCompletion(
     timelineItem: AgentTimelineItem,
     itemId: string | null | undefined,
-  ): boolean {
+  ): itemId is string {
     if (!itemId) {
       return false;
     }
@@ -6738,20 +7001,27 @@ export class CodexAppServerAgentSession implements AgentSession {
     }
   }
 
-  private handleItemStartedNotification(
+  private async handleItemStartedNotification(
     parsed: Extract<ParsedCodexNotification, { kind: "item_started" }>,
-  ): void {
+  ): Promise<void> {
+    this.recordTurnTerminalProcess(parsed);
     if (shouldIgnoreMirroredLifecycleItem(parsed.source, parsed.item)) {
       return;
     }
     if (this.isUserMessageItem(parsed.item)) {
-      this.handleUserMessageItem(parsed);
+      await this.handleUserMessageItem(parsed);
       return;
     }
     const childSubAgentCallId = this.getSubAgentCallIdForThread(parsed.threadId);
     if (
       childSubAgentCallId &&
-      this.handleSubAgentContextCompactionItem(childSubAgentCallId, parsed.item, "loading")
+      parsed.threadId &&
+      this.handleSubAgentContextCompactionItem(
+        childSubAgentCallId,
+        parsed.threadId,
+        parsed.item,
+        "loading",
+      )
     ) {
       return;
     }
@@ -6767,13 +7037,14 @@ export class CodexAppServerAgentSession implements AgentSession {
     if (this.handleRegisteredSubAgentActivity(parsed.item)) {
       return;
     }
-    const timelineItem = threadItemToTimeline(parsed.item, {
+    const timelineItem = await threadItemToTimeline(parsed.item, {
       includeUserMessage: false,
       cwd: this.config.cwd ?? null,
     });
     if (!timelineItem || timelineItem.type !== "tool_call") {
       return;
     }
+    this.pendingToolCallDetails.set(timelineItem.callId, timelineItem.detail);
     const registeredChildThreadIds = this.registerSubAgentToolCall({
       timelineItem,
       rawItem: parsed.item,
@@ -6782,11 +7053,8 @@ export class CodexAppServerAgentSession implements AgentSession {
     });
     if (childSubAgentCallId) {
       this.emitStartedProviderSubagentItem(parsed.threadId, timelineItem);
-      if (parsed.item.id) {
-        this.upsertSubAgentChildItem(childSubAgentCallId, parsed.item.id, timelineItem);
-      }
       this.emitSubAgentActivityUpdate(childSubAgentCallId, "running");
-      this.replayPendingSubAgentNotifications(registeredChildThreadIds);
+      await this.replayPendingSubAgentNotifications(registeredChildThreadIds);
       return;
     }
     const normalizedItemType = normalizeCodexThreadItemType(
@@ -6810,14 +7078,14 @@ export class CodexAppServerAgentSession implements AgentSession {
       this.pendingCommandOutputDeltas.delete(itemId);
       this.pendingFileChangeOutputDeltas.delete(itemId);
     }
-    this.replayPendingSubAgentNotifications(registeredChildThreadIds);
+    await this.replayPendingSubAgentNotifications(registeredChildThreadIds);
   }
 
-  private handleUserMessageItem(
+  private async handleUserMessageItem(
     parsed: Extract<ParsedCodexNotification, { kind: "item_started" | "item_completed" }>,
-  ): void {
+  ): Promise<void> {
     const itemId = parsed.item.id;
-    const timelineItem = threadItemToTimeline(parsed.item, {
+    const timelineItem = await threadItemToTimeline(parsed.item, {
       includeUserMessage: true,
       cwd: this.config.cwd ?? null,
     });
@@ -6838,9 +7106,6 @@ export class CodexAppServerAgentSession implements AgentSession {
       if (parsed.threadId) {
         this.emitProviderSubagentTimeline(parsed.threadId, timelineItem);
       }
-      if (itemId) {
-        this.upsertSubAgentChildItem(childSubAgentCallId, itemId, timelineItem);
-      }
       this.emitSubAgentActivityUpdate(childSubAgentCallId, "running");
       return;
     }
@@ -7049,7 +7314,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(),
@@ -7059,20 +7325,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,
@@ -7383,12 +7654,19 @@ export class CodexAppServerAgentClient implements AgentClient {
       const listLimit = options?.cwd ? Math.max(scanLimit, 50) : scanLimit;
       // Codex records each thread under the model provider that ran it and,
       // unless told otherwise, lists only the provider its own config selects.
-      // A custom provider runs under its own id, so ask for exactly that one.
+      // Include legacy custom ids, but keep Codex built-in sessions separate.
       const customProviderConfig = this.customProviderConfig();
+      let modelProviders: string[] | undefined;
+      if (customProviderConfig && this.deps.customProvider) {
+        modelProviders = [customProviderConfig.model_provider];
+        if (!CODEX_BUILTIN_MODEL_PROVIDER_IDS.has(this.deps.customProvider.id)) {
+          modelProviders.push(this.deps.customProvider.id);
+        }
+      }
       const allThreads = await readCodexThreadWindow(client, this.logger, {
         limit: listLimit,
         cwd: options?.cwd,
-        ...(customProviderConfig ? { modelProviders: [customProviderConfig.model_provider] } : {}),
+        ...(modelProviders ? { modelProviders } : {}),
       });
       const threads = filterCodexThreadsByCwd(allThreads, options?.cwd);
       return threads.slice(0, limit).map((thread) => {
diff --git a/packages/server/src/server/agent/providers/codex-custom-provider-import.local.e2e.test.ts b/packages/server/src/server/agent/providers/codex-custom-provider-import.local.e2e.test.ts
index ebd8de5ab5..f546dc69e7 100644
--- a/packages/server/src/server/agent/providers/codex-custom-provider-import.local.e2e.test.ts
+++ b/packages/server/src/server/agent/providers/codex-custom-provider-import.local.e2e.test.ts
@@ -7,7 +7,8 @@ import path from "node:path";
 import { afterEach, describe, expect, test } from "vitest";
 
 import { createTestLogger } from "../../../test-utils/test-logger.js";
-import { CodexAppServerAgentClient } from "./codex-app-server-agent.js";
+import { spawnProcess } from "../../../utils/spawn.js";
+import { CodexAppServerAgentClient, CodexAppServerAgentSession } from "./codex-app-server-agent.js";
 
 // Runs the real `codex` binary against a local Responses endpoint standing in
 // for a custom provider's OPENAI_BASE_URL, so no login is needed.
@@ -88,52 +89,106 @@ describe("Codex custom provider import list", () => {
     for (const cleanup of cleanups.splice(0).toReversed()) await cleanup();
   });
 
-  test("lists a custom provider's session under that provider and imports it there", async () => {
-    const codexHome = mkdtempSync(path.join(os.tmpdir(), "codex-custom-import-home-"));
-    const cwd = mkdtempSync(path.join(os.tmpdir(), "codex-custom-import-cwd-"));
-    cleanups.push(() => rmSync(codexHome, { recursive: true, force: true }));
-    cleanups.push(() => rmSync(cwd, { recursive: true, force: true }));
-    const { baseUrl, server, requestCount } = await startResponsesEndpoint();
-    cleanups.push(() => closeServer(server));
+  test.each([
+    { providerId: "my-codex", seedLegacy: false, seedBuiltin: false },
+    { providerId: "ollama", seedLegacy: false, seedBuiltin: false },
+    { providerId: "my-codex", seedLegacy: true, seedBuiltin: false },
+    { providerId: "ollama", seedLegacy: false, seedBuiltin: true },
+  ])(
+    "lists and imports sessions for $providerId (legacy: $seedLegacy, native: $seedBuiltin)",
+    async ({ providerId, seedLegacy, seedBuiltin }) => {
+      const codexHome = mkdtempSync(path.join(os.tmpdir(), "codex-custom-import-home-"));
+      const cwd = mkdtempSync(path.join(os.tmpdir(), "codex-custom-import-cwd-"));
+      cleanups.push(() => rmSync(codexHome, { recursive: true, force: true }));
+      cleanups.push(() => rmSync(cwd, { recursive: true, force: true }));
+      const { baseUrl, server, requestCount } = await startResponsesEndpoint();
+      cleanups.push(() => closeServer(server));
 
-    const logger = createTestLogger();
-    const customCodex = new CodexAppServerAgentClient(
-      logger,
-      { env: { CODEX_HOME: codexHome, OPENAI_BASE_URL: baseUrl, OPENAI_API_KEY: "test-key" } },
-      { customProvider: { id: "my-codex", label: "My Codex", extends: "codex" } },
-    );
-    const stockCodex = new CodexAppServerAgentClient(logger, { env: { CODEX_HOME: codexHome } });
+      const logger = createTestLogger();
+      if (seedLegacy || seedBuiltin) {
+        // Seed an old custom session or a native built-in session with real Codex.
+        const environment = {
+          ...process.env,
+          CODEX_HOME: codexHome,
+          CODEX_OSS_BASE_URL: baseUrl,
+          OPENAI_API_KEY: "test-key",
+        };
+        const legacy = new CodexAppServerAgentSession(
+          { provider: "codex", cwd, model: "mock-model" },
+          null,
+          logger,
+          async () =>
+            spawnProcess("codex", ["app-server"], { cwd, env: environment, stdio: "pipe" }),
+          {
+            environment,
+            customCodexConfig: {
+              model_provider: providerId,
+              model_providers: seedBuiltin
+                ? {}
+                : {
+                    [providerId]: {
+                      name: "My Codex",
+                      base_url: baseUrl,
+                      wire_api: "responses",
+                      env_key: "OPENAI_API_KEY",
+                      requires_openai_auth: false,
+                    },
+                  },
+            },
+          },
+        );
+        try {
+          await legacy.run("hello from the legacy provider");
+        } finally {
+          await legacy.close();
+        }
+      }
+      const customCodex = new CodexAppServerAgentClient(
+        logger,
+        { env: { CODEX_HOME: codexHome, OPENAI_BASE_URL: baseUrl, OPENAI_API_KEY: "test-key" } },
+        { customProvider: { id: providerId, label: "My Codex", extends: "codex" } },
+      );
+      const stockCodex = new CodexAppServerAgentClient(logger, { env: { CODEX_HOME: codexHome } });
 
-    const session = await customCodex.createSession({
-      provider: "codex",
-      cwd,
-      model: "mock-model",
-    });
-    try {
-      await session.run("hello from the custom provider");
-    } finally {
-      await session.close();
-    }
+      const session = await customCodex.createSession({
+        provider: "codex",
+        cwd,
+        model: "mock-model",
+      });
+      try {
+        await session.run("hello from the custom provider");
+      } finally {
+        await session.close();
+      }
 
-    const customSessions = await customCodex.listImportableSessions({ cwd });
-    const stockSessions = await stockCodex.listImportableSessions({ cwd });
+      const customSessions = await customCodex.listImportableSessions({ cwd });
+      const stockSessions = await stockCodex.listImportableSessions({ cwd });
 
-    expect(customSessions.map((entry) => entry.firstPromptPreview)).toEqual([
-      "hello from the custom provider",
-    ]);
-    expect(stockSessions).toEqual([]);
+      expect(customSessions.map((entry) => entry.firstPromptPreview).sort()).toEqual(
+        seedLegacy
+          ? ["hello from the custom provider", "hello from the legacy provider"]
+          : ["hello from the custom provider"],
+      );
+      expect(stockSessions).toEqual([]);
 
-    const config = { provider: "codex", cwd, model: "mock-model" };
-    const imported = await customCodex.importSession(
-      { providerHandleId: customSessions[0].providerHandleId, cwd },
-      { config, storedConfig: config },
-    );
-    const requestsBeforeImportedTurn = requestCount();
-    try {
-      await imported.session.run("hello again after import");
-    } finally {
-      await imported.session.close();
-    }
-    expect(requestCount()).toBeGreaterThan(requestsBeforeImportedTurn);
-  }, 120_000);
+      const config = { provider: "codex", cwd, model: "mock-model" };
+      const sessionToImport = seedLegacy
+        ? customSessions.find(
+            (entry) => entry.firstPromptPreview === "hello from the legacy provider",
+          )!
+        : customSessions[0];
+      const imported = await customCodex.importSession(
+        { providerHandleId: sessionToImport.providerHandleId, cwd },
+        { config, storedConfig: config },
+      );
+      const requestsBeforeImportedTurn = requestCount();
+      try {
+        await imported.session.run("hello again after import");
+      } finally {
+        await imported.session.close();
+      }
+      expect(requestCount()).toBeGreaterThan(requestsBeforeImportedTurn);
+    },
+    120_000,
+  );
 });
diff --git a/packages/server/src/server/agent/providers/codex-history-string-limit.real.e2e.test.ts b/packages/server/src/server/agent/providers/codex-history-string-limit.real.e2e.test.ts
new file mode 100644
index 0000000000..fba51b9e1d
--- /dev/null
+++ b/packages/server/src/server/agent/providers/codex-history-string-limit.real.e2e.test.ts
@@ -0,0 +1,53 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, test } from "vitest";
+
+// Regression for #3905. Real Codex, synthetic on-disk history, no model turns.
+// Opt in because the oversized cases need approximately 2 GiB of memory and over
+// 1 GiB of temporary storage.
+const enabled = process.env.PASEO_CODEX_HISTORY_STRING_LIMIT_REPRO === "1";
+const script = fileURLToPath(
+  new URL("../../../../scripts/reproduce-codex-history-string-limit.mts", import.meta.url),
+);
+
+test.runIf(enabled).each([
+  { megabytes: 2, historyMode: "legacy", expected: "History loaded: 3 timeline rows" },
+  { megabytes: 520, historyMode: "legacy", expected: "codex migrate-rollouts --apply --thread" },
+  { megabytes: 520, historyMode: "paginated", expected: "History loaded: 521 timeline rows" },
+])(
+  "opening $megabytes MiB of $historyMode Codex history does not crash its hosting process",
+  async ({ megabytes, historyMode, expected }) => {
+    const root = await mkdtemp(path.join(process.cwd(), ".codex-history-test-"));
+    try {
+      const result = await new Promise<{ code: number; stdout: string; stderr: string }>(
+        (resolve) => {
+          const child = execFile(
+            process.execPath,
+            ["--import", "tsx", script, String(megabytes), historyMode],
+            {
+              cwd: root,
+              detached: true,
+              timeout: 120_000,
+              maxBuffer: 1024 * 1024,
+            },
+            (error, stdout, stderr) => {
+              try {
+                if (child.pid) process.kill(-child.pid, "SIGKILL");
+              } catch (killError) {
+                if ((killError as NodeJS.ErrnoException).code !== "ESRCH") throw killError;
+              }
+              resolve({ code: error ? Number(error.code ?? 1) : 0, stdout, stderr });
+            },
+          );
+        },
+      );
+      expect(result.code, result.stderr).toBe(0);
+      expect(result.stdout).toContain(expected);
+    } finally {
+      await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+    }
+  },
+  180_000,
+);
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/app-server-transport.test.ts b/packages/server/src/server/agent/providers/codex/app-server-transport.test.ts
index cc32a3c013..84b82b431b 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
@@ -183,3 +183,56 @@ describe("Codex app-server transport", () => {
     codex.child.stdin.end();
   });
 });
+
+describe("Codex stdout byte admission", () => {
+  test("an oversized response fails only its own request", async () => {
+    const child = createCodexAppServerChildProcess();
+    const client = new CodexAppServerClient(child, createTestLogger());
+    const terminations: Error[] = [];
+    client.setUnexpectedTerminationHandler((error) => terminations.push(error));
+    const oversized = client.request("thread/items/list", {}).catch((error: Error) => error);
+    const other = client.request("model/list", {});
+    const chunk = Buffer.alloc(64 * 1024, "x");
+    child.stdout.write('{"id":1,"result":"');
+    for (let index = 0; index < 2049; index++) child.stdout.write(chunk);
+    child.stdout.write('"}\n{"id":2,"result":{"data":[]}}\n');
+
+    expect(await oversized).toMatchObject({
+      name: "CodexAppServerResponseTooLargeError",
+      method: "thread/items/list",
+      limitBytes: 128 * 1024 * 1024,
+    });
+    await expect(other).resolves.toEqual({ data: [] });
+    const next = client.request("model/list", {});
+    child.stdout.write('{"id":3,"result":{"data":["next"]}}\n');
+    await expect(next).resolves.toEqual({ data: ["next"] });
+    expect(terminations).toEqual([]);
+    await client.dispose();
+    child.stdout.end();
+    child.stderr.end();
+  });
+
+  test("an oversized notification fails pending requests and the session", async () => {
+    const child = createCodexAppServerChildProcess();
+    const client = new CodexAppServerClient(child, createTestLogger());
+    const terminations: Error[] = [];
+    client.setUnexpectedTerminationHandler((error) => terminations.push(error));
+    const request = client.request("thread/resume", {}, 1000).catch((error: Error) => error);
+    const chunk = Buffer.alloc(64 * 1024, "x");
+    child.stdout.write('{"method":"item/completed","params":"');
+    for (let index = 0; index < 2048; index++) child.stdout.write(chunk);
+    const error = await request;
+    expect(error).toMatchObject({
+      name: "ProviderStreamLimitError",
+      code: "PROVIDER_STREAM_LINE_TOO_LARGE",
+      limitBytes: 128 * 1024 * 1024,
+    });
+    expect(terminations).toEqual([error]);
+    expect(client.hasPendingRequests()).toBe(false);
+    child.stdout.write('"}\n{"id":1,"result":"late"}\n');
+    await expect(client.request("model/list")).rejects.toThrow("closed");
+    await client.dispose();
+    child.stdout.end();
+    child.stderr.end();
+  });
+});
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 29b8cf8880..5a218e2edb 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
@@ -1,10 +1,15 @@
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
-import { StringDecoder } from "node:string_decoder";
 import type { Logger } from "pino";
 import { z } from "zod";
 
 import { terminateWithTreeKill } from "../../../../utils/tree-kill.js";
 
+import { ProviderLineReader, ProviderStreamLimitError } from "../jsonl-frame-decoder.js";
+
+// A measured long-thread resume was 19.75 MB; preserve the existing 32 MiB fixture
+// with 4x margin for longer threads. This is provider stdout, not the client protocol.
+export const CODEX_PROVIDER_LINE_BYTES = 128 * 1024 * 1024;
+
 const DEFAULT_TIMEOUT_MS = 14 * 24 * 60 * 60 * 1000;
 const APP_SERVER_GRACEFUL_SHUTDOWN_TIMEOUT_MS = 2_000;
 const APP_SERVER_FORCE_SHUTDOWN_TIMEOUT_MS = 1_000;
@@ -28,11 +33,26 @@ interface JsonRpcNotification {
 }
 
 interface PendingRequest {
+  method: string;
   resolve: (value: unknown) => void;
   reject: (error: Error) => void;
   timer: NodeJS.Timeout;
 }
 
+/** A response past the provider line cap. Only its request fails; the session stays up. */
+export class CodexAppServerResponseTooLargeError extends Error {
+  constructor(
+    readonly method: string,
+    readonly limitBytes: number,
+  ) {
+    super(`Codex app-server response to ${method} exceeds ${limitBytes} bytes`);
+    this.name = "CodexAppServerResponseTooLargeError";
+  }
+}
+
+// Codex serializes a response with `id` first, so its head names the request.
+const OVERSIZED_RESPONSE_HEAD = /^\{"id":(\d+),"result":/;
+
 export class CodexAppServerRpcError extends Error {
   constructor(
     message: string,
@@ -167,39 +187,6 @@ function readProviderTurnId(params: unknown): string | undefined {
   return isRecord(turn) && typeof turn.id === "string" ? turn.id : undefined;
 }
 
-/**
- * Splits stdout into lines on "\n" only. `node:readline` additionally treats U+2028 and U+2029
- * as line terminators, but Codex emits those characters raw inside JSON strings, so readline
- * would cut a single JSON-RPC message into pieces that fail to parse.
- */
-function createNewlineLineReader(
-  input: NodeJS.ReadableStream,
-  onLine: (line: string) => void,
-): { close(): void } {
-  const decoder = new StringDecoder("utf8");
-  // Text after the last "\n", kept as parts and joined once its line ends, so a large line
-  // arriving in many chunks is scanned and copied once instead of once per chunk.
-  let unterminated: string[] = [];
-  const onData = (chunk: Buffer | string): void => {
-    const text = typeof chunk === "string" ? chunk : decoder.write(chunk);
-    let lineStart = 0;
-    let index = text.indexOf("\n");
-    while (index !== -1) {
-      unterminated.push(text.slice(lineStart, index));
-      const line = unterminated.join("");
-      unterminated = [];
-      onLine(line.endsWith("\r") ? line.slice(0, -1) : line);
-      lineStart = index + 1;
-      index = text.indexOf("\n", lineStart);
-    }
-    if (lineStart < text.length) {
-      unterminated.push(text.slice(lineStart));
-    }
-  };
-  input.on("data", onData);
-  return { close: () => void input.off("data", onData) };
-}
-
 export class CodexAppServerClient {
   private readonly stdoutLineReader: { close(): void };
   private activeProviderRequests = 0;
@@ -216,11 +203,24 @@ export class CodexAppServerClient {
     private readonly logger: Logger,
     private readonly getTraceContext: () => CodexAppServerTraceContext = () => ({}),
   ) {
-    this.stdoutLineReader = createNewlineLineReader(child.stdout, (line) => {
-      void this.handleLine(line).catch((error) => {
-        this.logger.warn({ error, line }, "Failed to handle Codex app-server stdout line");
-      });
-    });
+    // Split only on LF: U+2028/U+2029 are valid raw characters inside Codex JSON.
+    const reader = new ProviderLineReader(
+      CODEX_PROVIDER_LINE_BYTES,
+      (line) => {
+        void this.handleLine(line).catch((error) => {
+          this.logger.warn({ error, line }, "Failed to handle Codex app-server stdout line");
+        });
+      },
+      (error) => this.handleStreamLimit(error),
+    );
+    const onData = (chunk: Buffer | string) => reader.write(chunk);
+    child.stdout.on("data", onData);
+    this.stdoutLineReader = {
+      close: () => {
+        reader.close();
+        child.stdout.off("data", onData);
+      },
+    };
 
     child.stderr.on("data", (chunk) => {
       this.stderrBuffer += chunk.toString();
@@ -273,7 +273,7 @@ export class CodexAppServerClient {
         this.pending.delete(id);
         reject(new Error(`Codex app-server request timed out for ${method}`));
       }, timeoutMs);
-      this.pending.set(id, { resolve, reject, timer });
+      this.pending.set(id, { method, resolve, reject, timer });
     });
   }
 
@@ -318,6 +318,28 @@ export class CodexAppServerClient {
     }
   }
 
+  private handleStreamLimit(failure: ProviderStreamLimitError): void {
+    const responseId = OVERSIZED_RESPONSE_HEAD.exec(failure.lineHead)?.[1];
+    const pending = responseId === undefined ? undefined : this.pending.get(Number(responseId));
+    if (pending) {
+      clearTimeout(pending.timer);
+      this.pending.delete(Number(responseId));
+      this.logger.warn(
+        { method: pending.method, limitBytes: failure.limitBytes },
+        "Codex app-server response exceeded the line cap",
+      );
+      pending.reject(new CodexAppServerResponseTooLargeError(pending.method, failure.limitBytes));
+      return;
+    }
+    // A lost notification or server request cannot be replayed. Fail the session,
+    // including live turns with no pending RPC, rather than dropping a stream unit.
+    this.stdoutLineReader.close();
+    this.handleUnexpectedTermination(failure);
+    void this.dispose().catch((err) => {
+      this.logger.warn({ err }, "Failed to terminate oversized Codex stdout producer");
+    });
+  }
+
   private handleUnexpectedTermination(error: Error): void {
     if (this.disposed) {
       return;
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/rewind.test.ts b/packages/server/src/server/agent/providers/codex/rewind.test.ts
index da7fe6a8f5..7a0b2dc0f9 100644
--- a/packages/server/src/server/agent/providers/codex/rewind.test.ts
+++ b/packages/server/src/server/agent/providers/codex/rewind.test.ts
@@ -108,7 +108,7 @@ describe("Codex Rewind", () => {
         cwd: "/workspace/project",
         model: "gpt-5.4-mini",
         serviceTier: null,
-        excludeTurns: false,
+        excludeTurns: true,
         persistExtendedHistory: true,
       },
     ]);
@@ -190,7 +190,7 @@ describe("Codex Rewind", () => {
         cwd: "/workspace/project",
         model: "gpt-5.4-mini",
         serviceTier: null,
-        excludeTurns: false,
+        excludeTurns: true,
         persistExtendedHistory: true,
       },
     ]);
diff --git a/packages/server/src/server/agent/providers/codex/rewind.ts b/packages/server/src/server/agent/providers/codex/rewind.ts
index 021d57645c..a22931b92b 100644
--- a/packages/server/src/server/agent/providers/codex/rewind.ts
+++ b/packages/server/src/server/agent/providers/codex/rewind.ts
@@ -8,6 +8,7 @@ import {
   parseCodexThreadForkResponse,
   parseCodexThreadRollbackResponse,
 } from "./app-server-transport.js";
+import { readCodexThreadHistoryMode } from "./thread-history.js";
 
 export interface CodexRewindClient {
   forkThread?(params: CodexThreadForkParams): Promise<CodexThreadForkResponse>;
@@ -20,26 +21,6 @@ export interface CodexUserMessageTurnIndex {
   count(): number;
 }
 
-type CodexThreadHistoryMode = "legacy" | "paginated";
-
-async function readCodexThreadHistoryMode(
-  client: CodexRewindClient,
-  threadId: string,
-): Promise<CodexThreadHistoryMode> {
-  const response = await client.request("thread/read", { threadId, includeTurns: false });
-  if (typeof response !== "object" || response === null || !("thread" in response)) {
-    throw new Error("Codex thread/read did not return thread metadata");
-  }
-  const thread = response.thread;
-  if (typeof thread !== "object" || thread === null || !("historyMode" in thread)) {
-    return "legacy";
-  }
-  if (thread.historyMode === "legacy" || thread.historyMode === "paginated") {
-    return thread.historyMode;
-  }
-  throw new Error(`Codex thread/read returned unknown history mode ${String(thread.historyMode)}`);
-}
-
 async function forkCodexThread(
   client: CodexRewindClient,
   params: CodexThreadForkParams,
@@ -95,7 +76,8 @@ export async function revertCodexConversation(input: {
     model: input.model ?? null,
     serviceTier: input.serviceTier ?? null,
     ...(input.config ? { config: input.config } : {}),
-    excludeTurns: false,
+    // Paseo re-reads the rewound thread through paged history, not the fork reply.
+    excludeTurns: true,
     persistExtendedHistory: true,
   };
 
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 226eeb9738..106c734753 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
@@ -3,6 +3,10 @@ import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
 
 import type { AgentSession, AgentStreamEvent } from "../../../agent-sdk-types.js";
+import { CODEX_PROVIDER_LINE_BYTES } from "../app-server-transport.js";
+
+/** A handler result that the fake writes as a response line past the provider line cap. */
+export const OVERSIZED_RESPONSE = Symbol("oversized Codex response");
 
 type JsonObject = Record<string, unknown>;
 type FakeCodexAppServerHandler = (params: unknown) => unknown;
@@ -39,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;
@@ -84,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;
@@ -163,6 +175,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) => ({
@@ -229,8 +242,18 @@ export function createFakeCodexAppServer(
       return;
     }
 
-    Promise.resolve(handler(message.params))
+    let response: unknown;
+    try {
+      response = handler(message.params);
+    } catch (error) {
+      response = Promise.reject(error);
+    }
+    Promise.resolve(response)
       .then((result) => {
+        if (result === OVERSIZED_RESPONSE) {
+          writeOversizedResponse(message.id as number);
+          return undefined;
+        }
         const rpcError = toJsonObject(result).__jsonRpcError;
         if (rpcError) {
           child.stdout.write(`${JSON.stringify({ id: message.id, error: rpcError })}\n`);
@@ -313,6 +336,16 @@ export function createFakeCodexAppServer(
     });
   }
 
+  // Codex writes `id` first, then a result past the provider line cap.
+  function writeOversizedResponse(id: number): void {
+    child.stdout.write(`{"id":${id},"result":{"data":[{"item":{"text":"`);
+    const chunk = Buffer.alloc(1024 * 1024, "x");
+    for (let written = 0; written <= CODEX_PROVIDER_LINE_BYTES; written += chunk.byteLength) {
+      child.stdout.write(chunk);
+    }
+    child.stdout.write('"}}]}}\n');
+  }
+
   function writeNotification(method: string, params: JsonObject): void {
     child.stdout.write(`${JSON.stringify({ method, params })}\n`);
   }
@@ -443,6 +476,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 = [
         {
@@ -696,3 +743,81 @@ export function waitForProviderSubagent(
 ): Promise<ProviderSubagentEvent> {
   return waitForNextEvent(session, "provider_subagent", (event) => event.event.id === id);
 }
+
+export interface FakeCodexHistoryTurn {
+  id: string;
+  startedAt?: number;
+  completedAt?: number;
+  items: JsonObject[];
+}
+
+export interface FakeCodexHistoryThread {
+  /** Omitted on Codex builds older than 0.143, which only have legacy history. */
+  historyMode?: "legacy" | "paginated";
+  turns: FakeCodexHistoryTurn[];
+}
+
+export interface FakeCodexHistoryOptions {
+  /** Any response carrying one of these items is written past the line cap. */
+  oversizedItemIds?: string[];
+}
+
+/**
+ * Codex's persisted thread history: `thread/read` for metadata and legacy full
+ * reads, `thread/items/list` for paginated threads. Paginated threads reject
+ * the full read as Codex 0.145 and 0.146 do.
+ */
+export function fakeCodexThreadHistory(
+  threads: Record<string, FakeCodexHistoryThread>,
+  options: FakeCodexHistoryOptions = {},
+): Record<string, FakeCodexAppServerHandler> {
+  const oversizedItemIds = new Set(options.oversizedItemIds ?? []);
+  const isOversized = (items: JsonObject[]) =>
+    items.some((item) => oversizedItemIds.has(String(item.id)));
+
+  function readThread(params: unknown): { id: string; thread: FakeCodexHistoryThread } {
+    const id = String(toJsonObject(params).threadId);
+    const thread = threads[id];
+    if (!thread) throw new Error(`thread not found: ${id}`);
+    return { id, thread };
+  }
+
+  return {
+    "thread/read": (params) => {
+      const { id, thread } = readThread(params);
+      if (!toJsonObject(params).includeTurns) {
+        return {
+          thread: { id, ...(thread.historyMode ? { historyMode: thread.historyMode } : {}) },
+        };
+      }
+      if (thread.historyMode === "paginated") {
+        throw new Error("paginated threads do not support thread/read(includeTurns=true)");
+      }
+      if (isOversized(thread.turns.flatMap((turn) => turn.items))) return OVERSIZED_RESPONSE;
+      return { thread: { id, turns: thread.turns } };
+    },
+    "thread/items/list": (params) => {
+      const { thread } = readThread(params);
+      if (thread.historyMode !== "paginated") {
+        throw new Error("thread/items/list is not supported for legacy threads");
+      }
+      const request = toJsonObject(params);
+      // Codex records each item's own times; the fake gives every item its turn's.
+      const rows = thread.turns.flatMap((turn) =>
+        turn.items.map((item) => ({
+          turnId: turn.id,
+          item,
+          startedAtMs: turn.startedAt === undefined ? null : turn.startedAt * 1000,
+          completedAtMs: turn.completedAt === undefined ? null : turn.completedAt * 1000,
+        })),
+      );
+      const limit = Math.min(typeof request.limit === "number" ? request.limit : 25, 100);
+      const start =
+        typeof request.cursor === "string" ? Number(request.cursor.slice("cursor-".length)) : 0;
+      const end = Math.min(rows.length, start + limit);
+      const data = rows.slice(start, end);
+      if (isOversized(data.map((row) => row.item))) return OVERSIZED_RESPONSE;
+      return { data, nextCursor: end < rows.length ? `cursor-${end}` : null };
+    },
+  };
+}
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
new file mode 100644
index 0000000000..8d3d8fce3d
--- /dev/null
+++ b/packages/server/src/server/agent/providers/codex/thread-history.test.ts
@@ -0,0 +1,220 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { describe, expect, test } from "vitest";
+
+import { createTestLogger } from "../../../../test-utils/test-logger.js";
+import type { AgentSession, AgentStreamEvent } from "../../agent-sdk-types.js";
+import { CodexAppServerAgentClient } from "../codex-app-server-agent.js";
+import {
+  createFakeCodexAppServer,
+  type FakeCodexAppServer,
+  type FakeCodexHistoryOptions,
+  type FakeCodexHistoryThread,
+  fakeCodexThreadHistory,
+} from "./test-utils/fake-app-server.js";
+
+function userItem(id: string, text: string) {
+  return { type: "userMessage", id, content: [{ type: "text", text }] };
+}
+
+function agentItem(id: string, text: string) {
+  return { type: "agentMessage", id, text };
+}
+
+async function openCodexThread(
+  thread: FakeCodexHistoryThread,
+  options?: FakeCodexHistoryOptions,
+): Promise<{ appServer: FakeCodexAppServer; session: AgentSession }> {
+  const appServer = createFakeCodexAppServer(
+    fakeCodexThreadHistory({ "saved-thread": thread }, options),
+  );
+  const provider = new CodexAppServerAgentClient(createTestLogger());
+  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 };
+}
+
+async function readHistory(session: AgentSession): Promise<AgentStreamEvent[]> {
+  const events: AgentStreamEvent[] = [];
+  for await (const event of session.streamHistory()) events.push(event);
+  return events;
+}
+
+function timelineItems(events: AgentStreamEvent[]) {
+  return events.flatMap((event) => (event.type === "timeline" ? [event.item] : []));
+}
+
+function historyRequests(appServer: FakeCodexAppServer) {
+  return appServer
+    .requests()
+    .filter(
+      (request) =>
+        request.method === "thread/read" ||
+        request.method === "thread/turns/list" ||
+        request.method === "thread/items/list",
+    )
+    .map((request) => ({ method: request.method, params: request.params }));
+}
+
+describe("Codex thread history", () => {
+  test("loads a paginated thread through pages", async () => {
+    const answers = Array.from({ length: 150 }, (_, index) =>
+      agentItem(`agent-${index}`, `Answer ${index}`),
+    );
+    const { appServer, session } = await openCodexThread({
+      historyMode: "paginated",
+      turns: [
+        {
+          id: "turn-1",
+          startedAt: 1_778_832_941,
+          completedAt: 1_778_833_000,
+          items: [userItem("user-1", "First"), ...answers.slice(0, 120)],
+        },
+        {
+          id: "turn-2",
+          startedAt: 1_778_833_094,
+          completedAt: 1_778_833_100,
+          items: [userItem("user-2", "Second"), ...answers.slice(120)],
+        },
+      ],
+    });
+    try {
+      const events = await readHistory(session);
+
+      expect(timelineItems(events)).toEqual([
+        { type: "user_message", text: "First", messageId: "user-1" },
+        ...answers.slice(0, 120).map((answer) => ({
+          type: "assistant_message",
+          text: answer.text,
+          messageId: answer.id,
+        })),
+        { type: "user_message", text: "Second", messageId: "user-2" },
+        ...answers.slice(120).map((answer) => ({
+          type: "assistant_message",
+          text: answer.text,
+          messageId: answer.id,
+        })),
+      ]);
+      const timestamps = events.flatMap((event) =>
+        event.type === "timeline" ? [event.timestamp] : [],
+      );
+      expect(timestamps[0]).toBe("2026-05-15T08:15:41.000Z");
+      expect(timestamps[1]).toBe("2026-05-15T08:16:40.000Z");
+      expect(timestamps[121]).toBe("2026-05-15T08:18:14.000Z");
+      const requests = historyRequests(appServer);
+      expect(requests).not.toContainEqual(
+        expect.objectContaining({ params: expect.objectContaining({ includeTurns: true }) }),
+      );
+      const itemPages = requests.filter((request) => request.method === "thread/items/list");
+      expect(itemPages.length).toBeGreaterThan(1);
+      for (const page of itemPages) {
+        expect(page.params).toMatchObject({ threadId: "saved-thread", sortDirection: "asc" });
+        expect((page.params as { limit: number }).limit).toBeLessThanOrEqual(100);
+      }
+    } finally {
+      await session.close();
+    }
+    appServer.assertNoErrors();
+  });
+
+  test("loads a paginated thread whose full read Codex 0.145 rejects", async () => {
+    const { appServer, session } = await openCodexThread({
+      historyMode: "paginated",
+      turns: [{ id: "turn-1", items: [userItem("user-1", "Hello"), agentItem("agent-1", "Hi")] }],
+    });
+    try {
+      expect(timelineItems(await readHistory(session))).toEqual([
+        { type: "user_message", text: "Hello", messageId: "user-1" },
+        { type: "assistant_message", text: "Hi", messageId: "agent-1" },
+      ]);
+    } finally {
+      await session.close();
+    }
+    appServer.assertNoErrors();
+  });
+
+  test("a page too big to send shows a warning row and stops loading", async () => {
+    const answers = Array.from({ length: 120 }, (_, index) =>
+      agentItem(`agent-${index}`, `Answer ${index}`),
+    );
+    const { appServer, session } = await openCodexThread(
+      {
+        historyMode: "paginated",
+        turns: [
+          { id: "turn-1", items: [userItem("user-1", "One"), ...answers] },
+          { id: "turn-2", items: [userItem("user-2", "Two"), agentItem("huge", "never sent")] },
+        ],
+      },
+      { oversizedItemIds: ["huge"] },
+    );
+    const loaded = [
+      { type: "user_message", text: "One", messageId: "user-1" },
+      ...answers.slice(0, 99).map((answer) => ({
+        type: "assistant_message",
+        text: answer.text,
+        messageId: answer.id,
+      })),
+      {
+        type: "notification",
+        level: "warning",
+        message: "The rest of this Codex thread's history is too large to load.",
+      },
+    ];
+    try {
+      expect(timelineItems(await readHistory(session))).toEqual(loaded);
+      // The oversized reply failed only its own request; the session still answers.
+      expect(timelineItems(await readHistory(session))).toEqual(loaded);
+    } finally {
+      await session.close();
+    }
+    appServer.assertNoErrors();
+  });
+
+  test("loads a legacy thread that fits in one read", async () => {
+    const { appServer, session } = await openCodexThread({
+      historyMode: "legacy",
+      turns: [{ id: "turn-1", items: [userItem("user-1", "Hello"), agentItem("agent-1", "Hi")] }],
+    });
+    try {
+      expect(timelineItems(await readHistory(session))).toEqual([
+        { type: "user_message", text: "Hello", messageId: "user-1" },
+        { type: "assistant_message", text: "Hi", messageId: "agent-1" },
+      ]);
+      expect(historyRequests(appServer).map((request) => request.method)).not.toContain(
+        "thread/items/list",
+      );
+    } finally {
+      await session.close();
+    }
+    appServer.assertNoErrors();
+  });
+
+  test("a legacy thread too big for one read shows the migration command", async () => {
+    const { appServer, session } = await openCodexThread(
+      {
+        historyMode: "legacy",
+        turns: [{ id: "turn-1", items: [userItem("user-1", "Hello"), agentItem("huge", "x")] }],
+      },
+      { oversizedItemIds: ["huge"] },
+    );
+    const migrationRow = {
+      type: "notification",
+      level: "warning",
+      message: expect.stringContaining("codex migrate-rollouts --apply --thread saved-thread"),
+    };
+    try {
+      expect(timelineItems(await readHistory(session))).toEqual([migrationRow]);
+      // The session stays up for the user to prompt until they archive it to migrate.
+      expect(timelineItems(await readHistory(session))).toEqual([migrationRow]);
+    } finally {
+      await session.close();
+    }
+    appServer.assertNoErrors();
+  });
+});
diff --git a/packages/server/src/server/agent/providers/codex/thread-history.ts b/packages/server/src/server/agent/providers/codex/thread-history.ts
new file mode 100644
index 0000000000..bf7461deb6
--- /dev/null
+++ b/packages/server/src/server/agent/providers/codex/thread-history.ts
@@ -0,0 +1,168 @@
+import { z } from "zod";
+
+import { CodexAppServerResponseTooLargeError } from "./app-server-transport.js";
+
+// Codex clamps history pages to 100 rows.
+const PAGE_SIZE = 100;
+
+export interface CodexThreadHistoryClient {
+  request(method: string, params?: unknown): Promise<unknown>;
+}
+
+export type CodexThreadHistoryMode = "legacy" | "paginated";
+
+export interface CodexHistoryRow {
+  item: unknown;
+  turnId: string | undefined;
+  /** The item's times on a paginated thread; its turn's on a legacy thread. */
+  startedAt: unknown;
+  completedAt: unknown;
+}
+
+/** A history reply over the line cap; the rows before it were already read. */
+export class CodexThreadHistoryTooLargeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CodexThreadHistoryTooLargeError";
+  }
+}
+
+const CodexThreadMetadataSchema = z
+  .object({
+    thread: z.object({ historyMode: z.enum(["legacy", "paginated"]).optional() }).passthrough(),
+  })
+  .passthrough();
+
+const CodexLegacyThreadReadSchema = z
+  .object({
+    thread: z
+      .object({
+        turns: z
+          .array(
+            z
+              .object({
+                id: z.string().optional(),
+                startedAt: z.unknown().optional(),
+                completedAt: z.unknown().optional(),
+                items: z.array(z.unknown()).default([]),
+              })
+              .passthrough(),
+          )
+          .default([]),
+      })
+      .passthrough()
+      .default({ turns: [] }),
+  })
+  .passthrough();
+
+const CodexItemsPageSchema = z
+  .object({
+    data: z.array(
+      z
+        .object({
+          turnId: z.string(),
+          item: z.unknown(),
+          startedAtMs: z.number().nullable().optional(),
+          completedAtMs: z.number().nullable().optional(),
+        })
+        .passthrough(),
+    ),
+    nextCursor: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+/** Codex builds before 0.143 report no history mode; their threads are legacy. */
+export async function readCodexThreadHistoryMode(
+  client: CodexThreadHistoryClient,
+  threadId: string,
+): Promise<CodexThreadHistoryMode> {
+  const response = CodexThreadMetadataSchema.parse(
+    await client.request("thread/read", { threadId, includeTurns: false }),
+  );
+  return response.thread.historyMode ?? "legacy";
+}
+
+/**
+ * Reads a thread's persisted items in order. Paginated threads are read in
+ * pages; a legacy thread arrives in one `thread/read` reply, as Codex offers
+ * no pages for it.
+ */
+export async function* readCodexThreadHistory(
+  client: CodexThreadHistoryClient,
+  threadId: string,
+): AsyncGenerator<CodexHistoryRow> {
+  if ((await readCodexThreadHistoryMode(client, threadId)) === "paginated") {
+    yield* readPaginatedHistory(client, threadId);
+  } else {
+    yield* readLegacyHistory(client, threadId);
+  }
+}
+
+async function* readLegacyHistory(
+  client: CodexThreadHistoryClient,
+  threadId: string,
+): AsyncGenerator<CodexHistoryRow> {
+  const response = await requestHistory(
+    client,
+    "thread/read",
+    { threadId, includeTurns: true },
+    `This Codex thread's history is too large to load in one read. ` +
+      `To move it to paginated history, archive this agent, ` +
+      `run \`codex migrate-rollouts --apply --thread ${threadId}\` (Codex 0.148 or newer), ` +
+      `then unarchive the agent.`,
+  );
+  for (const turn of CodexLegacyThreadReadSchema.parse(response).thread.turns) {
+    for (const item of turn.items) {
+      yield { item, turnId: turn.id, startedAt: turn.startedAt, completedAt: turn.completedAt };
+    }
+  }
+}
+
+async function* readPaginatedHistory(
+  client: CodexThreadHistoryClient,
+  threadId: string,
+): AsyncGenerator<CodexHistoryRow> {
+  const seenCursors = new Set<string>();
+  let cursor: string | undefined;
+  for (;;) {
+    const page = CodexItemsPageSchema.parse(
+      await requestHistory(
+        client,
+        "thread/items/list",
+        { threadId, limit: PAGE_SIZE, sortDirection: "asc", cursor },
+        "The rest of this Codex thread's history is too large to load.",
+      ),
+    );
+    for (const row of page.data) {
+      yield {
+        item: row.item,
+        turnId: row.turnId,
+        startedAt: row.startedAtMs,
+        completedAt: row.completedAtMs,
+      };
+    }
+    if (page.nextCursor == null) return;
+    // Codex's own client guards against a cursor that does not advance.
+    if (seenCursors.has(page.nextCursor)) {
+      throw new Error(`Codex repeated history cursor for thread ${threadId}`);
+    }
+    seenCursors.add(page.nextCursor);
+    cursor = page.nextCursor;
+  }
+}
+
+async function requestHistory(
+  client: CodexThreadHistoryClient,
+  method: string,
+  params: unknown,
+  tooLargeMessage: string,
+): Promise<unknown> {
+  try {
+    return await client.request(method, params);
+  } catch (error) {
+    if (error instanceof CodexAppServerResponseTooLargeError) {
+      throw new CodexThreadHistoryTooLargeError(tooLargeMessage);
+    }
+    throw error;
+  }
+}
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 64629bc5d9..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 {
@@ -950,6 +1058,7 @@ function mapCollabAgentToolCallItem(
     type: "sub_agent",
     subAgentType: "Sub-agent",
     ...(item.prompt ? { description: item.prompt } : {}),
+    // COMPAT(subagent-log): remove after 2027-04-30.
     log: "",
     actions: [],
   };
@@ -1006,6 +1115,7 @@ function mapSubAgentActivityItem(
       type: "sub_agent",
       subAgentType: nativeName,
       description,
+      // COMPAT(subagent-log): remove after 2027-04-30.
       log: "",
       actions: [],
     },
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/jsonl-frame-decoder.test.ts b/packages/server/src/server/agent/providers/jsonl-frame-decoder.test.ts
index af2bdabf01..4844415324 100644
--- a/packages/server/src/server/agent/providers/jsonl-frame-decoder.test.ts
+++ b/packages/server/src/server/agent/providers/jsonl-frame-decoder.test.ts
@@ -1,3 +1,4 @@
+import { measureMainThreadWork } from "../../../test-utils/main-thread-work.js";
 import { describe, expect, it } from "vitest";
 import { JsonlFrameDecoder, type JsonlFrameProblem } from "./jsonl-frame-decoder.js";
 
@@ -36,6 +37,16 @@ describe("JsonlFrameDecoder", () => {
     expect(problems).toEqual([]);
   });
 
+  it("preserves UTF-8 characters split across raw stdout buffers", () => {
+    const { decoder, frames, problems } = decoderHarness();
+    const bytes = Buffer.from('{"type":"notice","text":"é🙂"}\n');
+    const split = bytes.indexOf(Buffer.from("🙂")) + 1;
+    decoder.write(bytes.subarray(0, split));
+    decoder.write(bytes.subarray(split));
+    expect(frames).toEqual([{ type: "notice", text: "é🙂" }]);
+    expect(problems).toEqual([]);
+  });
+
   it("reassembles a large ordered v2 frame", () => {
     const { decoder, frames, problems } = decoderHarness();
     const frame = { type: "models", value: "x".repeat(1024 * 1024) };
@@ -55,3 +66,46 @@ describe("JsonlFrameDecoder", () => {
     expect(problems).toEqual(["out-of-order-chunk"]);
   });
 });
+
+describe("provider line admission", () => {
+  it("keeps the loop responsive while accumulating a fragmented provider response", async () => {
+    const { decoder, frames, problems } = decoderHarness();
+    const part = "x".repeat(512);
+    const { blockingMs } = await measureMainThreadWork("fragmented JSONL main-thread work", () => {
+      decoder.write('{"type":"notice","text":"');
+      // 1 MiB exposes the former rescan of every accumulated prefix.
+      for (let index = 0; index < 2048; index++) decoder.write(part);
+      decoder.write('"}\n');
+    });
+    expect(frames).toEqual([{ type: "notice", text: part.repeat(2048) }]);
+    expect(problems).toEqual([]);
+    expect(blockingMs).toBeLessThan(50);
+  });
+
+  it("rejects an unterminated over-cap UTF-8 line and stops accepting frames", () => {
+    const frames: Record<string, unknown>[] = [];
+    const failures: Array<{ problem: string; detail: unknown }> = [];
+    const decoder = new JsonlFrameDecoder({
+      frame: (frame) => frames.push(frame),
+      problem: (problem, detail) => failures.push({ problem, detail }),
+    });
+    // 64 MiB of UTF-8, only 32 Mi UTF-16 code units. No newline or JSON parse needed.
+    const chunk = "é".repeat(32 * 1024);
+    for (let index = 0; index < 1024; index++) decoder.write(chunk);
+    expect(failures).toEqual([]);
+    decoder.write("é");
+    expect(failures).toEqual([
+      {
+        problem: "line-too-large",
+        detail: expect.objectContaining({
+          name: "ProviderStreamLimitError",
+          code: "PROVIDER_STREAM_LINE_TOO_LARGE",
+          limitBytes: 64 * 1024 * 1024,
+        }),
+      },
+    ]);
+    decoder.write('\n{"type":"ready"}\n');
+    expect(frames).toEqual([]);
+    expect(failures).toHaveLength(1);
+  });
+});
diff --git a/packages/server/src/server/agent/providers/jsonl-frame-decoder.ts b/packages/server/src/server/agent/providers/jsonl-frame-decoder.ts
index 1662e7719c..ff8fa83489 100644
--- a/packages/server/src/server/agent/providers/jsonl-frame-decoder.ts
+++ b/packages/server/src/server/agent/providers/jsonl-frame-decoder.ts
@@ -1,3 +1,92 @@
+// Provider-process stdout only; these are not app/daemon wire limits.
+export const JSONL_PROVIDER_LINE_BYTES = 64 * 1024 * 1024;
+
+// Enough of an oversized line to read which response it was, e.g. `{"id":12,"result":`.
+const OVERSIZED_LINE_HEAD_BYTES = 64;
+
+export class ProviderStreamLimitError extends Error {
+  readonly code = "PROVIDER_STREAM_LINE_TOO_LARGE";
+
+  constructor(
+    readonly limitBytes: number,
+    /** The first bytes of the oversized line; the rest is discarded unread. */
+    readonly lineHead = "",
+  ) {
+    super(
+      `Provider stdout line exceeds ${limitBytes} bytes. Start a new thread or reduce the provider response size.`,
+    );
+    this.name = "ProviderStreamLimitError";
+  }
+}
+
+function readLineHead(parts: Buffer[]): string {
+  const head: Buffer[] = [];
+  let bytes = 0;
+  for (const part of parts) {
+    if (bytes >= OVERSIZED_LINE_HEAD_BYTES) break;
+    head.push(part.subarray(0, OVERSIZED_LINE_HEAD_BYTES - bytes));
+    bytes += head[head.length - 1].byteLength;
+  }
+  return Buffer.concat(head).toString("utf8");
+}
+
+/**
+ * Admits raw UTF-8 bytes before retaining, decoding or joining a complete line.
+ * An oversized line is reported with its head and skipped up to its newline;
+ * the owner closes the reader if the stream cannot continue without it.
+ */
+export class ProviderLineReader {
+  private parts: Buffer[] = [];
+  private bytes = 0;
+  private skippingOversizedLine = false;
+  private stopped = false;
+
+  constructor(
+    private readonly limitBytes: number,
+    private readonly onLine: (line: string) => void,
+    private readonly onLimit: (error: ProviderStreamLimitError) => void,
+  ) {}
+
+  write(chunk: Buffer | string): void {
+    if (this.stopped) return;
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+    let start = 0;
+    while (start < buffer.byteLength && !this.stopped) {
+      const newline = buffer.indexOf(10, start);
+      const end = newline === -1 ? buffer.byteLength : newline;
+      if (this.skippingOversizedLine) {
+        if (newline === -1) return;
+        this.skippingOversizedLine = false;
+        start = newline + 1;
+        continue;
+      }
+      const length = end - start;
+      if (length > this.limitBytes - this.bytes) {
+        const head = readLineHead([...this.parts, buffer.subarray(start, end)]);
+        this.parts = [];
+        this.bytes = 0;
+        this.skippingOversizedLine = true;
+        this.onLimit(new ProviderStreamLimitError(this.limitBytes, head));
+        continue;
+      }
+      if (length) this.parts.push(buffer.subarray(start, end));
+      this.bytes += length;
+      if (newline === -1) return;
+      const line = Buffer.concat(this.parts, this.bytes).toString("utf8");
+      this.parts = [];
+      this.bytes = 0;
+      this.onLine(line.endsWith("\r") ? line.slice(0, -1) : line);
+      start = newline + 1;
+    }
+  }
+
+  close(): void {
+    this.stopped = true;
+    this.parts = [];
+    this.bytes = 0;
+  }
+}
+
 const V2_FRAME_BYTES = 1024 * 1024;
 const V2_REASSEMBLED_BYTES = 64 * 1024 * 1024;
 const V2_CHUNK_BYTES = 256 * 1024;
@@ -5,6 +94,7 @@ const V2_BASE64_CHARS = Math.ceil(V2_CHUNK_BYTES / 3) * 4;
 const V2_MAX_CHUNKS = Math.ceil(V2_REASSEMBLED_BYTES / V2_CHUNK_BYTES);
 
 export type JsonlFrameProblem =
+  | "line-too-large"
   | "invalid-json"
   | "invalid-chunk"
   | "invalid-base64"
@@ -78,7 +168,7 @@ function chunkBytes(data: string): Buffer | null {
 }
 
 export class JsonlFrameDecoder {
-  private lineBuffer = "";
+  private readonly lines: ProviderLineReader;
   private assembly: ChunkAssembly | null = null;
 
   constructor(
@@ -86,17 +176,21 @@ export class JsonlFrameDecoder {
       frame(message: Record<string, unknown>): void;
       problem(problem: JsonlFrameProblem, detail?: unknown): void;
     },
-  ) {}
+  ) {
+    this.lines = new ProviderLineReader(
+      JSONL_PROVIDER_LINE_BYTES,
+      (line) => {
+        if (line.trim()) this.consumeLine(line);
+      },
+      (error) => {
+        this.lines.close();
+        this.drop("line-too-large", error);
+      },
+    );
+  }
 
-  write(text: string): void {
-    this.lineBuffer += text;
-    let newline = this.lineBuffer.indexOf("\n");
-    while (newline !== -1) {
-      const line = this.lineBuffer.slice(0, newline).replace(/\r$/, "");
-      this.lineBuffer = this.lineBuffer.slice(newline + 1);
-      if (line.trim()) this.consumeLine(line);
-      newline = this.lineBuffer.indexOf("\n");
-    }
+  write(chunk: Buffer | string): void {
+    this.lines.write(chunk);
   }
 
   private consumeLine(line: string): void {
diff --git a/packages/server/src/server/agent/providers/jsonl-rpc-process.test.ts b/packages/server/src/server/agent/providers/jsonl-rpc-process.test.ts
index 7dfbb6abb8..141b8f36f0 100644
--- a/packages/server/src/server/agent/providers/jsonl-rpc-process.test.ts
+++ b/packages/server/src/server/agent/providers/jsonl-rpc-process.test.ts
@@ -471,3 +471,25 @@ describe("JsonlRpcProcess", () => {
     }
   });
 });
+
+describe("JSONL stdout byte admission", () => {
+  test("fails pending requests and publishes the typed failure to live-turn consumers", async () => {
+    const child = createInMemoryChildProcess();
+    const process = startProcess({ child });
+    const exit = new Promise<JsonlRpcExit>((resolve) => process.onExit(resolve));
+    const request = process.request({ type: "hang" }, 1000).catch((error: Error) => error);
+    const chunk = Buffer.alloc(64 * 1024, "x");
+    child.stdout.write('{"type":"notice","text":"');
+    for (let index = 0; index < 1024; index++) child.stdout.write(chunk);
+    const error = await request;
+    expect(error).toMatchObject({
+      name: "ProviderStreamLimitError",
+      code: "PROVIDER_STREAM_LINE_TOO_LARGE",
+      limitBytes: 64 * 1024 * 1024,
+    });
+    expect((await exit).error).toBe(error);
+    await process.close();
+    child.stdout.end();
+    child.stderr.end();
+  });
+});
diff --git a/packages/server/src/server/agent/providers/jsonl-rpc-process.ts b/packages/server/src/server/agent/providers/jsonl-rpc-process.ts
index 9d8b9af623..ddf85eb316 100644
--- a/packages/server/src/server/agent/providers/jsonl-rpc-process.ts
+++ b/packages/server/src/server/agent/providers/jsonl-rpc-process.ts
@@ -3,7 +3,7 @@ import type { Logger } from "pino";
 
 import { spawnProcess } from "../../../utils/spawn.js";
 import { terminateWithTreeKill } from "../../../utils/tree-kill.js";
-import { JsonlFrameDecoder } from "./jsonl-frame-decoder.js";
+import { JsonlFrameDecoder, ProviderStreamLimitError } from "./jsonl-frame-decoder.js";
 export { supportsJsonlRpcProtocolV2 } from "./jsonl-frame-decoder.js";
 
 /** Default wall-clock timeout for control-plane / short RPC calls. */
@@ -81,6 +81,7 @@ export class JsonlRpcProcess {
   private stderrBuffer = "";
   private nextRequestId = 1;
   private disposed = false;
+  private streamFailure: ProviderStreamLimitError | null = null;
   private exited = false;
   private closing: Promise<void> | null = null;
   private readonly frameDecoder: JsonlFrameDecoder;
@@ -90,6 +91,14 @@ export class JsonlRpcProcess {
     this.frameDecoder = new JsonlFrameDecoder({
       frame: (message) => this.dispatchFrame(message),
       problem: (problem, detail) => {
+        if (problem === "line-too-large" && detail instanceof ProviderStreamLimitError) {
+          // Stop the producer: silently skipping a response or turn event loses state.
+          this.streamFailure = detail;
+          void this.close(detail).catch((err) => {
+            this.options.logger.warn({ err }, `Failed to close ${this.diagnosticName}`);
+          });
+          return;
+        }
         this.options.logger.warn(
           { problem, detail },
           `Ignoring invalid ${this.diagnosticName} frame`,
@@ -98,7 +107,7 @@ export class JsonlRpcProcess {
     });
     this.child = (options.spawn ?? spawnJsonlRpcProcess)(options.launch);
     this.child.stdout.on("data", (chunk) => {
-      this.handleStdoutChunk(chunk.toString());
+      this.handleStdoutChunk(chunk);
     });
     this.child.stderr.on("data", (chunk) => {
       this.stderrBuffer += chunk.toString();
@@ -114,9 +123,11 @@ export class JsonlRpcProcess {
     });
     this.child.on("exit", (code, signal) => {
       this.exited = true;
-      const error = new Error(
-        `${this.diagnosticName} process exited with code ${code ?? "null"} and signal ${signal ?? "null"}\n${this.stderrBuffer}`.trim(),
-      );
+      const error =
+        this.streamFailure ??
+        new Error(
+          `${this.diagnosticName} process exited with code ${code ?? "null"} and signal ${signal ?? "null"}\n${this.stderrBuffer}`.trim(),
+        );
       const exit = { code, signal, error };
       for (const subscriber of this.exitSubscribers) {
         subscriber(exit);
@@ -254,7 +265,7 @@ export class JsonlRpcProcess {
     }
   }
 
-  private handleStdoutChunk(chunk: string): void {
+  private handleStdoutChunk(chunk: Buffer | string): void {
     this.frameDecoder.write(chunk);
   }
 
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 7055030dc0..14322c6ccf 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
@@ -230,6 +230,7 @@ interface LargeAgentStreamPayloadRequest {
 }
 
 interface AgentStreamStressRequest {
+  tools: boolean;
   count: number;
   coalesced: boolean;
 }
@@ -461,7 +462,7 @@ function parseLargeAgentStreamPayloadPrompt(
 
 function parseAgentStreamStressPrompt(prompt: AgentPromptInput): AgentStreamStressRequest | null {
   const text = promptToText(prompt);
-  const match = /emit\s+(\d+)\s+(coalesced\s+)?agent stream updates/i.exec(text);
+  const match = /emit\s+(\d+)\s+(coalesced\s+|tool\s+)?agent stream updates/i.exec(text);
   if (!match) {
     return null;
   }
@@ -471,7 +472,8 @@ function parseAgentStreamStressPrompt(prompt: AgentPromptInput): AgentStreamStre
   }
   return {
     count: Math.min(count, 5_000),
-    coalesced: Boolean(match[2]),
+    coalesced: match[2]?.trim() === "coalesced",
+    tools: match[2]?.trim() === "tool",
   };
 }
 
@@ -1452,21 +1454,37 @@ export class MockLoadTestAgentSession implements AgentSession {
     this.emitTurnStarted(turn);
 
     for (let index = 0; index < stress.count; index += 1) {
-      this.emitTimeline(
-        turn.turnId,
-        stress.coalesced
-          ? {
-              type: "assistant_message",
-              text: `stress-update-${index}`,
-              messageId: turn.assistantMessageId,
-            }
-          : {
-              type: "todo",
-              items: [{ text: `stress-update-${index}`, completed: index % 2 === 0 }],
-            },
-      );
+      let item: AgentTimelineItem;
+      if (stress.tools) {
+        item = {
+          type: "tool_call",
+          callId: `${turn.turnId}:stress:${index}`,
+          name: "Bash",
+          status: "completed",
+          error: null,
+          detail: { type: "shell", command: `echo stress-${index}`, output: `stress-${index}` },
+        };
+      } else if (stress.coalesced) {
+        item = {
+          type: "assistant_message",
+          text: `stress-update-${index}`,
+          messageId: turn.assistantMessageId,
+        };
+      } else {
+        item = {
+          type: "todo",
+          items: [{ text: `stress-update-${index}`, completed: index % 2 === 0 }],
+        };
+      }
+      this.emitTimeline(turn.turnId, item);
     }
 
+    if (stress.tools)
+      this.emitTimeline(turn.turnId, {
+        type: "assistant_message",
+        text: `Completed ${stress.count} commands`,
+        messageId: turn.assistantMessageId,
+      });
     this.activeTurn = null;
     const usage = {
       inputTokens: 1,
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 983f9cf55f..15392fc07c 100644
--- a/packages/server/src/server/agent/providers/omp/agent.test.ts
+++ b/packages/server/src/server/agent/providers/omp/agent.test.ts
@@ -1133,6 +1133,17 @@ describe("OMP agent client and session", () => {
         messageId: "assistant-history",
       },
     ]);
+    await expect(
+      omp.runPrompt("continue after resume", "resumed follow-up complete"),
+    ).resolves.toMatchObject({
+      finalText: "resumed follow-up complete",
+    });
+    expect(omp.timeline()).toContainEqual(
+      expect.objectContaining({
+        type: "assistant_message",
+        text: "resumed follow-up complete",
+      }),
+    );
     expect(omp.usageSession()).toMatchObject({ provider: "omp", sessionKey: expect.any(String) });
     await omp.close();
     expect(omp.usageSession()).toBeNull();
@@ -1332,13 +1343,14 @@ describe("OMP agent client and session", () => {
     expect(omp.runtimeLaunches()).toHaveLength(1);
   });
 
-  test("closes a replacement process if the session closes during relaunch", async () => {
+  test("rejects a pending recovery start and closes its processes when the session closes", async () => {
     const omp = new OmpHarness();
     await omp.start();
     omp.processExit("OMP RPC process exited with code 1 and signal null");
     const turn = omp.startTurnDetached("continue");
+    const rejected = expect(turn).rejects.toThrow("closed");
     await omp.close();
-    await turn;
+    await rejected;
     await waitForImmediate();
     expect(omp.runtimeSessions().every((session) => session.closed)).toBe(true);
   });
@@ -1627,3 +1639,93 @@ test.each([
     expect(await session.canStopRuntime!()).toBe(expected);
   },
 );
+
+test.each([false, true])(
+  "image prompt keeps OMP's vision capability contract (vision: %s)",
+  async (vision) => {
+    const runtime = new FakeOmp();
+    runtime.queueSessionSetup((session) => {
+      session.state = {
+        ...session.state,
+        model: {
+          provider: "test",
+          id: "image-model",
+          input: vision ? ["text", "image"] : ["text"],
+        },
+      };
+    });
+    const client = new OmpAgentClient({ logger: createTestLogger(), runtime });
+    const session = await client.createSession({ provider: "omp", cwd: process.cwd() });
+    onTestFinished(() => session.close());
+    const bytes = Buffer.from("OMP attachment fixture");
+    const first = session.startTurn([
+      { type: "text", text: "Describe this image." },
+      { type: "image", data: bytes.toString("base64"), mimeType: "image/png" },
+    ]);
+    await expect(session.startTurn("overlapping prompt")).rejects.toThrow("already active");
+    await first;
+    const [prompt] = runtime.latestSession().prompts;
+    expect(prompt.imageCount).toBe(vision ? 1 : 0);
+    if (vision) expect(prompt.message).toBe("Describe this image.");
+    else {
+      const imagePath = prompt.message.match(/\[Image available at: (.+)\]/)?.[1];
+      expect(imagePath).toBeTruthy();
+      const { readFile, rm } = await import("node:fs/promises");
+      expect(await readFile(imagePath!)).toEqual(bytes);
+      await rm(imagePath!);
+    }
+  },
+);
+
+test("interrupting OMP during image conversion cancels the admitted turn and permits a follow-up", async () => {
+  const runtime = new FakeOmp();
+  const client = new OmpAgentClient({ logger: createTestLogger(), runtime });
+  const session = await client.createSession({ provider: "omp", cwd: process.cwd() });
+  onTestFinished(() => session.close());
+  const events: AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  let admitted = false;
+  const first = session
+    .startTurn([
+      {
+        type: "image",
+        data: Buffer.alloc(16 * 1024 * 1024, 53).toString("base64"),
+        mimeType: "image/png",
+      },
+    ])
+    .then((result) => {
+      admitted = true;
+      return result;
+    });
+  await waitForImmediate();
+  expect(admitted).toBe(false);
+  expect(runtime.latestSession().prompts).toHaveLength(0);
+  await session.interrupt();
+  const followup = await session.startTurn("follow-up after image interrupt");
+  const original = await first;
+  expect(events).toContainEqual(
+    expect.objectContaining({ type: "turn_canceled", turnId: original.turnId }),
+  );
+  expect(followup.turnId).not.toBe(original.turnId);
+  expect(runtime.latestSession().prompts).toEqual([
+    { message: "follow-up after image interrupt", imageCount: 0 },
+  ]);
+});
+
+test("closing OMP during image conversion rejects its pending start", async () => {
+  const runtime = new FakeOmp();
+  const client = new OmpAgentClient({ logger: createTestLogger(), runtime });
+  const session = await client.createSession({ provider: "omp", cwd: process.cwd() });
+  const first = session.startTurn([
+    {
+      type: "image",
+      data: Buffer.alloc(16 * 1024 * 1024, 54).toString("base64"),
+      mimeType: "image/png",
+    },
+  ]);
+  const rejected = expect(first).rejects.toThrow("closed");
+  await waitForImmediate();
+  expect(runtime.latestSession().prompts).toHaveLength(0);
+  await session.close();
+  await rejected;
+});
diff --git a/packages/server/src/server/agent/providers/omp/agent.ts b/packages/server/src/server/agent/providers/omp/agent.ts
index 434a49d89e..c8b44c0bd8 100644
--- a/packages/server/src/server/agent/providers/omp/agent.ts
+++ b/packages/server/src/server/agent/providers/omp/agent.ts
@@ -69,7 +69,7 @@ import {
   type OmpRuntimeOptions,
 } from "./provider-config.js";
 export { formatOmpVersionSupport, resolveOmpDiagnosticPaths } from "./provider-config.js";
-import { OmpSubagentCardTracker, type OmpSubagentCardScheduler } from "./subagent-card-tracker.js";
+import { OmpSubagentCardTracker } from "./subagent-card-tracker.js";
 import { ompSkillPromptUserText, shouldDisplayOmpCustomMessage } from "./custom-message.js";
 import { getUserMessageText } from "./message-history.js";
 import { mapOmpSystemNoticeToNotification } from "./system-notice.js";
@@ -130,7 +130,6 @@ export interface OmpAgentClientOptions {
   logger: Logger;
   runtimeSettings?: ProviderRuntimeSettings;
   runtime?: OmpRuntime;
-  subagentCardScheduler?: OmpSubagentCardScheduler;
   providerIdleScheduler?: OmpProviderIdleScheduler;
   noTurnScheduler?: OmpNoTurnScheduler;
   usagePollScheduler?: OmpUsagePollScheduler;
@@ -205,7 +204,6 @@ interface OmpAgentSessionOptions {
   initialState: OmpSessionState;
   currentModeId?: string | null;
   logger: Logger;
-  subagentCardScheduler?: OmpSubagentCardScheduler;
   providerIdleScheduler?: OmpProviderIdleScheduler;
   noTurnScheduler?: OmpNoTurnScheduler;
   usagePollScheduler?: OmpUsagePollScheduler;
@@ -317,9 +315,9 @@ function ompModelSupportsImageInput(model: OmpModel | null | undefined): boolean
   return model?.input?.includes("image") === true;
 }
 
-function renderTextOnlyImageHint(image: { data: string; mimeType: string }): string {
+async function renderTextOnlyImageHint(image: { data: string; mimeType: string }): Promise<string> {
   try {
-    const materialized = materializeProviderImage({
+    const materialized = await materializeProviderImage({
       data: image.data,
       mimeType: image.mimeType,
     });
@@ -329,10 +327,10 @@ function renderTextOnlyImageHint(image: { data: string; mimeType: string }): str
   }
 }
 
-function convertPromptInput(
+async function convertPromptInput(
   prompt: AgentPromptInput,
   options: { model: OmpModel | null | undefined },
-): OmpPromptPayload {
+): Promise<OmpPromptPayload> {
   if (typeof prompt === "string") {
     return { text: prompt };
   }
@@ -355,7 +353,7 @@ function convertPromptInput(
           mimeType: block.mimeType,
         });
       } else {
-        textParts.push(renderTextOnlyImageHint(block));
+        textParts.push(await renderTextOnlyImageHint(block));
       }
       continue;
     }
@@ -773,9 +771,7 @@ export class OmpAgentSession implements AgentSession {
         this.logger.debug({ err: error }, "OMP context usage poll failed");
       },
     });
-    this.subagentCardTracker = new OmpSubagentCardTracker({
-      scheduler: options.subagentCardScheduler,
-    });
+    this.subagentCardTracker = new OmpSubagentCardTracker();
     this.lastKnownThinkingOptionId =
       normalizeOmpThinkingOption(options.config.thinkingOptionId) ??
       this.state.thinkingLevel ??
@@ -868,11 +864,9 @@ export class OmpAgentSession implements AgentSession {
       throw new Error("An OMP turn is already active");
     }
 
-    const payload = convertPromptInput(prompt, { model: this.state.model });
     const turnId = randomUUID();
     this.live = true;
     this.activeTurnId = turnId;
-    this.rememberClientMessage(options?.clientMessageId ?? null, payload.text);
     this.activeAssistantMessageId = null;
     this.activeTurnTerminalAssistantMessage = null;
     this.activeTurnStarted = false;
@@ -880,6 +874,10 @@ export class OmpAgentSession implements AgentSession {
     this.activeTurnHasUserMessage = false;
     this.activePromptRequestId = null;
     this.clearNoTurnBuffers();
+    const payload = await convertPromptInput(prompt, { model: this.state.model });
+    if (this.closed) throw new Error("OMP session is closed");
+    if (this.activeTurnId !== turnId) return { turnId };
+    this.rememberClientMessage(options?.clientMessageId ?? null, payload.text);
     this.activeNoTurnPromptText = payload.text;
     this.usagePoller.startTurn();
     if (announceTurn) {
@@ -946,7 +944,9 @@ export class OmpAgentSession implements AgentSession {
   ): Promise<SteerResult> {
     if (this.closed || this.activeTurnId !== options.expectedTurnId)
       return { status: "unavailable" };
-    const payload = convertPromptInput(prompt, { model: this.state.model });
+    const payload = await convertPromptInput(prompt, { model: this.state.model });
+    if (this.closed || this.activeTurnId !== options.expectedTurnId)
+      return { status: "unavailable" };
     if (this.parseSlashCommandInput(payload.text)) return { status: "unavailable" };
     const submission = this.rememberClientMessage(options.clientMessageId ?? null, payload.text);
     try {
@@ -2151,8 +2151,7 @@ export class OmpAgentSession implements AgentSession {
     return mapOmpToolDetail(toolCall, result, {
       toolCallId,
       bridgedTool: this.hostTools?.bridge?.tool(toolCall.toolName),
-      mapSubagentDetail: (detail) =>
-        this.subagentCardTracker.detailFor(toolCallId, detail) ?? detail,
+      mapSubagentDetail: (detail) => this.subagentCardTracker.detailFor(toolCallId, detail),
     });
   }
 
@@ -2242,7 +2241,6 @@ export class OmpAgentClient implements AgentClient {
 
   private readonly logger: Logger;
   private readonly runtimeSettings?: ProviderRuntimeSettings;
-  private readonly subagentCardScheduler?: OmpSubagentCardScheduler;
   private readonly providerIdleScheduler?: OmpProviderIdleScheduler;
   private readonly noTurnScheduler?: OmpNoTurnScheduler;
   private readonly usagePollScheduler?: OmpUsagePollScheduler;
@@ -2261,7 +2259,6 @@ export class OmpAgentClient implements AgentClient {
     );
     this.logger = options.logger;
     this.runtimeSettings = runtimeSettings;
-    this.subagentCardScheduler = options.subagentCardScheduler;
     this.providerIdleScheduler = options.providerIdleScheduler;
     this.noTurnScheduler = options.noTurnScheduler;
     this.usagePollScheduler = options.usagePollScheduler;
@@ -2345,7 +2342,6 @@ export class OmpAgentClient implements AgentClient {
         initialState,
         currentModeId: launchMode.modeId,
         logger: this.logger,
-        subagentCardScheduler: this.subagentCardScheduler,
         providerIdleScheduler: this.providerIdleScheduler,
         noTurnScheduler: this.noTurnScheduler,
         usagePollScheduler: this.usagePollScheduler,
@@ -2417,7 +2413,6 @@ export class OmpAgentClient implements AgentClient {
         initialState,
         currentModeId: launchMode.modeId,
         logger: this.logger,
-        subagentCardScheduler: this.subagentCardScheduler,
         providerIdleScheduler: this.providerIdleScheduler,
         noTurnScheduler: this.noTurnScheduler,
         usagePollScheduler: this.usagePollScheduler,
diff --git a/packages/server/src/server/agent/providers/omp/history-mapper.test.ts b/packages/server/src/server/agent/providers/omp/history-mapper.test.ts
index e64a93fd64..6d39c21c2d 100644
--- a/packages/server/src/server/agent/providers/omp/history-mapper.test.ts
+++ b/packages/server/src/server/agent/providers/omp/history-mapper.test.ts
@@ -1,4 +1,5 @@
 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, test } from "vitest";
@@ -8,7 +9,7 @@ import { streamOmpCoreHistory, type OmpCapturedUserMessageEntry } from "./messag
 import type { OmpAgentMessage } from "./rpc-types.js";
 import { FakeOmp } from "./test-utils/fake-omp.js";
 import { OMP_HISTORY_MAPPER_HOOKS } from "./history-hooks.js";
-import { readOmpHistoryTodoState, streamOmpHistory } from "./history.js";
+import { readActiveOmpEntryChain, readOmpHistoryTodoState, streamOmpHistory } from "./history.js";
 
 async function collectHistory(
   messages: OmpAgentMessage[],
@@ -636,7 +637,7 @@ describe("OMP history mapper", () => {
             subAgentType: "explore",
             description: "Inspect files",
             childSessionId: "/tmp/omp-task/Explore.jsonl",
-            log: "done\ntranscript: /tmp/omp-task/Explore.jsonl",
+            log: "",
           },
           error: null,
         },
@@ -1245,3 +1246,53 @@ describe("OMP history mapper", () => {
     );
   });
 });
+
+test("indexes out-of-order branches, duplicate IDs and cycles before selecting history", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "omp-history-branches-"));
+  const sessionFile = join(directory, "session.jsonl");
+  const root = { id: "root", parentId: null };
+  const earlyLeaf = {
+    id: "early",
+    parentId: "root",
+    message: { role: "user", content: "你好🌍".repeat(15000) },
+  };
+  const branch = { id: "branch", parentId: "root" };
+  const active = { id: "active", parentId: "branch" };
+  const duplicate = {
+    id: "branch",
+    parentId: "root",
+    message: { role: "user", content: "replacement" },
+  };
+  try {
+    await writeFile(
+      sessionFile,
+      [earlyLeaf, active, root, branch, duplicate]
+        .map((entry) => JSON.stringify(entry))
+        .join("\n") + '\n{"id":',
+    );
+    // The final record is a branch ancestor, not the active leaf. Latest duplicate wins
+    // when following parents; the invalid tail contributes neither a leaf nor a parent.
+    await expect(readActiveOmpEntryChain(sessionFile)).resolves.toEqual([root, duplicate, active]);
+    await expect(readActiveOmpEntryChain(sessionFile, "early")).resolves.toEqual([root, earlyLeaf]);
+    await expect(readActiveOmpEntryChain(sessionFile, "missing")).resolves.toEqual([
+      root,
+      duplicate,
+      active,
+    ]);
+    const cycle = [
+      { id: "a", parentId: "b" },
+      { id: "b", parentId: "a" },
+    ];
+    await writeFile(sessionFile, cycle.map((entry) => JSON.stringify(entry)).join("\n"));
+    await expect(readActiveOmpEntryChain(sessionFile)).resolves.toEqual(cycle);
+    await writeFile(sessionFile, "null\n{}\ninvalid\n");
+    await expect(readActiveOmpEntryChain(sessionFile)).resolves.toEqual([]);
+    await expect(readActiveOmpEntryChain(directory)).rejects.toMatchObject({ code: "EISDIR" });
+    await expect(readActiveOmpEntryChain(join(directory, "missing"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+    await expect(readOmpHistoryTodoState(join(directory, "missing"))).resolves.toBeNull();
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
diff --git a/packages/server/src/server/agent/providers/omp/history.e2e.test.ts b/packages/server/src/server/agent/providers/omp/history.e2e.test.ts
new file mode 100644
index 0000000000..f0a00d5a0d
--- /dev/null
+++ b/packages/server/src/server/agent/providers/omp/history.e2e.test.ts
@@ -0,0 +1,99 @@
+import { measureMainThreadWork } from "../../../../test-utils/main-thread-work.js";
+import { BUILTIN_PROVIDER_IDS } from "@getpaseo/protocol/provider-manifest";
+import { mkdtemp, open, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { setTimeout as delay } from "node:timers/promises";
+import { expect, test } from "vitest";
+import { createTestPaseoDaemon } from "../../../test-utils/paseo-daemon.js";
+import { DaemonClient } from "../../../test-utils/daemon-client.js";
+import { readActiveOmpEntryChain } from "./history.js";
+
+test("replays selected OMP history without blocking the event loop", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "omp-history-budget-"));
+  const sessionFile = join(directory, "session.jsonl");
+  const started = performance.now();
+  try {
+    const daemon = await createTestPaseoDaemon({
+      // This regression exercises file replay and daemon requests, not executable discovery.
+      providerOverrides: Object.fromEntries(
+        BUILTIN_PROVIDER_IDS.map((id) => [id, { enabled: false }]),
+      ),
+    });
+    const client = new DaemonClient({
+      url: `ws://127.0.0.1:${daemon.port}/ws`,
+      appVersion: "0.13.2",
+    });
+    try {
+      await client.connect();
+      await client.fetchAgents({ subscribe: {} });
+      await client.getDaemonStatus();
+      const file = await open(sessionFile, "w");
+      // Structured message blocks expose document-sized parsing at a modest byte size.
+      // Replay an earlier active entry so inactive payload retention cannot drive the probe.
+      const text = Array.from({ length: 64 }, () => ({ type: "text", text: "x" }));
+      let bytes = 0;
+      let count = 0;
+      try {
+        while (bytes < 28 * 1024 * 1024) {
+          const line =
+            JSON.stringify({
+              type: "message",
+              id: `row-${count}`,
+              parentId: count ? `row-${count - 1}` : null,
+              message: { role: "user", content: text },
+            }) + "\n";
+          bytes += Buffer.byteLength(line);
+          await file.write(line);
+          count++;
+        }
+      } finally {
+        await file.close();
+      }
+      let repliesDuringReplay = 0;
+      const { result: replayedEntries, blockingMs } = await measureMainThreadWork(
+        "OMP history main-thread work",
+        async () => {
+          const replayState = { finished: false };
+          const replay = readActiveOmpEntryChain(sessionFile, "row-0").finally(() => {
+            replayState.finished = true;
+          });
+          // A real WebSocket RPC served by the isolated daemon on the same event loop.
+          const requests = (async () => {
+            while (!replayState.finished) {
+              await client.getDaemonStatus();
+              if (!replayState.finished) repliesDuringReplay++;
+              await delay(10);
+            }
+          })();
+          const [entries] = await Promise.all([replay, requests]);
+          return entries;
+        },
+      );
+      console.log(
+        JSON.stringify({
+          bytes,
+          count,
+          blockingMs,
+          repliesDuringReplay,
+          generationAndLoadMs: performance.now() - started,
+        }),
+      );
+      expect(replayedEntries).toEqual([
+        {
+          type: "message",
+          id: "row-0",
+          parentId: null,
+          message: { role: "user", content: text },
+        },
+      ]);
+      expect(blockingMs).toBeLessThan(50);
+      expect(repliesDuringReplay).toBeGreaterThan(0);
+    } finally {
+      await client.close().finally(() => daemon.close());
+    }
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}, 30000);
diff --git a/packages/server/src/server/agent/providers/omp/history.ts b/packages/server/src/server/agent/providers/omp/history.ts
index 2c818dfc5a..5102dfd44b 100644
--- a/packages/server/src/server/agent/providers/omp/history.ts
+++ b/packages/server/src/server/agent/providers/omp/history.ts
@@ -1,4 +1,5 @@
-import { readFile } from "node:fs/promises";
+import { open, type FileHandle } from "node:fs/promises";
+import { setImmediate } from "node:timers/promises";
 import { basename, extname, join } from "node:path";
 import type { AgentProvider, AgentStreamEvent, AgentTimelineItem } from "../../agent-sdk-types.js";
 import { normalizeProviderReplayTimestamp } from "../../provider-history-timestamps.js";
@@ -96,7 +97,9 @@ export async function* streamOmpHistory(input: {
   const messages: OmpAgentMessage[] = [];
   const replayEntries: OmpReplayEntry[] = [];
   const userEntries: OmpCapturedUserMessageEntry[] = [];
+  let prepared = 0;
   for (const entry of entries) {
+    if (++prepared % 32 === 0) await setImmediate();
     if (entry.type === "compaction") {
       replayEntries.push({ entry, item: mapCompactionEntry(entry) });
       continue;
@@ -115,7 +118,9 @@ export async function* streamOmpHistory(input: {
     OMP_HISTORY_MAPPER_HOOKS,
     input.bridgedTools,
   );
+  let replayed = 0;
   for (const replayEntry of replayEntries) {
+    if (++replayed % 32 === 0) await setImmediate();
     const timestamp = normalizeProviderReplayTimestamp(replayEntry.entry.timestamp);
     const events: AgentStreamEvent[] =
       "item" in replayEntry
@@ -329,34 +334,139 @@ function stripExtension(filePath: string): string {
   return extension ? filePath.slice(0, -extension.length) : filePath;
 }
 
-export async function readActiveOmpEntryChain(
-  sessionFile: string,
-  activeEntryId?: string,
-): Promise<OmpSessionEntry[]> {
-  const content = await readFile(sessionFile, "utf8");
-  const entries = content.split("\n").flatMap((line) => {
-    if (!line.trim()) return [];
-    try {
-      const value = JSON.parse(line) as OmpSessionEntry;
-      return value && typeof value === "object" && typeof value.id === "string" ? [value] : [];
-    } catch {
-      return [];
+interface OmpEntryLocation {
+  id: string;
+  parentId?: string | null;
+  offset: number;
+}
+
+// Yield after each bounded IO chunk, including chunks containing only tiny or invalid records.
+// Keep bytes until a complete line so multi-byte UTF-8 characters survive chunk boundaries.
+async function* readOmpLines(
+  file: FileHandle,
+  size: number,
+): AsyncGenerator<{
+  line: Buffer;
+  offset: number;
+}> {
+  const chunkSize = 64 * 1024;
+  let fragments: Buffer[] = [];
+  let lineOffset = 0;
+  for (let position = 0; position < size; ) {
+    const chunk = Buffer.allocUnsafe(Math.min(chunkSize, size - position));
+    const { bytesRead } = await file.read(chunk, 0, chunk.length, position);
+    if (!bytesRead) break;
+    let start = 0;
+    for (let index = 0; index < bytesRead; index++) {
+      if (chunk[index] !== 10) continue;
+      const tail = chunk.subarray(start, index);
+      const line = fragments.length ? Buffer.concat([...fragments, tail]) : tail;
+      yield { line, offset: lineOffset };
+      fragments = [];
+      start = index + 1;
+      lineOffset = position + start;
     }
-  });
-  if (entries.length === 0) return [];
-  const byId = new Map(entries.map((entry) => [entry.id!, entry]));
-  const parentIds = new Set(entries.flatMap((entry) => (entry.parentId ? [entry.parentId] : [])));
-  const leaves = entries.filter((entry) => !parentIds.has(entry.id!));
-  let current: OmpSessionEntry | undefined =
-    (activeEntryId ? byId.get(activeEntryId) : undefined) ?? leaves.at(-1) ?? entries.at(-1);
-  const chain: OmpSessionEntry[] = [];
+    if (start < bytesRead) fragments.push(chunk.subarray(start, bytesRead));
+    position += bytesRead;
+    await setImmediate();
+  }
+  if (fragments.length) yield { line: Buffer.concat(fragments), offset: lineOffset };
+}
+
+function parseOmpEntry(line: Buffer): OmpSessionEntry | null {
+  try {
+    const value: unknown = JSON.parse(line.toString("utf8"));
+    return value && typeof value === "object" && typeof Reflect.get(value, "id") === "string"
+      ? (value as OmpSessionEntry)
+      : null;
+  } catch {
+    // OMP can leave a partial last record; malformed records have always been ignored.
+    return null;
+  }
+}
+
+async function selectOmpChain(
+  locations: readonly OmpEntryLocation[],
+  byId: ReadonlyMap<string, OmpEntryLocation>,
+  parentIds: ReadonlySet<string>,
+  activeEntryId?: string,
+): Promise<OmpEntryLocation[]> {
+  let current = activeEntryId ? byId.get(activeEntryId) : undefined;
+  if (!current) {
+    for (let index = locations.length - 1; index >= 0; index--) {
+      const location = locations[index]!;
+      if (!parentIds.has(location.id)) {
+        current = location;
+        break;
+      }
+      if (index % 256 === 0) await setImmediate();
+    }
+    current ??= locations.at(-1);
+  }
+  const chain: OmpEntryLocation[] = [];
   const seen = new Set<string>();
   while (current?.id && !seen.has(current.id)) {
     chain.push(current);
     seen.add(current.id);
     current = current.parentId ? byId.get(current.parentId) : undefined;
+    if (chain.length % 256 === 0) await setImmediate();
+  }
+  return chain;
+}
+
+export async function readActiveOmpEntryChain(
+  sessionFile: string,
+  activeEntryId?: string,
+): Promise<OmpSessionEntry[]> {
+  const file = await open(sessionFile, "r");
+  try {
+    const stat = await file.stat();
+    if (stat.isDirectory()) {
+      throw Object.assign(
+        new Error(`EISDIR: illegal operation on a directory, read '${sessionFile}'`),
+        {
+          code: "EISDIR",
+        },
+      );
+    }
+    // One descriptor and a fixed byte boundary exclude appends made while replay is yielding.
+    // Retain graph metadata only: abandoned branches must not retain their message payloads.
+    const locations: OmpEntryLocation[] = [];
+    const byId = new Map<string, OmpEntryLocation>();
+    const parentIds = new Set<string>();
+    for await (const { line, offset } of readOmpLines(file, stat.size)) {
+      const entry = parseOmpEntry(line);
+      if (!entry) continue;
+      const location = { id: entry.id!, parentId: entry.parentId, offset };
+      locations.push(location);
+      byId.set(location.id, location);
+      if (location.parentId) parentIds.add(location.parentId);
+    }
+    const chain = await selectOmpChain(locations, byId, parentIds, activeEntryId);
+    if (chain.length === 0) return [];
+    const selected = new Map<number, number>();
+    for (let index = 0; index < chain.length; index++) {
+      selected.set(chain[index]!.offset, chain.length - index - 1);
+      if (index % 256 === 0) await setImmediate();
+    }
+    const entries: OmpSessionEntry[] = [];
+    for await (const { line, offset } of readOmpLines(file, stat.size)) {
+      const index = selected.get(offset);
+      if (index === undefined) continue;
+      const entry = parseOmpEntry(line);
+      // Truncation in place invalidates the indexed snapshot; never publish a partial chain.
+      if (!entry || entry.id !== chain[chain.length - index - 1]!.id) {
+        throw new Error(`OMP transcript changed during replay: ${sessionFile}`);
+      }
+      entries[index] = entry;
+      selected.delete(offset);
+      if (selected.size === 0) break;
+    }
+    if (selected.size) throw new Error(`OMP transcript changed during replay: ${sessionFile}`);
+    return entries;
+  } finally {
+    await file.close();
   }
-  return chain.toReversed();
 }
 
 function mapEntryMessage(entry: OmpSessionEntry): OmpAgentMessage | null {
diff --git a/packages/server/src/server/agent/providers/omp/subagent-card-tracker.test.ts b/packages/server/src/server/agent/providers/omp/subagent-card-tracker.test.ts
index 5164097661..6819292d33 100644
--- a/packages/server/src/server/agent/providers/omp/subagent-card-tracker.test.ts
+++ b/packages/server/src/server/agent/providers/omp/subagent-card-tracker.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, test } from "vitest";
 
-import { OmpSubagentCardTracker, type OmpSubagentCardScheduler } from "./subagent-card-tracker.js";
+import { OmpSubagentCardTracker } from "./subagent-card-tracker.js";
 import type { OmpSubagentLifecyclePayload, OmpSubagentProgressPayload } from "./rpc-types.js";
 
 const PARENT_TOOL_CALL_ID = "task-1";
@@ -59,184 +59,84 @@ const PROGRESS: OmpSubagentProgressPayload[] = [
   },
 ];
 
-class ManualScheduler implements OmpSubagentCardScheduler {
-  private currentMs = 0;
-  private nextId = 1;
-  private readonly timers = new Map<number, { dueMs: number; callback: () => void }>();
-
-  now(): number {
-    return this.currentMs;
-  }
-
-  setTimeout(callback: () => void, delayMs: number) {
-    const id = this.nextId;
-    this.nextId += 1;
-    this.timers.set(id, { dueMs: this.currentMs + delayMs, callback });
-    return { token: id };
-  }
-
-  clearTimeout(timer: { token: unknown }): void {
-    if (typeof timer.token === "number") {
-      this.timers.delete(timer.token);
-    }
-  }
-
-  advance(ms: number): void {
-    this.currentMs += ms;
-    const dueTimers = [...this.timers.entries()]
-      .filter(([, timer]) => timer.dueMs <= this.currentMs)
-      .sort((left, right) => left[1].dueMs - right[1].dueMs);
-    for (const [id, timer] of dueTimers) {
-      if (this.timers.delete(id)) {
-        timer.callback();
-      }
-    }
-  }
-}
-
 describe("OmpSubagentCardTracker", () => {
-  test("folds lifecycle and progress into one throttled sub-agent detail", () => {
-    const scheduler = new ManualScheduler();
+  test("keeps the card a launch marker while the child runs", () => {
     const emitted: string[] = [];
-    const tracker = new OmpSubagentCardTracker({
-      scheduler,
-      emitToolCall: (toolCallId) => {
-        emitted.push(toolCallId);
-        return true;
-      },
-    });
-    tracker.handleLifecycle(LIFECYCLE);
+    const emit = (toolCallId: string) => {
+      emitted.push(toolCallId);
+      return true;
+    };
+    const tracker = new OmpSubagentCardTracker();
+    tracker.handleLifecycle(LIFECYCLE, emit);
     for (const payload of PROGRESS) {
-      tracker.handleProgress(payload);
+      tracker.handleProgress(payload, emit);
     }
 
     expect(emitted).toEqual([PARENT_TOOL_CALL_ID]);
-    const detailBeforeTrailing = tracker.detailFor(PARENT_TOOL_CALL_ID, {
-      type: "sub_agent",
-      subAgentType: "task",
-      description: "Task arg description wins",
-      log: "",
-    });
-    expect(detailBeforeTrailing).toEqual({
-      type: "sub_agent",
-      subAgentType: "task",
-      description: "Task arg description wins",
-      childSessionId: SESSION_FILE,
-      log: [
-        "EchoSubagent started",
-        "[bash] echo subagent-hi",
-        "[yield]",
-        "EchoSubagent completed",
-      ].join("\n"),
-    });
-
-    scheduler.advance(500);
-
-    expect(emitted).toEqual([PARENT_TOOL_CALL_ID, PARENT_TOOL_CALL_ID]);
-  });
-
-  test("aggregates batch progress streams into one index-prefixed log", () => {
-    const scheduler = new ManualScheduler();
-    const emitted: string[] = [];
-    const tracker = new OmpSubagentCardTracker({
-      scheduler,
-      emitToolCall: (toolCallId) => {
-        emitted.push(toolCallId);
-        return true;
-      },
-    });
-
-    tracker.handleLifecycle({
-      id: "Explore",
-      agent: "task",
-      description: "Inspect files",
-      status: "started",
-      sessionFile: "/tmp/one.jsonl",
-      parentToolCallId: "task.batch-1",
-      index: 0,
-    });
-    scheduler.advance(600);
-    tracker.handleProgress({
-      index: 5,
-      agent: "task",
-      task: "Run tests",
-      parentToolCallId: "task.batch-1",
-      progress: {
-        id: "Test",
-        status: "running",
-        description: "Run tests",
-        recentTools: [{ tool: "bash", args: "npm test", endMs: 10 }],
-      },
-      sessionFile: "/tmp/two.jsonl",
-    });
-
-    expect(emitted).toEqual(["task.batch-1", "task.batch-1"]);
     expect(
-      tracker.detailFor("task.batch-1", {
+      tracker.detailFor(PARENT_TOOL_CALL_ID, {
         type: "sub_agent",
-        subAgentType: "batch",
-        actions: [],
+        subAgentType: "task",
+        description: "Task arg description wins",
         log: "",
       }),
     ).toEqual({
       type: "sub_agent",
-      subAgentType: "batch",
-      description: "Inspect files",
-      childSessionId: "/tmp/one.jsonl",
-      log: "[1/6] Explore started\n[6/6] [bash] npm test",
-      actions: [],
+      subAgentType: "task",
+      description: "Task arg description wins",
+      childSessionId: SESSION_FILE,
+      log: "",
     });
   });
 
-  test("keeps dirty trailing state available for final detail and cancels it on cleanup", () => {
-    const scheduler = new ManualScheduler();
+  test("re-emits the card when a later event names the child", () => {
     const emitted: string[] = [];
-    const tracker = new OmpSubagentCardTracker({
-      scheduler,
-      emitToolCall: (toolCallId) => {
-        emitted.push(toolCallId);
-        return true;
+    const emit = (toolCallId: string) => {
+      emitted.push(toolCallId);
+      return true;
+    };
+    const tracker = new OmpSubagentCardTracker();
+    tracker.handleLifecycle({ ...LIFECYCLE, description: undefined, sessionFile: undefined }, emit);
+    tracker.handleProgress(PROGRESS[0], emit);
+
+    expect(emitted).toEqual([PARENT_TOOL_CALL_ID, PARENT_TOOL_CALL_ID]);
+    expect(tracker.detailFor(PARENT_TOOL_CALL_ID, { type: "sub_agent", log: "" })).toEqual({
+      type: "sub_agent",
+      childSessionId: SESSION_FILE,
+      log: "",
+    });
+
+    tracker.delete(PARENT_TOOL_CALL_ID);
+    expect(tracker.detailFor(PARENT_TOOL_CALL_ID, { type: "sub_agent", log: "" })).toEqual({
+      type: "sub_agent",
+      log: "",
+    });
+  });
+  test("leaves the card alone when a later child of the same task starts", () => {
+    const emitted: string[] = [];
+    const emit = (toolCallId: string) => {
+      emitted.push(toolCallId);
+      return true;
+    };
+    const tracker = new OmpSubagentCardTracker();
+    tracker.handleLifecycle(LIFECYCLE, emit);
+    tracker.handleLifecycle(
+      {
+        ...LIFECYCLE,
+        id: "Second",
+        index: 1,
+        description: "Second child",
+        sessionFile: "/s.jsonl",
       },
+      emit,
+    );
+
+    expect(emitted).toEqual([PARENT_TOOL_CALL_ID]);
+    expect(tracker.detailFor(PARENT_TOOL_CALL_ID, { type: "sub_agent", log: "" })).toEqual({
+      type: "sub_agent",
+      description: "Run echo in subagent",
+      childSessionId: SESSION_FILE,
+      log: "",
     });
-
-    tracker.handleLifecycle({
-      id: "Explore",
-      agent: "task",
-      description: "Inspect files",
-      status: "started",
-      parentToolCallId: "task-1",
-      index: 0,
-    });
-    scheduler.advance(100);
-    tracker.handleProgress({
-      index: 0,
-      agent: "task",
-      task: "Inspect files",
-      parentToolCallId: "task-1",
-      progress: {
-        id: "Explore",
-        status: "running",
-        recentOutput: ["found target file"],
-      },
-    });
-
-    expect(emitted).toEqual(["task-1"]);
-    expect(
-      tracker.detailFor("task-1", {
-        type: "sub_agent",
-        log: "",
-      }).log,
-    ).toBe("Explore started\nfound target file");
-
-    tracker.delete("task-1");
-    scheduler.advance(500);
-
-    expect(emitted).toEqual(["task-1"]);
-    expect(
-      tracker.detailFor("task-1", {
-        type: "sub_agent",
-        log: "static",
-      }).log,
-    ).toBe("static");
   });
 });
diff --git a/packages/server/src/server/agent/providers/omp/subagent-card-tracker.ts b/packages/server/src/server/agent/providers/omp/subagent-card-tracker.ts
index 7034c4c506..60ad291058 100644
--- a/packages/server/src/server/agent/providers/omp/subagent-card-tracker.ts
+++ b/packages/server/src/server/agent/providers/omp/subagent-card-tracker.ts
@@ -1,361 +1,106 @@
 import type { ToolCallDetail } from "../../agent-sdk-types.js";
 import type { OmpSubagentLifecyclePayload, OmpSubagentProgressPayload } from "./rpc-types.js";
 
-export interface OmpSubagentCardTimer {
-  readonly token: unknown;
-}
-
-export interface OmpSubagentCardScheduler {
-  now(): number;
-  setTimeout(callback: () => void, delayMs: number): OmpSubagentCardTimer;
-  clearTimeout(timer: OmpSubagentCardTimer): void;
-}
-
-export interface OmpSubagentCardTrackerOptions {
-  scheduler?: OmpSubagentCardScheduler;
-  emitToolCall?: (toolCallId: string) => boolean;
-}
-
-interface OmpSubagentLogLine {
-  key: string;
-  text: string;
-}
-
-interface OmpSubagentCardItem {
+interface OmpSubagentCardChild {
   index: number;
   description?: string;
-  agent?: string;
-  status?: "pending" | "running" | "completed" | "failed" | "aborted";
   childSessionId?: string;
-  lines: OmpSubagentLogLine[];
-  lineKeys: Set<string>;
-}
-
-interface OmpSubagentCardState {
-  items: Map<number, OmpSubagentCardItem>;
-  emitToolCall: (toolCallId: string) => boolean;
-  lastEmitMs: number | null;
-  trailingTimer: OmpSubagentCardTimer | null;
-  dirty: boolean;
-}
-
-const MAX_LOG_LINES_PER_ITEM = 200;
-const MAX_LOG_LINE_CHARS = 240;
-const THROTTLE_INTERVAL_MS = 500;
-
-export function createOmpSubagentCardScheduler(): OmpSubagentCardScheduler {
-  return {
-    now: () => Date.now(),
-    setTimeout: (callback, delayMs) => ({ token: setTimeout(callback, delayMs) }),
-    clearTimeout: (timer) => {
-      clearTimeout(timer.token as ReturnType<typeof setTimeout>);
-    },
-  };
 }
 
+/**
+ * Fills a task card's description and child session from OMP's sub-agent events. The card is a
+ * launch marker that names the task's first child; the children's activity belongs to their own
+ * timelines.
+ */
 export class OmpSubagentCardTracker {
-  private readonly scheduler: OmpSubagentCardScheduler;
-  private readonly emitToolCall: (toolCallId: string) => boolean;
-  private readonly states = new Map<string, OmpSubagentCardState>();
-
-  constructor(options: OmpSubagentCardTrackerOptions) {
-    this.scheduler = options.scheduler ?? createOmpSubagentCardScheduler();
-    this.emitToolCall = options.emitToolCall ?? (() => false);
-  }
+  private readonly firstChildren = new Map<string, OmpSubagentCardChild>();
 
   handleLifecycle(
     payload: OmpSubagentLifecyclePayload,
-    emitToolCall: (toolCallId: string) => boolean = this.emitToolCall,
+    emitToolCall: (toolCallId: string) => boolean,
   ): void {
-    const parentToolCallId = readTrimmedString(payload.parentToolCallId);
-    if (!parentToolCallId) {
-      return;
-    }
-    this.stateFor(parentToolCallId).emitToolCall = emitToolCall;
-    const item = this.upsertItem(parentToolCallId, {
-      index: payload.index,
-      agent: payload.agent,
-      description: payload.description,
-      status: payload.status === "started" ? "running" : payload.status,
-      childSessionId: payload.sessionFile,
-    });
-    this.appendLine(
-      item,
-      `lifecycle:${payload.status}:${payload.id}`,
-      `${payload.id} ${payload.status}`,
+    this.update(
+      payload.parentToolCallId,
+      {
+        index: payload.index,
+        description: payload.description,
+        childSessionId: payload.sessionFile,
+      },
+      emitToolCall,
     );
-    this.requestEmit(parentToolCallId);
   }
 
   handleProgress(
     payload: OmpSubagentProgressPayload,
-    emitToolCall: (toolCallId: string) => boolean = this.emitToolCall,
+    emitToolCall: (toolCallId: string) => boolean,
   ): void {
-    const parentToolCallId = readTrimmedString(payload.parentToolCallId);
-    if (!parentToolCallId) {
-      return;
-    }
-    this.stateFor(parentToolCallId).emitToolCall = emitToolCall;
-    const item = this.upsertItem(parentToolCallId, {
-      index: payload.index,
-      agent: payload.agent,
-      description: payload.progress.description,
-      status: payload.progress.status,
-      childSessionId: payload.sessionFile,
-    });
-
-    const currentToolLine = summarizeTool(readRecord(payload.progress.currentTool));
-    if (currentToolLine) {
-      this.appendLine(item, `current:${currentToolLine.key}`, currentToolLine.text);
-    }
-
-    for (const tool of readRecordArray(payload.progress.recentTools)) {
-      const line = summarizeTool(tool);
-      if (line) {
-        this.appendLine(item, `tool:${line.key}`, line.text);
-      }
-    }
-
-    for (const output of readOutputLines(payload.progress.recentOutput)) {
-      this.appendLine(item, `output:${output}`, output);
-    }
-
-    if (payload.progress.status !== "running") {
-      this.appendLine(
-        item,
-        `status:${payload.progress.status}:${payload.progress.id}`,
-        `${payload.progress.id} ${payload.progress.status}`,
-      );
-    }
-
-    this.requestEmit(parentToolCallId);
+    this.update(
+      payload.parentToolCallId,
+      {
+        index: payload.index,
+        description: payload.progress.description,
+        childSessionId: payload.sessionFile,
+      },
+      emitToolCall,
+    );
   }
 
   detailFor(toolCallId: string, baseDetail: ToolCallDetail): ToolCallDetail {
     if (baseDetail.type !== "sub_agent") {
       return baseDetail;
     }
-    const state = this.states.get(toolCallId);
-    if (!state) {
+    const first = this.firstChildren.get(toolCallId);
+    if (!first) {
       return baseDetail;
     }
-    const items = [...state.items.values()].sort((left, right) => left.index - right.index);
-    const firstItem = items[0];
-    if (!firstItem) {
-      return baseDetail;
-    }
-
-    const detail: ToolCallDetail = {
-      type: "sub_agent",
-      ...(baseDetail.subAgentType ? { subAgentType: baseDetail.subAgentType } : {}),
-      ...((baseDetail.description ?? firstItem.description)
-        ? { description: baseDetail.description ?? firstItem.description }
-        : {}),
-      ...((firstItem.childSessionId ?? baseDetail.childSessionId)
-        ? { childSessionId: firstItem.childSessionId ?? baseDetail.childSessionId }
-        : {}),
-      log: buildLog(items, baseDetail.log),
+    const description = baseDetail.description ?? first.description;
+    const childSessionId = first.childSessionId ?? baseDetail.childSessionId;
+    return {
+      ...baseDetail,
+      ...(description ? { description } : {}),
+      ...(childSessionId ? { childSessionId } : {}),
     };
-    return baseDetail.actions ? { ...detail, actions: baseDetail.actions } : detail;
-  }
-
-  flush(toolCallId: string): void {
-    const state = this.states.get(toolCallId);
-    if (!state || !state.dirty) {
-      return;
-    }
-    this.emitNow(toolCallId, state);
   }
 
   delete(toolCallId: string): void {
-    const state = this.states.get(toolCallId);
-    if (state?.trailingTimer) {
-      this.scheduler.clearTimeout(state.trailingTimer);
-    }
-    this.states.delete(toolCallId);
+    this.firstChildren.delete(toolCallId);
   }
 
   clear(): void {
-    for (const toolCallId of this.states.keys()) {
-      this.delete(toolCallId);
-    }
+    this.firstChildren.clear();
   }
 
-  private upsertItem(
-    parentToolCallId: string,
-    input: {
-      index: number;
-      agent?: string;
-      status?: "pending" | "running" | "completed" | "failed" | "aborted";
-      description?: string;
-      childSessionId?: string;
-    },
-  ): OmpSubagentCardItem {
-    const state = this.stateFor(parentToolCallId);
-    const existing = state.items.get(input.index);
-    if (existing) {
-      existing.agent = readTrimmedString(input.agent) ?? existing.agent;
-      existing.status = input.status ?? existing.status;
-      existing.description = readTrimmedString(input.description) ?? existing.description;
-      existing.childSessionId = readTrimmedString(input.childSessionId) ?? existing.childSessionId;
-      return existing;
+  private update(
+    parentToolCallId: string | undefined,
+    input: { index: number; description?: string; childSessionId?: string },
+    emitToolCall: (toolCallId: string) => boolean,
+  ): void {
+    const toolCallId = readTrimmedString(parentToolCallId);
+    if (!toolCallId) {
+      return;
     }
-
-    const item: OmpSubagentCardItem = {
+    const first = this.firstChildren.get(toolCallId);
+    if (first && input.index > first.index) {
+      return;
+    }
+    const existing = first?.index === input.index ? first : undefined;
+    const next: OmpSubagentCardChild = {
       index: input.index,
-      lines: [],
-      lineKeys: new Set<string>(),
-      ...(readTrimmedString(input.agent) ? { agent: readTrimmedString(input.agent) } : {}),
-      ...(input.status ? { status: input.status } : {}),
-      ...(readTrimmedString(input.description)
-        ? { description: readTrimmedString(input.description) }
-        : {}),
-      ...(readTrimmedString(input.childSessionId)
-        ? { childSessionId: readTrimmedString(input.childSessionId) }
-        : {}),
+      description: readTrimmedString(input.description) ?? existing?.description,
+      childSessionId: readTrimmedString(input.childSessionId) ?? existing?.childSessionId,
     };
-    state.items.set(input.index, item);
-    return item;
-  }
-
-  private stateFor(parentToolCallId: string): OmpSubagentCardState {
-    const existing = this.states.get(parentToolCallId);
-    if (existing) {
-      return existing;
-    }
-    const state: OmpSubagentCardState = {
-      items: new Map(),
-      emitToolCall: this.emitToolCall,
-      lastEmitMs: null,
-      trailingTimer: null,
-      dirty: false,
-    };
-    this.states.set(parentToolCallId, state);
-    return state;
-  }
-
-  private appendLine(item: OmpSubagentCardItem, key: string, text: string): void {
-    const normalizedText = normalizeLine(text);
-    if (!normalizedText || item.lineKeys.has(key)) {
+    if (
+      existing &&
+      existing.description === next.description &&
+      existing.childSessionId === next.childSessionId
+    ) {
       return;
     }
-    item.lines.push({ key, text: normalizedText });
-    item.lineKeys.add(key);
-    while (item.lines.length > MAX_LOG_LINES_PER_ITEM) {
-      const removed = item.lines.shift();
-      if (removed) {
-        item.lineKeys.delete(removed.key);
-      }
-    }
+    this.firstChildren.set(toolCallId, next);
+    emitToolCall(toolCallId);
   }
-
-  private requestEmit(toolCallId: string): void {
-    const state = this.stateFor(toolCallId);
-    const now = this.scheduler.now();
-    const elapsedMs = state.lastEmitMs === null ? THROTTLE_INTERVAL_MS : now - state.lastEmitMs;
-    if (elapsedMs >= THROTTLE_INTERVAL_MS) {
-      this.emitNow(toolCallId, state);
-      return;
-    }
-
-    state.dirty = true;
-    if (state.trailingTimer) {
-      return;
-    }
-    state.trailingTimer = this.scheduler.setTimeout(() => {
-      state.trailingTimer = null;
-      if (state.dirty) {
-        this.emitNow(toolCallId, state);
-      }
-    }, THROTTLE_INTERVAL_MS - elapsedMs);
-  }
-
-  private emitNow(toolCallId: string, state: OmpSubagentCardState): void {
-    if (state.trailingTimer) {
-      this.scheduler.clearTimeout(state.trailingTimer);
-      state.trailingTimer = null;
-    }
-    state.dirty = false;
-    state.lastEmitMs = this.scheduler.now();
-    state.emitToolCall(toolCallId);
-  }
-}
-
-function buildLog(items: OmpSubagentCardItem[], fallback: string): string {
-  const itemCount = Math.max(...items.map((item) => item.index)) + 1;
-  const lines = items.flatMap((item) => {
-    const prefix = itemCount > 1 ? `[${item.index + 1}/${itemCount}] ` : "";
-    return item.lines.map((line) => `${prefix}${line.text}`);
-  });
-  return lines.length > 0 ? lines.join("\n") : fallback;
-}
-
-function summarizeTool(tool: Record<string, unknown> | null): OmpSubagentLogLine | null {
-  if (!tool) {
-    return null;
-  }
-  const toolName = readTrimmedString(tool.tool) ?? readTrimmedString(tool.name);
-  if (!toolName) {
-    return null;
-  }
-  const args = readTrimmedString(tool.args) ?? summarizeUnknown(tool.input);
-  const endMs = typeof tool.endMs === "number" ? `:${tool.endMs}` : "";
-  return {
-    key: `${toolName}:${args ?? ""}${endMs}`,
-    text: args ? `[${toolName}] ${args}` : `[${toolName}]`,
-  };
-}
-
-function readOutputLines(value: unknown): string[] {
-  if (!Array.isArray(value)) {
-    return [];
-  }
-  return value.flatMap((item) => {
-    const text =
-      readTrimmedString(item) ??
-      (isRecord(item)
-        ? (readTrimmedString(item.text) ??
-          readTrimmedString(item.output) ??
-          readTrimmedString(item.content))
-        : undefined);
-    return text ? [text] : [];
-  });
-}
-
-function readRecord(value: unknown): Record<string, unknown> | null {
-  return isRecord(value) ? value : null;
-}
-
-function readRecordArray(value: unknown): Record<string, unknown>[] {
-  return Array.isArray(value) ? value.filter(isRecord) : [];
-}
-
-function summarizeUnknown(value: unknown): string | undefined {
-  if (value === undefined || value === null) {
-    return undefined;
-  }
-  if (typeof value === "string") {
-    return readTrimmedString(value);
-  }
-  const json = JSON.stringify(value);
-  return typeof json === "string" ? normalizeLine(json) : undefined;
-}
-
-function normalizeLine(value: string): string | undefined {
-  const normalized = value.trim().replace(/\s+/g, " ");
-  if (!normalized) {
-    return undefined;
-  }
-  if (normalized.length <= MAX_LOG_LINE_CHARS) {
-    return normalized;
-  }
-  return `${normalized.slice(0, MAX_LOG_LINE_CHARS)}...`;
 }
 
 function readTrimmedString(value: unknown): string | undefined {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
diff --git a/packages/server/src/server/agent/providers/omp/tool-call-mapper.test.ts b/packages/server/src/server/agent/providers/omp/tool-call-mapper.test.ts
index ae4c0d0d77..cc13f9001f 100644
--- a/packages/server/src/server/agent/providers/omp/tool-call-mapper.test.ts
+++ b/packages/server/src/server/agent/providers/omp/tool-call-mapper.test.ts
@@ -85,7 +85,7 @@ describe("OMP tool call mapper", () => {
     expect(mapOmpToolDetail(parseToolArgs("todo", { op: "view" }), null)).toBeNull();
   });
 
-  test("uses task result text and transcript path as the best static replay detail", () => {
+  test("takes the child session from the task transcript path", () => {
     expect(
       mapOmpToolDetail(
         parseToolArgs("task", {
@@ -106,7 +106,7 @@ describe("OMP tool call mapper", () => {
       subAgentType: "explore",
       description: "Inspect the target files",
       childSessionId: "/tmp/omp-task-static/Explore.jsonl",
-      log: "done\ntranscript: /tmp/omp-task-static/Explore.jsonl",
+      log: "",
     });
   });
 
diff --git a/packages/server/src/server/agent/providers/omp/tool-call-mapper.ts b/packages/server/src/server/agent/providers/omp/tool-call-mapper.ts
index 86b1ee53ef..500123758a 100644
--- a/packages/server/src/server/agent/providers/omp/tool-call-mapper.ts
+++ b/packages/server/src/server/agent/providers/omp/tool-call-mapper.ts
@@ -179,7 +179,6 @@ const OPAQUE_TEXT_TOOLS = new Set([
 function mapOmpTaskDetail(args: unknown, result: OmpToolResult): ToolCallDetail {
   const argRecord = isRecord(args) ? args : {};
   const firstTask = Array.isArray(argRecord.tasks) ? argRecord.tasks.find(isRecord) : undefined;
-  const resultText = extractTextFromToolResult(result);
   const childSessionId = readChildSessionId(result);
   return {
     type: "sub_agent",
@@ -200,7 +199,8 @@ function mapOmpTaskDetail(args: unknown, result: OmpToolResult): ToolCallDetail
       argRecord.assignment,
     ),
     ...(childSessionId ? { childSessionId } : {}),
-    log: resultText?.trim() ?? "",
+    // COMPAT(subagent-log): remove after 2027-04-30.
+    log: "",
   };
 }
 
diff --git a/packages/server/src/server/agent/providers/opencode-agent.ts b/packages/server/src/server/agent/providers/opencode-agent.ts
index 81288f3e4f..6fef290d91 100644
--- a/packages/server/src/server/agent/providers/opencode-agent.ts
+++ b/packages/server/src/server/agent/providers/opencode-agent.ts
@@ -4846,15 +4846,6 @@ class OpenCodeAgentSession implements AgentSession {
             ...item,
             status: "failed",
             error,
-            detail:
-              item.detail.type === "sub_agent"
-                ? {
-                    ...item.detail,
-                    log: [item.detail.log, error.message]
-                      .filter((entry) => entry.trim().length > 0)
-                      .join("\n"),
-                  }
-                : item.detail,
           },
         },
         turnId,
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.local.e2e.test.ts b/packages/server/src/server/agent/providers/opencode-bridge.local.e2e.test.ts
index 843ef21ebb..749374b29f 100644
--- a/packages/server/src/server/agent/providers/opencode-bridge.local.e2e.test.ts
+++ b/packages/server/src/server/agent/providers/opencode-bridge.local.e2e.test.ts
@@ -455,9 +455,25 @@ test.each([
     let original: Awaited<ReturnType<typeof client.createSession>> | undefined;
     let resumed: Awaited<ReturnType<typeof client.resumeSession>> | undefined;
     try {
+      // Windows invokes the platform binary directly. Installing its wrapper also runs an
+      // unused postinstall binary probe, which has no timeout and can hold the fixture open.
+      const installPackage =
+        process.platform === "win32"
+          ? `${windowsPackage}-${process.arch}@${cliPackage.slice(cliPackage.lastIndexOf("@") + 1)}`
+          : cliPackage;
+      // npm abandons a stalled registry download only after its 5 minute default, past this
+      // test's budget, and the killed install keeps the fixture locked. Retry stalls sooner.
       await execCommand(
         "npm",
-        ["install", "--prefix", root, "--no-audit", "--no-fund", cliPackage],
+        [
+          "install",
+          "--prefix",
+          root,
+          "--no-audit",
+          "--no-fund",
+          "--fetch-timeout=30000",
+          installPackage,
+        ],
         {
           cwd: root,
           timeout: 180_000,
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 1396d1f784..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
@@ -56,6 +56,7 @@ test("bridge preserves tool failure messages and classifies invalid requests as
     getDaemonTcpHost: null,
     serviceProxyPublicBaseUrl: null,
     resolveScriptHealth: null,
+    getGlobalServicePorts: async () => undefined,
     logger,
     emit: () => {},
     publishStatusUpdate: () => {},
@@ -93,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/event-translator.test.ts b/packages/server/src/server/agent/providers/opencode/event-translator.test.ts
index 9ed61fef67..6dc5bd5a2e 100644
--- a/packages/server/src/server/agent/providers/opencode/event-translator.test.ts
+++ b/packages/server/src/server/agent/providers/opencode/event-translator.test.ts
@@ -1,3 +1,4 @@
+import { collectTimelineSnapshot } from "./test-utils/v2-timeline.js";
 import type { SessionMessageAssistant, SessionMessageUser } from "@opencode/client";
 import { V2Timeline } from "./v2/timeline.js";
 import { describe, expect, it } from "vitest";
@@ -1560,7 +1561,7 @@ describe("translateOpenCodeEvent", () => {
 });
 
 describe("OpenCode v2 history reconciliation", () => {
-  it("keeps client message identity on live echoes but omits it from history", () => {
+  it("keeps client message identity on live echoes but omits it from history", async () => {
     const user: SessionMessageUser = {
       id: "native-message",
       type: "user",
@@ -1568,13 +1569,13 @@ describe("OpenCode v2 history reconciliation", () => {
       time: { created: 1 },
       metadata: { paseoClientMessageId: "client-message" },
     };
-    expect(new V2Timeline().messages([user])).toMatchObject([
+    expect(await collectTimelineSnapshot(new V2Timeline(), [user])).toMatchObject([
       { item: { clientMessageId: "client-message", messageId: "native-message" } },
     ]);
-    expect(new V2Timeline(false).messages([user])).toMatchObject([
+    expect(await collectTimelineSnapshot(new V2Timeline(false), [user])).toMatchObject([
       { item: { type: "user_message", messageId: "native-message" } },
     ]);
-    const [event] = new V2Timeline(false).messages([user]);
+    const [event] = await collectTimelineSnapshot(new V2Timeline(false), [user]);
     expect(event && "item" in event && event.item).not.toHaveProperty("clientMessageId");
   });
   function assistant(text: string): SessionMessageAssistant {
@@ -1587,31 +1588,35 @@ describe("OpenCode v2 history reconciliation", () => {
       content: [{ type: "text", text }],
     };
   }
-  it("emits only the missing suffix after reconnect, even if an intermediate snapshot lags", () => {
+  it("emits only the missing suffix after reconnect, even if an intermediate snapshot lags", async () => {
     const timeline = new V2Timeline();
-    const text = (messages: ReturnType<V2Timeline["messages"]>) =>
+    const text = (messages: Awaited<ReturnType<typeof collectTimelineSnapshot>>) =>
       messages.flatMap((event) =>
         event.type === "timeline" && event.item.type === "assistant_message"
           ? [event.item.text]
           : [],
       );
-    expect(text(timeline.messages([assistant("hello")]))).toEqual(["hello"]);
-    expect(timeline.messages([assistant("hel")])).toEqual([]);
-    expect(text(timeline.messages([assistant("hello world")]))).toEqual([" world"]);
-    expect(timeline.messages([assistant("hello world")])).toEqual([]);
+    expect(text(await collectTimelineSnapshot(timeline, [assistant("hello")]))).toEqual(["hello"]);
+    expect(await collectTimelineSnapshot(timeline, [assistant("hel")])).toEqual([]);
+    expect(text(await collectTimelineSnapshot(timeline, [assistant("hello world")]))).toEqual([
+      " world",
+    ]);
+    expect(await collectTimelineSnapshot(timeline, [assistant("hello world")])).toEqual([]);
   });
-  it("keeps reasoning separate from assistant output", () => {
+  it("keeps reasoning separate from assistant output", async () => {
     const timeline = new V2Timeline();
     const message = assistant("answer");
     message.content.unshift({ type: "reasoning", text: "thinking" });
     expect(
-      timeline.messages([message]).map((event) => (event.type === "timeline" ? event.item : null)),
+      (await collectTimelineSnapshot(timeline, [message])).map((event) =>
+        event.type === "timeline" ? event.item : null,
+      ),
     ).toEqual([
       { type: "reasoning", text: "thinking" },
       { type: "assistant_message", text: "answer", messageId: "message" },
     ]);
   });
-  it("emits tool state transitions once and keeps their call identity", () => {
+  it("emits tool state transitions once and keeps their call identity", async () => {
     const timeline = new V2Timeline();
     const message = assistant("");
     message.content = [
@@ -1623,7 +1628,7 @@ describe("OpenCode v2 history reconciliation", () => {
         state: { status: "running", input: { command: "pwd" }, metadata: {} },
       },
     ];
-    expect(timeline.messages([message])).toMatchObject([
+    expect(await collectTimelineSnapshot(timeline, [message])).toMatchObject([
       { item: { type: "tool_call", callId: "call", status: "running" } },
     ]);
     message.content = [
@@ -1639,9 +1644,9 @@ describe("OpenCode v2 history reconciliation", () => {
         },
       },
     ];
-    expect(timeline.messages([message])).toMatchObject([
+    expect(await collectTimelineSnapshot(timeline, [message])).toMatchObject([
       { item: { type: "tool_call", callId: "call", status: "completed" } },
     ]);
-    expect(timeline.messages([message])).toEqual([]);
+    expect(await collectTimelineSnapshot(timeline, [message])).toEqual([]);
   });
 });
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..07f312da0a 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,6 +96,7 @@ 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);
@@ -193,6 +195,7 @@ test.each([
       logger,
       {
         command: { mode: "replace", argv: [process.execPath, script] },
+        env: { XDG_STATE_HOME: root },
       },
       { serverManager: new TrackedServerManager({ logger }) },
     );
@@ -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 features = await client.listFeatures({ provider: "opencode", cwd: "/tmp/project" });
+    expect(features.map((feature) => feature.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..e5fa17021a 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(
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/test-utils/v2-streamed-text-memory.ts b/packages/server/src/server/agent/providers/opencode/test-utils/v2-streamed-text-memory.ts
index d9d254d9de..98cd79526a 100644
--- a/packages/server/src/server/agent/providers/opencode/test-utils/v2-streamed-text-memory.ts
+++ b/packages/server/src/server/agent/providers/opencode/test-utils/v2-streamed-text-memory.ts
@@ -1,3 +1,4 @@
+import { collectTimelineSnapshot } from "./v2-timeline.js";
 import { TimelineProjection } from "../../../timeline-projection.js";
 import { V2Timeline } from "../v2/timeline.js";
 
@@ -21,16 +22,18 @@ for (let index = 0; index < chunks; index++) {
   const event =
     mode === "delta"
       ? timeline.delta({ ...part, delta })
-      : timeline.messages([
-          {
-            id: "answer",
-            type: "assistant",
-            agent: "build",
-            model: { providerID: "test", id: "model" },
-            time: { created: 2 },
-            content: [{ type: "reasoning", text }],
-          },
-        ])[0];
+      : (
+          await collectTimelineSnapshot(timeline, [
+            {
+              id: "answer",
+              type: "assistant",
+              agent: "build",
+              model: { providerID: "test", id: "model" },
+              time: { created: 2 },
+              content: [{ type: "reasoning", text }],
+            },
+          ])
+        )[0];
   if (event?.type !== "timeline") throw new Error("Expected a timeline event");
   projection.append({
     seq: index + 1,
diff --git a/packages/server/src/server/agent/providers/opencode/test-utils/v2-timeline.ts b/packages/server/src/server/agent/providers/opencode/test-utils/v2-timeline.ts
new file mode 100644
index 0000000000..e7aa552479
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/test-utils/v2-timeline.ts
@@ -0,0 +1,15 @@
+import type { SessionMessageInfo } from "@opencode/client";
+import type { AgentStreamEvent } from "../../../agent-sdk-types.js";
+import type { V2Timeline } from "../v2/timeline.js";
+
+// Snapshot assertions without a live stream can collect the publisher's events.
+export async function collectTimelineSnapshot(
+  timeline: V2Timeline,
+  messages: SessionMessageInfo[],
+): Promise<AgentStreamEvent[]> {
+  const events: AgentStreamEvent[] = [];
+  await timeline.messages(messages, (event) => {
+    events.push(event);
+  });
+  return events;
+}
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 8214ebb1d0..b3eb432f86 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
@@ -153,21 +153,6 @@ const OpencodeGrepOutputSchema = z
   ])
   .nullable();
 
-function formatLogEntry(value: unknown): string | undefined {
-  const outputText = readOutputText(value);
-  if (outputText) {
-    return outputText;
-  }
-  if (value === null || value === undefined) {
-    return undefined;
-  }
-  try {
-    return JSON.stringify(value, null, 2);
-  } catch {
-    return String(value);
-  }
-}
-
 function extractOpenCodeTaskSessionId(value: unknown): string | undefined {
   const text = readOutputText(value);
   if (text) {
@@ -195,7 +180,6 @@ function extractOpenCodeTaskSessionId(value: unknown): string | undefined {
 function deriveOpencodeTaskDetail(
   input: unknown,
   output: unknown,
-  error: unknown,
   metadata: Record<string, unknown> | undefined,
 ): ToolCallDetail | null {
   if (!isRecord(input)) {
@@ -208,7 +192,6 @@ function deriveOpencodeTaskDetail(
     return null;
   }
 
-  const log = [formatLogEntry(output), formatLogEntry(error)].filter((entry) => entry).join("\n");
   const childSessionId =
     normalizeSubAgentText(metadata?.sessionId) ?? extractOpenCodeTaskSessionId(output);
   return {
@@ -216,7 +199,8 @@ function deriveOpencodeTaskDetail(
     ...(subAgentType ? { subAgentType } : {}),
     ...(description ? { description } : {}),
     ...(childSessionId ? { childSessionId } : {}),
-    log,
+    // COMPAT(subagent-log): remove after 2027-04-30.
+    log: "",
     actions: [],
   };
 }
@@ -373,11 +357,10 @@ export function deriveOpencodeToolDetail(
   toolName: string,
   input: unknown,
   output: unknown,
-  error: unknown = null,
   metadata?: Record<string, unknown>,
 ): ToolCallDetail {
   if (toolName.trim().toLowerCase() === "task") {
-    const taskDetail = deriveOpencodeTaskDetail(input, output, error, metadata);
+    const taskDetail = deriveOpencodeTaskDetail(input, output, metadata);
     if (taskDetail) {
       return taskDetail;
     }
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 1c9ba212e1..eb38a04ac6 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
@@ -460,7 +460,7 @@ describe("opencode tool-call mapper", () => {
     });
   });
 
-  it("maps completed task calls with final output log to sub_agent detail", () => {
+  it("maps completed task calls to sub_agent detail", () => {
     const item = expectMapped(
       mapOpencodeToolCall({
         toolName: "task",
@@ -480,7 +480,7 @@ describe("opencode tool-call mapper", () => {
       type: "sub_agent",
       subAgentType: "explore",
       description: "Explore agent-tools codebase",
-      log: "Found the CLI entrypoint and provider registry.",
+      log: "",
       actions: [],
     });
   });
@@ -505,12 +505,12 @@ describe("opencode tool-call mapper", () => {
       subAgentType: "explore",
       description: "Explore current directory",
       childSessionId: "ses_2268db431ffe299vL1bbot8R7Z",
-      log: '<task id="ses_2268db431ffe299vL1bbot8R7Z">done</task>',
+      log: "",
       actions: [],
     });
   });
 
-  it("maps aborted task calls with preserved error log to sub_agent detail", () => {
+  it("maps aborted task calls to sub_agent detail", () => {
     const item = expectMapped(
       mapOpencodeToolCall({
         toolName: "task",
@@ -531,7 +531,7 @@ describe("opencode tool-call mapper", () => {
       type: "sub_agent",
       subAgentType: "explore",
       description: "Explore agent-tools codebase",
-      log: "Tool execution aborted",
+      log: "",
       actions: [],
     });
   });
diff --git a/packages/server/src/server/agent/providers/opencode/tool-call-mapper.ts b/packages/server/src/server/agent/providers/opencode/tool-call-mapper.ts
index 8fbc861a84..261a4ec827 100644
--- a/packages/server/src/server/agent/providers/opencode/tool-call-mapper.ts
+++ b/packages/server/src/server/agent/providers/opencode/tool-call-mapper.ts
@@ -43,7 +43,7 @@ export function mapOpencodeToolCall(params: OpencodeToolCallParams): ToolCallTim
   const error = raw.error ?? null;
   const rawStatus = typeof raw.status === "string" ? raw.status : undefined;
   const status = normalizeToolCallStatus(rawStatus, error, output);
-  const detail = deriveOpencodeToolDetail(name, input, output, error, raw.metadata);
+  const detail = deriveOpencodeToolDetail(name, input, output, raw.metadata);
 
   if (status === "failed") {
     return {
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..6e1a45409c 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,26 @@ 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("completes from execution events without a long-lived HTTP wait", async () => {
     const harness = new V2Harness();
     harness.prompt = async (input) => {
@@ -1181,3 +1201,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..119fa0ade7 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/agent.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/agent.ts
@@ -8,7 +8,7 @@ import {
 } 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";
 
@@ -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] })
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/children.ts b/packages/server/src/server/agent/providers/opencode/v2/children.ts
index 8c2e0ec312..08af88dcb0 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/children.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/children.ts
@@ -92,13 +92,13 @@ export class SessionChildren {
       this.childStates.set(info.id, signature);
       this.options.emit({ type: "provider_subagent", provider: "opencode", event: presentation });
     }
-    for (const event of timeline.messages(await messages(this.options.client(), info.id))) {
+    await timeline.messages(await messages(this.options.client(), info.id), (event) => {
       if (event.type === "timeline")
         this.options.emit({
           type: "provider_subagent",
           provider: "opencode",
           event: { type: "timeline", id: info.id, item: event.item, timestamp: event.timestamp },
         });
-    }
+    });
   }
 }
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..ec77052cb5 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);
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 9358a14040..58981c7086 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,4 @@
+import { OpenCodeBackgroundInventory } from "./background-inventory.js";
 import { SessionChildren } from "./children.js";
 import { SessionTurns } from "./turns.js";
 import { V2Timeline } from "./timeline.js";
@@ -57,6 +58,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,
@@ -70,6 +72,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,
@@ -100,7 +112,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({
@@ -131,7 +147,7 @@ export class OpenCodeV2Session implements AgentSession {
     await this.configureConnection();
     const location = { directory: this.config.cwd };
     this.modes = modesFromV2((await this.client.agent.list({ location })).data);
-    this.timeline.messages(await messages(this.client, this.id));
+    await this.timeline.messages(await messages(this.client, this.id), () => {});
     await this.startStream();
     await this.children.reconcile(this.id);
   }
@@ -139,6 +155,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;
@@ -146,6 +163,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 });
@@ -207,6 +225,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();
@@ -232,6 +255,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);
     };
@@ -261,7 +290,11 @@ export class OpenCodeV2Session implements AgentSession {
   async *streamHistory() {
     await this.reconnectIfExited();
     const history = new V2Timeline(false);
-    yield* history.messages(await messages(this.client, this.id));
+    const events: AgentStreamEvent[] = [];
+    await history.messages(await messages(this.client, this.id), (event) => {
+      events.push(event);
+    });
+    yield* events;
   }
   async getRuntimeInfo() {
     await this.reconnectIfExited();
@@ -382,11 +415,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();
   }
@@ -417,7 +454,7 @@ export class OpenCodeV2Session implements AgentSession {
     ]);
     this.info = info;
     this.history = history;
-    for (const event of this.timeline.messages(history)) this.emitTimeline(event);
+    await this.timeline.messages(history, (event) => this.emitTimeline(event));
     await this.permissions.reconcile(this.id);
   }
   private async reconcile() {
@@ -432,6 +469,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)
@@ -495,9 +533,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);
         }
@@ -513,6 +554,7 @@ export class OpenCodeV2Session implements AgentSession {
           "OpenCode event stream interrupted; reconciling on reconnect",
         );
       }
+      this.background.disconnect();
       await delay(100, undefined, { signal }).catch(() => undefined);
     }
   }
@@ -553,9 +595,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/opencode/v2/streaming.test.ts b/packages/server/src/server/agent/providers/opencode/v2/streaming.test.ts
index aa74faa6cf..b8c118f037 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/streaming.test.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/streaming.test.ts
@@ -1,3 +1,4 @@
+import { collectTimelineSnapshot } from "../test-utils/v2-timeline.js";
 import { V2Timeline } from "./timeline.js";
 import type { SessionMessageAssistant } from "@opencode/client";
 import { describe, expect, test } from "vitest";
@@ -80,7 +81,7 @@ describe("OpenCode v2 token streaming", () => {
     }
   });
 
-  test("deduplicates snapshots before and after deltas using per-type ordinals", () => {
+  test("deduplicates snapshots before and after deltas using per-type ordinals", async () => {
     const timeline = new V2Timeline();
     const text = { assistantMessageID: "answer", type: "text", ordinal: 0 } as const;
     const reasoning = { ...text, type: "reasoning" } as const;
@@ -99,24 +100,28 @@ describe("OpenCode v2 token streaming", () => {
       },
       { type: "text", text: "Hello" },
     ]);
-    expect(timeline.messages([snapshot])).toMatchObject([{ item: { text: "lo" } }]);
+    expect(await collectTimelineSnapshot(timeline, [snapshot])).toMatchObject([
+      { item: { text: "lo" } },
+    ]);
     expect(timeline.delta({ ...text, delta: "lo" })).toBeNull();
-    expect(timeline.messages([snapshot])).toEqual([]);
+    expect(await collectTimelineSnapshot(timeline, [snapshot])).toEqual([]);
     expect(timeline.delta({ ...text, delta: "!" })).toMatchObject({ item: { text: "!" } });
-    expect(timeline.messages([snapshot])).toEqual([]);
+    expect(await collectTimelineSnapshot(timeline, [snapshot])).toEqual([]);
   });
 
-  test("recovers missed fragments from snapshots after reconnect", () => {
+  test("recovers missed fragments from snapshots after reconnect", async () => {
     const timeline = new V2Timeline();
     const part = { assistantMessageID: "answer", type: "text", ordinal: 0 } as const;
     timeline.startPart(part);
     expect(timeline.delta({ ...part, delta: "Hel" })).toMatchObject({ item: { text: "Hel" } });
     timeline.resetStreams();
     expect(timeline.delta({ ...part, delta: "!" })).toBeNull();
-    expect(timeline.messages([assistant([{ type: "text", text: "Hello!" }])])).toMatchObject([
-      { item: { text: "lo!" } },
-    ]);
-    expect(timeline.messages([assistant([{ type: "text", text: "Hello!" }])])).toEqual([]);
+    expect(
+      await collectTimelineSnapshot(timeline, [assistant([{ type: "text", text: "Hello!" }])]),
+    ).toMatchObject([{ item: { text: "lo!" } }]);
+    expect(
+      await collectTimelineSnapshot(timeline, [assistant([{ type: "text", text: "Hello!" }])]),
+    ).toEqual([]);
   });
 
   test("withholds streamed prose during a structured-output turn", async () => {
@@ -203,3 +208,62 @@ describe("OpenCode v2 token streaming", () => {
     }
   });
 });
+
+test.each(["text", "reasoning"] as const)(
+  "publishes snapshot %s before a live suffix during image materialization",
+  async (type) => {
+    const timeline = new V2Timeline();
+    const part = { assistantMessageID: "answer", type, ordinal: 0 };
+    timeline.startPart(part);
+    const emitted: AgentStreamEvent[] = [];
+    let settled = false;
+    const snapshot = timeline
+      .messages(
+        [
+          assistant([
+            { type, text: "Hello" },
+            {
+              type: "tool",
+              id: "screenshot",
+              name: "paseo_browser_screenshot",
+              executed: false,
+              state: {
+                status: "completed",
+                input: {},
+                content: [
+                  { type: "file", uri: "data:image/png;base64,aGVsbG8=", mime: "image/png" },
+                ],
+                metadata: {},
+              },
+              time: { created: 2, ran: 2, completed: 2 },
+            },
+          ]),
+        ],
+        (event) => {
+          emitted.push(event);
+        },
+      )
+      .then(() => {
+        settled = true;
+        return undefined;
+      });
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    expect(settled).toBe(false);
+    const delta = timeline.delta({ ...part, delta: "Hello world" });
+    if (delta) emitted.push(delta);
+    await snapshot;
+    const text = emitted.flatMap((event) => {
+      if (event.type !== "timeline") return [];
+      if (
+        type === "text" &&
+        event.item.type === "assistant_message" &&
+        !event.item.text.includes("![Image]")
+      )
+        return [event.item.text];
+      if (type === "reasoning" && event.item.type === "reasoning") return [event.item.text];
+      return [];
+    });
+    expect(text).toEqual(["Hello", " world"]);
+    expect(text.join("")).toBe("Hello world");
+  },
+);
diff --git a/packages/server/src/server/agent/providers/opencode/v2/timeline.test.ts b/packages/server/src/server/agent/providers/opencode/v2/timeline.test.ts
index d86b9a7dcb..6e9b886c09 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/timeline.test.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/timeline.test.ts
@@ -1,3 +1,4 @@
+import { collectTimelineSnapshot } from "../test-utils/v2-timeline.js";
 import type { SessionMessageAssistant } from "@opencode/client";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -15,7 +16,7 @@ function assistant(content: SessionMessageAssistant["content"]): SessionMessageA
   };
 }
 
-test("a completed edit carries the replaced and replacement text", () => {
+test("a completed edit carries the replaced and replacement text", async () => {
   // Captured from OpenCode 2.0.18, whose edit tool takes `path` instead of `filePath`.
   const edit = assistant([
     {
@@ -45,7 +46,7 @@ test("a completed edit carries the replaced and replacement text", () => {
     },
   ]);
 
-  expect(new V2Timeline().messages([edit])).toMatchObject([
+  expect(await collectTimelineSnapshot(new V2Timeline(), [edit])).toMatchObject([
     {
       item: {
         type: "tool_call",
@@ -57,7 +58,7 @@ test("a completed edit carries the replaced and replacement text", () => {
   ]);
 });
 
-test("a tool's image output is shown as an image, not as base64 in the tool output", () => {
+test("a tool's image output is shown as an image, not as base64 in the tool output", async () => {
   const png =
     "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==";
   const screenshot = assistant([
@@ -80,7 +81,7 @@ test("a tool's image output is shown as an image, not as base64 in the tool outp
   ]);
   const timeline = new V2Timeline();
 
-  const events = timeline.messages([screenshot]);
+  const events = await collectTimelineSnapshot(timeline, [screenshot]);
 
   expect(JSON.stringify(events)).not.toContain(png);
   expect(events.map((event) => event.type === "timeline" && event.item)).toMatchObject([
@@ -95,7 +96,7 @@ test("a tool's image output is shown as an image, not as base64 in the tool outp
       text: expect.stringMatching(/^\n\n!\[Image\]\(file:\/\/.*paseo-attachments.*\.png\)\n\n$/),
     },
   ]);
-  expect(timeline.messages([screenshot])).toEqual([]);
+  expect(await collectTimelineSnapshot(timeline, [screenshot])).toEqual([]);
 });
 
 test("a surrogate pair split across deltas streams back intact", () => {
diff --git a/packages/server/src/server/agent/providers/opencode/v2/timeline.ts b/packages/server/src/server/agent/providers/opencode/v2/timeline.ts
index 0fdd6f9f40..5596443bbb 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/timeline.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/timeline.ts
@@ -55,18 +55,32 @@ export class V2Timeline {
     return { type: "timeline", provider: "opencode", item, timestamp: new Date().toISOString() };
   }
 
-  messages(messages: SessionMessageInfo[]): AgentStreamEvent[] {
-    const events: AgentStreamEvent[] = [];
+  private pendingMessages: Promise<unknown> = Promise.resolve();
+
+  // Publish each cursor advance in the same synchronous step. Buffering snapshot
+  // events until image IO finishes lets live deltas overtake already committed text.
+  messages(
+    messages: SessionMessageInfo[],
+    publish: (event: AgentStreamEvent) => void,
+  ): Promise<void> {
+    const result = this.pendingMessages.then(() => this.publishMessages(messages, publish));
+    this.pendingMessages = result.catch(() => {});
+    return result;
+  }
+
+  private async publishMessages(
+    messages: SessionMessageInfo[],
+    publish: (event: AgentStreamEvent) => void,
+  ): Promise<void> {
     const state: TimelineState = { structured: false, accepted: false };
     for (const message of messages) {
       const timestamp = new Date(message.time.created).toISOString();
       const push = (item: AgentTimelineItem) =>
-        events.push({ type: "timeline", provider: "opencode", item, timestamp });
+        publish({ type: "timeline", provider: "opencode", item, timestamp });
       if (message.type === "user") this.userMessage(message, state, push);
-      else if (message.type === "assistant") this.assistantMessage(message, state, push);
+      else if (message.type === "assistant") await this.assistantMessage(message, state, push);
       else if (message.type === "compaction") this.compactionMessage(message, push);
     }
-    return events;
   }
 
   private userMessage(
@@ -89,7 +103,7 @@ export class V2Timeline {
     });
   }
 
-  private assistantMessage(
+  private async assistantMessage(
     message: Extract<SessionMessageInfo, { type: "assistant" }>,
     state: TimelineState,
     push: (item: AgentTimelineItem) => void,
@@ -99,16 +113,16 @@ export class V2Timeline {
     // paths address the same cursor entry.
     let textOrdinal = 0;
     let reasoningOrdinal = 0;
-    message.content.forEach((part, partIndex) => {
+    for (const [partIndex, part] of message.content.entries()) {
       if (part.type === "tool" && part.name === STRUCTURED_OUTPUT_TOOL) {
         this.structuredOutputPart(message.id, partIndex, part, state, push);
       } else if (part.type === "text" || part.type === "reasoning") {
         const ordinal = part.type === "text" ? textOrdinal++ : reasoningOrdinal++;
         this.textPart(message.id, part, ordinal, state, push);
       } else {
-        this.toolPart(message.id, partIndex, part, push);
+        await this.toolPart(message.id, partIndex, part, push);
       }
-    });
+    }
   }
 
   private structuredOutputPart(
@@ -156,7 +170,7 @@ export class V2Timeline {
     else push({ type: "reasoning", text: suffix });
   }
 
-  private toolPart(
+  private async toolPart(
     messageID: string,
     partIndex: number,
     part: Extract<
@@ -174,16 +188,16 @@ export class V2Timeline {
     if (item) push(item);
     // Images follow their tool call as markdown, as Claude and Codex emit them,
     // so base64 never reaches the tool output.
-    images.forEach((image, index) => {
+    for (const [index, image] of images.entries()) {
       const imageKey = `${key}:image:${index}`;
-      if (this.content.has(imageKey)) return;
+      if (this.content.has(imageKey)) continue;
       this.content.set(imageKey, "");
-      const imageItem = renderProviderImageOutputAsAssistantMarkdown(
+      const imageItem = await renderProviderImageOutputAsAssistantMarkdown(
         { url: image.uri, mimeType: image.mime },
         { materialize: materializeProviderImage },
       );
       if (imageItem) push(imageItem);
-    });
+    }
   }
 
   private compactionMessage(
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 b9f31b61b2..9ca6c821b8 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(
@@ -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(
@@ -3583,3 +4021,174 @@ test("pi runtime safety protects queued replies and runtime-owned activity", asy
   native.getStateError = new Error("Unable to prove idle");
   await expect(session.canStopRuntime!()).rejects.toThrow("Unable to prove idle");
 });
+
+test("reserves the Pi turn while an image prompt is materialized", async () => {
+  const { pi, session } = await createSession();
+  onTestFinished(() => session.close());
+  const first = session.startTurn([
+    { type: "image", data: ONE_BY_ONE_PNG_BASE64, mimeType: "image/png" },
+  ]);
+  await expect(session.startTurn("overlapping prompt")).rejects.toThrow("already active");
+  await first;
+  expect(pi.latestSession().prompts).toHaveLength(1);
+});
+
+test("interrupting Pi during image conversion cancels the admitted turn and permits a follow-up", async () => {
+  const { pi, session } = await createSession();
+  onTestFinished(() => session.close());
+  const events: AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  let admitted = false;
+  const first = session
+    .startTurn([
+      {
+        type: "image",
+        data: Buffer.alloc(16 * 1024 * 1024, 51).toString("base64"),
+        mimeType: "image/png",
+      },
+    ])
+    .then((result) => {
+      admitted = true;
+      return result;
+    });
+  await waitForImmediate();
+  expect(admitted).toBe(false);
+  expect(pi.latestSession().prompts).toHaveLength(0);
+  await session.interrupt();
+  const followup = await session.startTurn("follow-up after image interrupt");
+  const original = await first;
+  expect(events).toContainEqual(
+    expect.objectContaining({ type: "turn_canceled", turnId: original.turnId }),
+  );
+  expect(followup.turnId).not.toBe(original.turnId);
+  expect(pi.latestSession().prompts).toEqual([
+    { message: "follow-up after image interrupt", imageCount: 0 },
+  ]);
+});
+
+test("closing Pi during image conversion rejects its pending start", async () => {
+  const { pi, session } = await createSession();
+  const first = session.startTurn([
+    {
+      type: "image",
+      data: Buffer.alloc(16 * 1024 * 1024, 52).toString("base64"),
+      mimeType: "image/png",
+    },
+  ]);
+  const rejected = expect(first).rejects.toThrow("closed");
+  await waitForImmediate();
+  expect(pi.latestSession().prompts).toHaveLength(0);
+  await session.close();
+  await rejected;
+});
+
+describe("Pi tool-result images", () => {
+  test.each([false, true])(
+    "tool-result images precede the reply and completion (isError=%s)",
+    async (isError) => {
+      const { pi, session, events } = await createSession();
+      onTestFinished(() => session.close());
+      const fakeSession = pi.latestSession();
+      await session.startTurn("run");
+      fakeSession.emit({
+        type: "tool_execution_start",
+        toolCallId: "shot-1",
+        toolName: "screenshot",
+        args: {},
+      });
+      fakeSession.emit({
+        type: "tool_execution_end",
+        toolCallId: "shot-1",
+        toolName: "screenshot",
+        result: {
+          content: [
+            { type: "text", text: "captured" },
+            { type: "image", data: Buffer.from("hello").toString("base64"), mimeType: "image/png" },
+          ],
+          structuredContent: {
+            type: "image",
+            data: Buffer.from("hello").toString("base64"),
+            mimeType: "image/png",
+            note: "captured",
+          },
+        },
+        isError,
+      });
+      fakeSession.emit({
+        type: "message_update",
+        assistantMessageEvent: { type: "text_delta", delta: "Image read complete." },
+      });
+      fakeSession.finishTurn();
+      await events.nextTurnCompletion();
+
+      const items = events.timelineItems();
+      const toolIndex = items.findIndex(
+        (item) =>
+          item.type === "tool_call" &&
+          item.callId === "shot-1" &&
+          item.status === (isError ? "failed" : "completed"),
+      );
+      expect(toolIndex).toBeGreaterThanOrEqual(0);
+      // Base64 must never reach the tool output stringifier.
+      expect(JSON.stringify(items[toolIndex])).not.toContain(
+        Buffer.from("hello").toString("base64"),
+      );
+      expect(items.slice(toolIndex + 1)).toEqual([
+        expect.objectContaining({
+          type: "assistant_message",
+          text: expect.stringContaining("![Image]("),
+        }),
+        expect.objectContaining({ type: "assistant_message", text: "Image read complete." }),
+      ]);
+      expect(events.timelineAndCompletionEvents().at(-1)).toEqual({ type: "turn_completed" });
+    },
+  );
+});
+
+test("Pi image rendering preserves turn ownership across an interrupt and follow-up", async () => {
+  const { pi, session, events } = await createSession();
+  onTestFinished(() => session.close());
+  const emitted: AgentStreamEvent[] = [];
+  session.subscribe((event) => emitted.push(event));
+  const native = pi.latestSession();
+  const first = await session.startTurn("read image");
+  native.emit({
+    type: "tool_execution_end",
+    toolCallId: "large-image",
+    toolName: "screenshot",
+    result: {
+      content: [
+        {
+          type: "image",
+          data: Buffer.alloc(8 * 1024 * 1024, 73).toString("base64"),
+          mimeType: "image/png",
+        },
+      ],
+    },
+    isError: false,
+  });
+  native.finishTurn();
+  await session.interrupt();
+  const followup = await session.startTurn("follow-up after image");
+  await waitForImmediate();
+  await waitForImmediate();
+  await expect
+    .poll(() =>
+      events
+        .timelineItems()
+        .some((item) => item.type === "assistant_message" && item.text.includes("![Image](")),
+    )
+    .toBe(true);
+  expect(events.turnCompletedEvents().some((event) => event.turnId === followup.turnId)).toBe(
+    false,
+  );
+  const imageEvent = emitted.find(
+    (event) =>
+      event.type === "timeline" &&
+      event.item.type === "assistant_message" &&
+      event.item.text.includes("![Image]("),
+  );
+  expect(imageEvent).toMatchObject({ turnId: first.turnId });
+  native.finishTurn();
+  await events.nextTurnCompletion();
+});
diff --git a/packages/server/src/server/agent/providers/pi/agent.ts b/packages/server/src/server/agent/providers/pi/agent.ts
index 881f8cbb29..513f9b62e9 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";
@@ -22,6 +22,7 @@ import {
   type AgentPersistenceHandle,
   type AgentPromptInput,
   type AgentProvider,
+  type AgentResumeSessionOptions,
   type AgentRunOptions,
   type AgentRunResult,
   type AgentRuntimeInfo,
@@ -64,15 +65,24 @@ import {
   streamPiHistory,
   type PiCapturedUserMessageEntry,
 } from "./history-mapper.js";
-import { materializeProviderImage } from "../provider-image-output.js";
+import {
+  materializeProviderImage,
+  renderProviderImageOutputAsAssistantMarkdown,
+  type ProviderImageOutput,
+} from "../provider-image-output.js";
 import { PiCliRuntime } from "./cli-runtime.js";
 import {
   createPiExtensionHost,
   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,
@@ -89,6 +99,7 @@ import {
   mapToolDetail,
   parseToolArgs,
   parseToolResult,
+  splitPiToolResultImages,
   type PiToolResult,
   type PiTrackedToolCall,
 } from "./tool-call-mapper.js";
@@ -240,7 +251,9 @@ interface PiRpcAgentSessionOptions {
   initialState: PiSessionState;
   capabilities: AgentCapabilityFlags;
   currentModeId?: string | null;
+  persistedSessionFile?: string;
   cleanup?: () => void;
+  closeAfterHistory?: boolean;
   extensionTimeoutMs?: number;
   logger: Logger;
   usagePollScheduler?: PiUsagePollScheduler;
@@ -367,9 +380,9 @@ function piModelSupportsImageInput(model: PiModel | null | undefined): boolean {
   return model?.input?.includes("image") === true;
 }
 
-function renderTextOnlyImageHint(image: { data: string; mimeType: string }): string {
+async function renderTextOnlyImageHint(image: { data: string; mimeType: string }): Promise<string> {
   try {
-    const materialized = materializeProviderImage({
+    const materialized = await materializeProviderImage({
       data: image.data,
       mimeType: image.mimeType,
     });
@@ -379,10 +392,10 @@ function renderTextOnlyImageHint(image: { data: string; mimeType: string }): str
   }
 }
 
-function convertPromptInput(
+async function convertPromptInput(
   prompt: AgentPromptInput,
   options: { model: PiModel | null | undefined },
-): PiPromptPayload {
+): Promise<PiPromptPayload> {
   if (typeof prompt === "string") {
     return { text: prompt };
   }
@@ -405,7 +418,7 @@ function convertPromptInput(
           mimeType: block.mimeType,
         });
       } else {
-        textParts.push(renderTextOnlyImageHint(block));
+        textParts.push(await renderTextOnlyImageHint(block));
       }
       continue;
     }
@@ -487,13 +500,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,
@@ -613,6 +627,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 = {},
@@ -661,8 +688,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",
 	  );
@@ -1186,7 +1211,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;
@@ -1199,8 +1223,10 @@ 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;
   // Pi publishes the terminal before acknowledging abort. Autonomous runs have no
   // turn ID; retain their errors too until the cancellation request settles.
   private interruptingTurn: { turnId: string | undefined; error: string | null } | null = null;
@@ -1226,7 +1252,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);
@@ -1256,7 +1284,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 {
@@ -1276,11 +1306,13 @@ 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");
     }
 
-    const payload = convertPromptInput(prompt, { model: this.state.model });
     const turnId = randomUUID();
     this.activeTurnId = turnId;
     this.usagePoller.startTurn();
@@ -1292,6 +1324,9 @@ export class PiRpcAgentSession implements AgentSession {
     this.activePromptRequestId = null;
     this.pendingSteerSubmissions.length = 0;
     this.clearNoTurnBuffers();
+    const payload = await convertPromptInput(prompt, { model: this.state.model });
+    if (this.closed) throw new Error("Pi session is closed");
+    if (this.activeTurnId !== turnId) return { turnId };
     this.activeNoTurnPromptText = payload.text;
     const shouldProbeForNoTurnPrompt = this.parseSlashCommandInput(payload.text) !== null;
 
@@ -1363,7 +1398,9 @@ export class PiRpcAgentSession implements AgentSession {
     if (this.closed || this.activeTurnId !== options.expectedTurnId) {
       return { status: "unavailable" };
     }
-    const payload = convertPromptInput(prompt, { model: this.state.model });
+    const payload = await convertPromptInput(prompt, { model: this.state.model });
+    if (this.closed || this.activeTurnId !== options.expectedTurnId)
+      return { status: "unavailable" };
     // Pi rejects steer RPCs that are extension commands, so slash inputs keep the
     // interrupt-and-replace fallback where they can run directly.
     if (this.parseSlashCommandInput(payload.text)) {
@@ -1421,16 +1458,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> {
@@ -1486,7 +1528,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 } : {}),
@@ -1598,6 +1640,7 @@ export class PiRpcAgentSession implements AgentSession {
       this.pendingExtensionUiRequests.size ||
       this.pendingExtensionResults.size ||
       this.pendingExtensionHydrations.size ||
+      this.pendingOutput ||
       this.pendingSteerSubmissions.length ||
       this.pendingNoTurnOutputs.length ||
       this.interruptingTurn
@@ -1618,7 +1661,7 @@ export class PiRpcAgentSession implements AgentSession {
     try {
       await this.runtimeSession.close();
     } finally {
-      await Promise.all(this.pendingExtensionHydrations);
+      await Promise.all([this.pendingOutput, ...this.pendingExtensionHydrations]);
       this.rejectAllExtensionResults(new Error("Pi session closed"));
       this.cleanup?.();
     }
@@ -1682,9 +1725,31 @@ export class PiRpcAgentSession implements AgentSession {
   }
 
   private emit(event: AgentStreamEvent): void {
-    for (const subscriber of this.subscribers) {
-      subscriber(event);
+    if (this.pendingOutput) {
+      this.emitAsync(() => Promise.resolve([event]));
+      return;
     }
+    this.publish(event);
+  }
+
+  private publish(event: AgentStreamEvent): void {
+    for (const subscriber of this.subscribers) subscriber(event);
+  }
+
+  // Keep timeline order while images are materialized, without delaying provider state changes.
+  private emitAsync(render: () => Promise<AgentStreamEvent[]>): void {
+    const pending = (this.pendingOutput ?? Promise.resolve())
+      .then(render)
+      .then((events) => {
+        if (!this.closed) for (const event of events) this.publish(event);
+        return undefined;
+      })
+      .catch((error) => this.logger.error({ err: error }, "Pi output rendering failed"));
+    this.pendingOutput = pending;
+    void pending.then(() => {
+      if (this.pendingOutput === pending) this.pendingOutput = null;
+      return undefined;
+    });
   }
 
   private emitExtensionOutput(output: PiExtensionEventOutput | undefined, turnId?: string): void {
@@ -1954,13 +2019,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);
     }
   }
@@ -1997,10 +2058,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);
     }
@@ -2136,6 +2194,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) {
@@ -2311,8 +2370,11 @@ export class PiRpcAgentSession implements AgentSession {
       this.activeToolCalls.get(event.toolCallId) ?? parseToolArgs(event.toolName, null);
     this.activeToolCalls.delete(event.toolCallId);
 
-    const result = parseToolResult(event.result);
-    const error = event.isError ? event.result : null;
+    // Pull image blocks out of the result so base64 never reaches the tool output, then render
+    // each one as an assistant_message markdown image after the tool_call (mirroring the Claude
+    // provider, upstream #1717).
+    const { images, result } = splitPiToolResultImages(parseToolResult(event.result));
+    const error = event.isError ? result : null;
     const status = event.isError ? "failed" : "completed";
     this.extensionHost.onToolEnd({
       callId: event.toolCallId,
@@ -2322,6 +2384,30 @@ export class PiRpcAgentSession implements AgentSession {
       result,
     });
     this.emitToolCallEvent(event.toolCallId, toolCall, status, result, error);
+    if (images.length === 0) return;
+    const turnId = this.currentTurnIdForEvent();
+    this.emitAsync(() => this.renderToolResultImages(images, turnId));
+  }
+
+  private async renderToolResultImages(
+    images: ProviderImageOutput[],
+    turnId: string | undefined,
+  ): Promise<AgentStreamEvent[]> {
+    const events: AgentStreamEvent[] = [];
+    for (const image of images) {
+      const imageItem = await renderProviderImageOutputAsAssistantMarkdown(image, {
+        materialize: materializeProviderImage,
+      });
+      if (imageItem && !this.closed) {
+        events.push({
+          type: "timeline",
+          provider: this.provider,
+          turnId,
+          item: imageItem,
+        });
+      }
+    }
+    return events;
   }
 
   private emitCompactionTimeline(input: {
@@ -2585,6 +2671,7 @@ export class PiRpcAgentClient implements AgentClient {
     handle: AgentPersistenceHandle,
     overrides?: Partial<AgentSessionConfig>,
     launchContext?: AgentLaunchContext,
+    options?: AgentResumeSessionOptions,
   ): Promise<AgentSession> {
     const sessionFile = handle.nativeHandle;
     if (!sessionFile) {
@@ -2593,6 +2680,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 ?? {},
@@ -2603,7 +2691,7 @@ export class PiRpcAgentClient implements AgentClient {
       ...launchContext?.env,
     };
     const mcp = await this.prepareMcpInjection(
-      resumeConfig.cwd,
+      processCwd,
       resumeConfig.config.mcpServers,
       mcpEnv,
       runtime,
@@ -2616,20 +2704,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 {
@@ -2642,15 +2739,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;
     }
   }
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/child-session.ts b/packages/server/src/server/agent/providers/pi/extensions/child-session.ts
index 2013b831be..0c7c7df9aa 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/child-session.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/child-session.ts
@@ -21,11 +21,11 @@ export function mapPiChildSession(
   return new PiChildSessionFollower(id, file, maxBytes).readNew();
 }
 
-function mapChildLine(
+async function mapChildLine(
   mapper: PiHistoryMapper,
   id: string,
   line: string,
-): ProviderSubagentInputEvent[] {
+): Promise<ProviderSubagentInputEvent[]> {
   let entry: { message?: PiAgentMessage; timestamp?: string };
   try {
     entry = JSON.parse(line);
@@ -33,7 +33,7 @@ function mapChildLine(
     return [];
   }
   if (!entry.message || typeof entry.message !== "object" || !("role" in entry.message)) return [];
-  return mapper.mapMessages([entry.message]).flatMap((mapped) =>
+  return (await mapper.mapMessages([entry.message])).flatMap((mapped) =>
     mapped.type === "timeline"
       ? [
           {
@@ -83,7 +83,10 @@ export class PiChildSessionFollower {
         const events: ProviderSubagentInputEvent[] = [];
         for (const line of data.subarray(0, lastNewline).toString("utf8").split("\n")) {
           if (this.items >= MAX_ITEMS) break;
-          const mapped = mapChildLine(this.mapper, this.id, line).slice(0, MAX_ITEMS - this.items);
+          const mapped = (await mapChildLine(this.mapper, this.id, line)).slice(
+            0,
+            MAX_ITEMS - this.items,
+          );
           this.items += mapped.length;
           events.push(...mapped);
         }
diff --git a/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/background-child-session.jsonl b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/background-child-session.jsonl
new file mode 100644
index 0000000000..ed668e807f
--- /dev/null
+++ b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/background-child-session.jsonl
@@ -0,0 +1,8 @@
+{"type": "session", "version": 3, "id": "e56a0006-f421-45be-9aef-e4019db1cf24", "timestamp": "2026-10-21T13:05:57.384Z", "cwd": "/tmp/paseo-edxeth-fixture/lean/workspace", "name": "[marker] Fixture marker verification", "parentSession": "/tmp/paseo-edxeth-fixture/lean/sessions/2026-10-21T13-05-53-085Z_01a15e91-73bd-7282-82c6-d3974711a941.jsonl"}
+{"type": "custom", "customType": "pi-subagents_launch_metadata", "data": {"version": 1, "timestamp": "2026-10-21T13:05:57.385Z", "name": "fixture-marker", "title": "Fixture marker verification", "sessionTitle": "[marker] Fixture marker verification", "agent": "marker", "mode": "background", "sessionMode": "lineage-only", "autoExit": true, "parentClosePolicy": "terminate", "reportContextUsage": true, "async": true, "model": "openai-codex/gpt-5.6-sol", "thinking": "high", "modelRef": "openai-codex/gpt-5.6-sol:high", "definitionModel": "openai-codex/gpt-5.6-sol", "definitionThinking": "high", "allowModelOverride": true, "modelSource": "agent", "tools": "read", "denyTools": ["subagent", "subagent_resume", "subagent_kill"], "spawnableAgents": [], "spawnBudget": null, "extensions": [], "noContextFiles": false, "inheritAppendSystem": false, "noSession": false, "trustProject": false, "agentConfigDir": "/tmp/paseo-edxeth-fixture/lean/agent", "cwd": "/tmp/paseo-edxeth-fixture/lean/workspace", "boundarySystemPrompt": false}, "id": "57355eeb", "parentId": null, "timestamp": "2026-10-21T13:05:57.386Z"}
+{"type": "session_info", "id": "847415e4", "parentId": "57355eeb", "timestamp": "2026-10-21T13:05:57.566Z", "name": "[marker] Fixture marker verification"}
+{"type": "model_change", "id": "d4ad59be", "parentId": "847415e4", "timestamp": "2026-10-21T13:05:57.672Z", "provider": "openai-codex", "modelId": "gpt-5.6-sol"}
+{"type": "thinking_level_change", "id": "7f6bf9d2", "parentId": "d4ad59be", "timestamp": "2026-10-21T13:05:57.672Z", "thinkingLevel": "high"}
+{"type": "message", "id": "737b762e", "parentId": "6b436446", "timestamp": "2026-10-21T13:05:57.679Z", "message": {"role": "user", "content": [{"type": "text", "text": "<file name=\"/home/pi-user/.pi/history/workspace/artifacts/01a15e91-73bd-7282-82c6-d3974711a941/context/fixture-marker-2026-10-21T13-05-57.md\">\n\n\nReturn only the exact marker supplied by the user. Do not use tools.\n\nComplete your task autonomously.\n\nReturn only PASEO_EDXETH_LEAN_OK\n\nYour FINAL assistant message should summarize what you accomplished.\n</file>\n"}], "timestamp": 1792587957678}}
+{"type": "message", "id": "100b110d", "parentId": "737b762e", "timestamp": "2026-10-21T13:06:02.050Z", "message": {"role": "assistant", "content": [{"type": "text", "text": "PASEO_EDXETH_LEAN_OK"}], "api": "openai-codex-responses", "provider": "openai-codex", "model": "gpt-5.6-sol", "usage": {"input": 1713, "output": 13, "cacheRead": 0, "cacheWrite": 0, "reasoning": 0, "totalTokens": 1726, "cost": {"input": 0.006852, "output": 0.00026000000000000003, "cacheRead": 0, "cacheWrite": 0, "total": 0.007111999999999999}}, "stopReason": "stop", "timestamp": 1792587957684, "responseId": "resp_0bc8bfaee079148a016ad8b8b7edb08191924676ed8dcfd447", "rawStopReason": "completed"}}
+{"type": "custom", "customType": "pi-subagent-completion", "data": {"reason": "normal"}, "id": "80bbd3bb", "parentId": "100b110d", "timestamp": "2026-10-21T13:06:02.054Z"}
diff --git a/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/background.json b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/background.json
new file mode 100644
index 0000000000..fe4913f6b6
--- /dev/null
+++ b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/background.json
@@ -0,0 +1,263 @@
+{
+  "provenance": {
+    "package": "Zeno2019/pi-subagents-lean",
+    "version": "2.9.2-lean.1",
+    "sourceCommit": "e10fe855808abcae193a205ea98f8ccd70d25620",
+    "piVersion": "0.87.1",
+    "captureDate": "2026-10-21"
+  },
+  "events": [
+    {
+      "type": "tool_execution_start",
+      "toolCallId": "call_f28b261de3c6440b953f0f56c3fec7d0|fc_0d35cf51b3ed48b9016ad8b8b4a63c81918a55903d0a4f12cb",
+      "toolName": "subagent",
+      "args": {
+        "agent": "marker",
+        "name": "fixture-marker",
+        "title": "Fixture marker verification",
+        "task": "Return only PASEO_EDXETH_LEAN_OK"
+      }
+    },
+    {
+      "type": "tool_execution_end",
+      "toolCallId": "call_f28b261de3c6440b953f0f56c3fec7d0|fc_0d35cf51b3ed48b9016ad8b8b4a63c81918a55903d0a4f12cb",
+      "toolName": "subagent",
+      "result": {
+        "content": [
+          {
+            "type": "text",
+            "text": "Sub-agent \"fixture-marker\" launched async with id 1bfdf3b3. Results will be delivered automatically as a steer message when it finishes. Use this exact id if you need to resume or stop this child.\n\nActivity: /home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/activity.jsonl\nRun evidence: /home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/result.json\nRead these on demand for progress or failure diagnosis; activity is evidence, not a completion verdict."
+          }
+        ],
+        "details": {
+          "evidence": {
+            "runId": "1bfdf3b3",
+            "cwd": "/tmp/paseo-edxeth-fixture/lean/workspace",
+            "activityFile": "/home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/activity.jsonl",
+            "resultFile": "/home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/result.json"
+          },
+          "id": "1bfdf3b3",
+          "name": "fixture-marker",
+          "title": "Fixture marker verification",
+          "task": "Return only PASEO_EDXETH_LEAN_OK",
+          "agent": "marker",
+          "sessionFile": "/tmp/paseo-edxeth-fixture/background/child-session.jsonl",
+          "noSession": false,
+          "status": "started",
+          "mode": "background",
+          "deliveryState": "detached",
+          "parentClosePolicy": "terminate",
+          "async": true,
+          "autoExit": true
+        }
+      },
+      "isError": false
+    },
+    {
+      "type": "message_end",
+      "message": {
+        "role": "custom",
+        "customType": "subagent_result",
+        "content": "Sub-agent \"fixture-marker\" completed (7s).\n\nPASEO_EDXETH_LEAN_OK\n\nSession: /tmp/paseo-edxeth-fixture/background/child-session.jsonl\nResume: pi --session /tmp/paseo-edxeth-fixture/background/child-session.jsonl\n\nSub-agent context: 2K/372K tokens (0%) used at finish.\n\nActivity: /home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/activity.jsonl\nRun evidence: /home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/result.json\nRead these on demand for progress or failure diagnosis; activity is evidence, not a completion verdict.",
+        "display": true,
+        "details": {
+          "evidence": {
+            "runId": "1bfdf3b3",
+            "cwd": "/tmp/paseo-edxeth-fixture/lean/workspace",
+            "activityFile": "/home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/activity.jsonl",
+            "resultFile": "/home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/result.json",
+            "finalized": true
+          },
+          "id": "1bfdf3b3",
+          "name": "fixture-marker",
+          "task": "Return only PASEO_EDXETH_LEAN_OK",
+          "agent": "marker",
+          "mode": "background",
+          "status": "completed",
+          "deliveryState": "detached",
+          "parentClosePolicy": "terminate",
+          "async": true,
+          "exitCode": 0,
+          "elapsed": 7,
+          "outputTokens": 13,
+          "contextTokens": 1775,
+          "contextWindow": 372000,
+          "sessionFile": "/tmp/paseo-edxeth-fixture/background/child-session.jsonl"
+        },
+        "timestamp": 1792587964414
+      }
+    }
+  ],
+  "messages": [
+    {
+      "role": "assistant",
+      "content": [
+        {
+          "type": "toolCall",
+          "id": "call_f28b261de3c6440b953f0f56c3fec7d0|fc_0d35cf51b3ed48b9016ad8b8b4a63c81918a55903d0a4f12cb",
+          "name": "subagent",
+          "arguments": {
+            "agent": "marker",
+            "name": "fixture-marker",
+            "title": "Fixture marker verification",
+            "task": "Return only PASEO_EDXETH_LEAN_OK"
+          }
+        }
+      ],
+      "api": "openai-codex-responses",
+      "provider": "openai-codex",
+      "model": "gpt-5.6-sol",
+      "usage": {
+        "input": 2020,
+        "output": 43,
+        "cacheRead": 0,
+        "cacheWrite": 0,
+        "reasoning": 0,
+        "totalTokens": 2063,
+        "cost": {
+          "input": 0.00808,
+          "output": 0.0008600000000000001,
+          "cacheRead": 0,
+          "cacheWrite": 0,
+          "total": 0.00894
+        }
+      },
+      "stopReason": "toolUse",
+      "timestamp": 1792587953256,
+      "responseId": "resp_0d35cf51b3ed48b9016ad8b8b3698481918f82962b6eaf2788",
+      "rawStopReason": "completed"
+    },
+    {
+      "role": "toolResult",
+      "toolCallId": "call_f28b261de3c6440b953f0f56c3fec7d0|fc_0d35cf51b3ed48b9016ad8b8b4a63c81918a55903d0a4f12cb",
+      "toolName": "subagent",
+      "content": [
+        {
+          "type": "text",
+          "text": "Sub-agent \"fixture-marker\" launched async with id 1bfdf3b3. Results will be delivered automatically as a steer message when it finishes. Use this exact id if you need to resume or stop this child.\n\nActivity: /home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/activity.jsonl\nRun evidence: /home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/result.json\nRead these on demand for progress or failure diagnosis; activity is evidence, not a completion verdict."
+        }
+      ],
+      "details": {
+        "evidence": {
+          "runId": "1bfdf3b3",
+          "cwd": "/tmp/paseo-edxeth-fixture/lean/workspace",
+          "activityFile": "/home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/activity.jsonl",
+          "resultFile": "/home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/result.json",
+          "finalized": true
+        },
+        "id": "1bfdf3b3",
+        "name": "fixture-marker",
+        "title": "Fixture marker verification",
+        "task": "Return only PASEO_EDXETH_LEAN_OK",
+        "agent": "marker",
+        "sessionFile": "/tmp/paseo-edxeth-fixture/background/child-session.jsonl",
+        "noSession": false,
+        "status": "started",
+        "mode": "background",
+        "deliveryState": "detached",
+        "parentClosePolicy": "terminate",
+        "async": true,
+        "autoExit": true
+      },
+      "isError": false,
+      "timestamp": 1792587957399
+    },
+    {
+      "role": "assistant",
+      "content": [
+        {
+          "type": "thinking",
+          "thinking": "**Identifying need for await keyword**"
+        },
+        {
+          "type": "text",
+          "text": "DONE"
+        }
+      ],
+      "api": "openai-codex-responses",
+      "provider": "openai-codex",
+      "model": "gpt-5.6-sol",
+      "usage": {
+        "input": 2258,
+        "output": 18,
+        "cacheRead": 0,
+        "cacheWrite": 0,
+        "reasoning": 11,
+        "totalTokens": 2276,
+        "cost": {
+          "input": 0.009032,
+          "output": 0.00036,
+          "cacheRead": 0,
+          "cacheWrite": 0,
+          "total": 0.009392
+        }
+      },
+      "stopReason": "stop",
+      "timestamp": 1792587957402,
+      "responseId": "resp_0d35cf51b3ed48b9016ad8b8b602108191a8e8f7fd77fbe5b5",
+      "rawStopReason": "completed"
+    },
+    {
+      "role": "custom",
+      "customType": "subagent_result",
+      "content": "Sub-agent \"fixture-marker\" completed (7s).\n\nPASEO_EDXETH_LEAN_OK\n\nSession: /tmp/paseo-edxeth-fixture/background/child-session.jsonl\nResume: pi --session /tmp/paseo-edxeth-fixture/background/child-session.jsonl\n\nSub-agent context: 2K/372K tokens (0%) used at finish.\n\nActivity: /home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/activity.jsonl\nRun evidence: /home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/result.json\nRead these on demand for progress or failure diagnosis; activity is evidence, not a completion verdict.",
+      "display": true,
+      "details": {
+        "evidence": {
+          "runId": "1bfdf3b3",
+          "cwd": "/tmp/paseo-edxeth-fixture/lean/workspace",
+          "activityFile": "/home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/activity.jsonl",
+          "resultFile": "/home/pi-user/.pi/history/workspace/artifacts/2026-10-21T13-05-57-380Z_db802a71-7bb32177-573971ee-535c/subagents/1bfdf3b3/result.json",
+          "finalized": true
+        },
+        "id": "1bfdf3b3",
+        "name": "fixture-marker",
+        "task": "Return only PASEO_EDXETH_LEAN_OK",
+        "agent": "marker",
+        "mode": "background",
+        "status": "completed",
+        "deliveryState": "detached",
+        "parentClosePolicy": "terminate",
+        "async": true,
+        "exitCode": 0,
+        "elapsed": 7,
+        "outputTokens": 13,
+        "contextTokens": 1775,
+        "contextWindow": 372000,
+        "sessionFile": "/tmp/paseo-edxeth-fixture/background/child-session.jsonl"
+      },
+      "timestamp": 1792587964414
+    },
+    {
+      "role": "assistant",
+      "content": [
+        {
+          "type": "text",
+          "text": "DONE"
+        }
+      ],
+      "api": "openai-codex-responses",
+      "provider": "openai-codex",
+      "model": "gpt-5.6-sol",
+      "usage": {
+        "input": 389,
+        "output": 5,
+        "cacheRead": 2176,
+        "cacheWrite": 0,
+        "reasoning": 0,
+        "totalTokens": 2570,
+        "cost": {
+          "input": 0.0015559999999999999,
+          "output": 0.0001,
+          "cacheRead": 0.0008704000000000001,
+          "cacheWrite": 0,
+          "total": 0.0025264
+        }
+      },
+      "stopReason": "stop",
+      "timestamp": 1792587964417,
+      "responseId": "resp_0d35cf51b3ed48b9016ad8b8bd0c548191bddd1fe3410a1c82",
+      "rawStopReason": "completed"
+    }
+  ]
+}
diff --git a/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/foreground-child-session.jsonl b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/foreground-child-session.jsonl
new file mode 100644
index 0000000000..a607a1032d
--- /dev/null
+++ b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/foreground-child-session.jsonl
@@ -0,0 +1,8 @@
+{"type": "session", "version": 3, "id": "afbea6e0-7858-4ecf-8ef1-e26af9b7d6e0", "timestamp": "2026-10-21T13:05:17.628Z", "cwd": "/tmp/paseo-edxeth-fixture/upstream/workspace", "name": "[marker] Fixture marker verification", "parentSession": "/tmp/paseo-edxeth-fixture/upstream/sessions/2026-10-21T13-05-12-212Z_01a15e90-d414-7243-a701-4eb4b0bec880.jsonl"}
+{"type": "custom", "customType": "pi-subagents_launch_metadata", "data": {"version": 1, "timestamp": "2026-10-21T13:05:17.628Z", "name": "fixture-marker", "title": "Fixture marker verification", "sessionTitle": "[marker] Fixture marker verification", "agent": "marker", "mode": "background", "sessionMode": "lineage-only", "autoExit": true, "parentClosePolicy": "terminate", "reportContextUsage": true, "async": false, "model": "openai-codex/gpt-5.6-sol", "thinking": "high", "modelRef": "openai-codex/gpt-5.6-sol:high", "definitionModel": "openai-codex/gpt-5.6-sol", "definitionThinking": "high", "allowModelOverride": true, "modelSource": "agent", "tools": "read", "denyTools": ["subagent", "subagent_resume", "subagent_kill"], "spawnableAgents": [], "spawnBudget": null, "extensions": [], "noContextFiles": false, "inheritAppendSystem": false, "noSession": false, "trustProject": false, "agentConfigDir": "/tmp/paseo-edxeth-fixture/upstream/agent", "cwd": "/tmp/paseo-edxeth-fixture/upstream/workspace", "boundarySystemPrompt": false}, "id": "3f7d3c3f", "parentId": null, "timestamp": "2026-10-21T13:05:17.629Z"}
+{"type": "session_info", "id": "6e198450", "parentId": "3f7d3c3f", "timestamp": "2026-10-21T13:05:17.825Z", "name": "[marker] Fixture marker verification"}
+{"type": "model_change", "id": "94bf4c0b", "parentId": "6e198450", "timestamp": "2026-10-21T13:05:17.962Z", "provider": "openai-codex", "modelId": "gpt-5.6-sol"}
+{"type": "thinking_level_change", "id": "57cc6428", "parentId": "94bf4c0b", "timestamp": "2026-10-21T13:05:17.962Z", "thinkingLevel": "high"}
+{"type": "message", "id": "a9e47f08", "parentId": "8c186624", "timestamp": "2026-10-21T13:05:17.970Z", "message": {"role": "user", "content": [{"type": "text", "text": "<file name=\"/home/pi-user/.pi/history/workspace/artifacts/01a15e90-d414-7243-a701-4eb4b0bec880/context/fixture-marker-2026-10-21T13-05-17.md\">\n\n\nReturn only the exact marker supplied by the user. Do not use tools.\n\nComplete your task autonomously.\n\nReturn only PASEO_EDXETH_UPSTREAM_OK\n\nYour FINAL assistant message should summarize what you accomplished.\n</file>\n"}], "timestamp": 1792587917968}}
+{"type": "message", "id": "bc221a13", "parentId": "a9e47f08", "timestamp": "2026-10-21T13:05:23.476Z", "message": {"role": "assistant", "content": [{"type": "thinking", "thinking": "**Following user file marker exactly**"}, {"type": "text", "text": "PASEO_EDXETH_UPSTREAM_OK"}], "api": "openai-codex-responses", "provider": "openai-codex", "model": "gpt-5.6-sol", "usage": {"input": 1673, "output": 49, "cacheRead": 0, "cacheWrite": 0, "reasoning": 34, "totalTokens": 1722, "cost": {"input": 0.006692, "output": 0.0009800000000000002, "cacheRead": 0, "cacheWrite": 0, "total": 0.007672}}, "stopReason": "stop", "timestamp": 1792587917974, "responseId": "resp_09445c1733d532e7016ad8b8909c908191ba803c059497945e", "rawStopReason": "completed"}}
+{"type": "custom", "customType": "pi-subagent-completion", "data": {"reason": "normal"}, "id": "832fc8c9", "parentId": "bc221a13", "timestamp": "2026-10-21T13:05:23.477Z"}
diff --git a/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/foreground.json b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/foreground.json
new file mode 100644
index 0000000000..c8df8eb5c2
--- /dev/null
+++ b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/fixtures/foreground.json
@@ -0,0 +1,156 @@
+{
+  "provenance": {
+    "package": "edxeth/pi-subagents",
+    "version": "2.9.2",
+    "sourceCommit": "cf6dbf41c17986f3882e6804a68e8fb8282d25e6",
+    "piVersion": "0.87.1",
+    "captureDate": "2026-10-21"
+  },
+  "events": [
+    {
+      "type": "tool_execution_start",
+      "toolCallId": "call_0bc6fc2213cd49aa92950947bde5dd8a|fc_0a0ca4aa78cd296a016ad8b88d018481919eadbf09eb191a1a",
+      "toolName": "subagent",
+      "args": {
+        "agent": "marker",
+        "name": "fixture-marker",
+        "title": "Fixture marker verification",
+        "task": "Return only PASEO_EDXETH_UPSTREAM_OK"
+      }
+    },
+    {
+      "type": "tool_execution_end",
+      "toolCallId": "call_0bc6fc2213cd49aa92950947bde5dd8a|fc_0a0ca4aa78cd296a016ad8b88d018481919eadbf09eb191a1a",
+      "toolName": "subagent",
+      "result": {
+        "content": [
+          {
+            "type": "text",
+            "text": "Sub-agent \"fixture-marker\" completed (7s).\n\nPASEO_EDXETH_UPSTREAM_OK\n\nSession: /tmp/paseo-edxeth-fixture/foreground/child-session.jsonl\nResume: pi --session /tmp/paseo-edxeth-fixture/foreground/child-session.jsonl\n\nSub-agent context: 2K/372K tokens (0%) used at finish."
+          }
+        ],
+        "details": {
+          "id": "dd7f94e8",
+          "name": "fixture-marker",
+          "agent": "marker",
+          "status": "completed",
+          "mode": "background",
+          "parentClosePolicy": "terminate",
+          "deliveryState": "awaited",
+          "async": false,
+          "autoExit": true,
+          "exitCode": 0,
+          "elapsed": 7,
+          "outputTokens": 49,
+          "contextTokens": 1777,
+          "contextWindow": 372000,
+          "summary": "PASEO_EDXETH_UPSTREAM_OK",
+          "sessionFile": "/tmp/paseo-edxeth-fixture/foreground/child-session.jsonl"
+        }
+      },
+      "isError": false
+    }
+  ],
+  "messages": [
+    {
+      "role": "assistant",
+      "content": [
+        {
+          "type": "toolCall",
+          "id": "call_0bc6fc2213cd49aa92950947bde5dd8a|fc_0a0ca4aa78cd296a016ad8b88d018481919eadbf09eb191a1a",
+          "name": "subagent",
+          "arguments": {
+            "agent": "marker",
+            "name": "fixture-marker",
+            "title": "Fixture marker verification",
+            "task": "Return only PASEO_EDXETH_UPSTREAM_OK"
+          }
+        }
+      ],
+      "api": "openai-codex-responses",
+      "provider": "openai-codex",
+      "model": "gpt-5.6-sol",
+      "usage": {
+        "input": 3256,
+        "output": 43,
+        "cacheRead": 0,
+        "cacheWrite": 0,
+        "reasoning": 0,
+        "totalTokens": 3299,
+        "cost": {
+          "input": 0.013023999999999999,
+          "output": 0.0008600000000000001,
+          "cacheRead": 0,
+          "cacheWrite": 0,
+          "total": 0.013883999999999999
+        }
+      },
+      "stopReason": "toolUse",
+      "timestamp": 1792587912428,
+      "responseId": "resp_0a0ca4aa78cd296a016ad8b88bd52881918cbb9b8326b3060a",
+      "rawStopReason": "completed"
+    },
+    {
+      "role": "toolResult",
+      "toolCallId": "call_0bc6fc2213cd49aa92950947bde5dd8a|fc_0a0ca4aa78cd296a016ad8b88d018481919eadbf09eb191a1a",
+      "toolName": "subagent",
+      "content": [
+        {
+          "type": "text",
+          "text": "Sub-agent \"fixture-marker\" completed (7s).\n\nPASEO_EDXETH_UPSTREAM_OK\n\nSession: /tmp/paseo-edxeth-fixture/foreground/child-session.jsonl\nResume: pi --session /tmp/paseo-edxeth-fixture/foreground/child-session.jsonl\n\nSub-agent context: 2K/372K tokens (0%) used at finish."
+        }
+      ],
+      "details": {
+        "id": "dd7f94e8",
+        "name": "fixture-marker",
+        "agent": "marker",
+        "status": "completed",
+        "mode": "background",
+        "parentClosePolicy": "terminate",
+        "deliveryState": "awaited",
+        "async": false,
+        "autoExit": true,
+        "exitCode": 0,
+        "elapsed": 7,
+        "outputTokens": 49,
+        "contextTokens": 1777,
+        "contextWindow": 372000,
+        "summary": "PASEO_EDXETH_UPSTREAM_OK",
+        "sessionFile": "/tmp/paseo-edxeth-fixture/foreground/child-session.jsonl"
+      },
+      "isError": false,
+      "timestamp": 1792587924671
+    },
+    {
+      "role": "assistant",
+      "content": [
+        {
+          "type": "text",
+          "text": "DONE"
+        }
+      ],
+      "api": "openai-codex-responses",
+      "provider": "openai-codex",
+      "model": "gpt-5.6-sol",
+      "usage": {
+        "input": 388,
+        "output": 5,
+        "cacheRead": 3072,
+        "cacheWrite": 0,
+        "reasoning": 0,
+        "totalTokens": 3465,
+        "cost": {
+          "input": 0.001552,
+          "output": 0.0001,
+          "cacheRead": 0.0012288000000000002,
+          "cacheWrite": 0,
+          "total": 0.0028808
+        }
+      },
+      "stopReason": "stop",
+      "timestamp": 1792587924675,
+      "responseId": "resp_0a0ca4aa78cd296a016ad8b896af2c81919c0ef586dd50f2f0",
+      "rawStopReason": "completed"
+    }
+  ]
+}
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
new file mode 100644
index 0000000000..86692ab32e
--- /dev/null
+++ b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/index.test.ts
@@ -0,0 +1,336 @@
+import { describe, expect, test } from "vitest";
+import { fileURLToPath } from "node:url";
+import { createPiExtensionHost } from "../index.js";
+import { readSubagentFixture, verifySubagentFixture } from "../subagent-fixture-test.js";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { edxethPiSubagents } from "./index.js";
+import { streamPiHistory } from "../../history-mapper.js";
+import { ProviderSubagentStore } from "../../../../provider-subagents/store.js";
+
+const args = {
+  agent: "scout",
+  name: "status-scout",
+  title: "Check child status",
+  task: "Return the completion marker",
+};
+
+describe("edxeth/pi-subagents adapter", () => {
+  test.each(["tool", "notification"])("ends a child that requested help via %s", (delivery) => {
+    const host = createPiExtensionHost();
+    const call = { callId: "spawn-1", toolName: "subagent", args, status: "completed" as const };
+    host.mapToolCall({
+      ...call,
+      result: { details: { id: "run-1", name: args.name, status: "started" } },
+    });
+    const details = { id: "run-1", name: args.name, message: "Please clarify the task" };
+    const result =
+      delivery === "tool"
+        ? host.mapToolCall({ ...call, result: { details: { ...details, status: "pinged" } } })
+        : host.mapCustomMessage({
+            role: "custom",
+            customType: "subagent_ping",
+            content: "Child requested help and exited",
+            details,
+          });
+    expect(result?.subagents).toEqual([
+      expect.objectContaining({
+        type: "upsert",
+        id: "spawn-1",
+        status: "canceled",
+        subtitle: "Needs help",
+      }),
+    ]);
+  });
+
+  test("leaves unrelated tools and other subagent protocols to their adapters", () => {
+    const host = createPiExtensionHost(undefined, [edxethPiSubagents]);
+    const call = { callId: "other", toolName: "subagent", args, status: "completed" as const };
+    for (const details of [null, {}, { mode: "single", results: [] }, { id: "run-1" }]) {
+      expect(host.mapToolCall({ ...call, result: { details } })).toBeUndefined();
+    }
+    expect(
+      host.mapToolCall({
+        ...call,
+        toolName: "unrelated",
+        result: { details: { id: "run-1", name: args.name, status: "completed" } },
+      }),
+    ).toBeUndefined();
+    for (const details of [{ id: "run-1" }, { id: "run-1", status: "unknown" }]) {
+      expect(
+        host.mapCustomMessage({
+          role: "custom",
+          customType: "subagent_result",
+          content: "Unrecognized result",
+          details,
+        }),
+      ).toBeUndefined();
+    }
+  });
+
+  test("waits for cancellation after a kill acknowledgement reports stopping", () => {
+    const host = createPiExtensionHost();
+    host.mapToolCall({
+      callId: "spawn-1",
+      toolName: "subagent",
+      args,
+      status: "completed",
+      result: { details: { id: "run-1", name: args.name, status: "started" } },
+    });
+    const stopping = host.mapToolCall({
+      callId: "kill-1",
+      toolName: "subagent_kill",
+      args: { id: "run-1" },
+      status: "completed",
+      result: { details: { id: "run-1", name: args.name, status: "stopping" } },
+    });
+    expect(stopping?.subagents ?? []).toEqual([]);
+    expect(
+      host.mapCustomMessage({
+        role: "custom",
+        customType: "subagent_result",
+        content: "Cancelled",
+        details: { id: "run-1", status: "cancelled" },
+      })?.subagents,
+    ).toEqual([{ type: "upsert", id: "spawn-1", status: "canceled" }]);
+  });
+
+  test("preserves a completion that arrives before its launch acknowledgement", () => {
+    const host = createPiExtensionHost();
+    const early = host.mapCustomMessage({
+      role: "custom",
+      customType: "subagent_result",
+      content: "Already done",
+      details: { id: "fast-run", status: "completed" },
+    });
+    expect(early?.subagents ?? []).toEqual([]);
+    const started = host.mapToolCall({
+      callId: "fast-call",
+      toolName: "subagent",
+      args,
+      status: "completed",
+      result: {
+        details: { id: "fast-run", name: args.name, agent: args.agent, status: "started" },
+      },
+    });
+    expect(started?.subagents).toEqual([
+      {
+        type: "upsert",
+        id: "fast-call",
+        title: "scout",
+        description: args.task,
+        toolCallId: "fast-call",
+        status: "completed",
+      },
+    ]);
+  });
+
+  test.each([
+    { details: { status: "completed" }, expected: "completed" },
+    { details: { status: "failed" }, expected: "failed" },
+    { details: { status: "cancelled" }, expected: "canceled" },
+    { details: { error: "Child watcher exited unexpectedly" }, expected: "failed" },
+  ])("maps completion $details to $expected", ({ details, expected }) => {
+    const host = createPiExtensionHost();
+    host.mapToolCall({
+      callId: "spawn-1",
+      toolName: "subagent",
+      args,
+      status: "completed",
+      result: { details: { id: "run-1", name: args.name, status: "started" } },
+    });
+    expect(
+      host.mapCustomMessage({
+        role: "custom",
+        customType: "subagent_result",
+        content: "Child result",
+        details: { id: "run-1", ...details },
+      })?.subagents,
+    ).toEqual([{ type: "upsert", id: "spawn-1", status: expected }]);
+  });
+
+  test("a resume gets its own run and reads the retained child session", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "paseo-edxeth-resume-"));
+    const file = join(dir, "child.jsonl");
+    const host = createPiExtensionHost();
+    try {
+      await writeFile(
+        file,
+        JSON.stringify({
+          type: "message",
+          message: { role: "assistant", content: [{ type: "text", text: "RESUMED" }] },
+        }) + "\n",
+      );
+      const original = host.mapToolCall({
+        callId: "spawn-1",
+        toolName: "subagent",
+        args,
+        status: "completed",
+        result: {
+          details: { id: "run-1", name: args.name, status: "completed", sessionFile: file },
+        },
+      });
+      await original?.hydration;
+      const resumed = host.mapToolCall({
+        callId: "resume-1",
+        toolName: "subagent_resume",
+        args: { sessionFile: file, task: "Continue" },
+        status: "completed",
+        result: {
+          details: { id: "run-2", name: args.name, status: "started", sessionFile: file },
+        },
+      });
+      expect(resumed?.childSessions).toEqual([{ id: "resume-1", file }]);
+      expect(await resumed?.hydration).toEqual([
+        {
+          type: "provider_subagent",
+          provider: "pi",
+          event: {
+            type: "timeline",
+            id: "resume-1",
+            item: expect.objectContaining({ type: "assistant_message", text: "RESUMED" }),
+          },
+        },
+      ]);
+      expect(
+        host.mapCustomMessage({
+          role: "custom",
+          customType: "subagent_result",
+          content: "Resumed run complete",
+          details: { id: "run-2", status: "completed", sessionFile: file },
+        })?.subagents,
+      ).toEqual([{ type: "upsert", id: "resume-1", status: "completed" }]);
+    } finally {
+      host.close();
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("settles each batched child by run id without creating a parent-call card", () => {
+    const host = createPiExtensionHost();
+    const result = host.mapToolCall({
+      callId: "batch-1",
+      toolName: "subagent",
+      args: { children: [args, { ...args, agent: "reviewer", name: "status-reviewer" }] },
+      status: "completed",
+      result: {
+        details: {
+          status: "batch",
+          children: [
+            { id: "run-1", ...args, mode: "background", status: "completed" },
+            { id: "run-2", name: "status-reviewer", agent: "reviewer", status: "started" },
+          ],
+        },
+      },
+    });
+    expect(result?.subagents).toEqual([
+      {
+        type: "upsert",
+        id: "batch-1:0",
+        title: "scout",
+        description: args.task,
+        toolCallId: "batch-1",
+        status: "completed",
+      },
+      {
+        type: "upsert",
+        id: "batch-1:1",
+        title: "reviewer",
+        description: undefined,
+        toolCallId: "batch-1",
+        status: "running",
+      },
+    ]);
+    expect(
+      host.mapCustomMessage({
+        role: "custom",
+        customType: "subagent_result",
+        content: "Done",
+        details: { id: "run-2", status: "completed" },
+      })?.subagents,
+    ).toEqual([{ type: "upsert", id: "batch-1:1", status: "completed" }]);
+  });
+
+  test.each([
+    { mode: "foreground", statuses: ["running", "completed"] },
+    { mode: "background", statuses: ["running", "running", "completed"] },
+  ])("settles the captured $mode run live and on replay", async ({ mode, statuses }) => {
+    const fixture = readSubagentFixture(new URL(`./fixtures/${mode}.json`, import.meta.url), {
+      from: `/tmp/paseo-edxeth-fixture/${mode}/child-session.jsonl`,
+      to: fileURLToPath(new URL(`./fixtures/${mode}-child-session.jsonl`, import.meta.url)),
+    });
+    const events = await verifySubagentFixture(fixture);
+    const updates = events.flatMap(({ event }) => (event.type === "upsert" ? [event] : []));
+    expect(updates.map((event) => event.status)).toEqual(statuses);
+    expect(new Set(updates.map((event) => event.id)).size).toBe(1);
+    expect(events.some(({ event }) => event.type === "timeline")).toBe(true);
+  });
+
+  test.each(["foreground", "background"])(
+    "restores a completed %s child and its transcript to the consumer store",
+    async (mode) => {
+      const fixture = readSubagentFixture(new URL(`./fixtures/${mode}.json`, import.meta.url), {
+        from: `/tmp/paseo-edxeth-fixture/${mode}/child-session.jsonl`,
+        to: fileURLToPath(new URL(`./fixtures/${mode}-child-session.jsonl`, import.meta.url)),
+      });
+      const store = new ProviderSubagentStore();
+      for await (const event of streamPiHistory("pi", fixture.messages)) {
+        if (event.type === "provider_subagent") store.apply("parent", "pi", event.event);
+      }
+      const children = store.list("parent");
+      expect(children).toEqual([expect.objectContaining({ status: "completed", title: "marker" })]);
+      const transcript = store.fetchTimeline("parent", children[0]!.id);
+      expect(transcript.rows).toContainEqual(
+        expect.objectContaining({
+          item: expect.objectContaining({
+            type: "assistant_message",
+            text: mode === "foreground" ? "PASEO_EDXETH_UPSTREAM_OK" : "PASEO_EDXETH_LEAN_OK",
+          }),
+        }),
+      );
+    },
+  );
+
+  test("settles a synchronous result on the card created when the tool started", () => {
+    const host = createPiExtensionHost();
+    const call = { callId: "spawn-1", toolName: "subagent", args };
+    const start = host.mapToolCall({ ...call, status: "running", result: null });
+    expect(start?.subagents).toEqual([
+      {
+        type: "upsert",
+        id: "spawn-1",
+        title: "scout",
+        description: args.task,
+        toolCallId: "spawn-1",
+        status: "running",
+      },
+    ]);
+    const end = host.mapToolCall({
+      ...call,
+      status: "completed",
+      result: {
+        content: [{ type: "text", text: "DONE" }],
+        details: {
+          id: "run-1",
+          name: args.name,
+          agent: args.agent,
+          mode: "background",
+          status: "completed",
+          deliveryState: "awaited",
+          exitCode: 0,
+        },
+      },
+    });
+    expect(end?.subagents).toEqual([
+      {
+        type: "upsert",
+        id: "spawn-1",
+        title: "scout",
+        description: args.task,
+        toolCallId: "spawn-1",
+        status: "completed",
+      },
+    ]);
+  });
+});
diff --git a/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/index.ts b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/index.ts
new file mode 100644
index 0000000000..c58f0faf15
--- /dev/null
+++ b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/index.ts
@@ -0,0 +1,119 @@
+import { z } from "zod";
+import type { PiChildSessionFile, PiExtension } from "../contract.js";
+import type { ProviderSubagentInputEvent } from "../../../../provider-subagents/store.js";
+
+const Run = z
+  .object({
+    id: z.string().trim().min(1),
+    name: z.string().trim().min(1),
+    agent: z.string().trim().min(1).optional(),
+    task: z.string().optional(),
+    status: z.enum(["started", "completed", "failed", "cancelled", "pinged"]),
+    sessionFile: z.string().trim().min(1).optional(),
+  })
+  .passthrough();
+const Args = z.object({ task: z.string().optional() }).passthrough();
+const Batch = z.object({ status: z.enum(["started", "batch"]), children: z.array(Run).min(1) });
+const Completion = z
+  .object({
+    id: z.string().trim().min(1),
+    status: z.enum(["completed", "failed", "cancelled", "pinged"]).optional(),
+    error: z.string().optional(),
+    sessionFile: z.string().trim().min(1).optional(),
+  })
+  .passthrough();
+const Ping = Completion.extend({ message: z.string() });
+
+function childStatus(status: z.infer<typeof Run>["status"]) {
+  if (status === "started") return "running";
+  // A ping ends the child process and needs a new resume run. It is not success.
+  if (status === "cancelled" || status === "pinged") return "canceled";
+  return status;
+}
+
+export const edxethPiSubagents: PiExtension = {
+  id: "edxeth/pi-subagents",
+  createSession: () => {
+    const callsByRun = new Map<string, string>();
+    const completions = new Map<string, z.infer<typeof Completion>>();
+    const readSessions = new Map<string, string>();
+    const childSession = (id: string, file: string | undefined): PiChildSessionFile[] => {
+      if (!file || readSessions.get(id) === file) return [];
+      readSessions.set(id, file);
+      return [{ id, file }];
+    };
+    const completeRun = (result: z.infer<typeof Completion>) => {
+      const status = result.status ?? (result.error === undefined ? undefined : "failed");
+      if (!status) return undefined;
+      // A fast child can finish before the tool returns its run id. Keep the
+      // terminal outcome so a later "started" acknowledgement cannot regress it.
+      completions.set(result.id, { ...result, status });
+      const id = callsByRun.get(result.id);
+      if (!id) return undefined;
+      const subagents: ProviderSubagentInputEvent[] = [
+        {
+          type: "upsert",
+          id,
+          status: childStatus(status),
+          ...(status === "pinged" ? { subtitle: "Needs help" } : {}),
+        },
+      ];
+      return { subagents, childSessions: childSession(id, result.sessionFile) };
+    };
+    return {
+      mapToolCall(call) {
+        const isLaunch = call.toolName === "subagent" || call.toolName === "subagent_resume";
+        if (!isLaunch || call.status === "running") return undefined;
+        const details = typeof call.result === "object" ? call.result?.details : null;
+        const single = Run.safeParse(details);
+        let runs: z.infer<typeof Run>[];
+        if (single.success) {
+          runs = [single.data];
+        } else {
+          const batch = Batch.safeParse(details);
+          if (!batch.success) return undefined;
+          runs = batch.data.children;
+        }
+        const args = Args.safeParse(call.args);
+        const description = args.success ? args.data.task : undefined;
+        const subagents: ProviderSubagentInputEvent[] = [];
+        const childSessions: PiChildSessionFile[] = [];
+        for (const [index, run] of runs.entries()) {
+          const id = runs.length === 1 ? call.callId : `${call.callId}:${index}`;
+          const completion = completions.get(run.id);
+          const status = completion?.status ?? run.status;
+          callsByRun.set(run.id, id);
+          subagents.push({
+            type: "upsert",
+            id,
+            title: run.agent ?? run.name,
+            description: run.task ?? description,
+            toolCallId: call.callId,
+            status: childStatus(status),
+            ...(status === "pinged" ? { subtitle: "Needs help" } : {}),
+          });
+          childSessions.push(...childSession(id, completion?.sessionFile ?? run.sessionFile));
+        }
+        return {
+          detail: {
+            type: "sub_agent",
+            description,
+            // COMPAT(subagent-log): remove after 2027-04-30.
+            log: "",
+          },
+          subagents,
+          childSessions,
+        };
+      },
+      mapCustomMessage(message) {
+        if (message.customType === "subagent_ping") {
+          const ping = Ping.safeParse(message.details);
+          return ping.success ? completeRun({ ...ping.data, status: "pinged" }) : undefined;
+        }
+        if (message.customType !== "subagent_result") return undefined;
+        const parsed = Completion.safeParse(message.details);
+        return parsed.success ? completeRun(parsed.data) : undefined;
+      },
+    };
+  },
+};
diff --git a/packages/server/src/server/agent/providers/pi/extensions/gotgenes-pi-subagents/index.test.ts b/packages/server/src/server/agent/providers/pi/extensions/gotgenes-pi-subagents/index.test.ts
index f89a9aefd3..7bb62a9d1f 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/gotgenes-pi-subagents/index.test.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/gotgenes-pi-subagents/index.test.ts
@@ -130,6 +130,18 @@ describe("@gotgenes/pi-subagents adapter", () => {
         .filter((event) => event.event.type === "upsert")
         .map((event) => (event.event.type === "upsert" ? event.event.status : null)),
     ).toEqual(["running", "completed"]);
+    expect(
+      events.flatMap((event) => (event.event.type === "timeline" ? [event.event] : [])),
+    ).toEqual([
+      {
+        type: "timeline",
+        id: "call_502323",
+        item: {
+          type: "assistant_message",
+          text: "Agent completed in 4.7s (1 tool uses, 9.0k token).\nAgent ID: 848583f5-6749-4a1\n\nThe workspace is empty.",
+        },
+      },
+    ]);
   });
   test("correlates a background notification and result collection", async () => {
     const source = readSubagentFixture(new URL("./fixtures/background.json", import.meta.url));
diff --git a/packages/server/src/server/agent/providers/pi/extensions/gotgenes-pi-subagents/index.ts b/packages/server/src/server/agent/providers/pi/extensions/gotgenes-pi-subagents/index.ts
index e1869705f8..9383911c3d 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/gotgenes-pi-subagents/index.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/gotgenes-pi-subagents/index.ts
@@ -64,7 +64,8 @@ export const gotgenesPiSubagents: PiExtension = {
         type: "sub_agent" as const,
         subAgentType: title,
         description,
-        log: extractTextFromToolResult(call.result)?.trim() ?? "",
+        // COMPAT(subagent-log): remove after 2027-04-30.
+        log: "",
       };
       if (call.status === "running")
         return {
@@ -92,6 +93,10 @@ export const gotgenesPiSubagents: PiExtension = {
         outputFileFromToolResult(call.result) ?? pendingFilesByAgent.get(details.data.agentId);
       pendingFilesByAgent.delete(details.data.agentId);
       const childSessions = childSession(call.callId, file);
+      const childStatus = status(details.data.status);
+      // Without a session file, as on replay, the child's answer is the tool result.
+      const answer =
+        !file && childStatus !== "running" ? extractTextFromToolResult(call.result)?.trim() : "";
       return {
         detail,
         subagents: [
@@ -101,8 +106,17 @@ export const gotgenesPiSubagents: PiExtension = {
             title,
             description,
             toolCallId: call.callId,
-            status: status(details.data.status),
+            status: childStatus,
           },
+          ...(answer
+            ? [
+                {
+                  type: "timeline" as const,
+                  id: call.callId,
+                  item: { type: "assistant_message" as const, text: answer },
+                },
+              ]
+            : []),
         ],
         childSessions,
       };
@@ -118,7 +132,8 @@ export const gotgenesPiSubagents: PiExtension = {
       const detail = {
         type: "sub_agent" as const,
         description: details.success ? details.data.description : undefined,
-        log: extractTextFromToolResult(call.result)?.trim() ?? "",
+        // COMPAT(subagent-log): remove after 2027-04-30.
+        log: "",
       };
       if (call.status === "running" || !details.success) return { detail };
       const file = details.data.transcriptPath;
diff --git a/packages/server/src/server/agent/providers/pi/extensions/index.test.ts b/packages/server/src/server/agent/providers/pi/extensions/index.test.ts
index 9afacae977..d374c1a02d 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/index.test.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/index.test.ts
@@ -83,7 +83,7 @@ describe("Pi extension host", () => {
   test("declines a throwing adapter and preserves generic history", async () => {
     const host = createPiExtensionHost(undefined, [throwingAdapter]);
     const mapper = new PiHistoryMapper("pi", [], {}, host);
-    const events = mapper.mapMessages([
+    const events = await mapper.mapMessages([
       {
         role: "assistant",
         content: [{ type: "toolCall", id: "call-1", name: "other", arguments: {} }],
@@ -193,7 +193,7 @@ describe("Pi extension host", () => {
     await output?.hydration;
     expect(reads).toHaveLength(8);
   });
-  test("claims a tool, declines an unrelated one, and maps history like live events", () => {
+  test("claims a tool, declines an unrelated one, and maps history like live events", async () => {
     const host = createPiExtensionHost();
     const args = { agent: "scout", task: "Inspect files" };
     const result = parseToolResult({ content: [{ type: "text", text: "Found two files" }] });
@@ -210,7 +210,7 @@ describe("Pi extension host", () => {
           type: "sub_agent",
           subAgentType: "scout",
           description: "Inspect files",
-          log: "Found two files",
+          log: "",
         },
       }),
     );
@@ -225,7 +225,7 @@ describe("Pi extension host", () => {
     ).toBeUndefined();
 
     const mapper = new PiHistoryMapper("pi");
-    const events = mapper.mapMessages([
+    const events = await mapper.mapMessages([
       {
         role: "assistant",
         content: [{ type: "toolCall", id: "call-1", name: "subagent", arguments: args }],
diff --git a/packages/server/src/server/agent/providers/pi/extensions/pi-subagents/index.test.ts b/packages/server/src/server/agent/providers/pi/extensions/pi-subagents/index.test.ts
index 8e9db54047..740d66aadc 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/pi-subagents/index.test.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/pi-subagents/index.test.ts
@@ -137,7 +137,7 @@ describe("pi-subagents adapter", () => {
       type: "sub_agent",
       subAgentType: "reviewer",
       description: "Review the Pi mapper change",
-      log: "The mapper change preserves provider status.",
+      log: "",
     });
   });
 
diff --git a/packages/server/src/server/agent/providers/pi/extensions/pi-subagents/index.ts b/packages/server/src/server/agent/providers/pi/extensions/pi-subagents/index.ts
index 64e814af3f..058171e8df 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/pi-subagents/index.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/pi-subagents/index.ts
@@ -131,7 +131,8 @@ export const piSubagents: PiExtension = {
         type: "sub_agent" as const,
         subAgentType: args.data.agent,
         description: args.data.task,
-        log: extractTextFromToolResult(call.result)?.trim() ?? "",
+        // COMPAT(subagent-log): remove after 2027-04-30.
+        log: "",
       };
       const base = {
         type: "upsert" as const,
diff --git a/packages/server/src/server/agent/providers/pi/extensions/registry.ts b/packages/server/src/server/agent/providers/pi/extensions/registry.ts
index c66fabad80..ca273b83bb 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/registry.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/registry.ts
@@ -1,5 +1,6 @@
 import { piAskUser } from "./pi-ask-user/index.js";
 import { piSubagents } from "./pi-subagents/index.js";
+import { edxethPiSubagents } from "./edxeth-pi-subagents/index.js";
 import { piMcpAdapter } from "./pi-mcp-adapter/index.js";
 import { rpivTodo } from "./rpiv-todo/index.js";
 import { piExampleTodo } from "./pi-example-todo/index.js";
@@ -10,6 +11,7 @@ import { rpivAskUserQuestion } from "./rpiv-ask-user-question/index.js";
 
 export const piExtensions = [
   piAskUser, // Dialog correlation
+  edxethPiSubagents, // Structured results before the generic subagent tool matcher
   piSubagents, // Delegation calls
   tintinwebPiSubagents,
   gotgenesPiSubagents,
diff --git a/packages/server/src/server/agent/providers/pi/extensions/rpiv-ask-user-question/index.test.ts b/packages/server/src/server/agent/providers/pi/extensions/rpiv-ask-user-question/index.test.ts
index 3ec9256a29..d3c9fb7a9e 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/rpiv-ask-user-question/index.test.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/rpiv-ask-user-question/index.test.ts
@@ -79,7 +79,7 @@ test("cancellation declines each remaining real RPC dialog", () => {
   }
 });
 
-test("captured result renders in live and history tool rows, while foreign shapes decline", () => {
+test("captured result renders in live and history tool rows, while foreign shapes decline", async () => {
   const call = {
     callId: end.toolCallId,
     toolName: end.toolName,
@@ -93,7 +93,7 @@ test("captured result renders in live and history tool rows, while foreign shape
     label: "Questions",
     text: "Which snack?: Cookie\nWhich colors?: Red, Blue\nWhat project name?: Nebula",
   });
-  const history = new PiHistoryMapper("pi").mapMessages([
+  const history = await new PiHistoryMapper("pi").mapMessages([
     {
       role: "assistant",
       content: [
diff --git a/packages/server/src/server/agent/providers/pi/extensions/subagent-fixture-test.ts b/packages/server/src/server/agent/providers/pi/extensions/subagent-fixture-test.ts
index 8a9ca61d08..96ba771594 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/subagent-fixture-test.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/subagent-fixture-test.ts
@@ -54,8 +54,6 @@ export async function verifySubagentFixture(
   try {
     await session.startTurn("Delegate work");
     for (const event of fixture.events) pi.latestSession().emit(event);
-    const immediate = live.filter((event) => event.type === "provider_subagent");
-    expect(immediate.some((event) => event.event.type === "timeline")).toBe(false);
     pi.latestSession().finishTurn();
     const replay: AgentStreamEvent[] = [];
     for await (const event of streamPiHistory("pi", fixture.messages)) replay.push(event);
diff --git a/packages/server/src/server/agent/providers/pi/extensions/task-fixture-test.ts b/packages/server/src/server/agent/providers/pi/extensions/task-fixture-test.ts
index a3b2114cab..f702e0d7cf 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/task-fixture-test.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/task-fixture-test.ts
@@ -89,7 +89,7 @@ export async function verifyTaskFixture(path: URL, expectedStatuses: string[]):
     for (const event of fixture.events) pi.latestSession().emit(event);
     pi.latestSession().finishTurn();
     expect(todos(live)).toEqual(mapped);
-    const replay = new PiHistoryMapper("pi").mapMessages(fixture.messages);
+    const replay = await new PiHistoryMapper("pi").mapMessages(fixture.messages);
     expect(todos(replay)).toEqual(mapped);
     expect(
       replay.filter(
diff --git a/packages/server/src/server/agent/providers/pi/extensions/tintinweb-pi-subagents/index.test.ts b/packages/server/src/server/agent/providers/pi/extensions/tintinweb-pi-subagents/index.test.ts
index ad666bb4d3..60f3b12869 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/tintinweb-pi-subagents/index.test.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/tintinweb-pi-subagents/index.test.ts
@@ -36,12 +36,17 @@ describe("@tintinweb/pi-subagents adapter", () => {
     });
     expect(mapping?.subagents).toEqual([
       expect.objectContaining({ id: "call-1", status: "completed" }),
+      {
+        type: "timeline",
+        id: "call-1",
+        item: { type: "assistant_message", text: "Wrapped up (turn limit)" },
+      },
     ]);
     expect(mapping?.detail).toEqual({
       type: "sub_agent",
       subAgentType: "Explore",
       description: "Inspect",
-      log: "Wrapped up (turn limit)",
+      log: "",
     });
   });
   test("maps captured foreground lifecycle live and on replay", async () => {
@@ -53,6 +58,18 @@ describe("@tintinweb/pi-subagents adapter", () => {
         .filter((event) => event.event.type === "upsert")
         .map((event) => (event.event.type === "upsert" ? event.event.status : null)),
     ).toEqual(["running", "completed"]);
+    expect(
+      events.flatMap((event) => (event.event.type === "timeline" ? [event.event] : [])),
+    ).toEqual([
+      {
+        type: "timeline",
+        id: "call_458926",
+        item: {
+          type: "assistant_message",
+          text: "Agent completed in 6.6s (1 tool uses, 18.8k token).\n\nThe workspace directory `/tmp/paseo-pi-extension-phase3/workspace` is empty (no files or hidden dotfiles).",
+        },
+      },
+    ]);
   });
   test("uses a structured notification to complete a background child", async () => {
     const source = readSubagentFixture(new URL("./fixtures/background.json", import.meta.url));
@@ -147,7 +164,7 @@ describe("@tintinweb/pi-subagents adapter", () => {
       expect(mapping?.detail).toEqual({
         type: "sub_agent",
         description: undefined,
-        log: "Wrapped up (turn limit)",
+        log: "",
       });
     },
   );
diff --git a/packages/server/src/server/agent/providers/pi/extensions/tintinweb-pi-subagents/index.ts b/packages/server/src/server/agent/providers/pi/extensions/tintinweb-pi-subagents/index.ts
index 56b5935172..6858dec8be 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/tintinweb-pi-subagents/index.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/tintinweb-pi-subagents/index.ts
@@ -57,7 +57,8 @@ export const tintinwebPiSubagents: PiExtension = {
         type: "sub_agent" as const,
         subAgentType: title,
         description,
-        log: extractTextFromToolResult(call.result)?.trim() ?? "",
+        // COMPAT(subagent-log): remove after 2027-04-30.
+        log: "",
       };
       if (call.status === "running")
         return {
@@ -84,6 +85,10 @@ export const tintinwebPiSubagents: PiExtension = {
       const file = outputFileFromToolResult(call.result);
       const childSessions = file && !readSessions.has(file) ? [{ id: call.callId, file }] : [];
       if (file) readSessions.add(file);
+      const childStatus = status(details.data.status);
+      // A foreground child has no session file; its answer is the tool result.
+      const answer =
+        !file && childStatus !== "running" ? extractTextFromToolResult(call.result)?.trim() : "";
       return {
         detail,
         subagents: [
@@ -93,8 +98,17 @@ export const tintinwebPiSubagents: PiExtension = {
             title,
             description,
             toolCallId: call.callId,
-            status: status(details.data.status),
+            status: childStatus,
           },
+          ...(answer
+            ? [
+                {
+                  type: "timeline" as const,
+                  id: call.callId,
+                  item: { type: "assistant_message" as const, text: answer },
+                },
+              ]
+            : []),
         ],
         childSessions,
       };
@@ -110,7 +124,8 @@ export const tintinwebPiSubagents: PiExtension = {
       const detail = {
         type: "sub_agent" as const,
         description: details.success ? details.data.description : undefined,
-        log: extractTextFromToolResult(call.result)?.trim() ?? "",
+        // COMPAT(subagent-log): remove after 2027-04-30.
+        log: "",
       };
       if (call.status === "running" || !details.success) return { detail };
       return {
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 24d18306b2..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";
@@ -221,3 +223,307 @@ describe("Pi history mapper", () => {
     ]);
   });
 });
+
+describe("Pi tool-result image replay", () => {
+  test("recreates an image from native tool-result history without its source file", async () => {
+    const events = await collectHistory([
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "toolCall",
+            id: "image-read",
+            name: "read",
+            arguments: { path: "missing-preview.png" },
+          },
+        ],
+      },
+      {
+        role: "toolResult",
+        toolCallId: "image-read",
+        toolName: "read",
+        content: [
+          { type: "text", text: "Read image file [image/png]" },
+          { type: "image", data: "aGVsbG8=", mimeType: "image/png" },
+        ],
+      },
+    ]);
+    expect(events.map((event) => event.item?.type)).toEqual([
+      "tool_call",
+      "tool_call",
+      "assistant_message",
+    ]);
+    const image = events.find(
+      (event) => event.type === "timeline" && event.item.type === "assistant_message",
+    );
+    expect(image).toMatchObject({
+      type: "timeline",
+      item: { type: "assistant_message", text: expect.stringContaining("![Image](file://") },
+    });
+    if (image?.type !== "timeline" || image.item.type !== "assistant_message")
+      throw new Error("Missing image");
+    const url = image.item.text.match(/\((file:[^)]+)\)/)![1];
+    const { readFile, unlink } = await import("node:fs/promises");
+    expect(await readFile(new URL(url))).toEqual(Buffer.from("hello"));
+    await unlink(new URL(url));
+    const replay = await collectHistory([
+      {
+        role: "toolResult",
+        toolCallId: "image-read",
+        toolName: "read",
+        content: [{ type: "image", data: "aGVsbG8=", mimeType: "image/png" }],
+      },
+    ]);
+    expect(replay).toContainEqual(image);
+    expect(await readFile(new URL(url))).toEqual(Buffer.from("hello"));
+  });
+});
+
+test("replayed Pi images keep their position before the following reply", async () => {
+  const events = await collectHistory([
+    {
+      role: "toolResult",
+      toolCallId: "image-position",
+      toolName: "read",
+      content: [{ type: "image", data: "aGVsbG8=", mimeType: "image/png" }],
+    },
+    { role: "assistant", content: [{ type: "text", text: "Image read complete." }] },
+  ]);
+  expect(
+    events.map((event) =>
+      event.item?.type === "assistant_message" ? event.item.text : event.item?.type,
+    ),
+  ).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/history-mapper.ts b/packages/server/src/server/agent/providers/pi/history-mapper.ts
index 27a0250b00..89d9fcedce 100644
--- a/packages/server/src/server/agent/providers/pi/history-mapper.ts
+++ b/packages/server/src/server/agent/providers/pi/history-mapper.ts
@@ -1,5 +1,9 @@
 import { mapCustomMessageToToolCall } from "../custom-message.js";
 import type { AgentStreamEvent, AgentTimelineItem, ToolCallDetail } from "../../agent-sdk-types.js";
+import {
+  materializeProviderImage,
+  renderProviderImageOutputAsAssistantMarkdown,
+} from "../provider-image-output.js";
 import {
   createPiExtensionHost,
   type PiExtensionEventOutput,
@@ -11,6 +15,7 @@ import {
   mapToolDetail,
   parseToolArgs,
   parseToolResult,
+  splitPiToolResultImages,
   type PiToolResult,
   type PiTrackedToolCall,
 } from "./tool-call-mapper.js";
@@ -71,7 +76,7 @@ export class PiHistoryMapper {
     private readonly extensionHost: PiExtensionHost = createPiExtensionHost(),
   ) {}
 
-  mapMessages(messages: readonly PiAgentMessage[]): AgentStreamEvent[] {
+  async mapMessages(messages: readonly PiAgentMessage[]): Promise<AgentStreamEvent[]> {
     const events: AgentStreamEvent[] = [];
 
     for (const message of messages) {
@@ -86,7 +91,7 @@ export class PiHistoryMapper {
           events.push(...this.mapAssistantMessage(message));
           break;
         case "toolResult": {
-          events.push(...this.mapToolResultMessage(message));
+          events.push(...(await this.mapToolResultMessage(message)));
           break;
         }
         case "bashExecution":
@@ -207,24 +212,35 @@ export class PiHistoryMapper {
     return events;
   }
 
-  private mapToolResultMessage(
+  private async mapToolResultMessage(
     message: Extract<PiAgentMessage, { role: "toolResult" }>,
-  ): AgentStreamEvent[] {
+  ): Promise<AgentStreamEvent[]> {
     const tracked =
       this.pendingToolCalls.get(message.toolCallId) ?? parseToolArgs(message.toolName, null);
     this.pendingToolCalls.delete(message.toolCallId);
     const result = parseToolResult({ content: message.content, details: message.details });
+    // Pull image blocks out of the result so base64 never reaches the tool output, then render
+    // each one as an assistant_message markdown image after the tool_call (mirroring the live
+    // path and the Claude provider, upstream #1717).
+    const { images, result: splitResult } = splitPiToolResultImages(result);
     const mapping = this.extensionHost.mapToolCall({
       callId: message.toolCallId,
       toolName: tracked.toolName,
       args: tracked.args,
       status: message.isError ? "failed" : "completed",
-      result,
+      result: splitResult,
     });
-    const detail = this.mapToolDetail(message.toolCallId, tracked, result, mapping?.detail);
+    const detail = this.mapToolDetail(message.toolCallId, tracked, splitResult, mapping?.detail);
     if (!detail) {
       return [];
     }
+    const imageEvents: AgentStreamEvent[] = [];
+    for (const image of images) {
+      const item = await renderProviderImageOutputAsAssistantMarkdown(image, {
+        materialize: materializeProviderImage,
+      });
+      if (item) imageEvents.push({ type: "timeline", provider: this.provider, item });
+    }
     return [
       {
         type: "timeline",
@@ -234,9 +250,10 @@ export class PiHistoryMapper {
           name: mapping?.name ?? tracked.toolName,
           isError: Boolean(message.isError),
           detail,
-          errorText: extractTextFromToolResult(result) ?? "Tool call failed",
+          errorText: extractTextFromToolResult(splitResult) ?? "Tool call failed",
         }),
       },
+      ...imageEvents,
       ...this.extensionEvents(mapping),
     ];
   }
@@ -297,9 +314,10 @@ export async function* streamPiHistory(
   signal?: AbortSignal,
 ): AsyncGenerator<AgentStreamEvent> {
   const mapper = new PiHistoryMapper(provider, userEntries, hooks, extensionHost);
-  for (const event of mapper.mapMessages(messages)) {
+  for (const message of messages) {
     if (signal?.aborted) return;
-    if (event) {
+    for (const event of await mapper.mapMessages([message])) {
+      if (signal?.aborted) return;
       yield event;
     }
   }
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/tool-call-mapper.test.ts b/packages/server/src/server/agent/providers/pi/tool-call-mapper.test.ts
index 63b557f994..0c065e27cd 100644
--- a/packages/server/src/server/agent/providers/pi/tool-call-mapper.test.ts
+++ b/packages/server/src/server/agent/providers/pi/tool-call-mapper.test.ts
@@ -1,6 +1,12 @@
 import { describe, expect, test } from "vitest";
 
-import { mapToolDetail, parseToolArgs, parseToolResult } from "./tool-call-mapper.js";
+import {
+  extractTextFromToolResult,
+  mapToolDetail,
+  parseToolArgs,
+  parseToolResult,
+  splitPiToolResultImages,
+} from "./tool-call-mapper.js";
 
 describe("Pi tool call mapper", () => {
   test("maps bash args and result to shell detail", () => {
@@ -56,3 +62,77 @@ describe("Pi tool call mapper", () => {
     });
   });
 });
+
+describe("splitPiToolResultImages", () => {
+  test("extracts image blocks and replaces them with [image] placeholders", () => {
+    const parsed = parseToolResult({
+      content: [
+        { type: "text", text: "shot taken" },
+        { type: "image", data: "aGVsbG8=", mimeType: "image/png" },
+      ],
+    });
+    const { images, result } = splitPiToolResultImages(parsed);
+
+    expect(images).toEqual([{ data: "aGVsbG8=", mimeType: "image/png" }]);
+    expect(result).toEqual({
+      content: [
+        { type: "text", text: "shot taken" },
+        { type: "text", text: "[image]" },
+      ],
+    });
+  });
+
+  test("replaces image-only results with a non-empty placeholder", () => {
+    const parsed = parseToolResult({
+      content: [{ type: "image", data: "aGVsbG8=", mimeType: "image/jpeg" }],
+    });
+    const { images, result } = splitPiToolResultImages(parsed);
+
+    expect(images).toHaveLength(1);
+    expect(extractTextFromToolResult(result)).toBe("[image]");
+  });
+
+  test("passes through string results and results without images", () => {
+    expect(splitPiToolResultImages("plain output")).toEqual({
+      images: [],
+      result: "plain output",
+    });
+    const textOnly = parseToolResult({ content: [{ type: "text", text: "no images" }] });
+    expect(splitPiToolResultImages(textOnly)).toEqual({ images: [], result: textOnly });
+    expect(splitPiToolResultImages(null)).toEqual({ images: [], result: null });
+  });
+
+  test("keeps other fields on the result object", () => {
+    const parsed = parseToolResult({
+      exitCode: 0,
+      content: [{ type: "image", data: "aGVsbG8=" }],
+    });
+    const { result } = splitPiToolResultImages(parsed);
+    expect(result).toMatchObject({ exitCode: 0 });
+  });
+});
+
+test("tool-result images remove nested structured image data while preserving metadata", () => {
+  const data = Buffer.from("nested screenshot bytes").toString("base64");
+  const result = parseToolResult({
+    content: [{ type: "image", data, mimeType: "image/png" }],
+    structuredContent: {
+      content: [{ type: "image", data, mimeType: "image/png", width: 64 }],
+      captureId: "capture-1",
+      read: { type: "image", data, mimeType: "image/png", note: "Read image file" },
+      extra: { data: "keep ordinary data" },
+    },
+  });
+  const split = splitPiToolResultImages(result);
+  const detail = mapToolDetail(parseToolArgs("screenshot", {}), split.result);
+  expect(JSON.stringify(detail)).not.toContain(data);
+  expect(split.images).toEqual([{ data, mimeType: "image/png" }]);
+  expect(split.result).toMatchObject({
+    structuredContent: {
+      content: [{ type: "image", data: "[image]", mimeType: "image/png", width: 64 }],
+      captureId: "capture-1",
+      read: { type: "image", data: "[image]", mimeType: "image/png", note: "Read image file" },
+      extra: { data: "keep ordinary data" },
+    },
+  });
+});
diff --git a/packages/server/src/server/agent/providers/pi/tool-call-mapper.ts b/packages/server/src/server/agent/providers/pi/tool-call-mapper.ts
index 8c18a8fdbf..8fbba690b8 100644
--- a/packages/server/src/server/agent/providers/pi/tool-call-mapper.ts
+++ b/packages/server/src/server/agent/providers/pi/tool-call-mapper.ts
@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import type { ToolCallDetail } from "../../agent-sdk-types.js";
+import type { ProviderImageOutput } from "../provider-image-output.js";
 
 interface BashToolInput {
   command: string;
@@ -52,6 +53,7 @@ interface PiToolResultObject {
   stdout?: string;
   text?: string;
   content?: PiToolResultContent[];
+  structuredContent?: unknown;
   exitCode?: number;
   code?: number;
   details?: PiToolResultDetails;
@@ -67,6 +69,12 @@ interface PiToolResultTextContent {
   text: string;
 }
 
+const PiToolResultImageContentSchema = z.object({
+  type: z.literal("image"),
+  data: z.string().min(1),
+  mimeType: z.string().optional(),
+});
+
 interface PiToolResultUnknownContent {
   type: string;
 }
@@ -236,6 +244,61 @@ export function parseToolResult(rawResult: unknown): PiToolResult {
   return null;
 }
 
+// Pi returns images inside tool-result content as base64 blocks. Left in place they reach the
+// tool-output stringifier, which dumps base64 into the tool output. We pull those blocks out to
+// render them as image markdown and leave a "[image]" placeholder so image-only results still
+// produce non-empty output (mirroring splitClaudeToolResultImages).
+export function splitPiToolResultImages(result: PiToolResult): {
+  images: ProviderImageOutput[];
+  result: PiToolResult;
+} {
+  if (!result || typeof result === "string" || !result.content) {
+    return { images: [], result };
+  }
+  const images: ProviderImageOutput[] = [];
+  let replaced = false;
+  const content = result.content.map((block) => {
+    const image = toPiImageOutput(block);
+    if (image) {
+      images.push(image);
+      replaced = true;
+      return { type: "text", text: "[image]" } satisfies PiToolResultTextContent;
+    }
+    return block;
+  });
+  if (!replaced) {
+    return { images: [], result };
+  }
+  return {
+    images,
+    result: {
+      ...result,
+      content,
+      ...(result.structuredContent === undefined
+        ? {}
+        : { structuredContent: withoutImageData(result.structuredContent) }),
+    },
+  };
+}
+
+function withoutImageData(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(withoutImageData);
+  if (value === null || typeof value !== "object") return value;
+  const image = toPiImageOutput(value);
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [
+      key,
+      image && key === "data" ? "[image]" : withoutImageData(child),
+    ]),
+  );
+}
+
+function toPiImageOutput(block: unknown): ProviderImageOutput | null {
+  const parsed = PiToolResultImageContentSchema.safeParse(block);
+  if (!parsed.success) return null;
+  return { data: parsed.data.data, mimeType: parsed.data.mimeType ?? null };
+}
+
 export function extractTextFromToolResult(result: PiToolResult): string | undefined {
   if (typeof result === "string") {
     return result;
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-image-output.posix.test.ts b/packages/server/src/server/agent/providers/provider-image-output.posix.test.ts
index 1f4da6e04a..5e71bad0bd 100644
--- a/packages/server/src/server/agent/providers/provider-image-output.posix.test.ts
+++ b/packages/server/src/server/agent/providers/provider-image-output.posix.test.ts
@@ -5,8 +5,8 @@ import { describe, expect, test } from "vitest";
 import { materializeProviderImage } from "./provider-image-output.js";
 
 describe.skipIf(process.platform === "win32")("materializeProviderImage", () => {
-  test("writes image attachments under a private temp directory", () => {
-    const materialized = materializeProviderImage({
+  test("writes image attachments under a private temp directory", async () => {
+    const materialized = await materializeProviderImage({
       data: "YWJjMTIz",
       mimeType: "image/png",
     });
diff --git a/packages/server/src/server/agent/providers/provider-image-output.test.ts b/packages/server/src/server/agent/providers/provider-image-output.test.ts
index b4f4784a66..3388edb6d5 100644
--- a/packages/server/src/server/agent/providers/provider-image-output.test.ts
+++ b/packages/server/src/server/agent/providers/provider-image-output.test.ts
@@ -1,10 +1,11 @@
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, rmSync, statSync, readFileSync } from "node:fs";
 import path from "node:path";
 import MarkdownIt from "markdown-it";
 import { projectTimelineRows } from "../timeline-projection.js";
 import { describe, expect, test } from "vitest";
 
 import {
+  MAX_PROVIDER_IMAGE_BYTES,
   isProviderImageMarkdown,
   materializeProviderImage,
   renderProviderImageOutputAsAssistantMarkdown,
@@ -12,8 +13,8 @@ import {
 
 const HASH = "a".repeat(64);
 
-function renderImageMarkdown(imagePath: string): string {
-  const item = renderProviderImageOutputAsAssistantMarkdown({ path: imagePath });
+async function renderImageMarkdown(imagePath: string): Promise<string> {
+  const item = await renderProviderImageOutputAsAssistantMarkdown({ path: imagePath });
   if (!item || item.type !== "assistant_message") {
     throw new Error("Expected provider image output to render as assistant markdown.");
   }
@@ -40,8 +41,8 @@ describe("isProviderImageMarkdown", () => {
     ).toBe(true);
   });
 
-  test("emits Windows file paths as file URIs", () => {
-    const markdown = renderImageMarkdown(
+  test("emits Windows file paths as file URIs", async () => {
+    const markdown = await renderImageMarkdown(
       `C:\\Users\\me\\AppData\\Local\\Temp\\paseo-attachments\\${HASH}.png`,
     );
 
@@ -51,22 +52,24 @@ describe("isProviderImageMarkdown", () => {
     expect(isProviderImageMarkdown(markdown)).toBe(true);
   });
 
-  test("emits POSIX file paths with spaces as valid file URI markdown", () => {
-    const markdown = renderImageMarkdown("/home/user/Projects/Project With Spaces/screenshot.png");
+  test("emits POSIX file paths with spaces as valid file URI markdown", async () => {
+    const markdown = await renderImageMarkdown(
+      "/home/user/Projects/Project With Spaces/screenshot.png",
+    );
 
     expect(markdown).toBe(
       "\n\n![Image](file:///home/user/Projects/Project%20With%20Spaces/screenshot.png)\n\n",
     );
   });
 
-  test("encodes URI-significant characters in POSIX file paths", () => {
-    const markdown = renderImageMarkdown("/tmp/screenshot#1?draft.png");
+  test("encodes URI-significant characters in POSIX file paths", async () => {
+    const markdown = await renderImageMarkdown("/tmp/screenshot#1?draft.png");
 
     expect(markdown).toBe("\n\n![Image](file:///tmp/screenshot%231%3Fdraft.png)\n\n");
   });
 
-  test("preserves double-leading slashes in POSIX file paths", () => {
-    const markdown = renderImageMarkdown("//tmp/screenshot#1.png");
+  test("preserves double-leading slashes in POSIX file paths", async () => {
+    const markdown = await renderImageMarkdown("//tmp/screenshot#1.png");
 
     expect(markdown).toBe("\n\n![Image](file:////tmp/screenshot%231.png)\n\n");
   });
@@ -78,8 +81,8 @@ describe("isProviderImageMarkdown", () => {
       "\\\\?\\UNC\\server\\share\\shot?draft.png",
       "file://server/share/shot%3Fdraft.png",
     ],
-  ])("encodes %s image paths as file URIs", (_label, imagePath, expectedSource) => {
-    expect(renderImageMarkdown(imagePath)).toBe(`\n\n![Image](${expectedSource})\n\n`);
+  ])("encodes %s image paths as file URIs", async (_label, imagePath, expectedSource) => {
+    expect(await renderImageMarkdown(imagePath)).toBe(`\n\n![Image](${expectedSource})\n\n`);
   });
 
   test("rejects user-authored markdown that is not a materialized attachment", () => {
@@ -92,8 +95,8 @@ describe("isProviderImageMarkdown", () => {
 });
 
 describe("materializeProviderImage", () => {
-  test("recreates the private temp directory if the cached directory is removed", () => {
-    const first = materializeProviderImage({
+  test("recreates the private temp directory if the cached directory is removed", async () => {
+    const first = await materializeProviderImage({
       data: "YWJjMTIz",
       mimeType: "image/png",
     });
@@ -102,7 +105,7 @@ describe("materializeProviderImage", () => {
 
     rmSync(firstDir, { recursive: true, force: true });
 
-    const second = materializeProviderImage({
+    const second = await materializeProviderImage({
       data: "ZGVmNDU2",
       mimeType: "image/png",
     });
@@ -117,8 +120,8 @@ describe("materializeProviderImage", () => {
 });
 
 describe("provider image paragraph boundaries", () => {
-  test.each(["", "\n"])("keeps image outputs separate from prose ending in %j", (ending) => {
-    const image = renderProviderImageOutputAsAssistantMarkdown({
+  test.each(["", "\n"])("keeps image outputs separate from prose ending in %j", async (ending) => {
+    const image = await renderProviderImageOutputAsAssistantMarkdown({
       url: "https://example.com/chart.png",
     });
     if (!image) throw new Error("Expected image output");
@@ -152,10 +155,10 @@ describe("provider image paragraph boundaries", () => {
   });
 });
 
-test("materialized image output retains paragraph boundaries and attachment recognition", () => {
-  const item = renderProviderImageOutputAsAssistantMarkdown(
+test("materialized image output retains paragraph boundaries and attachment recognition", async () => {
+  const item = await renderProviderImageOutputAsAssistantMarkdown(
     { data: "YWJjMTIz", mimeType: "image/png" },
-    { materialize: () => ({ path: `/tmp/paseo-attachments/${HASH}.png` }) },
+    { materialize: async () => ({ path: `/tmp/paseo-attachments/${HASH}.png` }) },
   );
   expect(item).toEqual({
     type: "assistant_message",
@@ -164,3 +167,83 @@ test("materialized image output retains paragraph boundaries and attachment reco
   if (!item || item.type !== "assistant_message") throw new Error("Expected image output");
   expect(isProviderImageMarkdown(item.text)).toBe(true);
 });
+
+test("repeated content is reused without rewriting the attachment", async () => {
+  const image = {
+    data: Buffer.from("dedupe regression").toString("base64"),
+    mimeType: "image/png",
+  };
+  const first = await materializeProviderImage(image);
+  const before = statSync(first.path, { bigint: true });
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  const second = await materializeProviderImage(image);
+  expect(second.path).toBe(first.path);
+  expect(statSync(second.path, { bigint: true }).mtimeNs).toBe(before.mtimeNs);
+});
+
+test("64 MiB materialization leaves the event loop responsive and preserves bytes", async () => {
+  const bytes = Buffer.alloc(64 * 1024 * 1024, 37);
+  const data = bytes.toString("base64");
+  // Main-thread CPU time between ticks bounds the decode and hash work done on the loop;
+  // wall-clock gaps on shared CI runners also count preemption and timer granularity.
+  // File writes stay on fs/promises, so they never block the loop.
+  const threadCpuMs = () => {
+    const { user, system } = process.threadCpuUsage();
+    return (user + system) / 1000;
+  };
+  let previous = threadCpuMs();
+  let longest = 0;
+  const probe = setInterval(() => {
+    const now = threadCpuMs();
+    longest = Math.max(longest, now - previous);
+    previous = now;
+  }, 1);
+  try {
+    const result = await materializeProviderImage({ data, mimeType: "image/png" });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    console.log(`64 MiB attachment longest blocking stretch: ${longest.toFixed(2)} ms CPU`);
+    expect(longest).toBeLessThan(50);
+    expect(readFileSync(result.path).equals(bytes)).toBe(true);
+    rmSync(result.path, { force: true });
+  } finally {
+    clearInterval(probe);
+  }
+});
+
+test("preserves base64 decoding across whitespace and chunk boundaries", async () => {
+  const bytes = Buffer.alloc(512 * 1024, 123);
+  const base64 = bytes.toString("base64");
+  const data = base64.match(/.{1,77}/g)!.join("\n");
+  const result = await materializeProviderImage({ data, mimeType: "image/png" });
+  expect(readFileSync(result.path).equals(bytes)).toBe(true);
+});
+
+test("rejects oversized materialization before work and leaves the queue usable", async () => {
+  const data = "A".repeat(Math.ceil(MAX_PROVIDER_IMAGE_BYTES / 3) * 4 + 260);
+  await expect(materializeProviderImage({ data, mimeType: "image/png" })).rejects.toThrow(
+    "exceeds",
+  );
+  const omitted = await renderProviderImageOutputAsAssistantMarkdown(
+    { data, mimeType: "image/png" },
+    { materialize: materializeProviderImage },
+  );
+  expect(omitted).toEqual({
+    type: "assistant_message",
+    text: "Image output was omitted because it was not available as a file path or URL.",
+  });
+  const image = await materializeProviderImage({ data: "YWJjMTIz", mimeType: "image/png" });
+  expect(readFileSync(image.path).toString()).toBe("abc123");
+});
+
+test("simultaneous requests for the same content share the published file", async () => {
+  const image = {
+    data: Buffer.from("concurrent dedupe fixture").toString("base64"),
+    mimeType: "image/png",
+  };
+  const results = await Promise.all([
+    materializeProviderImage(image),
+    materializeProviderImage(image),
+  ]);
+  expect(results[0]).toEqual(results[1]);
+  expect(readFileSync(results[0].path).toString()).toBe("concurrent dedupe fixture");
+});
diff --git a/packages/server/src/server/agent/providers/provider-image-output.ts b/packages/server/src/server/agent/providers/provider-image-output.ts
index ba8843918b..0cd0787c1e 100644
--- a/packages/server/src/server/agent/providers/provider-image-output.ts
+++ b/packages/server/src/server/agent/providers/provider-image-output.ts
@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import * as fsSync from "node:fs";
+import * as fs from "node:fs/promises";
+import { setImmediate } from "node:timers/promises";
 import os from "node:os";
 import path from "node:path";
 
@@ -23,32 +24,26 @@ const PRIVATE_ATTACHMENT_DIR_MODE = 0o700;
 const MATERIALIZED_IMAGE_FILE_MODE = 0o600;
 
 let materializedImageAttachmentDir: string | null = null;
+// Serialize materializations: one decoder and one file operation at a time, including
+// concurrent history replay and live turns. A rejected operation must not poison the queue.
+let pendingMaterialization: Promise<unknown> = Promise.resolve();
 
-function canReuseMaterializedImageAttachmentDir(dir: string): boolean {
-  try {
-    const stats = fsSync.lstatSync(dir);
-    if (!stats.isDirectory()) {
-      return false;
+async function getMaterializedImageAttachmentDir(): Promise<string> {
+  if (materializedImageAttachmentDir) {
+    try {
+      const stats = await fs.lstat(materializedImageAttachmentDir);
+      if (stats.isDirectory()) {
+        await fs.chmod(materializedImageAttachmentDir, PRIVATE_ATTACHMENT_DIR_MODE);
+        return materializedImageAttachmentDir;
+      }
+    } catch {
+      /* Temp storage may have been removed between turns. */
     }
-    fsSync.chmodSync(dir, PRIVATE_ATTACHMENT_DIR_MODE);
-    return true;
-  } catch {
-    return false;
   }
-}
-
-function getMaterializedImageAttachmentDir(): string {
-  if (
-    materializedImageAttachmentDir &&
-    canReuseMaterializedImageAttachmentDir(materializedImageAttachmentDir)
-  ) {
-    return materializedImageAttachmentDir;
-  }
-
-  materializedImageAttachmentDir = fsSync.mkdtempSync(
+  materializedImageAttachmentDir = await fs.mkdtemp(
     path.join(os.tmpdir(), PROVIDER_IMAGE_ATTACHMENT_DIR_PREFIX),
   );
-  fsSync.chmodSync(materializedImageAttachmentDir, PRIVATE_ATTACHMENT_DIR_MODE);
+  await fs.chmod(materializedImageAttachmentDir, PRIVATE_ATTACHMENT_DIR_MODE);
   return materializedImageAttachmentDir;
 }
 
@@ -71,32 +66,92 @@ function getImageExtension(mimeType: string): string {
   }
 }
 
-function normalizeImageData(mimeType: string, data: string): { mimeType: string; data: string } {
-  if (data.startsWith("data:")) {
-    const match = data.match(/^data:([^;]+);base64,(.*)$/);
-    if (match) {
-      return { mimeType: match[1], data: match[2] };
-    }
-  }
-  return { mimeType, data };
-}
+// 128 MiB admits the measured 64 MiB fixture with headroom while bounding disk
+// and decoding per image. This is materialization admission, not a wire schema limit.
+export const MAX_PROVIDER_IMAGE_BYTES = 128 * 1024 * 1024;
+const BASE64_CHUNK_CHARACTERS = 256 * 1024; // Multiple of four; decode units stay aligned.
 
-// Filenames are a content hash of the bytes so re-materializing the same image
-// within a process reuses the existing temp file instead of leaking a fresh one
-// for repeated image blocks or history replay.
 export function materializeProviderImage(image: {
   data: string;
   mimeType: string | null;
-}): MaterializedProviderImage {
-  const attachmentsDir = getMaterializedImageAttachmentDir();
-  const normalized = normalizeImageData(image.mimeType ?? "image/png", image.data);
-  const bytes = Buffer.from(normalized.data, "base64");
-  const extension = getImageExtension(normalized.mimeType);
-  const hash = createHash("sha256").update(bytes).digest("hex");
-  const filePath = path.join(attachmentsDir, `${hash}.${extension}`);
-  fsSync.writeFileSync(filePath, bytes, { mode: MATERIALIZED_IMAGE_FILE_MODE });
-  fsSync.chmodSync(filePath, MATERIALIZED_IMAGE_FILE_MODE);
-  return { path: filePath };
+}): Promise<MaterializedProviderImage> {
+  const result = pendingMaterialization.then(() => materializeImage(image));
+  pendingMaterialization = result.catch(() => {});
+  return result;
+}
+
+async function materializeImage(image: {
+  data: string;
+  mimeType: string | null;
+}): Promise<MaterializedProviderImage> {
+  const maxEncodedCharacters = Math.ceil(MAX_PROVIDER_IMAGE_BYTES / 3) * 4;
+  // Check length before inspecting/copying the payload, including a bounded data URI header.
+  if (image.data.length > maxEncodedCharacters + 256) {
+    throw new Error(`Image attachment exceeds ${MAX_PROVIDER_IMAGE_BYTES} bytes`);
+  }
+  let data = image.data;
+  let mimeType = image.mimeType ?? "image/png";
+  if (data.startsWith("data:")) {
+    const separator = data.indexOf(";base64,");
+    if (separator >= 0 && separator < 256) {
+      mimeType = data.slice(5, separator);
+      data = data.slice(separator + 8);
+    }
+  }
+  if (data.length > maxEncodedCharacters) {
+    throw new Error(`Image attachment exceeds ${MAX_PROVIDER_IMAGE_BYTES} bytes`);
+  }
+  const hash = createHash("sha256");
+  for await (const bytes of decodeImage(data)) hash.update(bytes);
+  const dir = await getMaterializedImageAttachmentDir();
+  const filePath = path.join(dir, `${hash.digest("hex")}.${getImageExtension(mimeType)}`);
+  try {
+    await fs.stat(filePath);
+    return { path: filePath };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+
+  const staging = await fs.mkdtemp(path.join(dir, ".pending-"));
+  const stagingPath = path.join(staging, "image");
+  try {
+    await fs.chmod(staging, PRIVATE_ATTACHMENT_DIR_MODE);
+    const file = await fs.open(stagingPath, "wx", MATERIALIZED_IMAGE_FILE_MODE);
+    try {
+      await file.chmod(MATERIALIZED_IMAGE_FILE_MODE);
+      // Decode again only for a new hash. This bounds retained memory to one chunk
+      // and performs no writes at all for repeated content, including history replay.
+      for await (const bytes of decodeImage(data)) await file.writeFile(bytes);
+    } finally {
+      await file.close();
+    }
+    await fs.rename(stagingPath, filePath);
+    return { path: filePath };
+  } finally {
+    await fs.rm(staging, { recursive: true, force: true });
+  }
+}
+
+async function* decodeImage(data: string): AsyncGenerator<Buffer> {
+  let carry = "";
+  let decodedBytes = 0;
+  for (let offset = 0; offset < data.length; offset += BASE64_CHUNK_CHARACTERS) {
+    // Buffer.from ignores non-base64 characters. Carry incomplete quartets so
+    // line-wrapped payloads decode identically across chunk boundaries.
+    const chunk =
+      carry +
+      data.slice(offset, offset + BASE64_CHUNK_CHARACTERS).replace(/[^A-Za-z0-9+/_=-]/g, "");
+    const finalChunk = offset + BASE64_CHUNK_CHARACTERS >= data.length || chunk.includes("=");
+    const end = finalChunk ? chunk.length : chunk.length - (chunk.length % 4);
+    const bytes = Buffer.from(chunk.slice(0, end), "base64");
+    carry = chunk.slice(end);
+    decodedBytes += bytes.length;
+    if (decodedBytes > MAX_PROVIDER_IMAGE_BYTES)
+      throw new Error("Image attachment exceeds size limit");
+    yield bytes;
+    await setImmediate();
+    if (finalChunk) break;
+  }
 }
 
 // Recognizes markdown rendered for a materialized provider image: its source is a content-hashed
@@ -112,7 +167,10 @@ export function isProviderImageMarkdown(text: string): boolean {
 }
 
 interface RenderProviderImageOutputOptions {
-  materialize?: (image: { data: string; mimeType: string | null }) => MaterializedProviderImage;
+  materialize?: (image: {
+    data: string;
+    mimeType: string | null;
+  }) => Promise<MaterializedProviderImage>;
 }
 
 function nonEmptyString(value: string | null | undefined): string | null {
@@ -169,10 +227,10 @@ function escapeMarkdownImageSource(value: string): string {
   return markdownImageSource(value).replace(/\\/g, "\\\\").replace(/\)/g, "\\)");
 }
 
-export function renderProviderImageOutputAsAssistantMarkdown(
+export async function renderProviderImageOutputAsAssistantMarkdown(
   image: ProviderImageOutput,
   options: RenderProviderImageOutputOptions = {},
-): AgentTimelineItem | null {
+): Promise<AgentTimelineItem | null> {
   const source = nonEmptyString(image.path) ?? nonEmptyString(image.url);
   if (source && !isDataImageSource(source)) {
     const altText = escapeMarkdownImageAlt(nonEmptyString(image.altText) ?? "Image");
@@ -191,7 +249,7 @@ export function renderProviderImageOutputAsAssistantMarkdown(
   let materialized: MaterializedProviderImage | null = null;
   try {
     materialized = options.materialize
-      ? options.materialize({
+      ? await options.materialize({
           data,
           mimeType: nonEmptyString(image.mimeType),
         })
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/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
new file mode 100644
index 0000000000..77adf359c4
--- /dev/null
+++ b/packages/server/src/server/agent/restart-recovery/index.test.ts
@@ -0,0 +1,105 @@
+import { expect, test } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AgentStorage, parseStoredAgentRecord } from "../agent-storage.js";
+import { createTestLogger } from "../../../test-utils/test-logger.js";
+import { createRestartRecovery } from "./index.js";
+
+test("recovery saves intent before normalization, clears before dispatch, and resumes each agent independently", async () => {
+  const root = await mkdtemp(join(tmpdir(), "restart-recovery-"));
+  try {
+    const storage = new AgentStorage(root, createTestLogger());
+    for (const [id, lastStatus] of [
+      ["broken", "running"],
+      ["stuck", "running"],
+      ["working", "running"],
+      ["idle", "idle"],
+      ["initializing", "initializing"],
+    ] as const) {
+      await storage.upsert(
+        parseStoredAgentRecord({
+          id,
+          lastStatus,
+          provider: "codex",
+          cwd: root,
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        }),
+      );
+    }
+    const dispatched: string[] = [];
+    const recovery = createRestartRecovery({
+      storage,
+      settings: () => ({ enabled: true, prompt: "Continue verbatim.\n" }),
+      eligible: async () => true,
+      dispatch: async (id, prompt) => {
+        expect((await storage.get(id))?.resumeOnStartup).toBe(false);
+        if (id === "broken") throw new Error("unavailable");
+        if (id === "stuck") return new Promise(() => {});
+        dispatched.push(id + prompt);
+      },
+      report: () => {},
+    });
+    await recovery.prepareStartup();
+    expect((await storage.get("working"))?.resumeOnStartup).toBe(true);
+    expect((await storage.get("working"))?.lastStatus).toBe("closed");
+    recovery.resumePending();
+    const running = new AbortController().signal;
+    await recovery.waitForResume("broken", running);
+    await recovery.waitForResume("working", running);
+    await recovery.waitForResume("idle", running);
+    expect(dispatched).toEqual(["workingContinue verbatim.\n"]);
+    const stopped = new AbortController();
+    stopped.abort();
+    await expect(recovery.waitForResume("stuck", stopped.signal)).rejects.toBeDefined();
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("opt-out consumes pending recovery and excludes archived, private, owned and archived-workspace agents", async () => {
+  const root = await mkdtemp(join(tmpdir(), "restart-recovery-"));
+  try {
+    const storage = new AgentStorage(root, createTestLogger());
+    for (const extra of [
+      { id: "running" },
+      { id: "archived", archivedAt: "today" },
+      { id: "private", internal: true },
+      { id: "owned", owner: { kind: "daemon", daemonId: "hub", executionId: "run" } },
+      { id: "workspace", workspaceId: "archived" },
+    ]) {
+      await storage.upsert(
+        parseStoredAgentRecord({
+          lastStatus: "running",
+          provider: "codex",
+          cwd: root,
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+          ...extra,
+        }),
+      );
+    }
+    let enabled = true;
+    const dispatched: string[] = [];
+    const recovery = createRestartRecovery({
+      storage,
+      settings: () => ({ enabled, prompt: "Resume working." }),
+      eligible: async (record) => record.workspaceId !== "archived",
+      dispatch: async (id) => {
+        dispatched.push(id);
+      },
+      report: () => {},
+    });
+    await recovery.captureRunningAgents();
+    expect((await storage.get("running"))?.resumeOnStartup).toBe(true);
+    enabled = false;
+    await recovery.prepareStartup();
+    enabled = true;
+    recovery.resumePending();
+    expect(dispatched).toEqual([]);
+    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
new file mode 100644
index 0000000000..fe558b0219
--- /dev/null
+++ b/packages/server/src/server/agent/restart-recovery/index.ts
@@ -0,0 +1,83 @@
+import type { AgentStorage, StoredAgentRecord } from "../agent-storage.js";
+interface Dependencies {
+  storage: AgentStorage;
+  settings(): { enabled: boolean; prompt: string };
+  eligible(record: StoredAgentRecord): Promise<boolean>;
+  dispatch(agentId: string, prompt: string): Promise<unknown>;
+  report(agentId: string, error: unknown): void;
+}
+export function createRestartRecovery(deps: Dependencies) {
+  // Candidates are chosen at startup; each settles once its resume was sent or abandoned.
+  const resuming = new Map<string, { promise: Promise<void>; resolve(): void }>();
+  const eligible = async (record: StoredAgentRecord) =>
+    !record.archivedAt && !record.internal && !record.owner && (await deps.eligible(record));
+  async function resume(agentId: string) {
+    const record = await deps.storage.get(agentId);
+    if (!record?.resumeOnStartup) return;
+    await deps.storage.upsert({ ...record, resumeOnStartup: false });
+    if (!deps.settings().enabled || !(await eligible(record))) return;
+    await deps.dispatch(agentId, deps.settings().prompt);
+  }
+  return {
+    /** Choose candidates before anything else reads or repairs persisted running status. */
+    async prepareStartup() {
+      // 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") &&
+          (await eligible(record));
+        await deps.storage.upsert({
+          ...record,
+          resumeOnStartup: pending,
+          lastStatus:
+            record.lastStatus === "running" || record.lastStatus === "initializing"
+              ? "closed"
+              : record.lastStatus,
+        });
+        if (pending) {
+          let resolve!: () => void;
+          const promise = new Promise<void>((settle) => {
+            resolve = settle;
+          });
+          resuming.set(record.id, { promise, resolve });
+        }
+      }
+    },
+    async captureRunningAgents() {
+      await deps.storage.flush();
+      // 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 });
+      }
+    },
+    /** Resume every candidate in the background; a slow provider holds back only its agent. */
+    resumePending() {
+      for (const [agentId, settled] of resuming) {
+        void resume(agentId)
+          .catch((error) => deps.report(agentId, error))
+          .finally(() => {
+            resuming.delete(agentId);
+            settled.resolve();
+          });
+      }
+    },
+    /** Wait until this agent's resume was sent or abandoned. Others return at once. */
+    async waitForResume(agentId: string, signal: AbortSignal) {
+      const settled = resuming.get(agentId);
+      if (!settled) return;
+      let abort!: () => void;
+      const aborted = new Promise<never>((_resolve, reject) => {
+        abort = () => reject(signal.reason);
+        if (signal.aborted) abort();
+        else signal.addEventListener("abort", abort, { once: true });
+      });
+      try {
+        await Promise.race([settled.promise, aborted]);
+      } finally {
+        signal.removeEventListener("abort", abort);
+      }
+    },
+  };
+}
diff --git a/packages/server/src/server/agent/rewind/rewind.test.ts b/packages/server/src/server/agent/rewind/rewind.test.ts
index df5c242251..73d98e8741 100644
--- a/packages/server/src/server/agent/rewind/rewind.test.ts
+++ b/packages/server/src/server/agent/rewind/rewind.test.ts
@@ -162,7 +162,7 @@ describe("AgentManager rewind", () => {
     });
   });
 
-  test("blocks new prompts until the rehydrate epoch broadcasts", async () => {
+  test("blocks new prompts immediately and until the rehydrate epoch broadcasts", async () => {
     const historyGate = new RewindHistoryGate();
     historyGate.hold();
     const { manager, agentId } = await createRewindHarness({ historyGate });
diff --git a/packages/server/src/server/agent/runtime-mcp-config.ts b/packages/server/src/server/agent/runtime-mcp-config.ts
index af04e8021c..711638ce2f 100644
--- a/packages/server/src/server/agent/runtime-mcp-config.ts
+++ b/packages/server/src/server/agent/runtime-mcp-config.ts
@@ -1,6 +1,6 @@
 import type { AgentSessionConfig, McpServerConfig } from "./agent-sdk-types.js";
 
-const PASEO_MCP_SERVER_NAME = "paseo";
+export const PASEO_MCP_SERVER_NAME = "paseo";
 const PASEO_MCP_PATHNAME = "/mcp/agents";
 
 export function stripInternalPaseoMcpServer(config: AgentSessionConfig): AgentSessionConfig {
diff --git a/packages/server/src/server/agent/test-utils/plugin-stream-memory.ts b/packages/server/src/server/agent/test-utils/plugin-stream-memory.ts
new file mode 100644
index 0000000000..948202bae2
--- /dev/null
+++ b/packages/server/src/server/agent/test-utils/plugin-stream-memory.ts
@@ -0,0 +1,176 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import type { ProviderEvent, ProviderRegistration } from "@getpaseo/plugin/server/provider";
+import pino from "pino";
+import { PluginAgentClientRegistry } from "../plugin-provider.js";
+import { InMemoryAgentTimelineStore } from "../agent-timeline-store.js";
+import { AgentManager } from "../agent-manager.js";
+import { AgentStorage } from "../agent-storage.js";
+import { buildProviderRegistry } from "../provider-registry.js";
+
+if (!global.gc) throw new Error("Run with --expose-gc");
+const logger = pino({ level: "silent" });
+const plugins = new PluginAgentClientRegistry(logger);
+const root = await mkdtemp(join(tmpdir(), "plugin-stream-memory-"));
+const emitters: Array<(event: ProviderEvent) => void> = [];
+const ids: string[] = [];
+const registrations: ProviderRegistration[] = Array.from({ length: 3 }, (_, index) => ({
+  id: `memory-${index}`,
+  label: "Memory fixture",
+  async connect() {
+    let listener: (event: ProviderEvent) => void = () => {};
+    const capabilities = ["prompt.message", "session.persistence"] as const;
+    return {
+      version: 1,
+      capabilities,
+      onEvent(callback) {
+        listener = callback;
+        // Plugin IPC delivers independent JSON strings, rather than shared ropes.
+        emitters[index] = (event) => listener(JSON.parse(JSON.stringify(event)));
+        return () => {
+          listener = () => {};
+        };
+      },
+      async send(input) {
+        if (input.type === "session.open") {
+          ids[index] = input.sessionId;
+          listener({
+            type: "session.opened",
+            requestId: input.requestId,
+            sessionId: input.sessionId,
+            cwd: "/tmp",
+            capabilities,
+            restoration: "core",
+            persistence: { version: 1, data: { index } },
+          });
+          listener({
+            type: "session.ready",
+            requestId: input.requestId,
+            sessionId: input.sessionId,
+          });
+        } else if (input.type === "catalog") {
+          listener({
+            type: "catalog",
+            requestId: input.requestId,
+            catalog: { models: [], modes: [], thinkingOptions: [] },
+          });
+        } else if (input.type === "session.close") {
+          listener({ type: "session.closed", sessionId: input.sessionId });
+          listener({ type: "request.completed", requestId: input.requestId });
+        }
+      },
+      async close() {},
+    };
+  },
+}));
+plugins.replace(registrations);
+const store = new InMemoryAgentTimelineStore();
+const manager = new AgentManager({
+  clients: plugins.clients(),
+  providerDefinitions: buildProviderRegistry(logger, { pluginProviders: plugins.definitions() }),
+  registry: new AgentStorage(root, logger),
+  timelineStore: store,
+  logger,
+});
+const agents = await Promise.all(
+  Object.keys(plugins.clients()).map((provider) =>
+    manager.createAgent({ provider, cwd: root }, undefined, {}),
+  ),
+);
+const sessions = agents.map((agent) => agent.session!);
+agents.forEach((_agent, index) => {
+  emitters[index]!({
+    type: "session.opened",
+    sessionId: `child-${index}`,
+    parentSessionId: ids[index]!,
+    capabilities: [],
+    restoration: "parent",
+    cwd: root,
+  });
+});
+global.gc();
+const before = process.memoryUsage().heapUsed;
+const steps = 4;
+const chunks = 200;
+const expected = new Map<string, string>();
+for (let step = 0; step < steps; step++) {
+  for (let index = 0; index < sessions.length; index++) {
+    const text = `${index}:${step}:` + "推理".repeat(15000) + "a\uD83D\uDE00b";
+    expected.set(`${index}:${step}`, text);
+    for (let chunk = 1; chunk <= chunks; chunk++) {
+      for (const sessionId of [ids[index]!, `child-${index}`]) {
+        emitters[index]!({
+          type: "timeline.item",
+          sessionId,
+          item: {
+            type: "reasoning",
+            id: `reason-${step}`,
+            text: text.slice(0, Math.ceil((chunk * text.length) / chunks)),
+          },
+        });
+      }
+    }
+    emitters[index]!({
+      type: "timeline.item",
+      sessionId: ids[index]!,
+      item: {
+        type: "tool_call",
+        id: `tool-${step}`,
+        callId: `tool-${step}`,
+        name: "read",
+        status: "completed",
+        error: null,
+        detail: { type: "unknown", input: null, output: "输出".repeat(16000) },
+      },
+    });
+    emitters[index]!({
+      type: "timeline.item",
+      sessionId: `child-${index}`,
+      item: {
+        type: "assistant_message",
+        id: `answer-${step}`,
+        text: "Child step complete.",
+      },
+    });
+  }
+  // Drain the manager's event queue; terminal tool states flush its real coalescer.
+  await delay(80);
+}
+global.gc();
+const retained = process.memoryUsage().heapUsed - before;
+assert(retained < 24 * 1024 * 1024, `Retained heap exceeded 24 MiB: ${retained} bytes`);
+for (let index = 0; index < sessions.length; index++) {
+  const items = store.getItems(agents[index]!.id);
+  assert.equal(items.length, steps * 2);
+  for (let step = 0; step < steps; step++) {
+    const item = items[step * 2]!;
+    assert.equal(item.type === "reasoning" && item.text, expected.get(`${index}:${step}`));
+  }
+  const children = manager.listProviderSubagents(agents[index]!.id);
+  assert.equal(children.length, 1);
+  let rootItems = 0;
+  let childItems = 0;
+  for await (const event of sessions[index]!.streamHistory()) {
+    if (event.type === "timeline") rootItems++;
+    if (event.type === "provider_subagent" && event.event.type === "timeline") childItems++;
+  }
+  assert.equal(rootItems, steps * 2);
+  assert.equal(childItems, steps * 2);
+  await manager.archiveAgent(agents[index]!.id);
+  assert.equal(store.has(agents[index]!.id), false);
+  assert.equal(
+    manager.listAgents().some((agent) => agent.id === agents[index]!.id),
+    false,
+  );
+}
+await plugins.shutdown();
+await manager.flushForShutdown();
+await rm(root, { recursive: true, force: true });
+global.gc();
+const closed = process.memoryUsage().heapUsed - before;
+// Keep closed session references alive, as callers can retain them after archive.
+assert.equal(sessions.length, 3);
+process.stdout.write(JSON.stringify({ retained, closed }));
diff --git a/packages/server/src/server/agent/test-utils/timeline-page-reference.ts b/packages/server/src/server/agent/test-utils/timeline-page-reference.ts
new file mode 100644
index 0000000000..b3a51f22e5
--- /dev/null
+++ b/packages/server/src/server/agent/test-utils/timeline-page-reference.ts
@@ -0,0 +1,249 @@
+// Frozen pre-index page selection: differential oracle for retained projection tests.
+import type { AgentTimelineRow } from "../agent-timeline-store-types.js";
+import {
+  TimelineProjection,
+  projectTimelineRows,
+  type TimelineProjectionEntry,
+  type ProjectedTimelineRow,
+  type TimelineLimitDirection,
+  type ProjectedTimelinePageSelection,
+} from "../timeline-projection.js";
+
+function makeCanonicalEntries(rows: readonly AgentTimelineRow[]): TimelineProjectionEntry[] {
+  return rows.map((row) => {
+    if ("seqStart" in row) return { ...(row as ProjectedTimelineRow) };
+    return {
+      item: row.item,
+      timestamp: row.timestamp,
+      ...(row.turnId ? { turnId: row.turnId } : {}),
+      ...(row.providerMessageId ? { providerMessageId: row.providerMessageId } : {}),
+      seqStart: row.seq,
+      seqEnd: row.seq,
+      sourceSeqRanges: [{ startSeq: row.seq, endSeq: row.seq }],
+      collapsed: [],
+    };
+  });
+}
+
+function getTimelineBounds(
+  rows: readonly AgentTimelineRow[],
+): { minSeq: number; maxSeq: number } | null {
+  const first = rows[0];
+  const last = rows[rows.length - 1];
+  if (!first || !last) {
+    return null;
+  }
+  const entries = makeCanonicalEntries(rows);
+  return {
+    minSeq: entries.reduce((min, e) => Math.min(min, e.seqStart), Infinity),
+    maxSeq: entries.reduce((max, e) => Math.max(max, e.seqEnd), 0),
+  };
+}
+
+function firstSourceSeqInRange(
+  entry: TimelineProjectionEntry,
+  startSeq: number,
+  endSeq: number,
+): number | null {
+  for (const range of entry.sourceSeqRanges) {
+    const firstSeq = Math.max(range.startSeq, startSeq);
+    if (firstSeq <= Math.min(range.endSeq, endSeq)) return firstSeq;
+  }
+  return null;
+}
+
+interface ProjectedEntryCandidate {
+  entry: TimelineProjectionEntry;
+  index: number;
+  firstSourceSeq: number;
+}
+
+function selectProjectedEntriesAfter(input: {
+  entries: readonly TimelineProjectionEntry[];
+  startSeq: number;
+  maxSeq: number;
+  limit: number;
+}): { entries: TimelineProjectionEntry[]; endSeq: number | null } {
+  const eligible = input.entries
+    .map((entry, index) => ({
+      entry,
+      index,
+      firstSourceSeq: firstSourceSeqInRange(entry, input.startSeq, input.maxSeq),
+    }))
+    .filter((candidate): candidate is ProjectedEntryCandidate => candidate.firstSourceSeq !== null)
+    .sort((left, right) => left.firstSourceSeq - right.firstSourceSeq || left.index - right.index);
+  const selected = input.limit === 0 ? eligible : eligible.slice(0, input.limit);
+  const selectedEntries = selected
+    .sort((left, right) => left.index - right.index)
+    .map((candidate) => candidate.entry);
+  if (selectedEntries.length === 0) return { entries: [], endSeq: null };
+
+  const selectedRanges = selectedEntries
+    .flatMap((entry) => entry.sourceSeqRanges)
+    .sort((left, right) => left.startSeq - right.startSeq || left.endSeq - right.endSeq);
+  // Wide projected entries can include future, discontiguous source ranges. The
+  // page cursor advances only through source rows covered without a gap.
+  let endSeq = input.startSeq - 1;
+  for (const range of selectedRanges) {
+    if (range.endSeq <= endSeq) continue;
+    if (range.startSeq > endSeq + 1) break;
+    endSeq = Math.min(range.endSeq, input.maxSeq);
+  }
+
+  return {
+    entries: selectedEntries,
+    endSeq: endSeq >= input.startSeq ? endSeq : null,
+  };
+}
+
+function selectProjectedEntriesBefore(input: {
+  entries: readonly TimelineProjectionEntry[];
+  endSeq: number;
+  limit: number;
+}): { entries: TimelineProjectionEntry[]; startSeq: number | null; hasOlder: boolean } {
+  // Older history follows projected display order. Lifecycle updates can move an
+  // entry's seqEnd without moving its display anchor, so seqStart keeps the full
+  // projected item on exactly one backward page.
+  const eligible = input.entries.filter((entry) => entry.seqStart <= input.endSeq);
+  const selected =
+    input.limit === 0 || input.limit >= eligible.length
+      ? eligible
+      : eligible.slice(eligible.length - input.limit);
+
+  return {
+    entries: selected,
+    startSeq: selected[0]?.seqStart ?? null,
+    hasOlder: selected.length < eligible.length,
+  };
+}
+
+function selectProjectedEntriesTail(
+  projectedAll: TimelineProjectionEntry[],
+  limit: number,
+  bounds: { minSeq: number; maxSeq: number },
+): ProjectedTimelinePageSelection {
+  let start = limit === 0 ? 0 : Math.max(0, projectedAll.length - limit);
+  // Include earlier display anchors with updates in the selected source window,
+  // so a tail certifies contiguous coverage even with interleaved tool updates.
+  for (let i = start - 1; i >= 0; i--) {
+    if (projectedAll[i].seqEnd >= projectedAll[start].seqStart) start = i;
+  }
+  const selected = projectedAll.slice(start);
+  return {
+    entries: selected,
+    startSeq: selected[0]?.seqStart ?? null,
+    endSeq: bounds.maxSeq,
+    hasOlder: start > 0,
+    hasNewer: false,
+  };
+}
+
+export function selectReferenceProjectedTimelinePage(input: {
+  rows: readonly AgentTimelineRow[];
+  bounds?: { minSeq: number; maxSeq: number };
+  direction: TimelineLimitDirection;
+  cursorSeq?: number;
+  limit?: number;
+}): ProjectedTimelinePageSelection {
+  const limit = input.limit === undefined ? 0 : Math.max(0, Math.floor(input.limit));
+  const bounds = input.bounds ?? getTimelineBounds(input.rows);
+  const projectedAll = projectTimelineRows({ rows: input.rows, mode: "projected" });
+  if (!bounds) {
+    return {
+      entries: [],
+      startSeq: null,
+      endSeq: null,
+      hasOlder: false,
+      hasNewer: false,
+    };
+  }
+
+  if (projectedAll.length === 0) {
+    if (input.direction === "after") {
+      const cursorSeq = input.cursorSeq ?? bounds.minSeq - 1;
+      return {
+        entries: [],
+        startSeq: null,
+        endSeq: null,
+        hasOlder: cursorSeq >= bounds.minSeq,
+        hasNewer: cursorSeq < bounds.maxSeq,
+      };
+    }
+    if (input.direction === "before") {
+      const cursorSeq = input.cursorSeq ?? bounds.maxSeq + 1;
+      return {
+        entries: [],
+        startSeq: null,
+        endSeq: null,
+        hasOlder: cursorSeq > bounds.minSeq,
+        hasNewer: cursorSeq <= bounds.maxSeq,
+      };
+    }
+    return {
+      entries: [],
+      startSeq: null,
+      endSeq: null,
+      hasOlder: false,
+      hasNewer: false,
+    };
+  }
+
+  if (input.direction === "tail") {
+    return selectProjectedEntriesTail(projectedAll, limit, bounds);
+  }
+
+  if (input.direction === "after") {
+    const cursorSeq = input.cursorSeq ?? bounds.minSeq - 1;
+    const startSeq = Math.max(bounds.minSeq, cursorSeq + 1);
+    const selected = selectProjectedEntriesAfter({
+      entries: projectedAll,
+      startSeq,
+      maxSeq: bounds.maxSeq,
+      limit,
+    });
+    return {
+      entries: selected.entries,
+      startSeq: selected.endSeq === null ? null : startSeq,
+      endSeq: selected.endSeq,
+      hasOlder: startSeq > bounds.minSeq,
+      hasNewer: selected.endSeq !== null && selected.endSeq < bounds.maxSeq,
+    };
+  }
+
+  const cursorSeq = input.cursorSeq ?? bounds.maxSeq + 1;
+  const endSeq = Math.min(bounds.maxSeq, cursorSeq - 1);
+  if (endSeq < bounds.minSeq) {
+    return {
+      entries: [],
+      startSeq: null,
+      endSeq: null,
+      hasOlder: false,
+      hasNewer: endSeq < bounds.maxSeq,
+    };
+  }
+
+  const selected = selectProjectedEntriesBefore({ entries: projectedAll, endSeq, limit });
+  return {
+    entries: selected.entries,
+    startSeq: selected.startSeq,
+    endSeq,
+    hasOlder: selected.hasOlder,
+    hasNewer: endSeq < bounds.maxSeq,
+  };
+}
+
+// Existing selection fixtures exercise the retained owner through its public API.
+export function selectProjectedTimelinePage(
+  input: Parameters<typeof selectReferenceProjectedTimelinePage>[0] & { wholeTurns?: boolean },
+) {
+  const projection = new TimelineProjection(input.rows);
+  const bounds = input.bounds ?? getTimelineBounds(input.rows) ?? { minSeq: 0, maxSeq: 0 };
+  const page = projection.selectPage({ ...input, bounds });
+  return {
+    ...page,
+    entries: page.entries.map((row) => {
+      const { seq: _seq, ...entry } = row as ProjectedTimelineRow;
+      return entry;
+    }),
+  };
+}
diff --git a/packages/server/src/server/agent/test-utils/timeline-responsiveness.ts b/packages/server/src/server/agent/test-utils/timeline-responsiveness.ts
new file mode 100644
index 0000000000..bfe5ee59c4
--- /dev/null
+++ b/packages/server/src/server/agent/test-utils/timeline-responsiveness.ts
@@ -0,0 +1,25 @@
+import { setImmediate as nextTurn } from "node:timers/promises";
+import { measureMainThreadWork } from "../../../test-utils/main-thread-work.js";
+import { InMemoryAgentTimelineStore } from "../agent-timeline-store.js";
+
+// Measure a cold fetch on its own thread, without Vitest reporting or callbacks.
+const wholeTurns = process.argv[2] === "true";
+const store = new InMemoryAgentTimelineStore();
+store.initialize("large");
+for (let index = 0; index < 100_000; index++) {
+  store.append("large", { type: "user_message", text: String(index) });
+}
+// Finish fixture allocation and collect its temporary garbage before measuring.
+globalThis.gc!();
+await nextTurn();
+const measured = await measureMainThreadWork(
+  `timeline tail main-thread work (wholeTurns=${wholeTurns})`,
+  () => {
+    let page = store.fetch("large", { limit: 200, wholeTurns });
+    for (let repeat = 1; repeat < 8; repeat++)
+      page = store.fetch("large", { limit: 200, wholeTurns });
+    return page;
+  },
+);
+
+process.stdout.write(JSON.stringify(measured));
diff --git a/packages/server/src/server/agent/timeline-projection.test.ts b/packages/server/src/server/agent/timeline-projection.test.ts
index 2d8cf9d4a1..d5e4c5b637 100644
--- a/packages/server/src/server/agent/timeline-projection.test.ts
+++ b/packages/server/src/server/agent/timeline-projection.test.ts
@@ -1,9 +1,9 @@
+import { selectProjectedTimelinePage } from "./test-utils/timeline-page-reference.js";
 import { describe, expect, test } from "vitest";
 
 import type { AgentTimelineRow } from "./agent-manager.js";
 import {
   projectTimelineRows,
-  selectProjectedTimelinePage,
   selectTimelineWindowByProjectedLimit,
 } from "./timeline-projection.js";
 
@@ -534,6 +534,154 @@ describe("selectProjectedTimelinePage", () => {
     };
   }
 
+  test("whole-turn pages extend past the soft target and keep prompt jumps whole", () => {
+    const rows: AgentTimelineRow[] = Array.from({ length: 125 }, (_, index) => ({
+      seq: index + 1,
+      timestamp: new Date(1000 + index).toISOString(),
+      turnId: ["short", "long", "latest"][Number(index >= 3) + Number(index >= 123)],
+      item: {
+        type: "tool_call",
+        callId: `tool-${index}`,
+        name: "shell",
+        status: "completed",
+        error: null,
+        detail: { type: "unknown", input: null, output: null },
+      },
+    }));
+    const tail = selectProjectedTimelinePage({
+      rows,
+      direction: "tail",
+      limit: 40,
+      wholeTurns: true,
+    });
+    expect(tail.entries.map((entry) => entry.seqStart)).toEqual(
+      rows.slice(3).map((row) => row.seq),
+    );
+    expect(tail).toMatchObject({ startSeq: 4, endSeq: 125, hasOlder: true, hasNewer: false });
+    const before = selectProjectedTimelinePage({
+      rows,
+      direction: "before",
+      cursorSeq: 124,
+      limit: 40,
+      wholeTurns: true,
+    });
+    expect(before.entries.map((entry) => entry.seqStart)).toEqual(
+      rows.slice(3, 123).map((row) => row.seq),
+    );
+    expect(before.endSeq).toBe(123);
+    const older = selectProjectedTimelinePage({
+      rows,
+      direction: "before",
+      cursorSeq: 4,
+      limit: 40,
+      wholeTurns: true,
+    });
+    expect(older.entries.map((entry) => entry.seqStart)).toEqual([1, 2, 3]);
+    expect(older.hasOlder).toBe(false);
+    const jump = selectProjectedTimelinePage({
+      rows,
+      direction: "before",
+      cursorSeq: 70,
+      limit: 40,
+      wholeTurns: true,
+    });
+    expect(jump.entries.map((entry) => entry.seqStart)).toEqual(
+      rows.slice(3, 123).map((row) => row.seq),
+    );
+    expect(jump).toMatchObject({ startSeq: 4, endSeq: 123, hasOlder: true, hasNewer: true });
+    const nearPreviousPrompt = selectProjectedTimelinePage({
+      rows,
+      direction: "before",
+      cursorSeq: 10,
+      limit: 40,
+      wholeTurns: true,
+    });
+    expect(nearPreviousPrompt).toMatchObject({ startSeq: 1, endSeq: 123 });
+    expect(
+      selectProjectedTimelinePage({ rows, direction: "tail", limit: 40 }).entries,
+    ).toHaveLength(40);
+  });
+
+  test("whole-turn pages share short runs and use the same deterministic legacy triggers", () => {
+    const rows: AgentTimelineRow[] = Array.from({ length: 24 }, (_, index) => ({
+      seq: index + 1,
+      timestamp: new Date(1000 + index).toISOString(),
+      item:
+        index % 2 === 0
+          ? { type: "user_message", text: `prompt-${index}` }
+          : { type: "assistant_message", text: `reply-${index}` },
+    }));
+    const page = selectProjectedTimelinePage({
+      rows,
+      direction: "tail",
+      limit: 7,
+      wholeTurns: true,
+    });
+    expect(page.entries.map((entry) => entry.seqStart)).toEqual([17, 18, 19, 20, 21, 22, 23, 24]);
+    expect(
+      selectProjectedTimelinePage({ rows, direction: "tail", limit: 0, wholeTurns: true }).entries,
+    ).toHaveLength(24);
+    rows.push({
+      ...toolRow(25, "completed"),
+      item: { ...toolRow(25, "completed").item, name: "heartbeat" } as AgentTimelineRow["item"],
+    });
+    rows.push({
+      seq: 26,
+      timestamp: new Date().toISOString(),
+      item: { type: "assistant_message", text: "awake" },
+    });
+    expect(
+      selectProjectedTimelinePage({
+        rows,
+        direction: "tail",
+        limit: 1,
+        wholeTurns: true,
+      }).entries.map((entry) => entry.seqStart),
+    ).toEqual([25, 26]);
+  });
+
+  test("whole-turn tails close interleaved source coverage without changing forward catch-up", () => {
+    const rows: AgentTimelineRow[] = [
+      {
+        seq: 1,
+        timestamp: new Date(1).toISOString(),
+        turnId: "first",
+        item: { type: "user_message", text: "go" },
+      },
+      { ...toolRow(2, "running"), turnId: "first" },
+      {
+        seq: 3,
+        timestamp: new Date(3).toISOString(),
+        turnId: "second",
+        item: { type: "user_message", text: "next" },
+      },
+      {
+        seq: 4,
+        timestamp: new Date(4).toISOString(),
+        turnId: "second",
+        item: { type: "assistant_message", text: "done" },
+      },
+      { ...toolRow(5, "completed"), turnId: "first" },
+    ];
+    expect(
+      selectProjectedTimelinePage({ rows, direction: "tail", limit: 1, wholeTurns: true }),
+    ).toMatchObject({
+      startSeq: 1,
+      endSeq: 5,
+      hasOlder: false,
+      hasNewer: false,
+    });
+    expect(
+      selectProjectedTimelinePage({
+        rows,
+        direction: "after",
+        cursorSeq: 2,
+        limit: 1,
+        wholeTurns: true,
+      }),
+    ).toEqual(selectProjectedTimelinePage({ rows, direction: "after", cursorSeq: 2, limit: 1 }));
+  });
+
   test("tail page returns full projected items instead of tool lifecycle deltas", () => {
     const rows: AgentTimelineRow[] = [
       { seq: 1, timestamp: "2026-02-13T00:00:00.000Z", item: { type: "user_message", text: "go" } },
diff --git a/packages/server/src/server/agent/timeline-projection.ts b/packages/server/src/server/agent/timeline-projection.ts
index 1f72cdc498..bd5357e581 100644
--- a/packages/server/src/server/agent/timeline-projection.ts
+++ b/packages/server/src/server/agent/timeline-projection.ts
@@ -1,3 +1,4 @@
+import { continuesTimelineTurn, isTimelineTurnTrigger } from "@getpaseo/protocol/timeline-turn";
 import type { AgentTimelineItem, ToolCallDetail } from "./agent-sdk-types.js";
 import { timelineItemIdentity } from "@getpaseo/protocol/timeline-identity";
 
@@ -295,12 +296,45 @@ function mergeAssistantChunks(entries: readonly WorkingEntry[]): WorkingEntry[]
 /** A retained item. `seq` is its latest source event, not its display anchor. */
 export type ProjectedTimelineRow = AgentTimelineRow & TimelineProjectionEntry;
 
+interface ProjectedTimelinePageOptions {
+  wholeTurns?: boolean;
+  bounds: { minSeq: number; maxSeq: number };
+  direction: TimelineLimitDirection;
+  cursorSeq?: number;
+  limit?: number;
+}
+
 /** Owns projected state; source events are consumed, never retained. */
 export class TimelineProjection {
   private readonly rows: ProjectedTimelineRow[] = [];
   private readonly identities = new Map<string, number>();
+  private lastAssistantRowIndex: number | null = null;
+  // Disjoint source-coverage spans in display order. A tail starting inside a
+  // span must include its first anchor to cover interleaved lifecycle updates.
+  private readonly spans: { start: number; endSeq: number }[] = [];
 
-  append(row: AgentTimelineRow): void {
+  private readonly sourceRanges: { startSeq: number; endSeq: number; rowIndex: number }[] = [];
+
+  constructor(rows: readonly AgentTimelineRow[] = []) {
+    for (const row of rows) this.appendProjected(row);
+    for (const [rowIndex, row] of this.rows.entries()) {
+      for (const range of row.sourceSeqRanges) this.sourceRanges.push({ ...range, rowIndex });
+    }
+    this.sourceRanges.sort((a, b) => a.startSeq - b.startSeq);
+  }
+
+  append(row: AgentTimelineRow): ProjectedTimelineRow {
+    const rowIndex = this.appendProjected(row);
+    const last = this.sourceRanges.at(-1);
+    if (last && last.rowIndex === rowIndex && last.endSeq + 1 === row.seq) {
+      last.endSeq = row.seq;
+    } else {
+      this.sourceRanges.push({ startSeq: row.seq, endSeq: row.seq, rowIndex });
+    }
+    return { ...this.rows[rowIndex] };
+  }
+
+  private appendProjected(row: AgentTimelineRow): number {
     const entry = makeCanonicalEntries([row])[0];
     const identity = timelineItemIdentity(row.item);
     const index = identity === null ? undefined : this.identities.get(identity);
@@ -308,7 +342,8 @@ export class TimelineProjection {
     const merged = existing ? mergeIdentityEntries(existing, entry) : null;
     if (merged && index !== undefined) {
       this.rows[index] = { ...merged, seq: merged.seqEnd };
-      return;
+      this.extendSpan(index);
+      return index;
     }
     const previous = this.rows.at(-1);
     const adjacent = previous
@@ -317,16 +352,181 @@ export class TimelineProjection {
     if (previous && adjacent.length === 1) {
       const mergedText = adjacent[0];
       this.rows[this.rows.length - 1] = { ...mergedText, seq: mergedText.seqEnd };
-      return;
+      this.extendSpan(this.rows.length - 1);
+      return this.rows.length - 1;
     }
     if (identity !== null) this.identities.set(identity, this.rows.length);
+    if (entry.item.type === "assistant_message") this.lastAssistantRowIndex = this.rows.length;
     this.rows.push({ ...entry, seq: entry.seqEnd });
+    const last = this.spans.at(-1);
+    if (last && last.endSeq >= entry.seqStart) {
+      last.endSeq = Math.max(last.endSeq, entry.seqEnd);
+    } else {
+      this.spans.push({ start: this.rows.length - 1, endSeq: entry.seqEnd });
+    }
+    return this.rows.length - 1;
+  }
+
+  private spanIndex(rowIndex: number): number {
+    let low = 0;
+    let high = this.spans.length;
+    while (low + 1 < high) {
+      const middle = (low + high) >>> 1;
+      if (this.spans[middle].start <= rowIndex) low = middle;
+      else high = middle;
+    }
+    return low;
+  }
+
+  private extendSpan(rowIndex: number): void {
+    const index = this.spanIndex(rowIndex);
+    const span = this.spans[index];
+    span.endSeq = Math.max(span.endSeq, this.rows[rowIndex].seqEnd);
+    let end = index + 1;
+    while (end < this.spans.length && this.rows[this.spans[end].start].seqStart <= span.endSeq) {
+      span.endSeq = Math.max(span.endSeq, this.spans[end].endSeq);
+      end++;
+    }
+    this.spans.splice(index + 1, end - index - 1);
   }
 
   getRows(): ProjectedTimelineRow[] {
     return this.rows.map((row) => ({ ...row }));
   }
 
+  selectPage(input: ProjectedTimelinePageOptions): ProjectedTimelinePageSelection {
+    if (this.rows.length === 0) {
+      const cursor =
+        input.cursorSeq ??
+        (input.direction === "before" ? input.bounds.maxSeq + 1 : input.bounds.minSeq - 1);
+      return {
+        entries: [],
+        startSeq: null,
+        endSeq: null,
+        hasOlder:
+          input.direction === "after"
+            ? cursor >= input.bounds.minSeq
+            : input.direction === "before" && cursor > input.bounds.minSeq,
+        hasNewer:
+          input.direction === "after"
+            ? cursor < input.bounds.maxSeq
+            : input.direction === "before" && cursor <= input.bounds.maxSeq,
+      };
+    }
+    switch (input.direction) {
+      case "tail":
+        return this.selectTail(input);
+      case "after":
+        return this.selectAfter(input);
+      case "before":
+        return this.selectBefore(input);
+    }
+  }
+
+  private selectTail(input: ProjectedTimelinePageOptions): ProjectedTimelinePageSelection {
+    const limit = Math.max(0, Math.floor(input.limit ?? 0));
+    const requestedStart = limit === 0 ? 0 : Math.max(0, this.rows.length - limit);
+    const coveredStart = this.spans[this.spanIndex(requestedStart)].start;
+    const start = input.wholeTurns ? this.wholeTurnWindowStart(coveredStart) : coveredStart;
+    return {
+      entries: this.rows.slice(start),
+      startSeq: this.rows[start].seqStart,
+      endSeq: input.bounds.maxSeq,
+      hasOlder: start > 0,
+      hasNewer: false,
+    };
+  }
+
+  private wholeTurnWindowStart(requestedStart: number): number {
+    let start = requestedStart;
+    for (;;) {
+      while (start > 0 && continuesProjectedTurn(this.rows[start - 1], this.rows[start])) start--;
+      // Source coverage can pull in an earlier tool and therefore its entire run.
+      const coveredStart = this.spans[this.spanIndex(start)].start;
+      if (coveredStart === start) return start;
+      start = coveredStart;
+    }
+  }
+
+  private selectAfter(input: ProjectedTimelinePageOptions): ProjectedTimelinePageSelection {
+    const startSeq = Math.max(
+      input.bounds.minSeq,
+      (input.cursorSeq ?? input.bounds.minSeq - 1) + 1,
+    );
+    let low = 0;
+    let high = this.sourceRanges.length;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      if (this.sourceRanges[middle].endSeq < startSeq) low = middle + 1;
+      else high = middle;
+    }
+    const indexes = new Set<number>();
+    const limit = Math.max(0, Math.floor(input.limit ?? 0));
+    for (let i = low; i < this.sourceRanges.length; i++) {
+      const range = this.sourceRanges[i];
+      if (range.startSeq > input.bounds.maxSeq) break;
+      indexes.add(range.rowIndex);
+      if (limit > 0 && indexes.size === limit) break;
+    }
+    const entries = [...indexes].sort((a, b) => a - b).map((index) => this.rows[index]);
+    const selected = selectProjectedEntriesAfter({
+      entries,
+      startSeq,
+      maxSeq: input.bounds.maxSeq,
+      limit,
+    });
+    return {
+      entries: selected.entries,
+      startSeq: selected.endSeq === null ? null : startSeq,
+      endSeq: selected.endSeq,
+      hasOlder: startSeq > input.bounds.minSeq,
+      hasNewer: selected.endSeq !== null && selected.endSeq < input.bounds.maxSeq,
+    };
+  }
+
+  private selectBefore(input: ProjectedTimelinePageOptions): ProjectedTimelinePageSelection {
+    const endSeq = Math.min(input.bounds.maxSeq, (input.cursorSeq ?? input.bounds.maxSeq + 1) - 1);
+    if (endSeq >= input.bounds.minSeq) {
+      let low = 0;
+      let high = this.rows.length;
+      while (low < high) {
+        const middle = (low + high) >>> 1;
+        if (this.rows[middle].seqStart <= endSeq) low = middle + 1;
+        else high = middle;
+      }
+      const limit = Math.max(0, Math.floor(input.limit ?? 0));
+      const requestedStart = limit === 0 ? 0 : Math.max(0, low - limit);
+      const start = input.wholeTurns ? this.wholeTurnWindowStart(requestedStart) : requestedStart;
+      // Choose the window before extending the right edge, so a prompt jump
+      // cannot lose its target when the next turn is arbitrarily large.
+      if (input.wholeTurns) {
+        while (low < this.rows.length && continuesProjectedTurn(this.rows[low - 1], this.rows[low]))
+          low++;
+      }
+      let selectedEnd = endSeq;
+      if (input.wholeTurns)
+        selectedEnd = low === this.rows.length ? input.bounds.maxSeq : this.rows[low].seqStart - 1;
+      return {
+        entries: this.rows.slice(start, low),
+        startSeq: this.rows[start]?.seqStart ?? null,
+        endSeq: selectedEnd,
+        hasOlder: start > 0,
+        hasNewer: selectedEnd < input.bounds.maxSeq,
+      };
+    }
+    return { entries: [], startSeq: null, endSeq: null, hasOlder: false, hasNewer: true };
+  }
+
+  getLastItem(seq: number): AgentTimelineItem | null {
+    const last = this.sourceRanges.at(-1);
+    return last?.endSeq === seq ? this.rows[last.rowIndex].item : null;
+  }
+
+  getLastAssistantMessage(): string | null {
+    const row = this.lastAssistantRowIndex === null ? null : this.rows[this.lastAssistantRowIndex];
+    return row?.item.type === "assistant_message" ? row.item.text : null;
+  }
+
   enrichSubmittedUserMessage(
     clientMessageId: string,
     providerMessageId: string,
@@ -444,21 +644,6 @@ export function selectTimelineWindowByProjectedLimit(input: {
   };
 }
 
-function getTimelineBounds(
-  rows: readonly AgentTimelineRow[],
-): { minSeq: number; maxSeq: number } | null {
-  const first = rows[0];
-  const last = rows[rows.length - 1];
-  if (!first || !last) {
-    return null;
-  }
-  const entries = makeCanonicalEntries(rows);
-  return {
-    minSeq: entries.reduce((min, e) => Math.min(min, e.seqStart), Infinity),
-    maxSeq: entries.reduce((max, e) => Math.max(max, e.seqEnd), 0),
-  };
-}
-
 function firstSourceSeqInRange(
   entry: TimelineProjectionEntry,
   startSeq: number,
@@ -515,140 +700,11 @@ function selectProjectedEntriesAfter(input: {
   };
 }
 
-function selectProjectedEntriesBefore(input: {
-  entries: readonly TimelineProjectionEntry[];
-  endSeq: number;
-  limit: number;
-}): { entries: TimelineProjectionEntry[]; startSeq: number | null; hasOlder: boolean } {
-  // Older history follows projected display order. Lifecycle updates can move an
-  // entry's seqEnd without moving its display anchor, so seqStart keeps the full
-  // projected item on exactly one backward page.
-  const eligible = input.entries.filter((entry) => entry.seqStart <= input.endSeq);
-  const selected =
-    input.limit === 0 || input.limit >= eligible.length
-      ? eligible
-      : eligible.slice(eligible.length - input.limit);
-
-  return {
-    entries: selected,
-    startSeq: selected[0]?.seqStart ?? null,
-    hasOlder: selected.length < eligible.length,
-  };
-}
-
-function selectProjectedEntriesTail(
-  projectedAll: TimelineProjectionEntry[],
-  limit: number,
-  bounds: { minSeq: number; maxSeq: number },
-): ProjectedTimelinePageSelection {
-  let start = limit === 0 ? 0 : Math.max(0, projectedAll.length - limit);
-  // Include earlier display anchors with updates in the selected source window,
-  // so a tail certifies contiguous coverage even with interleaved tool updates.
-  for (let i = start - 1; i >= 0; i--) {
-    if (projectedAll[i].seqEnd >= projectedAll[start].seqStart) start = i;
-  }
-  const selected = projectedAll.slice(start);
-  return {
-    entries: selected,
-    startSeq: selected[0]?.seqStart ?? null,
-    endSeq: bounds.maxSeq,
-    hasOlder: start > 0,
-    hasNewer: false,
-  };
-}
-
-export function selectProjectedTimelinePage(input: {
-  rows: readonly AgentTimelineRow[];
-  bounds?: { minSeq: number; maxSeq: number };
-  direction: TimelineLimitDirection;
-  cursorSeq?: number;
-  limit?: number;
-}): ProjectedTimelinePageSelection {
-  const limit = input.limit === undefined ? 0 : Math.max(0, Math.floor(input.limit));
-  const bounds = input.bounds ?? getTimelineBounds(input.rows);
-  const projectedAll = projectTimelineRows({ rows: input.rows, mode: "projected" });
-  if (!bounds) {
-    return {
-      entries: [],
-      startSeq: null,
-      endSeq: null,
-      hasOlder: false,
-      hasNewer: false,
-    };
-  }
-
-  if (projectedAll.length === 0) {
-    if (input.direction === "after") {
-      const cursorSeq = input.cursorSeq ?? bounds.minSeq - 1;
-      return {
-        entries: [],
-        startSeq: null,
-        endSeq: null,
-        hasOlder: cursorSeq >= bounds.minSeq,
-        hasNewer: cursorSeq < bounds.maxSeq,
-      };
-    }
-    if (input.direction === "before") {
-      const cursorSeq = input.cursorSeq ?? bounds.maxSeq + 1;
-      return {
-        entries: [],
-        startSeq: null,
-        endSeq: null,
-        hasOlder: cursorSeq > bounds.minSeq,
-        hasNewer: cursorSeq <= bounds.maxSeq,
-      };
-    }
-    return {
-      entries: [],
-      startSeq: null,
-      endSeq: null,
-      hasOlder: false,
-      hasNewer: false,
-    };
-  }
-
-  if (input.direction === "tail") {
-    return selectProjectedEntriesTail(projectedAll, limit, bounds);
-  }
-
-  if (input.direction === "after") {
-    const cursorSeq = input.cursorSeq ?? bounds.minSeq - 1;
-    const startSeq = Math.max(bounds.minSeq, cursorSeq + 1);
-    const selected = selectProjectedEntriesAfter({
-      entries: projectedAll,
-      startSeq,
-      maxSeq: bounds.maxSeq,
-      limit,
-    });
-    return {
-      entries: selected.entries,
-      startSeq: selected.endSeq === null ? null : startSeq,
-      endSeq: selected.endSeq,
-      hasOlder: startSeq > bounds.minSeq,
-      hasNewer: selected.endSeq !== null && selected.endSeq < bounds.maxSeq,
-    };
-  }
-
-  const cursorSeq = input.cursorSeq ?? bounds.maxSeq + 1;
-  const endSeq = Math.min(bounds.maxSeq, cursorSeq - 1);
-  if (endSeq < bounds.minSeq) {
-    return {
-      entries: [],
-      startSeq: null,
-      endSeq: null,
-      hasOlder: false,
-      hasNewer: endSeq < bounds.maxSeq,
-    };
-  }
-
-  const selected = selectProjectedEntriesBefore({ entries: projectedAll, endSeq, limit });
-  return {
-    entries: selected.entries,
-    startSeq: selected.startSeq,
-    endSeq,
-    hasOlder: selected.hasOlder,
-    hasNewer: endSeq < bounds.maxSeq,
-  };
+function continuesProjectedTurn(
+  previous: TimelineProjectionEntry,
+  next: TimelineProjectionEntry,
+): boolean {
+  return continuesTimelineTurn(previous.turnId, next.turnId, isTimelineTurnTrigger(next.item));
 }
 
 /**
diff --git a/packages/server/src/server/agent/tools/paseo-tools.ts b/packages/server/src/server/agent/tools/paseo-tools.ts
index 6b84f17161..42b6ddec4c 100644
--- a/packages/server/src/server/agent/tools/paseo-tools.ts
+++ b/packages/server/src/server/agent/tools/paseo-tools.ts
@@ -1,3 +1,4 @@
+import { registerPluginTools } from "./plugin-tools.js";
 import type { FinishSubscriptions, FinishRegistration } from "../finish-subscriptions/index.js";
 import type { AgentMessageDelivery } from "../agent-messages/index.js";
 import {
@@ -41,6 +42,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";
@@ -136,7 +138,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,
@@ -152,7 +154,7 @@ export interface PaseoToolHostDependencies {
   ensureWorkspaceForCreate?: (
     cwd: string,
     firstAgentContext?: FirstAgentContext,
-    context?: { callerWorkspaceId?: string },
+    context?: { background?: boolean; callerWorkspaceId?: string },
   ) => Promise<string>;
   browserToolsEnabled?: boolean;
   browserToolsBroker?: BrowserToolsBroker | null;
@@ -186,6 +188,7 @@ interface ProviderSummary {
 }
 
 const WorkspaceAutomationSummarySchema = z.object({
+  parentWorkspaceId: z.string().optional(),
   workspaceId: z.string(),
   projectId: z.string(),
   cwd: z.string(),
@@ -204,6 +207,7 @@ function toWorkspaceAutomationSummary(workspace: PersistedWorkspaceRecord) {
     kind: workspace.kind,
     title: workspace.title,
     background: workspace.background,
+    parentWorkspaceId: workspace.parentWorkspaceId,
   };
 }
 
@@ -704,6 +708,7 @@ function createToolCatalog(
   }
   const localHostOperations = new Map<string, HostOperation>();
   const tools = new Map<string, PaseoToolDefinition>();
+  const builtinNames = new Set<string>();
   const hostTools = new Map([
     ["create_agent", "createAgent"],
     ["create_workspace", "createWorkspace"],
@@ -716,6 +721,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");
@@ -738,6 +744,7 @@ function createToolCatalog(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Tool handlers are schema-validated at registration boundaries.
     handler: (input: any, context: PaseoToolExecutionContext) => Promise<PaseoToolResult>,
   ) => {
+    builtinNames.add(name);
     if (!isPaseoToolEnabled(options.paseoToolPolicy, name)) {
       return;
     }
@@ -857,6 +864,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 => {
@@ -1188,6 +1203,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(
@@ -1394,7 +1415,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"])
@@ -1464,10 +1485,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;
@@ -1498,8 +1521,7 @@ function createToolCatalog(
             ...(worktreeSlug ? { worktreeSlug } : {}),
             ...worktreeTarget,
             ...(title ? { title } : {}),
-            background,
-            callerWorkspaceId: resolveCallerAgent()?.workspaceId,
+            ...workspaceBackgroundIntent(background),
           },
         );
         if (!result.ok) {
@@ -1527,7 +1549,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),
         )
@@ -1587,7 +1609,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(),
@@ -1645,6 +1667,7 @@ function createToolCatalog(
           mode: parsedArgs.settings?.modeId,
           promptFailure: "throw",
           notifyOnFinish,
+          background: parsedArgs.background,
           detached: resolvedArgs.detached,
           callerAgentId,
           callerContext,
@@ -1818,9 +1841,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();
@@ -1924,9 +1949,11 @@ function createToolCatalog(
       }
       return {
         cwd,
-        workspaceId: await options.ensureWorkspaceForCreate(cwd, firstAgentContext, {
-          callerWorkspaceId: resolveCallerAgent()?.workspaceId,
-        }),
+        workspaceId: await options.ensureWorkspaceForCreate(
+          cwd,
+          firstAgentContext,
+          workspaceBackgroundIntent(undefined),
+        ),
       };
     }
 
@@ -3272,6 +3299,14 @@ function createToolCatalog(
     },
   );
 
+  registerPluginTools({
+    agentManager,
+    callerAgentId,
+    scope,
+    tools,
+    builtinNames,
+    policy: options.paseoToolPolicy,
+  });
   return toCatalog();
 }
 
diff --git a/packages/server/src/server/agent/tools/plugin-tools.ts b/packages/server/src/server/agent/tools/plugin-tools.ts
new file mode 100644
index 0000000000..c0c94d11ab
--- /dev/null
+++ b/packages/server/src/server/agent/tools/plugin-tools.ts
@@ -0,0 +1,40 @@
+import { z } from "zod";
+import type { ProviderPaseoToolsPolicy } from "@getpaseo/protocol/provider-config";
+import type { AgentManager } from "../agent-manager.js";
+import { isPaseoToolEnabled } from "../paseo-tool-policy.js";
+import type { PaseoToolDefinition } from "./types.js";
+import { addModelVisibleStructuredContent } from "./paseo-tool-serialization.js";
+
+export function registerPluginTools(options: {
+  agentManager: AgentManager;
+  callerAgentId?: string;
+  scope: "agent" | "top-level";
+  tools: Map<string, PaseoToolDefinition>;
+  builtinNames: Set<string>;
+  policy?: ProviderPaseoToolsPolicy;
+}): void {
+  const { agentManager, callerAgentId, scope, tools, builtinNames, policy } = options;
+  if (scope !== "agent" || !callerAgentId) return;
+  for (const tool of agentManager.getPluginTools(callerAgentId)) {
+    if (builtinNames.has(tool.name)) {
+      throw new Error(
+        `Agent tool ${tool.name} from plugin ${tool.pluginId} collides with Paseo tool ${tool.name}`,
+      );
+    }
+    if (!isPaseoToolEnabled(policy, tool.name)) continue;
+    tools.set(tool.name, {
+      name: tool.name,
+      title: tool.title,
+      description: tool.description,
+      inputSchema: z.fromJSONSchema(tool.inputSchema),
+      async handler(input, { signal }) {
+        const result = await agentManager.executePluginTool(tool, callerAgentId, input, signal);
+        return addModelVisibleStructuredContent({
+          content: result.text === undefined ? [] : [{ type: "text", text: result.text }],
+          structuredContent: result.structuredContent,
+          isError: result.isError,
+        });
+      },
+    });
+  }
+}
diff --git a/packages/server/src/server/authorization/operation-permissions.ts b/packages/server/src/server/authorization/operation-permissions.ts
index f7a5b17857..728057e6b7 100644
--- a/packages/server/src/server/authorization/operation-permissions.ts
+++ b/packages/server/src/server/authorization/operation-permissions.ts
@@ -19,6 +19,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",
@@ -142,6 +144,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 +156,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",
@@ -214,8 +218,10 @@ const INBOUND_PERMISSION = {
   "workspace.label.list.request": "workspace.read",
   "workspace.label.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 +253,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",
@@ -378,6 +387,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",
@@ -390,6 +402,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",
@@ -452,8 +465,10 @@ const OUTBOUND_PERMISSION = {
   "workspace.label.update": "workspace.read",
   "workspace.label.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 f6304491ab..81c621f7fd 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");
@@ -1069,7 +1069,7 @@ function probeWebSocketConnection(
   });
 }
 
-test("startup closes stale active records before serving status without resuming sessions", async () => {
+test("disabled recovery closes stale active records without resuming sessions", async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), "paseo-stale-status-"));
   const logger = pino({ level: "silent" });
   const storagePath = path.join(root, ".paseo", "agents");
@@ -1121,6 +1121,7 @@ test("startup closes stale active records before serving status without resuming
   let sessionsCreated = 0;
   const handle = await createTestPaseoDaemon({
     paseoHomeRoot: root,
+    resumeOnStartup: false,
     agentClients: createTestAgentClients({
       beforeCreateSession: async () => {
         sessionsCreated++;
@@ -1131,17 +1132,20 @@ test("startup closes stale active records before serving status without resuming
   try {
     const expected = records.map((record) => ({
       ...record,
+      resumeOnStartup: false,
       lastStatus:
         record.lastStatus === "running" || record.lastStatus === "initializing"
           ? "closed"
           : 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.test.ts b/packages/server/src/server/bootstrap.test.ts
index 0881e828d0..23d3dcd1a7 100644
--- a/packages/server/src/server/bootstrap.test.ts
+++ b/packages/server/src/server/bootstrap.test.ts
@@ -141,11 +141,11 @@ function liveCleanupHost() {
 test("bootstrap's host toggle prevents collection live, persists, and leaves other hosts enabled", async () => {
   const host = liveCleanupHost();
   const other = liveCleanupHost();
-  host.store.patch({ idleRuntimeCleanup: false });
+  await host.store.patch({ idleRuntimeCleanup: false });
   expect(loadPersistedConfig(host.home).agents?.idleRuntimeCleanup).toBe(false);
   expect((await host.sweep()).collected).toEqual([]);
   expect((await other.sweep()).collected).toHaveLength(1);
-  host.store.patch({ idleRuntimeCleanup: true });
+  await host.store.patch({ idleRuntimeCleanup: true });
   host.protect(true);
   expect((await host.sweep()).collected).toEqual([]);
   host.protect(false);
@@ -160,7 +160,7 @@ test("bootstrap's config-file reload binding disables and enables eligible colle
       path.join(host.home, "config.json"),
       JSON.stringify({ version: 1, agents: { idleRuntimeCleanup: enabled } }),
     );
-    expect(host.store.reload()).toEqual({
+    expect(await host.store.reload()).toEqual({
       appliedPaths: ["agents.idleRuntimeCleanup"],
       restartRequiredPaths: [],
       overrideControlledPaths: [],
@@ -173,12 +173,12 @@ test.each([false, true])(
   "failed config apply restores prior idle cleanup behavior (previous: %s)",
   async (previous) => {
     const host = liveCleanupHost();
-    host.store.patch({ idleRuntimeCleanup: previous });
+    await host.store.patch({ idleRuntimeCleanup: previous });
     const persistedBefore = loadPersistedConfig(host.home);
     const refuse = host.store.onApply(() => {
       throw new Error("Another live owner refused");
     });
-    expect(() => host.store.patch({ idleRuntimeCleanup: !previous })).toThrow(
+    await expect(host.store.patch({ idleRuntimeCleanup: !previous })).rejects.toThrow(
       "Another live owner refused",
     );
     expect(host.store.get().idleRuntimeCleanup).toBe(previous);
@@ -191,6 +191,6 @@ test.each([false, true])(
 test("disposing bootstrap's binding stops configuration delivery", async () => {
   const host = liveCleanupHost();
   host.unsubscribe();
-  host.store.patch({ idleRuntimeCleanup: false });
+  await host.store.patch({ idleRuntimeCleanup: false });
   expect((await host.sweep()).collected).toHaveLength(1);
 });
diff --git a/packages/server/src/server/bootstrap.ts b/packages/server/src/server/bootstrap.ts
index 2eeccfb653..59990f817f 100644
--- a/packages/server/src/server/bootstrap.ts
+++ b/packages/server/src/server/bootstrap.ts
@@ -1,3 +1,5 @@
+import { createRestartRecovery } from "./agent/restart-recovery/index.js";
+import { sendPromptToAgent } from "./agent/agent-prompt.js";
 import { createIdleRuntimeCleanup } from "./agent/idle-runtime-cleanup/index.js";
 import {
   createFinishSubscriptions,
@@ -161,7 +163,11 @@ import { CheckoutDiffManager } from "./checkout-diff-manager.js";
 import { ScheduleService } from "./schedule/service.js";
 import { DaemonConfigStore, type MutableDaemonConfig } from "./daemon-config-store.js";
 import { createOrchestrationSkills } from "./orchestration-skills/index.js";
-import { resolveConfigFromPersisted, type CliConfigOverrides } from "./config.js";
+import {
+  resolveReloadableConfig,
+  type ResolvedDaemonSettings,
+  type CliConfigOverrides,
+} from "./config.js";
 import { resolvePaseoToolPolicy } from "./agent/paseo-tool-policy.js";
 import { BrowserToolsBroker } from "./browser-tools/broker.js";
 import { DaemonConfigBrowserToolsPolicy } from "./browser-tools/policy.js";
@@ -176,7 +182,7 @@ import {
 import { setupAutoArchiveOnMerge } from "./auto-archive-on-merge/index.js";
 import { wrapSessionMessage, type SessionOutboundMessage } from "./messages.js";
 import type { TerminalManager } from "../terminal/terminal-manager.js";
-import { createConfiguredTerminalManager } from "../terminal/terminal-manager-factory.js";
+import { startWorkerTerminalManager } from "../terminal/worker-terminal-manager.js";
 import { applyTerminalAgentHookSetting } from "../terminal/agent-hooks/terminal-agent-hook-setting.js";
 import { loadOrCreateDaemonKeyPair } from "./daemon-keypair.js";
 import { createRelayRuntime, type RelayRuntime } from "./relay-runtime.js";
@@ -196,7 +202,7 @@ import type {
   AgentProviderRuntimeSettingsMap,
   ProviderOverride,
 } from "./agent/provider-launch-config.js";
-import { loadPersistedConfig, type PersistedConfig } from "./persisted-config.js";
+import { type PersistedConfig } from "./persisted-config.js";
 import { createServiceProxySubsystem, type ServiceProxySubsystem } from "./service-proxy.js";
 import { releaseWorkspaceServicePortPlan } from "./workspace-service-port-registry.js";
 import { ScriptHealthMonitor } from "./script-health-monitor.js";
@@ -392,12 +398,14 @@ export type DaemonLifecycleIntent =
       clientId: string;
       requestId: string;
       reason: string;
+      keepTerminals: boolean;
     }
   | {
       type: "restart";
       clientId: string;
       requestId: string;
       reason: string;
+      keepTerminals: boolean;
     };
 
 export interface PaseoDaemonConfig {
@@ -412,6 +420,7 @@ export interface PaseoDaemonConfig {
   trustedProxies?: true | string[];
   mcpEnabled?: boolean;
   mcpInjectIntoAgents?: boolean;
+  usageEnabled?: boolean;
   browserToolsEnabled?: boolean;
   git?: {
     maxProcessesPerSecond: number;
@@ -458,6 +467,8 @@ export interface PaseoDaemonConfig {
   downloadTokenTtlMs?: number;
   agentProviderSettings?: AgentProviderRuntimeSettingsMap;
   idleRuntimeCleanup?: boolean;
+  resumeOnStartup?: boolean;
+  resumePrompt?: string;
   providerCatalogRefreshTimeoutMs?: number;
   metadataGeneration?: {
     providers?: Array<{
@@ -489,7 +500,8 @@ export interface PaseoDaemon {
   scriptRuntimeStore: WorkspaceScriptRuntimeStore;
   browserToolsBroker: BrowserToolsBroker;
   start(): Promise<void>;
-  stop(): Promise<void>;
+  /** Stops the daemon. Terminals keep running for the next daemon only with keepTerminals. */
+  stop(options?: { keepTerminals?: boolean }): Promise<void>;
   getListenTarget(): ListenTarget | null;
   getServerId(): string;
 }
@@ -551,7 +563,7 @@ function resolveExpressTrustProxySetting(config: PaseoDaemonConfig): true | stri
   return config.trustedProxies ?? ["loopback"];
 }
 
-function createInitialRelayConfig(config: PaseoDaemonConfig): MutableDaemonConfig["relay"] {
+function createInitialRelayConfig(config: ResolvedDaemonSettings): MutableDaemonConfig["relay"] {
   return {
     enabled: config.relayEnabled ?? true,
     requireProtectedSecurity: config.relayRequireProtectedSecurity ?? false,
@@ -562,7 +574,7 @@ function resolveReloadEnv(config: PaseoDaemonConfig): NodeJS.ProcessEnv {
   return config.configReload?.env ?? process.env;
 }
 
-function createInitialMutableDaemonConfig(config: PaseoDaemonConfig): MutableDaemonConfig {
+function createInitialMutableDaemonConfig(config: ResolvedDaemonSettings): MutableDaemonConfig {
   const providers = config.providerOverrides ?? {};
 
   const initialConfig: MutableDaemonConfig = {
@@ -579,6 +591,7 @@ function createInitialMutableDaemonConfig(config: PaseoDaemonConfig): MutableDae
     ...(config.providerCatalogRefreshTimeoutMs !== undefined
       ? { catalogRefreshTimeoutMs: config.providerCatalogRefreshTimeoutMs }
       : {}),
+    usage: { enabled: config.usageEnabled !== false },
     browserTools: { enabled: config.browserToolsEnabled ?? false },
     providers,
     metadataGeneration: {
@@ -587,6 +600,8 @@ function createInitialMutableDaemonConfig(config: PaseoDaemonConfig): MutableDae
     autoArchiveAfterMerge: config.autoArchiveAfterMerge ?? false,
     enableTerminalAgentHooks: config.enableTerminalAgentHooks ?? false,
     idleRuntimeCleanup: config.idleRuntimeCleanup !== false,
+    resumeOnStartup: config.resumeOnStartup === true,
+    resumePrompt: config.resumePrompt ?? "Resume working.",
     appendSystemPrompt: config.appendSystemPrompt ?? "",
     pluginsEnabled: config.pluginsEnabled ?? false,
     plugins: config.plugins ?? {},
@@ -638,14 +653,14 @@ export async function createPaseoDaemon(
     }),
     reloadSource: {
       resolve: (persisted) => {
-        const reloaded = resolveConfigFromPersisted(config.paseoHome, persisted, {
+        const reloaded = resolveReloadableConfig(persisted, {
           env: resolveReloadEnv(config),
           cli: config.configReload?.cli,
           relayEnabledFallback: config.configReload?.relayEnabledFallback,
         });
         return {
           mutable: createInitialMutableDaemonConfig(reloaded),
-          overrideControlledPaths: reloaded.configReload?.overrideControlledPaths ?? [],
+          overrideControlledPaths: reloaded.overrideControlledPaths,
         };
       },
     },
@@ -705,7 +720,10 @@ export async function createPaseoDaemon(
   });
   let boundListenTarget: ListenTarget | null = null;
   let workspaceRegistry: FileBackedWorkspaceRegistry | null = null;
-  const terminalManager = createConfiguredTerminalManager({
+  const terminalManager = await startWorkerTerminalManager({
+    paseoHome: config.paseoHome,
+    paseoVersion: daemonVersion,
+    logger,
     getTerminalActivityUrl: () => createTerminalActivityUrl(boundListenTarget),
   });
   applyTerminalAgentHookSetting({ store: daemonConfigStore, logger });
@@ -946,14 +964,14 @@ 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,
       );
       if (!hasActiveWorkspace) workspaceRuntimeStore.remove(cwd);
     }
     if (mutation.kind === "archive" && mutation.workspace) {
-      pluginRuntime.emit("workspace.archived", {
+      pluginRuntime.emit("workspace.archive.after", {
         workspace: describeHookWorkspace(mutation.workspace),
       });
     }
@@ -995,6 +1013,7 @@ export async function createPaseoDaemon(
   const initialAgentManagerState = providerSnapshotManager.getAgentManagerProviderState();
   const agentManager = new AgentManager({
     pluginLifecycle: pluginRuntime,
+    pluginAgentTools: pluginRuntime,
     clients: initialAgentManagerState.clients,
     providerDefinitions: initialAgentManagerState.providerDefinitions,
     registry: agentStorage,
@@ -1015,13 +1034,29 @@ export async function createPaseoDaemon(
   const unsubscribePluginProviders =
     pluginRuntime.subscribeProviderRegistrations(syncPluginProviders);
 
+  const unsubscribePluginSessionChanges = pluginRuntime.subscribeSessionOpenChanges(() => {
+    agentManager.invalidatePluginSessions();
+  });
+
   const detachAgentStoragePersistence = attachAgentStoragePersistence(
     logger,
     agentManager,
     agentStorage,
   );
   await agentStorage.initialize();
-  await closeStaleAgentRecords(agentStorage);
+  const restartRecovery = createRestartRecovery({
+    storage: agentStorage,
+    settings: () => ({
+      enabled: daemonConfigStore.get().resumeOnStartup === true,
+      prompt: daemonConfigStore.get().resumePrompt ?? "Resume working.",
+    }),
+    eligible: async (record) =>
+      !record.workspaceId || !(await workspaceRegistry?.get(record.workspaceId))?.archivedAt,
+    dispatch: (agentId, prompt) =>
+      sendPromptToAgent({ agentId, prompt, agentManager, agentStorage, logger, unarchive: false }),
+    report: (agentId, err) => logger.error({ agentId, err }, "Agent restart recovery failed"),
+  });
+  await restartRecovery.prepareStartup();
   logger.info({ elapsed: elapsed() }, "Agent storage initialized");
   await bootstrapWorkspaceRegistries({
     serverId,
@@ -1079,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,
@@ -1102,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) => ({
@@ -1137,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) => {
@@ -1197,6 +1233,7 @@ export async function createPaseoDaemon(
         worktreesRoot: config.worktreesRoot,
         createPaseoWorktree: async (workflowInput, workflowOptions) => {
           return createRegisteredPaseoWorktree(workflowInput, {
+            lifecycle: pluginRuntime,
             github,
             ...(workflowOptions?.resolveDefaultBranch
               ? {
@@ -1429,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`,
@@ -1454,6 +1492,7 @@ export async function createPaseoDaemon(
     ...createFinishObservation({
       agentManager,
       agentStorage,
+      waitForResume: restartRecovery.waitForResume,
       serverId,
       logger,
       messages: () => {
@@ -1536,7 +1575,7 @@ export async function createPaseoDaemon(
       spawnWorkspaceScript,
       assertAutomationAllowed: (workspaceId) =>
         assertWorkspaceAutomationAllowedForWorkspace(workspaceRegistry, workspaceId),
-      globalServicePorts: loadPersistedConfig(config.paseoHome).worktrees?.servicePorts,
+      getGlobalServicePorts: () => daemonConfigStore.readServicePorts(),
     }),
     markWorkspaceArchiving: markWorkspaceArchivingExternal,
     clearWorkspaceArchiving: clearWorkspaceArchivingExternal,
@@ -1853,6 +1892,7 @@ export async function createPaseoDaemon(
             pluginRuntime.bindPaseoSessionHost(wsServer);
             await pluginRuntime.start();
             providerSnapshotManager.settlePluginProviders();
+            restartRecovery.resumePending();
             await finishSubscriptions.start();
             wsServer.beginAcceptingConnections();
             const relaySecurityLogger = logger.child({ module: "relay-security" });
@@ -1914,6 +1954,7 @@ export async function createPaseoDaemon(
       localCredential = null;
       await deleteLocalCredential(config.paseoHome);
       unsubscribePluginProviders();
+      unsubscribePluginSessionChanges();
       await pluginRuntime.stopAllPlugins().catch(() => undefined);
       await serviceProxy.stopStandalone().catch(() => undefined);
       await agentProviderRuntime.shutdown().catch(() => undefined);
@@ -1925,7 +1966,9 @@ export async function createPaseoDaemon(
     }
   };
 
-  const stop = async () => {
+  const stop = async (options?: { keepTerminals?: boolean }) => {
+    const keepTerminals = options?.keepTerminals === true;
+    let terminalShutdownError: unknown = null;
     localCredential = null;
     await deleteLocalCredential(config.paseoHome);
     // Stop tracking plugin provider registrations before anything tears plugins
@@ -1933,6 +1976,7 @@ export async function createPaseoDaemon(
     // that is still open. Plugins themselves are stopped once every session
     // they serve has been closed, further down.
     unsubscribePluginProviders();
+    unsubscribePluginSessionChanges();
     await hubRelationships.stop();
     workspaceReconciliation.dispose();
     scriptHealthMonitor.stop();
@@ -1943,6 +1987,7 @@ export async function createPaseoDaemon(
     await finishSubscriptions.close();
     await wsServer?.agentMessages.close();
     agentManager.prepareForShutdown();
+    await restartRecovery.captureRunningAgents();
     await closeAllAgents(logger, agentManager);
     await withTimeout({
       promise: pluginRuntime.drainEvents(),
@@ -1954,7 +1999,19 @@ export async function createPaseoDaemon(
     await agentStorage.flush().catch(() => undefined);
     await agentProviderRuntime.shutdown();
     await pluginRuntime.stopAllPlugins();
-    terminalManager.killAll();
+    try {
+      if (keepTerminals) {
+        await terminalManager.detach();
+        logger.info("Terminals left running for the next daemon");
+      } else {
+        await terminalManager.closeTerminals();
+      }
+    } catch (error) {
+      // Finish the rest of the shutdown, then report it: the supervisor and `daemon stop`
+      // retry the cleanup from the record the reaper kept.
+      terminalShutdownError = error;
+      logger.error({ err: error }, "Terminal shutdown failed");
+    }
     await speechService.stop();
     await scheduleService.stop().catch(() => undefined);
     await relayRuntime?.stop().catch(() => undefined);
@@ -1977,6 +2034,9 @@ export async function createPaseoDaemon(
     if (listenTarget.type === "socket" && existsSync(listenTarget.path)) {
       unlinkSync(listenTarget.path);
     }
+    if (terminalShutdownError) {
+      throw terminalShutdownError;
+    }
   };
 
   return {
@@ -1994,16 +2054,6 @@ export async function createPaseoDaemon(
   };
 }
 
-async function closeStaleAgentRecords(agentStorage: AgentStorage): Promise<void> {
-  // No provider runtimes are loaded at startup. Repair interrupted
-  // shutdowns before any status consumer sees the persisted active states.
-  for (const record of await agentStorage.list()) {
-    if (record.lastStatus === "running" || record.lastStatus === "initializing") {
-      await agentStorage.upsert({ ...record, lastStatus: "closed" });
-    }
-  }
-}
-
 /**
  * Closing an agent asks its provider to close the session and waits for the
  * answer. A provider that never answers must not hold the daemon open, so a
diff --git a/packages/server/src/server/checkout-diff-cache.test.ts b/packages/server/src/server/checkout-diff-cache.test.ts
index 37f9283320..a587f89894 100644
--- a/packages/server/src/server/checkout-diff-cache.test.ts
+++ b/packages/server/src/server/checkout-diff-cache.test.ts
@@ -132,3 +132,22 @@ test.each(["base", "uncommitted"] as const)(
     expect(await read("next", "next-after")).toEqual({ diff: "next-after" });
   },
 );
+
+test("superseding a diff cancels its highlighting while identical readers share work", async () => {
+  const cache = new CheckoutDiffCache(() => 0);
+  const release = Promise.withResolvers<{ diff: string }>();
+  let activeSignal: AbortSignal | undefined;
+  const load = (signal: AbortSignal) => {
+    activeSignal = signal;
+    return release.promise;
+  };
+  const first = cache.read({ cwd: "repo", compare: { mode: "base" }, load });
+  await Promise.resolve();
+  expect(activeSignal).toBeDefined();
+  expect(activeSignal!.aborted).toBe(false);
+  expect(cache.read({ cwd: "repo", compare: { mode: "base" }, load })).toBe(first);
+  cache.invalidate("repo", "base");
+  expect(activeSignal!.aborted).toBe(true);
+  release.resolve({ diff: "old snapshot" });
+  await first;
+});
diff --git a/packages/server/src/server/checkout-diff-cache.ts b/packages/server/src/server/checkout-diff-cache.ts
index 4547cdf2e5..71d7d95497 100644
--- a/packages/server/src/server/checkout-diff-cache.ts
+++ b/packages/server/src/server/checkout-diff-cache.ts
@@ -4,6 +4,7 @@ import type { CheckoutDiffCompare, CheckoutDiffResult } from "../utils/checkout-
 interface ActiveRead {
   promise: Promise<CheckoutDiffResult>;
   invalidated: boolean;
+  controller: AbortController;
 }
 
 interface CachedDiff {
@@ -17,7 +18,7 @@ interface CheckoutDiffReadInput {
   compare: CheckoutDiffCompare;
   force?: boolean;
   reason?: string;
-  load: () => Promise<CheckoutDiffResult>;
+  load: (signal: AbortSignal) => Promise<CheckoutDiffResult>;
 }
 
 /** Completed payloads are bounded; active work survives invalidation and eviction. */
@@ -51,6 +52,7 @@ export class CheckoutDiffCache {
     if (pending) {
       if (force) {
         pending.invalidated = true;
+        pending.controller.abort();
         this.values.delete(key);
       }
       if (!pending.invalidated) return pending.promise;
@@ -66,8 +68,9 @@ export class CheckoutDiffCache {
     // Defer load until ownership is installed, including synchronous invalidations.
     const read: ActiveRead = {
       invalidated: false,
+      controller: new AbortController(),
       promise: Promise.resolve()
-        .then(load)
+        .then(() => load(read.controller.signal))
         .then((value) => {
           // Never repopulate the cache with a snapshot invalidated during its build.
           if (!read.invalidated)
@@ -86,7 +89,10 @@ export class CheckoutDiffCache {
       if (cachedCwd !== cwd || (cachedMode !== mode && cachedMode !== "all")) continue;
       this.values.delete(key);
       const pending = this.active.get(key);
-      if (pending) pending.invalidated = true;
+      if (pending) {
+        pending.invalidated = true;
+        pending.controller.abort();
+      }
     }
   }
 }
diff --git a/packages/server/src/server/checkout-diff-manager.ts b/packages/server/src/server/checkout-diff-manager.ts
index 917813d587..8293ce965f 100644
--- a/packages/server/src/server/checkout-diff-manager.ts
+++ b/packages/server/src/server/checkout-diff-manager.ts
@@ -195,6 +195,7 @@ export class CheckoutDiffManager {
       remoteUrl: snapshot.git.remoteUrl,
       isPaseoOwnedWorktree: snapshot.git.isPaseoOwnedWorktree,
       baseRef: snapshot.git.baseRef,
+      baseRefExact: snapshot.git.baseRefExact,
       aheadBehind: snapshot.git.aheadBehind,
       aheadOfOrigin: snapshot.git.aheadOfOrigin,
       behindOfOrigin: snapshot.git.behindOfOrigin,
diff --git a/packages/server/src/server/checkout/status-projection.ts b/packages/server/src/server/checkout/status-projection.ts
index 7f7365efca..90c900435c 100644
--- a/packages/server/src/server/checkout/status-projection.ts
+++ b/packages/server/src/server/checkout/status-projection.ts
@@ -61,6 +61,7 @@ export function buildCheckoutStatusPayloadFromSnapshot({
       currentBranch: snapshot.git.currentBranch ?? null,
       isDirty: snapshot.git.isDirty,
       baseRef: snapshot.git.baseRef,
+      baseRefExact: snapshot.git.baseRefExact,
       aheadBehind: snapshot.git.aheadBehind ?? null,
       upstreamRef: snapshot.git.upstreamRef ?? null,
       aheadOfOrigin: snapshot.git.aheadOfOrigin ?? null,
@@ -81,6 +82,7 @@ export function buildCheckoutStatusPayloadFromSnapshot({
     currentBranch: snapshot.git.currentBranch ?? null,
     isDirty: snapshot.git.isDirty,
     baseRef: snapshot.git.baseRef ?? null,
+    baseRefExact: snapshot.git.baseRefExact,
     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 e8c5f2faa0..f453da7812 100644
--- a/packages/server/src/server/config.test.ts
+++ b/packages/server/src/server/config.test.ts
@@ -1,10 +1,16 @@
+import { measureMainThreadWork } from "../test-utils/main-thread-work.js";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { afterEach, describe, expect, test } from "vitest";
 
-import { loadConfig, resolveBundledWebUiDistDir, resolveConfigFromPersisted } from "./config.js";
+import {
+  loadConfig,
+  resolveBundledWebUiDistDir,
+  resolveConfigFromPersisted,
+  resolveReloadableConfig,
+} from "./config.js";
 import { loadPersistedConfig } from "./persisted-config.js";
 
 const roots: string[] = [];
@@ -14,6 +20,44 @@ describe("server config", () => {
     await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
   });
 
+  test("resolves reloadable settings without resolving the startup password", async () => {
+    const paseoHome = await mkdtemp(path.join(os.tmpdir(), "paseo-config-auth-reload-"));
+    roots.push(paseoHome);
+    const env = { PASEO_PASSWORD: "synthetic-audit-password" };
+    const persisted = loadPersistedConfig(paseoHome);
+    const startup = resolveConfigFromPersisted(paseoHome, persisted, { env });
+    const { result: reloaded, blockingMs } = await measureMainThreadWork(
+      "config resolve main-thread work",
+      () =>
+        resolveReloadableConfig(
+          { ...persisted, daemon: { ...persisted.daemon, browserTools: { enabled: true } } },
+          { env },
+        ),
+    );
+    expect(reloaded).not.toHaveProperty("auth");
+    expect(reloaded.browserToolsEnabled).toBe(true);
+    expect(startup.auth?.password).toBeTypeOf("string");
+    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 74a8037d07..5340bbbcd3 100644
--- a/packages/server/src/server/config.ts
+++ b/packages/server/src/server/config.ts
@@ -523,6 +523,10 @@ function resolveAppendSystemPrompt(persisted: ReturnType<typeof loadPersistedCon
   return persisted.daemon?.appendSystemPrompt ?? "";
 }
 
+function resolveUsageEnabled(persisted: ReturnType<typeof loadPersistedConfig>): boolean {
+  return persisted.daemon?.usage?.enabled !== false;
+}
+
 function resolveBrowserToolsEnabled(persisted: ReturnType<typeof loadPersistedConfig>): boolean {
   return persisted.daemon?.browserTools?.enabled ?? false;
 }
@@ -548,6 +552,7 @@ function resolveStaticLoadConfigSettings(
     mcpEnabled: cli?.mcpEnabled ?? persisted.daemon?.mcp?.enabled ?? true,
     mcpInjectIntoAgents:
       cli?.mcpInjectIntoAgents ?? persisted.daemon?.mcp?.injectIntoAgents ?? false,
+    usageEnabled: resolveUsageEnabled(persisted),
     browserToolsEnabled: resolveBrowserToolsEnabled(persisted),
     autoArchiveAfterMerge: persisted.daemon?.autoArchiveAfterMerge ?? false,
     appendSystemPrompt: resolveAppendSystemPrompt(persisted),
@@ -568,31 +573,46 @@ interface ResolveConfigFromPersistedOptions {
   relayEnabledFallback?: boolean;
 }
 
+// Startup values, including authentication, never enter runtime settings resolution.
+export type ResolvedDaemonSettings = Pick<
+  PaseoDaemonConfig,
+  | "corsAllowedOrigins"
+  | "hostnames"
+  | "trustedProxies"
+  | "mcpEnabled"
+  | "mcpInjectIntoAgents"
+  | "usageEnabled"
+  | "browserToolsEnabled"
+  | "git"
+  | "autoArchiveAfterMerge"
+  | "enableTerminalAgentHooks"
+  | "appendSystemPrompt"
+  | "terminalProfiles"
+  | "agentProfiles"
+  | "skillSelection"
+  | "pluginsEnabled"
+  | "plugins"
+  | "relayEnabled"
+  | "relayRequireProtectedSecurity"
+  | "appBaseUrl"
+  | "idleRuntimeCleanup"
+  | "resumeOnStartup"
+  | "resumePrompt"
+  | "providerCatalogRefreshTimeoutMs"
+  | "metadataGeneration"
+  | "providerOverrides"
+>;
+
 export function resolveConfigFromPersisted(
   paseoHome: string,
   persisted: PersistedConfig,
   options?: ResolveConfigFromPersistedOptions,
 ): PaseoDaemonConfig {
-  const resolvedOptions = options ?? {};
-  const env = configurationEnvironment(resolvedOptions.env ?? process.env);
-  const cli = resolvedOptions.cli;
+  const env = configurationEnvironment(options?.env ?? process.env);
+  const cli = options?.cli;
   const relayEnabledFallback =
-    resolvedOptions.relayEnabledFallback ?? persisted.daemon?.relay?.enabled === undefined;
-
-  const listen = resolveListenAddress(env, cli, persisted);
-  const {
-    mcpEnabled,
-    mcpInjectIntoAgents,
-    browserToolsEnabled,
-    autoArchiveAfterMerge,
-    appendSystemPrompt,
-    terminalProfiles,
-    agentProfiles,
-    hostnames,
-    trustedProxies,
-    appBaseUrl,
-  } = resolveStaticLoadConfigSettings(env, cli, persisted);
-
+    options?.relayEnabledFallback ?? persisted.daemon?.relay?.enabled === undefined;
+  const { overrideControlledPaths, ...settings } = resolveReloadableConfig(persisted, options);
   const relay = resolveRelayConfig({
     env,
     persisted,
@@ -600,42 +620,14 @@ export function resolveConfigFromPersisted(
     cliRelayUseTls: cli?.relayUseTls,
     enabledFallback: relayEnabledFallback,
   });
-  const serviceProxy = resolveServiceProxyConfig(env, persisted);
-  const webUi = resolveWebUiConfig(paseoHome, env, cli, persisted);
-
-  const { openai, speech } = resolveSpeechConfig({
-    paseoHome,
-    env,
-    persisted,
-  });
-
+  const { openai, speech } = resolveSpeechConfig({ paseoHome, env, persisted });
   const voiceLlm = resolveVoiceLlmConfig(env, persisted);
-  const providerOverrides = extractProviderOverrides(
-    persisted.agents?.providers as Record<string, unknown> | undefined,
-  );
-
-  const overrideControlledPaths = resolveOverrideControlledPaths(env, cli, persisted);
-
   return {
-    listen,
+    ...settings,
+    listen: resolveListenAddress(env, cli, persisted),
     paseoHome,
     desktopManaged: env.PASEO_DESKTOP_MANAGED === "1",
     worktreesRoot: resolveWorktreesRoot(paseoHome, persisted),
-    corsAllowedOrigins: resolveCorsAllowedOrigins(env, persisted),
-    hostnames,
-    trustedProxies,
-    mcpEnabled,
-    mcpInjectIntoAgents,
-    browserToolsEnabled,
-    git: resolveGitProcessConfig(env, persisted),
-    autoArchiveAfterMerge,
-    enableTerminalAgentHooks: persisted.daemon?.enableTerminalAgentHooks ?? false,
-    appendSystemPrompt,
-    terminalProfiles,
-    agentProfiles,
-    skillSelection: persisted.agents?.skills?.selection,
-    pluginsEnabled: persisted.pluginsEnabled ?? false,
-    plugins: persisted.plugins,
     pluginRegistries: persisted.pluginRegistries,
     pluginRegistryUrl: env.PASEO_PLUGIN_REGISTRY,
     mcpDebug: env.MCP_DEBUG === "1",
@@ -643,27 +635,20 @@ export function resolveConfigFromPersisted(
     agentStoragePath: path.join(paseoHome, "agents"),
     staticDir: "public",
     agentClients: {},
-    relayEnabled: relay.enabled,
     relayEnabledMutable: relay.enabledMutable,
-    relayRequireProtectedSecurity: relay.requireProtectedSecurity,
     relayEndpoint: relay.endpoint,
     relayPublicEndpoint: relay.publicEndpoint,
     relayUseTls: relay.useTls,
     relayPublicUseTls: relay.publicUseTls,
-    serviceProxy,
-    webUi,
-    appBaseUrl,
+    serviceProxy: resolveServiceProxyConfig(env, persisted),
+    webUi: resolveWebUiConfig(paseoHome, env, cli, persisted),
     auth: resolveAuthConfig(env, persisted),
     openai,
     speech,
     voiceLlmProvider: voiceLlm.provider,
     voiceLlmProviderExplicit: voiceLlm.providerExplicit,
     voiceLlmModel: voiceLlm.model,
-    agentProviderSettings: extractAgentProviderSettings(providerOverrides),
-    idleRuntimeCleanup: persisted.agents?.idleRuntimeCleanup ?? true,
-    providerCatalogRefreshTimeoutMs: persisted.agents?.catalogRefreshTimeoutMs,
-    metadataGeneration: persisted.agents?.metadataGeneration,
-    providerOverrides,
+    agentProviderSettings: extractAgentProviderSettings(settings.providerOverrides),
     log: resolveLogConfigFromEnv(env, persisted),
     configReload: {
       env: { ...env },
@@ -675,6 +660,41 @@ export function resolveConfigFromPersisted(
   };
 }
 
+export function resolveReloadableConfig(
+  persisted: PersistedConfig,
+  options?: ResolveConfigFromPersistedOptions,
+): ResolvedDaemonSettings & { overrideControlledPaths: string[] } {
+  const env = configurationEnvironment(options?.env ?? process.env);
+  const cli = options?.cli;
+  const relay = resolveRelayConfig({
+    env,
+    persisted,
+    cliRelayEnabled: cli?.relayEnabled,
+    cliRelayUseTls: cli?.relayUseTls,
+    enabledFallback:
+      options?.relayEnabledFallback ?? persisted.daemon?.relay?.enabled === undefined,
+  });
+  return {
+    ...resolveStaticLoadConfigSettings(env, cli, persisted),
+    corsAllowedOrigins: resolveCorsAllowedOrigins(env, persisted),
+    git: resolveGitProcessConfig(env, persisted),
+    enableTerminalAgentHooks: persisted.daemon?.enableTerminalAgentHooks ?? false,
+    skillSelection: persisted.agents?.skills?.selection,
+    pluginsEnabled: persisted.pluginsEnabled ?? false,
+    plugins: persisted.plugins,
+    relayEnabled: relay.enabled,
+    relayRequireProtectedSecurity: relay.requireProtectedSecurity,
+    idleRuntimeCleanup: persisted.agents?.idleRuntimeCleanup ?? true,
+    ...resolveRestartRecoveryConfig(persisted.agents),
+    providerCatalogRefreshTimeoutMs: persisted.agents?.catalogRefreshTimeoutMs,
+    metadataGeneration: persisted.agents?.metadataGeneration,
+    providerOverrides: extractProviderOverrides(
+      persisted.agents?.providers as Record<string, unknown> | undefined,
+    ),
+    overrideControlledPaths: resolveOverrideControlledPaths(env, cli, persisted),
+  };
+}
+
 export function loadConfig(
   paseoHome: string,
   options?: Omit<ResolveConfigFromPersistedOptions, "relayEnabledFallback">,
@@ -816,3 +836,10 @@ function resolveSpeechOverrideControlledPaths(
   if (env.PASEO_LOCAL_MODELS_DIR !== undefined) paths.push("providers.local.modelsDir");
   return paths;
 }
+
+function resolveRestartRecoveryConfig(agents: PersistedConfig["agents"]) {
+  return {
+    resumeOnStartup: agents?.resumeOnStartup ?? false,
+    resumePrompt: agents?.resumePrompt ?? "Resume working.",
+  };
+}
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 b6765051f6..416c6adb31 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");
@@ -1543,6 +1732,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 },
@@ -2091,3 +2351,151 @@ test.each(["removed", "disabled"] as const)(
     ).toEqual([]);
   },
 );
+
+test(
+  "a 50 MiB timeline crosses a routed host without dropping content or the route",
+  { timeout: 30000 },
+  async () => {
+    const b = await daemon();
+    const a = await daemon();
+    const destination = await api(b);
+    const origin = await api(a);
+    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: "Large history",
+    });
+    // Keep each row below the established item budget; exercise transport size across rows.
+    const text = "x".repeat(240 * 1024);
+    const rowCount = 220;
+    for (let index = 0; index < rowCount; index++) {
+      await b.daemon.agentManager.appendTimelineItem(agent.id, { type: "user_message", text });
+    }
+    await origin.paseo.hosts.add({ connection: `127.0.0.1:${b.port}` });
+    const serverId = (await online(origin.paseo)).hosts[0]!.serverId!;
+    const remote = await origin.paseo.hosts.client(serverId);
+    const response = await remote.agents.ref(agent.id).timeline.refetch({ limit: 0 });
+    const messages = response.entries.flatMap((row) =>
+      row.item.type === "user_message" ? [row.item.text] : [],
+    );
+    expect(messages).toHaveLength(rowCount);
+    expect(messages.every((message) => message === text)).toBe(true);
+    expect(
+      messages.reduce((bytes, message) => bytes + Buffer.byteLength(message), 0),
+    ).toBeGreaterThan(50 * 1024 * 1024);
+    expect((await remote.workspaces.list()).entries).toHaveLength(1);
+    await remote.dispose();
+  },
+);
+
+test("a pre-write host budget rejection leaves sibling routes connected", async () => {
+  const { HostTransportBudget } = await import("@getpaseo/client/node");
+  const b = await daemon();
+  const origin = createHostClient(
+    `127.0.0.1:${b.port}`,
+    { clientId: "budget-origin", reconnect: { enabled: false } },
+    new HostTransportBudget(1024 * 1024),
+  );
+  cleanup.push(() => origin.close());
+  await origin.connect();
+  const serverId = origin.getLastServerInfoMessage()!.serverId;
+  const routeIds = [
+    await origin.openHostLink("budget-first"),
+    await origin.openHostLink("budget-sibling"),
+  ];
+  const peers = routeIds.map(
+    (id, index) =>
+      new DaemonClient({
+        url: "ws://host-link/ws",
+        clientId: `budget-child-${index}`,
+        reconnect: { enabled: false },
+        transportFactory: createHostChannelTransport(origin, serverId, `budget-${index}`, id),
+      }),
+  );
+  for (const peer of peers) {
+    cleanup.push(() => peer.close());
+    await peer.connect();
+  }
+  await expect(async () =>
+    origin.sendHostFrame(routeIds[0]!, new Uint8Array(2 * 1024 * 1024)),
+  ).rejects.toMatchObject({ code: "resource_limit" });
+  await peers[1]!.ping({ timeoutMs: 2000 });
+  expect([origin.isConnected, ...peers.map((peer) => peer.isConnected)]).toEqual([
+    true,
+    true,
+    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 1a8f7c2731..bfff76239c 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,
@@ -21,6 +23,7 @@ import {
   type HostUpdate,
 } from "@getpaseo/protocol/hosts";
 import type { DaemonPermission, WSHelloMessage } from "@getpaseo/protocol/messages";
+import { webSocketProxyAgent } from "../network/index.js";
 
 export class HostError extends Error {
   constructor(
@@ -234,22 +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;
+    const transports =
+      resume?.transports ??
+      createHostTransportFactory(row.connection, this.budget, {
+        webSocketAgent: webSocketProxyAgent,
+      });
     let stopped = false;
-    const client = createHostClient(
-      row.connection,
-      {
-        clientId: `host-link-${this.self.serverId}-${row.registrationId}`,
-        connectTimeoutMs: 10000,
-      },
-      this.budget,
-    );
+    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();
       },
     };
@@ -283,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 () => {
@@ -302,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();
       }
@@ -327,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;
@@ -349,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;
@@ -508,10 +536,13 @@ export class ConnectedHosts {
           return;
         }
         if (!verified) throw new HostError("host_offline", "Host identity has not been verified");
-        try {
-          transport.send(data);
-        } catch {
+        const rejectWrite = () =>
           route.close("resource_limit", "Host buffer limit reached or transport unavailable");
+        try {
+          const write = transport.send(data);
+          if (write) void write.catch(rejectWrite);
+        } catch {
+          rejectWrite();
         }
       },
     };
@@ -526,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.ts b/packages/server/src/server/connected-hosts/link.ts
index 85fe06ed4e..a18c89aeb0 100644
--- a/packages/server/src/server/connected-hosts/link.ts
+++ b/packages/server/src/server/connected-hosts/link.ts
@@ -1,7 +1,11 @@
 import type { SessionDelivery } from "../session/owned-subscriptions/index.js";
 import { EventEmitter } from "node:events";
 import { createHash } from "node:crypto";
-import { encodeHostRouteFrame, type HostRouteFrame } from "@getpaseo/protocol/binary-frames/index";
+import {
+  MAX_HOST_CHANNEL_FRAME_BYTES,
+  encodeHostRouteFrame,
+  type HostRouteFrame,
+} from "@getpaseo/protocol/binary-frames/index";
 import type {
   DaemonPermission,
   SessionInboundMessage,
@@ -10,6 +14,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;
   readyState = 1;
   constructor(
     private readonly output: (data: string | Uint8Array) => Promise<void>,
diff --git a/packages/server/src/server/daemon-config-store.test.ts b/packages/server/src/server/daemon-config-store.test.ts
index f4c1a02de9..d9b2e94181 100644
--- a/packages/server/src/server/daemon-config-store.test.ts
+++ b/packages/server/src/server/daemon-config-store.test.ts
@@ -10,6 +10,10 @@ import { readSpeechSettings } from "./speech/speech-settings.js";
 import type { PersistedConfig } from "./persisted-config.js";
 import type { MutableDaemonConfig } from "@getpaseo/protocol/messages";
 
+function usageEnabled(persisted: PersistedConfig): boolean {
+  return persisted.daemon?.usage?.enabled !== false;
+}
+
 function reloadableConfig(
   persisted: PersistedConfig,
   options: { relayEnabledFallback?: boolean } = {},
@@ -23,6 +27,7 @@ function reloadableConfig(
       enabled: relay.enabled ?? options.relayEnabledFallback ?? true,
     },
     mcp: { enabled: true, injectIntoAgents: false },
+    usage: { enabled: usageEnabled(persisted) },
     browserTools: { enabled: daemon.browserTools?.enabled ?? false },
     providers: (agents.providers ?? {}) as MutableDaemonConfig["providers"],
     metadataGeneration: { providers: agents.metadataGeneration?.providers ?? [] },
@@ -101,7 +106,7 @@ describe("DaemonConfigStore", () => {
     }
   });
 
-  test("patch persists relay state and emits its field change", () => {
+  test("patch persists relay state and emits its field change", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
     const store = new DaemonConfigStore(paseoHome, {
@@ -117,13 +122,13 @@ describe("DaemonConfigStore", () => {
     const changes: unknown[] = [];
     store.onFieldChange("relay.enabled", (value) => changes.push(value));
 
-    store.patch({ relay: { enabled: true } });
+    await store.patch({ relay: { enabled: true } });
 
     expect(changes).toEqual([true]);
     expect(loadPersistedConfig(paseoHome).daemon?.relay?.enabled).toBe(true);
   });
 
-  test("patch persists the relay protected security requirement independently of relay enablement", () => {
+  test("patch persists the relay protected security requirement independently of relay enablement", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
     const store = new DaemonConfigStore(
@@ -145,14 +150,14 @@ describe("DaemonConfigStore", () => {
     const changes: unknown[] = [];
     store.onFieldChange("relay.requireProtectedSecurity", (value) => changes.push(value));
 
-    store.patch({ relay: { requireProtectedSecurity: true } });
+    await store.patch({ relay: { requireProtectedSecurity: true } });
 
     expect(changes).toEqual([true]);
     expect(store.get().relay).toEqual({ enabled: true, requireProtectedSecurity: true });
     expect(loadPersistedConfig(paseoHome).daemon?.relay?.requireProtectedSecurity).toBe(true);
   });
 
-  test("patch round-trips agent profiles through the strictly-parsed persisted config", () => {
+  test("patch round-trips agent profiles through the strictly-parsed persisted config", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
     const store = new DaemonConfigStore(paseoHome, {
@@ -166,7 +171,7 @@ describe("DaemonConfigStore", () => {
       appendSystemPrompt: "",
     });
 
-    store.patch({
+    await store.patch({
       agentProfiles: [
         {
           id: "profile_ui",
@@ -198,7 +203,7 @@ describe("DaemonConfigStore", () => {
     expect(store.get().agentProfiles).toHaveLength(1);
   });
 
-  test("patch replaces the whole agent profile list rather than merging entries", () => {
+  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);
     const store = new DaemonConfigStore(paseoHome, {
@@ -216,13 +221,13 @@ describe("DaemonConfigStore", () => {
       ],
     });
 
-    store.patch({ agentProfiles: [{ id: "a", name: "Keep", provider: "claude" }] });
+    await store.patch({ agentProfiles: [{ id: "a", name: "Keep", provider: "claude" }] });
 
     expect(store.get().agentProfiles).toEqual([{ id: "a", name: "Keep", provider: "claude" }]);
     expect(loadPersistedConfig(paseoHome).daemon?.agentProfiles).toHaveLength(1);
   });
 
-  test("rolls back config when a field transition fails", () => {
+  test("rolls back config when a field transition fails", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
     const store = new DaemonConfigStore(paseoHome, {
@@ -241,14 +246,14 @@ describe("DaemonConfigStore", () => {
       }
     });
 
-    expect(() => store.patch({ relay: { enabled: true } })).toThrow(
+    await expect(store.patch({ relay: { enabled: true } })).rejects.toThrow(
       "Relay transport failed to start",
     );
     expect(store.get().relay?.enabled).toBe(false);
     expect(loadPersistedConfig(paseoHome).daemon?.relay?.enabled).toBe(false);
   });
 
-  test("rolls back live owners when a later transactional owner fails", () => {
+  test("rolls back live owners when a later transactional owner fails", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
     const store = new DaemonConfigStore(paseoHome, {
@@ -272,7 +277,7 @@ describe("DaemonConfigStore", () => {
       throw new Error("Provider refresh failed");
     });
 
-    expect(() => store.patch({ browserTools: { enabled: true } })).toThrow(
+    await expect(store.patch({ browserTools: { enabled: true } })).rejects.toThrow(
       "Provider refresh failed",
     );
     expect(browserToolsEnabled).toBe(false);
@@ -280,7 +285,7 @@ describe("DaemonConfigStore", () => {
     expect(loadPersistedConfig(paseoHome).daemon?.browserTools?.enabled).toBeUndefined();
   });
 
-  test("rejects relay patches when a launch override owns the setting", () => {
+  test("rejects relay patches when a launch override owns the setting", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
     const store = new DaemonConfigStore(
@@ -299,12 +304,12 @@ describe("DaemonConfigStore", () => {
       { relayEnabledMutable: false },
     );
 
-    expect(() => store.patch({ relay: { enabled: true } })).toThrow(
+    await expect(store.patch({ relay: { enabled: true } })).rejects.toThrow(
       "Relay is controlled by a daemon launch override",
     );
   });
 
-  test("unrelated patches do not persist a one-launch relay override", () => {
+  test("unrelated patches do not persist a one-launch relay override", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
     const persisted = loadPersistedConfig(paseoHome);
@@ -331,12 +336,12 @@ describe("DaemonConfigStore", () => {
       { relayEnabledMutable: false },
     );
 
-    store.patch({ browserTools: { enabled: true } });
+    await store.patch({ browserTools: { enabled: true } });
 
     expect(loadPersistedConfig(paseoHome).daemon?.relay?.enabled).toBe(false);
   });
 
-  test("unrelated patches persist only requested file intent", () => {
+  test("unrelated patches persist only requested file intent", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
     const before = loadPersistedConfig(paseoHome);
@@ -362,7 +367,7 @@ describe("DaemonConfigStore", () => {
       { relayEnabledMutable: false },
     );
 
-    store.patch({
+    await store.patch({
       appendSystemPrompt: "Only this field",
       // Reload-only runtime state is accepted as unknown wire data for forward
       // compatibility but is not part of the patch capability.
@@ -376,7 +381,7 @@ describe("DaemonConfigStore", () => {
     });
   });
 
-  test("patch persists provider enabled flags into config.json", () => {
+  test("patch persists provider enabled flags into config.json", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -417,7 +422,7 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    store.patch({
+    await store.patch({
       providers: {
         gemini: { enabled: false },
       },
@@ -432,7 +437,7 @@ describe("DaemonConfigStore", () => {
     });
   });
 
-  test("patch persists provider Paseo-tool policy without changing availability", () => {
+  test("patch persists provider Paseo-tool policy without changing availability", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
     writeFileSync(
@@ -449,14 +454,14 @@ describe("DaemonConfigStore", () => {
       appendSystemPrompt: "",
     });
 
-    store.patch({
+    await store.patch({
       providers: {
         claude: {
           paseoTools: { enabled: true, disabledTools: ["list_agents"] },
         },
       },
     });
-    store.patch({
+    await store.patch({
       providers: {
         claude: {
           paseoTools: { disabledTools: ["create_agent"] },
@@ -474,7 +479,7 @@ describe("DaemonConfigStore", () => {
     });
   });
 
-  test("patch removes provider entries from config.json", () => {
+  test("patch removes provider entries from config.json", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -519,7 +524,7 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    const next = store.patch({ removeProviders: ["gemini"] });
+    const next = await store.patch({ removeProviders: ["gemini"] });
 
     expect(next.providers.gemini).toBeUndefined();
     expect(next.providers.claude).toEqual({ enabled: false });
@@ -528,7 +533,7 @@ describe("DaemonConfigStore", () => {
     expect(persisted.agents?.providers?.claude).toEqual({ enabled: false });
   });
 
-  test("patch removes the providers object when the last provider is deleted", () => {
+  test("patch removes the providers object when the last provider is deleted", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -567,13 +572,13 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    store.patch({ removeProviders: ["gemini"] });
+    await store.patch({ removeProviders: ["gemini"] });
 
     const persisted = loadPersistedConfig(paseoHome);
     expect(persisted.agents?.providers).toBeUndefined();
   });
 
-  test("patch removes deleted providers from metadata generation", () => {
+  test("patch removes deleted providers from metadata generation", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -629,7 +634,7 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    const next = store.patch({ removeProviders: ["gemini"] });
+    const next = await store.patch({ removeProviders: ["gemini"] });
 
     expect(next.metadataGeneration.providers).toEqual([{ provider: "claude", model: "haiku" }]);
     const persisted = loadPersistedConfig(paseoHome);
@@ -638,7 +643,7 @@ describe("DaemonConfigStore", () => {
     });
   });
 
-  test("patch persists provider removal when in-memory config is already clean", () => {
+  test("patch persists provider removal when in-memory config is already clean", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -680,7 +685,7 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    const next = store.patch({ removeProviders: ["gemini"] });
+    const next = await store.patch({ removeProviders: ["gemini"] });
 
     expect(next.providers.gemini).toBeUndefined();
     const persisted = loadPersistedConfig(paseoHome);
@@ -688,7 +693,7 @@ describe("DaemonConfigStore", () => {
     expect(persisted.agents?.metadataGeneration).toEqual({ providers: [] });
   });
 
-  test("patch persists append system prompt into config.json", () => {
+  test("patch persists append system prompt into config.json", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -706,7 +711,7 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    store.patch({
+    await store.patch({
       appendSystemPrompt: "Prefer terse replies.",
     });
 
@@ -714,7 +719,7 @@ describe("DaemonConfigStore", () => {
     expect(persisted.daemon?.appendSystemPrompt).toBe("Prefer terse replies.");
   });
 
-  test("patch persists browser tools opt-in into config.json", () => {
+  test("patch persists browser tools opt-in into config.json", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -731,13 +736,13 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    store.patch({ browserTools: { enabled: true } });
+    await store.patch({ browserTools: { enabled: true } });
 
     const persisted = loadPersistedConfig(paseoHome);
     expect(persisted.daemon?.browserTools).toEqual({ enabled: true });
   });
 
-  test("patch persists provider additional models into config.json", () => {
+  test("patch persists provider additional models into config.json", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -755,7 +760,7 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    store.patch({
+    await store.patch({
       providers: {
         claude: {
           additionalModels: [
@@ -779,7 +784,7 @@ describe("DaemonConfigStore", () => {
     });
   });
 
-  test("patch persists daemon append system prompt into config.json", () => {
+  test("patch persists daemon append system prompt into config.json", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -797,7 +802,7 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    store.patch({
+    await store.patch({
       appendSystemPrompt: "Prefer terse replies.",
     });
 
@@ -805,7 +810,7 @@ describe("DaemonConfigStore", () => {
     expect(persisted.daemon?.appendSystemPrompt).toBe("Prefer terse replies.");
   });
 
-  test("patch persists enable terminal agent hooks into config.json", () => {
+  test("patch persists enable terminal agent hooks into config.json", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -822,13 +827,13 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    store.patch({ enableTerminalAgentHooks: true });
+    await store.patch({ enableTerminalAgentHooks: true });
 
     const persisted = loadPersistedConfig(paseoHome);
     expect(persisted.daemon?.enableTerminalAgentHooks).toBe(true);
   });
 
-  test("patch persists metadata generation providers into config.json", () => {
+  test("patch persists metadata generation providers into config.json", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -846,7 +851,7 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    store.patch({
+    await store.patch({
       metadataGeneration: {
         providers: [
           { provider: "claude", model: "haiku" },
@@ -864,7 +869,7 @@ describe("DaemonConfigStore", () => {
     });
   });
 
-  test("patch persists clearing metadata generation providers into config.json", () => {
+  test("patch persists clearing metadata generation providers into config.json", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -899,13 +904,13 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    store.patch({ metadataGeneration: { providers: [] } });
+    await store.patch({ metadataGeneration: { providers: [] } });
 
     const persisted = loadPersistedConfig(paseoHome);
     expect(persisted.agents?.metadataGeneration).toEqual({ providers: [] });
   });
 
-  test("patch persists the host idle runtime cleanup opt-out for the next daemon start", () => {
+  test("patch persists the host idle runtime cleanup opt-out for the next daemon start", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
     writeFileSync(
@@ -930,7 +935,7 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    expect(store.patch({ idleRuntimeCleanup: false }).idleRuntimeCleanup).toBe(false);
+    expect((await store.patch({ idleRuntimeCleanup: false })).idleRuntimeCleanup).toBe(false);
 
     expect(loadPersistedConfig(paseoHome).agents).toEqual({
       metadataGeneration: { providers: [{ provider: "claude" }] },
@@ -938,11 +943,20 @@ describe("DaemonConfigStore", () => {
     });
     expect(loadConfig(paseoHome, { env: {} }).idleRuntimeCleanup).toBe(false);
 
-    store.patch({ idleRuntimeCleanup: true });
+    await store.patch({ idleRuntimeCleanup: true });
     expect(loadConfig(paseoHome, { env: {} }).idleRuntimeCleanup).toBe(true);
+    await store.patch({ resumeOnStartup: false, resumePrompt: "Keep going.\n" });
+    expect(loadPersistedConfig(paseoHome).agents).toMatchObject({
+      resumeOnStartup: false,
+      resumePrompt: "Keep going.\n",
+    });
+    expect(loadConfig(paseoHome, { env: {} })).toMatchObject({
+      resumeOnStartup: false,
+      resumePrompt: "Keep going.\n",
+    });
   });
 
-  test("patch persists custom ACP provider overrides into config.json", () => {
+  test("patch persists custom ACP provider overrides into config.json", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
 
@@ -960,7 +974,7 @@ describe("DaemonConfigStore", () => {
       undefined,
     );
 
-    store.patch({
+    await store.patch({
       providers: {
         "paseo-e2e-acp": {
           extends: "acp",
@@ -1028,7 +1042,49 @@ describe("DaemonConfigStore reload", () => {
     writeFileSync(path.join(paseoHome, "config.json"), `${JSON.stringify(config, null, 2)}\n`);
   }
 
-  test("applies mutable edits and reports startup-only edits", () => {
+  test("applies overlapping plugin mutations to the latest committed sources", async () => {
+    const { store } = createReloadableStore({
+      initialPersisted: {
+        plugins: {
+          a: { source: "directory", path: "/a", enabled: false },
+          b: { source: "directory", path: "/b", enabled: true },
+        },
+      },
+    });
+    const enable = store.patch((current) => ({
+      plugins: {
+        ...current.plugins,
+        a: { ...current.plugins.a!, enabled: true },
+      },
+    }));
+    const disable = store.patch((current) => ({
+      plugins: {
+        ...current.plugins,
+        b: { ...current.plugins.b!, enabled: false },
+      },
+    }));
+    await Promise.all([enable, disable]);
+    expect(store.get().plugins).toEqual({
+      a: { source: "directory", path: "/a", enabled: true },
+      b: { source: "directory", path: "/b", enabled: false },
+    });
+  });
+
+  test("serializes overlapping patches before committing their combined state", async () => {
+    const { paseoHome, store } = createReloadableStore();
+    const first = store.patch({ appendSystemPrompt: "first" });
+    const second = store.patch({ browserTools: { enabled: true } });
+    expect(store.get().appendSystemPrompt).toBe("");
+    await Promise.all([first, second]);
+    expect(store.get().appendSystemPrompt).toBe("first");
+    expect(store.get().browserTools.enabled).toBe(true);
+    expect(loadPersistedConfig(paseoHome).daemon).toMatchObject({
+      appendSystemPrompt: "first",
+      browserTools: { enabled: true },
+    });
+  });
+
+  test("applies mutable edits and reports startup-only edits", async () => {
     const { paseoHome, store, persisted } = createReloadableStore();
     writeConfig(paseoHome, {
       ...persisted,
@@ -1040,7 +1096,7 @@ describe("DaemonConfigStore reload", () => {
       },
     });
 
-    expect(store.reload()).toEqual({
+    expect(await store.reload()).toEqual({
       appliedPaths: [
         "daemon.browserTools.enabled",
         "daemon.git.maxProcessConcurrency",
@@ -1053,13 +1109,13 @@ describe("DaemonConfigStore reload", () => {
     expect(store.get().git).toEqual({ maxProcessesPerSecond: 12, maxProcessConcurrency: 3 });
   });
 
-  test("reloads idle runtime cleanup in both directions without requiring a restart", () => {
+  test("reloads idle runtime cleanup in both directions without requiring a restart", async () => {
     const { paseoHome, store, persisted } = createReloadableStore();
     const changes: unknown[] = [];
     store.onFieldChange("idleRuntimeCleanup", (value) => changes.push(value));
     for (const enabled of [false, true]) {
       writeConfig(paseoHome, { ...persisted, agents: { idleRuntimeCleanup: enabled } });
-      expect(store.reload()).toEqual({
+      expect(await store.reload()).toEqual({
         appliedPaths: ["agents.idleRuntimeCleanup"],
         restartRequiredPaths: [],
         overrideControlledPaths: [],
@@ -1067,8 +1123,8 @@ describe("DaemonConfigStore reload", () => {
       expect(store.get().idleRuntimeCleanup).toBe(enabled);
     }
     expect(changes).toEqual([false, true]);
-    store.patch({ idleRuntimeCleanup: false });
-    expect(store.reload()).toEqual({
+    await store.patch({ idleRuntimeCleanup: false });
+    expect(await store.reload()).toEqual({
       appliedPaths: [],
       restartRequiredPaths: [],
       overrideControlledPaths: [],
@@ -1076,7 +1132,7 @@ describe("DaemonConfigStore reload", () => {
     expect(store.get().idleRuntimeCleanup).toBe(false);
   });
 
-  test("applies the global plugin switch in both directions", () => {
+  test("applies the global plugin switch in both directions", async () => {
     const { paseoHome, store, persisted } = createReloadableStore({
       initialPersisted: { version: 1, pluginsEnabled: false },
     });
@@ -1084,7 +1140,7 @@ describe("DaemonConfigStore reload", () => {
     store.onFieldChange("pluginsEnabled", (value) => changes.push(value));
 
     writeConfig(paseoHome, { ...persisted, pluginsEnabled: true });
-    expect(store.reload()).toEqual({
+    expect(await store.reload()).toEqual({
       appliedPaths: ["pluginsEnabled"],
       restartRequiredPaths: [],
       overrideControlledPaths: [],
@@ -1092,7 +1148,7 @@ describe("DaemonConfigStore reload", () => {
     expect(store.get().pluginsEnabled).toBe(true);
 
     writeConfig(paseoHome, { ...persisted, pluginsEnabled: false });
-    expect(store.reload()).toEqual({
+    expect(await store.reload()).toEqual({
       appliedPaths: ["pluginsEnabled"],
       restartRequiredPaths: [],
       overrideControlledPaths: [],
@@ -1101,7 +1157,7 @@ describe("DaemonConfigStore reload", () => {
     expect(changes).toEqual([true, false]);
   });
 
-  test("classifies every leaf when a parent subtree is added", () => {
+  test("classifies every leaf when a parent subtree is added", async () => {
     const { paseoHome, store } = createReloadableStore({
       initialPersisted: { version: 1 },
     });
@@ -1116,14 +1172,14 @@ describe("DaemonConfigStore reload", () => {
       },
     });
 
-    expect(store.reload()).toEqual({
+    expect(await store.reload()).toEqual({
       appliedPaths: ["daemon.relay.enabled"],
       restartRequiredPaths: ["daemon.relay.endpoint", "daemon.relay.useTls"],
       overrideControlledPaths: [],
     });
   });
 
-  test("classifies every leaf when the daemon subtree is removed", () => {
+  test("classifies every leaf when the daemon subtree is removed", async () => {
     const { paseoHome, store } = createReloadableStore({
       initialPersisted: {
         version: 1,
@@ -1144,7 +1200,7 @@ describe("DaemonConfigStore reload", () => {
     });
     writeConfig(paseoHome, { version: 1 });
 
-    expect(store.reload()).toEqual({
+    expect(await store.reload()).toEqual({
       appliedPaths: ["daemon.browserTools.enabled"],
       restartRequiredPaths: [
         "daemon.listen",
@@ -1158,7 +1214,7 @@ describe("DaemonConfigStore reload", () => {
     expect(store.get().relay?.enabled).toBe(false);
   });
 
-  test("keeps overridden leaves separate from restart-required siblings", () => {
+  test("keeps overridden leaves separate from restart-required siblings", async () => {
     const { paseoHome, store } = createReloadableStore({
       initialPersisted: { version: 1 },
       overrideControlledPaths: ["daemon.relay.enabled"],
@@ -1170,25 +1226,25 @@ describe("DaemonConfigStore reload", () => {
       },
     });
 
-    expect(store.reload()).toEqual({
+    expect(await store.reload()).toEqual({
       appliedPaths: [],
       restartRequiredPaths: ["daemon.relay.endpoint"],
       overrideControlledPaths: ["daemon.relay.enabled"],
     });
   });
 
-  test("invalid JSON and invalid schema apply nothing", () => {
+  test("invalid JSON and invalid schema apply nothing", async () => {
     const { paseoHome, store } = createReloadableStore();
     writeFileSync(path.join(paseoHome, "config.json"), "{ nope\n");
-    expect(() => store.reload()).toThrow("Invalid JSON");
+    await expect(store.reload()).rejects.toThrow("Invalid JSON");
     expect(store.get().browserTools.enabled).toBe(false);
 
     writeConfig(paseoHome, { daemon: { browserTools: { enabled: "yes" } } });
-    expect(() => store.reload()).toThrow("Invalid config");
+    await expect(store.reload()).rejects.toThrow("Invalid config");
     expect(store.get().browserTools.enabled).toBe(false);
   });
 
-  test("removing providers and optional profiles clears live state", () => {
+  test("removing providers and optional profiles clears live state", async () => {
     const { paseoHome, store, persisted } = createReloadableStore();
     writeConfig(paseoHome, {
       ...persisted,
@@ -1203,10 +1259,10 @@ describe("DaemonConfigStore reload", () => {
         },
       },
     });
-    store.reload();
+    await store.reload();
 
     writeConfig(paseoHome, persisted);
-    const result = store.reload();
+    const result = await store.reload();
 
     expect(result.appliedPaths).toEqual([
       "agents.providers",
@@ -1218,7 +1274,7 @@ describe("DaemonConfigStore reload", () => {
     expect(store.get().agentProfiles).toBeUndefined();
   });
 
-  test("reports a launch-controlled edit without changing live state", () => {
+  test("reports a launch-controlled edit without changing live state", async () => {
     const { paseoHome, store, persisted } = createReloadableStore({
       overrideControlledPaths: ["daemon.relay.enabled"],
     });
@@ -1228,7 +1284,7 @@ describe("DaemonConfigStore reload", () => {
       daemon: { ...persisted.daemon, relay: { enabled: !initialRelay } },
     });
 
-    expect(store.reload()).toEqual({
+    expect(await store.reload()).toEqual({
       appliedPaths: [],
       restartRequiredPaths: [],
       overrideControlledPaths: ["daemon.relay.enabled"],
@@ -1236,7 +1292,7 @@ describe("DaemonConfigStore reload", () => {
     expect(store.get().relay?.enabled).toBe(initialRelay);
   });
 
-  test("an unrelated patch does not mark a manual override-owned edit as applied", () => {
+  test("an unrelated patch does not mark a manual override-owned edit as applied", async () => {
     const { paseoHome, store, persisted } = createReloadableStore({
       overrideControlledPaths: ["daemon.relay.enabled"],
     });
@@ -1244,16 +1300,16 @@ describe("DaemonConfigStore reload", () => {
       ...persisted,
       daemon: { ...persisted.daemon, relay: { enabled: true } },
     });
-    store.patch({ appendSystemPrompt: "patched elsewhere" });
+    await store.patch({ appendSystemPrompt: "patched elsewhere" });
 
-    expect(store.reload()).toEqual({
+    expect(await store.reload()).toEqual({
       appliedPaths: [],
       restartRequiredPaths: [],
       overrideControlledPaths: ["daemon.relay.enabled"],
     });
   });
 
-  test("reports startup-only launch overrides instead of restart warnings", () => {
+  test("reports startup-only launch overrides instead of restart warnings", async () => {
     const { paseoHome, store, persisted } = createReloadableStore({
       overrideControlledPaths: ["daemon.listen", "daemon.relay.endpoint"],
     });
@@ -1269,16 +1325,16 @@ describe("DaemonConfigStore reload", () => {
       },
     });
 
-    expect(store.reload()).toEqual({
+    expect(await store.reload()).toEqual({
       appliedPaths: [],
       restartRequiredPaths: [],
       overrideControlledPaths: ["daemon.listen", "daemon.relay.endpoint"],
     });
   });
 
-  test("a no-op reload returns empty path lists", () => {
+  test("a no-op reload returns empty path lists", async () => {
     const { store } = createReloadableStore();
-    expect(store.reload()).toEqual({
+    expect(await store.reload()).toEqual({
       appliedPaths: [],
       restartRequiredPaths: [],
       overrideControlledPaths: [],
@@ -1317,25 +1373,25 @@ describe("DaemonConfigStore speech settings", () => {
     return { paseoHome, store, applied, persisted };
   }
 
-  test("reads, patches, and clears local STT language without losing it on other saves", () => {
+  test("reads, patches, and clears local STT language without losing it on other saves", async () => {
     const { paseoHome, store } = createSpeechStore({
       features: { dictation: { stt: { language: "fr" } } },
     });
     expect(store.get().features?.dictation.stt).toEqual({ provider: "local", language: "fr" });
-    store.patch({ features: { voiceMode: { enabled: true } } });
+    await store.patch({ features: { voiceMode: { enabled: true } } });
     expect(loadPersistedConfig(paseoHome).features?.dictation?.stt).toEqual({
       provider: "local",
       language: "fr",
     });
-    const patched = store.patch({
+    const patched = await store.patch({
       features: { dictation: { stt: { provider: "local", language: "de" } } },
     });
     expect(patched.features?.dictation.stt).toEqual({ provider: "local", language: "de" });
-    store.patch({ features: { dictation: { stt: { language: null } } } });
+    await store.patch({ features: { dictation: { stt: { language: null } } } });
     expect(loadPersistedConfig(paseoHome).features?.dictation?.stt).toEqual({ provider: "local" });
   });
 
-  test("reports language env overrides for both local STT sites", () => {
+  test("reports language env overrides for both local STT sites", async () => {
     const { store } = createSpeechStore(
       {},
       { PASEO_DICTATION_LANGUAGE: "fr", PASEO_VOICE_LANGUAGE: "de" },
@@ -1346,22 +1402,22 @@ describe("DaemonConfigStore speech settings", () => {
     });
   });
 
-  test("keeps voice mode off until it is turned on", () => {
+  test("keeps voice mode off until it is turned on", async () => {
     const { paseoHome, store } = createSpeechStore();
 
     expect(store.get().features?.dictation.enabled).toBe(true);
     expect(store.get().features?.voiceMode.enabled).toBe(false);
 
-    const result = store.patch({ features: { voiceMode: { enabled: true } } });
+    const result = await store.patch({ features: { voiceMode: { enabled: true } } });
 
     expect(result.features?.voiceMode.enabled).toBe(true);
     expect(loadPersistedConfig(paseoHome).features?.voiceMode?.enabled).toBe(true);
   });
 
-  test("stores the OpenAI key without ever returning it", () => {
+  test("stores the OpenAI key without ever returning it", async () => {
     const { paseoHome, store, applied } = createSpeechStore();
 
-    const result = store.patch({
+    const result = await store.patch({
       features: { dictation: { stt: { provider: "openai", apiKey: " sk-test " } } },
     });
 
@@ -1373,26 +1429,26 @@ describe("DaemonConfigStore speech settings", () => {
     expect(applied).toHaveLength(1);
   });
 
-  test("applies a replaced key even though the visible settings do not change", () => {
+  test("applies a replaced key even though the visible settings do not change", async () => {
     const { store, applied } = createSpeechStore({
       version: 1,
       features: { dictation: { stt: { provider: "openai", apiKey: "sk-old" } } },
     });
 
-    store.patch({ features: { dictation: { stt: { apiKey: "sk-new" } } } });
+    await store.patch({ features: { dictation: { stt: { apiKey: "sk-new" } } } });
 
     expect(applied.map((next) => next.features?.dictation?.stt)).toEqual([
       { provider: "openai", apiKey: "sk-new" },
     ]);
   });
 
-  test("switching provider clears the previous provider's model", () => {
+  test("switching provider clears the previous provider's model", async () => {
     const { paseoHome, store } = createSpeechStore({
       version: 1,
       features: { dictation: { stt: { provider: "local", model: "parakeet-tdt-0.6b-v3-int8" } } },
     });
 
-    const result = store.patch({ features: { dictation: { stt: { provider: "openai" } } } });
+    const result = await store.patch({ features: { dictation: { stt: { provider: "openai" } } } });
 
     expect(result.features?.dictation.stt).toEqual({ provider: "openai", hasApiKey: false });
     expect(loadPersistedConfig(paseoHome).features?.dictation?.stt).toEqual({
@@ -1400,62 +1456,62 @@ describe("DaemonConfigStore speech settings", () => {
     });
   });
 
-  test("rejects a local model id outside the catalog without persisting it", () => {
+  test("rejects a local model id outside the catalog without persisting it", async () => {
     const { paseoHome, store, applied } = createSpeechStore();
 
-    expect(() =>
+    await expect(
       store.patch({ features: { voiceMode: { tts: { provider: "local", model: "nope" } } } }),
-    ).toThrow("Unknown local voice model: nope");
+    ).rejects.toThrow("Unknown local voice model: nope");
     expect(loadPersistedConfig(paseoHome).features?.voiceMode).toBeUndefined();
     expect(applied).toEqual([]);
   });
 
-  test("reload applies hand-edited speech settings without a restart", () => {
+  test("reload applies hand-edited speech settings without a restart", async () => {
     const { paseoHome, store, applied, persisted } = createSpeechStore();
     writeFileSync(
       path.join(paseoHome, "config.json"),
       `${JSON.stringify({ ...persisted, features: { voiceMode: { enabled: false } } }, null, 2)}\n`,
     );
 
-    const result = store.reload();
+    const result = await store.reload();
 
     expect(result.appliedPaths).toContain("features.voiceMode");
     expect(result.restartRequiredPaths).toEqual([]);
     expect(store.get().features?.voiceMode.enabled).toBe(false);
     expect(applied).toHaveLength(1);
   });
-  test("merges same-provider fields and replaces the whole variant when provider changes", () => {
+  test("merges same-provider fields and replaces the whole variant when provider changes", async () => {
     const { paseoHome, store } = createSpeechStore();
-    store.patch({
+    await store.patch({
       features: {
         voiceMode: {
           stt: { provider: "openai", apiKey: "secret", baseUrl: "https://site/v1", model: "first" },
         },
       },
     });
-    store.patch({ features: { voiceMode: { stt: { model: "second", baseUrl: null } } } });
+    await store.patch({ features: { voiceMode: { stt: { model: "second", baseUrl: null } } } });
     expect(loadPersistedConfig(paseoHome).features?.voiceMode?.stt).toEqual({
       provider: "openai",
       apiKey: "secret",
       model: "second",
     });
-    store.patch({ features: { voiceMode: { stt: { provider: "openai", model: "third" } } } });
+    await store.patch({ features: { voiceMode: { stt: { provider: "openai", model: "third" } } } });
     expect(store.get().features?.voiceMode.stt).toEqual({
       provider: "openai",
       model: "third",
       hasApiKey: true,
     });
-    store.patch({ features: { voiceMode: { stt: { apiKey: "new-secret" } } } });
-    store.patch({ features: { voiceMode: { stt: { provider: "local" } } } });
-    store.patch({ features: { voiceMode: { stt: { provider: "openai" } } } });
+    await store.patch({ features: { voiceMode: { stt: { apiKey: "new-secret" } } } });
+    await store.patch({ features: { voiceMode: { stt: { provider: "local" } } } });
+    await store.patch({ features: { voiceMode: { stt: { provider: "openai" } } } });
     expect(store.get().features?.voiceMode.stt).toEqual({ provider: "openai", hasApiKey: false });
   });
 
-  test("keeps a saved OpenAI key when a full variant patch omits the write-only key", () => {
+  test("keeps a saved OpenAI key when a full variant patch omits the write-only key", async () => {
     const { paseoHome, store } = createSpeechStore({
       features: { voiceMode: { stt: { provider: "openai", apiKey: "saved-secret" } } },
     });
-    const result = store.patch({
+    const result = await store.patch({
       features: { voiceMode: { stt: { provider: "openai", model: "whisper-1" } } },
     });
     expect(result.features?.voiceMode.stt).toEqual({
@@ -1471,7 +1527,7 @@ describe("DaemonConfigStore speech settings", () => {
     expect(JSON.stringify(result)).not.toContain("saved-secret");
   });
 
-  test("loads a legacy host, redacts its key and writes the normalized config after any save", () => {
+  test("loads a legacy host, redacts its key and writes the normalized config after any save", async () => {
     const { paseoHome, store } = createSpeechStore({
       providers: { openai: { apiKey: "legacy-secret", stt: { baseUrl: "https://old/v1" } } },
       features: { voiceMode: { enabled: true, stt: { provider: "openai" } } },
@@ -1482,13 +1538,13 @@ describe("DaemonConfigStore speech settings", () => {
       hasApiKey: true,
     });
     expect(JSON.stringify(store.get())).not.toContain("legacy-secret");
-    store.patch({ autoArchiveAfterMerge: true });
+    await store.patch({ autoArchiveAfterMerge: true });
     const disk = JSON.parse(readFileSync(path.join(paseoHome, "config.json"), "utf8"));
     expect(disk.providers).not.toHaveProperty("openai");
     expect(disk.features.voiceMode.stt.apiKey).toBe("legacy-secret");
   });
 
-  test("reports env overrides and removes fallback provenance after saving a key", () => {
+  test("reports env overrides and removes fallback provenance after saving a key", async () => {
     const { store } = createSpeechStore(
       { features: { voiceMode: { stt: { provider: "openai", model: "configured" } } } },
       {
@@ -1514,10 +1570,38 @@ describe("DaemonConfigStore speech settings", () => {
       "features.voiceMode.stt.model": "STT_MODEL",
     });
     expect(other.get().features?.voiceMode.stt.hasApiKey).toBe(false);
-    other.patch({
+    await other.patch({
       features: { voiceMode: { stt: { apiKey: "saved-secret", baseUrl: "https://saved/v1" } } },
     });
     expect(other.get().envOverrides).toEqual({ "features.voiceMode.stt.model": "STT_MODEL" });
     expect(JSON.stringify(other.get())).not.toContain("secret");
   });
 });
+
+test("usage policy persists across restart and live reload", async () => {
+  const paseoHome = mkdtempSync(path.join(tmpdir(), "usage-policy-"));
+  try {
+    const initial = reloadableConfig({});
+    const store = new DaemonConfigStore(paseoHome, initial, undefined, {
+      reloadSource: {
+        resolve: (persisted) => ({
+          mutable: reloadableConfig(persisted),
+          overrideControlledPaths: [],
+        }),
+      },
+    });
+    await store.patch({ usage: { enabled: false } });
+    expect(loadConfig(paseoHome, { env: {} }).usageEnabled).toBe(false);
+    const persisted = loadPersistedConfig(paseoHome);
+    const restarted = new DaemonConfigStore(paseoHome, reloadableConfig(persisted));
+    expect(restarted.get().usage).toEqual({ enabled: false });
+    writeFileSync(
+      path.join(paseoHome, "config.json"),
+      JSON.stringify({ daemon: { usage: { enabled: true } } }),
+    );
+    await store.reload();
+    expect(store.get().usage).toEqual({ enabled: true });
+  } finally {
+    rmSync(paseoHome, { recursive: true, force: true });
+  }
+});
diff --git a/packages/server/src/server/daemon-config-store.ts b/packages/server/src/server/daemon-config-store.ts
index 51957e15f6..e83874235f 100644
--- a/packages/server/src/server/daemon-config-store.ts
+++ b/packages/server/src/server/daemon-config-store.ts
@@ -1,6 +1,7 @@
 import {
   loadPersistedConfig,
-  savePersistedConfig,
+  savePersistedConfigAsync,
+  loadPersistedConfigAsync,
   type PersistedConfig,
 } from "./persisted-config.js";
 import { ProviderOverrideSchema } from "./agent/provider-launch-config.js";
@@ -21,6 +22,7 @@ type ProviderOverride = import("./agent/provider-launch-config.js").ProviderOver
 interface SupportedMutableConfigPatch {
   relay?: { enabled?: boolean; requireProtectedSecurity?: boolean };
   mcp?: { injectIntoAgents?: boolean };
+  usage?: { enabled: boolean };
   browserTools?: { enabled?: boolean };
   providers?: MutableDaemonConfig["providers"];
   removeProviders?: string[];
@@ -28,6 +30,8 @@ interface SupportedMutableConfigPatch {
   autoArchiveAfterMerge?: boolean;
   enableTerminalAgentHooks?: boolean;
   idleRuntimeCleanup?: boolean;
+  resumeOnStartup?: boolean;
+  resumePrompt?: string;
   appendSystemPrompt?: string;
   terminalProfiles?: MutableDaemonConfig["terminalProfiles"];
   agentProfiles?: MutableDaemonConfig["agentProfiles"];
@@ -179,6 +183,7 @@ const RELOADABLE_PATHS = [
   "daemon.relay.requireProtectedSecurity",
   "daemon.mcp.enabled",
   "daemon.mcp.injectIntoAgents",
+  "daemon.usage.enabled",
   "daemon.browserTools.enabled",
   "daemon.hostnames",
   "daemon.cors.allowedOrigins",
@@ -192,6 +197,8 @@ const RELOADABLE_PATHS = [
   "daemon.agentProfiles",
   "app.baseUrl",
   "agents.idleRuntimeCleanup",
+  "agents.resumeOnStartup",
+  "agents.resumePrompt",
   "agents.providers",
   "agents.catalogRefreshTimeoutMs",
   "agents.metadataGeneration",
@@ -204,6 +211,7 @@ const PERSISTED_TO_MUTABLE_PATH = new Map<string, string>([
   ["daemon.relay.requireProtectedSecurity", "relay.requireProtectedSecurity"],
   ["daemon.mcp.enabled", "mcp.enabled"],
   ["daemon.mcp.injectIntoAgents", "mcp.injectIntoAgents"],
+  ["daemon.usage.enabled", "usage.enabled"],
   ["daemon.browserTools.enabled", "browserTools.enabled"],
   ["daemon.hostnames", "hostnames"],
   ["daemon.cors.allowedOrigins", "cors.allowedOrigins"],
@@ -217,6 +225,8 @@ const PERSISTED_TO_MUTABLE_PATH = new Map<string, string>([
   ["daemon.agentProfiles", "agentProfiles"],
   ["app.baseUrl", "app.baseUrl"],
   ["agents.idleRuntimeCleanup", "idleRuntimeCleanup"],
+  ["agents.resumeOnStartup", "resumeOnStartup"],
+  ["agents.resumePrompt", "resumePrompt"],
   ["agents.providers", "providers"],
   ["agents.catalogRefreshTimeoutMs", "catalogRefreshTimeoutMs"],
   ["agents.metadataGeneration", "metadataGeneration"],
@@ -274,6 +284,7 @@ function pickRelayPatch(
 function pickSupportedPatchFields(patch: MutableDaemonConfigPatch): SupportedMutableConfigPatch {
   return {
     ...pickRelayPatch(patch.relay),
+    usage: patch.usage,
     ...(patch.mcp?.injectIntoAgents !== undefined
       ? { mcp: { injectIntoAgents: patch.mcp.injectIntoAgents } }
       : {}),
@@ -291,6 +302,8 @@ function pickSupportedPatchFields(patch: MutableDaemonConfigPatch): SupportedMut
     ...(patch.enableTerminalAgentHooks !== undefined
       ? { enableTerminalAgentHooks: patch.enableTerminalAgentHooks }
       : {}),
+    ...(patch.resumeOnStartup !== undefined ? { resumeOnStartup: patch.resumeOnStartup } : {}),
+    ...(patch.resumePrompt !== undefined ? { resumePrompt: patch.resumePrompt } : {}),
     ...(patch.idleRuntimeCleanup !== undefined
       ? { idleRuntimeCleanup: patch.idleRuntimeCleanup }
       : {}),
@@ -335,6 +348,7 @@ export function applyMutableProviderConfigToOverrides(
 }
 
 export class DaemonConfigStore {
+  private mutations: Promise<unknown> = Promise.resolve();
   private current: MutableDaemonConfig;
   private readonly paseoHome: string;
   private readonly logger: LoggerLike | undefined;
@@ -376,16 +390,29 @@ export class DaemonConfigStore {
     return this.current;
   }
 
-  public patch(partial: MutableDaemonConfigPatch): MutableDaemonConfig {
-    const parsedPatch = pickSupportedPatchFields(MutableDaemonConfigPatchSchema.parse(partial));
-    return this.applySupportedPatch(parsedPatch);
+  public patch(
+    partial:
+      | MutableDaemonConfigPatch
+      | ((current: MutableDaemonConfig) => MutableDaemonConfigPatch),
+  ): Promise<MutableDaemonConfig> {
+    return this.enqueue(() =>
+      this.applySupportedPatch(
+        pickSupportedPatchFields(
+          MutableDaemonConfigPatchSchema.parse(
+            typeof partial === "function" ? partial(this.current) : partial,
+          ),
+        ),
+      ),
+    );
   }
 
-  public setAgentSkillSelection(selection: AgentSkillSelection): MutableDaemonConfig {
-    return this.applySupportedPatch({ skills: { selection } });
+  public setAgentSkillSelection(selection: AgentSkillSelection): Promise<MutableDaemonConfig> {
+    return this.enqueue(() => this.applySupportedPatch({ skills: { selection } }));
   }
 
-  private applySupportedPatch(parsedPatch: SupportedMutableConfigPatch): MutableDaemonConfig {
+  private async applySupportedPatch(
+    parsedPatch: SupportedMutableConfigPatch,
+  ): Promise<MutableDaemonConfig> {
     if (parsedPatch.relay?.enabled !== undefined && !this.relayEnabledMutable) {
       throw new Error(
         "Relay is controlled by a daemon launch override. Remove PASEO_RELAY_ENABLED or the relay CLI flag before changing it here.",
@@ -414,7 +441,7 @@ export class DaemonConfigStore {
       return this.current;
     }
 
-    const { previous: persistedBeforePatch, knownNext } = this.persistConfig(
+    const { previous: persistedBeforePatch, knownNext } = await this.persistConfig(
       patch,
       removedProviders,
     );
@@ -423,7 +450,7 @@ export class DaemonConfigStore {
       try {
         this.applyReplacement(next, { removedProviders });
       } catch (error) {
-        savePersistedConfig(this.paseoHome, persistedBeforePatch, this.logger);
+        await savePersistedConfigAsync(this.paseoHome, persistedBeforePatch, this.logger);
         throw error;
       }
     }
@@ -454,12 +481,16 @@ export class DaemonConfigStore {
     );
   }
 
-  public reload(): DaemonConfigReloadResult {
+  public reload(): Promise<DaemonConfigReloadResult> {
+    return this.enqueue(() => this.reloadPersisted());
+  }
+
+  private async reloadPersisted(): Promise<DaemonConfigReloadResult> {
     if (!this.reloadSource) {
       throw new Error("Daemon config reload is unavailable for this daemon instance");
     }
 
-    const persisted = loadPersistedConfig(this.paseoHome, this.logger);
+    const persisted = await loadPersistedConfigAsync(this.paseoHome, this.logger);
     const resolved = this.reloadSource.resolve(persisted);
     // Plugin source changes require the plugin lifecycle operation or a daemon
     // restart. The global switch is independently reloadable.
@@ -621,11 +652,24 @@ export class DaemonConfigStore {
     };
   }
 
-  private persistConfig(
+  private enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.mutations.then(operation);
+    this.mutations = result.catch(() => {});
+    return result;
+  }
+
+  public readServicePorts(): Promise<NonNullable<PersistedConfig["worktrees"]>["servicePorts"]> {
+    return this.enqueue(
+      async () =>
+        (await loadPersistedConfigAsync(this.paseoHome, this.logger)).worktrees?.servicePorts,
+    );
+  }
+
+  private async persistConfig(
     patch: Omit<SupportedMutableConfigPatch, "removeProviders">,
     removeProviders: readonly string[],
-  ): { previous: PersistedConfig; knownNext: PersistedConfig } {
-    const persisted = loadPersistedConfig(this.paseoHome, this.logger);
+  ): Promise<{ previous: PersistedConfig; knownNext: PersistedConfig }> {
+    const persisted = await loadPersistedConfigAsync(this.paseoHome, this.logger);
     const merge = (source: PersistedConfig) =>
       mergeMutablePatchIntoPersistedConfig({
         persisted: source,
@@ -635,7 +679,7 @@ export class DaemonConfigStore {
       });
     const nextPersisted = merge(persisted);
     const knownNext = merge(this.lastKnownPersisted);
-    savePersistedConfig(this.paseoHome, nextPersisted, this.logger);
+    await savePersistedConfigAsync(this.paseoHome, nextPersisted, this.logger);
     return { previous: persisted, knownNext };
   }
 }
@@ -670,6 +714,7 @@ function mergeMutableAgentPatch(
     patch.providers === undefined &&
     patch.metadataGeneration === undefined &&
     patch.skills === undefined &&
+    !hasRestartRecoveryPatch(patch) &&
     patch.idleRuntimeCleanup === undefined &&
     removeProviders.length === 0
   ) {
@@ -703,6 +748,7 @@ function mergeMutableAgentPatch(
     next["skills"] = { selection: patch.skills.selection };
   }
 
+  Object.assign(next, restartRecoveryPatch(patch));
   if (patch.idleRuntimeCleanup !== undefined) {
     next["idleRuntimeCleanup"] = patch.idleRuntimeCleanup;
   }
@@ -725,6 +771,7 @@ function mergeMutableDaemonPatch(
   if (patch.mcp?.injectIntoAgents !== undefined) {
     next.mcp = { ...next.mcp, injectIntoAgents: patch.mcp.injectIntoAgents };
   }
+  if (patch.usage) next.usage = patch.usage;
   if (patch.browserTools?.enabled !== undefined) {
     next.browserTools = { ...next.browserTools, enabled: patch.browserTools.enabled };
   }
@@ -739,3 +786,13 @@ function mergeMutableDaemonPatch(
   if (patch.agentProfiles !== undefined) next.agentProfiles = patch.agentProfiles;
   return Object.keys(next).length > 0 ? next : undefined;
 }
+
+function hasRestartRecoveryPatch(patch: SupportedMutableConfigPatch) {
+  return patch.resumeOnStartup !== undefined || patch.resumePrompt !== undefined;
+}
+function restartRecoveryPatch(patch: SupportedMutableConfigPatch) {
+  return {
+    ...(patch.resumeOnStartup !== undefined ? { resumeOnStartup: patch.resumeOnStartup } : {}),
+    ...(patch.resumePrompt !== undefined ? { resumePrompt: patch.resumePrompt } : {}),
+  };
+}
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/background-subagent-action-log.real.e2e.test.ts b/packages/server/src/server/daemon-e2e/background-subagent-action-log.real.e2e.test.ts
index 7eba32f22a..557f8360de 100644
--- a/packages/server/src/server/daemon-e2e/background-subagent-action-log.real.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/background-subagent-action-log.real.e2e.test.ts
@@ -1,6 +1,3 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { fileURLToPath } from "node:url";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -10,7 +7,7 @@ import { ClaudeAgentClient } from "../agent/providers/claude/agent.js";
 import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
 import { DaemonClient } from "../test-utils/daemon-client.js";
 
-test("background cards retain child actions after the parent finishes (#6253)", async () => {
+test("background children keep their actions after the parent finishes (#6253)", async () => {
   const cwd = mkdtempSync(path.join(tmpdir(), "paseo-background-card-"));
   const logger = pino({ level: "silent" });
   const daemon = await createTestPaseoDaemon({
@@ -62,22 +59,6 @@ test("background cards retain child actions after the parent finishes (#6253)",
       limit: 0,
       projection: "projected",
     });
-    const { stdout } = await promisify(execFile)(
-      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,
-      ],
-      { env: { ...process.env, PASEO_HOME: daemon.paseoHome }, timeout: 30_000 },
-    );
-    expect(stdout).toContain("[Bash] ls -1");
-    expect(stdout).toContain("[Bash] pwd");
     expect(
       atFinish.entries.filter(
         (row) => row.item.type === "tool_call" && row.item.detail?.type === "sub_agent",
@@ -94,9 +75,6 @@ test("background cards retain child actions after the parent finishes (#6253)",
         ),
       ).toBe(true);
     }
-    for (const card of cards) {
-      expect(card.detail?.type === "sub_agent" ? card.detail.log : "").toContain("[Bash]");
-    }
   } finally {
     await client.close();
     await daemon.close();
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 09da7506c9..56e7cdefb8 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
@@ -1,6 +1,7 @@
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { rm } from "node:fs/promises";
+import { rm, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { expect, test } from "vitest";
@@ -87,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-"));
 
@@ -111,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}`);
@@ -122,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 });
@@ -223,3 +220,76 @@ test("All changes subscriptions refresh on file edits and commits", async () =>
     await rm(cwd, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
   }
 }, 60_000);
+
+test("large source diffs stay renderable for reads, subscriptions, and commit files", async () => {
+  const ctx = await createDaemonTestContext();
+  const cwd = mkdtempSync(join(tmpdir(), "checkout-diff-budget-"));
+  const runGit = promisify(execFile);
+  try {
+    git(cwd, "init", "-b", "main");
+    git(cwd, "config", "user.name", "Test");
+    git(cwd, "config", "user.email", "test@example.com");
+    git(cwd, "config", "core.autocrlf", "false");
+    const original = "const value = Math.max(42, 7);\n".repeat(Math.ceil((5 * 1024 * 1024) / 30));
+    writeFileSync(join(cwd, "generated.ts"), original);
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "initial");
+    await writeFile(join(cwd, "generated.ts"), original.replace("42", "43"));
+    const pending = ctx.client.getCheckoutDiff(cwd, { mode: "uncommitted" });
+    const rpcStarted = performance.now();
+    await ctx.client.fetchAgents({});
+    const rpcMs = performance.now() - rpcStarted;
+    const initial = await pending;
+    expect(initial.error).toBeNull();
+    const check = (file: (typeof initial.files)[number] | null | undefined, value: string) => {
+      expect(file).toMatchObject({ path: "generated.ts", additions: 1, deletions: 1 });
+      const lines = file!.hunks.flatMap((hunk) => hunk.lines);
+      expect(lines.filter((line) => line.type === "add").map((line) => line.content)).toEqual([
+        `const value = Math.max(${value}, 7);`,
+      ]);
+      expect(lines.find((line) => line.type === "add")?.tokens).toContainEqual({
+        text: value,
+        style: "number",
+      });
+    };
+    check(initial.files[0], "43");
+    const subscription = ctx.client.observeCheckoutDiff(cwd, { mode: "uncommitted" });
+    try {
+      let latest = await subscription.ready;
+      check(latest.files[0], "43");
+      subscription.subscribe({
+        snapshot: (snapshot) => {
+          latest = snapshot;
+        },
+        update: (message) => {
+          if (message.type === "checkout_diff_update") latest = message.payload;
+        },
+      });
+      await writeFile(join(cwd, "generated.ts"), original.replace("42", "44"));
+      await expect
+        .poll(
+          () =>
+            latest.files[0]?.hunks.flatMap((hunk) => hunk.lines).find((line) => line.type === "add")
+              ?.content,
+          { timeout: 15_000 },
+        )
+        .toBe("const value = Math.max(44, 7);");
+      check(latest.files[0], "44");
+    } finally {
+      await subscription.release();
+    }
+    await runGit("git", ["add", "."], { cwd });
+    await runGit("git", ["-c", "commit.gpgsign=false", "commit", "-m", "edit"], { cwd });
+    const { stdout } = await runGit("git", ["rev-parse", "HEAD"], { cwd });
+    const commit = await ctx.client.getCommitFileDiff(cwd, stdout.trim(), "generated.ts");
+    check(commit.file, "44");
+    console.info({
+      sourceBytes: Buffer.byteLength(original),
+      cheapRpcMs: rpcMs,
+      isolatedDaemonPort: ctx.daemon.port,
+    });
+  } finally {
+    await ctx.cleanup();
+    await rm(cwd, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  }
+}, 60_000);
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 d8388f9dd2..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";
 
@@ -87,3 +90,275 @@ test("logs --follow preserves the same assistant text as one-shot logs", async (
     await daemon.close();
   }
 }, 60_000);
+
+test("omitted after limit pages forward while explicit zero preserves complete CLI history", async () => {
+  const daemon = await createTestPaseoDaemon();
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    const agent = await client.createAgent({ provider: "claude", cwd: daemon.paseoHome });
+    const initial = await client.fetchAgentTimeline(agent.id, { direction: "tail", limit: 0 });
+    const cursor = { epoch: initial.epoch, seq: initial.window.maxSeq };
+    for (let index = 0; index < 451; index++) {
+      await daemon.daemon.agentManager.appendTimelineItem(agent.id, {
+        type: "user_message",
+        text: String(index),
+      });
+    }
+    const first = await client.fetchAgentTimeline(agent.id, { direction: "after", cursor });
+    expect(first.entries).toHaveLength(200);
+    expect(first.hasNewer).toBe(true);
+    expect(first.endCursor).toEqual({ epoch: cursor.epoch, seq: cursor.seq + 200 });
+    const second = await client.fetchAgentTimeline(agent.id, {
+      direction: "after",
+      cursor: first.endCursor!,
+    });
+    const third = await client.fetchAgentTimeline(agent.id, {
+      direction: "after",
+      cursor: second.endCursor!,
+    });
+    expect(second.entries).toHaveLength(200);
+    expect(third.entries).toHaveLength(51);
+    expect(third.hasNewer).toBe(false);
+    expect(
+      [...first.entries, ...second.entries, ...third.entries].map((entry) => entry.item),
+    ).toEqual(
+      Array.from({ length: 451 }, (_, index) => ({ type: "user_message", text: String(index) })),
+    );
+    const allAfter = await client.fetchAgentTimeline(agent.id, {
+      direction: "after",
+      cursor,
+      limit: 0,
+    });
+    const allTail = await client.fetchAgentTimeline(agent.id, { direction: "tail", limit: 0 });
+    expect(allAfter.entries).toHaveLength(451);
+    expect(allAfter.hasNewer).toBe(false);
+    expect(allTail.entries).toHaveLength(initial.entries.length + 451);
+  } finally {
+    await client.close();
+    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/codex-steer-starting.real.e2e.test.ts b/packages/server/src/server/daemon-e2e/codex-steer-starting.real.e2e.test.ts
new file mode 100644
index 0000000000..60508205f2
--- /dev/null
+++ b/packages/server/src/server/daemon-e2e/codex-steer-starting.real.e2e.test.ts
@@ -0,0 +1,80 @@
+import { expect, test } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import pino from "pino";
+
+import { CodexAppServerAgentClient } from "../agent/providers/codex-app-server-agent.js";
+import { DaemonClient } from "../test-utils/daemon-client.js";
+import { createMessageCollector } from "../test-utils/message-collector.js";
+import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
+import { canRunRealProvider } from "./real-provider-test-config.js";
+
+test("keeps two concurrent startup steer messages in one real Codex turn", async (context) => {
+  if (!(await canRunRealProvider("codex"))) {
+    context.skip();
+    return;
+  }
+  const cwd = mkdtempSync(path.join(tmpdir(), "codex-steer-starting-"));
+  const logger = pino({ level: "silent" });
+  const daemon = await createTestPaseoDaemon({
+    agentClients: { codex: new CodexAppServerAgentClient(logger) },
+    logger,
+  });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  const collector = createMessageCollector(client);
+  const subscriptions: ReturnType<DaemonClient["subscribeAgentTimeline"]>[] = [];
+  try {
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const agent = await client.createAgent({
+        cwd,
+        provider: "codex",
+        modeId: "full-access",
+      });
+      const subscription = client.subscribeAgentTimeline(agent.id, () => {});
+      subscriptions.push(subscription);
+      await subscription.ready;
+      await Promise.all([
+        client.sendAgentMessage(agent.id, "Reply exactly: FIRST", {
+          messageId: `first-${attempt}`,
+          activeTurnBehavior: "steer",
+        }),
+        client.sendAgentMessage(agent.id, "Reply exactly: SECOND", {
+          messageId: `second-${attempt}`,
+          activeTurnBehavior: "steer",
+        }),
+      ]);
+      await client.waitForFinish(agent.id, 90_000);
+      const timeline = await client.fetchAgentTimeline(agent.id, { limit: 100 });
+      const users = timeline.entries.filter((entry) => entry.item.type === "user_message");
+      const events = collector.messages.flatMap((message) =>
+        message.type === "agent_stream" && message.payload.agentId === agent.id
+          ? [message.payload.event]
+          : [],
+      );
+      expect(users.map((entry) => entry.item.text).sort()).toEqual([
+        "Reply exactly: FIRST",
+        "Reply exactly: SECOND",
+      ]);
+      expect(new Set(users.map((entry) => entry.turnId)).size).toBe(1);
+      expect(events.filter((event) => event.type === "turn_started")).toHaveLength(1);
+      expect(
+        events.filter((event) => event.type === "turn_canceled" || event.type === "turn_failed"),
+      ).toHaveLength(0);
+      expect(
+        timeline.entries.some(
+          (entry) =>
+            entry.item.type === "assistant_message" && entry.item.text.includes("[System Error]"),
+        ),
+      ).toBe(false);
+    }
+  } finally {
+    await Promise.all(subscriptions.map((subscription) => subscription.release()));
+    collector.unsubscribe();
+    await client.close();
+    await daemon.close();
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}, 300_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 efc99c9b59..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
@@ -76,10 +76,14 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { DaemonClient } from "../test-utils/daemon-client.js";
 
-async function restartFixture(root: string) {
+async function restartFixture(
+  root: string,
+  settings: { resumeOnStartup?: boolean; resumePrompt?: string } = {},
+  fixture: { holdResume?: boolean } = {},
+) {
   const child = fork(
     fileURLToPath(new URL("../test-utils/finish-subscription-daemon.ts", import.meta.url)),
-    [root],
+    [root, JSON.stringify(settings), JSON.stringify(fixture)],
     {
       execArgv: ["--conditions=source", "--import", "tsx"],
       stdio: ["ignore", "pipe", "pipe", "ipc"],
@@ -130,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();
@@ -178,12 +182,30 @@ 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);
       expect(prompts[0]).toContain(`Agent ${childId}`);
-      expect(prompts[0]).toContain("was closed");
+      expect(prompts[0]).not.toContain("was closed");
+      const recoveredPrompts = (await readFile(path.join(root, "all-prompts.jsonl"), "utf8"))
+        .trim()
+        .split("\n")
+        .map((line) => JSON.parse(line));
+      expect(recoveredPrompts.filter((entry) => entry.prompt === "Resume working.")).toHaveLength(
+        1,
+      );
+      const restored = recoveredPrompts.find((entry) => entry.prompt === "Resume working.").config;
+      const original = recoveredPrompts.find((entry) =>
+        String(entry.prompt).includes("HOLD_CHILD"),
+      ).config;
+      expect(restored).toMatchObject({
+        provider: original.provider,
+        model: original.model,
+        modeId: original.modeId,
+        cwd: original.cwd,
+      });
+
       await expect
         .poll(
           async () =>
@@ -196,11 +218,11 @@ test.each([false, true])(
       client = new DaemonClient({ url: `ws://127.0.0.1:${second.port}/ws`, appVersion: "0.13.0" });
       await client.connect();
       await client.fetchAgents({ subscribe: {} });
-      expect((await client.fetchAgent(childId))?.agent.status).toBe("closed");
+      expect((await client.fetchAgent(childId))?.agent.status).toBe("idle");
       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(
@@ -220,3 +242,120 @@ test.each([false, true])(
   },
   60000,
 );
+
+test.each([undefined, false, true])(
+  "host restart recovery settings (enabled=%s)",
+  async (enabled) => {
+    const root = await mkdtemp(path.join(tmpdir(), "resume-settings-process-"));
+    const processes: ChildProcess[] = [];
+    let client: DaemonClient | undefined;
+    const settings = { resumeOnStartup: enabled, resumePrompt: "Continue exactly.\n" };
+    try {
+      const first = await restartFixture(root, settings);
+      processes.push(first.child);
+      client = new DaemonClient({ url: `ws://127.0.0.1:${first.port}/ws`, appVersion: "0.13.0" });
+      await client.connect();
+      const working = await client.createAgent({
+        provider: "claude",
+        cwd: first.cwd,
+        modeId: "full-access",
+      });
+      const idle = await client.createAgent({
+        provider: "claude",
+        cwd: first.cwd,
+        modeId: "full-access",
+      });
+      await client.sendMessage(working.id, "HOLD_CHILD");
+      await expect
+        .poll(
+          async () =>
+            (
+              await new AgentStorage(path.join(first.paseoHome, "agents"), createTestLogger()).get(
+                working.id,
+              )
+            )?.lastStatus,
+        )
+        .toBe("running");
+      const original = await new AgentStorage(
+        path.join(first.paseoHome, "agents"),
+        createTestLogger(),
+      ).get(working.id);
+      await client.close();
+      client = undefined;
+      await stopFixture(first.child, false);
+      const second = await restartFixture(root, settings);
+      processes.push(second.child);
+      client = new DaemonClient({ url: `ws://127.0.0.1:${second.port}/ws`, appVersion: "0.13.0" });
+      await client.connect();
+      const storage = new AgentStorage(path.join(second.paseoHome, "agents"), createTestLogger());
+      // Resume runs in the background; it is done once the saved intent is consumed.
+      await expect.poll(async () => (await storage.get(working.id))?.resumeOnStartup).toBe(false);
+      const resumePrompts = async () =>
+        (await readFile(path.join(root, "all-prompts.jsonl"), "utf8"))
+          .trim()
+          .split("\n")
+          .map((line) => JSON.parse(line))
+          .filter((entry) => entry.prompt === settings.resumePrompt);
+      await expect.poll(resumePrompts).toHaveLength(enabled ? 1 : 0);
+      expect((await client.fetchAgent(idle.id))?.agent.status).toBe("closed");
+      const restored = await storage.get(working.id);
+      expect(restored?.persistence?.sessionId).toBe(original?.persistence?.sessionId);
+    } finally {
+      await client?.close();
+      for (const child of processes.toReversed()) await stopFixture(child, true);
+      await rm(root, { recursive: true, force: true });
+    }
+  },
+  60000,
+);
+
+test("a provider that is slow to reopen does not hold daemon startup", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "resume-background-process-"));
+  const processes: ChildProcess[] = [];
+  let client: DaemonClient | undefined;
+  try {
+    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();
+    const working = await client.createAgent({
+      provider: "claude",
+      cwd: first.cwd,
+      modeId: "full-access",
+    });
+    await client.sendMessage(working.id, "HOLD_CHILD");
+    await expect
+      .poll(
+        async () =>
+          (
+            await new AgentStorage(path.join(first.paseoHome, "agents"), createTestLogger()).get(
+              working.id,
+            )
+          )?.lastStatus,
+      )
+      .toBe("running");
+    await client.close();
+    client = undefined;
+    await stopFixture(first.child, false);
+
+    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();
+    expect((await client.fetchAgent(working.id))?.agent.id).toBe(working.id);
+    second.child.send("release-resume");
+    await expect
+      .poll(async () =>
+        (await readFile(path.join(root, "all-prompts.jsonl"), "utf8"))
+          .trim()
+          .split("\n")
+          .map((line) => JSON.parse(line).prompt)
+          .filter((prompt) => prompt === "Resume working."),
+      )
+      .toHaveLength(1);
+  } finally {
+    await client?.close();
+    for (const child of processes.toReversed()) await stopFixture(child, true);
+    await rm(root, { recursive: true, force: true });
+  }
+}, 30000);
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/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/oversized-timeline.e2e.test.ts b/packages/server/src/server/daemon-e2e/oversized-timeline.e2e.test.ts
new file mode 100644
index 0000000000..bc78db2eab
--- /dev/null
+++ b/packages/server/src/server/daemon-e2e/oversized-timeline.e2e.test.ts
@@ -0,0 +1,46 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "vitest";
+import { createDaemonTestContext } from "../test-utils/index.js";
+
+// #2220: a timeline page is one WebSocket message, so a few huge entries used to close the socket.
+test.each([40, 0])(
+  "fetching image-heavy history with limit %i keeps the direct connection usable",
+  async (limit) => {
+    const ctx = await createDaemonTestContext();
+    const cwd = mkdtempSync(path.join(tmpdir(), "oversized-timeline-"));
+    try {
+      const agent = await ctx.client.createAgent({ provider: "codex", cwd });
+      const imageUrl = `data:image/jpeg;base64,${"A".repeat(14 * 1024 * 1024)}`;
+      for (let index = 0; index < 5; index += 1) {
+        await ctx.daemon.daemon.agentManager.appendTimelineItem(agent.id, {
+          type: "tool_call",
+          callId: `screenshot-${index}`,
+          name: "node_repl.js",
+          status: "completed",
+          error: null,
+          detail: {
+            type: "unknown",
+            input: { index },
+            output: { _meta: { "codex/toolSurface": { screenshot: { url: imageUrl } } } },
+          },
+        });
+      }
+
+      const page = await ctx.client.fetchAgentTimeline(agent.id, { direction: "tail", limit });
+      const screenshots = page.entries.filter((entry) => entry.item.type === "tool_call");
+      expect(screenshots).toHaveLength(5);
+      for (const entry of screenshots) {
+        expect(Buffer.byteLength(JSON.stringify(entry.item))).toBeLessThanOrEqual(64 * 1024);
+      }
+
+      const next = await ctx.client.fetchAgentTimeline(agent.id, { direction: "tail", limit: 1 });
+      expect(next.entries).toHaveLength(1);
+    } finally {
+      await ctx.cleanup();
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  },
+  60_000,
+);
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/relay-transport.e2e.test.ts b/packages/server/src/server/daemon-e2e/relay-transport.e2e.test.ts
index 32d3a1f36c..f47accaa55 100644
--- a/packages/server/src/server/daemon-e2e/relay-transport.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/relay-transport.e2e.test.ts
@@ -9,7 +9,7 @@ import {
 } from "@getpaseo/protocol/binary-frames/index";
 import {
   getDaemonAuthFailureReason,
-  type DaemonClient as HostClient,
+  DaemonClient as HostClient,
 } from "@getpaseo/client/internal/daemon-client";
 import type { SessionOutboundMessage } from "@getpaseo/protocol/messages";
 import { describe, expect, test } from "vitest";
@@ -593,72 +593,112 @@ async function waitForCapturedLog(
     }
   }, 90000);
 
-  test("oversized attachments fail without disconnecting or resubmitting over the relay", async () => {
-    await startRelay({ useLocalRelay: true });
-    const daemon = await createTestPaseoDaemon({
-      relayEnabled: true,
-      relayEndpoint: `127.0.0.1:${relayPort}`,
-      relayUseTls: false,
-      relayPublicUseTls: false,
-    });
-    let client: DaemonClient | null = null;
-    try {
-      const offerUrl = await getPairingOfferUrl({
-        paseoHome: daemon.paseoHome,
+  test.each([true, false])(
+    "large messages cross the relay with unpaced upload admission preserved (supportsDrain=%s)",
+    async (supportsDrain) => {
+      await startRelay({ useLocalRelay: true });
+      const daemon = await createTestPaseoDaemon({
         relayEnabled: true,
-        relayEndpoint: daemon.config.relayEndpoint,
+        relayEndpoint: `127.0.0.1:${relayPort}`,
+        relayUseTls: false,
+        relayPublicUseTls: false,
       });
-      const { serverId, daemonPublicKeyB64 } = decodeOfferFromFragmentUrl(offerUrl);
-      client = new DaemonClient({
-        url: buildRelayWebSocketUrl({
-          endpoint: `127.0.0.1:${relayPort}`,
-          useTls: false,
-          serverId,
-          role: "client",
-        }),
-        e2ee: { enabled: true, daemonPublicKeyB64 },
-        reconnect: { baseDelayMs: 100, maxDelayMs: 100 },
-      });
-      await client.connect();
-      const statuses: string[] = [];
-      client.subscribeConnectionStatus((state) => statuses.push(state.status));
-      for (const imageMiB of [30, 61]) {
-        // Attachments are base64 in the JSON, then E2EE base64 expands the frame again.
-        const images = [
-          { data: "A".repeat(4 * Math.ceil((imageMiB * 1024 * 1024) / 3)), mimeType: "image/png" },
-        ];
+      let client: HostClient | null = null;
+      try {
+        const offerUrl = await getPairingOfferUrl({
+          paseoHome: daemon.paseoHome,
+          relayEnabled: true,
+          relayEndpoint: daemon.config.relayEndpoint,
+        });
+        const { serverId, daemonPublicKeyB64 } = decodeOfferFromFragmentUrl(offerUrl);
+        client = new HostClient({
+          clientId: "paced-relay-regression",
+          webSocketFactory: Object.assign((url: string) => new WebSocket(url), { supportsDrain }),
+          url: buildRelayWebSocketUrl({
+            endpoint: `127.0.0.1:${relayPort}`,
+            useTls: false,
+            serverId,
+            role: "client",
+          }),
+          e2ee: { enabled: true, daemonPublicKeyB64 },
+          reconnect: { baseDelayMs: 100, maxDelayMs: 100 },
+        });
+        await client.connect();
+        const statuses: string[] = [];
+        client.subscribeConnectionStatus((state) => statuses.push(state.status));
+        for (const imageMiB of [30, 61]) {
+          const images = [
+            {
+              data: "A".repeat(4 * Math.ceil((imageMiB * 1024 * 1024) / 3)),
+              mimeType: "image/png",
+            },
+          ];
+          const creation = client.createWorkspace({
+            source: { kind: "directory", path: daemon.staticDir },
+            agent: {
+              provider: "claude",
+              cwd: daemon.staticDir,
+              initialPrompt: "Describe these screens.",
+              images,
+            },
+          });
+          if (supportsDrain)
+            await withTimeout(creation, 30000, "Chunked workspace creation did not settle");
+          else await expect(creation).rejects.toThrow(/too large.*32\.0 MiB/);
+        }
+        expect((await client.fetchAgents()).entries).toHaveLength(supportsDrain ? 2 : 0);
         await expect(
-          withTimeout(
-            client.createWorkspace({
-              source: { kind: "directory", path: daemon.staticDir },
-              agent: {
-                provider: "claude",
-                cwd: daemon.staticDir,
-                initialPrompt: "Describe these screens.",
-                images,
-              },
-            }),
-            10000,
-            "Workspace creation did not settle",
-          ),
-        ).rejects.toThrow(/too large.*32\.0 MiB/);
-        expect((await client.fetchAgents()).entries).toEqual([]);
-      }
-      const agent = await client.createAgent({ provider: "claude", cwd: daemon.staticDir });
-      await expect(
-        client.sendMessage(agent.id, "Describe these screens.", {
+          client.createWorkspace({
+            source: { kind: "directory", path: daemon.staticDir },
+            agent: {
+              provider: "claude",
+              cwd: daemon.staticDir,
+              initialPrompt: "Describe these screens.",
+              images: [{ data: "A".repeat(101 * 1024 * 1024), mimeType: "image/png" }],
+            },
+          }),
+        ).rejects.toThrow(/too large.*100\.0 MiB/);
+        expect((await client.fetchAgents()).entries).toHaveLength(supportsDrain ? 2 : 0);
+        const agent = await client.createAgent({ provider: "claude", cwd: daemon.staticDir });
+        const attachment = client.sendMessage(agent.id, "Describe these screens.", {
           images: [{ data: "A".repeat(40 * 1024 * 1024), mimeType: "image/png" }],
-        }),
-      ).rejects.toThrow(/too large.*32\.0 MiB/);
-      await client.sendMessage(agent.id, "A small follow-up still works.");
-      expect((await client.fetchAgents()).entries).toHaveLength(1);
-      expect(statuses).toEqual(["connected"]);
-    } finally {
-      await client?.close();
-      await daemon.close();
-      await stopRelay();
-    }
-  }, 60000);
+        });
+        if (supportsDrain) await attachment;
+        else await expect(attachment).rejects.toThrow(/too large.*32\.0 MiB/);
+        await expect(
+          client.sendMessage(agent.id, "Describe these screens.", {
+            images: [{ data: "A".repeat(101 * 1024 * 1024), mimeType: "image/png" }],
+          }),
+        ).rejects.toThrow(/too large.*100\.0 MiB/);
+        await client.sendMessage(agent.id, "A small follow-up still works.");
+        expect((await client.fetchAgents()).entries).toHaveLength(supportsDrain ? 3 : 1);
+        // Respect the per-item content budget while exceeding the relay frame limit.
+        const text = "x".repeat(240 * 1024);
+        for (let row = 0; row < 220; row++)
+          await daemon.daemon.agentManager.appendTimelineItem(agent.id, {
+            type: "user_message",
+            text,
+          });
+        const timeline = await client.fetchAgentTimeline(agent.id, {
+          projection: "canonical",
+          limit: 0,
+          timeout: 30000,
+        });
+        const delivered = timeline.entries.filter(
+          (row) => row.item.type === "user_message" && row.item.text === text,
+        );
+        expect(delivered).toHaveLength(220);
+        expect(delivered.length * Buffer.byteLength(text)).toBeGreaterThan(50 * 1024 * 1024);
+        await client.ping();
+        expect(statuses).toEqual(["connected"]);
+      } finally {
+        await client?.close();
+        await daemon.close();
+        await stopRelay();
+      }
+    },
+    120000,
+  );
 
   test("daemon connects to relay and client ping/pong works through relay", async () => {
     process.env.PASEO_PRIMARY_LAN_IP = "192.168.1.12";
diff --git a/packages/server/src/server/daemon-e2e/terminal-byte-headless-parity.e2e.test.ts b/packages/server/src/server/daemon-e2e/terminal-byte-headless-parity.e2e.test.ts
index 2b789788ad..ed00f6cd9a 100644
--- a/packages/server/src/server/daemon-e2e/terminal-byte-headless-parity.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/terminal-byte-headless-parity.e2e.test.ts
@@ -7,7 +7,6 @@ import { Terminal as HeadlessTerminal, type IBufferCell, type IBufferLine } from
 import { expect, test } from "vitest";
 
 import type { TerminalCell, TerminalState } from "@getpaseo/protocol/messages";
-import { renderTerminalSnapshotToAnsi } from "@getpaseo/protocol/terminal-snapshot";
 import type { TerminalStreamEvent } from "@getpaseo/client/internal/daemon-client";
 import { DaemonClient } from "../test-utils/daemon-client.js";
 import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
@@ -46,7 +45,7 @@ test("byte-stream headless terminal matches daemon state after high-output attac
       terminalId: terminal.id,
       headless: liveHeadless,
     });
-    const initialSnapshot = waitForTerminalStreamEvent(client, terminal.id, "snapshot");
+    const initialSnapshot = waitForReplayEnd(client, terminal.id);
 
     const liveSubscription = await subscribeTerminal(client, terminal.id);
     await initialSnapshot;
@@ -60,13 +59,13 @@ test("byte-stream headless terminal matches daemon state after high-output attac
       text: BYTE_DONE_MARKER,
       rows: BYTE_TEST_SIZE.rows,
     });
-    const daemonSnapshot = await readTerminalSnapshot({
+    const daemonSnapshot = await readReplayViewport({
       port: daemon.port,
       terminalId: terminal.id,
     });
     await liveHeadless.flush();
 
-    expect(liveHeadless.visibleLines()).toEqual(visibleTerminalLines(daemonSnapshot));
+    expect(liveHeadless.visibleLines()).toEqual(daemonSnapshot.lines);
     expect(liveHeadless.cursor()).toEqual(daemonSnapshot.cursor);
     expect(liveHeadless.visibleLines()).toEqual(capturedViewport.lines);
 
@@ -79,7 +78,7 @@ test("byte-stream headless terminal matches daemon state after high-output attac
       terminalId: terminal.id,
       headless: restoreHeadless,
     });
-    const restoreFrame = waitForTerminalStreamEvent(client, terminal.id, "restore");
+    const restoreFrame = waitForReplayEnd(client, terminal.id);
 
     await subscribeTerminal(client, terminal.id, {
       restore: { mode: "visible-snapshot", scrollbackLines: 200, size: BYTE_TEST_SIZE },
@@ -116,12 +115,10 @@ class ClientHeadlessTerminal {
   }
 
   applyEvent(event: TerminalStreamEvent): void {
-    if (event.type === "snapshot") {
-      this.enqueueText(renderTerminalSnapshotToAnsi(event.state), { resetDecoder: true });
-      return;
-    }
-    if (event.type === "restore") {
-      this.enqueueText(this.decoder.decode(event.data, { stream: false }), { resetDecoder: true });
+    if (event.type === "replay") {
+      if (event.replay.type === "begin") this.enqueueText("\x1bc", { resetDecoder: true });
+      if (event.replay.type === "data")
+        this.enqueueText(this.decoder.decode(event.replay.data, { stream: true }));
       return;
     }
     this.enqueueText(this.decoder.decode(event.data, { stream: true }));
@@ -187,35 +184,32 @@ async function subscribeTerminal(
   return response.subscription;
 }
 
-async function readTerminalSnapshot(input: {
-  port: number;
-  terminalId: string;
-}): Promise<TerminalState> {
-  const client = new DaemonClient({
-    url: `ws://127.0.0.1:${input.port}/ws`,
-    appVersion: "0.1.96",
-    clientType: "mobile",
-  });
+async function readReplayViewport(input: { port: number; terminalId: string }): Promise<{
+  lines: string[];
+  cursor: TerminalState["cursor"];
+}> {
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${input.port}/ws`, clientType: "mobile" });
+  const headless = new ClientHeadlessTerminal(BYTE_TEST_SIZE);
+  const stop = pipeTerminalStreamToHeadless({ client, terminalId: input.terminalId, headless });
   try {
     await client.connect();
-    const snapshot = waitForTerminalStreamEvent(client, input.terminalId, "snapshot");
+    const completed = waitForReplayEnd(client, input.terminalId);
     await subscribeTerminal(client, input.terminalId);
-    const event = await snapshot;
-    return event.state;
+    await completed;
+    await headless.flush();
+    return { lines: headless.visibleLines(), cursor: headless.cursor() };
   } finally {
+    stop();
     await client.close();
   }
 }
 
-function waitForTerminalStreamEvent<TType extends TerminalStreamEvent["type"]>(
-  client: DaemonClient,
-  terminalId: string,
-  type: TType,
-): Promise<Extract<TerminalStreamEvent, { type: TType }>> {
-  return client.waitForTerminalStreamEvent(
-    (event) => event.terminalId === terminalId && event.type === type,
-    10_000,
-  ) as Promise<Extract<TerminalStreamEvent, { type: TType }>>;
+async function waitForReplayEnd(client: DaemonClient, terminalId: string): Promise<void> {
+  await client.waitForTerminalStreamEvent(
+    (event) =>
+      event.terminalId === terminalId && event.type === "replay" && event.replay.type === "end",
+    10000,
+  );
 }
 
 async function createPackageLockTerminalCwd(): Promise<PackageLockTerminalCwd> {
@@ -287,24 +281,16 @@ async function waitForCondition<T>(
   throw new Error(`Timed out after ${timeoutMs}ms waiting for terminal byte parity`);
 }
 
-function visibleTerminalLines(state: TerminalState): string[] {
-  return state.grid.map(terminalRowText);
-}
-
-function terminalRowText(row: TerminalState["grid"][number]): string {
-  return row
-    .map((cell) => cell.char)
-    .join("")
-    .trimEnd();
-}
-
 function bufferLineText(line: IBufferLine | undefined, reusableCell: IBufferCell): string {
   const cells: TerminalCell[] = [];
   for (let col = 0; col < BYTE_TEST_SIZE.cols; col += 1) {
     const cell = line?.getCell(col, reusableCell);
     cells.push({ char: cell?.getChars() || " " });
   }
-  return terminalRowText(cells);
+  return cells
+    .map((cell) => cell.char)
+    .join("")
+    .trimEnd();
 }
 
 function packageLockStreamScript(): string {
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
new file mode 100644
index 0000000000..a9789c906e
--- /dev/null
+++ b/packages/server/src/server/daemon-e2e/terminal-worker-lifecycle.e2e.test.ts
@@ -0,0 +1,683 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { spawn, type ChildProcess } from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { createServer } from "node:net";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+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";
+import { launchTerminalWorker } from "../../terminal/terminal-worker-launch.js";
+import { prepareTerminalWorkerRuntime } from "../../terminal/terminal-worker-runtime.js";
+import { createWorkerTerminalManager } from "../../terminal/worker-terminal-manager.js";
+import {
+  listTerminalWorkerRecords,
+  writeTerminalWorkerRecord,
+  type TerminalWorkerRecord,
+} from "../../terminal/terminal-worker-record.js";
+
+// Real supervisors started through scripts/supervisor-entrypoint.ts, driven by DaemonClient the
+// way the app drives them. Every daemon, worker and program here lives in a throwaway home and
+// is killed in afterEach; nothing touches another daemon.
+
+const SERVER_ROOT = path.resolve(import.meta.dirname, "../../..");
+const SUPERVISOR_ENTRY = path.join(SERVER_ROOT, "scripts/supervisor-entrypoint.ts");
+const READY_TIMEOUT_MS = 90_000;
+const POSIX = process.platform !== "win32";
+const inspector = createTerminalWorkerProcessInspector();
+
+interface Harness {
+  home: string;
+  workDir: string;
+  port: number;
+  supervisor: ChildProcess;
+  output: () => string;
+}
+
+const harnesses: Harness[] = [];
+const extraPids = new Set<number>();
+const extraDirs: string[] = [];
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitFor<T>(
+  probe: () => Promise<T | null | undefined | false> | T | null | undefined | false,
+  message: string,
+  timeoutMs = READY_TIMEOUT_MS,
+): Promise<T> {
+  const deadline = Date.now() + timeoutMs;
+  let lastError: unknown = null;
+  while (Date.now() < deadline) {
+    try {
+      const value = await probe();
+      if (value) return value;
+    } catch (error) {
+      lastError = error;
+    }
+    await delay(100);
+  }
+  throw new Error(`${message}${lastError ? ` (last error: ${String(lastError)})` : ""}`);
+}
+
+async function getAvailablePort(): Promise<number> {
+  const server = createServer();
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
+  const address = server.address();
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  if (!address || typeof address === "string") throw new Error("no port");
+  return address.port;
+}
+
+async function startSupervisor(
+  options: { home?: string; port?: number; pathPrefix?: string } = {},
+): Promise<Harness> {
+  const home = options.home ?? mkdtempSync(path.join(tmpdir(), "tw-life-"));
+  const workDir = path.join(home, "work");
+  mkdirSync(workDir, { recursive: true });
+  const port = options.port ?? (await getAvailablePort());
+  const env: NodeJS.ProcessEnv = {
+    ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("PASEO_"))),
+    HOME: home,
+    USERPROFILE: home,
+    PASEO_HOME: home,
+    PASEO_LISTEN: `127.0.0.1:${port}`,
+    PASEO_RELAY_ENABLED: "false",
+    PASEO_NODE_INSPECT: "0",
+    PASEO_LOCAL_SPEECH_AUTO_DOWNLOAD: "0",
+    PASEO_DICTATION_ENABLED: "0",
+    PASEO_VOICE_MODE_ENABLED: "0",
+    CI: "true",
+  };
+  if (options.pathPrefix) {
+    env.PATH = `${options.pathPrefix}${path.delimiter}${env.PATH ?? ""}`;
+  }
+  let output = "";
+  const supervisor = spawn(
+    process.execPath,
+    ["--import", "tsx", SUPERVISOR_ENTRY, "--dev", "--no-relay"],
+    { cwd: SERVER_ROOT, env, stdio: ["ignore", "pipe", "pipe"] },
+  );
+  supervisor.stdout?.on("data", (chunk) => (output = (output + String(chunk)).slice(-20_000)));
+  supervisor.stderr?.on("data", (chunk) => (output = (output + String(chunk)).slice(-20_000)));
+  const harness: Harness = { home, workDir, port, supervisor, output: () => output };
+  harnesses.push(harness);
+  await waitFor(async () => {
+    const instance = await readDaemonInstance(home);
+    return instance?.pid === supervisor.pid && instance.listen ? instance : null;
+  }, `supervisor did not become ready:\n${output}`);
+  return harness;
+}
+
+async function connect(harness: Harness): Promise<DaemonClient> {
+  return waitFor(async () => {
+    const client = new DaemonClient({
+      url: `ws://127.0.0.1:${harness.port}/ws`,
+      connectTimeoutMs: 5_000,
+    });
+    try {
+      await client.connect();
+      return client;
+    } catch (error) {
+      await client.close().catch(() => undefined);
+      throw error;
+    }
+  }, "cannot connect to the daemon");
+}
+
+// A plain `paseo daemon stop`: SIGTERM on POSIX, the shutdown RPC where there is no signal
+// for it (Windows refuses a graceful stop without one).
+async function stopDaemon(harness: Harness): Promise<void> {
+  await stopDaemonInstance(harness.home, {
+    requestShutdown: async () => {
+      const client = await connect(harness);
+      try {
+        await client.shutdownServer();
+      } finally {
+        await client.close();
+      }
+    },
+  });
+}
+
+async function daemonWorkerPid(client: DaemonClient): Promise<number> {
+  return (await client.getDaemonStatus()).pid;
+}
+
+async function waitForReplacement(harness: Harness, previousPid: number): Promise<DaemonClient> {
+  return waitFor(async () => {
+    const client = await connect(harness);
+    const pid = await daemonWorkerPid(client).catch(() => previousPid);
+    if (pid !== previousPid) return client;
+    await client.close();
+    return null;
+  }, "the daemon worker was not replaced");
+}
+
+async function createWorkspace(client: DaemonClient, harness: Harness): Promise<string> {
+  const result = await client.createWorkspace({
+    source: { kind: "directory", path: harness.workDir },
+    title: "lifecycle",
+  });
+  if (!result.workspace) throw new Error(result.error ?? "workspace creation failed");
+  return result.workspace.id;
+}
+
+interface MarkedTerminal {
+  id: string;
+  programPid: number;
+}
+
+// A terminal whose program writes its pid, prints a marker and echoes each input line.
+async function createMarkedTerminal(
+  client: DaemonClient,
+  harness: Harness,
+  workspaceId: string,
+  marker: string,
+): Promise<MarkedTerminal> {
+  const pidFile = path.join(harness.workDir, `${marker}.pid`);
+  const created = await client.createTerminal(harness.workDir, marker, undefined, {
+    workspaceId,
+    command: process.execPath,
+    args: [
+      "-e",
+      `require("node:fs").writeFileSync(${JSON.stringify(pidFile)}, String(process.pid));
+       console.log(${JSON.stringify(marker)});
+       process.stdin.on("data", (data) => console.log("ECHO:" + data.toString().trim()));`,
+    ],
+  });
+  if (!created.terminal) throw new Error(created.error ?? "terminal creation failed");
+  const programPid = await waitFor(
+    () => (existsSync(pidFile) ? Number(readFileSync(pidFile, "utf8")) : null),
+    "terminal program did not start",
+    10_000,
+  );
+  await waitForScreen(client, created.terminal.id, marker);
+  return { id: created.terminal.id, programPid };
+}
+
+// A shell program that ignores SIGHUP. With `exec`, the shell becomes `sleep`: same pid and
+// birth time, another command line. Without it, `sleep` runs as the shell's child.
+async function createHupResistantTerminal(
+  client: DaemonClient,
+  harness: Harness,
+  workspaceId: string,
+  name: string,
+  mode: "exec" | "child",
+): Promise<{ id: string; shellPid: number; sleepPid: number }> {
+  const shellPidFile = path.join(harness.workDir, `${name}.shell.pid`);
+  const sleepPidFile = path.join(harness.workDir, `${name}.sleep.pid`);
+  const script =
+    mode === "exec"
+      ? `trap '' HUP; echo $$ > '${shellPidFile}'; echo $$ > '${sleepPidFile}'; exec sleep 100000`
+      : `trap '' HUP; echo $$ > '${shellPidFile}'; sleep 100000 & echo $! > '${sleepPidFile}'; wait`;
+  const created = await client.createTerminal(harness.workDir, name, undefined, {
+    workspaceId,
+    command: "/bin/sh",
+    args: ["-c", script],
+  });
+  if (!created.terminal) throw new Error(created.error ?? "terminal creation failed");
+  const read = (file: string) =>
+    existsSync(file) && readFileSync(file, "utf8").trim()
+      ? Number(readFileSync(file, "utf8").trim())
+      : null;
+  const shellPid = await waitFor(() => read(shellPidFile), "shell did not start", 10_000);
+  const sleepPid = await waitFor(() => read(sleepPidFile), "sleep did not start", 10_000);
+  extraPids.add(shellPid);
+  extraPids.add(sleepPid);
+  // `exec` replaces the shell; wait until the process really is `sleep`.
+  await waitFor(
+    async () => {
+      const inspection = await inspector.inspect(sleepPid);
+      return inspection.status === "alive" && inspection.snapshot.commandLine?.startsWith("sleep");
+    },
+    "sleep did not start",
+    10_000,
+  );
+  return { id: created.terminal.id, shellPid, sleepPid };
+}
+
+async function screen(client: DaemonClient, terminalId: string): Promise<string> {
+  return (await client.captureTerminal(terminalId, { stripAnsi: true })).lines.join("\n");
+}
+
+async function waitForScreen(client: DaemonClient, terminalId: string, text: string) {
+  await waitFor(
+    async () => (await screen(client, terminalId)).includes(text),
+    `terminal ${terminalId} never showed ${text}`,
+    15_000,
+  );
+}
+
+async function expectKept(
+  client: DaemonClient,
+  terminal: MarkedTerminal,
+  marker: string,
+  trigger: string,
+) {
+  const listed = await client.listTerminals(undefined, undefined, {});
+  expect(listed.terminals.map((entry) => entry.id)).toContain(terminal.id);
+  expect(isAlive(terminal.programPid)).toBe(true);
+  expect(await screen(client, terminal.id)).toContain(marker);
+  client.sendTerminalInput(terminal.id, { type: "input", data: `after-${trigger}\r` });
+  await waitForScreen(client, terminal.id, `ECHO:after-${trigger}`);
+}
+
+async function waitUntilGone(pid: number, what: string) {
+  await waitFor(() => !isAlive(pid), `${what} (pid ${pid}) is still alive`, 15_000);
+}
+
+async function liveRecords(home: string): Promise<TerminalWorkerRecord[]> {
+  return (await listTerminalWorkerRecords(home)).flatMap((file) =>
+    "record" in file ? [file.record] : [],
+  );
+}
+
+async function currentWorkerRecord(home: string): Promise<TerminalWorkerRecord> {
+  const records = await liveRecords(home);
+  if (records.length !== 1) throw new Error(`expected one worker record, found ${records.length}`);
+  return records[0]!;
+}
+
+async function expectAllClosed(home: string, pids: number[]) {
+  for (const pid of pids) {
+    await waitUntilGone(pid, "a process that should be closed");
+  }
+  expect(await liveRecords(home)).toEqual([]);
+}
+
+function spawnUnrelated(): ChildProcess {
+  const child = spawn(process.execPath, ["-e", "setInterval(() => {}, 1e9)"], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  extraPids.add(child.pid!);
+  return child;
+}
+
+afterEach(async () => {
+  for (const harness of harnesses.splice(0)) {
+    const pid = harness.supervisor.pid;
+    if (pid && isAlive(pid)) {
+      try {
+        process.kill(pid, "SIGCONT");
+      } catch {
+        // gone
+      }
+    }
+    await stopDaemonInstance(harness.home, { force: true, timeoutMs: 15_000 }).catch(
+      () => undefined,
+    );
+    if (pid && isAlive(pid)) process.kill(pid, "SIGKILL");
+    for (const record of await liveRecords(harness.home)) {
+      if (isAlive(record.pid)) {
+        try {
+          process.kill(record.pid, "SIGCONT");
+        } catch {
+          // gone
+        }
+      }
+    }
+    await reapTerminalWorkers({ paseoHome: harness.home, gracefulMs: 0 }).catch(() => undefined);
+    rmSync(harness.home, { recursive: true, force: true });
+  }
+  for (const pid of extraPids) {
+    if (isAlive(pid)) {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
+        // gone
+      }
+    }
+  }
+  extraPids.clear();
+  for (const dir of extraDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("terminals across daemon restarts", { timeout: 240_000 }, () => {
+  test("Settings restart keeps the terminal; Settings restart and close terminals kills it", async () => {
+    const harness = await startSupervisor();
+    let client = await connect(harness);
+    const workspaceId = await createWorkspace(client, harness);
+    const terminal = await createMarkedTerminal(client, harness, workspaceId, "MARKER-SETTINGS");
+    const workerPid = (await currentWorkerRecord(harness.home)).pid;
+
+    // Exactly what the app sends from Settings: no killTerminals.
+    let daemonPid = await daemonWorkerPid(client);
+    await client.restartServer("settings_update");
+    await client.close();
+    client = await waitForReplacement(harness, daemonPid);
+    await expectKept(client, terminal, "MARKER-SETTINGS", "settings-restart");
+    expect((await currentWorkerRecord(harness.home)).pid).toBe(workerPid);
+
+    daemonPid = await daemonWorkerPid(client);
+    await client.restartServer("settings_update", undefined, { killTerminals: true });
+    await client.close();
+    client = await waitForReplacement(harness, daemonPid);
+    await waitUntilGone(terminal.programPid, "terminal program");
+    await waitUntilGone(workerPid, "old terminal worker");
+    expect((await client.listTerminals(undefined, undefined, {})).terminals).toEqual([]);
+    expect((await liveRecords(harness.home)).every((record) => record.pid !== workerPid)).toBe(
+      true,
+    );
+    await client.close();
+  });
+
+  test("a daemon crash keeps the terminal; the restarted daemon lists it", async () => {
+    const harness = await startSupervisor();
+    let client = await connect(harness);
+    const workspaceId = await createWorkspace(client, harness);
+    const terminal = await createMarkedTerminal(client, harness, workspaceId, "MARKER-CRASH");
+    const daemonPid = await daemonWorkerPid(client);
+    process.kill(daemonPid, "SIGKILL");
+    await client.close();
+    client = await waitForReplacement(harness, daemonPid);
+    await expectKept(client, terminal, "MARKER-CRASH", "crash");
+    await client.close();
+  });
+
+  test("daemon.update.request restarts the daemon and keeps the terminal", async () => {
+    // Fake npm only: `ls` reports this checkout as the global install at the daemon's
+    // version, `install -g` does nothing, and anything else fails so real npm never runs.
+    const fakeBin = mkdtempSync(path.join(tmpdir(), "tw-npm-"));
+    extraDirs.push(fakeBin);
+    const listing = JSON.stringify({
+      path: path.join(fakeBin, "global"),
+      dependencies: {
+        "@getpaseo/cli": {
+          version: resolveDaemonVersion(import.meta.url),
+          path: SERVER_ROOT,
+        },
+      },
+    });
+    const fakeNpm = path.join(fakeBin, "fake-npm.cjs");
+    writeFileSync(
+      fakeNpm,
+      `const args = process.argv.slice(2);
+const has = (...tokens) => tokens.every((token) => args.includes(token));
+if (has("-g", "ls", "@getpaseo/cli", "--json", "--depth=0", "--long")) {
+  process.stdout.write(${JSON.stringify(listing)} + "\\n");
+} else if (args[0] === "install" && has("-g", "@getpaseo/cli@latest")) {
+  // The installed version is already the running one: nothing to do.
+} else {
+  process.stderr.write("unexpected npm call: " + args.join(" ") + "\\n");
+  process.exit(1);
+}
+`,
+    );
+    const npmScript = path.join(fakeBin, "npm");
+    writeFileSync(npmScript, `#!/bin/sh\nexec "${process.execPath}" "${fakeNpm}" "$@"\n`);
+    chmodSync(npmScript, 0o755);
+    writeFileSync(path.join(fakeBin, "npm.cmd"), `@"${process.execPath}" "${fakeNpm}" %*\r\n`);
+    const harness = await startSupervisor({ pathPrefix: fakeBin });
+    let client = await connect(harness);
+    const workspaceId = await createWorkspace(client, harness);
+    const terminal = await createMarkedTerminal(client, harness, workspaceId, "MARKER-UPDATE");
+    const daemonPid = await daemonWorkerPid(client);
+
+    const update = await client.updateDaemon();
+    expect(update).toMatchObject({ success: true });
+    await client.close();
+    client = await waitForReplacement(harness, daemonPid);
+    await expectKept(client, terminal, "MARKER-UPDATE", "update");
+    await client.close();
+  });
+
+  test.skipIf(!POSIX)(
+    "POSIX: a kill restart whose shutdown hangs closes terminals before the respawn",
+    async () => {
+      const harness = await startSupervisor();
+      let client = await connect(harness);
+      const workspaceId = await createWorkspace(client, harness);
+      const terminal = await createMarkedTerminal(client, harness, workspaceId, "MARKER-HUNG");
+      const daemonPid = await daemonWorkerPid(client);
+      const supervisorPid = harness.supervisor.pid!;
+      const logPath = path.join(harness.home, "daemon.log");
+
+      // Barrier: the supervisor is paused, so the restart intent waits in its IPC channel.
+      // The daemon's own log line marks the intent dispatched; then the daemon is paused, so
+      // its graceful shutdown can never run and the supervisor's force path must.
+      process.kill(supervisorPid, "SIGSTOP");
+      await client.restartServer("settings_update", undefined, { killTerminals: true });
+      await waitFor(
+        () => readFileSync(logPath, "utf8").includes("Lifecycle intent dispatched"),
+        "the daemon never dispatched the restart intent",
+        15_000,
+      );
+      process.kill(daemonPid, "SIGSTOP");
+      expect(isAlive(terminal.programPid)).toBe(true);
+      process.kill(supervisorPid, "SIGCONT");
+      await client.close();
+
+      client = await waitForReplacement(harness, daemonPid);
+      const log = readFileSync(logPath, "utf8");
+      const forced = log.indexOf("forcing process tree kill");
+      const cleaned = log.indexOf('"msg":"Terminal cleanup finished","when":"before_respawn"');
+      const respawned = log.indexOf('"msg":"Spawning worker"', forced);
+      expect(forced).toBeGreaterThan(-1);
+      expect(cleaned).toBeGreaterThan(forced);
+      expect(respawned).toBeGreaterThan(cleaned);
+      expect(isAlive(terminal.programPid)).toBe(false);
+      expect((await client.listTerminals(undefined, undefined, {})).terminals).toEqual([]);
+      await client.close();
+    },
+  );
+});
+
+describe("terminals when the daemon stops", { timeout: 240_000 }, () => {
+  test.skipIf(!POSIX)(
+    "POSIX: stop closes a terminal whose program ignores HUP, child process included",
+    async () => {
+      const harness = await startSupervisor();
+      const client = await connect(harness);
+      const workspaceId = await createWorkspace(client, harness);
+      const terminal = await createHupResistantTerminal(
+        client,
+        harness,
+        workspaceId,
+        "hup",
+        "child",
+      );
+      const workerPid = (await currentWorkerRecord(harness.home)).pid;
+      await client.close();
+      await stopDaemon(harness);
+      await expectAllClosed(harness.home, [terminal.shellPid, terminal.sleepPid, workerPid]);
+    },
+  );
+
+  for (const force of [false, true]) {
+    test.skipIf(!POSIX)(
+      `POSIX: worker death reaps an exec'd HUP-resistant program and ${force ? "stop --force" : "stop"} closes its replacement`,
+      async () => {
+        const harness = await startSupervisor();
+        const client = await connect(harness);
+        const workspaceId = await createWorkspace(client, harness);
+        const terminal = await createHupResistantTerminal(
+          client,
+          harness,
+          workspaceId,
+          "orphan",
+          "exec",
+        );
+        const workerPid = (await currentWorkerRecord(harness.home)).pid;
+        const daemonPid = await daemonWorkerPid(client);
+        process.kill(workerPid, "SIGKILL");
+        await waitUntilGone(workerPid, "terminal worker");
+        await waitUntilGone(terminal.sleepPid, "orphaned terminal program");
+        await waitFor(
+          async () => (await client.listTerminals(undefined, undefined, {})).terminals.length === 0,
+          "dead terminal was not removed",
+        );
+        expect(await daemonWorkerPid(client)).toBe(daemonPid);
+        const replacement = await createMarkedTerminal(client, harness, workspaceId, "RECOVERED");
+        await expectKept(client, replacement, "RECOVERED", "worker-death");
+        await client.close();
+        await stopDaemonInstance(harness.home, { force });
+        await expectAllClosed(harness.home, [terminal.sleepPid, replacement.programPid]);
+      },
+    );
+  }
+
+  test.skipIf(!POSIX)(
+    "POSIX: stop --force kills a stopped (SIGSTOP) worker and its terminal",
+    async () => {
+      const harness = await startSupervisor();
+      const client = await connect(harness);
+      const workspaceId = await createWorkspace(client, harness);
+      const terminal = await createMarkedTerminal(client, harness, workspaceId, "MARKER-STOPPED");
+      const workerPid = (await currentWorkerRecord(harness.home)).pid;
+      await client.close();
+      process.kill(workerPid, "SIGSTOP");
+      await stopDaemonInstance(harness.home, { force: true });
+      await expectAllClosed(harness.home, [workerPid, terminal.programPid]);
+    },
+  );
+
+  test("the worker socket rejects a wrong secret and leaves its terminals alone", async () => {
+    const harness = await startSupervisor();
+    const client = await connect(harness);
+    const workspaceId = await createWorkspace(client, harness);
+    const terminal = await createMarkedTerminal(client, harness, workspaceId, "MARKER-AUTH");
+    const record = await currentWorkerRecord(harness.home);
+    await expect(
+      connectTerminalWorker({ socketPath: record.socketPath, secret: "not-the-secret" }),
+    ).rejects.toThrow();
+    await expectKept(client, terminal, "MARKER-AUTH", "auth");
+    await client.close();
+  });
+
+  test("stop and stop --force never signal processes a stale or earlier-boot record names", async () => {
+    const harness = await startSupervisor();
+    const client = await connect(harness);
+    await client.close();
+    const reused = spawnUnrelated();
+    const earlierBoot = spawnUnrelated();
+    const base = await currentWorkerRecord(harness.home);
+    // A reused pid with its old record-specific socket gone must never be signaled.
+    writeTerminalWorkerRecord(harness.home, {
+      ...base,
+      recordId: "stale-record",
+      pid: reused.pid!,
+      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" }],
+    });
+    // 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",
+      terminals: [{ id: "t-boot", pid: earlierBoot.pid!, startedAt: null }],
+    });
+
+    await stopDaemon(harness);
+    expect(isAlive(reused.pid!)).toBe(true);
+    expect(isAlive(earlierBoot.pid!)).toBe(true);
+    expect(await liveRecords(harness.home)).toEqual([]);
+
+    // A second round through --force, with the stale record put back.
+    writeTerminalWorkerRecord(harness.home, {
+      ...base,
+      recordId: "stale-record",
+      pid: reused.pid!,
+      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 });
+    expect(isAlive(reused.pid!)).toBe(true);
+    expect(await liveRecords(harness.home)).toEqual([]);
+  });
+});
+
+describe("a worker launched from its own copy", { timeout: 240_000 }, () => {
+  // What a built daemon does: bundle the worker, copy bundle + shell integration + node-pty into
+  // the home, launch from the copy. Here the copy's node-pty (ConPTY on Windows) opens a real
+  // terminal; nothing is loaded from this checkout once the worker runs.
+  test("opens a terminal and runs a command from the copied bundle and node-pty", async () => {
+    const home = mkdtempSync(path.join(tmpdir(), "tw-copy-home-"));
+    const bundleDirectory = mkdtempSync(path.join(tmpdir(), "tw-copy-bundle-"));
+    extraDirs.push(home, bundleDirectory);
+    const buildScript = path.join(SERVER_ROOT, "scripts/build-terminal-worker.mjs");
+    const { buildTerminalWorkerBundle } = (await import(buildScript)) as {
+      buildTerminalWorkerBundle(input: { outDir: string }): Promise<void>;
+    };
+    await buildTerminalWorkerBundle({ outDir: bundleDirectory });
+    const nodePtyDirectory = path.dirname(
+      createRequire(import.meta.url).resolve("node-pty/package.json"),
+    );
+    const entry = prepareTerminalWorkerRuntime({
+      paseoHome: home,
+      paseoVersion: "0.0.0-copy",
+      bundleDirectory,
+      nodePtyDirectory,
+    });
+
+    const launched = await launchTerminalWorker({
+      paseoHome: home,
+      paseoVersion: "0.0.0-copy",
+      entry,
+    });
+    extraPids.add(launched.record.pid);
+    expect(launched.record.runtime).toBe(entry.runtime);
+    const manager = createWorkerTerminalManager({
+      worker: await connectTerminalWorker({
+        socketPath: launched.record.socketPath,
+        secret: launched.record.secret,
+      }),
+      closeTerminals: async () => {
+        await reapTerminalWorkers({ paseoHome: home });
+      },
+    });
+    try {
+      const session = await manager.createTerminal({
+        workspaceId: "ws-copy",
+        cwd: home,
+        command: process.execPath,
+        args: ["-e", "console.log('COPY-' + 'OK'); setInterval(() => {}, 1000);"],
+      });
+      await waitFor(
+        async () =>
+          (await manager.captureTerminal(session.id, { stripAnsi: true })).lines
+            .join("\n")
+            .includes("COPY-OK"),
+        "the terminal in the copied worker never printed its marker",
+        30_000,
+      );
+    } finally {
+      await manager.closeTerminals();
+    }
+    expect(isAlive(launched.record.pid)).toBe(false);
+    expect(existsSync(path.dirname(entry.scriptPath))).toBe(false);
+  });
+});
diff --git a/packages/server/src/server/daemon-e2e/terminal.e2e.test.ts b/packages/server/src/server/daemon-e2e/terminal.e2e.test.ts
index 633bd3bc1c..36425ffeec 100644
--- a/packages/server/src/server/daemon-e2e/terminal.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/terminal.e2e.test.ts
@@ -1,3 +1,4 @@
+import { Terminal as HeadlessTerminal } from "@xterm/headless";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
 import { mkdtempSync, rmSync } from "fs";
 import { tmpdir } from "os";
@@ -10,7 +11,6 @@ import {
   type WSOutboundMessage,
 } from "@getpaseo/protocol/messages";
 import {
-  decodeTerminalSnapshotPayload,
   decodeTerminalStreamFrame,
   encodeTerminalStreamFrame,
   TerminalStreamOpcode,
@@ -80,6 +80,24 @@ async function waitForCondition(
   throw new Error(`Timed out after ${timeoutMs}ms waiting for condition`);
 }
 
+function readHeadlessState(terminal: HeadlessTerminal): TerminalState {
+  const buffer = terminal.buffer.active;
+  const lines: TerminalState["grid"] = [];
+  for (let row = 0; row < buffer.length; row++) {
+    const cells: TerminalState["grid"][number] = [];
+    for (let col = 0; col < terminal.cols; col++)
+      cells.push({ char: buffer.getLine(row)?.getCell(col)?.getChars() ?? "" });
+    lines.push(cells);
+  }
+  return {
+    rows: terminal.rows,
+    cols: terminal.cols,
+    grid: lines.slice(buffer.baseY),
+    scrollback: lines.slice(0, buffer.baseY),
+    cursor: { row: buffer.cursorY, col: buffer.cursorX },
+  };
+}
+
 async function waitForTerminalSnapshot(
   client: DaemonClient,
   terminalId: string,
@@ -92,16 +110,34 @@ async function waitForTerminalSnapshot(
       reject(new Error(`Timeout waiting for terminal snapshot (${timeout}ms)`));
     }, timeout);
 
+    let terminal: HeadlessTerminal | null = null;
+    let writes = Promise.resolve();
     const unsubscribe = client.onTerminalStreamEvent((event) => {
-      if (event.terminalId !== terminalId || event.type !== "snapshot") {
-        return;
+      if (event.terminalId !== terminalId || event.type !== "replay") return;
+      const replay = event.replay;
+      if (replay.type === "begin") {
+        terminal?.dispose();
+        terminal = new HeadlessTerminal({
+          rows: replay.rows ?? 24,
+          cols: replay.cols ?? 80,
+          scrollback: 1000,
+          allowProposedApi: true,
+        });
+      } else if (replay.type === "data") {
+        const active = terminal!;
+        writes = writes.then(() => new Promise<void>((done) => active.write(replay.data, done)));
+      } else {
+        void writes.then(() => {
+          const active = terminal!;
+          const state = readHeadlessState(active);
+          if (!predicate(state)) return null;
+          clearTimeout(timeoutHandle);
+          unsubscribe();
+          active.dispose();
+          resolve(state);
+          return null;
+        });
       }
-      if (!predicate(event.state)) {
-        return;
-      }
-      clearTimeout(timeoutHandle);
-      unsubscribe();
-      resolve(event.state);
     });
   });
 }
@@ -160,7 +196,7 @@ function toWsBuffer(raw: WebSocket.RawData): Buffer | null {
   return null;
 }
 
-async function connectRawWebSocket(port: number): Promise<WebSocket> {
+async function connectRawWebSocket(port: number, chunkedReplay = false): Promise<WebSocket> {
   const ws = new WebSocket(`ws://127.0.0.1:${port}/ws`);
   await new Promise<void>((resolve, reject) => {
     ws.once("open", () => resolve());
@@ -180,6 +216,7 @@ async function connectRawWebSocket(port: number): Promise<WebSocket> {
       clientId: `terminal-raw-${Date.now()}-${Math.random().toString(36).slice(2)}`,
       clientType: "cli",
       protocolVersion: 1,
+      capabilities: { terminal_chunked_replay: chunkedReplay },
     }),
   );
 
@@ -386,17 +423,24 @@ async function collectRawBinaryFrames(
   });
 }
 
+async function decodeRestoreState(
+  frame: TerminalStreamFrame,
+  terminalId: string,
+): Promise<TerminalState> {
+  const size = ctx.daemon.daemon.terminalManager!.getTerminal(terminalId)!.getSize();
+  const terminal = new HeadlessTerminal({ ...size, scrollback: 1000, allowProposedApi: true });
+  try {
+    await new Promise<void>((resolve) => terminal.write(frame.payload, resolve));
+    return readHeadlessState(terminal);
+  } finally {
+    terminal.dispose();
+  }
+}
+
 function getFrameText(frame: TerminalStreamFrame): string {
   if (frame.opcode === TerminalStreamOpcode.Output) {
     return new TextDecoder().decode(frame.payload);
   }
-  if (frame.opcode === TerminalStreamOpcode.Snapshot) {
-    const state = decodeTerminalSnapshotPayload(frame.payload);
-    if (!state) {
-      return "";
-    }
-    return extractStateText(state);
-  }
   if (frame.opcode === TerminalStreamOpcode.Restore) {
     return new TextDecoder().decode(frame.payload);
   }
@@ -446,7 +490,10 @@ function startTerminalOutputCapture(ws: WebSocket, slot: number): TerminalOutput
     if (!frame || frame.slot !== slot) {
       return;
     }
-    if (frame.opcode === TerminalStreamOpcode.Snapshot) {
+    if (
+      frame.opcode === TerminalStreamOpcode.Restore ||
+      frame.opcode === TerminalStreamOpcode.ReplayEnd
+    ) {
       snapshotCount += 1;
       return;
     }
@@ -634,7 +681,7 @@ async function measureRepeatCadenceForTerminal(input: {
     const slot = await subscribeRawTerminal(ws, terminalId, `sub-repeat-cadence-${input.name}`);
     await waitForRawBinaryFrame(
       ws,
-      (frame) => frame.slot === slot && frame.opcode === TerminalStreamOpcode.Snapshot,
+      (frame) => frame.slot === slot && frame.opcode === TerminalStreamOpcode.Restore,
       10000,
     );
     await new Promise((resolve) => setTimeout(resolve, 1000));
@@ -817,13 +864,7 @@ test("live terminal restore skips the initial snapshot", async () => {
 
     expect(outputText).toContain("after-live");
     expect(outputText).not.toContain("before-live");
-    expect(
-      outputFrames.some(
-        (frame) =>
-          frame.opcode === TerminalStreamOpcode.Snapshot ||
-          frame.opcode === TerminalStreamOpcode.Restore,
-      ),
-    ).toBe(false);
+    expect(outputFrames.some((frame) => frame.opcode === TerminalStreamOpcode.Restore)).toBe(false);
   } finally {
     await closeWebSocket(ws);
   }
@@ -901,15 +942,12 @@ test("propagates debounced terminal titles through list responses and snapshots"
   }
   expect(listedTitle).toBe("Build Output");
 
-  const snapshotPromise = waitForTerminalSnapshot(
-    ctx.client,
-    terminalId,
-    (state) => state.title === "Build Output",
+  const attached = await ctx.client.subscribeTerminal(terminalId);
+  expect(attached.error).toBeNull();
+  const afterAttach = await ctx.client.listTerminals(cwd);
+  expect(afterAttach.terminals.find((terminal) => terminal.id === terminalId)?.title).toBe(
+    "Build Output",
   );
-  await ctx.client.subscribeTerminal(terminalId);
-  const snapshot = await snapshotPromise;
-
-  expect(snapshot.title).toBe("Build Output");
 
   rmSync(cwd, { recursive: true, force: true });
 }, 30000);
@@ -973,13 +1011,10 @@ test("subscribe response is sent before the initial snapshot frame", async () =>
           return;
         }
         const frame = decodeTerminalStreamFrame(new Uint8Array(buffer));
-        if (frame?.opcode !== TerminalStreamOpcode.Snapshot) {
-          return;
-        }
-        const state = decodeTerminalSnapshotPayload(frame.payload);
-        if (!state || !extractStateText(state).includes("hello-ordering")) {
+        if (frame?.opcode !== TerminalStreamOpcode.Restore) {
           return;
         }
+        if (!getFrameText(frame).includes("hello-ordering")) return;
         events.push("snapshot");
         maybeResolve();
       };
@@ -1113,7 +1148,7 @@ test("reconnected terminal streams replay active input modes after the snapshot"
     const firstSlot = await subscribeRawTerminal(firstWs, terminalId, "sub-input-mode-first");
     await waitForRawBinaryFrame(
       firstWs,
-      (frame) => frame.slot === firstSlot && frame.opcode === TerminalStreamOpcode.Snapshot,
+      (frame) => frame.slot === firstSlot && frame.opcode === TerminalStreamOpcode.Restore,
     );
     sendRawTerminalInput(firstWs, firstSlot, "e");
     await waitForRawBinaryFrame(
@@ -1140,7 +1175,7 @@ test("reconnected terminal streams replay active input modes after the snapshot"
     const secondSlot = await subscribeRawTerminal(secondWs, terminalId, "sub-input-mode-second");
     await waitForRawBinaryFrame(
       secondWs,
-      (frame) => frame.slot === secondSlot && frame.opcode === TerminalStreamOpcode.Snapshot,
+      (frame) => frame.slot === secondSlot && frame.opcode === TerminalStreamOpcode.Restore,
     );
     const replay = await waitForRawBinaryFrame(
       secondWs,
@@ -1172,7 +1207,7 @@ test("reconnected terminal streams do not replay input modes before they are ena
     const slot = await subscribeRawTerminal(ws, terminalId, "sub-input-mode-inactive");
     await waitForRawBinaryFrame(
       ws,
-      (frame) => frame.slot === slot && frame.opcode === TerminalStreamOpcode.Snapshot,
+      (frame) => frame.slot === slot && frame.opcode === TerminalStreamOpcode.Restore,
     );
     await waitForNoRawBinaryFrame(ws, 300);
   } finally {
@@ -1188,7 +1223,7 @@ test("fast output to a slow websocket client falls back to a snapshot", async ()
   const ws = await connectRawWebSocket(ctx.daemon.port);
 
   await subscribeRawTerminal(ws, terminalId, "sub-raw");
-  await waitForRawBinaryFrame(ws, (frame) => frame.opcode === TerminalStreamOpcode.Snapshot, 10000);
+  await waitForRawBinaryFrame(ws, (frame) => frame.opcode === TerminalStreamOpcode.Restore, 10000);
 
   const rawSocket = (ws as WebSocket & { _socket?: { pause: () => void; resume: () => void } })
     ._socket;
@@ -1203,12 +1238,12 @@ test("fast output to a slow websocket client falls back to a snapshot", async ()
   await new Promise((resolve) => setTimeout(resolve, 750));
   const catchUpFramePromise = waitForRawBinaryFrame(
     ws,
-    (frame) => frame.opcode === TerminalStreamOpcode.Snapshot,
+    (frame) => frame.opcode === TerminalStreamOpcode.Restore,
     15000,
   );
   rawSocket!.resume();
   const catchUpFrame = await catchUpFramePromise;
-  expect(catchUpFrame.opcode).toBe(TerminalStreamOpcode.Snapshot);
+  expect(catchUpFrame.opcode).toBe(TerminalStreamOpcode.Restore);
 
   await closeWebSocket(ws);
   rmSync(cwd, { recursive: true, force: true });
@@ -1260,7 +1295,7 @@ test("resize updates server dimensions without sending a live snapshot", async (
 
   await new Promise((resolve) => setTimeout(resolve, 300));
 
-  const state = ctx.daemon.daemon.terminalManager?.getTerminal(terminalId)?.getState();
+  const state = ctx.daemon.daemon.terminalManager?.getTerminal(terminalId)?.getSize();
   expect(state?.rows).toBe(10);
   expect(state?.cols).toBe(40);
 
@@ -1277,7 +1312,7 @@ test("the latest resize from any attached client owns the PTY size", async () =>
   );
 
   const readSize = () => {
-    const state = ctx.daemon.daemon.terminalManager?.getTerminal(terminalId)?.getState();
+    const state = ctx.daemon.daemon.terminalManager?.getTerminal(terminalId)?.getSize();
     return state ? { rows: state.rows, cols: state.cols } : null;
   };
   const expectSize = async (size: { rows: number; cols: number }) => {
@@ -1403,10 +1438,10 @@ test("websocket terminate then new connection gets snapshot with all prior outpu
     await subscribeRawTerminal(firstSocket, terminalId, "sub-drop-a");
     const initialSnapshot = await waitForRawBinaryFrame(
       firstSocket,
-      (frame) => frame.opcode === TerminalStreamOpcode.Snapshot,
+      (frame) => frame.opcode === TerminalStreamOpcode.Restore,
       10000,
     );
-    expect(initialSnapshot.opcode).toBe(TerminalStreamOpcode.Snapshot);
+    expect(initialSnapshot.opcode).toBe(TerminalStreamOpcode.Restore);
 
     ctx.client.sendTerminalInput(terminalId, {
       type: "input",
@@ -1442,9 +1477,9 @@ test("websocket terminate then new connection gets snapshot with all prior outpu
     try {
       await subscribeRawTerminal(secondSocket, terminalId, "sub-drop-b");
       const reconnectFrame = await waitForRawBinaryFrame(secondSocket, () => true, 10000);
-      expect(reconnectFrame.opcode).toBe(TerminalStreamOpcode.Snapshot);
+      expect(reconnectFrame.opcode).toBe(TerminalStreamOpcode.Restore);
 
-      const state = decodeTerminalSnapshotPayload(reconnectFrame.payload);
+      const state = await decodeRestoreState(reconnectFrame, terminalId);
       expect(state).not.toBeNull();
       expect(extractStateText(state!)).toContain("before-drop");
       expect(extractStateText(state!)).toContain("while-dead");
@@ -1513,11 +1548,11 @@ test("snapshot fidelity through websocket decode preserves dimensions and visibl
     await subscribeRawTerminal(ws, terminalId, "sub-fidelity");
     const snapshotFrame = await waitForRawBinaryFrame(
       ws,
-      (frame) => frame.opcode === TerminalStreamOpcode.Snapshot,
+      (frame) => frame.opcode === TerminalStreamOpcode.Restore,
       10000,
     );
 
-    const state = decodeTerminalSnapshotPayload(snapshotFrame.payload);
+    const state = await decodeRestoreState(snapshotFrame, terminalId);
     expect(state).not.toBeNull();
     expect(state).toMatchObject({
       rows: 24,
@@ -1545,7 +1580,7 @@ test("terminal exit prevents resubscribe and sends no frames after exit", async
     await subscribeRawTerminal(ws, terminalId, "sub-exit");
     await waitForRawBinaryFrame(
       ws,
-      (frame) => frame.opcode === TerminalStreamOpcode.Snapshot,
+      (frame) => frame.opcode === TerminalStreamOpcode.Restore,
       10000,
     );
 
@@ -1561,8 +1596,7 @@ test("terminal exit prevents resubscribe and sends no frames after exit", async
     const exitMessage = await exitMessagePromise;
     expect(exitMessage.message.type).toBe("terminal_stream_exit");
 
-    const subscribeResult = await ctx.client.subscribeTerminal(terminalId);
-    expect(subscribeResult.error).toBe("Terminal not found");
+    await expect(ctx.client.subscribeTerminal(terminalId)).rejects.toThrow("Terminal not found");
     await waitForNoRawBinaryFrame(ws, 750);
   } finally {
     await closeWebSocket(ws);
@@ -1580,7 +1614,7 @@ test("empty input frame does not crash the server", async () => {
     const slot = await subscribeRawTerminal(ws, terminalId, "sub-empty-input");
     await waitForRawBinaryFrame(
       ws,
-      (frame) => frame.opcode === TerminalStreamOpcode.Snapshot,
+      (frame) => frame.opcode === TerminalStreamOpcode.Restore,
       10000,
     );
 
@@ -1619,7 +1653,7 @@ test("1MB output burst keeps frames decodable and terminal usable afterward", as
     await subscribeRawTerminal(ws, terminalId, "sub-large-output");
     await waitForRawBinaryFrame(
       ws,
-      (frame) => frame.opcode === TerminalStreamOpcode.Snapshot,
+      (frame) => frame.opcode === TerminalStreamOpcode.Restore,
       10000,
     );
 
@@ -1636,7 +1670,7 @@ test("1MB output burst keeps frames decodable and terminal usable afterward", as
           .reduce((sum, frame) => sum + frame.payload.byteLength, 0);
         return (
           outputBytes >= 1024 * 1024 ||
-          collectedFrames.some((frame) => frame.opcode === TerminalStreamOpcode.Snapshot)
+          collectedFrames.some((frame) => frame.opcode === TerminalStreamOpcode.Restore)
         );
       },
       20000,
@@ -1646,7 +1680,7 @@ test("1MB output burst keeps frames decodable and terminal usable afterward", as
     for (const frame of frames) {
       expect(
         frame.opcode === TerminalStreamOpcode.Output ||
-          frame.opcode === TerminalStreamOpcode.Snapshot,
+          frame.opcode === TerminalStreamOpcode.Restore,
       ).toBe(true);
     }
 
@@ -1836,3 +1870,194 @@ describe("list terminals across directories", () => {
     ]);
   });
 });
+
+test.each([3000, 12050])(
+  "chunked SDK replay retains requested history for %s printed lines",
+  async (count) => {
+    const cwd = tmpCwd();
+    tempDirs.push(cwd);
+    const created = await createTerminalInWorkspace(ctx.client, {
+      cwd,
+      options: {
+        command: "/bin/sh",
+        args: [
+          "-lc",
+          `i=1; while [ $i -le ${count} ]; do printf '\\033[31mreplay-%04d界🙂 payload-abcdefghijklmnopqrstuvwxyz0123456789\\033[0m\\n' $i; i=$((i+1)); done; sleep 30`,
+        ],
+      },
+    });
+    const id = created.terminal!.id;
+    await waitForCondition(
+      async () =>
+        (await ctx.client.captureTerminal(id)).lines
+          .join("\n")
+          .includes(`replay-${String(count).padStart(4, "0")}`),
+      10000,
+    );
+    const events: import("@getpaseo/client").TerminalStreamEvent[] = [];
+    let end!: () => void;
+    const completed = new Promise<void>((resolve) => {
+      end = resolve;
+    });
+    const subscription = ctx.client.observeTerminal(
+      id,
+      (event) => {
+        events.push(event);
+        if (event.type === "replay" && event.replay.type === "end") end();
+      },
+      { restore: { mode: "visible-snapshot", scrollbackLines: 10000 } },
+    );
+    try {
+      await subscription.ready;
+      await completed;
+      const replay = events.flatMap((event) => (event.type === "replay" ? [event.replay] : []));
+      expect(replay[0]).toMatchObject({
+        type: "begin",
+        retainedHistoryLines: count === 12050 ? 10000 : expect.any(Number),
+      });
+      expect(replay.at(-1)).toEqual({ type: "end" });
+      const chunks = replay.flatMap((event) => (event.type === "data" ? [event.data] : []));
+      expect(chunks.every((chunk) => chunk.length <= 65536)).toBe(true);
+      const text = Buffer.concat(chunks).toString("utf8");
+      const begin = replay[0];
+      if (begin?.type !== "begin" || begin.rows === undefined)
+        throw new Error("Missing replay dimensions");
+      expect(text.match(/replay-\d{4,5}/g)).toHaveLength(Math.min(count, 10000 + begin.rows - 1));
+      expect(text).toContain(`replay-${String(count).padStart(4, "0")}界🙂`);
+      if (count === 3000) expect(text).toContain("replay-0001界🙂");
+      else {
+        expect(text).not.toContain("replay-0001");
+        expect(chunks.length).toBeGreaterThan(1);
+      }
+    } finally {
+      await subscription.release();
+    }
+  },
+  30000,
+);
+
+test.each([false, true])(
+  "default SDK observation replays a terminal without waiting for output (quietScreen=%s)",
+  async (quietScreen) => {
+    const cwd = tmpCwd();
+    tempDirs.push(cwd);
+    const created = await createTerminalInWorkspace(ctx.client, {
+      cwd,
+      options: {
+        command: process.execPath,
+        args: [
+          "-e",
+          `${quietScreen ? 'process.stdout.write("QUIET-SCREEN\\r\\n");' : ""} process.stdin.on("data", data => process.stdout.write("LIVE:" + data)); setInterval(() => {}, 1000);`,
+        ],
+      },
+    });
+    const id = created.terminal!.id;
+    if (quietScreen)
+      await waitForCondition(
+        async () => (await ctx.client.captureTerminal(id)).lines.join("").includes("QUIET-SCREEN"),
+        10000,
+      );
+    const events: import("@getpaseo/client").TerminalStreamEvent[] = [];
+    const observation = ctx.client.observeTerminal(id, (event) => events.push(event));
+    try {
+      await observation.ready;
+      await waitForCondition(
+        () => events.some((event) => event.type === "replay" && event.replay.type === "end"),
+        10000,
+      );
+      const replay = events.flatMap((event) => (event.type === "replay" ? [event.replay] : []));
+      const begin = replay[0];
+      if (begin?.type !== "begin" || !begin.rows || !begin.cols)
+        throw new Error("Missing replay begin geometry");
+      expect(replay.at(-1)).toEqual({ type: "end" });
+      const terminal = new HeadlessTerminal({
+        rows: begin.rows,
+        cols: begin.cols,
+        allowProposedApi: true,
+      });
+      try {
+        for (const event of replay)
+          if (event.type === "data")
+            await new Promise<void>((resolve) => terminal.write(event.data, resolve));
+        const text = extractStateText(readHeadlessState(terminal));
+        expect(text).toBe(quietScreen ? "QUIET-SCREEN" : "");
+      } finally {
+        terminal.dispose();
+      }
+      ctx.client.sendTerminalInput(id, { type: "input", data: "next\r" });
+      await waitForCondition(
+        () =>
+          events.some(
+            (event) =>
+              event.type === "output" && new TextDecoder().decode(event.data).includes("LIVE:next"),
+          ),
+        10000,
+      );
+    } finally {
+      await observation.release();
+    }
+  },
+  30000,
+);
+
+test.each([false, true])(
+  "a paused terminal consumer catches up through ANSI replay instead of retaining every output frame (chunked=%s)",
+  async (chunked) => {
+    const { existsSync } = await import("node:fs");
+    const cwd = tmpCwd();
+    tempDirs.push(cwd);
+    const marker = path.join(cwd, "output-complete");
+    const created = await createTerminalInWorkspace(ctx.client, {
+      cwd,
+      options: {
+        command: process.execPath,
+        args: [
+          "-e",
+          `
+      const fs = require('node:fs');
+      process.stdin.setRawMode?.(true);
+      process.stdin.resume();
+      process.stdin.once('data', () => {
+        const chunk = Buffer.alloc(256 * 1024, 120);
+        let remaining = 128;
+        const write = () => {
+          if (remaining-- === 0) { fs.writeFileSync(${JSON.stringify(marker)}, 'done'); return; }
+          process.stdout.write(chunk, write);
+        };
+        write();
+      });
+    `,
+        ],
+      },
+    });
+    const ws = await connectRawWebSocket(ctx.daemon.port, chunked);
+    try {
+      const slot = await subscribeRawTerminal(ws, created.terminal!.id, "slow-terminal");
+      await waitForRawBinaryFrame(
+        ws,
+        (frame) =>
+          frame.slot === slot &&
+          frame.opcode ===
+            (chunked ? TerminalStreamOpcode.ReplayEnd : TerminalStreamOpcode.Restore),
+      );
+      const capture = startTerminalOutputCapture(ws, slot);
+      try {
+        ws.pause();
+        sendRawTerminalInput(ws, slot, "go\n");
+        await waitForCondition(() => existsSync(marker), 20000);
+        ws.resume();
+        await waitForCondition(() => capture.snapshotCount > 0, 10000);
+        expect(ws.readyState).toBe(WebSocket.OPEN);
+        expect(capture.frames.reduce((total, frame) => total + frame.payloadBytes, 0)).toBeLessThan(
+          32 * 1024 * 1024,
+        );
+      } finally {
+        ws.resume();
+        capture.stop();
+      }
+    } finally {
+      await closeWebSocket(ws);
+    }
+  },
+  40000,
+);
diff --git a/packages/server/src/server/daemon-instance.ts b/packages/server/src/server/daemon-instance.ts
index 02f4446795..b3b07e7ff0 100644
--- a/packages/server/src/server/daemon-instance.ts
+++ b/packages/server/src/server/daemon-instance.ts
@@ -11,6 +11,7 @@ import {
 } from "./pid-lock.js";
 import { daemonLaunchEnvironment } from "./config-environment.js";
 import { readPersistedConfig } from "./persisted-config.js";
+import { reapTerminalWorkers } from "../terminal/terminal-worker-reaper.js";
 import treeKill from "tree-kill";
 const killTree = (pid: number, signal: string): Promise<void> =>
   new Promise((resolve, reject) =>
@@ -29,6 +30,10 @@ export { resolvePaseoHome } from "./paseo-home.js";
 export { ensurePrivateDirectory } from "./private-files.js";
 export { daemonLaunchEnvironment } from "./config-environment.js";
 export { readLocalCredentialForTarget } from "./local-credential.js";
+export {
+  TerminalCleanupNotConfirmedError,
+  retryUnconfirmedTerminalCleanup,
+} from "../terminal/terminal-worker-reaper.js";
 export {
   isSamePidLock as isSameDaemonInstance,
   type PidLockInfo as DaemonInstance,
@@ -97,11 +102,23 @@ async function requestInstanceStop(
   instance: PidLockInfo,
   options: {
     force?: boolean;
+    keepTerminals?: boolean;
     requestShutdown?: (instance: PidLockInfo & { listen: string }) => Promise<void>;
   },
 ) {
   let forced = false;
   let usedLifecycleRpc = false;
+  if (options.keepTerminals) {
+    // SIGTERM means "stop and close terminals"; keeping them always goes over the RPC.
+    if (!instance.listen || !options.requestShutdown) {
+      throw new DaemonInstanceError(
+        "STOP_NO_GRACEFUL_CHANNEL",
+        `PID ${instance.pid} for ${home} has no listen address, so it cannot be asked to keep its terminals.`,
+      );
+    }
+    await options.requestShutdown({ ...instance, listen: instance.listen });
+    return { forced, usedLifecycleRpc: true };
+  }
   if (process.platform === "win32") {
     if (instance.listen && options.requestShutdown) {
       try {
@@ -142,6 +159,8 @@ export async function stopDaemonInstance(
   options: {
     instance?: PidLockInfo;
     force?: boolean;
+    // Leave the terminal worker running so the next daemon adopts it. Not valid with force.
+    keepTerminals?: boolean;
     timeoutMs?: number;
     killTimeoutMs?: number;
     requestShutdown?: (instance: PidLockInfo & { listen: string }) => Promise<void>;
@@ -153,6 +172,7 @@ export async function stopDaemonInstance(
   usedLifecycleRpc: boolean;
 }> {
   const { timeoutMs = 15_000, killTimeoutMs = 3_000 } = options;
+  assertStopOptions(options);
   const deadline = Date.now() + timeoutMs;
   const instance = await getPidLockInfo(home);
   if (options.instance && instance && !isSamePidLock(instance, options.instance)) {
@@ -164,6 +184,9 @@ export async function stopDaemonInstance(
   if (!instance || !isPidLockOwnerRunning(instance)) {
     if (instance)
       await releasePidLock(home, { ownerPid: instance.pid, startedAt: instance.startedAt });
+    // Terminals a `stop --keep-terminals` left behind belong to no daemon now; a plain stop
+    // closes them.
+    await closeLeftoverTerminals(home, { keepTerminals: options.keepTerminals, forced: false });
     return {
       action: "not_running",
       pid: instance?.pid ?? null,
@@ -200,9 +223,29 @@ export async function stopDaemonInstance(
       `Timed out waiting for supervisor PID ${instance.pid} in ${home} to exit${options.force ? "" : "; use --force to permit forced cleanup"}.`,
     );
   await releasePidLock(home, { ownerPid: instance.pid, startedAt: instance.startedAt });
+  // The supervisor already closed the terminals unless it was killed; this confirms it, and
+  // after --force (no graceful shutdown happened) does it at once.
+  await closeLeftoverTerminals(home, { keepTerminals: options.keepTerminals, forced });
   return { action: "stopped", pid: instance.pid, forced, usedLifecycleRpc };
 }
 
+function assertStopOptions(options: { force?: boolean; keepTerminals?: boolean }): void {
+  if (options.force && options.keepTerminals) {
+    throw new DaemonInstanceError(
+      "INVALID_STOP_OPTIONS",
+      "--force kills terminals; it cannot be combined with --keep-terminals.",
+    );
+  }
+}
+
+async function closeLeftoverTerminals(
+  home: string,
+  options: { keepTerminals?: boolean; forced: boolean },
+): Promise<void> {
+  if (options.keepTerminals) return;
+  await reapTerminalWorkers({ paseoHome: home, gracefulMs: options.forced ? 0 : undefined });
+}
+
 export async function startDaemonInstance(input: {
   home: string;
   command: string;
diff --git a/packages/server/src/server/daemon-worker.ts b/packages/server/src/server/daemon-worker.ts
index bc5acbc404..8af60cd7bc 100644
--- a/packages/server/src/server/daemon-worker.ts
+++ b/packages/server/src/server/daemon-worker.ts
@@ -1,5 +1,6 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
+import { initializeEnvironmentProxy } from "./network/index.js";
 import { createPaseoDaemon, formatListenTarget } from "./bootstrap.js";
 import { loadConfig } from "./config.js";
 import { resolvePaseoHome } from "./paseo-home.js";
@@ -13,6 +14,7 @@ type SupervisorLifecycleMessage =
   | {
       type: "paseo:shutdown";
       reason: string;
+      keepTerminals: boolean;
     }
   | {
       type: "paseo:ready";
@@ -22,6 +24,7 @@ type SupervisorLifecycleMessage =
   | {
       type: "paseo:restart";
       reason?: string;
+      keepTerminals: boolean;
     };
 
 interface BootstrapResult {
@@ -130,6 +133,11 @@ function applyCliFlagOverrides(config: ReturnType<typeof loadConfig>): void {
 
 async function main() {
   const { paseoHome, logger, config } = bootstrapFromEnvironment();
+  for (const variable of initializeEnvironmentProxy()) {
+    writeWorkerLifecycleLog(paseoHome, "Ignoring invalid or unsupported HTTP proxy variable", {
+      variable,
+    });
+  }
   let daemon: Awaited<ReturnType<typeof createPaseoDaemon>> | null = null;
   let shutdownPromise: Promise<number> | null = null;
   let exitHookInstalled = false;
@@ -151,12 +159,15 @@ async function main() {
     options?: {
       reason?: string;
       successExitCode?: number;
+      keepTerminals?: boolean;
     },
   ) => {
     const reason = options?.reason ?? `worker_received_${signal}`;
+    // Signals mean "stop and close terminals"; only an explicit keep request keeps them.
+    const keepTerminals = options?.keepTerminals === true;
     if (!shutdownPromise) {
       logger.info(
-        { signal, reason, ...getProcessDiagnostics() },
+        { signal, reason, keepTerminals, ...getProcessDiagnostics() },
         `${signal} received, shutting down gracefully...`,
       );
 
@@ -175,7 +186,7 @@ async function main() {
             clearTimeout(forceExit);
             return 1;
           }
-          await daemon.stop();
+          await daemon.stop({ keepTerminals });
           clearTimeout(forceExit);
           logger.info("Server closed");
           return options?.successExitCode ?? 0;
@@ -209,36 +220,53 @@ async function main() {
   };
 
   const handleLifecycleIntent = (intent: DaemonLifecycleIntent) => {
+    const fields = {
+      clientId: intent.clientId,
+      requestId: intent.requestId,
+      reason: intent.reason,
+      keepTerminals: intent.keepTerminals,
+    };
     if (intent.type === "shutdown") {
-      logger.warn(
-        { clientId: intent.clientId, requestId: intent.requestId, reason: intent.reason },
-        "Shutdown requested via websocket",
-      );
-      if (sendSupervisorLifecycleMessage({ type: "paseo:shutdown", reason: intent.reason })) {
+      logger.warn(fields, "Shutdown requested via websocket");
+      const sent = sendSupervisorLifecycleMessage({
+        type: "paseo:shutdown",
+        reason: intent.reason,
+        keepTerminals: intent.keepTerminals,
+      });
+      recordLifecycleIntentDispatched(intent.type, fields);
+      if (sent) {
         return;
       }
-      beginShutdown("shutdown lifecycle intent", { reason: intent.reason });
+      beginShutdown("shutdown lifecycle intent", {
+        reason: intent.reason,
+        keepTerminals: intent.keepTerminals,
+      });
       return;
     }
 
-    logger.warn(
-      { clientId: intent.clientId, requestId: intent.requestId, reason: intent.reason },
-      "Restart requested via websocket",
-    );
-    if (
-      sendSupervisorLifecycleMessage({
-        type: "paseo:restart",
-        ...(intent.reason ? { reason: intent.reason } : {}),
-      })
-    ) {
+    logger.warn(fields, "Restart requested via websocket");
+    const sent = sendSupervisorLifecycleMessage({
+      type: "paseo:restart",
+      ...(intent.reason ? { reason: intent.reason } : {}),
+      keepTerminals: intent.keepTerminals,
+    });
+    recordLifecycleIntentDispatched(intent.type, fields);
+    if (sent) {
       return;
     }
     beginShutdown("restart lifecycle intent", {
       reason: intent.reason,
       successExitCode: 0,
+      keepTerminals: intent.keepTerminals,
     });
   };
 
+  // Written straight to daemon.log: the pino stream goes through the supervisor's pipe, which
+  // a paused or busy supervisor does not drain. Tests synchronize on this line.
+  const recordLifecycleIntentDispatched = (type: string, fields: Record<string, unknown>) => {
+    writeWorkerLifecycleLog(paseoHome, "Lifecycle intent dispatched", { type, ...fields });
+  };
+
   const installSupervisorLivenessGuard = () => {
     if (typeof process.send !== "function") {
       return;
@@ -278,9 +306,10 @@ async function main() {
         return;
       }
       if (type === "paseo:graceful-shutdown") {
-        const reason = (message as { reason?: unknown }).reason;
+        const { reason, keepTerminals } = message as { reason?: unknown; keepTerminals?: unknown };
         beginShutdown("Supervisor shutdown request", {
           reason: typeof reason === "string" ? reason : "supervisor_requested_shutdown",
+          keepTerminals: keepTerminals === true,
         });
       }
     });
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/git-metadata-event-rules.test.ts b/packages/server/src/server/git-metadata-event-rules.test.ts
index 8c7e491970..4456573624 100644
--- a/packages/server/src/server/git-metadata-event-rules.test.ts
+++ b/packages/server/src/server/git-metadata-event-rules.test.ts
@@ -21,6 +21,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 }],
diff --git a/packages/server/src/server/git-metadata-event-rules.ts b/packages/server/src/server/git-metadata-event-rules.ts
index dab6bc4887..ff82747ba0 100644
--- a/packages/server/src/server/git-metadata-event-rules.ts
+++ b/packages/server/src/server/git-metadata-event-rules.ts
@@ -44,7 +44,7 @@ export const GIT_METADATA_EVENT_RULES = [
   },
   {
     id: "paseo-worktree-metadata",
-    scope: "worktree",
+    scope: "both",
     match: "exact",
     path: "paseo/worktree.json",
     route: "owner",
diff --git a/packages/server/src/server/git-observation-paths.ts b/packages/server/src/server/git-observation-paths.ts
new file mode 100644
index 0000000000..1ef0a4e571
--- /dev/null
+++ b/packages/server/src/server/git-observation-paths.ts
@@ -0,0 +1,106 @@
+import { realpath } from "node:fs";
+import { readlink } from "node:fs/promises";
+import { promisify } from "node:util";
+import pLimit from "p-limit";
+import { dirname, resolve as resolvePath, sep } from "node:path";
+import { looksLikeDefiniteWindowsPath, normalizePathPreservingCase } from "../utils/path.js";
+
+const nativeRealpath = promisify(realpath.native);
+const jsRealpath = promisify(realpath);
+const identityIo = pLimit(2);
+
+/** A subscription owns its lexical namespace, including the OS's real-root alias. */
+export class GitObservationPaths {
+  private constructor(
+    private readonly root: string,
+    private readonly aliases: string[],
+    private readonly windows: boolean,
+  ) {}
+
+  static async create(root: string): Promise<GitObservationPaths> {
+    const windows = looksLikeDefiniteWindowsPath(root);
+    const normalizePath = (value: string) =>
+      windows
+        ? normalizePathPreservingCase(value, true).replaceAll("\\", "/").toLowerCase()
+        : normalizePathPreservingCase(value, false);
+    const aliases = new Set([normalizePath(root)]);
+    // Sequential: foreign paths must not fan out into the shared libuv pool.
+    for (const resolve of [nativeRealpath, jsRealpath]) {
+      try {
+        aliases.add(normalizePath(await identityIo(() => resolve(root))));
+      } catch {
+        /* Missing roots retain lexical identity. */
+      }
+    }
+    // A link may name /var/... while realpath returns /private/var/... on macOS.
+    // Retain literal targets too, including chains, without following links in callbacks.
+    let current = root;
+    const visited = new Set<string>();
+    for (let remaining = 40; remaining > 0; remaining--) {
+      const alias = normalizePath(current);
+      if (visited.has(alias)) break;
+      visited.add(alias);
+      aliases.add(alias);
+      try {
+        const target = await identityIo(() => readlink(current));
+        current = resolvePath(dirname(current), target);
+      } catch {
+        break;
+      }
+    }
+    return new GitObservationPaths(root, [...aliases], windows);
+  }
+
+  relative(candidate: string): string | null {
+    const normalized = this.normalizeEventPath(candidate);
+    const comparable = this.windows ? normalized.toLowerCase() : normalized;
+    for (const alias of this.aliases) {
+      if (comparable === alias) return "";
+      const prefix = alias.endsWith("/") ? alias : `${alias}/`;
+      if (comparable.startsWith(prefix)) {
+        // Slice the original spelling, preserving case in ref names on Windows.
+        return normalized.slice(prefix.length);
+      }
+    }
+    return null;
+  }
+
+  // Compile excluded subtrees in every established root namespace. The event callback
+  // only compares strings; neither an ignored root nor an event needs another realpath.
+  createEventFilter(excludedRoots: Iterable<string>): (candidate: string) => boolean {
+    const excluded: string[] = [];
+    for (const root of excludedRoots) {
+      const relative = this.relative(root);
+      if (relative === null) continue;
+      for (const alias of this.aliases) {
+        const subtree = relative ? `${alias}/${relative}` : alias;
+        excluded.push(this.windows ? subtree.toLowerCase() : subtree);
+      }
+    }
+    const prefixes = excluded.map((root) => `${root}/`);
+    return (candidate) => {
+      const normalized = this.normalizeEventPath(candidate);
+      const comparable = this.windows ? normalized.toLowerCase() : normalized;
+      if (this.aliases.includes(comparable)) return false;
+      for (let i = 0; i < excluded.length; i++) {
+        if (comparable === excluded[i] || comparable.startsWith(prefixes[i])) return false;
+      }
+      return true;
+    };
+  }
+
+  private normalizeEventPath(candidate: string): string {
+    if (this.windows) return normalizePathPreservingCase(candidate, true).replaceAll("\\", "/");
+    if (candidate.includes("/.") || candidate.includes("//") || candidate.endsWith("/"))
+      return normalizePathPreservingCase(candidate, false);
+    return candidate;
+  }
+
+  matches = (candidate: string): boolean => this.relative(candidate) === "";
+
+  toWatchPath(candidate: string): string {
+    const relative = this.relative(candidate);
+    if (relative === null) return candidate;
+    return relative ? `${this.root}${sep}${relative}` : this.root;
+  }
+}
diff --git a/packages/server/src/server/hub/execution-session.websocket.test.ts b/packages/server/src/server/hub/execution-session.websocket.test.ts
index 88f376b3ba..266c55e196 100644
--- a/packages/server/src/server/hub/execution-session.websocket.test.ts
+++ b/packages/server/src/server/hub/execution-session.websocket.test.ts
@@ -248,7 +248,7 @@ test("ordinary Hub requests survive daemon restart and restore an archived works
     }),
   ).toMatchObject({ payload: { agentId, accepted: true } });
   expect(hub.providerPromptTexts().filter((text) => text === "follow up")).toHaveLength(1);
-}, 20_000);
+});
 
 test("Hub completes the standard hello before rejecting a second hello", async () => {
   const hub = await launchRelationship();
diff --git a/packages/server/src/server/hub/relationship-remote.ts b/packages/server/src/server/hub/relationship-remote.ts
index 9c6f88a63d..6427b71fa6 100644
--- a/packages/server/src/server/hub/relationship-remote.ts
+++ b/packages/server/src/server/hub/relationship-remote.ts
@@ -1,5 +1,6 @@
 import { WebSocket } from "ws";
 import { z } from "zod";
+import { webSocketProxyAgent } from "../network/index.js";
 import type { WebSocketLike } from "../websocket-server.js";
 
 const SOCKET_PING_INTERVAL_MS = 10_000;
@@ -166,6 +167,7 @@ export class DirectHubRelationshipRemote implements HubRelationshipRemote {
   openSocket(input: HubSocketCredentials, events: HubSocketEvents): HubSocketConnection {
     let sessionProtocol: "legacy" | "session-v1" = "legacy";
     const socket = new WebSocket(input.webSocketUrl, {
+      agent: webSocketProxyAgent(input.webSocketUrl),
       handshakeTimeout: this.requestTimeoutMs,
       headers: {
         authorization: `Bearer ${input.credential}`,
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 84726d0b02..c3abe397f9 100644
--- a/packages/server/src/server/hub/test-utils/relationship-harness.ts
+++ b/packages/server/src/server/hub/test-utils/relationship-harness.ts
@@ -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/managed-processes/managed-processes.test.ts b/packages/server/src/server/managed-processes/managed-processes.test.ts
index e247db027f..b4be4d16bd 100644
--- a/packages/server/src/server/managed-processes/managed-processes.test.ts
+++ b/packages/server/src/server/managed-processes/managed-processes.test.ts
@@ -12,6 +12,7 @@ import {
   type ManagedProcessInspection,
   type ManagedProcessSnapshot,
   type ManagedProcessTable,
+  windowsPowerShellPath,
 } from "./managed-processes.js";
 import { spawnProcess } from "../../utils/spawn.js";
 import {
@@ -333,7 +334,7 @@ describe("system managed process table", () => {
     });
     expect(commandRunner.commands).toEqual([
       {
-        command: "powershell.exe",
+        command: windowsPowerShellPath(),
         args: [
           "-NoProfile",
           "-NonInteractive",
@@ -345,6 +346,17 @@ describe("system managed process table", () => {
   });
 });
 
+describe("windowsPowerShellPath", () => {
+  test("names Windows PowerShell under SystemRoot, whatever PATH holds", () => {
+    expect(windowsPowerShellPath({ SystemRoot: "D:\\Win", PATH: "" })).toBe(
+      "D:\\Win\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
+    );
+    expect(windowsPowerShellPath({})).toBe(
+      "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
+    );
+  });
+});
+
 class FakeProcessTable implements ManagedProcessTable {
   private readonly snapshots: Map<number, ManagedProcessSnapshot>;
   private readonly errorPids: Set<number>;
diff --git a/packages/server/src/server/managed-processes/managed-processes.ts b/packages/server/src/server/managed-processes/managed-processes.ts
index 0031080c67..43c1b3c810 100644
--- a/packages/server/src/server/managed-processes/managed-processes.ts
+++ b/packages/server/src/server/managed-processes/managed-processes.ts
@@ -7,6 +7,20 @@ import { writeJsonFileAtomic } from "../atomic-file.js";
 import { execCommand } from "../../utils/spawn.js";
 import type { ProcessTerminator, TreeKillTarget } from "../../utils/tree-kill.js";
 
+/**
+ * Windows PowerShell by its install path. Process identity must not depend on the caller's
+ * PATH: a daemon or terminal worker can run with a PATH that does not reach System32.
+ */
+export function windowsPowerShellPath(env: NodeJS.ProcessEnv = process.env): string {
+  return path.win32.join(
+    env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows",
+    "System32",
+    "WindowsPowerShell",
+    "v1.0",
+    "powershell.exe",
+  );
+}
+
 const MANAGED_PROCESS_GRACEFUL_SHUTDOWN_TIMEOUT_MS = 5_000;
 const MANAGED_PROCESS_FORCE_SHUTDOWN_TIMEOUT_MS = 1_000;
 const MANAGED_PROCESS_EXIT_POLL_INTERVAL_MS = 50;
@@ -183,7 +197,7 @@ class SystemManagedProcessTable implements ManagedProcessTable {
       `$process = Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}';`,
       "if ($process) { $process | Select-Object ProcessId,CommandLine,CreationDate | ConvertTo-Json -Compress }",
     ].join(" ");
-    const { stdout } = await this.commandRunner.exec("powershell.exe", [
+    const { stdout } = await this.commandRunner.exec(windowsPowerShellPath(), [
       "-NoProfile",
       "-NonInteractive",
       "-Command",
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/network/index.ts b/packages/server/src/server/network/index.ts
new file mode 100644
index 0000000000..46565d801a
--- /dev/null
+++ b/packages/server/src/server/network/index.ts
@@ -0,0 +1,116 @@
+import type { Agent } from "node:http";
+import { EnvHttpProxyAgent, Pool, setGlobalDispatcher } from "undici";
+import { HttpsProxyAgent } from "https-proxy-agent";
+
+interface ProxyEnvironment {
+  httpProxy: string;
+  httpsProxy: string;
+  noProxy: string;
+}
+
+let environment = readEnvironment(process.env, process.platform).environment;
+
+function readEnvironment(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+): {
+  environment: ProxyEnvironment;
+  ignored: string[];
+} {
+  // process.env lookups are case-insensitive on Windows. Read each actual entry once.
+  const values = new Map(
+    Object.entries(env).map(([name, value]) => [
+      platform === "win32" ? name.toLowerCase() : name,
+      value,
+    ]),
+  );
+  const ignored: string[] = [];
+  function proxy(variable: string): string | undefined {
+    const value = values.get(variable);
+    if (value === undefined) return undefined;
+    if (!value.trim()) return undefined;
+    try {
+      const url = new URL(value.includes("://") ? value : `http://${value}`);
+      if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw new Error("Unsupported proxy protocol");
+      decodeURIComponent(url.username);
+      decodeURIComponent(url.password);
+      return url.href;
+    } catch {
+      ignored.push(variable);
+      return undefined;
+    }
+  }
+  const httpProxy = proxy("http_proxy") ?? proxy("HTTP_PROXY") ?? "";
+  return {
+    environment: {
+      httpProxy,
+      httpsProxy: proxy("https_proxy") ?? proxy("HTTPS_PROXY") ?? httpProxy,
+      noProxy: values.get("no_proxy") ?? values.get("NO_PROXY") ?? "",
+    },
+    ignored,
+  };
+}
+
+function bypassList(noProxy: string): string {
+  return noProxy.split(/[,\s]+/).includes("*") ? "*" : `${noProxy},localhost,127.0.0.1,[::1],::1`;
+}
+
+function proxyClient(origin: URL, options: object) {
+  const pool = new Pool(origin, options);
+  if (!origin.username && !origin.password) return pool;
+  const credentials = `${decodeURIComponent(origin.username)}:${decodeURIComponent(origin.password)}`;
+  const authorization = `Basic ${Buffer.from(credentials).toString("base64")}`;
+  // This pool only sends CONNECT requests to this proxy, never requests to the origin.
+  // undici's URL auth requires both fields; HTTP Basic also permits either field to be empty.
+  return pool.compose(
+    (dispatch) => (request, handler) =>
+      dispatch(
+        {
+          ...request,
+          headers: { ...request.headers, "proxy-authorization": authorization },
+        },
+        handler,
+      ),
+  );
+}
+
+/** Install once at startup; return ignored variable names for logging without exposing credentials. */
+export function initializeEnvironmentProxy(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string[] {
+  const resolved = readEnvironment(env, platform);
+  environment = resolved.environment;
+  setGlobalDispatcher(
+    new EnvHttpProxyAgent({
+      httpProxy: environment.httpProxy,
+      httpsProxy: environment.httpsProxy,
+      noProxy: bypassList(environment.noProxy),
+      clientFactory: proxyClient,
+    }),
+  );
+  return resolved.ignored;
+}
+
+/** ws uses Node HTTP agents rather than the fetch dispatcher. */
+export function webSocketProxyAgent(address: string): Agent | undefined {
+  const url = new URL(address);
+  const hostname = url.hostname.toLowerCase();
+  const port = url.port || (url.protocol === "wss:" ? "443" : "80");
+  const entries = bypassList(environment.noProxy)
+    .toLowerCase()
+    .split(/[,\s]+/);
+  if (
+    entries.some((entry) => {
+      if (entry === "*") return true;
+      const match = entry.match(/^(.+):(\d+)$/);
+      if (match && Number(match[2]) !== Number(port)) return false;
+      const host = (match ? match[1]! : entry).replace(/^\*?\./, "");
+      return host !== "" && (hostname === host || hostname.endsWith(`.${host}`));
+    })
+  )
+    return undefined;
+  const proxy = url.protocol === "wss:" ? environment.httpsProxy : environment.httpProxy;
+  return proxy ? new HttpsProxyAgent(proxy) : undefined;
+}
diff --git a/packages/server/src/server/network/network.test.ts b/packages/server/src/server/network/network.test.ts
new file mode 100644
index 0000000000..88e7d61aa6
--- /dev/null
+++ b/packages/server/src/server/network/network.test.ts
@@ -0,0 +1,341 @@
+import { fork } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServer, type Server } from "node:http";
+import { once } from "node:events";
+import { connect } from "node:net";
+import { afterEach, expect, test } from "vitest";
+import { WebSocket, WebSocketServer } from "ws";
+import { getGlobalDispatcher, setGlobalDispatcher } from "undici";
+import { initializeEnvironmentProxy, webSocketProxyAgent } from "./index.js";
+import { ConnectedHosts } from "../connected-hosts/index.js";
+const original = getGlobalDispatcher();
+const servers: Server[] = [];
+afterEach(async () => {
+  const installed = getGlobalDispatcher();
+  setGlobalDispatcher(original);
+  if (installed !== original) await installed.close();
+  await Promise.all(
+    servers.splice(0).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          server.closeAllConnections();
+          server.close(() => resolve());
+        }),
+    ),
+  );
+});
+async function listen(server: Server) {
+  servers.push(server);
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Missing address");
+  return `127.0.0.1:${address.port}`;
+}
+async function proxy() {
+  const tunnels: string[] = [];
+  const server = createServer();
+  server.on("connect", (request, socket) => {
+    tunnels.push(request.url!);
+    socket.end("HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n");
+  });
+  return { url: `http://${await listen(server)}`, tunnels };
+}
+test("loopback fetch and WebSockets bypass HTTP_PROXY with empty NO_PROXY", async () => {
+  const recorder = await proxy();
+  initializeEnvironmentProxy({ HTTP_PROXY: recorder.url, NO_PROXY: "" });
+  const server = createServer((_, response) => response.end("direct"));
+  const sockets = new WebSocketServer({ server });
+  sockets.on("connection", (socket) => socket.send("direct"));
+  const address = await listen(server);
+  expect(await (await fetch(`http://${address}`)).text()).toBe("direct");
+  const socket = new WebSocket(`ws://${address}`, {
+    agent: webSocketProxyAgent(`ws://${address}`),
+  });
+  expect((await once(socket, "message"))[0].toString()).toBe("direct");
+  socket.close();
+  await once(socket, "close");
+  await new Promise<void>((resolve) => sockets.close(() => resolve()));
+  for (const host of ["localhost", "127.0.0.1", "[::1]"])
+    expect(webSocketProxyAgent(`wss://${host}:1234`)).toBeUndefined();
+  expect(recorder.tunnels).toEqual([]);
+});
+test("fetch and WebSockets send non-loopback traffic through CONNECT", async () => {
+  const recorder = await proxy();
+  initializeEnvironmentProxy({ http_proxy: recorder.url });
+  await expect(
+    fetch("https://vendor.invalid/", { signal: AbortSignal.timeout(500) }),
+  ).rejects.toThrow();
+  const socket = new WebSocket("wss://vendor.invalid", {
+    agent: webSocketProxyAgent("wss://vendor.invalid"),
+  });
+  await once(socket, "error");
+  expect(
+    recorder.tunnels.filter((host) => host === "vendor.invalid:443").length,
+  ).toBeGreaterThanOrEqual(2);
+});
+test("NO_PROXY and absent variables keep matching WebSockets direct", async () => {
+  const recorder = await proxy();
+  initializeEnvironmentProxy({
+    HTTPS_PROXY: recorder.url,
+    NO_PROXY: "vendor.invalid,.example.invalid:443",
+  });
+  expect(webSocketProxyAgent("wss://vendor.invalid")).toBeUndefined();
+  await expect(
+    fetch("https://vendor.invalid/", { signal: AbortSignal.timeout(500) }),
+  ).rejects.toThrow();
+  expect(webSocketProxyAgent("wss://sub.example.invalid")).toBeUndefined();
+  expect(webSocketProxyAgent("wss://example.invalid:444")).toBeDefined();
+  initializeEnvironmentProxy({ HTTP_PROXY: recorder.url, no_proxy: "*" });
+  expect(webSocketProxyAgent("ws://vendor.invalid")).toBeUndefined();
+  initializeEnvironmentProxy({});
+  expect(webSocketProxyAgent("wss://vendor.invalid")).toBeUndefined();
+  const address = await listen(createServer((_, response) => response.end("direct")));
+  expect(await (await fetch(`http://${address}`)).text()).toBe("direct");
+  expect(recorder.tunnels).toEqual([]);
+});
+
+test.each(["127.0.0.1", "localhost"])(
+  "scheme-less %s proxies work for fetch and WebSockets",
+  async (host) => {
+    const recorder = await proxy();
+    const address = new URL(recorder.url);
+    initializeEnvironmentProxy({ https_proxy: `${host}:${address.port}` });
+    await expect(
+      fetch("https://vendor.invalid", { signal: AbortSignal.timeout(500) }),
+    ).rejects.toThrow();
+    const socket = new WebSocket("wss://vendor.invalid", {
+      agent: webSocketProxyAgent("wss://vendor.invalid"),
+    });
+    await once(socket, "error");
+    expect(recorder.tunnels).toContain("vendor.invalid:443");
+  },
+);
+
+test.each([
+  "http://[",
+  "http://user%zz:secret@proxy.corp",
+  "socks5://127.0.0.1:7890",
+  "ftp://proxy.corp:8080",
+])("ignores invalid or unsupported proxy %s without stopping startup", async (value) => {
+  const recorder = await proxy();
+  expect(initializeEnvironmentProxy({ HTTP_PROXY: recorder.url, https_proxy: value })).toEqual([
+    "https_proxy",
+  ]);
+  expect(webSocketProxyAgent("wss://vendor.invalid")).toBeDefined();
+  await expect(
+    fetch("https://vendor.invalid", { signal: AbortSignal.timeout(500) }),
+  ).rejects.toThrow();
+  const socket = new WebSocket("wss://vendor.invalid", {
+    agent: webSocketProxyAgent("wss://vendor.invalid"),
+  });
+  await once(socket, "error");
+  expect(recorder.tunnels).toEqual(["vendor.invalid:443", "vendor.invalid:443"]);
+});
+
+test("daemon starts with an ignored proxy and writes one redacted warning to daemon.log", async () => {
+  const home = await mkdtemp(path.join(os.tmpdir(), "daemon-invalid-proxy-"));
+  const env = Object.fromEntries(
+    Object.entries(process.env).filter(
+      ([key]) => !["http_proxy", "https_proxy"].includes(key.toLowerCase()),
+    ),
+  );
+  const worker = fork(fileURLToPath(new URL("../daemon-worker.ts", import.meta.url)), [], {
+    execArgv: ["--import", "tsx"],
+    silent: true,
+    env: {
+      ...env,
+      PASEO_HOME: home,
+      HOME: home,
+      USERPROFILE: home,
+      PASEO_LISTEN: "127.0.0.1:0",
+      PASEO_RELAY_ENABLED: "0",
+      https_proxy: "socks5://private:secret@127.0.0.1:7890",
+    },
+  });
+  worker.stdout?.resume();
+  let stderr = "";
+  worker.stderr?.on("data", (chunk) => {
+    stderr += String(chunk);
+  });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      worker.on("message", (message) => {
+        if (
+          typeof message === "object" &&
+          message !== null &&
+          "type" in message &&
+          message.type === "paseo:ready"
+        )
+          resolve();
+      });
+      worker.on("exit", (code) => reject(new Error(`Worker exited ${code}: ${stderr}`)));
+    });
+    const log = await readFile(path.join(home, "daemon.log"), "utf8");
+    const warnings = log
+      .split("\n")
+      .filter((line) => line.includes("Ignoring invalid or unsupported HTTP proxy variable"));
+    expect(warnings).toHaveLength(1);
+    expect(JSON.parse(warnings[0]!).variable).toBe("https_proxy");
+    expect(warnings[0]).not.toContain("secret");
+  } finally {
+    if (worker.exitCode === null && worker.signalCode === null) {
+      const exited = once(worker, "exit");
+      worker.kill("SIGTERM");
+      await exited;
+    }
+    await rm(home, { recursive: true, force: true });
+  }
+}, 60_000);
+
+test("accepts a scheme-less corporate proxy hostname", () => {
+  expect(initializeEnvironmentProxy({ https_proxy: "proxy.corp:8080" })).toEqual([]);
+  expect(webSocketProxyAgent("wss://vendor.invalid")).toBeDefined();
+});
+
+test("an ignored lowercase variable falls back to the uppercase variable", async () => {
+  const recorder = await proxy();
+  expect(
+    initializeEnvironmentProxy(
+      {
+        https_proxy: "socks5://proxy.invalid",
+        HTTPS_PROXY: recorder.url,
+      },
+      "linux",
+    ),
+  ).toEqual(["https_proxy"]);
+  await expect(
+    fetch("https://vendor.invalid", { signal: AbortSignal.timeout(500) }),
+  ).rejects.toThrow();
+  const socket = new WebSocket("wss://vendor.invalid", {
+    agent: webSocketProxyAgent("wss://vendor.invalid"),
+  });
+  await once(socket, "error");
+  expect(recorder.tunnels).toEqual(["vendor.invalid:443", "vendor.invalid:443"]);
+});
+
+test("case-insensitive environment access reports a variable only once", () => {
+  const env = new Proxy(
+    { https_proxy: "socks5://127.0.0.1:7890" },
+    {
+      get(target, key) {
+        return Reflect.get(target, typeof key === "string" ? key.toLowerCase() : key);
+      },
+    },
+  );
+  expect(initializeEnvironmentProxy(env)).toEqual(["https_proxy"]);
+});
+
+test("connected-host links send remote WebSockets through the environment proxy", async () => {
+  const recorder = await proxy();
+  initializeEnvironmentProxy({ HTTPS_PROXY: recorder.url });
+  const home = await mkdtemp(path.join(os.tmpdir(), "connected-host-proxy-"));
+  const hosts = new ConnectedHosts(home, { serverId: "self", label: "Self" });
+  try {
+    await hosts.add(
+      { connection: "wss://remote.invalid/ws" },
+      { sourceId: "test", manageSources: true },
+    );
+    await expect.poll(() => recorder.tunnels).toContain("remote.invalid:443");
+  } finally {
+    await hosts.close();
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test.each(["corp.internal,*", "vendor.invalid:0443"])(
+  "fetch and WebSockets share NO_PROXY=%s",
+  async (noProxy) => {
+    const recorder = await proxy();
+    initializeEnvironmentProxy({ HTTPS_PROXY: recorder.url, NO_PROXY: noProxy });
+    expect(webSocketProxyAgent("wss://vendor.invalid")).toBeUndefined();
+    await expect(
+      fetch("https://vendor.invalid", { signal: AbortSignal.timeout(500) }),
+    ).rejects.toThrow();
+    expect(recorder.tunnels).toEqual([]);
+  },
+);
+
+test("Windows mixed-case environment names route and bypass both transports", async () => {
+  const recorder = await proxy();
+  // Windows preserves spelling but treats environment names without regard to case.
+  initializeEnvironmentProxy({ Https_Proxy: recorder.url, No_Proxy: "other.invalid" }, "win32");
+  expect(webSocketProxyAgent("wss://other.invalid")).toBeUndefined();
+  await expect(
+    fetch("https://other.invalid", { signal: AbortSignal.timeout(500) }),
+  ).rejects.toThrow();
+  expect(webSocketProxyAgent("wss://vendor.invalid")).toBeDefined();
+  await expect(
+    fetch("https://vendor.invalid", { signal: AbortSignal.timeout(500) }),
+  ).rejects.toThrow();
+  const socket = new WebSocket("wss://vendor.invalid", {
+    agent: webSocketProxyAgent("wss://vendor.invalid"),
+  });
+  await once(socket, "error");
+  expect(recorder.tunnels).toEqual(["vendor.invalid:443", "vendor.invalid:443"]);
+});
+
+test("POSIX mixed-case names do not override standard proxy names", async () => {
+  const recorder = await proxy();
+  initializeEnvironmentProxy(
+    { Https_Proxy: recorder.url, HTTPS_PROXY: recorder.url, No_Proxy: "*" },
+    "linux",
+  );
+  expect(webSocketProxyAgent("wss://vendor.invalid")).toBeDefined();
+  await expect(
+    fetch("https://vendor.invalid", { signal: AbortSignal.timeout(500) }),
+  ).rejects.toThrow();
+  expect(recorder.tunnels).toEqual(["vendor.invalid:443"]);
+});
+
+test("proxy credentials stay on CONNECT and do not reach the HTTP origin", async () => {
+  let originAuthorization: string | undefined;
+  const origin = createServer((request, response) => {
+    originAuthorization = request.headers["proxy-authorization"];
+    response.end("through proxy");
+  });
+  const originAddress = new URL(`http://${await listen(origin)}`);
+  const authorizations: (string | undefined)[] = [];
+  const server = createServer();
+  server.on("connect", (request, socket, head) => {
+    authorizations.push(request.headers["proxy-authorization"]);
+    const upstream = connect(Number(originAddress.port), "127.0.0.1", () => {
+      socket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+      if (head.length) upstream.write(head);
+      socket.pipe(upstream).pipe(socket);
+    });
+    socket.on("error", () => upstream.destroy());
+    upstream.on("error", () => socket.destroy());
+    socket.on("close", () => upstream.destroy());
+  });
+  initializeEnvironmentProxy({ HTTP_PROXY: `http://user:@${await listen(server)}` });
+  const response = await fetch("http://vendor.invalid", { signal: AbortSignal.timeout(3000) });
+  expect(await response.text()).toBe("through proxy");
+  expect(authorizations).toEqual([`Basic ${Buffer.from("user:").toString("base64")}`]);
+  expect(originAuthorization).toBeUndefined();
+});
+
+test.each(["user:@", ":secret@", "user:secret@"])(
+  "fetch and WebSockets authenticate proxy credentials %s",
+  async (credentials) => {
+    const authorizations: (string | undefined)[] = [];
+    const server = createServer();
+    server.on("connect", (request, socket) => {
+      authorizations.push(request.headers["proxy-authorization"]);
+      socket.end("HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n");
+    });
+    initializeEnvironmentProxy({ HTTPS_PROXY: `http://${credentials}${await listen(server)}` });
+    await expect(
+      fetch("https://vendor.invalid", { signal: AbortSignal.timeout(500) }),
+    ).rejects.toThrow();
+    const socket = new WebSocket("wss://vendor.invalid", {
+      agent: webSocketProxyAgent("wss://vendor.invalid"),
+    });
+    await once(socket, "error");
+    const expected = `Basic ${Buffer.from(credentials.slice(0, -1)).toString("base64")}`;
+    expect(authorizations).toEqual([expected, expected]);
+  },
+);
diff --git a/packages/server/src/server/orchestration-skills/internal/selection-store.test.ts b/packages/server/src/server/orchestration-skills/internal/selection-store.test.ts
index 5a42fd0dac..50fb071fef 100644
--- a/packages/server/src/server/orchestration-skills/internal/selection-store.test.ts
+++ b/packages/server/src/server/orchestration-skills/internal/selection-store.test.ts
@@ -57,7 +57,7 @@ describe("daemon agent skill selection", () => {
   it("does not expose selection through the generic config patch path", async () => {
     const { config, root, store } = await createStore();
 
-    config.patch({
+    await config.patch({
       skills: { selection: { mode: "custom", skills: ["paseo"] } },
     } as MutableDaemonConfigPatch);
 
diff --git a/packages/server/src/server/orchestration-skills/internal/selection-store.ts b/packages/server/src/server/orchestration-skills/internal/selection-store.ts
index 6fa00af6e6..a3f7f95569 100644
--- a/packages/server/src/server/orchestration-skills/internal/selection-store.ts
+++ b/packages/server/src/server/orchestration-skills/internal/selection-store.ts
@@ -43,7 +43,7 @@ export function createSkillSelectionStore(
     },
     async set(selection) {
       const parsed = coerceSkillSelection(selection);
-      configStore.setAgentSkillSelection(parsed);
+      await configStore.setAgentSkillSelection(parsed);
       return parsed;
     },
     async isSet() {
diff --git a/packages/server/src/server/owned-subscriptions.e2e.test.ts b/packages/server/src/server/owned-subscriptions.e2e.test.ts
index 68437daf70..fc73e44db4 100644
--- a/packages/server/src/server/owned-subscriptions.e2e.test.ts
+++ b/packages/server/src/server/owned-subscriptions.e2e.test.ts
@@ -1,7 +1,8 @@
 import { MockLoadTestAgentClient } from "./agent/providers/mock-load-test-agent.js";
 import { createPaseoApi } from "@getpaseo/client";
+import type { AgentManager } from "./agent/agent-manager.js";
 import { execFileSync } from "node:child_process";
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { expect, test } from "vitest";
 import type { z } from "zod";
@@ -71,15 +72,18 @@ class SubscriptionPeer {
   async request(message: z.input<typeof SessionInboundMessageSchema>): Promise<void> {
     this.socket.send(JSON.stringify({ type: "session", message }));
     await expect
-      .poll(() =>
-        this.frames.some(
-          (frame) =>
-            frame.type === "session" &&
-            "payload" in frame.message &&
-            "requestId" in frame.message.payload &&
-            "requestId" in message &&
-            frame.message.payload.requestId === message.requestId,
-        ),
+      .poll(
+        () =>
+          this.frames.some(
+            (frame) =>
+              frame.type === "session" &&
+              "payload" in frame.message &&
+              "requestId" in frame.message.payload &&
+              "requestId" in message &&
+              frame.message.payload.requestId === message.requestId,
+          ),
+        // Diagnostics invoke external tools with their own multi-second deadlines.
+        { timeout: 10_000 },
       )
       .toBe(true);
   }
@@ -119,6 +123,16 @@ class SubscriptionPeer {
   }
 }
 
+function removedAgentIds(peer: SubscriptionPeer): string[] {
+  return peer.frames.flatMap((frame) =>
+    frame.type === "session" &&
+    frame.message.type === "agent_update" &&
+    frame.message.payload.kind === "remove"
+      ? [frame.message.payload.agentId]
+      : [],
+  );
+}
+
 test("a pure list reply belongs only to its source socket in a shared logical session", async () => {
   const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
   const peers: SubscriptionPeer[] = [];
@@ -225,6 +239,96 @@ test("combined filtered agent lists create independent server-owned observations
   }
 });
 
+test.each([
+  {
+    state: "live",
+    prepare: async (_manager: AgentManager, _agentId: string) => {},
+  },
+  {
+    state: "stored-only",
+    prepare: (manager: AgentManager, agentId: string) => manager.closeAgent(agentId),
+  },
+])(
+  "$state agent deletion reaches directory observers across logical sessions without broadcasting its reply",
+  async ({ prepare }) => {
+    const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
+    const admin = new DaemonClient({
+      url: `ws://127.0.0.1:${daemon.port}/ws`,
+      appVersion: "0.8.0",
+    });
+    const peers: SubscriptionPeer[] = [];
+    try {
+      await admin.connect();
+      const workspace = (
+        await admin.createWorkspace({ source: { kind: "directory", path: daemon.staticDir } })
+      ).workspace;
+      if (!workspace) throw new Error("Workspace creation failed");
+      const removed = await admin.createAgent({
+        provider: "codex",
+        cwd: daemon.staticDir,
+        workspaceId: workspace.id,
+      });
+      const survivor = await admin.createAgent({
+        provider: "codex",
+        cwd: daemon.staticDir,
+        workspaceId: workspace.id,
+      });
+      const sentinel = path.join(daemon.staticDir, "keep-project-file.txt");
+      await writeFile(sentinel, "keep this project file\n");
+      await prepare(daemon.daemon.agentManager, removed.id);
+      const requester = await SubscriptionPeer.connect(daemon.port, "deletion-origin");
+      const sibling = await SubscriptionPeer.connect(daemon.port, "deletion-origin");
+      const observer = await SubscriptionPeer.connect(daemon.port, "deletion-observer");
+      const legacy = await SubscriptionPeer.connect(daemon.port, "deletion-legacy", {
+        owned_subscriptions: false,
+      });
+      peers.push(requester, sibling, observer, legacy);
+      for (const [index, peer] of peers.entries()) {
+        await peer.request({
+          type: "fetch_agents_request",
+          requestId: `directory-${index}`,
+          subscribe: {},
+        });
+        const entries = peer.frames.flatMap((frame) =>
+          frame.type === "session" && frame.message.type === "fetch_agents_response"
+            ? frame.message.payload.entries.map((entry) => entry.agent.id)
+            : [],
+        );
+        expect(entries.sort()).toEqual([removed.id, survivor.id].sort());
+        peer.frames.length = 0;
+      }
+      await requester.request({
+        type: "delete_agent_request",
+        requestId: "delete-observed-agent",
+        agentId: removed.id,
+      });
+      await expect
+        .poll(() => peers.map(removedAgentIds))
+        .toEqual([[removed.id], [removed.id], [removed.id], [removed.id]]);
+      const replies = peers.map((peer) =>
+        peer.frames.flatMap((frame) =>
+          frame.type === "session" && frame.message.type === "agent_deleted"
+            ? [frame.message.payload]
+            : [],
+        ),
+      );
+      expect(replies).toEqual([
+        [{ agentId: removed.id, requestId: "delete-observed-agent" }],
+        [],
+        [],
+        [],
+      ]);
+      expect(await daemon.daemon.agentStorage.get(removed.id)).toBeNull();
+      expect((await daemon.daemon.agentStorage.get(survivor.id))?.id).toBe(survivor.id);
+      expect(await readFile(sentinel, "utf8")).toBe("keep this project file\n");
+    } finally {
+      for (const peer of peers) peer.close();
+      await admin.close();
+      await daemon.close();
+    }
+  },
+);
+
 test("workspace filters and identical queries coexist until their own release", async () => {
   const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
   const admin = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.8.0" });
@@ -679,7 +783,8 @@ test("same-workspace terminal directory observers do not share a teardown slot",
     peer.frames.length = 0;
     const result = await admin.createTerminal(daemon.staticDir, "Observed terminal", undefined, {
       workspaceId: workspace.id,
-      command: "/bin/cat",
+      command: process.execPath,
+      args: ["-e", "process.stdin.on('data', data => process.stdout.write(data))"],
     });
     expect(result.error).toBe(null);
     await expect
@@ -717,85 +822,100 @@ test("same-workspace terminal directory observers do not share a teardown slot",
   }
 });
 
-test("terminal output has separate server IDs and binary slots, including in a shared session", async () => {
-  const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
-  const admin = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.8.0" });
-  const peers: SubscriptionPeer[] = [];
-  try {
-    await admin.connect();
-    const workspace = (
-      await admin.createWorkspace({ source: { kind: "directory", path: daemon.staticDir } })
-    ).workspace!;
-    const result = await admin.createTerminal(daemon.staticDir, "Output ownership", undefined, {
-      workspaceId: workspace.id,
-      command: "/bin/cat",
+test.each([false, true])(
+  "terminal output has separate server IDs and binary slots, including in a shared session (chunked=%s)",
+  async (chunked) => {
+    const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
+    const admin = new DaemonClient({
+      url: `ws://127.0.0.1:${daemon.port}/ws`,
+      appVersion: "0.8.0",
     });
-    expect(result.error).toBe(null);
-    const idle = await SubscriptionPeer.connect(daemon.port, "terminal-output-session");
-    peers.push(idle);
-    const peer = await SubscriptionPeer.connect(daemon.port, "terminal-output-session");
-    peers.push(peer);
-    for (const requestId of ["output-a", "output-b"]) {
-      await peer.request({
-        type: "subscribe_terminal_request",
-        requestId,
-        terminalId: result.terminal!.id,
+    const peers: SubscriptionPeer[] = [];
+    try {
+      await admin.connect();
+      const workspace = (
+        await admin.createWorkspace({ source: { kind: "directory", path: daemon.staticDir } })
+      ).workspace!;
+      const result = await admin.createTerminal(daemon.staticDir, "Output ownership", undefined, {
+        workspaceId: workspace.id,
+        command: process.execPath,
+        args: ["-e", "process.stdin.on('data', data => process.stdout.write(data))"],
       });
-    }
-    const replies = peer.frames.flatMap((frame) =>
-      frame.type === "session" &&
-      frame.message.type === "subscribe_terminal_response" &&
-      frame.message.payload.error === null
-        ? [frame.message.payload]
-        : [],
-    );
-    expect(replies).toHaveLength(2);
-    const ids = replies.map(
-      (reply) => (reply as typeof reply & { subscriptionId: string }).subscriptionId,
-    );
-    expect(ids.every((id) => typeof id === "string")).toBe(true);
-    expect(ids[0]).not.toBe(ids[1]);
-    expect(replies[0].slot).not.toBe(replies[1].slot);
-    await expect
-      .poll(() =>
-        peer.binaryFrames
-          .map(decodeTerminalStreamFrame)
-          .filter((frame) => frame?.opcode === TerminalStreamOpcode.Snapshot)
-          .map((frame) => frame!.slot),
-      )
-      .toEqual(expect.arrayContaining(replies.map((reply) => reply.slot)));
-    expect(idle.binaryFrames).toEqual([]);
-    await peer.request({
-      type: "subscription.release.request",
-      requestId: "release-output-a",
-      subscriptionId: ids[0],
-    });
-    peer.binaryFrames.length = 0;
-    admin.sendTerminalInput(result.terminal!.id, { type: "input", data: "remaining-observer\n" });
-    await expect
-      .poll(
-        () =>
+      expect(result.error).toBe(null);
+      const idle = await SubscriptionPeer.connect(daemon.port, "terminal-output-session", {
+        terminal_chunked_replay: chunked,
+      });
+      peers.push(idle);
+      const peer = await SubscriptionPeer.connect(daemon.port, "terminal-output-session", {
+        terminal_chunked_replay: chunked,
+      });
+      peers.push(peer);
+      for (const requestId of ["output-a", "output-b"]) {
+        await peer.request({
+          type: "subscribe_terminal_request",
+          requestId,
+          terminalId: result.terminal!.id,
+        });
+      }
+      const replies = peer.frames.flatMap((frame) =>
+        frame.type === "session" &&
+        frame.message.type === "subscribe_terminal_response" &&
+        frame.message.payload.error === null
+          ? [frame.message.payload]
+          : [],
+      );
+      expect(replies).toHaveLength(2);
+      const ids = replies.map(
+        (reply) => (reply as typeof reply & { subscriptionId: string }).subscriptionId,
+      );
+      expect(ids.every((id) => typeof id === "string")).toBe(true);
+      expect(ids[0]).not.toBe(ids[1]);
+      expect(replies[0].slot).not.toBe(replies[1].slot);
+      await expect
+        .poll(() =>
           peer.binaryFrames
             .map(decodeTerminalStreamFrame)
-            .filter((frame) => frame?.opcode === TerminalStreamOpcode.Output)
-            .map((frame) => Buffer.from(frame!.payload).toString())
-            .join(""),
-        { timeout: 5000 },
-      )
-      .toContain("remaining-observer");
-    expect(
-      peer.binaryFrames
-        .map(decodeTerminalStreamFrame)
-        .every((frame) => frame?.slot === replies[1].slot),
-    ).toBe(true);
-    expect(idle.binaryFrames).toEqual([]);
-    await admin.killTerminal(result.terminal!.id);
-  } finally {
-    for (const peer of peers) peer.close();
-    await admin.close();
-    await daemon.close();
-  }
-});
+            .filter(
+              (frame) =>
+                frame?.opcode ===
+                (chunked ? TerminalStreamOpcode.ReplayEnd : TerminalStreamOpcode.Restore),
+            )
+            .map((frame) => frame!.slot),
+        )
+        .toEqual(expect.arrayContaining(replies.map((reply) => reply.slot)));
+      expect(idle.binaryFrames).toEqual([]);
+      await peer.request({
+        type: "subscription.release.request",
+        requestId: "release-output-a",
+        subscriptionId: ids[0],
+      });
+      peer.binaryFrames.length = 0;
+      admin.sendTerminalInput(result.terminal!.id, { type: "input", data: "remaining-observer\n" });
+      await expect
+        .poll(
+          () =>
+            peer.binaryFrames
+              .map(decodeTerminalStreamFrame)
+              .filter((frame) => frame?.opcode === TerminalStreamOpcode.Output)
+              .map((frame) => Buffer.from(frame!.payload).toString())
+              .join(""),
+          { timeout: 5000 },
+        )
+        .toContain("remaining-observer");
+      expect(
+        peer.binaryFrames
+          .map(decodeTerminalStreamFrame)
+          .every((frame) => frame?.slot === replies[1].slot),
+      ).toBe(true);
+      expect(idle.binaryFrames).toEqual([]);
+      await admin.killTerminal(result.terminal!.id);
+    } finally {
+      for (const peer of peers) peer.close();
+      await admin.close();
+      await daemon.close();
+    }
+  },
+);
 
 test("a modern connection and pure reads retain no client observation producers", async () => {
   const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
@@ -1423,7 +1543,7 @@ test("request outcomes for import and attention reach only their requesting sock
   });
   const requester = await SubscriptionPeer.connect(daemon.port, "reply-shared");
   const sibling = await SubscriptionPeer.connect(daemon.port, "reply-shared");
-  const admin = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  const admin = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.8.0" });
   try {
     await admin.connect();
     await requester.request({
@@ -1462,7 +1582,7 @@ test("request outcomes for import and attention reach only their requesting sock
       }),
     );
     const agent = await admin.createAgent({
-      provider: "codex",
+      provider: "mock",
       cwd: daemon.staticDir,
       title: "Attention",
     });
diff --git a/packages/server/src/server/paseo-worktree-service.test.ts b/packages/server/src/server/paseo-worktree-service.test.ts
index 66740d2ae2..dc5780ebf9 100644
--- a/packages/server/src/server/paseo-worktree-service.test.ts
+++ b/packages/server/src/server/paseo-worktree-service.test.ts
@@ -548,7 +548,7 @@ test("renames an eligible unnamed branch-off worktree once on first agent contex
   );
 
   expect(created.worktree.branchName).toBe("dazzling-yak");
-  expect(readPaseoWorktreeMetadata(created.worktree.worktreePath)).toMatchObject({
+  expect(await readPaseoWorktreeMetadata(created.worktree.worktreePath)).toMatchObject({
     version: 2,
     firstAgentBranchAutoName: {
       status: "pending",
@@ -575,7 +575,7 @@ test("renames an eligible unnamed branch-off worktree once on first agent contex
     branchName: "renamed-from-agent-context",
   });
   expect(branchAfterFirst).toBe("renamed-from-agent-context");
-  expect(readPaseoWorktreeMetadata(created.worktree.worktreePath)).toMatchObject({
+  expect(await readPaseoWorktreeMetadata(created.worktree.worktreePath)).toMatchObject({
     version: 2,
     firstAgentBranchAutoName: {
       status: "attempted",
@@ -762,7 +762,7 @@ test("leaves the branch alone when generated branch text is invalid", async () =
       .toString()
       .trim(),
   ).toBe("dazzling-yak");
-  expect(readPaseoWorktreeMetadata(created.worktree.worktreePath)).toMatchObject({
+  expect(await readPaseoWorktreeMetadata(created.worktree.worktreePath)).toMatchObject({
     version: 2,
     firstAgentBranchAutoName: {
       status: "attempted",
@@ -794,7 +794,7 @@ test("does not mark checkout branch worktrees as eligible for first-agent rename
   // baseRefName must be the repo's default branch, not the checked-out branch
   // itself — otherwise the diff panel compares the branch against itself and
   // always shows no changes.
-  expect(readPaseoWorktreeMetadata(created.worktree.worktreePath)).toMatchObject({
+  expect(await readPaseoWorktreeMetadata(created.worktree.worktreePath)).toMatchObject({
     version: 1,
     baseRefName: "main",
   });
@@ -831,7 +831,7 @@ test("does not mark GitHub PR checkout worktrees as eligible for first-agent ren
     createDeps(),
   );
 
-  expect(readPaseoWorktreeMetadata(created.worktree.worktreePath)).toMatchObject({
+  expect(await readPaseoWorktreeMetadata(created.worktree.worktreePath)).toMatchObject({
     version: 1,
     baseRefName: "main",
   });
@@ -1092,7 +1092,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 61e00723d0..1205554d4a 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 { PluginLifecycle } from "./plugins/lifecycle/index.js";
 import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
 
@@ -59,6 +60,7 @@ export interface AttemptFirstAgentBranchAutoNameResult {
 }
 
 export interface CreatePaseoWorktreeDeps extends CreateWorktreeCoreDeps {
+  lifecycle?: Pick<PluginLifecycle, "wait" | "before">;
   workspaceGitService: WorkspaceGitService;
   workspaceProvisioning: Pick<WorkspaceProvisioningService, "createWorkspaceForWorktree">;
 }
@@ -77,7 +79,16 @@ async function createPaseoWorktreeWithPriority(
   const workspaceCwdPlan = await planWorkspaceCwdForWorktree(input.cwd, deps.workspaceGitService);
   const createdWorktree = await createWorktreeCore(input, deps);
   try {
-    maybeMarkFirstAgentBranchAutoNameEligible({ createdWorktree });
+    if (createdWorktree.created) {
+      await deps.lifecycle?.wait("worktree.create.after", {
+        worktree: {
+          path: createdWorktree.worktree.worktreePath,
+          branch: createdWorktree.worktree.branchName,
+          sourceCheckout: workspaceCwdPlan.sourceCheckout,
+        },
+      });
+    }
+    await maybeMarkFirstAgentBranchAutoNameEligible({ createdWorktree });
     const workspaceCwd = mapWorkspaceRelativeCwdToWorktree({
       relativeWorkspaceCwd: workspaceCwdPlan.relativeWorkspaceCwd,
       targetWorktreePath: createdWorktree.worktree.worktreePath,
@@ -155,7 +166,7 @@ async function isDirectory(targetPath: string): Promise<boolean> {
 async function planWorkspaceCwdForWorktree(
   inputCwd: string,
   workspaceGitService: Pick<WorkspaceGitService, "getCheckout">,
-): Promise<{ inputCwd: string; relativeWorkspaceCwd: string }> {
+): Promise<{ inputCwd: string; relativeWorkspaceCwd: string; sourceCheckout: string }> {
   const normalizedInputCwd = resolve(inputCwd);
   const sourceCheckout = await workspaceGitService.getCheckout(normalizedInputCwd);
   const sourceWorktreePath = sourceCheckout.worktreeRoot ?? normalizedInputCwd;
@@ -163,7 +174,7 @@ async function planWorkspaceCwdForWorktree(
   if (relativeWorkspaceCwd === null) {
     throw new Error(`Workspace cwd is outside its source worktree: ${normalizedInputCwd}`);
   }
-  return { inputCwd: normalizedInputCwd, relativeWorkspaceCwd };
+  return { inputCwd: normalizedInputCwd, relativeWorkspaceCwd, sourceCheckout: sourceWorktreePath };
 }
 
 export async function attemptFirstAgentBranchAutoName(options: {
@@ -182,9 +193,9 @@ export async function attemptFirstAgentBranchAutoName(options: {
     return { attempted: false, renamed: false, branchName: null };
   }
 
-  let metadata: ReturnType<typeof readPaseoWorktreeMetadata>;
+  let metadata: Awaited<ReturnType<typeof readPaseoWorktreeMetadata>>;
   try {
-    metadata = readPaseoWorktreeMetadata(options.cwd);
+    metadata = await readPaseoWorktreeMetadata(options.cwd);
   } catch {
     return { attempted: false, renamed: false, branchName: null };
   }
@@ -199,11 +210,11 @@ export async function attemptFirstAgentBranchAutoName(options: {
   const getCurrentBranchImpl = options.getCurrentBranch ?? getCurrentBranch;
   const placeholderBranchName = metadata.firstAgentBranchAutoName.placeholderBranchName;
   if ((await getCurrentBranchImpl(options.cwd)) !== placeholderBranchName) {
-    markPaseoWorktreeFirstAgentBranchAutoNameAttempted(options.cwd);
+    await markPaseoWorktreeFirstAgentBranchAutoNameAttempted(options.cwd);
     return { attempted: true, renamed: false, branchName: null };
   }
 
-  markPaseoWorktreeFirstAgentBranchAutoNameAttempted(options.cwd);
+  await markPaseoWorktreeFirstAgentBranchAutoNameAttempted(options.cwd);
 
   const branchName = await options.generateBranchNameFromContext({
     cwd: options.cwd,
@@ -264,15 +275,15 @@ async function findAvailableBranchName(options: {
   return null;
 }
 
-function maybeMarkFirstAgentBranchAutoNameEligible(options: {
+async function maybeMarkFirstAgentBranchAutoNameEligible(options: {
   createdWorktree: Awaited<ReturnType<typeof createWorktreeCore>>;
-}): void {
+}): Promise<void> {
   const { createdWorktree } = options;
   if (!createdWorktree.created || createdWorktree.intent.kind !== "branch-off") {
     return;
   }
 
-  writePaseoWorktreeFirstAgentBranchAutoNameMetadata(createdWorktree.worktree.worktreePath, {
+  await writePaseoWorktreeFirstAgentBranchAutoNameMetadata(createdWorktree.worktree.worktreePath, {
     placeholderBranchName: createdWorktree.worktree.branchName,
   });
 }
diff --git a/packages/server/src/server/persisted-config.test.ts b/packages/server/src/server/persisted-config.test.ts
index 019bcbb0f8..fb38e41591 100644
--- a/packages/server/src/server/persisted-config.test.ts
+++ b/packages/server/src/server/persisted-config.test.ts
@@ -16,9 +16,11 @@ import { describe, expect, test } from "vitest";
 
 import {
   loadPersistedConfig,
+  loadPersistedConfigAsync,
   PersistedConfigSchema,
   readPersistedConfig,
   savePersistedConfig,
+  savePersistedConfigAsync,
 } from "./persisted-config.js";
 import { PRIVATE_DIRECTORY_MODE, PRIVATE_FILE_MODE } from "./private-files.js";
 
@@ -827,11 +829,14 @@ describe("readPersistedConfig with an unreadable config.json", () => {
   });
 });
 
-describe.skipIf(process.platform === "win32")("persisted config file permissions", () => {
-  test("initializes config.json with private permissions", () => {
+describe.skipIf(process.platform === "win32").each([
+  { name: "startup", load: loadPersistedConfig, save: savePersistedConfig },
+  { name: "runtime", load: loadPersistedConfigAsync, save: savePersistedConfigAsync },
+])("persisted config file permissions ($name)", ({ load, save }) => {
+  test("initializes config.json with private permissions", async () => {
     const home = createTempHome();
     try {
-      loadPersistedConfig(home);
+      await load(home);
 
       expect(modeOf(path.join(home, "config.json"))).toBe(PRIVATE_FILE_MODE);
     } finally {
@@ -839,14 +844,14 @@ describe.skipIf(process.platform === "win32")("persisted config file permissions
     }
   });
 
-  test("repairs permissive config.json permissions when loading", () => {
+  test("repairs permissive config.json permissions when loading", async () => {
     const home = createTempHome();
     const configPath = path.join(home, "config.json");
     try {
       writeFileSync(configPath, "{}\n", { mode: PERMISSIVE_FILE_MODE });
       chmodSync(configPath, PERMISSIVE_FILE_MODE);
 
-      loadPersistedConfig(home);
+      await load(home);
 
       expect(modeOf(configPath)).toBe(PRIVATE_FILE_MODE);
     } finally {
@@ -854,11 +859,24 @@ describe.skipIf(process.platform === "win32")("persisted config file permissions
     }
   });
 
-  test("saves config.json with private permissions", () => {
+  test("repairs unreadable owner permissions before reading config.json", async () => {
+    const home = createTempHome();
+    const configPath = path.join(home, "config.json");
+    try {
+      writeFileSync(configPath, "{}\n");
+      chmodSync(configPath, 0);
+      expect(await load(home)).toEqual({});
+      expect(modeOf(configPath)).toBe(PRIVATE_FILE_MODE);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test("saves config.json with private permissions", async () => {
     const parent = createTempHome();
     const home = path.join(parent, "home");
     try {
-      savePersistedConfig(home, {
+      await save(home, {
         features: { dictation: { stt: { provider: "openai", apiKey: "secret" } } },
       });
 
@@ -870,37 +888,37 @@ describe.skipIf(process.platform === "win32")("persisted config file permissions
   });
 });
 
-describe.skipIf(process.platform === "win32")(
-  "config.json symlinked from another directory",
-  () => {
-    test("saving writes through the symlink and leaves it in place", () => {
-      const parent = createTempHome();
-      const home = path.join(parent, "home");
-      const dotfiles = path.join(parent, "dotfiles");
-      const linkedConfigPath = path.join(dotfiles, "config.json");
-      const configPath = path.join(home, "config.json");
-      try {
-        mkdirSync(home);
-        mkdirSync(dotfiles, { mode: 0o755 });
-        chmodSync(dotfiles, 0o755);
-        writeFileSync(linkedConfigPath, '{ "version": 1 }\n');
-        symlinkSync(linkedConfigPath, configPath);
+describe.skipIf(process.platform === "win32").each([
+  { name: "startup", save: savePersistedConfig },
+  { name: "runtime", save: savePersistedConfigAsync },
+])("config.json symlinked from another directory ($name)", ({ save }) => {
+  test("saving writes through the symlink and leaves it in place", async () => {
+    const parent = createTempHome();
+    const home = path.join(parent, "home");
+    const dotfiles = path.join(parent, "dotfiles");
+    const linkedConfigPath = path.join(dotfiles, "config.json");
+    const configPath = path.join(home, "config.json");
+    try {
+      mkdirSync(home);
+      mkdirSync(dotfiles, { mode: 0o755 });
+      chmodSync(dotfiles, 0o755);
+      writeFileSync(linkedConfigPath, '{ "version": 1 }\n');
+      symlinkSync(linkedConfigPath, configPath);
 
-        savePersistedConfig(home, { version: 1, daemon: { relay: { enabled: false } } });
+      await save(home, { version: 1, daemon: { relay: { enabled: false } } });
 
-        expect(lstatSync(configPath).isSymbolicLink()).toBe(true);
-        expect(JSON.parse(readFileSync(linkedConfigPath, "utf8"))).toEqual({
-          version: 1,
-          daemon: { relay: { enabled: false } },
-        });
-        expect(modeOf(dotfiles)).toBe(0o755);
-        expect(modeOf(linkedConfigPath)).toBe(PRIVATE_FILE_MODE);
-      } finally {
-        rmSync(parent, { recursive: true, force: true });
-      }
-    });
-  },
-);
+      expect(lstatSync(configPath).isSymbolicLink()).toBe(true);
+      expect(JSON.parse(readFileSync(linkedConfigPath, "utf8"))).toEqual({
+        version: 1,
+        daemon: { relay: { enabled: false } },
+      });
+      expect(modeOf(dotfiles)).toBe(0o755);
+      expect(modeOf(linkedConfigPath)).toBe(PRIVATE_FILE_MODE);
+    } finally {
+      rmSync(parent, { recursive: true, force: true });
+    }
+  });
+});
 
 describe("speech provider config normalization", () => {
   test.each([undefined, "local"])(
diff --git a/packages/server/src/server/persisted-config.ts b/packages/server/src/server/persisted-config.ts
index c6c3f9c7e1..3138ec9132 100644
--- a/packages/server/src/server/persisted-config.ts
+++ b/packages/server/src/server/persisted-config.ts
@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { PluginRegistriesSchema } from "@getpaseo/protocol/plugin-registry";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
@@ -9,7 +10,12 @@ import {
   ProviderOverridesSchema,
 } from "./agent/provider-launch-config.js";
 import type { AgentProviderRuntimeSettingsMap } from "./agent/provider-launch-config.js";
-import { ensurePrivateFile, writePrivateFileAtomicSync } from "./private-files.js";
+import {
+  ensurePrivateFile,
+  ensurePrivateFileAsync,
+  writePrivateFileAtomic,
+  writePrivateFileAtomicSync,
+} from "./private-files.js";
 import { AgentProfileSchema, AgentSkillSelectionSchema } from "@getpaseo/protocol/agent-profile";
 import { PluginIdSchema, PluginSourceSchema } from "@getpaseo/protocol/plugin-config";
 import { TerminalProfileSchema } from "@getpaseo/protocol/terminal-profile";
@@ -253,6 +259,7 @@ export const PersistedConfigSchema = z
           })
           .passthrough()
           .optional(),
+        usage: z.object({ enabled: z.boolean().optional() }).optional(),
         browserTools: z
           .object({
             enabled: z.boolean().optional(),
@@ -342,6 +349,8 @@ export const PersistedConfigSchema = z
       .object({
         providers: z.preprocess(normalizeAgentProviders, ProviderOverridesSchema).optional(),
         idleRuntimeCleanup: z.boolean().optional(),
+        resumeOnStartup: z.boolean().optional(),
+        resumePrompt: z.string().optional(),
         catalogRefreshTimeoutMs: z.number().int().positive().max(2_147_483_647).optional(),
         metadataGeneration: AgentMetadataGenerationSchema.optional(),
         skills: z.object({ selection: AgentSkillSelectionSchema.optional() }).strict().optional(),
@@ -523,6 +532,40 @@ export function loadPersistedConfig(paseoHome: string, logger?: LoggerLike): Per
   return config;
 }
 
+/** Runtime config IO. Startup and offline CLI consumers retain their synchronous entry points. */
+export async function loadPersistedConfigAsync(
+  paseoHome: string,
+  logger?: LoggerLike,
+): Promise<PersistedConfig> {
+  const log = getLogger(logger);
+  const configPath = getConfigPath(paseoHome);
+  let raw: string;
+  await ensurePrivateFileAsync(configPath);
+  try {
+    raw = await readFile(configPath, "utf-8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw new Error(
+        `[Config] Failed to read ${configPath}: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
+    try {
+      raw = JSON.stringify(DEFAULT_PERSISTED_CONFIG, null, 2) + "\n";
+      await writePrivateFileAtomic(configPath, raw);
+      log?.info(`Initialized config file at ${configPath}`);
+    } catch (initializationError) {
+      throw new Error(
+        `[Config] Failed to initialize ${configPath}: ${initializationError instanceof Error ? initializationError.message : String(initializationError)}`,
+        { cause: initializationError },
+      );
+    }
+  }
+  const config = parseConfigFile(configPath, raw, log);
+  log?.info(`Loaded from ${configPath}`);
+  return config;
+}
+
 /** Observe the file without initializing a home, identity, or default configuration. */
 export function readPersistedConfig(
   paseoHome: string,
@@ -642,16 +685,10 @@ export function savePersistedConfig(
   const log = getLogger(logger);
   const configPath = getConfigPath(paseoHome);
 
-  const result = PersistedConfigSchema.safeParse(config);
-  if (!result.success) {
-    const issues = result.error.issues
-      .map((i) => `  - ${i.path.join(".")}: ${i.message}`)
-      .join("\n");
-    throw new Error(`[Config] Invalid config to save:\n${issues}`);
-  }
+  const data = serializePersistedConfig(config);
 
   try {
-    writePrivateFileAtomicSync(configPath, JSON.stringify(result.data, null, 2) + "\n");
+    writePrivateFileAtomicSync(configPath, data);
     log?.info(`Saved to ${configPath}`);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -660,3 +697,33 @@ export function savePersistedConfig(
     });
   }
 }
+
+function serializePersistedConfig(config: PersistedConfig): string {
+  const result = PersistedConfigSchema.safeParse(config);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `  - ${i.path.join(".")}: ${i.message}`)
+      .join("\n");
+    throw new Error(`[Config] Invalid config to save:\n${issues}`);
+  }
+
+  return JSON.stringify(result.data, null, 2) + "\n";
+}
+
+export async function savePersistedConfigAsync(
+  paseoHome: string,
+  config: PersistedConfig,
+  logger?: LoggerLike,
+): Promise<void> {
+  const configPath = getConfigPath(paseoHome);
+  const data = serializePersistedConfig(config);
+  try {
+    await writePrivateFileAtomic(configPath, data);
+    getLogger(logger)?.info(`Saved to ${configPath}`);
+  } catch (error) {
+    throw new Error(
+      `[Config] Failed to write ${configPath}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+}
diff --git a/packages/server/src/server/persistence-hooks.ts b/packages/server/src/server/persistence-hooks.ts
index e95743d6be..bbcc3c79eb 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 {
@@ -141,6 +141,7 @@ export function extractTimestamps(record: StoredAgentRecord): {
   labels?: Record<string, string>;
   workspaceId?: string;
   owner?: StoredAgentRecord["owner"];
+  background?: boolean;
 } {
   return {
     createdAt: new Date(record.createdAt),
@@ -149,6 +150,7 @@ export function extractTimestamps(record: StoredAgentRecord): {
     labels: record.labels,
     workspaceId: record.workspaceId,
     owner: record.owner,
+    background: record.background,
   };
 }
 
diff --git a/packages/server/src/server/pid-lock.ts b/packages/server/src/server/pid-lock.ts
index 314b44ea47..6f3e7135d9 100644
--- a/packages/server/src/server/pid-lock.ts
+++ b/packages/server/src/server/pid-lock.ts
@@ -30,13 +30,16 @@ function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
   return err instanceof Error && "code" in err;
 }
 
+// The field is assigned explicitly rather than declared as a constructor parameter property:
+// the terminal worker loads this module under --experimental-strip-types, which cannot emit
+// the assignment a parameter property implies.
 export class PidLockError extends Error {
-  constructor(
-    message: string,
-    public readonly existingLock?: PidLockInfo,
-  ) {
+  readonly existingLock?: PidLockInfo;
+
+  constructor(message: string, existingLock?: PidLockInfo) {
     super(message);
     this.name = "PidLockError";
+    this.existingLock = existingLock;
   }
 }
 
@@ -69,7 +72,7 @@ let cachedBootId: string | null | undefined;
 // Linux names each boot. The wall-clock boot instant is not enough there: a VM paused while
 // its host sleeps keeps its uptime, so after it resumes the instant lands after locks its
 // running supervisor wrote.
-function currentBootId(): string | null {
+export function currentBootId(): string | null {
   if (cachedBootId === undefined) {
     try {
       cachedBootId = readFileSync("/proc/sys/kernel/random/boot_id", "utf-8").trim() || null;
@@ -80,10 +83,17 @@ function currentBootId(): string | null {
   return cachedBootId;
 }
 
-function writtenDuringThisBoot(lock: PidLockInfo): boolean {
+/**
+ * Whether a record stamped with `startedAt` (and, on Linux, `bootId`) was written during the
+ * current boot. Daemon locks and terminal worker records share this rule.
+ */
+export function writtenDuringThisBoot(stamp: {
+  startedAt: string;
+  bootId?: string | null;
+}): boolean {
   const thisBoot = currentBootId();
-  if (lock.bootId && thisBoot) return lock.bootId === thisBoot;
-  return !precedesThisBoot(lock.startedAt);
+  if (stamp.bootId && thisBoot) return stamp.bootId === thisBoot;
+  return !precedesThisBoot(stamp.startedAt);
 }
 
 /**
diff --git a/packages/server/src/server/plugins/agent-configuration.e2e.test.ts b/packages/server/src/server/plugins/agent-configuration.e2e.test.ts
index 3228306297..a3e4e273a4 100644
--- a/packages/server/src/server/plugins/agent-configuration.e2e.test.ts
+++ b/packages/server/src/server/plugins/agent-configuration.e2e.test.ts
@@ -1,20 +1,32 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, 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 { DaemonClient } from "../test-utils/daemon-client.js";
+import type { AgentClient, AgentSessionConfig } from "../agent/agent-sdk-types.js";
 import { createTestAgentClient } from "../test-utils/fake-agent-client.js";
 import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
 
-test("the configuration example adds MCP servers and overrides Codex options while preserving other configuration", async () => {
+test("the configuration example saves Codex options and injects launch-only MCP servers while preserving other configuration", async () => {
   const directory = await mkdtemp(path.join(tmpdir(), "paseo-config-example-"));
+  const launches: AgentSessionConfig[] = [];
   const daemon = await createTestPaseoDaemon({
-    daemonVersion: "0.8.0",
-    agentClients: { codex: createTestAgentClient("codex", { supportsMcpServers: true }) },
+    daemonVersion: "0.14.0-beta.1",
+    agentClients: {
+      codex: createTestAgentClient("codex", {
+        supportsMcpServers: true,
+        beforeCreateSession: async (config) => {
+          launches.push(config);
+        },
+      }),
+    },
     mcpEnabled: false,
   });
-  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.8.0" });
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    appVersion: "0.14.0-beta.1",
+  });
   try {
     await client.connect();
     await client.fetchAgents({ subscribe: {} });
@@ -44,9 +56,15 @@ test("the configuration example adds MCP servers and overrides Codex options whi
       },
       mcpServers: {
         existing: { type: "http", url: "https://existing.example.com/mcp" },
-        company: { type: "http", url: "https://tools.example.com/mcp" },
       },
     });
+    expect(daemon.daemon.agentManager.getAgent(agent.id)!.config.mcpServers).toEqual({
+      existing: { type: "http", url: "https://existing.example.com/mcp" },
+    });
+    expect(launches[0].mcpServers).toEqual({
+      existing: { type: "http", url: "https://existing.example.com/mcp" },
+      company: { type: "http", url: "https://tools.example.com/mcp" },
+    });
     await client.archiveAgent(agent.id);
   } finally {
     await client.close();
@@ -54,3 +72,71 @@ test("the configuration example adds MCP servers and overrides Codex options whi
     await rm(directory, { recursive: true, force: true });
   }
 }, 60_000);
+
+test("session-open entrypoint contributions are optional and rederived for existing agents", async () => {
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-entrypoint-hook-"));
+  const launches: { provider: string; env?: Record<string, string> }[] = [];
+  function recordingProvider(provider: "claude" | "codex"): AgentClient {
+    const inner = createTestAgentClient(provider);
+    return {
+      provider: inner.provider,
+      capabilities: inner.capabilities,
+      isAvailable: () => inner.isAvailable(),
+      fetchCatalog: (options) => inner.fetchCatalog(options),
+      createSession: async (...args: Parameters<typeof inner.createSession>) => {
+        launches.push({ provider, env: args[1]?.env });
+        return inner.createSession(...args);
+      },
+      resumeSession: async (...args: Parameters<typeof inner.resumeSession>) => {
+        launches.push({ provider, env: args[2]?.env });
+        return inner.resumeSession(...args);
+      },
+    };
+  }
+  const daemon = await createTestPaseoDaemon({
+    daemonVersion: "0.14.0-beta.2",
+    agentClients: { claude: recordingProvider("claude"), codex: recordingProvider("codex") },
+    mcpEnabled: false,
+  });
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    appVersion: "0.14.0-beta.2",
+  });
+  try {
+    await writeFile(
+      path.join(directory, "paseo-plugin.json"),
+      JSON.stringify({ id: "entrypoint-test", requirements: { paseo: ">=0.14.0-beta.2" } }),
+    );
+    await writeFile(
+      path.join(directory, "index.server.ts"),
+      `
+export default function contribute(server) {
+  return server.before("agent.session_open", ({ request }) => {
+    if (request.provider !== "claude") return;
+    return { ...request, env: { ...request.env, CLAUDE_CODE_ENTRYPOINT: "custom-client" } };
+  });
+}
+`,
+    );
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    const existing = await client.createAgent({ provider: "claude", cwd: directory });
+    expect(launches.at(-1)?.env?.CLAUDE_CODE_ENTRYPOINT).toBeUndefined();
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(directory);
+    await daemon.daemon.agentManager.reloadAgentSession(existing.id);
+    expect(launches.at(-1)?.env?.CLAUDE_CODE_ENTRYPOINT).toBe("custom-client");
+    await client.createAgent({ provider: "claude", cwd: directory });
+    expect(launches.at(-1)?.env?.CLAUDE_CODE_ENTRYPOINT).toBe("custom-client");
+    await client.createAgent({ provider: "codex", cwd: directory });
+    expect(launches.at(-1)).toMatchObject({ provider: "codex" });
+    expect(launches.at(-1)?.env?.CLAUDE_CODE_ENTRYPOINT).toBeUndefined();
+    await client.disablePlugin("entrypoint-test");
+    await daemon.daemon.agentManager.reloadAgentSession(existing.id);
+    expect(launches.at(-1)?.env?.CLAUDE_CODE_ENTRYPOINT).toBeUndefined();
+  } finally {
+    await client.close();
+    await daemon.close();
+    await rm(directory, { recursive: true, force: true });
+  }
+}, 60_000);
diff --git a/packages/server/src/server/plugins/agent-tools.e2e.test.ts b/packages/server/src/server/plugins/agent-tools.e2e.test.ts
new file mode 100644
index 0000000000..b652c569fe
--- /dev/null
+++ b/packages/server/src/server/plugins/agent-tools.e2e.test.ts
@@ -0,0 +1,1042 @@
+import { fileURLToPath } from "node:url";
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "vitest";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { DaemonClient } from "../test-utils/daemon-client.js";
+import {
+  createTestAgentClient,
+  type TestAgentClientOptions,
+} from "../test-utils/fake-agent-client.js";
+import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
+import { importSessionFromPersistence } from "../agent/provider-session-import.js";
+import { BuiltinPluginLoader } from "./builtin/index.js";
+import { serializePaseoToolInputParameters } from "../agent/tools/paseo-tool-serialization.js";
+import type {
+  AgentClient,
+  AgentLaunchContext,
+  AgentSessionConfig,
+  AgentPromptInput,
+} from "../agent/agent-sdk-types.js";
+
+function recordingProvider(native: boolean, callbacks: TestAgentClientOptions = {}) {
+  const launches: { config: AgentSessionConfig; context?: AgentLaunchContext }[] = [];
+  const turns: { prompt: AgentPromptInput; launchCount: number }[] = [];
+  const steers: AgentPromptInput[] = [];
+  const events = { interrupts: 0 };
+  const inner = createTestAgentClient("codex", {
+    ...callbacks,
+    supportsMcpServers: callbacks.supportsMcpServers ?? true,
+    onStartTurn: (prompt, config) => {
+      turns.push({ prompt, launchCount: launches.length });
+      callbacks.onStartTurn?.(prompt, config);
+    },
+    steerActiveTurn: async (prompt) => {
+      steers.push(prompt);
+      return { status: "accepted" };
+    },
+    onInterrupt: () => {
+      events.interrupts++;
+      callbacks.onInterrupt?.();
+    },
+  });
+  const provider: AgentClient = {
+    provider: inner.provider,
+    capabilities: { ...inner.capabilities, supportsNativePaseoTools: native },
+    createSession: async (config, context, options) => {
+      launches.push({ config, context });
+      return inner.createSession(config, context, options);
+    },
+    resumeSession: async (handle, config, context, options) => {
+      launches.push({ config: config as AgentSessionConfig, context });
+      return inner.resumeSession(handle, config, context, options);
+    },
+    importSession: (input, context) =>
+      importSessionFromPersistence({
+        provider: "codex",
+        request: input,
+        context,
+        resumeSession: provider.resumeSession.bind(provider),
+      }),
+    isAvailable: () => inner.isAvailable(),
+    fetchCatalog: (options) => inner.fetchCatalog(options),
+  };
+  return { provider, launches, turns, steers, events };
+}
+
+const pluginSource = `
+import { z } from "zod";
+import { defineAgentTool } from "@getpaseo/plugin/server";
+let calls = 0;
+const tool = defineAgentTool({
+  name: "plugin_echo", description: "Echo for the chosen agent",
+  input: z.object({ text: z.string().min(1).refine(value => value !== "forbidden", "Forbidden by plugin").describe("Message") }),
+  async execute(input, { agent, paseo, signal }) {
+    calls++;
+    if (input.text === "throw") throw new Error("handler failed");
+    return { text: JSON.stringify({ agent, input, calls, sdk: typeof paseo.agents.ref, aborted: signal.aborted }) };
+  },
+});
+export default function contribute(server) {
+  server.addHook("agent.open.before", async ({ request }) => {
+    if (request.labels.x !== "y") return;
+    return { ...request, env: { ...request.env, OPEN_INFO: JSON.stringify({ title: request.title, labels: request.labels, reason: request.reason }) }, tools: [...request.tools, tool] };
+  });
+  return () => {};
+}
+`;
+
+async function setup(
+  native = false,
+  source = pluginSource,
+  policy?: { enabled?: boolean; disabledTools?: string[] },
+  providerOptions?: TestAgentClientOptions,
+) {
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-agent-tools-"));
+  const recorder = recordingProvider(native, providerOptions);
+  const daemon = await createTestPaseoDaemon({
+    daemonVersion: "0.14.0-beta.1",
+    agentClients: { codex: recorder.provider },
+    mcpEnabled: true,
+    providerOverrides: { codex: { paseoTools: policy } },
+  });
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    appVersion: "0.14.0-beta.1",
+  });
+  const mcps: Client[] = [];
+  async function install(id: string, code: string) {
+    const pluginDirectory = path.join(directory, id);
+    await mkdir(pluginDirectory);
+    await writeFile(
+      path.join(pluginDirectory, "paseo-plugin.json"),
+      JSON.stringify({ id, requirements: { paseo: ">=0.14.0-beta.1" } }),
+    );
+    await writeFile(path.join(pluginDirectory, "index.server.ts"), code);
+    await client.installDirectoryPlugin(pluginDirectory);
+  }
+  await client.connect();
+  await client.fetchAgents({ subscribe: {} });
+  await client.patchDaemonConfig({ pluginsEnabled: true });
+  try {
+    await install("tools-test", source);
+  } catch (error) {
+    await client.close();
+    await daemon.close();
+    await rm(directory, { recursive: true, force: true });
+    throw error;
+  }
+  return {
+    ...recorder,
+    daemon,
+    client,
+    directory,
+    install,
+    async create(labels: Record<string, string> = {}) {
+      return daemon.daemon.agentManager.createAgent(
+        { provider: "codex", cwd: directory },
+        undefined,
+        { labels, initialTitle: "Chosen title" },
+      );
+    },
+    async mcp(agentId?: string) {
+      const server = recorder.launches.at(-1)!.config.mcpServers?.paseo;
+      let url: string;
+      if (agentId) url = `http://127.0.0.1:${daemon.port}/mcp/agents?callerAgentId=${agentId}`;
+      else {
+        if (server?.type !== "http") throw new Error("Expected HTTP server");
+        url = server.url;
+      }
+      const mcp = new Client({ name: "plugin-tools-test", version: "1" });
+      mcps.push(mcp);
+      await mcp.connect(new StreamableHTTPClientTransport(new URL(url)));
+      return mcp;
+    },
+    async close() {
+      await Promise.all(mcps.map((mcp) => mcp.close()));
+      await client.close();
+      await daemon.close();
+      await rm(directory, { recursive: true, force: true });
+    },
+  };
+}
+
+test("session hooks attach tools only to matching agents over MCP, with validated input and caller context", async () => {
+  const h = await setup();
+  try {
+    const a = await h.create({ x: "y" });
+    expect(JSON.parse(h.launches.at(-1)!.context!.env!.OPEN_INFO)).toEqual({
+      title: "Chosen title",
+      labels: { x: "y" },
+      reason: "create",
+    });
+    const mcpA = await h.mcp();
+    const listed = (await mcpA.listTools()).tools.find((tool) => tool.name === "plugin_echo");
+    expect(listed).toMatchObject({
+      name: "plugin_echo",
+      inputSchema: {
+        type: "object",
+        properties: { text: { type: "string", minLength: 1, description: "Message" } },
+        required: ["text"],
+      },
+    });
+    const b = await h.create();
+    const mcpB = await h.mcp();
+    expect((await mcpB.listTools()).tools.map((tool) => tool.name)).not.toContain("plugin_echo");
+    const invalid = await mcpA.callTool({ name: "plugin_echo", arguments: { text: "" } });
+    expect(invalid.isError).toBe(true);
+    expect(JSON.stringify(invalid)).toContain("text");
+    expect(
+      await mcpA.callTool({ name: "plugin_echo", arguments: { text: "forbidden" } }),
+    ).toMatchObject({
+      isError: true,
+      content: [{ type: "text", text: expect.stringContaining("Forbidden by plugin") }],
+    });
+    const result = await mcpA.callTool({ name: "plugin_echo", arguments: { text: "hello" } });
+    expect(result.isError).not.toBe(true);
+    expect(JSON.parse((result.content as { text: string }[])[0].text)).toMatchObject({
+      agent: { id: a.id, cwd: h.directory, title: "Chosen title" },
+      input: { text: "hello" },
+      calls: 1,
+      sdk: "function",
+      aborted: false,
+    });
+    expect(a.id).not.toBe(b.id);
+    expect(
+      await mcpA.callTool({ name: "plugin_echo", arguments: { text: "throw" } }),
+    ).toMatchObject({ isError: true, content: [{ type: "text", text: "handler failed" }] });
+    expect(
+      (await mcpA.callTool({ name: "plugin_echo", arguments: { text: "still alive" } })).isError,
+    ).not.toBe(true);
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("native providers get the same attached schema and execution", async () => {
+  const h = await setup(true);
+  try {
+    const a = await h.create({ x: "y" });
+    const catalog = h.launches.at(-1)!.context!.paseoTools!;
+    expect(catalog.getTool("plugin_echo")?.description).toBe("Echo for the chosen agent");
+    const mcp = await h.mcp(a.id);
+    const advertised = (await mcp.listTools()).tools.find((tool) => tool.name === "plugin_echo")!;
+    expect(serializePaseoToolInputParameters(catalog.getTool("plugin_echo")!)).toEqual(
+      advertised.inputSchema,
+    );
+    const result = await catalog.executeTool("plugin_echo", { text: "native" });
+    expect(JSON.parse(result.content[0].text!)).toMatchObject({
+      agent: { id: a.id },
+      input: { text: "native" },
+    });
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("resume uses the stored title and labels, and close removes the attachment", async () => {
+  const h = await setup(true);
+  try {
+    const a = await h.create({ x: "y" });
+    const catalog = h.launches.at(-1)!.context!.paseoTools!;
+    const handle = a.persistence!;
+    await h.daemon.daemon.agentManager.setTitle(a.id, "Stored title");
+    await h.daemon.daemon.agentManager.closeAgent(a.id);
+    expect(h.daemon.daemon.agentManager.getPluginTools(a.id)).toEqual([]);
+    await expect(catalog.executeTool("plugin_echo", { text: "closed" })).rejects.toThrow(
+      "Agent is not live",
+    );
+    await h.daemon.daemon.agentManager.resumeAgentFromPersistence(handle, a.config, a.id);
+    expect(JSON.parse(h.launches.at(-1)!.context!.env!.OPEN_INFO)).toEqual({
+      title: "Stored title",
+      labels: { x: "y" },
+      reason: "resume",
+    });
+    expect(h.launches.at(-1)!.context!.paseoTools!.getTool("plugin_echo")?.name).toBe(
+      "plugin_echo",
+    );
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test.each([
+  {
+    name: "Paseo",
+    source: pluginSource.replace('name: "plugin_echo"', 'name: "list_agents"'),
+    other: false,
+    message: /plugin tools-test.*Paseo tool list_agents/,
+  },
+  {
+    name: "another plugin",
+    source: pluginSource,
+    other: true,
+    message: /plugin tools-test.*plugin other-tools/,
+  },
+  {
+    name: "the same plugin",
+    source: pluginSource.replace("tools: [...request.tools, tool]", "tools: [tool, tool]"),
+    other: false,
+    message: /Duplicate agent tool: plugin_echo/,
+  },
+])(
+  "collisions with $name fail only targeted session opens",
+  async ({ source, other, message }) => {
+    const h = await setup(false, source);
+    try {
+      if (other) await h.install("other-tools", pluginSource);
+      await expect(h.create({ x: "y" })).rejects.toThrow(message);
+      expect(h.launches).toHaveLength(0);
+      await h.create();
+      expect(h.launches).toHaveLength(1);
+      expect((await (await h.mcp()).listTools()).tools.map((tool) => tool.name)).not.toContain(
+        "plugin_echo",
+      );
+    } finally {
+      await h.close();
+    }
+  },
+  60_000,
+);
+
+test("each plugin owns its tool array and callbacks can remove earlier attachments", async () => {
+  const source = pluginSource.replace(
+    "  return () => {};",
+    `
+  server.addHook("agent.open.before", async ({ request }) => {
+    if (request.labels.x === "y" && request.tools[0]?.name !== "plugin_echo") throw new Error("Lost plugin-local definitions");
+    return { ...request, tools: [] };
+  });
+  return () => {};`,
+  );
+  const h = await setup(false, source);
+  try {
+    await h.install(
+      "other-tools",
+      pluginSource
+        .replace('name: "plugin_echo"', 'name: "other_echo"')
+        .replace(
+          '    if (request.labels.x !== "y") return;',
+          '    if (request.tools.length !== 0) throw new Error("Saw another plugin tools");\n    if (request.labels.x !== "y") return;',
+        ),
+    );
+    await h.create({ x: "y" });
+    const names = (await (await h.mcp()).listTools()).tools.map((tool) => tool.name);
+    expect(names).toContain("other_echo");
+    expect(names).not.toContain("plugin_echo");
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("disabled plugins remove tools from existing and new MCP catalogs", async () => {
+  const h = await setup();
+  try {
+    await h.create({ x: "y" });
+    const mcp = await h.mcp();
+    expect((await mcp.listTools()).tools.map((tool) => tool.name)).toContain("plugin_echo");
+    await h.client.patchDaemonConfig({ pluginsEnabled: false });
+    expect((await mcp.listTools()).tools.map((tool) => tool.name)).not.toContain("plugin_echo");
+    await h.create({ x: "y" });
+    expect((await (await h.mcp()).listTools()).tools.map((tool) => tool.name)).not.toContain(
+      "plugin_echo",
+    );
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test.each([false, true])(
+  "provider tools disabled gates plugin tools (native=%s)",
+  async (native) => {
+    const h = await setup(native, pluginSource, { enabled: false });
+    try {
+      await h.create({ x: "y" });
+      expect(h.launches.at(-1)!.context!.paseoTools).toBeUndefined();
+      expect(h.launches.at(-1)!.config.mcpServers?.paseo).toBeUndefined();
+    } finally {
+      await h.close();
+    }
+  },
+  60_000,
+);
+
+test("disabledTools filters plugin tool names", async () => {
+  const h = await setup(true, pluginSource, { disabledTools: ["plugin_echo"] });
+  try {
+    await h.create({ x: "y" });
+    expect(h.launches.at(-1)!.context!.paseoTools!.getTool("plugin_echo")).toBeUndefined();
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+const waitingSource = pluginSource
+  .replace("import { z }", 'import { writeFile } from "node:fs/promises";\nimport { z }')
+  .replace(
+    "    calls++;",
+    `
+    calls++;
+    if (input.text === "wait") {
+      await writeFile(agent.cwd + "/started", agent.id);
+      await new Promise(resolve => signal.addEventListener("abort", resolve, { once: true }));
+      await writeFile(agent.cwd + "/aborted", agent.id);
+      return { text: "discard this result" };
+    }
+`,
+  );
+
+test("caller cancellation aborts the plugin handler and discards its result", async () => {
+  const h = await setup(true, waitingSource);
+  try {
+    const a = await h.create({ x: "y" });
+    const catalog = h.launches.at(-1)!.context!.paseoTools!;
+    const controller = new AbortController();
+    const call = catalog.executeTool(
+      "plugin_echo",
+      { text: "wait" },
+      { signal: controller.signal },
+    );
+    const rejected = expect(call).rejects.toThrow("Canceled by caller");
+    await expect.poll(() => readFile(path.join(h.directory, "started"), "utf8")).toBe(a.id);
+    controller.abort(new Error("Canceled by caller"));
+    await rejected;
+    await expect.poll(() => readFile(path.join(h.directory, "aborted"), "utf8")).toBe(a.id);
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("a plugin stopping mid-call returns a tool error", async () => {
+  const h = await setup(true, waitingSource);
+  try {
+    const a = await h.create({ x: "y" });
+    const call = h.launches
+      .at(-1)!
+      .context!.paseoTools!.executeTool("plugin_echo", { text: "wait" });
+    await expect.poll(() => readFile(path.join(h.directory, "started"), "utf8")).toBe(a.id);
+    await h.client.patchDaemonConfig({ pluginsEnabled: false });
+    expect(await call).toMatchObject({
+      isError: true,
+      content: [{ type: "text", text: expect.stringContaining("Plugin stopped") }],
+    });
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("history sessions ignore attached tools", async () => {
+  const h = await setup(true);
+  try {
+    const a = await h.create({ x: "y" });
+    const handle = a.persistence!;
+    await h.client.archiveAgent(a.id);
+    await h.daemon.daemon.agentManager.resumeAgentFromPersistence(handle, a.config, a.id);
+    expect(h.daemon.daemon.agentManager.getPluginTools(a.id)).toEqual([]);
+    expect(h.launches.at(-1)!.context!.paseoTools?.getTool("plugin_echo")).toBeUndefined();
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("disabled plugins attach no tools to a new native session", async () => {
+  const h = await setup(true);
+  try {
+    await h.client.patchDaemonConfig({ pluginsEnabled: false });
+    await h.create({ x: "y" });
+    expect(h.launches.at(-1)!.context!.paseoTools!.getTool("plugin_echo")).toBeUndefined();
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("structured tool results get model-visible text when text is omitted", async () => {
+  const h = await setup(
+    true,
+    pluginSource.replace(
+      "    calls++;",
+      '    return { structuredContent: { status: "created" } };',
+    ),
+  );
+  try {
+    await h.create({ x: "y" });
+    expect(
+      await h.launches
+        .at(-1)!
+        .context!.paseoTools!.executeTool("plugin_echo", { text: "structured" }),
+    ).toEqual({
+      content: [{ type: "text", text: JSON.stringify({ status: "created" }, null, 2) }],
+      structuredContent: { status: "created" },
+      isError: undefined,
+    });
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("reloading a plugin retires its old attachments before an agent reopens", async () => {
+  const h = await setup(true);
+  try {
+    const a = await h.create({ x: "y" });
+    const mcp = await h.mcp(a.id);
+    const oldCatalog = h.launches.at(-1)!.context!.paseoTools!;
+    expect((await mcp.listTools()).tools.map((tool) => tool.name)).toContain("plugin_echo");
+    await h.client.reloadPlugin("tools-test");
+    expect((await mcp.listTools()).tools.map((tool) => tool.name)).not.toContain("plugin_echo");
+    expect(h.daemon.daemon.agentManager.getPluginTools(a.id)).toEqual([]);
+    expect(await oldCatalog.executeTool("plugin_echo", { text: "retired" })).toMatchObject({
+      isError: true,
+      content: [{ type: "text", text: expect.stringContaining("not available") }],
+    });
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("built-in plugins attach and execute tools while configured plugins are disabled", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-builtin-tools-"));
+  const directory = path.join(root, "builtin-tools");
+  await mkdir(directory);
+  await writeFile(
+    path.join(directory, "paseo-plugin.json"),
+    JSON.stringify({ id: "builtin-tools", requirements: { paseo: ">=0.14.0-beta.1" } }),
+  );
+  await writeFile(path.join(directory, "index.server.ts"), pluginSource);
+  const recorder = recordingProvider(true);
+  const daemon = await createTestPaseoDaemon({
+    daemonVersion: "0.14.0-beta.1",
+    agentClients: { codex: recorder.provider },
+    pluginsEnabled: false,
+    builtinPlugins: new BuiltinPluginLoader(root, ["builtin-tools"]),
+  });
+  try {
+    const a = await daemon.daemon.agentManager.createAgent(
+      { provider: "codex", cwd: root },
+      undefined,
+      { labels: { x: "y" } },
+    );
+    const catalog = recorder.launches.at(-1)!.context!.paseoTools!;
+    expect(catalog.getTool("plugin_echo")?.name).toBe("plugin_echo");
+    const result = await catalog.executeTool("plugin_echo", { text: "builtin" });
+    expect(result.isError).not.toBe(true);
+    expect(JSON.parse(result.content[0].text!)).toMatchObject({
+      agent: { id: a.id },
+      input: { text: "builtin" },
+    });
+  } finally {
+    await daemon.close();
+    await rm(root, { recursive: true, force: true });
+  }
+}, 60_000);
+
+test("a session hook missing tools reports a schema issue", async () => {
+  const h = await setup(
+    false,
+    pluginSource.replace("tools: [...request.tools, tool]", "tools: undefined"),
+  );
+  try {
+    await expect(h.create({ x: "y" })).rejects.toThrow('"tools"');
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+async function sendAndFinish(h: Awaited<ReturnType<typeof setup>>, agentId: string, text: string) {
+  const previous = h.turns.length;
+  await h.client.sendMessage(agentId, text, { activeTurnBehavior: "steer" });
+  await expect.poll(() => h.turns.length).toBe(previous + 1);
+  await expect.poll(() => h.daemon.daemon.agentManager.hasInFlightRun(agentId)).toBe(false);
+}
+
+test("an idle agent reopens once before its next prompt after a session-hook plugin reload", async () => {
+  const h = await setup();
+  try {
+    const b = await h.create();
+    const mcp = await h.mcp();
+    expect((await mcp.listTools()).tools.map((tool) => tool.name)).not.toContain("plugin_echo");
+    await writeFile(
+      path.join(h.directory, "tools-test", "index.server.ts"),
+      pluginSource.replace('    if (request.labels.x !== "y") return;', ""),
+    );
+    await h.client.reloadPlugin("tools-test");
+    expect(h.launches).toHaveLength(1);
+    await sendAndFinish(h, b.id, "first prompt");
+    expect(h.launches).toHaveLength(2);
+    expect(h.turns.map((turn) => turn.launchCount)).toEqual([2]);
+    expect((await mcp.listTools()).tools.map((tool) => tool.name)).toContain("plugin_echo");
+    await sendAndFinish(h, b.id, "second prompt");
+    expect(h.launches).toHaveLength(2);
+    expect(h.turns.map((turn) => turn.launchCount)).toEqual([2, 2]);
+    expect(h.events.interrupts).toBe(0);
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("a busy agent is steered after plugin reload and reopens only at its next idle prompt", async () => {
+  let release!: () => void;
+  const blocked = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const h = await setup(true, pluginSource, undefined, { beforeTurnComplete: async () => blocked });
+  try {
+    const a = await h.create({ x: "y" });
+    await h.client.sendMessage(a.id, "busy prompt", { activeTurnBehavior: "steer" });
+    await expect.poll(() => h.daemon.daemon.agentManager.hasInFlightRun(a.id)).toBe(true);
+    await expect
+      .poll(() => h.daemon.daemon.agentManager.getAgent(a.id)!.activeTurnId)
+      .not.toBeNull();
+    const turnId = h.daemon.daemon.agentManager.getAgent(a.id)!.activeTurnId;
+    await h.client.reloadPlugin("tools-test");
+    await h.client.sendMessage(a.id, "steering prompt", { activeTurnBehavior: "steer" });
+    expect(h.steers).toHaveLength(1);
+    expect(h.launches).toHaveLength(1);
+    expect(h.events.interrupts).toBe(0);
+    expect(h.daemon.daemon.agentManager.getAgent(a.id)!.activeTurnId).toBe(turnId);
+    release();
+    await expect.poll(() => h.daemon.daemon.agentManager.hasInFlightRun(a.id)).toBe(false);
+    await sendAndFinish(h, a.id, "idle prompt");
+    expect(h.launches).toHaveLength(2);
+    expect(h.events.interrupts).toBe(0);
+    expect(h.launches.at(-1)!.context!.paseoTools!.getTool("plugin_echo")?.name).toBe(
+      "plugin_echo",
+    );
+    await sendAndFinish(h, a.id, "stable prompt");
+    expect(h.launches).toHaveLength(2);
+  } finally {
+    release();
+    await h.close();
+  }
+}, 60_000);
+
+const reloadRpcSource = pluginSource
+  .replace("import { z }", 'import { defineRpc } from "@getpaseo/plugin";\nimport { z }')
+  .replace(
+    "  return () => {};",
+    `
+  server.handle(defineRpc({ name: "reload_agent", input: z.object({ id: z.string() }), output: z.object({ id: z.string() }) }), async ({ id }, { paseo }) => {
+    const agent = paseo.agents.ref(id);
+    await agent.refresh();
+    await agent.reload();
+    return { id: agent.current().id };
+  });
+  return () => {};
+`,
+  );
+
+test("a plugin can reload an agent through the SDK and rerun session hooks with reason refresh", async () => {
+  const h = await setup(true, reloadRpcSource);
+  try {
+    const a = await h.create({ x: "y" });
+    expect(h.launches).toHaveLength(1);
+    expect(await h.client.invokePluginRpc("tools-test", "reload_agent", { id: a.id })).toEqual({
+      id: a.id,
+    });
+    expect(h.launches).toHaveLength(2);
+    expect(JSON.parse(h.launches.at(-1)!.context!.env!.OPEN_INFO).reason).toBe("refresh");
+    expect(h.launches.at(-1)!.context!.paseoTools!.getTool("plugin_echo")?.name).toBe(
+      "plugin_echo",
+    );
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("starting and stopping a session-hook plugin each causes one idle reopen", async () => {
+  const h = await setup(true);
+  try {
+    const a = await h.create({ x: "y" });
+    await h.install(
+      "added-tools",
+      pluginSource.replace('name: "plugin_echo"', 'name: "added_echo"'),
+    );
+    await sendAndFinish(h, a.id, "after start");
+    expect(h.launches).toHaveLength(2);
+    expect(h.launches.at(-1)!.context!.paseoTools!.getTool("added_echo")?.name).toBe("added_echo");
+    await h.client.disablePlugin("added-tools");
+    await sendAndFinish(h, a.id, "after stop");
+    expect(h.launches).toHaveLength(3);
+    expect(h.launches.at(-1)!.context!.paseoTools!.getTool("added_echo")).toBeUndefined();
+    await sendAndFinish(h, a.id, "stable after stop");
+    expect(h.launches).toHaveLength(3);
+    expect(h.events.interrupts).toBe(0);
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("plugins without a session-open hook do not make agent sessions stale", async () => {
+  const h = await setup(true);
+  try {
+    const a = await h.create({ x: "y" });
+    await h.install(
+      "no-session-hook",
+      "export default function contribute(server) { server.on('agent.created', () => {}); return () => {}; }",
+    );
+    await sendAndFinish(h, a.id, "after unrelated start");
+    expect(h.launches).toHaveLength(1);
+    await h.client.reloadPlugin("no-session-hook");
+    await sendAndFinish(h, a.id, "after unrelated reload");
+    expect(h.launches).toHaveLength(1);
+    await h.client.disablePlugin("no-session-hook");
+    await sendAndFinish(h, a.id, "after unrelated stop");
+    expect(h.launches).toHaveLength(1);
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("explicit SDK reload interrupts a running turn before reopening its session", async () => {
+  let release!: () => void;
+  const blocked = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const h = await setup(true, reloadRpcSource, undefined, {
+    beforeTurnComplete: async () => blocked,
+    onInterrupt: () => release(),
+  });
+  try {
+    const a = await h.create({ x: "y" });
+    await h.client.sendMessage(a.id, "running before explicit reload", {
+      activeTurnBehavior: "steer",
+    });
+    await expect
+      .poll(() => h.daemon.daemon.agentManager.getAgent(a.id)!.activeTurnId)
+      .not.toBeNull();
+    expect(await h.client.invokePluginRpc("tools-test", "reload_agent", { id: a.id })).toEqual({
+      id: a.id,
+    });
+    expect(h.events.interrupts).toBe(1);
+    expect(h.launches).toHaveLength(2);
+    expect(JSON.parse(h.launches.at(-1)!.context!.env!.OPEN_INFO).reason).toBe("refresh");
+  } finally {
+    release();
+    await h.close();
+  }
+}, 60_000);
+
+test("the agent-tools example appends notes only for labeled agents", async () => {
+  const h = await setup();
+  try {
+    await h.client.installDirectoryPlugin(
+      fileURLToPath(new URL("../../../../../plugin-examples/agent-tools", import.meta.url)),
+    );
+    const a = await h.create({ "notes/enabled": "true" });
+    const mcpA = await h.mcp(a.id);
+    expect((await mcpA.listTools()).tools.map((tool) => tool.name)).toContain(
+      "append_workspace_note",
+    );
+    expect(
+      await mcpA.callTool({
+        name: "append_workspace_note",
+        arguments: { note: "Run the targeted tests before committing." },
+      }),
+    ).toMatchObject({
+      content: [
+        { type: "text", text: `Saved note to ${path.join(h.directory, "AGENT_NOTES.md")}` },
+      ],
+      structuredContent: { path: path.join(h.directory, "AGENT_NOTES.md") },
+    });
+    expect(await readFile(path.join(h.directory, "AGENT_NOTES.md"), "utf8")).toBe(
+      "Run the targeted tests before committing.\n",
+    );
+    await mcpA.callTool({
+      name: "append_workspace_note",
+      arguments: { note: "Keep existing notes." },
+    });
+    expect(await readFile(path.join(h.directory, "AGENT_NOTES.md"), "utf8")).toBe(
+      "Run the targeted tests before committing.\nKeep existing notes.\n",
+    );
+    await h.create();
+    const mcpB = await h.mcp();
+    expect((await mcpB.listTools()).tools.map((tool) => tool.name)).not.toContain(
+      "append_workspace_note",
+    );
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+const companyServer = { type: "http", url: "https://tools.example.com/mcp" } as const;
+const mcpSource = `
+export default function contribute(server) {
+  server.addHook("agent.open.before", async ({ request }) => {
+    if (request.provider !== "codex") return;
+    return { ...request, mcpServers: { ...request.mcpServers, company: ${JSON.stringify(companyServer)} },
+      env: { ...request.env, OPEN_REASON: request.reason } };
+  });
+  return () => {};
+}
+`;
+
+test.each([
+  { native: false, serverNames: ["paseo", "company"] },
+  { native: true, serverNames: ["company"] },
+])(
+  "session-open MCP servers reach launch but never saved configuration (native=$native)",
+  async ({ native, serverNames }) => {
+    const h = await setup(native, mcpSource);
+    try {
+      const a = await h.create();
+      expect(h.launches.at(-1)!.config.mcpServers?.company).toEqual(companyServer);
+      expect(a.config.mcpServers?.company).toBeUndefined();
+      const snapshot = (await h.client.fetchAgent(a.id))!.agent;
+      expect(snapshot.id).toBe(a.id);
+      expect(JSON.stringify(snapshot)).not.toContain("tools.example.com");
+      expect(h.launches.at(-1)!.context!.env!.OPEN_REASON).toBe("create");
+      expect(Object.keys(h.launches.at(-1)!.config.mcpServers!)).toEqual(serverNames);
+      await h.daemon.daemon.agentManager.closeAgent(a.id);
+      const agentFiles = await readdir(path.join(h.daemon.paseoHome, "agents"), {
+        recursive: true,
+      });
+      const recordFile = agentFiles.find((file) => file.endsWith(a.id + ".json"))!;
+      const record = await readFile(path.join(h.daemon.paseoHome, "agents", recordFile), "utf8");
+      expect(record).not.toContain("tools.example.com");
+    } finally {
+      await h.close();
+    }
+  },
+  60_000,
+);
+
+test("session-open MCP servers are rederived on resume, SDK reload, and provider import", async () => {
+  const source = reloadRpcSource
+    .replace('    if (request.labels.x !== "y") return;', "")
+    .replace(
+      "return { ...request, env:",
+      `return { ...request, mcpServers: { ...request.mcpServers, company: ${JSON.stringify(companyServer)} }, env:`,
+    );
+  const h = await setup(true, source);
+  try {
+    const a = await h.create({ x: "y" });
+    const manager = h.daemon.daemon.agentManager;
+    await manager.closeAgent(a.id);
+    await manager.resumeAgentFromPersistence(a.persistence!, a.config, a.id);
+    expect(h.launches.at(-1)!.config.mcpServers?.company).toEqual(companyServer);
+    expect(JSON.parse(h.launches.at(-1)!.context!.env!.OPEN_INFO).reason).toBe("resume");
+    await h.client.invokePluginRpc("tools-test", "reload_agent", { id: a.id });
+    expect(h.launches.at(-1)!.config.mcpServers?.company).toEqual(companyServer);
+    expect(JSON.parse(h.launches.at(-1)!.context!.env!.OPEN_INFO).reason).toBe("refresh");
+    const imported = await manager.importProviderSession({
+      provider: "codex",
+      providerHandleId: "imported-session",
+      cwd: h.directory,
+      workspaceId: "import-workspace",
+      labels: { x: "y" },
+    });
+    expect(h.launches.at(-1)!.config.mcpServers?.company).toEqual(companyServer);
+    expect(JSON.parse(h.launches.at(-1)!.context!.env!.OPEN_INFO).reason).toBe("import");
+    expect(imported.config.mcpServers?.company).toBeUndefined();
+    expect(JSON.stringify(imported.persistence)).not.toContain("tools.example.com");
+    expect(manager.getAgent(a.id)!.config.mcpServers?.company).toBeUndefined();
+    expect(JSON.stringify(manager.getAgent(a.id)!.persistence)).not.toContain("tools.example.com");
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("installing and disabling an MCP plugin reopens idle sessions before their next prompt", async () => {
+  const h = await setup(true, "export default function contribute() { return () => {}; }");
+  try {
+    const a = await h.create();
+    expect(h.launches.at(-1)!.config.mcpServers?.company).toBeUndefined();
+    await h.install("company-mcp", mcpSource);
+    await sendAndFinish(h, a.id, "after install");
+    expect(h.launches).toHaveLength(2);
+    expect(h.launches.at(-1)!.config.mcpServers?.company).toEqual(companyServer);
+    await h.client.disablePlugin("company-mcp");
+    await sendAndFinish(h, a.id, "after disable");
+    expect(h.launches).toHaveLength(3);
+    expect(h.launches.at(-1)!.config.mcpServers?.company).toBeUndefined();
+    await sendAndFinish(h, a.id, "stable");
+    expect(h.launches).toHaveLength(3);
+    expect(h.events.interrupts).toBe(0);
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("installing and disabling an MCP plugin never interrupts a running turn", async () => {
+  let release!: () => void;
+  const blocked = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const h = await setup(
+    true,
+    "export default function contribute() { return () => {}; }",
+    undefined,
+    { beforeTurnComplete: async () => blocked },
+  );
+  try {
+    const a = await h.create();
+    await h.client.sendMessage(a.id, "busy", { activeTurnBehavior: "steer" });
+    const manager = h.daemon.daemon.agentManager;
+    await expect.poll(() => manager.getAgent(a.id)!.activeTurnId).not.toBeNull();
+    const turn = manager.getAgent(a.id)!.activeTurnId;
+    await h.install("company-mcp", mcpSource);
+    expect(h.launches).toHaveLength(1);
+    expect(manager.getAgent(a.id)!.activeTurnId).toBe(turn);
+    await h.client.disablePlugin("company-mcp");
+    expect(h.launches).toHaveLength(1);
+    expect(manager.getAgent(a.id)!.activeTurnId).toBe(turn);
+    expect(h.events.interrupts).toBe(0);
+    release();
+    await expect.poll(() => manager.hasInFlightRun(a.id)).toBe(false);
+    await sendAndFinish(h, a.id, "idle");
+    expect(h.launches).toHaveLength(2);
+    expect(h.launches.at(-1)!.config.mcpServers?.company).toBeUndefined();
+  } finally {
+    release();
+    await h.close();
+  }
+}, 60_000);
+
+test.each([
+  {
+    target: "saved configuration",
+    saved: true,
+    name: "company",
+    other: false,
+    error: /company.*plugin tools-test.*agent saved configuration/,
+  },
+  {
+    target: "saved Paseo name",
+    saved: true,
+    name: "paseo",
+    other: false,
+    error: /paseo.*plugin tools-test.*agent saved configuration/,
+  },
+  {
+    target: "Paseo internal server",
+    saved: false,
+    name: "paseo",
+    other: false,
+    error: /paseo.*plugin tools-test.*Paseo internal MCP server/,
+  },
+  {
+    target: "another plugin with identical config",
+    saved: false,
+    name: "company",
+    other: true,
+    error: /Plugin tools-test.*company.*plugin other-mcp/,
+  },
+])(
+  "session-open MCP collisions with $target name both owners",
+  async ({ saved, name, other, error }) => {
+    const h = await setup(true, mcpSource.replace("company:", name + ":"));
+    try {
+      if (other) await h.install("other-mcp", mcpSource);
+      await expect(
+        h.daemon.daemon.agentManager.createAgent(
+          {
+            provider: "codex",
+            cwd: h.directory,
+            ...(saved
+              ? { mcpServers: { [name]: { type: "http", url: "https://saved.example.com" } } }
+              : {}),
+          },
+          undefined,
+          {},
+        ),
+      ).rejects.toThrow(error);
+      expect(h.launches).toHaveLength(0);
+    } finally {
+      await h.close();
+    }
+  },
+  60_000,
+);
+
+test("session-open MCP servers fail on unsupported providers and leave saved config untouched", async () => {
+  const h = await setup(false, mcpSource, undefined, { supportsMcpServers: false });
+  try {
+    await h.client.disablePlugin("tools-test");
+    const a = await h.create();
+    await h.client.enablePlugin("tools-test");
+    await expect(h.daemon.daemon.agentManager.reloadAgentSession(a.id)).rejects.toThrow(
+      /does not support MCP servers.*plugin tools-test/,
+    );
+    expect(a.config.mcpServers?.company).toBeUndefined();
+    await expect(h.create()).rejects.toThrow(/does not support MCP servers.*plugin tools-test/);
+    const imported = h.daemon.daemon.agentManager.importProviderSession({
+      provider: "codex",
+      providerHandleId: "unsupported-import",
+      cwd: h.directory,
+      workspaceId: "import-workspace",
+    });
+    await expect(imported).rejects.toThrow(/does not support MCP servers.*plugin tools-test/);
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("history opens ignore session-open MCP servers", async () => {
+  const h = await setup(true, mcpSource);
+  try {
+    const a = await h.create();
+    await h.client.archiveAgent(a.id);
+    await h.install("other-mcp", mcpSource);
+    await h.daemon.daemon.agentManager.resumeAgentFromPersistence(a.persistence!, a.config, a.id);
+    expect(h.launches.at(-1)!.config.mcpServers?.company).toBeUndefined();
+    expect(h.launches.at(-1)!.context!.mcpServers).toBeUndefined();
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("session-open MCP maps are plugin-local and accumulate only across their own callbacks", async () => {
+  const h = await setup(true, mcpSource);
+  try {
+    await h.install(
+      "z-extend",
+      `
+export default function contribute(server) {
+  server.addHook("agent.open.before", async ({ request }) => {
+    if ("mcpServerOwners" in request) throw new Error("Daemon provenance leaked");
+    if (Object.keys(request.mcpServers).length !== 0) throw new Error("Saw another plugin servers");
+    return { ...request, mcpServers: { ...request.mcpServers, extra: { type: "stdio", command: "company-tools", args: ["--mcp"], env: { MODE: "agent" } } } };
+  });
+  server.addHook("agent.open.before", async ({ request }) => {
+    if (request.mcpServers.extra.command !== "company-tools") throw new Error("Lost own earlier server");
+    return { ...request, mcpServers: { ...request.mcpServers, additional: { type: "http", url: "https://additional.example.com/mcp" } } };
+  });
+  server.addHook("agent.open.before", async () => undefined);
+  return () => {};
+}`,
+    );
+    const a = await h.create();
+    expect(h.launches.at(-1)!.config.mcpServers).toEqual({
+      company: companyServer,
+      extra: { type: "stdio", command: "company-tools", args: ["--mcp"], env: { MODE: "agent" } },
+      additional: { type: "http", url: "https://additional.example.com/mcp" },
+    });
+    const contributedServers = h.launches.at(-1)!.config.mcpServers;
+    await h.install(
+      "zz-remove",
+      `export default function contribute(server) {
+  server.addHook("agent.open.before", async ({ request }) => ({ ...request, mcpServers: {} }));
+  return () => {};
+}`,
+    );
+    await sendAndFinish(h, a.id, "after removal");
+    expect(h.launches.at(-1)!.config.mcpServers).toEqual(contributedServers);
+    expect(a.config.mcpServers).toBeUndefined();
+  } finally {
+    await h.close();
+  }
+}, 60_000);
+
+test("session-open MCP configs are validated before a provider launches", async () => {
+  const h = await setup(
+    true,
+    mcpSource.replace(JSON.stringify(companyServer), '{ type: "http", url: 42 }'),
+  );
+  try {
+    await expect(h.create()).rejects.toThrow(/Plugin tools-test.*agent.open.before/s);
+    expect(h.launches).toHaveLength(0);
+  } finally {
+    await h.close();
+  }
+}, 60_000);
diff --git a/packages/server/src/server/plugins/agent-tools.test.ts b/packages/server/src/server/plugins/agent-tools.test.ts
new file mode 100644
index 0000000000..f3bf7b886f
--- /dev/null
+++ b/packages/server/src/server/plugins/agent-tools.test.ts
@@ -0,0 +1,46 @@
+import { expect, test } from "vitest";
+import { z } from "zod";
+import { defineAgentTool } from "@getpaseo/plugin/server";
+import { serializeAgentTool } from "./agent-tools.js";
+import { serializePaseoToolInputParameters } from "../agent/tools/paseo-tool-serialization.js";
+
+test("agent tool schemas survive the process boundary and catalog round trip", () => {
+  const input = z
+    .object({
+      title: z.string().min(1).describe("Issue title"),
+      state: z.enum(["open", "closed"]),
+      tags: z.array(z.string()).optional(),
+      nested: z.object({ enabled: z.boolean() }),
+    })
+    .describe("Create an issue");
+  const tool = defineAgentTool({
+    name: "create_issue",
+    description: "Create",
+    input,
+    execute: () => ({ text: "done" }),
+  });
+  const metadata = JSON.parse(JSON.stringify(serializeAgentTool(tool)));
+  const restored = z.fromJSONSchema(metadata.inputSchema);
+  expect(
+    serializePaseoToolInputParameters({
+      ...metadata,
+      inputSchema: restored,
+      handler: async () => ({ content: [] }),
+    }),
+  ).toEqual({
+    ...metadata.inputSchema,
+    additionalProperties: {},
+    properties: {
+      ...metadata.inputSchema.properties,
+      nested: { ...metadata.inputSchema.properties.nested, additionalProperties: {} },
+    },
+  });
+  expect(restored.parse({ title: "Bug", state: "open", nested: { enabled: true } })).toEqual({
+    title: "Bug",
+    state: "open",
+    nested: { enabled: true },
+  });
+  expect(
+    restored.safeParse({ title: "", state: "unknown", nested: { enabled: true } }).success,
+  ).toBe(false);
+});
diff --git a/packages/server/src/server/plugins/agent-tools.ts b/packages/server/src/server/plugins/agent-tools.ts
new file mode 100644
index 0000000000..266234b446
--- /dev/null
+++ b/packages/server/src/server/plugins/agent-tools.ts
@@ -0,0 +1,108 @@
+import { z } from "zod";
+import type {
+  AgentToolDefinition,
+  AgentToolResult,
+  PluginHookContext,
+  PluginSessionOpenRequest,
+  PluginHookAgent,
+} from "@getpaseo/plugin/server";
+import { toJsonSchemaCompat } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
+
+export const agentToolMetadataSchema = z
+  .object({
+    name: z
+      .string()
+      .regex(/^[a-z][a-z0-9_]*$/)
+      .max(64),
+    title: z.string().optional(),
+    description: z.string(),
+    inputSchema: z.record(z.string(), z.unknown()),
+    pluginId: z.string().optional(),
+    pluginInstanceId: z.string().optional(),
+  })
+  .strict();
+export type AgentToolMetadata = z.infer<typeof agentToolMetadataSchema>;
+export type AttachedAgentTool = AgentToolMetadata & { pluginId: string; pluginInstanceId: string };
+export type SessionOpenWireRequest = Omit<PluginSessionOpenRequest, "tools"> & {
+  tools: AgentToolMetadata[];
+};
+
+export interface PluginAgentToolsRuntime {
+  isToolPluginAvailable(pluginId: string, pluginInstanceId: string): boolean;
+  detachTools(agentId: string): void;
+  callTool(
+    pluginId: string,
+    pluginInstanceId: string,
+    agent: PluginHookAgent,
+    name: string,
+    input: unknown,
+    signal?: AbortSignal,
+  ): Promise<AgentToolResult>;
+}
+
+export function serializeAgentTool(tool: AgentToolDefinition): AgentToolMetadata {
+  return agentToolMetadataSchema.parse({
+    name: tool.name,
+    title: tool.title,
+    description: tool.description,
+    inputSchema: toJsonSchemaCompat(tool.input, { strictUnions: true, pipeStrategy: "input" }),
+  });
+}
+
+// This store lives only in the plugin process. Definitions and parsed values never cross IPC.
+export class PluginAgentTools {
+  private readonly agents = new Map<string, AgentToolDefinition[]>();
+  private readonly calls = new Map<string, { agentId: string; controller: AbortController }>();
+
+  attach(agentId: string, tools: AgentToolDefinition[]): AgentToolMetadata[] {
+    const names = new Set<string>();
+    const metadata = tools.map((tool) => {
+      const serialized = serializeAgentTool(tool);
+      if (names.has(tool.name)) throw new Error(`Duplicate agent tool: ${tool.name}`);
+      names.add(tool.name);
+      return serialized;
+    });
+    this.agents.set(agentId, tools);
+    return metadata;
+  }
+
+  detach(agentId: string): void {
+    this.agents.delete(agentId);
+    for (const call of this.calls.values()) {
+      if (call.agentId === agentId) call.controller.abort();
+    }
+  }
+
+  cancel(requestId: string): void {
+    this.calls.get(requestId)?.controller.abort();
+  }
+
+  close(): void {
+    for (const call of this.calls.values()) call.controller.abort();
+    this.agents.clear();
+  }
+
+  async call(
+    requestId: string,
+    agent: PluginHookAgent,
+    name: string,
+    input: unknown,
+    paseo: PluginHookContext["paseo"],
+  ): Promise<AgentToolResult> {
+    const controller = new AbortController();
+    this.calls.set(requestId, { agentId: agent.id, controller });
+    try {
+      const tool = this.agents.get(agent.id)?.find((definition) => definition.name === name);
+      if (!tool) throw new Error(`Agent tool not attached: ${name}`);
+      const parsed = await tool.input.parseAsync(input);
+      controller.signal.throwIfAborted();
+      const result = await tool.execute(parsed, { agent, paseo, signal: controller.signal });
+      controller.signal.throwIfAborted();
+      return result;
+    } catch (error) {
+      return { isError: true, text: error instanceof Error ? error.message : String(error) };
+    } finally {
+      this.calls.delete(requestId);
+    }
+  }
+}
diff --git a/packages/server/src/server/plugins/builtin/index.test.ts b/packages/server/src/server/plugins/builtin/index.test.ts
index 6160c8f855..5f4728ecfa 100644
--- a/packages/server/src/server/plugins/builtin/index.test.ts
+++ b/packages/server/src/server/plugins/builtin/index.test.ts
@@ -78,6 +78,45 @@ test("listed client bundle is published while plugins are disabled; unlisted dir
   }
 }, 60_000);
 
+test("a repeated catalog fetch leaves out the client bundle the client already holds", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "paseo-builtin-catalog-cache-"));
+  roots.push(root);
+  const directory = await fixture(root, "large", true);
+  // About the size of a real plugin client bundle.
+  await writeFile(
+    path.join(directory, "index.client.tsx"),
+    `const payload = ${JSON.stringify("x".repeat(1_000_000))};
+export default function contribute() { void payload; return () => {}; }`,
+  );
+  const daemon = await createTestPaseoDaemon({
+    daemonVersion: "0.9.2",
+    pluginsEnabled: false,
+    builtinPlugins: new BuiltinPluginLoader(root, ["large"]),
+  });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.9.2" });
+  const responseBytes: number[] = [];
+  const unsubscribe = client.subscribeRawMessages((message) => {
+    if (message.type === "plugin.catalog.get.response") {
+      responseBytes.push(JSON.stringify(message).length);
+    }
+  });
+  try {
+    await client.connect();
+    const first = await client.getPluginCatalog();
+    const second = await client.getPluginCatalog();
+
+    expect(second).toEqual(first);
+    expect(second[0]?.clientBundle).toContain("x".repeat(1_000_000));
+    expect(responseBytes).toHaveLength(2);
+    expect(responseBytes[0]).toBeGreaterThan(1_000_000);
+    expect(responseBytes[1]).toBeLessThan(500);
+  } finally {
+    unsubscribe();
+    await client.close();
+    await daemon.close();
+  }
+}, 60_000);
+
 test("directory, Git, and npm installs reject a built-in ID", async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), "paseo-builtin-install-"));
   roots.push(root);
diff --git a/packages/server/src/server/plugins/builtin/index.ts b/packages/server/src/server/plugins/builtin/index.ts
index cf6ffe9eee..463ee8407d 100644
--- a/packages/server/src/server/plugins/builtin/index.ts
+++ b/packages/server/src/server/plugins/builtin/index.ts
@@ -14,6 +14,7 @@ export const builtinPlugins = [
   "minimax-usage-source",
   "muse-provider",
   "opencode-go-usage-source",
+  "worktree-include",
   "zai-usage-source",
 ] as const;
 
diff --git a/packages/server/src/server/plugins/compiler-build.ts b/packages/server/src/server/plugins/compiler-build.ts
new file mode 100644
index 0000000000..51eb2d2549
--- /dev/null
+++ b/packages/server/src/server/plugins/compiler-build.ts
@@ -0,0 +1,450 @@
+import { stat } from "node:fs/promises";
+import { readPluginManifest } from "./manifest.js";
+import { assertPluginCompatibility } from "@getpaseo/protocol/plugin-requirements";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { isBuiltin } from "node:module";
+import path from "node:path";
+import { createPluginImportReader, type PluginImportKind } from "./compiler-imports.js";
+import type { Metafile, OnResolveResult, Plugin } from "esbuild";
+import {
+  isPluginClientOnlySdkSpecifier,
+  isPluginServerOnlySdkSpecifier,
+  PLUGIN_SDK_SPECIFIERS,
+} from "./plugin-sdk-specifiers.js";
+
+import { loadEsbuild, SERVER_HOST_MODULES } from "./compiler-esbuild.js";
+
+type PluginBuildTarget = "client" | "server";
+
+type PluginModuleLocation = PluginBuildTarget | "shared" | "invalid";
+
+function directoryTarget(filePath: string, pluginDirectory: string): PluginModuleLocation | null {
+  const relative = path.relative(pluginDirectory, filePath);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) return "invalid";
+  const segments = relative.split(path.sep);
+  if (segments.includes("node_modules")) return null;
+  if (segments[0] === "client") return "client";
+  if (segments[0] === "server") return "server";
+  if (segments[0] === "shared") return "shared";
+  if (/^index\.client\.tsx?$/.test(relative)) return "client";
+  if (/^index\.server\.tsx?$/.test(relative)) return "server";
+  return "invalid";
+}
+
+function containsPath(directory: string, filePath: string): boolean {
+  const relative = path.relative(directory, filePath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function dependencyName(specifier: string): string {
+  const segments = specifier.split("/");
+  return specifier.startsWith("@") ? segments.slice(0, 2).join("/") : segments[0];
+}
+
+function findDependencyRoot(
+  resolvedPath: string,
+  specifier: string,
+  pluginDirectory: string,
+): string | null {
+  const expectedName = dependencyName(specifier);
+  const ambientName = `@types/${expectedName.replace(/^@/, "").replace("/", "__")}`;
+  let directory = path.dirname(resolvedPath);
+  for (;;) {
+    const manifestPath = path.join(directory, "package.json");
+    if (existsSync(manifestPath)) {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { name?: unknown };
+      if (manifest.name === expectedName || manifest.name === ambientName) {
+        if (containsPath(pluginDirectory, directory) || containsPath(directory, pluginDirectory)) {
+          return null;
+        }
+        return directory;
+      }
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+function moduleBoundaryError(
+  moduleLocation: PluginModuleLocation | null,
+  target: PluginBuildTarget | "shared",
+  filePath: string,
+): OnResolveResult | null {
+  if (moduleLocation === "invalid") {
+    return {
+      errors: [{ text: `Plugin modules belong in client/, server/, or shared/: ${filePath}` }],
+    };
+  }
+  if (moduleLocation === null || moduleLocation === "shared" || moduleLocation === target) {
+    return null;
+  }
+  return {
+    errors: [
+      {
+        text: `${moduleLocation}-only module cannot be imported into the plugin ${target} bundle: ${filePath}`,
+      },
+    ],
+  };
+}
+
+function lexicalBoundaryError(
+  specifier: string,
+  resolveDirectory: string,
+  pluginDirectory: string,
+  target: PluginBuildTarget | "shared",
+): OnResolveResult | null {
+  if (!specifier.startsWith(".") && !path.isAbsolute(specifier)) return null;
+  const lexicalPath = path.resolve(resolveDirectory, specifier);
+  if (containsPath(pluginDirectory, lexicalPath)) {
+    return moduleBoundaryError(directoryTarget(lexicalPath, pluginDirectory), target, lexicalPath);
+  }
+  // Normalize only a containing root alias. Resolving the whole import would erase
+  // an authored server/ or client/ location when the final file is a symlink.
+  for (let ancestor = path.dirname(lexicalPath); ; ancestor = path.dirname(ancestor)) {
+    if (existsSync(ancestor) && realpathSync.native(ancestor) === pluginDirectory) {
+      const ownedPath = path.join(pluginDirectory, path.relative(ancestor, lexicalPath));
+      return moduleBoundaryError(directoryTarget(ownedPath, pluginDirectory), target, lexicalPath);
+    }
+    if (path.dirname(ancestor) === ancestor) return null;
+  }
+}
+
+function createRuntimeBoundaryPlugin(target: PluginBuildTarget, pluginDirectory: string): Plugin {
+  const boundaryResolution = {};
+  const linkedDependencyRoots = new Set<string>();
+  return {
+    name: `paseo-plugin-${target}-runtime-boundary`,
+    setup(buildContext) {
+      const checked = new Set<string>();
+      const imports = createPluginImportReader(pluginDirectory);
+      function resolvedBoundaryError(
+        resolvedFile: string,
+        specifier: string,
+        importer: string,
+        owner: PluginBuildTarget | "shared",
+      ) {
+        const file = realpathSync.native(resolvedFile);
+        const location = directoryTarget(file, pluginDirectory);
+        if (location === "invalid") {
+          if (
+            [...linkedDependencyRoots].some(
+              (root) => containsPath(root, importer) && containsPath(root, file),
+            )
+          )
+            return null;
+          if (!specifier.startsWith(".") && !path.isAbsolute(specifier)) {
+            const root = findDependencyRoot(file, specifier, pluginDirectory);
+            if (root) {
+              linkedDependencyRoots.add(root);
+              return null;
+            }
+          }
+        }
+        return moduleBoundaryError(location, owner, file);
+      }
+      async function resolveImportFiles(
+        file: string,
+        specifier: string,
+        kind: PluginImportKind,
+        typeOnly: boolean,
+      ): Promise<Set<string>> {
+        const declaration = imports.resolve(specifier, file, kind);
+        const dependencyFiles = new Set<string>();
+        if (declaration && (typeOnly || /\.d\.[cm]?ts$/.test(declaration)))
+          dependencyFiles.add(declaration);
+        if (typeOnly && !declaration) {
+          throw new Error(`Could not resolve type dependency "${specifier}" imported by ${file}`);
+        }
+        if (!typeOnly && kind !== "type-reference") {
+          const resolution = await buildContext.resolve(specifier, {
+            importer: file,
+            resolveDir: path.dirname(file),
+            kind,
+          });
+          // esbuild owns missing-runtime errors: erased imports and guarded optional
+          // requires are legal. Inspect every dependency that actually resolves.
+          if (!resolution.errors.length && !resolution.external && resolution.namespace === "file")
+            dependencyFiles.add(realpathSync.native(resolution.path));
+        }
+        return dependencyFiles;
+      }
+      async function checkSourceImports(
+        sourcePath: string,
+        inheritedOwner: PluginBuildTarget | "shared",
+      ): Promise<OnResolveResult | null> {
+        const file = realpathSync.native(sourcePath);
+        const owner =
+          directoryTarget(file, pluginDirectory) === "shared" ? "shared" : inheritedOwner;
+        const key = `${owner}:${file}`;
+        if (checked.has(key) || !/\.[cm]?[jt]sx?$/.test(file)) return null;
+        checked.add(key);
+        for (const { specifier, kind, typeOnly } of imports.read(file)) {
+          const packageSpecifier =
+            kind === "type-reference"
+              ? `@types/${specifier.replace(/^@/, "").replace("/", "__")}`
+              : specifier;
+          const error =
+            runtimeSpecifierError(specifier, owner, file) ??
+            runtimeSpecifierError(packageSpecifier, owner, file) ??
+            lexicalBoundaryError(specifier, path.dirname(file), pluginDirectory, owner);
+          if (error) return error;
+          // Protocol types are shared host contracts, also exposed by the SDK's peer
+          // dependency during development. Erased imports need no plugin-local install;
+          // runtime imports still go through normal dependency resolution below.
+          if (typeOnly && specifier.startsWith("@getpaseo/protocol/")) continue;
+          // Host modules have separately enforced SDK boundaries and need no local installation.
+          if (
+            (PLUGIN_SDK_SPECIFIERS as readonly string[]).includes(specifier) ||
+            /^(zod|react|react-native|@tanstack\/react-query)(\/|$)/.test(specifier) ||
+            isBuiltin(specifier) ||
+            packageSpecifier === "@types/node"
+          )
+            continue;
+          const dependencyFiles = await resolveImportFiles(file, specifier, kind, typeOnly);
+          for (const dependencyFile of dependencyFiles) {
+            const boundaryError = resolvedBoundaryError(dependencyFile, specifier, file, owner);
+            if (boundaryError) return boundaryError;
+            const dependencyError = await checkSourceImports(dependencyFile, owner);
+            if (dependencyError) return dependencyError;
+          }
+        }
+        return null;
+      }
+      buildContext.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) =>
+        checkSourceImports(args.path, target),
+      );
+      buildContext.onResolve({ filter: /.*/ }, async (args) => {
+        if (args.kind === "entry-point") return null;
+        if (args.pluginData === boundaryResolution) return null;
+        const importer =
+          args.namespace === "file" ? realpathSync.native(args.importer) : args.importer;
+        const resolveDir = args.namespace === "file" ? path.dirname(importer) : args.resolveDir;
+        const owner = directoryTarget(importer, pluginDirectory) === "shared" ? "shared" : target;
+        const specifierError = runtimeSpecifierError(args.path, owner, importer);
+        if (specifierError) return specifierError;
+        const lexicalError = lexicalBoundaryError(args.path, resolveDir, pluginDirectory, owner);
+        if (lexicalError) return lexicalError;
+        const resolution = await buildContext.resolve(args.path, {
+          importer,
+          namespace: args.namespace,
+          resolveDir,
+          kind: args.kind,
+          pluginData: boundaryResolution,
+          with: args.with,
+        });
+        if (
+          resolution.errors.length > 0 ||
+          resolution.external ||
+          resolution.namespace !== "file"
+        ) {
+          return null;
+        }
+        return resolvedBoundaryError(resolution.path, args.path, importer, owner);
+      });
+    },
+  };
+}
+
+function wrapCommonJsBundle(code: string): string {
+  return `(function(require) {\nconst module = { exports: {} };\nconst exports = module.exports;\n${code}\nreturn module.exports;\n})`;
+}
+
+function makeHermesInteropEager(code: string): string {
+  // Hermes evaluates esbuild's lazy CommonJS interop getters from a string with
+  // the final loop binding, so every named import can resolve to the last export.
+  // Plugin bundles execute once and do not need live bindings from host modules.
+  return code.replaceAll("get: () => from[key]", "value: from[key]");
+}
+
+async function minifyClientBundle(code: string): Promise<string> {
+  const { transform } = loadEsbuild();
+  // Minify after the eager replace. Whitespace minify rewrites the getter this
+  // replace matches, and identifier minify can delete the helper entirely.
+  const result = await transform(code, {
+    minifyWhitespace: true,
+    minifySyntax: true,
+    minifyIdentifiers: false,
+    target: "es2020",
+    supported: { "async-await": false },
+    charset: "ascii",
+    legalComments: "inline",
+  });
+  return result.code;
+}
+
+function runtimeSpecifierError(
+  specifier: string,
+  target: PluginBuildTarget | "shared",
+  importer: string,
+): OnResolveResult | null {
+  let kind: string | null = null;
+  if (specifier === "@getpaseo/plugin/client/host") kind = "host-private";
+  else if (
+    (specifier === "@getpaseo/plugin" ||
+      specifier.startsWith("@getpaseo/plugin/") ||
+      specifier === "@paseo/plugin" ||
+      specifier.startsWith("@paseo/plugin/")) &&
+    !(PLUGIN_SDK_SPECIFIERS as readonly string[]).includes(specifier)
+  )
+    kind = "Unknown SDK";
+  else if (target !== "server" && (isBuiltin(specifier) || specifier === "@types/node"))
+    kind = "Node";
+  else if (target !== "server" && isPluginServerOnlySdkSpecifier(specifier)) kind = "server-only";
+  else if (
+    target !== "client" &&
+    (isPluginClientOnlySdkSpecifier(specifier) ||
+      /^((?:@types\/)?react(?:-dom|-native)?|use-sync-external-store|@tanstack\/react-query)(\/|$)/.test(
+        specifier,
+      ))
+  )
+    kind = "client-only";
+  return kind
+    ? {
+        errors: [
+          {
+            text: `${kind} module cannot be imported into the plugin ${target} bundle: ${specifier} imported by ${importer}`,
+          },
+        ],
+      }
+    : null;
+}
+
+function checkSharedDependencies(inputs: Metafile["inputs"], pluginDirectory: string): void {
+  function inputLocation(file: string): PluginModuleLocation | null {
+    const absolutePath = path.resolve(file);
+    // Metafile keys must stay unchanged for graph traversal. Only filesystem
+    // inputs have canonical paths; data URLs and external specifiers do not.
+    return directoryTarget(
+      existsSync(absolutePath) ? realpathSync.native(absolutePath) : absolutePath,
+      pluginDirectory,
+    );
+  }
+  const pending = Object.keys(inputs).filter((file) => inputLocation(file) === "shared");
+  const visited = new Set<string>();
+  while (pending.length) {
+    const file = pending.pop()!;
+    if (visited.has(file)) continue;
+    visited.add(file);
+    for (const dependency of inputs[file]?.imports ?? []) {
+      const location = dependency.external ? null : inputLocation(dependency.path);
+      const error =
+        runtimeSpecifierError(dependency.original ?? dependency.path, "shared", file) ??
+        (dependency.external
+          ? null
+          : moduleBoundaryError(
+              location === "invalid" ? null : location,
+              "shared",
+              dependency.path,
+            ));
+      if (error?.errors?.length) throw new Error(error.errors[0].text);
+      if (!dependency.external) pending.push(dependency.path);
+    }
+  }
+}
+
+async function compileTarget(entryPath: string, target: PluginBuildTarget): Promise<string> {
+  const { build } = loadEsbuild();
+  // Use native canonical paths throughout: TypeScript expands Windows short names
+  // when resolving type references, while the JS realpath implementation retains them.
+  const pluginDirectory = realpathSync.native(path.dirname(entryPath));
+  const result = await build({
+    entryPoints: [realpathSync.native(entryPath)],
+    bundle: true,
+    format: "cjs",
+    jsx: "automatic",
+    // `import icon from "./icon.svg"` yields the markup for an inline `{ svg }` icon.
+    loader: { ".svg": "text" },
+    platform: target === "server" ? "node" : "neutral",
+    target: target === "server" ? "node20" : "es2020",
+    // The neutral platform reads no package.json entry fields, so packages without
+    // `exports` would not resolve. Read the same fields as esbuild's browser platform
+    // minus `browser`, since the bundle also runs in React Native.
+    mainFields: target === "client" ? ["module", "main"] : undefined,
+    // Metro lowers async syntax before Hermes sees app code. Plugin client bundles bypass Metro,
+    // so apply the same compatibility transform before the app evaluates them from source.
+    supported: target === "client" ? { "async-await": false } : undefined,
+    external:
+      target === "client"
+        ? [
+            ...PLUGIN_SDK_SPECIFIERS,
+            "@tanstack/react-query",
+            "react",
+            "react/jsx-runtime",
+            "react-native",
+            "zod",
+          ]
+        : SERVER_HOST_MODULES,
+    plugins: [createRuntimeBoundaryPlugin(target, pluginDirectory)],
+    metafile: true,
+    logLevel: "silent",
+    treeShaking: true,
+    write: false,
+  });
+  checkSharedDependencies(result.metafile.inputs, pluginDirectory);
+  const output = result.outputFiles[0]?.text;
+  if (!output) throw new Error(`Plugin ${target} compilation produced no output`);
+  const eager = makeHermesInteropEager(output);
+  let prepared = eager;
+  if (target === "client") prepared = await minifyClientBundle(eager);
+  return wrapCommonJsBundle(prepared);
+}
+
+export async function compilePlugin(entryPaths: {
+  client: string | null;
+  server: string | null;
+}): Promise<{
+  clientBundle: string | null;
+  serverBundle: string | null;
+}> {
+  const [clientBundle, serverBundle] = await Promise.all([
+    entryPaths.client ? compileTarget(entryPaths.client, "client") : null,
+    entryPaths.server ? compileTarget(entryPaths.server, "server") : null,
+  ]);
+  return { clientBundle, serverBundle };
+}
+
+const CLIENT_ENTRY_FILENAMES = ["index.client.ts", "index.client.tsx"] as const;
+const SERVER_ENTRY_FILENAMES = ["index.server.ts", "index.server.tsx"] as const;
+async function findEntry(directory: string, filenames: readonly string[]): Promise<string | null> {
+  for (const filename of filenames) {
+    const filePath = path.join(directory, filename);
+    const info = await stat(filePath).catch(() => null);
+    if (info?.isFile()) return filePath;
+  }
+  return null;
+}
+
+async function resolveEntryPaths(directory: string): Promise<{
+  client: string | null;
+  server: string | null;
+}> {
+  const [client, server] = await Promise.all([
+    findEntry(directory, CLIENT_ENTRY_FILENAMES),
+    findEntry(directory, SERVER_ENTRY_FILENAMES),
+  ]);
+  if (client || server) return { client, server };
+  const legacyEntry = await findEntry(directory, ["index.ts", "index.tsx"]);
+  if (legacyEntry) {
+    throw new Error(
+      "This plugin was made for an older version of Paseo and cannot run on Paseo v0.8. Ask its author to update it. Plugin authors can follow the migration guide: https://paseo.sh/docs/plugins/migration",
+    );
+  }
+  throw new Error(
+    `Plugin entry points are missing: expected ${CLIENT_ENTRY_FILENAMES.join(" or ")} and/or ${SERVER_ENTRY_FILENAMES.join(" or ")} in ${directory}`,
+  );
+}
+
+export async function compileDirectoryPlugin(
+  directory: string,
+  version: string,
+  builtinId?: string,
+) {
+  const manifest = await readPluginManifest(directory);
+  if (builtinId !== undefined && manifest.id !== builtinId) {
+    throw new Error(`Built-in plugin ${builtinId} has manifest ID ${manifest.id}`);
+  }
+  assertPluginCompatibility({ ...manifest, version, runtime: "daemon" });
+  const bundles = await compilePlugin(await resolveEntryPaths(directory));
+  return { ...bundles, manifest };
+}
diff --git a/packages/server/src/server/plugins/compiler-esbuild.ts b/packages/server/src/server/plugins/compiler-esbuild.ts
new file mode 100644
index 0000000000..c36c9c22f9
--- /dev/null
+++ b/packages/server/src/server/plugins/compiler-esbuild.ts
@@ -0,0 +1,64 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { PLUGIN_SDK_SPECIFIERS } from "./plugin-sdk-specifiers.js";
+const nodeRequire = createRequire(import.meta.url);
+export const SERVER_HOST_MODULES = [...PLUGIN_SDK_SPECIFIERS, "zod"];
+const ESBUILD_BINARY_PATH = "ESBUILD_BINARY_PATH";
+
+// esbuild resolves its own platform binary via require.resolve() the first time its
+// module is evaluated. Inside the packaged desktop app that resolves to a path under
+// app.asar even though electron-builder unpacks the real binary to app.asar.unpacked.
+// child_process.spawn bypasses Electron's asar fs shim, so the OS rejects that path
+// with ENOTDIR. Point esbuild at the real unpacked binary before its module loads.
+export function unpackedEsbuildBinaryFromPackageDir(
+  esbuildPackageDir: string,
+  platform: NodeJS.Platform,
+  arch: string,
+): string | null {
+  const asarSegment = `${path.sep}app.asar${path.sep}`;
+  const asarIndex = esbuildPackageDir.indexOf(asarSegment);
+  if (asarIndex === -1) return null;
+  return path.join(
+    esbuildPackageDir.slice(0, asarIndex),
+    "app.asar.unpacked",
+    "node_modules",
+    `@esbuild/${platform}-${arch}`,
+    ...(platform === "win32" ? ["esbuild.exe"] : ["bin", "esbuild"]),
+  );
+}
+
+export function resolveExistingAsarUnpackedEsbuildBinary(
+  esbuildPackageDir: string,
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+  exists: (file: string) => boolean = existsSync,
+): string | null {
+  const binaryPath = unpackedEsbuildBinaryFromPackageDir(esbuildPackageDir, platform, arch);
+  return binaryPath && exists(binaryPath) ? binaryPath : null;
+}
+
+function resolveAsarUnpackedEsbuildBinary(): string | null {
+  let esbuildDir: string;
+  try {
+    esbuildDir = path.dirname(nodeRequire.resolve("esbuild/package.json"));
+  } catch {
+    return null;
+  }
+  return resolveExistingAsarUnpackedEsbuildBinary(esbuildDir);
+}
+
+export function loadEsbuild(): typeof import("esbuild") {
+  const previousBinaryPath = process.env[ESBUILD_BINARY_PATH];
+  const unpackedBinary = resolveAsarUnpackedEsbuildBinary();
+  if (unpackedBinary) process.env[ESBUILD_BINARY_PATH] = unpackedBinary;
+
+  try {
+    // esbuild reads this variable while its CommonJS module is evaluated. Keep
+    // the compatibility bridge local so it cannot become an agent's environment.
+    return nodeRequire("esbuild") as typeof import("esbuild");
+  } finally {
+    if (previousBinaryPath === undefined) delete process.env[ESBUILD_BINARY_PATH];
+    else process.env[ESBUILD_BINARY_PATH] = previousBinaryPath;
+  }
+}
diff --git a/packages/server/src/server/plugins/compiler-worker.ts b/packages/server/src/server/plugins/compiler-worker.ts
new file mode 100644
index 0000000000..ddf2544b8b
--- /dev/null
+++ b/packages/server/src/server/plugins/compiler-worker.ts
@@ -0,0 +1,62 @@
+import { parentPort } from "node:worker_threads";
+import type { ZodIssue } from "zod";
+import { compilePlugin, compileDirectoryPlugin } from "./compiler-build.js";
+import { runPluginBuild } from "./preparation-build.js";
+import type { CompilerTask } from "./compiler.js";
+
+export type CompilerReply =
+  | { kind: "log"; data: Record<string, unknown>; message: string }
+  | { kind: "result"; value: unknown }
+  | {
+      kind: "error";
+      error: Error;
+      properties: Record<string, unknown>;
+      issues?: ZodIssue[];
+      errors?: unknown[];
+      warnings?: unknown[];
+    };
+
+const port = parentPort!;
+// The compiler owner serializes requests; the port queues the first request
+// until this entrypoint has loaded, including in source/tsx development.
+port.on("message", (task: CompilerTask) => {
+  void run(task);
+});
+
+async function run(task: CompilerTask): Promise<void> {
+  try {
+    let value: unknown;
+    switch (task.kind) {
+      case "entries":
+        value = await compilePlugin(task.entries);
+        break;
+      case "directory":
+        value = await compileDirectoryPlugin(task.directory, task.version, task.builtinId);
+        break;
+      case "prepare":
+        await runPluginBuild(
+          task.directory,
+          task.commands,
+          {
+            info: (data, message) =>
+              port.postMessage({ kind: "log", data, message } satisfies CompilerReply),
+          },
+          task.environment,
+        );
+        break;
+    }
+    port.postMessage({ kind: "result", value } satisfies CompilerReply);
+  } catch (cause) {
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    port.postMessage({
+      kind: "error",
+      error,
+      // Error cloning drops own metadata such as filesystem code/path. Zod's
+      // readonly issues are reconstructed separately by the compiler owner.
+      properties: Object.fromEntries(Object.entries(error).filter(([key]) => key !== "issues")),
+      ...("issues" in error ? { issues: error.issues as ZodIssue[] } : {}),
+      ...("errors" in error ? { errors: error.errors as unknown[] } : {}),
+      ...("warnings" in error ? { warnings: error.warnings as unknown[] } : {}),
+    } satisfies CompilerReply);
+  }
+}
diff --git a/packages/server/src/server/plugins/compiler.test.ts b/packages/server/src/server/plugins/compiler.test.ts
index 6f694fbaa3..69510cdfb0 100644
--- a/packages/server/src/server/plugins/compiler.test.ts
+++ b/packages/server/src/server/plugins/compiler.test.ts
@@ -3,8 +3,11 @@ import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
+import * as zod from "zod";
+import { ZodError } from "zod";
 import {
   compilePlugin,
+  compileDirectoryPlugin,
   resolveExistingAsarUnpackedEsbuildBinary,
   unpackedEsbuildBinaryFromPackageDir,
 } from "./compiler.js";
@@ -567,6 +570,101 @@ export default function contribute(client) {
     expect(clientBundle).toContain("__async");
   });
 
+  it("reduces client bytes while preserving registration and leaving server output readable", async () => {
+    const entries = await createSplitPlugin();
+    const source = `import { z } from "zod";
+const commandSchema = z.object({ id: z.string(), title: z.string() });
+export default function contribute(client) {
+  const command = commandSchema.parse({ id: "open", title: "Open – plugin" });
+  client.addCommandCenterItem({
+    ...command,
+    icon: "Scan",
+    context: "global",
+    onSelect() { return Promise.resolve(command.title); },
+  });
+  return () => undefined;
+}`;
+    await Promise.all([writeFile(entries.client, source), writeFile(entries.server, source)]);
+    const { clientBundle, serverBundle } = await compilePlugin(entries);
+    if (clientBundle === null || serverBundle === null) {
+      throw new Error("compilePlugin returned no bundle");
+    }
+
+    for (const bundle of [clientBundle, serverBundle]) {
+      const registered: { id: string; title: string; onSelect: () => Promise<string> }[] = [];
+      const exports = new Function(`return ${bundle}`)()((specifier: string) => {
+        expect(specifier).toBe("zod");
+        return zod;
+      });
+      const cleanup = exports.default({
+        addCommandCenterItem: (command: (typeof registered)[number]) => registered.push(command),
+      });
+      expect(registered).toMatchObject([{ id: "open", title: "Open – plugin" }]);
+      await expect(registered[0]!.onSelect()).resolves.toBe("Open – plugin");
+      expect(cleanup()).toBeUndefined();
+    }
+    expect(Buffer.byteLength(clientBundle)).toBeLessThan(Buffer.byteLength(serverBundle) * 0.9);
+    expect(clientBundle.split("").every((char) => char.charCodeAt(0) <= 0x7f)).toBe(true);
+    expect(serverBundle).toContain('title: "Open');
+  });
+
+  it("retains dependency license notices while minifying executable client code", async () => {
+    const entries = await createSplitPlugin();
+    const dependency = path.join(entries.directory, "node_modules/licensed-dependency");
+    const notice = "Copyright Example Authors. SPDX-License-Identifier: MIT";
+    await mkdir(dependency, { recursive: true });
+    await writeFile(
+      path.join(dependency, "package.json"),
+      JSON.stringify({ name: "licensed-dependency", main: "index.js" }),
+    );
+    await writeFile(
+      path.join(dependency, "index.js"),
+      `/*! ${notice} */
+exports.title = function title(input) {
+  const trimmed = input.trim();
+  return "Licensed " + trimmed;
+};`,
+    );
+    const source = `import { title } from "licensed-dependency";
+export default function contribute() { return title(" plugin "); }`;
+    await Promise.all([writeFile(entries.client, source), writeFile(entries.server, source)]);
+    const { clientBundle, serverBundle } = await compilePlugin(entries);
+    if (clientBundle === null || serverBundle === null) {
+      throw new Error("compilePlugin returned no bundle");
+    }
+
+    for (const bundle of [clientBundle, serverBundle]) {
+      expect(bundle).toContain(notice);
+      const exports = new Function(`return ${bundle}`)()(() => {
+        throw new Error("The dependency must be bundled");
+      });
+      expect(exports.default()).toBe("Licensed plugin");
+    }
+    expect(Buffer.byteLength(clientBundle)).toBeLessThan(Buffer.byteLength(serverBundle) * 0.9);
+  });
+
+  it("keeps distinct host exports eager when minifying in the worker", async () => {
+    const entries = await createSplitPlugin();
+    await writeFile(
+      entries.client,
+      `import * as host from "zod";
+export default function contribute() { return [host.first, host.second]; }`,
+    );
+    const { clientBundle } = await compilePlugin({ client: entries.client, server: null });
+    const host = { first: "first export", second: "second export" };
+    const factory = new Function(`return ${clientBundle}`)() as (
+      require: (specifier: string) => typeof host,
+    ) => { default: () => unknown };
+    function requireHost(specifier: string): typeof host {
+      expect(specifier).toBe("zod");
+      return host;
+    }
+    const exports = factory(requireHost);
+    host.first = "changed first export";
+    host.second = "changed second export";
+    expect(exports.default()).toEqual(["first export", "second export"]);
+  });
+
   it("rejects node imports from the client entry", async () => {
     const entries = await createSplitPlugin();
     await writeFile(
@@ -975,3 +1073,52 @@ export default function contribute() { void value; void secret; return () => und
     expect(serverBundle).toBeNull();
   });
 });
+
+it("preserves esbuild diagnostics across the compiler boundary", async () => {
+  const { server } = await createSplitPlugin();
+  await writeFile(server, "export default function contribute( {");
+  const error = await compilePlugin({ client: null, server }).catch((cause: unknown) => cause);
+  expect(error).toBeInstanceOf(Error);
+  expect(error).toMatchObject({
+    name: "Error",
+    message: expect.stringContaining("Expected identifier but found end of file"),
+    errors: [
+      expect.objectContaining({
+        text: "Expected identifier but found end of file",
+        location: expect.objectContaining({
+          line: 1,
+          lineText: "export default function contribute( {",
+        }),
+      }),
+    ],
+    warnings: [],
+  });
+  // A failed task does not poison the next build.
+  await writeFile(server, 'export default () => "recovered";');
+  const bundles = await compilePlugin({ client: null, server });
+  expect(bundles.serverBundle).toContain("recovered");
+});
+
+it("preserves manifest validation errors across the compiler boundary", async () => {
+  const { directory } = await createSplitPlugin();
+  await writeFile(path.join(directory, "paseo-plugin.json"), JSON.stringify({ id: 42 }));
+  const error = await compileDirectoryPlugin(directory, "0.13.2").catch((cause: unknown) => cause);
+  expect(error).toBeInstanceOf(ZodError);
+  expect(error).toMatchObject({
+    name: "ZodError",
+    issues: [expect.objectContaining({ path: ["id"], code: "invalid_type" })],
+  });
+  await writeFile(path.join(directory, "paseo-plugin.json"), "{");
+  await expect(compileDirectoryPlugin(directory, "0.13.2")).rejects.toBeInstanceOf(SyntaxError);
+});
+
+it("preserves filesystem error metadata for a missing entry", async () => {
+  const { server } = await createSplitPlugin();
+  await rm(server);
+  await expect(compilePlugin({ client: null, server })).rejects.toMatchObject({
+    code: "ENOENT",
+    errno: expect.any(Number),
+    syscall: "realpath",
+    path: server,
+  });
+});
diff --git a/packages/server/src/server/plugins/compiler.ts b/packages/server/src/server/plugins/compiler.ts
index 4cf89a902c..b96c8ecd4e 100644
--- a/packages/server/src/server/plugins/compiler.ts
+++ b/packages/server/src/server/plugins/compiler.ts
@@ -1,442 +1,152 @@
-import { existsSync, readFileSync, realpathSync } from "node:fs";
-import { createRequire, isBuiltin } from "node:module";
-import path from "node:path";
-import { createPluginImportReader, type PluginImportKind } from "./compiler-imports.js";
-import type { Metafile, OnResolveResult, Plugin } from "esbuild";
-import {
-  isPluginClientOnlySdkSpecifier,
-  isPluginServerOnlySdkSpecifier,
-  PLUGIN_SDK_SPECIFIERS,
-} from "./plugin-sdk-specifiers.js";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { Worker } from "node:worker_threads";
+import pLimit from "p-limit";
+import { ZodError } from "zod";
+import type * as build from "./compiler-build.js";
+import type { PluginManifest } from "./manifest.js";
+import type { CompilerReply } from "./compiler-worker.js";
 
-const nodeRequire = createRequire(import.meta.url);
-export const SERVER_HOST_MODULES = [...PLUGIN_SDK_SPECIFIERS, "zod"];
-const ESBUILD_BINARY_PATH = "ESBUILD_BINARY_PATH";
+export {
+  SERVER_HOST_MODULES,
+  resolveExistingAsarUnpackedEsbuildBinary,
+  unpackedEsbuildBinaryFromPackageDir,
+} from "./compiler-esbuild.js";
 
-// esbuild resolves its own platform binary via require.resolve() the first time its
-// module is evaluated. Inside the packaged desktop app that resolves to a path under
-// app.asar even though electron-builder unpacks the real binary to app.asar.unpacked.
-// child_process.spawn bypasses Electron's asar fs shim, so the OS rejects that path
-// with ENOTDIR. Point esbuild at the real unpacked binary before its module loads.
-export function unpackedEsbuildBinaryFromPackageDir(
-  esbuildPackageDir: string,
-  platform: NodeJS.Platform,
-  arch: string,
-): string | null {
-  const asarSegment = `${path.sep}app.asar${path.sep}`;
-  const asarIndex = esbuildPackageDir.indexOf(asarSegment);
-  if (asarIndex === -1) return null;
-  return path.join(
-    esbuildPackageDir.slice(0, asarIndex),
-    "app.asar.unpacked",
-    "node_modules",
-    `@esbuild/${platform}-${arch}`,
-    ...(platform === "win32" ? ["esbuild.exe"] : ["bin", "esbuild"]),
-  );
-}
-
-export function resolveExistingAsarUnpackedEsbuildBinary(
-  esbuildPackageDir: string,
-  platform: NodeJS.Platform = process.platform,
-  arch: string = process.arch,
-  exists: (file: string) => boolean = existsSync,
-): string | null {
-  const binaryPath = unpackedEsbuildBinaryFromPackageDir(esbuildPackageDir, platform, arch);
-  return binaryPath && exists(binaryPath) ? binaryPath : null;
-}
-
-function resolveAsarUnpackedEsbuildBinary(): string | null {
-  let esbuildDir: string;
-  try {
-    esbuildDir = path.dirname(nodeRequire.resolve("esbuild/package.json"));
-  } catch {
-    return null;
-  }
-  return resolveExistingAsarUnpackedEsbuildBinary(esbuildDir);
-}
-
-function loadEsbuild(): typeof import("esbuild") {
-  const previousBinaryPath = process.env[ESBUILD_BINARY_PATH];
-  const unpackedBinary = resolveAsarUnpackedEsbuildBinary();
-  if (unpackedBinary) process.env[ESBUILD_BINARY_PATH] = unpackedBinary;
-
-  try {
-    // esbuild reads this variable while its CommonJS module is evaluated. Keep
-    // the compatibility bridge local so it cannot become an agent's environment.
-    return nodeRequire("esbuild") as typeof import("esbuild");
-  } finally {
-    if (previousBinaryPath === undefined) delete process.env[ESBUILD_BINARY_PATH];
-    else process.env[ESBUILD_BINARY_PATH] = previousBinaryPath;
-  }
-}
-
-type PluginBuildTarget = "client" | "server";
-
-type PluginModuleLocation = PluginBuildTarget | "shared" | "invalid";
-
-function directoryTarget(filePath: string, pluginDirectory: string): PluginModuleLocation | null {
-  const relative = path.relative(pluginDirectory, filePath);
-  if (relative.startsWith("..") || path.isAbsolute(relative)) return "invalid";
-  const segments = relative.split(path.sep);
-  if (segments.includes("node_modules")) return null;
-  if (segments[0] === "client") return "client";
-  if (segments[0] === "server") return "server";
-  if (segments[0] === "shared") return "shared";
-  if (/^index\.client\.tsx?$/.test(relative)) return "client";
-  if (/^index\.server\.tsx?$/.test(relative)) return "server";
-  return "invalid";
-}
-
-function containsPath(directory: string, filePath: string): boolean {
-  const relative = path.relative(directory, filePath);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
-function dependencyName(specifier: string): string {
-  const segments = specifier.split("/");
-  return specifier.startsWith("@") ? segments.slice(0, 2).join("/") : segments[0];
-}
-
-function findDependencyRoot(
-  resolvedPath: string,
-  specifier: string,
-  pluginDirectory: string,
-): string | null {
-  const expectedName = dependencyName(specifier);
-  const ambientName = `@types/${expectedName.replace(/^@/, "").replace("/", "__")}`;
-  let directory = path.dirname(resolvedPath);
-  for (;;) {
-    const manifestPath = path.join(directory, "package.json");
-    if (existsSync(manifestPath)) {
-      const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { name?: unknown };
-      if (manifest.name === expectedName || manifest.name === ambientName) {
-        if (containsPath(pluginDirectory, directory) || containsPath(directory, pluginDirectory)) {
-          return null;
-        }
-        return directory;
-      }
-    }
-    const parent = path.dirname(directory);
-    if (parent === directory) return null;
-    directory = parent;
-  }
-}
-
-function moduleBoundaryError(
-  moduleLocation: PluginModuleLocation | null,
-  target: PluginBuildTarget | "shared",
-  filePath: string,
-): OnResolveResult | null {
-  if (moduleLocation === "invalid") {
-    return {
-      errors: [{ text: `Plugin modules belong in client/, server/, or shared/: ${filePath}` }],
+export type CompilerTask =
+  | { kind: "entries"; entries: Parameters<typeof build.compilePlugin>[0] }
+  | { kind: "directory"; directory: string; version: string; builtinId?: string }
+  | {
+      kind: "prepare";
+      directory: string;
+      commands: PluginManifest["build"];
+      environment: NodeJS.ProcessEnv;
     };
-  }
-  if (moduleLocation === null || moduleLocation === "shared" || moduleLocation === target) {
-    return null;
-  }
-  return {
-    errors: [
-      {
-        text: `${moduleLocation}-only module cannot be imported into the plugin ${target} bundle: ${filePath}`,
-      },
-    ],
-  };
+
+interface TaskResult {
+  entries: Awaited<ReturnType<typeof build.compilePlugin>>;
+  directory: Awaited<ReturnType<typeof build.compileDirectoryPlugin>>;
+  prepare: void;
 }
 
-function lexicalBoundaryError(
-  specifier: string,
-  resolveDirectory: string,
-  pluginDirectory: string,
-  target: PluginBuildTarget | "shared",
-): OnResolveResult | null {
-  if (!specifier.startsWith(".") && !path.isAbsolute(specifier)) return null;
-  const lexicalPath = path.resolve(resolveDirectory, specifier);
-  if (containsPath(pluginDirectory, lexicalPath)) {
-    return moduleBoundaryError(directoryTarget(lexicalPath, pluginDirectory), target, lexicalPath);
-  }
-  // Normalize only a containing root alias. Resolving the whole import would erase
-  // an authored server/ or client/ location when the final file is a symlink.
-  for (let ancestor = path.dirname(lexicalPath); ; ancestor = path.dirname(ancestor)) {
-    if (existsSync(ancestor) && realpathSync.native(ancestor) === pluginDirectory) {
-      const ownedPath = path.join(pluginDirectory, path.relative(ancestor, lexicalPath));
-      return moduleBoundaryError(directoryTarget(ownedPath, pluginDirectory), target, lexicalPath);
-    }
-    if (path.dirname(ancestor) === ancestor) return null;
-  }
-}
+const IDLE_TIMEOUT_MS = 1_000;
+const source = import.meta.url.endsWith(".ts");
+const workerUrl = new URL(
+  source ? "./compiler-worker.ts" : "./compiler-worker.js",
+  import.meta.url,
+);
+// Resolve the development loader once at module initialization, never during a
+// compile request. Packaged workers execute ordinary JavaScript without tsx.
+const workerEntrypoint = source
+  ? `import(${JSON.stringify(pathToFileURL(createRequire(import.meta.url).resolve("tsx/esm/api")).href)}).then(({ register }) => { register(); return import(${JSON.stringify(workerUrl.href)}); });`
+  : workerUrl;
 
-function createRuntimeBoundaryPlugin(target: PluginBuildTarget, pluginDirectory: string): Plugin {
-  const boundaryResolution = {};
-  const linkedDependencyRoots = new Set<string>();
-  return {
-    name: `paseo-plugin-${target}-runtime-boundary`,
-    setup(buildContext) {
-      const checked = new Set<string>();
-      const imports = createPluginImportReader(pluginDirectory);
-      function resolvedBoundaryError(
-        resolvedFile: string,
-        specifier: string,
-        importer: string,
-        owner: PluginBuildTarget | "shared",
-      ) {
-        const file = realpathSync.native(resolvedFile);
-        const location = directoryTarget(file, pluginDirectory);
-        if (location === "invalid") {
-          if (
-            [...linkedDependencyRoots].some(
-              (root) => containsPath(root, importer) && containsPath(root, file),
-            )
-          )
-            return null;
-          if (!specifier.startsWith(".") && !path.isAbsolute(specifier)) {
-            const root = findDependencyRoot(file, specifier, pluginDirectory);
-            if (root) {
-              linkedDependencyRoots.add(root);
-              return null;
-            }
+// Reuse the isolate during a build batch (notably daemon bootstrap), then release
+// TypeScript's heap when idle. Only this owner admits work or stops the worker.
+class PluginCompiler {
+  private readonly queue = pLimit(1);
+  private worker: Worker | null = null;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private stopping: Promise<unknown> = Promise.resolve();
+
+  run<T extends CompilerTask>(
+    task: T,
+    onLog?: (data: Record<string, unknown>, message: string) => void,
+  ): Promise<TaskResult[T["kind"]]> {
+    return this.queue(async () => {
+      if (this.idleTimer) clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+      await this.stopping;
+      const worker = this.worker ?? this.startWorker();
+      worker.ref();
+      try {
+        return await this.request<T>(worker, task, onLog);
+      } finally {
+        if (this.worker === worker) {
+          worker.unref();
+          this.idleTimer = setTimeout(() => this.stopWorker(worker), IDLE_TIMEOUT_MS);
+          this.idleTimer.unref();
+        } else {
+          await this.stopping;
+        }
+      }
+    });
+  }
+
+  private startWorker(): Worker {
+    const worker = new Worker(workerEntrypoint, { eval: source, execArgv: [] });
+    this.worker = worker;
+    // Keep error/exit ownership while idle too. The next caller gets a fresh
+    // isolate after a crash; author build commands are never retried.
+    worker.on("error", () => this.stopWorker(worker));
+    worker.on("exit", () => {
+      if (this.worker === worker) this.stopWorker(worker);
+    });
+    return worker;
+  }
+
+  private stopWorker(worker: Worker): void {
+    if (this.worker !== worker) return;
+    this.worker = null;
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+    this.stopping = worker.terminate();
+  }
+
+  private async request<T extends CompilerTask>(
+    worker: Worker,
+    task: T,
+    onLog?: (data: Record<string, unknown>, message: string) => void,
+  ): Promise<TaskResult[T["kind"]]> {
+    let onMessage: (reply: CompilerReply) => void;
+    let onError: (error: Error) => void;
+    let onExit: (code: number) => void;
+    try {
+      return await new Promise<TaskResult[T["kind"]]>((resolve, reject) => {
+        onError = reject;
+        onExit = (code) => reject(new Error(`Plugin compiler worker exited (code ${code})`));
+        onMessage = (reply) => {
+          if (reply.kind === "log") {
+            onLog?.(reply.data, reply.message);
+          } else if (reply.kind === "result") {
+            resolve(reply.value as TaskResult[T["kind"]]);
+          } else {
+            const error = reply.issues ? new ZodError(reply.issues) : reply.error;
+            Object.assign(error, reply.properties);
+            if (reply.errors) Object.assign(error, { errors: reply.errors });
+            if (reply.warnings) Object.assign(error, { warnings: reply.warnings });
+            // Promise.all can reject while the other target is still compiling.
+            // Retire the isolate before another request can enter it.
+            this.stopWorker(worker);
+            reject(error);
           }
-        }
-        return moduleBoundaryError(location, owner, file);
-      }
-      async function resolveImportFiles(
-        file: string,
-        specifier: string,
-        kind: PluginImportKind,
-        typeOnly: boolean,
-      ): Promise<Set<string>> {
-        const declaration = imports.resolve(specifier, file, kind);
-        const dependencyFiles = new Set<string>();
-        if (declaration && (typeOnly || /\.d\.[cm]?ts$/.test(declaration)))
-          dependencyFiles.add(declaration);
-        if (typeOnly && !declaration) {
-          throw new Error(`Could not resolve type dependency "${specifier}" imported by ${file}`);
-        }
-        if (!typeOnly && kind !== "type-reference") {
-          const resolution = await buildContext.resolve(specifier, {
-            importer: file,
-            resolveDir: path.dirname(file),
-            kind,
-          });
-          // esbuild owns missing-runtime errors: erased imports and guarded optional
-          // requires are legal. Inspect every dependency that actually resolves.
-          if (!resolution.errors.length && !resolution.external && resolution.namespace === "file")
-            dependencyFiles.add(realpathSync.native(resolution.path));
-        }
-        return dependencyFiles;
-      }
-      async function checkSourceImports(
-        sourcePath: string,
-        inheritedOwner: PluginBuildTarget | "shared",
-      ): Promise<OnResolveResult | null> {
-        const file = realpathSync.native(sourcePath);
-        const owner =
-          directoryTarget(file, pluginDirectory) === "shared" ? "shared" : inheritedOwner;
-        const key = `${owner}:${file}`;
-        if (checked.has(key) || !/\.[cm]?[jt]sx?$/.test(file)) return null;
-        checked.add(key);
-        for (const { specifier, kind, typeOnly } of imports.read(file)) {
-          const packageSpecifier =
-            kind === "type-reference"
-              ? `@types/${specifier.replace(/^@/, "").replace("/", "__")}`
-              : specifier;
-          const error =
-            runtimeSpecifierError(specifier, owner, file) ??
-            runtimeSpecifierError(packageSpecifier, owner, file) ??
-            lexicalBoundaryError(specifier, path.dirname(file), pluginDirectory, owner);
-          if (error) return error;
-          // Protocol types are shared host contracts, also exposed by the SDK's peer
-          // dependency during development. Erased imports need no plugin-local install;
-          // runtime imports still go through normal dependency resolution below.
-          if (typeOnly && specifier.startsWith("@getpaseo/protocol/")) continue;
-          // Host modules have separately enforced SDK boundaries and need no local installation.
-          if (
-            (PLUGIN_SDK_SPECIFIERS as readonly string[]).includes(specifier) ||
-            /^(zod|react|react-native|@tanstack\/react-query)(\/|$)/.test(specifier) ||
-            isBuiltin(specifier) ||
-            packageSpecifier === "@types/node"
-          )
-            continue;
-          const dependencyFiles = await resolveImportFiles(file, specifier, kind, typeOnly);
-          for (const dependencyFile of dependencyFiles) {
-            const boundaryError = resolvedBoundaryError(dependencyFile, specifier, file, owner);
-            if (boundaryError) return boundaryError;
-            const dependencyError = await checkSourceImports(dependencyFile, owner);
-            if (dependencyError) return dependencyError;
-          }
-        }
-        return null;
-      }
-      buildContext.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) =>
-        checkSourceImports(args.path, target),
-      );
-      buildContext.onResolve({ filter: /.*/ }, async (args) => {
-        if (args.kind === "entry-point") return null;
-        if (args.pluginData === boundaryResolution) return null;
-        const importer =
-          args.namespace === "file" ? realpathSync.native(args.importer) : args.importer;
-        const resolveDir = args.namespace === "file" ? path.dirname(importer) : args.resolveDir;
-        const owner = directoryTarget(importer, pluginDirectory) === "shared" ? "shared" : target;
-        const specifierError = runtimeSpecifierError(args.path, owner, importer);
-        if (specifierError) return specifierError;
-        const lexicalError = lexicalBoundaryError(args.path, resolveDir, pluginDirectory, owner);
-        if (lexicalError) return lexicalError;
-        const resolution = await buildContext.resolve(args.path, {
-          importer,
-          namespace: args.namespace,
-          resolveDir,
-          kind: args.kind,
-          pluginData: boundaryResolution,
-          with: args.with,
-        });
-        if (
-          resolution.errors.length > 0 ||
-          resolution.external ||
-          resolution.namespace !== "file"
-        ) {
-          return null;
-        }
-        return resolvedBoundaryError(resolution.path, args.path, importer, owner);
+        };
+        worker.on("error", onError);
+        worker.on("exit", onExit);
+        worker.on("message", onMessage);
+        worker.postMessage(task, []);
       });
-    },
-  };
-}
-
-function wrapCommonJsBundle(code: string): string {
-  return `(function(require) {\nconst module = { exports: {} };\nconst exports = module.exports;\n${code}\nreturn module.exports;\n})`;
-}
-
-function makeHermesInteropEager(code: string): string {
-  // Hermes evaluates esbuild's lazy CommonJS interop getters from a string with
-  // the final loop binding, so every named import can resolve to the last export.
-  // Plugin bundles execute once and do not need live bindings from host modules.
-  return code.replaceAll("get: () => from[key]", "value: from[key]");
-}
-
-function runtimeSpecifierError(
-  specifier: string,
-  target: PluginBuildTarget | "shared",
-  importer: string,
-): OnResolveResult | null {
-  let kind: string | null = null;
-  if (specifier === "@getpaseo/plugin/client/host") kind = "host-private";
-  else if (
-    (specifier === "@getpaseo/plugin" ||
-      specifier.startsWith("@getpaseo/plugin/") ||
-      specifier === "@paseo/plugin" ||
-      specifier.startsWith("@paseo/plugin/")) &&
-    !(PLUGIN_SDK_SPECIFIERS as readonly string[]).includes(specifier)
-  )
-    kind = "Unknown SDK";
-  else if (target !== "server" && (isBuiltin(specifier) || specifier === "@types/node"))
-    kind = "Node";
-  else if (target !== "server" && isPluginServerOnlySdkSpecifier(specifier)) kind = "server-only";
-  else if (
-    target !== "client" &&
-    (isPluginClientOnlySdkSpecifier(specifier) ||
-      /^((?:@types\/)?react(?:-dom|-native)?|use-sync-external-store|@tanstack\/react-query)(\/|$)/.test(
-        specifier,
-      ))
-  )
-    kind = "client-only";
-  return kind
-    ? {
-        errors: [
-          {
-            text: `${kind} module cannot be imported into the plugin ${target} bundle: ${specifier} imported by ${importer}`,
-          },
-        ],
-      }
-    : null;
-}
-
-function checkSharedDependencies(inputs: Metafile["inputs"], pluginDirectory: string): void {
-  function inputLocation(file: string): PluginModuleLocation | null {
-    const absolutePath = path.resolve(file);
-    // Metafile keys must stay unchanged for graph traversal. Only filesystem
-    // inputs have canonical paths; data URLs and external specifiers do not.
-    return directoryTarget(
-      existsSync(absolutePath) ? realpathSync.native(absolutePath) : absolutePath,
-      pluginDirectory,
-    );
-  }
-  const pending = Object.keys(inputs).filter((file) => inputLocation(file) === "shared");
-  const visited = new Set<string>();
-  while (pending.length) {
-    const file = pending.pop()!;
-    if (visited.has(file)) continue;
-    visited.add(file);
-    for (const dependency of inputs[file]?.imports ?? []) {
-      const location = dependency.external ? null : inputLocation(dependency.path);
-      const error =
-        runtimeSpecifierError(dependency.original ?? dependency.path, "shared", file) ??
-        (dependency.external
-          ? null
-          : moduleBoundaryError(
-              location === "invalid" ? null : location,
-              "shared",
-              dependency.path,
-            ));
-      if (error?.errors?.length) throw new Error(error.errors[0].text);
-      if (!dependency.external) pending.push(dependency.path);
+    } finally {
+      worker.off("message", onMessage!);
+      worker.off("error", onError!);
+      worker.off("exit", onExit!);
     }
   }
 }
 
-async function compileTarget(entryPath: string, target: PluginBuildTarget): Promise<string> {
-  const { build } = loadEsbuild();
-  // Use native canonical paths throughout: TypeScript expands Windows short names
-  // when resolving type references, while the JS realpath implementation retains them.
-  const pluginDirectory = realpathSync.native(path.dirname(entryPath));
-  const result = await build({
-    entryPoints: [realpathSync.native(entryPath)],
-    bundle: true,
-    format: "cjs",
-    jsx: "automatic",
-    // `import icon from "./icon.svg"` yields the markup for an inline `{ svg }` icon.
-    loader: { ".svg": "text" },
-    platform: target === "server" ? "node" : "neutral",
-    target: target === "server" ? "node20" : "es2020",
-    // The neutral platform reads no package.json entry fields, so packages without
-    // `exports` would not resolve. Read the same fields as esbuild's browser platform
-    // minus `browser`, since the bundle also runs in React Native.
-    mainFields: target === "client" ? ["module", "main"] : undefined,
-    // Metro lowers async syntax before Hermes sees app code. Plugin client bundles bypass Metro,
-    // so apply the same compatibility transform before the app evaluates them from source.
-    supported: target === "client" ? { "async-await": false } : undefined,
-    external:
-      target === "client"
-        ? [
-            ...PLUGIN_SDK_SPECIFIERS,
-            "@tanstack/react-query",
-            "react",
-            "react/jsx-runtime",
-            "react-native",
-            "zod",
-          ]
-        : SERVER_HOST_MODULES,
-    plugins: [createRuntimeBoundaryPlugin(target, pluginDirectory)],
-    metafile: true,
-    logLevel: "silent",
-    treeShaking: true,
-    write: false,
-  });
-  checkSharedDependencies(result.metafile.inputs, pluginDirectory);
-  const output = result.outputFiles[0]?.text;
-  if (!output) throw new Error(`Plugin ${target} compilation produced no output`);
-  return wrapCommonJsBundle(makeHermesInteropEager(output));
+const compiler = new PluginCompiler();
+
+export function runCompilerTask<T extends CompilerTask>(
+  task: T,
+  onLog?: (data: Record<string, unknown>, message: string) => void,
+): Promise<TaskResult[T["kind"]]> {
+  return compiler.run(task, onLog);
 }
 
-export async function compilePlugin(entryPaths: {
-  client: string | null;
-  server: string | null;
-}): Promise<{
-  clientBundle: string | null;
-  serverBundle: string | null;
-}> {
-  const [clientBundle, serverBundle] = await Promise.all([
-    entryPaths.client ? compileTarget(entryPaths.client, "client") : null,
-    entryPaths.server ? compileTarget(entryPaths.server, "server") : null,
-  ]);
-  return { clientBundle, serverBundle };
+export function compilePlugin(entries: Parameters<typeof build.compilePlugin>[0]) {
+  return runCompilerTask({ kind: "entries", entries });
+}
+
+export function compileDirectoryPlugin(directory: string, version: string, builtinId?: string) {
+  return runCompilerTask({ kind: "directory", directory, version, builtinId });
 }
diff --git a/packages/server/src/server/plugins/index.posix.test.ts b/packages/server/src/server/plugins/index.posix.test.ts
index 71fe2b96e9..5b6985a55e 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, 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);
-    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);
@@ -730,7 +813,7 @@ export default function contribute(server: PluginServerContext) {
         await service.stopAllPlugins();
       }
     },
-    30_000,
+    60_000,
   );
 
   it("keeps the running commit when a Git update build command fails", async () => {
@@ -1071,27 +1154,65 @@ 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 }),
     );
-    await service.start();
-    await service.installDirectory({ path: first });
-    await service.installDirectory({ path: second });
+    try {
+      await service.start();
+      await service.installDirectory({ path: first });
+      await service.installDirectory({ path: second });
+      expect(catalogIds(service)).toEqual(["first", "second"]);
+      await store.patch({ pluginsEnabled: false });
 
-    store.patch({ pluginsEnabled: false });
-
-    expect(service.catalog()).toEqual([]);
-    await expect(service.invokePluginRpc("second", "anything", {})).rejects.toThrow(
-      "Plugin is not available",
-    );
-    store.patch({ pluginsEnabled: true });
-    await service.reloadPlugin("first");
-    expect((await service.listPlugins()).map(({ id, status }) => ({ id, status }))).toEqual([
-      { id: "first", status: "running" },
-      { id: "second", status: "running" },
-    ]);
-    await service.stopAllPlugins();
+      expect(service.catalog()).toEqual([]);
+      await expect(service.invokePluginRpc("second", "anything", {})).rejects.toThrow(
+        "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
+        .poll(() => service.listPlugins(), { timeout: 10_000 })
+        .toMatchObject([
+          { id: "first", status: "running" },
+          { id: "second", status: "running" },
+        ]);
+    } finally {
+      finishCleanup();
+      await service.stopAllPlugins();
+    }
   }, 20_000);
 
   it("does not publish an in-flight start after a later global disable", async () => {
@@ -1100,16 +1221,16 @@ export default function contribute(plugin: unknown) {
     const store = createStore(home, {
       slow: { source: "directory", path: "/plugins/slow", enabled: true },
     });
-    store.patch({ pluginsEnabled: false });
+    await store.patch({ pluginsEnabled: false });
     const paused = createPausedRuntime();
     const service = new PluginService(pino({ level: "silent" }), store, "0.4.0", {
       runtime: paused.runtime,
     });
     await service.start();
 
-    store.patch({ pluginsEnabled: true });
+    await store.patch({ pluginsEnabled: true });
     await paused.started;
-    store.patch({ pluginsEnabled: false });
+    await store.patch({ pluginsEnabled: false });
     paused.releaseStart();
     await service.stopAllPlugins();
 
@@ -1119,6 +1240,47 @@ export default function contribute(plugin: unknown) {
     ]);
   });
 
+  it("persists overlapping enable and disable without losing either source mutation", async () => {
+    const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
+    roots.push(home);
+    const store = createStore(home, {
+      a: { source: "directory", path: "/plugins/a", enabled: false },
+      b: { source: "directory", path: "/plugins/b", enabled: true },
+    });
+    const paused = createPluginSelectivePausedRuntime("unused");
+    const service = new PluginService(pino({ level: "silent" }), store, "0.4.0", {
+      runtime: paused.runtime,
+    });
+    await service.start();
+    await Promise.all([service.enablePlugin("a"), service.disablePlugin("b")]);
+    expect(store.get().plugins).toEqual({
+      a: { source: "directory", path: "/plugins/a", enabled: true },
+      b: { source: "directory", path: "/plugins/b", enabled: false },
+    });
+    await service.stopAllPlugins();
+  });
+
+  it("clears a failed disable intent so the previous enabled state can publish", async () => {
+    const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
+    roots.push(home);
+    const store = createStore(home, {
+      slow: { source: "directory", path: "/plugins/slow", enabled: false },
+    });
+    const paused = createPausedRuntime();
+    const service = new PluginService(pino({ level: "silent" }), store, "0.4.0", {
+      runtime: paused.runtime,
+    });
+    await service.start();
+    const enabling = service.enablePlugin("slow");
+    await paused.started;
+    await writeFile(path.join(home, "config.json"), "invalid JSON");
+    await expect(service.disablePlugin("slow")).rejects.toThrow("Invalid JSON");
+    paused.releaseStart();
+    await expect(enabling).resolves.toMatchObject({ enabled: true, status: "running" });
+    expect(service.catalog()).toEqual([{ id: "slow", clientBundle: "bundle" }]);
+    await service.stopAllPlugins();
+  });
+
   it("does not publish an in-flight enable after a later plugin disable", async () => {
     const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
     roots.push(home);
@@ -1279,8 +1441,111 @@ 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", () => {
-  it("preserves dependencies and metadata, and reloads without npm", async () => {
+  let registry: Awaited<ReturnType<typeof startNpmRegistry>>;
+
+  // Give real npm fixture construction its own setup budget so it does not consume
+  // the installation journey on Windows.
+  beforeAll(async () => {
     const packages = npmPluginPackages();
     const fixture = packages[1];
     packages.push({ ...fixture, version: "2.0.0", tags: ["future"] });
@@ -1315,7 +1580,7 @@ describe("npm plugin installation", () => {
     for (const [name, overrides] of failures) {
       failedPackages.push({ ...fixture, name, files: { ...fixture.files, ...overrides } });
     }
-    const registry = await startNpmRegistry([
+    registry = await startNpmRegistry([
       ...packages,
       {
         name: "paseo-prepared-plugin",
@@ -1345,6 +1610,9 @@ export default function contribute() {
       },
       ...failedPackages,
     ]);
+  }, 120_000);
+
+  it("preserves dependencies and metadata, and reloads without npm", async () => {
     const home = await mkdtemp(path.join(tmpdir(), "paseo-npm-service-"));
     roots.push(home);
     const previousConfig = process.env.npm_config_userconfig;
diff --git a/packages/server/src/server/plugins/index.ts b/packages/server/src/server/plugins/index.ts
index a5ecea8097..c3ffb6bef2 100644
--- a/packages/server/src/server/plugins/index.ts
+++ b/packages/server/src/server/plugins/index.ts
@@ -1,3 +1,4 @@
+import type { PluginAgentToolsRuntime } from "./agent-tools.js";
 import type { PluginLifecycle } from "./lifecycle/index.js";
 import path from "node:path";
 import { stat, rm } from "node:fs/promises";
@@ -24,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";
@@ -37,11 +39,17 @@ import type { PluginUsageSourceMetadata } from "./plugin-process-protocol.js";
 const BUILTIN_PROVIDER_ID_SET: ReadonlySet<string> = new Set(BUILTIN_PROVIDER_IDS);
 
 interface PluginRuntimePort {
+  subscribeSessionOpenChanges?: PluginRuntime["subscribeSessionOpenChanges"];
+  isToolPluginAvailable?: PluginRuntime["isToolPluginAvailable"];
+  callTool?: PluginRuntime["callTool"];
+  detachTools?: PluginRuntime["detachTools"];
   emit?: PluginLifecycle["emit"];
   drainEvents?: PluginRuntime["drainEvents"];
   before?: PluginLifecycle["before"];
+  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[];
@@ -92,6 +100,10 @@ export class PluginService {
   private readonly providerListeners = new Set<() => void>();
   private lifecycle = Promise.resolve();
   private globalStartsBlocked = true;
+  private readonly pendingOperations = new Map<
+    string,
+    { kind: "disable" | "remove"; completion: Promise<void> }
+  >();
   private started = false;
   private readonly settingsListeners = new Set<(pluginId: string, settingsId: string) => void>();
 
@@ -131,6 +143,38 @@ export class PluginService {
     this.runtime.emit?.(name, event);
   };
 
+  subscribeSessionOpenChanges(listener: () => void): () => void {
+    return this.runtime.subscribeSessionOpenChanges?.(listener) ?? (() => {});
+  }
+
+  readonly isToolPluginAvailable: PluginAgentToolsRuntime["isToolPluginAvailable"] = (
+    pluginId,
+    pluginInstanceId,
+  ) => {
+    return this.runtime.isToolPluginAvailable?.(pluginId, pluginInstanceId) ?? false;
+  };
+
+  readonly detachTools: PluginAgentToolsRuntime["detachTools"] = (agentId) => {
+    this.runtime.detachTools?.(agentId);
+  };
+
+  readonly callTool: PluginAgentToolsRuntime["callTool"] = async (
+    pluginId,
+    pluginInstanceId,
+    agent,
+    name,
+    input,
+    signal,
+  ) => {
+    if (!this.isToolPluginAvailable(pluginId, pluginInstanceId) || !this.runtime.callTool)
+      return { isError: true, text: `Plugin is not available: ${pluginId}` };
+    return this.runtime.callTool(pluginId, pluginInstanceId, agent, name, input, signal);
+  };
+
+  readonly wait: PluginLifecycle["wait"] = async (name, payload) => {
+    await this.runtime.wait?.(name, payload);
+  };
+
   async drainEvents(): Promise<void> {
     await this.runtime.drainEvents?.();
   }
@@ -188,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);
@@ -265,11 +316,7 @@ export class PluginService {
           `Plugin ID "${pluginId}" is already configured; choose another ID with --id`,
         );
       }
-      const sources = {
-        ...this.configStore.get().plugins,
-        [pluginId]: { source: "directory" as const, path: directory, enabled: true },
-      };
-      this.configStore.patch({ plugins: sources });
+      await this.patchSource(pluginId, { source: "directory", path: directory, enabled: true });
       if (this.canPublish(pluginId)) await this.startConfigured(pluginId);
       this.notify(pluginId);
       const installed = await this.requireItem(pluginId);
@@ -328,15 +375,17 @@ export class PluginService {
         await managedSources.discard(candidate);
         throw error;
       }
-      this.patchSource(pluginId, { source: "directory", path: candidate.directory, enabled: true });
+      await this.patchSource(pluginId, {
+        source: "directory",
+        path: candidate.directory,
+        enabled: true,
+      });
       try {
         if (this.canPublish(pluginId)) await this.startExplicit(pluginId, candidate.directory);
         managedSources.commit(pluginId, candidate.record);
       } catch (error) {
         await this.stopPlugin(pluginId);
-        const sources = { ...this.configStore.get().plugins };
-        delete sources[pluginId];
-        this.configStore.patch({ plugins: sources });
+        await this.removeSource(pluginId);
         await managedSources.discard(candidate);
         this.errors.delete(pluginId);
         this.notify(pluginId);
@@ -428,10 +477,11 @@ export class PluginService {
   }
 
   async enablePlugin(pluginId: string): Promise<PluginListItem> {
-    const source = this.requireSource(pluginId);
-    this.patchSource(pluginId, { ...source, enabled: true });
+    await this.patchSource(pluginId, (source) => ({ ...source, enabled: true }));
     this.errors.delete(pluginId);
     return this.enqueue(async () => {
+      // Cancellation persistence uses the store queue, so it never waits behind a blocked start.
+      await this.pendingOperations.get(pluginId)?.completion.catch(() => {});
       const current = this.requireSource(pluginId);
       if (current.enabled !== false && this.configStore.get().pluginsEnabled === true) {
         await this.startExplicit(pluginId, current.path);
@@ -442,8 +492,17 @@ export class PluginService {
   }
 
   async disablePlugin(pluginId: string): Promise<PluginListItem> {
-    const source = this.requireSource(pluginId);
-    this.patchSource(pluginId, { ...source, enabled: false });
+    const operation = {
+      kind: "disable",
+      completion: this.patchSource(pluginId, (source) => ({ ...source, enabled: false })),
+    } as const;
+    this.pendingOperations.set(pluginId, operation);
+    try {
+      await operation.completion;
+    } finally {
+      if (this.pendingOperations.get(pluginId) === operation)
+        this.pendingOperations.delete(pluginId);
+    }
     const stopping = this.stopPlugin(pluginId);
     return this.enqueue(async () => {
       await stopping;
@@ -455,10 +514,15 @@ export class PluginService {
 
   async removePlugin(pluginId: string): Promise<void> {
     this.requireSource(pluginId);
+    const operation = { kind: "remove", completion: this.removeSource(pluginId) } as const;
+    this.pendingOperations.set(pluginId, operation);
+    try {
+      await operation.completion;
+    } finally {
+      if (this.pendingOperations.get(pluginId) === operation)
+        this.pendingOperations.delete(pluginId);
+    }
     const stopping = this.stopPlugin(pluginId);
-    const sources = { ...this.configStore.get().plugins };
-    delete sources[pluginId];
-    this.configStore.patch({ plugins: sources });
     await this.enqueue(async () => {
       await stopping;
       this.runtime.clearLogs(pluginId);
@@ -477,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();
@@ -505,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);
     }
@@ -531,6 +599,7 @@ export class PluginService {
   private canPublish(pluginId: string): boolean {
     const config = this.configStore.get();
     return (
+      !this.pendingOperations.has(pluginId) &&
       !this.globalStartsBlocked &&
       config.pluginsEnabled === true &&
       config.plugins?.[pluginId]?.enabled !== false &&
@@ -538,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);
@@ -744,7 +818,10 @@ export class PluginService {
       await managedSources.discard(candidate);
       throw new Error(`Plugin is no longer configured: ${pluginId}`);
     }
-    this.patchSource(pluginId, { ...activatedSource, path: candidate.directory });
+    await this.patchSource(pluginId, (currentSource) => ({
+      ...currentSource,
+      path: candidate.directory,
+    }));
     this.errors.delete(pluginId);
     this.notify(pluginId);
     let warning: string | undefined;
@@ -786,9 +863,28 @@ export class PluginService {
     return source;
   }
 
-  private patchSource(pluginId: string, source: PluginSource): void {
-    this.configStore.patch({
-      plugins: { ...this.configStore.get().plugins, [pluginId]: source },
+  private async patchSource(
+    pluginId: string,
+    update: PluginSource | ((source: PluginSource) => PluginSource),
+  ): Promise<void> {
+    await this.configStore.patch((current) => {
+      const source = current.plugins?.[pluginId];
+      if (typeof update === "function" && !source)
+        throw new Error(`Plugin is not configured: ${pluginId}`);
+      return {
+        plugins: {
+          ...current.plugins,
+          [pluginId]: typeof update === "function" ? update(source!) : update,
+        },
+      };
+    });
+  }
+
+  private async removeSource(pluginId: string): Promise<void> {
+    await this.configStore.patch((current) => {
+      const sources = { ...current.plugins };
+      delete sources[pluginId];
+      return { plugins: sources };
     });
   }
 
diff --git a/packages/server/src/server/plugins/lifecycle-archive.e2e.test.ts b/packages/server/src/server/plugins/lifecycle-archive.e2e.test.ts
index 6f3d8661e7..1b05b56b53 100644
--- a/packages/server/src/server/plugins/lifecycle-archive.e2e.test.ts
+++ b/packages/server/src/server/plugins/lifecycle-archive.e2e.test.ts
@@ -8,8 +8,11 @@ import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
 
 test("closing and archiving agents publish their distinct lifecycle hooks once", async () => {
   const directory = await mkdtemp(path.join(tmpdir(), "paseo-archive-hooks-"));
-  const daemon = await createTestPaseoDaemon({ daemonVersion: "0.8.0" });
-  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.8.0" });
+  const daemon = await createTestPaseoDaemon({ daemonVersion: "0.14.0-beta.1" });
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    appVersion: "0.14.0-beta.1",
+  });
   try {
     await client.connect();
     await client.fetchAgents({ subscribe: {} });
@@ -39,7 +42,7 @@ test("closing and archiving agents publish their distinct lifecycle hooks once",
       .poll(async () => {
         const logs = await client.getPluginLogs("lifecycle-logger");
         return logs
-          .filter((entry) => entry.message.startsWith('{"hook":"agent.closed"'))
+          .filter((entry) => entry.message.startsWith('{"hook":"agent.close.after"'))
           .map((entry) => JSON.parse(entry.message).data.agent.id);
       })
       .toEqual([closed.id]);
@@ -49,7 +52,7 @@ test("closing and archiving agents publish their distinct lifecycle hooks once",
         const logs = await client.getPluginLogs("lifecycle-logger");
         return logs
           .filter((entry) => {
-            return entry.message.startsWith('{"hook":"agent.archived"');
+            return entry.message.startsWith('{"hook":"agent.archive.after"');
           })
           .map((entry) => {
             return JSON.parse(entry.message).data.agent.id;
@@ -61,7 +64,7 @@ test("closing and archiving agents publish their distinct lifecycle hooks once",
       .poll(async () => {
         const logs = await client.getPluginLogs("lifecycle-logger");
         return logs
-          .filter((entry) => entry.message.startsWith('{"hook":"agent.closed"'))
+          .filter((entry) => entry.message.startsWith('{"hook":"agent.close.after"'))
           .map((entry) => JSON.parse(entry.message).data.agent.id)
           .sort();
       })
@@ -75,20 +78,23 @@ test("closing and archiving agents publish their distinct lifecycle hooks once",
 
 test("daemon shutdown lets agent close hooks finish before stopping plugins", async () => {
   const directory = await mkdtemp(path.join(tmpdir(), "paseo-close-hook-shutdown-"));
-  const daemon = await createTestPaseoDaemon({ daemonVersion: "0.8.0" });
-  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.8.0" });
+  const daemon = await createTestPaseoDaemon({ daemonVersion: "0.14.0-beta.1" });
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    appVersion: "0.14.0-beta.1",
+  });
   const completedFile = path.join(directory, "closed.txt");
   try {
     await writeFile(
       path.join(directory, "paseo-plugin.json"),
-      JSON.stringify({ id: "close-hook-shutdown", requirements: { paseo: ">=0.8.0" } }),
+      JSON.stringify({ id: "close-hook-shutdown", requirements: { paseo: ">=0.14.0-beta.1" } }),
     );
     await writeFile(
       path.join(directory, "index.server.ts"),
       `import { writeFile } from "node:fs/promises";
 import { setTimeout } from "node:timers/promises";
 export default function contribute(server) {
-  server.on("agent.closed", async (event, context) => {
+  server.addHook("agent.close.after", async (event, context) => {
     await setTimeout(200, undefined, { signal: context.signal });
     await writeFile(${JSON.stringify(completedFile)}, event.agent.id);
   });
diff --git a/packages/server/src/server/plugins/lifecycle.e2e.test.ts b/packages/server/src/server/plugins/lifecycle.e2e.test.ts
index 9c75f63746..bd1dfa8859 100644
--- a/packages/server/src/server/plugins/lifecycle.e2e.test.ts
+++ b/packages/server/src/server/plugins/lifecycle.e2e.test.ts
@@ -1,4 +1,5 @@
-import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { cp, mkdir, mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -6,6 +7,7 @@ import { expect, onTestFinished, test } from "vitest";
 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";
 
 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-"));
@@ -74,6 +76,76 @@ export default function contribute(server) {
   }
 }, 60_000);
 
+test("addHook transforms workspace creation once across receipt replays and observes its committed lifecycle", async () => {
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-lifecycle-"));
+  const daemon = await createTestPaseoDaemon({ daemonVersion: "0.8.0" });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.8.0" });
+  try {
+    await writeFile(
+      path.join(directory, "paseo-plugin.json"),
+      JSON.stringify({ id: "lifecycle", requirements: { paseo: ">=0.8.0" } }),
+    );
+    await writeFile(
+      path.join(directory, "index.server.ts"),
+      `
+export default function contribute(server) {
+  server.addHook("workspace.create.before", async ({ request }) => {
+    console.log(JSON.stringify({ hook: "workspace.before" }));
+    return { ...request, title: "Created through a hook" };
+  });
+  server.addHook("workspace.create.after", async (event) => {
+    console.log(JSON.stringify({ hook: "workspace.create.after", event }));
+  });
+  server.addHook("workspace.archive.after", async (event) => {
+    console.log(JSON.stringify({ hook: "workspace.archive.after", event }));
+  });
+  return () => {};
+}
+`,
+    );
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(directory);
+    const created = await client.createWorkspace({
+      idempotencyKey: "plugin-workspace",
+      source: { kind: "directory", path: directory },
+    });
+    expect(created.workspace?.name).toBe("Created through a hook");
+    const workspaceId = created.workspace!.id;
+    const replay = await client.createWorkspace({
+      idempotencyKey: "plugin-workspace",
+      source: { kind: "directory", path: directory },
+    });
+    expect(replay.error).toBeNull();
+    expect(replay.workspace?.id).toBe(workspaceId);
+    await client.archiveWorkspace(workspaceId);
+    await expect
+      .poll(async () => {
+        const logs = await client.getPluginLogs("lifecycle");
+        return logs
+          .filter((entry) => {
+            return entry.message.startsWith('{"hook":');
+          })
+          .map((entry) => {
+            return JSON.parse(entry.message);
+          });
+      })
+      .toMatchObject([
+        { hook: "workspace.before" },
+        {
+          hook: "workspace.create.after",
+          event: { workspace: { id: workspaceId, cwd: directory } },
+        },
+        { hook: "workspace.archive.after", event: { workspace: { id: workspaceId } } },
+      ]);
+  } finally {
+    await client.close();
+    await daemon.close();
+    await rm(directory, { recursive: true, force: true });
+  }
+}, 60_000);
+
 test("plugins observe turns, answer permissions, and observe archive without blocking the agent", async () => {
   const directory = await mkdtemp(path.join(tmpdir(), "paseo-turn-hooks-"));
   const daemon = await createTestPaseoDaemon({ daemonVersion: "0.8.0" });
@@ -87,24 +159,24 @@ test("plugins observe turns, answer permissions, and observe archive without blo
       path.join(directory, "index.server.ts"),
       `
 export default function contribute(server) {
-  server.on("agent.turn_started", (event) => {
-    console.log(JSON.stringify({ hook: "agent.turn_started", event }));
+  server.addHook("agent.turn.before", async (event) => {
+    console.log(JSON.stringify({ hook: "agent.turn.before", event }));
   });
-  server.on("agent.turn_ended", (event) => {
-    console.log(JSON.stringify({ hook: "agent.turn_ended", event }));
+  server.addHook("agent.turn.after", async (event) => {
+    console.log(JSON.stringify({ hook: "agent.turn.after", event }));
   });
-  server.on("agent.permission_requested", async (event, context) => {
-    console.log(JSON.stringify({ hook: "agent.permission_requested", event }));
+  server.addHook("agent.permission.before", async (event, context) => {
+    console.log(JSON.stringify({ hook: "agent.permission.before", event }));
     await context.paseo.agents.ref(event.agent.id).respondToPermission({
       requestId: event.request.id,
       response: { behavior: "deny", message: "Declined by plugin" },
     });
   });
-  server.on("agent.permission_resolved", (event) => {
-    console.log(JSON.stringify({ hook: "agent.permission_resolved", event }));
+  server.addHook("agent.permission.after", async (event) => {
+    console.log(JSON.stringify({ hook: "agent.permission.after", event }));
   });
-  server.on("agent.archived", (event) => {
-    console.log(JSON.stringify({ hook: "agent.archived", event }));
+  server.addHook("agent.archive.after", async (event) => {
+    console.log(JSON.stringify({ hook: "agent.archive.after", event }));
   });
   return () => {};
 }
@@ -139,16 +211,16 @@ export default function contribute(server) {
         { timeout: 10_000 },
       )
       .toMatchObject([
+        { hook: "agent.permission.after", event: { resolution: { behavior: "deny" } } },
         {
-          hook: "agent.permission_requested",
+          hook: "agent.permission.before",
           event: { request: { input: { command: "rm -f permission.txt" } } },
         },
-        { hook: "agent.permission_resolved", event: { resolution: { behavior: "deny" } } },
         {
-          hook: "agent.turn_ended",
+          hook: "agent.turn.after",
           event: { outcome: { kind: "completed" }, timeline: [] },
         },
-        { hook: "agent.turn_started", event: { agent: { id: agent.id } } },
+        { hook: "agent.turn.before", event: { agent: { id: agent.id } } },
       ]);
     const page = await client.fetchAgentTimeline(agent.id, { direction: "tail", limit: 20 });
     expect(page.entries.length).toBeGreaterThan(0);
@@ -157,7 +229,7 @@ export default function contribute(server) {
       .poll(async () => {
         const logs = await client.getPluginLogs("turn-hooks");
         return logs.filter((entry) => {
-          return entry.message.startsWith('{"hook":"agent.archived"');
+          return entry.message.startsWith('{"hook":"agent.archive.after"');
         }).length;
       })
       .toBe(1);
@@ -170,44 +242,41 @@ export default function contribute(server) {
 
 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 daemon = await createTestPaseoDaemon({ daemonVersion: "0.8.0" });
-  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.8.0" });
-  try {
-    await writeFile(
-      path.join(directory, "paseo-plugin.json"),
-      JSON.stringify({ id: "agent-hooks", requirements: { paseo: ">=0.8.0" } }),
-    );
-    await writeFile(
-      path.join(directory, "index.server.ts"),
-      `
-export default function contribute(server) {
-  server.before("agent.create", ({ request }) => {
-    return { ...request, config: { ...request.config, provider: "codex" }, env: { ...request.env, HOOK_CREATE: "created" } };
+  const pluginDirectory = await createProviderPlugin(directory, {
+    acknowledgeClose: true,
+    hooks: `
+  server.addHook("agent.create.before", async ({ request }) => {
+    return { ...request, config: { ...request.config, provider: "${PROVIDER_ID}", model: "shutdown-model" }, env: { ...request.env, HOOK_CREATE: "created" } };
   });
-  server.before("agent.session_open", ({ request }) => {
-    console.log(JSON.stringify({ hook: "agent.session_open", request }));
+  server.addHook("agent.open.before", async ({ request }) => {
+    console.log(JSON.stringify({ hook: "agent.open.before", request }));
     return { ...request, env: { ...request.env, HOOK_OPEN: "opened" } };
   });
-  server.on("agent.created", (event) => {
-    console.log(JSON.stringify({ hook: "agent.created", event }));
+  server.addHook("agent.create.after", async (event) => {
+    console.log(JSON.stringify({ hook: "agent.create.after", event }));
+  });`,
+    reportOpen: true,
   });
-  return () => {};
-}
-`,
-    );
+  const daemon = await createTestPaseoDaemon();
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
     await client.connect();
     await client.fetchAgents({ subscribe: {} });
     await client.patchDaemonConfig({ pluginsEnabled: true });
-    await client.installDirectoryPlugin(directory);
+    await client.installDirectoryPlugin(pluginDirectory);
     const agent = await client.createAgent({
       provider: "claude",
       cwd: directory,
       title: "Hook test",
     });
-    expect(agent.provider).toBe("codex");
+    expect(agent.provider).toBe(PROVIDER_ID);
+    expect(await daemon.daemon.agentStorage.get(agent.id)).toMatchObject({
+      provider: PROVIDER_ID,
+      config: { model: "shutdown-model" },
+    });
     await expect
       .poll(async () => {
-        const logs = await client.getPluginLogs("agent-hooks");
+        const logs = await client.getPluginLogs("shutdown-provider-plugin");
         return logs
           .filter((entry) => {
             return entry.message.startsWith('{"hook":');
@@ -218,10 +287,17 @@ export default function contribute(server) {
       })
       .toMatchObject([
         {
-          hook: "agent.session_open",
+          hook: "agent.open.before",
           request: { agentId: agent.id, env: { HOOK_CREATE: "created" } },
         },
-        { hook: "agent.created", event: { agent: { id: agent.id, provider: "codex" } } },
+        {
+          hook: "provider.open",
+          config: { env: { HOOK_CREATE: "created", HOOK_OPEN: "opened" } },
+        },
+        {
+          hook: "agent.create.after",
+          event: { agent: { id: agent.id, provider: PROVIDER_ID } },
+        },
       ]);
     await client.archiveAgent(agent.id);
   } finally {
@@ -244,10 +320,10 @@ test("invalid output from an untyped plugin rejects creation before later callba
       path.join(directory, "index.server.ts"),
       `
 export default function contribute(server) {
-  server.before("workspace.create", () => {
+  server.addHook("workspace.create.before", async () => {
     return { source: { kind: "worktree", branchName: 42 } };
   });
-  server.before("workspace.create", ({ request }) => {
+  server.addHook("workspace.create.before", async ({ request }) => {
     console.log("Unexpected later callback");
     return request;
   });
@@ -260,7 +336,7 @@ export default function contribute(server) {
     await client.installDirectoryPlugin(directory);
     const result = await client.createWorkspace({ source: { kind: "directory", path: directory } });
     expect(result.workspace).toBeNull();
-    expect(result.error).toContain("Plugin invalid-hook before workspace.create failed");
+    expect(result.error).toContain("Plugin invalid-hook workspace.create.before failed");
     const logs = await client.getPluginLogs("invalid-hook");
     expect(
       logs.some((entry) => {
@@ -278,7 +354,9 @@ const PROVIDER_ID = "shutdown-provider";
 
 async function createProviderPlugin(
   root: string,
-  options: { acknowledgeClose: boolean } = { acknowledgeClose: true },
+  options: { acknowledgeClose: boolean; hooks?: string; reportOpen?: boolean } = {
+    acknowledgeClose: true,
+  },
 ): Promise<string> {
   const directory = path.join(root, "plugin");
   await mkdir(directory, { recursive: true });
@@ -324,6 +402,7 @@ const provider: ProviderRegistration = {
           return;
         }
         if (input.type === "session.open") {
+          if (${JSON.stringify(options.reportOpen ?? false)}) console.log(JSON.stringify({ hook: "provider.open", config: input.config }));
           emit({
             type: "session.opened",
             requestId: input.requestId,
@@ -375,6 +454,7 @@ const provider: ProviderRegistration = {
 
 export default function contribute(server: { registerProvider(p: ProviderRegistration): void }) {
   server.registerProvider(provider);
+${options.hooks ?? ""}
   return () => undefined;
 }`,
   );
@@ -383,7 +463,7 @@ export default function contribute(server: { registerProvider(p: ProviderRegistr
 
 test("a clean daemon shutdown leaves a completed plugin-provider agent without an error", async () => {
   const root = await mkdtemp(path.join(tmpdir(), "plugin-provider-shutdown-"));
-  onTestFinished(() => rm(root, { recursive: true, force: true }));
+  onTestFinished(() => rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }));
   const pluginDirectory = await createProviderPlugin(root);
   const workspace = path.join(root, "workspace");
   await mkdir(workspace, { recursive: true });
@@ -427,7 +507,7 @@ test("a clean daemon shutdown leaves a completed plugin-provider agent without a
 
 test("reloading a plugin leaves a completed plugin-provider agent without an error", async () => {
   const root = await mkdtemp(path.join(tmpdir(), "plugin-provider-reload-"));
-  onTestFinished(() => rm(root, { recursive: true, force: true }));
+  onTestFinished(() => rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }));
   const pluginDirectory = await createProviderPlugin(root);
   const workspace = path.join(root, "workspace");
   await mkdir(workspace, { recursive: true });
@@ -476,7 +556,7 @@ test("reloading a plugin leaves a completed plugin-provider agent without an err
 
 test("a provider that never acknowledges session.close does not hold the daemon open", async () => {
   const root = await mkdtemp(path.join(tmpdir(), "plugin-provider-stuck-close-"));
-  onTestFinished(() => rm(root, { recursive: true, force: true }));
+  onTestFinished(() => rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }));
   const pluginDirectory = await createProviderPlugin(root, { acknowledgeClose: false });
   const workspace = path.join(root, "workspace");
   await mkdir(workspace, { recursive: true });
@@ -586,3 +666,644 @@ test("reloading a plugin does not send on a closed IPC channel", async () => {
     await rm(pluginDirectory, { recursive: true, force: true });
   }
 }, 60_000);
+
+test("waiting hook failures reject the operation while notification failures are logged and later handlers run", async () => {
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-hook-failures-"));
+  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: "hook-failures",
+        requirements: { paseo: ">=0.14.0-beta.1" },
+      }),
+    );
+    await writeFile(
+      path.join(directory, "index.server.ts"),
+      `
+export default function contribute(server) {
+  server.addHook("workspace.create.before", async ({ request }) => {
+    if (request.title === "reject") throw new Error("waiting hook rejected");
+    return request;
+  });
+  server.addHook("workspace.create.after", async () => {
+    throw new Error("notification rejected");
+  });
+  server.addHook("workspace.create.after", async ({ workspace }) => {
+    console.log("Later notification for " + workspace.id);
+  });
+  return () => {};
+}`,
+    );
+    await client.connect();
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(directory);
+    const failed = await client.createWorkspace({
+      title: "reject",
+      source: { kind: "directory", path: directory },
+    });
+    expect(failed.workspace).toBeNull();
+    expect(failed.error).toContain(
+      "Plugin hook-failures workspace.create.before failed: waiting hook rejected",
+    );
+    const created = await client.createWorkspace({
+      source: { kind: "directory", path: directory },
+    });
+    expect(created.error).toBeNull();
+    expect(created.workspace?.workspaceDirectory).toBe(directory);
+    await expect
+      .poll(async () =>
+        (await client.getPluginLogs("hook-failures")).map(({ message }) => message).join("\n"),
+      )
+      .toContain("Later notification for " + created.workspace!.id);
+    const messages = (await client.getPluginLogs("hook-failures"))
+      .map(({ message }) => message)
+      .join("\n");
+    expect(messages).toContain("Lifecycle hook workspace.create.after failed");
+    expect(messages).toContain("notification rejected");
+    expect(messages).toContain("Later notification for " + created.workspace!.id);
+  } finally {
+    await client.close();
+    await daemon.close();
+    await rm(directory, { recursive: true, force: true });
+  }
+}, 60_000);
+
+test.each([false, true])(
+  "worktree creation waits for plugins before its first agent and rolls back failures (firstAgentContext: %s)",
+  async (withFirstAgentContext) => {
+    const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-hook-"));
+    const repository = path.join(root, "repository");
+    execFileSync("git", ["init", "-b", "main", repository], { stdio: "pipe" });
+    execFileSync(
+      "git",
+      [
+        "-c",
+        "user.name=Test",
+        "-c",
+        "user.email=test@example.com",
+        "-c",
+        "commit.gpgsign=false",
+        "commit",
+        "--allow-empty",
+        "-m",
+        "initial",
+      ],
+      { cwd: repository, stdio: "pipe" },
+    );
+    execFileSync("git", ["checkout", "-b", "plugin-base"], { cwd: repository, stdio: "pipe" });
+    await writeFile(path.join(repository, "from-plugin-base.txt"), "base");
+    execFileSync("git", ["add", "."], { cwd: repository, stdio: "pipe" });
+    execFileSync(
+      "git",
+      [
+        "-c",
+        "user.name=Test",
+        "-c",
+        "user.email=test@example.com",
+        "-c",
+        "commit.gpgsign=false",
+        "commit",
+        "-m",
+        "plugin base",
+      ],
+      { cwd: repository, stdio: "pipe" },
+    );
+    execFileSync("git", ["checkout", "main"], { cwd: repository, stdio: "pipe" });
+    const orderFile = path.join(root, "order.jsonl");
+    const pluginDirectory = await createProviderPlugin(root, {
+      acknowledgeClose: true,
+      hooks: `
+  server.addHook("worktree.create.before", async ({ request }) => {
+    const { appendFile } = await import("node:fs/promises");
+    await appendFile(${JSON.stringify(orderFile)}, JSON.stringify({ hook: "worktree.create.before", request }) + "\\n");
+    return { ...request, path: ${JSON.stringify(path.join(root, "elsewhere"))} + "/" + request.slug,
+      branch: request.branch === "accept-hook" ? "plugin-branch" : request.branch,
+      baseRef: request.branch === "accept-hook" ? "plugin-base" : request.baseRef };
+  });
+  server.addHook("worktree.create.after", async ({ worktree }) => {
+    const { appendFile, writeFile } = await import("node:fs/promises");
+    await appendFile(${JSON.stringify(orderFile)}, JSON.stringify({ hook: "worktree.create.after", worktree }) + "\\n");
+    if (worktree.branch === "reject-hook") throw new Error("worktree rejected");
+    await writeFile(worktree.path + "/plugin-ready.txt", "ready");
+  });
+  server.addHook("workspace.create.after", async () => {
+    const { appendFile } = await import("node:fs/promises");
+    await appendFile(${JSON.stringify(orderFile)}, JSON.stringify({ hook: "workspace.create.after" }) + "\\n");
+  });
+  server.addHook("agent.create.before", async ({ request }) => {
+    const { appendFile } = await import("node:fs/promises");
+    await appendFile(${JSON.stringify(orderFile)}, JSON.stringify({ hook: "agent.create.before" }) + "\\n");
+    return request;
+  });
+  server.addHook("agent.open.before", async ({ request }) => {
+    const { readFile } = await import("node:fs/promises");
+    const contents = await readFile(request.cwd + "/plugin-ready.txt", "utf8");
+    if (contents !== "ready") throw new Error("missing plugin output");
+    console.log(JSON.stringify({ hook: "first-agent-ready", agentId: request.agentId, cwd: request.cwd, contents }));
+    return request;
+  });`,
+    });
+    let daemon = await createTestPaseoDaemon({
+      paseoHomeRoot: path.join(root, "state"),
+      cleanup: false,
+    });
+    let client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+    try {
+      await client.connect();
+      await client.patchDaemonConfig({ pluginsEnabled: true });
+      const installed = await client.installDirectoryPlugin(pluginDirectory);
+      expect(installed.status).toBe("running");
+      const created = await client.createWorkspace({
+        ...(withFirstAgentContext
+          ? {
+              firstAgentContext: { prompt: "Check the initialized worktree" },
+              agent: {
+                provider: PROVIDER_ID,
+                cwd: repository,
+                initialPrompt: "Check the initialized worktree",
+              },
+            }
+          : {}),
+        source: {
+          kind: "worktree",
+          cwd: repository,
+          branchName: "accept-hook",
+          worktreeSlug: "accept-hook",
+        },
+      });
+      expect(created.error).toBeNull();
+      const cwd = created.workspace!.workspaceDirectory;
+      expect(created.workspace!.gitRuntime?.currentBranch).toBe("plugin-branch");
+      const persisted = JSON.parse(
+        await readFile(path.join(daemon.paseoHome, "projects", "workspaces.json"), "utf8"),
+      );
+      expect(persisted).toContainEqual(
+        expect.objectContaining({
+          workspaceId: created.workspace!.id,
+          branch: "plugin-branch",
+          baseBranch: "refs/heads/plugin-base",
+          worktreeRoot: cwd,
+        }),
+      );
+      expect(cwd).toBe(path.join(await realpath(root), "elsewhere", "accept-hook"));
+      expect(await readFile(path.join(cwd, "from-plugin-base.txt"), "utf8")).toBe("base");
+      expect(
+        execFileSync("git", ["branch", "--show-current"], { cwd, encoding: "utf8" }).trim(),
+      ).toBe("plugin-branch");
+      expect(await readFile(path.join(cwd, "plugin-ready.txt"), "utf8")).toBe("ready");
+      const firstAgent = withFirstAgentContext
+        ? created.agent!
+        : await client.createAgent({
+            provider: PROVIDER_ID,
+            cwd,
+            workspaceId: created.workspace!.id,
+          });
+      expect(firstAgent).toMatchObject({
+        cwd,
+        workspaceId: created.workspace!.id,
+        provider: PROVIDER_ID,
+      });
+      await expect
+        .poll(async () =>
+          (await client.getPluginLogs("shutdown-provider-plugin"))
+            .filter(({ message }) => message.startsWith('{"hook":"first-agent-ready"'))
+            .map(({ message }) => JSON.parse(message)),
+        )
+        .toContainEqual({
+          hook: "first-agent-ready",
+          agentId: firstAgent.id,
+          cwd,
+          contents: "ready",
+        });
+      const records = (await readFile(orderFile, "utf8"))
+        .trim()
+        .split("\n")
+        .map((line) => JSON.parse(line));
+      expect(records.map((record) => record.hook)).toEqual([
+        "worktree.create.before",
+        "worktree.create.after",
+        "workspace.create.after",
+        "agent.create.before",
+      ]);
+      expect({
+        ...records[1].worktree,
+        sourceCheckout: await realpath(records[1].worktree.sourceCheckout),
+      }).toEqual({
+        path: cwd,
+        branch: "plugin-branch",
+        sourceCheckout: await realpath(repository),
+      });
+      expect((await client.fetchWorkspaces()).entries.map((workspace) => workspace.id)).toContain(
+        created.workspace!.id,
+      );
+      await client.archiveWorkspace(created.workspace!.id);
+      await expect(stat(cwd)).rejects.toMatchObject({ code: "ENOENT" });
+      const hookRecordsBeforeRestore = await readFile(orderFile, "utf8");
+      await client.close();
+      await daemon.close();
+      daemon = await createTestPaseoDaemon({
+        paseoHomeRoot: path.join(root, "state"),
+        cleanup: false,
+        pluginsEnabled: true,
+        plugins: {
+          "shutdown-provider-plugin": { source: "directory", path: pluginDirectory, enabled: true },
+        },
+      });
+      client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+      await client.connect();
+      await client.restoreWorkspace(created.workspace!.id);
+      expect(await readFile(path.join(cwd, "from-plugin-base.txt"), "utf8")).toBe("base");
+      expect(await readFile(orderFile, "utf8")).toBe(hookRecordsBeforeRestore);
+      const beforeFailure = await client.fetchWorkspaces();
+      const worktreesBeforeFailure = execFileSync("git", ["worktree", "list", "--porcelain"], {
+        cwd: repository,
+        encoding: "utf8",
+      });
+      const rejected = await client.createWorkspace({
+        source: {
+          kind: "worktree",
+          cwd: repository,
+          branchName: "reject-hook",
+          worktreeSlug: "reject-hook",
+        },
+      });
+      expect(rejected.workspace).toBeNull();
+      expect(rejected.error).toContain(
+        "Plugin shutdown-provider-plugin worktree.create.after failed: worktree rejected",
+      );
+      const failedRecords = (await readFile(orderFile, "utf8"))
+        .trim()
+        .split("\n")
+        .map((line) => JSON.parse(line));
+      const failedPath = failedRecords.at(-1).worktree.path;
+      await expect(stat(failedPath)).rejects.toMatchObject({ code: "ENOENT" });
+      expect((await client.fetchWorkspaces()).entries.map(({ id }) => id).sort()).toEqual(
+        beforeFailure.entries.map(({ id }) => id).sort(),
+      );
+      expect(
+        execFileSync("git", ["worktree", "list", "--porcelain"], {
+          cwd: repository,
+          encoding: "utf8",
+        }),
+      ).toBe(worktreesBeforeFailure);
+    } finally {
+      await client.close();
+      await daemon.close();
+      await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+    }
+  },
+  60_000,
+);
+
+test("worktree before hook rejects unsafe destinations with plugin attribution before creating branches", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-before-invalid-"));
+  const repository = path.join(root, "repository");
+  execFileSync("git", ["init", "-b", "main", repository], { stdio: "pipe" });
+  execFileSync(
+    "git",
+    [
+      "-c",
+      "user.name=Test",
+      "-c",
+      "user.email=test@example.com",
+      "-c",
+      "commit.gpgsign=false",
+      "commit",
+      "--allow-empty",
+      "-m",
+      "initial",
+    ],
+    { cwd: repository, stdio: "pipe" },
+  );
+  const occupied = path.join(root, "occupied");
+  await mkdir(occupied);
+  const destinations = [
+    occupied,
+    "relative/path",
+    repository,
+    path.join(repository, ".git", "worktree"),
+    root,
+    path.parse(root).root,
+    (await import("node:os")).homedir(),
+  ];
+  const pluginDirectory = await createProviderPlugin(root, {
+    acknowledgeClose: true,
+    hooks: `
+  server.addHook("worktree.create.before", async ({ request }) => {
+    if (request.branch === "throws") throw new Error("creation denied");
+    if (request.branch === "readonly") return { ...request, repoRoot: "/different-repository" };
+    return { ...request, path: ${JSON.stringify(destinations)}[Number(request.branch.slice(4))] };
+  });`,
+  });
+  const daemon = await createTestPaseoDaemon();
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    await client.connect();
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(pluginDirectory);
+    for (const branchName of [
+      ...destinations.map((_, index) => `bad-${index}`),
+      "throws",
+      "readonly",
+    ]) {
+      const created = await client.createWorkspace({
+        source: { kind: "worktree", cwd: repository, branchName, worktreeSlug: branchName },
+      });
+      expect(created.workspace).toBeNull();
+      expect(created.error).toContain(
+        "Plugin shutdown-provider-plugin worktree.create.before failed:",
+      );
+      expect(
+        execFileSync("git", ["branch", "--format=%(refname:short)"], {
+          cwd: repository,
+          encoding: "utf8",
+        }).trim(),
+      ).toBe("main");
+      expect(
+        execFileSync("git", ["worktree", "list", "--porcelain"], {
+          cwd: repository,
+          encoding: "utf8",
+        }).match(/^worktree /gm),
+      ).toHaveLength(1);
+    }
+    expect((await client.fetchWorkspaces()).entries).toEqual([]);
+  } finally {
+    await client.close();
+    await daemon.close();
+    await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  }
+}, 60_000);
+
+test("the placement example creates a sibling worktree, opens its first agent there, lists and archives it", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-placement-example-"));
+  const repository = path.join(root, "repository");
+  execFileSync("git", ["init", "-b", "main", repository], { stdio: "pipe" });
+  execFileSync(
+    "git",
+    [
+      "-c",
+      "user.name=Test",
+      "-c",
+      "user.email=test@example.com",
+      "-c",
+      "commit.gpgsign=false",
+      "commit",
+      "--allow-empty",
+      "-m",
+      "initial",
+    ],
+    { cwd: repository, stdio: "pipe" },
+  );
+  const providerDirectory = await createProviderPlugin(root, {
+    acknowledgeClose: true,
+    reportOpen: true,
+  });
+  const daemon = await createTestPaseoDaemon();
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    await client.connect();
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(providerDirectory);
+    const installed = await client.installDirectoryPlugin(
+      fileURLToPath(new URL("../../../../../plugin-examples/worktree-placement", import.meta.url)),
+    );
+    expect(installed.status).toBe("running");
+    const created = await client.createWorkspace({
+      source: {
+        kind: "worktree",
+        cwd: repository,
+        branchName: "feature/x",
+        worktreeSlug: "feature-x",
+      },
+    });
+    expect(created.error).toBeNull();
+    const cwd = path.join(await realpath(root), "repository.feature-x");
+    expect(created.workspace!.workspaceDirectory).toBe(cwd);
+    expect((await stat(cwd)).isDirectory()).toBe(true);
+    expect((await client.fetchWorkspaces()).entries.map((workspace) => workspace.id)).toContain(
+      created.workspace!.id,
+    );
+    const worktrees = await client.getPaseoWorktreeList({ cwd: repository });
+    expect(worktrees.error).toBeNull();
+    expect(worktrees.worktrees).toContainEqual(
+      expect.objectContaining({ worktreePath: cwd, branchName: "feature/x" }),
+    );
+    const collision = await client.createWorkspace({
+      source: {
+        kind: "worktree",
+        cwd: repository,
+        branchName: "feature/x",
+        worktreeSlug: "another-slug",
+      },
+    });
+    expect(collision.workspace).toBeNull();
+    expect(collision.error).toContain("Plugin worktree-placement worktree.create.before failed:");
+    expect(collision.error).toContain("already exists");
+    const agent = await client.createAgent({
+      provider: PROVIDER_ID,
+      cwd,
+      workspaceId: created.workspace!.id,
+    });
+    expect(agent.cwd).toBe(cwd);
+    const logs = await client.getPluginLogs("shutdown-provider-plugin");
+    const opened = logs
+      .filter((entry) => entry.message.startsWith('{"hook":"provider.open"'))
+      .map((entry) => JSON.parse(entry.message));
+    expect(opened.map((entry) => entry.config.cwd)).toContain(cwd);
+    await client.archiveWorkspace(created.workspace!.id);
+    await expect(stat(cwd)).rejects.toMatchObject({ code: "ENOENT" });
+  } finally {
+    await client.close();
+    await daemon.close();
+    await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  }
+}, 60_000);
+
+test("worktree includes reach the first agent without copying tracked or unignored files", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-include-"));
+  const repository = path.join(root, "repository");
+  execFileSync("git", ["init", "-b", "main", repository], { stdio: "pipe" });
+  const git = (...args: string[]) => execFileSync("git", args, { cwd: repository, stdio: "pipe" });
+  await mkdir(path.join(repository, "config"));
+  await writeFile(path.join(repository, ".gitignore"), ".env\nconfig/*.local.json\n");
+  await writeFile(
+    path.join(repository, ".worktreeinclude"),
+    ".env\nconfig/*.local.json\nunignored.txt\n",
+  );
+  await writeFile(path.join(repository, "config/tracked.local.json"), "git version");
+  git("add", ".gitignore", ".worktreeinclude");
+  git("add", "-f", "config/tracked.local.json");
+  git(
+    "-c",
+    "user.name=Test",
+    "-c",
+    "user.email=test@example.com",
+    "-c",
+    "commit.gpgsign=false",
+    "commit",
+    "-m",
+    "initial",
+  );
+  await writeFile(path.join(repository, ".env"), "SECRET=source");
+  await writeFile(path.join(repository, "config/app.local.json"), "local config");
+  await writeFile(path.join(repository, "config/tracked.local.json"), "uncommitted source version");
+  await writeFile(path.join(repository, "unignored.txt"), "unignored source");
+  const observed = path.join(root, "observed.json");
+  const pluginDirectory = await createProviderPlugin(root, {
+    acknowledgeClose: true,
+    hooks: `
+  server.addHook("agent.open.before", async ({ request }) => {
+    const { readFile, writeFile } = await import("node:fs/promises");
+    const contents = await Promise.all([".env", "config/app.local.json", "config/tracked.local.json"].map(file => readFile(request.cwd + "/" + file, "utf8")));
+    await writeFile(${JSON.stringify(observed)}, JSON.stringify(contents));
+  });`,
+  });
+  const daemon = await createTestPaseoDaemon({ builtinPlugins: new BuiltinPluginLoader() });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    await client.connect();
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    expect((await client.installDirectoryPlugin(pluginDirectory)).status).toBe("running");
+    const created = await client.createWorkspace({
+      source: { kind: "worktree", cwd: repository, branchName: "include", worktreeSlug: "include" },
+    });
+    expect(created.error).toBeNull();
+    await client.createAgent({
+      provider: PROVIDER_ID,
+      cwd: created.workspace!.workspaceDirectory,
+      workspaceId: created.workspace!.id,
+    });
+    expect(JSON.parse(await readFile(observed, "utf8"))).toEqual([
+      "SECRET=source",
+      "local config",
+      "git version",
+    ]);
+    await expect(
+      stat(path.join(created.workspace!.workspaceDirectory, "unignored.txt")),
+    ).rejects.toMatchObject({ code: "ENOENT" });
+
+    const sourceWorktree = created.workspace!.workspaceDirectory;
+    await writeFile(path.join(sourceWorktree, ".env"), "SECRET=worktree");
+    await writeFile(path.join(sourceWorktree, "config/app.local.json"), "worktree config");
+    const nested = await client.createWorkspace({
+      source: {
+        kind: "worktree",
+        cwd: sourceWorktree,
+        branchName: "nested",
+        worktreeSlug: "nested",
+      },
+    });
+    expect(nested.error).toBeNull();
+    await client.createAgent({
+      provider: PROVIDER_ID,
+      cwd: nested.workspace!.workspaceDirectory,
+      workspaceId: nested.workspace!.id,
+    });
+    expect(JSON.parse(await readFile(observed, "utf8"))).toEqual([
+      "SECRET=worktree",
+      "worktree config",
+      "git version",
+    ]);
+
+    execFileSync("git", ["add", "-f", ".env"], { cwd: sourceWorktree, stdio: "pipe" });
+    execFileSync(
+      "git",
+      [
+        "-c",
+        "user.name=Test",
+        "-c",
+        "user.email=test@example.com",
+        "-c",
+        "commit.gpgsign=false",
+        "commit",
+        "-m",
+        "commit branch env",
+      ],
+      { cwd: sourceWorktree, stdio: "pipe" },
+    );
+    const existing = await client.createWorkspace({
+      source: {
+        kind: "worktree",
+        cwd: repository,
+        baseBranch: "include",
+        branchName: "existing",
+        worktreeSlug: "existing",
+      },
+    });
+    expect(existing.error).toBeNull();
+    await client.createAgent({
+      provider: PROVIDER_ID,
+      cwd: existing.workspace!.workspaceDirectory,
+      workspaceId: existing.workspace!.id,
+    });
+    expect(JSON.parse(await readFile(observed, "utf8"))).toEqual([
+      "SECRET=worktree",
+      "local config",
+      "git version",
+    ]);
+
+    await rm(path.join(repository, ".worktreeinclude"));
+    const noIncludes = await client.createWorkspace({
+      source: {
+        kind: "worktree",
+        cwd: repository,
+        baseBranch: "main",
+        branchName: "no-includes",
+        worktreeSlug: "no-includes",
+      },
+    });
+    expect(noIncludes.error).toBeNull();
+    await expect(
+      stat(path.join(noIncludes.workspace!.workspaceDirectory, ".env")),
+    ).rejects.toMatchObject({ code: "ENOENT" });
+    await expect(
+      stat(path.join(noIncludes.workspace!.workspaceDirectory, "config/app.local.json")),
+    ).rejects.toMatchObject({ code: "ENOENT" });
+
+    await writeFile(path.join(repository, ".worktreeinclude"), ".env\nconfig/*.local.json\n");
+    await rm(path.join(sourceWorktree, "config"), { recursive: true });
+    await writeFile(
+      path.join(sourceWorktree, "config"),
+      "committed file blocks the config directory",
+    );
+    execFileSync("git", ["add", "-A", "config"], { cwd: sourceWorktree, stdio: "pipe" });
+    execFileSync(
+      "git",
+      [
+        "-c",
+        "user.name=Test",
+        "-c",
+        "user.email=test@example.com",
+        "-c",
+        "commit.gpgsign=false",
+        "commit",
+        "-m",
+        "block config directory",
+      ],
+      { cwd: sourceWorktree, stdio: "pipe" },
+    );
+    const beforeFailure = await client.fetchWorkspaces();
+    const worktreesBeforeFailure = git("worktree", "list", "--porcelain").toString();
+    const failed = await client.createWorkspace({
+      source: {
+        kind: "worktree",
+        cwd: repository,
+        baseBranch: "include",
+        branchName: "copy-failure",
+        worktreeSlug: "copy-failure",
+      },
+    });
+    expect(failed.workspace).toBeNull();
+    expect(failed.error).toContain("Plugin worktree-include worktree.create.after failed:");
+    expect((await client.fetchWorkspaces()).entries.map(({ id }) => id).sort()).toEqual(
+      beforeFailure.entries.map(({ id }) => id).sort(),
+    );
+    expect(git("worktree", "list", "--porcelain").toString()).toBe(worktreesBeforeFailure);
+  } finally {
+    await client.close();
+    await daemon.close();
+    await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  }
+}, 60_000);
diff --git a/packages/server/src/server/plugins/lifecycle.real.e2e.test.ts b/packages/server/src/server/plugins/lifecycle.real.e2e.test.ts
index fc9cfbd84d..40de1215d8 100644
--- a/packages/server/src/server/plugins/lifecycle.real.e2e.test.ts
+++ b/packages/server/src/server/plugins/lifecycle.real.e2e.test.ts
@@ -6,7 +6,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import pino from "pino";
 import { expect, test } from "vitest";
-import type { PluginBeforeRequests, PluginLifecycleEvents } from "@getpaseo/plugin/server";
+import type { PluginHookRequests, PluginHookEvents } from "@getpaseo/plugin/server";
 import { ClaudeAgentClient } from "../agent/providers/claude/agent.js";
 import { CodexAppServerAgentClient } from "../agent/providers/codex-app-server-agent.js";
 import { DaemonClient } from "../test-utils/daemon-client.js";
@@ -14,14 +14,14 @@ import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
 
 type RecordedHook =
   | {
-      [Name in keyof PluginLifecycleEvents]: { hook: Name; data: PluginLifecycleEvents[Name] };
-    }[keyof PluginLifecycleEvents]
+      [Name in keyof PluginHookEvents]: { hook: Name; data: PluginHookEvents[Name] };
+    }[keyof PluginHookEvents]
   | {
-      [Name in keyof PluginBeforeRequests]: {
-        hook: `before ${Name}`;
-        data: { request: PluginBeforeRequests[Name] };
+      [Name in keyof PluginHookRequests]: {
+        hook: Name;
+        data: { request: PluginHookRequests[Name] };
       };
-    }[keyof PluginBeforeRequests];
+    }[keyof PluginHookRequests];
 
 const repoRoot = fileURLToPath(new URL("../../../../../", import.meta.url));
 const evidenceDirectory = path.join(repoRoot, ".dev", "lifecycle-proof");
@@ -39,8 +39,8 @@ async function readHooks(client: DaemonClient): Promise<RecordedHook[]> {
 
 async function endedTurns(client: DaemonClient, agentId: string) {
   const events = await readHooks(client);
-  return events.filter((event): event is Extract<RecordedHook, { hook: "agent.turn_ended" }> => {
-    return event.hook === "agent.turn_ended" && event.data.agent.id === agentId;
+  return events.filter((event): event is Extract<RecordedHook, { hook: "agent.turn.after" }> => {
+    return event.hook === "agent.turn.after" && event.data.agent.id === agentId;
   });
 }
 
@@ -63,7 +63,7 @@ async function waitForPermission(client: DaemonClient, agentId: string, command:
         const events = await readHooks(client);
         for (const event of events) {
           if (
-            event.hook === "agent.permission_requested" &&
+            event.hook === "agent.permission.before" &&
             event.data.agent.id === agentId &&
             event.data.request.input?.command === command
           ) {
@@ -111,7 +111,7 @@ test.skipIf(process.platform !== "linux")(
     });
     const logger = pino({ level: "info" }, destination);
     const daemon = await createTestPaseoDaemon({
-      daemonVersion: "0.8.0",
+      daemonVersion: "0.14.0-beta.1",
       logger,
       agentClients: {
         claude: new ClaudeAgentClient({ logger }),
@@ -121,7 +121,7 @@ test.skipIf(process.platform !== "linux")(
     });
     const client = new DaemonClient({
       url: `ws://127.0.0.1:${daemon.port}/ws`,
-      appVersion: "0.8.0",
+      appVersion: "0.14.0-beta.1",
     });
     const proof: Record<string, unknown> = {
       port: daemon.port,
@@ -169,7 +169,7 @@ test.skipIf(process.platform !== "linux")(
       const approvalId = await waitForPermission(client, agent.id, "git status");
       expect(await readHooks(client)).toContainEqual(
         expect.objectContaining({
-          hook: "agent.permission_resolved",
+          hook: "agent.permission.after",
           data: expect.objectContaining({
             requestId: approvalId,
             resolution: expect.objectContaining({ behavior: "allow" }),
@@ -186,7 +186,7 @@ test.skipIf(process.platform !== "linux")(
       const deniedId = await waitForPermission(client, agent.id, "rm -rf canary.txt");
       expect(await readHooks(client)).toContainEqual(
         expect.objectContaining({
-          hook: "agent.permission_resolved",
+          hook: "agent.permission.after",
           data: expect.objectContaining({
             requestId: deniedId,
             resolution: expect.objectContaining({ behavior: "deny" }),
@@ -224,7 +224,7 @@ test.skipIf(process.platform !== "linux")(
         .poll(
           async () => {
             return (await readHooks(client)).filter((event) => {
-              return event.hook === "agent.turn_started" && event.data.agent.id === agent.id;
+              return event.hook === "agent.turn.before" && event.data.agent.id === agent.id;
             }).length;
           },
           { timeout: 30_000 },
@@ -278,23 +278,26 @@ test.skipIf(process.platform !== "linux")(
           );
           return [...names].sort();
         })
-        .toEqual([
-          "agent.archived",
-          "agent.closed",
-          "agent.created",
-          "agent.permission_requested",
-          "agent.permission_resolved",
-          "agent.turn_ended",
-          "agent.turn_started",
-          "before agent.create",
-          "before agent.session_open",
-          "before workspace.create",
-          "workspace.archived",
-          "workspace.created",
-        ]);
+        .toEqual(
+          [
+            "agent.archive.after",
+            "agent.close.after",
+            "agent.create.after",
+            "agent.permission.before",
+            "agent.permission.after",
+            "agent.turn.after",
+            "agent.turn.before",
+            "agent.create.before",
+            "agent.open.before",
+            "worktree.create.after",
+            "workspace.create.before",
+            "workspace.archive.after",
+            "workspace.create.after",
+          ].sort(),
+        );
       const openReasons = (await readHooks(client))
         .filter((event) => {
-          return event.hook === "before agent.session_open";
+          return event.hook === "agent.open.before";
         })
         .map((event) => {
           return event.data.request.reason;
diff --git a/packages/server/src/server/plugins/lifecycle/handlers.test.ts b/packages/server/src/server/plugins/lifecycle/handlers.test.ts
index 5e30535953..e17cca1ed5 100644
--- a/packages/server/src/server/plugins/lifecycle/handlers.test.ts
+++ b/packages/server/src/server/plugins/lifecycle/handlers.test.ts
@@ -1,7 +1,7 @@
 import { expect, test } from "vitest";
 import { createPaseoApi } from "@getpaseo/client";
 import { DaemonClient } from "@getpaseo/client/internal/daemon-client";
-import { PluginHookHandlers } from "./index.js";
+import { validateBeforeResult, PluginHookHandlers } from "./index.js";
 
 const paseo = createPaseoApi(
   new DaemonClient({ url: "ws://127.0.0.1:1/ws", clientId: "lifecycle-unit" }),
@@ -9,18 +9,17 @@ const paseo = createPaseoApi(
 
 test("removing an old registration twice preserves a newer registration for the same hook", async () => {
   const hooks = new PluginHookHandlers(() => {});
-  const remove = hooks.before("workspace.create", ({ request }) => {
+  const remove = hooks.addHook("workspace.create.before", async ({ request }) => {
     return { ...request, title: "old" };
   });
   remove();
-  hooks.before("workspace.create", ({ request }) => {
+  hooks.addHook("workspace.create.before", async ({ request }) => {
     return { ...request, title: "new" };
   });
   remove();
   const output = await hooks.invoke(
     "operation",
-    "before",
-    "workspace.create",
+    "workspace.create.before",
     {
       source: { kind: "directory", path: "/project" },
     },
@@ -31,17 +30,17 @@ test("removing an old registration twice preserves a newer registration for the
 
 test("before hooks compose returned requests and preserve the original input", async () => {
   const hooks = new PluginHookHandlers(() => {});
-  hooks.before("workspace.create", ({ request }) => {
+  hooks.addHook("workspace.create.before", async ({ request }) => {
     return { ...request, title: "first" };
   });
-  hooks.before("workspace.create", () => {
+  hooks.addHook("workspace.create.before", async () => {
     return;
   });
-  hooks.before("workspace.create", ({ request }) => {
+  hooks.addHook("workspace.create.before", async ({ request }) => {
     return { ...request, title: request.title + ":second" };
   });
   const input = { source: { kind: "directory", path: "/project" } };
-  expect(await hooks.invoke("operation", "before", "workspace.create", input, paseo)).toEqual({
+  expect(await hooks.invoke("operation", "workspace.create.before", input, paseo)).toEqual({
     source: { kind: "directory", path: "/project" },
     title: "first:second",
   });
@@ -50,7 +49,7 @@ test("before hooks compose returned requests and preserve the original input", a
 
 test("teardown aborts an active callback and removes its registrations", async () => {
   const hooks = new PluginHookHandlers(() => {});
-  hooks.before("workspace.create", async (_input, context) => {
+  hooks.addHook("workspace.create.before", async (_input, context) => {
     await new Promise<void>((_resolve, reject) => {
       context.signal.addEventListener(
         "abort",
@@ -63,8 +62,7 @@ test("teardown aborts an active callback and removes its registrations", async (
   });
   const invocation = hooks.invoke(
     "operation",
-    "before",
-    "workspace.create",
+    "workspace.create.before",
     {
       source: { kind: "directory", path: "/project" },
     },
@@ -72,19 +70,18 @@ test("teardown aborts an active callback and removes its registrations", async (
   );
   hooks.close();
   await expect(invocation).rejects.toThrow("Hook aborted");
-  expect(hooks.catalog()).toEqual({ events: [], before: [] });
+  expect(hooks.catalog()).toEqual([]);
 });
 
 test("session-open hooks reject changes to session identity instead of silently ignoring them", async () => {
   const hooks = new PluginHookHandlers(() => {});
-  hooks.before("agent.session_open", ({ request }) => {
+  hooks.addHook("agent.open.before", async ({ request }) => {
     return { ...request, provider: "another-provider" };
   });
   await expect(
     hooks.invoke(
       "operation",
-      "before",
-      "agent.session_open",
+      "agent.open.before",
       {
         agentId: "agent",
         workspaceId: "workspace",
@@ -93,8 +90,166 @@ test("session-open hooks reject changes to session identity instead of silently
         reason: "resume",
         purpose: "interactive",
         env: {},
+        title: null,
+        labels: {},
+        tools: [],
+        mcpServers: {},
       },
       paseo,
     ),
-  ).rejects.toThrow("agent.session_open hooks can only change env");
+  ).rejects.toThrow("agent.open.before hooks can only change env");
+});
+
+test.each([{ title: "Changed" }, { labels: { changed: "true" } }])(
+  "session-open targeting metadata is read-only: %j",
+  async (patch) => {
+    const hooks = new PluginHookHandlers(() => {});
+    hooks.addHook("agent.open.before", async ({ request }) => ({ ...request, ...patch }));
+    await expect(
+      hooks.invoke(
+        "operation",
+        "agent.open.before",
+        {
+          agentId: "agent",
+          workspaceId: null,
+          provider: "codex",
+          cwd: "/project",
+          title: "Original",
+          labels: {},
+          tools: [],
+          mcpServers: {},
+          env: {},
+          reason: "create",
+          purpose: "interactive",
+        },
+        paseo,
+      ),
+    ).rejects.toThrow("agent.open.before hooks can only change env, tools, and mcpServers");
+  },
+);
+
+test("new request-changing registrations compose with legacy registrations in registration order", async () => {
+  const hooks = new PluginHookHandlers(() => {});
+  hooks.before("workspace.create", ({ request }) => ({ ...request, title: "legacy" }));
+  hooks.addHook("workspace.create.before", async ({ request }) => ({
+    ...request,
+    title: request.title + ":new",
+  }));
+  hooks.before("workspace.create", ({ request }) => ({
+    ...request,
+    title: request.title + ":last",
+  }));
+  expect(
+    await hooks.invoke(
+      "operation",
+      "workspace.create.before",
+      {
+        source: { kind: "directory", path: "/project" },
+      },
+      paseo,
+    ),
+  ).toEqual({ source: { kind: "directory", path: "/project" }, title: "legacy:new:last" });
+});
+
+test.each(["agent.session_open", "agent.create.prepare", "nonsense"])(
+  "addHook rejects unsupported name %s at registration",
+  (name) => {
+    const hooks = new PluginHookHandlers(() => {});
+    // @ts-expect-error Runtime validation also protects untyped plugins.
+    expect(() => hooks.addHook(name, async () => {})).toThrow(name);
+  },
+);
+
+test.each([
+  ["workspace.create", "workspace.create.before"],
+  ["workspace.created", "workspace.create.after"],
+  ["workspace.archived", "workspace.archive.after"],
+  ["agent.create", "agent.create.before"],
+  ["agent.created", "agent.create.after"],
+  ["agent.session_open", "agent.open.before"],
+  ["agent.closed", "agent.close.after"],
+  ["agent.archived", "agent.archive.after"],
+  ["agent.turn_started", "agent.turn.before"],
+  ["agent.turn_ended", "agent.turn.after"],
+  ["agent.permission_requested", "agent.permission.before"],
+  ["agent.permission_resolved", "agent.permission.after"],
+] as const)("legacy %s registers only %s across the process boundary", (oldName, newName) => {
+  const hooks = new PluginHookHandlers(() => {});
+  const handler = async () => {};
+  const remove =
+    oldName === "workspace.create" || oldName === "agent.create" || oldName === "agent.session_open"
+      ? hooks.before(oldName, handler)
+      : hooks.on(oldName, handler);
+  hooks.addHook(newName, async () => {});
+  expect(hooks.catalog()).toEqual([newName]);
+  remove();
+  expect(hooks.catalog()).toEqual([newName]);
+  hooks.close();
+  expect(hooks.catalog()).toEqual([]);
+});
+
+test("legacy notifications and addHook share payloads, registration order, and cleanup", async () => {
+  const hooks = new PluginHookHandlers(() => {});
+  const received: unknown[] = [];
+  const remove = hooks.on("workspace.created", (event) => {
+    received.push(["old", event]);
+  });
+  hooks.addHook("workspace.create.after", async (event) => {
+    received.push(["new", event]);
+  });
+  const payload = {
+    workspace: {
+      id: "workspace",
+      projectId: "project",
+      cwd: "/project",
+      name: null,
+      archivedAt: null,
+    },
+  };
+  await hooks.invoke("first", "workspace.create.after", payload, paseo);
+  remove();
+  remove();
+  await hooks.invoke("second", "workspace.create.after", payload, paseo);
+  expect(received).toEqual([
+    ["old", payload],
+    ["new", payload],
+    ["new", payload],
+  ]);
+});
+
+test("a waiting after hook propagates failures and stops later handlers", async () => {
+  const hooks = new PluginHookHandlers(() => {});
+  const received: string[] = [];
+  hooks.addHook("worktree.create.after", async ({ worktree }) => {
+    received.push(worktree.path);
+    throw new Error("cannot initialize worktree");
+  });
+  hooks.addHook("worktree.create.after", async () => {
+    received.push("unexpected later handler");
+  });
+  await expect(
+    hooks.invoke(
+      "worktree",
+      "worktree.create.after",
+      {
+        worktree: { path: "/worktree", branch: "feature", sourceCheckout: "/source" },
+      },
+      paseo,
+    ),
+  ).rejects.toThrow("cannot initialize worktree");
+  expect(received).toEqual(["/worktree"]);
+});
+
+test("checkout-branch hooks reject a branch-off baseRef", async () => {
+  const request = {
+    kind: "checkout-branch" as const,
+    repoRoot: "/repo",
+    sourceCheckout: "/repo",
+    branch: "feature",
+    slug: "feature",
+    path: "/work/feature",
+  };
+  await expect(
+    validateBeforeResult("worktree.create.before", request, { ...request, baseRef: "main" }),
+  ).rejects.toThrow(/baseRef/);
 });
diff --git a/packages/server/src/server/plugins/lifecycle/index.ts b/packages/server/src/server/plugins/lifecycle/index.ts
index 29d5fda145..d4f58cc78c 100644
--- a/packages/server/src/server/plugins/lifecycle/index.ts
+++ b/packages/server/src/server/plugins/lifecycle/index.ts
@@ -1,36 +1,98 @@
+import { validateBranchSlug } from "@getpaseo/protocol/branch-slug";
+import {
+  createLifecycleRegistration,
+  pluginHookRegistry,
+} from "@getpaseo/plugin/internal/lifecycle";
+import { isDeepStrictEqual } from "node:util";
+import {
+  serializeAgentTool,
+  agentToolMetadataSchema,
+  type SessionOpenWireRequest,
+  type PluginAgentTools,
+} from "../agent-tools.js";
+import type { AgentToolDefinition } from "@getpaseo/plugin/server";
 import type { AgentStreamEvent } from "../../agent/agent-sdk-types.js";
 import { z } from "zod";
 import { CreateAgentRequestMessageSchema } from "@getpaseo/protocol/messages";
 import type {
   PluginHookAgent,
+  PluginHookPayload,
   PluginHookContext,
   PluginLifecycleRegistration,
 } from "@getpaseo/plugin/server";
 import { PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
 import type {
-  PluginBeforeRequests,
+  PluginHookRequests,
   PluginHookWorkspace,
-  PluginLifecycleEvents,
+  PluginHookEvents,
 } from "@getpaseo/plugin/server";
 import { WorkspaceCreateRequestSchema } from "@getpaseo/protocol/messages";
 import type { PersistedWorkspaceRecord } from "../../workspace-registry.js";
 
-export const lifecycleEventNames = [
-  "agent.created",
-  "agent.closed",
-  "agent.turn_started",
-  "agent.turn_ended",
-  "agent.permission_requested",
-  "agent.permission_resolved",
-  "agent.archived",
-  "workspace.created",
-  "workspace.archived",
-] as const;
-export const beforeHookNames = ["agent.create", "agent.session_open", "workspace.create"] as const;
+export type PluginWireBeforeRequests = Omit<PluginHookRequests, "agent.open.before"> & {
+  "agent.open.before": SessionOpenWireRequest;
+};
+
+/** Daemon-only results; ownership never crosses the plugin process boundary. */
+export type PluginBeforeResults = PluginWireBeforeRequests & {
+  "agent.open.before": SessionOpenWireRequest & { mcpServerOwners?: Record<string, string> };
+};
+
+const worktreeRequestFields = {
+  repoRoot: z.string(),
+  sourceCheckout: z.string(),
+  branch: z.string().min(1),
+  slug: z.string().refine((value) => validateBranchSlug(value).valid, "Invalid worktree slug"),
+  path: z.string().min(1),
+};
+const changeRequestFields = {
+  headRef: z.string().min(1),
+  headRepositoryOwner: z.string().optional(),
+  checkoutRefs: z
+    .array(z.object({ remoteName: z.string().optional(), remoteRef: z.string() }))
+    .optional(),
+  pushRemoteUrl: z.string().optional(),
+  trackOriginHead: z.boolean().optional(),
+};
+const worktreeRequestSchema = z.discriminatedUnion("kind", [
+  z
+    .object({ ...worktreeRequestFields, kind: z.literal("branch-off"), baseRef: z.string().min(1) })
+    .strict(),
+  z
+    .object({
+      ...worktreeRequestFields,
+      kind: z.literal("checkout-branch"),
+    })
+    .strict(),
+  z
+    .object({
+      ...worktreeRequestFields,
+      ...changeRequestFields,
+      kind: z.literal("checkout-change-request"),
+      baseRef: z.string().min(1),
+      forge: z.string(),
+      changeRequestNumber: z.number().int().positive(),
+      headRepository: z.string().optional(),
+    })
+    .strict(),
+  z
+    .object({
+      ...worktreeRequestFields,
+      ...changeRequestFields,
+      kind: z.literal("checkout-github-pr"),
+      baseRef: z.string().min(1),
+      githubPrNumber: z.number().int().positive(),
+    })
+    .strict(),
+]);
 
 const beforeSchemas = {
-  "agent.create": CreateAgentRequestMessageSchema.pick({ config: true, env: true }).strict(),
-  "agent.session_open": z
+  "worktree.create.before": worktreeRequestSchema,
+  "agent.create.before": CreateAgentRequestMessageSchema.pick({
+    config: true,
+    env: true,
+  }).strict(),
+  "agent.open.before": z
     .object({
       agentId: z.string(),
       workspaceId: z.string().nullable(),
@@ -38,28 +100,49 @@ const beforeSchemas = {
       cwd: z.string(),
       reason: z.enum(["create", "resume", "refresh", "import"]),
       purpose: z.enum(["interactive", "history"]),
+      title: z.string().nullable(),
+      labels: z.record(z.string(), z.string()),
+      tools: z.array(agentToolMetadataSchema),
       env: z.record(z.string(), z.string()),
+      mcpServers: CreateAgentRequestMessageSchema.shape.config.shape.mcpServers.unwrap(),
     })
     .strict(),
-  "workspace.create": WorkspaceCreateRequestSchema.omit({ type: true, requestId: true }).strict(),
+  "workspace.create.before": WorkspaceCreateRequestSchema.omit({
+    type: true,
+    requestId: true,
+  }).strict(),
 };
 
+const sessionOpenLocalResultSchema = beforeSchemas["agent.open.before"].extend({
+  tools: z.array(
+    z.custom<AgentToolDefinition>(
+      (tool) =>
+        typeof tool === "object" &&
+        tool !== null &&
+        "input" in tool &&
+        "execute" in tool &&
+        typeof tool.execute === "function",
+    ),
+  ),
+});
+
 export interface PluginLifecycle {
-  emit<Name extends keyof PluginLifecycleEvents>(
+  wait(
+    name: "worktree.create.after",
+    payload: PluginHookPayload<"worktree.create.after">,
+  ): Promise<void>;
+  emit<Name extends keyof PluginHookEvents>(name: Name, event: PluginHookEvents[Name]): void;
+  before<Name extends keyof PluginWireBeforeRequests>(
     name: Name,
-    event: PluginLifecycleEvents[Name],
-  ): void;
-  before<Name extends keyof PluginBeforeRequests>(
-    name: Name,
-    request: PluginBeforeRequests[Name],
-  ): Promise<PluginBeforeRequests[Name]>;
+    request: PluginWireBeforeRequests[Name],
+  ): Promise<PluginBeforeResults[Name]>;
 }
 
-export function validateBeforeRequest<Name extends keyof PluginBeforeRequests>(
+export function validateBeforeRequest<Name extends keyof PluginWireBeforeRequests>(
   name: Name,
   value: unknown,
-): PluginBeforeRequests[Name] {
-  return beforeSchemas[name].parse(value) as PluginBeforeRequests[Name];
+): PluginWireBeforeRequests[Name] {
+  return beforeSchemas[name].parse(value) as PluginWireBeforeRequests[Name];
 }
 
 export function describeHookWorkspace(workspace: PersistedWorkspaceRecord): PluginHookWorkspace {
@@ -96,32 +179,32 @@ export function publishAgentStream(
   event: AgentStreamEvent,
 ): void {
   if (event.type === "turn_started") {
-    lifecycle.emit("agent.turn_started", { agent, turnId: event.turnId ?? null });
+    lifecycle.emit("agent.turn.before", { agent, turnId: event.turnId ?? null });
   } else if (event.type === "turn_completed") {
-    lifecycle.emit("agent.turn_ended", {
+    lifecycle.emit("agent.turn.after", {
       agent,
       turnId: event.turnId ?? null,
       timeline: [],
       outcome: { kind: "completed" },
     });
   } else if (event.type === "turn_failed") {
-    lifecycle.emit("agent.turn_ended", {
+    lifecycle.emit("agent.turn.after", {
       agent,
       turnId: event.turnId ?? null,
       timeline: [],
       outcome: { kind: "failed", error: { message: event.error, code: event.code } },
     });
   } else if (event.type === "turn_canceled") {
-    lifecycle.emit("agent.turn_ended", {
+    lifecycle.emit("agent.turn.after", {
       agent,
       turnId: event.turnId ?? null,
       timeline: [],
       outcome: { kind: "canceled", reason: event.reason },
     });
   } else if (event.type === "permission_requested") {
-    lifecycle.emit("agent.permission_requested", { agent, request: event.request });
+    lifecycle.emit("agent.permission.before", { agent, request: event.request });
   } else if (event.type === "permission_resolved") {
-    lifecycle.emit("agent.permission_resolved", {
+    lifecycle.emit("agent.permission.after", {
       agent,
       requestId: event.requestId,
       resolution: event.resolution,
@@ -129,31 +212,40 @@ export function publishAgentStream(
   }
 }
 
-export function validateBeforeResult<Name extends keyof PluginBeforeRequests>(
+export async function validateBeforeResult<Name extends keyof PluginWireBeforeRequests>(
   name: Name,
-  input: PluginBeforeRequests[Name],
+  input: PluginWireBeforeRequests[Name],
   output: unknown,
-): PluginBeforeRequests[Name] {
+): Promise<PluginWireBeforeRequests[Name]> {
   const result = validateBeforeRequest(name, output);
-  if (name === "agent.session_open") {
-    const previous = beforeSchemas["agent.session_open"].parse(input);
-    const next = beforeSchemas["agent.session_open"].parse(result);
+  if (name === "agent.open.before") {
+    const previous = beforeSchemas["agent.open.before"].parse(input);
+    const next = beforeSchemas["agent.open.before"].parse(result);
     if (
       previous.agentId !== next.agentId ||
       previous.workspaceId !== next.workspaceId ||
       previous.provider !== next.provider ||
       previous.cwd !== next.cwd ||
       previous.reason !== next.reason ||
-      previous.purpose !== next.purpose
+      previous.purpose !== next.purpose ||
+      previous.title !== next.title ||
+      !isDeepStrictEqual(previous.labels, next.labels)
     ) {
-      throw new Error("agent.session_open hooks can only change env");
+      throw new Error("agent.open.before hooks can only change env, tools, and mcpServers");
     }
   }
-  if (name === "agent.create") {
-    const previous = beforeSchemas["agent.create"].parse(input);
-    const next = beforeSchemas["agent.create"].parse(result);
+  if (name === "agent.create.before") {
+    const previous = beforeSchemas["agent.create.before"].parse(input);
+    const next = beforeSchemas["agent.create.before"].parse(result);
     if (previous.config.cwd !== next.config.cwd) {
-      throw new Error("agent.create hooks cannot change the workspace directory");
+      throw new Error("agent.create.before hooks cannot change the workspace directory");
+    }
+  }
+  if (name === "worktree.create.before") {
+    const previous = beforeSchemas["worktree.create.before"].parse(input);
+    const next = beforeSchemas["worktree.create.before"].parse(result);
+    if (previous.repoRoot !== next.repoRoot || previous.sourceCheckout !== next.sourceCheckout) {
+      throw new Error("worktree.create.before hooks cannot change repoRoot or sourceCheckout");
     }
   }
   return result;
@@ -162,37 +254,34 @@ export function validateBeforeResult<Name extends keyof PluginBeforeRequests>(
 type Handler = (input: unknown, context: PluginHookContext) => unknown;
 
 export class PluginHookHandlers implements PluginLifecycleRegistration {
-  private readonly events = new Map<string, Set<Handler>>();
-  private readonly transforms = new Map<string, Set<Handler>>();
+  private readonly handlers = new Map<string, Set<Handler>>();
   private readonly active = new Map<string, AbortController>();
 
   private readonly changed: () => void;
 
-  constructor(changed: () => void) {
+  private readonly agentTools: PluginAgentTools | undefined;
+
+  constructor(changed: () => void, agentTools?: PluginAgentTools) {
+    this.agentTools = agentTools;
     this.changed = changed;
+    const registration = createLifecycleRegistration((name, handler) =>
+      this.register(name, handler as Handler),
+    );
+    this.addHook = registration.addHook;
+    this.on = registration.on;
+    this.before = registration.before;
   }
 
-  readonly on: PluginLifecycleRegistration["on"] = (name, handler) => {
-    if (!lifecycleEventNames.includes(name)) {
-      throw new Error(`Unknown lifecycle event: ${name}`);
-    }
-    return this.register(this.events, name, handler as Handler);
-  };
+  readonly addHook: PluginLifecycleRegistration["addHook"];
+  readonly on: PluginLifecycleRegistration["on"];
+  readonly before: PluginLifecycleRegistration["before"];
 
-  readonly before: PluginLifecycleRegistration["before"] = (name, handler) => {
-    if (!beforeHookNames.includes(name)) {
-      throw new Error(`Unknown before hook: ${name}`);
-    }
-    return this.register(this.transforms, name, handler as Handler);
-  };
-
-  catalog(): { events: string[]; before: string[] } {
-    return { events: [...this.events.keys()], before: [...this.transforms.keys()] };
+  catalog(): string[] {
+    return [...this.handlers.keys()];
   }
 
   async invoke(
     id: string,
-    kind: "event" | "before",
     name: string,
     input: unknown,
     paseo: PluginHookContext["paseo"],
@@ -200,33 +289,32 @@ export class PluginHookHandlers implements PluginLifecycleRegistration {
     const controller = new AbortController();
     this.active.set(id, controller);
     try {
-      if (kind === "before") {
-        if (
-          !beforeHookNames.includes(
-            name as keyof import("@getpaseo/plugin/server").PluginBeforeRequests,
-          )
-        ) {
-          throw new Error(`Unknown before hook: ${name}`);
+      if (Object.hasOwn(beforeSchemas, name)) {
+        const hookName = name as keyof PluginHookRequests;
+        if (hookName === "agent.open.before") {
+          return await this.openSession(input, { paseo, signal: controller.signal });
         }
-        const hookName = name as keyof import("@getpaseo/plugin/server").PluginBeforeRequests;
         let request = validateBeforeRequest(hookName, input);
-        for (const handler of this.transforms.get(name) ?? []) {
+        for (const handler of this.handlers.get(name) ?? []) {
           controller.signal.throwIfAborted();
           const result = await handler(
             { request: structuredClone(request) },
             { paseo, signal: controller.signal },
           );
-          if (result !== undefined) {
-            request = validateBeforeResult(hookName, request, result);
-          }
+          if (result !== undefined) request = await validateBeforeResult(hookName, request, result);
         }
         return request;
       }
-      for (const handler of this.events.get(name) ?? []) {
+      for (const handler of this.handlers.get(name) ?? []) {
         controller.signal.throwIfAborted();
         try {
           await handler(structuredClone(input), { paseo, signal: controller.signal });
         } catch (error) {
+          if (
+            Object.hasOwn(pluginHookRegistry, name) &&
+            pluginHookRegistry[name as keyof typeof pluginHookRegistry].waits
+          )
+            throw error;
           console.error(`Lifecycle hook ${name} failed`, error);
         }
       }
@@ -236,6 +324,36 @@ export class PluginHookHandlers implements PluginLifecycleRegistration {
     }
   }
 
+  private async openSession(
+    input: unknown,
+    context: PluginHookContext,
+  ): Promise<SessionOpenWireRequest> {
+    let request = validateBeforeRequest("agent.open.before", input);
+    this.agentTools?.detach(request.agentId);
+    let tools: AgentToolDefinition[] = [];
+    for (const handler of this.handlers.get("agent.open.before") ?? []) {
+      context.signal.throwIfAborted();
+      const result = await handler(
+        { request: { ...structuredClone(request), tools: [...tools] } },
+        context,
+      );
+      if (result === undefined) continue;
+      const local = sessionOpenLocalResultSchema.parse(result);
+      const metadata = local.tools.map(serializeAgentTool);
+      request = await validateBeforeResult("agent.open.before", request, {
+        ...local,
+        tools: metadata,
+      });
+      tools = local.tools;
+    }
+    context.signal.throwIfAborted();
+    if (request.purpose === "history") {
+      request.tools = [];
+      request.mcpServers = {};
+    } else this.agentTools?.attach(request.agentId, tools);
+    return request;
+  }
+
   cancel(id: string): void {
     this.active.get(id)?.abort();
   }
@@ -244,19 +362,14 @@ export class PluginHookHandlers implements PluginLifecycleRegistration {
     for (const controller of this.active.values()) {
       controller.abort();
     }
-    this.events.clear();
-    this.transforms.clear();
+    this.handlers.clear();
   }
 
-  private register(
-    registry: Map<string, Set<Handler>>,
-    name: string,
-    handler: Handler,
-  ): () => void {
-    let handlers = registry.get(name);
+  private register(name: string, handler: Handler): () => void {
+    let handlers = this.handlers.get(name);
     if (!handlers) {
       handlers = new Set();
-      registry.set(name, handlers);
+      this.handlers.set(name, handlers);
     }
     handlers.add(handler);
     this.changed();
@@ -265,7 +378,7 @@ export class PluginHookHandlers implements PluginLifecycleRegistration {
         return;
       }
       if (handlers.size === 0) {
-        registry.delete(name);
+        this.handlers.delete(name);
       }
       this.changed();
     };
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-paseo-api.e2e.test.ts b/packages/server/src/server/plugins/plugin-paseo-api.e2e.test.ts
index 5da355d5df..042388447b 100644
--- a/packages/server/src/server/plugins/plugin-paseo-api.e2e.test.ts
+++ b/packages/server/src/server/plugins/plugin-paseo-api.e2e.test.ts
@@ -1,3 +1,9 @@
+import { measureMainThreadWork } from "../../test-utils/main-thread-work.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import pino from "pino";
+import { createPaseoDaemon } from "../bootstrap.js";
+import { loadConfig } from "../config.js";
 import { createRequire } from "node:module";
 import { runInNewContext } from "node:vm";
 import { fileURLToPath } from "node:url";
@@ -198,6 +204,51 @@ export default function contribute(server: PluginServerContext) {
   }
 }, 60_000);
 
+test("password-protected config reload preserves startup auth and session construction does not read config", async () => {
+  const home = await mkdtemp(path.join(tmpdir(), "paseo-protected-config-reload-"));
+  roots.push(home);
+  const password = "synthetic-audit-password";
+  const config = loadConfig(home, { env: { PASEO_PASSWORD: password, PASEO_RELAY_ENABLED: "0" } });
+  const daemon = await createPaseoDaemon(
+    {
+      ...config,
+      listen: "127.0.0.1:0",
+      mcpEnabled: false,
+      agentClients: createTestAgentClients(),
+      staticDir: home,
+    },
+    pino({ level: "silent" }),
+  );
+  await daemon.start();
+  const target = daemon.getListenTarget();
+  if (target?.type !== "tcp") throw new Error("Expected TCP daemon");
+  const connect = () =>
+    new DaemonClient({ url: `ws://127.0.0.1:${target.port}/ws`, password, appVersion: "0.4.0" });
+  const client = connect();
+  const replacement = connect();
+  try {
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    const configPath = path.join(home, "config.json");
+    await writeFile(configPath, JSON.stringify({ daemon: { browserTools: { enabled: true } } }));
+    const { result: reloaded, blockingMs } = await measureMainThreadWork(
+      "daemon config reload main-thread work",
+      () => client.reloadDaemonConfig(),
+    );
+    expect(reloaded.appliedPaths).toContain("daemon.browserTools.enabled");
+    expect(blockingMs).toBeLessThan(50);
+    expect((await client.getDaemonConfig()).config.browserTools.enabled).toBe(true);
+    // A new physical session uses ready daemon state; corrupt config is reported only by an explicit read.
+    await writeFile(configPath, "invalid JSON");
+    await replacement.connect();
+    await replacement.fetchAgents({ subscribe: {} });
+    await expect(replacement.reloadDaemonConfig()).rejects.toThrow("Invalid JSON");
+  } finally {
+    await Promise.all([client.close(), replacement.close()]);
+    await daemon.stop();
+  }
+}, 60_000);
+
 test("daemon config reload enables and disables configured plugins without restarting", async () => {
   const pluginDirectory = await mkdtemp(path.join(tmpdir(), "paseo-reload-plugin-"));
   const paseoHomeRoot = await mkdtemp(path.join(tmpdir(), "paseo-reload-home-"));
@@ -465,3 +516,24 @@ export default function contribute(server: PluginServerContext) {
     await daemon.close();
   }
 }, 60_000);
+
+test("keeps reload and enable responsive while compiling a real plugin", async () => {
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-responsive-plugin-"));
+  roots.push(directory);
+  const { stdout, stderr } = await promisify(execFile)(
+    process.execPath,
+    [
+      "--import",
+      "tsx",
+      fileURLToPath(new URL("./test-fixtures/compile-responsiveness.e2e.ts", import.meta.url)),
+      directory,
+    ],
+    { timeout: 20_000 },
+  );
+  process.stderr.write(stderr);
+  const results = z
+    .array(z.object({ blockingMs: z.number() }))
+    .length(2)
+    .parse(JSON.parse(stdout));
+  for (const result of results) expect(result.blockingMs).toBeLessThan(20);
+});
diff --git a/packages/server/src/server/plugins/plugin-process-protocol.ts b/packages/server/src/server/plugins/plugin-process-protocol.ts
index b3f363cb29..8c157ed5cb 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 { PluginHookAgent } from "@getpaseo/plugin/server";
 import { UsageScopeSchema, type UsageScope } from "@getpaseo/plugin/server/usage";
 import type {
   ProviderConnectRequest,
@@ -31,6 +32,9 @@ export interface PluginUsageSourceMetadata {
 }
 
 export type PluginProcessRequest =
+  | { type: "tool.call"; requestId: string; agent: PluginHookAgent; name: string; input: unknown }
+  | { type: "tool.cancel"; requestId: string }
+  | { type: "tools.detach"; agentId: string }
   | {
       type: "provider.status";
       requestId: string;
@@ -51,11 +55,19 @@ export type PluginProcessRequest =
       providerId: string;
       options: ProviderCatalogOptions;
     }
-  | { type: "hook"; requestId: string; kind: "event" | "before"; name: string; input: unknown }
+  | { type: "hook"; requestId: string; name: string; input: unknown }
   | { type: "hook.cancel"; requestId: string }
   | { 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;
@@ -75,17 +87,20 @@ export type PluginProcessRequest =
 
 export type PluginProcessMessage =
   | { type: "settings.changed"; settingsId: string }
-  | { type: "hooks.changed"; hooks: { events: string[]; before: string[] } }
+  | { type: "hooks.changed"; hooks: string[] }
   | {
       type: "ready";
       methods: string[];
+      subscriptions?: string[];
       providers: PluginProviderMetadata[];
       usageSources?: PluginUsageSourceMetadata[];
-      hooks?: { events: string[]; before: string[] };
+      hooks?: string[];
     }
   | { 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;
@@ -105,7 +120,7 @@ export type PluginProcessMessage =
   | { type: "paseo_frame"; data: string | Uint8Array; isBinary: boolean }
   | { type: "paseo_close" };
 
-const hooksSchema = z.object({ events: z.array(z.string()), before: z.array(z.string()) }).strict();
+const hooksSchema = z.array(z.string());
 
 const providerMetadataSchema = z
   .object({
@@ -141,6 +156,26 @@ const frameFields = {
 export const PluginProcessRequestSchema: z.ZodType<PluginProcessRequest> = z.discriminatedUnion(
   "type",
   [
+    z
+      .object({
+        type: z.literal("tool.call"),
+        requestId: z.string(),
+        agent: z
+          .object({
+            id: z.string(),
+            workspaceId: z.string().nullable(),
+            parentAgentId: z.string().nullable(),
+            provider: z.string(),
+            cwd: z.string(),
+            title: z.string().nullable(),
+          })
+          .strict(),
+        name: z.string(),
+        input: z.unknown(),
+      })
+      .strict(),
+    z.object({ type: z.literal("tool.cancel"), requestId: z.string() }).strict(),
+    z.object({ type: z.literal("tools.detach"), agentId: z.string() }).strict(),
     z
       .object({
         type: z.literal("provider.status"),
@@ -187,7 +222,6 @@ export const PluginProcessRequestSchema: z.ZodType<PluginProcessRequest> = z.dis
       .object({
         type: z.literal("hook"),
         requestId: z.string(),
-        kind: z.enum(["event", "before"]),
         name: z.string(),
         input: z.unknown(),
       })
@@ -217,6 +251,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"),
@@ -249,6 +293,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(),
@@ -261,6 +306,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 5e6efa1925..1c0d6bc476 100644
--- a/packages/server/src/server/plugins/plugin-process.ts
+++ b/packages/server/src/server/plugins/plugin-process.ts
@@ -1,3 +1,4 @@
+import { PluginAgentTools } from "./agent-tools.js";
 import { PluginHookHandlers } from "./lifecycle/index.js";
 import { evaluateBundle } from "./bundle-evaluator.js";
 import {
@@ -6,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 {
@@ -23,6 +37,7 @@ import { createPluginClientId } from "./plugin-session-identity.js";
 
 import { PluginSettingsStore } from "./settings/index.js";
 import { readPluginProviderIcon } from "./provider-icon.js";
+import { initializeEnvironmentProxy } from "../network/index.js";
 function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -59,10 +74,12 @@ export function createPluginWorker(options: {
     handler: RpcHandler;
   }
 
+  const agentTools = new PluginAgentTools();
   const hooks = new PluginHookHandlers(() => {
     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<
@@ -95,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`);
@@ -281,11 +322,11 @@ 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,
+      addHook: hooks.addHook,
       on: hooks.on,
       before: hooks.before,
     });
@@ -307,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))
@@ -322,6 +364,8 @@ export function createPluginWorker(options: {
       ?.dispose()
       .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;
@@ -360,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") {
@@ -381,6 +426,50 @@ export function createPluginWorker(options: {
     }
   }
 
+  function handleToolMessage(
+    message: PluginProcessRequest,
+  ): message is Extract<
+    PluginProcessRequest,
+    { type: "tool.call" | "tool.cancel" | "tools.detach" }
+  > {
+    if (message.type === "tools.detach") {
+      agentTools.detach(message.agentId);
+      return true;
+    }
+    if (message.type === "tool.cancel") {
+      agentTools.cancel(message.requestId);
+      return true;
+    }
+    if (message.type === "tool.call") {
+      if (!paseo) {
+        send({ type: "error", requestId: message.requestId, error: "Plugin API unavailable" });
+        return true;
+      }
+      void agentTools
+        .call(message.requestId, message.agent, message.name, message.input, paseo)
+        .then((output) =>
+          send({
+            type: "result",
+            requestId: message.requestId,
+            output: jsonTransportValue(output),
+          }),
+        )
+        .catch((error) =>
+          send({ type: "error", requestId: message.requestId, error: describeError(error) }),
+        );
+      return true;
+    }
+    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) {
@@ -422,6 +511,7 @@ export function createPluginWorker(options: {
       rejectWhileStopping(message);
       return;
     }
+    if (handleToolMessage(message)) return;
     if (message.type === "provider.status") {
       void (async () => {
         const provider = providers.get(message.providerId);
@@ -483,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({
@@ -498,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) =>
@@ -523,7 +621,7 @@ export function createPluginWorker(options: {
         });
         return;
       }
-      void hooks.invoke(message.requestId, message.kind, message.name, message.input, paseo).then(
+      void hooks.invoke(message.requestId, message.name, message.input, paseo).then(
         (output) => {
           return send({ type: "result", requestId: message.requestId, output });
         },
@@ -565,6 +663,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
     const parsed = PluginProcessRequestSchema.safeParse(raw);
     if (!worker && parsed.success && parsed.data.type === "initialize") {
       try {
+        initializeEnvironmentProxy();
         worker = createPluginWorker({ channel, contribute: evaluateBundle(parsed.data.bundle) });
       } catch (error) {
         channel.send({ type: "fatal", error: describeError(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/preparation-build.ts b/packages/server/src/server/plugins/preparation-build.ts
new file mode 100644
index 0000000000..cd42772617
--- /dev/null
+++ b/packages/server/src/server/plugins/preparation-build.ts
@@ -0,0 +1,76 @@
+import { spawnProcess } from "../../utils/spawn.js";
+
+import type { PluginManifest } from "./manifest.js";
+
+const OUTPUT_LIMIT = 64 * 1024;
+
+export async function runPluginBuild(
+  directory: string,
+  commands: PluginManifest["build"],
+  logger: { info(data: Record<string, unknown>, message: string): void },
+  environment: NodeJS.ProcessEnv,
+): Promise<void> {
+  for (const command of commands ?? []) {
+    logger.info({ directory, command }, "Running plugin build command");
+    const result = await run(command, directory, environment);
+    if (result.stdout)
+      logger.info({ directory, command, output: result.stdout }, "Plugin build stdout");
+    if (result.stderr)
+      logger.info({ directory, command, output: result.stderr }, "Plugin build stderr");
+    if (result.error) {
+      throw new Error(
+        `Plugin build command failed to start: ${formatCommand(command)}\n${result.error.message}`,
+      );
+    }
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Plugin build command failed (exit ${result.exitCode}): ${formatCommand(command)}${formatOutput(result)}`,
+      );
+    }
+  }
+}
+
+function run(
+  command: string[],
+  directory: string,
+  environment: NodeJS.ProcessEnv,
+): Promise<CommandResult> {
+  return new Promise((resolve) => {
+    const executable = command[0]!;
+    const arguments_ = command.slice(1);
+    const child = spawnProcess(executable, arguments_, { cwd: directory, env: environment });
+    let stdout = "";
+    let stderr = "";
+    let error: Error | undefined;
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      stdout = appendOutput(stdout, chunk.toString());
+    });
+    child.stderr?.on("data", (chunk: Buffer | string) => {
+      stderr = appendOutput(stderr, chunk.toString());
+    });
+    child.once("error", (spawnError) => {
+      error = spawnError;
+    });
+    child.once("close", (exitCode) => resolve({ exitCode, stdout, stderr, error }));
+  });
+}
+
+function appendOutput(current: string, next: string): string {
+  return `${current}${next}`.slice(-OUTPUT_LIMIT);
+}
+
+function formatCommand(command: string[]): string {
+  return command.map((argument) => JSON.stringify(argument)).join(" ");
+}
+
+function formatOutput(result: CommandResult): string {
+  const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+  return output ? `\n${output}` : "";
+}
+
+interface CommandResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+}
diff --git a/packages/server/src/server/plugins/preparation.test.ts b/packages/server/src/server/plugins/preparation.test.ts
index 0fdb0e34fc..d83fa012e3 100644
--- a/packages/server/src/server/plugins/preparation.test.ts
+++ b/packages/server/src/server/plugins/preparation.test.ts
@@ -1,6 +1,8 @@
 import { chmod, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { Writable } from "node:stream";
+import pino from "pino";
 import { afterEach, describe, expect, it } from "vitest";
 import { createTestLogger } from "../../test-utils/test-logger.js";
 import { runPluginBuild } from "./preparation.js";
@@ -117,6 +119,52 @@ describe("runPluginBuild", () => {
     ).rejects.toThrow(/Plugin build command failed \(exit 2\)/);
   });
 
+  it("forwards build progress and output from the worker to the caller's logger", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-build-"));
+    directories.push(directory);
+    const records: Array<{ msg: string; output?: string }> = [];
+    const logger = pino(
+      new Writable({
+        write(chunk, _encoding, callback) {
+          records.push(JSON.parse(chunk.toString()));
+          callback();
+        },
+      }),
+    );
+    await runPluginBuild(
+      directory,
+      [[process.execPath, "-e", 'console.log("prepared"); console.error("diagnostic");']],
+      logger,
+    );
+    expect(records).toMatchObject([
+      { msg: "Running plugin build command" },
+      { msg: "Plugin build stdout", output: "prepared\n" },
+      { msg: "Plugin build stderr", output: expect.stringContaining("diagnostic\n") },
+    ]);
+  });
+
+  it("uses the caller's current environment across consecutive builds", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-build-"));
+    directories.push(directory);
+    const previous = process.env.PASEO_PLUGIN_TEST_BUILD_VALUE;
+    const command = [
+      process.execPath,
+      "-e",
+      'require("node:fs").writeFileSync(process.argv[1], process.env.PASEO_PLUGIN_TEST_BUILD_VALUE);',
+    ];
+    try {
+      process.env.PASEO_PLUGIN_TEST_BUILD_VALUE = "first";
+      await runPluginBuild(directory, [[...command, "first.txt"]], createTestLogger());
+      process.env.PASEO_PLUGIN_TEST_BUILD_VALUE = "second";
+      await runPluginBuild(directory, [[...command, "second.txt"]], createTestLogger());
+      expect(await readFile(path.join(directory, "first.txt"), "utf8")).toBe("first");
+      expect(await readFile(path.join(directory, "second.txt"), "utf8")).toBe("second");
+    } finally {
+      if (previous === undefined) delete process.env.PASEO_PLUGIN_TEST_BUILD_VALUE;
+      else process.env.PASEO_PLUGIN_TEST_BUILD_VALUE = previous;
+    }
+  });
+
   it("handles empty or undefined build commands gracefully", async () => {
     const directory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-build-"));
     directories.push(directory);
diff --git a/packages/server/src/server/plugins/preparation.ts b/packages/server/src/server/plugins/preparation.ts
index 267f9697e9..79aec65cdc 100644
--- a/packages/server/src/server/plugins/preparation.ts
+++ b/packages/server/src/server/plugins/preparation.ts
@@ -1,71 +1,15 @@
-import { spawnProcess } from "../../utils/spawn.js";
 import type pino from "pino";
 import type { PluginManifest } from "./manifest.js";
-
-const OUTPUT_LIMIT = 64 * 1024;
+import { runCompilerTask } from "./compiler.js";
 
 export async function runPluginBuild(
   directory: string,
   commands: PluginManifest["build"],
   logger: pino.Logger,
 ): Promise<void> {
-  for (const command of commands ?? []) {
-    logger.info({ directory, command }, "Running plugin build command");
-    const result = await run(command, directory);
-    if (result.stdout)
-      logger.info({ directory, command, output: result.stdout }, "Plugin build stdout");
-    if (result.stderr)
-      logger.info({ directory, command, output: result.stderr }, "Plugin build stderr");
-    if (result.error) {
-      throw new Error(
-        `Plugin build command failed to start: ${formatCommand(command)}\n${result.error.message}`,
-      );
-    }
-    if (result.exitCode !== 0) {
-      throw new Error(
-        `Plugin build command failed (exit ${result.exitCode}): ${formatCommand(command)}${formatOutput(result)}`,
-      );
-    }
-  }
-}
-
-function run(command: string[], directory: string): Promise<CommandResult> {
-  return new Promise((resolve) => {
-    const executable = command[0]!;
-    const arguments_ = command.slice(1);
-    const child = spawnProcess(executable, arguments_, { cwd: directory });
-    let stdout = "";
-    let stderr = "";
-    let error: Error | undefined;
-    child.stdout?.on("data", (chunk: Buffer | string) => {
-      stdout = appendOutput(stdout, chunk.toString());
-    });
-    child.stderr?.on("data", (chunk: Buffer | string) => {
-      stderr = appendOutput(stderr, chunk.toString());
-    });
-    child.once("error", (spawnError) => {
-      error = spawnError;
-    });
-    child.once("close", (exitCode) => resolve({ exitCode, stdout, stderr, error }));
-  });
-}
-
-function appendOutput(current: string, next: string): string {
-  return `${current}${next}`.slice(-OUTPUT_LIMIT);
-}
-
-function formatCommand(command: string[]): string {
-  return command.map((argument) => JSON.stringify(argument)).join(" ");
-}
-
-function formatOutput(result: CommandResult): string {
-  const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
-  return output ? `\n${output}` : "";
-}
-
-interface CommandResult {
-  exitCode: number | null;
-  stdout: string;
-  stderr: string;
-  error?: Error;
+  if (!commands?.length) return;
+  await runCompilerTask(
+    { kind: "prepare", directory, commands, environment: { ...process.env } },
+    (data, message) => logger.info(data, message),
+  );
 }
diff --git a/packages/server/src/server/plugins/requirements.posix.test.ts b/packages/server/src/server/plugins/requirements.posix.test.ts
index 65462336a3..597d907e18 100644
--- a/packages/server/src/server/plugins/requirements.posix.test.ts
+++ b/packages/server/src/server/plugins/requirements.posix.test.ts
@@ -1,4 +1,5 @@
 import { mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -68,9 +69,18 @@ it("rejects incompatible installs without persisting them, then accepts the corr
   await expect(service.installDirectory({ path: root })).resolves.toMatchObject({
     status: "running",
   });
-  expect(service.catalog()).toEqual([
-    { id: "example", requirements: { paseo: "^0.8.0" }, clientBundle: expect.any(String) },
+  const catalog = service.catalog();
+  expect(catalog).toEqual([
+    {
+      id: "example",
+      requirements: { paseo: "^0.8.0" },
+      clientBundle: expect.any(String),
+      clientBundleHash: expect.any(String),
+    },
   ]);
+  expect(catalog[0]!.clientBundleHash).toBe(
+    createHash("sha256").update(catalog[0]!.clientBundle).digest("hex"),
+  );
 });
 
 it("marks pre-0.8 plugins failed on startup and recovers after migration and reload", async () => {
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 8dd80ce499..1b2e7192c7 100644
--- a/packages/server/src/server/plugins/runtime.posix.test.ts
+++ b/packages/server/src/server/plugins/runtime.posix.test.ts
@@ -1,5 +1,6 @@
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { fork } from "node:child_process";
+import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import { PassThrough } from "node:stream";
 import path from "node:path";
@@ -10,6 +11,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import type { AgentStreamEvent } from "../agent/agent-sdk-types.js";
 import { PluginAgentClientRegistry } from "../agent/plugin-provider.js";
 import { PluginRuntime } from "./runtime.js";
+import { resolveDaemonVersion } from "../daemon-version.js";
 import type { PluginSessionSocket } from "./session-socket.js";
 
 const temporaryDirectories: string[] = [];
@@ -106,6 +108,12 @@ function createReloadChild(
   };
 }
 
+function sha256(text: string | undefined): string {
+  return createHash("sha256")
+    .update(text ?? "")
+    .digest("hex");
+}
+
 function createTestRuntime(
   dependencies: NonNullable<ConstructorParameters<typeof PluginRuntime>[2]> = {},
   logger = pino({ level: "silent" }),
@@ -651,7 +659,8 @@ lines.on("line", (line) => {
         type: "timeline.item",
         item: expect.objectContaining({
           type: "assistant_message",
-          id: "assistant-1",
+          id: JSON.stringify(["agent_message_chunk", "assistant-1"]),
+          messageId: "assistant-1",
           text: "ACP says hi",
         }),
       }),
@@ -1390,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 {
@@ -1535,6 +1582,7 @@ export default function contribute(server: { registerProvider(provider: Provider
 
     expect(spawnChild).not.toHaveBeenCalled();
     expect(runtime.catalog()[0]?.clientBundle).toContain("addTheme");
+    expect(runtime.catalog()[0]?.clientBundleHash).toBe(sha256(runtime.catalog()[0]?.clientBundle));
     await runtime.stopAll();
   });
 
@@ -1697,6 +1745,7 @@ export function inspectHost(_input: z.input<typeof inspectRpc.input>) {
     const plugin = runtime.catalog()[0];
     expect(plugin?.clientBundle).toContain("Client-only surface");
     expect(plugin?.clientBundle).not.toContain("node:os");
+    expect(plugin?.clientBundleHash).toBe(sha256(plugin?.clientBundle));
     await expect(runtime.invoke("split-runtime", "inspect", {})).resolves.toMatchObject({
       platform: expect.any(String),
     });
@@ -1804,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";
@@ -1823,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();
   });
 
@@ -1849,9 +1900,9 @@ export default function contribute(plugin: any) {
     const child = createReloadChild("blocked", events);
     const runtime = createTestRuntime({ spawnChild: () => child });
 
-    await expect(runtime.startPlugin("blocked", directory, () => false)).rejects.toThrow(
-      "Plugin start cancelled: blocked",
-    );
+    await expect(
+      runtime.startPlugin("blocked", directory, () => events.length === 0),
+    ).rejects.toThrow("Plugin start cancelled: blocked");
 
     expect(runtime.catalog()).toEqual([]);
     expect(events).toEqual(["start:blocked", "shutdown:blocked", "exit:blocked"]);
@@ -2055,3 +2106,54 @@ export default function contribute(server) {
     await runtime.stopAll();
   }
 });
+
+const examplesDirectory = fileURLToPath(
+  new URL("../../../../../plugin-examples/", import.meta.url),
+);
+// The Markdown example owns npm preparation in the real app fixture:
+// packages/app/e2e/browser/plugin-file-panel-examples.spec.ts.
+const examples = (await readdir(examplesDirectory, { withFileTypes: true }))
+  .filter((entry) => entry.isDirectory() && entry.name !== "markdown-panel")
+  .map((entry) => entry.name);
+
+it.each(examples)("builds and loads the %s plugin example", async (example) => {
+  const settingsDirectory = await mkdtemp(path.join(tmpdir(), "paseo-example-settings-"));
+  temporaryDirectories.push(settingsDirectory);
+  const runtime = createTestRuntime(
+    { settingsDirectory },
+    undefined,
+    resolveDaemonVersion(import.meta.url),
+  );
+  try {
+    await runtime.startPlugin(example, path.join(examplesDirectory, example));
+    expect(runtime.catalog()).toMatchObject([{ id: example }]);
+    expect(pluginMessages(runtime, example)).toContain("[paseo] Plugin ready");
+  } finally {
+    await runtime.stopAll();
+  }
+});
+
+it("does not initialize a plugin cancelled during compilation", async () => {
+  const directory = await createPlugin("cancelled-build", "export default () => {};");
+  const marker = path.join(directory, "initialized.txt");
+  await writeFile(
+    path.join(directory, "index.server.ts"),
+    `
+import { writeFileSync } from "node:fs";
+export default function contribute() {
+  writeFileSync(${JSON.stringify(marker)}, "initialized");
+  return () => {};
+}`,
+  );
+  const runtime = createTestRuntime();
+  let allowed = true;
+  try {
+    const loading = runtime.startPlugin("cancelled-build", directory, () => allowed);
+    allowed = false;
+    await expect(loading).rejects.toThrow("Plugin start cancelled: cancelled-build");
+    expect(await readTextIfPresent(marker)).toBeNull();
+    expect(runtime.catalog()).toEqual([]);
+  } finally {
+    await runtime.stopAll();
+  }
+});
diff --git a/packages/server/src/server/plugins/runtime.ts b/packages/server/src/server/plugins/runtime.ts
index 9886a368e7..98cbf8fcf0 100644
--- a/packages/server/src/server/plugins/runtime.ts
+++ b/packages/server/src/server/plugins/runtime.ts
@@ -1,16 +1,19 @@
+import { validateWorktreePath } from "../../utils/worktree-path.js";
+import type { PluginHookPayload } from "@getpaseo/plugin/server";
+import type { PluginWireBeforeRequests, PluginBeforeResults } from "./lifecycle/index.js";
+import type { SessionOpenWireRequest, AttachedAgentTool } from "./agent-tools.js";
 import type { UsageScope } from "@getpaseo/plugin/server/usage";
 import {
   ProviderStatusSchema,
   type ProviderStatus,
   type ProviderStatusRequest,
 } from "@getpaseo/plugin/server/provider";
-import type { PluginBeforeRequests, PluginLifecycleEvents } from "@getpaseo/plugin/server";
+import type { PluginHookEvents, PluginHookAgent, AgentToolResult } from "@getpaseo/plugin/server";
 import { validateBeforeRequest, validateBeforeResult } from "./lifecycle/index.js";
 import { fork } from "node:child_process";
-import { stat } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import type pino from "pino";
 import {
   PROVIDER_CAPABILITIES,
@@ -22,10 +25,8 @@ import {
   type ProviderInput,
 } from "@getpaseo/plugin/server/provider";
 import type { PluginLogEntry } from "@getpaseo/protocol/messages";
-import { compilePlugin } from "./compiler.js";
-import { readPluginManifest } from "./manifest.js";
+import { compileDirectoryPlugin } from "./compiler.js";
 import type { PluginRequirements } from "@getpaseo/protocol/messages";
-import { assertPluginCompatibility } from "@getpaseo/protocol/plugin-requirements";
 import type {
   PluginProcessMessage,
   PluginProcessRequest,
@@ -33,13 +34,16 @@ 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";
 
-const CLIENT_ENTRY_FILENAMES = ["index.client.ts", "index.client.tsx"] as const;
-const SERVER_ENTRY_FILENAMES = ["index.server.ts", "index.server.tsx"] as const;
 const REQUEST_TIMEOUT_MS = 30_000;
+const TOOL_CALL_TIMEOUT_MS = 10 * 60_000;
 const MAX_LOG_ENTRIES = 500;
 const MAX_LOG_BYTES = 256 * 1024;
 const MAX_LOG_LINE_BYTES = 16 * 1024;
@@ -69,10 +73,15 @@ interface PendingInvocation {
 
 interface LoadedPlugin {
   id: string;
+  instanceId: string;
   requirements: PluginRequirements | undefined;
   clientBundle: string;
+  /** Lets a client that already holds this bundle skip downloading it again. */
+  clientBundleHash: string;
   methods: ReadonlySet<string>;
-  hooks: { events: string[]; before: string[] };
+  subscriptionMethods: ReadonlySet<string>;
+  subscriptions: Map<string, BufferedPluginSubscription>;
+  hooks: string[];
   providers: readonly PluginProviderMetadata[];
   usageSources: readonly PluginUsageSourceMetadata[];
   child: PluginChild | null;
@@ -243,6 +252,10 @@ function terminatePluginChild(child: PluginChild): void {
   if (!child.killed) child.kill();
 }
 
+function hashClientBundle(clientBundle: string): string {
+  return createHash("sha256").update(clientBundle).digest("hex");
+}
+
 function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -265,35 +278,6 @@ function send(child: PluginChild, message: PluginProcessRequest): Promise<void>
   });
 }
 
-async function findEntry(directory: string, filenames: readonly string[]): Promise<string | null> {
-  for (const filename of filenames) {
-    const filePath = path.join(directory, filename);
-    const info = await stat(filePath).catch(() => null);
-    if (info?.isFile()) return filePath;
-  }
-  return null;
-}
-
-async function resolveEntryPaths(directory: string): Promise<{
-  client: string | null;
-  server: string | null;
-}> {
-  const [client, server] = await Promise.all([
-    findEntry(directory, CLIENT_ENTRY_FILENAMES),
-    findEntry(directory, SERVER_ENTRY_FILENAMES),
-  ]);
-  if (client || server) return { client, server };
-  const legacyEntry = await findEntry(directory, ["index.ts", "index.tsx"]);
-  if (legacyEntry) {
-    throw new Error(
-      "This plugin was made for an older version of Paseo and cannot run on Paseo v0.8. Ask its author to update it. Plugin authors can follow the migration guide: https://paseo.sh/docs/plugins/migration",
-    );
-  }
-  throw new Error(
-    `Plugin entry points are missing: expected ${CLIENT_ENTRY_FILENAMES.join(" or ")} and/or ${SERVER_ENTRY_FILENAMES.join(" or ")} in ${directory}`,
-  );
-}
-
 export class PluginRuntime {
   private readonly plugins = new Map<string, LoadedPlugin>();
   private readonly pendingEvents = new Set<Promise<void>>();
@@ -302,6 +286,7 @@ export class PluginRuntime {
   private readonly spawnChild: () => PluginChild;
   private sessionHost: PluginPaseoSessionHost | null;
   private readonly listeners = new Set<(pluginId: string, error?: string) => void>();
+  private readonly sessionOpenListeners = new Set<() => void>();
 
   constructor(
     logger: pino.Logger,
@@ -324,6 +309,16 @@ export class PluginRuntime {
     return () => this.listeners.delete(listener);
   }
 
+  subscribeSessionOpenChanges(listener: () => void): () => void {
+    this.sessionOpenListeners.add(listener);
+    return () => this.sessionOpenListeners.delete(listener);
+  }
+
+  private notifySessionOpenChange(loaded: LoadedPlugin): void {
+    if (!loaded.hooks.includes("agent.open.before")) return;
+    for (const listener of this.sessionOpenListeners) listener();
+  }
+
   async startPlugin(
     pluginId: string,
     configuredPath: string,
@@ -331,15 +326,22 @@ export class PluginRuntime {
   ): Promise<void> {
     if (this.plugins.has(pluginId)) throw new Error(`Plugin is already running: ${pluginId}`);
     this.appendLog(pluginId, "stdout", "[paseo] Loading plugin");
-    const loaded = await this.loadDirectoryPlugin(pluginId, configuredPath).catch((error) => {
-      this.appendLog(pluginId, "stderr", `[paseo] Plugin failed to load: ${describeError(error)}`);
-      throw error;
-    });
+    const loaded = await this.loadDirectoryPlugin(pluginId, configuredPath, canPublish).catch(
+      (error) => {
+        this.appendLog(
+          pluginId,
+          "stderr",
+          `[paseo] Plugin failed to load: ${describeError(error)}`,
+        );
+        throw error;
+      },
+    );
     if (!canPublish()) {
       await this.stopPlugin(loaded);
       throw new Error(`Plugin start cancelled: ${pluginId}`);
     }
     this.plugins.set(pluginId, loaded);
+    this.notifySessionOpenChange(loaded);
     this.appendLog(pluginId, "stdout", "[paseo] Plugin ready");
   }
 
@@ -347,12 +349,8 @@ export class PluginRuntime {
     if (this.plugins.has(input.id)) throw new Error(`Plugin is already running: ${input.id}`);
     this.appendLog(input.id, "stdout", "[paseo] Loading plugin");
     const directory = path.resolve(input.directory);
-    const manifest = await readPluginManifest(directory);
-    if (manifest.id !== input.id) {
-      throw new Error(`Built-in plugin ${input.id} has manifest ID ${manifest.id}`);
-    }
-    assertPluginCompatibility({ ...manifest, version: this.daemonVersion, runtime: "daemon" });
-    const bundles = await compilePlugin(await resolveEntryPaths(directory));
+    const bundles = await compileDirectoryPlugin(directory, this.daemonVersion, input.id);
+    const { manifest } = bundles;
     if (!bundles.serverBundle) throw new Error(`Built-in plugin ${input.id} needs a server entry`);
     const loaded = await this.launchPlugin({
       pluginId: input.id,
@@ -363,29 +361,37 @@ export class PluginRuntime {
       clientBundle: bundles.clientBundle ?? "",
     });
     this.plugins.set(input.id, loaded);
+    this.notifySessionOpenChange(loaded);
     this.appendLog(input.id, "stdout", "[paseo] Plugin ready");
   }
 
   async validatePlugin(configuredPath: string): Promise<void> {
-    const directory = path.resolve(configuredPath);
-    const manifest = await readPluginManifest(directory);
-    assertPluginCompatibility({ ...manifest, version: this.daemonVersion, runtime: "daemon" });
-    const entryPaths = await resolveEntryPaths(directory);
-    await compilePlugin(entryPaths);
+    await compileDirectoryPlugin(path.resolve(configuredPath), this.daemonVersion);
   }
 
   async stopPluginById(pluginId: string): Promise<boolean> {
     const loaded = this.plugins.get(pluginId);
     if (!loaded) return false;
     this.plugins.delete(pluginId);
+    this.notifySessionOpenChange(loaded);
     this.rejectPending(loaded, `Plugin stopped: ${pluginId}`);
     await this.stopPlugin(loaded);
     return true;
   }
 
-  catalog(): Array<{ id: string; clientBundle: string; requirements?: PluginRequirements }> {
+  catalog(): Array<{
+    id: string;
+    clientBundle: string;
+    clientBundleHash: string;
+    requirements?: PluginRequirements;
+  }> {
     return [...this.plugins.values()]
-      .map(({ id, clientBundle, requirements }) => ({ id, clientBundle, requirements }))
+      .map(({ id, clientBundle, clientBundleHash, requirements }) => ({
+        id,
+        clientBundle,
+        clientBundleHash,
+        requirements,
+      }))
       .sort((left, right) => left.id.localeCompare(right.id));
   }
 
@@ -514,18 +520,48 @@ export class PluginRuntime {
     return this.request(loaded, { type: "invoke", requestId: randomUUID(), method, input });
   }
 
-  emit<Name extends keyof PluginLifecycleEvents>(
-    name: Name,
-    event: PluginLifecycleEvents[Name],
-  ): void {
+  /** 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.events.includes(name)) {
+      if (!loaded.hooks.includes(name)) {
         continue;
       }
       const request = this.request(loaded, {
         type: "hook",
         requestId: randomUUID(),
-        kind: "event",
         name,
         input: event,
       })
@@ -546,33 +582,76 @@ export class PluginRuntime {
     await Promise.all(this.pendingEvents);
   }
 
-  async before<Name extends keyof PluginBeforeRequests>(
+  async wait(
+    name: "worktree.create.after",
+    payload: PluginHookPayload<"worktree.create.after">,
+  ): Promise<void> {
+    const plugins = [...this.plugins.values()].sort((left, right) =>
+      left.id.localeCompare(right.id),
+    );
+    for (const loaded of plugins) {
+      if (!loaded.hooks.includes(name)) continue;
+      try {
+        await this.request(loaded, { type: "hook", requestId: randomUUID(), name, input: payload });
+      } catch (error) {
+        throw new Error(`Plugin ${loaded.id} ${name} failed: ${describeError(error)}`, {
+          cause: error,
+        });
+      }
+    }
+  }
+
+  async before<Name extends keyof PluginWireBeforeRequests>(
     name: Name,
-    input: PluginBeforeRequests[Name],
-  ): Promise<PluginBeforeRequests[Name]> {
+    input: PluginWireBeforeRequests[Name],
+  ): Promise<PluginBeforeResults[Name]> {
     let request = validateBeforeRequest(name, input);
     const plugins = [...this.plugins.values()].sort((left, right) => {
       return left.id.localeCompare(right.id);
     });
+    const attached: AttachedAgentTool[] = [];
+    const mcpServers: SessionOpenWireRequest["mcpServers"] = {};
+    const mcpServerOwners: Record<string, string> = {};
     for (const loaded of plugins) {
-      if (!loaded.hooks.before.includes(name)) {
+      if (!loaded.hooks.includes(name)) {
         continue;
       }
       try {
         const output = await this.request(loaded, {
           type: "hook",
           requestId: randomUUID(),
-          kind: "before",
           name,
-          input: request,
+          input: name === "agent.open.before" ? { ...request, tools: [], mcpServers: {} } : request,
         });
-        request = validateBeforeResult(name, request, output);
+        request = await validateBeforeResult(name, request, output);
+        if (name === "worktree.create.before") {
+          const worktree = request as PluginWireBeforeRequests["worktree.create.before"];
+          worktree.path = await validateWorktreePath({
+            candidate: worktree.path,
+            repoPath: worktree.repoRoot,
+          });
+        }
+        if (name === "agent.open.before") {
+          const opened = request as SessionOpenWireRequest;
+          this.collectMcpServers(mcpServers, mcpServerOwners, loaded, opened.mcpServers);
+          this.collectAgentTools(attached, loaded, opened.tools);
+        }
       } catch (error) {
-        throw new Error(`Plugin ${loaded.id} before ${name} failed: ${describeError(error)}`, {
+        if (name === "agent.open.before")
+          this.detachTools((request as SessionOpenWireRequest).agentId);
+        throw new Error(`Plugin ${loaded.id} ${name} failed: ${describeError(error)}`, {
           cause: error,
         });
       }
     }
+    if (name === "agent.open.before") {
+      return {
+        ...request,
+        tools: attached,
+        mcpServers,
+        mcpServerOwners,
+      } as PluginBeforeResults[Name];
+    }
     return request;
   }
 
@@ -594,25 +673,124 @@ export class PluginRuntime {
     return output;
   }
 
+  private collectMcpServers(
+    servers: SessionOpenWireRequest["mcpServers"],
+    owners: Record<string, string>,
+    loaded: LoadedPlugin,
+    contributions: SessionOpenWireRequest["mcpServers"],
+  ): void {
+    for (const [name, server] of Object.entries(contributions)) {
+      if (Object.hasOwn(servers, name)) {
+        throw new Error(
+          `MCP server ${name} from plugin ${loaded.id} collides with plugin ${owners[name]}`,
+        );
+      }
+      servers[name] = server;
+      owners[name] = loaded.id;
+    }
+  }
+
+  private collectAgentTools(
+    attached: AttachedAgentTool[],
+    loaded: LoadedPlugin,
+    tools: SessionOpenWireRequest["tools"],
+  ): void {
+    for (const tool of tools) {
+      const collision = attached.find((entry) => entry.name === tool.name);
+      if (collision)
+        throw new Error(
+          `Agent tool ${tool.name} from plugin ${loaded.id} collides with plugin ${collision.pluginId}`,
+        );
+      attached.push({ ...tool, pluginId: loaded.id, pluginInstanceId: loaded.instanceId });
+    }
+  }
+
+  isToolPluginAvailable(pluginId: string, pluginInstanceId: string): boolean {
+    return this.plugins.get(pluginId)?.instanceId === pluginInstanceId;
+  }
+
+  detachTools(agentId: string): void {
+    for (const loaded of this.plugins.values()) {
+      if (loaded.child) void send(loaded.child, { type: "tools.detach", agentId }).catch(() => {});
+    }
+  }
+
+  async callTool(
+    pluginId: string,
+    pluginInstanceId: string,
+    agent: PluginHookAgent,
+    name: string,
+    input: unknown,
+    signal?: AbortSignal,
+  ): Promise<AgentToolResult> {
+    const loaded = this.plugins.get(pluginId);
+    if (!loaded || loaded.instanceId !== pluginInstanceId)
+      return { isError: true, text: `Plugin is not available: ${pluginId}` };
+    const requestId = randomUUID();
+    try {
+      return (await this.request(
+        loaded,
+        { type: "tool.call", requestId, agent, name, input },
+        signal,
+      )) as AgentToolResult;
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      return { isError: true, text: describeError(error) };
+    }
+  }
+
   private request(
     loaded: LoadedPlugin,
     message: Extract<PluginProcessRequest, { requestId: string }>,
+    signal?: AbortSignal,
   ): Promise<unknown> {
     const child = loaded.child;
     const pluginId = loaded.id;
     if (!child) throw new Error(`Plugin ${pluginId} has no server entry`);
     const requestId = message.requestId;
+    signal?.throwIfAborted();
     return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
+      const cancel = () => {
+        clearTimeout(timeout);
         loaded.pending.delete(requestId);
-        if (message.type === "hook") {
-          void send(child, { type: "hook.cancel", requestId }).catch(() => {});
-        }
-        reject(new Error(`Plugin RPC timed out: ${pluginId}.${message.type}`));
-      }, REQUEST_TIMEOUT_MS);
-      loaded.pending.set(requestId, { resolve, reject, timeout });
+        if (message.type === "tool.call")
+          void send(child, { type: "tool.cancel", requestId }).catch(() => {});
+        signal?.removeEventListener("abort", cancel);
+        reject(signal?.reason ?? new Error("Tool call canceled"));
+      };
+      const timeout = setTimeout(
+        () => {
+          loaded.pending.delete(requestId);
+          signal?.removeEventListener("abort", cancel);
+          if (message.type === "tool.call")
+            void send(child, { type: "tool.cancel", requestId }).catch(() => {});
+          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,
+      );
+      signal?.addEventListener("abort", cancel, { once: true });
+      loaded.pending.set(requestId, {
+        resolve: (value) => {
+          signal?.removeEventListener("abort", cancel);
+          resolve(value);
+        },
+        reject: (error) => {
+          signal?.removeEventListener("abort", cancel);
+          reject(error);
+        },
+        timeout,
+      });
       void send(child, message).catch((error) => {
         clearTimeout(timeout);
+        signal?.removeEventListener("abort", cancel);
         loaded.pending.delete(requestId);
         reject(error);
       });
@@ -623,6 +801,7 @@ export class PluginRuntime {
     const loaded = [...this.plugins.values()];
     this.plugins.clear();
     for (const plugin of loaded) {
+      this.notifySessionOpenChange(plugin);
       this.rejectPending(plugin, `Plugin stopped: ${plugin.id}`);
     }
     await Promise.all(loaded.map((plugin) => this.stopPlugin(plugin)));
@@ -631,20 +810,25 @@ export class PluginRuntime {
   private async loadDirectoryPlugin(
     pluginId: string,
     configuredPath: string,
+    canPublish: () => boolean,
   ): Promise<LoadedPlugin> {
     const directory = path.resolve(configuredPath);
-    const manifest = await readPluginManifest(directory);
-    assertPluginCompatibility({ ...manifest, version: this.daemonVersion, runtime: "daemon" });
-    const entryPaths = await resolveEntryPaths(directory);
-    const bundles = await compilePlugin(entryPaths);
+    const bundles = await compileDirectoryPlugin(directory, this.daemonVersion);
+    const { manifest } = bundles;
+    if (!canPublish()) throw new Error(`Plugin start cancelled: ${pluginId}`);
     const serverBundle = bundles.serverBundle;
     if (!serverBundle) {
+      const clientBundle = bundles.clientBundle ?? "";
       return {
         id: pluginId,
-        clientBundle: bundles.clientBundle ?? "",
+        instanceId: randomUUID(),
+        clientBundle,
+        clientBundleHash: hashClientBundle(clientBundle),
         requirements: manifest.requirements,
         methods: new Set(),
-        hooks: { events: [], before: [] },
+        subscriptionMethods: new Set(),
+        subscriptions: new Map(),
+        hooks: [],
         providers: [],
         usageSources: [],
         child: null,
@@ -769,10 +953,14 @@ export class PluginRuntime {
     }
     loaded = {
       id: pluginId,
+      instanceId: randomUUID(),
       clientBundle,
+      clientBundleHash: hashClientBundle(clientBundle),
       requirements,
       methods: new Set(ready.methods),
-      hooks: ready.hooks ?? { events: [], before: [] },
+      subscriptionMethods: new Set(ready.subscriptions ?? []),
+      subscriptions: new Map(),
+      hooks: ready.hooks ?? [],
       providers: ready.providers ?? [],
       usageSources: ready.usageSources ?? [],
       child,
@@ -852,7 +1040,14 @@ export class PluginRuntime {
 
   private handleChildMessage(loaded: LoadedPlugin, message: PluginProcessMessage): void {
     if (message.type === "hooks.changed") {
+      const hadSessionOpen = loaded.hooks.includes("agent.open.before");
       loaded.hooks = message.hooks;
+      if (
+        this.plugins.get(loaded.id) === loaded &&
+        hadSessionOpen !== loaded.hooks.includes("agent.open.before")
+      ) {
+        for (const listener of this.sessionOpenListeners) listener();
+      }
       return;
     }
     if (message.type === "settings.changed") {
@@ -863,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;
@@ -1166,6 +1371,7 @@ export class PluginRuntime {
     const wasPublished = this.plugins.get(loaded.id) === loaded;
     if (wasPublished) {
       this.plugins.delete(loaded.id);
+      this.notifySessionOpenChange(loaded);
     }
     this.rejectPending(loaded, `Plugin process exited: ${loaded.id}`);
     for (const state of loaded.providerConnections.values()) {
@@ -1220,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/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/plugins/test-fixtures/compile-responsiveness.e2e.ts b/packages/server/src/server/plugins/test-fixtures/compile-responsiveness.e2e.ts
new file mode 100644
index 0000000000..95aaec0d6a
--- /dev/null
+++ b/packages/server/src/server/plugins/test-fixtures/compile-responsiveness.e2e.ts
@@ -0,0 +1,69 @@
+import { measureMainThreadWork } from "../../../test-utils/main-thread-work.js";
+import assert from "node:assert/strict";
+import { open as openFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import pino from "pino";
+import { DaemonConfigStore } from "../../daemon-config-store.js";
+import { PluginService } from "../index.js";
+
+// A fresh process excludes the E2E harness's transform/bootstrap garbage from
+// the compiler measurement. All work and dependencies below are real.
+const directory = process.argv[2];
+assert.ok(directory, "Fixture directory is required");
+const results: { blockingMs: number }[] = [];
+await writeFile(
+  path.join(directory, "paseo-plugin.json"),
+  JSON.stringify({ id: "responsive-build" }),
+);
+// Erased types stress TypeScript's AST walk without a multi-MiB runtime bundle.
+// Payload transfer is a different cost from import validation.
+const entryFile = await openFile(path.join(directory, "index.client.ts"), "w");
+try {
+  await entryFile.write("type FixtureValues = [");
+  for (let offset = 0; offset < 350_000; offset += 10_000) {
+    await entryFile.write(
+      Array.from({ length: 10_000 }, (_, index) => offset + index).join(",") + ",",
+    );
+  }
+  await entryFile.write(
+    ']; export default function contribute() { return () => "compiled fixture"; }',
+  );
+} finally {
+  await entryFile.close();
+}
+const store = new DaemonConfigStore(directory, {
+  mcp: { injectIntoAgents: true },
+  browserTools: { enabled: false },
+  providers: {},
+  metadataGeneration: { providers: [] },
+  autoArchiveAfterMerge: false,
+  enableTerminalAgentHooks: false,
+  appendSystemPrompt: "",
+  pluginsEnabled: true,
+  plugins: {
+    "responsive-build": { source: "directory", path: directory, enabled: false },
+  },
+});
+const service = new PluginService(pino({ level: "silent" }), store, "0.4.0");
+await service.start();
+try {
+  for (const action of [
+    () => service.enablePlugin("responsive-build"),
+    () => service.reloadPlugin("responsive-build"),
+  ]) {
+    const { blockingMs } = await measureMainThreadWork("plugin compile main-thread work", action);
+    assert.ok(service.catalog()[0]?.clientBundle.includes("compiled fixture"));
+    results.push({ blockingMs });
+  }
+  // Evaluate after both probes so parsing the returned code is not charged to compilation.
+  const factory = globalThis.eval(service.catalog()[0]!.clientBundle) as (
+    require: (specifier: string) => never,
+  ) => { default: () => () => string };
+  const result = factory((specifier) => {
+    throw new Error(`Unexpected fixture dependency: ${specifier}`);
+  }).default()();
+  assert.equal(result, "compiled fixture");
+} finally {
+  await service.stopAllPlugins();
+}
+process.stdout.write(JSON.stringify(results));
diff --git a/packages/server/src/server/plugins/test-fixtures/usage-proxy-daemon.ts b/packages/server/src/server/plugins/test-fixtures/usage-proxy-daemon.ts
new file mode 100644
index 0000000000..23364d3fda
--- /dev/null
+++ b/packages/server/src/server/plugins/test-fixtures/usage-proxy-daemon.ts
@@ -0,0 +1,31 @@
+import path from "node:path";
+import { initializeEnvironmentProxy } from "../../network/index.js";
+import { DaemonClient } from "../../test-utils/daemon-client.js";
+import { createTestPaseoDaemon } from "../../test-utils/paseo-daemon.js";
+import { BuiltinPluginLoader, resolveBuiltinPluginsRoot } from "../builtin/index.js";
+
+const mode = process.argv[2];
+if (mode !== "builtin" && mode !== "directory") throw new Error("Expected builtin or directory");
+const sources = ["claude-usage-source", "codex-usage-source"];
+// Built-ins run inside the daemon; directory plugins initialize their own subprocess network.
+if (mode === "builtin") initializeEnvironmentProxy();
+const daemon = await createTestPaseoDaemon({
+  pluginsEnabled: mode === "directory",
+  builtinPlugins: new BuiltinPluginLoader(
+    resolveBuiltinPluginsRoot(),
+    mode === "builtin" ? sources : [],
+  ),
+});
+const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+try {
+  await client.connect();
+  if (mode === "directory") {
+    for (const source of sources) {
+      await client.installDirectoryPlugin(path.join(resolveBuiltinPluginsRoot(), source), source);
+    }
+  }
+  await client.listUsageReports();
+} finally {
+  await client.close();
+  await daemon.close();
+}
diff --git a/packages/server/src/server/plugins/usage-sources.e2e.test.ts b/packages/server/src/server/plugins/usage-sources.e2e.test.ts
index 037da5e0c6..46dc134ff6 100644
--- a/packages/server/src/server/plugins/usage-sources.e2e.test.ts
+++ b/packages/server/src/server/plugins/usage-sources.e2e.test.ts
@@ -1,7 +1,11 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { cp, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { createServer } from "node:http";
+import { once } from "node:events";
 import { expect, test } from "vitest";
 import { DaemonClient } from "../test-utils/daemon-client.js";
 import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
@@ -335,3 +339,74 @@ export default function contribute(server) {
     await rm(root, { recursive: true, force: true });
   }
 }, 60_000);
+
+test.each(["builtin", "directory"])(
+  "%s usage plugins reach the environment proxy",
+  async (mode) => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "usage-proxy-"));
+    const tunnels: string[] = [];
+    const proxy = createServer();
+    proxy.on("connect", (request, socket) => {
+      tunnels.push(request.url!);
+      socket.end("HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n");
+    });
+    proxy.listen(0, "127.0.0.1");
+    await once(proxy, "listening");
+    const address = proxy.address();
+    if (!address || typeof address === "string") throw new Error("Missing proxy address");
+    const guard = path.join(root, "network-guard.cjs");
+    // Prevent vendor DNS/network access even when proxy support is broken.
+    await writeFile(
+      guard,
+      `const dns = require('node:dns');
+const lookup = dns.lookup;
+dns.lookup = function(host, ...args) {
+  if (host === 'localhost' || host === '127.0.0.1' || host === '::1') return lookup.call(this, host, ...args);
+  args.at(-1)(Object.assign(new Error('External DNS forbidden in proxy test'), { code: 'ENOTFOUND' }));
+};`,
+    );
+    await mkdir(path.join(root, ".claude"));
+    await mkdir(path.join(root, ".codex"));
+    await writeFile(
+      path.join(root, ".claude", ".credentials.json"),
+      JSON.stringify({ claudeAiOauth: { accessToken: "fixture-claude" } }),
+    );
+    await writeFile(
+      path.join(root, ".codex", "auth.json"),
+      JSON.stringify({ tokens: { access_token: "fixture-codex", account_id: "fixture-account" } }),
+    );
+    try {
+      await promisify(execFile)(
+        process.execPath,
+        [
+          "--import",
+          "tsx",
+          fileURLToPath(new URL("./test-fixtures/usage-proxy-daemon.ts", import.meta.url)),
+          mode,
+        ],
+        {
+          timeout: 45_000,
+          maxBuffer: 1024 * 1024,
+          env: {
+            ...process.env,
+            HOME: root,
+            USERPROFILE: root,
+            CODEX_HOME: path.join(root, ".codex"),
+            CLAUDE_CONFIG_DIR: path.join(root, ".claude"),
+            NODE_OPTIONS: `--require=${JSON.stringify(guard.replaceAll("\\", "/"))}`,
+            https_proxy: `http://127.0.0.1:${address.port}`,
+            no_proxy: "",
+            NO_PROXY: "",
+          },
+        },
+      );
+      expect(tunnels).toContain("api.anthropic.com:443");
+      expect(tunnels).toContain("chatgpt.com:443");
+    } finally {
+      proxy.closeAllConnections();
+      await new Promise<void>((resolve) => proxy.close(() => resolve()));
+      await rm(root, { recursive: true, force: true });
+    }
+  },
+  60_000,
+);
diff --git a/packages/server/src/server/private-files.ts b/packages/server/src/server/private-files.ts
index 0e12457be1..182101149e 100644
--- a/packages/server/src/server/private-files.ts
+++ b/packages/server/src/server/private-files.ts
@@ -1,3 +1,4 @@
+import { chmod, mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { chmodSync, mkdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
@@ -52,3 +53,30 @@ function resolveSymlinkedFile(filePath: string): string {
     throw error;
   }
 }
+
+export async function ensurePrivateFileAsync(filePath: string): Promise<void> {
+  if (process.platform === "win32") return;
+  await chmod(filePath, PRIVATE_FILE_MODE).catch(() => {});
+}
+
+export async function writePrivateFileAtomic(filePath: string, data: string): Promise<void> {
+  const directory = path.dirname(filePath);
+  await mkdir(directory, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
+  if (process.platform !== "win32") await chmod(directory, PRIVATE_DIRECTORY_MODE).catch(() => {});
+  const destination = await realpath(filePath).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") return filePath;
+    throw error;
+  });
+  const temporary = path.join(
+    path.dirname(destination),
+    `.${path.basename(destination)}.${process.pid}.${randomUUID()}`,
+  );
+  try {
+    await writeFile(temporary, data, { mode: PRIVATE_FILE_MODE });
+    await rename(temporary, destination);
+    await ensurePrivateFileAsync(destination);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw 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/relay-transport.ts b/packages/server/src/server/relay-transport.ts
index 08fcd826d5..a0898df247 100644
--- a/packages/server/src/server/relay-transport.ts
+++ b/packages/server/src/server/relay-transport.ts
@@ -2,6 +2,7 @@
 import { WebSocket } from "ws";
 import type pino from "pino";
 import { buildRelayWebSocketUrl } from "@getpaseo/protocol/daemon-endpoints";
+import { webSocketProxyAgent } from "./network/index.js";
 import type { ExternalSocketMetadata } from "./websocket-server.js";
 
 export interface RelayTransportOptions {
@@ -56,7 +57,7 @@ const RELAY_WEBSOCKET_OPTIONS = {
 } as const;
 
 function createDefaultRelayWebSocket(url: string): RelayWebSocketLike {
-  return new WebSocket(url, RELAY_WEBSOCKET_OPTIONS);
+  return new WebSocket(url, { ...RELAY_WEBSOCKET_OPTIONS, agent: webSocketProxyAgent(url) });
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
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..43b7abdf68 100644
--- a/packages/server/src/server/schedule/service.test.ts
+++ b/packages/server/src/server/schedule/service.test.ts
@@ -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({
@@ -2114,6 +2114,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 3b462cc5b1..6121b7e6bd 100644
--- a/packages/server/src/server/schedule/service.ts
+++ b/packages/server/src/server/schedule/service.ts
@@ -226,6 +226,7 @@ type ScheduleAgentManager = Pick<
   AgentRunController,
   | "getAgent"
   | "reloadAgentSession"
+  | "reloadStalePluginSession"
   | "tryRunOutOfBand"
   | "hasInFlightRun"
   | "replaceAgentRun"
diff --git a/packages/server/src/server/script-health-monitor.test.ts b/packages/server/src/server/script-health-monitor.test.ts
index 96af0133ca..c5e4904a9d 100644
--- a/packages/server/src/server/script-health-monitor.test.ts
+++ b/packages/server/src/server/script-health-monitor.test.ts
@@ -68,13 +68,7 @@ function createStubTerminalManager(
         subscribe: () => () => {},
         onExit: () => () => {},
         onCommandFinished: () => () => {},
-        getState: () => ({
-          rows: 1,
-          cols: 1,
-          grid: [[{ char: "$" }]],
-          scrollback: [],
-          cursor: { row: 0, col: 0 },
-        }),
+        hasOutput: () => true,
         kill: () => {},
         onTitleChange: () => () => {},
         getSize: () => ({ rows: 1, cols: 1 }),
diff --git a/packages/server/src/server/script-status-projection.test.ts b/packages/server/src/server/script-status-projection.test.ts
index 3c963f907c..b6ef6e18f5 100644
--- a/packages/server/src/server/script-status-projection.test.ts
+++ b/packages/server/src/server/script-status-projection.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { tmpdir } from "node:os";
@@ -7,6 +7,7 @@ import { ScriptRouteStore } from "./script-proxy.js";
 import {
   buildWorkspaceScriptPayloads,
   createScriptStatusEmitter,
+  readPaseoConfigForProjection,
 } from "./script-status-projection.js";
 import { WorkspaceScriptPayloadSchema } from "@getpaseo/protocol/messages";
 import type { ScriptHealthState } from "./script-health-monitor.js";
@@ -50,7 +51,7 @@ function createWorkspaceRepo(options?: {
   };
 }
 
-function buildPayloads(input: {
+async function buildPayloads(input: {
   workspaceId: string;
   workspaceDirectory: string;
   paseoConfig?: PaseoConfig | null;
@@ -63,7 +64,9 @@ function buildPayloads(input: {
   resolveHealth?: (hostname: string) => ScriptHealthState | null;
 }) {
   const paseoConfig =
-    input.paseoConfig !== undefined ? input.paseoConfig : loadConfig(input.workspaceDirectory);
+    input.paseoConfig !== undefined
+      ? input.paseoConfig
+      : await loadConfig(input.workspaceDirectory);
   const { routeStore, serviceProxy, ...rest } = input;
   return buildWorkspaceScriptPayloads({
     ...rest,
@@ -72,8 +75,8 @@ function buildPayloads(input: {
   });
 }
 
-function loadConfig(repoRoot: string): PaseoConfig | null {
-  const result = readPaseoConfig(repoRoot);
+async function loadConfig(repoRoot: string): Promise<PaseoConfig | null> {
+  const result = await readPaseoConfig(repoRoot);
   return result.ok ? result.config : null;
 }
 
@@ -93,7 +96,7 @@ describe("script-status-projection", () => {
     ).toBeNull();
   });
 
-  it("projects plain scripts and services differently", () => {
+  it("projects plain scripts and services differently", async () => {
     const workspaceId = "workspace-plain-and-service";
     const workspace = createWorkspaceRepo({
       paseoConfig: {
@@ -116,7 +119,7 @@ describe("script-status-projection", () => {
 
     try {
       expect(
-        buildPayloads({
+        await buildPayloads({
           workspaceId,
           workspaceDirectory: workspace.repoDir,
           routeStore,
@@ -154,7 +157,7 @@ describe("script-status-projection", () => {
     }
   });
 
-  it("builds service hostnames from service-provided git metadata", () => {
+  it("builds service hostnames from service-provided git metadata", async () => {
     const workspaceId = "workspace-service-metadata";
     const workspace = createWorkspaceRepo({
       branchName: "local-branch-that-should-not-be-read",
@@ -168,7 +171,7 @@ describe("script-status-projection", () => {
     const runtimeStore = new WorkspaceScriptRuntimeStore();
 
     try {
-      const payloads = buildPayloads({
+      const payloads = await buildPayloads({
         workspaceId,
         workspaceDirectory: workspace.repoDir,
         serviceProxy: routeStore,
@@ -200,7 +203,7 @@ describe("script-status-projection", () => {
     }
   });
 
-  it("projects local and public service URLs while keeping proxyUrl public-first", () => {
+  it("projects local and public service URLs while keeping proxyUrl public-first", async () => {
     const workspaceId = "workspace-public-service";
     const workspace = createWorkspaceRepo({
       paseoConfig: {
@@ -214,7 +217,7 @@ describe("script-status-projection", () => {
 
     try {
       expect(
-        buildPayloads({
+        await buildPayloads({
           workspaceId,
           workspaceDirectory: workspace.repoDir,
           routeStore,
@@ -243,7 +246,7 @@ describe("script-status-projection", () => {
     }
   });
 
-  it("overlays runtime, route, and health state for running services", () => {
+  it("overlays runtime, route, and health state for running services", async () => {
     const workspaceId = "workspace-running-service";
     const workspace = createWorkspaceRepo({
       branchName: "feature/card",
@@ -273,7 +276,7 @@ describe("script-status-projection", () => {
 
     try {
       expect(
-        buildPayloads({
+        await buildPayloads({
           workspaceId,
           workspaceDirectory: workspace.repoDir,
           routeStore,
@@ -301,7 +304,7 @@ describe("script-status-projection", () => {
     }
   });
 
-  it("maps internal pending health to null on the wire", () => {
+  it("maps internal pending health to null on the wire", async () => {
     const workspaceId = "workspace-pending-health";
     const workspace = createWorkspaceRepo({
       paseoConfig: {
@@ -330,7 +333,7 @@ describe("script-status-projection", () => {
 
     try {
       expect(
-        buildPayloads({
+        await buildPayloads({
           workspaceId,
           workspaceDirectory: workspace.repoDir,
           routeStore,
@@ -358,7 +361,7 @@ describe("script-status-projection", () => {
     }
   });
 
-  it("includes orphaned running runtime entries even after config removal", () => {
+  it("includes orphaned running runtime entries even after config removal", async () => {
     const workspaceId = "workspace-orphaned-service";
     const workspace = createWorkspaceRepo();
     const routeStore = new ScriptRouteStore();
@@ -381,7 +384,7 @@ describe("script-status-projection", () => {
 
     try {
       expect(
-        buildPayloads({
+        await buildPayloads({
           workspaceId,
           workspaceDirectory: workspace.repoDir,
           routeStore,
@@ -408,7 +411,7 @@ describe("script-status-projection", () => {
     }
   });
 
-  it("projects orphaned plain scripts as scripts instead of services", () => {
+  it("projects orphaned plain scripts as scripts instead of services", async () => {
     const workspaceId = "workspace-orphaned-script";
     const workspace = createWorkspaceRepo();
     const routeStore = new ScriptRouteStore();
@@ -424,7 +427,7 @@ describe("script-status-projection", () => {
 
     try {
       expect(
-        buildPayloads({
+        await buildPayloads({
           workspaceId,
           workspaceDirectory: workspace.repoDir,
           routeStore,
@@ -449,7 +452,7 @@ describe("script-status-projection", () => {
     }
   });
 
-  it("readPaseoConfig fails with configPath and error when paseo.json is malformed", () => {
+  it("readPaseoConfig fails with configPath and error when paseo.json is malformed", async () => {
     const workspace = createWorkspaceRepo();
     const configPath = path.join(workspace.repoDir, "paseo.json");
     writeFileSync(
@@ -458,7 +461,7 @@ describe("script-status-projection", () => {
     );
 
     try {
-      const result = readPaseoConfig(workspace.repoDir);
+      const result = await readPaseoConfig(workspace.repoDir);
       expect(result.ok).toBe(false);
       if (result.ok) throw new Error("unreachable");
       expect(result.configPath).toBe(configPath);
@@ -468,7 +471,7 @@ describe("script-status-projection", () => {
     }
   });
 
-  it("buildWorkspaceScriptPayloads given paseoConfig=null still surfaces orphaned runtime scripts", () => {
+  it("buildWorkspaceScriptPayloads given paseoConfig=null still surfaces orphaned runtime scripts", async () => {
     const workspaceId = "workspace-null-config";
     const workspace = createWorkspaceRepo();
     const routeStore = new ScriptRouteStore();
@@ -484,7 +487,7 @@ describe("script-status-projection", () => {
 
     try {
       expect(
-        buildPayloads({
+        await buildPayloads({
           workspaceId,
           workspaceDirectory: workspace.repoDir,
           paseoConfig: null,
@@ -538,7 +541,12 @@ describe("script-status-projection", () => {
       exitCode: null,
     });
 
-    const session = { emit: vi.fn() };
+    const messages: unknown[] = [];
+    const session = {
+      emit: (message: unknown) => {
+        messages.push(message);
+      },
+    };
     const emitUpdate = createScriptStatusEmitter({
       sessions: () => [session],
       serviceProxy: routeStore,
@@ -550,7 +558,11 @@ describe("script-status-projection", () => {
     });
 
     try {
-      emitUpdate(workspaceId, [
+      const originalConfig = await readPaseoConfigForProjection(
+        workspace.repoDir,
+        createTestLogger(),
+      );
+      await emitUpdate(workspaceId, [
         {
           scriptName: "api",
           hostname: "api--repo.localhost",
@@ -558,9 +570,25 @@ describe("script-status-projection", () => {
           health: "healthy",
         },
       ]);
-      await Promise.resolve();
 
-      expect(session.emit).toHaveBeenCalledWith({
+      expect(await readPaseoConfigForProjection(workspace.repoDir, createTestLogger())).toBe(
+        originalConfig,
+      );
+      await emitUpdate(workspaceId, [
+        { scriptName: "api", hostname: "api--repo.localhost", port: 3001, health: "unhealthy" },
+      ]);
+      expect(messages.at(-1)).toMatchObject({
+        payload: {
+          scripts: [
+            { scriptName: "api", health: "unhealthy" },
+            { scriptName: "typecheck", health: null },
+          ],
+        },
+      });
+      expect(await readPaseoConfigForProjection(workspace.repoDir, createTestLogger())).toBe(
+        originalConfig,
+      );
+      expect(messages).toContainEqual({
         type: "script_status_update",
         payload: {
           workspaceId,
diff --git a/packages/server/src/server/script-status-projection.ts b/packages/server/src/server/script-status-projection.ts
index 2d02751fc6..a66f5fb073 100644
--- a/packages/server/src/server/script-status-projection.ts
+++ b/packages/server/src/server/script-status-projection.ts
@@ -33,11 +33,11 @@ interface BuildWorkspaceScriptPayloadsOptions {
   resolveHealth?: (hostname: string) => ScriptHealthState | null;
 }
 
-export function readPaseoConfigForProjection(
+export async function readPaseoConfigForProjection(
   workspaceDirectory: string,
   logger: Logger,
-): PaseoConfig | null {
-  const result = readPaseoConfig(workspaceDirectory);
+): Promise<PaseoConfig | null> {
+  const result = await readPaseoConfig(workspaceDirectory);
   if (result.ok) {
     return result.config;
   }
@@ -288,9 +288,9 @@ export function createScriptStatusEmitter({
   serviceProxyPublicBaseUrl?: string | null;
   resolveWorkspaceDirectory: (workspaceId: string) => string | null | Promise<string | null>;
   logger: Logger;
-}): (workspaceId: string, scripts: ScriptHealthEntry[]) => void {
-  return (workspaceId, scripts) => {
-    void (async () => {
+}): (workspaceId: string, scripts: ScriptHealthEntry[]) => Promise<void> {
+  return async (workspaceId, scripts) => {
+    try {
       const workspaceDirectory = await resolveWorkspaceDirectory(workspaceId);
       if (!workspaceDirectory) {
         return;
@@ -304,7 +304,7 @@ export function createScriptStatusEmitter({
       const projected = buildWorkspaceScriptPayloads({
         workspaceId,
         workspaceDirectory,
-        paseoConfig: readPaseoConfigForProjection(workspaceDirectory, logger),
+        paseoConfig: await readPaseoConfigForProjection(workspaceDirectory, logger),
         serviceProxy,
         runtimeStore,
         daemonPort: resolvedDaemonPort,
@@ -320,6 +320,8 @@ export function createScriptStatusEmitter({
       for (const session of sessions()) {
         session.emit(message);
       }
-    })();
+    } catch (error) {
+      logger.warn({ err: error, workspaceId }, "Failed to project workspace script status");
+    }
   };
 }
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 2fc05d0131..36e9a2e961 100644
--- a/packages/server/src/server/session.test.ts
+++ b/packages/server/src/server/session.test.ts
@@ -8,7 +8,15 @@ import {
   createTestCreationService,
 } from "./test-utils/session-stubs.js";
 import { execSync } from "child_process";
-import { existsSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "fs";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "fs";
 import { tmpdir } from "os";
 import { join, resolve as resolvePath } from "path";
 import pino from "pino";
@@ -28,6 +36,11 @@ import {
   type FileTransferFrame,
 } from "@getpaseo/protocol/binary-frames/index";
 import { Session } from "./session.js";
+import {
+  terminalCleanupRecordPath,
+  terminalWorkerDirectory,
+  writeTerminalCleanupRecord,
+} from "../terminal/terminal-worker-record.js";
 import { OWNER_PERMISSIONS, type DaemonPermission } from "./authorization/index.js";
 import { DownloadTokenStore } from "./file-download/token-store.js";
 import { StructuredAgentFallbackError } from "./agent/agent-response-loop.js";
@@ -335,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;
@@ -389,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(),
@@ -396,6 +411,7 @@ function createSessionForTest(options: SessionForTestOptions = {}): Session {
     agentManager: asAgentManager({
       listAgents: vi.fn(() => []),
       listProviderSubagentActivity: vi.fn(() => []),
+      getAgentBackgroundWorkSummary: () => undefined,
       subscribe: vi.fn(() => () => {}),
       ...options.agentManager,
     }),
@@ -425,6 +441,7 @@ function createSessionForTest(options: SessionForTestOptions = {}): Session {
     github: asGitHubService(github),
     workspaceGitService: asWorkspaceGitService(workspaceGitService),
     daemonConfigStore: asDaemonConfigStore({
+      readServicePorts: async () => undefined,
       get: vi.fn(() => ({
         mcp: { injectIntoAgents: false },
         providers: {},
@@ -587,6 +604,136 @@ 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"]> = {
+    before: async (_name, request) => request,
+    emit: () => {},
+    listPlugins: async () => [],
+    getLogs: () => [],
+    installDirectory: async () => {
+      throw new Error("Unexpected install");
+    },
+    inspectDirectory: async () => ({ id: "unused" }),
+    reloadPlugin: async () => {
+      throw new Error("Unexpected reload");
+    },
+    enablePlugin: async () => {
+      throw new Error("Unexpected enable");
+    },
+    disablePlugin: async () => {
+      throw new Error("Unexpected disable");
+    },
+    removePlugin: async () => undefined,
+    subscribe: () => () => {},
+    catalog: () => [
+      { id: "cached", clientBundle: "cached bundle", clientBundleHash: "hash-cached" },
+      { id: "changed", clientBundle: "new bundle", clientBundleHash: "hash-new" },
+      { id: "added", clientBundle: "added bundle", clientBundleHash: "hash-added" },
+    ],
+    invokePluginRpc: async () => null,
+    listUsageReports: async () => [],
+    listLegacyUsage: async () => ({ fetchedAt: "2026-01-01T00:00:00.000Z", providers: [] }),
+  };
+  const session = createSessionForTest({ messages, pluginRuntime });
+
+  await session.handleMessage({
+    type: "plugin.catalog.get.request",
+    requestId: "reconnect",
+    cachedClientBundles: [
+      { id: "cached", clientBundleHash: "hash-cached" },
+      { id: "changed", clientBundleHash: "hash-old" },
+      { id: "removed", clientBundleHash: "hash-removed" },
+    ],
+  });
+  // Clients from before cachedClientBundles always receive every bundle.
+  await session.handleMessage({ type: "plugin.catalog.get.request", requestId: "legacy" });
+
+  expect(messages).toEqual([
+    {
+      type: "plugin.catalog.get.response",
+      payload: {
+        requestId: "reconnect",
+        plugins: [
+          { id: "cached", clientBundleHash: "hash-cached" },
+          { id: "changed", clientBundle: "new bundle", clientBundleHash: "hash-new" },
+          { id: "added", clientBundle: "added bundle", clientBundleHash: "hash-added" },
+        ],
+      },
+    },
+    {
+      type: "plugin.catalog.get.response",
+      payload: {
+        requestId: "legacy",
+        plugins: [
+          { id: "cached", clientBundle: "cached bundle", clientBundleHash: "hash-cached" },
+          { id: "changed", clientBundle: "new bundle", clientBundleHash: "hash-new" },
+          { id: "added", clientBundle: "added bundle", clientBundleHash: "hash-added" },
+        ],
+      },
+    },
+  ]);
+  await session.cleanup();
+});
+
 describe("workspace label subscriptions", () => {
   type LabelSubscription = Awaited<ReturnType<WorkspaceLabelService["subscribe"]>>;
   type LabelChange = Parameters<Parameters<WorkspaceLabelService["subscribe"]>[0]["onChange"]>[0];
@@ -1998,11 +2145,84 @@ describe("daemon status + pairing RPC", () => {
             { provider: "claude", available: true, error: null },
             { provider: "codex", available: false, error: "boom" },
           ],
+          terminalCleanupUnconfirmed: [],
         },
       },
     ]);
   });
 
+  test("daemon.get_status.request reports what a terminal cleanup could not confirm gone", async () => {
+    const messages: unknown[] = [];
+    const paseoHome = makeHome();
+    const unresolved = {
+      pid: 4242,
+      role: "terminal program" as const,
+      reason: "still alive" as const,
+      detail: "survived SIGKILL",
+    };
+    await writeTerminalCleanupRecord(paseoHome, {
+      recordId: "closing-record",
+      pid: 4241,
+      bootId: null,
+      createdAt: new Date().toISOString(),
+      identity: { startedAt: "Thu Jan  1 00:00:00 1970", commandLine: "worker" },
+      protocolVersion: 1,
+      paseoVersion: "0.0.0-test",
+      socketPath: join(paseoHome, "closing.sock"),
+      secret: "closing-secret",
+      terminals: [{ id: "t1", pid: 4242, startedAt: "Thu Jan  1 00:00:00 1970" }],
+      closing: { unresolved: [unresolved] },
+    });
+    const session = createSessionForTest({
+      messages,
+      paseoHome,
+      serverId: "srv-test",
+      daemonVersion: "9.9.9",
+      daemonRuntimeConfig: { listen: "127.0.0.1:6767", getRelayConfig: () => null },
+      agentManager: { listProviderAvailability: vi.fn().mockResolvedValue([]) },
+    });
+
+    await session.handleMessage({ type: "daemon.get_status.request", requestId: "status-2" });
+
+    expect(messages).toEqual([
+      expect.objectContaining({
+        type: "daemon.get_status.response",
+        payload: expect.objectContaining({ terminalCleanupUnconfirmed: [unresolved] }),
+      }),
+    ]);
+  });
+
+  test("daemon.get_status.request fails when a terminal cleanup record cannot be read", async () => {
+    const messages: unknown[] = [];
+    const paseoHome = makeHome();
+    mkdirSync(terminalWorkerDirectory(paseoHome), { recursive: true });
+    const cleanupPath = terminalCleanupRecordPath(paseoHome, "closing-record");
+    writeFileSync(cleanupPath, "{ not json");
+    const session = createSessionForTest({
+      messages,
+      paseoHome,
+      serverId: "srv-test",
+      daemonVersion: "9.9.9",
+      daemonRuntimeConfig: { listen: "127.0.0.1:6767", getRelayConfig: () => null },
+      agentManager: { listProviderAvailability: vi.fn().mockResolvedValue([]) },
+    });
+
+    await session.handleMessage({ type: "daemon.get_status.request", requestId: "status-3" });
+
+    expect(messages).toContainEqual(
+      expect.objectContaining({
+        type: "rpc_error",
+        payload: expect.objectContaining({
+          requestId: "status-3",
+          error: expect.stringContaining(cleanupPath),
+        }),
+      }),
+    );
+    expect(messages).not.toContainEqual(
+      expect.objectContaining({ type: "daemon.get_status.response" }),
+    );
+  });
+
   test("daemon.get_status.request falls back to a null/empty status when provider listing fails", async () => {
     const messages: unknown[] = [];
     const session = createSessionForTest({
@@ -2034,6 +2254,7 @@ describe("daemon status + pairing RPC", () => {
           listen: null,
           relay: null,
           providers: [],
+          terminalCleanupUnconfirmed: [],
         },
       },
     ]);
@@ -4019,7 +4240,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),
@@ -4099,7 +4320,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(),
@@ -5885,3 +6106,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 f573b1dd95..83f030d971 100644
--- a/packages/server/src/server/session.ts
+++ b/packages/server/src/server/session.ts
@@ -1,8 +1,14 @@
 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 +22,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";
@@ -50,6 +57,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";
@@ -81,7 +93,6 @@ import {
   type WorkspaceScriptsService,
 } from "./session/workspace-scripts/workspace-scripts-service.js";
 import type { DaemonConfigStore } from "./daemon-config-store.js";
-import { loadPersistedConfig } from "./persisted-config.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";
@@ -115,7 +126,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,
@@ -145,6 +162,7 @@ import {
   listImportableProviderSessions,
   normalizeImportAgentRequest,
 } from "./agent/import-sessions.js";
+import { listProjectSuggestions, ProjectSuggestionsRequestError } from "./project-suggestions.js";
 import {
   checkoutLiteFromGitSnapshot,
   checkoutFromPersistedWorkspacePlacement,
@@ -261,6 +279,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";
 
@@ -269,6 +291,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 {
@@ -383,6 +411,7 @@ type CreateAgentRequestMessage = Extract<SessionInboundMessage, { type: "create_
 interface ResolvedSessionCreateAgentIntent {
   config: AgentSessionConfig;
   intent: CreateAgentIntent;
+  background: boolean;
   createdDirectoryWorkspace: boolean;
 }
 
@@ -471,6 +500,7 @@ export interface SessionOptions {
   creationService: Pick<CreationService, "create" | "subscribe">;
   projectRegistry: ProjectRegistry;
   workspaceRegistry: WorkspaceRegistry;
+  workspaceBaseBranch?: WorkspaceBaseBranchService;
   directorySync?: DirectorySyncService;
   workspaceLabelService?: WorkspaceLabelService;
   filesystem?: SessionFileSystem;
@@ -486,6 +516,7 @@ export interface SessionOptions {
   workspaceAutoName: WorkspaceAutoName;
   daemonConfigStore: DaemonConfigStore;
   pluginRuntime?: {
+    wait: import("./plugins/lifecycle/index.js").PluginLifecycle["wait"];
     before: import("./plugins/lifecycle/index.js").PluginLifecycle["before"];
     emit: import("./plugins/lifecycle/index.js").PluginLifecycle["emit"];
     listPlugins(): Promise<import("@getpaseo/protocol/messages").PluginListItem[]>;
@@ -519,8 +550,13 @@ export interface SessionOptions {
     removePlugin(pluginId: string): Promise<void>;
     subscribe(listener: (pluginId: string) => void): () => void;
     subscribeSettings?(listener: (pluginId: string, settingsId: string) => void): () => void;
-    catalog(): Array<{ id: string; clientBundle: string }>;
+    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[];
@@ -541,6 +577,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,
@@ -577,12 +615,14 @@ export type SessionLifecycleIntent =
       clientId: string;
       requestId: string;
       reason: string;
+      keepTerminals: boolean;
     }
   | {
       type: "restart";
       clientId: string;
       requestId: string;
       reason: string;
+      keepTerminals: boolean;
     };
 
 function parseClientCapabilities(
@@ -759,6 +799,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"];
@@ -809,6 +850,7 @@ 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;
@@ -874,6 +916,7 @@ export class Session {
       scriptRuntimeStore,
       workspaceSetupObservation,
       workspaceSetupRuntime,
+      workspaceArchiveOperations,
       onBranchChanged,
       getDaemonTcpPort,
       getDaemonTcpHost,
@@ -924,7 +967,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,
@@ -942,12 +985,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,
@@ -1040,6 +1093,7 @@ export class Session {
       logger: this.sessionLogger,
     });
     this.usageSession = new UsageSession({
+      isEnabled: () => daemonConfigStore.get().usage?.enabled !== false,
       emit: (msg) => this.emit(msg),
       runtime: pluginRuntime,
       logger: this.sessionLogger,
@@ -1105,9 +1159,11 @@ export class Session {
         "Terminal output": this.terminalController.getMetrics().streamSubscriptionCount,
       }),
       listProviderAvailability: () => this.agentManager.listProviderAvailability(),
+      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(),
@@ -1126,11 +1182,11 @@ export class Session {
       terminalManager,
       emit: (msg) => this.emit(msg),
       hasBinaryChannel: () => this.onBinaryMessage !== null,
+      supportsChunkedReplay: (source) =>
+        this.supportsForSource(CLIENT_CAPS.terminalChunkedReplay, source),
       isPathWithinRoot: (rootPath, candidatePath) => this.isPathWithinRoot(rootPath, candidatePath),
       sessionLogger: this.sessionLogger,
       listTerminalWorkspaceRefs: () => this.listActiveWorkspaceRefs(),
-      clientSupportsWrapReflow: (source) =>
-        this.supportsForSource(CLIENT_CAPS.terminalReflowableSnapshot, source),
       getClientBufferedAmount: (source) => this.getTransportBufferedAmount(source),
     });
     this.agentDirectory = new AgentDirectory({
@@ -1147,8 +1203,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),
@@ -1208,6 +1264,7 @@ export class Session {
       },
     );
     this.workspaceSetupRuntime = resolveWorkspaceSetupRuntime(workspaceSetupRuntime);
+    this.workspaceArchiveOperations = resolveWorkspaceArchiveOperations(workspaceArchiveOperations);
     this.getDaemonTcpPort = getDaemonTcpPort ?? null;
     this.getDaemonTcpHost = getDaemonTcpHost ?? null;
     this.serviceProxyPublicBaseUrl = serviceProxyPublicBaseUrl ?? null;
@@ -1232,14 +1289,16 @@ export class Session {
       spawnWorkspaceScript,
       assertAutomationAllowed: (workspaceId) =>
         assertWorkspaceAutomationAllowedForWorkspace(this.workspaceRegistry, workspaceId),
-      globalServicePorts: loadPersistedConfig(this.paseoHome).worktrees?.servicePorts,
+      getGlobalServicePorts: () => this.daemonConfigStore.readServicePorts(),
     });
     this.workspaceDirectory = new WorkspaceDirectory({
       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),
@@ -1713,7 +1772,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?.();
@@ -1853,11 +1913,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 (
@@ -1989,6 +2057,24 @@ export class Session {
           return;
         }
 
+        if (event.type === "agent_removed") {
+          if (event.internal) return;
+          void this.agentUpdates
+            .removeAgent(event.agentId)
+            .then(() => {
+              if (event.workspaceId)
+                return this.emitWorkspaceUpdateForWorkspaceId(event.workspaceId);
+              return undefined;
+            })
+            .catch((error) => {
+              this.sessionLogger.error(
+                { err: error, agentId: event.agentId },
+                "Failed to emit agent removal",
+              );
+            });
+          return;
+        }
+
         if (event.type === "agent_state") {
           this.sessionLogger.trace(
             {
@@ -2005,14 +2091,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;
         }
 
@@ -2087,6 +2171,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;
@@ -2119,6 +2223,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;
@@ -2199,13 +2304,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) {
@@ -2270,6 +2377,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[] {
@@ -2432,6 +2550,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;
@@ -2585,30 +2704,112 @@ export class Session {
       });
     }
     if (msg.type === "plugin.catalog.get.request") {
+      const cached = new Map(
+        msg.cachedClientBundles?.map((entry) => [entry.id, entry.clientBundleHash]),
+      );
+      const plugins = (this.pluginRuntime?.catalog() ?? []).map(({ clientBundle, ...plugin }) =>
+        plugin.clientBundleHash !== undefined && cached.get(plugin.id) === plugin.clientBundleHash
+          ? plugin
+          : Object.assign(plugin, { clientBundle }),
+      );
       this.emit({
         type: "plugin.catalog.get.response",
-        payload: {
-          requestId: msg.requestId,
-          plugins: this.pluginRuntime?.catalog() ?? [],
-        },
+        payload: { requestId: msg.requestId, plugins },
       });
       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");
@@ -2723,9 +2924,13 @@ export class Session {
       case "dictation_stream_cancel":
         return this.voiceSessions.handleMessage(msg);
       case "restart_server_request":
-        return this.handleRestartServerRequest(msg.requestId, msg.reason);
+        return this.handleRestartServerRequest(msg.requestId, msg.reason, {
+          keepTerminals: msg.killTerminals !== true,
+        });
       case "shutdown_server_request":
-        return this.handleShutdownServerRequest(msg.requestId);
+        return this.handleShutdownServerRequest(msg.requestId, {
+          keepTerminals: msg.keepTerminals === true,
+        });
       case "client_heartbeat":
         this.handleClientHeartbeat(msg);
         return undefined;
@@ -2783,6 +2988,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": {
@@ -2927,8 +3136,7 @@ export class Session {
       case "daemon.get_pairing_offer.request":
         return this.daemonSession.handleGetPairingOfferRequest(msg);
       case "daemon.config.reload.request":
-        this.daemonSession.handleConfigReloadRequest(msg);
-        return undefined;
+        return this.daemonSession.handleConfigReloadRequest(msg);
       case "hub.management.daemon.connect.request":
       case "hub.management.daemon.get_status.request":
       case "hub.management.daemon.disconnect.request":
@@ -2939,14 +3147,15 @@ export class Session {
       case "daemon.update.request":
         return this.daemonSession.handleUpdateRequest(msg);
       case "set_daemon_config_request":
-        this.emit({
-          type: "set_daemon_config_response",
-          payload: {
-            requestId: msg.requestId,
-            config: this.daemonConfigStore.patch(msg.config),
-          },
+        return this.daemonConfigStore.patch(msg.config).then((config) => {
+          return this.emit({
+            type: "set_daemon_config_response",
+            payload: {
+              requestId: msg.requestId,
+              config,
+            },
+          });
         });
-        return undefined;
       case "read_project_config_request":
         return this.projectConfigSession.handleReadProjectConfigRequest(msg);
       case "write_project_config_request":
@@ -2964,7 +3173,7 @@ export class Session {
       case "checkout.commits.list.request":
         return this.checkoutSession.handleCommitsListRequest(msg);
       case "checkout.commits.file_diff.request":
-        return this.checkoutSession.handleCommitFileDiffRequest(msg);
+        return this.checkoutSession.handleCommitFileDiffRequest(msg, this.delivery.requestSignal);
       case "validate_branch_request":
         return this.checkoutSession.handleValidateBranchRequest(msg);
       case "branch_suggestions_request":
@@ -3031,6 +3240,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":
@@ -3060,6 +3271,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;
     }
@@ -3133,6 +3346,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":
@@ -3241,6 +3456,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;
     }
@@ -3251,7 +3482,11 @@ export class Session {
     this.terminalController.handleBinaryFrame(binaryFrame.frame, source);
   }
 
-  private async handleRestartServerRequest(requestId: string, reason?: string): Promise<void> {
+  private async handleRestartServerRequest(
+    requestId: string,
+    reason: string | undefined,
+    options: { keepTerminals: boolean },
+  ): Promise<void> {
     const lifecycleReason = normalizeClientRestartRpcReason(reason);
     const payload: { status: string } & Record<string, unknown> = {
       status: "restart_requested",
@@ -3262,7 +3497,10 @@ export class Session {
     }
     payload.requestId = requestId;
 
-    this.sessionLogger.warn({ reason: lifecycleReason }, "Restart requested via websocket");
+    this.sessionLogger.warn(
+      { reason: lifecycleReason, keepTerminals: options.keepTerminals },
+      "Restart requested via websocket",
+    );
     this.emit({
       type: "status",
       payload,
@@ -3273,12 +3511,19 @@ export class Session {
       clientId: this.clientId,
       requestId,
       reason: lifecycleReason,
+      keepTerminals: options.keepTerminals,
     });
   }
 
-  private async handleShutdownServerRequest(requestId: string): Promise<void> {
+  private async handleShutdownServerRequest(
+    requestId: string,
+    options: { keepTerminals: boolean },
+  ): Promise<void> {
     const reason = CLIENT_SHUTDOWN_RPC_REASON;
-    this.sessionLogger.warn({ reason }, "Shutdown requested via websocket");
+    this.sessionLogger.warn(
+      { reason, keepTerminals: options.keepTerminals },
+      "Shutdown requested via websocket",
+    );
     this.emit({
       type: "status",
       payload: {
@@ -3293,6 +3538,7 @@ export class Session {
       clientId: this.clientId,
       requestId,
       reason,
+      keepTerminals: options.keepTerminals,
     });
   }
 
@@ -3310,10 +3556,8 @@ export class Session {
   private async handleDeleteAgentRequest(agentId: string, requestId: string): Promise<void> {
     this.sessionLogger.info({ agentId }, `Deleting agent ${agentId} from registry`);
 
-    const knownWorkspaceId =
-      this.agentManager.getAgent(agentId)?.workspaceId ??
-      (await this.agentStorage.get(agentId))?.workspaceId ??
-      null;
+    const knownAgent =
+      this.agentManager.getAgent(agentId) ?? (await this.agentStorage.get(agentId));
 
     // File-backed storage still needs an early delete fence before closeAgent().
     beginAgentDeleteIfSupported(this.agentStorage, agentId);
@@ -3334,6 +3578,8 @@ export class Session {
     try {
       await this.agentStorage.remove(agentId);
       await this.agentManager.deleteAgentState(agentId);
+      // Directory removal is daemon-wide; agent_deleted below stays a source-scoped RPC reply.
+      if (knownAgent) this.agentManager.notifyAgentRemoved(knownAgent);
     } catch (error) {
       this.sessionLogger.error({ err: error, agentId }, `Failed to fully delete agent ${agentId}`);
     }
@@ -3345,12 +3591,6 @@ export class Session {
         requestId,
       },
     });
-
-    await this.agentUpdates.removeAgent(agentId);
-
-    if (knownWorkspaceId) {
-      await this.emitWorkspaceUpdateForWorkspaceId(knownWorkspaceId);
-    }
   }
 
   private async handleArchiveAgentRequest(agentId: string, requestId: string): Promise<void> {
@@ -3638,7 +3878,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);
@@ -3690,7 +3930,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) {
@@ -3736,7 +3976,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
@@ -3898,6 +4138,41 @@ export class Session {
     }
   }
 
+  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,
@@ -4367,14 +4642,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(
@@ -4425,8 +4692,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({
@@ -4457,6 +4723,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 }
@@ -4472,7 +4739,10 @@ export class Session {
         },
       );
       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(
           {
@@ -4508,20 +4778,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) {
@@ -4538,7 +4801,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,
@@ -4549,6 +4812,7 @@ export class Session {
     return {
       config,
       intent,
+      background: inheritAgentBackground(request.background, callerAgent),
       createdDirectoryWorkspace: !createdWorktree && !request.workspaceId && !callerAgent,
     };
   }
@@ -5315,7 +5579,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) {
@@ -5427,7 +5692,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(
@@ -5500,7 +5765,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;
@@ -5516,9 +5796,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 =
@@ -5605,6 +5883,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);
@@ -5664,13 +5943,14 @@ export class Session {
       pinnedAt: workspace.pinnedAt,
       ...(workspace.labels && workspace.labels.length > 0 ? { labels: workspace.labels } : {}),
       background: workspace.background,
+      parentWorkspaceId: workspace.parentWorkspaceId,
       archivingAt: null,
       status: "done",
       statusEnteredAt: null,
       activityAt: null,
       createdAt: workspace.createdAt,
       diffStat,
-      scripts: this.buildWorkspaceScriptPayloadSnapshot(workspace, resolvedProjectRecord),
+      scripts: await this.buildWorkspaceScriptPayloadSnapshot(workspace, resolvedProjectRecord),
       ...(resolvedProjectRecord
         ? {
             project: await this.buildProjectPlacementForWorkspace(workspace, resolvedProjectRecord),
@@ -5752,6 +6032,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,
@@ -5813,7 +6094,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);
   }
 
@@ -5941,6 +6223,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}`);
@@ -5983,6 +6269,7 @@ export class Session {
     },
   ): Promise<CreatePaseoWorktreeResult> {
     const result = await createPaseoWorktree(input, {
+      lifecycle: this.pluginRuntime,
       github: this.github,
       ...(options?.resolveDefaultBranch
         ? { resolveDefaultBranch: options.resolveDefaultBranch }
@@ -6003,7 +6290,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) => ({
@@ -6029,7 +6316,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(
@@ -6234,7 +6521,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;
     }
@@ -6251,16 +6538,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);
@@ -6270,8 +6558,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);
@@ -6315,7 +6603,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: {
@@ -6509,6 +6800,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");
@@ -6649,6 +6971,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(
@@ -6656,19 +6979,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) };
@@ -6769,11 +7092,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(
@@ -6791,7 +7137,7 @@ export class Session {
     // and must not rerun hooks or compare their potentially changing output.
     if (this.pluginRuntime) {
       const { type, requestId, ...input } = request;
-      const transformed = await this.pluginRuntime.before("workspace.create", input);
+      const transformed = await this.pluginRuntime.before("workspace.create.before", input);
       creationRequest = { ...transformed, type, requestId };
     }
     return creationRequest.source.kind === "directory"
@@ -6822,8 +7168,7 @@ export class Session {
       {
         expectsInitialAgent: Boolean(request.firstAgentContext),
         workspaceId,
-        background: request.background,
-        callerWorkspaceId: this.getCallerWorkspaceId(request.callerAgentId),
+        ...(await this.workspaceBackgroundIntent(request.background, request.callerAgentId)),
       },
     );
     await this.syncWorkspaceGitObserverForWorkspace(workspace);
@@ -6886,8 +7231,7 @@ export class Session {
         githubPrNumber: source.githubPrNumber,
         firstAgentContext: request.firstAgentContext,
         title: request.title,
-        background: request.background,
-        callerWorkspaceId: this.getCallerWorkspaceId(request.callerAgentId),
+        ...(await this.workspaceBackgroundIntent(request.background, request.callerAgentId)),
       },
       source.baseBranch
         ? { resolveDefaultBranch: async () => source.baseBranch as string }
@@ -6931,7 +7275,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);
@@ -7263,7 +7607,7 @@ export class Session {
   private buildWorkspaceScriptPayloadSnapshot(
     workspace: PersistedWorkspaceRecord,
     project: PersistedProjectRecord | null,
-  ): WorkspaceDescriptorPayload["scripts"] {
+  ): Promise<WorkspaceDescriptorPayload["scripts"]> {
     return this.workspaceScripts.buildSnapshot(workspace, project);
   }
 
@@ -7489,41 +7833,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({
@@ -7553,6 +7918,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> {
@@ -7560,7 +7988,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) => ({
@@ -7700,14 +8131,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(
@@ -7716,7 +8155,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);
@@ -7787,8 +8226,6 @@ export class Session {
   ): Promise<void> {
     const direction: AgentTimelineFetchDirection = msg.direction ?? (msg.cursor ? "after" : "tail");
     const projection = "projected" as const;
-    const requestedLimit = msg.limit;
-    const pageLimit = requestedLimit ?? (direction === "after" ? 0 : 200);
     const cursor: AgentTimelineCursor | undefined = msg.cursor
       ? {
           epoch: msg.cursor.epoch,
@@ -7801,13 +8238,15 @@ export class Session {
         agentManager: this.agentManager,
         agentStorage: this.agentStorage,
         logger: this.sessionLogger,
+        purpose: "history",
       });
       const agentPayload = await this.buildAgentPayload(snapshot);
 
       const fetchedControlTimeline = this.agentManager.fetchTimeline(msg.agentId, {
         direction,
         cursor,
-        limit: pageLimit,
+        limit: msg.limit,
+        wholeTurns: msg.wholeTurns,
       });
       const selectedTimeline = {
         timeline: fetchedControlTimeline,
@@ -8055,6 +8494,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,
@@ -8275,7 +8783,7 @@ export class Session {
             },
             activeTurnBehavior: msg.activeTurnBehavior ?? "steer",
             sessionMode: msg.sessionMode,
-            clearPendingPermissions: true,
+            clearPendingPermissions: false,
           });
           deliveryStatus = "queued";
           queued();
@@ -8647,9 +9155,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;
     }
@@ -8776,6 +9284,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":
@@ -8814,6 +9323,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 e4a0ca7668..928131ab3a 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>;
   };
@@ -149,7 +151,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 () => {},
@@ -1744,7 +1875,9 @@ test("workspace clear attention clears stored-only agents and responds", async (
   });
   const session = createSessionForWorkspaceTests({ onMessage: (message) => emitted.push(message) });
 
-  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];
@@ -1859,7 +1992,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 +2030,146 @@ 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"]),
+    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,7 +2196,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}`,
+    error: `Workspace has no read agent to mark unread: ${workspace.workspaceId}`,
   });
 });
 
@@ -1972,7 +2246,7 @@ test("workspace clear attention can clear multiple workspaces in one request", a
   );
   const session = createSessionForWorkspaceTests({ onMessage: (message) => emitted.push(message) });
 
-  session.workspaceRegistry.list = async () => workspaces;
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => workspaces;
   session.workspaceRegistry.get = async (id: string) =>
     workspaces.find((workspace) => workspace.workspaceId === id) ?? null;
   session.projectRegistry.list = async () => projects;
@@ -2099,7 +2373,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 +2415,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 +2563,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 +2607,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 +2719,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 +2761,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 +2831,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 +2999,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 +3097,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 +3179,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 +3242,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 +3312,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 +3400,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 +3622,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 +3689,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 +3734,7 @@ test("fetch_recent_provider_sessions_request reports filteredAlreadyImportedCoun
       },
     },
   ];
-  session.agentStorage.list = async () => [];
+  session.agentStorage.listAll = async () => [];
   session.agentManager.listImportableSessions = async () => ({
     sessions: [
       {
@@ -3532,7 +3828,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 +3871,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 +3918,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 +3984,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 +3999,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 +4149,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 +4219,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 +4316,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 +4433,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 +4514,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 +4615,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 +4671,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 +4697,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 +4786,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 +4817,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 +4862,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 +4939,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 +5051,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 +5121,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 +5197,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 +5314,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 +5405,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 +5495,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 +5551,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 +5612,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 +5705,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 () => {};
@@ -5486,7 +5804,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 () => {};
@@ -5577,7 +5896,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 () => {};
@@ -5676,7 +5996,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 () => {};
@@ -5806,7 +6127,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 () => {};
 
@@ -5864,7 +6186,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",
@@ -5940,7 +6263,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({
@@ -5991,6 +6316,9 @@ test("archive_workspace_request archives a worktree-kind workspace and removes t
     projectId,
     cwd: worktree.worktreePath,
     kind: "worktree",
+    worktreeRoot: worktree.worktreePath,
+    mainRepoRoot: repoDir,
+    isPaseoOwnedWorktree: true,
     displayName: "worktree-kind-archive",
     createdAt: "2026-03-01T12:00:00.000Z",
     updatedAt: "2026-03-01T12:00:00.000Z",
@@ -6037,7 +6365,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;
   };
@@ -6123,7 +6453,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>,
   ) => {
@@ -6229,7 +6560,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>,
   ) => {
@@ -6325,7 +6657,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>,
   ) => {
@@ -6385,7 +6718,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,
@@ -6447,7 +6782,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(
@@ -6481,7 +6818,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 };
   };
 
@@ -6708,7 +7047,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 () => [
@@ -6765,7 +7107,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",
@@ -6823,7 +7167,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 () =>
     (
@@ -6871,7 +7217,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);
@@ -6927,7 +7275,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];
   };
@@ -6978,7 +7326,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 () => {
@@ -7039,7 +7388,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",
@@ -7138,7 +7489,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",
@@ -7206,7 +7559,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",
@@ -7319,7 +7674,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) {
@@ -7380,7 +7738,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 () => {},
@@ -7425,14 +7786,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;
     };
   });
 
@@ -7502,7 +7865,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 () => {},
@@ -7618,7 +7984,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 () => {},
@@ -7692,7 +8061,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 () => {},
@@ -7957,7 +8329,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",
@@ -8047,7 +8419,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;
 
@@ -8103,7 +8477,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",
@@ -8145,7 +8519,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",
@@ -8216,7 +8590,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);
@@ -8286,7 +8661,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;
@@ -8343,7 +8719,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);
@@ -8417,7 +8794,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 () => {},
@@ -8474,7 +8854,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;
@@ -9021,7 +9401,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);
@@ -9228,8 +9611,8 @@ test("workspace auto-name uses the backing root for a nested worktree", async ()
   execFileSync("git", ["add", "README.md"], { cwd: repoDir, stdio: "pipe" });
   execFileSync("git", ["commit", "-m", "initial"], { cwd: repoDir, stdio: "pipe" });
   execFileSync("git", ["branch", "-M", "placeholder-branch"], { cwd: repoDir, stdio: "pipe" });
-  writePaseoWorktreeMetadata(repoDir, { baseRefName: "main" });
-  writePaseoWorktreeFirstAgentBranchAutoNameMetadata(repoDir, {
+  await writePaseoWorktreeMetadata(repoDir, { baseRefName: "main" });
+  await writePaseoWorktreeFirstAgentBranchAutoNameMetadata(repoDir, {
     placeholderBranchName: "placeholder-branch",
   });
   const workspaceCwd = path.join(repoDir, "packages", "app");
@@ -9288,6 +9671,7 @@ test("workspace auto-name uses the backing root for a nested worktree", async ()
       firstAgentContext: { prompt: "Fix checkout title" },
     });
     await vi.runAllTimersAsync();
+    await vi.waitFor(() => expect(emittedCwds).toEqual([workspaceCwd]));
 
     expect(generateCalls).toBe(1);
     expect(stored.get(workspace.workspaceId)).toMatchObject({
@@ -9299,7 +9683,7 @@ test("workspace auto-name uses the backing root for a nested worktree", async ()
         .toString()
         .trim(),
     ).toBe("placeholder-branch");
-    expect(readPaseoWorktreeMetadata(repoDir)).toMatchObject({
+    expect(await readPaseoWorktreeMetadata(repoDir)).toMatchObject({
       version: 2,
       firstAgentBranchAutoName: {
         status: "attempted",
@@ -9344,7 +9728,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;
@@ -9384,7 +9769,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);
@@ -9425,7 +9813,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);
@@ -9477,7 +9868,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);
@@ -9559,7 +9953,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",
@@ -9754,7 +10149,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 () => {},
@@ -9925,3 +10323,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-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.ts b/packages/server/src/server/session/checkout/checkout-session.ts
index 419d418050..4deb28a56b 100644
--- a/packages/server/src/server/session/checkout/checkout-session.ts
+++ b/packages/server/src/server/session/checkout/checkout-session.ts
@@ -290,7 +290,10 @@ export class CheckoutSession {
     }
   }
 
-  async handleCommitFileDiffRequest(msg: CheckoutCommitFileDiffRequest): Promise<void> {
+  async handleCommitFileDiffRequest(
+    msg: CheckoutCommitFileDiffRequest,
+    signal: AbortSignal,
+  ): Promise<void> {
     const { cwd, sha, path, requestId } = msg;
 
     try {
@@ -298,7 +301,7 @@ 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 });
+      const file = await getCommitFileDiff({ cwd: expandTilde(cwd), sha, path, signal });
       this.host.emit({
         type: "checkout.commits.file_diff.response",
         payload: { cwd, sha, path, file, error: null, requestId },
@@ -376,13 +379,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",
diff --git a/packages/server/src/server/session/daemon/daemon-self-update-session-controller.test.ts b/packages/server/src/server/session/daemon/daemon-self-update-session-controller.test.ts
index 81c41f3421..e9bcf94b65 100644
--- a/packages/server/src/server/session/daemon/daemon-self-update-session-controller.test.ts
+++ b/packages/server/src/server/session/daemon/daemon-self-update-session-controller.test.ts
@@ -118,6 +118,7 @@ describe("DaemonSelfUpdateSessionController", () => {
         clientId: "client-1",
         requestId: "update-1",
         reason: "daemon_update",
+        keepTerminals: true,
       },
     ]);
   });
diff --git a/packages/server/src/server/session/daemon/daemon-self-update-session-controller.ts b/packages/server/src/server/session/daemon/daemon-self-update-session-controller.ts
index 461a97277b..bb75f008bd 100644
--- a/packages/server/src/server/session/daemon/daemon-self-update-session-controller.ts
+++ b/packages/server/src/server/session/daemon/daemon-self-update-session-controller.ts
@@ -19,6 +19,7 @@ interface DaemonSelfUpdateRestartIntent {
   clientId: string;
   requestId: string;
   reason: string;
+  keepTerminals: boolean;
 }
 
 export interface DaemonSelfUpdateSessionControllerOptions {
@@ -88,6 +89,8 @@ export class DaemonSelfUpdateSessionController {
         clientId: this.clientId,
         requestId: msg.requestId,
         reason: "daemon_update",
+        // A self-update restart keeps terminals: the worker outlives the daemon.
+        keepTerminals: true,
       });
     } catch (error) {
       if (error instanceof DaemonSelfUpdateInProgressError) {
diff --git a/packages/server/src/server/session/daemon/daemon-session.test.ts b/packages/server/src/server/session/daemon/daemon-session.test.ts
index cac6a91ea6..cb6da8777b 100644
--- a/packages/server/src/server/session/daemon/daemon-session.test.ts
+++ b/packages/server/src/server/session/daemon/daemon-session.test.ts
@@ -43,7 +43,7 @@ function makeSubsystem(overrides: {
   listProviderAvailability?: () => Promise<ProviderAvailability[]>;
   getWebSocketRuntimeMetrics?: () => DaemonWebSocketRuntimeDiagnosticSnapshot | null;
   hubRelationships?: HubRelationshipManagement;
-  reloadConfig?: () => DaemonConfigReloadResult;
+  reloadConfig?: () => Promise<DaemonConfigReloadResult>;
 }) {
   const emitted: SessionOutboundMessage[] = [];
   const restartIntents: Parameters<DaemonSessionHost["emitLifecycleIntent"]>[0][] = [];
@@ -67,7 +67,7 @@ function makeSubsystem(overrides: {
     hubRelationships: overrides.hubRelationships,
     reloadConfig:
       overrides.reloadConfig ??
-      (() => ({
+      (async () => ({
         appliedPaths: [],
         restartRequiredPaths: [],
         overrideControlledPaths: [],
@@ -78,16 +78,16 @@ function makeSubsystem(overrides: {
 }
 
 describe("DaemonSession", () => {
-  test("config reload returns the daemon-owned classification", () => {
+  test("config reload returns the daemon-owned classification", async () => {
     const { subsystem, emitted } = makeSubsystem({
-      reloadConfig: () => ({
+      reloadConfig: async () => ({
         appliedPaths: ["daemon.browserTools.enabled"],
         restartRequiredPaths: ["daemon.listen"],
         overrideControlledPaths: ["app.baseUrl"],
       }),
     });
 
-    subsystem.handleConfigReloadRequest({
+    await subsystem.handleConfigReloadRequest({
       type: "daemon.config.reload.request",
       requestId: "reload-1",
     });
@@ -105,14 +105,14 @@ describe("DaemonSession", () => {
     ]);
   });
 
-  test("config reload failures return a correlated RPC error", () => {
+  test("config reload failures return a correlated RPC error", async () => {
     const { subsystem, emitted } = makeSubsystem({
-      reloadConfig: () => {
+      reloadConfig: async () => {
         throw new Error("Invalid config");
       },
     });
 
-    subsystem.handleConfigReloadRequest({
+    await subsystem.handleConfigReloadRequest({
       type: "daemon.config.reload.request",
       requestId: "reload-2",
     });
@@ -212,6 +212,7 @@ describe("DaemonSession", () => {
             { provider: "claude", available: true, error: null },
             { provider: "codex", available: false, error: "boom" },
           ],
+          terminalCleanupUnconfirmed: [],
         },
       },
     ]);
@@ -242,6 +243,7 @@ describe("DaemonSession", () => {
           listen: null,
           relay: null,
           providers: [],
+          terminalCleanupUnconfirmed: [],
         },
       },
     ]);
diff --git a/packages/server/src/server/session/daemon/daemon-session.ts b/packages/server/src/server/session/daemon/daemon-session.ts
index fbe1a06415..585fa45573 100644
--- a/packages/server/src/server/session/daemon/daemon-session.ts
+++ b/packages/server/src/server/session/daemon/daemon-session.ts
@@ -2,6 +2,7 @@ import type pino from "pino";
 import type { ProviderAvailability } from "../../agent/agent-manager.js";
 import type { SessionInboundMessage, SessionOutboundMessage } from "../../messages.js";
 import { getPidLockInfo } from "../../pid-lock.js";
+import { readUnconfirmedTerminalCleanup } from "../../../terminal/terminal-worker-reaper.js";
 import { generateLocalPairingOffer } from "../../pairing-offer.js";
 import {
   collectDaemonDiagnostics,
@@ -35,6 +36,7 @@ export interface DaemonSessionHost {
     clientId: string;
     requestId: string;
     reason: string;
+    keepTerminals: boolean;
   }): void;
 }
 
@@ -49,11 +51,13 @@ export interface DaemonSessionOptions {
   listProjects: () => Promise<PersistedProjectRecord[]>;
   listWorkspaces: () => Promise<PersistedWorkspaceRecord[]>;
   listProviderAvailability: () => Promise<ProviderAvailability[]>;
+  /** Why this host's terminals cannot be served (held by a newer Paseo's worker), if so. */
+  getTerminalsUnavailable?: () => string | null;
   getWebSocketRuntimeMetrics?: () => DaemonWebSocketRuntimeDiagnosticSnapshot | null;
   getObservationMetrics?: () => Record<string, number>;
   logger: pino.Logger;
   hubRelationships?: HubRelationshipManagement;
-  reloadConfig: () => DaemonConfigReloadResult;
+  reloadConfig: () => Promise<DaemonConfigReloadResult>;
 }
 
 /**
@@ -74,12 +78,13 @@ export class DaemonSession {
   private readonly listProjects: () => Promise<PersistedProjectRecord[]>;
   private readonly listWorkspaces: () => Promise<PersistedWorkspaceRecord[]>;
   private readonly listProviderAvailability: () => Promise<ProviderAvailability[]>;
+  private readonly getTerminalsUnavailable: () => string | null;
   private readonly getWebSocketRuntimeMetrics: () => DaemonWebSocketRuntimeDiagnosticSnapshot | null;
   private readonly getObservationMetrics: DaemonSessionOptions["getObservationMetrics"];
   private readonly logger: pino.Logger;
   private readonly selfUpdate: DaemonSelfUpdateSessionController;
   private readonly hubRelationships: HubRelationshipManagement | null;
-  private readonly reloadConfig: () => DaemonConfigReloadResult;
+  private readonly reloadConfig: () => Promise<DaemonConfigReloadResult>;
 
   constructor(options: DaemonSessionOptions) {
     this.host = options.host;
@@ -92,6 +97,7 @@ export class DaemonSession {
     this.listProjects = options.listProjects;
     this.listWorkspaces = options.listWorkspaces;
     this.listProviderAvailability = options.listProviderAvailability;
+    this.getTerminalsUnavailable = options.getTerminalsUnavailable ?? (() => null);
     this.getWebSocketRuntimeMetrics = options.getWebSocketRuntimeMetrics ?? (() => null);
     this.getObservationMetrics = options.getObservationMetrics;
     this.logger = options.logger;
@@ -173,6 +179,12 @@ export class DaemonSession {
   async handleGetStatusRequest(
     msg: Extract<SessionInboundMessage, { type: "daemon.get_status.request" }>,
   ): Promise<void> {
+    // Read outside the degraded-status fallback below: a status that cannot say whether
+    // terminal cleanup finished must fail the request, not report that nothing is left.
+    const terminalCleanupUnconfirmed = (await readUnconfirmedTerminalCleanup(this.paseoHome)).map(
+      ({ pid, role, reason, detail }) => ({ pid, role, reason, detail }),
+    );
+    const terminalsUnavailable = this.getTerminalsUnavailable();
     try {
       const pidInfo = await getPidLockInfo(this.paseoHome);
       const providers = (await this.listProviderAvailability()).map((p) => ({
@@ -192,6 +204,8 @@ export class DaemonSession {
           listen: this.daemonRuntimeConfig?.listen ?? null,
           relay: this.daemonRuntimeConfig?.getRelayConfig() ?? null,
           providers,
+          terminalCleanupUnconfirmed,
+          ...(terminalsUnavailable ? { terminalsUnavailable } : {}),
         },
       });
     } catch (error) {
@@ -208,6 +222,8 @@ export class DaemonSession {
           listen: null,
           relay: null,
           providers: [],
+          terminalCleanupUnconfirmed,
+          ...(terminalsUnavailable ? { terminalsUnavailable } : {}),
         },
       });
     }
@@ -252,13 +268,13 @@ export class DaemonSession {
     }
   }
 
-  handleConfigReloadRequest(
+  async handleConfigReloadRequest(
     msg: Extract<SessionInboundMessage, { type: "daemon.config.reload.request" }>,
-  ): void {
+  ): Promise<void> {
     try {
       this.host.emit({
         type: "daemon.config.reload.response",
-        payload: { requestId: msg.requestId, ...this.reloadConfig() },
+        payload: { requestId: msg.requestId, ...(await this.reloadConfig()) },
       });
     } catch (error) {
       this.logger.error({ err: error }, "Failed to reload daemon config");
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/project-config/project-config-session.test.ts b/packages/server/src/server/session/project-config/project-config-session.test.ts
index 6e93dff805..f8f6b59304 100644
--- a/packages/server/src/server/session/project-config/project-config-session.test.ts
+++ b/packages/server/src/server/session/project-config/project-config-session.test.ts
@@ -228,7 +228,7 @@ describe("ProjectConfigSession", () => {
       requestId: "write-uncommitted-setup",
       repoRoot,
       config: { worktree: { setup: "npm install" } },
-      expectedRevision: statPaseoConfigPath(repoRoot),
+      expectedRevision: await statPaseoConfigPath(repoRoot),
     });
 
     expect(emitted).toEqual([
diff --git a/packages/server/src/server/session/project-config/project-config-session.ts b/packages/server/src/server/session/project-config/project-config-session.ts
index 6056d08826..d2e8c419f0 100644
--- a/packages/server/src/server/session/project-config/project-config-session.ts
+++ b/packages/server/src/server/session/project-config/project-config-session.ts
@@ -1,10 +1,10 @@
-import { realpathSync } from "node:fs";
-import { resolve, sep } from "path";
+import { resolve } from "path";
 import type pino from "pino";
 import type { SessionInboundMessage, SessionOutboundMessage } from "../../messages.js";
 import type { ProjectRegistry } from "../../workspace-registry.js";
 import {
   readPaseoConfigForEdit,
+  resolveProjectConfigRoot,
   writePaseoConfigForEdit,
   type ProjectConfigRpcError,
 } from "../../../utils/paseo-config-file.js";
@@ -47,7 +47,7 @@ export class ProjectConfigSession {
       return;
     }
 
-    const result = readPaseoConfigForEdit(repoRoot);
+    const result = await readPaseoConfigForEdit(repoRoot);
     if (!result.ok) {
       this.logger.warn(
         { repoRoot, requestId: msg.requestId, outcome: result.error.code },
@@ -94,7 +94,7 @@ export class ProjectConfigSession {
       { repoRoot, requestId: msg.requestId, outcome: "write_attempt" },
       "Writing project config",
     );
-    const result = writePaseoConfigForEdit({
+    const result = await writePaseoConfigForEdit({
       repoRoot,
       config: msg.config,
       expectedRevision: msg.expectedRevision,
@@ -173,34 +173,21 @@ export class ProjectConfigSession {
   }
 
   private async resolveKnownProjectRoot(repoRoot: string): Promise<string | null> {
-    const requestedRoot = canonicalizeConfigRoot(repoRoot);
+    const requestedRoot = resolve(repoRoot);
     const projects = await this.projectRegistry.list();
-    for (const project of projects) {
-      if (project.archivedAt !== null) {
-        continue;
-      }
-      const projectRoot = canonicalizeConfigRoot(project.rootPath);
-      if (requestedRoot === projectRoot) {
-        return projectRoot;
-      }
-    }
-    return null;
+    const activeRoots = new Set(
+      projects
+        .filter((project) => project.archivedAt === null)
+        .map((project) => resolve(project.rootPath)),
+    );
+    const root = await resolveProjectConfigRoot(requestedRoot, activeRoots);
+    if (!root) return null;
+    // Authorization follows live registry state after alias IO, including archive/removal.
+    const current = await this.projectRegistry.list();
+    return current.some(
+      (project) => project.archivedAt === null && resolve(project.rootPath) === root,
+    )
+      ? root
+      : null;
   }
 }
-
-function canonicalizeConfigRoot(repoRoot: string): string {
-  const resolved = resolve(repoRoot);
-  try {
-    return stripTrailingPathSeparators(realpathSync(resolved));
-  } catch {
-    return stripTrailingPathSeparators(resolved);
-  }
-}
-
-function stripTrailingPathSeparators(path: string): string {
-  let normalized = path;
-  while (normalized.length > 1 && normalized.endsWith(sep)) {
-    normalized = normalized.slice(0, -1);
-  }
-  return normalized;
-}
diff --git a/packages/server/src/server/session/usage/usage-session.test.ts b/packages/server/src/server/session/usage/usage-session.test.ts
index 2aa65992b8..3a397094a3 100644
--- a/packages/server/src/server/session/usage/usage-session.test.ts
+++ b/packages/server/src/server/session/usage/usage-session.test.ts
@@ -15,6 +15,7 @@ test("lists reports from usage sources", async () => {
     report: { status: "available" as const, windows: [] },
   };
   const usage = new UsageSession({
+    isEnabled: () => true,
     emit: (message) => emitted.push(message),
     runtime: {
       async listUsageReports(options) {
@@ -40,6 +41,7 @@ test("lists reports from usage sources", async () => {
 test("surfaces a legacy usage-list failure as an rpc_error envelope", async () => {
   const emitted: SessionOutboundMessage[] = [];
   const usage = new UsageSession({
+    isEnabled: () => true,
     emit: (message) => emitted.push(message),
     runtime: {
       async listUsageReports() {
@@ -61,6 +63,7 @@ test("surfaces a legacy usage-list failure as an rpc_error envelope", async () =
 test("request failures terminate with an error response and no updates", async () => {
   const emitted: SessionOutboundMessage[] = [];
   const usage = new UsageSession({
+    isEnabled: () => true,
     emit: (message) => emitted.push(message),
     logger: pino({ level: "silent" }),
   });
@@ -72,3 +75,36 @@ test("request failures terminate with an error response and no updates", async (
     },
   ]);
 });
+
+test("off rejects both protocols before runtime discovery and turning on restores reports", async () => {
+  let enabled = false;
+  let calls = 0;
+  const emitted: SessionOutboundMessage[] = [];
+  const usage = new UsageSession({
+    isEnabled: () => enabled,
+    emit: (message) => emitted.push(message),
+    logger: pino({ level: "silent" }),
+    runtime: {
+      async listUsageReports() {
+        calls++;
+        return [];
+      },
+      async listLegacyUsage() {
+        calls++;
+        return { fetchedAt: "now", providers: [] };
+      },
+    },
+  });
+  await usage.handleListReports({ type: "usage.list_reports.request", requestId: "off" });
+  await usage.handleLegacyList({ type: "provider.usage.list.request", requestId: "old" });
+  expect(calls).toBe(0);
+  expect(emitted[0]).toMatchObject({ payload: { error: "Usage is off on this host." } });
+  expect(emitted[1]).toMatchObject({
+    type: "rpc_error",
+    payload: { error: "Usage is off on this host." },
+  });
+  enabled = true;
+  await usage.handleListReports({ type: "usage.list_reports.request", requestId: "on" });
+  expect(calls).toBe(1);
+  expect(emitted[2]).toMatchObject({ payload: { error: null } });
+});
diff --git a/packages/server/src/server/session/usage/usage-session.ts b/packages/server/src/server/session/usage/usage-session.ts
index 500c03a088..cd1e2e8801 100644
--- a/packages/server/src/server/session/usage/usage-session.ts
+++ b/packages/server/src/server/session/usage/usage-session.ts
@@ -9,6 +9,7 @@ export interface UsageSessionOptions {
     listUsageReports(options: ListUsageReportsOptions): Promise<UsageReportEntry[]>;
     listLegacyUsage(): Promise<{ fetchedAt: string; providers: ProviderUsage[] }>;
   };
+  isEnabled: () => boolean;
   logger: pino.Logger;
 }
 
@@ -19,6 +20,7 @@ export class UsageSession {
     msg: Extract<SessionInboundMessage, { type: "usage.list_reports.request" }>,
   ): Promise<void> {
     try {
+      if (!this.options.isEnabled()) throw new Error("Usage is off on this host.");
       if (!this.options.runtime) throw new Error("Plugin runtime is unavailable");
       await this.options.runtime.listUsageReports({
         forceRefresh: msg.forceRefresh,
@@ -49,6 +51,18 @@ export class UsageSession {
   async handleLegacyList(
     msg: Extract<SessionInboundMessage, { type: "provider.usage.list.request" }>,
   ): Promise<void> {
+    if (!this.options.isEnabled()) {
+      this.options.emit({
+        type: "rpc_error",
+        payload: {
+          requestId: msg.requestId,
+          requestType: msg.type,
+          error: "Usage is off on this host.",
+          code: "provider_usage_list_failed",
+        },
+      });
+      return;
+    }
     try {
       if (!this.options.runtime) throw new Error("Plugin runtime is unavailable");
       const usage = await this.options.runtime.listLegacyUsage();
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 0a3b8cb257..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[] = [];
@@ -175,7 +312,7 @@ test("background workspace creation preserves hooks, inheritance and durable vis
   expect(child.background).toBe(true);
   expect(visible.background).toBe(false);
   expect(human.background).toBe(false);
-  expect(events).toEqual(Array(4).fill("workspace.created"));
+  expect(events).toEqual(Array(4).fill("workspace.create.after"));
   const reloaded = new FileBackedWorkspaceRegistry(
     path.join(tmpDir, "projects", "workspaces.json"),
     logger,
@@ -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 3ac91a834a..5744c2ddeb 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
@@ -20,6 +20,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;
@@ -107,6 +108,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 +151,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 +182,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 +227,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(
@@ -252,21 +261,31 @@ 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,
+        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(
@@ -297,7 +316,7 @@ export function createWorkspaceProvisioningService(deps: {
       createdAt: timestamp,
       updatedAt: timestamp,
       ...(input.untrustedSource ? { untrustedSource: input.untrustedSource } : {}),
-      background: await resolveBackground(input),
+      ...(await resolveCreationMetadata(input)),
     });
     await workspaceRegistry.upsert(workspace, {
       expectsInitialAgent: input.expectsInitialAgent,
@@ -307,7 +326,9 @@ export function createWorkspaceProvisioningService(deps: {
   }
 
   function emitWorkspaceCreated(workspace: PersistedWorkspaceRecord): void {
-    deps.lifecycle?.emit("workspace.created", { workspace: describeHookWorkspace(workspace) });
+    deps.lifecycle?.emit("workspace.create.after", {
+      workspace: describeHookWorkspace(workspace),
+    });
   }
 
   async function resolveSourceProjectForWorktree(input: {
@@ -319,7 +340,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),
@@ -354,7 +375,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/session/workspace-recovery/workspace-recovery-service.test.ts b/packages/server/src/server/session/workspace-recovery/workspace-recovery-service.test.ts
index f738a0b0d6..5526166d05 100644
--- a/packages/server/src/server/session/workspace-recovery/workspace-recovery-service.test.ts
+++ b/packages/server/src/server/session/workspace-recovery/workspace-recovery-service.test.ts
@@ -4,6 +4,7 @@ import {
   mkdirSync,
   mkdtempSync,
   realpathSync,
+  readFileSync,
   rmSync,
   statSync,
   writeFileSync,
@@ -347,7 +348,7 @@ async function createBaseRecoveryFixture(baseBranch: string | null) {
 
 test("preserves ordinary checkout behavior when no separate base was recorded", async () => {
   const fixture = await createBaseRecoveryFixture(null);
-  writePaseoWorktreeMetadata(fixture.workspace.cwd, { baseRefName: "feature" });
+  await writePaseoWorktreeMetadata(fixture.workspace.cwd, { baseRefName: "feature" });
   await fixture.archiveAndRemove();
   await fixture.service.restore(fixture.workspace.workspaceId);
   expect((await fixture.registry.get(fixture.workspace.workspaceId))?.baseBranch).toBeNull();
@@ -430,7 +431,7 @@ test("restores the branch HEAD with a base name when the exact base is missing",
   });
   expect(existsSync(fixture.workspace.cwd)).toBe(true);
   expect((await fixture.registry.get(fixture.workspace.workspaceId))?.archivedAt).toBeNull();
-  const metadata = readPaseoWorktreeMetadata(fixture.workspace.cwd);
+  const metadata = await readPaseoWorktreeMetadata(fixture.workspace.cwd);
   expect(metadata).toMatchObject({ baseRefName: "main" });
   expect(metadata?.baseRef).toBeUndefined();
   expect(
@@ -450,7 +451,7 @@ test("restore fetches a deleted local branch from origin and retains its base",
   await fixture.archiveAndRemove();
   execFileSync("git", ["branch", "-D", "feature"], { cwd: fixture.repoDir });
   await fixture.service.restore(fixture.workspace.workspaceId);
-  expect(readPaseoWorktreeMetadata(fixture.workspace.cwd)?.baseRef).toBe("refs/heads/main");
+  expect((await readPaseoWorktreeMetadata(fixture.workspace.cwd))?.baseRef).toBe("refs/heads/main");
   expect(
     await getCheckoutStatus(fixture.workspace.cwd, { paseoHome: fixture.paseoHome }),
   ).toMatchObject({
@@ -476,3 +477,43 @@ test("restore rejects a branch checked out elsewhere without inventing another b
     }).trim(),
   ).toBe("* feature");
 });
+
+test("restores a user-created worktree at its recorded path outside Paseo's root", async () => {
+  const { tempDir, repoDir } = createGitRepository();
+  const worktreeRoot = join(realpathSync(tempDir), "external-worktree");
+  execFileSync("git", ["worktree", "add", "-b", "external-feature", worktreeRoot], {
+    cwd: repoDir,
+    stdio: "pipe",
+  });
+  const workspace = createWorkspace({
+    cwd: worktreeRoot,
+    worktreeRoot,
+    mainRepoRoot: repoDir,
+    branch: "external-feature",
+    baseBranch: "main",
+    isPaseoOwnedWorktree: false,
+  });
+  execFileSync("git", ["worktree", "remove", worktreeRoot], { cwd: repoDir, stdio: "pipe" });
+  const unarchived: string[] = [];
+  const service = createWorkspaceRecoveryService({
+    paseoHome: join(tempDir, "paseo-home"),
+    getWorkspace: async () => workspace,
+    getProject: async () => createProject({ rootPath: repoDir }),
+    isDirectory: async (target) => existsSync(target) && statSync(target).isDirectory(),
+    unarchiveWorkspace: async (record) => {
+      unarchived.push(record.workspaceId);
+    },
+  });
+  await expect(service.restore(workspace.workspaceId)).resolves.toEqual({
+    workspaceId: workspace.workspaceId,
+    action: "restore",
+  });
+  expect(readFileSync(join(worktreeRoot, "README.md"), "utf8").trim()).toBe("initial");
+  expect(
+    execFileSync("git", ["branch", "--show-current"], {
+      cwd: worktreeRoot,
+      encoding: "utf8",
+    }).trim(),
+  ).toBe("external-feature");
+  expect(unarchived).toEqual([workspace.workspaceId]);
+});
diff --git a/packages/server/src/server/session/workspace-recovery/workspace-recovery-service.ts b/packages/server/src/server/session/workspace-recovery/workspace-recovery-service.ts
index 1a715dd349..a683a07744 100644
--- a/packages/server/src/server/session/workspace-recovery/workspace-recovery-service.ts
+++ b/packages/server/src/server/session/workspace-recovery/workspace-recovery-service.ts
@@ -166,6 +166,7 @@ export function createWorkspaceRecoveryService(deps: {
     }
 
     let previousWorktreePath = workspace.worktreeRoot;
+    let hasRecordedWorktreePath = Boolean(previousWorktreePath);
     if (!previousWorktreePath) {
       // COMPAT(worktreeRestoreMissingWorktreeRoot): records created before v0.1.110
       // lack durable backing placement; remove filesystem discovery after 2027-01-17.
@@ -176,6 +177,7 @@ export function createWorkspaceRecoveryService(deps: {
       previousWorktreePath = ownership.allowed
         ? (ownership.worktreePath ?? workspace.cwd)
         : workspace.cwd;
+      hasRecordedWorktreePath = ownership.allowed;
     }
 
     let recreatedWorktreePath: string;
@@ -187,6 +189,7 @@ export function createWorkspaceRecoveryService(deps: {
 
         paseoHome: deps.paseoHome,
         worktreesRoot: deps.worktreesRoot,
+        ...(hasRecordedWorktreePath ? { worktreePath: previousWorktreePath } : {}),
       });
       recreatedWorktreePath = result.worktreePath;
     } catch (error) {
diff --git a/packages/server/src/server/session/workspace-scripts/workspace-scripts-service.test.ts b/packages/server/src/server/session/workspace-scripts/workspace-scripts-service.test.ts
index 18ae1f1366..664fcc14de 100644
--- a/packages/server/src/server/session/workspace-scripts/workspace-scripts-service.test.ts
+++ b/packages/server/src/server/session/workspace-scripts/workspace-scripts-service.test.ts
@@ -1,3 +1,5 @@
+import { DaemonConfigStore } from "../../daemon-config-store.js";
+import type { PaseoServicePortAllocation } from "@getpaseo/protocol/paseo-config-schema";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -82,6 +84,7 @@ interface BuildOptions {
   spawnThrows?: string;
   runtimeStore?: Pick<WorkspaceRuntimeStore, "get">;
   automationError?: Error;
+  getGlobalServicePorts?: () => Promise<PaseoServicePortAllocation | undefined>;
 }
 
 function buildService(options: BuildOptions = {}) {
@@ -111,6 +114,7 @@ function buildService(options: BuildOptions = {}) {
     getDaemonTcpHost: () => "127.0.0.1",
     serviceProxyPublicBaseUrl: null,
     resolveScriptHealth: null,
+    getGlobalServicePorts: options.getGlobalServicePorts ?? (async () => undefined),
     logger,
     emit: (message) => emitted.push(message),
     publishStatusUpdate: (message) => published.push(message),
@@ -152,18 +156,42 @@ afterEach(() => {
   }
 });
 
+test("reads external service-port edits at the next launch without construction IO", async () => {
+  const home = mkdtempSync(join(tmpdir(), "workspace-service-ports-"));
+  tempDirs.push(home);
+  const store = new DaemonConfigStore(home, {
+    providers: {},
+    mcp: { enabled: true, injectIntoAgents: false },
+  });
+  const { service, spawnCalls } = buildService({
+    getGlobalServicePorts: () => store.readServicePorts(),
+  });
+  writeFileSync(
+    join(home, "config.json"),
+    JSON.stringify({ worktrees: { servicePorts: { range: "9000-9999" } } }),
+  );
+  await service.start(request);
+  expect(spawnCalls.map((call) => call.globalServicePorts)).toEqual([{ range: "9000-9999" }]);
+});
+
 describe("buildSnapshot", () => {
   test("returns no scripts when the service proxy is unavailable", async () => {
     const { service } = buildService({ serviceProxy: null });
     expect(
-      service.buildSnapshot({ workspaceId: "ws-1", cwd: "/tmp/repo" } as PersistedWorkspaceRecord),
+      await service.buildSnapshot({
+        workspaceId: "ws-1",
+        cwd: "/tmp/repo",
+      } as PersistedWorkspaceRecord),
     ).toEqual([]);
   });
 
   test("returns no scripts when the runtime store is unavailable", async () => {
     const { service } = buildService({ scriptRuntimeStore: null });
     expect(
-      service.buildSnapshot({ workspaceId: "ws-1", cwd: "/tmp/repo" } as PersistedWorkspaceRecord),
+      await service.buildSnapshot({
+        workspaceId: "ws-1",
+        cwd: "/tmp/repo",
+      } as PersistedWorkspaceRecord),
     ).toEqual([]);
   });
 
@@ -172,7 +200,7 @@ describe("buildSnapshot", () => {
     tempDirs.push(dir);
     const { service } = buildService();
     expect(
-      service.buildSnapshot({ workspaceId: "ws-1", cwd: dir } as PersistedWorkspaceRecord),
+      await service.buildSnapshot({ workspaceId: "ws-1", cwd: dir } as PersistedWorkspaceRecord),
     ).toEqual([]);
   });
 
@@ -207,7 +235,7 @@ describe("buildSnapshot", () => {
       runtimeStore: { get: () => null },
     });
 
-    expect(service.buildSnapshot(workspace, project)[0]?.hostname).toBe(
+    expect((await service.buildSnapshot(workspace, project))[0]?.hostname).toBe(
       serviceProxy.projectWorkspaceService({
         projectSlug: deriveProjectServiceSlug(project),
         branchName: workspace.branch,
@@ -352,10 +380,12 @@ describe("start", () => {
       daemonPort: 6767,
       daemonListenHost: "127.0.0.1",
     });
-    expect(published).toContainEqual({
-      type: "script_status_update",
-      payload: { workspaceId: "ws-1", scripts: [] },
-    });
+    await expect
+      .poll(() => published)
+      .toContainEqual({
+        type: "script_status_update",
+        payload: { workspaceId: "ws-1", scripts: [] },
+      });
     expect(emitted).toContainEqual({
       type: "start_workspace_script_response",
       payload: {
@@ -449,7 +479,7 @@ describe("start", () => {
     const serviceProxy = createServiceProxySubsystem({ logger });
     const { service, spawnCalls } = buildService({ workspace, project, serviceProxy });
 
-    const snapshot = service.buildSnapshot(workspace, project);
+    const snapshot = await service.buildSnapshot(workspace, project);
     await service.start({ ...request, workspaceId: workspace.workspaceId });
 
     const started = spawnCalls[0]!;
diff --git a/packages/server/src/server/session/workspace-scripts/workspace-scripts-service.ts b/packages/server/src/server/session/workspace-scripts/workspace-scripts-service.ts
index 103c3ed16b..eebad7f1e5 100644
--- a/packages/server/src/server/session/workspace-scripts/workspace-scripts-service.ts
+++ b/packages/server/src/server/session/workspace-scripts/workspace-scripts-service.ts
@@ -43,7 +43,7 @@ export interface WorkspaceScriptsService {
   buildSnapshot(
     workspace: PersistedWorkspaceRecord,
     project?: PersistedProjectRecord | null,
-  ): WorkspaceScriptsPayload;
+  ): Promise<WorkspaceScriptsPayload>;
   emitStatusUpdate(workspaceId: string, workspaceDirectory: string): Promise<void>;
   list(workspaceId: string): Promise<WorkspaceScriptPayload[]>;
   launch(input: { workspaceId: string; scriptName: string }): Promise<WorkspaceScriptPayload>;
@@ -62,7 +62,7 @@ export function createWorkspaceScriptsService(deps: {
   getDaemonTcpHost: (() => string | null) | null;
   serviceProxyPublicBaseUrl: string | null;
   resolveScriptHealth: ((hostname: string) => ScriptHealthState | null) | null;
-  globalServicePorts?: PaseoServicePortAllocation;
+  getGlobalServicePorts: () => Promise<PaseoServicePortAllocation | undefined>;
   logger: pino.Logger;
   emit: (message: SessionOutboundMessage) => void;
   // Script status is daemon state, so it reaches every client, not only the requester.
@@ -81,7 +81,7 @@ export function createWorkspaceScriptsService(deps: {
     getDaemonTcpHost,
     serviceProxyPublicBaseUrl,
     resolveScriptHealth,
-    globalServicePorts,
+    getGlobalServicePorts,
     logger,
     emit,
     publishStatusUpdate,
@@ -110,17 +110,17 @@ export function createWorkspaceScriptsService(deps: {
     };
   }
 
-  function buildSnapshot(
+  async function buildSnapshot(
     workspace: PersistedWorkspaceRecord,
     project: PersistedProjectRecord | null = null,
-  ): WorkspaceScriptsPayload {
+  ): Promise<WorkspaceScriptsPayload> {
     if (!serviceProxy || !scriptRuntimeStore) {
       return [];
     }
     return buildWorkspaceScriptPayloads({
       workspaceId: workspace.workspaceId,
       workspaceDirectory: workspace.cwd,
-      paseoConfig: readPaseoConfigForProjection(workspace.cwd, logger),
+      paseoConfig: await readPaseoConfigForProjection(workspace.cwd, logger),
       serviceProxy,
       runtimeStore: scriptRuntimeStore,
       daemonPort: getDaemonTcpPort?.() ?? null,
@@ -137,7 +137,7 @@ export function createWorkspaceScriptsService(deps: {
       const project = await projectRegistry.get(workspace.projectId);
       publishStatusUpdate({
         type: "script_status_update",
-        payload: { workspaceId, scripts: buildSnapshot(workspace, project) },
+        payload: { workspaceId, scripts: await buildSnapshot(workspace, project) },
       });
     } catch (error) {
       logger.warn({ err: error, workspaceId }, "Failed to project workspace script status");
@@ -172,6 +172,7 @@ export function createWorkspaceScriptsService(deps: {
 
   async function launchProcess(input: { workspaceId: string; scriptName: string }) {
     const available = requireAvailable();
+    const globalServicePorts = await getGlobalServicePorts();
     const workspace = await getWorkspace(input.workspaceId);
     await assertAutomationAllowed(workspace.workspaceId);
     const project = await projectRegistry.get(workspace.projectId);
@@ -202,7 +203,7 @@ export function createWorkspaceScriptsService(deps: {
     scriptName: string;
   }): Promise<WorkspaceScriptPayload> {
     const { workspace, project } = await launchProcess(input);
-    const script = buildSnapshot(workspace, project).find(
+    const script = (await buildSnapshot(workspace, project)).find(
       (entry) => entry.scriptName === input.scriptName,
     );
     if (!script) {
@@ -230,7 +231,7 @@ export function createWorkspaceScriptsService(deps: {
     // The launcher's terminal exit listener owns route removal and runtime state updates.
     await available.terminalManager.killTerminalAndWait(runtime.terminalId);
 
-    const script = buildSnapshot(workspace, project).find(
+    const script = (await buildSnapshot(workspace, project)).find(
       (entry) => entry.scriptName === input.scriptName,
     );
     if (!script) {
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
new file mode 100644
index 0000000000..b6490e8f88
--- /dev/null
+++ b/packages/server/src/server/test-fixtures/reconciliation-registries.ts
@@ -0,0 +1,118 @@
+import type pino from "pino";
+import { createPersistedProjectRecord } from "../workspace-registry.js";
+import type {
+  PersistedProjectRecord,
+  PersistedWorkspaceRecord,
+  ProjectRegistry,
+  WorkspaceRegistry,
+} from "../workspace-registry.js";
+
+export function createTestRegistries() {
+  let archiveGate: {
+    started: ReturnType<typeof deferred>;
+    release: ReturnType<typeof deferred>;
+  } | null = null;
+  const holdNextArchive = () => {
+    archiveGate = { started: deferred(), release: deferred() };
+    return archiveGate;
+  };
+  const projects = new Map<string, PersistedProjectRecord>();
+  const workspaces = new Map<string, PersistedWorkspaceRecord>();
+
+  const projectRegistry: ProjectRegistry = {
+    initialize: async () => {},
+    existsOnDisk: async () => true,
+    list: async () => Array.from(projects.values()),
+    get: async (id: string) => projects.get(id) ?? null,
+    getOrCreateActiveByRoot: async (input) => {
+      const existing = Array.from(projects.values()).find(
+        (project) => !project.archivedAt && project.rootPath === input.rootPath,
+      );
+      if (existing) return existing;
+      const record = createPersistedProjectRecord({
+        projectId: `prj_${projects.size}`,
+        rootPath: input.rootPath,
+        kind: input.kind,
+        displayName: input.displayName,
+        createdAt: input.timestamp,
+        updatedAt: input.timestamp,
+      });
+      projects.set(record.projectId, record);
+      return record;
+    },
+    update: async (id, updater) => {
+      const current = projects.get(id);
+      if (!current) return null;
+      const updated = updater(current);
+      projects.set(id, updated);
+      return updated;
+    },
+    upsert: async (record: PersistedProjectRecord) => {
+      projects.set(record.projectId, record);
+    },
+    archive: async (id: string, archivedAt: string) => {
+      const existing = projects.get(id);
+      if (existing) {
+        projects.set(id, { ...existing, archivedAt, updatedAt: archivedAt });
+      }
+    },
+    remove: async (id: string) => {
+      projects.delete(id);
+    },
+  };
+
+  const workspaceRegistry: WorkspaceRegistry = {
+    initialize: async () => {},
+    existsOnDisk: async () => true,
+    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);
+      if (!existing) return null;
+      const updated = updater(existing);
+      workspaces.set(id, updated);
+      return updated;
+    },
+    upsert: async (record: PersistedWorkspaceRecord) => {
+      workspaces.set(record.workspaceId, record);
+    },
+    archive: async (id: string, archivedAt: string) => {
+      const gate = archiveGate;
+      archiveGate = null;
+      if (gate) {
+        gate.started.resolve();
+        await gate.release.promise;
+      }
+      const existing = workspaces.get(id);
+      if (!existing || existing.archivedAt) return false;
+      workspaces.set(id, { ...existing, archivedAt, updatedAt: archivedAt });
+      return true;
+    },
+    remove: async (id: string) => {
+      workspaces.delete(id);
+    },
+  };
+
+  return { projects, workspaces, projectRegistry, workspaceRegistry, holdNextArchive };
+}
+
+export function createTestLogger() {
+  const logger = {
+    child: () => logger,
+    trace: () => undefined,
+    debug: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+  };
+  return logger as unknown as pino.Logger;
+}
+
+export function deferred(): { promise: Promise<void>; resolve(): void } {
+  let resolve!: () => void;
+  const promise = new Promise<void>((accept) => {
+    resolve = accept;
+  });
+  return { promise, resolve };
+}
diff --git a/packages/server/src/server/test-fixtures/reconciliation-responsiveness.ts b/packages/server/src/server/test-fixtures/reconciliation-responsiveness.ts
new file mode 100644
index 0000000000..dd73ce38a8
--- /dev/null
+++ b/packages/server/src/server/test-fixtures/reconciliation-responsiveness.ts
@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import { createHook, executionAsyncResource } from "node:async_hooks";
+import { MessagePort } from "node:worker_threads";
+import path from "node:path";
+import { stat } from "node:fs/promises";
+import { setImmediate as nextTurn } from "node:timers/promises";
+import { measureMainThreadWork } from "../../test-utils/main-thread-work.js";
+import { createTestRegistries, createTestLogger } from "./reconciliation-registries.js";
+import {
+  createPersistedProjectRecord,
+  createPersistedWorkspaceRecord,
+} from "../workspace-registry.js";
+import { WorkspaceReconciliationService } from "../workspace-reconciliation-service.js";
+import { deriveProjectKey } from "../project-key.js";
+
+const rootPath = process.argv[2];
+if (!rootPath) throw new Error("Project root is required");
+const timestamp = "2025-01-01T00:00:00.000Z";
+const { projects, workspaces, projectRegistry, workspaceRegistry } = createTestRegistries();
+projects.set(
+  "p1",
+  createPersistedProjectRecord({
+    projectId: "p1",
+    rootPath,
+    projectKey: deriveProjectKey({
+      rootPath,
+      remoteUrl: null,
+      worktreeRoot: null,
+      mainRepoRoot: null,
+    }),
+    kind: "non_git",
+    displayName: "project",
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  }),
+);
+for (let i = 0; i < 20000; i++) {
+  const workspaceId = `w${i}`;
+  workspaces.set(
+    workspaceId,
+    createPersistedWorkspaceRecord({
+      workspaceId,
+      projectId: "p1",
+      cwd: path.join(rootPath, workspaceId),
+      kind: "directory",
+      displayName: workspaceId,
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    }),
+  );
+}
+const service = new WorkspaceReconciliationService({
+  projectRegistry,
+  workspaceRegistry,
+  logger: createTestLogger(),
+});
+
+// Compile before launch and measure in plain Node, outside the test runner's
+// thread and TypeScript loader. Keep the first real reconciliation cold.
+// Initialize async filesystem support using the bundle, leaving every project
+// and workspace path untouched until the first reconciliation.
+await stat(process.argv[1]);
+// Collect fixture allocations before the measured run; allocations made by
+// reconciliation itself remain part of its budget.
+assert.ok(global.gc, "Launch the probe with --expose-gc");
+global.gc();
+await nextTurn();
+let workerMessages = 0;
+const activity = createHook({
+  before() {
+    if (executionAsyncResource() instanceof MessagePort) workerMessages++;
+  },
+}).enable();
+try {
+  const measured = await measureMainThreadWork("workspace reconciliation main-thread work", () =>
+    service.runOnce(),
+  );
+  activity.disable();
+  process.stdout.write(
+    JSON.stringify({
+      blockingMs: measured.blockingMs,
+      filesystemRequests: measured.filesystemRequests,
+      yields: measured.yields,
+      workerMessages,
+      changesApplied: measured.result.changesApplied.length,
+      allArchived: [...workspaces.values()].every((workspace) => workspace.archivedAt !== null),
+    }),
+  );
+} finally {
+  activity.disable();
+  service.dispose();
+}
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 1c7127d144..4304a767e1 100644
--- a/packages/server/src/server/test-utils/fake-agent-client.ts
+++ b/packages/server/src/server/test-utils/fake-agent-client.ts
@@ -60,14 +60,19 @@ interface FakeAgentSessionOptions {
   closeSession?: () => Promise<void>;
   onStartTurn?: (prompt: AgentPromptInput, config: AgentSessionConfig) => void;
   beforeTurnComplete?: (prompt: AgentPromptInput) => Promise<void>;
+  steerActiveTurn?: AgentSession["steerActiveTurn"];
+  onInterrupt?: () => void;
   historyEvents?: readonly AgentStreamEvent[];
 }
 
 export interface TestAgentClientOptions {
   beforeCreateSession?: (config: AgentSessionConfig) => Promise<void>;
+  beforeResumeSession?: (handle: AgentPersistenceHandle) => Promise<void>;
   closeSession?: () => Promise<void>;
   onStartTurn?: (prompt: AgentPromptInput, config: AgentSessionConfig) => void;
   beforeTurnComplete?: (prompt: AgentPromptInput) => Promise<void>;
+  steerActiveTurn?: AgentSession["steerActiveTurn"];
+  onInterrupt?: () => void;
   supportsMcpServers?: boolean;
   historyEvents?: readonly AgentStreamEvent[];
 }
@@ -340,6 +345,8 @@ class FakeAgentSession implements AgentSession {
   private nextTurnOrdinal = 0;
   private activeForegroundTurnId: string | null = null;
 
+  readonly steerActiveTurn: AgentSession["steerActiveTurn"];
+  private readonly onInterrupt: (() => void) | undefined;
   private readonly closeSession: (() => Promise<void>) | undefined;
   private readonly onStartTurn: TestAgentClientOptions["onStartTurn"];
   private readonly beforeTurnComplete: ((prompt: AgentPromptInput) => Promise<void>) | undefined;
@@ -354,6 +361,8 @@ class FakeAgentSession implements AgentSession {
     this.config = options.config;
     this.id = options.sessionId ?? randomUUID();
     this.memoryMarker = options.memoryMarker ?? null;
+    this.steerActiveTurn = options.steerActiveTurn;
+    this.onInterrupt = options.onInterrupt;
     this.closeSession = options.closeSession;
     this.onStartTurn = options.onStartTurn;
     this.beforeTurnComplete = options.beforeTurnComplete;
@@ -896,6 +905,7 @@ class FakeAgentSession implements AgentSession {
   }
 
   async interrupt(): Promise<void> {
+    this.onInterrupt?.();
     this.interruptSignal.resolve();
   }
 
@@ -1234,6 +1244,8 @@ class FakeAgentClient implements AgentClient {
       closeSession: this.options.closeSession,
       onStartTurn: this.options.onStartTurn,
       beforeTurnComplete: this.options.beforeTurnComplete,
+      steerActiveTurn: this.options.steerActiveTurn,
+      onInterrupt: this.options.onInterrupt,
       historyEvents: this.options.historyEvents,
     });
   }
@@ -1243,6 +1255,7 @@ class FakeAgentClient implements AgentClient {
     overrides?: Partial<AgentSessionConfig>,
     _launchContext?: AgentLaunchContext,
   ): Promise<AgentSession> {
+    await this.options.beforeResumeSession?.(handle);
     const cfg: AgentSessionConfig = {
       provider: this.provider,
       cwd: overrides?.cwd ?? process.cwd(),
@@ -1261,6 +1274,8 @@ class FakeAgentClient implements AgentClient {
       closeSession: this.options.closeSession,
       onStartTurn: this.options.onStartTurn,
       beforeTurnComplete: this.options.beforeTurnComplete,
+      steerActiveTurn: this.options.steerActiveTurn,
+      onInterrupt: this.options.onInterrupt,
       historyEvents: this.options.historyEvents,
     });
   }
diff --git a/packages/server/src/server/test-utils/finish-subscription-daemon.ts b/packages/server/src/server/test-utils/finish-subscription-daemon.ts
index d35bc55ec8..eafe11e74a 100644
--- a/packages/server/src/server/test-utils/finish-subscription-daemon.ts
+++ b/packages/server/src/server/test-utils/finish-subscription-daemon.ts
@@ -9,18 +9,24 @@ const root = process.argv[2];
 if (!root || !process.send) throw new Error("Expected isolated test home and IPC parent");
 await mkdir(join(root, "static"), { recursive: true });
 const held = Promise.withResolvers<void>();
+const fixture = JSON.parse(process.argv[4] ?? "{}") as { holdResume?: boolean };
+const resumeReleased = Promise.withResolvers<void>();
+if (!fixture.holdResume) resumeReleased.resolve();
 const daemon = await createTestPaseoDaemon({
   paseoHomeRoot: root,
+  ...JSON.parse(process.argv[3] ?? "{}"),
   staticDir: join(root, "static"),
   logger: pino({ level: "warn" }, pino.destination(join(root, "fixture.log"))),
   cleanup: false,
   mcpEnabled: true,
   agentClients: createTestAgentClients({
-    onStartTurn: (prompt) => {
+    onStartTurn: (prompt, config) => {
+      void appendFile(join(root, "all-prompts.jsonl"), `${JSON.stringify({ prompt, config })}\n`);
       if (String(prompt).includes('kind="agent-notification"')) {
         void appendFile(join(root, "parent-prompts.jsonl"), `${JSON.stringify(prompt)}\n`);
       }
     },
+    beforeResumeSession: () => resumeReleased.promise,
     beforeTurnComplete: (prompt) =>
       String(prompt).includes("HOLD_CHILD") ? held.promise : Promise.resolve(),
   }),
@@ -28,6 +34,7 @@ const daemon = await createTestPaseoDaemon({
 process.send({ port: daemon.port, paseoHome: daemon.paseoHome, cwd: daemon.staticDir });
 process.on("message", (message) => {
   if (message === "finish") held.resolve();
+  if (message === "release-resume") resumeReleased.resolve();
   if (message === "stop") {
     void daemon.close().then(
       () => process.exit(0),
diff --git a/packages/server/src/server/test-utils/paseo-daemon.test.ts b/packages/server/src/server/test-utils/paseo-daemon.test.ts
index 4ee417c221..3fbb0b5232 100644
--- a/packages/server/src/server/test-utils/paseo-daemon.test.ts
+++ b/packages/server/src/server/test-utils/paseo-daemon.test.ts
@@ -45,7 +45,15 @@ describe("createTestPaseoDaemon", () => {
       createTestPaseoDaemon({ listenPort: takenPort, cleanup: false, mcpEnabled: false }),
     ).rejects.toMatchObject({ code: "EADDRINUSE" });
 
-    expect(await readdir(scratchTmp)).toEqual([]);
+    // A home under this scratch dir is too long for a unix socket path, so the terminal worker
+    // listens in the per-user `paseo-<uid>` directory of the temp root. Like tmux's, that
+    // owner-only directory is shared by every worker and outlives them; it must be empty.
+    const sharedSocketDir = `paseo-${process.getuid?.() ?? 0}`;
+    const leftovers = await readdir(scratchTmp);
+    expect(leftovers.filter((name) => name !== sharedSocketDir)).toEqual([]);
+    if (leftovers.includes(sharedSocketDir)) {
+      expect(await readdir(path.join(scratchTmp, sharedSocketDir))).toEqual([]);
+    }
   }, 60_000);
 });
 
diff --git a/packages/server/src/server/test-utils/paseo-daemon.ts b/packages/server/src/server/test-utils/paseo-daemon.ts
index a1f8369b59..766fd49919 100644
--- a/packages/server/src/server/test-utils/paseo-daemon.ts
+++ b/packages/server/src/server/test-utils/paseo-daemon.ts
@@ -52,6 +52,8 @@ interface TestPaseoDaemonOptions {
   trustedProxies?: PaseoDaemonConfig["trustedProxies"];
   agentProfiles?: AgentProfile[];
   autoArchiveAfterMerge?: boolean;
+  resumeOnStartup?: boolean;
+  resumePrompt?: string;
   pluginsEnabled?: PaseoDaemonConfig["pluginsEnabled"];
   builtinPlugins?: BuiltinPluginLoader;
   plugins?: PaseoDaemonConfig["plugins"];
@@ -226,6 +228,8 @@ async function prepareTestDaemonConfig(
     downloadTokenTtlMs: options.downloadTokenTtlMs,
     agentProfiles: options.agentProfiles,
     autoArchiveAfterMerge: options.autoArchiveAfterMerge,
+    resumeOnStartup: options.resumeOnStartup,
+    resumePrompt: options.resumePrompt,
     pluginsEnabled: options.pluginsEnabled,
     plugins: options.plugins,
   };
diff --git a/packages/server/src/server/test-utils/session-stubs.ts b/packages/server/src/server/test-utils/session-stubs.ts
index 922f673935..89b7fcbcb9 100644
--- a/packages/server/src/server/test-utils/session-stubs.ts
+++ b/packages/server/src/server/test-utils/session-stubs.ts
@@ -37,6 +37,7 @@ export function asAgentManager(stub: {
   return createStub<SessionOptions["agentManager"]>({
     listProviderSubagentActivity: () => [],
     getRetiredInternalAgent: () => null,
+    getAgentBackgroundWorkSummary: () => undefined,
     ...stub,
   });
 }
@@ -45,6 +46,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,
diff --git a/packages/server/src/server/utils/diff-highlighter.test.ts b/packages/server/src/server/utils/diff-highlighter.test.ts
index fda98d6cbf..794cd00856 100644
--- a/packages/server/src/server/utils/diff-highlighter.test.ts
+++ b/packages/server/src/server/utils/diff-highlighter.test.ts
@@ -1,7 +1,11 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
+import { setImmediate } from "node:timers/promises";
+import { measureMainThreadWork } from "../../test-utils/main-thread-work.js";
+import { SessionDelivery } from "../session/owned-subscriptions/index.js";
+import { highlightCode, highlightCodeWithBudget } from "@getpaseo/highlight";
 import {
   parseDiff,
   reconstructNewFile,
@@ -819,3 +823,139 @@ index 1111111..2222222 100644
     }
   });
 });
+
+describe("diff highlighting budget", () => {
+  it.each(["supplied", "local"] as const)(
+    "keeps a one-line diff on a 5 MiB %s source responsive using hunk tokens",
+    async (source) => {
+      const cwd = mkdtempSync(join(tmpdir(), "diff-highlight-budget-"));
+      const oldFileContent = "const value = Math.max(42, 7);\n".repeat(
+        Math.ceil((5 * 1024 * 1024) / 30),
+      );
+      const newFileContent = oldFileContent.replace("42", "43");
+      writeFileSync(join(cwd, "example.ts"), newFileContent);
+      const file = parseDiff(`diff --git a/example.ts b/example.ts
+--- a/example.ts
++++ b/example.ts
+@@ -1 +1 @@
+-const value = Math.max(42, 7);
++const value = Math.max(43, 7);`)[0];
+      try {
+        const { result: highlighted, blockingMs } = await measureMainThreadWork(
+          `diff highlight 5MiB ${source} main-thread work`,
+          () =>
+            highlightDiffWithFileContent(
+              file,
+              cwd,
+              source === "supplied" ? { oldFileContent } : {},
+            ),
+        );
+        expect(blockingMs).toBeLessThan(50);
+        expect(highlighted).toEqual(highlightDiffFromHunks(file));
+      } finally {
+        rmSync(cwd, { recursive: true, force: true });
+      }
+    },
+    30_000,
+  );
+
+  it("preserves byte-identical tokens below the budget, including multiline syntax", async () => {
+    const oldFileContent = "/*\nold comment\n*/\nconst value = 42;";
+    const newFileContent = oldFileContent.replace("old", "new");
+    const file = parseDiff(`diff --git a/example.ts b/example.ts
+--- a/example.ts
++++ b/example.ts
+@@ -2 +2 @@
+-old comment
++new comment`)[0];
+    const highlighted = await highlightDiffWithFileContent(file, ".", {
+      oldFileContent,
+      newFileContent,
+    });
+    expect(JSON.stringify(highlighted.hunks[0].lines[1].tokens)).toBe(
+      JSON.stringify(highlightCode(oldFileContent, file.path)[1]),
+    );
+    expect(JSON.stringify(highlighted.hunks[0].lines[2].tokens)).toBe(
+      JSON.stringify(highlightCode(newFileContent, file.path)[1]),
+    );
+  });
+});
+
+it("disconnecting the requesting source stops a parser between highlight steps", async () => {
+  const delivery = new SessionDelivery(() => {});
+  const source = {};
+  delivery.attach(source, true);
+  const yielded = Promise.withResolvers<void>();
+  let result: Awaited<ReturnType<typeof highlightCodeWithBudget>> = [];
+  const pending = delivery.request(source, { type: "ping", requestId: "highlight" }, async () => {
+    result = await highlightCodeWithBudget(
+      "const value = Math.max(42, 7);\n".repeat(3_000),
+      "file.ts",
+      {
+        signal: delivery.requestSignal,
+        yieldToEventLoop: () => {
+          yielded.resolve();
+          return setImmediate();
+        },
+      },
+    );
+  });
+  await yielded.promise;
+  await delivery.detach(source);
+  await pending;
+  expect(result).toBeNull();
+});
+
+it("keeps real session.ts diffs highlighted and byte-identical under the source budget", async () => {
+  const cwd = mkdtempSync(join(tmpdir(), "diff-highlight-real-source-"));
+  try {
+    const oldFileContent = readFileSync(new URL("../session.ts", import.meta.url), "utf8");
+    const newFileContent = oldFileContent.replace(
+      "WorkspaceRuntimeStore",
+      "WorkspaceRuntimeSnapshot",
+    );
+    writeFileSync(join(cwd, "session.ts"), newFileContent);
+    const oldLine = oldFileContent.split("\n")[0];
+    const newLine = newFileContent.split("\n")[0];
+    const [file] = parseDiff(`diff --git a/session.ts b/session.ts
+--- a/session.ts
++++ b/session.ts
+@@ -1 +1 @@
+-${oldLine}
++${newLine}`);
+    const highlighted = await highlightDiffWithFileContent(file, cwd, { oldFileContent });
+    const removed = highlighted.hunks[0].lines.find((line) => line.type === "remove");
+    const added = highlighted.hunks[0].lines.find((line) => line.type === "add");
+    expect(removed?.tokens).toEqual(highlightCode(oldFileContent, "session.ts")[0]);
+    expect(added?.tokens).toEqual(highlightCode(newFileContent, "session.ts")[0]);
+    expect(added?.tokens?.some((token) => token.style !== null)).toBe(true);
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+it("highlights a one-line hunk from an over-budget JSON source without blocking the loop", async () => {
+  const cwd = mkdtempSync(join(tmpdir(), "diff-highlight-large-json-"));
+  const oldFileContent = `{\n${'  "value": 42,\n'.repeat(100_000)}  "last": true\n}`;
+  const newFileContent = oldFileContent.replace("42", "43");
+  writeFileSync(join(cwd, "package-lock.json"), newFileContent);
+  const [file] = parseDiff(`diff --git a/package-lock.json b/package-lock.json
+--- a/package-lock.json
++++ b/package-lock.json
+@@ -2 +2 @@
+-  "value": 42,
++  "value": 43,`);
+  try {
+    const { result, blockingMs } = await measureMainThreadWork(
+      "diff highlight large JSON main-thread work",
+      () => highlightDiffWithFileContent(file, cwd, { oldFileContent }),
+    );
+    expect(blockingMs).toBeLessThan(50);
+    expect(result.hunks[0].lines.find((line) => line.type === "add")?.tokens).toContainEqual({
+      text: "43",
+      style: "number",
+    });
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
diff --git a/packages/server/src/server/utils/diff-highlighter.ts b/packages/server/src/server/utils/diff-highlighter.ts
index 3c2df279e2..e3a0460322 100644
--- a/packages/server/src/server/utils/diff-highlighter.ts
+++ b/packages/server/src/server/utils/diff-highlighter.ts
@@ -1,6 +1,14 @@
-import { readFile } from "node:fs/promises";
+import { open } from "node:fs/promises";
+import { constants } from "node:fs";
+import { setImmediate } from "node:timers/promises";
 import { resolve } from "node:path";
-import { highlightCode, isLanguageSupported, type HighlightToken } from "@getpaseo/highlight";
+import {
+  highlightCode,
+  highlightCodeWithBudget,
+  HIGHLIGHT_MAX_SOURCE_BYTES,
+  isLanguageSupported,
+  type HighlightToken,
+} from "@getpaseo/highlight";
 import { unquoteGitPath } from "../../utils/git-quoted-path.js";
 
 const MAX_DIFF_HIGHLIGHT_LINE_CHARS = 10_000;
@@ -30,11 +38,13 @@ export interface ParsedDiffFile {
 }
 
 interface HighlightDiffWithFileContentOptions {
+  signal?: AbortSignal;
   oldFileContent?: string | null;
   newFileContent?: string | null;
 }
 
 interface ParseAndHighlightDiffOptions {
+  signal?: AbortSignal;
   getOldFileContent?: (file: ParsedDiffFile) => Promise<string | null>;
   getNewFileContent?: (file: ParsedDiffFile) => Promise<string | null>;
 }
@@ -269,20 +279,71 @@ function buildTokenLookup(
   return lookup;
 }
 
-function buildFullFileTokenLookup(
+async function buildFullFileTokenLookup(
   fileContent: string,
   path: string,
-): Map<number, HighlightToken[]> | null {
-  if (hasOversizedLine(fileContent)) return null;
+  signal?: AbortSignal,
+): Promise<Map<number, HighlightToken[]> | null> {
+  const highlighted = await highlightCodeWithBudget(fileContent, path, {
+    yieldToEventLoop: setImmediate,
+    signal,
+  });
+  if (!highlighted) return null;
+  return new Map(highlighted.map((tokens, index) => [index + 1, tokens]));
+}
 
-  const lookup = new Map<number, HighlightToken[]>();
-  const highlighted = highlightCode(fileContent, path);
-
-  for (let i = 0; i < highlighted.length; i++) {
-    lookup.set(i + 1, highlighted[i]);
+async function readHighlightSource(path: string): Promise<string | null> {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > HIGHLIGHT_MAX_SOURCE_BYTES) return null;
+    const buffer = Buffer.alloc(Math.min(stat.size, HIGHLIGHT_MAX_SOURCE_BYTES) + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, null);
+      if (bytesRead === 0) break;
+      offset += bytesRead;
+    }
+    // A full buffer includes the extra byte: the source grew after stat.
+    return offset === buffer.length ? null : buffer.toString("utf8", 0, offset);
+  } catch {
+    return null;
+  } finally {
+    await handle?.close();
   }
+}
 
-  return lookup;
+function exceedsSourceBudget(content: string): boolean {
+  return (
+    content.length > HIGHLIGHT_MAX_SOURCE_BYTES ||
+    Buffer.byteLength(content) > HIGHLIGHT_MAX_SOURCE_BYTES
+  );
+}
+
+async function buildBudgetedReconstructedTokens(file: ParsedDiffFile, signal?: AbortSignal) {
+  const newLines = reconstructNewFile(file.hunks);
+  const oldLines = reconstructOldFile(file.hunks);
+  const build = async (lines: Map<number, string>) => {
+    // Sparse hunks can be far apart. Admit the span before filling its gaps.
+    const numbers = Array.from(lines.keys());
+    if (numbers.length && numbers[numbers.length - 1] - numbers[0] > HIGHLIGHT_MAX_SOURCE_BYTES)
+      return null;
+    let bytes = 0;
+    for (const line of lines.values()) {
+      bytes += Buffer.byteLength(line) + 1;
+      if (bytes > HIGHLIGHT_MAX_SOURCE_BYTES) return null;
+    }
+    const highlighted = await highlightCodeWithBudget(buildFileContent(lines), file.path, {
+      yieldToEventLoop: setImmediate,
+      signal,
+    });
+    return highlighted ? buildTokenLookup(lines, highlighted) : null;
+  };
+  const newTokensByLine = await build(newLines);
+  if (!newTokensByLine) return null;
+  const oldTokensByLine = await build(oldLines);
+  return oldTokensByLine ? { newTokensByLine, oldTokensByLine } : null;
 }
 
 function buildReconstructedTokenLookups(file: ParsedDiffFile): {
@@ -328,36 +389,50 @@ export async function highlightDiffWithFileContent(
   cwd: string,
   options: HighlightDiffWithFileContentOptions = {},
 ): Promise<ParsedDiffFile> {
-  if (!isLanguageSupported(file.path) || hasOversizedDiffLine(file)) {
-    return file;
-  }
+  if (!isDiffHighlightEligible(file, options)) return file;
 
-  let newTokensByLine: Map<number, HighlightToken[]> | null = null;
-  const oldTokensByLine =
-    typeof options.oldFileContent === "string"
-      ? buildFullFileTokenLookup(options.oldFileContent, file.path)
-      : null;
-  if (typeof options.newFileContent === "string") {
-    newTokensByLine = buildFullFileTokenLookup(options.newFileContent, file.path);
-  } else {
-    try {
-      const fileContent = await readFile(resolve(cwd, file.path), "utf-8");
-      newTokensByLine = buildFullFileTokenLookup(fileContent, file.path);
-    } catch {
-      // Deleted or unavailable files use reconstructed tokens below.
-    }
-  }
+  const newContent =
+    typeof options.newFileContent === "string"
+      ? options.newFileContent
+      : await readHighlightSource(resolve(cwd, file.path));
+  if (options.signal?.aborted) return file;
 
-  if (newTokensByLine && oldTokensByLine)
-    return applyTokensToHunks(file, newTokensByLine, oldTokensByLine);
-  const reconstructedTokens = buildReconstructedTokenLookups(file);
+  const oldTokens = await highlightAvailableSource(
+    options.oldFileContent,
+    file.path,
+    options.signal,
+  );
+  if (options.signal?.aborted) return file;
+  const newTokens = await highlightAvailableSource(newContent, file.path, options.signal);
+  if (options.signal?.aborted) return file;
+  if (oldTokens && newTokens) return applyTokensToHunks(file, newTokens, oldTokens);
+  const reconstructed = await buildBudgetedReconstructedTokens(file, options.signal);
+  if (!reconstructed || options.signal?.aborted) return file;
   return applyTokensToHunks(
     file,
-    newTokensByLine ?? reconstructedTokens.newTokensByLine,
-    oldTokensByLine ?? reconstructedTokens.oldTokensByLine,
+    newTokens ?? reconstructed.newTokensByLine,
+    oldTokens ?? reconstructed.oldTokensByLine,
   );
 }
 
+function isDiffHighlightEligible(
+  file: ParsedDiffFile,
+  options: HighlightDiffWithFileContentOptions,
+): boolean {
+  return !options.signal?.aborted && isLanguageSupported(file.path) && !hasOversizedDiffLine(file);
+}
+
+async function highlightAvailableSource(
+  content: string | null | undefined,
+  path: string,
+  signal?: AbortSignal,
+): Promise<Map<number, HighlightToken[]> | null> {
+  // Preserve the existing hunk-context fallback for oversized individual lines.
+  if (typeof content !== "string" || exceedsSourceBudget(content) || hasOversizedLine(content))
+    return null;
+  return buildFullFileTokenLookup(content, path, signal);
+}
+
 function applyTokensToHunks(
   file: ParsedDiffFile,
   newTokensByLine: Map<number, HighlightToken[]>,
@@ -406,20 +481,24 @@ export async function parseAndHighlightDiff(
 ): Promise<ParsedDiffFile[]> {
   const files = parseDiff(diffText);
 
-  const highlightedFiles = await Promise.all(
-    files.map(async (file) => {
-      const [oldFileContent, newFileContent] = await Promise.all([
-        options.getOldFileContent?.(file),
-        options.getNewFileContent?.(file),
-      ]);
-
-      return highlightDiffWithFileContent(file, cwd, {
+  const highlightedFiles: ParsedDiffFile[] = [];
+  for (const file of files) {
+    if (options.signal?.aborted) {
+      highlightedFiles.push(file);
+      continue;
+    }
+    const [oldFileContent, newFileContent] = await Promise.all([
+      options.getOldFileContent?.(file),
+      options.getNewFileContent?.(file),
+    ]);
+    highlightedFiles.push(
+      await highlightDiffWithFileContent(file, cwd, {
         oldFileContent: oldFileContent ?? undefined,
         newFileContent: newFileContent ?? undefined,
-      });
-    }),
-  );
-
+        signal: options.signal,
+      }),
+    );
+  }
   return highlightedFiles;
 }
 
diff --git a/packages/server/src/server/watcher-liveness-canary.test.ts b/packages/server/src/server/watcher-liveness-canary.test.ts
index 4da1481408..7e719da9f0 100644
--- a/packages/server/src/server/watcher-liveness-canary.test.ts
+++ b/packages/server/src/server/watcher-liveness-canary.test.ts
@@ -1,4 +1,5 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import { watchFile, unwatchFile } from "node:fs";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, expect, test } from "vitest";
@@ -31,3 +32,39 @@ test("rejects when the watcher never reports the canary", async () => {
 
   await expect(canary.verify()).rejects.toThrow("did not report its liveness canary");
 });
+
+test("verifies a watcher that starts delivering after the initial canary write", async () => {
+  const watchRoot = await mkdtemp(join(tmpdir(), "paseo-watcher-canary-"));
+  cleanupPaths.push(watchRoot);
+  const canary = createWatcherLivenessCanary(watchRoot);
+  const verification = canary.verify();
+  const verified = expect(verification).resolves.toBeUndefined();
+
+  // The initial write happens before the observer starts delivering changes.
+  await expect.poll(() => readFile(canary.path, "utf8")).toBe("paseo watcher liveness canary\n");
+  watchFile(canary.path, { interval: 10 }, () => {
+    canary.filterEvents([{ path: canary.path, type: "update" }]);
+  });
+  try {
+    await verified;
+    await expect(readFile(canary.path)).rejects.toMatchObject({ code: "ENOENT" });
+  } finally {
+    unwatchFile(canary.path);
+  }
+});
+
+test("aborting verification stops pulses before removing the canary", async () => {
+  const watchRoot = await mkdtemp(join(tmpdir(), "paseo-watcher-canary-"));
+  cleanupPaths.push(watchRoot);
+  const canary = createWatcherLivenessCanary(watchRoot);
+  const controller = new AbortController();
+  const verification = canary.verify(controller.signal);
+  const cancelled = expect(verification).rejects.toThrow("stop watching");
+  await expect.poll(() => readFile(canary.path, "utf8")).toBe("paseo watcher liveness canary\n");
+  const initialWrite = (await stat(canary.path)).mtimeMs;
+  await expect.poll(async () => (await stat(canary.path)).mtimeMs).toBeGreaterThan(initialWrite);
+
+  controller.abort(new Error("stop watching"));
+  await cancelled;
+  await expect(readFile(canary.path)).rejects.toMatchObject({ code: "ENOENT" });
+});
diff --git a/packages/server/src/server/watcher-liveness-canary.ts b/packages/server/src/server/watcher-liveness-canary.ts
index a366f0229a..2fc5c5dbdf 100644
--- a/packages/server/src/server/watcher-liveness-canary.ts
+++ b/packages/server/src/server/watcher-liveness-canary.ts
@@ -1,9 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { setInterval } from "node:timers/promises";
 import type { FileChange } from "./file-observer/index.js";
 
 export const WATCHER_LIVENESS_CANARY_TIMEOUT_MS = 10_000;
+const CANARY_CONTENTS = "paseo watcher liveness canary\n";
 
 export interface WatcherLivenessCanary {
   readonly path: string;
@@ -32,7 +34,11 @@ export function createWatcherLivenessCanary(
       return filtered;
     },
     async verify(signal) {
-      await writeFile(canaryPath, "paseo watcher liveness canary\n", { flag: "wx" });
+      await writeFile(canaryPath, CANARY_CONTENTS, { flag: "wx" });
+      // Native registration can return before macOS starts its FSEvents stream.
+      // Keep probing until an event round-trips instead of relying on the first write.
+      const pulses = new AbortController();
+      const pulsing = pulseCanary(canaryPath, pulses.signal);
       let timeout: NodeJS.Timeout | null = null;
       let removeAbortListener = () => {};
       try {
@@ -55,12 +61,24 @@ export function createWatcherLivenessCanary(
           signal.addEventListener("abort", rejectForAbort, { once: true });
           removeAbortListener = () => signal.removeEventListener("abort", rejectForAbort);
         });
-        await Promise.race([reported, timeoutPromise, abortPromise]);
+        await Promise.race([reported, timeoutPromise, abortPromise, pulsing]);
       } finally {
         if (timeout) clearTimeout(timeout);
         removeAbortListener();
+        pulses.abort();
+        await Promise.allSettled([pulsing]);
         await rm(canaryPath, { force: true });
       }
     },
   };
 }
+
+async function pulseCanary(path: string, signal: AbortSignal): Promise<void> {
+  try {
+    for await (const _ of setInterval(100, undefined, { signal })) {
+      await writeFile(path, CANARY_CONTENTS);
+    }
+  } catch (error) {
+    if (!signal.aborted) throw error;
+  }
+}
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.file-transfer.e2e.test.ts b/packages/server/src/server/websocket-server.file-transfer.e2e.test.ts
index 5131456ee9..abce664ffd 100644
--- a/packages/server/src/server/websocket-server.file-transfer.e2e.test.ts
+++ b/packages/server/src/server/websocket-server.file-transfer.e2e.test.ts
@@ -90,7 +90,11 @@ test(
   TEST_TIMEOUT_MS,
 );
 
-async function connectSocket(port: number, clientId: string): Promise<WebSocket> {
+async function connectSocket(
+  port: number,
+  clientId: string,
+  capabilities?: Record<string, unknown>,
+): Promise<WebSocket> {
   const socket = new WebSocket(`ws://127.0.0.1:${port}/ws`);
   await new Promise<void>((resolve, reject) => {
     socket.once("open", resolve);
@@ -98,7 +102,7 @@ async function connectSocket(port: number, clientId: string): Promise<WebSocket>
   });
   await sendAndWait(
     socket,
-    { type: "hello", clientId, clientType: "browser", protocolVersion: 1 },
+    { type: "hello", clientId, clientType: "browser", protocolVersion: 1, capabilities },
     (message) =>
       message.type === "session" &&
       message.message.type === "status" &&
@@ -166,3 +170,97 @@ function sendAndWait(
   socket.send(JSON.stringify(message));
   return response;
 }
+
+test("an awaited timeline framing overflow closes the actual daemon socket", async () => {
+  const { createHostClient } = await import("@getpaseo/client/node");
+  const { createPaseoApi } = await import("@getpaseo/client");
+  const { default: pino } = await import("pino");
+  const { Writable } = await import("node:stream");
+  const messages: string[] = [];
+  const logger = pino(
+    { level: "warn" },
+    new Writable({
+      write(chunk, _encoding, done) {
+        messages.push(JSON.parse(chunk.toString()).msg);
+        done();
+      },
+    }),
+  );
+  daemon = await createTestPaseoDaemon({ logger });
+  const client = createHostClient(`127.0.0.1:${daemon.port}`, {
+    clientId: "framing-seed",
+    reconnect: { enabled: false },
+  });
+  await client.connect();
+  const api = createPaseoApi(client);
+  try {
+    const workspace = await api.workspaces.create({
+      source: { kind: "directory", path: daemon.staticDir },
+    });
+    const agents = [];
+    const text = "x".repeat(240 * 1024);
+    for (const [index, rows] of [350, 90].entries()) {
+      const agent = await workspace.agents.create({
+        config: { provider: "claude/claude-test", modeId: "full-access" },
+        title: `Framing overflow ${index}`,
+      });
+      agents.push(agent.id);
+      for (let row = 0; row < rows; row++)
+        await daemon.daemon.agentManager.appendTimelineItem(agent.id, {
+          type: "user_message",
+          text,
+        });
+    }
+    const source = await connectSocket(daemon.port, "framing-overflow", {
+      binary_chunking_v1: true,
+    });
+    sockets.push(source);
+    const closed = new Promise<void>((resolve) => source.once("close", () => resolve()));
+    const firstChunk = new Promise<void>((resolve) => {
+      const listener = (data: RawData, binary: boolean) => {
+        if (!binary || (data as Buffer)[0] !== 0x31) return;
+        source.off("message", listener);
+        source.pause();
+        resolve();
+      };
+      source.on("message", listener);
+    });
+    const fetch = (agentId: string, requestId: string) =>
+      source.send(
+        JSON.stringify({
+          type: "session",
+          message: {
+            type: "fetch_agent_timeline_request",
+            requestId,
+            agentId,
+            direction: "tail",
+            projection: "canonical",
+            limit: 0,
+          },
+        }),
+      );
+    fetch(agents[0]!, "first");
+    await firstChunk;
+    fetch(agents[1]!, "overflow");
+    await expect
+      .poll(() => messages.includes("Closing physical WebSocket after outbound framing failure"), {
+        timeout: 15000,
+      })
+      .toBe(true);
+    expect(messages).not.toContain("Closing physical WebSocket at outbound high-water mark");
+    source.resume();
+    await closed;
+  } finally {
+    await api.dispose();
+    await client.close();
+  }
+}, 60000);
+
+test("malformed chunk metadata closes the daemon socket with a protocol error", async () => {
+  daemon = await createTestPaseoDaemon();
+  const source = await connectSocket(daemon.port, "invalid-framing", { binary_chunking_v1: true });
+  sockets.push(source);
+  const closed = new Promise<number>((resolve) => source.once("close", (code) => resolve(code)));
+  source.send(new Uint8Array([0x31, 2, 0, 3, 65]));
+  expect(await closed).toBe(1002);
+});
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..c99d5ac9cc 100644
--- a/packages/server/src/server/websocket-server.relay-reconnect.test.ts
+++ b/packages/server/src/server/websocket-server.relay-reconnect.test.ts
@@ -1157,6 +1157,7 @@ describe("relay external socket reconnect behavior", () => {
     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 53172b2835..1bbc171f4a 100644
--- a/packages/server/src/server/websocket-server.ts
+++ b/packages/server/src/server/websocket-server.ts
@@ -1,3 +1,7 @@
+import {
+  ChunkedTransport,
+  ChunkedTransportProtocolError,
+} from "@getpaseo/protocol/chunked-transport";
 import { type WorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
 import {
   createAgentMessageDelivery,
@@ -12,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";
@@ -57,6 +65,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";
@@ -124,8 +133,8 @@ import {
   MAX_PHYSICAL_SOCKET_BUFFERED_BYTES,
   outboundFrameByteLength,
   physicalSocketHasCapacity,
-  sendBoundedPhysicalFrame,
   sendBoundedPhysicalFrameAndWait,
+  sendBoundedPhysicalFrame,
 } from "./websocket/physical-socket.js";
 
 const WS_CLOSE_DAEMON_AUTH_FAILED = 4401;
@@ -354,11 +363,12 @@ function createNoopWorkspaceRegistry(): WorkspaceRegistry {
   return {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => [],
+    listAll: async () => [],
+    listActive: async () => [],
     get: async () => null,
     update: async () => null,
     upsert: async () => {},
-    archive: async () => {},
+    archive: async () => false,
     remove: async () => {},
   };
 }
@@ -440,6 +450,7 @@ function bufferFromWsData(data: Buffer | ArrayBuffer | Buffer[] | string): Buffe
 }
 
 export interface WebSocketLike {
+  maxFrameBytes?: number;
   readyState: number;
   bufferedAmount?: number;
   send: (
@@ -563,6 +574,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;
@@ -598,6 +610,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!:
@@ -750,12 +765,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({
@@ -1273,6 +1294,67 @@ export class VoiceAssistantWebSocketServer {
     return { sockets: writableSockets, payload, bytes: outboundFrameByteLength(payload) };
   }
 
+  private sendHelloResponse(ws: WebSocketLike, session: Session, hello: WSHelloMessage): void {
+    // The peer learns our support from this ordinary response before receiving chunks.
+    this.sendToClient(ws, this.createServerInfoMessage(session));
+    this.chunkedSocket(ws).enabled = hello.capabilities?.[CLIENT_CAPS.binaryChunkingV1] === true;
+  }
+
+  private readonly chunkedSockets = new WeakMap<WebSocketLike, ChunkedTransport>();
+
+  private chunkedSocket(ws: WebSocketLike): ChunkedTransport {
+    let transport = this.chunkedSockets.get(ws);
+    if (!transport) {
+      transport = new ChunkedTransport({
+        frameBytes: ws.maxFrameBytes ?? 32 * 1024 * 1024,
+        onFailure: (err) =>
+          this.closePhysicalSocket({
+            ws,
+            logMessage: "Closing physical WebSocket after outbound framing failure",
+            logFields: { err },
+          }),
+        send: (frame, waitForDrain) => {
+          const params = {
+            socket: ws,
+            frame,
+            onHighWater: () => this.closeAtOutboundHighWater(ws),
+          };
+          if (waitForDrain)
+            return sendBoundedPhysicalFrameAndWait(params).then((sent) => {
+              if (!sent) throw new Error("Source is closed");
+              return undefined;
+            });
+          if (!sendBoundedPhysicalFrame(params)) throw new Error("Source is closed");
+        },
+        deliver: (frame) =>
+          this.handleRawMessage(ws, typeof frame === "string" ? frame : Buffer.from(frame)),
+      });
+      this.chunkedSockets.set(ws, transport);
+    }
+    return transport;
+  }
+
+  private socketBufferedAmount(ws: WebSocketLike): number | null {
+    const queued = this.chunkedSockets.get(ws)?.queuedByteLength ?? 0;
+    if (typeof ws.bufferedAmount === "number") return ws.bufferedAmount + queued;
+    return queued > 0 ? queued : null;
+  }
+
+  private sendSocketFrame(
+    ws: WebSocketLike,
+    frame: string | Uint8Array,
+    bytes: number,
+    waitForDrain = false,
+  ): Promise<void> {
+    const transport = this.chunkedSocket(ws);
+    const admittedBytes = transport.isWriting
+      ? bytes
+      : Math.min(bytes, ws.maxFrameBytes ?? 32 * 1024 * 1024);
+    if (!this.ensureOutboundCapacity(ws, admittedBytes))
+      return Promise.reject(new Error("Source is closed"));
+    return transport.send(frame, { waitForDrain, byteLength: bytes });
+  }
+
   private async sendMessageToClientAndWait(
     ws: WebSocketLike,
     message: WSOutboundMessage,
@@ -1280,13 +1362,7 @@ export class VoiceAssistantWebSocketServer {
     const prepared = this.prepareJsonDelivery([ws], message, true);
     if (!prepared) throw new Error("Source message delivery unavailable");
     try {
-      const sent = await sendBoundedPhysicalFrameAndWait({
-        socket: ws,
-        frame: prepared.payload,
-        frameBytes: prepared.bytes,
-        onHighWater: () => this.closeAtOutboundHighWater(ws),
-      });
-      if (!sent) throw new Error("Source is closed");
+      await this.sendSocketFrame(ws, prepared.payload, prepared.bytes, true);
       this.runtimeMetrics.recordOutboundMessage(message, ws.bufferedAmount);
     } catch (err) {
       this.logger.warn({ err }, "ws_send_failed");
@@ -1313,14 +1389,7 @@ export class VoiceAssistantWebSocketServer {
       return;
     }
     try {
-      const sent = await sendBoundedPhysicalFrameAndWait({
-        socket: ws,
-        frame,
-        onHighWater: () => this.closeAtOutboundHighWater(ws),
-      });
-      if (!sent) {
-        throw new Error("Physical WebSocket is not open");
-      }
+      await this.sendSocketFrame(ws, frame, frame.byteLength, true);
       this.runtimeMetrics.recordOutboundBinaryFrame(ws.bufferedAmount);
     } catch (err) {
       this.logger.warn({ err }, "ws_send_failed");
@@ -1335,13 +1404,9 @@ export class VoiceAssistantWebSocketServer {
     recordSent: () => void,
   ): void {
     try {
-      const sent = sendBoundedPhysicalFrame({
-        socket: ws,
-        frame,
-        frameBytes,
-        onHighWater: () => this.closeAtOutboundHighWater(ws),
+      void this.sendSocketFrame(ws, frame, frameBytes).then(recordSent, (err) => {
+        this.logger.warn({ err }, "ws_send_failed");
       });
-      if (sent) recordSent();
     } catch (err) {
       this.logger.warn({ err }, "ws_send_failed");
     }
@@ -1349,7 +1414,13 @@ export class VoiceAssistantWebSocketServer {
 
   private ensureOutboundCapacity(ws: WebSocketLike, frameBytes: number): boolean {
     if (ws.readyState !== 1) return false;
-    if (physicalSocketHasCapacity(ws, frameBytes)) return true;
+    if (
+      physicalSocketHasCapacity(
+        { bufferedAmount: this.socketBufferedAmount(ws) ?? undefined },
+        frameBytes,
+      )
+    )
+      return true;
 
     this.closeAtOutboundHighWater(ws);
     return false;
@@ -1522,16 +1593,15 @@ export class VoiceAssistantWebSocketServer {
         if (!connection) {
           return null;
         }
-        if (source) return (source as WebSocketLike).bufferedAmount ?? null;
+        if (source) return this.socketBufferedAmount(source as WebSocketLike);
         // Relay-attached sockets are a WebSocketLike that doesn't expose
         // bufferedAmount. Return null when no socket gives a signal so the
         // terminal fallback can't mistake "no signal" for "client keeping up";
         // a direct ws reports its real buffered bytes (0 when drained).
         let maxBuffered: number | null = null;
         for (const socket of connection.sockets) {
-          if (typeof socket.bufferedAmount === "number") {
-            maxBuffered = Math.max(maxBuffered ?? 0, socket.bufferedAmount);
-          }
+          const buffered = this.socketBufferedAmount(socket);
+          if (buffered !== null) maxBuffered = Math.max(maxBuffered ?? 0, buffered);
         }
         return maxBuffered;
       },
@@ -1568,8 +1638,9 @@ export class VoiceAssistantWebSocketServer {
         let total = 0;
         for (const socket of this.sessions.keys()) {
           if (socket instanceof VirtualHostSocket) continue;
-          if (typeof socket.bufferedAmount !== "number") return null;
-          total += socket.bufferedAmount;
+          const buffered = this.socketBufferedAmount(socket);
+          if (buffered === null) return null;
+          total += buffered;
         }
         return total;
       },
@@ -1605,6 +1676,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,
@@ -1629,6 +1701,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,
@@ -1770,7 +1843,7 @@ export class VoiceAssistantWebSocketServer {
       this.externalSessionsByKey.set(sessionKey, connection);
     }
     pending.identity.sessionId = connection.session.getSessionId();
-    this.sendToClient(ws, this.createServerInfoMessage(connection.session));
+    this.sendHelloResponse(ws, connection.session, message);
     connection.connectionLogger.info(
       {
         ...toConnectionLogFields(pending.identity),
@@ -1906,7 +1979,7 @@ export class VoiceAssistantWebSocketServer {
     existing.sockets.add(ws);
     this.sessions.set(ws, existing);
     pending.identity.sessionId = existing.session.getSessionId();
-    this.sendToClient(ws, this.createServerInfoMessage(existing.session));
+    this.sendHelloResponse(ws, existing.session, message);
     pending.connectionLogger.info(
       {
         ...toConnectionLogFields(pending.identity),
@@ -1949,13 +2022,18 @@ export class VoiceAssistantWebSocketServer {
         hostMultiplexing: true,
         // COMPAT(relayProtectedSecurity): added in v0.13.0, remove gate after 2027-04-21.
         relayProtectedSecurity: true,
+        usageSetting: true,
         usageSources: true,
         ownedSubscriptions: 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.
@@ -2009,16 +2087,21 @@ 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.
         idleRuntimeCleanupSetting: true,
+        resumeOnStartupSetting: true,
         // COMPAT(terminalRestoreModes): added in v0.1.81, remove gate after 2026-11-23.
         "terminal-restore-modes": true,
         // COMPAT(terminalInputModeReplay): added in v0.2.6, remove gate after 2027-02-02.
         "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,
@@ -2036,10 +2119,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.
@@ -2054,14 +2141,21 @@ export class VoiceAssistantWebSocketServer {
         daemonDiagnostics: true,
         // COMPAT(daemonSelfUpdate): added in v0.1.93, remove gate after 2026-12-13.
         daemonSelfUpdate: this.daemonRuntimeConfig?.desktopManaged !== true,
+        // COMPAT(terminalsSurviveRestart): added in v0.12.0, remove gate after 2027-04-21.
+        terminalsSurviveRestart: true,
         // COMPAT(agentForkContext): added in v0.1.102, remove gate after 2026-12-28.
         agentForkContext: true,
         // COMPAT(agentForkContextCursor): added in v0.1.108, remove gate after 2027-01-14.
         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,
         // COMPAT(providerSubagentNesting): added in v0.7, remove gate after 2027-03-04.
         providerSubagentNesting: true,
         // COMPAT(workspacePinning): added in v0.1.107, remove gate after 2027-01-12.
@@ -2160,10 +2254,16 @@ export class VoiceAssistantWebSocketServer {
   private bindSocketHandlers(ws: WebSocketLike): void {
     ws.on("message", (...args: unknown[]) => {
       const data = args[0] as Buffer | ArrayBuffer | Buffer[] | string;
-      this.handleRawMessage(ws, data);
+      try {
+        this.chunkedSocket(ws).receive(typeof data === "string" ? data : bufferFromWsData(data));
+      } catch (error) {
+        if (!(error instanceof ChunkedTransportProtocolError)) throw error;
+        ws.close(1002, "Invalid chunked transport");
+      }
     });
 
     ws.on("close", async (...args: unknown[]) => {
+      this.chunkedSockets.get(ws)?.close();
       const code = args[0];
       const reason = args[1];
       await this.detachSocket(ws, {
@@ -2563,7 +2663,7 @@ export class VoiceAssistantWebSocketServer {
         identity: JSON.stringify([connection.principalId, connection.clientId]),
         permissions: () => connection.session.getPermissions(),
         routed: () => connection.session.isRouted(),
-        bufferedAmount: () => ws.bufferedAmount ?? null,
+        bufferedAmount: () => this.socketBufferedAmount(ws),
         delivery: connection.session.delivery,
         admit: (socket, permissions) =>
           this.attachSocket(socket, undefined, undefined, false, {
diff --git a/packages/server/src/server/websocket/encrypted-relay-socket.test.ts b/packages/server/src/server/websocket/encrypted-relay-socket.test.ts
index f2a880f15f..3e17f0cbb4 100644
--- a/packages/server/src/server/websocket/encrypted-relay-socket.test.ts
+++ b/packages/server/src/server/websocket/encrypted-relay-socket.test.ts
@@ -140,3 +140,74 @@ test("encrypted sockets do not double-count bytes already buffered by the transp
 
   expect(socket.bufferedAmount).toBe(payload.byteLength + 40);
 });
+
+test("50 MiB logical text and routed binary cross encrypted relay frames in both directions", async () => {
+  const { ChunkedTransport } = await import("@getpaseo/protocol/chunked-transport");
+  const { openClientSecureChannel, openDaemonSecureChannel } = await import("@getpaseo/relay/e2ee");
+  const { generateKeyPair, exportPublicKey, maxSecuredPlaintextByteLength } =
+    await import("@getpaseo/relay");
+  const { encodeHostRouteFrame, decodeHostRouteFrame } =
+    await import("@getpaseo/protocol/binary-frames/index");
+  type Transport = import("@getpaseo/relay/e2ee").Transport;
+  const limit = 32 * 1024 * 1024;
+  const wireSizes: number[] = [];
+  const endpoint = (): Transport => ({
+    send: () => {},
+    close: () => {},
+    onmessage: null,
+    onclose: null,
+    onerror: null,
+  });
+  const left = endpoint();
+  const right = endpoint();
+  const wire = (destination: Transport) => (data: string | ArrayBuffer) => {
+    const size = typeof data === "string" ? Buffer.byteLength(data) : data.byteLength;
+    expect(size).toBeLessThanOrEqual(limit);
+    wireSizes.push(size);
+    queueMicrotask(() => destination.onmessage?.({ data, isBinary: typeof data !== "string" }));
+  };
+  left.send = wire(right);
+  right.send = wire(left);
+  const key = generateKeyPair();
+  const delivered: (string | Uint8Array)[][] = [[], []];
+  let receivers: InstanceType<typeof ChunkedTransport>[] = [];
+  const incoming = (index: number) => (data: string | ArrayBuffer) =>
+    receivers[index]!.receive(typeof data === "string" ? data : new Uint8Array(data));
+  const daemonPromise = openDaemonSecureChannel(right, {
+    daemonKeyPair: key,
+    events: { onmessage: incoming(1) },
+  });
+  const client = await openClientSecureChannel(left, {
+    daemonPublicKeyB64: exportPublicKey(key.publicKey),
+    events: { onmessage: incoming(0) },
+  });
+  const daemon = await daemonPromise;
+  receivers = [client, daemon].map(
+    (channel, index) =>
+      new ChunkedTransport({
+        frameBytes: maxSecuredPlaintextByteLength(limit),
+        send: (frame) => channel.send(typeof frame === "string" ? frame : frame.slice().buffer),
+        deliver: (frame) => {
+          delivered[index]!.push(frame);
+        },
+      }),
+  );
+  for (const receiver of receivers) receiver.enabled = true;
+  const text = "x".repeat(50 * 1024 * 1024);
+  wireSizes.length = 0;
+  await receivers[1]!.send(text);
+  await new Promise<void>((resolve) => setImmediate(resolve));
+  expect(delivered[0]).toEqual([text]);
+  expect(wireSizes.length).toBeGreaterThan(1);
+  const routed = encodeHostRouteFrame("route", new Uint8Array(50 * 1024 * 1024).fill(7));
+  await receivers[0]!.send(routed);
+  await new Promise<void>((resolve) => setImmediate(resolve));
+  expect(delivered[1]).toHaveLength(1);
+  const received = decodeHostRouteFrame(delivered[1]![0] as Uint8Array)!;
+  expect(received.routeId).toBe("route");
+  expect(
+    Buffer.from(received.payload).equals(Buffer.from(new Uint8Array(50 * 1024 * 1024).fill(7))),
+  ).toBe(true);
+  client.close();
+  daemon.close();
+}, 30_000);
diff --git a/packages/server/src/server/websocket/encrypted-relay-socket.ts b/packages/server/src/server/websocket/encrypted-relay-socket.ts
index f11162761c..794789718c 100644
--- a/packages/server/src/server/websocket/encrypted-relay-socket.ts
+++ b/packages/server/src/server/websocket/encrypted-relay-socket.ts
@@ -1,3 +1,5 @@
+import { maxSecuredPlaintextByteLength } from "@getpaseo/relay";
+import { MAX_RELAY_WEBSOCKET_MESSAGE_BYTES } from "@getpaseo/protocol/websocket-message-limit";
 import { EventEmitter } from "node:events";
 import { MAX_PHYSICAL_SOCKET_BUFFERED_BYTES } from "./physical-socket.js";
 
@@ -8,6 +10,7 @@ export interface EncryptedRelayChannel {
 }
 
 export interface EncryptedRelaySocket {
+  readonly maxFrameBytes: number;
   readonly readyState: number;
   readonly bufferedAmount: number;
   send: (data: string | Uint8Array | ArrayBuffer) => void | Promise<void>;
@@ -43,6 +46,7 @@ export function createEncryptedRelaySocket(params: {
   });
 
   return {
+    maxFrameBytes: maxSecuredPlaintextByteLength(MAX_RELAY_WEBSOCKET_MESSAGE_BYTES),
     get readyState() {
       return readyState;
     },
diff --git a/packages/server/src/server/websocket/physical-socket.test.ts b/packages/server/src/server/websocket/physical-socket.test.ts
index c81b1410d6..6dce3e151d 100644
--- a/packages/server/src/server/websocket/physical-socket.test.ts
+++ b/packages/server/src/server/websocket/physical-socket.test.ts
@@ -120,3 +120,96 @@ test("the awaitable physical send rejects callback errors", async () => {
     }),
   ).rejects.toThrow("send failed");
 });
+
+test("ordinary frames expose a paused real socket's backlog and terminate at the physical backstop", async () => {
+  const { once } = await import("node:events");
+  const { WebSocket, WebSocketServer } = await import("ws");
+  const { ChunkedTransport } = await import("@getpaseo/protocol/chunked-transport");
+  const server = new WebSocketServer({ host: "127.0.0.1", port: 0 });
+  await once(server, "listening");
+  const connected = once(server, "connection");
+  const address = server.address();
+  if (typeof address === "string" || !address) throw new Error("Missing server address");
+  const client = new WebSocket(`ws://127.0.0.1:${address.port}`);
+  await once(client, "open");
+  const [socket] = (await connected) as [InstanceType<typeof WebSocket>];
+  const tcp = (socket as unknown as { _socket: import("node:net").Socket })._socket;
+  let terminated = false;
+  const transport = new ChunkedTransport({
+    frameBytes: 32 * 1024 * 1024,
+    deliver: () => {},
+    send: (frame, wait) => {
+      const options = {
+        socket,
+        frame,
+        onHighWater: () => {
+          terminated = true;
+          socket.terminate();
+        },
+      };
+      if (wait) return sendBoundedPhysicalFrameAndWait(options).then(() => undefined);
+      sendBoundedPhysicalFrame(options);
+    },
+  });
+  try {
+    client.pause();
+    tcp.cork();
+    const frame = new Uint8Array(256 * 1024);
+    for (let count = 0; count < 200; count++) await transport.send(frame);
+    expect(socket.bufferedAmount).toBeGreaterThan(4 * 1024 * 1024);
+    expect(transport.queuedByteLength).toBe(0);
+    for (let count = 0; count < 100; count++) {
+      if (terminated) break;
+      await transport.send(frame);
+    }
+    expect(terminated).toBe(true);
+  } finally {
+    transport.close();
+    client.terminate();
+    socket.terminate();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+});
+
+test("an awaited framing failure terminates its real socket immediately", async () => {
+  const { once } = await import("node:events");
+  const { WebSocket, WebSocketServer } = await import("ws");
+  const { ChunkedTransport } = await import("@getpaseo/protocol/chunked-transport");
+  const server = new WebSocketServer({ host: "127.0.0.1", port: 0 });
+  await once(server, "listening");
+  const connected = once(server, "connection");
+  const address = server.address();
+  if (typeof address === "string" || !address) throw new Error("Missing server address");
+  const client = new WebSocket(`ws://127.0.0.1:${address.port}`);
+  await once(client, "open");
+  const [socket] = (await connected) as [InstanceType<typeof WebSocket>];
+  const tcp = (socket as unknown as { _socket: import("node:net").Socket })._socket;
+  const transport = new ChunkedTransport({
+    frameBytes: 32 * 1024 * 1024,
+    deliver: () => {},
+    onFailure: () => socket.terminate(),
+    send: (frame) =>
+      sendBoundedPhysicalFrameAndWait({
+        socket,
+        frame,
+        onHighWater: () => socket.terminate(),
+      }).then(() => undefined),
+  });
+  transport.enabled = true;
+  try {
+    client.pause();
+    tcp.cork();
+    const closed = once(socket, "close");
+    const first = transport.send(new Uint8Array(100 * 1024 * 1024), { waitForDrain: true });
+    const overflow = transport.send(new Uint8Array([1]), { waitForDrain: true });
+    const settled = Promise.allSettled([first, overflow]);
+    await closed;
+    expect(socket.readyState).toBe(WebSocket.CLOSED);
+    expect((await settled).map((result) => result.status)).toEqual(["rejected", "rejected"]);
+  } finally {
+    transport.close();
+    client.terminate();
+    socket.terminate();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+});
diff --git a/packages/server/src/server/wire-compat.test.ts b/packages/server/src/server/wire-compat.test.ts
index 00faf1f441..a0de895810 100644
--- a/packages/server/src/server/wire-compat.test.ts
+++ b/packages/server/src/server/wire-compat.test.ts
@@ -114,6 +114,10 @@ class InMemoryAgentManager {
     };
   }
 
+  getAgentBackgroundWorkSummary() {
+    return undefined;
+  }
+
   fetchTimeline(_agentId: string, options?: AgentTimelineFetchOptions) {
     return this.timeline.fetch("agent-1", options);
   }
@@ -128,13 +132,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 {
@@ -156,6 +169,12 @@ class EmptyProjectRegistry {
 }
 
 class EmptyWorkspaceRegistry {
+  listActive() {
+    return [];
+  }
+  listAll() {
+    return [];
+  }
   get() {
     return null;
   }
@@ -753,7 +772,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 a1a901c4d6..ecf4210ece 100644
--- a/packages/server/src/server/workspace-archive-service.test.ts
+++ b/packages/server/src/server/workspace-archive-service.test.ts
@@ -7,7 +7,9 @@ import { afterEach, describe, expect, test, vi } from "vitest";
 
 import type { ForgeService } from "../services/forge-service.js";
 import { createRealpathAwarePathMatcher } from "../utils/path.js";
-import { createWorktree, type WorktreeConfig } from "../utils/worktree.js";
+import { getPaseoWorktreeMetadataPath } from "../utils/worktree-metadata.js";
+import { archiveCommand } from "./worktree/commands.js";
+import { createWorktree, listPaseoWorktrees, type WorktreeConfig } from "../utils/worktree.js";
 import type { ManagedAgent } from "./agent/agent-manager.js";
 import type { AgentStorage, StoredAgentRecord } from "./agent/agent-storage.js";
 import type { WorkspaceGitService } from "./workspace-git-service.js";
@@ -17,6 +19,7 @@ import {
   type ArchiveDependencies,
   type ArchiveResult,
   resolveWorkspaceIdAtPath,
+  WorkspaceArchiveCanceledError,
 } from "./workspace-archive-service.js";
 import { WorkspaceAutomationBlockedError } from "./workspace-automation-gate.js";
 
@@ -190,6 +193,54 @@ function assertArchiveResult(
 }
 
 describe("archiveByScope", () => {
+  test.each(["workspace", "worktree"] as const)(
+    "%s archive preserves a restored external worktree despite its marker",
+    async (kind) => {
+      const { tempDir, repoDir } = createGitRepo();
+      const paseoHome = path.join(tempDir, ".paseo");
+      const recordedPath = path.join(tempDir, "external");
+      execFileSync("git", ["worktree", "add", "-b", "external", recordedPath], {
+        cwd: repoDir,
+        stdio: "pipe",
+      });
+      execFileSync("git", ["worktree", "remove", recordedPath], { cwd: repoDir, stdio: "pipe" });
+      const restored = await createWorktree({
+        cwd: repoDir,
+        paseoHome,
+        worktreeSlug: "external",
+        worktreePath: recordedPath,
+        source: { kind: "restore", branchName: "external", baseRef: "main" },
+      });
+      expect(existsSync(await getPaseoWorktreeMetadataPath(restored.worktreePath))).toBe(true);
+      const workspaceId = "external-workspace";
+      const result = await archiveByScope(
+        createArchiveDeps({
+          paseoHome,
+          activeWorkspaces: [
+            {
+              workspaceId,
+              cwd: restored.worktreePath,
+              kind: "worktree",
+              worktreeRoot: restored.worktreePath,
+              mainRepoRoot: repoDir,
+              isPaseoOwnedWorktree: false,
+            },
+          ],
+        }),
+        {
+          scope:
+            kind === "workspace"
+              ? { kind, workspaceId }
+              : { kind, targetPath: restored.worktreePath },
+          requestId: "archive-external",
+        },
+      );
+      expect(result.removedDirectory).toBe(false);
+      expect(existsSync(restored.worktreePath)).toBe(true);
+      expect(result.archivedWorkspaceIds).toEqual([workspaceId]);
+    },
+  );
+
   test("workspace scope archives the record and removes the directory on last reference", async () => {
     const { tempDir, repoDir } = createGitRepo();
     const paseoHome = path.join(tempDir, ".paseo");
@@ -220,6 +271,120 @@ describe("archiveByScope", () => {
     expect(existsSync(worktree.worktreePath)).toBe(false);
   });
 
+  test("workspace scope archives the record but leaves a plugin-placed directory whose marker is gone", async () => {
+    const { tempDir, repoDir } = createGitRepo();
+    const paseoHome = path.join(tempDir, ".paseo");
+    const worktree = await createWorktree({
+      cwd: repoDir,
+      worktreeSlug: "unproven-workspace",
+      source: { kind: "branch-off", baseBranch: "main", branchName: "unproven-workspace" },
+      paseoHome,
+      worktreePath: path.join(tempDir, "placed-worktree"),
+    });
+    // Remove the ownership marker: no proof remains for this path.
+    rmSync(await getPaseoWorktreeMetadataPath(worktree.worktreePath), { force: true });
+    const workspaceId = "ws-unproven";
+
+    const logs: Array<{ targetPath: string; msg: string }> = [];
+    const dependencies = createArchiveDeps({
+      paseoHome,
+      activeWorkspaces: [{ workspaceId, cwd: worktree.worktreePath, kind: "worktree" }],
+    });
+    dependencies.sessionLogger = pino(
+      { level: "warn" },
+      {
+        write(message) {
+          logs.push(JSON.parse(message));
+        },
+      },
+    );
+    const result = await archiveByScope(dependencies, {
+      scope: { kind: "workspace", workspaceId },
+      requestId: "req-unproven-workspace",
+    });
+
+    assertArchiveResult(result, { archivedWorkspaceIds: [workspaceId], removedDirectory: false });
+    expect(result.directoryLeftBehind?.path).toBe(worktree.worktreePath);
+    expect(result.directoryLeftBehind?.reason).toContain("no ownership proof");
+    expect(existsSync(worktree.worktreePath)).toBe(true);
+    expect(logs).toContainEqual(
+      expect.objectContaining({
+        targetPath: worktree.worktreePath,
+        msg: expect.stringContaining("no ownership proof"),
+      }),
+    );
+  });
+
+  test("archives a plugin-placed worktree by its discovered directory name", async () => {
+    const { tempDir, repoDir } = createGitRepo();
+    const paseoHome = path.join(tempDir, ".paseo");
+    const worktreePath = path.join(tempDir, "sibling-feature");
+    await createWorktree({
+      cwd: repoDir,
+      paseoHome,
+      worktreePath,
+      worktreeSlug: "original-slug",
+      source: { kind: "branch-off", branchName: "feature", baseBranch: "main" },
+    });
+    const dependencies = createArchiveDeps({ paseoHome, activeWorkspaces: [] });
+    const result = await archiveCommand(
+      {
+        ...dependencies,
+        workspaceGitService: {
+          ...dependencies.workspaceGitService,
+          listWorktrees: (cwd) => listPaseoWorktrees({ cwd, paseoHome }),
+        },
+      },
+      {
+        repoRoot: repoDir,
+        worktreeSlug: "sibling-feature",
+        scope: "worktree",
+        requestId: "slug-archive",
+      },
+    );
+    expect(result).toEqual({ ok: true, removedAgents: [] });
+    expect(existsSync(worktreePath)).toBe(false);
+  });
+
+  test("workspace scope deletes a plugin-placed directory on registry proof even with the marker gone", async () => {
+    const { tempDir, repoDir } = createGitRepo();
+    const paseoHome = path.join(tempDir, ".paseo");
+    const worktree = await createWorktree({
+      cwd: repoDir,
+      worktreeSlug: "registry-proven-workspace",
+      source: {
+        kind: "branch-off",
+        baseBranch: "main",
+        branchName: "registry-proven-workspace",
+      },
+      paseoHome,
+      worktreePath: path.join(tempDir, "placed-worktree"),
+    });
+    rmSync(await getPaseoWorktreeMetadataPath(worktree.worktreePath), { force: true });
+    const workspaceId = "ws-registry-proven";
+
+    const result = await archiveByScope(
+      createArchiveDeps({
+        paseoHome,
+        activeWorkspaces: [
+          {
+            workspaceId,
+            cwd: worktree.worktreePath,
+            kind: "worktree",
+            isPaseoOwnedWorktree: true,
+            worktreeRoot: worktree.worktreePath,
+            mainRepoRoot: repoDir,
+          },
+        ],
+      }),
+      { scope: { kind: "workspace", workspaceId }, requestId: "req-registry-proven-workspace" },
+    );
+
+    assertArchiveResult(result, { archivedWorkspaceIds: [workspaceId], removedDirectory: true });
+    expect(result.directoryLeftBehind).toBeUndefined();
+    expect(existsSync(worktree.worktreePath)).toBe(false);
+  });
+
   test("workspace scope runs teardown while keeping a directory referenced by a sibling", async () => {
     const { tempDir, repoDir } = createGitRepo();
     writeFileSync(
@@ -809,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 },
@@ -854,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 e9e58681a1..54d772add1 100644
--- a/packages/server/src/server/workspace-archive-service.ts
+++ b/packages/server/src/server/workspace-archive-service.ts
@@ -67,13 +67,38 @@ 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
+  // disk because no ownership proof held for it. The directory is never
+  // deleted in that case; the path and reason surface here and in the log.
+  directoryLeftBehind?: { path: string; reason: string };
 }
 
 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(
@@ -92,6 +117,15 @@ export async function requireActiveWorkspaceForArchive(
 interface BackingDirectory {
   path: string;
   isPaseoOwnedWorktree: boolean;
+  // True when the directory backs a worktree workspace (or a worktree-scope
+  // archive), so a failed ownership proof means a Paseo worktree directory
+  // is being left behind rather than a user's local checkout being ignored.
+  expectsPaseoOwnership: boolean;
+  // True only when this backing came from a workspace registry record
+  // matched to this path (the record is itself an ownership proof, passed
+  // through to deletePaseoWorktree). Disk-derived backings stay false:
+  // they must prove ownership on disk.
+  registryProven: boolean;
   mainRepoRoot: string | null;
   paseoWorktreesRoot: string | null;
 }
@@ -131,27 +165,42 @@ 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());
   }
 
   let removedDirectory = false;
+  let directoryLeftBehind: ArchiveResult["directoryLeftBehind"];
 
   try {
     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 {
@@ -168,18 +217,22 @@ async function archiveByScopeWithPriority(
     }
 
     if (target.backing !== null) {
-      removedDirectory = await maybeRemoveDirectory(
+      const removal = await maybeRemoveDirectory(
         dependencies,
-        request,
+        { requestId: request.requestId, checkpoint },
         target,
         archivedWorkspaceIds,
       );
+      removedDirectory = removal.removedDirectory;
+      directoryLeftBehind = removal.directoryLeftBehind;
     }
 
     return {
       archivedAgentIds: Array.from(archivedAgents),
+      newlyArchivedAgentIds: Array.from(progress.newlyArchivedAgentIds),
       archivedWorkspaceIds,
       removedDirectory,
+      ...(directoryLeftBehind ? { directoryLeftBehind } : {}),
     };
   } finally {
     if (targetWorkspaceIds.length > 0) {
@@ -189,6 +242,11 @@ async function archiveByScopeWithPriority(
   }
 }
 
+interface ArchiveProgress {
+  newlyArchivedAgentIds: Set<string>;
+  recordArchived: boolean;
+}
+
 async function resolveArchiveTarget(
   dependencies: ArchiveDependencies,
   scope: ArchiveScope,
@@ -226,14 +284,16 @@ async function resolveArchiveTarget(
       }),
     )
   ).filter((workspace): workspace is ActiveWorkspaceRef => workspace !== null);
-  const persistedMainRepoRoot = targetWorkspaces.find(
-    (workspace) => workspace.mainRepoRoot,
-  )?.mainRepoRoot;
+  const recordedId = await dependencies.findWorkspaceIdForCwd(backing.path);
+  const recorded = recordedId ? await dependencies.getWorkspace?.(recordedId) : null;
+  const record =
+    targetWorkspaces.find((workspace) => workspace.kind === "worktree") ??
+    (recorded && matchesBackingDirectory(recorded.worktreeRoot ?? recorded.cwd)
+      ? recorded
+      : null) ??
+    targetWorkspaces[0];
   return {
-    backing: {
-      ...backing,
-      mainRepoRoot: persistedMainRepoRoot ?? backing.mainRepoRoot,
-    },
+    backing: record ? await resolveWorkspaceBackingDirectory(record, dependencies) : backing,
     teardownTargets:
       targetWorkspaces.length > 0
         ? targetWorkspaces.map((workspace) => ({
@@ -271,10 +331,22 @@ async function resolveWorkspaceBackingDirectory(
   workspace: ActiveWorkspaceRef,
   dependencies: Pick<ArchiveDependencies, "paseoHome" | "paseoWorktreesBaseRoot">,
 ): Promise<BackingDirectory> {
+  if (workspace.isPaseoOwnedWorktree === false) {
+    return {
+      path: resolve(workspace.worktreeRoot ?? workspace.cwd),
+      isPaseoOwnedWorktree: false,
+      expectsPaseoOwnership: false,
+      registryProven: false,
+      mainRepoRoot: workspace.mainRepoRoot ?? null,
+      paseoWorktreesRoot: null,
+    };
+  }
   if (workspace.isPaseoOwnedWorktree && workspace.worktreeRoot && workspace.mainRepoRoot) {
     return {
       path: resolve(workspace.worktreeRoot),
       isPaseoOwnedWorktree: true,
+      expectsPaseoOwnership: true,
+      registryProven: true,
       mainRepoRoot: workspace.mainRepoRoot,
       paseoWorktreesRoot: null,
     };
@@ -283,6 +355,8 @@ async function resolveWorkspaceBackingDirectory(
     return {
       path: resolve(workspace.cwd),
       isPaseoOwnedWorktree: false,
+      expectsPaseoOwnership: false,
+      registryProven: false,
       mainRepoRoot: workspace.mainRepoRoot ?? null,
       paseoWorktreesRoot: null,
     };
@@ -309,6 +383,8 @@ async function resolveBackingDirectory(
   return {
     path: resolve(ownership.allowed && ownership.worktreePath ? ownership.worktreePath : cwd),
     isPaseoOwnedWorktree: ownership.allowed,
+    expectsPaseoOwnership: true,
+    registryProven: false,
     mainRepoRoot: ownership.repoRoot ?? null,
     paseoWorktreesRoot: ownership.worktreeRoot ?? null,
   };
@@ -317,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 };
     }),
   );
 
@@ -336,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",
       );
     }
@@ -349,13 +437,31 @@ async function archiveTargetRecords(
 
 async function maybeRemoveDirectory(
   dependencies: ArchiveDependencies,
-  request: Pick<ArchiveByScopeRequest, "requestId">,
+  request: { requestId: string; checkpoint: () => void },
   target: ArchiveTarget,
   archivedWorkspaceIds: string[],
-): Promise<boolean> {
+): Promise<{
+  removedDirectory: boolean;
+  directoryLeftBehind?: { path: string; reason: string };
+}> {
   const backing = target.backing;
   if (!backing?.isPaseoOwnedWorktree) {
-    return false;
+    // Missing ownership proof for a worktree-backed directory: the record
+    // still archives, but the directory is left in place and surfaced.
+    // Never delete an unproven directory.
+    if (backing?.expectsPaseoOwnership) {
+      const reason =
+        "no ownership proof (not under the Paseo worktrees root, no paseo/worktree.json marker, no registry record)";
+      dependencies.sessionLogger?.warn(
+        { targetPath: backing.path, requestId: request.requestId },
+        `Worktree directory left in place during archive: ${reason}`,
+      );
+      return {
+        removedDirectory: false,
+        directoryLeftBehind: { path: backing.path, reason },
+      };
+    }
+    return { removedDirectory: false };
   }
 
   const archivedWorkspaceIdSet = new Set(archivedWorkspaceIds);
@@ -370,6 +476,7 @@ async function maybeRemoveDirectory(
       teardownTargets,
     );
     for (const teardownTarget of uniqueTeardownTargets(allowedTeardownTargets)) {
+      request.checkpoint();
       await runWorktreeTeardownCommands({
         worktreePath: backing.path,
         teardownCwd: teardownTarget.cwd,
@@ -382,7 +489,7 @@ async function maybeRemoveDirectory(
         { err: error, targetPath: backing.path, requestId: request.requestId },
         "Worktree teardown failed during archive; workspace already archived",
       );
-      return false;
+      return { removedDirectory: false };
     }
     throw error;
   }
@@ -396,9 +503,12 @@ async function maybeRemoveDirectory(
       dependencies,
     ))
   ) {
-    return false;
+    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,
@@ -407,16 +517,17 @@ async function maybeRemoveDirectory(
       worktreesRoot: backing.paseoWorktreesRoot ?? undefined,
       paseoHome: dependencies.paseoHome,
       worktreesBaseRoot: dependencies.paseoWorktreesBaseRoot,
+      registryProven: backing.registryProven,
     });
     dependencies.workspaceGitService.invalidateWorktrees();
     dependencies.github.invalidate({ cwd: backing.path });
-    return true;
+    return { removedDirectory: true };
   } catch (error) {
     dependencies.sessionLogger?.warn(
       { err: error, targetPath: backing.path, requestId: request.requestId },
       "Worktree disk removal failed during archive; workspace already archived",
     );
-    return false;
+    return { removedDirectory: false };
   }
 }
 
@@ -464,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
@@ -488,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-create-worktree-source.e2e.test.ts b/packages/server/src/server/workspace-create-worktree-source.e2e.test.ts
index fc9efe1684..cd9ec71d83 100644
--- a/packages/server/src/server/workspace-create-worktree-source.e2e.test.ts
+++ b/packages/server/src/server/workspace-create-worktree-source.e2e.test.ts
@@ -493,6 +493,7 @@ async function createRestorableWorkspace(baseRef: string) {
   commitFile(cwd, "feature.txt", "feature change\n");
   const head = runGit(cwd, "rev-parse", "HEAD");
   await client.checkoutRefresh(cwd);
+  expect(await client.getCheckoutStatus(cwd)).toMatchObject({ isPaseoOwnedWorktree: true });
   const before = await client.getCheckoutDiff(cwd, { mode: "base", baseRef: "main" });
   expect(before.error).toBeNull();
   expect(before.files.map((file) => file.path)).toEqual(["feature.txt"]);
diff --git a/packages/server/src/server/workspace-directory.test.ts b/packages/server/src/server/workspace-directory.test.ts
index be59c3a24a..5e1cb88dc7 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,148 @@ 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"]),
+      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-fetch.test.ts b/packages/server/src/server/workspace-git-fetch.test.ts
index 29a95b64d8..de9e69959e 100644
--- a/packages/server/src/server/workspace-git-fetch.test.ts
+++ b/packages/server/src/server/workspace-git-fetch.test.ts
@@ -1,4 +1,8 @@
 import { describe, expect, test } from "vitest";
+import { createServer } from "node:http";
+import { mkdtemp, readFile, writeFile, rm, chmod } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 import {
   diffWorkspaceGitRefs,
@@ -6,14 +10,21 @@ import {
   fetchWorkspaceGitRemote,
   parseWorkspaceGitRefs,
 } from "./workspace-git-fetch.js";
-import type { RunGitCommand } from "../utils/run-git-command.js";
+import { runGitCommand, type RunGitCommand } from "../utils/run-git-command.js";
 
 describe("workspace Git remote refs", () => {
   test("runs the complete fetch through the supplied Git runner", async () => {
     const commands: string[][] = [];
     let refRead = 0;
-    const runGitCommand: RunGitCommand = async (args) => {
+    const run: RunGitCommand = async (args, options) => {
       commands.push(args);
+      if (args[0] === "fetch") {
+        expect(options.envOverlay).toEqual({
+          GIT_TERMINAL_PROMPT: "0",
+          GIT_ASKPASS: "",
+          GCM_INTERACTIVE: "0",
+        });
+      }
       const stdout =
         args[0] === "for-each-ref"
           ? `refs/remotes/origin/main\0${refRead++ === 0 ? "aaaaaaaa" : "bbbbbbbb"}`
@@ -22,7 +33,7 @@ describe("workspace Git remote refs", () => {
     };
 
     await expect(
-      fetchWorkspaceGitRemote("/repo", { onRefSnapshot() {} }, runGitCommand),
+      fetchWorkspaceGitRemote("/repo", { onRefSnapshot() {} }, run),
     ).resolves.toMatchObject({
       changes: [
         {
@@ -109,3 +120,130 @@ describe("workspace Git remote refs", () => {
     ]);
   });
 });
+
+// Serve a real bare repository over Git's dumb HTTP transport, behind Basic authentication.
+// Both the authentication challenge and successful fetch exercise Git itself.
+async function withAuthenticatedRemote(
+  verify: (fixture: {
+    cwd: string;
+    run: RunGitCommand;
+    root: string;
+    origin: string;
+    expectedOid: string;
+  }) => Promise<void>,
+): Promise<void> {
+  const root = await mkdtemp(join(tmpdir(), "paseo-fetch-auth-"));
+  const cwd = join(root, "checkout");
+  const remote = join(root, "remote.git");
+  const emptyConfig = join(root, "gitconfig");
+  const askpass = join(root, "askpass.sh");
+  const marker = join(root, "prompts");
+  await writeFile(emptyConfig, "");
+  await writeFile(
+    askpass,
+    `#!/bin/sh\nprintf 'prompt\\n' >> '${marker.replaceAll("'", "'\\''")}'\nexit 1\n`,
+  );
+  await chmod(askpass, 0o755);
+  const askpassCommand = askpass;
+  const run: RunGitCommand = (args, options) =>
+    runGitCommand(args, {
+      ...options,
+      env: {
+        ...options.env,
+        GIT_CONFIG_GLOBAL: emptyConfig,
+        GIT_CONFIG_NOSYSTEM: "1",
+        GIT_ASKPASS: askpassCommand,
+        SSH_ASKPASS: askpassCommand,
+      },
+    });
+  const server = createServer(async (request, response) => {
+    if (
+      request.headers.authorization !== `Basic ${Buffer.from("fixture:secret").toString("base64")}`
+    ) {
+      response.writeHead(401, { "WWW-Authenticate": 'Basic realm="git-test"' });
+      response.end();
+      return;
+    }
+    const pathname = new URL(request.url!, "http://localhost").pathname;
+    try {
+      const contents = await readFile(join(root, pathname));
+      response.writeHead(200, { "Content-Type": "application/octet-stream" });
+      response.end(contents);
+    } catch {
+      response.writeHead(404);
+      response.end();
+    }
+  });
+  try {
+    await run(["init", "--initial-branch=main", cwd], { cwd: root });
+    await run(
+      [
+        "-c",
+        "user.name=Fixture",
+        "-c",
+        "user.email=fixture@example.invalid",
+        "commit",
+        "--allow-empty",
+        "-m",
+        "initial",
+      ],
+      { cwd },
+    );
+    await run(["clone", "--bare", cwd, remote], { cwd: root });
+    await run(["update-server-info"], { cwd: remote });
+    await run(["config", "credential.helper", ""], { cwd });
+    await run(["config", "core.askPass", askpassCommand], { cwd });
+    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("Expected TCP server");
+    const origin = `http://127.0.0.1:${address.port}/remote.git`;
+    await run(["remote", "add", "origin", origin], { cwd });
+    const expectedOid = (await run(["rev-parse", "HEAD"], { cwd })).stdout.trim();
+    await verify({ cwd, run, root, origin, expectedOid });
+  } finally {
+    server.closeAllConnections();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  }
+}
+
+test.skipIf(process.platform === "win32")(
+  "background fetches never invoke askpass when credentials are missing",
+  async () => {
+    await withAuthenticatedRemote(async ({ cwd, run, root }) => {
+      for (let attempt = 0; attempt < 2; attempt++) {
+        const result = await fetchWorkspaceGitRemote(cwd, { onRefSnapshot() {} }, run);
+        expect(String(result.error)).toContain("terminal prompts disabled");
+      }
+      await expect(readFile(join(root, "prompts"), "utf8")).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    });
+  },
+);
+
+test.skipIf(process.platform === "win32")(
+  "background fetches still use stored credentials",
+  async () => {
+    await withAuthenticatedRemote(async ({ cwd, run, root, origin, expectedOid }) => {
+      const credentials = join(root, "credentials");
+      await writeFile(credentials, origin.replace("http://", "http://fixture:secret@") + "\n");
+      await run(["config", "credential.helper", `store --file="${credentials}"`], { cwd });
+
+      const result = await fetchWorkspaceGitRemote(cwd, { onRefSnapshot() {} }, run);
+
+      expect(result.error).toBeNull();
+      expect(result.changes).toContainEqual({
+        kind: "added",
+        ref: "origin/main",
+        afterOid: expectedOid,
+      });
+      expect((await run(["rev-parse", "refs/remotes/origin/main"], { cwd })).stdout.trim()).toBe(
+        expectedOid,
+      );
+      await expect(readFile(join(root, "prompts"), "utf8")).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    });
+  },
+);
diff --git a/packages/server/src/server/workspace-git-fetch.ts b/packages/server/src/server/workspace-git-fetch.ts
index 72f5d407da..5673600d23 100644
--- a/packages/server/src/server/workspace-git-fetch.ts
+++ b/packages/server/src/server/workspace-git-fetch.ts
@@ -33,7 +33,9 @@ export async function fetchWorkspaceGitRemote(
   try {
     await run(["fetch", "origin", "--prune"], {
       cwd,
-      envOverlay: { GIT_TERMINAL_PROMPT: "0" },
+      // Terminal prompting and graphical credential prompting have separate controls.
+      // Keep cached credentials available, but never start a login from a passive fetch.
+      envOverlay: { GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "", GCM_INTERACTIVE: "0" },
       timeout: 120_000,
     });
   } catch (caught) {
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 a8a1f11dfb..17e3a4a2af 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,4 @@
+import { flushGitCommandTrace } from "../utils/git-command-trace.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,19 +6,18 @@ 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 {
+  getCheckoutStatus as readCheckoutStatus,
+  type CheckoutSnapshotFacts,
+  type CheckoutStatusGit,
+} from "../utils/checkout-git.js";
 import { CheckoutDiffManager } from "./checkout-diff-manager.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";
 
 function createLogger(): pino.Logger {
-  const logger = {
-    child: () => logger,
-    debug: vi.fn(),
-    warn: vi.fn(),
-  };
-  return logger as unknown as pino.Logger;
+  return pino({ level: "warn" });
 }
 
 function createFacts(cwd: string): CheckoutSnapshotFacts {
@@ -64,6 +64,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");
@@ -232,7 +275,14 @@ test("recursive observation updates tracked state and prunes ignored storms", as
 
   await vi.waitFor(
     () => {
-      expect(activeWatcherCount).toBe(2);
+      expect(
+        activeWatcherCount,
+        JSON.stringify({
+          observer: observer.getDiagnostics(),
+          service: service.getMetrics(),
+          deliveredEvents,
+        }),
+      ).toBe(2);
       expect(workspaceRuntimeStore.get(repoDir)).not.toBeNull();
       expect(service.getMetrics()).toMatchObject({
         workspaceObservationSetupInFlightCount: 0,
@@ -526,3 +576,327 @@ test("a late Git-ignored tree is pruned while tracked changes still notify consu
     rmSync(tempDir, { recursive: true, force: true });
   }
 }, 15_000);
+
+test("Git refresh, command tracing and 10,000 ignored alias events do no synchronous IO", async () => {
+  const { execFile } = await import("node:child_process");
+  const { promisify } = await import("node:util");
+  const { fileURLToPath } = await import("node:url");
+  const repositoryRoot = fileURLToPath(new URL("../../../../", import.meta.url));
+  const source = `
+    import assert from 'node:assert/strict';
+    import { write } from 'node:fs';
+    import { mkdtemp, mkdir, writeFile, symlink, rm } from 'node:fs/promises';
+    import { tmpdir } from 'node:os';
+    import { join } from 'node:path';
+    import { setImmediate as tick } from 'node:timers/promises';
+    import { createHook } from 'node:async_hooks';
+    import pino from 'pino';
+    import { WorkspaceGitServiceImpl } from './packages/server/src/server/workspace-git-service.ts';
+    import { runGitCommand } from './packages/server/src/utils/run-git-command.ts';
+    import { writePaseoWorktreeMetadata } from './packages/server/src/utils/worktree-metadata.ts';
+    const root = await mkdtemp(join(tmpdir(), 'git-async-contract-'));
+    const home = join(root, 'home');
+    const repo = join(root, 'repo');
+    const worktree = join(home, 'worktrees', 'project', 'topic');
+    const alias = join(root, 'alias');
+    const logger = pino({ level: 'trace' }, { write() {} });
+    // Async descriptor writes avoid Windows stderr's synchronous stream API.
+    const marker = (label) => new Promise((resolve, reject) => {
+      write(2, label + '\\n', (error) => error ? reject(error) : resolve());
+    });
+    let callback;
+    let notifications = 0;
+    const service = new WorkspaceGitServiceImpl({ logger, paseoHome: home, deps: {
+      subscribe: async (_root, onChange) => {
+        callback = onChange;
+        return { updateIgnore: async () => {}, unsubscribe: async () => {} };
+      }
+    } });
+    try {
+      await mkdir(repo);
+      await runGitCommand(['init', '-b', 'main'], { cwd: repo });
+      await runGitCommand(['-c', 'user.name=Test', '-c', 'user.email=test@example.com', 'commit', '--allow-empty', '-m', 'base'], { cwd: repo });
+      await mkdir(join(home, 'worktrees', 'project'), { recursive: true });
+      await runGitCommand(['worktree', 'add', '-b', 'topic', worktree], { cwd: repo });
+      await writePaseoWorktreeMetadata(worktree, { baseRefName: 'main' });
+      await writeFile(join(worktree, '.gitignore'), 'ignored/\\n');
+      await mkdir(join(worktree, 'ignored'));
+      await writeFile(join(worktree, 'ignored', 'noise'), 'noise');
+      await symlink(worktree, alias, process.platform === 'win32' ? 'junction' : 'dir');
+      const subscription = await service.requestWorkingTreeWatch(alias, () => { notifications++; });
+      // 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();
+      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;
+        }
+      });
+      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);
+        cpu = threadCpuUsage(startedCpu);
+        // Cap coarse Windows CPU accounting by elapsed time; exclude descheduling.
+        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: ' + 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') }]);
+      assert.equal(notifications, 1);
+      await marker('REFRESH_START');
+      const snapshot = await service.getSnapshot(worktree);
+      assert.equal(snapshot.git.isGit, true);
+      assert.equal(snapshot.git.isPaseoOwnedWorktree, true);
+      await runGitCommand(['status', '--porcelain'], { cwd: alias, logger });
+      await marker('REFRESH_END');
+      subscription.unsubscribe();
+    } finally {
+      await service.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  `;
+  for (const tracing of [false, true]) {
+    const { stdout, stderr } = await promisify(execFile)(
+      process.execPath,
+      [
+        "--expose-gc",
+        "--import",
+        "tsx",
+        ...(tracing ? ["--trace-sync-io"] : []),
+        "--input-type=module",
+        "--eval",
+        source,
+      ],
+      {
+        cwd: repositoryRoot,
+        env: { ...process.env, GIT_IO_TRACE: tracing ? "1" : "" },
+        timeout: 30_000,
+        maxBuffer: 4 * 1024 * 1024,
+      },
+    ).catch((error) => {
+      throw new Error(String(error.stderr).replaceAll(/at .*/g, "[child stack omitted]"));
+    });
+    for (const phase of ["FILTER", "REFRESH"]) {
+      const output = stderr.split(`${phase}_START\n`)[1]?.split(`${phase}_END\n`)[0];
+      expect(output, `${phase}: synchronous filesystem IO`).toBe("");
+    }
+    const measurement = JSON.parse(stdout.trim().split("\n")[0]);
+    console.info("Git filter budget", { tracing, ...measurement });
+    expect(measurement).toMatchObject({ fsCalls: 0 });
+  }
+}, 60_000);
+
+test("Git event identity preserves Windows namespace, case and subtree boundaries", async () => {
+  const { GitObservationPaths } = await import("./git-observation-paths.js");
+  const paths = await GitObservationPaths.create("C:\\paseo-observation-contract");
+  const accept = paths.createEventFilter(["C:\\paseo-observation-contract\\Build"]);
+  expect(paths.relative("\\\\?\\C:\\PASEO-OBSERVATION-CONTRACT\\refs\\heads\\MixedCase")).toBe(
+    "refs/heads/MixedCase",
+  );
+  expect(accept("\\\\?\\C:\\paseo-observation-contract\\build\\noise")).toBe(false);
+  expect(accept("C:\\paseo-observation-contract\\BuildSibling\\file")).toBe(true);
+});
+
+test("concurrent alias requests establish one working-tree subscription", async () => {
+  const { symlink } = await import("node:fs/promises");
+  const root = realpathSync(mkdtempSync(path.join(tmpdir(), "git-observation-concurrent-")));
+  const repo = path.join(root, "repo");
+  const alias = path.join(root, "alias");
+  execFileSync("git", ["init", "-b", "main", repo], { stdio: "pipe" });
+  await symlink(repo, alias, process.platform === "win32" ? "junction" : "dir");
+  let subscriptions = 0;
+  const service = new WorkspaceGitServiceImpl({
+    logger: pino({ enabled: false }),
+    paseoHome: path.join(root, "home"),
+    deps: {
+      subscribe: async () => {
+        subscriptions++;
+        return { updateIgnore: async () => {}, unsubscribe: async () => {} };
+      },
+    },
+  });
+  try {
+    const watches = await Promise.all([
+      service.requestWorkingTreeWatch(repo, () => {}),
+      service.requestWorkingTreeWatch(alias, () => {}),
+    ]);
+    expect(subscriptions).toBe(1);
+    for (const watch of watches) watch.unsubscribe();
+  } finally {
+    await service.dispose();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("Git event identity retains a symlink's literal target before canonicalizing its parent", async () => {
+  const { mkdir, symlink } = await import("node:fs/promises");
+  const { GitObservationPaths } = await import("./git-observation-paths.js");
+  const root = realpathSync(mkdtempSync(path.join(tmpdir(), "git-observation-literal-target-")));
+  const repository = path.join(root, "repository");
+  const parentAlias = path.join(root, "parent-alias");
+  const workspaceAlias = path.join(root, "workspace-alias");
+  const literalTarget = path.join(parentAlias, "repository");
+  const linkType = process.platform === "win32" ? "junction" : "dir";
+  try {
+    await mkdir(repository);
+    await symlink(root, parentAlias, linkType);
+    await symlink(literalTarget, workspaceAlias, linkType);
+    const paths = await GitObservationPaths.create(workspaceAlias);
+    const accept = paths.createEventFilter([path.join(workspaceAlias, "ignored")]);
+    for (const spelling of [workspaceAlias, literalTarget, repository]) {
+      expect(paths.relative(path.join(spelling, "deleted.txt"))).toBe("deleted.txt");
+      expect(accept(path.join(spelling, "ignored", "deleted.txt"))).toBe(false);
+    }
+  } finally {
+    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,
+);
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 f91a96e464..86a49b55ac 100644
--- a/packages/server/src/server/workspace-git-service.observation.test.ts
+++ b/packages/server/src/server/workspace-git-service.observation.test.ts
@@ -244,6 +244,7 @@ function createService(
         filterEvents: (events) => events,
         verify: vi.fn(async () => {}),
       })),
+      workspaceFolderExists: vi.fn(async () => true),
       ...overrides,
     } as never,
   });
@@ -810,64 +811,78 @@ describe("WorkspaceGitService checkout observation", () => {
     service.dispose();
   });
 
-  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);
+  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(1);
+      });
+
+      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(1);
-    });
+      expect(getCheckoutRefDerivedState).not.toHaveBeenCalled();
 
-    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);
 
-    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();
@@ -1189,7 +1204,7 @@ describe("WorkspaceGitService checkout observation", () => {
       ]);
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.waitFor(() => {
-      expect(getCalledCwds(getCheckoutStatus)).toEqual([WORKTREE_A, WORKTREE_B]);
+      expect(getCalledCwds(getCheckoutStatus).sort()).toEqual([WORKTREE_A, WORKTREE_B].sort());
     });
 
     first.unsubscribe();
@@ -1624,6 +1639,12 @@ describe("WorkspaceGitService checkout observation", () => {
     const subscription = service.registerWorkspace({ cwd: REPO_CWD }, vi.fn());
 
     await vi.waitFor(() => {
+      expect(watcher.subscribe).toHaveBeenCalledWith(
+        GIT_DIR,
+        expect.any(Function),
+        expect.any(Object),
+      );
+      expect(getCheckoutStatus).toHaveBeenCalledTimes(1);
       expect(service.getMetrics().workspaceObservationSetupInFlightCount).toBe(0);
       expect(service.getMetrics().workspaceRefreshInFlightCount).toBe(0);
     });
@@ -1642,14 +1663,17 @@ describe("WorkspaceGitService checkout observation", () => {
       [60_000, 6],
     ] as const) {
       await vi.advanceTimersByTimeAsync(elapsedMs);
-      expect(pollCount()).toBe(expectedPolls);
+      await vi.waitFor(() => {
+        expect(pollCount()).toBe(expectedPolls);
+        expect(service.getMetrics().workspaceRefreshInFlightCount).toBe(0);
+      });
     }
 
     isDirty = true;
     await vi.advanceTimersByTimeAsync(60_000);
-    expect(pollCount()).toBe(7);
+    await vi.waitFor(() => expect(pollCount()).toBe(7));
     await vi.advanceTimersByTimeAsync(5_000);
-    expect(pollCount()).toBe(8);
+    await vi.waitFor(() => expect(pollCount()).toBe(8));
 
     subscription.unsubscribe();
     service.dispose();
@@ -1860,8 +1884,10 @@ describe("WorkspaceGitService checkout observation", () => {
       expect(watcher.subscribe).toHaveBeenCalledTimes(1);
     });
     await vi.advanceTimersByTimeAsync(35_000);
-    expect(service.getMetrics().workingTreeWatchSetupInFlightCount).toBe(0);
-    expect(service.getMetrics().workspaceObservationSetupAdmissionActiveCount).toBe(0);
+    await vi.waitFor(() => {
+      expect(service.getMetrics().workingTreeWatchSetupInFlightCount).toBe(0);
+      expect(service.getMetrics().workspaceObservationSetupAdmissionActiveCount).toBe(0);
+    });
     expect(getWatcherSubscribeCallCount(watcher, REPO_CWD)).toBe(1);
 
     openedSubscription.resolve({
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 9a3599740c..1b43026c7d 100644
--- a/packages/server/src/server/workspace-git-service.primitive.test.ts
+++ b/packages/server/src/server/workspace-git-service.primitive.test.ts
@@ -991,7 +991,7 @@ describe("WorkspaceGitServiceImpl primitive refresh entrypoint", () => {
     await vi.advanceTimersByTimeAsync(60_000);
     await flushPromises();
 
-    expect(subscribe).toHaveBeenCalledTimes(2);
+    await vi.waitFor(() => expect(subscribe).toHaveBeenCalledTimes(2));
     expect(getCheckoutStatus).toHaveBeenCalledTimes(1);
 
     subscription.unsubscribe();
@@ -2221,7 +2221,7 @@ describe("WorkspaceGitServiceImpl D2 read methods", () => {
     expect(getCheckoutStatus).toHaveBeenCalledTimes(2);
     expect(getPullRequestStatus).toHaveBeenCalledTimes(2);
 
-    service.dispose();
+    await service.dispose();
   });
 
   test("onWorkspaceStateMayHaveChanged preserves includeForge when a file watcher fires within the debounce window", async () => {
diff --git a/packages/server/src/server/workspace-git-service.test.ts b/packages/server/src/server/workspace-git-service.test.ts
index 4b0b13b7a2..d87e896ead 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,
@@ -324,6 +334,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 +766,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}`),
@@ -796,15 +974,21 @@ describe("WorkspaceGitServiceImpl", () => {
     const service = createService({ getCheckoutStatus, subscribe, runGitCommand });
 
     cwds.forEach((cwd) => service.registerWorkspace({ cwd }, vi.fn()));
-    await vi.waitFor(() => {
-      expect(service.getMetrics()).toMatchObject({
-        workspaceRefreshAdmissionActiveCount: WORKSPACE_GIT_REFRESH_CONCURRENCY,
-        workspaceRefreshAdmissionPendingCount: 1,
-        workspaceObservationSetupAdmissionActiveCount: WORKSPACE_GIT_OBSERVATION_SETUP_CONCURRENCY,
-        workspaceObservationSetupAdmissionPendingCount:
-          cwds.length - WORKSPACE_GIT_OBSERVATION_SETUP_CONCURRENCY,
-      });
-    });
+    await vi.waitFor(
+      () => {
+        expect(service.getMetrics()).toMatchObject({
+          workspaceRefreshAdmissionActiveCount: WORKSPACE_GIT_REFRESH_CONCURRENCY,
+          workspaceRefreshAdmissionPendingCount: 1,
+          workspaceObservationSetupAdmissionActiveCount:
+            WORKSPACE_GIT_OBSERVATION_SETUP_CONCURRENCY,
+          workspaceObservationSetupAdmissionPendingCount:
+            cwds.length - WORKSPACE_GIT_OBSERVATION_SETUP_CONCURRENCY,
+        });
+        // Admission precedes asynchronous path setup; dispose only once watchers are pending.
+        expect(subscribe).toHaveBeenCalledTimes(WORKSPACE_GIT_OBSERVATION_SETUP_CONCURRENCY);
+      },
+      { timeout: 10_000 },
+    );
     const queuedRefreshSettlement = service.getSnapshot(cwds.at(-1)!).then(
       () => ({ status: "fulfilled" as const, error: null }),
       (error: unknown) => ({ status: "rejected" as const, error }),
@@ -1105,12 +1289,23 @@ describe("WorkspaceGitServiceImpl", () => {
       { cwd: join(REPO_CWD, "packages", "server") },
       vi.fn(),
     );
-    await vi.waitFor(() => {
-      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
-    });
+    await vi.waitFor(
+      () => {
+        expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
+        expect(service.getMetrics()).toMatchObject({
+          repositoryWorkspaceLinkCount: 2,
+          workspaceObservationSetupInFlightCount: 0,
+          workspaceRefreshInFlightCount: 0,
+          fetchInFlightCount: 1,
+        });
+      },
+      { timeout: 10_000 },
+    );
 
     releaseFetch.resolve();
-    await flushPromises();
+    await vi.waitFor(() => {
+      expect(service.getMetrics().fetchInFlightCount).toBe(0);
+    });
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.waitFor(() => {
       expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(4);
@@ -1154,10 +1349,14 @@ describe("WorkspaceGitServiceImpl", () => {
     const subscription = service.registerWorkspace({ cwd: REPO_CWD }, listener);
     await vi.waitFor(() => {
       expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(1);
+      expect(service.getMetrics().fetchInFlightCount).toBe(1);
     });
 
     releaseFetch.resolve();
-    await flushPromises();
+    // The refresh debounce starts when the fetch result is applied, not when it is released.
+    await vi.waitFor(() => {
+      expect(service.getMetrics().fetchInFlightCount).toBe(0);
+    });
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.waitFor(() => {
       expect(getCheckoutRefDerivedState).toHaveBeenCalledTimes(1);
@@ -1390,6 +1589,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");
@@ -1397,7 +1831,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();
@@ -1532,3 +1966,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 dcd2ead214..ea91186e9b 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";
@@ -42,18 +42,13 @@ import {
   type ForgeResolver,
 } from "../services/forge-resolver.js";
 import { parseGitRevParsePath } from "../utils/git-rev-parse-path.js";
-import {
-  createRealpathAwarePathMatcher,
-  getRealpathAwareRelativePath,
-  isPathInsideRoot,
-  isRealpathInsideRoot,
-  looksLikeDefiniteWindowsPath,
-} from "../utils/path.js";
+import { isPathInsideRoot, looksLikeDefiniteWindowsPath } from "../utils/path.js";
 import {
   createRunGitCommand,
   runGitCommand,
   type RunGitCommand,
 } from "../utils/run-git-command.js";
+import { GitObservationPaths } from "./git-observation-paths.js";
 import { branchNameFromRef } from "../utils/worktree-metadata.js";
 import { listPaseoWorktrees, type PaseoWorktreeInfo } from "../utils/worktree.js";
 import { READ_ONLY_GIT_ENV } from "./checkout-git-utils.js";
@@ -79,7 +74,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;
@@ -160,10 +155,12 @@ 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;
     aheadBehind: { ahead: number; behind: number } | null;
     upstreamRef: string | null;
     aheadOfOrigin: number | null;
@@ -190,6 +187,7 @@ export interface WorkspaceGitRuntimeSnapshot {
       state: string;
       baseRefName: string;
       headRefName: string;
+      headSha?: string;
       isMerged: boolean;
       isDraft?: boolean;
       mergeable?: PullRequestMergeable;
@@ -299,6 +297,7 @@ export type WorkspaceGitReadOptions =
 export interface WorkspaceGitBranchSuggestionsOptions {
   query?: string;
   limit?: number;
+  refMode?: "exact";
 }
 
 export interface WorkspaceGitStashListOptions {
@@ -325,6 +324,7 @@ export type WorkspaceGitSnapshotOptions =
   | {
       force: true;
       includeForge?: boolean;
+      afterInFlight?: boolean;
       reason: string;
     };
 
@@ -389,6 +389,7 @@ interface WorkspaceGitServiceDependencies {
   runGitCommand: typeof runGitCommand;
   getWorkspaceGitSelfHealPhaseMs: typeof getWorkspaceGitObservationReensurePhaseMs;
   createWatcherLivenessCanary: typeof createWatcherLivenessCanary;
+  workspaceFolderExists: (cwd: string) => Promise<boolean>;
   now: () => Date;
 }
 
@@ -417,6 +418,7 @@ class WorkspaceGitWatcherSubscriptionTimeoutError extends Error {
 }
 
 interface WorkspaceGitTarget {
+  gitDirPaths: GitObservationPaths | null;
   cwd: string;
   listeners: Set<WorkspaceGitListener>;
   workingTreeWatchTarget: WorkingTreeWatchTarget | null;
@@ -439,10 +441,13 @@ interface WorkspaceGitTarget {
   repoGitRoot: string | null;
   observationSetupPromise: Promise<void> | null;
   observationSetupComplete: boolean;
+  folderMissing: boolean;
+  folderRestorePromise: Promise<void> | null;
   closed: boolean;
 }
 
 interface RepoGitTarget {
+  paths: GitObservationPaths;
   repoGitRoot: string;
   cwd: string;
   workspaceKeys: Set<string>;
@@ -470,6 +475,8 @@ interface RepoMetadataWorkspaceRefresh {
 }
 
 interface WorkingTreeWatchTarget {
+  paths: GitObservationPaths;
+  acceptsEvent: (candidate: string) => boolean;
   cwd: string;
   watchPath: string;
   repoRoot: string | null;
@@ -572,10 +579,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,
@@ -601,6 +619,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>();
@@ -661,6 +680,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);
     }
@@ -752,6 +774,9 @@ 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);
   }
@@ -815,11 +840,16 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       cwd: normalizedCwd,
       compare: normalizedOptions,
       ...readOptions,
-      load: () =>
-        this.deps.getCheckoutDiff(normalizedCwd, normalizedOptions, {
-          paseoHome: this.paseoHome,
-          worktreesRoot: this.worktreesRoot,
-        }),
+      load: (signal) =>
+        this.deps.getCheckoutDiff(
+          normalizedCwd,
+          normalizedOptions,
+          {
+            paseoHome: this.paseoHome,
+            worktreesRoot: this.worktreesRoot,
+          },
+          signal,
+        ),
     });
   }
 
@@ -877,7 +907,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),
     );
@@ -968,6 +1004,9 @@ 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, {
       force: false,
       refreshStructure: true,
@@ -1001,9 +1040,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, { queueIfBusy: false });
   }
 
   onWorkspaceStateMayHaveChanged(cwd: string): void {
@@ -1014,6 +1058,10 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       return;
     }
     this.invalidateForge(normalizedCwd);
+    if (target.folderMissing) {
+      void this.resumeWorkspaceIfFolderRestored(target);
+      return;
+    }
     this.scheduleWorkspaceRefresh(target, {
       force: true,
       includeForge: true,
@@ -1056,7 +1104,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;
   }
 
@@ -1165,6 +1218,8 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
 
   private async resolveWorkingTreeWatchTarget(cwd: string): Promise<WorkingTreeWatchTarget> {
     const repoRoot = await this.resolveCheckoutWatchRoot(cwd);
+    const cwdPaths = repoRoot ? await GitObservationPaths.create(cwd) : null;
+    this.assertNotDisposed();
     const targetCwd = repoRoot ?? cwd;
     const existingTarget = this.workingTreeWatchTargets.get(targetCwd);
     if (existingTarget) {
@@ -1179,7 +1234,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       return target;
     }
 
-    const watchPath = repoRoot && createRealpathAwarePathMatcher(repoRoot)(cwd) ? cwd : targetCwd;
+    const watchPath = repoRoot && cwdPaths?.matches(repoRoot) ? cwd : targetCwd;
     const setup = this.createWorkingTreeWatchTarget(targetCwd, watchPath, repoRoot).finally(() => {
       if (this.workingTreeWatchSetups.get(targetCwd) === setup) {
         this.workingTreeWatchSetups.delete(targetCwd);
@@ -1198,6 +1253,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
 
   private createWorkspaceTarget(cwd: string): WorkspaceGitTarget {
     const target: WorkspaceGitTarget = {
+      gitDirPaths: null,
       cwd,
       listeners: new Set(),
       workingTreeWatchTarget: null,
@@ -1220,6 +1276,8 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       repoGitRoot: null,
       observationSetupPromise: null,
       observationSetupComplete: false,
+      folderMissing: false,
+      folderRestorePromise: null,
       closed: false,
     };
 
@@ -1299,6 +1357,11 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     }
     await this.promoteWorkingTreeWatchTarget(workingTreeTarget, facts.worktreeRoot);
     const gitDir = facts.absoluteGitDir;
+    const gitDirPaths = target.gitDirPaths?.matches(gitDir)
+      ? target.gitDirPaths
+      : await GitObservationPaths.create(gitDir);
+    if (!this.isActiveObservedWorkspaceTarget(target)) return;
+    target.gitDirPaths = gitDirPaths;
     const repoGitRoot = facts.gitCommonDir ?? (await this.resolveWorkspaceGitRefsRoot(gitDir));
     if (!this.isActiveObservedWorkspaceTarget(target)) {
       return;
@@ -1331,7 +1394,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     const promise = this.deps
       .getCheckoutSnapshotFacts(target.cwd, context)
       .then((facts) => {
-        target.latestFacts = facts;
+        if (!target.closed) target.latestFacts = facts;
         return facts;
       })
       .finally(() => {
@@ -1346,6 +1409,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
     );
@@ -1359,7 +1423,11 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     const ignoredDirectories = repoRoot
       ? (await this.loadIgnoredDirs(watchPath)).ignored
       : new Set<string>();
+    const paths = await GitObservationPaths.create(watchPath);
+    this.assertNotDisposed();
     const target: WorkingTreeWatchTarget = {
+      paths,
+      acceptsEvent: paths.createEventFilter([join(watchPath, ".git"), ...ignoredDirectories]),
       cwd,
       watchPath,
       repoRoot,
@@ -1492,6 +1560,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 = () => {
@@ -1504,6 +1574,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;
@@ -1523,21 +1600,21 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
           if (watcherErrored) {
             return;
           }
+          events = this.relevantWorkingTreeEvents(target, events);
+          if (events.length === 0) return;
           const discovered = this.noteWorkingTreeDirectories(target, events);
           if (events.some((event) => basename(event.path) === ".gitignore")) {
             void this.refreshWorkingTreeIgnoredDirectories(target);
           } else if (discovered) {
             this.scheduleWorkingTreeIgnoreRefresh(target);
           }
-          if (!this.hasRelevantWorkingTreeEvent(target, events)) {
-            return;
-          }
           this.notifyWorkingTreeChanged(target, "working-tree-watch");
         },
         { ignore },
         markSubscribeSettled,
       );
       if (watcherErrored) {
+        abandoned = true;
         await this.unsubscribeWatcherSubscription(subscription, target.watchPath);
         return false;
       }
@@ -1546,9 +1623,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
@@ -1566,11 +1645,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 },
@@ -1579,6 +1659,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       if (!options?.replaceFallback) {
         this.startWorkingTreeWatchFallback(target, "watcher_setup_failed");
       }
+      this.scheduleWorkingTreeWatchRecovery(target);
       return false;
     }
   }
@@ -1597,11 +1678,110 @@ 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, {
+      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,7 +1819,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
@@ -1708,7 +1890,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);
   }
 
@@ -1716,6 +1904,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;
@@ -1763,20 +1955,15 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     }
     this.removeDeletedKnownDirectories(target, events);
     const gitDir = join(target.watchPath, ".git");
-    // `matchesWatchPath` is realpath-aware because it compares an event-reported
-    // directory against `target.watchPath` itself — a config-time root that can
-    // legitimately differ from the watcher's reported form (e.g. a symlinked
-    // temp dir). It is now gated behind the plain Set lookup below, so it only
-    // runs for a directory this target has never seen before, not on every
-    // event.
-    const matchesWatchPath = createRealpathAwarePathMatcher(target.watchPath);
+    // Event paths have already been mapped into this subscription's established namespace.
+    const matchesWatchPath = target.paths.matches;
     // One new directory is enough: the scheduled Git query inventories every
     // ignored directory that exists by then. Stop before a large event batch
     // multiplies containment checks across all its new directories.
     for (const event of events) {
       const directory = dirname(event.path);
       // Cheap Set lookup first — the steady-state case where the directory is
-      // already known must never reach the realpath-aware matcher below.
+      // already known do not need another root comparison.
       if (target.knownDirectories.has(directory) || matchesWatchPath(directory)) {
         continue;
       }
@@ -1955,28 +2142,22 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     target.pendingKnownDirectories.clear();
   }
 
-  private hasRelevantWorkingTreeEvent(
+  private relevantWorkingTreeEvents(
     target: WorkingTreeWatchTarget,
     events: FileChange[],
-  ): boolean {
-    const gitDir = join(target.watchPath, ".git");
-    const matchesWatchPath = createRealpathAwarePathMatcher(target.watchPath);
-    return events.some((event) => {
-      // Directory metadata changes at the watch root do not change Git state.
-      // FSEvents may emit these when every changed descendant was ignored.
-      if (matchesWatchPath(event.path)) {
-        return false;
+  ): FileChange[] {
+    const relevant: FileChange[] = [];
+    // Watch backends may report the same path more than once in a batch.
+    const acceptedPaths = new Map<string, boolean>();
+    for (const event of events) {
+      let accepted = acceptedPaths.get(event.path);
+      if (accepted === undefined) {
+        accepted = target.acceptsEvent(event.path);
+        acceptedPaths.set(event.path, accepted);
       }
-      if (isRealpathInsideRoot(gitDir, event.path)) {
-        return false;
-      }
-      for (const ignoredDirectory of target.ignoredDirectories) {
-        if (isRealpathInsideRoot(ignoredDirectory, event.path)) {
-          return false;
-        }
-      }
-      return true;
-    });
+      if (accepted) relevant.push({ ...event, path: target.paths.toWatchPath(event.path) });
+    }
+    return relevant;
   }
 
   private refreshWorkingTreeIgnoredDirectories(target: WorkingTreeWatchTarget): Promise<void> {
@@ -2031,6 +2212,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     }
     if (!this.haveSamePaths(target.ignoredDirectories, ignoredDirectories)) {
       target.ignoredDirectories = ignoredDirectories;
+      target.acceptsEvent = target.paths.createEventFilter(this.workingTreeIgnoreList(target));
       this.pruneKnownDirectories(target);
     }
     if (target.fallbackPolling) {
@@ -2152,7 +2334,15 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       return;
     }
 
+    const paths = await GitObservationPaths.create(repoGitRoot);
+    if (!this.isActiveObservedWorkspaceTarget(workspaceTarget)) return;
+    const establishedTarget = this.repoTargets.get(repoGitRoot);
+    if (establishedTarget) {
+      establishedTarget.workspaceKeys.add(workspaceTarget.cwd);
+      return;
+    }
     const repoTarget: RepoGitTarget = {
+      paths,
       repoGitRoot,
       cwd: workspaceTarget.cwd,
       workspaceKeys: new Set([workspaceTarget.cwd]),
@@ -2205,12 +2395,15 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     target: RepoGitTarget,
     options?: { replaceFallback?: boolean },
   ): Promise<boolean> {
+    const paths = target.paths;
     const ignore = getPrunedGitMetadataPaths("common").map((path) =>
       join(target.repoGitRoot, path),
     );
-    const matchesRepoGitRoot = createRealpathAwarePathMatcher(target.repoGitRoot);
+    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 = () => {
@@ -2223,7 +2416,16 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       const subscription = await this.subscribeWithDeadline(
         target.repoGitRoot,
         (error, events) => {
-          const liveEvents = canary.filterEvents(events);
+          if (
+            abandoned ||
+            target.closed ||
+            (activeSubscription && target.subscription !== activeSubscription)
+          ) {
+            return;
+          }
+          const liveEvents = canary.filterEvents(
+            events.map((event) => ({ ...event, path: paths.toWatchPath(event.path) })),
+          );
           if (error) {
             if (watcherErrored) {
               return;
@@ -2249,7 +2451,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
           const relevantEvents = liveEvents.filter(
             (event) =>
               !matchesRepoGitRoot(event.path) &&
-              ignore.every((ignoredPath) => !isRealpathInsideRoot(ignoredPath, event.path)),
+              ignore.every((ignoredPath) => !isPathInsideRoot(ignoredPath, event.path)),
           );
           if (relevantEvents.length > 0) {
             const immediateEvents = target.fetchInFlight
@@ -2279,6 +2481,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;
       }
@@ -2287,9 +2490,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
@@ -2304,6 +2509,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       }
       return true;
     } catch (error) {
+      abandoned = true;
       if (openedSubscription) {
         await this.unsubscribeWatcherSubscription(openedSubscription, target.repoGitRoot);
       }
@@ -2311,7 +2517,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 },
@@ -2320,6 +2526,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       if (!options?.replaceFallback) {
         this.startRepoMetadataFallback(target);
       }
+      this.scheduleRepoMetadataWatchRecovery(target);
       return false;
     }
   }
@@ -2341,7 +2548,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);
   }
 
@@ -2355,6 +2568,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(
@@ -2362,7 +2577,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     events: FileChange[],
   ): Map<string, RepoMetadataWorkspaceRefresh> | null {
     const refreshes = new Map<string, RepoMetadataWorkspaceRefresh>();
-    const matchesRepoGitRoot = createRealpathAwarePathMatcher(target.repoGitRoot);
+    const matchesRepoGitRoot = target.paths.matches;
 
     for (const event of events) {
       if (!this.routeRepoMetadataEvent(target, event, matchesRepoGitRoot, refreshes)) return null;
@@ -2377,10 +2592,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
   ): void {
     const workspaceKeys = new Set<string>();
     for (const event of events) {
-      const commonRelativePath = getRealpathAwareRelativePath(
-        target.repoGitRoot,
-        event.path,
-      )?.replaceAll("\\", "/");
+      const commonRelativePath = target.paths.relative(event.path)?.replaceAll("\\", "/");
       if (commonRelativePath === "config" || commonRelativePath === "info/exclude") {
         for (const workspaceKey of target.workspaceKeys) workspaceKeys.add(workspaceKey);
         continue;
@@ -2390,24 +2602,36 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
         if (
           facts?.isGit &&
           facts.absoluteGitDir &&
-          getRealpathAwareRelativePath(facts.absoluteGitDir, event.path)?.replaceAll("\\", "/") ===
-            "config.worktree"
+          this.workspaceTargets
+            .get(workspaceKey)
+            ?.gitDirPaths?.relative(event.path)
+            ?.replaceAll("\\", "/") === "config.worktree"
         ) {
           workspaceKeys.add(workspaceKey);
         }
       }
     }
+    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 {
-    const relativePath = getRealpathAwareRelativePath(target.repoGitRoot, event.path);
+    const relativePath = target.paths.relative(event.path);
     const effect = classifyGitMetadataPath("common", relativePath ?? "");
     return (
       (effect.kind === "ref" && effect.namespace === "remote") ||
@@ -2419,12 +2643,12 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
   private routeRepoMetadataEvent(
     target: RepoGitTarget,
     event: FileChange,
-    matchesRepoGitRoot: ReturnType<typeof createRealpathAwarePathMatcher>,
+    matchesRepoGitRoot: (candidate: string) => boolean,
     refreshes: Map<string, RepoMetadataWorkspaceRefresh>,
   ): boolean {
     if (this.routePrivateGitDirEvent(target, event, matchesRepoGitRoot, refreshes)) return true;
 
-    const commonRelativePath = getRealpathAwareRelativePath(target.repoGitRoot, event.path);
+    const commonRelativePath = target.paths.relative(event.path);
     const effect = classifyGitMetadataPath("common", commonRelativePath ?? "");
     switch (effect.kind) {
       case "ignore":
@@ -2476,7 +2700,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
   private routePrivateGitDirEvent(
     target: RepoGitTarget,
     event: FileChange,
-    matchesRepoGitRoot: ReturnType<typeof createRealpathAwarePathMatcher>,
+    matchesRepoGitRoot: (candidate: string) => boolean,
     refreshes: Map<string, RepoMetadataWorkspaceRefresh>,
   ): boolean {
     let matched = false;
@@ -2485,8 +2709,10 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       if (!facts?.isGit || !facts.absoluteGitDir || matchesRepoGitRoot(facts.absoluteGitDir)) {
         continue;
       }
-      const relativePath = getRealpathAwareRelativePath(facts.absoluteGitDir, event.path);
-      if (relativePath === null) continue;
+      const relativePath = this.workspaceTargets
+        .get(workspaceKey)
+        ?.gitDirPaths?.relative(event.path);
+      if (relativePath == null) continue;
       matched = true;
       const effect = classifyGitMetadataPath("worktree", relativePath);
       if (effect.kind === "owner") {
@@ -2500,7 +2726,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
 
   private routeMainCheckoutMetadata(
     target: RepoGitTarget,
-    matchesRepoGitRoot: ReturnType<typeof createRealpathAwarePathMatcher>,
+    matchesRepoGitRoot: (candidate: string) => boolean,
     refreshBase: boolean,
     refreshes: Map<string, RepoMetadataWorkspaceRefresh>,
   ): void {
@@ -2769,7 +2995,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
   }
 
   private updateForgePrStatusPollForTarget(target: WorkspaceGitTarget): void {
-    if (target.listeners.size === 0) {
+    if (!this.isActiveObservedWorkspaceTarget(target)) {
       this.stopForgePrStatusPollForTarget(target);
       return;
     }
@@ -3032,6 +3258,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 =
@@ -3052,11 +3281,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,
@@ -3082,7 +3313,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       refreshWorktree: true,
       includeForge: options?.includeForge ?? true,
       reason: options?.reason ?? defaultReason,
-      queueIfBusy: false,
+      queueIfBusy: force && options?.afterInFlight === true,
       movedRemoteRefs: new Set(),
     };
   }
@@ -3174,11 +3405,19 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       try {
         const runRefreshGitCommand = createRunGitCommand(`workspace-refresh:${request.reason}`);
         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;
         }
@@ -3192,6 +3431,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;
       }
@@ -3338,6 +3581,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,
@@ -3345,6 +3589,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) {
@@ -3370,12 +3618,14 @@ 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,
       aheadBehind: checkoutStatus.aheadBehind,
       upstreamRef: checkoutStatus.upstreamRef,
       aheadOfOrigin: checkoutStatus.aheadOfOrigin,
@@ -3487,7 +3737,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;
@@ -3643,21 +3893,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) {
@@ -3702,6 +3956,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;
@@ -3710,12 +3969,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 8977641bab..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();
   }
 }
 
@@ -495,6 +495,10 @@ describe("observed workspace placement", () => {
 
     expect((await observed.placement("workspace-one"))?.archivedAt).toEqual(expect.any(String));
     expect(observed.workspaceBatches).toEqual([["workspace-one"]]);
+    const archived = await observed.placement("workspace-one");
+    await observed.advanceBy(RESCAN_INTERVAL_MS);
+    expect(await observed.placement("workspace-one")).toEqual(archived);
+    expect(observed.workspaceBatches).toEqual([["workspace-one"]]);
     observed.dispose();
   });
 
diff --git a/packages/server/src/server/workspace-reconciliation-service.test.ts b/packages/server/src/server/workspace-reconciliation-service.test.ts
index 52c7d41065..b818804912 100644
--- a/packages/server/src/server/workspace-reconciliation-service.test.ts
+++ b/packages/server/src/server/workspace-reconciliation-service.test.ts
@@ -1,26 +1,45 @@
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { build } from "esbuild";
+import {
+  createTestRegistries,
+  createTestLogger,
+  deferred,
+} from "./test-fixtures/reconciliation-registries.js";
 import type { ProjectCheckoutLitePayload } from "@getpaseo/protocol/messages";
 import type pino from "pino";
-import { afterEach, describe, expect, test } from "vitest";
+import { afterAll, beforeAll, afterEach, describe, expect, test } from "vitest";
 import {
   createPersistedProjectRecord,
   createPersistedWorkspaceRecord,
 } from "./workspace-registry.js";
-import type {
-  PersistedProjectRecord,
-  PersistedWorkspaceRecord,
-  ProjectRegistry,
-  WorkspaceRegistry,
-} from "./workspace-registry.js";
 import {
   type ReconciliationChange,
   WorkspaceReconciliationService,
 } from "./workspace-reconciliation-service.js";
 import { deriveProjectKey } from "./project-key.js";
 
+let probeDirectory: string;
+let probePath: string;
+beforeAll(async () => {
+  probeDirectory = mkdtempSync(path.join(tmpdir(), "reconciliation-probe-"));
+  probePath = path.join(probeDirectory, "reconciliation.mjs");
+  await build({
+    entryPoints: [
+      fileURLToPath(new URL("./test-fixtures/reconciliation-responsiveness.ts", import.meta.url)),
+    ],
+    outfile: probePath,
+    bundle: true,
+    platform: "node",
+    format: "esm",
+  });
+});
+afterAll(() => rmSync(probeDirectory, { recursive: true, force: true }));
+
 function canonicalLocalProjectKey(rootPath: string): string {
   return deriveProjectKey({
     rootPath,
@@ -30,86 +49,6 @@ function canonicalLocalProjectKey(rootPath: string): string {
   });
 }
 
-function createTestRegistries() {
-  const projects = new Map<string, PersistedProjectRecord>();
-  const workspaces = new Map<string, PersistedWorkspaceRecord>();
-
-  const projectRegistry: ProjectRegistry = {
-    initialize: async () => {},
-    existsOnDisk: async () => true,
-    list: async () => Array.from(projects.values()),
-    get: async (id: string) => projects.get(id) ?? null,
-    getOrCreateActiveByRoot: async (input) => {
-      const existing = Array.from(projects.values()).find(
-        (project) => !project.archivedAt && project.rootPath === input.rootPath,
-      );
-      if (existing) return existing;
-      const record = createPersistedProjectRecord({
-        projectId: `prj_${projects.size}`,
-        rootPath: input.rootPath,
-        kind: input.kind,
-        displayName: input.displayName,
-        createdAt: input.timestamp,
-        updatedAt: input.timestamp,
-      });
-      projects.set(record.projectId, record);
-      return record;
-    },
-    upsert: async (record: PersistedProjectRecord) => {
-      projects.set(record.projectId, record);
-    },
-    archive: async (id: string, archivedAt: string) => {
-      const existing = projects.get(id);
-      if (existing) {
-        projects.set(id, { ...existing, archivedAt, updatedAt: archivedAt });
-      }
-    },
-    remove: async (id: string) => {
-      projects.delete(id);
-    },
-  };
-
-  const workspaceRegistry: WorkspaceRegistry = {
-    initialize: async () => {},
-    existsOnDisk: async () => true,
-    list: async () => Array.from(workspaces.values()),
-    get: async (id: string) => workspaces.get(id) ?? null,
-    update: async (id, updater) => {
-      const existing = workspaces.get(id);
-      if (!existing) return null;
-      const updated = updater(existing);
-      workspaces.set(id, updated);
-      return updated;
-    },
-    upsert: async (record: PersistedWorkspaceRecord) => {
-      workspaces.set(record.workspaceId, record);
-    },
-    archive: async (id: string, archivedAt: string) => {
-      const existing = workspaces.get(id);
-      if (existing) {
-        workspaces.set(id, { ...existing, archivedAt, updatedAt: archivedAt });
-      }
-    },
-    remove: async (id: string) => {
-      workspaces.delete(id);
-    },
-  };
-
-  return { projects, workspaces, projectRegistry, workspaceRegistry };
-}
-
-function createTestLogger() {
-  const logger = {
-    child: () => logger,
-    trace: () => undefined,
-    debug: () => undefined,
-    info: () => undefined,
-    warn: () => undefined,
-    error: () => undefined,
-  };
-  return logger as unknown as pino.Logger;
-}
-
 interface CapturedLogRecord {
   message: string;
   payload: unknown;
@@ -117,6 +56,7 @@ interface CapturedLogRecord {
 
 function createCapturingLogger() {
   const infoRecords: CapturedLogRecord[] = [];
+  const warnRecords: CapturedLogRecord[] = [];
   const logger = {
     child: () => logger,
     trace: () => undefined,
@@ -124,10 +64,12 @@ function createCapturingLogger() {
     info: (payload: unknown, message?: string) => {
       infoRecords.push({ payload, message: message ?? "" });
     },
-    warn: () => undefined,
+    warn: (payload: unknown, message?: string) => {
+      warnRecords.push({ payload, message: message ?? "" });
+    },
     error: () => undefined,
   };
-  return { logger: logger as unknown as pino.Logger, infoRecords };
+  return { logger: logger as unknown as pino.Logger, infoRecords, warnRecords };
 }
 
 function createWorkspaceGitServiceStub(
@@ -185,14 +127,6 @@ function createCheckout(
   };
 }
 
-function deferred(): { promise: Promise<void>; resolve(): void } {
-  let resolve!: () => void;
-  const promise = new Promise<void>((accept) => {
-    resolve = accept;
-  });
-  return { promise, resolve };
-}
-
 class TestCheckouts {
   readonly reads: string[] = [];
   private readonly checkouts = new Map<string, ProjectCheckoutLitePayload>();
@@ -241,6 +175,416 @@ describe("WorkspaceReconciliationService", () => {
     tempDirs.length = 0;
   });
 
+  test("does not emit a duplicate archive when user archival commits before reconciliation's archive", async () => {
+    const rootPath = realpathSync(mkdtempSync(path.join(tmpdir(), "reconcile-archive-commit-")));
+    tempDirs.push(rootPath);
+    const { projects, workspaces, projectRegistry, workspaceRegistry, holdNextArchive } =
+      createTestRegistries();
+    projects.set(
+      "p1",
+      createPersistedProjectRecord({
+        projectId: "p1",
+        rootPath,
+        projectKey: canonicalLocalProjectKey(rootPath),
+        kind: "non_git",
+        displayName: "project",
+        createdAt: timestamp,
+        updatedAt: timestamp,
+      }),
+    );
+    workspaces.set(
+      "w1",
+      createPersistedWorkspaceRecord({
+        workspaceId: "w1",
+        projectId: "p1",
+        cwd: path.join(rootPath, "missing"),
+        kind: "directory",
+        displayName: "workspace",
+        createdAt: timestamp,
+        updatedAt: timestamp,
+      }),
+    );
+    const callbacks: string[] = [];
+    const service = new WorkspaceReconciliationService({
+      projectRegistry,
+      workspaceRegistry,
+      logger: createTestLogger(),
+      onWorkspaceArchived: (id) => {
+        callbacks.push(id);
+      },
+    });
+    const gate = holdNextArchive();
+    try {
+      const scan = service.runOnce();
+      await gate.started.promise;
+      expect(await workspaceRegistry.archive("w1", timestamp)).toBe(true);
+      gate.release.resolve();
+      expect((await scan).changesApplied).toEqual([]);
+      expect(callbacks).toEqual([]);
+      expect(workspaces.get("w1")?.archivedAt).toBe(timestamp);
+    } finally {
+      gate.release.resolve();
+      service.dispose();
+    }
+  });
+
+  test("preserves paths while two inspections saturate capacity, logs once, and recovers after they drain", async () => {
+    const rootPath = realpathSync(mkdtempSync(path.join(tmpdir(), "reconcile-saturated-")));
+    tempDirs.push(rootPath);
+    const { projects, workspaces, projectRegistry, workspaceRegistry } = createTestRegistries();
+    const { logger, warnRecords, infoRecords } = createCapturingLogger();
+    projects.set(
+      "p1",
+      createPersistedProjectRecord({
+        projectId: "p1",
+        rootPath,
+        projectKey: canonicalLocalProjectKey(rootPath),
+        kind: "non_git",
+        displayName: "project",
+        createdAt: timestamp,
+        updatedAt: timestamp,
+      }),
+    );
+    const ids = ["hung1", "hung2", "healthy"];
+    for (const workspaceId of ids) {
+      workspaces.set(
+        workspaceId,
+        createPersistedWorkspaceRecord({
+          workspaceId,
+          projectId: "p1",
+          cwd: path.join(rootPath, workspaceId),
+          kind: "directory",
+          displayName: workspaceId,
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        }),
+      );
+    }
+    const release = deferred();
+    const calls: string[] = [];
+    let recovered = false;
+    let ticks = 0;
+    const probe = setInterval(() => ticks++, 1);
+    const service = new WorkspaceReconciliationService({
+      projectRegistry,
+      workspaceRegistry,
+      logger,
+      inspectionTimeoutMs: 30,
+      inspectDirectory: async (targetPath) => {
+        calls.push(targetPath);
+        if (!recovered && path.basename(targetPath).startsWith("hung")) await release.promise;
+        return "directory";
+      },
+    });
+    try {
+      const result = await service.runOnce();
+      expect(ticks).toBeGreaterThan(0);
+      expect(result.durationMs).toBeLessThan(1000);
+      expect(result.changesApplied).toEqual([]);
+      expect(calls).toEqual(ids.slice(0, 2).map((id) => path.join(rootPath, id)));
+      expect([...workspaces.values()].map((workspace) => workspace.archivedAt)).toEqual([
+        null,
+        null,
+        null,
+      ]);
+      expect(warnRecords.filter((record) => record.message.includes("saturated"))).toEqual([
+        {
+          message: "Workspace directory inspection saturated; preserving uninspected workspaces",
+          payload: { paths: ids.slice(0, 2).map((id) => path.join(rootPath, id)) },
+        },
+      ]);
+      recovered = true;
+      release.resolve();
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      expect(infoRecords).toEqual([
+        {
+          message:
+            "Timed-out workspace directory inspections drained; reconciliation capacity restored",
+          payload: {},
+        },
+      ]);
+      calls.length = 0;
+      await service.runOnce();
+      expect(calls).toEqual([...ids.map((id) => path.join(rootPath, id)), rootPath]);
+      expect(warnRecords.filter((record) => record.message.includes("saturated"))).toHaveLength(1);
+    } finally {
+      release.resolve();
+      clearInterval(probe);
+      service.dispose();
+    }
+  });
+
+  test("inspects every healthy path when one hung inspection times out during a longer scan", async () => {
+    const rootPath = realpathSync(mkdtempSync(path.join(tmpdir(), "reconcile-long-hung-")));
+    tempDirs.push(rootPath);
+    const { projects, workspaces, projectRegistry, workspaceRegistry } = createTestRegistries();
+    projects.set(
+      "p1",
+      createPersistedProjectRecord({
+        projectId: "p1",
+        rootPath,
+        projectKey: canonicalLocalProjectKey(rootPath),
+        kind: "non_git",
+        displayName: "project",
+        createdAt: timestamp,
+        updatedAt: timestamp,
+      }),
+    );
+    const healthyIds = Array.from({ length: 12 }, (_, i) => `healthy${i}`);
+    for (const workspaceId of ["hung", ...healthyIds]) {
+      workspaces.set(
+        workspaceId,
+        createPersistedWorkspaceRecord({
+          workspaceId,
+          projectId: "p1",
+          cwd: path.join(rootPath, workspaceId),
+          kind: "directory",
+          displayName: workspaceId,
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        }),
+      );
+    }
+    const calls: string[] = [];
+    let outstanding = 0;
+    let maximumOutstanding = 0;
+    const { logger, warnRecords } = createCapturingLogger();
+    const service = new WorkspaceReconciliationService({
+      projectRegistry,
+      workspaceRegistry,
+      logger,
+      inspectionTimeoutMs: 100,
+      inspectDirectory: async (targetPath) => {
+        calls.push(targetPath);
+        maximumOutstanding = Math.max(maximumOutstanding, ++outstanding);
+        if (path.basename(targetPath) === "hung") return new Promise(() => {});
+        await new Promise<void>((resolve) => setTimeout(resolve, 20));
+        outstanding--;
+        return "directory";
+      },
+    });
+    try {
+      const result = await service.runOnce();
+      expect(result.durationMs).toBeGreaterThan(100);
+      expect(calls).toEqual(
+        ["hung", ...healthyIds].map((id) => path.join(rootPath, id)).concat(rootPath),
+      );
+      expect(maximumOutstanding).toBe(2);
+      expect(outstanding).toBe(1);
+      expect(workspaces.get("hung")?.archivedAt).toBeNull();
+      expect(result.changesApplied).toEqual([]);
+      expect(warnRecords.filter((record) => record.message.includes("saturated"))).toEqual([]);
+    } finally {
+      service.dispose();
+    }
+  });
+
+  test("times out a hung inspection without archiving it or blocking healthy paths, and retains its IO slot", async () => {
+    const rootPath = realpathSync(mkdtempSync(path.join(tmpdir(), "reconcile-hung-")));
+    tempDirs.push(rootPath);
+    const { projects, workspaces, projectRegistry, workspaceRegistry } = createTestRegistries();
+    projects.set(
+      "p1",
+      createPersistedProjectRecord({
+        projectId: "p1",
+        rootPath,
+        projectKey: canonicalLocalProjectKey(rootPath),
+        kind: "non_git",
+        displayName: "project",
+        createdAt: timestamp,
+        updatedAt: timestamp,
+      }),
+    );
+    for (const workspaceId of ["hung", "healthy", "healthy2", "healthy3"]) {
+      workspaces.set(
+        workspaceId,
+        createPersistedWorkspaceRecord({
+          workspaceId,
+          projectId: "p1",
+          cwd: path.join(rootPath, workspaceId),
+          kind: "directory",
+          displayName: workspaceId,
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        }),
+      );
+    }
+    const calls: string[] = [];
+    let outstanding = 0;
+    let maximumOutstanding = 0;
+    const healthyInspected = deferred();
+    const service = new WorkspaceReconciliationService({
+      projectRegistry,
+      workspaceRegistry,
+      logger: createTestLogger(),
+      inspectionTimeoutMs: 30,
+      inspectDirectory: async (targetPath) => {
+        calls.push(targetPath);
+        maximumOutstanding = Math.max(maximumOutstanding, ++outstanding);
+        if (path.basename(targetPath) === "hung") return new Promise(() => {});
+        healthyInspected.resolve();
+        await new Promise<void>((resolve) => setImmediate(resolve));
+        outstanding--;
+        return "directory";
+      },
+    });
+    try {
+      const scan = service.runOnce();
+      await Promise.race([
+        healthyInspected.promise,
+        scan.then(() => {
+          throw new Error("Reconciliation did not use its directory inspection capability");
+        }),
+      ]);
+      expect(outstanding).toBeLessThanOrEqual(2);
+      expect(workspaces.get("hung")?.archivedAt).toBeNull();
+      const result = await scan;
+      expect(result.changesApplied).toEqual([]);
+      await service.runOnce();
+      expect(calls.filter((cwd) => path.basename(cwd) === "hung")).toHaveLength(1);
+      expect(calls.filter((cwd) => path.basename(cwd) === "healthy3")).toHaveLength(2);
+      expect(maximumOutstanding).toBe(2);
+      expect([...workspaces.values()].map((workspace) => workspace.archivedAt)).toEqual([
+        null,
+        null,
+        null,
+        null,
+      ]);
+    } finally {
+      service.dispose();
+    }
+  });
+
+  test.each(["missing", "directory"] as const)(
+    "does not process or archive a workspace archived during %s inspection",
+    async (state) => {
+      const rootPath = realpathSync(
+        mkdtempSync(path.join(tmpdir(), "reconcile-inspection-archive-")),
+      );
+      tempDirs.push(rootPath);
+      const { projects, workspaces, projectRegistry, workspaceRegistry } = createTestRegistries();
+      projects.set(
+        "p1",
+        createPersistedProjectRecord({
+          projectId: "p1",
+          rootPath,
+          projectKey: canonicalLocalProjectKey(rootPath),
+          kind: "non_git",
+          displayName: "project",
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        }),
+      );
+      const cwd = path.join(rootPath, "missing");
+      workspaces.set(
+        "w1",
+        createPersistedWorkspaceRecord({
+          workspaceId: "w1",
+          projectId: "p1",
+          cwd,
+          kind: "directory",
+          displayName: "workspace",
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        }),
+      );
+      const started = deferred();
+      const release = deferred();
+      const archivedCallbacks: string[] = [];
+      const checkouts = new TestCheckouts();
+      const service = new WorkspaceReconciliationService({
+        projectRegistry,
+        workspaceRegistry,
+        logger: createTestLogger(),
+        workspaceGitService: checkouts,
+        onWorkspaceArchived: (id) => {
+          archivedCallbacks.push(id);
+        },
+        inspectDirectory: async (targetPath) => {
+          if (targetPath === cwd) {
+            started.resolve();
+            await release.promise;
+            return state;
+          }
+          return "directory";
+        },
+      });
+      try {
+        const scan = service.runOnce();
+        await Promise.race([
+          started.promise,
+          scan.then(() => {
+            throw new Error("Reconciliation did not use its directory inspection capability");
+          }),
+        ]);
+        await workspaceRegistry.archive("w1", "2026-01-01T00:00:00.000Z");
+        const archived = workspaces.get("w1");
+        release.resolve();
+        const result = await scan;
+        expect(workspaces.get("w1")).toEqual(archived);
+        expect(archivedCallbacks).toEqual([]);
+        expect(checkouts.reads).toEqual([rootPath]);
+        expect(result.changesApplied).toEqual([]);
+      } finally {
+        release.resolve();
+        service.dispose();
+      }
+    },
+  );
+
+  test("keeps the event loop responsive while inspecting 20000 real workspace paths", async () => {
+    const rootPath = realpathSync(mkdtempSync(path.join(tmpdir(), "reconcile-many-")));
+    tempDirs.push(rootPath);
+    // This CPU belongs to the runner, not to reconciliation. Keep it present
+    // throughout the read so a later loop turn cannot contaminate the budget.
+    let running = true;
+    const unrelatedWork = () => {
+      const threadCpuUsage: (previous?: NodeJS.CpuUsage) => NodeJS.CpuUsage = Reflect.get(
+        process,
+        "threadCpuUsage",
+      );
+      const start = threadCpuUsage();
+      let elapsed: NodeJS.CpuUsage;
+      do {
+        elapsed = threadCpuUsage(start);
+      } while (elapsed.user + elapsed.system < 60_000);
+      if (running) unrelated = setImmediate(unrelatedWork);
+    };
+    let unrelated = setImmediate(unrelatedWork);
+    try {
+      const { stdout, stderr } = await promisify(execFile)(
+        process.execPath,
+        ["--expose-gc", probePath, rootPath],
+        { timeout: 25_000 },
+      );
+      process.stderr.write(stderr);
+      const {
+        changesApplied,
+        blockingMs,
+        filesystemRequests,
+        yields,
+        allArchived,
+        workerMessages,
+      } = JSON.parse(stdout) as {
+        changesApplied: number;
+        blockingMs: number;
+        filesystemRequests: number;
+        yields: number;
+        allArchived: boolean;
+        workerMessages: number;
+      };
+      expect(blockingMs).toBeLessThan(20);
+      expect(filesystemRequests).toBe(20001);
+      expect(changesApplied).toBe(20000);
+      expect(allArchived).toBe(true);
+      expect(yields).toBeGreaterThan(0);
+      expect(workerMessages).toBe(0);
+    } finally {
+      running = false;
+      clearImmediate(unrelated);
+    }
+  }, 30000);
+
   test("preserves workspace archival that lands during boot reconciliation", async () => {
     const workspaceRoot = realpathSync(mkdtempSync(path.join(tmpdir(), "reconcile-archive-race-")));
     tempDirs.push(workspaceRoot);
diff --git a/packages/server/src/server/workspace-reconciliation-service.ts b/packages/server/src/server/workspace-reconciliation-service.ts
index eb79dbacd2..a007dedb59 100644
--- a/packages/server/src/server/workspace-reconciliation-service.ts
+++ b/packages/server/src/server/workspace-reconciliation-service.ts
@@ -1,4 +1,6 @@
-import { statSync, watch as watchPath } from "node:fs";
+import { watch as watchPath } from "node:fs";
+import { stat } from "node:fs/promises";
+import { setImmediate as yieldToLoop } from "node:timers/promises";
 import type { ProjectCheckoutLitePayload } from "@getpaseo/protocol/messages";
 import type pino from "pino";
 import type {
@@ -19,6 +21,8 @@ import { deriveProjectKey } from "./project-key.js";
 
 const DEFAULT_RESCAN_INTERVAL_MS = 5 * 60_000;
 const DEFAULT_DEBOUNCE_MS = 100;
+const INSPECTION_CONCURRENCY = 2;
+const DEFAULT_INSPECTION_TIMEOUT_MS = 5000;
 
 export type ProjectUpdate =
   | { kind: "upsert"; project: PersistedProjectRecord }
@@ -95,6 +99,8 @@ export interface WorkspaceReconciliationServiceOptions {
   clock?: ReconciliationClock;
   rescanIntervalMs?: number;
   debounceMs?: number;
+  inspectDirectory?: (targetPath: string) => Promise<DirectoryState>;
+  inspectionTimeoutMs?: number;
 }
 
 interface ProjectReconciliationInput {
@@ -110,9 +116,17 @@ interface CachedCheckoutRead {
   checkout: Promise<ProjectCheckoutLitePayload>;
 }
 
-type DirectoryState = "directory" | "missing" | "unreadable";
+export type DirectoryState = "directory" | "missing" | "unreadable";
 
 export class WorkspaceReconciliationService {
+  // Timed-out fs operations retain their slot until the OS returns. Never use
+  // the deadline to admit more work into libuv's shared threadpool.
+  private readonly timedOutPaths = new Set<string>();
+  private inspectionSaturated = false;
+  private readonly inspectionWaiters = new Set<() => void>();
+  private readonly pendingInspections = new Map<string, Promise<DirectoryState>>();
+  private readonly directoryInspection: (targetPath: string) => Promise<DirectoryState>;
+  private readonly inspectionTimeoutMs: number;
   private readonly serverId: string | undefined;
   private readonly projectRegistry: ProjectRegistry;
   private readonly workspaceRegistry: WorkspaceRegistry;
@@ -136,6 +150,10 @@ export class WorkspaceReconciliationService {
   private reconcileQueuedMode: "metadata" | "full" | null = null;
 
   constructor(options: WorkspaceReconciliationServiceOptions) {
+    this.directoryInspection =
+      options.inspectDirectory ??
+      (async (targetPath) => ((await stat(targetPath)).isDirectory() ? "directory" : "missing"));
+    this.inspectionTimeoutMs = options.inspectionTimeoutMs ?? DEFAULT_INSPECTION_TIMEOUT_MS;
     this.serverId = options.serverId;
     this.projectRegistry = options.projectRegistry;
     this.workspaceRegistry = options.workspaceRegistry;
@@ -180,6 +198,7 @@ export class WorkspaceReconciliationService {
 
   dispose(): void {
     this.disposed = true;
+    this.wakeInspectionWaiters();
     this.unsubscribeRegistry?.();
     this.unsubscribeRegistry = null;
     if (this.rescanTimer) this.clock.clearInterval(this.rescanTimer);
@@ -194,19 +213,26 @@ 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[]>();
-    for (const workspace of workspaces) {
-      if (workspace.archivedAt || this.inspectDirectory(workspace.cwd) !== "directory") continue;
+    const workspaceStates = await mapBounded(
+      workspaces.filter((w) => !w.archivedAt),
+      async (workspace) => ({ workspace, state: await this.inspectDirectory(workspace.cwd) }),
+    );
+    for (const { workspace, state } of workspaceStates) {
+      if (state !== "directory") continue;
+      if ((await this.workspaceRegistry.get(workspace.workspaceId))?.archivedAt !== null) continue;
       const siblings = workspacesByProject.get(workspace.projectId) ?? [];
       siblings.push(workspace);
       workspacesByProject.set(workspace.projectId, siblings);
     }
+    const projectStates = await mapBounded(
+      projects.filter((p) => !p.archivedAt),
+      async (project) => ({ project, state: await this.inspectDirectory(project.rootPath) }),
+    );
     await this.reconcileGitMetadataForProjects(
-      projects.filter(
-        (project) => !project.archivedAt && this.inspectDirectory(project.rootPath) === "directory",
-      ),
+      projectStates.filter(({ state }) => state === "directory").map(({ project }) => project),
       workspacesByProject,
       changes,
     );
@@ -219,26 +245,33 @@ 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(
+      activeProjects.map((project) => [project.projectId, project]),
+    );
     const activeWorkspaces = allWorkspaces.filter((w) => !w.archivedAt);
-    const workspaceDirectoryStates = activeWorkspaces.map((workspace) => ({
+    const workspaceDirectoryStates = await mapBounded(activeWorkspaces, async (workspace) => ({
       workspace,
-      state: this.inspectDirectory(workspace.cwd),
+      state: await this.inspectDirectory(workspace.cwd),
+    }));
+    // Read project roots after workspaces: losing a volume can withhold an
+    // archive, never turn a workspace's absence into proof of deletion.
+    const projectStates = await mapBounded(activeProjects, async (project) => ({
+      project,
+      state: await this.inspectDirectory(project.rootPath),
     }));
-    // Project roots are read after the workspace directories, so a volume that
-    // goes away mid-pass leaves its project unreachable rather than its workspaces
-    // alone. The skew can only withhold an archive, never produce one.
     const reachableProjectIds = new Set(
-      activeProjects
-        .filter((project) => this.inspectDirectory(project.rootPath) === "directory")
-        .map((project) => project.projectId),
+      projectStates
+        .filter(({ state }) => state === "directory")
+        .map(({ project }) => project.projectId),
     );
 
     const workspacesByProject = new Map<string, PersistedWorkspaceRecord[]>();
     for (const { workspace, state } of workspaceDirectoryStates) {
       if (state !== "directory") continue;
+      if ((await this.workspaceRegistry.get(workspace.workspaceId))?.archivedAt !== null) continue;
       const list = workspacesByProject.get(workspace.projectId) ?? [];
       list.push(workspace);
       workspacesByProject.set(workspace.projectId, list);
@@ -255,26 +288,29 @@ export class WorkspaceReconciliationService {
           state === "missing" && reachableProjectIds.has(workspace.projectId),
       )
       .map(({ workspace }) => workspace);
-    await Promise.all(
-      missingWorkspaces.map(async (workspace) => {
-        const timestamp = new Date().toISOString();
-        await this.workspaceRegistry.archive(workspace.workspaceId, timestamp);
-        await this.onWorkspaceArchived?.(workspace.workspaceId);
-        changes.push({
-          kind: "workspace_archived",
-          workspaceId: workspace.workspaceId,
-          directory: workspace.cwd,
-          reason: "directory_missing",
-        });
-
-        // Update the in-memory list for the project orphan check below
-        const siblings = workspacesByProject.get(workspace.projectId);
-        if (siblings) {
-          const updated = siblings.filter((w) => w.workspaceId !== workspace.workspaceId);
-          workspacesByProject.set(workspace.projectId, updated);
-        }
-      }),
-    );
+    await mapBounded(missingWorkspaces, async (workspace) => {
+      const current = await this.workspaceRegistry.get(workspace.workspaceId);
+      const project = await this.projectRegistry.get(workspace.projectId);
+      if (
+        !current ||
+        current.archivedAt ||
+        current.cwd !== workspace.cwd ||
+        current.projectId !== workspace.projectId ||
+        !project ||
+        project.archivedAt ||
+        project.rootPath !== activeProjectsById.get(project.projectId)?.rootPath
+      )
+        return;
+      const timestamp = new Date().toISOString();
+      if (!(await this.workspaceRegistry.archive(workspace.workspaceId, timestamp))) return;
+      await this.onWorkspaceArchived?.(workspace.workspaceId);
+      changes.push({
+        kind: "workspace_archived",
+        workspaceId: workspace.workspaceId,
+        directory: workspace.cwd,
+        reason: "directory_missing",
+      });
+    });
 
     // 2. Reconcile mutable git metadata without changing identity or membership.
     //    Projects persist until explicitly removed, even when they currently have
@@ -351,13 +387,17 @@ export class WorkspaceReconciliationService {
   }
 
   private async reconcileProject(input: ProjectReconciliationInput): Promise<void> {
-    const { project, siblings, currentGit, readCheckout, changes } = input;
+    const { siblings, currentGit, readCheckout, changes } = input;
     const workspaceCheckouts = await Promise.all(
-      siblings.map(async (workspace) => ({
-        workspace,
-        checkout: await readCheckout(workspace.cwd),
-      })),
+      siblings.map(async (workspace) => {
+        const current = await this.workspaceRegistry.get(workspace.workspaceId);
+        if (!current || current.cwd !== workspace.cwd || current.projectId !== workspace.projectId)
+          return null;
+        return { workspace: current, checkout: await readCheckout(current.cwd) };
+      }),
     );
+    const project = await this.projectRegistry.get(input.project.projectId);
+    if (!project || project.archivedAt || project.rootPath !== input.project.rootPath) return;
     const projectUpdates: Partial<Pick<PersistedProjectRecord, "kind" | "projectKey">> = {};
     const mappedKind = deriveProjectKind(currentGit);
     const projectKey = deriveProjectKey({
@@ -377,40 +417,47 @@ export class WorkspaceReconciliationService {
 
     if (Object.keys(projectUpdates).length > 0) {
       const timestamp = new Date().toISOString();
-      await this.projectRegistry.upsert({
-        ...project,
-        ...projectUpdates,
-        updatedAt: timestamp,
-      });
-      changes.push({
-        kind: "project_updated",
-        projectId: project.projectId,
-        directory: project.rootPath,
-        fields: projectUpdates,
+      let applied = false;
+      await this.projectRegistry.update(project.projectId, (current) => {
+        if (current.archivedAt || current.rootPath !== project.rootPath) return current;
+        applied = true;
+        return { ...current, ...projectUpdates, updatedAt: timestamp };
       });
+      if (applied)
+        changes.push({
+          kind: "project_updated",
+          projectId: project.projectId,
+          directory: project.rootPath,
+          fields: projectUpdates,
+        });
     }
 
     await Promise.all(
-      workspaceCheckouts.map(async ({ workspace, checkout: wsGit }) => {
+      workspaceCheckouts.map(async (entry) => {
+        if (!entry) return;
+        const { workspace, checkout: wsGit } = entry;
         const timestamp = new Date().toISOString();
-        const update = reconcileWorkspacePlacement({
-          workspace,
-          checkout: wsGit,
-          updatedAt: timestamp,
+        if (!reconcileWorkspacePlacement({ workspace, checkout: wsGit, updatedAt: timestamp }))
+          return;
+        let fields: Partial<MutableWorkspacePlacement> | null = null;
+        await this.workspaceRegistry.update(workspace.workspaceId, (current) => {
+          if (current.cwd !== workspace.cwd || current.projectId !== workspace.projectId)
+            return current;
+          const update = reconcileWorkspacePlacement({
+            workspace: current,
+            checkout: wsGit,
+            updatedAt: timestamp,
+          });
+          if (!update) return current;
+          fields = update.fields;
+          return { ...current, ...fields, updatedAt: timestamp };
         });
-        if (!update) return;
-
-        const updated = await this.workspaceRegistry.update(workspace.workspaceId, (current) => ({
-          ...current,
-          ...update.fields,
-          updatedAt: timestamp,
-        }));
-        if (!updated) return;
+        if (!fields) return;
         changes.push({
           kind: "workspace_updated",
           workspaceId: workspace.workspaceId,
           directory: workspace.cwd,
-          fields: update.fields,
+          fields,
         });
       }),
     );
@@ -500,7 +547,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);
         }
@@ -537,16 +584,74 @@ export class WorkspaceReconciliationService {
     return this.workspaceGitService.getCheckout(cwd);
   }
 
-  private inspectDirectory(targetPath: string): DirectoryState {
+  private wakeInspectionWaiters(): void {
+    for (const wake of this.inspectionWaiters) wake();
+    this.inspectionWaiters.clear();
+  }
+
+  private async inspectDirectory(targetPath: string): Promise<DirectoryState> {
+    // A healthy in-flight inspection owns capacity temporarily. Wait for it;
+    // only unresolved operations that have all timed out justify skipping paths.
+    while (
+      !this.disposed &&
+      !this.pendingInspections.has(targetPath) &&
+      this.pendingInspections.size >= INSPECTION_CONCURRENCY
+    ) {
+      if (this.timedOutPaths.size === INSPECTION_CONCURRENCY) return "unreadable";
+      await new Promise<void>((resolve) => this.inspectionWaiters.add(resolve));
+    }
+    if (this.disposed) return "unreadable";
+    let pending = this.pendingInspections.get(targetPath);
+    if (!pending) {
+      pending = Promise.resolve()
+        .then(() => this.directoryInspection(targetPath))
+        .catch((error) => {
+          if (isMissingPathError(error)) return "missing" as const;
+          this.logger.warn(
+            { err: error, targetPath },
+            "Skipped workspace reconciliation after directory inspection failed",
+          );
+          return "unreadable" as const;
+        })
+        .finally(() => {
+          this.pendingInspections.delete(targetPath);
+          this.timedOutPaths.delete(targetPath);
+          this.wakeInspectionWaiters();
+          if (this.inspectionSaturated && this.timedOutPaths.size === 0) {
+            this.inspectionSaturated = false;
+            this.logger.info(
+              {},
+              "Timed-out workspace directory inspections drained; reconciliation capacity restored",
+            );
+          }
+        });
+      this.pendingInspections.set(targetPath, pending);
+    }
+    let timer: ReturnType<typeof setTimeout> | undefined;
     try {
-      return statSync(targetPath).isDirectory() ? "directory" : "missing";
-    } catch (error) {
-      if (isMissingPathError(error)) return "missing";
-      this.logger.warn(
-        { err: error, targetPath },
-        "Skipped workspace reconciliation after directory inspection failed",
-      );
-      return "unreadable";
+      return await Promise.race([
+        pending,
+        new Promise<DirectoryState>((resolve) => {
+          timer = setTimeout(() => {
+            this.timedOutPaths.add(targetPath);
+            this.wakeInspectionWaiters();
+            if (!this.inspectionSaturated && this.timedOutPaths.size === INSPECTION_CONCURRENCY) {
+              this.inspectionSaturated = true;
+              this.logger.warn(
+                { paths: [...this.timedOutPaths] },
+                "Workspace directory inspection saturated; preserving uninspected workspaces",
+              );
+            }
+            this.logger.warn(
+              { targetPath },
+              "Skipped workspace reconciliation after directory inspection timed out",
+            );
+            resolve("unreadable");
+          }, this.inspectionTimeoutMs);
+        }),
+      ]);
+    } finally {
+      clearTimeout(timer);
     }
   }
 }
@@ -555,3 +660,21 @@ function isMissingPathError(error: unknown): boolean {
   if (typeof error !== "object" || error === null || !("code" in error)) return false;
   return error.code === "ENOENT" || error.code === "ENOTDIR";
 }
+
+// Two workers bound admission; yielding also bounds passes whose adapters settle
+// immediately (including unavailable paths after both IO slots time out).
+async function mapBounded<T, R>(items: T[], visit: (item: T) => Promise<R>): Promise<R[]> {
+  const results: R[] = [];
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(INSPECTION_CONCURRENCY, items.length) }, async () => {
+      let count = 0;
+      while (next < items.length) {
+        const index = next++;
+        results[index] = await visit(items[index]!);
+        if (++count % 32 === 0) await yieldToLoop();
+      }
+    }),
+  );
+  return results;
+}
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 cf192a44b6..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 ||
@@ -74,7 +74,7 @@ export async function bootstrapWorkspaceRegistries(options: {
       continue;
     }
     try {
-      pinPaseoWorktreeBranchIdentityIfMissing(workspace.worktreeRoot, workspace.branch);
+      await pinPaseoWorktreeBranchIdentityIfMissing(workspace.worktreeRoot, workspace.branch);
     } catch (error) {
       options.logger.warn(
         { err: error, workspaceId: workspace.workspaceId },
@@ -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 6c27027edc..c26a2fe447 100644
--- a/packages/server/src/server/workspace-registry.test.ts
+++ b/packages/server/src/server/workspace-registry.test.ts
@@ -116,6 +116,35 @@ describe("workspace registries", () => {
     expect(await projectRegistry.list()).toEqual([]);
   });
 
+  test("writes once per mutation and skips missing-record mutations", async () => {
+    let writes = 0;
+    const registry = new FileBackedProjectRegistry(
+      path.join(tmpDir, "projects", "write-count.json"),
+      logger,
+      {
+        writeRecords: async (filePath, records) => {
+          writes++;
+          await writeJsonFileAtomic(filePath, records);
+        },
+      },
+    );
+    const project = createPersistedProjectRecord({
+      projectId: "counted",
+      rootPath: tmpDir,
+      kind: "git",
+      displayName: "Counted",
+      createdAt: "2026-03-01T00:00:00.000Z",
+      updatedAt: "2026-03-01T00:00:00.000Z",
+    });
+    await registry.upsert(project);
+    expect(writes).toBe(1);
+    await registry.update("missing", (current) => current);
+    await registry.remove("missing");
+    expect(writes).toBe(1);
+    await registry.update(project.projectId, (current) => ({ ...current, customName: "Changed" }));
+    expect(writes).toBe(2);
+  });
+
   test("preserves a concurrent project update when archiving", async () => {
     let pauseNextWrite = false;
     let releaseWrite!: () => void;
@@ -471,10 +500,10 @@ describe("workspace registries", () => {
       workspace: archived,
     });
     expect(await workspaceRegistry.get("/tmp/repo")).toBeNull();
-    expect(await workspaceRegistry.list()).toEqual([]);
+    expect(await workspaceRegistry.listAll()).toEqual([]);
   });
 
-  test("refreshes workspace archive timestamps when an archive is repeated", async () => {
+  test("preserves the first workspace archive and reports whether a queued archive applied", async () => {
     await workspaceRegistry.initialize();
     await workspaceRegistry.upsert(
       createPersistedWorkspaceRecord({
@@ -488,12 +517,24 @@ describe("workspace registries", () => {
       }),
     );
 
-    await workspaceRegistry.archive("workspace-one", "2026-03-02T00:00:00.000Z");
-    await workspaceRegistry.archive("workspace-one", "2026-03-03T00:00:00.000Z");
-
-    expect(await workspaceRegistry.get("workspace-one")).toMatchObject({
-      archivedAt: "2026-03-03T00:00:00.000Z",
-      updatedAt: "2026-03-03T00:00:00.000Z",
+    const events: WorkspaceMutation[] = [];
+    workspaceRegistry.subscribeToMutations((event) => {
+      events.push(event);
+    });
+    expect(
+      await Promise.all([
+        workspaceRegistry.archive("workspace-one", "2026-03-02T00:00:00.000Z"),
+        workspaceRegistry.archive("workspace-one", "2026-03-03T00:00:00.000Z"),
+      ]),
+    ).toEqual([true, false]);
+    expect(events.map((event) => event.kind)).toEqual(["archive"]);
+    const reloaded = new FileBackedWorkspaceRegistry(
+      path.join(tmpDir, "projects", "workspaces.json"),
+      logger,
+    );
+    expect(await reloaded.get("workspace-one")).toMatchObject({
+      archivedAt: "2026-03-02T00:00:00.000Z",
+      updatedAt: "2026-03-02T00:00:00.000Z",
     });
   });
 
diff --git a/packages/server/src/server/workspace-registry.ts b/packages/server/src/server/workspace-registry.ts
index 0e0fb4e62c..b337543c7e 100644
--- a/packages/server/src/server/workspace-registry.ts
+++ b/packages/server/src/server/workspace-registry.ts
@@ -49,6 +49,7 @@ const PersistedProjectRecordSchema = z.object({
 });
 
 const PersistedWorkspaceRecordSchema = z.object({
+  parentWorkspaceId: z.string().optional(),
   workspaceId: z.string(),
   projectId: z.string(),
   cwd: z.string(),
@@ -75,9 +76,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()
@@ -156,7 +157,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,
@@ -167,7 +169,7 @@ export interface WorkspaceRegistry {
     workspaceId: string,
     archivedAt: string,
     context?: WorkspaceArchiveContext,
-  ): Promise<void>;
+  ): Promise<boolean>;
   remove(workspaceId: string): Promise<void>;
   /** Central lifecycle seam for daemon-global workspace observers. */
   subscribeToMutations?(
@@ -182,6 +184,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 +222,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;
@@ -247,20 +255,6 @@ class FileBackedRegistry<TRecord extends RegistryRecord> {
     });
   }
 
-  async archive(id: string, archivedAt: string): Promise<void> {
-    await this.archiveIfPresent(id, archivedAt);
-  }
-
-  protected async archiveIfPresent(id: string, archivedAt: string): Promise<TRecord | null> {
-    return this.mutateCache((records) => {
-      const existing = records.get(id);
-      if (!existing) return null;
-      const next = this.schema.parse({ ...existing, updatedAt: archivedAt, archivedAt });
-      records.set(id, next);
-      return next;
-    });
-  }
-
   protected async archiveIfActive(id: string, archivedAt: string): Promise<TRecord | null> {
     return this.mutateCache((records) => {
       const existing = records.get(id);
@@ -302,6 +296,7 @@ class FileBackedRegistry<TRecord extends RegistryRecord> {
         this.logger.error({ err: error, filePath: this.filePath }, "Failed to load registry file");
       }
     }
+    this.rebuildActiveIndex();
     this.loaded = true;
   }
 
@@ -349,6 +344,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 {
@@ -356,6 +352,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;
   }
@@ -373,6 +374,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<
@@ -485,7 +490,7 @@ export class FileBackedProjectRegistry
     return project;
   }
 
-  override async archive(projectId: string, archivedAt: string): Promise<void> {
+  async archive(projectId: string, archivedAt: string): Promise<void> {
     const project = await this.archiveIfActive(projectId, archivedAt);
     if (!project) return;
     await this.notifyMutation({ kind: "archive", projectId, project });
@@ -565,21 +570,28 @@ export class FileBackedWorkspaceRegistry
     });
   }
 
-  override async archive(
+  async archive(
     workspaceId: string,
     archivedAt: string,
     context?: WorkspaceArchiveContext,
-  ): Promise<void> {
-    const workspace = await super.update(workspaceId, (existing) => ({
-      ...existing,
-      updatedAt: archivedAt,
-      archivedAt,
-      ...(context?.autoArchivedChangeRequestUrl
-        ? { autoArchivedChangeRequestUrl: context.autoArchivedChangeRequestUrl }
-        : {}),
-    }));
-    if (!workspace) return;
+  ): Promise<boolean> {
+    const [workspace] = await this.mutateMany((records) => {
+      const existing = records.get(workspaceId);
+      if (!existing || existing.archivedAt) return [];
+      return [
+        {
+          ...existing,
+          updatedAt: archivedAt,
+          archivedAt,
+          ...(context?.autoArchivedChangeRequestUrl
+            ? { autoArchivedChangeRequestUrl: context.autoArchivedChangeRequestUrl }
+            : {}),
+        },
+      ];
+    });
+    if (!workspace) return false;
     await this.notifyMutation({ kind: "archive", workspaceId, workspace });
+    return true;
   }
 
   override async remove(workspaceId: string): Promise<void> {
@@ -668,6 +680,7 @@ export function resolveProjectDisplayName(record: PersistedProjectRecord): strin
 }
 
 export function createPersistedWorkspaceRecord(input: {
+  parentWorkspaceId?: string;
   workspaceId: string;
   projectId: string;
   cwd: string;
diff --git a/packages/server/src/server/worktree-bootstrap.test.ts b/packages/server/src/server/worktree-bootstrap.test.ts
index 96da6e648b..ed43e02388 100644
--- a/packages/server/src/server/worktree-bootstrap.test.ts
+++ b/packages/server/src/server/worktree-bootstrap.test.ts
@@ -209,13 +209,8 @@ describe("runWorktreeAutoTerminals", () => {
             getSize: () => ({ rows: 0, cols: 0 }),
             getTitle: () => undefined,
             getExitInfo: () => null,
-            getState: () => ({
-              rows: 0,
-              cols: 0,
-              grid: [],
-              scrollback: [],
-              cursor: { row: 0, col: 0 },
-            }),
+            hasOutput: () => false,
+
             kill: () => {},
             killAndWait: async () => {},
           };
@@ -312,13 +307,8 @@ describe("runWorktreeAutoTerminals", () => {
               }
             };
           },
-          getState: () => ({
-            rows: 1,
-            cols: 1,
-            grid: [[{ char: "$" }]],
-            scrollback: [],
-            cursor: { row: 0, col: 0 },
-          }),
+          hasOutput: () => true,
+
           kill: () => {},
           onTitleChange: () => () => {},
           onActivityChange: () => () => {},
diff --git a/packages/server/src/server/worktree-bootstrap.ts b/packages/server/src/server/worktree-bootstrap.ts
index 6e138e8ab4..1e1ba58f8e 100644
--- a/packages/server/src/server/worktree-bootstrap.ts
+++ b/packages/server/src/server/worktree-bootstrap.ts
@@ -269,9 +269,9 @@ export function buildWorktreeSetupDetail(input: {
 }
 
 async function waitForTerminalBootstrapReadiness(
-  terminal: Pick<TerminalSession, "getState" | "subscribe">,
+  terminal: Pick<TerminalSession, "hasOutput" | "subscribe">,
 ): Promise<void> {
-  if (terminalHasOutput(terminal.getState())) {
+  if (terminal.hasOutput()) {
     return;
   }
 
@@ -304,7 +304,7 @@ async function waitForTerminalBootstrapReadiness(
       finish();
     });
 
-    if (terminalHasOutput(terminal.getState())) {
+    if (terminal.hasOutput()) {
       finish();
       return;
     }
@@ -313,17 +313,6 @@ async function waitForTerminalBootstrapReadiness(
   });
 }
 
-function terminalHasOutput(state: ReturnType<TerminalSession["getState"]>): boolean {
-  for (const row of [...state.scrollback, ...state.grid]) {
-    for (const cell of row) {
-      if (cell.char.trim().length > 0) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-
 export async function runWorktreeAutoTerminals(options: {
   workspaceId: string;
   worktree: WorktreeConfig;
@@ -335,7 +324,7 @@ export async function runWorktreeAutoTerminals(options: {
   if (!options.terminalManager) return;
   const terminalManager = options.terminalManager;
   await Promise.all(
-    getWorktreeTerminalSpecs(options.workspaceCwd).map(async (spec) => {
+    (await getWorktreeTerminalSpecs(options.workspaceCwd)).map(async (spec) => {
       try {
         const terminal = await terminalManager.createTerminal({
           cwd: options.workspaceCwd,
@@ -545,7 +534,7 @@ export async function spawnWorkspaceScript(
     logger,
     onLifecycleChanged,
   } = options;
-  const configResult = readPaseoConfig(repoRoot);
+  const configResult = await readPaseoConfig(repoRoot);
   if (!configResult.ok) {
     throw paseoConfigParseError(configResult);
   }
diff --git a/packages/server/src/server/worktree-branch-name-generator.test.ts b/packages/server/src/server/worktree-branch-name-generator.test.ts
index 8eb1625265..186dcbc0b1 100644
--- a/packages/server/src/server/worktree-branch-name-generator.test.ts
+++ b/packages/server/src/server/worktree-branch-name-generator.test.ts
@@ -343,8 +343,8 @@ describe("generateBranchNameFromFirstAgentContext", () => {
     const repoRoot = createTempDir("paseo-branch-config-");
     const worktreeRoot = createTempDir("paseo-branch-worktree-");
     mkdirSync(path.join(worktreeRoot, ".git"));
-    writePaseoWorktreeMetadata(worktreeRoot, { baseRefName: "main" });
-    writePaseoWorktreeFirstAgentBranchAutoNameMetadata(worktreeRoot, {
+    await writePaseoWorktreeMetadata(worktreeRoot, { baseRefName: "main" });
+    await writePaseoWorktreeFirstAgentBranchAutoNameMetadata(worktreeRoot, {
       placeholderBranchName: "dazzling-yak",
     });
     writeConfig(repoRoot, {
diff --git a/packages/server/src/server/worktree-core.posix.test.ts b/packages/server/src/server/worktree-core.posix.test.ts
index 9d02d0a2ec..7a7a342732 100644
--- a/packages/server/src/server/worktree-core.posix.test.ts
+++ b/packages/server/src/server/worktree-core.posix.test.ts
@@ -24,6 +24,7 @@ import {
   getPaseoWorktreeMetadataPath,
   readPaseoWorktreeMetadata,
 } from "../utils/worktree-metadata.js";
+import { validateBeforeRequest, validateBeforeResult } from "./plugins/lifecycle/index.js";
 import { UnknownBranchError } from "../utils/worktree.js";
 import { createWorktreeCore as createCoreWorktree } from "./worktree-core.js";
 import { isPlatform } from "../test-utils/platform.js";
@@ -419,6 +420,21 @@ describe.skipIf(isPlatform("win32"))("worktree-core POSIX-only", () => {
       expect(existsSync(result.worktree.worktreePath)).toBe(true);
     });
 
+    test("keeps default placement suffixes when the default destination already exists", async () => {
+      const { tempDir, repoDir, paseoHome } = createGitRepo();
+      cleanupPaths.push(tempDir);
+      const first = await createCoreWorktree(
+        { cwd: repoDir, paseoHome, branchName: "first", worktreeSlug: "same" },
+        createCoreDeps(),
+      );
+      const second = await createCoreWorktree(
+        { cwd: repoDir, paseoHome, branchName: "second", worktreeSlug: "same" },
+        createCoreDeps(),
+      );
+      expect(second.worktree.worktreePath).toBe(first.worktree.worktreePath + "-1");
+      expect(existsSync(first.worktree.worktreePath)).toBe(true);
+    });
+
     test("creates branch-off worktrees from origin main without tracking origin main", async () => {
       const { tempDir, repoDir, paseoHome } = createGitRepoWithOriginMain();
       cleanupPaths.push(tempDir);
@@ -488,6 +504,42 @@ describe.skipIf(isPlatform("win32"))("worktree-core POSIX-only", () => {
       expect(result.worktree.branchName).toBe("feature/review-pr");
     });
 
+    test("round trips every resolved change-request field through an unchanged before-hook result", async () => {
+      const { tempDir, repoDir, paseoHome } = createGitHubPrRemoteRepo();
+      cleanupPaths.push(tempDir);
+      const deps = createCoreDeps();
+      const requests: unknown[] = [];
+      const result = await createCoreWorktree(
+        { cwd: repoDir, githubPrNumber: 123, refName: "feature/review-pr", paseoHome },
+        {
+          ...deps,
+          lifecycle: {
+            before: async (name, request) => {
+              requests.push(request);
+              return validateBeforeResult(name, validateBeforeRequest(name, request), request);
+            },
+          },
+        },
+      );
+      expect(requests).toEqual([
+        {
+          kind: "checkout-change-request",
+          forge: "github",
+          changeRequestNumber: 123,
+          headRef: "feature/review-pr",
+          baseRef: "main",
+          branch: "feature/review-pr",
+          checkoutRefs: [{ remoteName: "origin", remoteRef: "refs/pull/123/head" }],
+          trackOriginHead: true,
+          repoRoot: repoDir,
+          sourceCheckout: repoDir,
+          slug: "feature-review-pr",
+          path: result.worktree.worktreePath,
+        },
+      ]);
+      expect(result.worktree.branchName).toBe("feature/review-pr");
+    });
+
     test("uses the PR head ref as the default slug when no slug is supplied", async () => {
       const { tempDir, repoDir, paseoHome } = createGitHubPrRemoteRepo();
       cleanupPaths.push(tempDir);
@@ -854,7 +906,7 @@ describe.skipIf(isPlatform("win32"))("worktree-core POSIX-only", () => {
         second.worktree.worktreePath,
         "remote.paseo-pr-14.url",
       );
-      const metadata = readPaseoWorktreeMetadata(second.worktree.worktreePath);
+      const metadata = await readPaseoWorktreeMetadata(second.worktree.worktreePath);
       const facts = await getCheckoutSnapshotFacts(second.worktree.worktreePath, { paseoHome });
 
       expect(second.worktree.branchName).toBe("feature/gitlab-mr-1");
@@ -1113,7 +1165,7 @@ describe.skipIf(isPlatform("win32"))("worktree-core POSIX-only", () => {
         createCoreDeps({ github }),
       );
       writeFileSync(
-        getPaseoWorktreeMetadataPath(second.worktree.worktreePath),
+        await getPaseoWorktreeMetadataPath(second.worktree.worktreePath),
         `${JSON.stringify({ version: 1, baseRefName: "main" }, null, 2)}\n`,
         "utf8",
       );
diff --git a/packages/server/src/server/worktree-core.ts b/packages/server/src/server/worktree-core.ts
index b0310d6e1f..cc6c9fdbd6 100644
--- a/packages/server/src/server/worktree-core.ts
+++ b/packages/server/src/server/worktree-core.ts
@@ -1,8 +1,11 @@
+import type { PluginWorktreeCreateRequest } from "@getpaseo/plugin/server";
+import type { PluginLifecycle } from "./plugins/lifecycle/index.js";
 import { createNameId } from "mnemonic-id";
 
 import type { ForgeService } from "../services/forge-service.js";
 import {
   createWorktree,
+  resolveDefaultWorktreePath,
   slugify,
   validateBranchSlug,
   type CreatedWorktree,
@@ -15,7 +18,7 @@ import {
 } from "./resolve-worktree-creation-intent.js";
 import type { ChangeRequestCheckoutSource, FirstAgentContext } from "@getpaseo/protocol/messages";
 import type { WorkspaceGitService } from "./workspace-git-service.js";
-import { runWithGitCommandPriority } from "../utils/run-git-command.js";
+import { runGitCommand, runWithGitCommandPriority } from "../utils/run-git-command.js";
 
 export interface CreateWorktreeCoreInput {
   cwd: string;
@@ -31,6 +34,7 @@ export interface CreateWorktreeCoreInput {
 }
 
 export interface CreateWorktreeCoreDeps {
+  lifecycle?: Pick<PluginLifecycle, "before">;
   github: ForgeService;
   workspaceGitService?: Pick<
     WorkspaceGitService,
@@ -90,7 +94,7 @@ async function createWorktreeCoreWithPriority(
   }
 
   const forge = await resolveForge(repoRoot, deps, intentInput);
-  const intent = await resolveWorktreeCreationIntent(intentInput, repoRoot, {
+  let intent = await resolveWorktreeCreationIntent(intentInput, repoRoot, {
     forge: forge.forge,
     forgeService: forge.service,
     resolveDefaultBranch: (root) => resolveDefaultBranch(root, deps),
@@ -114,10 +118,33 @@ async function createWorktreeCoreWithPriority(
     }
   }
 
+  const defaultPath = await resolveDefaultWorktreePath({
+    cwd: repoRoot,
+    paseoHome: input.paseoHome,
+    worktreesRoot: input.worktreesRoot,
+    worktreeSlug: normalizedSlug,
+  });
+  const { stdout: sourceRoot } = await runGitCommand(["rev-parse", "--show-toplevel"], {
+    cwd: input.cwd,
+  });
+  const sourceCheckout = sourceRoot.trim();
+  const request = describeCreationRequest(intent, {
+    repoRoot,
+    sourceCheckout,
+    slug: normalizedSlug,
+    path: defaultPath,
+  });
+  const transformed = deps.lifecycle
+    ? await deps.lifecycle.before("worktree.create.before", request)
+    : request;
+  normalizedSlug = validateWorktreeSlug(transformed.slug);
+  intent = creationIntentFromRequest(transformed, intent);
+
   return {
     worktree: await createWorktree({
       cwd: repoRoot,
       worktreeSlug: normalizedSlug,
+      worktreePath: transformed.path,
       source: intent,
       paseoHome: input.paseoHome,
       worktreesRoot: input.worktreesRoot,
@@ -128,6 +155,61 @@ async function createWorktreeCoreWithPriority(
   };
 }
 
+function describeCreationRequest(
+  intent: WorktreeCreationIntent,
+  placement: Pick<PluginWorktreeCreateRequest, "repoRoot" | "sourceCheckout" | "slug" | "path">,
+): PluginWorktreeCreateRequest {
+  if (intent.kind === "branch-off")
+    return {
+      ...placement,
+      kind: intent.kind,
+      branch: intent.branchName,
+      baseRef: intent.baseBranch,
+    };
+  if (intent.kind === "checkout-branch")
+    return { ...placement, kind: intent.kind, branch: intent.branchName };
+  const { localBranchName, baseRefName, ...facts } = intent;
+  return {
+    ...placement,
+    ...facts,
+    branch: localBranchName ?? intent.headRef,
+    baseRef: baseRefName,
+  };
+}
+
+function creationIntentFromRequest(
+  request: PluginWorktreeCreateRequest,
+  original: WorktreeCreationIntent,
+): WorktreeCreationIntent {
+  if (request.kind === "branch-off") {
+    return { kind: request.kind, branchName: request.branch, baseBranch: request.baseRef };
+  }
+  if (request.kind === "checkout-branch") {
+    return {
+      kind: request.kind,
+      branchName: request.branch,
+    };
+  }
+  const {
+    repoRoot: _repoRoot,
+    sourceCheckout: _checkout,
+    slug: _slug,
+    path: _path,
+    branch,
+    baseRef,
+    ...facts
+  } = request;
+  const keepLocalBranchName =
+    branch !== request.headRef ||
+    ((original.kind === "checkout-change-request" || original.kind === "checkout-github-pr") &&
+      original.localBranchName !== undefined);
+  return {
+    ...facts,
+    ...(keepLocalBranchName ? { localBranchName: branch } : {}),
+    baseRefName: baseRef,
+  };
+}
+
 async function resolveForge(
   repoRoot: string,
   deps: CreateWorktreeCoreDeps,
diff --git a/packages/server/src/server/worktree-session.test.ts b/packages/server/src/server/worktree-session.test.ts
index d462a2605a..845e8e0a75 100644
--- a/packages/server/src/server/worktree-session.test.ts
+++ b/packages/server/src/server/worktree-session.test.ts
@@ -212,13 +212,7 @@ function createTerminalManagerStub(options?: {
             id: `terminal-${terminals.length + 1}`,
             name: input.name ?? "Terminal",
             cwd: input.cwd,
-            getState: () => ({
-              rows: 1,
-              cols: 1,
-              scrollback: [[{ char: "$" }]],
-              grid: [],
-              cursor: { row: 0, col: 0 },
-            }),
+            hasOutput: () => true,
             subscribe: () => () => {},
             onExit: () => () => {},
             onCommandFinished: () => () => {},
@@ -337,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);
@@ -483,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[]> => [],
   };
 }
 
@@ -556,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 () => {},
@@ -606,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/server/worktree-session.ts b/packages/server/src/server/worktree-session.ts
index 4ba1010bd3..1cbad931eb 100644
--- a/packages/server/src/server/worktree-session.ts
+++ b/packages/server/src/server/worktree-session.ts
@@ -554,7 +554,7 @@ export async function runWorktreeSetupInBackground(
         emitSetupProgress("completed", null);
       } else {
         const workspaceCwd = options.workspaceCwd ?? worktree.worktreePath;
-        const setupCommands = getWorktreeSetupCommands(workspaceCwd);
+        const setupCommands = await getWorktreeSetupCommands(workspaceCwd);
         const runtimeEnv = await resolveWorktreeRuntimeEnv({
           worktreePath: worktree.worktreePath,
           branchName: worktree.branchName,
diff --git a/packages/server/src/server/worktree/commands.ts b/packages/server/src/server/worktree/commands.ts
index 0aab346984..4382e46633 100644
--- a/packages/server/src/server/worktree/commands.ts
+++ b/packages/server/src/server/worktree/commands.ts
@@ -1,6 +1,6 @@
-import { join } from "node:path";
+import { basename } from "node:path";
 
-import { getPaseoWorktreesRoot, isPaseoOwnedWorktreeCwd } from "../../utils/worktree.js";
+import { isPaseoOwnedWorktreeCwd } from "../../utils/worktree.js";
 import {
   archiveByScope,
   resolveWorkspaceIdAtPath,
@@ -208,10 +208,18 @@ async function resolveWorktreeSlugPath(
   repoRoot: string,
   worktreeSlug: string,
 ): Promise<string> {
-  const worktreesRoot = await getPaseoWorktreesRoot(
-    repoRoot,
-    dependencies.paseoHome,
-    dependencies.paseoWorktreesBaseRoot,
-  );
-  return join(worktreesRoot, worktreeSlug);
+  // Worktrees can live anywhere (legacy root or wherever
+  // a plugin placed them), so a slug resolves against the
+  // discovered worktree list for the repo, never a guessed path.
+  const worktrees = await dependencies.workspaceGitService.listWorktrees(repoRoot);
+  const match = worktrees.find((entry) => basename(entry.path) === worktreeSlug);
+  if (!match) {
+    const found = worktrees.map((entry) => basename(entry.path));
+    throw new Error(
+      found.length > 0
+        ? `Paseo worktree not found for slug ${worktreeSlug}: found ${found.join(", ")}`
+        : `Paseo worktree not found for slug ${worktreeSlug}`,
+    );
+  }
+  return match.path;
 }
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/agent-hooks/terminal-agent-hook-setting.test.ts b/packages/server/src/terminal/agent-hooks/terminal-agent-hook-setting.test.ts
index aa9e8e01dc..eaa306c185 100644
--- a/packages/server/src/terminal/agent-hooks/terminal-agent-hook-setting.test.ts
+++ b/packages/server/src/terminal/agent-hooks/terminal-agent-hook-setting.test.ts
@@ -80,7 +80,7 @@ describe("applyTerminalAgentHookSetting", () => {
     expect(existsSync(paths.opencode)).toBe(true);
   });
 
-  it("installs on enable and removes hooks on disable when toggled live", () => {
+  it("installs on enable and removes hooks on disable when toggled live", async () => {
     const root = createTempDir("paseo-hook-setting-");
     const store = createStore(createTempDir("paseo-hook-setting-home-"), false);
     const paths = hookPaths(root);
@@ -88,11 +88,11 @@ describe("applyTerminalAgentHookSetting", () => {
     applyTerminalAgentHookSetting({ store, install: createInstallEnv(root) });
     expect(existsSync(paths.opencode)).toBe(false);
 
-    store.patch({ enableTerminalAgentHooks: true });
+    await store.patch({ enableTerminalAgentHooks: true });
     expect(existsSync(paths.codex)).toBe(true);
     expect(existsSync(paths.opencode)).toBe(true);
 
-    store.patch({ enableTerminalAgentHooks: false });
+    await store.patch({ enableTerminalAgentHooks: false });
     expect(existsSync(paths.opencode)).toBe(false);
   });
 });
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/paseo-cli-path.ts b/packages/server/src/terminal/paseo-cli-path.ts
new file mode 100644
index 0000000000..18dff56f1b
--- /dev/null
+++ b/packages/server/src/terminal/paseo-cli-path.ts
@@ -0,0 +1,83 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve as resolvePath } from "node:path";
+
+// Where the Paseo CLI lives, for the PATH entry and PASEO_HOOK_CLI every terminal gets. Kept
+// apart from terminal.ts so the daemon can resolve it without loading node-pty.
+
+const require = createRequire(import.meta.url);
+const PASEO_CLI_BIN_ENTRY = "@getpaseo/cli/bin/paseo";
+
+export function resolveExternalProcessPath(filePath: string): string {
+  return filePath.replace(/\.asar(?=[/\\]|$)/, ".asar.unpacked");
+}
+
+export function resolvePaseoCliBinDir(): string | null {
+  const cliExecutable = resolvePaseoCliExecutablePath();
+  return cliExecutable ? dirname(cliExecutable) : null;
+}
+
+export function resolvePaseoCliExecutablePath(): string | null {
+  const configuredCli = process.env.PASEO_CLI?.trim();
+  if (configuredCli) {
+    return resolvePath(configuredCli);
+  }
+
+  const cliEntrypoint = resolvePaseoCliBinEntrypoint();
+  if (!cliEntrypoint) {
+    return null;
+  }
+
+  const externalCliEntrypoint = resolveExternalProcessPath(cliEntrypoint);
+  const npmBinDir = findNpmBinDir(dirname(externalCliEntrypoint));
+  if (npmBinDir) {
+    const shim = resolvePaseoCliShim(npmBinDir);
+    if (shim) {
+      return shim;
+    }
+  }
+
+  return externalCliEntrypoint;
+}
+
+function resolvePaseoCliBinEntrypoint(): string | null {
+  try {
+    return require.resolve(PASEO_CLI_BIN_ENTRY);
+  } catch {
+    return null;
+  }
+}
+
+function findNpmBinDir(startPath: string): string | null {
+  let current = startPath;
+  while (true) {
+    const candidate = join(current, "node_modules", ".bin");
+    if (hasPaseoCliShim(candidate)) {
+      return candidate;
+    }
+
+    const parent = dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+function hasPaseoCliShim(binDir: string): boolean {
+  return resolvePaseoCliShim(binDir) !== null;
+}
+
+function resolvePaseoCliShim(binDir: string): string | null {
+  for (const name of paseoCliShimNames()) {
+    const candidate = join(binDir, name);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function paseoCliShimNames(): string[] {
+  return process.platform === "win32" ? ["paseo.cmd", "paseo.exe", "paseo"] : ["paseo"];
+}
diff --git a/packages/server/src/terminal/terminal-capture.ts b/packages/server/src/terminal/terminal-capture.ts
index e22d3b6f69..4f8a0f4625 100644
--- a/packages/server/src/terminal/terminal-capture.ts
+++ b/packages/server/src/terminal/terminal-capture.ts
@@ -1,6 +1,5 @@
 import stripAnsi from "strip-ansi";
-import type { TerminalCell } from "@getpaseo/protocol/messages";
-import type { TerminalSession } from "./terminal.js";
+import type { IBuffer } from "@xterm/headless";
 
 export interface CaptureTerminalLinesOptions {
   start?: number;
@@ -13,14 +12,6 @@ export interface CaptureTerminalLinesResult {
   totalLines: number;
 }
 
-function cellsToPlainText(cells: TerminalCell[], options: { stripAnsi: boolean }): string {
-  const text = cells
-    .map((cell) => cell.char)
-    .join("")
-    .trimEnd();
-  return options.stripAnsi ? stripAnsi(text) : text;
-}
-
 function resolveCaptureLineIndex(
   lineNumber: number | undefined,
   totalLines: number,
@@ -46,14 +37,10 @@ function resolveCaptureLineIndex(
 }
 
 export function captureTerminalLines(
-  terminal: TerminalSession,
+  buffer: IBuffer,
   options: CaptureTerminalLinesOptions = {},
 ): CaptureTerminalLinesResult {
-  const state = terminal.getState();
-  const allLines = [...state.scrollback, ...state.grid].map((cells) =>
-    cellsToPlainText(cells, { stripAnsi: options.stripAnsi ?? true }),
-  );
-  const totalLines = allLines.length;
+  const totalLines = buffer.length;
   const startIndex = resolveCaptureLineIndex(options.start, totalLines, "start");
   const endIndex = resolveCaptureLineIndex(options.end, totalLines, "end");
 
@@ -64,8 +51,10 @@ export function captureTerminalLines(
     };
   }
 
-  return {
-    lines: allLines.slice(startIndex, endIndex + 1),
-    totalLines,
-  };
+  const lines: string[] = [];
+  for (let row = startIndex; row <= endIndex; row++) {
+    const text = buffer.getLine(row)!.translateToString(true).trimEnd();
+    lines.push(options.stripAnsi === false ? text : stripAnsi(text));
+  }
+  return { lines, totalLines };
 }
diff --git a/packages/server/src/terminal/terminal-manager-factory.ts b/packages/server/src/terminal/terminal-manager-factory.ts
deleted file mode 100644
index 88dcc2d692..0000000000
--- a/packages/server/src/terminal/terminal-manager-factory.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-import type { TerminalManager } from "./terminal-manager.js";
-import { createWorkerTerminalManager } from "./worker-terminal-manager.js";
-
-export interface ConfiguredTerminalManagerOptions {
-  getTerminalActivityUrl?: () => string | null;
-}
-
-export function createConfiguredTerminalManager(
-  options: ConfiguredTerminalManagerOptions = {},
-): TerminalManager {
-  return createWorkerTerminalManager(options);
-}
diff --git a/packages/server/src/terminal/terminal-manager.test.ts b/packages/server/src/terminal/terminal-manager.test.ts
index 47905d1424..83ba035c37 100644
--- a/packages/server/src/terminal/terminal-manager.test.ts
+++ b/packages/server/src/terminal/terminal-manager.test.ts
@@ -457,7 +457,6 @@ it("setTerminalTitle returns false for unknown terminal ids without changing exi
 
   expect(manager.setTerminalTitle("unknown-id", "x")).toBe(false);
   expect(session.getTitle()).toBe("Existing title");
-  expect(session.getState().title).toBe("Existing title");
   expect(snapshots).toEqual([]);
 
   unsubscribe();
diff --git a/packages/server/src/terminal/terminal-manager.ts b/packages/server/src/terminal/terminal-manager.ts
index df4ced389b..f8ba1851fa 100644
--- a/packages/server/src/terminal/terminal-manager.ts
+++ b/packages/server/src/terminal/terminal-manager.ts
@@ -1,11 +1,16 @@
+import {
+  replayTerminal,
+  type TerminalReplaySink,
+  type TerminalReplayMetadata,
+  type TerminalReplayOptions,
+} from "./terminal-replay.js";
 import {
   createTerminal,
+  type LocalTerminalSession,
   type TerminalActivityTransition,
   type TerminalSession,
-  type TerminalStateSnapshot,
-  type TerminalStateSnapshotOptions,
 } from "./terminal.js";
-import { captureTerminalLines, type CaptureTerminalLinesResult } from "./terminal-capture.js";
+import { type CaptureTerminalLinesResult } from "./terminal-capture.js";
 import { randomBytes, randomUUID } from "node:crypto";
 import { resolve, sep } from "node:path";
 import { assertAbsolutePath, isSameOrDescendantPath } from "../server/path-utils.js";
@@ -50,6 +55,11 @@ export type TerminalWorkspaceContributionChangedListener = (
 ) => void;
 
 export interface TerminalManager {
+  /**
+   * Set when this host's terminals cannot be served at all (a worker from a newer Paseo holds
+   * them). Callers that answer terminal requests report it instead of an empty list.
+   */
+  getUnavailableError?(): Error | null;
   getTerminals(cwd: string, options?: { workspaceId?: string }): Promise<TerminalSession[]>;
   createTerminal(options: {
     id?: string;
@@ -64,14 +74,17 @@ export interface TerminalManager {
     cols?: number;
     activityToken?: string;
     activityUrl?: string | null;
+    baseEnv?: Record<string, string>;
+    paseoCliPath?: string | null;
   }): Promise<TerminalSession>;
   registerCwdEnv(options: { cwd: string; env: Record<string, string> }): void;
   validateTerminalActivityToken(terminalId: string, token: string): "valid" | "unknown" | "invalid";
   getTerminal(id: string): TerminalSession | undefined;
-  getTerminalState(
+  replayTerminal(
     id: string,
-    options?: TerminalStateSnapshotOptions,
-  ): Promise<TerminalStateSnapshot | null>;
+    options: TerminalReplayOptions | undefined,
+    sink: TerminalReplaySink,
+  ): Promise<TerminalReplayMetadata | null>;
   setTerminalTitle(id: string, title: string): boolean;
   setTerminalActivity(id: string, state: TerminalActivityState): Promise<boolean>;
   clearTerminalAttention(id: string): Promise<boolean>;
@@ -97,15 +110,25 @@ export interface TerminalManagerOptions {
   getTerminalActivityUrl?: () => string | null;
 }
 
+/** The in-process manager the terminal worker runs: it owns each PTY, so it knows its pid. */
+export interface LocalTerminalManager extends TerminalManager {
+  createTerminal(
+    options: Parameters<TerminalManager["createTerminal"]>[0],
+  ): Promise<LocalTerminalSession>;
+  getTerminal(id: string): LocalTerminalSession | undefined;
+  getTerminalProcessId(id: string): number | null;
+  getTerminalActivityToken(id: string): string | null;
+}
+
 function createActivityToken(): string {
   return randomBytes(32).toString("base64url");
 }
 
 export function createTerminalManager(
   managerOptions: TerminalManagerOptions = {},
-): TerminalManager {
+): LocalTerminalManager {
   const terminalsByCwd = new Map<string, TerminalSession[]>();
-  const terminalsById = new Map<string, TerminalSession>();
+  const terminalsById = new Map<string, LocalTerminalSession>();
   const terminalExitUnsubscribeById = new Map<string, () => void>();
   const terminalTitleUnsubscribeById = new Map<string, () => void>();
   const terminalActivityUnsubscribeById = new Map<string, () => void>();
@@ -186,7 +209,7 @@ export function createTerminalManager(
     return bestMatchRoot ? defaultEnvByRootCwd.get(bestMatchRoot) : undefined;
   }
 
-  function registerSession(session: TerminalSession): TerminalSession {
+  function registerSession(session: LocalTerminalSession): LocalTerminalSession {
     terminalsById.set(session.id, session);
     const unsubscribeExit = session.onExit(() => {
       removeSessionById(session.id, { kill: false });
@@ -321,7 +344,9 @@ export function createTerminalManager(
       cols?: number;
       activityToken?: string;
       activityUrl?: string | null;
-    }): Promise<TerminalSession> {
+      baseEnv?: Record<string, string>;
+      paseoCliPath?: string | null;
+    }): Promise<LocalTerminalSession> {
       assertAbsolutePath(options.cwd);
 
       const terminals = terminalsByCwd.get(options.cwd) ?? [];
@@ -341,7 +366,7 @@ export function createTerminalManager(
         ...(terminalActivityUrl ? { PASEO_TERMINAL_ACTIVITY_URL: terminalActivityUrl } : {}),
       };
       terminalActivityTokenById.set(terminalId, activityToken);
-      let session: TerminalSession;
+      let session: LocalTerminalSession;
       try {
         session = registerSession(
           await createTerminal({
@@ -355,6 +380,8 @@ export function createTerminalManager(
             ...(options.rows !== undefined ? { rows: options.rows } : {}),
             ...(options.cols !== undefined ? { cols: options.cols } : {}),
             ...(mergedEnv ? { env: mergedEnv } : {}),
+            ...(options.baseEnv ? { baseEnv: options.baseEnv } : {}),
+            ...(options.paseoCliPath === undefined ? {} : { paseoCliPath: options.paseoCliPath }),
             activityEnv,
           }),
         );
@@ -386,15 +413,21 @@ export function createTerminalManager(
       return expected === token ? "valid" : "invalid";
     },
 
-    getTerminal(id: string): TerminalSession | undefined {
+    getTerminal(id: string): LocalTerminalSession | undefined {
       return terminalsById.get(id);
     },
 
-    async getTerminalState(
-      id: string,
-      options?: TerminalStateSnapshotOptions,
-    ): Promise<TerminalStateSnapshot | null> {
-      return terminalsById.get(id)?.getStateSnapshot(options) ?? null;
+    getTerminalProcessId(id: string): number | null {
+      return terminalsById.get(id)?.pid ?? null;
+    },
+
+    getTerminalActivityToken(id: string): string | null {
+      return terminalActivityTokenById.get(id) ?? null;
+    },
+
+    async replayTerminal(id, options, sink) {
+      const session = terminalsById.get(id);
+      return session ? replayTerminal(session, options, sink) : null;
     },
 
     setTerminalTitle(id: string, title: string): boolean {
@@ -456,7 +489,7 @@ export function createTerminalManager(
           totalLines: 0,
         };
       }
-      return captureTerminalLines(session, options);
+      return session.captureLines(options);
     },
 
     listDirectories(): string[] {
diff --git a/packages/server/src/terminal/terminal-replay.ts b/packages/server/src/terminal/terminal-replay.ts
new file mode 100644
index 0000000000..73336a88f1
--- /dev/null
+++ b/packages/server/src/terminal/terminal-replay.ts
@@ -0,0 +1,135 @@
+import type { FramedSocket } from "./terminal-worker-frames.js";
+import type {
+  TerminalWorkerRequest,
+  TerminalWorkerToParentMessage,
+} from "./terminal-worker-protocol.js";
+import type { LocalTerminalSession } from "./terminal.js";
+
+export interface TerminalReplayOptions {
+  scrollbackLines?: number;
+}
+
+export interface TerminalReplayMetadata {
+  rows: number;
+  cols: number;
+  retainedHistoryLines: number;
+  revision: number;
+  replayPreamble: string;
+}
+export type TerminalReplayEvent =
+  | { type: "begin"; metadata: TerminalReplayMetadata }
+  | { type: "data"; data: Uint8Array }
+  | { type: "end" };
+export type TerminalReplaySink = (event: TerminalReplayEvent) => void;
+export const TERMINAL_REPLAY_CHUNK_BYTES = 64 * 1024;
+
+export function* createTerminalReplay(
+  session: LocalTerminalSession,
+  options: TerminalReplayOptions | undefined,
+): Generator<TerminalReplayEvent, TerminalReplayMetadata> {
+  const { metadata, data } = session.serializeReplay(options);
+  yield { type: "begin", metadata };
+  for (let offset = 0; offset < data.length; offset += TERMINAL_REPLAY_CHUNK_BYTES) {
+    yield { type: "data", data: data.subarray(offset, offset + TERMINAL_REPLAY_CHUNK_BYTES) };
+  }
+  yield { type: "end" };
+  return metadata;
+}
+
+export async function replayTerminal(
+  session: LocalTerminalSession,
+  options: TerminalReplayOptions | undefined,
+  sink: TerminalReplaySink,
+): Promise<TerminalReplayMetadata> {
+  const replay = createTerminalReplay(session, options);
+  let next = replay.next();
+  while (!next.done) {
+    sink(next.value);
+    next = replay.next();
+  }
+  return next.value;
+}
+
+interface TerminalReplayPorts {
+  getSession(id: string): LocalTerminalSession | undefined;
+  flushOutput(id: string): void;
+}
+
+/** Worker-owned ANSI capture and paced delivery; live observations never wait for a replay. */
+export function createTerminalReplayController(ports: TerminalReplayPorts) {
+  let controller: FramedSocket | null = null;
+
+  function sendToController(message: TerminalWorkerToParentMessage): void {
+    // A stalled physical controller is different from a stalled viewer: all its
+    // observations must reconnect to the surviving worker after this socket closes.
+    if (controller && controller.socket.writableLength > 4 * 1024 * 1024) {
+      controller.socket.destroy();
+      return;
+    }
+    controller?.send(message);
+  }
+
+  async function deliverReplay(
+    connection: FramedSocket,
+    message: Extract<TerminalWorkerRequest, { type: "replayTerminal" }>,
+  ): Promise<void> {
+    ports.flushOutput(message.terminalId);
+    const session = ports.getSession(message.terminalId);
+    if (!session) {
+      await connection.sendAndWait({
+        type: "response",
+        requestId: message.requestId,
+        ok: true,
+        result: null,
+      });
+      return;
+    }
+    // Flush and capture share one synchronous turn. Each daemon viewer buffers
+    // its own live tail and discards revisions already included in this cut.
+    const replay = createTerminalReplay(session, message.options);
+    let next = replay.next();
+    while (!next.done) {
+      if (controller !== connection) throw new Error("Terminal replay controller disconnected");
+      await connection.sendAndWait({
+        type: "terminalReplay",
+        requestId: message.requestId,
+        event: next.value,
+      });
+      next = replay.next();
+    }
+    await connection.sendAndWait({
+      type: "response",
+      requestId: message.requestId,
+      ok: true,
+      result: next.value,
+    });
+  }
+
+  return {
+    setConnection(connection: FramedSocket | null): void {
+      if (controller === connection) return;
+      const previous = controller;
+      controller = connection;
+      previous?.socket.destroy();
+    },
+    send: sendToController,
+    async replay(
+      request: Extract<TerminalWorkerRequest, { type: "replayTerminal" }>,
+    ): Promise<void> {
+      const connection = controller;
+      if (!connection) return;
+      try {
+        await deliverReplay(connection, request);
+      } catch (error) {
+        await connection
+          .sendAndWait({
+            type: "response",
+            requestId: request.requestId,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+          })
+          .catch(() => {});
+      }
+    },
+  };
+}
diff --git a/packages/server/src/terminal/terminal-restore.test.ts b/packages/server/src/terminal/terminal-restore.test.ts
index 7255cba1a5..ad008e1bd7 100644
--- a/packages/server/src/terminal/terminal-restore.test.ts
+++ b/packages/server/src/terminal/terminal-restore.test.ts
@@ -4,56 +4,45 @@ import {
   TerminalStreamOpcode,
   decodeTerminalStreamFrame,
 } from "@getpaseo/protocol/binary-frames/index";
-import type { TerminalCell, TerminalState } from "@getpaseo/protocol/messages";
 import {
+  createTerminalRestoreDelivery,
   encodeTerminalRestoreFrame,
   resolveRestoreAfterOutputOverflow,
   resolveTerminalRestoreSnapshotOptions,
-  resolveTerminalSubscriptionSnapshotMode,
 } from "./terminal-restore.js";
 
-function terminalRow(text: string, cols = 80): TerminalCell[] {
-  return Array.from({ length: cols }, (_, index) => ({
-    char: text[index] ?? " ",
-  }));
-}
-
-function terminalState(text: string): TerminalState {
-  return {
-    rows: 1,
-    cols: 80,
-    grid: [terminalRow(text)],
-    scrollback: [],
-    cursor: { row: 0, col: text.length },
-  };
-}
-
 describe("terminal restore policy", () => {
-  test("uses ready snapshots only for restore-aware subscriptions", () => {
-    expect(resolveTerminalSubscriptionSnapshotMode(undefined)).toBe("state");
-    expect(resolveTerminalSubscriptionSnapshotMode({ mode: "live" })).toBe("ready");
-  });
-
   test("resolves bounded restore snapshot options", () => {
-    expect(resolveTerminalRestoreSnapshotOptions({ mode: "live" })).toBeNull();
-    expect(resolveTerminalRestoreSnapshotOptions({ mode: "full-snapshot" })).toBeUndefined();
-    expect(resolveTerminalRestoreSnapshotOptions({ mode: "visible-snapshot" })).toEqual({
+    expect(
+      resolveTerminalRestoreSnapshotOptions({ restore: { mode: "live" }, chunked: false }),
+    ).toBeNull();
+    expect(
+      resolveTerminalRestoreSnapshotOptions({ restore: { mode: "full-snapshot" }, chunked: false }),
+    ).toBeUndefined();
+    expect(
+      resolveTerminalRestoreSnapshotOptions({
+        restore: { mode: "visible-snapshot" },
+        chunked: false,
+      }),
+    ).toEqual({
       scrollbackLines: 200,
     });
     expect(
       resolveTerminalRestoreSnapshotOptions({
-        mode: "visible-snapshot",
-        scrollbackLines: 999,
+        restore: { mode: "visible-snapshot", scrollbackLines: 999 },
+        chunked: false,
       }),
     ).toEqual({ scrollbackLines: 500 });
   });
 
-  test("promotes live restore to visible restore after output overflow", () => {
+  test("bounds pressure recovery for every restore mode", () => {
     expect(resolveRestoreAfterOutputOverflow({ mode: "live" })).toEqual({
       mode: "visible-snapshot",
+      scrollbackLines: 500,
     });
     expect(resolveRestoreAfterOutputOverflow({ mode: "full-snapshot" })).toEqual({
-      mode: "full-snapshot",
+      mode: "visible-snapshot",
+      scrollbackLines: 500,
     });
   });
 
@@ -61,10 +50,7 @@ describe("terminal restore policy", () => {
     const frame = decodeTerminalStreamFrame(
       encodeTerminalRestoreFrame({
         slot: 4,
-        snapshot: {
-          state: terminalState("restored"),
-          revision: 1,
-        },
+        data: new TextEncoder().encode("restored"),
       }),
     );
 
@@ -73,3 +59,40 @@ describe("terminal restore policy", () => {
     expect(new TextDecoder().decode(frame?.payload ?? new Uint8Array())).toContain("restored");
   });
 });
+
+test("projects chunked replay begin onto the declared wire metadata", () => {
+  const frames: Uint8Array[] = [];
+  const deliver = createTerminalRestoreDelivery({
+    slot: 7,
+    chunked: true,
+    send: (frame) => {
+      frames.push(frame);
+    },
+  });
+  deliver({
+    type: "begin",
+    metadata: {
+      rows: 30,
+      cols: 120,
+      retainedHistoryLines: 842,
+      revision: 5123,
+      replayPreamble: "\x1b[?2004h",
+    },
+  });
+  const data = new TextEncoder().encode("\x1b[31m界 replay\x1b[0m");
+  deliver({ type: "data", data });
+  deliver({ type: "end" });
+  const decoded = frames.map((frame) => decodeTerminalStreamFrame(frame)!);
+  expect(decoded.map((frame) => ({ slot: frame.slot, opcode: frame.opcode }))).toEqual([
+    { slot: 7, opcode: TerminalStreamOpcode.ReplayBegin },
+    { slot: 7, opcode: TerminalStreamOpcode.ReplayData },
+    { slot: 7, opcode: TerminalStreamOpcode.ReplayEnd },
+  ]);
+  expect(JSON.parse(new TextDecoder().decode(decoded[0]!.payload))).toEqual({
+    rows: 30,
+    cols: 120,
+    retainedHistoryLines: 842,
+  });
+  expect(decoded[1]!.payload).toEqual(data);
+  expect(decoded[2]!.payload.byteLength).toBe(0);
+});
diff --git a/packages/server/src/terminal/terminal-restore.ts b/packages/server/src/terminal/terminal-restore.ts
index ffc1bd9faa..c0ee7b1105 100644
--- a/packages/server/src/terminal/terminal-restore.ts
+++ b/packages/server/src/terminal/terminal-restore.ts
@@ -1,11 +1,11 @@
+import type { z } from "zod";
 import type { SubscribeTerminalRequest } from "@getpaseo/protocol/messages";
 import {
   TerminalStreamOpcode,
-  encodeTerminalSnapshotPayload,
+  type TerminalReplayMetadataSchema,
   encodeTerminalStreamFrame,
 } from "@getpaseo/protocol/binary-frames/index";
-import { renderTerminalSnapshotToAnsi } from "@getpaseo/protocol/terminal-snapshot";
-import type { TerminalStateSnapshot, TerminalStateSnapshotOptions } from "./terminal.js";
+import type { TerminalReplaySink, TerminalReplayOptions } from "./terminal-replay.js";
 
 export const MAX_TERMINAL_OUTPUT_FRAME_BYTES = 256 * 1024;
 
@@ -21,62 +21,84 @@ const MAX_VISIBLE_RESTORE_SCROLLBACK_LINES = 500;
 
 export type TerminalRestoreOptions = NonNullable<SubscribeTerminalRequest["restore"]>;
 
-export type TerminalSubscriptionSnapshotMode = "state" | "ready";
-
-export function resolveTerminalSubscriptionSnapshotMode(
-  restore: TerminalRestoreOptions | undefined,
-): TerminalSubscriptionSnapshotMode {
-  return restore ? "ready" : "state";
-}
-
 export function resolveRestoreAfterOutputOverflow(
   restore: TerminalRestoreOptions | undefined,
-): TerminalRestoreOptions | undefined {
-  if (restore?.mode === "live") {
-    return { mode: "visible-snapshot" };
-  }
-  return restore;
+): TerminalRestoreOptions {
+  return {
+    mode: "visible-snapshot",
+    scrollbackLines: Math.min(
+      restore?.scrollbackLines ?? MAX_VISIBLE_RESTORE_SCROLLBACK_LINES,
+      MAX_VISIBLE_RESTORE_SCROLLBACK_LINES,
+    ),
+  };
 }
 
-export function resolveTerminalRestoreSnapshotOptions(
-  restore: TerminalRestoreOptions,
-): TerminalStateSnapshotOptions | null | undefined {
+export function resolveTerminalRestoreSnapshotOptions({
+  restore,
+  chunked,
+}: {
+  restore: TerminalRestoreOptions;
+  chunked: boolean;
+}): TerminalReplayOptions | null | undefined {
   if (restore.mode === "live") {
     return null;
   }
-  if (restore.mode === "visible-snapshot") {
-    return {
-      scrollbackLines: resolveVisibleRestoreScrollbackLines(restore.scrollbackLines),
-    };
+  if (restore.mode === "full-snapshot") {
+    return chunked ? { scrollbackLines: restore.scrollbackLines } : undefined;
   }
-  return undefined;
+  const scrollbackLines = restore.scrollbackLines ?? DEFAULT_VISIBLE_RESTORE_SCROLLBACK_LINES;
+  return {
+    scrollbackLines: chunked
+      ? scrollbackLines
+      : Math.min(scrollbackLines, MAX_VISIBLE_RESTORE_SCROLLBACK_LINES),
+  };
 }
 
-export function encodeLegacyTerminalSnapshotFrame(input: {
-  slot: number;
-  snapshot: TerminalStateSnapshot;
-}): Uint8Array {
-  return encodeTerminalStreamFrame({
-    opcode: TerminalStreamOpcode.Snapshot,
-    slot: input.slot,
-    payload: encodeTerminalSnapshotPayload(input.snapshot.state),
-  });
-}
-
-export function encodeTerminalRestoreFrame(input: {
-  slot: number;
-  snapshot: TerminalStateSnapshot;
-}): Uint8Array {
+export function encodeTerminalRestoreFrame(input: { slot: number; data: Uint8Array }): Uint8Array {
   return encodeTerminalStreamFrame({
     opcode: TerminalStreamOpcode.Restore,
     slot: input.slot,
-    payload: renderTerminalSnapshotToAnsi(input.snapshot.state),
+    payload: input.data,
   });
 }
 
-function resolveVisibleRestoreScrollbackLines(value: number | undefined): number {
-  if (typeof value !== "number") {
-    return DEFAULT_VISIBLE_RESTORE_SCROLLBACK_LINES;
-  }
-  return Math.min(Math.max(0, value), MAX_VISIBLE_RESTORE_SCROLLBACK_LINES);
+/** The daemon's only old-app adapter. Capable delivery never assembles the replay. */
+export function createTerminalRestoreDelivery(input: {
+  slot: number;
+  chunked: boolean;
+  send(frame: Uint8Array): void;
+}): TerminalReplaySink {
+  // COMPAT(terminalSingleRestore): added after v0.14.0; remove after 2027-04-30 when client floor supports chunked replay.
+  const legacyChunks: Uint8Array[] = [];
+  return (event) => {
+    if (!input.chunked) {
+      if (event.type === "data") legacyChunks.push(event.data);
+      if (event.type === "end")
+        input.send(
+          encodeTerminalRestoreFrame({
+            slot: input.slot,
+            data: Buffer.concat(legacyChunks),
+          }),
+        );
+      return;
+    }
+    const opcodes = {
+      begin: TerminalStreamOpcode.ReplayBegin,
+      data: TerminalStreamOpcode.ReplayData,
+      end: TerminalStreamOpcode.ReplayEnd,
+    };
+    let payload: string | Uint8Array | undefined;
+    if (event.type === "begin") {
+      const begin = {
+        rows: event.metadata.rows,
+        cols: event.metadata.cols,
+        retainedHistoryLines: event.metadata.retainedHistoryLines,
+      } satisfies z.infer<typeof TerminalReplayMetadataSchema>;
+      payload = JSON.stringify(begin);
+    }
+    if (event.type === "data") payload = event.data;
+    input.send(
+      encodeTerminalStreamFrame({ slot: input.slot, opcode: opcodes[event.type], payload }),
+    );
+  };
 }
diff --git a/packages/server/src/terminal/terminal-serializer.ts b/packages/server/src/terminal/terminal-serializer.ts
new file mode 100644
index 0000000000..5f79064948
--- /dev/null
+++ b/packages/server/src/terminal/terminal-serializer.ts
@@ -0,0 +1,42 @@
+import type { Terminal as TerminalType } from "@xterm/headless";
+import { SerializeAddon } from "@xterm/addon-serialize";
+import type { TerminalReplayOptions } from "./terminal-replay.js";
+
+/** Serialize the owned model; the PTY is a transport, not an ANSI parser oracle. */
+export function createTerminalSerializer(
+  terminal: TerminalType,
+): (options?: TerminalReplayOptions) => Uint8Array {
+  const addon = new SerializeAddon();
+  terminal.loadAddon(addon);
+  return (options) => {
+    const data = addon.serialize({ scrollback: options?.scrollbackLines });
+    const buffer = terminal.buffer.active;
+    // Addon 0.14 applies a horizontal offset after vertical movement has already
+    // clamped a pending-wrap column, losing a column. Restore a valid position
+    // 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");
+  };
+}
+
+// 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 {
+  const core = (
+    terminal as unknown as {
+      _core: {
+        coreService: {
+          isCursorHidden: boolean;
+          decPrivateModes: { cursorStyle?: "block" | "underline" | "bar"; cursorBlink?: boolean };
+        };
+      };
+    }
+  )._core.coreService;
+  const visibility = `\x1b[?25${core.isCursorHidden ? "l" : "h"}`;
+  const cursorStyle = core.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`;
+}
diff --git a/packages/server/src/terminal/terminal-session-controller.test.ts b/packages/server/src/terminal/terminal-session-controller.test.ts
index b438af8381..d91eae6f06 100644
--- a/packages/server/src/terminal/terminal-session-controller.test.ts
+++ b/packages/server/src/terminal/terminal-session-controller.test.ts
@@ -1,3 +1,6 @@
+import type { TerminalReplayOptions } from "./terminal-replay.js";
+import type { TerminalRestoreOptions } from "./terminal-restore.js";
+import type { TerminalReplayMetadata } from "./terminal-replay.js";
 import { describe, expect, test, vi } from "vitest";
 import pino from "pino";
 
@@ -7,8 +10,7 @@ import {
   decodeTerminalStreamFrame,
   type TerminalStreamFrame,
 } from "@getpaseo/protocol/binary-frames/index";
-import type { TerminalCell, TerminalState } from "@getpaseo/protocol/messages";
-import type { ServerMessage, TerminalSession, TerminalStateSnapshot } from "./terminal.js";
+import type { ServerMessage, TerminalSession } from "./terminal.js";
 import {
   TerminalSessionController,
   type TerminalSessionControllerOptions,
@@ -17,9 +19,35 @@ import { SessionDelivery } from "../server/session/owned-subscriptions/index.js"
 import type { TerminalManager, TerminalsChangedEvent } from "./terminal-manager.js";
 import { isSameOrDescendantPath } from "../server/path-utils.js";
 import { PluginSessionSocket } from "../server/plugins/session-socket.js";
+import { TerminalWorkerIncompatibleError } from "./terminal-worker-pool.js";
+
+interface ReplayFixture {
+  data: Uint8Array;
+  metadata: TerminalReplayMetadata;
+}
+function terminalReplay(text: string, revision: number, replayPreamble = ""): ReplayFixture {
+  return {
+    data: Buffer.from(text),
+    metadata: { rows: 1, cols: 80, retainedHistoryLines: 0, revision, replayPreamble },
+  };
+}
+function replayFixture(
+  read: () => Promise<ReplayFixture | null>,
+): TerminalManager["replayTerminal"] {
+  return async (_id, _options, sink) => {
+    const replay = await read();
+    if (!replay) return null;
+    await sink({ type: "begin", metadata: replay.metadata });
+    await sink({ type: "data", data: replay.data });
+    await sink({ type: "end" });
+    return replay.metadata;
+  };
+}
 
 function createController(
-  options: TerminalSessionControllerOptions & { emitBinary(frame: Uint8Array): void },
+  options: TerminalSessionControllerOptions & {
+    emitBinary(frame: Uint8Array): void | Promise<void>;
+  },
 ) {
   const source = {};
   const ownership = new SessionDelivery(
@@ -58,22 +86,6 @@ function deferred<T>(): {
   return { promise, resolve, reject };
 }
 
-function terminalRow(text: string, cols = 80): TerminalCell[] {
-  return Array.from({ length: cols }, (_, index) => ({
-    char: text[index] ?? " ",
-  }));
-}
-
-function terminalState(text: string): TerminalState {
-  return {
-    rows: 1,
-    cols: 80,
-    grid: [terminalRow(text)],
-    scrollback: [],
-    cursor: { row: 0, col: text.length },
-  };
-}
-
 function createLogger(): pino.Logger {
   return {
     warn: vi.fn(),
@@ -81,10 +93,14 @@ 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;
-    const snapshot = deferred<TerminalStateSnapshot | null>();
+    const snapshot = deferred<ReplayFixture | null>();
     const binaryFrames: TerminalStreamFrame[] = [];
     const outboundMessages: SessionOutboundMessage[] = [];
     const terminal: TerminalSession = {
@@ -103,8 +119,7 @@ describe("terminal-session-controller restore", () => {
       onTitleChange: () => vi.fn(),
       onActivityChange: () => vi.fn(),
       getSize: () => ({ rows: 1, cols: 80 }),
-      getState: () => terminalState("restore-before"),
-      getStateSnapshot: () => ({ state: terminalState("restore-before"), revision: 1 }),
+      hasOutput: () => true,
       getReplayPreamble: () => "\x1b[?1h\x1b[?2004h",
       getTitle: () => undefined,
       getActivity: () => null,
@@ -120,7 +135,7 @@ describe("terminal-session-controller restore", () => {
       registerCwdEnv: vi.fn(),
       validateTerminalActivityToken: vi.fn(() => "unknown"),
       getTerminal: vi.fn(() => terminal),
-      getTerminalState: vi.fn(() => snapshot.promise),
+      replayTerminal: replayFixture(() => snapshot.promise),
       setTerminalTitle: vi.fn(),
       setTerminalActivity: vi.fn(),
       killTerminal: vi.fn(),
@@ -156,12 +171,15 @@ describe("terminal-session-controller restore", () => {
       },
     });
     await Promise.resolve();
-    expect(terminalManager.getTerminalState).toHaveBeenCalledTimes(1);
+    expect(binaryFrames).toEqual([]);
 
     terminalListener?.({ type: "output", data: "restore-after\n", revision: 2 });
-    snapshot.resolve({ state: terminalState("restore-before"), revision: 1 });
+    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",
@@ -172,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");
   });
 });
 
@@ -201,8 +217,7 @@ function listSession(input: {
     onTitleChange: () => vi.fn(),
     onActivityChange: () => vi.fn(),
     getSize: () => ({ rows: 1, cols: 80 }),
-    getState: () => terminalState(""),
-    getStateSnapshot: () => ({ state: terminalState(""), revision: 0 }),
+    hasOutput: () => true,
     getReplayPreamble: () => "",
     getTitle: () => undefined,
     getActivity: () => null,
@@ -235,7 +250,7 @@ describe("terminal-session-controller legacy terminal creation", () => {
       registerCwdEnv: vi.fn(),
       validateTerminalActivityToken: vi.fn(() => "unknown"),
       getTerminal: vi.fn(),
-      getTerminalState: vi.fn(),
+      replayTerminal: async () => null,
       setTerminalTitle: vi.fn(),
       setTerminalActivity: vi.fn(),
       clearTerminalAttention: vi.fn(),
@@ -310,7 +325,7 @@ describe("terminal-session-controller legacy terminal creation", () => {
       registerCwdEnv: vi.fn(),
       validateTerminalActivityToken: vi.fn(() => "unknown"),
       getTerminal: vi.fn(),
-      getTerminalState: vi.fn(),
+      replayTerminal: async () => null,
       setTerminalTitle: vi.fn(),
       setTerminalActivity: vi.fn(),
       clearTerminalAttention: vi.fn(),
@@ -347,6 +362,76 @@ describe("terminal-session-controller legacy terminal creation", () => {
   });
 });
 
+describe("terminal-session-controller with terminals held by a newer Paseo", () => {
+  const incompatible = new TerminalWorkerIncompatibleError({
+    paseoVersion: "9.9.9",
+    protocolVersion: 7,
+  });
+
+  function incompatibleManager(): TerminalManager {
+    return {
+      getUnavailableError: () => incompatible,
+      getTerminals: vi.fn(async () => Promise.reject(incompatible)),
+      createTerminal: vi.fn(async () => Promise.reject(incompatible)),
+      registerCwdEnv: vi.fn(),
+      validateTerminalActivityToken: vi.fn(() => "unknown"),
+      getTerminal: vi.fn(),
+      replayTerminal: async () => null,
+      setTerminalTitle: vi.fn(),
+      setTerminalActivity: vi.fn(),
+      clearTerminalAttention: vi.fn(),
+      killTerminal: vi.fn(),
+      killTerminalAndWait: vi.fn(),
+      captureTerminal: vi.fn(),
+      // The incompatible worker's terminals are not in this daemon's view.
+      listDirectories: vi.fn(() => []),
+      killAll: vi.fn(),
+      subscribeTerminalsChanged: vi.fn(() => vi.fn()),
+      subscribeTerminalActivity: vi.fn(() => vi.fn()),
+      subscribeTerminalWorkspaceContributionChanged: vi.fn(() => vi.fn()),
+    };
+  }
+
+  test.each([
+    { type: "list_terminals_request" as const, requestId: "req-list" },
+    { type: "list_terminals_request" as const, requestId: "req-list-cwd", cwd: "/work/repo" },
+    {
+      type: "create_terminal_request" as const,
+      requestId: "req-create",
+      cwd: "/work/repo",
+      workspaceId: "ws-1",
+    },
+  ])(
+    "answers $type ($requestId) with a terminal_worker_incompatible rpc_error",
+    async (request) => {
+      const outboundMessages: SessionOutboundMessage[] = [];
+      const controller = createController({
+        terminalManager: incompatibleManager(),
+        emit: (message) => outboundMessages.push(message),
+        emitBinary: vi.fn(),
+        hasBinaryChannel: () => true,
+        isPathWithinRoot: isSameOrDescendantPath,
+        sessionLogger: createLogger(),
+        listTerminalWorkspaceRefs: async () => [{ workspaceId: "ws-1", cwd: "/work/repo" }],
+      });
+
+      await controller.dispatch(request);
+
+      expect(outboundMessages).toEqual([
+        {
+          type: "rpc_error",
+          payload: {
+            requestId: request.requestId,
+            requestType: request.type,
+            error: incompatible.message,
+            code: "terminal_worker_incompatible",
+          },
+        },
+      ]);
+    },
+  );
+});
+
 async function flushMicrotasks(): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, 0));
 }
@@ -357,99 +442,6 @@ async function waitForCoalescerFlush(): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, 30));
 }
 
-describe("terminal-session-controller wrap-flag gating", () => {
-  function setup(clientSupportsWrapReflow?: () => boolean): {
-    controller: ReturnType<typeof createController>;
-    getTerminalState: ReturnType<typeof vi.fn>;
-  } {
-    const terminal: TerminalSession = {
-      id: "term-1",
-      name: "Terminal",
-      cwd: "/tmp",
-      workspaceId: "ws-test",
-      send: vi.fn(),
-      subscribe: (listener) => {
-        queueMicrotask(() => listener({ type: "snapshotReady", revision: 1 }));
-        return vi.fn();
-      },
-      onExit: () => vi.fn(),
-      onCommandFinished: () => vi.fn(),
-      onTitleChange: () => vi.fn(),
-      onActivityChange: () => vi.fn(),
-      getSize: () => ({ rows: 1, cols: 80 }),
-      getState: () => terminalState("hello"),
-      getStateSnapshot: () => ({ state: terminalState("hello"), revision: 1 }),
-      getReplayPreamble: () => "",
-      getTitle: () => undefined,
-      getActivity: () => null,
-      setActivity: vi.fn(),
-      setTitle: vi.fn(),
-      getExitInfo: () => null,
-      kill: vi.fn(),
-      killAndWait: vi.fn(),
-    };
-    const getTerminalState = vi.fn(() =>
-      Promise.resolve<TerminalStateSnapshot>({ state: terminalState("hello"), revision: 1 }),
-    );
-    const terminalManager = {
-      getTerminals: vi.fn(),
-      createTerminal: vi.fn(),
-      registerCwdEnv: vi.fn(),
-      validateTerminalActivityToken: vi.fn(() => "unknown"),
-      getTerminal: vi.fn(() => terminal),
-      getTerminalState,
-      setTerminalTitle: vi.fn(),
-      setTerminalActivity: vi.fn(),
-      killTerminal: vi.fn(),
-      killTerminalAndWait: vi.fn(),
-      captureTerminal: vi.fn(),
-      listDirectories: vi.fn(() => []),
-      killAll: vi.fn(),
-      subscribeTerminalsChanged: vi.fn(() => vi.fn()),
-      subscribeTerminalActivity: vi.fn(() => vi.fn()),
-      subscribeTerminalWorkspaceContributionChanged: vi.fn(() => vi.fn()),
-    } as unknown as TerminalManager;
-    const controller = createController({
-      terminalManager,
-      emit: vi.fn(),
-      emitBinary: vi.fn(),
-      hasBinaryChannel: () => true,
-      isPathWithinRoot: () => false,
-      sessionLogger: createLogger(),
-      ...(clientSupportsWrapReflow ? { clientSupportsWrapReflow } : {}),
-    });
-    return { controller, getTerminalState };
-  }
-
-  async function subscribe(controller: ReturnType<typeof createController>): Promise<void> {
-    await controller.dispatch({
-      type: "subscribe_terminal_request",
-      terminalId: "term-1",
-      requestId: "req-1",
-      restore: { mode: "visible-snapshot", scrollbackLines: 200 },
-    });
-    await flushMicrotasks();
-  }
-
-  test("requests wrap flags when the client supports reflowable snapshots", async () => {
-    const { controller, getTerminalState } = setup(() => true);
-    await subscribe(controller);
-    expect(getTerminalState).toHaveBeenCalledWith(
-      "term-1",
-      expect.objectContaining({ includeWrapFlags: true }),
-    );
-  });
-
-  test("omits wrap flags when the client does not advertise support", async () => {
-    const { controller, getTerminalState } = setup();
-    await subscribe(controller);
-    expect(getTerminalState).toHaveBeenCalledWith(
-      "term-1",
-      expect.objectContaining({ includeWrapFlags: false }),
-    );
-  });
-});
-
 describe("terminal-session-controller subdirectory aggregation", () => {
   test("delivers a subdirectory change to a root subscriber as an aggregated, root-keyed snapshot", async () => {
     const rootCwd = "/work/repo";
@@ -470,7 +462,7 @@ describe("terminal-session-controller subdirectory aggregation", () => {
       registerCwdEnv: vi.fn(),
       validateTerminalActivityToken: vi.fn(() => "unknown"),
       getTerminal: vi.fn(),
-      getTerminalState: vi.fn(),
+      replayTerminal: async () => null,
       setTerminalTitle: vi.fn(),
       setTerminalActivity: vi.fn(),
       killTerminal: vi.fn(),
@@ -538,7 +530,7 @@ describe("terminal-session-controller subdirectory aggregation", () => {
       registerCwdEnv: vi.fn(),
       validateTerminalActivityToken: vi.fn(() => "unknown"),
       getTerminal: vi.fn(),
-      getTerminalState: vi.fn(),
+      replayTerminal: async () => null,
       setTerminalTitle: vi.fn(),
       setTerminalActivity: vi.fn(),
       killTerminal: vi.fn(),
@@ -630,7 +622,7 @@ describe("terminal-session-controller workspace-scoped subscriptions", () => {
       registerCwdEnv: vi.fn(),
       validateTerminalActivityToken: vi.fn(() => "unknown"),
       getTerminal: vi.fn(),
-      getTerminalState: vi.fn(),
+      replayTerminal: async () => null,
       setTerminalTitle: vi.fn(),
       setTerminalActivity: vi.fn(),
       killTerminal: vi.fn(),
@@ -693,9 +685,17 @@ describe("terminal-session-controller workspace-scoped subscriptions", () => {
 });
 
 describe("terminal-session-controller backpressure snapshot fallback", () => {
-  async function setup(getClientBufferedAmount: () => number | null): Promise<{
+  async function setup(
+    getClientBufferedAmount: () => number | null,
+    chunked = false,
+    pace?: () => Promise<void>,
+    restore?: TerminalRestoreOptions,
+  ): Promise<{
+    messages: SessionOutboundMessage[];
     pushOutput: (data: string) => void;
     frames: TerminalStreamFrame[];
+    replayOptions: Array<TerminalReplayOptions | undefined>;
+    ready: () => void;
   }> {
     let terminalListener: ((message: ServerMessage) => void) | null = null;
     const terminal: TerminalSession = {
@@ -706,19 +706,15 @@ describe("terminal-session-controller backpressure snapshot fallback", () => {
       send: vi.fn(),
       subscribe: (listener) => {
         terminalListener = listener;
-        // Legacy stream: a snapshot arrives on subscribe (one Snapshot frame),
-        // after which output streams through the coalescer as Output frames.
-        queueMicrotask(() =>
-          listener({ type: "snapshot", state: terminalState("live"), revision: 1 }),
-        );
+        // Readiness starts ANSI replay; later bytes use Output frames.
+        queueMicrotask(() => listener({ type: "snapshotReady", revision: 1 }));
         return vi.fn();
       },
       onExit: () => vi.fn(),
       onCommandFinished: () => vi.fn(),
       onTitleChange: () => vi.fn(),
       getSize: () => ({ rows: 1, cols: 80 }),
-      getState: () => terminalState("live"),
-      getStateSnapshot: () => ({ state: terminalState("live"), revision: 1 }),
+      hasOutput: () => true,
       getReplayPreamble: () => "",
       getTitle: () => undefined,
       setTitle: vi.fn(),
@@ -726,14 +722,16 @@ describe("terminal-session-controller backpressure snapshot fallback", () => {
       kill: vi.fn(),
       killAndWait: vi.fn(),
     };
-    const terminalManager = {
+    const replayOptions: Array<TerminalReplayOptions | undefined> = [];
+    const terminalManager: TerminalManager = {
       getTerminals: vi.fn(),
       createTerminal: vi.fn(),
       registerCwdEnv: vi.fn(),
       getTerminal: vi.fn(() => terminal),
-      getTerminalState: vi.fn(() =>
-        Promise.resolve<TerminalStateSnapshot>({ state: terminalState("live"), revision: 1 }),
-      ),
+      replayTerminal: (id, options, sink) => {
+        replayOptions.push(options);
+        return replayFixture(async () => terminalReplay("live", 1))(id, options, sink);
+      },
       setTerminalTitle: vi.fn(),
       killTerminal: vi.fn(),
       killTerminalAndWait: vi.fn(),
@@ -741,16 +739,26 @@ describe("terminal-session-controller backpressure snapshot fallback", () => {
       listDirectories: vi.fn(() => []),
       killAll: vi.fn(),
       subscribeTerminalsChanged: vi.fn(() => vi.fn()),
-    } as unknown as TerminalManager;
+      validateTerminalActivityToken: () => "unknown",
+      setTerminalActivity: async () => true,
+      clearTerminalAttention: async () => false,
+      subscribeTerminalActivity: () => () => {},
+      subscribeTerminalWorkspaceContributionChanged: () => () => {},
+    };
 
     const frames: TerminalStreamFrame[] = [];
+    const messages: SessionOutboundMessage[] = [];
     const controller = createController({
       terminalManager,
-      emit: vi.fn(),
+      emit: (message) => {
+        messages.push(message);
+      },
+      supportsChunkedReplay: () => chunked,
       emitBinary: (bytes) => {
         const frame = decodeTerminalStreamFrame(bytes);
         if (frame) {
           frames.push(frame);
+          if (frame.opcode === TerminalStreamOpcode.ReplayBegin) return pace?.();
         }
       },
       hasBinaryChannel: () => true,
@@ -763,6 +771,7 @@ describe("terminal-session-controller backpressure snapshot fallback", () => {
       type: "subscribe_terminal_request",
       terminalId: "term-1",
       requestId: "req-1",
+      restore,
     });
     await waitForCoalescerFlush();
     // Drop the initial subscribe snapshot frame so each test only sees frames
@@ -770,11 +779,83 @@ describe("terminal-session-controller backpressure snapshot fallback", () => {
     frames.length = 0;
 
     return {
+      replayOptions,
+      ready: () => terminalListener?.({ type: "snapshotReady" }),
       pushOutput: (data) => terminalListener?.({ type: "output", data, revision: 2 }),
       frames,
+      messages,
     };
   }
 
+  test.each([false, true])(
+    "preserves visible history defaults and explicit requests across delivery (chunked=%s)",
+    async (chunked) => {
+      const replayOpcodes = chunked
+        ? [
+            TerminalStreamOpcode.ReplayBegin,
+            TerminalStreamOpcode.ReplayData,
+            TerminalStreamOpcode.ReplayEnd,
+          ]
+        : [TerminalStreamOpcode.Restore];
+      for (const [restore, expected] of [
+        [{ mode: "visible-snapshot" }, [{ scrollbackLines: 200 }]],
+        [{ mode: "visible-snapshot", scrollbackLines: 0 }, [{ scrollbackLines: 0 }]],
+        [{ mode: "visible-snapshot", scrollbackLines: 5 }, [{ scrollbackLines: 5 }]],
+        [{ mode: "visible-snapshot", scrollbackLines: 500 }, [{ scrollbackLines: 500 }]],
+        [
+          { mode: "visible-snapshot", scrollbackLines: 10000 },
+          [{ scrollbackLines: chunked ? 10000 : 500 }],
+        ],
+        [{ mode: "full-snapshot" }, [chunked ? { scrollbackLines: undefined } : undefined]],
+        [{ mode: "live" }, []],
+      ] as const) {
+        const fixture = await setup(() => 0, chunked, undefined, restore);
+        expect(fixture.replayOptions).toEqual(expected);
+        fixture.ready();
+        await waitForCoalescerFlush();
+        expect(fixture.replayOptions).toEqual([...expected, ...expected]);
+        expect(fixture.frames.map((frame) => frame.opcode)).toEqual(
+          restore.mode === "live" ? [] : replayOpcodes,
+        );
+        fixture.pushOutput("after-restore");
+        await waitForCoalescerFlush();
+        expect(fixture.frames.at(-1)?.opcode).toBe(TerminalStreamOpcode.Output);
+        expect(new TextDecoder().decode(fixture.frames.at(-1)!.payload)).toBe("after-restore");
+      }
+    },
+  );
+
+  test.each([false, true])(
+    "bounds recovery without changing attach demand (chunked=%s)",
+    async (chunked) => {
+      for (const [restore, history] of [
+        [{ mode: "visible-snapshot" }, 500],
+        [{ mode: "visible-snapshot", scrollbackLines: 10000 }, 500],
+        [{ mode: "full-snapshot" }, 500],
+        [{ mode: "visible-snapshot", scrollbackLines: 5 }, 5],
+        [{ mode: "visible-snapshot", scrollbackLines: 0 }, 0],
+        [{ mode: "full-snapshot", scrollbackLines: 0 }, 0],
+        [{ mode: "live", scrollbackLines: 0 }, 0],
+        [{ mode: "live" }, 500],
+        [undefined, 500],
+      ] as const) {
+        const fixture = await setup(() => 8 * 1024 * 1024, chunked, undefined, restore);
+        const initial = fixture.replayOptions.slice();
+        fixture.pushOutput("pressure".repeat(40000));
+        await waitForCoalescerFlush();
+        expect(fixture.replayOptions.at(-1)).toEqual({ scrollbackLines: history });
+        expect(fixture.replayOptions).toHaveLength(initial.length + 1);
+        fixture.ready(); // Worker adoption must use the original demand, even on the same stream.
+        await waitForCoalescerFlush();
+        expect(fixture.replayOptions.slice(initial.length + 1)).toEqual(initial);
+        fixture.frames.length = 0;
+        fixture.pushOutput("after-catch-up");
+        await waitForCoalescerFlush();
+        expect(fixture.frames.map((frame) => frame.opcode)).toEqual([TerminalStreamOpcode.Output]);
+      }
+    },
+  );
+
   test("streams all output without a snapshot when the client keeps up", async () => {
     const { pushOutput, frames } = await setup(() => 0);
 
@@ -782,7 +863,7 @@ describe("terminal-session-controller backpressure snapshot fallback", () => {
     pushOutput(chunk);
     await waitForCoalescerFlush();
 
-    expect(frames.some((frame) => frame.opcode === TerminalStreamOpcode.Snapshot)).toBe(false);
+    expect(frames.some((frame) => frame.opcode === TerminalStreamOpcode.Restore)).toBe(false);
     const outputFrames = frames.filter((frame) => frame.opcode === TerminalStreamOpcode.Output);
     expect(outputFrames.length).toBeGreaterThan(0);
     const receivedBytes = outputFrames.reduce(
@@ -798,7 +879,7 @@ describe("terminal-session-controller backpressure snapshot fallback", () => {
     pushOutput("y".repeat(300 * 1024));
     await waitForCoalescerFlush();
 
-    expect(frames.some((frame) => frame.opcode === TerminalStreamOpcode.Snapshot)).toBe(true);
+    expect(frames.some((frame) => frame.opcode === TerminalStreamOpcode.Restore)).toBe(true);
 
     // After the snapshot the byte counter is reset, so a small follow-up chunk
     // streams as Output rather than tripping the fallback again.
@@ -806,7 +887,7 @@ describe("terminal-session-controller backpressure snapshot fallback", () => {
     pushOutput("z".repeat(1024));
     await waitForCoalescerFlush();
 
-    expect(frames.some((frame) => frame.opcode === TerminalStreamOpcode.Snapshot)).toBe(false);
+    expect(frames.some((frame) => frame.opcode === TerminalStreamOpcode.Restore)).toBe(false);
     expect(frames.some((frame) => frame.opcode === TerminalStreamOpcode.Output)).toBe(true);
   });
 
@@ -822,7 +903,7 @@ describe("terminal-session-controller backpressure snapshot fallback", () => {
     pushOutput("p".repeat(300 * 1024));
     await waitForCoalescerFlush();
 
-    expect(frames.some((frame) => frame.opcode === TerminalStreamOpcode.Snapshot)).toBe(true);
+    expect(frames.some((frame) => frame.opcode === TerminalStreamOpcode.Restore)).toBe(true);
   });
 
   test("falls back to a snapshot at the byte threshold when no backpressure signal exists", async () => {
@@ -834,11 +915,41 @@ describe("terminal-session-controller backpressure snapshot fallback", () => {
     pushOutput("r".repeat(300 * 1024));
     await waitForCoalescerFlush();
 
-    expect(frames.some((frame) => frame.opcode === TerminalStreamOpcode.Snapshot)).toBe(true);
+    expect(frames.some((frame) => frame.opcode === TerminalStreamOpcode.Restore)).toBe(true);
+  });
+  test("queues capable catch-up without waiting for the direct socket to drain", async () => {
+    let buffered = 0;
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const { pushOutput, frames, messages } = await setup(
+      () => buffered,
+      true,
+      () => (buffered ? gate : Promise.resolve()),
+    );
+    buffered = 8 * 1024 * 1024;
+    pushOutput("y".repeat(300 * 1024));
+    await waitForCoalescerFlush();
+    expect(messages.filter((message) => message.type === "terminal_stream_exit")).toEqual([]);
+    expect(frames.map((frame) => frame.opcode)).toEqual([
+      TerminalStreamOpcode.ReplayBegin,
+      TerminalStreamOpcode.ReplayData,
+      TerminalStreamOpcode.ReplayEnd,
+    ]);
+    buffered = 0;
+    release();
+    await waitForCoalescerFlush();
+    expect(frames.map((frame) => frame.opcode)).toContain(TerminalStreamOpcode.ReplayEnd);
+    frames.length = 0;
+    buffered = 8 * 1024 * 1024; // Small output must stay live after the replay resets its byte counter.
+    pushOutput("live-after-recovery");
+    await waitForCoalescerFlush();
+    expect(frames.map((frame) => frame.opcode)).toEqual([TerminalStreamOpcode.Output]);
   });
 });
 
-function exitFixture(readSnapshot: () => Promise<TerminalStateSnapshot | null>, backedUp = false) {
+function exitFixture(readReplay: () => Promise<ReplayFixture | null>, backedUp = false) {
   const outputs = new Set<(message: ServerMessage) => void>();
   const exits = new Set<Parameters<TerminalSession["onExit"]>[0]>();
   const terminal: TerminalSession = {
@@ -863,8 +974,7 @@ function exitFixture(readSnapshot: () => Promise<TerminalStateSnapshot | null>,
     onTitleChange: () => () => {},
     onActivityChange: () => () => {},
     getSize: () => ({ rows: 1, cols: 80 }),
-    getState: () => terminalState("snapshot"),
-    getStateSnapshot: () => ({ state: terminalState("snapshot"), revision: 0 }),
+    hasOutput: () => true,
     getReplayPreamble: () => "",
     getTitle: () => undefined,
     getActivity: () => null,
@@ -877,7 +987,7 @@ function exitFixture(readSnapshot: () => Promise<TerminalStateSnapshot | null>,
   };
   const manager: TerminalManager = {
     getTerminal: () => terminal,
-    getTerminalState: readSnapshot,
+    replayTerminal: replayFixture(readReplay),
     getTerminals: async () => [terminal],
     createTerminal: async () => terminal,
     registerCwdEnv() {},
@@ -955,7 +1065,7 @@ describe("terminal output before natural exit", () => {
     "flushes each observer's final bytes before exit (modern=%s)",
     async (modern) => {
       vi.useFakeTimers();
-      const f = exitFixture(async () => ({ state: terminalState("snapshot"), revision: 0 }));
+      const f = exitFixture(async () => terminalReplay("snapshot", 0));
       try {
         const source = {};
         const owners = [
@@ -977,7 +1087,7 @@ describe("terminal output before natural exit", () => {
                   row.message.payload.subscriptionId === owner.id)),
           );
           expect(ordered.map((row) => row.binary?.opcode ?? row.message?.type)).toEqual([
-            TerminalStreamOpcode.Snapshot,
+            TerminalStreamOpcode.Restore,
             TerminalStreamOpcode.Output,
             TerminalStreamOpcode.Output,
             "terminal_stream_exit",
@@ -997,7 +1107,7 @@ describe("terminal output before natural exit", () => {
 
   test("waits for bootstrap snapshot and flushes buffered bytes without starting backpressure work", async () => {
     vi.useFakeTimers();
-    const snapshot = deferred<TerminalStateSnapshot | null>();
+    const snapshot = deferred<ReplayFixture | null>();
     let reads = 0;
     const f = exitFixture(() => {
       reads++;
@@ -1010,10 +1120,10 @@ describe("terminal output before natural exit", () => {
       f.exit();
       await vi.advanceTimersByTimeAsync(0);
       expect(f.frames.map((row) => row.message?.type)).toEqual(["subscribe_terminal_response"]);
-      snapshot.resolve({ state: terminalState("snapshot"), revision: 0 });
+      snapshot.resolve(terminalReplay("snapshot", 0));
       await vi.advanceTimersByTimeAsync(0);
       expect(f.frames.slice(1).map((row) => row.binary?.opcode ?? row.message?.type)).toEqual([
-        TerminalStreamOpcode.Snapshot,
+        TerminalStreamOpcode.Restore,
         TerminalStreamOpcode.Output,
         "terminal_stream_exit",
       ]);
@@ -1033,11 +1143,10 @@ describe("terminal output before natural exit", () => {
     "finishes an in-flight backpressure snapshot (available=%s)",
     async (available) => {
       vi.useFakeTimers();
-      const snapshot = deferred<TerminalStateSnapshot | null>();
+      const snapshot = deferred<ReplayFixture | null>();
       let reads = 0;
       const f = exitFixture(
-        async () =>
-          ++reads === 1 ? { state: terminalState("initial"), revision: 0 } : snapshot.promise,
+        async () => (++reads === 1 ? terminalReplay("initial", 0) : snapshot.promise),
         true,
       );
       try {
@@ -1051,10 +1160,7 @@ describe("terminal output before natural exit", () => {
         await vi.advanceTimersByTimeAsync(0);
         expect(f.frames.some((row) => row.message?.type === "terminal_stream_exit")).toBe(false);
         if (available === "rejected") snapshot.reject(new Error("Snapshot failed during exit"));
-        else
-          snapshot.resolve(
-            available ? { state: terminalState("pressure-snapshot"), revision: 1 } : null,
-          );
+        else snapshot.resolve(available ? terminalReplay("pressure-snapshot", 1) : null);
         await vi.advanceTimersByTimeAsync(0);
         const output = f.frames
           .filter((row) => row.binary?.opcode === TerminalStreamOpcode.Output)
@@ -1074,7 +1180,7 @@ describe("terminal output before natural exit", () => {
 
   test("release during exit's pending snapshot suppresses late delivery", async () => {
     vi.useFakeTimers();
-    const snapshot = deferred<TerminalStateSnapshot | null>();
+    const snapshot = deferred<ReplayFixture | null>();
     const f = exitFixture(() => snapshot.promise);
     const source = {};
     try {
@@ -1087,7 +1193,7 @@ describe("terminal output before natural exit", () => {
         subscriptionId: owner.id!,
       };
       const release = f.delivery.request(source, request, () => f.delivery.release(owner.id!));
-      snapshot.resolve({ state: terminalState("snapshot"), revision: 0 });
+      snapshot.resolve(terminalReplay("snapshot", 0));
       await release;
       await vi.advanceTimersByTimeAsync(0);
       expect(f.frames.map((row) => row.message?.type)).toEqual(["subscribe_terminal_response"]);
@@ -1102,7 +1208,7 @@ describe("terminal output before natural exit", () => {
 
   test("explicit release discards only that observer's trailing output", async () => {
     vi.useFakeTimers();
-    const f = exitFixture(async () => ({ state: terminalState("snapshot"), revision: 0 }));
+    const f = exitFixture(async () => terminalReplay("snapshot", 0));
     const source = {};
     try {
       const a = await f.subscribe(source, true, "a");
@@ -1150,8 +1256,8 @@ describe("terminal snapshot failure", () => {
       let reads = 0;
       const f = exitFixture(async () => {
         if (++reads === (phase === "backpressure" ? 2 : 1))
-          throw new Error("Terminal worker request timed out: getTerminalState");
-        return { state: terminalState("healthy"), revision: 0 };
+          throw new Error("Terminal worker request timed out: replayTerminal");
+        return terminalReplay("healthy", 0);
       }, phase === "backpressure");
       try {
         const source = {};
@@ -1179,7 +1285,7 @@ describe("terminal snapshot failure", () => {
             payload: {
               terminalId: "exit-terminal",
               subscriptionId: failed.id,
-              error: "Terminal worker request timed out: getTerminalState",
+              error: "Terminal worker request timed out: replayTerminal",
             },
           },
         ]);
@@ -1210,7 +1316,7 @@ describe("terminal snapshot failure", () => {
   );
 
   test("release during pending rejection suppresses the failure and completes cleanup", async () => {
-    const snapshot = deferred<TerminalStateSnapshot | null>();
+    const snapshot = deferred<ReplayFixture | null>();
     const f = exitFixture(() => snapshot.promise);
     const source = {};
     try {
@@ -1222,7 +1328,7 @@ describe("terminal snapshot failure", () => {
         subscriptionId: owner.id!,
       };
       const release = f.delivery.request(source, request, () => f.delivery.release(owner.id!));
-      snapshot.reject(new Error("Terminal worker request timed out: getTerminalState"));
+      snapshot.reject(new Error("Terminal worker request timed out: replayTerminal"));
       await release;
       expect(f.frames.map((row) => row.message?.type)).toEqual(["subscribe_terminal_response"]);
       expect(f.delivery.registrationCount).toBe(0);
@@ -1242,7 +1348,7 @@ test.each([false, true])(
     let reads = 0;
     const f = exitFixture(async () => {
       if (++reads === (backpressure ? 2 : 1)) throw new Error("Snapshot unavailable");
-      return { state: terminalState("recovered"), revision: 0 };
+      return terminalReplay("recovered", 0);
     }, backpressure);
     try {
       await f.subscribe({}, false, "legacy-recovery");
@@ -1256,7 +1362,7 @@ test.each([false, true])(
       for (const listener of f.outputs) listener({ type: "snapshotReady", revision: 2 });
       await vi.advanceTimersByTimeAsync(5);
       expect(reads).toBe(backpressure ? 3 : 2);
-      expect(f.frames.some((row) => row.binary?.opcode === TerminalStreamOpcode.Snapshot)).toBe(
+      expect(f.frames.some((row) => row.binary?.opcode === TerminalStreamOpcode.Restore)).toBe(
         true,
       );
       f.exit();
@@ -1276,3 +1382,51 @@ test.each([false, true])(
     }
   },
 );
+
+test("bounds a capturing viewer tail without ending a healthy viewer", async () => {
+  const pending = deferred<ReplayFixture | null>();
+  let reads = 0;
+  const f = exitFixture(() =>
+    ++reads === 2 ? pending.promise : Promise.resolve(terminalReplay("retained", 0)),
+  );
+  const desktop = {},
+    phone = {};
+  try {
+    await f.subscribe(desktop, true, "desktop");
+    await waitForCoalescerFlush();
+    await f.subscribe(phone, true, "phone");
+    f.output("x".repeat(4 * 1024 * 1024 + 1), 1);
+    await waitForCoalescerFlush();
+    expect(
+      f.frames.filter(
+        (row) => row.source === phone && row.message?.type === "terminal_stream_exit",
+      ),
+    ).toHaveLength(1);
+    expect(
+      f.frames.filter(
+        (row) => row.source === desktop && row.message?.type === "terminal_stream_exit",
+      ),
+    ).toHaveLength(0);
+    expect(
+      f.frames.some(
+        (row) => row.source === desktop && row.binary?.opcode === TerminalStreamOpcode.Output,
+      ),
+    ).toBe(true);
+    pending.resolve(terminalReplay("phone", 1));
+    await waitForCoalescerFlush();
+    f.output("AFTER-OVERFLOW", 2);
+    await waitForCoalescerFlush();
+    expect(
+      f.frames.some(
+        (row) =>
+          row.source === desktop &&
+          row.binary?.opcode === TerminalStreamOpcode.Output &&
+          Buffer.from(row.binary.payload).toString().includes("AFTER-OVERFLOW"),
+      ),
+    ).toBe(true);
+    expect(f.delivery.registrationCount).toBe(1);
+  } finally {
+    pending.resolve(null);
+    await f.delivery.close();
+  }
+});
diff --git a/packages/server/src/terminal/terminal-session-controller.ts b/packages/server/src/terminal/terminal-session-controller.ts
index 4f46dbc88c..653524e54a 100644
--- a/packages/server/src/terminal/terminal-session-controller.ts
+++ b/packages/server/src/terminal/terminal-session-controller.ts
@@ -28,16 +28,16 @@ import { TerminalOutputCoalescer } from "./terminal-output-coalescer.js";
 import {
   MAX_CLIENT_BUFFERED_BYTES,
   MAX_TERMINAL_OUTPUT_FRAME_BYTES,
-  encodeLegacyTerminalSnapshotFrame,
-  encodeTerminalRestoreFrame,
+  createTerminalRestoreDelivery,
   resolveRestoreAfterOutputOverflow,
   resolveTerminalRestoreSnapshotOptions,
-  resolveTerminalSubscriptionSnapshotMode,
   type TerminalRestoreOptions,
 } from "./terminal-restore.js";
+import type { TerminalReplayMetadata } from "./terminal-replay.js";
 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";
 
@@ -67,31 +67,28 @@ interface ActiveTerminalStream {
   needsSnapshot: boolean;
   snapshotInFlight: boolean;
   retrySnapshotErrors: boolean;
-  readyRevision?: number;
+  // Readiness is independent of revision: reconnect adoption has no revision.
+  snapshotReady: boolean;
   restore?: TerminalRestoreOptions;
   bufferedOutputs: BufferedTerminalOutput[];
+  bufferedOutputBytes: number;
   outputBytesSinceSnapshot: number;
   outputCoalescer: TerminalOutputCoalescer;
 }
 
-interface SnapshotSendResult {
-  shouldContinue: boolean;
-  replayRevision?: number;
-}
+type SnapshotSendResult =
+  | { shouldContinue: false }
+  | { shouldContinue: true; replay: TerminalReplayMetadata | null };
 
 export interface TerminalSessionControllerOptions {
   terminalManager: TerminalManager | null;
   emit: (msg: SessionOutboundMessage) => void;
   hasBinaryChannel: () => boolean;
+  supportsChunkedReplay?: (source: object) => boolean;
   isPathWithinRoot: (rootPath: string, candidatePath: string) => boolean;
   sessionLogger: pino.Logger;
   listTerminalWorkspaceRefs?: () => Promise<readonly TerminalWorkspaceRef[]>;
   listTerminalWorkspaceRoots?: () => Promise<readonly string[]>;
-  // Whether the connected client can reflow restored snapshots. When true the
-  // daemon attaches per-row soft-wrap flags to snapshots; otherwise it omits them
-  // so old (strict-schema) clients still parse the snapshot.
-  clientSupportsWrapReflow?: (source: object) => boolean;
-  // Current max bytes queued on the client's transport(s) but not yet sent.
   // Drives the snapshot catch-up fallback: a keeping-up client reports ~0 and
   // keeps streaming; a backed-up client trips the snapshot path. Defaults to a
   // constant 0 (no backpressure signal) so callers without a transport always
@@ -144,7 +141,6 @@ export class TerminalSessionController {
   private readonly sessionLogger: pino.Logger;
   private readonly listTerminalWorkspaceRefs: () => Promise<readonly TerminalWorkspaceRef[]>;
   private readonly listTerminalWorkspaceRoots: () => Promise<readonly string[]>;
-  private readonly clientSupportsWrapReflow: (source: object) => boolean;
   private readonly getClientBufferedAmount: (source: object) => number | null;
 
   private readonly subscribedDirectories = new Map<string, TerminalDirectorySubscription>();
@@ -152,7 +148,7 @@ export class TerminalSessionController {
   private readonly activeStreams = new Map<number, ActiveTerminalStream>();
   private nextSlot = 0;
 
-  constructor(options: TerminalSessionControllerOptions) {
+  constructor(private readonly options: TerminalSessionControllerOptions) {
     this.terminalManager = options.terminalManager;
     this.emit = options.emit;
     this.hasBinaryChannel = options.hasBinaryChannel;
@@ -162,7 +158,6 @@ export class TerminalSessionController {
     this.listTerminalWorkspaceRoots =
       options.listTerminalWorkspaceRoots ??
       (async () => (await this.listTerminalWorkspaceRefs()).map((workspace) => workspace.cwd));
-    this.clientSupportsWrapReflow = options.clientSupportsWrapReflow ?? (() => false);
     this.getClientBufferedAmount = options.getClientBufferedAmount ?? (() => 0);
   }
 
@@ -427,6 +422,8 @@ export class TerminalSessionController {
     }
 
     try {
+      const unavailable = this.terminalManager.getUnavailableError?.();
+      if (unavailable) throw unavailable;
       let terminals: TerminalSession[];
       if (msg.workspaceId !== undefined) {
         terminals = (await this.getAllTerminalSessions()).filter(
@@ -449,6 +446,10 @@ export class TerminalSessionController {
       });
     } catch (error) {
       this.sessionLogger.error({ err: error, cwd: msg.cwd }, "Failed to list terminals");
+      if (error instanceof TerminalWorkerIncompatibleError) {
+        this.emitIncompatible(msg, error);
+        return;
+      }
       this.emit({
         type: "list_terminals_response",
         payload: {
@@ -460,6 +461,23 @@ 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 },
+    error: TerminalWorkerIncompatibleError,
+  ): void {
+    this.emit({
+      type: "rpc_error",
+      payload: {
+        requestId: msg.requestId,
+        requestType: msg.type,
+        error: error.message,
+        code: error.code,
+      },
+    });
+  }
+
   private async getAllTerminalSessions(): Promise<TerminalSession[]> {
     if (!this.terminalManager) {
       return [];
@@ -597,6 +615,10 @@ export class TerminalSessionController {
       });
     } catch (error) {
       this.sessionLogger.error({ err: error, cwd: msg.cwd }, "Failed to create terminal");
+      if (error instanceof TerminalWorkerIncompatibleError) {
+        this.emitIncompatible(msg, error);
+        return;
+      }
       this.emit({
         type: "create_terminal_response",
         payload: {
@@ -876,9 +898,10 @@ export class TerminalSessionController {
       snapshotInFlight: false,
       retrySnapshotErrors: options.retrySnapshotErrors,
       exiting: false,
-      readyRevision: undefined,
+      snapshotReady: false,
       restore: options?.restore,
       bufferedOutputs: [],
+      bufferedOutputBytes: 0,
       outputBytesSinceSnapshot: 0,
       outputCoalescer: new TerminalOutputCoalescer({
         timers: { setTimeout, clearTimeout },
@@ -906,7 +929,6 @@ export class TerminalSessionController {
             // The snapshot replaces this batch only after it succeeds. If the
             // terminal disappears during the read, completion still owns these bytes.
             activeStream.snapshotOutput = payload;
-            activeStream.restore = resolveRestoreAfterOutputOverflow(activeStream.restore);
             activeStream.needsSnapshot = true;
             void this.trySendSnapshot(activeStream);
             return;
@@ -924,35 +946,45 @@ export class TerminalSessionController {
 
     this.activeStreams.set(slot, activeStream);
 
-    const unsubscribeOutput = terminal.subscribe(
-      (message) => {
-        if (this.activeStreams.get(slot) !== activeStream) {
-          return;
-        }
-        if (message.type === "snapshot" || message.type === "snapshotReady") {
-          activeStream.readyRevision = message.revision;
-          activeStream.outputCoalescer.flush();
-          activeStream.needsSnapshot = true;
-          void this.trySendSnapshot(activeStream);
-          return;
-        }
-        if (message.type === "titleChange") {
-          return;
-        }
-        if (message.data.length === 0) {
-          return;
-        }
-        if (activeStream.needsSnapshot || activeStream.snapshotInFlight) {
-          activeStream.bufferedOutputs.push({
-            data: message.data,
-            revision: message.revision,
+    const unsubscribeOutput = terminal.subscribe((message) => {
+      if (this.activeStreams.get(slot) !== activeStream) {
+        return;
+      }
+      if (message.type === "snapshotReady") {
+        activeStream.snapshotReady = true;
+        activeStream.outputCoalescer.flush();
+        activeStream.needsSnapshot = true;
+        void this.trySendSnapshot(activeStream);
+        return;
+      }
+      if (message.type === "titleChange") {
+        return;
+      }
+      if (message.data.length === 0) {
+        return;
+      }
+      if (activeStream.needsSnapshot || activeStream.snapshotInFlight) {
+        activeStream.bufferedOutputBytes += Buffer.byteLength(message.data);
+        if (activeStream.bufferedOutputBytes > MAX_CLIENT_BUFFERED_BYTES) {
+          activeStream.owner.emit({
+            type: "terminal_stream_exit",
+            payload: {
+              terminalId: activeStream.terminalId,
+              error: "Terminal replay live tail exceeded the buffer; attach again",
+            },
           });
+          this.detachRegistration(activeStream);
+          void activeStream.owner.release();
           return;
         }
-        activeStream.outputCoalescer.handle(message.data);
-      },
-      { initialSnapshot: resolveTerminalSubscriptionSnapshotMode(options?.restore) },
-    );
+        activeStream.bufferedOutputs.push({
+          data: message.data,
+          revision: message.revision,
+        });
+        return;
+      }
+      activeStream.outputCoalescer.handle(message.data);
+    });
     const unsubscribeExit = terminal.onExit(() =>
       this.detachStream(terminal.id, { emitExit: true }),
     );
@@ -989,22 +1021,27 @@ export class TerminalSessionController {
       this.detachStream(activeStream.terminalId, { emitExit: true });
       return;
     }
-    if (activeStream.restore && activeStream.readyRevision === undefined) {
+    if (activeStream.restore && !activeStream.snapshotReady) {
       return;
     }
 
     activeStream.outputCoalescer.flush();
     activeStream.snapshotInFlight = true;
     try {
-      const restore = activeStream.restore;
+      // A pressure catch-up replaces the skipped batch with a recent window.
+      // Keep the subscription demand intact for later adoption/full restores.
+      const restore =
+        activeStream.snapshotOutput !== undefined
+          ? resolveRestoreAfterOutputOverflow(activeStream.restore)
+          : activeStream.restore;
       const snapshotResult = restore
         ? await this.emitRestoreSnapshot(activeStream, terminalManager, restore)
-        : await this.emitLegacySnapshot(activeStream, terminalManager);
+        : await this.emitRestoreSnapshot(activeStream, terminalManager, { mode: "full-snapshot" });
       if (!snapshotResult.shouldContinue) {
         return;
       }
       activeStream.snapshotOutput = undefined;
-      this.replayTerminalOutputAfterSnapshot(activeStream, terminal, snapshotResult.replayRevision);
+      this.replayTerminalOutputAfterSnapshot(activeStream, terminal, snapshotResult.replay);
       activeStream.needsSnapshot = false;
       activeStream.outputBytesSinceSnapshot = 0;
     } catch (error) {
@@ -1042,47 +1079,31 @@ export class TerminalSessionController {
     }
   }
 
-  private async emitLegacySnapshot(
-    activeStream: ActiveTerminalStream,
-    terminalManager: TerminalManager,
-  ): Promise<SnapshotSendResult> {
-    const snapshot = await terminalManager.getTerminalState(activeStream.terminalId, {
-      includeWrapFlags: this.clientSupportsWrapReflow(activeStream.owner.source),
-    });
-    if (this.activeStreams.get(activeStream.slot) !== activeStream) {
-      return { shouldContinue: false };
-    }
-    if (!snapshot) {
-      this.detachStream(activeStream.terminalId, { emitExit: true });
-      return { shouldContinue: false };
-    }
-
-    activeStream.owner.emitBinary(
-      encodeLegacyTerminalSnapshotFrame({
-        slot: activeStream.slot,
-        snapshot,
-      }),
-    );
-    // The snapshot frame went out-of-band; keep the replay that follows on the
-    // coalescer's trailing path so it doesn't flush back-to-back with it.
-    activeStream.outputCoalescer.markFlushed();
-    return { shouldContinue: true, replayRevision: snapshot.revision };
-  }
-
   private async emitRestoreSnapshot(
     activeStream: ActiveTerminalStream,
     terminalManager: TerminalManager,
     restore: TerminalRestoreOptions,
   ): Promise<SnapshotSendResult> {
-    const snapshotOptions = resolveTerminalRestoreSnapshotOptions(restore);
+    const chunked = this.options.supportsChunkedReplay?.(activeStream.owner.source) === true;
+    const snapshotOptions = resolveTerminalRestoreSnapshotOptions({ restore, chunked });
     if (snapshotOptions === null) {
-      return { shouldContinue: true };
+      return { shouldContinue: true, replay: null };
     }
 
-    const snapshot = await terminalManager.getTerminalState(activeStream.terminalId, {
-      ...snapshotOptions,
-      includeWrapFlags: this.clientSupportsWrapReflow(activeStream.owner.source),
+    const deliver = createTerminalRestoreDelivery({
+      slot: activeStream.slot,
+      chunked,
+      // Network delivery belongs to the bounded application transport, not the worker request.
+      send: (frame) => activeStream.owner.emitBinary(frame),
     });
+    const snapshot = await terminalManager.replayTerminal(
+      activeStream.terminalId,
+      snapshotOptions,
+      (event) => {
+        if (this.activeStreams.get(activeStream.slot) !== activeStream) return;
+        deliver(event);
+      },
+    );
     if (this.activeStreams.get(activeStream.slot) !== activeStream) {
       return { shouldContinue: false };
     }
@@ -1091,38 +1112,31 @@ export class TerminalSessionController {
       return { shouldContinue: false };
     }
 
-    activeStream.owner.emitBinary(
-      encodeTerminalRestoreFrame({
-        slot: activeStream.slot,
-        snapshot,
-      }),
-    );
     // The restore frame went out-of-band; keep the replay that follows on the
     // coalescer's trailing path so it doesn't flush back-to-back with it.
     activeStream.outputCoalescer.markFlushed();
-    return { shouldContinue: true, replayRevision: snapshot.revision };
+    return { shouldContinue: true, replay: snapshot };
   }
 
   private replayTerminalOutputAfterSnapshot(
     activeStream: ActiveTerminalStream,
     terminal: TerminalSession,
-    replayRevision: number | undefined,
+    replay: TerminalReplayMetadata | null,
   ): void {
-    const replayPreamble = terminal.getReplayPreamble();
+    // A captured viewer must start from its cut, then apply the buffered mode changes.
+    // Live-only subscriptions have no capture and start from the current shared modes.
+    const replayPreamble = replay === null ? terminal.getReplayPreamble() : replay.replayPreamble;
     if (replayPreamble.length > 0) {
       activeStream.outputCoalescer.handle(replayPreamble);
     }
 
+    activeStream.bufferedOutputBytes = 0;
     const bufferedOutputs = activeStream.bufferedOutputs.splice(
       0,
       activeStream.bufferedOutputs.length,
     );
     for (const output of bufferedOutputs) {
-      if (
-        replayRevision !== undefined &&
-        output.revision !== undefined &&
-        output.revision <= replayRevision
-      ) {
+      if (replay !== null && output.revision !== undefined && output.revision <= replay.revision) {
         continue;
       }
       activeStream.outputCoalescer.handle(output.data);
diff --git a/packages/server/src/terminal/terminal-worker-client.test.ts b/packages/server/src/terminal/terminal-worker-client.test.ts
new file mode 100644
index 0000000000..119d339b18
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-client.test.ts
@@ -0,0 +1,160 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
+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 { 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";
+
+const temporaryDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of temporaryDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+async function waitUntil(predicate: () => boolean, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() > deadline) throw new Error("condition not met in time");
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+describe("terminal worker frames", () => {
+  it("decodes frames split across chunks and several frames in one chunk", () => {
+    const first = encodeFrame({ type: "a", data: new Map([["k", 1]]) });
+    const second = encodeFrame({ type: "b" });
+    const joined = Buffer.concat([first, second]);
+    const decoder = new FrameDecoder();
+    expect(decoder.push(joined.subarray(0, 3))).toEqual([]);
+    expect(decoder.push(joined.subarray(3, first.length + 2))).toEqual([
+      { type: "a", data: new Map([["k", 1]]) },
+    ]);
+    expect(decoder.push(joined.subarray(first.length + 2))).toEqual([{ type: "b" }]);
+  });
+
+  it("rejects a frame header announcing an oversized payload", () => {
+    const header = Buffer.alloc(4);
+    header.writeUInt32BE(0xffffffff, 0);
+    expect(() => new FrameDecoder().push(header)).toThrow(TerminalWorkerFrameError);
+  });
+});
+
+describe("terminal worker authentication", () => {
+  it("closes a connection with the wrong secret and accepts the record's secret", async () => {
+    const paseoHome = mkdtempSync(path.join(tmpdir(), "tw-auth-"));
+    temporaryDirs.push(paseoHome);
+    const { record, recordPath } = await launchTerminalWorker({
+      paseoHome,
+      paseoVersion: "0.0.0-test",
+    });
+    expect(recordPath).toBe(terminalWorkerRecordPath(paseoHome, record.pid));
+    if (!isPlatform("win32")) {
+      expect(statSync(recordPath).mode & 0o777).toBe(0o600);
+      expect(statSync(record.socketPath).mode & 0o777).toBe(0o600);
+    }
+
+    await expect(
+      connectTerminalWorker({ socketPath: record.socketPath, secret: "wrong-secret" }),
+    ).rejects.toBeInstanceOf(TerminalWorkerConnectError);
+
+    const connection = await connectTerminalWorker({
+      socketPath: record.socketPath,
+      secret: record.secret,
+    });
+    expect(connection.workerPid).toBe(record.pid);
+    // With no terminals, a worker whose controller leaves exits and removes its record.
+    connection.disconnect();
+    await waitUntil(() => !existsSync(recordPath), 10_000);
+  });
+});
+
+it("bounds a stalled framed writer to one chunk and resumes in order", async () => {
+  const { attachFramedSocket } = await import("./terminal-worker-frames.js");
+  const server = createServer();
+  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 test address");
+  const accepted = new Promise<import("node:net").Socket>((resolve) =>
+    server.once("connection", resolve),
+  );
+  const reader = createConnection(address.port, "127.0.0.1");
+  reader.pause();
+  const writer = await accepted;
+  const framed = attachFramedSocket(writer, () => {});
+  let completed = 0;
+  let peakQueuedBytes = 0;
+  const received: number[] = [];
+  attachFramedSocket(reader, (value) => received.push((value as { index: number }).index));
+  const sending = (async () => {
+    for (let index = 0; index < 512; index++) {
+      const pending = framed.sendAndWait({ index, data: Buffer.alloc(64 * 1024) });
+      peakQueuedBytes = Math.max(peakQueuedBytes, writer.writableLength);
+      await pending;
+      completed++;
+    }
+  })();
+  try {
+    await waitUntil(() => writer.writableLength > 0, 10000);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(completed).toBeLessThan(512);
+    expect(peakQueuedBytes).toBeLessThan(65 * 1024);
+    reader.resume();
+    await sending;
+    await waitUntil(() => received.length === 512, 10000);
+    expect(received).toEqual(Array.from({ length: 512 }, (_, index) => index));
+    expect(writer.destroyed).toBe(false);
+  } finally {
+    reader.destroy();
+    writer.destroy();
+    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
new file mode 100644
index 0000000000..ac48293879
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-client.ts
@@ -0,0 +1,173 @@
+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 {
+  TERMINAL_WORKER_PROTOCOL_VERSION,
+  type TerminalWorkerHello,
+  type TerminalWorkerHelloAck,
+  type TerminalWorkerRequest,
+  type TerminalWorkerToParentMessage,
+} from "./terminal-worker-protocol.js";
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 5_000;
+
+/** The daemon's (or cleanup's) authenticated connection to one terminal worker. */
+export interface TerminalWorkerConnection {
+  readonly connected: boolean;
+  readonly workerPid: number;
+  send(message: TerminalWorkerRequest, callback: (error: Error | null) => void): boolean;
+  /** Closes the socket. The worker keeps running and keeps its terminals. */
+  disconnect(): void;
+  on(event: "message", listener: (message: TerminalWorkerToParentMessage) => void): this;
+  on(event: "close", listener: () => void): this;
+}
+
+export class TerminalWorkerConnectError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "TerminalWorkerConnectError";
+  }
+}
+
+class SocketTerminalWorkerConnection extends EventEmitter implements TerminalWorkerConnection {
+  readonly workerPid: number;
+  private readonly framed: FramedSocket;
+  private closed = false;
+
+  constructor(framed: FramedSocket, workerPid: number) {
+    super();
+    this.framed = framed;
+    this.workerPid = workerPid;
+    framed.socket.once("close", () => {
+      this.closed = true;
+      this.emit("close");
+    });
+  }
+
+  get connected(): boolean {
+    return !this.closed && !this.framed.socket.destroyed;
+  }
+
+  send(message: TerminalWorkerRequest, callback: (error: Error | null) => void): boolean {
+    return this.framed.send(message, callback);
+  }
+
+  disconnect(): void {
+    this.framed.close();
+  }
+
+  deliver(message: TerminalWorkerToParentMessage): void {
+    this.emit("message", message);
+  }
+}
+
+function isHelloAck(message: unknown): message is TerminalWorkerHelloAck {
+  return (
+    typeof message === "object" &&
+    message !== null &&
+    (message as { type?: unknown }).type === "helloAck" &&
+    typeof (message as { pid?: unknown }).pid === "number"
+  );
+}
+
+/**
+ * Connects to a worker's socket and authenticates with the record's secret. The worker closes
+ * the socket on a wrong secret, so a rejected hello surfaces as a connect error.
+ */
+export function connectTerminalWorker(input: {
+  socketPath: string;
+  secret: string;
+  timeoutMs?: number;
+}): Promise<TerminalWorkerConnection> {
+  const timeoutMs = input.timeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(input.socketPath);
+    let connection: SocketTerminalWorkerConnection | null = null;
+    let settled = false;
+    const fail = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      reject(error);
+    };
+    const timer = setTimeout(() => {
+      fail(
+        new TerminalWorkerConnectError(
+          `Terminal worker at ${input.socketPath} did not answer within ${timeoutMs}ms`,
+        ),
+      );
+    }, timeoutMs);
+    const framed = attachFramedSocket(socket, (message) => {
+      if (connection) {
+        connection.deliver(message as TerminalWorkerToParentMessage);
+        return;
+      }
+      if (!isHelloAck(message)) {
+        fail(new TerminalWorkerConnectError("Terminal worker sent an unexpected first frame"));
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      connection = new SocketTerminalWorkerConnection(framed, message.pid);
+      resolve(connection);
+    });
+    // `on`, not `once`: an error after authentication must not go unhandled. `close`
+    // follows every socket error and ends the connection.
+    socket.on("error", (error) => {
+      fail(
+        new TerminalWorkerConnectError(
+          `Cannot connect to terminal worker at ${input.socketPath}: ${error.message}`,
+          { cause: error },
+        ),
+      );
+    });
+    socket.once("close", () => {
+      fail(
+        new TerminalWorkerConnectError(
+          `Terminal worker at ${input.socketPath} closed the connection during authentication`,
+        ),
+      );
+    });
+    socket.once("connect", () => {
+      const hello: TerminalWorkerHello = {
+        type: "hello",
+        secret: input.secret,
+        protocolVersion: TERMINAL_WORKER_PROTOCOL_VERSION,
+      };
+      framed.send(hello);
+    });
+  });
+}
+
+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-frames.ts b/packages/server/src/terminal/terminal-worker-frames.ts
new file mode 100644
index 0000000000..897e91826f
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-frames.ts
@@ -0,0 +1,110 @@
+import type { Socket } from "node:net";
+import { deserialize, serialize } from "node:v8";
+
+// Frames on the terminal worker socket: a 4-byte big-endian length, then a v8-serialized
+// payload (the same structured-clone semantics the old fork IPC used with
+// `serialization: "advanced"`). The frame format is part of the frozen envelope: every worker
+// version must keep it.
+const FRAME_HEADER_BYTES = 4;
+const MAX_FRAME_BYTES = 256 * 1024 * 1024;
+
+export class TerminalWorkerFrameError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TerminalWorkerFrameError";
+  }
+}
+
+export function encodeFrame(value: unknown): Buffer {
+  const payload = serialize(value);
+  if (payload.length > MAX_FRAME_BYTES) {
+    throw new TerminalWorkerFrameError(
+      `Terminal worker frame of ${payload.length} bytes is too large`,
+    );
+  }
+  const header = Buffer.allocUnsafe(FRAME_HEADER_BYTES);
+  header.writeUInt32BE(payload.length, 0);
+  return Buffer.concat([header, payload]);
+}
+
+export class FrameDecoder {
+  private buffered: Buffer = Buffer.alloc(0);
+
+  push(chunk: Buffer): unknown[] {
+    this.buffered = this.buffered.length === 0 ? chunk : Buffer.concat([this.buffered, chunk]);
+    const messages: unknown[] = [];
+    while (this.buffered.length >= FRAME_HEADER_BYTES) {
+      const length = this.buffered.readUInt32BE(0);
+      if (length > MAX_FRAME_BYTES) {
+        throw new TerminalWorkerFrameError(`Terminal worker frame of ${length} bytes is too large`);
+      }
+      const end = FRAME_HEADER_BYTES + length;
+      if (this.buffered.length < end) break;
+      messages.push(deserialize(this.buffered.subarray(FRAME_HEADER_BYTES, end)));
+      this.buffered = this.buffered.subarray(end);
+    }
+    return messages;
+  }
+}
+
+export interface FramedSocket {
+  readonly socket: Socket;
+  send(message: unknown, callback?: (error: Error | null) => void): boolean;
+  sendAndWait(message: unknown): Promise<void>;
+  close(): void;
+}
+
+/**
+ * Wraps a connected socket in length-prefixed frames. A malformed frame destroys the socket:
+ * the peer is either not a terminal worker endpoint or is corrupt, and both end the session.
+ */
+export function attachFramedSocket(
+  socket: Socket,
+  onMessage: (message: unknown) => void,
+): FramedSocket {
+  const decoder = new FrameDecoder();
+  socket.on("data", (chunk: Buffer) => {
+    let messages: unknown[];
+    try {
+      messages = decoder.push(chunk);
+    } catch (error) {
+      socket.destroy(error instanceof Error ? error : new Error(String(error)));
+      return;
+    }
+    for (const message of messages) {
+      if (socket.destroyed) return;
+      onMessage(message);
+    }
+  });
+  return {
+    socket,
+    send(message, callback) {
+      if (socket.destroyed || !socket.writable) {
+        callback?.(new Error("Terminal worker socket is closed"));
+        return false;
+      }
+      let frame: Buffer;
+      try {
+        frame = encodeFrame(message);
+      } catch (error) {
+        callback?.(error instanceof Error ? error : new Error(String(error)));
+        return false;
+      }
+      return socket.write(frame, (error) => callback?.(error ?? null));
+    },
+    sendAndWait(message) {
+      return new Promise<void>((resolve, reject) => {
+        this.send(message, (error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+    },
+    close() {
+      socket.end(() => socket.destroy());
+    },
+  };
+}
diff --git a/packages/server/src/terminal/terminal-worker-launch.ts b/packages/server/src/terminal/terminal-worker-launch.ts
new file mode 100644
index 0000000000..573abe3bd8
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-launch.ts
@@ -0,0 +1,93 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { buildSelfNodeCommand } from "../server/paseo-env.js";
+import { ensurePrivateDirectory } from "../server/private-files.js";
+import {
+  readTerminalWorkerRecord,
+  terminalWorkerDirectory,
+  terminalWorkerRecordPath,
+  type TerminalWorkerRecord,
+} from "./terminal-worker-record.js";
+import { resolveTerminalWorkerEntry, type TerminalWorkerEntry } from "./terminal-worker-runtime.js";
+
+const LAUNCH_TIMEOUT_MS = 20_000;
+
+export class TerminalWorkerLaunchError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "TerminalWorkerLaunchError";
+  }
+}
+
+/**
+ * Starts a terminal worker outside this process's tree: the launcher spawns the worker
+ * detached and exits once it listens, so the worker is re-parented and survives this daemon.
+ * Resolves with the record the worker wrote; a failed start leaves no worker behind.
+ */
+export async function launchTerminalWorker(input: {
+  paseoHome: string;
+  paseoVersion: string;
+  timeoutMs?: number;
+  /** Defaults to the copy of this installation's bundle (source in dev). */
+  entry?: TerminalWorkerEntry;
+}): Promise<{ record: TerminalWorkerRecord; recordPath: string }> {
+  const recordId = randomUUID();
+  ensurePrivateDirectory(terminalWorkerDirectory(input.paseoHome));
+  const entry = input.entry ?? resolveTerminalWorkerEntry(input);
+  const launch = buildSelfNodeCommand([
+    ...entry.execArgv,
+    entry.scriptPath,
+    "--launch",
+    "--record-id",
+    recordId,
+    "--paseo-home",
+    input.paseoHome,
+    "--paseo-version",
+    input.paseoVersion,
+    ...(entry.runtime ? ["--runtime", entry.runtime] : []),
+  ]);
+  const stdout = await new Promise<string>((resolve, reject) => {
+    execFile(
+      launch.command,
+      launch.args,
+      {
+        env: launch.env,
+        timeout: input.timeoutMs ?? LAUNCH_TIMEOUT_MS,
+        windowsHide: true,
+        encoding: "utf8",
+      },
+      (error, out, err) => {
+        if (error) {
+          const detail = err.trim() || error.message;
+          reject(
+            new TerminalWorkerLaunchError(`Terminal worker failed to start: ${detail}`, {
+              cause: error,
+            }),
+          );
+          return;
+        }
+        resolve(out);
+      },
+    );
+  });
+
+  let pid: number;
+  try {
+    const parsed = JSON.parse(stdout.trim()) as { pid?: unknown };
+    if (typeof parsed.pid !== "number") throw new Error("missing pid");
+    pid = parsed.pid;
+  } catch (error) {
+    throw new TerminalWorkerLaunchError(
+      `Terminal worker launcher printed an unexpected result: ${stdout.trim()}`,
+      { cause: error },
+    );
+  }
+  const recordPath = terminalWorkerRecordPath(input.paseoHome, pid);
+  const record = await readTerminalWorkerRecord(recordPath);
+  if (record.recordId !== recordId) {
+    throw new TerminalWorkerLaunchError(
+      `Terminal worker record ${recordPath} belongs to another launch`,
+    );
+  }
+  return { record, recordPath };
+}
diff --git a/packages/server/src/terminal/terminal-worker-ownership.test.ts b/packages/server/src/terminal/terminal-worker-ownership.test.ts
new file mode 100644
index 0000000000..aefa364338
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-ownership.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import type { ManagedProcessInspection } from "../server/managed-processes/managed-processes.js";
+import {
+  classifyTerminalProgramProcess,
+  identifyTerminalWorker,
+} from "./terminal-worker-ownership.js";
+
+const BIRTH = "Wed Oct 21 18:12:49 2026";
+const OTHER_BIRTH = "Wed Oct 21 18:13:02 2026";
+
+function alive(startedAt: string | null, commandLine: string | null): ManagedProcessInspection {
+  return { status: "alive", snapshot: { pid: 4242, startedAt, commandLine } };
+}
+
+describe("terminal program ownership", () => {
+  it("owns a program that ran exec: same pid and birth time, new command line", () => {
+    expect(
+      classifyTerminalProgramProcess({ startedAt: BIRTH }, alive(BIRTH, "sleep 100000")),
+    ).toEqual({ status: "owned" });
+  });
+
+  it("treats a reused pid with the same command line but another birth time as unrelated", () => {
+    expect(
+      classifyTerminalProgramProcess({ startedAt: BIRTH }, alive(OTHER_BIRTH, "/bin/zsh -l")),
+    ).toMatchObject({ status: "unrelated" });
+  });
+
+  it("never owns a process without a birth time on either side, whatever its command", () => {
+    expect(
+      classifyTerminalProgramProcess({ startedAt: BIRTH }, alive(null, "/bin/zsh -l")),
+    ).toMatchObject({ status: "unknown" });
+    expect(
+      classifyTerminalProgramProcess({ startedAt: null }, alive(BIRTH, "/bin/zsh -l")),
+    ).toMatchObject({ status: "unknown" });
+  });
+
+  it("reports an inspection error as unknown, not gone", () => {
+    expect(
+      classifyTerminalProgramProcess(
+        { startedAt: BIRTH },
+        { status: "error", error: new Error("ps failed") },
+      ),
+    ).toMatchObject({ status: "unknown", reason: expect.stringContaining("ps failed") });
+  });
+
+  it("reports a missing process as gone", () => {
+    expect(classifyTerminalProgramProcess({ startedAt: BIRTH }, { status: "not-found" })).toEqual({
+      status: "gone",
+    });
+  });
+});
+
+describe("terminal worker ownership", () => {
+  it("retires a live unrelated pid when its socket is absent without inspecting it", async () => {
+    expect(
+      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
new file mode 100644
index 0000000000..0f7033f1b3
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-ownership.ts
@@ -0,0 +1,89 @@
+import type { ManagedProcessInspection } from "../server/managed-processes/managed-processes.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.
+//
+// This is deliberately not `processIdentityMatches` from managed-processes.ts: that matcher
+// falls back to command text when a birth time is missing, and requires the original argv when
+// it is present. A terminal program is often a shell that ran `exec`, which keeps its pid and
+// birth time but changes its command line; and a reused pid can run the same command line.
+// Here birth time alone identifies a terminal program, and nothing without one is ever owned.
+
+export type ProcessOwnership =
+  | { status: "gone" }
+  | { status: "unrelated"; reason: string }
+  | { status: "owned" }
+  | { status: "unknown"; reason: string };
+
+/** 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" };
+  }
+  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" };
+  }
+}
+
+export function classifyTerminalProgramProcess(
+  entry: { startedAt: string | null },
+  inspection: ManagedProcessInspection,
+): ProcessOwnership {
+  return classifyBirth(entry.startedAt, inspection);
+}
+
+function classifyBirth(
+  recordedStartedAt: string | null,
+  inspection: ManagedProcessInspection,
+): ProcessOwnership {
+  if (inspection.status === "not-found") return { status: "gone" };
+  if (inspection.status === "error") {
+    const message =
+      inspection.error instanceof Error ? inspection.error.message : String(inspection.error);
+    return { status: "unknown", reason: `inspection failed: ${message}` };
+  }
+  const startedAt = inspection.snapshot.startedAt;
+  if (!recordedStartedAt || !startedAt) {
+    return { status: "unknown", reason: "birth time unavailable" };
+  }
+  if (startedAt !== recordedStartedAt) {
+    return { status: "unrelated", reason: "pid reused by a process with another birth time" };
+  }
+  return { status: "owned" };
+}
diff --git a/packages/server/src/terminal/terminal-worker-pool.ts b/packages/server/src/terminal/terminal-worker-pool.ts
new file mode 100644
index 0000000000..517d34aa33
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-pool.ts
@@ -0,0 +1,288 @@
+import type { TerminalActivityState } from "@getpaseo/protocol/terminal-activity";
+import type { CaptureTerminalLinesResult } from "./terminal-capture.js";
+import type {
+  TerminalActivityListener,
+  TerminalsChangedListener,
+  TerminalWorkspaceContributionChangedListener,
+} from "./terminal-manager.js";
+import type { TerminalSession } from "./terminal.js";
+import type { WorkerCreateTerminalOptions } from "./terminal-worker-protocol.js";
+import type { DaemonTerminalManager } from "./worker-terminal-manager.js";
+
+// The daemon's terminal service over up to two terminal workers: the current one, which takes
+// every new terminal, and one draining a previous worker protocol, which keeps serving the
+// terminals it already runs and is let go once its last one exits. With no current worker (two
+// were already running), the first terminal created after one exits starts one. A worker from a
+// newer Paseo
+// is not driven at all: the service then refuses terminal requests with
+// TerminalWorkerIncompatibleError instead of serving a partial view.
+
+export class TerminalWorkerIncompatibleError extends Error {
+  readonly code = "terminal_worker_incompatible";
+  readonly paseoVersion: string;
+  readonly protocolVersion: unknown;
+
+  constructor(input: { paseoVersion: string; protocolVersion: unknown }) {
+    super(
+      `Terminals are held by a newer Paseo (v${input.paseoVersion}, worker protocol ${String(input.protocolVersion)}). Update Paseo to v${input.paseoVersion} or later to use them, or run \`paseo daemon stop\` to close them.`,
+    );
+    this.name = "TerminalWorkerIncompatibleError";
+    this.paseoVersion = input.paseoVersion;
+    this.protocolVersion = input.protocolVersion;
+  }
+}
+
+export class NoTerminalWorkerAvailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "NoTerminalWorkerAvailableError";
+  }
+}
+
+export interface TerminalWorkerPoolMember {
+  manager: DaemonTerminalManager;
+  workerPid: number;
+  /** Resolves only after confirmed worker death and its scoped cleanup. */
+  exited: Promise<void>;
+  /** Waits for any reconnect; false once the member is retired or stopping. */
+  ready(): Promise<boolean>;
+  stopRecovery(): void;
+}
+
+export interface TerminalWorkerPoolOptions {
+  current: TerminalWorkerPoolMember | null;
+  draining: TerminalWorkerPoolMember[];
+  /** Set when a worker from a newer Paseo holds this home's terminals. */
+  incompatible: TerminalWorkerIncompatibleError | null;
+  /**
+   * Starts a current worker when there is none. Throws NoTerminalWorkerAvailableError, saying
+   * why, while no worker may start.
+   */
+  startCurrent?: () => Promise<TerminalWorkerPoolMember>;
+  /** Closes every terminal of every worker in the home and verifies they ended. */
+  closeAll: () => Promise<void>;
+  /** A draining worker's last terminal exited and the pool let it go. */
+  onDrained?: (member: TerminalWorkerPoolMember) => void;
+}
+
+export function createTerminalWorkerPool(
+  options: TerminalWorkerPoolOptions,
+): DaemonTerminalManager {
+  let current = options.current;
+  const draining = new Set(options.draining);
+  const terminalsChangedListeners = new Set<TerminalsChangedListener>();
+  const terminalActivityListeners = new Set<TerminalActivityListener>();
+  const contributionListeners = new Set<TerminalWorkspaceContributionChangedListener>();
+  let closePromise: Promise<void> | null = null;
+  let detached = false;
+  // One start at a time, so concurrent creates never launch two workers.
+  let starting: Promise<TerminalWorkerPoolMember> | null = null;
+  // Registrations belong to the service and are replayed whenever a current worker starts.
+  const cwdEnv = new Map<string, Record<string, string>>();
+
+  function members(): TerminalWorkerPoolMember[] {
+    return [...(current ? [current] : []), ...draining];
+  }
+
+  function assertAvailable(): void {
+    if (options.incompatible) throw options.incompatible;
+  }
+
+  function ownerOf(terminalId: string): DaemonTerminalManager | null {
+    for (const member of members()) {
+      if (member.manager.getTerminal(terminalId)) return member.manager;
+    }
+    return null;
+  }
+
+  function routed(terminalId: string): DaemonTerminalManager {
+    assertAvailable();
+    const owner = ownerOf(terminalId) ?? current?.manager;
+    if (!owner) {
+      throw new NoTerminalWorkerAvailableError(`Terminal ${terminalId} is not running`);
+    }
+    return owner;
+  }
+
+  function releaseIfDrained(member: TerminalWorkerPoolMember): void {
+    if (!draining.has(member) || member.manager.listDirectories().length > 0) return;
+    draining.delete(member);
+    // With no controller and no terminals the worker exits on its own. The request that closed
+    // the last terminal is still waiting for its answer.
+    void member.manager
+      .detach({ afterPendingRequests: true })
+      .then(() => options.onDrained?.(member));
+  }
+
+  function forwardEvents(member: TerminalWorkerPoolMember): void {
+    void member.exited.then(() => {
+      if (current === member) current = null;
+      return draining.delete(member);
+    });
+    member.manager.subscribeTerminalsChanged((event) => {
+      for (const listener of Array.from(terminalsChangedListeners)) listener(event);
+      releaseIfDrained(member);
+    });
+    member.manager.subscribeTerminalActivity((event) => {
+      for (const listener of Array.from(terminalActivityListeners)) listener(event);
+    });
+    member.manager.subscribeTerminalWorkspaceContributionChanged((event) => {
+      for (const listener of Array.from(contributionListeners)) listener(event);
+    });
+  }
+
+  for (const member of members()) forwardEvents(member);
+  for (const member of Array.from(draining)) releaseIfDrained(member);
+
+  async function currentManager(): Promise<DaemonTerminalManager> {
+    if (closePromise || detached)
+      throw new NoTerminalWorkerAvailableError("No terminal worker can take new terminals");
+    const candidate = current;
+    if (candidate && (await candidate.ready())) return candidate.manager;
+    const startCurrent = options.startCurrent;
+    if (!startCurrent || closePromise || detached) {
+      return Promise.reject(
+        new NoTerminalWorkerAvailableError("No terminal worker can take new terminals"),
+      );
+    }
+    starting ??= startCurrent()
+      .then(async (member) => {
+        if (closePromise || detached) {
+          // The service closed or let go while the worker started: it takes no terminals.
+          member.stopRecovery();
+          await member.manager.detach();
+          throw new NoTerminalWorkerAvailableError("No terminal worker can take new terminals");
+        }
+        forwardEvents(member);
+        for (const [cwd, env] of cwdEnv) member.manager.registerCwdEnv({ cwd, env });
+        current = member;
+        return member;
+      })
+      .finally(() => {
+        starting = null;
+      });
+    return starting.then((member) => member.manager);
+  }
+
+  function closeTerminals(): Promise<void> {
+    closePromise ??= (async () => {
+      for (const member of members()) member.stopRecovery();
+      await starting?.catch(() => {});
+      await Promise.all(members().map((member) => member.manager.detach()));
+      draining.clear();
+      await options.closeAll();
+    })();
+    return closePromise;
+  }
+
+  return {
+    getUnavailableError(): Error | null {
+      return options.incompatible;
+    },
+
+    async getTerminals(cwd, filter) {
+      assertAvailable();
+      const lists = await Promise.all(
+        members().map((member) => member.manager.getTerminals(cwd, filter)),
+      );
+      return lists.flat();
+    },
+
+    async createTerminal(
+      createOptions: WorkerCreateTerminalOptions & { workspaceId: string },
+    ): Promise<TerminalSession> {
+      assertAvailable();
+      const manager = await currentManager();
+      return manager.createTerminal(createOptions);
+    },
+
+    registerCwdEnv(registration) {
+      cwdEnv.set(registration.cwd, registration.env);
+      if (current) current.manager.registerCwdEnv(registration);
+    },
+
+    validateTerminalActivityToken(terminalId, token) {
+      for (const member of members()) {
+        const result = member.manager.validateTerminalActivityToken(terminalId, token);
+        if (result !== "unknown") return result;
+      }
+      return "unknown";
+    },
+
+    getTerminal(id) {
+      for (const member of members()) {
+        const session = member.manager.getTerminal(id);
+        if (session) return session;
+      }
+      return undefined;
+    },
+
+    async replayTerminal(id, replayOptions, sink) {
+      return routed(id).replayTerminal(id, replayOptions, sink);
+    },
+
+    setTerminalTitle(id, title) {
+      return ownerOf(id)?.setTerminalTitle(id, title) ?? false;
+    },
+
+    async setTerminalActivity(id, state: TerminalActivityState) {
+      return (await ownerOf(id)?.setTerminalActivity(id, state)) ?? false;
+    },
+
+    async clearTerminalAttention(id) {
+      return (await ownerOf(id)?.clearTerminalAttention(id)) ?? false;
+    },
+
+    killTerminal(id) {
+      ownerOf(id)?.killTerminal(id);
+    },
+
+    async killTerminalAndWait(id, waitOptions) {
+      await routed(id).killTerminalAndWait(id, waitOptions);
+    },
+
+    async captureTerminal(id, captureOptions): Promise<CaptureTerminalLinesResult> {
+      return routed(id).captureTerminal(id, captureOptions);
+    },
+
+    listDirectories() {
+      return [...new Set(members().flatMap((member) => member.manager.listDirectories()))];
+    },
+
+    killAll() {
+      void closeTerminals().catch(() => {
+        // The synchronous interface cannot report it; closeTerminals() callers see the error.
+      });
+    },
+
+    closeTerminals,
+
+    async detach() {
+      detached = true;
+      for (const member of members()) member.stopRecovery();
+      await starting?.catch(() => {});
+      await Promise.all(members().map((member) => member.manager.detach()));
+    },
+
+    async adoptTerminals() {
+      const counts = await Promise.all(members().map((member) => member.manager.adoptTerminals()));
+      for (const member of Array.from(draining)) releaseIfDrained(member);
+      return counts.reduce((sum, count) => sum + count, 0);
+    },
+
+    subscribeTerminalsChanged(listener) {
+      terminalsChangedListeners.add(listener);
+      return () => terminalsChangedListeners.delete(listener);
+    },
+
+    subscribeTerminalActivity(listener) {
+      terminalActivityListeners.add(listener);
+      return () => terminalActivityListeners.delete(listener);
+    },
+
+    subscribeTerminalWorkspaceContributionChanged(listener) {
+      contributionListeners.add(listener);
+      return () => contributionListeners.delete(listener);
+    },
+  };
+}
diff --git a/packages/server/src/terminal/terminal-worker-process.ts b/packages/server/src/terminal/terminal-worker-process.ts
index a70d37c5b9..b9eb4698c0 100644
--- a/packages/server/src/terminal/terminal-worker-process.ts
+++ b/packages/server/src/terminal/terminal-worker-process.ts
@@ -1,352 +1,760 @@
+import { createTerminalReplayController } from "./terminal-replay.js";
+import { spawn } from "node:child_process";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, closeSync, existsSync, openSync, rmSync, writeSync } from "node:fs";
+import { createServer, type Server, type Socket } from "node:net";
+import { fileURLToPath } from "node:url";
+import { currentBootId } from "../server/pid-lock.js";
+import { PRIVATE_FILE_MODE } from "../server/private-files.js";
 import { createTerminalManager } from "./terminal-manager.js";
-import { captureTerminalLines } from "./terminal-capture.js";
 import { TerminalOutputCoalescer } from "./terminal-output-coalescer.js";
-import type { TerminalSession, TerminalStateSnapshotOptions } from "./terminal.js";
-import type {
-  TerminalWorkerRequest,
-  TerminalWorkerStateResult,
-  TerminalWorkerToParentMessage,
-  WorkerTerminalInfo,
+import type { TerminalExitInfo, LocalTerminalSession } from "./terminal.js";
+import { attachFramedSocket, type FramedSocket } from "./terminal-worker-frames.js";
+import { createTerminalWorkerProcessInspector } from "./terminal-worker-processes.js";
+import {
+  TERMINAL_WORKER_MARKER_ARG,
+  terminalWorkerLogPath,
+  terminalWorkerRecordPath,
+  writeTerminalWorkerRecord,
+  type TerminalWorkerRecord,
+} from "./terminal-worker-record.js";
+import { createTerminalWorkerRecordPublisher } from "./terminal-worker-record-publisher.js";
+import { resolveTerminalWorkerSocketPath } from "./terminal-worker-socket-path.js";
+import {
+  TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV,
+  TERMINAL_WORKER_PROTOCOL_VERSION,
+  type TerminalWorkerHello,
+  type TerminalWorkerHelloAck,
+  type TerminalWorkerListResult,
+  type TerminalWorkerRequest,
+  type TerminalWorkerToParentMessage,
+  type WorkerTerminalInfo,
 } from "./terminal-worker-protocol.js";
 
-type TerminalCreateRequest = Extract<TerminalWorkerRequest, { type: "createTerminal" }>;
+// The terminal worker owns every PTY. It runs detached from the daemon (re-parented by the
+// launcher below) so a daemon restart, crash or forced kill of the daemon's process tree does
+// not take the terminals down, and it talks to whichever daemon controls it over an
+// owner-only socket authenticated by the secret in its record.
+//
+// `--launch` runs the launcher: it starts the real worker detached, waits for it to listen,
+// prints `{ pid, socketPath }` and exits, which leaves the worker parented to init.
 
-const manager = createTerminalManager();
-const unsubscribeByTerminalId = new Map<string, Array<() => void>>();
-const outputCoalescerByTerminalId = new Map<string, TerminalOutputCoalescer>();
-let ipcClosing = false;
+const LAUNCH_ARG = "--launch";
+const READY_TIMEOUT_MS = 15_000;
+const HELLO_TIMEOUT_MS = 5_000;
+// A freshly launched worker waits this long for its first controller before giving up.
+const FIRST_CONTROLLER_TIMEOUT_MS = 30_000;
+// While nobody controls it, the worker checks that its record still exists. A deleted record
+// (a removed $PASEO_HOME) means no daemon can ever find these terminals again.
+const ORPHAN_CHECK_INTERVAL_MS = 10_000;
+const READY_FD = 3;
 
-interface InFlightTerminalCreateRequest {
-  requestId: string;
-  errorReported: boolean;
+interface WorkerArgs {
+  recordId: string;
+  paseoHome: string;
+  paseoVersion: string;
+  // The copy under terminal-worker/ this worker runs from; absent when it runs from source.
+  runtime: string | null;
 }
 
-let inFlightTerminalCreateRequest: InFlightTerminalCreateRequest | null = null;
-
-// The conpty failure signal is process-scoped, not request-scoped. Serializing
-// creates keeps an async spawn failure attributable to exactly one request.
-let createTerminalQueue: Promise<void> = Promise.resolve();
-
-// node-pty completes its Windows conpty spawn asynchronously on a separate
-// conout worker thread. When that spawn fails (bad cwd, missing command, etc.)
-// it throws an exception there that cannot be caught at the call site and would
-// otherwise crash this worker process and sever every existing terminal.
-process.on("uncaughtException", (error) => {
-  console.error("Terminal worker uncaught exception (kept alive):", error);
-  reportInFlightTerminalCreateFailure(error);
-});
-
-function sendToParent(message: TerminalWorkerToParentMessage): void {
-  if (ipcClosing || !process.connected || !process.send) {
-    return;
-  }
-  try {
-    process.send(message, (error) => {
-      if (error) {
-        ipcClosing = true;
-      }
-    });
-  } catch {
-    ipcClosing = true;
+function readArg(argv: string[], name: string): string {
+  const index = argv.indexOf(name);
+  const value = index === -1 ? undefined : argv[index + 1];
+  if (!value) {
+    throw new Error(`Terminal worker requires ${name}`);
   }
+  return value;
 }
 
-function buildTerminalStateResult(
-  session: TerminalSession | undefined,
-  options?: TerminalStateSnapshotOptions,
-): TerminalWorkerStateResult {
-  if (!session) {
-    return null;
-  }
-  return { ...session.getStateSnapshot(options), replayPreamble: session.getReplayPreamble() };
-}
-
-function toTerminalInfo(session: TerminalSession): WorkerTerminalInfo {
+function parseWorkerArgs(argv: string[], recordIdArg: string): WorkerArgs {
   return {
-    id: session.id,
-    name: session.name,
-    cwd: session.cwd,
-    workspaceId: session.workspaceId,
-    ...(session.getTitle() ? { title: session.getTitle() } : {}),
-    activity: session.getActivity(),
+    recordId: readArg(argv, recordIdArg),
+    paseoHome: readArg(argv, "--paseo-home"),
+    paseoVersion: readArg(argv, "--paseo-version"),
+    runtime: argv.includes("--runtime") ? readArg(argv, "--runtime") : null,
   };
 }
 
-function terminalWorkerErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : "Terminal worker request failed";
-}
-
-function reportInFlightTerminalCreateFailure(error: unknown): void {
-  if (!inFlightTerminalCreateRequest || inFlightTerminalCreateRequest.errorReported) {
-    return;
+// The protocol version this worker reports in its record and hello. Tests override it to stand
+// up older and newer workers from one build.
+function reportedProtocolVersion(): number {
+  const override = process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV];
+  if (override === undefined || override === "") return TERMINAL_WORKER_PROTOCOL_VERSION;
+  const parsed = Number(override);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new Error(`${TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV} is not an integer: ${override}`);
   }
-  inFlightTerminalCreateRequest.errorReported = true;
-  sendToParent({
-    type: "response",
-    requestId: inFlightTerminalCreateRequest.requestId,
-    ok: false,
-    error: terminalWorkerErrorMessage(error),
-  });
+  return parsed;
 }
 
-function clearTerminalSubscriptions(terminalId: string): void {
-  const subscriptions = unsubscribeByTerminalId.get(terminalId);
-  if (subscriptions) {
-    for (const unsubscribe of subscriptions) {
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// ---------------------------------------------------------------------------------------------
+// Launcher
+// ---------------------------------------------------------------------------------------------
+
+function runLauncher(argv: string[]): void {
+  const args = parseWorkerArgs(argv, "--record-id");
+  const logFd = openSync(terminalWorkerLogPath(args.paseoHome), "a", PRIVATE_FILE_MODE);
+  const child = spawn(
+    process.execPath,
+    [
+      ...process.execArgv,
+      fileURLToPath(import.meta.url),
+      TERMINAL_WORKER_MARKER_ARG,
+      args.recordId,
+      "--paseo-home",
+      args.paseoHome,
+      "--paseo-version",
+      args.paseoVersion,
+      ...(args.runtime ? ["--runtime", args.runtime] : []),
+    ],
+    {
+      detached: true,
+      stdio: ["ignore", "ignore", logFd, "pipe"],
+      env: process.env,
+      windowsHide: true,
+    },
+  );
+  closeSync(logFd);
+
+  let settled = false;
+  let buffered = "";
+  const finish = (code: number, output: string) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    if (code !== 0 && child.exitCode === null && child.pid) {
+      // A worker that never reported ready must not be left behind.
       try {
-        unsubscribe();
+        process.kill(child.pid, "SIGKILL");
       } catch {
-        // no-op
+        // Already gone.
       }
     }
-  }
-  unsubscribeByTerminalId.delete(terminalId);
-  const coalescer = outputCoalescerByTerminalId.get(terminalId);
-  if (coalescer) {
-    coalescer.dispose();
-    outputCoalescerByTerminalId.delete(terminalId);
-  }
+    child.unref();
+    (child.stdio[READY_FD] as NodeJS.ReadableStream & { destroy(): void }).destroy();
+    // Exit from the write callback: a pipe write can still be pending when process.exit runs.
+    (code === 0 ? process.stdout : process.stderr).write(output, () => process.exit(code));
+  };
+  const timer = setTimeout(() => {
+    finish(1, `Terminal worker did not report ready within ${READY_TIMEOUT_MS}ms\n`);
+  }, READY_TIMEOUT_MS);
+
+  const readyStream = child.stdio[READY_FD] as NodeJS.ReadableStream;
+  readyStream.setEncoding("utf8");
+  readyStream.on("data", (chunk: string) => {
+    buffered += chunk;
+    const newline = buffered.indexOf("\n");
+    if (newline === -1) return;
+    const line = buffered.slice(0, newline);
+    if (line.startsWith("ready ")) {
+      finish(0, `${JSON.stringify({ pid: child.pid, socketPath: line.slice("ready ".length) })}\n`);
+      return;
+    }
+    finish(1, `${line.startsWith("error ") ? line.slice("error ".length) : line}\n`);
+  });
+  child.once("error", (error) => finish(1, `Cannot start terminal worker: ${error.message}\n`));
+  child.once("exit", (code, signal) => {
+    finish(1, `Terminal worker exited before it was ready (${signal ?? `code ${code}`})\n`);
+  });
 }
 
-function watchTerminal(session: TerminalSession): void {
-  clearTerminalSubscriptions(session.id);
+// ---------------------------------------------------------------------------------------------
+// Worker
+// ---------------------------------------------------------------------------------------------
 
-  // Coalesce pty output chunks into a single IPC message per ~5ms window so a
-  // burst of small chunks no longer costs one process.send each. The batch
-  // carries the LAST chunk's revision (the highest) so downstream snapshot
-  // replay dedup stays correct.
-  let pendingOutputRevision: number | undefined;
-  const outputCoalescer = new TerminalOutputCoalescer({
-    timers: { setTimeout, clearTimeout },
-    onFlush: ({ payload }) => {
-      const revision = pendingOutputRevision;
-      pendingOutputRevision = undefined;
-      sendToParent({
-        type: "terminalMessage",
-        terminalId: session.id,
-        message: { type: "output", data: payload.toString("utf8"), revision },
-        replayPreamble: session.getReplayPreamble(),
-      });
-    },
+type TerminalCreateRequest = Extract<TerminalWorkerRequest, { type: "createTerminal" }>;
+
+function runWorker(argv: string[]): void {
+  const args = parseWorkerArgs(argv, TERMINAL_WORKER_MARKER_ARG);
+  const protocolVersion = reportedProtocolVersion();
+  const manager = createTerminalManager();
+  const inspector = createTerminalWorkerProcessInspector();
+  const sessionsById = new Map<string, LocalTerminalSession>();
+  const unsubscribeByTerminalId = new Map<string, Array<() => void>>();
+  const outputCoalescerByTerminalId = new Map<string, TerminalOutputCoalescer>();
+  // A terminal is published (terminalCreated) only once its program is recorded. An exit that
+  // arrives before then is held here and sent after the creation, so the controller never
+  // receives an exit for a terminal it does not know yet.
+  const exitsHeldDuringCreation = new Map<string, TerminalExitInfo | null>();
+  const secret = randomBytes(32).toString("base64url");
+  let record: TerminalWorkerRecord | null = null;
+  let server: Server | null = null;
+  let controller: FramedSocket | null = null;
+  let everControlled = false;
+  let exiting = false;
+
+  interface InFlightTerminalCreateRequest {
+    requestId: string;
+    errorReported: boolean;
+  }
+
+  let inFlightTerminalCreateRequest: InFlightTerminalCreateRequest | null = null;
+
+  // The conpty failure signal is process-scoped, not request-scoped. Serializing
+  // creates keeps an async spawn failure attributable to exactly one request.
+  let createTerminalQueue: Promise<void> = Promise.resolve();
+
+  // node-pty completes its Windows conpty spawn asynchronously on a separate
+  // conout worker thread. When that spawn fails (bad cwd, missing command, etc.)
+  // it throws an exception there that cannot be caught at the call site and would
+  // otherwise crash this worker process and sever every existing terminal.
+  process.on("uncaughtException", (error) => {
+    console.error("Terminal worker uncaught exception (kept alive):", error);
+    reportInFlightTerminalCreateFailure(error);
   });
-  outputCoalescerByTerminalId.set(session.id, outputCoalescer);
 
-  const unsubscribeMessage = session.subscribe(
-    (message) => {
+  const replayController = createTerminalReplayController({
+    getSession: (id) => sessionsById.get(id),
+    flushOutput: (id) => outputCoalescerByTerminalId.get(id)?.flush(),
+  });
+  function sendToController(message: TerminalWorkerToParentMessage): void {
+    replayController.send(message);
+  }
+
+  const recordPublisher = createTerminalWorkerRecordPublisher((state) => {
+    writeTerminalWorkerRecord(args.paseoHome, state);
+  });
+
+  async function persistRecord(): Promise<void> {
+    if (!record || exiting) return;
+    record = {
+      ...record,
+      terminals: record.terminals.filter((entry) => sessionsById.has(entry.id)),
+    };
+    await recordPublisher.publish(record);
+  }
+
+  function removeOwnFiles(): void {
+    rmSync(terminalWorkerRecordPath(args.paseoHome, process.pid), { force: true });
+    if (record && process.platform !== "win32") {
+      rmSync(record.socketPath, { force: true });
+    }
+  }
+
+  function exitWorker(code: number): void {
+    if (exiting) return;
+    exiting = true;
+    recordPublisher.stop();
+    removeOwnFiles();
+    server?.close();
+    process.exit(code);
+  }
+
+  async function killEveryTerminalAndExit(): Promise<void> {
+    const sessions = Array.from(sessionsById.values());
+    await Promise.all(
+      sessions.map((session) =>
+        session.killAndWait().catch((error: unknown) => {
+          console.error(`Terminal worker could not kill terminal ${session.id}:`, error);
+        }),
+      ),
+    );
+    exitWorker(0);
+  }
+
+  function exitIfIdle(): void {
+    if (!controller && everControlled && sessionsById.size === 0) {
+      exitWorker(0);
+    }
+  }
+
+  function terminalMetadata(session: LocalTerminalSession) {
+    return { ...session.getSize(), hasOutput: session.hasOutput(), title: session.getTitle() };
+  }
+
+  function toTerminalInfo(session: LocalTerminalSession): WorkerTerminalInfo {
+    return {
+      id: session.id,
+      name: session.name,
+      cwd: session.cwd,
+      workspaceId: session.workspaceId,
+      ...(session.getTitle() ? { title: session.getTitle() } : {}),
+      activity: session.getActivity(),
+    };
+  }
+
+  function terminalWorkerErrorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : "Terminal worker request failed";
+  }
+
+  function reportInFlightTerminalCreateFailure(error: unknown): void {
+    if (!inFlightTerminalCreateRequest || inFlightTerminalCreateRequest.errorReported) {
+      return;
+    }
+    inFlightTerminalCreateRequest.errorReported = true;
+    sendToController({
+      type: "response",
+      requestId: inFlightTerminalCreateRequest.requestId,
+      ok: false,
+      error: terminalWorkerErrorMessage(error),
+    });
+  }
+
+  function clearTerminalSubscriptions(terminalId: string): void {
+    const subscriptions = unsubscribeByTerminalId.get(terminalId);
+    if (subscriptions) {
+      for (const unsubscribe of subscriptions) {
+        try {
+          unsubscribe();
+        } catch {
+          // no-op
+        }
+      }
+    }
+    unsubscribeByTerminalId.delete(terminalId);
+    const coalescer = outputCoalescerByTerminalId.get(terminalId);
+    if (coalescer) {
+      coalescer.dispose();
+      outputCoalescerByTerminalId.delete(terminalId);
+    }
+  }
+
+  function watchTerminal(session: LocalTerminalSession): void {
+    clearTerminalSubscriptions(session.id);
+
+    // Coalesce pty output chunks into a single frame per ~5ms window so a burst of small
+    // chunks no longer costs one socket write each. The batch carries the LAST chunk's
+    // revision (the highest) so downstream snapshot replay dedup stays correct.
+    let pendingOutputRevision: number | undefined;
+    const outputCoalescer = new TerminalOutputCoalescer({
+      timers: { setTimeout, clearTimeout },
+      onFlush: ({ payload }) => {
+        const revision = pendingOutputRevision;
+        pendingOutputRevision = undefined;
+        sendToController({
+          type: "terminalMessage",
+          terminalId: session.id,
+          message: { type: "output", data: payload.toString("utf8"), revision },
+          replayPreamble: session.getReplayPreamble(),
+        });
+      },
+    });
+    outputCoalescerByTerminalId.set(session.id, outputCoalescer);
+
+    const unsubscribeMessage = session.subscribe((message) => {
       if (message.type === "output") {
         pendingOutputRevision = message.revision;
         outputCoalescer.handle(message.data);
         return;
       }
-      // Non-output messages (snapshot/snapshotReady/titleChange) must not jump
+      // Non-output messages (snapshotReady/titleChange) must not jump
       // ahead of buffered output: flush the coalescer first, then forward.
       outputCoalescer.flush();
-      sendToParent({
+      sendToController({
         type: "terminalMessage",
         terminalId: session.id,
         message,
         replayPreamble: session.getReplayPreamble(),
       });
-    },
-    // Creation already sends an authoritative state in terminalCreated. A second
-    // asynchronous state snapshot can arrive after the create response and
-    // overwrite a resize issued immediately by the caller.
-    { initialSnapshot: "ready" },
-  );
-  const unsubscribeExit = session.onExit((info) => {
-    outputCoalescer.flush();
-    clearTerminalSubscriptions(session.id);
-    sendToParent({
-      type: "terminalExit",
-      terminalId: session.id,
-      info,
     });
-  });
-  const unsubscribeTitle = session.onTitleChange((title) => {
-    outputCoalescer.flush();
-    sendToParent({
-      type: "terminalTitleChange",
-      terminalId: session.id,
-      title,
-    });
-  });
-  const unsubscribeCommandFinished = session.onCommandFinished((info) => {
-    outputCoalescer.flush();
-    sendToParent({
-      type: "terminalCommandFinished",
-      terminalId: session.id,
-      info,
-    });
-  });
-  const unsubscribeActivity = session.onActivityChange((transition) => {
-    sendToParent({
-      type: "terminalActivityChange",
-      terminalId: session.id,
-      activity: transition.activity,
-      previous: transition.previous,
-    });
-  });
-
-  unsubscribeByTerminalId.set(session.id, [
-    unsubscribeMessage,
-    unsubscribeExit,
-    unsubscribeTitle,
-    unsubscribeCommandFinished,
-    unsubscribeActivity,
-  ]);
-}
-
-function enqueueCreateTerminalRequest(message: TerminalCreateRequest): Promise<void> {
-  const nextRequest = createTerminalQueue.then(() => handleCreateTerminalRequest(message));
-  createTerminalQueue = nextRequest.catch(() => {});
-  return nextRequest;
-}
-
-async function handleCreateTerminalRequest(message: TerminalCreateRequest): Promise<void> {
-  const request: InFlightTerminalCreateRequest = {
-    requestId: message.requestId,
-    errorReported: false,
-  };
-  inFlightTerminalCreateRequest = request;
-  try {
-    const { workspaceId } = message.options;
-    if (!workspaceId) {
-      throw new Error("workspaceId is required");
-    }
-    const session = await manager.createTerminal({ ...message.options, workspaceId });
-    if (request.errorReported) {
-      session.kill();
-      return;
-    }
-    watchTerminal(session);
-    const initialSnapshot = session.getStateSnapshot();
-    sendToParent({
-      type: "terminalCreated",
-      terminal: toTerminalInfo(session),
-      state: initialSnapshot.state,
-    });
-    sendToParent({
-      type: "response",
-      requestId: message.requestId,
-      ok: true,
-      result: {
-        terminal: toTerminalInfo(session),
-        state: initialSnapshot.state,
-      },
-    });
-  } catch (error) {
-    reportInFlightTerminalCreateFailure(error);
-  } finally {
-    if (inFlightTerminalCreateRequest === request) {
-      inFlightTerminalCreateRequest = null;
-    }
-  }
-}
-
-async function handleRequest(message: TerminalWorkerRequest): Promise<void> {
-  switch (message.type) {
-    case "createTerminal": {
-      await enqueueCreateTerminalRequest(message);
-      return;
-    }
-
-    case "registerCwdEnv": {
-      manager.registerCwdEnv({ cwd: message.cwd, env: message.env });
-      sendToParent({ type: "response", requestId: message.requestId, ok: true });
-      return;
-    }
-
-    case "setActivity": {
-      await manager.setTerminalActivity(message.terminalId, message.state);
-      sendToParent({ type: "response", requestId: message.requestId, ok: true });
-      return;
-    }
-
-    case "clearAttention": {
-      await manager.clearTerminalAttention(message.terminalId);
-      sendToParent({ type: "response", requestId: message.requestId, ok: true });
-      return;
-    }
-
-    case "killTerminal": {
-      manager.killTerminal(message.terminalId);
-      // Removal is owned by session.onExit -> terminalExit; the parent mirror
-      // clears contribution and emits terminalsChanged from that single path.
-      clearTerminalSubscriptions(message.terminalId);
-      sendToParent({ type: "response", requestId: message.requestId, ok: true });
-      return;
-    }
-
-    case "killTerminalAndWait": {
-      await manager.killTerminalAndWait(message.terminalId, message.options);
-      clearTerminalSubscriptions(message.terminalId);
-      sendToParent({ type: "response", requestId: message.requestId, ok: true });
-      return;
-    }
-
-    case "getTerminalState": {
-      // Flush buffered output before snapshotting: the headless state already includes it,
-      // so if the coalescer emitted it afterward (in a batch carrying a revision past the
-      // snapshot's) the controller's revision dedup wouldn't drop it and the client would
-      // see the bytes twice. Flushing first sends them with a revision <= the snapshot's.
-      outputCoalescerByTerminalId.get(message.terminalId)?.flush();
-      sendToParent({
-        type: "response",
-        requestId: message.requestId,
-        ok: true,
-        result: buildTerminalStateResult(manager.getTerminal(message.terminalId), message.options),
+    const unsubscribeExit = session.onExit((info) => {
+      outputCoalescer.flush();
+      clearTerminalSubscriptions(session.id);
+      sessionsById.delete(session.id);
+      void persistRecord().catch((error) => {
+        if (!exiting) console.error("Cannot publish terminal exit:", error);
       });
-      return;
-    }
-
-    case "captureTerminal": {
-      const session = manager.getTerminal(message.terminalId);
-      const result = session
-        ? captureTerminalLines(session, {
-            start: message.start,
-            end: message.end,
-            stripAnsi: message.stripAnsi,
-          })
-        : { lines: [], totalLines: 0 };
-      sendToParent({
-        type: "response",
-        requestId: message.requestId,
-        ok: true,
-        result,
-      });
-      return;
-    }
-
-    case "killAll": {
-      manager.killAll();
-      for (const terminalId of Array.from(unsubscribeByTerminalId.keys())) {
-        clearTerminalSubscriptions(terminalId);
+      if (exitsHeldDuringCreation.has(session.id)) {
+        exitsHeldDuringCreation.set(session.id, info);
+        return;
       }
-      sendToParent({ type: "response", requestId: message.requestId, ok: true });
+      sendToController({
+        type: "terminalExit",
+        terminalId: session.id,
+        info,
+      });
+      exitIfIdle();
+    });
+    const unsubscribeTitle = session.onTitleChange((title) => {
+      outputCoalescer.flush();
+      sendToController({
+        type: "terminalTitleChange",
+        terminalId: session.id,
+        title,
+      });
+    });
+    const unsubscribeCommandFinished = session.onCommandFinished((info) => {
+      outputCoalescer.flush();
+      sendToController({
+        type: "terminalCommandFinished",
+        terminalId: session.id,
+        info,
+      });
+    });
+    const unsubscribeActivity = session.onActivityChange((transition) => {
+      sendToController({
+        type: "terminalActivityChange",
+        terminalId: session.id,
+        activity: transition.activity,
+        previous: transition.previous,
+      });
+    });
+
+    unsubscribeByTerminalId.set(session.id, [
+      unsubscribeMessage,
+      unsubscribeExit,
+      unsubscribeTitle,
+      unsubscribeCommandFinished,
+      unsubscribeActivity,
+    ]);
+  }
+
+  // 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.
+    const pid = manager.getTerminalProcessId(session.id);
+    if (pid === null) {
+      throw new Error(`Terminal ${session.id} has no program pid`);
+    }
+    const inspection = inspector.reportsBirthTimes ? await inspector.inspect(pid) : null;
+    if (inspection?.status === "not-found" || session.getExitInfo()) {
       return;
     }
+    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";
+      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");
+    }
+    record = {
+      ...record,
+      terminals: [
+        ...record.terminals.filter((entry) => entry.id !== session.id),
+        { id: session.id, pid, startedAt },
+      ],
+    };
+    await persistRecord();
+  }
 
-    case "send": {
-      const session = manager.getTerminal(message.terminalId);
-      session?.send(message.message);
-      sendToParent({ type: "response", requestId: message.requestId, ok: true });
-      return;
+  function enqueueCreateTerminalRequest(message: TerminalCreateRequest): Promise<void> {
+    const nextRequest = createTerminalQueue.then(() => handleCreateTerminalRequest(message));
+    createTerminalQueue = nextRequest.catch(() => {});
+    return nextRequest;
+  }
+
+  async function handleCreateTerminalRequest(message: TerminalCreateRequest): Promise<void> {
+    const request: InFlightTerminalCreateRequest = {
+      requestId: message.requestId,
+      errorReported: false,
+    };
+    inFlightTerminalCreateRequest = request;
+    try {
+      const { workspaceId } = message.options;
+      if (!workspaceId) {
+        throw new Error("workspaceId is required");
+      }
+      const session = await manager.createTerminal({ ...message.options, workspaceId });
+      if (request.errorReported) {
+        session.kill();
+        return;
+      }
+      sessionsById.set(session.id, session);
+      exitsHeldDuringCreation.set(session.id, null);
+      watchTerminal(session);
+      try {
+        await recordTerminalProgram(session);
+      } catch (error) {
+        exitsHeldDuringCreation.delete(session.id);
+        clearTerminalSubscriptions(session.id);
+        sessionsById.delete(session.id);
+        await session.killAndWait().catch(() => undefined);
+        throw error;
+      }
+      const state = terminalMetadata(session);
+      sendToController({
+        type: "terminalCreated",
+        terminal: toTerminalInfo(session),
+        state,
+      });
+      // Startup output/readiness may have arrived while recording the program,
+      // before the daemon knew this terminal. Publish its current modes after creation.
+      sendToController({
+        type: "terminalMessage",
+        terminalId: session.id,
+        message: { type: "snapshotReady" },
+        replayPreamble: session.getReplayPreamble(),
+      });
+      sendToController({
+        type: "response",
+        requestId: message.requestId,
+        ok: true,
+        result: {
+          terminal: toTerminalInfo(session),
+          state,
+        },
+      });
+      const heldExit = exitsHeldDuringCreation.get(session.id);
+      exitsHeldDuringCreation.delete(session.id);
+      if (heldExit) {
+        sendToController({ type: "terminalExit", terminalId: session.id, info: heldExit });
+        exitIfIdle();
+      }
+    } catch (error) {
+      reportInFlightTerminalCreateFailure(error);
+    } finally {
+      if (inFlightTerminalCreateRequest === request) {
+        inFlightTerminalCreateRequest = null;
+      }
     }
   }
+
+  function listTerminals(): TerminalWorkerListResult {
+    return Array.from(sessionsById.values()).map((session) => {
+      // Buffered output is already in the headless state; flushing first keeps a later
+      // batch from carrying bytes the snapshot already shows.
+      outputCoalescerByTerminalId.get(session.id)?.flush();
+      return {
+        terminal: toTerminalInfo(session),
+        state: terminalMetadata(session),
+        activityToken: manager.getTerminalActivityToken(session.id),
+        replayPreamble: session.getReplayPreamble(),
+      };
+    });
+  }
+
+  async function handleRequest(message: TerminalWorkerRequest): Promise<void> {
+    switch (message.type) {
+      case "createTerminal": {
+        await enqueueCreateTerminalRequest(message);
+        return;
+      }
+
+      case "registerCwdEnv": {
+        manager.registerCwdEnv({ cwd: message.cwd, env: message.env });
+        sendToController({ type: "response", requestId: message.requestId, ok: true });
+        return;
+      }
+
+      case "setActivity": {
+        await manager.setTerminalActivity(message.terminalId, message.state);
+        sendToController({ type: "response", requestId: message.requestId, ok: true });
+        return;
+      }
+
+      case "clearAttention": {
+        await manager.clearTerminalAttention(message.terminalId);
+        sendToController({ type: "response", requestId: message.requestId, ok: true });
+        return;
+      }
+
+      case "killTerminal": {
+        manager.killTerminal(message.terminalId);
+        // Removal is owned by session.onExit -> terminalExit; the parent mirror
+        // clears contribution and emits terminalsChanged from that single path.
+        sendToController({ type: "response", requestId: message.requestId, ok: true });
+        return;
+      }
+
+      case "killTerminalAndWait": {
+        await manager.killTerminalAndWait(message.terminalId, message.options);
+        sendToController({ type: "response", requestId: message.requestId, ok: true });
+        return;
+      }
+
+      case "replayTerminal": {
+        await replayController.replay(message);
+        return;
+      }
+
+      case "captureTerminal": {
+        const session = manager.getTerminal(message.terminalId);
+        const result = session
+          ? session.captureLines({
+              start: message.start,
+              end: message.end,
+              stripAnsi: message.stripAnsi,
+            })
+          : { lines: [], totalLines: 0 };
+        sendToController({
+          type: "response",
+          requestId: message.requestId,
+          ok: true,
+          result,
+        });
+        return;
+      }
+
+      case "listTerminals": {
+        sendToController({
+          type: "response",
+          requestId: message.requestId,
+          ok: true,
+          result: listTerminals(),
+        });
+        return;
+      }
+
+      case "shutdown": {
+        const sessions = Array.from(sessionsById.values());
+        await Promise.all(sessions.map((session) => session.killAndWait().catch(() => undefined)));
+        // Exit once the response frame is flushed, so the requester sees the confirmation.
+        const requester = controller;
+        if (!requester) {
+          exitWorker(0);
+          return;
+        }
+        requester.send({ type: "response", requestId: message.requestId, ok: true }, () =>
+          exitWorker(0),
+        );
+        return;
+      }
+
+      case "send": {
+        const session = manager.getTerminal(message.terminalId);
+        session?.send(message.message);
+        sendToController({ type: "response", requestId: message.requestId, ok: true });
+        return;
+      }
+    }
+  }
+
+  function isHello(message: unknown): message is TerminalWorkerHello {
+    return (
+      typeof message === "object" &&
+      message !== null &&
+      (message as { type?: unknown }).type === "hello" &&
+      typeof (message as { secret?: unknown }).secret === "string"
+    );
+  }
+
+  function secretMatches(candidate: string): boolean {
+    const expected = Buffer.from(secret, "utf8");
+    const actual = Buffer.from(candidate, "utf8");
+    return expected.length === actual.length && timingSafeEqual(expected, actual);
+  }
+
+  function handleConnection(socket: Socket): void {
+    let authenticated = false;
+    socket.on("error", () => {
+      // `close` follows; a broken controller socket only means no controller.
+    });
+    const helloTimer = setTimeout(() => socket.destroy(), HELLO_TIMEOUT_MS);
+    const framed = attachFramedSocket(socket, (message) => {
+      if (!authenticated) {
+        clearTimeout(helloTimer);
+        if (!isHello(message) || !secretMatches(message.secret)) {
+          socket.destroy();
+          return;
+        }
+        authenticated = true;
+        // One controller at a time: a new authenticated connection replaces the old one.
+        controller = framed;
+        replayController.setConnection(framed);
+        everControlled = true;
+        const ack: TerminalWorkerHelloAck = {
+          type: "helloAck",
+          pid: process.pid,
+          protocolVersion,
+        };
+        framed.send(ack);
+        return;
+      }
+      if (framed !== controller) {
+        return;
+      }
+      const request = message as TerminalWorkerRequest;
+      void handleRequest(request).catch((error: unknown) => {
+        sendToController({
+          type: "response",
+          requestId: request.requestId,
+          ok: false,
+          error: terminalWorkerErrorMessage(error),
+        });
+      });
+    });
+    socket.once("close", () => {
+      clearTimeout(helloTimer);
+      if (controller === framed) {
+        controller = null;
+        replayController.setConnection(null);
+        exitIfIdle();
+      }
+    });
+  }
+
+  function reportReady(line: string): void {
+    try {
+      writeSync(READY_FD, `${line}\n`);
+      closeSync(READY_FD);
+    } catch {
+      // Started without a launcher pipe (tests that spawn the worker directly).
+    }
+  }
+
+  async function start(): Promise<void> {
+    const socketPath = resolveTerminalWorkerSocketPath({
+      paseoHome: args.paseoHome,
+      workerPid: process.pid,
+      recordId: args.recordId,
+    });
+    if (process.platform !== "win32") {
+      rmSync(socketPath, { force: true });
+    }
+    const listening = createServer(handleConnection);
+    await new Promise<void>((resolve, reject) => {
+      listening.once("error", reject);
+      listening.listen(socketPath, () => {
+        listening.off("error", reject);
+        resolve();
+      });
+    });
+    server = listening;
+    if (process.platform !== "win32") {
+      chmodSync(socketPath, PRIVATE_FILE_MODE);
+    }
+
+    record = {
+      recordId: args.recordId,
+      pid: process.pid,
+      bootId: currentBootId(),
+      createdAt: new Date().toISOString(),
+      protocolVersion,
+      paseoVersion: args.paseoVersion,
+      socketPath,
+      secret,
+      runtime: args.runtime,
+      terminals: [],
+    };
+    writeTerminalWorkerRecord(args.paseoHome, record);
+    reportReady(`ready ${socketPath}`);
+
+    setTimeout(() => {
+      if (!everControlled && sessionsById.size === 0) exitWorker(0);
+    }, FIRST_CONTROLLER_TIMEOUT_MS).unref();
+    setInterval(() => {
+      if (!controller && !existsSync(terminalWorkerRecordPath(args.paseoHome, process.pid))) {
+        void killEveryTerminalAndExit();
+      }
+    }, ORPHAN_CHECK_INTERVAL_MS);
+  }
+
+  process.on("SIGTERM", () => {
+    void killEveryTerminalAndExit();
+  });
+
+  start().catch((error: unknown) => {
+    const message = errorMessage(error).replace(/\n/g, " | ");
+    console.error(`Terminal worker failed to start: ${errorMessage(error)}`);
+    reportReady(`error ${message}`);
+    exitWorker(1);
+  });
 }
 
-process.on("message", (message: TerminalWorkerRequest) => {
-  void handleRequest(message).catch((error: unknown) => {
-    sendToParent({
-      type: "response",
-      requestId: message.requestId,
-      ok: false,
-      error: terminalWorkerErrorMessage(error),
-    });
-  });
-});
-
-process.once("disconnect", () => {
-  ipcClosing = true;
-  manager.killAll();
-});
+if (process.argv.includes(LAUNCH_ARG)) {
+  runLauncher(process.argv.slice(2));
+} else {
+  runWorker(process.argv.slice(2));
+}
diff --git a/packages/server/src/terminal/terminal-worker-processes.ts b/packages/server/src/terminal/terminal-worker-processes.ts
new file mode 100644
index 0000000000..90de521bab
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-processes.ts
@@ -0,0 +1,154 @@
+import { readFile } from "node:fs/promises";
+import { execCommand } from "../utils/spawn.js";
+import {
+  createSystemManagedProcessTable,
+  type ManagedProcessCommandRunner,
+  type ManagedProcessInspection,
+} from "../server/managed-processes/managed-processes.js";
+
+// 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.
+
+const PS_TIMEOUT_MS = 15_000;
+const POSIX_LSTART_WIDTH = 24;
+
+export interface ProcessTableEntry {
+  pid: number;
+  ppid: number;
+  startedAt: string;
+  // POSIX session id where `ps` reports one (Linux). macOS `ps` has no session column.
+  sessionId: number | null;
+}
+
+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[]>;
+  /**
+   * The environment a process was started with, as NAME=value entries; null when the process
+   * is gone. Throws when it cannot be read. Only called where `reportsSessions` is true.
+   */
+  readEnvironment(pid: number): Promise<string[] | null>;
+}
+
+function createLocaleNeutralCommandRunner(): ManagedProcessCommandRunner {
+  return {
+    exec: (command, args) =>
+      execCommand(command, args, {
+        envMode: "internal",
+        envOverlay: { LC_ALL: "C" },
+        timeout: PS_TIMEOUT_MS,
+        maxBuffer: 64 * 1024 * 1024,
+      }).then(({ stdout, stderr }) => ({ stdout: String(stdout), stderr: String(stderr) })),
+  };
+}
+
+export function createTerminalWorkerProcessInspector(
+  options: { platform?: NodeJS.Platform; commandRunner?: ManagedProcessCommandRunner } = {},
+): TerminalWorkerProcessInspector {
+  const platform = options.platform ?? process.platform;
+  const commandRunner = options.commandRunner ?? createLocaleNeutralCommandRunner();
+  const table = createSystemManagedProcessTable({ platform, commandRunner });
+  return {
+    reportsSessions: platform === "linux",
+    reportsBirthTimes: platform !== "win32",
+    inspect: (pid) =>
+      platform === "win32"
+        ? 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),
+  };
+}
+
+async function readLinuxEnvironment(
+  platform: NodeJS.Platform,
+  pid: number,
+): Promise<string[] | null> {
+  if (platform !== "linux") {
+    throw new Error(`reading a process environment is not supported on ${platform}`);
+  }
+  let raw: string;
+  try {
+    raw = await readFile(`/proc/${pid}/environ`, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+  return raw.split("\0").filter((entry) => entry.length > 0);
+}
+
+async function listPosixProcesses(
+  commandRunner: ManagedProcessCommandRunner,
+  platform: NodeJS.Platform,
+): Promise<ProcessTableEntry[]> {
+  const withSession = platform === "linux";
+  const columns = withSession
+    ? ["-o", "pid=", "-o", "ppid=", "-o", "sid=", "-o", "lstart="]
+    : ["-o", "pid=", "-o", "ppid=", "-o", "lstart="];
+  const { stdout } = await commandRunner.exec("ps", ["-A", "-ww", ...columns]);
+  const entries: ProcessTableEntry[] = [];
+  const leadingInts = withSession ? 3 : 2;
+  for (const line of stdout.split("\n")) {
+    const match = line.match(
+      withSession ? /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.+?)\s*$/ : /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/,
+    );
+    if (!match) continue;
+    const startedAt = match[leadingInts + 1].slice(0, POSIX_LSTART_WIDTH).trim();
+    entries.push({
+      pid: Number(match[1]),
+      ppid: Number(match[2]),
+      sessionId: withSession ? Number(match[3]) : null,
+      startedAt,
+    });
+  }
+  if (entries.length === 0) {
+    throw new Error("ps returned no processes");
+  }
+  return entries;
+}
+
+/**
+ * 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
+ * is a session leader, and the kernel keeps its pid reserved as the session id while any member
+ * lives, so the session still names a HUP-ignoring job after the shell exits and the job is
+ * reparented.
+ */
+export function collectDescendants(
+  snapshot: ProcessTableEntry[],
+  rootPid: number,
+): ProcessTableEntry[] {
+  const childrenByParent = new Map<number, ProcessTableEntry[]>();
+  for (const entry of snapshot) {
+    const siblings = childrenByParent.get(entry.ppid) ?? [];
+    siblings.push(entry);
+    childrenByParent.set(entry.ppid, siblings);
+  }
+  const found = new Map<number, ProcessTableEntry>();
+  const queue = [rootPid];
+  for (const entry of snapshot) {
+    if (entry.sessionId === rootPid && entry.pid !== rootPid) {
+      found.set(entry.pid, entry);
+      queue.push(entry.pid);
+    }
+  }
+  while (queue.length > 0) {
+    const parent = queue.shift()!;
+    for (const child of childrenByParent.get(parent) ?? []) {
+      if (child.pid === rootPid || found.has(child.pid)) continue;
+      found.set(child.pid, child);
+      queue.push(child.pid);
+    }
+  }
+  return Array.from(found.values());
+}
diff --git a/packages/server/src/terminal/terminal-worker-protocol.test.ts b/packages/server/src/terminal/terminal-worker-protocol.test.ts
new file mode 100644
index 0000000000..6ea9a823db
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-protocol.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { classifyTerminalWorkerProtocol } from "./terminal-worker-protocol.js";
+
+describe("classifyTerminalWorkerProtocol", () => {
+  it("rejects the unreleased cell protocol without a draining adapter", () => {
+    expect(classifyTerminalWorkerProtocol(1, 2)).toBe("obsolete");
+    expect(classifyTerminalWorkerProtocol(2, 3)).toBe("obsolete");
+    expect(classifyTerminalWorkerProtocol(3, 4)).toBe("obsolete");
+    expect(classifyTerminalWorkerProtocol(4, 5)).toBe("obsolete");
+  });
+  it.each([
+    [6, "current"],
+    [5, "previous"],
+    [4, "obsolete"],
+    [-1, "obsolete"],
+    [7, "newer"],
+    // A version this daemon cannot read comes from a Paseo it does not know.
+    ["6", "newer"],
+    [4.5, "newer"],
+    [Number.NaN, "newer"],
+    [undefined, "newer"],
+  ])("a worker reporting %s to a daemon at 6 is %s", (reported, fit) => {
+    expect(classifyTerminalWorkerProtocol(reported, 6)).toBe(fit);
+  });
+});
diff --git a/packages/server/src/terminal/terminal-worker-protocol.ts b/packages/server/src/terminal/terminal-worker-protocol.ts
index 5e7d1a30c0..e781543697 100644
--- a/packages/server/src/terminal/terminal-worker-protocol.ts
+++ b/packages/server/src/terminal/terminal-worker-protocol.ts
@@ -1,11 +1,11 @@
-import type {
-  TerminalExitInfo,
-  ServerMessage,
-  ClientMessage,
-  TerminalStateSnapshot,
-  TerminalStateSnapshotOptions,
-} from "./terminal.js";
-import type { TerminalState } from "@getpaseo/protocol/messages";
+import type { TerminalExitInfo, ServerMessage, ClientMessage } from "./terminal.js";
+import type { TerminalReplayEvent, TerminalReplayOptions } from "./terminal-replay.js";
+export interface WorkerTerminalState {
+  rows: number;
+  cols: number;
+  hasOutput: boolean;
+  title?: string;
+}
 import type { TerminalActivity, TerminalActivityState } from "@getpaseo/protocol/terminal-activity";
 import type { CaptureTerminalLinesResult } from "./terminal-capture.js";
 
@@ -31,6 +31,56 @@ export interface WorkerCreateTerminalOptions {
   cols?: number;
   activityToken?: string;
   activityUrl?: string | null;
+  // The worker outlives the daemon that started it, so the controlling daemon
+  // sends its own environment and Paseo CLI path with every create instead of
+  // letting the worker reuse whatever it inherited at launch.
+  baseEnv?: Record<string, string>;
+  paseoCliPath?: string | null;
+}
+
+// Bumped when a request, response or event changes shape. The frozen envelope never changes
+// across versions: the frame format, `hello`/`helloAck`, the `listTerminals` info fields, and
+// `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;
+
+// Test-only: the protocol version a worker reports, so tests can stand up older and newer
+// workers from one build.
+export const TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV = "PASEO_TERMINAL_WORKER_PROTOCOL_OVERRIDE";
+
+/** How a daemon at `current` treats a worker reporting `reported`. */
+export type TerminalWorkerProtocolFit = "current" | "previous" | "obsolete" | "newer";
+
+export function classifyTerminalWorkerProtocol(
+  reported: unknown,
+  current: number = TERMINAL_WORKER_PROTOCOL_VERSION,
+): TerminalWorkerProtocolFit {
+  // A version this daemon cannot read comes from a Paseo it does not know: treat it as newer.
+  if (typeof reported !== "number" || !Number.isSafeInteger(reported)) return "newer";
+  if (reported === current) return "current";
+  // Protocols 1 through 4 were unreleased; they have no draining adapter.
+  if (reported === current - 1 && reported >= 5) return "previous";
+  return reported < current ? "obsolete" : "newer";
+}
+
+export interface TerminalWorkerHello {
+  type: "hello";
+  secret: string;
+  protocolVersion: number;
+}
+
+export interface TerminalWorkerHelloAck {
+  type: "helloAck";
+  pid: number;
+  protocolVersion: number;
+}
+
+export interface WorkerListedTerminal {
+  terminal: WorkerTerminalInfo;
+  state: WorkerTerminalState;
+  activityToken: string | null;
+  replayPreamble: string;
 }
 
 export interface WorkerKillAndWaitOptions {
@@ -73,10 +123,10 @@ export type TerminalWorkerRequest =
       options?: WorkerKillAndWaitOptions;
     }
   | {
-      type: "getTerminalState";
+      type: "replayTerminal";
       requestId: string;
       terminalId: string;
-      options?: TerminalStateSnapshotOptions;
+      options?: TerminalReplayOptions;
     }
   | {
       type: "captureTerminal";
@@ -87,7 +137,12 @@ export type TerminalWorkerRequest =
       stripAnsi?: boolean;
     }
   | {
-      type: "killAll";
+      type: "listTerminals";
+      requestId: string;
+    }
+  | {
+      // Kill every terminal (waiting for each program to exit) and exit.
+      type: "shutdown";
       requestId: string;
     }
   | {
@@ -112,10 +167,11 @@ export type TerminalWorkerResponse =
     };
 
 export type TerminalWorkerEvent =
+  | { type: "terminalReplay"; requestId: string; event: TerminalReplayEvent }
   | {
       type: "terminalCreated";
       terminal: WorkerTerminalInfo;
-      state: TerminalState;
+      state: WorkerTerminalState;
     }
   | {
       type: "terminalMessage";
@@ -149,7 +205,6 @@ export type TerminalWorkerEvent =
 
 export type TerminalWorkerToParentMessage = TerminalWorkerResponse | TerminalWorkerEvent;
 
+export type TerminalWorkerListResult = WorkerListedTerminal[];
+
 export type TerminalWorkerCaptureResult = CaptureTerminalLinesResult;
-// The worker fills TerminalStateSnapshot.replayPreamble on getTerminalState so
-// the parent can cache the input-mode preamble instead of re-deriving it.
-export type TerminalWorkerStateResult = TerminalStateSnapshot | null;
diff --git a/packages/server/src/terminal/terminal-worker-reaper.test.ts b/packages/server/src/terminal/terminal-worker-reaper.test.ts
new file mode 100644
index 0000000000..ef8d4fe487
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-reaper.test.ts
@@ -0,0 +1,798 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { execFile, spawn, type ChildProcess } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+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,
+  type TerminalWorkerProcessInspector,
+} from "./terminal-worker-processes.js";
+import {
+  readUnconfirmedTerminalCleanup,
+  reapTerminalWorkers,
+  retryUnconfirmedTerminalCleanup,
+  TerminalCleanupNotConfirmedError,
+} from "./terminal-worker-reaper.js";
+import {
+  readTerminalWorkerRecord,
+  terminalCleanupRecordPath,
+  terminalWorkerDirectory,
+  writeTerminalWorkerRecord,
+  writeTerminalCleanupRecord,
+  type TerminalWorkerRecord,
+} from "./terminal-worker-record.js";
+
+// Real throwaway processes stand in for workers and terminal programs, so every signal the
+// reaper sends lands on a process this test started. Nothing here uses invented pids.
+
+const inspector = createTerminalWorkerProcessInspector();
+const children: ChildProcess[] = [];
+const extraPids: number[] = [];
+const temporaryDirs: string[] = [];
+
+function spawnIdle(
+  script = "setInterval(() => {}, 1e9)",
+  env: NodeJS.ProcessEnv = process.env,
+): ChildProcess {
+  const child = spawn(process.execPath, ["-e", script], {
+    detached: true,
+    stdio: ["ignore", "pipe", "ignore"],
+    env,
+  });
+  children.push(child);
+  return child;
+}
+
+// A program with one child of its own in a separate process group, so only the descendant walk
+// (not the program's group kill) can reach it.
+async function spawnProgramWithChild(): Promise<{ program: ChildProcess; childPid: number }> {
+  const program = spawnIdle(`
+    const child = require("node:child_process").spawn(process.execPath, ["-e", "setInterval(() => {}, 1e9)"], { stdio: "ignore", detached: true });
+    process.stdout.write(String(child.pid) + "\\n");
+    setInterval(() => {}, 1e9);
+  `);
+  const childPid = await new Promise<number>((resolve) => {
+    program.stdout!.once("data", (chunk: Buffer) => resolve(Number(chunk.toString().trim())));
+  });
+  extraPids.push(childPid);
+  return { program, childPid };
+}
+
+async function birthOf(pid: number): Promise<string> {
+  const inspection = await inspector.inspect(pid);
+  if (inspection.status !== "alive" || !inspection.snapshot.startedAt) {
+    throw new Error(`cannot read birth time of ${pid}`);
+  }
+  return inspection.snapshot.startedAt;
+}
+
+async function goneProcessPid(): Promise<number> {
+  const child = spawn(process.execPath, ["-e", ""], { stdio: "ignore" });
+  await new Promise((resolve) => child.once("exit", resolve));
+  return child.pid!;
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitUntilGone(pid: number): Promise<void> {
+  const deadline = Date.now() + 5_000;
+  while (isAlive(pid) && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+// A member of the terminal "t1" carries its id, as every program a terminal starts does.
+function terminalEnv(terminalId: string): NodeJS.ProcessEnv {
+  return { ...process.env, PASEO_TERMINAL_ID: terminalId };
+}
+
+// A process's start environment: /proc where the real inspector reads it (Linux), `ps -E` on
+// macOS, whose real inspector has no session walk and so never reads one.
+function readEnvironment(pid: number): Promise<string[] | null> {
+  if (process.platform === "linux") return inspector.readEnvironment(pid);
+  return new Promise((resolve) => {
+    execFile("ps", ["-E", "-ww", "-o", "command=", "-p", String(pid)], (error, stdout) => {
+      resolve(error ? null : stdout.trim().split(/\s+/));
+    });
+  });
+}
+
+// The real process table as a Linux `ps` would print it for one session: `memberPid` belongs to
+// the session `sessionId` led, and every other process to none this test knows. macOS `ps` has
+// no session column, so this is the only way to run the Linux branch here; the member is a real
+// process the test started. `reusedRoot` adds a process that took the session id's pid.
+function withSessionMember(input: {
+  memberPid: number;
+  sessionId: number;
+  reusedRoot?: boolean;
+  environmentUnreadable?: boolean;
+}): TerminalWorkerProcessInspector {
+  return {
+    reportsSessions: true,
+    reportsBirthTimes: true,
+    inspect: (pid) => inspector.inspect(pid),
+    listProcesses: async () => {
+      // A fresh snapshot each call, so it is rewritten in place.
+      const snapshot = await inspector.listProcesses();
+      for (const entry of snapshot) {
+        entry.sessionId = entry.pid === input.memberPid ? input.sessionId : null;
+      }
+      if (input.reusedRoot) {
+        snapshot.push({
+          pid: input.sessionId,
+          ppid: 1,
+          startedAt: "Fri Jan  1 00:00:00 2100",
+          sessionId: input.sessionId,
+        });
+      }
+      return snapshot;
+    },
+    readEnvironment: (pid) =>
+      input.environmentUnreadable
+        ? Promise.reject(new Error("permission denied"))
+        : readEnvironment(pid),
+  };
+}
+
+// A record this process cannot open until another thread restores it, the way a worker's
+// rename over its record ends a Windows sharing violation. The thread waits for `release()`, then
+// restores the record while this thread is still inside the (synchronous) record read.
+async function unreadableUntilReleased(
+  recordPath: string,
+): Promise<{ release: () => void; restored: Promise<void> }> {
+  chmodSync(recordPath, 0);
+  const signal = new Int32Array(new SharedArrayBuffer(8));
+  const thread = new Worker(
+    `
+    const { parentPort, workerData } = require("node:worker_threads");
+    const signal = new Int32Array(workerData.signal);
+    parentPort.postMessage("ready");
+    Atomics.wait(signal, 0, 0);
+    Atomics.wait(signal, 1, 0, 30);
+    require("node:fs").chmodSync(workerData.recordPath, 0o600);
+    `,
+    { eval: true, workerData: { recordPath, signal: signal.buffer } },
+  );
+  await new Promise((resolve) => thread.once("message", resolve));
+  const restored = new Promise<void>((resolve, reject) => {
+    thread.once("exit", () => resolve());
+    thread.once("error", reject);
+  });
+  return {
+    release: () => {
+      Atomics.store(signal, 0, 1);
+      Atomics.notify(signal, 0);
+    },
+    restored,
+  };
+}
+
+function makeHome(): string {
+  const home = mkdtempSync(path.join(tmpdir(), "tw-reaper-"));
+  temporaryDirs.push(home);
+  return home;
+}
+
+function writeRecord(
+  home: string,
+  input: Partial<TerminalWorkerRecord> & Pick<TerminalWorkerRecord, "pid">,
+): string {
+  const record: TerminalWorkerRecord = {
+    recordId: "record-under-test",
+    bootId: currentBootId(),
+    createdAt: new Date().toISOString(),
+    identity: {
+      startedAt: "Thu Jan  1 00:00:00 1970",
+      commandLine: "node terminal-worker --paseo-terminal-worker record-under-test",
+    },
+    protocolVersion: 1,
+    paseoVersion: "0.0.0-test",
+    socketPath: path.join(home, "missing.sock"),
+    secret: "not-a-real-secret",
+    terminals: [],
+    ...input,
+  };
+  return writeTerminalWorkerRecord(home, record);
+}
+
+afterEach(async () => {
+  for (const child of children.splice(0)) {
+    if (child.pid && isAlive(child.pid)) {
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch {
+        child.kill("SIGKILL");
+      }
+    }
+  }
+  for (const pid of extraPids.splice(0)) {
+    if (isAlive(pid)) process.kill(pid, "SIGKILL");
+  }
+  for (const dir of temporaryDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe.skipIf(isPlatform("win32"))("terminal worker reaper", () => {
+  it("ends the programs a dead worker left, and their children, then retires the record", async () => {
+    const home = makeHome();
+    const { program, childPid } = await spawnProgramWithChild();
+    const recordPath = writeRecord(home, {
+      pid: await goneProcessPid(),
+      terminals: [{ id: "t1", pid: program.pid!, startedAt: await birthOf(program.pid!) }],
+    });
+
+    const result = await reapTerminalWorkers({ paseoHome: home, inspector });
+
+    await waitUntilGone(program.pid!);
+    await waitUntilGone(childPid);
+    expect(isAlive(program.pid!)).toBe(false);
+    expect(isAlive(childPid)).toBe(false);
+    expect(result.signaled).toEqual(expect.arrayContaining([program.pid!, childPid]));
+    expect(existsSync(recordPath)).toBe(false);
+  });
+
+  it("never signals a live process that reuses the worker pid, but still ends its programs", async () => {
+    const home = makeHome();
+    const reusedWorkerPid = spawnIdle().pid!;
+    const program = spawnIdle();
+    writeRecord(home, {
+      pid: reusedWorkerPid,
+      terminals: [{ id: "t1", pid: program.pid!, startedAt: await birthOf(program.pid!) }],
+    });
+
+    const result = await reapTerminalWorkers({ paseoHome: home, inspector });
+
+    await waitUntilGone(program.pid!);
+    expect(isAlive(program.pid!)).toBe(false);
+    expect(isAlive(reusedWorkerPid)).toBe(true);
+    expect(result.signaled).not.toContain(reusedWorkerPid);
+  });
+
+  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: [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 () => {
+    const home = makeHome();
+    const program = spawnIdle();
+    const recordPath = writeRecord(home, {
+      pid: spawnIdle().pid!,
+      bootId: null,
+      createdAt: "2000-01-01T00:00:00.000Z",
+      terminals: [{ id: "t1", pid: program.pid!, startedAt: await birthOf(program.pid!) }],
+    });
+
+    await reapTerminalWorkers({ paseoHome: home, inspector });
+
+    expect(isAlive(program.pid!)).toBe(true);
+    expect(existsSync(recordPath)).toBe(false);
+  });
+
+  it("keeps a record of what it could not inspect and reports cleanup unconfirmed", async () => {
+    const home = makeHome();
+    const uninspectable = spawnIdle();
+    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") })
+          : inspector.inspect(pid),
+      listProcesses: () => inspector.listProcesses(),
+      readEnvironment: (pid) => inspector.readEnvironment(pid),
+    };
+    const workerPid = await goneProcessPid();
+    const recordPath = writeRecord(home, {
+      pid: workerPid,
+      terminals: [
+        { id: "t1", pid: uninspectable.pid!, startedAt: await birthOf(uninspectable.pid!) },
+        { id: "t2", pid: killable.pid!, startedAt: await birthOf(killable.pid!) },
+      ],
+    });
+
+    let caught: unknown;
+    try {
+      await reapTerminalWorkers({ paseoHome: home, inspector: failing, confirmMs: 500 });
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toBeInstanceOf(TerminalCleanupNotConfirmedError);
+    expect((caught as TerminalCleanupNotConfirmedError).unresolved).toEqual([
+      expect.objectContaining({ pid: uninspectable.pid, reason: "inspection failed" }),
+    ]);
+    await waitUntilGone(killable.pid!);
+    expect(isAlive(killable.pid!)).toBe(false);
+    expect(isAlive(uninspectable.pid!)).toBe(true);
+    // The closing state goes to the cleanup record; the worker's own record is left as it was.
+    const kept = await readTerminalWorkerRecord(
+      terminalCleanupRecordPath(home, "record-under-test"),
+    );
+    expect(kept.pid).toBe(workerPid);
+    expect(kept.closing?.unresolved.length).toBeGreaterThan(0);
+    expect(kept.terminals.map((entry) => entry.pid)).toEqual([uninspectable.pid]);
+    expect((await readTerminalWorkerRecord(recordPath)).closing).toBeUndefined();
+  });
+
+  it("ends a session member its gone terminal program left behind, where sessions are reported", async () => {
+    const home = makeHome();
+    const member = spawnIdle(undefined, terminalEnv("t1"));
+    const goneProgramPid = await goneProcessPid();
+    const recordPath = writeRecord(home, {
+      pid: await goneProcessPid(),
+      terminals: [{ id: "t1", pid: goneProgramPid, startedAt: await birthOf(process.pid) }],
+    });
+
+    const result = await reapTerminalWorkers({
+      paseoHome: home,
+      inspector: withSessionMember({ memberPid: member.pid!, sessionId: goneProgramPid }),
+    });
+
+    await waitUntilGone(member.pid!);
+    expect(isAlive(member.pid!)).toBe(false);
+    expect(result.signaled).toContain(member.pid);
+    expect(existsSync(recordPath)).toBe(false);
+  });
+
+  it("leaves alive a later session that reuses a gone terminal program's session id", async () => {
+    const home = makeHome();
+    // Born after the recorded program, as any member of a later session is; only the missing
+    // terminal id tells it apart.
+    const member = spawnIdle(undefined, terminalEnv("another-terminal"));
+    const goneProgramPid = await goneProcessPid();
+    const recordPath = writeRecord(home, {
+      pid: await goneProcessPid(),
+      terminals: [{ id: "t1", pid: goneProgramPid, startedAt: "Thu Jan  1 00:00:00 1970" }],
+    });
+
+    const result = await reapTerminalWorkers({
+      paseoHome: home,
+      inspector: withSessionMember({ memberPid: member.pid!, sessionId: goneProgramPid }),
+    });
+
+    expect(isAlive(member.pid!)).toBe(true);
+    expect(result.signaled).toEqual([]);
+    expect(existsSync(recordPath)).toBe(false);
+  });
+
+  it("signals no session member it cannot identify, and keeps the cleanup unconfirmed", async () => {
+    const home = makeHome();
+    const member = spawnIdle(undefined, terminalEnv("t1"));
+    const goneProgramPid = await goneProcessPid();
+    writeRecord(home, {
+      pid: await goneProcessPid(),
+      terminals: [{ id: "t1", pid: goneProgramPid, startedAt: "Thu Jan  1 00:00:00 1970" }],
+    });
+
+    await expect(
+      reapTerminalWorkers({
+        paseoHome: home,
+        inspector: withSessionMember({
+          memberPid: member.pid!,
+          sessionId: goneProgramPid,
+          environmentUnreadable: true,
+        }),
+      }),
+    ).rejects.toBeInstanceOf(TerminalCleanupNotConfirmedError);
+
+    expect(isAlive(member.pid!)).toBe(true);
+    expect(await readUnconfirmedTerminalCleanup(home)).toEqual([
+      expect.objectContaining({ pid: goneProgramPid, reason: "inspection failed" }),
+    ]);
+  });
+
+  it("signals no session member whose environment carries no terminal id, and keeps the cleanup unconfirmed", async () => {
+    const home = makeHome();
+    // A job started with a scrubbed environment (`env -i`) carries no terminal id at all: it
+    // may still be this terminal's, so it is neither signaled nor dismissed as unrelated.
+    const member = spawnIdle(undefined, {});
+    const goneProgramPid = await goneProcessPid();
+    writeRecord(home, {
+      pid: await goneProcessPid(),
+      terminals: [{ id: "t1", pid: goneProgramPid, startedAt: "Thu Jan  1 00:00:00 1970" }],
+    });
+    const scrubbedMember = withSessionMember({ memberPid: member.pid!, sessionId: goneProgramPid });
+
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      await expect(
+        reapTerminalWorkers({ paseoHome: home, inspector: scrubbedMember }),
+      ).rejects.toBeInstanceOf(TerminalCleanupNotConfirmedError);
+      expect(isAlive(member.pid!)).toBe(true);
+      expect(await readUnconfirmedTerminalCleanup(home)).toEqual([
+        expect.objectContaining({
+          pid: goneProgramPid,
+          reason: "inspection failed",
+          detail: expect.stringContaining(`session member ${member.pid}`),
+        }),
+      ]);
+    }
+    expect(existsSync(terminalCleanupRecordPath(home, "record-under-test"))).toBe(true);
+  });
+
+  it("does not walk a gone terminal program's pid that another process took before the table was read", async () => {
+    const home = makeHome();
+    const member = spawnIdle(undefined, terminalEnv("t1"));
+    const goneProgramPid = await goneProcessPid();
+    writeRecord(home, {
+      pid: await goneProcessPid(),
+      terminals: [{ id: "t1", pid: goneProgramPid, startedAt: "Thu Jan  1 00:00:00 1970" }],
+    });
+
+    const result = await reapTerminalWorkers({
+      paseoHome: home,
+      inspector: withSessionMember({
+        memberPid: member.pid!,
+        sessionId: goneProgramPid,
+        reusedRoot: true,
+      }),
+    });
+
+    expect(isAlive(member.pid!)).toBe(true);
+    expect(result.signaled).toEqual([]);
+  });
+
+  // A kill cleanup that meets an unreadable worker record cannot check what it names and
+  // leaves nothing else behind, so status and retry must keep reporting it after a respawn.
+  it.each([
+    ["cleanup", (home: string) => terminalCleanupRecordPath(home, "record-under-test")],
+    ["worker", (home: string) => path.join(terminalWorkerDirectory(home), "4242.json")],
+  ])("never reports an unreadable %s record as finished", async (_kind, recordPathIn) => {
+    const home = makeHome();
+    mkdirSync(terminalWorkerDirectory(home), { recursive: true });
+    const unreadablePath = recordPathIn(home);
+    writeFileSync(unreadablePath, "{ not json");
+
+    for (const attempt of [
+      async () => await readUnconfirmedTerminalCleanup(home),
+      () => retryUnconfirmedTerminalCleanup(home),
+      () => reapTerminalWorkers({ paseoHome: home, inspector }),
+    ]) {
+      let caught: unknown;
+      try {
+        await attempt();
+      } catch (error) {
+        caught = error;
+      }
+      expect(caught).toBeInstanceOf(TerminalCleanupNotConfirmedError);
+      expect((caught as TerminalCleanupNotConfirmedError).unreadableRecords).toEqual([
+        expect.objectContaining({ path: unreadablePath }),
+      ]);
+    }
+    expect(existsSync(unreadablePath)).toBe(true);
+  });
+
+  it("signals nothing while the process table cannot be read, so a retry still ends the children", async () => {
+    const home = makeHome();
+    const { program, childPid } = await spawnProgramWithChild();
+    const recordPath = writeRecord(home, {
+      pid: await goneProcessPid(),
+      terminals: [{ id: "t1", pid: program.pid!, startedAt: await birthOf(program.pid!) }],
+    });
+    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),
+    };
+
+    await expect(
+      reapTerminalWorkers({ paseoHome: home, inspector: tableUnavailable }),
+    ).rejects.toBeInstanceOf(TerminalCleanupNotConfirmedError);
+
+    expect(isAlive(program.pid!)).toBe(true);
+    expect(isAlive(childPid)).toBe(true);
+    const kept = await readTerminalWorkerRecord(
+      terminalCleanupRecordPath(home, "record-under-test"),
+    );
+    expect(kept.closing?.unresolved.length).toBeGreaterThan(0);
+    expect(kept.terminals.map((entry) => entry.pid)).toEqual([program.pid]);
+
+    const retry = await reapTerminalWorkers({ paseoHome: home, inspector, gracefulMs: 0 });
+
+    await waitUntilGone(program.pid!);
+    await waitUntilGone(childPid);
+    expect(isAlive(program.pid!)).toBe(false);
+    expect(isAlive(childPid)).toBe(false);
+    expect(retry.signaled).toEqual(expect.arrayContaining([program.pid!, childPid]));
+    expect(existsSync(recordPath)).toBe(false);
+    expect(existsSync(terminalCleanupRecordPath(home, "record-under-test"))).toBe(false);
+  });
+
+  it("escalates to SIGKILL a program that ignores SIGHUP and SIGTERM", async () => {
+    const home = makeHome();
+    const stubborn = spawnIdle(`
+      process.on("SIGHUP", () => {});
+      process.on("SIGTERM", () => {});
+      setInterval(() => {}, 1e9);
+    `);
+    writeRecord(home, {
+      pid: await goneProcessPid(),
+      terminals: [{ id: "t1", pid: stubborn.pid!, startedAt: await birthOf(stubborn.pid!) }],
+    });
+
+    await reapTerminalWorkers({ paseoHome: home, inspector });
+
+    await waitUntilGone(stubborn.pid!);
+    expect(isAlive(stubborn.pid!)).toBe(false);
+  });
+
+  it.skipIf(process.getuid?.() === 0)(
+    "keeps the daemon event loop responsive while status retries an unreadable record",
+    async () => {
+      const home = makeHome();
+      const recordPath = writeRecord(home, { pid: process.pid });
+      chmodSync(recordPath, 0);
+      let serviced = false;
+      setImmediate(() => {
+        serviced = true;
+      });
+      try {
+        await expect(
+          Promise.resolve().then(() => readUnconfirmedTerminalCleanup(home)),
+        ).rejects.toBeInstanceOf(TerminalCleanupNotConfirmedError);
+        expect(serviced).toBe(true);
+      } finally {
+        chmodSync(recordPath, 0o600);
+      }
+    },
+  );
+
+  // chmod cannot make a file unreadable to root.
+  describe.skipIf(process.getuid?.() === 0)("a record that cannot be opened for a moment", () => {
+    it("still ends a live worker it names, then retires the record", async () => {
+      const home = makeHome();
+      const worker = spawn(
+        process.execPath,
+        [
+          "-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",
+        },
+      });
+      const record = await unreadableUntilReleased(recordPath);
+
+      record.release();
+      const result = await reapTerminalWorkers({ paseoHome: home, inspector, gracefulMs: 0 });
+      await record.restored;
+
+      await waitUntilGone(worker.pid!);
+      expect(isAlive(worker.pid!)).toBe(false);
+      expect(result.signaled).toContain(worker.pid!);
+      expect(existsSync(recordPath)).toBe(false);
+    });
+
+    it("confirms the cleanup of a worker that already exited, then retires the record", async () => {
+      const home = makeHome();
+      const program = spawnIdle();
+      const recordPath = writeRecord(home, {
+        pid: await goneProcessPid(),
+        terminals: [{ id: "t1", pid: program.pid!, startedAt: await birthOf(program.pid!) }],
+      });
+      const record = await unreadableUntilReleased(recordPath);
+
+      record.release();
+      const result = await reapTerminalWorkers({ paseoHome: home, inspector, gracefulMs: 0 });
+      await record.restored;
+
+      await waitUntilGone(program.pid!);
+      expect(isAlive(program.pid!)).toBe(false);
+      expect(result.retired).toBe(1);
+      expect(existsSync(recordPath)).toBe(false);
+    });
+
+    it("still reports a record that stays unreadable, and signals nothing it names", async () => {
+      const home = makeHome();
+      const worker = spawn(
+        process.execPath,
+        [
+          "-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",
+        },
+      });
+      chmodSync(recordPath, 0);
+
+      let caught: unknown;
+      try {
+        await reapTerminalWorkers({ paseoHome: home, inspector, gracefulMs: 0 });
+      } catch (error) {
+        caught = error;
+      }
+
+      expect(caught).toBeInstanceOf(TerminalCleanupNotConfirmedError);
+      expect((caught as TerminalCleanupNotConfirmedError).unreadableRecords).toEqual([
+        expect.objectContaining({ path: recordPath, error: expect.stringContaining("EACCES") }),
+      ]);
+      expect(isAlive(worker.pid!)).toBe(true);
+      chmodSync(recordPath, 0o600);
+      expect(existsSync(recordPath)).toBe(true);
+    });
+  });
+});
+
+// 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
new file mode 100644
index 0000000000..da229f9ddd
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-reaper.ts
@@ -0,0 +1,652 @@
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import treeKill from "tree-kill";
+import { writtenDuringThisBoot } from "../server/pid-lock.js";
+import { connectTerminalWorker } from "./terminal-worker-client.js";
+import { pruneTerminalWorkerRuntimes } from "./terminal-worker-runtime.js";
+import {
+  classifyTerminalProgramProcess,
+  identifyTerminalWorker,
+  authorizeTerminalWorkerTermination,
+  type ProcessOwnership,
+} from "./terminal-worker-ownership.js";
+import {
+  collectDescendants,
+  createTerminalWorkerProcessInspector,
+  type ProcessTableEntry,
+  type TerminalWorkerProcessInspector,
+} from "./terminal-worker-processes.js";
+import {
+  listTerminalWorkerRecords,
+  retireTerminalWorkerRecord,
+  terminalCleanupRecordPath,
+  writeTerminalCleanupRecord,
+  type TerminalCleanupUnresolved,
+  type TerminalWorkerRecord,
+  type TerminalWorkerRecordFile,
+  type TerminalWorkerTerminalEntry,
+} from "./terminal-worker-record.js";
+
+// The one kill path for terminal workers outside a connected daemon, and the one the daemon
+// 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 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
+//    program is gone, its session id can belong to a later session, so a member of a gone
+//    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. 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.
+
+const DEFAULT_GRACEFUL_MS = 5_000;
+const DEFAULT_CONFIRM_MS = 3_000;
+const POLL_INTERVAL_MS = 100;
+
+export interface UnresolvedTerminalProcess extends TerminalCleanupUnresolved {
+  recordPath: string;
+}
+
+// What a cleanup could not confirm, as a caller reports it: read here, or from the daemon
+// status of a host the caller cannot read itself.
+export interface UnconfirmedTerminalProcess {
+  pid: number;
+  role: string;
+  reason: string;
+  detail: string;
+}
+
+export interface UnreadableTerminalWorkerRecord {
+  path: string;
+  error: string;
+}
+
+export class TerminalCleanupNotConfirmedError extends Error {
+  readonly code = "TERMINAL_CLEANUP_NOT_CONFIRMED";
+  readonly unresolved: UnconfirmedTerminalProcess[];
+  readonly unreadableRecords: UnreadableTerminalWorkerRecord[];
+
+  constructor(
+    unresolved: UnconfirmedTerminalProcess[],
+    unreadableRecords: UnreadableTerminalWorkerRecord[] = [],
+  ) {
+    super(
+      [
+        "Terminal cleanup was not confirmed.",
+        ...(unresolved.length > 0
+          ? [
+              "These processes may still be running:",
+              ...unresolved.map(
+                (entry) => `  pid ${entry.pid} (${entry.role}): ${entry.reason} (${entry.detail})`,
+              ),
+              "Their record is kept; the next `paseo daemon stop` retries the cleanup.",
+            ]
+          : []),
+        ...(unreadableRecords.length > 0
+          ? [
+              "These records cannot be read, so the processes they name cannot be checked:",
+              ...unreadableRecords.map((entry) => `  ${entry.path}: ${entry.error}`),
+              "Repair or remove each once you have checked its processes are gone.",
+            ]
+          : []),
+      ].join("\n"),
+    );
+    this.name = "TerminalCleanupNotConfirmedError";
+    this.unresolved = unresolved;
+    this.unreadableRecords = unreadableRecords;
+  }
+}
+
+/**
+ * Retries the cleanup an earlier kill could not confirm (records marked closing), leaving any
+ * live worker a daemon controls alone. Throws TerminalCleanupNotConfirmedError when processes
+ * still survive, or when a record cannot be read, so a kill restart can report them.
+ */
+export async function retryUnconfirmedTerminalCleanup(paseoHome: string): Promise<void> {
+  const files = await listTerminalWorkerRecords(paseoHome);
+  const recordPaths = files.flatMap((file) =>
+    ("record" in file && file.record.closing) || "error" in file ? [file.path] : [],
+  );
+  if (recordPaths.length === 0) return;
+  await reapTerminalWorkers({ paseoHome, gracefulMs: 0, recordPaths });
+}
+
+/**
+ * What the last cleanup of this home could not confirm gone, as its closing records name it.
+ * Read without retrying, so a daemon can report it (daemon status) to clients that cannot read
+ * this home themselves. Throws TerminalCleanupNotConfirmedError when any record cannot be read,
+ * worker records included: a kill cleanup that met it could not check what it names, and a
+ * failed cleanup leaves nothing else behind, so the cleanup cannot be reported finished.
+ */
+export async function readUnconfirmedTerminalCleanup(
+  paseoHome: string,
+): Promise<UnresolvedTerminalProcess[]> {
+  const files = await listTerminalWorkerRecords(paseoHome);
+  const unresolved = files.flatMap((file) =>
+    "record" in file && file.record.closing
+      ? file.record.closing.unresolved.map((entry) => ({ ...entry, recordPath: file.path }))
+      : [],
+  );
+  const unreadable = files.flatMap((file) =>
+    "error" in file ? [{ path: file.path, error: file.error.message }] : [],
+  );
+  if (unreadable.length > 0) {
+    throw new TerminalCleanupNotConfirmedError(unresolved, unreadable);
+  }
+  return unresolved;
+}
+
+export interface TerminalWorkerReapResult {
+  records: number;
+  retired: number;
+  signaled: number[];
+}
+
+export interface ReapTerminalWorkersOptions {
+  paseoHome: string;
+  /** Time the worker gets to close its terminals before SIGKILL. 0 skips the shutdown request. */
+  gracefulMs?: number;
+  confirmMs?: number;
+  /** Limit cleanup to these record files. Defaults to every record in the home. */
+  recordPaths?: string[];
+  inspector?: TerminalWorkerProcessInspector;
+  log?: (message: string, fields?: Record<string, unknown>) => void;
+}
+
+interface Candidate {
+  pid: number;
+  startedAt: string | null;
+  role: UnresolvedTerminalProcess["role"];
+  terminalId: string;
+  state: ProcessOwnership;
+  // Set when this program's children could not be looked up: its cleanup is never reported
+  // confirmed, even once the program itself is gone, and its entry stays for the retry.
+  descendantsUnconfirmed: string | null;
+}
+
+interface CandidateDiscovery {
+  candidates: Candidate[];
+  // The process table could not be read, so no process of the record may be signaled yet.
+  tableError: string | null;
+}
+
+export async function reapTerminalWorkers(
+  options: ReapTerminalWorkersOptions,
+): Promise<TerminalWorkerReapResult> {
+  const inspector = options.inspector ?? createTerminalWorkerProcessInspector();
+  const gracefulMs = options.gracefulMs ?? DEFAULT_GRACEFUL_MS;
+  const confirmMs = options.confirmMs ?? DEFAULT_CONFIRM_MS;
+  const log = options.log ?? (() => {});
+  const wanted = options.recordPaths ? new Set(options.recordPaths) : null;
+  const result: TerminalWorkerReapResult = { records: 0, retired: 0, signaled: [] };
+  const unresolved: UnresolvedTerminalProcess[] = [];
+  const unreadable: UnreadableTerminalWorkerRecord[] = [];
+
+  for (const file of await listTerminalWorkerRecords(options.paseoHome)) {
+    if (wanted && !wanted.has(file.path)) continue;
+    result.records += 1;
+    if ("error" in file) {
+      // Nothing in an unreadable record can identify a process, so nothing may be signaled,
+      // and nothing it names can be confirmed gone.
+      log("Skipping unreadable terminal worker record", {
+        recordPath: file.path,
+        error: file.error.message,
+      });
+      unreadable.push({ path: file.path, error: file.error.message });
+      continue;
+    }
+    const outcome = await reapRecord({
+      paseoHome: options.paseoHome,
+      file,
+      inspector,
+      gracefulMs,
+      confirmMs,
+      log,
+    });
+    result.signaled.push(...outcome.signaled);
+    if (outcome.unresolved.length === 0) {
+      result.retired += 1;
+    } else {
+      unresolved.push(...outcome.unresolved);
+    }
+  }
+
+  // Copies of worker files no remaining record names belong to no worker now.
+  const pruned = await pruneTerminalWorkerRuntimes(options.paseoHome);
+  for (const failure of pruned.failed) {
+    log("Cannot remove a terminal worker copy; the next cleanup retries", failure);
+  }
+
+  if (unresolved.length > 0 || unreadable.length > 0) {
+    throw new TerminalCleanupNotConfirmedError(unresolved, unreadable);
+  }
+  return result;
+}
+
+type ReadableRecordFile = Extract<TerminalWorkerRecordFile, { record: TerminalWorkerRecord }>;
+
+interface ReapRecordInput {
+  paseoHome: string;
+  file: ReadableRecordFile;
+  inspector: TerminalWorkerProcessInspector;
+  gracefulMs: number;
+  confirmMs: number;
+  log: NonNullable<ReapTerminalWorkersOptions["log"]>;
+}
+
+async function reapRecord(
+  input: ReapRecordInput,
+): Promise<{ signaled: number[]; unresolved: UnresolvedTerminalProcess[] }> {
+  const { file, inspector, log } = input;
+  const { record } = file;
+  const recordPath = file.path;
+  if (!writtenDuringThisBoot({ startedAt: record.createdAt, bootId: record.bootId })) {
+    await retireTerminalWorkerRecord(file);
+    log("Retired terminal worker record from an earlier boot", { recordPath });
+    return { signaled: [], unresolved: [] };
+  }
+
+  const worker = await identifyTerminalWorker(record);
+  const discovery = await collectCandidates(record, inspector, log);
+  const tracked: TrackedProcesses = {
+    record,
+    inspector,
+    worker,
+    candidates: discovery.candidates,
+  };
+
+  if (discovery.tableError !== null) {
+    return await keepUnresolved(input, tracked, [], `not signaled: ${discovery.tableError}`);
+  }
+
+  const shutdownMs = shutdownWindow(tracked.worker, input.gracefulMs);
+  if (shutdownMs > 0) {
+    await requestWorkerShutdown(record, shutdownMs, log);
+  }
+  await waitUntilSettled(tracked, Date.now() + shutdownMs);
+
+  let signaled: number[] = [];
+  if (!isSettled(tracked)) {
+    signaled = await forceKillOwned(tracked, recordPath, log);
+    await waitUntilSettled(tracked, Date.now() + input.confirmMs);
+  }
+
+  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
+// were deliberately left alone.
+async function keepUnresolved(
+  input: Pick<ReapRecordInput, "paseoHome" | "file" | "log">,
+  tracked: TrackedProcesses,
+  signaled: number[],
+  notSignaled: string | null,
+): Promise<{ signaled: number[]; unresolved: UnresolvedTerminalProcess[] }> {
+  const { record } = tracked;
+  const { file, log } = input;
+  const recordPath = terminalCleanupRecordPath(input.paseoHome, record.recordId);
+  const { unresolved, remaining } = collectUnresolved(tracked, recordPath, notSignaled);
+  if (unresolved.length === 0) {
+    await retireTerminalWorkerRecord(file);
+    log("Terminal worker record cleaned up", { recordPath: file.path, signaled });
+    return { signaled, unresolved };
+  }
+  await writeTerminalCleanupRecord(input.paseoHome, {
+    ...record,
+    terminals: remaining,
+    closing: {
+      unresolved: unresolved.map(({ pid, role, reason, detail }) => ({
+        pid,
+        role,
+        reason,
+        detail,
+      })),
+    },
+  });
+  log("Terminal worker cleanup not confirmed; record kept", {
+    recordPath,
+    unresolved: unresolved.map((entry) => ({ pid: entry.pid, reason: entry.reason })),
+  });
+  return { signaled, unresolved };
+}
+
+interface TrackedProcesses {
+  record: TerminalWorkerRecord;
+  inspector: TerminalWorkerProcessInspector;
+  worker: ProcessOwnership;
+  candidates: Candidate[];
+}
+
+function isOpen(state: ProcessOwnership): boolean {
+  return state.status === "owned" || state.status === "unknown";
+}
+
+function isSettled(tracked: TrackedProcesses): boolean {
+  return !isOpen(tracked.worker) && tracked.candidates.every((c) => !isOpen(c.state));
+}
+
+async function refreshTracked(tracked: TrackedProcesses): Promise<void> {
+  if (isOpen(tracked.worker)) {
+    tracked.worker = await identifyTerminalWorker(tracked.record);
+  }
+  for (const candidate of tracked.candidates) {
+    if (isOpen(candidate.state)) {
+      candidate.state = classifyTerminalProgramProcess(
+        candidate,
+        await tracked.inspector.inspect(candidate.pid),
+      );
+    }
+  }
+}
+
+async function waitUntilSettled(tracked: TrackedProcesses, deadline: number): Promise<void> {
+  await refreshTracked(tracked);
+  while (!isSettled(tracked) && Date.now() < deadline) {
+    await delay(POLL_INTERVAL_MS);
+    await refreshTracked(tracked);
+  }
+}
+
+// SIGKILL every process still owned, re-inspecting each right before its signal.
+async function forceKillOwned(
+  tracked: TrackedProcesses,
+  recordPath: string,
+  log: NonNullable<ReapTerminalWorkersOptions["log"]>,
+): Promise<number[]> {
+  const { record, inspector } = tracked;
+  const signaled: number[] = [];
+  if (tracked.worker.status === "owned") {
+    tracked.worker = await authorizeTerminalWorkerTermination(record);
+    if (tracked.worker.status === "owned") {
+      await forceKillWorker(record.pid);
+      signaled.push(record.pid);
+      log("Force-killed terminal worker", { pid: record.pid, recordPath });
+    }
+  }
+  for (const candidate of tracked.candidates) {
+    if (candidate.state.status !== "owned") continue;
+    candidate.state = classifyTerminalProgramProcess(
+      candidate,
+      await inspector.inspect(candidate.pid),
+    );
+    if (candidate.state.status !== "owned") continue;
+    forceKillProgram(candidate.pid);
+    signaled.push(candidate.pid);
+    log("Force-killed terminal program", {
+      pid: candidate.pid,
+      terminalId: candidate.terminalId,
+      recordPath,
+    });
+  }
+  return signaled;
+}
+
+function collectUnresolved(
+  tracked: TrackedProcesses,
+  recordPath: string,
+  notSignaled: string | null,
+): { unresolved: UnresolvedTerminalProcess[]; remaining: TerminalWorkerTerminalEntry[] } {
+  const unresolved: UnresolvedTerminalProcess[] = [];
+  if (isOpen(tracked.worker)) {
+    unresolved.push(
+      describeUnresolved({
+        pid: tracked.record.pid,
+        role: "worker",
+        state: tracked.worker,
+        recordPath,
+        notSignaled,
+      }),
+    );
+  }
+  const remaining: TerminalWorkerTerminalEntry[] = [];
+  for (const candidate of tracked.candidates) {
+    const stillOpen = isOpen(candidate.state);
+    if (!stillOpen && candidate.descendantsUnconfirmed === null) continue;
+    unresolved.push(
+      stillOpen
+        ? describeUnresolved({
+            pid: candidate.pid,
+            role: candidate.role,
+            state: candidate.state,
+            recordPath,
+            notSignaled,
+          })
+        : {
+            pid: candidate.pid,
+            role: candidate.role,
+            reason: "inspection failed",
+            detail: candidate.descendantsUnconfirmed!,
+            recordPath,
+          },
+    );
+    remaining.push({
+      id: candidate.terminalId,
+      pid: candidate.pid,
+      startedAt: candidate.startedAt,
+    });
+  }
+  return { unresolved, remaining };
+}
+
+async function collectCandidates(
+  record: TerminalWorkerRecord,
+  inspector: TerminalWorkerProcessInspector,
+  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,
+      startedAt: entry.startedAt,
+      role: "terminal program",
+      terminalId: entry.id,
+      state: classifyTerminalProgramProcess(entry, await inspector.inspect(entry.pid)),
+      descendantsUnconfirmed: null,
+    });
+  }
+  // Owned programs are walked through the table. Where sessions are reported, so are programs
+  // 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" && c.startedAt !== null && inspector.reportsSessions),
+  );
+  if (roots.length === 0) return { candidates: Array.from(candidates.values()), tableError: null };
+
+  let snapshot: ProcessTableEntry[];
+  try {
+    snapshot = await inspector.listProcesses();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    log("Cannot list processes for terminal cleanup", { error: message });
+    for (const root of roots) {
+      root.descendantsUnconfirmed = `its child processes could not be listed: ${message}`;
+    }
+    return {
+      candidates: Array.from(candidates.values()),
+      tableError: `process table unavailable: ${message}`,
+    };
+  }
+  for (const root of roots) {
+    const inTable = snapshot.find((entry) => entry.pid === root.pid);
+    if (inTable && inTable.startedAt !== root.startedAt) {
+      // The program ended and its pid was reused before the snapshot: what is below that pid
+      // now belongs to someone else, and the old session ended with every member of it.
+      log("Not walking a terminal program pid reused before the process table was read", {
+        pid: root.pid,
+        terminalId: root.terminalId,
+      });
+      continue;
+    }
+    if (!inTable && !inspector.reportsSessions) continue;
+    // Below a live program its parent links prove ownership. Once it is gone, its session id
+    // may have been reused by a later session, so each member must carry the terminal's id.
+    const rootGone = !inTable;
+    for (const descendant of collectDescendants(snapshot, root.pid)) {
+      if (candidates.has(descendant.pid)) continue;
+      if (rootGone) {
+        const proof = await proveTerminalMember(inspector, descendant.pid, root.terminalId);
+        if (proof.status === "gone") continue;
+        if (proof.status === "unknown") {
+          root.descendantsUnconfirmed = `session member ${descendant.pid} cannot be identified: ${proof.reason}`;
+          continue;
+        }
+        if (proof.status === "unrelated") {
+          log("Ignoring a session member that does not carry its terminal's id", {
+            pid: descendant.pid,
+            terminalId: root.terminalId,
+          });
+          continue;
+        }
+      }
+      candidates.set(descendant.pid, {
+        pid: descendant.pid,
+        startedAt: descendant.startedAt,
+        role: "terminal program",
+        terminalId: root.terminalId,
+        state: { status: "owned" },
+        descendantsUnconfirmed: null,
+      });
+    }
+  }
+  return { candidates: Array.from(candidates.values()), tableError: null };
+}
+
+// A terminal's programs inherit PASEO_TERMINAL_ID (terminal-manager.ts) from its PTY program.
+// A process in a later session that happens to reuse the session id does not carry it.
+async function proveTerminalMember(
+  inspector: TerminalWorkerProcessInspector,
+  pid: number,
+  terminalId: string,
+): Promise<ProcessOwnership> {
+  let environment: string[] | null;
+  try {
+    environment = await inspector.readEnvironment(pid);
+  } catch (error) {
+    return {
+      status: "unknown",
+      reason: `environment unreadable: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  if (environment === null) return { status: "gone" };
+  if (environment.includes(`PASEO_TERMINAL_ID=${terminalId}`)) return { status: "owned" };
+  // Another terminal's id proves the process belongs elsewhere. No id at all proves nothing: a
+  // job started with a scrubbed environment (`env -i`) can still be this terminal's.
+  return environment.some((entry) => entry.startsWith("PASEO_TERMINAL_ID="))
+    ? { status: "unrelated", reason: "environment carries another terminal's id" }
+    : { status: "unknown", reason: "its environment carries no terminal id" };
+}
+
+async function requestWorkerShutdown(
+  record: TerminalWorkerRecord,
+  gracefulMs: number,
+  log: NonNullable<ReapTerminalWorkersOptions["log"]>,
+): Promise<void> {
+  const deadline = Date.now() + gracefulMs;
+  let connection;
+  try {
+    connection = await connectTerminalWorker({
+      socketPath: record.socketPath,
+      secret: record.secret,
+      timeoutMs: Math.min(gracefulMs, 2_000),
+    });
+  } catch (error) {
+    // 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,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return;
+  }
+  const responded = new Promise<void>((resolve) => {
+    connection.on("message", (message) => {
+      if (message.type === "response") resolve();
+    });
+  });
+  const closed = new Promise<void>((resolve) => connection.on("close", () => resolve()));
+  const sendFailed = new Promise<void>((resolve) => {
+    connection.send({ type: "shutdown", requestId: randomUUID() }, (error) => {
+      if (error) resolve();
+    });
+  });
+  const timeout = new AbortController();
+  await Promise.race([
+    responded,
+    closed,
+    sendFailed,
+    delay(Math.max(0, deadline - Date.now()), undefined, { signal: timeout.signal }).catch(
+      () => undefined,
+    ),
+  ]);
+  timeout.abort();
+  connection.disconnect();
+}
+
+function forceKillWorker(pid: number): Promise<void> {
+  if (process.platform === "win32") {
+    return new Promise((resolve) => {
+      treeKill(pid, "SIGKILL", () => resolve());
+    });
+  }
+  signalIgnoringMissing(pid, "SIGKILL");
+  return Promise.resolve();
+}
+
+function forceKillProgram(pid: number): void {
+  if (process.platform !== "win32") {
+    // A PTY program leads its own session and process group. The group cannot outlive its
+    // leader's pid while any member is alive, so it holds nothing but this program's job.
+    signalIgnoringMissing(-pid, "SIGKILL");
+  }
+  signalIgnoringMissing(pid, "SIGKILL");
+}
+
+function signalIgnoringMissing(pid: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(pid, signal);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "ESRCH" && code !== "EPERM") throw error;
+  }
+}
+
+function describeUnresolved(input: {
+  pid: number;
+  role: UnresolvedTerminalProcess["role"];
+  state: ProcessOwnership;
+  recordPath: string;
+  notSignaled: string | null;
+}): UnresolvedTerminalProcess {
+  const { pid, role, state, recordPath, notSignaled } = input;
+  if (state.status === "unknown") {
+    return { pid, role, reason: "inspection failed", detail: state.reason, recordPath };
+  }
+  if (notSignaled !== null) {
+    return { pid, role, reason: "inspection failed", detail: notSignaled, recordPath };
+  }
+  return { pid, role, reason: "still alive", detail: "survived SIGKILL", recordPath };
+}
diff --git a/packages/server/src/terminal/terminal-worker-record-publisher.test.ts b/packages/server/src/terminal/terminal-worker-record-publisher.test.ts
new file mode 100644
index 0000000000..dba50b9efe
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-record-publisher.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { setTimeout as delay } from "node:timers/promises";
+import { createTerminalWorkerRecordPublisher } from "./terminal-worker-record-publisher.js";
+import type { TerminalWorkerRecord } from "./terminal-worker-record.js";
+
+const record: TerminalWorkerRecord = {
+  recordId: "worker",
+  pid: 123,
+  bootId: null,
+  createdAt: "now",
+  identity: { startedAt: "now", commandLine: "worker" },
+  protocolVersion: 1,
+  paseoVersion: "test",
+  socketPath: "socket",
+  secret: "secret",
+  terminals: [{ id: "terminal", pid: 124, startedAt: "now" }],
+};
+
+describe("live worker record publication", () => {
+  it.each(["EPERM", "EBUSY", "EACCES"])(
+    "publishes the latest state after %s contention clears",
+    async (code) => {
+      let locked = true;
+      const written: TerminalWorkerRecord[] = [];
+      const publisher = createTerminalWorkerRecordPublisher((state) => {
+        if (locked) throw Object.assign(new Error("reader holds record"), { code });
+        written.push(state);
+      });
+      try {
+        const creation = publisher.publish(record);
+        const exited = { ...record, terminals: [] };
+        const exit = publisher.publish(exited);
+        expect(written).toEqual([]);
+        locked = false;
+        await Promise.all([creation, exit]);
+        expect(written).toEqual([exited]);
+      } finally {
+        publisher.stop();
+      }
+    },
+  );
+
+  it("does not recreate a retired record when a reader releases it", async () => {
+    let locked = true;
+    const written: TerminalWorkerRecord[] = [];
+    const publisher = createTerminalWorkerRecordPublisher((state) => {
+      if (locked)
+        throw Object.assign(new Error("reader holds record"), {
+          code: "EPERM",
+        });
+      written.push(state);
+    });
+    const pending = publisher.publish(record);
+    const rejected = expect(pending).rejects.toThrow("stopped");
+    publisher.stop();
+    locked = false;
+    await rejected;
+    await delay(50);
+    expect(written).toEqual([]);
+    await expect(publisher.publish(record)).rejects.toThrow("stopped");
+  });
+
+  it("reports permanent storage failures without retrying", async () => {
+    const publisher = createTerminalWorkerRecordPublisher(() => {
+      throw Object.assign(new Error("disk full"), { code: "ENOSPC" });
+    });
+    await expect(publisher.publish(record)).rejects.toThrow("disk full");
+    publisher.stop();
+  });
+});
diff --git a/packages/server/src/terminal/terminal-worker-record-publisher.ts b/packages/server/src/terminal/terminal-worker-record-publisher.ts
new file mode 100644
index 0000000000..415c785102
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-record-publisher.ts
@@ -0,0 +1,62 @@
+import type { TerminalWorkerRecord } from "./terminal-worker-record.js";
+
+const TRANSIENT_ERRORS = new Set(["EPERM", "EBUSY", "EACCES"]);
+
+/** Serializes live worker publication, retaining the latest state across reader contention.
+ * Creation awaits publication; exit notifications need not wait for a reader to close.
+ * Stop before retiring the record so a pending retry cannot recreate it.
+ */
+export function createTerminalWorkerRecordPublisher(write: (record: TerminalWorkerRecord) => void) {
+  let stopped = false;
+  let latest: TerminalWorkerRecord;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let pending:
+    | {
+        promise: Promise<void>;
+        resolve: () => void;
+        reject: (error: unknown) => void;
+      }
+    | undefined;
+
+  function attempt(): void {
+    timer = undefined;
+    const publication = pending;
+    if (!publication) return;
+    try {
+      write(latest);
+      publication.resolve();
+      pending = undefined;
+    } catch (error) {
+      if (TRANSIENT_ERRORS.has((error as NodeJS.ErrnoException).code ?? "")) {
+        timer = setTimeout(attempt, 25);
+      } else {
+        publication.reject(error);
+        pending = undefined;
+      }
+    }
+  }
+
+  return {
+    publish(record: TerminalWorkerRecord): Promise<void> {
+      if (stopped) return Promise.reject(new Error("Worker record publisher stopped"));
+      latest = record;
+      if (pending) return pending.promise;
+      let resolve!: () => void;
+      let reject!: (error: unknown) => void;
+      const promise = new Promise<void>((yes, no) => {
+        resolve = yes;
+        reject = no;
+      });
+      pending = { promise, resolve, reject };
+      attempt();
+      return promise;
+    },
+    stop(): void {
+      stopped = true;
+      clearTimeout(timer);
+      timer = undefined;
+      pending?.reject(new Error("Worker record publisher stopped"));
+      pending = undefined;
+    },
+  };
+}
diff --git a/packages/server/src/terminal/terminal-worker-record.ts b/packages/server/src/terminal/terminal-worker-record.ts
new file mode 100644
index 0000000000..63ac0ddd91
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-record.ts
@@ -0,0 +1,233 @@
+import { readdir, readFile, rm } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import path from "node:path";
+import { z } from "zod";
+import { writePrivateFileAtomicSync, writePrivateFileAtomic } from "../server/private-files.js";
+
+// 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
+// client reading daemon status) can name it.
+const TerminalCleanupUnresolvedSchema = z.object({
+  pid: z.number().int().positive(),
+  role: z.enum(["worker", "terminal program"]),
+  reason: z.enum(["still alive", "inspection failed"]),
+  detail: z.string(),
+});
+
+const TerminalWorkerRecordSchema = z.object({
+  recordId: z.string().min(1),
+  pid: z.number().int().positive(),
+  bootId: z.string().nullable(),
+  createdAt: 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()]),
+  paseoVersion: z.string(),
+  socketPath: z.string().min(1),
+  secret: z.string().min(1),
+  // The copy of the worker's files it runs from (a directory name under terminal-worker/), or
+  // null when it runs from source. A copy named by any record is never deleted.
+  runtime: z.string().nullable().optional(),
+  terminals: z.array(TerminalWorkerTerminalEntrySchema),
+  // Set only in a cleanup record (below), with what a cleanup could not confirm gone. A record
+  // marked closing is never adopted: the next daemon or stop retries the cleanup instead.
+  closing: z.object({ unresolved: z.array(TerminalCleanupUnresolvedSchema).min(1) }).optional(),
+});
+
+export type TerminalWorkerTerminalEntry = z.infer<typeof TerminalWorkerTerminalEntrySchema>;
+export type TerminalCleanupUnresolved = z.infer<typeof TerminalCleanupUnresolvedSchema>;
+export type TerminalWorkerRecord = z.infer<typeof TerminalWorkerRecordSchema>;
+
+// A worker record (`<pid>.json`) belongs to the worker, which rewrites it from memory whenever
+// a terminal starts or exits. A cleanup that cannot confirm every process gone therefore keeps
+// its state in a cleanup record of its own (`closing-<recordId>.json`) that no worker writes, so
+// the kill intent and what it could not confirm survive any later worker rewrite.
+type TerminalWorkerRecordKind = "worker" | "cleanup";
+
+export type TerminalWorkerRecordFile =
+  | {
+      // The file holding this record's state: the cleanup record when there is one.
+      path: string;
+      record: TerminalWorkerRecord;
+      // The worker's own record file, when it still exists.
+      workerRecordPath: string | null;
+    }
+  | { path: string; error: Error };
+
+// The worker's command line carries this marker followed by its record id, so a reused pid
+// running some other process (even another worker) never matches the record.
+export const TERMINAL_WORKER_MARKER_ARG = "--paseo-terminal-worker";
+
+export function terminalWorkerDirectory(paseoHome: string): string {
+  return path.join(paseoHome, "terminal-worker");
+}
+
+export function terminalWorkerRecordPath(paseoHome: string, workerPid: number): string {
+  return path.join(terminalWorkerDirectory(paseoHome), `${workerPid}.json`);
+}
+
+export function terminalCleanupRecordPath(paseoHome: string, recordId: string): string {
+  return path.join(terminalWorkerDirectory(paseoHome), `closing-${recordId}.json`);
+}
+
+export function terminalWorkerLogPath(paseoHome: string): string {
+  return path.join(paseoHome, "terminal-worker.log");
+}
+
+export function writeTerminalWorkerRecord(paseoHome: string, record: TerminalWorkerRecord): string {
+  const recordPath = terminalWorkerRecordPath(paseoHome, record.pid);
+  writePrivateFileAtomicSync(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+  return recordPath;
+}
+
+/** Writes the state of a cleanup that could not confirm every process gone. */
+export async function writeTerminalCleanupRecord(
+  paseoHome: string,
+  record: TerminalWorkerRecord & { closing: NonNullable<TerminalWorkerRecord["closing"]> },
+): Promise<string> {
+  if (!RECORD_ID_PATTERN.test(record.recordId)) {
+    throw new Error(`Terminal worker record id is not a file name: ${record.recordId}`);
+  }
+  const recordPath = terminalCleanupRecordPath(paseoHome, record.recordId);
+  await writePrivateFileAtomic(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+  return recordPath;
+}
+
+export async function readTerminalWorkerRecord(recordPath: string): Promise<TerminalWorkerRecord> {
+  return TerminalWorkerRecordSchema.parse(JSON.parse(await readRecordFile(recordPath)));
+}
+
+// A worker rewrites its record by renaming a new file over it. On Windows an open() that races
+// that rename fails with EPERM (or EBUSY) for a moment, so such an error is retried for a short
+// window before the record counts as unreadable. Reads and retries yield so daemon status and
+// cleanup never block unrelated requests while another process holds the record open.
+const TRANSIENT_READ_ERRORS = new Set(["EPERM", "EBUSY", "EACCES"]);
+const TRANSIENT_READ_WINDOW_MS = 250;
+const TRANSIENT_READ_PAUSE_MS = 10;
+
+async function readRecordFile(recordPath: string): Promise<string> {
+  const deadline = Date.now() + TRANSIENT_READ_WINDOW_MS;
+  for (;;) {
+    try {
+      return await readFile(recordPath, "utf8");
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (!code || !TRANSIENT_READ_ERRORS.has(code) || Date.now() >= deadline) throw error;
+      await delay(TRANSIENT_READ_PAUSE_MS);
+    }
+  }
+}
+
+const RECORD_ID_PATTERN = /^[A-Za-z0-9-]+$/;
+const WORKER_RECORD_NAME = /^\d+\.json$/;
+const CLEANUP_RECORD_NAME = /^closing-[A-Za-z0-9-]+\.json$/;
+
+function recordKindOf(fileName: string): TerminalWorkerRecordKind | null {
+  if (WORKER_RECORD_NAME.test(fileName)) return "worker";
+  if (CLEANUP_RECORD_NAME.test(fileName)) return "cleanup";
+  return null;
+}
+
+/**
+ * Every record in the home. A cleanup record is merged with the worker record of the same
+ * record id: its closing state wins, and terminals the worker recorded since join it, so the
+ * retry covers everything the worker still runs.
+ */
+export async function listTerminalWorkerRecords(
+  paseoHome: string,
+): Promise<TerminalWorkerRecordFile[]> {
+  const directory = terminalWorkerDirectory(paseoHome);
+  let names: string[];
+  try {
+    names = await readdir(directory);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+  const errors: TerminalWorkerRecordFile[] = [];
+  const workers: Array<{ path: string; record: TerminalWorkerRecord }> = [];
+  const cleanups: Array<{ path: string; record: TerminalWorkerRecord }> = [];
+  for (const name of names.sort()) {
+    const kind = recordKindOf(name);
+    if (!kind) continue;
+    const recordPath = path.join(directory, name);
+    try {
+      const record = await readTerminalWorkerRecord(recordPath);
+      (kind === "worker" ? workers : cleanups).push({ path: recordPath, record });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      errors.push({
+        path: recordPath,
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+    }
+  }
+  const files: TerminalWorkerRecordFile[] = [];
+  const merged = new Set<string>();
+  for (const cleanup of cleanups) {
+    const worker = workers.find(
+      (entry) =>
+        entry.record.recordId === cleanup.record.recordId &&
+        entry.record.pid === cleanup.record.pid,
+    );
+    if (worker) merged.add(worker.path);
+    const known = new Set(cleanup.record.terminals.map((entry) => `${entry.id}:${entry.pid}`));
+    const added = (worker?.record.terminals ?? []).filter(
+      (entry) => !known.has(`${entry.id}:${entry.pid}`),
+    );
+    files.push({
+      path: cleanup.path,
+      record: { ...cleanup.record, terminals: [...cleanup.record.terminals, ...added] },
+      workerRecordPath: worker?.path ?? null,
+    });
+  }
+  for (const worker of workers) {
+    if (merged.has(worker.path)) continue;
+    files.push({ path: worker.path, record: worker.record, workerRecordPath: worker.path });
+  }
+  return [...files, ...errors];
+}
+
+/**
+ * Deletes a record, the worker's own record file and the socket it names, unless a later worker
+ * that reused the pid wrote that file since. The pipe namespace on Windows needs no unlink.
+ */
+export async function retireTerminalWorkerRecord(file: {
+  path: string;
+  record: TerminalWorkerRecord;
+  workerRecordPath: string | null;
+}): Promise<void> {
+  if (file.path !== file.workerRecordPath) await rm(file.path, { force: true });
+  if (file.workerRecordPath) {
+    if (await workerRecordNamesAnother(file.workerRecordPath, file.record.recordId)) return;
+    await rm(file.workerRecordPath, { force: true });
+  }
+  if (process.platform !== "win32") {
+    await rm(file.record.socketPath, { force: true });
+  }
+}
+
+// True when the file now belongs to another worker, or cannot be read to tell.
+async function workerRecordNamesAnother(recordPath: string, recordId: string): Promise<boolean> {
+  try {
+    return (await readTerminalWorkerRecord(recordPath)).recordId !== recordId;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ENOENT";
+  }
+}
diff --git a/packages/server/src/terminal/terminal-worker-runtime.test.ts b/packages/server/src/terminal/terminal-worker-runtime.test.ts
new file mode 100644
index 0000000000..257787b944
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-runtime.test.ts
@@ -0,0 +1,224 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { builtinModules } from "node:module";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isPlatform } from "../test-utils/platform.js";
+import {
+  prepareTerminalWorkerRuntime,
+  pruneTerminalWorkerRuntimes,
+  TerminalWorkerRuntimeError,
+} from "./terminal-worker-runtime.js";
+import {
+  terminalWorkerDirectory,
+  writeTerminalWorkerRecord,
+  type TerminalWorkerRecord,
+} from "./terminal-worker-record.js";
+
+const temporaryDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of temporaryDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function makeDir(prefix: string): string {
+  const dir = mkdtempSync(path.join(tmpdir(), prefix));
+  temporaryDirs.push(dir);
+  return dir;
+}
+
+// A built bundle directory and a node-pty package shaped like the real ones.
+function makeSources(bundleSource = "export {};\n"): {
+  bundleDirectory: string;
+  nodePtyDirectory: string;
+} {
+  const bundleDirectory = makeDir("tw-bundle-");
+  writeFileSync(path.join(bundleDirectory, "terminal-worker.mjs"), bundleSource);
+  mkdirSync(path.join(bundleDirectory, "shell-integration", "zsh"), { recursive: true });
+  writeFileSync(path.join(bundleDirectory, "shell-integration", "zsh", ".zshenv"), "# zsh\n");
+  const nodePtyDirectory = makeDir("tw-node-pty-");
+  writeFileSync(path.join(nodePtyDirectory, "package.json"), '{"version":"1.2.3"}\n');
+  mkdirSync(path.join(nodePtyDirectory, "lib"));
+  writeFileSync(path.join(nodePtyDirectory, "lib", "index.js"), "module.exports = {};\n");
+  const native = path.join(nodePtyDirectory, "prebuilds", `${process.platform}-${process.arch}`);
+  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 };
+}
+
+function recordNaming(runtime: string | null, pid = 4242): TerminalWorkerRecord {
+  return {
+    recordId: `record-${pid}`,
+    pid,
+    bootId: null,
+    createdAt: new Date().toISOString(),
+    identity: { startedAt: "Thu Jan  1 00:00:00 1970", commandLine: "worker" },
+    protocolVersion: 1,
+    paseoVersion: "1.0.0",
+    socketPath: "/tmp/does-not-exist.sock",
+    secret: "secret",
+    runtime,
+    terminals: [],
+  };
+}
+
+describe("terminal worker runtime copy", () => {
+  it("copies the bundle, its shell integration and this platform's node-pty into the home", () => {
+    const home = makeDir("tw-runtime-home-");
+    const entry = prepareTerminalWorkerRuntime({
+      paseoHome: home,
+      paseoVersion: "1.0.0-beta.1",
+      ...makeSources(),
+    });
+
+    const directory = path.join(terminalWorkerDirectory(home), entry.runtime!);
+    expect(entry.runtime).toMatch(/^1\.0\.0-beta\.1-[0-9a-f]{12}$/);
+    expect(entry.scriptPath).toBe(path.join(directory, "terminal-worker.mjs"));
+    expect(entry.execArgv).toEqual([]);
+    expect(existsSync(path.join(directory, "shell-integration", "zsh", ".zshenv"))).toBe(true);
+    const nodePty = path.join(directory, "node_modules", "node-pty");
+    expect(existsSync(path.join(nodePty, "lib", "index.js"))).toBe(true);
+    expect(readdirSync(path.join(nodePty, "prebuilds"))).toEqual([
+      `${process.platform}-${process.arch}`,
+    ]);
+    if (!isPlatform("win32")) {
+      const helper = path.join(nodePty, "prebuilds", `${process.platform}-${process.arch}`);
+      expect(statSync(path.join(helper, "spawn-helper")).mode & 0o111).toBe(0o111);
+    }
+  });
+
+  it("reuses a finished copy of the same content and makes a new one for a different build", () => {
+    const home = makeDir("tw-runtime-home-");
+    const sources = makeSources();
+    const first = prepareTerminalWorkerRuntime({
+      paseoHome: home,
+      paseoVersion: "1.0.0",
+      ...sources,
+    });
+    const marker = path.join(terminalWorkerDirectory(home), first.runtime!, "terminal-worker.mjs");
+    writeFileSync(marker, "// the running copy\n");
+
+    const again = prepareTerminalWorkerRuntime({
+      paseoHome: home,
+      paseoVersion: "1.0.0",
+      ...sources,
+    });
+    const rebuilt = prepareTerminalWorkerRuntime({
+      paseoHome: home,
+      paseoVersion: "1.0.0",
+      ...makeSources("export const rebuilt = true;\n"),
+    });
+
+    expect(again.runtime).toBe(first.runtime);
+    expect(statSync(marker).size).toBe("// the running copy\n".length);
+    expect(rebuilt.runtime).not.toBe(first.runtime);
+  });
+
+  it("replaces a copy an earlier run left unfinished", () => {
+    const home = makeDir("tw-runtime-home-");
+    const sources = makeSources();
+    const first = prepareTerminalWorkerRuntime({
+      paseoHome: home,
+      paseoVersion: "1.0.0",
+      ...sources,
+    });
+    const directory = path.join(terminalWorkerDirectory(home), first.runtime!);
+    rmSync(directory, { recursive: true });
+    mkdirSync(directory);
+
+    prepareTerminalWorkerRuntime({ paseoHome: home, paseoVersion: "1.0.0", ...sources });
+
+    expect(existsSync(path.join(directory, "terminal-worker.mjs"))).toBe(true);
+  });
+
+  it("fails before copying anything when node-pty has no native build for this platform", () => {
+    const home = makeDir("tw-runtime-home-");
+    const sources = makeSources();
+    rmSync(path.join(sources.nodePtyDirectory, "prebuilds"), { recursive: true });
+
+    expect(() =>
+      prepareTerminalWorkerRuntime({ paseoHome: home, paseoVersion: "1.0.0", ...sources }),
+    ).toThrow(TerminalWorkerRuntimeError);
+    expect(readdirSync(terminalWorkerDirectory(home))).toEqual([]);
+  });
+
+  it("removes only copies no worker record names", async () => {
+    const home = makeDir("tw-runtime-home-");
+    const used = prepareTerminalWorkerRuntime({
+      paseoHome: home,
+      paseoVersion: "1.0.0",
+      ...makeSources(),
+    });
+    const unused = prepareTerminalWorkerRuntime({
+      paseoHome: home,
+      paseoVersion: "0.9.0",
+      ...makeSources(),
+    });
+    writeTerminalWorkerRecord(home, recordNaming(used.runtime));
+    const socketDirectory = path.join(terminalWorkerDirectory(home), "sock");
+    mkdirSync(socketDirectory);
+
+    const result = await pruneTerminalWorkerRuntimes(home);
+
+    expect(result.removed).toEqual([path.join(terminalWorkerDirectory(home), unused.runtime!)]);
+    expect(existsSync(path.dirname(used.scriptPath))).toBe(true);
+    expect(existsSync(socketDirectory)).toBe(true);
+  });
+
+  it("removes nothing while a record cannot be read", async () => {
+    const home = makeDir("tw-runtime-home-");
+    const copy = prepareTerminalWorkerRuntime({
+      paseoHome: home,
+      paseoVersion: "1.0.0",
+      ...makeSources(),
+    });
+    writeFileSync(path.join(terminalWorkerDirectory(home), "4242.json"), "{ not json");
+
+    expect((await pruneTerminalWorkerRuntimes(home)).removed).toEqual([]);
+    expect(existsSync(copy.scriptPath)).toBe(true);
+  });
+});
+
+describe("terminal worker bundle", () => {
+  // The copy holds the bundle and node-pty only. A package the bundle loads at run time
+  // (a require hidden from esbuild behind createRequire) would be missing from it.
+  it("loads nothing at run time but Node built-ins and node-pty", async () => {
+    const outDir = makeDir("tw-bundle-build-");
+    const script = fileURLToPath(
+      new URL("../../scripts/build-terminal-worker.mjs", import.meta.url),
+    );
+    const { buildTerminalWorkerBundle } = (await import(script)) as {
+      buildTerminalWorkerBundle(input: { outDir: string }): Promise<void>;
+    };
+    await buildTerminalWorkerBundle({ outDir });
+
+    const bundle = readFileSync(path.join(outDir, "terminal-worker.mjs"), "utf8");
+    const loaded = new Set<string>();
+    for (const match of bundle.matchAll(
+      /(?:\brequire\w*(?:\.resolve)?\(|\bfrom\s+|\bimport\s*\()\s*"([^"]+)"/g,
+    )) {
+      loaded.add(match[1]!);
+    }
+    const builtins = new Set(builtinModules.flatMap((name) => [name, `node:${name}`]));
+    const packages = [...loaded].filter((specifier) => !builtins.has(specifier));
+    expect(packages.map((specifier) => specifier.split("/")[0])).toEqual(
+      packages.map(() => "node-pty"),
+    );
+    expect(existsSync(path.join(outDir, "shell-integration", "zsh"))).toBe(true);
+  });
+});
diff --git a/packages/server/src/terminal/terminal-worker-runtime.ts b/packages/server/src/terminal/terminal-worker-runtime.ts
new file mode 100644
index 0000000000..7ee0696478
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-runtime.ts
@@ -0,0 +1,249 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { access, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensurePrivateDirectory } from "../server/private-files.js";
+import { listTerminalWorkerRecords, terminalWorkerDirectory } from "./terminal-worker-record.js";
+
+// A terminal worker outlives the installation that started it. An npm or desktop update
+// replaces that installation's files, so a worker launched from them would fail its next
+// terminal create (node-pty's spawn-helper, the zsh integration). A built daemon therefore
+// copies the worker bundle, its shell integration and node-pty into
+// $PASEO_HOME/terminal-worker/<paseoVersion>-<content hash>/ and launches the worker from there.
+// The hash keeps two builds of one version (a local rebuild) from sharing a copy. A copy is
+// removed once no worker record names it: after a worker drains, after a kill cleanup, and at
+// daemon start. Dev runs (.ts source) launch from source and copy nothing.
+
+export const TERMINAL_WORKER_BUNDLE_NAME = "terminal-worker.mjs";
+// Written last into a finished copy; a directory without it is an interrupted copy.
+const RUNTIME_MARKER = "paseo-terminal-worker-runtime.json";
+const TEMP_PREFIX = ".tmp-";
+
+export class TerminalWorkerRuntimeError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "TerminalWorkerRuntimeError";
+  }
+}
+
+/** What the launcher runs: the worker script, the node flags it needs, and the copy it is in. */
+export interface TerminalWorkerEntry {
+  scriptPath: string;
+  execArgv: string[];
+  /** The copy's directory name under terminal-worker/, or null when run from source. */
+  runtime: string | null;
+}
+
+function sourceExecArgv(): string[] {
+  const loaderUrl = new URL("./terminal-ts-loader.mjs", import.meta.url).href;
+  const importSource = [
+    'import { register } from "node:module";',
+    'import { pathToFileURL } from "node:url";',
+    `register(${JSON.stringify(loaderUrl)}, pathToFileURL("./"));`,
+  ].join(" ");
+  return [
+    "--experimental-strip-types",
+    "--import",
+    `data:text/javascript,${encodeURIComponent(importSource)}`,
+  ];
+}
+
+/**
+ * The entry a daemon launches its worker from: the source file in dev, otherwise a copy of the
+ * built bundle in this home, prepared on demand.
+ */
+export function resolveTerminalWorkerEntry(input: {
+  paseoHome: string;
+  paseoVersion: string;
+}): TerminalWorkerEntry {
+  if (import.meta.url.endsWith(".ts")) {
+    return {
+      scriptPath: fileURLToPath(new URL("./terminal-worker-process.ts", import.meta.url)),
+      execArgv: sourceExecArgv(),
+      runtime: null,
+    };
+  }
+  const bundleDirectory = fileURLToPath(new URL("../terminal-worker/", import.meta.url));
+  if (!existsSync(path.join(bundleDirectory, TERMINAL_WORKER_BUNDLE_NAME))) {
+    throw new TerminalWorkerRuntimeError(
+      `The terminal worker bundle is missing from ${bundleDirectory}; rebuild @getpaseo/server (npm run build).`,
+    );
+  }
+  const require = createRequire(import.meta.url);
+  const nodePtyDirectory = path.dirname(require.resolve("node-pty/package.json"));
+  return prepareTerminalWorkerRuntime({
+    paseoHome: input.paseoHome,
+    paseoVersion: input.paseoVersion,
+    bundleDirectory,
+    nodePtyDirectory,
+  });
+}
+
+function runtimeName(input: {
+  paseoVersion: string;
+  bundleDirectory: string;
+  nodePtyDirectory: string;
+}): string {
+  const hash = createHash("sha256");
+  hash.update(readFileSync(path.join(input.bundleDirectory, TERMINAL_WORKER_BUNDLE_NAME)));
+  hash.update(readFileSync(path.join(input.nodePtyDirectory, "package.json")));
+  hash.update(`${process.platform}-${process.arch}`);
+  const version = input.paseoVersion.replace(/[^A-Za-z0-9._-]/g, "_");
+  return `${version}-${hash.digest("hex").slice(0, 12)}`;
+}
+
+// Plain fs calls on purpose: inside the desktop app the sources live in app.asar, which
+// Electron's fs reads transparently but newer helpers like cpSync do not.
+function copyTree(source: string, destination: string): void {
+  const stat = statSync(source);
+  if (stat.isDirectory()) {
+    mkdirSync(destination, { recursive: true });
+    for (const name of readdirSync(source)) {
+      copyTree(path.join(source, name), path.join(destination, name));
+    }
+    return;
+  }
+  writeFileSync(destination, readFileSync(source));
+  // Keeps node-pty's spawn-helper executable.
+  chmodSync(destination, stat.mode & 0o777);
+}
+
+function copyNodePty(source: string, destination: string): void {
+  mkdirSync(destination, { recursive: true });
+  copyTree(path.join(source, "package.json"), path.join(destination, "package.json"));
+  copyTree(path.join(source, "lib"), path.join(destination, "lib"));
+  const native = [
+    path.join("build", "Release"),
+    path.join("prebuilds", `${process.platform}-${process.arch}`),
+  ].filter((relative) => existsSync(path.join(source, relative)));
+  if (native.length === 0) {
+    throw new TerminalWorkerRuntimeError(
+      `node-pty at ${source} has no native build for ${process.platform}-${process.arch}`,
+    );
+  }
+  for (const relative of native) {
+    copyTree(path.join(source, relative), path.join(destination, relative));
+  }
+}
+
+function isCompleteRuntime(directory: string): boolean {
+  return existsSync(path.join(directory, RUNTIME_MARKER));
+}
+
+/**
+ * Copies the worker bundle, its shell integration and node-pty into this home, unless a finished
+ * copy of the same content is already there. Returns the entry to launch from the copy.
+ */
+export function prepareTerminalWorkerRuntime(input: {
+  paseoHome: string;
+  paseoVersion: string;
+  bundleDirectory: string;
+  nodePtyDirectory: string;
+}): TerminalWorkerEntry {
+  const root = terminalWorkerDirectory(input.paseoHome);
+  ensurePrivateDirectory(root);
+  const name = runtimeName(input);
+  const directory = path.join(root, name);
+  const entry = {
+    scriptPath: path.join(directory, TERMINAL_WORKER_BUNDLE_NAME),
+    execArgv: [],
+    runtime: name,
+  };
+  if (isCompleteRuntime(directory)) return entry;
+
+  // An interrupted copy left behind: no worker can be running from it.
+  rmSync(directory, { recursive: true, force: true });
+  const temporary = path.join(root, `${TEMP_PREFIX}${name}-${randomUUID()}`);
+  try {
+    mkdirSync(temporary, { recursive: true });
+    copyTree(
+      path.join(input.bundleDirectory, TERMINAL_WORKER_BUNDLE_NAME),
+      path.join(temporary, TERMINAL_WORKER_BUNDLE_NAME),
+    );
+    copyTree(
+      path.join(input.bundleDirectory, "shell-integration"),
+      path.join(temporary, "shell-integration"),
+    );
+    copyNodePty(input.nodePtyDirectory, path.join(temporary, "node_modules", "node-pty"));
+    writeFileSync(
+      path.join(temporary, RUNTIME_MARKER),
+      `${JSON.stringify({ paseoVersion: input.paseoVersion, copiedAt: new Date().toISOString() })}\n`,
+    );
+    renameSync(temporary, directory);
+  } catch (error) {
+    rmSync(temporary, { recursive: true, force: true });
+    if (isCompleteRuntime(directory)) return entry;
+    throw new TerminalWorkerRuntimeError(
+      `Cannot copy the terminal worker into ${directory}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+  return entry;
+}
+
+export interface PruneTerminalWorkerRuntimesResult {
+  removed: string[];
+  /** Copies that could not be deleted (a worker that just exited can still hold files on Windows). */
+  failed: Array<{ directory: string; error: string }>;
+}
+
+/**
+ * Deletes every copy no worker record names. With an unreadable record it deletes nothing: that
+ * record could name a copy a live worker runs from.
+ */
+export async function pruneTerminalWorkerRuntimes(
+  paseoHome: string,
+): Promise<PruneTerminalWorkerRuntimesResult> {
+  const result: PruneTerminalWorkerRuntimesResult = { removed: [], failed: [] };
+  const root = terminalWorkerDirectory(paseoHome);
+  const files = await listTerminalWorkerRecords(paseoHome);
+  const inUse = new Set<string>();
+  for (const file of files) {
+    if ("error" in file) return result;
+    if (file.record.runtime) inUse.add(file.record.runtime);
+  }
+  let names: string[];
+  try {
+    names = await readdir(root);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return result;
+    throw error;
+  }
+  for (const name of names) {
+    if (inUse.has(name)) continue;
+    const directory = path.join(root, name);
+    if (
+      !name.startsWith(TEMP_PREFIX) &&
+      !(await access(path.join(directory, RUNTIME_MARKER)).then(
+        () => true,
+        (error: NodeJS.ErrnoException) => {
+          if (error.code === "ENOENT" || error.code === "ENOTDIR") return false;
+          throw error;
+        },
+      ))
+    )
+      continue;
+    try {
+      await rm(directory, { recursive: true, force: true });
+      result.removed.push(directory);
+    } catch (error) {
+      result.failed.push({
+        directory,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  return result;
+}
diff --git a/packages/server/src/terminal/terminal-worker-socket-path.test.ts b/packages/server/src/terminal/terminal-worker-socket-path.test.ts
new file mode 100644
index 0000000000..6017177fcf
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-socket-path.test.ts
@@ -0,0 +1,150 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { isPlatform } from "../test-utils/platform.js";
+import {
+  resolveTerminalWorkerSocketPath,
+  TerminalWorkerSocketPathError,
+} from "./terminal-worker-socket-path.js";
+
+const temporaryDirs: string[] = [];
+
+function makeDir(prefix: string, root = tmpdir()): string {
+  const dir = mkdtempSync(path.join(root, prefix));
+  temporaryDirs.push(dir);
+  return dir;
+}
+
+// A home path long enough that its socket cannot fit sun_path, with multi-byte segments so the
+// budget is measured in bytes, not characters.
+function longHome(root: string): string {
+  const home = path.join(root, "worktree-ñandú-".repeat(5), "paseo-home");
+  mkdirSync(home, { recursive: true });
+  return home;
+}
+
+afterEach(() => {
+  for (const dir of temporaryDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe.skipIf(isPlatform("win32"))("terminal worker socket path", () => {
+  it("uses the home's own socket directory when the path fits", () => {
+    // macOS $TMPDIR alone is ~50 bytes; a short root keeps the home's own path in budget.
+    const home = makeDir("tw-h-", "/tmp");
+    const socketPath = resolveTerminalWorkerSocketPath({
+      paseoHome: home,
+      recordId: "test",
+      workerPid: 4242,
+      platform: "darwin",
+    });
+    expect(socketPath.startsWith(path.join(home, "terminal-worker", "sock"))).toBe(true);
+  });
+
+  it("falls to /tmp/paseo-<uid> when the home and TMPDIR are too long, within the byte budget", () => {
+    const root = makeDir("tw-sock-long-");
+    const home = longHome(root);
+    const tmpDir = path.join(root, "tmp-ñandú-".repeat(6));
+    mkdirSync(tmpDir, { recursive: true });
+    const uid = process.getuid!();
+    const socketPath = resolveTerminalWorkerSocketPath({
+      paseoHome: home,
+      recordId: "test",
+      workerPid: 99999,
+      platform: "darwin",
+      tmpDir,
+    });
+    expect(path.dirname(socketPath)).toBe(`/tmp/paseo-${uid}`);
+    expect(Buffer.byteLength(socketPath, "utf8")).toBeLessThanOrEqual(103);
+  });
+
+  it("rejects a shared-root directory that is a symlink, has another mode, or is not a directory", () => {
+    const root = makeDir("tw-sock-reject-");
+    const home = longHome(root);
+    const uid = process.getuid!();
+    const tmpDir = makeDir("tw-");
+    const target = makeDir("tw-target-");
+    chmodSync(target, 0o700);
+    symlinkSync(target, path.join(tmpDir, `paseo-${uid}`));
+    // A budget check alone would accept the long-home fallback through the symlink; it must
+    // also be refused, and /tmp/paseo-<uid> takes over.
+    const socketPath = resolveTerminalWorkerSocketPath({
+      paseoHome: home,
+      recordId: "test",
+      workerPid: 7,
+      platform: "darwin",
+      tmpDir,
+    });
+    expect(path.dirname(socketPath)).toBe(`/tmp/paseo-${uid}`);
+
+    const wideTmp = makeDir("tw-");
+    mkdirSync(path.join(wideTmp, `paseo-${uid}`), { mode: 0o755 });
+    chmodSync(path.join(wideTmp, `paseo-${uid}`), 0o755);
+    expect(
+      path.dirname(
+        resolveTerminalWorkerSocketPath({
+          paseoHome: home,
+          recordId: "test",
+          workerPid: 7,
+          platform: "darwin",
+          tmpDir: wideTmp,
+        }),
+      ),
+    ).toBe(`/tmp/paseo-${uid}`);
+  });
+
+  it("names every rejected candidate with its byte length when none fits", () => {
+    const root = makeDir("tw-sock-none-");
+    const home = longHome(root);
+    const tmpDir = path.join(root, "tmp-ñandú-".repeat(6));
+    mkdirSync(tmpDir, { recursive: true });
+    let caught: unknown;
+    try {
+      resolveTerminalWorkerSocketPath({
+        paseoHome: home,
+        recordId: "test",
+        workerPid: 7,
+        platform: "darwin",
+        tmpDir,
+        // Another uid's /tmp/paseo-<uid> directory does not exist or is not ours; with a uid
+        // nobody owns, the /tmp candidate's directory is created by us but owned by our real
+        // uid, so it is rejected for its owner.
+        uid: 2_000_000_000,
+      });
+    } catch (error) {
+      caught = error;
+    }
+    rmSync("/tmp/paseo-2000000000", { recursive: true, force: true });
+    expect(caught).toBeInstanceOf(TerminalWorkerSocketPathError);
+    const rejected = (caught as TerminalWorkerSocketPathError).rejected;
+    expect(rejected).toHaveLength(3);
+    expect(rejected[0].reason).toMatch(/longer than 103 bytes/);
+    expect(rejected[0].byteLength).toBe(Buffer.byteLength(rejected[0].path, "utf8"));
+    expect(rejected[2].reason).toMatch(/owned by uid/);
+  });
+
+  it("accepts a real listen on the chosen path", async () => {
+    const home = makeDir("tw-l-", "/tmp");
+    const socketPath = resolveTerminalWorkerSocketPath({
+      paseoHome: home,
+      recordId: "test",
+      workerPid: 5,
+    });
+    const server = createServer();
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(socketPath, () => resolve());
+    });
+    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
new file mode 100644
index 0000000000..d9a153c598
--- /dev/null
+++ b/packages/server/src/terminal/terminal-worker-socket-path.ts
@@ -0,0 +1,134 @@
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { ensurePrivateDirectory } from "../server/private-files.js";
+import { terminalWorkerDirectory } from "./terminal-worker-record.js";
+
+// `sun_path` holds 104 bytes on macOS and 108 on Linux, NUL included. Dev homes under
+// worktrees and long $TMPDIR values exceed that, so the socket goes to the first owner-only
+// directory whose full path fits, measured in UTF-8 bytes.
+const SOCKET_PATH_BYTE_BUDGET: Partial<Record<NodeJS.Platform, number>> = {
+  darwin: 103,
+  linux: 107,
+};
+const DEFAULT_SOCKET_PATH_BYTE_BUDGET = 103;
+const OWNER_ONLY_MODE = 0o700;
+
+export interface TerminalWorkerSocketPathInput {
+  paseoHome: string;
+  workerPid: number;
+  recordId: string;
+  platform?: NodeJS.Platform;
+  tmpDir?: string;
+  uid?: number;
+}
+
+export interface RejectedSocketCandidate {
+  path: string;
+  byteLength: number;
+  reason: string;
+}
+
+export class TerminalWorkerSocketPathError extends Error {
+  readonly rejected: RejectedSocketCandidate[];
+
+  constructor(rejected: RejectedSocketCandidate[], budget: number) {
+    super(
+      [
+        `No terminal worker socket path fits ${budget} bytes in an owner-only directory:`,
+        ...rejected.map(
+          (candidate) => `  ${candidate.path} (${candidate.byteLength} bytes): ${candidate.reason}`,
+        ),
+      ].join("\n"),
+    );
+    this.name = "TerminalWorkerSocketPathError";
+    this.rejected = rejected;
+  }
+}
+
+/** First 16 hex chars of sha256(home) plus the worker pid: unique per home and worker. */
+export function terminalWorkerSocketId(paseoHome: string, workerPid: number): string {
+  const digest = createHash("sha256").update(path.resolve(paseoHome)).digest("hex");
+  return `${digest.slice(0, 16)}-${workerPid}`;
+}
+
+/**
+ * Picks (and creates) the socket path a worker listens on. Windows uses a named pipe; POSIX
+ * tries $PASEO_HOME/terminal-worker/sock, then <tmpdir>/paseo-<uid>, then /tmp/paseo-<uid>.
+ * A shared root is never chmodded: an existing directory there is used only when it is a real
+ * directory owned by this user with mode 0700.
+ */
+export function resolveTerminalWorkerSocketPath(input: TerminalWorkerSocketPathInput): string {
+  const platform = input.platform ?? process.platform;
+  const id = terminalWorkerSocketId(input.paseoHome, input.workerPid) + "-" + input.recordId;
+  if (platform === "win32") {
+    return `\\\\.\\pipe\\paseo-tw-${id}`;
+  }
+
+  const uid = input.uid ?? process.getuid?.() ?? 0;
+  const budget = SOCKET_PATH_BYTE_BUDGET[platform] ?? DEFAULT_SOCKET_PATH_BYTE_BUDGET;
+  const fileName = `tw-${id}.sock`;
+  const homeSocketDirectory = path.join(terminalWorkerDirectory(input.paseoHome), "sock");
+  const candidates: Array<{ directory: string; prepare: () => string | null }> = [
+    {
+      directory: homeSocketDirectory,
+      prepare: () => {
+        ensurePrivateDirectory(homeSocketDirectory);
+        return verifyOwnerOnlyDirectory(homeSocketDirectory, uid);
+      },
+    },
+    ...[input.tmpDir ?? tmpdir(), "/tmp"].map((root) => {
+      const directory = path.join(root, `paseo-${uid}`);
+      return {
+        directory,
+        prepare: () => prepareSharedRootDirectory(directory, uid),
+      };
+    }),
+  ];
+
+  const rejected: RejectedSocketCandidate[] = [];
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    const socketPath = path.join(candidate.directory, fileName);
+    if (seen.has(socketPath)) continue;
+    seen.add(socketPath);
+    const byteLength = Buffer.byteLength(socketPath, "utf8");
+    if (byteLength > budget) {
+      rejected.push({ path: socketPath, byteLength, reason: `longer than ${budget} bytes` });
+      continue;
+    }
+    let problem: string | null;
+    try {
+      problem = candidate.prepare();
+    } catch (error) {
+      problem = error instanceof Error ? error.message : String(error);
+    }
+    if (problem) {
+      rejected.push({ path: socketPath, byteLength, reason: problem });
+      continue;
+    }
+    return socketPath;
+  }
+  throw new TerminalWorkerSocketPathError(rejected, budget);
+}
+
+function prepareSharedRootDirectory(directory: string, uid: number): string | null {
+  try {
+    mkdirSync(directory, { mode: OWNER_ONLY_MODE });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+  return verifyOwnerOnlyDirectory(directory, uid);
+}
+
+/** Returns why the directory cannot hold the socket, or null when it is owner-only. */
+function verifyOwnerOnlyDirectory(directory: string, uid: number): string | null {
+  const stats = lstatSync(directory);
+  if (stats.isSymbolicLink()) return "is a symlink";
+  if (!stats.isDirectory()) return "is not a directory";
+  if (stats.uid !== uid) return `is owned by uid ${stats.uid}, not ${uid}`;
+  const mode = stats.mode & 0o777;
+  if (mode !== OWNER_ONLY_MODE) return `has mode ${mode.toString(8)}, not 700`;
+  return null;
+}
diff --git a/packages/server/src/terminal/terminal.posix.test.ts b/packages/server/src/terminal/terminal.posix.test.ts
index 4452fb6c1f..474507f771 100644
--- a/packages/server/src/terminal/terminal.posix.test.ts
+++ b/packages/server/src/terminal/terminal.posix.test.ts
@@ -1,3 +1,5 @@
+import { readTerminalState } from "./test-utils/terminal-state.js";
+import type { TerminalState } from "@getpaseo/protocol/messages";
 // POSIX-only: node-pty + POSIX shell assertions
 /* eslint-disable max-nested-callbacks */
 import { describe, it, expect, afterEach } from "vitest";
@@ -6,7 +8,7 @@ import {
   buildTerminalEnvironment,
   createTerminal,
   resolveZshShellIntegrationDir,
-  type TerminalSession,
+  type LocalTerminalSession as TerminalSession,
 } from "./terminal.js";
 import {
   chmodSync,
@@ -28,7 +30,7 @@ if (isPlatform("win32") && !process.env.ComSpec && !process.env.COMSPEC) {
   process.env.ComSpec = "C:\\Windows\\System32\\cmd.exe";
 }
 
-type TerminalRow = ReturnType<TerminalSession["getState"]>["grid"][number];
+type TerminalRow = TerminalState["grid"][number];
 
 function rowToText(row: TerminalRow): string {
   return row
@@ -38,12 +40,12 @@ function rowToText(row: TerminalRow): string {
 }
 
 // Extract text from a single row
-function getRowText(state: ReturnType<TerminalSession["getState"]>, rowIndex: number): string {
+function getRowText(state: TerminalState, rowIndex: number): string {
   return rowToText(state.grid[rowIndex]);
 }
 
 // Extract all visible lines as array (trimmed, empty lines included)
-function getLines(state: ReturnType<TerminalSession["getState"]>): string[] {
+function getLines(state: TerminalState): string[] {
   return state.grid.map(rowToText);
 }
 
@@ -55,7 +57,7 @@ async function waitForLines(
 ): Promise<void> {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    const lines = getLines(session.getState());
+    const lines = getLines(await readTerminalState(session));
     let matches = true;
     for (let i = 0; i < expectedLines.length; i++) {
       if (lines[i] !== expectedLines[i]) {
@@ -68,7 +70,7 @@ async function waitForLines(
     }
     await new Promise((resolve) => setTimeout(resolve, 50));
   }
-  const actual = getLines(session.getState()).slice(0, expectedLines.length);
+  const actual = getLines(await readTerminalState(session)).slice(0, expectedLines.length);
   throw new Error(
     `Timeout waiting for expected lines.\nExpected:\n${JSON.stringify(expectedLines, null, 2)}\nActual:\n${JSON.stringify(actual, null, 2)}`,
   );
@@ -76,12 +78,12 @@ async function waitForLines(
 
 async function waitForState(
   session: TerminalSession,
-  predicate: (state: ReturnType<TerminalSession["getState"]>) => boolean,
+  predicate: (state: TerminalState) => boolean,
   timeoutMs = 5000,
-): Promise<ReturnType<TerminalSession["getState"]>> {
+): Promise<TerminalState> {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    const state = session.getState();
+    const state = await readTerminalState(session);
     if (predicate(state)) {
       return state;
     }
@@ -232,19 +234,19 @@ function isOsc11OkLine(line: string): boolean {
   return line.startsWith("OSC11_OK:");
 }
 
-function hasDaOkLine(state: ReturnType<TerminalSession["getState"]>): boolean {
+function hasDaOkLine(state: TerminalState): boolean {
   return getLines(state).some(isDaOkLine);
 }
 
-function hasDsrOkLine(state: ReturnType<TerminalSession["getState"]>): boolean {
+function hasDsrOkLine(state: TerminalState): boolean {
   return getLines(state).some(isDsrOkLine);
 }
 
-function hasOsc11OkLine(state: ReturnType<TerminalSession["getState"]>): boolean {
+function hasOsc11OkLine(state: TerminalState): boolean {
   return getLines(state).some(isOsc11OkLine);
 }
 
-function lastNonEmptyLineIsPrompt(state: ReturnType<TerminalSession["getState"]>): boolean {
+function lastNonEmptyLineIsPrompt(state: TerminalState): boolean {
   const last =
     getLines(state)
       .toReversed()
@@ -322,7 +324,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       // Line 2: "$"
       await waitForLines(session, ["$ echo hello", "hello", "$"]);
 
-      const state = session.getState();
+      const state = await readTerminalState(session);
       expect(getRowText(state, 0)).toBe("$ echo hello");
       expect(getRowText(state, 1)).toBe("hello");
       expect(getRowText(state, 2)).toBe("$");
@@ -346,7 +348,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       session.send({ type: "input", data: "echo second\r" });
       await waitForLines(session, ["$ echo first", "first", "$ echo second", "second", "$"]);
 
-      const state = session.getState();
+      const state = await readTerminalState(session);
       expect(getRowText(state, 0)).toBe("$ echo first");
       expect(getRowText(state, 1)).toBe("first");
       expect(getRowText(state, 2)).toBe("$ echo second");
@@ -370,7 +372,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
 
       await waitForLines(session, ["$ pwd", "/tmp", "$"]);
 
-      const state = session.getState();
+      const state = await readTerminalState(session);
       expect(getRowText(state, 0)).toBe("$ pwd");
       expect(getRowText(state, 1)).toBe("/tmp");
       expect(getRowText(state, 2)).toBe("$");
@@ -431,7 +433,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
 
       expect(seenTitles).toContain("npm run dev");
       expect(session.getTitle()).toBe("npm run dev");
-      expect(session.getState().title).toBe("npm run dev");
+      expect(session.getTitle()).toBe("npm run dev");
 
       unsubscribeTitle();
     });
@@ -457,7 +459,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
 
       expect(seenTitles).toContain("Build Log");
       expect(session.getTitle()).toBe("Build Log");
-      expect(session.getState().title).toBe("Build Log");
+      expect(session.getTitle()).toBe("Build Log");
 
       unsubscribeTitle();
     });
@@ -478,7 +480,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       await new Promise((resolve) => setTimeout(resolve, 150));
 
       expect(session.getTitle()).toBe("typecheck");
-      expect(session.getState().title).toBe("typecheck");
+      expect(session.getTitle()).toBe("typecheck");
     });
 
     it("emits command completion from VS Code OSC 633 without visible output", async () => {
@@ -507,7 +509,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       await waitForState(session, () => commandCompletions.length === 1);
 
       expect(commandCompletions).toEqual([7]);
-      expect(getLines(session.getState()).join("\n")).not.toContain("633;D;7");
+      expect(getLines(await readTerminalState(session)).join("\n")).not.toContain("633;D;7");
 
       unsubscribeCommandFinished();
     });
@@ -541,7 +543,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       await waitForState(session, () => commandCompletions.length === 1);
 
       expect(commandCompletions).toEqual([3]);
-      expect(getLines(session.getState()).join("\n")).not.toContain("633;D;garbage");
+      expect(getLines(await readTerminalState(session)).join("\n")).not.toContain("633;D;garbage");
 
       unsubscribeCommandFinished();
     });
@@ -696,7 +698,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       await waitForState(session, () => commandCompletions.includes(1));
 
       expect(commandCompletions).toEqual([1]);
-      expect(getLines(session.getState()).join("\n")).not.toContain("633;D;1");
+      expect(getLines(await readTerminalState(session)).join("\n")).not.toContain("633;D;1");
 
       unsubscribeCommandFinished();
     });
@@ -720,7 +722,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
 
       await waitForLines(session, ["$ printf '\\033[31mRED\\033[0m'", "RED$"]);
 
-      const state = session.getState();
+      const state = await readTerminalState(session);
       const outputRow = state.grid[1];
 
       expect(outputRow[0].char).toBe("R");
@@ -750,7 +752,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
 
       await waitForLines(session, ["$ printf '\\033[38;5;208mORG\\033[0m'", "ORG$"]);
 
-      const state = session.getState();
+      const state = await readTerminalState(session);
       const outputRow = state.grid[1];
 
       // Check O cell
@@ -776,7 +778,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
 
       await waitForLines(session, ["$ printf '\\033[38;2;255;128;64mRGB\\033[0m'", "RGB$"]);
 
-      const state = session.getState();
+      const state = await readTerminalState(session);
       const outputRow = state.grid[1];
 
       // Check R cell
@@ -805,7 +807,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
 
       await waitForLines(session, ["$ printf '\\033[41mBG\\033[0m'", "BG$"]);
 
-      const state = session.getState();
+      const state = await readTerminalState(session);
       const outputRow = state.grid[1];
 
       expect(outputRow[0].char).toBe("B");
@@ -815,7 +817,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
   });
 
   describe("subscribe", () => {
-    it("receives a snapshot on initial subscription", async () => {
+    it("receives readiness on initial subscription", async () => {
       const session = trackSession(
         await createTerminal({
           workspaceId: "ws-test",
@@ -831,7 +833,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       await new Promise((resolve) => setTimeout(resolve, 100));
 
       expect(messages.length).toBeGreaterThan(0);
-      expect(messages[0].type).toBe("snapshot");
+      expect(messages[0].type).toBe("snapshotReady");
 
       unsubscribe();
     });
@@ -861,12 +863,14 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       await waitForLines(session, ["$ echo test", "test", "$"]);
 
       expect(messages.some((message) => message.type === "output")).toBe(true);
-      expect(messages.some((message) => message.type === "snapshot")).toBe(false);
+      expect(
+        messages.every((message) => message.type === "output" || message.type === "titleChange"),
+      ).toBe(true);
 
       unsubscribe();
     });
 
-    it("does not emit snapshot messages for resize-only updates", async () => {
+    it("keeps resize updates in the live observation lifecycle", async () => {
       const session = trackSession(
         await createTerminal({
           workspaceId: "ws-test",
@@ -889,13 +893,15 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       session.send({ type: "resize", rows: 30, cols: 100 });
       await new Promise((resolve) => setTimeout(resolve, 200));
 
-      expect(messages.some((message) => message.type === "snapshot")).toBe(false);
+      expect(
+        messages.every((message) => message.type === "output" || message.type === "titleChange"),
+      ).toBe(true);
       expect(session.getSize()).toEqual({ rows: 30, cols: 100 });
 
       unsubscribe();
     });
 
-    it("emits output only after getState reflects the new data", async () => {
+    it("emits output only after text capture reflects the new data", async () => {
       const session = trackSession(
         await createTerminal({
           workspaceId: "ws-test",
@@ -912,7 +918,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
             return;
           }
           unsubscribe();
-          const stateText = getLines(session.getState()).join("\n");
+          const stateText = session.captureLines().lines.join("\n");
           resolve(stateText.includes("state-after-output"));
         });
       });
@@ -965,7 +971,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       session.send({ type: "input", data: `${process.execPath} ${helperPath}\r` });
       await waitForState(session, hasDaOkLine);
 
-      const ack = getLines(session.getState()).find(isDaOkLine) ?? "";
+      const ack = getLines(await readTerminalState(session)).find(isDaOkLine) ?? "";
       expect(ack).toMatch(/^DA_OK:\[\?[\d;]+c$/);
     });
 
@@ -1003,7 +1009,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       session.send({ type: "input", data: `${process.execPath} ${helperPath} cursor\r` });
       await waitForState(session, hasDsrOkLine);
 
-      const ack = getLines(session.getState()).find(isDsrOkLine) ?? "";
+      const ack = getLines(await readTerminalState(session)).find(isDsrOkLine) ?? "";
       expect(ack).toMatch(/^DSR_OK:\d+:\d+$/);
     });
 
@@ -1023,7 +1029,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       session.send({ type: "input", data: `${process.execPath} ${helperPath} private-cursor\r` });
       await waitForState(session, hasDsrOkLine);
 
-      const ack = getLines(session.getState()).find(isDsrOkLine) ?? "";
+      const ack = getLines(await readTerminalState(session)).find(isDsrOkLine) ?? "";
       expect(ack).toMatch(/^DSR_OK:\d+:\d+$/);
     });
 
@@ -1043,7 +1049,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       session.send({ type: "input", data: `${process.execPath} ${helperPath} status\r` });
       await waitForState(session, hasDsrOkLine);
 
-      const ack = getLines(session.getState()).find(isDsrOkLine) ?? "";
+      const ack = getLines(await readTerminalState(session)).find(isDsrOkLine) ?? "";
       expect(ack).toBe("DSR_OK:status");
     });
 
@@ -1063,7 +1069,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       session.send({ type: "input", data: `${process.execPath} ${helperPath}\r` });
       await waitForState(session, hasOsc11OkLine);
 
-      const ack = getLines(session.getState()).find(isOsc11OkLine) ?? "";
+      const ack = getLines(await readTerminalState(session)).find(isOsc11OkLine) ?? "";
       expect(ack).toBe("OSC11_OK:ESC]11;rgb:0b0b/0b0b/0b0bESC\\");
     });
   });
@@ -1097,7 +1103,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       unsubscribe();
     });
 
-    it("sends the current snapshot to a new subscriber instead of replaying raw output", async () => {
+    it("announces readiness for a fresh replay instead of replaying raw live output", async () => {
       const session = trackSession(
         await createTerminal({
           workspaceId: "ws-test",
@@ -1121,26 +1127,24 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
         "$",
       ]);
 
-      let snapshotText = "";
-      const unsubscribe = session.subscribe((message) => {
-        if (message.type !== "snapshot") {
-          return;
-        }
-        snapshotText = [...message.state.scrollback, ...message.state.grid]
-          .map(rowToText)
-          .join("\n");
+      let ready!: () => void;
+      const readiness = new Promise<void>((resolve) => {
+        ready = resolve;
       });
-
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      expect(snapshotText).toContain("before-detach");
-      expect(snapshotText).toContain("after-detach");
+      const unsubscribe = session.subscribe((message) => {
+        if (message.type === "snapshotReady") ready();
+      });
+      await readiness;
+      const state = await readTerminalState(session);
+      const text = [...state.scrollback, ...state.grid].map(rowToText).join("\n");
+      expect(text).toContain("before-detach");
+      expect(text).toContain("after-detach");
       unsubscribe();
     });
   });
 
-  describe("getState", () => {
-    it("returns current terminal state with grid", async () => {
+  describe("ANSI replay observation", () => {
+    it("reconstructs current terminal state from ANSI", async () => {
       const session = trackSession(
         await createTerminal({
           workspaceId: "ws-test",
@@ -1152,7 +1156,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
         }),
       );
 
-      const state = session.getState();
+      const state = await readTerminalState(session);
 
       expect(state.rows).toBe(24);
       expect(state.cols).toBe(80);
@@ -1179,19 +1183,16 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       await waitForLines(session, ["$"]);
       session.send({ type: "input", data: "printf '\\033[2 q\\033[?25l'\r" });
 
-      const state = await waitForState(
-        session,
-        (current) =>
-          current.cursor.style === "block" &&
-          current.cursor.blink === false &&
-          current.cursor.hidden === true,
+      const deadline = Date.now() + 5000;
+      while (
+        !new TextDecoder().decode(session.serializeReplay().data).includes("\x1b[?25l\x1b[2 q")
+      ) {
+        if (Date.now() > deadline) throw new Error("cursor presentation did not reach replay");
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      }
+      expect(new TextDecoder().decode(session.serializeReplay().data)).toContain(
+        "\x1b[?25l\x1b[2 q",
       );
-
-      expect(state.cursor).toMatchObject({
-        style: "block",
-        blink: false,
-        hidden: true,
-      });
     });
 
     it("grid cells have char and color attributes", async () => {
@@ -1206,7 +1207,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
 
       await waitForLines(session, ["$"]);
 
-      const state = session.getState();
+      const state = await readTerminalState(session);
       // First cell should be "$"
       expect(state.grid[0][0].char).toBe("$");
       expect(state.grid[0][0]).toHaveProperty("fg");
@@ -1238,7 +1239,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       // The visible area will show something like: 17, 18, 19, 20, $
       await waitForLines(session, ["17", "18", "19", "20", "$"]);
 
-      const state = session.getState();
+      const state = await readTerminalState(session);
 
       // Scrollback should contain the earlier output
       expect(state.scrollback.length).toBeGreaterThan(0);
@@ -1269,7 +1270,7 @@ describe.skipIf(isPlatform("win32"))("terminal POSIX-only", () => {
       session.kill();
 
       // Should not throw when trying to get state after kill
-      const state = session.getState();
+      const state = await readTerminalState(session);
       expect(state).toBeDefined();
     });
 
diff --git a/packages/server/src/terminal/terminal.test.ts b/packages/server/src/terminal/terminal.test.ts
index 751fb1b33a..3d1fcca545 100644
--- a/packages/server/src/terminal/terminal.test.ts
+++ b/packages/server/src/terminal/terminal.test.ts
@@ -1,3 +1,7 @@
+import { TerminalInputModeTracker } from "@getpaseo/protocol/terminal-input-mode";
+import { createTerminalSerializer } from "./terminal-serializer.js";
+import { readTerminalState } from "./test-utils/terminal-state.js";
+import type { TerminalState } from "@getpaseo/protocol/messages";
 import { describe, it, expect, afterEach, vi } from "vitest";
 import { isPlatform } from "../test-utils/platform.js";
 import {
@@ -10,7 +14,7 @@ import {
   humanizeProcessTitle,
   normalizeProcessTitle,
   resolveZshShellIntegrationDir,
-  type TerminalSession,
+  type LocalTerminalSession as TerminalSession,
 } from "./terminal.js";
 import {
   chmodSync,
@@ -26,7 +30,6 @@ import {
 import { spawnSync } from "node:child_process";
 import * as pty from "node-pty";
 import xterm from "@xterm/headless";
-import { renderTerminalSnapshotToAnsi } from "@getpaseo/protocol/terminal-snapshot";
 import { delimiter, join } from "node:path";
 import { tmpdir } from "node:os";
 import { setImmediate as waitForImmediate, setTimeout as delay } from "node:timers/promises";
@@ -34,7 +37,7 @@ import { stripVTControlCharacters } from "node:util";
 
 const hasZsh = existsSync("/bin/zsh");
 
-type TerminalRow = ReturnType<TerminalSession["getState"]>["grid"][number];
+type TerminalRow = TerminalState["grid"][number];
 
 function rowToText(row: TerminalRow): string {
   return row
@@ -44,12 +47,12 @@ function rowToText(row: TerminalRow): string {
 }
 
 // Extract text from a single row
-function getRowText(state: ReturnType<TerminalSession["getState"]>, rowIndex: number): string {
+function getRowText(state: TerminalState, rowIndex: number): string {
   return rowToText(state.grid[rowIndex]);
 }
 
 // Extract all visible lines as array (trimmed, empty lines included)
-function getLines(state: ReturnType<TerminalSession["getState"]>): string[] {
+function getLines(state: TerminalState): string[] {
   return state.grid.map(rowToText);
 }
 
@@ -65,7 +68,7 @@ async function waitForLines(
 ): Promise<void> {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    const lines = getLines(session.getState());
+    const lines = getLines(await readTerminalState(session));
     let matches = true;
     for (let i = 0; i < expectedLines.length; i++) {
       if (lines[i] !== expectedLines[i]) {
@@ -78,7 +81,7 @@ async function waitForLines(
     }
     await new Promise((resolve) => setTimeout(resolve, 50));
   }
-  const actual = getLines(session.getState()).slice(0, expectedLines.length);
+  const actual = getLines(await readTerminalState(session)).slice(0, expectedLines.length);
   throw new Error(
     `Timeout waiting for expected lines.\nExpected:\n${JSON.stringify(expectedLines, null, 2)}\nActual:\n${JSON.stringify(actual, null, 2)}`,
   );
@@ -86,12 +89,12 @@ async function waitForLines(
 
 async function waitForState(
   session: TerminalSession,
-  predicate: (state: ReturnType<TerminalSession["getState"]>) => boolean,
+  predicate: (state: TerminalState) => boolean,
   timeoutMs = 5000,
-): Promise<ReturnType<TerminalSession["getState"]>> {
+): Promise<TerminalState> {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    const state = session.getState();
+    const state = await readTerminalState(session);
     if (predicate(state)) {
       return state;
     }
@@ -407,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,
+          ],
         }),
       );
 
@@ -473,7 +481,7 @@ describe("createTerminal", () => {
       }),
     );
 
-    const state = session.getState();
+    const state = await readTerminalState(session);
     expect(state.rows).toBe(24);
     expect(state.cols).toBe(80);
   });
@@ -493,12 +501,12 @@ describe("createTerminal", () => {
       }),
     );
 
-    const state = session.getState();
+    const state = await readTerminalState(session);
     expect(state.rows).toBe(40);
     expect(state.cols).toBe(120);
   });
 
-  it("reports per-row soft-wrap flags only when wrap flags are requested", async () => {
+  it("preserves soft-wrap boundaries through public replay", async () => {
     const session = trackSession(
       await createTerminal({
         workspaceId: "ws-test",
@@ -513,21 +521,15 @@ describe("createTerminal", () => {
 
     const start = Date.now();
     while (Date.now() - start < 5000) {
-      if (rowToText(session.getState().grid[2]).startsWith("A")) {
+      if (rowToText((await readTerminalState(session)).grid[2]).startsWith("A")) {
         break;
       }
       await new Promise((resolve) => setTimeout(resolve, 50));
     }
 
     // Rows 0 and 1 continue onto the next row; row 2 is the end of the logical line.
-    const withFlags = session.getState({ includeWrapFlags: true });
+    const withFlags = await readTerminalState(session);
     expect(withFlags.gridWrapped?.slice(0, 3)).toEqual([true, true, false]);
-
-    // Back-compat gate: without the capability the daemon must not attach the new
-    // fields, so an old strict-schema client still parses the snapshot.
-    const withoutFlags = session.getState();
-    expect(withoutFlags.gridWrapped).toBeUndefined();
-    expect(withoutFlags.scrollbackWrapped).toBeUndefined();
   });
 
   it("restores CJK text without injected spaces when a snapshot round-trips through the client", async () => {
@@ -555,9 +557,7 @@ describe("createTerminal", () => {
     // row back the way a selection copy would.
     const restored = new xterm.Terminal({ cols: 80, rows: 10, allowProposedApi: true });
     try {
-      await new Promise<void>((resolve) =>
-        restored.write(renderTerminalSnapshotToAnsi(state), resolve),
-      );
+      await new Promise<void>((resolve) => restored.write(session.serializeReplay().data, resolve));
       expect(restored.buffer.active.getLine(0)?.translateToString(true)).toBe(text);
     } finally {
       restored.dispose();
@@ -568,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({
@@ -615,11 +680,8 @@ describe("createTerminal", () => {
 
     // Poll the parsed buffer until the final line lands, so the exit summary
     // (which reads the headless buffer) can't race the async xterm parse.
-    const finalLineParsed = (): boolean => {
-      const state = session.getState();
-      const rowText = (row: { char: string }[]): string => row.map((cell) => cell.char).join("");
-      return [...state.scrollback, ...state.grid].some((row) => rowText(row).includes("line-2999"));
-    };
+    const finalLineParsed = (): boolean =>
+      session.captureLines({ start: -12 }).lines.some((line) => line.includes("line-2999"));
     const deadline = Date.now() + 10000;
     while (!finalLineParsed()) {
       if (Date.now() > deadline) {
@@ -678,7 +740,7 @@ describe("createTerminal", () => {
       );
 
       await waitForLines(session, ["paseo-launch-ok"]);
-      expect(getLines(session.getState())[0]).toBe("paseo-launch-ok");
+      expect(getLines(await readTerminalState(session))[0]).toBe("paseo-launch-ok");
     },
   );
 
@@ -721,7 +783,7 @@ describe("createTerminal", () => {
       );
 
       await waitForLines(session, ["paseo-launch-ok"]);
-      expect(getLines(session.getState())[0]).toBe("paseo-launch-ok");
+      expect(getLines(await readTerminalState(session))[0]).toBe("paseo-launch-ok");
     },
   );
 
@@ -743,7 +805,7 @@ describe("createTerminal", () => {
     );
 
     await waitForLines(session, ["paseo-launch-ok"]);
-    expect(getLines(session.getState())[0]).toBe("paseo-launch-ok");
+    expect(getLines(await readTerminalState(session))[0]).toBe("paseo-launch-ok");
   });
 
   it("leaves the command check to the terminal itself on Windows", async () => {
@@ -807,7 +869,7 @@ describe.skipIf(isPlatform("win32"))("send input", () => {
     // Line 2: "$"
     await waitForLines(session, ["$ echo hello", "hello", "$"]);
 
-    const state = session.getState();
+    const state = await readTerminalState(session);
     expect(getRowText(state, 0)).toBe("$ echo hello");
     expect(getRowText(state, 1)).toBe("hello");
     expect(getRowText(state, 2)).toBe("$");
@@ -829,7 +891,7 @@ describe.skipIf(isPlatform("win32"))("send input", () => {
 
     await waitForLines(session, ["$ pwd", "/tmp", "$"]);
 
-    const state = session.getState();
+    const state = await readTerminalState(session);
     expect(getRowText(state, 0)).toBe("$ pwd");
     expect(getRowText(state, 1)).toBe("/tmp");
     expect(getRowText(state, 2)).toBe("$");
@@ -890,7 +952,6 @@ describe.skipIf(isPlatform("win32"))("terminal title", () => {
 
     expect(seenTitles).toContain("npm run dev");
     expect(session.getTitle()).toBe("npm run dev");
-    expect(session.getState().title).toBe("npm run dev");
 
     unsubscribeTitle();
   });
@@ -916,7 +977,6 @@ describe.skipIf(isPlatform("win32"))("terminal title", () => {
 
     expect(seenTitles).toContain("Build Log");
     expect(session.getTitle()).toBe("Build Log");
-    expect(session.getState().title).toBe("Build Log");
 
     unsubscribeTitle();
   });
@@ -937,7 +997,6 @@ describe.skipIf(isPlatform("win32"))("terminal title", () => {
     await new Promise((resolve) => setTimeout(resolve, 150));
 
     expect(session.getTitle()).toBe("typecheck");
-    expect(session.getState().title).toBe("typecheck");
   });
 
   it("emits command completion from VS Code OSC 633 without visible output", async () => {
@@ -966,7 +1025,7 @@ describe.skipIf(isPlatform("win32"))("terminal title", () => {
     await waitForState(session, () => commandCompletions.length === 1);
 
     expect(commandCompletions).toEqual([7]);
-    expect(getLines(session.getState()).join("\n")).not.toContain("633;D;7");
+    expect(getLines(await readTerminalState(session)).join("\n")).not.toContain("633;D;7");
 
     unsubscribeCommandFinished();
   });
@@ -1000,7 +1059,7 @@ describe.skipIf(isPlatform("win32"))("terminal title", () => {
     await waitForState(session, () => commandCompletions.length === 1);
 
     expect(commandCompletions).toEqual([3]);
-    expect(getLines(session.getState()).join("\n")).not.toContain("633;D;garbage");
+    expect(getLines(await readTerminalState(session)).join("\n")).not.toContain("633;D;garbage");
 
     unsubscribeCommandFinished();
   });
@@ -1155,7 +1214,7 @@ describe.skipIf(isPlatform("win32"))("terminal title", () => {
     await waitForState(session, () => commandCompletions.includes(1));
 
     expect(commandCompletions).toEqual([1]);
-    expect(getLines(session.getState()).join("\n")).not.toContain("633;D;1");
+    expect(getLines(await readTerminalState(session)).join("\n")).not.toContain("633;D;1");
 
     unsubscribeCommandFinished();
   });
@@ -1189,7 +1248,6 @@ describe.skipIf(isPlatform("win32"))("terminal title", () => {
 
     expect(seenTitles).toEqual(["Build Log", "User terminal"]);
     expect(session.getTitle()).toBe("User terminal");
-    expect(session.getState().title).toBe("User terminal");
 
     unsubscribeTitle();
   });
@@ -1219,7 +1277,6 @@ describe.skipIf(isPlatform("win32"))("terminal title", () => {
 
     expect(seenTitles).toEqual(["Build Log", "User terminal"]);
     expect(session.getTitle()).toBe("User terminal");
-    expect(session.getState().title).toBe("User terminal");
 
     unsubscribeTitle();
   });
@@ -1248,7 +1305,6 @@ describe.skipIf(isPlatform("win32"))("terminal title", () => {
 
     expect(seenTitles).toEqual(["Build Log", "User terminal"]);
     expect(session.getTitle()).toBe("User terminal");
-    expect(session.getState().title).toBe("User terminal");
 
     unsubscribeTitle();
   });
@@ -1272,7 +1328,7 @@ describe.skipIf(isPlatform("win32"))("colors", () => {
 
     await waitForLines(session, ["$ printf '\\033[31mRED\\033[0m'", "RED$"]);
 
-    const state = session.getState();
+    const state = await readTerminalState(session);
     const outputRow = state.grid[1];
 
     expect(outputRow[0].char).toBe("R");
@@ -1302,7 +1358,7 @@ describe.skipIf(isPlatform("win32"))("colors", () => {
 
     await waitForLines(session, ["$ printf '\\033[38;2;255;128;64mRGB\\033[0m'", "RGB$"]);
 
-    const state = session.getState();
+    const state = await readTerminalState(session);
     const outputRow = state.grid[1];
 
     // Check R cell
@@ -1331,7 +1387,7 @@ describe.skipIf(isPlatform("win32"))("colors", () => {
 
     await waitForLines(session, ["$ printf '\\033[41mBG\\033[0m'", "BG$"]);
 
-    const state = session.getState();
+    const state = await readTerminalState(session);
     const outputRow = state.grid[1];
 
     expect(outputRow[0].char).toBe("B");
@@ -1355,7 +1411,7 @@ describe("resize", () => {
 
     await new Promise((resolve) => setTimeout(resolve, 100));
 
-    const state = session.getState();
+    const state = await readTerminalState(session);
     expect(state.rows).toBe(40);
     expect(state.cols).toBe(120);
   });
@@ -1373,7 +1429,7 @@ describe("resize", () => {
     session.send({ type: "resize", rows: 10, cols: 40 });
     await new Promise((resolve) => setTimeout(resolve, 100));
 
-    const state = session.getState();
+    const state = await readTerminalState(session);
     expect(state.grid.length).toBe(10);
     expect(state.grid[0].length).toBe(40);
   });
@@ -1552,7 +1608,7 @@ it.runIf(isPlatform("linux", "darwin"))(
         env: { PATH: "bin" },
       });
       await waitForLines(session, ["paseo-launch-ok"]);
-      expect(getLines(session.getState())[0]).toBe("paseo-launch-ok");
+      expect(getLines(await readTerminalState(session))[0]).toBe("paseo-launch-ok");
       expect(session.cwd).toBe(realpathSync(projectDir));
       expect(session.getExitInfo()).toBeNull();
     } finally {
@@ -1574,3 +1630,309 @@ it.runIf(isPlatform("linux", "darwin"))(
     ).rejects.toThrow(" node : command not found");
   },
 );
+
+it.each([false, true])(
+  "serializes styled Unicode, cursor presentation and modes directly (alternate=%s)",
+  async (alternate) => {
+    // Exercise the serializer's input model directly. ConPTY renders program
+    // output: it consumes input modes and need not publish a hidden cursor move.
+    const terminal = new xterm.Terminal({
+      rows: 4,
+      cols: 16,
+      scrollback: 10000,
+      allowProposedApi: true,
+    });
+    const serialize = createTerminalSerializer(terminal);
+    const inputModes = new TerminalInputModeTracker();
+    const content =
+      Array.from({ length: 8 }, (_, i) => "normal-" + i + "\r\n").join("") +
+      (alternate ? "\x1b[?1049h\x1b[H" : "") +
+      "\x1b[38;2;255;128;64;4m界é🙂\x1b[0m\r\nVIEW-READY\x1b[?1h\x1b[?2004h\x1b[>1u\x1b[?9001h\x1b[?7l\x1b[?1000h\x1b[5 q\x1b[?25l";
+    const output = content + "\x1b[2;7H";
+    await new Promise<void>((resolve) => terminal.write(output, resolve));
+    inputModes.feed(output);
+    const data = serialize();
+    const ansi = new TextDecoder().decode(data);
+    expect(ansi).toContain("\x1b[?25l\x1b[5 q");
+    expect(ansi).not.toContain("NaN");
+    expect(terminal.buffer.normal.baseY).toBeGreaterThan(0);
+    const receiver = new xterm.Terminal({
+      rows: 4,
+      cols: 16,
+      scrollback: 10000,
+      allowProposedApi: true,
+    });
+    try {
+      await new Promise<void>((resolve) => receiver.write(data, resolve));
+      await new Promise<void>((resolve) => receiver.write(inputModes.getPreamble(), resolve));
+      expect(receiver.buffer.active.type).toBe(alternate ? "alternate" : "normal");
+      const lines = Array.from({ length: receiver.buffer.active.length }, (_, i) =>
+        receiver.buffer.active.getLine(i)!.translateToString(true),
+      );
+      expect(lines.join("\n")).toContain("界é🙂");
+      expect(lines.join("\n")).toContain("VIEW-READY");
+      const coloredIndex = lines.findIndex((line) => line.includes("界"));
+      const colored = receiver.buffer.active.getLine(coloredIndex)!.getCell(0)!;
+      expect(colored.getChars()).toBe("界");
+      expect(colored.getFgColor()).toBe(0xff8040);
+      expect(colored.isUnderline()).not.toBe(0);
+      expect(receiver.buffer.normal.getLine(0)!.translateToString(true)).toBe("normal-0");
+      expect({ row: receiver.buffer.active.cursorY, col: receiver.buffer.active.cursorX }).toEqual({
+        row: 1,
+        col: 6,
+      });
+      expect(receiver.modes).toMatchObject({
+        applicationCursorKeysMode: true,
+        bracketedPasteMode: true,
+        wraparoundMode: false,
+        mouseTrackingMode: "vt200",
+      });
+      const modes = new TerminalInputModeTracker();
+      modes.feed(ansi + inputModes.getPreamble());
+      expect(modes.getState()).toMatchObject({
+        kittyKeyboardFlags: 1,
+        win32InputMode: true,
+        applicationCursorKeys: true,
+        bracketedPaste: true,
+      });
+    } finally {
+      receiver.dispose();
+      terminal.dispose();
+    }
+  },
+);
+
+it.each([
+  { name: "unset", presentation: "", style: undefined, visible: true },
+  {
+    name: "reset to client default",
+    presentation: "\x1b[5 q\x1b[0 q",
+    style: undefined,
+    visible: true,
+  },
+  { name: "unset hidden", presentation: "\x1b[?25l", style: undefined, visible: false },
+  ...[1, 2, 3, 4, 5, 6].map((style) => ({
+    name: `explicit style ${style}`,
+    presentation: `\x1b[${style} q\x1b[?25l`,
+    style,
+    visible: false,
+  })),
+])("replays cursor presentation without replacing client defaults ($name)", async (input) => {
+  const session = trackSession(
+    await createTerminal({
+      cwd: realpathSync(tmpdir()),
+      workspaceId: "cursor-presentation",
+      command: process.execPath,
+      args: [
+        "-e",
+        `process.stdout.write(${JSON.stringify(input.presentation + "CURSOR-READY\r\n")});setInterval(()=>{},1000)`,
+      ],
+    }),
+  );
+  await waitForLines(session, ["CURSOR-READY"]);
+  const { data } = session.serializeReplay();
+  const ansi = new TextDecoder().decode(data);
+  const receiver = new xterm.Terminal({
+    cursorStyle: "bar",
+    cursorBlink: true,
+    allowProposedApi: true,
+  });
+  const styles: number[] = [];
+  receiver.parser.registerCsiHandler({ intermediates: " ", final: "q" }, (params) => {
+    styles.push(Number(params[0]));
+    return false;
+  });
+  try {
+    await new Promise<void>((resolve) => receiver.write(data, resolve));
+    expect(styles).toEqual(input.style === undefined ? [] : [input.style]);
+    expect(ansi).toContain(`\x1b[?25${input.visible ? "h" : "l"}`);
+  } finally {
+    receiver.dispose();
+  }
+});
+
+it("captures input modes at the same committed cut as serialized bytes", async () => {
+  const session = trackSession(
+    await createTerminal({
+      cwd: realpathSync(tmpdir()),
+      workspaceId: "mode-cut",
+      rows: 4,
+      cols: 80,
+      command: process.execPath,
+      args: [
+        "-e",
+        'process.stdin.on("data",()=>process.stdout.write("x".repeat(1024*1024)+"\x1b[?1hMODE-CUT"));setInterval(()=>{},1000)',
+      ],
+    }),
+  );
+  const mismatches: string[] = [];
+  let completed!: () => void;
+  const output = new Promise<void>((resolve) => {
+    completed = resolve;
+  });
+  const unsubscribe = session.subscribe((message) => {
+    if (message.type !== "output") return;
+    if (session.getReplayPreamble().includes("\x1b[?1h")) {
+      const cut = session.serializeReplay({ scrollbackLines: 0 });
+      if (!new TextDecoder().decode(cut.data).includes("\x1b[?1h"))
+        mismatches.push(cut.metadata.replayPreamble);
+    }
+    if (message.data.includes("MODE-CUT")) completed();
+  });
+  try {
+    session.send({ type: "input", data: "go\r" });
+    await Promise.race([
+      output,
+      delay(5000).then(() => {
+        throw new Error("mode cut did not complete");
+      }),
+    ]);
+    expect(mismatches).toEqual([]);
+  } finally {
+    unsubscribe();
+  }
+});
+
+it.each(
+  [false, true].flatMap((alternate) => [
+    {
+      alternate,
+      pendingWrap: false,
+      position: "\x1b[3;16H",
+      cursor: { row: 2, col: 15 },
+      after: { row: 2, col: 16 },
+    },
+    {
+      alternate,
+      pendingWrap: true,
+      position: "",
+      cursor: { row: 0, col: 16 },
+      after: { row: 1, col: 1 },
+    },
+  ]),
+)(
+  "replays a full-width row without losing cursor state ($alternate, pendingWrap=$pendingWrap)",
+  async (input) => {
+    const source = new xterm.Terminal({
+      rows: 4,
+      cols: 16,
+      scrollback: 10000,
+      allowProposedApi: true,
+    });
+    const serialize = createTerminalSerializer(source);
+    const receiver = new xterm.Terminal({
+      rows: 4,
+      cols: 16,
+      scrollback: 10000,
+      allowProposedApi: true,
+    });
+    try {
+      await new Promise<void>((resolve) =>
+        source.write(
+          (input.alternate ? "\x1b[?1049h" : "") + "x".repeat(16) + input.position,
+          resolve,
+        ),
+      );
+      expect({ row: source.buffer.active.cursorY, col: source.buffer.active.cursorX }).toEqual(
+        input.cursor,
+      );
+      await new Promise<void>((resolve) => receiver.write(serialize(), resolve));
+      expect({ row: receiver.buffer.active.cursorY, col: receiver.buffer.active.cursorX }).toEqual(
+        input.cursor,
+      );
+      await new Promise<void>((resolve) => receiver.write("Z", resolve));
+      expect({ row: receiver.buffer.active.cursorY, col: receiver.buffer.active.cursorX }).toEqual(
+        input.after,
+      );
+    } finally {
+      receiver.dispose();
+      source.dispose();
+    }
+  },
+);
+
+it.each([false, true])(
+  "replays the observed PTY projection including startup modes (alternate=%s)",
+  async (alternate) => {
+    const gate = mkdtempSync(join(tmpdir(), "terminal-projection-"));
+    temporaryDirs.push(gate);
+    const release = join(gate, "output");
+    const content =
+      Array.from({ length: 8 }, (_, i) => `normal-${i}\r\n`).join("") +
+      (alternate ? "\x1b[?1049h\x1b[H" : "") +
+      "\x1b[38;2;255;128;64;4m界é🙂\x1b[0m\r\nVIEW-READY\x1b[?1h\x1b[?2004h\x1b[>1u\x1b[?9001h\x1b[?7l\x1b[?1000h\x1b[5 q\x1b[?25l\x1b[2;7H";
+    const session = trackSession(
+      await createTerminal({
+        cwd: realpathSync(tmpdir()),
+        workspaceId: "projection",
+        rows: 4,
+        cols: 16,
+        command: process.execPath,
+        args: [
+          "-e",
+          `const fs=require("node:fs");let sent=false;
+      function emit(){if(!sent&&fs.existsSync(${JSON.stringify(release)})){sent=true;watcher.close();process.stdout.write(${JSON.stringify(content)});}}
+      const watcher=fs.watch(${JSON.stringify(gate)},emit);emit();setInterval(()=>{},1000);`,
+        ],
+      }),
+    );
+    const bootstrap = session.serializeReplay();
+    const output: string[] = [];
+    const unsubscribe = session.subscribe((message) => {
+      if (message.type === "output") output.push(message.data);
+    });
+    const reference = new xterm.Terminal({
+      rows: 4,
+      cols: 16,
+      scrollback: 10000,
+      allowProposedApi: true,
+    });
+    const receiver = new xterm.Terminal({
+      rows: 4,
+      cols: 16,
+      scrollback: 10000,
+      allowProposedApi: true,
+    });
+    try {
+      await new Promise<void>((resolve) => reference.write(bootstrap.data, resolve));
+      await new Promise<void>((resolve) =>
+        reference.write(bootstrap.metadata.replayPreamble, resolve),
+      );
+      writeFileSync(release, "release");
+      const deadline = Date.now() + 5000;
+      while (!session.captureLines().lines.some((line) => line.includes("VIEW-READY"))) {
+        if (Date.now() > deadline) throw new Error("PTY did not render fixture output");
+        await delay(20);
+      }
+      // Bootstrap and these committed output events cover precisely this source cut.
+      // Program bytes are not the oracle: ConPTY consumes modes and renders cells.
+      const replay = session.serializeReplay();
+      const committed = output.join("");
+      await new Promise<void>((resolve) => reference.write(committed, resolve));
+      await new Promise<void>((resolve) => receiver.write(replay.data, resolve));
+      await new Promise<void>((resolve) => receiver.write(replay.metadata.replayPreamble, resolve));
+      const text = (terminal: typeof receiver) =>
+        Array.from({ length: terminal.buffer.active.length }, (_, i) =>
+          terminal.buffer.active.getLine(i)!.translateToString(true).trimEnd(),
+        );
+      expect(text(receiver)).toEqual(text(reference));
+      expect(text(receiver).join("\n")).toContain("界é🙂");
+      expect(text(receiver).join("\n")).toContain("VIEW-READY");
+      expect(receiver.buffer.active.type).toBe(alternate ? "alternate" : "normal");
+      expect({ row: receiver.buffer.active.cursorY, col: receiver.buffer.active.cursorX }).toEqual({
+        row: reference.buffer.active.cursorY,
+        col: reference.buffer.active.cursorX,
+      });
+      expect(receiver.modes).toEqual(reference.modes);
+      const expectedModes = new TerminalInputModeTracker();
+      expectedModes.feed(bootstrap.metadata.replayPreamble + committed);
+      const actualModes = new TerminalInputModeTracker();
+      actualModes.feed(new TextDecoder().decode(replay.data) + replay.metadata.replayPreamble);
+      expect(actualModes.getState()).toEqual(expectedModes.getState());
+    } finally {
+      unsubscribe();
+      receiver.dispose();
+      reference.dispose();
+    }
+  },
+);
diff --git a/packages/server/src/terminal/terminal.ts b/packages/server/src/terminal/terminal.ts
index 24f243b6ea..b09bc8bbf6 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,
@@ -15,19 +15,29 @@ import { basename, delimiter, dirname, extname, join, resolve as resolvePath } f
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { createExternalProcessEnv } from "../server/paseo-env.js";
+import {
+  resolveExternalProcessPath,
+  resolvePaseoCliBinDir,
+  resolvePaseoCliExecutablePath,
+} from "./paseo-cli-path.js";
 import { writePrivateFileAtomicSync } from "../server/private-files.js";
 import {
   findExecutable,
   findExecutableWithoutProbing,
 } from "../executable-resolution/executable-resolution.js";
-import type { TerminalCell, TerminalState } from "@getpaseo/protocol/messages";
+import { createHeadlessTerminal } from "./headless-terminal.js";
+import { createTerminalSerializer } from "./terminal-serializer.js";
+import {
+  captureTerminalLines,
+  type CaptureTerminalLinesOptions,
+  type CaptureTerminalLinesResult,
+} from "./terminal-capture.js";
+import type { TerminalReplayOptions, TerminalReplayMetadata } from "./terminal-replay.js";
 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);
-const PASEO_CLI_BIN_ENTRY = "@getpaseo/cli/bin/paseo";
 let nodePtySpawnHelperChecked = false;
 const TERMINAL_TITLE_DEBOUNCE_MS = 150;
 const TERMINAL_EXIT_OUTPUT_LINE_LIMIT = 12;
@@ -62,26 +72,6 @@ export interface TerminalCommandFinishedInfo {
   exitCode: number | null;
 }
 
-export interface TerminalStateSnapshot {
-  state: TerminalState;
-  revision: number;
-  // Input-mode replay preamble at snapshot time. Populated by the terminal
-  // worker so the daemon main loop doesn't have to re-derive it from output.
-  replayPreamble?: string;
-}
-
-export interface TerminalStateSnapshotOptions {
-  scrollbackLines?: number;
-  // Include per-row soft-wrap flags (gridWrapped/scrollbackWrapped) so the client
-  // can reflow restored content on resize. Gated on a client capability, so old
-  // clients never receive the extra fields.
-  includeWrapFlags?: boolean;
-}
-
-export interface TerminalSubscribeOptions {
-  initialSnapshot?: "state" | "ready";
-}
-
 export type ClientMessage =
   | { type: "input"; data: string }
   | { type: "resize"; rows: number; cols: number }
@@ -89,7 +79,6 @@ export type ClientMessage =
 
 export type ServerMessage =
   | { type: "output"; data: string; revision?: number }
-  | { type: "snapshot"; state: TerminalState; revision?: number }
   | { type: "snapshotReady"; revision?: number; replayPreamble?: string }
   | { type: "titleChange"; title?: string };
 
@@ -104,14 +93,13 @@ export interface TerminalSession {
   cwd: string;
   workspaceId: string;
   send(msg: ClientMessage): void;
-  subscribe(listener: (msg: ServerMessage) => void, options?: TerminalSubscribeOptions): () => void;
+  subscribe(listener: (msg: ServerMessage) => void): () => void;
   onExit(listener: (info: TerminalExitInfo) => void): () => void;
   onCommandFinished(listener: (info: TerminalCommandFinishedInfo) => void): () => void;
   onTitleChange(listener: (title?: string) => void): () => void;
   onActivityChange(listener: (transition: TerminalActivityTransition) => void): () => void;
   getSize(): { rows: number; cols: number };
-  getState(): TerminalState;
-  getStateSnapshot(options?: TerminalStateSnapshotOptions): TerminalStateSnapshot;
+  hasOutput(): boolean;
   getReplayPreamble(): string;
   getTitle(): string | undefined;
   getActivity(): TerminalActivity | null;
@@ -123,6 +111,16 @@ export interface TerminalSession {
   killAndWait(options?: { gracefulTimeoutMs?: number; forceTimeoutMs?: number }): Promise<void>;
 }
 
+/** A session that owns its PTY in this process, so it knows the program's pid. */
+export interface LocalTerminalSession extends TerminalSession {
+  readonly pid: number;
+  serializeReplay(options?: TerminalReplayOptions): {
+    metadata: TerminalReplayMetadata;
+    data: Uint8Array;
+  };
+  captureLines(options?: CaptureTerminalLinesOptions): CaptureTerminalLinesResult;
+}
+
 function parseCommandFinishedOsc(data: string): TerminalCommandFinishedInfo | null {
   // OSC 633 is terminal control traffic, but a foreground command can still
   // print arbitrary control bytes. Keep this boundary to the exact VS Code
@@ -153,6 +151,11 @@ export interface CreateTerminalOptions {
   title?: string;
   command?: string;
   args?: string[];
+  // Environment the terminal starts from instead of this process's own. A detached terminal
+  // worker outlives the daemon that launched it, so each create carries the controlling
+  // daemon's environment and its resolved Paseo CLI path.
+  baseEnv?: Record<string, string>;
+  paseoCliPath?: string | null;
 }
 
 function toTerminalActivity(snapshot: {
@@ -181,6 +184,7 @@ function isTerminalActivityInterruptInput(data: string): boolean {
 interface BuildTerminalEnvironmentInput {
   shell: string;
   env: Record<string, string>;
+  baseEnv?: Record<string, string>;
   zshShellIntegrationDir?: string;
   paseoCliBinDir?: string | null;
   paseoHookCliPath?: string | null;
@@ -410,84 +414,12 @@ export async function resolveTerminalSpawnCommand(
   return { command: resolved, args };
 }
 
+export { resolvePaseoCliBinDir, resolvePaseoCliExecutablePath };
+
 export function resolveZshShellIntegrationDir(): string {
   return fileURLToPath(new URL("./shell-integration/zsh", import.meta.url));
 }
 
-function resolveExternalProcessPath(filePath: string): string {
-  return filePath.replace(/\.asar(?=[/\\]|$)/, ".asar.unpacked");
-}
-
-export function resolvePaseoCliBinDir(): string | null {
-  const cliExecutable = resolvePaseoCliExecutablePath();
-  return cliExecutable ? dirname(cliExecutable) : null;
-}
-
-export function resolvePaseoCliExecutablePath(): string | null {
-  const configuredCli = process.env.PASEO_CLI?.trim();
-  if (configuredCli) {
-    return resolvePath(configuredCli);
-  }
-
-  const cliEntrypoint = resolvePaseoCliBinEntrypoint();
-  if (!cliEntrypoint) {
-    return null;
-  }
-
-  const externalCliEntrypoint = resolveExternalProcessPath(cliEntrypoint);
-  const npmBinDir = findNpmBinDir(dirname(externalCliEntrypoint));
-  if (npmBinDir) {
-    const shim = resolvePaseoCliShim(npmBinDir);
-    if (shim) {
-      return shim;
-    }
-  }
-
-  return externalCliEntrypoint;
-}
-
-function resolvePaseoCliBinEntrypoint(): string | null {
-  try {
-    return require.resolve(PASEO_CLI_BIN_ENTRY);
-  } catch {
-    return null;
-  }
-}
-
-function findNpmBinDir(startPath: string): string | null {
-  let current = startPath;
-  while (true) {
-    const candidate = join(current, "node_modules", ".bin");
-    if (hasPaseoCliShim(candidate)) {
-      return candidate;
-    }
-
-    const parent = dirname(current);
-    if (parent === current) {
-      return null;
-    }
-    current = parent;
-  }
-}
-
-function hasPaseoCliShim(binDir: string): boolean {
-  return resolvePaseoCliShim(binDir) !== null;
-}
-
-function resolvePaseoCliShim(binDir: string): string | null {
-  for (const name of paseoCliShimNames()) {
-    const candidate = join(binDir, name);
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-  }
-  return null;
-}
-
-function paseoCliShimNames(): string[] {
-  return process.platform === "win32" ? ["paseo.cmd", "paseo.exe", "paseo"] : ["paseo"];
-}
-
 function resolveZshShellIntegrationRuntimeDir(): string {
   let username = "unknown";
   try {
@@ -517,10 +449,14 @@ function prepareZshShellIntegrationRuntimeDir(sourceDir = resolveZshShellIntegra
 export function buildTerminalEnvironment(
   input: BuildTerminalEnvironmentInput,
 ): Record<string, string> {
-  const baseEnv: Record<string, string> = createExternalProcessEnv(process.env, input.env, {
-    TERM: "xterm-256color",
-    TERM_PROGRAM: "kitty",
-  });
+  const baseEnv: Record<string, string> = createExternalProcessEnv(
+    input.baseEnv ?? process.env,
+    input.env,
+    {
+      TERM: "xterm-256color",
+      TERM_PROGRAM: "kitty",
+    },
+  );
   const envWithAgentHooks = prependPaseoCliToPath(
     baseEnv,
     input.paseoCliBinDir === undefined ? resolvePaseoCliBinDir() : input.paseoCliBinDir,
@@ -556,6 +492,23 @@ function injectPaseoHookCli(
   };
 }
 
+// The environment and CLI path a terminal starts from: the caller's when it sends them (the
+// daemon controlling a detached worker does), this process's otherwise.
+function resolveTerminalEnvironmentSource(
+  input: Pick<CreateTerminalOptions, "baseEnv" | "paseoCliPath">,
+): Pick<BuildTerminalEnvironmentInput, "baseEnv" | "paseoCliBinDir" | "paseoHookCliPath"> {
+  const source: Pick<
+    BuildTerminalEnvironmentInput,
+    "baseEnv" | "paseoCliBinDir" | "paseoHookCliPath"
+  > = {};
+  if (input.baseEnv) source.baseEnv = input.baseEnv;
+  if (input.paseoCliPath !== undefined) {
+    source.paseoCliBinDir = input.paseoCliPath ? dirname(input.paseoCliPath) : null;
+    source.paseoHookCliPath = input.paseoCliPath;
+  }
+  return source;
+}
+
 function prependPaseoCliToPath(
   env: Record<string, string>,
   cliBinDir: string | null,
@@ -581,179 +534,6 @@ function prependPathEntry(currentPath: string, entry: string): string {
   return [entry, ...entries].join(delimiter);
 }
 
-function extractCell(terminal: TerminalType, row: number, col: number): TerminalCell {
-  const buffer = terminal.buffer.active;
-  const line = buffer.getLine(row);
-  if (!line) {
-    return { char: " ", fg: undefined, bg: undefined };
-  }
-
-  const cell = line.getCell(col);
-  if (!cell) {
-    return { char: " ", fg: undefined, bg: undefined };
-  }
-
-  // Color modes from xterm.js: 0=DEFAULT, 1=16 colors (ANSI), 2=256 colors, 3=RGB
-  // getFgColorMode() returns packed value with mode in upper byte (e.g. 0x01000000 for mode 1)
-  const fgModeRaw = cell.getFgColorMode();
-  const bgModeRaw = cell.getBgColorMode();
-  const fgMode = fgModeRaw >> 24;
-  const bgMode = bgModeRaw >> 24;
-
-  // Only return color if not default (mode 0)
-  const fg = fgMode !== 0 ? cell.getFgColor() : undefined;
-  const bg = bgMode !== 0 ? cell.getBgColor() : undefined;
-
-  return {
-    // Wide chars (CJK) span two cells; xterm returns "" for the zero-width
-    // continuation. Collapsing it to " " injects a real space on restore.
-    char: cell.getWidth() === 0 ? "" : cell.getChars() || " ",
-    fg,
-    bg,
-    fgMode: fgMode !== 0 ? fgMode : undefined,
-    bgMode: bgMode !== 0 ? bgMode : undefined,
-    bold: cell.isBold() !== 0,
-    italic: cell.isItalic() !== 0,
-    underline: cell.isUnderline() !== 0,
-    dim: cell.isDim() !== 0,
-    inverse: cell.isInverse() !== 0,
-    strikethrough: cell.isStrikethrough() !== 0,
-  };
-}
-
-function extractGrid(terminal: TerminalType): TerminalCell[][] {
-  const grid: TerminalCell[][] = [];
-  const buffer = terminal.buffer.active;
-  // Visible viewport starts at baseY
-  const baseY = buffer.baseY;
-
-  for (let row = 0; row < terminal.rows; row++) {
-    const rowCells: TerminalCell[] = [];
-    for (let col = 0; col < terminal.cols; col++) {
-      rowCells.push(extractCell(terminal, baseY + row, col));
-    }
-    grid.push(rowCells);
-  }
-
-  return grid;
-}
-
-function extractScrollback(
-  terminal: TerminalType,
-  options?: { scrollbackLines?: number },
-): TerminalCell[][] {
-  const scrollback: TerminalCell[][] = [];
-  const buffer = terminal.buffer.active;
-  // baseY is the first row of the visible viewport (0-indexed)
-  // Lines 0 to baseY-1 are in scrollback, lines baseY onwards are visible
-  const scrollbackLines = buffer.baseY;
-  const startRow =
-    typeof options?.scrollbackLines === "number"
-      ? Math.max(0, scrollbackLines - options.scrollbackLines)
-      : 0;
-
-  for (let row = startRow; row < scrollbackLines; row++) {
-    const rowCells: TerminalCell[] = [];
-    const line = buffer.getLine(row);
-    for (let col = 0; col < terminal.cols; col++) {
-      if (line) {
-        const cell = line.getCell(col);
-        if (cell) {
-          const fgModeRaw = cell.getFgColorMode();
-          const bgModeRaw = cell.getBgColorMode();
-          const fgMode = fgModeRaw >> 24;
-          const bgMode = bgModeRaw >> 24;
-          const fg = fgMode !== 0 ? cell.getFgColor() : undefined;
-          const bg = bgMode !== 0 ? cell.getBgColor() : undefined;
-          rowCells.push({
-            // Wide chars (CJK) span two cells; xterm returns "" for the zero-width
-            // continuation. Collapsing it to " " injects a real space on restore.
-            char: cell.getWidth() === 0 ? "" : cell.getChars() || " ",
-            fg,
-            bg,
-            fgMode: fgMode !== 0 ? fgMode : undefined,
-            bgMode: bgMode !== 0 ? bgMode : undefined,
-            bold: cell.isBold() !== 0,
-            italic: cell.isItalic() !== 0,
-            underline: cell.isUnderline() !== 0,
-            dim: cell.isDim() !== 0,
-            inverse: cell.isInverse() !== 0,
-            strikethrough: cell.isStrikethrough() !== 0,
-          });
-        } else {
-          rowCells.push({ char: " ", fg: undefined, bg: undefined });
-        }
-      } else {
-        rowCells.push({ char: " ", fg: undefined, bg: undefined });
-      }
-    }
-    scrollback.push(rowCells);
-  }
-
-  return scrollback;
-}
-
-// xterm marks a line `isWrapped` when it is a continuation of the PREVIOUS line.
-// The snapshot carries the inverse, tmux-style flag — "this row continues onto the
-// next row" — so the client can rejoin and reflow logical lines. So row y's flag is
-// whether line y+1 is a wrapped continuation.
-function lineContinuesToNext(terminal: TerminalType, absoluteRow: number): boolean {
-  return terminal.buffer.active.getLine(absoluteRow + 1)?.isWrapped === true;
-}
-
-function extractGridWrapped(terminal: TerminalType): boolean[] {
-  const baseY = terminal.buffer.active.baseY;
-  const wrapped: boolean[] = [];
-  for (let row = 0; row < terminal.rows; row++) {
-    wrapped.push(lineContinuesToNext(terminal, baseY + row));
-  }
-  return wrapped;
-}
-
-function extractScrollbackWrapped(
-  terminal: TerminalType,
-  options?: { scrollbackLines?: number },
-): boolean[] {
-  const scrollbackLines = terminal.buffer.active.baseY;
-  const startRow =
-    typeof options?.scrollbackLines === "number"
-      ? Math.max(0, scrollbackLines - options.scrollbackLines)
-      : 0;
-  const wrapped: boolean[] = [];
-  for (let row = startRow; row < scrollbackLines; row++) {
-    wrapped.push(lineContinuesToNext(terminal, row));
-  }
-  return wrapped;
-}
-
-function extractCursorState(terminal: TerminalType): TerminalState["cursor"] {
-  const coreService = (terminal as unknown as { _core?: { coreService?: Record<string, unknown> } })
-    ._core?.coreService as
-    | {
-        decPrivateModes?: { cursorStyle?: unknown; cursorBlink?: unknown };
-        isCursorHidden?: unknown;
-      }
-    | undefined;
-  const cursorStyle = coreService?.decPrivateModes?.cursorStyle;
-  const normalizedCursorStyle =
-    cursorStyle === "block" || cursorStyle === "underline" || cursorStyle === "bar"
-      ? cursorStyle
-      : undefined;
-  const cursorBlink =
-    typeof coreService?.decPrivateModes?.cursorBlink === "boolean"
-      ? coreService.decPrivateModes.cursorBlink
-      : undefined;
-  const hidden = Boolean(coreService?.isCursorHidden);
-
-  return {
-    row: terminal.buffer.active.cursorY,
-    col: terminal.buffer.active.cursorX,
-    ...(hidden ? { hidden: true } : {}),
-    ...(normalizedCursorStyle ? { style: normalizedCursorStyle } : {}),
-    ...(typeof cursorBlink === "boolean" ? { blink: cursorBlink } : {}),
-  };
-}
-
 function normalizeProcessToken(token: string): string {
   if (token.length === 0) {
     return token;
@@ -967,7 +747,9 @@ export async function assertTerminalCommandCanStart(
   }
 }
 
-export async function createTerminal(options: CreateTerminalOptions): Promise<TerminalSession> {
+export async function createTerminal(
+  options: CreateTerminalOptions,
+): Promise<LocalTerminalSession> {
   const {
     cwd,
     workspaceId,
@@ -980,8 +762,10 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
     title: presetTitle,
     command,
     args = [],
+    baseEnv,
+    paseoCliPath,
   } = options;
-  const resolvedShell = shell ?? resolveDefaultTerminalShell();
+  const resolvedShell = shell ?? resolveDefaultTerminalShell({ env: baseEnv });
 
   const id = options.id ?? randomUUID();
   const listeners = new Set<(msg: ServerMessage) => void>();
@@ -1012,13 +796,9 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
   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: 1000,
-    allowProposedApi: true,
-  });
+  const terminal = createHeadlessTerminal({ rows, cols, scrollback: 10000 });
+
+  const serialize = createTerminalSerializer(terminal);
 
   ensureNodePtySpawnHelperExecutableForCurrentPlatform();
 
@@ -1033,6 +813,7 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
       ...activityEnv,
       PASEO_WORKSPACE_ID: workspaceId,
     },
+    ...resolveTerminalEnvironmentSource({ baseEnv, paseoCliPath }),
   });
 
   await assertTerminalCommandCanStart({ command, cwd, env: terminalEnv });
@@ -1255,6 +1036,10 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
       if (disposed || killed) {
         return;
       }
+      // Commit protocol modes with the parsed bytes, so a replay cut cannot
+      // combine an older xterm buffer with modes from queued future output.
+      const inputModeUpdate = inputModeTracker.feed(data);
+      for (const response of inputModeUpdate.responses) ptyProcess.write(response);
       stateRevision += 1;
       for (const listener of listeners) {
         listener({ type: "output", data, revision: stateRevision });
@@ -1265,10 +1050,6 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
   // Pipe PTY output to terminal emulator
   ptyProcess.onData((data) => {
     if (killed) return;
-    const inputModeUpdate = inputModeTracker.feed(data);
-    for (const response of inputModeUpdate.responses) {
-      ptyProcess.write(response);
-    }
     recentOutputChunks.push(data);
     recentOutputLength += data.length;
     // Drop whole leading chunks while the rest still covers the char limit, so
@@ -1326,32 +1107,15 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
     }
   }
 
-  function getState(snapshotOptions?: TerminalStateSnapshotOptions): TerminalState {
-    return {
+  function serializeReplay(replayOptions?: TerminalReplayOptions) {
+    const metadata = {
       rows: terminal.rows,
       cols: terminal.cols,
-      grid: extractGrid(terminal),
-      scrollback: extractScrollback(terminal, {
-        scrollbackLines: snapshotOptions?.scrollbackLines,
-      }),
-      cursor: extractCursorState(terminal),
-      ...(title ? { title } : {}),
-      ...(snapshotOptions?.includeWrapFlags
-        ? {
-            gridWrapped: extractGridWrapped(terminal),
-            scrollbackWrapped: extractScrollbackWrapped(terminal, {
-              scrollbackLines: snapshotOptions?.scrollbackLines,
-            }),
-          }
-        : {}),
-    };
-  }
-
-  function getStateSnapshot(snapshotOptions?: TerminalStateSnapshotOptions): TerminalStateSnapshot {
-    return {
-      state: getState(snapshotOptions),
+      retainedHistoryLines: terminal.buffer.normal.baseY,
       revision: stateRevision,
+      replayPreamble: getReplayPreamble(),
     };
+    return { metadata, data: serialize(replayOptions) };
   }
 
   function getSize(): { rows: number; cols: number } {
@@ -1417,14 +1181,10 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
     }
   }
 
-  function subscribe(
-    listener: (msg: ServerMessage) => void,
-    subscribeOptions?: TerminalSubscribeOptions,
-  ): () => void {
+  function subscribe(listener: (msg: ServerMessage) => void): () => void {
     let active = true;
     let snapshotDelivered = false;
     const queuedMessages: ServerMessage[] = [];
-    const initialSnapshot = subscribeOptions?.initialSnapshot ?? "state";
     const subscriptionListener = (msg: ServerMessage): void => {
       if (!active) {
         return;
@@ -1441,17 +1201,11 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
     terminal.write("", () => {
       if (!disposed && active && listeners.has(subscriptionListener)) {
         snapshotDelivered = true;
-        if (initialSnapshot === "ready") {
-          // Carry the input-mode preamble so the snapshot-less "ready" path
-          // (live restore) can replay it without a separate state fetch.
-          listener({
-            type: "snapshotReady",
-            revision: stateRevision,
-            replayPreamble: getReplayPreamble(),
-          });
-        } else {
-          listener({ type: "snapshot", ...getStateSnapshot() });
-        }
+        listener({
+          type: "snapshotReady",
+          revision: stateRevision,
+          replayPreamble: getReplayPreamble(),
+        });
         for (const message of queuedMessages.splice(0)) {
           listener(message);
         }
@@ -1624,6 +1378,7 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
 
   return {
     id,
+    pid: ptyProcess.pid,
     name,
     cwd,
     workspaceId,
@@ -1634,8 +1389,15 @@ export async function createTerminal(options: CreateTerminalOptions): Promise<Te
     onTitleChange,
     onActivityChange,
     getSize,
-    getState,
-    getStateSnapshot,
+    serializeReplay,
+    captureLines: (captureOptions) => captureTerminalLines(terminal.buffer.active, captureOptions),
+    hasOutput: () => {
+      const buffer = terminal.buffer.active;
+      for (let row = 0; row < buffer.length; row++) {
+        if (buffer.getLine(row)?.translateToString(true).trim()) return true;
+      }
+      return false;
+    },
     getReplayPreamble,
     getTitle,
     getActivity,
diff --git a/packages/server/src/terminal/test-utils/terminal-state.ts b/packages/server/src/terminal/test-utils/terminal-state.ts
new file mode 100644
index 0000000000..fb5f5d610a
--- /dev/null
+++ b/packages/server/src/terminal/test-utils/terminal-state.ts
@@ -0,0 +1,50 @@
+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 = createHeadlessTerminal({
+    rows: metadata.rows,
+    cols: metadata.cols,
+    scrollback: 10000,
+  });
+  try {
+    await new Promise<void>((resolve) => terminal.write(data, resolve));
+    const buffer = terminal.buffer.active;
+    const rows = Array.from({ length: buffer.length }, (_, row) =>
+      Array.from({ length: terminal.cols }, (_cell, col) => {
+        const cell = buffer.getLine(row)!.getCell(col)!;
+        const fgMode = cell.getFgColorMode() >> 24;
+        const bgMode = cell.getBgColorMode() >> 24;
+        return {
+          char: cell.getWidth() === 0 ? "" : cell.getChars() || " ",
+          fg: fgMode ? cell.getFgColor() : undefined,
+          bg: bgMode ? cell.getBgColor() : undefined,
+          fgMode: fgMode || undefined,
+          bgMode: bgMode || undefined,
+          bold: !!cell.isBold(),
+          italic: !!cell.isItalic(),
+          underline: !!cell.isUnderline(),
+          dim: !!cell.isDim(),
+          inverse: !!cell.isInverse(),
+          strikethrough: !!cell.isStrikethrough(),
+        };
+      }),
+    );
+    const wrapped = rows.map((_, i) => buffer.getLine(i + 1)?.isWrapped === true);
+    return {
+      rows: terminal.rows,
+      cols: terminal.cols,
+      grid: rows.slice(buffer.baseY),
+      scrollback: rows.slice(0, buffer.baseY),
+      gridWrapped: wrapped.slice(buffer.baseY),
+      scrollbackWrapped: wrapped.slice(0, buffer.baseY),
+      cursor: { row: buffer.cursorY, col: buffer.cursorX },
+      ...(session.getTitle() ? { title: session.getTitle() } : {}),
+    };
+  } finally {
+    terminal.dispose();
+  }
+}
diff --git a/packages/server/src/terminal/worker-terminal-manager.test.ts b/packages/server/src/terminal/worker-terminal-manager.test.ts
index e11c9eca9f..26cbb031d0 100644
--- a/packages/server/src/terminal/worker-terminal-manager.test.ts
+++ b/packages/server/src/terminal/worker-terminal-manager.test.ts
@@ -1,13 +1,41 @@
+import { TerminalInputModeTracker } from "@getpaseo/protocol/terminal-input-mode";
+import { encodeTerminalKeyInput } from "@getpaseo/protocol/terminal-key-input";
+import type { SubscribeTerminalRequest } from "@getpaseo/protocol/messages";
+import { TerminalSessionController } from "./terminal-session-controller.js";
+import { SessionDelivery } from "../server/session/owned-subscriptions/index.js";
+import {
+  decodeTerminalStreamFrame,
+  TerminalStreamOpcode,
+  type TerminalStreamFrame,
+} from "@getpaseo/protocol/binary-frames/index";
+import type { SessionOutboundMessage } from "../server/messages.js";
+import { createConnection } from "node:net";
+import { attachFramedSocket } from "./terminal-worker-frames.js";
+import xterm from "@xterm/headless";
 import { afterEach, expect, it } from "vitest";
 import { isPlatform } from "../test-utils/platform.js";
 import { EventEmitter } from "node:events";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  closeSync,
+  existsSync,
+  openSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { delimiter, join } from "node:path";
 import { tmpdir } from "node:os";
-import { createWorkerTerminalManager } from "./worker-terminal-manager.js";
+import pino from "pino";
+import {
+  createWorkerTerminalManager,
+  startWorkerTerminalManager,
+  type DaemonTerminalManager,
+} from "./worker-terminal-manager.js";
 import type {
   TerminalActivityTransitionEvent,
-  TerminalManager,
   TerminalWorkspaceContributionChangedEvent,
 } from "./terminal-manager.js";
 import {
@@ -19,8 +47,37 @@ import type { TerminalState } from "@getpaseo/protocol/messages";
 import type { TerminalActivity } from "@getpaseo/protocol/terminal-activity";
 import type {
   TerminalWorkerRequest,
+  WorkerTerminalState,
   TerminalWorkerToParentMessage,
 } from "./terminal-worker-protocol.js";
+import { classifyTerminalProgramProcess } from "./terminal-worker-ownership.js";
+import { createTerminalWorkerProcessInspector } from "./terminal-worker-processes.js";
+import {
+  readUnconfirmedTerminalCleanup,
+  reapTerminalWorkers,
+  TerminalCleanupNotConfirmedError,
+} from "./terminal-worker-reaper.js";
+import {
+  listTerminalWorkerRecords,
+  readTerminalWorkerRecord,
+  terminalWorkerDirectory,
+  terminalWorkerRecordPath,
+  writeTerminalWorkerRecord,
+  writeTerminalCleanupRecord,
+  type TerminalWorkerRecord,
+} from "./terminal-worker-record.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, TerminalWorkerLaunchError } from "./terminal-worker-launch.js";
+import { currentBootId } from "../server/pid-lock.js";
+import { spawn } from "node:child_process";
 
 type TerminalRow = TerminalState["grid"][number];
 
@@ -46,8 +103,35 @@ async function waitForCondition(
   throw new Error(`Timed out after ${timeoutMs}ms waiting for condition`);
 }
 
-function getVisibleText(session: TerminalSession): string {
-  return getVisibleTextFromState(session.getState());
+async function readReplay(manager: DaemonTerminalManager, id: string) {
+  const chunks: Uint8Array[] = [];
+  const metadata = await manager.replayTerminal(id, undefined, (event) => {
+    if (event.type === "data") chunks.push(event.data);
+  });
+  if (!metadata) return null;
+  const terminal = new xterm.Terminal({
+    rows: metadata.rows,
+    cols: metadata.cols,
+    scrollback: 1000,
+    allowProposedApi: true,
+  });
+  await new Promise<void>((resolve) => terminal.write(Buffer.concat(chunks), resolve));
+  const buffer = terminal.buffer.active;
+  const rows = Array.from({ length: buffer.length }, (_, i) => {
+    const line = buffer.getLine(i)!;
+    return Array.from({ length: metadata.cols }, (_cell, col) => ({
+      char: line.getCell(col)?.getChars() || " ",
+    }));
+  });
+  const state: TerminalState = {
+    rows: metadata.rows,
+    cols: metadata.cols,
+    scrollback: rows.slice(0, buffer.baseY),
+    grid: rows.slice(buffer.baseY),
+    cursor: { row: buffer.cursorY, col: buffer.cursorX },
+  };
+  terminal.dispose();
+  return { state, revision: metadata.revision };
 }
 
 function rowToText(row: TerminalRow): string {
@@ -76,20 +160,13 @@ function readRenderedTokenIndexesFromState(state: TerminalState): number[] {
   return indexes;
 }
 
-function createTerminalState(): TerminalState {
-  const blankCell = { char: " " };
-  return {
-    rows: 1,
-    cols: 1,
-    grid: [[blankCell]],
-    scrollback: [],
-    cursor: { row: 0, col: 0 },
-  };
+function createTerminalState(): WorkerTerminalState {
+  return { rows: 1, cols: 1, hasOutput: false };
 }
 
 class FakeTerminalWorker extends EventEmitter {
   connected = true;
-  killed = false;
+  readonly workerPid = 1;
   readonly sentMessages: TerminalWorkerRequest[] = [];
 
   send(message: TerminalWorkerRequest, callback: (error: Error | null) => void): boolean {
@@ -100,14 +177,7 @@ class FakeTerminalWorker extends EventEmitter {
 
   disconnect(): void {
     this.connected = false;
-    this.emit("exit", 0, null);
-  }
-
-  kill(): boolean {
-    this.killed = true;
-    this.connected = false;
-    this.emit("exit", 0, null);
-    return true;
+    this.emit("close");
   }
 
   emitWorkerMessage(message: TerminalWorkerToParentMessage): void {
@@ -115,8 +185,31 @@ class FakeTerminalWorker extends EventEmitter {
   }
 }
 
-let manager: TerminalManager | null = null;
+let manager: DaemonTerminalManager | null = null;
 const temporaryDirs: string[] = [];
+
+// A real detached worker in a throwaway home; afterEach closes its terminals and the worker.
+async function startRealWorkerManager(
+  options: {
+    getTerminalActivityUrl?: () => string | null;
+    requestTimeoutMs?: number;
+    paseoHome?: string;
+  } = {},
+): Promise<DaemonTerminalManager> {
+  const { paseoHome = createTemporaryHome(), ...rest } = options;
+  return startWorkerTerminalManager({
+    paseoHome,
+    paseoVersion: "0.0.0-test",
+    logger: pino({ level: "silent" }),
+    ...rest,
+  });
+}
+
+function createTemporaryHome(): string {
+  const paseoHome = mkdtempSync(join(tmpdir(), "worker-terminal-manager-home-"));
+  temporaryDirs.push(paseoHome);
+  return paseoHome;
+}
 const terminalSessions: TerminalSession[] = [];
 
 function trackTerminal(session: TerminalSession): TerminalSession {
@@ -150,7 +243,7 @@ afterEach(async () => {
         .catch(() => {}),
     ),
   );
-  manager?.killAll();
+  await manager?.closeTerminals();
   manager = null;
   while (temporaryDirs.length > 0) {
     const dir = temporaryDirs.pop();
@@ -160,10 +253,187 @@ afterEach(async () => {
   }
 });
 
+it("retires a killed worker's sessions and shares one replacement across concurrent creates", async () => {
+  const paseoHome = createTemporaryHome();
+  manager = await startRealWorkerManager({ paseoHome });
+  manager.registerCwdEnv({ cwd: paseoHome, env: { QA_RECOVERY_ENV: "retained" } });
+  const terminal = await manager.createTerminal({
+    workspaceId: "ws-recovery",
+    cwd: paseoHome,
+    ...nodeTerminalCommand(
+      "process.stdin.on('data', chunk => process.stdout.write('echo:' + process.env.QA_RECOVERY_ENV + ':' + chunk)); setInterval(() => {}, 1000)",
+    ),
+  });
+  const records = await listTerminalWorkerRecords(paseoHome);
+  const file = records.find((entry) => !("error" in entry));
+  if (!file || "error" in file) throw new Error("Missing worker record");
+  const changes: string[][] = [];
+  manager.subscribeTerminalsChanged((event) =>
+    changes.push(event.terminals.map((item) => item.id)),
+  );
+  const exits: unknown[] = [];
+  terminal.onExit((info) => exits.push(info));
+  process.kill(file.record.pid, "SIGKILL");
+  await waitForCondition(() => manager!.getTerminal(terminal.id) === undefined, 10000);
+  expect(changes).toContainEqual([]);
+  expect(exits).toHaveLength(1);
+  const sessions = await Promise.all(
+    Array.from({ length: 4 }, () =>
+      manager!.createTerminal({
+        workspaceId: "ws-recovery",
+        cwd: paseoHome,
+        ...nodeTerminalCommand(
+          "process.stdin.on('data', chunk => process.stdout.write('echo:' + process.env.QA_RECOVERY_ENV + ':' + chunk)); setInterval(() => {}, 1000)",
+        ),
+      }),
+    ),
+  );
+  for (const session of sessions) {
+    const output: string[] = [];
+    session.subscribe((message) => {
+      if (message.type === "output") output.push(message.data);
+    });
+    session.send({ type: "input", data: "recovered\r" });
+    await waitForCondition(() => output.join("").includes("echo:retained:recovered"), 10000);
+  }
+  expect(await manager.getTerminals(paseoHome)).toHaveLength(4);
+  const remaining = (await listTerminalWorkerRecords(paseoHome)).filter(
+    (entry) => !("error" in entry),
+  );
+  expect(remaining).toHaveLength(1);
+}, 30000);
+
+it("reconnects a live worker without replacing terminal sessions or processes", async () => {
+  const paseoHome = createTemporaryHome();
+  manager = await startRealWorkerManager({ paseoHome });
+  const terminal = await manager.createTerminal({
+    workspaceId: "ws-reconnect",
+    cwd: paseoHome,
+    ...nodeTerminalCommand(
+      "process.stdin.on('data', chunk => process.stdout.write('echo:' + chunk)); setInterval(() => {}, 1000)",
+    ),
+  });
+  const [before] = await workerRecords(paseoHome);
+  const pids = await recordedTerminalPids(paseoHome);
+  let replayRequests = 0;
+  terminal.subscribe((message) => {
+    if (message.type === "snapshotReady") replayRequests += 1;
+  });
+  // A second authenticated controller replaces the daemon's socket. The process stays alive.
+  const competitor = await connectTerminalWorker({
+    socketPath: before!.socketPath,
+    secret: before!.secret,
+  });
+  await waitForCondition(() => !competitor.connected, 10000);
+  await waitForCondition(async () => {
+    try {
+      return (await readReplay(manager!, terminal.id)) !== null;
+    } catch {
+      return false;
+    }
+  }, 10000);
+  await waitForCondition(() => replayRequests > 0, 1000);
+  expect(manager.getTerminal(terminal.id)).toBe(terminal);
+  expect(await recordedTerminalPids(paseoHome)).toEqual(pids);
+  expect((await workerRecords(paseoHome)).map((record) => record.pid)).toEqual([before!.pid]);
+  const output: string[] = [];
+  terminal.subscribe((message) => {
+    if (message.type === "output") output.push(message.data);
+  });
+  terminal.send({ type: "input", data: "reconnected\r" });
+  await waitForCondition(() => output.join("").includes("echo:reconnected"), 10000);
+}, 30000);
+
+it.each(["detach", "closeTerminals"] as const)(
+  "does not replace a failed worker during %s",
+  async (operation) => {
+    const paseoHome = createTemporaryHome();
+    manager = await startRealWorkerManager({ paseoHome });
+    await manager.createTerminal({
+      workspaceId: "ws-stop-recovery",
+      cwd: paseoHome,
+      ...nodeTerminalCommand("setInterval(() => {}, 1000)"),
+    });
+    const [record] = await workerRecords(paseoHome);
+    process.kill(record!.pid, "SIGKILL");
+    await manager[operation]();
+    await expect(
+      manager.createTerminal({ workspaceId: "ws-stop-recovery", cwd: paseoHome }),
+    ).rejects.toBeInstanceOf(NoTerminalWorkerAvailableError);
+    await manager.closeTerminals();
+    expect(await workerRecords(paseoHome)).toEqual([]);
+  },
+  30000,
+);
+
+it.each(["detach", "closeTerminals"] as const)(
+  "does not leak a replacement stopped during launch by %s",
+  async (operation) => {
+    const paseoHome = createTemporaryHome();
+    manager = await startRealWorkerManager({ paseoHome });
+    const terminal = await manager.createTerminal({
+      workspaceId: "ws-launch-race",
+      cwd: paseoHome,
+      ...nodeTerminalCommand("setInterval(() => {}, 1000)"),
+    });
+    const [record] = await workerRecords(paseoHome);
+    process.kill(record!.pid, "SIGKILL");
+    await waitForCondition(() => !manager!.getTerminal(terminal.id), 10000);
+    const creating = manager.createTerminal({ workspaceId: "ws-launch-race", cwd: paseoHome });
+    const rejected = expect(creating).rejects.toBeInstanceOf(NoTerminalWorkerAvailableError);
+    await manager[operation]();
+    await rejected;
+    await waitForCondition(async () => (await workerRecords(paseoHome)).length === 0, 10000);
+    expect(await manager.getTerminals(paseoHome)).toEqual([]);
+  },
+  30000,
+);
+
+it.each(["current", "draining"] as const)(
+  "keeps the peer usable when the %s worker dies",
+  async (target) => {
+    const paseoHome = createTemporaryHome();
+    const seeds = [
+      await launchDetachedWorkerWithTerminal(paseoHome),
+      await launchDetachedWorkerWithTerminal(paseoHome),
+    ];
+    // Exercise an existing seed adopted as current; launch age does not imply draining ownership.
+    const [firstAdopted] = await workerRecords(paseoHome);
+    const seed = seeds.find((candidate) => candidate.workerPid === firstAdopted!.pid)!;
+    manager = await startRealWorkerManager({ paseoHome });
+    const added = await manager.createTerminal({
+      workspaceId: "ws-peer",
+      cwd: seed.cwd,
+      ...nodeTerminalCommand("setInterval(() => {}, 1000)"),
+    });
+    const records = await workerRecords(paseoHome);
+    const current = records.find((record) =>
+      record.terminals.some((terminal) => terminal.id === added.id),
+    )!;
+    const draining = records.find((record) => record.pid !== current.pid)!;
+    const drainingId = draining.terminals[0]!.id;
+    const deadId = target === "current" ? added.id : drainingId;
+    const healthyId = target === "current" ? drainingId : added.id;
+    const healthy = manager.getTerminal(healthyId);
+    expect(healthy).toBeDefined();
+    process.kill(target === "current" ? current.pid : draining.pid, "SIGKILL");
+    await waitForCondition(() => !manager!.getTerminal(deadId), 10000);
+    expect(manager.getTerminal(healthyId)).toBe(healthy);
+    expect(await readReplay(manager, healthyId)).not.toBeNull();
+    await manager.createTerminal({
+      workspaceId: "ws-peer",
+      cwd: seed.cwd,
+      ...nodeTerminalCommand("setInterval(() => {}, 1000)"),
+    });
+    expect((await workerRecords(paseoHome)).length).toBeLessThanOrEqual(2);
+  },
+  30000,
+);
+
 it("creates a terminal through the worker and streams output", async () => {
   const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-output-"));
   temporaryDirs.push(cwd);
-  manager = createWorkerTerminalManager();
+  manager = await startRealWorkerManager();
   const session = trackTerminal(
     await manager.createTerminal({
       workspaceId: "ws-test",
@@ -177,38 +447,31 @@ it("creates a terminal through the worker and streams output", async () => {
     }),
   );
   const messages: string[] = [];
-  let snapshots = 0;
+  let snapshotReady = false;
   const unsubscribe = session.subscribe((message) => {
     if (message.type === "output") {
       messages.push(message.data);
     }
-    if (message.type === "snapshot") {
-      snapshots += 1;
+    if (message.type === "snapshotReady") {
+      snapshotReady = true;
     }
   });
-  await new Promise((resolve) => setTimeout(resolve, 100));
-  const snapshotsBeforeOutput = snapshots;
+  // 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") ||
-      getVisibleText(session).includes("worker-output:hello"),
-    10000,
-  );
-  await new Promise((resolve) => setTimeout(resolve, 100));
+  await waitForCondition(() => messages.join("").includes("worker-output:hello"), 10000);
   unsubscribe();
 
-  expect(messages.join("") + getVisibleText(session)).toContain("worker-output:hello");
-  expect(snapshots).toBe(snapshotsBeforeOutput);
+  expect(messages.join("")).toContain("worker-output:hello");
 });
 
 it("delivers rapid small writes complete and in order through worker coalescing", async () => {
   const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-coalesce-"));
   temporaryDirs.push(cwd);
   const burstGatePath = join(cwd, "burst-ready");
-  manager = createWorkerTerminalManager();
+  manager = await startRealWorkerManager();
   // The file gate starts the burst after this test subscribes without depending
   // on platform-specific PTY input echo/canonical-mode behavior.
   const session = trackTerminal(
@@ -237,19 +500,19 @@ it("delivers rapid small writes complete and in order through worker coalescing"
   session.subscribe((message) => {
     if (message.type === "output") {
       events.push({ type: "output", data: message.data });
-    } else if (message.type === "snapshot" || message.type === "snapshotReady") {
+    } else if (message.type === "snapshotReady") {
       events.push({ type: message.type });
     }
   });
 
-  // Let the snapshot subscription settle, then trigger the burst.
+  // Let readiness settle, then trigger the burst.
   await new Promise((resolve) => setTimeout(resolve, 100));
   writeFileSync(burstGatePath, "go");
 
   const expected = Array.from({ length: 500 }, (_, index) => index);
   let received: number[] = [];
   await waitForCondition(async () => {
-    const snapshot = await manager!.getTerminalState(session.id);
+    const snapshot = await readReplay(manager!, session.id);
     received = snapshot ? readRenderedTokenIndexesFromState(snapshot.state) : [];
     return expected.every((value, index) => received[index] === value);
   }, 10000);
@@ -258,20 +521,19 @@ it("delivers rapid small writes complete and in order through worker coalescing"
 
   await waitForCondition(() => events.some((event) => event.type === "output"), 10000);
 
-  // No snapshot may land after output it should have preceded: every snapshot
-  // event must come before the first output event.
+  // Readiness precedes the ordered live stream.
   const firstOutputIndex = events.findIndex((event) => event.type === "output");
   expect(firstOutputIndex).toBeGreaterThanOrEqual(0);
-  const snapshotAfterOutput = events
+  const readinessAfterOutput = events
     .slice(firstOutputIndex + 1)
-    .find((event) => event.type === "snapshot" || event.type === "snapshotReady");
-  expect(snapshotAfterOutput).toBeUndefined();
+    .find((event) => event.type === "snapshotReady");
+  expect(readinessAfterOutput).toBeUndefined();
 });
 
 it("pulls fresh terminal state from the worker authority", async () => {
   const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-state-"));
   temporaryDirs.push(cwd);
-  manager = createWorkerTerminalManager();
+  manager = await startRealWorkerManager();
   const session = trackTerminal(
     await manager.createTerminal({
       workspaceId: "ws-test",
@@ -285,7 +547,7 @@ it("pulls fresh terminal state from the worker authority", async () => {
 
   let visibleText = "";
   await waitForCondition(async () => {
-    const snapshot = await manager!.getTerminalState(session.id);
+    const snapshot = await readReplay(manager!, session.id);
     visibleText = snapshot ? getVisibleTextFromState(snapshot.state) : "";
     return visibleText.includes("worker-state-ready");
   }, 10000);
@@ -298,11 +560,11 @@ it("pulls fresh terminal state from the worker authority", async () => {
 // preamble-caching contract is verified on Linux/macOS; the daemon's input-mode
 // handling runs identically on every platform once the escape is observed.
 it.skipIf(isPlatform("win32"))(
-  "caches the input-mode replay preamble from the worker after getTerminalState",
+  "caches input modes from worker output independently of replay capture",
   async () => {
     const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-preamble-"));
     temporaryDirs.push(cwd);
-    manager = createWorkerTerminalManager();
+    manager = await startRealWorkerManager();
     // \x1b[>1u pushes kitty keyboard flag 1, which the worker's input-mode
     // tracker records and reflects in its replay preamble (\x1b[=1;1u).
     const session = trackTerminal(
@@ -316,11 +578,10 @@ it.skipIf(isPlatform("win32"))(
       }),
     );
 
-    await waitForCondition(async () => {
-      const snapshot = await manager!.getTerminalState(session.id);
-      return snapshot !== null && session.getReplayPreamble() === "\x1b[=1;1u";
-    }, 10000);
-
+    await waitForCondition(() => session.getReplayPreamble() === "\x1b[=1;1u", 10000);
+    // Initial shared modes must be ready without a replay response repairing the cache.
+    expect(session.getReplayPreamble()).toBe("\x1b[=1;1u");
+    expect(await readReplay(manager!, session.id)).not.toBeNull();
     expect(session.getReplayPreamble()).toBe("\x1b[=1;1u");
   },
 );
@@ -328,7 +589,7 @@ it.skipIf(isPlatform("win32"))(
 it("refreshes cached terminal title after worker title changes", async () => {
   const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-title-"));
   temporaryDirs.push(cwd);
-  manager = createWorkerTerminalManager();
+  manager = await startRealWorkerManager();
   const session = trackTerminal(
     await manager.createTerminal({
       workspaceId: "ws-test",
@@ -342,28 +603,28 @@ it("refreshes cached terminal title after worker title changes", async () => {
 
   await waitForCondition(() => session.getTitle() === "Build Output", 10000);
 
-  expect(session.getState().title).toBe("Build Output");
+  expect(session.getTitle()).toBe("Build Output");
 });
 
 it("refreshes cached terminal size after worker resize", async () => {
   const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-resize-"));
   temporaryDirs.push(cwd);
-  manager = createWorkerTerminalManager();
+  manager = await startRealWorkerManager();
   const session = trackTerminal(await manager.createTerminal({ cwd, workspaceId: "ws-test" }));
 
   session.send({ type: "resize", rows: 10, cols: 40 });
-  const snapshot = await manager.getTerminalState(session.id);
+  const snapshot = await readReplay(manager, session.id);
 
   expect(snapshot?.state.rows).toBe(10);
   expect(snapshot?.state.cols).toBe(40);
-  expect(session.getState().rows).toBe(10);
-  expect(session.getState().cols).toBe(40);
+  expect(session.getSize().rows).toBe(10);
+  expect(session.getSize().cols).toBe(40);
 });
 
 it("captures terminal output from the worker authority", async () => {
   const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-capture-"));
   temporaryDirs.push(cwd);
-  manager = createWorkerTerminalManager();
+  manager = await startRealWorkerManager();
   const session = trackTerminal(await manager.createTerminal({ cwd, workspaceId: "ws-test" }));
 
   session.send({ type: "input", data: "echo hello world\r" });
@@ -382,7 +643,7 @@ it("does not surface fire-and-forget send timeouts as unhandled rejections", asy
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 5,
-    forkWorker: () => worker,
+    worker,
   });
 
   worker.emitWorkerMessage({
@@ -416,7 +677,7 @@ it("does not surface fire-and-forget send timeouts as unhandled rejections", asy
 });
 
 it("keeps registered cwd env inheritance behind the worker manager interface", async () => {
-  manager = createWorkerTerminalManager();
+  manager = await startRealWorkerManager();
   const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-env-"));
   temporaryDirs.push(cwd);
   const markerPath = join(cwd, "env.txt");
@@ -449,7 +710,7 @@ it("injects parent-minted terminal activity env through the worker", async () =>
   temporaryDirs.push(cwd);
   const envPath = join(cwd, "activity-env.json");
   const activityUrl = "http://127.0.0.1:12345/api/terminal-activity";
-  manager = createWorkerTerminalManager({
+  manager = await startRealWorkerManager({
     getTerminalActivityUrl: () => activityUrl,
   });
 
@@ -496,8 +757,234 @@ it("injects parent-minted terminal activity env through the worker", async () =>
   expect(env.path?.split(delimiter)[0]).toBe(paseoCliBinDir);
 });
 
+it("adopts a detached worker's terminals with their activity tokens and keeps them usable", async () => {
+  const paseoHome = createTemporaryHome();
+  const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-adopt-"));
+  temporaryDirs.push(cwd);
+  const envPath = join(cwd, "adopt-env.json");
+  const first = await startRealWorkerManager({ paseoHome });
+  const created = await first.createTerminal({
+    workspaceId: "ws-adopt",
+    cwd,
+    ...nodeTerminalCommand(`
+      require("node:fs").writeFileSync(
+        ${JSON.stringify(envPath)},
+        JSON.stringify({ token: process.env.PASEO_ACTIVITY_TOKEN }),
+      );
+      process.stdin.on("data", (chunk) => {
+        process.stdout.write("adopted-output:" + chunk.toString());
+      });
+      setInterval(() => {}, 1000);
+    `),
+  });
+  await waitForCondition(() => existsSync(envPath), 10000);
+  const { token } = JSON.parse(readFileSync(envPath, "utf8")) as { token: string };
+
+  await first.detach();
+  manager = await startRealWorkerManager({ paseoHome });
+
+  const adopted = manager.getTerminal(created.id);
+  expect(adopted?.workspaceId).toBe("ws-adopt");
+  expect(await manager.getTerminals(cwd)).toHaveLength(1);
+  expect(manager.validateTerminalActivityToken(created.id, token)).toBe("valid");
+  const messages: string[] = [];
+  adopted?.subscribe((message) => {
+    if (message.type === "output") messages.push(message.data);
+  });
+  adopted?.send({ type: "input", data: "after-adopt\r" });
+  await waitForCondition(() => messages.join("").includes("adopted-output:after-adopt"), 10000);
+});
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The terminals the worker itself recorded, read from its own record file.
+async function recordedTerminalPids(paseoHome: string): Promise<Map<string, number>> {
+  const pids = new Map<string, number>();
+  const directory = terminalWorkerDirectory(paseoHome);
+  for (const name of readdirSync(directory).filter((entry) => /^\d+\.json$/.test(entry))) {
+    for (const entry of (await readTerminalWorkerRecord(join(directory, name))).terminals) {
+      pids.set(entry.id, entry.pid);
+    }
+  }
+  return pids;
+}
+
+it.each([false, true])(
+  "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-"));
+    temporaryDirs.push(cwd);
+    const first = await startRealWorkerManager({ paseoHome });
+    manager = first;
+    const exitRequestPath = join(cwd, "exit-requested");
+    const exitObservedPath = join(cwd, "exit-observed");
+    const ending = await first.createTerminal({
+      workspaceId: "ws-unfinished-kill",
+      cwd,
+      ...nodeTerminalCommand(`
+      const { existsSync, writeFileSync } = require("node:fs");
+      setInterval(() => {
+        if (existsSync(${JSON.stringify(exitRequestPath)})) {
+          writeFileSync(${JSON.stringify(exitObservedPath)}, "");
+          process.exit(0);
+        }
+      }, 25);
+    `),
+    });
+    const remaining = await first.createTerminal({
+      workspaceId: "ws-unfinished-kill",
+      cwd,
+      ...nodeTerminalCommand("setInterval(() => {}, 1000);"),
+    });
+    const pids = await recordedTerminalPids(paseoHome);
+    const endingPid = pids.get(ending.id)!;
+    const remainingPid = pids.get(remaining.id)!;
+    const [record] = await workerRecords(paseoHome);
+
+    // 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 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.
+    // Windows cannot replace the record while this handle is open. The exit must
+    // still reach the controller, and publication must recover after release.
+    const recordFd = holdReader
+      ? openSync(terminalWorkerRecordPath(paseoHome, record!.pid), "r")
+      : null;
+    try {
+      writeFileSync(exitRequestPath, "");
+      await waitForCondition(() => first.getTerminal(ending.id) === undefined, 10000);
+      expect(existsSync(exitObservedPath)).toBe(true);
+      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);
+    }
+    await waitForCondition(
+      async () => !(await recordedTerminalPids(paseoHome)).has(ending.id),
+      10000,
+    );
+    expect((await readUnconfirmedTerminalCleanup(paseoHome)).length).toBeGreaterThan(0);
+
+    await first.detach();
+    manager = await startRealWorkerManager({ paseoHome });
+
+    expect(manager.getTerminal(remaining.id)).toBeUndefined();
+    expect(await manager.getTerminals(cwd)).toEqual([]);
+    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);
+  },
+);
+
+// The worker's own `ps`, delayed: a program that exits while the worker reads its birth time
+// lands its exit in the middle of creation. Only the worker launched while this PATH is set sees
+// the shim; the PATH is restored as soon as it is up.
+async function startWorkerWithSlowProcessTable(
+  delaySeconds: number,
+  options: { paseoHome?: string; requestTimeoutMs?: number } = {},
+): Promise<DaemonTerminalManager> {
+  const realPs = (process.env.PATH ?? "")
+    .split(delimiter)
+    .map((dir) => join(dir, "ps"))
+    .find((candidate) => existsSync(candidate));
+  if (!realPs) throw new Error("ps not found on PATH");
+  const shimDir = createTemporaryHome();
+  writeFileSync(join(shimDir, "ps"), `#!/bin/sh\nsleep ${delaySeconds}\nexec ${realPs} "$@"\n`, {
+    mode: 0o755,
+  });
+  const originalPath = process.env.PATH;
+  process.env.PATH = `${shimDir}${delimiter}${originalPath ?? ""}`;
+  try {
+    return await startRealWorkerManager(options);
+  } finally {
+    process.env.PATH = originalPath;
+  }
+}
+
+async function expectCompletedShortCommand(
+  terminalManager: DaemonTerminalManager,
+  script: string,
+): Promise<void> {
+  const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-short-"));
+  temporaryDirs.push(cwd);
+
+  const session = await terminalManager.createTerminal({
+    workspaceId: "ws-test",
+    cwd,
+    command: "/bin/sh",
+    args: ["-c", script],
+  });
+
+  await waitForCondition(() => session.getExitInfo() !== null, 10000);
+  expect(session.getExitInfo()?.exitCode).toBe(0);
+  expect(terminalManager.getTerminal(session.id)).toBeUndefined();
+  expect(await terminalManager.getTerminals(cwd)).toEqual([]);
+  expect(await readReplay(terminalManager, session.id)).toBeNull();
+}
+
+it.skipIf(isPlatform("win32"))(
+  "creates a short command that finishes before creation returns, with its exit",
+  async () => {
+    manager = await startRealWorkerManager();
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      await expectCompletedShortCommand(manager, "echo short; exit 0");
+    }
+  },
+);
+
+it.skipIf(isPlatform("win32"))(
+  "publishes the creation before an exit that arrives while the program is being recorded",
+  async () => {
+    manager = await startWorkerWithSlowProcessTable(0.3);
+    await expectCompletedShortCommand(manager, "sleep 0.1; echo short; exit 0");
+  },
+);
+
 it("starts the default shell through the worker and accepts quoted commands", async () => {
-  manager = createWorkerTerminalManager();
+  manager = await startRealWorkerManager();
   const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-shell-"));
   temporaryDirs.push(cwd);
   const markerPath = join(cwd, "shell quoted marker.txt");
@@ -518,7 +1005,7 @@ it("lists subdirectory terminals when querying the workspace root", async () =>
   const subdirCwd = join(rootCwd, "apps", "mobile");
   mkdirSync(subdirCwd, { recursive: true });
   temporaryDirs.push(rootCwd);
-  manager = createWorkerTerminalManager();
+  manager = await startRealWorkerManager();
   const created = trackTerminal(
     await manager.createTerminal({
       workspaceId: "ws-test",
@@ -536,7 +1023,7 @@ it("lists terminals locally without waiting on the worker", async () => {
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 5,
-    forkWorker: () => worker,
+    worker,
   });
 
   worker.emitWorkerMessage({
@@ -577,7 +1064,7 @@ it("includes only stamped terminals in workspace-scoped local reads", async () =
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 5,
-    forkWorker: () => worker,
+    worker,
   });
 
   worker.emitWorkerMessage({
@@ -629,7 +1116,7 @@ it("rejects non-absolute cwd in getTerminals", async () => {
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 5,
-    forkWorker: () => worker,
+    worker,
   });
 
   await expect(manager.getTerminals("relative/path")).rejects.toThrow("cwd must be absolute path");
@@ -639,7 +1126,7 @@ it("surfaces worker activity changes via getActivity, onActivityChange, and term
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 50,
-    forkWorker: () => worker,
+    worker,
   });
 
   worker.emitWorkerMessage({
@@ -702,7 +1189,7 @@ it("sets terminal activity through a worker request", async () => {
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 50,
-    forkWorker: () => worker,
+    worker,
   });
   worker.emitWorkerMessage({
     type: "terminalCreated",
@@ -735,7 +1222,7 @@ it("clears terminal attention through a worker request", async () => {
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 50,
-    forkWorker: () => worker,
+    worker,
   });
   worker.emitWorkerMessage({
     type: "terminalCreated",
@@ -766,7 +1253,7 @@ it("clears terminal attention through a worker request", async () => {
 it("clears finished attention on a real terminal", async () => {
   const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-attention-"));
   temporaryDirs.push(cwd);
-  manager = createWorkerTerminalManager();
+  manager = await startRealWorkerManager();
   const session = trackTerminal(
     await manager.createTerminal({
       workspaceId: "ws-test",
@@ -802,7 +1289,7 @@ it("clears finished attention on a real terminal", async () => {
 it("removes worker terminals after killAndWait", async () => {
   const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-kill-"));
   temporaryDirs.push(cwd);
-  manager = createWorkerTerminalManager();
+  manager = await startRealWorkerManager();
   const session = trackTerminal(
     await manager.createTerminal({
       workspaceId: "ws-test",
@@ -827,7 +1314,7 @@ it("produces one terminals-changed snapshot per title change", async () => {
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 50,
-    forkWorker: () => worker,
+    worker,
   });
 
   worker.emitWorkerMessage({
@@ -864,7 +1351,7 @@ it("produces one terminals-changed snapshot and one contribution event per activ
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 50,
-    forkWorker: () => worker,
+    worker,
   });
 
   worker.emitWorkerMessage({
@@ -914,7 +1401,7 @@ it("removes a killed worker terminal from terminalExit without duplicate snapsho
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 50,
-    forkWorker: () => worker,
+    worker,
   });
   const workingActivity = { state: "working" as const, changedAt: 1000 };
 
@@ -973,7 +1460,7 @@ it("does not resurrect a terminal that exited before its create response was han
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 50,
-    forkWorker: () => worker,
+    worker,
   });
 
   const snapshots: Array<{ cwd: string; terminalIds: string[] }> = [];
@@ -1026,7 +1513,7 @@ it("replays the exit to a listener attached after a create that lost the race",
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 50,
-    forkWorker: () => worker,
+    worker,
   });
 
   const created = manager.createTerminal({
@@ -1074,7 +1561,7 @@ it("rejects createTerminal and registers nothing when the worker cannot start th
   const worker = new FakeTerminalWorker();
   manager = createWorkerTerminalManager({
     requestTimeoutMs: 50,
-    forkWorker: () => worker,
+    worker,
   });
 
   const snapshots: Array<{ cwd: string; terminalIds: string[] }> = [];
@@ -1104,3 +1591,1317 @@ it("rejects createTerminal and registers nothing when the worker cannot start th
   expect(await manager.getTerminals("/workspace")).toEqual([]);
   expect(snapshots).toEqual([]);
 });
+
+// The live worker records in a home, by worker pid.
+async function workerRecords(paseoHome: string): Promise<TerminalWorkerRecord[]> {
+  return (await listTerminalWorkerRecords(paseoHome)).flatMap((file) =>
+    "record" in file && !file.record.closing ? [file.record] : [],
+  );
+}
+
+// A worker launched while the override is set reports that protocol version; the variable is
+// restored as soon as it is up, so later workers report the build's own.
+async function startManagerWithWorkerProtocol(
+  paseoHome: string,
+  protocolVersion: number,
+): Promise<DaemonTerminalManager> {
+  const previous = process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV];
+  process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV] = String(protocolVersion);
+  try {
+    return await startRealWorkerManager({ paseoHome });
+  } finally {
+    if (previous === undefined) delete process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV];
+    else process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV] = previous;
+  }
+}
+
+// A terminal running an idle program in a worker that reports `protocolVersion`, left running
+// after its daemon lets go (stop --keep-terminals).
+async function leaveWorkerWithTerminal(
+  paseoHome: string,
+  protocolVersion: number,
+): Promise<{ terminalId: string; programPid: number; workerPid: number; cwd: string }> {
+  const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-protocol-"));
+  temporaryDirs.push(cwd);
+  const previous = await startManagerWithWorkerProtocol(paseoHome, protocolVersion);
+  const session = await previous.createTerminal({
+    workspaceId: "ws-protocol",
+    cwd,
+    ...nodeTerminalCommand("setInterval(() => {}, 1000);"),
+  });
+  const [record] = await workerRecords(paseoHome);
+  await previous.detach();
+  return {
+    terminalId: session.id,
+    programPid: (await recordedTerminalPids(paseoHome)).get(session.id)!,
+    workerPid: record!.pid,
+    cwd,
+  };
+}
+
+it.each([1, 4])(
+  "hard cuts unreleased worker protocol %s, closing its terminals",
+  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 });
+
+    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);
+  },
+);
+
+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);
+
+  manager = await startRealWorkerManager({ paseoHome });
+
+  const unavailable = manager.getUnavailableError?.();
+  expect(unavailable).toBeInstanceOf(TerminalWorkerIncompatibleError);
+  expect(unavailable?.message).toContain("worker protocol 6");
+  await expect(manager.getTerminals(newer.cwd)).rejects.toBeInstanceOf(
+    TerminalWorkerIncompatibleError,
+  );
+  await expect(
+    manager.createTerminal({ workspaceId: "ws-protocol", cwd: newer.cwd }),
+  ).rejects.toBeInstanceOf(TerminalWorkerIncompatibleError);
+  expect(isProcessAlive(newer.programPid)).toBe(true);
+  expect((await workerRecords(paseoHome)).map((record) => record.pid)).toEqual([newer.workerPid]);
+
+  await manager.closeTerminals();
+
+  expect(isProcessAlive(newer.workerPid)).toBe(false);
+  expect(isProcessAlive(newer.programPid)).toBe(false);
+  expect(await workerRecords(paseoHome)).toEqual([]);
+});
+
+// A worker launched on its own, as two daemons that each started one would leave it: running an
+// idle program in a terminal, with no daemon attached.
+async function launchDetachedWorkerWithTerminal(
+  paseoHome: string,
+  protocolVersion?: number,
+): Promise<{ terminalId: string; workerPid: number; cwd: string }> {
+  const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-detached-"));
+  temporaryDirs.push(cwd);
+  const previous = process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV];
+  if (protocolVersion !== undefined) {
+    process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV] = String(protocolVersion);
+  }
+  let launched: Awaited<ReturnType<typeof launchTerminalWorker>>;
+  try {
+    launched = await launchTerminalWorker({ paseoHome, paseoVersion: "0.0.0-test" });
+  } finally {
+    if (previous === undefined) delete process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV];
+    else process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV] = previous;
+  }
+  const worker = createWorkerTerminalManager({
+    worker: await connectTerminalWorker({
+      socketPath: launched.record.socketPath,
+      secret: launched.record.secret,
+    }),
+  });
+  const session = await worker.createTerminal({
+    workspaceId: "ws-detached",
+    cwd,
+    ...nodeTerminalCommand("setInterval(() => {}, 1000);"),
+  });
+  await worker.detach();
+  return { terminalId: session.id, workerPid: launched.record.pid, cwd };
+}
+
+// Worker pids alive in a home, from every record, closing ones included.
+async function liveWorkerPids(paseoHome: string): Promise<number[]> {
+  return (await listTerminalWorkerRecords(paseoHome))
+    .flatMap((file) => ("record" in file ? [file.record.pid] : []))
+    .filter(isProcessAlive)
+    .sort();
+}
+
+it.skipIf(isPlatform("win32"))(
+  "counts live workers whose cleanup could not be confirmed and never starts a third",
+  async () => {
+    const paseoHome = createTemporaryHome();
+    const first = await launchDetachedWorkerWithTerminal(paseoHome);
+    const second = await launchDetachedWorkerWithTerminal(paseoHome);
+    // A kill cleanup that cannot read the process table signals nothing: both workers keep
+    // running with their records marked closing.
+    const inspector = createTerminalWorkerProcessInspector();
+    await expect(
+      reapTerminalWorkers({
+        paseoHome,
+        gracefulMs: 0,
+        inspector: { ...inspector, listProcesses: () => Promise.reject(new Error("ps timed out")) },
+      }),
+    ).rejects.toBeInstanceOf(TerminalCleanupNotConfirmedError);
+    expect((await readUnconfirmedTerminalCleanup(paseoHome)).map((entry) => entry.role)).toContain(
+      "worker",
+    );
+
+    // The daemon's own retry fails the same way: only the full process table is unreadable.
+    const realPs = (process.env.PATH ?? "")
+      .split(delimiter)
+      .map((dir) => join(dir, "ps"))
+      .find((candidate) => existsSync(candidate));
+    if (!realPs) throw new Error("ps not found on PATH");
+    const shimDir = createTemporaryHome();
+    writeFileSync(
+      join(shimDir, "ps"),
+      `#!/bin/sh\nif [ "$1" = "-A" ]; then echo "process table unavailable" >&2; exit 1; fi\nexec ${realPs} "$@"\n`,
+      { mode: 0o755 },
+    );
+    const originalPath = process.env.PATH;
+    process.env.PATH = `${shimDir}${delimiter}${originalPath ?? ""}`;
+    try {
+      manager = await startRealWorkerManager({ paseoHome });
+    } finally {
+      process.env.PATH = originalPath;
+    }
+
+    expect(await liveWorkerPids(paseoHome)).toEqual([first.workerPid, second.workerPid].sort());
+    await expect(
+      manager.createTerminal({ workspaceId: "ws-detached", cwd: first.cwd }),
+    ).rejects.toThrow("2 terminal workers are already running");
+    expect(await liveWorkerPids(paseoHome)).toEqual([first.workerPid, second.workerPid].sort());
+  },
+);
+
+it("replays bounded ANSI chunks independently of live output and reconstructs the revision cut", async () => {
+  const cwd = createTemporaryHome();
+  const finishBefore = join(cwd, "finish-before");
+  manager = await startRealWorkerManager();
+  const session = trackTerminal(
+    await manager.createTerminal({
+      cwd,
+      workspaceId: "ws-replay",
+      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");
+        const finish = setInterval(() => {
+          if (!require("node:fs").existsSync(${JSON.stringify(finishBefore)})) return;
+          clearInterval(finish);
+          process.stdout.write("\\r\\n");
+        }, 5);
+      });
+      setInterval(() => {}, 1000);
+    `),
+    }),
+  );
+  await waitForCondition(
+    async () =>
+      (await manager!.captureTerminal(session.id)).lines.some((line) => line.startsWith("0799:")),
+    10000,
+  );
+  const events: string[] = [];
+  const replayEvents: string[] = [];
+  const liveOutputs: Array<{ data: string; revision?: number }> = [];
+  const chunks: Uint8Array[] = [];
+  let live = "";
+  const unsubscribe = session.subscribe((event) => {
+    if (event.type === "output") {
+      events.push("live");
+      liveOutputs.push(event);
+      live += event.data;
+    }
+  });
+  session.send({ type: "input", data: "before\r" });
+  await waitForCondition(() => live.includes("PRE-CUT"), 10000);
+  // A PTY may deliver the marker and its trailing newline separately. Finish
+  // that output before replay, so the two captures must describe the same cut.
+  writeFileSync(finishBefore, "");
+  await waitForCondition(async () => {
+    const { lines } = await manager!.captureTerminal(session.id);
+    return lines.at(-2) === "PRE-CUT" && lines.at(-1) === "";
+  }, 10000);
+  const expected = await manager.captureTerminal(session.id);
+  const metadata = await manager.replayTerminal(session.id, undefined, (event) => {
+    events.push(event.type);
+    replayEvents.push(event.type);
+    if (event.type === "begin") session.send({ type: "input", data: "go\r" });
+    if (event.type === "data") chunks.push(event.data);
+  });
+  await waitForCondition(() => live.includes("LIVE-AFTER-REPLAY"), 10000);
+  unsubscribe();
+  // Existing live observers are independent of replay. Pre-cut output may also be
+  // flushed by capture before begin; only the replay events have begin/data/end order.
+  expect(events[0]).toBe("live");
+  expect(replayEvents[0]).toBe("begin");
+  expect(replayEvents.at(-1)).toBe("end");
+  expect(replayEvents.slice(1, -1)).toEqual(chunks.map(() => "data"));
+  const beforeCut = liveOutputs.filter((output) => output.data.includes("PRE-CUT"));
+  const afterCut = liveOutputs.filter((output) => output.data.includes("LIVE-AFTER-REPLAY"));
+  expect(beforeCut).toHaveLength(1);
+  expect(afterCut).toHaveLength(1);
+  expect(beforeCut[0]!.revision).toBeDefined();
+  expect(beforeCut[0]!.revision).toBeLessThanOrEqual(metadata!.revision);
+  expect(afterCut[0]!.revision).toBeGreaterThan(metadata!.revision);
+  expect(live.match(/LIVE-AFTER-REPLAY/g)).toHaveLength(1);
+  expect(chunks.length).toBeGreaterThan(1);
+  expect(chunks.every((chunk) => chunk.byteLength <= 64 * 1024)).toBe(true);
+  expect(metadata?.rows).toBe(8);
+  expect(metadata?.cols).toBe(120);
+  const terminal = new xterm.Terminal({
+    rows: 8,
+    cols: 120,
+    scrollback: 1000,
+    allowProposedApi: true,
+  });
+  try {
+    await new Promise<void>((resolve) => terminal.write(Buffer.concat(chunks), resolve));
+    const buffer = terminal.buffer.active;
+    expect(
+      Array.from({ length: buffer.length }, (_, i) => buffer.getLine(i)!.translateToString(true)),
+    ).toEqual(expected.lines);
+    expect(expected.lines.filter((line) => line.includes("PRE-CUT"))).toHaveLength(1);
+    expect(expected.lines.some((line) => line.includes("LIVE-AFTER-REPLAY"))).toBe(false);
+    expect(buffer.getLine(0)!.getCell(0)!.getFgColor()).toBe(1);
+  } finally {
+    terminal.dispose();
+  }
+});
+
+it("completes a replay larger than the socket budget while a sibling stays usable", async () => {
+  const paseoHome = createTemporaryHome();
+  const overflowProgress = join(paseoHome, "overflow-progress");
+  manager = await startRealWorkerManager({ paseoHome });
+  const terminal = trackTerminal(
+    await manager.createTerminal({
+      cwd: paseoHome,
+      workspaceId: "ws-wide",
+      rows: 4,
+      cols: 1024,
+      ...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");
+      // 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);
+    `),
+    }),
+  );
+  const siblingProgress = join(paseoHome, "sibling-progress");
+  const sibling = trackTerminal(
+    await manager.createTerminal({
+      cwd: paseoHome,
+      workspaceId: "ws-wide",
+      ...nodeTerminalCommand(`
+        let count = 0;
+        process.stdin.on("data", () => {
+          count++;
+          process.stdout.write((count > 1 ? "z".repeat(1024 * 1024) : "") + "SIBLING-ALIVE\\r\\n", () => require("node:fs").writeFileSync(${JSON.stringify(siblingProgress)}, String(count)));
+        });
+        setInterval(() => {}, 1000);
+      `),
+    }),
+  );
+  await waitForCondition(
+    async () =>
+      (await manager!.captureTerminal(terminal.id)).lines.some((line) =>
+        line.includes("READY-WIDE"),
+      ),
+    20000,
+  );
+  const seen: string[] = [];
+  const unsubscribe = sibling.subscribe((event) => {
+    if (event.type === "output") seen.push(event.data);
+  });
+  let bytes = 0;
+  const metadata = await manager.replayTerminal(terminal.id, undefined, (event) => {
+    if (event.type === "data") bytes += event.data.byteLength;
+    if (event.type === "begin") {
+      sibling.send({ type: "input", data: "go\r" });
+    }
+  });
+  expect(bytes).toBeGreaterThan(4 * 1024 * 1024);
+  expect(metadata?.cols).toBe(1024);
+  await waitForCondition(() => seen.join("").includes("SIBLING-ALIVE"), 10000);
+  unsubscribe();
+  expect(manager.getTerminal(sibling.id)).toBe(sibling);
+  const truncated = await manager.replayTerminal(terminal.id, { scrollbackLines: 200 }, () => {});
+  expect(metadata!.retainedHistoryLines).toBeGreaterThan(200);
+  expect(truncated!.retainedHistoryLines).toBe(metadata!.retainedHistoryLines);
+  const concurrent = await Promise.all(
+    [0, 1].map(() => manager!.replayTerminal(terminal.id, { scrollbackLines: 200 }, () => {})),
+  );
+  expect(concurrent.map((replay) => replay!.retainedHistoryLines)).toEqual([
+    metadata!.retainedHistoryLines,
+    metadata!.retainedHistoryLines,
+  ]);
+  await manager.detach();
+  const [record] = await workerRecords(paseoHome);
+  const socket = createConnection(record!.socketPath);
+  let began = false;
+  let ended = false;
+  let completed = false;
+  let resumedBytes = 0;
+  let cancelledReplayBegan = false;
+  let existingLiveOutput = "";
+  const replayOrder: string[] = [];
+  const framed = attachFramedSocket(socket, (value) => {
+    const message = value as TerminalWorkerToParentMessage | { type: "helloAck" };
+    if (
+      message.type === "terminalMessage" &&
+      message.terminalId === terminal.id &&
+      message.message.type === "output"
+    ) {
+      existingLiveOutput += message.message.data;
+      replayOrder.push("live");
+    }
+    if (message.type === "helloAck") {
+      framed.send({ type: "replayTerminal", terminalId: terminal.id, requestId: "stalled-replay" });
+    } else if (message.type === "terminalReplay") {
+      if (message.requestId === "cancelled-replay") {
+        if (message.event.type === "begin") {
+          cancelledReplayBegan = true;
+          socket.pause();
+        }
+        return;
+      }
+      if (message.event.type === "begin") {
+        began = true;
+        socket.pause();
+      }
+      if (message.event.type === "data") resumedBytes += message.event.data.byteLength;
+      if (message.event.type === "end") {
+        ended = true;
+        replayOrder.push("end");
+      }
+    } else if (message.type === "response" && message.requestId === "stalled-replay")
+      completed = message.ok;
+  });
+  try {
+    framed.send({ type: "hello", secret: record!.secret, protocolVersion: 5 });
+    await waitForCondition(() => began, 10000);
+    framed.send({
+      type: "send",
+      terminalId: terminal.id,
+      requestId: "same-terminal-input",
+      message: { type: "input", data: "small\r" },
+    });
+    framed.send({
+      type: "send",
+      terminalId: sibling.id,
+      requestId: "sibling-input",
+      message: { type: "input", data: "again\r" },
+    });
+    await waitForCondition(
+      () => existsSync(siblingProgress) && readFileSync(siblingProgress, "utf8") === "2",
+      10000,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    expect(completed).toBe(false);
+    expect(socket.destroyed).toBe(false);
+    socket.resume();
+    await waitForCondition(() => completed, 10000);
+    expect(ended).toBe(true);
+    expect(resumedBytes).toBe(bytes);
+    await waitForCondition(() => existingLiveOutput.includes("SAME-TERMINAL-LIVE"), 10000);
+    expect(existingLiveOutput.match(/SAME-TERMINAL-LIVE/g)).toHaveLength(1);
+    expect(replayOrder.indexOf("live")).toBeLessThan(replayOrder.indexOf("end"));
+    framed.send({ type: "replayTerminal", terminalId: terminal.id, requestId: "cancelled-replay" });
+    await waitForCondition(() => cancelledReplayBegan, 10000);
+    // Replace a controller while its large replay is socket-paced. The original
+    // request must never leak frames or completion onto the replacement connection.
+    manager = await startRealWorkerManager({ paseoHome });
+    socket.resume();
+    await waitForCondition(() => socket.destroyed, 10000);
+    expect((await readReplay(manager, terminal.id))?.state.cols).toBe(1024);
+  } finally {
+    socket.destroy();
+  }
+  expect(
+    (await manager!.captureTerminal(terminal.id)).lines.some((line) => line.includes("READY-WIDE")),
+  ).toBe(true);
+  const exitingReplay = await manager.replayTerminal(
+    terminal.id,
+    { scrollbackLines: 200 },
+    (event) => {
+      if (event.type === "begin") manager!.killTerminal(terminal.id);
+    },
+  );
+  expect(exitingReplay!.cols).toBe(1024);
+  await waitForCondition(() => manager!.getTerminal(terminal.id) === undefined, 10000);
+  expect(manager.getTerminal(sibling.id)?.id).toBe(sibling.id);
+}, 60000);
+
+function terminalViewers(
+  terminalManager: DaemonTerminalManager,
+  terminalId: string,
+  chunked = true,
+  getClientBufferedAmount?: (source: object) => number | null,
+) {
+  const frames: Array<{ source: object; frame: TerminalStreamFrame }> = [];
+  const messages: Array<{ source: object; message: SessionOutboundMessage }> = [];
+  let blockedSource: object | null = null;
+  let started = false;
+  let finish!: (error?: Error) => void;
+  const block = new Promise<void>((resolve, reject) => {
+    finish = (error) => (error ? reject(error) : resolve());
+  });
+  const delivery = new SessionDelivery(
+    (source, message) => {
+      messages.push({ source, message });
+    },
+    async (source, bytes) => {
+      const frame = decodeTerminalStreamFrame(bytes)!;
+      frames.push({ source, frame });
+      if (
+        source === blockedSource &&
+        frame.opcode === (chunked ? TerminalStreamOpcode.ReplayBegin : TerminalStreamOpcode.Restore)
+      ) {
+        started = true;
+        await block;
+      }
+    },
+  );
+  const controller = new TerminalSessionController({
+    terminalManager,
+    emit: (message) => {
+      delivery.reply(message);
+    },
+    hasBinaryChannel: () => true,
+    supportsChunkedReplay: () => chunked,
+    getClientBufferedAmount,
+    isPathWithinRoot: () => true,
+    sessionLogger: pino({ level: "silent" }),
+  });
+  return {
+    frames,
+    messages,
+    delivery,
+    controller,
+    block(source: object) {
+      blockedSource = source;
+    },
+    started: () => started,
+    finish,
+    async attach(
+      source: object,
+      requestId: string,
+      restore: NonNullable<SubscribeTerminalRequest["restore"]> = {
+        mode: "visible-snapshot",
+        scrollbackLines: 1000,
+      },
+    ) {
+      delivery.attach(source, true);
+      const request = {
+        type: "subscribe_terminal_request" as const,
+        terminalId,
+        requestId,
+        restore,
+      };
+      await delivery.request(source, request, () => controller.dispatch(request, delivery));
+    },
+    text(source: object) {
+      return frames
+        .filter((row) => row.source === source && row.frame.opcode === TerminalStreamOpcode.Output)
+        .map((row) => Buffer.from(row.frame.payload).toString("utf8"))
+        .join("");
+    },
+    ended(source: object) {
+      return messages.filter(
+        (row) => row.source === source && row.message.type === "terminal_stream_exit",
+      );
+    },
+    replayed(source: object) {
+      return frames.some(
+        (row) => row.source === source && row.frame.opcode === TerminalStreamOpcode.ReplayEnd,
+      );
+    },
+  };
+}
+
+it("isolates a failed app transport while another viewer of the same terminal stays live", async () => {
+  manager = await startRealWorkerManager();
+  const session = trackTerminal(
+    await manager.createTerminal({
+      cwd: createTemporaryHome(),
+      workspaceId: "two-viewers",
+      ...nodeTerminalCommand(
+        'process.stdout.write("READY\\r\\n"); process.stdin.on("data", data => process.stdout.write("ECHO:" + data)); setInterval(() => {}, 1000);',
+      ),
+    }),
+  );
+  await waitForCondition(
+    async () =>
+      (await manager!.captureTerminal(session.id)).lines.some((line) => line.includes("READY")),
+    10000,
+  );
+  const viewers = terminalViewers(manager, session.id);
+  const desktop = {},
+    phone = {},
+    fresh = {};
+  try {
+    await viewers.attach(desktop, "desktop");
+    await waitForCondition(() => viewers.replayed(desktop), 10000);
+    await expect(
+      manager.replayTerminal(session.id, undefined, () => {
+        throw new Error("Consumer cancelled replay");
+      }),
+    ).rejects.toThrow("Consumer cancelled replay");
+    viewers.block(phone);
+    await viewers.attach(phone, "phone");
+    await waitForCondition(viewers.started, 10000);
+    session.send({ type: "input", data: "BEFORE-FAILURE\r" });
+    await waitForCondition(() => viewers.text(desktop).includes("ECHO:BEFORE-FAILURE"), 1500);
+    expect(viewers.ended(desktop)).toHaveLength(0);
+    expect(viewers.ended(phone)).toHaveLength(0);
+    viewers.finish(new Error("Phone socket closed"));
+    await viewers.delivery.detach(phone);
+    expect(viewers.ended(desktop)).toHaveLength(0);
+    session.send({ type: "input", data: "AFTER-FAILURE\r" });
+    await waitForCondition(() => viewers.text(desktop).includes("ECHO:AFTER-FAILURE"), 10000);
+    expect(viewers.ended(desktop)).toHaveLength(0);
+    await viewers.attach(fresh, "fresh");
+    await waitForCondition(() => viewers.replayed(fresh), 10000);
+    expect(manager.getTerminal(session.id)).toBe(session);
+  } finally {
+    viewers.finish();
+    await viewers.delivery.close();
+  }
+}, 20000);
+
+it("keeps concurrent viewer replays and live output ordered behind slow app delivery", async () => {
+  manager = await startRealWorkerManager();
+  const session = trackTerminal(
+    await manager.createTerminal({
+      cwd: createTemporaryHome(),
+      workspaceId: "concurrent-delivery",
+      ...nodeTerminalCommand(
+        'process.stdout.write("READY\\r\\n"); process.stdin.on("data", data => process.stdout.write("ECHO:" + data)); setInterval(() => {}, 1000);',
+      ),
+    }),
+  );
+  await waitForCondition(
+    async () => (await manager!.captureTerminal(session.id)).lines.join("").includes("READY"),
+    10000,
+  );
+  const viewers = terminalViewers(manager, session.id);
+  const desktop = {},
+    phone = {},
+    concurrent = {};
+  try {
+    await viewers.attach(desktop, "desktop");
+    await waitForCondition(() => viewers.replayed(desktop), 10000);
+    viewers.block(phone);
+    await viewers.attach(phone, "phone");
+    await waitForCondition(viewers.started, 10000);
+    await viewers.attach(concurrent, "concurrent");
+    await waitForCondition(() => viewers.replayed(concurrent) && viewers.replayed(phone), 10000);
+    session.send({ type: "input", data: "DURING-DELIVERY\r" });
+    await waitForCondition(
+      () =>
+        viewers.text(phone).includes("ECHO:DURING-DELIVERY") &&
+        viewers.text(desktop).includes("ECHO:DURING-DELIVERY"),
+      3000,
+    );
+    expect(viewers.text(phone).match(/ECHO:DURING-DELIVERY/g)).toHaveLength(1);
+    const order = viewers.frames
+      .filter((row) => row.source === phone)
+      .map((row) => row.frame.opcode);
+    expect(order.indexOf(TerminalStreamOpcode.Output)).toBeGreaterThan(
+      order.indexOf(TerminalStreamOpcode.ReplayEnd),
+    );
+    expect(viewers.ended(phone)).toHaveLength(0);
+    expect(viewers.ended(desktop)).toHaveLength(0);
+  } finally {
+    viewers.finish();
+    await viewers.delivery.close();
+  }
+}, 20000);
+
+it.each([true, false])(
+  "queues replay independently of app delivery past the worker deadline (chunked=%s)",
+  async (chunked) => {
+    const paseoHome = createTemporaryHome();
+    // Slow program identification belongs to setup, not the replay request deadline.
+    // The POSIX shim deterministically exceeds 800 ms; Windows keeps its real OS path.
+    manager = isPlatform("win32")
+      ? await startRealWorkerManager({ paseoHome })
+      : await startWorkerWithSlowProcessTable(1, { paseoHome });
+    const created = await manager.createTerminal({
+      cwd: paseoHome,
+      workspaceId: "slow-delivery",
+      ...nodeTerminalCommand(
+        'process.stdout.write("READY\\r\\n"); process.stdin.on("data", data => process.stdout.write("ECHO:" + data)); setInterval(() => {}, 1000);',
+      ),
+    });
+    await waitForCondition(
+      async () => (await manager!.captureTerminal(created.id)).lines.join("").includes("READY"),
+      10000,
+    );
+    await manager.detach();
+    manager = await startRealWorkerManager({ paseoHome, requestTimeoutMs: 800 });
+    const session = manager.getTerminal(created.id);
+    if (!session) throw new Error("Replay fixture did not adopt its prepared terminal");
+    trackTerminal(session);
+    const viewers = terminalViewers(manager, session.id, chunked);
+    const phone = {};
+    viewers.block(phone);
+    try {
+      await viewers.attach(phone, "slow-phone");
+      await waitForCondition(viewers.started, 10000);
+      await new Promise((resolve) => setTimeout(resolve, 1100));
+      expect(viewers.ended(phone)).toHaveLength(0);
+      expect((await manager.captureTerminal(session.id)).lines.join("")).toContain("READY");
+      session.send({ type: "input", data: "AFTER-DEADLINE\r" });
+      await waitForCondition(() => viewers.text(phone).includes("ECHO:AFTER-DEADLINE"), 3000);
+    } finally {
+      viewers.finish();
+      await viewers.delivery.close();
+    }
+  },
+  20000,
+);
+
+it.each(["replacement", "socket-overflow"] as const)(
+  "recovers an attached restore viewer after worker %s",
+  async (loss) => {
+    const paseoHome = createTemporaryHome();
+    const drained = join(paseoHome, "burst-drained");
+    manager = await startRealWorkerManager({ paseoHome });
+    const session = trackTerminal(
+      await manager.createTerminal({
+        cwd: paseoHome,
+        workspaceId: "attached-reconnect",
+        ...nodeTerminalCommand(
+          `process.stdout.write("RETAINED\\r\\n"); process.stdin.on("data", data => {
+            if (data.toString().includes("BURST")) process.stdout.write("x".repeat(12 * 1024 * 1024) + "\\r\\nRETAINED-AFTER-LOSS\\r\\n", () => require("node:fs").writeFileSync(${JSON.stringify(drained)}, "done"));
+            else process.stdout.write("ECHO:" + data);
+          }); setInterval(() => {}, 1000);`,
+        ),
+      }),
+    );
+    await waitForCondition(
+      async () => (await manager!.captureTerminal(session.id)).lines.join("").includes("RETAINED"),
+      10000,
+    );
+    const viewers = terminalViewers(manager, session.id);
+    const desktop = {};
+    try {
+      await viewers.attach(desktop, "desktop");
+      await waitForCondition(() => viewers.replayed(desktop), 10000);
+      viewers.frames.length = 0;
+      const [record] = await workerRecords(paseoHome);
+      if (loss === "replacement") {
+        const competitor = await connectTerminalWorker({
+          socketPath: record!.socketPath,
+          secret: record!.secret,
+        });
+        await waitForCondition(() => !competitor.connected, 10000);
+      } else {
+        session.send({ type: "input", data: "BURST\r" });
+        // Stall only the daemon event loop. The detached worker and PTY keep running,
+        // filling the bounded worker socket and forcing its disconnect/re-adoption path.
+        const stall = new Int32Array(new SharedArrayBuffer(4));
+        const deadline = Date.now() + 10000;
+        while (!existsSync(drained) && Date.now() < deadline) Atomics.wait(stall, 0, 0, 25);
+        expect(existsSync(drained)).toBe(true);
+      }
+      await waitForCondition(() => viewers.replayed(desktop), 10000);
+      const replay = viewers.frames
+        .filter((row) => row.frame.opcode === TerminalStreamOpcode.ReplayData)
+        .map((row) => Buffer.from(row.frame.payload).toString("utf8"))
+        .join("");
+      expect(replay).toContain("RETAINED");
+      if (loss === "socket-overflow") expect(replay).toContain("RETAINED-AFTER-LOSS");
+      expect((await workerRecords(paseoHome)).map((worker) => worker.pid)).toEqual([record!.pid]);
+      session.send({ type: "input", data: "RECOVERED\r" });
+      await waitForCondition(() => viewers.text(desktop).includes("ECHO:RECOVERED"), 3000);
+      expect(viewers.ended(desktop)).toHaveLength(0);
+      expect(manager.getTerminal(session.id)).toBe(session);
+    } finally {
+      await viewers.delivery.close();
+    }
+  },
+  30000,
+);
+
+it.each([true, false])(
+  "keeps live modes after a replay captured enabled=%s while restoring its own modes first",
+  async (enabled) => {
+    const on = "\x1b[?1h\x1b[?2004h";
+    const off = "\x1b[?1l\x1b[?2004l";
+    const captured = enabled ? on : "";
+    const latest = enabled ? "" : on;
+    const live = (enabled ? off : on) + "MODE-LIVE";
+    const worker = new FakeTerminalWorker();
+    manager = createWorkerTerminalManager({ worker, requestTimeoutMs: 1000 });
+    worker.emitWorkerMessage({
+      type: "terminalCreated",
+      terminal: {
+        id: "mode-terminal",
+        name: "Terminal",
+        cwd: "/tmp",
+        workspaceId: "modes",
+        activity: null,
+      },
+      state: createTerminalState(),
+    });
+    worker.emitWorkerMessage({
+      type: "terminalMessage",
+      terminalId: "mode-terminal",
+      replayPreamble: captured,
+      message: { type: "snapshotReady", revision: 1 },
+    });
+    const session = manager.getTerminal("mode-terminal")!;
+    const viewers = terminalViewers(manager, session.id);
+    const restoring = {},
+      following = {};
+    try {
+      await viewers.attach(restoring, "restoring");
+      await waitForCondition(
+        () => worker.sentMessages.some((message) => message.type === "replayTerminal"),
+        1000,
+      );
+      const request = worker.sentMessages.find((message) => message.type === "replayTerminal")!;
+      const metadata = {
+        rows: 30,
+        cols: 120,
+        retainedHistoryLines: 10,
+        revision: 1,
+        replayPreamble: captured,
+      };
+      worker.emitWorkerMessage({
+        type: "terminalReplay",
+        requestId: request.requestId,
+        event: { type: "begin", metadata },
+      });
+      worker.emitWorkerMessage({
+        type: "terminalReplay",
+        requestId: request.requestId,
+        event: { type: "data", data: Buffer.from("CAPTURE-A") },
+      });
+      worker.emitWorkerMessage({
+        type: "terminalMessage",
+        terminalId: session.id,
+        replayPreamble: latest,
+        message: { type: "output", data: live, revision: 2 },
+      });
+      expect(session.getReplayPreamble()).toBe(latest);
+      worker.emitWorkerMessage({
+        type: "terminalReplay",
+        requestId: request.requestId,
+        event: { type: "data", data: Buffer.from("CAPTURE-B") },
+      });
+      worker.emitWorkerMessage({
+        type: "terminalReplay",
+        requestId: request.requestId,
+        event: { type: "end" },
+      });
+      worker.emitWorkerMessage({
+        type: "response",
+        requestId: request.requestId,
+        ok: true,
+        result: metadata,
+      });
+      await waitForCondition(() => viewers.text(restoring).includes("MODE-LIVE"), 1000);
+      expect(session.getReplayPreamble()).toBe(latest);
+      expect(viewers.text(restoring)).toBe(captured + live);
+      const sequence = viewers.frames
+        .filter((row) => row.source === restoring)
+        .map((row) => row.frame.opcode);
+      expect(sequence.indexOf(TerminalStreamOpcode.Output)).toBeGreaterThan(
+        sequence.indexOf(TerminalStreamOpcode.ReplayEnd),
+      );
+      const modes = new TerminalInputModeTracker();
+      modes.feed(session.getReplayPreamble());
+      expect(encodeTerminalKeyInput({ key: "ArrowUp" }, { inputMode: modes.getState() })).toBe(
+        enabled ? "\x1b[A" : "\x1bOA",
+      );
+      expect(modes.getState().bracketedPaste).toBe(!enabled);
+      await viewers.attach(following, "live-following", { mode: "live" });
+      await waitForCondition(() => latest === "" || viewers.text(following).length > 0, 1000);
+      expect(viewers.text(following)).toBe(latest);
+      expect(
+        worker.sentMessages.filter((message) => message.type === "replayTerminal"),
+      ).toHaveLength(1);
+    } finally {
+      await viewers.delivery.close();
+    }
+  },
+);
+
+it.each([3000, 12050])(
+  "retains ten thousand history rows and restores exact demands after %s printed rows",
+  async (count) => {
+    manager = await startRealWorkerManager();
+    const gate = createTemporaryHome();
+    const releaseNewline = join(gate, "newline");
+    const session = trackTerminal(
+      await manager.createTerminal({
+        cwd: createTemporaryHome(),
+        workspaceId: "ten-thousand",
+        rows: 4,
+        cols: 80,
+        ...nodeTerminalCommand(
+          `const fs=require("node:fs");
+          const watcher=fs.watch(${JSON.stringify(gate)},()=>{
+            if(fs.existsSync(${JSON.stringify(releaseNewline)})){
+              watcher.close();process.stdout.write("\\r\\nROWS-COMPLETE");
+            }
+          });
+          for(let i=0;i<${count};i++) process.stdout.write("\\x1b[31mrow-"+String(i).padStart(5,"0")+" 界é🙂\\x1b[0m"+(i===${count}-1?"":"\\r\\n"));
+          setInterval(()=>{},1000)`,
+        ),
+      }),
+    );
+    await waitForCondition(
+      async () =>
+        (await manager!.captureTerminal(session.id, { start: -5 })).lines
+          .join("")
+          .includes("row-" + String(count - 1).padStart(5, "0")),
+      15000,
+    );
+    // A visible final label can precede its trailing CRLF. Hold that transition
+    // deliberately, then observe content on the following row before capture.
+    writeFileSync(releaseNewline, "release");
+    await waitForCondition(
+      async () =>
+        (await manager!.captureTerminal(session.id, { start: -1 })).lines[0] === "ROWS-COMPLETE",
+      15000,
+    );
+    for (const history of [0, 200, 1000, 10000]) {
+      const chunks: Uint8Array[] = [];
+      const metadata = await manager.replayTerminal(
+        session.id,
+        { scrollbackLines: history },
+        (event) => {
+          if (event.type === "data") chunks.push(event.data);
+        },
+      );
+      expect(metadata).toMatchObject({
+        rows: 4,
+        cols: 80,
+        retainedHistoryLines: Math.min(10000, count - 3),
+      });
+      expect(chunks.every((chunk) => chunk.byteLength <= 64 * 1024)).toBe(true);
+      const restored = new xterm.Terminal({
+        rows: 4,
+        cols: 80,
+        scrollback: 10000,
+        allowProposedApi: true,
+      });
+      try {
+        await new Promise<void>((resolve) => restored.write(Buffer.concat(chunks), resolve));
+        const buffer = restored.buffer.active;
+        const labels = Array.from({ length: buffer.length }, (_, i) =>
+          buffer.getLine(i)!.translateToString(true),
+        ).filter((line) => line.includes("row-"));
+        expect({ row: buffer.cursorY, col: buffer.cursorX }).toEqual({ row: 3, col: 13 });
+        expect(buffer.getLine(buffer.length - 1)!.translateToString(true)).toBe("ROWS-COMPLETE");
+        expect(labels).toHaveLength(Math.min(count, history + 3));
+        expect(labels[0]).toContain("row-" + String(count - labels.length).padStart(5, "0"));
+        expect(labels.at(-1)).toContain("row-" + String(count - 1).padStart(5, "0") + " 界é🙂");
+      } finally {
+        restored.dispose();
+      }
+    }
+  },
+  30000,
+);
+
+it.each([false, true])(
+  "shrinks real ten-thousand-row pressure recovery and preserves reattach (chunked=%s)",
+  async (chunked) => {
+    manager = await startRealWorkerManager();
+    const session = trackTerminal(
+      await manager.createTerminal({
+        cwd: createTemporaryHome(),
+        workspaceId: "pressure-history",
+        rows: 4,
+        cols: 120,
+        ...nodeTerminalCommand(`
+      process.stdin.setRawMode(true);
+      let row = 0;
+      function print(count) {
+        for(let i=0;i<count;i++,row++) process.stdout.write("\\x1b[31mrow-" + String(row).padStart(5,"0") + " 界é🙂 " + "log ".repeat(20) + "\\x1b[0m\\r\\n");
+      }
+      print(12050);
+      process.stdout.write("READY\\r\\n");
+      process.stdin.on("data", data => {
+        if(data.toString().includes("BURST")) { print(4000); process.stdout.write("BURST-DONE\\r\\n"); }
+        else process.stdout.write("ECHO:" + data.toString() + "\\r\\n");
+      });
+      setInterval(()=>{},1000);
+    `),
+      }),
+    );
+    await waitForCondition(
+      async () =>
+        (await manager!.captureTerminal(session.id, { start: -5 })).lines
+          .join("")
+          .includes("READY"),
+      15000,
+    );
+    const desktop = {},
+      phone = {},
+      fresh = {};
+    let pressure = false;
+    const viewers = terminalViewers(manager, session.id, chunked, (source) =>
+      source === phone && pressure ? 8 * 1024 * 1024 : 0,
+    );
+    const restore = { mode: "full-snapshot" as const, scrollbackLines: 10000 };
+    function payloads(source: object): Buffer[] {
+      const result: Buffer[] = [];
+      let chunks: Uint8Array[] = [];
+      for (const { source: owner, frame } of viewers.frames) {
+        if (owner !== source) continue;
+        if (frame.opcode === TerminalStreamOpcode.Restore) result.push(Buffer.from(frame.payload));
+        if (frame.opcode === TerminalStreamOpcode.ReplayBegin) chunks = [];
+        if (frame.opcode === TerminalStreamOpcode.ReplayData) chunks.push(frame.payload);
+        if (frame.opcode === TerminalStreamOpcode.ReplayEnd) result.push(Buffer.concat(chunks));
+      }
+      return result;
+    }
+    async function parse(payload: Uint8Array) {
+      const receiver = new xterm.Terminal({
+        rows: 4,
+        cols: 120,
+        scrollback: 10000,
+        allowProposedApi: true,
+      });
+      try {
+        await new Promise<void>((resolve) => receiver.write(payload, resolve));
+        const buffer = receiver.buffer.active;
+        return {
+          history: buffer.baseY,
+          text: Array.from({ length: buffer.length }, (_, i) =>
+            buffer.getLine(i)!.translateToString(true),
+          ).join("\n"),
+        };
+      } finally {
+        receiver.dispose();
+      }
+    }
+    try {
+      await viewers.attach(desktop, "healthy", restore);
+      await viewers.attach(phone, "pressured", restore);
+      await waitForCondition(
+        () => payloads(phone).length === 1 && payloads(desktop).length === 1,
+        15000,
+      );
+      const initial = payloads(phone)[0]!;
+      expect((await parse(initial)).history).toBe(10000);
+      pressure = true;
+      session.send({ type: "input", data: "BURST" });
+      await waitForCondition(() => payloads(phone).length >= 2, 15000);
+      pressure = false;
+      // The final burst marker may belong to the replay cut or to its live tail.
+      // Read the same replay/output exchange a renderer sees rather than assuming
+      // worker parsing and daemon request scheduling cut the burst at one point.
+      async function currentView(source: object) {
+        const frames = viewers.frames
+          .filter((row) => row.source === source)
+          .map((row) => row.frame);
+        const start = frames.findLastIndex(
+          (frame) =>
+            frame.opcode === TerminalStreamOpcode.Restore ||
+            frame.opcode === TerminalStreamOpcode.ReplayBegin,
+        );
+        return parse(
+          Buffer.concat(
+            frames
+              .slice(start)
+              .filter(
+                (frame) =>
+                  frame.opcode === TerminalStreamOpcode.Restore ||
+                  frame.opcode === TerminalStreamOpcode.ReplayData ||
+                  frame.opcode === TerminalStreamOpcode.Output,
+              )
+              .map((frame) => frame.payload),
+          ),
+        );
+      }
+      await waitForCondition(
+        async () =>
+          (await currentView(phone)).text.includes("BURST-DONE") &&
+          (await currentView(desktop)).text.includes("BURST-DONE"),
+        15000,
+      );
+      const recovery = payloads(phone)[1]!;
+      const recovered = await parse(recovery);
+      expect(recovered.history).toBe(500);
+      expect(recovered.text).toContain("界é🙂");
+      for (const source of [phone, desktop]) {
+        const indexes = [...(await currentView(source)).text.matchAll(/row-(\d+)/g)].map((match) =>
+          Number(match[1]),
+        );
+        expect(indexes.at(-1)).toBe(16049);
+        expect(indexes).toEqual(Array.from({ length: indexes.length }, (_, i) => indexes[0]! + i));
+      }
+      expect(recovery.byteLength).toBeLessThan(initial.byteLength / 10);
+      expect(recovery.byteLength).toBeLessThan(256 * 1024);
+      expect(payloads(desktop)).toHaveLength(1); // The healthy peer keeps its full replay and live stream.
+      session.send({ type: "input", data: "AFTER-CATCH-UP" });
+      await waitForCondition(
+        () =>
+          viewers.text(phone).includes("ECHO:AFTER-CATCH-UP") &&
+          viewers.text(desktop).includes("ECHO:AFTER-CATCH-UP"),
+        10000,
+      );
+      expect(viewers.text(phone).match(/ECHO:AFTER-CATCH-UP/g)).toHaveLength(1);
+      expect(viewers.text(desktop).match(/ECHO:AFTER-CATCH-UP/g)).toHaveLength(1);
+      await viewers.delivery.detach(phone);
+      await viewers.attach(fresh, "reattach", restore);
+      await waitForCondition(() => payloads(fresh).length === 1, 15000);
+      const reattached = await parse(payloads(fresh)[0]!);
+      expect(reattached.history).toBe(10000);
+      expect(reattached.text).toContain("row-16049");
+      expect(reattached.text).toContain("ECHO:AFTER-CATCH-UP");
+      expect(viewers.ended(desktop)).toHaveLength(0);
+      expect(viewers.ended(phone)).toHaveLength(0);
+      process.stdout.write(
+        JSON.stringify({
+          chunked,
+          initialBytes: initial.byteLength,
+          recoveryBytes: recovery.byteLength,
+          reattachBytes: payloads(fresh)[0]!.byteLength,
+          retainedHistory: reattached.history,
+          recoveryHistory: recovered.history,
+        }) + "\n",
+      );
+    } finally {
+      await viewers.delivery.close();
+    }
+  },
+  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 0a1adb2c44..2592b0c89c 100644
--- a/packages/server/src/terminal/worker-terminal-manager.ts
+++ b/packages/server/src/terminal/worker-terminal-manager.ts
@@ -1,8 +1,12 @@
-import { fileURLToPath } from "node:url";
-import { fork } from "node:child_process";
+import type { TerminalReplaySink, TerminalReplayMetadata } from "./terminal-replay.js";
 import { randomBytes, randomUUID } from "node:crypto";
+import { access } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import type { Logger } from "pino";
+import { createExternalProcessEnv } from "../server/paseo-env.js";
 import { assertAbsolutePath, isSameOrDescendantPath } from "../server/path-utils.js";
-import type { TerminalState } from "@getpaseo/protocol/messages";
+import { writtenDuringThisBoot } from "../server/pid-lock.js";
+import type { WorkerTerminalState } from "./terminal-worker-protocol.js";
 import type { TerminalActivity, TerminalActivityState } from "@getpaseo/protocol/terminal-activity";
 import { deriveTerminalActivityStatusBucket } from "@getpaseo/protocol/terminal-activity";
 import type {
@@ -12,9 +16,26 @@ import type {
   TerminalCommandFinishedInfo,
   TerminalExitInfo,
   TerminalSession,
-  TerminalStateSnapshot,
 } from "./terminal.js";
+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 { identifyTerminalWorker } from "./terminal-worker-ownership.js";
+import { createTerminalWorkerProcessInspector } from "./terminal-worker-processes.js";
+import { reapTerminalWorkers } from "./terminal-worker-reaper.js";
+import {
+  listTerminalWorkerRecords,
+  terminalWorkerRecordPath,
+  type TerminalWorkerRecord,
+} from "./terminal-worker-record.js";
+import {
+  createTerminalWorkerPool,
+  NoTerminalWorkerAvailableError,
+  TerminalWorkerIncompatibleError,
+  type TerminalWorkerPoolMember,
+} from "./terminal-worker-pool.js";
+import { pruneTerminalWorkerRuntimes } from "./terminal-worker-runtime.js";
 import type {
   TerminalActivityListener,
   TerminalActivityTransitionEvent,
@@ -25,12 +46,16 @@ import type {
   TerminalsChangedEvent,
   TerminalsChangedListener,
 } from "./terminal-manager.js";
+import {
+  classifyTerminalWorkerProtocol,
+  type TerminalWorkerProtocolFit,
+} from "./terminal-worker-protocol.js";
 import type {
+  TerminalWorkerListResult,
   TerminalWorkerRequest,
   TerminalWorkerResponse,
   TerminalWorkerToParentMessage,
   WorkerCreateTerminalOptions,
-  TerminalWorkerStateResult,
   WorkerTerminalInfo,
 } from "./terminal-worker-protocol.js";
 
@@ -64,7 +89,7 @@ interface PendingRequest {
 
 interface WorkerTerminalRecord {
   info: RequiredWorkerTerminalInfo;
-  state: TerminalState;
+  state: WorkerTerminalState;
   activity: TerminalActivity | null;
   // Cached input-mode preamble from the worker (the authoritative tracker lives
   // in the worker process). Updated with streamed output and snapshot responses.
@@ -78,49 +103,45 @@ interface WorkerTerminalRecord {
   session: TerminalSession;
 }
 
-interface TerminalWorkerProcess {
-  connected: boolean;
-  killed: boolean;
-  send(message: TerminalWorkerRequest, callback: (error: Error | null) => void): boolean;
-  disconnect(): void;
-  kill(): boolean;
-  on(event: "message", listener: (message: TerminalWorkerToParentMessage) => void): this;
-  on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+export interface TerminalCreateEnvironment {
+  baseEnv: Record<string, string>;
+  paseoCliPath: string | null;
 }
 
 interface WorkerTerminalManagerOptions {
+  worker: TerminalWorkerConnection;
+  /** Reconnects a surviving worker; null means it is confirmed gone or the owner stopped. */
+  reconnect?: () => Promise<TerminalWorkerConnection | null>;
   requestTimeoutMs?: number;
-  forkWorker?: () => TerminalWorkerProcess;
   getTerminalActivityUrl?: () => string | null;
+  resolveCreateEnvironment?: () => TerminalCreateEnvironment;
+  // The kill path. The daemon passes the reaper, which verifies every program is gone; the
+  // default asks the connected worker to shut down.
+  closeTerminals?: () => Promise<void>;
+}
+
+/** The daemon's terminal manager: its terminals live in a worker that can outlive it. */
+export interface DaemonTerminalManager extends TerminalManager {
+  /** Registers every terminal the connected worker already runs. Resolves with their count. */
+  adoptTerminals(): Promise<number>;
+  /** Kills every terminal and verifies their programs ended. */
+  closeTerminals(): Promise<void>;
+  /**
+   * Lets go of the worker; its terminals keep running for the next daemon. With
+   * `afterPendingRequests`, requests already sent get their answers first.
+   */
+  detach(options?: { afterPendingRequests?: boolean }): Promise<void>;
 }
 
 function createActivityToken(): string {
   return randomBytes(32).toString("base64url");
 }
 
-function resolveWorkerUrl(): URL {
-  const currentUrl = import.meta.url;
-  if (currentUrl.endsWith(".ts")) {
-    return new URL("./terminal-worker-process.ts", currentUrl);
-  }
-  return new URL("./terminal-worker-process.js", currentUrl);
-}
-
-function resolveWorkerExecArgv(): string[] {
-  if (!import.meta.url.endsWith(".ts")) {
-    return [];
-  }
-  const loaderUrl = new URL("./terminal-ts-loader.mjs", import.meta.url).href;
-  const importSource = [
-    'import { register } from "node:module";',
-    'import { pathToFileURL } from "node:url";',
-    `register(${JSON.stringify(loaderUrl)}, pathToFileURL("./"));`,
-  ].join(" ");
-  return [
-    "--experimental-strip-types",
-    "--import",
-    `data:text/javascript,${encodeURIComponent(importSource)}`,
-  ];
+function resolveDaemonTerminalCreateEnvironment(): TerminalCreateEnvironment {
+  return {
+    baseEnv: createExternalProcessEnv(process.env),
+    paseoCliPath: resolvePaseoCliExecutablePath(),
+  };
 }
 
 function isResponse(message: TerminalWorkerToParentMessage): message is TerminalWorkerResponse {
@@ -138,20 +159,18 @@ function cloneTerminalInfo(info: RequiredWorkerTerminalInfo): RequiredWorkerTerm
   };
 }
 
-function forkTerminalWorker(): TerminalWorkerProcess {
-  return fork(fileURLToPath(resolveWorkerUrl()), [], {
-    execArgv: resolveWorkerExecArgv(),
-    serialization: "advanced",
-    stdio: ["ignore", "ignore", "inherit", "ipc"],
-  }) as TerminalWorkerProcess;
-}
-
 export function createWorkerTerminalManager(
-  managerOptions: WorkerTerminalManagerOptions = {},
-): TerminalManager {
-  const worker = managerOptions.forkWorker ? managerOptions.forkWorker() : forkTerminalWorker();
+  managerOptions: WorkerTerminalManagerOptions,
+): DaemonTerminalManager {
+  let worker = managerOptions.worker;
+  let detached = false;
+  let reconnecting: Promise<void> | null = null;
   const requestTimeoutMs = managerOptions.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
+  const resolveCreateEnvironment =
+    managerOptions.resolveCreateEnvironment ?? resolveDaemonTerminalCreateEnvironment;
+  const replaySinks = new Map<string, TerminalReplaySink>();
   const pendingRequests = new Map<string, PendingRequest>();
+  const inFlight = new Set<Promise<void>>();
   const recordsById = new Map<string, WorkerTerminalRecord>();
   const terminalIdsByCwd = new Map<string, Set<string>>();
   const terminalActivityTokenById = new Map<string, string>();
@@ -162,8 +181,8 @@ export function createWorkerTerminalManager(
   const terminalActivityListeners = new Set<TerminalActivityListener>();
   const terminalWorkspaceContributionChangedListeners =
     new Set<TerminalWorkspaceContributionChangedListener>();
-  let workerExited = false;
-  let workerShutdownTimer: ReturnType<typeof setTimeout> | null = null;
+  let workerDisconnected = false;
+  let closePromise: Promise<void> | null = null;
 
   function emitTerminalsChanged(event: TerminalsChangedEvent): void {
     for (const listener of Array.from(terminalsChangedListeners)) {
@@ -222,7 +241,7 @@ export function createWorkerTerminalManager(
 
   function registerRecord(input: {
     info: RequiredWorkerTerminalInfo;
-    state: TerminalState;
+    state: WorkerTerminalState;
   }): TerminalSession {
     const existing = recordsById.get(input.info.id);
     if (existing) {
@@ -268,18 +287,11 @@ export function createWorkerTerminalManager(
         }
         sendBestEffortRequest({ type: "send", terminalId: record.info.id, message });
       },
-      subscribe(
-        listener: (msg: ServerMessage) => void,
-        options?: { initialSnapshot?: "state" | "ready" },
-      ): () => void {
+      subscribe(listener: (msg: ServerMessage) => void): () => void {
         record.messageListeners.add(listener);
-        if (options?.initialSnapshot === "ready") {
-          queueMicrotask(() => {
-            if (record.messageListeners.has(listener)) {
-              listener({ type: "snapshotReady", revision: 0 });
-            }
-          });
-        }
+        queueMicrotask(() => {
+          if (record.messageListeners.has(listener)) listener({ type: "snapshotReady" });
+        });
         return () => {
           record.messageListeners.delete(listener);
         };
@@ -340,19 +352,8 @@ export function createWorkerTerminalManager(
           cols: record.state.cols,
         };
       },
-      getState(): TerminalState {
-        return record.state;
-      },
-      getStateSnapshot(options?: { scrollbackLines?: number }): TerminalStateSnapshot {
-        const scrollbackLines = options?.scrollbackLines;
-        const scrollback =
-          typeof scrollbackLines === "number"
-            ? record.state.scrollback.slice(-scrollbackLines)
-            : record.state.scrollback;
-        return {
-          state: { ...record.state, scrollback },
-          revision: 0,
-        };
+      hasOutput(): boolean {
+        return record.state.hasOutput;
       },
       getReplayPreamble(): string {
         return record.replayPreamble;
@@ -420,9 +421,7 @@ export function createWorkerTerminalManager(
     if (!record) {
       return;
     }
-    if (message.message.type === "snapshot") {
-      record.state = message.message.state;
-    }
+    if (message.message.type === "output") record.state.hasOutput = true;
     record.replayPreamble = message.replayPreamble;
     for (const listener of Array.from(record.messageListeners)) {
       listener(message.message);
@@ -587,46 +586,106 @@ export function createWorkerTerminalManager(
     }
   }
 
-  worker.on("message", (message: TerminalWorkerToParentMessage) => {
-    if (isResponse(message)) {
-      const pending = pendingRequests.get(message.requestId);
-      if (!pending) {
+  function attachWorker(): void {
+    const connection = worker;
+    connection.on("message", (message: TerminalWorkerToParentMessage) => {
+      if (message.type === "terminalReplay") {
+        // Consumption queues into the application's bounded transport synchronously.
+        // Never wait for app network delivery or accumulate a second replay queue here.
+        if (worker !== connection || !pendingRequests.has(message.requestId)) return;
+        try {
+          replaySinks.get(message.requestId)?.(message.event);
+        } catch (error) {
+          const pending = pendingRequests.get(message.requestId)!;
+          clearTimeout(pending.timeout);
+          pendingRequests.delete(message.requestId);
+          replaySinks.delete(message.requestId);
+          pending.reject(error instanceof Error ? error : new Error(String(error)));
+        }
         return;
       }
-      clearTimeout(pending.timeout);
-      pendingRequests.delete(message.requestId);
-      if (message.ok) {
-        pending.resolve(message.result);
-      } else {
-        pending.reject(new Error(message.error));
+      if (isResponse(message)) {
+        const pending = pendingRequests.get(message.requestId);
+        if (!pending) {
+          return;
+        }
+        clearTimeout(pending.timeout);
+        pendingRequests.delete(message.requestId);
+        if (message.ok) {
+          pending.resolve(message.result);
+        } else {
+          pending.reject(new Error(message.error));
+        }
+        return;
       }
-      return;
-    }
-    handleWorkerEvent(message);
-  });
+      handleWorkerEvent(message);
+    });
 
-  worker.on("exit", (code, signal) => {
-    workerExited = true;
-    if (workerShutdownTimer) {
-      clearTimeout(workerShutdownTimer);
-      workerShutdownTimer = null;
-    }
-    rejectPendingRequests(new Error(`Terminal worker exited (${signal ?? code ?? "unknown"})`));
-  });
+    connection.on("close", () => {
+      if (worker !== connection) return;
+      workerDisconnected = true;
+      rejectPendingRequests(new Error("Terminal worker connection closed"));
+      const reconnect = managerOptions.reconnect;
+      if (!detached && reconnect) {
+        reconnecting = (async () => {
+          const recovered = await reconnect();
+          if (!recovered) {
+            for (const terminalId of Array.from(recordsById.keys())) {
+              handleTerminalExitEvent({
+                type: "terminalExit",
+                terminalId,
+                info: { exitCode: null, signal: null, lastOutputLines: [] },
+              });
+            }
+            return;
+          }
+          if (detached) {
+            recovered.disconnect();
+            return;
+          }
+          worker = recovered;
+          workerDisconnected = false;
+          attachWorker();
+          await adoptTerminals();
+          // Output emitted without a controller is retained in the worker's screen. Existing
+          // streams must fetch that screen before applying further live output.
+          for (const record of recordsById.values()) {
+            handleTerminalMessageEvent({
+              type: "terminalMessage",
+              terminalId: record.info.id,
+              message: { type: "snapshotReady" },
+              replayPreamble: record.replayPreamble,
+            });
+          }
+        })().finally(() => {
+          reconnecting = null;
+        });
+        void reconnecting.catch(() => {});
+      }
+    });
+  }
+  attachWorker();
 
-  function sendRequest(input: TerminalWorkerRequestInput): Promise<unknown> {
-    if (workerExited || !worker.connected) {
+  function sendRequest(
+    input: TerminalWorkerRequestInput,
+    sink?: TerminalReplaySink,
+  ): Promise<unknown> {
+    if (reconnecting && workerDisconnected)
+      return reconnecting.then(() => sendRequest(input, sink));
+    if (workerDisconnected || !worker.connected) {
       return Promise.reject(new Error("Terminal worker is not running"));
     }
+    const connection = worker;
     const requestId = randomUUID();
+    if (sink) replaySinks.set(requestId, sink);
     const message = { ...input, requestId } as TerminalWorkerRequest;
-    return new Promise((resolve, reject) => {
+    const request = new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
         pendingRequests.delete(requestId);
         reject(new Error(`Terminal worker request timed out: ${input.type}`));
       }, requestTimeoutMs);
       pendingRequests.set(requestId, { resolve, reject, timeout });
-      worker.send(message, (error) => {
+      connection.send(message, (error) => {
         if (!error) {
           return;
         }
@@ -635,6 +694,17 @@ export function createWorkerTerminalManager(
         reject(error);
       });
     });
+    // Tracks settlement only; the caller handles the rejection.
+    const settled = request.then(
+      () => undefined,
+      () => undefined,
+    );
+    inFlight.add(settled);
+    void settled.finally(() => {
+      inFlight.delete(settled);
+      replaySinks.delete(requestId);
+    });
+    return request;
   }
 
   function sendBestEffortRequest(input: TerminalWorkerRequestInput): void {
@@ -645,6 +715,71 @@ export function createWorkerTerminalManager(
     });
   }
 
+  function clearRecords(): void {
+    for (const terminalId of Array.from(recordsById.keys())) {
+      removeRecord(terminalId);
+    }
+  }
+
+  function disconnectWorker(): Promise<void> {
+    if (workerDisconnected || !worker.connected) {
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      worker.on("close", () => resolve());
+      worker.disconnect();
+    });
+  }
+
+  function closeTerminals(): Promise<void> {
+    detached = true;
+    closePromise ??= (async () => {
+      await reconnecting;
+      if (managerOptions.closeTerminals) {
+        await disconnectWorker();
+        clearRecords();
+        await managerOptions.closeTerminals();
+        return;
+      }
+      // Unverified: production passes the reaper, which confirms every program ended.
+      sendBestEffortRequest({ type: "shutdown" });
+      await disconnectWorker();
+      clearRecords();
+    })();
+    return closePromise;
+  }
+
+  async function adoptTerminals(): Promise<number> {
+    const listed = (await sendRequest({ type: "listTerminals" })) as TerminalWorkerListResult;
+    const cwds = new Set<string>();
+    const liveIds = new Set(listed.map((item) => item.terminal.id));
+    for (const terminalId of Array.from(recordsById.keys())) {
+      if (!liveIds.has(terminalId))
+        handleTerminalExitEvent({
+          type: "terminalExit",
+          terminalId,
+          info: { exitCode: null, signal: null, lastOutputLines: [] },
+        });
+    }
+    for (const item of listed) {
+      const info = asRequiredWorkerTerminalInfo(item.terminal);
+      registerRecord({ info, state: item.state });
+      const record = recordsById.get(info.id);
+      if (record) {
+        record.replayPreamble = item.replayPreamble;
+      }
+      // The agent hooks inside each shell keep the token they were started with.
+      if (item.activityToken) {
+        terminalActivityTokenById.set(info.id, item.activityToken);
+      }
+      cwds.add(info.cwd);
+    }
+    for (const cwd of cwds) {
+      emitTerminalsChanged({ cwd, terminals: listTerminalItemsForCwd(cwd) });
+    }
+    return listed.length;
+  }
+
   return {
     async getTerminals(
       cwd: string,
@@ -688,6 +823,7 @@ export function createWorkerTerminalManager(
       const creation = { session: null as TerminalSession | null };
       pendingCreationsById.set(terminalId, creation);
       try {
+        const environment = resolveCreateEnvironment();
         await sendRequest({
           type: "createTerminal",
           options: {
@@ -695,6 +831,8 @@ export function createWorkerTerminalManager(
             id: terminalId,
             activityToken,
             activityUrl: terminalActivityUrl,
+            baseEnv: environment.baseEnv,
+            paseoCliPath: environment.paseoCliPath,
           },
         });
         if (!creation.session) {
@@ -732,22 +870,12 @@ export function createWorkerTerminalManager(
       return recordsById.get(id)?.session;
     },
 
-    async getTerminalState(
-      id: string,
-      options?: { scrollbackLines?: number },
-    ): Promise<TerminalStateSnapshot | null> {
-      const snapshot = (await sendRequest({
-        type: "getTerminalState",
-        terminalId: id,
-        ...(options ? { options } : {}),
-      })) as TerminalWorkerStateResult;
-      if (snapshot && snapshot.replayPreamble !== undefined) {
-        const record = recordsById.get(id);
-        if (record) {
-          record.replayPreamble = snapshot.replayPreamble;
-        }
-      }
-      return snapshot;
+    async replayTerminal(id, options, sink): Promise<TerminalReplayMetadata | null> {
+      const metadata = (await sendRequest(
+        { type: "replayTerminal", terminalId: id, options },
+        sink,
+      )) as TerminalReplayMetadata | null;
+      return metadata;
     },
 
     setTerminalTitle(id: string, title: string): boolean {
@@ -812,25 +940,25 @@ export function createWorkerTerminalManager(
     },
 
     killAll(): void {
-      void sendRequest({ type: "killAll" })
-        .catch(() => {
-          // no-op
-        })
-        .finally(() => {
-          if (worker.connected) {
-            worker.disconnect();
-          }
-          if (!worker.killed && !workerShutdownTimer) {
-            workerShutdownTimer = setTimeout(() => {
-              worker.kill();
-            }, 1000);
-          }
-        });
-      for (const terminalId of Array.from(recordsById.keys())) {
-        removeRecord(terminalId);
-      }
+      void closeTerminals().catch(() => {
+        // The synchronous interface cannot report it; closeTerminals() callers see the error.
+      });
     },
 
+    closeTerminals,
+
+    async detach(options?: { afterPendingRequests?: boolean }): Promise<void> {
+      detached = true;
+      await reconnecting;
+      if (options?.afterPendingRequests) {
+        await Promise.allSettled(Array.from(inFlight));
+      }
+      await disconnectWorker();
+      clearRecords();
+    },
+
+    adoptTerminals,
+
     subscribeTerminalsChanged(listener: TerminalsChangedListener): () => void {
       terminalsChangedListeners.add(listener);
       return () => {
@@ -856,6 +984,349 @@ export function createWorkerTerminalManager(
   };
 }
 
-export function terminateWorkerTerminalManager(manager: TerminalManager): void {
-  manager.killAll();
+export interface StartWorkerTerminalManagerOptions {
+  paseoHome: string;
+  paseoVersion: string;
+  logger: Logger;
+  getTerminalActivityUrl?: () => string | null;
+  requestTimeoutMs?: number;
+}
+
+// The current worker plus one draining a previous protocol. Every live worker counts,
+// incompatible, unreachable, unidentified and closing ones included: the daemon never starts a
+// third.
+const MAX_TERMINAL_WORKERS = 2;
+const DRAINED_WORKER_EXIT_TIMEOUT_MS = 10_000;
+
+interface LiveWorkerRecord {
+  path: string;
+  record: TerminalWorkerRecord;
+  fit: TerminalWorkerProtocolFit;
+}
+
+/**
+ * Connects the daemon to its terminal workers. A worker of this daemon's protocol is adopted
+ * (restart, crash, `stop --keep-terminals`); one a protocol older is adopted to drain; anything
+ * older is shut down, its terminals closed; one from a newer Paseo is left running and the
+ * terminal service reports it as incompatible. A worker is launched only when none is current,
+ * none is incompatible and fewer than two run; when two run, the first terminal created after one
+ * of them exits launches it. Records that cannot be adopted (a cleanup that
+ * never finished, a dead worker whose programs survived it) go through the reaper first, so a
+ * daemon never adopts terminals someone asked to close.
+ */
+export async function startWorkerTerminalManager(
+  options: StartWorkerTerminalManagerOptions,
+): Promise<DaemonTerminalManager> {
+  const logger = options.logger.child({ module: "terminal-worker" });
+  const inspector = createTerminalWorkerProcessInspector();
+  const log = (message: string, fields?: Record<string, unknown>) => logger.info(fields, message);
+  const live: LiveWorkerRecord[] = [];
+  const toReap: string[] = [];
+  for (const file of await listTerminalWorkerRecords(options.paseoHome)) {
+    if ("error" in file) {
+      logger.warn({ recordPath: file.path, err: file.error }, "Unreadable terminal worker record");
+      continue;
+    }
+    const { record } = file;
+    if (
+      record.closing ||
+      !writtenDuringThisBoot({ startedAt: record.createdAt, bootId: record.bootId })
+    ) {
+      toReap.push(file.path);
+      continue;
+    }
+    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 {
+      // Its programs lost their PTY with the worker and cannot be adopted.
+      toReap.push(file.path);
+    }
+  }
+
+  if (toReap.length > 0) {
+    await reapTerminalWorkers({
+      paseoHome: options.paseoHome,
+      gracefulMs: 0,
+      recordPaths: toReap,
+      inspector,
+      log,
+    }).catch((error: unknown) => {
+      logger.warn({ err: error }, "Terminal cleanup of an unadoptable worker was not confirmed");
+    });
+  }
+
+  const obsolete = live.filter((entry) => entry.fit === "obsolete");
+  if (obsolete.length > 0) {
+    for (const entry of obsolete) {
+      logger.warn(
+        {
+          pid: entry.record.pid,
+          protocolVersion: entry.record.protocolVersion,
+          paseoVersion: entry.record.paseoVersion,
+          terminals: entry.record.terminals.length,
+        },
+        "Closing a terminal worker two or more protocol versions old; its terminals close",
+      );
+    }
+    await reapTerminalWorkers({
+      paseoHome: options.paseoHome,
+      recordPaths: obsolete.map((entry) => entry.path),
+      inspector,
+      log,
+    }).catch((error: unknown) => {
+      logger.warn({ err: error }, "Closing an obsolete terminal worker was not confirmed");
+    });
+  }
+
+  const closeAll = async () => {
+    const result = await reapTerminalWorkers({ paseoHome: options.paseoHome, inspector, log });
+    logger.info(result, "Terminals closed");
+  };
+  const prune = async () => {
+    const result = await pruneTerminalWorkerRuntimes(options.paseoHome);
+    if (result.removed.length > 0)
+      log("Removed terminal worker copies", { removed: result.removed });
+    for (const failure of result.failed) {
+      logger.warn(failure, "Cannot remove a terminal worker copy; the next start retries");
+    }
+  };
+
+  const pruneAfterExit = async (workerPid: number) => {
+    if (await waitForWorkerRecordRemoval(options.paseoHome, workerPid)) {
+      await prune();
+      return;
+    }
+    logger.warn({ pid: workerPid }, "Drained terminal worker has not exited yet");
+  };
+
+  const newer = live.find((entry) => entry.fit === "newer");
+  if (newer) {
+    const incompatible = new TerminalWorkerIncompatibleError({
+      paseoVersion: newer.record.paseoVersion,
+      protocolVersion: newer.record.protocolVersion,
+    });
+    logger.error({ pid: newer.record.pid }, incompatible.message);
+    await prune();
+    return createTerminalWorkerPool({
+      current: null,
+      draining: [],
+      incompatible,
+      closeAll,
+    });
+  }
+
+  const createMember = async (
+    record: TerminalWorkerRecord,
+    connection: TerminalWorkerConnection,
+  ): Promise<TerminalWorkerPoolMember> => {
+    let alive = true;
+    let resolveExit!: () => void;
+    const exited = new Promise<void>((resolve) => {
+      resolveExit = resolve;
+    });
+    let recovery: Promise<TerminalWorkerConnection | null> | null = null;
+    const recoveryState = { stopped: false };
+    const reconnect = () => {
+      recovery ??= (async () => {
+        while (!recoveryState.stopped) {
+          const ownership = await identifyTerminalWorker(record);
+          if (ownership.status === "gone" || ownership.status === "unrelated") {
+            await reapTerminalWorkers({
+              paseoHome: options.paseoHome,
+              recordPaths: [terminalWorkerRecordPath(options.paseoHome, record.pid)],
+              inspector,
+              log,
+              gracefulMs: 0,
+            }).catch((error) =>
+              logger.warn({ err: error }, "Dead terminal worker cleanup was not confirmed"),
+            );
+            alive = false;
+            resolveExit();
+            return null;
+          }
+          try {
+            return await connectTerminalWorker({
+              socketPath: record.socketPath,
+              secret: record.secret,
+              timeoutMs: 500,
+            });
+          } catch {
+            await delay(100);
+          }
+        }
+        return null;
+      })().finally(() => {
+        recovery = null;
+      });
+      return recovery;
+    };
+    const manager = createWorkerTerminalManager({
+      worker: connection,
+      reconnect,
+      ...(options.requestTimeoutMs === undefined
+        ? {}
+        : { requestTimeoutMs: options.requestTimeoutMs }),
+      ...(options.getTerminalActivityUrl
+        ? { getTerminalActivityUrl: options.getTerminalActivityUrl }
+        : {}),
+      closeTerminals: closeAll,
+    });
+    const count = await manager.adoptTerminals();
+    if (count > 0) {
+      logger.info({ pid: record.pid, terminals: count }, "Adopted terminals from a running worker");
+    }
+    return {
+      manager,
+      workerPid: record.pid,
+      exited,
+      ready: async () => {
+        await recovery;
+        return alive && !recoveryState.stopped;
+      },
+      stopRecovery: () => {
+        recoveryState.stopped = true;
+      },
+    };
+  };
+
+  let current: TerminalWorkerPoolMember | null = null;
+  const draining: TerminalWorkerPoolMember[] = [];
+  const adoptable = [
+    ...live.filter((entry) => entry.fit === "current"),
+    ...live.filter((entry) => entry.fit === "previous"),
+  ];
+  for (const entry of adoptable) {
+    let connection: TerminalWorkerConnection;
+    try {
+      connection = await connectTerminalWorker({
+        socketPath: entry.record.socketPath,
+        secret: entry.record.secret,
+      });
+    } catch (error) {
+      logger.warn(
+        { pid: entry.record.pid, err: error },
+        "Cannot reach terminal worker; leaving it running",
+      );
+      continue;
+    }
+    const member = await createMember(entry.record, connection);
+    if (entry.fit === "current" && !current) {
+      logger.info({ pid: entry.record.pid }, "Adopting running terminal worker");
+      current = member;
+    } else {
+      // A previous protocol, or a second worker of this one: it keeps its terminals and takes
+      // no new ones.
+      logger.info(
+        { pid: entry.record.pid, protocolVersion: entry.record.protocolVersion },
+        "Draining terminal worker; it exits after its last terminal",
+      );
+      draining.push(member);
+    }
+  }
+
+  // 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);
+    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`,
+      );
+    }
+    const launched = await launchTerminalWorker({
+      paseoHome: options.paseoHome,
+      paseoVersion: options.paseoVersion,
+    });
+    const connection = await connectTerminalWorker({
+      socketPath: launched.record.socketPath,
+      secret: launched.record.secret,
+    });
+    logger.info(
+      { pid: launched.record.pid, runtime: launched.record.runtime ?? null },
+      "Launched terminal worker",
+    );
+    return createMember(launched.record, connection);
+  };
+
+  await prune();
+  if (!current) {
+    try {
+      current = await startCurrent();
+    } catch (error) {
+      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",
+        );
+      }
+    }
+  }
+
+  return createTerminalWorkerPool({
+    current,
+    draining,
+    incompatible: null,
+    startCurrent,
+    closeAll,
+    onDrained: (member) => {
+      log("Released drained terminal worker", { pid: member.workerPid });
+      void pruneAfterExit(member.workerPid);
+    },
+  });
+}
+
+// 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 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) {
+      running += 1;
+      continue;
+    }
+    const { record } = file;
+    if (!writtenDuringThisBoot({ startedAt: record.createdAt, bootId: record.bootId })) continue;
+    const worker = await identifyTerminalWorker(record);
+    if (worker.status === "owned" || worker.status === "unknown") running += 1;
+  }
+  return running;
+}
+
+// A worker deletes its own record as it exits.
+async function waitForWorkerRecordRemoval(paseoHome: string, workerPid: number): Promise<boolean> {
+  const recordPath = terminalWorkerRecordPath(paseoHome, workerPid);
+  const deadline = Date.now() + DRAINED_WORKER_EXIT_TIMEOUT_MS;
+  while (
+    await access(recordPath).then(
+      () => true,
+      (error: NodeJS.ErrnoException) => {
+        if (error.code === "ENOENT") return false;
+        throw error;
+      },
+    )
+  ) {
+    if (Date.now() >= deadline) return false;
+    await delay(100);
+  }
+  return true;
 }
diff --git a/packages/server/src/test-utils/main-thread-work.ts b/packages/server/src/test-utils/main-thread-work.ts
new file mode 100644
index 0000000000..66bb55e491
--- /dev/null
+++ b/packages/server/src/test-utils/main-thread-work.ts
@@ -0,0 +1,108 @@
+import { createHook, executionAsyncResource } from "node:async_hooks";
+import { performance, PerformanceObserver, type PerformanceEntry } from "node:perf_hooks";
+import { MessagePort } from "node:worker_threads";
+
+/** Measure main-thread work without charging idle IO or runner descheduling. */
+export async function measureMainThreadWork<T>(label: string, action: () => T | Promise<T>) {
+  // Node 22.20 supplies this API; the repository's older declarations omit it.
+  const threadCpuUsage: (previous?: NodeJS.CpuUsage) => NodeJS.CpuUsage = Reflect.get(
+    process,
+    "threadCpuUsage",
+  );
+  let blockingMs = 0;
+  let filesystemRequests = 0;
+  let yields = 0;
+  let longestCallbackMs = 0;
+  let longestCallbackCpuMs = 0;
+  let longestGapMs = 0;
+  let longestGcMs = 0;
+  let gcCount = 0;
+  let workerEvents = 0;
+  let draining = false;
+  const startedAt = performance.now();
+  let previous = startedAt;
+  let previousCpu = threadCpuUsage();
+  let probe: ReturnType<typeof setInterval>;
+  let drain: ReturnType<typeof setImmediate>;
+  const callbacks = new Map<number, { wall: number; cpu: NodeJS.CpuUsage }>();
+  const record = (wallMs: number, cpu: NodeJS.CpuUsage) => {
+    const cpuMs = (cpu.user + cpu.system) / 1_000;
+    // Windows CPU accounting is coarse. Cap charged CPU by the real span so a
+    // counter increment cannot inflate a short callback. Zero-CPU waits drop out.
+    blockingMs = Math.max(blockingMs, Math.min(wallMs, cpuMs));
+    if (wallMs > longestCallbackMs) {
+      longestCallbackMs = wallMs;
+      longestCallbackCpuMs = cpuMs;
+    }
+  };
+  const observeGc = (entries: readonly PerformanceEntry[]) => {
+    for (const entry of entries) {
+      if (entry.startTime < startedAt) continue;
+      gcCount++;
+      longestGcMs = Math.max(longestGcMs, entry.duration);
+    }
+  };
+  const gc = new PerformanceObserver((list) => observeGc(list.getEntries()));
+  gc.observe({ entryTypes: ["gc"] });
+  const activity = createHook({
+    init(_id, type) {
+      if (type.startsWith("FSREQ")) filesystemRequests++;
+      if (!draining && type === "Immediate") yields++;
+      if (type === "WORKER") workerEvents++;
+    },
+    before(id) {
+      const resource = executionAsyncResource();
+      if (resource === probe || resource === drain) return;
+      if (resource instanceof MessagePort) workerEvents++;
+      callbacks.set(id, { wall: performance.now(), cpu: threadCpuUsage() });
+    },
+    after(id) {
+      const start = callbacks.get(id);
+      if (!start) return;
+      callbacks.delete(id);
+      record(performance.now() - start.wall, threadCpuUsage(start.cpu));
+    },
+  }).enable();
+  const sample = () => {
+    const now = performance.now();
+    const cpu = threadCpuUsage();
+    const wallMs = now - previous;
+    longestGapMs = Math.max(longestGapMs, wallMs);
+    // Worker construction/message cloning can precede async_hooks.before.
+    if (workerEvents) {
+      blockingMs = Math.max(
+        blockingMs,
+        Math.min(wallMs, (cpu.user - previousCpu.user + cpu.system - previousCpu.system) / 1_000),
+      );
+    }
+    workerEvents = 0;
+    previous = now;
+    previousCpu = cpu;
+  };
+  probe = setInterval(sample, 1);
+  let result: T;
+  try {
+    // The caller's current callback began before the hook was installed.
+    const wall = performance.now();
+    const cpu = threadCpuUsage();
+    const pending = action();
+    record(performance.now() - wall, threadCpuUsage(cpu));
+    result = await pending;
+    draining = true;
+    await new Promise<void>((resolve) => {
+      drain = setImmediate(resolve);
+    });
+    sample();
+    observeGc(gc.takeRecords());
+  } finally {
+    clearInterval(probe);
+    activity.disable();
+    gc.disconnect();
+  }
+  // GC CPU inside callbacks is charged above. Elapsed GC spans, like elapsed
+  // callback spans, include preemption and remain diagnostics rather than gates.
+  process.stderr.write(
+    `${label}: ${JSON.stringify({ blockingMs, filesystemRequests, yields, longestCallbackMs, longestCallbackCpuMs, longestGcMs, gcCount, longestGapMs })}\n`,
+  );
+  return { result, blockingMs, filesystemRequests, yields };
+}
diff --git a/packages/server/src/utils/build-metadata-prompt.ts b/packages/server/src/utils/build-metadata-prompt.ts
index 9f4f008308..b68f660515 100644
--- a/packages/server/src/utils/build-metadata-prompt.ts
+++ b/packages/server/src/utils/build-metadata-prompt.ts
@@ -1,8 +1,5 @@
-import { readPaseoConfigJson } from "./paseo-config-file.js";
-import {
-  PaseoConfigSchema,
-  type PaseoMetadataGeneration,
-} from "@getpaseo/protocol/paseo-config-schema";
+import { readPaseoConfig } from "./paseo-config-file.js";
+import { type PaseoMetadataGeneration } from "@getpaseo/protocol/paseo-config-schema";
 
 export type MetadataConfigKey = "title" | "branchName" | "commitMessage" | "pullRequest";
 
@@ -52,8 +49,8 @@ async function readProjectMetadataOverrides(
   }
   try {
     const repoRoot = await options.workspaceGitService.resolveRepoRoot(options.cwd);
-    const json = readPaseoConfigJson(repoRoot);
-    return PaseoConfigSchema.parse(json).metadataGeneration;
+    const result = await readPaseoConfig(repoRoot);
+    return result.ok ? result.config?.metadataGeneration : undefined;
   } catch {
     return undefined;
   }
diff --git a/packages/server/src/utils/checkout-git.commit-file-diff.test.ts b/packages/server/src/utils/checkout-git.commit-file-diff.test.ts
index 576e9b0c80..efda5be92c 100644
--- a/packages/server/src/utils/checkout-git.commit-file-diff.test.ts
+++ b/packages/server/src/utils/checkout-git.commit-file-diff.test.ts
@@ -4,6 +4,7 @@ import { tmpdir } from "os";
 import { join } from "path";
 import { afterEach, describe, expect, it } from "vitest";
 import { getCommitFileDiff, listCheckoutCommits } from "./checkout-git.js";
+import { SessionDelivery } from "../server/session/owned-subscriptions/index.js";
 import { startGitCommandMetrics, stopGitCommandMetrics } from "./run-git-command.js";
 
 const tempDirs: string[] = [];
@@ -302,3 +303,44 @@ describe("getCommitFileDiff", () => {
     expect(file?.deletions).toBe(0);
   });
 });
+
+it("identical commit-file requests from two requesters both retain syntax tokens", async () => {
+  const repoDir = initRepo();
+  const original = "const value = Math.max(42, 7);\n".repeat(3_000);
+  commitFile(repoDir, "file.ts", original, "initial");
+  commitFile(repoDir, "file.ts", original.replace("42", "43"), "edit");
+  const input = { cwd: repoDir, sha: headSha(repoDir), path: "file.ts" };
+  const results = await Promise.all([getCommitFileDiff(input), getCommitFileDiff(input)]);
+  for (const file of results) {
+    expect(
+      file?.hunks[0].lines
+        .find((line) => line.type === "add")
+        ?.tokens?.some((token) => token.style !== null),
+    ).toBe(true);
+  }
+});
+
+it("a disconnected requester cancels commit highlighting before its sources arrive", async () => {
+  const repoDir = initRepo();
+  commitFile(repoDir, "file.ts", "const value = 42;\n", "initial");
+  commitFile(repoDir, "file.ts", "const value = 43;\n", "edit");
+  const delivery = new SessionDelivery(() => {});
+  const source = {};
+  delivery.attach(source, true);
+  const request = {
+    type: "checkout.commits.file_diff.request" as const,
+    cwd: repoDir,
+    sha: headSha(repoDir),
+    path: "file.ts",
+    requestId: "disconnect",
+  };
+  const results: Awaited<ReturnType<typeof getCommitFileDiff>>[] = [];
+  const pending = delivery.request(source, request, async () => {
+    results.push(await getCommitFileDiff({ ...request, signal: delivery.requestSignal }));
+  });
+  await delivery.detach(source);
+  await pending;
+  expect(
+    results[0]?.hunks.flatMap((hunk) => hunk.lines).every((line) => line.tokens === undefined),
+  ).toBe(true);
+});
diff --git a/packages/server/src/utils/checkout-git.commits.test.ts b/packages/server/src/utils/checkout-git.commits.test.ts
index d614e32f9b..7baac91c23 100644
--- a/packages/server/src/utils/checkout-git.commits.test.ts
+++ b/packages/server/src/utils/checkout-git.commits.test.ts
@@ -3,7 +3,7 @@ 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 } from "./checkout-git.js";
 import { writePaseoWorktreeMetadata } from "./worktree-metadata.js";
 
 const tempDirs: string[] = [];
@@ -172,7 +172,7 @@ describe("listCheckoutCommits", () => {
     mkdirSync(join(worktreesRoot, "repo-hash"), { recursive: true });
     git(["worktree", "add", "-b", "feature", worktreeDir], repoDir);
     commitFile(worktreeDir, "feature.txt", "feature\n", "Feature work");
-    writePaseoWorktreeMetadata(worktreeDir, { baseRefName: "deleted-base" });
+    await writePaseoWorktreeMetadata(worktreeDir, { baseRefName: "deleted-base" });
 
     const { baseRef, commits } = await listCheckoutCommits({
       cwd: worktreeDir,
@@ -332,6 +332,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);
diff --git a/packages/server/src/utils/checkout-git.test.ts b/packages/server/src/utils/checkout-git.test.ts
index 3cc5c3dace..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",
@@ -2859,7 +2917,7 @@ const x = 1;
       execFileSync("git", ["worktree", "add", workspaceDir, "contributor/old-change"], {
         cwd: repoDir,
       });
-      writePaseoWorktreeMetadata(workspaceDir, {
+      await writePaseoWorktreeMetadata(workspaceDir, {
         baseRefName: "main",
         changeRequestLookupTarget: {
           headRef: "old-change",
@@ -2899,7 +2957,7 @@ const x = 1;
     const workspaceDir = join(paseoHome, "worktrees", "repo", "renamed-by-agent");
     mkdirSync(join(paseoHome, "worktrees", "repo"), { recursive: true });
     execFileSync("git", ["worktree", "add", workspaceDir, "placeholder"], { cwd: repoDir });
-    writePaseoWorktreeMetadata(workspaceDir, {
+    await writePaseoWorktreeMetadata(workspaceDir, {
       baseRefName: "main",
       changeRequestLookupTarget: {
         headRef: "placeholder",
@@ -2936,7 +2994,7 @@ const x = 1;
     const workspaceDir = join(paseoHome, "worktrees", "repo", "pinned-worktree");
     mkdirSync(join(paseoHome, "worktrees", "repo"), { recursive: true });
     execFileSync("git", ["worktree", "add", workspaceDir, "feature/pinned"], { cwd: repoDir });
-    writePaseoWorktreeMetadata(workspaceDir, {
+    await writePaseoWorktreeMetadata(workspaceDir, {
       baseRefName: "main",
       changeRequestLookupTarget: {
         headRef: "feature/pinned",
@@ -2975,7 +3033,7 @@ const x = 1;
     execFileSync("git", ["worktree", "add", workspaceDir, "contributor/old-change-1"], {
       cwd: repoDir,
     });
-    writePaseoWorktreeMetadata(workspaceDir, {
+    await writePaseoWorktreeMetadata(workspaceDir, {
       baseRefName: "main",
       changeRequestLookupTarget: {
         headRef: "old-change",
@@ -2997,7 +3055,7 @@ const x = 1;
     execFileSync("git", ["worktree", "add", workspaceDir, "contributor/old-change"], {
       cwd: repoDir,
     });
-    writePaseoWorktreeMetadata(workspaceDir, {
+    await writePaseoWorktreeMetadata(workspaceDir, {
       baseRefName: "main",
       changeRequestLookupTarget: {
         headRef: "old-change",
@@ -3062,7 +3120,7 @@ const x = 1;
     execFileSync("git", ["worktree", "add", workspaceDir, "mixedowner/old-change"], {
       cwd: repoDir,
     });
-    writePaseoWorktreeMetadata(workspaceDir, {
+    await writePaseoWorktreeMetadata(workspaceDir, {
       baseRefName: "main",
       changeRequestLookupTarget: {
         headRef: "old-change",
@@ -3114,7 +3172,7 @@ const x = 1;
     execFileSync("git", ["worktree", "add", workspaceDir, "feature/gitlab-mr"], {
       cwd: repoDir,
     });
-    writePaseoWorktreeMetadata(workspaceDir, {
+    await writePaseoWorktreeMetadata(workspaceDir, {
       baseRefName: "main",
       changeRequestLookupTarget: {
         headRef: "feature/gitlab-mr",
@@ -3128,7 +3186,9 @@ const x = 1;
     const forge = createGitHubServiceRecordingPullRequestTargets({ requestedTargets });
 
     await renameCurrentBranch(workspaceCwd, "feature/renamed");
-    expect(readPaseoWorktreeMetadata(workspaceDir)?.changeRequestLookupTarget).toMatchObject({
+    expect(
+      (await readPaseoWorktreeMetadata(workspaceDir))?.changeRequestLookupTarget,
+    ).toMatchObject({
       localBranchName: "feature/renamed",
     });
     const renamedFacts = await getCheckoutSnapshotFacts(workspaceDir, { paseoHome });
@@ -3164,7 +3224,7 @@ const x = 1;
     execFileSync("git", ["worktree", "add", workspaceDir, "feature/placeholder"], {
       cwd: repoDir,
     });
-    writePaseoWorktreeMetadata(workspaceDir, {
+    await writePaseoWorktreeMetadata(workspaceDir, {
       baseRefName: "main",
       changeRequestLookupTarget: {
         headRef: "feature/placeholder",
@@ -3174,7 +3234,7 @@ const x = 1;
 
     await renameCurrentBranch(workspaceDir, "feature/generated");
 
-    expect(readPaseoWorktreeMetadata(workspaceDir)?.changeRequestLookupTarget).toEqual({
+    expect((await readPaseoWorktreeMetadata(workspaceDir))?.changeRequestLookupTarget).toEqual({
       headRef: "feature/generated",
       localBranchName: "feature/generated",
     });
@@ -3951,7 +4011,7 @@ const x = 1;
       cwd: worktree.worktreePath,
     });
 
-    const metadataPath = getPaseoWorktreeMetadataPath(worktree.worktreePath);
+    const metadataPath = await getPaseoWorktreeMetadataPath(worktree.worktreePath);
     rmSync(metadataPath, { force: true });
 
     const baseDiff = await getCheckoutDiff(worktree.worktreePath, { mode: "base" }, { paseoHome });
@@ -3970,7 +4030,7 @@ const x = 1;
       paseoHome,
     });
 
-    const metadataPath = getPaseoWorktreeMetadataPath(worktree.worktreePath);
+    const metadataPath = await getPaseoWorktreeMetadataPath(worktree.worktreePath);
     rmSync(metadataPath, { force: true });
 
     const status = await getCheckoutStatus(worktree.worktreePath, { paseoHome });
diff --git a/packages/server/src/utils/checkout-git.ts b/packages/server/src/utils/checkout-git.ts
index fbbb494b4a..d793e2c683 100644
--- a/packages/server/src/utils/checkout-git.ts
+++ b/packages/server/src/utils/checkout-git.ts
@@ -1,7 +1,15 @@
 import { MAX_RELAY_WEBSOCKET_MESSAGE_BYTES } from "@getpaseo/protocol/websocket-message-limit";
 import { resolve, dirname, basename } from "path";
-import { existsSync, realpathSync } from "fs";
-import { open as openFile, readFile, stat as statFile, mkdtemp, copyFile, rm } from "fs/promises";
+import {
+  open as openFile,
+  readFile,
+  stat as statFile,
+  mkdtemp,
+  copyFile,
+  realpath,
+  access,
+  rm,
+} from "fs/promises";
 import { tmpdir } from "node:os";
 import { setImmediate } from "node:timers/promises";
 import { TTLCache } from "@isaacs/ttlcache";
@@ -37,10 +45,13 @@ import { unquoteGitPath } from "./git-quoted-path.js";
 import { isPaseoOwnedWorktreeCwd, resolvePaseoWorktreesBaseRoot } from "./worktree.js";
 import {
   branchNameFromRef,
+  findPaseoWorktreeRootForCwd,
+  hasPaseoWorktreeMetadata,
   getPaseoWorktreeChangeRequestHintForBranch,
   type PaseoWorktreeMetadata,
   readPaseoWorktreeMetadata,
   rebindPaseoWorktreeChangeRequestHint,
+  setPaseoWorktreeBaseRef,
 } from "./worktree-metadata.js";
 const READ_ONLY_GIT_ENV = {
   GIT_OPTIONAL_LOCKS: "0",
@@ -313,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"),
@@ -626,6 +652,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}`);
   }
 
@@ -874,6 +905,7 @@ export interface CheckoutStatusGitNonPaseo {
   currentBranch: string | null;
   isDirty: boolean;
   baseRef: string | null;
+  baseRefExact?: 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
@@ -893,6 +925,7 @@ export interface CheckoutStatusGitPaseo {
   currentBranch: string | null;
   isDirty: boolean;
   baseRef: string;
+  baseRefExact?: string | null;
   aheadBehind: AheadBehind | null;
   upstreamRef: string | null;
   aheadOfOrigin: number | null;
@@ -1104,7 +1137,7 @@ async function getMainRepoRootFromCommonDir(
   if (!commonDir) {
     throw new Error("Not in a git repository");
   }
-  const normalized = realpathSync(commonDir);
+  const normalized = await realpath(commonDir);
 
   if (basename(normalized) === ".git") {
     return dirname(normalized);
@@ -1118,9 +1151,17 @@ async function getMainRepoRootFromCommonDir(
     },
   );
   const worktrees = parseWorktreeList(worktreeOut);
+  const paseoPaths = new Set(
+    (
+      await Promise.all(
+        worktrees.map(async (wt) => ((await hasPaseoWorktreeMetadata(wt.path)) ? wt.path : null)),
+      )
+    ).filter((p) => p !== null),
+  );
   const nonBareNonPaseo = worktrees.filter(
     (wt) =>
       !wt.isBare &&
+      !paseoPaths.has(wt.path) &&
       !isPaseoWorktreePath(wt.path, {
         paseoHome: context?.paseoHome,
         worktreesRoot: context?.worktreesRoot,
@@ -1229,7 +1270,7 @@ export async function renameCurrentBranch(
 
   const currentBranch = await getCurrentBranch(cwd);
   if (currentBranch) {
-    rebindPaseoWorktreeChangeRequestHint(worktreeRoot, previousBranch, currentBranch);
+    await rebindPaseoWorktreeChangeRequestHint(worktreeRoot, previousBranch, currentBranch);
   }
   return { previousBranch, currentBranch };
 }
@@ -1249,7 +1290,7 @@ async function getPaseoWorktreeForCwd(
   options: PaseoWorktreeLookupOptions = {},
 ): Promise<PaseoWorktreeForCwd> {
   // Fast-path reject: non-worktree paths do not need expensive ownership checks.
-  if (!/[\\/]worktrees[\\/]/.test(cwd)) {
+  if (!/[\\/]worktrees[\\/]/.test(cwd) && (await findPaseoWorktreeRootForCwd(cwd)) === null) {
     return { isPaseoOwnedWorktree: false };
   }
 
@@ -1274,8 +1315,8 @@ function storedBaseRefFromMetadata(metadata: PaseoWorktreeMetadata | null): stri
   return metadata?.baseRef ?? metadata?.baseRefName ?? null;
 }
 
-function readPaseoWorktreeBaseRef(worktreeRoot: string): string | null {
-  return storedBaseRefFromMetadata(readPaseoWorktreeMetadata(worktreeRoot));
+async function readPaseoWorktreeBaseRef(worktreeRoot: string): Promise<string | null> {
+  return storedBaseRefFromMetadata(await readPaseoWorktreeMetadata(worktreeRoot));
 }
 
 async function getStoredBaseRefForCwd(
@@ -1285,12 +1326,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(
@@ -1549,7 +1614,12 @@ async function abortGitPullConflictState(cwd: string): Promise<void> {
   const rebaseMergePath = resolve(gitDir, "rebase-merge");
   const rebaseApplyPath = resolve(gitDir, "rebase-apply");
 
-  if (existsSync(mergeHeadPath)) {
+  if (
+    await access(mergeHeadPath).then(
+      () => true,
+      () => false,
+    )
+  ) {
     try {
       await runGitCommand(["merge", "--abort"], { cwd, timeout: 120_000 });
     } catch {
@@ -1557,7 +1627,16 @@ async function abortGitPullConflictState(cwd: string): Promise<void> {
     }
   }
 
-  if (existsSync(rebaseMergePath) || existsSync(rebaseApplyPath)) {
+  if (
+    (await access(rebaseMergePath).then(
+      () => true,
+      () => false,
+    )) ||
+    (await access(rebaseApplyPath).then(
+      () => true,
+      () => false,
+    ))
+  ) {
     try {
       await runGitCommand(["rebase", "--abort"], { cwd, timeout: 120_000 });
     } catch {
@@ -1749,7 +1828,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 =
@@ -2078,7 +2161,7 @@ export async function getCheckoutSnapshotFacts(
   }
 
   const paseoWorktreeMetadata = inspected.paseoWorktree.isPaseoOwnedWorktree
-    ? readPaseoWorktreeMetadata(inspected.paseoWorktree.worktreeRoot)
+    ? await readPaseoWorktreeMetadata(inspected.paseoWorktree.worktreeRoot)
     : null;
   const storedBaseRef = storedBaseRefFromMetadata(paseoWorktreeMetadata);
   const resolvedBaseRef = storedBaseRef ?? (await resolveBaseRef(cwd, context));
@@ -2091,7 +2174,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,
@@ -2336,6 +2420,7 @@ export async function getCheckoutStatus(
       currentBranch,
       isDirty,
       baseRef: displayBaseRef ?? baseRef,
+      baseRefExact: baseRef,
       aheadBehind,
       upstreamRef,
       aheadOfOrigin,
@@ -2354,6 +2439,7 @@ export async function getCheckoutStatus(
     currentBranch,
     isDirty,
     baseRef: displayBaseRef,
+    baseRefExact: baseRef,
     aheadBehind,
     upstreamRef,
     aheadOfOrigin,
@@ -2568,7 +2654,10 @@ async function tryResolveCheckoutCommitsBaseRef(
     return null;
   }
   const normalizedBaseRef = branchNameFromRef(baseRef);
-  if (!normalizedBaseRef || normalizedBaseRef === currentBranch) {
+  if (
+    !normalizedBaseRef ||
+    (!isQualifiedBranchRef(baseRef) && normalizedBaseRef === currentBranch)
+  ) {
     return null;
   }
   try {
@@ -2719,10 +2808,12 @@ export async function getCommitFileDiff({
   cwd,
   sha,
   path,
+  signal,
 }: {
   cwd: string;
   sha: string;
   path: string;
+  signal?: AbortSignal;
 }): Promise<ParsedDiffFile | null> {
   const worktreeRoot = await requireGitWorktreeRoot(cwd);
   const renames = await getCommitRenames(worktreeRoot, sha);
@@ -2750,6 +2841,7 @@ export async function getCommitFileDiff({
   }
 
   const parsedFiles = await parseAndHighlightDiff(stdout, worktreeRoot, {
+    signal,
     getOldFileContent: (file) => readGitFileContentAtRef(worktreeRoot, `${sha}^`, file.path),
     getNewFileContent: (file) => readGitFileContentAtRef(worktreeRoot, sha, file.path),
   });
@@ -3132,6 +3224,7 @@ export function warmCheckoutShortstatInBackground(
 }
 
 interface AppendStructuredTrackedDiffsInput {
+  signal?: AbortSignal;
   cwd: string;
   trackedChanges: CheckoutFileChange[];
   trackedNumstatByPath: Map<string, FileStat>;
@@ -3147,6 +3240,7 @@ interface AppendStructuredTrackedDiffsInput {
 }
 
 async function buildHighlightedTrackedDiffFile(input: {
+  signal?: AbortSignal;
   cwd: string;
   change: CheckoutFileChange;
   parsedFile: ParsedDiffFile;
@@ -3169,6 +3263,7 @@ async function buildHighlightedTrackedDiffFile(input: {
           : null,
       ]);
   const highlightedFile = await highlightDiffWithFileContent(parsedFile, cwd, {
+    signal: input.signal,
     oldFileContent,
     newFileContent,
   });
@@ -3254,6 +3349,7 @@ async function appendStructuredTrackedDiffs(
       const parsedFile = parsedTrackedByPath.get(change.path);
       if (parsedFile) {
         const file = await buildHighlightedTrackedDiffFile({
+          signal: input.signal,
           cwd,
           change,
           parsedFile,
@@ -3295,6 +3391,7 @@ async function appendStructuredTrackedDiffs(
 }
 
 interface ProcessUntrackedChangeInput {
+  signal?: AbortSignal;
   cwd: string;
   change: CheckoutFileChange;
   ignoreWhitespace: boolean;
@@ -3345,7 +3442,7 @@ async function processUntrackedChange(input: ProcessUntrackedChangeInput): Promi
   }
 
   appendDiff(text);
-  const parsed = await parseAndHighlightDiff(text, cwd);
+  const parsed = await parseAndHighlightDiff(text, cwd, { signal: input.signal });
   const parsedFile =
     parsed[0] ??
     ({
@@ -3541,6 +3638,7 @@ export async function getCheckoutDiff(
   cwd: string,
   compare: CheckoutDiffCompare,
   context?: CheckoutContext,
+  signal?: AbortSignal,
 ): Promise<CheckoutDiffResult> {
   cwd = await requireGitWorktreeRoot(cwd);
 
@@ -3552,10 +3650,15 @@ export async function getCheckoutDiff(
   const index =
     compare.mode === "all" ? await prepareAllChangesIndex(cwd, refsForDiff.baseRef) : null;
   try {
-    return await readCheckoutDiff(cwd, compare, {
-      ...refsForDiff,
-      indexEnv: index ? { GIT_INDEX_FILE: index.indexFile } : undefined,
-    });
+    return await readCheckoutDiff(
+      cwd,
+      compare,
+      {
+        ...refsForDiff,
+        indexEnv: index ? { GIT_INDEX_FILE: index.indexFile } : undefined,
+      },
+      signal,
+    );
   } finally {
     await index?.cleanup();
   }
@@ -3565,6 +3668,7 @@ async function readCheckoutDiff(
   cwd: string,
   compare: CheckoutDiffCompare,
   refsForDiff: CheckoutDiffRefs,
+  signal?: AbortSignal,
 ): Promise<CheckoutDiffResult> {
   const ignoreWhitespace = compare.ignoreWhitespace === true;
   let effectiveRefsForDiff = refsForDiff;
@@ -3625,6 +3729,7 @@ async function readCheckoutDiff(
 
   if (compare.includeStructured) {
     const didAppendTrackedDiffs = await appendStructuredTrackedDiffs({
+      signal,
       cwd,
       trackedChanges,
       trackedNumstatByPath: trackedDiff.trackedNumstatByPath,
@@ -3652,6 +3757,7 @@ async function readCheckoutDiff(
       break;
     }
     const didAppendUntrackedDiff = await processUntrackedChange({
+      signal,
       cwd,
       change,
       ignoreWhitespace,
@@ -3836,7 +3942,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);
@@ -4169,6 +4275,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/paseo-config-file.test.ts b/packages/server/src/utils/paseo-config-file.test.ts
index 02cbd90542..6a7e43c757 100644
--- a/packages/server/src/utils/paseo-config-file.test.ts
+++ b/packages/server/src/utils/paseo-config-file.test.ts
@@ -1,15 +1,63 @@
 import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { writeFile, truncate, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { build } from "esbuild";
 import { isPlatform } from "../test-utils/platform.js";
-import { getWorktreeSetupCommands, getWorktreeTeardownCommands } from "./worktree.js";
+import {
+  readPaseoConfig,
+  PaseoConfigSchema,
+  PaseoConfigRawSchema,
+  getWorktreeSetupCommands,
+  getWorktreeTeardownCommands,
+} from "./worktree.js";
 import {
   readPaseoConfigForEdit,
   statPaseoConfigPath,
   writePaseoConfigForEdit,
 } from "./paseo-config-file.js";
 
+let probeDirectory: string;
+let probePath: string;
+
+beforeAll(async () => {
+  probeDirectory = mkdtempSync(join(tmpdir(), "paseo-config-probe-"));
+  probePath = join(probeDirectory, "config-responsiveness.mjs");
+  // Compile before starting the measured process. A runtime TypeScript loader
+  // owns MessagePorts that the responsiveness probe otherwise charges as work.
+  await build({
+    entryPoints: [
+      fileURLToPath(new URL("./test-fixtures/config-responsiveness.ts", import.meta.url)),
+    ],
+    outfile: probePath,
+    bundle: true,
+    platform: "node",
+    format: "esm",
+  });
+});
+
+afterAll(() => {
+  rmSync(probeDirectory, { recursive: true, force: true });
+});
+
+async function measureConfigRead(directory: string) {
+  const { stdout, stderr } = await promisify(execFile)(process.execPath, [probePath, directory], {
+    timeout: 15_000,
+  });
+  process.stderr.write(stderr);
+  return JSON.parse(stdout) as {
+    result: Awaited<ReturnType<typeof readPaseoConfigForEdit>>;
+    blockingMs: number;
+    filesystemRequests: number;
+    yields: number;
+    workerMessages: number;
+  };
+}
+
 describe("paseo config file substrate", () => {
   let tempDir: string;
 
@@ -21,16 +69,185 @@ describe("paseo config file substrate", () => {
     rmSync(tempDir, { recursive: true, force: true });
   });
 
-  it("returns null config and revision when paseo.json is missing", () => {
-    const result = readPaseoConfigForEdit(tempDir);
+  it("rejects an oversized config before parsing its otherwise valid JSON", async () => {
+    writeFileSync(
+      join(tempDir, "paseo.json"),
+      JSON.stringify({ extra: "x".repeat(2 * 1024 * 1024) }),
+    );
+    expect(await readPaseoConfigForEdit(tempDir)).toEqual({
+      ok: false,
+      error: { code: "invalid_project_config" },
+    });
+  });
+
+  it("rejects a sparse oversized file without allocating its contents", async () => {
+    const configPath = join(tempDir, "paseo.json");
+    await writeFile(configPath, "");
+    await truncate(configPath, 1024 * 1024 * 1024);
+    expect(await readPaseoConfigForEdit(tempDir)).toEqual({
+      ok: false,
+      error: { code: "invalid_project_config" },
+    });
+  });
+
+  it.skipIf(isPlatform("win32"))("rejects a FIFO without waiting for a writer", async () => {
+    await promisify(execFile)("mkfifo", [join(tempDir, "paseo.json")]);
+    const modulePath = fileURLToPath(new URL("./paseo-config-file.ts", import.meta.url));
+    const script = `import { readPaseoConfigForEdit } from ${JSON.stringify(modulePath)};
+      const result = await readPaseoConfigForEdit(${JSON.stringify(tempDir)});
+      if (JSON.stringify(result) !== JSON.stringify({ok:false,error:{code:"invalid_project_config"}})) process.exit(1);`;
+    // Isolate the regression: the old sync reader blocks on the pipe and must be killed.
+    await promisify(execFile)(
+      process.execPath,
+      ["--import", "tsx", "--input-type=module", "-e", script],
+      { timeout: 2_000 },
+    );
+  });
+
+  it("excludes test-runner and loader activity from the config read budget", async () => {
+    await writeFile(join(tempDir, "paseo.json"), JSON.stringify({ worktree: { setup: "npm ci" } }));
+    const unrelatedWork = new Promise<void>((resolve) => {
+      setImmediate(() => {
+        const threadCpuUsage: (previous?: NodeJS.CpuUsage) => NodeJS.CpuUsage = Reflect.get(
+          process,
+          "threadCpuUsage",
+        );
+        const start = threadCpuUsage();
+        let elapsed: NodeJS.CpuUsage;
+        do {
+          elapsed = threadCpuUsage(start);
+        } while (elapsed.user + elapsed.system < 60_000);
+        resolve();
+      });
+    });
+    const { result, blockingMs, filesystemRequests, workerMessages } =
+      await measureConfigRead(tempDir);
+    await unrelatedWork;
+    expect(workerMessages).toBe(0);
+    expect(result).toEqual({
+      ok: true,
+      config: { worktree: { setup: "npm ci" } },
+      revision: await statPaseoConfigPath(tempDir),
+    });
+    expect(filesystemRequests).toBeGreaterThan(0);
+    expect(blockingMs).toBeLessThan(20);
+  });
+
+  it("keeps main-thread work below 20ms while admitting large configs", async () => {
+    const config = {
+      scripts: Object.fromEntries(
+        Array.from({ length: 7_000 }, (_, i) => [`script${i}`, { command: "echo hi" }]),
+      ),
+      worktree: { setup: "npm ci" },
+    };
+    await writeFile(join(tempDir, "paseo.json"), JSON.stringify(config));
+    const { result, blockingMs, filesystemRequests, yields, workerMessages } =
+      await measureConfigRead(tempDir);
+    expect(result).toEqual({ ok: true, config, revision: await statPaseoConfigPath(tempDir) });
+    expect(blockingMs).toBeLessThan(20);
+    expect(filesystemRequests).toBeGreaterThan(0);
+    expect(yields).toBeGreaterThan(0);
+    expect(workerMessages).toBe(0);
+  });
+
+  it("rejects a 32MiB config with main-thread work below 20ms", async () => {
+    await writeFile(
+      join(tempDir, "paseo.json"),
+      JSON.stringify({ extra: "x".repeat(32 * 1024 * 1024) }),
+    );
+    const { result, blockingMs, filesystemRequests, workerMessages } =
+      await measureConfigRead(tempDir);
+    expect(blockingMs).toBeLessThan(20);
+    expect(filesystemRequests).toBeGreaterThan(0);
+    expect(workerMessages).toBe(0);
+    expect(result).toEqual({ ok: false, error: { code: "invalid_project_config" } });
+  });
+
+  it.each([
+    {
+      scripts: Object.fromEntries(
+        Array.from({ length: 130 }, (_, i) => [
+          `script${i}`,
+          { command: "echo hi", extra: { keep: true } },
+        ]),
+      ),
+    },
+    {
+      scripts: { valid: { command: "echo hi" }, invalid: 42 },
+      worktree: { setup: ["one", "", 42] },
+    },
+    { scripts: ["invalid record"], worktree: { setup: "echo hi" } },
+    JSON.parse(
+      '{"scripts":{"__proto__":{"command":"echo hi"},"constructor":{"command":"echo hi"}}}',
+    ),
+  ])("preserves edit and runtime schema behavior with grouped validation (%#)", async (config) => {
+    await writeFile(join(tempDir, "paseo.json"), JSON.stringify(config));
+    const expected = PaseoConfigRawSchema.safeParse(config);
+    expect(await readPaseoConfigForEdit(tempDir)).toEqual(
+      expected.success
+        ? { ok: true, config: expected.data, revision: await statPaseoConfigPath(tempDir) }
+        : { ok: false, error: { code: "invalid_project_config" } },
+    );
+    expect(await readPaseoConfig(tempDir)).toEqual({
+      ok: true,
+      config: PaseoConfigSchema.parse(config),
+    });
+  });
+
+  it("refreshes snapshots after an external edit, repair, and removal", async () => {
+    const configPath = join(tempDir, "paseo.json");
+    await writeFile(configPath, JSON.stringify({ worktree: { setup: "old" } }));
+    const original = await readPaseoConfig(tempDir);
+    expect(original).toEqual({ ok: true, config: { worktree: { setup: ["old"], teardown: [] } } });
+    await writeFile(configPath, "{ malformed");
+    expect(await readPaseoConfigForEdit(tempDir)).toEqual({
+      ok: false,
+      error: { code: "invalid_project_config" },
+    });
+    await writeFile(configPath, JSON.stringify({ worktree: { setup: "repaired" } }));
+    expect(await readPaseoConfig(tempDir)).toEqual({
+      ok: true,
+      config: { worktree: { setup: ["repaired"], teardown: [] } },
+    });
+    await rm(configPath);
+    expect(await readPaseoConfigForEdit(tempDir)).toEqual({
+      ok: true,
+      config: null,
+      revision: null,
+    });
+  });
+
+  it("serializes competing edits so exactly one matching revision commits", async () => {
+    const results = await Promise.all(
+      ["first", "second"].map((setup) =>
+        writePaseoConfigForEdit({
+          repoRoot: tempDir,
+          config: { worktree: { setup } },
+          expectedRevision: null,
+        }),
+      ),
+    );
+    const saved = await readPaseoConfigForEdit(tempDir);
+    expect(results[0]).toEqual(saved);
+    expect(results[1]).toEqual({
+      ok: false,
+      error: {
+        code: "stale_project_config",
+        currentRevision: await statPaseoConfigPath(tempDir),
+      },
+    });
+  });
+
+  it("returns null config and revision when paseo.json is missing", async () => {
+    const result = await readPaseoConfigForEdit(tempDir);
 
     expect(result).toEqual({ ok: true, config: null, revision: null });
   });
 
-  it("returns invalid_project_config for invalid JSON", () => {
+  it("returns invalid_project_config for invalid JSON", async () => {
     writeFileSync(join(tempDir, "paseo.json"), "{ invalid json\n");
 
-    const result = readPaseoConfigForEdit(tempDir);
+    const result = await readPaseoConfigForEdit(tempDir);
 
     expect(result).toEqual({
       ok: false,
@@ -38,7 +255,7 @@ describe("paseo config file substrate", () => {
     });
   });
 
-  it("preserves raw lifecycle string and array forms with a revision token", () => {
+  it("preserves raw lifecycle string and array forms with a revision token", async () => {
     writeFileSync(
       join(tempDir, "paseo.json"),
       JSON.stringify({
@@ -49,7 +266,7 @@ describe("paseo config file substrate", () => {
       }),
     );
 
-    const result = readPaseoConfigForEdit(tempDir);
+    const result = await readPaseoConfigForEdit(tempDir);
 
     expect(result).toEqual({
       ok: true,
@@ -59,11 +276,11 @@ describe("paseo config file substrate", () => {
           teardown: ["npm run clean", "npm run reset"],
         },
       },
-      revision: statPaseoConfigPath(tempDir),
+      revision: await statPaseoConfigPath(tempDir),
     });
   });
 
-  it("keeps runtime lifecycle commands normalized for execution", () => {
+  it("keeps runtime lifecycle commands normalized for execution", async () => {
     writeFileSync(
       join(tempDir, "paseo.json"),
       JSON.stringify({
@@ -74,15 +291,15 @@ describe("paseo config file substrate", () => {
       }),
     );
 
-    expect(getWorktreeSetupCommands(tempDir)).toEqual(["npm install"]);
-    expect(getWorktreeTeardownCommands(tempDir)).toEqual(["npm run clean", "npm run reset"]);
+    expect(await getWorktreeSetupCommands(tempDir)).toEqual(["npm install"]);
+    expect(await getWorktreeTeardownCommands(tempDir)).toEqual(["npm run clean", "npm run reset"]);
   });
 
-  it("writes pretty JSON with a trailing newline when revision matches", () => {
+  it("writes pretty JSON with a trailing newline when revision matches", async () => {
     writeFileSync(join(tempDir, "paseo.json"), JSON.stringify({ worktree: { setup: "old" } }));
-    const expectedRevision = statPaseoConfigPath(tempDir);
+    const expectedRevision = await statPaseoConfigPath(tempDir);
 
-    const result = writePaseoConfigForEdit({
+    const result = await writePaseoConfigForEdit({
       repoRoot: tempDir,
       config: { worktree: { setup: "npm install" } },
       expectedRevision,
@@ -91,7 +308,7 @@ describe("paseo config file substrate", () => {
     expect(result).toEqual({
       ok: true,
       config: { worktree: { setup: "npm install" } },
-      revision: statPaseoConfigPath(tempDir),
+      revision: await statPaseoConfigPath(tempDir),
     });
     expect(readFileSync(join(tempDir, "paseo.json"), "utf8")).toBe(
       '{\n  "worktree": {\n    "setup": "npm install"\n  }\n}\n',
@@ -101,13 +318,13 @@ describe("paseo config file substrate", () => {
   // POSIX-only: Windows mtime granularity can collapse the two revisions in this fixture.
   it.skipIf(isPlatform("win32"))(
     "rejects stale writes when the current revision changed before rename",
-    () => {
+    async () => {
       writeFileSync(join(tempDir, "paseo.json"), JSON.stringify({ worktree: { setup: "old" } }));
-      const expectedRevision = statPaseoConfigPath(tempDir);
+      const expectedRevision = await statPaseoConfigPath(tempDir);
       writeFileSync(join(tempDir, "paseo.json"), JSON.stringify({ worktree: { setup: "new" } }));
-      const currentRevision = statPaseoConfigPath(tempDir);
+      const currentRevision = await statPaseoConfigPath(tempDir);
 
-      const result = writePaseoConfigForEdit({
+      const result = await writePaseoConfigForEdit({
         repoRoot: tempDir,
         config: { worktree: { setup: "from editor" } },
         expectedRevision,
@@ -123,7 +340,7 @@ describe("paseo config file substrate", () => {
     },
   );
 
-  it("round-trips unknown top-level, worktree, and script-entry fields", () => {
+  it("round-trips unknown top-level, worktree, and script-entry fields", async () => {
     const config = {
       extraTop: { keep: true },
       worktree: {
@@ -139,7 +356,7 @@ describe("paseo config file substrate", () => {
       },
     };
 
-    const result = writePaseoConfigForEdit({
+    const result = await writePaseoConfigForEdit({
       repoRoot: tempDir,
       config,
       expectedRevision: null,
@@ -148,20 +365,20 @@ describe("paseo config file substrate", () => {
     expect(result).toEqual({
       ok: true,
       config,
-      revision: statPaseoConfigPath(tempDir),
+      revision: await statPaseoConfigPath(tempDir),
     });
-    expect(readPaseoConfigForEdit(tempDir)).toEqual({
+    expect(await readPaseoConfigForEdit(tempDir)).toEqual({
       ok: true,
       config,
-      revision: statPaseoConfigPath(tempDir),
+      revision: await statPaseoConfigPath(tempDir),
     });
   });
 
-  it("returns write_failed for filesystem write exceptions", () => {
+  it("returns write_failed for filesystem write exceptions", async () => {
     const fileRoot = join(tempDir, "not-a-directory");
     writeFileSync(fileRoot, "file");
 
-    const result = writePaseoConfigForEdit({
+    const result = await writePaseoConfigForEdit({
       repoRoot: fileRoot,
       config: { worktree: { setup: "npm install" } },
       expectedRevision: null,
@@ -173,10 +390,10 @@ describe("paseo config file substrate", () => {
     });
   });
 
-  it("creates paseo.json when the file is still missing and expected revision is null", () => {
+  it("creates paseo.json when the file is still missing and expected revision is null", async () => {
     mkdirSync(join(tempDir, "nested"));
 
-    const result = writePaseoConfigForEdit({
+    const result = await writePaseoConfigForEdit({
       repoRoot: join(tempDir, "nested"),
       config: { scripts: { dev: { command: "npm run dev" } } },
       expectedRevision: null,
@@ -185,7 +402,7 @@ describe("paseo config file substrate", () => {
     expect(result).toEqual({
       ok: true,
       config: { scripts: { dev: { command: "npm run dev" } } },
-      revision: statPaseoConfigPath(join(tempDir, "nested")),
+      revision: await statPaseoConfigPath(join(tempDir, "nested")),
     });
   });
 });
diff --git a/packages/server/src/utils/paseo-config-file.ts b/packages/server/src/utils/paseo-config-file.ts
index 9b31918e63..b8152c4f22 100644
--- a/packages/server/src/utils/paseo-config-file.ts
+++ b/packages/server/src/utils/paseo-config-file.ts
@@ -1,8 +1,14 @@
-import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { constants, type Stats } from "node:fs";
+import { open, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import pLimit from "p-limit";
+import { withTimeout } from "./promise-timeout.js";
+import { setImmediate as nextTurn } from "node:timers/promises";
 import { randomUUID } from "node:crypto";
 import {
   PaseoConfigRawSchema,
+  PaseoConfigSchema,
+  type PaseoConfig,
   type PaseoConfigRaw,
   type PaseoConfigRevision,
   type ProjectConfigRpcError,
@@ -15,15 +21,18 @@ export {
 } from "@getpaseo/protocol/paseo-config-schema";
 
 export const PASEO_CONFIG_FILE_NAME = "paseo.json";
+// Configuration is deliberately small. Bound both IO and main-thread JSON/schema work.
+export const MAX_PASEO_CONFIG_BYTES = 256 * 1024;
 
 export type ReadPaseoConfigForEditResult =
   | { ok: true; config: PaseoConfigRaw | null; revision: PaseoConfigRevision | null }
   | { ok: false; error: ProjectConfigRpcError };
-
+export type ReadPaseoConfigResult =
+  | { ok: true; config: PaseoConfig | null }
+  | { ok: false; configPath: string; error: unknown };
 export type WritePaseoConfigForEditResult =
   | { ok: true; config: PaseoConfigRaw; revision: PaseoConfigRevision }
   | { ok: false; error: ProjectConfigRpcError };
-
 export interface WritePaseoConfigForEditInput {
   repoRoot: string;
   config: PaseoConfigRaw;
@@ -34,96 +43,272 @@ export function resolvePaseoConfigPath(repoRoot: string): string {
   return join(repoRoot, PASEO_CONFIG_FILE_NAME);
 }
 
-export function statPaseoConfigPath(repoRoot: string): PaseoConfigRevision | null {
-  const configPath = resolvePaseoConfigPath(repoRoot);
-  if (!existsSync(configPath)) {
-    return null;
-  }
-  const stats = statSync(configPath);
-  return {
-    mtimeMs: stats.mtimeMs,
-    size: stats.size,
-  };
+function revision(stats: Stats): PaseoConfigRevision {
+  return { mtimeMs: stats.mtimeMs, size: stats.size };
 }
 
-export function readPaseoConfigJson(repoRoot: string): unknown {
-  const configPath = resolvePaseoConfigPath(repoRoot);
-  if (!existsSync(configPath)) {
-    return null;
-  }
-  return JSON.parse(readFileSync(configPath, "utf8"));
-}
-
-export function readPaseoConfigForEdit(repoRoot: string): ReadPaseoConfigForEditResult {
+async function inspect(repoRoot: string): Promise<Stats | null> {
   try {
-    const json = readPaseoConfigJson(repoRoot);
-    if (json === null) {
-      return { ok: true, config: null, revision: null };
+    return await stat(resolvePaseoConfigPath(repoRoot));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export async function statPaseoConfigPath(repoRoot: string): Promise<PaseoConfigRevision | null> {
+  const stats = await inspect(repoRoot);
+  return stats ? revision(stats) : null;
+}
+
+function admit(stats: Stats): void {
+  if (!stats.isFile() || stats.size > MAX_PASEO_CONFIG_BYTES) {
+    throw new Error(`paseo.json must be a regular file of at most ${MAX_PASEO_CONFIG_BYTES} bytes`);
+  }
+}
+
+function fingerprint(stats: Stats | null): string {
+  return stats
+    ? `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}:${stats.ctimeMs}`
+    : "missing";
+}
+
+// The record schema validates every script synchronously. Validate bounded groups
+// through the same schemas so thousands of script entries do not monopolize a turn.
+async function validateConfig(json: unknown): Promise<{
+  edit: ReturnType<typeof PaseoConfigRawSchema.safeParse>;
+  runtime: PaseoConfig;
+}> {
+  if (json === null || typeof json !== "object" || Array.isArray(json)) {
+    return { edit: PaseoConfigRawSchema.safeParse(json), runtime: PaseoConfigSchema.parse(json) };
+  }
+  const scripts = (json as Record<string, unknown>).scripts;
+  if (scripts === null || typeof scripts !== "object" || Array.isArray(scripts)) {
+    return { edit: PaseoConfigRawSchema.safeParse(json), runtime: PaseoConfigSchema.parse(json) };
+  }
+  const withoutScripts = { ...json, scripts: {} };
+  let edit = PaseoConfigRawSchema.safeParse(withoutScripts);
+  const runtime = PaseoConfigSchema.parse(withoutScripts);
+  const entries = Object.entries(scripts);
+  if (entries.length > 32) await nextTurn();
+  let lastYield = performance.now();
+  for (let offset = 0; offset < entries.length; offset += 32) {
+    const group = { scripts: Object.fromEntries(entries.slice(offset, offset + 32)) };
+    if (edit.success) {
+      const parsed = PaseoConfigRawSchema.safeParse(group);
+      if (parsed.success) Object.assign(edit.data.scripts!, parsed.data.scripts);
+      else edit = parsed;
     }
-    return {
-      ok: true,
-      config: PaseoConfigRawSchema.parse(json),
-      revision: statPaseoConfigPath(repoRoot),
-    };
+    Object.assign(runtime.scripts!, PaseoConfigSchema.parse(group).scripts);
+    if (performance.now() - lastYield >= 2) {
+      await nextTurn();
+      lastYield = performance.now();
+    }
+  }
+  return { edit, runtime };
+}
+
+interface Snapshot {
+  fingerprint: string;
+  edit: ReadPaseoConfigForEditResult;
+  runtime: ReadPaseoConfigResult;
+}
+
+/** Owns config admission, snapshots and daemon read/modify/write ordering for every consumer. */
+class ProjectConfigOwner {
+  // A stalled mount retains its slot until the OS returns; never consume the whole fs pool.
+  private readonly filesystemOperations = pLimit(2);
+  private readonly pendingAliases = new Map<string, Promise<string>>();
+  private readonly snapshots = new Map<string, Snapshot>();
+  private readonly pending = new Map<
+    string,
+    { kind: "read" | "write"; promise: Promise<unknown> }
+  >();
+
+  async resolveRoot(repoRoot: string, activeRoots: Set<string>): Promise<string | null> {
+    const root = resolve(repoRoot);
+    if (activeRoots.has(root)) return root;
+    let pending = this.pendingAliases.get(root);
+    if (!pending) {
+      pending = this.filesystemOperations(() => realpath(root)).finally(() =>
+        this.pendingAliases.delete(root),
+      );
+      this.pendingAliases.set(root, pending);
+    }
+    try {
+      const alias = await withTimeout(pending, 5_000, "Project root unavailable");
+      return activeRoots.has(alias) ? alias : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async serialized<T>(
+    root: string,
+    kind: "read" | "write",
+    operation: () => Promise<T>,
+  ): Promise<T> {
+    const previous = this.pending.get(root);
+    if (kind === "read" && previous?.kind === "read") return previous.promise as Promise<T>;
+    const next = (async () => {
+      await previous?.promise.catch(() => undefined);
+      return this.filesystemOperations(operation);
+    })();
+    this.pending.set(root, { kind, promise: next });
+    try {
+      return await next;
+    } finally {
+      if (this.pending.get(root)?.promise === next) this.pending.delete(root);
+    }
+  }
+
+  private remember(root: string, snapshot: Snapshot): Snapshot {
+    this.snapshots.delete(root);
+    this.snapshots.set(root, snapshot);
+    // Worktrees come and go; retain only a bounded set of reusable snapshots.
+    if (this.snapshots.size > 256) this.snapshots.delete(this.snapshots.keys().next().value!);
+    return snapshot;
+  }
+
+  async read(repoRoot: string): Promise<Snapshot> {
+    const root = resolve(repoRoot);
+    return withTimeout(
+      this.serialized(root, "read", () => this.load(root)),
+      5_000,
+      "Project config unavailable",
+    );
+  }
+
+  private async load(root: string): Promise<Snapshot> {
+    const stats = await inspect(root);
+    if (stats) admit(stats);
+    const key = fingerprint(stats);
+    const cached = this.snapshots.get(root);
+    if (cached?.fingerprint === key) return this.remember(root, cached);
+    let json: unknown = null;
+    if (stats) {
+      // O_NONBLOCK prevents a regular-file -> FIFO replacement between stat and open
+      // from waiting for a writer. Check the opened descriptor again before any read.
+      const handle = await open(
+        resolvePaseoConfigPath(root),
+        constants.O_RDONLY | constants.O_NONBLOCK,
+      );
+      try {
+        const openedStats = await handle.stat();
+        admit(openedStats);
+        const bytes = Buffer.alloc(MAX_PASEO_CONFIG_BYTES + 1);
+        let length = 0;
+        while (length < bytes.length) {
+          const { bytesRead } = await handle.read(bytes, length, bytes.length - length, null);
+          if (bytesRead === 0) break;
+          length += bytesRead;
+        }
+        if (length > MAX_PASEO_CONFIG_BYTES) throw new Error("paseo.json exceeds byte limit");
+        // Never publish bytes under a revision that did not describe the opened file.
+        if (fingerprint(await handle.stat()) !== fingerprint(openedStats)) {
+          throw new Error("paseo.json changed while reading; retry the operation");
+        }
+        try {
+          json = JSON.parse(bytes.toString("utf8", 0, length));
+        } catch (error) {
+          return this.remember(root, {
+            fingerprint: key,
+            edit: { ok: false, error: { code: "invalid_project_config" } },
+            runtime: { ok: false, configPath: resolvePaseoConfigPath(root), error },
+          });
+        }
+        if (fingerprint(openedStats) !== key) {
+          throw new Error("paseo.json was replaced while reading; retry the operation");
+        }
+      } finally {
+        await handle.close();
+      }
+    }
+    const validated = json === null ? null : await validateConfig(json);
+    const parsed = validated?.edit ?? null;
+    let edit: ReadPaseoConfigForEditResult = { ok: true, config: null, revision: null };
+    if (parsed !== null) {
+      edit = parsed.success
+        ? { ok: true, config: parsed.data, revision: stats ? revision(stats) : null }
+        : { ok: false, error: { code: "invalid_project_config" } };
+    }
+    return this.remember(root, {
+      fingerprint: key,
+      edit,
+      runtime: { ok: true, config: validated?.runtime ?? null },
+    });
+  }
+
+  async write(input: WritePaseoConfigForEditInput): Promise<WritePaseoConfigForEditResult> {
+    const root = resolve(input.repoRoot);
+    return this.serialized(root, "write", async () => {
+      const { edit: parsed } = await validateConfig(input.config);
+      if (!parsed.success) return { ok: false, error: { code: "invalid_project_config" } };
+      const content = `${JSON.stringify(parsed.data, null, 2)}\n`;
+      if (Buffer.byteLength(content) > MAX_PASEO_CONFIG_BYTES) {
+        return { ok: false, error: { code: "invalid_project_config" } };
+      }
+      const tempPath = join(root, `.${PASEO_CONFIG_FILE_NAME}.${process.pid}.${randomUUID()}.tmp`);
+      try {
+        await writeFile(tempPath, content, { flag: "wx" });
+        const savedRevision = revision(await stat(tempPath));
+        const currentStats = await inspect(root);
+        if (currentStats) admit(currentStats);
+        const currentRevision = currentStats ? revision(currentStats) : null;
+        if (!paseoConfigRevisionsEqual(currentRevision, input.expectedRevision)) {
+          return { ok: false, error: { code: "stale_project_config", currentRevision } };
+        }
+        // Serialized against daemon edits. External writers still have the existing
+        // optimistic stat/rename race; revision tokens remain mtime + size.
+        await rename(tempPath, resolvePaseoConfigPath(root));
+        this.snapshots.delete(root);
+        return { ok: true, config: parsed.data, revision: savedRevision };
+      } catch {
+        return { ok: false, error: { code: "write_failed" } };
+      } finally {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+      }
+    });
+  }
+}
+
+const projectConfig = new ProjectConfigOwner();
+
+export function resolveProjectConfigRoot(
+  repoRoot: string,
+  activeRoots: Set<string>,
+): Promise<string | null> {
+  return projectConfig.resolveRoot(repoRoot, activeRoots);
+}
+
+export async function readPaseoConfig(repoRoot: string): Promise<ReadPaseoConfigResult> {
+  try {
+    return (await projectConfig.read(repoRoot)).runtime;
+  } catch (error) {
+    return { ok: false, configPath: resolvePaseoConfigPath(repoRoot), error };
+  }
+}
+
+export async function readPaseoConfigForEdit(
+  repoRoot: string,
+): Promise<ReadPaseoConfigForEditResult> {
+  try {
+    return (await projectConfig.read(repoRoot)).edit;
   } catch {
-    return {
-      ok: false,
-      error: { code: "invalid_project_config" },
-    };
+    return { ok: false, error: { code: "invalid_project_config" } };
   }
 }
 
 export function writePaseoConfigForEdit(
   input: WritePaseoConfigForEditInput,
-): WritePaseoConfigForEditResult {
-  const parsed = PaseoConfigRawSchema.safeParse(input.config);
-  if (!parsed.success) {
-    return { ok: false, error: { code: "invalid_project_config" } };
-  }
-
-  const configPath = resolvePaseoConfigPath(input.repoRoot);
-  const tempPath = join(
-    input.repoRoot,
-    `.${PASEO_CONFIG_FILE_NAME}.${process.pid}.${randomUUID()}.tmp`,
-  );
-
-  try {
-    writeFileSync(tempPath, `${JSON.stringify(parsed.data, null, 2)}\n`);
-    const currentRevision = statPaseoConfigPath(input.repoRoot);
-    if (!paseoConfigRevisionsEqual(currentRevision, input.expectedRevision)) {
-      removeTempPaseoConfig(tempPath);
-      return {
-        ok: false,
-        error: { code: "stale_project_config", currentRevision },
-      };
-    }
-
-    renameSync(tempPath, configPath);
-    const revision = statPaseoConfigPath(input.repoRoot);
-    if (!revision) {
-      return { ok: false, error: { code: "write_failed" } };
-    }
-    return { ok: true, config: parsed.data, revision };
-  } catch {
-    removeTempPaseoConfig(tempPath);
-    return { ok: false, error: { code: "write_failed" } };
-  }
+): Promise<WritePaseoConfigForEditResult> {
+  return projectConfig.write(input);
 }
 
 function paseoConfigRevisionsEqual(
   left: PaseoConfigRevision | null,
   right: PaseoConfigRevision | null,
 ): boolean {
-  if (left === null || right === null) {
-    return left === right;
-  }
+  if (left === null || right === null) return left === right;
   return left.mtimeMs === right.mtimeMs && left.size === right.size;
 }
-
-function removeTempPaseoConfig(tempPath: string): void {
-  try {
-    rmSync(tempPath, { force: true });
-  } catch {
-    // Best-effort cleanup only; callers need the original write outcome.
-  }
-}
diff --git a/packages/server/src/utils/path.ts b/packages/server/src/utils/path.ts
index a0ec908fbb..45cb8b01b5 100644
--- a/packages/server/src/utils/path.ts
+++ b/packages/server/src/utils/path.ts
@@ -107,7 +107,7 @@ export function isRealpathInsideRoot(root: string, candidate: string): boolean {
   return getRealpathAwareRelativePath(root, candidate) !== null;
 }
 
-function getRelativePathInsideRoot(root: string, candidate: string): string | null {
+export function getRelativePathInsideRoot(root: string, candidate: string): string | null {
   const compareAsWindows = shouldCompareAsWindows(root, candidate);
   const platformPath = compareAsWindows ? nodePath.win32 : nodePath.posix;
   const normalizedRoot = normalizePathForComparison(root, compareAsWindows);
@@ -175,7 +175,7 @@ function normalizePathForComparison(value: string, compareAsWindows: boolean): s
   return compareAsWindows ? normalized.toLowerCase() : normalized;
 }
 
-function normalizePathPreservingCase(value: string, compareAsWindows: boolean): string {
+export function normalizePathPreservingCase(value: string, compareAsWindows: boolean): string {
   const platformPath = compareAsWindows ? nodePath.win32 : nodePath.posix;
   const comparableValue = compareAsWindows ? stripWindowsNamespacePrefix(value) : value;
   const platformNormalized = platformPath.normalize(comparableValue);
diff --git a/packages/server/src/utils/run-git-command.test.ts b/packages/server/src/utils/run-git-command.test.ts
index 32844d0de8..5153b606dc 100644
--- a/packages/server/src/utils/run-git-command.test.ts
+++ b/packages/server/src/utils/run-git-command.test.ts
@@ -507,7 +507,6 @@ describe("runGitCommand", () => {
         command: "git",
         args: ["status", "--short"],
         cwd: process.cwd(),
-        cwdExists: true,
         timeout: 30_000,
         maxOutputBytes: 20 * 1024 * 1024,
         acceptExitCodes: [0, 1],
@@ -520,7 +519,6 @@ describe("runGitCommand", () => {
         command: "git",
         args: ["status", "--short"],
         cwd: process.cwd(),
-        cwdExists: true,
         durationMs: expect.any(Number),
         exitCode: 0,
         signal: null,
@@ -530,6 +528,9 @@ describe("runGitCommand", () => {
       }),
       "Git command closed",
     );
+    for (const [record] of trace.mock.calls) {
+      expect(record).not.toHaveProperty("cwdExists");
+    }
   });
 
   it("rejects non-zero exit codes that are not accepted and frees the slot", async () => {
diff --git a/packages/server/src/utils/run-git-command.ts b/packages/server/src/utils/run-git-command.ts
index bdf7bc1f32..3a3cbf5b4c 100644
--- a/packages/server/src/utils/run-git-command.ts
+++ b/packages/server/src/utils/run-git-command.ts
@@ -1,5 +1,4 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { existsSync } from "node:fs";
 import type { Logger } from "pino";
 import type { ProcessEnvRecord } from "../server/paseo-env.js";
 import {
@@ -311,7 +310,6 @@ function executeGitCommand<Output>(
             command: "git",
             args,
             cwd: options.cwd,
-            cwdExists: existsSync(options.cwd),
             timeout,
             maxOutputBytes,
             acceptExitCodes,
diff --git a/packages/server/src/utils/test-fixtures/config-responsiveness.ts b/packages/server/src/utils/test-fixtures/config-responsiveness.ts
new file mode 100644
index 0000000000..787ad88674
--- /dev/null
+++ b/packages/server/src/utils/test-fixtures/config-responsiveness.ts
@@ -0,0 +1,30 @@
+import { createHook, executionAsyncResource } from "node:async_hooks";
+import { stat } from "node:fs/promises";
+import { MessagePort } from "node:worker_threads";
+import assert from "node:assert/strict";
+import { setImmediate as nextTurn } from "node:timers/promises";
+import { measureMainThreadWork } from "../../test-utils/main-thread-work.js";
+import { readPaseoConfigForEdit } from "../paseo-config-file.js";
+
+// The parent bundles this fixture before launching plain Node, keeping test
+// runner callbacks and runtime loader messages outside the measured thread.
+// Read the real file once, without warming the config snapshot or schema.
+const directory = process.argv[2];
+assert.ok(directory, "Config directory is required");
+// The daemon has already used asynchronous filesystem APIs before reading a
+// project config. Start libuv's filesystem worker pool outside the measurement:
+// its first submission synchronously creates workers in a fresh Node process.
+// Stat the probe itself so the config, snapshot and schemas remain cold.
+await stat(process.argv[1]);
+await nextTurn();
+let workerMessages = 0;
+const activity = createHook({
+  before() {
+    if (executionAsyncResource() instanceof MessagePort) workerMessages++;
+  },
+}).enable();
+const measured = await measureMainThreadWork("project config main-thread work", () =>
+  readPaseoConfigForEdit(directory),
+);
+activity.disable();
+process.stdout.write(JSON.stringify({ ...measured, workerMessages }));
diff --git a/packages/server/src/utils/worktree-metadata.ts b/packages/server/src/utils/worktree-metadata.ts
index b977f7952b..fc4488d742 100644
--- a/packages/server/src/utils/worktree-metadata.ts
+++ b/packages/server/src/utils/worktree-metadata.ts
@@ -1,7 +1,12 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
-import { isAbsolute, join, resolve } from "path";
+import { mkdir, open, realpath, rename, stat, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import pLimit from "p-limit";
+import { dirname, isAbsolute, join, resolve } from "path";
 import { z } from "zod";
 
+const MAX_WORKTREE_METADATA_BYTES = 64 * 1024;
+
 const ChangeRequestLookupTargetSchema = z.object({
   headRef: z.string().min(1),
   headRepositoryOwner: z.string().min(1).optional(),
@@ -9,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({
@@ -90,75 +95,78 @@ function normalizeLegacyGitHubOwnerForBranch(owner: string): string | null {
   return /^[a-z0-9-]+$/.test(normalized) ? normalized : null;
 }
 
-export function rebindPaseoWorktreeChangeRequestHint(
+export async function rebindPaseoWorktreeChangeRequestHint(
   worktreeRoot: string,
   previousBranch: string,
   currentBranch: string,
-): boolean {
-  const metadata = readPaseoWorktreeMetadata(worktreeRoot);
-  const target = getPaseoWorktreeChangeRequestHintForBranch(metadata, previousBranch);
-  if (!metadata || !target) {
-    return false;
-  }
+): Promise<boolean> {
+  return mutateMetadata(worktreeRoot, async (root) => {
+    const metadata = await readMetadataFile(root);
+    const target = getPaseoWorktreeChangeRequestHintForBranch(metadata, previousBranch);
+    if (!metadata || !target) {
+      return false;
+    }
 
-  writePaseoWorktreeMetadataFile(worktreeRoot, {
-    ...metadata,
-    changeRequestLookupTarget: {
-      ...target,
-      ...(target.headRef === previousBranch &&
-      !target.headRepositoryOwner &&
-      target.changeRequestNumber === undefined
-        ? { headRef: currentBranch }
-        : {}),
-      localBranchName: currentBranch,
-    },
+    await writePaseoWorktreeMetadataFile(root, {
+      ...metadata,
+      changeRequestLookupTarget: {
+        ...target,
+        ...(target.headRef === previousBranch &&
+        !target.headRepositoryOwner &&
+        target.changeRequestNumber === undefined
+          ? { headRef: currentBranch }
+          : {}),
+        localBranchName: currentBranch,
+      },
+    });
+    return true;
   });
-  return true;
 }
 
-export function pinPaseoWorktreeBranchIdentityIfMissing(
+export async function pinPaseoWorktreeBranchIdentityIfMissing(
   worktreeRoot: string,
   branch: string,
-): boolean {
-  const metadata = readPaseoWorktreeMetadata(worktreeRoot);
-  if (!metadata || metadata.changeRequestLookupTarget) {
-    return false;
-  }
-  const target = createPaseoWorktreeChangeRequestHint({
-    headRef: branch,
-    localBranchName: branch,
+): Promise<boolean> {
+  return mutateMetadata(worktreeRoot, async (root) => {
+    const metadata = await readMetadataFile(root);
+    if (!metadata || metadata.changeRequestLookupTarget) {
+      return false;
+    }
+    const target = createPaseoWorktreeChangeRequestHint({
+      headRef: branch,
+      localBranchName: branch,
+    });
+    await writePaseoWorktreeMetadataFile(root, {
+      ...metadata,
+      changeRequestLookupTarget: target,
+    });
+    return true;
   });
-  writePaseoWorktreeMetadataFile(worktreeRoot, {
-    ...metadata,
-    changeRequestLookupTarget: target,
-  });
-  return true;
 }
 
-function getGitDirForWorktreeRoot(worktreeRoot: string): string {
+async function getGitDirForWorktreeRoot(worktreeRoot: string): Promise<string> {
   const gitPath = join(worktreeRoot, ".git");
-  if (!existsSync(gitPath)) {
-    throw new Error(`Not a git repository: ${worktreeRoot}`);
-  }
-
-  // In a worktree checkout, `.git` is a file containing `gitdir: <path>`.
-  // In a normal checkout, `.git` is a directory.
+  let info;
   try {
-    const gitFileContent = readFileSync(gitPath, "utf8");
-    const match = gitFileContent.match(/gitdir:\s*(.+)/);
-    if (match?.[1]) {
-      const raw = match[1].trim();
-      return isAbsolute(raw) ? raw : resolve(worktreeRoot, raw);
-    }
-  } catch {
-    // If `.git` is a directory, readFileSync will throw; fall through.
+    info = await stat(gitPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT")
+      throw new Error(`Not a git repository: ${worktreeRoot}`, { cause: error });
+    throw error;
+  }
+  if (info.isDirectory()) return gitPath;
+  const gitFileContent = await readBoundedFile(gitPath);
+  const match = gitFileContent.match(/gitdir:\s*(.+)/);
+  if (match?.[1]) {
+    const raw = match[1].trim();
+    return isAbsolute(raw) ? raw : resolve(worktreeRoot, raw);
   }
 
   return gitPath;
 }
 
-export function getPaseoWorktreeMetadataPath(worktreeRoot: string): string {
-  const gitDir = getGitDirForWorktreeRoot(worktreeRoot);
+export async function getPaseoWorktreeMetadataPath(worktreeRoot: string): Promise<string> {
+  const gitDir = await getGitDirForWorktreeRoot(worktreeRoot);
   return join(gitDir, "paseo", "worktree.json");
 }
 
@@ -213,120 +221,214 @@ function assertValidBaseRef(value: string): void {
   }
 }
 
-export function writePaseoWorktreeMetadata(
+export async function writePaseoWorktreeMetadata(
   worktreeRoot: string,
   options: {
     baseRefName: string;
     baseRef?: string;
     changeRequestLookupTarget?: PaseoWorktreeChangeRequestHint;
   },
-): void {
-  const baseRefName = normalizeBaseRefName(options.baseRefName);
-  assertValidBaseRef(baseRefName);
-  const baseRef = options.baseRef?.trim();
-  if (baseRef) {
-    assertValidBaseRef(baseRef);
-  }
+): Promise<void> {
+  return mutateMetadata(worktreeRoot, async (root) => {
+    const baseRefName = normalizeBaseRefName(options.baseRefName);
+    assertValidBaseRef(baseRefName);
+    const baseRef = options.baseRef?.trim();
+    if (baseRef) {
+      assertValidBaseRef(baseRef);
+    }
 
-  const metadata: PaseoWorktreeMetadata = {
-    version: 1,
-    baseRefName,
-    ...(baseRef ? { baseRef } : {}),
-    ...(options.changeRequestLookupTarget
-      ? { changeRequestLookupTarget: options.changeRequestLookupTarget }
-      : {}),
-  };
-  writePaseoWorktreeMetadataFile(worktreeRoot, metadata);
-}
-
-export function writePaseoWorktreeRuntimeMetadata(
-  worktreeRoot: string,
-  options: { worktreePort: number },
-): void {
-  if (!Number.isInteger(options.worktreePort) || options.worktreePort <= 0) {
-    throw new Error(`Invalid worktree runtime port: ${options.worktreePort}`);
-  }
-
-  const current = readPaseoWorktreeMetadata(worktreeRoot);
-  if (!current) {
-    throw new Error("Cannot persist worktree runtime metadata: missing base metadata");
-  }
-
-  const next: PaseoWorktreeMetadata = {
-    ...current,
-    version: 2,
-    runtime: {
-      worktreePort: options.worktreePort,
-    },
-  };
-  writePaseoWorktreeMetadataFile(worktreeRoot, next);
-}
-
-export function writePaseoWorktreeFirstAgentBranchAutoNameMetadata(
-  worktreeRoot: string,
-  options: { placeholderBranchName: string },
-): void {
-  const placeholderBranchName = options.placeholderBranchName.trim();
-  if (!placeholderBranchName) {
-    throw new Error("Placeholder branch name is required");
-  }
-
-  const current = readPaseoWorktreeMetadata(worktreeRoot);
-  if (!current) {
-    throw new Error("Cannot persist first-agent branch auto-name metadata: missing base metadata");
-  }
-
-  writePaseoWorktreeMetadataFile(worktreeRoot, {
-    ...current,
-    version: 2,
-    firstAgentBranchAutoName: {
-      status: "pending",
-      placeholderBranchName,
-    },
+    const metadata: PaseoWorktreeMetadata = {
+      version: 1,
+      baseRefName,
+      ...(baseRef ? { baseRef } : {}),
+      ...(options.changeRequestLookupTarget
+        ? { changeRequestLookupTarget: options.changeRequestLookupTarget }
+        : {}),
+    };
+    await writePaseoWorktreeMetadataFile(root, metadata);
   });
 }
 
-export function markPaseoWorktreeFirstAgentBranchAutoNameAttempted(
+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 },
+): Promise<void> {
+  return mutateMetadata(worktreeRoot, async (root) => {
+    if (!Number.isInteger(options.worktreePort) || options.worktreePort <= 0) {
+      throw new Error(`Invalid worktree runtime port: ${options.worktreePort}`);
+    }
+
+    const current = await readMetadataFile(root);
+    if (!current) {
+      throw new Error("Cannot persist worktree runtime metadata: missing base metadata");
+    }
+
+    const next: PaseoWorktreeMetadata = {
+      ...current,
+      version: 2,
+      runtime: {
+        worktreePort: options.worktreePort,
+      },
+    };
+    await writePaseoWorktreeMetadataFile(root, next);
+  });
+}
+
+export async function writePaseoWorktreeFirstAgentBranchAutoNameMetadata(
+  worktreeRoot: string,
+  options: { placeholderBranchName: string },
+): Promise<void> {
+  return mutateMetadata(worktreeRoot, async (root) => {
+    const placeholderBranchName = options.placeholderBranchName.trim();
+    if (!placeholderBranchName) {
+      throw new Error("Placeholder branch name is required");
+    }
+
+    const current = await readMetadataFile(root);
+    if (!current) {
+      throw new Error(
+        "Cannot persist first-agent branch auto-name metadata: missing base metadata",
+      );
+    }
+
+    await writePaseoWorktreeMetadataFile(root, {
+      ...current,
+      version: 2,
+      firstAgentBranchAutoName: {
+        status: "pending",
+        placeholderBranchName,
+      },
+    });
+  });
+}
+
+export async function markPaseoWorktreeFirstAgentBranchAutoNameAttempted(
   worktreeRoot: string,
   options: { attemptedAt?: string } = {},
-): PaseoWorktreeMetadata | null {
-  const current = readPaseoWorktreeMetadata(worktreeRoot);
-  if (!current || current.version !== 2 || current.firstAgentBranchAutoName?.status !== "pending") {
-    return current;
-  }
+): Promise<PaseoWorktreeMetadata | null> {
+  return mutateMetadata(worktreeRoot, async (root) => {
+    const current = await readMetadataFile(root);
+    if (
+      !current ||
+      current.version !== 2 ||
+      current.firstAgentBranchAutoName?.status !== "pending"
+    ) {
+      return current;
+    }
 
-  const next: PaseoWorktreeMetadata = {
-    ...current,
-    firstAgentBranchAutoName: {
-      status: "attempted",
-      placeholderBranchName: current.firstAgentBranchAutoName.placeholderBranchName,
-      attemptedAt: options.attemptedAt ?? new Date().toISOString(),
-    },
-  };
-  writePaseoWorktreeMetadataFile(worktreeRoot, next);
-  return next;
+    const next: PaseoWorktreeMetadata = {
+      ...current,
+      firstAgentBranchAutoName: {
+        status: "attempted",
+        placeholderBranchName: current.firstAgentBranchAutoName.placeholderBranchName,
+        attemptedAt: options.attemptedAt ?? new Date().toISOString(),
+      },
+    };
+    await writePaseoWorktreeMetadataFile(root, next);
+    return next;
+  });
 }
 
-export function readPaseoWorktreeMetadata(worktreeRoot: string): PaseoWorktreeMetadata | null {
-  const metadataPath = getPaseoWorktreeMetadataPath(worktreeRoot);
-  if (!existsSync(metadataPath)) {
-    return null;
+export async function hasPaseoWorktreeMetadata(worktreeRoot: string): Promise<boolean> {
+  try {
+    return (await readPaseoWorktreeMetadata(worktreeRoot)) !== null;
+  } catch {
+    return false;
   }
-  const parsed = JSON.parse(readFileSync(metadataPath, "utf8"));
-  return PaseoWorktreeMetadataSchema.parse(parsed);
 }
 
-export function requirePaseoWorktreeBaseRefName(worktreeRoot: string): string {
-  const metadataPath = getPaseoWorktreeMetadataPath(worktreeRoot);
-  const metadata = readPaseoWorktreeMetadata(worktreeRoot);
+/**
+ * Filesystem-only search for a Paseo worktree root at or above cwd: the
+ * first directory containing a .git entry wins, and it only counts when
+ * its git admin dir holds the paseo/worktree.json marker. Lets callers
+ * cheaply rule out plain directories before running git ownership checks.
+ */
+export async function findPaseoWorktreeRootForCwd(cwd: string): Promise<string | null> {
+  let current = resolve(cwd);
+  for (;;) {
+    if (
+      await stat(join(current, ".git")).then(
+        () => true,
+        () => false,
+      )
+    ) {
+      return (await hasPaseoWorktreeMetadata(current)) ? current : null;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+export async function readPaseoWorktreeMetadata(
+  worktreeRoot: string,
+): Promise<PaseoWorktreeMetadata | null> {
+  const key = await resolveMetadataIdentity(worktreeRoot);
+  await metadataMutations.get(key)?.catch(() => {});
+  return metadataIo(() => readMetadataFile(key));
+}
+
+async function readMetadataFile(worktreeRoot: string): Promise<PaseoWorktreeMetadata | null> {
+  const metadataPath = await getPaseoWorktreeMetadataPath(worktreeRoot);
+  try {
+    return PaseoWorktreeMetadataSchema.parse(JSON.parse(await readBoundedFile(metadataPath)));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+// O_NONBLOCK lets us reject FIFOs by kind without hanging in open(). A fixed read also
+// caps a regular file that grows between stat and read; readFile's whole-file loop does not.
+async function readBoundedFile(path: string): Promise<string> {
+  const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    const info = await file.stat();
+    const limit = MAX_WORKTREE_METADATA_BYTES;
+    if (!info.isFile() || info.size > limit)
+      throw new Error(`Invalid Paseo worktree metadata file: ${path}`);
+    const buffer = Buffer.alloc(limit + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const { bytesRead } = await file.read(buffer, length, buffer.length - length);
+      if (bytesRead === 0) break;
+      length += bytesRead;
+    }
+    if (length > limit) throw new Error(`Invalid Paseo worktree metadata file: ${path}`);
+    return buffer.toString("utf8", 0, length);
+  } finally {
+    await file.close();
+  }
+}
+
+export async function requirePaseoWorktreeBaseRefName(worktreeRoot: string): Promise<string> {
+  const metadataPath = await getPaseoWorktreeMetadataPath(worktreeRoot);
+  const metadata = await readPaseoWorktreeMetadata(worktreeRoot);
   if (!metadata) {
     throw new Error(`Missing Paseo worktree base metadata: ${metadataPath}`);
   }
   return metadata.baseRefName;
 }
 
-export function readPaseoWorktreeRuntimePort(worktreeRoot: string): number | null {
-  const metadata = readPaseoWorktreeMetadata(worktreeRoot);
+export async function readPaseoWorktreeRuntimePort(worktreeRoot: string): Promise<number | null> {
+  const metadata = await readPaseoWorktreeMetadata(worktreeRoot);
   if (!metadata) {
     return null;
   }
@@ -336,13 +438,61 @@ export function readPaseoWorktreeRuntimePort(worktreeRoot: string): number | nul
   return null;
 }
 
-function writePaseoWorktreeMetadataFile(
+async function writePaseoWorktreeMetadataFile(
   worktreeRoot: string,
   metadata: PaseoWorktreeMetadata,
-): void {
-  const metadataPath = getPaseoWorktreeMetadataPath(worktreeRoot);
-  mkdirSync(join(getGitDirForWorktreeRoot(worktreeRoot), "paseo"), { recursive: true });
-  const tempPath = `${metadataPath}.${process.pid}.${Date.now()}.tmp`;
-  writeFileSync(tempPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
-  renameSync(tempPath, metadataPath);
+): Promise<void> {
+  const metadataPath = await getPaseoWorktreeMetadataPath(worktreeRoot);
+  const contents = `${JSON.stringify(metadata, null, 2)}\n`;
+  if (Buffer.byteLength(contents) > MAX_WORKTREE_METADATA_BYTES) {
+    throw new Error(`Invalid Paseo worktree metadata file: ${metadataPath}`);
+  }
+  // Never recreate an archived Git directory while a queued mutation is pending.
+  try {
+    await mkdir(join(await getGitDirForWorktreeRoot(worktreeRoot), "paseo"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+  const tempPath = `${metadataPath}.${randomUUID()}.tmp`;
+  await writeFile(tempPath, contents, "utf8");
+  await rename(tempPath, metadataPath);
+}
+
+const metadataIo = pLimit(2);
+const metadataMutations = new Map<string, Promise<unknown>>();
+
+// Only share in-flight identity resolution: a replaced symlink must not retain an old owner.
+const metadataIdentities = new Map<string, Promise<string>>();
+
+function resolveMetadataIdentity(worktreeRoot: string): Promise<string> {
+  const path = resolve(worktreeRoot);
+  const existing = metadataIdentities.get(path);
+  if (existing) return existing;
+  const identity = metadataIo(async () => {
+    try {
+      return await realpath(path);
+    } catch {
+      return path;
+    }
+  }).finally(() => {
+    if (metadataIdentities.get(path) === identity) metadataIdentities.delete(path);
+  });
+  metadataIdentities.set(path, identity);
+  return identity;
+}
+
+async function mutateMetadata<T>(
+  worktreeRoot: string,
+  mutation: (root: string) => Promise<T>,
+): Promise<T> {
+  const key = await resolveMetadataIdentity(worktreeRoot);
+  const previous = metadataMutations.get(key) ?? Promise.resolve();
+  const pending = previous.catch(() => {}).then(() => metadataIo(() => mutation(key)));
+  metadataMutations.set(key, pending);
+  void pending
+    .finally(() => {
+      if (metadataMutations.get(key) === pending) metadataMutations.delete(key);
+    })
+    .catch(() => {});
+  return pending;
 }
diff --git a/packages/server/src/utils/worktree-path.ts b/packages/server/src/utils/worktree-path.ts
new file mode 100644
index 0000000000..d36abea762
--- /dev/null
+++ b/packages/server/src/utils/worktree-path.ts
@@ -0,0 +1,88 @@
+import { realpath, lstat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
+import { getRelativePathInsideRoot } from "./path.js";
+
+async function normalizeAbsolute(path: string): Promise<string> {
+  try {
+    return await realpath(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+// Resolve a path that does not exist yet (the normal case for a worktree
+// destination): realpath the nearest existing ancestor, then append the
+// missing tail. A plain resolve() would let a symlinked parent smuggle
+// the destination past the denylist — e.g. <repo>/alias -> <repo>/.git.
+async function normalizeCandidatePath(path: string): Promise<string> {
+  let current = resolve(path);
+  const missing: string[] = [];
+  while (!(await pathExists(current))) {
+    missing.unshift(basename(current));
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  const resolvedAncestor = await normalizeAbsolute(current);
+  return missing.length > 0 ? join(resolvedAncestor, ...missing) : resolvedAncestor;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+/**
+ * Validate a worktree destination. Throws
+ * with the reason on any violation; returns the normalized absolute path.
+ */
+export async function validateWorktreePath(options: {
+  candidate: string;
+  repoPath: string;
+}): Promise<string> {
+  const { candidate, repoPath } = options;
+  if (!isAbsolute(candidate)) {
+    throw new Error(
+      `Worktree hook returned a relative path '${candidate}'; it must be an absolute path`,
+    );
+  }
+  const normalized = await normalizeCandidatePath(candidate);
+  const normalizedRepoPath = await normalizeAbsolute(repoPath);
+
+  if (normalized === parse(normalized).root) {
+    throw new Error("Worktree hook returned the filesystem root, which is not allowed");
+  }
+  if (normalized === (await normalizeAbsolute(homedir()))) {
+    throw new Error("Worktree hook returned the user's home directory, which is not allowed");
+  }
+  if (normalized === normalizedRepoPath) {
+    throw new Error("Worktree hook returned the repository root itself, which is not allowed");
+  }
+  if (
+    [normalized, resolve(candidate)].some((path) =>
+      path
+        .split(sep)
+        .some((part) => (process.platform === "win32" ? part.toLowerCase() : part) === ".git"),
+    )
+  ) {
+    throw new Error(`Worktree hook returned a path inside a .git directory: ${normalized}`);
+  }
+  const relativeToCandidate = getRelativePathInsideRoot(normalized, normalizedRepoPath);
+  if (relativeToCandidate !== null && relativeToCandidate !== "") {
+    throw new Error(`Worktree hook returned an ancestor of the repository: ${normalized}`);
+  }
+  if ((await pathExists(normalized)) || (await pathExists(candidate))) {
+    throw new Error(
+      `Worktree hook returned a path that already exists: ${normalized}. Paseo creates the returned path.`,
+    );
+  }
+  return normalized;
+}
diff --git a/packages/server/src/utils/worktree.posix.test.ts b/packages/server/src/utils/worktree.posix.test.ts
index a550995fb3..35d59cce3f 100644
--- a/packages/server/src/utils/worktree.posix.test.ts
+++ b/packages/server/src/utils/worktree.posix.test.ts
@@ -1,5 +1,6 @@
 // POSIX-only: git worktree and teardown shell fixtures
 /* eslint-disable max-nested-callbacks */
+import { validateWorktreePath } from "./worktree-path.js";
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import {
   createWorktree as createWorktreePrimitive,
@@ -21,7 +22,13 @@ import {
   type WorktreeConfig,
 } from "./worktree";
 import type { PaseoConfig } from "@getpaseo/protocol/paseo-config-schema";
-import { getPaseoWorktreeMetadataPath, readPaseoWorktreeMetadata } from "./worktree-metadata.js";
+import {
+  getPaseoWorktreeMetadataPath,
+  readPaseoWorktreeMetadata,
+  writePaseoWorktreeMetadata,
+  writePaseoWorktreeRuntimeMetadata,
+  writePaseoWorktreeFirstAgentBranchAutoNameMetadata,
+} from "./worktree-metadata.js";
 import {
   getCheckoutDiff,
   getCheckoutStatus,
@@ -48,8 +55,8 @@ import { delimiter, dirname, join } from "path";
 import { tmpdir } from "os";
 import net from "node:net";
 
-function loadConfigForTest(repoRoot: string): PaseoConfig | null {
-  const result = readPaseoConfig(repoRoot);
+async function loadConfigForTest(repoRoot: string): Promise<PaseoConfig | null> {
+  const result = await readPaseoConfig(repoRoot);
   return result.ok ? result.config : null;
 }
 
@@ -125,7 +132,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
       expect(result.worktreePath).toBe(join(paseoHome, "worktrees", projectHash, "hello-world"));
       expect(existsSync(result.worktreePath)).toBe(true);
       expect(existsSync(join(result.worktreePath, "file.txt"))).toBe(true);
-      const metadataPath = getPaseoWorktreeMetadataPath(result.worktreePath);
+      const metadataPath = await getPaseoWorktreeMetadataPath(result.worktreePath);
       expect(existsSync(metadataPath)).toBe(true);
       const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
       expect(metadata).toMatchObject({
@@ -153,7 +160,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
       ).resolves.toMatchObject({ allowed: true, worktreeRoot: join(worktreesRoot, projectHash) });
       await expect(
         isPaseoOwnedWorktreeCwd(result.worktreePath, { paseoHome }),
-      ).resolves.toMatchObject({ allowed: false });
+      ).resolves.toMatchObject({ allowed: true, worktreePath: result.worktreePath });
 
       const worktrees = await listPaseoWorktrees({ cwd: repoDir, paseoHome, worktreesRoot });
       expect(worktrees.map((entry) => entry.path)).toContain(result.worktreePath);
@@ -256,7 +263,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
         cwd: result.worktreePath,
       });
 
-      const metadataPath = getPaseoWorktreeMetadataPath(result.worktreePath);
+      const metadataPath = await getPaseoWorktreeMetadataPath(result.worktreePath);
       const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
       expect(metadata).toMatchObject({
         version: 1,
@@ -319,7 +326,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
       // baseRefName must be the repo's default branch, not the checked-out branch
       // itself — otherwise the diff panel compares the branch against itself and
       // always shows no changes.
-      const metadataPath = getPaseoWorktreeMetadataPath(result.worktreePath);
+      const metadataPath = await getPaseoWorktreeMetadataPath(result.worktreePath);
       const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
       expect(metadata).toMatchObject({
         version: 1,
@@ -370,7 +377,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
       });
 
       expect(existsSync(result.worktreePath)).toBe(true);
-      const metadataPath = getPaseoWorktreeMetadataPath(result.worktreePath);
+      const metadataPath = await getPaseoWorktreeMetadataPath(result.worktreePath);
       const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
       expect(metadata).toMatchObject({ version: 1, baseRefName: "develop" });
     });
@@ -406,7 +413,9 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
 
       expect(result.branchName).toBe("main-1");
       expect(existsSync(result.worktreePath)).toBe(true);
-      expect(readPaseoWorktreeMetadata(result.worktreePath)?.changeRequestLookupTarget).toEqual({
+      expect(
+        (await readPaseoWorktreeMetadata(result.worktreePath))?.changeRequestLookupTarget,
+      ).toEqual({
         headRef: "main-1",
         localBranchName: "main-1",
       });
@@ -459,7 +468,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
         .trim();
       expect(currentBranch).toBe("user/feature");
 
-      const metadataPath = getPaseoWorktreeMetadataPath(result.worktreePath);
+      const metadataPath = await getPaseoWorktreeMetadataPath(result.worktreePath);
       const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
       expect(metadata).toMatchObject({ baseRefName: "main" });
     });
@@ -566,7 +575,9 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
         "from-origin\n",
       );
       expect(
-        JSON.parse(readFileSync(getPaseoWorktreeMetadataPath(originResult.worktreePath), "utf8")),
+        JSON.parse(
+          readFileSync(await getPaseoWorktreeMetadataPath(originResult.worktreePath), "utf8"),
+        ),
       ).toMatchObject({ baseRefName: "main" });
     });
 
@@ -607,7 +618,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
       // to the commit the worktree was cut from: "main" resolves local-first, which here is
       // a different commit than the fork's upstream.
       expect(
-        JSON.parse(readFileSync(getPaseoWorktreeMetadataPath(result.worktreePath), "utf8")),
+        JSON.parse(readFileSync(await getPaseoWorktreeMetadataPath(result.worktreePath), "utf8")),
       ).toMatchObject({ baseRefName: "main", baseRef: "refs/remotes/upstream/main" });
 
       // An untouched child must report no work of its own. Comparing against the wrong base
@@ -694,7 +705,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
       });
 
       expect(
-        JSON.parse(readFileSync(getPaseoWorktreeMetadataPath(result.worktreePath), "utf8")),
+        JSON.parse(readFileSync(await getPaseoWorktreeMetadataPath(result.worktreePath), "utf8")),
       ).toMatchObject({
         baseRefName: "release+hotfix",
         baseRef: "refs/remotes/upstream/release+hotfix",
@@ -894,7 +905,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
         worktreePath: result.worktreePath,
         branchName: result.branchName,
       });
-      expect(getWorktreeSetupCommands(result.worktreePath)).toEqual([
+      expect(await getWorktreeSetupCommands(result.worktreePath)).toEqual([
         'greeting="hello from string setup"\necho "$greeting" > setup.log',
       ]);
       expect(readFileSync(join(result.worktreePath, "setup.log"), "utf8").trim()).toBe(
@@ -963,7 +974,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
       expect(readFileSync(join(repoDir, "setup-path.log"), "utf8").trim()).toBe("shim:ok");
     });
 
-    it("treats blank lifecycle strings as empty", () => {
+    it("treats blank lifecycle strings as empty", async () => {
       writeFileSync(
         join(repoDir, "paseo.json"),
         JSON.stringify({
@@ -974,11 +985,11 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
         }),
       );
 
-      expect(getWorktreeSetupCommands(repoDir)).toEqual([]);
-      expect(getWorktreeTeardownCommands(repoDir)).toEqual([]);
+      expect(await getWorktreeSetupCommands(repoDir)).toEqual([]);
+      expect(await getWorktreeTeardownCommands(repoDir)).toEqual([]);
     });
 
-    it("filters non-string and blank entries from lifecycle arrays", () => {
+    it("filters non-string and blank entries from lifecycle arrays", async () => {
       writeFileSync(
         join(repoDir, "paseo.json"),
         JSON.stringify({
@@ -999,11 +1010,11 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
         }),
       );
 
-      expect(getWorktreeSetupCommands(repoDir)).toEqual([
+      expect(await getWorktreeSetupCommands(repoDir)).toEqual([
         'echo "first" > setup-array.log',
         'echo "second" >> setup-array.log',
       ]);
-      expect(getWorktreeTeardownCommands(repoDir)).toEqual([
+      expect(await getWorktreeTeardownCommands(repoDir)).toEqual([
         'echo "first" > "$PASEO_SOURCE_CHECKOUT_PATH/teardown-array.log"',
         'echo "second" >> "$PASEO_SOURCE_CHECKOUT_PATH/teardown-array.log"',
       ]);
@@ -1134,7 +1145,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
       };
       writeFileSync(join(repoDir, "paseo.json"), JSON.stringify(paseoConfig));
 
-      expect(getWorktreeTerminalSpecs(repoDir)).toEqual([
+      expect(await getWorktreeTerminalSpecs(repoDir)).toEqual([
         { name: "Dev Server", command: "npm run dev" },
         { command: "cd packages/app && npm run dev" },
       ]);
@@ -1154,7 +1165,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
       };
       writeFileSync(join(repoDir, "paseo.json"), JSON.stringify(paseoConfig));
 
-      expect(getWorktreeTerminalSpecs(repoDir)).toEqual([
+      expect(await getWorktreeTerminalSpecs(repoDir)).toEqual([
         { name: "Watch", command: "npm run watch" },
         { command: "npm run test" },
       ]);
@@ -1172,7 +1183,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
         }),
       );
 
-      const scriptConfigs = getScriptConfigs(loadConfigForTest(repoDir));
+      const scriptConfigs = getScriptConfigs(await loadConfigForTest(repoDir));
       const typecheck = scriptConfigs.get("typecheck");
 
       expect(typecheck).toEqual({
@@ -1196,7 +1207,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
         }),
       );
 
-      const scriptConfigs = getScriptConfigs(loadConfigForTest(repoDir));
+      const scriptConfigs = getScriptConfigs(await loadConfigForTest(repoDir));
       const server = scriptConfigs.get("server");
 
       expect(server).toEqual({
@@ -1236,7 +1247,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
         }),
       );
 
-      expect(getScriptConfigs(loadConfigForTest(repoDir))).toEqual(
+      expect(getScriptConfigs(await loadConfigForTest(repoDir))).toEqual(
         new Map([
           ["valid", { command: "npm run valid" }],
           ["invalidType", { command: "npm run worker" }],
@@ -1370,6 +1381,200 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
     });
   });
 
+  describe("worktrees at explicit paths", () => {
+    let tempDir: string;
+    let repoDir: string;
+    let paseoHome: string;
+
+    beforeEach(() => {
+      tempDir = realpathSync(mkdtempSync(join(tmpdir(), "worktree-explicit-test-")));
+      repoDir = join(tempDir, "test-repo");
+      paseoHome = join(tempDir, "paseo-home");
+
+      mkdirSync(repoDir, { recursive: true });
+      execFileSync("git", ["init", "-b", "main"], { cwd: repoDir });
+      execFileSync("git", ["config", "user.email", "test@test.com"], { cwd: repoDir });
+      execFileSync("git", ["config", "user.name", "Test"], { cwd: repoDir });
+      writeFileSync(join(repoDir, "file.txt"), "hello\n");
+      execFileSync("git", ["add", "."], { cwd: repoDir });
+      execFileSync("git", ["-c", "commit.gpgsign=false", "commit", "-m", "initial"], {
+        cwd: repoDir,
+      });
+    });
+
+    afterEach(() => {
+      rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it("places, owns, lists, and deletes a worktree outside the legacy root", async () => {
+      // Sibling layout: <repo-parent>/wt-<slug>
+
+      const result = await createWorktreePrimitive({
+        cwd: repoDir,
+        worktreeSlug: "sibling-one",
+        source: { kind: "branch-off", baseBranch: "main", branchName: "feature/sibling" },
+        paseoHome,
+        worktreePath: join(tempDir, "wt-sibling-one"),
+      });
+
+      expect(result.worktreePath).toBe(join(tempDir, "wt-sibling-one"));
+      expect(existsSync(join(result.worktreePath, "file.txt"))).toBe(true);
+      expect(existsSync(await getPaseoWorktreeMetadataPath(result.worktreePath))).toBe(true);
+
+      const ownership = await isPaseoOwnedWorktreeCwd(result.worktreePath, { paseoHome });
+      expect(ownership.allowed).toBe(true);
+      expect(ownership.worktreePath).toBe(result.worktreePath);
+      // A subdirectory of the worktree resolves to the worktree root.
+      mkdirSync(join(result.worktreePath, "sub"), { recursive: true });
+      const nested = await isPaseoOwnedWorktreeCwd(join(result.worktreePath, "sub"), {
+        paseoHome,
+      });
+      expect(nested.worktreePath).toBe(result.worktreePath);
+
+      const listed = await listPaseoWorktrees({ cwd: repoDir, paseoHome });
+      expect(listed.map((entry) => entry.path)).toContain(result.worktreePath);
+
+      await deletePaseoWorktree({ cwd: repoDir, worktreePath: result.worktreePath, paseoHome });
+      expect(existsSync(result.worktreePath)).toBe(false);
+    });
+
+    it("removes branches fetched by the source plan when git worktree add fails", async () => {
+      // A branch that exists only on the remote: resolving a
+      // checkout-branch plan fetches it into a local branch. A script
+      // failure must not leave that branch behind, or the next attempt
+      // would uniquify to a different branch name.
+      const remoteDir = join(tempDir, "remote.git");
+      execFileSync("git", ["clone", "--bare", repoDir, remoteDir], { cwd: tempDir });
+      execFileSync("git", ["remote", "add", "origin", remoteDir], { cwd: repoDir });
+      execFileSync("git", ["push", "origin", "main"], { cwd: repoDir });
+      execFileSync("git", ["branch", "feature/remote-check"], { cwd: repoDir });
+      execFileSync("git", ["push", "origin", "feature/remote-check"], { cwd: repoDir });
+      execFileSync("git", ["branch", "-D", "feature/remote-check"], { cwd: repoDir });
+      execFileSync("git", ["fetch", "origin"], { cwd: repoDir });
+
+      mkdirSync(join(tempDir, "occupied"));
+      writeFileSync(join(tempDir, "occupied", "keep"), "keep");
+      await expect(
+        createWorktreePrimitive({
+          cwd: repoDir,
+          worktreeSlug: "remote-check",
+          source: { kind: "checkout-branch", branchName: "feature/remote-check" },
+          paseoHome,
+          worktreePath: join(tempDir, "occupied"),
+        }),
+      ).rejects.toThrow();
+
+      const localBranches = execFileSync("git", ["branch", "--list", "feature/remote-check"], {
+        cwd: repoDir,
+        encoding: "utf8",
+      });
+      expect(localBranches.trim()).toBe("");
+    });
+
+    it("deletes only the registered destination nested beneath the legacy root", async () => {
+      const parent = join(paseoHome, "worktrees", "acme", "widgets");
+      const worktreePath = join(parent, "topic");
+      const siblingPath = join(parent, "sibling");
+      await createWorktreePrimitive({
+        cwd: repoDir,
+        paseoHome,
+        worktreeSlug: "topic",
+        worktreePath,
+        source: { kind: "branch-off", branchName: "topic", baseBranch: "main" },
+      });
+      await createWorktreePrimitive({
+        cwd: repoDir,
+        paseoHome,
+        worktreeSlug: "sibling",
+        worktreePath: siblingPath,
+        source: { kind: "branch-off", branchName: "sibling", baseBranch: "main" },
+      });
+      mkdirSync(join(worktreePath, "nested"));
+      expect(
+        await isPaseoOwnedWorktreeCwd(join(worktreePath, "nested"), { paseoHome }),
+      ).toMatchObject({ allowed: true, worktreePath });
+      await deletePaseoWorktree({ cwd: repoDir, paseoHome, worktreePath, registryProven: true });
+      expect(existsSync(worktreePath)).toBe(false);
+      expect(readFileSync(join(siblingPath, "file.txt"), "utf8")).toBe("hello\n");
+    });
+
+    it("rejects a destination under a symlink into .git", async () => {
+      const alias = join(tempDir, "git-alias");
+      symlinkSync(join(repoDir, ".git"), alias, "dir");
+      await expect(
+        validateWorktreePath({ candidate: join(alias, "new", "worktree"), repoPath: repoDir }),
+      ).rejects.toThrow("inside a .git directory");
+      expect(existsSync(join(repoDir, ".git", "new"))).toBe(false);
+    });
+
+    it("uses an explicit worktreePath verbatim", async () => {
+      const explicitPath = join(tempDir, "explicit-wt");
+
+      const result = await createWorktreePrimitive({
+        cwd: repoDir,
+        worktreeSlug: "explicit-one",
+        source: { kind: "branch-off", baseBranch: "main", branchName: "feature/explicit" },
+        paseoHome,
+        worktreePath: explicitPath,
+      });
+
+      expect(result.worktreePath).toBe(explicitPath);
+      expect(existsSync(join(explicitPath, "file.txt"))).toBe(true);
+    });
+
+    it("restore recreates at the recorded path", async () => {
+      const created = await createWorktreePrimitive({
+        cwd: repoDir,
+        worktreeSlug: "restorable",
+        source: { kind: "branch-off", baseBranch: "main", branchName: "feature/restorable" },
+        paseoHome,
+        worktreePath: join(tempDir, "wt-sibling-one"),
+      });
+      await deletePaseoWorktree({ cwd: repoDir, worktreePath: created.worktreePath, paseoHome });
+      expect(existsSync(created.worktreePath)).toBe(false);
+
+      const restored = await createWorktreePrimitive({
+        cwd: repoDir,
+        worktreeSlug: "restorable",
+        source: { kind: "restore", branchName: "feature/restorable", baseRef: "main" },
+        paseoHome,
+        worktreePath: created.worktreePath,
+      });
+
+      expect(restored.worktreePath).toBe(created.worktreePath);
+      expect(existsSync(join(restored.worktreePath, "file.txt"))).toBe(true);
+    });
+
+    it("does not treat a copied marker in a non-worktree directory as ownership", async () => {
+      const created = await createWorktreePrimitive({
+        cwd: repoDir,
+        worktreeSlug: "marker-source",
+        source: { kind: "branch-off", baseBranch: "main", branchName: "feature/marker" },
+        paseoHome,
+        worktreePath: join(tempDir, "wt-sibling-one"),
+      });
+      const metadata = await readPaseoWorktreeMetadata(created.worktreePath);
+      expect(metadata).not.toBeNull();
+
+      // A plain directory with a .git file pointing at a copied admin dir
+      // that holds a paseo/worktree.json. Git does not list it as a
+      // worktree, so the copied marker must not prove ownership.
+      const fakeDir = join(tempDir, "fake-worktree");
+      const fakeAdmin = join(tempDir, "fake-admin");
+      mkdirSync(join(fakeAdmin, "paseo"), { recursive: true });
+      mkdirSync(fakeDir, { recursive: true });
+      writeFileSync(join(fakeAdmin, "paseo", "worktree.json"), JSON.stringify(metadata));
+      writeFileSync(join(fakeDir, ".git"), `gitdir: ${fakeAdmin}\n`);
+
+      const ownership = await isPaseoOwnedWorktreeCwd(fakeDir, { paseoHome });
+      expect(ownership.allowed).toBe(false);
+      await expect(
+        deletePaseoWorktree({ cwd: repoDir, worktreePath: fakeDir, paseoHome }),
+      ).rejects.toThrow("Refusing to delete non-Paseo worktree");
+      expect(existsSync(fakeDir)).toBe(true);
+    });
+  });
+
   describe("paseo worktree manager", () => {
     let tempDir: string;
     let repoDir: string;
@@ -1547,7 +1752,7 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
 
       await deletePaseoWorktree({ cwd: repoDir, worktreePath: created.worktreePath, paseoHome });
 
-      expect(getWorktreeTeardownCommands(repoDir)).toEqual([
+      expect(await getWorktreeTeardownCommands(repoDir)).toEqual([
         'cleanup_message="teardown string"\necho "$cleanup_message" > "$PASEO_SOURCE_CHECKOUT_PATH/teardown.log"',
       ]);
       expect(readFileSync(join(repoDir, "teardown.log"), "utf8").trim()).toBe("teardown string");
@@ -1617,3 +1822,104 @@ describe.skipIf(isPlatform("win32"))("worktree POSIX-only", () => {
     });
   });
 });
+
+describe.skipIf(isPlatform("win32"))("async worktree metadata", () => {
+  it("serializes metadata mutations per worktree while another worktree progresses", async () => {
+    const root = mkdtempSync(join(tmpdir(), "worktree-metadata-order-"));
+    const first = join(root, "first");
+    const second = join(root, "second");
+    mkdirSync(join(first, ".git"), { recursive: true });
+    mkdirSync(join(second, ".git"), { recursive: true });
+    try {
+      await writePaseoWorktreeMetadata(first, { baseRefName: "main" });
+      await writePaseoWorktreeMetadata(second, { baseRefName: "release" });
+      const order: string[] = [];
+      const runtime = writePaseoWorktreeRuntimeMetadata(first, { worktreePort: 4101 }).then(() =>
+        order.push("first-runtime"),
+      );
+      const unrelated = writePaseoWorktreeRuntimeMetadata(second, { worktreePort: 4102 }).then(() =>
+        order.push("second-runtime"),
+      );
+      const naming = writePaseoWorktreeFirstAgentBranchAutoNameMetadata(first, {
+        placeholderBranchName: "topic",
+      }).then(() => order.push("first-naming"));
+      // A read issued while writes are pending observes their completed snapshot.
+      const snapshot = readPaseoWorktreeMetadata(first);
+      await Promise.all([runtime, unrelated, naming]);
+      expect(order.indexOf("first-runtime")).toBeLessThan(order.indexOf("first-naming"));
+      expect(await snapshot).toMatchObject({
+        baseRefName: "main",
+        runtime: { worktreePort: 4101 },
+        firstAgentBranchAutoName: { status: "pending", placeholderBranchName: "topic" },
+      });
+      expect(await readPaseoWorktreeMetadata(second)).toMatchObject({
+        baseRefName: "release",
+        runtime: { worktreePort: 4102 },
+      });
+      const alias = join(root, "first-alias");
+      symlinkSync(first, alias, "dir");
+      await Promise.all([
+        writePaseoWorktreeRuntimeMetadata(first, { worktreePort: 4103 }),
+        writePaseoWorktreeFirstAgentBranchAutoNameMetadata(alias, {
+          placeholderBranchName: "renamed",
+        }),
+      ]);
+      expect(await readPaseoWorktreeMetadata(first)).toMatchObject({
+        runtime: { worktreePort: 4103 },
+        firstAgentBranchAutoName: { placeholderBranchName: "renamed" },
+      });
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("a queued metadata mutation cannot recreate an archived Git directory", async () => {
+    const root = mkdtempSync(join(tmpdir(), "worktree-metadata-archive-"));
+    mkdirSync(join(root, ".git"));
+    try {
+      await writePaseoWorktreeMetadata(root, { baseRefName: "main" });
+      const pending = writePaseoWorktreeRuntimeMetadata(root, { worktreePort: 4101 });
+      // The mutation is queued in a microtask, so archive wins this ordering.
+      rmSync(join(root, ".git"), { recursive: true });
+      await expect(pending).rejects.toThrow("Not a git repository");
+      expect(existsSync(join(root, ".git"))).toBe(false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("recognizes a removed worktree under a symlinked ownership root", async () => {
+    const root = mkdtempSync(join(tmpdir(), "worktree-ownership-alias-"));
+    const actual = join(root, "actual");
+    const alias = join(root, "worktrees");
+    mkdirSync(actual);
+    symlinkSync(actual, alias, "dir");
+    try {
+      const cwd = join(alias, "project", "removed");
+      expect(
+        await isPaseoOwnedWorktreeCwd(cwd, { worktreesRoot: alias, knownGitCommonDir: null }),
+      ).toMatchObject({ allowed: true, worktreePath: cwd });
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects oversized metadata and named pipes without reading them whole", async () => {
+    const root = mkdtempSync(join(tmpdir(), "worktree-metadata-admission-"));
+    mkdirSync(join(root, ".git", "paseo"), { recursive: true });
+    try {
+      const path = await getPaseoWorktreeMetadataPath(root);
+      writeFileSync(path, JSON.stringify({ version: 1, baseRefName: "x".repeat(64 * 1024) }));
+      await expect(readPaseoWorktreeMetadata(root)).rejects.toThrow(
+        "Invalid Paseo worktree metadata file",
+      );
+      rmSync(path);
+      execFileSync("mkfifo", [path]);
+      await expect(readPaseoWorktreeMetadata(root)).rejects.toThrow(
+        "Invalid Paseo worktree metadata file",
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/server/src/utils/worktree.test.ts b/packages/server/src/utils/worktree.test.ts
index 4d6f50bba6..f549b461f8 100644
--- a/packages/server/src/utils/worktree.test.ts
+++ b/packages/server/src/utils/worktree.test.ts
@@ -5,6 +5,7 @@ import {
   deletePaseoWorktree,
   isPaseoOwnedWorktreeCwd,
   mapWorkspaceCwdToWorktree,
+  runWorktreeTeardownCommands,
   slugify,
   type CreateWorktreeOptions,
   type WorktreeConfig,
@@ -171,7 +172,15 @@ describe("paseo worktree manager", () => {
     expect(existsSync(created.worktreePath)).toBe(true);
 
     const ownership = await isPaseoOwnedWorktreeCwd(created.worktreePath, { paseoHome });
-    expect(ownership.allowed).toBe(true);
+    expect(ownership).toMatchObject({ allowed: true, worktreePath: created.worktreePath });
+    // Windows may report the same root through native 8.3 and JS long spellings.
+    const nativeWorktreePath = realpathSync.native(created.worktreePath);
+    await expect(
+      runWorktreeTeardownCommands({
+        worktreePath: created.worktreePath,
+        teardownCwd: nativeWorktreePath,
+      }),
+    ).resolves.toEqual([]);
     await expect(
       isPaseoOwnedWorktreeCwd(join(created.worktreePath, "packages", "app"), { paseoHome }),
     ).resolves.toMatchObject({
@@ -293,6 +302,22 @@ describe("paseo worktree manager", () => {
     expect(existsSync(created.worktreePath)).toBe(false);
   });
 
+  it("deletes a worktree when Git reports its source through native and long path spellings", async () => {
+    const created = await createLegacyWorktreeForTest({
+      branchName: "identity-delete",
+      cwd: repoDir,
+      baseBranch: "main",
+      worktreeSlug: "identity-delete",
+      paseoHome,
+    });
+    await deletePaseoWorktree({
+      cwd: realpathSync.native(repoDir),
+      worktreePath: created.worktreePath,
+      paseoHome,
+    });
+    expect(existsSync(created.worktreePath)).toBe(false);
+  });
+
   it("is idempotent: deleting an already-absent worktree succeeds", async () => {
     const created = await createLegacyWorktreeForTest({
       branchName: "idempotent-delete-branch",
diff --git a/packages/server/src/utils/worktree.ts b/packages/server/src/utils/worktree.ts
index ca921fb219..2fc8bc05db 100644
--- a/packages/server/src/utils/worktree.ts
+++ b/packages/server/src/utils/worktree.ts
@@ -1,16 +1,17 @@
 import { execFile } from "child_process";
 import { promisify } from "util";
-import { constants as fsConstants, existsSync, mkdirSync, realpathSync, statSync } from "fs";
-import { copyFile, rm, stat } from "fs/promises";
+import { constants as fsConstants, realpath } from "fs";
+import { copyFile, mkdir, rm, stat } from "fs/promises";
 import { join, basename, dirname, isAbsolute, resolve, sep } from "path";
 import net from "node:net";
 import { createHash } from "node:crypto";
 import stripAnsi from "strip-ansi";
+import pLimit from "p-limit";
 import {
   buildStringCommandShellInvocation,
   createStringCommandShellEnv,
 } from "./string-command-shell.js";
-import { readPaseoConfigJson, resolvePaseoConfigPath } from "./paseo-config-file.js";
+import { readPaseoConfig } from "./paseo-config-file.js";
 export {
   PaseoConfigRawSchema,
   PaseoLifecycleCommandRawSchema,
@@ -20,9 +21,11 @@ export {
   type PaseoConfig,
   type PaseoConfigRaw,
 } from "@getpaseo/protocol/paseo-config-schema";
-import { PaseoConfigSchema, type PaseoConfig } from "@getpaseo/protocol/paseo-config-schema";
+import { type PaseoConfig } from "@getpaseo/protocol/paseo-config-schema";
 import {
   createPaseoWorktreeChangeRequestHint,
+  hasPaseoWorktreeMetadata,
+  findPaseoWorktreeRootForCwd,
   normalizeBaseRefName,
   isQualifiedRef,
   type PaseoWorktreeChangeRequestHint,
@@ -37,7 +40,12 @@ import { spawnProcess } from "./spawn.js";
 import { resolvePaseoHome } from "../server/paseo-home.js";
 import { createExternalProcessEnv } from "../server/paseo-env.js";
 import { parseGitRevParsePath, resolveGitRevParsePath } from "./git-rev-parse-path.js";
-import { expandTilde, getRealpathAwareRelativePath, isPathInsideRoot } from "./path.js";
+import {
+  expandTilde,
+  getRealpathAwareRelativePath,
+  getRelativePathInsideRoot,
+  isPathInsideRoot,
+} from "./path.js";
 import { terminateWithTreeKill } from "./tree-kill.js";
 
 export { slugify, validateBranchSlug } from "@getpaseo/protocol/branch-slug";
@@ -212,6 +220,7 @@ export interface CreateWorktreeOptions {
   source: WorktreeSource;
   paseoHome?: string;
   worktreesRoot?: string;
+  worktreePath?: string;
 }
 
 export class BranchAlreadyCheckedOutError extends Error {
@@ -246,21 +255,7 @@ export class InvalidGitBranchNameError extends Error {
   }
 }
 
-export type ReadPaseoConfigResult =
-  | { ok: true; config: PaseoConfig | null }
-  | { ok: false; configPath: string; error: unknown };
-
-export function readPaseoConfig(repoRoot: string): ReadPaseoConfigResult {
-  try {
-    const json = readPaseoConfigJson(repoRoot);
-    if (json === null) {
-      return { ok: true, config: null };
-    }
-    return { ok: true, config: PaseoConfigSchema.parse(json) };
-  } catch (error) {
-    return { ok: false, configPath: resolvePaseoConfigPath(repoRoot), error };
-  }
-}
+export { readPaseoConfig, type ReadPaseoConfigResult } from "./paseo-config-file.js";
 
 export function paseoConfigParseError(failure: { configPath: string; error: unknown }): Error {
   const detail = failure.error instanceof Error ? failure.error.message : String(failure.error);
@@ -269,24 +264,26 @@ export function paseoConfigParseError(failure: { configPath: string; error: unkn
   });
 }
 
-function readPaseoConfigOrThrow(repoRoot: string): PaseoConfig | null {
-  const result = readPaseoConfig(repoRoot);
+async function readPaseoConfigOrThrow(repoRoot: string): Promise<PaseoConfig | null> {
+  const result = await readPaseoConfig(repoRoot);
   if (!result.ok) {
     throw paseoConfigParseError(result);
   }
   return result.config;
 }
 
-export function getWorktreeSetupCommands(repoRoot: string): string[] {
-  return readPaseoConfigOrThrow(repoRoot)?.worktree?.setup ?? [];
+export async function getWorktreeSetupCommands(repoRoot: string): Promise<string[]> {
+  return (await readPaseoConfigOrThrow(repoRoot))?.worktree?.setup ?? [];
 }
 
-export function getWorktreeTeardownCommands(repoRoot: string): string[] {
-  return readPaseoConfigOrThrow(repoRoot)?.worktree?.teardown ?? [];
+export async function getWorktreeTeardownCommands(repoRoot: string): Promise<string[]> {
+  return (await readPaseoConfigOrThrow(repoRoot))?.worktree?.teardown ?? [];
 }
 
-export function getWorktreeTerminalSpecs(repoRoot: string): WorktreeTerminalConfig[] {
-  const terminals = readPaseoConfigOrThrow(repoRoot)?.worktree?.terminals;
+export async function getWorktreeTerminalSpecs(
+  repoRoot: string,
+): Promise<WorktreeTerminalConfig[]> {
+  const terminals = (await readPaseoConfigOrThrow(repoRoot))?.worktree?.terminals;
   if (!Array.isArray(terminals) || terminals.length === 0) {
     return [];
   }
@@ -607,7 +604,7 @@ async function assertPortAvailable(port: number): Promise<void> {
 async function inferRepoRootPathFromWorktreePath(worktreePath: string): Promise<string> {
   try {
     const commonDir = await getGitCommonDir(worktreePath);
-    const normalizedCommonDir = normalizePathForOwnership(commonDir);
+    const normalizedCommonDir = await normalizePathForOwnership(commonDir);
     // Normal repo/worktree: common dir is <repoRoot>/.git
     if (basename(normalizedCommonDir) === ".git") {
       return dirname(normalizedCommonDir);
@@ -623,12 +620,12 @@ async function inferRepoRootPathFromWorktreePath(worktreePath: string): Promise<
       });
       const topLevel = parseGitRevParsePath(stdout);
       if (topLevel) {
-        return normalizePathForOwnership(topLevel);
+        return await normalizePathForOwnership(topLevel);
       }
     } catch {
       // ignore
     }
-    return normalizePathForOwnership(worktreePath);
+    return await normalizePathForOwnership(worktreePath);
   }
 }
 
@@ -641,7 +638,7 @@ export async function runWorktreeSetupCommands(options: {
   onEvent?: (event: WorktreeSetupCommandProgressEvent) => void;
 }): Promise<WorktreeSetupCommandResult[]> {
   // Read paseo.json from the worktree (it will have the same content as the source repo)
-  const setupCommands = getWorktreeSetupCommands(options.worktreePath);
+  const setupCommands = await getWorktreeSetupCommands(options.worktreePath);
   if (setupCommands.length === 0) {
     return [];
   }
@@ -711,12 +708,12 @@ export async function resolveWorktreeRuntimeEnv(options: {
   const branchName =
     options.branchName ?? (await resolveBranchNameForWorktreePath(options.worktreePath));
 
-  let worktreePort = readPaseoWorktreeRuntimePort(options.worktreePath);
+  let worktreePort = await readPaseoWorktreeRuntimePort(options.worktreePath);
   if (worktreePort === null) {
     worktreePort = await getAvailablePort();
-    const metadata = readPaseoWorktreeMetadata(options.worktreePath);
+    const metadata = await readPaseoWorktreeMetadata(options.worktreePath);
     if (metadata) {
-      writePaseoWorktreeRuntimeMetadata(options.worktreePath, { worktreePort });
+      await writePaseoWorktreeRuntimeMetadata(options.worktreePath, { worktreePort });
     }
   } else {
     await assertPortAvailable(worktreePort);
@@ -742,10 +739,10 @@ export async function runWorktreeTeardownCommands(options: {
   repoRootPath?: string;
 }): Promise<WorktreeTeardownCommandResult[]> {
   const teardownCwd = options.teardownCwd ?? options.worktreePath;
-  if (getRealpathAwareRelativePath(options.worktreePath, teardownCwd) === null) {
+  if ((await getOwnershipRelativePath(options.worktreePath, teardownCwd)) === null) {
     throw new Error(`Worktree teardown cwd is outside the worktree: ${teardownCwd}`);
   }
-  const teardownCommands = getWorktreeTeardownCommands(teardownCwd);
+  const teardownCommands = await getWorktreeTeardownCommands(teardownCwd);
   if (teardownCommands.length === 0) {
     return [];
   }
@@ -754,7 +751,7 @@ export async function runWorktreeTeardownCommands(options: {
     options.repoRootPath ?? (await inferRepoRootPathFromWorktreePath(options.worktreePath));
   const branchName =
     options.branchName ?? (await resolveBranchNameForWorktreePath(options.worktreePath));
-  const worktreePort = readPaseoWorktreeRuntimePort(options.worktreePath);
+  const worktreePort = await readPaseoWorktreeRuntimePort(options.worktreePath);
 
   const teardownEnv: NodeJS.ProcessEnv = createStringCommandShellEnv(
     createExternalProcessEnv(process.env, {
@@ -831,12 +828,12 @@ function deriveShortAlphanumericHash(value: string): string {
 export async function deriveWorktreeProjectHash(cwd: string): Promise<string> {
   try {
     const commonDir = await getGitCommonDir(cwd);
-    const normalizedCommonDir = normalizePathForOwnership(commonDir);
+    const normalizedCommonDir = await normalizePathForOwnership(commonDir);
     const repoRoot =
       basename(normalizedCommonDir) === ".git" ? dirname(normalizedCommonDir) : normalizedCommonDir;
     return deriveShortAlphanumericHash(repoRoot);
   } catch {
-    return deriveShortAlphanumericHash(normalizePathForOwnership(cwd));
+    return deriveShortAlphanumericHash(await normalizePathForOwnership(cwd));
   }
 }
 
@@ -904,16 +901,46 @@ export function mapWorkspaceRelativeCwdToWorktree(input: {
   return mappedCwd;
 }
 
-function normalizePathForOwnership(input: string): string {
+// Keep the former realpathSync spelling on Windows: promises.realpath uses the
+// native resolver and can return an 8.3 alias instead of the long path.
+const resolveOwnershipPath = promisify(realpath);
+const resolveNativeOwnershipPath = promisify(realpath.native);
+const ownershipIdentityIo = pLimit(2);
+
+async function normalizePathForOwnership(input: string): Promise<string> {
   try {
-    return realpathSync(input);
+    return await ownershipIdentityIo(() => resolveOwnershipPath(input));
   } catch {
     return resolve(input);
   }
 }
 
-function resolveRepoRootFromGitCommonDir(commonDir: string): string {
-  const normalizedCommonDir = normalizePathForOwnership(commonDir);
+async function ownershipPathVariants(input: string): Promise<string[]> {
+  const variants = new Set([input, await normalizePathForOwnership(input)]);
+  try {
+    variants.add(await ownershipIdentityIo(() => resolveNativeOwnershipPath(input)));
+  } catch {
+    // Missing descendants still match a lexical or established root spelling.
+  }
+  return [...variants];
+}
+
+// Keep lexical variants for missing paths: archive must still recognize a removed
+// worktree below a symlinked worktrees root, whose full realpath no longer exists.
+async function getOwnershipRelativePath(root: string, candidate: string): Promise<string | null> {
+  const roots = await ownershipPathVariants(root);
+  const candidates = await ownershipPathVariants(candidate);
+  for (const rootPath of roots) {
+    for (const candidatePath of candidates) {
+      const relative = getRelativePathInsideRoot(rootPath, candidatePath);
+      if (relative !== null) return relative;
+    }
+  }
+  return null;
+}
+
+async function resolveRepoRootFromGitCommonDir(commonDir: string): Promise<string> {
+  const normalizedCommonDir = await normalizePathForOwnership(commonDir);
   return basename(normalizedCommonDir) === ".git"
     ? dirname(normalizedCommonDir)
     : normalizedCommonDir;
@@ -923,56 +950,93 @@ export async function isPaseoOwnedWorktreeCwd(
   cwd: string,
   options?: PaseoWorktreeOwnershipOptions,
 ): Promise<PaseoWorktreeOwnership> {
-  const resolvedCwd = normalizePathForOwnership(cwd);
+  const resolvedCwd = await normalizePathForOwnership(cwd);
 
   // repoRoot is best-effort: git may be unreachable from the worktree (e.g. a
   // previous archive attempt removed the admin dir before the working tree
   // could be fully cleaned up). We still want to allow archiving in that case.
   let repoRoot: string | undefined;
   if (options?.knownGitCommonDir) {
-    repoRoot = resolveRepoRootFromGitCommonDir(options.knownGitCommonDir);
+    repoRoot = await resolveRepoRootFromGitCommonDir(options.knownGitCommonDir);
   } else if (options?.knownGitCommonDir === undefined) {
     try {
       const gitCommonDir = await getGitCommonDir(cwd);
-      repoRoot = resolveRepoRootFromGitCommonDir(gitCommonDir);
+      repoRoot = await resolveRepoRootFromGitCommonDir(gitCommonDir);
     } catch {
       // ignore
     }
   }
 
+  // Worktrees placed at plugin-chosen paths are
+  // proven by the marker createWorktree writes unconditionally: a
+  // paseo/worktree.json in the worktree's git admin dir, with the path
+  // still registered in the repo's `git worktree list`. The marker alone
+  // is not proof — it lives in a git admin dir a user can copy into a
+  // hand-made directory that git does not know about.
+  if (options?.knownGitCommonDir !== null) {
+    const metadataProof = await resolveMetadataOwnedWorktree(cwd, repoRoot);
+    if (metadataProof) {
+      return {
+        allowed: true,
+        ...(repoRoot !== undefined ? { repoRoot } : {}),
+        worktreeRoot: metadataProof.worktreeRoot,
+        worktreePath: metadataProof.worktreePath,
+      };
+    }
+  }
+
   const worktreesBaseRoot = resolvePaseoWorktreesBaseRoot(options);
-  const relativePath = getRealpathAwareRelativePath(worktreesBaseRoot, resolvedCwd);
+  const relativePath = await getOwnershipRelativePath(worktreesBaseRoot, resolvedCwd);
 
   // Ownership is defined by the path living under <worktrees-root>/<hash>/<slug>[/...].
   // The <hash>/<slug> prefix is Paseo-private — nothing else writes there — so the
   // path shape alone is sufficient proof of ownership, even when git has already
   // forgotten about the worktree.
-  if (relativePath === null) {
-    return {
-      allowed: false,
-      ...(repoRoot !== undefined ? { repoRoot } : {}),
-      worktreePath: resolvedCwd,
-    };
+  if (relativePath !== null) {
+    const parts = relativePath.split(sep).filter((part) => part.length > 0);
+    if (parts.length >= 2) {
+      const worktreesRoot = join(worktreesBaseRoot, parts[0]);
+      return {
+        allowed: true,
+        ...(repoRoot !== undefined ? { repoRoot } : {}),
+        worktreeRoot: worktreesRoot,
+        worktreePath: join(worktreesRoot, parts[1]),
+      };
+    }
   }
 
-  const parts = relativePath.split(sep).filter((part) => part.length > 0);
-  if (parts.length < 2) {
-    return {
-      allowed: false,
-      ...(repoRoot !== undefined ? { repoRoot } : {}),
-      worktreePath: resolvedCwd,
-    };
-  }
-
-  const worktreesRoot = join(worktreesBaseRoot, parts[0]);
   return {
-    allowed: true,
+    allowed: false,
     ...(repoRoot !== undefined ? { repoRoot } : {}),
-    worktreeRoot: worktreesRoot,
-    worktreePath: join(worktreesRoot, parts[1]),
+    worktreePath: resolvedCwd,
   };
 }
 
+async function resolveMetadataOwnedWorktree(
+  cwd: string,
+  repoRoot: string | undefined,
+): Promise<{ worktreePath: string; worktreeRoot: string } | null> {
+  try {
+    const root = await findPaseoWorktreeRootForCwd(cwd);
+    if (!root) return null;
+    const candidate = await normalizePathForOwnership(root);
+    if (repoRoot !== undefined && candidate === (await normalizePathForOwnership(repoRoot)))
+      return null;
+    const { stdout: listOutput } = await runGitCommand(["worktree", "list", "--porcelain"], {
+      cwd: candidate,
+      envOverlay: READ_ONLY_GIT_ENV,
+    });
+    for (const entry of parseWorktreeList(listOutput)) {
+      if ((await normalizePathForOwnership(entry.path)) === candidate) {
+        return { worktreePath: candidate, worktreeRoot: dirname(candidate) };
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 type ParsedPaseoWorktreeInfo = Omit<PaseoWorktreeInfo, "createdAt">;
 
 function parseWorktreeList(output: string): ParsedPaseoWorktreeInfo[] {
@@ -1012,9 +1076,9 @@ function parseWorktreeList(output: string): ParsedPaseoWorktreeInfo[] {
   return entries;
 }
 
-function resolveWorktreeCreatedAtIso(worktreePath: string): string {
+async function resolveWorktreeCreatedAtIso(worktreePath: string): Promise<string> {
   try {
-    const stats = statSync(worktreePath);
+    const stats = await stat(worktreePath);
     const birthtimeMs = stats.birthtimeMs;
     const createdAtMs =
       Number.isFinite(birthtimeMs) && birthtimeMs > 0 ? birthtimeMs : stats.ctimeMs;
@@ -1039,12 +1103,20 @@ export async function listPaseoWorktrees({
     envOverlay: READ_ONLY_GIT_ENV,
   });
 
-  return parseWorktreeList(stdout)
-    .map((entry) => Object.assign({}, entry, { path: normalizePathForOwnership(entry.path) }))
-    .filter((entry) => getRealpathAwareRelativePath(projectWorktreesRoot, entry.path) !== null)
-    .map((entry) =>
-      Object.assign({}, entry, { createdAt: resolveWorktreeCreatedAtIso(entry.path) }),
-    );
+  const mainCheckoutPath = await resolveRepoRootFromGitCommonDir(await getGitCommonDir(cwd));
+  const roots = await ownershipPathVariants(projectWorktreesRoot);
+  const worktrees: PaseoWorktreeInfo[] = [];
+  // Inspect foreign paths sequentially; a large worktree list must not consume the FS pool.
+  for (const entry of parseWorktreeList(stdout)) {
+    const path = await normalizePathForOwnership(entry.path);
+    if (
+      !roots.some((root) => getRelativePathInsideRoot(root, path) !== null) &&
+      !(path !== mainCheckoutPath && (await hasPaseoWorktreeMetadata(path)))
+    )
+      continue;
+    worktrees.push({ ...entry, path, createdAt: await resolveWorktreeCreatedAtIso(path) });
+  }
+  return worktrees;
 }
 
 export interface DeletePaseoWorktreeOptions {
@@ -1055,6 +1127,30 @@ export interface DeletePaseoWorktreeOptions {
   worktreesRoot?: string;
   paseoHome?: string;
   worktreesBaseRoot?: string;
+  // The caller has a workspace registry record backing worktreePath (the
+  // record's cwd is this path). Registry membership is an ownership proof
+  // in its own right: it covers worktrees whose git admin dir is already
+  // gone, where the marker proof can no longer be verified. Only pass
+  // this when the record was matched against the path by the caller.
+  registryProven?: boolean;
+}
+
+// Project scoping for delete: a proof for some other repo's worktree must
+// not make this repo's delete remove it. Only refuses on a positive
+// mismatch — when git has forgotten either side, the ownership proof the
+// caller already established stands.
+async function assertWorktreeBelongsToRepo(cwd: string, worktreePath: string): Promise<void> {
+  let callerRepoRoot: string;
+  let targetRepoRoot: string;
+  try {
+    callerRepoRoot = await resolveRepoRootFromGitCommonDir(await getGitCommonDir(cwd));
+    targetRepoRoot = await resolveRepoRootFromGitCommonDir(await getGitCommonDir(worktreePath));
+  } catch {
+    return;
+  }
+  if ((await getOwnershipRelativePath(callerRepoRoot, targetRepoRoot)) !== "") {
+    throw new Error("Refusing to delete non-Paseo worktree");
+  }
 }
 
 export async function deletePaseoWorktree({
@@ -1065,6 +1161,7 @@ export async function deletePaseoWorktree({
   worktreesRoot,
   paseoHome,
   worktreesBaseRoot,
+  registryProven,
 }: DeletePaseoWorktreeOptions): Promise<void> {
   if (!worktreePath && !worktreeSlug) {
     throw new Error("worktreePath or worktreeSlug is required");
@@ -1083,22 +1180,27 @@ export async function deletePaseoWorktree({
   }
 
   const requestedPath = worktreePath ?? join(resolvedWorktreesRoot, worktreeSlug!);
-  const resolvedRequested = normalizePathForOwnership(requestedPath);
   const ownership = await isPaseoOwnedWorktreeCwd(requestedPath, {
     paseoHome,
     worktreesRoot: worktreesBaseRoot,
   });
-  const resolvedWorktree =
-    ownership.allowed && ownership.worktreePath ? ownership.worktreePath : resolvedRequested;
-
-  const relativeWorktreePath = getRealpathAwareRelativePath(
-    resolvedWorktreesRoot,
-    resolvedWorktree,
-  );
-  if (relativeWorktreePath === null || relativeWorktreePath === "") {
+  // Deletion is gated on the ownership proof set (legacy shape, the
+  // paseo/worktree.json marker verified against `git worktree list`, or a
+  // caller-asserted registry record), not on living under the per-project
+  // hashed root: plugin-placed worktrees live anywhere.
+  let resolvedWorktree: string;
+  if (registryProven) {
+    resolvedWorktree = await normalizePathForOwnership(requestedPath);
+  } else if (ownership.allowed && ownership.worktreePath) {
+    resolvedWorktree = ownership.worktreePath;
+  } else {
     throw new Error("Refusing to delete non-Paseo worktree");
   }
 
+  if (cwd) {
+    await assertWorktreeBelongsToRepo(cwd, resolvedWorktree);
+  }
+
   if (await pathExists(resolvedWorktree)) {
     for (const teardownCwd of teardownCwds ?? [resolvedWorktree]) {
       await runWorktreeTeardownCommands({
@@ -1195,6 +1297,67 @@ async function removeDirectoryWithRetries(path: string): Promise<void> {
   }
 }
 
+async function listLocalBranchNames(cwd: string): Promise<Set<string>> {
+  const { stdout } = await runGitCommand(
+    ["for-each-ref", "--format=%(refname:short)", "refs/heads"],
+    { cwd },
+  );
+  return new Set(
+    stdout
+      .split("\n")
+      .map((name) => name.trim())
+      .filter((name) => name.length > 0),
+  );
+}
+
+// The one local branch a source plan can create while resolving: a
+// checkout-branch plan fetches refs/heads/<source.branchName>, and a
+// change-request/PR plan fetches refs/heads/<localBranchName> (which is
+// the plan's branchName). branch-off creates no local branch. Only this
+// ref may be rolled back when creation fails — never any other
+// branch that appeared in the meantime; other creators own those.
+function planCreatedLocalBranch(
+  source: WorktreeSource,
+  sourcePlan: WorktreeSourcePlan,
+): string | null {
+  switch (source.kind) {
+    case "checkout-branch":
+      return source.branchName;
+    case "checkout-change-request":
+    case "checkout-github-pr":
+      return sourcePlan.branchName;
+    default:
+      return null;
+  }
+}
+
+async function readLocalBranchTip(cwd: string, branchName: string): Promise<string | null> {
+  try {
+    const { stdout } = await runGitCommand(
+      ["rev-parse", "--verify", `refs/heads/${branchName}^{commit}`],
+      { cwd },
+    );
+    const tip = stdout.trim();
+    return tip.length > 0 ? tip : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve the default placement once, before presenting it to creation hooks. */
+export async function resolveDefaultWorktreePath(
+  options: Pick<CreateWorktreeOptions, "cwd" | "paseoHome" | "worktreesRoot" | "worktreeSlug">,
+): Promise<string> {
+  const original = join(
+    await getPaseoWorktreesRoot(options.cwd, options.paseoHome, options.worktreesRoot),
+    options.worktreeSlug,
+  );
+  let candidate = original;
+  let suffix = 1;
+  while (await pathExists(candidate)) candidate = `${original}-${suffix++}`;
+  return candidate;
+}
+
 /**
  * Create a git worktree with proper naming conventions
  */
@@ -1204,56 +1367,73 @@ export const createWorktree = async ({
   worktreeSlug,
   paseoHome,
   worktreesRoot,
+  worktreePath: explicitWorktreePath,
 }: CreateWorktreeOptions): Promise<CreatedWorktree> => {
+  const branchesBefore =
+    source.kind === "checkout-branch" ||
+    source.kind === "checkout-change-request" ||
+    source.kind === "checkout-github-pr"
+      ? await listLocalBranchNames(cwd)
+      : new Set<string>();
   const sourcePlan = await resolveWorktreeSourcePlan({ cwd, source, desiredSlug: worktreeSlug });
-  let worktreePath = join(await getPaseoWorktreesRoot(cwd, paseoHome, worktreesRoot), worktreeSlug);
-  mkdirSync(dirname(worktreePath), { recursive: true });
+  const fetchedBranch = planCreatedLocalBranch(source, sourcePlan);
+  const fetchedTip =
+    fetchedBranch && !branchesBefore.has(fetchedBranch)
+      ? await readLocalBranchTip(cwd, fetchedBranch)
+      : null;
+  try {
+    let worktreePath =
+      explicitWorktreePath ??
+      (await resolveDefaultWorktreePath({ cwd, paseoHome, worktreesRoot, worktreeSlug }));
+    await mkdir(dirname(worktreePath), { recursive: true });
 
-  // Also handle worktree path collision
-  let finalWorktreePath = worktreePath;
-  let pathSuffix = 1;
-  while (existsSync(finalWorktreePath)) {
-    finalWorktreePath = `${worktreePath}-${pathSuffix}`;
-    pathSuffix++;
-  }
-
-  // Primitive owner for `git worktree add`; callers route through createWorktreeCore.
-  await runGitCommand(["worktree", "add", finalWorktreePath, ...sourcePlan.addArguments], {
-    cwd,
-    timeout: 120_000,
-  });
-  worktreePath = normalizePathForOwnership(finalWorktreePath);
-
-  if (sourcePlan.pushRemote) {
-    await configureWorktreePushRemote({
+    // Primitive owner for `git worktree add`; callers route through createWorktreeCore.
+    await runGitCommand(["worktree", "add", worktreePath, ...sourcePlan.addArguments], {
       cwd,
-      branchName: sourcePlan.branchName,
-      remote: sourcePlan.pushRemote,
+      timeout: 120_000,
     });
-  }
-  if (sourcePlan.trackingRemote) {
-    await configureWorktreeTrackingRemote({
-      cwd,
-      branchName: sourcePlan.branchName,
-      remote: sourcePlan.trackingRemote,
+    worktreePath = await normalizePathForOwnership(worktreePath);
+
+    if (sourcePlan.pushRemote) {
+      await configureWorktreePushRemote({
+        cwd,
+        branchName: sourcePlan.branchName,
+        remote: sourcePlan.pushRemote,
+      });
+    }
+    if (sourcePlan.trackingRemote) {
+      await configureWorktreeTrackingRemote({
+        cwd,
+        branchName: sourcePlan.branchName,
+        remote: sourcePlan.trackingRemote,
+      });
+    }
+
+    await writePaseoWorktreeMetadata(worktreePath, {
+      baseRefName: sourcePlan.metadataBaseRefName,
+      ...(sourcePlan.metadataBaseRef ? { baseRef: sourcePlan.metadataBaseRef } : {}),
+      ...(sourcePlan.changeRequestLookupTarget
+        ? { changeRequestLookupTarget: sourcePlan.changeRequestLookupTarget }
+        : {}),
     });
+
+    await seedPaseoConfigFile({ sourceCwd: cwd, targetCwd: worktreePath });
+
+    return {
+      branchName: sourcePlan.branchName,
+      worktreePath,
+      comparisonBaseRef: sourcePlan.metadataBaseRef ?? sourcePlan.metadataBaseRefName,
+    };
+  } catch (error) {
+    if (
+      fetchedBranch &&
+      fetchedTip &&
+      (await readLocalBranchTip(cwd, fetchedBranch)) === fetchedTip
+    ) {
+      await runGitCommand(["branch", "-D", fetchedBranch], { cwd }).catch(() => {});
+    }
+    throw error;
   }
-
-  writePaseoWorktreeMetadata(worktreePath, {
-    baseRefName: sourcePlan.metadataBaseRefName,
-    ...(sourcePlan.metadataBaseRef ? { baseRef: sourcePlan.metadataBaseRef } : {}),
-    ...(sourcePlan.changeRequestLookupTarget
-      ? { changeRequestLookupTarget: sourcePlan.changeRequestLookupTarget }
-      : {}),
-  });
-
-  await seedPaseoConfigFile({ sourceCwd: cwd, targetCwd: worktreePath });
-
-  return {
-    branchName: sourcePlan.branchName,
-    worktreePath,
-    comparisonBaseRef: sourcePlan.metadataBaseRef ?? sourcePlan.metadataBaseRefName,
-  };
 };
 
 interface ResolveWorktreeSourcePlanOptions {
diff --git a/packages/server/tsconfig.scripts.json b/packages/server/tsconfig.scripts.json
index cc8e24efd4..6a75825b00 100644
--- a/packages/server/tsconfig.scripts.json
+++ b/packages/server/tsconfig.scripts.json
@@ -19,6 +19,11 @@
     "declaration": false,
     "sourceMap": true
   },
-  "include": ["scripts/supervisor-entrypoint.ts", "scripts/dev-runner.ts", "scripts/supervisor.ts"],
+  "include": [
+    "scripts/supervisor-entrypoint.ts",
+    "scripts/dev-runner.ts",
+    "scripts/supervisor.ts",
+    "src/executable-resolution/which.d.ts"
+  ],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/packages/server/tsconfig.server.json b/packages/server/tsconfig.server.json
index 9c868b42df..1c7a5c3579 100644
--- a/packages/server/tsconfig.server.json
+++ b/packages/server/tsconfig.server.json
@@ -22,7 +22,12 @@
     "declarationMap": true,
     "sourceMap": true
   },
-  "include": ["src/server/**/*", "src/services/**/*", "src/terminal/**/*"],
+  "include": [
+    "src/server/**/*",
+    "src/services/**/*",
+    "src/terminal/**/*",
+    "src/executable-resolution/which.d.ts"
+  ],
   "exclude": [
     "node_modules",
     "dist",
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/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..02d17e92cb 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();
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..27d4a55c4a 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" };
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 2166f1a22e..b13fa5254a 100644
--- a/packages/website/package.json
+++ b/packages/website/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/website",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "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 c1c32ed20a..bae380d4c8 100644
--- a/packages/website/public/schemas/paseo.config.v1.json
+++ b/packages/website/public/schemas/paseo.config.v1.json
@@ -70,6 +70,14 @@
           },
           "additionalProperties": {}
         },
+        "usage": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            }
+          }
+        },
         "browserTools": {
           "type": "object",
           "properties": {
@@ -513,6 +521,12 @@
         "idleRuntimeCleanup": {
           "type": "boolean"
         },
+        "resumeOnStartup": {
+          "type": "boolean"
+        },
+        "resumePrompt": {
+          "type": "string"
+        },
         "catalogRefreshTimeoutMs": {
           "type": "integer",
           "exclusiveMinimum": 0,
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/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..3365a9fffa 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",
diff --git a/packages/website/src/i18n/resources/zh-CN.json b/packages/website/src/i18n/resources/zh-CN.json
index 048d351e4d..2cb1cf4f3f 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": "历史",
diff --git a/packages/website/src/plugin-docs-navigation.test.ts b/packages/website/src/plugin-docs-navigation.test.ts
index 0aeed8ff88..a3e537620a 100644
--- a/packages/website/src/plugin-docs-navigation.test.ts
+++ b/packages/website/src/plugin-docs-navigation.test.ts
@@ -1,7 +1,26 @@
 import { describe, expect, it } from "vitest";
-import { buildDocsNavTree, getDoc, getDocs, getLegacyDocsRedirect } from "./docs";
+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",
@@ -14,11 +33,20 @@ describe("plugin documentation", () => {
         { type: "page", label: "Publishing", href: "/docs/plugins/publishing" },
         { type: "page", label: "Provider plugins", href: "/docs/plugins/providers" },
         { type: "page", label: "Migration", href: "/docs/plugins/migration" },
+        { type: "page", label: "Hooks", href: "/docs/plugins/hooks" },
         { type: "page", label: "Reference", href: "/docs/plugins/reference" },
       ],
     });
   });
 
+  it.each(["en", "zh-CN"] as const)("resolves worktree placement hook links in %s", (locale) => {
+    const hooks = getDoc("plugins/hooks", locale)!;
+    expect(parseHeadings(hooks.content).map((heading) => heading.id)).toContain(
+      "worktreecreatebefore",
+    );
+    expect(hooks.content).toContain("plugin-examples/worktree-placement");
+  });
+
   it.each(["v0.7", "v0.8"])("redirects %s links to existing current pages", (version) => {
     for (const page of ["", "/index", "/reference", "/providers", "/migration"]) {
       const target = `/docs/plugins${page === "/index" ? "" : page}`;
@@ -32,7 +60,7 @@ describe("plugin documentation", () => {
   });
 
   it("serves canonical pages without redirect loops", () => {
-    for (const page of ["", "/publishing", "/reference", "/providers", "/migration"]) {
+    for (const page of ["", "/publishing", "/reference", "/providers", "/migration", "/hooks"]) {
       expect(getLegacyDocsRedirect(`/docs/plugins${page}`)).toBeUndefined();
       expect(getLegacyDocsRedirect(`/docs/plugins${page}.md`)).toBeUndefined();
     }
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/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/@legendapp+list+3.7.1.patch b/patches/@legendapp+list+3.7.1.patch
new file mode 100644
index 0000000000..b232494bf5
--- /dev/null
+++ b/patches/@legendapp+list+3.7.1.patch
@@ -0,0 +1,575 @@
+# 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 (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.
+# 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.
+#
+# 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..5fe940d 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++) {
+@@ -2371,7 +2394,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 +2541,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 +3405,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 +4597,17 @@ 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);
++      }
++    }
+   }
+   return idsInView;
+ }
+@@ -5176,8 +5215,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 +5335,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 +5463,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 +6332,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 +6343,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 +6566,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 +6712,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 +6726,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 +7947,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 +8053,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+     estimatedListSize,
+     extraData,
+     getFixedItemSize,
++    getEstimatedItemSize,
+     getItemType,
+     horizontal,
+     rtl,
+@@ -8282,6 +8347,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..7f1b9dd 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++) {
+@@ -2350,7 +2373,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 +2520,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 +3384,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 +4576,17 @@ 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);
++      }
++    }
+   }
+   return idsInView;
+ }
+@@ -5155,8 +5194,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 +5314,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 +5442,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 +6311,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 +6322,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 +6545,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 +6691,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 +6705,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 +7926,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 +8032,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+     estimatedListSize,
+     extraData,
+     getFixedItemSize,
++    getEstimatedItemSize,
+     getItemType,
+     horizontal,
+     rtl,
+@@ -8261,6 +8326,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 7ec1ec33b5..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),
@@ -3770,3 +3798,201 @@ index eaa3279..05a02eb 100644
  private:
    int forceHeightRecalculationCounter_{0};
    std::shared_ptr<MarkdownTextMeasurementManager> measurementsManager_;
+diff --git a/node_modules/react-native-enriched-markdown/ios/generated/ReactCodegen/EnrichedMarkdownTextSpec/Props.h b/node_modules/react-native-enriched-markdown/ios/generated/ReactCodegen/EnrichedMarkdownTextSpec/Props.h
+--- a/node_modules/react-native-enriched-markdown/ios/generated/ReactCodegen/EnrichedMarkdownTextSpec/Props.h
++++ b/node_modules/react-native-enriched-markdown/ios/generated/ReactCodegen/EnrichedMarkdownTextSpec/Props.h
+@@ -1639,6 +1639,7 @@
+ struct EnrichedMarkdownMarkdownStyleCodeStruct {
+   std::string fontFamily{};
+   Float fontSize{0.0};
++  Float fontScale{0.0};
+   SharedColor color{};
+   SharedColor backgroundColor{};
+   SharedColor borderColor{};
+@@ -1651,6 +1652,7 @@
+     folly::dynamic result = folly::dynamic::object();
+     result["fontFamily"] = fontFamily;
+     result["fontSize"] = fontSize;
++    result["fontScale"] = fontScale;
+     result["color"] = ::facebook::react::toDynamic(color);
+     result["backgroundColor"] = ::facebook::react::toDynamic(backgroundColor);
+     result["borderColor"] = ::facebook::react::toDynamic(borderColor);
+@@ -1670,6 +1672,10 @@
+   if (tmp_fontSize != map.end()) {
+     fromRawValue(context, tmp_fontSize->second, result.fontSize);
+   }
++  auto tmp_fontScale = map.find("fontScale");
++  if (tmp_fontScale != map.end()) {
++    fromRawValue(context, tmp_fontScale->second, result.fontScale);
++  }
+   auto tmp_color = map.find("color");
+   if (tmp_color != map.end()) {
+     fromRawValue(context, tmp_color->second, result.color);
+@@ -6185,6 +6191,7 @@
+ struct EnrichedMarkdownTextMarkdownStyleCodeStruct {
+   std::string fontFamily{};
+   Float fontSize{0.0};
++  Float fontScale{0.0};
+   SharedColor color{};
+   SharedColor backgroundColor{};
+   SharedColor borderColor{};
+@@ -6197,6 +6204,7 @@
+     folly::dynamic result = folly::dynamic::object();
+     result["fontFamily"] = fontFamily;
+     result["fontSize"] = fontSize;
++    result["fontScale"] = fontScale;
+     result["color"] = ::facebook::react::toDynamic(color);
+     result["backgroundColor"] = ::facebook::react::toDynamic(backgroundColor);
+     result["borderColor"] = ::facebook::react::toDynamic(borderColor);
+@@ -6216,6 +6224,10 @@
+   if (tmp_fontSize != map.end()) {
+     fromRawValue(context, tmp_fontSize->second, result.fontSize);
+   }
++  auto tmp_fontScale = map.find("fontScale");
++  if (tmp_fontScale != map.end()) {
++    fromRawValue(context, tmp_fontScale->second, result.fontScale);
++  }
+   auto tmp_color = map.find("color");
+   if (tmp_color != map.end()) {
+     fromRawValue(context, tmp_color->second, result.color);
+diff --git a/node_modules/react-native-enriched-markdown/android/generated/jni/react/renderer/components/EnrichedMarkdownTextSpec/Props.h b/node_modules/react-native-enriched-markdown/android/generated/jni/react/renderer/components/EnrichedMarkdownTextSpec/Props.h
+--- a/node_modules/react-native-enriched-markdown/android/generated/jni/react/renderer/components/EnrichedMarkdownTextSpec/Props.h
++++ b/node_modules/react-native-enriched-markdown/android/generated/jni/react/renderer/components/EnrichedMarkdownTextSpec/Props.h
+@@ -1639,6 +1639,7 @@
+ struct EnrichedMarkdownMarkdownStyleCodeStruct {
+   std::string fontFamily{};
+   Float fontSize{0.0};
++  Float fontScale{0.0};
+   SharedColor color{};
+   SharedColor backgroundColor{};
+   SharedColor borderColor{};
+@@ -1651,6 +1652,7 @@
+     folly::dynamic result = folly::dynamic::object();
+     result["fontFamily"] = fontFamily;
+     result["fontSize"] = fontSize;
++    result["fontScale"] = fontScale;
+     result["color"] = ::facebook::react::toDynamic(color);
+     result["backgroundColor"] = ::facebook::react::toDynamic(backgroundColor);
+     result["borderColor"] = ::facebook::react::toDynamic(borderColor);
+@@ -1669,6 +1671,10 @@
+   auto tmp_fontSize = map.find("fontSize");
+   if (tmp_fontSize != map.end()) {
+     fromRawValue(context, tmp_fontSize->second, result.fontSize);
++  }
++  auto tmp_fontScale = map.find("fontScale");
++  if (tmp_fontScale != map.end()) {
++    fromRawValue(context, tmp_fontScale->second, result.fontScale);
+   }
+   auto tmp_color = map.find("color");
+   if (tmp_color != map.end()) {
+@@ -6185,6 +6191,7 @@
+ struct EnrichedMarkdownTextMarkdownStyleCodeStruct {
+   std::string fontFamily{};
+   Float fontSize{0.0};
++  Float fontScale{0.0};
+   SharedColor color{};
+   SharedColor backgroundColor{};
+   SharedColor borderColor{};
+@@ -6197,6 +6204,7 @@
+     folly::dynamic result = folly::dynamic::object();
+     result["fontFamily"] = fontFamily;
+     result["fontSize"] = fontSize;
++    result["fontScale"] = fontScale;
+     result["color"] = ::facebook::react::toDynamic(color);
+     result["backgroundColor"] = ::facebook::react::toDynamic(backgroundColor);
+     result["borderColor"] = ::facebook::react::toDynamic(borderColor);
+@@ -6215,6 +6223,10 @@
+   auto tmp_fontSize = map.find("fontSize");
+   if (tmp_fontSize != map.end()) {
+     fromRawValue(context, tmp_fontSize->second, result.fontSize);
++  }
++  auto tmp_fontScale = map.find("fontScale");
++  if (tmp_fontScale != map.end()) {
++    fromRawValue(context, tmp_fontScale->second, result.fontScale);
+   }
+   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 7f40053f19..c3da63a8ac 100644
--- a/patches/react-native-unistyles+3.2.4.patch
+++ b/patches/react-native-unistyles+3.2.4.patch
@@ -486,3 +486,278 @@ diff --git a/node_modules/react-native-unistyles/lib/commonjs/core/withUnistyles
        ...(narrowedProps.style ? {
          style: styleSecrets.styles
        } : {}),
+diff --git a/node_modules/react-native-unistyles/lib/commonjs/web/runtime.js b/node_modules/react-native-unistyles/lib/commonjs/web/runtime.js
+index 305fa49..5957aa5 100644
+--- a/node_modules/react-native-unistyles/lib/commonjs/web/runtime.js
++++ b/node_modules/react-native-unistyles/lib/commonjs/web/runtime.js
+@@ -35,10 +35,17 @@ class UnistylesRuntime {
+     return this.darkMedia;
+   }
+   get colorScheme() {
++    // Read the scheme through fresh lists, never through lightMedia/darkMedia. Chromium defers
++    // MediaQueryList change events while the document is hidden and drops the pending event
++    // of any list whose `matches` was read before the document became visible again, which
++    // would silence the adaptive-theme listeners registered on those two lists.
++    if ((0, _utils.isServer)()) {
++      return _types.ColorScheme.Unspecified;
++    }
+     switch (true) {
+-      case this.getLightMedia()?.matches:
++      case window.matchMedia('(prefers-color-scheme: light)').matches:
+         return _types.ColorScheme.Light;
+-      case this.getDarkMedia()?.matches:
++      case window.matchMedia('(prefers-color-scheme: dark)').matches:
+         return _types.ColorScheme.Dark;
+       default:
+         return _types.ColorScheme.Unspecified;
+diff --git a/node_modules/react-native-unistyles/lib/module/web/runtime.js b/node_modules/react-native-unistyles/lib/module/web/runtime.js
+index 7f13a06..c487bee 100644
+--- a/node_modules/react-native-unistyles/lib/module/web/runtime.js
++++ b/node_modules/react-native-unistyles/lib/module/web/runtime.js
+@@ -31,10 +31,17 @@ export class UnistylesRuntime {
+     return this.darkMedia;
+   }
+   get colorScheme() {
++    // Read the scheme through fresh lists, never through lightMedia/darkMedia. Chromium defers
++    // MediaQueryList change events while the document is hidden and drops the pending event
++    // of any list whose `matches` was read before the document became visible again, which
++    // would silence the adaptive-theme listeners registered on those two lists.
++    if (isServer()) {
++      return ColorScheme.Unspecified;
++    }
+     switch (true) {
+-      case this.getLightMedia()?.matches:
++      case window.matchMedia('(prefers-color-scheme: light)').matches:
+         return ColorScheme.Light;
+-      case this.getDarkMedia()?.matches:
++      case window.matchMedia('(prefers-color-scheme: dark)').matches:
+         return ColorScheme.Dark;
+       default:
+         return ColorScheme.Unspecified;
+diff --git a/node_modules/react-native-unistyles/src/web/runtime.ts b/node_modules/react-native-unistyles/src/web/runtime.ts
+index a16dac0..6519858 100644
+--- a/node_modules/react-native-unistyles/src/web/runtime.ts
++++ b/node_modules/react-native-unistyles/src/web/runtime.ts
+@@ -41,8 +41,16 @@ export class UnistylesRuntime {
+     get colorScheme() {
++        // Read the scheme through fresh lists, never through lightMedia/darkMedia. Chromium defers
++        // MediaQueryList change events while the document is hidden and drops the pending event
++        // of any list whose `matches` was read before the document became visible again, which
++        // would silence the adaptive-theme listeners registered on those two lists.
++        if (isServer()) {
++            return ColorScheme.Unspecified
++        }
++
+         switch (true) {
+-            case this.getLightMedia()?.matches:
++            case window.matchMedia('(prefers-color-scheme: light)').matches:
+                 return ColorScheme.Light
+-            case this.getDarkMedia()?.matches:
++            case window.matchMedia('(prefers-color-scheme: dark)').matches:
+                 return ColorScheme.Dark
+             default:
+                 return ColorScheme.Unspecified
+diff --git a/node_modules/react-native-unistyles/android/src/main/java/com/unistyles/NativePlatform+android.kt b/node_modules/react-native-unistyles/android/src/main/java/com/unistyles/NativePlatform+android.kt
+index 0f8d1f0..154a12a 100644
+--- a/node_modules/react-native-unistyles/android/src/main/java/com/unistyles/NativePlatform+android.kt
++++ b/node_modules/react-native-unistyles/android/src/main/java/com/unistyles/NativePlatform+android.kt
+@@ -3,11 +3,16 @@ package com.unistyles
+ import android.os.Build
+ import android.content.Context
+ import android.content.res.Configuration
++import android.content.res.Resources
++import android.os.Handler
++import android.os.Looper
+ import android.util.DisplayMetrics
+ import android.view.View
+ import android.view.WindowManager
+ import androidx.annotation.Keep
++import androidx.core.content.OnConfigurationChangedProvider
+ import androidx.core.text.TextUtilsCompat
++import androidx.core.util.Consumer
+ import androidx.core.view.ViewCompat
+ import androidx.core.view.WindowCompat
+ import androidx.core.view.WindowInsetsCompat
+@@ -22,6 +27,7 @@ import com.margelo.nitro.unistyles.Insets
+ import com.margelo.nitro.unistyles.Orientation
+ import com.margelo.nitro.unistyles.UnistyleDependency
+ import com.margelo.nitro.unistyles.UnistylesNativeMiniRuntime
++import java.lang.ref.WeakReference
+ import java.util.Locale
+ 
+ @Keep
+@@ -30,6 +36,14 @@ class NativePlatformAndroid(private val reactContext: ReactApplicationContext):
+     private val _insets = NativePlatformInsets(reactContext, this::getMiniRuntime) { this.onConfigChange() }
+     private var _miniRuntime: UnistylesNativeMiniRuntime = buildMiniRuntime()
+     private val _listener = NativePlatformListener(reactContext, this::getMiniRuntime) { this.diffMiniRuntime() }
++    private var _configurationProvider: WeakReference<OnConfigurationChangedProvider>? = null
++    private val _activityConfigurationListener = Consumer<Configuration> {
++        Handler(Looper.getMainLooper()).post { this.onConfigChange() }
++    }
++
++    // Application resources can lag behind configuration changes
++    private val configurationResources: Resources
++        get() = reactContext.currentActivity?.resources ?: reactContext.resources
+ 
+     init {
+         checkEdgeToEdge()
+@@ -37,12 +51,16 @@ class NativePlatformAndroid(private val reactContext: ReactApplicationContext):
+     }
+ 
+     fun onDestroy() {
++        stopObservingActivityConfiguration()
+         _listener.onDestroy()
+         _insets.onDestroy()
+         reactContext.removeLifecycleEventListener(this)
+     }
+ 
+     override fun onHostResume() {
++        observeActivityConfiguration()
++        // catch configuration changes missed while no Activity was attached
++        onConfigChange()
+         _insets.getInitialInsets(false)
+         _insets.startInsetsListener()
+     }
+@@ -51,7 +69,26 @@ class NativePlatformAndroid(private val reactContext: ReactApplicationContext):
+         _insets.stopInsetsListener()
+     }
+ 
+-    override fun onHostDestroy() {}
++    override fun onHostDestroy() {
++        stopObservingActivityConfiguration()
++    }
++
++    private fun observeActivityConfiguration() {
++        val provider = reactContext.currentActivity as? OnConfigurationChangedProvider
++
++        if (_configurationProvider?.get() === provider) {
++            return
++        }
++
++        stopObservingActivityConfiguration()
++        provider?.addOnConfigurationChangedListener(_activityConfigurationListener)
++        _configurationProvider = provider?.let { WeakReference(it) }
++    }
++
++    private fun stopObservingActivityConfiguration() {
++        _configurationProvider?.get()?.removeOnConfigurationChangedListener(_activityConfigurationListener)
++        _configurationProvider = null
++    }
+ 
+     override val memorySize: Long
+         get() = 0
+@@ -61,7 +98,7 @@ class NativePlatformAndroid(private val reactContext: ReactApplicationContext):
+     }
+ 
+     override fun getColorScheme(): ColorScheme {
+-        val uiMode = reactContext.resources.configuration.uiMode
++        val uiMode = configurationResources.configuration.uiMode
+ 
+         val colorScheme = when (uiMode.and(Configuration.UI_MODE_NIGHT_MASK)) {
+             Configuration.UI_MODE_NIGHT_YES -> ColorScheme.DARK
+@@ -73,15 +110,15 @@ class NativePlatformAndroid(private val reactContext: ReactApplicationContext):
+     }
+ 
+     override fun getFontScale(): Double {
+-        return reactContext.resources.configuration.fontScale.toDouble()
++        return configurationResources.configuration.fontScale.toDouble()
+     }
+ 
+     override fun getPixelRatio(): Double {
+-        return reactContext.resources.displayMetrics.density.toDouble()
++        return configurationResources.displayMetrics.density.toDouble()
+     }
+ 
+     override fun getOrientation(): Orientation {
+-        val orientation = when (reactContext.resources.configuration.orientation) {
++        val orientation = when (configurationResources.configuration.orientation) {
+             Configuration.ORIENTATION_PORTRAIT -> Orientation.PORTRAIT
+             Configuration.ORIENTATION_LANDSCAPE -> Orientation.LANDSCAPE
+             else -> Orientation.PORTRAIT
+@@ -122,7 +159,7 @@ class NativePlatformAndroid(private val reactContext: ReactApplicationContext):
+                 return Dimensions(screenWidth, screenHeight)
+             }
+             else -> {
+-                val displayMetrics = reactContext.resources.displayMetrics
++                val displayMetrics = configurationResources.displayMetrics
+ 
+                 reactContext.currentActivity?.windowManager?.currentWindowMetrics?.bounds?.let {
+                     val boundsWidth = (it.width() / displayMetrics.density).toDouble()
+@@ -157,7 +194,7 @@ class NativePlatformAndroid(private val reactContext: ReactApplicationContext):
+             "com.facebook.react.modules.i18nmanager.I18nUtil",
+             Context.MODE_PRIVATE
+         )
+-        val resourcesLocale = reactContext.resources.configuration.locales[0]
++        val resourcesLocale = configurationResources.configuration.locales[0]
+         val hasForcedRtl = sharedPrefs.getBoolean("RCTI18nUtil_forceRTL", false)
+         // user preferences
+         val isRtl = TextUtilsCompat.getLayoutDirectionFromLocale(Locale.getDefault()) == ViewCompat.LAYOUT_DIRECTION_RTL
+diff --git a/node_modules/react-native-unistyles/android/src/main/java/com/unistyles/NativePlatform+insets.kt b/node_modules/react-native-unistyles/android/src/main/java/com/unistyles/NativePlatform+insets.kt
+index a9c1804..f5a3c20 100644
+--- a/node_modules/react-native-unistyles/android/src/main/java/com/unistyles/NativePlatform+insets.kt
++++ b/node_modules/react-native-unistyles/android/src/main/java/com/unistyles/NativePlatform+insets.kt
+@@ -38,7 +38,7 @@ class NativePlatformInsets(
+     }
+ 
+     fun getInsets(): Insets {
+-        val density = reactContext.resources.displayMetrics.density
++        val density = (reactContext.currentActivity?.resources ?: reactContext.resources).displayMetrics.density
+ 
+         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/agent-configuration/README.md b/plugin-examples/agent-configuration/README.md
index 189afe6cfd..cb191bd3e1 100644
--- a/plugin-examples/agent-configuration/README.md
+++ b/plugin-examples/agent-configuration/README.md
@@ -1,14 +1,19 @@
 # Agent configuration
 
-Changes new Codex agents through `server.before("agent.create", ...)`:
+Sets saved Codex options through `server.addHook("agent.create.before", async ...)`:
 
 - Sets `config.providerOptions.sandbox_mode` to `workspace-write`.
 - Sets `config.providerOptions.approval_policy` to `on-request`.
-- Adds the `company` server to `config.mcpServers`.
-- Preserves other configuration, provider options, MCP servers, and environment overrides.
+- Preserves other configuration and provider options.
+
+Adds the `company` MCP server to Codex launches through
+`server.addHook("agent.open.before", async ...)`. The server is never saved in the agent's configuration;
+existing saved MCP servers are preserved. Existing agents receive the server through the
+[session reopen behavior](../../public-docs/plugins/hooks.md#attach-tools-to-agents).
 
 Replace `https://tools.example.com/mcp` in `index.server.ts` with your MCP server URL before using
-this example. The URL is a placeholder. The `company` entry replaces an existing server with that name.
+this example. A `company` name collision with a saved server or another
+plugin fails the session open and names both sources.
 
 Install on a daemon with plugins enabled:
 
@@ -16,11 +21,13 @@ Install on a daemon with plugins enabled:
 paseo plugin install /absolute/path/to/plugin-examples/agent-configuration
 ```
 
-The callback receives the request after earlier plugins have transformed it. The nested spreads
-preserve their settings; the explicit values replace only the named fields. Paseo validates and saves
-the resulting configuration before starting the agent. Existing agents are unchanged.
+Each session-open callback receives only this plugin's MCP servers. The nested spreads preserve
+entries added by this plugin's earlier callbacks. The create callback receives configuration after
+earlier plugins have transformed it; its explicit Codex options replace the named fields in the
+saved configuration of new agents and remain after this plugin is disabled.
 
-See the [lifecycle reference](../../public-docs/plugins/reference.md#lifecycle-hooks) for ordering
-and callback shapes. [Lifecycle actions](../lifecycle-actions) demonstrates provider switching and
-environment injection. Its provider-switch callback clears provider options when changing Codex to
-Claude, so use these examples separately when trying the Codex-specific settings.
+See [Inject MCP servers](../../public-docs/plugins/hooks.md#inject-mcp-servers) for choosing
+between saved configuration and plugin-owned servers. [Lifecycle actions](../lifecycle-actions)
+demonstrates provider switching and environment injection. Its provider-switch callback clears
+provider options when changing Codex to Claude, so use these examples separately when trying the
+Codex-specific settings.
diff --git a/plugin-examples/agent-configuration/index.server.ts b/plugin-examples/agent-configuration/index.server.ts
index 1f86e63a67..cfb236caa1 100644
--- a/plugin-examples/agent-configuration/index.server.ts
+++ b/plugin-examples/agent-configuration/index.server.ts
@@ -1,7 +1,7 @@
 import type { PluginServerContext } from "@getpaseo/plugin/server";
 
 export default function contribute(server: PluginServerContext) {
-  server.before("agent.create", ({ request }) => {
+  server.addHook("agent.create.before", async ({ request }) => {
     if (request.config.provider !== "codex") {
       return request;
     }
@@ -15,12 +15,22 @@ export default function contribute(server: PluginServerContext) {
           sandbox_mode: "workspace-write",
           approval_policy: "on-request",
         },
-        mcpServers: {
-          ...request.config.mcpServers,
-          company: {
-            type: "http",
-            url: "https://tools.example.com/mcp",
-          },
+      },
+    };
+  });
+
+  server.addHook("agent.open.before", async ({ request }) => {
+    if (request.provider !== "codex") {
+      return;
+    }
+
+    return {
+      ...request,
+      mcpServers: {
+        ...request.mcpServers,
+        company: {
+          type: "http",
+          url: "https://tools.example.com/mcp",
         },
       },
     };
diff --git a/plugin-examples/agent-configuration/paseo-plugin.json b/plugin-examples/agent-configuration/paseo-plugin.json
index 1a049eda62..98e1460c12 100644
--- a/plugin-examples/agent-configuration/paseo-plugin.json
+++ b/plugin-examples/agent-configuration/paseo-plugin.json
@@ -1,6 +1,6 @@
 {
   "id": "agent-configuration",
   "requirements": {
-    "paseo": ">=0.8.0"
+    "paseo": ">=0.14.0-beta.1"
   }
 }
diff --git a/plugin-examples/agent-tools/README.md b/plugin-examples/agent-tools/README.md
new file mode 100644
index 0000000000..e8674a9d66
--- /dev/null
+++ b/plugin-examples/agent-tools/README.md
@@ -0,0 +1,33 @@
+# Agent tools
+
+Attaches `append_workspace_note` to agents whose `notes/enabled` label is `"true"`.
+Calling the tool with `{ "note": "Run the targeted tests before committing." }` appends that
+line to `AGENT_NOTES.md` in the calling agent's working directory and returns the file path.
+It creates the file if it does not exist.
+
+Install on a daemon with plugins enabled:
+
+```bash
+paseo plugin install /absolute/path/to/plugin-examples/agent-tools
+```
+
+Create a labeled agent through the SDK:
+
+```ts
+const agent = await paseo.agents.create({
+  config: { provider: "codex/gpt-5.4" },
+  cwd: "/projects/shop",
+  labels: { "notes/enabled": "true" },
+});
+```
+
+The session-open callback also runs when an agent resumes or reloads. After changing an existing
+agent's labels, call `paseo.agents.ref(id).reload()` to apply the selection immediately. This
+interrupts a running turn. `refresh()` reads the agent snapshot without reopening its session.
+
+From the repository root, `npm run typecheck` includes this example. Outside this repository,
+use `paseo plugin init` to create the package and TypeScript setup, then copy `index.server.ts`
+and the manifest into that project.
+
+See [Attach tools to agents](../../public-docs/plugins/hooks.md#attach-tools-to-agents)
+for targeting, execution, provider gates, collisions, and plugin reload behavior.
diff --git a/plugin-examples/agent-tools/index.server.ts b/plugin-examples/agent-tools/index.server.ts
new file mode 100644
index 0000000000..1bede92569
--- /dev/null
+++ b/plugin-examples/agent-tools/index.server.ts
@@ -0,0 +1,26 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { defineAgentTool, type PluginServerContext } from "@getpaseo/plugin/server";
+
+const appendWorkspaceNote = defineAgentTool({
+  name: "append_workspace_note",
+  description: "Append a note to AGENT_NOTES.md in this agent's working directory.",
+  input: z.object({ note: z.string().min(1).describe("Note to append") }),
+  async execute({ note }, { agent, signal }) {
+    const notePath = path.join(agent.cwd, "AGENT_NOTES.md");
+    await writeFile(notePath, `${note}\n`, { encoding: "utf8", flag: "a", signal });
+    return {
+      text: `Saved note to ${notePath}`,
+      structuredContent: { path: notePath },
+    };
+  },
+});
+
+export default function contribute(server: PluginServerContext) {
+  server.addHook("agent.open.before", async ({ request }) => {
+    if (request.labels["notes/enabled"] !== "true") return;
+    return { ...request, tools: [...request.tools, appendWorkspaceNote] };
+  });
+  return () => {};
+}
diff --git a/plugin-examples/agent-tools/paseo-plugin.json b/plugin-examples/agent-tools/paseo-plugin.json
new file mode 100644
index 0000000000..e67c53f072
--- /dev/null
+++ b/plugin-examples/agent-tools/paseo-plugin.json
@@ -0,0 +1,4 @@
+{
+  "id": "agent-tools",
+  "requirements": { "paseo": ">=0.14.0-beta.1" }
+}
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/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/lifecycle-actions/index.server.ts b/plugin-examples/lifecycle-actions/index.server.ts
index c97f2a7254..7b1fb1e761 100644
--- a/plugin-examples/lifecycle-actions/index.server.ts
+++ b/plugin-examples/lifecycle-actions/index.server.ts
@@ -2,7 +2,7 @@ import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { latestOutputText, shellCommand } from "./server/inspect";
 
 export default function contribute(server: PluginServerContext) {
-  server.before("workspace.create", ({ request }) => {
+  server.addHook("workspace.create.before", async ({ request }) => {
     if (request.title === "Isolated lifecycle example" && request.source.kind === "directory") {
       return {
         ...request,
@@ -17,7 +17,7 @@ export default function contribute(server: PluginServerContext) {
     return request;
   });
 
-  server.on("agent.turn_ended", async (event, context) => {
+  server.addHook("agent.turn.after", async (event, context) => {
     if (event.outcome.kind === "canceled") {
       return;
     }
@@ -30,7 +30,7 @@ export default function contribute(server: PluginServerContext) {
     }
   });
 
-  server.on("agent.permission_requested", async (event, context) => {
+  server.addHook("agent.permission.before", async (event, context) => {
     const command = shellCommand(event.request);
     if (command === null) {
       return;
@@ -56,7 +56,7 @@ export default function contribute(server: PluginServerContext) {
     }
   });
 
-  server.before("agent.create", ({ request }) => {
+  server.addHook("agent.create.before", async ({ request }) => {
     return {
       ...request,
       env: {
@@ -66,7 +66,7 @@ export default function contribute(server: PluginServerContext) {
     };
   });
 
-  server.before("agent.create", ({ request }) => {
+  server.addHook("agent.create.before", async ({ request }) => {
     if (request.config.provider === "codex") {
       return {
         ...request,
@@ -82,7 +82,7 @@ export default function contribute(server: PluginServerContext) {
     return request;
   });
 
-  server.before("agent.session_open", ({ request }) => {
+  server.addHook("agent.open.before", async ({ request }) => {
     return {
       ...request,
       env: {
diff --git a/plugin-examples/lifecycle-actions/paseo-plugin.json b/plugin-examples/lifecycle-actions/paseo-plugin.json
index fe578fae6d..df289d0aa2 100644
--- a/plugin-examples/lifecycle-actions/paseo-plugin.json
+++ b/plugin-examples/lifecycle-actions/paseo-plugin.json
@@ -1,6 +1,6 @@
 {
   "id": "lifecycle-actions",
   "requirements": {
-    "paseo": ">=0.8.0"
+    "paseo": ">=0.14.0-beta.1"
   }
 }
diff --git a/plugin-examples/lifecycle-logger/README.md b/plugin-examples/lifecycle-logger/README.md
index d6c00b8032..60259d34c7 100644
--- a/plugin-examples/lifecycle-logger/README.md
+++ b/plugin-examples/lifecycle-logger/README.md
@@ -1,6 +1,6 @@
 # Lifecycle logger
 
-Registers all eleven server lifecycle hooks and logs their data as JSON. It observes agent creation,
+Registers agent, workspace, and worktree hooks and logs their data as JSON. It observes agent creation,
 session opening, turns, permissions, archive, and workspace creation/archive. Before hooks return
 the request unchanged. Environment values are redacted; prompts and timeline content are logged.
 
diff --git a/plugin-examples/lifecycle-logger/index.server.ts b/plugin-examples/lifecycle-logger/index.server.ts
index 0f5fd4ed95..e87be2c2f6 100644
--- a/plugin-examples/lifecycle-logger/index.server.ts
+++ b/plugin-examples/lifecycle-logger/index.server.ts
@@ -2,55 +2,59 @@ import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { logHook } from "./server/log";
 
 export default function contribute(server: PluginServerContext) {
-  server.before("workspace.create", ({ request }) => {
-    logHook("before workspace.create", { request });
+  server.addHook("workspace.create.before", async ({ request }) => {
+    logHook("workspace.create.before", { request });
     return request;
   });
 
-  server.on("workspace.created", (event) => {
-    logHook("workspace.created", event);
+  server.addHook("workspace.create.after", async (event) => {
+    logHook("workspace.create.after", event);
   });
 
-  server.on("workspace.archived", (event) => {
-    logHook("workspace.archived", event);
+  server.addHook("workspace.archive.after", async (event) => {
+    logHook("workspace.archive.after", event);
   });
 
-  server.before("agent.create", ({ request }) => {
-    logHook("before agent.create", { request });
+  server.addHook("worktree.create.after", async (event) => {
+    logHook("worktree.create.after", event);
+  });
+
+  server.addHook("agent.create.before", async ({ request }) => {
+    logHook("agent.create.before", { request });
     return request;
   });
 
-  server.before("agent.session_open", ({ request }) => {
-    logHook("before agent.session_open", { request });
+  server.addHook("agent.open.before", async ({ request }) => {
+    logHook("agent.open.before", { request });
     return request;
   });
 
-  server.on("agent.created", (event) => {
-    logHook("agent.created", event);
+  server.addHook("agent.create.after", async (event) => {
+    logHook("agent.create.after", event);
   });
 
-  server.on("agent.closed", (event) => {
-    logHook("agent.closed", event);
+  server.addHook("agent.close.after", async (event) => {
+    logHook("agent.close.after", event);
   });
 
-  server.on("agent.turn_started", (event) => {
-    logHook("agent.turn_started", event);
+  server.addHook("agent.turn.before", async (event) => {
+    logHook("agent.turn.before", event);
   });
 
-  server.on("agent.turn_ended", (event) => {
-    logHook("agent.turn_ended", event);
+  server.addHook("agent.turn.after", async (event) => {
+    logHook("agent.turn.after", event);
   });
 
-  server.on("agent.permission_requested", (event) => {
-    logHook("agent.permission_requested", event);
+  server.addHook("agent.permission.before", async (event) => {
+    logHook("agent.permission.before", event);
   });
 
-  server.on("agent.permission_resolved", (event) => {
-    logHook("agent.permission_resolved", event);
+  server.addHook("agent.permission.after", async (event) => {
+    logHook("agent.permission.after", event);
   });
 
-  server.on("agent.archived", (event) => {
-    logHook("agent.archived", event);
+  server.addHook("agent.archive.after", async (event) => {
+    logHook("agent.archive.after", event);
   });
 
   return () => {};
diff --git a/plugin-examples/lifecycle-logger/paseo-plugin.json b/plugin-examples/lifecycle-logger/paseo-plugin.json
index 8385fbf14c..2c964d4622 100644
--- a/plugin-examples/lifecycle-logger/paseo-plugin.json
+++ b/plugin-examples/lifecycle-logger/paseo-plugin.json
@@ -1,6 +1,6 @@
 {
   "id": "lifecycle-logger",
   "requirements": {
-    "paseo": ">=0.8.0"
+    "paseo": ">=0.14.0-beta.1"
   }
 }
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/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/worktree-placement/README.md b/plugin-examples/worktree-placement/README.md
new file mode 100644
index 0000000000..8d88d8c627
--- /dev/null
+++ b/plugin-examples/worktree-placement/README.md
@@ -0,0 +1,36 @@
+# Worktree placement
+
+Place worktrees next to their source checkout, using the repository directory name and branch.
+For `/home/me/src/paseo` on branch `feature/x`, the new worktree is
+`/home/me/src/paseo.feature-x`. Slashes in branch names become hyphens.
+
+Install on Paseo 0.14.0-beta.1 or newer with plugins enabled:
+
+```bash
+paseo plugin install /absolute/path/to/plugin-examples/worktree-placement
+```
+
+The plugin is one file, `index.server.ts`:
+
+```ts
+import { basename, dirname, join } from "node:path";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+
+export default function contribute(server: PluginServerContext) {
+  return server.addHook("worktree.create.before", async ({ request }) => ({
+    ...request,
+    path: join(
+      dirname(request.sourceCheckout),
+      `${basename(request.sourceCheckout)}.${request.branch.replaceAll("/", "-")}`,
+    ),
+  }));
+}
+```
+
+Paseo validates the returned path and refuses an existing one. It creates, lists, restores,
+and removes the worktree through the normal workspace workflow. Restoring uses the recorded
+path without running the hook. Git can choose a unique branch name after this hook runs;
+the path retains the branch name received by the hook.
+
+See [worktree.create.before](../../public-docs/plugins/hooks.md#worktreecreatebefore)
+for the request fields and validation rules.
diff --git a/plugin-examples/worktree-placement/index.server.ts b/plugin-examples/worktree-placement/index.server.ts
new file mode 100644
index 0000000000..67509a000d
--- /dev/null
+++ b/plugin-examples/worktree-placement/index.server.ts
@@ -0,0 +1,12 @@
+import { basename, dirname, join } from "node:path";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+
+export default function contribute(server: PluginServerContext) {
+  return server.addHook("worktree.create.before", async ({ request }) => ({
+    ...request,
+    path: join(
+      dirname(request.sourceCheckout),
+      `${basename(request.sourceCheckout)}.${request.branch.replaceAll("/", "-")}`,
+    ),
+  }));
+}
diff --git a/plugin-examples/worktree-placement/paseo-plugin.json b/plugin-examples/worktree-placement/paseo-plugin.json
new file mode 100644
index 0000000000..ab7f7a20e6
--- /dev/null
+++ b/plugin-examples/worktree-placement/paseo-plugin.json
@@ -0,0 +1,4 @@
+{
+  "id": "worktree-placement",
+  "requirements": { "paseo": ">=0.14.0-beta.1" }
+}
diff --git a/plugins/package.json b/plugins/package.json
index 30d9929eef..a47ddf956d 100644
--- a/plugins/package.json
+++ b/plugins/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/builtin-plugins",
-  "version": "0.13.2",
+  "version": "0.15.3",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/plugins/worktree-include/LICENSE b/plugins/worktree-include/LICENSE
new file mode 100644
index 0000000000..60cf520f1d
--- /dev/null
+++ b/plugins/worktree-include/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Precioso
+
+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/plugins/worktree-include/index.server.ts b/plugins/worktree-include/index.server.ts
new file mode 100644
index 0000000000..9055c1677d
--- /dev/null
+++ b/plugins/worktree-include/index.server.ts
@@ -0,0 +1,8 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { copyWorktreeIncludes } from "./server/copy.js";
+
+export default function contribute(server: PluginServerContext) {
+  return server.addHook("worktree.create.after", async ({ worktree }) => {
+    await copyWorktreeIncludes(worktree.path, worktree.sourceCheckout);
+  });
+}
diff --git a/plugins/worktree-include/paseo-plugin.json b/plugins/worktree-include/paseo-plugin.json
new file mode 100644
index 0000000000..711476b70f
--- /dev/null
+++ b/plugins/worktree-include/paseo-plugin.json
@@ -0,0 +1 @@
+{ "id": "worktree-include", "requirements": { "paseo": ">=0.14.0-beta.1" } }
diff --git a/plugins/worktree-include/server/copy.ts b/plugins/worktree-include/server/copy.ts
new file mode 100644
index 0000000000..73a3ba63f3
--- /dev/null
+++ b/plugins/worktree-include/server/copy.ts
@@ -0,0 +1,71 @@
+// Derived from cprecioso/paseo-worktreeinclude (MIT); see ./LICENSE in the plugin root.
+// Copyright (c) 2026 Carlos Precioso.
+import { execFile } from "node:child_process";
+import { constants, existsSync } from "node:fs";
+import { copyFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+const INCLUDE_FILE = ".worktreeinclude";
+
+export type CopyResult =
+  | { kind: "no-include-file" }
+  | { kind: "copied"; copied: string[]; skipped: string[] };
+
+async function git(cwd: string, args: string[], input?: string): Promise<string> {
+  const child = exec("git", args, { cwd, maxBuffer: 64 * 1024 * 1024 });
+  if (input !== undefined) {
+    child.child.stdin?.end(input);
+  }
+  const { stdout } = await child;
+  return stdout;
+}
+
+async function gitAllowExit1(cwd: string, args: string[], input: string): Promise<string> {
+  try {
+    return await git(cwd, args, input);
+  } catch (error) {
+    // `git check-ignore` exits 1 when nothing matched.
+    if ((error as { code?: number }).code === 1) return "";
+    throw error;
+  }
+}
+
+const splitNul = (s: string) => s.split("\0").filter(Boolean);
+
+// Copy files that match .worktreeinclude (gitignore syntax)
+// AND are gitignored, so tracked files are never touched.
+export async function copyWorktreeIncludes(worktree: string, source: string): Promise<CopyResult> {
+  if (!existsSync(join(source, INCLUDE_FILE))) return { kind: "no-include-file" };
+
+  const matches = splitNul(
+    await git(source, [
+      "ls-files",
+      "--others",
+      "--ignored",
+      `--exclude-from=${INCLUDE_FILE}`,
+      "-z",
+    ]),
+  );
+  if (matches.length === 0) return { kind: "copied", copied: [], skipped: [] };
+
+  const ignored = splitNul(
+    await gitAllowExit1(source, ["check-ignore", "--stdin", "-z"], matches.join("\0") + "\0"),
+  );
+
+  const copied: string[] = [];
+  const skipped: string[] = [];
+  for (const file of ignored) {
+    const dest = join(worktree, file);
+    if (existsSync(dest)) {
+      skipped.push(file);
+      continue;
+    }
+    await mkdir(dirname(dest), { recursive: true });
+    // Clone (APFS/btrfs copy-on-write) when supported, else fall back to a regular copy.
+    await copyFile(join(source, file), dest, constants.COPYFILE_FICLONE);
+    copied.push(file);
+  }
+  return { kind: "copied", copied, skipped };
+}
diff --git a/public-docs/cli.md b/public-docs/cli.md
index dd61ef60ae..f28911ac5a 100644
--- a/public-docs/cli.md
+++ b/public-docs/cli.md
@@ -289,10 +289,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..6e47391771 100644
--- a/public-docs/cli.zh-CN.md
+++ b/public-docs/cli.zh-CN.md
@@ -270,10 +270,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/hub/configuration/hub-yml.md b/public-docs/hub/configuration/hub-yml.md
index 91b71782d9..26578854a8 100644
--- a/public-docs/hub/configuration/hub-yml.md
+++ b/public-docs/hub/configuration/hub-yml.md
@@ -141,14 +141,15 @@ steps:
 
 Use one of these semantic event names for new GitHub workflows:
 
-| `on`                                  | Matches                                                                   |
-| ------------------------------------- | ------------------------------------------------------------------------- |
-| `github.issue_created`                | An `issues` delivery whose action is `opened`.                            |
-| `github.pull_request_created`         | A `pull_request` delivery whose action is `opened`.                       |
-| `github.issue_comment_created`        | An `issue_comment` delivery whose action is `created`, on an issue.       |
-| `github.pull_request_comment_created` | An `issue_comment` delivery whose action is `created`, on a pull request. |
-| `github.issue_label_added`            | An `issues` delivery whose action is `labeled`.                           |
-| `github.pull_request_label_added`     | A `pull_request` delivery whose action is `labeled`.                      |
+| `on`                                   | Matches                                                                   |
+| -------------------------------------- | ------------------------------------------------------------------------- |
+| `github.issue_created`                 | An `issues` delivery whose action is `opened`.                            |
+| `github.pull_request_created`          | A `pull_request` delivery whose action is `opened`.                       |
+| `github.pull_request_ready_for_review` | A draft pull request is marked ready for review.                          |
+| `github.issue_comment_created`         | An `issue_comment` delivery whose action is `created`, on an issue.       |
+| `github.pull_request_comment_created`  | An `issue_comment` delivery whose action is `created`, on a pull request. |
+| `github.issue_label_added`             | An `issues` delivery whose action is `labeled`.                           |
+| `github.pull_request_label_added`      | A `pull_request` delivery whose action is `labeled`.                      |
 
 Existing configurations may continue to use `github.issues`, `github.issue_comment`, `github.pull_request_review`, `github.pull_request_review_comment`, and `github.push`. These legacy events retain their existing behavior.
 
diff --git a/public-docs/hub/configuration/hub-yml.zh-CN.md b/public-docs/hub/configuration/hub-yml.zh-CN.md
index 13f1ea5478..db8ddd38af 100644
--- a/public-docs/hub/configuration/hub-yml.zh-CN.md
+++ b/public-docs/hub/configuration/hub-yml.zh-CN.md
@@ -139,14 +139,15 @@ steps:
 
 新的 GitHub workflow 请使用以下语义化事件名之一：
 
-| `on`                                  | 匹配                                                              |
-| ------------------------------------- | ----------------------------------------------------------------- |
-| `github.issue_created`                | action 为 `opened` 的 `issues` 投递。                             |
-| `github.pull_request_created`         | action 为 `opened` 的 `pull_request` 投递。                       |
-| `github.issue_comment_created`        | 在 issue 上、action 为 `created` 的 `issue_comment` 投递。        |
-| `github.pull_request_comment_created` | 在 Pull Request 上、action 为 `created` 的 `issue_comment` 投递。 |
-| `github.issue_label_added`            | action 为 `labeled` 的 `issues` 投递。                            |
-| `github.pull_request_label_added`     | action 为 `labeled` 的 `pull_request` 投递。                      |
+| `on`                                   | 匹配                                                              |
+| -------------------------------------- | ----------------------------------------------------------------- |
+| `github.issue_created`                 | action 为 `opened` 的 `issues` 投递。                             |
+| `github.pull_request_created`          | action 为 `opened` 的 `pull_request` 投递。                       |
+| `github.pull_request_ready_for_review` | 草稿 PR 被标记为可审查。                                          |
+| `github.issue_comment_created`         | 在 issue 上、action 为 `created` 的 `issue_comment` 投递。        |
+| `github.pull_request_comment_created`  | 在 Pull Request 上、action 为 `created` 的 `issue_comment` 投递。 |
+| `github.issue_label_added`             | action 为 `labeled` 的 `issues` 投递。                            |
+| `github.pull_request_label_added`      | action 为 `labeled` 的 `pull_request` 投递。                      |
 
 已有的配置可以继续使用 `github.issues`、`github.issue_comment`、`github.pull_request_review`、`github.pull_request_review_comment` 和 `github.push`。这些旧版事件保持原有的行为。
 
diff --git a/public-docs/hub/self-hosting/github-app.md b/public-docs/hub/self-hosting/github-app.md
index 740ce9da5c..ad47a03f42 100644
--- a/public-docs/hub/self-hosting/github-app.md
+++ b/public-docs/hub/self-hosting/github-app.md
@@ -31,7 +31,7 @@ Keep GitHub's SSL verification enabled.
 
 ## Subscribe to GitHub events
 
-Under **Subscribe to events**, select **Issue comment**, **Issues**, **Pull requests**, **Pull request review**, **Pull request review comment**, and **Push**. **Pull requests** is required for `github.pull_request_created` and `github.pull_request_label_added`.
+Under **Subscribe to events**, select **Issue comment**, **Issues**, **Pull requests**, **Pull request review**, **Pull request review comment**, and **Push**. **Pull requests** is required for `github.pull_request_created`, `github.pull_request_ready_for_review`, and `github.pull_request_label_added`.
 
 ## Connect repositories
 
diff --git a/public-docs/hub/self-hosting/github-app.zh-CN.md b/public-docs/hub/self-hosting/github-app.zh-CN.md
index 75c0ac67a4..ef892fe815 100644
--- a/public-docs/hub/self-hosting/github-app.zh-CN.md
+++ b/public-docs/hub/self-hosting/github-app.zh-CN.md
@@ -29,7 +29,7 @@ GitHub 会使用以下 Hub URL：
 
 ## 订阅 GitHub 事件 {#subscribe-to-github-events}
 
-在 **Subscribe to events** 下，选择 **Issue comment**、**Issues**、**Pull requests**、**Pull request review**、**Pull request review comment** 和 **Push**。`github.pull_request_created` 和 `github.pull_request_label_added` 需要 **Pull requests**。
+在 **Subscribe to events** 下，选择 **Issue comment**、**Issues**、**Pull requests**、**Pull request review**、**Pull request review comment** 和 **Push**。`github.pull_request_created`、`github.pull_request_ready_for_review` 和 `github.pull_request_label_added` 需要 **Pull requests**。
 
 ## 连接仓库 {#connect-repositories}
 
diff --git a/public-docs/hub/triggers/github.md b/public-docs/hub/triggers/github.md
index 92be54bfe1..3585a2be3a 100644
--- a/public-docs/hub/triggers/github.md
+++ b/public-docs/hub/triggers/github.md
@@ -74,6 +74,10 @@ steps:
 
 `github.pull_request_created` fires only when someone opens a pull request.
 
+To wait until a draft is finished, change `on` in the example above to `github.pull_request_ready_for_review`. It fires only when a draft is marked ready, with the user making that transition checked against `from_users`. Opening a pull request, later pushes, and converting it back to draft do not fire this event.
+
+Pull request webhook context includes `github.pull_request.draft` and `github.pull_request.head_sha` as delivered by GitHub. `github.pull_request` is `null` for other events, including conversation comments on a pull request. Fetch the live pull request with `gh pr view` before reviewing and again before posting. Finish without posting if it is now draft or its head differs from the reviewed SHA. Converting back to draft does not cancel a Hub run already in progress; the workflow owns these live checks.
+
 ## Respond to new comments
 
 `.paseo/workflows/respond-to-issue-comment.yml`:
@@ -177,14 +181,15 @@ steps:
 
 ## Choose the event
 
-| `on`                                  | Fires when                                           |
-| ------------------------------------- | ---------------------------------------------------- |
-| `github.issue_created`                | An issue is opened.                                  |
-| `github.pull_request_created`         | A pull request is opened.                            |
-| `github.issue_comment_created`        | A comment is created on an issue.                    |
-| `github.pull_request_comment_created` | A conversation comment is created on a pull request. |
-| `github.issue_label_added`            | A label is added to an issue.                        |
-| `github.pull_request_label_added`     | A label is added to a pull request.                  |
+| `on`                                   | Fires when                                           |
+| -------------------------------------- | ---------------------------------------------------- |
+| `github.issue_created`                 | An issue is opened.                                  |
+| `github.pull_request_created`          | A pull request is opened.                            |
+| `github.pull_request_ready_for_review` | A draft pull request is marked ready for review.     |
+| `github.issue_comment_created`         | A comment is created on an issue.                    |
+| `github.pull_request_comment_created`  | A conversation comment is created on a pull request. |
+| `github.issue_label_added`             | A label is added to an issue.                        |
+| `github.pull_request_label_added`      | A label is added to a pull request.                  |
 
 Choose `github.issue_comment_created` for a comment on an issue and `github.pull_request_comment_created` for a conversation comment on a pull request. GitHub delivers both as issue comments; Hub separates them for you. A comment on a changed line is a diff comment, covered by the legacy `github.pull_request_review_comment` event.
 
diff --git a/public-docs/hub/triggers/github.zh-CN.md b/public-docs/hub/triggers/github.zh-CN.md
index 3f599873f6..71c033129f 100644
--- a/public-docs/hub/triggers/github.zh-CN.md
+++ b/public-docs/hub/triggers/github.zh-CN.md
@@ -72,6 +72,10 @@ steps:
 
 `github.pull_request_created` 只在有人创建 PR 时触发。
 
+若要等草稿完成后再开始审查，将上例的 `on` 改为 `github.pull_request_ready_for_review`。只有将草稿 PR 标记为可审查时才会触发；创建 PR、后续 push 和转回草稿都不会触发。`from_users` 匹配执行此操作的用户。
+
+PR webhook 的上下文通过 `github.pull_request.draft` 和 `github.pull_request.head_sha` 提供投递时的草稿状态和 head commit。其他事件（包括 PR 会话评论）的此字段为 `null`。审查前及发布结果前，通过 `gh pr view` 重新获取 PR；如果它已成为草稿或 head 与已审查的 SHA 不同，就结束运行而不发布结果。转回草稿不会取消已启动的 Hub 运行，workflow 应自行检查状态。
+
 ## 回复新评论 {#respond-to-new-comments}
 
 `.paseo/workflows/respond-to-issue-comment.yml`：
@@ -175,14 +179,15 @@ steps:
 
 ## 选择事件 {#choose-the-event}
 
-| `on`                                  | 触发时机               |
-| ------------------------------------- | ---------------------- |
-| `github.issue_created`                | 创建 issue。           |
-| `github.pull_request_created`         | 创建 PR。              |
-| `github.issue_comment_created`        | 在 issue 上创建评论。  |
-| `github.pull_request_comment_created` | 在 PR 上创建对话评论。 |
-| `github.issue_label_added`            | 为 issue 添加标签。    |
-| `github.pull_request_label_added`     | 为 PR 添加标签。       |
+| `on`                                   | 触发时机                 |
+| -------------------------------------- | ------------------------ |
+| `github.issue_created`                 | 创建 issue。             |
+| `github.pull_request_created`          | 创建 PR。                |
+| `github.pull_request_ready_for_review` | 草稿 PR 被标记为可审查。 |
+| `github.issue_comment_created`         | 在 issue 上创建评论。    |
+| `github.pull_request_comment_created`  | 在 PR 上创建对话评论。   |
+| `github.issue_label_added`             | 为 issue 添加标签。      |
+| `github.pull_request_label_added`      | 为 PR 添加标签。         |
 
 issue 上的评论选择 `github.issue_comment_created`，PR 上的对话评论选择 `github.pull_request_comment_created`。GitHub 把两者都作为 issue 评论投递；Hub 会替你区分它们。针对某一行改动的评论属于 diff 评论，由旧的 `github.pull_request_review_comment` 事件处理。
 
diff --git a/public-docs/hub/triggers/index.md b/public-docs/hub/triggers/index.md
index 164d1739eb..002ad5c20e 100644
--- a/public-docs/hub/triggers/index.md
+++ b/public-docs/hub/triggers/index.md
@@ -87,17 +87,18 @@ Hub includes an `executionId` in each prompt. When using a continuing agent, pas
 
 ## Events
 
-| `on`                                  | Fires when                                           |
-| ------------------------------------- | ---------------------------------------------------- |
-| `github.issue_created`                | An issue is opened.                                  |
-| `github.pull_request_created`         | A pull request is opened.                            |
-| `github.issue_comment_created`        | A comment is created on an issue.                    |
-| `github.pull_request_comment_created` | A conversation comment is created on a pull request. |
-| `github.issue_label_added`            | A label is added to an issue.                        |
-| `github.pull_request_label_added`     | A label is added to a pull request.                  |
-| `slack.mention`                       | The bot is mentioned in a channel.                   |
-| `discord.mention`                     | The bot is mentioned in a guild.                     |
-| `manual.run`                          | A run started from the API.                          |
+| `on`                                   | Fires when                                           |
+| -------------------------------------- | ---------------------------------------------------- |
+| `github.issue_created`                 | An issue is opened.                                  |
+| `github.pull_request_created`          | A pull request is opened.                            |
+| `github.pull_request_ready_for_review` | A draft pull request is marked ready for review.     |
+| `github.issue_comment_created`         | A comment is created on an issue.                    |
+| `github.pull_request_comment_created`  | A conversation comment is created on a pull request. |
+| `github.issue_label_added`             | A label is added to an issue.                        |
+| `github.pull_request_label_added`      | A label is added to a pull request.                  |
+| `slack.mention`                        | The bot is mentioned in a channel.                   |
+| `discord.mention`                      | The bot is mentioned in a guild.                     |
+| `manual.run`                           | A run started from the API.                          |
 
 New GitHub workflows should use a semantic event. The five legacy events remain compatible: `github.issues`, `github.issue_comment`, `github.pull_request_review`, `github.pull_request_review_comment`, and `github.push`. See [GitHub triggers](/docs/hub/triggers/github) for complete workflows and when to use each event.
 
diff --git a/public-docs/hub/triggers/index.zh-CN.md b/public-docs/hub/triggers/index.zh-CN.md
index 9835633efd..549614ca1a 100644
--- a/public-docs/hub/triggers/index.zh-CN.md
+++ b/public-docs/hub/triggers/index.zh-CN.md
@@ -85,17 +85,18 @@ Hub 在每段提示词中都包含一个 `executionId`。使用持续的 Agent 
 
 ## 事件 {#events}
 
-| `on`                                  | 触发时机                        |
-| ------------------------------------- | ------------------------------- |
-| `github.issue_created`                | 有 issue 被创建。               |
-| `github.pull_request_created`         | 有 Pull Request 被创建。        |
-| `github.issue_comment_created`        | issue 上新增了评论。            |
-| `github.pull_request_comment_created` | Pull Request 上新增了对话评论。 |
-| `github.issue_label_added`            | issue 被添加了标签。            |
-| `github.pull_request_label_added`     | Pull Request 被添加了标签。     |
-| `slack.mention`                       | 机器人在频道中被提及。          |
-| `discord.mention`                     | 机器人在服务器中被提及。        |
-| `manual.run`                          | 通过 API 发起了一次运行。       |
+| `on`                                   | 触发时机                        |
+| -------------------------------------- | ------------------------------- |
+| `github.issue_created`                 | 有 issue 被创建。               |
+| `github.pull_request_created`          | 有 Pull Request 被创建。        |
+| `github.pull_request_ready_for_review` | 草稿 PR 被标记为可审查。        |
+| `github.issue_comment_created`         | issue 上新增了评论。            |
+| `github.pull_request_comment_created`  | Pull Request 上新增了对话评论。 |
+| `github.issue_label_added`             | issue 被添加了标签。            |
+| `github.pull_request_label_added`      | Pull Request 被添加了标签。     |
+| `slack.mention`                        | 机器人在频道中被提及。          |
+| `discord.mention`                      | 机器人在服务器中被提及。        |
+| `manual.run`                           | 通过 API 发起了一次运行。       |
 
 新的 GitHub workflow 应使用语义化事件。五个旧版事件仍然兼容：`github.issues`、`github.issue_comment`、`github.pull_request_review`、`github.pull_request_review_comment` 和 `github.push`。完整的 workflow 以及何时使用哪个事件，见 [GitHub 触发器](/docs/hub/triggers/github)。
 
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
new file mode 100644
index 0000000000..25c8cf0527
--- /dev/null
+++ b/public-docs/plugins/hooks.md
@@ -0,0 +1,659 @@
+---
+title: Plugin hooks
+description: Register hooks to change requests or observe agent and workspace operations.
+nav: Hooks
+order: 48
+category: Plugins
+---
+
+# Plugin hooks
+
+Use `server.addHook(name, handler)` in `index.server.ts`. Hooks run while the plugin is enabled, even with no app connected. `addHook` is available from Paseo 0.14; set `requirements.paseo` to the release you build against.
+
+```ts
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+
+export default function contribute(server: PluginServerContext) {
+  const remove = server.addHook("agent.open.before", async ({ request }) => ({
+    ...request,
+    env: { ...request.env, REGION: "eu" },
+  }));
+  return remove;
+}
+```
+
+## Naming and timing
+
+Names follow `subject.operation.position`: the subject, the operation, then `before` or `after`. The name identifies a lifecycle position. Whether Paseo waits is a per-hook property shown in the table below. `workspace` covers every workspace; `worktree` covers only git worktrees.
+
+- Waiting hooks finish before Paseo continues. Throwing, returning invalid data, or exceeding 30 seconds fails the operation with `Plugin <id> <hook> failed: …`. Request-changing hooks receive `{ request }` and may return a complete replacement request or `undefined`.
+- Notifications receive the event object and return `Promise<void>`. Paseo does not wait; errors are logged against the plugin and the operation continues. `agent.turn.before` and `agent.permission.before` are notifications fired when a turn starts or a permission becomes pending.
+
+All handlers must be async. Turn completion includes success, failure, and cancellation; inspect `outcome`. Permission completion includes every resolution; inspect `resolution`.
+
+Creating an agent happens once, and `agent.create.before` changes its saved configuration. Opening starts the provider process: the first run, resume after a daemon restart, reading history, importing an outside session, or reload. `agent.open.before` contributes launch-only environment, tools, and MCP servers each time. Creating opens the agent; opening an existing agent does not create it; closing ends the running instance. Opening a tab in the app is a separate action.
+
+`worktree.create.after` runs before the workspace is registered. It precedes `workspace.create.after`, and both precede the first agent's `agent.create.before` / `agent.open.before`.
+
+### Return early from a waiting hook
+
+Start detached work and return when the operation should continue immediately:
+
+```ts
+server.addHook("worktree.create.after", async ({ worktree }) => {
+  void warmCaches(worktree.path);
+});
+```
+
+Paseo only sees the returned promise, so detached work gets no error reporting and no cancellation `signal`.
+
+## 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 }`     |                                                |
+
+## Shared payloads
+
+```ts
+interface PluginHookAgent {
+  id: string;
+  workspaceId: string | null;
+  parentAgentId: string | null;
+  provider: string;
+  cwd: string;
+  title: string | null;
+}
+
+interface PluginHookWorkspace {
+  id: string;
+  projectId: string;
+  cwd: string;
+  name: string | null;
+  archivedAt: string | null;
+}
+
+type PluginTurnOutcome =
+  | { kind: "completed" }
+  | { kind: "failed"; error: { message: string; code?: string } }
+  | { kind: "canceled"; reason: string };
+```
+
+| Field        | Shape / meaning                                                                        |
+| ------------ | -------------------------------------------------------------------------------------- |
+| `turnId`     | Provider-reported `string` or `null`; can repeat after a session reopens               |
+| `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                                                                       |
+
+## 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.
+
+### Choose workspace isolation
+
+```ts
+server.addHook("workspace.create.before", async ({ request }) => {
+  if (request.source.kind !== "directory") {
+    return request;
+  }
+
+  return {
+    ...request,
+    source: {
+      kind: "worktree",
+      cwd: request.source.path,
+      action: "branch-off",
+    },
+  };
+});
+```
+
+**Result:** an explicit directory creation request becomes a worktree request. Existing workspaces
+and directory lookup/import operations are unaffected.
+
+## workspace.create.after
+
+Fires after the workspace record is created and its directory is available. Receives `{ workspace }`.
+
+```ts
+server.addHook("workspace.create.after", async ({ workspace }) => {
+  console.log(workspace);
+});
+```
+
+## workspace.archive.after
+
+Fires after archive state is saved. Receives `{ workspace }`; worktree cleanup can still be pending.
+
+```ts
+server.addHook("workspace.archive.after", async ({ workspace }) => {
+  console.log(workspace);
+});
+```
+
+## worktree.create.before {#worktreecreatebefore}
+
+Choose the location and creation options for a new worktree. Paseo awaits this hook before `git worktree add`, on creation from the app, CLI, MCP, and agent creation. Receives `{ request }`; return a complete replacement request or `undefined` to keep it. Throwing, invalid returned data, or a 30-second timeout aborts creation with the plugin and hook named in the error.
+
+```ts
+import { basename, dirname, join } from "node:path";
+
+server.addHook("worktree.create.before", async ({ request }) => ({
+  ...request,
+  path: join(
+    dirname(request.sourceCheckout),
+    `${basename(request.sourceCheckout)}.${request.branch.replaceAll("/", "-")}`,
+  ),
+}));
+```
+
+For source `/home/me/src/paseo` and branch `feature/x`, this creates `/home/me/src/paseo.feature-x`. See the complete [worktree-placement example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/worktree-placement).
+
+| Request field                             | Meaning                                                                                                                                           |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kind`                                    | `branch-off`, `checkout-branch`, `checkout-change-request`, or `checkout-github-pr`                                                               |
+| `branch`                                  | Requested local branch name                                                                                                                       |
+| `baseRef`                                 | Starting ref for branch-off; comparison base for change requests; absent for `checkout-branch`. To branch off a ref, return `kind: "branch-off"`. |
+| `slug`                                    | Normalized worktree name                                                                                                                          |
+| `path`                                    | Absolute destination; initially the default location with any existing-path suffix resolved                                                       |
+| `repoRoot`                                | Read-only main repository root                                                                                                                    |
+| `sourceCheckout`                          | Read-only source checkout root, including when creation starts from another worktree                                                              |
+| `forge`, `changeRequestNumber`, `headRef` | Change-request checkout identity; GitHub legacy checkouts use `githubPrNumber` instead of `forge` and `changeRequestNumber`                       |
+| `headRepositoryOwner`, `headRepository`   | Optional source repository facts; `headRepository` is present only on change-request checkouts                                                    |
+| `checkoutRefs`                            | Optional fetch sources: `{ remoteName?: string, remoteRef: string }[]`                                                                            |
+| `pushRemoteUrl`, `trackOriginHead`        | Optional push destination and tracking policy                                                                                                     |
+
+Once `path` is returned, `slug` only feeds branch-off naming; the CLI looks up worktrees by the basename of their path.
+
+Every field except `repoRoot` and `sourceCheckout` is transformable. Return all required facts for the chosen `kind`. Paseo resolves the Git source plan after this hook, so handlers can change the branch and base before fetching refs, while Git can still choose a unique final branch name afterward.
+
+Paseo resolves symlinked parents and validates the returned path. It must be absolute, must not exist, and must not be the filesystem root, your home directory, the repository root, inside a `.git` directory, or an ancestor of the repository. An existing destination fails creation; Paseo never adds a suffix to a plugin-chosen path. The plugin must leave directory creation to Paseo.
+
+Ordering: `worktree.create.before` → `git worktree add` → `worktree.create.after` → workspace registration. Restoring a missing worktree recreates it at its recorded path without running either worktree creation hook.
+
+## worktree.create.after
+
+Paseo waits for this hook after a new git worktree exists and before workspace registration, setup, terminals, or agents. Receives `{ worktree: { path, branch, sourceCheckout } }`: the absolute worktree path, branch name, and source checkout directory. There is no workspace id yet. Return nothing; write files directly into the worktree. Throwing or exceeding 30 seconds aborts creation and removes the new worktree.
+
+This covers branch-off, branch checkout, and PR checkout creation. Restoring a missing archived worktree uses a separate recovery path and does not fire this hook.
+
+```ts
+import { copyFile } from "node:fs/promises";
+
+server.addHook("worktree.create.after", async ({ worktree }) => {
+  await copyFile(`${worktree.sourceCheckout}/.env`, `${worktree.path}/.env`);
+});
+```
+
+## 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.
+
+**`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                                                              |
+
+### Change saved configuration
+
+Add this callback inside `contribute(server)` to set the saved options for new Codex agents:
+
+```ts
+server.addHook("agent.create.before", async ({ request }) => {
+  if (request.config.provider !== "codex") {
+    return request;
+  }
+
+  return {
+    ...request,
+    config: {
+      ...request.config,
+      providerOptions: {
+        ...request.config.providerOptions,
+        sandbox_mode: "workspace-write",
+        approval_policy: "on-request",
+      },
+    },
+  };
+});
+```
+
+| Input                                       | Result                  |
+| ------------------------------------------- | ----------------------- |
+| `providerOptions.sandbox_mode: "read-only"` | `"workspace-write"`     |
+| `providerOptions.web_search: "disabled"`    | Preserved by the spread |
+
+The selected provider validates `providerOptions`. Explicit Codex sandbox and approval options
+override its mode presets.
+
+## agent.create.after
+
+Ordinary creation finishes. Receives `{ agent }`; import and resume do not fire it.
+
+```ts
+server.addHook("agent.create.after", async ({ agent }) => {
+  console.log(agent);
+});
+```
+
+## agent.open.before
+
+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.
+
+**`agent.open.before` request example:**
+
+```json
+{
+  "agentId": "agent-123",
+  "workspaceId": "workspace-456",
+  "provider": "codex",
+  "cwd": "/projects/shop",
+  "title": "Workspace notes",
+  "labels": { "notes/enabled": "true" },
+  "tools": [],
+  "mcpServers": {},
+  "reason": "resume",
+  "purpose": "interactive",
+  "env": { "COMPANY_ENV": "development" }
+}
+```
+
+| Field         | Values                                                                                                                  |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `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.                                               |
+| `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`                                                                                 |
+| `purpose`     | `interactive`, `history`                                                                                                |
+| `env`         | Launch override map; excludes the daemon's inherited environment. Replace the map to add, replace, or remove overrides. |
+
+### Inject environment variables on every session opening
+
+```ts
+server.addHook("agent.open.before", async ({ request }) => {
+  return {
+    ...request,
+    env: {
+      ...request.env,
+      COMPANY_ENV: "development",
+    },
+  };
+});
+```
+
+Session-open overrides are re-derived on every open. `agent.create.before.env` applies only to the
+initial launch and is not saved in the agent's configuration.
+
+### Inject MCP servers
+
+Use `agent.create.before.config.mcpServers` when the server should become part of the agent's saved
+configuration. For a plugin-owned server, add this callback inside `contribute(server)`, replacing
+the placeholder URL with your MCP endpoint:
+
+```ts
+server.addHook("agent.open.before", async ({ request }) => {
+  if (request.provider !== "codex") return;
+
+  return {
+    ...request,
+    mcpServers: {
+      ...request.mcpServers,
+      company: { type: "http", url: "https://tools.example.com/mcp" },
+    },
+  };
+});
+```
+
+`request.mcpServers` uses the same server configurations as `AgentSessionConfig.mcpServers`.
+The map starts empty for each plugin and accumulates across that plugin's own callbacks. It never
+contains the agent's saved servers or another plugin's servers. Replace the map to add, replace,
+or remove this plugin's entries; returning `undefined` preserves it. Paseo merges the plugins'
+final maps in plugin-ID order.
+
+A name colliding with a saved server, Paseo's internal `paseo` server, or another plugin's server
+fails the session open and names the server and both sources. A provider without MCP support fails
+with `does not support MCP servers`, naming the plugin. Opens with `purpose: "history"` ignore
+these servers. Install, disable, and reload changes reach existing agents through the
+[session reopen behavior](#attach-tools-to-agents).
+
+### Attach tools to agents
+
+Define a tool in `index.server.ts` and attach it in `server.addHook("agent.open.before", async handler)`.
+This example gives `append_workspace_note` only to agents with the label `notes/enabled: "true"`:
+
+```ts
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { defineAgentTool, type PluginServerContext } from "@getpaseo/plugin/server";
+
+const appendWorkspaceNote = defineAgentTool({
+  name: "append_workspace_note",
+  description: "Append a note to AGENT_NOTES.md in this agent's working directory.",
+  input: z.object({ note: z.string().min(1).describe("Note to append") }),
+  async execute({ note }, { agent, signal }) {
+    const notePath = path.join(agent.cwd, "AGENT_NOTES.md");
+    await writeFile(notePath, `${note}\n`, { encoding: "utf8", flag: "a", signal });
+    return {
+      text: `Saved note to ${notePath}`,
+      structuredContent: { path: notePath },
+    };
+  },
+});
+
+export default function contribute(server: PluginServerContext) {
+  server.addHook("agent.open.before", async ({ request }) => {
+    if (request.labels["notes/enabled"] !== "true") return;
+    return { ...request, tools: [...request.tools, appendWorkspaceNote] };
+  });
+  return () => {};
+}
+```
+
+Set the label when creating an agent with the SDK:
+
+```ts
+const agent = await paseo.agents.create({
+  config: { provider: "codex/gpt-5.4" },
+  cwd: "/projects/shop",
+  labels: { "notes/enabled": "true" },
+});
+```
+
+Select agents using any of the session-open request fields:
+
+| Select by        | Condition in the callback                    |
+| ---------------- | -------------------------------------------- |
+| Label            | `request.labels["notes/enabled"] === "true"` |
+| Provider         | `request.provider === "codex"`               |
+| Workspace        | `request.workspaceId === "workspace-456"`    |
+| Individual agent | `request.agentId === chosenAgentId`          |
+
+`request.tools` starts empty for each plugin. Each callback sees the tools returned by earlier
+callbacks in that plugin; replace the array to add or remove tools. Returning `undefined` preserves
+the request. Tools are ignored for `purpose: "history"`.
+
+Import `defineAgentTool`, `AgentToolDefinition`, `AgentToolContext`, and `AgentToolResult` from
+`@getpaseo/plugin/server`. The helper infers the validated input from your Zod schema:
+
+```ts
+declare function defineAgentTool<Input extends z.ZodType>(tool: {
+  name: string;
+  title?: string;
+  description: string;
+  input: Input;
+  execute(
+    input: z.output<Input>,
+    context: AgentToolContext,
+  ): AgentToolResult | Promise<AgentToolResult>;
+}): AgentToolDefinition;
+
+interface AgentToolResult {
+  text?: string;
+  structuredContent?: unknown;
+  isError?: boolean;
+}
+```
+
+| Execution context | Value                                                                                               |
+| ----------------- | --------------------------------------------------------------------------------------------------- |
+| `agent`           | Calling agent as a `PluginHookAgent`, including `id`, `workspaceId`, `provider`, `cwd`, and `title` |
+| `paseo`           | SDK connected to this daemon                                                                        |
+| `signal`          | Abort signal for this tool call; pass it to file operations or external requests                    |
+
+`execute` runs in the plugin process. Closures and the original Zod schema stay there; only tool
+metadata and call inputs/results cross the process boundary. Paseo validates input before calling
+`execute`. Invalid input returns schema issues to the agent. A thrown error becomes
+`{ isError: true, text: message }` and the plugin keeps running. Canceling the call or closing its
+transport aborts `signal` and discards the result. Tool calls have a 10 minute ceiling, separate
+from the 30 second hook timeout. Closing or reopening an agent session drops its old definitions.
+
+Return model-visible text in `text`. `structuredContent` must be JSON-serializable; when `text` is
+omitted, Paseo formats that value as text for the model. Set `isError: true` to report a tool error.
+
+Paseo delivers attached tools through its agent tool transport, using MCP or native registration
+as the provider supports. The same definition and callback work with either. Attached tools obey
+the [same gates as Paseo tools](/docs/mcp#limit-paseo-tools-by-provider). Only that agent sees them.
+
+Names must match `/^[a-z][a-z0-9_]*$/` and be at most 64 characters. A name colliding with a Paseo
+tool or another plugin's tool on the same agent fails the session open and names both owners.
+A duplicate name within one plugin also fails the session open. Agents the callback does not
+target are unaffected.
+
+| Change                                                        | When the agent receives it                                                                                                                                                                                 |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Start, stop, or reload a plugin declaring `agent.open.before` | Open sessions become stale. Each reopens before its next idle prompt; a running turn continues without interruption. The next prompt after that reopen reuses the session.                                 |
+| Change which agents the callback targets                      | Run `paseo plugin reload agent-tools` after editing this example, then send the agent a prompt when it is idle.                                                                                            |
+| Apply immediately                                             | Call `await paseo.agents.ref(id).reload({ requestId: "reload-notes" })`. `requestId` is optional. This reopens the provider session, reruns hooks with `reason: "refresh"`, and interrupts a running turn. |
+| Read the current snapshot                                     | Call `await paseo.agents.ref(id).refresh()`. This reads state without reopening the session.                                                                                                               |
+
+If an automatic reopen fails, the triggering prompt fails with that error. See the
+[complete agent-tools example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-tools).
+
+## agent.close.after
+
+A live agent runtime closes. Receives `{ agent }`.
+
+```ts
+server.addHook("agent.close.after", async ({ agent }) => {
+  console.log(agent);
+});
+```
+
+## agent.archive.after
+
+Archive state is saved. Receives `{ agent, archivedAt }`; runtime cleanup can still be pending.
+
+```ts
+server.addHook("agent.archive.after", async ({ agent, archivedAt }) => {
+  console.log(agent, archivedAt);
+});
+```
+
+## agent.turn.before
+
+A live turn starts. Receives `{ agent, turnId }`. History replay does not fire it.
+
+```ts
+server.addHook("agent.turn.before", async ({ agent, turnId }) => {
+  console.log(agent, turnId);
+});
+```
+
+## agent.turn.after
+
+A live turn completes, fails, or is canceled. Receives `{ agent, turnId, outcome, timeline }`. `outcome.kind` is `completed`, `failed`, or `canceled`. `timeline` is deprecated and always empty; fetch history through the SDK as below.
+
+### Send a follow-up when a turn ends
+
+Copy [server/inspect.ts](https://github.com/getpaseo/paseo/blob/main/plugin-examples/lifecycle-actions/server/inspect.ts)
+into your plugin. The helper imports types from `@getpaseo/protocol/agent-types`; add
+`@getpaseo/protocol` at the version matching your daemon to your development dependencies
+and install them before loading the plugin. `latestOutputText` joins text chunks after the latest user message.
+
+```ts
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { latestOutputText } from "./server/inspect";
+
+export default function contribute(server: PluginServerContext) {
+  server.addHook("agent.turn.after", async (event, context) => {
+    if (event.outcome.kind === "canceled") {
+      return;
+    }
+
+    const agent = context.paseo.agents.ref(event.agent.id);
+    const page = await agent.timeline.refetch({ direction: "tail", limit: 20 });
+    const text = latestOutputText(page.entries.map(({ item }) => item));
+    if (/out of credits/i.test(text)) {
+      await agent.send("Try again.");
+    }
+  });
+
+  return () => {};
+}
+```
+
+```text
+Turn ends: "out of credits"
+  → plugin sends "Try again."
+  → a new turn starts
+```
+
+The handler fetches only the last 20 timeline items. Output before that page is not inspected.
+Use `cursor` and `direction` to page further when your plugin needs more history.
+
+This sends a new message with the existing SDK. Persistent matches keep sending follow-ups;
+add limits or delays in your plugin when needed. Attachments and tool effects are not replayed.
+
+## agent.permission.before
+
+A permission or question becomes pending. Receives `{ agent, request }`; `request` is an `AgentPermissionRequest`. Send the answer through the SDK.
+
+### Answer a permission request
+
+Using `shellCommand` from the same [helper file](https://github.com/getpaseo/paseo/blob/main/plugin-examples/lifecycle-actions/server/inspect.ts):
+
+```ts
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { shellCommand } from "./server/inspect";
+
+export default function contribute(server: PluginServerContext) {
+  server.addHook("agent.permission.before", async (event, context) => {
+    const command = shellCommand(event.request);
+    if (command === null) {
+      return;
+    }
+
+    const agent = context.paseo.agents.ref(event.agent.id);
+    if (/\brm\s+-rf\b/.test(command)) {
+      await agent.respondToPermission({
+        requestId: event.request.id,
+        response: { behavior: "deny", message: "Recursive deletion is blocked." },
+      });
+      return;
+    }
+
+    if (command.trim() === "git status") {
+      await agent.respondToPermission({
+        requestId: event.request.id,
+        response: { behavior: "allow" },
+      });
+    }
+  });
+
+  return () => {};
+}
+```
+
+| Request                  | Result                    |
+| ------------------------ | ------------------------- |
+| `rm -rf build`           | Declined                  |
+| `git status`             | Approved                  |
+| Other command or request | Left pending for the user |
+| Already-resolved request | SDK response fails        |
+
+The regex is an example policy, not a shell parser. Permission requests can also be questions,
+plans, and mode changes; requesting permission does not end the turn.
+
+## agent.permission.after
+
+A pending request is answered or cleared. Receives `{ agent, requestId, resolution }`; `resolution` is an `AgentPermissionResponse`.
+
+```ts
+server.addHook("agent.permission.after", async ({ agent, requestId, resolution }) => {
+  console.log(agent, requestId, resolution);
+});
+```
+
+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
+
+```text
+Creation request
+  → agent.create.before hooks (plugin-ID order; registration order within each plugin)
+  → 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
+  → open provider session and save agent configuration
+```
+
+| Callback returns                                        | Next callback receives                              |
+| ------------------------------------------------------- | --------------------------------------------------- |
+| `{ ...request, env: { ...request.env, REGION: "eu" } }` | Prior request with `REGION` added/replaced          |
+| `{ ...request, env: { REGION: "eu" } }`                 | Prior request with the entire override map replaced |
+| `undefined`                                             | Unchanged request                                   |
+| Throws or returns invalid data                          | Operation fails; later callbacks do not run         |
+
+There is no automatic deep merge. `env` accumulates across plugins; `tools` and `mcpServers`
+accumulate only across callbacks within the same plugin. Returning a replacement map or array
+replaces that scope's prior value.
+
+## Context and cleanup
+
+| Contract                           | Behavior                                                                                                         |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `context.paseo`                    | Existing SDK connected to this daemon                                                                            |
+| `context.signal`                   | Aborted on invocation timeout or plugin stop; pass to external requests                                          |
+| Input data                         | Detached snapshot; change state through returned requests or SDK commands                                        |
+| Registration result                | Idempotent remover, e.g. `const remove = server.addHook(...); remove();`                                         |
+| Reload, disable, removal, shutdown | Remaining registrations removed                                                                                  |
+| Unknown hook name                  | Registration fails                                                                                               |
+| Hook timeout                       | 30 seconds; aborts the signal. A waiting hook fails the pending operation; a notification handler logs an error. |
+| Event-handler error                | Logged against plugin; original operation continues                                                              |
+| Event delivery                     | Live, best effort; no replay, persistence, or automatic retry                                                    |
+| Event concurrency                  | Different events may overlap; callback completion order is not guaranteed                                        |
+
+## Complete examples
+
+| Plugin                                                                                                 | Includes                                                                         |
+| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| [lifecycle-logger](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-logger)       | Agent, workspace, and worktree hooks; JSON logs with environment values redacted |
+| [lifecycle-actions](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-actions)     | Follow-ups, permissions, environment, provider switching, worktree selection     |
+| [agent-configuration](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-configuration) | MCP injection and Codex sandbox/approval options                                 |
+| [agent-tools](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-tools)                 | Label-targeted tools and file operations in the plugin process                   |
+
+Read logger output with `paseo plugin logs lifecycle-logger` or the host's `daemon.log`.
+
+## Renamed hooks
+
+The old registration methods are deprecated for removal after 2027-04-30. Existing plugins keep their behavior. Mixed old and new registrations within a plugin run in registration order. `addHook` accepts only the new names.
+
+| Old registration                                   | New registration                                          |
+| -------------------------------------------------- | --------------------------------------------------------- |
+| `server.before("workspace.create", handler)`       | `server.addHook("workspace.create.before", asyncHandler)` |
+| `server.on("workspace.created", handler)`          | `server.addHook("workspace.create.after", asyncHandler)`  |
+| `server.on("workspace.archived", handler)`         | `server.addHook("workspace.archive.after", asyncHandler)` |
+| `server.before("agent.create", handler)`           | `server.addHook("agent.create.before", asyncHandler)`     |
+| `server.on("agent.created", handler)`              | `server.addHook("agent.create.after", asyncHandler)`      |
+| `server.before("agent.session_open", handler)`     | `server.addHook("agent.open.before", asyncHandler)`       |
+| `server.on("agent.closed", handler)`               | `server.addHook("agent.close.after", asyncHandler)`       |
+| `server.on("agent.archived", handler)`             | `server.addHook("agent.archive.after", asyncHandler)`     |
+| `server.on("agent.turn_started", handler)`         | `server.addHook("agent.turn.before", asyncHandler)`       |
+| `server.on("agent.turn_ended", handler)`           | `server.addHook("agent.turn.after", asyncHandler)`        |
+| `server.on("agent.permission_requested", handler)` | `server.addHook("agent.permission.before", asyncHandler)` |
+| `server.on("agent.permission_resolved", handler)`  | `server.addHook("agent.permission.after", asyncHandler)`  |
diff --git a/public-docs/plugins/hooks.zh-CN.md b/public-docs/plugins/hooks.zh-CN.md
new file mode 100644
index 0000000000..5469582b3f
--- /dev/null
+++ b/public-docs/plugins/hooks.zh-CN.md
@@ -0,0 +1,641 @@
+---
+title: 插件钩子
+description: 为 Agent 和工作区操作注册钩子，修改请求或接收通知。
+nav: 钩子
+---
+
+# 插件钩子 {#plugin-hooks}
+
+在 `index.server.ts` 中使用 `server.addHook(name, handler)`。钩子在插件启用时运行，即使没有连接的应用。`addHook` 从 Paseo 0.14 起可用；将 `requirements.paseo` 设置为你开发插件时使用的版本。
+
+```ts
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+
+export default function contribute(server: PluginServerContext) {
+  const remove = server.addHook("agent.open.before", async ({ request }) => ({
+    ...request,
+    env: { ...request.env, REGION: "eu" },
+  }));
+  return remove;
+}
+```
+
+## 命名与等待 {#naming-and-timing}
+
+名称遵循 `subject.operation.position`：主体、操作、`before` 或 `after`。名称标识生命周期中的位置；Paseo 是否等待由每个钩子决定，见下表。`workspace` 包括所有工作区，`worktree` 仅包括 git worktree。
+
+- 等待型钩子结束后 Paseo 才继续。抛出错误、返回无效数据或超过 30 秒会让操作失败，错误包含 `Plugin <id> <hook> failed: …`。修改请求的钩子收到 `{ request }`，可以返回完整的替换请求或 `undefined`。
+- 通知收到事件对象，返回 `Promise<void>`。Paseo 不等待；错误会记录在插件名下，原操作继续。`agent.turn.before` 和 `agent.permission.before` 分别在轮次开始或权限进入待处理状态时发出通知。
+
+所有处理函数都必须为异步函数。轮次完成包括成功、失败和取消，请查看 `outcome`。权限完成包括所有处理结果，请查看 `resolution`。
+
+创建 Agent 会发生一次，`agent.create.before` 修改已保存的配置。打开 Agent 指启动 Provider 进程，包括首次运行、daemon 重启后恢复、读取历史、导入外部会话和重新加载。`agent.open.before` 为每次启动提供临时的环境变量、工具和 MCP 服务器。创建会打开 Agent；打开已有 Agent 不会创建它；关闭会结束运行中的实例。在应用中打开标签页不属于此操作。
+
+`worktree.create.after` 在工作区注册前运行，随后是 `workspace.create.after`，两者都早于第一个 Agent 的 `agent.create.before` / `agent.open.before`。
+
+### 从等待型钩子提前返回 {#return-early-from-a-waiting-hook}
+
+如果操作应立即继续，可以启动独立任务并返回：
+
+```ts
+server.addHook("worktree.create.after", async ({ worktree }) => {
+  void warmCaches(worktree.path);
+});
+```
+
+Paseo 只观察返回的 Promise，因此独立任务没有错误报告，也没有取消 `signal`。
+
+## 钩子一览 {#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 }`     |                                           |
+
+## 共享载荷 {#shared-payloads}
+
+```ts
+interface PluginHookAgent {
+  id: string;
+  workspaceId: string | null;
+  parentAgentId: string | null;
+  provider: string;
+  cwd: string;
+  title: string | null;
+}
+
+interface PluginHookWorkspace {
+  id: string;
+  projectId: string;
+  cwd: string;
+  name: string | null;
+  archivedAt: string | null;
+}
+
+type PluginTurnOutcome =
+  | { kind: "completed" }
+  | { kind: "failed"; error: { message: string; code?: string } }
+  | { kind: "canceled"; reason: string };
+```
+
+| 字段         | 结构 / 含义                                                                              |
+| ------------ | ---------------------------------------------------------------------------------------- |
+| `turnId`     | Provider 报告的 `string` 或 `null`；会话重新打开后可能重复                               |
+| `timeline`   | 已弃用，始终为 `[]`；通过 SDK 获取历史。                                                 |
+| `request`    | SDK 的 `AgentPermissionRequest`；`kind` 为 `tool`、`plan`、`question`、`mode` 或 `other` |
+| `resolution` | SDK 的 `AgentPermissionResponse`                                                         |
+| `archivedAt` | 时间戳字符串                                                                             |
+
+## workspace.create.before {#workspacecreatebefore}
+
+收到 `{ request }`，其中包含 `source`、可选的 `title` 和 `firstAgentContext`。可替换整个显式创建请求；抛出错误、无效返回或超时会让创建失败。已有工作区和目录查找、导入不受影响。
+
+### 选择工作区隔离方式 {#choose-workspace-isolation}
+
+```ts
+server.addHook("workspace.create.before", async ({ request }) => {
+  if (request.source.kind !== "directory") {
+    return request;
+  }
+
+  return {
+    ...request,
+    source: {
+      kind: "worktree",
+      cwd: request.source.path,
+      action: "branch-off",
+    },
+  };
+});
+```
+
+**结果**：显式的目录创建请求会变成 worktree 请求。已有的工作区以及目录查找/导入操作不受影响。
+
+## workspace.create.after {#workspacecreateafter}
+
+工作区记录创建且目录可用后触发，收到 `{ workspace }`。
+
+```ts
+server.addHook("workspace.create.after", async ({ workspace }) => {
+  console.log(workspace);
+});
+```
+
+## workspace.archive.after {#workspacearchiveafter}
+
+归档状态保存后触发，收到 `{ workspace }`；worktree 清理可能尚未完成。
+
+```ts
+server.addHook("workspace.archive.after", async ({ workspace }) => {
+  console.log(workspace);
+});
+```
+
+## worktree.create.before {#worktreecreatebefore}
+
+为新 worktree 选择路径和创建选项。通过应用、CLI、MCP 或创建 Agent 新建 worktree 时，Paseo 在 `git worktree add` 之前等待此钩子。钩子收到 `{ request }`，返回完整的替换请求，或返回 `undefined` 保持原值。抛出错误、返回无效数据或超过 30 秒会终止创建，错误包含插件和钩子名称。
+
+```ts
+import { basename, dirname, join } from "node:path";
+
+server.addHook("worktree.create.before", async ({ request }) => ({
+  ...request,
+  path: join(
+    dirname(request.sourceCheckout),
+    `${basename(request.sourceCheckout)}.${request.branch.replaceAll("/", "-")}`,
+  ),
+}));
+```
+
+源检出目录为 `/home/me/src/paseo`、分支为 `feature/x` 时，目标为 `/home/me/src/paseo.feature-x`。完整插件见 [worktree-placement 示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/worktree-placement)。
+
+| 请求字段                                  | 含义                                                                                                                   |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `kind`                                    | `branch-off`、`checkout-branch`、`checkout-change-request` 或 `checkout-github-pr`                                     |
+| `branch`                                  | 请求的本地分支名称                                                                                                     |
+| `baseRef`                                 | branch-off 的起始引用；变更请求的比较基准；`checkout-branch` 不含此字段。要从引用创建分支，返回 `kind: "branch-off"`。 |
+| `slug`                                    | 规范化的 worktree 名称                                                                                                 |
+| `path`                                    | 绝对目标路径，初始值为已处理现有路径后缀的默认位置                                                                     |
+| `repoRoot`                                | 只读，主仓库根目录                                                                                                     |
+| `sourceCheckout`                          | 只读，源检出根目录，也支持从另一个 worktree 发起创建                                                                   |
+| `forge`、`changeRequestNumber`、`headRef` | 变更请求检出标识；旧版 GitHub 检出用 `githubPrNumber` 代替 `forge` 和 `changeRequestNumber`                            |
+| `headRepositoryOwner`、`headRepository`   | 可选的源仓库信息；`headRepository` 仅用于变更请求检出                                                                  |
+| `checkoutRefs`                            | 可选的获取源：`{ remoteName?: string, remoteRef: string }[]`                                                           |
+| `pushRemoteUrl`、`trackOriginHead`        | 可选的推送目标和跟踪策略                                                                                               |
+
+返回 `path` 后，`slug` 仅用于 branch-off 分支命名；CLI 使用路径的最后一级目录名查找 worktree。
+
+除 `repoRoot` 和 `sourceCheckout` 外，所有字段都可以修改。返回所选 `kind` 的全部必填字段。Paseo 在钩子之后解析 Git 源计划，因此钩子可以在获取引用之前修改分支和基准，而 Git 之后仍可能选择唯一的最终分支名称。
+
+Paseo 解析父目录中的符号链接并验证返回的路径。路径必须为绝对路径且不存在，不能是文件系统根目录、用户主目录、仓库根目录、`.git` 目录内的路径或仓库的祖先目录。目标已存在时创建失败，Paseo 不会为插件选择的路径添加后缀。插件应让 Paseo 创建目录。
+
+顺序：`worktree.create.before` → `git worktree add` → `worktree.create.after` → 注册工作区。恢复缺失的 worktree 时使用记录的原路径，不运行这两个创建钩子。
+
+## worktree.create.after {#worktreecreateafter}
+
+新的 git worktree 在磁盘上创建后，Paseo 会等待此钩子，然后才注册工作区、运行 setup、打开终端或启动 Agent。收到 `{ worktree: { path, branch, sourceCheckout } }`，分别是 worktree 绝对路径、分支名、来源 checkout 目录。此时还没有工作区 id。无需返回数据，直接写入 worktree 即可。抛出错误或超过 30 秒会中止创建并删除新 worktree。
+
+此钩子覆盖新建分支、检出分支和检出 PR。恢复缺失的已归档 worktree 使用独立路径，不触发此钩子。
+
+```ts
+import { copyFile } from "node:fs/promises";
+
+server.addHook("worktree.create.after", async ({ worktree }) => {
+  await copyFile(`${worktree.sourceCheckout}/.env`, `${worktree.path}/.env`);
+});
+```
+
+## agent.create.before {#agentcreatebefore}
+
+收到 `{ request: { config, env? } }`。配置修改会保存，即使插件以后被停用或移除；`env` 只用于首次启动，不会保存。不能修改 `config.cwd`。抛出错误、无效返回或超时会让创建失败。
+
+**`agent.create.before.config`** 使用 `AgentSessionConfig`：
+
+| 字段                                          | 约束                                                     |
+| --------------------------------------------- | -------------------------------------------------------- |
+| `provider`, `model`                           | 独立的字段；修改 Provider 可能需要同时修改模型/模式/选项 |
+| `modeId`, `thinkingOptionId`, `featureValues` | 特定于 Provider 的选择                                   |
+| `title`, `systemPrompt`                       | Agent 配置                                               |
+| `providerOptions`                             | 不透明的、特定于 Provider 的选项                         |
+| `mcpServers`, `toolPolicy`                    | MCP 配置和精确的工具预批准                               |
+| `cwd`                                         | 不能修改                                                 |
+
+### 修改已保存的配置 {#change-saved-configuration}
+
+在 `contribute(server)` 中添加这个回调，为新的 Codex Agent 设置已保存的选项：
+
+```ts
+server.addHook("agent.create.before", async ({ request }) => {
+  if (request.config.provider !== "codex") {
+    return request;
+  }
+
+  return {
+    ...request,
+    config: {
+      ...request.config,
+      providerOptions: {
+        ...request.config.providerOptions,
+        sandbox_mode: "workspace-write",
+        approval_policy: "on-request",
+      },
+    },
+  };
+});
+```
+
+| 输入                                        | 结果                |
+| ------------------------------------------- | ------------------- |
+| `providerOptions.sandbox_mode: "read-only"` | `"workspace-write"` |
+| `providerOptions.web_search: "disabled"`    | 由展开运算保留      |
+
+所选的 Provider 会校验 `providerOptions`。显式的 Codex 沙盒和批准选项会覆盖它的模式预设。
+
+## agent.create.after {#agentcreateafter}
+
+常规创建完成后触发，收到 `{ agent }`；导入和恢复不会触发。
+
+```ts
+server.addHook("agent.create.after", async ({ agent }) => {
+  console.log(agent);
+});
+```
+
+## agent.open.before {#agentopenbefore}
+
+收到 `{ request }`，只能修改 `env`、`tools` 和 `mcpServers`，修改只用于此次启动。其他字段只读。抛出错误、无效返回或超时会让打开操作失败。
+
+**`agent.open.before` 请求示例：**
+
+```json
+{
+  "agentId": "agent-123",
+  "workspaceId": "workspace-456",
+  "provider": "codex",
+  "cwd": "/projects/shop",
+  "title": "Workspace notes",
+  "labels": { "notes/enabled": "true" },
+  "tools": [],
+  "mcpServers": {},
+  "reason": "resume",
+  "purpose": "interactive",
+  "env": { "COMPANY_ENV": "development" }
+}
+```
+
+| 字段          | 取值                                                                                                     |
+| ------------- | -------------------------------------------------------------------------------------------------------- |
+| `workspaceId` | 字符串或 `null`                                                                                          |
+| `title`       | 只读字符串或 `null`；创建时使用创建请求的标题，恢复时使用已保存的标题。                                  |
+| `labels`      | 只读的字符串映射；创建时使用创建请求的标签，恢复时使用已保存的标签。                                     |
+| `tools`       | 可编辑的 `AgentToolDefinition[]`，仅包含此插件的工具。参阅[为 Agent 附加工具](#attach-tools-to-agents)。 |
+| `mcpServers`  | 可编辑的服务器映射，仅用于启动且仅包含本插件的条目。参阅[注入 MCP 服务器](#inject-mcp-servers)。         |
+| `reason`      | `create`、`resume`、`refresh`、`import`                                                                  |
+| `purpose`     | `interactive`、`history`                                                                                 |
+| `env`         | 启动覆盖映射；不包括 daemon 继承的环境变量。替换整个映射即可添加、替换或移除覆盖项。                     |
+
+### 在每次打开会话时注入环境变量 {#inject-environment-variables-on-every-session-opening}
+
+```ts
+server.addHook("agent.open.before", async ({ request }) => {
+  return {
+    ...request,
+    env: {
+      ...request.env,
+      COMPANY_ENV: "development",
+    },
+  };
+});
+```
+
+会话打开时的环境变量覆盖项会在每次打开时重新计算。`agent.create.before.env` 只作用于首次启动，不会写入 Agent 的已保存配置。
+
+### 注入 MCP 服务器 {#inject-mcp-servers}
+
+需要将服务器保存为 Agent 配置的一部分时，使用 `agent.create.before.config.mcpServers`。
+插件拥有的服务器使用下面的回调，在 `contribute(server)` 中添加，并把占位 URL 替换为你的 MCP 端点：
+
+```ts
+server.addHook("agent.open.before", async ({ request }) => {
+  if (request.provider !== "codex") return;
+
+  return {
+    ...request,
+    mcpServers: {
+      ...request.mcpServers,
+      company: { type: "http", url: "https://tools.example.com/mcp" },
+    },
+  };
+});
+```
+
+`request.mcpServers` 使用与 `AgentSessionConfig.mcpServers` 相同的服务器配置。
+每个插件的映射从空开始，只在该插件自己的回调之间累积，不包含 Agent 已保存的服务器或其他插件的服务器。
+替换映射即可添加、替换或移除本插件的条目；返回 `undefined` 会保持不变。
+Paseo 按插件 ID 顺序合并各插件的最终映射。
+
+名称与已保存的服务器、Paseo 内部的 `paseo` 服务器或其他插件的服务器冲突时，会话打开失败，错误会指出服务器名称及双方来源。
+不支持 MCP 的 Provider 会报 `does not support MCP servers` 错误，并指出插件名称。
+`purpose: "history"` 的会话打开会忽略这些服务器。安装、停用和重新加载插件后，现有 Agent
+通过[会话重新打开行为](#attach-tools-to-agents)获取变化。
+
+### 为 Agent 附加工具 {#attach-tools-to-agents}
+
+在 `index.server.ts` 中定义工具，并在 `server.addHook("agent.open.before", async handler)` 中附加它。
+此示例只向带有 `notes/enabled: "true"` 标签的 Agent 提供 `append_workspace_note`：
+
+```ts
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { defineAgentTool, type PluginServerContext } from "@getpaseo/plugin/server";
+
+const appendWorkspaceNote = defineAgentTool({
+  name: "append_workspace_note",
+  description: "Append a note to AGENT_NOTES.md in this agent's working directory.",
+  input: z.object({ note: z.string().min(1).describe("Note to append") }),
+  async execute({ note }, { agent, signal }) {
+    const notePath = path.join(agent.cwd, "AGENT_NOTES.md");
+    await writeFile(notePath, `${note}\n`, { encoding: "utf8", flag: "a", signal });
+    return {
+      text: `Saved note to ${notePath}`,
+      structuredContent: { path: notePath },
+    };
+  },
+});
+
+export default function contribute(server: PluginServerContext) {
+  server.addHook("agent.open.before", async ({ request }) => {
+    if (request.labels["notes/enabled"] !== "true") return;
+    return { ...request, tools: [...request.tools, appendWorkspaceNote] };
+  });
+  return () => {};
+}
+```
+
+通过 SDK 创建 Agent 时设置标签：
+
+```ts
+const agent = await paseo.agents.create({
+  config: { provider: "codex/gpt-5.4" },
+  cwd: "/projects/shop",
+  labels: { "notes/enabled": "true" },
+});
+```
+
+使用会话打开请求中的字段选择 Agent：
+
+| 选择依据   | 回调中的条件                                 |
+| ---------- | -------------------------------------------- |
+| 标签       | `request.labels["notes/enabled"] === "true"` |
+| Provider   | `request.provider === "codex"`               |
+| 工作区     | `request.workspaceId === "workspace-456"`    |
+| 单个 Agent | `request.agentId === chosenAgentId`          |
+
+每个插件的 `request.tools` 都从空数组开始。同一插件中的后续回调会看到前面回调返回的工具；
+替换数组即可添加或移除工具。返回 `undefined` 会保留请求。`purpose: "history"` 时会忽略工具。
+
+从 `@getpaseo/plugin/server` 导入 `defineAgentTool`、`AgentToolDefinition`、`AgentToolContext`
+和 `AgentToolResult`。辅助函数会根据 Zod schema 推断验证后的输入类型：
+
+```ts
+declare function defineAgentTool<Input extends z.ZodType>(tool: {
+  name: string;
+  title?: string;
+  description: string;
+  input: Input;
+  execute(
+    input: z.output<Input>,
+    context: AgentToolContext,
+  ): AgentToolResult | Promise<AgentToolResult>;
+}): AgentToolDefinition;
+
+interface AgentToolResult {
+  text?: string;
+  structuredContent?: unknown;
+  isError?: boolean;
+}
+```
+
+| 执行 context | 值                                                                                                  |
+| ------------ | --------------------------------------------------------------------------------------------------- |
+| `agent`      | 发起调用的 Agent，以 `PluginHookAgent` 表示，包括 `id`、`workspaceId`、`provider`、`cwd` 和 `title` |
+| `paseo`      | 已连接到此 daemon 的 SDK                                                                            |
+| `signal`     | 此次工具调用的中止信号；请把它传给文件操作或外部请求                                                |
+
+`execute` 在插件进程中运行。闭包和原始 Zod schema 保留在该进程中；只有工具元数据和调用的
+输入、结果会跨进程传递。Paseo 在调用 `execute` 前验证输入。无效输入会将 schema 问题返回给
+Agent。抛出的错误会转换为 `{ isError: true, text: message }`，插件继续运行。取消调用或关闭
+其传输连接会中止 `signal` 并丢弃结果。工具调用最长运行 10 分钟，与钩子的 30 秒超时分开。
+关闭或重新打开 Agent 会话会移除旧定义。
+
+在 `text` 中返回模型可见的文本。`structuredContent` 必须可序列化为 JSON；省略 `text` 时，
+Paseo 会将该值格式化为供模型读取的文本。设置 `isError: true` 可报告工具错误。
+
+Paseo 通过 Agent 工具传输提供附加的工具，按 Provider 的支持情况使用 MCP 或原生注册。
+同一份定义和回调适用于这两种方式。附加的工具遵循[与 Paseo 工具相同的限制](/docs/mcp#limit-paseo-tools-by-provider)。
+只有该 Agent 能看到这些工具。
+
+名称必须匹配 `/^[a-z][a-z0-9_]*$/`，且不超过 64 个字符。如果名称与同一 Agent 的 Paseo
+工具或另一插件的工具冲突，会话打开会失败，并指出双方。一个插件内的重复名称也会导致
+会话打开失败。回调未选中的 Agent 不受影响。
+
+| 变更                                                  | Agent 何时收到变更                                                                                                                                                                 |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 启动、停止或重新加载声明了 `agent.open.before` 的插件 | 已打开的会话会标记为过期。每个会话在下一次空闲提示词前重新打开；正在运行的轮次会继续，不会被中断。重新打开后的下一条提示词复用该会话。                                             |
+| 修改回调选择的 Agent                                  | 编辑此示例后运行 `paseo plugin reload agent-tools`，然后在 Agent 空闲时发送提示词。                                                                                                |
+| 立即应用                                              | 调用 `await paseo.agents.ref(id).reload({ requestId: "reload-notes" })`。`requestId` 可选。这会重新打开 Provider 会话，以 `reason: "refresh"` 再次运行钩子，并中断正在运行的轮次。 |
+| 读取当前快照                                          | 调用 `await paseo.agents.ref(id).refresh()`。这只读取状态，不会重新打开会话。                                                                                                      |
+
+如果自动重新打开失败，触发它的提示词会返回该错误。参阅
+[完整 agent-tools 示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-tools)。
+
+## agent.close.after {#agentcloseafter}
+
+运行中的 Agent 实例关闭后触发，收到 `{ agent }`。
+
+```ts
+server.addHook("agent.close.after", async ({ agent }) => {
+  console.log(agent);
+});
+```
+
+## agent.archive.after {#agentarchiveafter}
+
+归档状态保存后触发，收到 `{ agent, archivedAt }`；运行时清理可能尚未完成。
+
+```ts
+server.addHook("agent.archive.after", async ({ agent, archivedAt }) => {
+  console.log(agent, archivedAt);
+});
+```
+
+## agent.turn.before {#agentturnbefore}
+
+实时轮次开始后触发，收到 `{ agent, turnId }`。历史重放不会触发。
+
+```ts
+server.addHook("agent.turn.before", async ({ agent, turnId }) => {
+  console.log(agent, turnId);
+});
+```
+
+## agent.turn.after {#agentturnafter}
+
+实时轮次完成、失败或取消后触发，收到 `{ agent, turnId, outcome, timeline }`。`outcome.kind` 为 `completed`、`failed` 或 `canceled`。`timeline` 已弃用且始终为空；请按下面的示例通过 SDK 获取历史。
+
+### 在轮次结束时发送后续消息 {#send-a-follow-up-when-a-turn-ends}
+
+把 [server/inspect.ts](https://github.com/getpaseo/paseo/blob/main/plugin-examples/lifecycle-actions/server/inspect.ts) 复制到你的插件中。该辅助文件从 `@getpaseo/protocol/agent-types` 导入类型；请把与 daemon 版本相同的 `@getpaseo/protocol` 加入开发依赖，并在加载插件之前安装它们。`latestOutputText` 会拼接最近一条用户消息之后的文本片段。
+
+```ts
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { latestOutputText } from "./server/inspect";
+
+export default function contribute(server: PluginServerContext) {
+  server.addHook("agent.turn.after", async (event, context) => {
+    if (event.outcome.kind === "canceled") {
+      return;
+    }
+
+    const agent = context.paseo.agents.ref(event.agent.id);
+    const page = await agent.timeline.refetch({ direction: "tail", limit: 20 });
+    const text = latestOutputText(page.entries.map(({ item }) => item));
+    if (/out of credits/i.test(text)) {
+      await agent.send("Try again.");
+    }
+  });
+
+  return () => {};
+}
+```
+
+```text
+Turn ends: "out of credits"
+  → plugin sends "Try again."
+  → a new turn starts
+```
+
+该处理函数只获取最近 20 条时间线条目，不检查这一页之前的输出。插件需要更多历史时，请用 `cursor` 和 `direction` 继续翻页。
+
+这会用现有的 SDK 发送一条新消息。持续匹配会不断发送后续消息；需要时请在插件中添加次数限制或延迟。附件和工具的效果不会被重放。
+
+## agent.permission.before {#agentpermissionbefore}
+
+权限或问题进入待处理状态后触发，收到 `{ agent, request }`；`request` 为 `AgentPermissionRequest`。通过 SDK 回应。
+
+### 回应权限请求 {#answer-a-permission-request}
+
+使用同一个[辅助文件](https://github.com/getpaseo/paseo/blob/main/plugin-examples/lifecycle-actions/server/inspect.ts)中的 `shellCommand`：
+
+```ts
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { shellCommand } from "./server/inspect";
+
+export default function contribute(server: PluginServerContext) {
+  server.addHook("agent.permission.before", async (event, context) => {
+    const command = shellCommand(event.request);
+    if (command === null) {
+      return;
+    }
+
+    const agent = context.paseo.agents.ref(event.agent.id);
+    if (/\brm\s+-rf\b/.test(command)) {
+      await agent.respondToPermission({
+        requestId: event.request.id,
+        response: { behavior: "deny", message: "Recursive deletion is blocked." },
+      });
+      return;
+    }
+
+    if (command.trim() === "git status") {
+      await agent.respondToPermission({
+        requestId: event.request.id,
+        response: { behavior: "allow" },
+      });
+    }
+  });
+
+  return () => {};
+}
+```
+
+| 请求             | 结果                 |
+| ---------------- | -------------------- |
+| `rm -rf build`   | 拒绝                 |
+| `git status`     | 批准                 |
+| 其他命令或请求   | 保持待处理，留给用户 |
+| 已经处理过的请求 | SDK 响应失败         |
+
+这个正则表达式只是一个示例策略，而不是 shell 解析器。权限请求也可能是问题、计划和模式变更；请求权限不会结束当前轮次。
+
+## agent.permission.after {#agentpermissionafter}
+
+待处理请求得到回应或清除后触发，收到 `{ agent, requestId, resolution }`；`resolution` 为 `AgentPermissionResponse`。
+
+```ts
+server.addHook("agent.permission.after", async ({ agent, requestId, resolution }) => {
+  console.log(agent, requestId, resolution);
+});
+```
+
+Agent 钩子不包括 daemon 的私有临时辅助 Agent。后台 Agent 和后台工作区中的 Agent 使用相同钩子。
+
+## 顺序与返回值 {#ordering-and-returned-values}
+
+```text
+Creation request
+  → agent.create.before hooks (plugin-ID order; registration order within each plugin)
+  → 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
+  → open provider session and save agent configuration
+```
+
+| 回调返回                                                | 下一个回调收到                    |
+| ------------------------------------------------------- | --------------------------------- |
+| `{ ...request, env: { ...request.env, REGION: "eu" } }` | 之前的请求，添加或替换了 `REGION` |
+| `{ ...request, env: { REGION: "eu" } }`                 | 之前的请求，整个覆盖映射被替换    |
+| `undefined`                                             | 未改变的请求                      |
+| 抛出错误或返回无效数据                                  | 操作失败；后面的回调不会运行      |
+
+没有自动的深度合并。`env` 在插件之间累积；`tools` 和 `mcpServers` 只在同一插件的回调之间累积。
+返回替换的映射或数组会替换该范围内之前的值。
+
+## context 与清理 {#context-and-cleanup}
+
+| 契约                       | 行为                                                                               |
+| -------------------------- | ---------------------------------------------------------------------------------- |
+| `context.paseo`            | 已连接到此 daemon 的现有 SDK                                                       |
+| `context.signal`           | 在调用超时或插件停止时中止；请把它传给外部请求                                     |
+| 输入数据                   | 分离的快照；通过返回的请求或 SDK 命令改变状态                                      |
+| 注册结果                   | 幂等的移除函数，例如 `const remove = server.addHook(...); remove();`               |
+| 重新加载、停用、移除、关闭 | 移除剩余的注册                                                                     |
+| 未知的钩子名称             | 注册失败                                                                           |
+| 钩子超时                   | 30 秒；会中止 signal。等待型钩子会让待处理的操作失败；事件处理函数会记录一条错误。 |
+| 事件处理函数出错           | 记录在插件名下；原操作继续进行                                                     |
+| 事件投递                   | 实时、尽力而为；没有重放、持久化或自动重试                                         |
+| 事件并发                   | 不同的事件可能重叠；不保证回调完成的顺序                                           |
+
+## 完整示例 {#complete-examples}
+
+| 插件                                                                                                   | 包含                                                      |
+| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
+| [lifecycle-logger](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-logger)       | Agent、工作区和 worktree 钩子；隐去环境变量值的 JSON 日志 |
+| [lifecycle-actions](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-actions)     | 后续消息、权限、环境变量、切换 Provider、选择 worktree    |
+| [agent-configuration](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-configuration) | MCP 注入以及 Codex 沙盒/批准选项                          |
+| [agent-tools](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-tools)                 | 按标签选择 Agent，并在插件进程中执行文件操作的工具        |
+
+用 `paseo plugin logs lifecycle-logger` 或主机的 `daemon.log` 读取 logger 的输出。
+
+## 已重命名的钩子 {#renamed-hooks}
+
+旧注册方法已弃用，会在 2027-04-30 之后移除。现有插件继续按原来的方式运行。同一插件中混合使用新旧注册方法时，处理函数按注册顺序运行。`addHook` 只接受新名称。
+
+| 旧注册方式                                         | 新注册方式                                                |
+| -------------------------------------------------- | --------------------------------------------------------- |
+| `server.before("workspace.create", handler)`       | `server.addHook("workspace.create.before", asyncHandler)` |
+| `server.on("workspace.created", handler)`          | `server.addHook("workspace.create.after", asyncHandler)`  |
+| `server.on("workspace.archived", handler)`         | `server.addHook("workspace.archive.after", asyncHandler)` |
+| `server.before("agent.create", handler)`           | `server.addHook("agent.create.before", asyncHandler)`     |
+| `server.on("agent.created", handler)`              | `server.addHook("agent.create.after", asyncHandler)`      |
+| `server.before("agent.session_open", handler)`     | `server.addHook("agent.open.before", asyncHandler)`       |
+| `server.on("agent.closed", handler)`               | `server.addHook("agent.close.after", asyncHandler)`       |
+| `server.on("agent.archived", handler)`             | `server.addHook("agent.archive.after", asyncHandler)`     |
+| `server.on("agent.turn_started", handler)`         | `server.addHook("agent.turn.before", asyncHandler)`       |
+| `server.on("agent.turn_ended", handler)`           | `server.addHook("agent.turn.after", asyncHandler)`        |
+| `server.on("agent.permission_requested", handler)` | `server.addHook("agent.permission.before", asyncHandler)` |
+| `server.on("agent.permission_resolved", handler)`  | `server.addHook("agent.permission.after", asyncHandler)`  |
diff --git a/public-docs/plugins/migration.md b/public-docs/plugins/migration.md
index fdefda5971..d4b247a16c 100644
--- a/public-docs/plugins/migration.md
+++ b/public-docs/plugins/migration.md
@@ -144,8 +144,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
 
diff --git a/public-docs/plugins/providers.md b/public-docs/plugins/providers.md
index 6fbe766c61..9a87dfb155 100644
--- a/public-docs/plugins/providers.md
+++ b/public-docs/plugins/providers.md
@@ -287,6 +287,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.
diff --git a/public-docs/plugins/reference.md b/public-docs/plugins/reference.md
index 81b99b0dd0..5e88cf9bf5 100644
--- a/public-docs/plugins/reference.md
+++ b/public-docs/plugins/reference.md
@@ -2,7 +2,7 @@
 title: Plugin reference
 description: Local plugin files, client and server runtimes, platform limits, contributions, RPCs, lifecycle, hosts, and CLI commands.
 nav: Reference
-order: 48
+order: 49
 category: Plugins
 ---
 
@@ -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
@@ -628,340 +628,11 @@ export default function contribute(client: PluginClientContext) {
 }
 ```
 
-Cleanup can be async. Release timers, watchers, sockets, and other resources created by the plugin. Paseo also removes registrations, unmounts surfaces, rejects pending RPCs, closes the plugin's daemon session, and stops its subprocess on reload, disable, removal, disconnect, or daemon shutdown.
+Cleanup can be async. Release timers, watchers, sockets, and other resources created by the plugin. Reload, disable, and removal dispose the affected installation. Stopping a server plugin also closes its daemon session and stops its subprocess. Client installations follow [Hosts and lifecycle](#hosts-and-lifecycle), including retention during a temporary disconnect.
 
 ## Lifecycle hooks
 
-In `index.server.ts`:
-
-```ts
-import type { PluginServerContext } from "@getpaseo/plugin/server";
-
-export default function contribute(server: PluginServerContext) {
-  server.on("agent.turn_ended", (event) => {
-    console.log(event.agent.id, event.outcome);
-  });
-
-  return () => {};
-}
-```
-
-| Register                        | Callback receives                  | Return                                                       |
-| ------------------------------- | ---------------------------------- | ------------------------------------------------------------ |
-| `server.on(name, callback)`     | `(event, { paseo, signal })`       | `void` or `Promise<void>`                                    |
-| `server.before(name, callback)` | `({ request }, { paseo, signal })` | Modified request, or `undefined` to keep it; async supported |
-
-Hooks run on the daemon while the plugin is enabled, even with no app connected.
-
-### Change configuration and inject an MCP server
-
-Add this callback inside `contribute(server)`. Replace the placeholder URL with your MCP endpoint.
-
-```ts
-server.before("agent.create", ({ request }) => {
-  if (request.config.provider !== "codex") {
-    return request;
-  }
-
-  return {
-    ...request,
-    config: {
-      ...request.config,
-      providerOptions: {
-        ...request.config.providerOptions,
-        sandbox_mode: "workspace-write",
-        approval_policy: "on-request",
-      },
-      mcpServers: {
-        ...request.config.mcpServers,
-        company: {
-          type: "http",
-          url: "https://tools.example.com/mcp",
-        },
-      },
-    },
-  };
-});
-```
-
-| Input                                       | Result                        |
-| ------------------------------------------- | ----------------------------- |
-| `providerOptions.sandbox_mode: "read-only"` | `"workspace-write"`           |
-| `providerOptions.web_search: "disabled"`    | Preserved by the spread       |
-| Existing `mcpServers.search`                | Preserved by the spread       |
-| Existing `mcpServers.company`               | Replaced with the entry above |
-
-The selected provider validates `providerOptions` and must support the configured MCP servers.
-Explicit Codex sandbox and approval options override its mode presets.
-
-### Inject environment variables on every session opening
-
-```ts
-server.before("agent.session_open", ({ request }) => {
-  return {
-    ...request,
-    env: {
-      ...request.env,
-      COMPANY_ENV: "development",
-    },
-  };
-});
-```
-
-This runs on create, resume, refresh, and import. To inject only on creation, set `env` in an
-`agent.create` callback instead.
-
-### Choose workspace isolation
-
-```ts
-server.before("workspace.create", ({ request }) => {
-  if (request.source.kind !== "directory") {
-    return request;
-  }
-
-  return {
-    ...request,
-    source: {
-      kind: "worktree",
-      cwd: request.source.path,
-      action: "branch-off",
-    },
-  };
-});
-```
-
-**Result:** an explicit directory creation request becomes a worktree request. Existing workspaces
-and directory lookup/import operations are unaffected.
-
-### Send a follow-up when a turn ends
-
-Copy [server/inspect.ts](https://github.com/getpaseo/paseo/blob/main/plugin-examples/lifecycle-actions/server/inspect.ts)
-into your plugin. The helper imports types from `@getpaseo/protocol/agent-types`; add
-`@getpaseo/protocol` at the same version as your plugin SDK to your development dependencies
-and install them before loading the plugin. `latestOutputText` joins text chunks after the latest user message.
-
-```ts
-import type { PluginServerContext } from "@getpaseo/plugin/server";
-import { latestOutputText } from "./server/inspect";
-
-export default function contribute(server: PluginServerContext) {
-  server.on("agent.turn_ended", async (event, context) => {
-    if (event.outcome.kind === "canceled") {
-      return;
-    }
-
-    const agent = context.paseo.agents.ref(event.agent.id);
-    const page = await agent.timeline.refetch({ direction: "tail", limit: 20 });
-    const text = latestOutputText(page.entries.map(({ item }) => item));
-    if (/out of credits/i.test(text)) {
-      await agent.send("Try again.");
-    }
-  });
-
-  return () => {};
-}
-```
-
-```text
-Turn ends: "out of credits"
-  → plugin sends "Try again."
-  → a new turn starts
-```
-
-The handler fetches only the last 20 timeline items. Output before that page is not inspected.
-Use `cursor` and `direction` to page further when your plugin needs more history.
-
-This sends a new message with the existing SDK. Persistent matches keep sending follow-ups;
-add limits or delays in your plugin when needed. Attachments and tool effects are not replayed.
-
-### Answer a permission request
-
-Using `shellCommand` from the same [helper file](https://github.com/getpaseo/paseo/blob/main/plugin-examples/lifecycle-actions/server/inspect.ts):
-
-```ts
-import type { PluginServerContext } from "@getpaseo/plugin/server";
-import { shellCommand } from "./server/inspect";
-
-export default function contribute(server: PluginServerContext) {
-  server.on("agent.permission_requested", async (event, context) => {
-    const command = shellCommand(event.request);
-    if (command === null) {
-      return;
-    }
-
-    const agent = context.paseo.agents.ref(event.agent.id);
-    if (/\brm\s+-rf\b/.test(command)) {
-      await agent.respondToPermission({
-        requestId: event.request.id,
-        response: { behavior: "deny", message: "Recursive deletion is blocked." },
-      });
-      return;
-    }
-
-    if (command.trim() === "git status") {
-      await agent.respondToPermission({
-        requestId: event.request.id,
-        response: { behavior: "allow" },
-      });
-    }
-  });
-
-  return () => {};
-}
-```
-
-| Request                  | Result                    |
-| ------------------------ | ------------------------- |
-| `rm -rf build`           | Declined                  |
-| `git status`             | Approved                  |
-| Other command or request | Left pending for the user |
-| Already-resolved request | SDK response fails        |
-
-The regex is an example policy, not a shell parser. Permission requests can also be questions,
-plans, and mode changes; requesting permission does not end the turn.
-
-### Events
-
-| Name                         | Event fields                                            | Trigger                                            |
-| ---------------------------- | ------------------------------------------------------- | -------------------------------------------------- |
-| `agent.created`              | `agent`                                                 | Ordinary creation finishes; excludes import/resume |
-| `agent.closed`               | `agent`                                                 | A live agent runtime closes                        |
-| `agent.turn_started`         | `agent`, `turnId`                                       | Live turn starts                                   |
-| `agent.turn_ended`           | `agent`, `turnId`, `outcome`, deprecated `timeline: []` | Live turn completes, fails, or is canceled         |
-| `agent.permission_requested` | `agent`, `request`                                      | Permission or question becomes pending             |
-| `agent.permission_resolved`  | `agent`, `requestId`, `resolution`                      | Pending request is answered or cleared             |
-| `agent.archived`             | `agent`, `archivedAt`                                   | Archive state is saved                             |
-| `workspace.created`          | `workspace`                                             | Record created; directory available                |
-| `workspace.archived`         | `workspace`                                             | Archive state is saved                             |
-
-Agent events exclude the daemon's private disposable helpers. Public background workspaces and
-their ordinary agents run the same lifecycle hooks as other workspaces. Archive events can precede
-runtime/worktree cleanup; observe lifecycle completion separately when cleanup matters.
-
-`agent.turn_ended.timeline` is deprecated and always empty. Fetch history on demand with
-`context.paseo.agents.ref(event.agent.id).timeline.refetch({ direction: "tail", limit: 20 })`.
-The hook payload size does not grow with conversation history.
-
-**Shared payload shapes** (`@getpaseo/plugin/server`):
-
-```ts
-interface PluginHookAgent {
-  id: string;
-  workspaceId: string | null;
-  parentAgentId: string | null;
-  provider: string;
-  cwd: string;
-  title: string | null;
-}
-
-interface PluginHookWorkspace {
-  id: string;
-  projectId: string;
-  cwd: string;
-  name: string | null;
-  archivedAt: string | null;
-}
-
-type PluginTurnOutcome =
-  | { kind: "completed" }
-  | { kind: "failed"; error: { message: string; code?: string } }
-  | { kind: "canceled"; reason: string };
-```
-
-| Field        | Shape / meaning                                                                                       |
-| ------------ | ----------------------------------------------------------------------------------------------------- |
-| `turnId`     | Provider-reported `string` or `null`; can repeat after a session reopens                              |
-| `timeline`   | `readonly AgentTimelineItem[]`; complete snapshot including earlier conversation; text may span items |
-| `request`    | SDK `AgentPermissionRequest`; `kind` is `tool`, `plan`, `question`, `mode`, or `other`                |
-| `resolution` | SDK `AgentPermissionResponse`                                                                         |
-| `archivedAt` | Timestamp string                                                                                      |
-
-### Before hooks
-
-| Name                 | Request fields                                                          | Editable                                |
-| -------------------- | ----------------------------------------------------------------------- | --------------------------------------- |
-| `agent.create`       | `config`, optional `env`                                                | Public agent config except `cwd`; `env` |
-| `agent.session_open` | `agentId`, `workspaceId`, `provider`, `cwd`, `reason`, `purpose`, `env` | Only `env`                              |
-| `workspace.create`   | `source`, optional `title`, `firstAgentContext`                         | Entire explicit creation request        |
-
-**`agent.create.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                                                              |
-
-**`agent.session_open` request example:**
-
-```json
-{
-  "agentId": "agent-123",
-  "workspaceId": "workspace-456",
-  "provider": "codex",
-  "cwd": "/projects/shop",
-  "reason": "resume",
-  "purpose": "interactive",
-  "env": { "COMPANY_ENV": "development" }
-}
-```
-
-| Field         | Values                                                                                                                  |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `workspaceId` | String or `null`                                                                                                        |
-| `reason`      | `create`, `resume`, `refresh`, `import`                                                                                 |
-| `purpose`     | `interactive`, `history`                                                                                                |
-| `env`         | Launch override map; excludes the daemon's inherited environment. Replace the map to add, replace, or remove overrides. |
-
-### Ordering and returned values
-
-```text
-Creation request
-  → agent.create hooks (plugin-ID order; registration order within each plugin)
-  → resolve defaults and validate provider configuration
-  → derive launch configuration with Paseo runtime tools and daemon prompt
-  → agent.session_open hooks (same ordering; env only)
-  → set PASEO_AGENT_ID and PASEO_AGENT_CWD
-  → open provider session and save agent configuration
-```
-
-| Callback returns                                        | Next callback receives                              |
-| ------------------------------------------------------- | --------------------------------------------------- |
-| `{ ...request, env: { ...request.env, REGION: "eu" } }` | Prior request with `REGION` added/replaced          |
-| `{ ...request, env: { REGION: "eu" } }`                 | Prior request with the entire override map replaced |
-| `undefined`                                             | Unchanged request                                   |
-| Throws or returns invalid data                          | Operation fails; later callbacks do not run         |
-
-No automatic deep merge. Later callbacks can overwrite earlier values. Agent configuration is
-saved; environment overrides are not persisted with it.
-
-### Context and cleanup
-
-| Contract                           | Behavior                                                                                                  |
-| ---------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `context.paseo`                    | Existing SDK connected to this daemon                                                                     |
-| `context.signal`                   | Aborted on invocation timeout or plugin stop; pass to external requests                                   |
-| Input data                         | Detached snapshot; change state through returned requests or SDK commands                                 |
-| Registration result                | Idempotent remover, e.g. `const remove = server.on(...); remove();`                                       |
-| Reload, disable, removal, shutdown | Remaining registrations removed                                                                           |
-| Unknown hook name                  | Registration fails                                                                                        |
-| Hook timeout                       | 30 seconds; aborts the signal. A before hook fails the pending operation; an event handler logs an error. |
-| Event-handler error                | Logged against plugin; original operation continues                                                       |
-| Event delivery                     | Live, best effort; no replay, persistence, or automatic retry                                             |
-| Event concurrency                  | Different events may overlap; callback completion order is not guaranteed                                 |
-
-### Complete examples
-
-| Plugin                                                                                                 | Includes                                                                     |
-| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
-| [lifecycle-logger](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-logger)       | All eleven hooks; JSON logs with environment values redacted                 |
-| [lifecycle-actions](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-actions)     | Follow-ups, permissions, environment, provider switching, worktree selection |
-| [agent-configuration](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-configuration) | MCP injection and Codex sandbox/approval options                             |
-
-Read logger output with `paseo plugin logs lifecycle-logger` or the host's `daemon.log`.
+Register async handlers with `server.addHook(name, handler)`. See [Hooks](/docs/plugins/hooks) for names, payloads, ordering, errors, and complete examples.
 
 ## Screens and sidebar items
 
@@ -1631,8 +1302,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
@@ -2226,7 +1900,10 @@ decisions.
 `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({
@@ -2346,7 +2023,7 @@ Hiding preserves the registration, so showing it again restores its position. It
 an action already in progress.
 
 `remove()` is idempotent. Updates after removal do nothing. Paseo removes outstanding buttons when
-the plugin installation or host connection is torn down. Return cleanup from the client entry for
+the plugin installation is disposed (see [Hosts and lifecycle](#hosts-and-lifecycle)). Return cleanup from the client entry for
 your subscriptions, timers, and other resources.
 
 ## Use the Paseo SDK
@@ -2407,6 +2084,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
@@ -2551,10 +2230,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:
@@ -2674,9 +2511,11 @@ Plugins are installed per daemon. When the same contribution exists on several c
 
 Attachment sources remain scoped to each composer's host.
 
-Workspace panels and Command Center items stay scoped to the active host and exact cached context.
-Reload replaces their registrations. Disable, removal, host disconnect, and evaluation failure
-remove Command Center items and clear the installation's query state. An already-restored panel tab
+A dropped connection keeps client plugin registrations, mounted surfaces, local state, and query caches. Reconnecting through the existing `DaemonClient` object keeps unchanged installations and refreshes their settings. Consume SDK observation snapshots to refresh other daemon state; setup does not run again for an unchanged installation. Daemon calls still depend on connectivity.
+
+Switching connections (for example, from direct to relay) currently replaces the `DaemonClient` object and reinstalls client plugins. Reload, changed bundles or requirements, disable, plugin removal, and host removal also dispose affected installations and clear their query state. A replacement that fails evaluation leaves its contributions unavailable.
+
+Workspace panels and Command Center items stay scoped to the active host and exact cached context. An already-restored panel tab
 remains as unavailable until its matching contribution returns or the user closes it. Panel render
 failures stay inside the plugin error boundary.
 
diff --git a/public-docs/plugins/reference.zh-CN.md b/public-docs/plugins/reference.zh-CN.md
index 62caec83e5..bb979f52e2 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 参考。                                                                                    |
@@ -504,326 +504,11 @@ export default function contribute(client: PluginClientContext) {
 }
 ```
 
-清理函数可以是异步的。请释放插件创建的计时器、监听器、套接字和其他资源。在重新加载、停用、移除、断开连接或 daemon 关闭时，Paseo 还会移除注册、卸载界面、reject 待处理的 RPC、关闭插件的 daemon 会话并停止它的子进程。
+清理函数可以是异步的。请释放插件创建的计时器、监听器、套接字和其他资源。重新加载、停用和移除会销毁受影响的插件安装。停止服务端插件还会关闭它的 daemon 会话并停止其子进程。客户端安装遵循[主机与生命周期](#hosts-and-lifecycle)中的规则，包括在暂时断开连接时保留安装。
 
 ## 生命周期钩子 {#lifecycle-hooks}
 
-在 `index.server.ts` 中：
-
-```ts
-import type { PluginServerContext } from "@getpaseo/plugin/server";
-
-export default function contribute(server: PluginServerContext) {
-  server.on("agent.turn_ended", (event) => {
-    console.log(event.agent.id, event.outcome);
-  });
-
-  return () => {};
-}
-```
-
-| 注册                            | 回调接收                           | 返回                                                |
-| ------------------------------- | ---------------------------------- | --------------------------------------------------- |
-| `server.on(name, callback)`     | `(event, { paseo, signal })`       | `void` 或 `Promise<void>`                           |
-| `server.before(name, callback)` | `({ request }, { paseo, signal })` | 修改后的请求，或返回 `undefined` 保持不变；支持异步 |
-
-只要插件处于启用状态，钩子就会在 daemon 上运行，即使没有应用连接。
-
-### 修改配置并注入 MCP 服务器 {#change-configuration-and-inject-an-mcp-server}
-
-在 `contribute(server)` 中添加这个回调。把占位 URL 替换为你的 MCP 端点。
-
-```ts
-server.before("agent.create", ({ request }) => {
-  if (request.config.provider !== "codex") {
-    return request;
-  }
-
-  return {
-    ...request,
-    config: {
-      ...request.config,
-      providerOptions: {
-        ...request.config.providerOptions,
-        sandbox_mode: "workspace-write",
-        approval_policy: "on-request",
-      },
-      mcpServers: {
-        ...request.config.mcpServers,
-        company: {
-          type: "http",
-          url: "https://tools.example.com/mcp",
-        },
-      },
-    },
-  };
-});
-```
-
-| 输入                                        | 结果                |
-| ------------------------------------------- | ------------------- |
-| `providerOptions.sandbox_mode: "read-only"` | `"workspace-write"` |
-| `providerOptions.web_search: "disabled"`    | 由展开运算保留      |
-| 已有的 `mcpServers.search`                  | 由展开运算保留      |
-| 已有的 `mcpServers.company`                 | 被替换为上面的条目  |
-
-所选的 Provider 会校验 `providerOptions`，并且必须支持配置的 MCP 服务器。显式的 Codex 沙盒和批准选项会覆盖它的模式预设。
-
-### 在每次打开会话时注入环境变量 {#inject-environment-variables-on-every-session-opening}
-
-```ts
-server.before("agent.session_open", ({ request }) => {
-  return {
-    ...request,
-    env: {
-      ...request.env,
-      COMPANY_ENV: "development",
-    },
-  };
-});
-```
-
-它会在创建、恢复、刷新和导入时运行。如果只想在创建时注入，请改为在 `agent.create` 回调中设置 `env`。
-
-### 选择工作区隔离方式 {#choose-workspace-isolation}
-
-```ts
-server.before("workspace.create", ({ request }) => {
-  if (request.source.kind !== "directory") {
-    return request;
-  }
-
-  return {
-    ...request,
-    source: {
-      kind: "worktree",
-      cwd: request.source.path,
-      action: "branch-off",
-    },
-  };
-});
-```
-
-**结果**：显式的目录创建请求会变成 worktree 请求。已有的工作区以及目录查找/导入操作不受影响。
-
-### 在轮次结束时发送后续消息 {#send-a-follow-up-when-a-turn-ends}
-
-把 [server/inspect.ts](https://github.com/getpaseo/paseo/blob/main/plugin-examples/lifecycle-actions/server/inspect.ts) 复制到你的插件中。该辅助文件从 `@getpaseo/protocol/agent-types` 导入类型；请把与插件 SDK 版本相同的 `@getpaseo/protocol` 加入开发依赖，并在加载插件之前安装它们。`latestOutputText` 会拼接最近一条用户消息之后的文本片段。
-
-```ts
-import type { PluginServerContext } from "@getpaseo/plugin/server";
-import { latestOutputText } from "./server/inspect";
-
-export default function contribute(server: PluginServerContext) {
-  server.on("agent.turn_ended", async (event, context) => {
-    if (event.outcome.kind === "canceled") {
-      return;
-    }
-
-    const agent = context.paseo.agents.ref(event.agent.id);
-    const page = await agent.timeline.refetch({ direction: "tail", limit: 20 });
-    const text = latestOutputText(page.entries.map(({ item }) => item));
-    if (/out of credits/i.test(text)) {
-      await agent.send("Try again.");
-    }
-  });
-
-  return () => {};
-}
-```
-
-```text
-Turn ends: "out of credits"
-  → plugin sends "Try again."
-  → a new turn starts
-```
-
-该处理函数只获取最近 20 条时间线条目，不检查这一页之前的输出。插件需要更多历史时，请用 `cursor` 和 `direction` 继续翻页。
-
-这会用现有的 SDK 发送一条新消息。持续匹配会不断发送后续消息；需要时请在插件中添加次数限制或延迟。附件和工具的效果不会被重放。
-
-### 回应权限请求 {#answer-a-permission-request}
-
-使用同一个[辅助文件](https://github.com/getpaseo/paseo/blob/main/plugin-examples/lifecycle-actions/server/inspect.ts)中的 `shellCommand`：
-
-```ts
-import type { PluginServerContext } from "@getpaseo/plugin/server";
-import { shellCommand } from "./server/inspect";
-
-export default function contribute(server: PluginServerContext) {
-  server.on("agent.permission_requested", async (event, context) => {
-    const command = shellCommand(event.request);
-    if (command === null) {
-      return;
-    }
-
-    const agent = context.paseo.agents.ref(event.agent.id);
-    if (/\brm\s+-rf\b/.test(command)) {
-      await agent.respondToPermission({
-        requestId: event.request.id,
-        response: { behavior: "deny", message: "Recursive deletion is blocked." },
-      });
-      return;
-    }
-
-    if (command.trim() === "git status") {
-      await agent.respondToPermission({
-        requestId: event.request.id,
-        response: { behavior: "allow" },
-      });
-    }
-  });
-
-  return () => {};
-}
-```
-
-| 请求             | 结果                 |
-| ---------------- | -------------------- |
-| `rm -rf build`   | 拒绝                 |
-| `git status`     | 批准                 |
-| 其他命令或请求   | 保持待处理，留给用户 |
-| 已经处理过的请求 | SDK 响应失败         |
-
-这个正则表达式只是一个示例策略，而不是 shell 解析器。权限请求也可能是问题、计划和模式变更；请求权限不会结束当前轮次。
-
-### 事件 {#events}
-
-| 名称                         | 事件字段                                              | 触发时机                      |
-| ---------------------------- | ----------------------------------------------------- | ----------------------------- |
-| `agent.created`              | `agent`                                               | 普通创建完成；不包括导入/恢复 |
-| `agent.closed`               | `agent`                                               | 一个运行中的 Agent 运行时关闭 |
-| `agent.turn_started`         | `agent`, `turnId`                                     | 实时轮次开始                  |
-| `agent.turn_ended`           | `agent`, `turnId`, `outcome`, 已弃用的 `timeline: []` | 实时轮次完成、失败或被取消    |
-| `agent.permission_requested` | `agent`, `request`                                    | 权限请求或问题进入待处理状态  |
-| `agent.permission_resolved`  | `agent`, `requestId`, `resolution`                    | 待处理的请求得到回应或被清除  |
-| `agent.archived`             | `agent`, `archivedAt`                                 | 归档状态已保存                |
-| `workspace.created`          | `workspace`                                           | 记录已创建；目录可用          |
-| `workspace.archived`         | `workspace`                                           | 归档状态已保存                |
-
-Agent 事件不包括 daemon 私有的一次性辅助 Agent。公开的后台工作区及其普通 Agent 与其他工作区运行相同的生命周期钩子。归档事件可能早于运行时/worktree 清理；当清理很重要时，请单独观察生命周期何时完成。
-
-`agent.turn_ended.timeline` 已弃用，并且始终为空。需要历史时，请用 `context.paseo.agents.ref(event.agent.id).timeline.refetch({ direction: "tail", limit: 20 })` 按需获取。钩子负载的大小不会随对话历史增长。
-
-**共享的负载结构**（`@getpaseo/plugin/server`）：
-
-```ts
-interface PluginHookAgent {
-  id: string;
-  workspaceId: string | null;
-  parentAgentId: string | null;
-  provider: string;
-  cwd: string;
-  title: string | null;
-}
-
-interface PluginHookWorkspace {
-  id: string;
-  projectId: string;
-  cwd: string;
-  name: string | null;
-  archivedAt: string | null;
-}
-
-type PluginTurnOutcome =
-  | { kind: "completed" }
-  | { kind: "failed"; error: { message: string; code?: string } }
-  | { kind: "canceled"; reason: string };
-```
-
-| 字段         | 结构 / 含义                                                                              |
-| ------------ | ---------------------------------------------------------------------------------------- |
-| `turnId`     | Provider 报告的 `string` 或 `null`；会话重新打开后可能重复                               |
-| `timeline`   | `readonly AgentTimelineItem[]`；包含之前对话的完整快照；文本可能跨越多个条目             |
-| `request`    | SDK 的 `AgentPermissionRequest`；`kind` 为 `tool`、`plan`、`question`、`mode` 或 `other` |
-| `resolution` | SDK 的 `AgentPermissionResponse`                                                         |
-| `archivedAt` | 时间戳字符串                                                                             |
-
-### before 钩子 {#before-hooks}
-
-| 名称                 | 请求字段                                                                | 可编辑                              |
-| -------------------- | ----------------------------------------------------------------------- | ----------------------------------- |
-| `agent.create`       | `config`，可选的 `env`                                                  | 除 `cwd` 外的公开 Agent 配置；`env` |
-| `agent.session_open` | `agentId`, `workspaceId`, `provider`, `cwd`, `reason`, `purpose`, `env` | 仅 `env`                            |
-| `workspace.create`   | `source`，可选的 `title`，`firstAgentContext`                           | 整个显式创建请求                    |
-
-**`agent.create.config`** 使用 `AgentSessionConfig`：
-
-| 字段                                          | 约束                                                     |
-| --------------------------------------------- | -------------------------------------------------------- |
-| `provider`, `model`                           | 独立的字段；修改 Provider 可能需要同时修改模型/模式/选项 |
-| `modeId`, `thinkingOptionId`, `featureValues` | 特定于 Provider 的选择                                   |
-| `title`, `systemPrompt`                       | Agent 配置                                               |
-| `providerOptions`                             | 不透明的、特定于 Provider 的选项                         |
-| `mcpServers`, `toolPolicy`                    | MCP 配置和精确的工具预批准                               |
-| `cwd`                                         | 不能修改                                                 |
-
-**`agent.session_open` 请求示例：**
-
-```json
-{
-  "agentId": "agent-123",
-  "workspaceId": "workspace-456",
-  "provider": "codex",
-  "cwd": "/projects/shop",
-  "reason": "resume",
-  "purpose": "interactive",
-  "env": { "COMPANY_ENV": "development" }
-}
-```
-
-| 字段          | 取值                                                                                 |
-| ------------- | ------------------------------------------------------------------------------------ |
-| `workspaceId` | 字符串或 `null`                                                                      |
-| `reason`      | `create`、`resume`、`refresh`、`import`                                              |
-| `purpose`     | `interactive`、`history`                                                             |
-| `env`         | 启动覆盖映射；不包括 daemon 继承的环境变量。替换整个映射即可添加、替换或移除覆盖项。 |
-
-### 顺序与返回值 {#ordering-and-returned-values}
-
-```text
-Creation request
-  → agent.create hooks (plugin-ID order; registration order within each plugin)
-  → resolve defaults and validate provider configuration
-  → derive launch configuration with Paseo runtime tools and daemon prompt
-  → agent.session_open hooks (same ordering; env only)
-  → set PASEO_AGENT_ID and PASEO_AGENT_CWD
-  → open provider session and save agent configuration
-```
-
-| 回调返回                                                | 下一个回调收到                    |
-| ------------------------------------------------------- | --------------------------------- |
-| `{ ...request, env: { ...request.env, REGION: "eu" } }` | 之前的请求，添加或替换了 `REGION` |
-| `{ ...request, env: { REGION: "eu" } }`                 | 之前的请求，整个覆盖映射被替换    |
-| `undefined`                                             | 未改变的请求                      |
-| 抛出错误或返回无效数据                                  | 操作失败；后面的回调不会运行      |
-
-没有自动的深度合并。后面的回调可以覆盖前面的值。Agent 配置会被保存；环境变量覆盖项不会随之持久化。
-
-### context 与清理 {#context-and-cleanup}
-
-| 契约                       | 行为                                                                                |
-| -------------------------- | ----------------------------------------------------------------------------------- |
-| `context.paseo`            | 已连接到此 daemon 的现有 SDK                                                        |
-| `context.signal`           | 在调用超时或插件停止时中止；请把它传给外部请求                                      |
-| 输入数据                   | 分离的快照；通过返回的请求或 SDK 命令改变状态                                       |
-| 注册结果                   | 幂等的移除函数，例如 `const remove = server.on(...); remove();`                     |
-| 重新加载、停用、移除、关闭 | 移除剩余的注册                                                                      |
-| 未知的钩子名称             | 注册失败                                                                            |
-| 钩子超时                   | 30 秒；会中止 signal。before 钩子会让待处理的操作失败；事件处理函数会记录一条错误。 |
-| 事件处理函数出错           | 记录在插件名下；原操作继续进行                                                      |
-| 事件投递                   | 实时、尽力而为；没有重放、持久化或自动重试                                          |
-| 事件并发                   | 不同的事件可能重叠；不保证回调完成的顺序                                            |
-
-### 完整示例 {#complete-examples}
-
-| 插件                                                                                                   | 包含                                                   |
-| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
-| [lifecycle-logger](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-logger)       | 全部十一个钩子；隐去环境变量值的 JSON 日志             |
-| [lifecycle-actions](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-actions)     | 后续消息、权限、环境变量、切换 Provider、选择 worktree |
-| [agent-configuration](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-configuration) | MCP 注入以及 Codex 沙盒/批准选项                       |
-
-用 `paseo plugin logs lifecycle-logger` 或主机的 `daemon.log` 读取 logger 的输出。
+使用 `server.addHook(name, handler)` 注册异步处理函数。请参阅[钩子](/docs/plugins/hooks)，了解命名、载荷、顺序、错误处理和完整示例。
 
 ## 界面和侧边栏项 {#screens-and-sidebar-items}
 
@@ -1069,7 +754,7 @@ export function IssueActions({ theme }: PluginSurfaceProps) {
 ```tsx
 import { Markdown } from "@getpaseo/plugin/client/ui";
 
-<Markdown>{"## 审查\n\n检查**通过**。"}</Markdown>;
+<Markdown>{"## Review\n\nThe checks **passed**."}</Markdown>;
 ```
 
 `children` 是唯一的属性，必须为字符串。更新它会立即渲染新内容；空字符串不渲染任何内容。
@@ -1402,7 +1087,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)` 可以打开你自己的某个界面。即使多台主机安装了同一个插件，每次安装也有各自的值和路由。
 
@@ -2033,7 +1718,7 @@ const behavior: PluginButtonBehavior = {
 隐藏或禁用按钮会关闭它的浮层。更新它的 behavior 也会关闭浮层。隐藏会保留注册，因此再次显示时会恢复它
 原来的位置。它不会取消已经在进行中的操作。
 
-`remove()` 是幂等的。移除之后的更新不起作用。当插件安装或主机连接被拆除时，Paseo 会移除尚存的按钮。
+`remove()` 是幂等的。移除之后的更新不起作用。当插件安装被销毁时，Paseo 会移除尚存的按钮（参见[主机与生命周期](#hosts-and-lifecycle)）。
 请从客户端入口返回清理函数，用来释放你的订阅、定时器和其他资源。
 
 ## 使用 Paseo SDK {#use-the-paseo-sdk}
@@ -2094,6 +1779,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)` 对其中一台主机
@@ -2239,6 +1926,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：
@@ -2352,8 +2173,11 @@ Composer 菜单、搜索选择器、选中后的胶囊、草稿状态和提交
 
 附件来源仍然限定在各个 Composer 所在的主机上。
 
-工作区面板和 Command Center 条目仍然限定在当前活动的主机和确切的缓存上下文中。重新加载会替换它们的
-注册。停用、移除、主机断开和求值失败会移除 Command Center 条目，并清除该安装的查询状态。已经恢复的面板
+连接中断时，客户端插件的注册、已挂载界面、本地状态和查询缓存会保留。通过原有的 `DaemonClient` 对象重新连接时，未变化的安装会保留，其设置会刷新。请使用 SDK 观察快照刷新其他 daemon 状态；未变化的安装不会再次运行初始化函数。调用 daemon 仍然依赖连接。
+
+切换连接（例如从直连切换到中继）目前会替换 `DaemonClient` 对象并重新安装客户端插件。重新加载、插件包或版本要求变化、停用、移除插件和移除主机也会销毁受影响的安装，并清除其查询状态。如果替换安装求值失败，它的贡献将不可用。
+
+工作区面板和 Command Center 条目仍然限定在当前活动的主机和确切的缓存上下文中。已经恢复的面板
 标签页会保持“不可用”状态，直到与之匹配的贡献重新出现或用户关闭它。面板的渲染失败会被限制在插件的错误
 边界内。
 
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 9762323dce..81f077a9e1 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 190d4c9a48..69e8e8c5ad 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 2867261c32..5a095b2c2a 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 fcda38bc89..5879e9cab9 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/worktrees.md b/public-docs/worktrees/index.md
similarity index 88%
rename from public-docs/worktrees.md
rename to public-docs/worktrees/index.md
index 5bb1db793f..faabb2d81f 100644
--- a/public-docs/worktrees.md
+++ b/public-docs/worktrees/index.md
@@ -35,6 +35,8 @@ With a custom root, Paseo keeps the same hashed layout under that directory:
 }
 ```
 
+Plugins can choose a location anywhere on disk with [`worktree.create.before`](/docs/plugins/hooks#worktreecreatebefore). The [worktree-placement example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/worktree-placement) places worktrees next to the source checkout. Paseo validates the path, refuses an existing destination, and manages listing, archive, and deletion there. Recovery uses the recorded path without running creation hooks.
+
 1. Create a workspace with worktree isolation, Paseo creates the worktree and runs your setup hooks
 2. Launch one or more agents in that workspace
 3. Review the diff against the base branch
@@ -80,6 +82,10 @@ paseo workspace create \
 
 Add `--forge <name>` when Paseo cannot infer the forge from the source checkout.
 
+## Copy local files with .worktreeinclude
+
+Use [`.worktreeinclude`](/docs/worktrees/worktreeinclude) to copy selected gitignored files, such as `.env`, from your source checkout before setup runs.
+
 ## paseo.json
 
 Drop a `paseo.json` in your repo root. Paseo reads it from the committed version of the base branch you picked, so uncommitted changes in other branches don't apply.
@@ -99,12 +105,14 @@ Drop a `paseo.json` in your repo root. Paseo reads it from the committed version
 
 ## Setup and teardown
 
-`setup` runs once after the worktree is created. A fresh worktree has no installed dependencies and no ignored files (like `.env`), so use setup to install and copy what you need. `teardown` runs during archive, before the directory is removed.
+Plugins can use [`worktree.create.after`](/docs/plugins/hooks#worktreecreateafter) to write files before setup, terminals, and the first agent.
+
+`setup` runs once after the worktree is created. Use setup to install dependencies and run project initialization. Use [`.worktreeinclude`](#copy-local-files-with-worktreeinclude) to copy ignored files such as `.env`. `teardown` runs during archive, before the directory is removed.
 
 ```json
 {
   "worktree": {
-    "setup": "npm ci\ncp \"$PASEO_SOURCE_CHECKOUT_PATH/.env\" .env\nnpm run db:migrate",
+    "setup": "npm ci\nnpm run db:migrate",
     "teardown": "npm run db:drop || true"
   }
 }
diff --git a/public-docs/worktrees.zh-CN.md b/public-docs/worktrees/index.zh-CN.md
similarity index 88%
rename from public-docs/worktrees.zh-CN.md
rename to public-docs/worktrees/index.zh-CN.md
index 0bf3af55a4..cce65fc090 100644
--- a/public-docs/worktrees.zh-CN.md
+++ b/public-docs/worktrees/index.zh-CN.md
@@ -33,6 +33,8 @@ worktree 默认存放在 `$PASEO_HOME/worktrees/` 下，按源检出路径的哈
 }
 ```
 
+插件可以通过 [`worktree.create.before`](/docs/plugins/hooks#worktreecreatebefore) 将 worktree 放到磁盘上的自选位置。[worktree-placement 示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/worktree-placement) 将其放在源检出目录旁边。Paseo 验证路径并拒绝已存在的目标，同时支持在该位置列出、归档和删除 worktree。恢复时使用记录的原路径，不运行创建钩子。
+
 1. 创建一个使用 worktree 隔离的工作区，Paseo 会创建 worktree 并运行你的 setup 钩子
 2. 在该工作区中启动一个或多个 Agent
 3. 对照基础分支审查 diff
@@ -78,6 +80,10 @@ paseo workspace create \
 
 当 Paseo 无法从源检出推断代码托管平台时，添加 `--forge <name>`。
 
+## 使用 .worktreeinclude 复制本地文件 {#copy-local-files-with-worktreeinclude}
+
+使用 [`.worktreeinclude`](/docs/worktrees/worktreeinclude)，在 setup 运行前将 `.env` 等选定的 Git 忽略文件从源检出复制到新 worktree。
+
 ## paseo.json {#paseojson}
 
 在仓库根目录放一个 `paseo.json`。Paseo 从你所选基础分支的已提交版本中读取它，因此其他分支中未提交的改动不会生效。
@@ -97,12 +103,14 @@ paseo workspace create \
 
 ## Setup 与 teardown {#setup-and-teardown}
 
-`setup` 在 worktree 创建后运行一次。新的 worktree 没有安装依赖，也没有被忽略的文件（例如 `.env`），因此请用 setup 安装和复制你需要的内容。`teardown` 在归档期间、目录被删除之前运行。
+插件可以通过 [`worktree.create.after`](/docs/plugins/hooks#worktreecreateafter) 在 setup、终端和第一个 Agent 运行之前写入文件。
+
+`setup` 在 worktree 创建后运行一次。使用 setup 安装依赖并初始化项目。使用 [`.worktreeinclude`](#copy-local-files-with-worktreeinclude) 复制 `.env` 等被忽略的文件。`teardown` 在归档期间、目录被删除之前运行。
 
 ```json
 {
   "worktree": {
-    "setup": "npm ci\ncp \"$PASEO_SOURCE_CHECKOUT_PATH/.env\" .env\nnpm run db:migrate",
+    "setup": "npm ci\nnpm run db:migrate",
     "teardown": "npm run db:drop || true"
   }
 }
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/ci-workflow.test.mjs b/scripts/ci-workflow.test.mjs
index 4842870cc3..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";
@@ -24,7 +24,10 @@ const gatedCiJobs = new Map([
     "server-integration-windows",
     { name: "server-integration (windows-latest)", contract: "server" },
   ],
-  ["server-tests-macos", { name: "server-tests (macos-14, file observation)", contract: "server" }],
+  [
+    "server-tests-macos",
+    { name: "server-tests (macos-latest, file observation)", contract: "server" },
+  ],
   ["desktop-tests-ubuntu", { name: "desktop-tests (ubuntu-latest)", contract: "desktop" }],
   ["desktop-tests-windows", { name: "desktop-tests (windows-latest)", contract: "desktop" }],
   ["app-tests", { name: "app-tests", contract: "app" }],
@@ -137,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") ?? "";
@@ -157,6 +197,14 @@ test("focused contracts stay inside existing required checks", () => {
   assert.ok(!jobs.has("playwright-desktop"));
 });
 
+test("ordinary CI keeps app tests without prebuilding Android modules", () => {
+  const source = readFileSync(ciWorkflowPath, "utf8");
+  const app = jobBlocks(source).get("app-tests").join("\n");
+  assert.match(app, /npm run build:app-deps/);
+  assert.match(app, /npm run test --workspace=@getpaseo\/app/);
+  assert.doesNotMatch(source, /test:android|expo prebuild|gradlew|actions\/setup-java/);
+});
+
 test("server builds exclude test utilities at every domain depth", () => {
   const tsconfig = JSON.parse(readFileSync(serverTsconfigPath, "utf8"));
   assert.ok(tsconfig.exclude.includes("src/server/**/test-utils/**"));
@@ -483,14 +531,14 @@ test("Windows units and integration run independently with complete routed cover
   assert.equal(scripts.test, "npm run test:unit && npm run test:integration");
   assert.equal(scripts["test:unit"], 'vitest run --fileParallelism --exclude "**/*.e2e.test.ts"');
   const invocations = scripts["test:integration"].split(" && ");
-  // Each vitest start costs about half a minute on Windows, so the four
+  // Each vitest start costs about half a minute on Windows, so the
   // name-filtered files share one invocation and one combined filter.
   assert.equal(invocations.length, 2);
   assert.ok(invocations.every((command) => command.startsWith("vitest run --maxWorkers=1 ")));
   assert.doesNotMatch(invocations[0], / -t /);
   assert.equal(
     invocations[1],
-    'vitest run --maxWorkers=1 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"',
+    '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"',
   );
   const serverConfig = readFileSync(new URL("packages/server/vitest.config.ts", repoRoot), "utf8");
   assert.doesNotMatch(serverConfig, /maxWorkers/);
@@ -641,3 +689,75 @@ process.exit(code);
     });
   }
 });
+
+// GitHub retires macOS 14 on 2026-11-02; brownouts already reject these jobs.
+test("workflows avoid retired macOS 14 runners", () => {
+  for (const path of filesUnder(".github/workflows", (candidate) => /\.ya?ml$/.test(candidate))) {
+    assert.doesNotMatch(
+      readFileSync(new URL(path, repoRoot), "utf8"),
+      /macos-14(?:-large|-xlarge)?\b/,
+      path,
+    );
+  }
+});
+
+test("macOS jobs use latest runners while preserving release architectures", () => {
+  for (const [workflow, jobId] of [
+    [ciWorkflowPath, "server-tests-macos"],
+    [nixWorkflowPath, "build-desktop-darwin"],
+  ]) {
+    assert.match(
+      jobBlocks(readFileSync(workflow, "utf8")).get(jobId).join("\n"),
+      /^    runs-on: macos-latest$/m,
+    );
+  }
+  const release = readFileSync(new URL(".github/workflows/desktop-release.yml", repoRoot), "utf8");
+  assert.match(release, /runner: macos-latest\n\s+electron_arch: arm64/);
+  // 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/oxlint/paseo-plugin.mjs b/scripts/oxlint/paseo-plugin.mjs
index d6f8d0365e..af58021991 100644
--- a/scripts/oxlint/paseo-plugin.mjs
+++ b/scripts/oxlint/paseo-plugin.mjs
@@ -34,9 +34,130 @@ const noRawPressable = {
   },
 };
 
+const SYNC_IO_MODULES = new Set(["fs", "node:fs", "child_process", "node:child_process"]);
+
+function propertyName(node) {
+  return node.type === "Identifier" ? node.name : node.value;
+}
+
+function findDefinition(node, sourceCode) {
+  let scope = sourceCode.getScope(node);
+  while (scope && !scope.set.has(node.name)) scope = scope.upper;
+  return scope?.set.get(node.name)?.defs[0];
+}
+
+function isIoNamespaceImport(definition) {
+  if (definition?.node.type === "TSImportEqualsDeclaration") {
+    return SYNC_IO_MODULES.has(definition.node.moduleReference.expression?.value);
+  }
+  if (definition?.type !== "ImportBinding") return false;
+  return (
+    (definition.node.type !== "ImportSpecifier" ||
+      propertyName(definition.node.imported) === "default") &&
+    SYNC_IO_MODULES.has(definition.parent.source.value)
+  );
+}
+
+// Follow only immutable namespace aliases. Resolve bindings rather than spelling so a parameter
+// named `fs` is not mistaken for the imported namespace.
+function isIoNamespace(node, sourceCode, seen = new Set()) {
+  if (!node || seen.has(node)) return false;
+  seen.add(node);
+  if (node.type === "AwaitExpression") return isIoNamespace(node.argument, sourceCode, seen);
+  if (node.type === "ImportExpression") return SYNC_IO_MODULES.has(node.source.value);
+  if (node.type === "CallExpression") {
+    return (
+      node.callee.type === "Identifier" &&
+      node.callee.name === "require" &&
+      SYNC_IO_MODULES.has(node.arguments[0]?.value)
+    );
+  }
+  if (node.type !== "Identifier") return false;
+  const definition = findDefinition(node, sourceCode);
+  if (isIoNamespaceImport(definition)) return true;
+  return (
+    definition?.type === "Variable" &&
+    definition.parent.kind === "const" &&
+    definition.node.id.type === "Identifier" &&
+    isIoNamespace(definition.node.init, sourceCode, seen)
+  );
+}
+
+const noSyncIo = {
+  meta: {
+    schema: [
+      {
+        type: "object",
+        properties: {
+          allow: {
+            type: "object",
+            additionalProperties: { type: "array", items: { type: "string" } },
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const filename = context.filename.replaceAll("\\", "/");
+    const relativeFile = filename.split("/packages/server/src/")[1];
+    const allowed = new Set(context.options[0]?.allow?.[relativeFile] ?? []);
+    const unused = new Set(allowed);
+    function check(node, name) {
+      if (typeof name !== "string" || !name.endsWith("Sync")) return;
+      if (allowed.has(name)) {
+        unused.delete(name);
+        return;
+      }
+      context.report({
+        node,
+        message: `Synchronous Node IO (${name}) blocks the daemon event loop. Use an asynchronous capability at the owning module boundary.`,
+      });
+    }
+    return {
+      "Program:exit"(node) {
+        for (const name of unused) {
+          context.report({ node, message: `Remove the unused sync IO exception for ${name}.` });
+        }
+      },
+      ImportDeclaration(node) {
+        if (node.importKind === "type" || !SYNC_IO_MODULES.has(node.source.value)) return;
+        for (const specifier of node.specifiers) {
+          if (specifier.type === "ImportSpecifier" && specifier.importKind !== "type") {
+            check(specifier, propertyName(specifier.imported));
+          }
+        }
+      },
+      ExportNamedDeclaration(node) {
+        if (node.exportKind === "type" || !SYNC_IO_MODULES.has(node.source?.value)) return;
+        for (const specifier of node.specifiers) {
+          if (specifier.exportKind !== "type") check(specifier, propertyName(specifier.local));
+        }
+      },
+      MemberExpression(node) {
+        if (node.computed && node.property.type !== "Literal") return;
+        const name = propertyName(node.property);
+        if (typeof name !== "string" || !name.endsWith("Sync")) return;
+        if (isIoNamespace(node.object, context.sourceCode)) {
+          check(node.property, name);
+        }
+      },
+      VariableDeclarator(node) {
+        if (node.id.type !== "ObjectPattern" || !isIoNamespace(node.init, context.sourceCode)) {
+          return;
+        }
+        for (const property of node.id.properties) {
+          if (property.type === "Property") check(property, propertyName(property.key));
+        }
+      },
+    };
+  },
+};
+
 export default {
   meta: { name: "paseo" },
   rules: {
     "no-raw-pressable": noRawPressable,
+    "no-sync-io": noSyncIo,
   },
 };
diff --git a/scripts/oxlint/paseo-plugin.test.mjs b/scripts/oxlint/paseo-plugin.test.mjs
index c30a429026..4312f5e337 100644
--- a/scripts/oxlint/paseo-plugin.test.mjs
+++ b/scripts/oxlint/paseo-plugin.test.mjs
@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { test } from "node:test";
@@ -10,15 +10,21 @@ const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../
 const oxlintBin = path.join(repoRoot, "node_modules/.bin/oxlint");
 const pluginPath = path.join(repoRoot, "scripts/oxlint/paseo-plugin.mjs");
 
-function lint(source) {
+function lint(source, rule = "paseo/no-raw-pressable", options, filename = "probe.tsx") {
+  const config = JSON.stringify({
+    jsPlugins: [pluginPath],
+    rules: { [rule]: options ? ["error", options] : "error" },
+  });
+  return lintWithConfig(source, config, filename);
+}
+
+function lintWithConfig(source, config, filename) {
   const dir = mkdtempSync(path.join(tmpdir(), "paseo-oxlint-"));
   try {
-    writeFileSync(
-      path.join(dir, ".oxlintrc.json"),
-      JSON.stringify({ jsPlugins: [pluginPath], rules: { "paseo/no-raw-pressable": "error" } }),
-    );
-    writeFileSync(path.join(dir, "probe.tsx"), source);
-    const result = spawnSync(oxlintBin, ["-c", ".oxlintrc.json", "probe.tsx"], {
+    writeFileSync(path.join(dir, ".oxlintrc.json"), config);
+    mkdirSync(path.dirname(path.join(dir, filename)), { recursive: true });
+    writeFileSync(path.join(dir, filename), source);
+    const result = spawnSync(oxlintBin, ["-c", ".oxlintrc.json", filename], {
       cwd: dir,
       encoding: "utf8",
     });
@@ -52,3 +58,95 @@ test("press primitives and pressable types are allowed", () => {
   );
   assert.equal(result.failed, false, result.output);
 });
+
+for (const source of [
+  'import { readFileSync as read } from "node:fs"; export { read };',
+  'import { execSync } from "child_process"; export { execSync };',
+  'import fs from "node:fs"; export const read = fs.readFileSync;',
+  'import { default as fs } from "node:fs"; export const read = fs.readFileSync;',
+  'import fs = require("node:fs"); export const read = fs.readFileSync;',
+  'import * as fs from "fs"; export const read = fs["readFileSync"];',
+  'import cp from "node:child_process"; export const run = cp.spawnSync;',
+  'const { readFileSync: read } = require("node:fs"); export { read };',
+  'const fs = require("fs"); export const read = fs.readFileSync;',
+  'export const run = require("node:child_process").execFileSync;',
+  'import fs from "node:fs"; const other = fs; export const read = other.statSync;',
+  'export { readFileSync as read } from "node:fs";',
+  'export const read = (await import("node:fs")).readFileSync;',
+]) {
+  test(`sync IO is reported: ${source}`, () => {
+    const result = lint(source, "paseo/no-sync-io");
+    assert.equal(result.failed, true, result.output);
+    assert.match(result.output, /Synchronous Node IO/);
+  });
+}
+
+test("async IO, types, unrelated methods and shadowed namespaces are allowed", () => {
+  const result = lint(
+    'import fs from "node:fs"; import { readFile } from "node:fs/promises";\n' +
+      'import type { readFileSync } from "node:fs";\n' +
+      "export const read = readFile; export const asyncRead = fs.promises.readFile;\n" +
+      "export function unrelated(fs: { readFileSync(): void }) { fs.readFileSync(); }\n" +
+      "export type Reader = typeof readFileSync;\n",
+    "paseo/no-sync-io",
+  );
+  assert.equal(result.failed, false, result.output);
+});
+
+test("sync IO exceptions allow only named APIs in the named server module", () => {
+  const options = { allow: { "server/startup.ts": ["readFileSync"] } };
+  const source = 'import { readFileSync } from "node:fs"; export { readFileSync };';
+  const allowed = lint(
+    source,
+    "paseo/no-sync-io",
+    options,
+    "packages/server/src/server/startup.ts",
+  );
+  assert.equal(allowed.failed, false, allowed.output);
+  const otherFile = lint(
+    source,
+    "paseo/no-sync-io",
+    options,
+    "packages/server/src/server/session.ts",
+  );
+  assert.equal(otherFile.failed, true, otherFile.output);
+  assert.match(otherFile.output, /Synchronous Node IO/);
+  const otherApi = lint(
+    'import fs from "node:fs"; export const read = fs.statSync;',
+    "paseo/no-sync-io",
+    options,
+    "packages/server/src/server/startup.ts",
+  );
+  assert.equal(otherApi.failed, true, otherApi.output);
+  assert.match(otherApi.output, /Synchronous Node IO/);
+});
+
+test("repository config guards request paths while allowing startup APIs and test fixtures", () => {
+  const config = readFileSync(path.join(repoRoot, ".oxlintrc.json"), "utf8").replace(
+    '"./scripts/oxlint/paseo-plugin.mjs"',
+    JSON.stringify(pluginPath),
+  );
+  const source = 'import { existsSync } from "node:fs"; export const probe = existsSync;';
+  const request = lintWithConfig(source, config, "packages/server/src/server/probe.ts");
+  assert.equal(request.failed, true, request.output);
+  assert.match(request.output, /Synchronous Node IO/);
+  for (const filename of [
+    "packages/server/src/server/config.ts",
+    "packages/server/src/server/probe.test.ts",
+    "packages/app/src/probe.ts",
+  ]) {
+    const result = lintWithConfig(source, config, filename);
+    assert.equal(result.failed, false, result.output);
+  }
+});
+
+test("sync IO exceptions must be removed when a module stops using the API", () => {
+  const result = lint(
+    'import { readFile } from "node:fs/promises"; export const read = readFile;',
+    "paseo/no-sync-io",
+    { allow: { "server/startup.ts": ["readFileSync"] } },
+    "packages/server/src/server/startup.ts",
+  );
+  assert.equal(result.failed, true, result.output);
+  assert.match(result.output, /Remove the unused sync IO exception for readFileSync/);
+});
diff --git a/scripts/postinstall-patches.mjs b/scripts/postinstall-patches.mjs
index 435f6331e0..e6b9195a94 100644
--- a/scripts/postinstall-patches.mjs
+++ b/scripts/postinstall-patches.mjs
@@ -24,7 +24,13 @@ const patchedPackages = [
   },
   // Registry cleanup: remove after react-native-unistyles ships
   // https://github.com/jpudysz/react-native-unistyles/pull/1203.
+  // Adaptive themes: keep until colorScheme reads no longer consume listener-owned media changes.
   // 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+",
@@ -37,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+",
@@ -56,6 +70,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/postinstall-patches.test.mjs b/scripts/postinstall-patches.test.mjs
index 9e4d4c0722..11cd2d157a 100644
--- a/scripts/postinstall-patches.test.mjs
+++ b/scripts/postinstall-patches.test.mjs
@@ -10,6 +10,43 @@ const bin = path.resolve("node_modules", ".bin");
 const packageName = "react-native-draggable-flatlist";
 const patchFile = `${packageName}+4.0.3.patch`;
 
+for (const platform of ["ios", "android"]) {
+  test(`patched Markdown ships ${platform} props generated from its native specs`, () => {
+    const packageDir = path.resolve("packages/app/node_modules/react-native-enriched-markdown");
+    const output = mkdtempSync(path.join(tmpdir(), `markdown-${platform}-codegen-`));
+    try {
+      // includesGeneratedCode makes native builds use the shipped headers instead of
+      // regenerating them after patch-package changes the TypeScript specs.
+      const result = spawnSync(
+        process.execPath,
+        [
+          path.resolve("node_modules/react-native/scripts/generate-codegen-artifacts.js"),
+          "-p",
+          packageDir,
+          "-t",
+          platform,
+          "-o",
+          output,
+          "-s",
+          "library",
+        ],
+        { encoding: "utf8" },
+      );
+      assert.equal(result.status, 0, result.stdout + result.stderr);
+      const header =
+        platform === "ios"
+          ? "ReactCodegen/EnrichedMarkdownTextSpec/Props.h"
+          : "jni/react/renderer/components/EnrichedMarkdownTextSpec/Props.h";
+      assert.equal(
+        readFileSync(path.join(packageDir, platform, "generated", header), "utf8"),
+        readFileSync(path.join(output, header), "utf8"),
+      );
+    } finally {
+      rmSync(output, { recursive: true, force: true });
+    }
+  });
+}
+
 function createCheckout() {
   const root = mkdtempSync(path.join(tmpdir(), "postinstall-patches-"));
   writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "checkout" }));
diff --git a/scripts/test-support/npm-registry.mts b/scripts/test-support/npm-registry.mts
index a0a39e27d9..5640487049 100644
--- a/scripts/test-support/npm-registry.mts
+++ b/scripts/test-support/npm-registry.mts
@@ -50,6 +50,7 @@ export async function startNpmRegistry(packages: FixturePackage[]) {
     `registry=${url}/\n//127.0.0.1:${address.port}/:_authToken=fixture-token\ncache=${root}/cache\n`,
   );
   try {
+    const prepared = [];
     for (const [index, pkg] of packages.entries()) {
       const directory = path.join(root, String(index));
       await mkdir(directory);
@@ -65,11 +66,17 @@ export async function startNpmRegistry(packages: FixturePackage[]) {
         await mkdir(path.dirname(path.join(directory, file)), { recursive: true });
         await writeFile(path.join(directory, file), content);
       }
-      const { stdout } = await execCommand("npm", ["pack", "--ignore-scripts", "--json"], {
-        cwd: directory,
-      });
-      const packed: Array<{ filename: string }> = JSON.parse(stdout);
-      const artifact = await readFile(path.join(directory, packed[0].filename));
+      prepared.push({ directory, manifest, pkg, index });
+    }
+    // Pack all fixtures in one npm process instead of paying startup once per package.
+    const { stdout } = await execCommand(
+      "npm",
+      ["pack", "--ignore-scripts", "--json", ...prepared.map(({ directory }) => directory)],
+      { cwd: root },
+    );
+    const packed: Array<{ filename: string }> = JSON.parse(stdout);
+    for (const { manifest, pkg, index } of prepared) {
+      const artifact = await readFile(path.join(root, packed[index].filename));
       const artifactPath = `/artifacts/${index}.tgz`;
       artifacts.set(artifactPath, artifact);
       const published = {
diff --git a/skills/paseo-advisor/SKILL.md b/skills/paseo-advisor/SKILL.md
index 94d4558e5a..23868d9a2d 100644
--- a/skills/paseo-advisor/SKILL.md
+++ b/skills/paseo-advisor/SKILL.md
@@ -9,7 +9,7 @@ argument-hint: "[--profile <name>] <question or topic>"
 
 Single agent. Reads the situation you're in. Gives a judgment. You decide what to do — the advisor doesn't drive the work.
 
-**User's request:** $ARGUMENTS
+Use the user's request and current conversation as input, including any arguments supplied with the skill invocation. Optional syntax: `[--profile <name>] <question or topic>`.
 
 ## Prerequisites
 
@@ -40,13 +40,15 @@ This is analysis only. Do NOT edit, create, or delete any files. Do NOT write co
 
 ## Forwarded skills
 
-If `$ARGUMENTS` contains another skill reference — `/unslop`, `/unslop-risk`, `$unslop`, etc. — the user is asking the advisor to run that skill against the current task. Examples:
+If the user's request contains another skill reference, such as `/unslop`, `/skill:unslop`, or `$unslop`, the user is asking the advisor to run that skill against the current task. Examples:
 
 - `/paseo-advisor /unslop` → advisor runs `/unslop` on the current diff.
 - `/paseo-advisor /unslop-risk` → advisor does an unslop-risk review.
 - `/paseo-advisor $diagnose this build failure` → advisor invokes `/diagnose`.
+- `/skill:paseo-advisor /skill:unslop` → advisor runs the `unslop` skill on the current diff in Pi.
+- `$paseo-advisor $unslop` → advisor runs the `unslop` skill on the current diff in Codex.
 
-Parse the forwarded skill name out of `$ARGUMENTS` (`/<name>` or `$<name>`). In the briefing, tell the advisor explicitly:
+Parse the forwarded skill name from the user's request (`/<name>`, `/skill:<name>`, or `$<name>`), excluding this skill's own invocation. In the briefing, tell the advisor explicitly:
 
 ```
 Invoke the `<name>` skill against this task. Load it via the Skill tool before doing anything else.
diff --git a/skills/paseo-committee/SKILL.md b/skills/paseo-committee/SKILL.md
index 2b16189556..e41ca8ba81 100644
--- a/skills/paseo-committee/SKILL.md
+++ b/skills/paseo-committee/SKILL.md
@@ -8,7 +8,7 @@ user-invocable: true
 
 Two agents from contrasting profiles, fresh context, planning a solution in parallel.
 
-**User's additional context:** $ARGUMENTS
+Use the user's request and current conversation as input, including any arguments supplied with the skill invocation.
 
 ## Prerequisites
 
diff --git a/skills/paseo-handoff/SKILL.md b/skills/paseo-handoff/SKILL.md
index b321365306..fac6793e5e 100644
--- a/skills/paseo-handoff/SKILL.md
+++ b/skills/paseo-handoff/SKILL.md
@@ -8,7 +8,7 @@ user-invocable: true
 
 Transfer the current task — context, decisions, failed attempts, constraints — to a fresh agent. The receiving agent starts with **zero context**, so the handoff prompt must be a self-contained briefing.
 
-**User's arguments:** $ARGUMENTS
+Use the user's request and current conversation as input, including any arguments supplied with the skill invocation.
 
 ## Prerequisites
 
diff --git a/skills/paseo-help/SKILL.md b/skills/paseo-help/SKILL.md
index 951c1207bc..52dcf57a44 100644
--- a/skills/paseo-help/SKILL.md
+++ b/skills/paseo-help/SKILL.md
@@ -7,7 +7,7 @@ description: Answer questions about the Paseo product and app, including setup,
 
 You are helping a user understand, configure, or troubleshoot Paseo itself. Answer their question directly, verify the answer against the current public documentation, and include the relevant documentation link. Do not send the user away to read the docs in place of helping them.
 
-**User's question:** $ARGUMENTS
+Use the user's question and current conversation as input, including any arguments supplied with the skill invocation.
 
 ## Use current documentation
 
diff --git a/skills/paseo-plugin/SKILL.md b/skills/paseo-plugin/SKILL.md
index 028d869085..53a301eeb6 100644
--- a/skills/paseo-plugin/SKILL.md
+++ b/skills/paseo-plugin/SKILL.md
@@ -7,7 +7,7 @@ description: Build and manage trusted local Paseo plugins. Use when the user ask
 
 Build or manage the requested plugin directly. Use the current public docs to catch contract changes, but keep working from this skill if the network is unavailable.
 
-**User's request:** $ARGUMENTS
+Use the user's request and current conversation as input, including any arguments supplied with the skill invocation.
 
 ## Check current documentation
 
@@ -27,28 +27,30 @@ 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`                                             | Change agent config, provider options, MCP servers, environment, or workspace isolation before the operation  | [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                                                                                                |
-| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Log all eleven hooks                                                | [lifecycle-logger](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-logger)       |
-| Follow-ups, permissions, environment, provider switching, worktrees | [lifecycle-actions](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-actions)     |
-| Inject MCP servers and change Codex sandbox/approval options        | [agent-configuration](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-configuration) |
+| Lifecycle task                                                         | Example                                                                                                |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Log all eleven hooks                                                   | [lifecycle-logger](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-logger)       |
+| Follow-ups, permissions, environment, provider switching, worktrees    | [lifecycle-actions](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-actions)     |
+| Inject launch-only MCP servers and save Codex sandbox/approval options | [agent-configuration](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-configuration) |
+| Attach a tool to selected agents                                       | [agent-tools](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-tools)                 |
 
 ## Create the project
 
@@ -373,10 +375,39 @@ 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.
 
+### Contribute tools and MCP servers at session open
+
+Use `before("agent.session_open")` for per-agent tools and plugin-owned MCP servers. Add this
+callback inside `contribute(server)`:
+
+```ts
+server.before("agent.session_open", ({ request }) => {
+  if (request.provider !== "codex") return;
+  return {
+    ...request,
+    mcpServers: {
+      ...request.mcpServers,
+      company: { type: "http", url: "https://tools.example.com/mcp" },
+    },
+  };
+});
+```
+
+`tools` and `mcpServers` start empty for each plugin and accumulate across its own callbacks.
+They are launch-only. Use `agent.create` to edit configuration that should be saved with the agent.
+See [Attach tools to agents](https://paseo.sh/docs/plugins/reference.md#attach-tools-to-agents)
+for `defineAgentTool` and targeting, and
+[Inject MCP servers](https://paseo.sh/docs/plugins/reference.md#inject-mcp-servers) for server configuration and collisions.
+
+Starting, stopping, or reloading a plugin with a session-open hook marks open agent sessions stale.
+Each reopens before its next idle prompt without interrupting a running turn.
+`await paseo.agents.ref(id).reload()` applies changes immediately and interrupts a running turn;
+`refresh()` only reads the current snapshot.
+
 ### Debug daemon-side behavior
 
 Backend contributions can use normal Node logging. `console.log()` writes to the plugin's stdout;