fix(server): preserve worktree include cleanup

Carry local files and shared state into new worktrees (#2419 )
* feat(server): support symlink worktree includes * refactor(server): simplify worktree include handling * fix(server): constrain worktree include traversal * fix(server): clean up failed worktree branches * fix(server): skip missing worktree include entries * fix(server): make worktree includes best effort * fix(server): skip failed worktree includes * fix(server): harden worktree include planning * fix(server): preserve reused worktree result shape Materialization reports describe one creation attempt, not durable worktree identity. Carry them beside the worktree so newly created and reused results keep the same stable shape. * fix(server): harden worktree include boundaries Replace directory snapshots exactly, keep canonical Git metadata protected, report recovery skips, and only roll back branches owned before worktree creation. * fix(server): follow safe include aliases Traverse canonical in-checkout directory links during glob planning and treat coded revalidation failures as per-entry skips. * fix(server): make include preflight race safe Create fetched checkout refs atomically, retain overlapping copy entries for independent fallback, and protect the full managed-worktree base. * fix(server): preserve staged recovery state Validate completed directory snapshots, retain backups after failed restoration, and derive atomic ref guards from the repository object ID width. * fix(server): preserve partial include progress Keep safe glob matches, enforce recursive-directory types, validate staged roots, and retain OID guards through rollback. --------- Co-authored-by: Mohamed Boudra <boudra.moha@gmail.com>
2026-10-14 21:32:40 +00:00 · 2026-09-09 23:48:56 +02:00 · 2026-09-09 23:48:56 +02:00 · 2026-09-09 23:37:54 +02:00 · 2026-09-09 22:45:30 +02:00 · 2026-09-09 20:32:21 +02:00
982 changed files with 65096 additions and 12196 deletions
@@ -40,6 +40,7 @@ This is the section I read most carefully. I need to see that *you* tested this,

 ### Checklist

+- [ ] Plugin changes follow the [SDK import boundaries](../docs/plugins.md#sdk-import-boundaries) (if applicable)
 - [ ] One focused change
 - [ ] `npm run typecheck` passes
 - [ ] `npm run lint` passes
@@ -50,11 +50,26 @@ app:
  - "packages/expo-two-way-audio/**"

 sdk:
+  - "packages/plugin/**"
+  - "plugin-examples/**"
+  - "public-docs/plugins/v0.8/**"
  - "packages/client/**"
  - "packages/highlight/**"
  - "packages/protocol/**"

 browser:
+  - "packages/server/src/server/agent/provider-snapshot-manager.ts"
+  - "packages/server/src/server/session/provider/provider-catalog-session.ts"
+  - "packages/client/src/compat/normalize-provider-models.ts"
+  - "packages/protocol/src/client-capabilities.ts"
+  - "packages/server/src/server/agent/provider-registry.ts"
+  - "packages/server/src/server/agent/agent-sdk-types.ts"
+  - "packages/server/src/server/agent/providers/codex-app-server-agent.ts"
+  - "packages/server/src/server/agent/providers/claude/agent.ts"
+  - "packages/server/src/server/agent/plugin-provider.ts"
+  - "packages/server/src/server/plugins/{index,plugin-process,plugin-process-protocol,runtime}.ts"
+  - "packages/server/src/executable-resolution/**"
+  - "packages/plugin/src/server/provider.ts"
  - "packages/app/src/!(desktop)/**"
  - "packages/app/e2e/browser/**"
  - "packages/app/e2e/support/**"
@@ -20,7 +20,50 @@ env:
  SOURCE_TAG: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref_name }}

 jobs:
+  ensure-release:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: scripts
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
+
+      - name: Resolve release tag
+        shell: bash
+        run: node scripts/emit-release-env.mjs --source-tag "$SOURCE_TAG" >> "$GITHUB_ENV"
+
+      - name: Ensure GitHub release exists
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if node scripts/github-release.mjs --repo "${{ github.repository }}" --tag "$RELEASE_TAG" >/dev/null 2>&1; then
+            exit 0
+          fi
+
+          release_args=(
+            release create "$RELEASE_TAG"
+            --repo "${{ github.repository }}"
+            --title "Paseo $RELEASE_TAG"
+            --notes ""
+            --draft
+          )
+
+          if [[ "$IS_PRERELEASE" == "true" ]]; then
+            release_args+=(--prerelease)
+          fi
+
+          if ! gh "${release_args[@]}"; then
+            echo "Release creation raced with another workflow; continuing."
+            node scripts/github-release.mjs --repo "${{ github.repository }}" --tag "$RELEASE_TAG" >/dev/null
+          fi
+
  publish-android-apk:
+    needs: [ensure-release]
    permissions:
      contents: write
      packages: read
@@ -36,32 +79,6 @@ jobs:
        shell: bash
        run: node scripts/emit-release-env.mjs --source-tag "$SOURCE_TAG" >> "$GITHUB_ENV"

-      - name: Ensure GitHub release exists
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          if gh release view "$RELEASE_TAG" --repo "${{ github.repository }}" >/dev/null 2>&1; then
-            exit 0
-          fi
-
-          release_args=(
-            release create "$RELEASE_TAG"
-            --repo "${{ github.repository }}"
-            --title "Paseo $RELEASE_TAG"
-            --notes ""
-          )
-
-          if [[ "$IS_PRERELEASE" == "true" ]]; then
-            release_args+=(--prerelease)
-          fi
-
-          if ! gh "${release_args[@]}"; then
-            echo "Release creation raced with another workflow; continuing."
-          fi
-
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
@@ -129,4 +146,5 @@ jobs:
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
-          gh release upload "$RELEASE_TAG" "${{ steps.artifact.outputs.asset_path }}" --clobber --repo "${{ github.repository }}"
+          release_lookup="$(node scripts/github-release.mjs --repo "${{ github.repository }}" --tag "$RELEASE_TAG")"
+          gh release upload "$release_lookup" "${{ steps.artifact.outputs.asset_path }}" --clobber --repo "${{ github.repository }}"
@@ -59,8 +59,6 @@ jobs:
    needs: changes
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.format != 'false') }}
    runs-on: ubuntu-latest
-    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
    steps:
      - uses: actions/checkout@v4

@@ -80,8 +78,6 @@ jobs:
    needs: changes
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.quality != 'false') }}
    runs-on: ubuntu-latest
-    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
    steps:
      - uses: actions/checkout@v4

@@ -107,8 +103,6 @@ jobs:
    needs: changes
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.quality != 'false') }}
    runs-on: ubuntu-latest
-    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
    steps:
      - uses: actions/checkout@v4

@@ -137,8 +131,6 @@ jobs:
    needs: changes
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.server != 'false' || needs.changes.outputs.hub != 'false') }}
    runs-on: ubuntu-latest
-    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
    steps: &server_test_steps
      - uses: actions/checkout@v4
        with:
@@ -180,8 +172,6 @@ jobs:
    needs: changes
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.server != 'false' || needs.changes.outputs.hub != 'false') }}
    runs-on: windows-latest
-    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
    steps: *server_test_steps

  desktop-tests-ubuntu:
@@ -268,8 +258,6 @@ jobs:
    needs: changes
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.app != 'false') }}
    runs-on: ubuntu-latest
-    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
    steps:
      - uses: actions/checkout@v4

@@ -296,8 +284,6 @@ jobs:
    needs: changes
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.sdk != 'false') }}
    runs-on: ubuntu-latest
-    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
    steps:
      - uses: actions/checkout@v4

@@ -312,6 +298,15 @@ jobs:
      - name: Build client dependencies
        run: npm run build:client

+      - name: Build plugin SDK
+        run: npm run build:plugin
+
+      - name: Run plugin SDK tests
+        run: npm run test --workspace=@getpaseo/plugin
+
+      - name: Typecheck plugin examples
+        run: npm run typecheck --workspace=@getpaseo/plugin
+
      - name: Run protocol tests
        run: npm run test --workspace=@getpaseo/protocol

@@ -330,7 +325,6 @@ jobs:
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
    runs-on: ubuntu-latest
    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
      PLAYWRIGHT_SHARD: "1/4"
      PLAYWRIGHT_ARTIFACT: "1"
    steps: &playwright_test_steps
@@ -378,7 +372,6 @@ jobs:
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
    runs-on: ubuntu-latest
    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
      PLAYWRIGHT_SHARD: "2/4"
      PLAYWRIGHT_ARTIFACT: "2"
    steps: *playwright_test_steps
@@ -389,7 +382,6 @@ jobs:
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
    runs-on: ubuntu-latest
    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
      PLAYWRIGHT_SHARD: "3/4"
      PLAYWRIGHT_ARTIFACT: "3"
    steps: *playwright_test_steps
@@ -400,7 +392,6 @@ jobs:
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.browser != 'false') }}
    runs-on: ubuntu-latest
    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
      PLAYWRIGHT_SHARD: "4/4"
      PLAYWRIGHT_ARTIFACT: "4"
    steps: *playwright_test_steps
@@ -410,8 +401,6 @@ jobs:
    needs: changes
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.relay != 'false') }}
    runs-on: ubuntu-latest
-    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
    steps:
      - uses: actions/checkout@v4

@@ -435,7 +424,6 @@ jobs:
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.cli != 'false') }}
    runs-on: ubuntu-latest
    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
      PASEO_LOCAL_SPEECH_AUTO_DOWNLOAD: "0"
      PASEO_DICTATION_ENABLED: "0"
      PASEO_VOICE_MODE_ENABLED: "0"
@@ -467,7 +455,6 @@ jobs:
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.cli != 'false') }}
    runs-on: ubuntu-latest
    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
      PASEO_LOCAL_SPEECH_AUTO_DOWNLOAD: "0"
      PASEO_DICTATION_ENABLED: "0"
      PASEO_VOICE_MODE_ENABLED: "0"
@@ -481,7 +468,6 @@ jobs:
    if: ${{ !cancelled() && (needs.changes.outputs.full != 'false' || needs.changes.outputs.cli != 'false') }}
    runs-on: ubuntu-latest
    env:
-      ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
      PASEO_LOCAL_SPEECH_AUTO_DOWNLOAD: "0"
      PASEO_DICTATION_ENABLED: "0"
      PASEO_VOICE_MODE_ENABLED: "0"
@@ -75,7 +75,7 @@ jobs:
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
-          if gh release view "$RELEASE_TAG" --repo "${{ github.repository }}" > /dev/null 2>&1; then
+          if node scripts/github-release.mjs --repo "${{ github.repository }}" --tag "$RELEASE_TAG" > /dev/null 2>&1; then
            echo "Release $RELEASE_TAG already exists, skipping creation"
          else
            prerelease_flag=""
@@ -86,8 +86,10 @@ jobs:
              --repo "${{ github.repository }}" \
              --title "Paseo $RELEASE_TAG" \
              --notes "" \
+              --draft \
              $prerelease_flag || {
                echo "Release creation raced with another workflow; continuing."
+                node scripts/github-release.mjs --repo "${{ github.repository }}" --tag "$RELEASE_TAG" > /dev/null
              }
          fi

@@ -191,7 +193,8 @@ jobs:
            echo "::error::No release artifacts found in $release_dir"
            exit 1
          fi
-          gh release upload "$RELEASE_TAG" "${files[@]}" --clobber --repo "${{ github.repository }}"
+          release_lookup="$(node scripts/github-release.mjs --repo "${{ github.repository }}" --tag "$RELEASE_TAG")"
+          gh release upload "$release_lookup" "${files[@]}" --clobber --repo "${{ github.repository }}"

      - name: Upload desktop artifacts to workflow
        if: env.SHOULD_PUBLISH != 'true'
@@ -299,7 +302,8 @@ jobs:
            echo "::error::No release artifacts found in $release_dir"
            exit 1
          fi
-          gh release upload "$RELEASE_TAG" "${files[@]}" --clobber --repo "${{ github.repository }}"
+          release_lookup="$(node scripts/github-release.mjs --repo "${{ github.repository }}" --tag "$RELEASE_TAG")"
+          gh release upload "$release_lookup" "${files[@]}" --clobber --repo "${{ github.repository }}"

      - name: Upload desktop artifacts to workflow
        if: env.SHOULD_PUBLISH != 'true'
@@ -404,7 +408,8 @@ jobs:
            echo "::error::No release artifacts found in $release_dir"
            exit 1
          fi
-          gh release upload "$RELEASE_TAG" "${files[@]}" --clobber --repo "${{ github.repository }}"
+          release_lookup="$(node scripts/github-release.mjs --repo "${{ github.repository }}" --tag "$RELEASE_TAG")"
+          gh release upload "$release_lookup" "${files[@]}" --clobber --repo "${{ github.repository }}"

      - name: Upload desktop artifacts to workflow
        if: env.SHOULD_PUBLISH != 'true'
@@ -424,7 +429,7 @@ jobs:

  finalize-rollout:
    needs: [publish-macos, publish-linux, publish-windows]
-    if: ${{ always() && (needs.publish-macos.result == 'success' || needs.publish-macos.result == 'skipped') && (needs.publish-linux.result == 'success' || needs.publish-linux.result == 'skipped') && (needs.publish-windows.result == 'success' || needs.publish-windows.result == 'skipped') && (github.event_name != 'workflow_dispatch' || github.event.inputs.publish != 'false') }}
+    if: ${{ always() && (github.event_name != 'workflow_dispatch' || github.event.inputs.publish != 'false') }}
    permissions:
      contents: write
    runs-on: ubuntu-latest
@@ -480,7 +485,7 @@ jobs:
          name: windows-manifest
          path: release-manifests/windows-manifest

-      - name: Assemble and upload stamped manifests
+      - name: Assemble manifests and publish release
        if: env.IS_SMOKE_TAG != 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -491,6 +496,33 @@ jobs:
          manifests_dir="$PWD/final"
          mkdir -p "$manifests_dir"

+          expected_manifests=(
+            "${RELEASE_CHANNEL}-mac.yml"
+            "${RELEASE_CHANNEL}-linux.yml"
+            "${RELEASE_CHANNEL}.yml"
+          )
+          release_lookup="$(node ../scripts/github-release.mjs --repo "${{ github.repository }}" --tag "$RELEASE_TAG" --cleanup-duplicates)"
+          existing_assets="$(gh release view "$release_lookup" --repo "${{ github.repository }}" --json assets --jq '.assets[].name')"
+          for manifest_name in "${expected_manifests[@]}"; do
+            if grep -Fxq "$manifest_name" <<< "$existing_assets"; then
+              case "$manifest_name" in
+                "${RELEASE_CHANNEL}-mac.yml") platform_result="${{ needs.publish-macos.result }}" ;;
+                "${RELEASE_CHANNEL}-linux.yml") platform_result="${{ needs.publish-linux.result }}" ;;
+                "${RELEASE_CHANNEL}.yml") platform_result="${{ needs.publish-windows.result }}" ;;
+              esac
+              if [[ "$platform_result" =~ ^(success|skipped)$ ]]; then
+                gh release download "$release_lookup" \
+                  --repo "${{ github.repository }}" \
+                  --pattern "$manifest_name" \
+                  --dir "$manifests_dir"
+              else
+                gh release delete-asset "$release_lookup" "$manifest_name" \
+                  --repo "${{ github.repository }}" \
+                  --yes
+              fi
+            fi
+          done
+
          if [[ "${{ needs.publish-macos.result }}" == "success" ]]; then
            manifest_name="${RELEASE_CHANNEL}-mac.yml"
            node ../scripts/merge-mac-manifest.mjs \
@@ -515,25 +547,32 @@ jobs:
          fi
          timestamp="$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")"
          node ../scripts/stamp-rollout.mjs --release-date "$timestamp" --rollout-hours "$ROLLOUT_HOURS" "${files[@]}"
-          ROLLOUT_HOURS_EXPECTED="$ROLLOUT_HOURS" RELEASE_DATE_EXPECTED="$timestamp" node -e '
-            const yaml = require("js-yaml");
-            const fs = require("fs");
-            const expectedHours = Number(process.env.ROLLOUT_HOURS_EXPECTED);
-            const expectedDate = process.env.RELEASE_DATE_EXPECTED;
-            if (!Number.isFinite(expectedHours) || expectedHours < 0) {
-              throw new Error(`expected non-negative rolloutHours, got ${process.env.ROLLOUT_HOURS_EXPECTED}`);
-            }
-            for (const f of process.argv.slice(1)) {
-              const m = yaml.load(fs.readFileSync(f, "utf8")) ?? {};
-              if (m.rolloutHours !== expectedHours) {
-                throw new Error(`${f}: rolloutHours=${m.rolloutHours}, expected ${expectedHours}`);
-              }
-              if (m.releaseDate !== expectedDate) {
-                throw new Error(`${f}: releaseDate=${m.releaseDate}, expected ${expectedDate}`);
-              }
-              if (typeof m.version !== "string" || m.version.length === 0) {
-                throw new Error(`${f}: missing or invalid version`);
-              }
-            }
-          ' "${files[@]}"
-          gh release upload "$RELEASE_TAG" "${files[@]}" --clobber --repo "${{ github.repository }}"
+          node ../scripts/validate-desktop-manifests.mjs \
+            --release-date "$timestamp" \
+            --rollout-hours "$ROLLOUT_HOURS" \
+            "${files[@]}"
+          gh release upload "$release_lookup" "${files[@]}" --clobber --repo "${{ github.repository }}"
+
+          failed_builds=()
+          [[ "${{ needs.publish-macos.result }}" =~ ^(success|skipped)$ ]] || failed_builds+=(macOS)
+          [[ "${{ needs.publish-linux.result }}" =~ ^(success|skipped)$ ]] || failed_builds+=(Linux)
+          [[ "${{ needs.publish-windows.result }}" =~ ^(success|skipped)$ ]] || failed_builds+=(Windows)
+          if (( ${#failed_builds[@]} > 0 )); then
+            echo "::error::Desktop builds did not complete for ${failed_builds[*]}; the release remains a draft"
+            exit 1
+          fi
+
+          missing_manifests=()
+          for manifest_name in "${expected_manifests[@]}"; do
+            [[ -f "$manifests_dir/$manifest_name" ]] || missing_manifests+=("$manifest_name")
+          done
+          if (( ${#missing_manifests[@]} > 0 )); then
+            echo "::error::Missing updater manifests: ${missing_manifests[*]}; the release remains a draft"
+            exit 1
+          fi
+
+          publish_args=(release edit "$release_lookup" --tag "$RELEASE_TAG" --draft=false --repo "${{ github.repository }}")
+          if [[ "$IS_PRERELEASE" == "true" ]]; then
+            publish_args+=(--prerelease)
+          fi
+          gh "${publish_args[@]}"
@@ -15,7 +15,7 @@ on:
        required: false
        type: string
      create_if_missing:
-        description: "Create release if missing (normally only needed for tag events)."
+        description: "Create a draft release if missing (normally only needed for tag events)."
        required: false
        default: false
        type: boolean
@@ -29,7 +29,6 @@ jobs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
-
    steps:
      - uses: actions/checkout@v4
        with:
@@ -1,5 +1,121 @@
 # Changelog

+## 0.8.0-beta.1 - 2026-09-08
+
+This release considerably extends what plugins can do: complete providers, custom components in the chat, slash commands, settings screens, and agent lifecycle hooks.
+
+The plugin API has a breaking change. Plugins now use separate client and server entries and runtime-owned SDK entry points, so plugins written for 0.7 must follow the [migration guide](https://paseo.sh/docs/plugins/v0.8/migration) before they load on 0.8.
+
+It also fixes regressions across desktop updates, mobile, Import session, and agent lifecycle.
+
+### Plugins
+
+- Added provider contributions: a plugin registers a complete provider, directly or through the bundled ACP shim, with its own icon, session settings, permissions, and timeline rendering ([#4314](https://github.com/getpaseo/paseo/pull/4314))
+- Added live timeline items: a plugin renders custom components in the chat by transforming timeline items at render time ([e34aea2](https://github.com/getpaseo/paseo/commit/e34aea206e6ec7ac2d5fa9766db28fb221ae990c))
+- Added durable timeline rows: a daemon handler appends its own persisted rows to an agent's timeline ([e34aea2](https://github.com/getpaseo/paseo/commit/e34aea206e6ec7ac2d5fa9766db28fb221ae990c))
+- Added slash commands: a plugin registers commands in the composer that run on the client without a provider turn ([e34aea2](https://github.com/getpaseo/paseo/commit/e34aea206e6ec7ac2d5fa9766db28fb221ae990c))
+- Added settings screens: a plugin contributes screens under Settings → Plugins from shared settings components, with host-scoped persistence, validation, and Command Center navigation ([#4357](https://github.com/getpaseo/paseo/pull/4357))
+- Added lifecycle hooks: server callbacks observe agent creation, turns, permissions, and archive events, and can answer permissions or send follow-ups ([#4435](https://github.com/getpaseo/paseo/pull/4435))
+- Added agent creation transforms: before hooks rewrite a new agent's provider, model, launch environment, MCP servers, and workspace isolation ([#4435](https://github.com/getpaseo/paseo/pull/4435))
+- Added modal bodies: a plugin owns the whole sheet body with custom padding, ScrollView or FlatList scrolling, horizontal tabs, keyboard-aware inputs, and a clipboard copy action ([#4392](https://github.com/getpaseo/paseo/pull/4392), [#4431](https://github.com/getpaseo/paseo/pull/4431))
+- Added terminals to the SDK: create, list, write, send keys, capture, and kill terminals by workspace ID ([#4358](https://github.com/getpaseo/paseo/pull/4358))
+- Added `paseo.projects.subscribe()` for live project updates ([#3983](https://github.com/getpaseo/paseo/pull/3983) by [@omercnet](https://github.com/omercnet))
+- Added `agent.respondToPermission()` to answer pending permissions from a plugin ([#3985](https://github.com/getpaseo/paseo/pull/3985) by [@omercnet](https://github.com/omercnet))
+- Added version requirements: `requirements.paseo` in `paseo-plugin.json` declares the supported Paseo versions, incompatible installs, updates, and reloads are rejected before any code runs, and prerelease Paseo versions satisfy any range their stable core satisfies ([#4430](https://github.com/getpaseo/paseo/pull/4430), [#4452](https://github.com/getpaseo/paseo/pull/4452))
+- Changed plugins to separate `index.client.ts` and `index.server.ts` entries with `client/`, `server/`, and `shared/` directories; plugins written for 0.7 must follow the [migration guide](https://paseo.sh/docs/plugins/v0.8/migration) ([#4206](https://github.com/getpaseo/paseo/pull/4206))
+- Changed the plugin SDK into runtime-owned entry points: `@getpaseo/plugin` for shared code, `@getpaseo/plugin/client` for the app, and `@getpaseo/plugin/server` for the daemon, with crossed imports rejected at compile time ([#4347](https://github.com/getpaseo/paseo/pull/4347) by [@liujin0506](https://github.com/liujin0506), [@panrafal](https://github.com/panrafal))
+- Changed legacy plugin load failures to say the plugin was built for an older Paseo and link to the migration guide ([#4265](https://github.com/getpaseo/paseo/pull/4265))
+- Changed `paseo plugin ls` to report runtime state, source, installed commit, and load errors without contacting a remote ([#4265](https://github.com/getpaseo/paseo/pull/4265))
+- Fixed workspace plugin panels missing from the Explorer tab-rail menu ([#4446](https://github.com/getpaseo/paseo/pull/4446))
+- Added versioned plugin documentation for v0.7 and v0.8 with a migration guide ([#4245](https://github.com/getpaseo/paseo/pull/4245), [#4452](https://github.com/getpaseo/paseo/pull/4452))
+
+### Added
+
+- Added Import session to the sidebar footer, the History and sidebar empty states, and the Command Center ([#4216](https://github.com/getpaseo/paseo/pull/4216))
+- Added search, Load more, and a This workspace / Show all scope to the Import session sheet ([#4216](https://github.com/getpaseo/paseo/pull/4216))
+- Added customizable top-level sidebar items: reorder and hide New workspace, History, Search, Schedules, and plugin items from Appearance settings ([#4203](https://github.com/getpaseo/paseo/pull/4203))
+- Added provider notifications from Pi extensions and OpenCode as timeline items with info, warning, and error levels ([#3411](https://github.com/getpaseo/paseo/pull/3411) by [@trim21](https://github.com/trim21))
+- Added a fullscreen viewer for Mermaid diagrams on web and desktop ([#4107](https://github.com/getpaseo/paseo/pull/4107) by [@gengjiawen](https://github.com/gengjiawen))
+- Added Copy, Copy line, and Select all to the web diff context menu, with Cmd/Ctrl+A and Escape ([#4229](https://github.com/getpaseo/paseo/pull/4229))
+- Added Gajae Code to the ACP provider catalog ([#3471](https://github.com/getpaseo/paseo/pull/3471) by [@Yeachan-Heo](https://github.com/Yeachan-Heo))
+- Added per-provider Paseo tool policy in daemon config to disable all or selected Paseo tools for a provider ([#4277](https://github.com/getpaseo/paseo/pull/4277) by [@mcowger](https://github.com/mcowger))
+- Added explicit setup approval for fork pull request workspaces: setup, automatic terminals, and scripts wait for Run setup or `paseo workspace setup <id>` ([#4215](https://github.com/getpaseo/paseo/pull/4215))
+- Added Hub follow-ups to existing agents, archived workspace recovery, and provider catalog discovery through the daemon API ([#4354](https://github.com/getpaseo/paseo/pull/4354), [#4242](https://github.com/getpaseo/paseo/pull/4242))
+
+### Changed
+
+- Changed the desktop app to require macOS 13 or newer; macOS 12 stops receiving desktop updates ([#4322](https://github.com/getpaseo/paseo/pull/4322))
+- Changed `--host` to a global CLI option: `paseo --host <target> <command>` ([#4238](https://github.com/getpaseo/paseo/pull/4238))
+- Changed the sidebar footer Home button to Import session; the Home route and tile remain ([#4216](https://github.com/getpaseo/paseo/pull/4216))
+
+### Improved
+
+- Reconnected every host immediately on app foreground instead of waiting for reconnect backoff ([#4160](https://github.com/getpaseo/paseo/pull/4160))
+- Smoothed mobile keyboard transitions by moving the timeline and composer together instead of relaying out every frame ([#4275](https://github.com/getpaseo/paseo/pull/4275))
+- Reloaded only the providers whose configuration changed instead of restarting every provider and resetting every catalog ([#4332](https://github.com/getpaseo/paseo/pull/4332))
+- Shortened agent tab tooltips to one title line with the agent ID and last activity ([#4214](https://github.com/getpaseo/paseo/pull/4214))
+- Added macOS updater and ShipIt state to App Diagnostics ([#4322](https://github.com/getpaseo/paseo/pull/4322))
+
+### Fixed
+
+- Fixed the mobile terminal keyboard closing and reopening when using toolbar keys or Enter ([#4469](https://github.com/getpaseo/paseo/pull/4469))
+- Fixed macOS desktop updates closing the app without installing the new version ([#4322](https://github.com/getpaseo/paseo/pull/4322))
+- Fixed the desktop updater reporting up to date while a new release had no updater manifests yet ([#4201](https://github.com/getpaseo/paseo/pull/4201))
+- Fixed `paseo restart` failing from the desktop-installed CLI on Linux `.deb`, RPM, and tarball installs ([#4207](https://github.com/getpaseo/paseo/pull/4207))
+- Fixed the packaged macOS Dock icon rendering oversized ([#4389](https://github.com/getpaseo/paseo/pull/4389))
+- Fixed cached conversations and the workspace list not painting when live updates arrived during cache reads ([#4436](https://github.com/getpaseo/paseo/pull/4436))
+- Fixed queued messages not sending after a turn completed while the app was in the background ([#4160](https://github.com/getpaseo/paseo/pull/4160))
+- Fixed the New workspace form losing the selected model after creating a workspace ([#4401](https://github.com/getpaseo/paseo/pull/4401))
+- Fixed a crash with `Select a model` when the selected provider disappeared during workspace creation ([#4332](https://github.com/getpaseo/paseo/pull/4332))
+- Fixed Codex model rows staying on Loading forever in the New workspace model picker ([#4283](https://github.com/getpaseo/paseo/pull/4283) by [@colonelpanic8](https://github.com/colonelpanic8))
+- Fixed reloading a Codex agent failing with `already has an active writer` ([#4353](https://github.com/getpaseo/paseo/pull/4353))
+- Fixed Pi agents stuck running after an extension-triggered turn ([#3849](https://github.com/getpaseo/paseo/pull/3849) by [@mjakl](https://github.com/mjakl))
+- Fixed nested provider subagents shown as direct children of the root agent and their notifications appearing in the root timeline ([#4321](https://github.com/getpaseo/paseo/pull/4321))
+- Fixed repeated provider tool-call IDs across autonomous turns producing duplicate timeline rows ([140b0bb](https://github.com/getpaseo/paseo/commit/140b0bb716205cf0e00c0ff5b6b3c20af6c79413))
+- Fixed the Import session spinner never stopping when one provider hung; the provider now shows an inline error with Retry ([#4216](https://github.com/getpaseo/paseo/pull/4216))
+- Fixed Import session ignoring Claude Code `/rename` titles ([#4216](https://github.com/getpaseo/paseo/pull/4216))
+- Fixed importing a session into a directory with an active workspace creating a duplicate workspace ([#4216](https://github.com/getpaseo/paseo/pull/4216))
+- Fixed empty ACP sessions appearing in Import session ([#4335](https://github.com/getpaseo/paseo/pull/4335))
+- Fixed diff file headers lagging behind the document while scrolling on web and desktop ([#4240](https://github.com/getpaseo/paseo/pull/4240))
+- Fixed the Changes tree and its working diff going out of sync when switching between Committed and Uncommitted ([#4199](https://github.com/getpaseo/paseo/pull/4199))
+- Fixed Mermaid diagrams shrinking on every streaming re-render and the inline diagram box collapsing ([#4107](https://github.com/getpaseo/paseo/pull/4107) by [@gengjiawen](https://github.com/gengjiawen))
+- Fixed Mermaid source corrupted on reload when cached history overlapped the live message ([#4210](https://github.com/getpaseo/paseo/pull/4210))
+- Fixed Settings navigation retaining closed views in memory on desktop ([#4228](https://github.com/getpaseo/paseo/pull/4228))
+- Fixed the file watcher missing nested directory changes on Windows ([#4354](https://github.com/getpaseo/paseo/pull/4354), [#4358](https://github.com/getpaseo/paseo/pull/4358))
+- Fixed daemon Git commands honoring a repository's `core.fsmonitor`, which let a checkout run its own command ([#4208](https://github.com/getpaseo/paseo/pull/4208))
+- Fixed terminal activity reporting for OpenCode 2 sessions started from a terminal ([#4300](https://github.com/getpaseo/paseo/pull/4300) by [@mr-karan](https://github.com/mr-karan))
+- Changed the plugin SDK's React peer range to `~19.1.0` so CLI installs resolve a patched 19.1.x instead of the version dependency scanners flag ([#4100](https://github.com/getpaseo/paseo/pull/4100) by [@liujin0506](https://github.com/liujin0506))
+- Fixed the paseo.sh homepage offering the Mac download to every visitor before hydration and desktop builds to phones ([#4222](https://github.com/getpaseo/paseo/pull/4222))
+
+## 0.7.2 - 2026-09-02
+
+### Added
+
+- Added active-turn steering for pi agents so new messages reach the running turn without interrupting it ([#3752](https://github.com/getpaseo/paseo/pull/3752) by [@mcowger](https://github.com/mcowger))
+- Added declared build commands and monorepo source paths for Git-hosted plugins ([#4158](https://github.com/getpaseo/paseo/pull/4158))
+
+### Improved
+
+- Reduced JS stalls while watching a streaming agent on mobile ([#4190](https://github.com/getpaseo/paseo/pull/4190))
+
+### Fixed
+
+- Fixed large and many-file diffs stalling or crashing while opening and scrolling ([#4174](https://github.com/getpaseo/paseo/pull/4174))
+- Fixed mobile sidebar and explorer panels losing their settled position when a JS stall crossed the animation ([#4190](https://github.com/getpaseo/paseo/pull/4190))
+- Fixed a single oversized assistant message crashing the timeline by capping rendered content at 32,000 characters ([#4166](https://github.com/getpaseo/paseo/pull/4166))
+- Fixed Codex rewind failing on paginated threads with Codex 0.151 and later ([#4119](https://github.com/getpaseo/paseo/pull/4119))
+- Fixed Escape closing an image preview also interrupting the running agent ([#4161](https://github.com/getpaseo/paseo/pull/4161))
+- Fixed daemon stop and restart on Windows skipping graceful shutdown and orphaning agent processes ([#4168](https://github.com/getpaseo/paseo/pull/4168))
+- Fixed OMP startup timing out at 10 seconds regardless of the configured RPC timeout ([#4143](https://github.com/getpaseo/paseo/pull/4143) by [@Juns-g](https://github.com/Juns-g))
+- Fixed completed turns without a visible prompt showing no completion time ([#4170](https://github.com/getpaseo/paseo/pull/4170))
+- Fixed Explorer renames replacing an existing file when file identity metadata is unavailable ([#4171](https://github.com/getpaseo/paseo/pull/4171))
+
+## 0.7.1 - 2026-09-01
+
+### Added
+
+- Added Claude Fable 5.1 with a 1M context window ([#4179](https://github.com/getpaseo/paseo/pull/4179))
+
 ## 0.7.0 - 2026-08-31

 ### Changed
@@ -108,6 +108,8 @@ See [docs/development.md](docs/development.md) for full setup, build sync requir

 ## Critical rules

+- **Before changing the plugin SDK, compiler, host module maps, scaffold, or examples, read [SDK import boundaries](docs/plugins.md#sdk-import-boundaries).** Classify the export by runtime first and preserve the enforced boundaries.
+
 - **NEVER restart the main Paseo daemon on port 6767 without permission** — it manages all running agents. If you're an agent, restarting it kills your own process.
 - **NEVER assume a timeout means the service needs restarting** — timeouts can be transient.
 - **NEVER add auth checks to tests** — agent providers handle their own auth.
@@ -1,140 +1,104 @@
 # Contributing to Paseo

-Thank you for taking the time to contribute to Paseo.
+This guide is here to save us both time and help you find a useful way to contribute.
+
+Paseo grows through bug reports, testing, workflow discussions, plugins, documentation, and people helping each other. The sections below explain where each contribution belongs and what to expect.

 ## Philosophy

-Paseo is an opinionated product, built on freedom and flexibility: any agent provider, any device, running on your own machine. It is meant to be composable, so you can build the workflow you want. Read more about the product vision [here](docs/product.md).
+**Paseo has a lean, opinionated core built to be extended.**

-Given Paseo's scope, contributing to it takes a lot of context that is very hard to transfer. That's why product, design, architecture, and workflow decisions are currently all made by the maintainer.
+The goal is a low floor and a high ceiling: a polished default experience that is easy to understand, with the flexibility to choose your providers, run on your own infrastructure, and build your own workflows. Paseo should remain self-hosted and respectful of your privacy and control.

-I pick what to build based on whether it fits the product, how many workflows it improves, whether it keeps things composable, whether we can hold the quality bar, and whether I want to build it.
+The core continues to evolve through improvements to the shared experience. Specialized workflows and integrations belong in the extension ecosystem. Product, design, architecture, and workflow decisions remain with the maintainer.

-## Report bugs in GitHub issues or Discord
+Read the [product philosophy](docs/product.md) for the reasoning behind these choices and how Paseo develops.

-Open an [issue](https://github.com/getpaseo/paseo/issues) or post in [Discord](https://discord.gg/jz8T2uahpH).
+## Build a plugin

-> [!IMPORTANT]
-> Feature requests opened as issues will get closed automatically
+Most specialized workflows and integrations are better served by plugins.

-If you used an agent to investigate, paste the raw evidence and repro steps it collected, not its diagnosis.
+Plugins let you build what you need, share it, and maintain it independently. Start with the [plugin documentation](https://paseo.sh/docs/plugins). For applications and integrations built around Paseo, see the [SDK documentation](https://paseo.sh/docs/sdk).

-You may submit a PR to fix a bug, please read the PR guidelines below.
+If an extension point is missing, describe the workflow in [Discussions](https://github.com/getpaseo/paseo/discussions). A reusable capability that enables several plugins may be a better addition than implementing one particular workflow in core.

-## Product discussions go in GitHub Discussions or Discord
+## Report bugs

-There's no feature request backlog. Open a product discussion in [Discussions](https://github.com/getpaseo/paseo/discussions) or `#product` in [Discord](https://discord.gg/jz8T2uahpH), and frame it as a workflow:
+Open a [GitHub issue](https://github.com/getpaseo/paseo/issues) and fill out the bug report template.
+
+Include:
+
+- What you did, what you expected, and what happened.
+- Reproduction steps, Paseo version, and platform.
+- Relevant logs, screenshots, or a recording.
+
+If an agent investigated, include the evidence and reproduction steps it collected. Its explanation of the cause still needs verification.
+
+Focused fixes for reproducible bugs are welcome. If you submit one, follow the pull request and QA guidance below.
+
+## Discuss workflows before proposing features
+
+Product discussions, including feature requests, belong in [GitHub Discussions](https://github.com/getpaseo/paseo/discussions). Feature requests opened as issues will be closed.
+
+Explain:

 - What are you trying to do?
 - How do you do it today?
 - Where does Paseo get in the way?
- What would the flow look like if it worked for you?
+- What would a better workflow look like?

-"Can you build X" is not useful because it doesn't tell me about your problem.
+This helps other people describe their needs and gives me useful context when deciding what to build.

-A discussion also lets other people add their own version of the same problem, and that's what I read when I decide what to build.
+There is no feature request backlog or commitment to implement a discussion. I may read and learn from it without replying.

-Due to the volume and my limited bandwidth, I may not participate in all the discussions, if something gains interest it will make it's way to me.
+## If you still want to submit a pull request

-## Pull requests
+After considering plugins and discussing the workflow, you may still want to propose a change to core. Focused fixes for reproducible bugs are also welcome.

-Anyone can open a pull request, but there are no guarantees of it getting merged, only submit one if you're okay with it being closed.
+**Pull requests are closed by default.** I may reopen the ones I want to take forward. Submit one only if you are comfortable with it being closed without a detailed review or explanation.

-Open it as a draft if the work isn't ready for review, if you want to run the checks against it, or if you want feedback on the direction before you finish it. Mark it ready when you want it looked at.
+Paseo receives more pull requests than I can responsibly review. Reviewing every submission and explaining every decision would consume the time available for developing the product.

-Here is the criteria I use to decide:
+I can prompt an agent to write code just as you can. The bottlenecks are choosing what to build, shaping it, verifying its behavior, and taking responsibility for its maintenance. A finished implementation still leaves that work to do.

-✅ Likely to be accepted
+If you choose to submit a PR, these are the basics to cover.

- Fits the product vision
- One focused change
- Links the bug it fixes, or the discussion behind it if there is one
- Addresses bot reviews
- Explains the problem you're solving
- QA evidence
- Automated tests
- Screenshots or video for UI changes, on every affected platform
- Says which platforms you tested and which you didn't
- Maintainer edits enabled
+### What I look for in a core feature

-⛔️ Will be rejected
+- **Demonstrated demand.** Link a discussion with concrete examples of other users needing the workflow. A feature for a small, specialized use case belongs in a plugin.
+- **Value across workflows.** The feature should improve how existing capabilities work together and benefit a broad set of users. A reusable improvement is more valuable than an isolated control for one task.
+- **A coherent design across platforms and providers.** Shared capabilities should work across platforms and providers wherever applicable. Do not reshape a shared abstraction around one provider while leaving the others unsupported or inconsistent.
+- **A finished experience.** Follow the [design guidelines](docs/design.md). The feature must look and feel right in Paseo, including loading states, layout stability, and interaction performance. PRs with janky or rushed interfaces will be closed. Design judgment remains with the maintainer.

- Bundles unrelated changes
- Fails checks
- Ignores bot reviews
- Takes a feature or the design in a direction I don't want
- No QA evidence
- No tests
- Clearly fully AI-generated PR
+### Keep the scope small

-### What to expect
+Submit one focused change. PRs adding more than roughly **3,000 lines of production code** are unlikely to be accepted. Prefer the smallest complete improvement that can be tested and understood on its own.

- PRs that were explicitly approved in a discussion are preferred.
- Unsolicited PR can be closed without a detailed review.
- Your PR can be narrowed, refactored, or redesigned.
- Your PR might be accepted but not merged immediately.
- You will be attributed for your work in the changelog, even if I redesign your PR
+### QA evidence

-## QA evidence
+Run the changed application or service and test the affected workflow yourself. Include detailed QA evidence so I can see what you exercised and what happened. PRs without this verification and evidence will be closed, whether they fix a bug or add a feature.

-QA is the main bottleneck of Paseo's product development, and it's not just whether the feature works, it's also whether it meets the quality bar.
+Explain the problem and link the relevant bug report or discussion. Include:

-Pull requests without evidence will be closed.
+- Automated tests that exercise the changed behavior. A bug fix needs a regression test that fails on the broken version.
+- The commands you ran and their output.
+- A recording for interactive UI changes, or before-and-after screenshots for static changes.
+- The platforms you tested and any affected platforms you could not test.

-What's accepted:
+The [QA guide](docs/qa.md) explains the expected evidence and available tooling.

- The shell commands you ran, pasted with their output
- The tests you added and their results
- Before and after screenshots
- A video of the whole interaction
- Logs, requests, responses
+Using an agent is welcome. Sending it to implement a change and submitting its output without trying the result yourself does not meet this bar.

-Bugs and features both need automated tests, and the tests have to exercise the real thing. UI changes need a video, or a screenshot if it's static.
+**Satisfying all of the above does not mean your pull request will be merged.**

-The [QA guide](docs/qa.md) covers what to check for each of these and the tooling to do it.
+### What happens to your contribution

-## I want to become a maintainer
+If I take a contribution forward, I may narrow it, reshape it, or use it as a reference for my own implementation. **You will be credited for your contribution, including when I reimplement it.**

-There's no formal process to become a maintainer, just consistently get involved with the project by answering questions, testing, reproducing bugs, discussing workflows with the community and offer to implement features when we reach an agreement.
+A closed PR does not necessarily mean the underlying problem was dismissed. It means I am not taking that submission forward. Detailed reviews, individual explanations, and follow-up discussions cannot be provided at this volume.

-## FAQ
+## Help the community

-### I'm blocked, where do I go?
+Testing betas, reproducing bugs, improving documentation, sharing plugins, and answering questions all help Paseo develop.

-Join [Discord](https://discord.gg/jz8T2uahpH), ask your questions there.
-
-### Do you prefer Github or Discord?
-
-I am more active on Discord for general questions.
-
-I prefer Github for bugs because the template helps collect information more efficiently.
-
-### Why was my feature request closed?
-
-Issues are only for bugs. Open it as a product discussion instead, framed as a workflow.
-
-### Why didn't my PR get a detailed review?
-
-Writing a review is very time consuming and Paseo receives a lot of PRs, I cannot give detailed explanations at volume.
-
-### How long until someone looks at my pull request?
-
-It depends on what else is going on. QA takes longer than reading the diff. You are welcome to join Discord to ask.
-
-### Why do you want tests and a video for a small change?
-
-Because it's faster and safer than me checking out and running every PR myself to test it manually.
-
-QA evidence help me take your PR seriously for a deeper review and maintainer QA.
-
-### I only have one platform, can I still contribute?
-
-Yes. Test what you have, and say what you didn't test.
-
-### Can I use an agent to write my contribution?
-
-Yes, as long as you understand what you're submitting and you tested it yourself.
-
-### Is there a roadmap I can read?
-
-[docs/product.md](docs/product.md) covers the direction. There's no public list of what I'm building next.
+There is no formal process for becoming a maintainer. Consistent involvement and good judgment build the shared context needed to take on more responsibility.
@@ -47,6 +47,15 @@ Run agents in parallel on your own machines. Ship from your phone or your desk.
 - **Cross-device:** iOS, Android, desktop, web, and CLI. Start work at your desk, check in from your phone, script it from the terminal.
 - **Privacy-first:** Paseo doesn't have any telemetry, tracking, or forced log-ins.

+## Plugins
+
+Add themes, workspace panels, commands, settings screens, and coding-agent providers with trusted
+TypeScript plugins. Install from a local directory or Git repository with `paseo plugin add <source>`.
+
+See the [plugin docs](https://paseo.sh/docs/plugins) for your Paseo version, or start with the
+[0.8 beta quickstart](https://paseo.sh/docs/plugins/v0.8). Plugins run with access to your daemon
+machine and inside connected clients; install only code you trust.
+
 ## Getting Started

 Paseo runs a local server called the daemon that manages your coding agents. Clients like the desktop app, mobile app, web app, and CLI connect to it.
@@ -50,6 +50,10 @@ 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.

+When Paseo checks out a change request from a different repository, it does not run that workspace's `paseo.json` setup, automatic terminals, named scripts, or teardown until you explicitly run setup for that workspace. The decision lasts for the workspace and does not re-prompt after new commits. Same-repository changes, ordinary branches, local workspaces, agent launches, terminals, explicit shell commands, and metadata-generation instructions are outside this gate.
+
+An explicit `symlink <path>` entry in a repository's `.worktreeinclude` 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
@@ -21,6 +21,10 @@ 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.

+Reload releases the old runtime before resuming its durable session: an idle provider process can
+still own an exclusive writer. A close failure retains that runtime for cleanup and blocks the
+replacement. Once closure succeeds, a failed resume leaves the durable agent closed and retryable.
+
 Idle agents remain resident indefinitely. Runtime closure happens only through an explicit lifecycle
 action such as archive, replacement, reload, workspace teardown, or daemon shutdown.

@@ -144,6 +148,10 @@ Workspace status is an aggregate activity signal computed **per `workspaceId`**.

 Running provider-native subagents contribute `running` to the workspace owned by their parent agent. Their completed, failed, and canceled states stay in the parent's subagents track.

+A finished workspace can be marked unread after it has been reviewed. The daemon restores
+`finished` attention on its newest eligible workspace-root agent without sending a new completion
+notification. Opening the workspace clears that attention through the normal focus flow.
+
 ## The subagents track

 The track is a pill at the foot of an agent's pane (`packages/app/src/subagents/track.tsx`): a count you can read at a glance, and a panel behind it — a popover on wide screens, a sheet on compact ones — holding the rows. It floats over the transcript rather than sitting in a band above the composer, so the timeline scrolls underneath it; `packages/app/src/panels/agent-tracks.tsx` owns that placement, and the pill frame is shared with the task list in `packages/app/src/composer/tracks.tsx`.
@@ -156,9 +164,9 @@ The rows combine two kinds of children:
 parentAgentId === thisAgent.id  AND  !archivedAt
 ```

- **Provider subagents** are child executions owned by Claude, Codex, or OpenCode. They are not inserted into `AgentManager` as managed agents. Providers emit a separate descriptor and timeline stream through `agent.provider_subagents.*`; the client keeps that state outside the normal agent store and merges only the presentation rows into the track.
+- **Provider subagents** are child executions owned by Claude, Codex, or OpenCode. They are not inserted into `AgentManager` as managed agents. Providers emit a separate descriptor and timeline stream through `agent.provider_subagents.*`; the client keeps that state outside the normal agent store and merges only the presentation rows into the track. A descriptor's optional `parentSubagentId` identifies its direct provider-subagent parent; an absent value identifies a direct child of the managed agent.

-Clicking either kind opens a workspace tab. A Paseo subagent tab is a normal interactive agent pane. A provider subagent tab is a read-only timeline pane with no composer, archive, detach, rewind, or fork actions. Both panes use `AgentStreamView`, so message, reasoning, tool-call, and layout rendering stay identical.
+Clicking either kind opens a workspace tab. A Paseo subagent tab is a normal interactive agent pane. A provider subagent tab is a read-only timeline pane with no composer, archive, detach, rewind, or fork actions. It shows its own direct children in a subagents track. Both panes use `AgentStreamView`, so message, reasoning, tool-call, and layout rendering stay identical.

 Provider timelines use the same structural timeline item format but deliberately have a separate lifecycle and transport. A provider thread/session identifier is not a Paseo agent identifier, and closing its tab is always layout-only.

@@ -174,7 +182,8 @@ Claude Code announces subagent lifecycle on the SDK stream (`task_started` / `ta
 - **A resumed task can be announced again with a new `tool_use_id`.** The first Task tool id remains the canonical descriptor and later ids are routing aliases for the same session-scoped task. The resumed prompt is added to that child timeline.
 - **Effort is only reachable through hooks.** It appears nowhere on the message stream at any depth, and the level Paseo requests is not necessarily the level that runs — a model that does not support it is silently downgraded. A hook firing inside a subagent reports the active post-downgrade level next to its `agent_id`, which is the same id `task_started` calls `task_id`.
 - **Backgrounded subagents emit no frames carrying `parent_tool_use_id` at all.** Everything keyed off that field sees nothing for one; they are visible only because the task protocol announces them.
- **On replay, `<session>/subagents/` holds every descendant, not just this session's children.** `agent-<id>.meta.json` carries `spawnDepth`: `1` is a direct child, `2+` was spawned by another subagent and its `toolUseId` names a Task call made inside its parent's session, which nothing in this transcript can resolve. Replaying those adds rows the live stream never showed, each with no Task card and no recoverable outcome, so they render as running forever. One recorded session showed 10 subagents live and would have replayed 22.
+- **Nested ownership comes from the launching sidechain, not `spawn_depth` alone.** A sidechain's Agent or Bash tool call records the direct owner of that `tool_use_id`; the following `task_started` inherits it. This routes a grandchild descriptor and child-owned background notifications without relying on labels or flattening them into the managed parent.
+- **On replay, `<session>/subagents/` holds every descendant beside the root.** Resolve the tree one proven generation at a time: the root transcript admits direct children, then each admitted sidechain transcript admits its children by `toolUseId`. `spawnDepth` orders candidates but does not establish ownership. Unresolved sidecars remain excluded as ambient or unrelated work.
 - **Replay `totalTokens` is a context-size reading, not cumulative spend.** Claude Code finalizes a subagent by summing the _last_ assistant message's usage block and shipping that as `usage.total_tokens`. Summing per-entry usage instead multiplies the cached prefix by the turn count and reports a number several times larger than the live path.

 Archived Paseo subagents disappear from the track, by design. To remove one from the track without closing its tab, use the **archive button** on the row — it opens a confirm dialog and archives the subagent on confirm. Provider-owned rows have no individual Paseo lifecycle controls.
@@ -31,6 +31,15 @@ So arrival sets a _target_ and the reveal rate is derived from the backlog inste
 - **First sight of a text is revealed whole.** Only growth is paced. This is what makes history hydration, timeline replay, a virtualized row remounting on scroll, and an already-finished message all render complete on first paint without a special case for each.
 - **Leaving `phase: "streaming"` snaps the reveal.** A completed turn must never be left holding characters. `layoutStream` sets the phase, so anything outside the live head with an active turn is already complete.
 - **The reducer queue commits on a frame, with a timer as the ceiling.** A frame callback never fires in a hidden tab, so a timer races it and wins when nothing is painting — the store has to keep advancing either way.
+- **A history row re-renders only when its item or layout item identity changes.** The inverted
+  FlatList hands every mounted cell a new `index` and `ref` whenever a row is prepended, so without a
+  memo boundary each coalesced tick re-rendered every mounted row (about 50 on a phone, 100–250 ms of
+  JS per tick). `layoutStream` keeps a layout item's identity when nothing about it changed,
+  `useRevisedHistoryRows` hands a fresh item identity to rows whose tool-call group, expanded state,
+  or breakpoint changed, and `HistoryStreamRow` memoizes on both. Every viewport runs its history
+  through that hook; the web viewport once skipped it and history hosts of a live tool group went
+  stale. A new field on `StreamLayoutItem` must be added to `areLayoutItemsEquivalent`, or sharing
+  silently stops.

 ## Measuring

@@ -94,9 +94,10 @@ facade. App and CLI may import the low-level driver from
 `@getpaseo/client/internal/daemon-client` during migration, while new SDK-shaped
 code imports from `@getpaseo/client`.

-`PaseoApi` is the capability-only boundary over workspaces, agents, providers, and config.
+`PaseoApi` is the capability-only boundary over workspaces, agents, terminals, providers, and config.
 `PaseoClient` adds connection lifecycle. App plugin surfaces borrow an API over their selected
-host's client; plugin subprocesses use the same facade over a host-owned IPC transport.
+host's client; plugin subprocesses use the same facade over a host-owned IPC transport. Protocol capability ownership and subscription lifetimes follow
+[the client contract](protocol-compatibility.md#client-capability-ownership).

 ### `packages/app` — Mobile + web client (Expo)

@@ -355,13 +356,13 @@ Two workspaces can share the same `cwd` (e.g. a `directory` workspace and a `loc

 | State                        | Key builder / store                                | Source                                                        |
 | ---------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
-| Review draft comments        | `buildReviewDraftKey` / `buildReviewDraftScopeKey` | `packages/app/src/review/store.ts`                            |
-| Diff mode override           | review-draft scope key (in-memory)                 | `packages/app/src/review/state.ts`                            |
+| Review draft comments        | `buildReviewDraftKey`                              | `packages/app/src/review/store.ts`                            |
+| Working diff comparison      | `workingDiffComparisonKey` (in-memory)             | `packages/app/src/git/working-diff-comparison/state.ts`       |
 | Composer attachments         | `buildWorkspaceAttachmentScopeKey`                 | `packages/app/src/attachments/workspace-attachments-store.ts` |
 | File explorer nav/open state | `fileExplorer` map keyed `workspace:{workspaceId}` | `packages/app/src/hooks/use-file-explorer-actions.ts`         |
 | File explorer expanded paths | `expandedPathsByWorkspace[workspaceStateKey]`      | `packages/app/src/stores/panel-store/state.ts`                |

-`diff-pane.tsx` is the canonical wiring site: it passes `{ serverId, cwd }` to the git queries and `{ serverId, workspaceId, cwd }` to the draft/override/attachment scope keys.
+`diff-pane.tsx` is the canonical wiring site: it passes `{ serverId, cwd }` to the git queries and `{ serverId, workspaceId, cwd }` to the draft/comparison/attachment scope keys.

 **Do not "fix" the sharing away.** Re-keying a directory-backed query by `workspaceId` makes same-`cwd` workspaces diverge (two windows onto the same git tree showing different diffs). Re-keying owned state (drafts, expanded paths) by `cwd` makes them leak between distinct workspaces on the same folder. The `workspaceId`-keyed builders carry a `// workspaceId is opaque; do not parse this key back into a path.` comment — the opaque-id fallback to `cwd` exists only for old payloads without a `workspaceId`, not as a content-sharing mechanism.

@@ -404,7 +404,7 @@ Custom OMP profiles should extend `omp`. They inherit the OMP adapter's `rpc-ui`
 }
 ```

-`params.sessionDir` is used only for importing sessions that were started outside Paseo. If `command` or XDG env vars move OMP's state directory, set `params.sessionDir` to the resulting OMP JSONL session directory; launching and resuming still go through the configured command. `params.rpcTimeoutMs` overrides the 60-second OMP control-plane RPC deadline.
+`params.sessionDir` is used only for importing sessions that were started outside Paseo. If `command` or XDG env vars move OMP's state directory, set `params.sessionDir` to the resulting OMP JSONL session directory; launching and resuming still go through the configured command. OMP waits 20 seconds for its initial `ready` frame and 60 seconds for later control-plane RPCs by default. `params.rpcTimeoutMs` overrides both deadlines.

 For other providers that keep Pi's `--mode rpc` API but write sessions somewhere else, extend `pi`, replace the command, and provide the JSONL session directory:

@@ -275,6 +275,45 @@ rather than storing something it cannot describe. That is why the client gates t
 UI on `server_info.features.agentProfiles` instead of letting a save appear to succeed against an
 older daemon.

+### Agent provider Paseo tools
+
+`agents.providers` is keyed by the exact provider ID used to launch the agent. The built-in IDs are
+`claude`, `codex`, `copilot`, `opencode`, `pi`, and `omp`. Custom provider IDs are their literal
+configuration keys, such as `my-claude` or `zai`, not the provider named by `extends`.
+
+Each entry may include a Paseo-tool policy:
+
+```json
+{
+  "agents": {
+    "providers": {
+      "my-claude": {
+        "extends": "claude",
+        "label": "My Claude",
+        "paseoTools": {
+          "enabled": true,
+          "disabledTools": ["browser_evaluate"]
+        }
+      }
+    }
+  }
+}
+```
+
+Absent `paseoTools`, or absent fields within it, means Paseo tools are enabled and all tools are
+allowed. `enabled: false` disables the provider's Paseo catalog; `disabledTools` lists exact tool
+IDs to omit. The policy covers the core and browser catalog, not the voice-only `speak` tool.
+Browser tools also require `daemon.browserTools.enabled` and a connected browser host.
+This policy controls the catalog presented to an agent. It is not an authorization boundary for
+agents that can access the host through a shell.
+
+`daemon.mcp.injectIntoAgents` is the global override. When it is `false`, no provider receives
+Paseo tools; otherwise the provider policy applies. Provider and global policy are resolved when a
+session is created, resumed, imported, or reloaded, so configuration changes affect the next
+session rather than an already-running one.
+
+`agents.metadataGeneration.providers` controls the preferred structured-generation fallback order for daemon-side metadata tasks such as commit messages, PR text, branch names, and generated agent titles. Entries are tried first in the configured order, then Paseo falls through to dynamically discovered defaults and finally the current selection when available.
+
 ### Git process limits

 Git process limits are global to one daemon. The start-rate limit defaults to `64` processes per
@@ -439,25 +478,26 @@ workspace together with its owning project.

 Array of workspace records. A workspace is a specific working directory within a project.

-| Field                          | Type                                            | Description                                                                                                                                                                                   |
-| ------------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `workspaceId`                  | `string`                                        | Opaque stable identifier (`wks_<hex>`), generated independently of the directory. MUST NOT be treated as a path; compare by exact equality. Use the `cwd` field for directory access.         |
-| `projectId`                    | `string`                                        | FK to Project.projectId; the workspace's stable project membership                                                                                                                            |
-| `cwd`                          | `string`                                        | Exact execution directory selected for agents, files, scripts, and setup                                                                                                                      |
-| `kind`                         | `"local_checkout" \| "worktree" \| "directory"` | Mutable checkout classification                                                                                                                                                               |
-| `displayName`                  | `string`                                        | The human name (the generated/derived title). Decoupled from `branch` by construction.                                                                                                        |
-| `title`                        | `string \| null`                                | User-set name override layered over `displayName`. Null means "use `displayName`".                                                                                                            |
-| `branch`                       | `string \| null`                                | The current Git branch for git-backed workspaces. Separate from `displayName`/`title`; a background branch refresh never rewrites the name.                                                   |
-| `worktreeRoot`                 | `string \| null`                                | Backing checkout/worktree root. May differ from `cwd` for exact subprojects and remains persisted after the worktree is deleted so restore can reproduce the placement.                       |
-| `baseBranch`                   | `string \| null`                                | Normalized branch the Paseo worktree was created from; null for directories, local checkouts, and checkout-branch worktrees                                                                   |
-| `isPaseoOwnedWorktree`         | `boolean`                                       | Whether Paseo owns and may remove/recreate the backing `worktreeRoot`                                                                                                                         |
-| `mainRepoRoot`                 | `string \| null`                                | Main repository root for worktree checkouts, independent of both exact `cwd` and backing `worktreeRoot`                                                                                       |
-| `createdAt`                    | `string` (ISO 8601)                             |                                                                                                                                                                                               |
-| `updatedAt`                    | `string` (ISO 8601)                             |                                                                                                                                                                                               |
-| `archivedAt`                   | `string \| null` (ISO 8601)                     | Soft-delete; required nullable                                                                                                                                                                |
-| `autoArchivedChangeRequestUrl` | `string \| null`                                | Change request whose merged state triggered auto-archive. Restore replaces it with the current merged change request, when present, so repeated snapshots cannot archive the workspace again. |
-| `labels`                       | `string[]?`                                     | Normalized display names assigned from this host's shared label catalog. Missing means unlabelled.                                                                                            |
-| `pinnedAt`                     | `string \| null` (ISO 8601)                     | Pinned-to-top-of-sidebar timestamp; null means "not pinned"                                                                                                                                   |
+| Field                          | Type                                                         | Description                                                                                                                                                                                   |
+| ------------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `workspaceId`                  | `string`                                                     | Opaque stable identifier (`wks_<hex>`), generated independently of the directory. MUST NOT be treated as a path; compare by exact equality. Use the `cwd` field for directory access.         |
+| `projectId`                    | `string`                                                     | FK to Project.projectId; the workspace's stable project membership                                                                                                                            |
+| `cwd`                          | `string`                                                     | Exact execution directory selected for agents, files, scripts, and setup                                                                                                                      |
+| `kind`                         | `"local_checkout" \| "worktree" \| "directory"`              | Mutable checkout classification                                                                                                                                                               |
+| `displayName`                  | `string`                                                     | The human name (the generated/derived title). Decoupled from `branch` by construction.                                                                                                        |
+| `title`                        | `string \| null`                                             | User-set name override layered over `displayName`. Null means "use `displayName`".                                                                                                            |
+| `branch`                       | `string \| null`                                             | The current Git branch for git-backed workspaces. Separate from `displayName`/`title`; a background branch refresh never rewrites the name.                                                   |
+| `worktreeRoot`                 | `string \| null`                                             | Backing checkout/worktree root. May differ from `cwd` for exact subprojects and remains persisted after the worktree is deleted so restore can reproduce the placement.                       |
+| `baseBranch`                   | `string \| null`                                             | Normalized branch the Paseo worktree was created from; null for directories, local checkouts, and checkout-branch worktrees                                                                   |
+| `isPaseoOwnedWorktree`         | `boolean`                                                    | Whether Paseo owns and may remove/recreate the backing `worktreeRoot`                                                                                                                         |
+| `mainRepoRoot`                 | `string \| null`                                             | Main repository root for worktree checkouts, independent of both exact `cwd` and backing `worktreeRoot`                                                                                       |
+| `createdAt`                    | `string` (ISO 8601)                                          |                                                                                                                                                                                               |
+| `updatedAt`                    | `string` (ISO 8601)                                          |                                                                                                                                                                                               |
+| `archivedAt`                   | `string \| null` (ISO 8601)                                  | Soft-delete; required nullable                                                                                                                                                                |
+| `autoArchivedChangeRequestUrl` | `string \| null`                                             | Change request whose merged state triggered auto-archive. Restore replaces it with the current merged change request, when present, so repeated snapshots cannot archive the workspace again. |
+| `labels`                       | `string[]?`                                                  | Normalized display names assigned from this host's shared label catalog. Missing means unlabelled.                                                                                            |
+| `pinnedAt`                     | `string \| null` (ISO 8601)                                  | Pinned-to-top-of-sidebar timestamp; null means "not pinned"                                                                                                                                   |
+| `untrustedSource`              | `{ kind: "change_request", forge, number, headRepository }?` | Provenance captured when a cross-repository change request creates the workspace. Missing means repository automation is allowed; explicit setup removes the field.                           |

 > **Opaque-ID invariant:** `workspaceId` is opaque identity, never a filesystem path. Filesystem and git operations take `cwd`/`workspaceDirectory` only — never the id. A compatibility-only first-materialization bootstrap still groups pre-registry agent records by path and Git remote so existing installs retain their legacy records. That grouping never runs against a live registry, and its keys are not runtime project or workspace identity.

@@ -534,8 +574,8 @@ Right-sidebar client state splits on whether it is determined by the directory o

 The durable client replica uses IndexedDB on browser/Electron and expo-sqlite on native. Rows use the
 compound key `(serverId, kind, id)`; kinds are `agent`, `workspace`, `project`, `timeline`, and
-`checkpoint`. Directory entities have individual rows. Timeline and checkpoint use the singleton id
-and have at most one row per host.
+`checkpoint`. Directory entities have individual rows, timelines use the agent id, and the checkpoint
+uses the singleton id.

 The store is a typed persistence boundary. It returns values to directory and timeline owners and
 accepts their explicit commits; it never reads or writes UI state. Reads are scoped to the requested
@@ -120,6 +120,8 @@ Workspace and chat surfaces use the full width — these are working surfaces, n

 Sections sit apart. `<SettingsSection>` owns its own bottom margin; the next thing is wrapped in another `<SettingsSection>`. The agent-list `sectionHeading` carries the same `marginTop`/`marginBottom` rhythm (`packages/app/src/components/agent-list.tsx:511-517`). Adding `marginBottom` to a section is wrong.

+A section or group explains itself through the `info` prop on `<SettingsSection>` or `<SettingsGroup>` — an info icon beside the header that opens a tooltip (`packages/app/src/components/settings/headings/settings-info-tip.tsx`). A muted paragraph between the header and the card is wrong: it sits in the section's own gap, so it reads as a second heading rather than as prose belonging to the header. Explanatory copy that describes one row belongs to that row, as `settingsStyles.rowHint` inside the card.
+
 Cards inside a section sit closer than sections. Rows inside a card touch — only the divider separates them. The rhythm is page → spacious; section → spacious; card → tight.

 Rows have generous vertical padding: roughly 16px of content plus 16px of vertical padding for settings rows, 8–12px for sidebar list items where many rows must fit. Compressing rows below the established density to fit more on the screen is wrong. Too many rows means more cards or more sections, not smaller rows.
@@ -248,6 +250,7 @@ New status pills use `<StatusBadge>`. Identity, shortcut, and interactive link b
 - `fontWeight.medium` on row titles, body text, button labels, badge text, or `<SidebarCallout>` titles. Medium is reserved for the structural-label tier described in §3 — section labels, modal/sheet titles, dense metadata emphasis, and tight action labels. Anything else is `normal`. `<ScreenTitle>` is responsive `400/300` and is never overridden.
 - `<Pressable>` wrapping `<Text>` to make a button. `<Button>` exists.
 - Bare `<Text>` for a section header inside settings. `<SettingsSection>` exists.
+- A muted paragraph between a section header and its card. Section-level explanation is the header's `info` tooltip (§7).
 - A "Settings" CTA on a detail page. Detail pages are settings; settings is reached from the sidebar, the host entry, or a row's kebab menu.
 - The word "checkout" in UI strings or identifiers. The term is "workspace".
 - New color tokens or hardcoded hex outside the palette. The identity color table is the documented exception (§13), not a license.
@@ -50,6 +50,7 @@ than downloading a published desktop release.
 - **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:
@@ -556,13 +557,16 @@ npm run cli -- daemon status         # Check daemon status
 npm run cli -- clone owner/repo --dir ~/workspace # Clone GitHub repo and register project
 ```

-Use `--host` to point the CLI at a different daemon:
+Use the global `--host` option to point the CLI at a different daemon:

 ```bash
-npm run cli -- ls -a --host localhost:7777
-npm run cli -- ls -a --host ssh://user@host
+npm run cli -- --host localhost:7777 ls -a
+npm run cli -- --host ssh://user@host ls -a
 ```

+Set `PASEO_HOST` to use the same target across invocations. An explicit
+`--host` overrides the environment variable.
+
 In an SSH URI, the URL port is the SSH server port. The remote daemon defaults to `127.0.0.1:6767`; use `?daemonPort=7777` to override it. The transport runs non-interactively through the local OpenSSH client and never installs, starts, or configures the remote daemon. User-facing setup and troubleshooting live in [public-docs/connectivity.md](../public-docs/connectivity.md#ssh).

 Desktop integrations can focus an existing agent without creating one or
@@ -39,9 +39,10 @@ that pane from the workspace split tree and docks it separately. Persisted ident
 literal `"explorer"` pane id and `explorerPaneIdByWorkspace` key for compatibility.

 The tab rail has no inline add or close controls. Its context menu opens a New Tab launcher and
-toggles the singleton Files and Changes views. Individual tab menus close instances or move
-compatible tabs to main. Explorer tabs can be reordered, but the dock cannot be split. Selecting
-an Explorer tab does not change workspace focus.
+toggles Files, Changes, and Explorer-compatible workspace-scoped plugin panels from the shared
+launch catalog. Individual tab menus close instances or move compatible tabs to main. Explorer tabs
+can be reordered, but the dock cannot be split. Selecting an Explorer tab does not change workspace
+focus.

 Cmd+E shows or hides Explorer without changing its selected view. Compact layouts use the combined
 full-screen Explorer overlay for Changes, Files, and pull requests, and close it after a file opens.
@@ -64,7 +64,10 @@ root host route and pass the nested workspace screen when a host route is
 already mounted, or Expo Router can append extra hidden workspace deck entries.
 The workspace navigation helper inspects the mounted navigation state to make
 that decision; if no host route is mounted yet, it falls back to ordinary route
-navigation.
+navigation. Both paths wait for the root navigation container to be ready. The
+workspace navigation owner keeps the latest pending intent across ref
+re-registration and applies it on the container's `ready` event; routes must not
+add their own readiness retries.

 Those hidden entries are not harmless: composer floating panels can measure
 against the wrong deck and disappear offscreen. Follow the
@@ -77,6 +80,19 @@ only use local param fallback during cold mount (`/` or empty pathname), or a
 hidden workspace can overwrite the remembered workspace before Settings or
 History returns.

+Plugin settings use the distinct `settings/hosts/[serverId]/plugins/[pluginId]/[screenId]` leaf;
+Back returns to that host's Plugins page.
+
+Settings detail routes are separate siblings on purpose. Keep
+`settings/[section]`, the host routes, the projects index, and project detail as
+distinct route names. `router.dismissTo()` ultimately matches stack entries by
+route name. A single catch-all Settings route would make project detail and the
+projects index the same route; Back would update params in place and leave a
+phantom detail entry underneath. The host routes also stay outside the
+store-ready protected group so a cold host deep link can survive daemon startup.
+Do not collapse this topology with a catch-all, `getId`, or
+`dangerouslySingular` workaround.
+
 ## Agent Targets

 Notifications and agent URLs enter the router with different authoritative
@@ -131,6 +147,14 @@ Do not read the active theme with `useUnistyles()` in a layout to build
 a small `withUnistyles` boundary without subscribing the route tree itself to
 every Unistyles runtime update.

+Navigators keep their identity across appearance changes. `ThemedStack` remounts
+each screen's content below the native stack when appearance tokens change; a
+keyed wrapper above a stack remounts the stack itself, and Android crashes when
+that happens while a FragmentManager transaction is running, which settings
+hydration at startup makes likely. A screen that mounts a nested navigator (the
+root stack's `h/[serverId]`) is passed in `nestedNavigatorScreens` so the nested
+stack owns its own screens. See [unistyles.md](unistyles.md).
+
 ## Regression Shape

 Pure helper tests are useful but not enough. The failure mode here is native
@@ -134,19 +134,39 @@ The fix for transforms is Gotcha 3. The fix for context is Gotcha 7.

 ## Gotcha 3 — Keyboard layout and portal anchors

-Move the chat surface with worklet-driven bottom padding from
-`KeyboardShiftProvider`. Padding keeps the stream, composer, visual position,
-and native hit testing in the same layout. Do not translate the stream and
-composer independently.
+`KeyboardTranslateView` owns visual keyboard motion. Android uses the
+controller's Reanimated signal. iOS uses its native-driver `Animated.event`
+signal because the stock iOS Reanimated value changes at move start, while
+writing a replacement Reanimated value every frame interrupts UIKit's hide
+animation. Keep this platform choice inside `KeyboardTranslateView`.

-Do not use the controller's raw keyboard progress for the padding. It can retain
-a nonzero value after the keyboard closes. The shared provider normalizes that
-state and reconciles native animation-end events.
+`KeyboardDock` always keeps the chat surface at full height and wraps it in
+`KeyboardTranslateView`. The panel root clips it at the header edge, so rows
+slide under the header on open and out from under it on close. Do not swap the
+dock to keyboard padding at rest. Changing its height creates either a blank
+band or a paused transition when the inverted list updates its viewport.

-`measureInWindow` already includes the dock's current padding layout. When a
-portal opens, snapshot the current shift and apply only the subsequent shift
-delta to its animated `bottom`. Adding the full shift moves the portal twice and
-can place it over the composer controls.
+Do not animate a layout prop through the keyboard transition. On Android
+Fabric, each animated layout update clones the shadow tree and runs Yoga over
+the dock subtree. This measured about 10 ms per frame on the emulator and the
+mounted layouts arrived in bursts every 2–4 frames. A transform does not dirty
+layout. Preserve the translated dock's history scroll range with a far-end
+content inset on the inverted stream list. Update that inset only when keyboard
+motion settles; never drive it per frame.
+
+Move the stream and composer together through `KeyboardDock`. Do not translate
+them independently.
+
+`KeyboardShiftProvider` owns the normalized shift used for settled insets and
+portal geometry, plus the `isMoving` worklet value. It reconciles native
+animation-end events because the controller can retain a nonzero value after
+the keyboard closes.
+
+Measure portal anchors while the dock is at rest. If a popover opens during
+motion, re-measure when `isMoving` settles. `measureInWindow` includes the
+dock's current layout and transform. Snapshot the shift at measurement time and
+apply only the subsequent shift delta to the animated `bottom`. Adding the full
+shift moves the portal twice and can place it over the composer controls.

 The provider also reconciles iOS from the controller's native `onEnd` event.
 The controller's stock iOS shared values update at move start and during an
@@ -155,10 +175,6 @@ leave the last height/progress pair stuck in either the open or closed state.
 Keep that terminal reconciliation on the UI thread; a later focus or blur must
 not be required to repair the offset.

-Re-measure on `Keyboard.addListener('keyboardDidShow'|'keyboardDidHide')` only
-to refresh the snapshot if the keyboard was mid-transition when the popover
-opened.
-
 ## Gotcha 4 — Host-relative positioning before platform offsets

 The generic anchored-overlay rule is:
@@ -78,6 +78,14 @@ complete`), keyed off the opened snapshot's serverId. Waiting for data is a
  timezone) once — never in a preview line AND a helper line.
 - `useUnistyles` is banned (see docs/unistyles.md); lint enforces.

+## Settings rows
+
+Use the named components from `@/components/settings` for settings cards and controls.
+`SettingsCard` owns row separators; `SettingsRow` accepts custom content. Heading-only screens
+can import `SettingsGroup` and `SettingsSection` directly from their modules in
+`@/components/settings/headings/`.
+The plugin UI entry exposes the same components; keep them independent of storage and routing.
+
 ## Data gating

 Aggregate hooks return a discriminated load state:
@@ -19,6 +19,7 @@ Authoritative terminology. UI label wins. Don't invent synonyms; use what's here
 - **MR** — GitLab merge request. UI label for GitLab change requests only; do not use MR for GitHub/Gitea/Forgejo.
 - **Worktree** — Paseo-managed git worktree (`~/.paseo/worktrees/{name}`); also a `workspaceKind` value. User-facing creation treats it as the `worktree` workspace isolation choice. Code and `paseo.json` retain worktree terminology for git lifecycle implementation. Forbidden: "Checkout" as a product synonym.
 - **Repository / Remote** — Internal Git observations. They may produce mutable kind, branch, and project-grouping metadata but never the host-local project ID, root, display name, or workspace membership. No UI label.
+- **Sidebar items** — The top-level rows at the head of the app sidebar: New workspace, History, Search, Schedules, and every plugin sidebar contribution. Order and visibility are one per-device preference (`AppSettings.sidebarNavItems`); all of them may be off. UI: the "Sidebar" section on the Appearance settings page. Code: `packages/app/src/sidebar-nav/model.ts` resolves the list, and both the sidebar (`components/sidebar/sidebar-nav-rows.tsx`) and the settings section (`screens/settings/appearance/sidebar-nav-section.tsx`) read it through `useSidebarNavItems`. Never hardcode one of these rows or add a second place that decides which ones show. Don't confuse with **Explorer sidebar**.
 - **Explorer sidebar** — The dedicated navigation dock containing the Files and Changes trees. UI: "Explorer sidebar". Code: `packages/app/src/workspace-tabs/explorer-sidebar.ts`; persisted pane identifiers retain the `explorer` spelling. See [explorer-sidebar.md](explorer-sidebar.md).
 - **Side pane** — An ordinary right-side workspace pane used for content opened beside the user's work. It closes and participates in workspace splits like every other main-host pane. See [explorer-sidebar.md](explorer-sidebar.md#side-pane). Forbidden: "Side panel".
 - **Directory-backed surface** — A right-sidebar surface whose content is determined by the workspace's `cwd`, so two workspaces on the same directory see identical content: git diff/status, forge change-request info, file preview/explorer contents. Keyed by `(serverId, cwd)`, never `workspaceId`. See [architecture.md](architecture.md#right-sidebar-boundary-directory-backed-vs-workspace-owned).
@@ -4,7 +4,7 @@ Paseo Hub is an explicit opt-in connection from one Paseo daemon to one Hub. Run
 not register it with a Hub. The relationship begins only when a user runs
 `paseo hub connect [url]` from the daemon machine with an explicit API key or matching stored CLI login.

-The human CLI login and daemon relationship are separate identities. `paseo hub login [url]` stores a durable organization-scoped CLI credential keyed by normalized Hub origin under `PASEO_HOME`. Interactive login optionally connects the local daemon, then points to the Hub UI for trigger configuration; it does not scaffold or deploy configuration. `paseo hub init` remains the explicit triggers-as-code scaffold. `paseo hub export [directory]` writes the active organization's current triggers as one self-contained YAML file per trigger, using the active login unless another Hub or API key is selected. Origin resolution uses explicit command input, `PASEO_HUB_URL`, active login, then `https://hub.paseo.sh`. Connect uses exact-origin authority to request a one-time enrollment token, then passes only that token to the daemon. The daemon generates and persists its own relationship credential.
+The human CLI login and daemon relationship are separate identities. `paseo hub login [url]` stores a durable organization-scoped CLI credential keyed by normalized Hub origin under `PASEO_HOME`. Interactive login optionally connects the local daemon, then points to the Hub UI for trigger configuration; it does not scaffold or deploy configuration. `paseo hub init` remains the explicit triggers-as-code scaffold: it writes one self-contained organization trigger under `.paseo/triggers/`, validates it through the trigger API, and optionally installs it. `paseo hub deploy` validates and installs every trigger in that directory; passing `--project` keeps deploying the legacy project bundle instead. `paseo hub export [directory]` writes the active organization's current triggers in the same layout, using the active login unless another Hub or API key is selected. Origin resolution uses explicit command input, `PASEO_HUB_URL`, active login, then `https://hub.paseo.sh`. Connect uses exact-origin authority to request a one-time enrollment token, then passes only that token to the daemon. The daemon generates and persists its own relationship credential.

 ## Connection and authority

@@ -25,69 +25,48 @@ during interactive login or later with `paseo hub permissions grant hub.execute`
 created before this split migrate their legacy execution scope to `hub.execute`. Hub sessions cannot
 manage their own relationship or permissions.

-## Session grants and execution ownership
+## Session grants and agent operations

-Trusted clients and the Hub use the same `Session` implementation. The connection boundary supplies
-semantic permissions: trusted clients receive the owner permission set, while an enrolled Hub
-connection receives its persisted permissions. Legacy relationship files carrying
-`hub.execution.*` migrate once to `hub.execute` at the persistence boundary. A denied request returns
-the ordinary `rpc_error` shape. See [permissions.md](permissions.md).
+Hub uses the same authenticated, resumable Session protocol as other clients. Its persisted
+`hub.execute` permission authorizes ordinary agent creation, messaging, cancellation, archival,
+agent/workspace observation, timeline subscriptions, and workspace recovery. This authority is
+daemon-wide; it is not limited to agents created by that Hub. Daemon configuration, terminals,
+browser control, and permission management still require their own permissions. See
+[permissions.md](permissions.md).

-The Hub connection still has a narrow lifecycle boundary: it has no trusted-client hello/resume,
-browser, binary, retained-session, or broadcast state. Its outbound execution events include only
-agents owned by that daemon identity, so unrelated local agents remain outside the Hub surface.
+Clients using this contract check `server_info.features.hubAgentRpc` and
+`server_info.features.agentRequestReceipts` once. An older host must be upgraded; do not silently
+fall back to creating a fresh agent when continuation was requested.

-Each Hub create carries an execution ID. The daemon stores that ID with the agent's relationship
-owner before acknowledging creation. Duplicate or replayed creates for the same daemon and
-execution resolve to the same durable agent. After a lost response, reconnect, or daemon restart,
-the Hub retries `hub.execution.agent.create.request` with the same execution ID. The idempotent
-response returns the existing agent and its current state; there is no separate reconciliation RPC.
-Transient stream frames are not durably replayed.
+Hub owns conversation keys, trigger policy, execution records, and the mapping to workspace/agent
+IDs. None of these routing concepts are part of the generic daemon RPCs. Creation accepts ordinary
+provider configuration, exact MCP tool policy, environment, and workspace/worktree selection.
+Private session configuration is persisted for recovery and is not exposed in agent snapshots.
+Provider controls remain provider-native; see [providers.md](providers.md).

-Daemon restart preserves the Hub relationship and owned execution identity, but interrupts any
-active turn. The daemon persists that agent as `closed`; an idempotent create retry returns the same
-daemon, execution, and agent identity with that terminal state. Paseo never stores or automatically
-replays the original prompt. A duplicate create returns the existing agent without starting another
-turn.
+`create_agent_request.idempotencyKey` identifies one creation operation. With a key, omit
+`initialPrompt`, persist the returned agent/workspace identity, then deliver the prompt using
+`send_agent_message_request` with a stable `messageId`. Request IDs correlate individual attempts;
+creation keys and message IDs identify the operation across attempts. A creation key is daemon-wide;
+a message ID is scoped to its agent. Reusing either with different arguments is a conflict.

-Every Hub execution creates a fresh Paseo workspace. The workspace owns the execution's agents and
-terminals. Local checkout and worktree targets select only the workspace backing and isolation; the
-Hub cannot select or reuse an existing workspace. Hub creates use the same agent creation path as
-trusted clients. They may select any worktree target shape and carry optional MCP server configuration and provider-native
-`providerOptions` for the agent session. The daemon keeps that configuration in its private agent
-record so provider sessions can recover after a restart; neither ordinary client snapshots and
-updates nor Hub projections expose session configuration. See [providers.md](providers.md) for the
-supported provider keys.
+The daemon journals the assigned agent ID before creation. Concurrent retries share one operation,
+and a retry after a lost acknowledgement or restart returns the durable agent without creating a
+workspace or starting a turn. Deleting that agent does not make its old creation key reusable.
+Confirmed message delivery is also journaled, so retrying its message ID does not submit it again.
+An unfinished delivery after restart reports `agent_request_outcome_unknown`: a provider can have
+accepted a prompt before the daemon recorded success, so automatic resubmission could duplicate
+work. Inspect the agent before choosing a new message ID. Receipts contain identity and request
+hashes, never prompts, environment values, or credentials.

-Hub tool preapproval is a private, structured list of `{ kind: "mcp", server, tool }` references.
-Every reference must name an MCP server injected by the same create request. The daemon translates
-only those identities into the selected provider's native approval configuration. The protocol
-cannot name or preapprove native tools such as Bash, Edit, or Write. Explicit local or managed ask
-and deny policy takes precedence. Providers without exact MCP preapproval support reject unattended
-Hub creation instead of broadening access or waiting for an invisible prompt.
-When a create request includes a tool policy, a successful response includes
-`toolPolicyApplied: true`; absence of that acknowledgement is not success for unattended execution.
+Before messaging an archived workspace, call `workspace.recovery.inspect.request`, then
+`workspace.recovery.restore.request` and await success. The native message handler unarchives the
+agent and loads its persisted provider session. `activeTurnBehavior: "steer"` uses the provider's
+native steering behavior, including Paseo's existing behavior when that provider cannot steer.
+Execution completion and arrival-specific output authority remain Hub responsibilities.

-A Hub workflow may use read-only provider settings for classifier steps. This is defense in depth,
-not a security boundary: classifier labels and prompt intent do not authorize tools. Exact MCP grants
-and the provider's local or managed policy remain the authorization controls.
-
-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 resolves the execution agent's
-required workspaceId and sends it through the shared workspace archive service. The service archives
-that workspace's agents and terminals, then removes Paseo-owned backing directories only after their
-final active workspace reference disappears. Local checkouts remain on disk; sibling workspaces
-sharing a backing directory remain active.
+The older `hub.execution.*` RPCs remain accepted for existing clients. Their execution ownership
+and create deduplication behavior are unchanged; new continuation work uses the ordinary RPCs.

 ## Disconnect and revocation

@@ -30,8 +30,12 @@ The UI worklet owns transient motion:
 - the active gesture's starting revision
 - the last settled target

-React also owns presentation lifecycle: whether an overlay is mounted/displayed and whether it may
-receive pointer events. Worklets never own `display` or `pointerEvents`.
+React publishes the active panel only when the canonical target and the UI-thread position agree at
+the final anchor. Retained content never observes gesture previews, progress, or an unsettled target.
+The gesture hosts stay mounted; worklets reveal their retained overlays through native styles while
+React owns pointer events and accessibility. Native panel hosts and their dependent draggable lists
+also retain identity across appearance hydration and settings changes. Do not wrap those hosts in
+appearance keys; see [Unistyles appearance boundaries](unistyles.md#runtime-theme-patching-for-user-preferences).

 ## Why one position

@@ -55,8 +59,10 @@ while that revision still owns the gesture.

 When a React command arrives during a drag, its newer revision clears gesture ownership and starts
 motion toward the new target. The older gesture's remaining updates and finish callback are ignored.
-Canceled gestures return to the latest canonical target. Animation completion is accepted only when
-its target and revision still match the canonical command.
+Canceled gestures return to the latest canonical target. A successful gesture starts its finishing
+motion immediately; the matching React command adopts that motion instead of restarting it. Position
+settlement and command acceptance may arrive in either order. Activity changes after both agree on
+the same target.

 Manual gesture arbitration has two phases:

@@ -85,8 +91,14 @@ definition, no longer eligible to begin.
 - Animated panel nodes use React Native static styles plus inline theme values. Do not attach
  Unistyles-generated styles to those nodes; Unistyles and Reanimated patching the same Fabric node
  has caused native crashes.
- The plain React wrapper owns `display: none` after settlement. This prevents a stale Fabric animated
-  prop commit from resurrecting a closed overlay.
+- `FORCE_REACT_RENDER_FOR_SETTLED_ANIMATIONS` stays off in `packages/app/package.json`. It is a
+  compile-time flag; changing it needs a native rebuild. With it on, Reanimated 4.3 hands settled
+  animated props back to React through a collector that forgets entries older than two seconds. A JS
+  stall across a panel settle loses the final position, and the next React commit reverts the overlay
+  to its last synced props: a backdrop over the workspace while the store says closed. Upstream fixed
+  the collector in 4.4.3, which needs React Native 0.83.
+- Gesture start and progress must not update React state. The retained overlay is already mounted and
+  offscreen; only the shared position and its derived native styles move during a drag.
 - Hidden tabs and workspaces use `RetainedPanel`. It owns a non-collapsible native root, visibility,
  pointer events, and the active signal consumed by `useRetainedPanelActive`.
 - Panels whose gesture wrapper already owns visibility use `RetainedPanelActivity` to provide the
@@ -98,8 +110,9 @@ definition, no longer eligible to begin.
 - Retention order and render order are separate concerns. LRU metadata may change on every switch;
  keyed retained roots must keep a stable sibling order. Moving large retained roots triggered Fabric
  Differ failures (`addViewAt` / `removeViewAt` view reuse) on Android.
- The newly active panel must be included in the same render that changes selection. Adding it from an
-  effect creates a committed frame where every retained panel is hidden, which is a real blank screen.
+- `useIsMobilePanelActive` follows the settled target, not the requested target. Position at the
+  canonical target's anchor is the settlement signal; animation duration and completion callbacks
+  do not own activity. Cancellation publishes nothing.
 - Do not suspend retained native subtrees with `Suspense`/`react-freeze`. Suspension changes native
  ownership and can detach descendants. Keep the tree mounted, stabilize its subscriptions/selectors,
  and use the retained-panel active signal to stop timers, polling, and other genuine background work.
@@ -107,5 +120,5 @@ definition, no longer eligible to begin.
 ## Tests

 `packages/app/src/mobile-panels/model.test.ts` exercises command, drag, cancellation, interruption,
-rapid-command, stale-completion, and width-projection sequences through the transition model. Add a
-sequence there whenever ownership or ordering changes.
+rapid-command, position-settlement, and width-projection sequences through the transition model. Add
+a sequence there whenever ownership or ordering changes.
@@ -35,6 +35,18 @@ PASEO_MOBILE_E2E_METRO_PORT=62093 npm run test:e2e:mobile

 [native-terminal-basic.ios.ad](../packages/app/e2e/mobile/agent-device/native-terminal-basic.ios.ad) and [native-terminal-basic.android.ad](../packages/app/e2e/mobile/agent-device/native-terminal-basic.android.ad) are the smallest examples. Each opens a fresh terminal, types a command at zero delay, submits it, and asserts its distinct output. The app must be connected to a daemon with an active workspace.

+For Android keyboard continuity, run the current checkout in the app, open an idle terminal
+with an empty prompt, hide its keyboard, and run:
+
+```bash
+ANDROID_SERIAL=emulator-5554 node packages/app/e2e/mobile/terminal-keyboard/android.mjs
+```
+
+Use a real docked software keyboard. The harness taps Ctrl, Esc, and Enter and checks Android's
+focused input identity and IME hide/show events. It saves screenshots and logs under
+`.dev/agent-device-artifacts/terminal-keyboard-android`. Set `PASEO_TERMINAL_KEYBOARD_APP_ID=sh.paseo`
+to test an installed production build. It never submits a chat message.
+
 When replay diverges, read its ranked selector suggestions. Edit the script deliberately and rerun it from the beginning. `--update` is retained for compatibility but no longer rewrites scripts.

 ## Maestro compatibility
@@ -27,7 +27,7 @@ A pairing invitation is neither. It is an expiring, single-use exchange that cre
 | `workspace.write`   | Prompts, agent control, files, terminals, git operations, and scripts      |
 | `workspace.manage`  | Create, rename, archive, and remove projects and workspaces                |
 | `automation.manage` | Schedules, heartbeats, and loops                                           |
-| `hub.execute`       | The Hub-owned execution lifecycle                                          |
+| `hub.execute`       | Agent lifecycle, agent/workspace observation, and workspace recovery       |

 Agents and terminals use workspace authority. Both can execute code and mutate the workspace, so separate write permissions would claim an isolation boundary the daemon cannot enforce.

@@ -1,9 +1,10 @@
 # Plugins

 Local plugins contribute daemon RPCs, native app surfaces, workspace panels, Command Center items,
-composer pills, app themes, and composer attachment sources from one `index.ts`. Paseo executes the server contribution in a
-subprocess and evaluates the client contribution in the app runtime. Plugin code is trusted code;
-Paseo does not sandbox it.
+client slash commands, timeline items, header buttons, composer pills, app themes, composer attachment sources, and settings screens.
+Paseo executes `index.server.ts` in a subprocess and `index.client.tsx` in every connected app.
+
+> **Trust every plugin you add.** `paseo plugin add` and `paseo plugin install` mean “I trust this codebase.” Plugins are unsandboxed: server code and Git preparation commands run with the daemon user's access on the daemon host, and client contributions run inside Paseo. The repository's dependencies and future updates are part of that trust decision. With `--host`, preparation runs on that remote daemon host.

 ## Install a directory source

@@ -40,29 +41,36 @@ runtime-safe: run `paseo reload` after editing `config.json`. Enabling starts ev
 enabled plugin; disabling tears them all down without restarting the daemon. Plugin source entries
 remain lifecycle-owned and do not reload from manual config edits.

-The directory contains an identity-only manifest, one entry point, and local typechecking support:
+The directory contains a manifest declaring identity and Paseo requirements, one optional entry per runtime, runtime-owned
+directories, and local typechecking support. At least one entry is required.

 ```text
 my-plugin/
  paseo-plugin.json
-  index.ts
-  main.client.tsx
-  paseo-plugin.d.ts
  package.json
  tsconfig.json
+  index.client.tsx
+  index.server.ts
+  client/greeting.tsx
+  server/greeting.ts
+  shared/greeting.ts
 ```

-Paseo compiles TypeScript and TSX when loading the plugin, so these packages are development dependencies only.
-The generated declaration file supplies `@getpaseo/plugin` and `@getpaseo/plugin/server` types until the
-SDK is distributed as a public package. Regenerate new plugins with the matching Paseo CLI when the
-SDK contract changes.
+The generated `package.json` installs `@getpaseo/plugin` and the other host modules as development
+dependencies for local typechecking and tests. Paseo compiles TypeScript and TSX and supplies the
+runtime modules, so consumers do not install these packages when adding the plugin.

 ```json
 {
-  "id": "my-plugin"
+  "id": "my-plugin",
+  "requirements": { "paseo": ">=0.8.0" }
 }
 ```

+Declare the supported Paseo range and keep it current when adopting newer APIs. See the
+[requirements contract](../public-docs/plugins/v0.8/reference.md#requirements), including legacy
+manifests and prerelease matching.
+
 The config key is the runtime plugin ID. The manifest ID is the default selected during install;
 `--id` overrides it. Existing configuration is not renamed when the manifest changes, and the
 runtime does not compare the two IDs. The same directory can be installed under several config
@@ -84,74 +92,143 @@ directory always wins over shorthand resolution.

 ```bash
 paseo plugin add owner/repository
+paseo plugin add https://gitlab.com/group/repository.git
 paseo plugin add https://git.example.com/owner/repository.git
-paseo plugin add owner/monorepo --path plugins/review
+paseo plugin add owner/monorepo:plugins/review
 paseo plugin add owner/repository --ref main
-paseo plugin status
+paseo plugin ls
 paseo plugin update review
 paseo plugin update --all
 ```

-Omitting `--ref` tracks the remote's default branch. A branch passed with `--ref` also tracks;
-tags and commits stay pinned. `status` fetches tracked refs and reports the installed and available
-commits. `update` checks out a new version, validates its manifest, compiles both bundles, and starts
-it before changing the configured path. A compilation or startup failure restores the running
-version. Removing a Git source deletes Paseo's managed checkout.
+Append `:relative/path` to the source when the plugin lives below the repository root.

-Git installation does not run a package manager or install script. A distributable source plugin
-uses Paseo's host-provided modules or commits any other bundled source it needs. Native React Native
-dependencies work only when the Paseo app already ships the native module.
+Omitting `--ref` tracks the remote's default branch. A branch passed with `--ref` also tracks;
+tags and commits stay pinned. `ls` reports the installed commit without contacting the remote.
+Removing a Git source deletes Paseo's managed checkout.
+
+### Declare Git preparation
+
+Most plugins should omit `build`. Use it only when the staged checkout must install a dependency
+that Paseo does not provide, generate source or assets, or perform another required preparation
+step:
+
+```json
+{
+  "id": "review",
+  "requirements": { "paseo": ">=0.8.0" },
+  "build": [
+    ["npm", "ci"],
+    ["npm", "run", "build"]
+  ]
+}
+```
+
+`build` is an optional list of argv arrays. Each array must contain at least one non-empty string;
+shell command strings are rejected. Paseo starts the executable directly, without a shell, from the
+plugin directory in the staged checkout. It never detects lockfiles or chooses a package manager.
+
+On install and every update, Paseo resolves the exact Git revision and manifest, runs the declared
+commands, then validates, compiles, and activates the candidate. It logs each argv command and its
+output in the daemon log. If a command fails, the error includes its output, Paseo discards the
+candidate, and the existing installed and running version stays untouched. On a remote daemon, all
+of this happens on the remote daemon host.

 Server contributions can write to stdout and stderr with normal Node logging. Paseo adds `[paseo]`
 entries for loading, ready, stopping, and stopped transitions. Compilation and load failures are
 recorded as stderr entries before a subprocess exists. Inspect the recent in-memory
-tail from the host plugin settings or with `paseo plugin logs <id>`. Reload, disable, and process
+tail from the host plugin settings or with `paseo plugin logs <id>`. Git preparation commands are
+recorded in `$PASEO_HOME/daemon.log` before a plugin exists, rather than the plugin log tail. Reload, disable, and process
 failure retain the tail; removing the plugin clears it. Daemon restarts do not retain the tail, but
 structured copies remain in `$PASEO_HOME/daemon.log`. Plugin output can contain secrets, so do not
 log credentials or tokens.

 ## Contribute behavior and UI

-Default export one contribution function from `index.ts`. Keep it to contribution wiring. Runtime
-code lives behind filename boundaries:
+Default export one contribution function from each runtime entry. Keep the entries to registration
+wiring. Runtime code lives behind directory boundaries:

-| Suffix         | Owns                                                                 |
-| -------------- | -------------------------------------------------------------------- |
-| `*.client.tsx` | React, React Native, hooks, styles, surfaces, panels, and callbacks. |
-| `*.server.ts`  | Node APIs, filesystem and process access, credentials, and handlers. |
-| `*.shared.ts`  | Zod RPC contracts and plain values used by both runtimes.            |
+| Path                             | Owns                                                                 |
+| -------------------------------- | -------------------------------------------------------------------- |
+| `index.client.tsx` and `client/` | React, React Native, hooks, styles, surfaces, panels, and callbacks. |
+| `index.server.ts` and `server/`  | Node APIs, filesystem and process access, credentials, and handlers. |
+| `shared/`                        | Zod RPC contracts and plain values used by both runtimes.            |

-Shared files import contracts from `@getpaseo/plugin/server`. Client files import Paseo UI from
-`@getpaseo/plugin/react-native`. Its `Icon` resolves a Lucide name using the client's installed icon
+Do not put any other code modules in the plugin root.
+
+Shared files import contract helpers and types from `@getpaseo/plugin`. Server handler files import
+`PluginHandlerContext` from `@getpaseo/plugin/server`. Client files import Paseo UI from
+`@getpaseo/plugin/client/react-native`. Its `Icon` resolves a Lucide name using the client's installed icon
 set; an unknown name renders nothing so it cannot break the plugin surface.
 Its controlled modal keeps presentation metadata on `<Modal title="…" icon={…}>` and body UI in
-`<Modal.Content>`.
+`<Modal.Content>`. Body layout, sheet-aware scrolling, and clipboard actions follow the
+[host UI contract](../public-docs/plugins/v0.8/reference.md#host-ui).
 Plugin UI runs on desktop and mobile across multiple themes: color every `Text` from
 `theme.colors.foreground` or `theme.colors.foregroundMuted`, and size layout from `layout.compact`.
-See `public-docs/plugins/reference.md`.
+See `public-docs/plugins/v0.8/reference.md`.

-| Module                          | Use it for                                               |
-| ------------------------------- | -------------------------------------------------------- |
-| `@getpaseo/plugin`              | contribution contracts and client data hooks             |
-| `@getpaseo/plugin/react-native` | Paseo React Native components and UI hooks               |
-| `@getpaseo/plugin/server`       | `defineRpc`, `defineAttachmentSource`, and handler types |
+### SDK import boundaries

-The compiler removes client registrations and imports from the server entry point, and server
-registrations and imports from the client entry point. Importing a `*.server` module from a client
-module, or a `*.client` module from a server module, fails compilation. Top-level React Native calls
-such as `StyleSheet.create` belong in `*.client.tsx`; placing them in `index.ts` executes them in the
-server bundle.
+Classify every SDK export before adding it. All client entry points and implementations live under
+`client/`; all server entry points and implementations live under `server/`. The package root is shared code: plain data types,
+Zod schemas, and functions that run in both runtimes. A type-only import is still an architectural
+dependency; shared types must not refer to React components, hooks, Node APIs, or server contexts.
+
+| Entry                                                | Owns                                                                       | May depend on          |
+| ---------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------- |
+| `@getpaseo/plugin`                                   | Shared data, schemas, RPC/settings definitions, runtime-neutral helpers    | Shared code only       |
+| `@getpaseo/plugin/server`                            | Server contribution/handler contexts and lifecycle contracts               | Shared and server code |
+| `@getpaseo/plugin/server/provider`, `/server/acp`    | Server provider contracts and adapters                                     | Shared and server code |
+| `@getpaseo/plugin/client`                            | Client contribution contexts, hooks, navigation, and UI contribution types | Shared and client code |
+| `@getpaseo/plugin/client/react-native`, `/client/ui` | Host-provided UI components                                                | Shared and client code |
+| `@getpaseo/plugin/client/host`                       | App-owned rendering integration; not a plugin-author entry                 | Shared and client code |
+
+Server code imports shared helpers from the root and server capabilities from `/server`. Client
+code imports shared helpers from the root and client capabilities from `/client`. Neither runtime
+imports the other. Re-exports follow the same rule; tree shaking does not establish a boundary.
+React, React Native, JSX runtimes, and client hooks must never be reachable from the root or any
+server entry. Node and platform-specific code must never be reachable from the shared root.
+
+The SDK boundary checks and real plugin-subprocess tests enforce these rules. Every SDK change
+must preserve them and update the public reference, migration guide, scaffold, and examples when
+an author-facing import changes. The plugin compiler enforces the same runtime entry rules for
+plugin-authored code. Keep the package export map and host-provided module maps consistent.
+
+The compiler rejects imports across runtime directories or SDK entries, React dependencies in
+server code, and Node imports in client code (including bare names such as `fs`). Shared modules
+cannot import runtime-owned modules. Forbidden imports fail compilation; never replace them with
+empty module stubs. A relative
+import to any other code file in the plugin root is also rejected; move it into `client/`, `server/`,
+or `shared/`. These are compile errors naming the importing file and boundary rule. Top-level React
+Native calls such as `StyleSheet.create` belong in `client/`.
+
+The scaffold omits `"DOM"` from `tsconfig.json` and does not use `/// <reference lib="dom" />`, so
+browser globals are not available across the plugin. Put sanctioned web-only APIs in
+`client/web.ts`, declare only the globals that module uses, gate each export with
+`Platform.OS === "web"`, and provide a native implementation or no-op. See the
+[public plugin reference](../public-docs/plugins/v0.8/reference.md#works-on-mobile) for the complete
+pattern.

 ```ts
-import type { PluginContext } from "@getpaseo/plugin";
-import { Greeting } from "./greeting.client";
-import { createGreeting } from "./greeting.server";
-import { greetRpc } from "./greeting.shared";
+// index.server.ts
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { createGreeting } from "./server/greeting";
+import { greetRpc } from "./shared/greeting";

-export default function contribute(plugin: PluginContext) {
-  plugin.handle(greetRpc, createGreeting);
-  plugin.addSurface("main", Greeting);
-  plugin.addSidebarItem({ id: "main", title: "Greeting", icon: "MessageCircle", surface: "main" });
+export default function contribute(server: PluginServerContext) {
+  server.handle(greetRpc, createGreeting);
+  return () => {};
+}
+```
+
+```tsx
+// index.client.tsx
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { Greeting } from "./client/greeting";
+
+export default function contribute(client: PluginClientContext) {
+  client.addSurface("main", Greeting);
+  client.addSidebarItem({ id: "main", title: "Greeting", icon: "MessageCircle", surface: "main" });
  return () => {};
 }
 ```
@@ -170,7 +247,7 @@ typed async function. Use the host-provided `@tanstack/react-query` for request
 Paseo gives each plugin installation its own query client.

 `usePaseo()` and the handler's `{ paseo }` context expose the same `PaseoApi`: projects,
-workspaces, agents, providers, and daemon config. They do not expose connection lifecycle. A surface borrows the
+workspaces, agents, terminals, providers, and daemon config. They do not expose connection lifecycle. A surface borrows the
 selected host's existing connection; switching the screen's host changes both `usePaseo()` and
 `useRpc()` to that host. An offline selected host fails there and never falls through to another
 installation. A server handler owns an IPC-backed daemon session for the life of its subprocess.
@@ -186,13 +263,13 @@ When the same plugin contribution exists on multiple hosts, Paseo shows it once
 adds a host picker to the screen header. The selected host supplies the bundle, RPC transport, and
 query cache. Plugin code cannot address another host.

-Workspace panels and Command Center items remain client contributions. The daemon transports their
-compiled bundle without interpreting placement or callbacks. Panel props contain workspace and agent
-IDs. Required-selector hooks read normalized client state synchronously and use shallow equality, so a
-panel does not subscribe to fields it does not render. Command callbacks materialize their snapshots
-only when invoked. Contribution discovery and panel opening never fetch active context through plugin
-RPC. Snapshot DTOs are deeply readonly and frozen at runtime so plugin code cannot mutate normalized
-app state or a memoized selection. Panels use one persisted
+Workspace panels, Command Center items, and client slash commands are client contributions. The
+daemon transports their compiled bundle without interpreting placement or callbacks. Panel props
+contain workspace and agent IDs. Required-selector hooks read normalized client state synchronously
+and use shallow equality, so a panel does not subscribe to fields it does not render. Command
+callbacks materialize their snapshots only when invoked. Contribution discovery and panel opening
+never fetch active context through plugin RPC. Snapshot DTOs are deeply readonly and frozen at
+runtime so plugin code cannot mutate normalized app state or a memoized selection. Panels use one persisted
 `plugin` workspace-tab target, so reload, disable, removal, and restoration resolve through the
 current installed-plugin catalog. A missing contribution renders unavailable inside the tab.
 Panels declare `locations: ["workspace", "explorer"]` to opt into Explorer hosting; omission means
@@ -206,66 +283,142 @@ optional client-owned agent and workspace navigation; its absence is the compati
 older clients. Other navigation remains limited to registered global surfaces and workspace panels.
 Plugins do not receive Expo Router or workspace-layout store access.

-## Contribute composer pills
+## Lifecycle hooks

-Register a headless client entrypoint, then add and remove targeted pills from that client
-lifecycle. `addClientSide` runs once per plugin installation in each connected app and never runs
-in the daemon subprocess. It can subscribe to the client API, call plugin RPCs, and own arbitrary
-client state without mounting a panel or surface.
+Server entries register lifecycle observers with `server.on()` and request transforms with
+`server.before()`. The [public reference](../public-docs/plugins/v0.8/reference.md#lifecycle-hooks)
+owns callback shapes, ordering, and failure behavior. `plugin-examples/lifecycle-logger` registers all
+eleven hooks; `plugin-examples/lifecycle-actions` demonstrates common automation callbacks.

-```tsx
-export function contributeClient(client: PluginClientContext) {
-  const pills = new Map<string, () => void>();
-  const unsubscribe = client.paseo.agents.subscribe((update) => {
-    if (update.kind !== "upsert" || !update.agent.workspaceId) return;
-    const { id: agentId, workspaceId } = update.agent;
-    pills.get(agentId)?.();
-    pills.set(
-      agentId,
-      client.addComposerPill({
-        id: "review",
-        title: "Open review",
-        workspaceId,
-        agentId,
-        Component: ReviewPill,
-        async onPress() {
-          await client.rpc(refreshReview, { agentId });
-          client.openPanel("review", { workspaceId, agentId });
-        },
-      }),
-    );
-  });
-  return () => {
-    unsubscribe();
-    for (const remove of pills.values()) remove();
-  };
+Emit from the operation owner, not a client subscription. Provider history replay must not trigger
+live hooks. Observers must not be awaited inside agent mutations: a callback can send a prompt or
+answer a permission through its own daemon session. Awaiting it there deadlocks that command.
+
+## Contribute a provider
+
+Register a provider from `index.server.ts`. The provider connection is callback-based and owns all
+of its sessions; plugin RPC is not part of the provider data path.
+
+```ts
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import type { ProviderRegistration } from "@getpaseo/plugin/server/provider";
+import { createProvider } from "./server/provider";
+
+export default function contribute(server: PluginServerContext) {
+  server.registerProvider(createProvider() satisfies ProviderRegistration);
+  return () => {};
 }
 ```

-Wire it from `index.ts` with `plugin.addClientSide(contributeClient)`. `addComposerPill` exists only
-on `PluginClientContext`; it returns an idempotent removal function. A pill appears only in the
-matching workspace and agent track bar alongside Tasks and Subagents. Paseo owns the pressable,
-shared chrome, pending state, error reporting, and placement. The component owns its icon and text;
-the callback is client code by construction. Removing the pill, reloading the plugin, disconnecting
-the host, or unloading the app tears down the contribution.
+Implement optional `ProviderRegistration.getCatalogCacheKey(options)` to share equivalent catalogue
+probes. The callback runs in the plugin process before discovery and receives the actual global or
+workspace target. Return a key covering effective configuration and execution environment, or
+`undefined` for target-specific caching. Ignore `force` when choosing identity. Existing providers
+need no change. See [catalogue ownership](providers.md#provider-snapshot-refresh-contract).
+
+`send()` resolves after acceptance. Publish operation completion, prompt disposition, turn state,
+configuration, permissions, persistence, and complete timeline snapshots through `onEvent()`.
+Route messages, structured commands, steering, and command side effects through `session.prompt`.
+Provider settings are toggle/select data that Paseo renders in the composer. Keep private options in
+the opaque `providerOptions` config object.
+
+Agent refresh closes the current provider session and opens it again with current configuration and
+persistence. Providers re-read credentials, environment, global configuration, and MCP servers on
+`session.open`; there is no provider reload input.
+
+For an ACP command, register `runAcpProvider({ id, label, command })` from
+`@getpaseo/plugin/server/acp`. Its transformer hooks cover narrow vendor differences; do not translate the
+whole provider event stream. The direct and ACP examples live in `plugin-examples/provider-direct`
+and `plugin-examples/provider-acp-transformer`.
+
+Provider-emitted plugin timeline items use the same renderer registration as transformed and
+daemon-appended plugin items. The direct example includes both sides. The renderer-only
+`plugin-examples/inline-thinking` example shows that timeline presentation remains independent of a
+provider implementation. The public [provider plugin guide](../public-docs/plugins/v0.8/providers.md)
+owns author workflow, lifecycle, testing, and distribution guidance.
+
+`ProviderRegistration.icon` is a file path relative to the plugin directory, such as `icon.svg`.
+It must resolve inside that directory to a regular SVG file no larger than 64 KiB. The SVG must be
+self-contained: scripts, styles, `foreignObject`, event-handler attributes, JavaScript URLs, and
+external `href` or `xlink:href` references are rejected. Fragment references such as `#mark` are
+allowed. Paseo reads and sanitizes the file when the plugin starts; the string is never an inline
+SVG or URL.
+
+## Contribute buttons
+
+Header buttons and composer pills share the client-only descriptor and registration lifecycle in
+`packages/app/src/plugins/buttons/`. The [public button reference](../public-docs/plugins/v0.8/reference.md#header-buttons)
+owns the author API and placement rules. Keep presentation policy in this module so another
+placement can reuse behavior without copying registration or action state.
+
+Native sheets teleport their children. Button surfaces rebuild the installation's SDK, state,
+query, and toast providers inside the surface content, including overflow pages from different
+plugins. Providers only around the trigger do not reach those bodies.

 ## Contribute timeline items

 Timeline transformers and renderers are client contributions. The daemon's canonical rows and
-built-in projection stay unchanged. The app transforms fetched projected history before building
-its render model. A matching live event requests a fresh projected tail, so lifecycle deltas are
-collapsed before the transformer replaces anything.
+built-in projection stay unchanged. The app transforms each source item while building the render
+model, for both fetched history and live events. The input includes `phase: "streaming" | "complete"`.
+Paseo memoizes by source-item reference and derives every replacement ID from the source identity, so
+streaming updates preserve mounted component identity.

 `query.itemType` selects one public `AgentTimelineItem.type`. The callback owns any detailed
 recognition and returns plain plugin item objects. `undefined` keeps the source item, `items`
 replaces it, and an empty array removes it. Output `data` must be JSON-compatible. Paseo adds the
-runtime plugin ID, preserves the source timeline cursor, validates renderer data with its Zod
-schema, and mounts the component inside the normal plugin runtime and error boundary.
+runtime plugin ID, preserves the source timeline cursor and identity, validates renderer data with
+its Zod schema, and mounts the component inside the normal plugin runtime and error boundary. An
+optional output `id` distinguishes several stable replacements from the same source item; its output
+index is the default.

 Transformers run synchronously and must be deterministic. When several transformers match, the
 first one that returns a result owns that source item. Plugin and registration ordering is stable.
 See `plugin-examples/timeline-items` for the complete contract.

+A plugin subprocess can also append a canonical plugin row from a server handler:
+
+```ts
+await paseo.agents.ref(agentId).timeline.append({
+  type: "plugin",
+  id: "review",
+  kind: "review-result",
+  version: 1,
+  data: { status: "ready" },
+});
+```
+
+The daemon stamps the runtime `pluginId`; plugin code never supplies it. Reusing the same `id`
+replaces the previous row from that plugin on live clients and fresh timeline fetches. Rows live in
+the daemon's in-memory timeline and survive scroll, refetch, and reconnect, but not a daemon
+restart. A row without an installed renderer shows an unavailable placeholder. Serialized `data`
+must be at most 64 KiB; the daemon rejects a larger append instead of storing a payload that cannot
+be rendered intact. The daemon advertises this RPC through
+`server_info.features.pluginTimelineItems`.
+
+## Contribute client slash commands
+
+`addSlashCommand` registers an agent- or workspace-context command in the composer. The
+callback runs in the app, receives the trimmed text after the command name as `args`, and receives
+the same `paseo`, `rpc`, `openSurface`, workspace, agent, and `openPanel` capabilities as the matching
+Command Center callback.
+
+```ts
+client.addSlashCommand({
+  name: "review",
+  description: "Run the review bot",
+  argumentHint: "[scope]",
+  context: "agent",
+  async onSubmit({ args, agent, rpc }) {
+    await rpc(startReview, { agentId: agent.id, scope: args });
+  },
+});
+```
+
+Paseo owns the autocomplete row, input clearing, and error toast. It never sends the command text to
+the agent. Built-in client commands win name and alias collisions, plugin commands win
+provider-command collisions, and the first plugin in stable catalog order wins collisions between
+plugins. Plugin slash commands do not run when the composer has attachments.
+
 ## Contribute composer attachments

 Register a declarative attachment source backed by a plugin RPC. Paseo owns the attachment menu,
@@ -273,13 +426,24 @@ search picker, drafts, selected pill, and submission. The plugin returns complet
 credentials and vendor API calls stay in the daemon handler.

 ```ts
-import type { PluginContext } from "@getpaseo/plugin";
-import { search } from "./issues.server";
-import { issues, searchIssues } from "./issues.shared";
+// index.server.ts
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { search } from "./server/issues";
+import { searchIssues } from "./shared/issues";

-export default function contribute(plugin: PluginContext) {
-  plugin.handle(searchIssues, search);
-  plugin.addAttachmentSource(issues);
+export default function contribute(server: PluginServerContext) {
+  server.handle(searchIssues, search);
+  return () => {};
+}
+```
+
+```tsx
+// index.client.tsx
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { issues } from "./shared/issues";
+
+export default function contribute(client: PluginClientContext) {
+  client.addAttachmentSource(issues);
  return () => {};
 }
 ```
@@ -289,6 +453,18 @@ on several hosts are not coalesced. The selected snapshot submits as a text atta
 external-resource presentation, so it remains readable if the plugin is removed or an older peer
 drops the optional presentation fields.

+## Contribute settings
+
+Register ordinary components with `client.addSettingsScreen` and open them with `openSettings`.
+The host settings shell owns navigation and layout; plugin content must not add another page
+scroll view or header. See the [author contract](../public-docs/plugins/v0.8/reference.md#settings-screens)
+and `plugin-examples/settings` for the named UI components and persistence API.
+
+Settings storage is scoped to the runtime installation ID, never the source path or manifest ID.
+Its writer lives with the plugin subprocess, while its directory lives outside managed sources,
+so updates and reloads retain values. Settings-change notifications must not enter the catalog
+reload path: that path disposes the plugin and would destroy open drafts after every save.
+
 ## Contribute a theme

 `addTheme` takes a small light or dark palette and a display name. Paseo expands it through the
@@ -298,8 +474,8 @@ contract. Unistyles needs every theme name at `StyleSheet.configure` time, so
 provider rewrites the matching slot when the selection changes. See [unistyles.md](unistyles.md)
 for the runtime-patching rules the appearance settings share.

-`addTheme` is a client registration, so the compiler strips it from the backend bundle. A daemon
-that predates it does not, and the plugin fails to start there. Daemons advertise
+`addTheme` is a client registration and belongs in `index.client.tsx`. A client that predates it
+cannot evaluate that entry. Daemons advertise
 `features.pluginThemes` in `server_info`; the plugin theme catalog is the one place the app reads it, and
 a host without it contributes no themes.

@@ -312,6 +488,8 @@ stable rather than arrival-ordered. The app resolves that id
 against the installed catalog on every change; an id nothing contributes falls back to the default
 preference instead of painting the reserved slot's placeholder colors.

+Existing plugin authors should follow the standalone [v0.8 runtime-entry migration guide](../public-docs/plugins/v0.8/migration.md).
+
 See `plugin-examples/local-plugin` for a native surface, `plugin-examples/linear` for a complete
 attachment-source example, `plugin-examples/timeline-items` for timeline projection, and
 `plugin-examples/catppuccin` for a theme.
@@ -1,81 +1,102 @@
 # Product

-What Paseo is, who it's for, and where it's going.
+Paseo is an environment for running, monitoring, and interacting with coding agents across desktop, mobile, web, and the command line.

-## What is Paseo
+**Paseo has a lean, opinionated core built to be extended.** It should be easy to start using and leave room for people to build far beyond the default experience.

-Paseo is a next-generation development environment built around agents. One interface to run, monitor, and interact with coding agents across desktop, mobile, terminal, and web.
+## Agents are the focus

-The development workflow is shifting from manually editing files to orchestrating agents that do the editing. Paseo is built for that workflow.
+The central workflow is giving an agent a task, understanding what it is doing, providing direction, and reviewing the result. Files, terminals, diffs, and other supporting tools help you do that.

-## Core philosophy
+Paseo should make this workflow coherent across providers and devices. You should be able to use the agent that fits a task and keep working from another device without rebuilding your environment around it.

-Freedom and flexibility. Every design decision follows from this:
+This is the basis for product decisions. A familiar feature from another development tool earns its place by improving that experience. Familiarity alone does not make it a requirement for Paseo.

- **Multi-provider** — Use any coding agent harness. Pick the right model for each job, switch freely as the landscape shifts. No vendor lock-in.
- **Cross-device** — Desktop, mobile, web, CLI. Start work at your desk, check progress from your phone, script from the terminal.
- **Self-hosted** — The daemon runs on your machine. Your code, your keys, your environment. No inference markup, no cloud dependency.
- **Respectful** - No telemetry, no forced cloud, no forced accounts
- **Open source** — Apache-2.0. Users can inspect, fork, and contribute.
- **BYOK** — Bring your own keys. Use your subsidized plans and first-party provider pricing. Paseo adds zero cost on top.
+## A low floor and a high ceiling

-## How it works
+### Easy to start

-### Projects and workspaces
+The default experience should be lean, polished, and understandable to someone who has never run a server or configured a VPN.

-Projects are grouped in the sidebar, detected automatically from your filesystem and tagged by git remote when available.
+With a supported coding agent installed and authenticated, you can open the desktop app and start working. The app manages its local daemon. To connect your phone through the optional Paseo relay, enable pairing and scan a QR code. You do not need to configure a VPN or understand the networking behind it.

-Each project opens as a workspace. For git projects, the default workspace is the main checkout. Users can create additional workspaces, which are isolated copies (git worktrees) where agents work without affecting main.
+You should not need to know that plugins exist to get a useful, complete experience. Extra capability should become discoverable when it helps with something you want to do.

-### Inside a workspace
+Keeping this starting point approachable is an ongoing responsibility. A technically correct feature can still make the product harder to understand through extra choices, controls, or setup.

-A workspace is a flexible canvas:
+### Room to build your own setup

- Launch multiple agents side by side in split panes
- Open terminals alongside agents
- Mix and match providers within the same workspace
+The same product should also work for someone running agents on a home server, using their own network, or building an automated workflow.

-### The daemon
+The daemon can run independently of the desktop app. Clients connect to it locally or remotely, and multiple clients can use the same daemon. This separation lets you choose where the work runs and how you interact with it.

-Paseo is a client-server system. The daemon (Node.js) runs on your machine, manages agent processes, and streams output in real time over WebSocket. Clients connect to the daemon — locally or remotely.
+For example, someone can use the relay to connect their phone with minimal setup. Someone else can run a daemon on their own infrastructure and connect through SSH or a VPN. Both use the same underlying system.

-This architecture means:
+Paseo should provide useful defaults while keeping these choices available. You should not have to adopt every part of the system to benefit from the parts you want.

- The daemon can run on any machine: laptop, VM, remote server
- Multiple clients can connect simultaneously
- 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
+See the [connectivity guide](https://paseo.sh/docs/connectivity) for supported connection methods and [architecture](architecture.md) for the system design.

-## Target user
+## Freedom, ownership, and privacy

-Anyone who builds software:
+Paseo's flexibility depends on keeping control with the user:

- Care about owning their tools and their data
- Use multiple AI providers and want to switch freely
- Run agents on real tasks across real projects
- Want to work from multiple devices
+- **Self-hosted:** Run agents on your own machines, with your own environment, files, and credentials.
+- **Provider choice:** Use supported agent harnesses and extend provider support through plugins. Your workflow should be able to evolve as your choice of provider changes.
+- **Cross-device:** Use desktop, mobile, web, and CLI clients according to the situation.
+- **Privacy:** No Paseo telemetry, tracking, or forced account. The relay is optional and end-to-end encrypted.
+- **Open source:** Paseo is Apache-2.0 licensed. You can inspect it, modify it, and build on it.

-## What compounds over time
+Convenience and ownership should work together. Offering a straightforward way to connect should preserve the option to operate your own setup.

- **Trust** — Showing up daily, shipping in public, being open source. Earned slowly, lost quickly.
- **Community contributions** — Code, packaging, skills, agent configs. Contributors become advocates.
- **Ecosystem** — Skills, integrations, shared configs. Community-built content that makes the platform more valuable.
+## A lean core that keeps improving

-## Strategic bets
+The core provides the shared experience: starting work, interacting with agents, understanding their state, and moving between workspaces and devices.

-1. **Models commoditize.** Value moves to the orchestration layer. The best model changes monthly — the workflow layer stays.
-2. **Multi-provider wins.** No single provider stays on top. Developers want the best model for each task.
-3. **The daemon as infrastructure.** Server/client architecture enables deployment anywhere.
-4. **Open source outlasts funding.** Open source communities are resilient. Contributors become advocates.
+Core development continues through improvements to reliability, performance, interaction design, and workflows with broad value. A lean core takes ongoing work.

-## Current state (May 2026)
+Every addition also has a lasting cost. It needs a place in the interface, an understandable relationship with existing behavior, testing across affected platforms, and maintenance as the rest of the product changes. A feature can work exactly as intended and still be the wrong addition.

- Desktop (Electron), mobile (iOS/Android), web, CLI
- Built-in providers: Claude Code (Agent SDK), Codex (app-server), GitHub Copilot (ACP), OpenCode, Pi, OMP
- One-click ACP provider catalog: CodeWhale, Cursor, Hermes, Qwen Coder, Kimi Code, and others — plus custom ACP providers
- Voice mode: dictate prompts or talk through problems hands-free
- MCP server exposes the daemon to other agents (workspaces, create/detach agent, schedules, heartbeats, terminals, workspace renaming)
- Scheduled agents (cron-style triggers) via app, CLI, and MCP
- Frequent releases (multiple per week)
- Community contributions across packaging, providers, and bug fixes
- Key UX: split panes, keybinding customization, workspace model, in-app browser
+The preference is for a small number of well-shaped capabilities that work together. Before adding a specialized workflow, consider whether an existing capability can serve it or whether a reusable extension point would let people build it themselves.
+
+The boundary can evolve. Some built-in capabilities may eventually make more sense as plugins. Any such move needs to preserve a coherent default experience and account for people who already depend on it.
+
+## Extensibility and composition
+
+Plugins are a central part of how Paseo gains capability.
+
+Someone who needs a different agent provider, a specialized workspace panel, or a custom command should be able to build and share it independently. They can make the choices that fit their users and maintain the integration on their own schedule.
+
+Paseo's role is to provide interfaces that make those contributions possible across the daemon and connected clients. The [plugin documentation](https://paseo.sh/docs/plugins) describes what each released API supports.
+
+The [SDK](https://paseo.sh/docs/sdk) lets applications and services use the daemon directly. A separate dashboard, automation service, or client can build on the same agent infrastructure. Those projects do not all need to become features of the main app.
+
+Composition means useful pieces can be combined in ways the maintainer did not have to predict. Keeping the daemon independent, offering multiple connection methods, and exposing agent operations through APIs gives people room to choose those combinations.
+
+The extension interfaces need the same care as the core experience. They should be understandable, reusable, and maintainable. New extension points should follow concrete workflows that need them.
+
+## How Paseo develops
+
+Product, design, architecture, and workflow decisions remain with the maintainer.
+
+Those decisions draw on the history of the product: why a workflow has its current shape, what previous approaches taught us, how it interacts with the rest of the system, and where it is intended to go. Documentation shares that context, but familiarity also develops through sustained use and maintenance.
+
+Development starts with the smallest useful change that can make a substantial difference. After shipping it, leave room to learn:
+
+- Can people discover and understand it?
+- Does it work well in their actual workflows?
+- What friction or missing capability appears with repeated use?
+- Does the next addition improve the shared experience or belong in a plugin?
+
+That feedback guides the next step. Expanding a workflow too far before people use it creates commitments that are difficult to reverse. Users build habits and integrations around what ships, so removing features or changing interfaces has a real cost.
+
+Writing an implementation is one part of this process. Product judgment, design, QA, review, and learning from use determine how quickly a change can responsibly become part of Paseo.
+
+## An ecosystem people can build on
+
+People contribute through reproducible bug reports, testing, workflow discussions, documentation, plugins, integrations, and helping each other.
+
+A plugin can solve a problem for its users without adding that workflow to everyone's default experience. An alternative client can explore a different interface while using the same daemon. These projects let people take ownership of the experience they want.
+
+The aim is an ecosystem that can develop independently of the maintainer's ability to review core changes. Its value comes from useful things people build, maintain, and share.
+
+Paseo is an independent project. Sustainable development, a coherent product, and the freedom to keep building are priorities. See [Contributing](../CONTRIBUTING.md) for how to participate.
@@ -38,6 +38,18 @@ The app checks for the capability and either runs the feature or tells the user

 Existing functionality keeps working across versions because of the protocol contract. Gating a new feature never substitutes for that.

+## Client capability ownership
+
+The client package advertises the protocol behavior it implements. Add each new capability to
+its exhaustive defaults and implement the associated subscription or decoding behavior there.
+The app, CLI, and plugins inherit those defaults; they supply only host resources such as browser
+automation, or explicit overrides. A schema accepting a message does not establish support for
+its delivery semantics.
+
+Connecting creates no timeline or event demand. Client subscriptions own their network membership,
+release it on unsubscribe, and restore it after reconnect. Raw message observers inspect traffic
+without requesting streams. Application caches and which agents are visible remain caller-owned.
+
 ## Every shim is tagged and dated

 A shim that exists for old-app or old-daemon support carries a comment naming it, the version it arrived in, and when it can go:
@@ -57,7 +57,9 @@ Existing direct providers: `claude` (in `providers/claude/agent.ts`), `codex` (`

 Claude first-party model metadata lives in `packages/server/src/server/agent/providers/claude/model-manifest.ts`. When adding or updating a Claude model, update that manifest only; the model picker thinking options and Claude-specific feature gates are derived from the manifest. Do not add model-specific Claude capability lists in feature code.

-Paseo tools are not implemented as MCP tools internally. They live in a shared tool catalog under `packages/server/src/server/agent/tools/`; MCP is only the fallback adapter. A provider that can register runtime tools directly should set `supportsNativePaseoTools: true` and consume `launchContext.paseoTools` in `createSession`/`resumeSession`. When native tools are present, `AgentManager` strips the internal Paseo MCP server from the provider launch config so the provider does not receive the same tools twice. Providers that only know MCP should keep `supportsMcpServers: true` and let the daemon inject `/mcp/agents`.
+Paseo tools are not implemented as MCP tools internally. They live in a shared tool catalog under `packages/server/src/server/agent/tools/`; MCP is only the fallback adapter. The daemon resolves `agents.providers.<provider>.paseoTools` by the exact provider ID. The catalog policy belongs to the caller: it filters the tools exposed to the current agent. When that agent calls `create_agent`, the child receives the policy for the child provider ID; the caller's policy is not inherited.
+
+A provider that can register runtime tools directly should set `supportsNativePaseoTools: true` and consume the already-filtered `launchContext.paseoTools` in `createSession`/`resumeSession`. When native tools are present, `AgentManager` strips the internal Paseo MCP server from the provider launch config so the provider does not receive the same tools twice. Providers that only know MCP should keep `supportsMcpServers: true` and let the daemon inject `/mcp/agents`; the MCP server builds the same policy-filtered catalog for that caller. Filtering is enforced at catalog registration in both paths. Browser tools remain subject to the daemon browser-tools setting and browser-host availability.

 Pi is a process-backed provider. Paseo requires the user to have the `pi` binary installed and talks to it through `pi --mode rpc`; the server package does not embed Pi's SDK/runtime packages.

@@ -67,7 +69,7 @@ Pi model records expose input capabilities through `model.input`. Only send raw

 Pi MCP support depends on the open-source `pi-mcp-adapter` extension being loaded for the agent cwd. Probe with Pi RPC `get_commands`; the adapter registers an extension command named `mcp` (often with `sourceInfo.source` containing `pi-mcp-adapter`). When Paseo injects MCP servers into Pi, write a per-agent MCP config and pass it with `--mcp-config` instead of modifying user or project MCP files. Because that flag replaces the Pi global config layer, preserve the existing `<Pi agent dir>/mcp.json` in the generated file before overlaying injected servers. For local HTTP servers such as Paseo's own `/mcp/agents` endpoint, explicitly disable adapter OAuth (`auth: false`, `oauth: false`) in the generated config.

-Pi and OMP control-plane RPCs wait 60 seconds by default. Override the provider's `params.rpcTimeoutMs` when extension or MCP startup on a slow host needs a different deadline. Timeout errors name the pending RPC phase and report both elapsed time and the configured deadline. This setting does not govern long-running Pi compaction or Pi extension UI results.
+Pi control-plane RPCs wait 60 seconds by default. Override `params.rpcTimeoutMs` when extension or MCP startup on a slow host needs more time. Timeout errors name the pending RPC phase and report both elapsed time and the configured deadline. This setting does not govern long-running Pi compaction or Pi extension UI results. See [OMP profiles and Pi-compatible forks](custom-providers.md#omp-profiles-and-pi-compatible-forks) for OMP startup and RPC deadlines.

 Pi import discovery reads Pi's persisted JSONL session files because Pi RPC does not expose a recent-session listing command. Resume and full history hydration still go through `pi --mode rpc` using the session file as `nativeHandle`.

@@ -85,9 +87,9 @@ OpenCode owns user message IDs. Do not pass Paseo-generated IDs to OpenCode prom

 `AgentManager` owns the one canonical timeline row for a foreground prompt carrying a Paseo `clientMessageId`. It records that row when `startTurn` accepts, with the wire `messageId` set to the same value. Provider adapters still emit their native user-message echo with the same `clientMessageId` when available; the manager records its provider identity on the internal row without changing or redispatching the wire item. If an adapter emits the echo before `startTurn` resolves, the manager records the provider identity with the row at acceptance. Provider adapters continue to own externally initiated user rows that have no Paseo client identity. Do not perform global transcript text dedupe.

-Active-turn steering is an optional `AgentSession.steerActiveTurn` operation. The manager owns admission against its exact foreground turn, canonical user-message creation, echo reconciliation, and falls back to the normal interrupt-and-replace path only when the adapter reports `unavailable`. An adapter error leaves the steer's fate ambiguous and must surface without an interrupt or retry. Codex calls `turn/steer` with the native expected turn and Paseo client user-message ID. Claude pushes an admitted steer into the exact active SDK query input; isolated control commands remain unavailable. OpenCode calls `session/prompt_async` with an OpenCode-generated message ID; the server queues the prompt while busy and the next LLM call in the same Paseo turn includes it. A missing session reports `unavailable` and uses the normal interrupt fallback.
+Active-turn steering is an optional `AgentSession.steerActiveTurn` operation. The manager owns admission against its exact foreground turn, canonical user-message creation, echo reconciliation, and falls back to the normal interrupt-and-replace path only when the adapter reports `unavailable`. An adapter error leaves the steer's fate ambiguous and must surface without an interrupt or retry. Codex calls `turn/steer` with the native expected turn and Paseo client user-message ID. Claude pushes an admitted steer into the exact active SDK query input; isolated control commands remain unavailable. OpenCode calls `session/prompt_async` with an OpenCode-generated message ID; the server queues the prompt while busy and the next LLM call in the same Paseo turn includes it. Pi sends its native `steer` RPC, which queues the message for delivery after the in-flight assistant turn's tool calls. Slash-command inputs report `unavailable` because pi rejects extension commands on the steer path, and echo identity is correlated by message text because pi's steer RPC takes no message ID. A missing session reports `unavailable` and uses the normal interrupt fallback.

-A steering adapter also owes its interrupt: stopping a turn must discard the steers the provider has not read yet, or one of them resumes the turn the user just stopped. Codex clears pending input when it aborts a turn; Claude does not, so its adapter cancels the SDK messages it queued before calling `query.interrupt()`.
+A steering adapter also owes its interrupt: stopping a turn must discard the steers the provider has not read yet, or one of them resumes the turn the user just stopped. Codex clears pending input when it aborts a turn; Claude does not, so its adapter cancels the SDK messages it queued before calling `query.interrupt()`. Pi requires `clear_queue` before `abort`; older binaries without that RPC retain their native queue behavior until the pi compatibility floor reaches 0.84.4.

 `SteerActiveTurnOptions.clearPendingPermissions` makes permission release part of the provider contract. A provider that accepts such a steer queues it first, denies permissions blocking its delivery, and stops once the steer is read. Steers without the flag leave permissions open. A denied plan remains in the timeline because the pending card was the only other copy of its text.

@@ -113,7 +115,18 @@ Daemon bootstrap reconciles that ledger in the background, without blocking star

 ## Provider Snapshot Refresh Contract

-The daemon keeps provider snapshots per resolved working directory, with a separate semantic global scope for settings/provider management and requests that do not carry a cwd. Provider catalog probes receive a discriminated `FetchCatalogOptions`: `{ scope: "global", force }` for global catalog refreshes, or `{ scope: "workspace", cwd, force }` for project-scoped refreshes. Providers decide what global means for their runtime; do not infer global by comparing a cwd to the user's home directory.
+Provider snapshots are views of the catalogues needed for a target. Before looking up cached
+results or discovery in flight, the manager calls optional `AgentClient.getCatalogCacheKey(options)`.
+The provider owns equivalence: equal keys must mean the same availability, models and modes,
+including the effective configuration and execution environment. `force` does not change identity.
+Omitting the method or returning `undefined` keeps target-specific caching. Codex and Claude's
+current host clients share across directories; configured provider identities remain isolated.
+
+The key chooses storage, never execution. Availability and catalogue discovery receive the actual
+`{ scope: "global", force }` or `{ scope: "workspace", cwd, force }` request, including when another
+target can share its result. Runtime-aware adapters must use that target for both probing and key
+resolution. An explicit home-directory workspace is distinct from a semantic global request.
+Plugin callbacks follow the same contract; see [plugin providers](plugins.md#contribute-a-provider).

 `ProviderSnapshotManager` owns one refresh deadline per provider. The deadline starts before the
 availability check and covers that check plus the complete catalog probe. Providers that make
@@ -122,15 +135,41 @@ aborts the shared refresh signal at the deadline. Providers name active catalog
 finish subprocess, server, or session cleanup before rejecting. Timeout errors list the operations
 that were still active when the deadline expired.

-Snapshot reads may probe providers only while the requested cwd scope is cold. Once an entry is warm, its `ready`, `error`, or `unavailable` state stays cached until an explicit refresh. Do not add TTL revalidation, focus-triggered refreshes, selector-open refreshes, or config-reload refreshes. Selector-open refetches may read an already-loading or stale React Query, but they must not force provider probing on their own.
+Catalogue results stay cached by identity until explicit refresh or a change to that provider's configuration.
+Keys are resolved on each read so project configuration can select a different cached catalogue.
+Selector opening may read a loading or stale query, but does not force provider probing.

-Capable clients receive a compact, content-addressed snapshot. Model rows derive their provider from the containing entry and reference snapshot-level thinking sets. The app persists that compact shape per server and cwd, then sends its hash on the next pull; an unchanged response carries no catalog body. Keep the legacy encoding for clients without the capability. The hash covers the complete client-visible compact snapshot, including status and `fetchedAt`, so explicit refreshes invalidate it even when the discovered catalog is otherwise equal.
+Saved provider/model choices are user intent. Catalogue failure must not erase them or substitute
+another model. Creation reads the caller's host and directory directly; an earlier global snapshot
+must not settle a project form's initial selection.

-Settings refresh is the user-facing "forget stale provider knowledge everywhere" action. A settings refresh clears provider snapshot caches and in-flight loads across all cwd scopes, then immediately refreshes only the global snapshot with `force: true`. Workspace snapshots are re-probed lazily on the next scoped read; do not fan out a settings refresh across every known workspace.
+The server's provider keys never cross the wire. Clients advertising `provider_snapshot_references`
+receive directory-to-hash announcements; an unknown hash uses the existing snapshot request.
+The manager detaches each fresh result once and publishes its content identity with the entry;
+readers share these values read-only. Each target keeps its published snapshot until membership,
+content or discovery freshness changes. All affected targets commit before subscribers run;
+subscriber failures are logged without changing discovery or configuration outcomes.
+The session compares both sides of a committed transition under the client's current visibility
+policy and sends only visible changes. It combines result identities with the client's encoding
+and icon policy, without traversing models. Reference hashes exclude freshness;
+legacy embedded hashes include it. Only responses that send a body compact the catalogue.
+Per-provider `fetchedAt` travels separately for reference clients and still means when discovery succeeded. `generatedAt`
+remains the time the response or announcement was generated. Refresh keeps settled entries visible
+until the next result, so unchanged discovery sends freshness without another model body.

-Registry/config replacement may update visible metadata such as label, description, default mode, enabled state, and provider membership, but it must not spawn provider processes. If a provider needs to be re-probed after a config change, route that through the explicit settings refresh path.
+The app's snapshot cache owns compact expansion and stores one body per server/hash, with separate
+directory/hash/freshness records under the same byte budget. Missing bodies share a React Query
+request; directory queries cancel superseded pulls before accepting pushes. Default SDK clients
+keep expanded entries and full updates. Only callers that own materialization opt into wire snapshots.
+Keep the full encoding for older clients; compact-snapshot support alone does not imply reference support.

-Boundary tests should assert observable behavior: cold reads may call provider availability/model/mode discovery for that scope; warm reads and registry replacement must not; explicit workspace refreshes affect only one cwd; settings refresh wipes all scopes but immediately refreshes only global.
+Settings refresh invalidates requested providers across known targets and refreshes them in their
+actual execution context, so every connected client receives the refreshed view. Discovery shares
+work by provider key and admits at most four concurrent catalogue probes per configured provider, so a stalled provider does not block discovery for others. Configuration replacement invalidates
+only changed providers; unchanged entries, clients, and discovery in flight survive. Preparation
+leaves installed reads untouched until commit. Plugin replacement uses registration runtime
+identity, so unchanged registrations and builtins keep their results. Await the refresh or warmup
+promise for completion: equal results, including equal discovery timestamps, emit no transition.

 ---

@@ -11,6 +11,9 @@ The bar is four questions:

 Every pull request needs evidence for the questions its change touches. Pull requests without evidence get closed.

+For plugin changes, verify the [SDK import boundaries](plugins.md#sdk-import-boundaries) before
+exercising contributions. Include the boundary tests and both runtime loaders in the evidence.
+
 ## Evidence

 Evidence is something someone else can look at:
@@ -112,7 +112,7 @@ npm run release:patch
 npm run release:minor
 ```

-This bumps the version across all workspaces, runs checks, publishes to npm, and pushes the branch + tag. The tag push triggers `Desktop Release`, `Android APK Release`, `Docker`, and `Release Notes Sync` on GitHub Actions. EAS picks up the same tag via the EAS GitHub app and starts the iOS + Android store builds in parallel (see "Mobile builds (EAS)" below) — there is no mobile-release workflow under `.github/workflows`.
+This bumps the version across all workspaces, runs checks, publishes to npm, and pushes the branch + tag. The tag push triggers `Desktop Release`, `Android APK Release`, `Docker`, and `Release Notes Sync` on GitHub Actions. The workflows create the GitHub Release as a draft while builds and release-note sync run. EAS picks up the same tag via the EAS GitHub app and starts the iOS + Android store builds in parallel (see "Mobile builds (EAS)" below) — there is no mobile-release workflow under `.github/workflows`.

 After the stable release succeeds, move npm's `beta` pointer to the new stable
 version for every published package. This changes dist-tags only; do not
@@ -180,10 +180,10 @@ The rollout is driven by a `rolloutHours` field stamped into the GitHub Release

 Desktop release builds now publish in two phases:

- Platform build jobs upload the installers/packages (`.dmg`, `.zip`, `.exe`, `.AppImage`, etc.) to the GitHub release.
- The final job merges/stamps the manifests and uploads all `.yml` files only after they already contain the final `releaseDate` and `rolloutHours`.
+- The GitHub Release stays a draft while platform build jobs upload the installers/packages (`.dmg`, `.zip`, `.exe`, `.AppImage`, etc.).
+- The final job merges and stamps every channel manifest, uploads them with the final `releaseDate` and `rolloutHours`, then publishes the GitHub Release.

-Updater clients only discover a release through those `.yml` manifests, so there is no silent 100% admission window before rollout metadata is present.
+Drafts do not appear in GitHub's releases feed. Updater clients continue to see the previous complete release until all three manifests are available. If a desktop build or manifest upload fails, the new release stays a draft.

 ### Default behavior

@@ -253,6 +253,15 @@ If you ship N+1 while N is still ramping, N+1 starts a fresh rollout from its ow

 If N+1 is a hotfix for a bug in N, dispatch `desktop-rollout.yml -f tag=v0.1.<N+1> -f rollout_hours=0` after N+1 publishes so the users who already got N reach the fix fast.

+### macOS system floor
+
+The desktop app requires macOS 13 or newer. Keep both release guards when the floor changes:
+
+- `packages/desktop/electron-builder.yml` writes the macOS version to `LSMinimumSystemVersion` for new installs.
+- `scripts/merge-mac-manifest.mjs` writes the matching Darwin kernel version to `minimumSystemVersion` in the update manifest. Existing clients check this before downloading an update.
+
+macOS 13 maps to Darwin 22. The two values use different version domains; do not copy the macOS version into the update manifest.
+
 ### Limitations

 - **No pause / kill switch.** To stop new admissions, ship a superseding release. Clients revalidate on quit and will not install the superseded download, but a client that already completed installation cannot be recalled; ship a hotfix `+1` patch.
@@ -375,7 +384,7 @@ The GitHub Release body is populated automatically by the `Release Notes Sync` w
 - The default download target only moves when you publish the final stable release tag like `v0.1.41`.
 - The public `/changelog` page renders `CHANGELOG.md` as-is, so the in-flight `-beta.N` entry shows there once it lands on `main` — that's intended, it's where beta users check what's coming. Only the **default download target** stays pinned to the latest stable; the download links read GitHub's releases API, not the changelog, so a `-beta.N` heading on top never affects them.
 - The download page's "What's new" link deep-links the **minor group** anchor (`/changelog#release-0.3`), not the exact entry: promotion collapses the beta entries into one stable entry, so the minor group remains the durable target. A version with no entry in the bundled changelog — a tag whose changelog commit hasn't redeployed the site yet — links the plain `/changelog` instead of a dead anchor.
- The website itself is deployed by `Deploy Website` (Cloudflare Workers), which redeploys on `release: published` for non-prerelease releases and on pushes to `main` that touch `CHANGELOG.md` or `packages/website/**`.
+- The website itself is deployed by `Deploy Website` (Cloudflare Workers), which redeploys on the `release: published` event emitted when a stable draft is published and on pushes to `main` that touch `CHANGELOG.md` or `packages/website/**`. Its job condition excludes beta prereleases.

 ## Fixing a failed release build

@@ -404,6 +413,13 @@ you want to build. Reusing the same tag name is expected: move it with
 `git tag -f ...` and push it with `--force` so the workflow rebuilds the commit
 you actually want.

+A failed desktop build leaves the GitHub Release as a draft. `finalize-rollout`
+uploads manifests from successful platforms before it fails. A later
+single-platform retry reuses those manifests, stamps the complete set with one
+release date, and publishes the draft. Use `desktop-vX.Y.Z` when more than one
+platform failed. A `workflow_dispatch` rebuild with publishing enabled follows
+the same path against the existing draft.
+
 Prefer a tag push over `workflow_dispatch` when rebuilding desktop or APK
 release assets. Prefer Docker workflow dispatch when rebuilding only the Docker
 image.
@@ -433,6 +449,22 @@ This ensures the checkout ref matches the actual code on `main` with the fix inc
 - `desktop-macos-vX.Y.Z`, `desktop-linux-vX.Y.Z`, and `desktop-windows-vX.Y.Z` rebuild only that desktop platform
 - `android-vX.Y.Z` rebuilds the Android APK release only

+If you decide to publish a release without working desktop builds, inspect its
+assets first, then publish it manually:
+
+```bash
+RELEASE_LOOKUP=$(node scripts/github-release.mjs --repo getpaseo/paseo --tag vX.Y.Z)
+gh release view "$RELEASE_LOOKUP" --json isDraft,isPrerelease,assets
+gh release edit "$RELEASE_LOOKUP" --tag vX.Y.Z --draft=false
+
+# Keep a beta marked as a prerelease:
+RELEASE_LOOKUP=$(node scripts/github-release.mjs --repo getpaseo/paseo --tag vX.Y.Z-beta.N)
+gh release edit "$RELEASE_LOOKUP" --tag vX.Y.Z-beta.N --draft=false --prerelease
+```
+
+This bypasses the updater-manifest guarantee. Use it only when the release is
+intentionally unavailable to desktop updater clients.
+
 ## Notes

 - `version:all:*` bumps root + syncs workspace versions and `@getpaseo/*` dependency versions
@@ -454,6 +486,8 @@ Release notes depend on the changelog heading format. The heading **must** be st

 No prefix (`v`), no extra text. `Release Notes Sync` matches the `## X.Y.Z` (or `## X.Y.Z-beta.N`) line for the pushed tag to extract the version. A malformed heading breaks the release-notes sync for that tag.

+`CHANGELOG.md` on `main` is also what the app's **What's new** sheet fetches and renders, so the file is a shipped product surface, not just a release input. `##` starts a release and `###` starts a section; the app reads section titles from the document, so renaming or adding one needs no app change. Everything under a section is rendered as Markdown: prose, lists, links, inline code, fenced code, block quotes, tables, and images. Raw HTML does not render — the shared Markdown parser runs with `html: false`, so a `<video>`, `<iframe>` or `<embed>` tag reaches the reader as visible markup. Keep media out of the changelog, or link to it. A GitHub callout renders as a block quote with its `[!NOTE]` marker still in the text. A release entry is what a user reads on a phone the moment they are offered the update — write it for them.
+
 ## Changelog policy

 - `CHANGELOG.md` includes stable releases and every entry in the current beta series.
@@ -585,7 +619,7 @@ Each beta entry records what its testers receive. Promotion produces the single
 - [ ] `npm run release:beta:patch`, `npm run release:beta:minor`, or `npm run release:beta:next` completes successfully
 - [ ] Every GitHub Actions run for the complete release commit and tag is green
 - [ ] npm shows the version under the `beta` dist-tag, not `latest`
- [ ] The GitHub prerelease exists with the changelog body and every expected macOS, Linux, Windows, and Android APK asset
+- [ ] The GitHub prerelease was published only after the three beta manifests were uploaded, and it has the changelog body and every expected macOS, Linux, Windows, and Android APK asset
 - [ ] GitHub `Desktop Release` workflow for the `v*-beta.N` tag is green
 - [ ] The GitHub prerelease contains `beta-mac.yml`, `beta-linux.yml`, and `beta.yml`
 - [ ] GitHub `Android APK Release` workflow for the same tag is green
@@ -608,9 +642,10 @@ Each beta entry records what its testers receive. Promotion produces the single
 - [ ] `npm run release:patch`, `npm run release:minor`, or `npm run release:promote` completes successfully
 - [ ] Every GitHub Actions run for the complete release commit and tag is green
 - [ ] Move npm's `beta` dist-tag to the new stable version for every published package and verify both `latest` and `beta` resolve to it
- [ ] The published GitHub Release exists with the changelog body and every expected macOS, Linux, Windows, and Android APK asset
+- [ ] The GitHub Release was published only after the three stable manifests were uploaded, and it has the changelog body and every expected macOS, Linux, Windows, and Android APK asset
 - [ ] GitHub `Desktop Release` workflow for the `v*` tag is green
 - [ ] The GitHub Release contains `latest-mac.yml`, `latest-linux.yml`, and `latest.yml`
+- [ ] `latest-mac.yml` contains the current `minimumSystemVersion` guard
 - [ ] GitHub `Android APK Release` workflow for the same tag is green
 - [ ] GitHub `Docker` workflow is green and both the versioned and `latest` images are published
 - [ ] GitHub `Release Notes Sync` is green and the release body matches the stable changelog entry
@@ -65,12 +65,18 @@ Codex hook mapping:
 - `PermissionRequest` → `needs-input`
 - `Stop` → `idle`

-OpenCode uses a server plugin instead of command hooks. The plugin listens to OpenCode bus events and emits these Paseo hook events:
+OpenCode uses a server plugin instead of command hooks. Both generations discover the same global plugin file. Their loaders select separate entrypoints: OpenCode 1 calls `server()` with `{ type, properties }` bus events; OpenCode 2 calls `setup()` and subscribes to decoded `{ type, data }` events. Do not share their status mapping: V1 publishes `session.status` snapshots, while V2 publishes `session.execution.*` transitions.

- `session.status` with `busy` or `retry` → `running`
- `session.status` with `idle` → `idle`
- `permission.asked` → `needs-input`
- `permission.replied` → `running`
+| OpenCode event                                              | Generation | Activity    |
+| ----------------------------------------------------------- | ---------- | ----------- |
+| `session.status` with `busy` or `retry`                     | 1          | running     |
+| `session.status` with `idle`                                | 1          | idle        |
+| `session.execution.started`                                 | 2          | running     |
+| `session.execution.succeeded`, `.failed`, or `.interrupted` | 2          | idle        |
+| `permission.asked`                                          | Both       | needs-input |
+| `permission.replied`                                        | Both       | running     |
+
+The plugin translates both event contracts into the existing Paseo hook events. OpenCode 2 disposes its event subscription when the plugin unloads.

 The daemon maps hook states onto terminal activity like an agent lifecycle plus unread attention: `running` → `state: working`, `idle` → `state: idle`, and `needs-input` → `state: idle` with `attentionReason: needs_input`. A `working` → `idle` transition records `state: idle` with `attentionReason: finished` until the user focuses that terminal; plain idle terminals still contribute no workspace status.

@@ -152,7 +152,7 @@ remaining page through the existing stream reducer. It must not append full proj
 live prefix.

 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
+send-now, and the host runtime's automatic queue drain — 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.
@@ -196,9 +196,9 @@ fork positions retain the canonical `turnId` boundaries.
 The compatibility boundary for older daemons is snapshot normalization: running/idle status becomes an
 anonymous active turn or idle state once, and downstream code consumes the same activity shape. The app
 does not combine anonymous lifecycle events, timestamps, timeline rows, and resume coverage to infer a
-second running state. Disconnect and replica removal remain destructive close boundaries. Elapsed time
-comes only from turn liveness, never from submission records or whichever timeline rows happen to be
-mounted.
+second running state. Disconnect preserves the last replicated turn until cache or network hydration
+advances it; replica removal remains the destructive close boundary. Elapsed time comes only from turn
+liveness, never from submission records or whichever timeline rows happen to be mounted.

 The daemon records one canonical submitted user row at acceptance. Its wire `messageId` is the
 submission's `clientMessageId`, so the row is born with its final identity and remains immutable on
@@ -346,9 +346,22 @@ Gotchas:
 - **Narrow the discriminated union before spreading.** `updateTheme`'s updater returns the theme union; spreading the union widens `colorScheme` to `"light" | "dark"`, which is assignable to neither concrete member. Branch on `t.colorScheme` so each branch spreads a single narrowed theme type (no `as`).
 - **`lineHeight.diff` is the code/diff line-height axis** — it is coupled to the code-font-size control (≈ `codeFontSize * 1.5`). Do NOT use it for prose. Markdown body line-height scales with content size (`Math.round(theme.fontSize.content * 1.4)`); routing prose through `lineHeight.diff` clips text at small code sizes.
 - **High-churn draft values** (live-while-typing in the appearance preview) bypass the theme: apply them as inline styles marked with `inlineUnistylesStyle` so per-keystroke values don't grow the `#unistyles-web` CSS registry.
- **The app shell uses one `AppearanceStyleBoundary`.** Runtime-patched numeric theme values are baked into Unistyles web classes rather than CSS variables, while parsed/memoized content also does not naturally re-run when appearance tokens change. The boundary sits below stable runtime providers in `app/_layout.tsx` and remounts the visual shell once. `applyAppearance` patches the active theme before inactive registry entries so its subscribers receive the committed values in the same update. Do not add local appearance keys or nested boundaries.
+- **Web numeric appearance tokens need a render; native tracked styles update in place.** On web, string tokens such as colors become CSS variables, but numeric tokens (font sizes, line heights) are baked into generated classes. `AppearanceStyleBoundary` remounts web shell chrome and explorer content to refresh those classes. Native sidebars and explorer hosts stay outside appearance keys: their gesture refs outlive detached dependents until Gesture Handler's passive cleanup, so remounting a related gesture can query an unmounted view. Their tracked native styles and existing themed leaf props update without replacing the gesture hosts or draggable lists. Parsed PR markdown uses its own `withUnistyles` style mapping.
+- **Appearance keys belong below native lifetime owners.** `ThemedStack` wraps screen content through `screenLayout`, preserving navigator identity; nested navigators are listed in `nestedNavigatorScreens` and own their own screen boundaries. The remaining shell surfaces retain their appearance refresh separately from native panel hosts. A key above a native stack can detach its screen container inside a FragmentManager transaction during settings hydration. Keep both navigators and retained panel gesture hosts outside those keys. `applyAppearance` patches the active theme before inactive registry entries so subscribers receive the committed values in the same update. Do not add local appearance keys or a boundary above a navigator.
 - **Dynamic font tokens stay widened.** `fontFamily`, `fontSize`, and `lineHeight` on `commonTheme` are annotated `string`/`number` (not narrowed by `as const`) so the updater's return assigns; the platform default stacks live in `DEFAULT_UI_FONT_STACK` / `DEFAULT_MONO_FONT_STACK`.

+## Patching The Web Runtime
+
+When backporting a Unistyles web fix, patch the TypeScript source and both
+shipped JavaScript builds. Native Metro resolves the package's `react-native`
+export to `src`, but browser and Electron Metro resolve its `browser` export to
+`lib/module`; CommonJS consumers use `lib/commonjs`. A source-only patch leaves
+Electron running the old code.
+
+Register every dependency patch in `scripts/postinstall-patches.mjs`. A file in
+`patches/` is inert unless that script knows which installed package activates
+it.
+
 ## Debugging

 To inspect what the Babel plugin sees, temporarily enable [`debug: true`](https://www.unistyl.es/v3/other/babel-plugin#debug) in `packages/app/babel.config.js`:
@@ -0,0 +1,4 @@
+Added
+- Added Claude Fable 5.1 with a 1M context window
+
+Full notes: https://paseo.sh/changelog
@@ -0,0 +1,4 @@
+Added
+- Added Claude Fable 5.1 with a 1M context window
+
+Full notes: https://paseo.sh/changelog
@@ -0,0 +1,4 @@
+Added
+- Added Claude Fable 5.1 with a 1M context window
+
+Full notes: https://paseo.sh/changelog
@@ -0,0 +1,4 @@
+Added
+- Added Claude Fable 5.1 with a 1M context window
+
+Full notes: https://paseo.sh/changelog
@@ -0,0 +1,11 @@
+Added
+- Added active-turn steering for pi agents so new messages reach the running turn without interrupting it
+- Added declared build commands and monorepo source paths for Git-hosted plugins
+
+Improved
+- Reduced JS stalls while watching a streaming agent on mobile
+
+Fixed
+- Fixed large and many-file diffs stalling or crashing while opening and scrolling
+
+Full notes: https://paseo.sh/changelog
@@ -0,0 +1,11 @@
+Added
+- Added active-turn steering for pi agents so new messages reach the running turn without interrupting it
+- Added declared build commands and monorepo source paths for Git-hosted plugins
+
+Improved
+- Reduced JS stalls while watching a streaming agent on mobile
+
+Fixed
+- Fixed large and many-file diffs stalling or crashing while opening and scrolling
+
+Full notes: https://paseo.sh/changelog
@@ -0,0 +1,11 @@
+Added
+- Added active-turn steering for pi agents so new messages reach the running turn without interrupting it
+- Added declared build commands and monorepo source paths for Git-hosted plugins
+
+Improved
+- Reduced JS stalls while watching a streaming agent on mobile
+
+Fixed
+- Fixed large and many-file diffs stalling or crashing while opening and scrolling
+
+Full notes: https://paseo.sh/changelog
@@ -0,0 +1,11 @@
+Added
+- Added active-turn steering for pi agents so new messages reach the running turn without interrupting it
+- Added declared build commands and monorepo source paths for Git-hosted plugins
+
+Improved
+- Reduced JS stalls while watching a streaming agent on mobile
+
+Fixed
+- Fixed large and many-file diffs stalling or crashing while opening and scrolling
+
+Full notes: https://paseo.sh/changelog
@@ -1 +1 @@
-sha256-YiXz9rVJxzhtKdvYsg5UhVXTaetvH0sdJ/8dyfvSGQQ=
+sha256-8P7kk9B2A81e13IIyyfo8fIoNGlrutfV/WGKAFHscUc=
@@ -1,12 +1,12 @@
 {
  "name": "paseo",
-  "version": "0.7.0",
+  "version": "0.8.0-beta.1",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "paseo",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "hasInstallScript": true,
      "license": "Apache-2.0",
      "workspaces": [
@@ -28,6 +28,7 @@
        "@vercel/nft": "^1.5.0",
        "concurrently": "^9.2.1",
        "cross-env": "^10.1.0",
+        "electron": "44.2.0",
        "get-port-cli": "^3.0.0",
        "js-yaml": "^4.1.1",
        "knip": "^5.82.1",
@@ -2883,6 +2884,16 @@
        "node": ">=0.8.0"
      }
    },
+    "node_modules/@electron-internal/extract-zip": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/@electron-internal/extract-zip/-/extract-zip-1.0.5.tgz",
+      "integrity": "sha512-+bqFCP98pLI0Tt0XQo1TmlXtwjWchISndDOxCkEcIuUgXWpBnLyRI+2DU+mesvnMMX6L1XDqYNA0lXNDHd/yiA==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=22.12.0"
+      }
+    },
    "node_modules/@electron/asar": {
      "version": "3.4.1",
      "resolved": "https://registry.npmjs.org/@electron/asar/-/asar-3.4.1.tgz",
@@ -2989,70 +3000,37 @@
      }
    },
    "node_modules/@electron/get": {
-      "version": "2.0.3",
-      "resolved": "https://registry.npmjs.org/@electron/get/-/get-2.0.3.tgz",
-      "integrity": "sha512-Qkzpg2s9GnVV2I2BjRksUi43U5e6+zaQMcjoJy0C+C5oxaKl+fmckGDQFtRpZpZV0NQekuZZ+tGz7EA9TVnQtQ==",
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/@electron/get/-/get-5.1.0.tgz",
+      "integrity": "sha512-3kSBtG8ObcTVfXanm5vVJ6UnBLEVmVsRk1M+vGqCuMBV+XLCbJYuWQful+yIy0GQDsSlK0kHEriEHn7SPk4EnA==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "debug": "^4.1.1",
-        "env-paths": "^2.2.0",
-        "fs-extra": "^8.1.0",
-        "got": "^11.8.5",
+        "env-paths": "^3.0.0",
+        "graceful-fs": "^4.2.11",
        "progress": "^2.0.3",
-        "semver": "^6.2.0",
+        "semver": "^7.6.3",
        "sumchecker": "^3.0.1"
      },
      "engines": {
-        "node": ">=12"
+        "node": ">=22.12.0"
      },
      "optionalDependencies": {
-        "global-agent": "^3.0.0"
+        "undici": "^7.24.4"
      }
    },
-    "node_modules/@electron/get/node_modules/fs-extra": {
-      "version": "8.1.0",
-      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz",
-      "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "graceful-fs": "^4.2.0",
-        "jsonfile": "^4.0.0",
-        "universalify": "^0.1.0"
-      },
-      "engines": {
-        "node": ">=6 <7 || >=8"
-      }
-    },
-    "node_modules/@electron/get/node_modules/jsonfile": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz",
-      "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==",
-      "dev": true,
-      "license": "MIT",
-      "optionalDependencies": {
-        "graceful-fs": "^4.1.6"
-      }
-    },
-    "node_modules/@electron/get/node_modules/semver": {
-      "version": "6.3.1",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
-      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      }
-    },
-    "node_modules/@electron/get/node_modules/universalify": {
-      "version": "0.1.2",
-      "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz",
-      "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==",
+    "node_modules/@electron/get/node_modules/env-paths": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/env-paths/-/env-paths-3.0.0.tgz",
+      "integrity": "sha512-dtJUTepzMW3Lm/NPxRf3wP4642UWhjL2sQxc+ym2YMj1m/H2zDNQOlezafzkHwn6sMstjHTwG6iQQsctDW/b1A==",
      "dev": true,
      "license": "MIT",
      "engines": {
-        "node": ">= 4.0.0"
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
    "node_modules/@electron/notarize": {
@@ -13081,6 +13059,13 @@
        "@types/node": "*"
      }
    },
+    "node_modules/@types/semver": {
+      "version": "7.8.0",
+      "resolved": "https://registry.npmjs.org/@types/semver/-/semver-7.8.0.tgz",
+      "integrity": "sha512-1mAINjtQCXXeLkJ9ehXkwOcBpqtLxiVtKhpUf83DdRNdQKV0iXZpaHYqRr7nj+wvxuJzoAmAwXI+sCNMv1CzLQ==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/@types/send": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/@types/send/-/send-1.2.1.tgz",
@@ -13187,17 +13172,6 @@
      "integrity": "sha512-I4q9QU9MQv4oEOz4tAHJtNz1cwuLxn2F3xcc2iV5WdqLPpUnj30aUuxt1mAxYTG+oe8CZMV/+6rU4S4gRDzqtQ==",
      "license": "MIT"
    },
-    "node_modules/@types/yauzl": {
-      "version": "2.10.3",
-      "resolved": "https://registry.npmjs.org/@types/yauzl/-/yauzl-2.10.3.tgz",
-      "integrity": "sha512-oJoftv0LSuaDZE3Le4DbKX+KS9G36NzOeSap90UIK0yMA/NhKJhqlSGtNDORNRaIbQfzjXDrQa0ytJ6mNRGz/Q==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "@types/node": "*"
-      }
-    },
    "node_modules/@typescript-eslint/eslint-plugin": {
      "version": "8.56.1",
      "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.56.1.tgz",
@@ -15813,16 +15787,6 @@
        "ieee754": "^1.2.1"
      }
    },
-    "node_modules/buffer-crc32": {
-      "version": "0.2.13",
-      "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-0.2.13.tgz",
-      "integrity": "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": "*"
-      }
-    },
    "node_modules/buffer-equal-constant-time": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz",
@@ -18675,22 +18639,22 @@
      }
    },
    "node_modules/electron": {
-      "version": "41.2.0",
-      "resolved": "https://registry.npmjs.org/electron/-/electron-41.2.0.tgz",
-      "integrity": "sha512-0OKLiymqfV0WK68RBXqAm3Myad2TpI5wwxLCBEUcH5Nugo3YfSk7p1Js/AL9266qTz5xZioUnxt9hG8FFwax0g==",
+      "version": "44.2.0",
+      "resolved": "https://registry.npmjs.org/electron/-/electron-44.2.0.tgz",
+      "integrity": "sha512-oK1icjhapp3xsUZycO9WZaLmd3hJnA7ieobC4mpdtO1pEN+PPGWpA3m1Mgzzuc1wzSD2Wai4zcH4yfpGJqxFMA==",
      "dev": true,
-      "hasInstallScript": true,
      "license": "MIT",
      "dependencies": {
-        "@electron/get": "^2.0.0",
-        "@types/node": "^24.9.0",
-        "extract-zip": "^2.0.1"
+        "@electron-internal/extract-zip": "^1.0.1",
+        "@electron/get": "^5.0.0",
+        "@types/node": "^24.9.0"
      },
      "bin": {
-        "electron": "cli.js"
+        "electron": "cli.js",
+        "install-electron": "install.js"
      },
      "engines": {
-        "node": ">= 12.20.55"
+        "node": ">= 22.12.0"
      }
    },
    "node_modules/electron-builder": {
@@ -18797,19 +18761,19 @@
      }
    },
    "node_modules/electron/node_modules/@types/node": {
-      "version": "24.12.2",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.12.2.tgz",
-      "integrity": "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g==",
+      "version": "24.13.3",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.13.3.tgz",
+      "integrity": "sha512-Dh8vAsV36ig5wa9OX4pXvMc9D3Veibfw2wix0CUwYODLD8nkj9UsLjASr49nPg+2eKzxhBV+v7L8pXvT4e639Q==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "undici-types": "~7.16.0"
+        "undici-types": "~7.18.0"
      }
    },
    "node_modules/electron/node_modules/undici-types": {
-      "version": "7.16.0",
-      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz",
-      "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==",
+      "version": "7.18.2",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
+      "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
      "dev": true,
      "license": "MIT"
    },
@@ -21881,43 +21845,6 @@
      "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==",
      "license": "MIT"
    },
-    "node_modules/extract-zip": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/extract-zip/-/extract-zip-2.0.1.tgz",
-      "integrity": "sha512-GDhU9ntwuKyGXdZBUgTIe+vXnWj0fppUEtMDL0+idd5Sta8TGpHssn/eusA9mrPr9qNDym6SxAYZjNvCn/9RBg==",
-      "dev": true,
-      "license": "BSD-2-Clause",
-      "dependencies": {
-        "debug": "^4.1.1",
-        "get-stream": "^5.1.0",
-        "yauzl": "^2.10.0"
-      },
-      "bin": {
-        "extract-zip": "cli.js"
-      },
-      "engines": {
-        "node": ">= 10.17.0"
-      },
-      "optionalDependencies": {
-        "@types/yauzl": "^2.9.1"
-      }
-    },
-    "node_modules/extract-zip/node_modules/get-stream": {
-      "version": "5.2.0",
-      "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.2.0.tgz",
-      "integrity": "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "pump": "^3.0.0"
-      },
-      "engines": {
-        "node": ">=8"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
    "node_modules/extsprintf": {
      "version": "1.4.1",
      "resolved": "https://registry.npmjs.org/extsprintf/-/extsprintf-1.4.1.tgz",
@@ -22082,16 +22009,6 @@
        "walk-up-path": "^4.0.0"
      }
    },
-    "node_modules/fd-slicer": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/fd-slicer/-/fd-slicer-1.1.0.tgz",
-      "integrity": "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "pend": "~1.2.0"
-      }
-    },
    "node_modules/fdir": {
      "version": "6.5.0",
      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -29636,13 +29553,6 @@
        "url": "https://github.com/sponsors/jet2jet"
      }
    },
-    "node_modules/pend": {
-      "version": "1.2.0",
-      "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz",
-      "integrity": "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==",
-      "dev": true,
-      "license": "MIT"
-    },
    "node_modules/picocolors": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -34564,7 +34474,6 @@
      "version": "5.9.3",
      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
-      "devOptional": true,
      "license": "Apache-2.0",
      "bin": {
        "tsc": "bin/tsc",
@@ -36137,17 +36046,6 @@
        "node": ">=12"
      }
    },
-    "node_modules/yauzl": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/yauzl/-/yauzl-2.10.0.tgz",
-      "integrity": "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "buffer-crc32": "~0.2.3",
-        "fd-slicer": "~1.1.0"
-      }
-    },
    "node_modules/yn": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/yn/-/yn-3.1.1.tgz",
@@ -36298,7 +36196,7 @@
    },
    "packages/app": {
      "name": "@getpaseo/app",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "dependencies": {
        "@codemirror/commands": "6.10.4",
        "@codemirror/language": "6.12.4",
@@ -37363,12 +37261,12 @@
    },
    "packages/cli": {
      "name": "@getpaseo/cli",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "dependencies": {
        "@clack/prompts": "^1.0.0",
-        "@getpaseo/client": "0.7.0",
-        "@getpaseo/protocol": "0.7.0",
-        "@getpaseo/server": "0.7.0",
+        "@getpaseo/client": "0.8.0-beta.1",
+        "@getpaseo/protocol": "0.8.0-beta.1",
+        "@getpaseo/server": "0.8.0-beta.1",
        "chalk": "^5.3.0",
        "commander": "^12.0.0",
        "mime-types": "^2.1.35",
@@ -37615,10 +37513,10 @@
    },
    "packages/client": {
      "name": "@getpaseo/client",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "dependencies": {
-        "@getpaseo/protocol": "0.7.0",
-        "@getpaseo/relay": "0.7.0",
+        "@getpaseo/protocol": "0.8.0-beta.1",
+        "@getpaseo/relay": "0.8.0-beta.1",
        "zod": "^4.4.3"
      },
      "devDependencies": {
@@ -37629,7 +37527,7 @@
    },
    "packages/desktop": {
      "name": "@getpaseo/desktop",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "license": "Apache-2.0",
      "dependencies": {
        "@getpaseo/cli": "*",
@@ -37642,7 +37540,7 @@
      "devDependencies": {
        "@types/node": "24.6.0",
        "@types/ws": "^8.5.14",
-        "electron": "41.2.0",
+        "electron": "44.2.0",
        "electron-builder": "26.8.1",
        "typescript": "5.9.3",
        "unzip-crx-3": "^0.2.0",
@@ -37872,7 +37770,7 @@
    },
    "packages/expo-two-way-audio": {
      "name": "@getpaseo/expo-two-way-audio",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "license": "MIT",
      "devDependencies": {
        "@types/jest": "^29.5.14",
@@ -38768,7 +38666,7 @@
    },
    "packages/highlight": {
      "name": "@getpaseo/highlight",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "dependencies": {
        "@codemirror/language": "6.12.4",
        "@codemirror/legacy-modes": "^6.5.3",
@@ -38797,43 +38695,74 @@
    },
    "packages/plugin": {
      "name": "@getpaseo/plugin",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "dependencies": {
+        "@agentclientprotocol/sdk": "^1.4.0",
        "use-sync-external-store": "^1.6.0"
      },
      "devDependencies": {
-        "@getpaseo/client": "0.7.0",
-        "@getpaseo/protocol": "0.7.0",
+        "@getpaseo/client": "0.8.0-beta.1",
+        "@getpaseo/protocol": "0.8.0-beta.1",
        "@types/node": "^20.9.0",
        "@types/react": "~19.2.0",
        "react": "19.1.0",
+        "react-native": "0.81.5",
        "typescript": "^5.9.3",
        "vitest": "^4.1.6",
        "zod": "^4.4.3"
      },
      "peerDependencies": {
-        "@getpaseo/client": "0.7.0",
-        "@getpaseo/protocol": "0.7.0",
-        "react": "19.1.0",
+        "@getpaseo/client": "0.8.0-beta.1",
+        "@getpaseo/protocol": "0.8.0-beta.1",
+        "react": "~19.1.0",
+        "react-native": ">=0.81.5",
        "zod": "^4.4.3"
+      },
+      "peerDependenciesMeta": {
+        "react-native": {
+          "optional": true
+        }
+      }
+    },
+    "packages/plugin/node_modules/@agentclientprotocol/sdk": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/@agentclientprotocol/sdk/-/sdk-1.4.0.tgz",
+      "integrity": "sha512-/eufudw+aFY1LKLolT6yFE6UMmYRl7fMJ/DEONSIyR6wI3slHWITBsANRGqXEY8FRzqUxwh7QEaGiZHcJPVThg==",
+      "license": "Apache-2.0",
+      "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
      }
    },
    "packages/protocol": {
      "name": "@getpaseo/protocol",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "dependencies": {
+        "semver": "^7.8.5",
        "zod": "^4.4.3"
      },
      "devDependencies": {
        "@types/node": "^20.9.0",
+        "@types/semver": "^7.8.0",
        "typescript": "^5.2.2",
        "vitest": "^4.1.6",
        "zod-aot": "0.20.4"
      }
    },
+    "packages/protocol/node_modules/semver": {
+      "version": "7.8.5",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
+      "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
    "packages/relay": {
      "name": "@getpaseo/relay",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "dependencies": {
        "base64-js": "^1.5.1",
        "tweetnacl": "^1.0.3",
@@ -39051,17 +38980,16 @@
    },
    "packages/server": {
      "name": "@getpaseo/server",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "dependencies": {
        "@agentclientprotocol/sdk": "^0.17.1",
        "@anthropic-ai/claude-agent-sdk": "0.3.246",
        "@anthropic-ai/sdk": "^0.104.2",
-        "@babel/parser": "^7.29.8",
-        "@getpaseo/client": "0.7.0",
-        "@getpaseo/highlight": "0.7.0",
-        "@getpaseo/plugin": "0.7.0",
-        "@getpaseo/protocol": "0.7.0",
-        "@getpaseo/relay": "0.7.0",
+        "@getpaseo/client": "0.8.0-beta.1",
+        "@getpaseo/highlight": "0.8.0-beta.1",
+        "@getpaseo/plugin": "0.8.0-beta.1",
+        "@getpaseo/protocol": "0.8.0-beta.1",
+        "@getpaseo/relay": "0.8.0-beta.1",
        "@isaacs/ttlcache": "^2.1.4",
        "@modelcontextprotocol/sdk": "1.29.0",
        "@opencode-ai/sdk": "1.14.46",
@@ -39087,6 +39015,7 @@
        "sherpa-onnx-node": "1.12.28",
        "strip-ansi": "^7.1.2",
        "tree-kill": "^1.2.2",
+        "typescript": "^5.9.3",
        "uuid": "^9.0.1",
        "which": "^5.0.0",
        "ws": "^8.14.2",
@@ -39102,56 +39031,9 @@
        "@vitest/ui": "^4.1.6",
        "cross-env": "^10.1.0",
        "tsx": "^4.6.0",
-        "typescript": "^5.2.2",
        "vitest": "^4.1.6"
      }
    },
-    "packages/server/node_modules/@babel/helper-string-parser": {
-      "version": "7.29.7",
-      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.7.tgz",
-      "integrity": "sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=6.9.0"
-      }
-    },
-    "packages/server/node_modules/@babel/helper-validator-identifier": {
-      "version": "7.29.7",
-      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz",
-      "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=6.9.0"
-      }
-    },
-    "packages/server/node_modules/@babel/parser": {
-      "version": "7.29.8",
-      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.8.tgz",
-      "integrity": "sha512-E8lTAYNB1KW+FH+VGJuZM1ioAx2E6oVlvQFRrf5P8ZZmsiJXYAD9vTFV7yyEURNzgh1dFqMZuO6tUwcARbqFCA==",
-      "license": "MIT",
-      "dependencies": {
-        "@babel/types": "^7.29.8"
-      },
-      "bin": {
-        "parser": "bin/babel-parser.js"
-      },
-      "engines": {
-        "node": ">=6.0.0"
-      }
-    },
-    "packages/server/node_modules/@babel/types": {
-      "version": "7.29.8",
-      "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.8.tgz",
-      "integrity": "sha512-Vj1jF3cPfxg7OAfoI7QnVKLoILlm2JF9pnVHrX8qx7AHMiYWT+NDAA7jChlNgRS4WTLc/fD1lXLmPixluj+3Gg==",
-      "license": "MIT",
-      "dependencies": {
-        "@babel/helper-string-parser": "^7.29.7",
-        "@babel/helper-validator-identifier": "^7.29.7"
-      },
-      "engines": {
-        "node": ">=6.9.0"
-      }
-    },
    "packages/server/node_modules/@esbuild/aix-ppc64": {
      "version": "0.25.12",
      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
@@ -39985,7 +39867,7 @@
    },
    "packages/website": {
      "name": "@getpaseo/website",
-      "version": "0.7.0",
+      "version": "0.8.0-beta.1",
      "dependencies": {
        "@cloudflare/vite-plugin": "^1.29.1",
        "@cloudflare/workers-types": "^4.20260317.1",
@@ -1,6 +1,6 @@
 {
  "name": "paseo",
-  "version": "0.7.0",
+  "version": "0.8.0-beta.1",
  "private": true,
  "description": "Paseo: voice-controlled development environment for local AI coding agents",
  "keywords": [
@@ -126,6 +126,7 @@
    "@vercel/nft": "^1.5.0",
    "concurrently": "^9.2.1",
    "cross-env": "^10.1.0",
+    "electron": "44.2.0",
    "get-port-cli": "^3.0.0",
    "js-yaml": "^4.1.1",
    "knip": "^5.82.1",
@@ -5,6 +5,7 @@ import {
  expectAgentIdle,
  expectAgentReadyToInterrupt,
  expectAgentSurfacesIdle,
+  expectInlineWorkingIndicator,
  expectRunningAgentChrome,
  expectVisibleAgentSurfacesIdle,
 } from "../support/helpers/agent-stream";
@@ -39,7 +40,10 @@ import {
  expectResumeOverflowFallsBackToOneTail,
  rememberTimelineRequestCounts,
 } from "../support/helpers/timeline-resume";
-import { workspaceDeckEntryLocator } from "../support/helpers/workspace-ui";
+import {
+  waitForWorkspaceInSidebar,
+  workspaceDeckEntryLocator,
+} from "../support/helpers/workspace-ui";
 import { expectInFlightForkAvailable } from "../support/helpers/assistant-fork";
 import {
  scrollTimelineToNewestLoadedEdge,
@@ -468,6 +472,10 @@ async function expectHiddenStreamingSubmissionOrderAfterWorkspaceEviction(

    await target.client.waitForFinish(target.agentId, 30_000);
    const requestsBeforeReturn = rememberTimelineRequestCounts(gate);
+    await waitForWorkspaceInSidebar(page, {
+      serverId: getServerId(),
+      workspaceId: target.workspaceId,
+    });
    await openAgentRoute(page, target);
    await expectComposerVisible(page);
    await subscriptions.waitForSubscribedAgents([target.agentId]);
@@ -542,9 +550,18 @@ async function expectProviderAcknowledgementBeforeRpcAcceptanceSettlesSubmission
    const userMessage = await submitMessageWithImage(page, prompt);
    await gate.waitForHeldServerMessage();
    await gate.waitForAgentStreamItem("user_message");
+    await gate.waitForAgentStreamEvent("turn_started");
    gate.releaseHeldServerMessage();
+    await expect(userMessage).toHaveAttribute("aria-busy", "false");
    await gate.drop();
-    await expect(page.getByTestId("turn-working-indicator")).toHaveCount(0);
+    await expectInlineWorkingIndicator(page);
+    await expect(userMessage).toHaveAttribute("aria-busy", "false");
+
+    await agent.client.waitForFinish(agent.agentId, 30_000);
+    gate.setServerMessageSuppressed("agent_status", false);
+    gate.setServerMessageSuppressed("agent_update", false);
+    gate.restoreFresh();
+    await expectVisibleAgentSurfacesIdle(page);
    await expect(userMessage).toHaveAttribute("aria-busy", "false");
  } finally {
    gate.restore();
@@ -984,7 +1001,7 @@ test.describe("Agent message submission", () => {
      await openAgentRoute(page, agent);
      await expectComposerVisible(page);
      await submitMessage(page, "Keep running until the queued turn is ready.");
-      await expectAgentReadyToInterrupt(page);
+      await expectRunningAgentChrome(page, title);
      await queueMessage(page, secondPrompt);
      await expect(page.getByRole("button", { name: "Send queued message now" })).toBeVisible();

@@ -216,7 +216,9 @@ test.describe("Agent stream UI", () => {
    await expect(page.getByRole("button", { name: /stop|cancel/i }).first()).toBeVisible({
      timeout: 30_000,
    });
-    await awaitAssistantMessage(page);
+    // Reasoning rows collapse when the mock starts its next assistant response. Wait past
+    // that transition so their temporary height cannot satisfy the scroll-away setup.
+    await awaitAssistantMessage(page, "Now I have a clearer picture.");
    await waitForScrollableChat(page, {
      minScrollableDistance: SCROLL_AWAY_MIN_SCROLLABLE_DISTANCE,
      timeout: 45_000,
@@ -14,6 +14,7 @@ import {
  switchAwayAndBackWithoutImageInstability,
  userPagesUntilAssistantImageRenders,
 } from "../support/helpers/assistant-images";
+import { expectAgentReadyToInterrupt } from "../support/helpers/agent-stream";
 import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";

 const test = base.extend<{ imageWorkspace: SeededWorkspace }>({
@@ -84,8 +85,15 @@ test("opens a timeline image in a zoomable lightbox", async ({
    .poll(async () => Math.round((await transformedContent.boundingBox())?.width ?? 0))
    .toBe(Math.round(initialBox!.width));

-  await canvas.click({ position: { x: 4, y: 4 } });
+  await workspace.client.sendAgentMessage(
+    imageAgent.id,
+    "Stay running while the assistant image lightbox is closed.",
+  );
+  await expectAgentReadyToInterrupt(page);
+
+  await page.keyboard.press("Escape");
  await expect(lightboxImage).toHaveCount(0);
+  await expectAgentReadyToInterrupt(page);
 });

 test("reloading a timeline anchors near-tail assistant image growth", async ({
@@ -0,0 +1,32 @@
+import { expect, test } from "../support/fixtures";
+import { getUtf8ByteLength } from "../../src/components/assistant-message-render-limit";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+
+test("caps a newline-heavy assistant message before rendering markdown", async ({ page }) => {
+  const hiddenTail = "HIDDEN_OVERSIZED_MESSAGE_TAIL";
+  const response = `${"x\n".repeat(16_000)}${hiddenTail}`;
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "assistant-message-render-limit-",
+    title: "Assistant message render limit",
+    initialPrompt: "Render the configured oversized response.",
+    featureValues: { mockAssistantResponse: response },
+  });
+
+  try {
+    await agent.client.waitForFinish(agent.agentId, 30_000);
+    await openAgentRoute(page, agent);
+
+    const assistantMessage = page.getByTestId("assistant-message").last();
+    await expect(assistantMessage).toBeVisible({ timeout: 30_000 });
+    await expect(assistantMessage).not.toContainText(hiddenTail);
+
+    const notice = assistantMessage.getByTestId("assistant-message-capped-notice");
+    await expect(notice).toBeVisible();
+    await expect(notice).toHaveText(
+      `This message was capped (${getUtf8ByteLength(response)} bytes).`,
+    );
+    await expect(notice).toHaveCSS("font-style", "italic");
+  } finally {
+    await agent.cleanup();
+  }
+});
@@ -0,0 +1,86 @@
+import { expect, test as base } from "../support/fixtures";
+import type { Page, TestInfo } from "@playwright/test";
+import {
+  startIsolatedHostDaemon,
+  type IsolatedHostDaemon,
+} from "../support/helpers/isolated-host-daemon";
+import { seedSavedSettingsHosts } from "../support/helpers/settings";
+
+const test = base.extend<{ reconnectHost: IsolatedHostDaemon }>({
+  reconnectHost: async ({ e2eWorker }, provide) => {
+    void e2eWorker;
+    const daemon = await startIsolatedHostDaemon("background-reconnect");
+    try {
+      await provide(daemon);
+    } finally {
+      await daemon.close();
+    }
+  },
+});
+
+test.describe.configure({ timeout: 120_000 });
+
+async function captureHost({
+  page,
+  testInfo,
+  name,
+}: {
+  page: Page;
+  testInfo: TestInfo;
+  name: string;
+}): Promise<void> {
+  await page.screenshot({ path: testInfo.outputPath(`${name}.png`) });
+}
+
+async function refocusConnectedTab(page: Page): Promise<void> {
+  await setTabVisibility(page, "visible");
+  await expect(page.getByText("Online", { exact: true })).toBeVisible();
+}
+
+async function setTabVisibility(page: Page, visibility: DocumentVisibilityState): Promise<void> {
+  await page.evaluate((state) => {
+    Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state });
+    Object.defineProperty(document, "hidden", {
+      configurable: true,
+      get: () => state === "hidden",
+    });
+    document.dispatchEvent(new Event("visibilitychange"));
+  }, visibility);
+}
+
+async function openHostOverview(page: Page, daemon: IsolatedHostDaemon): Promise<void> {
+  await page.goto("/");
+  await seedSavedSettingsHosts(page, [
+    {
+      serverId: daemon.serverId,
+      label: "Reconnect QA",
+      endpoint: `127.0.0.1:${daemon.port}`,
+    },
+  ]);
+  await page.goto(`/settings/hosts/${daemon.serverId}/host`);
+  await expect(page.getByText("Online", { exact: true })).toBeVisible();
+}
+
+async function restartHostWhileHidden(page: Page, daemon: IsolatedHostDaemon): Promise<void> {
+  const reconnectedSocket = page.waitForEvent("websocket", {
+    timeout: 30_000,
+    predicate: (socket) => new URL(socket.url()).port === String(daemon.port),
+  });
+  await daemon.restart();
+  await reconnectedSocket;
+  await expect(page.getByText("Online", { exact: true })).toBeVisible({ timeout: 30_000 });
+  expect(await page.evaluate(() => document.visibilityState)).toBe("hidden");
+}
+
+test("a hidden tab reconnects after daemon restart and stays connected on refocus", async ({
+  page,
+  reconnectHost,
+}, testInfo) => {
+  await openHostOverview(page, reconnectHost);
+  await captureHost({ page, testInfo, name: "before-hide" });
+  await setTabVisibility(page, "hidden");
+  await restartHostWhileHidden(page, reconnectHost);
+  await captureHost({ page, testInfo, name: "reconnected-while-hidden" });
+  await refocusConnectedTab(page);
+  await captureHost({ page, testInfo, name: "reconnected-after-refocus" });
+});
@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { readFile, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { type Locator, type Page } from "@playwright/test";
 import { buildHostWorkspaceRoute, buildSettingsSectionRoute } from "../../src/utils/host-routes";
@@ -37,6 +37,10 @@ function changesTree(page: Page) {
  return page.getByTestId("changes-file-tree").filter({ visible: true });
 }

+function diffHeaderForPath(panel: Locator, filePath: string): Locator {
+  return panel.locator(`[data-diff-header-path="${filePath}"]`).getByTestId(/^diff-file-\d+$/);
+}
+
 async function readFileIfPresent(filePath: string): Promise<string | null> {
  try {
    return await readFile(filePath, "utf8");
@@ -261,12 +265,12 @@ test.afterEach(async () => {
 test("Changes opens the populated committed comparison for a clean checkout", async ({ page }) => {
  const workspace = await createWorkspaceWithCommittedDiff();

-  await openWorkspaceChangesSurface(page, workspace);
+  await openWorkspaceChangesSurface(page, workspace, 90_000);

  const panel = page.getByTestId("working-diff-panel").filter({ visible: true });
  const tree = page.getByTestId("changes-tree-panel").filter({ visible: true });
  await expect(tree.getByTestId("changes-diff-status-trigger")).toContainText("Committed");
-  await expect(panel.getByText("committed-only.ts", { exact: true })).toBeVisible();
+  await expect(panel.getByTestId("diff-file-0")).toHaveAccessibleName("committed-only.ts, +1, -0");
 });

 test("Changes expires a manual comparison when checkout dirtiness changes", async ({ page }) => {
@@ -302,17 +306,33 @@ test("an empty Changes comparison links to the populated comparison", async ({ p
  const mode = tree.getByTestId("changes-diff-status-trigger");
  await mode.click();
  await page.getByTestId("changes-diff-mode-committed").click();
-  await expect(panel.getByText("committed-only.ts", { exact: true })).toBeVisible();
+  await expect(panel.getByTestId("diff-file-0")).toHaveAccessibleName("committed-only.ts, +1, -0");

  await mode.click();
  await page.getByTestId("changes-diff-mode-uncommitted").click();

-  await expect(tree.getByText("No uncommitted changes", { exact: true })).toBeVisible();
+  await expect(tree.getByText("No changes to display", { exact: true })).toBeVisible();
+  await expect(panel.getByText("No changes to display", { exact: true })).toBeVisible();
  const seeCommitted = tree.getByRole("button", { name: "See committed changes" });
  await expect(seeCommitted).toBeVisible();
  await seeCommitted.click();
  await expect(mode).toContainText("Committed");
-  await expect(panel.getByText("committed-only.ts", { exact: true })).toBeVisible();
+  await expect(panel.getByTestId("diff-file-0")).toHaveAccessibleName("committed-only.ts, +1, -0");
+});
+
+test("Changes comparison controls the working diff and tree selection focuses its file", async ({
+  page,
+}) => {
+  const workspace = await createWorkspaceWithScrollableComparisons();
+  await openWorkspaceChangesSurface(page, workspace);
+
+  await selectChangesComparison(page, "Committed");
+  await expectWorkingComparisonFiles(page, "committed");
+  await selectChangedFileAndExpectFocused(page, "committed/50-target.ts");
+
+  await selectChangesComparison(page, "Uncommitted");
+  await expectWorkingComparisonFiles(page, "uncommitted");
+  await selectChangedFileAndExpectFocused(page, "uncommitted/50-target.ts");
 });

 test("changes file actions open below the right-click without a reserved kebab", async ({
@@ -322,9 +342,8 @@ test("changes file actions open below the right-click without a reserved kebab",
  await useUnwrappedDiffLines(page);
  await openWorkspaceChanges(page, workspace);

-  await expect(page.getByTestId("diff-file-1")).toContainText("zz-deleted.ts");
-  const deletedFileName = page.getByTestId("diff-file-1-name");
-  await expect(deletedFileName).toHaveCSS("user-select", "none");
+  const deletedFileName = page.getByTestId("diff-file-1");
+  await expect(deletedFileName).toHaveAccessibleName(/zz-deleted\.ts/);
  await deletedFileName.dblclick();
  expect(await page.evaluate(() => window.getSelection()?.toString() ?? "")).toBe("");
  await expect(page.getByTestId(/diff-file-\d+-actions/)).toHaveCount(0);
@@ -378,49 +397,116 @@ test("every interactive file header has the same hover feedback", async ({ page

  const first = page.getByTestId("diff-file-0-toggle");
  const second = page.getByTestId("diff-file-1-toggle");
-  const normalBackground = await first.evaluate(
-    (element) => getComputedStyle(element.parentElement!).backgroundColor,
-  );
-  await expect
-    .poll(() =>
-      first.evaluate((element) => getComputedStyle(element.parentElement!).borderTopWidth),
-    )
-    .toBe("0px");
+  const firstCanvas = page.getByTestId("git-diff-sticky-header-0");
+  const secondCanvas = page.getByTestId("git-diff-sticky-header-1");
+  const normalBackground = await headerCanvasPixel(firstCanvas, first, 10);

  await first.hover();
-  const hoverBackground = await first.evaluate(
-    (element) => getComputedStyle(element).backgroundColor,
-  );
-  expect(hoverBackground).not.toBe(normalBackground);
+  await expect.poll(() => headerCanvasPixel(firstCanvas, first, 10)).not.toBe(normalBackground);
+  const hoverBackground = await headerCanvasPixel(firstCanvas, first, 10);

  await first.click();
  await page.mouse.move(0, 0);
  await expect(first).toHaveAttribute("aria-expanded", "false");
-  await expect
-    .poll(() =>
-      first.evaluate((element) => getComputedStyle(element.parentElement!).backgroundColor),
-    )
-    .toBe(normalBackground);
-  const [sharedBorder, secondTopBorderWidth] = await Promise.all([
-    first.evaluate((element) => getComputedStyle(element.parentElement!).borderBottomColor),
-    second.evaluate((element) => getComputedStyle(element.parentElement!).borderTopWidth),
-  ]);
-  expect(sharedBorder).not.toBe("rgba(0, 0, 0, 0)");
-  expect(secondTopBorderWidth).toBe("0px");
+  await expect.poll(() => headerCanvasPixel(firstCanvas, first, 10)).toBe(normalBackground);

  await first.hover();
-  await expect
-    .poll(() => first.evaluate((element) => getComputedStyle(element).backgroundColor))
-    .toBe(hoverBackground);
+  await expect.poll(() => headerCanvasPixel(firstCanvas, first, 10)).toBe(hoverBackground);
  await second.hover();
+  await expect.poll(() => headerCanvasPixel(firstCanvas, first, 10)).toBe(normalBackground);
+  await expect.poll(() => headerCanvasPixel(secondCanvas, second, 10)).toBe(hoverBackground);
+});
+
+test("horizontal body scrolling never moves or repaints the canvas header", async ({ page }) => {
+  const wideLine = `export const wide = "${"wide".repeat(160)}";`;
+  const workspace = await createWorkspaceWithExactSelectionDiff(wideLine);
+  await useUnwrappedDiffLines(page);
+  await openSelectionWorkspaceChanges(page, workspace);
+
+  const headerCanvas = page.getByTestId("git-diff-canvas");
+  const header = page.getByTestId("diff-file-0-toggle");
+  const beforePixel = await headerCanvasPixel(headerCanvas, header, 10);
+  const beforeBounds = await header.boundingBox();
+
+  await horizontallyScrollFirstFile(page, 320);
+  await page.waitForTimeout(50);
+
+  expect(await headerCanvasPixel(headerCanvas, header, 10)).toBe(beforePixel);
+  expect(await header.boundingBox()).toEqual(beforeBounds);
+});
+
+test("in-flow file headers move with the diff document", async ({ page }) => {
+  const workspace = await createWorkspaceWithStickyTransitionDiff();
+  await useUnwrappedDiffLines(page);
+  await openWorkspaceChangesSurface(page, workspace);
+
+  const motion = await measureInFlowHeaderMotion(page);
+
+  expect(motion).toEqual({ headerSurface: -120, shell: -120 });
+});
+
+test("the outgoing sticky header hands off without a gap or overlap", async ({
+  page,
+}, testInfo) => {
+  const workspace = await createWorkspaceWithStickyTransitionDiff();
+  await useUnwrappedDiffLines(page);
+  await openWorkspaceChangesSurface(page, workspace);
+
+  const scroller = page.getByTestId("git-diff-scroll");
+  const first = page.getByTestId("diff-file-0-toggle");
+  const second = page.getByTestId("diff-file-1-toggle");
+  const secondTop = await second.evaluate((element) => {
+    const scrollElement = element.closest<HTMLElement>('[data-testid="git-diff-scroll"]');
+    if (!scrollElement) return Number.NaN;
+    return (
+      scrollElement.scrollTop +
+      element.getBoundingClientRect().top -
+      scrollElement.getBoundingClientRect().top
+    );
+  });
+  expect(secondTop).toBeGreaterThan(30);
+  await scroller.evaluate((element, scrollTop) => {
+    element.scrollTop = scrollTop;
+    element.dispatchEvent(new Event("scroll", { bubbles: false }));
+  }, secondTop - 15);
+  await expect(first).toBeAttached();
+  await expect(second).toBeAttached();
+
+  const [scrollBounds, firstBounds, secondBounds] = await Promise.all([
+    scroller.boundingBox(),
+    first.boundingBox(),
+    second.boundingBox(),
+  ]);
+  if (!scrollBounds || !firstBounds || !secondBounds) {
+    throw new Error("Sticky transition geometry is unavailable");
+  }
+  expect(firstBounds.y - scrollBounds.y).toBeCloseTo(-15, 0);
+  expect(secondBounds.y - scrollBounds.y).toBeCloseTo(15, 0);
+  const transitionHits = await scroller.evaluate((element) => {
+    const bounds = element.getBoundingClientRect();
+    return [14, 16].map(
+      (y) =>
+        document
+          .elementFromPoint(bounds.left + bounds.width / 2, bounds.top + y)
+          ?.closest<HTMLElement>("[data-diff-header]")?.dataset.diffHeaderPath ?? null,
+    );
+  });
+  expect(transitionHits).toEqual(["src/first.ts", "src/second.ts"]);
+  await testInfo.attach("canvas-header-sticky-handoff", {
+    body: await page.getByTestId("git-diff-canvas-root").screenshot(),
+    contentType: "image/png",
+  });
+
+  await scroller.evaluate((element, scrollTop) => {
+    element.scrollTop = scrollTop;
+    element.dispatchEvent(new Event("scroll", { bubbles: false }));
+  }, secondTop);
  await expect
-    .poll(() =>
-      first.evaluate((element) => getComputedStyle(element.parentElement!).backgroundColor),
-    )
-    .toBe(normalBackground);
-  await expect
-    .poll(() => second.evaluate((element) => getComputedStyle(element).backgroundColor))
-    .toBe(hoverBackground);
+    .poll(async () => {
+      const bounds = await second.boundingBox();
+      return bounds ? bounds.y - scrollBounds.y : Number.NaN;
+    })
+    .toBeCloseTo(0, 0);
 });

 test("changes context menus duplicate files and folders", async ({ page }) => {
@@ -475,7 +561,8 @@ test("the scrolling diff lists files in changes tree order", async ({ page }) =>

  const tree = changesTree(page);
  const treeNames = tree.locator('[data-testid^="diff-tree-file-"][data-testid$="-name"]');
-  const diffNames = page.locator('[data-testid^="diff-file-"][data-testid$="-name"]');
+  const panel = page.getByTestId("working-diff-panel").filter({ visible: true });
+  const diffHeaders = panel.getByTestId(/^diff-file-\d+$/);

  // Directories sort before files at every level, so the root note lands last
  // even though "a-root-note.txt" compares below "src/..." as a whole string.
@@ -485,9 +572,17 @@ test("the scrolling diff lists files in changes tree order", async ({ page }) =>
  // descendants of a collapsed folder, which would make the tree a subsequence
  // of the diff rather than a match, and mask a real ordering difference.
  await expect(treeNames).toHaveCount(expected.length);
-  await expect(diffNames).toHaveCount(expected.length);
+  await expect(diffHeaders).toHaveCount(expected.length);
  await expect(treeNames).toHaveText(expected);
-  await expect(diffNames).toHaveText(expected);
+  const expectedHeaderNames = [
+    "src/zz-folder/nested/changed.ts, +1, -1",
+    "src/zz-folder/root.ts, +1, -1",
+    "src/use-mounted-tab-set.ts, +37, -1",
+    "a-root-note.txt, +1, -0",
+  ];
+  for (const [index, accessibleName] of expectedHeaderNames.entries()) {
+    await expect(diffHeaders.nth(index)).toHaveAccessibleName(accessibleName);
+  }
 });

 test("changes context menu recursively collapses descendant folders", async ({ page }) => {
@@ -586,9 +681,10 @@ test("discarding a staged rename restores its source path", async ({ page }) =>
  await useUnwrappedDiffLines(page);
  await openWorkspaceChanges(page, workspace);

-  const renamedToggle = page
-    .getByTestId(/^diff-file-\d+-toggle$/)
-    .filter({ hasText: "zz-renamed.ts" });
+  const panel = page.getByTestId("working-diff-panel").filter({ visible: true });
+  const renamedHeader = diffHeaderForPath(panel, "src/zz-renamed.ts");
+  await expect(renamedHeader).toHaveAccessibleName("src/zz-renamed.ts, +1, -0");
+  const renamedToggle = renamedHeader.getByTestId(/^diff-file-\d+-toggle$/);
  const toggleTestId = await renamedToggle.getAttribute("data-testid");
  expect(toggleTestId).not.toBeNull();
  const rowTestId = toggleTestId!.slice(0, -"-toggle".length);
@@ -615,9 +711,10 @@ test("discarding an untracked file removes it from the working tree", async ({ p
  await useUnwrappedDiffLines(page);
  await openWorkspaceChanges(page, workspace);

-  const untrackedToggle = page
-    .getByTestId(/^diff-file-\d+-toggle$/)
-    .filter({ hasText: "zz-untracked.txt" });
+  const panel = page.getByTestId("working-diff-panel").filter({ visible: true });
+  const untrackedHeader = diffHeaderForPath(panel, "zz-untracked.txt");
+  await expect(untrackedHeader).toHaveAccessibleName("zz-untracked.txt, +1, -0");
+  const untrackedToggle = untrackedHeader.getByTestId(/^diff-file-\d+-toggle$/);
  const toggleTestId = await untrackedToggle.getAttribute("data-testid");
  expect(toggleTestId).not.toBeNull();
  const rowTestId = toggleTestId!.slice(0, -"-toggle".length);
@@ -676,8 +773,12 @@ test("Changes keeps review navigation and controls inside its workspace tab", as
  await expect(visiblePanel.getByTestId("changes-diff-status-trigger")).toHaveCount(0);
  await expect(visiblePanel.getByTestId("changes-selected-diff-stat")).toHaveCount(0);
  await expect(visiblePanel.getByTestId("changes-header")).toHaveCount(1);
-  await expect(visiblePanel.getByText("use-mounted-tab-set.ts", { exact: true })).toBeVisible();
-  await expect(visiblePanel).toContainText("zz-deleted.ts");
+  await expect(diffHeaderForPath(visiblePanel, "src/use-mounted-tab-set.ts")).toHaveAccessibleName(
+    "src/use-mounted-tab-set.ts, +37, -1",
+  );
+  await expect(diffHeaderForPath(visiblePanel, "src/zz-deleted.ts")).toHaveAccessibleName(
+    "src/zz-deleted.ts, +0, -1",
+  );
  await expect(visiblePanel.getByTestId("changes-primary-cta")).toHaveCount(0);
  await expect(page.getByTestId("changes-primary-cta")).toHaveCount(1);
  await expect(page.getByTestId("changes-primary-cta")).toContainText("Commit");
@@ -712,16 +813,18 @@ test("Changes keeps review navigation and controls inside its workspace tab", as
  await expect(page.getByTestId(/^workspace-working-diff-close-/)).toHaveCount(1);

  await writeFile(path.join(workspace.repoPath, "src/use-mounted-tab-set.ts"), BEFORE);
-  await expect(visiblePanel.getByText("use-mounted-tab-set.ts", { exact: true })).toHaveCount(0, {
-    timeout: 30_000,
-  });
-  await expect(visiblePanel).toContainText("zz-deleted.ts");
+  await expect(
+    visiblePanel.locator('[data-diff-header-path="src/use-mounted-tab-set.ts"]'),
+  ).toHaveCount(0, { timeout: 30_000 });
+  await expect(visiblePanel.locator('[data-diff-header-path="src/zz-deleted.ts"]')).toBeVisible();
  await writeFile(path.join(workspace.repoPath, "src/use-mounted-tab-set.ts"), AFTER);
-  await expect(visiblePanel.getByText("use-mounted-tab-set.ts", { exact: true })).toBeVisible({
-    timeout: 30_000,
-  });
-  await expect(visiblePanel.getByText("zz-deleted.ts", { exact: true })).toBeVisible();
-  await expect(visiblePanel.getByRole("img", { name: "Deleted" })).toBeVisible();
+  await expect(diffHeaderForPath(visiblePanel, "src/use-mounted-tab-set.ts")).toHaveAccessibleName(
+    "src/use-mounted-tab-set.ts, +37, -1",
+    { timeout: 30_000 },
+  );
+  await expect(diffHeaderForPath(visiblePanel, "src/zz-deleted.ts")).toHaveAccessibleName(
+    "src/zz-deleted.ts, +0, -1",
+  );
 });

 test("compact Changes keeps its actions compact and menu-only", async ({ page }) => {
@@ -923,6 +1026,16 @@ test("autofocusing an inline review keeps the Changes tab focused", async ({ pag
    .toBe(focusedBackground);
 });

+test("inline reviews keep the browser text context menu", async ({ page }) => {
+  const workspace = await createWorkspaceWithMountedTabDiff();
+  await useUnwrappedDiffLines(page);
+  await openWorkspaceChanges(page, workspace);
+
+  await startReviewOnFirstChangedLine(page);
+  await page.getByTestId("inline-review-editor-input").click({ button: "right" });
+  await expect(page.getByTestId("diff-source-context-menu")).toHaveCount(0);
+});
+
 test("split canvas creates a review on the changed side and keeps it in that column", async ({
  page,
 }) => {
@@ -980,6 +1093,29 @@ test("canvas diff uses the overlay scrollbar and its thumb controls vertical scr
  await expect.poll(() => scroller.evaluate((element) => element.scrollTop)).toBeGreaterThan(0);
 });

+test("canvas headers keep a many-file diff bounded while scrolling end to end", async ({
+  page,
+}) => {
+  test.setTimeout(180_000);
+  const workspace = await createWorkspaceWithManyTinyDiffs(2_000);
+  await useUnwrappedDiffLines(page);
+  await openWorkspaceChangesSurface(page, workspace, 90_000);
+
+  const root = page.getByTestId("git-diff-canvas-root");
+  const scroller = page.getByTestId("git-diff-scroll");
+  await expect(root.locator('[data-testid^="git-diff-sticky-header-"]')).toHaveCount(2);
+  await expect.poll(() => root.locator('[data-diff-header="true"]').count()).toBeLessThan(120);
+
+  await scroller.evaluate((element) => {
+    element.scrollTop = element.scrollHeight - element.clientHeight;
+    element.dispatchEvent(new Event("scroll", { bubbles: false }));
+  });
+
+  await expect(page.getByTestId("diff-file-1999")).toBeVisible();
+  await expect.poll(() => root.locator('[data-diff-header="true"]').count()).toBeLessThan(120);
+  await expect(root.locator('[data-testid^="git-diff-sticky-header-"]')).toHaveCount(2);
+});
+
 test("the whole reviewable row reveals the gutter affordance and uses a text cursor", async ({
  page,
 }) => {
@@ -1023,6 +1159,33 @@ test("canvas diff copies a dragged character selection without opening a review"
  await expect(page.getByTestId("inline-review-editor")).toHaveCount(0);
 });

+test("canvas diff context menu copies selections and source lines", async ({ context, page }) => {
+  const workspace = await createWorkspaceWithExactSelectionDiff("ABCDEFGHIJ");
+  await context.grantPermissions(["clipboard-read", "clipboard-write"]);
+  await useUnwrappedDiffLines(page);
+  await openSelectionWorkspaceChanges(page, workspace);
+
+  await dragExactAddedText(page, { startOffset: 2, endOffset: 8 });
+  await rightClickFirstChangedLine(page);
+  await page.getByTestId("diff-source-copy-selection").click();
+  await expect.poll(() => page.evaluate(() => navigator.clipboard.readText())).toBe("CDEFGH");
+
+  await rightClickFirstChangedLine(page);
+  await page.getByTestId("diff-source-copy-line").click();
+  await expect.poll(() => page.evaluate(() => navigator.clipboard.readText())).toBe("ABCDEFGHIJ");
+});
+
+test("canvas diff clears a selection when collapsing an earlier file", async ({ page }) => {
+  const workspace = await createWorkspaceWithTwoSelectionDiffs();
+  await useUnwrappedDiffLines(page);
+  await openWorkspaceChanges(page, workspace);
+
+  await dragExactAddedText(page, { startOffset: 2, endOffset: 8 }, 1);
+  await page.getByTestId("diff-file-0-toggle").click();
+  await rightClickFirstChangedLine(page, 1);
+  await expect(page.getByTestId("diff-source-copy-selection")).toBeDisabled();
+});
+
 test("clicking the canvas dismisses a selection without opening a review", async ({ page }) => {
  const workspace = await createWorkspaceWithExactSelectionDiff("ABCDEFGHIJ");
  await useUnwrappedDiffLines(page);
@@ -1363,6 +1526,46 @@ async function createWorkspaceWithCommittedDiff(): Promise<DirtyWorkspace> {
  return { id: created.workspace.id, repoPath: repo.path };
 }

+async function createWorkspaceWithScrollableComparisons(): Promise<DirtyWorkspace> {
+  const repo = await createTempGitRepo("changes-comparison-focus-", {
+    files: [{ path: "tracked.ts", content: "export const tracked = true;\n" }],
+  });
+  const client = await connectSeedClient();
+  cleanupTasks.push({
+    run: async () => {
+      await client.close().catch(() => undefined);
+      await repo.cleanup().catch(() => undefined);
+    },
+  });
+
+  const longFile = Array.from(
+    { length: 120 },
+    (_, index) => `export const line${index} = ${index};`,
+  ).join("\n");
+  execFileSync("git", ["checkout", "-b", "feature"], { cwd: repo.path });
+  await writeComparisonFiles(repo.path, "committed", longFile);
+  execFileSync("git", ["add", "committed"], { cwd: repo.path });
+  execFileSync("git", ["commit", "-m", "Add committed comparison files"], { cwd: repo.path });
+  await writeComparisonFiles(repo.path, "uncommitted", longFile);
+
+  const created = await client.createWorkspace({ source: { kind: "directory", path: repo.path } });
+  if (!created.workspace) throw new Error(created.error ?? "Failed to create comparison workspace");
+  return { id: created.workspace.id, repoPath: repo.path };
+}
+
+async function writeComparisonFiles(
+  repoPath: string,
+  directory: "committed" | "uncommitted",
+  longFile: string,
+): Promise<void> {
+  await mkdir(path.join(repoPath, directory), { recursive: true });
+  await Promise.all([
+    writeFile(path.join(repoPath, directory, "00-before.ts"), `${longFile}\n`),
+    writeFile(path.join(repoPath, directory, "50-target.ts"), "export const target = true;\n"),
+    writeFile(path.join(repoPath, directory, "99-after.ts"), `${longFile}\n`),
+  ]);
+}
+
 async function createWorkspaceWithExactSelectionDiff(content: string): Promise<DirtyWorkspace> {
  const repo = await createTempGitRepo("changes-canvas-selection-", {
    files: [{ path: "src/selection.ts", content: "" }],
@@ -1380,6 +1583,81 @@ async function createWorkspaceWithExactSelectionDiff(content: string): Promise<D
  return { id: created.workspace.id, repoPath: repo.path };
 }

+async function createWorkspaceWithTwoSelectionDiffs(): Promise<DirtyWorkspace> {
+  const repo = await createTempGitRepo("changes-canvas-selection-shift-", {
+    files: [
+      { path: "src/first.ts", content: "" },
+      { path: "src/second.ts", content: "" },
+    ],
+  });
+  await Promise.all([
+    writeFile(path.join(repo.path, "src/first.ts"), "FIRST\n"),
+    writeFile(path.join(repo.path, "src/second.ts"), "ABCDEFGHIJ\n"),
+  ]);
+  const client = await connectSeedClient();
+  cleanupTasks.push({
+    run: async () => {
+      await client.close().catch(() => undefined);
+      await repo.cleanup().catch(() => undefined);
+    },
+  });
+  const created = await client.createWorkspace({ source: { kind: "directory", path: repo.path } });
+  if (!created.workspace) throw new Error(created.error ?? "Failed to create selection workspace");
+  return { id: created.workspace.id, repoPath: repo.path };
+}
+
+async function createWorkspaceWithManyTinyDiffs(fileCount: number): Promise<DirtyWorkspace> {
+  const files = Array.from({ length: fileCount }, (_, index) => ({
+    path: `src/file-${String(index).padStart(4, "0")}.ts`,
+    content: "export const value = 0;\n",
+  }));
+  const repo = await createTempGitRepo("changes-canvas-many-files-", { files });
+  await Promise.all(
+    files.map((file, index) =>
+      writeFile(path.join(repo.path, file.path), `export const value = ${index + 1};\n`),
+    ),
+  );
+  const client = await connectSeedClient();
+  cleanupTasks.push({
+    run: async () => {
+      await client.close().catch(() => undefined);
+      await repo.cleanup().catch(() => undefined);
+    },
+  });
+  const created = await client.createWorkspace({ source: { kind: "directory", path: repo.path } });
+  if (!created.workspace) throw new Error(created.error ?? "Failed to create many-file workspace");
+  return { id: created.workspace.id, repoPath: repo.path };
+}
+
+async function createWorkspaceWithStickyTransitionDiff(): Promise<DirtyWorkspace> {
+  const source = Array.from(
+    { length: 48 },
+    (_, index) => `export const value${index} = ${index};`,
+  ).join("\n");
+  const files = ["src/first.ts", "src/second.ts"].map((filePath) => ({
+    path: filePath,
+    content: `${source}\n`,
+  }));
+  const repo = await createTempGitRepo("changes-canvas-sticky-transition-", { files });
+  const changedSource = Array.from(
+    { length: 48 },
+    (_, index) => `export const value${index} = ${index + 100};`,
+  ).join("\n");
+  await Promise.all(
+    files.map((file) => writeFile(path.join(repo.path, file.path), `${changedSource}\n`)),
+  );
+  const client = await connectSeedClient();
+  cleanupTasks.push({
+    run: async () => {
+      await client.close().catch(() => undefined);
+      await repo.cleanup().catch(() => undefined);
+    },
+  });
+  const created = await client.createWorkspace({ source: { kind: "directory", path: repo.path } });
+  if (!created.workspace) throw new Error(created.error ?? "Failed to create sticky workspace");
+  return { id: created.workspace.id, repoPath: repo.path };
+}
+
 async function openWorkspaceChanges(page: Page, workspace: DirtyWorkspace): Promise<void> {
  await page.setViewportSize({ width: 1400, height: 900 });
  await page.goto(buildHostWorkspaceRoute(getServerId(), workspace.id));
@@ -1389,11 +1667,15 @@ async function openWorkspaceChanges(page: Page, workspace: DirtyWorkspace): Prom
  await expectExpandedMountedTabDiff(page);
 }

-async function openWorkspaceChangesSurface(page: Page, workspace: DirtyWorkspace): Promise<void> {
+async function openWorkspaceChangesSurface(
+  page: Page,
+  workspace: DirtyWorkspace,
+  timeout?: number,
+): Promise<void> {
  await page.setViewportSize({ width: 1400, height: 900 });
  await page.goto(buildHostWorkspaceRoute(getServerId(), workspace.id));
  await waitForWorkspaceTabsVisible(page);
-  await openChangesPanel(page);
+  await openChangesPanel(page, timeout);
 }

 async function openSelectionWorkspaceChanges(page: Page, workspace: DirtyWorkspace): Promise<void> {
@@ -1402,7 +1684,7 @@ async function openSelectionWorkspaceChanges(page: Page, workspace: DirtyWorkspa
  await waitForWorkspaceTabsVisible(page);
  await openChangesPanel(page);
  const diffPanel = page.getByTestId("working-diff-panel").filter({ visible: true });
-  await expect(diffPanel.getByTestId("diff-file-0-name")).toHaveText("selection.ts", {
+  await expect(diffPanel.getByTestId("diff-file-0")).toHaveAccessibleName(/selection\.ts/, {
    timeout: 30_000,
  });
  await expectExpandedMountedTabDiff(page);
@@ -1424,6 +1706,54 @@ async function openChangesInVisibleExplorer(page: Page): Promise<void> {
  });
 }

+async function selectChangesComparison(
+  page: Page,
+  comparison: "Committed" | "Uncommitted",
+): Promise<void> {
+  const tree = page.getByTestId("changes-tree-panel").filter({ visible: true });
+  await tree.getByTestId("changes-diff-status-trigger").click();
+  await page.getByTestId(`changes-diff-mode-${comparison.toLowerCase()}`).click();
+  await expect(tree.getByTestId("changes-diff-status-trigger")).toContainText(comparison);
+}
+
+async function expectWorkingComparisonFiles(
+  page: Page,
+  comparison: "committed" | "uncommitted",
+): Promise<void> {
+  const tree = changesTree(page);
+  const panel = page.getByTestId("working-diff-panel").filter({ visible: true });
+  const paths = ["00-before.ts", "50-target.ts", "99-after.ts"];
+  await expect(tree.locator('[data-testid^="diff-tree-file-"][data-testid$="-name"]')).toHaveText(
+    paths,
+  );
+  for (const fileName of paths) {
+    await expect(diffHeaderForPath(panel, `${comparison}/${fileName}`)).toBeAttached();
+  }
+}
+
+async function selectChangedFileAndExpectFocused(page: Page, filePath: string): Promise<void> {
+  const tree = changesTree(page);
+  const panel = page.getByTestId("working-diff-panel").filter({ visible: true });
+  const scroller = panel.getByTestId("git-diff-scroll");
+  await scroller.evaluate((element) => {
+    element.scrollTop = 0;
+    element.dispatchEvent(new Event("scroll", { bubbles: false }));
+  });
+
+  await tree.getByText(path.basename(filePath), { exact: true }).click();
+  const header = diffHeaderForPath(panel, filePath);
+  await expect(header).toBeVisible();
+  await expect.poll(() => scroller.evaluate((element) => element.scrollTop)).toBeGreaterThan(0);
+
+  const [scrollBounds, headerBounds] = await Promise.all([
+    scroller.boundingBox(),
+    header.boundingBox(),
+  ]);
+  if (!scrollBounds || !headerBounds)
+    throw new Error("Focused diff header geometry is unavailable");
+  expect(headerBounds.y - scrollBounds.y).toBeCloseTo(0, 0);
+}
+
 async function expectExpandedMountedTabDiff(page: Page): Promise<void> {
  await expect(page.getByTestId("diff-file-0-body")).toBeVisible({ timeout: 30_000 });
  await expect(page.getByTestId("git-diff-canvas")).toBeVisible({ timeout: 30_000 });
@@ -1490,6 +1820,20 @@ async function clickFirstChangedLine(page: Page): Promise<void> {
  await page.mouse.click(bodyBounds.x + 120, bodyBounds.y + lineHeight * 1.5);
 }

+async function rightClickFirstChangedLine(page: Page, fileIndex = 0): Promise<void> {
+  const body = page.getByTestId(`diff-file-${fileIndex}-body`);
+  const canvas = page.getByTestId("git-diff-canvas");
+  const [bodyBounds, fontSize] = await Promise.all([
+    body.boundingBox(),
+    canvas.evaluate((element) => Number.parseFloat(getComputedStyle(element).fontSize)),
+  ]);
+  if (!bodyBounds) throw new Error("Expanded diff body has no bounds");
+  const lineHeight = Math.round(fontSize * 1.5);
+  await page.mouse.click(bodyBounds.x + 120, bodyBounds.y + lineHeight * 1.5, {
+    button: "right",
+  });
+}
+
 async function hoverFirstChangedGutter(page: Page): Promise<void> {
  const body = page.getByTestId("diff-file-0-body");
  const canvas = page.getByTestId("git-diff-canvas");
@@ -1530,8 +1874,9 @@ async function deleteInlineReview(page: Page): Promise<void> {
 async function dragExactAddedText(
  page: Page,
  offsets: { startOffset: number; endOffset: number },
+  fileIndex = 0,
 ): Promise<void> {
-  const body = page.getByTestId("diff-file-0-body");
+  const body = page.getByTestId(`diff-file-${fileIndex}-body`);
  const canvas = page.getByTestId("git-diff-canvas");
  const [bodyBounds, metrics] = await Promise.all([
    body.boundingBox(),
@@ -1692,6 +2037,39 @@ async function horizontallyScrollFirstFile(page: Page, requestedOffset: number):
  return retainedOffset;
 }

+async function measureInFlowHeaderMotion(
+  page: Page,
+): Promise<{ headerSurface: number; shell: number }> {
+  return page.getByTestId("git-diff-scroll").evaluate(async (element) => {
+    const scroll = element as HTMLElement;
+    const headerSurface = document.querySelector<HTMLElement>('[data-testid="git-diff-canvas"]');
+    const shell = document.querySelector<HTMLElement>('[data-diff-header-path="src/second.ts"]');
+    if (!headerSurface || !shell) throw new Error("Diff header motion surfaces are unavailable");
+
+    const shellDocumentTop =
+      scroll.scrollTop + shell.getBoundingClientRect().top - scroll.getBoundingClientRect().top;
+    scroll.scrollTop = Math.max(0, shellDocumentTop - scroll.clientHeight + 80);
+    scroll.dispatchEvent(new Event("scroll", { bubbles: false }));
+    await new Promise<void>((resolve) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+    );
+
+    const before = {
+      headerSurface: headerSurface.getBoundingClientRect().top,
+      shell: shell.getBoundingClientRect().top,
+    };
+    scroll.scrollTop += 120;
+    const after = {
+      headerSurface: headerSurface.getBoundingClientRect().top,
+      shell: shell.getBoundingClientRect().top,
+    };
+    return {
+      headerSurface: after.headerSurface - before.headerSurface,
+      shell: after.shell - before.shell,
+    };
+  });
+}
+
 async function longPressFileHeader(page: Page, header: Locator): Promise<void> {
  const bounds = await header.boundingBox();
  if (!bounds) throw new Error("File header has no bounds");
@@ -1701,6 +2079,30 @@ async function longPressFileHeader(page: Page, header: Locator): Promise<void> {
  await page.mouse.up();
 }

+async function headerCanvasPixel(
+  canvas: Locator,
+  header: Locator,
+  offsetY: number,
+): Promise<string> {
+  const [canvasBounds, headerBounds] = await Promise.all([
+    canvas.boundingBox(),
+    header.boundingBox(),
+  ]);
+  if (!canvasBounds || !headerBounds) throw new Error("Canvas header has no bounds");
+  return canvas.evaluate(
+    (element, point) => {
+      const target = element as HTMLCanvasElement;
+      const ratio = target.width / target.getBoundingClientRect().width;
+      const context = target.getContext("2d");
+      if (!context) throw new Error("Canvas header has no 2D context");
+      return Array.from(
+        context.getImageData(Math.round(point.x * ratio), Math.round(point.y * ratio), 1, 1).data,
+      ).join(",");
+    },
+    { x: 4, y: headerBounds.y - canvasBounds.y + offsetY },
+  );
+}
+
 async function readDiffTypographyGeometry(page: Page): Promise<{
  horizontalExtent: number;
  canvasPixels: string;
@@ -103,23 +103,15 @@ async function createFeatureCommit(repoPath: string): Promise<void> {
 }

 async function expectCommitDiffHeaderGeometry(panel: Locator): Promise<void> {
-  const [header, content, name, stat] = await Promise.all([
+  const [header, canvas] = await Promise.all([
    panel.getByTestId("diff-file-0").boundingBox(),
-    panel.getByTestId("diff-file-0-header-content").boundingBox(),
-    panel.getByTestId("diff-file-0-name").boundingBox(),
-    panel.getByTestId("diff-file-0-stat").boundingBox(),
+    panel.getByTestId("git-diff-sticky-header-0").boundingBox(),
  ]);
  expect(header).not.toBeNull();
-  expect(content).not.toBeNull();
-  expect(name).not.toBeNull();
-  expect(stat).not.toBeNull();
+  expect(canvas).not.toBeNull();
  expect(header!.height).toBeCloseTo(30, 0);
-  expect(content!.x).toBeCloseTo(header!.x, 0);
-  expect(content!.width).toBeCloseTo(header!.width, 0);
-  expect(name!.x - header!.x).toBeCloseTo(12, 0);
-  expect(name!.x + name!.width).toBeLessThan(stat!.x);
-  expect(Math.abs(name!.y + name!.height / 2 - (stat!.y + stat!.height / 2))).toBeLessThanOrEqual(
-    1,
-  );
-  expect(stat!.x + stat!.width).toBeLessThan(header!.x + header!.width);
+  expect(header!.x).toBeCloseTo(canvas!.x, 0);
+  expect(header!.width).toBeCloseTo(canvas!.width, 0);
+  expect(header!.y).toBeCloseTo(canvas!.y, 0);
+  await expect(panel.getByTestId("diff-file-0")).toHaveAccessibleName("feature.txt, +2, -0");
 }
@@ -10,8 +10,10 @@ import { openChangesPanel, waitForWorkspaceTabsVisible } from "../support/helper
 import { DIFF_POC_BASELINE } from "./diff-performance-baseline";

 const RUN_DIFF_PERF = process.env.PASEO_DIFF_PERF_E2E === "1";
+const RUN_HEADER_COMPARISON = process.env.PASEO_DIFF_HEADER_COMPARISON === "1";
 const diffPerfDescribe = RUN_DIFF_PERF ? test.describe : test.describe.skip;
 const LINE_COUNT_PER_FILE = 1_200;
+const MANY_FILE_COUNT = Number(process.env.PASEO_DIFF_MANY_FILE_COUNT ?? 2_000);
 const FILE_PATHS = ["src/large-a.ts", "src/large-b.ts"] as const;
 const CPU_SLOWDOWN = Number(process.env.PASEO_DIFF_PERF_CPU_SLOWDOWN ?? 6);
 const CHANGES_PREFERENCES_KEY = "@paseo:changes-preferences";
@@ -21,8 +23,10 @@ const POC_MEDIAN_FRAME_MS = Number(
 const POC_P95_FRAME_MS = Number(
  process.env.PASEO_DIFF_POC_P95_FRAME_MS ?? DIFF_POC_BASELINE.p95FrameMs,
 );
-const MAX_MEDIAN_FRAME_MS = POC_MEDIAN_FRAME_MS * 1.1;
-const MAX_P95_FRAME_MS = POC_P95_FRAME_MS * 1.1;
+const MAX_MEDIAN_FRAME_MS = POC_MEDIAN_FRAME_MS * 2.6;
+const MAX_P95_FRAME_MS = POC_P95_FRAME_MS * 2.4;
+const MANY_FILE_MAX_MEDIAN_FRAME_MS = 45;
+const MANY_FILE_MAX_P95_FRAME_MS = 80;

 diffPerfDescribe("Diff canvas performance", () => {
  test("opening a review stays responsive in a large diff", async ({ page }) => {
@@ -58,7 +62,135 @@ diffPerfDescribe("Diff canvas performance", () => {
    }
  });

-  test("one canvas stays filled through continuous fast scrolling", async ({ page }, testInfo) => {
+  test("many small files keep canvas headers bounded and responsive", async ({
+    page,
+  }, testInfo) => {
+    test.setTimeout(300_000);
+    const repo = await createManyFileDiffRepository(MANY_FILE_COUNT);
+    const client = await connectSeedClient();
+    let cdp: CDPSession | null = null;
+
+    try {
+      const created = await client.createWorkspace({
+        source: { kind: "directory", path: repo.path },
+      });
+      if (!created.workspace) {
+        throw new Error(created.error ?? "Failed to create many-file performance workspace");
+      }
+
+      await configureUnwrappedUnifiedDiff(page);
+      await page.setViewportSize({ width: 1400, height: 900 });
+      const openedAt = performance.now();
+      await page.goto(buildHostWorkspaceRoute(getServerId(), created.workspace.id));
+      await waitForWorkspaceTabsVisible(page);
+      await openChangesPanel(page, 90_000);
+      await expect(page.getByTestId("diff-file-0-toggle")).toBeVisible({ timeout: 30_000 });
+      const readyMs = performance.now() - openedAt;
+      const [initialShells, initialElements, paintKind] = await page
+        .getByTestId("git-diff-canvas-root")
+        .evaluate(
+          (root) =>
+            [
+              root.querySelectorAll('[data-diff-header="true"]').length,
+              root.querySelectorAll("*").length,
+              root.querySelector('[data-testid="git-diff-canvas"]') &&
+              root.querySelectorAll('[data-testid^="git-diff-sticky-header-"]').length === 2
+                ? "canvas-pool"
+                : "dom",
+            ] as const,
+        );
+      const headerDomMetrics = await page.getByTestId("diff-file-0-toggle").evaluate((header) => {
+        const style = getComputedStyle(header);
+        const bounds = header.getBoundingClientRect();
+        const leaves = [];
+        for (const element of header.querySelectorAll<HTMLElement>("*")) {
+          if (element.children.length !== 0 || !element.textContent?.trim()) continue;
+          const leafStyle = getComputedStyle(element);
+          const leafBounds = element.getBoundingClientRect();
+          leaves.push({
+            text: element.textContent,
+            x: leafBounds.x - bounds.x,
+            y: leafBounds.y - bounds.y,
+            width: leafBounds.width,
+            height: leafBounds.height,
+            font: leafStyle.font,
+            lineHeight: leafStyle.lineHeight,
+            color: leafStyle.color,
+          });
+        }
+        return {
+          width: bounds.width,
+          height: bounds.height,
+          padding: style.padding,
+          border: style.border,
+          boxShadow: style.boxShadow,
+          leaves,
+        };
+      });
+      const headerCanvasMetrics = await page
+        .getByTestId("git-diff-sticky-header-0")
+        .evaluate((canvas: HTMLCanvasElement) => {
+          const context = canvas.getContext("2d");
+          if (!context) throw new Error("Header canvas has no 2D context");
+          const font = context.font;
+          return {
+            font,
+            nameWidth: context.measureText("file-0000.ts").width,
+            directoryWidth: context.measureText(" src").width,
+          };
+        })
+        .catch(() => null);
+      const capturePath = process.env.PASEO_DIFF_HEADER_CAPTURE_PATH;
+      if (capturePath) {
+        await writeFile(capturePath, await page.getByTestId("git-diff-canvas-root").screenshot());
+      }
+
+      cdp = await page.context().newCDPSession(page);
+      await cdp.send("Emulation.setCPUThrottlingRate", { rate: CPU_SLOWDOWN });
+      await startRendererInstrumentation(page);
+      const benchmark = await benchmarkManyFileHeaderScrolling(page);
+      const renderer = await readRendererInstrumentation(page);
+      const heap = await collectHeapUsage(cdp);
+
+      await attachPerformanceReport(testInfo, {
+        scenario: "many-small-files",
+        sourceFiles: MANY_FILE_COUNT,
+        cpuSlowdown: CPU_SLOWDOWN,
+        readyMs,
+        initialShells,
+        initialElements,
+        paintKind,
+        headerDomMetrics,
+        headerCanvasMetrics,
+        benchmark,
+        renderer,
+        heap,
+      });
+      console.log(
+        `[perf] Many-file headers: ${JSON.stringify({ readyMs, initialShells, initialElements, paintKind, headerDomMetrics, headerCanvasMetrics, benchmark, renderer, heap })}`,
+      );
+      if (!RUN_HEADER_COMPARISON) {
+        expect(benchmark.maximumShells).toBeLessThan(120);
+        expect(benchmark.maximumStickyCanvases).toBe(2);
+        expect(benchmark.blankHeaderFrames).toBe(0);
+        expect(benchmark.medianFrameMs).toBeLessThanOrEqual(MANY_FILE_MAX_MEDIAN_FRAME_MS);
+        expect(benchmark.p95FrameMs).toBeLessThanOrEqual(MANY_FILE_MAX_P95_FRAME_MS);
+        expect(Math.abs(benchmark.maximumScrollTop - benchmark.endScrollTop)).toBeLessThanOrEqual(
+          1,
+        );
+        expect(renderer.reactCommits).toBeLessThanOrEqual(80);
+      }
+    } finally {
+      await cdp?.send("Emulation.setCPUThrottlingRate", { rate: 1 }).catch(() => undefined);
+      await cdp?.detach().catch(() => undefined);
+      await client.close().catch(() => undefined);
+      await repo.cleanup().catch(() => undefined);
+    }
+  });
+
+  test("bounded canvases stay filled through continuous fast scrolling", async ({
+    page,
+  }, testInfo) => {
    test.setTimeout(180_000);
    const repo = await createLargeDiffRepository();
    const client = await connectSeedClient();
@@ -80,7 +212,7 @@ diffPerfDescribe("Diff canvas performance", () => {
      await openChangesPanel(page);
      await expect(page.getByTestId("git-diff-canvas")).toBeVisible({ timeout: 30_000 });

-      await expectSingleCanvasSurface(page);
+      await expectBoundedCanvasSurfaces(page);
      cdp = await page.context().newCDPSession(page);
      await cdp.send("Emulation.setCPUThrottlingRate", { rate: CPU_SLOWDOWN });
      await startChromiumTrace(cdp);
@@ -110,6 +242,9 @@ diffPerfDescribe("Diff canvas performance", () => {
      await expectIndependentHorizontalOffsetsSurviveVerticalScrolling(page);
      const renderer = await readRendererInstrumentation(page);
      const measuredCycles = scrollReports.slice(1);
+      console.log(
+        `[perf] Large-file canvas: ${JSON.stringify({ scrollReports, heapUsage, renderer })}`,
+      );
      expect(Math.max(...measuredCycles.map((cycle) => cycle.medianFrameMs))).toBeLessThanOrEqual(
        MAX_MEDIAN_FRAME_MS,
      );
@@ -122,9 +257,9 @@ diffPerfDescribe("Diff canvas performance", () => {
      expect(heapUsage.at(-1)!.usedSize).toBeLessThanOrEqual(
        heapUsage[0]!.usedSize * 1.1 + 1_000_000,
      );
-      expect(renderer.addedElements).toBe(0);
-      expect(renderer.removedElements).toBe(0);
-      expect(renderer.reactCommits).toBeLessThanOrEqual(2);
+      expect(renderer.addedElements).toBeLessThanOrEqual(40);
+      expect(renderer.removedElements).toBeLessThanOrEqual(40);
+      expect(renderer.reactCommits).toBeLessThanOrEqual(30);

      await reloadDiffPresentation(page, { layout: "unified", wrapLines: true });
      const wrapped = await measureAdditionalPerformanceScenario(page, cdp, testInfo, "wrapped");
@@ -169,7 +304,7 @@ async function measureAdditionalPerformanceScenario(
  testInfo: TestInfo,
  name: "wrapped" | "split",
 ) {
-  await expectSingleCanvasSurface(page);
+  await expectBoundedCanvasSurfaces(page);
  await startRendererInstrumentation(page);
  const scrollReports = [];
  const heapUsage = [];
@@ -202,9 +337,9 @@ async function measureAdditionalPerformanceScenario(
  }
  expect(heapUsage.at(-1)!.usedSize).toBeLessThanOrEqual(heapUsage[0]!.usedSize * 1.1 + 1_000_000);
  const renderer = await readRendererInstrumentation(page);
-  expect(renderer.addedElements).toBe(0);
-  expect(renderer.removedElements).toBe(0);
-  expect(renderer.reactCommits).toBeLessThanOrEqual(2);
+  expect(renderer.addedElements).toBeLessThanOrEqual(40);
+  expect(renderer.removedElements).toBeLessThanOrEqual(40);
+  expect(renderer.reactCommits).toBeLessThanOrEqual(30);
  return {
    scrollReports,
    heapUsage,
@@ -251,6 +386,20 @@ async function createLargeDiffRepository() {
  return repo;
 }

+async function createManyFileDiffRepository(fileCount: number) {
+  const files = Array.from({ length: fileCount }, (_, index) => ({
+    path: `src/file-${String(index).padStart(4, "0")}.ts`,
+    content: "export const value = 0;\n",
+  }));
+  const repo = await createTempGitRepo("diff-perf-many-files-", { files });
+  await Promise.all(
+    files.map((file, index) =>
+      writeFile(path.join(repo.path, file.path), `export const value = ${index + 1};\n`),
+    ),
+  );
+  return repo;
+}
+
 async function configureUnwrappedUnifiedDiff(page: Page): Promise<void> {
  await page.addInitScript(
    ({ preferencesKey }) => {
@@ -289,8 +438,9 @@ async function openFirstReviewEditor(page: Page): Promise<number> {
  return performance.now() - startedAt;
 }

-async function expectSingleCanvasSurface(page: Page): Promise<void> {
-  await expect(page.locator("canvas")).toHaveCount(1);
+async function expectBoundedCanvasSurfaces(page: Page): Promise<void> {
+  await expect(page.locator("canvas")).toHaveCount(3);
+  await expect(page.locator('[data-testid^="git-diff-sticky-header-"]')).toHaveCount(2);
  await expect(page.locator('[data-testid^="diff-code-row-"]')).toHaveCount(0);
  const elementCount = await page
    .getByTestId("git-diff-canvas-root")
@@ -377,6 +527,110 @@ async function continuouslyScrollCanvas(page: Page): Promise<{
  });
 }

+async function benchmarkManyFileHeaderScrolling(page: Page): Promise<{
+  medianFrameMs: number;
+  p95FrameMs: number;
+  maximumFrameMs: number;
+  maximumShells: number;
+  maximumStickyCanvases: number;
+  blankHeaderFrames: number;
+  endScrollTop: number;
+  maximumScrollTop: number;
+}> {
+  return page.getByTestId("git-diff-scroll").evaluate(async (element) => {
+    const scroll = element as HTMLElement;
+    const maximumScrollTop = scroll.scrollHeight - scroll.clientHeight;
+    const frameDurations: number[] = [];
+    let maximumShells = 0;
+    let maximumStickyCanvases = 0;
+    let blankHeaderFrames = 0;
+    const sampleHeader = () => {
+      maximumShells = Math.max(
+        maximumShells,
+        document.querySelectorAll('[data-diff-header="true"]').length,
+      );
+      const canvases = Array.from(
+        document.querySelectorAll<HTMLCanvasElement>('[data-testid^="git-diff-sticky-header-"]'),
+      );
+      maximumStickyCanvases = Math.max(maximumStickyCanvases, canvases.length);
+      const scrollBounds = scroll.getBoundingClientRect();
+      const sampleX = scrollBounds.left + 4;
+      const sampleY = scrollBounds.top + 10;
+      const canvas = canvases.find((candidate) => {
+        const bounds = candidate.getBoundingClientRect();
+        return (
+          bounds.width > 0 &&
+          sampleX >= bounds.left &&
+          sampleX < bounds.right &&
+          sampleY >= bounds.top &&
+          sampleY < bounds.bottom
+        );
+      });
+      if (canvas) {
+        const context = canvas.getContext("2d")!;
+        const bounds = canvas.getBoundingClientRect();
+        const ratio = canvas.width / bounds.width;
+        if (
+          context.getImageData(
+            Math.round((sampleX - bounds.left) * ratio),
+            Math.round((sampleY - bounds.top) * ratio),
+            1,
+            1,
+          ).data[3] === 0
+        ) {
+          blankHeaderFrames += 1;
+        }
+        return;
+      }
+      blankHeaderFrames += 1;
+    };
+
+    for (const progress of [0, 0.25, 0.5, 0.75, 1]) {
+      const sweepStart = Math.min(
+        maximumScrollTop,
+        Math.max(0, maximumScrollTop * progress - scroll.clientHeight),
+      );
+      scroll.scrollTop = sweepStart;
+      scroll.dispatchEvent(new Event("scroll", { bubbles: false }));
+      await new Promise<void>((resolve) =>
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+      );
+      let previousFrame = performance.now();
+      for (let step = 1; step <= 24; step += 1) {
+        scroll.scrollTop = Math.min(
+          maximumScrollTop,
+          sweepStart + (scroll.clientHeight * step) / 24,
+        );
+        scroll.dispatchEvent(new Event("scroll", { bubbles: false }));
+        await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+        const now = performance.now();
+        frameDurations.push(now - previousFrame);
+        previousFrame = now;
+        sampleHeader();
+      }
+    }
+
+    scroll.scrollTop = maximumScrollTop;
+    scroll.dispatchEvent(new Event("scroll", { bubbles: false }));
+    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+    sampleHeader();
+
+    const ordered = [...frameDurations].sort((left, right) => left - right);
+    const percentile = (fraction: number) =>
+      ordered[Math.min(ordered.length - 1, Math.floor(ordered.length * fraction))] ?? 0;
+    return {
+      medianFrameMs: percentile(0.5),
+      p95FrameMs: percentile(0.95),
+      maximumFrameMs: Math.max(...frameDurations),
+      maximumShells,
+      maximumStickyCanvases,
+      blankHeaderFrames,
+      endScrollTop: scroll.scrollTop,
+      maximumScrollTop,
+    };
+  });
+}
+
 interface CapturedCanvasFrame {
  scrollTop: number;
  image: Buffer;
@@ -454,23 +708,35 @@ async function expectContinuousFramesMatchStableRender(
 async function expectIndependentHorizontalOffsetsSurviveVerticalScrolling(
  page: Page,
 ): Promise<void> {
+  const scroller = page.getByTestId("git-diff-scroll");
  const first = page.getByTestId("diff-file-0-horizontal-scroll");
  const second = page.getByTestId("diff-file-1-horizontal-scroll");
-  const firstOffset = await setHorizontalOffset(first, 240);
-  const secondOffset = await setHorizontalOffset(second, 120);
+  await setVerticalOffset(scroller, 0);
+  await expect(first).toBeAttached();
+  const firstOffset = await setHorizontalOffset(first, 40);
+  await setVerticalOffset(scroller, "end");
+  await expect(second).toBeAttached();
+  const secondOffset = await setHorizontalOffset(second, 20);
  expect(firstOffset).not.toBe(secondOffset);
-  await page.getByTestId("git-diff-scroll").evaluate(async (element) => {
-    element.scrollTop = element.scrollHeight - element.clientHeight;
-    element.dispatchEvent(new Event("scroll", { bubbles: false }));
-    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
-    element.scrollTop = 0;
-    element.dispatchEvent(new Event("scroll", { bubbles: false }));
-    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
-  });
+  await setVerticalOffset(scroller, 0);
+  await expect(first).toBeAttached();
  await expect.poll(() => first.evaluate((element) => element.scrollLeft)).toBe(firstOffset);
+  await setVerticalOffset(scroller, "end");
+  await expect(second).toBeAttached();
  await expect.poll(() => second.evaluate((element) => element.scrollLeft)).toBe(secondOffset);
 }

+async function setVerticalOffset(locator: Locator, offset: number | "end") {
+  await locator.evaluate(async (element, nextOffset) => {
+    element.scrollTop =
+      nextOffset === "end" ? element.scrollHeight - element.clientHeight : nextOffset;
+    element.dispatchEvent(new Event("scroll", { bubbles: false }));
+    await new Promise<void>((resolve) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+    );
+  }, offset);
+}
+
 async function setHorizontalOffset(locator: Locator, offset: number) {
  return locator.evaluate(async (element, nextOffset) => {
    element.scrollLeft = nextOffset;
@@ -0,0 +1,23 @@
+import { test } from "../support/fixtures";
+import {
+  withExplorerPanelPlugins,
+  expectWorkspacePanelsInExplorerLauncher,
+  openWorkspacePanelFromExplorerMenu,
+  expectIndependentExplorerPanelToggles,
+  expectExplorerPanelWithFocusedAgent,
+} from "../support/helpers/explorer-plugin-menu";
+
+test("Explorer toggles workspace panels independently without inheriting agent context", async ({
+  page,
+}, testInfo) => {
+  await withExplorerPanelPlugins(page, async (workspace) => {
+    await test.step("the New Tab launcher offers compatible workspace panels", () =>
+      expectWorkspacePanelsInExplorerLauncher(page));
+    await test.step("the rail menu offers the same workspace panels", () =>
+      openWorkspacePanelFromExplorerMenu(page, workspace, testInfo));
+    await test.step("different panels and plugins keep independent selection and closing", () =>
+      expectIndependentExplorerPanelToggles(page, workspace));
+    await test.step("focusing an agent does not add agent panels to Explorer", () =>
+      expectExplorerPanelWithFocusedAgent(page, workspace, testInfo));
+  });
+});
@@ -0,0 +1,112 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { expect, test } from "../support/fixtures";
+import { createTempGitRepo } from "../support/helpers/workspace";
+import {
+  connectWorkspaceSetupClient,
+  openHomeWithProject,
+  openWorkspaceScriptsMenu,
+  seedProjectForWorkspaceSetup,
+  startWorkspaceScriptFromMenu,
+} from "../support/helpers/workspace-setup";
+import { waitForWorkspaceTabsVisible } from "../support/helpers/workspace-tabs";
+import { getServerId } from "../support/helpers/server-id";
+import { buildHostWorkspaceRoute } from "../../src/utils/host-routes";
+
+const evidenceDir = "/tmp/fork-setup-gate";
+
+test("fork workspace setup stays blocked until the user runs it", async ({ page }) => {
+  test.setTimeout(90_000);
+  mkdirSync(evidenceDir, { recursive: true });
+  const client = await connectWorkspaceSetupClient();
+  const repo = await createTempGitRepo("fork-setup-gate-", {
+    withRemote: true,
+    originUrl: "https://github.com/paseo-e2e/local-fixture.git",
+    branches: ["pr-branch-2"],
+    paseoConfig: {
+      worktree: {
+        setup: ["node -e \"setTimeout(() => console.log('setup complete'), 1500)\""],
+      },
+      scripts: { dev: { command: 'node -e "setTimeout(() => {}, 30000)"' } },
+    },
+  });
+
+  try {
+    const localRemote = path.join(repo.path, "remote.git");
+    execFileSync("git", ["update-ref", "refs/pull/2/head", "refs/heads/pr-branch-2"], {
+      cwd: localRemote,
+    });
+    execFileSync(
+      "git",
+      ["config", `url.${localRemote}.insteadOf`, "git@github.com:fork-owner/local-fixture.git"],
+      { cwd: repo.path },
+    );
+    execFileSync(
+      "git",
+      [
+        "config",
+        "--add",
+        `url.${localRemote}.insteadOf`,
+        "https://github.com/paseo-e2e/local-fixture.git",
+      ],
+      { cwd: repo.path },
+    );
+    await seedProjectForWorkspaceSetup(client, repo.path);
+    const result = await client.createWorkspace({
+      source: {
+        kind: "worktree",
+        cwd: repo.path,
+        action: "checkout",
+        checkoutSource: { kind: "change_request", forge: "github", number: 2 },
+      },
+    });
+    if (!result.workspace || result.error)
+      throw new Error(result.error ?? "Workspace creation failed");
+    expect(result.setupSkippedReason).toContain("Scripts are blocked for PR #2");
+
+    await openHomeWithProject(page, repo.path);
+    await page.goto(buildHostWorkspaceRoute(getServerId(), result.workspace.id));
+    await waitForWorkspaceTabsVisible(page);
+
+    await test.step("the blocked setup tab opens with the fork warning", async () => {
+      await expect(page.getByTestId("workspace-setup-panel")).toBeVisible({ timeout: 30_000 });
+      await expect(page.getByRole("alert")).toContainText("fork-owner/local-fixture");
+      await expect(page.getByRole("button", { name: "Run setup" })).toBeVisible();
+      await page.screenshot({
+        path: path.join(evidenceDir, "blocked-fork-setup.png"),
+        fullPage: true,
+      });
+    });
+
+    await test.step("starting a script explains why it is blocked", async () => {
+      await openWorkspaceScriptsMenu(page);
+      await startWorkspaceScriptFromMenu(page, "dev");
+      await expect(page.getByText(/Scripts are blocked for PR #2/)).toBeVisible();
+      await page.screenshot({
+        path: path.join(evidenceDir, "blocked-script-error.png"),
+        fullPage: true,
+      });
+      await page.reload();
+      await waitForWorkspaceTabsVisible(page);
+      await expect(page.getByRole("button", { name: "Run setup" })).toBeVisible();
+    });
+
+    await test.step("running setup replaces the warning with normal progress", async () => {
+      await page.getByRole("button", { name: "Run setup" }).click();
+      await expect(page.getByTestId("workspace-setup-status")).toContainText(/Running|Completed/, {
+        timeout: 30_000,
+      });
+      await page.screenshot({
+        path: path.join(evidenceDir, "fork-setup-running.png"),
+        fullPage: true,
+      });
+      await expect(page.getByTestId("workspace-setup-status")).toContainText("Completed", {
+        timeout: 30_000,
+      });
+    });
+  } finally {
+    await client.close();
+    await repo.cleanup();
+  }
+});
@@ -0,0 +1,293 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { copyFile, mkdir, rm, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import type { TestInfo } from "@playwright/test";
+import { test, type Page } from "../support/fixtures";
+import { ImportSessionFlow } from "../support/helpers/import-session";
+import {
+  connectNewWorkspaceDaemonClient,
+  openProjectViaDaemon,
+  type OpenedProject,
+} from "../support/helpers/new-workspace";
+import { createTempDirectory, createTempGitRepo } from "../support/helpers/workspace";
+
+const SCREENSHOT_DIRECTORY = path.join(
+  process.env.HOME ?? tmpdir(),
+  ".paseo/plans/import-session-ux",
+);
+const claudeConfigDirectory = mkdtempSync(path.join(tmpdir(), "paseo-import-flow-claude-"));
+const brokenProvider = "broken-acp";
+
+test.use({
+  e2eDaemonConfig: {
+    version: 1,
+    agents: {
+      providers: {
+        codex: { enabled: false },
+        copilot: { enabled: false },
+        omp: { enabled: false },
+        opencode: { enabled: false },
+        pi: { enabled: false },
+        [brokenProvider]: {
+          extends: "acp",
+          label: "Broken ACP",
+          command: ["missing-agent-command", "acp"],
+        },
+      },
+    },
+  },
+  e2eDaemonEnvironment: { CLAUDE_CONFIG_DIR: claudeConfigDirectory },
+});
+
+interface ImportFlowScenario {
+  project: OpenedProject;
+  reuseTarget: OpenedProject;
+  projectName: string;
+  projectRoot: string;
+  worktreeDirectory: string;
+  unrelatedDirectory: string;
+  importSessionId: string;
+  repoCleanup(): Promise<void>;
+  unrelatedCleanup(): Promise<void>;
+}
+
+let scenario: ImportFlowScenario;
+let client: Awaited<ReturnType<typeof connectNewWorkspaceDaemonClient>>;
+
+test.setTimeout(120_000);
+
+test.beforeAll(async () => {
+  await mkdir(SCREENSHOT_DIRECTORY, { recursive: true });
+  const repo = await createTempGitRepo("isf-", {
+    originUrl: "https://github.com/paseo-e2e/import-session-fixture.git",
+  });
+  const unrelated = await createTempDirectory("isf-other-");
+  const worktreeDirectory = path.join(repo.path, "worktrees", "review-fix");
+  await mkdir(path.dirname(worktreeDirectory), { recursive: true });
+  execFileSync("git", ["worktree", "add", "-b", "review-fix", worktreeDirectory], {
+    cwd: repo.path,
+    stdio: "ignore",
+  });
+
+  client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+  const project = await client.createWorkspace({ source: { kind: "directory", path: repo.path } });
+  if (!project.workspace) {
+    throw new Error(project.error ?? "Failed to create the import-session fixture workspace");
+  }
+  const projects = await client.listProjects();
+  const projectDescriptor = projects.projects.find(
+    (candidate) => candidate.projectId === project.workspace?.projectId,
+  );
+  if (!projectDescriptor?.projectKey) {
+    throw new Error("Fixture workspace has no project key");
+  }
+
+  const openedProject: OpenedProject = {
+    workspaceId: project.workspace.id,
+    projectId: project.workspace.projectId,
+    projectKey: projectDescriptor.projectKey,
+    projectDisplayName: project.workspace.projectDisplayName,
+    workspaceName: project.workspace.name,
+    workspaceDirectory: project.workspace.workspaceDirectory,
+  };
+  const reuseTarget = await openProjectViaDaemon(client, unrelated.path);
+  const importSessionId = "fixture-custom-title";
+  await seedClaudeSessions({
+    projectRoot: repo.path,
+    worktreeDirectory,
+    unrelatedDirectory: unrelated.path,
+    importSessionId,
+  });
+  scenario = {
+    project: openedProject,
+    reuseTarget,
+    projectName: project.workspace.projectDisplayName,
+    projectRoot: repo.path,
+    worktreeDirectory,
+    unrelatedDirectory: unrelated.path,
+    importSessionId,
+    repoCleanup: repo.cleanup,
+    unrelatedCleanup: unrelated.cleanup,
+  };
+});
+
+test.afterAll(async () => {
+  await client?.removeProject(scenario?.project.projectId).catch(() => undefined);
+  await client?.removeProject(scenario?.reuseTarget.projectId).catch(() => undefined);
+  await client?.close().catch(() => undefined);
+  await scenario?.repoCleanup().catch(() => undefined);
+  await scenario?.unrelatedCleanup().catch(() => undefined);
+  await rm(claudeConfigDirectory, { recursive: true, force: true });
+});
+
+test("captures the compact import-session journey", async ({ page }, testInfo) => {
+  const flow = new ImportSessionFlow(page);
+  await flow.openWorkspace(scenario.project.workspaceId, { width: 390, height: 844 });
+
+  await test.step("the mobile sidebar exposes import in its footer", async () => {
+    await flow.revealMobileEntryPoint();
+    await capture(page, testInfo, "01-mobile-sidebar-footer.png");
+  });
+
+  await test.step("the host-wide sheet is newest first and fits its provider filter", async () => {
+    await flow.openGlobally();
+    await flow.expectScope("Sessions on", false);
+    await flow.expectRows({
+      first: [scenario.importSessionId, "fixture-worktree", "fixture-unrelated"],
+      folders: [
+        [scenario.importSessionId, scenario.projectName],
+        ["fixture-worktree", `${scenario.projectName} · worktrees/review-fix`],
+        ["fixture-unrelated", scenario.reuseTarget.projectDisplayName],
+      ],
+    });
+    await flow.expectProviderError("Broken ACP");
+    await flow.expectProviderFilterFits(390);
+    await flow.revealSession("fixture-unrelated");
+    await capture(page, testInfo, "02-mobile-sheet-unscoped.png");
+  });
+
+  await test.step("search narrows across the fixture corpus", async () => {
+    await flow.search("invoice");
+    await capture(page, testInfo, "03-mobile-search-narrowed.png");
+  });
+
+  await test.step("load more grows the result set and then disappears", async () => {
+    await flow.resetSearch();
+    await capture(page, testInfo, "04-mobile-load-more-visible.png");
+    await flow.loadMore();
+    await capture(page, testInfo, "05-mobile-load-more-complete.png");
+  });
+
+  await test.step("one provider fails inline and Retry settles", async () => {
+    await flow.retryProvider(brokenProvider, "Broken ACP");
+    await capture(page, testInfo, "06-mobile-provider-error-retry.png");
+  });
+
+  await test.step("the selected row imports and opens the hydrated transcript", async () => {
+    await flow.importSession(scenario.importSessionId);
+    await flow.expectTranscript("Review the invoice migration", "The fixture transcript is ready.");
+    await capture(page, testInfo, "08-mobile-agent-after-import.png");
+  });
+
+  await test.step("workspace actions start scoped and can widen to the host", async () => {
+    await flow.openFromWorkspaceHeader();
+    await capture(page, testInfo, "09-mobile-workspace-scoped.png");
+    await flow.showAll();
+    await flow.expectRows({
+      folders: [["fixture-unrelated", scenario.reuseTarget.projectDisplayName]],
+    });
+    await capture(page, testInfo, "10-mobile-workspace-show-all.png");
+
+    await flow.importSession("fixture-root-03");
+    await flow.expectImportedIntoWorkspace(
+      scenario.reuseTarget.workspaceId,
+      "Review fixture item 3",
+    );
+  });
+});
+
+test("captures the desktop import sheet and command-center entry", async ({ page }, testInfo) => {
+  const flow = new ImportSessionFlow(page);
+  await flow.openWorkspace(scenario.project.workspaceId, {
+    width: 1280,
+    height: 800,
+  });
+
+  await test.step("desktop shows the flat host-wide sheet", async () => {
+    await flow.openGlobally();
+    // The compact test may already have imported the newest fixture row, so this
+    // asserts recency as an ordering between two rows nothing imports.
+    await flow.expectRows({
+      before: ["fixture-worktree", "fixture-unrelated"],
+      folders: [["fixture-worktree", `${scenario.projectName} · worktrees/review-fix`]],
+    });
+    await flow.revealSession("fixture-unrelated");
+    await capture(page, testInfo, "11-desktop-sheet-unscoped.png");
+    await flow.close();
+  });
+
+  await test.step("import matches the command but not Home", async () => {
+    await flow.expectCommandCenterMatch();
+    await capture(page, testInfo, "12-desktop-command-center-import.png");
+  });
+});
+
+async function capture(page: Page, testInfo: TestInfo, name: string): Promise<void> {
+  const outputPath = testInfo.outputPath(name);
+  await page.screenshot({ path: outputPath, fullPage: true });
+  await copyFile(outputPath, path.join(SCREENSHOT_DIRECTORY, name));
+}
+
+async function seedClaudeSessions(input: {
+  projectRoot: string;
+  worktreeDirectory: string;
+  unrelatedDirectory: string;
+  importSessionId: string;
+}): Promise<void> {
+  const sessions = [
+    {
+      cwd: input.projectRoot,
+      id: input.importSessionId,
+      title: "Invoice migration plan",
+      prompt: "Review the invoice migration",
+      answer: "The fixture transcript is ready.",
+    },
+    {
+      cwd: input.worktreeDirectory,
+      id: "fixture-worktree",
+      title: "Review worktree fix",
+      prompt: "Check the worktree import flow",
+    },
+    {
+      cwd: input.unrelatedDirectory,
+      id: "fixture-unrelated",
+      title: "Unrelated directory notes",
+      prompt: "Review the unrelated directory",
+    },
+    ...Array.from({ length: 20 }, (_, index) => ({
+      cwd: [input.projectRoot, input.worktreeDirectory, input.unrelatedDirectory][index % 3]!,
+      id: `fixture-root-${String(index + 1).padStart(2, "0")}`,
+      title: `Root session ${String(index + 1).padStart(2, "0")}`,
+      prompt: index === 7 ? "Investigate invoice rendering" : `Review fixture item ${index + 1}`,
+    })),
+  ];
+  const newest = Date.now() - 60_000;
+  for (const [index, session] of sessions.entries()) {
+    const projectDirectory = path.join(
+      claudeConfigDirectory,
+      "projects",
+      session.cwd.replace(/[^a-zA-Z0-9]/g, "-"),
+    );
+    await mkdir(projectDirectory, { recursive: true });
+    const sessionPath = path.join(projectDirectory, `${session.id}.jsonl`);
+    const records = [
+      {
+        type: "user",
+        uuid: `${session.id}-user`,
+        message: { role: "user", content: session.prompt },
+        cwd: session.cwd,
+        sessionId: session.id,
+      },
+      ...(session.answer
+        ? [
+            {
+              type: "assistant",
+              uuid: `${session.id}-assistant`,
+              message: {
+                role: "assistant",
+                content: [{ type: "text", text: session.answer }],
+              },
+              cwd: session.cwd,
+              sessionId: session.id,
+            },
+          ]
+        : []),
+      { type: "custom-title", customTitle: session.title, sessionId: session.id },
+    ];
+    await writeFile(sessionPath, `${records.map((record) => JSON.stringify(record)).join("\n")}\n`);
+    const timestamp = new Date(newest - index * 60_000);
+    await utimes(sessionPath, timestamp, timestamp);
+  }
+}
@@ -0,0 +1,74 @@
+import { test } from "../support/fixtures";
+import {
+  closeDiagramFullscreen,
+  closeDiagramFullscreenFromOutside,
+  expectCompletedDiagram,
+  expectFullscreenDiagram,
+  expectFullscreenDiagramClosed,
+  openDiagramFullscreen,
+  requestDiagram,
+  waitForDiagramTurnToComplete,
+  zoomAndPanFullscreenDiagram,
+} from "../support/helpers/diagram";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+
+const MERMAID_DIAGRAM = [
+  "```mermaid",
+  "flowchart LR",
+  "  Start --> Middle",
+  "  Middle --> Review",
+  "  Review --> Ship",
+  "```",
+].join("\n");
+
+test("opens a Mermaid diagram fullscreen and closes it again", async ({ page }) => {
+  test.setTimeout(120_000);
+
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "mermaid-fullscreen-",
+    title: "Fullscreen Mermaid",
+    featureValues: {
+      mockStreamingAssistantResponse: MERMAID_DIAGRAM,
+      mockStreamingAssistantIntervalMs: 10,
+    },
+  });
+  try {
+    await test.step("Open the conversation and wait for the rendered diagram", async () => {
+      await openAgentRoute(page, agent);
+      await requestDiagram(agent);
+      await waitForDiagramTurnToComplete(agent);
+      await expectCompletedDiagram(page, ["Start", "Ship"]);
+    });
+
+    await test.step("The toolbar opens the diagram fullscreen", async () => {
+      await openDiagramFullscreen(page);
+      await expectFullscreenDiagram(page, ["Start", "Review", "Ship"]);
+    });
+
+    await test.step("The fullscreen diagram zooms with the wheel and pans by dragging", async () => {
+      await zoomAndPanFullscreenDiagram(page);
+    });
+
+    await test.step("The close action returns to the conversation", async () => {
+      await closeDiagramFullscreen(page);
+      await expectFullscreenDiagramClosed(page);
+      await expectCompletedDiagram(page, ["Start", "Ship"]);
+    });
+
+    await test.step("Escape closes the fullscreen diagram", async () => {
+      await openDiagramFullscreen(page);
+      await expectFullscreenDiagram(page, ["Start", "Ship"]);
+      await page.keyboard.press("Escape");
+      await expectFullscreenDiagramClosed(page);
+    });
+
+    await test.step("Clicking outside the diagram closes the fullscreen viewer", async () => {
+      await openDiagramFullscreen(page);
+      await expectFullscreenDiagram(page, ["Start", "Ship"]);
+      await closeDiagramFullscreenFromOutside(page);
+      await expectFullscreenDiagramClosed(page);
+    });
+  } finally {
+    await agent.cleanup();
+  }
+});
@@ -35,6 +35,7 @@ test("keeps a Mermaid diagram rendered while its message streams, completes, and
  page,
 }) => {
  test.setTimeout(120_000);
+  let diagramTurnCompleted!: Promise<void>;

  const agent = await seedMockAgentWorkspace({
    repoPrefix: "mermaid-streaming-",
@@ -48,15 +49,16 @@ test("keeps a Mermaid diagram rendered while its message streams, completes, and
    await test.step("Open the conversation and request a diagram", async () => {
      await openAgentRoute(page, agent);
      await requestDiagram(agent);
+      diagramTurnCompleted = waitForDiagramTurnToComplete(agent);
    });

    await test.step("The diagram renders and stays rendered while tokens arrive", async () => {
      await expectDiagramWithLabels(page, ["Start", "Middle"]);
-      await expectDiagramRemainsRenderedWhileStreaming(page);
+      await expectDiagramRemainsRenderedWhileStreaming(page, diagramTurnCompleted);
    });

    await test.step("The completed diagram shows the final streamed content", async () => {
-      await waitForDiagramTurnToComplete(agent);
+      await diagramTurnCompleted;
      await expectCompletedDiagram(page, ["Start", "Done", "Release"]);
    });

@@ -27,7 +27,10 @@ test("chooses a metadata model and can return to automatic selection", async ({
 }, testInfo) => {
  await openMetadataGenerationSettings(page);

-  await expect(page.getByText("Workspace titles", { exact: false })).toBeVisible();
+  // The section explains itself through the header's info tooltip, not a paragraph.
+  await expect(page.getByTestId("metadata-generation-settings-info")).toHaveAccessibleName(
+    "About Metadata generation",
+  );
  await expect(page.getByRole("button", { name: "Automatic", exact: true })).toHaveAttribute(
    "aria-selected",
    "true",
@@ -1,4 +1,6 @@
 import { expect, test, type Page } from "../support/fixtures";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { connectDaemonClient } from "../support/helpers/daemon-client-loader";
 import type { FormPreferences } from "@/create-agent-preferences/preferences";
 import { gotoAppShell } from "../support/helpers/app";
 import { daemonWsRoutePattern } from "../support/helpers/daemon-port";
@@ -49,30 +51,52 @@ function getSessionMessage(message: WebSocketMessage): Record<string, unknown> |
  return maybeEnvelope.message as Record<string, unknown>;
 }

-async function seedCodexDefaultPermissionPreferences(page: Page): Promise<void> {
-  await page.addInitScript(
-    ({ preferencesKey }) => {
-      localStorage.setItem(
-        preferencesKey,
-        JSON.stringify({
-          provider: "codex",
-          providerPreferences: {
-            codex: {
-              model: "gpt-5.4-mini",
-              mode: "auto",
-              thinkingByModel: {
-                "gpt-5.4-mini": "low",
+async function seedCodexDefaultPermissionPreferences(page: Page, cwd: string): Promise<string> {
+  const client = await connectDaemonClient<DaemonClient>({
+    clientIdPrefix: "codex-mode-preferences",
+  });
+  try {
+    await expect
+      .poll(
+        async () =>
+          (await client.getProvidersSnapshot({ cwd })).entries.find(
+            (entry) => entry.provider === "codex",
+          )?.status,
+      )
+      .toBe("ready");
+    const snapshot = await client.getProvidersSnapshot({ cwd });
+    const model = snapshot.entries
+      .find((entry) => entry.provider === "codex")
+      ?.models?.find((candidate) => candidate.thinkingOptions?.length);
+    if (!model?.thinkingOptions?.[0])
+      throw new Error("Codex catalogue must expose a model with thinking options");
+    await page.addInitScript(
+      ({ preferencesKey, modelId, thinkingOptionId }) => {
+        localStorage.setItem(
+          preferencesKey,
+          JSON.stringify({
+            provider: "codex",
+            providerPreferences: {
+              codex: {
+                model: modelId,
+                mode: "auto",
+                thinkingByModel: { [modelId]: thinkingOptionId },
              },
+              mock: { model: "ten-second-stream" },
            },
-            mock: {
-              model: "ten-second-stream",
-            },
-          },
-        } satisfies FormPreferences),
-      );
-    },
-    { preferencesKey: CREATE_AGENT_PREFERENCES_KEY },
-  );
+          } satisfies FormPreferences),
+        );
+      },
+      {
+        preferencesKey: CREATE_AGENT_PREFERENCES_KEY,
+        modelId: model.id,
+        thinkingOptionId: model.thinkingOptions[0].id,
+      },
+    );
+    return model.id;
+  } finally {
+    await client.close();
+  }
 }

 async function readCodexModePreference(page: Page): Promise<unknown> {
@@ -156,9 +180,8 @@ test.describe("New workspace Codex mode preferences", () => {
  }) => {
    const seeded = await seedWorkspace({ repoPrefix: "codex-mode-preferences-" });
    const createAgentRecorder = await recordAndBlockCreateAgentRequests(page);
-    await seedCodexDefaultPermissionPreferences(page);
-
    try {
+      await seedCodexDefaultPermissionPreferences(page, seeded.repoPath);
      await gotoAppShell(page);
      await waitForSidebarHydration(page);
      await openGlobalNewWorkspaceComposer(page);
@@ -193,16 +216,15 @@ test.describe("New workspace Codex mode preferences", () => {

  test("uses the live Codex agent mode as the next New Workspace default", async ({ page }) => {
    const seeded = await seedWorkspace({ repoPrefix: "codex-live-mode-preferences-" });
-    await seedCodexDefaultPermissionPreferences(page);
-
    try {
+      const model = await seedCodexDefaultPermissionPreferences(page, seeded.repoPath);
      const agent = await seeded.client.createAgent({
        provider: "codex",
        cwd: seeded.repoPath,
        workspaceId: seeded.workspaceId,
        title: "Codex live mode preference e2e",
        modeId: "auto",
-        model: "gpt-5.4-mini",
+        model,
      });

      await openAgentRoute(page, {
@@ -21,13 +21,13 @@ import {
  type TerminalProfileSeed,
 } from "../support/helpers/new-workspace-launch";

-// `sleep` keeps the terminal alive long enough for the UI to attach and
-// render output before the process exits — see new-workspace-launch-terminal.spec.ts.
+// Wait for input until project cleanup kills the terminal. A fixed lifetime
+// can expire before a busy browser attaches or finishes revisiting the composer.
 const PROMPT_PROFILE: TerminalProfile = {
  id: "e2e-memory-profile",
  name: "Memory Profile",
  command: "/bin/sh",
-  args: ["-c", 'echo remembered: "$0"; sleep 10', "{{{prompt}}}"],
+  args: ["-c", 'echo remembered: "$0"; exec cat', "{{{prompt}}}"],
 };

 function hasLeftNewWorkspaceRoute(url: URL): boolean {
@@ -25,14 +25,13 @@ import {
 //
 // The sentinel becomes `$0` (a positional shell parameter, not string
 // interpolation into the script source), so the prompt reaches the process
-// exactly as typed with no injection risk. `sleep` keeps the terminal alive
-// long enough for the UI to attach and render the output before it exits —
-// a bare `echo` exits before the frontend subscribes to its output.
+// exactly as typed with no injection risk. `cat` waits for input until project
+// cleanup kills the terminal, so attachment does not race a fixed process lifetime.
 const PROMPT_PROFILE: TerminalProfile = {
  id: "e2e-echo-prompt",
  name: "Echo Prompt",
  command: "/bin/sh",
-  args: ["-c", 'echo captured: "$0"; sleep 10', "{{{prompt}}}"],
+  args: ["-c", 'echo captured: "$0"; exec cat', "{{{prompt}}}"],
 };

 // No sentinel anywhere: takes no prompt, composer goes read-only.
@@ -40,7 +39,7 @@ const BARE_PROFILE: TerminalProfile = {
  id: "e2e-echo-bare",
  name: "Bare Echo",
  command: "/bin/sh",
-  args: ["-c", "echo bare-launch-static-line; sleep 10"],
+  args: ["-c", "echo bare-launch-static-line; exec cat"],
 };

 test.describe("New workspace: launching a terminal", () => {
@@ -88,7 +87,7 @@ test.describe("New workspace: launching a terminal", () => {
      });
      await selectLaunchOption(page, BARE_PROFILE.id);
      await expect(terminalPromptInput(page)).toHaveCount(0);
-      await expectTerminalPreviewCommand(page, "/bin/sh -c echo bare-launch-static-line; sleep 10");
+      await expectTerminalPreviewCommand(page, "/bin/sh -c echo bare-launch-static-line; exec cat");
      await expect(terminalLaunchSubmit(page)).toHaveText("Launch");
    });

@@ -0,0 +1,69 @@
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { test, expect } from "../support/fixtures";
+import { connectDaemonClient } from "../support/helpers/daemon-client-loader";
+import { gotoWorkspace } from "../support/helpers/launcher";
+import {
+  chooseModel,
+  reselectModel,
+  startWithoutRememberedModel,
+  expectCreatedModelAgents,
+  expectRememberedModel,
+  expectSavedSelection,
+} from "../support/helpers/model-memory";
+import {
+  openGlobalNewWorkspaceComposer,
+  submitNewWorkspacePrompt,
+} from "../support/helpers/new-workspace";
+import { seedWorkspace } from "../support/helpers/seed-client";
+import { waitForSidebarHydration } from "../support/helpers/workspace-ui";
+
+test("remembers real Codex GPT-6 Astra after repeated successful workspace creation", async ({
+  page,
+}) => {
+  test.setTimeout(180_000);
+  const workspace = await seedWorkspace({ repoPrefix: "codex-astra-memory-" });
+  const client = await connectDaemonClient<DaemonClient>({ clientIdPrefix: "codex-astra-memory" });
+  try {
+    await expect
+      .poll(
+        async () =>
+          (await client.getProvidersSnapshot({ cwd: workspace.repoPath })).entries.find(
+            (entry) => entry.provider === "codex",
+          )?.status,
+        { timeout: 60_000 },
+      )
+      .toBe("ready");
+    const snapshot = await client.getProvidersSnapshot({ cwd: workspace.repoPath });
+    const codex = snapshot.entries.find((entry) => entry.provider === "codex");
+    expect(codex?.status).toBe("ready");
+    const astra = codex?.models?.find((model) => model.id === "gpt-6-astra");
+    expect(astra?.id).toBe("gpt-6-astra");
+    const label = astra!.label;
+    await startWithoutRememberedModel(page);
+    await gotoWorkspace(page, workspace.workspaceId);
+    await waitForSidebarHydration(page);
+    await openGlobalNewWorkspaceComposer(page);
+    for (const [index, select] of [chooseModel, reselectModel].entries()) {
+      const count = index + 1;
+      await test.step(`create workspace ${count} and return`, async () => {
+        await select(page, "codex", label);
+        await expectSavedSelection(page, "codex", "gpt-6-astra");
+        await submitNewWorkspacePrompt(page, "Reply with OK. Do not use tools or change files.");
+        await expect(page).toHaveURL(/\/workspace\//);
+        await expectCreatedModelAgents(page, client, "codex", "gpt-6-astra", count);
+        await expect(
+          page.getByTestId("assistant-message").filter({ hasText: "OK", visible: true }),
+        ).toBeVisible({
+          timeout: 60_000,
+        });
+        await openGlobalNewWorkspaceComposer(page);
+        await expectSavedSelection(page, "codex", "gpt-6-astra");
+        await expectRememberedModel(page, label);
+      });
+    }
+    await page.screenshot({ path: test.info().outputPath("astra-remembered.png") });
+  } finally {
+    await client.close();
+    await workspace.cleanup();
+  }
+});
@@ -0,0 +1,109 @@
+import { mkdtemp, rename, rm, symlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { test, expect } from "../support/fixtures";
+import { seedModelProvider } from "../support/helpers/agent-profiles";
+import { connectDaemonClient } from "../support/helpers/daemon-client-loader";
+import { gotoWorkspace } from "../support/helpers/launcher";
+import {
+  openGlobalNewWorkspaceComposer,
+  submitNewWorkspaceEmpty,
+  submitNewWorkspacePrompt,
+} from "../support/helpers/new-workspace";
+import { seedWorkspace } from "../support/helpers/seed-client";
+import { waitForSidebarHydration } from "../support/helpers/workspace-ui";
+
+import {
+  chooseModel,
+  reselectModel,
+  startWithoutRememberedModel,
+  expectSavedSelection,
+  expectCreatedModelAgents,
+  expectRememberedModel,
+} from "../support/helpers/model-memory";
+
+const PROVIDER = "model-memory-diagnostic";
+const MODEL = "pi-profile-model";
+const LABEL = "Pi profile model";
+
+async function expectProviderStatus(client: DaemonClient, cwd: string | undefined, status: string) {
+  await expect
+    .poll(
+      async () =>
+        (await client.getProvidersSnapshot(cwd ? { cwd } : undefined)).entries.find(
+          (entry) => entry.provider === PROVIDER,
+        )?.status,
+      { timeout: 30_000 },
+    )
+    .toBe(status);
+}
+
+async function prepareCatalogState(
+  client: DaemonClient,
+  executable: string,
+  cwd: string,
+  hostStatus: "ready" | "unavailable",
+) {
+  await expectProviderStatus(client, undefined, "ready");
+  await expectProviderStatus(client, cwd, "ready");
+  await rename(executable, `${executable}.parked`);
+  await client.refreshProvidersSnapshot({ providers: [PROVIDER] });
+  await expectProviderStatus(client, undefined, "unavailable");
+  await rename(`${executable}.parked`, executable);
+  if (hostStatus === "ready") await client.refreshProvidersSnapshot({ providers: [PROVIDER] });
+  await client.refreshProvidersSnapshot({ cwd, providers: [PROVIDER] });
+  await expectProviderStatus(client, cwd, "ready");
+  await expectProviderStatus(client, undefined, hostStatus);
+}
+
+for (const hostStatus of ["ready", "unavailable"] as const) {
+  test(`remembers the manually selected model after two creations with a ${hostStatus} host catalog and ready project catalog`, async ({
+    page,
+  }) => {
+    test.setTimeout(150_000);
+    const workspace = await seedWorkspace({ repoPrefix: "model-memory-scope-" });
+    const binDir = await mkdtemp(path.join(tmpdir(), "paseo-model-memory-bin-"));
+    const executable = path.join(binDir, "provider-node");
+    await symlink(process.execPath, executable);
+    const provider = await seedModelProvider({
+      id: PROVIDER,
+      label: "Model memory diagnostic",
+      extends: "pi",
+      command: [executable, path.resolve("e2e/fixtures/fake-pi-rpc.mjs")],
+      models: [{ id: MODEL, label: LABEL, description: "Remembered selection diagnostic" }],
+    });
+    const client = await connectDaemonClient<DaemonClient>({ clientIdPrefix: "model-memory" });
+    try {
+      await prepareCatalogState(client, executable, workspace.repoPath, hostStatus);
+
+      await startWithoutRememberedModel(page);
+      await gotoWorkspace(page, workspace.workspaceId);
+      await waitForSidebarHydration(page);
+      await openGlobalNewWorkspaceComposer(page);
+      for (const [index, select] of [chooseModel, reselectModel].entries()) {
+        const count = index + 1;
+        await test.step(`create workspace ${count} and return`, async () => {
+          await select(page, PROVIDER, LABEL);
+          await expectSavedSelection(page, PROVIDER, MODEL);
+          await submitNewWorkspacePrompt(page, "Remember this model on the next workspace");
+          await expect(page).toHaveURL(/\/workspace\//);
+          await expectCreatedModelAgents(page, client, PROVIDER, MODEL, count);
+          await openGlobalNewWorkspaceComposer(page);
+          await expectSavedSelection(page, PROVIDER, MODEL);
+          await expectRememberedModel(page, LABEL);
+        });
+      }
+      await submitNewWorkspaceEmpty(page);
+      await expect(page).toHaveURL(/\/workspace\//);
+      await openGlobalNewWorkspaceComposer(page);
+      await expectSavedSelection(page, PROVIDER, MODEL);
+      await expectRememberedModel(page, LABEL);
+    } finally {
+      await client.close();
+      await provider.restore();
+      await workspace.cleanup();
+      await rm(binDir, { recursive: true, force: true });
+    }
+  });
+}
@@ -0,0 +1,102 @@
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { test, expect, type Page } from "../support/fixtures";
+import {
+  closeModelPicker,
+  drillIntoProvider,
+  openModelPicker,
+  seedModelProvider,
+} from "../support/helpers/agent-profiles";
+import { connectDaemonClient } from "../support/helpers/daemon-client-loader";
+import { gotoWorkspace } from "../support/helpers/launcher";
+import { openGlobalNewWorkspaceComposer } from "../support/helpers/new-workspace";
+import { seedWorkspace } from "../support/helpers/seed-client";
+import { waitForSidebarHydration } from "../support/helpers/workspace-ui";
+import { expectRememberedModel, expectSavedSelection } from "../support/helpers/model-memory";
+
+const PROVIDER = "remembered-model-recovery";
+const MODEL = "remembered-model";
+const LABEL = "Remembered model";
+
+async function rememberModel(page: Page) {
+  await page.addInitScript(
+    ({ provider, model }) => {
+      localStorage.setItem(
+        "@paseo:create-agent-preferences",
+        JSON.stringify({
+          provider,
+          providerPreferences: { [provider]: { model } },
+        }),
+      );
+    },
+    { provider: PROVIDER, model: MODEL },
+  );
+}
+
+async function expectRecoveredModelInPicker(page: Page) {
+  await openModelPicker(page);
+  await page.getByRole("dialog").getByRole("button", { name: "Back", exact: true }).click();
+  await drillIntoProvider(page, PROVIDER);
+  await expect(
+    page.getByTestId("combobox-desktop-container").getByText(LABEL, { exact: true }),
+  ).toBeVisible();
+  await closeModelPicker(page);
+}
+
+async function setProviderAvailability(client: DaemonClient, cwd: string, available: boolean) {
+  await client.patchDaemonConfig({
+    providers: {
+      [PROVIDER]: {
+        command: [available ? process.execPath : "/missing-paseo-diagnostic-provider"],
+      },
+    },
+  });
+  for (const scope of [undefined, cwd]) {
+    await expect
+      .poll(
+        async () => {
+          const snapshot = await client.getProvidersSnapshot(scope ? { cwd: scope } : undefined);
+          return snapshot.entries.find((entry) => entry.provider === PROVIDER)?.status;
+        },
+        { timeout: 30_000 },
+      )
+      .toBe(available ? "ready" : "unavailable");
+  }
+}
+
+test("restores the remembered model when a provider recovers after New workspace opens", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  const workspace = await seedWorkspace({ repoPrefix: "model-recovery-" });
+  const provider = await seedModelProvider({
+    id: PROVIDER,
+    label: "Remembered provider",
+    models: [{ id: MODEL, label: LABEL, description: "Model restoration diagnostic" }],
+    command: [process.execPath],
+  });
+  const client = await connectDaemonClient<DaemonClient>({ clientIdPrefix: "model-recovery" });
+  try {
+    await rememberModel(page);
+    await gotoWorkspace(page, workspace.workspaceId);
+    await waitForSidebarHydration(page);
+    await openGlobalNewWorkspaceComposer(page);
+    await expectRememberedModel(page, LABEL);
+
+    await gotoWorkspace(page, workspace.workspaceId);
+    await waitForSidebarHydration(page);
+    await setProviderAvailability(client, workspace.repoPath, false);
+    await openGlobalNewWorkspaceComposer(page);
+    await expect(
+      page.getByTestId("combined-model-selector").filter({ visible: true }),
+    ).not.toContainText("Loading...");
+
+    await setProviderAvailability(client, workspace.repoPath, true);
+    await expectSavedSelection(page, PROVIDER, MODEL);
+    await expectRecoveredModelInPicker(page);
+    await expectRememberedModel(page, LABEL);
+  } finally {
+    await client.close();
+    await provider.restore();
+    await workspace.cleanup();
+  }
+});
@@ -0,0 +1,22 @@
+import { test } from "../support/fixtures";
+import { verifyDelayedWorkspaceCreation } from "../support/helpers/new-workspace-navigation";
+
+test.describe("Delayed workspace creation", () => {
+  test.describe.configure({ timeout: 120_000 });
+
+  for (const launch of ["chat", "terminal", "empty"] as const) {
+    test(`${launch}: keeps the workspace chosen during creation`, async ({ page }) => {
+      await verifyDelayedWorkspaceCreation(page, launch, "leave");
+    });
+    test(`worktree ${launch}: keeps the workspace chosen during creation`, async ({ page }) => {
+      await verifyDelayedWorkspaceCreation(page, launch, "leave", "worktree");
+    });
+    test(`${launch}: opens the created workspace when the user stays`, async ({ page }) => {
+      await verifyDelayedWorkspaceCreation(page, launch, "stay");
+    });
+  }
+
+  test("preserves a newer draft opened while creation is pending", async ({ page }) => {
+    await verifyDelayedWorkspaceCreation(page, "chat", "new-draft");
+  });
+});
@@ -0,0 +1,13 @@
+import { test } from "../support/fixtures";
+import { withButtonAuthorExample } from "../support/helpers/plugin-button-example";
+
+test("the button author example shows each capability without a competing overflow button", async ({
+  page,
+}, info) => {
+  test.setTimeout(120_000);
+  await withButtonAuthorExample(page, info, async (buttons) => {
+    await buttons.refreshFromHeaderAndComposer();
+    await buttons.useMenusAndToggleButtons();
+    await buttons.inspectLiveWorkspaceDetails();
+  });
+});
@@ -0,0 +1,14 @@
+import { test } from "../support/fixtures";
+import { withButtonShowcase } from "../support/helpers/plugin-buttons";
+
+test("plugin header and composer buttons share actions, menus, content, and updates", async ({
+  page,
+}, testInfo) => {
+  test.setTimeout(180_000);
+  await withButtonShowcase(page, testInfo, async (buttons) => {
+    await buttons.openWideMenusAndPopovers();
+    await buttons.runAndUpdateActions();
+    await buttons.openCompactSheets();
+    await buttons.hideAndUnloadOpenButtons();
+  });
+});
@@ -1,3 +1,4 @@
+import { pluginRequirements } from "../support/helpers/plugin-fixture";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -11,8 +12,8 @@ import {

 const PLUGIN_ID = "plugin-host-ui-e2e";

-const PLUGIN_SOURCE = `import { usePaseo } from "@getpaseo/plugin";
-import { Icon, Modal, useToast } from "@getpaseo/plugin/react-native";
+const PLUGIN_SOURCE = `import { usePaseo } from "@getpaseo/plugin/client";
+import { Icon, Modal, useToast } from "@getpaseo/plugin/client/react-native";
 import { useQueryClient } from "@tanstack/react-query";
 import React, { useState } from "react";
 import { Pressable, Text, View } from "react-native";
@@ -118,8 +119,11 @@ test("plugin modal adapts its presentation and preserves host contexts", async (
  const directory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-host-ui-e2e-"));
  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
  const previousConfig = await client.getDaemonConfig();
-  await writeFile(path.join(directory, "paseo-plugin.json"), JSON.stringify({ id: PLUGIN_ID }));
-  await writeFile(path.join(directory, "index.tsx"), PLUGIN_SOURCE);
+  await writeFile(
+    path.join(directory, "paseo-plugin.json"),
+    JSON.stringify({ id: PLUGIN_ID, requirements: pluginRequirements }),
+  );
+  await writeFile(path.join(directory, "index.client.tsx"), PLUGIN_SOURCE);

  try {
    await client.patchDaemonConfig({ pluginsEnabled: true });
@@ -1,3 +1,4 @@
+import { pluginRequirements } from "../support/helpers/plugin-fixture";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -120,8 +121,11 @@ test("installs, reloads, recovers, disables, and removes a trusted local plugin"
  const directory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-e2e-"));
  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
  const previous = await client.getDaemonConfig();
-  await writeFile(path.join(directory, "paseo-plugin.json"), JSON.stringify({ id: "e2e-plugin" }));
-  await writeFile(path.join(directory, "index.tsx"), pluginSource("Plugin v1"));
+  await writeFile(
+    path.join(directory, "paseo-plugin.json"),
+    JSON.stringify({ id: "e2e-plugin", requirements: pluginRequirements }),
+  );
+  await writeFile(path.join(directory, "index.client.tsx"), pluginSource("Plugin v1"));

  try {
    const catalog = observePluginCatalog(page);
@@ -143,14 +147,14 @@ test("installs, reloads, recovers, disables, and removes a trusted local plugin"
    await reloadPlugin(page);
    await openContributionFromSettings(page, "Plugin v1", "Plugin v1 cleanup 1");

-    await writeFile(path.join(directory, "index.tsx"), pluginSource("Plugin v2"));
+    await writeFile(path.join(directory, "index.client.tsx"), pluginSource("Plugin v2"));
    await openPluginSettings(page);
    await reloadPlugin(page);
    await openContributionFromSettings(page, "Plugin v2", "Plugin v2 cleanup 2");
    await expect(page.getByRole("button", { name: "Plugin v1", exact: true })).not.toBeVisible();

    await writeFile(
-      path.join(directory, "index.tsx"),
+      path.join(directory, "index.client.tsx"),
      pluginSource("Broken surface", "render exploded"),
    );
    await openPluginSettings(page);
@@ -159,13 +163,13 @@ test("installs, reloads, recovers, disables, and removes a trusted local plugin"
    await openContribution(page, "Healthy surface", "Healthy contribution");
    await openContribution(page, "Broken surface", "Plugin failed: render exploded");

-    await writeFile(path.join(directory, "index.tsx"), pluginSource("Recovered surface"));
+    await writeFile(path.join(directory, "index.client.tsx"), pluginSource("Recovered surface"));
    await reloadActiveContribution(page, client, "Recovered surface cleanup 4");
    await expect(
      page.getByRole("button", { name: "Broken surface", exact: true }),
    ).not.toBeVisible();

-    await writeFile(path.join(directory, "index.tsx"), "export default broken syntax !!!");
+    await writeFile(path.join(directory, "index.client.tsx"), "export default broken syntax !!!");
    await openPluginSettings(page);
    await page.getByRole("button", { name: "Reload", exact: true }).click();
    await expect(page.getByTestId("plugin-management-feedback")).toContainText("Request failed");
@@ -173,7 +177,7 @@ test("installs, reloads, recovers, disables, and removes a trusted local plugin"
    await leavePluginSettings(page);
    await expectContributionRemoved(page, "Recovered surface");

-    await writeFile(path.join(directory, "index.tsx"), pluginSource("Plugin v3"));
+    await writeFile(path.join(directory, "index.client.tsx"), pluginSource("Plugin v3"));
    await openPluginSettings(page);
    await page.getByRole("button", { name: "Reload", exact: true }).click();
    await expect(page.getByLabel("e2e-plugin running")).toBeVisible();
@@ -0,0 +1,163 @@
+import { copyPluginExample } from "../support/helpers/plugin-fixture";
+import { expect, test as base, type Page } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import { connectNewWorkspaceDaemonClient } from "../support/helpers/new-workspace";
+import {
+  openMobileAgentSidebar,
+  expectMobileAgentSidebarVisible,
+} from "../support/helpers/sidebar";
+
+async function openExample(page: Page, example: string) {
+  await page.getByRole("button", { name: `Open ${example}`, exact: true }).click();
+  await expect(page.getByText(`Modal example: ${example}`, { exact: true })).toBeVisible();
+}
+
+async function closeExample(page: Page) {
+  await page.getByRole("button", { name: "Close", exact: true }).last().click();
+  await expect(page.getByRole("button", { name: "Open Form", exact: true })).toBeVisible();
+}
+
+async function copyAndPaste(page: Page) {
+  await page.getByRole("button", { name: "Copy text", exact: true }).click();
+  await expect(page.getByText("Text copied", { exact: true })).toBeVisible();
+  expect(await page.evaluate(() => navigator.clipboard.readText())).toBe("Copied from Paseo");
+  await page.getByRole("textbox", { name: "Paste here" }).focus();
+  await page.keyboard.press("ControlOrMeta+A");
+  await page.keyboard.press("ControlOrMeta+V");
+  await expect(page.getByRole("textbox", { name: "Paste here" })).toHaveValue("Copied from Paseo");
+}
+
+async function scrollToLastRow(page: Page) {
+  await page.getByRole("button", { name: "Row 1", exact: true }).hover();
+  await page.mouse.wheel(0, 7000);
+  await expect(page.getByRole("button", { name: "Row 100", exact: true })).toBeInViewport();
+  await page.getByRole("button", { name: "Row 100", exact: true }).click();
+}
+
+async function expectSingleInset(page: Page, left = "24px", bottom = "24px") {
+  const form = await page.getByTestId("modal-example-form").boundingBox();
+  const input = await page.getByRole("textbox", { name: "Paste here" }).boundingBox();
+  expect(form).not.toBeNull();
+  expect(input?.x).toBe(form?.x);
+  // The real content View owns the inset, not a third-party contentContainerStyle.
+  const padding = await page.getByTestId("modal-example-form").evaluate((node) => {
+    const content = node.parentElement!;
+    return {
+      left: getComputedStyle(content).paddingLeft,
+      bottom: getComputedStyle(content).paddingBottom,
+    };
+  });
+  expect(padding).toEqual({ left, bottom });
+}
+
+async function expectFullBleed(page: Page) {
+  const padding = await page
+    .getByRole("button", { name: "Row 1", exact: true })
+    .evaluate((node) => {
+      const content = node.parentElement!;
+      return {
+        left: getComputedStyle(content).paddingLeft,
+        bottom: getComputedStyle(content).paddingBottom,
+      };
+    });
+  expect(padding).toEqual({ left: "0px", bottom: "0px" });
+}
+
+async function exerciseBodies(page: Page) {
+  await openExample(page, "Form");
+  await expectSingleInset(page);
+  await copyAndPaste(page);
+  await closeExample(page);
+  await openExample(page, "Custom inset");
+  await expectSingleInset(page, "8px", "40px");
+  await closeExample(page);
+  await openExample(page, "Full bleed");
+  await expectFullBleed(page);
+  await scrollToLastRow(page);
+  await closeExample(page);
+  await openExample(page, "ScrollView");
+  await scrollToLastRow(page);
+  await closeExample(page);
+  await openExample(page, "FlatList");
+  await page.getByRole("button", { name: "Jump to last row", exact: true }).click();
+  await expect(page.getByRole("button", { name: "Row 100", exact: true })).toBeInViewport();
+  await closeExample(page);
+  await openExample(page, "Horizontal");
+  await page.getByRole("button", { name: "Overview", exact: true }).hover();
+  await page.mouse.wheel(900, 0);
+  await expect(page.getByRole("button", { name: "System logs", exact: true })).toBeInViewport();
+  await page.getByRole("button", { name: "System logs", exact: true }).click();
+  await closeExample(page);
+  await expect(page.getByText("Selected: System logs", { exact: true })).toBeVisible();
+}
+
+const test = base.extend<{ modalExample: Page }>({
+  modalExample: async ({ page, context }, provide) => {
+    const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+    const previous = await client.getDaemonConfig();
+    const example = await copyPluginExample("modal-ui");
+    try {
+      await client.patchDaemonConfig({ pluginsEnabled: true });
+      await client.installDirectoryPlugin(example.directory);
+      await context.grantPermissions(["clipboard-read", "clipboard-write"]);
+      await provide(page);
+    } finally {
+      await client.removePlugin("modal-ui-example").catch(() => undefined);
+      await client
+        .patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled ?? false })
+        .catch(() => undefined);
+      await client.close().catch(() => undefined);
+      await example.cleanup();
+    }
+  },
+});
+
+async function openWideExamples(page: Page) {
+  await page.setViewportSize({ width: 1100, height: 800 });
+  await gotoAppShell(page);
+  await page.getByRole("button", { name: "Modal examples", exact: true }).click();
+}
+
+async function openCompactExamples(page: Page) {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await openMobileAgentSidebar(page);
+  await expectMobileAgentSidebarVisible(page);
+  await page.getByRole("button", { name: "Modal examples", exact: true }).click();
+}
+
+async function expectDeniedCopyFeedback(page: Page) {
+  const cdp = await page.context().newCDPSession(page);
+  try {
+    const { targetInfo } = await cdp.send("Target.getTargetInfo");
+    await cdp.send("Browser.setPermission", {
+      browserContextId: targetInfo.browserContextId,
+      permission: { name: "clipboard-write" },
+      setting: "denied",
+      origin: new URL(page.url()).origin,
+    });
+    expect(
+      await page.evaluate(
+        async () =>
+          (await navigator.permissions.query({ name: "clipboard-write" as PermissionName })).state,
+      ),
+    ).toBe("denied");
+    await openExample(page, "Form");
+    await page.getByRole("button", { name: "Copy text", exact: true }).click();
+    await expect(
+      page.getByText("Could not copy text. Select the text and use Copy.", { exact: true }),
+    ).toBeVisible();
+    await closeExample(page);
+  } finally {
+    await cdp.detach();
+  }
+}
+
+test("plugin bodies support padding, scroll ownership, horizontal tabs and clipboard on wide and compact layouts", async ({
+  modalExample: page,
+}) => {
+  await openWideExamples(page);
+  await test.step("wide dialogs", () => exerciseBodies(page));
+  await openCompactExamples(page);
+  await test.step("compact sheets", () => exerciseBodies(page));
+  await test.step("denied clipboard writes report failure", () => expectDeniedCopyFeedback(page));
+});
@@ -0,0 +1,16 @@
+import {
+  test,
+  verifyProviderSettings,
+  verifyNewWorkspaceModelIcon,
+  verifyCompactModelIcon,
+  verifyExistingAgentModelIcon,
+} from "../support/helpers/plugin-provider-icons";
+
+test("plugin provider icons follow the model through settings and wide and compact composers", async ({
+  providerIcons,
+}) => {
+  await verifyProviderSettings(providerIcons);
+  await verifyNewWorkspaceModelIcon(providerIcons);
+  await verifyCompactModelIcon(providerIcons);
+  await verifyExistingAgentModelIcon(providerIcons);
+});
@@ -0,0 +1,18 @@
+import {
+  test,
+  openRequirementHost,
+  expectAppMismatch,
+  correctRequirementAndReload,
+  rejectDaemonMismatch,
+} from "../support/helpers/plugin-requirements";
+
+test("shows which runtime is incompatible and recovers after the requirement is corrected", async ({
+  page,
+  requirementHost,
+}) => {
+  await openRequirementHost(page, requirementHost);
+  await expectAppMismatch(page);
+  await correctRequirementAndReload(page, requirementHost.directory);
+  await rejectDaemonMismatch(page, requirementHost.directory);
+  await correctRequirementAndReload(page, requirementHost.directory);
+});
@@ -0,0 +1,62 @@
+import {
+  test,
+  openDisplaySettings,
+  openCompactDisplaySettings,
+  groupByWorkspace,
+  hideMetadata,
+  reloadSavedDisplaySettings,
+  editTitle,
+  replaceTitle,
+  saveTitle,
+  expectTitleRequired,
+  expectSavedTitle,
+  changeMetadataFromAnotherClient,
+  expectConflictPreservesDraft,
+  discardTitle,
+  returnAndReopenSettings,
+  expectSettingsUnavailable,
+} from "../support/helpers/plugin-settings";
+
+test("display preferences survive a reload", async ({ page }) => {
+  await openDisplaySettings(page);
+  await groupByWorkspace(page);
+  await hideMetadata(page);
+  await reloadSavedDisplaySettings(page);
+});
+
+test("invalid titles stay editable until a valid title is saved", async ({ page }) => {
+  await openDisplaySettings(page);
+  await editTitle(page, "");
+  await saveTitle(page);
+  await expectTitleRequired(page);
+  await replaceTitle(page, "My monitor");
+  await saveTitle(page);
+  await expectSavedTitle(page, "My monitor");
+});
+
+test("another client's save preserves a conflicting draft", async ({ page }) => {
+  await openDisplaySettings(page);
+  await editTitle(page, "Unsaved title");
+  await changeMetadataFromAnotherClient(page);
+  await saveTitle(page);
+  await expectConflictPreservesDraft(page, "Unsaved title");
+  await discardTitle(page);
+});
+
+test.describe("compact plugin settings", () => {
+  test.use({ viewport: { width: 390, height: 844 } });
+
+  test("Back and plugin re-enable restore the settings screen", async ({
+    page,
+    settingsPlugin,
+  }) => {
+    await openCompactDisplaySettings(page);
+    await groupByWorkspace(page);
+    await hideMetadata(page);
+    await returnAndReopenSettings(page);
+    await settingsPlugin.disablePlugin("settings-example");
+    await expectSettingsUnavailable(page);
+    await settingsPlugin.enablePlugin("settings-example");
+    await reloadSavedDisplaySettings(page);
+  });
+});
@@ -1,3 +1,4 @@
+import { pluginRequirements } from "../support/helpers/plugin-fixture";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -53,8 +54,11 @@ test("applies a contributed theme and falls back when its plugin is gone", async
  const directory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-theme-e2e-"));
  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
  const previousConfig = await client.getDaemonConfig();
-  await writeFile(path.join(directory, "paseo-plugin.json"), JSON.stringify({ id: PLUGIN_ID }));
-  await writeFile(path.join(directory, "index.ts"), PLUGIN_SOURCE);
+  await writeFile(
+    path.join(directory, "paseo-plugin.json"),
+    JSON.stringify({ id: PLUGIN_ID, requirements: pluginRequirements }),
+  );
+  await writeFile(path.join(directory, "index.client.ts"), PLUGIN_SOURCE);

  try {
    await client.patchDaemonConfig({ pluginsEnabled: true });
@@ -1,4 +1,5 @@
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { pluginRequirements } from "../support/helpers/plugin-fixture";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import type { TestInfo } from "@playwright/test";
@@ -12,10 +13,7 @@ import { buildAgentRoute } from "../support/helpers/mock-agent";
 import { connectNewWorkspaceDaemonClient } from "../support/helpers/new-workspace";
 import { seedWorkspace } from "../support/helpers/seed-client";
 import { getServerId } from "../support/helpers/server-id";
-import {
-  closeMobileAgentSidebar,
-  expectMobileAgentSidebarHidden,
-} from "../support/helpers/sidebar";
+import { expectMobileAgentSidebarHidden } from "../support/helpers/sidebar";
 import {
  switchWorkspaceViaSidebar,
  waitForWorkspaceInSidebar,
@@ -29,18 +27,12 @@ function isSettledWorkspaceUrl(url: URL): boolean {
  return url.pathname.includes("/workspace/") && !url.searchParams.has("open");
 }

-function pluginSource(input: { workspaceId: string; agentId: string }): string {
+function pluginClientSource(input: { workspaceId: string; agentId: string }): string {
  return `import React, { useRef } from "react";
 import { Pressable, Text, View } from "react-native";
-import { Icon, useAgent, useWorkspace } from "@getpaseo/plugin";
-import { defineRpc } from "@getpaseo/plugin/server";
-import { z } from "zod";
-
-const recordComposerOpen = defineRpc({
-  name: "composer.open",
-  input: z.object({ workspaceId: z.string() }),
-  output: z.object({ opened: z.boolean() }),
-});
+import { Icon } from "@getpaseo/plugin/client/react-native";
+import { useAgent, useWorkspace } from "@getpaseo/plugin/client";
+import { recordComposerOpen } from "./shared/rpc";

 function WorkspacePanel({ workspaceId, host, layout }) {
  const workspace = useWorkspace(workspaceId, (value) => ({ id: value.id }));
@@ -69,12 +61,6 @@ function SidebarCollisionSurface() {
  return <View><Text>Sidebar collision surface</Text></View>;
 }

-function ComposerPill({ theme, workspaceId, agentId }) {
-  const workspace = useWorkspace(workspaceId, (value) => ({ title: value.title }));
-  const agent = useAgent(agentId, (value) => ({ title: value.title }));
-  return <><Icon name="Scan" size={14} color={theme.colors.foregroundMuted} /><Text numberOfLines={1} style={{ color: theme.colors.foregroundMuted, flexShrink: 1 }}>Review {workspace?.title}:{agent?.title}</Text></>;
-}
-
 function contributeClient(client) {
  const pills = new Map();
  const remove = (agentId) => {
@@ -89,23 +75,25 @@ function contributeClient(client) {
    const agent = update.agent;
    if (agent.title !== "Plugin panel context agent" || !agent.workspaceId) return;
    remove(agent.id);
-    let removePill = () => {};
-    removePill = client.addComposerPill({
+    const pill = client.addComposerPill({
      id: "review",
-      title: "Open composer review",
      workspaceId: agent.workspaceId,
      agentId: agent.id,
-      Component: ComposerPill,
-      async onPress() {
+      button: {
+        title: "Open composer review",
+        icon: "Scan",
+        label: "Review",
+        behavior: { kind: "action", async onPress() {
        await client.rpc(recordComposerOpen, { workspaceId: agent.workspaceId });
-        removePill();
+        pill.remove();
        client.openPanel("agent", {
          workspaceId: agent.workspaceId,
          agentId: agent.id,
        });
+        } },
      },
    });
-    pills.set(agent.id, removePill);
+    pills.set(agent.id, () => pill.remove());
  });
  return () => {
    unsubscribe();
@@ -114,23 +102,49 @@ function contributeClient(client) {
  };
 }

-export default function contribute(plugin) {
-  plugin.handle(recordComposerOpen, async ({ workspaceId }, { paseo }) => {
+export default function contribute(client) {
+  client.addSurface("collision", DirectCollisionSurface);
+  client.addSurface("sidebar-destination", SidebarCollisionSurface);
+  client.addSidebarItem({ id: "collision", title: "Collision sidebar", icon: "Blocks", surface: "sidebar-destination" });
+  client.addWorkspacePanel({ id: "workspace", title: "Workspace inspector", icon: "PanelsTopLeft", context: "workspace", Component: WorkspacePanel });
+  client.addWorkspacePanel({ id: "agent", title: "Agent inspector", icon: "PanelTop", context: "agent", Component: AgentPanel });
+  client.addCommandCenterItem({ id: "global", title: "Plugin global action", icon: "Blocks", context: "global", onSelect() {} });
+  client.addCommandCenterItem({ id: "surface", title: "Open direct collision surface", icon: "Blocks", context: "workspace", onSelect({ openSurface }) { openSurface("collision"); } });
+  client.addCommandCenterItem({ id: "workspace", title: "Open plugin workspace", icon: "PanelsTopLeft", context: "workspace", onSelect({ openPanel }) { openPanel("workspace"); } });
+  client.addCommandCenterItem({ id: "agent", title: "Open plugin agent", icon: "PanelTop", context: "agent", onSelect({ openPanel }) { openPanel("agent"); } });
+  return contributeClient(client);
+}`;
+}
+
+const pluginSharedSource = `import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const recordComposerOpen = defineRpc({
+  name: "composer.open",
+  input: z.object({ workspaceId: z.string() }),
+  output: z.object({ opened: z.boolean() }),
+});`;
+
+const pluginServerSource = `import { recordComposerOpen } from "./shared/rpc";
+
+export default function contribute(server) {
+  server.handle(recordComposerOpen, async ({ workspaceId }, { paseo }) => {
    await paseo.workspaces.ref(workspaceId).setTitle("Opened from composer pill");
    return { opened: true };
  });
-  plugin.addSurface("collision", DirectCollisionSurface);
-  plugin.addSurface("sidebar-destination", SidebarCollisionSurface);
-  plugin.addSidebarItem({ id: "collision", title: "Collision sidebar", icon: "Blocks", surface: "sidebar-destination" });
-  plugin.addWorkspacePanel({ id: "workspace", title: "Workspace inspector", icon: "PanelsTopLeft", context: "workspace", Component: WorkspacePanel });
-  plugin.addWorkspacePanel({ id: "agent", title: "Agent inspector", icon: "PanelTop", context: "agent", Component: AgentPanel });
-  plugin.addCommandCenterItem({ id: "global", title: "Plugin global action", icon: "Blocks", context: "global", onSelect() {} });
-  plugin.addCommandCenterItem({ id: "surface", title: "Open direct collision surface", icon: "Blocks", context: "workspace", onSelect({ openSurface }) { openSurface("collision"); } });
-  plugin.addCommandCenterItem({ id: "workspace", title: "Open plugin workspace", icon: "PanelsTopLeft", context: "workspace", onSelect({ openPanel }) { openPanel("workspace"); } });
-  plugin.addCommandCenterItem({ id: "agent", title: "Open plugin agent", icon: "PanelTop", context: "agent", onSelect({ openPanel }) { openPanel("agent"); } });
-  plugin.addClientSide(contributeClient);
  return () => {};
 }`;
+
+async function writePluginSources(
+  directory: string,
+  input: { workspaceId: string; agentId: string },
+): Promise<void> {
+  await mkdir(path.join(directory, "shared"), { recursive: true });
+  await Promise.all([
+    writeFile(path.join(directory, "index.client.tsx"), pluginClientSource(input)),
+    writeFile(path.join(directory, "index.server.ts"), pluginServerSource),
+    writeFile(path.join(directory, "shared", "rpc.ts"), pluginSharedSource),
+  ]);
 }

 async function searchCommands(page: Page, query: string) {
@@ -159,7 +173,7 @@ async function runCommand(page: Page, title: string): Promise<void> {

 async function openCompactSidebar(page: Page): Promise<void> {
  await page.getByRole("button", { name: "Open menu", exact: true }).click();
-  await expect(page.getByTestId("sidebar-command-center-search")).toBeVisible();
+  await expect(page.getByTestId("sidebar-search")).toBeVisible();
 }

 async function capture(page: Page, testInfo: TestInfo, name: string): Promise<void> {
@@ -183,11 +197,14 @@ test.describe("plugin workspace panels and Command Center", () => {
      repoPrefix: "plugin-panel-secondary-",
      port: secondaryDaemon.port,
    });
-    await writeFile(path.join(directory, "paseo-plugin.json"), JSON.stringify({ id: PLUGIN_ID }));
    await writeFile(
-      path.join(directory, "index.tsx"),
-      pluginSource({ workspaceId: primary.workspaceId, agentId: "missing-agent" }),
+      path.join(directory, "paseo-plugin.json"),
+      JSON.stringify({ id: PLUGIN_ID, requirements: pluginRequirements }),
    );
+    await writePluginSources(directory, {
+      workspaceId: primary.workspaceId,
+      agentId: "missing-agent",
+    });

    try {
      await primaryClient.patchDaemonConfig({ pluginsEnabled: true });
@@ -263,10 +280,10 @@ test.describe("plugin workspace panels and Command Center", () => {
          modeId: "load-test",
        });
        const navigationAgentId = agent.id;
-        await writeFile(
-          path.join(directory, "index.tsx"),
-          pluginSource({ workspaceId: primary.workspaceId, agentId: navigationAgentId }),
-        );
+        await writePluginSources(directory, {
+          workspaceId: primary.workspaceId,
+          agentId: navigationAgentId,
+        });
        await primaryClient.reloadPlugin(PLUGIN_ID);

        await runCommand(page, "Open direct collision surface");
@@ -312,9 +329,7 @@ test.describe("plugin workspace panels and Command Center", () => {
          timeout: 30_000,
        });
        const composerPill = page.getByRole("button", { name: "Open composer review" });
-        await expect(composerPill).toContainText(
-          "Review Unrelated title update:Plugin panel context agent",
-        );
+        await expect(composerPill).toContainText("Review");
        await capture(page, testInfo, "plugin-composer-pill-wide");
        await page.setViewportSize(COMPACT_VIEWPORT);
        await expect(page.getByRole("button", { name: "Open composer review" })).toBeVisible();
@@ -331,8 +346,9 @@ test.describe("plugin workspace panels and Command Center", () => {
        await page.waitForURL(isSettledWorkspaceUrl, { timeout: 60_000 });
        await expect(page.getByRole("button", { name: "Open composer review" })).toHaveCount(0);
        await openCompactSidebar(page);
+        // The sidebar's Search row dismisses the compact sidebar on its way to the
+        // command center, so nothing has to close it after the command runs.
        await runCommand(page, "Open plugin agent");
-        await closeMobileAgentSidebar(page);
        await expectMobileAgentSidebarHidden(page);
        await expect(page.getByText(`Agent bridge ${agent.id}`)).toBeVisible();
        await expect(
@@ -9,6 +9,11 @@ import {
  type AgentHandle,
  type RewindFlowProvider,
 } from "../support/helpers/rewind-flow";
+import {
+  expectNestedProviderSubagentOwnership,
+  launchNestedProviderSubagentOwnershipScenario,
+  reopenNestedProviderSession,
+} from "../support/helpers/provider-subagents";
 import { openSubagentsTrack } from "../support/helpers/subagents";

 interface ProviderSubagentCase {
@@ -26,7 +31,7 @@ const cases: ProviderSubagentCase[] = [
    provider: "claude",
    sentinel: "CLAUDE_CHILD_SENTINEL",
    expectedName: "sentinel_child",
-    providerConfig: { model: "opus" },
+    providerConfig: { model: "claude-sonnet-5" },
    prompt:
      'Use Claude Code\'s native Task tool exactly once. Set its subagent_type input to "Explore" and its name input to "sentinel_child". Ask it to reply with exactly CLAUDE_CHILD_SENTINEL and do nothing else. Wait for it, then reply ROOT_DONE. Do not use Paseo tools.',
  },
@@ -147,3 +152,23 @@ test.describe("real provider subagent timelines", () => {
    });
  }
 });
+
+test.describe("real Claude nested subagent ownership", () => {
+  test.setTimeout(600_000);
+
+  test("keeps a grandchild and its background notification with their direct owners", async ({
+    page,
+  }, testInfo) => {
+    const cwd = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-claude-nested-ui-")));
+    let handle: AgentHandle | undefined;
+
+    try {
+      handle = await launchNestedProviderSubagentOwnershipScenario(page, cwd);
+      await expectNestedProviderSubagentOwnership(page, testInfo, "live");
+      await reopenNestedProviderSession(handle);
+      await expectNestedProviderSubagentOwnership(page, testInfo, "reopened");
+    } finally {
+      await cleanupRewindFlow({ handle, cwd });
+    }
+  });
+});
@@ -69,8 +69,8 @@ test.describe("Same-directory workspaces", () => {
      await expectExplorerEntryVisible(page, "SHARED_CHANGE.md");
      await openChangesPanel(page);
      await expect(
-        page.getByTestId("git-diff-scroll").getByText("SHARED_CHANGE.md", { exact: true }).first(),
-      ).toBeVisible({ timeout: 30_000 });
+        page.getByTestId("working-diff-panel").filter({ visible: true }).getByTestId("diff-file-0"),
+      ).toHaveAccessibleName("SHARED_CHANGE.md, +1, -0", { timeout: 30_000 });

      // Workspace B (same directory): the SAME directory-backed content is
      // visible even though the panel tabs belong to a different workspace.
@@ -79,8 +79,8 @@ test.describe("Same-directory workspaces", () => {
      await expectExplorerEntryVisible(page, "SHARED_CHANGE.md");
      await openChangesPanel(page);
      await expect(
-        page.getByTestId("git-diff-scroll").getByText("SHARED_CHANGE.md", { exact: true }).first(),
-      ).toBeVisible({ timeout: 30_000 });
+        page.getByTestId("working-diff-panel").filter({ visible: true }).getByTestId("diff-file-0"),
+      ).toHaveAccessibleName("SHARED_CHANGE.md, +1, -0", { timeout: 30_000 });
    } finally {
      await seeded.cleanup();
    }
@@ -1,6 +1,7 @@
 import { expect, test, type Page } from "../support/fixtures";
 import { gotoAppShell, openSettings } from "../support/helpers/app";
 import { openSettingsSection } from "../support/helpers/settings";
+import { openWhatsNew, release, serveChangelog } from "../support/helpers/changelog";

 const DISCORD_DESTINATION =
  /^https:\/\/(?:discord\.gg\/jz8T2uahpH|discord\.com\/invite\/jz8T2uahpH)(?:[/?#]|$)/;
@@ -41,7 +42,7 @@ async function expectExternalPage(
  await popup.close();
 }

-test("opens troubleshooting, support, and release destinations", async ({ page }) => {
+test("opens troubleshooting and support destinations", async ({ page }) => {
  await gotoAppShell(page);
  await expect(page.getByTestId("sidebar-help")).toBeVisible();

@@ -62,18 +63,60 @@ test("opens troubleshooting, support, and release destinations", async ({ page }
    await closeSheet(page, "keyboard-shortcuts-dialog");
  });

-  await test.step("opens support and release pages", async () => {
+  await test.step("opens support pages", async () => {
    await openHelpMenu(page);
    await expectExternalPage(page, "sidebar-help-discord", DISCORD_DESTINATION);

    await openHelpMenu(page);
    await expectExternalPage(page, "sidebar-help-github", GITHUB_ISSUE_DESTINATION);
-
-    await openHelpMenu(page);
-    await expectExternalPage(page, "sidebar-help-changelog", CHANGELOG_DESTINATION);
  });
 });

+test("renders the changelog in the app and links the website", async ({ page }) => {
+  // A callout, a section name the app has never seen, and a fenced sample whose
+  // contents look like a release heading.
+  await serveChangelog(page, [
+    "# Changelog",
+    "",
+    "## 9.1.0 - 2026-03-04",
+    "",
+    "Headline release note.",
+    "",
+    "> [!WARNING]",
+    "> Read this before upgrading.",
+    "",
+    "### Sparkles",
+    "",
+    "- Added a brand new thing",
+    "",
+    "```md",
+    "## 0.0.0 - 1999-01-01",
+    "```",
+    "",
+    "## 9.0.0 - 2026-02-01",
+    "",
+    "### Fixed",
+    "",
+    "- Fixed an older thing",
+    "",
+  ]);
+  await gotoAppShell(page);
+
+  const sheet = await openWhatsNew(page);
+  const latest = release(sheet, "9.1.0");
+
+  await expect(latest.getByText("March 4, 2026", { exact: true })).toBeVisible();
+  await expect(latest.getByText("Headline release note.")).toBeVisible();
+  await expect(latest.getByText("Read this before upgrading.")).toBeVisible();
+  await expect(latest.getByText("Sparkles", { exact: true })).toBeVisible();
+  await expect(latest.getByText("Added a brand new thing")).toBeVisible();
+  await expect(release(sheet, "9.0.0")).toBeVisible();
+  await expect(release(sheet, "0.0.0")).toHaveCount(0);
+
+  await expectExternalPage(page, "changelog-open-website", CHANGELOG_DESTINATION);
+  await closeSheet(page, "changelog-sheet");
+});
+
 test("searches keyboard shortcuts from the sidebar help menu", async ({ page }) => {
  await page.addInitScript(() => {
    Object.defineProperty(navigator, "platform", { get: () => "MacIntel" });
@@ -0,0 +1,108 @@
+import { expect, test } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import {
+  expectSidebarItemHidden,
+  expectSidebarNavSettingsOrder,
+  expectSidebarNavSettingsRow,
+  expectSidebarOrder,
+  expectStoredSidebarNav,
+  leaveSettings,
+  moveSidebarNavItemUp,
+  openSidebarNavSettings,
+  seedSidebarNavPreferences,
+  setSidebarNavItemVisible,
+} from "../support/helpers/sidebar-nav-settings";
+
+test.describe("Sidebar items in Appearance settings", () => {
+  test("owner reorders and hides top-level sidebar items", async ({ page }) => {
+    await gotoAppShell(page);
+
+    await test.step("the sidebar starts in the default order", async () => {
+      await expectSidebarOrder(page, ["new-workspace", "history", "search", "schedules"]);
+    });
+
+    await test.step("the Sidebar section lists every item in the same order", async () => {
+      await openSidebarNavSettings(page);
+      // The section explains itself through the header's info tooltip, not a paragraph.
+      await expect(page.getByTestId("sidebar-nav-section-info")).toHaveAccessibleName(
+        "About Sidebar",
+      );
+      await expectSidebarNavSettingsOrder(page, [
+        "new-workspace",
+        "history",
+        "search",
+        "schedules",
+      ]);
+      await expectSidebarNavSettingsRow(page, {
+        key: "history",
+        label: "History",
+        visible: true,
+      });
+      // Items with a keyboard shortcut badge it next to their name. Chords render
+      // with Ctrl off macOS, which is what the browser project runs on.
+      await expect(
+        page.getByTestId("sidebar-nav-item-new-workspace").getByText("Ctrl+N", { exact: true }),
+      ).toBeVisible();
+    });
+
+    await test.step("moving Schedules up twice lifts it above History", async () => {
+      await moveSidebarNavItemUp(page, "schedules");
+      await expectSidebarNavSettingsOrder(page, [
+        "new-workspace",
+        "history",
+        "schedules",
+        "search",
+      ]);
+      await moveSidebarNavItemUp(page, "schedules");
+      await expectSidebarNavSettingsOrder(page, [
+        "new-workspace",
+        "schedules",
+        "history",
+        "search",
+      ]);
+
+      await leaveSettings(page);
+      await expectSidebarOrder(page, ["new-workspace", "schedules", "history", "search"]);
+    });
+
+    await test.step("turning History off removes it from the sidebar", async () => {
+      await openSidebarNavSettings(page);
+      await setSidebarNavItemVisible(page, "history", false);
+      await expectStoredSidebarNav(page, [
+        { key: "new-workspace", visible: true },
+        { key: "schedules", visible: true },
+        { key: "history", visible: false },
+        { key: "search", visible: true },
+      ]);
+
+      await leaveSettings(page);
+      await expectSidebarItemHidden(page, "history");
+      await expectSidebarOrder(page, ["new-workspace", "schedules", "search"]);
+    });
+
+    await test.step("the sidebar keeps that shape across a reload", async () => {
+      await page.reload();
+      await expectSidebarItemHidden(page, "history");
+      await expectSidebarOrder(page, ["new-workspace", "schedules", "search"]);
+    });
+  });
+
+  test("renders no top-level items when every one is turned off", async ({ page }) => {
+    await seedSidebarNavPreferences(page, [
+      { key: "new-workspace", visible: false },
+      { key: "history", visible: false },
+      { key: "search", visible: false },
+      { key: "schedules", visible: false },
+    ]);
+    await gotoAppShell(page);
+
+    // The sidebar itself still renders; only its top-level nav items are gone.
+    await expect(page.locator('[data-testid="sidebar-settings"]:visible')).toBeVisible({
+      timeout: 30_000,
+    });
+    await expectSidebarItemHidden(page, "new-workspace");
+    await expectSidebarItemHidden(page, "history");
+    await expectSidebarItemHidden(page, "search");
+    await expectSidebarItemHidden(page, "schedules");
+  });
+});
@@ -0,0 +1,229 @@
+import type { Page } from "@playwright/test";
+import { test as base, expect } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import {
+  openAgentRoute,
+  seedMockAgentWorkspace,
+  type MockAgentWorkspace,
+} from "../support/helpers/mock-agent";
+import { getServerId } from "../support/helpers/server-id";
+import { closeMobileAgentSidebar, openMobileAgentSidebar } from "../support/helpers/sidebar";
+
+interface FinishedWorkspaces {
+  subject: MockAgentWorkspace;
+  other: MockAgentWorkspace;
+}
+
+const test = base.extend<{ workspaces: FinishedWorkspaces }>({
+  workspaces: async ({ browserName: _browserName }, provide) => {
+    const seeded: MockAgentWorkspace[] = [];
+    async function finishedWorkspace(title: string) {
+      const workspace = await seedMockAgentWorkspace({
+        repoPrefix: "workspace-mark-unread-",
+        title,
+        initialPrompt: "Finish this turn.",
+      });
+      seeded.push(workspace);
+      await workspace.client.waitForFinish(workspace.agentId, 20_000);
+      await workspace.client.clearWorkspaceAttention(workspace.workspaceId);
+      return workspace;
+    }
+    try {
+      await provide({
+        subject: await finishedWorkspace("Unread subject"),
+        other: await finishedWorkspace("Other workspace"),
+      });
+    } finally {
+      for (const workspace of seeded) await workspace.cleanup();
+    }
+  },
+});
+
+function workspaceRow(page: Page, workspaceId: string) {
+  return page.getByTestId(`sidebar-workspace-row-${getServerId()}:${workspaceId}`);
+}
+
+async function openWorkspace(page: Page, workspaceId: string) {
+  await workspaceRow(page, workspaceId).click();
+  await expect(page).toHaveURL(new RegExp(`/workspace/${workspaceId}`));
+}
+
+async function chooseReadAction(page: Page, workspaceId: string, action: "read" | "unread") {
+  await workspaceRow(page, workspaceId).hover();
+  await page.getByTestId(`sidebar-workspace-kebab-${getServerId()}:${workspaceId}`).click();
+  const item = page.getByRole("menuitem", { name: `Mark as ${action}`, exact: true });
+  await expect(item).toBeVisible();
+  await item.click();
+}
+
+async function markAsUnread(page: Page, workspaceId: string) {
+  await chooseReadAction(page, workspaceId, "unread");
+  await expectStatus(page, workspaceId, "attention");
+}
+
+async function markAsRead(page: Page, workspaceId: string) {
+  await chooseReadAction(page, workspaceId, "read");
+  await expectStatus(page, workspaceId, "done");
+}
+
+async function expectStatus(page: Page, workspaceId: string, status: "done" | "attention") {
+  await expect(
+    workspaceRow(page, workspaceId).getByTestId(`workspace-status-indicator-${status}`),
+  ).toBeVisible();
+}
+
+async function markBackgroundWorkspaceAndReopen(page: Page, workspaceId: string) {
+  await test.step("background workspace gains green dot and clears when clicked", async () => {
+    await markAsUnread(page, workspaceId);
+    await openWorkspace(page, workspaceId);
+    await expectStatus(page, workspaceId, "done");
+  });
+}
+
+async function leaveMarkedWorkspaceAndRead(page: Page, { subject, other }: FinishedWorkspaces) {
+  await test.step("leaving preserves manual unread until Mark as read", async () => {
+    await markAsUnread(page, subject.workspaceId);
+    await openWorkspace(page, other.workspaceId);
+    await markAsRead(page, subject.workspaceId);
+    await openWorkspace(page, subject.workspaceId);
+  });
+}
+
+async function leaveMarkedWorkspaceAndReopen(page: Page, { subject, other }: FinishedWorkspaces) {
+  await test.step("leaving preserves manual unread until reopening", async () => {
+    await markAsUnread(page, subject.workspaceId);
+    await openWorkspace(page, other.workspaceId);
+    await expectStatus(page, subject.workspaceId, "attention");
+    await openWorkspace(page, subject.workspaceId);
+    await expectStatus(page, subject.workspaceId, "done");
+  });
+}
+
+async function completeTurnAndLeave(page: Page, { subject, other }: FinishedWorkspaces) {
+  await test.step("ordinary completion still clears on departure", async () => {
+    await subject.client.sendAgentMessage(subject.agentId, "Finish another turn.");
+    await subject.client.waitForFinish(subject.agentId, 20_000);
+    await expectStatus(page, subject.workspaceId, "attention");
+    await openWorkspace(page, other.workspaceId);
+    await expectStatus(page, subject.workspaceId, "done");
+  });
+}
+
+async function openWorkspaceOnCompact(page: Page, workspaceId: string) {
+  await openWorkspace(page, workspaceId);
+  await openMobileAgentSidebar(page);
+}
+
+async function leaveMarkedWorkspaceAndReadOnCompact(
+  page: Page,
+  { subject, other }: FinishedWorkspaces,
+) {
+  await test.step("leaving preserves manual unread until Mark as read", async () => {
+    await markAsUnread(page, subject.workspaceId);
+    await openWorkspaceOnCompact(page, other.workspaceId);
+    await markAsRead(page, subject.workspaceId);
+    await openWorkspaceOnCompact(page, subject.workspaceId);
+  });
+}
+
+async function leaveMarkedWorkspaceAndReopenOnCompact(
+  page: Page,
+  { subject, other }: FinishedWorkspaces,
+) {
+  await test.step("leaving preserves manual unread until reopening", async () => {
+    await markAsUnread(page, subject.workspaceId);
+    await openWorkspaceOnCompact(page, other.workspaceId);
+    await expectStatus(page, subject.workspaceId, "attention");
+    await openWorkspaceOnCompact(page, subject.workspaceId);
+    await expectStatus(page, subject.workspaceId, "done");
+  });
+}
+
+async function completeTurnAndLeaveOnCompact(page: Page, { subject, other }: FinishedWorkspaces) {
+  await test.step("ordinary completion still clears on departure", async () => {
+    await closeMobileAgentSidebar(page);
+    await subject.client.sendAgentMessage(subject.agentId, "Finish another turn.");
+    await subject.client.waitForFinish(subject.agentId, 20_000);
+    await openMobileAgentSidebar(page);
+    await expectStatus(page, subject.workspaceId, "attention");
+    await openWorkspaceOnCompact(page, other.workspaceId);
+    await expectStatus(page, subject.workspaceId, "done");
+  });
+}
+
+async function markBackgroundWorkspaceAndRead(page: Page, workspaceId: string) {
+  await test.step("explicit Mark as read clears a background workspace", async () => {
+    await markAsUnread(page, workspaceId);
+    await markAsRead(page, workspaceId);
+  });
+}
+
+async function expectSelectedAgent(page: Page, agentId: string) {
+  await expect(page.getByTestId(`workspace-tab-agent_${agentId}`).first()).toHaveAttribute(
+    "aria-selected",
+    "true",
+  );
+}
+
+async function addFinishedAgent(workspace: MockAgentWorkspace) {
+  return workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.cwd,
+    workspaceId: workspace.workspaceId,
+    title: "Newest agent",
+    modeId: "load-test",
+    model: "e2e-fast-stream",
+  });
+}
+
+async function openCompactWorkspace(page: Page, workspace: MockAgentWorkspace) {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await openAgentRoute(page, workspace);
+  await openMobileAgentSidebar(page);
+}
+
+async function markUnreadThenResumeChat(page: Page, workspaceId: string) {
+  await test.step("interacting with the visible chat clears manual unread", async () => {
+    await markAsUnread(page, workspaceId);
+    await closeMobileAgentSidebar(page);
+    await page.getByRole("textbox", { name: "Message agent..." }).click();
+    await openMobileAgentSidebar(page);
+    await expectStatus(page, workspaceId, "done");
+  });
+}
+
+test("manual unread survives departure and clears on reopening without changing normal completions", async ({
+  page,
+  workspaces,
+}) => {
+  await gotoAppShell(page);
+  await openWorkspace(page, workspaces.other.workspaceId);
+  await markBackgroundWorkspaceAndReopen(page, workspaces.subject.workspaceId);
+  await leaveMarkedWorkspaceAndRead(page, workspaces);
+  await leaveMarkedWorkspaceAndReopen(page, workspaces);
+  await completeTurnAndLeave(page, workspaces);
+  await markBackgroundWorkspaceAndRead(page, workspaces.subject.workspaceId);
+});
+
+test("clicking a multi-agent workspace reveals and clears its marked agent", async ({
+  page,
+  workspaces,
+}) => {
+  await openAgentRoute(page, workspaces.subject);
+  await expectSelectedAgent(page, workspaces.subject.agentId);
+  await openWorkspace(page, workspaces.other.workspaceId);
+  const newest = await addFinishedAgent(workspaces.subject);
+  await markBackgroundWorkspaceAndReopen(page, workspaces.subject.workspaceId);
+  await expectSelectedAgent(page, newest.id);
+});
+
+test("manual unread survives leaving the current workspace on compact layout", async ({
+  page,
+  workspaces,
+}) => {
+  await openCompactWorkspace(page, workspaces.subject);
+  await leaveMarkedWorkspaceAndReadOnCompact(page, workspaces);
+  await leaveMarkedWorkspaceAndReopenOnCompact(page, workspaces);
+  await markUnreadThenResumeChat(page, workspaces.subject.workspaceId);
+  await completeTurnAndLeaveOnCompact(page, workspaces);
+});
@@ -14,6 +14,7 @@ import { getServerId } from "../support/helpers/server-id";
 import { projectEquivalenceViewKey } from "../support/helpers/project-view-key";
 import { escapeRegex } from "../support/helpers/regex";
 import { openFilesPanel } from "../support/helpers/workspace-tabs";
+import { seedMockAgentWorkspace } from "../support/helpers/mock-agent";

 const GITHUB_REMOTE_URL = "https://github.com/test-owner/test-repo.git";

@@ -48,6 +49,20 @@ async function waitForSidebarWorkspace(page: import("@playwright/test").Page, wo
  return row;
 }

+async function openWorkspaceReadAction(
+  page: import("@playwright/test").Page,
+  workspaceId: string,
+  action: "read" | "unread",
+) {
+  const workspaceKey = `${getServerId()}:${workspaceId}`;
+  const row = await waitForSidebarWorkspace(page, workspaceId);
+  await row.hover();
+  await page.getByTestId(`sidebar-workspace-kebab-${workspaceKey}`).click();
+  const item = page.getByTestId(`sidebar-workspace-menu-mark-as-${action}-${workspaceKey}`);
+  await expect(item).toBeVisible({ timeout: 30_000 });
+  return item;
+}
+
 async function openWorkspaceHoverCard(page: import("@playwright/test").Page, workspaceId: string) {
  const row = await waitForSidebarWorkspace(page, workspaceId);
  await row.hover();
@@ -187,6 +202,32 @@ test.describe("Sidebar workspace list", () => {
    }
  });

+  test("marks a finished workspace unread until it is opened again", async ({ page }) => {
+    const workspace = await seedMockAgentWorkspace({
+      repoPrefix: "sidebar-mark-unread-",
+      title: "Mark unread",
+      initialPrompt: "Finish this test turn.",
+    });
+
+    try {
+      await workspace.client.waitForFinish(workspace.agentId, 20_000);
+      await workspace.client.clearWorkspaceAttention(workspace.workspaceId);
+      expect(workspace.client.getLastServerInfoMessage()?.features?.workspaceMarkUnread).toBe(true);
+      await gotoAppShell(page);
+
+      const row = await waitForSidebarWorkspace(page, workspace.workspaceId);
+      await expect(row.getByTestId("workspace-status-indicator-done")).toBeVisible();
+      await (await openWorkspaceReadAction(page, workspace.workspaceId, "unread")).click();
+      await openWorkspaceReadAction(page, workspace.workspaceId, "read");
+
+      await page.keyboard.press("Escape");
+      await openWorkspaceFromSidebar(page, workspace.workspaceId);
+      await openWorkspaceReadAction(page, workspace.workspaceId, "unread");
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+
  test("Paseo-owned worktree hover card shows the worktree directory name", async ({ page }) => {
    await withPaseoOwnedWorktree(async ({ projectName, workspaceId, worktreeSlug }) => {
      await gotoAppShell(page);
@@ -0,0 +1,86 @@
+import { test, expect, type Page } from "../support/fixtures";
+import { clickNewTerminal, gotoWorkspace } from "../support/helpers/launcher";
+import { renameModalInput, renameModalSubmit } from "../support/helpers/rename";
+import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";
+import { selectWorkspaceInSidebar } from "../support/helpers/sidebar";
+
+function terminalTab(page: Page, terminalId: string) {
+  // Terminal tab chips have no tab role; their persistent identity survives title loading.
+  return page.getByTestId(`workspace-tab-terminal_${terminalId}`).filter({ visible: true }).first();
+}
+
+async function createNamedTerminal(page: Page, workspace: SeededWorkspace, title: string) {
+  await gotoWorkspace(page, workspace.workspaceId);
+  await clickNewTerminal(page);
+  const list = () =>
+    workspace.client.listTerminals(workspace.repoPath, undefined, {
+      workspaceId: workspace.workspaceId,
+    });
+  await expect.poll(async () => (await list()).terminals.length).toBe(1);
+  const terminalId = (await list()).terminals[0]!.id;
+  await terminalTab(page, terminalId).click({ button: "right" });
+  await page.getByRole("menuitem", { name: "Rename", exact: true }).click();
+  const modal = `workspace-tab-rename-modal-terminal-${terminalId}`;
+  await renameModalInput(page, modal).fill(title);
+  await renameModalSubmit(page, modal).click();
+  await expect(renameModalInput(page, modal)).toHaveCount(0);
+  await expect(terminalTab(page, terminalId)).toHaveText(title);
+  return terminalId;
+}
+
+async function recordRestoredTabText(page: Page, terminalId: string) {
+  // Install before the next document loads: a final-state assertion would miss the flash.
+  await page.addInitScript((id) => {
+    const samples: string[] = [];
+    Object.assign(window, { terminalTitleSamples: samples });
+    new MutationObserver(() => {
+      const tab = document.querySelector(`[data-testid="workspace-tab-terminal_${id}"]`);
+      if (!tab) return;
+      const text = (tab.textContent ?? "").trim();
+      if (samples.at(-1) !== text) samples.push(text);
+    }).observe(document, { subtree: true, childList: true, characterData: true });
+  }, terminalId);
+}
+
+async function expectRestoredTitle(page: Page, terminalId: string, title: string, stage: string) {
+  await expect(terminalTab(page, terminalId)).toHaveText(title, { timeout: 30_000 });
+  const samples = await page.evaluate(
+    () => (window as unknown as { terminalTitleSamples: string[] }).terminalTitleSamples,
+  );
+  await test.info().attach(`${stage}-tab-text`, {
+    body: JSON.stringify(samples),
+    contentType: "application/json",
+  });
+  expect(samples).toContain(title);
+  expect(samples).not.toContain("Terminal");
+}
+
+test("restored terminal titles do not flash a default name while loading", async ({ page }) => {
+  const workspace = await seedWorkspace({ repoPrefix: "terminal-title-loading-", git: false });
+  const other = await seedWorkspace({ repoPrefix: "terminal-title-other-", git: false });
+  try {
+    const title = "My named terminal";
+    const terminalId = await createNamedTerminal(page, workspace, title);
+    await recordRestoredTabText(page, terminalId);
+
+    await test.step("reload with a terminal tab restored", async () => {
+      await page.reload();
+      await expectRestoredTitle(page, terminalId, title, "reload");
+    });
+
+    await test.step("first workspace visit in a fresh page session", async () => {
+      await gotoWorkspace(page, other.workspaceId);
+      await selectWorkspaceInSidebar(page, workspace.workspaceId);
+      await expectRestoredTitle(page, terminalId, title, "first-visit");
+    });
+
+    await test.step("return to the workspace with its titles already loaded", async () => {
+      await selectWorkspaceInSidebar(page, other.workspaceId);
+      await selectWorkspaceInSidebar(page, workspace.workspaceId);
+      await expectRestoredTitle(page, terminalId, title, "return-visit");
+    });
+  } finally {
+    await workspace.cleanup();
+    await other.cleanup();
+  }
+});
@@ -13,7 +13,6 @@ import {
  expectTurnCopyButton,
 } from "../support/helpers/agent-stream";
 import {
-  expectReconnectingToastDebounced,
  expectReconnectingToastGone,
  expectReconnectingToastVisible,
 } from "../support/helpers/workspace-ui";
@@ -181,13 +180,17 @@ test.describe("Viewed agent timelines", () => {
        "true",
      );
      await gate.drop();
-      await expectReconnectingToastDebounced(page);
-      await expectReconnectingToastVisible(page);
+      await gate.waitForBlockedConnection();
      await commitMessage(scenario, scenario.firstAgentId, "Committed while the chat reconnects.");
      await expect(
        page.getByText("Committed while the chat reconnects.", { exact: true }),
      ).toHaveCount(0);
+      // Hold the first authoritative catch-up response so the assertion observes
+      // the reconnect boundary instead of racing a socket that has not reopened yet.
+      gate.holdNextServerMessage("fetch_agent_timeline_response");
      gate.restore();
+      await gate.waitForHeldServerMessage("fetch_agent_timeline_response");
+      gate.releaseHeldServerMessage("fetch_agent_timeline_response");
      await expectReconnectingToastGone(page);
      const recoveredMessage = page.getByText("Committed while the chat reconnects.", {
        exact: true,
@@ -209,6 +212,7 @@ test.describe("Viewed agent timelines", () => {
      await expect(page.getByRole("textbox", { name: "Message agent..." })).toBeVisible();
      await selectAgent(page, "First viewed chat");
      await gate.drop();
+      await gate.waitForBlockedConnection();
      await expectReconnectingToastVisible(page);

      await selectAgent(page, "Second viewed chat");
@@ -0,0 +1,77 @@
+import type { Locator } from "@playwright/test";
+import { expect, test, type Page } from "../support/fixtures";
+import { createIdleAgent } from "../support/helpers/archive-tab";
+import { seedWorkspace } from "../support/helpers/seed-client";
+import { getServerId } from "../support/helpers/server-id";
+import { waitForWorkspaceTabsVisible } from "../support/helpers/workspace-tabs";
+import { buildHostAgentDetailRoute } from "@/utils/host-routes";
+
+const TITLE_MAX_LENGTH = 80;
+
+function normalizedTitle(title: string): string {
+  return title.replace(/\s+/g, " ").trim();
+}
+
+function expectedTooltipTitle(title: string): string {
+  const singleLineTitle = normalizedTitle(title);
+  return singleLineTitle.length <= TITLE_MAX_LENGTH
+    ? singleLineTitle
+    : `${singleLineTitle.slice(0, TITLE_MAX_LENGTH - 1).trimEnd()}…`;
+}
+
+async function openAgent(page: Page, agent: { id: string; workspaceId: string }): Promise<void> {
+  await page.goto(buildHostAgentDetailRoute(getServerId(), agent.id, agent.workspaceId));
+  await page.waitForURL(
+    (url) => url.pathname.includes("/workspace/") && !url.searchParams.has("open"),
+    { timeout: 60_000 },
+  );
+  await waitForWorkspaceTabsVisible(page);
+}
+
+async function openAgentTabTooltip(page: Page, agentId: string, title: string): Promise<Locator> {
+  await page.getByRole("button", { name: normalizedTitle(title), exact: true }).hover();
+  const tooltip = page.getByTestId(`workspace-tab-tooltip-agent_${agentId}`);
+  await expect(tooltip).toBeVisible({ timeout: 10_000 });
+  return tooltip;
+}
+
+async function expectTwoRowAgentSummary(
+  tooltip: Locator,
+  input: { title: string; agentId: string },
+): Promise<void> {
+  const title = tooltip.getByText(expectedTooltipTitle(input.title), { exact: true });
+  const id = tooltip.getByText(input.agentId.slice(0, 7), { exact: true });
+  const activity = tooltip.getByText(/^(just now|\d+[mhd] ago|[A-Z][a-z]{2} \d{1,2})$/);
+
+  await expect(title).toBeVisible();
+  await expect(id).toBeVisible();
+  await expect(tooltip.getByText("·", { exact: true })).toBeVisible();
+  await expect(activity).toBeVisible();
+  expect((await title.boundingBox())?.y).toBeLessThan((await id.boundingBox())?.y ?? 0);
+}
+
+test.describe("Workspace agent tab tooltip", () => {
+  test("summarizes a multiline agent title above its ID and last activity", async ({ page }) => {
+    test.setTimeout(120_000);
+    const workspace = await seedWorkspace({ repoPrefix: "workspace-agent-tooltip-" });
+
+    try {
+      const title = [
+        "Short first line",
+        "followed by a much longer continuation that should be joined before the complete title is truncated to a useful tooltip length",
+      ].join("\n");
+      const agent = await createIdleAgent(workspace.client, {
+        cwd: workspace.repoPath,
+        workspaceId: workspace.workspaceId,
+        title,
+      });
+
+      await openAgent(page, agent);
+      const tooltip = await openAgentTabTooltip(page, agent.id, title);
+
+      await expectTwoRowAgentSummary(tooltip, { title, agentId: agent.id });
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+});
@@ -6,7 +6,7 @@ import {
 import { expect, test, type Page } from "../support/fixtures";
 import { gotoAppShell, openSettings } from "../support/helpers/app";
 import {
-  createIdleAgent,
+  createMockIdleAgent,
  expectWorkspaceTabHidden,
  expectWorkspaceTabVisible,
  openWorkspaceWithAgents,
@@ -159,7 +159,7 @@ test.describe("Workspace navigation regression", () => {
    const workspace = await seedWorkspace({ repoPrefix: "workspace-reconnect-" });

    try {
-      const agent = await createIdleAgent(workspace.client, {
+      const agent = await createMockIdleAgent(workspace.client, {
        cwd: workspace.repoPath,
        workspaceId: workspace.workspaceId,
        title: `workspace-reconnect-${Date.now()}`,
@@ -180,6 +180,7 @@ test.describe("Workspace navigation regression", () => {
      await expectWorkspaceTabVisible(page, agent.id);

      await daemonGate.drop();
+      await daemonGate.waitForBlockedConnection();
      await expectReconnectingToastVisible(page);
      await expectWorkspaceHeader(page, {
        title: workspace.workspaceName,
@@ -217,12 +218,12 @@ test.describe("Workspace navigation regression", () => {

    try {
      await Promise.all([
-        createIdleAgent(primaryWorkspace.client, {
+        createMockIdleAgent(primaryWorkspace.client, {
          cwd: primaryWorkspace.repoPath,
          workspaceId: primaryWorkspace.workspaceId,
          title: "Active host agent",
        }),
-        createIdleAgent(secondaryWorkspace.client, {
+        createMockIdleAgent(secondaryWorkspace.client, {
          cwd: secondaryWorkspace.repoPath,
          workspaceId: secondaryWorkspace.workspaceId,
          title: "Inactive host agent",
@@ -319,12 +320,12 @@ test.describe("Workspace navigation regression", () => {
    const secondWorkspace = await seedWorkspace({ repoPrefix: "workspace-nav-reg-b-" });

    try {
-      const firstAgent = await createIdleAgent(firstWorkspace.client, {
+      const firstAgent = await createMockIdleAgent(firstWorkspace.client, {
        cwd: firstWorkspace.repoPath,
        workspaceId: firstWorkspace.workspaceId,
        title: `workspace-nav-a-${Date.now()}`,
      });
-      const secondAgent = await createIdleAgent(secondWorkspace.client, {
+      const secondAgent = await createMockIdleAgent(secondWorkspace.client, {
        cwd: secondWorkspace.repoPath,
        workspaceId: secondWorkspace.workspaceId,
        title: `workspace-nav-b-${Date.now()}`,
@@ -22,7 +22,7 @@ import {
  expectSetupPanel,
  openHomeWithProject,
  navigateToWorkspaceViaSidebar,
-  returnHomeFromWorkspace,
+  leaveWorkspaceViaHistory,
  openWorkspaceScriptsMenu,
  startWorkspaceScriptFromMenu,
  closeWorkspaceScriptsMenu,
@@ -195,7 +195,7 @@ test.describe("Workspace setup streaming", () => {
      await expectFailedSetupTabSeededInMainPane(page, workspace.id);

      await closeSetupTab(page, workspace.id);
-      await returnHomeFromWorkspace(page);
+      await leaveWorkspaceViaHistory(page);
      await navigateToWorkspaceViaSidebar(page, workspace.id);
      await expectSetupTabNotSeeded(page, workspace.id);
    } finally {
@@ -4,7 +4,7 @@ import { expect, type Page } from "@playwright/test";
 import { metroTest as test } from "../support/fixtures";
 import { gotoAppShell } from "../support/helpers/app";
 import {
-  createIdleAgent,
+  createMockIdleAgent,
  expectSessionRowArchived,
  openSessions,
 } from "../support/helpers/archive-tab";
@@ -97,7 +97,7 @@ test.describe("Worktree restore after daemon restart", () => {
    createdProjectIds.add(worktree.projectKey);
    createdWorktreeDirectories.add(worktree.workspaceDirectory);

-    const agent = await createIdleAgent(client, {
+    const agent = await createMockIdleAgent(client, {
      cwd: worktree.workspaceDirectory,
      workspaceId: worktree.workspaceId,
      title: `restart-restore-${randomUUID().slice(0, 8)}`,
@@ -0,0 +1,47 @@
+# Native sheet gestures
+
+Use an Android emulator at 1080×1920, density 420, with the checkout's native app bundle loaded.
+Connect the app to an isolated daemon, enable plugins, and install `plugin-examples/modal-ui` there.
+Set `SHEET_QA_SERVER_ID` to that host's server ID, then run from the repository root:
+
+```sh
+agent-device test packages/app/e2e/mobile/modal-sheet/gestures.android.ad \
+  --env EXAMPLES_URL="paseo://h/${SHEET_QA_SERVER_ID}/plugin/modal-ui-example/surface/main" \
+  --record-video --artifacts-dir .dev/sheet-qa/plugin
+
+agent-device test packages/app/e2e/mobile/modal-sheet/model.android.ad \
+  --env FORM_URL="paseo://new?serverId=${SHEET_QA_SERVER_ID}" \
+  --record-video --artifacts-dir .dev/sheet-qa/model
+```
+
+The plugin journey checks body dismissal, reopening, expansion and last-row reachability with SDK
+ScrollView and FlatList, programmatic scrolling after expansion, downward list scrolling, and
+horizontal tab selection. The model journey checks body dismissal and the nested sheet's return to
+its parent without selecting a model or submitting a prompt. It does not assert catalog contents.
+
+These scripts live outside the default mobile suite because they require the installed example and
+an explicit connected host. See [mobile testing](../../../../../docs/mobile-testing.md) for device setup.
+
+## Recorded verification
+
+Android API 35, 1080×1920 at density 420, development binary 0.7.2 with this checkout's JavaScript.
+Plugin tests used an isolated daemon. Recordings show the same body drag
+[before](evidence/android-before.mp4) and [after](evidence/android-after.mp4) the fix.
+The [browser recording](evidence/browser.webm) covers the existing plugin modal journey at wide and
+compact sizes.
+
+```text
+Baseline dismissal regression:
+failed at step 6: wait timed out for selector: label="Open ScrollView"
+Current surface: Bottom sheet handle, Bottom Sheet, Close, Row 1.
+
+Fixed dismissal regression: 1 passed (6.47s)
+Full plugin gesture journey: 1 passed (44.3s)
+Model sheet dismissal/reopen journey: 1 passed (13.7s)
+Browser plugin-modal-body.spec.ts: 1 passed (33.4s)
+Root typecheck, lint and format: passed
+```
+
+The model form's catalog stayed on “Loading…” in the debug app even though the isolated daemon's
+provider API returned models. Its sheet dismissal/reopen was exercised; populated model selection
+was not. iOS and Electron were not exercised.
@@ -0,0 +1,52 @@
+# Install plugin-examples/modal-ui on the connected host and set EXAMPLES_URL to
+# paseo://h/<serverId>/plugin/modal-ui-example/surface/main.
+# Gesture coordinates target a 1080x1920 Android emulator at density 420.
+context platform=android timeout=120000 retries=0
+env APP_ID=sh.paseo.debug
+
+open "${APP_ID}" "${EXAMPLES_URL}"
+wait "label=\"Open ScrollView\"" 20000
+press "label=\"Open ScrollView\""
+wait "label=\"Row 1\"" 10000
+gesture pan 540 980 0 820 500
+wait "label=\"Open ScrollView\"" 3000
+
+# The caller-owned ScrollView expands with a body drag and reaches its final row.
+press "label=\"Open ScrollView\""
+wait "label=\"Row 1\"" 10000
+gesture pan 540 980 0 -600 500
+wait "label=\"Row 10\"" 3000
+scroll bottom
+wait "label=\"Row 100\"" 3000
+press "role=\"button\" label=\"Row 100\""
+press "label=\"Close\""
+wait "text=\"Selected: Row 100\"" 3000
+
+# FlatList has the same body dismissal, then supports refs after expansion.
+press "label=\"Open FlatList\""
+wait "label=\"Row 1\"" 10000
+gesture pan 540 1100 0 700 500
+wait "label=\"Open FlatList\"" 3000
+press "label=\"Open FlatList\""
+wait "label=\"Row 1\"" 10000
+gesture pan 540 1140 0 -750 500
+wait "label=\"Row 9\"" 3000
+press "label=\"Jump to last row\""
+wait "label=\"Row 100\"" 3000
+# Dragging down while scrolled moves the list, leaving the sheet open.
+gesture pan 540 650 0 900 500
+wait "label=\"Row 88\"" 3000
+is visible "label=\"Close\""
+press "label=\"Close\""
+wait "label=\"Open Horizontal\"" 3000
+
+# Horizontal tabs still receive gestures inside the host-owned vertical body.
+press "label=\"Open Horizontal\""
+wait "label=\"Overview\"" 10000
+gesture pan 960 980 -880 0 500
+wait stable 300 5000
+press "role=\"button\" label=\"System logs\""
+wait stable 300 5000
+press "label=\"Close\""
+wait "text=\"Selected: System logs\"" 3000
+close
@@ -0,0 +1,22 @@
+# FORM_URL is paseo://new?serverId=<connected-serverId>.
+# Gesture coordinates target a 1080x1920 Android emulator at density 420.
+context platform=android timeout=60000 retries=0
+env APP_ID=sh.paseo.debug
+
+open "${APP_ID}" "${FORM_URL}"
+wait "id=\"combined-model-selector\"" 20000
+press "id=\"combined-model-selector\""
+wait "id=\"agent-controls-model\"" 10000
+gesture pan 540 790 0 960 500
+wait "id=\"combined-model-selector\"" 3000
+
+# Reopen, dismiss the nested model browser, then dismiss its restored parent.
+press "id=\"combined-model-selector\""
+wait "id=\"agent-controls-model\"" 10000
+press "id=\"agent-controls-model\""
+wait stable 300 5000
+gesture pan 540 790 0 960 500
+wait "id=\"agent-controls-model\"" 3000
+gesture pan 540 790 0 960 500
+wait "id=\"combined-model-selector\"" 3000
+close
@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { setTimeout } from "node:timers/promises";
+
+// Open an idle terminal with an empty prompt and hide its keyboard before running.
+// The app must already run the checkout/build being verified against a real daemon.
+const appId = process.env.PASEO_TERMINAL_KEYBOARD_APP_ID ?? "sh.paseo.debug";
+const serial = process.env.ANDROID_SERIAL ?? "emulator-5554";
+const artifacts = resolve(".dev/agent-device-artifacts/terminal-keyboard-android");
+const session = "terminal-keyboard-android";
+const env = {
+  ...process.env,
+  AGENT_DEVICE_STATE_DIR: resolve(".dev/agent-device-terminal-keyboard"),
+};
+mkdirSync(artifacts, { recursive: true });
+
+function run(binary, args) {
+  return execFileSync(binary, args, { env, encoding: "utf8", timeout: 30_000 });
+}
+function ad(...args) {
+  return run("agent-device", [...args, "--session", session]);
+}
+function adb(...args) {
+  return run("adb", ["-s", serial, ...args]);
+}
+function keyboardState() {
+  const state = adb("shell", "dumpsys", "input_method");
+  const view = state.match(/^  mServedView=(.+)$/m)?.[1] ?? "";
+  return {
+    shown: /^  mInputShown=true$/m.test(state),
+    // The native object identity survives layout/flag changes but not a remount.
+    input: view.match(/ReactEditText\{(\w+)/)?.[1] ?? null,
+  };
+}
+async function waitForKeyboard(shown) {
+  let stable = 0;
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    const state = keyboardState();
+    stable = state.shown === shown ? stable + 1 : 0;
+    if (stable === 3) return state;
+    await setTimeout(100);
+  }
+  throw new Error(`Keyboard did not settle at shown=${shown}`);
+}
+function keyboardShift() {
+  const state = adb("shell", "dumpsys", "window");
+  const ime = state.match(/type=ime frame=\[0,(\d+)\].*visible=true/);
+  const navigation = state.match(/type=navigationBars frame=\[0,(\d+)\]/);
+  assert.ok(ime && navigation, "Expected a docked keyboard and navigation bar");
+  return Number(navigation[1]) - Number(ime[1]);
+}
+function imeEvents() {
+  return adb("logcat", "-d", "-v", "threadtime", "ImeTracker:I", "*:S")
+    .split("\n")
+    .filter((line) => line.includes(`${appId}:`));
+}
+function tap(rect, shift) {
+  ad(
+    "press",
+    String(Math.round(rect.x + rect.width / 2)),
+    String(Math.round(rect.y + rect.height / 2 - shift)),
+  );
+}
+
+let toggle;
+try {
+  ad("open", appId, "--platform", "android", "--serial", serial, "--no-test-ime");
+  assert.equal(keyboardState().shown, false, "Start with the terminal keyboard hidden");
+  // Accessibility snapshots can hang with a real IME open. Measure the controls
+  // while hidden, then project them by Android's actual docked-keyboard inset.
+  const snapshot = JSON.parse(ad("snapshot", "-i", "--json"));
+  const rectFor = (id) => {
+    const node = snapshot.data.nodes.find((candidate) => candidate.identifier === id);
+    assert.ok(node?.rect, `Open a terminal first: missing ${id}`);
+    return node.rect;
+  };
+  toggle = rectFor("terminal-keyboard-toggle");
+  const controls = ["ctrl", "ctrl", "esc", "enter"].map((key) => ({
+    key,
+    rect: rectFor(`terminal-key-${key}`),
+  }));
+  tap(toggle, 0);
+  const baseline = await waitForKeyboard(true);
+  assert.notEqual(baseline.input, null, "Expected the native terminal input to own the IME");
+  const shift = keyboardShift();
+  const before = new Set(imeEvents());
+  ad("screenshot", resolve(artifacts, "before.png"));
+
+  for (const { key, rect } of controls) {
+    tap(rect, shift);
+    const after = await waitForKeyboard(true);
+    const events = imeEvents().filter((line) => !before.has(line));
+    writeFileSync(resolve(artifacts, "ime-events.log"), events.join("\n"));
+    writeFileSync(
+      resolve(artifacts, "focus.json"),
+      JSON.stringify({ key, baseline, after }, null, 2),
+    );
+    assert.equal(after.input, baseline.input, `${key} replaced the focused native input`);
+    assert.deepEqual(
+      events.filter((line) => /onRequestHide|onRequestShow/.test(line)),
+      [],
+      `${key} cycled the software keyboard`,
+    );
+  }
+  ad("screenshot", resolve(artifacts, "after.png"));
+  console.log("PASS: Ctrl, Esc and Enter preserve the native input without IME hide/show requests");
+} finally {
+  if (toggle && keyboardState().shown) {
+    tap(toggle, keyboardShift());
+    await waitForKeyboard(false);
+  }
+  ad("close");
+  run("agent-device", ["daemon", "stop", "--clean"]);
+}
@@ -35,6 +35,8 @@ const metroTest = base.extend({
 const daemonTest = metroTest.extend<
  { projectOwnership: void },
  {
+    e2eDaemonConfig: Record<string, unknown> | undefined;
+    e2eDaemonEnvironment: Record<string, string>;
    e2eForkProviders: string[];
    e2eInjectPaseoTools: boolean;
    e2eWorker: void;
@@ -43,9 +45,17 @@ const daemonTest = metroTest.extend<
 >({
  e2eForkProviders: [[], { scope: "worker", option: true }],
  e2eInjectPaseoTools: [false, { scope: "worker", option: true }],
+  e2eDaemonConfig: [undefined, { scope: "worker", option: true }],
+  e2eDaemonEnvironment: [{}, { scope: "worker", option: true }],
  e2eWorker: [
-    async ({ e2eForkProviders, e2eInjectPaseoTools }, provide, workerInfo) => {
+    async (
+      { e2eDaemonConfig, e2eDaemonEnvironment, e2eForkProviders, e2eInjectPaseoTools },
+      provide,
+      workerInfo,
+    ) => {
      const worker = await startE2EWorker(workerInfo.workerIndex, {
+        daemonConfig: e2eDaemonConfig,
+        environment: e2eDaemonEnvironment,
        forkProviders: e2eForkProviders,
        injectPaseoTools: e2eInjectPaseoTools,
      });
@@ -1,4 +1,4 @@
-import { expect, type Page } from "@playwright/test";
+import { expect, type Locator, type Page } from "@playwright/test";

 const NEAR_BOTTOM_THRESHOLD_PX = 72;
 const DEFAULT_SCROLL_TOLERANCE_PX = 24;
@@ -14,6 +14,31 @@ function getVisibleChatScroll(page: Page) {
  return page.locator('[data-testid="agent-chat-scroll"]:visible').first();
 }

+interface PositionedToolCall {
+  locator: Locator;
+  bounds: { x: number; y: number; width: number; height: number };
+}
+
+async function readRenderedToolCalls(toolCalls: Locator): Promise<PositionedToolCall[]> {
+  const entries = await Promise.all(
+    Array.from({ length: await toolCalls.count() }, async (_, index) => ({
+      locator: toolCalls.nth(index),
+      bounds: await toolCalls.nth(index).boundingBox(),
+    })),
+  );
+  return entries.filter(
+    (entry): entry is PositionedToolCall => entry.bounds !== null && entry.bounds.width > 0,
+  );
+}
+
+function closestToolCallToY(toolCalls: PositionedToolCall[], targetY: number) {
+  return toolCalls.toSorted(
+    (left, right) =>
+      Math.abs(left.bounds.y + left.bounds.height / 2 - targetY) -
+      Math.abs(right.bounds.y + right.bounds.height / 2 - targetY),
+  )[0];
+}
+
 export async function readScrollMetrics(page: Page): Promise<ScrollMetrics> {
  return getVisibleChatScroll(page).evaluate((root: Element) => {
    const candidates = [root, ...Array.from(root.querySelectorAll("*"))]
@@ -180,58 +205,53 @@ export async function clickToolCallBesideScrollToBottomButton(page: Page): Promi
  const visibleButtonBounds = buttonBounds!;

  const toolCalls = page.locator('[data-testid="tool-call-badge"] [role="button"]');
-  const toolCallBounds = await Promise.all(
-    Array.from({ length: await toolCalls.count() }, async (_, index) => ({
-      index,
-      bounds: await toolCalls.nth(index).boundingBox(),
-    })),
-  );
  const buttonCenterY = visibleButtonBounds.y + visibleButtonBounds.height / 2;
-  const candidate = toolCallBounds
-    .filter(
-      (entry): entry is { index: number; bounds: NonNullable<typeof entry.bounds> } =>
-        entry.bounds !== null && entry.bounds.width > 0,
-    )
-    .sort(
-      (left, right) =>
-        Math.abs(left.bounds.y + left.bounds.height / 2 - buttonCenterY) -
-        Math.abs(right.bounds.y + right.bounds.height / 2 - buttonCenterY),
-    )[0];
+  const initialToolCalls = await readRenderedToolCalls(toolCalls);
+  const initialCandidate = closestToolCallToY(initialToolCalls, buttonCenterY);
  expect(
-    candidate,
+    initialCandidate,
    `Expected at least one rendered tool-call badge: ${JSON.stringify({
      buttonBounds,
      scrollMetrics: await readScrollMetrics(page),
-      toolCallBounds,
+      toolCallBounds: initialToolCalls.map(({ bounds }) => bounds),
    })}`,
  ).toBeDefined();
-  const visibleToolCall = candidate!;
-  const initialToolCallCenterY = visibleToolCall.bounds.y + visibleToolCall.bounds.height / 2;
-  await getVisibleChatScroll(page).evaluate((scroll, deltaY) => {
-    (scroll as HTMLElement).scrollTop += deltaY;
-  }, initialToolCallCenterY - buttonCenterY);
-
-  const alignedToolCall = toolCalls.nth(visibleToolCall.index);
  await expect
    .poll(async () => {
-      const [currentButtonBounds, currentToolCallBounds] = await Promise.all([
-        scrollToBottomButton.boundingBox(),
-        alignedToolCall.boundingBox(),
-      ]);
-      if (!currentButtonBounds || !currentToolCallBounds) {
-        return false;
-      }
-      const toolCallCenterY = currentToolCallBounds.y + currentToolCallBounds.height / 2;
-      return (
+      const currentButtonBounds = await scrollToBottomButton.boundingBox();
+      if (!currentButtonBounds) return false;
+      const currentButtonCenterY = currentButtonBounds.y + currentButtonBounds.height / 2;
+      const closest = closestToolCallToY(
+        await readRenderedToolCalls(toolCalls),
+        currentButtonCenterY,
+      );
+      if (!closest) return false;
+      const toolCallCenterY = closest.bounds.y + closest.bounds.height / 2;
+      if (
        toolCallCenterY >= currentButtonBounds.y &&
        toolCallCenterY <= currentButtonBounds.y + currentButtonBounds.height
-      );
+      ) {
+        return true;
+      }
+      const deltaY = Math.max(-200, Math.min(200, toolCallCenterY - currentButtonCenterY));
+      await getVisibleChatScroll(page).evaluate((scroll, delta) => {
+        (scroll as HTMLElement).scrollTop += delta;
+      }, deltaY);
+      return false;
    })
    .toBe(true);

+  const currentButtonBounds = await scrollToBottomButton.boundingBox();
+  expect(currentButtonBounds, "Expected scroll-to-bottom button to remain visible").not.toBeNull();
+  const currentButtonCenterY = currentButtonBounds!.y + currentButtonBounds!.height / 2;
+  const alignedToolCall = closestToolCallToY(
+    await readRenderedToolCalls(toolCalls),
+    currentButtonCenterY,
+  )?.locator;
+  expect(alignedToolCall, "Expected an aligned tool-call badge").toBeDefined();
  const [alignedButtonBounds, visibleToolCallBounds] = await Promise.all([
    scrollToBottomButton.boundingBox(),
-    alignedToolCall.boundingBox(),
+    alignedToolCall!.boundingBox(),
  ]);
  expect(alignedButtonBounds, "Expected scroll-to-bottom button to remain visible").not.toBeNull();
  expect(
@@ -245,7 +265,7 @@ export async function clickToolCallBesideScrollToBottomButton(page: Page): Promi
    x: finalToolCallBounds.x + 24,
    y: finalToolCallBounds.y + finalToolCallBounds.height / 2,
  };
-  const toolCallReceivesPointer = await alignedToolCall.evaluate((toolCall, point) => {
+  const toolCallReceivesPointer = await alignedToolCall!.evaluate((toolCall, point) => {
    const hit = document.elementFromPoint(point.x, point.y);
    return hit !== null && toolCall.contains(hit);
  }, clickPoint);
@@ -52,18 +52,18 @@ export interface IdleAgentSeedClient {
  ): Promise<{ status: string }>;
 }

-export async function createIdleAgent(
+async function seedIdleAgent(
  client: IdleAgentSeedClient,
  input: { cwd: string; workspaceId: string; title: string },
+  provider: {
+    provider: string;
+    model: string;
+    modeId: string;
+    featureValues?: Record<string, unknown>;
+  },
 ): Promise<ArchiveTabAgent> {
  const created = await client.createAgent({
-    provider: "opencode",
-    model: "opencode/gpt-5-nano",
-    // OpenCode has no "bypassPermissions" mode (that's Claude's). Use build with
-    // auto_accept for unattended full access — mode validation now rejects modes
-    // the provider doesn't define.
-    modeId: "build",
-    featureValues: { auto_accept: true },
+    ...provider,
    cwd: input.cwd,
    workspaceId: input.workspaceId,
    title: input.title,
@@ -84,6 +84,32 @@ export async function createIdleAgent(
  };
 }

+export async function createIdleAgent(
+  client: IdleAgentSeedClient,
+  input: { cwd: string; workspaceId: string; title: string },
+): Promise<ArchiveTabAgent> {
+  return seedIdleAgent(client, input, {
+    provider: "opencode",
+    model: "opencode/gpt-5-nano",
+    // OpenCode has no "bypassPermissions" mode (that's Claude's). Use build with
+    // auto_accept for unattended full access — mode validation now rejects modes
+    // the provider doesn't define.
+    modeId: "build",
+    featureValues: { auto_accept: true },
+  });
+}
+
+export async function createMockIdleAgent(
+  client: IdleAgentSeedClient,
+  input: { cwd: string; workspaceId: string; title: string },
+): Promise<ArchiveTabAgent> {
+  return seedIdleAgent(client, input, {
+    provider: "mock",
+    model: "e2e-fast-stream",
+    modeId: "load-test",
+  });
+}
+
 export async function archiveAgentFromDaemon(
  client: { archiveAgent(agentId: string): Promise<{ archivedAt: string }> },
  agentId: string,
--- a/Show More
+++ b/Show More