fix(explorer): apply directory toggles atomically

Reconcile completed restoration against the current expansion set atomically so folder interactions made while directory requests are in flight are not overwritten.

.github/workflows/ci.yml

@@ -18,6 +18,106 @@ env:
   ONNXRUNTIME_NODE_INSTALL: skip
 
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      quality: ${{ steps.filter.outputs.shared != 'false' || steps.filter.outputs.quality != 'false' }}
+      server: ${{ steps.filter.outputs.shared != 'false' || steps.filter.outputs.server != 'false' }}
+      desktop: ${{ steps.filter.outputs.shared != 'false' || steps.filter.outputs.desktop != 'false' }}
+      desktop_package: ${{ steps.filter.outputs.shared != 'false' || steps.filter.outputs.desktop_package != 'false' }}
+      app: ${{ steps.filter.outputs.shared != 'false' || steps.filter.outputs.app != 'false' }}
+      sdk: ${{ steps.filter.outputs.shared != 'false' || steps.filter.outputs.sdk != 'false' }}
+      playwright: ${{ steps.filter.outputs.shared != 'false' || steps.filter.outputs.playwright != 'false' }}
+      relay: ${{ steps.filter.outputs.shared != 'false' || steps.filter.outputs.relay != 'false' }}
+      cli: ${{ steps.filter.outputs.shared != 'false' || steps.filter.outputs.cli != 'false' }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
+
+      - name: Detect affected CI jobs
+        id: filter
+        uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3.0.3
+        with:
+          filters: |
+            shared:
+              - '.github/workflows/ci.yml'
+              - '.github/actions/**'
+              - '.mise.toml'
+              - '.tool-versions'
+              - 'package.json'
+              - 'package-lock.json'
+              - 'patches/**'
+              - 'scripts/**'
+              - 'tsconfig.json'
+              - 'tsconfig.base.json'
+              - 'vitest.config.ts'
+            quality:
+              - 'packages/**'
+              - '*.cjs'
+              - '*.js'
+              - '*.json'
+              - '*.mjs'
+              - '*.ts'
+            server:
+              - 'packages/app/e2e/fixtures/recording.*'
+              - 'packages/client/**'
+              - 'packages/cli/src/**'
+              - 'packages/highlight/**'
+              - 'packages/protocol/**'
+              - 'packages/relay/**'
+              - 'packages/server/**'
+            desktop:
+              - 'packages/app/**'
+              - 'packages/cli/**'
+              - 'packages/client/**'
+              - 'packages/desktop/**'
+              - 'packages/expo-two-way-audio/**'
+              - 'packages/highlight/**'
+              - 'packages/protocol/**'
+              - 'packages/relay/**'
+              - 'packages/server/**'
+            desktop_package:
+              - '.github/workflows/ci.yml'
+              - 'packages/desktop/**'
+            app:
+              - 'packages/app/**'
+              - 'packages/client/**'
+              - 'packages/expo-two-way-audio/**'
+              - 'packages/highlight/**'
+              - 'packages/protocol/**'
+              - 'packages/relay/**'
+            sdk:
+              - 'packages/client/**'
+              - 'packages/protocol/**'
+              - 'packages/relay/**'
+            playwright:
+              - 'packages/app/**'
+              - 'packages/client/**'
+              - 'packages/expo-two-way-audio/**'
+              - 'packages/highlight/**'
+              - 'packages/protocol/**'
+              - 'packages/relay/**'
+              - 'packages/server/**'
+            relay:
+              - 'packages/relay/**'
+            cli:
+              - 'nix/**'
+              - 'packages/app/e2e/global-setup.ts'
+              - 'packages/cli/**'
+              - 'packages/client/**'
+              - 'packages/desktop/src/daemon/runtime-paths.ts'
+              - 'packages/highlight/**'
+              - 'packages/protocol/**'
+              - 'packages/relay/**'
+              - 'packages/server/**'
+
+      - name: Validate CI workflow
+        run: node --test scripts/ci-workflow.test.mjs
+
   format:
     runs-on: ubuntu-latest
     env:
@@ -39,6 +139,12 @@ jobs:
         run: npx oxfmt --check .
 
   lint:
+    needs: changes
+    if: >-
+      ${{ !cancelled() &&
+          (github.event_name == 'workflow_dispatch' ||
+           needs.changes.result != 'success' ||
+           needs.changes.outputs.quality != 'false') }}
     runs-on: ubuntu-latest
     env:
       ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
@@ -63,6 +169,12 @@ jobs:
         run: npm run lint
 
   typecheck:
+    needs: changes
+    if: >-
+      ${{ !cancelled() &&
+          (github.event_name == 'workflow_dispatch' ||
+           needs.changes.result != 'success' ||
+           needs.changes.outputs.quality != 'false') }}
     runs-on: ubuntu-latest
     env:
       ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
@@ -89,6 +201,8 @@ jobs:
           npm pack --dry-run --ignore-scripts --workspace=@getpaseo/server
 
   server-tests:
+    needs: changes
+    if: ${{ !cancelled() }}
     strategy:
       fail-fast: false
       matrix:
@@ -97,28 +211,43 @@ jobs:
     name: server-tests (${{ matrix.os }})
     env:
       ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
+      RUN_TESTS: >-
+        ${{ github.event_name == 'workflow_dispatch' ||
+            needs.changes.result != 'success' ||
+            needs.changes.outputs.server != 'false' }}
     steps:
+      - name: Skip unaffected server tests
+        if: env.RUN_TESTS != 'true'
+        run: echo "No server changes detected."
+
       - uses: actions/checkout@v4
+        if: env.RUN_TESTS == 'true'
         with:
           fetch-depth: 0
 
       - uses: actions/setup-node@v4
+        if: env.RUN_TESTS == 'true'
         with:
           node-version: "22"
           cache: "npm"
 
       - name: Fetch origin/main (worktree tests)
+        if: env.RUN_TESTS == 'true'
         run: git fetch --no-tags origin main:refs/remotes/origin/main
 
       - name: Install dependencies
+        if: env.RUN_TESTS == 'true'
         run: node scripts/npm-retry.mjs ci
       - name: Install agent CLIs for provider tests
+        if: env.RUN_TESTS == 'true'
         run: node scripts/npm-retry.mjs install -g @anthropic-ai/claude-code opencode-ai
 
       - name: Build server dependencies
+        if: env.RUN_TESTS == 'true'
         run: npm run build:server-deps
 
       - name: Run server tests
+        if: env.RUN_TESTS == 'true'
         run: npm run test --workspace=@getpaseo/server
         env:
           CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
@@ -126,6 +255,8 @@ jobs:
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
 
   desktop-tests:
+    needs: changes
+    if: ${{ !cancelled() }}
     strategy:
       fail-fast: false
       matrix:
@@ -134,49 +265,53 @@ jobs:
     timeout-minutes: 30
     permissions:
       contents: read
-      pull-requests: read
+    env:
+      RUN_TESTS: >-
+        ${{ github.event_name == 'workflow_dispatch' ||
+            needs.changes.result != 'success' ||
+            needs.changes.outputs.desktop != 'false' }}
     steps:
-      - uses: actions/checkout@v4
+      - name: Skip unaffected desktop tests
+        if: env.RUN_TESTS != 'true'
+        run: echo "No desktop changes detected."
 
-      - name: Detect desktop changes
-        if: matrix.os == 'ubuntu-latest'
-        id: desktop_changes
-        uses: dorny/paths-filter@v3
-        with:
-          filters: |
-            desktop:
-              - 'packages/desktop/**'
+      - uses: actions/checkout@v4
+        if: env.RUN_TESTS == 'true'
 
       - uses: actions/setup-node@v4
+        if: env.RUN_TESTS == 'true'
         with:
           node-version: "22"
           cache: "npm"
 
       - name: Install dependencies with retry
+        if: env.RUN_TESTS == 'true'
         run: node scripts/npm-retry.mjs ci
       - name: Build server stack
+        if: env.RUN_TESTS == 'true'
         run: npm run build:server
 
       - name: Run desktop tests
+        if: env.RUN_TESTS == 'true'
         run: npm run test --workspace=@getpaseo/desktop
 
       - name: Build app dependencies for desktop E2E
-        if: matrix.os == 'ubuntu-latest'
+        if: env.RUN_TESTS == 'true' && matrix.os == 'ubuntu-latest'
         run: npm run build:app-deps
 
       - name: Install virtual display
-        if: matrix.os == 'ubuntu-latest'
+        if: env.RUN_TESTS == 'true' && matrix.os == 'ubuntu-latest'
         run: sudo apt-get update && sudo apt-get install -y xvfb xauth
 
       - name: Run real Electron browser tab bridge E2E
-        if: matrix.os == 'ubuntu-latest'
+        if: env.RUN_TESTS == 'true' && matrix.os == 'ubuntu-latest'
         run: npm run test:e2e:browser-tab-bridge --workspace=@getpaseo/desktop
         env:
           PASEO_TAB_BRIDGE_E2E_ARTIFACT_DIR: ${{ runner.temp }}/browser-tab-bridge-e2e
 
       - name: Upload browser tab bridge diagnostics
         uses: actions/upload-artifact@v4
-        if: failure() && matrix.os == 'ubuntu-latest'
+        if: env.RUN_TESTS == 'true' && failure() && matrix.os == 'ubuntu-latest'
         with:
           name: browser-tab-bridge-e2e
           path: ${{ runner.temp }}/browser-tab-bridge-e2e
@@ -184,7 +319,11 @@ jobs:
           retention-days: 7
 
       - name: Build and smoke unpacked desktop app
-        if: matrix.os == 'ubuntu-latest' && steps.desktop_changes.outputs.desktop == 'true'
+        if: >-
+          env.RUN_TESTS == 'true' && matrix.os == 'ubuntu-latest' &&
+          (github.event_name == 'workflow_dispatch' ||
+           needs.changes.result != 'success' ||
+           needs.changes.outputs.desktop_package != 'false')
         run: npm run build:desktop -- --publish never --linux --x64 --dir
         env:
           EP_GH_IGNORE_TIME: true
@@ -192,7 +331,11 @@ jobs:
           PASEO_DESKTOP_SMOKE_ARTIFACT_DIR: ${{ runner.temp }}/desktop-smoke
 
       - name: Upload packaged smoke diagnostics
-        if: failure() && matrix.os == 'ubuntu-latest' && steps.desktop_changes.outputs.desktop == 'true'
+        if: >-
+          env.RUN_TESTS == 'true' && failure() && matrix.os == 'ubuntu-latest' &&
+          (github.event_name == 'workflow_dispatch' ||
+           needs.changes.result != 'success' ||
+           needs.changes.outputs.desktop_package != 'false')
         uses: actions/upload-artifact@v4
         with:
           name: desktop-packaged-smoke-linux-x64
@@ -201,6 +344,12 @@ jobs:
           retention-days: 7
 
   app-tests:
+    needs: changes
+    if: >-
+      ${{ !cancelled() &&
+          (github.event_name == 'workflow_dispatch' ||
+           needs.changes.result != 'success' ||
+           needs.changes.outputs.app != 'false') }}
     runs-on: ubuntu-latest
     env:
       ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
@@ -225,6 +374,12 @@ jobs:
         run: npm run test --workspace=@getpaseo/app
 
   sdk-tests:
+    needs: changes
+    if: >-
+      ${{ !cancelled() &&
+          (github.event_name == 'workflow_dispatch' ||
+           needs.changes.result != 'success' ||
+           needs.changes.outputs.sdk != 'false') }}
     runs-on: ubuntu-latest
     env:
       ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
@@ -251,6 +406,8 @@ jobs:
         run: npm run typecheck:examples --workspace=@getpaseo/client
 
   playwright:
+    needs: changes
+    if: ${{ !cancelled() }}
     strategy:
       fail-fast: false
       matrix:
@@ -264,43 +421,57 @@ jobs:
     runs-on: ubuntu-latest
     env:
       ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
+      RUN_TESTS: >-
+        ${{ github.event_name == 'workflow_dispatch' ||
+            needs.changes.result != 'success' ||
+            needs.changes.outputs.playwright != 'false' }}
     steps:
+      - name: Skip unaffected Playwright tests
+        if: env.RUN_TESTS != 'true'
+        run: echo "No Playwright changes detected."
+
       - uses: actions/checkout@v4
+        if: env.RUN_TESTS == 'true'
 
       - uses: actions/setup-node@v4
+        if: env.RUN_TESTS == 'true'
         with:
           node-version: "22"
           cache: "npm"
 
       - name: Install dependencies with retry
+        if: env.RUN_TESTS == 'true'
         run: node scripts/npm-retry.mjs ci
       - name: Install Playwright browsers
+        if: env.RUN_TESTS == 'true'
         timeout-minutes: 10
         run: npx playwright install chromium
 
       - name: Build app dependencies
+        if: env.RUN_TESTS == 'true'
         run: npm run build:app-deps
 
       - name: Build server stack
+        if: env.RUN_TESTS == 'true'
         run: npm run build:server
 
       - name: Install agent CLIs for provider tests
-        if: ${{ !matrix.desktop }}
+        if: env.RUN_TESTS == 'true' && !matrix.desktop
         run: node scripts/npm-retry.mjs install -g @anthropic-ai/claude-code @openai/codex@0.105.0 opencode-ai
 
       - name: Run Playwright E2E tests
-        if: ${{ !matrix.desktop }}
+        if: env.RUN_TESTS == 'true' && !matrix.desktop
         run: npm run test:e2e --workspace=@getpaseo/app -- --shard=${{ matrix.shard }}/4
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
 
       - name: Run desktop-overlay Playwright tests
-        if: ${{ matrix.desktop }}
+        if: env.RUN_TESTS == 'true' && matrix.desktop
         run: npm run test:e2e:desktop --workspace=@getpaseo/app
 
       - name: Upload test artifacts
         uses: actions/upload-artifact@v4
-        if: failure()
+        if: env.RUN_TESTS == 'true' && failure()
         with:
           name: playwright-results-${{ matrix.shard }}
           path: |
@@ -309,6 +480,12 @@ jobs:
           retention-days: 7
 
   relay-tests:
+    needs: changes
+    if: >-
+      ${{ !cancelled() &&
+          (github.event_name == 'workflow_dispatch' ||
+           needs.changes.result != 'success' ||
+           needs.changes.outputs.relay != 'false') }}
     runs-on: ubuntu-latest
     env:
       ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
@@ -330,6 +507,8 @@ jobs:
         run: npm run test --workspace=@getpaseo/relay
 
   cli-tests:
+    needs: changes
+    if: ${{ !cancelled() }}
     strategy:
       fail-fast: false
       matrix:
@@ -338,21 +517,38 @@ jobs:
     name: cli-tests (shard ${{ matrix.shard }}/3)
     env:
       ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
+      RUN_TESTS: >-
+        ${{ github.event_name == 'workflow_dispatch' ||
+            needs.changes.result != 'success' ||
+            needs.changes.outputs.cli != 'false' }}
     steps:
+      - name: Skip unaffected CLI tests
+        if: env.RUN_TESTS != 'true'
+        run: echo "No CLI changes detected."
+
       - uses: actions/checkout@v4
+        if: env.RUN_TESTS == 'true'
 
       - uses: actions/setup-node@v4
+        if: env.RUN_TESTS == 'true'
         with:
           node-version: "22"
           cache: "npm"
 
       - name: Install dependencies
+        if: env.RUN_TESTS == 'true'
         run: node scripts/npm-retry.mjs ci
 
+      - name: Build server stack
+        if: env.RUN_TESTS == 'true'
+        run: npm run build:server
+
       - name: Install agent CLIs for provider tests
+        if: env.RUN_TESTS == 'true'
         run: node scripts/npm-retry.mjs install -g @anthropic-ai/claude-code @openai/codex@0.105.0 opencode-ai
 
       - name: Run CLI tests
+        if: env.RUN_TESTS == 'true'
         run: npm run test --workspace=@getpaseo/cli
         env:
           PASEO_LOCAL_SPEECH_AUTO_DOWNLOAD: "0"

CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.2.3 - 2026-07-27
+
+### Added
+
+- Manage workspace scripts from the CLI and agent MCP tools ([#1992](https://github.com/getpaseo/paseo/pull/1992) by [@mcowger](https://github.com/mcowger))
+- Copy terminal IDs from terminal tab menus ([#2371](https://github.com/getpaseo/paseo/pull/2371))
+- Long Markdown lines wrap by default in the file editor ([#2459](https://github.com/getpaseo/paseo/pull/2459))
+
+### Improved
+
+- Desktop stops its managed daemon when you quit unless “Keep daemon running after quit” is enabled ([#2454](https://github.com/getpaseo/paseo/pull/2454))
+- Remote terminal and file traffic uses less bandwidth over encrypted connections ([#2480](https://github.com/getpaseo/paseo/pull/2480))
+- Workspace search now shows and matches project names ([#2345](https://github.com/getpaseo/paseo/pull/2345) by [@cleiter](https://github.com/cleiter))
+- Claude usage shows model-specific weekly limits ([#2303](https://github.com/getpaseo/paseo/pull/2303) by [@cleiter](https://github.com/cleiter))
+- OMP models show only the thinking levels they support ([#2171](https://github.com/getpaseo/paseo/pull/2171) by [@bendavid](https://github.com/bendavid))
+
+### Fixed
+
+- Image uploads preserve the correct image format ([#2380](https://github.com/getpaseo/paseo/pull/2380))
+- Large file views no longer disconnect the session ([#2482](https://github.com/getpaseo/paseo/pull/2482))
+- Reaching the top of a chat loads the complete older history ([#2481](https://github.com/getpaseo/paseo/pull/2481))
+- Parent agents stay available while child agents are working ([#2458](https://github.com/getpaseo/paseo/pull/2458))
+- Stale client connections no longer exhaust daemon memory ([#2169](https://github.com/getpaseo/paseo/pull/2169))
+- Pin and unpin shortcuts work when sidebar sections are collapsed ([#2299](https://github.com/getpaseo/paseo/pull/2299) by [@cleiter](https://github.com/cleiter))
+- `Shift+Tab` no longer changes a background agent’s permission mode ([#1848](https://github.com/getpaseo/paseo/pull/1848) by [@cleiter](https://github.com/cleiter))
+- Proxied services preserve ports in redirects ([#2288](https://github.com/getpaseo/paseo/pull/2288) by [@cleiter](https://github.com/cleiter))
+- Provider settings open correctly above the model selector ([#2476](https://github.com/getpaseo/paseo/pull/2476))
+- Clicking the file editor correctly focuses its pane ([#2457](https://github.com/getpaseo/paseo/pull/2457))
+
+## 0.2.2 - 2026-07-25
+
+### Fixed
+
+- Claude 5 models now use the correct context windows.
+
 ## 0.2.1 - 2026-07-24
 
 ### Added

README.ja.md

@@ -151,23 +151,12 @@ npm run build:server
 npm run typecheck
 ```
 
-## コミュニティ
+## 関連プロジェクト
 
-- [paseo-relay](https://github.com/zenghongtu/paseo-relay) — Go 実装のセルフホスト型リレー
+- [getpaseo/paseo-relay](https://github.com/getpaseo/paseo-relay) — Elixir 製の公式分散リレー
+- [paseo-skins](https://github.com/huangguang1999/paseo-skins) — Paseo デスクトップ向けコミュニティテーマと、Agent Skill 対応のゼロパッチテーマローダー
 - [paseo-vscode](https://marketplace.visualstudio.com/items?itemName=hinnes.paseo-vscode) — VS Code 拡張機能
 
----
-
-<p align="center">
-  <a href="https://star-history.com/#getpaseo/paseo&Date">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=getpaseo/paseo&type=Date&theme=dark">
-      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=getpaseo/paseo&type=Date">
-      <img src="https://api.star-history.com/svg?repos=getpaseo/paseo&type=Date" alt="getpaseo/paseo のスター履歴チャート" width="600" style="max-width: 100%;">
-    </picture>
-  </a>
-</p>
-
 ## ライセンス
 
 AGPL-3.0

README.md

@@ -38,12 +38,6 @@
   <img src="https://paseo.sh/mobile-mockup.png" alt="Paseo mobile app" width="100%">
 </p>
 
-> [!NOTE]
-> I'm a solo maintainer and don't always keep up with GitHub Issues daily.
-> If something is urgent or blocking you, [Discord](https://discord.gg/jz8T2uahpH) is the fastest place to reach me.
-
----
-
 Run agents in parallel on your own machines. Ship from your phone or your desk.
 
 - **Self-hosted:** Agents run on your machine with your full dev environment. Use your tools, your configs, and your skills.
@@ -144,7 +138,7 @@ Quick monorepo package map:
 - `packages/app`: Expo client (iOS, Android, web)
 - `packages/cli`: `paseo` CLI for daemon and agent workflows
 - `packages/desktop`: Electron desktop app
-- `packages/relay`: Relay package for remote connectivity
+- `packages/relay`: Relay transport and encryption used by the daemon and clients
 - `packages/website`: Marketing site and documentation (`paseo.sh`)
 
 Common commands:
@@ -166,23 +160,12 @@ npm run build:server
 npm run typecheck
 ```
 
-## Community
+## Related projects
 
-- [paseo-relay](https://github.com/zenghongtu/paseo-relay) — self-hosted relay in Go
+- [getpaseo/paseo-relay](https://github.com/getpaseo/paseo-relay) — official distributed relay, written in Elixir
+- [paseo-skins](https://github.com/huangguang1999/paseo-skins) — community themes and a zero-patch desktop theme loader with an Agent Skill
 - [paseo-vscode](https://marketplace.visualstudio.com/items?itemName=hinnes.paseo-vscode) — VS Code extension
 
----
-
-<p align="center">
-  <a href="https://star-history.com/#getpaseo/paseo&Date">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=getpaseo/paseo&type=Date&theme=dark">
-      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=getpaseo/paseo&type=Date">
-      <img src="https://api.star-history.com/svg?repos=getpaseo/paseo&type=Date" alt="Star history chart for getpaseo/paseo" width="600" style="max-width: 100%;">
-    </picture>
-  </a>
-</p>
-
 ## License
 
 AGPL-3.0

README.zh-CN.md

@@ -151,9 +151,10 @@ npm run build:server
 npm run typecheck
 ```
 
-## 社区
+## 相关项目
 
-- [paseo-relay](https://github.com/zenghongtu/paseo-relay) — Go 实现的自托管 relay
+- [getpaseo/paseo-relay](https://github.com/getpaseo/paseo-relay) — 官方分布式 relay，使用 Elixir 编写
+- [paseo-skins](https://github.com/huangguang1999/paseo-skins) — Paseo 桌面端社区主题与零 patch 换肤工具，支持 Agent Skill
 - [paseo-vscode](https://marketplace.visualstudio.com/items?itemName=hinnes.paseo-vscode) — VS Code 扩展
 
 ### 自托管 relay TLS
@@ -202,18 +203,6 @@ server {
 }
 ```
 
----
-
-<p align="center">
-  <a href="https://star-history.com/#getpaseo/paseo&Date">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=getpaseo/paseo&type=Date&theme=dark">
-      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=getpaseo/paseo&type=Date">
-      <img src="https://api.star-history.com/svg?repos=getpaseo/paseo&type=Date" alt="Star history chart for getpaseo/paseo" width="600" style="max-width: 100%;">
-    </picture>
-  </a>
-</p>
-
 ## License
 
 AGPL-3.0

SECURITY.md

@@ -22,7 +22,9 @@ The relay is designed to be untrusted. All traffic between your phone and daemon
 1. The daemon generates a persistent Curve25519 keypair on first run and stores it at `$PASEO_HOME/daemon-keypair.json` with mode `0600`
 2. The pairing URL (rendered as a QR code or opened directly) carries the daemon's public key in its URL fragment (`https://app.paseo.sh/#offer=...`). Fragments are not sent to the web server, so `app.paseo.sh` never sees the key.
 3. When the phone connects via the relay, it generates a fresh ephemeral Curve25519 keypair and sends an `e2ee_hello` message containing its public key. The daemon will not process any application messages until this handshake completes.
-4. Both sides perform a Curve25519 ECDH key exchange to derive a shared key. All subsequent messages are encrypted with XSalsa20-Poly1305 (NaCl `box`). The wire format is `[24-byte nonce][ciphertext]`, base64-encoded as a WebSocket text frame.
+4. Both sides perform a Curve25519 ECDH key exchange to derive a shared key. All subsequent messages are encrypted with XSalsa20-Poly1305 (NaCl `box`). The encrypted bundle is `[24-byte nonce][ciphertext]`. Peers optionally negotiate `binaryCiphertext` in `e2ee_hello` / `e2ee_ready`: negotiated application text is carried as a base64 WebSocket text frame, while application binary is carried as a raw WebSocket binary frame. A peer that does not negotiate the capability uses base64 text frames for both kinds.
+
+The WebSocket opcode is preserved end to end after negotiation; the receiver never guesses whether authenticated plaintext is text or binary from its byte contents. The plaintext handshake remains WebSocket text and contains only public keys and capability declarations.
 
 The relay sees only: IP addresses, timing, message sizes, session IDs, and the plaintext `e2ee_hello` / `e2ee_ready` handshake frames (which contain only public keys). It cannot read message contents, forge messages, or derive encryption keys from observing the handshake.
 
@@ -48,6 +50,12 @@ The daemon also supports an optional shared-secret password (set via `auth.passw
 
 Connected clients are trusted operators of the daemon user. File previews follow that authority: a preview request may read any regular file the daemon process can read, while keeping path normalization and symlink checks in the daemon file service. Workspace-relative paths remain a UI convenience, not a security boundary.
 
+An explicit `symlink <path>` entry in a repository's .worktreeinclude intentionally gives a
+Paseo-created worktree live access to that source-checkout file or directory. It is useful for
+local dependencies and caches, but it weakens the usual worktree isolation: agents and lifecycle
+scripts can modify the source through the link. Paseo validates entries and refuses traversal or
+destination-link escapes, but the linked source is a deliberate shared-data boundary.
+
 If you expose the daemon beyond loopback, such as by binding to `0.0.0.0`, forwarding it through a tunnel or reverse proxy, or publishing it from a Docker container, you are responsible for restricting and securing that access. Setting a password is strongly recommended in that case.
 
 In Docker, the official image runs the daemon and agents as the non-root

docs/agent-lifecycle.md

@@ -21,11 +21,12 @@ the agent runs through `ensureAgentLoaded()`, which resumes the durable provider
 same Paseo agent ID. Provider history is not appended again when the canonical timeline is already
 primed.
 
-The daemon collects an eligible idle runtime after two minutes and sweeps every 15 seconds. Only
+The daemon collects an eligible idle runtime after 30 minutes and sweeps every minute. Only
 unarchived, non-internal agents that are exactly `idle`, have no active or pending run, replacement,
 or permission, and have not been activated during the idle window are eligible. `running`,
-`initializing`, and `error` agents stay resident. Subagents are considered independently; collection
-does not cascade or change parentage.
+`initializing`, and `error` agents stay resident. An idle parent also stays resident while current
+in-memory state shows a running managed child or provider subagent. Otherwise agents are evaluated
+independently; collection does not cascade or change parentage.
 
 Active schedules targeting an existing agent protect that agent from collection. Paused, completed,
 and new-agent schedules do not. A pane may remain open after collection; its next prompt resumes the

docs/architecture.md

@@ -121,6 +121,7 @@ Commander.js CLI with Docker-style commands. Common agent operations are also ex
 - `paseo daemon start/stop/restart/status/pair/set-password`
 - `paseo chat ls/create/inspect/post/read/wait/delete`
 - `paseo terminal ls/create/capture/send-keys/kill`
+- `paseo script ls/start/stop`
 - `paseo loop run/ls/inspect/logs/stop`
 - `paseo schedule create/ls/inspect/update/pause/resume/run-once/logs/delete`
 - `paseo heartbeat create/update/delete`
@@ -132,16 +133,19 @@ Commander.js CLI with Docker-style commands. Common agent operations are also ex
 
 Communicates with the daemon via the same WebSocket protocol as the app.
 
-### `packages/relay` — E2E encrypted relay
+### `packages/relay` — Relay transport and E2E encryption
 
 Enables remote access when the daemon is behind a firewall.
 
 - Curve25519 ECDH key exchange + XSalsa20-Poly1305 (NaCl `box`) encryption
-- Relay server is zero-knowledge — it routes encrypted bytes, cannot read content
+- The relay is zero-knowledge — it routes encrypted bytes and cannot read content
 - Client and daemon channels with identical API (`createClientChannel`, `createDaemonChannel`)
 - Pairing via QR code transfers the daemon's public key to the client
+- Optional E2EE capability negotiation preserves application frame kind: text plaintext uses base64 ciphertext text frames, while binary plaintext uses raw ciphertext binary frames; mixed-version peers remain base64-only
 - Self-hosted relays opt into TLS with `daemon.relay.useTls` or `PASEO_RELAY_USE_TLS=true`; the public (client-facing) TLS setting can be overridden independently via `daemon.relay.publicUseTls` or `PASEO_RELAY_PUBLIC_USE_TLS`
 
+The production relay server lives in [getpaseo/paseo-relay](https://github.com/getpaseo/paseo-relay). It is a distributed Elixir service. The Cloudflare relay implementation in this monorepo is retained as legacy code and is not deployed.
+
 See [SECURITY.md](../SECURITY.md) for the full threat model.
 
 ### Paseo Hub
@@ -208,7 +212,9 @@ There is no dedicated welcome message; the server emits a `status` session messa
 
 **Top-level WS envelopes** are `hello`, `recording_state`, `ping`/`pong`, and `session` (which wraps the rich union of session messages).
 
-Client liveness checks use the top-level JSON `ping`/`pong` envelope, not a session RPC and not RFC6455 protocol ping. The app runs through browser and React Native WebSocket APIs, which do not expose protocol ping, so this envelope is the portable way to test the direct or relay data path. Session RPC timeouts are operation failures and must not be treated as proof that the socket is dead.
+Client liveness checks use the top-level JSON `ping`/`pong` envelope, not a session RPC or RFC6455 control ping. Current clients ping every 10 seconds, beginning one interval after connecting. The first ping claims an application-ownership lease for that physical socket, all later inbound activity renews it, and the daemon forcibly terminates the socket if the lease expires. A legacy or raw socket that never sends an application ping never enters this lease and is not closed for omitting one. Session RPC timeouts are operation failures and must not be treated as proof that the socket is dead.
+
+Every physical send path enforces an 8 MiB outbound high-water mark, including JSON broadcasts, binary terminal frames, and the encrypted relay adapter's asynchronous queue. This sits above the terminal stream's 4 MiB soft backpressure threshold, leaving room for snapshot catch-up before the hard cutoff. JSON is serialized once per broadcast after sockets already at the limit are removed, then its exact byte length is checked for every remaining socket. A frame that would cross the limit is not sent; that physical socket is forcibly terminated without disturbing other sockets attached to the same logical session. Multiple tabs and simultaneous direct and relay paths may legitimately share a client id.
 
 Client session RPC waits default to 60s so slow relay or mobile networks do not turn a live but delayed daemon response into a false operation failure. Keep connect timeouts, app-level grace windows, explicit diagnostic latency probes, liveness ping timers, and genuinely long-running RPCs separate from this default.
 
@@ -246,6 +252,10 @@ Terminal I/O is sent as binary WebSocket frames decoded by `decodeTerminalStream
 Terminal PTY size is last-interacting-client-wins. A client claims the PTY size only when its terminal viewport genuinely changes size or the user focuses/taps the terminal. Passive rendering work — attaching, restoring visibility, font settling, renderer refits, or just looking at a visible terminal — must not send a resize frame. The server does not broadcast resize ownership; the resized PTY redraws through normal output, and every attached client renders that output in its own local viewport.
 
 There is also a separate file-transfer binary frame format in the same directory, used for download/upload streams.
+File downloads keep the existing `FileBegin`/`FileChunk`/`FileEnd` framing and stream 256 KiB chunks
+from one stable file handle. Each transfer awaits completion of its own physical WebSocket send before
+reading the next chunk; it is scoped to the requesting physical socket and does not queue unrelated
+messages or transfers.
 
 ### Compatibility rules
 
@@ -377,5 +387,5 @@ $PASEO_HOME/
 ## Deployment models
 
 1. **Local daemon** (default): `paseo daemon start` on `127.0.0.1:6767`
-2. **Managed desktop**: Electron app spawns daemon as subprocess
+2. **Managed desktop**: Electron app spawns daemon as subprocess, and stops it again on quit so that "restart the app" is a complete reset. Settings > Host > "Keep daemon running after quit" opts out. Only a daemon the desktop started is stopped — a daemon you started yourself with `paseo daemon start` is left alone (`paseo.pid` records `desktopManaged`).
 3. **Remote + relay**: Daemon behind firewall, relay bridges with E2E encryption

docs/development.md

@@ -29,6 +29,7 @@ Root checkout dev is intentionally split across terminals:
 - **Repo dev scripts** default to `$ROOT/.dev/paseo-home`, where `$ROOT` is the current checkout or worktree root. This keeps all dev state scoped to the checkout instead of the packaged desktop app.
 - **`npm run cli -- ...`** runs through the same dev-home wrapper as the dev scripts, so the in-repo CLI automatically targets the current checkout's `.dev/paseo-home` and configured dev daemon endpoint.
 - **Paseo-created worktrees** seed `$PASEO_WORKTREE_PATH/.dev/paseo-home` from `$PASEO_SOURCE_CHECKOUT_PATH/.dev/paseo-home` by copying durable JSON metadata. Runtime files like pid files, sockets, and logs are not copied.
+- **Paseo-created worktrees** read `.worktreeinclude` from the live source checkout before creation. Bare paths and `copy <path>` copy a snapshot into the new worktree; `symlink <path>` creates a live source link. Missing paths, malformed entries, unsafe paths, incompatible include overlaps, destination conflicts, unavailable platform links, and ordinary read/write failures are skipped individually and reported in the daemon log, so the rest of the plan still runs. A source symlink is allowed only when its resolved target remains inside the active source checkout. If that checkout is itself Paseo-managed, its own paths remain eligible while other managed worktree paths stay protected; `copy` snapshots that resolved target, while `symlink` links directly to it. Hard links are ordinary files. Each include is staged before it is committed; Paseo aborts creation only if it cannot safely clean up partial materialization state (or Git/worktree setup itself fails). Materialization finishes before `worktree.setup` runs.
 - **This repo's worktree setup** also best-effort seeds `packages/app/ios` and the newest `.dev/ios-build` entry from the source checkout so iOS simulator services can reuse native project and Xcode cache state when it is safe enough to do so.
 
 Override knobs:
@@ -242,6 +243,14 @@ commands use the same non-login Bash behavior on macOS/Linux, but preserve their
 existing `cmd.exe /c` string semantics on Windows. Service scripts are separate:
 they launch in a terminal and receive the service environment described below.
 
+Because the shell differs per platform, a lifecycle command that must run
+everywhere cannot use POSIX-only syntax — `VAR=1 cmd` env prefixes, `$VAR`
+expansion, `cp`/`rm`, or a `./scripts/*.sh` entrypoint all fail under PowerShell,
+and `bash` is not guaranteed to exist on Windows. Put that logic in a Node script
+that reads what it needs from `process.env` and invoke it as
+`node ./scripts/<name>.mjs`. This repo's own setup does exactly that in
+`scripts/seed-worktree-dev-state.mjs` and `scripts/seed-ios-native-cache.mjs`.
+
 ```json
 {
   "worktree": {

docs/docker.md

@@ -176,8 +176,9 @@ IPs and `localhost` are allowed by default.
 
 - Set `PASEO_PASSWORD` for any published port or network-reachable deployment.
 - Prefer HTTPS at the reverse proxy for direct browser access.
-- Use the Paseo relay for untrusted networks or mobile access when you do not
-  want to expose the daemon port directly.
+- Use the [official Paseo relay](https://github.com/getpaseo/paseo-relay) for
+  untrusted networks or mobile access when you do not want to expose the daemon
+  port directly.
 - The container is the isolation boundary for agents. Agents can read and write
   whatever you mount into `/workspace` and whatever credentials you place in
   `/home/paseo`.

docs/floating-panels.md

@@ -78,6 +78,29 @@ ordinary portals regardless of `z-index`, which would hide app toasts and
 tooltips behind the menu. The shared overlay scale keeps menus below toasts and
 lets tooltip portals paint above both.
 
+The shared overlay scale is relative for interactive surfaces: a base floating
+panel is below a base modal, while a floating panel rendered from inside a modal
+inherits that modal's layer and paints above it. Wrap portal content in
+`OverlayLayerProvider`; do not assign one global menu z-index. Desktop web
+comboboxes must use `overlay-root` too. Rendering them through React Native
+Web's `<Modal>` puts them in the browser top layer, where no ordinary modal
+portal can cover them.
+
+Painting and keyboard ownership use the same relative layer model. Register
+desktop modal, combobox, and dropdown focus scopes with `useWebOverlayRegistration`; the
+highest painted scope alone receives overlay keys, traps focus, and restores
+focus when it closes. Do not add component-local global Escape listeners: two
+stacked overlays would both close on one keypress.
+
+If an overlay is rendered by a global host rather than beneath its opener in
+the React tree, carry the opener's current layer through the host store and
+restore it with `OverlayLayerProvider`. Otherwise painting and keyboard
+ownership silently reset at the app root. When the opener is a global keyboard
+action and has no component context to carry, resolve the host layer with
+`useGlobalWebOverlayLayer` on its closed-to-open transition. It captures the
+current top registered layer before the new host joins the stack; do not give a
+global dialog a fixed root-derived modal layer.
+
 ## Gotcha 2 — Portal breaks lifecycle and coordinate-system inheritance
 
 A Portal escapes Android's hit-test, but it also escapes two things you were

docs/hub.md

@@ -45,8 +45,22 @@ replays the original prompt. A duplicate create returns the existing agent witho
 turn.
 
 Hub creates use the same agent creation path as trusted clients. They may select any existing
-worktree target shape and may request `autoArchive`. Worktree creation and terminal auto-archive use
-the shared workspace-aware lifecycle policy; Hub does not have a second launch or cleanup path.
+worktree target shape. Execution completion policy remains outside the daemon: a completed agent
+turn does not imply that the Hub execution is terminal.
+
+The Hub ends an execution by sending `hub.execution.control.request` with the durable execution ID
+and either `interrupt` or `archive`. The daemon resolves the agent from the authenticated daemon
+relationship plus that execution ID; callers cannot supply an agent ID or workspace path. Both
+actions are idempotent and continue to resolve from stored ownership after daemon restart.
+If no execution exists for that authenticated daemon and execution ID, interrupt and archive return
+success because the requested stopped or archived state already holds. An execution owned by another
+daemon is indistinguishable from a missing execution and is never exposed or affected.
+
+Interrupt uses the ordinary agent cancellation lifecycle. Archive first archives the owned agent.
+When that agent belongs to an active Paseo-owned worktree workspace, the daemon also archives the
+workspace through the shared workspace archive service, so the backing directory is removed only
+after its final active workspace reference disappears. Local and shared checkouts archive only the
+execution-owned agent.
 
 ## Disconnect and revocation
 

docs/product.md

@@ -43,7 +43,8 @@ This architecture means:
 
 - The daemon can run on any machine: laptop, VM, remote server
 - Multiple clients can connect simultaneously
-- Agents keep running when you close the app
+- Agents keep running when a client disconnects — the daemon owns them, not the client
+- Quitting the desktop app stops the daemon it started, so "restart the app" is a real fix; a daemon you run yourself is unaffected
 
 ## Target user
 

docs/providers.md

@@ -34,7 +34,7 @@ Pi import discovery reads Pi's persisted JSONL session files because Pi RPC does
 
 OMP is a first-class built-in provider, disabled by default. Its launch contract, typed runtime, agent/session behavior, history, permissions, imports, and test fake live under `providers/omp/`; only the provider-neutral JSONL child-process transport is shared with Pi. It launches `omp --mode rpc-ui`, uses OMP's `get_available_commands` RPC for slash-command discovery, bridges OMP `rpc-ui` approval dialogs into Paseo permissions, and imports terminal-started sessions from `~/.omp/agent/sessions` when enabled.
 
-OMP supports native Paseo host tools. The adapter registers the caller-scoped Paseo tool catalog directly with OMP, so `create_agent`, `send_agent_prompt`, `wait_for_agent`, and related tools do not need the internal MCP fallback. OMP's provider-managed task subagents are surfaced as Paseo subagents through `child_session` imports; the parent keeps the subagents track while the child runtime stays owned by OMP. Custom OMP profiles should extend `omp`; other Pi-compatible forks can still extend `pi`, override `command`, and set `params.sessionDir` to their JSONL session directory.
+OMP supports native Paseo host tools. The adapter registers the full caller-scoped Paseo tool catalog directly with OMP, matching providers such as Claude that expose the full catalog through MCP. Serialize every OMP host definition with `loadMode: "essential"` so `create_agent`, `send_agent_prompt`, `wait_for_agent`, and related tools remain direct calls; omitting the field makes OMP mount non-built-in names under `xd://` instead. OMP's provider-managed task subagents are surfaced as Paseo subagents through `child_session` imports; the parent keeps the subagents track while the child runtime stays owned by OMP. Custom OMP profiles should extend `omp`; other Pi-compatible forks can still extend `pi`, override `command`, and set `params.sessionDir` to their JSONL session directory.
 
 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.
 

docs/release.md

@@ -78,7 +78,7 @@ This bumps the version across all workspaces, runs checks, publishes to npm, and
 
 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`.
 
-Relay deployment is manual-only while `relay.paseo.sh` bridges traffic to the Fly deployment. Releases and pushes to `main` do not deploy the Cloudflare relay worker. Deploy it explicitly with `gh workflow run deploy-relay.yml` only when the production bridge should change.
+The production relay is the Elixir service in [getpaseo/paseo-relay](https://github.com/getpaseo/paseo-relay), with its own deployment process. Paseo releases and pushes to this repository do not deploy it. The Cloudflare relay code and workflow in this repository are legacy and are not used in production.
 
 **Stable means stable.** If the user says "stable" or "ship stable", do not ask whether they want a beta first. They picked stable; treat it as a direct stable release. Only run the beta flow when the user explicitly says "beta".
 

docs/service-proxy.md

@@ -26,6 +26,18 @@ dev--feature-auth--miniweb.localhost
 
 Local and public routes use one combined leftmost label (`script--branch--project`). This keeps the hostname compatible with normal single-level wildcard DNS and TLS. If the combined label would exceed DNS's 63-character label limit, Paseo truncates it with a deterministic hash suffix to avoid collisions.
 
+## Managing workspace scripts
+
+Configured `paseo.json` scripts can be managed without addressing their backing terminal directly:
+
+```bash
+paseo script ls [--cwd <path> | --workspace <workspace-id>]
+paseo script start <name> [--cwd <path> | --workspace <workspace-id>]
+paseo script stop <name> [--cwd <path> | --workspace <workspace-id>]
+```
+
+The commands return the same script metadata shown by the workspace: lifecycle, service port, proxy URLs, health, exit code, and supervised terminal ID. `stop` terminates the managed terminal rather than only removing the proxy route, so normal script lifecycle cleanup remains authoritative. MCP exposes matching `list_workspace_scripts`, `start_workspace_script`, and `stop_workspace_script` tools; those require an explicit workspace ID.
+
 ## Configuration
 
 Add a `serviceProxy` block under `daemon` in `~/.paseo/config.json`:
@@ -95,6 +107,29 @@ server {
 }
 ```
 
+Nginx's `$host` drops the port. If you terminate on a non-default port, use `$http_host` instead so the port survives — that is what "forwards the `Host` header unchanged" means here.
+
+## Forwarded headers
+
+Paseo sets these when it forwards a request to a workspace service:
+
+| Header              | Value                                                                                                                                   |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `X-Forwarded-Host`  | The `Host` header verbatim, including the port when the client used one                                                                 |
+| `X-Forwarded-Proto` | The request scheme (`http` on the WebSocket upgrade path)                                                                               |
+| `X-Forwarded-For`   | The immediate peer address. Replaces any existing chain, so behind your own reverse proxy this is the proxy's address, not the client's |
+| `X-Forwarded-Port`  | The port from the `Host` header when it has one, otherwise whatever your proxy already set                                              |
+
+`X-Forwarded-Port` follows the same trust rule as `X-Forwarded-Host`: the authority Paseo observed wins. When the `Host` header carries a port, that port is reported and replaces any inbound `X-Forwarded-Port`, so a client cannot forge one. When `Host` carries no port there is nothing to observe, so a value your reverse proxy set survives untouched — that is the case where nginx's `$host` drops the port and `X-Forwarded-Port` is the only source. Paseo never derives the port from the scheme. Any other `X-Forwarded-*` header your proxy sends is passed through untouched.
+
+Services that build absolute URLs should prefer `Host` or `X-Forwarded-Host`.
+
+### The forwarded authority is not authenticated
+
+Route lookup normalizes the port away before matching a service hostname, so a client can address the daemon with any port in `Host` and still reach the service. That port is what lands in `X-Forwarded-Host` and `X-Forwarded-Port`. Paseo also does not check whether an inbound `X-Forwarded-Port` came from a proxy in `trustedProxies` — when `Host` carries no port, a client-supplied value is passed through.
+
+Treat the forwarded authority as client-influenced input. A service that builds password reset links, absolute redirects, or cached URLs from it should pin its own public origin in configuration rather than deriving one from request headers. This is not specific to `X-Forwarded-Port`: the `Host` header has always carried a client-chosen port.
+
 ## Environment variables
 
 The listen address and public base URL can also be set via environment variables, which take precedence over `config.json`:

docs/terminal-performance.md

@@ -41,5 +41,5 @@ Terminal frames share the daemon main event loop with all agent traffic. The `ev
 ## Known remaining contention (follow-up candidates)
 
 - A single large `agent_stream` message (e.g. a 250KB diff payload) measurably delays terminal echo (~100ms-class dips) — cost is split between daemon serialization and app-side parse/render on the shared browser main thread.
-- Relay-attached clients pay pure-JS tweetnacl encryption + base64 per frame on the daemon main loop (`packages/relay/src/encrypted-channel.ts`).
+- Relay-attached clients pay pure-JS tweetnacl encryption on the daemon main loop (`packages/relay/src/encrypted-channel.ts`). Negotiated binary application frames stay binary ciphertext and avoid base64 encode/decode; text and mixed-version traffic remain base64 WebSocket text frames.
 - `sendToClient` re-stringifies session messages per socket; only matters for multi-socket connections.

docs/timeline-sync.md

@@ -37,6 +37,12 @@ Initialization timeouts guard lack of catch-up progress, not the full multi-page
 
 The first load of an agent without a local cursor is different: it fetches a bounded latest tail page. Older history remains user-driven by scrolling upward.
 
+Reaching the history-start threshold loads one older page and preserves the visible content anchor.
+Cursor progress does not trigger another page. The user must leave and return to the threshold unless
+the anchored page still leaves the viewport at history start, as with short or compacted content; in
+that case pagination continues as one loading operation until the page fills the viewport or history
+is exhausted.
+
 ## Durable item anchors
 
 Provider message IDs are not guaranteed for every displayed item. Paseo-generated system errors are one example. Rendered item indices are not durable either because pagination and projection can merge source rows.
@@ -61,6 +67,22 @@ recomposition while the runtime still owns the same directory snapshot and timel
 Removing the host from the registry is the destructive boundary: it stops the runtime and clears the
 session and host-scoped setup state together.
 
+The durable replica cache is a display cache, not a synchronization checkpoint. Its timeline record
+contains only the focused `agentId` and a truncated item tail. It never persists a cursor, epoch,
+older-history availability, authority status, or sync generation because those facts would describe
+the complete source dataset rather than the truncated display dataset.
+
+Restoring that cache produces a painted timeline: the items may render immediately, but the first
+daemon timeline request is still `tail`. A successful tail response atomically establishes canonical
+items, range, and older-history availability. Live rows received between cache paint and that tail
+response stay in the separate live head, do not advance a cursor or trigger gap recovery, and are
+reconciled with the authoritative tail and subsequent catch-up.
+
+Every daemon-derived live item carries its timeline epoch and sequence position. Bootstrap
+replacement keeps only positioned rows newer than the page it installs, while unresolved local
+submissions remain governed by the submission registry. This prevents a page from duplicating rows
+it already covers without making the display replica authoritative.
+
 ## Selective and legacy delivery
 
 The app chooses one delivery policy from `server_info.features.selectiveAgentTimeline`:
@@ -87,14 +109,42 @@ its completion advances `seqEnd`, followed by a merged assistant message. The ap
 remaining page through the existing stream reducer. It must not append full projected text to a
 live prefix.
 
-Optimistic user prompts occupy stable timeline slots. Catch-up never extracts, delays, or reinserts
-them. A canonical user row replaces its matching slot in place; an unmatched prompt stays exactly
-where the user submitted it. Other canonical rows are applied after the already-present timeline
-instead of relocating visible user messages around newly fetched history.
+Every path that sends a message to an agent — composer send, dictation accept-and-send, queued
+send-now, and the automatic queue drain in `HostRuntime` — goes through
+`dispatchComposerAgentMessage` with a submission writer. There is no second transport for the same
+product action: calling `client.sendAgentMessage` directly skips the submitted row and the pending
+footer, and permanently drops attachments because the daemon does not echo them back.
+
+A submitted prompt is one `UserMessageItem` row. That row is the authoritative local presentation:
+its stable identity, text, timestamp, images, and attachments do not change when the provider
+acknowledges it. Submission lifecycle is a separate record keyed by agent, not another row shape or
+a property inferred from message identity. The transaction registry holds every unresolved send and
+records RPC acceptance and provider acknowledgement independently. Provider acknowledgement exists
+solely so a later transport error cannot roll back a prompt already observed canonically.
+
+The daemon's accepted response already waits for the correlated run start, but its response and the
+directory update reach client state separately. An accepted transaction remains active until the
+directory observes that run or canonical ingestion acknowledges the prompt, bridging those ordered
+authorities without inspecting timeline snapshots. Either signal clears only an RPC-accepted
+transaction, regardless of which arrived first; it cannot settle a fresh send.
+Overlapping sends settle independently rather than collapsing to one newest pending message.
 
 Canonical submitted user rows carry the provider's `messageId` and Paseo's optional
-`clientMessageId`. Clients reconcile optimistic prompts by `clientMessageId`. Content matching is
-limited to the dated compatibility path for daemon timelines created before that field existed.
+`clientMessageId`. The user-message producer reconciles them by `clientMessageId`, adds provider
+identity to the existing row, and keeps the local presentation in its original timeline slot.
+Content matching is limited to the dated compatibility path for daemon timelines created before
+that field existed. Canonical ingestion may match only an explicit unreconciled local candidate;
+the draft-create handoff is the one boundary that also permits the legacy canonical twin to have
+arrived first. Generic reducers and consumers do not reimplement message identity matching.
+
+Ordinary bootstrap, same-epoch reset, and catch-up replacement preserve unmatched locally submitted
+rows because a provider may never echo them. A known epoch change or rewind replaces history and
+drops acknowledged local rows omitted by the new canonical epoch; every transaction not yet
+acknowledged by the provider, and no other local row, crosses that destructive boundary.
+
+Canonical replacement owns both timeline lanes. A matching local row keeps its presentation ID and
+payload while taking the canonical row's ordered position. If a live assistant head is the
+canonical assistant prefix, it stays in the head lane. No row may be returned in both lanes.
 
 ## Relevant code
 

nix/npm-deps.hash

@@ -1 +1 @@
-sha256-t7FqvPj7U5YidGH9OZ1kFnD2dPTYUyjcxBlzAJU7Mak=
+sha256-n7k3zQ1NOm7dGmpqKE6RaEkl50/M2eFek6XIQJbYCEc=

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "paseo",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "paseo",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "hasInstallScript": true,
       "license": "AGPL-3.0-or-later",
       "workspaces": [
@@ -35211,7 +35211,7 @@
     },
     "packages/app": {
       "name": "@getpaseo/app",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "dependencies": {
         "@codemirror/commands": "6.10.4",
         "@codemirror/language": "6.12.4",
@@ -36236,18 +36236,19 @@
     },
     "packages/cli": {
       "name": "@getpaseo/cli",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "dependencies": {
         "@clack/prompts": "^1.0.0",
-        "@getpaseo/client": "0.2.1",
-        "@getpaseo/protocol": "0.2.1",
-        "@getpaseo/server": "0.2.1",
+        "@getpaseo/client": "0.2.3",
+        "@getpaseo/protocol": "0.2.3",
+        "@getpaseo/server": "0.2.3",
         "chalk": "^5.3.0",
         "commander": "^12.0.0",
         "mime-types": "^2.1.35",
         "tree-kill": "^1.2.2",
         "ws": "^8.14.2",
-        "yaml": "^2.8.4"
+        "yaml": "^2.8.4",
+        "zod": "^4.4.3"
       },
       "bin": {
         "paseo": "bin/paseo"
@@ -36487,10 +36488,10 @@
     },
     "packages/client": {
       "name": "@getpaseo/client",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "dependencies": {
-        "@getpaseo/protocol": "0.2.1",
-        "@getpaseo/relay": "0.2.1",
+        "@getpaseo/protocol": "0.2.3",
+        "@getpaseo/relay": "0.2.3",
         "zod": "^4.4.3"
       },
       "devDependencies": {
@@ -36501,7 +36502,7 @@
     },
     "packages/desktop": {
       "name": "@getpaseo/desktop",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "@getpaseo/cli": "*",
@@ -36744,7 +36745,7 @@
     },
     "packages/expo-two-way-audio": {
       "name": "@getpaseo/expo-two-way-audio",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "license": "MIT",
       "devDependencies": {
         "@types/jest": "^29.5.14",
@@ -37640,7 +37641,7 @@
     },
     "packages/highlight": {
       "name": "@getpaseo/highlight",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "dependencies": {
         "@codemirror/language": "6.12.4",
         "@codemirror/legacy-modes": "^6.5.3",
@@ -37872,7 +37873,7 @@
     },
     "packages/protocol": {
       "name": "@getpaseo/protocol",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "dependencies": {
         "zod": "^4.4.3"
       },
@@ -37885,7 +37886,7 @@
     },
     "packages/relay": {
       "name": "@getpaseo/relay",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "dependencies": {
         "base64-js": "^1.5.1",
         "tweetnacl": "^1.0.3",
@@ -38103,15 +38104,15 @@
     },
     "packages/server": {
       "name": "@getpaseo/server",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "dependencies": {
         "@agentclientprotocol/sdk": "^0.17.1",
-        "@anthropic-ai/claude-agent-sdk": "^0.3.214",
+        "@anthropic-ai/claude-agent-sdk": "^0.3.220",
         "@anthropic-ai/sdk": "^0.104.2",
-        "@getpaseo/client": "0.2.1",
-        "@getpaseo/highlight": "0.2.1",
-        "@getpaseo/protocol": "0.2.1",
-        "@getpaseo/relay": "0.2.1",
+        "@getpaseo/client": "0.2.3",
+        "@getpaseo/highlight": "0.2.3",
+        "@getpaseo/protocol": "0.2.3",
+        "@getpaseo/relay": "0.2.3",
         "@isaacs/ttlcache": "^2.1.4",
         "@modelcontextprotocol/sdk": "^1.20.1",
         "@opencode-ai/sdk": "1.14.46",
@@ -38155,22 +38156,22 @@
       }
     },
     "packages/server/node_modules/@anthropic-ai/claude-agent-sdk": {
-      "version": "0.3.214",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.3.214.tgz",
-      "integrity": "sha512-wt5ImwhU+p259Zt4K/Q9v5xVi6ruxYO5+KFICyJxnjs/QFEClAeSRqhcXx1J8jgGfatPW1faw09hkm66680UjA==",
+      "version": "0.3.220",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.3.220.tgz",
+      "integrity": "sha512-glc7SdwPkOkLw8oxwLo9PKTdLJGqW/PIR4urWXFoRtX9YllwozsEVc5Tc1+EvLSkfrsxPJqQWqOgpjUOQXf1oA==",
       "license": "SEE LICENSE IN README.md",
       "engines": {
         "node": ">=18.0.0"
       },
       "optionalDependencies": {
-        "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.214",
-        "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.214",
-        "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.214",
-        "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.214",
-        "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.214",
-        "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.214",
-        "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.214",
-        "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.214"
+        "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.220",
+        "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.220",
+        "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.220",
+        "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.220",
+        "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.220",
+        "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.220",
+        "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.220",
+        "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.220"
       },
       "peerDependencies": {
         "@anthropic-ai/sdk": ">=0.93.0",
@@ -38179,9 +38180,9 @@
       }
     },
     "packages/server/node_modules/@anthropic-ai/claude-agent-sdk/node_modules/@anthropic-ai/claude-agent-sdk-darwin-arm64": {
-      "version": "0.3.214",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-arm64/-/claude-agent-sdk-darwin-arm64-0.3.214.tgz",
-      "integrity": "sha512-vAAOeVtlXs3p7MpFVfvfu9ja32eaKtB+MDZnPxCbdzxJk5nofCHlNsHa1UJwXHOsP9lOnFYNIccYztsZ4DNaJA==",
+      "version": "0.3.220",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-arm64/-/claude-agent-sdk-darwin-arm64-0.3.220.tgz",
+      "integrity": "sha512-7VxlbEosK7DODiOnsjoVd0DSJzbnaPrM2jelMHI0y8zx1UnLS3WC6EFUXbvy74F2sXqEznh2tzn7EKWInaRN6Q==",
       "cpu": [
         "arm64"
       ],
@@ -38192,9 +38193,9 @@
       ]
     },
     "packages/server/node_modules/@anthropic-ai/claude-agent-sdk/node_modules/@anthropic-ai/claude-agent-sdk-darwin-x64": {
-      "version": "0.3.214",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-x64/-/claude-agent-sdk-darwin-x64-0.3.214.tgz",
-      "integrity": "sha512-NTbV8U2yucxCWqEiDC7L0MUehNmd8x3Op8OGzLZRhMF3xmQBy2DxpXiNZgSwwKWNDC3HdgKmJM5ZBbT7XrF/0g==",
+      "version": "0.3.220",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-x64/-/claude-agent-sdk-darwin-x64-0.3.220.tgz",
+      "integrity": "sha512-X9RwDsSmbF6ultKZroaip+DL8WRgC64gHbrAwrRlAFSPNZV7zmJyP2ur8rW7KrxqmtuehdMMkw8+SAC/6hD2PA==",
       "cpu": [
         "x64"
       ],
@@ -38205,9 +38206,9 @@
       ]
     },
     "packages/server/node_modules/@anthropic-ai/claude-agent-sdk/node_modules/@anthropic-ai/claude-agent-sdk-linux-arm64": {
-      "version": "0.3.214",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64/-/claude-agent-sdk-linux-arm64-0.3.214.tgz",
-      "integrity": "sha512-KBCf+BlusG0ZcgvpjjHwv1kh+6WiR8vJbPjpR2udwkrtcQgKLN+24l+FeaQEzO2TL+ExCmM1KC4tNPvnPpy+tw==",
+      "version": "0.3.220",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64/-/claude-agent-sdk-linux-arm64-0.3.220.tgz",
+      "integrity": "sha512-WkROPwWskqhKR9XgnmseHQ6rLi9zM9qt57IWoToIjL/eXOqDWipp7JXZ1L5ud+LrA42dunHPZfBwD/vXZ+A7LA==",
       "cpu": [
         "arm64"
       ],
@@ -38218,9 +38219,9 @@
       ]
     },
     "packages/server/node_modules/@anthropic-ai/claude-agent-sdk/node_modules/@anthropic-ai/claude-agent-sdk-linux-arm64-musl": {
-      "version": "0.3.214",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64-musl/-/claude-agent-sdk-linux-arm64-musl-0.3.214.tgz",
-      "integrity": "sha512-i06wQRsmevE7spY1ryYfs+NP+xdZ1FwAyTjDaF0k/xG+cgtzZYghTFUemdYF3GVwgWgpcava9GiCFDT3DoHI6w==",
+      "version": "0.3.220",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64-musl/-/claude-agent-sdk-linux-arm64-musl-0.3.220.tgz",
+      "integrity": "sha512-OHoZOZ8Cf2TBr6oXIXPwyvUxj9jrq2w8E4poA8dMpacXszcPSPiCQCMuuOh4aWJzfeJE1+TtWxhKMVb2csXyZQ==",
       "cpu": [
         "arm64"
       ],
@@ -38231,9 +38232,9 @@
       ]
     },
     "packages/server/node_modules/@anthropic-ai/claude-agent-sdk/node_modules/@anthropic-ai/claude-agent-sdk-linux-x64": {
-      "version": "0.3.214",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64/-/claude-agent-sdk-linux-x64-0.3.214.tgz",
-      "integrity": "sha512-vqadSceJkBKHaTUszxI35uTuECGWtsHWK/mOwIJ4b9DUtYYySz6EJEk4gHg4ccutisJ/oRVCpFXHIKFb+osrKw==",
+      "version": "0.3.220",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64/-/claude-agent-sdk-linux-x64-0.3.220.tgz",
+      "integrity": "sha512-tkTJFnpR9VifvWX2fmkCAPkT6+8Wk/gVu8B5jsVekKZPiZoWRHmMXO30BnZn+f0TZhgYP+82PSX3S8crH1kn+w==",
       "cpu": [
         "x64"
       ],
@@ -38244,9 +38245,9 @@
       ]
     },
     "packages/server/node_modules/@anthropic-ai/claude-agent-sdk/node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl": {
-      "version": "0.3.214",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64-musl/-/claude-agent-sdk-linux-x64-musl-0.3.214.tgz",
-      "integrity": "sha512-948RstHDhs0E69h+2dKYWIAL1kcwEme4zvtgNUwP8XpKXzWOhrTKmd6MAokHn25zwfuSx5d+HE0XHfFH6R4hLg==",
+      "version": "0.3.220",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64-musl/-/claude-agent-sdk-linux-x64-musl-0.3.220.tgz",
+      "integrity": "sha512-K+FWj+LcGhC1Z7wqeWoLxm1iemcba5xKpLLFVwYm4V6HyMx3ruYd/2r2TiQtjT+JWeNFWIys0ScHiItR6vWAiA==",
       "cpu": [
         "x64"
       ],
@@ -38257,9 +38258,9 @@
       ]
     },
     "packages/server/node_modules/@anthropic-ai/claude-agent-sdk/node_modules/@anthropic-ai/claude-agent-sdk-win32-arm64": {
-      "version": "0.3.214",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-arm64/-/claude-agent-sdk-win32-arm64-0.3.214.tgz",
-      "integrity": "sha512-CEKlPFCPv+ee79utQMEDSsgeo2f27ulhNHpjrKIt1jXz5G04J7lAWN/QwvPDv9XaLBkWpyfqZWiPXlRcwuaO/w==",
+      "version": "0.3.220",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-arm64/-/claude-agent-sdk-win32-arm64-0.3.220.tgz",
+      "integrity": "sha512-rIwgq0UwQExWl6KrHUyC4w5KwpL9l6nd95aUTx6RitexaAuEw//xtfTVLnuE4hDDQZFkzEwpdKc3nxDWoGcUbA==",
       "cpu": [
         "arm64"
       ],
@@ -38270,9 +38271,9 @@
       ]
     },
     "packages/server/node_modules/@anthropic-ai/claude-agent-sdk/node_modules/@anthropic-ai/claude-agent-sdk-win32-x64": {
-      "version": "0.3.214",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-x64/-/claude-agent-sdk-win32-x64-0.3.214.tgz",
-      "integrity": "sha512-cJMJfFoR9IWBZWnTtt9PnEm89hGOsZjoDNjOCEOF3+x+g/ANIXAjMJTcaQYv2HKh6MylWZ0AkxBASI+twkukaQ==",
+      "version": "0.3.220",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-x64/-/claude-agent-sdk-win32-x64-0.3.220.tgz",
+      "integrity": "sha512-MuOuXhbr66HlGaWXD2f3w0k2PsvmnbkwcUZ0dAe2poFLdl72GC2dapwwOBefxm9QmoNqk9+jmv/dSKGOVWyvLw==",
       "cpu": [
         "x64"
       ],
@@ -38648,7 +38649,7 @@
     },
     "packages/website": {
       "name": "@getpaseo/website",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "dependencies": {
         "@cloudflare/vite-plugin": "^1.29.1",
         "@cloudflare/workers-types": "^4.20260317.1",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "private": true,
   "description": "Paseo: voice-controlled development environment for local AI coding agents",
   "keywords": [
@@ -49,9 +49,9 @@
     "build:relay:clean": "npm run build:clean --workspace=@getpaseo/relay",
     "build:protocol": "npm run build --workspace=@getpaseo/protocol",
     "build:protocol:clean": "npm run build:clean --workspace=@getpaseo/protocol",
-    "build:client": "npm run build:protocol && npm run build --workspace=@getpaseo/client",
+    "build:client": "npm run build --workspace=@getpaseo/client",
     "build:client:clean": "npm run build:protocol:clean && npm run build:clean --workspace=@getpaseo/client",
-    "build:server-deps": "npm run build:highlight && npm run build:relay && npm run build:client",
+    "build:server-deps": "concurrently --kill-others-on-fail --names highlight,relay,client --prefix-colors yellow,blue,cyan \"npm run build:highlight\" \"npm run build:relay\" \"npm run build:client\"",
     "build:server-deps:clean": "npm run build:highlight:clean && npm run build:relay:clean && npm run build:client:clean",
     "build:server": "npm run build:server-deps && npm run build --workspace=@getpaseo/server && npm run build --workspace=@getpaseo/cli",
     "build:server:clean": "npm run build:server-deps:clean && npm run build:clean --workspace=@getpaseo/server && npm run build:clean --workspace=@getpaseo/cli",

packages/app/e2e/agent-message-submission.spec.ts

@@ -0,0 +1,685 @@
+import type { Locator, Page } from "@playwright/test";
+import { expect, test as baseTest } from "./fixtures";
+import { awaitToolCall, expectAgentIdle } from "./helpers/agent-stream";
+import { gateNextAgentMessage } from "./helpers/agent-message-gate";
+import {
+  attachImageFromMenu,
+  expectComposerDraft,
+  expectComposerEditable,
+  expectAttachmentPill,
+  expectComposerVisible,
+  fillComposerDraft,
+  sendDraftToQueue,
+  startRunningMockAgent,
+} from "./helpers/composer";
+import { openAgentRoute, seedMockAgentWorkspace } from "./helpers/mock-agent";
+import { readScrollMetrics } from "./helpers/agent-bottom-anchor";
+import { seedWorkspace } from "./helpers/seed-client";
+import { waitForWorkspaceTabsVisible } from "./helpers/workspace-tabs";
+import { getServerId } from "./helpers/server-id";
+import { buildHostWorkspaceRoute } from "@/utils/host-routes";
+import { delayBrowserAgentCreatedStatus } from "./helpers/new-workspace";
+import { installDaemonWebSocketGate } from "./helpers/daemon-websocket-gate";
+import { selectModel } from "./helpers/app";
+
+const IMAGE = {
+  name: "message-submission.png",
+  mimeType: "image/png",
+  buffer: Buffer.from(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
+    "base64",
+  ),
+};
+
+interface MessageGeometry {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+interface SubmissionScenario {
+  gate: Awaited<ReturnType<typeof gateNextAgentMessage>>;
+}
+
+interface DraftCreateScenario {
+  workspaceId: string;
+  agentCreatedDelay: Awaited<ReturnType<typeof delayBrowserAgentCreatedStatus>>;
+}
+
+interface RejectionScenario {
+  errorMessage: string;
+}
+
+interface UnrelatedRunningScenario {
+  gate: Awaited<ReturnType<typeof gateNextAgentMessage>>;
+  agent: Awaited<ReturnType<typeof seedMockAgentWorkspace>>;
+}
+
+const test = baseTest.extend<{
+  submissionScenario: SubmissionScenario;
+  draftCreateScenario: DraftCreateScenario;
+  rejectionScenario: RejectionScenario;
+  unrelatedRunningScenario: UnrelatedRunningScenario;
+}>({
+  submissionScenario: async ({ page }, provide, testInfo) => {
+    const gate = await gateNextAgentMessage(page);
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: `message-submission-${testInfo.workerIndex}-`,
+      title: "Message submission regression",
+      model: "ten-second-stream",
+    });
+    await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+    await expectComposerVisible(page);
+    await expectAgentIdle(page);
+    await provide({ gate });
+    await agent.cleanup();
+  },
+  draftCreateScenario: async ({ page }, provide, testInfo) => {
+    const agentCreatedDelay = await delayBrowserAgentCreatedStatus(page);
+    const workspace = await seedWorkspace({
+      repoPrefix: `message-create-handoff-${testInfo.workerIndex}-`,
+    });
+    await provide({ workspaceId: workspace.workspaceId, agentCreatedDelay });
+    agentCreatedDelay.release();
+    await workspace.cleanup();
+  },
+  rejectionScenario: async ({ page }, provide, testInfo) => {
+    const errorMessage = "Requested mock prompt rejection";
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: `message-rejection-${testInfo.workerIndex}-`,
+      title: "Message rejection regression",
+      model: "ten-second-stream",
+      featureValues: { mockPromptRejections: 1 },
+    });
+    await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+    await expectComposerVisible(page);
+    await expectAgentIdle(page);
+    await provide({ errorMessage });
+    await agent.cleanup();
+  },
+  unrelatedRunningScenario: async ({ page }, provide, testInfo) => {
+    const gate = await gateNextAgentMessage(page);
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: `unrelated-running-${testInfo.workerIndex}-`,
+      title: "Unrelated running transition",
+      model: "one-minute-stream",
+    });
+    await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+    await expectComposerVisible(page);
+    await expectAgentIdle(page);
+    await provide({ gate, agent });
+    await agent.cleanup();
+  },
+});
+
+async function submitMessageWithImage(page: Page, prompt: string): Promise<Locator> {
+  await attachImageFromMenu(page, IMAGE);
+  await expectAttachmentPill(page, "composer-image-attachment-pill");
+  const composer = page.getByRole("textbox", { name: "Message agent..." }).first();
+  await composer.fill(prompt);
+  await composer.press("Enter");
+  const nextFrame = await composer.evaluate(
+    (composerElement, submittedPrompt) =>
+      new Promise<{
+        rowPresent: boolean;
+        workingPresent: boolean;
+        composerValue: string | null;
+        attachmentPresent: boolean;
+      }>((resolve) => {
+        requestAnimationFrame(() => {
+          const rows = Array.from(document.querySelectorAll('[data-testid="user-message"]'));
+          const composerInput = composerElement as HTMLInputElement | HTMLTextAreaElement;
+          resolve({
+            rowPresent: rows.some((row) => row.textContent?.includes(submittedPrompt)),
+            workingPresent: Boolean(
+              document.querySelector('[data-testid="turn-working-indicator"]'),
+            ),
+            composerValue: composerInput.value,
+            attachmentPresent: Boolean(
+              document.querySelector('[data-testid="composer-image-attachment-pill"]'),
+            ),
+          });
+        });
+      }),
+    prompt,
+  );
+  expect(nextFrame).toEqual({
+    rowPresent: true,
+    workingPresent: true,
+    composerValue: "",
+    attachmentPresent: false,
+  });
+  return page.getByTestId("user-message").filter({ hasText: prompt }).last();
+}
+
+async function submitImageOnlyMessage(page: Page): Promise<Locator> {
+  await attachImageFromMenu(page, IMAGE);
+  await expectAttachmentPill(page, "composer-image-attachment-pill");
+  await page.getByRole("textbox", { name: "Message agent..." }).first().press("Enter");
+  const userMessage = page.getByTestId("user-message").last();
+  await expect(userMessage).toBeVisible();
+  await expect(userMessage.getByRole("button", { name: "Open image attachment" })).toBeVisible();
+  return userMessage;
+}
+
+async function expectPendingSubmission(page: Page, userMessage: Locator): Promise<void> {
+  await expect(userMessage).toBeVisible();
+  await expect(page.getByTestId("turn-working-indicator")).toBeVisible();
+  await expect(page.getByRole("textbox", { name: "Message agent..." }).first()).toHaveValue("");
+  await expect(page.getByTestId("composer-image-attachment-pill")).toHaveCount(0);
+  await expect(userMessage.getByTestId("user-message-timestamp")).toBeAttached();
+  await expect(userMessage.getByTestId("user-message-trailing-row")).toHaveCSS("opacity", "0");
+  await expect(userMessage).toHaveAttribute("aria-busy", "true");
+  await expect(userMessage.getByRole("button", { name: "Open image attachment" })).toBeVisible();
+}
+
+async function readMessageGeometry(page: Page, userMessage: Locator): Promise<MessageGeometry> {
+  const box = await userMessage.boundingBox();
+  if (!box) throw new Error("Submitted user message has no browser geometry");
+  const { offsetY } = await readScrollMetrics(page);
+  return { x: box.x, y: box.y + offsetY, width: box.width, height: box.height };
+}
+
+async function beginWorkingFooterContinuityCheck(page: Page): Promise<() => Promise<void>> {
+  await expect(page.getByTestId("turn-working-indicator")).toBeVisible();
+  await page.evaluate(() => {
+    const state = { active: true, sawMissing: false };
+    const windowState = window as unknown as Record<string, unknown>;
+    windowState.__messageSubmissionFooterContinuity = state;
+    const checkFrame = () => {
+      if (!state.active) return;
+      if (!document.querySelector('[data-testid="turn-working-indicator"]')) {
+        state.sawMissing = true;
+      }
+      requestAnimationFrame(checkFrame);
+    };
+    requestAnimationFrame(checkFrame);
+  });
+
+  return async () => {
+    const sawMissing = await page.evaluate(() => {
+      const windowState = window as unknown as Record<string, unknown>;
+      const state = windowState.__messageSubmissionFooterContinuity as
+        | { active: boolean; sawMissing: boolean }
+        | undefined;
+      if (!state) throw new Error("Working-footer continuity check was not started");
+      state.active = false;
+      delete windowState.__messageSubmissionFooterContinuity;
+      return state.sawMissing;
+    });
+    expect(sawMissing).toBe(false);
+  };
+}
+
+async function expectAcceptedSubmission(
+  page: Page,
+  userMessage: Locator,
+  submittedGeometry: MessageGeometry,
+): Promise<void> {
+  await expect(page.getByTestId("turn-working-indicator")).toBeVisible();
+  await expect(userMessage).toHaveAttribute("aria-busy", "false", { timeout: 30_000 });
+  await expect(page.getByTestId("turn-working-indicator")).toBeVisible();
+  expect(await readMessageGeometry(page, userMessage)).toEqual(submittedGeometry);
+}
+
+async function submitMessageThatWillBeRejected(page: Page, prompt: string): Promise<void> {
+  await attachImageFromMenu(page, IMAGE);
+  await expectAttachmentPill(page, "composer-image-attachment-pill");
+  const composer = page.getByRole("textbox", { name: "Message agent..." }).first();
+  await composer.fill(prompt);
+  await composer.press("Enter");
+}
+
+async function expectRejectedSubmissionRestored(
+  page: Page,
+  input: { prompt: string; errorMessage: string },
+): Promise<void> {
+  await expect(page.getByText(input.errorMessage)).toBeVisible({ timeout: 30_000 });
+  await expectComposerDraft(page, input.prompt);
+  await expectComposerEditable(page);
+  await expectAttachmentPill(page, "composer-image-attachment-pill");
+  await expect(page.getByRole("button", { name: "Send message" })).toBeEnabled();
+  await expect(page.getByTestId("user-message").filter({ hasText: input.prompt })).toHaveCount(0);
+  await expect(page.getByTestId("turn-working-indicator")).toHaveCount(0);
+}
+
+async function retryRestoredSubmission(page: Page, prompt: string): Promise<void> {
+  await page.getByRole("textbox", { name: "Message agent..." }).first().press("Enter");
+  const userMessage = page.getByTestId("user-message").filter({ hasText: prompt });
+  await expect(userMessage).toHaveCount(1);
+  await expect(userMessage).toHaveAttribute("aria-busy", "false", { timeout: 30_000 });
+  await expect(userMessage.getByRole("button", { name: "Open image attachment" })).toBeVisible();
+  await expect(page.getByTestId("composer-image-attachment-pill")).toHaveCount(0);
+}
+
+async function queueMessage(page: Page, prompt: string): Promise<void> {
+  await fillComposerDraft(page, prompt);
+  await sendDraftToQueue(page);
+}
+
+async function expectQueuedSendFailuresRestored(page: Page, prompts: string[]): Promise<void> {
+  await expect(page.getByRole("button", { name: "Send queued message now" })).toHaveCount(
+    prompts.length,
+  );
+  for (const prompt of prompts) {
+    await expect(page.getByTestId("user-message").filter({ hasText: prompt })).toHaveCount(0);
+  }
+}
+
+async function expectFailedSubmissionRestored(page: Page, prompt: string): Promise<void> {
+  await expectComposerDraft(page, prompt);
+  await expectComposerEditable(page);
+  await expect(page.getByTestId("user-message").filter({ hasText: prompt })).toHaveCount(0);
+}
+
+async function expectInterruptedTurnOrderAfterReconnect(
+  page: Page,
+  testInfo: { workerIndex: number },
+): Promise<void> {
+  const gate = await installDaemonWebSocketGate(page);
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: `submission-reconnect-${testInfo.workerIndex}-`,
+    title: "Submission reconnect ordering",
+    model: "ten-second-stream",
+  });
+  const prompt = "Keep this prompt before its response.";
+  try {
+    await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+    await expectComposerVisible(page);
+    await agent.client.sendAgentMessage(agent.agentId, "Start the turn that will be interrupted.");
+    await expect(page.getByRole("button", { name: /stop|cancel/i }).first()).toBeVisible();
+    await expect(page.getByText("Cycle 1", { exact: true })).toBeVisible();
+    await queueMessage(page, prompt);
+    gate.setAgentStreamSuppressed(true);
+    await page.getByRole("button", { name: "Send queued message now" }).click();
+    const promptRow = page.getByTestId("user-message").filter({ hasText: prompt });
+    await expect(promptRow).toBeVisible();
+    await gate.waitForServerMessage("send_agent_message_response");
+    await gate.drop();
+    await agent.client.waitForFinish(agent.agentId, 30_000);
+    gate.setAgentStreamSuppressed(false);
+    gate.forceNextTimelineEpochReset();
+    gate.restoreFresh();
+    await gate.waitForServerMessage("fetch_agent_timeline_response", 2);
+    const response = page.getByText("(end of synthetic stream)", { exact: true }).last();
+    await expect(promptRow).toBeVisible();
+    await expect(response).toBeVisible();
+    await expectRenderedBefore(promptRow, response);
+  } finally {
+    gate.restore();
+    await agent.cleanup();
+  }
+}
+
+async function expectCompletedSubmissionClearsAfterMissedRunningTransition(
+  page: Page,
+  testInfo: { workerIndex: number },
+): Promise<void> {
+  const gate = await installDaemonWebSocketGate(page);
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: `submission-missed-running-${testInfo.workerIndex}-`,
+    title: "Submission missed running transition",
+    model: "ten-second-stream",
+  });
+  try {
+    await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+    await expectComposerVisible(page);
+    await expectAgentIdle(page);
+    gate.holdNextClientRequest("send_agent_message_request");
+    const userMessage = await submitImageOnlyMessage(page);
+    await gate.waitForHeldClientRequest();
+    gate.setServerMessageSuppressed("agent_status", true);
+    gate.setServerMessageSuppressed("agent_update", true);
+    gate.releaseHeldClientRequest();
+    await gate.waitForServerMessage("send_agent_message_response");
+    await expect(userMessage).toHaveAttribute("aria-busy", "false");
+    await gate.drop();
+    await agent.client.waitForFinish(agent.agentId, 30_000);
+    gate.setServerMessageSuppressed("agent_status", false);
+    gate.setServerMessageSuppressed("agent_update", false);
+    gate.restoreFresh();
+    await gate.waitForServerMessage("fetch_agent_timeline_response", 2);
+    await expect(page.getByText("(end of synthetic stream)", { exact: true }).last()).toBeVisible();
+    await expect(page.getByTestId("turn-working-indicator")).toHaveCount(0);
+    await expect(userMessage).toHaveAttribute("aria-busy", "false");
+  } finally {
+    gate.restore();
+    await agent.cleanup();
+  }
+}
+
+async function expectProviderAcknowledgementBeforeRpcAcceptanceSettlesSubmission(
+  page: Page,
+  testInfo: { workerIndex: number },
+): Promise<void> {
+  const gate = await installDaemonWebSocketGate(page);
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: `submission-ack-before-rpc-${testInfo.workerIndex}-`,
+    title: "Submission acknowledgement before RPC",
+    model: "ten-second-stream",
+  });
+  const prompt = "Settle this provider-acknowledged submission.";
+  try {
+    await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+    await expectComposerVisible(page);
+    await expectAgentIdle(page);
+    gate.setServerMessageSuppressed("agent_status", true);
+    gate.setServerMessageSuppressed("agent_update", true);
+    gate.holdNextServerMessage("send_agent_message_response");
+    const userMessage = await submitMessageWithImage(page, prompt);
+    await gate.waitForHeldServerMessage();
+    await gate.waitForAgentStreamItem("user_message");
+    gate.releaseHeldServerMessage();
+    await gate.drop();
+    await expect(page.getByTestId("turn-working-indicator")).toHaveCount(0);
+    await expect(userMessage).toHaveAttribute("aria-busy", "false");
+  } finally {
+    gate.restore();
+    await agent.cleanup();
+  }
+}
+
+async function expectLegacyAssistantStartsAfterInterruptedPrompt(
+  page: Page,
+  testInfo: { workerIndex: number },
+): Promise<void> {
+  const gate = await installDaemonWebSocketGate(page);
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: `submission-legacy-assistant-${testInfo.workerIndex}-`,
+    title: "Legacy assistant interrupt boundary",
+    model: "ten-second-stream",
+  });
+  const prompt = "Start the replacement answer after this prompt.";
+  try {
+    await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+    await expectComposerVisible(page);
+    await agent.client.sendAgentMessage(agent.agentId, "Start the interrupted answer.");
+    await expect(page.getByText("Cycle 1", { exact: true })).toBeVisible();
+    await queueMessage(page, prompt);
+    gate.setAssistantMessageIdsStripped(true);
+    gate.setAgentStreamEventSuppressed("turn_canceled", true);
+    await page.getByRole("button", { name: "Send queued message now" }).click();
+    const promptRow = page.getByTestId("user-message").filter({ hasText: prompt });
+    const replacementAnswer = page.getByText("(end of synthetic stream)", { exact: true }).last();
+    await expect(promptRow).toBeVisible();
+    await expect(replacementAnswer).toBeVisible({ timeout: 30_000 });
+    await expectRenderedBefore(promptRow, replacementAnswer);
+  } finally {
+    gate.setAssistantMessageIdsStripped(false);
+    gate.setAgentStreamEventSuppressed("turn_canceled", false);
+    await agent.cleanup();
+  }
+}
+
+async function expectStaleCanonicalPagePreservesNewerLiveOutput(
+  page: Page,
+  testInfo: { workerIndex: number },
+): Promise<void> {
+  const gate = await installDaemonWebSocketGate(page);
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: `submission-stale-canonical-${testInfo.workerIndex}-`,
+    title: "Stale canonical page race",
+    model: "one-minute-stream",
+  });
+  try {
+    await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+    await expectComposerVisible(page);
+    await agent.client.sendAgentMessage(agent.agentId, "End the snapshot at a tool call.");
+    await awaitToolCall(page, "read");
+    await page
+      .getByRole("button", { name: /stop|cancel/i })
+      .first()
+      .click();
+    await expectAgentIdle(page);
+
+    gate.holdNextServerMessage("fetch_agent_timeline_response");
+    gate.requestTimelineTail(agent.agentId);
+    await gate.waitForHeldServerMessage();
+    gate.truncateHeldTimelineAfterLast("tool_call");
+    expect(gate.getHeldTimelineLastItemType()).toBe("tool_call");
+
+    const nextPrompt = "Stream after the stale snapshot.";
+    await agent.client.sendAgentMessage(agent.agentId, nextPrompt);
+    const nextPromptRow = page.getByTestId("user-message").filter({ hasText: nextPrompt });
+    const liveAssistant = nextPromptRow.locator(
+      'xpath=following::*[@data-testid="assistant-message"][1]',
+    );
+    await expect(nextPromptRow).toBeVisible();
+    await expect(liveAssistant).toContainText("Cycle 1");
+    gate.releaseHeldServerMessage();
+    await expect(liveAssistant).toContainText("Cycle 1");
+  } finally {
+    await agent.cleanup();
+  }
+}
+
+async function expectCanonicalOrderWinsAcrossOverlappingClients(
+  page: Page,
+  testInfo: { workerIndex: number },
+): Promise<void> {
+  const gate = await installDaemonWebSocketGate(page);
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: `submission-cross-client-order-${testInfo.workerIndex}-`,
+    title: "Cross-client submission order",
+    model: "ten-second-stream",
+  });
+  const localPrompt = "Send this after the other client turn.";
+  const remotePrompt = "Commit this other client turn first.";
+  try {
+    await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+    await expectComposerVisible(page);
+    await expectAgentIdle(page);
+    gate.holdNextClientRequest("send_agent_message_request");
+    const localRow = await submitMessageWithImage(page, localPrompt);
+    await gate.waitForHeldClientRequest();
+
+    await agent.client.sendAgentMessage(agent.agentId, remotePrompt);
+    await agent.client.waitForFinish(agent.agentId, 30_000);
+    const remoteRow = page.getByTestId("user-message").filter({ hasText: remotePrompt });
+    await expect(remoteRow).toBeVisible();
+
+    const userMessageCount = gate.getAgentStreamItemCount("user_message");
+    gate.releaseHeldClientRequest();
+    await gate.waitForAgentStreamItem("user_message", userMessageCount + 1);
+    await expect(localRow).toHaveAttribute("aria-busy", "false");
+    await expect(localRow.getByRole("button", { name: "Open image attachment" })).toBeVisible();
+    await expect
+      .poll(async () => {
+        const localElement = await localRow.elementHandle();
+        if (!localElement) return false;
+        return remoteRow.evaluate(
+          (remoteElement, localNode) =>
+            Boolean(
+              remoteElement.compareDocumentPosition(localNode) & Node.DOCUMENT_POSITION_FOLLOWING,
+            ),
+          localElement,
+        );
+      })
+      .toBe(true);
+  } finally {
+    gate.restore();
+    await agent.cleanup();
+  }
+}
+
+async function expectRenderedBefore(first: Locator, second: Locator): Promise<void> {
+  const secondElement = await second.elementHandle();
+  if (!secondElement) throw new Error("Expected the second timeline item to be rendered");
+  expect(
+    await first.evaluate(
+      (firstElement, secondNode) =>
+        Boolean(
+          firstElement.compareDocumentPosition(secondNode) & Node.DOCUMENT_POSITION_FOLLOWING,
+        ),
+      secondElement,
+    ),
+  ).toBe(true);
+}
+
+async function openWorkspaceDraft(page: Page, workspaceId: string): Promise<void> {
+  await page.goto(buildHostWorkspaceRoute(getServerId(), workspaceId));
+  await waitForWorkspaceTabsVisible(page);
+  await page.getByTestId("workspace-new-agent-tab-inline").click();
+  await expectComposerVisible(page);
+}
+
+async function expectCreatedAgentHandoff(
+  page: Page,
+  prompt: string,
+  userMessage: Locator,
+): Promise<void> {
+  await expect(page.getByTestId("turn-working-indicator")).toBeVisible();
+  await expect(page.getByTestId(/^workspace-tab-agent_/).first()).toBeVisible({ timeout: 30_000 });
+  await expect(userMessage).toHaveAttribute("aria-busy", "false", { timeout: 30_000 });
+  await expect(page.getByTestId("turn-working-indicator")).toBeVisible();
+  await expect(page.getByTestId("user-message").filter({ hasText: prompt })).toHaveCount(1);
+  await expect(userMessage.getByRole("button", { name: "Open image attachment" })).toBeVisible();
+}
+
+interface DraftCreatePendingSubmission {
+  prompt: string;
+  userMessage: Locator;
+}
+
+async function beginDraftCreateSubmission(
+  page: Page,
+  scenario: DraftCreateScenario,
+): Promise<DraftCreatePendingSubmission> {
+  await openWorkspaceDraft(page, scenario.workspaceId);
+  await selectModel(page, "one-minute-stream");
+  const prompt = "Keep this row through create handoff.";
+  const userMessage = await submitMessageWithImage(page, prompt);
+  await scenario.agentCreatedDelay.waitForCreateRequest();
+  await scenario.agentCreatedDelay.waitForDelayedCreatedStatus();
+  await expectPendingSubmission(page, userMessage);
+  return { prompt, userMessage };
+}
+
+async function completeDraftCreateSubmission(
+  page: Page,
+  scenario: DraftCreateScenario,
+  pending: DraftCreatePendingSubmission,
+): Promise<void> {
+  scenario.agentCreatedDelay.release();
+  await expectCreatedAgentHandoff(page, pending.prompt, pending.userMessage);
+}
+
+test.describe("Agent message submission", () => {
+  test("keeps the submitted row stable when the host accepts", async ({
+    page,
+    submissionScenario,
+  }) => {
+    const userMessage = await submitMessageWithImage(page, "Hold this submission.");
+    await expectPendingSubmission(page, userMessage);
+    await submissionScenario.gate.waitForRequest();
+    const submittedGeometry = await readMessageGeometry(page, userMessage);
+    const finishFooterContinuityCheck = await beginWorkingFooterContinuityCheck(page);
+    submissionScenario.gate.accept();
+    await expectAcceptedSubmission(page, userMessage, submittedGeometry);
+    await finishFooterContinuityCheck();
+  });
+
+  test("keeps the submitted row stable through draft create handoff", async ({
+    page,
+    draftCreateScenario,
+  }) => {
+    test.setTimeout(120_000);
+    const pending = await beginDraftCreateSubmission(page, draftCreateScenario);
+    await completeDraftCreateSubmission(page, draftCreateScenario, pending);
+  });
+
+  test("restores a rejected submission and accepts its retry", async ({
+    page,
+    rejectionScenario,
+  }) => {
+    const prompt = "Restore this rejected submission.";
+    await submitMessageThatWillBeRejected(page, prompt);
+    await expectRejectedSubmissionRestored(page, { prompt, ...rejectionScenario });
+    await retryRestoredSubmission(page, prompt);
+  });
+
+  test("restores overlapping queued sends when their connection fails", async ({
+    page,
+  }, testInfo) => {
+    test.setTimeout(120_000);
+    const gate = await gateNextAgentMessage(page);
+    const agent = await startRunningMockAgent(page, {
+      prefix: `overlapping-queued-send-${testInfo.workerIndex}-`,
+      model: "one-minute-stream",
+      prompt: "Keep the agent running while messages queue.",
+    });
+    const prompts = ["Restore the first queued send.", "Restore the second queued send."];
+    try {
+      await queueMessage(page, prompts[0]);
+      await queueMessage(page, prompts[1]);
+      await page.getByRole("button", { name: "Send queued message now" }).first().click();
+      await gate.waitForRequest(1);
+      await page.getByRole("button", { name: "Send queued message now" }).first().click();
+      await gate.waitForRequest(2);
+      await gate.disconnect();
+      await expectQueuedSendFailuresRestored(page, prompts);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("does not accept a failed submission from an unrelated running turn", async ({
+    page,
+    unrelatedRunningScenario,
+  }) => {
+    const prompt = "Restore this unsent prompt.";
+    await submitMessageThatWillBeRejected(page, prompt);
+    await unrelatedRunningScenario.gate.waitForRequest();
+    await unrelatedRunningScenario.agent.client.sendAgentMessage(
+      unrelatedRunningScenario.agent.agentId,
+      "Start an unrelated turn.",
+    );
+    await expect(
+      page.getByTestId("user-message").filter({ hasText: "Start an unrelated turn." }),
+    ).toBeVisible();
+    await unrelatedRunningScenario.gate.disconnect();
+    await expectFailedSubmissionRestored(page, prompt);
+  });
+
+  test("keeps a submitted prompt before its response when canonical history arrives", async ({
+    page,
+  }, testInfo) => {
+    test.setTimeout(90_000);
+    await expectInterruptedTurnOrderAfterReconnect(page, testInfo);
+  });
+
+  test("clears an attachment-only submission when canonical history arrives after a missed running transition", async ({
+    page,
+  }, testInfo) => {
+    test.setTimeout(90_000);
+    await expectCompletedSubmissionClearsAfterMissedRunningTransition(page, testInfo);
+  });
+
+  test("clears a provider acknowledgement that arrives before RPC acceptance", async ({
+    page,
+  }, testInfo) => {
+    test.setTimeout(90_000);
+    await expectProviderAcknowledgementBeforeRpcAcceptanceSettlesSubmission(page, testInfo);
+  });
+
+  test("keeps an old-daemon replacement answer after its interrupted prompt", async ({
+    page,
+  }, testInfo) => {
+    test.setTimeout(90_000);
+    await expectLegacyAssistantStartsAfterInterruptedPrompt(page, testInfo);
+  });
+
+  test("preserves newer live output when a stale canonical page arrives", async ({
+    page,
+  }, testInfo) => {
+    test.setTimeout(90_000);
+    await expectStaleCanonicalPagePreservesNewerLiveOutput(page, testInfo);
+  });
+
+  test("uses canonical order when another client turn overtakes a held submission", async ({
+    page,
+  }, testInfo) => {
+    await expectCanonicalOrderWinsAcrossOverlappingClients(page, testInfo);
+  });
+});

packages/app/e2e/agent-tab-image-stability.spec.ts

@@ -0,0 +1,85 @@
+import { test as base } from "./fixtures";
+import {
+  appendSettledTimelineTurns,
+  createNearTenMegabyteAssistantPng,
+  createSettledMockAgent,
+  createSmallAssistantPng,
+  emitSettledAssistantImage,
+  expectAssistantImageNotMounted,
+  expectAssistantImageRendered,
+  openAssistantImageTimeline,
+  openExistingImageAgentTabs,
+  remountAndRecoverAssistantImageFromHistory,
+  sendFollowUpAndExpectVisibleResponse,
+  switchAwayAndBackWithoutImageInstability,
+  userPagesUntilAssistantImageRenders,
+} from "./helpers/assistant-images";
+import { seedWorkspace, type SeededWorkspace } from "./helpers/seed-client";
+
+const test = base.extend<{ imageWorkspace: SeededWorkspace }>({
+  imageWorkspace: async ({ page: _page }, provide) => {
+    const workspace = await seedWorkspace({ repoPrefix: "agent-tab-image-stability-" });
+    try {
+      await provide(workspace);
+    } finally {
+      await workspace.cleanup();
+    }
+  },
+});
+
+test("switching between settled agent tabs keeps a real assistant PNG rendered", async ({
+  imageWorkspace: workspace,
+  page,
+}) => {
+  test.setTimeout(120_000);
+  const image = await createSmallAssistantPng(workspace, {
+    alt: "Real file image",
+    fileName: "assistant-preview.png",
+  });
+  const imageAgent = await createSettledMockAgent(workspace, "Image timeline");
+  const otherAgent = await createSettledMockAgent(workspace, "Other timeline");
+  await emitSettledAssistantImage(workspace.client, imageAgent, image);
+
+  await openExistingImageAgentTabs(page, { imageAgent, otherAgent });
+  await expectAssistantImageRendered(page, image);
+  await switchAwayAndBackWithoutImageInstability(page, { image, imageAgent, otherAgent });
+});
+
+test("a real assistant PNG remains reachable through pagination and remount", async ({
+  imageWorkspace: workspace,
+  page,
+}) => {
+  test.setTimeout(120_000);
+  const image = await createSmallAssistantPng(workspace, {
+    alt: "Paginated real file image",
+    fileName: "paginated-assistant-preview.png",
+  });
+  const imageAgent = await createSettledMockAgent(workspace, "Paginated image timeline");
+  await emitSettledAssistantImage(workspace.client, imageAgent, image);
+  await appendSettledTimelineTurns(workspace.client, imageAgent, 40);
+
+  await openAssistantImageTimeline(page, imageAgent);
+  await expectAssistantImageNotMounted(page, image);
+  await userPagesUntilAssistantImageRenders(page, image);
+  await remountAndRecoverAssistantImageFromHistory(page, image);
+});
+
+test("a near-10 MiB real assistant PNG renders and the app remains responsive", async ({
+  imageWorkspace: workspace,
+  page,
+}) => {
+  test.setTimeout(180_000);
+  const image = await createNearTenMegabyteAssistantPng(workspace, {
+    alt: "Large real file image",
+    fileName: "large-assistant-preview.png",
+  });
+  const imageAgent = await createSettledMockAgent(workspace, "Large image timeline");
+  await emitSettledAssistantImage(workspace.client, imageAgent, image);
+
+  await openAssistantImageTimeline(page, imageAgent);
+  await expectAssistantImageRendered(page, image);
+  await sendFollowUpAndExpectVisibleResponse(page, {
+    prompt: "confirm responsiveness: emit 1 coalesced agent stream updates",
+    response: "stress-update-0",
+  });
+});

packages/app/e2e/agent-timeline-pagination.spec.ts

@@ -1,28 +1,199 @@
-import { test } from "./fixtures";
+import { expect, test } from "./fixtures";
 import {
+  expectSameOlderHistoryLoadingOperation,
+  expectTimelineAtHistoryStart,
   expectTimelinePromptNotMounted,
+  expectTimelinePromptPositionPreserved,
   expectTimelinePromptVisible,
+  holdBootstrapTimelinePage,
+  holdDaemonHydration,
+  holdOlderHistoryPages,
+  makeLoadedTimelineFitViewport,
   openAgentTimeline,
+  rememberOlderHistoryLoadingOperation,
+  rememberTimelineViewport,
+  rememberTimelinePromptPosition,
+  reloadAgentTimelineFromPersistedReplica,
   scrollTimelineUntilOlderHistoryIsReachable,
+  scrollTimelineToNewestLoadedEdge,
   seedLongMockAgentTimeline,
+  sendLiveTurnBeforeHydration,
+  expectTimelineViewportAnchoredAfterPrepend,
+  userScrollsTimelineToHistoryStart,
 } from "./helpers/timeline-pagination";
 
 test.describe("Agent timeline pagination", () => {
-  test("loads older history when the user scrolls to the top of a long agent timeline", async ({
+  test("loads one page each time the user returns to history start", async ({ page }) => {
+    test.setTimeout(120_000);
+    const agent = await seedLongMockAgentTimeline({ turns: 80 });
+    try {
+      const history = await holdOlderHistoryPages(page, agent);
+      await openAgentTimeline(page, agent);
+      await expectTimelinePromptVisible(page, agent.newestPrompt);
+      await expectTimelinePromptNotMounted(page, agent.oldestPrompt);
+
+      await userScrollsTimelineToHistoryStart(page);
+      await history.expectRequestedPages(1);
+      history.releasePage(1);
+      await history.expectSettledWithRequestedPages(1);
+
+      await userScrollsTimelineToHistoryStart(page);
+      await history.expectRequestedPages(2);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("keeps the visible timeline position anchored while prepending a page", async ({ page }) => {
+    test.setTimeout(120_000);
+    const agent = await seedLongMockAgentTimeline({ turns: 80 });
+    try {
+      const history = await holdOlderHistoryPages(page, agent);
+      await openAgentTimeline(page, agent);
+      await userScrollsTimelineToHistoryStart(page);
+      await history.expectRequestedPages(1);
+      const viewport = await rememberTimelineViewport(page);
+
+      history.releasePage(1);
+      await expectTimelineViewportAnchoredAfterPrepend(page, viewport);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("keeps visible history anchored when live output grows during a prepend", async ({
     page,
   }) => {
     test.setTimeout(120_000);
     const agent = await seedLongMockAgentTimeline({ turns: 80 });
     try {
+      const history = await holdOlderHistoryPages(page, agent);
       await openAgentTimeline(page, agent);
-      await expectTimelinePromptVisible(page, agent.newestPrompt);
-      await expectTimelinePromptNotMounted(page, agent.oldestPrompt);
+      await userScrollsTimelineToHistoryStart(page);
+      await history.expectRequestedPages(1);
+      const position = await rememberTimelinePromptPosition(page, agent.initialTailOldestPrompt);
 
-      await scrollTimelineUntilOlderHistoryIsReachable(page);
+      await agent.client.sendAgentMessage(
+        agent.agentId,
+        "timeline live during held older page: emit 20 coalesced agent stream updates",
+      );
+      await agent.client.waitForFinish(agent.agentId, 15_000);
+      history.releasePage(1);
+
+      await expectTimelinePromptPositionPreserved(page, position);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("finishes loading an older page while live output continues", async ({ page }) => {
+    test.setTimeout(120_000);
+    const agent = await seedLongMockAgentTimeline({ turns: 40 });
+    try {
+      const history = await holdOlderHistoryPages(page, agent);
+      await openAgentTimeline(page, agent);
+      await userScrollsTimelineToHistoryStart(page);
+      await history.expectRequestedPages(1);
+
+      await agent.client.sendAgentMessage(agent.agentId, "keep streaming while history settles");
+      await agent.client.waitForAgentUpsert(
+        agent.agentId,
+        (snapshot) => snapshot.status === "running",
+      );
+      history.releasePage(1);
+
+      await expect(page.getByTestId("load-older-history-spinner")).toBeHidden({ timeout: 5_000 });
+      const running = await agent.client.fetchAgents({ scope: "active" });
+      expect(running.entries.find((entry) => entry.agent.id === agent.agentId)?.agent.status).toBe(
+        "running",
+      );
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("keeps the visible timeline anchored when the final page finishes", async ({ page }) => {
+    test.setTimeout(120_000);
+    const agent = await seedLongMockAgentTimeline({ turns: 40 });
+    try {
+      const history = await holdOlderHistoryPages(page, agent);
+      await openAgentTimeline(page, agent);
+      await userScrollsTimelineToHistoryStart(page);
+      await history.expectRequestedPages(1);
+      const position = await rememberTimelinePromptPosition(page, agent.initialTailOldestPrompt);
+
+      history.releasePage(1);
+
+      await expectTimelinePromptPositionPreserved(page, position);
+      await history.expectSettledWithRequestedPages(1);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("continues one loading operation while older pages still leave history start exposed", async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+    const agent = await seedLongMockAgentTimeline({ turns: 80 });
+    try {
+      await makeLoadedTimelineFitViewport(page);
+      const history = await holdOlderHistoryPages(page, agent);
+      await openAgentTimeline(page, agent);
+      await history.expectRequestedPages(1);
+      const loading = await rememberOlderHistoryLoadingOperation(page);
+
+      history.releasePage(1);
+      await history.expectRequestedPages(2);
+      await expectTimelineAtHistoryStart(page);
+      await expectSameOlderHistoryLoadingOperation(page, loading);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("keeps complete loaded history reachable after reload", async ({ page }) => {
+    test.setTimeout(120_000);
+    const agent = await seedLongMockAgentTimeline({ turns: 80 });
+    try {
+      await openAgentTimeline(page, agent);
+      await scrollTimelineUntilOlderHistoryIsReachable(page, agent.oldestPrompt);
+      await expectTimelinePromptVisible(page, agent.oldestPrompt);
+
+      const hydration = await holdDaemonHydration(page);
+      await reloadAgentTimelineFromPersistedReplica(page, agent);
+      hydration.release();
+      await scrollTimelineUntilOlderHistoryIsReachable(page, agent.oldestPrompt);
 
       await expectTimelinePromptVisible(page, agent.oldestPrompt);
     } finally {
       await agent.cleanup();
     }
   });
+
+  test("preserves a live row received before replica hydration", async ({ page }) => {
+    test.setTimeout(120_000);
+    const agent = await seedLongMockAgentTimeline({ turns: 80 });
+    try {
+      await openAgentTimeline(page, agent);
+      await scrollTimelineUntilOlderHistoryIsReachable(page, agent.oldestPrompt);
+
+      const hydration = await holdBootstrapTimelinePage(page, agent);
+      await reloadAgentTimelineFromPersistedReplica(page, agent);
+      await hydration.waitForDelayedResponse();
+      const livePrompt = await sendLiveTurnBeforeHydration(agent);
+      await expectTimelinePromptVisible(page, livePrompt);
+
+      hydration.release();
+      await hydration.waitForDelayedCatchUp();
+      await expectTimelinePromptVisible(page, livePrompt);
+      hydration.releaseCatchUp();
+      await scrollTimelineUntilOlderHistoryIsReachable(page, agent.oldestPrompt);
+      await expectTimelinePromptVisible(page, agent.oldestPrompt);
+      await scrollTimelineToNewestLoadedEdge(page);
+      await expectTimelinePromptVisible(page, livePrompt);
+    } finally {
+      await agent.cleanup();
+    }
+  });
 });

packages/app/e2e/command-center-workspaces.spec.ts

@@ -55,9 +55,15 @@ test.describe("Command center workspaces", () => {
       );
       await expect(row).toBeVisible({ timeout: 30_000 });
       await expect(row).toContainText(WORKSPACE_TITLE);
-      await expect(row).toContainText(PRIMARY_HOST_LABEL);
       await expect(row).toContainText(WORKSPACE_BRANCH);
 
+      // The subtitle disambiguates by project: host · project · branch (multi-host).
+      const subtitle = row.getByTestId("command-center-workspace-subtitle");
+      await expect(subtitle).toContainText(PRIMARY_HOST_LABEL);
+      await expect(subtitle).toContainText(seeded.projectDisplayName);
+      await expect(subtitle).toContainText(WORKSPACE_BRANCH);
+
+      // The agent subtitle is unchanged by the shared-helper refactor.
       const agentRow = panel.getByTestId(`command-center-agent-${getServerId()}:${agent.id}`);
       await expect(agentRow).toContainText(AGENT_TITLE);
       await expect(agentRow).toContainText(PRIMARY_HOST_LABEL);
@@ -89,6 +95,10 @@ test.describe("Command center workspaces", () => {
       await expect(agentRow).toBeVisible();
       await expect(row).not.toBeVisible();
 
+      // The project name is now part of the workspace searchText.
+      await input.fill(seeded.projectDisplayName);
+      await expect(row).toBeVisible();
+
       await input.fill(AGENT_TITLE);
       await expect(agentRow).toBeVisible();
       await expect(row).not.toBeVisible();
@@ -103,4 +113,38 @@ test.describe("Command center workspaces", () => {
       await seeded.cleanup();
     }
   });
+
+  test("single-host workspace subtitle omits the host and shows project · branch", async ({
+    page,
+  }) => {
+    const seeded = await seedWorkspace({
+      repoPrefix: "command-center-workspace-single-",
+      title: WORKSPACE_TITLE,
+    });
+
+    try {
+      execFileSync("git", ["checkout", "-b", WORKSPACE_BRANCH], {
+        cwd: seeded.repoPath,
+        stdio: "ignore",
+      });
+      const refreshed = await seeded.client.checkoutRefresh(seeded.repoPath);
+      if (!refreshed.success) {
+        throw new Error(`Failed to refresh checkout: ${JSON.stringify(refreshed.error)}`);
+      }
+
+      // No secondary host: with a single host, the host label is gated away.
+      await gotoAppShell(page);
+
+      const panel = await openCommandCenter(page);
+      const row = panel.getByTestId(
+        `command-center-workspace-${getServerId()}:${seeded.workspaceId}`,
+      );
+      await expect(row).toBeVisible({ timeout: 30_000 });
+
+      const subtitle = row.getByTestId("command-center-workspace-subtitle");
+      await expect(subtitle).toHaveText(`${seeded.projectDisplayName} · ${WORKSPACE_BRANCH}`);
+    } finally {
+      await seeded.cleanup();
+    }
+  });
 });

packages/app/e2e/file-editing.spec.ts

@@ -18,6 +18,14 @@ function editor(page: Page) {
   return page.getByTestId("file-source-editor").filter({ visible: true }).locator(".cm-content");
 }
 
+function hasHorizontalOverflow(element: HTMLElement): boolean {
+  return element.scrollWidth > element.clientWidth;
+}
+
+function fitsViewportWidth(element: HTMLElement): boolean {
+  return element.scrollWidth === element.clientWidth;
+}
+
 async function replaceEditorText(page: Page, content: string): Promise<void> {
   const contentElement = editor(page);
   await contentElement.click();
@@ -95,6 +103,34 @@ test.describe("CodeMirror workspace file editing", () => {
     }
   });
 
+  test("clicking the editor focuses its pane beside an agent", async ({ page }) => {
+    const target = "target.ts:42";
+    const session = await seedAgentWithFileLink(target);
+
+    try {
+      await page.setViewportSize({ width: 1280, height: 900 });
+      await openAgentRoute(page, session);
+
+      await page.getByRole("button", { name: "Split pane right" }).first().click();
+      await expect(page.getByTestId("workspace-tabs-row").filter({ visible: true })).toHaveCount(2);
+      await openWorkspaceFile(page, "target.ts");
+
+      await page
+        .getByTestId(`workspace-tab-agent_${session.agentId}`)
+        .filter({ visible: true })
+        .click();
+      await editor(page).click();
+      await page.keyboard.press("Alt+Shift+W");
+
+      await expect(page.getByTestId("workspace-tab-file_target.ts")).not.toBeVisible();
+      await expect(
+        page.getByTestId(`workspace-tab-agent_${session.agentId}`).filter({ visible: true }),
+      ).toBeVisible();
+    } finally {
+      await session.cleanup();
+    }
+  });
+
   test("shows the full file path and keeps editor controls stable", async ({
     page,
     withWorkspace,
@@ -174,6 +210,36 @@ test.describe("CodeMirror workspace file editing", () => {
     ).toHaveCSS("font-family", "monospace");
   });
 
+  test("wraps Markdown while source code remains horizontally scrollable", async ({
+    page,
+    withWorkspace,
+  }) => {
+    const workspace = await withWorkspace({ prefix: "file-editing-wrap-" });
+    const longLine = "word ".repeat(300);
+    await writeFile(path.join(workspace.repoPath, "notes.md"), `${longLine}\n`, "utf8");
+    await writeFile(
+      path.join(workspace.repoPath, "source.ts"),
+      `const value = "${longLine}";\n`,
+      "utf8",
+    );
+    await workspace.navigateTo();
+    await openWorkspaceFile(page, "notes.md");
+    await page.getByTestId("file-mode-source").click();
+
+    const markdownScroller = page
+      .getByTestId("file-source-editor")
+      .filter({ visible: true })
+      .locator(".cm-scroller");
+    await expect.poll(() => markdownScroller.evaluate(fitsViewportWidth)).toBe(true);
+
+    await openWorkspaceFile(page, "source.ts");
+    const sourceScroller = page
+      .getByTestId("file-source-editor")
+      .filter({ visible: true })
+      .locator(".cm-scroller");
+    await expect.poll(() => sourceScroller.evaluate(hasHorizontalOverflow)).toBe(true);
+  });
+
   test("autosaves, saves immediately, resolves conflicts, and restores live updates after reconnect", async ({
     page,
     withWorkspace,

packages/app/e2e/helpers/agent-message-gate.ts

@@ -0,0 +1,86 @@
+import type { Page, WebSocketRoute } from "@playwright/test";
+import { daemonWsRoutePattern } from "./daemon-port";
+
+type WebSocketMessage = string | Buffer;
+
+interface SendAgentMessageRequest {
+  type: "send_agent_message_request";
+  requestId: string;
+  agentId: string;
+}
+
+function readSendRequest(message: WebSocketMessage): SendAgentMessageRequest | null {
+  if (typeof message !== "string") return null;
+  try {
+    const envelope = JSON.parse(message) as {
+      type?: unknown;
+      message?: Record<string, unknown>;
+    };
+    const request = envelope.type === "session" ? envelope.message : null;
+    if (
+      request?.type !== "send_agent_message_request" ||
+      typeof request.requestId !== "string" ||
+      typeof request.agentId !== "string"
+    ) {
+      return null;
+    }
+    return {
+      type: "send_agent_message_request",
+      requestId: request.requestId,
+      agentId: request.agentId,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function gateNextAgentMessage(page: Page) {
+  let serverSocket: WebSocketRoute | null = null;
+  let browserSocket: WebSocketRoute | null = null;
+  const heldMessages: Array<WebSocketMessage | null> = [];
+  const requests: SendAgentMessageRequest[] = [];
+  const requestWaiters = new Set<() => void>();
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    browserSocket = ws;
+    const server = ws.connectToServer();
+    serverSocket = server;
+
+    ws.onMessage((message) => {
+      const request = readSendRequest(message);
+      if (request) {
+        heldMessages.push(message);
+        requests.push(request);
+        for (const resolve of requestWaiters) resolve();
+        requestWaiters.clear();
+        return;
+      }
+      server.send(message);
+    });
+
+    server.onMessage((message) => ws.send(message));
+  });
+
+  const waitForRequest = async (count = 1): Promise<SendAgentMessageRequest> => {
+    while (requests.length < count) {
+      await new Promise<void>((resolve) => requestWaiters.add(resolve));
+    }
+    return requests[count - 1];
+  };
+
+  return {
+    waitForRequest,
+    accept(index = 0) {
+      const heldMessage = heldMessages[index];
+      if (!serverSocket || !heldMessage) {
+        throw new Error("No held send-agent-message request to accept");
+      }
+      serverSocket.send(heldMessage);
+      heldMessages[index] = null;
+    },
+    async disconnect(): Promise<void> {
+      if (!browserSocket) throw new Error("No browser daemon socket to disconnect");
+      await browserSocket.close({ code: 1008, reason: "Dropped by submission test." });
+    },
+  };
+}

packages/app/e2e/helpers/agent-timeline-gate.ts

@@ -10,6 +10,26 @@ interface CreatedAgentTimelineGate {
   waitForForwardedResponse(): Promise<void>;
 }
 
+export interface AgentTimelineResponseGate {
+  release(): void;
+  waitForDelayedResponse(): Promise<void>;
+}
+
+export interface OlderTimelinePagesGate {
+  getRequestCount(): number;
+  releasePage(pageNumber: number): void;
+  waitForRequestCount(count: number): Promise<void>;
+}
+
+export interface DaemonHydrationGate {
+  release(): void;
+}
+
+export interface BootstrapTimelineGate extends AgentTimelineResponseGate {
+  releaseCatchUp(): void;
+  waitForDelayedCatchUp(): Promise<void>;
+}
+
 function parseWebSocketJson(message: WebSocketMessage): unknown {
   const rawMessage = typeof message === "string" ? message : message.toString("utf8");
   try {
@@ -40,6 +60,32 @@ function getPayload(message: Record<string, unknown>): Record<string, unknown> |
     : null;
 }
 
+export async function holdDaemonHydration(page: Page): Promise<DaemonHydrationGate> {
+  let released = false;
+  const delayedForwards: Array<() => void> = [];
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+    ws.onMessage((message) => server.send(message));
+    server.onMessage((message) => {
+      if (released) {
+        ws.send(message);
+        return;
+      }
+      delayedForwards.push(() => ws.send(message));
+    });
+  });
+
+  return {
+    release() {
+      released = true;
+      for (const forward of delayedForwards.splice(0)) {
+        forward();
+      }
+    },
+  };
+}
+
 export async function delayCreatedAgentInitialTailResponse(
   page: Page,
 ): Promise<CreatedAgentTimelineGate> {
@@ -118,3 +164,189 @@ export async function delayCreatedAgentInitialTailResponse(
     waitForForwardedResponse: () => forwardedResponse,
   };
 }
+
+export async function delayAgentOlderTimelineResponse(
+  page: Page,
+  agentId: string,
+): Promise<AgentTimelineResponseGate> {
+  return delayAgentTimelineResponse(page, agentId, "before");
+}
+
+export async function holdAgentOlderTimelinePages(
+  page: Page,
+  agentId: string,
+): Promise<OlderTimelinePagesGate> {
+  let requestCount = 0;
+  let responseCount = 0;
+  const releasedPages = new Set<number>();
+  const delayedForwards = new Map<number, Array<() => void>>();
+  const requestWaiters = new Map<number, Array<() => void>>();
+
+  const resolveRequestWaiters = () => {
+    for (const [count, resolvers] of requestWaiters) {
+      if (requestCount < count) continue;
+      requestWaiters.delete(count);
+      for (const resolve of resolvers) resolve();
+    }
+  };
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+    ws.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      if (
+        sessionMessage?.type === "fetch_agent_timeline_request" &&
+        sessionMessage.agentId === agentId &&
+        sessionMessage.direction === "before"
+      ) {
+        requestCount += 1;
+        resolveRequestWaiters();
+      }
+      server.send(message);
+    });
+    server.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      const payload = sessionMessage ? getPayload(sessionMessage) : null;
+      if (
+        sessionMessage?.type === "fetch_agent_timeline_response" &&
+        payload?.agentId === agentId &&
+        payload.direction === "before"
+      ) {
+        responseCount += 1;
+        const pageNumber = responseCount;
+        if (releasedPages.has(pageNumber)) {
+          ws.send(message);
+          return;
+        }
+        const forwards = delayedForwards.get(pageNumber) ?? [];
+        forwards.push(() => ws.send(message));
+        delayedForwards.set(pageNumber, forwards);
+        return;
+      }
+      ws.send(message);
+    });
+  });
+
+  return {
+    getRequestCount: () => requestCount,
+    releasePage(pageNumber) {
+      releasedPages.add(pageNumber);
+      for (const forward of delayedForwards.get(pageNumber) ?? []) forward();
+      delayedForwards.delete(pageNumber);
+    },
+    waitForRequestCount(count) {
+      if (requestCount >= count) return Promise.resolve();
+      return new Promise<void>((resolve) => {
+        const resolvers = requestWaiters.get(count) ?? [];
+        resolvers.push(resolve);
+        requestWaiters.set(count, resolvers);
+      });
+    },
+  };
+}
+
+export async function delayAgentBootstrapTailResponse(
+  page: Page,
+  agentId: string,
+): Promise<BootstrapTimelineGate> {
+  let tailReleased = false;
+  let catchUpReleased = false;
+  const delayedTailForwards: Array<() => void> = [];
+  const delayedCatchUpForwards: Array<() => void> = [];
+  let resolveDelayedTail: (() => void) | null = null;
+  let resolveDelayedCatchUp: (() => void) | null = null;
+  const delayedTail = new Promise<void>((resolve) => {
+    resolveDelayedTail = resolve;
+  });
+  const delayedCatchUp = new Promise<void>((resolve) => {
+    resolveDelayedCatchUp = resolve;
+  });
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+    ws.onMessage((message) => server.send(message));
+    server.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      const payload = sessionMessage ? getPayload(sessionMessage) : null;
+      const isTimelineResponse =
+        sessionMessage?.type === "fetch_agent_timeline_response" && payload?.agentId === agentId;
+      if (isTimelineResponse && payload.direction === "tail") {
+        resolveDelayedTail?.();
+        if (tailReleased) ws.send(message);
+        else delayedTailForwards.push(() => ws.send(message));
+        return;
+      }
+      if (isTimelineResponse && payload.direction === "after") {
+        resolveDelayedCatchUp?.();
+        if (catchUpReleased) ws.send(message);
+        else delayedCatchUpForwards.push(() => ws.send(message));
+        return;
+      }
+      ws.send(message);
+    });
+  });
+
+  return {
+    release() {
+      tailReleased = true;
+      for (const forward of delayedTailForwards.splice(0)) forward();
+    },
+    releaseCatchUp() {
+      catchUpReleased = true;
+      for (const forward of delayedCatchUpForwards.splice(0)) forward();
+    },
+    waitForDelayedResponse: () => delayedTail,
+    waitForDelayedCatchUp: () => delayedCatchUp,
+  };
+}
+
+async function delayAgentTimelineResponse(
+  page: Page,
+  agentId: string,
+  direction: "before" | "tail",
+): Promise<AgentTimelineResponseGate> {
+  let releaseRequested = false;
+  let delayedResponseSeen = false;
+  const delayedForwards: Array<() => void> = [];
+  let resolveDelayedResponse: (() => void) | null = null;
+  const delayedResponse = new Promise<void>((resolve) => {
+    resolveDelayedResponse = resolve;
+  });
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+    ws.onMessage((message) => {
+      server.send(message);
+    });
+    server.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      const payload = sessionMessage ? getPayload(sessionMessage) : null;
+      if (
+        !delayedResponseSeen &&
+        sessionMessage?.type === "fetch_agent_timeline_response" &&
+        payload?.agentId === agentId &&
+        payload.direction === direction
+      ) {
+        delayedResponseSeen = true;
+        resolveDelayedResponse?.();
+        if (releaseRequested) {
+          ws.send(message);
+          return;
+        }
+        delayedForwards.push(() => ws.send(message));
+        return;
+      }
+      ws.send(message);
+    });
+  });
+
+  return {
+    release() {
+      releaseRequested = true;
+      for (const forward of delayedForwards.splice(0)) {
+        forward();
+      }
+    },
+    waitForDelayedResponse: () => delayedResponse,
+  };
+}

packages/app/e2e/helpers/assistant-images.ts

@@ -0,0 +1,343 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { deflateSync } from "node:zlib";
+import { expect, type Page } from "@playwright/test";
+import type { ArchiveTabAgent } from "./archive-tab";
+import { openWorkspaceWithAgents } from "./archive-tab";
+import { submitMessage } from "./composer";
+import type { SeedDaemonClient, SeededWorkspace } from "./seed-client";
+import { openAgentRoute } from "./mock-agent";
+import { rememberTimelineViewport, userScrollsTimelineToHistoryStart } from "./timeline-pagination";
+
+const IMAGE_PREVIEW_ERROR = "Unable to load image preview.";
+const SMALL_PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==",
+  "base64",
+);
+const TEN_MEBIBYTES = 10 * 1024 * 1024;
+
+export interface AssistantImageFixture {
+  alt: string;
+  height: number;
+  relativePath: string;
+  size: number;
+  width: number;
+}
+
+export async function createSmallAssistantPng(
+  workspace: SeededWorkspace,
+  input: { alt: string; fileName: string },
+): Promise<AssistantImageFixture> {
+  await writeFile(path.join(workspace.repoPath, input.fileName), SMALL_PNG);
+  return {
+    alt: input.alt,
+    height: 1,
+    relativePath: input.fileName,
+    size: SMALL_PNG.byteLength,
+    width: 1,
+  };
+}
+
+export async function createNearTenMegabyteAssistantPng(
+  workspace: SeededWorkspace,
+  input: { alt: string; fileName: string },
+): Promise<AssistantImageFixture> {
+  const width = 2_048;
+  const height = 1_280;
+  const bytes = encodeDeterministicPng(width, height);
+  if (bytes.byteLength < TEN_MEBIBYTES * 0.95 || bytes.byteLength > TEN_MEBIBYTES * 1.05) {
+    throw new Error(`Expected a PNG near 10 MiB, encoded ${bytes.byteLength} bytes`);
+  }
+  await writeFile(path.join(workspace.repoPath, input.fileName), bytes);
+  return {
+    alt: input.alt,
+    height,
+    relativePath: input.fileName,
+    size: bytes.byteLength,
+    width,
+  };
+}
+
+export async function createSettledMockAgent(
+  workspace: SeededWorkspace,
+  title: string,
+): Promise<ArchiveTabAgent> {
+  const agent = await workspace.client.createAgent({
+    provider: "mock",
+    model: "ten-second-stream",
+    modeId: "load-test",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title,
+  });
+  await workspace.client.waitForAgentUpsert(
+    agent.id,
+    (snapshot) => snapshot.status === "idle",
+    30_000,
+  );
+  return {
+    id: agent.id,
+    title,
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+  };
+}
+
+export async function emitSettledAssistantImage(
+  client: SeedDaemonClient,
+  agent: ArchiveTabAgent,
+  image: AssistantImageFixture,
+): Promise<void> {
+  await client.sendAgentMessage(
+    agent.id,
+    `Emit settled assistant image Markdown: ![${image.alt}](${image.relativePath})`,
+  );
+  const result = await client.waitForFinish(agent.id, 30_000);
+  if (result.status !== "idle" || result.final?.lastError) {
+    throw new Error(
+      `Assistant image agent did not settle: ${result.final?.lastError ?? result.status}`,
+    );
+  }
+}
+
+export async function appendSettledTimelineTurns(
+  client: SeedDaemonClient,
+  agent: ArchiveTabAgent,
+  count: number,
+): Promise<void> {
+  for (let index = 0; index < count; index += 1) {
+    await client.sendAgentMessage(
+      agent.id,
+      `image-history-turn-${index}: emit 1 coalesced agent stream updates`,
+    );
+    const result = await client.waitForFinish(agent.id, 30_000);
+    if (result.status !== "idle" || result.final?.lastError) {
+      throw new Error(
+        `Assistant image history turn did not settle: ${result.final?.lastError ?? result.status}`,
+      );
+    }
+  }
+}
+
+export async function expectAssistantImageRendered(
+  page: Page,
+  image: AssistantImageFixture,
+): Promise<void> {
+  const rendered = page.getByRole("img", { name: image.alt }).first();
+  await expect(rendered).toBeVisible({ timeout: 30_000 });
+  await expect
+    .poll(async () =>
+      rendered.evaluate((element) => {
+        const imageElement =
+          element instanceof HTMLImageElement ? element : element.querySelector("img");
+        return imageElement?.complete
+          ? { height: imageElement.naturalHeight, width: imageElement.naturalWidth }
+          : null;
+      }),
+    )
+    .toEqual({ height: image.height, width: image.width });
+}
+
+export async function switchAwayAndBackWithoutImageInstability(
+  page: Page,
+  input: {
+    image: AssistantImageFixture;
+    imageAgent: ArchiveTabAgent;
+    otherAgent: ArchiveTabAgent;
+  },
+): Promise<void> {
+  await beginVisibleImageStabilityObservation(page, input.image.alt, input.imageAgent.id);
+  await selectSettledAgentTab(page, input.otherAgent);
+  await selectSettledAgentTab(page, input.imageAgent);
+  await expectAssistantImageRendered(page, input.image);
+  await expectNoVisibleImageInstability(page);
+}
+
+export async function openExistingImageAgentTabs(
+  page: Page,
+  input: { imageAgent: ArchiveTabAgent; otherAgent: ArchiveTabAgent },
+): Promise<void> {
+  await openWorkspaceWithAgents(page, [input.otherAgent, input.imageAgent]);
+}
+
+export async function openAssistantImageTimeline(
+  page: Page,
+  agent: ArchiveTabAgent,
+): Promise<void> {
+  await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.id });
+}
+
+export async function expectAssistantImageNotMounted(
+  page: Page,
+  image: AssistantImageFixture,
+): Promise<void> {
+  await expect(page.getByRole("img", { name: image.alt })).toHaveCount(0);
+}
+
+export async function userPagesUntilAssistantImageRenders(
+  page: Page,
+  image: AssistantImageFixture,
+): Promise<void> {
+  const rendered = page.getByRole("img", { name: image.alt });
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    if ((await rendered.count()) > 0) {
+      await expectAssistantImageRendered(page, image);
+      return;
+    }
+    const previous = await rememberTimelineViewport(page);
+    await userScrollsTimelineToHistoryStart(page);
+    await expect
+      .poll(async () => (await rememberTimelineViewport(page)).scrollHeight)
+      .toBeGreaterThan(previous.scrollHeight);
+  }
+  await expectAssistantImageRendered(page, image);
+}
+
+export async function remountAndRecoverAssistantImageFromHistory(
+  page: Page,
+  image: AssistantImageFixture,
+): Promise<void> {
+  await page.reload();
+  await userPagesUntilAssistantImageRenders(page, image);
+}
+
+export async function sendFollowUpAndExpectVisibleResponse(
+  page: Page,
+  input: { prompt: string; response: string },
+): Promise<void> {
+  await submitMessage(page, input.prompt);
+  await expect(page.getByText(input.prompt, { exact: true })).toBeVisible({ timeout: 30_000 });
+  await expect(page.getByText(input.response, { exact: true })).toBeVisible({ timeout: 30_000 });
+}
+
+async function selectSettledAgentTab(page: Page, agent: ArchiveTabAgent): Promise<void> {
+  const tab = page.getByRole("button", { name: agent.title, exact: true });
+  await tab.click();
+  await expect(page).toHaveTitle(agent.title);
+  await expect(tab).toHaveAttribute("aria-selected", "true");
+  await expect(page.locator('[data-testid="agent-chat-scroll"]:visible').first()).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+async function beginVisibleImageStabilityObservation(
+  page: Page,
+  alt: string,
+  imageAgentId: string,
+): Promise<void> {
+  await page.evaluate(
+    ({ accessibleName, errorText, tabTestId }) => {
+      const record = {
+        errorSeen: false,
+        missingSeen: false,
+        inspect: () => undefined,
+        observer: null as MutationObserver | null,
+      };
+      const isVisible = (element: Element) => {
+        const rect = element.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0;
+      };
+      record.inspect = () => {
+        record.errorSeen ||= Array.from(document.querySelectorAll("*")).some(
+          (element) =>
+            element.children.length === 0 &&
+            element.textContent?.trim() === errorText &&
+            isVisible(element),
+        );
+        const imageTab = document.querySelector(`[data-testid="${tabTestId}"]`);
+        if (imageTab?.getAttribute("aria-selected") !== "true") return;
+        const imageVisible = Array.from(document.querySelectorAll('[role="img"]')).some(
+          (element) => element.getAttribute("aria-label") === accessibleName && isVisible(element),
+        );
+        record.missingSeen ||= !imageVisible;
+      };
+      record.observer = new MutationObserver(record.inspect);
+      record.observer.observe(document.body, {
+        attributes: true,
+        childList: true,
+        subtree: true,
+        characterData: true,
+      });
+      record.inspect();
+      (
+        window as unknown as {
+          __paseoAssistantImageObservation?: typeof record;
+        }
+      ).__paseoAssistantImageObservation = record;
+    },
+    {
+      accessibleName: alt,
+      errorText: IMAGE_PREVIEW_ERROR,
+      tabTestId: `workspace-tab-agent_${imageAgentId}`,
+    },
+  );
+}
+
+async function expectNoVisibleImageInstability(page: Page): Promise<void> {
+  const observation = await page.evaluate(() => {
+    const owner = window as unknown as {
+      __paseoAssistantImageObservation?: {
+        errorSeen: boolean;
+        missingSeen: boolean;
+        inspect(): void;
+        observer: MutationObserver | null;
+      };
+    };
+    const record = owner.__paseoAssistantImageObservation;
+    if (!record) throw new Error("Assistant image stability observation was not started");
+    record.inspect();
+    record.observer?.disconnect();
+    delete owner.__paseoAssistantImageObservation;
+    return { errorSeen: record.errorSeen, missingSeen: record.missingSeen };
+  });
+  expect(observation).toEqual({ errorSeen: false, missingSeen: false });
+}
+
+function encodeDeterministicPng(width: number, height: number): Buffer {
+  const stride = width * 4 + 1;
+  const scanlines = Buffer.allocUnsafe(stride * height);
+  let state = 0x9e3779b9;
+  for (let row = 0; row < height; row += 1) {
+    const rowOffset = row * stride;
+    scanlines[rowOffset] = 0;
+    for (let offset = 1; offset < stride; offset += 1) {
+      state ^= state << 13;
+      state ^= state >>> 17;
+      state ^= state << 5;
+      scanlines[rowOffset + offset] = state & 0xff;
+    }
+  }
+
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width, 0);
+  header.writeUInt32BE(height, 4);
+  header[8] = 8;
+  header[9] = 6;
+  return Buffer.concat([
+    Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    pngChunk("IHDR", header),
+    pngChunk("IDAT", deflateSync(scanlines, { level: 0 })),
+    pngChunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+function pngChunk(type: string, data: Buffer): Buffer {
+  const typeBytes = Buffer.from(type, "ascii");
+  const chunk = Buffer.allocUnsafe(12 + data.byteLength);
+  chunk.writeUInt32BE(data.byteLength, 0);
+  typeBytes.copy(chunk, 4);
+  data.copy(chunk, 8);
+  chunk.writeUInt32BE(crc32(Buffer.concat([typeBytes, data])), 8 + data.byteLength);
+  return chunk;
+}
+
+function crc32(bytes: Buffer): number {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit += 1) {
+      crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}

packages/app/e2e/helpers/daemon-websocket-gate.ts

@@ -16,6 +16,20 @@ interface ClientRequest {
   type?: unknown;
   subscribe?: unknown;
   page?: { cursor?: unknown };
+  payload?: unknown;
+}
+
+function readSessionMessage(message: string | Buffer): ClientRequest | null {
+  if (typeof message !== "string") return null;
+  try {
+    const envelope = JSON.parse(message) as {
+      type?: unknown;
+      message?: ClientRequest;
+    };
+    return envelope.message ?? envelope;
+  } catch {
+    return null;
+  }
 }
 
 function readClientRequest(message: string | Buffer): ClientRequest | null {
@@ -38,15 +52,111 @@ function directoryForRequest(request: ClientRequest): keyof DirectoryBootstrapCo
   return null;
 }
 
+function stripAssistantMessageId(
+  message: string | Buffer,
+  enabled: boolean,
+  messageType: unknown,
+): string | Buffer {
+  if (!enabled || messageType !== "agent_stream" || typeof message !== "string") return message;
+  const envelope = JSON.parse(message) as {
+    message?: { payload?: { event?: { type?: unknown; item?: Record<string, unknown> } } };
+    payload?: { event?: { type?: unknown; item?: Record<string, unknown> } };
+  };
+  const event = (envelope.message?.payload ?? envelope.payload)?.event;
+  if (event?.type !== "timeline" || event.item?.type !== "assistant_message") return message;
+  delete event.item.messageId;
+  return JSON.stringify(envelope);
+}
+
+function stripMessageSubmissionDisposition(
+  message: string | Buffer,
+  enabled: boolean,
+  messageType: unknown,
+): string | Buffer {
+  if (!enabled || messageType !== "send_agent_message_response" || typeof message !== "string") {
+    return message;
+  }
+  const envelope = JSON.parse(message) as {
+    message?: { payload?: Record<string, unknown> };
+    payload?: Record<string, unknown>;
+  };
+  const payload = envelope.message?.payload ?? envelope.payload;
+  if (!payload) return message;
+  delete payload.outOfBand;
+  return JSON.stringify(envelope);
+}
+
+function forceTimelineReset(message: string | Buffer, enabled: boolean): string | Buffer {
+  if (!enabled || typeof message !== "string") return message;
+  const envelope = JSON.parse(message) as {
+    message?: { payload?: Record<string, unknown> };
+    payload?: Record<string, unknown>;
+  };
+  const payload = envelope.message?.payload ?? envelope.payload;
+  if (!payload) return message;
+  payload.epoch = `playwright-reset-${Date.now()}`;
+  payload.reset = true;
+  return JSON.stringify(envelope);
+}
+
+function readAgentStreamEventType(message: ClientRequest | null): string | null {
+  if (message?.type !== "agent_stream" || !message.payload || typeof message.payload !== "object") {
+    return null;
+  }
+  const event = (message.payload as { event?: { type?: unknown } }).event;
+  return typeof event?.type === "string" ? event.type : null;
+}
+
+function readAgentStreamItemType(message: ClientRequest | null): string | null {
+  if (message?.type !== "agent_stream" || !message.payload || typeof message.payload !== "object") {
+    return null;
+  }
+  const event = (message.payload as { event?: { type?: unknown; item?: { type?: unknown } } })
+    .event;
+  return event?.type === "timeline" && typeof event.item?.type === "string"
+    ? event.item.type
+    : null;
+}
+
+function shouldSuppressServerMessage(input: {
+  message: ClientRequest | null;
+  messageTypes: ReadonlySet<string>;
+  agentStreamEventTypes: ReadonlySet<string>;
+  suppressAgentStream: boolean;
+}): boolean {
+  const messageType = typeof input.message?.type === "string" ? input.message.type : null;
+  if (messageType && input.messageTypes.has(messageType)) return true;
+  if (input.suppressAgentStream && messageType === "agent_stream") return true;
+  const eventType = readAgentStreamEventType(input.message);
+  return Boolean(eventType && input.agentStreamEventTypes.has(eventType));
+}
+
 export async function installDaemonWebSocketGate(page: Page) {
   let acceptingConnections = true;
+  let reconnectWithFreshClient = false;
+  let suppressAgentStream = false;
+  let forceTimelineEpochReset = false;
+  let stripAssistantMessageIds = false;
+  let stripSubmissionDisposition = false;
+  let heldClientRequestType: string | null = null;
+  let heldClientRequest: { server: WebSocketRoute; message: string | Buffer } | null = null;
+  let resolveHeldClientRequest: (() => void) | null = null;
+  let heldServerMessageType: string | null = null;
+  let heldServerMessage: { browser: WebSocketRoute; message: string | Buffer } | null = null;
+  let resolveHeldServerMessage: (() => void) | null = null;
+  const suppressedServerMessageTypes = new Set<string>();
+  const suppressedAgentStreamEventTypes = new Set<string>();
   const activeSockets = new Set<WebSocketRoute>();
+  let latestServer: WebSocketRoute | null = null;
   const directoryStarts: DirectoryRequestStartCounts = {
     subscribed: { agents: 0, workspaces: 0 },
     unsubscribed: { agents: 0, workspaces: 0 },
     total: { agents: 0, workspaces: 0 },
   };
   const clientRequestCounts = new Map<string, number>();
+  const serverMessageCounts = new Map<string, number>();
+  const agentStreamItemCounts = new Map<string, number>();
+  const serverMessageWaiters = new Set<() => void>();
 
   await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
     if (!acceptingConnections) {
@@ -56,9 +166,20 @@ export async function installDaemonWebSocketGate(page: Page) {
 
     activeSockets.add(ws);
     const server = ws.connectToServer();
+    latestServer = server;
 
     ws.onMessage((message) => {
       if (!acceptingConnections) return;
+      if (reconnectWithFreshClient && typeof message === "string") {
+        const hello = readClientRequest(message);
+        if (hello?.type === "hello") {
+          const parsed = JSON.parse(message) as { clientId?: string };
+          parsed.clientId = `${parsed.clientId ?? "playwright"}-fresh-${Date.now()}`;
+          reconnectWithFreshClient = false;
+          server.send(JSON.stringify(parsed));
+          return;
+        }
+      }
       const request = readClientRequest(message);
       if (typeof request?.type === "string") {
         clientRequestCounts.set(request.type, (clientRequestCounts.get(request.type) ?? 0) + 1);
@@ -69,6 +190,12 @@ export async function installDaemonWebSocketGate(page: Page) {
           directoryStarts.total[directory] += 1;
         }
       }
+      if (request?.type === heldClientRequestType) {
+        heldClientRequest = { server, message };
+        resolveHeldClientRequest?.();
+        resolveHeldClientRequest = null;
+        return;
+      }
       try {
         server.send(message);
       } catch {
@@ -78,8 +205,55 @@ export async function installDaemonWebSocketGate(page: Page) {
 
     server.onMessage((message) => {
       if (!acceptingConnections) return;
+      const serverMessage = readSessionMessage(message);
+      let outboundMessage = stripAssistantMessageId(
+        message,
+        stripAssistantMessageIds,
+        serverMessage?.type,
+      );
+      outboundMessage = stripMessageSubmissionDisposition(
+        outboundMessage,
+        stripSubmissionDisposition,
+        serverMessage?.type,
+      );
+      const shouldForceTimelineReset =
+        forceTimelineEpochReset && serverMessage?.type === "fetch_agent_timeline_response";
+      outboundMessage = forceTimelineReset(outboundMessage, shouldForceTimelineReset);
+      if (shouldForceTimelineReset) forceTimelineEpochReset = false;
+      if (typeof serverMessage?.type === "string") {
+        serverMessageCounts.set(
+          serverMessage.type,
+          (serverMessageCounts.get(serverMessage.type) ?? 0) + 1,
+        );
+        for (const resolve of serverMessageWaiters) resolve();
+        serverMessageWaiters.clear();
+      }
+      const agentStreamItemType = readAgentStreamItemType(serverMessage);
+      if (agentStreamItemType) {
+        agentStreamItemCounts.set(
+          agentStreamItemType,
+          (agentStreamItemCounts.get(agentStreamItemType) ?? 0) + 1,
+        );
+        for (const resolve of serverMessageWaiters) resolve();
+        serverMessageWaiters.clear();
+      }
+      if (serverMessage?.type === heldServerMessageType) {
+        heldServerMessage = { browser: ws, message: outboundMessage };
+        resolveHeldServerMessage?.();
+        resolveHeldServerMessage = null;
+        return;
+      }
+      if (
+        shouldSuppressServerMessage({
+          message: serverMessage,
+          messageTypes: suppressedServerMessageTypes,
+          agentStreamEventTypes: suppressedAgentStreamEventTypes,
+          suppressAgentStream,
+        })
+      )
+        return;
       try {
-        ws.send(message);
+        ws.send(outboundMessage);
       } catch {
         activeSockets.delete(ws);
       }
@@ -100,6 +274,125 @@ export async function installDaemonWebSocketGate(page: Page) {
     restore(): void {
       acceptingConnections = true;
     },
+    restoreFresh(): void {
+      reconnectWithFreshClient = true;
+      acceptingConnections = true;
+    },
+    holdNextClientRequest(type: string): void {
+      heldClientRequestType = type;
+      heldClientRequest = null;
+    },
+    waitForHeldClientRequest(): Promise<void> {
+      if (heldClientRequest) return Promise.resolve();
+      return new Promise<void>((resolve) => {
+        resolveHeldClientRequest = resolve;
+      });
+    },
+    releaseHeldClientRequest(): void {
+      if (!heldClientRequest) throw new Error("No held client request to release");
+      heldClientRequest.server.send(heldClientRequest.message);
+      heldClientRequest = null;
+      heldClientRequestType = null;
+    },
+    holdNextServerMessage(type: string): void {
+      heldServerMessageType = type;
+      heldServerMessage = null;
+    },
+    waitForHeldServerMessage(): Promise<void> {
+      if (heldServerMessage) return Promise.resolve();
+      return new Promise<void>((resolve) => {
+        resolveHeldServerMessage = resolve;
+      });
+    },
+    releaseHeldServerMessage(): void {
+      if (!heldServerMessage) throw new Error("No held server message to release");
+      heldServerMessage.browser.send(heldServerMessage.message);
+      heldServerMessage = null;
+      heldServerMessageType = null;
+    },
+    requestTimelineTail(agentId: string): void {
+      if (!latestServer) throw new Error("No daemon WebSocket is connected");
+      latestServer.send(
+        JSON.stringify({
+          type: "session",
+          message: {
+            type: "fetch_agent_timeline_request",
+            agentId,
+            requestId: `playwright-timeline-${Date.now()}`,
+            direction: "tail",
+            limit: 0,
+            projection: "projected",
+          },
+        }),
+      );
+    },
+    getHeldTimelineLastItemType(): string | null {
+      if (!heldServerMessage) throw new Error("No held server message to inspect");
+      const response = readSessionMessage(heldServerMessage.message);
+      const payload = response?.payload;
+      if (!payload || typeof payload !== "object") return null;
+      const entries = (payload as { entries?: unknown }).entries;
+      if (!Array.isArray(entries)) return null;
+      const last = entries.at(-1) as { item?: { type?: unknown } } | undefined;
+      return typeof last?.item?.type === "string" ? last.item.type : null;
+    },
+    truncateHeldTimelineAfterLast(itemType: string): void {
+      if (!heldServerMessage || typeof heldServerMessage.message !== "string") {
+        throw new Error("No held text server message to truncate");
+      }
+      const envelope = JSON.parse(heldServerMessage.message) as {
+        message?: { payload?: Record<string, unknown> };
+        payload?: Record<string, unknown>;
+      };
+      const payload = envelope.message?.payload ?? envelope.payload;
+      if (!payload) throw new Error("Held message has no payload");
+      const entries = payload.entries;
+      if (!Array.isArray(entries)) throw new Error("Held message is not a timeline response");
+      const index = entries.findLastIndex(
+        (entry) =>
+          typeof entry === "object" &&
+          entry !== null &&
+          (entry as { item?: { type?: unknown } }).item?.type === itemType,
+      );
+      if (index < 0) throw new Error(`Timeline response has no ${itemType} item`);
+      const retained = entries.slice(0, index + 1) as Array<{ seqEnd?: unknown }>;
+      const lastSeq = retained.at(-1)?.seqEnd;
+      if (typeof lastSeq !== "number") throw new Error("Timeline entry has no sequence end");
+      payload.entries = retained;
+      payload.endCursor = { epoch: payload.epoch, seq: lastSeq };
+      payload.hasNewer = false;
+      if (payload.window && typeof payload.window === "object") {
+        (payload.window as Record<string, unknown>).maxSeq = lastSeq;
+        (payload.window as Record<string, unknown>).nextSeq = lastSeq + 1;
+      }
+      heldServerMessage.message = JSON.stringify(envelope);
+    },
+    setServerMessageSuppressed(type: string, suppressed: boolean): void {
+      if (suppressed) {
+        suppressedServerMessageTypes.add(type);
+      } else {
+        suppressedServerMessageTypes.delete(type);
+      }
+    },
+    setAgentStreamEventSuppressed(type: string, suppressed: boolean): void {
+      if (suppressed) {
+        suppressedAgentStreamEventTypes.add(type);
+      } else {
+        suppressedAgentStreamEventTypes.delete(type);
+      }
+    },
+    setAssistantMessageIdsStripped(stripped: boolean): void {
+      stripAssistantMessageIds = stripped;
+    },
+    setMessageSubmissionDispositionStripped(stripped: boolean): void {
+      stripSubmissionDisposition = stripped;
+    },
+    setAgentStreamSuppressed(suppressed: boolean): void {
+      suppressAgentStream = suppressed;
+    },
+    forceNextTimelineEpochReset(): void {
+      forceTimelineEpochReset = true;
+    },
     getDirectoryRequestStartCounts(): DirectoryRequestStartCounts {
       return {
         subscribed: { ...directoryStarts.subscribed },
@@ -110,5 +403,18 @@ export async function installDaemonWebSocketGate(page: Page) {
     getClientRequestCount(type: string): number {
       return clientRequestCounts.get(type) ?? 0;
     },
+    getAgentStreamItemCount(type: string): number {
+      return agentStreamItemCounts.get(type) ?? 0;
+    },
+    async waitForServerMessage(type: string, count = 1): Promise<void> {
+      while ((serverMessageCounts.get(type) ?? 0) < count) {
+        await new Promise<void>((resolve) => serverMessageWaiters.add(resolve));
+      }
+    },
+    async waitForAgentStreamItem(type: string, count = 1): Promise<void> {
+      while ((agentStreamItemCounts.get(type) ?? 0) < count) {
+        await new Promise<void>((resolve) => serverMessageWaiters.add(resolve));
+      }
+    },
   };
 }

packages/app/e2e/helpers/new-workspace.ts

@@ -177,6 +177,14 @@ export async function openGlobalNewWorkspaceComposer(page: Page): Promise<void>
   });
 }
 
+export async function openNewWorkspaceProjectPickerWithShortcut(page: Page): Promise<void> {
+  await page.keyboard.press("Control+P");
+
+  const searchInput = page.getByPlaceholder("Search projects");
+  await expect(searchInput).toBeVisible({ timeout: 30_000 });
+  await expect(searchInput).toBeFocused();
+}
+
 export async function expectNewWorkspaceProjectSelected(
   page: Page,
   projectDisplayName: string,

packages/app/e2e/helpers/timeline-pagination.ts

@@ -1,16 +1,51 @@
 import { expect, type Page } from "@playwright/test";
 import { buildAgentRoute, seedMockAgentWorkspace, type MockAgentWorkspace } from "./mock-agent";
+import {
+  delayAgentBootstrapTailResponse,
+  delayAgentOlderTimelineResponse,
+  holdDaemonHydration,
+  holdAgentOlderTimelinePages,
+  type AgentTimelineResponseGate,
+  type BootstrapTimelineGate,
+  type OlderTimelinePagesGate,
+} from "./agent-timeline-gate";
+
+export { holdDaemonHydration };
 
 interface LongTimelineAgentOptions {
   turns: number;
 }
 
 interface LongTimelineAgent extends MockAgentWorkspace {
+  initialTailOldestPrompt: string;
   oldestPrompt: string;
   newestPrompt: string;
 }
 
 const PROMPT_PREFIX = "timeline-pagination-turn";
+const LIVE_BEFORE_HYDRATION_PROMPT = "timeline live before authoritative hydration";
+const HISTORY_START_THRESHOLD_PX = 96;
+
+interface TimelineViewportSnapshot {
+  scrollHeight: number;
+  scrollTop: number;
+}
+
+interface TimelinePromptPositionSnapshot {
+  prompt: string;
+  top: number;
+}
+
+interface OlderHistoryLoadingOperation {
+  animationStartTime: number | null;
+  marker: string;
+}
+
+interface OlderHistoryPages {
+  expectRequestedPages(count: number): Promise<void>;
+  expectSettledWithRequestedPages(count: number): Promise<void>;
+  releasePage(pageNumber: number): void;
+}
 
 function promptForTurn(index: number): string {
   return `${PROMPT_PREFIX}-${index}: emit 1 coalesced agent stream updates`;
@@ -32,11 +67,41 @@ export async function seedLongMockAgentTimeline(
 
   return {
     ...agent,
+    initialTailOldestPrompt: promptForTurn(Math.max(0, options.turns - 20)),
     oldestPrompt: promptForTurn(0),
     newestPrompt: promptForTurn(options.turns - 1),
   };
 }
 
+export async function rememberTimelinePromptPosition(
+  page: Page,
+  prompt: string,
+): Promise<TimelinePromptPositionSnapshot> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  const item = timeline.getByText(prompt, { exact: true });
+  await expect(item).toBeVisible();
+  const box = await item.boundingBox();
+  if (!box) {
+    throw new Error(`Expected a rendered timeline item for ${prompt}`);
+  }
+  return { prompt, top: box.y };
+}
+
+export async function expectTimelinePromptPositionPreserved(
+  page: Page,
+  before: TimelinePromptPositionSnapshot,
+): Promise<void> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  const item = timeline.getByText(before.prompt, { exact: true });
+  await expect(item).toBeVisible();
+  await expect
+    .poll(async () => {
+      const box = await item.boundingBox();
+      return box ? Math.abs(box.y - before.top) : Number.POSITIVE_INFINITY;
+    })
+    .toBeLessThanOrEqual(2);
+}
+
 export async function openAgentTimeline(page: Page, agent: LongTimelineAgent): Promise<void> {
   await page.goto(buildAgentRoute(agent.workspaceId, agent.agentId));
   await page.waitForURL(
@@ -46,11 +111,173 @@ export async function openAgentTimeline(page: Page, agent: LongTimelineAgent): P
 }
 
 export async function expectTimelinePromptVisible(page: Page, prompt: string): Promise<void> {
-  await expect(page.getByText(prompt, { exact: true })).toBeVisible({ timeout: 30_000 });
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await expect(timeline.getByText(prompt, { exact: true })).toBeVisible({ timeout: 30_000 });
 }
 
 export async function expectTimelinePromptNotMounted(page: Page, prompt: string): Promise<void> {
-  await expect(page.getByText(prompt, { exact: true })).toHaveCount(0);
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await expect(timeline.getByText(prompt, { exact: true })).toHaveCount(0);
+}
+
+export async function makeLoadedTimelineFitViewport(page: Page): Promise<void> {
+  await page.setViewportSize({ width: 1280, height: 20_000 });
+}
+
+export async function expectLoadedTimelineDoesNotScroll(page: Page): Promise<void> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await expect
+    .poll(async () =>
+      scroll.evaluate((element) => {
+        if (!(element instanceof HTMLElement)) {
+          throw new Error("Agent chat scroll element is not an HTMLElement");
+        }
+        return element.scrollHeight <= element.clientHeight;
+      }),
+    )
+    .toBe(true);
+}
+
+export async function reloadAgentTimelineFromPersistedReplica(
+  page: Page,
+  agent: LongTimelineAgent,
+): Promise<void> {
+  await expect
+    .poll(() =>
+      page.evaluate((agentId) => {
+        const raw = localStorage.getItem("@paseo:replica-cache");
+        if (!raw) return false;
+        const cache = JSON.parse(raw) as {
+          hosts?: Array<{
+            timeline?: {
+              agentId?: string;
+              items?: unknown[];
+            } | null;
+          }>;
+        };
+        const timeline = cache.hosts?.find((host) => host.timeline?.agentId === agentId)?.timeline;
+        return timeline?.items?.length === 50;
+      }, agent.agentId),
+    )
+    .toBe(true);
+
+  await page.reload();
+  await expectTimelinePromptVisible(page, agent.newestPrompt);
+}
+
+export async function holdNextOlderTimelinePage(
+  page: Page,
+  agent: LongTimelineAgent,
+): Promise<AgentTimelineResponseGate & { expectLoading(): Promise<void> }> {
+  const gate = await delayAgentOlderTimelineResponse(page, agent.agentId);
+  return {
+    ...gate,
+    async expectLoading() {
+      await gate.waitForDelayedResponse();
+      await expect(page.getByTestId("load-older-history-spinner")).toBeVisible();
+      await expectTimelinePromptNotMounted(page, agent.oldestPrompt);
+    },
+  };
+}
+
+export async function holdOlderHistoryPages(
+  page: Page,
+  agent: LongTimelineAgent,
+): Promise<OlderHistoryPages> {
+  const gate: OlderTimelinePagesGate = await holdAgentOlderTimelinePages(page, agent.agentId);
+  return {
+    async expectRequestedPages(count) {
+      await gate.waitForRequestCount(count);
+      expect(gate.getRequestCount()).toBe(count);
+    },
+    async expectSettledWithRequestedPages(count) {
+      await waitForTimelineGeometryToSettle(page);
+      expect(gate.getRequestCount()).toBe(count);
+    },
+    releasePage(pageNumber) {
+      gate.releasePage(pageNumber);
+    },
+  };
+}
+
+export async function rememberTimelineViewport(page: Page): Promise<TimelineViewportSnapshot> {
+  return readTimelineViewport(page);
+}
+
+export async function expectTimelineViewportAnchoredAfterPrepend(
+  page: Page,
+  before: TimelineViewportSnapshot,
+): Promise<void> {
+  await expect
+    .poll(async () => (await readTimelineViewport(page)).scrollHeight)
+    .toBeGreaterThan(before.scrollHeight);
+  await waitForTimelineGeometryToSettle(page);
+  const after = await readTimelineViewport(page);
+  const contentGrowth = after.scrollHeight - before.scrollHeight;
+  const scrollAdjustment = after.scrollTop - before.scrollTop;
+  expect(Math.abs(contentGrowth - scrollAdjustment)).toBeLessThanOrEqual(2);
+}
+
+export async function rememberOlderHistoryLoadingOperation(
+  page: Page,
+): Promise<OlderHistoryLoadingOperation> {
+  const slot = page.getByTestId("load-older-history-spinner");
+  await expect(slot).toBeVisible();
+  const marker = `older-history-loading-${Date.now()}`;
+  await slot.evaluate((element, operationMarker) => {
+    const candidates = [element, ...Array.from(element.querySelectorAll("*"))];
+    const animated = candidates.find(
+      (candidate) => getComputedStyle(candidate).animationName !== "none",
+    );
+    if (!(animated instanceof HTMLElement)) {
+      throw new Error("Expected the older-history loader to contain an animated element");
+    }
+    animated.dataset.olderHistoryLoadingOperation = operationMarker;
+  }, marker);
+  const animated = page.locator(`[data-older-history-loading-operation="${marker}"]`);
+  await expect
+    .poll(async () => {
+      const startTime = await animated.evaluate((element) => element.getAnimations()[0]?.startTime);
+      return typeof startTime === "number" ? startTime : null;
+    })
+    .not.toBeNull();
+  const animationStartTime = await animated.evaluate((element) => {
+    const startTime = element.getAnimations()[0]?.startTime;
+    return typeof startTime === "number" ? startTime : null;
+  });
+  return { animationStartTime, marker };
+}
+
+export async function expectSameOlderHistoryLoadingOperation(
+  page: Page,
+  operation: OlderHistoryLoadingOperation,
+): Promise<void> {
+  const animated = page.locator(`[data-older-history-loading-operation="${operation.marker}"]`);
+  await expect(animated).toBeVisible();
+  const animationStartTime = await animated.evaluate((element) => {
+    const startTime = element.getAnimations()[0]?.startTime;
+    return typeof startTime === "number" ? startTime : null;
+  });
+  expect(animationStartTime).toBe(operation.animationStartTime);
+}
+
+export async function expectTimelineAtHistoryStart(page: Page): Promise<void> {
+  await expect
+    .poll(async () => (await readTimelineViewport(page)).scrollTop)
+    .toBeLessThanOrEqual(HISTORY_START_THRESHOLD_PX);
+}
+
+export async function holdBootstrapTimelinePage(
+  page: Page,
+  agent: LongTimelineAgent,
+): Promise<BootstrapTimelineGate> {
+  return delayAgentBootstrapTailResponse(page, agent.agentId);
+}
+
+export async function sendLiveTurnBeforeHydration(agent: LongTimelineAgent): Promise<string> {
+  await agent.client.sendAgentMessage(agent.agentId, LIVE_BEFORE_HYDRATION_PROMPT);
+  await agent.client.waitForFinish(agent.agentId, 15_000);
+  return LIVE_BEFORE_HYDRATION_PROMPT;
 }
 
 export async function scrollTimelineToOldestLoadedEdge(page: Page): Promise<void> {
@@ -72,31 +299,95 @@ export async function scrollTimelineToOldestLoadedEdge(page: Page): Promise<void
   });
 }
 
-export async function scrollTimelineUntilOlderHistoryIsReachable(page: Page): Promise<void> {
+export async function userScrollsTimelineToHistoryStart(page: Page): Promise<void> {
   const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
-  const previousHeight = await scroll.evaluate((element) => {
+  await scroll.hover();
+  for (let step = 0; step < 60; step += 1) {
+    if ((await readTimelineViewport(page)).scrollTop <= HISTORY_START_THRESHOLD_PX) {
+      break;
+    }
+    await page.mouse.wheel(0, -1_000);
+    await page.evaluate(
+      () =>
+        new Promise<void>((resolve) => {
+          requestAnimationFrame(() => resolve());
+        }),
+    );
+  }
+  await expect
+    .poll(async () => (await readTimelineViewport(page)).scrollTop)
+    .toBeLessThanOrEqual(HISTORY_START_THRESHOLD_PX);
+}
+
+export async function scrollTimelineToNewestLoadedEdge(page: Page): Promise<void> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await scroll.evaluate((element) => {
     if (!(element instanceof HTMLElement)) {
       throw new Error("Agent chat scroll element is not an HTMLElement");
     }
-    return element.scrollHeight;
+    element.scrollTop = element.scrollHeight;
+    element.dispatchEvent(new Event("scroll", { bubbles: true }));
   });
+}
 
-  await page.evaluate(
-    () =>
-      new Promise<void>((resolve) => {
-        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+export async function scrollTimelineUntilOlderHistoryIsReachable(
+  page: Page,
+  oldestPrompt: string,
+): Promise<void> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  const prompt = scroll.getByText(oldestPrompt, { exact: true });
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    if ((await prompt.count()) > 0) {
+      await expect(prompt).toBeVisible();
+      return;
+    }
+    const previousHeight = await readTimelineViewport(page);
+    await userScrollsTimelineToHistoryStart(page);
+    await expect
+      .poll(async () => (await readTimelineViewport(page)).scrollHeight)
+      .toBeGreaterThan(previousHeight.scrollHeight);
+    await waitForTimelineGeometryToSettle(page);
+  }
+  await expect(prompt).toBeVisible();
+}
+
+async function readTimelineViewport(page: Page): Promise<TimelineViewportSnapshot> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  return scroll.evaluate((element) => {
+    if (!(element instanceof HTMLElement)) {
+      throw new Error("Agent chat scroll element is not an HTMLElement");
+    }
+    return { scrollHeight: element.scrollHeight, scrollTop: element.scrollTop };
+  });
+}
+
+async function waitForTimelineGeometryToSettle(page: Page): Promise<void> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await scroll.evaluate(
+    (element) =>
+      new Promise<void>((resolve, reject) => {
+        if (!(element instanceof HTMLElement)) {
+          reject(new Error("Agent chat scroll element is not an HTMLElement"));
+          return;
+        }
+        const startedAt = performance.now();
+        let stableFrames = 0;
+        let previous = `${element.scrollTop}:${element.scrollHeight}`;
+        const sample = () => {
+          const current = `${element.scrollTop}:${element.scrollHeight}`;
+          stableFrames = current === previous ? stableFrames + 1 : 0;
+          previous = current;
+          if (stableFrames >= 4) {
+            resolve();
+            return;
+          }
+          if (performance.now() - startedAt > 5_000) {
+            reject(new Error("Timeline geometry did not settle"));
+            return;
+          }
+          requestAnimationFrame(sample);
+        };
+        requestAnimationFrame(sample);
       }),
   );
-  await scrollTimelineToOldestLoadedEdge(page);
-  await expect
-    .poll(async () =>
-      scroll.evaluate((element) => {
-        if (!(element instanceof HTMLElement)) {
-          throw new Error("Agent chat scroll element is not an HTMLElement");
-        }
-        return element.scrollHeight;
-      }),
-    )
-    .toBeGreaterThan(previousHeight);
-  await scrollTimelineToOldestLoadedEdge(page);
 }

packages/app/e2e/new-workspace-codex-mode-preferences.spec.ts

@@ -100,11 +100,7 @@ async function selectMode(page: Page, label: string): Promise<void> {
   await expect(searchInput).toBeVisible({ timeout: 10_000 });
   await searchInput.fill(label);
 
-  const option = page
-    .getByRole("dialog")
-    .last()
-    .getByText(new RegExp(`^${escapeRegex(label)}$`, "i"))
-    .first();
+  const option = popup.getByText(new RegExp(`^${escapeRegex(label)}$`, "i")).first();
   await expect(option).toBeVisible({ timeout: 10_000 });
   await option.click({ force: true });
   await expect(searchInput).not.toBeVisible({ timeout: 5_000 });

packages/app/e2e/new-workspace-entry.spec.ts

@@ -5,6 +5,7 @@ import {
   expectNewWorkspaceProjectSelected,
   openGlobalNewWorkspaceComposer,
   openNewWorkspaceComposer,
+  openNewWorkspaceProjectPickerWithShortcut,
 } from "./helpers/new-workspace";
 import { getE2EDaemonPort } from "./helpers/daemon-port";
 import { seedWorkspace, type SeededWorkspace } from "./helpers/seed-client";
@@ -106,6 +107,20 @@ test.describe("New workspace entry points", () => {
     }
   });
 
+  test("Ctrl+P opens the project picker with search focused", async ({ page }) => {
+    const seeded: SeededWorkspace = await seedWorkspace({ repoPrefix: "entry-shortcut-" });
+
+    try {
+      await gotoAppShell(page);
+      await waitForSidebarHydration(page);
+      await openGlobalNewWorkspaceComposer(page);
+
+      await openNewWorkspaceProjectPickerWithShortcut(page);
+    } finally {
+      await seeded.cleanup();
+    }
+  });
+
   test("keeps the in-progress form when the remembered workspace is archived elsewhere", async ({
     page,
   }) => {

packages/app/e2e/new-workspace-mode-cycle-safety.spec.ts

@@ -0,0 +1,146 @@
+import { expect, test, type Page } from "./fixtures";
+import { daemonWsRoutePattern } from "./helpers/daemon-port";
+import { openAgentRoute } from "./helpers/mock-agent";
+import { openGlobalNewWorkspaceComposer, selectNewWorkspaceProject } from "./helpers/new-workspace";
+import { seedWorkspace } from "./helpers/seed-client";
+import { getServerId } from "./helpers/server-id";
+
+const CREATE_AGENT_PREFERENCES_KEY = "@paseo:create-agent-preferences";
+
+type WebSocketMessage = string | Buffer;
+
+function parseWebSocketJson(message: WebSocketMessage): unknown {
+  const rawMessage = typeof message === "string" ? message : message.toString("utf8");
+  try {
+    return JSON.parse(rawMessage);
+  } catch {
+    return null;
+  }
+}
+
+function getSessionMessage(message: WebSocketMessage): Record<string, unknown> | null {
+  const envelope = parseWebSocketJson(message);
+  if (!envelope || typeof envelope !== "object") {
+    return null;
+  }
+  const maybeEnvelope = envelope as { type?: unknown; message?: unknown };
+  if (maybeEnvelope.type !== "session" || !maybeEnvelope.message) {
+    return null;
+  }
+  if (typeof maybeEnvelope.message !== "object") {
+    return null;
+  }
+  return maybeEnvelope.message as Record<string, unknown>;
+}
+
+// The draft mode control in New Workspace only mutates local form state; it never sends
+// set_agent_mode_request. So the only source of such a request while the New Workspace
+// composer is focused is a *live* agent's mode control. Recording those, keyed by agentId,
+// gives a direct signal that Shift+Tab leaked into a backgrounded agent.
+async function recordSetAgentModeRequests(page: Page): Promise<{
+  requestsForAgent(agentId: string): Array<{ agentId: string; modeId: string }>;
+}> {
+  const seen: Array<{ agentId: string; modeId: string }> = [];
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+    ws.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      if (sessionMessage?.type === "set_agent_mode_request") {
+        const agentId = typeof sessionMessage.agentId === "string" ? sessionMessage.agentId : "";
+        const modeId = typeof sessionMessage.modeId === "string" ? sessionMessage.modeId : "";
+        seen.push({ agentId, modeId });
+      }
+      server.send(message);
+    });
+    server.onMessage((message) => ws.send(message));
+  });
+  return {
+    requestsForAgent: (agentId: string) => seen.filter((request) => request.agentId === agentId),
+  };
+}
+
+async function seedCodexDefaultPreferences(page: Page, serverId: string): Promise<void> {
+  await page.addInitScript(
+    ({ preferencesKey, serverId: seededServerId }) => {
+      localStorage.setItem(
+        preferencesKey,
+        JSON.stringify({
+          serverId: seededServerId,
+          provider: "codex",
+          providerPreferences: {
+            codex: {
+              model: "gpt-5.4-mini",
+              mode: "auto",
+              thinkingByModel: { "gpt-5.4-mini": "low" },
+            },
+            mock: { model: "ten-second-stream" },
+          },
+        }),
+      );
+    },
+    { preferencesKey: CREATE_AGENT_PREFERENCES_KEY, serverId },
+  );
+}
+
+// Focus the New Workspace composer and cycle the execution mode with the keyboard.
+// Kept out of the test body so the test reads as intent rather than key mechanics.
+async function cycleNewWorkspaceMode(page: Page, presses: number): Promise<void> {
+  const composer = page.getByRole("textbox", { name: "Message agent..." });
+  await expect(composer).toBeVisible({ timeout: 30_000 });
+  await composer.click();
+  for (let i = 0; i < presses; i++) {
+    await page.keyboard.press("Shift+Tab");
+  }
+}
+
+test.describe("New Workspace mode cycle safety", () => {
+  test.describe.configure({ timeout: 240_000 });
+
+  // Regression guard for the P1 safety bug: cycling the execution mode with Shift+Tab in
+  // the New Workspace composer must never reach a backgrounded, still-mounted agent's mode
+  // control and silently change that (possibly running) agent's mode — e.g. into a
+  // permissive/bypass mode. See use-keyboard-action-handler.ts.
+  test("Shift+Tab in New Workspace never changes a backgrounded agent's mode", async ({ page }) => {
+    const serverId = getServerId();
+    const seeded = await seedWorkspace({ repoPrefix: "mode-cycle-safety-" });
+    await seedCodexDefaultPreferences(page, serverId);
+    const modeRequests = await recordSetAgentModeRequests(page);
+
+    try {
+      const agent = await seeded.client.createAgent({
+        provider: "codex",
+        cwd: seeded.repoPath,
+        workspaceId: seeded.workspaceId,
+        title: "mode cycle safety e2e",
+        modeId: "auto",
+        model: "gpt-5.4-mini",
+      });
+
+      // Mount the live agent tab: its mode control registers a mode-cycle keyboard handler.
+      await openAgentRoute(page, { workspaceId: seeded.workspaceId, agentId: agent.id });
+      await expect(page.getByTestId("mode-control").first()).toContainText("Default permissions", {
+        timeout: 30_000,
+      });
+
+      // Move to the New Workspace composer. The agent tab stays mounted in the background,
+      // so its handler is still registered when we cycle here.
+      await openGlobalNewWorkspaceComposer(page);
+      await selectNewWorkspaceProject(page, {
+        projectKey: seeded.projectId,
+        projectDisplayName: seeded.projectDisplayName,
+      });
+
+      await cycleNewWorkspaceMode(page, 6);
+
+      // fetchAgents is a real daemon round-trip; once it resolves, any mode change the
+      // presses would have triggered has already landed. Assert the running agent is
+      // untouched — both its committed mode and on the wire — with no fixed sleep.
+      const agents = await seeded.client.fetchAgents();
+      const backgroundAgent = agents.entries.find((entry) => entry.agent.id === agent.id)?.agent;
+      expect(backgroundAgent?.currentModeId).toBe("auto");
+      expect(modeRequests.requestsForAgent(agent.id)).toEqual([]);
+    } finally {
+      await seeded.cleanup();
+    }
+  });
+});

packages/app/e2e/out-of-band-command.codex.real.spec.ts

@@ -0,0 +1,52 @@
+import { mkdtempSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "./fixtures";
+import { submitMessage } from "./helpers/composer";
+import { cleanupRewindFlow, launchAgent, type AgentHandle } from "./helpers/rewind-flow";
+import { installDaemonWebSocketGate } from "./helpers/daemon-websocket-gate";
+
+test.describe("Codex out-of-band commands", () => {
+  test.setTimeout(300_000);
+
+  test("settles the submitted row when a goal command completes without a turn", async ({
+    page,
+  }) => {
+    const cwd = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-codex-command-")));
+    let handle: AgentHandle | undefined;
+
+    try {
+      handle = await launchAgent({ page, provider: "codex", cwd, mode: "full-access" });
+      await submitMessage(page, "/goal clear");
+      const command = page.getByTestId("user-message").filter({ hasText: "/goal clear" });
+
+      await expect(command).toBeVisible();
+      await expect(command).toHaveAttribute("aria-busy", "false", { timeout: 30_000 });
+      await expect(page.getByTestId("turn-working-indicator")).toHaveCount(0);
+    } finally {
+      await cleanupRewindFlow({ handle, cwd });
+    }
+  });
+
+  test("settles the submitted row when an older daemon omits submission disposition", async ({
+    page,
+  }) => {
+    const gate = await installDaemonWebSocketGate(page);
+    gate.setMessageSubmissionDispositionStripped(true);
+    const cwd = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-codex-command-compat-")));
+    let handle: AgentHandle | undefined;
+
+    try {
+      handle = await launchAgent({ page, provider: "codex", cwd, mode: "full-access" });
+      await submitMessage(page, "/goal clear");
+      const command = page.getByTestId("user-message").filter({ hasText: "/goal clear" });
+
+      await expect(command).toBeVisible();
+      await expect(command).toHaveAttribute("aria-busy", "false", { timeout: 30_000 });
+      await expect(page.getByTestId("turn-working-indicator")).toHaveCount(0);
+    } finally {
+      gate.restore();
+      await cleanupRewindFlow({ handle, cwd });
+    }
+  });
+});

packages/app/e2e/provider-settings-refresh.spec.ts

@@ -1,3 +1,4 @@
+import type { Locator } from "@playwright/test";
 import { expect, test, type Page } from "./fixtures";
 import { expectComposerVisible } from "./helpers/composer";
 import { openAgentRoute, seedMockAgentWorkspace } from "./helpers/mock-agent";
@@ -63,6 +64,33 @@ async function closeSheetByHeaderButton(page: Page, testId: string) {
   await expect(sheet).not.toBeVisible({ timeout: 10_000 });
 }
 
+async function expectOverlayAbove(page: Page, frontTestId: string, backTestId: string) {
+  const frontCoversBack = await page.evaluate(
+    ({ frontTestId: frontId, backTestId: backId }) => {
+      const front = document.querySelector(`[data-testid="${frontId}"]`);
+      const back = document.querySelector(`[data-testid="${backId}"]`);
+      if (!(front instanceof HTMLElement) || !(back instanceof HTMLElement)) return false;
+
+      const frontRect = front.getBoundingClientRect();
+      const backRect = back.getBoundingClientRect();
+      const left = Math.max(frontRect.left, backRect.left);
+      const right = Math.min(frontRect.right, backRect.right);
+      const top = Math.max(frontRect.top, backRect.top);
+      const bottom = Math.min(frontRect.bottom, backRect.bottom);
+      if (left >= right || top >= bottom) return false;
+
+      const topElement = document.elementFromPoint((left + right) / 2, (top + bottom) / 2);
+      return topElement != null && front.contains(topElement);
+    },
+    { frontTestId, backTestId },
+  );
+  expect(frontCoversBack).toBe(true);
+}
+
+async function hasFocusWithin(locator: Locator): Promise<boolean> {
+  return locator.evaluate((element) => element.contains(document.activeElement));
+}
+
 async function expectProviderSettingsVisible(page: Page) {
   await expect(page.getByTestId("provider-settings-sheet")).toBeVisible({ timeout: 10_000 });
   await expect(page.getByRole("button", { name: "Add model" })).toBeVisible();
@@ -89,7 +117,69 @@ async function exerciseProviderSettingsStack(page: Page) {
   await expectProviderSettingsVisible(page);
 }
 
-test.describe("provider settings bottom-sheet stack", () => {
+test.describe("provider settings overlay stack", () => {
+  test("provider settings covers the desktop model selector without closing it", async ({
+    page,
+  }) => {
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "provider-modal-layer-",
+      title: "Provider modal layer e2e",
+    });
+
+    try {
+      await openAgentRoute(page, session);
+      await expectComposerVisible(page);
+
+      await page.getByRole("button", { name: /Select model/ }).click();
+      const selector = page.getByTestId("combobox-desktop-container");
+      await expect(selector).toBeVisible({ timeout: 10_000 });
+      const searchInput = page.getByRole("textbox", { name: /search models/i });
+      await expect(searchInput).toBeFocused();
+      await page.keyboard.press("Shift+Tab");
+      await expect.poll(() => hasFocusWithin(selector)).toBe(true);
+
+      await page.keyboard.press("Shift+?");
+      const shortcuts = page.getByTestId("keyboard-shortcuts-dialog");
+      await expect(shortcuts).toBeVisible({ timeout: 10_000 });
+      await expect(page.getByPlaceholder("Search shortcuts")).toBeFocused();
+      await page.keyboard.press("Escape");
+      await expect(shortcuts).not.toBeVisible({ timeout: 10_000 });
+      await expect(selector).toBeVisible();
+
+      await page.keyboard.press("ControlOrMeta+K");
+      const commandCenter = page.getByTestId("command-center-panel");
+      await expect(commandCenter).toBeVisible({ timeout: 10_000 });
+      await expect(commandCenter.getByTestId("command-center-input")).toBeFocused();
+      await page.keyboard.press("Escape");
+      await expect(commandCenter).not.toBeVisible({ timeout: 10_000 });
+      await expect(selector).toBeVisible();
+
+      await page.keyboard.press("ControlOrMeta+K");
+      await expect(commandCenter).toBeVisible({ timeout: 10_000 });
+      await commandCenter.getByText("Add project", { exact: true }).click();
+      const addProject = page.getByTestId("add-project-flow");
+      await expect(addProject).toBeVisible({ timeout: 10_000 });
+      await expect(addProject.getByTestId("add-project-flow-input")).toBeFocused();
+      await page.keyboard.press("Escape");
+      await expect(addProject).not.toBeVisible({ timeout: 10_000 });
+      await expect(selector).toBeVisible();
+
+      const settingsButton = page.getByTestId("selector-header-settings-mock");
+      await settingsButton.click();
+
+      const settings = page.getByTestId("provider-settings-sheet");
+      await expect(settings).toBeVisible({ timeout: 10_000 });
+      await expectOverlayAbove(page, "provider-settings-sheet", "combobox-desktop-container");
+
+      await page.keyboard.press("Escape");
+      await expect(settings).not.toBeVisible({ timeout: 10_000 });
+      await expect(selector).toBeVisible();
+      await expect(settingsButton).toBeFocused();
+    } finally {
+      await session.cleanup();
+    }
+  });
+
   test("provider settings and children close back through the model selector stack", async ({
     page,
   }) => {

packages/app/e2e/rewind-menu.ui-contract.spec.ts

@@ -1,6 +1,8 @@
 import type { Locator } from "@playwright/test";
 import { expect, test, type Page } from "./fixtures";
 import { openAgentRoute, seedMockAgentWorkspace } from "./helpers/mock-agent";
+import { installDaemonWebSocketGate } from "./helpers/daemon-websocket-gate";
+import { scrollChatAwayFromBottom } from "./helpers/agent-bottom-anchor";
 import {
   composerLocator,
   expectComposerDraft,
@@ -23,7 +25,152 @@ async function expectUserMessageVisible(page: Page, text: string): Promise<void>
   await expect(userMessage(page, text)).toBeVisible();
 }
 
+async function rewriteCachedMessageAsLegacyRow(page: Page, prompt: string): Promise<void> {
+  await expect
+    .poll(() =>
+      page.evaluate((messageText) => {
+        const raw = localStorage.getItem("@paseo:replica-cache");
+        if (!raw) return false;
+        const cache = JSON.parse(raw) as {
+          hosts?: Array<{ timeline?: { items?: Array<Record<string, unknown>> } | null }>;
+        };
+        for (const host of cache.hosts ?? []) {
+          for (const item of host.timeline?.items ?? []) {
+            if (item.kind === "user_message" && item.text === messageText && item.messageId) {
+              return true;
+            }
+          }
+        }
+        return false;
+      }, prompt),
+    )
+    .toBe(true);
+
+  await page.evaluate((messageText) => {
+    const key = "@paseo:replica-cache";
+    const raw = localStorage.getItem(key);
+    if (!raw) throw new Error("Replica cache was not persisted");
+    const cache = JSON.parse(raw) as {
+      hosts?: Array<{ timeline?: { items?: Array<Record<string, unknown>> } | null }>;
+    };
+    const cachedMessage = cache.hosts
+      ?.flatMap((host) => host.timeline?.items ?? [])
+      .find((item) => item.kind === "user_message" && item.text === messageText);
+    if (!cachedMessage) throw new Error("Cached user message was not found");
+    delete cachedMessage.messageId;
+    localStorage.setItem(key, JSON.stringify(cache));
+  }, prompt);
+}
+
+async function waitForCurrentSubmissionExcludedFromCache(
+  page: Page,
+  prompt: string,
+): Promise<void> {
+  await expect
+    .poll(() =>
+      page.evaluate((messageText) => {
+        const raw = localStorage.getItem("@paseo:replica-cache");
+        if (!raw) return false;
+        const cache = JSON.parse(raw) as {
+          hosts?: Array<{ timeline?: { items?: Array<Record<string, unknown>> } | null }>;
+        };
+        return !cache.hosts
+          ?.flatMap((host) => host.timeline?.items ?? [])
+          .some(
+            (item) =>
+              item.kind === "user_message" &&
+              item.text === messageText &&
+              typeof item.clientMessageId === "string" &&
+              item.messageId === undefined,
+          );
+      }, prompt),
+    )
+    .toBe(true);
+}
+
+async function waitForCachedMessageWithoutProviderId(page: Page, prompt: string): Promise<void> {
+  await expect
+    .poll(() =>
+      page.evaluate((messageText) => {
+        const raw = localStorage.getItem("@paseo:replica-cache");
+        if (!raw) return false;
+        const cache = JSON.parse(raw) as {
+          hosts?: Array<{ timeline?: { items?: Array<Record<string, unknown>> } | null }>;
+        };
+        return cache.hosts
+          ?.flatMap((host) => host.timeline?.items ?? [])
+          .some(
+            (item) =>
+              item.kind === "user_message" &&
+              item.text === messageText &&
+              item.messageId === undefined,
+          );
+      }, prompt),
+    )
+    .toBe(true);
+}
+
+async function expectPendingSubmissionNotRestoredAfterReload(page: Page): Promise<void> {
+  const prompt = "Keep this cached submission pending.";
+  const gate = await installDaemonWebSocketGate(page);
+  const session = await seedMockAgentWorkspace({
+    repoPrefix: "rewind-current-cache-e2e-",
+    title: "Current cache submission e2e",
+  });
+
+  try {
+    await openAgentRoute(page, session);
+    await expectComposerVisible(page);
+    gate.holdNextClientRequest("send_agent_message_request");
+    await submitMessage(page, prompt);
+    await gate.waitForHeldClientRequest();
+    await waitForCurrentSubmissionExcludedFromCache(page, prompt);
+    await gate.drop();
+    await page.reload();
+
+    await expect(userMessage(page, prompt)).toHaveCount(0);
+  } finally {
+    gate.restore();
+    await session.cleanup();
+  }
+}
+
 test.describe("Rewind sheet", () => {
+  test("does not restore a local-only submission from the display cache", async ({ page }) => {
+    await expectPendingSubmissionNotRestoredAfterReload(page);
+  });
+
+  test("does not invent rewind identity for an ID-less cached message", async ({ page }) => {
+    const prompt = "Restore this rewind identity from the legacy cache.";
+    const gate = await installDaemonWebSocketGate(page);
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "rewind-cache-upgrade-e2e-",
+      title: "Rewind cache upgrade e2e",
+      initialPrompt: prompt,
+    });
+    let heldTimelineRequest = false;
+
+    try {
+      await openAgentRoute(page, session);
+      await expectUserMessageVisible(page, prompt);
+      await rewriteCachedMessageAsLegacyRow(page, prompt);
+      gate.holdNextClientRequest("fetch_agent_timeline_request");
+      await page.reload();
+      await gate.waitForHeldClientRequest();
+      heldTimelineRequest = true;
+
+      const restoredMessage = userMessage(page, prompt);
+      await expect(restoredMessage).toBeVisible();
+      await restoredMessage.hover();
+      await expect(restoredMessage.getByTestId("rewind-menu-trigger")).toHaveCount(0);
+      await waitForCachedMessageWithoutProviderId(page, prompt);
+    } finally {
+      if (heldTimelineRequest) gate.releaseHeldClientRequest();
+      gate.restore();
+      await session.cleanup();
+    }
+  });
+
   test("rewinds from a user message sheet option", async ({ page }) => {
     const firstPrompt = "emit 1 coalesced agent stream updates for first rewind turn.";
     const secondPrompt = "Prepare deleted rewind turn assistant content.";
@@ -45,6 +192,10 @@ test.describe("Rewind sheet", () => {
       await expect(page.getByText("Cycle 1", { exact: true })).toBeVisible();
       await expectUserMessageCount(page, 2);
 
+      await scrollChatAwayFromBottom(page, {
+        deltaY: -900,
+        minDistanceFromBottom: 300,
+      });
       await userMessage(page, firstPrompt).hover();
       await page.getByTestId("rewind-menu-trigger").first().click();
       const rewindSheet = page.getByTestId("rewind-menu-content");

packages/app/e2e/sidebar-workspace-pin-shortcut.spec.ts

@@ -0,0 +1,266 @@
+import { test, expect, type Page } from "./fixtures";
+import { gotoAppShell } from "./helpers/app";
+import { daemonWsRoutePattern } from "./helpers/daemon-port";
+import { seedWorkspace, type SeededWorkspace } from "./helpers/seed-client";
+import { getServerId } from "./helpers/server-id";
+
+// The pin shortcut used to be registered by the sidebar row itself, so it silently did nothing
+// whenever the row was unmounted — a collapsed project section being the common case. It now
+// lives in a single always-mounted handler keyed on the active route selection.
+const PIN_SHORTCUT = "ControlOrMeta+Shift+P";
+
+function workspaceRow(page: Page, workspaceId: string) {
+  return page.getByTestId(`sidebar-workspace-row-${getServerId()}:${workspaceId}`);
+}
+
+function pinnedSection(page: Page) {
+  return page.getByTestId("sidebar-pinned-section");
+}
+
+// Opens the workspace so it becomes the active route selection, which is what the shortcut acts on.
+async function openWorkspace(page: Page, workspaceId: string) {
+  const row = workspaceRow(page, workspaceId);
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  await row.click();
+  await expect(page).toHaveURL(/\/workspace\//, { timeout: 30_000 });
+}
+
+// The project key is host-scoped and not exposed by the seed helper, so the header is addressed by
+// its display name, scoped to project rows so a workspace row can never match. Pressing the header
+// toggles the section, which unmounts every workspace row under it.
+async function collapseProjectSection(page: Page, project: SeededWorkspace): Promise<void> {
+  const header = page
+    .locator('[data-testid^="sidebar-project-row-"]')
+    .filter({ hasText: project.projectDisplayName });
+  await expect(header).toHaveCount(1, { timeout: 30_000 });
+
+  await header.click();
+  await expect(workspaceRow(page, project.workspaceId)).toHaveCount(0, { timeout: 10_000 });
+}
+
+async function switchToStatusGrouping(page: Page): Promise<void> {
+  await page.getByTestId("sidebar-display-preferences-menu").click();
+  await page.getByTestId("sidebar-grouping-status").click();
+  await expect(page.getByTestId("sidebar-status-list-scroll")).toBeVisible({ timeout: 10_000 });
+}
+
+// Status mode buckets workspaces by state rather than project, so the group holding this workspace
+// is discovered from the rows container it sits in rather than assumed.
+async function collapseStatusGroupContaining(page: Page, workspaceId: string): Promise<void> {
+  const rows = page
+    .locator('[data-testid^="sidebar-status-group-rows-"]')
+    .filter({ has: workspaceRow(page, workspaceId) });
+  await expect(rows).toHaveCount(1, { timeout: 30_000 });
+
+  const rowsTestId = await rows.getAttribute("data-testid");
+  const bucket = rowsTestId?.replace("sidebar-status-group-rows-", "");
+  expect(bucket).toBeTruthy();
+
+  await page.getByTestId(`sidebar-status-group-${bucket}`).click();
+  await expect(workspaceRow(page, workspaceId)).toHaveCount(0, { timeout: 10_000 });
+}
+
+function readSessionMessage(
+  message: string | Buffer,
+): { type?: unknown; requestId?: unknown } | null {
+  const raw = typeof message === "string" ? message : message.toString("utf8");
+  try {
+    const envelope = JSON.parse(raw) as { type?: unknown; message?: unknown };
+    if (envelope.type !== "session" || typeof envelope.message !== "object") {
+      return null;
+    }
+    return envelope.message as { type?: unknown; requestId?: unknown };
+  } catch {
+    return null;
+  }
+}
+
+const PIN_REJECTION_MESSAGE = "Pin rejected by test.";
+
+interface PinRpcGate {
+  /** Pin requests the client has sent so far. */
+  sentCount(): number;
+}
+
+// Proxies everything so the app boots against the real daemon, counting pin RPCs and optionally
+// rejecting the first `rejectFirst` of them. The count asserts how many pins one keypress actually
+// dispatched, which the rendered pin state cannot show — a toggle that fired twice lands back
+// where it started.
+async function installPinRpcGate(
+  page: Page,
+  options: { rejectFirst?: number } = {},
+): Promise<PinRpcGate> {
+  const rejectFirst = options.rejectFirst ?? 0;
+  let sent = 0;
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+
+    ws.onMessage((message) => {
+      const sessionMessage = readSessionMessage(message);
+      if (
+        sessionMessage?.type === "workspace.pin.set.request" &&
+        typeof sessionMessage.requestId === "string"
+      ) {
+        sent += 1;
+        if (sent <= rejectFirst) {
+          ws.send(
+            JSON.stringify({
+              type: "session",
+              message: {
+                type: "rpc_error",
+                payload: {
+                  requestId: sessionMessage.requestId,
+                  requestType: "workspace.pin.set.request",
+                  error: PIN_REJECTION_MESSAGE,
+                  code: "transport",
+                },
+              },
+            }),
+          );
+          return;
+        }
+      }
+
+      try {
+        server.send(message);
+      } catch {
+        // server socket already closed
+      }
+    });
+
+    server.onMessage((message) => {
+      try {
+        ws.send(message);
+      } catch {
+        // client socket already closed
+      }
+    });
+  });
+
+  return { sentCount: () => sent };
+}
+
+test.describe("Pin workspace shortcut", () => {
+  test("pins the active workspace while its project section is collapsed", async ({ page }) => {
+    const workspace = await seedWorkspace({ repoPrefix: "pin-shortcut-collapsed-" });
+
+    try {
+      await gotoAppShell(page);
+      await openWorkspace(page, workspace.workspaceId);
+      await collapseProjectSection(page, workspace);
+
+      await page.keyboard.press(PIN_SHORTCUT);
+
+      await expect(pinnedSection(page)).toBeVisible({ timeout: 10_000 });
+      await expect(
+        pinnedSection(page).getByTestId(
+          `sidebar-workspace-row-${getServerId()}:${workspace.workspaceId}`,
+        ),
+      ).toBeVisible();
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+
+  test("unpins the active workspace while the Pinned section is collapsed", async ({ page }) => {
+    const workspace = await seedWorkspace({ repoPrefix: "pin-shortcut-unpin-" });
+
+    try {
+      await gotoAppShell(page);
+      await openWorkspace(page, workspace.workspaceId);
+
+      await page.keyboard.press(PIN_SHORTCUT);
+      await expect(pinnedSection(page)).toBeVisible({ timeout: 10_000 });
+
+      await page.getByTestId("sidebar-pinned-section-header").click();
+      await expect(workspaceRow(page, workspace.workspaceId)).toHaveCount(0, { timeout: 10_000 });
+
+      await page.keyboard.press(PIN_SHORTCUT);
+
+      await expect(pinnedSection(page)).toHaveCount(0, { timeout: 10_000 });
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+
+  test("sends exactly one pin RPC per press when the row is rendered and selected", async ({
+    page,
+  }) => {
+    const workspace = await seedWorkspace({ repoPrefix: "pin-shortcut-expanded-" });
+
+    try {
+      const gate = await installPinRpcGate(page);
+
+      await gotoAppShell(page);
+      await openWorkspace(page, workspace.workspaceId);
+
+      await page.keyboard.press(PIN_SHORTCUT);
+      await expect(pinnedSection(page)).toBeVisible({ timeout: 10_000 });
+      // Counting frames catches a press that produces zero or two RPCs — a misfiring in-flight
+      // guard, or a second dispatch path. It cannot detect a duplicate handler registration:
+      // `keyboardActionDispatcher.dispatch` returns at the first handler that returns true, so a
+      // shadowed second handler is unobservable from outside by design.
+      expect(gate.sentCount()).toBe(1);
+
+      await page.keyboard.press(PIN_SHORTCUT);
+      await expect(pinnedSection(page)).toHaveCount(0, { timeout: 10_000 });
+      expect(gate.sentCount()).toBe(2);
+      await expect(workspaceRow(page, workspace.workspaceId)).toHaveCount(1);
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+
+  test("pins the active workspace while its status group is collapsed", async ({ page }) => {
+    const workspace = await seedWorkspace({ repoPrefix: "pin-shortcut-status-" });
+
+    try {
+      await gotoAppShell(page);
+      await openWorkspace(page, workspace.workspaceId);
+      await switchToStatusGrouping(page);
+      await collapseStatusGroupContaining(page, workspace.workspaceId);
+
+      await page.keyboard.press(PIN_SHORTCUT);
+
+      await expect(pinnedSection(page)).toBeVisible({ timeout: 10_000 });
+      await expect(
+        pinnedSection(page).getByTestId(
+          `sidebar-workspace-row-${getServerId()}:${workspace.workspaceId}`,
+        ),
+      ).toBeVisible();
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+
+  test("shows an error toast when the host rejects the pin, and the next press succeeds", async ({
+    page,
+  }) => {
+    const workspace = await seedWorkspace({ repoPrefix: "pin-shortcut-failure-" });
+
+    try {
+      const gate = await installPinRpcGate(page, { rejectFirst: 1 });
+
+      await gotoAppShell(page);
+      await openWorkspace(page, workspace.workspaceId);
+
+      await page.keyboard.press(PIN_SHORTCUT);
+
+      await expect(page.getByTestId("app-toast-message")).toContainText(PIN_REJECTION_MESSAGE, {
+        timeout: 10_000,
+      });
+      await expect(pinnedSection(page)).toHaveCount(0);
+      await expect(workspaceRow(page, workspace.workspaceId)).toHaveCount(1);
+
+      // The failure must leave the action usable: the in-flight guard has to release the key so a
+      // retry is not swallowed. Without that release the workspace is unpinnable for the session.
+      await page.keyboard.press(PIN_SHORTCUT);
+
+      await expect(pinnedSection(page)).toBeVisible({ timeout: 10_000 });
+      expect(gate.sentCount()).toBe(2);
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+});

packages/app/e2e/workspace-terminal-tab-rename.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from "./fixtures";
+import { test, expect, type Page } from "./fixtures";
 import { clickNewTerminal, gotoWorkspace } from "./helpers/launcher";
 import { renameModalInput, renameModalSubmit } from "./helpers/rename";
 import { seedWorkspace, type SeededWorkspace } from "./helpers/seed-client";
@@ -36,7 +36,52 @@ async function waitForCreatedTerminalId(workspace: SeededWorkspace): Promise<str
   return terminal.id;
 }
 
+async function cleanupTerminal(
+  workspace: SeededWorkspace,
+  terminalId: string | null,
+): Promise<void> {
+  if (terminalId) {
+    await workspace.client.killTerminal(terminalId).catch(() => undefined);
+  }
+  await workspace.cleanup();
+}
+
+async function readClipboard(page: Page): Promise<string> {
+  return page.evaluate(() => navigator.clipboard.readText());
+}
+
 test.describe("Workspace terminal tab rename", () => {
+  test("right-click copy terminal id writes the terminal id to the clipboard", async ({
+    context,
+    page,
+  }) => {
+    test.setTimeout(60_000);
+
+    const workspace = await seedWorkspace({ repoPrefix: "workspace-terminal-copy-id-" });
+    let terminalId: string | null = null;
+
+    try {
+      await context.grantPermissions(["clipboard-read", "clipboard-write"]);
+      await gotoWorkspace(page, workspace.workspaceId);
+      await clickNewTerminal(page);
+      terminalId = await waitForCreatedTerminalId(workspace);
+
+      const tab = page.getByTestId(`workspace-tab-terminal_${terminalId}`).first();
+      await expect(tab).toBeVisible({ timeout: 15_000 });
+
+      await tab.click({ button: "right" });
+      const copyTerminalId = page.getByTestId(
+        `workspace-tab-context-terminal_${terminalId}-copy-terminal-id`,
+      );
+      await expect(copyTerminalId).toBeVisible({ timeout: 10_000 });
+      await copyTerminalId.click();
+
+      await expect.poll(() => readClipboard(page)).toBe(terminalId);
+    } finally {
+      await cleanupTerminal(workspace, terminalId);
+    }
+  });
+
   test("right-click rename persists the terminal title and updates the tab label", async ({
     page,
   }) => {
@@ -74,10 +119,7 @@ test.describe("Workspace terminal tab rename", () => {
         .poll(() => fetchTerminalTitle(workspace, terminalId!))
         .toBe("My Renamed Terminal");
     } finally {
-      if (terminalId) {
-        await workspace.client.killTerminal(terminalId).catch(() => undefined);
-      }
-      await workspace.cleanup();
+      await cleanupTerminal(workspace, terminalId);
     }
   });
 });

packages/app/eas.json

@@ -19,6 +19,9 @@
       "channel": "production",
       "env": {
         "APP_VARIANT": "production"
+      },
+      "android": {
+        "resourceClass": "large"
       }
     },
     "production-apk": {

packages/app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/app",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "private": true,
   "main": "index.ts",
   "scripts": {

packages/app/src/agent-stream/history-start-pagination.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it } from "vitest";
+import {
+  abandonHistoryStartPaginationRequest,
+  createHistoryStartPaginationState,
+  evaluateHistoryStartPagination,
+  isHistoryStartLoadingOperation,
+  rearmHistoryStartPagination,
+  settleHistoryStartPagination,
+  type HistoryStartPaginationInput,
+} from "./history-start-pagination";
+
+const visibleHistoryStart: HistoryStartPaginationInput = {
+  distanceFromHistoryStart: 0,
+  hasOlderHistory: true,
+  isLoadingOlderHistory: false,
+  isReady: true,
+  progressKey: "epoch-1:20",
+};
+
+describe("history start pagination", () => {
+  it("waits for anchored page geometry before authorizing another page", () => {
+    const first = evaluateHistoryStartPagination(
+      createHistoryStartPaginationState(),
+      visibleHistoryStart,
+    );
+    const inFlight = evaluateHistoryStartPagination(first.state, {
+      ...visibleHistoryStart,
+      isLoadingOlderHistory: true,
+    });
+    const pageApplied = evaluateHistoryStartPagination(inFlight.state, {
+      ...visibleHistoryStart,
+      isLoadingOlderHistory: true,
+      progressKey: "epoch-1:10",
+    });
+
+    expect([first.shouldLoad, inFlight.shouldLoad, pageApplied.shouldLoad]).toEqual([
+      true,
+      false,
+      false,
+    ]);
+    expect(pageApplied.state).toEqual({ status: "settling", loadedProgressKey: "epoch-1:10" });
+  });
+
+  it("loads one page each time anchored geometry leaves and returns to history start", () => {
+    const first = evaluateHistoryStartPagination(
+      createHistoryStartPaginationState(),
+      visibleHistoryStart,
+    );
+    const pageApplied = evaluateHistoryStartPagination(first.state, {
+      ...visibleHistoryStart,
+      progressKey: "epoch-1:10",
+    });
+    const settledAway = settleHistoryStartPagination(pageApplied.state, {
+      ...visibleHistoryStart,
+      distanceFromHistoryStart: 300,
+      progressKey: "epoch-1:10",
+    });
+    const returned = evaluateHistoryStartPagination(settledAway.state, {
+      ...visibleHistoryStart,
+      progressKey: "epoch-1:10",
+    });
+
+    expect([
+      first.shouldLoad,
+      pageApplied.shouldLoad,
+      settledAway.shouldLoad,
+      returned.shouldLoad,
+    ]).toEqual([true, false, false, true]);
+  });
+
+  it("continues the same loading operation when anchored geometry remains at history start", () => {
+    const first = evaluateHistoryStartPagination(
+      createHistoryStartPaginationState(),
+      visibleHistoryStart,
+    );
+    const pageApplied = evaluateHistoryStartPagination(first.state, {
+      ...visibleHistoryStart,
+      progressKey: "epoch-1:10",
+    });
+    const continued = settleHistoryStartPagination(pageApplied.state, {
+      ...visibleHistoryStart,
+      progressKey: "epoch-1:10",
+    });
+
+    expect(continued.shouldLoad).toBe(true);
+    expect(isHistoryStartLoadingOperation(first.state)).toBe(true);
+    expect(isHistoryStartLoadingOperation(pageApplied.state)).toBe(true);
+    expect(isHistoryStartLoadingOperation(continued.state)).toBe(true);
+  });
+
+  it("latches a request that finishes without cursor progress", () => {
+    const first = evaluateHistoryStartPagination(
+      createHistoryStartPaginationState(),
+      visibleHistoryStart,
+    );
+    const inFlight = evaluateHistoryStartPagination(first.state, {
+      ...visibleHistoryStart,
+      isLoadingOlderHistory: true,
+    });
+    const finished = evaluateHistoryStartPagination(inFlight.state, visibleHistoryStart);
+    const duplicate = evaluateHistoryStartPagination(finished.state, visibleHistoryStart);
+    const away = evaluateHistoryStartPagination(duplicate.state, {
+      ...visibleHistoryStart,
+      distanceFromHistoryStart: 300,
+    });
+
+    expect(finished.state).toEqual({ status: "latched" });
+    expect([finished.shouldLoad, duplicate.shouldLoad, away.shouldLoad]).toEqual([
+      false,
+      false,
+      false,
+    ]);
+    expect(away.state).toEqual({ status: "ready" });
+  });
+
+  it("allows another user attempt after a request finishes without progress", () => {
+    const first = evaluateHistoryStartPagination(
+      createHistoryStartPaginationState(),
+      visibleHistoryStart,
+    );
+    const inFlight = evaluateHistoryStartPagination(first.state, {
+      ...visibleHistoryStart,
+      isLoadingOlderHistory: true,
+    });
+    const failed = evaluateHistoryStartPagination(inFlight.state, visibleHistoryStart);
+    const retried = evaluateHistoryStartPagination(
+      rearmHistoryStartPagination(failed.state),
+      visibleHistoryStart,
+    );
+
+    expect(failed.state).toEqual({ status: "latched" });
+    expect(retried.shouldLoad).toBe(true);
+  });
+
+  it("latches an attempt that becomes invalid before entering flight", () => {
+    const requested = evaluateHistoryStartPagination(
+      createHistoryStartPaginationState(),
+      visibleHistoryStart,
+    );
+
+    expect(abandonHistoryStartPaginationRequest(requested.state, "epoch-1:20")).toEqual({
+      status: "latched",
+    });
+  });
+
+  it("does not mistake repeated edge observations for a finished request", () => {
+    const first = evaluateHistoryStartPagination(
+      createHistoryStartPaginationState(),
+      visibleHistoryStart,
+    );
+    const repeated = evaluateHistoryStartPagination(first.state, visibleHistoryStart);
+
+    expect(repeated.state).toBe(first.state);
+    expect(repeated.shouldLoad).toBe(false);
+  });
+
+  it("waits while history loading is unavailable or already active", () => {
+    const state = createHistoryStartPaginationState();
+
+    expect([
+      evaluateHistoryStartPagination(state, { ...visibleHistoryStart, isReady: false }).shouldLoad,
+      evaluateHistoryStartPagination(state, { ...visibleHistoryStart, hasOlderHistory: false })
+        .shouldLoad,
+      evaluateHistoryStartPagination(state, { ...visibleHistoryStart, isLoadingOlderHistory: true })
+        .shouldLoad,
+      evaluateHistoryStartPagination(state, { ...visibleHistoryStart, progressKey: null })
+        .shouldLoad,
+    ]).toEqual([false, false, false, false]);
+  });
+});

packages/app/src/agent-stream/history-start-pagination.ts

@@ -0,0 +1,134 @@
+export const HISTORY_START_THRESHOLD_PX = 96;
+
+export type HistoryStartPaginationState =
+  | { status: "ready" }
+  | { status: "loading"; requestedProgressKey: string; requestObserved: boolean }
+  | { status: "settling"; loadedProgressKey: string }
+  | { status: "latched" };
+
+export interface HistoryStartPaginationInput {
+  distanceFromHistoryStart: number;
+  hasOlderHistory: boolean;
+  isLoadingOlderHistory: boolean;
+  isReady: boolean;
+  progressKey: string | null;
+}
+
+export interface HistoryStartPaginationTransition {
+  state: HistoryStartPaginationState;
+  shouldLoad: boolean;
+}
+
+export function createHistoryStartPaginationState(): HistoryStartPaginationState {
+  return { status: "ready" };
+}
+
+export function isHistoryStartLoadingOperation(state: HistoryStartPaginationState): boolean {
+  return state.status === "loading" || state.status === "settling";
+}
+
+export function rearmHistoryStartPagination(
+  state: HistoryStartPaginationState,
+): HistoryStartPaginationState {
+  return state.status === "latched" ? { status: "ready" } : state;
+}
+
+export function abandonHistoryStartPaginationRequest(
+  state: HistoryStartPaginationState,
+  requestedProgressKey: string,
+): HistoryStartPaginationState {
+  if (
+    state.status !== "loading" ||
+    state.requestObserved ||
+    state.requestedProgressKey !== requestedProgressKey
+  ) {
+    return state;
+  }
+  return { status: "latched" };
+}
+
+export function evaluateHistoryStartPagination(
+  state: HistoryStartPaginationState,
+  input: HistoryStartPaginationInput,
+): HistoryStartPaginationTransition {
+  if (state.status === "loading") {
+    if (input.progressKey !== null && input.progressKey !== state.requestedProgressKey) {
+      return {
+        state: { status: "settling", loadedProgressKey: input.progressKey },
+        shouldLoad: false,
+      };
+    }
+    if (input.isLoadingOlderHistory && !state.requestObserved) {
+      return { state: { ...state, requestObserved: true }, shouldLoad: false };
+    }
+    if (!input.isLoadingOlderHistory && !input.hasOlderHistory) {
+      return { state: { status: "latched" }, shouldLoad: false };
+    }
+    if (
+      state.requestObserved &&
+      !input.isLoadingOlderHistory &&
+      input.progressKey === state.requestedProgressKey
+    ) {
+      return { state: { status: "latched" }, shouldLoad: false };
+    }
+    return { state, shouldLoad: false };
+  }
+
+  if (state.status === "settling") {
+    return { state, shouldLoad: false };
+  }
+
+  const isAtHistoryStart = input.distanceFromHistoryStart <= HISTORY_START_THRESHOLD_PX;
+  if (!isAtHistoryStart) {
+    return state.status === "ready"
+      ? { state, shouldLoad: false }
+      : { state: { status: "ready" }, shouldLoad: false };
+  }
+  if (
+    state.status === "latched" ||
+    !input.isReady ||
+    !input.hasOlderHistory ||
+    input.isLoadingOlderHistory ||
+    input.progressKey === null
+  ) {
+    return { state, shouldLoad: false };
+  }
+  return {
+    state: {
+      status: "loading",
+      requestedProgressKey: input.progressKey,
+      requestObserved: false,
+    },
+    shouldLoad: true,
+  };
+}
+
+export function settleHistoryStartPagination(
+  state: HistoryStartPaginationState,
+  input: HistoryStartPaginationInput,
+): HistoryStartPaginationTransition {
+  if (state.status !== "settling") {
+    return { state, shouldLoad: false };
+  }
+  const isAtHistoryStart = input.distanceFromHistoryStart <= HISTORY_START_THRESHOLD_PX;
+  if (
+    !isAtHistoryStart ||
+    !input.isReady ||
+    !input.hasOlderHistory ||
+    input.isLoadingOlderHistory ||
+    input.progressKey === null
+  ) {
+    return {
+      state: isAtHistoryStart ? { status: "latched" } : { status: "ready" },
+      shouldLoad: false,
+    };
+  }
+  return {
+    state: {
+      status: "loading",
+      requestedProgressKey: input.progressKey,
+      requestObserved: false,
+    },
+    shouldLoad: true,
+  };
+}

packages/app/src/agent-stream/history-start-settle-scheduler.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it, vi } from "vitest";
+import { createHistoryStartSettleScheduler } from "./history-start-settle-scheduler";
+
+describe("history start settle scheduler", () => {
+  it("does not restart its countdown when geometry keeps changing", () => {
+    const frames = new Map<number, () => void>();
+    let nextFrameId = 1;
+    const onFrame = vi.fn();
+    const onSettle = vi.fn();
+    const scheduler = createHistoryStartSettleScheduler({
+      settleFrames: 2,
+      requestFrame(callback) {
+        const id = nextFrameId;
+        nextFrameId += 1;
+        frames.set(id, callback);
+        return id;
+      },
+      cancelFrame: (id) => frames.delete(id),
+      isSettling: () => true,
+      isLoading: () => false,
+      onFrame,
+      onSettle,
+    });
+    const runNextFrame = () => {
+      const next = frames.entries().next().value as [number, () => void] | undefined;
+      if (!next) {
+        throw new Error("Expected a scheduled settlement frame");
+      }
+      frames.delete(next[0]);
+      next[1]();
+    };
+
+    scheduler.schedule();
+    scheduler.schedule();
+    runNextFrame();
+    scheduler.schedule();
+    runNextFrame();
+    scheduler.schedule();
+    runNextFrame();
+
+    expect(onSettle).toHaveBeenCalledTimes(1);
+    expect(onFrame).toHaveBeenCalledTimes(3);
+    expect(frames.size).toBe(0);
+  });
+});

packages/app/src/agent-stream/history-start-settle-scheduler.ts

@@ -0,0 +1,52 @@
+export interface HistoryStartSettleScheduler {
+  schedule(): void;
+  cancel(): void;
+}
+
+export function createHistoryStartSettleScheduler(input: {
+  settleFrames: number;
+  requestFrame: (callback: () => void) => number;
+  cancelFrame: (id: number) => void;
+  isSettling: () => boolean;
+  isLoading: () => boolean;
+  onFrame?: () => void;
+  onSettle: () => void;
+}): HistoryStartSettleScheduler {
+  let frameId: number | null = null;
+  let remainingFrames = 0;
+
+  const tick = () => {
+    input.onFrame?.();
+    if (!input.isSettling()) {
+      frameId = null;
+      remainingFrames = 0;
+      return;
+    }
+    if (input.isLoading() || remainingFrames > 0) {
+      if (!input.isLoading()) {
+        remainingFrames -= 1;
+      }
+      frameId = input.requestFrame(tick);
+      return;
+    }
+    frameId = null;
+    input.onSettle();
+  };
+
+  return {
+    schedule() {
+      if (frameId !== null) {
+        return;
+      }
+      remainingFrames = input.settleFrames;
+      frameId = input.requestFrame(tick);
+    },
+    cancel() {
+      if (frameId !== null) {
+        input.cancelFrame(frameId);
+      }
+      frameId = null;
+      remainingFrames = 0;
+    },
+  };
+}

packages/app/src/agent-stream/scroll-keyboard-dismiss/model.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest";
+import {
+  beginDrag,
+  IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE,
+  recordScroll,
+  releaseDrag,
+  type ScrollKeyboardDismissEvent,
+  type ScrollKeyboardDismissGesture,
+} from "./model";
+
+interface Point {
+  ts: number;
+  y: number;
+  nativeTs?: number | null;
+}
+
+function event(point: Point): ScrollKeyboardDismissEvent {
+  return {
+    timeStamp: point.ts,
+    nativeEvent: {
+      contentOffset: { y: point.y },
+      ...(point.nativeTs === null ? {} : { timestamp: point.nativeTs ?? point.ts }),
+    },
+  };
+}
+
+function dragThrough(start: Point, points: Point[]): ScrollKeyboardDismissGesture {
+  return points.reduce(
+    (gesture, point) => recordScroll(gesture, event(point)),
+    beginDrag(event(start)),
+  );
+}
+
+function shouldDismiss(start: Point, points: Point[], release: Point): boolean {
+  return releaseDrag(dragThrough(start, points), event(release)).shouldDismiss;
+}
+
+describe("scroll keyboard dismissal", () => {
+  it("keeps the keyboard up for a slow read-scroll", () => {
+    expect(
+      shouldDismiss(
+        { ts: 1000, y: 0 },
+        [
+          { ts: 1040, y: 8 },
+          { ts: 1080, y: 16 },
+          { ts: 1120, y: 24 },
+        ],
+        { 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(
+      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(
+      false,
+    );
+  });
+
+  it("keeps a fast-but-decelerating drag below the release threshold", () => {
+    expect(
+      shouldDismiss(
+        { ts: 1000, y: 0 },
+        [
+          { ts: 1100, y: 500 },
+          { ts: 1200, y: 590 },
+          { ts: 1270, y: 598 },
+        ],
+        { 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);
+  });
+
+  it("steps back a sample when release lands immediately after one", () => {
+    expect(
+      shouldDismiss(
+        { ts: 1000, y: 0 },
+        [
+          { ts: 1040, y: 120 },
+          { ts: 1075, y: 225 },
+        ],
+        { 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);
+  });
+
+  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,
+    );
+  });
+
+  it("uses native gesture time when delayed callbacks arrive in a burst", () => {
+    expect(
+      shouldDismiss(
+        { ts: 5000, nativeTs: 1000, y: 0 },
+        [
+          { ts: 5001, nativeTs: 1200, y: 40 },
+          { ts: 5002, nativeTs: 1400, y: 80 },
+        ],
+        { 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 }], {
+        ts: 1080,
+        nativeTs: null,
+        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 }));
+    expect(idle).toBe(IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE);
+    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 }));
+    expect(release.gesture).toBe(IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE);
+  });
+});

packages/app/src/agent-stream/scroll-keyboard-dismiss/model.ts

@@ -0,0 +1,124 @@
+/**
+ * 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
+ * release instead of introducing a competing pan recognizer.
+ */
+
+const DISMISS_VELOCITY_POINTS_PER_MS = 1.5;
+const RELEASE_SAMPLE_MIN_MS = 30;
+
+/**
+ * The subset of a native scroll event used by the classifier. React Native's
+ * type omits `nativeEvent.timestamp`, although iOS and Android both send it.
+ */
+export interface ScrollKeyboardDismissEvent {
+  timeStamp: number;
+  nativeEvent: {
+    contentOffset: { y: number };
+    timestamp?: number;
+  };
+}
+
+interface DragSamples {
+  startTs: number;
+  startY: number;
+  sampleTs: number;
+  sampleY: number;
+  previousSampleTs: number;
+  previousSampleY: number;
+}
+
+export type ScrollKeyboardDismissGesture =
+  | { phase: "idle" }
+  | { phase: "dragging"; samples: DragSamples };
+
+export const IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE: ScrollKeyboardDismissGesture = Object.freeze({
+  phase: "idle",
+});
+
+function resolveEventTimeMs(event: ScrollKeyboardDismissEvent): number {
+  const nativeTimestamp = event.nativeEvent.timestamp;
+  if (typeof nativeTimestamp === "number" && nativeTimestamp > 0) {
+    return nativeTimestamp;
+  }
+  return event.timeStamp;
+}
+
+export function beginDrag(event: ScrollKeyboardDismissEvent): ScrollKeyboardDismissGesture {
+  const timestamp = resolveEventTimeMs(event);
+  const offsetY = event.nativeEvent.contentOffset.y;
+  return {
+    phase: "dragging",
+    samples: {
+      startTs: timestamp,
+      startY: offsetY,
+      sampleTs: timestamp,
+      sampleY: offsetY,
+      previousSampleTs: 0,
+      previousSampleY: 0,
+    },
+  };
+}
+
+export function recordScroll(
+  gesture: ScrollKeyboardDismissGesture,
+  event: ScrollKeyboardDismissEvent,
+): ScrollKeyboardDismissGesture {
+  if (gesture.phase === "idle") {
+    return gesture;
+  }
+
+  const timestamp = resolveEventTimeMs(event);
+  if (timestamp - gesture.samples.sampleTs < RELEASE_SAMPLE_MIN_MS) {
+    return gesture;
+  }
+
+  const { samples } = gesture;
+  return {
+    phase: "dragging",
+    samples: {
+      startTs: samples.startTs,
+      startY: samples.startY,
+      sampleTs: timestamp,
+      sampleY: event.nativeEvent.contentOffset.y,
+      previousSampleTs: samples.sampleTs,
+      previousSampleY: samples.sampleY,
+    },
+  };
+}
+
+export function releaseDrag(
+  gesture: ScrollKeyboardDismissGesture,
+  event: ScrollKeyboardDismissEvent,
+): { gesture: ScrollKeyboardDismissGesture; shouldDismiss: boolean } {
+  if (gesture.phase === "idle") {
+    return { gesture, shouldDismiss: false };
+  }
+
+  const releaseTs = resolveEventTimeMs(event);
+  const releaseY = event.nativeEvent.contentOffset.y;
+  const { samples } = gesture;
+
+  // The release event carries the gesture's true endpoint. The final onScroll
+  // event can still be stale when a short flick lands.
+  let spanStartTs = samples.startTs;
+  let spanStartY = samples.startY;
+  if (releaseTs - samples.sampleTs >= RELEASE_SAMPLE_MIN_MS) {
+    spanStartTs = samples.sampleTs;
+    spanStartY = samples.sampleY;
+  } else if (samples.previousSampleTs > 0) {
+    spanStartTs = samples.previousSampleTs;
+    spanStartY = samples.previousSampleY;
+  }
+
+  const spanDurationMs = releaseTs - spanStartTs;
+  const releaseVelocity = spanDurationMs > 0 ? (releaseY - spanStartY) / spanDurationMs : 0;
+
+  return {
+    gesture: IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE,
+    shouldDismiss: releaseVelocity > DISMISS_VELOCITY_POINTS_PER_MS,
+  };
+}

packages/app/src/agent-stream/scroll-keyboard-dismiss/use-scroll-keyboard-dismiss.ts

@@ -0,0 +1,57 @@
+import { useRef } from "react";
+import {
+  Keyboard,
+  TextInput,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+} from "react-native";
+import { useKeyboardShift } from "@/hooks/keyboard-shift-context";
+import { useStableEvent } from "@/hooks/use-stable-event";
+import {
+  beginDrag,
+  IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE,
+  recordScroll,
+  releaseDrag,
+} from "./model";
+
+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
+ * calls removes the feature completely.
+ */
+export function useScrollKeyboardDismiss() {
+  const { shift } = useKeyboardShift();
+  const gestureRef = useRef(IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE);
+
+  const onScrollBeginDrag = useStableEvent((event: ScrollEvent) => {
+    gestureRef.current = beginDrag(event);
+  });
+
+  const onScroll = useStableEvent((event: ScrollEvent) => {
+    gestureRef.current = recordScroll(gestureRef.current, event);
+  });
+
+  const onScrollEndDrag = useStableEvent((event: ScrollEvent) => {
+    const release = releaseDrag(gestureRef.current, event);
+    gestureRef.current = release.gesture;
+
+    // `shift` is the app's UI-thread-derived keyboard inset. Besides avoiding a
+    // second calculation on JS, this prevents a hardware keyboard's focused
+    // composer from being blurred when no software keyboard occupies space.
+    if (!release.shouldDismiss || shift.value <= 0) {
+      return;
+    }
+
+    // Keep blur and dismiss paired: this exact sequence was validated on a
+    // physical Android device to clear both input focus and the IME inset.
+    const focusedInput = TextInput.State.currentlyFocusedInput();
+    if (focusedInput) {
+      TextInput.State.blurTextInput(focusedInput);
+    }
+    Keyboard.dismiss();
+  });
+
+  return { onScroll, onScrollBeginDrag, onScrollEndDrag };
+}

packages/app/src/agent-stream/strategy-native.tsx

@@ -9,7 +9,6 @@ import {
 } from "react";
 import {
   FlatList,
-  ActivityIndicator,
   Keyboard,
   Platform,
   View,
@@ -17,22 +16,53 @@ import {
   type ListRenderItemInfo,
   type NativeScrollEvent,
   type NativeSyntheticEvent,
+  type ViewStyle,
 } from "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 { useBottomAnchorController } from "./bottom-anchor-controller";
+import { useScrollKeyboardDismiss } from "./scroll-keyboard-dismiss/use-scroll-keyboard-dismiss";
 import type { StreamRenderInput, StreamStrategy, StreamViewportHandle } from "./strategy";
 import {
   createStreamStrategy,
   isNearBottomForStreamRenderStrategy,
   resolveBottomAnchorTransportBehavior,
 } from "./strategy";
+import {
+  abandonHistoryStartPaginationRequest,
+  createHistoryStartPaginationState,
+  evaluateHistoryStartPagination,
+  isHistoryStartLoadingOperation,
+  rearmHistoryStartPagination,
+  settleHistoryStartPagination,
+  type HistoryStartPaginationInput,
+  type HistoryStartPaginationTransition,
+} from "./history-start-pagination";
+import {
+  createHistoryStartSettleScheduler,
+  type HistoryStartSettleScheduler,
+} from "./history-start-settle-scheduler";
 
 const DEFAULT_MAINTAIN_VISIBLE_CONTENT_POSITION = Object.freeze({
   minIndexForVisible: 0,
   autoscrollToTopThreshold: 0,
 });
-const HISTORY_START_THRESHOLD_PX = 96;
+
+const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
+const foregroundMutedColorMapping = (theme: Theme) => ({
+  color: theme.colors.foregroundMuted,
+});
+const historyStartSlotStyle: ViewStyle = {
+  alignItems: "center",
+  justifyContent: "center",
+  minHeight: 32,
+  paddingTop: 4,
+  paddingBottom: 8,
+};
+const HISTORY_START_SETTLE_FRAMES = 2;
 
 interface HistoryRowDisplayVariants {
   regular?: StreamItem;
@@ -72,6 +102,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     onNearHistoryStart,
     isLoadingOlderHistory,
     hasOlderHistory,
+    olderHistoryProgressKey,
     scrollEnabled,
     listStyle,
     baseListContentContainerStyle,
@@ -90,11 +121,17 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
   });
   const scrollOffsetYRef = useRef(0);
   const isUserScrollActiveRef = useRef(false);
+  const scrollKeyboardDismiss = useScrollKeyboardDismiss();
   const userScrollEndFrameIdRef = useRef<number | null>(null);
   const programmaticScrollEventBudgetRef = useRef(0);
   const [isNativeViewportSettling, setIsNativeViewportSettling] = useState(false);
   const nativeViewportSettlingFrameIdRef = useRef<number | null>(null);
   const historyStartReadyRef = useRef(false);
+  const [historyStartPaginationState, setHistoryStartPaginationState] = useState(
+    createHistoryStartPaginationState,
+  );
+  const historyStartPaginationStateRef = useRef(historyStartPaginationState);
+  const historyStartSettleSchedulerRef = useRef<HistoryStartSettleScheduler | null>(null);
 
   const historyItems = useMemo(() => {
     if (segments.historyVirtualized.length === 0) {
@@ -123,6 +160,75 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       ),
     [displayStateHistoryRows, historyRowRevision?.contentById],
   );
+  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,
+      hasOlderHistory,
+      isLoadingOlderHistory,
+      isReady: historyStartReadyRef.current && hasMeasuredViewport,
+      progressKey: olderHistoryProgressKey,
+    };
+  });
+  const applyHistoryStartPaginationTransition = useStableEvent(
+    (transition: HistoryStartPaginationTransition) => {
+      const previousState = historyStartPaginationStateRef.current;
+      historyStartPaginationStateRef.current = transition.state;
+      if (transition.state !== previousState) {
+        setHistoryStartPaginationState(transition.state);
+      }
+      if (transition.shouldLoad) {
+        const requestedProgressKey = olderHistoryProgressKey;
+        if (requestedProgressKey === null) {
+          return;
+        }
+        void (async () => {
+          const started = await onNearHistoryStart();
+          if (started === true) {
+            return;
+          }
+          applyHistoryStartPaginationTransition({
+            state: abandonHistoryStartPaginationRequest(
+              historyStartPaginationStateRef.current,
+              requestedProgressKey,
+            ),
+            shouldLoad: false,
+          });
+        })();
+      }
+    },
+  );
+  const evaluateHistoryStart = useStableEvent(() => {
+    const transition = evaluateHistoryStartPagination(
+      historyStartPaginationStateRef.current,
+      getHistoryStartPaginationInput(),
+    );
+    applyHistoryStartPaginationTransition(transition);
+  });
+  const scheduleHistoryStartSettle = useStableEvent(() => {
+    let scheduler = historyStartSettleSchedulerRef.current;
+    if (!scheduler) {
+      scheduler = createHistoryStartSettleScheduler({
+        settleFrames: HISTORY_START_SETTLE_FRAMES,
+        requestFrame: requestAnimationFrame,
+        cancelFrame: cancelAnimationFrame,
+        isSettling: () => historyStartPaginationStateRef.current.status === "settling",
+        isLoading: () => getHistoryStartPaginationInput().isLoadingOlderHistory,
+        onSettle: () => {
+          const transition = settleHistoryStartPagination(
+            historyStartPaginationStateRef.current,
+            getHistoryStartPaginationInput(),
+          );
+          applyHistoryStartPaginationTransition(transition);
+        },
+      });
+      historyStartSettleSchedulerRef.current = scheduler;
+    }
+    scheduler.schedule();
+  });
 
   const clearNativeViewportSettling = useCallback(() => {
     if (nativeViewportSettlingFrameIdRef.current !== null) {
@@ -222,14 +328,20 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     clearNativeViewportSettling();
     setIsNativeViewportSettling(false);
     historyStartReadyRef.current = false;
+    const initialHistoryStartState = createHistoryStartPaginationState();
+    historyStartPaginationStateRef.current = initialHistoryStartState;
+    setHistoryStartPaginationState(initialHistoryStartState);
     const frame = requestAnimationFrame(() => {
       historyStartReadyRef.current = true;
+      evaluateHistoryStart();
     });
     return () => {
       cancelAnimationFrame(frame);
       clearPendingUserScrollEnd();
+      historyStartSettleSchedulerRef.current?.cancel();
+      historyStartSettleSchedulerRef.current = null;
     };
-  }, [agentId, clearNativeViewportSettling, clearPendingUserScrollEnd]);
+  }, [agentId, clearNativeViewportSettling, clearPendingUserScrollEnd, evaluateHistoryStart]);
 
   useEffect(() => {
     const keyboardEvents = [
@@ -295,6 +407,8 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
     const previousOffsetY = scrollOffsetYRef.current;
     scrollOffsetYRef.current = contentOffset.y;
+    scrollKeyboardDismiss.onScroll(event);
+
     streamViewportMetricsRef.current = {
       contentHeight: Math.max(0, contentSize.height),
       viewportWidth: Math.max(0, layoutMeasurement.width),
@@ -308,17 +422,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     const nearBottom = isScrollEventNearBottom(event);
     onNearBottomChange(nearBottom);
 
-    const distanceFromOldestEdge =
-      streamViewportMetricsRef.current.contentHeight -
-      streamViewportMetricsRef.current.viewportHeight -
-      contentOffset.y;
-    if (
-      historyStartReadyRef.current &&
-      hasOlderHistory &&
-      distanceFromOldestEdge <= HISTORY_START_THRESHOLD_PX
-    ) {
-      onNearHistoryStart();
-    }
+    evaluateHistoryStart();
 
     if (
       !isUserScrollActiveRef.current &&
@@ -335,16 +439,25 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     }
   });
 
-  const handleScrollBeginDrag = useStableEvent(() => {
+  const handleScrollBeginDrag = useStableEvent((event: NativeSyntheticEvent<NativeScrollEvent>) => {
     clearPendingUserScrollEnd();
     isUserScrollActiveRef.current = true;
+    scrollKeyboardDismiss.onScrollBeginDrag(event);
     bottomAnchorController.beginUserScroll();
+    const rearmed = rearmHistoryStartPagination(historyStartPaginationStateRef.current);
+    if (rearmed !== historyStartPaginationStateRef.current) {
+      historyStartPaginationStateRef.current = rearmed;
+      setHistoryStartPaginationState(rearmed);
+      evaluateHistoryStart();
+    }
   });
 
   // Defer drag end so momentum can take ownership, but capture the terminal
   // gesture position now because layout may move the viewport in the meantime.
   const handleScrollEndDrag = useStableEvent((event: NativeSyntheticEvent<NativeScrollEvent>) => {
     const isNearBottom = isScrollEventNearBottom(event);
+    scrollKeyboardDismiss.onScrollEndDrag(event);
+
     clearPendingUserScrollEnd();
     userScrollEndFrameIdRef.current = requestAnimationFrame(() => {
       userScrollEndFrameIdRef.current = null;
@@ -359,6 +472,11 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
 
   const handleMomentumScrollEnd = useStableEvent(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      // Android can emit momentum-end after a programmatic anchor correction.
+      // Only momentum that still owns the user gesture may settle scroll intent.
+      if (!isUserScrollActiveRef.current) {
+        return;
+      }
       const isNearBottom = isScrollEventNearBottom(event);
       clearPendingUserScrollEnd();
       isUserScrollActiveRef.current = false;
@@ -390,6 +508,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       previousViewportHeight,
       viewportHeight,
     });
+    evaluateHistoryStart();
   });
 
   const handleContentSizeChange = useStableEvent((_width: number, height: number) => {
@@ -405,8 +524,25 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       previousContentHeight,
       contentHeight: nextContentHeight,
     });
+    evaluateHistoryStart();
+    if (historyStartPaginationStateRef.current.status === "settling") {
+      scheduleHistoryStartSettle();
+    }
   });
 
+  useEffect(() => {
+    evaluateHistoryStart();
+    if (historyStartPaginationStateRef.current.status === "settling") {
+      scheduleHistoryStartSettle();
+    }
+  }, [
+    evaluateHistoryStart,
+    hasOlderHistory,
+    isLoadingOlderHistory,
+    olderHistoryProgressKey,
+    scheduleHistoryStartSettle,
+  ]);
+
   const renderItem = useStableEvent(
     ({ item, index }: ListRenderItemInfo<StreamItem>): ReactElement | null => {
       const rendered = renderHistoryMountedRow(item, index, historyItems);
@@ -446,15 +582,21 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
   ]);
 
   const historyFooterContent = useMemo(() => {
-    if (!isLoadingOlderHistory) {
+    const isLoadingOperation = isHistoryStartLoadingOperation(historyStartPaginationState);
+    if (!hasOlderHistory && !isLoadingOperation) {
       return null;
     }
     return (
-      <View testID="load-older-history-spinner">
-        <ActivityIndicator size="small" />
+      <View
+        style={historyStartSlotStyle}
+        testID={isLoadingOperation ? "load-older-history-spinner" : undefined}
+      >
+        {isLoadingOperation ? (
+          <ThemedLoadingSpinner size="small" uniProps={foregroundMutedColorMapping} />
+        ) : null}
       </View>
     );
-  }, [isLoadingOlderHistory]);
+  }, [hasOlderHistory, historyStartPaginationState]);
 
   // RN's FlatList strictMode keeps its internal renderItem wrapper stable when
   // data or the live header changes, preserving the row identities above.

packages/app/src/agent-stream/strategy-web.test.tsx

@@ -130,9 +130,10 @@ describe("createWebStreamStrategy", () => {
             routeBottomAnchorRequest: null,
             isAuthoritativeHistoryReady: true,
             onNearBottomChange: vi.fn(),
-            onNearHistoryStart: vi.fn(),
+            onNearHistoryStart: vi.fn().mockReturnValue(true),
             isLoadingOlderHistory: false,
             hasOlderHistory: false,
+            olderHistoryProgressKey: null,
             scrollEnabled: true,
             listStyle: null,
             baseListContentContainerStyle: null,
@@ -173,9 +174,10 @@ describe("createWebStreamStrategy", () => {
       routeBottomAnchorRequest: null,
       isAuthoritativeHistoryReady: true,
       onNearBottomChange: vi.fn(),
-      onNearHistoryStart: vi.fn(),
+      onNearHistoryStart: vi.fn().mockReturnValue(true),
       isLoadingOlderHistory: false,
       hasOlderHistory: false,
+      olderHistoryProgressKey: null,
       scrollEnabled: true,
       listStyle: null,
       baseListContentContainerStyle: null,
@@ -228,9 +230,10 @@ describe("createWebStreamStrategy", () => {
           routeBottomAnchorRequest: null,
           isAuthoritativeHistoryReady: true,
           onNearBottomChange: vi.fn(),
-          onNearHistoryStart: vi.fn(),
+          onNearHistoryStart: vi.fn().mockReturnValue(true),
           isLoadingOlderHistory: false,
           hasOlderHistory: false,
+          olderHistoryProgressKey: null,
           scrollEnabled: true,
           listStyle: null,
           baseListContentContainerStyle: null,
@@ -282,47 +285,52 @@ describe("createWebStreamStrategy", () => {
     expect(scrollTo).not.toHaveBeenCalled();
   });
 
-  it("fires near-history-start when the user scrolls near the top", async () => {
+  it("waits for bottom anchoring before evaluating a delayed initial tail", async () => {
+    HTMLElement.prototype.scrollTo = vi.fn(function (
+      this: HTMLElement,
+      options?: ScrollToOptions | number,
+      y?: number,
+    ) {
+      const top = typeof options === "object" ? (options.top ?? 0) : (y ?? 0);
+      Object.defineProperty(this, "scrollTop", { configurable: true, value: top });
+    });
     const strategy = createWebStreamStrategy({ isMobileBreakpoint: true });
     const viewportRef = React.createRef<StreamViewportHandle>();
-    const onNearHistoryStart = vi.fn();
+    const onNearHistoryStart = vi.fn().mockReturnValue(true);
+    const renderInput = {
+      agentId: "agent",
+      boundary: {
+        hasVirtualizedHistory: false,
+        hasMountedHistory: false,
+        hasLiveHead: false,
+      },
+      renderers: createRenderers(vi.fn()),
+      listEmptyComponent: null,
+      viewportRef,
+      routeBottomAnchorRequest: null,
+      isAuthoritativeHistoryReady: true,
+      onNearBottomChange: vi.fn(),
+      onNearHistoryStart,
+      isLoadingOlderHistory: false,
+      hasOlderHistory: false,
+      olderHistoryProgressKey: null,
+      scrollEnabled: true,
+      listStyle: null,
+      baseListContentContainerStyle: null,
+      forwardListContentContainerStyle: null,
+    };
     container = document.createElement("div");
     document.body.appendChild(container);
     root = createRoot(container);
 
     act(() => {
       root?.render(
-        <>
-          {strategy.render({
-            agentId: "agent",
-            segments: {
-              historyVirtualized: [],
-              historyMounted: [userMessage(1), userMessage(2)],
-              liveHead: [],
-            },
-            boundary: {
-              hasVirtualizedHistory: false,
-              hasMountedHistory: true,
-              hasLiveHead: false,
-            },
-            renderers: createRenderers(vi.fn()),
-            listEmptyComponent: null,
-            viewportRef,
-            routeBottomAnchorRequest: null,
-            isAuthoritativeHistoryReady: true,
-            onNearBottomChange: vi.fn(),
-            onNearHistoryStart,
-            isLoadingOlderHistory: false,
-            hasOlderHistory: true,
-            scrollEnabled: true,
-            listStyle: null,
-            baseListContentContainerStyle: null,
-            forwardListContentContainerStyle: null,
-          })}
-        </>,
+        strategy.render({
+          ...renderInput,
+          segments: { historyVirtualized: [], historyMounted: [], liveHead: [] },
+        }),
       );
     });
-
     await act(async () => {
       await new Promise((resolve) => requestAnimationFrame(resolve));
     });
@@ -333,13 +341,33 @@ describe("createWebStreamStrategy", () => {
     }
     Object.defineProperty(scrollContainer, "clientHeight", { configurable: true, value: 400 });
     Object.defineProperty(scrollContainer, "scrollHeight", { configurable: true, value: 1200 });
-    Object.defineProperty(scrollContainer, "scrollTop", { configurable: true, value: 64 });
+    Object.defineProperty(scrollContainer, "scrollTop", { configurable: true, value: 0 });
 
     act(() => {
-      scrollContainer?.dispatchEvent(new Event("scroll"));
+      root?.render(
+        strategy.render({
+          ...renderInput,
+          segments: {
+            historyVirtualized: [],
+            historyMounted: [userMessage(1), userMessage(2)],
+            liveHead: [],
+          },
+          boundary: {
+            hasVirtualizedHistory: false,
+            hasMountedHistory: true,
+            hasLiveHead: false,
+          },
+          hasOlderHistory: true,
+          olderHistoryProgressKey: "epoch-1:20",
+        }),
+      );
     });
 
-    expect(onNearHistoryStart).toHaveBeenCalledTimes(1);
+    expect(onNearHistoryStart).not.toHaveBeenCalled();
+    await act(async () => {
+      await new Promise((resolve) => requestAnimationFrame(resolve));
+    });
+    expect(onNearHistoryStart).not.toHaveBeenCalled();
   });
 
   it("keeps initial route entry anchored when delayed route readiness arrives before user scroll", async () => {
@@ -375,9 +403,10 @@ describe("createWebStreamStrategy", () => {
       viewportRef,
       routeBottomAnchorRequest,
       onNearBottomChange: vi.fn(),
-      onNearHistoryStart: vi.fn(),
+      onNearHistoryStart: vi.fn().mockReturnValue(true),
       isLoadingOlderHistory: false,
       hasOlderHistory: false,
+      olderHistoryProgressKey: null,
       scrollEnabled: true,
       listStyle: null,
       baseListContentContainerStyle: null,
@@ -482,9 +511,10 @@ describe("createWebStreamStrategy", () => {
       viewportRef,
       routeBottomAnchorRequest,
       onNearBottomChange: vi.fn(),
-      onNearHistoryStart: vi.fn(),
+      onNearHistoryStart: vi.fn().mockReturnValue(true),
       isLoadingOlderHistory: false,
       hasOlderHistory: false,
+      olderHistoryProgressKey: null,
       scrollEnabled: true,
       listStyle: null,
       baseListContentContainerStyle: null,
@@ -578,9 +608,10 @@ describe("createWebStreamStrategy", () => {
       viewportRef,
       routeBottomAnchorRequest,
       onNearBottomChange: vi.fn(),
-      onNearHistoryStart: vi.fn(),
+      onNearHistoryStart: vi.fn().mockReturnValue(true),
       isLoadingOlderHistory: false,
       hasOlderHistory: false,
+      olderHistoryProgressKey: null,
       scrollEnabled: true,
       listStyle: null,
       baseListContentContainerStyle: null,
@@ -676,9 +707,10 @@ describe("createWebStreamStrategy", () => {
       viewportRef,
       routeBottomAnchorRequest: null,
       onNearBottomChange: vi.fn(),
-      onNearHistoryStart: vi.fn(),
+      onNearHistoryStart: vi.fn().mockReturnValue(true),
       isLoadingOlderHistory: false,
       hasOlderHistory: false,
+      olderHistoryProgressKey: null,
       scrollEnabled: true,
       listStyle: null,
       baseListContentContainerStyle: null,

packages/app/src/agent-stream/strategy-web.tsx

@@ -8,16 +8,39 @@ import React, {
   useRef,
   useState,
 } from "react";
-import { ActivityIndicator } from "react-native";
 import { measureElement as measureVirtualElement, useVirtualizer } from "@tanstack/react-virtual";
+import { withUnistyles } from "react-native-unistyles";
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
+import { useStableEvent } from "@/hooks/use-stable-event";
+import type { Theme } from "@/styles/theme";
 import { estimateStreamItemHeight } from "./web-virtualization";
 import type { StreamRenderInput, StreamStrategy, StreamViewportHandle } from "./strategy";
 import { createStreamStrategy } from "./strategy";
+import {
+  abandonHistoryStartPaginationRequest,
+  createHistoryStartPaginationState,
+  evaluateHistoryStartPagination,
+  isHistoryStartLoadingOperation,
+  rearmHistoryStartPagination,
+  settleHistoryStartPagination,
+  type HistoryStartPaginationInput,
+  type HistoryStartPaginationTransition,
+} from "./history-start-pagination";
+import {
+  createHistoryStartSettleScheduler,
+  type HistoryStartSettleScheduler,
+} from "./history-start-settle-scheduler";
 
 interface CreateWebStreamStrategyInput {
   isMobileBreakpoint: boolean;
 }
 
+interface HistoryStartPrependAnchor {
+  progressKey: string;
+  rowId: string;
+  viewportOffset: number;
+}
+
 type ScrollBehaviorLike = "auto" | "smooth";
 
 const WEB_BOTTOM_SETTLE_TIMEOUT_MS = 200;
@@ -25,7 +48,21 @@ const USER_SCROLL_DELTA_EPSILON = 1;
 const BOTTOM_OVERSCROLL_TOLERANCE_PX = 2;
 const AUTO_SCROLL_BOTTOM_THRESHOLD_PX = 64;
 const AUTO_SCROLL_RESUME_THRESHOLD_PX = 1;
-const HISTORY_START_THRESHOLD_PX = 96;
+const HISTORY_START_SETTLE_FRAMES = 2;
+
+const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
+const foregroundMutedColorMapping = (theme: Theme) => ({
+  color: theme.colors.foregroundMuted,
+});
+
+function findHistoryRowElement(contentNode: HTMLElement, rowId: string): HTMLElement | null {
+  for (const element of contentNode.querySelectorAll<HTMLElement>("[data-history-row-id]")) {
+    if (element.dataset.historyRowId === rowId) {
+      return element;
+    }
+  }
+  return null;
+}
 
 const historyStartSlotStyle: CSSProperties = {
   display: "flex",
@@ -107,6 +144,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     onNearHistoryStart,
     isLoadingOlderHistory,
     hasOlderHistory,
+    olderHistoryProgressKey,
     scrollEnabled,
     isMobileBreakpoint,
   } = props;
@@ -133,6 +171,14 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   const pendingAutoScrollTimeoutRef = useRef<number | null>(null);
   const pendingVirtualRowMeasureFramesRef = useRef(new Map<Element, number>());
   const historyStartReadyRef = useRef(false);
+  const [historyStartPaginationState, setHistoryStartPaginationState] = useState(
+    createHistoryStartPaginationState,
+  );
+  const [isHistoryStartSlotReserved, setIsHistoryStartSlotReserved] = useState(hasOlderHistory);
+  const historyStartPaginationStateRef = useRef(historyStartPaginationState);
+  const historyStartPrependAnchorRef = useRef<HistoryStartPrependAnchor | null>(null);
+  const historyStartPrependAnchorActiveRef = useRef(false);
+  const historyStartSettleSchedulerRef = useRef<HistoryStartSettleScheduler | null>(null);
   const shouldUseVirtualizer = segments.historyVirtualized.length > 0;
   const {
     renderHistoryVirtualizedRow,
@@ -162,6 +208,9 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   });
   useEffect(() => {
     rowVirtualizer.shouldAdjustScrollPositionOnItemSizeChange = (_item, _delta, instance) => {
+      if (historyStartPrependAnchorActiveRef.current) {
+        return false;
+      }
       const viewportHeight = instance.scrollRect?.height ?? 0;
       const scrollOffset = instance.scrollOffset ?? 0;
       const remainingDistance = instance.getTotalSize() - (scrollOffset + viewportHeight);
@@ -173,6 +222,162 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   }, [rowVirtualizer]);
   const virtualRows = rowVirtualizer.getVirtualItems();
   const virtualTotalSize = rowVirtualizer.getTotalSize();
+  const getHistoryStartPaginationInput = useStableEvent((): HistoryStartPaginationInput | null => {
+    const scrollContainer = scrollContainerRef.current;
+    if (!scrollContainer) {
+      return null;
+    }
+    const bottomAnchorSettled =
+      !followOutputRef.current || isScrollContainerNearBottom(scrollContainer);
+    return {
+      distanceFromHistoryStart: scrollContainer.scrollTop,
+      hasOlderHistory,
+      isLoadingOlderHistory,
+      isReady: historyStartReadyRef.current && bottomAnchorSettled,
+      progressKey: olderHistoryProgressKey,
+    };
+  });
+  const applyHistoryStartPaginationTransition = useStableEvent(
+    (transition: HistoryStartPaginationTransition) => {
+      const previousState = historyStartPaginationStateRef.current;
+      historyStartPaginationStateRef.current = transition.state;
+      if (transition.state !== previousState) {
+        setHistoryStartPaginationState(transition.state);
+      }
+      if (!isHistoryStartLoadingOperation(transition.state)) {
+        historyStartPrependAnchorRef.current = null;
+        historyStartPrependAnchorActiveRef.current = false;
+      }
+      if (!transition.shouldLoad || olderHistoryProgressKey === null) {
+        return;
+      }
+      const scrollContainer = scrollContainerRef.current;
+      const contentNode = contentRef.current;
+      const anchorRow = segments.historyMounted.at(-1) ?? segments.historyVirtualized.at(-1);
+      const anchorElement =
+        contentNode && anchorRow ? findHistoryRowElement(contentNode, anchorRow.id) : null;
+      if (scrollContainer && anchorRow && anchorElement) {
+        historyStartPrependAnchorRef.current = {
+          progressKey: olderHistoryProgressKey,
+          rowId: anchorRow.id,
+          viewportOffset:
+            anchorElement.getBoundingClientRect().top - scrollContainer.getBoundingClientRect().top,
+        };
+      } else {
+        historyStartPrependAnchorRef.current = null;
+      }
+      historyStartPrependAnchorActiveRef.current = false;
+      const requestedProgressKey = olderHistoryProgressKey;
+      void (async () => {
+        const started = await onNearHistoryStart();
+        if (started === true) {
+          return;
+        }
+        applyHistoryStartPaginationTransition({
+          state: abandonHistoryStartPaginationRequest(
+            historyStartPaginationStateRef.current,
+            requestedProgressKey,
+          ),
+          shouldLoad: false,
+        });
+      })();
+    },
+  );
+  const evaluateHistoryStart = useStableEvent(() => {
+    const input = getHistoryStartPaginationInput();
+    if (!input) {
+      return;
+    }
+    const transition = evaluateHistoryStartPagination(
+      historyStartPaginationStateRef.current,
+      input,
+    );
+    applyHistoryStartPaginationTransition(transition);
+  });
+  const rearmHistoryStartFromUserIntent = useStableEvent(() => {
+    const rearmed = rearmHistoryStartPagination(historyStartPaginationStateRef.current);
+    if (rearmed === historyStartPaginationStateRef.current) {
+      return;
+    }
+    historyStartPaginationStateRef.current = rearmed;
+    setHistoryStartPaginationState(rearmed);
+    evaluateHistoryStart();
+  });
+  const applyHistoryStartPrependAnchor = useStableEvent(() => {
+    const scrollContainer = scrollContainerRef.current;
+    const contentNode = contentRef.current;
+    const anchor = historyStartPrependAnchorRef.current;
+    if (
+      !scrollContainer ||
+      !contentNode ||
+      !anchor ||
+      !historyStartPrependAnchorActiveRef.current
+    ) {
+      return;
+    }
+    const anchorElement = findHistoryRowElement(contentNode, anchor.rowId);
+    if (!anchorElement) {
+      return;
+    }
+    const viewportOffset =
+      anchorElement.getBoundingClientRect().top - scrollContainer.getBoundingClientRect().top;
+    scrollContainer.scrollTop += viewportOffset - anchor.viewportOffset;
+    lastKnownScrollTopRef.current = scrollContainer.scrollTop;
+  });
+  const scheduleHistoryStartPrependSettle = useStableEvent(() => {
+    let scheduler = historyStartSettleSchedulerRef.current;
+    if (!scheduler) {
+      scheduler = createHistoryStartSettleScheduler({
+        settleFrames: HISTORY_START_SETTLE_FRAMES,
+        requestFrame: (callback) => window.requestAnimationFrame(callback),
+        cancelFrame: (frame) => window.cancelAnimationFrame(frame),
+        isSettling: () => historyStartPaginationStateRef.current.status === "settling",
+        isLoading: () => {
+          const input = getHistoryStartPaginationInput();
+          return (
+            !input ||
+            input.isLoadingOlderHistory ||
+            pendingVirtualRowMeasureFramesRef.current.size > 0
+          );
+        },
+        onFrame: applyHistoryStartPrependAnchor,
+        onSettle: () => {
+          const input = getHistoryStartPaginationInput();
+          if (!input) {
+            return;
+          }
+          historyStartPrependAnchorActiveRef.current = false;
+          const transition = settleHistoryStartPagination(
+            historyStartPaginationStateRef.current,
+            input,
+          );
+          historyStartPrependAnchorRef.current = null;
+          applyHistoryStartPaginationTransition(transition);
+        },
+      });
+      historyStartSettleSchedulerRef.current = scheduler;
+    }
+    scheduler.schedule();
+  });
+
+  useLayoutEffect(() => {
+    const anchor = historyStartPrependAnchorRef.current;
+    if (!anchor || anchor.progressKey === olderHistoryProgressKey) {
+      return;
+    }
+    historyStartPrependAnchorActiveRef.current = true;
+    evaluateHistoryStart();
+    applyHistoryStartPrependAnchor();
+    scheduleHistoryStartPrependSettle();
+  }, [
+    applyHistoryStartPrependAnchor,
+    evaluateHistoryStart,
+    olderHistoryProgressKey,
+    scheduleHistoryStartPrependSettle,
+    segments.historyMounted,
+    segments.historyVirtualized,
+    virtualTotalSize,
+  ]);
 
   const measureVirtualizedRowElement = useCallback(
     (node: HTMLDivElement | null) => {
@@ -231,8 +436,9 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       scrollElementToBottom(scrollContainer, behavior);
       lastKnownScrollTopRef.current = scrollContainer.scrollTop;
       syncNearBottom(scrollContainer, onNearBottomChange);
+      evaluateHistoryStart();
     },
-    [onNearBottomChange],
+    [evaluateHistoryStart, onNearBottomChange],
   );
 
   const scheduleStickToBottom = useCallback(() => {
@@ -297,24 +503,26 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
 
     lastKnownScrollTopRef.current = currentScrollTop;
     updateScrollMetrics();
-    if (
-      historyStartReadyRef.current &&
-      hasOlderHistory &&
-      currentScrollTop <= HISTORY_START_THRESHOLD_PX
-    ) {
-      onNearHistoryStart();
-    }
-  }, [cancelPendingStickToBottom, hasOlderHistory, onNearHistoryStart, updateScrollMetrics]);
+    evaluateHistoryStart();
+  }, [cancelPendingStickToBottom, evaluateHistoryStart, updateScrollMetrics]);
 
   useEffect(() => {
+    const initialHistoryStartState = createHistoryStartPaginationState();
+    historyStartPaginationStateRef.current = initialHistoryStartState;
+    setHistoryStartPaginationState(initialHistoryStartState);
+    historyStartPrependAnchorRef.current = null;
+    historyStartPrependAnchorActiveRef.current = false;
     const frame = window.requestAnimationFrame(() => {
       historyStartReadyRef.current = true;
+      evaluateHistoryStart();
     });
     return () => {
       window.cancelAnimationFrame(frame);
       historyStartReadyRef.current = false;
+      historyStartSettleSchedulerRef.current?.cancel();
+      historyStartSettleSchedulerRef.current = null;
     };
-  }, [props.agentId]);
+  }, [evaluateHistoryStart, props.agentId]);
 
   useLayoutEffect(() => {
     if (!isActivationReady) {
@@ -370,7 +578,16 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
 
   useEffect(() => {
     updateScrollMetrics();
+    evaluateHistoryStart();
+    if (historyStartPaginationStateRef.current.status === "settling") {
+      scheduleHistoryStartPrependSettle();
+    }
   }, [
+    evaluateHistoryStart,
+    hasOlderHistory,
+    isLoadingOlderHistory,
+    olderHistoryProgressKey,
+    scheduleHistoryStartPrependSettle,
     segments.historyMounted.length,
     segments.historyVirtualized.length,
     segments.liveHead.length,
@@ -386,8 +603,16 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     }
 
     updateScrollMetrics();
+    evaluateHistoryStart();
     const observer = new ResizeObserver(() => {
+      if (historyStartPrependAnchorActiveRef.current) {
+        applyHistoryStartPrependAnchor();
+      }
+      if (historyStartPaginationStateRef.current.status === "settling") {
+        scheduleHistoryStartPrependSettle();
+      }
       updateScrollMetrics();
+      evaluateHistoryStart();
       if (!followOutputRef.current) {
         return;
       }
@@ -400,7 +625,13 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     return () => {
       observer.disconnect();
     };
-  }, [scheduleStickToBottom, updateScrollMetrics]);
+  }, [
+    applyHistoryStartPrependAnchor,
+    evaluateHistoryStart,
+    scheduleHistoryStartPrependSettle,
+    scheduleStickToBottom,
+    updateScrollMetrics,
+  ]);
 
   useEffect(() => {
     const scrollContainer = scrollContainerRef.current;
@@ -412,6 +643,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       if (event.deltaY < 0) {
         pendingUserScrollUpIntentRef.current = true;
         cancelPendingStickToBottom();
+        rearmHistoryStartFromUserIntent();
       }
     };
     const handlePointerDown = () => {
@@ -436,6 +668,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       if (previousTouchY !== null && touch.clientY > previousTouchY + 1) {
         pendingUserScrollUpIntentRef.current = true;
         cancelPendingStickToBottom();
+        rearmHistoryStartFromUserIntent();
       }
       lastTouchClientYRef.current = touch.clientY;
     };
@@ -464,7 +697,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       scrollContainer.removeEventListener("touchend", handleTouchEnd);
       scrollContainer.removeEventListener("touchcancel", handleTouchEnd);
     };
-  }, [cancelPendingStickToBottom, handleDomScroll]);
+  }, [cancelPendingStickToBottom, handleDomScroll, rearmHistoryStartFromUserIntent]);
 
   useEffect(() => {
     const handle: StreamViewportHandle = {
@@ -531,9 +764,9 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   );
   const mountedHistoryRows = useMemo(() => {
     return segments.historyMounted.map((item, index) => (
-      <Fragment key={item.id}>
+      <div key={item.id} data-history-row-id={item.id}>
         {renderHistoryMountedRow(item, index, segments.historyMounted)}
-      </Fragment>
+      </div>
     ));
   }, [renderHistoryMountedRow, segments.historyMounted]);
   const liveHeadRows = useMemo(() => {
@@ -545,16 +778,27 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   const liveAuxiliary = useMemo(() => {
     return renderLiveAuxiliary();
   }, [renderLiveAuxiliary]);
+  useEffect(() => {
+    if (hasOlderHistory || isHistoryStartLoadingOperation(historyStartPaginationState)) {
+      setIsHistoryStartSlotReserved(true);
+    }
+  }, [hasOlderHistory, historyStartPaginationState]);
   const historyStartSlot = useMemo(() => {
-    if (!isLoadingOlderHistory) {
+    const isLoadingOperation = isHistoryStartLoadingOperation(historyStartPaginationState);
+    if (!isHistoryStartSlotReserved && !hasOlderHistory && !isLoadingOperation) {
       return null;
     }
     return (
-      <div style={historyStartSlotStyle} data-testid="load-older-history-spinner">
-        <ActivityIndicator size="small" />
+      <div
+        style={historyStartSlotStyle}
+        data-testid={isLoadingOperation ? "load-older-history-spinner" : undefined}
+      >
+        {isLoadingOperation ? (
+          <ThemedLoadingSpinner size="small" uniProps={foregroundMutedColorMapping} />
+        ) : null}
       </div>
     );
-  }, [isLoadingOlderHistory]);
+  }, [hasOlderHistory, historyStartPaginationState, isHistoryStartSlotReserved]);
   const shouldRenderEmpty =
     !boundary.hasMountedHistory &&
     !boundary.hasVirtualizedHistory &&
@@ -581,6 +825,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
                 <div
                   key={virtualRow.key}
                   data-index={virtualRow.index}
+                  data-history-row-id={item.id}
                   ref={measureVirtualizedRowElement}
                   style={renderVirtualRowStyle(virtualRow.start)}
                 >

packages/app/src/agent-stream/strategy.ts

@@ -69,9 +69,10 @@ export interface StreamRenderInput {
   routeBottomAnchorRequest: BottomAnchorRouteRequest | null;
   isAuthoritativeHistoryReady: boolean;
   onNearBottomChange: (value: boolean) => void;
-  onNearHistoryStart: () => void;
+  onNearHistoryStart: () => boolean | Promise<boolean>;
   isLoadingOlderHistory: boolean;
   hasOlderHistory: boolean;
+  olderHistoryProgressKey: string | null;
   scrollEnabled: boolean;
   listStyle: StyleProp<ViewStyle>;
   baseListContentContainerStyle: StyleProp<ViewStyle>;

packages/app/src/agent-stream/view.tsx

@@ -1,3 +1,4 @@
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import React, {
   forwardRef,
   memo,
@@ -17,7 +18,6 @@ import {
   Text,
   Pressable,
   Platform,
-  ActivityIndicator,
   type PressableStateCallbackType,
   type StyleProp,
   type ViewStyle,
@@ -41,6 +41,7 @@ import {
 } from "@/components/message";
 import { PlanCard } from "@/components/plan-card";
 import type { StreamItem } from "@/types/stream";
+import type { PendingMessageSubmission } from "@/composer/submission/model";
 import type { PendingPermission } from "@/types/shared";
 import type {
   AgentCapabilityFlags,
@@ -76,6 +77,7 @@ import {
   type BottomAnchorLocalRequest,
   type BottomAnchorRouteRequest,
 } from "./bottom-anchor-controller";
+import { createAssistantImageOccurrenceKey } from "@/assistant-image/acquisition-cache";
 import {
   AssistantFileLinkResolverProvider,
   normalizeInlinePathTarget,
@@ -239,6 +241,7 @@ export interface AgentStreamViewProps {
   streamItems: StreamItem[];
   streamHead?: StreamItem[];
   pendingPermissions: Map<string, PendingPermission>;
+  pendingMessageSubmissions?: readonly PendingMessageSubmission[];
   routeBottomAnchorRequest?: BottomAnchorRouteRequest | null;
   isAuthoritativeHistoryReady?: boolean;
   toast?: ToastApi | null;
@@ -247,7 +250,8 @@ export interface AgentStreamViewProps {
   historyPagination?: {
     hasOlder: boolean;
     isLoadingOlder: boolean;
-    onLoadOlder: () => void;
+    progressKey: string | null;
+    onLoadOlder: () => boolean | Promise<boolean>;
   };
 }
 
@@ -264,6 +268,7 @@ const AGENT_CAPABILITY_FLAG_KEYS: (keyof AgentCapabilityFlags)[] = [
 ];
 
 const EMPTY_STREAM_HEAD: StreamItem[] = [];
+const EMPTY_PENDING_MESSAGE_SUBMISSIONS: readonly PendingMessageSubmission[] = [];
 const GROUPED_TOOL_CALL_DETAIL_MAX_HEIGHT = 200;
 
 function buildChatHistoryAttachment(input: {
@@ -326,6 +331,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       streamItems,
       streamHead: providedStreamHead,
       pendingPermissions,
+      pendingMessageSubmissions = EMPTY_PENDING_MESSAGE_SUBMISSIONS,
       routeBottomAnchorRequest = null,
       isAuthoritativeHistoryReady = true,
       toast,
@@ -340,6 +346,10 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
     const autoExpandReasoning = useSettings((settings) => settings.autoExpandReasoning);
     const toolCallDetailLevel = useSettings((settings) => settings.toolCallDetailLevel);
     const viewportRef = useRef<StreamViewportHandle | null>(null);
+    const pendingClientMessageIds = useMemo(
+      () => new Set(pendingMessageSubmissions.map((submission) => submission.clientMessageId)),
+      [pendingMessageSubmissions],
+    );
     const isMobile = useIsCompactFormFactor();
     const streamRenderStrategy = useMemo(
       () =>
@@ -388,10 +398,11 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       agentId,
       toast,
     });
-    const { isLoadingOlder, hasOlder, loadOlder } = historyPagination
+    const { isLoadingOlder, hasOlder, progressKey, loadOlder } = historyPagination
       ? {
           isLoadingOlder: historyPagination.isLoadingOlder,
           hasOlder: historyPagination.hasOlder,
+          progressKey: historyPagination.progressKey,
           loadOlder: historyPagination.onLoadOlder,
         }
       : agentHistoryPagination;
@@ -654,7 +665,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           <UserMessage
             serverId={resolvedServerId}
             agentId={agentId}
-            messageId={item.id}
+            messageId={item.messageId}
             message={item.text}
             images={item.images}
             attachments={item.attachments}
@@ -663,10 +674,14 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
             client={client}
             isFirstInGroup={layoutItem.isFirstInUserGroup}
             isLastInGroup={layoutItem.isLastInUserGroup}
+            isPending={
+              item.clientMessageId !== undefined &&
+              pendingClientMessageIds.has(item.clientMessageId)
+            }
           />
         );
       },
-      [context.capabilities, agentId, client, resolvedServerId],
+      [context.capabilities, agentId, client, pendingClientMessageIds, resolvedServerId],
     );
 
     const renderAssistantMessageItem = useCallback(
@@ -680,6 +695,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
             toast={toast}
           >
             <AssistantMessage
+              occurrenceKey={createAssistantImageOccurrenceKey({ agentId, itemId: item.id })}
               message={item.text}
               timestamp={item.timestamp.getTime()}
               workspaceRoot={workspaceRoot}
@@ -690,7 +706,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           </AssistantFileLinkResolverProvider>
         );
       },
-      [client, handleInlinePathPress, resolvedServerId, toast, workspaceRoot],
+      [agentId, client, handleInlinePathPress, resolvedServerId, toast, workspaceRoot],
     );
 
     const renderThoughtItem = useCallback(
@@ -876,7 +892,8 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       [pendingPermissions, agentId],
     );
 
-    const showRunningTurnFooter = baseRenderModel.turnTiming.isActive;
+    const showRunningTurnFooter =
+      context.status === "running" || pendingMessageSubmissions.length > 0;
     const pendingPermissionsNode = useMemo(
       () =>
         renderPendingPermissionsNode({
@@ -1029,6 +1046,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
               onNearHistoryStart: loadOlder,
               isLoadingOlderHistory: isLoadingOlder,
               hasOlderHistory: hasOlder,
+              olderHistoryProgressKey: progressKey,
               scrollEnabled: streamScrollEnabled,
               listStyle: stylesheet.list,
               baseListContentContainerStyle: stylesheet.listContentContainer,
@@ -1138,6 +1156,7 @@ function historyPaginationPropsEqual(
   return (
     left?.hasOlder === right?.hasOlder &&
     left?.isLoadingOlder === right?.isLoadingOlder &&
+    left?.progressKey === right?.progressKey &&
     left?.onLoadOlder === right?.onLoadOlder
   );
 }
@@ -1153,6 +1172,9 @@ function agentStreamViewPropsEqual(
   if (left.streamItems !== right.streamItems) reasons.push("streamItems");
   if (left.streamHead !== right.streamHead) reasons.push("streamHead");
   if (left.pendingPermissions !== right.pendingPermissions) reasons.push("pendingPermissions");
+  if (left.pendingMessageSubmissions !== right.pendingMessageSubmissions) {
+    reasons.push("pendingMessageSubmissions");
+  }
   if (
     !bottomAnchorRouteRequestsEqual(left.routeBottomAnchorRequest, right.routeBottomAnchorRequest)
   ) {
@@ -1194,7 +1216,7 @@ function ToolCallSlot({
   return <ToolCall {...rest} onInlineDetailsExpandedChange={handleExpandedChange} />;
 }
 
-const ThemedActivityIndicator = withUnistyles(ActivityIndicator);
+const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
 const ThemedCheckIcon = withUnistyles(Check);
 const ThemedXIcon = withUnistyles(X);
 
@@ -1241,7 +1263,7 @@ function PermissionActionButton({
   return (
     <Pressable testID={testID} style={pressableStyle} onPress={handlePress} disabled={isResponding}>
       {isRespondingAction ? (
-        <ThemedActivityIndicator size="small" uniProps={colorMapping} />
+        <ThemedLoadingSpinner size="small" uniProps={colorMapping} />
       ) : (
         <View style={permissionStyles.optionContent}>
           <Icon size={14} uniProps={colorMapping} />

packages/app/src/app/_layout.tsx

@@ -32,6 +32,7 @@ import { AppDiagnosticHost } from "@/components/app-diagnostic-host";
 import { LeftSidebar } from "@/components/left-sidebar";
 import { WindowSidebarMenuToggle } from "@/components/headers/menu-header";
 import { SidebarModelProvider } from "@/components/sidebar/sidebar-model";
+import { WorkspacePinShortcutHandler } from "@/components/workspace-pin-shortcut-handler";
 import { CompactExplorerSidebarHost } from "@/components/compact-explorer-sidebar-host";
 import { ProviderSettingsHost } from "@/components/provider-settings-host";
 import { RootErrorBoundary } from "@/components/root-error-boundary";
@@ -551,6 +552,7 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
       <UpdateCalloutSource />
       <WorktreeSetupCalloutSource />
       <CommandCenterRootActions />
+      <WorkspacePinShortcutHandler />
       <CommandCenter />
       <AddProjectFlowHost />
       <HostChooserModal />

packages/app/src/assets/acp-provider-icons.ts

@@ -58,8 +58,6 @@ export const ACP_PROVIDER_ICON_SVGS = {
   nova: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">\n  <circle cx="8" cy="8" r="6" fill="none" stroke="currentColor" stroke-width="1"/>\n  <circle cx="8" cy="8" r="4.5" fill="none" stroke="currentColor" stroke-width="0.3" opacity="0.5"/>\n  <line x1="8" y1="8" x2="13.5" y2="13.5" stroke="currentColor" stroke-width="1.3" stroke-linecap="round"/>\n  <polygon points="14.5,14.5 12.3,13.5 13.5,12.3" fill="currentColor"/>\n  <line x1="8" y1="8" x2="2.5" y2="2.5" stroke="currentColor" stroke-width="1.3" stroke-linecap="round"/>\n  <polygon points="1.5,1.5 3.7,2.5 2.5,3.7" fill="currentColor"/>\n  <circle cx="8" cy="8" r="1.3" fill="currentColor"/>\n  <circle cx="8" cy="8" r="0.6" fill="none" stroke="currentColor" stroke-width="0.5" opacity="0.7"/>\n</svg>\n',
   opencode:
     '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">\n<path fill-rule="evenodd" clip-rule="evenodd" d="M13 14H3V2H13V14ZM10.5 4.4H5.5V11.6H10.5V4.4Z" fill="currentColor"/>\n</svg>\n',
-  "pi-acp":
-    '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">\n<path d="M1 1H11.7692V7.9999H8.17942V11.4999H4.58982V15H1V1ZM4.58982 4.50005V7.9999H8.17942V4.50005H4.58982Z" fill="currentColor"/>\n<path d="M11.7692 7.46154H15V15H11.7692V7.46154Z" fill="currentColor"/>\n</svg>\n',
   poolside:
     '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">\n<path d="M2.63653 5.50522L2.18735 5.28559C2.09852 5.46726 2.12787 5.68456 2.26172 5.83616C2.39558 5.98775 2.60757 6.04379 2.79884 5.97814L2.63653 5.50522ZM5.83578 6.94285L5.3732 7.13265L5.5645 7.59886L6.02919 7.40392L5.83578 6.94285ZM10.7441 9.44034L10.2614 9.57083L10.393 10.0573L10.8784 9.92198L10.7441 9.44034ZM2.5 8.24963C2.4998 7.97349 2.27577 7.74979 1.99963 7.75C1.72349 7.75021 1.4998 7.97423 1.5 8.25037L2.5 8.24963ZM13.4143 10.7751C12.0197 13.6273 8.57701 14.8089 5.72485 13.4143L5.28559 14.3126C8.63389 15.9498 12.6754 14.5627 14.3126 11.2144L13.4143 10.7751ZM3.08571 5.72485C4.48031 2.87269 7.92299 1.69111 10.7751 3.08571L11.2144 2.18735C7.86611 0.550151 3.82455 1.93728 2.18735 5.28559L3.08571 5.72485ZM10.7751 3.08571C13.6273 4.48031 14.8089 7.92299 13.4143 10.7751L14.3126 11.2144C15.9498 7.86611 14.5627 3.82455 11.2144 2.18735L10.7751 3.08571ZM2.79884 5.97814C3.02201 5.90155 3.54835 5.84926 4.09141 6.00587C4.61256 6.15616 5.10736 6.48476 5.3732 7.13265L6.29835 6.75304C5.89213 5.76303 5.11508 5.26032 4.3685 5.04503C3.64385 4.83605 2.9066 4.8839 2.47422 5.0323L2.79884 5.97814ZM6.02919 7.40392C6.25314 7.30998 6.55771 7.25841 6.85281 7.36034C7.13062 7.45631 7.49214 7.72014 7.78743 8.4398L8.71257 8.0602C8.3358 7.14195 7.79046 6.62626 7.17931 6.41515C6.58544 6.21001 6.01893 6.32381 5.64236 6.48177L6.02919 7.40392ZM6.26827 7.19375C6.80493 6.26869 8.18817 4.18684 11.1653 3.10654L10.8242 2.16652C7.53166 3.36127 5.99463 5.67263 5.40329 6.69195L6.26827 7.19375ZM14.3364 10.8325C14.1845 10.39 13.7564 9.79897 13.14 9.37995C12.504 8.94759 11.6302 8.67426 10.6099 8.9587L10.8784 9.92198C11.5634 9.73102 12.1368 9.90713 12.5779 10.207C13.0385 10.5201 13.3174 10.9441 13.3905 11.1571L14.3364 10.8325ZM11.2268 9.30984C11.1236 8.92833 10.8783 8.39265 10.3638 8.02453C9.82769 7.6409 9.08331 7.49864 8.11574 7.76836L8.38426 8.73164C9.1221 8.52595 9.53979 8.66454 9.78189 8.83777C10.0457 9.02651 10.1946 9.32371 10.2614 9.57083L11.2268 9.30984ZM11.216 9.60556C11.6225 8.44463 12.4244 5.47936 11.4712 2.48487L10.5183 2.78819C11.3726 5.47172 10.6545 8.18331 10.2722 9.27512L11.216 9.60556ZM7.80082 8.03037L5.05604 13.6438L5.9544 14.0831L8.69918 8.46963L7.80082 8.03037ZM5.72485 13.4143C3.68742 12.4181 2.50158 10.3763 2.5 8.24963L1.5 8.25037C1.50185 10.7441 2.89229 13.1424 5.28559 14.3126L5.72485 13.4143Z" fill="currentColor"/>\n</svg>\n',
   qoder:

packages/app/src/assistant-image/acquisition-cache.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest";
+import {
+  collectRetainedAttachmentIds,
+  retainAttachmentForGarbageCollection,
+} from "@/attachments/gc-retention";
+import {
+  createAssistantImageAcquisitionCache,
+  createAssistantImageFileAcquisitionKey,
+  createAssistantImageFilePreviewAttachmentId,
+  createAssistantImageOccurrenceKey,
+} from "./acquisition-cache";
+
+describe("assistant image acquisition cache", () => {
+  it("evicts a rejected acquisition so the next request can retry", async () => {
+    const cache = createAssistantImageAcquisitionCache<string>({ capacity: 2 });
+    let attempts = 0;
+
+    await expect(
+      cache.acquire("image", async () => {
+        attempts += 1;
+        throw new Error("first attempt failed");
+      }),
+    ).rejects.toThrow("first attempt failed");
+    const recovered = await cache.acquire("image", async () => {
+      attempts += 1;
+      return "recovered";
+    });
+
+    expect({ attempts, recovered, size: cache.size() }).toEqual({
+      attempts: 2,
+      recovered: "recovered",
+      size: 1,
+    });
+  });
+
+  it("bounds successful acquisitions and evicts the least recently used entry", async () => {
+    const cache = createAssistantImageAcquisitionCache<string>({ capacity: 2 });
+    const located: string[] = [];
+    const locate = async (key: string) => {
+      located.push(key);
+      return key;
+    };
+
+    await cache.acquire("a", async () => await locate("a"));
+    await cache.acquire("b", async () => await locate("b"));
+    await cache.acquire("a", async () => await locate("a-again"));
+    await cache.acquire("c", async () => await locate("c"));
+    await cache.acquire("b", async () => await locate("b-again"));
+
+    expect({ located, size: cache.size() }).toEqual({
+      located: ["a", "b", "c", "b-again"],
+      size: 2,
+    });
+  });
+
+  it("reuses an acquired image when the current locator is unavailable", async () => {
+    const cache = createAssistantImageAcquisitionCache<string>({ capacity: 2 });
+    let unavailableCalls = 0;
+
+    await cache.acquire("message:image", async () => "persisted attachment");
+    const cached = await cache.acquire("message:image", async () => {
+      unavailableCalls += 1;
+      throw new Error("daemon disconnected");
+    });
+
+    expect({ cached, unavailableCalls }).toEqual({
+      cached: "persisted attachment",
+      unavailableCalls: 0,
+    });
+    expect(cache.peek("message:image")).toBe("persisted attachment");
+  });
+
+  it("scopes file acquisitions to the rendered message occurrence", () => {
+    const first = createAssistantImageFileAcquisitionKey({
+      serverId: "server",
+      occurrenceKey: "message-1:image-1",
+      cwd: "/workspace",
+      path: "screenshot.png",
+    });
+    const remount = createAssistantImageFileAcquisitionKey({
+      serverId: "server",
+      occurrenceKey: "message-1:image-1",
+      cwd: "/workspace",
+      path: "screenshot.png",
+    });
+    const laterMessage = createAssistantImageFileAcquisitionKey({
+      serverId: "server",
+      occurrenceKey: "message-2:image-1",
+      cwd: "/workspace",
+      path: "screenshot.png",
+    });
+
+    expect(remount).toBe(first);
+    expect(laterMessage).not.toBe(first);
+  });
+
+  it("scopes persisted file previews to the rendered message occurrence", () => {
+    const first = createAssistantImageFilePreviewAttachmentId({
+      serverId: "server-1",
+      occurrenceKey: "message-1:image-1",
+      mimeType: "image/png",
+      path: "/workspace/screenshot.png",
+      size: 512,
+      modifiedAt: "2026-07-27T12:00:00.000Z",
+      contentLength: 512,
+    });
+    const second = createAssistantImageFilePreviewAttachmentId({
+      serverId: "server-1",
+      occurrenceKey: "message-2:image-1",
+      mimeType: "image/png",
+      path: "/workspace/screenshot.png",
+      size: 512,
+      modifiedAt: "2026-07-27T12:00:00.000Z",
+      contentLength: 512,
+    });
+
+    expect(second).not.toBe(first);
+  });
+
+  it("scopes message occurrences to their agent", () => {
+    const first = createAssistantImageOccurrenceKey({ agentId: "agent-1", itemId: "message-1" });
+    const second = createAssistantImageOccurrenceKey({ agentId: "agent-2", itemId: "message-1" });
+
+    expect(second).not.toBe(first);
+  });
+
+  it("retains successful values until their cache entry is evicted", async () => {
+    const retained: string[] = [];
+    const released: string[] = [];
+    const cache = createAssistantImageAcquisitionCache<string>({
+      capacity: 1,
+      onRetain(value) {
+        retained.push(value);
+        return () => released.push(value);
+      },
+    });
+
+    await cache.acquire("first", async () => "attachment-1");
+    expect({ retained, released }).toEqual({ retained: ["attachment-1"], released: [] });
+
+    await cache.acquire("second", async () => "attachment-2");
+    expect({ retained, released }).toEqual({
+      retained: ["attachment-1", "attachment-2"],
+      released: ["attachment-1"],
+    });
+  });
+
+  it("does not evict a value while an active consumer retains it", async () => {
+    const released: string[] = [];
+    const cache = createAssistantImageAcquisitionCache<string>({
+      capacity: 1,
+      onRetain: (value) => () => released.push(value),
+    });
+
+    const first = cache.acquireRetained("first", async () => "attachment-1");
+    await first.promise;
+    const second = cache.acquireRetained("second", async () => "attachment-2");
+    await second.promise;
+
+    expect({ released, size: cache.size() }).toEqual({ released: [], size: 2 });
+
+    first.release();
+    expect({ released, size: cache.size() }).toEqual({
+      released: ["attachment-1"],
+      size: 1,
+    });
+    second.release();
+  });
+
+  it("protects every actively consumed attachment from garbage collection past capacity", async () => {
+    const cache = createAssistantImageAcquisitionCache<{ id: string }>({
+      capacity: 1,
+      onRetain: (attachment) => retainAttachmentForGarbageCollection(attachment.id),
+    });
+
+    const first = cache.acquireRetained("first", async () => ({ id: "mounted-image-1" }));
+    await first.promise;
+    const second = cache.acquireRetained("second", async () => ({ id: "mounted-image-2" }));
+    await second.promise;
+
+    expect(collectRetainedAttachmentIds()).toEqual(new Set(["mounted-image-1", "mounted-image-2"]));
+
+    first.release();
+    expect(collectRetainedAttachmentIds()).toEqual(new Set(["mounted-image-2"]));
+    second.release();
+    await expect(
+      cache.acquire("cleanup", async () => {
+        throw new Error("cleanup");
+      }),
+    ).rejects.toThrow("cleanup");
+    expect(collectRetainedAttachmentIds()).toEqual(new Set());
+  });
+});

packages/app/src/assistant-image/acquisition-cache.ts

@@ -0,0 +1,159 @@
+import { createPreviewAttachmentId } from "@/attachments/utils";
+
+export interface AssistantImageAcquisitionCache<T> {
+  acquire(key: string, locate: () => Promise<T>): Promise<T>;
+  acquireRetained(
+    key: string,
+    locate: () => Promise<T>,
+  ): { promise: Promise<T>; value?: T; release: () => void };
+  peek(key: string): T | undefined;
+  size(): number;
+}
+
+export function createAssistantImageOccurrenceKey(input: {
+  agentId: string;
+  itemId: string;
+}): string {
+  return `${input.agentId}:${input.itemId}`;
+}
+
+export function createAssistantImageFilePreviewAttachmentId(input: {
+  serverId?: string;
+  occurrenceKey: string;
+  mimeType: string;
+  path: string;
+  size: number;
+  modifiedAt?: string | null;
+  contentLength: number;
+}): string {
+  return createPreviewAttachmentId({
+    mimeType: input.mimeType,
+    path: input.path,
+    size: input.size,
+    modifiedAt: input.modifiedAt,
+    contentLength: input.contentLength,
+    contentKey: `${input.serverId ?? "unknown-server"}:${input.occurrenceKey}`,
+  });
+}
+
+export function createAssistantImageFileAcquisitionKey(input: {
+  serverId?: string;
+  occurrenceKey: string;
+  cwd: string;
+  path: string;
+}): string {
+  return `file:${input.serverId ?? "unknown-server"}:${input.occurrenceKey}:${input.cwd}:${input.path}`;
+}
+
+export function createAssistantImageAcquisitionCache<T>(input: {
+  capacity: number;
+  onRetain?: (value: T) => () => void;
+}): AssistantImageAcquisitionCache<T> {
+  if (!Number.isInteger(input.capacity) || input.capacity < 1) {
+    throw new Error("Assistant image acquisition cache capacity must be a positive integer.");
+  }
+  interface CacheEntry {
+    pending: Promise<T>;
+    resolved: boolean;
+    value?: T;
+    release: (() => void) | null;
+    activeConsumers: number;
+  }
+  const entries = new Map<string, CacheEntry>();
+
+  const evict = (key: string, entry: CacheEntry) => {
+    if (entries.get(key) === entry) {
+      entries.delete(key);
+    }
+    entry.release?.();
+    entry.release = null;
+  };
+
+  const enforceCapacity = () => {
+    while (entries.size > input.capacity) {
+      let evicted = false;
+      for (const [key, entry] of entries) {
+        if (entry.activeConsumers > 0) {
+          continue;
+        }
+        evict(key, entry);
+        evicted = true;
+        break;
+      }
+      if (!evicted) {
+        return;
+      }
+    }
+  };
+
+  const acquireEntry = (key: string, locate: () => Promise<T>, retain: boolean): CacheEntry => {
+    const cached = entries.get(key);
+    if (cached) {
+      entries.delete(key);
+      entries.set(key, cached);
+      if (retain) {
+        cached.activeConsumers += 1;
+      }
+      return cached;
+    }
+    const pending = locate();
+    const entry: CacheEntry = {
+      pending,
+      resolved: false,
+      release: null,
+      activeConsumers: retain ? 1 : 0,
+    };
+    entries.set(key, entry);
+    enforceCapacity();
+    void (async () => {
+      try {
+        const value = await pending;
+        const release = input.onRetain?.(value) ?? null;
+        if (entries.get(key) === entry) {
+          entry.value = value;
+          entry.resolved = true;
+          entry.release = release;
+        } else {
+          release?.();
+        }
+      } catch {
+        evict(key, entry);
+      }
+    })();
+    return entry;
+  };
+
+  return {
+    acquire(key, locate) {
+      return acquireEntry(key, locate, false).pending;
+    },
+    acquireRetained(key, locate) {
+      const entry = acquireEntry(key, locate, true);
+      let released = false;
+      return {
+        promise: entry.pending,
+        ...(entry.resolved ? { value: entry.value } : {}),
+        release() {
+          if (released) {
+            return;
+          }
+          released = true;
+          entry.activeConsumers = Math.max(0, entry.activeConsumers - 1);
+          enforceCapacity();
+        },
+      };
+    },
+    peek(key) {
+      const entry = entries.get(key);
+      if (!entry?.resolved) {
+        return undefined;
+      }
+      entries.delete(key);
+      entries.set(key, entry);
+      return entry.value;
+    },
+    size() {
+      return entries.size;
+    },
+  };
+}

packages/app/src/assistant-image/file-acquisition.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import type { AttachmentMetadata } from "@/attachments/types";
+import {
+  createAssistantImageFileAcquisition,
+  type AssistantImageFileAcquisitionPort,
+} from "./file-acquisition";
+
+class MemoryFileAcquisitionPort implements AssistantImageFileAcquisitionPort {
+  readonly reads: Array<{ cwd: string; path: string }> = [];
+
+  async readFile(cwd: string, path: string) {
+    this.reads.push({ cwd, path });
+    return {
+      kind: "image" as const,
+      path,
+      mime: "image/png",
+      size: 4,
+      modifiedAt: "1",
+      bytes: new Uint8Array([1, 2, 3, 4]),
+    };
+  }
+
+  async persist(input: { id: string; mimeType: string; fileName: string | null }) {
+    return {
+      id: input.id,
+      mimeType: input.mimeType,
+      storageType: "web-indexeddb" as const,
+      storageKey: input.id,
+      fileName: input.fileName,
+      byteSize: 4,
+      createdAt: 1,
+    } satisfies AttachmentMetadata;
+  }
+}
+
+describe("assistant image file acquisition", () => {
+  it("recreates the same acquisition with a live port after reconnect", async () => {
+    const common = {
+      resolution: { kind: "file_rpc" as const, cwd: "/workspace", path: "reconnect.png" },
+      serverId: "server",
+      occurrenceKey: "agent:message:reconnect-image",
+      unavailableMessage: "Image unavailable",
+    };
+    const disconnected = createAssistantImageFileAcquisition({ ...common, port: null });
+    const connectedPort = new MemoryFileAcquisitionPort();
+    const connected = createAssistantImageFileAcquisition({ ...common, port: connectedPort });
+
+    expect(disconnected?.key).toBe(connected?.key);
+    await expect(disconnected?.locate()).rejects.toThrow("Image unavailable");
+    await expect(connected?.locate()).resolves.toMatchObject({ mimeType: "image/png" });
+    expect(connectedPort.reads).toEqual([{ cwd: "/workspace", path: "reconnect.png" }]);
+  });
+});

packages/app/src/assistant-image/file-acquisition.ts

@@ -0,0 +1,67 @@
+import type { FileReadResult } from "@getpaseo/client/internal/daemon-client";
+import type { AttachmentMetadata } from "@/attachments/types";
+import { getFileNameFromPath } from "@/attachments/utils";
+import type { AssistantImageSourceResolution } from "@/utils/assistant-image-source";
+import {
+  createAssistantImageFileAcquisitionKey,
+  createAssistantImageFilePreviewAttachmentId,
+} from "./acquisition-cache";
+
+export interface AssistantImageFileAcquisitionPort {
+  readFile(cwd: string, path: string): Promise<FileReadResult>;
+  persist(input: {
+    id: string;
+    bytes: Uint8Array;
+    mimeType: string;
+    fileName: string | null;
+  }): Promise<AttachmentMetadata>;
+}
+
+export interface AssistantImageAcquisition {
+  key: string;
+  locate: () => Promise<AttachmentMetadata>;
+}
+
+export function createAssistantImageFileAcquisition(input: {
+  port: AssistantImageFileAcquisitionPort | null;
+  resolution: AssistantImageSourceResolution | null;
+  serverId?: string;
+  occurrenceKey: string;
+  unavailableMessage: string;
+}): AssistantImageAcquisition | null {
+  if (input.resolution?.kind !== "file_rpc") {
+    return null;
+  }
+  const { port, resolution } = input;
+  return {
+    key: createAssistantImageFileAcquisitionKey({
+      serverId: input.serverId,
+      occurrenceKey: input.occurrenceKey,
+      cwd: resolution.cwd,
+      path: resolution.path,
+    }),
+    locate: async () => {
+      if (!port) {
+        throw new Error(input.unavailableMessage);
+      }
+      const file = await port.readFile(resolution.cwd, resolution.path);
+      if (file.kind !== "image") {
+        throw new Error(input.unavailableMessage);
+      }
+      return await port.persist({
+        id: createAssistantImageFilePreviewAttachmentId({
+          serverId: input.serverId,
+          occurrenceKey: input.occurrenceKey,
+          mimeType: file.mime,
+          path: file.path || resolution.path,
+          size: file.size,
+          modifiedAt: file.modifiedAt,
+          contentLength: file.bytes.byteLength,
+        }),
+        bytes: file.bytes,
+        mimeType: file.mime,
+        fileName: getFileNameFromPath(file.path || resolution.path),
+      });
+    },
+  };
+}

packages/app/src/assistant-image/lifecycle.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { createAssistantImageLifecycle, transitionAssistantImageLifecycle } from "./lifecycle";
+
+describe("assistant image lifecycle", () => {
+  it("keeps preview URL recreation in the public loading state", () => {
+    const loading = transitionAssistantImageLifecycle(createAssistantImageLifecycle(), {
+      type: "preview_created",
+      uri: "blob:first",
+      aspectRatio: null,
+    });
+    const loaded = transitionAssistantImageLifecycle(loading, {
+      type: "image_loaded",
+      uri: "blob:first",
+      aspectRatio: 1.5,
+    });
+
+    const recreating = transitionAssistantImageLifecycle(loaded, {
+      type: "preview_released",
+    });
+
+    expect(recreating).toEqual({ status: "loading", uri: null, aspectRatio: null });
+  });
+
+  it("publishes loaded only after the recreated URL loads", () => {
+    const recreating = transitionAssistantImageLifecycle(createAssistantImageLifecycle(), {
+      type: "preview_created",
+      uri: "blob:recreated",
+      aspectRatio: 1.5,
+    });
+
+    expect(recreating).toEqual({
+      status: "loading",
+      uri: "blob:recreated",
+      aspectRatio: 1.5,
+    });
+
+    const recreated = transitionAssistantImageLifecycle(recreating, {
+      type: "image_loaded",
+      uri: "blob:recreated",
+      aspectRatio: 0.75,
+    });
+
+    expect(recreated).toEqual({
+      status: "loaded",
+      uri: "blob:recreated",
+      aspectRatio: 0.75,
+    });
+  });
+
+  it("does not reset a loaded image when the same preview is reported again", () => {
+    const loading = transitionAssistantImageLifecycle(createAssistantImageLifecycle(), {
+      type: "preview_created",
+      uri: "blob:current",
+      aspectRatio: null,
+    });
+    const loaded = transitionAssistantImageLifecycle(loading, {
+      type: "image_loaded",
+      uri: "blob:current",
+      aspectRatio: 1.5,
+    });
+
+    const repeated = transitionAssistantImageLifecycle(loaded, {
+      type: "preview_created",
+      uri: "blob:current",
+      aspectRatio: 1.5,
+    });
+
+    expect(repeated).toBe(loaded);
+  });
+
+  it("publishes failed for a terminal image failure on the current URI", () => {
+    const loading = transitionAssistantImageLifecycle(createAssistantImageLifecycle(), {
+      type: "preview_created",
+      uri: "blob:current",
+      aspectRatio: null,
+    });
+    const failed = transitionAssistantImageLifecycle(loading, {
+      type: "failed",
+      uri: "blob:current",
+      message: "Unable to load image preview.",
+    });
+
+    expect(failed).toEqual({
+      status: "failed",
+      message: "Unable to load image preview.",
+    });
+  });
+
+  it("ignores a stale load callback from a replaced URI", () => {
+    const current = transitionAssistantImageLifecycle(createAssistantImageLifecycle(), {
+      type: "preview_created",
+      uri: "blob:current",
+      aspectRatio: 1.25,
+    });
+
+    const afterStaleLoad = transitionAssistantImageLifecycle(current, {
+      type: "image_loaded",
+      uri: "blob:released",
+      aspectRatio: 2,
+    });
+
+    expect(afterStaleLoad).toEqual(current);
+  });
+
+  it("ignores a stale error callback from a replaced URI", () => {
+    const current = transitionAssistantImageLifecycle(createAssistantImageLifecycle(), {
+      type: "preview_created",
+      uri: "blob:current",
+      aspectRatio: null,
+    });
+
+    const afterStaleError = transitionAssistantImageLifecycle(current, {
+      type: "failed",
+      uri: "blob:released",
+      message: "Image unavailable",
+    });
+
+    expect(afterStaleError).toEqual(current);
+  });
+});

packages/app/src/assistant-image/lifecycle.ts

@@ -0,0 +1,46 @@
+export type AssistantImageLifecycle =
+  | { status: "loading"; uri: string | null; aspectRatio: number | null }
+  | { status: "loaded"; uri: string; aspectRatio: number }
+  | { status: "failed"; message: string };
+
+export type AssistantImageLifecycleEvent =
+  | { type: "preview_created"; uri: string; aspectRatio: number | null }
+  | { type: "preview_released" }
+  | { type: "image_loaded"; uri: string; aspectRatio: number }
+  | { type: "failed"; uri: string; message: string };
+
+export function createAssistantImageLifecycle(): AssistantImageLifecycle {
+  return { status: "loading", uri: null, aspectRatio: null };
+}
+
+export function transitionAssistantImageLifecycle(
+  state: AssistantImageLifecycle,
+  event: AssistantImageLifecycleEvent,
+): AssistantImageLifecycle {
+  if (event.type === "image_loaded") {
+    if (state.status !== "loading" || state.uri !== event.uri) {
+      return state;
+    }
+    return {
+      status: "loaded",
+      uri: event.uri,
+      aspectRatio: event.aspectRatio,
+    };
+  }
+  if (event.type === "failed") {
+    if (state.status === "failed" || state.uri !== event.uri) {
+      return state;
+    }
+    return { status: "failed", message: event.message };
+  }
+  if (event.type === "preview_created") {
+    if (state.status === "loaded" && state.uri === event.uri) {
+      return state;
+    }
+    return { status: "loading", uri: event.uri, aspectRatio: event.aspectRatio };
+  }
+  if (event.type === "preview_released") {
+    return { status: "loading", uri: null, aspectRatio: null };
+  }
+  return state;
+}

packages/app/src/assistant-image/load-dimensions.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import {
+  type AssistantImageRenderedDimensionsReader,
+  resolveAssistantImageLoadDimensions,
+} from "./load-dimensions";
+
+class MemoryRenderedDimensionsReader implements AssistantImageRenderedDimensionsReader {
+  constructor(private readonly dimensions: { width: number; height: number } | null) {}
+
+  read(): { width: number; height: number } | null {
+    return this.dimensions;
+  }
+}
+
+describe("assistant image load dimensions", () => {
+  it("prefers native source dimensions", () => {
+    const dimensions = resolveAssistantImageLoadDimensions({
+      source: { width: 640, height: 320 },
+      target: { naturalWidth: 800, naturalHeight: 400 },
+      renderedImage: null,
+      renderedDimensions: new MemoryRenderedDimensionsReader({ width: 900, height: 600 }),
+    });
+
+    expect(dimensions).toEqual({ width: 640, height: 320 });
+  });
+
+  it("uses browser event dimensions when native dimensions are absent", () => {
+    const dimensions = resolveAssistantImageLoadDimensions({
+      source: { width: 0, height: 0 },
+      target: { naturalWidth: 800, naturalHeight: 400 },
+      renderedImage: null,
+      renderedDimensions: new MemoryRenderedDimensionsReader({ width: 900, height: 600 }),
+    });
+
+    expect(dimensions).toEqual({ width: 800, height: 400 });
+  });
+
+  it("falls back to the rendered image adapter", () => {
+    const renderedImage = { id: "rendered-image" };
+    const dimensions = resolveAssistantImageLoadDimensions({
+      target: null,
+      renderedImage,
+      renderedDimensions: new MemoryRenderedDimensionsReader({ width: 900, height: 600 }),
+    });
+
+    expect(dimensions).toEqual({ width: 900, height: 600 });
+  });
+});

packages/app/src/assistant-image/load-dimensions.ts

@@ -0,0 +1,45 @@
+export interface AssistantImageDimensions {
+  width: number;
+  height: number;
+}
+
+interface AssistantImageDimensionCandidate {
+  width?: unknown;
+  height?: unknown;
+}
+
+export interface AssistantImageRenderedDimensionsReader {
+  read(renderedImage: unknown): AssistantImageDimensions | null;
+}
+
+function readPositiveDimensions(
+  candidate: AssistantImageDimensionCandidate | null | undefined,
+): AssistantImageDimensions | null {
+  if (
+    typeof candidate?.width !== "number" ||
+    typeof candidate.height !== "number" ||
+    candidate.width <= 0 ||
+    candidate.height <= 0
+  ) {
+    return null;
+  }
+  return { width: candidate.width, height: candidate.height };
+}
+
+export function resolveAssistantImageLoadDimensions(input: {
+  source?: AssistantImageDimensionCandidate | null;
+  target?: { naturalWidth?: unknown; naturalHeight?: unknown } | null;
+  renderedImage: unknown;
+  renderedDimensions: AssistantImageRenderedDimensionsReader;
+}): AssistantImageDimensions | null {
+  const source = readPositiveDimensions(input.source);
+  if (source) {
+    return source;
+  }
+
+  const target = readPositiveDimensions({
+    width: input.target?.naturalWidth,
+    height: input.target?.naturalHeight,
+  });
+  return target ?? input.renderedDimensions.read(input.renderedImage);
+}

packages/app/src/assistant-image/retry.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { runAssistantImageOperationWithRetry } from "./retry";
+
+describe("assistant image retry", () => {
+  it("recovers from transient failures while the image remains mounted", async () => {
+    const waits: number[] = [];
+    let attempts = 0;
+
+    const result = await runAssistantImageOperationWithRetry({
+      operation: async () => {
+        attempts += 1;
+        if (attempts < 3) {
+          throw new Error("transient");
+        }
+        return "loaded";
+      },
+      delaysMs: [10, 20, 30],
+      wait: async (delayMs) => {
+        waits.push(delayMs);
+      },
+    });
+
+    expect({ attempts, waits, result }).toEqual({
+      attempts: 3,
+      waits: [10, 20],
+      result: "loaded",
+    });
+  });
+
+  it("stops retrying after the image is released", async () => {
+    let stopped = false;
+    let attempts = 0;
+
+    await expect(
+      runAssistantImageOperationWithRetry({
+        operation: async () => {
+          attempts += 1;
+          throw new Error("transient");
+        },
+        delaysMs: [10, 20],
+        shouldStop: () => stopped,
+        wait: async () => {
+          stopped = true;
+        },
+      }),
+    ).rejects.toThrow("transient");
+    expect(attempts).toBe(1);
+  });
+});

packages/app/src/assistant-image/retry.ts

@@ -0,0 +1,31 @@
+export const ASSISTANT_IMAGE_RETRY_DELAYS_MS = [100, 400, 1_200] as const;
+
+export async function runAssistantImageOperationWithRetry<T>(input: {
+  operation: () => Promise<T>;
+  delaysMs?: readonly number[];
+  shouldStop?: () => boolean;
+  wait?: (delayMs: number) => Promise<void>;
+}): Promise<T> {
+  const delays = input.delaysMs ?? ASSISTANT_IMAGE_RETRY_DELAYS_MS;
+  const shouldStop = input.shouldStop ?? (() => false);
+  const wait =
+    input.wait ??
+    (async (delayMs: number) => {
+      await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
+    });
+
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await input.operation();
+    } catch (error) {
+      const delay = delays[attempt];
+      if (delay === undefined || shouldStop()) {
+        throw error;
+      }
+      await wait(delay);
+      if (shouldStop()) {
+        throw error;
+      }
+    }
+  }
+}

packages/app/src/assistant-image/use-assistant-image.ts

@@ -0,0 +1,544 @@
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+} from "react";
+import type { ImageLoadEvent } from "react-native";
+import { useTranslation } from "react-i18next";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { AttachmentMetadata } from "@/attachments/types";
+import { isWeb } from "@/constants/platform";
+import { useStableEvent } from "@/hooks/use-stable-event";
+import { retainAttachmentForGarbageCollection } from "@/attachments/gc-retention";
+import {
+  persistAttachmentFromBytes,
+  persistAttachmentFromDataUrl,
+  releaseAttachmentPreviewUrl,
+  resolveAttachmentPreviewUrl,
+} from "@/attachments/service";
+import { createPreviewAttachmentId, parseImageDataUrl } from "@/attachments/utils";
+import {
+  getAssistantImageMetadata,
+  setAssistantImageMetadata,
+} from "@/utils/assistant-image-metadata";
+import { resolveAssistantImageSource } from "@/utils/assistant-image-source";
+import { createAssistantImageAcquisitionCache } from "./acquisition-cache";
+import {
+  createAssistantImageFileAcquisition,
+  type AssistantImageAcquisition,
+  type AssistantImageFileAcquisitionPort,
+} from "./file-acquisition";
+import {
+  createAssistantImageLifecycle,
+  transitionAssistantImageLifecycle,
+  type AssistantImageLifecycle,
+  type AssistantImageLifecycleEvent,
+} from "./lifecycle";
+import {
+  type AssistantImageRenderedDimensionsReader,
+  resolveAssistantImageLoadDimensions,
+} from "./load-dimensions";
+import { runAssistantImageOperationWithRetry } from "./retry";
+
+interface AssistantImageRenderBinding {
+  uri: string;
+  onRef: (instance: unknown) => void;
+  onLoad: (event: ImageLoadEvent) => void;
+  onError: () => void;
+}
+
+const renderedDimensions: AssistantImageRenderedDimensionsReader = {
+  read(renderedImage) {
+    if (!isWeb || !(renderedImage instanceof HTMLElement)) {
+      return null;
+    }
+    const image = renderedImage.querySelector("img");
+    return image && image.naturalWidth > 0 && image.naturalHeight > 0
+      ? { width: image.naturalWidth, height: image.naturalHeight }
+      : null;
+  },
+};
+
+export type AssistantImageResult =
+  | {
+      status: "loading";
+      binding: AssistantImageRenderBinding | null;
+      aspectRatio: number | null;
+    }
+  | {
+      status: "loaded";
+      binding: AssistantImageRenderBinding;
+      aspectRatio: number;
+    }
+  | { status: "failed"; message: string };
+
+interface UseAssistantImageInput {
+  source: string;
+  occurrenceKey: string;
+  client?: DaemonClient | null;
+  workspaceRoot?: string;
+  serverId?: string;
+}
+
+type PreviewUrlState =
+  | { status: "waiting" }
+  | { status: "loading" }
+  | { status: "loaded"; uri: string }
+  | { status: "failed"; error: unknown };
+
+type AttachmentAcquisitionState =
+  | { status: "waiting" }
+  | { status: "loading" }
+  | { status: "loaded"; attachment: AttachmentMetadata }
+  | { status: "failed"; error: unknown };
+
+interface DataImage {
+  mimeType: string;
+  base64: string;
+  cacheKey: string;
+}
+
+const attachmentAcquisitionCache = createAssistantImageAcquisitionCache<AttachmentMetadata>({
+  capacity: 500,
+  onRetain: (attachment) => retainAttachmentForGarbageCollection(attachment.id),
+});
+
+interface CachedPreviewUrl {
+  attachment: AttachmentMetadata;
+  uri: string;
+}
+
+const previewUrlCache = createAssistantImageAcquisitionCache<CachedPreviewUrl>({
+  capacity: 500,
+  onRetain:
+    ({ attachment, uri }) =>
+    () => {
+      void releaseAttachmentPreviewUrl({ attachment, url: uri });
+    },
+});
+
+const LOADED_IMAGE_CACHE_CAPACITY = 500;
+const loadedImageCache = new Map<string, number>();
+
+function getLoadedImageAspectRatio(uri: string): number | null {
+  const aspectRatio = loadedImageCache.get(uri);
+  if (aspectRatio === undefined) {
+    return null;
+  }
+  loadedImageCache.delete(uri);
+  loadedImageCache.set(uri, aspectRatio);
+  return aspectRatio;
+}
+
+function rememberLoadedImage(uri: string, aspectRatio: number): void {
+  loadedImageCache.delete(uri);
+  loadedImageCache.set(uri, aspectRatio);
+  if (loadedImageCache.size <= LOADED_IMAGE_CACHE_CAPACITY) {
+    return;
+  }
+  const leastRecentlyUsedUri = loadedImageCache.keys().next().value;
+  if (leastRecentlyUsedUri !== undefined) {
+    loadedImageCache.delete(leastRecentlyUsedUri);
+  }
+}
+
+function useAttachmentAcquisition(
+  acquisition: AssistantImageAcquisition | null,
+): AttachmentAcquisitionState {
+  const acquisitionKey = acquisition?.key ?? null;
+  const [entry, setEntry] = useState<{
+    key: string | null;
+    state: AttachmentAcquisitionState;
+  }>(() => {
+    const cached = acquisitionKey ? attachmentAcquisitionCache.peek(acquisitionKey) : undefined;
+    return {
+      key: acquisitionKey,
+      state: cached ? { status: "loaded", attachment: cached } : { status: "waiting" },
+    };
+  });
+
+  useEffect(() => {
+    let disposed = false;
+    let releaseCurrent: (() => void) | null = null;
+    if (!acquisition || !acquisitionKey) {
+      setEntry({ key: null, state: { status: "waiting" } });
+      return;
+    }
+
+    const acquireCurrent = () => {
+      releaseCurrent?.();
+      const retained = attachmentAcquisitionCache.acquireRetained(
+        acquisitionKey,
+        acquisition.locate,
+      );
+      releaseCurrent = retained.release;
+      return retained;
+    };
+    const initial = acquireCurrent();
+    if (initial.value) {
+      setEntry({ key: acquisitionKey, state: { status: "loaded", attachment: initial.value } });
+      return () => {
+        disposed = true;
+        releaseCurrent?.();
+      };
+    }
+
+    setEntry({ key: acquisitionKey, state: { status: "loading" } });
+    void (async () => {
+      let firstAttempt: ReturnType<typeof acquireCurrent> | null = initial;
+      try {
+        const attachment = await runAssistantImageOperationWithRetry({
+          operation: async () => {
+            const retained = firstAttempt ?? acquireCurrent();
+            firstAttempt = null;
+            return await retained.promise;
+          },
+          shouldStop: () => disposed,
+        });
+        if (!disposed) {
+          setEntry({ key: acquisitionKey, state: { status: "loaded", attachment } });
+        }
+      } catch (error) {
+        if (!disposed) {
+          setEntry({ key: acquisitionKey, state: { status: "failed", error } });
+        }
+      }
+    })();
+    return () => {
+      disposed = true;
+      releaseCurrent?.();
+    };
+  }, [acquisition, acquisitionKey]);
+
+  if (!acquisitionKey) {
+    return { status: "waiting" };
+  }
+  const cached = attachmentAcquisitionCache.peek(acquisitionKey);
+  if (cached) {
+    return { status: "loaded", attachment: cached };
+  }
+  return entry.key === acquisitionKey ? entry.state : { status: "waiting" };
+}
+
+function createDataImageAcquisition(input: {
+  source: string;
+  dataImage: DataImage | null;
+}): AssistantImageAcquisition | null {
+  if (!input.dataImage) {
+    return null;
+  }
+  const { dataImage, source } = input;
+  return {
+    key: dataImage.cacheKey,
+    locate: async () =>
+      await persistAttachmentFromDataUrl({
+        id: createPreviewAttachmentId({
+          mimeType: dataImage.mimeType,
+          contentLength: dataImage.base64.length,
+          contentKey: dataImage.cacheKey,
+        }),
+        dataUrl: source,
+        mimeType: dataImage.mimeType,
+      }),
+  };
+}
+
+function usePreviewUrl(attachment: AttachmentMetadata | null | undefined): PreviewUrlState {
+  const id = attachment?.id;
+  const storageType = attachment?.storageType;
+  const storageKey = attachment?.storageKey;
+  const mimeType = attachment?.mimeType;
+  const previewKey =
+    id && storageType && storageKey && mimeType
+      ? `${id}:${storageType}:${storageKey}:${mimeType}`
+      : null;
+  const [entry, setEntry] = useState<{ key: string | null; state: PreviewUrlState }>(() => {
+    return {
+      key: previewKey,
+      state: { status: "waiting" },
+    };
+  });
+  const getCurrentAttachment = useStableEvent(() => attachment ?? null);
+
+  useLayoutEffect(() => {
+    let disposed = false;
+    let releaseCurrent: (() => void) | null = null;
+    const current = getCurrentAttachment();
+
+    if (!current || !previewKey) {
+      setEntry({ key: null, state: { status: "waiting" } });
+      return;
+    }
+
+    const acquireCurrent = () => {
+      releaseCurrent?.();
+      const retained = previewUrlCache.acquireRetained(previewKey, async () => ({
+        attachment: current,
+        uri: await resolveAttachmentPreviewUrl(current),
+      }));
+      releaseCurrent = retained.release;
+      return retained;
+    };
+    const initial = acquireCurrent();
+    if (initial.value) {
+      setEntry({ key: previewKey, state: { status: "loaded", uri: initial.value.uri } });
+      return () => {
+        disposed = true;
+        releaseCurrent?.();
+      };
+    }
+
+    setEntry({ key: previewKey, state: { status: "loading" } });
+    void (async () => {
+      let firstAttempt: ReturnType<typeof acquireCurrent> | null = initial;
+      try {
+        const preview = await runAssistantImageOperationWithRetry({
+          operation: async () => {
+            const retained = firstAttempt ?? acquireCurrent();
+            firstAttempt = null;
+            return await retained.promise;
+          },
+          shouldStop: () => disposed,
+        });
+        if (!disposed) {
+          setEntry({ key: previewKey, state: { status: "loaded", uri: preview.uri } });
+        }
+      } catch (error) {
+        if (!disposed) {
+          setEntry({ key: previewKey, state: { status: "failed", error } });
+        }
+      }
+    })();
+
+    return () => {
+      disposed = true;
+      releaseCurrent?.();
+    };
+  }, [getCurrentAttachment, previewKey]);
+
+  if (!previewKey) {
+    return { status: "waiting" };
+  }
+  return entry.key === previewKey ? entry.state : { status: "waiting" };
+}
+
+function lifecycleReducer(
+  state: AssistantImageLifecycle,
+  event: AssistantImageLifecycleEvent,
+): AssistantImageLifecycle {
+  return transitionAssistantImageLifecycle(state, event);
+}
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error ? error.message : fallback;
+}
+
+function getAcquisitionFailure(input: {
+  hasResolution: boolean;
+  isFileSource: boolean;
+  isDataImage: boolean;
+  fileAttachment: AttachmentAcquisitionState;
+  dataImageAttachment: AttachmentAcquisitionState;
+  preview: PreviewUrlState;
+  hasDirectUri: boolean;
+  fallbackMessage: string;
+}): AssistantImageResult | null {
+  if (!input.hasResolution) {
+    return { status: "failed", message: input.fallbackMessage };
+  }
+  if (input.isFileSource && input.fileAttachment.status === "failed") {
+    return {
+      status: "failed",
+      message: errorMessage(input.fileAttachment.error, input.fallbackMessage),
+    };
+  }
+  if (input.isDataImage && input.dataImageAttachment.status === "failed") {
+    return {
+      status: "failed",
+      message: errorMessage(input.dataImageAttachment.error, input.fallbackMessage),
+    };
+  }
+  if (!input.hasDirectUri && input.preview.status === "failed") {
+    return {
+      status: "failed",
+      message: errorMessage(input.preview.error, input.fallbackMessage),
+    };
+  }
+  return null;
+}
+
+export function useAssistantImage({
+  source,
+  occurrenceKey,
+  client,
+  workspaceRoot,
+  serverId,
+}: UseAssistantImageInput): AssistantImageResult {
+  const { t } = useTranslation();
+  const resolution = useMemo(
+    () => resolveAssistantImageSource({ source, workspaceRoot }),
+    [source, workspaceRoot],
+  );
+  const dataImage = useMemo(() => parseImageDataUrl(source), [source]);
+  const fileAcquisition = useMemo(() => {
+    const port: AssistantImageFileAcquisitionPort | null = client
+      ? {
+          readFile: async (cwd, path) => await client.readFile(cwd, path),
+          persist: persistAttachmentFromBytes,
+        }
+      : null;
+    return createAssistantImageFileAcquisition({
+      port,
+      resolution,
+      serverId,
+      occurrenceKey,
+      unavailableMessage: t("message.attachments.imagePreviewUnavailable"),
+    });
+  }, [client, occurrenceKey, resolution, serverId, t]);
+  const dataImageAcquisition = useMemo(
+    () => createDataImageAcquisition({ source, dataImage }),
+    [dataImage, source],
+  );
+  const fileAttachment = useAttachmentAcquisition(fileAcquisition);
+  const dataImageAttachment = useAttachmentAcquisition(dataImageAcquisition);
+  const filePreview = usePreviewUrl(
+    fileAttachment.status === "loaded" ? fileAttachment.attachment : null,
+  );
+  const dataImagePreview = usePreviewUrl(
+    dataImageAttachment.status === "loaded" ? dataImageAttachment.attachment : null,
+  );
+  const directUri = resolution?.kind === "direct" && !dataImage ? resolution.uri : null;
+  const preview = dataImage ? dataImagePreview : filePreview;
+  const previewUri = preview.status === "loaded" ? preview.uri : null;
+  const uri = directUri ?? previewUri;
+  const cachedMetadata = useMemo(
+    () => getAssistantImageMetadata({ source, workspaceRoot, serverId }),
+    [serverId, source, workspaceRoot],
+  );
+  const [lifecycle, dispatchLifecycle] = useReducer(
+    lifecycleReducer,
+    uri,
+    (initialUri): AssistantImageLifecycle => {
+      if (initialUri) {
+        const aspectRatio = getLoadedImageAspectRatio(initialUri);
+        if (aspectRatio !== null) {
+          return { status: "loaded", uri: initialUri, aspectRatio };
+        }
+      }
+      return createAssistantImageLifecycle();
+    },
+  );
+  const dispatch = useCallback((event: AssistantImageLifecycleEvent) => {
+    if (event.type === "image_loaded") {
+      rememberLoadedImage(event.uri, event.aspectRatio);
+    } else if (event.type === "failed" && event.uri) {
+      loadedImageCache.delete(event.uri);
+    }
+    dispatchLifecycle(event);
+  }, []);
+  const renderedImageRef = useRef<unknown>(null);
+  const handleImageRef = useCallback((instance: unknown) => {
+    renderedImageRef.current = instance;
+  }, []);
+
+  useEffect(() => {
+    if (!uri) {
+      dispatch({ type: "preview_released" });
+      return;
+    }
+
+    dispatch({
+      type: "preview_created",
+      uri,
+      aspectRatio: cachedMetadata?.aspectRatio ?? null,
+    });
+  }, [cachedMetadata, dispatch, uri]);
+
+  const handleImageError = useCallback(() => {
+    if (uri) {
+      dispatch({
+        type: "failed",
+        uri,
+        message: t("message.attachments.imageUnavailable"),
+      });
+    }
+  }, [dispatch, t, uri]);
+  const handleImageLoad = useCallback(
+    (event: ImageLoadEvent) => {
+      if (!uri) {
+        return;
+      }
+      const nativeEvent = event.nativeEvent as ImageLoadEvent["nativeEvent"] & {
+        target?: { naturalWidth?: unknown; naturalHeight?: unknown };
+      };
+      const dimensions = resolveAssistantImageLoadDimensions({
+        source: nativeEvent.source,
+        target: nativeEvent.target,
+        renderedImage: renderedImageRef.current,
+        renderedDimensions,
+      });
+      const metadata = dimensions
+        ? setAssistantImageMetadata({ source, workspaceRoot, serverId }, dimensions)
+        : null;
+      const aspectRatio = metadata?.aspectRatio ?? cachedMetadata?.aspectRatio ?? null;
+      if (!aspectRatio) {
+        dispatch({
+          type: "failed",
+          uri,
+          message: t("message.attachments.imageUnavailable"),
+        });
+        return;
+      }
+      dispatch({ type: "image_loaded", uri, aspectRatio });
+    },
+    [cachedMetadata, dispatch, serverId, source, t, uri, workspaceRoot],
+  );
+
+  const acquisitionFailure = getAcquisitionFailure({
+    hasResolution: resolution !== null,
+    isFileSource: resolution?.kind === "file_rpc",
+    isDataImage: dataImage !== null,
+    fileAttachment,
+    dataImageAttachment,
+    preview,
+    hasDirectUri: directUri !== null,
+    fallbackMessage: t("message.attachments.imagePreviewLoadFailed"),
+  });
+  if (acquisitionFailure) {
+    return acquisitionFailure;
+  }
+  const hasCurrentLifecycleUri = lifecycle.status !== "failed" && lifecycle.uri === uri;
+  let binding: AssistantImageRenderBinding | null = null;
+  if (hasCurrentLifecycleUri && lifecycle.uri) {
+    binding = {
+      uri: lifecycle.uri,
+      onRef: handleImageRef,
+      onLoad: handleImageLoad,
+      onError: handleImageError,
+    };
+  }
+  if (lifecycle.status === "loaded" && lifecycle.uri === uri) {
+    return {
+      status: "loaded",
+      binding: {
+        uri: lifecycle.uri,
+        onRef: handleImageRef,
+        onLoad: handleImageLoad,
+        onError: handleImageError,
+      },
+      aspectRatio: lifecycle.aspectRatio,
+    };
+  }
+  if (lifecycle.status === "failed") {
+    return lifecycle;
+  }
+  return {
+    status: "loading",
+    binding,
+    aspectRatio: hasCurrentLifecycleUri ? lifecycle.aspectRatio : null,
+  };
+}

packages/app/src/attachments/file-types.test.ts

@@ -6,6 +6,7 @@ import {
   isRasterImageMimeType,
   isRasterImagePath,
   RASTER_IMAGE_FILE_EXTENSIONS,
+  resolveRasterImageMimeType,
 } from "./file-types";
 
 describe("attachment file types", () => {
@@ -37,4 +38,28 @@ describe("attachment file types", () => {
       new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp", "heic", "heif", "avif", "tif", "tiff"]),
     );
   });
+
+  it("uses explicit raster MIME metadata before the filename", () => {
+    expect(
+      resolveRasterImageMimeType({ mimeType: "image/jpeg", path: "/tmp/screenshot.png" }),
+    ).toBe("image/jpeg");
+    expect(
+      resolveRasterImageMimeType({
+        mimeType: "image/png; charset=binary",
+        path: "/tmp/screenshot.jpg",
+      }),
+    ).toBe("image/png");
+  });
+
+  it("uses the filename only when MIME metadata is absent", () => {
+    expect(resolveRasterImageMimeType({ mimeType: "", path: "/tmp/screenshot.png" })).toBe(
+      "image/png",
+    );
+    expect(
+      resolveRasterImageMimeType({
+        mimeType: "application/octet-stream",
+        path: "/tmp/screenshot.png",
+      }),
+    ).toBeNull();
+  });
 });

packages/app/src/attachments/file-types.ts

@@ -41,18 +41,31 @@ export function getRasterImageMimeTypeFromPath(path: string): string | null {
   return RASTER_IMAGE_MIME_TYPE_BY_EXTENSION[getFileExtension(path)] ?? null;
 }
 
+export function resolveRasterImageMimeType(input: {
+  mimeType?: string | null;
+  path?: string | null;
+}): string | null {
+  const suppliedMimeType = input.mimeType?.trim();
+  if (suppliedMimeType) {
+    const normalizedMimeType = suppliedMimeType.split(";", 1)[0]?.trim().toLowerCase();
+    if (normalizedMimeType === "image/jpg") {
+      return "image/jpeg";
+    }
+    return normalizedMimeType && RASTER_IMAGE_MIME_TYPES.has(normalizedMimeType)
+      ? normalizedMimeType
+      : null;
+  }
+  return input.path ? getRasterImageMimeTypeFromPath(input.path) : null;
+}
+
 export function isRasterImagePath(path: string): boolean {
   return getRasterImageMimeTypeFromPath(path) !== null;
 }
 
 export function isRasterImageMimeType(mimeType: string | null | undefined): boolean {
-  const normalized = mimeType?.split(";", 1)[0]?.trim().toLowerCase();
-  return Boolean(normalized && RASTER_IMAGE_MIME_TYPES.has(normalized));
+  return resolveRasterImageMimeType({ mimeType }) !== null;
 }
 
 export function isRasterImageFile(file: Pick<File, "name" | "type">): boolean {
-  if (isRasterImageMimeType(file.type)) {
-    return true;
-  }
-  return file.type.trim().length === 0 && isRasterImagePath(file.name);
+  return resolveRasterImageMimeType({ mimeType: file.type, path: file.name }) !== null;
 }

packages/app/src/attachments/gc-retention.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { collectRetainedAttachmentIds, retainAttachmentForGarbageCollection } from "./gc-retention";
+
+describe("attachment garbage-collection retention", () => {
+  it("keeps an attachment referenced until its final owner releases it", () => {
+    const releaseFirst = retainAttachmentForGarbageCollection("preview-1");
+    const releaseSecond = retainAttachmentForGarbageCollection("preview-1");
+
+    expect(collectRetainedAttachmentIds()).toContain("preview-1");
+    releaseFirst();
+    expect(collectRetainedAttachmentIds()).toContain("preview-1");
+    releaseSecond();
+    expect(collectRetainedAttachmentIds()).not.toContain("preview-1");
+  });
+});

packages/app/src/attachments/gc-retention.ts

@@ -0,0 +1,22 @@
+const retentionCounts = new Map<string, number>();
+
+export function retainAttachmentForGarbageCollection(attachmentId: string): () => void {
+  retentionCounts.set(attachmentId, (retentionCounts.get(attachmentId) ?? 0) + 1);
+  let released = false;
+  return () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    const nextCount = (retentionCounts.get(attachmentId) ?? 1) - 1;
+    if (nextCount <= 0) {
+      retentionCounts.delete(attachmentId);
+      return;
+    }
+    retentionCounts.set(attachmentId, nextCount);
+  };
+}
+
+export function collectRetainedAttachmentIds(): ReadonlySet<string> {
+  return new Set(retentionCounts.keys());
+}

packages/app/src/attachments/service.test.ts

@@ -1,7 +1,11 @@
 import { afterEach, describe, expect, it } from "vitest";
 import type { AttachmentMetadata, AttachmentStore, SaveAttachmentInput } from "@/attachments/types";
 import { __setAttachmentStoreForTests } from "./store";
-import { encodeAttachmentsForSend, persistAttachmentFromBytes } from "./service";
+import {
+  encodeAttachmentsForSend,
+  garbageCollectAttachments,
+  persistAttachmentFromBytes,
+} from "./service";
 
 function createAttachment(input: Partial<AttachmentMetadata> = {}): AttachmentMetadata {
   return {
@@ -94,4 +98,46 @@ describe("attachment service", () => {
       { data: "att_send:base64", mimeType: "image/jpeg" },
     ]);
   });
+
+  it("does not collect an attachment persisted while garbage collection is starting", async () => {
+    let releaseSave: () => void = () => undefined;
+    let reportSaveStarted: () => void = () => undefined;
+    const saveStarted = new Promise<void>((resolve) => {
+      reportSaveStarted = resolve;
+    });
+    const saveGate = new Promise<void>((resolve) => {
+      releaseSave = resolve;
+    });
+    const garbageCollections: string[][] = [];
+    const store: AttachmentStore = {
+      ...createRecordingStore(),
+      async save(input) {
+        reportSaveStarted();
+        await saveGate;
+        return createAttachment({ id: input.id });
+      },
+      async garbageCollect({ referencedIds }) {
+        garbageCollections.push([...referencedIds]);
+      },
+    };
+    __setAttachmentStoreForTests(store);
+
+    const persist = persistAttachmentFromBytes({
+      id: "assistant-preview",
+      bytes: new Uint8Array([1, 2, 3]),
+      mimeType: "image/png",
+    });
+    await saveStarted;
+    const collect = garbageCollectAttachments({ referencedIds: new Set() });
+
+    try {
+      await Promise.resolve();
+      expect(garbageCollections).toEqual([]);
+    } finally {
+      releaseSave();
+      await Promise.all([persist, collect]);
+    }
+
+    expect(garbageCollections).toEqual([["assistant-preview"]]);
+  });
 });

packages/app/src/attachments/service.ts

@@ -1,5 +1,40 @@
-import type { AttachmentMetadata } from "@/attachments/types";
+import { collectRetainedAttachmentIds } from "@/attachments/gc-retention";
 import { getAttachmentStore } from "@/attachments/store";
+import type { AttachmentMetadata, SaveAttachmentInput } from "@/attachments/types";
+
+const activePersistence = new Set<Promise<AttachmentMetadata>>();
+const persistedDuringGarbageCollection = new Set<string>();
+let pendingGarbageCollections = 0;
+let garbageCollectionTail: Promise<void> = Promise.resolve();
+let persistenceBarrier: Promise<void> | null = null;
+let releasePersistenceBarrier: (() => void) | null = null;
+
+async function waitForPersistenceBarrier(): Promise<void> {
+  const barrier = persistenceBarrier;
+  if (!barrier) {
+    return;
+  }
+  await barrier;
+  await waitForPersistenceBarrier();
+}
+
+async function persistAttachment(input: SaveAttachmentInput): Promise<AttachmentMetadata> {
+  await waitForPersistenceBarrier();
+  const pending = (async () => {
+    const store = await getAttachmentStore();
+    const attachment = await store.save(input);
+    if (pendingGarbageCollections > 0) {
+      persistedDuringGarbageCollection.add(attachment.id);
+    }
+    return attachment;
+  })();
+  activePersistence.add(pending);
+  try {
+    return await pending;
+  } finally {
+    activePersistence.delete(pending);
+  }
+}
 
 export async function persistAttachmentFromBlob(input: {
   blob: Blob;
@@ -7,8 +42,7 @@ export async function persistAttachmentFromBlob(input: {
   fileName?: string | null;
   id?: string;
 }): Promise<AttachmentMetadata> {
-  const store = await getAttachmentStore();
-  return await store.save({
+  return await persistAttachment({
     id: input.id,
     mimeType: input.mimeType,
     fileName: input.fileName,
@@ -22,8 +56,7 @@ export async function persistAttachmentFromDataUrl(input: {
   fileName?: string | null;
   id?: string;
 }): Promise<AttachmentMetadata> {
-  const store = await getAttachmentStore();
-  return await store.save({
+  return await persistAttachment({
     id: input.id,
     mimeType: input.mimeType,
     fileName: input.fileName,
@@ -37,8 +70,7 @@ export async function persistAttachmentFromBytes(input: {
   fileName?: string | null;
   id?: string;
 }): Promise<AttachmentMetadata> {
-  const store = await getAttachmentStore();
-  return await store.save({
+  return await persistAttachment({
     id: input.id,
     mimeType: input.mimeType,
     fileName: input.fileName,
@@ -52,8 +84,7 @@ export async function persistAttachmentFromFileUri(input: {
   fileName?: string | null;
   id?: string;
 }): Promise<AttachmentMetadata> {
-  const store = await getAttachmentStore();
-  return await store.save({
+  return await persistAttachment({
     id: input.id,
     mimeType: input.mimeType,
     fileName: input.fileName,
@@ -133,6 +164,41 @@ export async function deleteAttachments(
 export async function garbageCollectAttachments(input: {
   referencedIds: ReadonlySet<string>;
 }): Promise<void> {
-  const store = await getAttachmentStore();
-  await store.garbageCollect({ referencedIds: input.referencedIds });
+  pendingGarbageCollections += 1;
+  if (!persistenceBarrier) {
+    persistenceBarrier = new Promise<void>((resolve) => {
+      releasePersistenceBarrier = resolve;
+    });
+  }
+
+  const previousGarbageCollection = garbageCollectionTail;
+  const currentGarbageCollection = (async () => {
+    await previousGarbageCollection;
+    while (activePersistence.size > 0) {
+      await Promise.allSettled(activePersistence);
+    }
+    const referencedIds = new Set(input.referencedIds);
+    for (const id of collectRetainedAttachmentIds()) {
+      referencedIds.add(id);
+    }
+    for (const id of persistedDuringGarbageCollection) {
+      referencedIds.add(id);
+    }
+    const store = await getAttachmentStore();
+    await store.garbageCollect({ referencedIds });
+  })();
+  garbageCollectionTail = currentGarbageCollection.catch(() => undefined);
+
+  try {
+    await currentGarbageCollection;
+  } finally {
+    pendingGarbageCollections -= 1;
+    if (pendingGarbageCollections === 0) {
+      persistedDuringGarbageCollection.clear();
+      const release = releasePersistenceBarrier;
+      releasePersistenceBarrier = null;
+      persistenceBarrier = null;
+      release?.();
+    }
+  }
 }

packages/app/src/attachments/utils.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   createImageSourceCacheKey,
+  createPreviewAttachmentId,
   fileUriToPath,
   localFileSourceToPath,
   parseDataUrl,
@@ -86,4 +87,29 @@ describe("parseImageDataUrl", () => {
   it("ignores SVG data URLs", () => {
     expect(parseImageDataUrl("data:image/svg+xml;base64,PHN2ZyAvPg==")).toBeNull();
   });
+
+  it("distinguishes image data that differs only in the middle", () => {
+    const prefix = "a".repeat(64);
+    const suffix = "z".repeat(64);
+    const first = `data:image/png;base64,${prefix}${"b".repeat(256)}${suffix}`;
+    const second = `data:image/png;base64,${prefix}${"c".repeat(256)}${suffix}`;
+
+    expect(createImageSourceCacheKey(first)).not.toBe(createImageSourceCacheKey(second));
+  });
+
+  it("gives equal-length preview content distinct attachment identities", () => {
+    expect(
+      createPreviewAttachmentId({
+        mimeType: "image/png",
+        contentLength: 512,
+        contentKey: "first-content",
+      }),
+    ).not.toBe(
+      createPreviewAttachmentId({
+        mimeType: "image/png",
+        contentLength: 512,
+        contentKey: "second-content",
+      }),
+    );
+  });
 });

packages/app/src/attachments/utils.ts

@@ -56,7 +56,7 @@ export function parseImageDataUrl(
     if (!isRasterImageMimeType(parsed.mimeType)) {
       return null;
     }
-    const fingerprint = `${parsed.mimeType}\0${parsed.base64.length}\0${parsed.base64.slice(0, 64)}\0${parsed.base64.slice(-64)}`;
+    const fingerprint = `${parsed.mimeType}\0${parsed.base64}`;
     return {
       ...parsed,
       cacheKey: `data-image:${parsed.mimeType}:${parsed.base64.length}:${hashString(fingerprint)}`,
@@ -87,12 +87,15 @@ export function createPreviewAttachmentId(input: {
   size?: number | null;
   modifiedAt?: string | null;
   contentLength?: number | null;
+  contentKey?: string | null;
 }): string {
   const path = input.path?.trim() ?? "";
   const size = Number.isFinite(input.size) ? String(input.size) : "";
   const modifiedAt = input.modifiedAt?.trim() ?? "";
   const contentLength = Number.isFinite(input.contentLength) ? String(input.contentLength) : "";
-  const hash = hashString(`${input.mimeType}\0${path}\0${size}\0${modifiedAt}\0${contentLength}`);
+  const contentKey = input.contentKey?.trim() ?? "";
+  const identity = `${input.mimeType}\0${path}\0${size}\0${modifiedAt}\0${contentLength}`;
+  const hash = hashString(contentKey ? `${identity}\0${contentKey}` : identity);
   return `preview_${size || contentLength || "unknown"}_${hash}`;
 }
 

packages/app/src/command-center/command-center.tsx

@@ -31,6 +31,11 @@ import { useAggregatedAgents, type AggregatedAgent } from "@/hooks/use-aggregate
 import { useKeyboardShortcutOverrides } from "@/hooks/use-keyboard-shortcut-overrides";
 import { useOpenAddProject } from "@/hooks/use-open-add-project";
 import { useProjects } from "@/hooks/use-projects";
+import {
+  OverlayLayerProvider,
+  useGlobalWebOverlayLayer,
+  useWebOverlayRegistration,
+} from "@/lib/overlay-root";
 import { useHosts } from "@/runtime/host-runtime";
 import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
 import { navigateToWorkspace } from "@/stores/navigation-active-workspace-store";
@@ -52,6 +57,7 @@ import type { CommandCenterContribution, CommandCenterIconProps } from "./contri
 import { useCommandCenterActions, useCommandCenterContributions } from "./provider";
 import {
   buildContributionSections,
+  joinSubtitleParts,
   moveActiveResultId,
   preserveActiveResultId,
   projectCommandCenterRows,
@@ -203,7 +209,7 @@ function useBuiltInSections(open: boolean, query: string): CommandCenterResultSe
   const { t } = useTranslation();
   const { agents } = useAggregatedAgents();
   const { projects } = useProjects({ enabled: open });
-  const showAgentHost = useHosts().length > 1;
+  const showHost = useHosts().length > 1;
 
   return useMemo(() => {
     if (!open) return [];
@@ -213,9 +219,11 @@ function useBuiltInSections(open: boolean, query: string): CommandCenterResultSe
         for (const workspace of host.workspaces) {
           if (workspace.archivingAt) continue;
           const title = workspace.title ?? workspace.name;
-          const subtitle = workspace.currentBranch
-            ? `${host.serverName} · ${workspace.currentBranch}`
-            : host.serverName;
+          const subtitle = joinSubtitleParts([
+            showHost ? host.serverName : null,
+            project.projectName,
+            workspace.currentBranch,
+          ]);
           const searchText = `${title} ${subtitle}`.toLowerCase();
           allWorkspaces.push({
             kind: "workspace",
@@ -251,13 +259,11 @@ function useBuiltInSections(open: boolean, query: string): CommandCenterResultSe
           ? workspaceTitleByKey.get(`${agent.serverId}:${agent.workspaceId}`)
           : undefined;
         const location = workspaceTitle ?? shortenPath(agent.cwd);
-        const subtitle = [
-          showAgentHost ? agent.serverLabel : null,
+        const subtitle = joinSubtitleParts([
+          showHost ? agent.serverLabel : null,
           location,
           formatTimeAgo(agent.lastActivityAt),
-        ]
-          .filter((part): part is string => Boolean(part))
-          .join(" · ");
+        ]);
         return {
           kind: "agent",
           id: `agent:${agent.serverId}:${agent.id}`,
@@ -282,7 +288,7 @@ function useBuiltInSections(open: boolean, query: string): CommandCenterResultSe
       },
       { id: "agents", rank: 3, title: t("shell.commandCenter.agents"), results: agentResults },
     ];
-  }, [agents, open, projects, query, showAgentHost, t]);
+  }, [agents, open, projects, query, showHost, t]);
 }
 
 interface CommandCenterState {
@@ -371,15 +377,6 @@ function useCommandCenterState(): CommandCenterState {
     return cancel;
   }, [open]);
 
-  useEffect(() => {
-    if (!open || !isWeb) return;
-    const listener = (event: KeyboardEvent) => {
-      if (key(event.key)) event.preventDefault();
-    };
-    window.addEventListener("keydown", listener, true);
-    return () => window.removeEventListener("keydown", listener, true);
-  }, [key, open]);
-
   return {
     open,
     query,
@@ -461,7 +458,11 @@ function ResultContent({ result }: { result: CommandCenterResult }) {
             <Text style={styles.title} numberOfLines={1}>
               {result.title}
             </Text>
-            <Text style={styles.subtitle} numberOfLines={1}>
+            <Text
+              style={styles.subtitle}
+              numberOfLines={1}
+              testID="command-center-workspace-subtitle"
+            >
               {result.subtitle}
             </Text>
           </View>
@@ -548,6 +549,7 @@ export function CommandCenter() {
   const state = useCommandCenterState();
   const isCompact = useIsCompactFormFactor();
   const showBottomSheet = isCompact && isNative;
+  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb && state.open && !showBottomSheet);
   const listRef = useRef<FlatList<CommandCenterListRow>>(null);
   const bottomSheetListRef = useRef<BottomSheetFlatListMethods>(null);
   const bottomSheetInputRef = useRef<React.ElementRef<typeof BottomSheetTextInput>>(null);
@@ -613,6 +615,19 @@ export function CommandCenter() {
     [state],
   );
   const submit = useCallback(() => state.key("Enter"), [state]);
+  const handleWebOverlayKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (!state.key(event.key)) return false;
+      event.preventDefault();
+      return true;
+    },
+    [state],
+  );
+  const setWebOverlayScope = useWebOverlayRegistration({
+    active: isWeb && state.open && !showBottomSheet,
+    layer: modalLayer,
+    onKeyDown: handleWebOverlayKeyDown,
+  });
   const backdrop = useCallback(
     (props: React.ComponentProps<typeof BottomSheetBackdrop>) => (
       <BottomSheetBackdrop {...props} disappearsOnIndex={-1} appearsOnIndex={0} opacity={0.45} />
@@ -658,27 +673,29 @@ export function CommandCenter() {
   }
   if (!state.open) return null;
   return (
-    <Modal visible transparent animationType="fade" onRequestClose={state.close}>
-      <View style={styles.overlay}>
-        <Pressable style={styles.backdrop} onPress={state.close} />
-        <View testID="command-center-panel" style={styles.panel}>
-          <View style={styles.header}>
-            <ThemedTextInput
-              testID="command-center-input"
-              ref={state.inputRef}
-              value={state.query}
-              onChangeText={state.setQuery}
-              placeholder={t("shell.commandCenter.placeholder")}
-              style={styles.input}
-              autoCapitalize="none"
-              autoCorrect={false}
-              autoFocus
-            />
+    <OverlayLayerProvider layer={isWeb ? modalLayer : 0}>
+      <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 style={styles.header}>
+              <ThemedTextInput
+                testID="command-center-input"
+                ref={state.inputRef}
+                value={state.query}
+                onChangeText={state.setQuery}
+                placeholder={t("shell.commandCenter.placeholder")}
+                style={styles.input}
+                autoCapitalize="none"
+                autoCorrect={false}
+                autoFocus
+              />
+            </View>
+            <FlatList ref={listRef} style={styles.results} {...commonListProps} />
           </View>
-          <FlatList ref={listRef} style={styles.results} {...commonListProps} />
         </View>
-      </View>
-    </Modal>
+      </Modal>
+    </OverlayLayerProvider>
   );
 }
 

packages/app/src/command-center/results.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import type { CommandCenterContribution } from "./contributions";
 import {
   buildContributionSections,
+  joinSubtitleParts,
   moveActiveResultId,
   preserveActiveResultId,
   projectCommandCenterRows,
@@ -103,3 +104,35 @@ describe("Command Center result projection", () => {
     expect(projection.offsets[151]).toBe(32 + 150 * 56);
   });
 });
+
+describe("joinSubtitleParts", () => {
+  it("joins all present parts with a middle dot", () => {
+    expect(joinSubtitleParts(["a", "b", "c"])).toBe("a · b · c");
+  });
+
+  it("drops null and undefined parts", () => {
+    expect(joinSubtitleParts(["host", null, "master"])).toBe("host · master");
+    expect(joinSubtitleParts(["host", undefined, "master"])).toBe("host · master");
+  });
+
+  it("drops empty strings (Boolean parity — agents subtitle refactor guard)", () => {
+    expect(joinSubtitleParts(["", "paseo", "master"])).toBe("paseo · master");
+  });
+
+  it("returns an empty string when every part is null or empty", () => {
+    expect(joinSubtitleParts([null, undefined, ""])).toBe("");
+  });
+
+  it("returns a single part unchanged, with no separator", () => {
+    expect(joinSubtitleParts([null, "paseo", null])).toBe("paseo");
+  });
+
+  it("builds the workspace subtitle in host · project · branch order", () => {
+    // Single-host: host gated away, project leads.
+    expect(joinSubtitleParts([null, "paseo", "master"])).toBe("paseo · master");
+    // Multi-host: host first, then project, then branch.
+    expect(joinSubtitleParts(["host", "paseo", "master"])).toBe("host · paseo · master");
+    // No branch: degrades to project (or host · project).
+    expect(joinSubtitleParts([null, "paseo", null])).toBe("paseo");
+  });
+});

packages/app/src/command-center/results.ts

@@ -63,6 +63,11 @@ function matchesQuery(searchText: string, query: string): boolean {
   return !normalized || searchText.includes(normalized);
 }
 
+/** Join non-empty subtitle parts with " · ", dropping null/undefined/empty. */
+export function joinSubtitleParts(parts: readonly (string | null | undefined)[]): string {
+  return parts.filter((part): part is string => Boolean(part)).join(" · ");
+}
+
 function contributionSearchText(contribution: CommandCenterContribution): string {
   const presentationText =
     contribution.presentation.kind === "action"

packages/app/src/components/adaptive-modal-sheet.tsx

@@ -6,7 +6,12 @@ import { Modal, Platform, Pressable, ScrollView, Text, TextInput, View } from "r
 import type { StyleProp, TextInputProps, ViewStyle } from "react-native";
 import { StyleSheet, useUnistyles, withUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
-import { getOverlayRoot, OVERLAY_Z } from "../lib/overlay-root";
+import {
+  getOverlayRoot,
+  OverlayLayerProvider,
+  useGlobalWebOverlayLayer,
+  useWebOverlayRegistration,
+} from "../lib/overlay-root";
 import {
   BottomSheetBackdrop,
   BottomSheetScrollView,
@@ -54,36 +59,8 @@ export interface SheetHeader {
   search?: SheetHeaderSearch;
 }
 
-type EscHandler = () => void;
-const escStack: EscHandler[] = [];
-let escListenerAttached = false;
 const ABSOLUTE_FILL_STYLE = { ...StyleSheet.absoluteFillObject };
 
-function handleEscKeyDown(event: KeyboardEvent) {
-  if (event.key !== "Escape") return;
-  const top = escStack[escStack.length - 1];
-  if (!top) return;
-  event.stopPropagation();
-  event.preventDefault();
-  top();
-}
-
-function pushEscHandler(handler: EscHandler): () => void {
-  escStack.push(handler);
-  if (!escListenerAttached && typeof window !== "undefined") {
-    window.addEventListener("keydown", handleEscKeyDown, true);
-    escListenerAttached = true;
-  }
-  return () => {
-    const index = escStack.lastIndexOf(handler);
-    if (index !== -1) escStack.splice(index, 1);
-    if (escStack.length === 0 && escListenerAttached && typeof window !== "undefined") {
-      window.removeEventListener("keydown", handleEscKeyDown, true);
-      escListenerAttached = false;
-    }
-  };
-}
-
 const styles = StyleSheet.create((theme) => ({
   desktopOverlay: {
     ...StyleSheet.absoluteFillObject,
@@ -91,7 +68,6 @@ const styles = StyleSheet.create((theme) => ({
     justifyContent: "center",
     alignItems: "center",
     padding: theme.spacing[6],
-    zIndex: OVERLAY_Z.modal,
     pointerEvents: "auto" as const,
   },
   desktopCard: {
@@ -582,6 +558,7 @@ export function AdaptiveModalSheet({
   });
   const [shouldRenderWeb, setShouldRenderWeb] = useState(visible);
   const [isWebClosing, setIsWebClosing] = useState(false);
+  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb && !isMobile && shouldRenderWeb);
   const nativeModalDismissNotifiedRef = useRef(!visible);
   const handleDismiss = useCallback(() => {
     handleSheetDismiss();
@@ -610,19 +587,31 @@ export function AdaptiveModalSheet({
     () => [
       styles.desktopOverlay,
       isWeb && {
+        zIndex: modalLayer,
         opacity: isWebClosing ? 0 : 1,
         transitionDuration: `${WEB_EXIT_DURATION_MS}ms`,
         transitionProperty: "opacity",
         transitionTimingFunction: "ease",
       },
     ],
-    [isWebClosing],
+    [isWebClosing, modalLayer],
   );
 
-  useEffect(() => {
-    if (!isWeb || isMobile || !visible) return;
-    return pushEscHandler(onClose);
-  }, [visible, isMobile, onClose]);
+  const handleWebOverlayKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (event.key !== "Escape") return false;
+      event.preventDefault();
+      event.stopPropagation();
+      onClose();
+      return true;
+    },
+    [onClose],
+  );
+  const setWebOverlayScope = useWebOverlayRegistration({
+    active: isWeb && !isMobile && visible,
+    layer: modalLayer,
+    onKeyDown: handleWebOverlayKeyDown,
+  });
 
   useEffect(() => {
     if (visible) {
@@ -700,7 +689,7 @@ export function AdaptiveModalSheet({
   }
 
   const cardInner = (
-    <>
+    <OverlayLayerProvider layer={modalLayer}>
       <SheetHeaderView header={header} onClose={onClose} />
       {scrollable ? (
         <View style={styles.desktopScrollContainer}>
@@ -717,7 +706,7 @@ export function AdaptiveModalSheet({
         <View style={[styles.desktopStaticContent, contentContainerStyle]}>{children}</View>
       )}
       {footer ? <View style={footerStyle}>{footer}</View> : null}
-    </>
+    </OverlayLayerProvider>
   );
 
   const desktopContent = (
@@ -727,7 +716,15 @@ export function AdaptiveModalSheet({
         style={ABSOLUTE_FILL_STYLE}
         onPress={onClose}
       />
-      <View style={desktopCardStyle}>{cardInner}</View>
+      <View
+        ref={setWebOverlayScope}
+        style={desktopCardStyle}
+        role="dialog"
+        aria-modal
+        tabIndex={-1}
+      >
+        {cardInner}
+      </View>
     </View>
   );
 

packages/app/src/components/add-project-flow.tsx

@@ -11,7 +11,15 @@ import {
   Search,
   Server,
 } from "lucide-react-native";
-import { useCallback, useEffect, useMemo, useRef, useState, type ComponentType } from "react";
+import {
+  createElement,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentType,
+} from "react";
 import {
   Modal,
   Pressable,
@@ -66,6 +74,11 @@ 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 {
   useHosts,
   useHostRuntimeClient,
@@ -769,14 +782,20 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
     [activeIndex, handleBack, rows, submitActive],
   );
 
-  useEffect(() => {
-    if (!isWeb || typeof window === "undefined") return;
-    const listener = (event: KeyboardEvent) => {
-      if (handleKey(event.key)) event.preventDefault();
-    };
-    window.addEventListener("keydown", listener, true);
-    return () => window.removeEventListener("keydown", listener, true);
-  }, [handleKey]);
+  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb);
+  const handleWebOverlayKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (!handleKey(event.key)) return false;
+      event.preventDefault();
+      return true;
+    },
+    [handleKey],
+  );
+  const setWebOverlayScope = useWebOverlayRegistration({
+    active: isWeb,
+    layer: modalLayer,
+    onKeyDown: handleWebOverlayKeyDown,
+  });
 
   const handleNativeKeyPress = useCallback(
     ({ nativeEvent: { key } }: { nativeEvent: { key: string } }) => {
@@ -816,11 +835,12 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
       ? joinDirectoryPath(page.parentPath, page.name.trim())
       : null;
 
-  return (
+  const modal = (
     <Modal visible transparent animationType="fade" onRequestClose={isWeb ? undefined : handleBack}>
       <View style={styles.overlay} testID="add-project-flow">
         <Pressable style={styles.backdrop} onPress={onClose} testID="add-project-flow-backdrop" />
         <View
+          ref={setWebOverlayScope}
           style={styles.panel}
           testID={`add-project-flow-page-${page.kind}`}
           accessibilityLabel={`Add project: ${page.kind}`}
@@ -913,6 +933,8 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
       </View>
     </Modal>
   );
+
+  return createElement(OverlayLayerProvider, { layer: isWeb ? modalLayer : 0 }, modal);
 }
 
 const styles = StyleSheet.create((theme) => ({

packages/app/src/components/dictation-controls.tsx

@@ -1,5 +1,6 @@
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { useMemo } from "react";
-import { View, Text, Pressable, ActivityIndicator } from "react-native";
+import { View, Text, Pressable } from "react-native";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { X, ArrowUp, RefreshCcw, Check, Mic, Pencil } from "lucide-react-native";
 import { useTranslation } from "react-i18next";
@@ -98,7 +99,7 @@ export function DictationControls({
         </Pressable>
         {actionsDisabled ? (
           <View style={styles.loadingContainer}>
-            <ActivityIndicator size="small" color={theme.colors.foreground} />
+            <LoadingSpinner size="small" color={theme.colors.foreground} />
           </View>
         ) : null}
         {!actionsDisabled && isFailed ? (
@@ -221,7 +222,7 @@ export function DictationOverlay({
       <View style={overlayStyles.actionButtonsContainer}>
         {actionsDisabled ? (
           <View style={overlayStyles.loadingContainer}>
-            <ActivityIndicator size="small" color={theme.colors.accentForeground} />
+            <LoadingSpinner size="small" color={theme.colors.accentForeground} />
           </View>
         ) : null}
         {!actionsDisabled && isFailed ? (

packages/app/src/components/download-toast.tsx

@@ -1,7 +1,8 @@
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { useCallback, useEffect, useMemo, useRef } from "react";
 import type { TFunction } from "i18next";
 import { useTranslation } from "react-i18next";
-import { ActivityIndicator, Pressable, Text, View } from "react-native";
+import { Pressable, Text, View } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { Check, X, XCircle } from "lucide-react-native";
@@ -69,7 +70,7 @@ export function DownloadToast() {
     <View style={containerStyle} pointerEvents="box-none">
       <View style={styles.toast}>
         {activeDownload.status === "downloading" ? (
-          <ActivityIndicator size="small" color={theme.colors.foreground} />
+          <LoadingSpinner size="small" color={theme.colors.foreground} />
         ) : null}
         {activeDownload.status === "complete" ? (
           <Check size={18} color={theme.colors.primary} />

packages/app/src/components/file-drop/use-drop-listeners.ts

@@ -5,9 +5,9 @@ import type { ImageAttachment } from "@/composer/types";
 import { getDesktopHost } from "@/desktop/host";
 import { persistAttachmentFromBlob, persistAttachmentFromFileUri } from "@/attachments/service";
 import {
-  getRasterImageMimeTypeFromPath,
   isRasterImageFile,
   isRasterImagePath,
+  resolveRasterImageMimeType,
 } from "@/attachments/file-types";
 import { isWeb } from "@/constants/platform";
 import type { DroppedItem, DroppedPathItem, FileDropSink } from "./types";
@@ -27,14 +27,21 @@ interface DesktopDragDropEvent {
 }
 
 async function filePathToImageAttachment(path: string): Promise<ImageAttachment> {
-  const mimeType = getRasterImageMimeTypeFromPath(path) ?? "image/jpeg";
+  const mimeType = resolveRasterImageMimeType({ path });
+  if (!mimeType) {
+    throw new Error(`Unsupported image type for '${path}'.`);
+  }
   return await persistAttachmentFromFileUri({ uri: path, mimeType });
 }
 
 async function fileToImageAttachment(file: File): Promise<ImageAttachment> {
+  const mimeType = resolveRasterImageMimeType({ mimeType: file.type, path: file.name });
+  if (!mimeType) {
+    throw new Error(`Unsupported image type for '${file.name}'.`);
+  }
   return await persistAttachmentFromBlob({
     blob: file,
-    mimeType: file.type || "image/jpeg",
+    mimeType,
     fileName: file.name,
   });
 }

packages/app/src/components/file-explorer-pane.tsx

@@ -2,7 +2,6 @@ import { useCallback, useEffect, useMemo, useRef, type ReactElement, type RefObj
 import { useQuery } from "@tanstack/react-query";
 import { useTranslation } from "react-i18next";
 import {
-  ActivityIndicator,
   FlatList,
   ListRenderItemInfo,
   Pressable,
@@ -12,7 +11,7 @@ import {
   type StyleProp,
   type ViewStyle,
 } from "react-native";
-import { StyleSheet, useUnistyles } from "react-native-unistyles";
+import { StyleSheet, useUnistyles, withUnistyles } from "react-native-unistyles";
 import { WORKSPACE_SECONDARY_HEADER_HEIGHT } from "@/constants/layout";
 import * as Clipboard from "expo-clipboard";
 import { ChevronDown, Eye, EyeOff, RotateCw } from "lucide-react-native";
@@ -24,16 +23,29 @@ import {
   WORKSPACE_FILE_ROW_VERTICAL_PADDING,
 } from "@/components/tree-primitives";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
-import type { AgentFileExplorerState, ExplorerEntry } from "@/stores/session-store";
+import type { Theme } from "@/styles/theme";
+import type {
+  AgentFileExplorerState,
+  ExplorerDirectory,
+  ExplorerEntry,
+} from "@/stores/session-store";
 import { useSessionStore } from "@/stores/session-store";
 import { FileActionsMenu } from "@/components/file-actions-menu";
 import { useFileDownload } from "@/hooks/use-file-download";
 import { useFileExplorerActions } from "@/hooks/use-file-explorer-actions";
 import { buildWorkspaceExplorerStateKey } from "@/hooks/use-file-explorer-actions";
-import { usePanelStore, type SortOption } from "@/stores/panel-store";
+import { usePanelStore, type ExpandedPathsUpdate, type SortOption } from "@/stores/panel-store";
 import { formatTimeAgo } from "@/utils/time";
 import { buildAbsoluteExplorerPath } from "@/utils/explorer-paths";
-import { filterVisibleExplorerEntries, isHiddenExplorerPath } from "@/file-explorer/visibility";
+import { isHiddenExplorerPath } from "@/file-explorer/visibility";
+import {
+  flattenExplorerTree,
+  reconcileRestoredExpandedPaths,
+  restoreExpandedDirectories,
+  setExpandedDirectoryPath,
+  showHiddenFilesAndRestoreExpandedDirectories,
+  type ExplorerTreeRow,
+} from "@/file-explorer/tree";
 import { useWorkspaceFileDragSource } from "@/attachments/use-workspace-file-drag-source";
 
 const SORT_OPTIONS: { value: SortOption }[] = [
@@ -42,6 +54,11 @@ const SORT_OPTIONS: { value: SortOption }[] = [
   { value: "size" },
 ];
 
+const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
+const foregroundMutedColorMapping = (theme: Theme) => ({
+  color: theme.colors.foregroundMuted,
+});
+
 function formatFileSize({ size }: { size: number }): string {
   if (size < 1024) {
     return `${size} B`;
@@ -78,7 +95,7 @@ function iconButtonStyle({ hovered, pressed }: PressableStateCallbackType & { ho
   return [styles.iconButton, (Boolean(hovered) || pressed) && styles.iconButtonHovered];
 }
 
-function treeRowKeyExtractor(row: TreeRow) {
+function treeRowKeyExtractor(row: ExplorerTreeRow) {
   return row.entry.path;
 }
 
@@ -163,7 +180,9 @@ function TreeRowItem({
             if (!isDirectory) {
               return <MaterialFileIcon fileName={entry.name} size={16} />;
             }
-            if (loading) return <ActivityIndicator size="small" />;
+            if (loading) {
+              return <ThemedLoadingSpinner size="small" uniProps={foregroundMutedColorMapping} />;
+            }
             return <TreeChevron expanded={isExpanded} />;
           })()}
         </View>
@@ -192,11 +211,6 @@ interface FileExplorerPaneProps {
   onAddToChat?: (path: string) => void;
 }
 
-interface TreeRow {
-  entry: ExplorerEntry;
-  depth: number;
-}
-
 export function FileExplorerPane({
   serverId,
   workspaceId,
@@ -256,7 +270,7 @@ export function FileExplorerPane({
     [isExplorerLoading, pendingRequest],
   );
 
-  const treeListRef = useRef<FlatList<TreeRow>>(null);
+  const treeListRef = useRef<FlatList<ExplorerTreeRow>>(null);
 
   const hasInitializedRef = useRef(false);
 
@@ -269,9 +283,19 @@ export function FileExplorerPane({
       hasWorkspaceScope,
       hasInitializedRef,
       workspaceStateKey,
+      persistedExpandedPaths: expandedPaths,
+      showHiddenFiles,
       requestDirectoryListing,
+      setExpandedPathsForWorkspace,
     });
-  }, [hasWorkspaceScope, requestDirectoryListing, workspaceStateKey]);
+  }, [
+    expandedPaths,
+    hasWorkspaceScope,
+    requestDirectoryListing,
+    setExpandedPathsForWorkspace,
+    showHiddenFiles,
+    workspaceStateKey,
+  ]);
 
   const handleToggleDirectory = useCallback(
     (entry: ExplorerEntry) =>
@@ -344,11 +368,42 @@ export function FileExplorerPane({
 
   const handleToggleHiddenFiles = useCallback(() => {
     const willShow = !usePanelStore.getState().explorerShowHiddenFiles;
-    toggleExplorerShowHiddenFiles();
-    if (willShow) {
-      requestPersistedExpandedPaths({ workspaceStateKey, requestDirectoryListing });
+    if (!willShow) {
+      toggleExplorerShowHiddenFiles();
+      return;
     }
-  }, [requestDirectoryListing, toggleExplorerShowHiddenFiles, workspaceStateKey]);
+    const rootDirectory = directories.get(".");
+    if (!rootDirectory || !workspaceStateKey) {
+      toggleExplorerShowHiddenFiles();
+      return;
+    }
+    void showHiddenFilesAndRestoreExpandedDirectories({
+      rootDirectory,
+      persistedExpandedPaths: expandedPaths,
+      showHiddenFiles: toggleExplorerShowHiddenFiles,
+      requestDirectoryListing: (path) =>
+        requestDirectoryListing(path, {
+          recordHistory: false,
+          setCurrentPath: false,
+        }),
+    }).then((restoredPaths) => {
+      setExpandedPathsForWorkspace(workspaceStateKey, (currentPaths) =>
+        reconcileRestoredExpandedPaths({
+          persistedExpandedPaths: expandedPaths,
+          currentExpandedPaths: new Set(currentPaths),
+          restoredExpandedPaths: restoredPaths,
+        }),
+      );
+      return null;
+    });
+  }, [
+    directories,
+    expandedPaths,
+    requestDirectoryListing,
+    setExpandedPathsForWorkspace,
+    toggleExplorerShowHiddenFiles,
+    workspaceStateKey,
+  ]);
 
   const refreshExplorer = useCallback(
     () =>
@@ -380,7 +435,7 @@ export function FileExplorerPane({
   const currentSortLabel = resolveCurrentSortLabel(sortOption, sortLabels);
 
   const treeRows = useMemo(
-    () => resolveTreeRows({ directories, expandedPaths, sortOption, showHiddenFiles }),
+    () => flattenExplorerTree({ directories, expandedPaths, sortOption, showHiddenFiles }),
     [directories, expandedPaths, showHiddenFiles, sortOption],
   );
 
@@ -393,7 +448,7 @@ export function FileExplorerPane({
   const errorRecoveryPath = useMemo(() => getErrorRecoveryPath(explorerState), [explorerState]);
 
   const renderTreeRow = useCallback(
-    (info: ListRenderItemInfo<TreeRow>) => (
+    (info: ListRenderItemInfo<ExplorerTreeRow>) => (
       <TreeRowDispatcher
         serverId={serverId}
         workspaceId={workspaceId}
@@ -473,11 +528,11 @@ interface FileExplorerPaneContentProps {
   error: string | null;
   showInitialLoading: boolean;
   showBackFromError: boolean;
-  treeRows: TreeRow[];
+  treeRows: ExplorerTreeRow[];
   currentSortLabel: string;
   isRefreshFetching: boolean;
-  treeListRef: RefObject<FlatList<TreeRow> | null>;
-  renderTreeRow: (info: ListRenderItemInfo<TreeRow>) => ReactElement;
+  treeListRef: RefObject<FlatList<ExplorerTreeRow> | null>;
+  renderTreeRow: (info: ListRenderItemInfo<ExplorerTreeRow>) => ReactElement;
   handleSortCycle: () => void;
   handleToggleHiddenFiles: () => void;
   handleRefresh: () => void;
@@ -549,7 +604,7 @@ function FileExplorerPaneContent(props: FileExplorerPaneContentProps) {
   if (showInitialLoading) {
     return (
       <View style={styles.centerState}>
-        <ActivityIndicator size="small" />
+        <ThemedLoadingSpinner size="small" uniProps={foregroundMutedColorMapping} />
         <Text style={styles.loadingText}>{t("workspace.fileExplorer.states.loading")}</Text>
       </View>
     );
@@ -630,71 +685,6 @@ function FileExplorerPaneContent(props: FileExplorerPaneContentProps) {
   );
 }
 
-function sortEntries(entries: ExplorerEntry[], sortOption: SortOption): ExplorerEntry[] {
-  const sorted = [...entries];
-  sorted.sort((a, b) => {
-    if (a.kind !== b.kind) {
-      return a.kind === "directory" ? -1 : 1;
-    }
-    switch (sortOption) {
-      case "name":
-        return a.name.localeCompare(b.name);
-      case "modified":
-        return new Date(b.modifiedAt).getTime() - new Date(a.modifiedAt).getTime();
-      case "size":
-        return b.size - a.size;
-      default:
-        return 0;
-    }
-  });
-  return sorted;
-}
-
-function buildTreeRows({
-  directories,
-  expandedPaths,
-  sortOption,
-  showHiddenFiles,
-  path,
-  depth,
-}: {
-  directories: Map<string, { path: string; entries: ExplorerEntry[] }>;
-  expandedPaths: Set<string>;
-  sortOption: SortOption;
-  showHiddenFiles: boolean;
-  path: string;
-  depth: number;
-}): TreeRow[] {
-  const directory = directories.get(path);
-  if (!directory) {
-    return [];
-  }
-
-  const rows: TreeRow[] = [];
-  const entries = sortEntries(
-    filterVisibleExplorerEntries(directory.entries, showHiddenFiles),
-    sortOption,
-  );
-
-  for (const entry of entries) {
-    rows.push({ entry, depth });
-    if (entry.kind === "directory" && expandedPaths.has(entry.path)) {
-      rows.push(
-        ...buildTreeRows({
-          directories,
-          expandedPaths,
-          sortOption,
-          showHiddenFiles,
-          path: entry.path,
-          depth: depth + 1,
-        }),
-      );
-    }
-  }
-
-  return rows;
-}
-
 function deriveExplorerFields(state: AgentFileExplorerState | undefined) {
   return {
     directories:
@@ -744,30 +734,6 @@ function resolveCurrentSortLabel(
   return labels[sortOption] ?? labels.name;
 }
 
-function resolveTreeRows({
-  directories,
-  expandedPaths,
-  sortOption,
-  showHiddenFiles,
-}: {
-  directories: Map<string, { path: string; entries: ExplorerEntry[] }>;
-  expandedPaths: Set<string>;
-  sortOption: SortOption;
-  showHiddenFiles: boolean;
-}): TreeRow[] {
-  if (!directories.get(".")) {
-    return [];
-  }
-  return buildTreeRows({
-    directories,
-    expandedPaths,
-    sortOption,
-    showHiddenFiles,
-    path: ".",
-    depth: 0,
-  });
-}
-
 function toggleDirectory({
   entry,
   workspaceStateKey,
@@ -779,26 +745,25 @@ function toggleDirectory({
   entry: ExplorerEntry;
   workspaceStateKey: string | null;
   expandedPaths: Set<string>;
-  directories: Map<string, { path: string; entries: ExplorerEntry[] }>;
+  directories: Map<string, ExplorerDirectory>;
   requestDirectoryListing: (
     path: string,
     opts?: { recordHistory?: boolean; setCurrentPath?: boolean },
-  ) => Promise<boolean>;
-  setExpandedPathsForWorkspace: (workspaceStateKey: string, paths: string[]) => void;
+  ) => Promise<ExplorerDirectory | null>;
+  setExpandedPathsForWorkspace: (workspaceStateKey: string, paths: ExpandedPathsUpdate) => void;
 }): void {
   if (!workspaceStateKey) {
     return;
   }
   const isExpanded = expandedPaths.has(entry.path);
-  if (isExpanded) {
-    setExpandedPathsForWorkspace(
-      workspaceStateKey,
-      Array.from(expandedPaths).filter((path) => path !== entry.path),
-    );
-    return;
-  }
-  setExpandedPathsForWorkspace(workspaceStateKey, [...Array.from(expandedPaths), entry.path]);
-  if (!directories.has(entry.path)) {
+  setExpandedPathsForWorkspace(workspaceStateKey, (currentPaths) =>
+    setExpandedDirectoryPath({
+      currentExpandedPaths: currentPaths,
+      directoryPath: entry.path,
+      expanded: !isExpanded,
+    }),
+  );
+  if (!isExpanded && !directories.has(entry.path)) {
     void requestDirectoryListing(entry.path, {
       recordHistory: false,
       setCurrentPath: false,
@@ -820,7 +785,7 @@ function TreeRowDispatcher({
 }: {
   serverId: string;
   workspaceId?: string | null;
-  info: ListRenderItemInfo<TreeRow>;
+  info: ListRenderItemInfo<ExplorerTreeRow>;
   expandedPaths: Set<string>;
   selectedEntryPath: string | null;
   isDirectoryLoading: (path: string) => boolean;
@@ -858,54 +823,59 @@ async function initializeExplorer({
   hasWorkspaceScope,
   hasInitializedRef,
   workspaceStateKey,
+  persistedExpandedPaths,
+  showHiddenFiles,
   requestDirectoryListing,
+  setExpandedPathsForWorkspace,
 }: {
   hasWorkspaceScope: boolean;
   hasInitializedRef: RefObject<boolean>;
   workspaceStateKey: string | null;
+  persistedExpandedPaths: ReadonlySet<string>;
+  showHiddenFiles: boolean;
   requestDirectoryListing: (
     path: string,
     opts?: { recordHistory?: boolean; setCurrentPath?: boolean },
-  ) => Promise<boolean>;
+  ) => Promise<ExplorerDirectory | null>;
+  setExpandedPathsForWorkspace: (workspaceStateKey: string, paths: ExpandedPathsUpdate) => void;
 }): Promise<void> {
   if (!hasWorkspaceScope || hasInitializedRef.current) {
     return;
   }
   hasInitializedRef.current = true;
-  const succeeded = await requestDirectoryListing(".", {
+  const rootDirectory = await requestDirectoryListing(".", {
     recordHistory: false,
     setCurrentPath: false,
   });
-  if (!succeeded) {
+  if (!rootDirectory) {
     hasInitializedRef.current = false;
     return;
   }
-  requestPersistedExpandedPaths({ workspaceStateKey, requestDirectoryListing });
-}
-
-function requestPersistedExpandedPaths({
-  workspaceStateKey,
-  requestDirectoryListing,
-}: {
-  workspaceStateKey: string | null;
-  requestDirectoryListing: (
-    path: string,
-    opts?: { recordHistory?: boolean; setCurrentPath?: boolean },
-  ) => Promise<boolean>;
-}): void {
-  const showHiddenFiles = usePanelStore.getState().explorerShowHiddenFiles;
-  const persistedPaths = usePanelStore.getState().expandedPathsByWorkspace[workspaceStateKey ?? ""];
-  if (!persistedPaths) {
+  if (!workspaceStateKey) {
     return;
   }
-  for (const path of persistedPaths) {
-    if (path !== "." && (showHiddenFiles || !isHiddenExplorerPath(path))) {
-      void requestDirectoryListing(path, {
+
+  const restoredPaths = await restoreExpandedDirectories({
+    rootDirectory,
+    persistedExpandedPaths,
+    showHiddenFiles,
+    requestDirectoryListing: (path) =>
+      requestDirectoryListing(path, {
         recordHistory: false,
         setCurrentPath: false,
-      });
-    }
-  }
+      }),
+  });
+  const hiddenPersistedPaths = showHiddenFiles
+    ? []
+    : Array.from(persistedExpandedPaths).filter(isHiddenExplorerPath);
+  const restoredPathsWithHidden = [...restoredPaths, ...hiddenPersistedPaths];
+  setExpandedPathsForWorkspace(workspaceStateKey, (currentPaths) =>
+    reconcileRestoredExpandedPaths({
+      persistedExpandedPaths,
+      currentExpandedPaths: new Set(currentPaths),
+      restoredExpandedPaths: restoredPathsWithHidden,
+    }),
+  );
 }
 
 async function refreshExplorerDirectories({
@@ -918,7 +888,7 @@ async function refreshExplorerDirectories({
   requestDirectoryListing: (
     path: string,
     opts?: { recordHistory?: boolean; setCurrentPath?: boolean },
-  ) => Promise<boolean>;
+  ) => Promise<ExplorerDirectory | null>;
 }): Promise<null> {
   if (!hasWorkspaceScope) {
     return null;

packages/app/src/components/markdown/html-ish.test.ts

@@ -296,6 +296,16 @@ describe("splitHtmlishMarkdown", () => {
     );
   });
 
+  it("normalizes HTML table cells and inline formatting into markdown", () => {
+    expect(
+      normalizeHtmlishMarkdown(
+        "<table><tr><td><strong>Score</strong>: 78</td></tr><tr><td><strong>No security concerns identified</strong></td></tr><tr><td><strong>Recommended focus areas for review</strong></td><td>Bearer authentication</td></tr></table>",
+      ),
+    ).toBe(
+      "\n- **Score**: 78\n- **No security concerns identified**\n- **Recommended focus areas for review**: Bearer authentication\n",
+    );
+  });
+
   it("leaves complex code tags inert instead of parsing HTML", () => {
     expect(normalizeHtmlishMarkdown('<code onclick="evil()"><script>x</script></code>')).toBe(
       '<code onclick="evil()"><script>x</script></code>',

packages/app/src/components/markdown/html-ish.ts

@@ -30,6 +30,15 @@ const BACKTICK_RUN_RE = /`+/g;
 const SAFE_IMAGE_SRC_RE = /^(https?:\/\/|data:image\/(?:png|gif|jpe?g);base64,)/i;
 const SAFE_LINK_HREF_RE = /^(https?:\/\/|#(?:$|[\w-]))/i;
 const VOID_HTML_TAGS = new Set(["br", "img"]);
+const MARKDOWN_TAG_WRAPPERS: Readonly<Record<string, readonly [string, string]>> = {
+  b: ["**", "**"],
+  del: ["~~", "~~"],
+  em: ["*", "*"],
+  i: ["*", "*"],
+  s: ["~~", "~~"],
+  strike: ["~~", "~~"],
+  strong: ["**", "**"],
+};
 
 interface ProtectedMarkdownRange {
   start: number;
@@ -313,36 +322,83 @@ function renderInlineTokens(tokens: HtmlToken[]): string {
     }
 
     const children = tokens.slice(index + 1, closeIndex);
-    if (token.name === "a") {
-      output += renderLinkToken(token, children);
-      index = closeIndex;
-      continue;
-    }
-    if (token.name === "sub") {
-      output += renderInlineTokens(children);
-      index = closeIndex;
-      continue;
-    }
-    if (token.name === "code" && children.every((child) => child.kind === "text")) {
-      output += `\`${renderInlineTokens(children)}\``;
-      index = closeIndex;
-      continue;
-    }
-    const rawTag = token.raw;
-    const tagName = token.name;
-    if (isHeadingTag(token)) {
-      output += renderInlineTokens(children);
-      index = closeIndex;
-      continue;
-    }
-
-    output += `${rawTag}${renderInlineTokens(children)}</${tagName}>`;
+    output += renderHtmlTag(token, children);
     index = closeIndex;
   }
 
   return output;
 }
 
+function renderHtmlTag(token: HtmlTagToken, children: HtmlToken[]): string {
+  if (token.name === "a") {
+    return renderLinkToken(token, children);
+  }
+  if (token.name === "sub" || isHeadingTagName(token.name)) {
+    return renderInlineTokens(children);
+  }
+  if (token.name === "code" && children.every((child) => child.kind === "text")) {
+    return `\`${renderInlineTokens(children)}\``;
+  }
+  const wrapper = MARKDOWN_TAG_WRAPPERS[token.name];
+  if (wrapper) {
+    return `${wrapper[0]}${renderInlineTokens(children)}${wrapper[1]}`;
+  }
+  if (token.name === "table") {
+    return renderTableTokens(children);
+  }
+  if (token.name === "p" || token.name === "div") {
+    return `\n\n${renderInlineTokens(children).trim()}\n\n`;
+  }
+  return `${token.raw}${renderInlineTokens(children)}</${token.name}>`;
+}
+
+function renderTableTokens(tokens: HtmlToken[]): string {
+  const rows: string[] = [];
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    if (!isOpenTag(tokens[index], "tr")) {
+      continue;
+    }
+    const closeIndex = findMatchingClose(tokens, index, "tr");
+    if (closeIndex === null) {
+      continue;
+    }
+    const cells = renderTableCells(tokens.slice(index + 1, closeIndex));
+    if (cells.length === 1) {
+      rows.push(`- ${cells[0]}`);
+    } else if (cells.length > 1) {
+      const label =
+        cells[0].startsWith("**") && cells[0].endsWith("**") ? cells[0] : `**${cells[0]}**`;
+      rows.push(`- ${label}: ${cells.slice(1).join(" ")}`);
+    }
+    index = closeIndex;
+  }
+
+  return rows.length > 0 ? `\n${rows.join("\n")}\n` : "";
+}
+
+function renderTableCells(tokens: HtmlToken[]): string[] {
+  const cells: string[] = [];
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!isOpenTag(token, "td") && !isOpenTag(token, "th")) {
+      continue;
+    }
+    const closeIndex = findMatchingClose(tokens, index, token.name);
+    if (closeIndex === null) {
+      continue;
+    }
+    const cell = renderInlineTokens(tokens.slice(index + 1, closeIndex)).trim();
+    if (cell) {
+      cells.push(cell);
+    }
+    index = closeIndex;
+  }
+
+  return cells;
+}
+
 function renderImageToken(token: HtmlTagToken): string {
   const image = imageTokenToInlineImage(token, undefined);
   if (!image) {

packages/app/src/components/message.tsx

@@ -1,9 +1,9 @@
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import {
   View,
   Text,
   Image,
   Pressable,
-  ActivityIndicator,
   type GestureResponderEvent,
   type LayoutChangeEvent,
   StyleProp,
@@ -29,7 +29,6 @@ import {
 } from "react";
 import type { ComponentType, ReactNode } from "react";
 import { MarkdownIt, type ASTNode, type RenderRules } from "react-native-markdown-display";
-import { useQuery } from "@tanstack/react-query";
 import MaskedView from "@react-native-masked-view/masked-view";
 import {
   Circle,
@@ -75,19 +74,7 @@ import { splitMarkdownBlocks } from "@/utils/split-markdown-blocks";
 import { formatDuration, formatMessageTimestamp } from "@/utils/time";
 import { writeMarkdownToRichClipboard } from "@/utils/rich-clipboard";
 import { getDefaultMarkdownClipboardEnvironment } from "@/utils/rich-clipboard-default-environment";
-import {
-  getAssistantImageLoadStateFromMetadata,
-  getAssistantImageMetadata,
-  setAssistantImageMetadata,
-  type AssistantImageLoadState,
-} from "@/utils/assistant-image-metadata";
 import { setAssistantMarkdownBlockHeight } from "@/utils/assistant-message-height-estimate";
-import { resolveAssistantImageSource } from "@/utils/assistant-image-source";
-import {
-  createPreviewAttachmentId,
-  getFileNameFromPath,
-  parseImageDataUrl,
-} from "@/attachments/utils";
 import { getAgentAttachmentPillContent } from "@/attachments/attachment-pill-content";
 import { PlanCard } from "./plan-card";
 import { useToolCallSheet } from "./tool-call-sheet";
@@ -102,8 +89,7 @@ import {
   useAssistantLinkPress,
 } from "@/assistant-file-links";
 import { getCompactionMarkerLabel } from "./message-compaction-label";
-import { useAttachmentPreviewUrl } from "@/attachments/use-attachment-preview-url";
-import { persistAttachmentFromBytes, persistAttachmentFromDataUrl } from "@/attachments/service";
+import { useAssistantImage } from "@/assistant-image/use-assistant-image";
 import {
   AttachmentFrame,
   AttachmentLabel,
@@ -132,6 +118,7 @@ interface UserMessageProps {
   client?: DaemonClient | null;
   isFirstInGroup?: boolean;
   isLastInGroup?: boolean;
+  isPending?: boolean;
   disableOuterSpacing?: boolean;
 }
 
@@ -172,6 +159,7 @@ const ThemedTodoCheckIcon = withUnistyles(Check);
 const ThemedFileSymlinkIcon = withUnistyles(FileSymlink);
 const ThemedTriangleAlertIcon = withUnistyles(TriangleAlertIcon);
 const ThemedChevronRightIcon = withUnistyles(ChevronRight);
+const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
 
 const foregroundColorMapping = (theme: Theme) => ({ color: theme.colors.foreground });
 const foregroundMutedColorMapping = (theme: Theme) => ({
@@ -429,6 +417,7 @@ export const UserMessage = memo(function UserMessage({
   client,
   isFirstInGroup = true,
   isLastInGroup = true,
+  isPending = false,
   disableOuterSpacing,
 }: UserMessageProps) {
   const isCompact = useIsCompactFormFactor();
@@ -440,7 +429,7 @@ export const UserMessage = memo(function UserMessage({
   const hasText = message.trim().length > 0;
   const hasImages = images.length > 0;
   const hasAttachments = attachments.length > 0;
-  const showTrailingRow = hasText && (isCompact || isNative || isHovered);
+  const showTrailingRow = !isPending && hasText && (isCompact || isNative || isHovered);
   const formattedTimestamp = useMemo(
     () => formatMessageTimestamp(new Date(timestamp)),
     [timestamp],
@@ -493,7 +482,7 @@ export const UserMessage = memo(function UserMessage({
   );
 
   return (
-    <View style={containerStyle} testID="user-message">
+    <View style={containerStyle} testID="user-message" aria-busy={isPending}>
       <View
         style={userMessageStylesheet.content}
         onPointerEnter={handlePointerEnter}
@@ -537,9 +526,15 @@ export const UserMessage = memo(function UserMessage({
           ) : null}
         </View>
         {hasText ? (
-          <View style={trailingRowStyle} pointerEvents={showTrailingRow ? "auto" : "none"}>
-            <Text style={userMessageStylesheet.timestampText}>{formattedTimestamp}</Text>
-            {capabilities ? (
+          <View
+            style={trailingRowStyle}
+            pointerEvents={showTrailingRow ? "auto" : "none"}
+            testID="user-message-trailing-row"
+          >
+            <Text style={userMessageStylesheet.timestampText} testID="user-message-timestamp">
+              {formattedTimestamp}
+            </Text>
+            {capabilities && messageId ? (
               <RewindMenu
                 capabilities={capabilities}
                 isPending={rewindMutation.isPending}
@@ -728,6 +723,7 @@ export const LiveElapsed = memo(function LiveElapsed({
 });
 
 interface AssistantMessageProps {
+  occurrenceKey: string;
   message: string;
   timestamp: number;
   workspaceRoot?: string;
@@ -755,11 +751,21 @@ export const assistantMessageStylesheet = StyleSheet.create((theme) => ({
   imageSurface: {
     width: "100%",
     overflow: "hidden",
+    position: "relative",
   },
   image: {
     width: "100%",
     height: "100%",
   },
+  imageLoadingOverlay: {
+    position: "absolute",
+    top: 0,
+    right: 0,
+    bottom: 0,
+    left: 0,
+    alignItems: "center",
+    justifyContent: "center",
+  },
   imageState: {
     alignItems: "center",
     justifyContent: "center",
@@ -776,123 +782,9 @@ export const assistantMessageStylesheet = StyleSheet.create((theme) => ({
 
 const ASSISTANT_IMAGE_MIN_HEIGHT = 160;
 
-const AssistantMarkdownResolvedImage = memo(function AssistantMarkdownResolvedImage({
-  uri,
-  alt,
-  containerStyle,
-  source,
-  workspaceRoot,
-  serverId,
-}: {
-  uri: string;
-  alt?: string;
-  containerStyle?: StyleProp<ViewStyle>;
-  source: string;
-  workspaceRoot?: string;
-  serverId?: string;
-}) {
-  const cachedMetadata = useMemo(
-    () => getAssistantImageMetadata({ source, workspaceRoot, serverId }),
-    [serverId, source, workspaceRoot],
-  );
-  const [loadState, setLoadState] = useState<AssistantImageLoadState>(() =>
-    getAssistantImageLoadStateFromMetadata(cachedMetadata),
-  );
-
-  useEffect(() => {
-    if (cachedMetadata) {
-      setLoadState(getAssistantImageLoadStateFromMetadata(cachedMetadata));
-      return () => {};
-    }
-
-    setLoadState({ status: "loading" });
-    let cancelled = false;
-
-    Image.getSize(
-      uri,
-      (width, height) => {
-        if (cancelled) {
-          return;
-        }
-        if (width > 0 && height > 0) {
-          const metadata = setAssistantImageMetadata(
-            { source, workspaceRoot, serverId },
-            { width, height },
-          );
-          setLoadState({
-            status: "ready",
-            aspectRatio: metadata?.aspectRatio ?? width / height,
-          });
-        }
-      },
-      () => {
-        if (cancelled) {
-          return;
-        }
-        setLoadState({ status: "error" });
-      },
-    );
-
-    return () => {
-      cancelled = true;
-    };
-  }, [cachedMetadata, serverId, source, uri, workspaceRoot]);
-
-  const handleImageError = useCallback(() => {
-    setLoadState({ status: "error" });
-  }, []);
-  const { t } = useTranslation();
-  const surfaceStyle = useMemo<StyleProp<ViewStyle>>(
-    () => [
-      assistantMessageStylesheet.imageSurface,
-      loadState.status === "ready"
-        ? { aspectRatio: loadState.aspectRatio }
-        : { height: ASSISTANT_IMAGE_MIN_HEIGHT },
-    ],
-    [loadState],
-  );
-  const frameStyle = useMemo<StyleProp<ViewStyle>>(
-    () => [assistantMessageStylesheet.imageFrame, containerStyle],
-    [containerStyle],
-  );
-  const stateSurfaceStyle = useMemo<StyleProp<ViewStyle>>(
-    () => [surfaceStyle, assistantMessageStylesheet.imageState],
-    [surfaceStyle],
-  );
-  const imageSource = useMemo(() => ({ uri }), [uri]);
-
-  if (loadState.status !== "ready") {
-    return (
-      <View style={frameStyle}>
-        <View style={stateSurfaceStyle}>
-          {loadState.status === "loading" ? <ActivityIndicator size="small" /> : null}
-          {loadState.status === "error" ? (
-            <Text style={assistantMessageStylesheet.imageErrorText}>
-              {t("message.attachments.imageUnavailable")}
-            </Text>
-          ) : null}
-        </View>
-      </View>
-    );
-  }
-
-  return (
-    <View style={frameStyle}>
-      <View style={surfaceStyle}>
-        <Image
-          source={imageSource}
-          style={assistantMessageStylesheet.image}
-          resizeMode="contain"
-          accessibilityLabel={alt}
-          onError={handleImageError}
-        />
-      </View>
-    </View>
-  );
-});
-
 function AssistantMarkdownImage({
   source,
+  occurrenceKey,
   alt,
   hasLeadingContent,
   client,
@@ -900,18 +792,13 @@ function AssistantMarkdownImage({
   serverId,
 }: {
   source: string;
+  occurrenceKey: string;
   alt?: string;
   hasLeadingContent: boolean;
   client?: DaemonClient | null;
   workspaceRoot?: string;
   serverId?: string;
 }) {
-  const { t } = useTranslation();
-  const resolution = useMemo(
-    () => resolveAssistantImageSource({ source, workspaceRoot }),
-    [source, workspaceRoot],
-  );
-  const dataImage = useMemo(() => parseImageDataUrl(source), [source]);
   const containerStyle = useMemo<StyleProp<ViewStyle>>(
     () => ({
       marginTop: hasLeadingContent ? 16 : 0,
@@ -919,64 +806,31 @@ function AssistantMarkdownImage({
     }),
     [hasLeadingContent],
   );
-
-  const query = useQuery({
-    queryKey: [
-      "assistantMarkdownImage",
-      serverId ?? "unknown-server",
-      resolution?.kind === "file_rpc" ? resolution.cwd : null,
-      resolution?.kind === "file_rpc" ? resolution.path : null,
-    ],
-    enabled: Boolean(client && resolution?.kind === "file_rpc"),
-    staleTime: 30_000,
-    queryFn: async () => {
-      if (!client || !resolution || resolution.kind !== "file_rpc") {
-        return null;
-      }
-
-      const file = await client.readFile(resolution.cwd, resolution.path);
-      if (file.kind !== "image") {
-        throw new Error(t("message.attachments.imagePreviewUnavailable"));
-      }
-
-      return await persistAttachmentFromBytes({
-        id: createPreviewAttachmentId({
-          mimeType: file.mime,
-          path: file.path || resolution.path,
-          size: file.size,
-          modifiedAt: file.modifiedAt,
-          contentLength: file.bytes.byteLength,
-        }),
-        bytes: file.bytes,
-        mimeType: file.mime,
-        fileName: getFileNameFromPath(file.path || resolution.path),
-      });
-    },
+  const image = useAssistantImage({
+    source,
+    occurrenceKey,
+    client,
+    workspaceRoot,
+    serverId,
   });
-  const dataImageQuery = useQuery({
-    queryKey: ["assistantMarkdownDataImage", dataImage?.cacheKey ?? null],
-    enabled: dataImage !== null,
-    staleTime: 30_000,
-    queryFn: async () => {
-      if (!dataImage) {
-        return null;
-      }
-
-      return await persistAttachmentFromDataUrl({
-        id: createPreviewAttachmentId({
-          mimeType: dataImage.mimeType,
-          contentLength: dataImage.base64.length,
-        }),
-        dataUrl: source,
-        mimeType: dataImage.mimeType,
-      });
-    },
-  });
-
-  const fileAssetUri = useAttachmentPreviewUrl(query.data);
-  const dataImageAssetUri = useAttachmentPreviewUrl(dataImageQuery.data);
-  const directUri = resolution?.kind === "direct" && !dataImage ? resolution.uri : null;
-  const resolvedUri = directUri ?? dataImageAssetUri ?? fileAssetUri ?? null;
+  const binding = image.status === "failed" ? null : image.binding;
+  const aspectRatio = image.status === "failed" ? null : image.aspectRatio;
+  const imageUri = binding?.uri ?? "";
+  const imageSource = useMemo(() => ({ uri: imageUri }), [imageUri]);
+  const frameStyle = useMemo<StyleProp<ViewStyle>>(
+    () => [assistantMessageStylesheet.imageFrame, containerStyle],
+    [containerStyle],
+  );
+  const imageSizeStyle = useMemo<ViewStyle>(() => {
+    if (aspectRatio) {
+      return { aspectRatio };
+    }
+    return { height: ASSISTANT_IMAGE_MIN_HEIGHT };
+  }, [aspectRatio]);
+  const surfaceStyle = useMemo<StyleProp<ViewStyle>>(
+    () => [assistantMessageStylesheet.imageSurface, imageSizeStyle],
+    [imageSizeStyle],
+  );
 
   const stateFrameStyle = useMemo<StyleProp<ViewStyle>>(
     () => [
@@ -988,50 +842,43 @@ function AssistantMarkdownImage({
     [containerStyle],
   );
 
-  if (resolvedUri) {
-    return (
-      <AssistantMarkdownResolvedImage
-        uri={resolvedUri}
-        alt={alt}
-        containerStyle={containerStyle}
-        source={source}
-        workspaceRoot={workspaceRoot}
-        serverId={serverId}
-      />
-    );
-  }
-
-  if (query.isLoading || dataImageQuery.isLoading) {
+  if (image.status === "failed") {
     return (
       <View style={stateFrameStyle}>
-        <ActivityIndicator size="small" />
+        <Text style={assistantMessageStylesheet.imageErrorText}>{image.message}</Text>
       </View>
     );
   }
 
-  const errorText = resolveAssistantImageErrorText(
-    query.error,
-    dataImageQuery.error,
-    t("message.attachments.imagePreviewLoadFailed"),
-  );
+  if (!binding) {
+    return (
+      <View style={stateFrameStyle}>
+        <ThemedLoadingSpinner size="small" uniProps={foregroundMutedColorMapping} />
+      </View>
+    );
+  }
 
   return (
-    <View style={stateFrameStyle}>
-      <Text style={assistantMessageStylesheet.imageErrorText}>{errorText}</Text>
+    <View style={frameStyle}>
+      <View style={surfaceStyle} accessibilityRole="image" accessibilityLabel={alt}>
+        <Image
+          ref={binding.onRef}
+          source={imageSource}
+          style={assistantMessageStylesheet.image}
+          resizeMode="contain"
+          onLoad={binding.onLoad}
+          onError={binding.onError}
+        />
+        {image.status === "loading" ? (
+          <View pointerEvents="none" style={assistantMessageStylesheet.imageLoadingOverlay}>
+            <ThemedLoadingSpinner size="small" uniProps={foregroundMutedColorMapping} />
+          </View>
+        ) : null}
+      </View>
     </View>
   );
 }
 
-function resolveAssistantImageErrorText(
-  fileError: unknown,
-  dataError: unknown,
-  fallbackText: string,
-): string {
-  if (fileError instanceof Error) return fileError.message;
-  if (dataError instanceof Error) return dataError.message;
-  return fallbackText;
-}
-
 function getInlineCodeAutoLinkUrl(
   markdownParser: ReturnType<typeof MarkdownIt>,
   content: string,
@@ -1572,6 +1419,7 @@ function MarkdownListView({ baseStyle, spacing, children }: MarkdownListViewProp
 }
 
 export const AssistantMessage = memo(function AssistantMessage({
+  occurrenceKey,
   message,
   timestamp: _timestamp,
   workspaceRoot,
@@ -1906,6 +1754,7 @@ export const AssistantMessage = memo(function AssistantMessage({
           <AssistantMarkdownImage
             key={node.key}
             source={String(node.attributes?.src ?? "")}
+            occurrenceKey={`${occurrenceKey}:${node.key}`}
             alt={typeof node.attributes?.alt === "string" ? node.attributes.alt : undefined}
             hasLeadingContent={hasLeadingContent}
             client={client}
@@ -1915,7 +1764,7 @@ export const AssistantMessage = memo(function AssistantMessage({
         );
       },
     };
-  }, [client, fileLinkActions, markdownParser, serverId, workspaceRoot]);
+  }, [client, fileLinkActions, markdownParser, occurrenceKey, serverId, workspaceRoot]);
 
   const blocks = useMemo(() => splitMarkdownBlocks(message), [message]);
   const keyedBlocks = useMemo(
@@ -2244,7 +2093,7 @@ export const CompactionMarker = memo(function CompactionMarker({
       <View style={compactionStylesheet.line} />
       <View style={compactionStylesheet.label}>
         {status === "loading" ? (
-          <ActivityIndicator size="small" color="#a1a1aa" />
+          <LoadingSpinner size="small" color="#a1a1aa" />
         ) : (
           <Scissors size={12} color="#a1a1aa" />
         )}

packages/app/src/components/model-browser.tsx

@@ -34,6 +34,7 @@ import {
   type ProviderSelectorProvider,
 } from "@/provider-selection/provider-selection";
 import { useProviderSettingsStore } from "@/stores/provider-settings-store";
+import { useCurrentOverlayLayer } from "@/lib/overlay-root";
 import { ICON_SIZE, type Theme } from "@/styles/theme";
 import {
   resolveInitialModelBrowserView,
@@ -53,6 +54,36 @@ const ThemedSearch = withUnistyles(Search);
 const ThemedSettings = withUnistyles(Settings);
 const ThemedStar = withUnistyles(Star);
 
+function ProviderSettingsAction({
+  accessibilityLabel,
+  provider,
+  serverId,
+}: {
+  accessibilityLabel: string;
+  provider: string;
+  serverId: string | null;
+}) {
+  const overlayParentLayer = useCurrentOverlayLayer();
+  const handlePress = useCallback(() => {
+    if (!serverId) return;
+    useProviderSettingsStore.getState().open({ serverId, provider, overlayParentLayer });
+  }, [overlayParentLayer, provider, serverId]);
+
+  return (
+    <Pressable
+      onPress={handlePress}
+      disabled={!serverId}
+      hitSlop={8}
+      style={iconButtonStyle}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
+      testID={`selector-header-settings-${provider}`}
+    >
+      <HeaderSettingsIcon disabled={!serverId} />
+    </Pressable>
+  );
+}
+
 const IndependentScrollGestureContext = createContext<ReturnType<typeof Gesture.Native> | null>(
   null,
 );
@@ -237,11 +268,6 @@ export function useModelBrowser({
     setSearchQuery(value);
   }, []);
 
-  const openProviderSettings = useCallback(() => {
-    if (!serverId || view.kind !== "provider") return;
-    useProviderSettingsStore.getState().open({ serverId, provider: view.providerId });
-  }, [serverId, view]);
-
   const singleProviderView = providers.length === 1;
   const header = useMemo<SheetHeader>(() => {
     if (view.kind === "all") {
@@ -254,19 +280,13 @@ export function useModelBrowser({
       ),
       back: singleProviderView ? undefined : { onPress: handleBackToAll },
       actions: (
-        <Pressable
-          onPress={openProviderSettings}
-          disabled={!serverId}
-          hitSlop={8}
-          style={iconButtonStyle}
-          accessibilityRole="button"
+        <ProviderSettingsAction
+          serverId={serverId}
+          provider={view.providerId}
           accessibilityLabel={t("modelSelector.openProviderSettings", {
             provider: view.providerLabel,
           })}
-          testID={`selector-header-settings-${view.providerId}`}
-        >
-          <HeaderSettingsIcon disabled={!serverId} />
-        </Pressable>
+        />
       ),
       search: {
         onChange: handleSearchQueryChange,
@@ -279,7 +299,6 @@ export function useModelBrowser({
   }, [
     handleBackToAll,
     handleSearchQueryChange,
-    openProviderSettings,
     searchResetKey,
     serverId,
     singleProviderView,

packages/app/src/components/provider-diagnostic-sheet.tsx

@@ -3,13 +3,7 @@ import { AlertTriangle, Copy, FileText, Plus, RotateCw, Trash2 } from "lucide-re
 import type { TFunction } from "i18next";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
-import {
-  ActivityIndicator,
-  Pressable,
-  type PressableStateCallbackType,
-  Text,
-  View,
-} from "react-native";
+import { Pressable, type PressableStateCallbackType, Text, View } from "react-native";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import {
   AdaptiveModalSheet,
@@ -365,7 +359,7 @@ function DiagnosticSubSheet({
     body = (
       <SurfaceCard key={visible ? "visible" : "hidden"}>
         <View style={sheetStyles.codeBlockLoading}>
-          <ActivityIndicator size="small" color={theme.colors.foregroundMuted} />
+          <LoadingSpinner size="small" color={theme.colors.foregroundMuted} />
           <Text style={sheetStyles.mutedText}>{t("settings.providers.diagnostic.running")}</Text>
         </View>
       </SurfaceCard>
@@ -504,7 +498,7 @@ function ProviderModalBody(props: ProviderModalBodyProps) {
   if (discoveredCount === 0 && additionalCount === 0 && providerSnapshotRefreshing) {
     return (
       <View style={sheetStyles.emptyState}>
-        <ActivityIndicator size="small" color={theme.colors.foregroundMuted} />
+        <LoadingSpinner size="small" color={theme.colors.foregroundMuted} />
         <Text style={sheetStyles.mutedText}>{t("settings.providers.models.loading")}</Text>
       </View>
     );

packages/app/src/components/provider-settings-host.tsx

@@ -1,11 +1,13 @@
 import { useCallback } from "react";
 import { ProviderDiagnosticSheet } from "@/components/provider-diagnostic-sheet";
+import { OverlayLayerProvider } from "@/lib/overlay-root";
 import { useProviderSettingsStore } from "@/stores/provider-settings-store";
 
 export function ProviderSettingsHost() {
   const serverId = useProviderSettingsStore((state) => state.serverId);
   const provider = useProviderSettingsStore((state) => state.provider);
   const visible = useProviderSettingsStore((state) => state.visible);
+  const overlayParentLayer = useProviderSettingsStore((state) => state.overlayParentLayer);
   const close = useProviderSettingsStore((state) => state.close);
 
   const handleClose = useCallback(() => {
@@ -17,12 +19,14 @@ export function ProviderSettingsHost() {
   }
 
   return (
-    <ProviderDiagnosticSheet
-      key={`${serverId}:${provider}`}
-      provider={provider}
-      serverId={serverId}
-      visible={visible}
-      onClose={handleClose}
-    />
+    <OverlayLayerProvider layer={overlayParentLayer}>
+      <ProviderDiagnosticSheet
+        key={`${serverId}:${provider}`}
+        provider={provider}
+        serverId={serverId}
+        visible={visible}
+        onClose={handleClose}
+      />
+    </OverlayLayerProvider>
   );
 }

packages/app/src/components/question-form-card.tsx

@@ -1,12 +1,6 @@
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { useState, useCallback, useMemo } from "react";
-import {
-  View,
-  Text,
-  TextInput,
-  Pressable,
-  ActivityIndicator,
-  type PressableStateCallbackType,
-} from "react-native";
+import { View, Text, TextInput, Pressable, type PressableStateCallbackType } from "react-native";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { Check, X } from "lucide-react-native";
@@ -581,7 +575,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
           testID="question-form-dismiss"
         >
           {respondingAction === "dismiss" ? (
-            <ActivityIndicator size="small" color={theme.colors.foregroundMuted} />
+            <LoadingSpinner size="small" color={theme.colors.foregroundMuted} />
           ) : (
             <View style={styles.actionContent}>
               <X size={14} color={theme.colors.foregroundMuted} />
@@ -599,7 +593,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
           testID="question-form-primary-action"
         >
           {respondingAction === "submit" ? (
-            <ActivityIndicator size="small" color={theme.colors.accentForeground} />
+            <LoadingSpinner size="small" color={theme.colors.accentForeground} />
           ) : (
             <View style={styles.actionContent}>
               <Check size={14} color={submitActionTextColor} />

packages/app/src/components/realtime-voice-overlay.tsx

@@ -1,6 +1,7 @@
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { useMemo } from "react";
 import { useTranslation } from "react-i18next";
-import { ActivityIndicator, Pressable, View } from "react-native";
+import { Pressable, View } from "react-native";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { Mic, MicOff, Square } from "lucide-react-native";
 import { FOOTER_HEIGHT } from "@/constants/layout";
@@ -75,7 +76,7 @@ export function RealtimeVoiceOverlay({
           style={stopButtonStyle}
         >
           {isSwitching ? (
-            <ActivityIndicator size="small" color={theme.colors.palette.white} />
+            <LoadingSpinner size="small" color={theme.colors.palette.white} />
           ) : (
             <Square
               size={theme.iconSize.lg}

packages/app/src/components/rewind/use-rewind-agent-mutation.ts

@@ -7,7 +7,6 @@ import type { RewindMode } from "./use-rewind-capabilities";
 import { useRewindComposerRestore } from "./composer-restore";
 import { useSessionStore } from "@/stores/session-store";
 import { shouldRestoreComposerForRewindMode } from "./rewind-mode";
-import { clearOptimisticUserMessages } from "@/types/stream";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
 
 interface UseRewindAgentMutationInput {
@@ -36,13 +35,6 @@ export function useRewindAgentMutation(input: UseRewindAgentMutationInput): {
       }
       await input.client.rewindAgent(input.agentId, input.messageId, mode);
       if (mode !== "files") {
-        if (input.serverId) {
-          const session = useSessionStore.getState().sessions[input.serverId];
-          useSessionStore.getState().setAgentStreamState(input.serverId, input.agentId, {
-            tail: clearOptimisticUserMessages(session?.agentStreamTail.get(input.agentId) ?? []),
-            head: clearOptimisticUserMessages(session?.agentStreamHead.get(input.agentId) ?? []),
-          });
-        }
         const cursor = input.serverId
           ? useSessionStore
               .getState()

packages/app/src/components/sidebar-workspace-list.tsx

@@ -1,8 +1,8 @@
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import {
   View,
   Text,
   Pressable,
-  ActivityIndicator,
   ScrollView,
   type GestureResponderEvent,
   type PressableStateCallbackType,
@@ -131,6 +131,7 @@ import {
   getIsElectron,
 } from "@/constants/platform";
 import { getDesktopHost } from "@/desktop/host";
+import { OpenInFileManagerMenuItem } from "@/workspace/open-in-file-manager/menu-item";
 
 const workspaceKeyExtractor = (workspace: SidebarWorkspacePlacement) => workspace.workspaceKey;
 
@@ -143,7 +144,7 @@ const DEFAULT_STATUS_DOT_OFFSET = 0;
 const EMPHASIZED_STATUS_DOT_OFFSET = -1;
 const ThemedExternalLink = withUnistyles(ExternalLink);
 const ThemedGitPullRequest = withUnistyles(GitPullRequest);
-const ThemedActivityIndicator = withUnistyles(ActivityIndicator);
+const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
 const ThemedCircleAlert = withUnistyles(CircleAlert);
 const ThemedSyncedLoader = withUnistyles(SyncedLoader);
 const ThemedPlus = withUnistyles(Plus);
@@ -609,6 +610,10 @@ function ProjectKebabMenu({
             {t("sidebar.project.actions.openNewWindow")}
           </DropdownMenuItem>
         ) : null}
+        <OpenInFileManagerMenuItem
+          path={projectPath}
+          testID={`sidebar-project-menu-open-folder-${projectKey}`}
+        />
         <DropdownMenuItem
           testID={`sidebar-project-menu-remove-${projectKey}`}
           leading={trash2LeadingIcon}
@@ -660,6 +665,7 @@ function WorkspaceRowRightGroup({
   isPinned?: boolean;
   onTogglePin?: () => void;
 }) {
+  const workspacePath = workspace.workspaceDirectory ?? workspace.projectRootPath;
   const { t } = useTranslation();
   const showShortcut = showShortcutBadge && shortcutNumber !== null;
   const showKebab = Boolean(onArchive && (isHovered || isTouchPlatform));
@@ -698,6 +704,7 @@ function WorkspaceRowRightGroup({
                 archiveShortcutKeys={archiveShortcutKeys}
                 isPinned={isPinned}
                 onTogglePin={onTogglePin}
+                openInFileManagerPath={workspacePath}
               />
             ) : null}
           </SidebarWorkspaceTrailingActionOverlay>
@@ -746,7 +753,7 @@ function ProjectLeadingVisualStatus({
   if (isArchiving) {
     return (
       <View style={styles.projectLeadingVisualSlot}>
-        <ThemedActivityIndicator size={8} uniProps={foregroundMutedColorMapping} />
+        <ThemedLoadingSpinner size={8} uniProps={foregroundMutedColorMapping} />
       </View>
     );
   }
@@ -855,7 +862,7 @@ function NewWorktreeButton({
           >
             {({ hovered, pressed }) =>
               loading ? (
-                <ThemedActivityIndicator size={14} uniProps={foregroundMutedColorMapping} />
+                <ThemedLoadingSpinner size={14} uniProps={foregroundMutedColorMapping} />
               ) : (
                 <ThemedPlus
                   size={15}
@@ -1368,17 +1375,6 @@ function WorkspaceRowWithMenu({
     },
   });
 
-  useKeyboardActionHandler({
-    handlerId: `workspace-pin-${workspace.workspaceKey}`,
-    actions: ["workspace.pin"],
-    enabled: selected && canPin,
-    priority: 0,
-    handle: () => {
-      onTogglePin?.();
-      return true;
-    },
-  });
-
   return (
     <>
       <WorkspaceRowInner

packages/app/src/components/sidebar/sidebar-status-list.tsx

@@ -549,17 +549,6 @@ function StatusWorkspaceRowWithMenu({
     },
   });
 
-  useKeyboardActionHandler({
-    handlerId: `workspace-pin-${workspace.workspaceKey}`,
-    actions: ["workspace.pin"],
-    enabled: selected && canPin,
-    priority: 0,
-    handle: () => {
-      onTogglePin?.();
-      return true;
-    },
-  });
-
   return (
     <>
       <StatusWorkspaceRowInner

packages/app/src/components/sidebar/sidebar-workspace-menu.tsx

@@ -13,6 +13,7 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { Shortcut } from "@/components/ui/shortcut";
+import { OpenInFileManagerMenuItem } from "@/workspace/open-in-file-manager/menu-item";
 
 const foregroundColorMapping = (theme: Theme) => ({ color: theme.colors.foreground });
 const foregroundMutedColorMapping = (theme: Theme) => ({
@@ -58,6 +59,7 @@ interface SidebarWorkspaceMenuProps {
   archiveShortcutKeys?: ShortcutKey[][] | null;
   isPinned?: boolean;
   onTogglePin?: () => void;
+  openInFileManagerPath?: string | null;
 }
 
 export function SidebarWorkspaceMenu({
@@ -73,6 +75,7 @@ export function SidebarWorkspaceMenu({
   archiveShortcutKeys,
   isPinned,
   onTogglePin,
+  openInFileManagerPath,
 }: SidebarWorkspaceMenuProps) {
   const { t } = useTranslation();
   const archiveTrailing = useMemo(
@@ -137,6 +140,10 @@ export function SidebarWorkspaceMenu({
             {isPinned ? t("sidebar.workspace.actions.unpin") : t("sidebar.workspace.actions.pin")}
           </DropdownMenuItem>
         ) : null}
+        <OpenInFileManagerMenuItem
+          path={openInFileManagerPath}
+          testID={`sidebar-workspace-menu-open-folder-${workspaceKey}`}
+        />
         <DropdownMenuItem
           testID={`sidebar-workspace-menu-archive-${workspaceKey}`}
           leading={archiveLeadingIcon}

packages/app/src/components/sidebar/sidebar-workspace-row-content.tsx

@@ -1,13 +1,7 @@
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { memo, useCallback, useMemo, useState, type ReactNode } from "react";
 import { useTranslation } from "react-i18next";
-import {
-  ActivityIndicator,
-  Pressable,
-  Text,
-  View,
-  type GestureResponderEvent,
-  type ViewStyle,
-} from "react-native";
+import { Pressable, Text, View, type GestureResponderEvent, type ViewStyle } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import {
   CircleAlert,
@@ -54,7 +48,7 @@ const purpleColorMapping = (theme: Theme) => ({ color: theme.colors.palette.purp
 
 const ThemedExternalLink = withUnistyles(ExternalLink);
 const ThemedGitPullRequest = withUnistyles(GitPullRequest);
-const ThemedActivityIndicator = withUnistyles(ActivityIndicator);
+const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
 const ThemedCircleAlert = withUnistyles(CircleAlert);
 const ThemedSyncedLoader = withUnistyles(SyncedLoader);
 const ThemedMonitor = withUnistyles(Monitor);
@@ -207,7 +201,7 @@ function WorkspaceStatusIndicator({
   if (loading) {
     return (
       <View style={styles.workspaceStatusDot} testID="workspace-status-indicator-loading">
-        <ThemedActivityIndicator size={8} uniProps={foregroundMutedColorMapping} />
+        <ThemedLoadingSpinner size={8} uniProps={foregroundMutedColorMapping} />
       </View>
     );
   }

packages/app/src/components/split-container-pane-focus.ts

@@ -4,7 +4,6 @@ const INTERACTIVE_TARGET_SELECTOR = [
   "select",
   "[role='button']",
   "[role='link']",
-  "[contenteditable='true']",
   "[data-paseo-pane-focus-exempt='true']",
 ].join(", ");
 

packages/app/src/components/split-container.tsx

@@ -95,6 +95,7 @@ interface SplitContainerProps {
   onCloseTab: (tabId: string) => Promise<void> | void;
   onCopyResumeCommand: (agentId: string) => Promise<void> | void;
   onCopyAgentId: (agentId: string) => Promise<void> | void;
+  onCopyTerminalId: (terminalId: string) => Promise<void> | void;
   onCopyFilePath: (path: string) => Promise<void> | void;
   onReloadAgent: (agentId: string) => Promise<void> | void;
   onRenameTab: (tab: WorkspaceTabDescriptor) => void;
@@ -373,6 +374,7 @@ export function SplitContainer({
   onCloseTab,
   onCopyResumeCommand,
   onCopyAgentId,
+  onCopyTerminalId,
   onCopyFilePath,
   onReloadAgent,
   onRenameTab,
@@ -592,6 +594,7 @@ export function SplitContainer({
           onCloseTab={onCloseTab}
           onCopyResumeCommand={onCopyResumeCommand}
           onCopyAgentId={onCopyAgentId}
+          onCopyTerminalId={onCopyTerminalId}
           onCopyFilePath={onCopyFilePath}
           onReloadAgent={onReloadAgent}
           onRenameTab={onRenameTab}
@@ -738,6 +741,7 @@ function SplitNodeView({
   onCloseTab,
   onCopyResumeCommand,
   onCopyAgentId,
+  onCopyTerminalId,
   onCopyFilePath,
   onReloadAgent,
   onRenameTab,
@@ -795,6 +799,7 @@ function SplitNodeView({
           onCloseTab={onCloseTab}
           onCopyResumeCommand={onCopyResumeCommand}
           onCopyAgentId={onCopyAgentId}
+          onCopyTerminalId={onCopyTerminalId}
           onCopyFilePath={onCopyFilePath}
           onReloadAgent={onReloadAgent}
           onRenameTab={onRenameTab}
@@ -844,6 +849,7 @@ function SplitNodeView({
               onCloseTab={onCloseTab}
               onCopyResumeCommand={onCopyResumeCommand}
               onCopyAgentId={onCopyAgentId}
+              onCopyTerminalId={onCopyTerminalId}
               onCopyFilePath={onCopyFilePath}
               onReloadAgent={onReloadAgent}
               onRenameTab={onRenameTab}
@@ -899,6 +905,7 @@ function SplitPaneView({
   onCloseTab,
   onCopyResumeCommand,
   onCopyAgentId,
+  onCopyTerminalId,
   onCopyFilePath,
   onReloadAgent,
   onRenameTab,
@@ -1044,6 +1051,7 @@ function SplitPaneView({
             onCloseTab={onCloseTab}
             onCopyResumeCommand={onCopyResumeCommand}
             onCopyAgentId={onCopyAgentId}
+            onCopyTerminalId={onCopyTerminalId}
             onCopyFilePath={onCopyFilePath}
             onReloadAgent={onReloadAgent}
             onRenameTab={onRenameTab}

packages/app/src/components/terminal-pane.tsx

@@ -1,11 +1,6 @@
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import {
-  ActivityIndicator,
-  Pressable,
-  Text,
-  View,
-  type PressableStateCallbackType,
-} from "react-native";
+import { Pressable, Text, View, type PressableStateCallbackType } from "react-native";
 import Animated, { runOnJS, useAnimatedReaction } from "react-native-reanimated";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { encodeTerminalKeyInput } from "@getpaseo/protocol/terminal-key-input";
@@ -836,7 +831,7 @@ export function TerminalPane({
 
         {showLoadingOverlay ? (
           <View style={styles.attachOverlay} pointerEvents="none" testID="terminal-attach-loading">
-            <ActivityIndicator size="small" color={theme.colors.foregroundMuted} />
+            <LoadingSpinner size="small" color={theme.colors.foregroundMuted} />
           </View>
         ) : null}
       </View>